Code-review findings, per-line code-block comments, and a document-comments agent skill

[kylemcd]

Fixes the issues from a full review of the codebase (the review doc lives in the planning vault), plus two follow-on additions built on that work: a per-line code-block comment feature and a reusable agent skill (see the last two sections). Full check — oxfmt, oxlint on src and test, tsc with noUncheckedIndexedAccess, 111 vitest tests — is green; production build verified.

Data-integrity fixes (each with a regression test)

• Forward-Delete no longer destroys a comment thread. The hidden <!--co:--> body block is now protected from atomic deletion, so a forward-Delete at the end of an anchored line removes only the swallowed newline instead of silently deleting the whole thread with no visible change.
• Multi-line comment text round-trips. Thread text is escaped (new format/escape.ts) so a reply like ok + Shift+Enter + +1 great no longer re-parses into a bogus entry and a fake reaction; blank lines and trailing spaces are preserved too. Reaction author commas are escaped.
• --> in the selected text or author no longer leaks the thread. The quote/author header fields break --> like body text already did, so the HTML comment can't terminate early in Reading view / GitHub / export.
• Add-comment inside a fenced code block is refused instead of writing masked, invisible markers.
• Delete removes every occurrence of a comment's markers, so copy-paste duplicates don't leave invisible, un-removable leftovers.
• Adjacent comments no longer both borrow the single space between them (which produced overlapping atomic ranges with no caret position between them).

Write-path correctness

• New editor/routing.ts centralizes edit routing: the reading margin and sidebar prefer an open editor (undo history + unsaved buffer) over a disk write that races autosave.
• New-comment offsets are verified against the captured selection before writing (mobile modal, reading draft, reading mobile), so a doc that shifted under the composer is caught instead of mis-anchoring.
• Reading-view Add-comment is rejected inside an embed/preview (a different file's block).
• Card: preserve an in-progress entry edit across external updates; drop the document-level mousedown listener on destroy; tear down the reaction-picker listener when an emoji is picked. Both margins guard rAF/reposition against a destroyed view.
• Comment-text links resolve against the editor's own file (editorInfoField); the sidebar loads a deferred (Obsidian 1.7+) leaf before use; settings changes resync the ribbon.

Refactor (removes the duplication the review flagged)

• Pure, tested stackTops stacking algorithm shared by both margins (and it batches DOM reads before writes); shared processFileEdit fold; shared spanSelector/closestSpanId, constants, and the draft composer. cardSignature/formatRelativeTime moved to a pure module and unit-tested. Settings single-sourced; Draft folded into TextRange; dead isValidId removed.

Tooling

• noUncheckedIndexedAccess on (and the resulting real cases fixed); test/ is now linted; redundant tsconfig flags dropped; package.json version synced.

A handful of low-value/high-churn items are consciously deferred and listed in the review doc's resolution-status section (e.g. table-quote link resolution, full CRLF-on-insert normalization, a margin base class, gating test typechecking).

Per-line code-block comments

Comments can now anchor specific lines inside a fenced code block, not just prose. The comment wraps the fence with own-line <!--c-->/<!--/c--> markers and records the block-relative line range (line:F-T) plus the exact code as the body quote:; the target lines are highlighted in Live Preview and Reading view.

• Live Preview layout is pixel-faithful to an uncommented block. The hidden marker/body lines are block-replaced to zero height while every newline is preserved, so the surrounding blank lines and both ``` fence rows keep their natural, theme-driven height — no ghost gap above the block and no row-shift below. (This resolves a glitch where absorbing a fence-adjacent newline stopped Obsidian tagging the opening/closing fence, and it does so with no hardcoded pixel values, so it holds across themes/font sizes.)
• CRLF-safe delete. Deleting a code comment on a CRLF file takes the whole \r\n with each own-line marker instead of leaving a stray blank line (the raw-file path — sidebar / Reading view — sees the file's real endings). Full CRLF-on-insert normalization remains the deferred item noted above.
• Regression tests cover the rendered row structure (both fences and both blank lines survive), the document-start and body-at-EOF edge cases, the atomic caret range, and the CRLF delete round-trip.

Agent skill (skills/document-comments/)

A self-contained, generic skill teaching an agent to create, reply to, resolve, and delete these comments correctly — leading with the alphanumeric-ID rule that silently breaks a comment when violated. Ships the on-disk format reference, a dependency-free validate_comments.py, and the eval suite used to verify it (100% with-skill vs 44% no-skill baseline over the bundled evals). Transient eval run outputs (skills/*-workspace/) and the packaged .skill artifact are gitignored; the source here is the single source of truth.

🤖 Generated with Claude Code