backnotprop/plannotator v0.27.16

on GitHub

Follow @plannotator on X for updates

What's New in v0.27.16

Diagrams are the theme of this release. Plans and documents with Mermaid or Graphviz fences now render in your color palette, on Mermaid 12, in a viewer you can zoom, pan, and comment on directly: a node, an edge, a sequence message, or the whole diagram. Twelve pull requests went in, three from the community, one from a first-time contributor. Code review learned to open a diff file without a repository, HTML annotation renders embedded sibling pages instead of a blank app, and a release-wide QA pass fixed a crash, a print regression, and a VS Code panel break before any of it shipped.

Themed diagrams

Mermaid diagrams used to render in one fixed dark-blue palette no matter which theme you chose. Now they follow the active palette and mode. Node fills come from your card color, text from your foreground, edges from your muted foreground, subgraphs from your muted surface, and the categorical fills that pie slices and git branches use are seeded from your palette's own accent colors. Every text-on-fill pair is checked against the 4.5:1 contrast rule and every line against 3:1, for all 78 palette and mode combinations that exist, so a diagram never becomes unreadable because a palette has a dark accent.

Mermaid itself moved from 11 to 12.0.0. The visible change is layout: 12 uses the ELK engine by default, which routes edges orthogonally and packs subgraphs more tightly. Flowcharts, state, class, ER, and requirement diagrams re-lay out; sequence, gitgraph, and pie are unchanged. The runtime is larger, so the plan editor loads it lazily on the first diagram, and a plan with no diagram never runs it. Mermaid 12 also introduced a heavier default node shadow; this release tones it down and derives its color from your palette, light on dark themes and dark on light ones, with a Diagram shadow control in Settings → Display if you prefer none, or the original strength.

(#1556, #1557, #1563)

Comment on any node, edge, or diagram

The diagram canvas is new. Every Mermaid and Graphviz fence renders inside a viewer with zoom, pan, fit, and keyboard controls, and a full-screen popout of the same viewer. Click a node, an edge, a subgraph, a sequence actor or message, a note, or a class relation, and the comment composer opens on that part. Click empty space and the comment attaches to the whole diagram. Each comment gets a numbered badge and a ring on its target, lists in the annotations panel beside your text comments, survives a reload and a theme change, and exports to the agent with its location: Diagram node Router (router), line 14.

Interaction was shaped by hands-on use. Nothing highlights on a plain mouse-over, because hover targeting fought the pan hand; a click selects and a drag pans, with a small threshold so a shaky click still lands. Hold Cmd (Ctrl elsewhere) to preview the target under the pointer. Edges were nearly impossible to hit at their 1 px stroke, so every edge carries an invisible 14 px hit area, and the edge label box no longer swallows the click at the midpoint. Sequence diagrams, whose parts Mermaid gives no ids, got their own anchor family. A pinned comment resolves by id, then label, then source line, and shows an Unanchored chip only when the diagram no longer contains it.

The viewer arrived from the commercial Workspaces app, where it was built first, and now ships in @plannotator/ui as the one diagram engine for both. (#1560, #1562)

Review a diff file, no repository required

plannotator review --patch-file change.diff opens the code review UI on a unified diff from anywhere: an email, a paste, a CI artifact, a remote agent's output. --patch-file - reads it from stdin. The server takes the patch as its snapshot and skips VCS detection entirely; staging, hunk expansion, base switching, and open-in-editor are hidden rather than left to fail, the header names the patch file, and a bad or empty patch says so. Reviews without the flag are byte-identical to before.

@soundvibe wrote the feature as a first contribution, with the server degrading cleanly on every repo-dependent endpoint. The browser-side gating and the open-in fix were added on top before merge. (#1554)

Embedded HTML documents render

An annotated HTML page that embeds a sibling page, through <iframe src="prototype.html">, <embed>, <object>, or a src assigned by script at runtime, used to show a second Plannotator inside every frame. The annotated page has no URL of its own, so relative references resolved onto the Plannotator server and hit the app's catch-all. Now the served page carries a base URL pointing at the session's asset route, which covers static attributes, script-assigned ones, and relative fetch calls alike; the asset route serves sibling HTML with its query string intact; and a framed request for a missing file gets a small 404 page naming it, never the app. Embedded documents stay sandboxed with no access to the session API. An armed pinpoint click on an embed pins the frame itself.

A release-QA check found that the framed 404 also fired for the app's own document when VS Code framed it, so the extension panel showed "Not found" on annotate sessions. Fixed before tagging: the 404 applies only to paths that name a file. (#1561, #1565)

References finds code in packages named vendor

Code navigation excluded any directory named vendor, target, build, dist, or coverage at any depth, so a Java package like com.example.vendor.app was silently dropped from References. Names that can only be tool output stay excluded everywhere; the ambiguous ones are excluded only at the repository root, where they are build output, since ripgrep already honors .gitignore for nested copies. A follow-up scoped the exemption per directory so a search from that package never re-admits the root vendor/ folder. @buptwlh reported it with a minimal ripgrep reproduction that made the diagnosis immediate. (#1559, closing #1558, #1564)

Printing from a dark theme

Printing or saving to PDF from a dark palette put near-black diagram labels on near-black nodes, because the print stylesheet forces text dark for paper and Mermaid 12 renders labels as HTML. Printing now renders the light half of your palette for the whole page, diagrams included, and restores your mode afterward. Light-theme users see no change. (#1564)

Additional Changes

• External annotation updates are validated. PATCH /api/external-annotations accepted any body; a diagramAnchor: null was stored and blanked the page. PATCH now runs the same field validators POST uses, on both runtimes, and the UI reads anchors defensively (#1564)
• Element context reaches embedding hosts. The validator for pinpoint element context moved into @plannotator/core so a host can import it instead of copying it; nothing changes for Plannotator users. @FNDEVVE, closing #1521 (#1549)
• Visual-explainer skill: a canonical diagram shell. Generated explainers now copy one zoomable diagram container with a clipping contract, so a zoomed diagram cannot paint over its caption. @FNDEVVE, addressing #1546 (#1551)
• @plannotator/ui package publishes. 0.40.0 on core 0.25.3 carries Mermaid 12 and the theming; 0.41.0 on core 0.25.4 the diagram engine and the diagramAnchor field; 0.41.1 loads the engine lazily so a host's document read no longer ships CodeMirror and the viewer for a page with no diagram; 0.41.2 the shadow default. The HANDOFF names every export, the SVG id contract 11 to 12, and the one DOM-order change (edge paths now in declaration order). Consumers must add their own root overrides for lodash-es 4.18.1, since Mermaid 12's parser pins a version with two open CVEs and a package override does not travel

Install / Update

macOS / Linux:

curl -fsSL https://plannotator.ai/install.sh | bash

Windows:

irm https://plannotator.ai/install.ps1 | iex

Claude Code Plugin: Run /plugin in Claude Code, find plannotator, and click "Update now".

Pi: Update @plannotator/pi-extension to 0.27.16 and restart Pi.

OpenCode: Clear cache and restart:

rm -rf ~/.bun/install/cache/@plannotator

What's Changed

• feat(ui): Mermaid diagrams follow the active color theme and mode by @backnotprop in #1556
• feat(core): carry elementContext through html-anchor host helpers by @FNDEVVE in #1549
• feat(ui): @plannotator/ui 0.40.0 with Mermaid 12.0.0 (ELK by default), loaded lazily by @backnotprop in #1557
• fix(annotate): render embedded local HTML documents instead of loading the app inside every embed by @backnotprop in #1561
• feat(ui): the Workspaces diagram viewer becomes the diagram engine (ui 0.41.0, core 0.25.4) by @backnotprop in #1560
• fix(code-nav): stop excluding source packages named vendor/target/build by @backnotprop in #1559
• fix(ui): load the diagram engine lazily, and keep the canvas controls out of the diagram; ui 0.41.1 by @backnotprop in #1562
• docs(skills): canonical zoomable diagram shell for visual-explainer by @FNDEVVE in #1551
• feat(review): add support for patch/diff files by @soundvibe in #1554
• fix: three release-QA findings: PATCH validation, dark-theme printing, and the root vendor/ exclusion by @backnotprop in #1564
• feat(ui): tone the Mermaid node shadow to 70 and derive its colour from the palette by @backnotprop in #1563
• fix(annotate): scope the framed 404 to paths that name a file, so a VS Code session renders the app by @backnotprop in #1565

New Contributors

• @soundvibe made their first contribution in #1554

Contributors

@soundvibe built patch-file review in #1554, a clean first contribution: the server refuses every repository-dependent endpoint with a clear error instead of crashing, nothing writes the patch to disk, and semantic diff works on the patch alone. The browser-side gating was layered on before merge, and the design underneath is his.

@FNDEVVE landed two more, bringing the count to twelve: the element context validator move in #1549, which lets the Workspaces app share the same code instead of copying it, and the diagram shell reference for the visual-explainer skill in #1551, which fixes a class of caption overlap he had reported himself in #1546.

The reports that shaped this release:

• @buptwlh reported the vendor package exclusion in #1558 with a two-command ripgrep reproduction; the fix and its follow-up both use his exact directory shape as the regression test

Thank you. Plannotator gets better because you tell us where it falls short.

Full Changelog: v0.27.15...v0.27.16