Canv Extension Author

Canv extension author

You are building an extension for Canv — a desktop writing app (Electron + React + TypeScript). Extensions extend Canv's UI via six contribution types: panel, fileHandler, command, menu, statusBar, language. An extension is a directory with manifest.json plus entry files; users install via Extensions tab → "Install from folder…".

When to activate

Activate for:

• Creating a new Canv extension from scratch
• Editing an existing extension in the user's workspace
• Debugging an installed Canv extension

Do not activate for unrelated Canv tasks (writing markdown, configuring profiles, switching themes, etc.).

Workflow

1. Pick contribution type(s). Read contributions/<type>.md for each type you'll use.
2. Read reference/conventions.md once. It covers manifest fields, capability declarations, visual rules, and the pre-emit checklist — applies to every extension.
3. Scaffold the directory. Default location: <workspace>/canv-extensions/<extension-id>/. Confirm with the user if not obvious.
4. Write manifest.json + entry files. Use reference/manifest-schema.md for field-level details.
5. Third-party libraries — if the extension needs an npm package:
   • Bundle with esbuild into vendor/<name>.js (self-contained ESM):

     npm install <pkg>
     npx esbuild --bundle --format=esm --platform=browser \
       --outfile=vendor/<name>.js node_modules/<pkg>/<entry>
     

   • Reference from HTML as <script type="module" src="./vendor/<name>.js"></script>.
   • Check recipes/ first — known-good setups for pdf.js, chart.js, etc. are already there.
6. Tell the user to install: Extensions tab → "Install from folder…" → pick the extension dir → trust when prompted → enable.

Hard constraints

Testing loop

After scaffolding:

1. Tell the user: open Canv → Extensions tab → Install from folder → pick the dir → trust workspace + extension → enable.
2. Manifest validation errors appear in the install consent modal. User reports; you regenerate.
3. Runtime errors appear in the extension DevTools (right-click inside the panel → Inspect Extension). User pastes; you iterate.
4. After any file change: uninstall + reinstall — Canv copies files at install time; changes are not picked up live.

Pre-emit checklist

Before reporting done:

• ID fields match their regex. manifest.id, panel.id, fileHandler.id, statusBar.id are kebab-case (/^[a-z][a-z0-9-]{0,63}$/ — lowercase, hyphens OK). command.id is dotted-lowercase with NO hyphens (/^[a-z][a-z0-9]*(?:\.[a-z][a-z0-9]*)*$/ — e.g. "format.selection", NOT "format-selection"). See reference/conventions.md.
• Every canv.* call has its capability declared in manifest.capabilities.
• Every contribution.entry path is a real file in the extension dir.
• No inline <script> or onclick attributes — all JS is in external .js files.
• CSS uses only --canv-* variables.
• No emoji in UI chrome (toolbar labels, headings, buttons).
• panel.location is "left-sidebar" or "bottom-dock".
• Third-party libraries are in vendor/<name>.js, bundled self-contained.

Reference index