vscode: markdown preview marker-aware features — inline REVIEW rendering + right-edge marker minimap

[amrmelsayed]

Problem

Today the markdown preview hides <!-- REVIEW(@<author>): <text> --> markers entirely (HTML comments don't render). Two consequences:

1. Reading the preview gives no signal that comments exist. Architect opens preview to review a spec; sees clean rendered prose; has no idea five REVIEW markers are sitting in the source. They have to switch to the editor to even know feedback exists, defeating the "preview is the reading surface" pattern that vscode: add review comments from the markdown preview pane (hover-+ per block, no editor mode-switch) #859, vscode: markdown preview navigation chrome — floating TOC + quick-jump overlay + per-heading mini-toolbar for long Codev artifacts #861, etc. are building toward.
2. No spatial overview of where comments are. Even if the architect knows comments exist, finding their locations means scrolling through the source editor's gutter or opening vscode: review summary webview — bird's-eye list of all REVIEW markers in spec/plan files with click-to-jump #860's review summary panel. No at-a-glance map.

This issue adds two complementary surfaces in the preview, both deriving from the same data (REVIEW markers in the source), both pure rendering (no interaction beyond click-to-jump).

Proposal — two marker-aware features, one bundle

Bundled because they share the same source of truth (REVIEW markers in the doc), the same parsing infrastructure (regex from plan-review.ts:31), and the same eligibility gating.

1. Inline REVIEW marker rendering

Render <!-- REVIEW(@<author>): <text> --> as styled inline call-out boxes in the preview, not as hidden HTML comments.

Visual:

... existing rendered paragraph ...

  ┌─ 💬 @architect ───────────────────────────────────┐
  │  tighten this paragraph                            │
  └────────────────────────────────────────────────────┘

... next rendered paragraph ...

• Implementation: a markdownItPlugin that transforms REVIEW markers at AST-conversion time. The plugin recognizes the marker syntax during tokenization and emits a custom <div class="codev-review-marker"> with author + body fields
• Visual: subtle border, colored accent on the left edge (VS Code theme variable), small icon (💬 or $(comment)), author label, comment body
• Click: clicking the call-out jumps to the marker's line in the source editor (uses the data-line attribute the plugin emits)
• Future-compat: when reply / resolve state lands (per the Phase 3 design call), the call-out grows to show thread state (unresolved border color, reply count, etc.)

2. REVIEW marker minimap (right-edge column)

A vertical column at the right edge of the preview showing colored dots at the scroll-positions of each REVIEW marker.

Visual:

              ┃     ← preview content
              ┃
              ┃     • marker at L47
              ┃
              ┃     • marker at L52
              ┃
              ┃     • marker at L58
              ┃
              ┃
              ┃     • marker at L91
              ┃
              ┃

• Implementation: previewScripts scans the rendered DOM for the inline call-out boxes from feature The Gestalt Problem - Features Developed in Isolation Without System Awareness #1; computes their vertical position in the preview viewport; renders a colored dot at the corresponding position in a position: fixed right-edge column
• Click dot: smooth-scrolls preview to that marker
• Hover dot: shows a tooltip with author + first ~80 chars of body
• Composes with vscode: markdown preview navigation chrome — floating TOC + quick-jump overlay + per-heading mini-toolbar for long Codev artifacts #861's floating TOC: TOC is the navigation chrome at the right edge; marker minimap is a narrower strip inside or beside it. Layout decision at implementation: nest the dots inside the TOC's gutter, or render as a parallel strip. Either is fine — pick whichever doesn't fight vscode: markdown preview navigation chrome — floating TOC + quick-jump overlay + per-heading mini-toolbar for long Codev artifacts #861's TOC visually

Path eligibility

Same as #859, #860, #861, and the document-state surfaces filing: only .md files in codev/(plans|specs|reviews)/. Other markdown files render REVIEW markers (if any) as standard hidden HTML comments, unchanged.

Implementation sketch

Files

• New: packages/vscode/src/markdown-preview/marker-render-plugin.ts — markdown-it plugin that recognizes REVIEW markers during tokenization and emits the call-out HTML
• New: packages/vscode/src/markdown-preview/marker-minimap.js — previewScripts entry; DOM scanning, dot rendering, click handlers
• New: packages/vscode/src/markdown-preview/marker-render.css — previewStyles for both the inline call-outs and the minimap dots

Marker-rendering plugin details

The plugin operates at the inline-token level. When it sees an HTML comment token matching REVIEW_COMMENT_PATTERN, it replaces the token with a custom block-level html_block token whose content is the styled call-out markup. Source-line attribution preserved via data-line (so the minimap can find the position).

Minimap details

• Computes positions via getBoundingClientRect() on each rendered call-out box
• Updates positions on resize (debounced) and on preview rebuild
• No virtualization needed — typical doc has <20 markers
• Click handler reuses the same postMessage({type: 'jumpToLine', line: N}) protocol from vscode: review summary webview — bird's-eye list of all REVIEW markers in spec/plan files with click-to-jump #860

Composition with the editor side

The editor-side Comments API surface (plan-review.ts) keeps rendering REVIEW markers as comment threads in the gutter. This issue is preview-only:

• Editor: gutter + and comment threads (unchanged)
• Preview: inline call-outs (new) + right-edge minimap (new)

Authors flow consistently through both: a marker added via #859's preview + shows up as an inline call-out in the preview AND as a Comments API thread in the editor on next refresh.

Acceptance criteria

Inline REVIEW marker rendering

• <!-- REVIEW(@<author>): <text> --> markers in eligible files render as visible inline call-out boxes in the preview
• Call-out shows author and body; subtle border with colored left edge
• Click call-out → opens source file at the marker's line in editor
• Uses VS Code theme variables (--vscode-editor-foreground, --vscode-textBlockQuote-border, etc.)
• Markers in non-eligible files render as standard hidden HTML comments (no change to default behavior)
• No regression to existing editor-side Comments API rendering — both surfaces show the same markers

REVIEW marker minimap

• Right-edge fixed column shows one colored dot per REVIEW marker, positioned proportional to the marker's location in the preview viewport
• Hover dot → tooltip with author + truncated body
• Click dot → smooth-scrolls preview to the marker's call-out
• Updates on window resize and preview rebuild
• Composes visually with vscode: markdown preview navigation chrome — floating TOC + quick-jump overlay + per-heading mini-toolbar for long Codev artifacts #861's floating TOC — no overlap or fighting for space
• Hidden when the doc has zero REVIEW markers

General

• All gated to codev/(plans|specs|reviews)/*.md paths
• Uses theme variables throughout
• No external runtime dependencies added
• Composes with vscode: add review comments from the markdown preview pane (hover-+ per block, no editor mode-switch) #859 (+ add-comment) — newly added markers appear in both the inline call-out rendering AND the minimap on next preview refresh

Out of scope (v1)

• Reply / thread display in the call-outs — single comment per call-out in v1; design call deferred (depends on the broader Phase 3 reply-storage decision)
• Resolve state visualization (different border color for resolved markers) — depends on resolve-state storage decision (Phase 3.3 from prior planning); add when that lands
• Filter UI in preview ("hide resolved markers", "show only mine") — that's vscode: review summary webview — bird's-eye list of all REVIEW markers in spec/plan files with click-to-jump #860's job; preview shows everything
• Editing markers from the call-out — call-outs are read + click-to-jump only; mutation happens in the editor via the existing Comments API path
• Per-marker minimap colors (e.g. red for unresolved, gray for resolved) — uniform color in v1; differentiation lands with resolve state
• Outline panel enrichment (markers as outline children) — different VS Code API entry point; separate filing if/when wanted

Dependencies

• vscode: add review comments from the markdown preview pane (hover-+ per block, no editor mode-switch) #859 — this issue is what I previously called "vscode: add review comments from the markdown preview pane (hover-+ per block, no editor mode-switch) #859 Phase 2." vscode: add review comments from the markdown preview pane (hover-+ per block, no editor mode-switch) #859 currently scopes to add-only; this issue is the read-side render and spatial overview. They're related but vscode: add review comments from the markdown preview pane (hover-+ per block, no editor mode-switch) #859 v1 does NOT require this issue. The reverse: this issue assumes the same REVIEW marker format and source-line attribution conventions as vscode: add review comments from the markdown preview pane (hover-+ per block, no editor mode-switch) #859

Related

• vscode: spec/plan review comments — polish pass (placeholders, reviews/ coverage, author identity, panel discoverability) #857 — author identity (git config user.name); the call-out's author label uses whatever convention vscode: spec/plan review comments — polish pass (placeholders, reviews/ coverage, author identity, panel discoverability) #857 lands
• vscode: review summary webview — bird's-eye list of all REVIEW markers in spec/plan files with click-to-jump #860 — review summary webview; complementary surface (list view; this issue is in-context spatial view)
• vscode: markdown preview navigation chrome — floating TOC + quick-jump overlay + per-heading mini-toolbar for long Codev artifacts #861 — preview navigation chrome (TOC + quick-jump + per-heading toolbar); shares preview infrastructure; minimap must compose with TOC's right-edge real-estate
• Editor-side counterpart: packages/vscode/src/comments/plan-review.ts + packages/vscode/src/review-decorations.ts — both unchanged by this issue

Why this is high leverage

Currently the preview is a partial view of the doc — it shows the rendered prose but hides the feedback layer entirely. The architect's "read the preview" workflow gives them no signal that there's anything to address. This issue completes the preview: the feedback layer becomes visible in context (inline call-outs at the exact paragraph being discussed) and spatially (minimap shows where feedback is concentrated). Combined with #859 (add comments from the preview), the preview becomes the complete review surface — read, see existing feedback, add new feedback, see where it is, click to navigate, all without switching to the source editor unless replying/deleting.