backnotprop/plannotator v0.27.17

on GitHub

Follow @plannotator on X for updates

What's New in v0.27.17

This is a stability release after the diagram-heavy v0.27.16. Twenty-four pull requests went in, ten of them written by community contributors, with two first-time authors and a third whose long-open branch finally landed. Two additions are worth naming up front: diagram files now open in the diagram viewer that fences already got, and approving a plan in OpenCode 2 switches the session model along with the agent. Everything else is repair work, most of it on code review.

Diagram files open in the diagram viewer

plannotator annotate flow.mmd used to refuse the file outright with File type not supported, and the same for .mermaid, .dot, and .gv. A Mermaid or Graphviz fence inside a plan, meanwhile, already got the whole diagram engine from v0.27.16: themed rendering, zoom, pan, fit, the full-size popout, and click-to-comment on a node, an edge, a cluster, or the diagram itself. People who keep their diagrams as files got none of it.

Those four extensions now open as one diagram in exactly that engine. The file is the document, the diagram fills the document card, and comments, drafts, export, version history, and share links behave the way they do for a fence. The extensions are not treated as markdown, so Mermaid's own --- … --- config block stays diagram content instead of being stripped as frontmatter, and they join the annotatable set everywhere else it matters: CLI target resolution, folder discovery, the file browser, the 2MB size cap, and /api/doc. Both runtimes decide the render kind through the same shared predicate, so a Bun session and a Pi session cannot disagree about what a .dot file is.

(#1571)

OpenCode switches the model with the agent

OpenCode stores the session's agent and its model independently. Approving a plan selected Build but left Plan's model active, so anyone who configures different models for the two agents kept planning-model settings through the build. Model metadata from V2 agent discovery is now preserved and applied: the agent switch runs first, then the model switch, which is the order OpenCode's own clients use.

A follow-up repaired older V2 hosts. The first change made switchModel support a prerequisite for switching agents at all, and hosts that expose switchAgent without it stopped changing the agent on approval. Agent selection now happens first and stands on its own; a missing or failing model switch warns rather than undoing it, while a failed agent switch still prevents the model attempt. @rcdailey wrote both.

(#1569, #1570)

An idle review stops touching the git remote

An open but idle code review session ran git ls-remote --symref origin HEAD about once a minute, for as long as the page stayed open. @freimer reported it from the worst place to hit it: SSH authentication backed by a hardware token, where every probe is a physical touch prompt, so a YubiKey kept blinking next to an agent that correctly reported itself as idle, with nothing in the UI showing an operation in flight.

The client polls /api/diff/fresh every five seconds to keep the "Diff out of date" banner honest, and that handler refreshed the remote base info, where a 60-second rate limit was the only thing between a five-second poll and a network round trip. The remote is now queried on the interactions where a reviewer is actually asking for a fresh answer: startup, the page load, a diff-type or base switch, and the explicit Fetch. A failed probe backs off by doubling up to fifteen minutes and resets on success. Separately, git commands spawned detached for timeout control were only ever reaped by a parent-side timer that dies with the parent, so a server stopped mid-probe orphaned the git and ssh pair; both runtimes now kill those process groups from an exit hook.

There is a full opt-out for anyone who would rather the review never reach the network on its own: plannotator review --no-git-remote-check, PLANNOTATOR_GIT_REMOTE_CHECK=0, or { "gitRemoteCheck": false } in ~/.plannotator/config.json, in that order of precedence. With it off, the session issues zero ls-remote calls including at startup, since the compare-target detection is itself an ls-remote. The flag is parsed by the shared review argument parser, so it works on Claude Code, OpenCode, and Pi rather than the Bun CLI alone.

One behavior change comes with this. A push that lands on the base branch in the middle of a review is no longer noticed within the minute on its own; it shows up on the next refresh, diff switch, or page reload. With the opt-out on, the compare target is resolved from local refs only, so a repository whose origin/HEAD is unset may pick a different default than the remote would have reported.

(#1585, closing #1553)

Long lines scroll, per file

A diff with long lines put its horizontal scrollbar at the bottom of the file's content, which is off-screen on any file taller than the panel. Each file's diff now carries its own horizontal scrollbar pinned to the file header, so a wide line is reachable without scrolling to the end of the file first.

The code is @Karrq's, written in #1224 and merged here from a replacement branch because the original could not take a maintainer push. Rebasing it onto current main meant resolving one conflict in the review editor's theme hook and dropping a lockfile revert; the change itself is unmodified.

(#1586, closing #1566 and #1048)

The review setup dialog is gone

The one-time "Set up your review view" chooser never appeared on a fresh profile. The settings store seeds every registry default into a cookie the first time settings are read, which happens before the first-run initializer runs, so the initializer always saw a persisted panel view and retired itself without showing anything. @FNDEVVE proposed fixing the gate in #1474, which is what surfaced the real path.

Rather than repair a dialog that asks a question the panel toggle already answers, the dialog is removed and Tree becomes the default panel view. The Tree | Git status | Commits toggle and Settings → Git remain the two ways to change it, with the toggle session-scoped and Settings persisting. Only fresh profiles are affected: a saved panel view still wins over the default, and anyone who has already chosen a view sees no change. The one-time dialog chain is now guide intro, look-and-feel, Edit Mode, token hover cards, terminal tools.

(#1587, closing #1463)

Selections at a block boundary

A double-click just past the end of a heading, paragraph, list item, fence, or blockquote leaves a selection whose entire content is the line break between two blocks. Depending on where the browser put the range's end, one of two things happened: the highlighter painted an invisible highlight and opened the toolbar on an empty quote, which stored an annotation with a newline as its text that counted toward the total, exported to the agent, and could never be re-anchored on the next load; or the range resolved past the last child node and an uncaught TypeError escaped the library's own listener.

Both are fixed. A run of 44 real mouse gestures in headless Chromium against a live annotate session produced three uncaught errors and 21 blank-quote toolbars before the change, and none of either after, with the 15 valid selections still opening the toolbar as they did.

@bohjak reported this in #881 with both failure modes separated, the stack trace, the offending line in the range model, and a proposed bounds check. The diagnosis was correct. The fix lands in Plannotator's own selection hook rather than in the highlighter library, so it does not wait on a new release of that dependency.

(#1584, closing #881)

Additional Changes

• The submission dialog's footer no longer covers a field. The GitHub and GitLab review submission dialog kept its sticky action footer inside the scrolling form body, so at constrained heights it overlaid the last control and clipped the "View on GitHub after submitting" checkbox. The footer is now a non-shrinking sibling of the scroll region. @leoreisdias (#1513)
• Nested frontmatter renders correctly. The frontmatter parser trimmed every line, so indented child keys hoisted to the document root and same-named keys overwrote each other, producing a card that looked complete and was wrong. Parsing is now indentation-aware: nested maps stay grouped, arrays of maps group per item, and flat scalars, string arrays, block scalars, and CRLF behave as before. @FNDEVVE, closing #1485 reported by @JaeyeongYang (#1548)
• Short links for small plans. Create short link is now offered for any shareable small plan, not only after a previous link was invalidated. Creation still requires the explicit click, and nothing uploads on its own. @FNDEVVE (#1475)
• The image annotator's Save button stays reachable. On narrow screens the annotation toolbar ran past the visible area and took Save with it. The toolbar is now bounded by the viewport including mobile safe areas, the controls through Clear scroll horizontally when they do not fit, and Save stays pinned at the right edge. @katya4oyu (#1469)
• Oh My Pi can submit a plan again. In planning mode the agent must submit by writing to the xd://plannotator_submit_plan device URI, but the planning write guard validated every write path as a file path and rejected it, so the planning contract required a call the guard blocked. That one URI is now allowlisted by exact match; other device URIs stay blocked and filesystem writes stay limited to in-cwd markdown. @FNDEVVE, closing #1466 reported by @alfkonee (#1547)
• Pi Web shows the review URL. Pi runs extensions in RPC mode where the user cannot reach the browser the host launches, but a successful launch suppressed the URL notification because the session did not read as remote. RPC contexts are now treated like remote sessions for that notification. @Shujakuinkuraudo, closing #1406 (#1407)
• The root build runs in dependency order. apps/hook copies the review bundle during its build, so bun run build on a clean checkout failed unless the review app had already been built. The root script now runs review, then hook, then opencode. @rNoz, closing #1388 (#1389)
• The documented compile command matches the release build. AGENTS.md dropped both flags the release workflow uses, so a binary built by following the docs reported itself as plannotator dev and, on macOS with Bun below 1.3.14, lost its linker signature and was killed on launch with no error. The command now carries both flags and names the Bun floor. @centraldogma99 (#1420)
• The folder empty state names diagram files. With .mmd and .dot files listed in the folder sidebar, the empty state still said "markdown or HTML". Found by release QA (#1588)
• The pierre-guard project skill is removed. Nothing in the repository loaded it (#1573)
• @plannotator/ui 0.42.0 through 0.45.2, on core 0.25.5. Seven pull requests add opt-in host seams to the published UI package: host-supplied selection actions and a comment mention source, mention ids on the annotation, a toolbar icon seam, mention picker presentation, mention chips in the composer, an annotation card header slot, and host labels on the embed picker. All of it is inert unless a host opts in, and nothing changes for Plannotator users. The 0.45.2 bump carries only the reviewPanelView registry default from the setup-dialog removal (#1572, #1574, #1575, #1576, #1577, #1578, #1579)

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.17 and restart Pi.

OpenCode: Clear cache and restart:

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

What's Changed

• fix(opencode): switch the OpenCode V2 session model along with the approved agent by @rcdailey in #1569
• feat(annotate): open .mmd and .dot files in the diagram viewer; core 0.25.5, ui 0.42.0 by @backnotprop in #1571
• feat(ui): host selection actions and comment mention source seams; ui 0.43.0 by @backnotprop in #1572
• feat(ui): mentionSource on Viewer and HtmlViewer, mention ids on the annotation; ui 0.43.1 by @backnotprop in #1574
• feat(ui): selectionActionsIcon on the toolbar seam, simpler default wand by @backnotprop in #1575
• feat(ui): mention picker heading and per-person avatar; ui 0.43.2 by @backnotprop in #1576
• feat(ui): mention tokens render as chips in the comment composer; ui 0.44.0 by @backnotprop in #1577
• feat(ui): annotation card header slot and @ mentions on the card's edit box; ui 0.45.0 by @backnotprop in #1578
• feat(ui): host labels on the embed picker; ui 0.45.1 by @backnotprop in #1579
• Preserve OpenCode agent switching on older hosts by @rcdailey in #1570
• fix(pi-extension): allow plan submission device through planning write guard by @FNDEVVE in #1547
• fix(ui): keep image annotation save action visible by @katya4oyu in #1469
• fix: build review before hook in root build by @rNoz in #1389
• chore: remove the pierre-guard project skill by @backnotprop in #1573
• fix(annotate): folder empty state names diagram files by @backnotprop in #1588
• fix(pi): notify review URL in RPC sessions by @Shujakuinkuraudo in #1407
• docs: complete the local compile command in AGENTS.md by @centraldogma99 in #1420
• fix(ui): whitespace-only and block-boundary selections no longer throw or create unanchorable annotations by @backnotprop in #1584
• fix(ui): parse nested frontmatter maps and arrays of maps by @FNDEVVE in #1548
• fix(share): allow explicit short links for small plans by @FNDEVVE in #1475
• Add horizontal scroll for diffs with long lines by @Karrq in #1586
• fix(review): stop contacting the git remote from the idle freshness poll; add PLANNOTATOR_GIT_REMOTE_CHECK opt-out and kill orphaned git transports on exit by @backnotprop in #1585
• fix(review): prevent submission footer overlap by @leoreisdias in #1513
• chore(review): remove the first-run review setup dialog; Tree is the default panel view by @backnotprop in #1587

New Contributors

• @Shujakuinkuraudo made their first contribution in #1407
• @centraldogma99 made their first contribution in #1420
• @Karrq's first contribution ships in #1586, the replacement branch carrying their work from #1224

Contributors

@rcdailey returned with the OpenCode model switch in #1569 and then caught what it broke on older V2 hosts before anyone else hit it, fixing it in #1570. The ordering he landed, agent first and model second when the host supports it, is what OpenCode's own clients do.

@Karrq wrote the per-file horizontal scrollbar in #1224 and waited a long time for it. The branch could not accept a maintainer push, so it was rebased and merged as #1586; the code is theirs and closes two separate reports.

@FNDEVVE landed three more: the indentation-aware frontmatter parser in #1548, the Oh My Pi plan submission guard in #1547, and short links for small plans in #1475. Their #1474 is also why the review setup dialog was looked at in the first place; the investigation there found the seeded-cookie gate, and the owner chose to drop the dialog rather than repair it.

@leoreisdias fixed the review submission dialog's footer overlap in #1513, with before and after screenshots and a regression test asserting the footer sits outside the scroll region.

@katya4oyu kept the image annotator's Save button reachable on narrow screens in #1469, verified on a physical phone, following their compact-viewport toolbar fix from the previous cycle.

@rNoz fixed the root build order in #1389, validated on a clean Linux checkout, and filed the issue behind it.

@Shujakuinkuraudo made Pi Web RPC sessions show the review URL in #1407, a first contribution that came with the issue, the one-line diagnosis, and a regression test that does not need a real browser.

@centraldogma99 corrected the documented compile command in #1420, also a first contribution. They traced both failure modes to the release workflow, including the macOS signing regression that kills a binary built with an older Bun without printing anything.

The reports that shaped this release:

• @freimer reported the idle ls-remote loop in #1553, with the hardware-token symptom that made the cost of a once-a-minute network probe obvious
• @bohjak reported the block-boundary selection bug in #881, separating the crash from the garbage annotation and naming the exact line in the range model; the fix follows their diagnosis
• @tekumara reported the unreachable horizontal scrollbar in #1566, and @TheOutdoorProgrammer had reported the same thing in #1048
• @JaeyeongYang reported the frontmatter card showing wrong values for nested YAML in #1485
• @alfkonee reported that Oh My Pi planning mode blocked plan submission in #1466

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

Full Changelog: v0.27.16...v0.27.17