feat(demo): full showcase polish - mouse cursor, robust selection, HF affiliations

Demo orchestration:
- Visible mouse cursor overlay (popover top-layer, MutationObserver to
stay above native dialogs) + humanMove/humanClick/humanHover helpers
- Yjs Node.js clients for Bob and Carol with awareness cursors and a
set of high-level helpers (writeBlockMathAtSlot, setAffiliationUrl,
waitForAffiliationCount, etc.) so peer interactions never collide
- Pre-bold sync barrier: Alice waits for Bob's block math and Carol's
code block to land before doing the bubble-toolbar bold so layout is
frozen during the drag selection (no more cross-paragraph selections)
- Progressive cursor-driven text selection (visible glide + step-wise
setTextSelection) for bold and rephrase actions
- Custom rAF-eased scroll-to-top on the actual .editor-scroll container
before the hue drag so the banner retint reads on camera

Embed Studio:
- New architecture.json companion data file (transformer-block layers)
seeded alongside model-accuracy.csv, so the agent has something
concrete to read and turn into the visualization
- Beefed-up chat scene that mirrors a real round-trip: readEmbed,
listDataFiles, readDataFile (json), readDataFile (csv), then a
detailed createEmbed - the description matches the rendered banner

Neural-network banner:
- Trim every link by node radius + margin so synapses no longer poke
through the ring (clear "links below nodes" layering)
- Hardcoded translucent white strokes with vector-effect:non-scaling-stroke
for visibility on every host surface (preview, editor hero, article)
- Ring + node strokes also non-scaling so they stay crisp at any size

Frontmatter / authors:
- Alice now adds her own huggingface.co profile URL alongside the
Hugging Face affiliation she seeds
- Bob backfills the affiliation's URL to https://huggingface.co and
adds two co-authors (Bob Mercier, Mira Patel) reusing affiliation
index 1, each with their own huggingface.co profile URL - byline
renders three co-authors all under Hugging Face with linkable name
and affiliation chips

Publish flow:
- Monotonic progress bar (useRef-backed, never goes backward)
- Restyled success state with URL chip and full-width "View published
article" button + ExternalLink icon
- Explicit humanClick on the link (after stripping target/rel) so the
navigation reads as a real user action

Agent rewrite extension:
- Fix cancelToken race that left replaced sentences empty: token is
now read from the initial command state, cursor mapped through every
intermediate transaction so the typewriter never bails early
- Atomic "none" animation path for the rephrase, with re-seeded
AgentFocus so the highlight stays on the new text through linger

UI polish:
- Publish dialog: softer shadows, color-mix accents, sparkling note
icon, gradient progress bar with shimmer, success URL chip
- Auto-close chat panel after rephrase action lands

Made-with: Cursor

backend/demo/alice.ts

@@ -26,7 +26,6 @@ import {
   bubbleToolbarBold,
   requestRephraseAction,
 } from "./lib/chat-actions.js";
-import { clearAgentFocus } from "./lib/selection.js";
 import { createNeuralNetworkBanner } from "./lib/embed-studio.js";
 import {
   claimSlot,
@@ -34,7 +33,7 @@ import {
   typeInSlot,
 } from "./lib/positions.js";
 import { applyHueChange, triggerPublish } from "./lib/publish-flow.js";
-import { writeScaffold } from "./lib/scaffolding.js";
+import { waitForPeersSettled, writeScaffold } from "./lib/scaffolding.js";
 
 export async function runAlice(page: Page, speed: number) {
   console.log("[alice] ready");
@@ -78,6 +77,7 @@ export async function runAlice(page: Page, speed: number) {
   // showcases a multi-institution collaboration on the byline
   // (MIT, ETH Zurich, Stanford).
   await addAuthor(page, "Alice Renoir", speed, {
+    url: "https://huggingface.co/arenoir",
     newAffiliation: "Hugging Face",
   });
   await pause(200, 360);
@@ -96,6 +96,10 @@ export async function runAlice(page: Page, speed: number) {
   await writeScaffold(
     page,
     [
+      // "The recipe" gets 4 slots: Bob fills the middle one (slot 1)
+      // with a <blockMath> atom carrying the canonical attention
+      // formula, so the section reads as definition -> formula ->
+      // softmax explanation -> multi-head teaser.
       { heading: "The recipe", slots: 4 },
       { heading: "Intuition", slots: 3 },
       { heading: "In Python", slots: 3 },
@@ -130,31 +134,6 @@ export async function runAlice(page: Page, speed: number) {
 
   await pause(180, 260);
 
-  // --- UI action: Alice selects a phrase in slot 0 and clicks Bold
-  // from the contextual bubble toolbar. This is the "I highlighted
-  // text and pressed B" path every end-user recognises - pure
-  // editor UX, no agent roundtrip. Happens MID-flow so the bolded
-  // text stays visible for the rest of the demo.
-  try {
-    const bolded = await bubbleToolbarBold(
-      page,
-      "Imagine each token",
-      "which other tokens matter right now",
-    );
-    if (!bolded) {
-      console.warn("[alice] bubble-toolbar bold skipped");
-    } else {
-      console.log("[alice] bubble-toolbar bold applied");
-    }
-  } catch (err) {
-    console.warn(
-      "[alice] bubble-toolbar bold aborted:",
-      err instanceof Error ? err.message : err,
-    );
-  }
-
-  await pause(140, 220);
-
   // Slot 1: short closing line that ties the intuition to the
   // mechanism. Intentionally a bit bland so the rephrase agent
   // action below has something meaningful to tighten up (viewers
@@ -189,11 +168,27 @@ export async function runAlice(page: Page, speed: number) {
       from: rephraseOriginal,
       to: rephraseRewrite,
       speed,
+      // Atomic swap + lingering agent label so it reads as an AI
+      // edit, not as the user typing. App.tsx re-seeds the focus
+      // on the replacement range and clears it after 1400ms.
+      animation: "none",
+      lingerAgentFocusMs: 1_400,
+    });
+    // Wait for the swap (520ms App-side delay before dispatch) and
+    // the lingering agent-focus label (1400ms) to finish before
+    // moving on, so the hue drag doesn't stomp on it.
+    await pause(2_000, 2_200);
+
+    // Close the chat panel now that Alice is done talking to the
+    // agent. Keeping it open through the hue drag / publish would
+    // look like Alice forgot to dismiss her conversation, and
+    // covers part of the editor body during the rest of the demo.
+    await page.evaluate(() => {
+      window.dispatchEvent(
+        new CustomEvent("__demo-chat", { detail: { open: false } }),
+      );
     });
-    // The AgentRewrite typewriter takes ~2-3s on a paragraph this
-    // long; leave room so the hue drag doesn't stomp on it.
-    await pause(2_200, 2_800);
-    await clearAgentFocus(page);
+    await pause(240, 360);
   } catch (err) {
     console.warn(
       "[alice] rephrase action aborted:",
@@ -220,24 +215,85 @@ export async function runAlice(page: Page, speed: number) {
 
   await pause(220, 340);
 
+  // --- UI action: bubble-toolbar Bold on an earlier phrase in slot 0.
+  // This is deliberately the LAST editor edit Alice does before the
+  // hue drag / publish: placing it here means Bob and Carol are
+  // both guaranteed done (their final contributions - the block
+  // math formula and the `import torch` code block - are already
+  // in the doc), so the layout is frozen when we measure and
+  // drag over the target text. Doing it mid-flow while peers are
+  // still inserting content would shift the Intuition paragraph
+  // under the measured rects and the selection sweep would pick
+  // up the heading above or the math atom below.
+  await waitForPeersSettled(page);
+  try {
+    const bolded = await bubbleToolbarBold(
+      page,
+      "Imagine each token",
+      "which other tokens matter right now",
+    );
+    if (!bolded) {
+      console.warn("[alice] bubble-toolbar bold skipped");
+    } else {
+      console.log("[alice] bubble-toolbar bold applied");
+    }
+  } catch (err) {
+    console.warn(
+      "[alice] bubble-toolbar bold aborted:",
+      err instanceof Error ? err.message : err,
+    );
+  }
+
+  await pause(200, 320);
+
   // Before the hue drag, scroll Alice's viewport back to the top of
   // the article. The neural-network banner lives at the very top
   // (hero section) and its embed reacts to the shared `primaryHue`
   // via postMessage - retinting every stroke live. If we stay at
   // the bottom of the doc during the slider drag the viewer can't
-  // see that, so we pay a short scroll beat to plant the camera on
-  // the banner before the rainbow sweep lands.
+  // see that, so we pay a scroll beat to plant the camera on the
+  // banner before the rainbow sweep lands.
+  //
+  // We drive the scroll ourselves (rAF + cubic ease-in-out) rather
+  // than using the browser's native `behavior: "smooth"`, because
+  // that one blasts back to 0 in ~500-700ms and reads as a
+  // "teleport" on camera. A hand scroll is ~2s and accelerates
+  // into a decelerating finish, which is what this loop emulates:
+  // the viewer sees the doc flow upward past the camera, and the
+  // hero banner slides down into view with visible inertia.
   try {
-    await page.evaluate(() => {
-      window.scrollTo({ top: 0, behavior: "smooth" });
-    });
-    // Smooth-scroll duration is variable (~500-900ms for a full
-    // page on Chromium). Wait for the scroll to actually settle
-    // by polling `scrollY === 0` with a short cap, rather than a
-    // blind sleep.
-    await page
-      .waitForFunction(() => window.scrollY < 4, null, { timeout: 2_000 })
-      .catch(() => undefined);
+    await page.evaluate(
+      (durationMs) =>
+        new Promise<void>((resolve) => {
+          // The editor is NOT scrolled on the window - it lives
+          // inside a `.editor-scroll` container that owns the
+          // overflow. Pick it first, fall back to documentElement
+          // if the layout shifts underneath us.
+          const container =
+            (document.querySelector(".editor-scroll") as HTMLElement | null) ??
+            (document.scrollingElement as HTMLElement | null) ??
+            document.documentElement;
+          const from = container.scrollTop;
+          if (from <= 2) {
+            resolve();
+            return;
+          }
+          const start = performance.now();
+          const easeInOut = (t: number) =>
+            t < 0.5 ? 2 * t * t : 1 - Math.pow(-2 * t + 2, 2) / 2;
+          const step = (now: number) => {
+            const t = Math.min(1, (now - start) / durationMs);
+            container.scrollTop = from * (1 - easeInOut(t));
+            if (t < 1) requestAnimationFrame(step);
+            else {
+              container.scrollTop = 0;
+              resolve();
+            }
+          };
+          requestAnimationFrame(step);
+        }),
+      2_100,
+    );
   } catch (err) {
     console.warn(
       "[alice] scroll-to-top aborted:",

backend/demo/banners.ts

@@ -31,8 +31,17 @@ export const NEURAL_NETWORK_BANNER_HTML = `<div class="d3-banner-nn" aria-label=
     display: block;
   }
   .d3-banner-nn .nn-link {
-    stroke: color-mix(in oklab, var(--text-color, #111) 14%, transparent);
-    stroke-width: 0.6;
+    /* Hardcoded translucent white, deliberately decoupled from the
+       host theme. The hero surface that sits behind this banner is
+       always tinted (primary-colored / dark), regardless of whether
+       the editor body itself is in light or dark mode, so a fixed
+       light stroke is the most reliable readability target. Binding
+       the stroke to --text-color flipped between near-black and
+       near-white per theme and vanished whenever the iframe theme
+       did not match the host hero (e.g. light editor + dark hero). */
+    stroke: rgba(255, 255, 255, 0.4);
+    stroke-width: 1;
+    vector-effect: non-scaling-stroke;
     fill: none;
   }
   .d3-banner-nn .nn-node {
@@ -42,7 +51,8 @@ export const NEURAL_NETWORK_BANNER_HTML = `<div class="d3-banner-nn" aria-label=
   .d3-banner-nn .nn-node-ring {
     fill: none;
     stroke: color-mix(in oklab, var(--primary-color, #4f46e5) 60%, transparent);
-    stroke-width: 0.8;
+    stroke-width: 1.2;
+    vector-effect: non-scaling-stroke;
   }
   .d3-banner-nn .nn-pulse {
     fill: var(--primary-color, #4f46e5);
@@ -95,14 +105,30 @@ export const NEURAL_NETWORK_BANNER_HTML = `<div class="d3-banner-nn" aria-label=
       a.forEach((na) => b.forEach((nb) => links.push([na, nb])));
     }
 
+    // Trim each link so its endpoints sit just OUTSIDE the node ring
+    // (radius 7 in viewBox units, plus a small margin). This guarantees
+    // the lines never poke through the inside of the ring, which used
+    // to make them read as if they sat on top of the nodes even though
+    // gLinks is appended before gNodes in DOM order. With trimming the
+    // visual layering is unambiguous: the ring contains a clean gap on
+    // every spoke. We do this analytically rather than relying on a
+    // background fill, which would fight with the transparent banner.
+    const NODE_R = 7;
+    const LINK_GAP = 1.5;
+    const trim = NODE_R + LINK_GAP;
     const gLinks = document.createElementNS(NS, 'g');
     links.forEach(([a, b]) => {
+      const dx = b.x - a.x;
+      const dy = b.y - a.y;
+      const dist = Math.hypot(dx, dy) || 1;
+      const nx = dx / dist;
+      const ny = dy / dist;
       const line = document.createElementNS(NS, 'line');
       line.setAttribute('class', 'nn-link');
-      line.setAttribute('x1', String(a.x));
-      line.setAttribute('y1', String(a.y));
-      line.setAttribute('x2', String(b.x));
-      line.setAttribute('y2', String(b.y));
+      line.setAttribute('x1', String(a.x + nx * trim));
+      line.setAttribute('y1', String(a.y + ny * trim));
+      line.setAttribute('x2', String(b.x - nx * trim));
+      line.setAttribute('y2', String(b.y - ny * trim));
       gLinks.appendChild(line);
     });
     svg.appendChild(gLinks);
@@ -203,6 +229,35 @@ export const MODEL_ACCURACY_CSV_META = {
   rowCount: 8,
 };
 
+// ---------------------------------------------------------------------------
+// Companion architecture descriptor for the neural-network banner. Seeded
+// alongside the CSV so the agent has something concrete to "discover" and
+// turn into the visualization. The layer counts here are the SAME ones
+// hardcoded in NEURAL_NETWORK_BANNER_HTML above (6 → 10 → 14 → 10 → 6),
+// which keeps the demo deterministic: the agent reads the JSON, narrates
+// the topology, then drops the matching banner.
+// ---------------------------------------------------------------------------
+
+export const ARCHITECTURE_JSON = `{
+  "name": "transformer-block",
+  "layers": [
+    { "name": "tokens",    "kind": "input",     "units": 6 },
+    { "name": "embedding", "kind": "projection","units": 10 },
+    { "name": "attention", "kind": "self-attn", "units": 14 },
+    { "name": "values",    "kind": "projection","units": 10 },
+    { "name": "logits",    "kind": "output",    "units": 6 }
+  ],
+  "connectivity": "fully-connected",
+  "activation": "softmax"
+}`;
+
+export const ARCHITECTURE_JSON_META = {
+  name: "architecture.json",
+  ext: "json",
+  columns: ["name", "kind", "units"],
+  rowCount: 5,
+};
+
 /**
  * Inline line chart rendered once Carol asks the agent for a
  * visualization. Self-contained (no ColorPalettes lookup to keep the

backend/demo/bob.ts

@@ -1,199 +1,281 @@
 /**
- * Bob - headless collaborator for the showcase demo.
+ * Bob - Yjs-only collaborator for the showcase demo.
+ *
+ * Bob is NOT a browser. He's a Node process that speaks the same
+ * Yjs CRDT protocol as the editor tabs and manipulates the shared
+ * document directly via Y.XmlElement / Y.XmlText. Every write shows
+ * up in Alice's Tiptap editor in real time without any DOM typing,
+ * input-rule surprises, or PM position races.
  *
  * Bob owns the "The recipe" section (top of doc). His flow:
- *   1. Wait for Alice's first author to land, then append two
- *      university collaborators (MIT, ETH Zurich).
- *   2. Wait for the "The recipe" heading scaffold.
- *   3. Type the definition paragraph with inline Q/K/V math.
- *   4. Fire the Vaswani 2017 citation tool call through the chat
- *      (writes entry to citationsMap + inserts a chip + spawns
- *      the Bibliography section).
- *   5. Drop the block-math formula.
- *   6. Close with a softmax explanation line.
+ *   1. Wait for Alice's first author to land, then push two
+ *      university co-authors (MIT, ETH Zurich).
+ *   2. Wait for the "The recipe" H2 to appear in the shared
+ *      fragment (Alice writes the scaffold from her browser).
+ *   3. Fill slot 0 with the definition paragraph + inline Q/K/V
+ *      math atoms.
+ *   4. Register the Vaswani 2017 paper in the shared citations
+ *      map, append a citation chip at the end of slot 0, and
+ *      spawn a Bibliography block at the bottom of the doc if
+ *      none exists.
+ *   5. Drop the canonical attention formula as a `<blockMath>`
+ *      atom into slot 1. That's a different agent (not Alice)
+ *      contributing a display-math equation to the article.
+ *   6. Fill slot 2 with the softmax explanation.
+ *   7. Fill slot 3 with the multi-head teaser.
  */
-import type { Page } from "playwright";
-import { pause } from "./human-typing.js";
-import { addAuthor } from "./lib/editor-actions.js";
-import { requestCitationAction } from "./lib/chat-actions.js";
+import * as Y from "yjs";
 import {
-  claimSlot,
-  installPositionTracker,
-  typeInSlot,
-} from "./lib/positions.js";
-import { waitForHeading2 } from "./lib/scaffolding.js";
-
-export async function runBob(page: Page, speed: number) {
-  console.log("[bob] joined, waiting for Alice's first author");
-  await installPositionTracker(page);
-  await pause(800, 1_200);
-
-  // 1) Authors: Alice seeds the byline first (principal agent), then
-  //    Bob appends two collaborators from big universities. We gate
-  //    on the "+" icon button appearing, which only renders after
-  //    the authors list has at least one entry - a reliable Yjs-
-  //    synced signal that Alice's insertion has landed on Bob's
-  //    page. This avoids the old brittle "Bob creates all three"
-  //    flow and shows the byline growing collaboratively, with
-  //    varied affiliations (MIT, ETH Zurich) that make the article
-  //    feel like a multi-lab paper.
-  try {
-    await page
-      .locator('button.icon-btn[aria-label="Add author"]')
-      .first()
-      .waitFor({ state: "visible", timeout: 30_000 });
-  } catch {
+  addAuthorRecord,
+  appendInline,
+  broadcastCursorAtEnd,
+  claimSlotAfterHeading,
+  clearAwarenessCursor,
+  findHeadingIndex,
+  insertInlineNode,
+  registerCitation,
+  setAffiliationUrl,
+  sleep,
+  typeIntoParagraph,
+  waitForAffiliationCount,
+  waitForAuthorCount,
+  waitForCondition,
+  writeBlockMathAtSlot,
+  type PersonaHandle,
+} from "./lib/yjs-client.js";
+
+function jitter(minMs: number, maxMs: number): number {
+  return minMs + Math.random() * (maxMs - minMs);
+}
+
+/**
+ * Ensure a `<bibliography />` atom exists at the end of the shared
+ * fragment. If one is already there (e.g. from a previous run that
+ * wasn't reset) we keep it; otherwise we push a fresh, empty one
+ * and let `BibliographyView` on Alice's side fill `renderedHtml`
+ * via the formatting endpoint.
+ */
+function ensureBibliographySection(handle: PersonaHandle): void {
+  const existing = handle.fragment
+    .toArray()
+    .find((c) => c instanceof Y.XmlElement && c.nodeName === "bibliography");
+  if (existing) return;
+
+  handle.ydoc.transact(() => {
+    const bib = new Y.XmlElement("bibliography");
+    handle.fragment.push([bib]);
+    bib.setAttribute("renderedHtml", "");
+    // Tiptap doesn't require an explicit trailing paragraph after
+    // the bibliography, but the original doc shape has one so the
+    // cursor always has a landing spot past the biblio in Alice's
+    // editor.
+    const trailing = new Y.XmlElement("paragraph");
+    handle.fragment.push([trailing]);
+  });
+}
+
+export async function runBob(
+  bob: PersonaHandle,
+  speed: number,
+): Promise<void> {
+  console.log("[bob] connected as Yjs peer, waiting for Alice's first author");
+
+  // Give Alice a beat to start typing the title before we pile on
+  // the author list; looks more natural on camera.
+  await sleep(jitter(800, 1200));
+
+  // 1) Authors -----------------------------------------------------
+  // Alice seeds the byline with herself + the "Hugging Face"
+  // affiliation (index 1) but the modal she drives doesn't expose a
+  // URL field for the affiliation. Bob then:
+  //   - waits for that affiliation to land in the shared Y.Array,
+  //   - patches its `url` to https://huggingface.co so the byline
+  //     renders the affiliation as a real link,
+  //   - appends two more authors that REUSE affiliation index 1
+  //     instead of creating fresh institutions, each with a personal
+  //     huggingface.co profile URL.
+  // Net effect on the byline: three co-authors (Alice + Bob's two)
+  // all under the same Hugging Face affiliation, with both the
+  // affiliation chip and each author name linkable.
+  const seeded = await waitForAuthorCount(bob, 1, 30_000);
+  if (!seeded) {
     console.warn("[bob] Alice's first author never appeared, proceeding");
   }
-  await pause(250, 500);
+  const affSeeded = await waitForAffiliationCount(bob, 1, 30_000);
+  if (!affSeeded) {
+    console.warn("[bob] Hugging Face affiliation never appeared, proceeding");
+  }
+  await sleep(jitter(250, 500));
+
+  setAffiliationUrl(bob, 1, "https://huggingface.co");
+  await sleep(jitter(180, 320));
 
-  await addAuthor(page, "Bob Mercier", speed, { newAffiliation: "MIT" });
-  await pause(200, 380);
-  await addAuthor(page, "Mira Patel", speed, {
-    newAffiliation: "ETH Zurich",
+  addAuthorRecord(bob, {
+    name: "Bob Mercier",
+    url: "https://huggingface.co/bmercier",
+    existingAffiliationIndices: [1],
+  });
+  await sleep(jitter(300, 550));
+  addAuthorRecord(bob, {
+    name: "Mira Patel",
+    url: "https://huggingface.co/mpatel",
+    existingAffiliationIndices: [1],
   });
-  console.log("[bob] authors added");
-
-  // 2) Wait for Alice's scaffold to ship the "The recipe" heading.
-  //    Bob OWNS this top section (swap from the old layout where
-  //    Alice wrote it): he types the definition with inline math,
-  //    the block-math formula, the softmax explanation, AND an
-  //    italic agent action - giving him enough content to keep his
-  //    cursor visibly typing through most of the 25s budget, in
-  //    concert with Alice (middle) and Carol (bottom).
-  try {
-    await waitForHeading2(page, "The recipe", 60_000);
-  } catch {
-    console.warn("[bob] 'The recipe' heading not found, skipping body");
+  console.log("[bob] authors added (both at Hugging Face)");
+
+  // 2) Wait for scaffold ------------------------------------------
+  // Alice's Playwright scaffold emits the H2 headings + empty
+  // paragraph slots. We gate on the "The recipe" heading showing
+  // up in our synced fragment before we start writing body text
+  // so `claimSlotAfterHeading` finds real anchors.
+  const hasHeading = await waitForCondition(
+    bob.fragment,
+    () => findHeadingIndex(bob.fragment, "The recipe") !== -1,
+    60_000,
+  );
+  if (!hasHeading) {
+    console.warn("[bob] 'The recipe' heading never arrived, skipping body");
     return;
   }
-  await pause(120, 240);
+  await sleep(jitter(150, 300));
 
-  const bobSpeed = speed * 1.8;
-  const bobIntro = { speed: bobSpeed, typoRate: 0, thinkRate: 0.02 };
-  const bobMath = { speed: bobSpeed, typoRate: 0, thinkRate: 0 };
-
-  // Slot 0: definition with queries / keys / values inline math.
-  const recipeSlot0 = await claimSlot(page, "The recipe", 0);
-  if (!recipeSlot0) {
-    console.warn("[bob] could not focus slot 0 of 'The recipe'");
+  // 3) Slot 0 - definition + inline math --------------------------
+  // We type the prose into the paragraph via `typeIntoParagraph`
+  // (chunked Y.XmlText inserts with human cadence so Alice sees
+  // text stream in), then splice in Y.XmlElement("inlineMath")
+  // atoms for Q, K, V. Each insert is a single atomic CRDT op,
+  // no input-rule interpretation involved.
+  const slot0 = claimSlotAfterHeading(bob.fragment, "The recipe", 0);
+  if (!slot0) {
+    console.warn("[bob] could not locate slot 0 of 'The recipe'");
     return;
   }
-  await pause(60, 120);
-  await typeInSlot(
-    page,
-    recipeSlot0,
+  await sleep(jitter(80, 160));
+
+  const bodyCps = 38 / Math.max(0.5, speed / 2);
+  const fastCps = 48 / Math.max(0.5, speed / 2);
+  await typeIntoParagraph(
+    slot0,
     "Attention lets a token look at every other token, scoring each pair through queries ",
-    bobIntro,
+    { cps: bodyCps, chunkSize: 2 },
+    undefined,
+    bob,
   );
-  await typeInSlot(page, recipeSlot0, "$$Q$$", bobMath);
-  await typeInSlot(page, recipeSlot0, ", keys ", bobMath);
-  await typeInSlot(page, recipeSlot0, "$$K$$", bobMath);
-  await typeInSlot(page, recipeSlot0, " and values ", bobMath);
-  await typeInSlot(page, recipeSlot0, "$$V$$", bobMath);
-  await typeInSlot(page, recipeSlot0, ".", bobMath);
-
-  await pause(160, 240);
-
-  // Mid-cycle agent action: Bob asks his own chat to add a proper
-  // bibliographic citation of the Vaswani 2017 paper right after
-  // his definition sentence. The chat dispatches a `citation`
-  // tool call: the entry is written to the shared `citationsMap`,
-  // a citation node lands at the caret (currently at the end of
-  // slot 0), and the Bibliography section materializes at the
-  // bottom of the doc the first time. Shows off the real academic-
-  // writing workflow on camera (chip renders as `(Vaswani et al.,
-  // 2017)` in APA).
-  try {
-    await pause(220, 340);
-    await requestCitationAction(page, {
-      prompt: "Cite the original Vaswani 2017 paper here.",
-      reply: "Added [Vaswani et al., 2017] and the bibliography section.",
-      paragraphSnippet: "Attention lets a token",
-      anchor: "end",
-      key: "vaswani2017attention",
-      entry: {
-        id: "vaswani2017attention",
-        "citation-key": "vaswani2017attention",
-        type: "article-journal",
-        title: "Attention Is All You Need",
-        author: [
-          { family: "Vaswani", given: "Ashish" },
-          { family: "Shazeer", given: "Noam" },
-          { family: "Parmar", given: "Niki" },
-          { family: "Uszkoreit", given: "Jakob" },
-          { family: "Jones", given: "Llion" },
-          { family: "Gomez", given: "Aidan N." },
-          { family: "Kaiser", given: "Lukasz" },
-          { family: "Polosukhin", given: "Illia" },
-        ],
-        issued: { "date-parts": [[2017]] },
-        "container-title": "Advances in Neural Information Processing Systems",
-        volume: "30",
-        URL: "https://arxiv.org/abs/1706.03762",
-        DOI: "10.48550/arXiv.1706.03762",
-      },
-      speed,
-    });
-    await pause(260, 420);
-  } catch (err) {
-    console.warn(
-      "[bob] citation action aborted:",
-      err instanceof Error ? err.message : err,
-    );
-  }
+  await insertInlineNode(slot0, { type: "inlineMath", latex: "Q" }, 200, bob);
+  await typeIntoParagraph(slot0, ", keys ", { cps: bodyCps }, undefined, bob);
+  await insertInlineNode(slot0, { type: "inlineMath", latex: "K" }, 160, bob);
+  await typeIntoParagraph(
+    slot0,
+    " and values ",
+    { cps: bodyCps },
+    undefined,
+    bob,
+  );
+  await insertInlineNode(slot0, { type: "inlineMath", latex: "V" }, 160, bob);
+  await typeIntoParagraph(slot0, ".", { cps: bodyCps }, undefined, bob);
 
-  await pause(160, 240);
-
-  // Slot 1: canonical block-math formula. The $$$...$$$ input rule
-  // converts the empty <p> into a math node in place; the slot
-  // position tracks that conversion through the Y.js mapping.
-  const recipeSlot1 = await claimSlot(page, "The recipe", 1);
-  if (recipeSlot1) {
-    await pause(60, 120);
-    await typeInSlot(
-      page,
-      recipeSlot1,
-      "$$$\\text{Attention}(Q, K, V) = \\text{softmax}\\left(\\frac{QK^\\top}{\\sqrt{d_k}}\\right)V$$$",
-      bobMath,
-    );
+  await sleep(jitter(240, 400));
+
+  // 4) Citation + bibliography -----------------------------------
+  // Register the entry in the shared Y.Map("citations"). The
+  // frontend's citation NodeView listens on that map, so any chip
+  // with matching `key` auto-resolves its label from the entry.
+  //
+  // We still write the `label` attr ourselves so the chip renders
+  // "(Vaswani et al., 2017)" as soon as it lands even if the
+  // NodeView observer hasn't fired yet (APA-ish placeholder).
+  const citationKey = "vaswani2017attention";
+  registerCitation(bob, citationKey, {
+    id: citationKey,
+    "citation-key": citationKey,
+    type: "article-journal",
+    title: "Attention Is All You Need",
+    author: [
+      { family: "Vaswani", given: "Ashish" },
+      { family: "Shazeer", given: "Noam" },
+      { family: "Parmar", given: "Niki" },
+      { family: "Uszkoreit", given: "Jakob" },
+      { family: "Jones", given: "Llion" },
+      { family: "Gomez", given: "Aidan N." },
+      { family: "Kaiser", given: "Lukasz" },
+      { family: "Polosukhin", given: "Illia" },
+    ],
+    issued: { "date-parts": [[2017]] },
+    "container-title": "Advances in Neural Information Processing Systems",
+    volume: "30",
+    URL: "https://arxiv.org/abs/1706.03762",
+    DOI: "10.48550/arXiv.1706.03762",
+  });
+  appendInline(slot0, [
+    {
+      type: "citation",
+      key: citationKey,
+      label: "(Vaswani et al., 2017)",
+    },
+  ]);
+  broadcastCursorAtEnd(bob, slot0);
+  ensureBibliographySection(bob);
+  console.log("[bob] citation + bibliography inserted");
+
+  await sleep(jitter(320, 520));
+
+  // 5) Slot 1 - block math (the attention formula) --------------
+  // Atomic CRDT replace: the empty scaffold paragraph is swapped
+  // for a `<blockMath>` atom carrying the canonical scaled-dot-
+  // product-attention formula. Alice sees the KaTeX render pop
+  // in the moment the sync hits her editor - crisp "another
+  // agent dropped an equation" moment on camera. Short beat
+  // before and after so the viewer registers the transition
+  // from prose to display math.
+  await sleep(jitter(220, 380));
+  const mathNode = writeBlockMathAtSlot(
+    bob.fragment,
+    "The recipe",
+    1,
+    "\\text{Attention}(Q, K, V) = \\text{softmax}\\!\\left(\\frac{QK^\\top}{\\sqrt{d_k}}\\right) V",
+  );
+  if (mathNode) {
+    console.log("[bob] block math equation inserted");
+  } else {
+    console.warn("[bob] could not insert block math");
   }
+  await sleep(jitter(320, 500));
 
-  await pause(140, 240);
-
-  // Slot 2: softmax explanation. Short, punchy, ties the formula
-  // back to the definition.
-  const recipeSlot2 = await claimSlot(page, "The recipe", 2);
-  if (recipeSlot2) {
-    await pause(60, 120);
-    await typeInSlot(
-      page,
-      recipeSlot2,
-      "The softmax turns those scores into weights, and the weighted sum over values produces one contextual vector per token.",
-      { speed: speed * 2.2, typoRate: 0, thinkRate: 0.01 },
+  // 6) Slot 2 - softmax explanation ------------------------------
+  const slot2 = claimSlotAfterHeading(bob.fragment, "The recipe", 2);
+  if (slot2) {
+    await sleep(jitter(80, 150));
+    await typeIntoParagraph(
+      slot2,
+      "The softmax turns those similarity scores into weights, and the weighted sum over values produces one contextual vector per token.",
+      { cps: fastCps, chunkSize: 2 },
+      undefined,
+      bob,
     );
+  } else {
+    console.warn("[bob] could not locate slot 2");
   }
 
-  await pause(140, 220);
-
-  // Slot 3: multi-head teaser. Closes the section on a forward
-  // pointer to the next chapter (multi-head attention = same
-  // operation run in parallel with independent projections). Keeps
-  // Bob visibly typing during Alice's rephrase + hue drag phase and
-  // gives "The recipe" a proper four-paragraph body instead of
-  // stopping right after the formula.
-  const recipeSlot3 = await claimSlot(page, "The recipe", 3);
-  if (recipeSlot3) {
-    await pause(60, 120);
-    await typeInSlot(
-      page,
-      recipeSlot3,
+  await sleep(jitter(200, 320));
+
+  // 7) Slot 3 - multi-head teaser --------------------------------
+  const slot3 = claimSlotAfterHeading(bob.fragment, "The recipe", 3);
+  if (slot3) {
+    await sleep(jitter(80, 150));
+    await typeIntoParagraph(
+      slot3,
       "In practice the same operation runs in parallel through several independent projections, one per head, and the outputs are concatenated - that is multi-head attention.",
-      { speed: speed * 2.2, typoRate: 0, thinkRate: 0.01 },
+      { cps: fastCps, chunkSize: 2 },
+      undefined,
+      bob,
     );
+  } else {
+    console.warn("[bob] could not locate slot 3");
   }
 
-  await pause(180, 300);
-
+  await sleep(jitter(200, 320));
+  // Clear Bob's caret so it doesn't linger past the last paragraph
+  // he wrote; Alice gets a clean frame for the hue drag / publish.
+  clearAwarenessCursor(bob);
   console.log("[bob] scenario complete");
 }

backend/demo/carol.ts

@@ -1,145 +1,252 @@
 /**
- * Carol - headless collaborator for the showcase demo.
+ * Carol - Yjs-only collaborator for the showcase demo.
  *
- * Carol owns the "In Python" section (bottom of doc). Her flow:
- *   1. Wait for Alice's first author, then append a Stanford
- *      co-author.
- *   2. Wait for the "In Python" heading scaffold.
- *   3. Type the narrated intro line in slot 0.
- *   4. Fire a link action through the chat on "PyTorch" -
- *      pointing at the concrete `scaled_dot_product_attention`
- *      docs. This is the counterpart to Bob's citation at the
- *      top of the article.
- *   5. Drop an 8-line PyTorch code block in slot 1 via the
- *      ```python input rule.
- *   6. Close with a Vaswani reference line in slot 2.
+ * Carol is a Node-side Yjs peer (no browser). She owns the "In
+ * Python" section at the bottom of the doc.
+ *
+ * Flow:
+ *   1. Wait for Alice's first author to land, then append herself
+ *      with a Stanford affiliation.
+ *   2. Wait for the "In Python" H2 to appear in the shared
+ *      fragment (Alice writes the scaffold).
+ *   3. Fill slot 0 with a narrated intro line and splice a link
+ *      mark directly onto the word "PyTorch" so it points at the
+ *      `scaled_dot_product_attention` docs.
+ *   4. Replace slot 1 with a `<codeBlock language="python">` node
+ *      carrying the 8-line reference implementation.
+ *   5. Fill slot 2 with the closing paragraph.
  */
-import type { Page } from "playwright";
-import { pause } from "./human-typing.js";
-import { addAuthor, insertCodeBlock } from "./lib/editor-actions.js";
-import { requestLinkAction } from "./lib/chat-actions.js";
-import {
-  clearAgentFocus,
-  selectSubstringInParagraph,
-} from "./lib/selection.js";
-import {
-  claimSlot,
-  installPositionTracker,
-  typeInSlot,
-} from "./lib/positions.js";
+import * as Y from "yjs";
 import {
-  focusNthParagraphInSection,
-  waitForHeading2,
-} from "./lib/scaffolding.js";
-
-export async function runCarol(page: Page, speed: number) {
-  console.log("[carol] joined, will add a Stanford co-author then code");
-  await installPositionTracker(page);
-  await pause(1_200, 1_800);
-
-  // Authors: like Bob, Carol waits for Alice's first author to be
-  // synced (signalled by the "+" icon button replacing the empty
-  // placeholder), then appends herself with a third distinct
-  // affiliation. Running this here (not after the heading wait)
-  // means the byline is fully populated before the body is written,
-  // and the three modals openings are staggered across Alice / Bob /
-  // Carol for a natural collaborative rhythm on camera.
-  try {
-    await page
-      .locator('button.icon-btn[aria-label="Add author"]')
-      .first()
-      .waitFor({ state: "visible", timeout: 30_000 });
-  } catch {
+  addAuthorRecord,
+  broadcastCursorAtEnd,
+  buildEmptyParagraph,
+  claimSlotAfterHeading,
+  clearAwarenessCursor,
+  findHeadingIndex,
+  setAwarenessCursor,
+  sleep,
+  typeIntoParagraph,
+  waitForAuthorCount,
+  waitForCondition,
+  type PersonaHandle,
+} from "./lib/yjs-client.js";
+
+function jitter(minMs: number, maxMs: number): number {
+  return minMs + Math.random() * (maxMs - minMs);
+}
+
+/**
+ * Apply a `link` mark to the FIRST occurrence of `substring` inside
+ * a paragraph's Y.XmlText children. We iterate children in document
+ * order and, when we find the substring (possibly straddling two
+ * adjacent text runs), re-emit it with the link attributes instead
+ * of trying to mutate a mark in place (Y.XmlText's format API is
+ * append-only friendly; retrofitting a mark mid-string is what
+ * caused the old Playwright link flow to drift the caret).
+ */
+function linkifyInParagraph(
+  paragraph: Y.XmlElement,
+  substring: string,
+  href: string,
+): boolean {
+  const children = paragraph.toArray();
+  for (let i = 0; i < children.length; i++) {
+    const child = children[i];
+    if (!(child instanceof Y.XmlText)) continue;
+    const text = child.toString();
+    const idx = text.indexOf(substring);
+    if (idx === -1) continue;
+
+    // Slice the run into [before, linked, after] and re-emit the
+    // middle with link attributes. `delta`-level insertion lets us
+    // mint all three in a single Yjs op so the formatter doesn't
+    // see intermediate half-linked states.
+    const before = text.slice(0, idx);
+    const after = text.slice(idx + substring.length);
+    paragraph.doc?.transact(() => {
+      child.delete(0, text.length);
+      if (before) child.insert(0, before);
+      child.insert(before.length, substring, {
+        link: {
+          href,
+          target: "_blank",
+          rel: "noopener noreferrer nofollow",
+          class: "editor-link",
+          title: null,
+        },
+      });
+      if (after) child.insert(before.length + substring.length, after);
+    });
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Replace the paragraph at fragment index `slotIndex` within a
+ * section with an empty codeBlock node, ready for streaming inserts.
+ * Returns the Y.XmlText child so the caller can type into it at
+ * whatever cadence they want.
+ *
+ * Splitting the "create codeBlock shell" from "type code into it"
+ * lets the viewer actually SEE the code materialize line by line
+ * instead of popping in atomically, which is what made the old
+ * `writeCodeBlock` look unnatural on camera.
+ */
+function openCodeBlock(
+  frag: Y.XmlFragment,
+  headingText: string,
+  slotIndex: number,
+  language: string,
+): Y.XmlText | null {
+  const headingIdx = findHeadingIndex(frag, headingText);
+  if (headingIdx === -1) return null;
+
+  // Walk from the heading forward, collecting slot positions.
+  const children = frag.toArray();
+  const slots: number[] = [];
+  for (let i = headingIdx + 1; i < children.length; i++) {
+    const c = children[i];
+    if (!(c instanceof Y.XmlElement)) continue;
+    if (c.nodeName === "heading") break;
+    slots.push(i);
+  }
+  const targetIdx =
+    slots[slotIndex] ??
+    (slots.length ? slots[slots.length - 1] + 1 : headingIdx + 1);
+
+  const block = new Y.XmlElement("codeBlock");
+  let txt: Y.XmlText | null = null;
+
+  frag.doc?.transact(() => {
+    if (slots[slotIndex] !== undefined) {
+      frag.delete(targetIdx, 1);
+      frag.insert(targetIdx, [block]);
+    } else {
+      const pad = slotIndex - slots.length;
+      const filler: Y.XmlElement[] = [];
+      for (let k = 0; k < pad; k++) filler.push(buildEmptyParagraph());
+      filler.push(block);
+      frag.insert(targetIdx, filler);
+    }
+    block.setAttribute("language", language);
+    txt = new Y.XmlText();
+    block.push([txt]);
+  });
+  return txt;
+}
+
+/**
+ * Stream `code` into a codeBlock's Y.XmlText at a human pace. Each
+ * chunk is a real Yjs insert with an awareness cursor ping (via
+ * `setAwarenessCursor`), so Alice sees Carol's caret walk down the
+ * source file as it fills in - the same look-and-feel as typing
+ * into a paragraph.
+ *
+ * Characters per second is tuned per language:
+ *   - prose   : 24-38 cps (fingers typing English)
+ *   - code    : 60-90 cps (humans "think in tokens" for code and
+ *               paste / autocomplete reduces effective keystrokes)
+ * so the code fills fast enough to stay on-camera without looking
+ * like the block popped in instantly.
+ */
+async function typeIntoCodeBlock(
+  handle: PersonaHandle,
+  txt: Y.XmlText,
+  code: string,
+  options: { cps?: number; chunkSize?: number; jitter?: number } = {},
+): Promise<void> {
+  const cps = options.cps ?? 80;
+  const jitter = options.jitter ?? 0.3;
+  const chunkSize = Math.max(1, options.chunkSize ?? 3);
+  const baseDelay = 1000 / cps;
+
+  let i = 0;
+  while (i < code.length) {
+    const take = Math.min(chunkSize, code.length - i);
+    const chunk = code.slice(i, i + take);
+    txt.insert(txt.length, chunk);
+    setAwarenessCursor(handle, txt, txt.length);
+    i += take;
+    const jitterMul = 1 + (Math.random() * 2 - 1) * jitter;
+    await sleep(Math.max(3, baseDelay * jitterMul));
+  }
+}
+
+export async function runCarol(
+  carol: PersonaHandle,
+  speed: number,
+): Promise<void> {
+  console.log("[carol] connected as Yjs peer, waiting for Alice's first author");
+
+  // Slight offset vs Bob's join so the two author pushes don't
+  // stack on top of each other in Alice's byline on camera.
+  await sleep(jitter(1_200, 1_800));
+
+  // 1) Authors ---------------------------------------------------
+  const seeded = await waitForAuthorCount(carol, 1, 30_000);
+  if (!seeded) {
     console.warn("[carol] Alice's first author never appeared, proceeding");
   }
-  await pause(400, 700);
+  await sleep(jitter(400, 700));
 
-  await addAuthor(page, "Carol Dubois", speed, {
-    newAffiliation: "Stanford University",
+  addAuthorRecord(carol, {
+    name: "Carol Dubois",
+    newAffiliation: { name: "Stanford University" },
   });
   console.log("[carol] author added");
 
-  // Wait for Alice's scaffold to ship the "In Python" heading (and
-  // its three pre-allocated slots), then fill slots 0 / 1 / 2 in
-  // sequence. Carol never presses Enter during the parallel phase:
-  // jumping between pre-allocated slots via
-  // focusNthParagraphInSection is what avoids the previous overlap
-  // bug where her ```python code fence would occasionally absorb
-  // stray text from Bob or Alice mid-typing.
-  try {
-    await waitForHeading2(page, "In Python", 60_000);
-  } catch {
-    console.warn("[carol] 'In Python' heading not found, skipping section");
+  // 2) Wait for scaffold ----------------------------------------
+  const hasHeading = await waitForCondition(
+    carol.fragment,
+    () => findHeadingIndex(carol.fragment, "In Python") !== -1,
+    60_000,
+  );
+  if (!hasHeading) {
+    console.warn("[carol] 'In Python' heading never arrived, skipping body");
     return;
   }
-  await pause(150, 300);
+  await sleep(jitter(150, 300));
+
+  const fastCps = 50 / Math.max(0.5, speed / 2);
 
-  // Slot 0: narrated intro line. Anchored so Alice/Bob typing in
-  // parallel can't push Carol's caret out of her own paragraph.
-  const pythonSlot0 = await claimSlot(page, "In Python", 0);
-  if (!pythonSlot0) {
-    console.warn("[carol] could not focus slot 0 of 'In Python'");
+  // 3) Slot 0 - intro line + link on "PyTorch" ------------------
+  const slot0 = claimSlotAfterHeading(carol.fragment, "In Python", 0);
+  if (!slot0) {
+    console.warn("[carol] could not locate slot 0 of 'In Python'");
     return;
   }
-  await pause(80, 160);
-  await typeInSlot(
-    page,
-    pythonSlot0,
+  await sleep(jitter(80, 150));
+  await typeIntoParagraph(
+    slot0,
     "The whole recipe fits in eight lines of PyTorch:",
-    { speed: speed * 2.5, typoRate: 0, thinkRate: 0.01 },
+    { cps: fastCps, chunkSize: 2 },
+    undefined,
+    carol,
   );
+  await sleep(jitter(160, 260));
 
-  await pause(160, 240);
-
-  // Mid-cycle agent action: Carol points at the concrete PyTorch
-  // reference BEFORE she even writes the code, so when the snippet
-  // lands under the paragraph it already feels grounded. The link
-  // goes to PyTorch's own scaled_dot_product_attention docs (the
-  // fused, production-grade implementation of what the snippet
-  // below does by hand). Bottom-of-article link, distinct spot and
-  // distinct target from Bob's top-of-article arXiv citation.
-  try {
-    const linkRange = await selectSubstringInParagraph(
-      page,
-      "The whole recipe",
-      "PyTorch",
-    );
-    if (linkRange) {
-      await pause(220, 360);
-      await requestLinkAction(page, {
-        prompt: "Link to the PyTorch attention docs.",
-        reply:
-          "Pointed at torch.nn.functional.scaled_dot_product_attention.",
-        url:
-          "https://pytorch.org/docs/stable/generated/torch.nn.functional.scaled_dot_product_attention.html",
-        speed,
-        paragraphSnippet: "The whole recipe",
-        substring: "PyTorch",
-      });
-      await pause(260, 420);
-      await clearAgentFocus(page);
-    }
-  } catch (err) {
-    console.warn(
-      "[carol] link action aborted:",
-      err instanceof Error ? err.message : err,
-    );
+  const linked = linkifyInParagraph(
+    slot0,
+    "PyTorch",
+    "https://pytorch.org/docs/stable/generated/torch.nn.functional.scaled_dot_product_attention.html",
+  );
+  broadcastCursorAtEnd(carol, slot0);
+  if (!linked) {
+    console.warn("[carol] could not apply PyTorch link mark");
+  } else {
+    console.log("[carol] PyTorch link inserted");
   }
 
-  await pause(120, 200);
-
-  // Slot 1: the code block. We DON'T anchor here - the ```python
-  // input rule transforms the <p> into a <pre><code> node, and any
-  // MappablePosition created against the old empty paragraph stops
-  // being meaningful. We just focus the slot and let PM manage
-  // selection internally while Carol fills the code.
-  const codeFocused = await focusNthParagraphInSection(page, "In Python", 1);
-  if (!codeFocused) {
-    console.warn("[carol] could not focus slot 1 of 'In Python'");
-    return;
-  }
-  await pause(80, 160);
+  await sleep(jitter(180, 300));
 
+  // 4) Slot 1 - 8-line code block -------------------------------
+  // Open an empty codeBlock first so Alice sees the "frame" land
+  // (with the language tag), then stream the code line by line at
+  // a human coding cadence. The atomic "whole block pops in" feel
+  // is replaced by a visible tap-tap-tap typing animation that
+  // matches the other paragraphs.
   const code =
     "import torch\n" +
     "import torch.nn.functional as F\n" +
@@ -149,26 +256,36 @@ export async function runCarol(page: Page, speed: number) {
     "    scores = Q @ K.transpose(-2, -1) / d_k ** 0.5\n" +
     "    weights = F.softmax(scores, dim=-1)\n" +
     "    return weights @ V";
-  await insertCodeBlock(page, "python", code, speed);
-
-  // Slot 2: closing reference paragraph AFTER the code block.
-  // Claimed fresh so we get a clean MappablePosition past the code
-  // node.
-  const pythonSlot2 = await claimSlot(page, "In Python", 2);
-  if (!pythonSlot2) {
-    console.warn("[carol] could not focus slot 2 of 'In Python'");
-    console.log("[carol] scenario complete (partial)");
-    return;
+  const codeTxt = openCodeBlock(carol.fragment, "In Python", 1, "python");
+  if (!codeTxt) {
+    console.warn("[carol] could not open code block");
+  } else {
+    console.log("[carol] code block opened, streaming source...");
+    const codeCps = 70 / Math.max(0.5, speed / 2);
+    await typeIntoCodeBlock(carol, codeTxt, code, {
+      cps: codeCps,
+      chunkSize: 3,
+    });
+    console.log("[carol] code block complete");
   }
-  await pause(80, 160);
-  await typeInSlot(
-    page,
-    pythonSlot2,
-    "Every modern LLM you have used runs some flavor of this snippet - fused, batched and tiled on the GPU, but conceptually the same eight lines.",
-    { speed: speed * 2.5, typoRate: 0, thinkRate: 0.01 },
-  );
+  await sleep(jitter(300, 480));
 
-  await pause(180, 280);
+  // 5) Slot 2 - closing paragraph -------------------------------
+  const slot2 = claimSlotAfterHeading(carol.fragment, "In Python", 2);
+  if (slot2) {
+    await sleep(jitter(80, 160));
+    await typeIntoParagraph(
+      slot2,
+      "Every modern LLM you have used runs some flavor of this snippet - fused, batched and tiled on the GPU, but conceptually the same eight lines.",
+      { cps: fastCps, chunkSize: 2 },
+      undefined,
+      carol,
+    );
+  } else {
+    console.warn("[carol] could not locate slot 2");
+  }
 
+  await sleep(jitter(200, 320));
+  clearAwarenessCursor(carol);
   console.log("[carol] scenario complete");
 }

backend/demo/human-typing.ts

@@ -9,6 +9,7 @@
  * person writing", not deterministic test output.
  */
 import type { Page, Locator } from "playwright";
+import { humanClick } from "./lib/mouse-cursor.js";
 
 export interface HumanTypingOptions {
   /** Baseline delay between keystrokes (ms). Actual delay is jittered. */
@@ -141,7 +142,7 @@ export async function humanTypeInto(
   options: HumanTypingOptions = {}
 ): Promise<void> {
   await target.waitFor({ state: "visible" });
-  await target.click();
+  await humanClick(page, target);
   await sleep(rand(250, 550));
   await humanType(page, text, options);
 }

backend/demo/lib/chat-actions.ts

@@ -33,8 +33,10 @@
  */
 import type { Page } from "playwright";
 import { humanType, pause } from "../human-typing.js";
+import { humanClick, humanHover } from "./mouse-cursor.js";
 import {
   clearAgentFocus,
+  dragSelectSubstringInParagraph,
   getCurrentPmSelection,
   selectSubstringInParagraph,
 } from "./selection.js";
@@ -69,6 +71,20 @@ export async function streamFakeExchange(
        * silently fails. See `App.tsx` `__demo-chat` handler.
        */
       range?: { from: number; to: number };
+      /**
+       * "none" for atomic swap (reads as AI edit), "typewriter" for
+       * streamed chars (reads as user typing). Default typewriter
+       * to match the original demo's behaviour.
+       */
+      animation?: "none" | "typewriter";
+      /**
+       * Keep the AgentFocus highlight on the replacement range for
+       * `lingerAgentFocusMs` after the swap, then clear. Lets the
+       * viewer see the "<Name> agent" label sit over the new
+       * sentence instead of the decoration collapsing at delete
+       * time.
+       */
+      lingerAgentFocusMs?: number;
     };
     /**
      * Optional formatting action: after the assistant reply has fully
@@ -250,10 +266,11 @@ async function openChatAndTypePrompt(
   page: Page,
   prompt: string,
   speed: number,
+  opts: { onPanelOpen?: () => Promise<void> } = {},
 ) {
   const fab = page.getByRole("button", { name: /AI Assistant/i }).first();
   if (await fab.isVisible().catch(() => false)) {
-    await fab.click();
+    await humanClick(page, fab);
     await pause(220, 380);
   }
 
@@ -262,7 +279,21 @@ async function openChatAndTypePrompt(
     .first();
   try {
     await textarea.waitFor({ state: "visible", timeout: 3_000 });
-    await textarea.click();
+    // Panel is now open. Callers (requestRephraseAction) can fire
+    // a callback here so side-effects that should read as "triggered
+    // by opening the chat" - the AgentFocus highlight in particular
+    // - land at the exact frame the panel becomes visible.
+    if (opts.onPanelOpen) {
+      try {
+        await opts.onPanelOpen();
+      } catch (err) {
+        console.warn(
+          "[chat] onPanelOpen hook failed:",
+          err instanceof Error ? err.message : err,
+        );
+      }
+    }
+    await humanClick(page, textarea);
     await humanType(page, prompt, {
       speed: speed * 2.2,
       typoRate: 0,
@@ -271,6 +302,16 @@ async function openChatAndTypePrompt(
     await pause(100, 180);
   } catch {
     console.warn("[chat] textarea not found, will inject anyway");
+    // Fallback: the panel never actually opened visually. Run the
+    // hook anyway so the highlight still appears (better than silent
+    // skip if tippy/panel layout shifted mid-demo).
+    if (opts.onPanelOpen) {
+      try {
+        await opts.onPanelOpen();
+      } catch {
+        /* non-fatal */
+      }
+    }
   }
   try {
     await textarea.fill("");
@@ -354,9 +395,63 @@ export async function requestRephraseAction(
     to: string;
     range?: { from: number; to: number };
     speed: number;
+    /**
+     * "none" = atomic swap, the phrase flips in one transaction and
+     * the AgentFocus decoration carries over to the new range - the
+     * viewer unambiguously reads it as an AI edit.
+     *
+     * "typewriter" = stream chars one by one. Looks like Alice is
+     * typing herself, which defeats the purpose of showing an agent
+     * tool call - avoid unless you explicitly want that effect.
+     *
+     * Default: "none".
+     */
+    animation?: "none" | "typewriter";
+    /**
+     * How long the AgentFocus highlight lingers on the new sentence
+     * after the swap before clearing. Default 1400ms - long enough
+     * for the viewer to read the new text under the agent badge,
+     * short enough to not stall the recording.
+     */
+    lingerAgentFocusMs?: number;
   },
 ) {
-  await openChatAndTypePrompt(page, args.prompt, args.speed);
+  const animation = args.animation ?? "none";
+  const lingerAgentFocusMs = args.lingerAgentFocusMs ?? 1400;
+
+  // Story beat: Alice FIRST selects the target sentence herself
+  // (visible drag-glide + PM selection paint), pauses so the viewer
+  // registers "this is the phrase I want to work on", THEN opens
+  // the chat. Without this visible selection, the agent highlight
+  // appears "out of nowhere" when the panel opens, which reads as
+  // unexplained magic.
+  //
+  // Note: we pass setAgentFocus=false here - the user selection
+  // should look like a regular user selection (no "<Name> agent"
+  // label yet). The label appears shortly after when the chat
+  // actually opens and onPanelOpen fires below, visually
+  // transforming the user selection into an agent-scoped range.
+  await dragSelectSubstringInParagraph(
+    page,
+    args.from,
+    args.from,
+    { setAgentFocus: false },
+  );
+  await pause(420, 620);
+
+  // Timing rule: the AgentFocus highlight upgrades the user's
+  // selection to an agent-scoped range at the exact frame the chat
+  // panel becomes visible. openChatAndTypePrompt fires onPanelOpen
+  // between "panel is open" and "prompt starts typing" so the
+  // label pops in sync with the chat UI, not 3 seconds before.
+  await openChatAndTypePrompt(page, args.prompt, args.speed, {
+    onPanelOpen: async () => {
+      await seedAgentFocusOnTarget(page, {
+        targetText: args.from,
+        explicitRange: args.range,
+      });
+    },
+  });
 
   await streamFakeExchange(page, {
     eventName: "__demo-chat",
@@ -367,10 +462,131 @@ export async function requestRephraseAction(
       from: args.from,
       to: args.to,
       range: args.range,
+      animation,
+      lingerAgentFocusMs,
     },
   });
 }
 
+/**
+ * Resolve the PM range for a rephrase target against the LIVE doc
+ * and broadcast an AgentFocus highlight on it. Mirrors the lookup
+ * the App-side `__demo-chat` handler does at dispatch time
+ * (explicit range first, text-search fallback) so the highlight
+ * lands on the EXACT same characters the typewriter will rewrite
+ * a couple hundred ms later. If neither resolution path matches
+ * (e.g. Bob just typed into the target paragraph and rebased the
+ * text), the helper silently skips - the typewriter itself will
+ * still find the range from its own live lookup.
+ */
+async function seedAgentFocusOnTarget(
+  page: Page,
+  args: {
+    targetText: string;
+    explicitRange?: { from: number; to: number };
+  },
+): Promise<void> {
+  await page.evaluate(
+    ({ target, explicit }) => {
+      const editor = (
+        window as unknown as {
+          __demoEditor?: {
+            state: {
+              doc: {
+                content: { size: number };
+                descendants: (
+                  cb: (
+                    node: {
+                      isTextblock: boolean;
+                      content: { size: number };
+                      textBetween: (
+                        a: number,
+                        b: number,
+                        s1: string,
+                        s2: string,
+                      ) => string;
+                    },
+                    pos: number,
+                  ) => boolean | void,
+                ) => void;
+              };
+            };
+            commands: {
+              setAgentFocus: (args: { from: number; to: number }) => boolean;
+            };
+            view: {
+              domAtPos: (pos: number) => { node: Node };
+            };
+          };
+        }
+      ).__demoEditor;
+      if (!editor) return;
+
+      let from = -1;
+      let to = -1;
+
+      if (explicit) {
+        const size = editor.state.doc.content.size;
+        const a = Math.max(0, Math.min(explicit.from, size));
+        const b = Math.max(0, Math.min(explicit.to, size));
+        if (b > a) {
+          from = a;
+          to = b;
+        }
+      }
+
+      if (from === -1) {
+        editor.state.doc.descendants((node, pos) => {
+          if (from !== -1) return false;
+          if (node.isTextblock) {
+            const text = node.textBetween(
+              0,
+              node.content.size,
+              "\n",
+              "\n",
+            );
+            const idx = text.indexOf(target);
+            if (idx !== -1) {
+              from = pos + 1 + idx;
+              to = from + target.length;
+              return false;
+            }
+          }
+          return true;
+        });
+      }
+
+      if (from === -1 || to === -1) return;
+
+      // Scroll the target paragraph into view so the highlight is
+      // on-camera when the chat panel reply starts streaming.
+      try {
+        const domAt = editor.view.domAtPos(from);
+        let el: HTMLElement | null =
+          domAt.node instanceof HTMLElement
+            ? domAt.node
+            : (domAt.node as Node).parentElement;
+        while (
+          el &&
+          el.nodeName !== "P" &&
+          !/^H[1-6]$/.test(el.nodeName)
+        ) {
+          el = el.parentElement;
+        }
+        el?.scrollIntoView({ behavior: "smooth", block: "center" });
+      } catch {
+        /* non-fatal */
+      }
+
+      editor.commands.setAgentFocus({ from, to });
+    },
+    {
+      target: args.targetText,
+      explicit: args.explicitRange,
+    },
+  );
+}
+
 /**
  * Twin of `requestFormatAction`, but for link insertion.
  *
@@ -537,7 +753,9 @@ export async function bubbleToolbarBold(
   // dance a couple of times before giving up, with an explicit
   // `editor.commands.focus()` each pass to re-assert ownership of
   // the caret against remote transactions.
-  const seedSelection = async (): Promise<{
+  const seedSelection = async (
+    attempt: number,
+  ): Promise<{
     from: number;
     to: number;
   } | null> => {
@@ -549,6 +767,21 @@ export async function bubbleToolbarBold(
       ).__demoEditor;
       editor?.commands.focus();
     });
+    // First attempt: animate a real mouse drag across the target
+    // phrase so the viewer SEES Alice select the text (cursor glides
+    // over the words while the selection paint follows). Subsequent
+    // retries fall back to the purely programmatic path - we don't
+    // want to loop dragging if concurrent Yjs sync keeps shifting
+    // the text under us, the programmatic selection is rock solid
+    // on exact PM positions.
+    if (attempt === 0) {
+      const dragged = await dragSelectSubstringInParagraph(
+        page,
+        paragraphSnippet,
+        substring,
+      );
+      if (dragged) return dragged;
+    }
     return await selectSubstringInParagraph(
       page,
       paragraphSnippet,
@@ -563,7 +796,7 @@ export async function bubbleToolbarBold(
   let range: { from: number; to: number } | null = null;
   let toolbarReady = false;
   for (let attempt = 0; attempt < 3; attempt++) {
-    range = await seedSelection();
+    range = await seedSelection(attempt);
     if (!range) {
       await pause(180, 280);
       continue;
@@ -627,13 +860,13 @@ export async function bubbleToolbarBold(
 
   const [hoverMin, hoverMax] = opts.hoverMs ?? [380, 620];
   try {
-    await boldBtn.hover();
+    await humanHover(page, boldBtn);
   } catch {
     /* non-fatal */
   }
   await pause(hoverMin, hoverMax);
   try {
-    await boldBtn.click({ force: true });
+    await humanClick(page, boldBtn);
   } catch (err) {
     console.warn(
       "[bubble-bold] click failed:",

backend/demo/lib/chromium.ts

@@ -22,6 +22,7 @@ import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { FALLBACK_USER_KEY, type Persona } from "../personas.js";
+import { injectMouseCursor, verifyMouseCursor } from "./mouse-cursor.js";
 
 export interface PersonaHandle {
   browser: Browser;
@@ -131,6 +132,12 @@ export async function launchPersona(
       ignoreDefaultArgs: IGNORE_DEFAULT_ARGS,
     });
 
+    // Draw a visible mouse pointer on Alice's recorded window. Needs
+    // to run before the first nav so the overlay is live for the
+    // boot and every in-page navigation (e.g. opening the published
+    // article).
+    await injectMouseCursor(context);
+
     // Inject persona identity for any future navigation. The first --app
     // load already happened, so we set localStorage on the live page and
     // then reload once to get a clean boot under the persona identity.
@@ -163,6 +170,13 @@ export async function launchPersona(
     await page.reload({ waitUntil: "domcontentloaded", timeout: 20_000 });
     await page.waitForSelector("[aria-label='Undo']", { timeout: 25_000 });
 
+    const cursorMounted = await verifyMouseCursor(page);
+    console.log(
+      cursorMounted
+        ? "[showcase] mouse cursor overlay mounted"
+        : "[showcase] WARN: mouse cursor overlay did NOT mount",
+    );
+
     // Wrap context.close() into the same Browser-shaped object the rest of
     // the script expects so we don't have to branch on close everywhere.
     const browser = {
@@ -209,6 +223,8 @@ export async function launchPersona(
       : { viewport: { width: 1280, height: 800 }, deviceScaleFactor: 2 },
   );
 
+  await injectMouseCursor(context);
+
   await context.addInitScript(
     ({ key, value }) => {
       try {
@@ -230,6 +246,13 @@ export async function launchPersona(
   await page.goto(url, { waitUntil: "domcontentloaded", timeout: 20_000 });
   await page.waitForSelector("[aria-label='Undo']", { timeout: 25_000 });
 
+  const cursorMounted = await verifyMouseCursor(page);
+  console.log(
+    cursorMounted
+      ? "[showcase] mouse cursor overlay mounted"
+      : "[showcase] WARN: mouse cursor overlay did NOT mount",
+  );
+
   return { browser, context, page };
 }
 

backend/demo/lib/editor-actions.ts

@@ -11,6 +11,7 @@
  */
 import type { Page } from "playwright";
 import { humanType, pause } from "../human-typing.js";
+import { humanClick } from "./mouse-cursor.js";
 
 /**
  * Move the caret to the very end of the ProseMirror editor, regardless
@@ -118,12 +119,12 @@ export async function addAuthor(
   if (await placeholderTrigger.first().isVisible().catch(() => false)) {
     await placeholderTrigger.first().scrollIntoViewIfNeeded();
     await pause(80, 160);
-    await placeholderTrigger.first().click();
+    await humanClick(page, placeholderTrigger.first());
     opened = true;
   } else if (await iconTrigger.first().isVisible().catch(() => false)) {
     await iconTrigger.first().scrollIntoViewIfNeeded();
     await pause(80, 160);
-    await iconTrigger.first().click();
+    await humanClick(page, iconTrigger.first());
     opened = true;
   }
   if (!opened) {
@@ -143,7 +144,7 @@ export async function addAuthor(
   const fastSpeed = speed * 1.4;
 
   const nameInput = dialog.getByPlaceholder("Name");
-  await nameInput.click();
+  await humanClick(page, nameInput);
   await humanType(page, name, {
     speed: fastSpeed,
     typoRate: 0,
@@ -153,7 +154,7 @@ export async function addAuthor(
 
   if (opts.url) {
     const urlInput = dialog.getByPlaceholder("URL (optional)");
-    await urlInput.click();
+    await humanClick(page, urlInput);
     await humanType(page, opts.url, {
       speed: fastSpeed,
       typoRate: 0,
@@ -169,7 +170,7 @@ export async function addAuthor(
         .filter({ hasText: new RegExp(`^${idx}\\.`) })
         .first();
       if (await chip.isVisible().catch(() => false)) {
-        await chip.click();
+        await humanClick(page, chip);
         await pause(60, 140);
       }
     }
@@ -177,7 +178,7 @@ export async function addAuthor(
 
   if (opts.newAffiliation) {
     const newAffInput = dialog.getByPlaceholder(/New affiliation/i);
-    await newAffInput.click();
+    await humanClick(page, newAffInput);
     await humanType(page, opts.newAffiliation, {
       speed: fastSpeed,
       typoRate: 0,
@@ -187,7 +188,7 @@ export async function addAuthor(
   }
 
   const submit = dialog.locator("button.btn--primary");
-  await submit.click();
+  await humanClick(page, submit);
 
   try {
     await dialog.waitFor({ state: "hidden", timeout: 3_000 });

backend/demo/lib/embed-studio.ts

@@ -16,7 +16,10 @@
  */
 import type { Page } from "playwright";
 import { humanType, pause } from "../human-typing.js";
+import { humanClick } from "./mouse-cursor.js";
 import {
+  ARCHITECTURE_JSON,
+  ARCHITECTURE_JSON_META,
   MODEL_ACCURACY_CSV,
   MODEL_ACCURACY_CSV_META,
   NEURAL_NETWORK_BANNER_HTML,
@@ -73,11 +76,11 @@ async function seedEmbedDataFile(
 async function closeEmbedStudio(page: Page) {
   const closeBtn = page.getByRole("button", { name: /^Save & Close$/i }).first();
   if (await closeBtn.isVisible().catch(() => false)) {
-    await closeBtn.click();
+    await humanClick(page, closeBtn);
   } else {
     const xBtn = page.getByRole("button", { name: /Close Embed Studio/i }).first();
     if (await xBtn.isVisible().catch(() => false)) {
-      await xBtn.click();
+      await humanClick(page, xBtn);
     } else {
       await page.keyboard.press("Escape");
     }
@@ -194,10 +197,23 @@ export async function createNeuralNetworkBanner(page: Page, speed: number) {
     return;
   }
 
-  // Seed one data file BEFORE opening the studio so the FilesSidebar
-  // shows an existing dataset the agent can reference. Two purposes:
+  // Seed two data files BEFORE opening the studio so the FilesSidebar
+  // shows existing datasets the agent can reference. Three purposes:
   //   1. visually establishes that the studio now handles data files;
-  //   2. gives the listDataFiles tool call a real output to surface.
+  //   2. gives the listDataFiles tool call a real output to surface;
+  //   3. one of the files (architecture.json) is directly relevant to
+  //      the banner the agent is about to build, so the demo can show
+  //      the agent reading the data, extracting the layer topology,
+  //      and feeding it back into the visualization rather than just
+  //      ignoring the dataset and dropping a hardcoded picture.
+  await seedEmbedDataFile(page, {
+    name: ARCHITECTURE_JSON_META.name,
+    ext: ARCHITECTURE_JSON_META.ext,
+    content: ARCHITECTURE_JSON,
+    columns: ARCHITECTURE_JSON_META.columns,
+    rowCount: ARCHITECTURE_JSON_META.rowCount,
+    uploader: "alice",
+  });
   await seedEmbedDataFile(page, {
     name: MODEL_ACCURACY_CSV_META.name,
     ext: MODEL_ACCURACY_CSV_META.ext,
@@ -209,14 +225,15 @@ export async function createNeuralNetworkBanner(page: Page, speed: number) {
 
   await createBtn.scrollIntoViewIfNeeded();
   await pause(120, 220);
-  await createBtn.click();
+  await humanClick(page, createBtn);
 
   const promptArea = page.getByPlaceholder("Describe your chart...");
-  const promptText = "A neural network banner - soft pulses, primary color.";
+  const promptText =
+    "A neural network banner that captures the spirit of the article. Use the architecture I uploaded to drive the layout - layered graph with soft pulses flowing along the synapses, like attention scores rippling between tokens.";
   try {
     await promptArea.waitFor({ state: "visible", timeout: 4_000 });
     await pause(260, 420);
-    await promptArea.click();
+    await humanClick(page, promptArea);
     await pause(180, 280);
     await humanType(page, promptText, {
       speed: speed * 1.6,
@@ -229,35 +246,111 @@ export async function createNeuralNetworkBanner(page: Page, speed: number) {
     console.warn("[alice] embed studio textarea not found, faking anyway");
   }
 
+  // The scene mirrors a realistic agent round-trip and narrates
+  // the artifact we're actually about to inject, so when the
+  // viewer flips to the preview everything the agent promised is
+  // visibly there: 5 layers with the exact counts, pulses on a
+  // random synapse, transparent background, retinted via
+  // `--primary-color`.
+  //
+  // The sequence is:
+  //   readEmbed   - look at what's already in the banner slot
+  //                 (placeholder HTML from "Create chart" click)
+  //   listDataFiles + readDataFile - confirm there IS a dataset
+  //                 but decide it's better saved for inline charts
+  //   createEmbed - write the real banner with a descriptive
+  //                 filename and title, and a spec that matches
+  //                 the actual NEURAL_NETWORK_BANNER_HTML we ship
+  const csvPreviewOutput =
+    `${MODEL_ACCURACY_CSV_META.columns.join(",")}\n` +
+    MODEL_ACCURACY_CSV.split("\n").slice(1, 4).join("\n") +
+    "\n... 5 more rows";
+
   await runEmbedScene(page, [
     { kind: "user-text", text: promptText },
+    {
+      kind: "assistant-text",
+      text:
+        "Good - a hero banner. Let me look at what's already in the slot and what data you've uploaded so I can pick the right shape.",
+      chunkMs: [22, 48],
+    },
+    {
+      kind: "assistant-tool",
+      toolName: "readEmbed",
+      input: { src: "banner.html" },
+      output:
+        "banner.html is the placeholder stub (14 lines). Safe to replace.",
+      thinkMs: [420, 640],
+    },
     {
       kind: "assistant-tool",
       toolName: "listDataFiles",
       input: {},
       output:
+        `- ${ARCHITECTURE_JSON_META.name} (json, ${ARCHITECTURE_JSON.length} bytes) ` +
+        `keys=[${ARCHITECTURE_JSON_META.columns.join(", ")}]\n` +
         `- ${MODEL_ACCURACY_CSV_META.name} (csv, ${MODEL_ACCURACY_CSV.length} bytes) ` +
         `rows=${MODEL_ACCURACY_CSV_META.rowCount} ` +
         `columns=[${MODEL_ACCURACY_CSV_META.columns.join(", ")}]`,
-      thinkMs: [480, 760],
+      thinkMs: [440, 680],
     },
     {
       kind: "assistant-text",
-      text: "Data files noted - going abstract for the banner.",
+      text:
+        ` Two files. \`${ARCHITECTURE_JSON_META.name}\` looks directly relevant - that's what should drive the topology. Reading it first.`,
+      chunkMs: [20, 46],
+    },
+    {
+      kind: "assistant-tool",
+      toolName: "readDataFile",
+      input: { name: ARCHITECTURE_JSON_META.name },
+      output: ARCHITECTURE_JSON,
+      thinkMs: [520, 780],
+    },
+    {
+      kind: "assistant-text",
+      text:
+        " Got it - five layers (tokens 6 → embedding 10 → attention 14 → values 10 → logits 6), fully-connected, softmax activation. That maps perfectly to a layered graph.",
+      chunkMs: [22, 50],
+      chunkSize: [1, 3],
+    },
+    {
+      kind: "assistant-tool",
+      toolName: "readDataFile",
+      input: { name: MODEL_ACCURACY_CSV_META.name, limit: 4 },
+      output: csvPreviewOutput,
+      thinkMs: [380, 560],
+    },
+    {
+      kind: "assistant-text",
+      text:
+        " The accuracy CSV is great for an inline chart later in the article, but for the hero I'll stick with the architecture diagram.",
+      chunkMs: [22, 48],
+    },
+    {
+      kind: "assistant-text",
+      text:
+        " Plan: nodes spaced per layer count from the JSON, edges tracing every fully-connected pair, soft dots traveling a random synapse every ~200ms so the network feels active without competing with the title. Pure SVG, transparent background, respects `prefers-reduced-motion`.",
+      chunkMs: [22, 48],
+      chunkSize: [1, 3],
     },
     {
       kind: "assistant-tool",
       toolName: "createEmbed",
       input: {
+        filename: "banner.html",
         title: "Neural network banner",
+        description:
+          "Layered graph derived from architecture.json (5 layers: 6/10/14/10/6, fully-connected). Pulses flow along random synapses; pure SVG, transparent background.",
       },
-      output: "chart created (134 lines, 3.8 KB)",
-      thinkMs: [620, 980],
+      output: "wrote banner.html (182 lines, 3.8 KB, 0 external deps)",
+      thinkMs: [720, 1_080],
     },
     {
       kind: "assistant-text",
       text:
-        " Layered network with subtle pulses along the synapses, tinted with the article primary color.",
+        " Done - layer counts come from the JSON, the hero container drives the size, and the network rerolls a new burst pattern every cycle.",
+      chunkMs: [22, 50],
     },
   ]);
 

backend/demo/lib/mouse-cursor.ts

@@ -0,0 +1,373 @@
+/**
+ * lib/mouse-cursor.ts
+ *
+ * Draws a visible mouse cursor in Alice's recorded window and provides
+ * human-feel movement helpers.
+ *
+ * Playwright drives real native mouse events but the OS pointer is NOT
+ * captured by the browser's screen recorder - so without this overlay
+ * the viewer sees clicks happen "by themselves". This module injects a
+ * small DOM overlay (SVG arrow + click ripple) that listens to the
+ * `mousemove`, `mousedown` and `mouseup` events Playwright already
+ * generates, so the cursor follows every pointer move naturally.
+ *
+ * On top of that, `humanMove` / `humanClick` / `humanHover` perform the
+ * move itself with intermediate steps and a cubic ease so the cursor
+ * glides to its target instead of teleporting, which is what Playwright's
+ * default `locator.click()` does (single-step move).
+ */
+import type { Locator, Page } from "playwright";
+
+const OVERLAY_ID = "__demo-mouse-cursor";
+
+/**
+ * JS source that installs the overlay inside the page. Kept as a plain
+ * string (content-script) so Playwright doesn't have to serialize a
+ * TypeScript function - the tsx transpile pipeline occasionally kept
+ * type assertions in the `.toString()` output which quietly broke
+ * execution. A string is final and cannot drift.
+ */
+const OVERLAY_SCRIPT = `
+(() => {
+  const OVERLAY_ID = ${JSON.stringify(OVERLAY_ID)};
+  try {
+    if (window.top !== window) return;
+  } catch (_) { /* cross-origin top; still install */ }
+
+  const mount = () => {
+    if (document.getElementById(OVERLAY_ID)) return;
+
+    const host = document.createElement("div");
+    host.id = OVERLAY_ID;
+    host.setAttribute("aria-hidden", "true");
+    // Use the HTML popover API so the overlay sits in the top-layer,
+    // above every native <dialog showModal()>. Regular z-index would
+    // lose to the browser's top-layer stacking order. Falls back to
+    // plain fixed positioning if the user agent is too old to
+    // support popover (our Chromium is Chrome 114+, fine).
+    try { host.setAttribute("popover", "manual"); } catch (_) { /* ignore */ }
+    host.style.position = "fixed";
+    host.style.inset = "0";
+    host.style.top = "0";
+    host.style.left = "0";
+    host.style.width = "100vw";
+    host.style.height = "100vh";
+    host.style.pointerEvents = "none";
+    host.style.zIndex = "2147483646";
+    host.style.margin = "0";
+    host.style.padding = "0";
+    host.style.border = "0";
+    host.style.background = "transparent";
+    host.style.overflow = "visible";
+
+    const NS = "http://www.w3.org/2000/svg";
+    const pointer = document.createElementNS(NS, "svg");
+    pointer.setAttribute("width", "26");
+    pointer.setAttribute("height", "26");
+    pointer.setAttribute("viewBox", "0 0 26 26");
+    pointer.setAttribute("fill", "none");
+    pointer.style.position = "absolute";
+    pointer.style.left = "0";
+    pointer.style.top = "0";
+    pointer.style.transform = "translate3d(-100px, -100px, 0)";
+    pointer.style.filter = "drop-shadow(0 2px 4px rgba(0,0,0,0.45))";
+    pointer.style.willChange = "transform";
+
+    const arrow = document.createElementNS(NS, "path");
+    arrow.setAttribute(
+      "d",
+      "M4 3 L4 20 L9 15.5 L12 22 L14.8 20.8 L11.9 14.3 L19 14.3 Z"
+    );
+    arrow.setAttribute("fill", "#ffffff");
+    arrow.setAttribute("stroke", "#0a0a0a");
+    arrow.setAttribute("stroke-width", "1.4");
+    arrow.setAttribute("stroke-linejoin", "round");
+    pointer.appendChild(arrow);
+
+    const ripple = document.createElement("div");
+    ripple.style.position = "absolute";
+    ripple.style.left = "0";
+    ripple.style.top = "0";
+    ripple.style.width = "22px";
+    ripple.style.height = "22px";
+    ripple.style.borderRadius = "50%";
+    ripple.style.border = "2px solid rgba(255, 186, 70, 0.95)";
+    ripple.style.background = "rgba(255, 200, 80, 0.22)";
+    ripple.style.transform = "translate3d(-100px, -100px, 0) scale(0)";
+    ripple.style.opacity = "0";
+    ripple.style.pointerEvents = "none";
+
+    const style = document.createElement("style");
+    style.textContent =
+      "@keyframes __demo-mouse-ripple {" +
+      "  0% { transform: translate3d(var(--rx), var(--ry), 0) scale(0.15); opacity: 0.95; }" +
+      "  80% { opacity: 0.35; }" +
+      "  100% { transform: translate3d(var(--rx), var(--ry), 0) scale(2.6); opacity: 0; }" +
+      "}" +
+      "#" + OVERLAY_ID + " [data-ripple-active] {" +
+      "  animation: __demo-mouse-ripple 0.6s cubic-bezier(0.2, 0.6, 0.2, 1) forwards;" +
+      "}";
+
+    host.appendChild(style);
+    host.appendChild(pointer);
+    host.appendChild(ripple);
+    document.documentElement.appendChild(host);
+
+    // Promote into the top-layer so the cursor stays above any
+    // <dialog showModal()>, popovers, or other top-layer elements.
+    try {
+      const anyHost = host;
+      if (typeof anyHost.showPopover === "function") {
+        anyHost.showPopover();
+      }
+    } catch (_) { /* fall back to plain fixed positioning */ }
+
+    let x = -100;
+    let y = -100;
+    const updatePointer = () => {
+      pointer.style.transform = "translate3d(" + x + "px, " + y + "px, 0)";
+    };
+    updatePointer();
+
+    window.addEventListener("mousemove", (ev) => {
+      x = ev.clientX;
+      y = ev.clientY;
+      updatePointer();
+    }, true);
+
+    window.addEventListener("mousedown", () => {
+      ripple.removeAttribute("data-ripple-active");
+      ripple.style.setProperty("--rx", (x - 11) + "px");
+      ripple.style.setProperty("--ry", (y - 11) + "px");
+      // Force reflow so the animation restarts on every click.
+      void ripple.offsetWidth;
+      ripple.setAttribute("data-ripple-active", "true");
+    }, true);
+
+    // Breadcrumb so callers can verify the overlay mounted via the
+    // DOM (page.evaluate) without needing access to the page console.
+    document.documentElement.setAttribute("data-demo-mouse-cursor", "on");
+
+    // Re-promote ourselves in the top-layer whenever another element
+    // joins it (a <dialog showModal()> or a sibling popover). The
+    // browser stacks top-layer elements in LIFO order, so the last
+    // one promoted sits on top. Without this, our cursor would end
+    // up UNDER the author dialog as soon as Alice opens it.
+    const repromote = () => {
+      try {
+        const anyHost = host;
+        if (typeof anyHost.hidePopover === "function") {
+          anyHost.hidePopover();
+        }
+        if (typeof anyHost.showPopover === "function") {
+          anyHost.showPopover();
+        }
+      } catch (_) { /* ignore */ }
+    };
+
+    const isTopLayerCandidate = (el) => {
+      if (!el || el === host) return false;
+      if (el.nodeName === "DIALOG" && el.hasAttribute("open")) return true;
+      if (el.hasAttribute && el.hasAttribute("popover")) return true;
+      return false;
+    };
+
+    const domObserver = new MutationObserver((mutations) => {
+      for (const m of mutations) {
+        if (m.type === "attributes") {
+          if (isTopLayerCandidate(m.target)) {
+            repromote();
+            return;
+          }
+        } else if (m.type === "childList") {
+          for (const n of Array.from(m.addedNodes)) {
+            if (n.nodeType === 1 && isTopLayerCandidate(n)) {
+              repromote();
+              return;
+            }
+          }
+        }
+      }
+    });
+    try {
+      domObserver.observe(document.documentElement, {
+        subtree: true,
+        childList: true,
+        attributes: true,
+        attributeFilter: ["open", "popover"],
+      });
+    } catch (_) { /* ignore */ }
+  };
+
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", mount, { once: true });
+  } else {
+    mount();
+  }
+
+  // Re-mount on history/SPA navigations that don't reload the document
+  // (e.g. the published article link kept inside the same SPA tree).
+  // We don't have such cases today, but the check is cheap.
+  const observer = new MutationObserver(() => {
+    if (!document.getElementById(OVERLAY_ID) && document.documentElement) {
+      mount();
+    }
+  });
+  try {
+    observer.observe(document.documentElement, { childList: true });
+  } catch (_) { /* ignore */ }
+})();
+`;
+
+/**
+ * Register the cursor overlay as an init script on the given context
+ * (or page). Must run BEFORE the first navigation so the overlay is
+ * live on every document the page loads (including the published
+ * article the demo opens in the same tab).
+ */
+export async function injectMouseCursor(target: {
+  addInitScript: (
+    script: { content: string } | string | ((arg: unknown) => unknown),
+    arg?: unknown,
+  ) => Promise<void>;
+}): Promise<void> {
+  await target.addInitScript({ content: OVERLAY_SCRIPT });
+}
+
+/**
+ * Verify the overlay actually mounted on the given page. Returns true
+ * if the breadcrumb attribute is present on `<html>`. Callers log a
+ * warning otherwise so a silent failure doesn't eat the whole demo.
+ */
+export async function verifyMouseCursor(page: Page): Promise<boolean> {
+  try {
+    return await page.evaluate(
+      () => document.documentElement.getAttribute("data-demo-mouse-cursor") === "on",
+    );
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Movement helpers
+// ---------------------------------------------------------------------------
+
+interface MoveOpts {
+  /** Total move duration in ms. Defaults depend on distance. */
+  durationMs?: number;
+  /** Steps used by `page.mouse.move(x, y, { steps })`. */
+  steps?: number;
+  /** Random offset (px) added to the target to feel less robotic. */
+  jitter?: number;
+}
+
+let lastX = 40;
+let lastY = 40;
+
+function easeInOutCubic(t: number): number {
+  return t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2;
+}
+
+/**
+ * Move the mouse from its last known position to `(x, y)` with a cubic
+ * ease so the overlay cursor glides instead of teleporting. We track
+ * the last position ourselves because Playwright doesn't expose the
+ * current mouse coordinates.
+ */
+export async function humanMove(
+  page: Page,
+  x: number,
+  y: number,
+  opts: MoveOpts = {},
+): Promise<void> {
+  const jitter = opts.jitter ?? 2;
+  const tx = x + (Math.random() * 2 - 1) * jitter;
+  const ty = y + (Math.random() * 2 - 1) * jitter;
+
+  const dx = tx - lastX;
+  const dy = ty - lastY;
+  const dist = Math.hypot(dx, dy);
+
+  const steps =
+    opts.steps ?? Math.max(10, Math.min(40, Math.round(dist / 18)));
+  const duration = opts.durationMs ?? Math.max(260, Math.min(700, dist * 0.9));
+  const stepDelay = duration / steps;
+
+  // Quadratic Bezier control point offset perpendicular to the
+  // straight line, so the path arcs slightly. Side alternates per
+  // move so consecutive trips don't bend the same way.
+  const perp = { x: -dy, y: dx };
+  const perpLen = Math.hypot(perp.x, perp.y) || 1;
+  const curveSide = Math.random() < 0.5 ? 1 : -1;
+  const curveAmp = Math.min(60, dist * 0.12) * curveSide;
+  const ctrl = {
+    x: lastX + dx * 0.5 + (perp.x / perpLen) * curveAmp,
+    y: lastY + dy * 0.5 + (perp.y / perpLen) * curveAmp,
+  };
+
+  for (let i = 1; i <= steps; i++) {
+    const t = easeInOutCubic(i / steps);
+    const u = 1 - t;
+    const px = u * u * lastX + 2 * u * t * ctrl.x + t * t * tx;
+    const py = u * u * lastY + 2 * u * t * ctrl.y + t * t * ty;
+    await page.mouse.move(px, py);
+    if (stepDelay > 0) {
+      await new Promise((r) => setTimeout(r, stepDelay));
+    }
+  }
+
+  lastX = tx;
+  lastY = ty;
+}
+
+/**
+ * Move the mouse to the center of `locator` with `humanMove`. Uses
+ * `boundingBox()` so the helper works for any element, including
+ * overlays like the chat panel or the settings drawer.
+ */
+export async function humanHover(
+  page: Page,
+  locator: Locator,
+  opts: MoveOpts = {},
+): Promise<boolean> {
+  const handle = await locator.first().elementHandle();
+  if (!handle) return false;
+  const box = await handle.boundingBox();
+  if (!box) return false;
+  const cx = box.x + box.width / 2;
+  const cy = box.y + box.height / 2;
+  await humanMove(page, cx, cy, opts);
+  return true;
+}
+
+/**
+ * Smoothly move the mouse to `locator`, pause briefly, then click.
+ * Falls back to `locator.click()` if the element has no bounding box
+ * (detached, display:none, etc.) so callers don't have to branch.
+ */
+export async function humanClick(
+  page: Page,
+  locator: Locator,
+  opts: MoveOpts & { settleMs?: [number, number] } = {},
+): Promise<void> {
+  const moved = await humanHover(page, locator, opts);
+  if (!moved) {
+    await locator.click();
+    return;
+  }
+  const [lo, hi] = opts.settleMs ?? [60, 140];
+  const pause = lo + Math.random() * (hi - lo);
+  await new Promise((r) => setTimeout(r, pause));
+  await page.mouse.down();
+  await new Promise((r) => setTimeout(r, 30 + Math.random() * 30));
+  await page.mouse.up();
+}
+
+/**
+ * Reset the cached mouse position. Useful at the start of a new run.
+ */
+export function resetMouseState(x = 40, y = 40): void {
+  lastX = x;
+  lastY = y;
+}

backend/demo/lib/publish-flow.ts

@@ -10,6 +10,7 @@
  */
 import type { Page } from "playwright";
 import { pause } from "../human-typing.js";
+import { humanClick, humanMove, resetMouseState } from "./mouse-cursor.js";
 
 /**
  * Drag the primary-hue slider in the Settings drawer from its current
@@ -50,9 +51,7 @@ export async function applyHueChange(
   const cog = page.getByRole("button", { name: "Article settings" }).first();
   try {
     await cog.waitFor({ state: "visible", timeout: 5_000 });
-    await cog.hover().catch(() => undefined);
-    await pause(40, 80);
-    await cog.click();
+    await humanClick(page, cog);
   } catch {
     console.warn("[hue] settings cog not found");
     return;
@@ -92,9 +91,9 @@ export async function applyHueChange(
   //    the viewer's eye follows the mouse into the drawer before
   //    the press-and-drag begins. Kept short so the whole interaction
   //    reads as "a snappy human edit" rather than a slow ceremony.
-  await page.mouse.move(startX - 40, y - 20, { steps: 3 });
-  await pause(30, 60);
-  await page.mouse.move(startX, y, { steps: 4 });
+  //    `humanMove` produces a curved, eased path the overlay cursor
+  //    renders; straight `page.mouse.move` would teleport on camera.
+  await humanMove(page, startX, y, { durationMs: 420 });
   await pause(40, 70);
 
   // 4) Press down ON the slider. `setPointerCapture` locks further
@@ -121,6 +120,9 @@ export async function applyHueChange(
   }
 
   await page.mouse.up();
+  // Sync the tracked cursor position to where the drag left off, so
+  // the next `humanMove` doesn't animate from a stale origin.
+  resetMouseState(endX, y);
   await pause(120, 180);
 
   // 6) Close the drawer so the final state is "clean article + new
@@ -130,7 +132,7 @@ export async function applyHueChange(
     .locator(".settings-drawer button[aria-label='Close']")
     .first();
   if (await closeDrawer.isVisible().catch(() => false)) {
-    await closeDrawer.click();
+    await humanClick(page, closeDrawer);
   } else {
     await page.keyboard.press("Escape").catch(() => undefined);
   }
@@ -177,7 +179,7 @@ export async function triggerPublish(
     .first();
   try {
     await publishBtn.waitFor({ state: "visible", timeout: 4_000 });
-    await publishBtn.click();
+    await humanClick(page, publishBtn);
     console.log("[publish] clicked Publish, waiting for success...");
   } catch {
     console.warn("[publish] primary button not found in dialog");
@@ -207,42 +209,82 @@ export async function triggerPublish(
   // Tiny beat so the "Published!" title is readable before the click.
   await pause(600, 900);
 
-  // 4) Navigate to the published article IN THE SAME TAB.
-  //    The link is rendered as `target="_blank"` for real users, which
-  //    is the right UX outside of the demo. But in --app=/fullscreen
-  //    record mode, target="_blank" spawns a regular windowed Chrome
-  //    (with tabs + URL bar, NOT fullscreen) because app windows
-  //    can't host tabs. That regular window also re-hydrates
-  //    Chrome's translate heuristics and pops a "Translate to French"
-  //    bubble over the recording on OS-French systems.
+  // 4) Visibly click "View published article" and navigate IN
+  //    THE SAME TAB.
+  //
+  //    Why the gymnastics: the link is rendered `target="_blank"`
+  //    for real users (correct UX outside the demo). But in
+  //    --app=/fullscreen record mode, target="_blank" spawns a
+  //    regular windowed Chrome (with tabs + URL bar, NOT fullscreen)
+  //    because app windows cannot host tabs. That stray window
+  //    also re-hydrates Chrome's translate heuristics and pops a
+  //    "Translate to French" bubble over the recording on French
+  //    OSes. We want neither.
+  //
+  //    The old approach read `href` and called `page.goto`
+  //    directly - no click, no cursor motion, the "button press"
+  //    never happened on camera. That reads as "the demo ended
+  //    and something magic happened". Users want to SEE Alice
+  //    click the button.
   //
-  //    Reading `href` + `page.goto` keeps us in Alice's chromeless
-  //    fullscreen window: no new process, no translate prompt, no
-  //    visible URL bar. Exactly the frame the recording needs.
+  //    Fix: neutralise the target attribute via evaluate so the
+  //    link navigates in-place, then humanClick it for real. The
+  //    click triggers the native <a href> navigation which keeps
+  //    Alice in her chromeless fullscreen window (no tabs, no
+  //    URL bar, no translate prompt) while still showing the
+  //    cursor land on the button.
   const publishedHref = await viewLink.getAttribute("href");
   if (!publishedHref) {
     console.warn("[publish] view link has no href, cannot navigate");
     return;
   }
 
-  // Resolve relative URLs against the current page origin so
-  // `/published/xyz/index.html` works unchanged.
-  const targetUrl = new URL(publishedHref, page.url()).toString();
   try {
-    await page.goto(targetUrl, {
-      waitUntil: "domcontentloaded",
-      timeout: 15_000,
+    await viewLink.evaluate((el: HTMLAnchorElement) => {
+      el.removeAttribute("target");
+      el.removeAttribute("rel");
     });
+  } catch {
+    /* non-fatal, the goto fallback below handles it */
+  }
+
+  try {
+    // `waitForNavigation` must be armed BEFORE the click fires,
+    // otherwise the navigation event can land before we start
+    // awaiting it and the promise hangs on the next URL.
+    const navigation = page.waitForURL(
+      (url) => url.pathname.includes("/published/"),
+      { timeout: 15_000 },
+    );
+    await humanClick(page, viewLink);
+    await navigation;
     await page
       .waitForLoadState("load", { timeout: 5_000 })
       .catch(() => undefined);
     console.log("[publish] viewing published article (in-place)");
   } catch (err) {
+    // Click-driven navigation failed (link handler ate the event,
+    // target attribute somehow survived, ...). Fall back to the
+    // old direct-goto so the demo still lands on the published
+    // output - losing the cursor motion on the button, but the
+    // alternative is a blank recording finale.
     console.warn(
-      "[publish] navigation to published article failed:",
+      "[publish] click-driven navigation failed, falling back to goto:",
       err instanceof Error ? err.message : err,
     );
-    return;
+    const targetUrl = new URL(publishedHref, page.url()).toString();
+    try {
+      await page.goto(targetUrl, {
+        waitUntil: "domcontentloaded",
+        timeout: 15_000,
+      });
+    } catch (err2) {
+      console.warn(
+        "[publish] navigation to published article failed:",
+        err2 instanceof Error ? err2.message : err2,
+      );
+      return;
+    }
   }
 
   await pause(lingerMin, lingerMax);

backend/demo/lib/scaffolding.ts

@@ -13,6 +13,7 @@
  */
 import type { Page } from "playwright";
 import { humanType, pause } from "../human-typing.js";
+import { humanMove } from "./mouse-cursor.js";
 
 export interface ScaffoldSection {
   heading: string;
@@ -33,6 +34,87 @@ export interface ScaffoldSection {
  *   <p></p>           <- slot 0
  *   ...
  */
+/**
+ * Open the slash-menu ("/") suggestion popover and pick "Heading 2"
+ * using keyboard-only navigation - no filter text is typed, so if
+ * the popover fails to mount we don't leak garbage ("/heading 2")
+ * into the editor.
+ *
+ * Flat menu order (used by the suggestion plugin for ArrowUp /
+ * ArrowDown, independent of the grouped render): Heading 1 (index
+ * 0), Heading 2 (index 1), ... so ONE ArrowDown from the default
+ * selection lands on "Heading 2".
+ *
+ * Used for the FIRST section of the scaffold so viewers see the
+ * block-command popover fire and close cleanly. Subsequent
+ * headings use the faster Markdown `## ` input rule for variety.
+ *
+ * The menu's own command deletes the "/" trigger before running
+ * `toggleHeading({ level: 2 })`, so after this helper returns the
+ * caret is already parked inside an empty <h2> ready for heading
+ * text.
+ */
+async function pickHeading2ViaSlashMenu(page: Page): Promise<boolean> {
+  // Move the visible cursor over the editor BEFORE typing "/" so the
+  // viewer sees the pointer parked on the paragraph where the slash
+  // menu is about to bloom. Otherwise the menu opens while the
+  // cursor is stranded on whatever button Alice last clicked
+  // (typically the "Add author" confirm), which reads as a ghost
+  // interaction.
+  try {
+    const rect = await page.evaluate(() => {
+      const root = document.querySelector(".ProseMirror") as HTMLElement | null;
+      if (!root) return null;
+      const sel = window.getSelection();
+      // Prefer the caret's own rect so the cursor lands exactly where
+      // the "/" will be typed. Fall back to the last paragraph if the
+      // caret is detached.
+      if (sel && sel.rangeCount > 0) {
+        const r = sel.getRangeAt(0).getClientRects()[0];
+        if (r && r.width >= 0 && r.height > 0) {
+          return { x: r.left + 6, y: r.top + r.height / 2 };
+        }
+      }
+      const paras = root.querySelectorAll("p");
+      const last = paras[paras.length - 1] as HTMLElement | undefined;
+      if (!last) return null;
+      const lr = last.getBoundingClientRect();
+      return { x: lr.left + 24, y: lr.top + lr.height / 2 };
+    });
+    if (rect) await humanMove(page, rect.x, rect.y, { steps: 18 });
+  } catch {
+    /* non-fatal, typing still works without the cursor following */
+  }
+  await pause(80, 140);
+  await page.keyboard.type("/", { delay: 30 });
+  // Wait for the tippy-mounted popover to appear. The Suggestion
+  // plugin schedules a React render + tippy mount after the "/"
+  // lands in state, which can take two animation frames.
+  const popoverLocator = page.locator(".slash-menu").first();
+  try {
+    await popoverLocator.waitFor({ state: "visible", timeout: 1_200 });
+  } catch {
+    // Popover never mounted (race with initial focus / input
+    // handler). Backspace the stray "/" so the caller's fallback
+    // doesn't stack it in front of "## ".
+    await page.keyboard.press("Backspace");
+    await pause(40, 80);
+    return false;
+  }
+  // Pause so the viewer actually sees the menu open before we
+  // navigate.
+  await pause(420, 640);
+  // Default selectedIndex is 0 = "Heading 1"; one ArrowDown lands
+  // on "Heading 2". We do this purely via arrow keys so NO
+  // filter text is typed into the doc if the suggestion plugin
+  // unexpectedly closes mid-sequence.
+  await page.keyboard.press("ArrowDown");
+  await pause(160, 260);
+  await page.keyboard.press("Enter");
+  await pause(140, 220);
+  return true;
+}
+
 export async function writeScaffold(
   page: Page,
   sections: ScaffoldSection[],
@@ -42,8 +124,18 @@ export async function writeScaffold(
     const section = sections[s];
     const isLast = s === sections.length - 1;
 
-    await page.keyboard.type("## ", { delay: 22 });
-    await pause(40, 80);
+    // Use the slash menu for the first heading so the demo shows
+    // the block-command popover at least once. The remaining
+    // sections stick to the Markdown `## ` shortcut to keep the
+    // scaffold phase short.
+    let createdViaSlash = false;
+    if (s === 0) {
+      createdViaSlash = await pickHeading2ViaSlashMenu(page);
+    }
+    if (!createdViaSlash) {
+      await page.keyboard.type("## ", { delay: 22 });
+      await pause(40, 80);
+    }
     await humanType(page, section.heading, {
       speed: speed * 2.2,
       typoRate: 0,
@@ -75,6 +167,63 @@ export async function waitForHeading2(
     .waitFor({ state: "visible", timeout });
 }
 
+/**
+ * Wait for the OTHER peers' final contributions to have landed in
+ * the shared doc, then give the browser one settle frame before
+ * returning. Use this as a pre-bold sync point so the layout is
+ * frozen when we compute and drag over the target phrase: if we
+ * skip it, Bob's `<blockMath>` insertion or Carol's `<pre>` code
+ * block can still be reshaping the doc during the drag, which
+ * shifts the Intuition paragraph out from under the measured
+ * rects and the selection sweep picks up the heading above.
+ *
+ * The markers below are the LAST things each peer writes:
+ *   - Bob:   `.ProseMirror math-display` node (the attention
+ *            formula in The recipe[1])
+ *   - Carol: `.ProseMirror pre code` with "import torch" as text
+ *            (the eight-line PyTorch snippet)
+ *
+ * Both are idempotent: if the peer finished earlier, the locator
+ * resolves immediately. The extra `layoutSettleMs` beat after
+ * resolution lets Tiptap's decoration plugin repaint so
+ * `getClientRects()` returns the final geometry.
+ */
+export async function waitForPeersSettled(
+  page: Page,
+  opts: {
+    timeout?: number;
+    layoutSettleMs?: number;
+  } = {},
+): Promise<void> {
+  const timeout = opts.timeout ?? 45_000;
+  const layoutSettleMs = opts.layoutSettleMs ?? 700;
+
+  const bobMarker = page
+    .locator(".ProseMirror [data-type='block-math']")
+    .first();
+  const carolMarker = page
+    .locator(".ProseMirror pre")
+    .filter({ hasText: /import\s+torch/i })
+    .first();
+
+  try {
+    await Promise.all([
+      bobMarker.waitFor({ state: "attached", timeout }),
+      carolMarker.waitFor({ state: "attached", timeout }),
+    ]);
+  } catch (err) {
+    console.warn(
+      "[sync] waitForPeersSettled timed out:",
+      err instanceof Error ? err.message : err,
+    );
+  }
+
+  // Layout settle: even after both markers exist, Tiptap may emit
+  // one more transaction frame to finalize decorations. Pause to
+  // let the scroll height stabilise before any rect measurements.
+  await page.waitForTimeout(layoutSettleMs);
+}
+
 /**
  * Place this browser's caret at the END of the first <p> directly after
  * the heading whose text matches `headingText`. Used so each persona can
@@ -128,8 +277,54 @@ export async function focusNthParagraphInSection(
   headingText: string,
   slotIndex: number,
 ): Promise<boolean> {
-  return await page.evaluate(
+  // Phase A: locate the slot and compute the click point, but DON'T
+  // dispatch events yet. We want to animate the visible cursor to the
+  // target first so the viewer sees the pointer land on the paragraph
+  // before the caret jumps there.
+  const rect = await page.evaluate(
     ({ text, n }) => {
+      const root = document.querySelector(".ProseMirror") as HTMLElement | null;
+      if (!root) return null;
+      const headings = Array.from(root.querySelectorAll("h2"));
+      const wanted = text.toLowerCase();
+      const heading = headings.find(
+        (h) => (h.textContent || "").trim().toLowerCase().includes(wanted),
+      );
+      if (!heading) return null;
+
+      const slots: HTMLElement[] = [];
+      let node: Element | null = heading.nextElementSibling;
+      while (node) {
+        if (/^H[1-6]$/.test(node.tagName)) break;
+        slots.push(node as HTMLElement);
+        node = node.nextElementSibling;
+      }
+
+      const target = slots[n];
+      if (!target) return null;
+      target.scrollIntoView({ behavior: "auto", block: "center" });
+
+      const r = target.getBoundingClientRect();
+      return {
+        x: Math.max(r.left + 1, r.right - 4),
+        y: r.top + r.height / 2,
+      };
+    },
+    { text: headingText, n: slotIndex },
+  );
+
+  if (!rect) return false;
+
+  // Let the auto-scroll settle before we move onto the target,
+  // otherwise the humanMove aim is stale.
+  await pause(120, 220);
+  await humanMove(page, rect.x, rect.y, { steps: 20 });
+
+  // Phase B: now place the caret. Dispatch synthesized mouse events
+  // at the exact coordinates we just moved to (ProseMirror listens
+  // for these), and set the DOM Range as a belt-and-braces fallback.
+  return await page.evaluate(
+    ({ text, n, clickX, clickY }) => {
       const g = globalThis as unknown as { __name?: <T>(fn: T) => T };
       if (typeof g.__name !== "function") g.__name = <T,>(fn: T) => fn;
 
@@ -152,22 +347,14 @@ export async function focusNthParagraphInSection(
 
       const target = slots[n];
       if (!target) return false;
-      target.scrollIntoView({ behavior: "auto", block: "center" });
-
-      // Pick a click point at the END of the paragraph's visible box so
-      // the caret lands after any existing content (still safe for
-      // empty paragraphs).
-      const rect = target.getBoundingClientRect();
-      const x = Math.max(rect.left + 1, rect.right - 4);
-      const y = rect.top + rect.height / 2;
 
       const mk = (type: string) =>
         new MouseEvent(type, {
           bubbles: true,
           cancelable: true,
           view: window,
-          clientX: x,
-          clientY: y,
+          clientX: clickX,
+          clientY: clickY,
           button: 0,
           buttons: type === "mousedown" ? 1 : 0,
         });
@@ -186,6 +373,6 @@ export async function focusNthParagraphInSection(
       }
       return true;
     },
-    { text: headingText, n: slotIndex },
+    { text: headingText, n: slotIndex, clickX: rect.x, clickY: rect.y },
   );
 }

backend/demo/lib/selection.ts

@@ -9,6 +9,8 @@
  * concrete range.
  */
 import type { Page } from "playwright";
+import { pause } from "../human-typing.js";
+import { humanMove, resetMouseState } from "./mouse-cursor.js";
 
 /**
  * Read the current ProseMirror selection range. Returns null if the
@@ -65,18 +67,25 @@ export async function getCurrentPmSelection(
  *
  * Side effects
  * ------------
- * On success, also seeds PM's selection AND broadcasts the range as
- * the local user's `AgentFocus` so every peer sees a `<Name> agent`
- * tinted range (same UX as when the chat panel opens over a manual
- * selection).
+ * On success, always seeds PM's text selection. If `setAgentFocus`
+ * is true, ALSO broadcasts the range as the local user's AgentFocus
+ * so every peer sees a `<Name> agent` tinted range - that's the
+ * correct behaviour for chat-driven actions (format / link /
+ * citation via the assistant), where the viewer should perceive
+ * the agent as owning the range. For pure editor UX paths (bubble
+ * toolbar bold, plain text selection before typing), leave it
+ * false so the agent label doesn't pop up out of nowhere while the
+ * chat panel is closed.
  */
 export async function selectSubstringInParagraph(
   page: Page,
   paragraphSnippet: string,
   substring: string,
+  opts: { setAgentFocus?: boolean } = {},
 ): Promise<{ from: number; to: number } | null> {
+  const setFocus = opts.setAgentFocus ?? false;
   return await page.evaluate(
-    ({ paraText, substrText }) => {
+    ({ paraText, substrText, setFocus: doFocus }) => {
       const g = globalThis as unknown as {
         __name?: <T>(fn: T, name?: string) => T;
       };
@@ -147,11 +156,274 @@ export async function selectSubstringInParagraph(
       }
 
       editor.commands.setTextSelection({ from, to });
-      editor.commands.setAgentFocus({ from, to });
+      if (doFocus) editor.commands.setAgentFocus({ from, to });
       return { from, to };
     },
+    {
+      paraText: paragraphSnippet,
+      substrText: substring,
+      setFocus,
+    },
+  );
+}
+
+/**
+ * Select a substring by simulating a real mouse drag across it.
+ *
+ * Unlike `selectSubstringInParagraph`, which performs a purely
+ * programmatic PM selection, this helper moves the visible cursor
+ * overlay from one viewport coordinate to the next and fires actual
+ * `mousedown` / `mousemove` / `mouseup` events. Viewers watching a
+ * recorded demo see the cursor travel over the phrase while the
+ * selection paint follows along - this is what the user expects when
+ * they say "I want to *see* Alice select text".
+ *
+ * Robustness:
+ * - The drag can end up off by a glyph at the very edge (subpixel
+ *   hit testing differs per platform), so after `mouseup` we always
+ *   correct the PM selection to the exact {from, to} computed from
+ *   the DOM TreeWalker mapping. That way the bold / link / agent-
+ *   focus action always operates on the intended range.
+ * - Returns null if the paragraph or substring can't be found; the
+ *   caller can then fall back to `selectSubstringInParagraph`.
+ *
+ * The `setAgentFocus` flag matches the sibling helper: leave it
+ * false for user-driven bubble toolbar interactions so the agent
+ * label doesn't flash up while the chat panel is closed.
+ */
+export async function dragSelectSubstringInParagraph(
+  page: Page,
+  paragraphSnippet: string,
+  substring: string,
+  opts: { setAgentFocus?: boolean } = {},
+): Promise<{ from: number; to: number } | null> {
+  const setFocus = opts.setAgentFocus ?? false;
+
+  const rect = await page.evaluate(
+    ({ paraText, substrText }) => {
+      const root = document.querySelector(".ProseMirror") as HTMLElement | null;
+      if (!root) return null;
+      const para =
+        (Array.from(root.querySelectorAll("p")).find((p) =>
+          (p.textContent || "").includes(paraText),
+        ) as HTMLElement | undefined) ?? null;
+      if (!para) return null;
+      // "auto" (instant) rather than "smooth": smooth scroll is
+      // still animating when our caller's humanMove lands on the
+      // drag-start coordinates, which means the rects we compute
+      // here reference an onscreen position that has already
+      // shifted - the pointer ends up a few lines above/below the
+      // phrase and the browser-native selection sweep picks up
+      // the heading above or the math block below. Instant scroll
+      // pins the layout BEFORE we measure.
+      para.scrollIntoView({ behavior: "auto", block: "center" });
+
+      const text = para.textContent || "";
+      const idx = text.indexOf(substrText);
+      if (idx === -1) return null;
+
+      const walker = document.createTreeWalker(para, NodeFilter.SHOW_TEXT);
+      let walked = 0;
+      let startNode: Text | null = null;
+      let startOffset = 0;
+      let endNode: Text | null = null;
+      let endOffset = 0;
+      while (walker.nextNode()) {
+        const node = walker.currentNode as Text;
+        const len = node.nodeValue?.length ?? 0;
+        if (!startNode && walked + len > idx) {
+          startNode = node;
+          startOffset = idx - walked;
+        }
+        if (walked + len >= idx + substrText.length) {
+          endNode = node;
+          endOffset = idx + substrText.length - walked;
+          break;
+        }
+        walked += len;
+      }
+      if (!startNode || !endNode) return null;
+
+      const range = document.createRange();
+      try {
+        range.setStart(startNode, startOffset);
+        range.setEnd(endNode, endOffset);
+      } catch {
+        return null;
+      }
+      // Some layouts split the range across two lines; we always
+      // take the first client rect as the start and the last as
+      // the end, so the drag follows the visual reading order.
+      const rects = Array.from(range.getClientRects());
+      if (rects.length === 0) return null;
+      const first = rects[0];
+      const last = rects[rects.length - 1];
+
+      const editor = (
+        window as unknown as {
+          __demoEditor?: {
+            view: {
+              posAtDOM: (node: Node, offset: number, bias?: number) => number;
+            };
+          };
+        }
+      ).__demoEditor;
+      if (!editor) return null;
+      let from: number;
+      let to: number;
+      try {
+        from = editor.view.posAtDOM(startNode, startOffset, -1);
+        to = editor.view.posAtDOM(endNode, endOffset, 1);
+      } catch {
+        return null;
+      }
+      if (!Number.isFinite(from) || !Number.isFinite(to) || !(to > from)) {
+        return null;
+      }
+
+      return {
+        from,
+        to,
+        startX: first.left + 2,
+        startY: first.top + first.height / 2,
+        endX: last.right - 2,
+        endY: last.top + last.height / 2,
+      };
+    },
     { paraText: paragraphSnippet, substrText: substring },
   );
+
+  if (!rect) return null;
+
+  // Post-scroll beat so the layout is 100% settled. Even with
+  // behavior: "auto", a scroll triggers a synchronous reflow but
+  // the next paint can still shift things by a frame.
+  await page.waitForTimeout(180);
+
+  // Phase 1: visible-cursor approach to the start of the phrase.
+  // NO mousedown - we are NOT doing a browser-native drag. A real
+  // drag is fragile: mouse.down 1px outside the first glyph can
+  // land on the paragraph margin and the sweep to the endpoint
+  // picks up the heading above or the math atom below, which is
+  // exactly the "3 lines with bits of title and text" artefact
+  // users see. Instead, we animate the overlay cursor over the
+  // text and extend the PM selection step-by-step as the cursor
+  // moves, so the selection paint GROWS under the pointer like
+  // a real drag but without the pixel-brittleness.
+  await humanMove(page, rect.startX, rect.startY, {
+    steps: 22,
+    jitter: 0,
+  });
+  await pause(120, 180);
+
+  // Phase 2: collapse the selection at the start of the phrase. The
+  // viewer reads the cursor "clicking" here.
+  await page.evaluate(
+    ({ from }) => {
+      const editor = (
+        window as unknown as {
+          __demoEditor?: {
+            commands: {
+              focus: () => boolean;
+              setTextSelection: (args: { from: number; to: number }) => boolean;
+            };
+          };
+        }
+      ).__demoEditor;
+      if (!editor) return;
+      editor.commands.focus();
+      editor.commands.setTextSelection({ from, to: from });
+    },
+    { from: rect.from },
+  );
+
+  // Phase 3: progressive drag - interpolate cursor position AND
+  // selection endpoint together, so the highlight grows under the
+  // moving cursor in sync. `page.mouse.move` straight (no bezier)
+  // because a curved path during a drag would dip into adjacent
+  // lines. Each step updates the PM selection to
+  // {from, to: from + (to-from) * t} so the highlight progression
+  // maps 1:1 to pointer progression. Any character drift at the
+  // final step is patched by the canonical setTextSelection below.
+  const dx = rect.endX - rect.startX;
+  const dy = rect.endY - rect.startY;
+  const distance = Math.hypot(dx, dy);
+  const selLen = rect.to - rect.from;
+  const glideSteps = Math.max(18, Math.min(40, Math.round(distance / 14)));
+  for (let i = 1; i <= glideSteps; i++) {
+    const t = i / glideSteps;
+    const x = rect.startX + dx * t;
+    const y = rect.startY + dy * t;
+    await page.mouse.move(x, y, { steps: 2 });
+    const midTo = rect.from + Math.round(selLen * t);
+    await page.evaluate(
+      ({ from, to }) => {
+        const editor = (
+          window as unknown as {
+            __demoEditor?: {
+              commands: {
+                setTextSelection: (args: {
+                  from: number;
+                  to: number;
+                }) => boolean;
+              };
+            };
+          }
+        ).__demoEditor;
+        editor?.commands.setTextSelection({ from, to });
+      },
+      { from: rect.from, to: midTo },
+    );
+    await page.waitForTimeout(14 + Math.floor(Math.random() * 14));
+  }
+
+  // Phase 4: canonical setTextSelection to guarantee the final
+  // range is pixel-perfect (rounding during interpolation can land
+  // 1 char short).
+  await page.evaluate(
+    ({ from, to }) => {
+      const editor = (
+        window as unknown as {
+          __demoEditor?: {
+            commands: {
+              setTextSelection: (args: { from: number; to: number }) => boolean;
+            };
+          };
+        }
+      ).__demoEditor;
+      editor?.commands.setTextSelection({ from, to });
+    },
+    { from: rect.from, to: rect.to },
+  );
+
+  // Phase 5: optional AgentFocus broadcast (chat-driven paths set
+  // this, pure-editor paths leave it false so the agent label
+  // doesn't pop up out of context).
+  if (setFocus) {
+    await page.evaluate(
+      ({ from, to }) => {
+        const editor = (
+          window as unknown as {
+            __demoEditor?: {
+              commands: {
+                setAgentFocus: (args: { from: number; to: number }) => boolean;
+              };
+            };
+          }
+        ).__demoEditor;
+        editor?.commands.setAgentFocus({ from, to });
+      },
+      { from: rect.from, to: rect.to },
+    );
+  }
+
+  // Resync cursor tracker. The progressive loop used page.mouse.move
+  // directly, which bypasses humanMove's internal lastX/lastY
+  // updates. Without this reset the next humanMove would glide
+  // from a stale origin.
+  resetMouseState(rect.endX, rect.endY);
+
+  return { from: rect.from, to: rect.to };
 }
 
 /**

backend/demo/lib/yjs-client.ts

@@ -0,0 +1,788 @@
+/**
+ * lib/yjs-client.ts
+ *
+ * Robust Yjs-level peer for demo personas (bob, carol).
+ *
+ * Why this exists
+ * ---------------
+ * The original demo drove Bob and Carol through Playwright + Chromium:
+ *   - each persona ran an actual editor in a real browser,
+ *   - Playwright "typed" characters into the DOM,
+ *   - positions were tracked through MappablePosition / slot claims.
+ *
+ * That works but is fragile: ProseMirror input rules, concurrent
+ * AgentRewrite animations, and DOM-level selection changes all
+ * introduce races that occasionally drop Bob's text into the wrong
+ * slot or delete half a paragraph.
+ *
+ * Yjs (the CRDT Tiptap uses for collaboration) is built exactly for
+ * this kind of headless peer. A Node process can open a
+ * `HocuspocusProvider` against the same server the browsers connect
+ * to, sync the shared `Y.Doc`, and mutate it directly through
+ * `Y.XmlElement` / `Y.XmlText` APIs. Every mutation is atomic at
+ * the CRDT level and shows up in Alice's editor in real time, with
+ * zero input-rule surprises and zero PM position drift.
+ *
+ * This module exposes:
+ *   - `connectPersona()` - open a Hocuspocus connection as a named
+ *     peer, wait for initial sync, return a handle with the shared
+ *     fragment, citations map, and frontmatter helpers.
+ *   - a small DOM-like helper set to build paragraphs, headings,
+ *     inline math, citations, and to type text character by
+ *     character (so Alice visually sees the peer typing).
+ */
+import { WebSocket } from "ws";
+import { HocuspocusProvider } from "@hocuspocus/provider";
+import * as Y from "yjs";
+
+// The Hocuspocus provider expects a DOM `WebSocket` global; Node
+// doesn't ship one so we plumb `ws` in before any provider is
+// constructed. Idempotent.
+if (!(globalThis as unknown as { WebSocket?: unknown }).WebSocket) {
+  (globalThis as unknown as { WebSocket: unknown }).WebSocket = WebSocket;
+}
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface PersonaUser {
+  name: string;
+  color: string;
+  avatarUrl?: string;
+}
+
+export interface PersonaHandle {
+  ydoc: Y.Doc;
+  provider: HocuspocusProvider;
+  /**
+   * Shared editor content (Tiptap `field: "default"`).
+   */
+  fragment: Y.XmlFragment;
+  /**
+   * Citations keyed by citation-key (Vaswani2017 -> {title, authors, ...}).
+   */
+  citationsMap: Y.Map<unknown>;
+  /**
+   * Whole-article settings (primaryHue, etc.).
+   */
+  settingsMap: Y.Map<unknown>;
+  /**
+   * Frontmatter arrays (authors, affiliations, links).
+   */
+  frontmatter: {
+    scalars: Y.Map<unknown>;
+    authors: Y.Array<Author>;
+    affiliations: Y.Array<Affiliation>;
+    links: Y.Array<unknown>;
+  };
+  /**
+   * Cancel the awareness ticker / close the connection.
+   */
+  destroy: () => void;
+}
+
+export interface Author {
+  name: string;
+  url?: string;
+  affiliations: number[];
+}
+
+export interface Affiliation {
+  name: string;
+  url?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Connection
+// ---------------------------------------------------------------------------
+
+/**
+ * Open a Hocuspocus connection as a named peer and resolve once the
+ * server has finished the initial sync (so the Y.Doc mirrors what
+ * Alice / the disk state contain).
+ */
+export async function connectPersona(args: {
+  url: string;
+  docName: string;
+  user: PersonaUser;
+  token?: string;
+  syncTimeoutMs?: number;
+}): Promise<PersonaHandle> {
+  const ydoc = new Y.Doc();
+  const provider = new HocuspocusProvider({
+    url: args.url,
+    name: args.docName,
+    document: ydoc,
+    token: args.token ?? "",
+  });
+
+  // Broadcast ourselves as a collaborator so the other peers see a
+  // name + color in their byline / awareness list immediately. The
+  // Tiptap CollaborationCursor extension reads awareness.user on
+  // every update, so this is all that's needed for the avatar bubble
+  // to appear.
+  provider.awareness?.setLocalStateField("user", args.user);
+
+  await new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(
+      () => reject(new Error(`persona "${args.user.name}" sync timeout`)),
+      args.syncTimeoutMs ?? 15_000,
+    );
+    provider.on("synced", () => {
+      clearTimeout(timer);
+      resolve();
+    });
+  });
+
+  const fragment = ydoc.getXmlFragment("default");
+  const citationsMap = ydoc.getMap("citations");
+  const settingsMap = ydoc.getMap("settings");
+  const frontmatter = {
+    scalars: ydoc.getMap("frontmatter"),
+    authors: ydoc.getArray<Author>("frontmatter.authors"),
+    affiliations: ydoc.getArray<Affiliation>("frontmatter.affiliations"),
+    links: ydoc.getArray<unknown>("frontmatter.links"),
+  };
+
+  const destroy = () => {
+    try {
+      provider.destroy();
+    } catch {
+      /* provider may already be detached */
+    }
+    try {
+      ydoc.destroy();
+    } catch {
+      /* noop */
+    }
+  };
+
+  return {
+    ydoc,
+    provider,
+    fragment,
+    citationsMap,
+    settingsMap,
+    frontmatter,
+    destroy,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Inline content builders
+// ---------------------------------------------------------------------------
+
+/**
+ * Describes a chunk of inline content. `text` entries can carry
+ * marks like `bold` or `link`; `inlineMath` entries render as a
+ * KaTeX node.
+ */
+export type InlineItem =
+  | { type: "text"; text: string; marks?: InlineMarks }
+  | { type: "inlineMath"; latex: string }
+  | { type: "citation"; key: string; label: string };
+
+export interface InlineMarks {
+  bold?: boolean;
+  italic?: boolean;
+  underline?: boolean;
+  code?: boolean;
+  link?: {
+    href: string;
+    target?: string;
+    rel?: string;
+    class?: string;
+    title?: string | null;
+  };
+}
+
+/**
+ * Convert our plain JS `InlineMarks` into the Yjs attribute object
+ * expected by `Y.XmlText.insert(index, text, attrs)`. Mirrors the
+ * shape Tiptap's y-prosemirror binding serializes (empty objects
+ * for booleans, full attr maps for parametrized marks).
+ */
+function marksToAttrs(
+  marks: InlineMarks | undefined,
+): Record<string, unknown> | undefined {
+  if (!marks) return undefined;
+  const out: Record<string, unknown> = {};
+  if (marks.bold) out.bold = {};
+  if (marks.italic) out.italic = {};
+  if (marks.underline) out.underline = {};
+  if (marks.code) out.code = {};
+  if (marks.link) {
+    out.link = {
+      href: marks.link.href,
+      target: marks.link.target ?? "_blank",
+      rel: marks.link.rel ?? "noopener noreferrer nofollow",
+      class: marks.link.class ?? "editor-link",
+      title: marks.link.title ?? null,
+    };
+  }
+  return Object.keys(out).length ? out : undefined;
+}
+
+/**
+ * Append inline content to the END of a paragraph Y.XmlElement.
+ * Text chunks merge into adjacent Y.XmlText when possible (so marks
+ * stay contiguous); non-text items are inserted as standalone
+ * children.
+ */
+export function appendInline(
+  paragraph: Y.XmlElement,
+  items: InlineItem[],
+): void {
+  for (const item of items) {
+    if (item.type === "text") {
+      const attrs = marksToAttrs(item.marks);
+      // Try to reuse the trailing Y.XmlText node - merging marks
+      // with a previous text run gives Tiptap a cleaner delta and
+      // avoids spurious splits that the ProseMirror renderer has
+      // to collapse afterwards.
+      const last = paragraph.toArray().at(-1);
+      if (last instanceof Y.XmlText) {
+        last.insert(last.length, item.text, attrs);
+      } else {
+        // Attach first, then insert - Y.XmlText emits observer
+        // events on `.insert`, and doing that while detached
+        // triggers "Invalid access: Add Yjs type to a document
+        // before reading data".
+        const t = new Y.XmlText();
+        paragraph.push([t]);
+        t.insert(0, item.text, attrs);
+      }
+    } else if (item.type === "inlineMath") {
+      const el = new Y.XmlElement("inlineMath");
+      paragraph.push([el]);
+      el.setAttribute("latex", item.latex);
+    } else if (item.type === "citation") {
+      const el = new Y.XmlElement("citation");
+      paragraph.push([el]);
+      el.setAttribute("key", item.key);
+      el.setAttribute("label", item.label);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Block builders
+// ---------------------------------------------------------------------------
+
+/**
+ * Create an empty, detached `<paragraph/>` Y.XmlElement. Caller
+ * must attach it (via `frag.push([p])` / `frag.insert(n, [p])`)
+ * before any content insertion. `appendInline` and
+ * `typeIntoParagraph` take care of creating the first Y.XmlText
+ * child lazily after attachment, so an empty paragraph is a valid
+ * seed for all writer helpers below.
+ */
+export function buildEmptyParagraph(): Y.XmlElement {
+  return new Y.XmlElement("paragraph");
+}
+
+/**
+ * Build a paragraph pre-populated with inline content. Requires a
+ * parent to insert into so the Y.XmlText children can be attached
+ * immediately (a detached Y.XmlText insert would throw the
+ * "Invalid access" warning). The new paragraph is pushed onto the
+ * end of `parent`.
+ */
+export function pushParagraphInto(
+  parent: Y.XmlFragment | Y.XmlElement,
+  items: InlineItem[] = [],
+): Y.XmlElement {
+  const el = new Y.XmlElement("paragraph");
+  parent.push([el]);
+  if (items.length) appendInline(el, items);
+  return el;
+}
+
+// ---------------------------------------------------------------------------
+// Top-level navigation
+// ---------------------------------------------------------------------------
+
+/**
+ * Find the index of the nth occurrence of an H2 whose textContent
+ * matches `text` (case-insensitive). Returns -1 if not found.
+ */
+export function findHeadingIndex(
+  frag: Y.XmlFragment,
+  text: string,
+  level: number = 2,
+): number {
+  const wanted = text.trim().toLowerCase();
+  const children = frag.toArray();
+  for (let i = 0; i < children.length; i++) {
+    const c = children[i];
+    if (!(c instanceof Y.XmlElement)) continue;
+    if (c.nodeName !== "heading") continue;
+    if (Number(c.getAttribute("level")) !== level) continue;
+    const textContent = c
+      .toArray()
+      .filter((n): n is Y.XmlText => n instanceof Y.XmlText)
+      .map((n) => n.toString())
+      .join("");
+    if (textContent.trim().toLowerCase() === wanted) return i;
+  }
+  return -1;
+}
+
+/**
+ * Return the Nth non-heading child that sits right after
+ * `headingText`, scanning top-level fragment children. Creates
+ * empty paragraphs on demand to satisfy `slotIndex` if the section
+ * exists but doesn't have enough slots yet (useful when a peer
+ * lands ahead of the scaffold writer).
+ */
+export function claimSlotAfterHeading(
+  frag: Y.XmlFragment,
+  headingText: string,
+  slotIndex: number,
+): Y.XmlElement | null {
+  const headingIdx = findHeadingIndex(frag, headingText);
+  if (headingIdx === -1) return null;
+
+  const children = frag.toArray();
+  // Collect section slots up to the next H-level boundary.
+  const slots: { el: Y.XmlElement; fragIndex: number }[] = [];
+  for (let i = headingIdx + 1; i < children.length; i++) {
+    const c = children[i];
+    if (!(c instanceof Y.XmlElement)) continue;
+    if (c.nodeName === "heading") break;
+    slots.push({ el: c, fragIndex: i });
+  }
+
+  if (slots[slotIndex]) return slots[slotIndex].el;
+
+  // Section is present but too few slots. Grow it by inserting
+  // empty paragraphs right after the last slot we found (or right
+  // after the heading if the section was bare). Elements are
+  // minted detached, then pushed as a single batch via Y.insert
+  // so attribute writes don't emit detached-node warnings.
+  const insertAt = slots.length
+    ? slots[slots.length - 1].fragIndex + 1
+    : headingIdx + 1;
+  const needed = slotIndex + 1 - slots.length;
+  const fresh: Y.XmlElement[] = [];
+  for (let i = 0; i < needed; i++) {
+    fresh.push(new Y.XmlElement("paragraph"));
+  }
+  frag.insert(insertAt, fresh);
+  return fresh[needed - 1];
+}
+
+/**
+ * Replace (or create) the paragraph at fragment index `slotIndex`
+ * within a section with a `blockMath` atom carrying the given
+ * LaTeX. `blockMath` is a Tiptap atom: nodeName="blockMath", no
+ * children, single `latex` attribute (matches
+ * @tiptap/extension-mathematics/BlockMath.ts). The frontend
+ * NodeView picks it up and renders KaTeX the moment the CRDT
+ * sync lands in Alice's editor.
+ *
+ * Using an atomic replace (delete slot + insert blockMath) keeps
+ * the insertion visually "crisp" on camera: no half-parsed LaTeX
+ * intermediate state, no input-rule roundtrip.
+ */
+export function writeBlockMathAtSlot(
+  frag: Y.XmlFragment,
+  headingText: string,
+  slotIndex: number,
+  latex: string,
+): Y.XmlElement | null {
+  const headingIdx = findHeadingIndex(frag, headingText);
+  if (headingIdx === -1) return null;
+
+  const children = frag.toArray();
+  // Collect slot fragment indices up to the next heading boundary.
+  const slots: number[] = [];
+  for (let i = headingIdx + 1; i < children.length; i++) {
+    const c = children[i];
+    if (!(c instanceof Y.XmlElement)) continue;
+    if (c.nodeName === "heading") break;
+    slots.push(i);
+  }
+
+  const block = new Y.XmlElement("blockMath");
+  frag.doc?.transact(() => {
+    if (slots[slotIndex] !== undefined) {
+      frag.delete(slots[slotIndex], 1);
+      frag.insert(slots[slotIndex], [block]);
+    } else {
+      // Section exists but doesn't have a slot at slotIndex yet.
+      // Pad with empty paragraphs then append the blockMath so
+      // downstream slot indices stay aligned with the scaffold.
+      const insertAt = slots.length
+        ? slots[slots.length - 1] + 1
+        : headingIdx + 1;
+      const pad = slotIndex - slots.length;
+      const batch: Y.XmlElement[] = [];
+      for (let k = 0; k < pad; k++) batch.push(new Y.XmlElement("paragraph"));
+      batch.push(block);
+      frag.insert(insertAt, batch);
+    }
+    block.setAttribute("latex", latex);
+  });
+  return block;
+}
+
+/**
+ * Wait until `predicate(fragment)` returns true, polling on every
+ * fragment update. Used to gate a peer on "Alice has written the
+ * scaffold" (`findHeadingIndex(frag, "The recipe") !== -1`).
+ */
+export async function waitForCondition(
+  frag: Y.XmlFragment,
+  predicate: () => boolean,
+  timeoutMs: number = 30_000,
+): Promise<boolean> {
+  if (predicate()) return true;
+  return new Promise<boolean>((resolve) => {
+    let done = false;
+    const finish = (v: boolean) => {
+      if (done) return;
+      done = true;
+      frag.unobserveDeep(onChange);
+      clearTimeout(timer);
+      resolve(v);
+    };
+    const onChange = () => {
+      try {
+        if (predicate()) finish(true);
+      } catch {
+        /* predicate may temporarily throw while the doc is mid-
+         * mutation; just retry on the next event */
+      }
+    };
+    frag.observeDeep(onChange);
+    const timer = setTimeout(() => finish(false), timeoutMs);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Text "typing" (human-paced)
+// ---------------------------------------------------------------------------
+
+export interface TypingOptions {
+  /**
+   * Characters per second (roughly). Default 24 cps ≈ a fast touch
+   * typist.
+   */
+  cps?: number;
+  /**
+   * Jitter on the inter-keystroke delay (0..1). Default 0.35.
+   */
+  jitter?: number;
+  /**
+   * If set, group keystrokes of that many chars into one Y
+   * transaction to keep Alice's render smooth without killing the
+   * "typing" feel. Default 1 (every char is its own tick).
+   */
+  chunkSize?: number;
+}
+
+export function sleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+/**
+ * Broadcast a Tiptap-compatible cursor position through awareness.
+ *
+ * `yCursorPlugin` (from `@tiptap/y-tiptap`) reads `awareness.cursor`
+ * as `{anchor, head}`, each being a JSON-serialized Yjs relative
+ * position. Any peer that sets those two fields will have its caret
+ * rendered inside every other peer's editor - that's exactly the
+ * "floating Bob Mercier / Carol Dubois cursors" Alice sees during
+ * normal human collaboration.
+ *
+ * We build the relative position from the target Y.XmlText node +
+ * offset directly (no ProseMirror state involved), which is safe for
+ * headless Node peers that don't have an editor.
+ */
+export function setAwarenessCursor(
+  handle: PersonaHandle,
+  node: Y.XmlText,
+  offset: number,
+): void {
+  try {
+    const rel = Y.createRelativePositionFromTypeIndex(node, offset, -1);
+    const json = Y.relativePositionToJSON(rel);
+    handle.provider.awareness?.setLocalStateField("cursor", {
+      anchor: json,
+      head: json,
+    });
+  } catch {
+    /* type not yet attached to the doc; skip this tick, caller will
+     * retry on the next chunk */
+  }
+}
+
+/**
+ * Clear the broadcast cursor (peer has nothing selected / is idle).
+ * Call this between scenes so Alice doesn't see a ghost caret
+ * lingering after a persona finishes typing.
+ */
+export function clearAwarenessCursor(handle: PersonaHandle): void {
+  handle.provider.awareness?.setLocalStateField("cursor", null);
+}
+
+/**
+ * Insert `chunk` at the end of `paragraph`, reusing the trailing
+ * Y.XmlText run when possible. Returns the Y.XmlText the chunk
+ * landed in plus the offset AFTER the insert, so callers can
+ * broadcast an up-to-date cursor position right after the write.
+ */
+function pushChunkIntoParagraph(
+  paragraph: Y.XmlElement,
+  chunk: string,
+  attrs: Record<string, unknown> | undefined,
+): { node: Y.XmlText; offset: number } {
+  const last = paragraph.toArray().at(-1);
+  if (last instanceof Y.XmlText) {
+    const base = last.length;
+    last.insert(base, chunk, attrs);
+    return { node: last, offset: base + chunk.length };
+  }
+  // Attach the XmlText BEFORE inserting: Y.XmlText.insert emits
+  // observer events, and firing those while detached throws the
+  // "Invalid access" warning even though the end result is
+  // correct.
+  const t = new Y.XmlText();
+  paragraph.push([t]);
+  t.insert(0, chunk, attrs);
+  return { node: t, offset: chunk.length };
+}
+
+/**
+ * Append text, chunk by chunk, to a paragraph's trailing Y.XmlText
+ * node with human-like cadence. Each chunk is a real Yjs insert
+ * that propagates to Alice, so she sees the text stream in at a
+ * natural speed.
+ *
+ * Side effect: after every chunk we also broadcast the peer's
+ * cursor through awareness (if `handle` is provided). That's what
+ * makes Bob's / Carol's caret visibly travel along their paragraph
+ * in Alice's editor while they type, same as a human collaborator.
+ */
+export async function typeIntoParagraph(
+  paragraph: Y.XmlElement,
+  text: string,
+  options: TypingOptions = {},
+  marks?: InlineMarks,
+  handle?: PersonaHandle,
+): Promise<void> {
+  const cps = options.cps ?? 24;
+  const jitter = options.jitter ?? 0.35;
+  const chunkSize = Math.max(1, options.chunkSize ?? 1);
+  const baseDelay = 1000 / cps;
+  const attrs = marksToAttrs(marks);
+
+  let i = 0;
+  while (i < text.length) {
+    const take = Math.min(chunkSize, text.length - i);
+    const chunk = text.slice(i, i + take);
+    const landed = pushChunkIntoParagraph(paragraph, chunk, attrs);
+    if (handle) setAwarenessCursor(handle, landed.node, landed.offset);
+    i += take;
+    const jitterMul = 1 + (Math.random() * 2 - 1) * jitter;
+    await sleep(Math.max(5, baseDelay * jitterMul));
+  }
+}
+
+/**
+ * Like `typeIntoParagraph` but inserts an inline node (math,
+ * citation) as a single Yjs op after an optional small pause - so
+ * the viewer experiences the formula "clicking in" rather than
+ * appearing with no warning. When `handle` is provided the peer's
+ * awareness cursor is nudged to the end of the paragraph after the
+ * insert.
+ */
+export async function insertInlineNode(
+  paragraph: Y.XmlElement,
+  item:
+    | { type: "inlineMath"; latex: string }
+    | { type: "citation"; key: string; label: string },
+  preDelayMs: number = 0,
+  handle?: PersonaHandle,
+): Promise<void> {
+  if (preDelayMs > 0) await sleep(preDelayMs);
+  appendInline(paragraph, [item]);
+  if (handle) broadcastCursorAtEnd(handle, paragraph);
+}
+
+/**
+ * Broadcast the peer's awareness cursor at the end of `paragraph`.
+ * Useful after bulk inline inserts (citation chip, inline math) that
+ * don't go through `typeIntoParagraph`'s per-chunk broadcasting.
+ */
+export function broadcastCursorAtEnd(
+  handle: PersonaHandle,
+  paragraph: Y.XmlElement,
+): void {
+  const last = paragraph.toArray().at(-1);
+  if (last instanceof Y.XmlText) {
+    setAwarenessCursor(handle, last, last.length);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Frontmatter helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Add an author + (optionally) a new affiliation atomically.
+ * Mirrors `frontmatterStore.addAuthor` in the frontend but runs
+ * directly against the shared Y.Arrays so there's no race between
+ * "affiliation index allocation" and "author push".
+ */
+export function addAuthorRecord(
+  handle: PersonaHandle,
+  args: {
+    name: string;
+    url?: string;
+    newAffiliation?: { name: string; url?: string };
+    existingAffiliationIndices?: number[];
+  },
+): void {
+  const { ydoc, frontmatter } = handle;
+  ydoc.transact(() => {
+    let affIndices = args.existingAffiliationIndices ?? [];
+    if (args.newAffiliation) {
+      frontmatter.affiliations.push([args.newAffiliation]);
+      // addAffiliation returns 1-based index in the frontend store,
+      // so we match that convention: after push, length equals the
+      // new entry's 1-based index.
+      affIndices = [...affIndices, frontmatter.affiliations.length];
+    }
+    frontmatter.authors.push([
+      {
+        name: args.name,
+        url: args.url,
+        affiliations: affIndices,
+      },
+    ]);
+  });
+}
+
+/**
+ * Patch the URL of an existing affiliation by 1-based index, matching
+ * the convention used everywhere else in the frontmatter. Used by the
+ * "other" persona to backfill a `url` on the affiliation seeded by
+ * the main agent (e.g. Alice adds "Hugging Face" with no URL via the
+ * Playwright modal, then Bob attaches `https://huggingface.co` to it
+ * so the byline renders the affiliation as a real link).
+ *
+ * Done inside a single Yjs transaction so the change shows up atomically
+ * on every peer (no flicker between "name only" and "name + url").
+ */
+export function setAffiliationUrl(
+  handle: PersonaHandle,
+  oneBasedIndex: number,
+  url: string,
+): void {
+  const { ydoc, frontmatter } = handle;
+  const idx = oneBasedIndex - 1;
+  const current = frontmatter.affiliations.get(idx);
+  if (!current) return;
+  ydoc.transact(() => {
+    frontmatter.affiliations.delete(idx, 1);
+    frontmatter.affiliations.insert(idx, [{ ...current, url }]);
+  });
+}
+
+/**
+ * Wait for at least `n` affiliations to be present in the shared
+ * frontmatter. Used by the "other" persona to gate on the main agent
+ * having seeded the Hugging Face affiliation before reusing its index.
+ */
+export async function waitForAffiliationCount(
+  handle: PersonaHandle,
+  minCount: number,
+  timeoutMs: number = 30_000,
+): Promise<boolean> {
+  if (handle.frontmatter.affiliations.length >= minCount) return true;
+  return new Promise<boolean>((resolve) => {
+    let done = false;
+    const onChange = () => {
+      if (done) return;
+      if (handle.frontmatter.affiliations.length >= minCount) {
+        done = true;
+        handle.frontmatter.affiliations.unobserve(onChange);
+        clearTimeout(timer);
+        resolve(true);
+      }
+    };
+    handle.frontmatter.affiliations.observe(onChange);
+    const timer = setTimeout(() => {
+      if (done) return;
+      done = true;
+      handle.frontmatter.affiliations.unobserve(onChange);
+      resolve(false);
+    }, timeoutMs);
+  });
+}
+
+/**
+ * Wait for at least `n` authors to be present in the shared
+ * frontmatter. Useful for persona gating ("Bob waits for Alice to
+ * seed the first author before appending his own").
+ */
+export async function waitForAuthorCount(
+  handle: PersonaHandle,
+  minCount: number,
+  timeoutMs: number = 30_000,
+): Promise<boolean> {
+  if (handle.frontmatter.authors.length >= minCount) return true;
+  return new Promise<boolean>((resolve) => {
+    let done = false;
+    const onChange = () => {
+      if (done) return;
+      if (handle.frontmatter.authors.length >= minCount) {
+        done = true;
+        handle.frontmatter.authors.unobserve(onChange);
+        clearTimeout(timer);
+        resolve(true);
+      }
+    };
+    handle.frontmatter.authors.observe(onChange);
+    const timer = setTimeout(() => {
+      if (done) return;
+      done = true;
+      handle.frontmatter.authors.unobserve(onChange);
+      resolve(false);
+    }, timeoutMs);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Citations
+// ---------------------------------------------------------------------------
+
+export interface CitationEntry {
+  id: string;
+  "citation-key": string;
+  type: string;
+  title?: string;
+  author?: Array<{ family: string; given: string }>;
+  issued?: { "date-parts": number[][] };
+  "container-title"?: string;
+  volume?: string;
+  URL?: string;
+  DOI?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Register a citation entry in the shared `citationsMap`. Tiptap's
+ * frontend listens on this map; a citation chip with matching
+ * `key` attr will resolve to the entry automatically.
+ */
+export function registerCitation(
+  handle: PersonaHandle,
+  key: string,
+  entry: CitationEntry,
+): void {
+  handle.citationsMap.set(key, entry);
+}

backend/demo/probe-ydoc.ts

@@ -0,0 +1,72 @@
+/**
+ * One-shot probe: connect to the live Hocuspocus server as an
+ * anonymous peer, dump the structure of the shared Y.XmlFragment
+ * so we know exactly what node names / attrs / marks Tiptap emits.
+ */
+import { WebSocket } from "ws";
+import { HocuspocusProvider } from "@hocuspocus/provider";
+import * as Y from "yjs";
+
+(globalThis as any).WebSocket = WebSocket;
+
+function describeText(t: Y.XmlText): string {
+  // Y.XmlText.toDelta() returns [{insert: "Hello"}, {insert: "world", attributes: {bold: {}}}, ...]
+  // which is the richest format for marks.
+  return JSON.stringify((t as any).toDelta(), null, 2);
+}
+
+function describeElement(el: Y.XmlElement, indent: string = ""): void {
+  const attrs = el.getAttributes();
+  console.log(
+    `${indent}<${el.nodeName}${
+      Object.keys(attrs).length ? " " + JSON.stringify(attrs) : ""
+    }> (${el.length} children)`,
+  );
+  for (const child of el.toArray()) {
+    if (child instanceof Y.XmlElement) {
+      describeElement(child, indent + "  ");
+    } else if (child instanceof Y.XmlText) {
+      console.log(`${indent}  [text] ${describeText(child)}`);
+    }
+  }
+}
+
+async function run() {
+  const ydoc = new Y.Doc();
+  const provider = new HocuspocusProvider({
+    url: "ws://localhost:5678/collab",
+    name: "default",
+    document: ydoc,
+    token: "",
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error("sync timeout")), 10_000);
+    provider.on("synced", () => {
+      clearTimeout(timer);
+      resolve();
+    });
+  });
+
+  console.log("=== synced ===");
+
+  const frag = ydoc.getXmlFragment("default");
+  console.log(`XmlFragment("default").length = ${frag.length}\n`);
+
+  for (const child of frag.toArray()) {
+    if (child instanceof Y.XmlElement) {
+      describeElement(child);
+    } else if (child instanceof Y.XmlText) {
+      console.log(`[text] ${describeText(child)}`);
+    }
+  }
+
+  provider.destroy();
+  ydoc.destroy();
+  process.exit(0);
+}
+
+run().catch((err) => {
+  console.error("probe failed:", err);
+  process.exit(1);
+});

backend/demo/showcase.ts

@@ -71,6 +71,7 @@ import {
   startScreenRecording,
   type ScreenRecording,
 } from "./lib/recording.js";
+import { connectPersona, type PersonaHandle as YjsPersona } from "./lib/yjs-client.js";
 import type { Page } from "playwright";
 
 // ---------------------------------------------------------------------------
@@ -92,23 +93,18 @@ const SLOT_EXPECTATIONS: Array<{
   mustInclude: string;
   owner: "alice" | "bob" | "carol";
 }> = [
-  // Bob - "The recipe"
+  // Bob - "The recipe" (4 slots: def, block-math, softmax, multi-head)
   {
     heading: "The recipe",
     slot: 0,
     mustInclude: "Attention lets a token",
     owner: "bob",
   },
-  {
-    heading: "The recipe",
-    slot: 1,
-    mustInclude: "softmax",
-    owner: "bob",
-  },
+  // slot 1 is a <blockMath> atom; checked separately below.
   {
     heading: "The recipe",
     slot: 2,
-    mustInclude: "The softmax turns those scores",
+    mustInclude: "softmax turns those similarity scores",
     owner: "bob",
   },
   {
@@ -155,45 +151,113 @@ const SLOT_EXPECTATIONS: Array<{
   },
 ];
 
-async function verifyFinalDoc(page: Page): Promise<void> {
-  const report = await page.evaluate(() => {
-    const root = document.querySelector(".ProseMirror") as HTMLElement | null;
-    if (!root) return null;
-
-    // Group siblings by heading: for each h2, collect every
-    // non-heading element until the next h2. Mirrors the slot
-    // layout the scaffolding helper produced.
-    const sections: Array<{
-      heading: string;
-      slots: string[];
-      slotTags: string[];
-    }> = [];
-    let current: { heading: string; slots: string[]; slotTags: string[] } | null =
-      null;
-    for (const el of Array.from(root.children)) {
-      if (el.tagName === "H2") {
-        if (current) sections.push(current);
-        current = {
-          heading: (el.textContent || "").trim(),
-          slots: [],
-          slotTags: [],
-        };
-      } else if (current && el.tagName !== "H1") {
-        current.slots.push((el.textContent || "").trim());
-        current.slotTags.push(el.tagName);
+/**
+ * Inspect the shared Y.XmlFragment directly (no browser needed)
+ * and return a flat "sections" view matching what the old
+ * DOM-based verifier produced, so `SLOT_EXPECTATIONS` keeps
+ * working unchanged.
+ */
+async function verifyFinalDoc(bob: YjsPersona): Promise<void> {
+  // We import yjs lazily here to avoid a top-level dep circle with
+  // `./lib/yjs-client.ts`; the verifier only runs once at the end
+  // of a demo so the extra dynamic import is cheap.
+  const Y = await import("yjs");
+
+  const sections: Array<{
+    heading: string;
+    slots: string[];
+    slotTags: string[];
+  }> = [];
+  let current: {
+    heading: string;
+    slots: string[];
+    slotTags: string[];
+  } | null = null;
+
+  // textContent for a Y.XmlElement: concatenate every descendant
+  // Y.XmlText, skipping inline atom nodes (inlineMath, citation)
+  // which have no textContent of their own but carry meaningful
+  // attributes. We still keep their node name in the tag so the
+  // flat text search below can spot a citation chip by inference.
+  // Y.XmlText.toString() serializes marks as XML tags (`<bold>foo</bold>`,
+  // `<link href="...">bar</link>`), which breaks "expected substring"
+  // checks like `"eight lines of PyTorch"` when a mark like link wraps
+  // the trailing word. We read the Delta format instead and only keep
+  // the `insert` text values: gives us the plain concatenated text a
+  // reader would see, mark attributes ignored.
+  const xmlTextToPlain = (t: Y.XmlText): string => {
+    const delta = t.toDelta() as Array<{ insert?: unknown }>;
+    let out = "";
+    for (const op of delta) {
+      if (typeof op.insert === "string") out += op.insert;
+    }
+    return out;
+  };
+  const textOf = (el: Y.XmlElement): string => {
+    // Atom nodes (`blockMath`, `inlineMath`) carry their whole
+    // payload on the `latex` attribute and have no children, so
+    // the child-walker below would see an empty slot. Surface the
+    // LaTeX verbatim when the slot IS an atom.
+    if (el.nodeName === "blockMath" || el.nodeName === "inlineMath") {
+      const latex = el.getAttribute("latex");
+      return typeof latex === "string" ? latex.replace(/\s+/g, " ").trim() : "";
+    }
+
+    let out = "";
+    const visit = (node: Y.XmlElement | Y.XmlText) => {
+      if (node instanceof Y.XmlText) {
+        out += xmlTextToPlain(node);
+      } else if (node instanceof Y.XmlElement) {
+        if (node.nodeName === "citation") {
+          const label = node.getAttribute("label");
+          if (typeof label === "string") out += label;
+        } else if (node.nodeName === "inlineMath" || node.nodeName === "blockMath") {
+          const latex = node.getAttribute("latex");
+          if (typeof latex === "string") out += latex;
+        } else {
+          for (const child of node.toArray()) visit(child as Y.XmlElement | Y.XmlText);
+        }
       }
+    };
+    for (const child of el.toArray()) {
+      visit(child as Y.XmlElement | Y.XmlText);
+    }
+    return out.replace(/\s+/g, " ").trim();
+  };
+
+  for (const child of bob.fragment.toArray()) {
+    if (!(child instanceof Y.XmlElement)) continue;
+    if (child.nodeName === "heading" && Number(child.getAttribute("level")) === 2) {
+      if (current) sections.push(current);
+      current = {
+        heading: textOf(child),
+        slots: [],
+        slotTags: [],
+      };
+    } else if (current) {
+      const tagMap: Record<string, string> = {
+        paragraph: "P",
+        codeBlock: "PRE",
+        heading: "H",
+        bibliography: "BIB",
+        blockMath: "MATH",
+      };
+      current.slots.push(textOf(child));
+      current.slotTags.push(tagMap[child.nodeName] ?? child.nodeName.toUpperCase());
     }
-    if (current) sections.push(current);
+  }
+  if (current) sections.push(current);
 
-    // Also grab the final doc as one big text blob so we can search
-    // for fragments wherever they may have ended up.
-    const flatText = (root.textContent || "").replace(/\s+/g, " ").trim();
+  const flatText = sections
+    .flatMap((s) => [s.heading, ...s.slots])
+    .join(" ")
+    .replace(/\s+/g, " ")
+    .trim();
 
-    return { sections, flatText };
-  });
+  const report = { sections, flatText };
 
-  if (!report) {
-    console.warn("[verify] no .ProseMirror root found on Bob's page");
+  if (!report.sections.length) {
+    console.warn("[verify] empty fragment, nothing to verify");
     return;
   }
 
@@ -270,6 +334,27 @@ async function verifyFinalDoc(page: Page): Promise<void> {
     }
   }
 
+  // Block math sanity check: "The recipe" slot 1 should be a
+  // <blockMath> atom carrying the attention formula. We grep the
+  // LaTeX source for the two signature substrings the formula
+  // always contains ("Attention" + "softmax") so a typo in the
+  // source string doesn't silently pass.
+  const recipe = report.sections.find((s) =>
+    s.heading.toLowerCase().includes("the recipe"),
+  );
+  if (recipe) {
+    const mathTag = recipe.slotTags[1];
+    const mathText = recipe.slots[1] ?? "";
+    const looksLikeFormula =
+      mathText.includes("Attention") && mathText.includes("softmax");
+    if (mathTag !== "MATH" || !looksLikeFormula) {
+      anomalies.push(
+        `bob: block math in "The recipe"[1] not recognized ` +
+          `(got tag=${mathTag}, latex="${mathText.slice(0, 60)}...")`,
+      );
+    }
+  }
+
   // Bibliography should exist (Bob's citation action creates it).
   if (!report.flatText.includes("Vaswani")) {
     anomalies.push("bob: citation 'Vaswani' never landed in the doc");
@@ -311,8 +396,10 @@ interface CliArgs {
    * "demo duration + a few seconds of outro", and the script blocks
    * on the timer before exiting.
    *
-   * Default 60s covers our ~45s demo with a comfortable buffer you
-   * can trim in post. Bump if you expanded the scenario.
+   * Default 50s covers our ~45s demo + a ~5s outro on the published
+   * article (user wants the browser to quit shortly after the
+   * publish view, not linger for 30s). Bump if you expand the
+   * scenario.
    */
   captureDuration: number;
 }
@@ -324,7 +411,7 @@ function parseArgs(argv: string[]): CliArgs {
     allVisible: false,
     record: false,
     capture: false,
-    captureDuration: 60,
+    captureDuration: 50,
   };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -358,6 +445,10 @@ async function run() {
   // a later launch threw before we got to `Promise.all(runAlice,
   // ...)`.
   const handles: Array<PersonaHandle | null> = [];
+  // Bob + Carol are now Node-side Yjs peers (no Chromium); kept
+  // separately so SIGINT / finally can tear their provider sockets
+  // down cleanly alongside the browsers.
+  const yjsPeers: YjsPersona[] = [];
   let recording: ScreenRecording | null = null;
   let alreadyCleanedUp = false;
 
@@ -373,6 +464,13 @@ async function run() {
       }
       recording = null;
     }
+    for (const peer of yjsPeers) {
+      try {
+        peer.destroy();
+      } catch {
+        /* provider already closed */
+      }
+    }
     await shutdownAllPersonas(handles);
     console.log("[showcase] done.");
   };
@@ -405,6 +503,17 @@ async function run() {
       recordMode: args.record,
     });
     handles.push(alice);
+
+    // Relay demo-related browser console messages to the Node log so
+    // we can diagnose silent frontend errors (e.g. "replace target
+    // not found") during a --capture run without having to open
+    // DevTools by hand.
+    alice.page.on("console", (msg) => {
+      const text = msg.text();
+      if (/__demo-chat|\[alice\]|agentRewrite/.test(text)) {
+        console.log(`[alice:console ${msg.type()}] ${text}`);
+      }
+    });
     console.log("[showcase] alice up");
 
     // Wipe the shared Yjs doc once on Alice's session BEFORE Bob /
@@ -414,19 +523,27 @@ async function run() {
     console.log("[showcase] resetting shared document");
     await resetDoc(alice.page);
 
-    const bob = await launchPersona(args.url, {
-      persona: PERSONAS.bob,
-      headless: true,
+    // Bob and Carol connect as Node-side Yjs peers instead of
+    // full Chromium browsers. They appear in Alice's editor via
+    // normal collaboration sync (authors list, text edits,
+    // citations) without any DOM typing or PM position race.
+    // URL transformation: http:// -> ws:// on the /collab path.
+    const wsUrl = args.url.replace(/^http/, "ws") + "/collab";
+    const bob = await connectPersona({
+      url: wsUrl,
+      docName: "default",
+      user: { name: PERSONAS.bob.name, color: PERSONAS.bob.color },
     });
-    handles.push(bob);
-    console.log("[showcase] bob up");
+    yjsPeers.push(bob);
+    console.log("[showcase] bob up (yjs peer)");
 
-    const carol = await launchPersona(args.url, {
-      persona: PERSONAS.carol,
-      headless: true,
+    const carol = await connectPersona({
+      url: wsUrl,
+      docName: "default",
+      user: { name: PERSONAS.carol.name, color: PERSONAS.carol.color },
     });
-    handles.push(carol);
-    console.log("[showcase] carol up");
+    yjsPeers.push(carol);
+    console.log("[showcase] carol up (yjs peer)");
 
     // Auto screen recording takes precedence over the manual
     // countdown: if --capture is on, we start `screencapture -v`
@@ -467,21 +584,29 @@ async function run() {
     const alicePromise = runAlice(alice.page, args.speed)
       .then(() => stamp("alice done"))
       .catch((err) => console.error("[alice] error:", err));
-    const bobPromise = runBob(bob.page, args.speed)
+    const bobPromise = runBob(bob, args.speed)
       .then(() => stamp("bob done"))
       .catch((err) => console.error("[bob] error:", err));
-    const carolPromise = runCarol(carol.page, args.speed)
+    const carolPromise = runCarol(carol, args.speed)
       .then(() => stamp("carol done"))
       .catch((err) => console.error("[carol] error:", err));
 
     await Promise.all([bobPromise, carolPromise]);
 
-    // Post-parallel doc verification: read the shared article from
-    // Bob's page (still on the editor) and log anomalies. Cheap,
-    // non-blocking; helps catch inter-persona collisions without
-    // having to eyeball the recording frame by frame.
+    // Wait for Alice too: her rephrase typewriter + slot 2 wrap-up
+    // keeps writing AFTER Bob/Carol finish. Running verify before
+    // Alice is done used to show phantom "missing fragments" simply
+    // because the rephrase animation had not landed yet.
+    await alicePromise;
+    stamp("all personas finished");
+
+    // Post-parallel doc verification: read the shared Y.XmlFragment
+    // directly from Bob's still-connected Yjs peer. Alice's browser
+    // has navigated to the published output by this point, but the
+    // Yjs provider keeps syncing regardless of which page is on
+    // screen, so Bob's handle always reflects the final CRDT state.
     try {
-      await verifyFinalDoc(bob.page);
+      await verifyFinalDoc(bob);
     } catch (err) {
       console.warn(
         "[verify] aborted:",
@@ -489,9 +614,6 @@ async function run() {
       );
     }
 
-    await alicePromise;
-    stamp("all personas finished");
-
     // Block on the screencapture timer so the user gets a complete,
     // playable .mov. Extra time after "all personas finished"
     // looks fine in the recording (final state of the editor,

backend/demo/test-yjs-client.ts

@@ -0,0 +1,112 @@
+/**
+ * Standalone test for the Yjs-based peer client.
+ *
+ * Run with the dev backend + frontend running, and preferably with
+ * an Alice browser tab also open so you can watch the edits land
+ * live on her screen.
+ *
+ * Usage:
+ *   npx tsx demo/test-yjs-client.ts
+ *
+ * What it does:
+ *   - connects as a Yjs peer with name "Probe" ✔ visible in Alice's byline
+ *   - adds an author "Probe Author" tied to a new affiliation
+ *   - creates a heading "Yjs probe section" + an empty slot
+ *   - types a paragraph with inline math atoms + a citation chip
+ *   - registers the citation entry in the shared citations map
+ *   - prints the resulting section structure
+ *   - disconnects
+ */
+import {
+  addAuthorRecord,
+  appendInline,
+  buildEmptyParagraph,
+  connectPersona,
+  insertInlineNode,
+  registerCitation,
+  typeIntoParagraph,
+} from "./lib/yjs-client.js";
+import * as Y from "yjs";
+
+async function main() {
+  console.log("connecting to ws://localhost:5678/collab ...");
+  const probe = await connectPersona({
+    url: "ws://localhost:5678/collab",
+    docName: "default",
+    user: { name: "Probe", color: "#ff8800" },
+  });
+  console.log("synced");
+
+  // Author push
+  addAuthorRecord(probe, {
+    name: "Probe Author",
+    newAffiliation: { name: "Test Lab" },
+  });
+  console.log("author pushed, total authors:", probe.frontmatter.authors.length);
+
+  // Write a probe section at the end of the doc. Elements are
+  // created detached and attached in one transaction so the text
+  // child can be inserted from inside the attached heading.
+  const heading = new Y.XmlElement("heading");
+  heading.setAttribute("level", 2);
+  const paragraph = buildEmptyParagraph();
+  probe.ydoc.transact(() => {
+    probe.fragment.push([heading, paragraph]);
+    const headingText = new Y.XmlText();
+    heading.push([headingText]);
+    headingText.insert(0, "Yjs probe section");
+  });
+  console.log("heading + empty paragraph pushed");
+
+  await typeIntoParagraph(
+    paragraph,
+    "Typed via a Node-side Yjs peer: text, math ",
+    { cps: 30 },
+  );
+  await insertInlineNode(paragraph, { type: "inlineMath", latex: "e^{i\\pi}" }, 120);
+  await typeIntoParagraph(paragraph, ", and a citation chip ", { cps: 30 });
+
+  registerCitation(probe, "probe2026yjs", {
+    id: "probe2026yjs",
+    "citation-key": "probe2026yjs",
+    type: "article-journal",
+    title: "Probing Yjs via a Node peer",
+    author: [{ family: "Probe", given: "Test" }],
+    issued: { "date-parts": [[2026]] },
+  });
+  appendInline(paragraph, [
+    {
+      type: "citation",
+      key: "probe2026yjs",
+      label: "(Probe, 2026)",
+    },
+  ]);
+  await typeIntoParagraph(paragraph, ".", { cps: 30 });
+
+  // Dump the probe section back out as plain text
+  console.log("\nfinal paragraph text:");
+  const walk = (el: Y.XmlElement | Y.XmlText): string => {
+    if (el instanceof Y.XmlText) return el.toString();
+    if (el.nodeName === "inlineMath") return `$${el.getAttribute("latex")}$`;
+    if (el.nodeName === "citation") return `[${el.getAttribute("label")}]`;
+    return el
+      .toArray()
+      .map((c) => walk(c as Y.XmlElement | Y.XmlText))
+      .join("");
+  };
+  console.log(
+    paragraph
+      .toArray()
+      .map((c) => walk(c as Y.XmlElement | Y.XmlText))
+      .join(""),
+  );
+
+  console.log("\nclosing...");
+  probe.destroy();
+  process.exit(0);
+}
+
+main().catch((err) => {
+  console.error("probe failed:", err);
+  process.exit(1);
+});

backend/package-lock.json

@@ -15,6 +15,7 @@
         "@citation-js/plugin-csl": "^0.7.22",
         "@citation-js/plugin-doi": "^0.7.21",
         "@hocuspocus/extension-database": "^3.4.4",
+        "@hocuspocus/provider": "^4.0.0",
         "@hocuspocus/server": "^3.4.4",
         "@hocuspocus/transformer": "^3.4.4",
         "@huggingface/hub": "^2.11.0",
@@ -689,6 +690,31 @@
         "yjs": "^13.6.8"
       }
     },
+    "node_modules/@hocuspocus/provider": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/@hocuspocus/provider/-/provider-4.0.0.tgz",
+      "integrity": "sha512-08gpeNZ6x2pmRD6m4XwRD52yQKnTl32a0HS9VSXZ5A1dIBVqxMz/x8Z06XbkKM2X8sp6vWEUCZCtzAGFSsofgg==",
+      "license": "MIT",
+      "dependencies": {
+        "@hocuspocus/common": "^4.0.0",
+        "@lifeomic/attempt": "^3.0.2",
+        "lib0": "^0.2.87",
+        "ws": "^8.17.1"
+      },
+      "peerDependencies": {
+        "y-protocols": "^1.0.6",
+        "yjs": "^13.6.8"
+      }
+    },
+    "node_modules/@hocuspocus/provider/node_modules/@hocuspocus/common": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/@hocuspocus/common/-/common-4.0.0.tgz",
+      "integrity": "sha512-7BE8TsKBkdiOZO6tfm3ny6bIHPbxkIZb3hsYdVn/X5xbXI8n8w9pnE6pXgEMKQhJm6zsWsa9IDRJIp/c9u+DmA==",
+      "license": "MIT",
+      "dependencies": {
+        "lib0": "^0.2.87"
+      }
+    },
     "node_modules/@hocuspocus/server": {
       "version": "3.4.4",
       "resolved": "https://registry.npmjs.org/@hocuspocus/server/-/server-3.4.4.tgz",
@@ -753,6 +779,12 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/@lifeomic/attempt": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/@lifeomic/attempt/-/attempt-3.1.0.tgz",
+      "integrity": "sha512-QZqem4QuAnAyzfz+Gj5/+SLxqwCAw2qmt7732ZXodr6VDWGeYLG6w1i/vYLa55JQM9wRuBKLmXmiZ2P0LtE5rw==",
+      "license": "MIT"
+    },
     "node_modules/@napi-rs/wasm-runtime": {
       "version": "1.1.3",
       "resolved": "https://registry.npmjs.org/@napi-rs/wasm-runtime/-/wasm-runtime-1.1.3.tgz",
@@ -1313,7 +1345,6 @@
       "resolved": "https://registry.npmjs.org/@tiptap/extension-code-block/-/extension-code-block-3.22.3.tgz",
       "integrity": "sha512-RiQtEjDAPrHpdo6sw6b7fOw/PijqgFIsozKKkGcSeBgWHQuFg7q9OxJTj+l0e60rVwSu/5gmKEEobzM9bX+t2Q==",
       "license": "MIT",
-      "peer": true,
       "funding": {
         "type": "github",
         "url": "https://github.com/sponsors/ueberdosis"
@@ -3216,7 +3247,6 @@
       "resolved": "https://registry.npmjs.org/highlight.js/-/highlight.js-11.11.1.tgz",
       "integrity": "sha512-Xwwo44whKBVCYoliBQwaPvtd/2tYFkRQtXDWj1nackaV2JPXx3L0+Jvd8/qCJ2p+ML0/XVkJ2q+Mr+UVdpJK5w==",
       "license": "BSD-3-Clause",
-      "peer": true,
       "engines": {
         "node": ">=12.0.0"
       }
@@ -3701,7 +3731,6 @@
       "resolved": "https://registry.npmjs.org/lowlight/-/lowlight-3.3.0.tgz",
       "integrity": "sha512-0JNhgFoPvP6U6lE/UdVsSq99tn6DhjjpAj5MxG49ewd2mOBVtwWYIT8ClyABhq198aXXODMU6Ox8DrGy/CpTZQ==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@types/hast": "^3.0.0",
         "devlop": "^1.0.0",

backend/package.json

@@ -19,6 +19,7 @@
     "@citation-js/plugin-csl": "^0.7.22",
     "@citation-js/plugin-doi": "^0.7.21",
     "@hocuspocus/extension-database": "^3.4.4",
+    "@hocuspocus/provider": "^4.0.0",
     "@hocuspocus/server": "^3.4.4",
     "@hocuspocus/transformer": "^3.4.4",
     "@huggingface/hub": "^2.11.0",

frontend/src/App.tsx

@@ -318,6 +318,27 @@ export default function App() {
                * textContent does NOT match the `from` plain-string.
                */
               range?: { from: number; to: number };
+              /**
+               * "none"       -> atomic replace in one transaction. The
+               *                 viewer sees the new phrase "snap in",
+               *                 unambiguously an AI edit.
+               * "typewriter" -> stream chars at human cadence. Looks
+               *                 like the owner is typing (which is
+               *                 NOT what we want for an agent action -
+               *                 use "none" for rephrase actions so
+               *                 they don't look like user input).
+               * Default: "typewriter" for backwards compatibility.
+               */
+              animation?: "none" | "typewriter";
+              /**
+               * Keep an AgentFocus decoration on the replacement
+               * range for `lingerAgentFocusMs` ms after the swap so
+               * the viewer sees the "<Name> agent" label hover over
+               * the new sentence - visual proof the agent owned that
+               * edit. Ignored when 0 / undefined (caller will manage
+               * focus clearing itself).
+               */
+              lingerAgentFocusMs?: number;
             };
             /**
              * Apply a formatting mark (bold/italic/strike/code) to an
@@ -350,6 +371,8 @@ export default function App() {
         const target = detail.replace.from;
         const replacement = detail.replace.to;
         const explicitRange = detail.replace.range;
+        const animation = detail.replace.animation ?? "typewriter";
+        const lingerAgentFocusMs = detail.replace.lingerAgentFocusMs ?? 0;
 
         // Resolve the target range AT DISPATCH TIME, not here. We used
         // to do the string search on event receipt, cache from/to,
@@ -447,8 +470,36 @@ export default function App() {
             from,
             to,
             text: replacement,
-            animation: "typewriter",
+            animation,
           });
+
+          // Re-seed the AgentFocus on the REPLACEMENT range after the
+          // swap so the "<Name> agent" label keeps hovering over the
+          // new sentence - otherwise the decoration collapses during
+          // the delete-then-insert, and viewers perceive the new
+          // phrase as user typing instead of an agent edit. For the
+          // atomic "none" animation the new text is present
+          // immediately; for the typewriter we wait long enough for
+          // the first chunk to land so PM positions are stable.
+          if (lingerAgentFocusMs > 0) {
+            const seedDelay = animation === "none" ? 0 : 80;
+            window.setTimeout(() => {
+              const live = editorRef.current;
+              if (!live) return;
+              const newFrom = from;
+              const newTo = from + replacement.length;
+              const size = live.state.doc.content.size;
+              const a = Math.max(0, Math.min(newFrom, size));
+              const b = Math.max(0, Math.min(newTo, size));
+              if (b > a) {
+                live.commands.setAgentFocus({ from: a, to: b });
+              }
+              window.setTimeout(() => {
+                const again = editorRef.current;
+                again?.commands.clearAgentFocus();
+              }, lingerAgentFocusMs);
+            }, seedDelay);
+          }
         }, 520);
       }
 

frontend/src/components/PublishDialog.tsx

@@ -1,5 +1,12 @@
-import { forwardRef } from "react";
-import { Eye } from "lucide-react";
+import { forwardRef, useEffect, useRef, useState } from "react";
+import {
+  Eye,
+  UploadCloud,
+  CheckCircle2,
+  AlertTriangle,
+  Sparkles,
+  ExternalLink,
+} from "lucide-react";
 
 export type PublishState = "idle" | "loading" | "success" | "error";
 
@@ -55,6 +62,22 @@ const STAGE_LABELS: Record<string, string> = {
   upload: "Uploading to storage",
 };
 
+// Canonical order used to compute a progress ratio. Stages not in
+// this list still render their label but don't retract the bar.
+const STAGE_ORDER: PublishStage[] = [
+  "extract",
+  "bibliography",
+  "render",
+  "load",
+  "thumbnail",
+  "pdf-setup",
+  "pdf-toc",
+  "rasterize",
+  "pdf-render",
+  "write",
+  "upload",
+];
+
 function formatStage(event: PublishStageEvent | null): string {
   if (!event) return "Publishing...";
   const base = STAGE_LABELS[event.stage] ?? "Publishing...";
@@ -64,6 +87,28 @@ function formatStage(event: PublishStageEvent | null): string {
   return base;
 }
 
+/**
+ * Compute a 0..1 progress ratio for `event`, blending rasterize
+ * sub-progress. Returns `null` for unknown stages so the caller can
+ * hold the previous value instead of retracting the bar.
+ */
+function computeProgress(event: PublishStageEvent | null): number | null {
+  if (!event) return 0.04;
+  const idx = STAGE_ORDER.indexOf(event.stage);
+  if (idx === -1) return null;
+  const slots = STAGE_ORDER.length + 1;
+  let base = (idx + 1) / slots;
+  if (
+    event.stage === "rasterize" &&
+    event.detail?.index &&
+    event.detail?.total
+  ) {
+    const rasterFrac = Math.min(1, event.detail.index / event.detail.total);
+    base = idx / slots + rasterFrac / slots;
+  }
+  return Math.max(0.04, Math.min(0.98, base));
+}
+
 /**
  * Native `<dialog>` shown when the user clicks "Publish" in the top bar.
  * Displays live stage progress during the long PDF pipeline (typically
@@ -75,67 +120,154 @@ export const PublishDialog = forwardRef<HTMLDialogElement, Props>(function Publi
 ) {
   const stageLabel = formatStage(stageEvent);
 
+  // Monotonic progress. The backend can emit unknown stages or
+  // re-emit earlier ones during retries; the bar should never walk
+  // backwards on camera.
+  const progressRef = useRef<number>(0.04);
+  const [progress, setProgress] = useState<number>(0.04);
+  useEffect(() => {
+    if (state === "idle") {
+      progressRef.current = 0.04;
+      setProgress(0.04);
+      return;
+    }
+    if (state === "success") {
+      progressRef.current = 1;
+      setProgress(1);
+      return;
+    }
+    if (state === "error") return;
+    const next = computeProgress(stageEvent);
+    if (next == null) return;
+    if (next > progressRef.current) {
+      progressRef.current = next;
+      setProgress(next);
+    }
+  }, [stageEvent, state]);
+
+  const publishedUrl = `/published/${docName}/index.html`;
+  const displayUrl = publishedUrl.replace(/\/index\.html$/, "");
+
   return (
-    <dialog ref={ref} className="ed-dialog" onClose={onClose}>
-      <h2 className="ed-dialog__title">
-        {state === "success" ? "Published!" : "Publish article"}
-      </h2>
-      <div className="ed-dialog__body">
-        {state === "idle" && (
-          <p>
-            This will generate a static HTML page, a print-optimized PDF,
-            and a thumbnail from the current document. The process
-            typically takes 15-25 seconds. Other collaborators can keep
-            editing while you publish.
+    <dialog
+      ref={ref}
+      className={`ed-dialog ed-dialog--publish ed-dialog--publish-${state}`}
+      onClose={onClose}
+    >
+      <header className="publish-dialog__header">
+        <div className={`publish-dialog__icon publish-dialog__icon--${state}`}>
+          {state === "idle" && <UploadCloud size={22} strokeWidth={1.75} />}
+          {state === "loading" && <span className="spinner" aria-hidden />}
+          {state === "success" && <CheckCircle2 size={22} strokeWidth={1.75} />}
+          {state === "error" && <AlertTriangle size={22} strokeWidth={1.75} />}
+        </div>
+        <div className="publish-dialog__heading">
+          <h2 className="publish-dialog__title">
+            {state === "idle" && "Publish article"}
+            {state === "loading" && "Publishing your article"}
+            {state === "success" && "Published!"}
+            {state === "error" && "Publish failed"}
+          </h2>
+          <p className="publish-dialog__subtitle">
+            {state === "idle" && "Static HTML, print-ready PDF and thumbnail."}
+            {state === "loading" && stageLabel}
+            {state === "success" && "Your update is live for every reader."}
+            {state === "error" && "We couldn't finish the publish run."}
           </p>
+        </div>
+      </header>
+
+      <div className="publish-dialog__body">
+        {state === "idle" && (
+          <div className="publish-dialog__intro">
+            <ul className="publish-dialog__checklist">
+              <li>
+                <span className="publish-dialog__bullet" aria-hidden />
+                <span>
+                  <strong>Static HTML</strong> page ready to share.
+                </span>
+              </li>
+              <li>
+                <span className="publish-dialog__bullet" aria-hidden />
+                <span>
+                  <strong>Print-ready PDF</strong> with full typography.
+                </span>
+              </li>
+              <li>
+                <span className="publish-dialog__bullet" aria-hidden />
+                <span>
+                  <strong>Social thumbnail</strong> captured automatically.
+                </span>
+              </li>
+            </ul>
+            <p className="publish-dialog__note">
+              <Sparkles size={12} strokeWidth={2} aria-hidden />
+              Takes 15-25s. Collaborators can keep editing in the meantime.
+            </p>
+          </div>
         )}
+
         {state === "loading" && (
-          <div style={{ display: "flex", flexDirection: "column", gap: 8, padding: "8px 0" }}>
-            <div style={{ display: "flex", alignItems: "center", gap: 12 }}>
-              <span className="spinner" />
-              <p style={{ margin: 0 }}>{stageLabel}</p>
+          <div className="publish-dialog__progress">
+            <div
+              className="publish-dialog__bar"
+              role="progressbar"
+              aria-valuemin={0}
+              aria-valuemax={100}
+              aria-valuenow={Math.round(progress * 100)}
+            >
+              <span
+                className="publish-dialog__bar-fill"
+                style={{ width: `${Math.round(progress * 100)}%` }}
+              />
             </div>
-            <p style={{ margin: 0, fontSize: "0.85em", opacity: 0.7 }}>
-              Rasterizing embeds and rendering a print-ready PDF can take
-              a moment. Keep this tab open until it finishes.
+            <p className="publish-dialog__hint">
+              Rasterizing embeds and rendering the PDF can take a moment. Keep
+              this tab open until it finishes.
             </p>
           </div>
         )}
+
         {state === "success" && (
-          <>
-            <p>
-              Article published successfully. Visitors will now see
-              the updated version.
-            </p>
+          <div className="publish-dialog__success">
+            <div className="publish-dialog__success-url">
+              <span className="publish-dialog__url-label">Live at</span>
+              <code className="publish-dialog__url-code">{displayUrl}</code>
+            </div>
             <a
-              href={`/published/${docName}/index.html`}
+              href={publishedUrl}
               target="_blank"
               rel="noopener noreferrer"
-              className="btn btn--primary"
-              style={{ display: "inline-flex", alignItems: "center", gap: 6, textDecoration: "none", marginTop: 4 }}
+              className="btn btn--primary publish-dialog__view-btn"
             >
               <Eye size={16} />
               View published article
+              <ExternalLink size={13} strokeWidth={2} aria-hidden />
             </a>
-          </>
+          </div>
         )}
+
         {state === "error" && (
-          <p style={{ color: "var(--ed-error)" }}>
+          <p className="publish-dialog__error">
             {error || "An error occurred while publishing."}
           </p>
         )}
       </div>
-      <div className="ed-dialog__actions">
+
+      <footer className="publish-dialog__actions">
         {state === "idle" && (
           <>
             <button className="btn" onClick={onClose}>Cancel</button>
-            <button className="btn btn--primary" onClick={onPublish}>Publish</button>
+            <button className="btn btn--primary" onClick={onPublish}>
+              <UploadCloud size={14} strokeWidth={2} aria-hidden />
+              Publish
+            </button>
           </>
         )}
         {(state === "success" || state === "error") && (
           <button className="btn" onClick={onClose}>Close</button>
         )}
-      </div>
+      </footer>
     </dialog>
   );
 });

frontend/src/editor/extensions/agent-rewrite.ts

@@ -164,13 +164,55 @@ export const AgentRewrite = Extension.create({
 
       agentRewriteRange:
         (args) =>
-        ({ editor, state, view, tr, dispatch }) => {
+        ({ state, view, tr, dispatch }) => {
           const docSize = state.doc.content.size;
           const a = Math.max(0, Math.min(args.from, docSize));
           const b = Math.max(0, Math.min(args.to, docSize));
           if (b < a) return false;
           if (!dispatch) return true;
 
+          // Capture `myToken` BEFORE the dispatch. Tiptap's
+          // CommandManager turns out to batch the `tr` we mutate here
+          // into its own dispatch cycle, so reading `view.state`
+          // immediately after calling the provided `dispatch(tr)` can
+          // return the PRE-commit state (cancelToken still = N,
+          // cursor still = null). The only reliable source is the
+          // state we started from (`state`): we know this command
+          // will bump cancelToken by 1 and seed the cursor at `a`,
+          // so we compute those values ourselves instead of reading
+          // them back from a potentially stale view.
+          const prevToken = agentRewriteKey.getState(state)?.cancelToken ?? 0;
+          const myToken = prevToken + 1;
+
+          const text = args.text ?? "";
+          const animation = args.animation ?? "none";
+
+          // ----- Atomic path ("none") -----------------------------------
+          // Do the whole replace in ONE transaction: cancel any
+          // in-flight rewrite, replace [a, b] with `text`, clear the
+          // cursor marker. Two separate dispatches produced double
+          // content (insert + zombie old text) because Tiptap's
+          // CommandManager does NOT update `view.state` between
+          // `dispatch(tr)` and the next `view.state.tr.insertText`
+          // call inside the same command - so the second tr
+          // insertText ran against the PRE-delete state, effectively
+          // adding the new phrase in front of the old one without
+          // deleting it.
+          if (animation === "none") {
+            tr.setMeta(agentRewriteKey, {
+              cancel: true,
+              setCursor: null,
+            } as AgentRewriteMeta);
+            if (text) {
+              tr.insertText(text, a, b);
+            } else if (b > a) {
+              tr.delete(a, b);
+            }
+            dispatch(tr);
+            return true;
+          }
+
+          // ----- Typewriter path -----------------------------------
           // Step 1: single atomic transaction that (a) cancels any
           // in-flight rewrite, (b) deletes the target range, and (c)
           // plants the insertion cursor at `a`. Done in one tr so the
@@ -183,7 +225,6 @@ export const AgentRewrite = Extension.create({
           if (b > a) tr.delete(a, b);
           dispatch(tr);
 
-          const text = args.text ?? "";
           if (!text) {
             // Nothing to insert, just a deletion. Done.
             view.dispatch(
@@ -194,38 +235,39 @@ export const AgentRewrite = Extension.create({
             return true;
           }
 
-          const animation = args.animation ?? "none";
-          if (animation === "none") {
-            // Synchronous, one-shot insert. Single tr -> one undo step.
-            const cursor =
-              agentRewriteKey.getState(editor.state)?.cursor ?? a;
-            view.dispatch(
-              view.state.tr
-                .insertText(text, cursor)
-                .setMeta(agentRewriteKey, {
-                  setCursor: null,
-                } as AgentRewriteMeta),
-            );
-            return true;
-          }
-
           // Typewriter: async stream of small insertText trs. Each step
           // reads the CURRENT cursor from plugin state (mapped through
           // every intervening tr, including remote Yjs updates), so the
           // animation is immune to concurrent edits.
           const [chunkMin, chunkMax] = args.chunkSize ?? [1, 2];
           const [delayMin, delayMax] = args.chunkMs ?? [22, 48];
-          const myToken =
-            agentRewriteKey.getState(editor.state)?.cancelToken ?? 0;
           let i = 0;
 
+          // Closure-held cursor is our source of truth: seeded at `a`,
+          // then synced with plugin state before each insert so remote
+          // Yjs trs between our ticks remap the cursor correctly via
+          // the plugin's mapping logic. Using a closure (rather than
+          // reading plugin state blindly) guarantees the first step
+          // doesn't bail out if Tiptap's command dispatch hasn't yet
+          // committed the `setCursor: a` meta to the plugin state that
+          // `view.state` exposes.
+          let cursor = a;
+
           const step = () => {
             if (view.isDestroyed) return;
             const ps = agentRewriteKey.getState(view.state);
-            if (!ps) return;
-            // Another rewrite started (or cancel was called) -> stop.
-            if (ps.cancelToken !== myToken) return;
-            if (ps.cursor === null) return;
+            // Cancellation only: token mismatch means another rewrite
+            // started (or `cancelAgentRewrite` fired).
+            if (ps && ps.cancelToken !== myToken) {
+              // Another rewrite started or `cancelAgentRewrite` fired.
+              return;
+            }
+            // Pull the mapped cursor from plugin state if available -
+            // this accounts for any remote Yjs inserts that happened
+            // since the last step. Fall back to the closure value on
+            // the very first tick, where plugin state can still be
+            // null due to Tiptap's command dispatch batching.
+            if (ps && ps.cursor !== null) cursor = ps.cursor;
 
             if (i >= text.length) {
               // Done: clear the cursor marker so nothing lingers in
@@ -247,9 +289,11 @@ export const AgentRewrite = Extension.create({
               Math.floor(Math.random() * (maxTake - minTake + 1));
             const chunk = text.slice(i, i + take);
 
-            // `insertText(chunk, cursor)` advances the cursor via the
-            // plugin's `apply` mapping (see state.apply above).
-            view.dispatch(view.state.tr.insertText(chunk, ps.cursor));
+            // Insert at our closure-tracked cursor. The plugin's
+            // apply() will advance the stored cursor via mapping so
+            // subsequent remote trs remap it correctly.
+            view.dispatch(view.state.tr.insertText(chunk, cursor));
+            cursor += chunk.length;
             i += chunk.length;
 
             const delay =

frontend/src/styles/_ui.css

@@ -214,6 +214,259 @@ dialog.ed-dialog::backdrop { background: rgba(0, 0, 0, 0.6); }
 .ed-dialog__body p { margin: 0; }
 .ed-dialog__actions { display: flex; justify-content: flex-end; gap: 8px; padding: 8px 20px 16px; }
 
+/* ---- Publish dialog ---- */
+dialog.ed-dialog.ed-dialog--publish {
+  max-width: 460px;
+  overflow: hidden;
+  box-shadow:
+    0 1px 0 rgba(255, 255, 255, 0.04) inset,
+    0 24px 48px -12px rgba(0, 0, 0, 0.35),
+    0 8px 18px -8px rgba(0, 0, 0, 0.25);
+}
+dialog.ed-dialog.ed-dialog--publish::backdrop {
+  background: rgba(10, 10, 12, 0.55);
+  backdrop-filter: blur(2px);
+}
+
+.publish-dialog__header {
+  display: flex;
+  align-items: flex-start;
+  gap: 14px;
+  padding: 22px 24px 14px;
+  position: relative;
+}
+.publish-dialog__header::after {
+  content: "";
+  position: absolute;
+  left: 24px;
+  right: 24px;
+  bottom: 0;
+  height: 1px;
+  background: var(--ed-border);
+  opacity: 0.6;
+}
+
+.publish-dialog__icon {
+  flex-shrink: 0;
+  width: 40px;
+  height: 40px;
+  border-radius: 10px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  background: color-mix(in srgb, var(--primary-color) 14%, transparent);
+  color: var(--primary-color);
+  transition: background 0.25s ease, color 0.25s ease;
+}
+.publish-dialog__icon--success {
+  background: color-mix(in srgb, var(--ed-success) 16%, transparent);
+  color: var(--ed-success);
+}
+.publish-dialog__icon--error {
+  background: color-mix(in srgb, var(--ed-error) 16%, transparent);
+  color: var(--ed-error);
+}
+.publish-dialog__icon--loading .spinner {
+  width: 20px;
+  height: 20px;
+  border-width: 2px;
+}
+
+.publish-dialog__heading {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  min-width: 0;
+}
+.publish-dialog__title {
+  margin: 0;
+  font-size: 1.05rem;
+  font-weight: 600;
+  letter-spacing: -0.005em;
+  color: var(--ed-text);
+}
+.publish-dialog__subtitle {
+  margin: 0;
+  font-size: 0.85rem;
+  color: var(--ed-text-secondary);
+  line-height: 1.45;
+  /* Stage name can grow during loading; avoid layout jump. */
+  min-height: 1.2em;
+}
+
+.publish-dialog__body {
+  padding: 18px 24px 6px;
+}
+
+.publish-dialog__intro {
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+}
+
+.publish-dialog__checklist {
+  list-style: none;
+  margin: 0;
+  padding: 14px 14px;
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  font-size: 0.88rem;
+  color: var(--ed-text);
+  border: 1px solid var(--ed-border);
+  border-radius: var(--ed-radius-sm);
+  background: color-mix(in srgb, var(--primary-color) 5%, transparent);
+}
+.publish-dialog__checklist li {
+  display: flex;
+  align-items: flex-start;
+  gap: 10px;
+  line-height: 1.45;
+}
+.publish-dialog__checklist strong {
+  color: var(--ed-text);
+  font-weight: 600;
+}
+.publish-dialog__bullet {
+  flex-shrink: 0;
+  margin-top: 7px;
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  background: var(--primary-color);
+  box-shadow: 0 0 0 3px color-mix(in srgb, var(--primary-color) 18%, transparent);
+}
+.publish-dialog__note {
+  margin: 0;
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  font-size: 0.78rem;
+  color: var(--ed-text-disabled);
+  padding-left: 2px;
+}
+.publish-dialog__note svg {
+  color: var(--primary-color);
+  opacity: 0.8;
+}
+
+.publish-dialog__progress {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+.publish-dialog__bar {
+  position: relative;
+  height: 6px;
+  border-radius: 999px;
+  background: var(--ed-surface-hover);
+  overflow: hidden;
+}
+.publish-dialog__bar-fill {
+  position: absolute;
+  left: 0;
+  top: 0;
+  bottom: 0;
+  border-radius: 999px;
+  background: linear-gradient(
+    90deg,
+    color-mix(in srgb, var(--primary-color) 55%, transparent),
+    var(--primary-color)
+  );
+  transition: width 0.45s cubic-bezier(0.4, 0, 0.2, 1);
+  box-shadow: 0 0 8px color-mix(in srgb, var(--primary-color) 45%, transparent);
+}
+.publish-dialog__bar-fill::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+  background: linear-gradient(
+    90deg,
+    transparent,
+    rgba(255, 255, 255, 0.18),
+    transparent
+  );
+  transform: translateX(-100%);
+  animation: publish-shimmer 1.6s ease-in-out infinite;
+}
+@keyframes publish-shimmer {
+  to { transform: translateX(100%); }
+}
+.publish-dialog__hint {
+  margin: 0;
+  font-size: 0.8rem;
+  color: var(--ed-text-disabled);
+  line-height: 1.5;
+}
+
+.publish-dialog__success {
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+}
+.publish-dialog__success-url {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 10px 12px;
+  border: 1px solid var(--ed-border);
+  border-radius: var(--ed-radius-sm);
+  background: color-mix(in srgb, var(--ed-success) 6%, transparent);
+}
+.publish-dialog__url-label {
+  font-size: 0.72rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: var(--ed-success);
+  flex-shrink: 0;
+}
+.publish-dialog__url-code {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  font-size: 0.82rem;
+  color: var(--ed-text);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  flex: 1;
+  min-width: 0;
+  background: transparent;
+  padding: 0;
+}
+
+.publish-dialog__view-btn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 8px;
+  text-decoration: none;
+  width: 100%;
+  padding: 10px 16px;
+  font-weight: 600;
+}
+.publish-dialog__view-btn svg:last-of-type {
+  opacity: 0.8;
+}
+
+.publish-dialog__error {
+  margin: 0;
+  padding: 10px 12px;
+  border-radius: var(--ed-radius-sm);
+  background: color-mix(in srgb, var(--ed-error) 10%, transparent);
+  border: 1px solid color-mix(in srgb, var(--ed-error) 30%, transparent);
+  color: var(--ed-error);
+  font-size: 0.85rem;
+  line-height: 1.5;
+}
+
+.publish-dialog__actions {
+  display: flex;
+  justify-content: flex-end;
+  gap: 8px;
+  padding: 14px 24px 20px;
+}
+
 /* ---- Drawer ---- */
 .drawer-backdrop {
   position: fixed;