# Canvas Branch Manager

[English](#english) | [简体中文](#简体中文)

## English

Canvas Branch Manager adds explicit hierarchy, branch movement, focused editing, and descendant collapse tools to Obsidian Canvas. It works locally with standard `.canvas` files and does not use network services.

### Features

- Move a node together with all of its descendants while preserving their relative positions.
- Focus on a selected node, its upstream ancestors, and its direct siblings.
- Optionally show the selected node's complete upstream and downstream knowledge chain.
- Copy one selected node together with every downstream descendant and their connecting edges, even while the branch is collapsed.
- Treat a group reached by a downstream edge as a container node whose enclosed cards participate in collapse, movement, and copying.
- Keep stable logical group membership: new cards join visible groups, dragged cards join or leave on drop, and overlapping groups no longer compete by geometry on every refresh.
- Mark Canvas edges as explicit `parent → child` relations.
- Collapse and expand descendants by branch direction.
- Optionally sync hierarchy markers and collapsed branches through a Markdown state note.
- Follow Obsidian's interface language automatically, with English and Chinese included.

### Requirements

- Obsidian 1.8.7 or later.
- The built-in Canvas core plugin must be enabled.

### Installation

Once the plugin is available in the Community directory:

1. Open **Settings → Community plugins → Browse** in Obsidian.
2. Search for **Canvas Branch Manager**.
3. Select **Install**, then **Enable**.

For manual installation, download `main.js`, `manifest.json`, and `styles.css` from the latest GitHub release and place them in:

```text
<vault>/.obsidian/plugins/canvas-branch-manager/
```

Reload Obsidian and enable **Canvas Branch Manager** under Community plugins.

### Quick start

1. Open a Canvas and select an edge.
2. Use the hierarchy button in the native Canvas selection controls to mark the edge's start node as the parent and its end node as the child.
3. Use the directional buttons on parent nodes to collapse or expand their branches.
4. Enable **Move branches together** in plugin settings, then hold `Alt` while dragging a parent node.
5. Select one node and use the ribbon, Canvas toolbar, or command palette to enter Focus mode.
6. Enable **Copy complete descendant branch**, select one node, then use its ribbon or Canvas toolbar copy button. Pasted copies retain explicit hierarchy markers and start expanded.

Logical groups use one direct parent per node. For manual corrections, use the command palette actions **Add selected nodes to the selected group**, **Remove selected nodes from their logical groups**, and **Rescan members of the selected group**.

Downstream cycles are allowed for branch copying and collapse. An individual operation is blocked only when that branch contains a path back to the selected node itself.

Before a Canvas has explicit markers, ordinary edges are interpreted as `fromNode → toNode` for hierarchy preview and branch movement. Marking the first edge switches that Canvas to explicit hierarchy mode.

### Data and privacy

Canvas Branch Manager does not send data over the network and does not include telemetry. Interaction preferences and hierarchy state are stored locally in the plugin's `data.json`.

If **Sync Canvas state with Markdown** is enabled, the plugin maintains `Canvas Branch Manager State.md` in the vault root. This note contains hierarchy markers, collapsed-branch state, and logical group membership so those values can be synchronized by services that only sync Markdown files.

### Development

```sh
npm install
npm run lint
npm run test:graph
npm run build
```

## 简体中文

Canvas Branch Manager 为 Obsidian Canvas 增加显式层级、分支联动移动、聚焦编辑和后代折叠功能。插件完全在本地处理标准 `.canvas` 文件，不使用网络服务。

### 功能

- 移动一个节点时，让它的全部后代保持相对位置一起移动。
- 聚焦显示所选节点、它的全部上游祖先以及直接兄弟节点。
- 可选显示所选节点完整的上游与下游知识链。
- 只选中一个节点，即可复制它的全部下游后代及内部连线，分支折叠时也能完整复制。
- 当下游连线指向一个 group 时，将 group 视为容器节点，并让组内卡片一起参与折叠、移动和复制。
- 保存稳定的逻辑分组成员：在可见分组中新建的卡片会自动加入，节点拖入或拖出后会在松手时更新归属，重叠分组不会再反复争抢成员。
- 将 Canvas 边标记为显式的 `父节点 → 子节点` 关系。
- 按分支方向折叠和展开后代节点。
- 可选通过 Markdown 状态笔记同步层级标记和折叠状态。
- 自动跟随 Obsidian 的界面语言，内置中文和英文。

### 使用要求

- Obsidian 1.8.7 或更高版本。
- 必须启用 Obsidian 内置的 Canvas 核心插件。

### 安装

插件进入社区目录后：

1. 在 Obsidian 中打开 **设置 → 第三方插件 → 浏览**。
2. 搜索 **Canvas Branch Manager**。
3. 点击**安装**，然后点击**启用**。

手动安装时，请从最新的 GitHub Release 下载 `main.js`、`manifest.json` 和 `styles.css`，放入：

```text
<仓库>/.obsidian/plugins/canvas-branch-manager/
```

重新加载 Obsidian，然后在第三方插件中启用 **Canvas Branch Manager**。

### 快速开始

1. 打开一个 Canvas 并选中一条边。
2. 使用 Canvas 原生选择控件中的层级按钮，将边的起点标记为父节点、终点标记为子节点。
3. 使用父节点四周的方向按钮折叠或展开对应分支。
4. 在插件设置中启用**分支联动移动**，按住 `Alt` 拖动父节点。
5. 选中一个节点，通过左侧功能区、Canvas 工具栏或命令面板进入聚焦模式。
6. 启用**复制完整后代分支**，选中一个节点后使用左侧功能区或 Canvas 工具栏中的复制按钮。粘贴后的副本会保留显式层级标记并默认展开。

逻辑分组规定每个节点只有一个直接父分组。如需手动修正，可在命令面板使用**将所选节点加入所选分组**、**将所选节点移出逻辑分组**和**重新扫描所选分组的成员**。

分支复制和折叠允许下游内部存在循环；只有某个分支包含返回所选节点自身的路径时，才会阻止该方向的操作。

在 Canvas 尚无显式标记时，普通边会按照 `fromNode → toNode` 用于层级预览和分支联动。标记第一条边后，该 Canvas 会切换到显式层级模式。

### 数据与隐私

Canvas Branch Manager 不会通过网络发送数据，也不包含遥测。交互偏好和层级状态保存在插件本地的 `data.json` 中。

启用**使用 Markdown 同步 Canvas 状态**后，插件会在仓库根目录维护 `Canvas Branch Manager State.md`。该笔记包含层级标记、分支折叠状态和逻辑分组成员，方便通过仅同步 Markdown 文件的服务在设备之间共享这些状态。

### 开发

```sh
npm install
npm run lint
npm run test:graph
npm run build
```

## License / 许可证

MIT. See [LICENSE](LICENSE).

Third-party design references and license notes are documented in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

本项目采用 MIT 许可证，详见 [LICENSE](LICENSE)。第三方设计参考和许可证说明见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。