# Canvas to Tasks

Canvas to Tasks is an Obsidian companion plugin that mirrors Markdown tasks in
Canvas text nodes to generated Markdown index files. The Tasks plugin can then
query and edit those tasks, while this plugin synchronizes changes back to the
source Canvas.

## Requirements

- Obsidian 1.6.6 or later.
- The community [Tasks plugin](https://github.com/obsidian-tasks-group/obsidian-tasks-plugin)
  must be installed and enabled to query the generated tasks and apply its
  status, recurrence, completion-date, and on-completion rules.

Canvas to Tasks still generates indexes when Tasks is unavailable, but the
Tasks-specific behavior is disabled until Tasks is enabled and Obsidian is
reloaded.

## How it works

- Canvas text nodes remain the user-facing source.
- A generated Markdown file is created for each Canvas under
  `_Canvas Tasks Index/` by default.
- Moving or renaming a Canvas moves its generated index to the matching path.
  Moving, renaming, or deleting a folder that contains Canvas files triggers a
  debounced structure reconciliation and removes empty generated directories.
- Tasks queries discover the generated Markdown tasks normally.
- Canvas task discovery follows the Tasks plugin's global filter and excludes
  checkbox statuses configured as `NON_TASK`. Like Tasks itself, a non-empty
  global filter matches anywhere in the task description.
- Changes made to generated task lines are written back to the exact Canvas
  text node and line.
- Checkbox changes made directly in Canvas are passed through the Tasks API,
  preserving status rules, completion dates, recurrence, and on-completion
  actions.
- Each generated task has an **Open Canvas card** link directly below it.
  Clicking the link opens the source Canvas, selects the exact text card, and
  zooms to it. The node mapping is stored in the link target, so generated task
  text no longer contains a visible bridge comment. Do not remove or edit the
  generated link if reverse synchronization is needed.
- Indexes created by earlier releases with inline `c2t:node` comments remain
  readable and are migrated automatically on the next synchronization.
- Canvas is the authoritative source. Version 2 indexes carry a complete-file
  marker and a fingerprint of each source task. An index edit is written back
  only when its mapping and original Canvas line still match exactly; otherwise
  the edit is rejected and the index is restored from the latest Canvas.

The generated index folder is managed by this plugin. Avoid manually adding
unrelated notes to it. A non-generated file is never overwritten.

## Installation

### From Obsidian Community plugins

After the plugin is accepted into the community directory:

1. Open **Settings → Community plugins** in Obsidian.
2. Select **Browse** and search for **Canvas to Tasks**.
3. Install and enable both **Canvas to Tasks** and **Tasks**.
4. Reload Obsidian after updating either plugin.

### Manual installation

1. Download `main.js`, `manifest.json`, and `styles.css` from the latest GitHub
   release.
2. Create `<Vault>/.obsidian/plugins/canvas-to-tasks/`.
3. Put the three downloaded files directly in that folder.
4. Reload Obsidian, then enable the plugin under **Settings → Community
   plugins**.

## Commands

- **Canvas to Tasks: Synchronize all Canvas tasks**
- **Canvas to Tasks: Open task index for current Canvas**

The setting **Use Tasks logic for Canvas checkboxes** controls whether Canvas
checkbox transitions are normalized through the Tasks API. It is enabled by
default. If the task description changes at the same time as its checkbox, the
plugin preserves the user's text and skips API normalization rather than
overwriting a concurrent edit.

## Mobile support

The runtime bundle uses Obsidian's Vault API and is marked as mobile-compatible.
Sync `manifest.json`, `main.js`, and `styles.css` to the mobile vault, enable
both Tasks and Canvas to Tasks on that device, and restart Obsidian after plugin
updates. Card links use an Obsidian protocol handler supplied by this plugin and
work on both desktop and mobile; they do not require Advanced Canvas.

## Privacy and network access

Canvas to Tasks works entirely inside the local Obsidian vault. It does not make
network requests, collect analytics or telemetry, show advertisements, or send
vault data to external services. It reads Canvas files and manages only the
generated Markdown indexes required for synchronization.

## Current safety behavior

- Writes are serialized and debounced to prevent feedback loops.
- Reverse synchronization stays disabled until the initial Canvas-to-index
  rebuild completes.
- A source line is updated only if it is still a Markdown task.
- Missing mappings, incomplete indexes, concurrent Canvas edits, and multiple
  deletions in one index event are treated as unsafe and never written back.
- Invalid Canvas JSON and missing nodes stop the write and show an error notice.
- Deleting a generated task line deletes its mapped Canvas task line when
  reverse sync is enabled.
- Deleting or renaming a Canvas trashes its generated index and creates the new
  index when applicable.
- Generated indexes mirror the current Canvas folder structure. Structural
  events are handled on demand; the plugin does not poll or continuously scan
  the vault.

## Uninstalling

1. Disable Canvas to Tasks in Obsidian.
2. Delete the generated index folder (`_Canvas Tasks Index/` by default) if you
   no longer need it. The Canvas source files remain unchanged.
3. Uninstall the plugin from **Settings → Community plugins**.

## Development

```powershell
npm.cmd install
npm.cmd run dev
```

After the build creates `main.js`, enable **Canvas to Tasks** in Obsidian's
community plugin settings. Source changes rebuild automatically; reload the
plugin in Obsidian to execute the new bundle.

## Verification

```powershell
npm.cmd run typecheck
npm.cmd test
npm.cmd run build
npm.cmd run validate-release
```

## Releasing

Keep the version in `package.json`, `manifest.json`, and `versions.json` in
sync. After committing and pushing the release changes, push a version tag that
exactly matches the manifest version and does not include a `v` prefix:

```powershell
git tag 0.2.7
git push origin 0.2.7
```

The release workflow validates the version, runs the checks above, builds a
minified `main.js`, and creates a GitHub release containing only `main.js`,
`manifest.json`, and `styles.css`.

## License

[MIT](LICENSE)