[tdody]

Summary

Fixes THI-443. Rebuilds the review walkthrough view (static/src/review/Walkthrough.jsx).

Before this change:

• Narrow text: stop text was a centered 72–80ch column about a third of the card's width.
• Unreadable diagrams: they were squeezed to that column, at 30% scale with ~5px labels.
• Code changes buried: behind a toggle, under a wall of "not in this diff" paths.
• No progress tracking: nothing recorded which stops you'd read.

The design is in docs/superpowers/specs/2026-10-29-walkthrough-two-column-design.md and the plan in docs/superpowers/plans/2026-10-29-walkthrough-two-column.md. CLAUDE.md's reviews row now points at that spec.

Page

• A fixed header (title, PR link, staleness badge, "N / M reviewed") over one scrolling body.
• A numbered contents list beside the problem statement. The problem statement now renders its markdown.
• Stop cards edged in their kind's color. Each has a title row, a full-width diagram row, then the prose beside a code-changes column.
  • The grid is minmax(min(52ch, 440px), 72ch) minmax(540px, 1fr), switching to one column below 1050px (a container query on the scroller).
  • The prose gives up width before the code column drops under ~70 monospace characters.
• Code column: a file list with change counts, all hidden refs (not in this diff / generated / unchanged at the cited lines / no text changes) in one summary line, then the hunks.
  • The column is sticky beside the prose and scrolls on its own.
  • A file row or a prose cite chip scrolls the column (never the page) to that file and flashes it.
  • Files over 300 lines start collapsed behind "show N lines".
  • Hunks are memoized, so a reviewed toggle doesn't re-highlight them.
• Comments: the always-open boxes become a "comment" link, with a ⌘↩/Ctrl+↩ hint. Drafts survive a stop folding. A folded stop shows "2 comments · 1 open".

Diagrams

• Parser: parseWalkthrough lifts top-level mermaid fences into stop.diagrams. Nested ones stay inline.
• Size: in the diagram row a diagram fills the card up to its natural width, never below 75% of it, and scrolls sideways inside its own box when wider than the card.
• Full-size view: ⤢, or a click on the diagram, opens it at natural size in a lightbox.
  • It's mounted at the app root in overlays/Overlays.jsx; inside #split-view the header would paint over it.
  • It re-renders the source with a fresh id; a copied SVG's duplicate ids broke its arrowheads.
  • Focus goes to the scroller, Tab is kept inside, and Esc, backdrop or ✕ closes it and returns focus.
• App-wide theme: mermaid's base theme in periscope's tokens (split/mermaidTheme.js, with the DOM side in split/mermaidRender.js). It waits for the UI font and follows Settings → Fonts.
  • Pie, git, mindmap and timeline get explicit category palettes. The base theme would have collapsed them to one grey.
  • This restyles diagrams in file previews too.

Reviewed marks

• stopSig is an FNV-1a hash of the stop's source, with trailing whitespace trimmed, keyed by title in ~/.claude/reviews/<repo>/<slug>/reviewed.json. A mark lapses when a re-prepare rewrites the stop.
• POST /api/reviews/reviewed returns 400 for a bad stop or sig, and 404 with no walkthrough or when the review is cleared mid-request.
• Writes take a thread lock plus an fcntl.flock on the review dir, because dev and prod both write ~/.claude/reviews, and they're atomic (temp file + os.replace).
• clear_review now takes the same flock, so a mark can't leave a stray reviewed.json-only dir behind as an orphan queue row.
• The client updates optimistically through a per-title queue, reverts on failure, and a refetch can't undo a mark that landed meanwhile.
• A reviewed stop folds to its title row; its title unfolds it without unmarking.

Type and color: scoped to .walkthrough, so file previews and the Reviews queue don't change, apart from the diagram theme.

• Five sizes (12/13/15/18/22px).
• All text is at least 4.5:1, measured in the browser. That covered --fg-3 coming in from shared styles (hunk heads, list markers, closed PR links, syntax comments) and links in comments.
• Kind tokens in :root.
• Focus rings on every control.

Process

The spec and plan went through an adversarial review before any code. Each task then had a spec-compliance review and a code-quality review, several with multiple rounds, and the branch had a final whole-branch review.

Review findings fixed along the way:

• compat's memo would have installed global vnode hooks;
• a refetch race;
• lost drafts;
• the lightbox under the header;
• grey pie charts;
• the cross-process write race.

Test plan

• npm test: 1390 passed. New tests:
  • the parser's diagram lift;
  • stopSig / isReviewed, including a pinned hash vector;
  • evidenceFor grouping;
  • markQueue and appliesRefetch;
  • the theme mapping;
  • lightbox focus and backdrop;
  • render tests of WalkthroughView: header states, contents, cards, folding, cite wiring, large-file collapse and comment placement.
• uv run pytest -q: 2035 passed. New tests: read_reviewed / set_reviewed (corrupt input, flock, atomic write, never creating the dir) and the route (round-trip, 400s, 404s, mid-request clear, surrogate stops).
• bin/check: passes (3 pre-existing biome warnings in files this PR doesn't touch).
• static/dist rebuilt and fresh.
• Dev server (:17375), on a real 13-stop walkthrough and a 5-stop one, at 1600, 1420 and 1000px:
  • the layout and the breakpoint (two columns at a 1110px pane: 462px prose, 540px code; one column at 1030px);
  • no sideways page scroll;
  • diagram size (labels from 7.6px up to 10.5–14px);
  • the lightbox (above the header, Esc/backdrop/✕, focus return);
  • file and cite jumps (the page doesn't move);
  • a reviewed mark surviving a reload, unfolding without unmarking, and unmarking removing the file;
  • contrast spot-checks (all ≥ 4.5:1);
  • pie and gitGraph in distinct colors.

Follow-ups

• THI-446: most cited files report "not in this diff" (server ref matching or diff base).
• THI-447: a refetch still re-highlights every hunk (memoize on content).

🤖 Generated with Claude Code

[tdody]

@tomplex, could you review this one? It's a big visual change to the review walkthrough, so I'd suggest trying it locally before reading the diff. The bundle is committed, so there's no build step:

git fetch origin
git worktree add .claude/worktrees/thi-443 origin/thibaultdody/thi-443-review-walkthrough-full-width-layout-legible-diagrams
cd .claude/worktrees/thi-443
PERISCOPE_PORT=17375 PERISCOPE_DEV=1 uv run server.py

Then open http://127.0.0.1:17375/, click ◉ reviews, and open any review that has a walkthrough, ideally one with mermaid diagrams.

Worth trying:

• a wide and a narrow window, to see two columns vs. one (it switches at about a 1050px pane);
• ⤢, or a click on a diagram, for the full-size view; Esc closes it;
• a file row or a path:line chip in the text, which should scroll only the code column;
• reviewed on a stop, then reload; it stays folded. The dev server shares ~/.claude/reviews with prod, so this writes the real reviewed.json. Unmark it afterwards; unmarking deletes the file;
• any .md with a pie chart or gitGraph in a file preview: the diagram theme is app-wide now.

When you're done, git worktree remove .claude/worktrees/thi-443.

The spec is in docs/superpowers/specs/2026-10-29-walkthrough-two-column-design.md, if you want the reasoning behind any of it.