@cfbender/cesium 0.6.1 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,104 @@
 # Changelog
 
+## v0.7.0 — 2026-05-13
+
+Headlining feature: a new `cesium_annotate` tool that publishes
+PR-style review artifacts. The user opens the URL, leaves per-line and
+per-block comments — by clicking the "Comment" button on any block, by
+highlighting text to summon a floating menu, or by clicking the gutter
+affordance on any diff or code line — and submits a final verdict:
+Approve, Request changes, or Comment. The agent calls `cesium_wait` and
+receives the structured feedback back. Use it whenever you'd otherwise
+ask the user to read a substantial proposal and paste line references
+into chat — diffs, plans, PRDs, code proposals, RFCs, audits, design docs.
+
+The companion breaking change: `cesium_publish` no longer accepts an
+`html` field. Block input is the only mode. The catalog of 16 block
+types covers every shape published artifacts use in practice, and the
+html escape valve was attracting traffic that should have been
+block-rendered. The `raw_html` block remains for genuinely bespoke
+regions inside an otherwise-structured document.
+
+- **feat:** New `cesium_annotate` tool. Args: `title`, `blocks`,
+  `verdictMode` (`"approve"` | `"approve-or-reject"` | `"full"`),
+  `perLineFor` (default `["diff", "code"]`), `requireVerdict`, plus the
+  usual `summary` / `tags` / `expiresAt`. Returns the same
+  `{ id, httpUrl, terminalSummary, … }` shape as `cesium_ask`.
+- **feat:** `cesium_wait` now surfaces `comments` and `verdict` fields
+  (plus a `kind: "annotate"` discriminator) when polling an annotate
+  session. Existing ask sessions still return `answers` / `remaining`
+  exactly as before.
+- **feat:** Render-time `data-cesium-anchor` attributes on every
+  annotatable block (`block-N`) and on each line of `diff` and `code`
+  blocks (`block-N.line-M`). Anchor IDs are stable and validated against
+  `/^block-\d+(\.line-\d+)?$/` on both ends of the wire.
+- **feat:** Three new API routes — `POST /comments`, `DELETE
+/comments/:id`, `POST /verdict` — alongside the existing answer/state
+  routes. Per-artifact file locking serializes concurrent writes; the
+  embedded `cesium-meta` JSON remains the source of truth.
+- **feat:** Client UI with always-visible "Comment" buttons in the
+  top-right of every annotatable block, hover-revealed gutter
+  affordances on diff and code lines (no layout shift), a floating
+  selection menu that captures highlighted text as comment context, and
+  a sticky verdict footer with comment-count gating.
+- **feat:** Frozen post-verdict rendering. After the user submits a
+  verdict, the artifact is rewritten with a verdict pill near the title,
+  comment bubbles populated server-side at their anchor positions, and
+  the interactive scaffold suppressed via CSS. The client script is
+  retained — its sole post-verdict job is bubble positioning and
+  bidirectional hover linking.
+- **feat:** `cesium_annotate` artifacts get their own top-level
+  `kind: "annotate"` value, so the index UI and filter chips treat them
+  as a distinct class.
+- **feat:** Two new reference fixtures —
+  `examples/annotate-pr-review.html` (open session) and
+  `examples/annotate-pr-review-closed.html` (frozen post-verdict). Both
+  open standalone via `file://` and demonstrate the full surface.
+- **feat:** Project and global index eyebrows are now clickable links to
+  the parent index — a small navigation nicety that closes the breadcrumb
+  loop.
+- **breaking:** `cesium_publish` no longer accepts `html`. Use `blocks`,
+  with `raw_html` for genuinely bespoke regions. The validator rejects
+  `html` input with a clear error message. Artifacts already on disk are
+  unaffected — they continue to render exactly as before.
+- **breaking:** The `inputMode` field on `ArtifactMeta` is removed. All
+  new artifacts are blocks-based by definition; the discriminator no
+  longer carries information.
+- **internal:** New `InteractiveAnnotateData` discriminated variant
+  alongside `InteractiveAskData`, gated by a `kind` field. A tolerant
+  reader (`coerceInteractiveData`) treats existing ask-only artifacts
+  without a `kind` field as `kind: "ask"`, so no on-disk rewrite is
+  required.
+- **internal:** Prompt fragment grew a routing-rules section so agents
+  consistently reach for `cesium_annotate` when reviewing generated
+  content rather than asking for chat-based feedback.
+- **tests:** ~200 new tests across schema, anchor stamping, tool
+  handler, mutate, API, client JS, frozen rendering, and a full
+  publish → comment → delete → verdict → wait end-to-end lifecycle.
+  Total suite is now 1530+ tests.
+
+Old `cesium_ask` artifacts on disk are not affected by any of this — the
+discriminator was added with a tolerant reader specifically for backward
+compatibility. The annotate flow lives entirely on the new code paths.
+
+## v0.6.2 — 2026-05-13
+
+Prompt fix. The `diff` block was missing from the agent-facing quick reference
+in `system-fragment.md` — only fifteen of the sixteen catalog blocks were
+surfaced — so agents would reach for `code` blocks with hand-rolled `+`/`-`
+lines when asked to walk through a diff or release. The `diff` block is now
+listed alongside `code`/`timeline`, and a short trigger note pairs "release
+walkthrough / version diff / before-after / refactor proposal" with the `diff`
+block explicitly.
+
+- **fix:** Add `diff` to the prompt's quick block reference.
+- **fix:** Add "When showing code changes" trigger paragraph.
+- **chore:** Bump the block-type enumeration tests from 15 → 16 to keep the
+  catalog and the human-curated reference in lockstep.
+
+No runtime or rendering changes; the `diff` block itself was already wired
+end-to-end since v0.4.
+
 ## v0.6.1 — 2026-05-13
 
 Fixes a regression introduced by the v0.4 blocks refactor: the README's
@@ -68,7 +167,7 @@ continue rendering unchanged.
   - Restructure `src/server/api.ts` regex matching to remove four
     `!` non-null assertions.
   - Replace `match![1]!` patterns in tests with a local `unwrap(value,
-    name)` helper for proper type narrowing.
+name)` helper for proper type narrowing.
   - Replace `handle!.url` in tests with an explicit null check.
   - Add targeted `eslint-disable-next-line no-await-in-loop` comments
     (with `--` reason annotations matching the existing repo convention)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfbender/cesium",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Beautiful self-contained HTML artifacts from your opencode agent.",
   "keywords": [
     "agent",

package/src/index.ts

@@ -6,6 +6,7 @@ import { fileURLToPath } from "node:url";
 import type { Plugin, Hooks } from "@opencode-ai/plugin";
 import { createPublishTool } from "./tools/publish.ts";
 import { createAskTool } from "./tools/ask.ts";
+import { createAnnotateTool } from "./tools/annotate.ts";
 import { createWaitTool } from "./tools/wait.ts";
 import { createStyleguideTool } from "./tools/styleguide.ts";
 import { createCritiqueTool } from "./tools/critique.ts";
@@ -27,6 +28,7 @@ export const CesiumPlugin: Plugin = async (ctx): Promise<Hooks> => {
     tool: {
       cesium_publish: createPublishTool(ctx),
       cesium_ask: createAskTool(ctx),
+      cesium_annotate: createAnnotateTool(ctx),
       cesium_wait: createWaitTool(ctx),
       cesium_styleguide: createStyleguideTool(ctx),
       cesium_critique: createCritiqueTool(ctx),

package/src/prompt/system-fragment.md

@@ -2,20 +2,21 @@
 
 Cesium publishes beautiful self-contained artifacts to a local server you can open in a browser.
 
-You have access to six tools:
+You have access to seven tools:
 
 - `cesium_publish` — write a substantive response as a self-contained HTML document
 - `cesium_ask` — publish an interactive Q&A artifact; returns `{ id, httpUrl, ... }`
-- `cesium_wait` — block until the user completes a `cesium_ask` artifact (polls disk)
+- `cesium_annotate` — publish a review artifact so the user can comment on the content and give a verdict
+- `cesium_wait` — block until the user completes a `cesium_ask` or `cesium_annotate` artifact
 - `cesium_styleguide` — fetch the full block reference (call before writing anything complex)
 - `cesium_critique` — analyze a draft artifact; returns a 0-100 score and findings
 - `cesium_stop` — stop the running cesium HTTP server
 
-## Two input modes
+## Describing content with blocks
 
-`cesium_publish` accepts either `blocks: Block[]` (preferred) or `html: string` (escape valve). Provide exactly one.
+`cesium_publish` takes a `blocks: Block[]` array — a closed set of typed building blocks (hero, tldr, section, prose, list, callout, code, diff, timeline, compare_table, risk_table, kv, pill_row, divider, diagram, raw_html). Blocks are token-efficient, server-templated, and machine-checkable. Call `cesium_styleguide` for the full block catalog with schemas and rendered examples.
 
-**Prefer `blocks`** for plans, reviews, reports, explainers, comparisons, audits, design docs. Blocks are token-efficient (no structural boilerplate), server-templated, and machine-checkable. Use `html` only when the whole document needs bespoke art-direction. For isolated bespoke regions, use `raw_html` or `diagram` blocks.
+For content that doesn't fit any typed block, use `raw_html` (an escape hatch for free-form HTML) or `diagram` (for inline SVG/HTML visualizations).
 
 ### Example
 
@@ -78,11 +79,16 @@ Call `cesium_styleguide` for full schemas and rendered examples.
 - `prose` — free-form markdown; `list` — bullet/numbered/checklist
 - `callout` — aside with variant: note/warn/risk; `divider` — rule
 - `code` — fenced code with lang; `timeline` — milestone list
+- `diff` — side-by-side before/after code with bezier connectors
 - `compare_table` — comparison grid; `risk_table` — risk grid
 - `kv` — key-value pairs; `pill_row` — pill/tag chips
 - `diagram` — SVG/HTML visual (scrubbed)
 - `raw_html` — custom HTML escape hatch (scrubbed; add `purpose`)
 
+## When showing code changes
+
+Showing what changed — release walkthroughs, version diffs, refactor proposals, before/after — use the `diff` block, not a `code` block with hand-rolled `+`/`-` lines. Pass either `patch` (unified diff) or both `before` and `after`. One `diff` block per file or hunk.
+
 {{BLOCK_FIELD_REFERENCE}}
 
 ## When to use raw_html / diagram
@@ -96,15 +102,33 @@ Publish when: ≥ 400 words; comparison/matrix/plan/PRD/RFC; code review with >3
 
 User overrides: "/cesium" or "publish this" → publish; "in terminal" → don't.
 
+## Choosing between cesium_publish, cesium_ask, and cesium_annotate
+
+Three tools, three different shapes of conversation:
+
+- **`cesium_publish`** — one-way broadcast. Use when delivering a finished artifact the user is likely to re-read or share, with no structured response needed.
+- **`cesium_ask`** — structured Q&A. Use when you need bounded input: a pick between N options, a numeric slider, a confirm, an approve/reject reaction on a small proposal.
+- **`cesium_annotate`** — review of substantive content. Use whenever you are asking the user to review, give feedback on, or approve generated content too rich for a yes/no — diffs, plans, PRDs, code proposals, RFCs, audits, design docs. The user can leave per-line and per-block comments and a final verdict (Approve / Request changes / Comment).
+
+Routing rules:
+
+- "Here's a diff — does it look right?" → `cesium_annotate`.
+- "Here's a plan — any concerns?" → `cesium_annotate`.
+- "Approve this short thing yes/no?" → `cesium_ask` with a `react` question.
+- "Pick one of these three options" → `cesium_ask` with `pick_one`.
+- Just delivering a finished artifact, no feedback needed → `cesium_publish`.
+
+Default bias for review-flavored work: prefer `cesium_annotate` over chat back-and-forth. Inline comments on the actual content are dramatically higher-fidelity than asking the user to paste line references into a chat reply.
+
 ## Self-check before publishing
 
-Call `cesium_critique` before `cesium_publish` on substantive artifacts. Mode is auto-detected (pass `html` or `blocks`). Act on warn-level findings; consider suggest-level. If score < 70, revise.
+Call `cesium_critique` before `cesium_publish` on substantive artifacts. Act on warn-level findings; consider suggest-level. If score < 70, revise.
 
 ## After publishing
 
-Print a 2-line terminal summary: `Cesium · <Title> (<kind>)` + the HTTP URL. Do not paste the full document content into the terminal.
+Print a 2-line terminal summary: `Cesium · <Title> (<kind>)` + the HTTP URL. Both `cesium_ask` and `cesium_annotate` return a `terminalSummary` field — print it the same way. Do not paste the full document content into the terminal.
 
-## Interactive Q&A: cesium_ask + cesium_wait
+## Interactive Q&A: cesium_ask
 
 1. `cesium_ask({ title, body, questions: [...] })` → returns `{ id, httpUrl, ... }`
 2. Print the terminalSummary so the user knows where to click.
@@ -113,6 +137,47 @@ Print a 2-line terminal summary: `Cesium · <Title> (<kind>)` + the HTTP URL. Do
 
 Question types: pick_one, pick_many, confirm, ask_text, slider, react. Set `optional: true` on an `ask_text` question to add a Skip button. Don't use cesium_ask for trivial yes/no questions — use it when the question deserves to live on disk as a decision record.
 
+## Reviewing content with cesium_annotate + cesium_wait
+
+For PR-style reviews of substantive content (diffs, plans, PRDs, code, designs):
+
+1. `cesium_annotate({ title, blocks: [...] })` → returns `{ id, httpUrl, terminalSummary, ... }`. The blocks render with hover affordances on every annotatable unit (per-line on `diff`/`code`, per-block elsewhere).
+2. Print the terminalSummary so the user knows where to click.
+3. `cesium_wait({ id })` → blocks until the user submits a verdict (10-min default timeout).
+4. Read `result.kind`, `result.comments`, and `result.verdict`. Ignore `result.answers` and `result.remaining` — those are populated only for `cesium_ask` sessions.
+
+Result shape for a completed annotate session:
+
+```json
+{
+  "status": "complete",
+  "kind": "annotate",
+  "comments": [
+    {
+      "id": "...",
+      "anchor": "block-2.line-5",
+      "selectedText": "return x + 1",
+      "comment": "Should this be x + 1 or x - 1?",
+      "createdAt": "..."
+    }
+  ],
+  "verdict": { "value": "request_changes", "decidedAt": "..." }
+}
+```
+
+Verdict values: `approve`, `request_changes`, `comment`. `verdict` may be `null` if the session timed out before the user decided. Each comment has a unique `id` and an `anchor` — either `block-N` (a whole block) or `block-N.line-M` (a single line inside a `diff` or `code` block).
+
+**Round-trip:** when the verdict is `request_changes`, revise the content and publish a new `cesium_annotate` with `supersedes` pointing at the prior id. The user can review the revision the same way.
+
+**Configuration:**
+
+- `verdictMode`: `"approve"` | `"approve-or-reject"` | `"full"` (default `"full"` — exposes all three verdict buttons).
+- `perLineFor`: array of block types that get per-line anchors. Default `["diff", "code"]`.
+- `requireVerdict`: if true (default), the session stays open until the user picks a verdict; otherwise the user can submit just comments.
+- `expiresAt`: ISO timestamp after which the session auto-expires. Default 24 hours from publish.
+
+Use `cesium_annotate` whenever a review with targeted comments would be higher fidelity than a chat back-and-forth.
+
 ## Stopping the server
 
 Call `cesium_stop` to stop or restart. The next `cesium_publish` will lazy-start a fresh server.

package/src/render/annotate-frozen.ts

@@ -0,0 +1,90 @@
+// Pure rendering functions for the frozen (post-verdict) annotate state.
+// No I/O — only string-in, string-out.
+//
+// These are called from setVerdict to bake the static review into the HTML
+// before the file is persisted. The client script still runs for positioning,
+// but all interactive affordances are hidden by CSS.
+
+import { escapeHtml, escapeAttr } from "./blocks/escape.ts";
+import type { Comment, Verdict } from "./validate.ts";
+
+// ─── Anchor humanization ──────────────────────────────────────────────────────
+//
+// Mirrors the client-side humanizeAnchor helper in client-js.ts so that
+// server-rendered labels match what the client would have shown.
+//
+// "block-3"        → "Block 3"
+// "block-3.line-12" → "Block 3 · line 12"
+
+function humanizeAnchor(anchor: string): string {
+  const parts = anchor.split(".");
+  const blockPart = parts[0] ?? "";
+  const blockNum = blockPart.replace("block-", "");
+  if (parts.length === 1) {
+    return `Block ${blockNum}`;
+  }
+  const linePart = parts[1] ?? "";
+  const lineNum = linePart.replace("line-", "");
+  return `Block ${blockNum} \u00b7 line ${lineNum}`;
+}
+
+// ─── renderFrozenBubble ───────────────────────────────────────────────────────
+
+/** Renders a single read-only comment bubble (no delete button). */
+export function renderFrozenBubble(comment: Comment): string {
+  const label = escapeHtml(humanizeAnchor(comment.anchor));
+  const text = escapeHtml(comment.comment);
+  const commentIdAttr = escapeAttr(comment.id);
+  const anchorAttr = escapeAttr(comment.anchor);
+
+  const quoteBlock =
+    comment.selectedText.trim() !== ""
+      ? `\n  <blockquote class="cs-comment-bubble-quote">${escapeHtml(comment.selectedText)}</blockquote>`
+      : "";
+
+  return `<article class="cs-comment-bubble" data-comment-id="${commentIdAttr}" data-anchor="${anchorAttr}">
+  <header class="cs-comment-bubble-head">
+    <span class="cs-comment-anchor-label">${label}</span>
+  </header>
+  <p class="cs-comment-text">${text}</p>${quoteBlock}
+</article>`;
+}
+
+// ─── renderFrozenRail ─────────────────────────────────────────────────────────
+
+/** Renders the comment rail populated with all frozen bubbles. */
+export function renderFrozenRail(comments: Comment[]): string {
+  const inner = comments.map((c) => renderFrozenBubble(c)).join("\n");
+  return `<aside class="cs-comment-rail" data-cesium-comment-rail aria-label="Review comments">${inner.length > 0 ? `\n${inner}\n` : ""}</aside>`;
+}
+
+// ─── renderVerdictPill ────────────────────────────────────────────────────────
+
+const VERDICT_LABELS: Record<Verdict, string> = {
+  approve: "Approved",
+  request_changes: "Changes requested",
+  comment: "Reviewed",
+};
+
+/** Formats an ISO date string as "Month DD, YYYY" (e.g. "May 13, 2026"). */
+function formatDecidedAt(decidedAt: string): string {
+  return new Date(decidedAt).toLocaleDateString("en-US", {
+    year: "numeric",
+    month: "short",
+    day: "numeric",
+  });
+}
+
+/** Renders a verdict pill to display prominently near the top of the artifact. */
+export function renderVerdictPill(verdict: { value: Verdict; decidedAt: string }): string {
+  const label = VERDICT_LABELS[verdict.value];
+  const dateDisplay = formatDecidedAt(verdict.decidedAt);
+  const decidedAtAttr = escapeAttr(verdict.decidedAt);
+  const valueAttr = escapeAttr(verdict.value);
+
+  return `<aside class="cs-verdict-pill cs-verdict-pill-${verdict.value}" data-cesium-verdict="${valueAttr}">
+  <span class="eyebrow">Verdict</span>
+  <strong>${escapeHtml(label)}</strong>
+  <time datetime="${decidedAtAttr}">${escapeHtml(dateDisplay)}</time>
+</aside>`;
+}

package/src/render/blocks/render.ts

@@ -35,6 +35,24 @@ export interface RenderCtx {
   path: string;
   /** Shiki highlight theme derived from the active cesium theme preset. */
   highlightTheme: HighlightTheme;
+  /**
+   * Anchor id for this block's outermost element, e.g. "block-3".
+   * Null for the divider block (no anchor) and for child blocks rendered inside a section
+   * (they live inside the section's anchored container).
+   */
+  anchor: string | null;
+}
+
+/**
+ * Returns a single attribute snippet ' data-cesium-anchor="block-N"' (with leading space),
+ * or empty string when ctx.anchor is null. Renderers splice this into the opening tag
+ * of their outermost element.
+ *
+ * The anchor value is safe by construction (matches block-\d+(\.line-\d+)?) — no escaping needed.
+ */
+export function anchorAttr(ctx: RenderCtx): string {
+  if (ctx.anchor === null) return "";
+  return ` data-cesium-anchor="${ctx.anchor}"`;
 }
 
 function makeRootCtx(highlightTheme: HighlightTheme = "claret-dark"): RenderCtx {
@@ -43,6 +61,7 @@ function makeRootCtx(highlightTheme: HighlightTheme = "claret-dark"): RenderCtx
     depth: 0,
     path: "blocks",
     highlightTheme,
+    anchor: null,
   };
 }
 
@@ -97,6 +116,7 @@ export async function renderBlocks(
     const blockCtx: RenderCtx = {
       ...ctx,
       path: `blocks[${i}]`,
+      anchor: block.type === "divider" ? null : `block-${i}`,
     };
     // eslint-disable-next-line no-await-in-loop -- sequential render required; section counter is a shared mutable ref
     parts.push(await renderBlock(block, blockCtx));

package/src/render/blocks/renderers/callout.ts

@@ -4,16 +4,17 @@
 import type { CalloutBlock } from "../types.ts";
 import type { BlockMeta } from "../types.ts";
 import type { RenderCtx } from "../render.ts";
+import { anchorAttr } from "../render.ts";
 import { escapeHtml } from "../escape.ts";
 import { renderMarkdown } from "../markdown.ts";
 
-export function renderCallout(block: CalloutBlock, _ctx: RenderCtx): string {
+export function renderCallout(block: CalloutBlock, ctx: RenderCtx): string {
   const titleHtml =
     block.title !== undefined && block.title !== ""
       ? `<strong>${escapeHtml(block.title)}</strong> `
       : "";
   const contentHtml = renderMarkdown(block.markdown);
-  return `<aside class="callout ${block.variant}">\n${titleHtml}${contentHtml}\n</aside>`;
+  return `<aside class="callout ${block.variant}"${anchorAttr(ctx)}>\n${titleHtml}${contentHtml}\n</aside>`;
 }
 
 export const meta: BlockMeta = {

package/src/render/blocks/renderers/code.ts

@@ -4,9 +4,22 @@
 import type { CodeBlock } from "../types.ts";
 import type { BlockMeta } from "../types.ts";
 import type { RenderCtx } from "../render.ts";
+import { anchorAttr } from "../render.ts";
 import { escapeHtml, escapeAttr } from "../escape.ts";
 import { highlightCode } from "../highlight.ts";
 
+/**
+ * Inject data-cesium-anchor attributes onto each <span class="line"> in highlighted HTML.
+ * Counter is 1-indexed. The anchor value is safe by construction — no escaping needed.
+ */
+function injectLineAnchors(html: string, blockAnchor: string): string {
+  let lineNum = 0;
+  return html.replace(/<span class="line">/g, () => {
+    lineNum++;
+    return `<span class="line" data-cesium-anchor="${blockAnchor}.line-${lineNum}">`;
+  });
+}
+
 export async function renderCode(block: CodeBlock, ctx: RenderCtx): Promise<string> {
   const parts: string[] = [];
 
@@ -16,9 +29,11 @@ export async function renderCode(block: CodeBlock, ctx: RenderCtx): Promise<stri
   }
 
   const highlighted = await highlightCode(block.code, block.lang, ctx.highlightTheme);
-  parts.push(`  <pre><code class="lang-${escapeAttr(block.lang)}">${highlighted}</code></pre>`);
+  const withAnchors =
+    ctx.anchor !== null ? injectLineAnchors(highlighted, ctx.anchor) : highlighted;
+  parts.push(`  <pre><code class="lang-${escapeAttr(block.lang)}">${withAnchors}</code></pre>`);
 
-  return `<figure class="code">\n${parts.join("\n")}\n</figure>`;
+  return `<figure class="code"${anchorAttr(ctx)}>\n${parts.join("\n")}\n</figure>`;
 }
 
 export const meta: BlockMeta = {

package/src/render/blocks/renderers/compare-table.ts

@@ -4,10 +4,11 @@
 import type { CompareTableBlock } from "../types.ts";
 import type { BlockMeta } from "../types.ts";
 import type { RenderCtx } from "../render.ts";
+import { anchorAttr } from "../render.ts";
 import { escapeHtml } from "../escape.ts";
 import { renderMarkdown } from "../markdown.ts";
 
-export function renderCompareTable(block: CompareTableBlock, _ctx: RenderCtx): string {
+export function renderCompareTable(block: CompareTableBlock, ctx: RenderCtx): string {
   const headerCells = block.headers.map((h) => `      <th>${escapeHtml(h)}</th>`).join("\n");
 
   const bodyRows = block.rows
@@ -23,7 +24,7 @@ export function renderCompareTable(block: CompareTableBlock, _ctx: RenderCtx): s
     .join("\n");
 
   return (
-    `<table class="compare-table">\n` +
+    `<table class="compare-table"${anchorAttr(ctx)}>\n` +
     `  <thead>\n    <tr>\n${headerCells}\n    </tr>\n  </thead>\n` +
     `  <tbody>\n${bodyRows}\n  </tbody>\n` +
     `</table>`

package/src/render/blocks/renderers/diagram.ts

@@ -4,10 +4,11 @@
 import type { DiagramBlock } from "../types.ts";
 import type { BlockMeta } from "../types.ts";
 import type { RenderCtx } from "../render.ts";
+import { anchorAttr } from "../render.ts";
 import { escapeHtml } from "../escape.ts";
 import { scrub } from "../../scrub.ts";
 
-export function renderDiagram(block: DiagramBlock, _ctx: RenderCtx): string {
+export function renderDiagram(block: DiagramBlock, ctx: RenderCtx): string {
   const payload = block.svg ?? block.html ?? "";
   const scrubResult = scrub(payload);
   const scrubbed = scrubResult.html;
@@ -19,7 +20,7 @@ export function renderDiagram(block: DiagramBlock, _ctx: RenderCtx): string {
     parts.push(`<figcaption>${escapeHtml(block.caption)}</figcaption>`);
   }
 
-  return `<figure class="diagram">\n${parts.join("\n")}\n</figure>`;
+  return `<figure class="diagram"${anchorAttr(ctx)}>\n${parts.join("\n")}\n</figure>`;
 }
 
 export const meta: BlockMeta = {

package/src/render/blocks/renderers/diff.ts

@@ -3,6 +3,7 @@
 
 import type { DiffBlock, BlockMeta } from "../types.ts";
 import type { RenderCtx } from "../render.ts";
+import { anchorAttr } from "../render.ts";
 import { escapeHtml, escapeAttr } from "../escape.ts";
 import { highlightCode } from "../highlight.ts";
 import { parseUnifiedDiff } from "../diff/parse-unified.ts";
@@ -195,7 +196,7 @@ export async function renderDiff(block: DiffBlock, ctx: RenderCtx): Promise<stri
           : "";
       const header = filename !== "" ? `<header class="diff-header">${filename}</header>\n` : "";
       return (
-        `<figure class="diff-block fallback" data-lang="${escapeAttr(lang)}">\n` +
+        `<figure class="diff-block fallback" data-lang="${escapeAttr(lang)}"${anchorAttr(ctx)}>\n` +
         header +
         `  <pre><code>${escaped}</code></pre>\n` +
         `</figure>`
@@ -266,13 +267,22 @@ export async function renderDiff(block: DiffBlock, ctx: RenderCtx): Promise<stri
   let rightHighIdx = 0;
   const leftRows: string[] = [];
   const rightRows: string[] = [];
+  // Per-line anchor counter — 1-indexed, increments for every <li> emitted in source order.
+  let lineNum = 0;
 
   for (const entry of entries) {
     if (entry.kind === "hunk-sep") {
       const sepLabel = `… @ ${entry.newStart}`;
-      const sepHtml = `<li class="diff-line hunk-sep"><span class="num"></span><span class="content">${escapeHtml(sepLabel)}</span></li>`;
-      leftRows.push(sepHtml);
-      rightRows.push(sepHtml);
+      const leftLineAnchor =
+        ctx.anchor !== null ? ` data-cesium-anchor="${ctx.anchor}.line-${++lineNum}"` : "";
+      const rightLineAnchor =
+        ctx.anchor !== null ? ` data-cesium-anchor="${ctx.anchor}.line-${++lineNum}"` : "";
+      leftRows.push(
+        `<li class="diff-line hunk-sep"${leftLineAnchor}><span class="num"></span><span class="content">${escapeHtml(sepLabel)}</span></li>`,
+      );
+      rightRows.push(
+        `<li class="diff-line hunk-sep"${rightLineAnchor}><span class="num"></span><span class="content">${escapeHtml(sepLabel)}</span></li>`,
+      );
       continue;
     }
 
@@ -282,9 +292,11 @@ export async function renderDiff(block: DiffBlock, ctx: RenderCtx): Promise<stri
       const hl =
         leftHighlighted[leftHighIdx] ?? `<span class="line">${escapeHtml(entry.text)}</span>`;
       leftHighIdx++;
-      const lineNum = entry.beforeLineNum !== null ? String(entry.beforeLineNum) : "";
+      const displayNum = entry.beforeLineNum !== null ? String(entry.beforeLineNum) : "";
+      const lineAnchor =
+        ctx.anchor !== null ? ` data-cesium-anchor="${ctx.anchor}.line-${++lineNum}"` : "";
       leftRows.push(
-        `<li class="diff-line ${kind}"><span class="num">${escapeHtml(lineNum)}</span><span class="content">${hl}</span></li>`,
+        `<li class="diff-line ${kind}"${lineAnchor}><span class="num">${escapeHtml(displayNum)}</span><span class="content">${hl}</span></li>`,
       );
     }
 
@@ -292,9 +304,11 @@ export async function renderDiff(block: DiffBlock, ctx: RenderCtx): Promise<stri
       const hl =
         rightHighlighted[rightHighIdx] ?? `<span class="line">${escapeHtml(entry.text)}</span>`;
       rightHighIdx++;
-      const lineNum = entry.afterLineNum !== null ? String(entry.afterLineNum) : "";
+      const displayNum = entry.afterLineNum !== null ? String(entry.afterLineNum) : "";
+      const lineAnchor =
+        ctx.anchor !== null ? ` data-cesium-anchor="${ctx.anchor}.line-${++lineNum}"` : "";
       rightRows.push(
-        `<li class="diff-line ${kind}"><span class="num">${escapeHtml(lineNum)}</span><span class="content">${hl}</span></li>`,
+        `<li class="diff-line ${kind}"${lineAnchor}><span class="num">${escapeHtml(displayNum)}</span><span class="content">${hl}</span></li>`,
       );
     }
   }
@@ -339,7 +353,7 @@ export async function renderDiff(block: DiffBlock, ctx: RenderCtx): Promise<stri
     `  </ol>`;
 
   return (
-    `<figure class="diff-block" data-lang="${escapeAttr(lang)}">\n` +
+    `<figure class="diff-block" data-lang="${escapeAttr(lang)}"${anchorAttr(ctx)}>\n` +
     `  ${headerHtml}\n` +
     `  <div class="diff-grid">\n` +
     `${leftOl}\n` +

package/src/render/blocks/renderers/hero.ts

@@ -4,9 +4,10 @@
 import type { HeroBlock } from "../types.ts";
 import type { BlockMeta } from "../types.ts";
 import type { RenderCtx } from "../render.ts";
+import { anchorAttr } from "../render.ts";
 import { escapeHtml } from "../escape.ts";
 
-export function renderHero(block: HeroBlock, _ctx: RenderCtx): string {
+export function renderHero(block: HeroBlock, ctx: RenderCtx): string {
   const parts: string[] = [];
 
   if (block.eyebrow !== undefined && block.eyebrow !== "") {
@@ -26,7 +27,7 @@ export function renderHero(block: HeroBlock, _ctx: RenderCtx): string {
     parts.push(`  <dl class="kv">\n${rows}\n  </dl>`);
   }
 
-  return `<header>\n${parts.join("\n")}\n</header>`;
+  return `<header${anchorAttr(ctx)}>\n${parts.join("\n")}\n</header>`;
 }
 
 export const meta: BlockMeta = {

package/src/render/blocks/renderers/kv.ts

@@ -4,13 +4,14 @@
 import type { KvBlock } from "../types.ts";
 import type { BlockMeta } from "../types.ts";
 import type { RenderCtx } from "../render.ts";
+import { anchorAttr } from "../render.ts";
 import { escapeHtml } from "../escape.ts";
 
-export function renderKv(block: KvBlock, _ctx: RenderCtx): string {
+export function renderKv(block: KvBlock, ctx: RenderCtx): string {
   const rows = block.rows
     .map((row) => `  <dt>${escapeHtml(row.k)}</dt><dd>${escapeHtml(row.v)}</dd>`)
     .join("\n");
-  return `<dl class="kv">\n${rows}\n</dl>`;
+  return `<dl class="kv"${anchorAttr(ctx)}>\n${rows}\n</dl>`;
 }
 
 export const meta: BlockMeta = {