Mermaid-Preview-Nova/CLAUDE.md

CLAUDE.md

Context for working on this repository.

What this is

A Nova extension that previews Markdown as rendered HTML, with Mermaid diagrams drawn inline. Nova previews Markdown already; the thing it cannot do is run JavaScript in that preview, which is what diagrams need.

The extension is not a previewer and cannot be one. It writes an ordinary HTML file inside the workspace and opens it, and Nova's own HTML preview — a WebView that does run JavaScript — renders it. Every awkward part of the design follows from that one fact.

Hard constraints (do not re-derive these)

These were established by reading Nova 14.1's bundle and probing its running preview server. They are facts about Nova, not preferences.

Constraint	Consequence
No preview/previewer extension point. Manifest keys are activationEvents, clips, commands, completions, entitlements, main, sidebars, syntaxes; categories are clips, commands, completions, issues, languages, sidebars, tasks, themes	Cannot supply the contents of a preview tab. Generate a file and open it
No webview / HTML UI for extensions; sidebars are TreeView only	Rendering can only happen inside Nova's own preview WebView
AssistantsRegistry covers completions, issues, symbols, colors, tasks only	No hook to intercept how a file is displayed
Nova's preview server only serves files under the preview root	Generated pages must live inside the workspace. A page outside it fails as a blank tab, not an error
The preview server does serve dot-directories (.git/HEAD returns 200)	.nova/MermaidPreview/ is a valid home for generated files
The preview server renders .md to HTML on the fly, with Nova's own stylesheet	A relative link from a generated page to another .md file shows Nova's rendering, not raw text
Nova's built-in Markdown preview is NovaPreviewMarkdownRenderer over discount, styled by MarkdownAuto/Bright/Dark.css with a custom-stylesheet preference	A stylesheet cannot run Mermaid. That preference is not a route to this feature
No API to reach into a preview WebView	No scroll sync, ever. Do not promise it
No API to close a tab, or to ask whether a tab is showing preview	Cleanup infers a close from onDidDestroy plus a re-check
nova.workspace.openFile options are line and column only	Cannot open a file directly into its preview state

The runtime is JavaScriptCore, not Node: no npm require, only relative require("./x.js") between Scripts/ files. setTimeout/clearTimeout and fetch exist. Vendored libraries are not required by the extension — they are copied into the workspace and loaded by the page.

Type definitions worth having open: npm pack @types/nova-editor-node (a single index.d.ts, more precise than the website).

How a preview happens

1. mermaidpreview.preview resolves the frontmost editor to a source (describeSource), refusing untitled and remote files — they have no path to resolve images and links against.
2. installAssets copies Assets/ into <output>/assets/ if missing or stale, stamped with ASSET_VERSION. Bump ASSET_VERSION in Scripts/preview.js whenever anything in Assets/ changes, or installed copies go stale.
3. buildDocument writes a ~2 KB shell: the Markdown embedded as JSON, plus script tags. No rendering happens in the extension.
4. Assets/preview.js renders in the WebView — markdown-it, then DOM fix-ups, then Mermaid one diagram at a time so a bad diagram fails alone.
5. Saving rewrites step 3 only. Nova reloads the preview because the file changed. Three megabytes are not rewritten per keystroke — keep it that way.
6. Closing either tab discards the page; the last one out removes assets/ and the directory.

Layout

extension.json          manifest: commands, config, entitlements
Scripts/                runs in Nova (JavaScriptCore)
  main.js               Controller: lifecycle, commands, watchers, cleanup
  preview.js            output paths, asset install, generate/discard
  render.js             builds the HTML shell — no Nova APIs, so node can test it
  util.js               conf, mkdirp, writeFile, copyFile, removeTree, shortHash
Assets/                 copied into the workspace, runs in the WebView
  preview.js            markdown-it wiring, DOM fix-ups, Mermaid
  preview.css           three themes, resolved in CSS so the page never flashes
  vendor/               markdown-it 14.3.0, mermaid 11.17.0 (both UMD, MIT)
Tests/                  node harness + headless-browser render test
install.sh              copy into Nova's extension directory, register, restart

Two files are called preview.js. Scripts/preview.js decides where files go; Assets/preview.js renders the page. They never see each other.

Conventions

• 4-space indent, CommonJS, no build step, no runtime dependencies.
• Comments explain why, especially where something encodes an API limitation. Several exist to stop a future reader "simplifying" a constraint back into a bug — the cleanup grace period is the sharpest example.
• User-visible strings are sentence case and plain English.
• Config keys are namespaced mermaidpreview.* and read through util.conf(), which prefers the workspace value.
• Vendored libraries are committed, never fetched at runtime. The extension makes no network requests and holds no network entitlement.

Testing

Tests/run.sh runs everything: syntax, manifest, and three suites.

• generate.test.js — Scripts/*.js against a stubbed nova global backed by the real filesystem (Tests/nova-stub.js). Covers generation, asset reuse, and discard/pruning.
• close.test.js — drives the whole Controller through the stub, including command invocation and fake editors that can be destroyed. Covers all four close paths.
• render.test.js — builds a page through the real render.js and dumps the DOM from headless Chromium, asserting on diagrams, rebased paths, task lists, headings and both themes. Skips itself if no browser is found; set MERMAID_PREVIEW_CHROME to point at one.

The stub is the highest-value tool here and it already caught real bugs (./ doubling in rebased links, checkbox state not surviving serialization). Extend it rather than testing by hand.

In Nova itself:

nova extension validate .    # manifest + bundle (makes network calls)
nova extension activate .    # load into Nova for development

Logs appear in Nova's Extension Console.

State

• Never published. min_runtime is 10; developed against Nova 14.1.
• Unverified assumption, worth settling first. Cleanup on tab-close assumes a tab showing Preview still appears in nova.workspace.textEditors. If it does not, flipping a page into Preview will delete it ~2.5 s later (CLEANUP_GRACE_MS in Scripts/main.js). Symptom: the preview stops updating and goes blank after a save. Fix is small — gate the page-tab cleanup on the source file being closed too, leaving only the source-close and quit paths. Recovery for the user is pressing ⌃⇧M again.
• No icon. Images/extension/ is empty; extension.png at the root is what Nova picks up (see the sibling claude-nova extension).
• No commits yet.

Things deliberately not done

• Syntax highlighting in code blocks — another bundle to vendor, and the page is already 3.5 MB. Add highlight.js to Assets/vendor/ and a highlight option in the markdown-it constructor if it becomes worth it.
• Scroll sync — impossible, see the constraints table.
• Replacing Nova's built-in .md preview — also impossible. This is a second tab, and the README says so plainly.
• Inlining assets into a single self-contained page — would make every save a 3.5 MB write.