Server Comments and Tags from the Reader's Parse

Status: draft (2026-11-03), issue #127. Full design in the repo at docs/superpowers/specs/2026-11-03-server-comments-from-the-reader-parse-design.md. It follows the one-editor-dialect work released in 2.5.7, which moved the editor onto its syntax tree.

The problem

A %%-delimited Obsidian comment is hidden from readers, and where it opens and closes depends on code and math (a %% inside either is literal). The editor now takes code and math from its CommonMark tree. The server still uses a hand-written text mask in wikantik-api. Wherever that mask misreads block structure, the author sees text dimmed as hidden that readers are shown. The remaining shapes involve a wikilink holding a backtick, backticks in HTML or autolinks, escaped backticks, pipes inside a code span in a table cell, a table on a list item's first line, and display math in a list item.

The tag index has the same weakness: it finds inline #tag text with a scan that uses the same mask, while the page draws tags from flexmark's own nodes.

The decision

The server already has a parser that reads block structure exactly as readers see it, because it is the reader. Ask it instead of approximating it.

How it is tested

Expected values come from the rendered page, never from the code under test, and each test is shown failing against the current mask first.

  1. Shared fixtures (comments.json, later inline-tags.json) run against the new server classes, with one new case per #127 shape.
  2. Render oracle: for every fixture and fuzz case, render the body. A sentinel inside each comment must be absent from the HTML exactly when the server calls it a comment, and the HTML's tag links must equal ReaderTags.
  3. Checked-in differential fixture: a seeded Java generator writes about 2,000 documents with the server's comment ranges. A Java staleness test regenerates it, and a vitest test asserts the editor's ranges equal the server's. The target is zero disagreements, and any exception must name the side that differs from the render.
  4. Access-rule locks: the existing tests stay green. A rule inside each misread shape locks the page, and an unreadable parse falls back to hiding and locks.
  5. Cost: parse-count seams prove a body without %% costs zero extra parses and one with it costs one. A ratio-based linear-time guard (not milliseconds) covers comment- and math-dense bodies.
  6. Corpus diff before deploy: the 2.5.7 prod check becomes a repeatable tool. It compares the old and new server over a page directory, toward or away from the render, in the gate over the repo corpus and once over a byte-exact prod copy before deploy.

Each phase is releasable alone. Phase B needs a reindex after deploy.