diff --git a/claude-notes/plans/2026-06-23-tiptap-rich-text-block-editor.md b/claude-notes/plans/2026-06-23-tiptap-rich-text-block-editor.md
new file mode 100644
index 000000000..9a5722f67
--- /dev/null
+++ b/claude-notes/plans/2026-06-23-tiptap-rich-text-block-editor.md
@@ -0,0 +1,541 @@
+# Rich-text (tiptap) block editor for q2-preview — feasibility plan
+
+**Date:** 2026-06-23
+**Strand:** bd-sjb4pzx8
+**Branch:** `braid/bd-sjb4pzx8-tiptap-rich-text-editor`
+**Status:** Phase 0 (spike) in progress — go-ahead given 2026-06-23.
+**Builds on / required reading:** `claude-notes/designs/2026-06-06-block-editing-design.md`
+(the master spec for the current editor), plus the boundary-splice
+(`2026-06-18/19`), track-me (`2026-06-13`), and glitch (`2026-06-15`→`18`) plans.
+
+---
+
+## Overview
+
+Today, activating a block in `q2 preview` / quarto-hub replaces it with a
+monospaced `<textarea>` showing the **raw qmd source slice** of that block's
+byte range. The user edits raw markdown; on commit the text is parsed and
+spliced back into the document.
+
+This plan explores replacing **only that textarea UI** with a **tiptap /
+ProseMirror rich-text editor**, so the user edits *formatted* text instead of
+raw markdown — while keeping the entire detection, identity, splice, reconcile,
+and incremental-write machinery **unchanged**.
+
+### The confirmed architecture (user's framing)
+
+The change is deliberately minimal and lives **entirely in TypeScript**:
+
+```
+                       ┌─────────────── UNCHANGED ───────────────┐
+ detect byte range  →  seed editor with markdown slice
+                       └──────────────────────────────────────────┘
+                                       │
+                       ┌─── NEW (this work) ───┐
+                       │  markdown slice         │
+                       │     → ProseMirror doc   │   (parse)
+                       │     → rich editing      │   (tiptap UI)
+                       │     → markdown text     │   (serialize)
+                       └─────────────────────────┘
+                                       │
+                       ┌─────────────── UNCHANGED ───────────────┐
+ commitTextEdit(markdown) → parse_qmd_content → apply_node_edit →
+   reconcile → incremental_write → onContentRewrite → re-render
+                       └──────────────────────────────────────────┘
+```
+
+We reuse the existing **text channel** (`commitTextEdit`) verbatim. The Rust
+backend, the Automerge sync, the source-map layer, and the parent↔iframe
+postMessage protocol **never know the difference** — they still receive a
+markdown string keyed by a `SourceInfo` byte range.
+
+### Design refinements (locked 2026-06-23, second iteration)
+
+These two refinements sharpen the approach above and supersede the earlier
+phrasing where they conflict:
+
+1. **Seed from the AST subtree, not from re-lexing markdown.** We already have
+   the untransformed Pandoc AST (with source byte-ranges) in the iframe. So the
+   **input/seed path is `AST subtree → ProseMirror doc`**, walking typed Pandoc
+   nodes — *not* parsing the markdown slice with a TS markdown library (which
+   would risk markdown-dialect mismatches against pampa). Chip detection thereby
+   stops being a lexing problem and becomes a typed-AST walk over data we already
+   trust: opaque node types (`Math`, `RawInline`, `RawBlock`, `Cite`, shortcode
+   nodes) become chips whose verbatim text is sliced from source by the node's
+   byte range. **The commit path is unchanged: `PM doc → markdown text →
+   commitTextEdit → parse-as-qmd`.** Only the *seed* direction moved from
+   markdown-text to AST.
+
+2. **Callout/nested divs need no block chip — we "reach into" them.** A
+   `::: {.callout}` (or any non-section `Div`) is not editable *as a unit*, but
+   its *inner* blocks carry their own source ranges, and the existing resolution
+   model already opens an editing session on an inner block (`Descendable`
+   reachability). So a tiptap session operates on an inner paragraph/list, not on
+   the whole div. Consequence: **block-level chips are rare; the real passthrough
+   need is *inline* chips** (shortcodes, math, `@crossref`, `[@cite]`, raw inline)
+   inside an otherwise-editable paragraph. The spike's chip work focuses there.
+
+> **Why the text channel and not the subtree (AST) channel?** The architecture
+> also supports `commitSubtreeEdit`, which commits an edited Pandoc AST subtree
+> directly (skipping the parse). A ProseMirror editor *could* map its doc to a
+> Pandoc AST and use that channel, retiring even the markdown serializer. We are
+> **deliberately not doing that** for the spike: the markdown round-trip keeps
+> the surface tiny (one component, no new WASM entry point, no PM⇄Pandoc-AST
+> bridge in Rust) and lets us reuse the parser as the single source of truth for
+> qmd semantics. The AST channel is recorded here as a **future alternative**,
+> not the v1 path.
+
+### Decisions locked with the user (2026-06-23)
+
+| Question | Decision |
+| --- | --- |
+| **Fidelity target (v1)** | **Prose-rich, Quarto-opaque.** Headings, bold/italic, links, lists, blockquotes, inline/fenced code render as true rich text. Everything Quarto-specific — shortcodes `{{< … >}}`, `::: {.callout}` divs + `{attrs}`, math `$…$`/`$$…$$`, `@crossref`/`@cite`, raw HTML/inline — becomes an **opaque "chip"**: an atomic ProseMirror node that renders as a non-editable pill and re-emits its **exact source token** on serialize. |
+| **Rollout** | Experimental **branch** for now (fidelity gaps are acceptable while exploring). Ship behind an **opt-in flag** (mirroring the existing `unlockNestingCursor` pattern), defaulting to the textarea. **Eventual** requirement (not this spike): fall back to the textarea when the user needs to type syntax the rich editor can't represent, or to add new blocks. |
+| **This session's deliverable** | A **throwaway round-trip spike**: a minimal, isolated harness proving `markdown → ProseMirror doc → markdown` (with chips) on real qmd fixtures, *before* any integration. De-risks the one genuine unknown. |
+
+---
+
+## The core feasibility question
+
+Everything reduces to one bidirectional contract, living entirely in TypeScript:
+
+> **markdown slice ⇄ ProseMirror doc**, such that:
+> 1. A block's qmd slice parses into a faithful, *editable* rich representation.
+> 2. Serializing the (possibly edited) doc back to markdown produces qmd that,
+>    when re-parsed by pampa, yields the intended AST.
+> 3. **Opaque constructs survive verbatim** as chips — a shortcode in, the same
+>    shortcode bytes out.
+> 4. **An unedited open-and-close is a semantic no-op** (see the dirty-guard
+>    trap below).
+
+The spike exists to answer: *how faithfully, and at what cost, can we do this?*
+
+### What posit-assistant tells us (reference, not reuse)
+
+`external-sources/assistant` uses tiptap, but as a **chat-message composer**:
+paragraphs + bold/italic/strike/link + custom `@file`/`/command` chip nodes.
+It **disables** headings, lists, blockquotes, code blocks, tables, and
+hand-writes a line-based markdown serializer (no `prosemirror-markdown`).
+
+- **What transfers:** the *React wiring* (`useEditor`, `EditorContent`,
+  imperative ref handle, `clipboardTextSerializer`), and crucially the **chip
+  pattern** — atomic inline nodes carrying a stored attribute, with
+  `renderText()` re-emitting the original token. That is exactly our
+  shortcode/math/crossref passthrough mechanism.
+- **What does NOT transfer:** their scope. They never round-trip lists,
+  headings, blockquotes, or any block structure, and they never touch
+  Pandoc/Quarto constructs. **The hard part of our problem — faithful
+  block-level qmd round-trip — is unsolved in their code.** We are not
+  inheriting a solution; we are inheriting a wiring pattern.
+
+This is the single most important feasibility caveat: *tiptap usage in the wild
+(including posit-assistant) sidesteps full-markdown round-trip by scoping the
+input. We cannot sidestep it — our editor opens on arbitrary existing qmd
+blocks, including whole lists and blockquotes (the "locked tile" can be a
+multi-line container).*
+
+---
+
+## Genuine cruxes the spike must resolve
+
+These are the things that can sink the approach. The spike is designed to hit
+each one.
+
+### C1 — Serializer fidelity (the dominant risk)
+
+`prosemirror-markdown`'s default serializer is CommonMark-ish and lossy
+(list-marker normalization, escaping `\_`/`\*`, blank-line collapsing, ATX vs
+setext headings, hard-wrap handling). We need output that **re-parses to the
+right AST**, not output that is byte-identical to the input. The acceptance bar
+is therefore *semantic* (AST-equivalence after re-parse), not textual.
+
+Open sub-questions for the spike:
+- Is `prosemirror-markdown` (+ custom node/mark serializer overrides) good
+  enough, or do we hand-roll a serializer (as posit-assistant did)?
+- How do fenced code blocks with Quarto attributes (` ```{python} `) survive?
+  (Likely a chip-bearing code node, since the info string is Quarto-specific.)
+
+### C2 — The chip / passthrough model
+
+Opaque tokens must survive untouched. Mechanism: a custom ProseMirror **atomic
+node** (inline or block) whose attrs store the verbatim source string and whose
+`renderText()`/serializer emits it back unchanged; non-editable, rendered as a
+visually distinct pill.
+
+The hard part is **detection at parse time**: given a markdown slice, identify
+the spans that are shortcodes / math / raw / crossrefs / cites and lift them
+into chips *before or during* the markdown→PM parse, rather than letting the
+markdown parser mangle them. Options to evaluate in the spike:
+- Pre-tokenize with a Quarto-aware pass (we may be able to reuse pampa's own
+  tokenization via WASM to *find* these spans authoritatively, rather than
+  re-implementing shortcode/math lexing in TS).
+- A markdown-it plugin that recognizes the tokens and emits chip nodes.
+
+### C3 — The dirty-guard trap (no-op fidelity)
+
+Today, "open then close without typing" is a guaranteed no-op because the
+textarea value is byte-identical to the slice (`normalize(draft).trimEnd() ===
+anchorSlice`). A tiptap round-trip is **not** byte-identical, so a naive
+"serialize and compare to slice" would mark *every* opened block dirty and
+silently reformat it on close.
+
+**Fix (design intent):** derive dirtiness from ProseMirror's own change signal
+— compare the current doc against the seeded doc (`editor.state.doc.eq(initialDoc)`
+or transaction `docChanged` accumulation), **not** from serialized-text
+comparison. An unedited doc ⇒ cancel, commit nothing, regardless of how the
+serializer would have re-rendered it. The spike must demonstrate this cleanly.
+
+### C4 — Multi-block container slices
+
+The "locked tile" the editor opens on can be a whole `BulletList`,
+`OrderedList`, `BlockQuote`, or `DefinitionList` — i.e. the seeded markdown is
+*several* blocks with list markers / `> ` prefixes, not one paragraph. The PM
+doc must model these as real structured nodes (a real `bullet_list` with
+`list_item`s) and serialize them back to correct qmd. This is precisely the
+scope posit-assistant skips. The spike must include at least one list and one
+blockquote fixture.
+
+### C5 — Nested / prefixed buffers
+
+For blocks nested in prefixing containers, the existing system already feeds the
+editor a **prefix-stripped clean buffer** (via `regenerate_nested_buffers` /
+`write_single_block`) so the user edits at column 0. Good news: tiptap inherits
+this for free — it receives the same clean buffer the textarea would. No new
+work, but the spike should confirm a clean buffer parses correctly.
+
+### C6 — What we explicitly do NOT need (simplifications)
+
+A large class of current pain **evaporates** because PM owns its own selection
+model: caret/column projection, prefix-width math, tight trailing source ranges,
+per-line provenance, last-visual-line geometry. None of that is needed for the
+rich editor's *internal* caret. (It remains relevant only at the
+parent/iframe identity boundary, which we are not touching.)
+
+---
+
+## What stays unchanged (explicitly out of scope for the spike)
+
+- `SourceInfo` byte-range identity, `captureEditTarget`, the byte-offset anchor.
+- `commitTextEdit` → `apply_node_edit` → reconcile → `incremental_write` (Rust).
+- Self-heal / track-me relocation, the settle-gate, concurrency handling.
+- Hover/activation/roving-tabindex, the measured wrapper box.
+- The cross-surface (arrow-out) cursor *for v1* — though tiptap will need its
+  own key handling eventually; the spike does not address inter-block cursoring.
+
+---
+
+## Phase plan
+
+> **Phase 0 is the only sanctioned work for this session.** Phases 1+ are
+> sketched so we can see the whole shape, but require explicit go-ahead.
+
+### Phase 0 — Throwaway round-trip spike (this session, after go-ahead)
+
+**Goal:** prove `markdown → PM doc → markdown` with chips, on real qmd, with a
+*semantic* (re-parse-to-same-AST) acceptance bar. Throwaway = isolated, not
+wired into the preview, deleted or quarantined after we read the results.
+
+**Spike pipeline (AST-driven, authoritative end-to-end):**
+
+```
+qmd fixture → pampa parse → AST_in → [AST→PM bridge] → PM doc
+           → [PM→markdown serializer] → md_out → pampa parse → AST_out
+           → assert AST_in ≅ AST_out   (semantic round-trip)
+```
+
+**Tasks (TDD — tests first):**
+
+- [x] Pick a home for the spike: `ts-packages/preview-renderer/src/q2-preview/`
+      `tiptap-roundtrip-spike/` (vitest, node env). **Oracle = native `pampa`**
+      (`-t json --json-source-location full`) shelled out via `child_process` —
+      gives the source-tracked untransformed AST with **no WASM init**.
+- [x] Assemble a **fixture corpus** (16 fixtures, `fixtures.ts`): plain para,
+      inline formatting, ATX heading, bullet/ordered/nested lists, blockquote,
+      plain + `{python}` code blocks, shortcode, inline/display math, crossref,
+      citation, callout div, raw HTML inline.
+- [x] Write the **acceptance oracle** (`roundtrip.test.ts` + `canonical.ts`):
+      buckets each fixture `exact` / `equivalent` (reformatted) / `broken` by
+      comparing source-stripped ASTs (exact) and whitespace-normalized ASTs
+      (equivalent). Fails the suite only on `broken`.
+- [x] Define the **ProseMirror schema** (`schema.ts`): `prosemirror-markdown`'s
+      schema + an atomic inline `chip` node (attrs `{src, kind}`).
+- [x] Implement **AST → PM doc** (`astToPm.ts`): walks the Pandoc AST; opaque
+      node types (`Math`/`Cite`/`Span.quarto-shortcode__`/`RawInline`, plus
+      block `Div`/`RawBlock`/`Table` for the spike) become chips carrying their
+      verbatim source slice (C2, refinement 1).
+- [x] Implement the **chip** (atomic, verbatim serialize via `state.text(src,
+      false)` — no markdown escaping).
+- [x] Implement **PM doc → markdown** (`pmToMarkdown.ts`): default
+      `prosemirror-markdown` serializer + the chip rule. **Zero custom node/mark
+      overrides were needed beyond the chip** (C1 — see verdict).
+- [ ] Demonstrate the **dirty/no-op signal** off `doc.eq(initialDoc)` (C3) —
+      *deferred to Phase 1*; the spike validated the static round-trip, which is
+      the harder unknown. C3 is a small, well-understood addition at integration.
+- [x] Produce a **findings table** + written verdict (below; `RESULTS.md` holds
+      per-fixture `qmd → md_out` evidence).
+
+**Exit criteria:** ✅ met — see verdict below.
+
+---
+
+## Phase 0 RESULTS (2026-06-23) — verdict: **GREEN**
+
+Ran 16 fixtures through `qmd → pampa AST → astToPm → prosemirror-markdown
+serialize → pampa AST → compare`:
+
+```
+exact:      15
+equivalent:  1   (blockquote: two soft-wrapped lines join into one — benign)
+broken:      0
+```
+
+Chips fired exactly where expected: shortcode (1), inline math (1), display
+math (1), crossref (1), citation (1), callout div (1), raw-HTML inline (2).
+Byte-exact passthrough confirmed in `RESULTS.md`, e.g.:
+
+- `{{< video https://youtu.be/abc >}}` → identical out
+- `@fig-plot` → identical out
+- `::: {.callout-note}\nThis is a note.\n:::` → identical out
+
+**What this proves.** The core unknown — *can we faithfully round-trip prose-rich
++ Quarto-opaque qmd through a ProseMirror document?* — is answered **yes**, with
+evidence. The AST-driven seed (refinement 1) means chip detection is a trivial,
+authoritative typed-AST walk, and `prosemirror-markdown`'s **stock serializer
+needed no per-node overrides** beyond the one chip rule. That resolves the
+post-spike "library vs hand-roll" question (open Q #2) decisively in favor of
+**`prosemirror-markdown` + the chip rule** — at least for this corpus.
+
+**Honest caveats (what the spike did NOT prove).**
+
+1. **This validates the model, not the tiptap *UX*.** The spike is headless
+   ProseMirror (`prosemirror-model` + `prosemirror-markdown`). tiptap is the
+   React editing layer on top; chips-as-pills, keyboard nav, IME, focus/blur
+   commit, and the measured-wrapper fit are **Phase 1** and remain unproven.
+2. **C3 (dirty/no-op) was designed, not exercised.** The blockquote
+   `equivalent` result is exactly the whitespace-normalization that would cause a
+   spurious reformat on open-and-close *unless* dirtiness is read from
+   `doc.eq(initialDoc)`. Phase 1 must implement and test that.
+3. **Block-chip for `Div` is a spike convenience.** Production reaches *into*
+   the div (refinement 2) and edits inner blocks; whole-div chipping was used
+   here only to measure round-trip, and pleasingly it also round-trips.
+4. **Corpus gaps.** Tables, figures-with-captions, definition lists, footnotes,
+   images-with-attrs, nested divs, multi-line raw blocks are not in the corpus;
+   the bridge maps them to verbatim block-chips (safe passthrough, not richly
+   editable — consistent with v1 scope). Fidelity there is untested.
+
+**Spike location (throwaway):**
+`ts-packages/preview-renderer/src/q2-preview/tiptap-roundtrip-spike/`
+(`fixtures.ts`, `pampa.ts`, `schema.ts`, `astToPm.ts`, `pmToMarkdown.ts`,
+`canonical.ts`, `roundtrip.test.ts`, `RESULTS.md`). Run:
+`cd ts-packages/preview-renderer && npx vitest run src/q2-preview/tiptap-roundtrip-spike/`.
+Deps added (dev): `prosemirror-model`, `prosemirror-markdown`. Quarantine/delete
+before any non-experimental merge; `tsc --noEmit` is clean and the full
+preview-renderer suite (473 tests) passes with it present.
+
+### Phase 1 — WYSIWYG in-place editor behind an opt-in flag (design locked 2026-06-23)
+
+**Goal of the experiment (user's framing):** the editable view should *look like
+the rendered page* — editing a paragraph shows body font, real bold, real links,
+not a monospaced box. See "how close we can get".
+
+**The key enabler (confirmed by recon).** The editor mounts in the **same iframe**
+as the rendered content, and that iframe already has the **full Bootstrap + Quarto
+theme CSS** loaded (`<link data-q2-theme>` in `document.head`, applied in
+`q2-preview/entry.tsx`). The renderer emits **clean semantic tags** (`<p>`, `<em>`,
+`<strong>`, `<h2>`, `<a>`, `<ul>/<li>`) with no proprietary classes. So a
+ProseMirror editor emitting the same tags is styled by the theme **for free** — we
+emit matching DOM and let the cascade do the work; we do **not** reimplement theme
+styling. The existing measured-box wrapper (`renderMeasuredEdit`, the
+`q2-active-edit-region` div) is **structural** (prevents reflow) and **stays**; we
+swap the monospaced `<textarea>` inside it for a tiptap editor and reset
+ProseMirror's default editor chrome so it doesn't fight the theme.
+
+**Dev loop.** `q2 preview --allow-edit` (no sync server; serves `{allowEdit:true}`
+read by the SPA at boot). A new `?richText=1` opt-in is plumbed exactly like
+`?nestingCursor=1`: `PreviewApp` parses it → `Q2PreviewIframe` prop → `UPDATE_AST`
+payload → `PreviewContext` → dispatcher branch. Iterate + screenshot via the
+chrome-devtools MCP.
+
+**tiptap now enters** (the spike was deliberately headless ProseMirror). Phase 1
+uses `@tiptap/react` (`useEditor`/`EditorContent`) and **React NodeViews for
+chips**. The spike's `astToPm` seed and `prosemirror-markdown` serializer port over
+essentially unchanged.
+
+**Decisions locked (2026-06-23, third iteration):**
+
+- **Staging: paragraph-first, then widen.** First cut targets single paragraphs
+  only (pure inline editing — em/strong/link/code/chips, **no** structural splits)
+  to prove the "looks like the page" feel + the commit loop in the real preview
+  before taking on interactive structural edits.
+- **Chips: source-text pills only (v1).** Every chip (shortcode, math, crossref,
+  cite, raw) renders as a small pill showing its source token; always serializes
+  verbatim. (Noted future option, explicitly out of v1: render inline math via the
+  already-loaded **KaTeX** / show resolved crossref text, to match the page while
+  staying atomic. Deferred.)
+
+**Sub-phases:**
+
+- **1a — Paragraph-only WYSIWYG proof.** Wire the `richText` flag end-to-end;
+      branch the `Block` dispatcher so a `Para` edit-target renders a tiptap editor
+      (seeded from the `sourceNode` via `resolveSource`, i.e. AST→PM) inside the
+      existing measured box; emit page-matching DOM; commit via the **unchanged**
+      `commitTextEdit` path; implement the **`doc.eq(initialDoc)` dirty guard (C3)**
+      and the stale-target/self-heal blur guards. Drive with chrome-devtools;
+      capture before/after screenshots proving the editor matches the rendered
+      paragraph. Round-trip unit tests for inline edits.
+  - [x] **Production round-trip core** (`src/q2-preview/richtext/`): `schema.ts`
+        (tiptap-named PM schema + `chip`), `ast.ts`, `astToProseMirror.ts`
+        (`astToDoc`), `serializer.ts` (`docToMarkdown`). Plus shared test oracle
+        `src/test-utils/pampaOracle.ts` and `richtext/roundtrip.test.ts` (13
+        fixtures, **all pass**). Gate = SEMANTIC equivalence (no dropped/changed
+        nodes), with byte-exactness informational per user guidance (imperfect
+        round-trip OK, dropped nodes not). Two qmd-specific serializer choices
+        landed: italic→`_` (avoids qmd-disallowed `***`), list `tight` from AST
+        (Plain vs Para items). Oracle compares inline marks as a *flat set*
+        (ProseMirror's model) so `[**x**](u)`≡`**[x](u)**`. tsc clean.
+  - [ ] tiptap `Chip` node extension (React NodeView pill).
+  - [ ] `RichTextEditor.tsx` (tiptap editor seeded via `astToDoc(...).toJSON()`;
+        commit via `docToMarkdown` + `commitTextEdit`; `doc.eq` dirty guard;
+        Esc/Cmd-Enter/blur + stale-target guard; Para-only, no structural splits).
+  - [ ] Plumb `richText` flag: `PreviewContext` → `Q2PreviewIframe` →
+        `UPDATE_AST` payload → `PreviewApp` `?richText=1` (mirror `unlockNestingCursor`).
+  - [ ] Dispatcher branch: `Block` renders `RichTextEditor` (vs `EditTextarea`)
+        for `Para` when `ctx.richText`.
+  - [x] Browser verification (`q2 preview --allow-edit` + `?richText=1`,
+        chrome-devtools). **Verified end-to-end 2026-06-23.** Clicking a paragraph
+        opens a tiptap editor that is visually identical to the rendered block
+        (bold/italic/code/link styled by the theme — same-iframe cascade), just
+        with a caret; DOM snapshot confirmed a real ProseMirror contenteditable
+        with `<strong>/<em>/<code>/<a>` nodes. A real edit (inserting bolded
+        "more") committed through the **unchanged** `commitTextEdit` path and
+        wrote clean qmd to disk — `(and **more**!)` — with the rest of the
+        paragraph (`**bold text**`, `*italic text*`, `` `inline code` ``,
+        `[hyperlink](…)`) round-tripped **byte-clean**. Evidence:
+        `claude-notes/richtext-shots/{01-rendered,02-editing-para1}.png`.
+
+**Phase 1a is COMPLETE and verified.** The thesis holds: the editable view looks
+like the page, edits are rich-text, and write-back is faithful qmd through the
+existing pipeline. Next: 1b (headings + inline polish), 1c (lists/blockquotes +
+interactive structural-edit round-trip tests).
+
+### 1a follow-ups (post-completion, all verified in `q2 preview`)
+
+- **Edit-mode tint** — active editor gets a subtle blue tint + ring (the faithful
+  WYSIWYG was *too* faithful to tell it was live). Zero text shift.
+- **Left-margin affordances** — "Editing…" label + a **rich/plain editor toggle**
+  parked in the left margin (absolute, off the text, so it never hijacks
+  clicking/selecting). The toggle is the in-place **escape hatch to the textarea**
+  for syntax the rich editor can't express (a Phase-2 idea brought forward).
+  Shared by both surfaces via `renderMeasuredEdit`; session-sticky `editorMode`
+  in `PreviewRoot`. A `editorModeSwitchRef` guard stops the surface swap from
+  triggering a blur-commit/close; rich→plain hands content across via
+  `editDraftRef` (dirty-aware, so an untouched toggle never reformats). Files:
+  `richtext/EditAffordance.tsx`, `richtext/styles.ts`, `dispatchers.tsx`,
+  `PreviewRoot.tsx`, `PreviewContext.tsx`. Evidence:
+  `richtext-shots/{07-toggle-rich,09-toggle-plain-fixed}.png`.
+- **Chip source via `.l`** — chip text now slices from a node's literal `.l`
+  location, not the compact pool entry (which is mis-assigned for shortcode
+  spans). Shortcode chips render verbatim `{{< meta key >}}`. (Also filed
+  bd-u145dg3y: warn when a block-level shortcode is used inline.)
+- **Known limitation (Phase 2):** plain→rich re-seeds the rich editor from the
+  original AST (it can't parse arbitrary edited markdown in-iframe). rich→plain
+  preserves edits. Full bidirectional content handoff needs the parent parse.
+- **1b — Headings + inline-formatting polish** (toolbar-free; rely on standard
+      marks + theme styling). Tighten visual parity (margins, line-height).
+  - [x] `Header` added to `RICHTEXT_SUPPORTED_TYPES`; heading node enabled in the
+        tiptap StarterKit config. The bridge already mapped `Header → heading{level}`,
+        so the round-trip was ready (added a `heading-with-marks` fixture, 14/14).
+  - [x] `enableInputRules: false` / `enablePasteRules: false` — 1b edits existing
+        structure only; typing "## " must not convert a paragraph or change a
+        heading's level (structural edits are a later phase; Cmd-B/I still work).
+  - [x] `trailingNode: false` — a single non-paragraph block (a heading) was
+        getting a phantom empty trailing `<p>` (extra editor height + a stray blank
+        block on commit). Verified the heading box is now tight in `q2 preview`.
+        Evidence: `richtext-shots/12-heading-tight.png`.
+  - [x] **Formatting toolbar** (`RichTextToolbar.tsx`) — a small box floating above
+        the top-left of the edit box: **B / I / S / x₂ / x² / 🔗**. Mark buttons call
+        `toggleMark` (same command as Cmd-B/I), highlight via `isActive`, and use
+        mousedown-preventDefault so clicking never collapses the selection. Verified
+        end-to-end: selecting a word + Bold writes `**word**` to disk.
+        Evidence: `richtext-shots/13-toolbar.png`.
+  - [x] **Subscript / superscript as real marks** — added `@tiptap/extension-{sub,super}script`,
+        schema marks, serializer (`~x~` / `^x^`), and AST mapping (Pandoc
+        `Subscript`/`Superscript` → marks, no longer chips). Round-trip fixture
+        `sub-sup-strike` green.
+  - [x] **Link create/edit** — toolbar 🔗 opens a URL input; `setLink` /
+        `extendMarkRange('link')` / `unsetLink` (edit/remove an existing link by
+        placing the cursor in it). Focus scope reworked: the editor commits only on
+        `focusout` leaving the whole `.q2-richtext-editor`, so focusing the link
+        input keeps the session open. The TS side is correct (commit log shows the
+        right markdown), **but** a downstream write-back bug corrupts a new link's
+        URL when the paragraph has another link — filed **bd-3zp3z4jx** (shared
+        text-channel bug, affects the textarea editor too; single-link edits fine).
+- [ ] **1c — Lists / blockquotes, incl. interactive structural edits** (Enter
+      split, new item, backspace-merge) with round-trip tests for *interactive*
+      edits (new surface beyond the spike's static round-trip).
+- [ ] **1d — Chip UX** (pills; read-only in v1) and the first seam toward the
+      Phase-2 textarea fallback.
+
+**Risks / open tensions for Phase 1:**
+
+- **Exact visual parity is a long tail.** ~95% free for prose; pixel-exact needs
+  iteration, and attributed blocks (`{.lead}`, classed lists) only match if we
+  carry their classes onto the editor's root node.
+- **Interactive structural edits are new** (1c). ProseMirror creates/splits nodes
+  natively; the serializer must produce correct qmd for those — proven only
+  statically so far. This also intersects Phase 2's "fall back to textarea for new
+  blocks".
+- **Chip editing.** A user fixing a typo inside a shortcode/math can't, in v1
+  (chips are read-only) — that routes through the Phase-2 textarea fallback.
+
+### Phase 2 — Fallback + new-block authoring (future)
+
+- Escape hatch: when the user needs unsupported syntax, to edit a chip's source,
+  or to add a new block, drop from the rich editor to the textarea (mode toggle,
+  or auto-fallback on detecting an unsupported edit).
+- Inter-block cursoring (arrow-out) under the rich editor.
+
+### Phase 3 — (Stretch) AST channel (future, possibly never)
+
+- Investigate committing via `commitSubtreeEdit` (PM doc → Pandoc AST),
+  retiring the markdown serializer entirely. Only if Phase 0/1 expose
+  serializer-fidelity pain that an AST bridge would resolve.
+
+---
+
+## Open questions — RESOLVED (2026-06-23, second iteration)
+
+1. **Chip granularity:** ~~block chip for divs?~~ **Resolved:** no block chip for
+   callout/divs. We reach into the div and edit inner blocks (refinement 2).
+   Chips are primarily *inline*.
+2. **Serializer choice:** **Resolved (deferred by design):** start with
+   `prosemirror-markdown` + overrides; reassess as a hand-roll only if the spike
+   shows we're fighting the library constantly. Decision is evidence-driven,
+   post-spike.
+3. **Chip detection source of truth:** **Resolved:** walk the **AST in TS**
+   (we already have the untransformed AST JSON). No markdown-it (dialect-mismatch
+   risk), no extra pampa call for detection (refinement 1).
+4. **Fixture corpus sign-off:** **Resolved:** corpus above is sufficient for the
+   spike.
+
+## Remaining open questions (post-spike)
+
+- Serializer library vs hand-roll (decide on spike evidence — see #2 above).
+- Whether/how to later move to the AST commit channel (Phase 3).
+
+---
+
+## References
+
+- Master spec: `claude-notes/designs/2026-06-06-block-editing-design.md`
+- Boundary-splice (pending): `claude-notes/plans/2026-06-18-boundary-splice-edit-design.md`,
+  `claude-notes/plans/2026-06-19-boundary-splice-implementation.md`
+- Track-me relocation: `claude-notes/plans/2026-06-13-track-me-node-relocation-successor.md`
+- Frontend: `ts-packages/preview-renderer/src/q2-preview/{dispatchers.tsx,
+  useBlockEditHover.tsx, PreviewContext.tsx, PreviewRoot.tsx, usePreviewEdit.ts,
+  sourceIndex.ts}`
+- Backend (unchanged): `crates/pampa/src/{apply_node_edit.rs, node_lookup.rs,
+  regenerate_nested_buffers.rs}`, `crates/pampa/src/writers/incremental.rs`,
+  `crates/quarto-ast-reconcile/`
+- tiptap reference (wiring + chip pattern only): `external-sources/assistant/
+  packages/ui/src/{TiptapInput.tsx, utils/tiptap-serialization.ts}`
diff --git a/claude-notes/richtext-shots/01-rendered.png b/claude-notes/richtext-shots/01-rendered.png
new file mode 100644
index 000000000..4067abd9e
Binary files /dev/null and b/claude-notes/richtext-shots/01-rendered.png differ
diff --git a/claude-notes/richtext-shots/02-editing-para1.png b/claude-notes/richtext-shots/02-editing-para1.png
new file mode 100644
index 000000000..d9d5d64c2
Binary files /dev/null and b/claude-notes/richtext-shots/02-editing-para1.png differ
diff --git a/claude-notes/richtext-shots/04-editing-tint.png b/claude-notes/richtext-shots/04-editing-tint.png
new file mode 100644
index 000000000..12e0155a2
Binary files /dev/null and b/claude-notes/richtext-shots/04-editing-tint.png differ
diff --git a/claude-notes/richtext-shots/06-shortcode-chip-fixed.png b/claude-notes/richtext-shots/06-shortcode-chip-fixed.png
new file mode 100644
index 000000000..0c9f2fbe5
Binary files /dev/null and b/claude-notes/richtext-shots/06-shortcode-chip-fixed.png differ
diff --git a/claude-notes/richtext-shots/07-toggle-rich.png b/claude-notes/richtext-shots/07-toggle-rich.png
new file mode 100644
index 000000000..a9b72be92
Binary files /dev/null and b/claude-notes/richtext-shots/07-toggle-rich.png differ
diff --git a/claude-notes/richtext-shots/09-toggle-plain-fixed.png b/claude-notes/richtext-shots/09-toggle-plain-fixed.png
new file mode 100644
index 000000000..60071e108
Binary files /dev/null and b/claude-notes/richtext-shots/09-toggle-plain-fixed.png differ
diff --git a/claude-notes/richtext-shots/12-heading-tight.png b/claude-notes/richtext-shots/12-heading-tight.png
new file mode 100644
index 000000000..8e8dc5c4a
Binary files /dev/null and b/claude-notes/richtext-shots/12-heading-tight.png differ
diff --git a/claude-notes/richtext-shots/13-toolbar.png b/claude-notes/richtext-shots/13-toolbar.png
new file mode 100644
index 000000000..b8f16656e
Binary files /dev/null and b/claude-notes/richtext-shots/13-toolbar.png differ
diff --git a/package-lock.json b/package-lock.json
index fc48e0d6f..e690e4ab0 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -2058,7 +2058,6 @@
       "os": [
         "aix"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2076,7 +2075,6 @@
       "os": [
         "android"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2094,7 +2092,6 @@
       "os": [
         "android"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2112,7 +2109,6 @@
       "os": [
         "android"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2130,7 +2126,6 @@
       "os": [
         "darwin"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2148,7 +2143,6 @@
       "os": [
         "darwin"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2166,7 +2160,6 @@
       "os": [
         "freebsd"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2184,7 +2177,6 @@
       "os": [
         "freebsd"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2202,7 +2194,6 @@
       "os": [
         "linux"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2220,7 +2211,6 @@
       "os": [
         "linux"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2238,7 +2228,6 @@
       "os": [
         "linux"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2256,7 +2245,6 @@
       "os": [
         "linux"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2274,7 +2262,6 @@
       "os": [
         "linux"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2292,7 +2279,6 @@
       "os": [
         "linux"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2310,7 +2296,6 @@
       "os": [
         "linux"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2328,7 +2313,6 @@
       "os": [
         "linux"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2346,7 +2330,6 @@
       "os": [
         "linux"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2364,7 +2347,6 @@
       "os": [
         "netbsd"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2382,7 +2364,6 @@
       "os": [
         "netbsd"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2400,7 +2381,6 @@
       "os": [
         "openbsd"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2418,7 +2398,6 @@
       "os": [
         "openbsd"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2436,7 +2415,6 @@
       "os": [
         "openharmony"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2454,7 +2432,6 @@
       "os": [
         "sunos"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2472,7 +2449,6 @@
       "os": [
         "win32"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2490,7 +2466,6 @@
       "os": [
         "win32"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2508,7 +2483,6 @@
       "os": [
         "win32"
       ],
-      "peer": true,
       "engines": {
         "node": ">=18"
       }
@@ -2694,6 +2668,34 @@
         "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
       }
     },
+    "node_modules/@floating-ui/core": {
+      "version": "1.7.5",
+      "resolved": "https://registry.npmjs.org/@floating-ui/core/-/core-1.7.5.tgz",
+      "integrity": "sha512-1Ih4WTWyw0+lKyFMcBHGbb5U5FtuHJuujoyyr5zTaWS5EYMeT6Jb2AuDeftsCsEuchO+mM2ij5+q9crhydzLhQ==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "@floating-ui/utils": "^0.2.11"
+      }
+    },
+    "node_modules/@floating-ui/dom": {
+      "version": "1.7.6",
+      "resolved": "https://registry.npmjs.org/@floating-ui/dom/-/dom-1.7.6.tgz",
+      "integrity": "sha512-9gZSAI5XM36880PPMm//9dfiEngYoC6Am2izES1FF406YFsjvyBMmeJ2g4SAju3xWwtuynNRFL2s9hgxpLI5SQ==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "@floating-ui/core": "^1.7.5",
+        "@floating-ui/utils": "^0.2.11"
+      }
+    },
+    "node_modules/@floating-ui/utils": {
+      "version": "0.2.11",
+      "resolved": "https://registry.npmjs.org/@floating-ui/utils/-/utils-0.2.11.tgz",
+      "integrity": "sha512-RiB/yIh78pcIxl6lLMG0CgBXAZ2Y0eVHqMPYugu+9U0AeT6YBeiJpf7lbdJNIugFP5SIjwNRgo4DhR1Qxi26Gg==",
+      "license": "MIT",
+      "optional": true
+    },
     "node_modules/@hono/node-server": {
       "version": "1.19.14",
       "resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-1.19.14.tgz",
@@ -4123,6 +4125,463 @@
         "@testing-library/dom": ">=7.21.4"
       }
     },
+    "node_modules/@tiptap/core": {
+      "version": "3.27.1",
+      "resolved": "https://registry.npmjs.org/@tiptap/core/-/core-3.27.1.tgz",
+      "integrity": "sha512-rV6Qn4wmC6BxfF+4mu6bqGWj9vA4oXXhsrpXaJL2uhjxeHAGofjwcHof2X84VYzeyXgdlsGmqKie4TAppVXZUQ==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/ueberdosis"
+      },
+      "peerDependencies": {
+        "@tiptap/pm": "3.27.1"
+      }
+    },
+    "node_modules/@tiptap/extension-blockquote": {
+      "version": "3.27.1",
+      "resolved": "https://registry.npmjs.org/@tiptap/extension-blockquote/-/extension-blockquote-3.27.1.tgz",
+      "integrity": "sha512-VMF7xJx6qEGiX6DTKNiL31NLqypOcd/4sNjFSe8rb41PwejBJh/nOqVIbBvWkiT6NMGFLxMhj7zJ8/zPo1hXeg==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/ueberdosis"
+      },
+      "peerDependencies": {
+        "@tiptap/core": "3.27.1"
+      }
+    },
+    "node_modules/@tiptap/extension-bold": {
+      "version": "3.27.1",
+      "resolved": "https://registry.npmjs.org/@tiptap/extension-bold/-/extension-bold-3.27.1.tgz",
+      "integrity": "sha512-TlC5bsS+pqETTrlz4CZz9RO/cKBYtELGIxwtKeivUn3eNfnOxQbbu4WDsiwIfzRFyd0OMnKl6BPM2KnYEehoEQ==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/ueberdosis"
+      },
+      "peerDependencies": {
+        "@tiptap/core": "3.27.1"
+      }
+    },
+    "node_modules/@tiptap/extension-bubble-menu": {
+      "version": "3.27.1",
+      "resolved": "https://registry.npmjs.org/@tiptap/extension-bubble-menu/-/extension-bubble-menu-3.27.1.tgz",
+      "integrity": "sha512-j/j8Qp9Z5nViade2m7zjrO/CYH/Ca80Qj7aqo0eUaei6FZQ5izlF9o4XQU5EFMAutV6mwynsPUp8FVo5sCuYfw==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "@floating-ui/dom": "^1.0.0"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/ueberdosis"
+      },
+      "peerDependencies": {
+        "@tiptap/core": "3.27.1",
+        "@tiptap/pm": "3.27.1"
+      }
+    },
+    "node_modules/@tiptap/extension-bullet-list": {
+      "version": "3.27.1",
+      "resolved": "https://registry.npmjs.org/@tiptap/extension-bullet-list/-/extension-bullet-list-3.27.1.tgz",
+      "integrity": "sha512-faCUHnRP47o9Zh9VZZX6EX/569udw9Vopm2PgEKPWuKLE2qaS5WBuUVU0iItdJmKUqaWiOZkpoW4jvnDmj0dfg==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/ueberdosis"
+      },
+      "peerDependencies": {
+        "@tiptap/extension-list": "3.27.1"
+      }
+    },
+    "node_modules/@tiptap/extension-code": {
+      "version": "3.27.1",
+      "resolved": "https://registry.npmjs.org/@tiptap/extension-code/-/extension-code-3.27.1.tgz",
+      "integrity": "sha512-epOUpFfEmBzjvnqvjv2qHX7NAuLo5dlOGV690lWu+sAYMjibuJBeVvAiKPyFCfRCCTUxdbDB3jbaOA1yEcEJ7w==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/ueberdosis"
+      },
+      "peerDependencies": {
+        "@tiptap/core": "3.27.1"
+      }
+    },
+    "node_modules/@tiptap/extension-code-block": {
+      "version": "3.27.1",
+      "resolved": "https://registry.npmjs.org/@tiptap/extension-code-block/-/extension-code-block-3.27.1.tgz",
+      "integrity": "sha512-pHlzmZx2OlHfyQ0yRlT5UL4mGokz947DthZuYefN1OleVqOkHpWBG+2JQwqoNq6bmzMne92zbH32rhcJUEYSjA==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/ueberdosis"
+      },
+      "peerDependencies": {
+        "@tiptap/core": "3.27.1",
+        "@tiptap/pm": "3.27.1"
+      }
+    },
+    "node_modules/@tiptap/extension-document": {
+      "version": "3.27.1",
+      "resolved": "https://registry.npmjs.org/@tiptap/extension-document/-/extension-document-3.27.1.tgz",
+      "integrity": "sha512-8FbBTkfnRP4iVaoj+2h3iWa+H0eGDD3yTyVCwrmue/sQTkqUNUoSuAZa3GDG4Sd41xdPwTJxl9nUWGgM1qDCnw==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/ueberdosis"
+      },
+      "peerDependencies": {
+        "@tiptap/core": "3.27.1"
+      }
+    },
+    "node_modules/@tiptap/extension-dropcursor": {
+      "version": "3.27.1",
+      "resolved": "https://registry.npmjs.org/@tiptap/extension-dropcursor/-/extension-dropcursor-3.27.1.tgz",
+      "integrity": "sha512-blFf9x9RG0Qr7P3FoAH/033ffa+mMLZn34trVs8Vi0Ppk6FmJAg5HpYFOtmYoeREdNDJ5rHJKV7SoACbOHgskQ==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/ueberdosis"
+      },
+      "peerDependencies": {
+        "@tiptap/extensions": "3.27.1"
+      }
+    },
+    "node_modules/@tiptap/extension-floating-menu": {
+      "version": "3.27.1",
+      "resolved": "https://registry.npmjs.org/@tiptap/extension-floating-menu/-/extension-floating-menu-3.27.1.tgz",
+      "integrity": "sha512-BmJF1VqB7dSJkgAalrpVFj88WLhxKjcWPuWHOqf2ITrUU2832BhKLXKmxjWUy1gqV8PfNNVWtGfIERy7I0y0+Q==",
+      "license": "MIT",
+      "optional": true,
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/ueberdosis"
+      },
+      "peerDependencies": {
+        "@floating-ui/dom": "^1.0.0",
+        "@tiptap/core": "3.27.1",
+        "@tiptap/pm": "3.27.1"
+      }
+    },
+    "node_modules/@tiptap/extension-gapcursor": {
+      "version": "3.27.1",
+      "resolved": "https://registry.npmjs.org/@tiptap/extension-gapcursor/-/extension-gapcursor-3.27.1.tgz",
+      "integrity": "sha512-QoezN0wdvXIwLQ4ee2ccWDaX3RG0lzgQpIMpMz55oPDhpUVax1+19ApsS53LkcktpS4EbnPL4xO4DaJk0Vp7PQ==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/ueberdosis"
+      },
+      "peerDependencies": {
+        "@tiptap/extensions": "3.27.1"
+      }
+    },
+    "node_modules/@tiptap/extension-hard-break": {
+      "version": "3.27.1",
+      "resolved": "https://registry.npmjs.org/@tiptap/extension-hard-break/-/extension-hard-break-3.27.1.tgz",
+      "integrity": "sha512-iv/m9hzl6jfSj9Q8UEjAxONvCoUDaP7M9SRCPx3PaLNxA230TTD6RE0Ye4zFJ8ze7ZVoJJMAqg9Qpq1iYg2JOQ==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/ueberdosis"
+      },
+      "peerDependencies": {
+        "@tiptap/core": "3.27.1"
+      }
+    },
+    "node_modules/@tiptap/extension-heading": {
+      "version": "3.27.1",
+      "resolved": "https://registry.npmjs.org/@tiptap/extension-heading/-/extension-heading-3.27.1.tgz",
+      "integrity": "sha512-SrC4l1kEIyv9ZXFaI/8LQqU2MyMmjczw7XXsWUQOTN4YXv0JyVgMNR3cI/wz0d2xsTfBdZ1N85Tdng+Ga1t0Sg==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/ueberdosis"
+      },
+      "peerDependencies": {
+        "@tiptap/core": "3.27.1"
+      }
+    },
+    "node_modules/@tiptap/extension-horizontal-rule": {
+      "version": "3.27.1",
+      "resolved": "https://registry.npmjs.org/@tiptap/extension-horizontal-rule/-/extension-horizontal-rule-3.27.1.tgz",
+      "integrity": "sha512-QlKE7qn5qMnIGVGhXQlvYedvLtNJ9z0dmit5w8vPb8tKzW4Spk6M7N2kruprrDA8GBwHfeR5wmF+njfUm34qxg==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/ueberdosis"
+      },
+      "peerDependencies": {
+        "@tiptap/core": "3.27.1",
+        "@tiptap/pm": "3.27.1"
+      }
+    },
+    "node_modules/@tiptap/extension-italic": {
+      "version": "3.27.1",
+      "resolved": "https://registry.npmjs.org/@tiptap/extension-italic/-/extension-italic-3.27.1.tgz",
+      "integrity": "sha512-jGGeyn9uRUnNjSTHpbqhiGsp6KaYTSbV09jDXPJI9cDwfV9hpugLvpaCZd0BMBbhU1B1W6kOfX0BE15qX/HQfA==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/ueberdosis"
+      },
+      "peerDependencies": {
+        "@tiptap/core": "3.27.1"
+      }
+    },
+    "node_modules/@tiptap/extension-link": {
+      "version": "3.27.1",
+      "resolved": "https://registry.npmjs.org/@tiptap/extension-link/-/extension-link-3.27.1.tgz",
+      "integrity": "sha512-/2jBfsxBZUDGJmpZifqRQPz7f1E5qpS1BckTZ39TADzUJX+feKy7RJ3DtQ02+8y6SSMzvP9loGVjrk6zEMTk4g==",
+      "license": "MIT",
+      "dependencies": {
+        "linkifyjs": "^4.3.3"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/ueberdosis"
+      },
+      "peerDependencies": {
+        "@tiptap/core": "3.27.1",
+        "@tiptap/pm": "3.27.1"
+      }
+    },
+    "node_modules/@tiptap/extension-list": {
+      "version": "3.27.1",
+      "resolved": "https://registry.npmjs.org/@tiptap/extension-list/-/extension-list-3.27.1.tgz",
+      "integrity": "sha512-c2Upru7lj0/ZV/Ibww6cNz6sUS8m6Dp/9uygFhYcZOd3X8M0xBIEk42c6m6SQehkPziVA8QOgNJz7sMqsbz1OQ==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/ueberdosis"
+      },
+      "peerDependencies": {
+        "@tiptap/core": "3.27.1",
+        "@tiptap/pm": "3.27.1"
+      }
+    },
+    "node_modules/@tiptap/extension-list-item": {
+      "version": "3.27.1",
+      "resolved": "https://registry.npmjs.org/@tiptap/extension-list-item/-/extension-list-item-3.27.1.tgz",
+      "integrity": "sha512-zwRl01ETfCkWUvtvK5fw9bXtAajMPkvlkE3Cq6JvH3LF7XXJwDtNj5Tj7exacMpCaSZmlNc43vFb2rAYnrnwMA==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/ueberdosis"
+      },
+      "peerDependencies": {
+        "@tiptap/extension-list": "3.27.1"
+      }
+    },
+    "node_modules/@tiptap/extension-list-keymap": {
+      "version": "3.27.1",
+      "resolved": "https://registry.npmjs.org/@tiptap/extension-list-keymap/-/extension-list-keymap-3.27.1.tgz",
+      "integrity": "sha512-OIMZNlzPSO8WRd4ic73Fxckzl4N1tesjjLL2XApaNA/uMpO0LoF6WSRPAWv+Z24Wp92ARRJAnRP7iZoI5+Jxig==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/ueberdosis"
+      },
+      "peerDependencies": {
+        "@tiptap/extension-list": "3.27.1"
+      }
+    },
+    "node_modules/@tiptap/extension-ordered-list": {
+      "version": "3.27.1",
+      "resolved": "https://registry.npmjs.org/@tiptap/extension-ordered-list/-/extension-ordered-list-3.27.1.tgz",
+      "integrity": "sha512-GYrKqD//9nHJ2r80uXqbDMzRnFpGzbaEQRTSGaO/SH7DvXWFMow8evkOdjQ7PCQO07jNjJo75+A85Jwu3Ov3AA==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/ueberdosis"
+      },
+      "peerDependencies": {
+        "@tiptap/extension-list": "3.27.1"
+      }
+    },
+    "node_modules/@tiptap/extension-paragraph": {
+      "version": "3.27.1",
+      "resolved": "https://registry.npmjs.org/@tiptap/extension-paragraph/-/extension-paragraph-3.27.1.tgz",
+      "integrity": "sha512-7K7eo1gruOgAsnbK+GCV23AUVUI0cL1bTig8HaPneoFMVbig7vddk8jNLKBWO8TXVbG7TuHdnDN4F98vdtwh5Q==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/ueberdosis"
+      },
+      "peerDependencies": {
+        "@tiptap/core": "3.27.1"
+      }
+    },
+    "node_modules/@tiptap/extension-strike": {
+      "version": "3.27.1",
+      "resolved": "https://registry.npmjs.org/@tiptap/extension-strike/-/extension-strike-3.27.1.tgz",
+      "integrity": "sha512-Y3DW1jlSlCNCyMGHP3+3qBNNPS83wuFz4RTYGjZtvRRTCRh7apZme9XRWMq1rN5mJ2Cr7fKocA2/5Bs13KgN6Q==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/ueberdosis"
+      },
+      "peerDependencies": {
+        "@tiptap/core": "3.27.1"
+      }
+    },
+    "node_modules/@tiptap/extension-subscript": {
+      "version": "3.27.1",
+      "resolved": "https://registry.npmjs.org/@tiptap/extension-subscript/-/extension-subscript-3.27.1.tgz",
+      "integrity": "sha512-A8bokr7c7QBndZcMX0F4AK1y4xEYd5MvOczojFusaiTfvAnH3D8PwFbOPQs3ZLB8W9K3bn4g/XH55P1IAPFGyg==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/ueberdosis"
+      },
+      "peerDependencies": {
+        "@tiptap/core": "3.27.1",
+        "@tiptap/pm": "3.27.1"
+      }
+    },
+    "node_modules/@tiptap/extension-superscript": {
+      "version": "3.27.1",
+      "resolved": "https://registry.npmjs.org/@tiptap/extension-superscript/-/extension-superscript-3.27.1.tgz",
+      "integrity": "sha512-8021uld246dqhtzZdzjvnWcfiJwElPQ50zZe7Fc3QGFiNRDVWQ2ATXGJFmXEopgCU5GuZaytPMtAq4UVDXc6xw==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/ueberdosis"
+      },
+      "peerDependencies": {
+        "@tiptap/core": "3.27.1",
+        "@tiptap/pm": "3.27.1"
+      }
+    },
+    "node_modules/@tiptap/extension-text": {
+      "version": "3.27.1",
+      "resolved": "https://registry.npmjs.org/@tiptap/extension-text/-/extension-text-3.27.1.tgz",
+      "integrity": "sha512-6ZwaZwSrDh+KFFv6V1J79oO37yPs7y1bFxvk1/9Ih2rn3Xr5AWz+eMS+n8RpH3djBVVAQpdIAeYQgcn+VCSsTg==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/ueberdosis"
+      },
+      "peerDependencies": {
+        "@tiptap/core": "3.27.1"
+      }
+    },
+    "node_modules/@tiptap/extension-underline": {
+      "version": "3.27.1",
+      "resolved": "https://registry.npmjs.org/@tiptap/extension-underline/-/extension-underline-3.27.1.tgz",
+      "integrity": "sha512-N889J4nXN/TPfVt8uF9N1A0SY82E90zwc1y26lqOcw6KWNLmQrlhMh/9OD4ikLDbekmFpOBq/UicpHf/6S8hbQ==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/ueberdosis"
+      },
+      "peerDependencies": {
+        "@tiptap/core": "3.27.1"
+      }
+    },
+    "node_modules/@tiptap/extensions": {
+      "version": "3.27.1",
+      "resolved": "https://registry.npmjs.org/@tiptap/extensions/-/extensions-3.27.1.tgz",
+      "integrity": "sha512-1Tdx9faw8k0/83V6X+xCDVhV8yElGt95JxeW3YMkKQJI56QdlPz0xOdJPlMiSGJKinPyVier+x9LJD/YZUZIaw==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/ueberdosis"
+      },
+      "peerDependencies": {
+        "@tiptap/core": "3.27.1",
+        "@tiptap/pm": "3.27.1"
+      }
+    },
+    "node_modules/@tiptap/pm": {
+      "version": "3.27.1",
+      "resolved": "https://registry.npmjs.org/@tiptap/pm/-/pm-3.27.1.tgz",
+      "integrity": "sha512-Ffjx+vimmBU7zH/KrpXzJid3+pziCe/VL2aexSTP63cyQwKQ65LkFkCKaIsSpFdQQuakVZBGWjCA5RoBV852pw==",
+      "license": "MIT",
+      "dependencies": {
+        "prosemirror-changeset": "^2.3.0",
+        "prosemirror-commands": "^1.6.2",
+        "prosemirror-dropcursor": "^1.8.1",
+        "prosemirror-gapcursor": "^1.3.2",
+        "prosemirror-history": "^1.4.1",
+        "prosemirror-inputrules": "^1.4.0",
+        "prosemirror-keymap": "^1.2.3",
+        "prosemirror-model": "^1.25.7",
+        "prosemirror-schema-list": "^1.5.0",
+        "prosemirror-state": "^1.4.4",
+        "prosemirror-tables": "^1.8.0",
+        "prosemirror-transform": "^1.12.0",
+        "prosemirror-view": "^1.41.8"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/ueberdosis"
+      }
+    },
+    "node_modules/@tiptap/react": {
+      "version": "3.27.1",
+      "resolved": "https://registry.npmjs.org/@tiptap/react/-/react-3.27.1.tgz",
+      "integrity": "sha512-/Wn2fc9zMtX08MXYScDFsm4wJ8lzfhfPEdbtls7WCDlbtrop48PWlkHDBBJrywARfAQTB2mFs9KiFy9yrQm5Lg==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/use-sync-external-store": "^0.0.6",
+        "fast-equals": "^5.3.3",
+        "use-sync-external-store": "^1.4.0"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/ueberdosis"
+      },
+      "optionalDependencies": {
+        "@tiptap/extension-bubble-menu": "^3.27.1",
+        "@tiptap/extension-floating-menu": "^3.27.1"
+      },
+      "peerDependencies": {
+        "@tiptap/core": "3.27.1",
+        "@tiptap/pm": "3.27.1",
+        "@types/react": "^17.0.0 || ^18.0.0 || ^19.0.0",
+        "@types/react-dom": "^17.0.0 || ^18.0.0 || ^19.0.0",
+        "react": "^17.0.0 || ^18.0.0 || ^19.0.0",
+        "react-dom": "^17.0.0 || ^18.0.0 || ^19.0.0"
+      }
+    },
+    "node_modules/@tiptap/starter-kit": {
+      "version": "3.27.1",
+      "resolved": "https://registry.npmjs.org/@tiptap/starter-kit/-/starter-kit-3.27.1.tgz",
+      "integrity": "sha512-vfxRsqW8rCc0k4pzo0ilU3wobVi2wqVj88VZI2SlgZlNnUAkrDGDIAph7CTa9k9fshV+O1ivpEgPC5yC046jow==",
+      "license": "MIT",
+      "dependencies": {
+        "@tiptap/core": "^3.27.1",
+        "@tiptap/extension-blockquote": "^3.27.1",
+        "@tiptap/extension-bold": "^3.27.1",
+        "@tiptap/extension-bullet-list": "^3.27.1",
+        "@tiptap/extension-code": "^3.27.1",
+        "@tiptap/extension-code-block": "^3.27.1",
+        "@tiptap/extension-document": "^3.27.1",
+        "@tiptap/extension-dropcursor": "^3.27.1",
+        "@tiptap/extension-gapcursor": "^3.27.1",
+        "@tiptap/extension-hard-break": "^3.27.1",
+        "@tiptap/extension-heading": "^3.27.1",
+        "@tiptap/extension-horizontal-rule": "^3.27.1",
+        "@tiptap/extension-italic": "^3.27.1",
+        "@tiptap/extension-link": "^3.27.1",
+        "@tiptap/extension-list": "^3.27.1",
+        "@tiptap/extension-list-item": "^3.27.1",
+        "@tiptap/extension-list-keymap": "^3.27.1",
+        "@tiptap/extension-ordered-list": "^3.27.1",
+        "@tiptap/extension-paragraph": "^3.27.1",
+        "@tiptap/extension-strike": "^3.27.1",
+        "@tiptap/extension-text": "^3.27.1",
+        "@tiptap/extension-underline": "^3.27.1",
+        "@tiptap/extensions": "^3.27.1",
+        "@tiptap/pm": "^3.27.1"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/ueberdosis"
+      }
+    },
     "node_modules/@trickfilm400/rollup-plugin-off-main-thread": {
       "version": "3.0.0-pre1",
       "resolved": "https://registry.npmjs.org/@trickfilm400/rollup-plugin-off-main-thread/-/rollup-plugin-off-main-thread-3.0.0-pre1.tgz",
@@ -4303,6 +4762,28 @@
       "integrity": "sha512-trgaNyfU+Xh2Tc+ABIb44a5AYUpicB3uwirOioeOkNPPbmgRNtcWyDeeFRzjPZENO9Vq8gvVqfhaaXWLlevVwg==",
       "license": "MIT"
     },
+    "node_modules/@types/linkify-it": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/@types/linkify-it/-/linkify-it-5.0.0.tgz",
+      "integrity": "sha512-sVDA58zAw4eWAffKOaQH5/5j3XeayukzDk+ewSsnv3p4yJEZHCCzMDiZM8e0OUrRvmpGZ85jf4yDHkHsgBNr9Q==",
+      "license": "MIT"
+    },
+    "node_modules/@types/markdown-it": {
+      "version": "14.1.2",
+      "resolved": "https://registry.npmjs.org/@types/markdown-it/-/markdown-it-14.1.2.tgz",
+      "integrity": "sha512-promo4eFwuiW+TfGxhi+0x3czqTYJkG8qB17ZUJiVF10Xm7NLVRSLUsfRTU/6h1e24VvRnXCx+hG7li58lkzog==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/linkify-it": "^5",
+        "@types/mdurl": "^2"
+      }
+    },
+    "node_modules/@types/mdurl": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/@types/mdurl/-/mdurl-2.0.0.tgz",
+      "integrity": "sha512-RGdgjQUZba5p6QEFAVx2OGb8rQDL/cPRG7GiedRzMcJ1tYnUANBncjbSB1NRGwbvjcPeikRABz2nshyPk1bhWg==",
+      "license": "MIT"
+    },
     "node_modules/@types/morphdom": {
       "version": "2.3.0",
       "resolved": "https://registry.npmjs.org/@types/morphdom/-/morphdom-2.3.0.tgz",
@@ -4337,7 +4818,6 @@
       "version": "19.2.17",
       "resolved": "https://registry.npmjs.org/@types/react/-/react-19.2.17.tgz",
       "integrity": "sha512-MXfmqaVPEVgkBT/aY0aGCkRWWtByiYQXo3xdQ8r5RzuFrPiRn8Gar2tQdXSUQ2GKV3bkXckek89V8wQBY2Q/Aw==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "csstype": "^3.2.2"
@@ -4347,7 +4827,6 @@
       "version": "19.2.3",
       "resolved": "https://registry.npmjs.org/@types/react-dom/-/react-dom-19.2.3.tgz",
       "integrity": "sha512-jp2L/eY6fn+KgVVQAOqYItbF0VY/YApe5Mz2F0aykSO8gx31bYCZyvSeYxCHKvzHG5eZjc+zyaS5BrBWya2+kQ==",
-      "dev": true,
       "license": "MIT",
       "peerDependencies": {
         "@types/react": "^19.2.0"
@@ -4388,6 +4867,12 @@
       "devOptional": true,
       "license": "MIT"
     },
+    "node_modules/@types/use-sync-external-store": {
+      "version": "0.0.6",
+      "resolved": "https://registry.npmjs.org/@types/use-sync-external-store/-/use-sync-external-store-0.0.6.tgz",
+      "integrity": "sha512-zFDAD+tlpf2r4asuHEj0XH6pY6i0g5NeAHPn+15wk3BV6JA69eERFXC1gyGThDkVa1zCyKr5jox1+2LbV/AMLg==",
+      "license": "MIT"
+    },
     "node_modules/@types/ws": {
       "version": "8.18.1",
       "resolved": "https://registry.npmjs.org/@types/ws/-/ws-8.18.1.tgz",
@@ -4992,7 +5477,6 @@
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz",
       "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==",
-      "dev": true,
       "license": "Python-2.0"
     },
     "node_modules/aria-query": {
@@ -5710,7 +6194,6 @@
       "version": "3.2.3",
       "resolved": "https://registry.npmjs.org/csstype/-/csstype-3.2.3.tgz",
       "integrity": "sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/data-urls": {
@@ -6563,6 +7046,15 @@
       "integrity": "sha512-VxPP4NqbUjj6MaAOafWeUn2cXWLcCtljklUtZf0Ind4XQ+QPtmA0b18zZy0jIQx+ExRVCR/ZQpBmik5lXshNsw==",
       "license": "Apache-2.0"
     },
+    "node_modules/fast-equals": {
+      "version": "5.4.0",
+      "resolved": "https://registry.npmjs.org/fast-equals/-/fast-equals-5.4.0.tgz",
+      "integrity": "sha512-jt2DW/aNFNwke7AUd+Z+e6pz39KO5rzdbbFCg2sGafS4mk13MI7Z8O5z9cADNn5lhGODIgLwug6TZO2ctf7kcw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.0.0"
+      }
+    },
     "node_modules/fast-json-stable-stringify": {
       "version": "2.1.0",
       "resolved": "https://registry.npmjs.org/fast-json-stable-stringify/-/fast-json-stable-stringify-2.1.0.tgz",
@@ -8120,6 +8612,31 @@
         "node": ">= 0.8.0"
       }
     },
+    "node_modules/linkify-it": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/linkify-it/-/linkify-it-5.0.1.tgz",
+      "integrity": "sha512-wVoTjP4Q6R0NW5hiZkVJaFZPWgtXfoGF+6LucL3/FtiNjmcHhYjEr5f1Kqjirc1nBW07J/ZuRFumqr2oqccEWg==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/puzrin"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/markdown-it"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "uc.micro": "^2.0.0"
+      }
+    },
+    "node_modules/linkifyjs": {
+      "version": "4.3.3",
+      "resolved": "https://registry.npmjs.org/linkifyjs/-/linkifyjs-4.3.3.tgz",
+      "integrity": "sha512-P8aEP5U/D1/IlTY2OeYsErdwh9bGuLE30NcXtKEjgdHcahveQoQwM2yZNsioQHsWFz0P7KKudisbrzCgR0sDHg==",
+      "license": "MIT"
+    },
     "node_modules/locate-path": {
       "version": "6.0.0",
       "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-6.0.0.tgz",
@@ -8242,6 +8759,45 @@
         "node": ">=10"
       }
     },
+    "node_modules/markdown-it": {
+      "version": "14.2.0",
+      "resolved": "https://registry.npmjs.org/markdown-it/-/markdown-it-14.2.0.tgz",
+      "integrity": "sha512-1TGiQiJVRQ3NPmZH6sx5Cfnmg6GQm9jvC1ch4TK511NjSJvjzKLzn5pPfZRNZkRPZP0HqCioSndqH8v2nRaWVQ==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/puzrin"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/markdown-it"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "argparse": "^2.0.1",
+        "entities": "^4.4.0",
+        "linkify-it": "^5.0.1",
+        "mdurl": "^2.0.0",
+        "punycode.js": "^2.3.1",
+        "uc.micro": "^2.1.0"
+      },
+      "bin": {
+        "markdown-it": "bin/markdown-it.mjs"
+      }
+    },
+    "node_modules/markdown-it/node_modules/entities": {
+      "version": "4.5.0",
+      "resolved": "https://registry.npmjs.org/entities/-/entities-4.5.0.tgz",
+      "integrity": "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==",
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">=0.12"
+      },
+      "funding": {
+        "url": "https://github.com/fb55/entities?sponsor=1"
+      }
+    },
     "node_modules/marked": {
       "version": "14.0.0",
       "resolved": "https://registry.npmjs.org/marked/-/marked-14.0.0.tgz",
@@ -8263,6 +8819,12 @@
         "node": ">= 0.4"
       }
     },
+    "node_modules/mdurl": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/mdurl/-/mdurl-2.0.0.tgz",
+      "integrity": "sha512-Lf+9+2r+Tdp5wXDXC4PcIBjTDtq4UKjCPMQhKIuzpJNW0b96kVqSwW0bT7FhRSfmAiFYgP+SCRvdrDozfh0U5w==",
+      "license": "MIT"
+    },
     "node_modules/media-typer": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/media-typer/-/media-typer-1.1.0.tgz",
@@ -8563,6 +9125,12 @@
         "node": ">= 0.8.0"
       }
     },
+    "node_modules/orderedmap": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/orderedmap/-/orderedmap-2.1.1.tgz",
+      "integrity": "sha512-TvAWxi0nDe1j/rtMcWcIj94+Ffe6n7zhow33h40SKxmsmozs6dz/e+EajymfoFcHd7sxNn8yHM8839uixMOV6g==",
+      "license": "MIT"
+    },
     "node_modules/own-keys": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/own-keys/-/own-keys-1.0.1.tgz",
@@ -8893,6 +9461,156 @@
         "url": "https://github.com/chalk/ansi-styles?sponsor=1"
       }
     },
+    "node_modules/prosemirror-changeset": {
+      "version": "2.4.1",
+      "resolved": "https://registry.npmjs.org/prosemirror-changeset/-/prosemirror-changeset-2.4.1.tgz",
+      "integrity": "sha512-96WBLhOaYhJ+kPhLg3uW359Tz6I/MfcrQfL4EGv4SrcqKEMC1gmoGrXHecPE8eOwTVCJ4IwgfzM8fFad25wNfw==",
+      "license": "MIT",
+      "dependencies": {
+        "prosemirror-transform": "^1.0.0"
+      }
+    },
+    "node_modules/prosemirror-commands": {
+      "version": "1.7.1",
+      "resolved": "https://registry.npmjs.org/prosemirror-commands/-/prosemirror-commands-1.7.1.tgz",
+      "integrity": "sha512-rT7qZnQtx5c0/y/KlYaGvtG411S97UaL6gdp6RIZ23DLHanMYLyfGBV5DtSnZdthQql7W+lEVbpSfwtO8T+L2w==",
+      "license": "MIT",
+      "dependencies": {
+        "prosemirror-model": "^1.0.0",
+        "prosemirror-state": "^1.0.0",
+        "prosemirror-transform": "^1.10.2"
+      }
+    },
+    "node_modules/prosemirror-dropcursor": {
+      "version": "1.8.2",
+      "resolved": "https://registry.npmjs.org/prosemirror-dropcursor/-/prosemirror-dropcursor-1.8.2.tgz",
+      "integrity": "sha512-CCk6Gyx9+Tt2sbYk5NK0nB1ukHi2ryaRgadV/LvyNuO3ena1payM2z6Cg0vO1ebK8cxbzo41ku2DE5Axj1Zuiw==",
+      "license": "MIT",
+      "dependencies": {
+        "prosemirror-state": "^1.0.0",
+        "prosemirror-transform": "^1.1.0",
+        "prosemirror-view": "^1.1.0"
+      }
+    },
+    "node_modules/prosemirror-gapcursor": {
+      "version": "1.4.1",
+      "resolved": "https://registry.npmjs.org/prosemirror-gapcursor/-/prosemirror-gapcursor-1.4.1.tgz",
+      "integrity": "sha512-pMdYaEnjNMSwl11yjEGtgTmLkR08m/Vl+Jj443167p9eB3HVQKhYCc4gmHVDsLPODfZfjr/MmirsdyZziXbQKw==",
+      "license": "MIT",
+      "dependencies": {
+        "prosemirror-keymap": "^1.0.0",
+        "prosemirror-model": "^1.0.0",
+        "prosemirror-state": "^1.0.0",
+        "prosemirror-view": "^1.0.0"
+      }
+    },
+    "node_modules/prosemirror-history": {
+      "version": "1.5.0",
+      "resolved": "https://registry.npmjs.org/prosemirror-history/-/prosemirror-history-1.5.0.tgz",
+      "integrity": "sha512-zlzTiH01eKA55UAf1MEjtssJeHnGxO0j4K4Dpx+gnmX9n+SHNlDqI2oO1Kv1iPN5B1dm5fsljCfqKF9nFL6HRg==",
+      "license": "MIT",
+      "dependencies": {
+        "prosemirror-state": "^1.2.2",
+        "prosemirror-transform": "^1.0.0",
+        "prosemirror-view": "^1.31.0",
+        "rope-sequence": "^1.3.0"
+      }
+    },
+    "node_modules/prosemirror-inputrules": {
+      "version": "1.5.1",
+      "resolved": "https://registry.npmjs.org/prosemirror-inputrules/-/prosemirror-inputrules-1.5.1.tgz",
+      "integrity": "sha512-7wj4uMjKaXWAQ1CDgxNzNtR9AlsuwzHfdFH1ygEHA2KHF2DOEaXl1CJfNPAKCg9qNEh4rum975QLaCiQPyY6Fw==",
+      "license": "MIT",
+      "dependencies": {
+        "prosemirror-state": "^1.0.0",
+        "prosemirror-transform": "^1.0.0"
+      }
+    },
+    "node_modules/prosemirror-keymap": {
+      "version": "1.2.3",
+      "resolved": "https://registry.npmjs.org/prosemirror-keymap/-/prosemirror-keymap-1.2.3.tgz",
+      "integrity": "sha512-4HucRlpiLd1IPQQXNqeo81BGtkY8Ai5smHhKW9jjPKRc2wQIxksg7Hl1tTI2IfT2B/LgX6bfYvXxEpJl7aKYKw==",
+      "license": "MIT",
+      "dependencies": {
+        "prosemirror-state": "^1.0.0",
+        "w3c-keyname": "^2.2.0"
+      }
+    },
+    "node_modules/prosemirror-markdown": {
+      "version": "1.13.4",
+      "resolved": "https://registry.npmjs.org/prosemirror-markdown/-/prosemirror-markdown-1.13.4.tgz",
+      "integrity": "sha512-D98dm4cQ3Hs6EmjK500TdAOew4Z03EV71ajEFiWra3Upr7diytJsjF4mPV2dW+eK5uNectiRj0xFxYI9NLXDbw==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/markdown-it": "^14.0.0",
+        "markdown-it": "^14.0.0",
+        "prosemirror-model": "^1.25.0"
+      }
+    },
+    "node_modules/prosemirror-model": {
+      "version": "1.25.9",
+      "resolved": "https://registry.npmjs.org/prosemirror-model/-/prosemirror-model-1.25.9.tgz",
+      "integrity": "sha512-pRTklkDDMMRopyoAcrr9wV/8g/RYgrLHBuJAb5hlEuYZRdm5yqmPjWId83fpBwPpSFqEdja0H7Dfd7z1X/npcA==",
+      "license": "MIT",
+      "dependencies": {
+        "orderedmap": "^2.0.0"
+      }
+    },
+    "node_modules/prosemirror-schema-list": {
+      "version": "1.5.1",
+      "resolved": "https://registry.npmjs.org/prosemirror-schema-list/-/prosemirror-schema-list-1.5.1.tgz",
+      "integrity": "sha512-927lFx/uwyQaGwJxLWCZRkjXG0p48KpMj6ueoYiu4JX05GGuGcgzAy62dfiV8eFZftgyBUvLx76RsMe20fJl+Q==",
+      "license": "MIT",
+      "dependencies": {
+        "prosemirror-model": "^1.0.0",
+        "prosemirror-state": "^1.0.0",
+        "prosemirror-transform": "^1.7.3"
+      }
+    },
+    "node_modules/prosemirror-state": {
+      "version": "1.4.4",
+      "resolved": "https://registry.npmjs.org/prosemirror-state/-/prosemirror-state-1.4.4.tgz",
+      "integrity": "sha512-6jiYHH2CIGbCfnxdHbXZ12gySFY/fz/ulZE333G6bPqIZ4F+TXo9ifiR86nAHpWnfoNjOb3o5ESi7J8Uz1jXHw==",
+      "license": "MIT",
+      "dependencies": {
+        "prosemirror-model": "^1.0.0",
+        "prosemirror-transform": "^1.0.0",
+        "prosemirror-view": "^1.27.0"
+      }
+    },
+    "node_modules/prosemirror-tables": {
+      "version": "1.8.5",
+      "resolved": "https://registry.npmjs.org/prosemirror-tables/-/prosemirror-tables-1.8.5.tgz",
+      "integrity": "sha512-V/0cDCsHKHe/tfWkeCmthNUcEp1IVO3p6vwN8XtwE9PZQLAZJigbw3QoraAdfJPir4NKJtNvOB8oYGKRl+t0Dw==",
+      "license": "MIT",
+      "dependencies": {
+        "prosemirror-keymap": "^1.2.3",
+        "prosemirror-model": "^1.25.4",
+        "prosemirror-state": "^1.4.4",
+        "prosemirror-transform": "^1.10.5",
+        "prosemirror-view": "^1.41.4"
+      }
+    },
+    "node_modules/prosemirror-transform": {
+      "version": "1.12.0",
+      "resolved": "https://registry.npmjs.org/prosemirror-transform/-/prosemirror-transform-1.12.0.tgz",
+      "integrity": "sha512-GxboyN4AMIsoHNtz5uf2r2Ru551i5hWeCMD6E2Ib4Eogqoub0NflniaBPVQ4MrGE5yZ8JV9tUHg9qcZTTrcN4w==",
+      "license": "MIT",
+      "dependencies": {
+        "prosemirror-model": "^1.21.0"
+      }
+    },
+    "node_modules/prosemirror-view": {
+      "version": "1.41.9",
+      "resolved": "https://registry.npmjs.org/prosemirror-view/-/prosemirror-view-1.41.9.tgz",
+      "integrity": "sha512-clTunTX+eaLbr87L1V1QPheRlEQJyTlL3gXe9x3jQIk3rL0RVWxviDGz8tFaydwIVm+hKhYCyr+R/zBtWr9s6A==",
+      "license": "MIT",
+      "dependencies": {
+        "prosemirror-model": "^1.25.8",
+        "prosemirror-state": "^1.0.0",
+        "prosemirror-transform": "^1.1.0"
+      }
+    },
     "node_modules/proxy-addr": {
       "version": "2.0.7",
       "resolved": "https://registry.npmjs.org/proxy-addr/-/proxy-addr-2.0.7.tgz",
@@ -8916,6 +9634,15 @@
         "node": ">=6"
       }
     },
+    "node_modules/punycode.js": {
+      "version": "2.3.1",
+      "resolved": "https://registry.npmjs.org/punycode.js/-/punycode.js-2.3.1.tgz",
+      "integrity": "sha512-uxFIHU0YlHYhDQtV4R9J6a52SLx28BCjT+4ieh7IGbgwVJWO+km431c4yRlREUAsAmt/uMjQUyQHNEPf0M39CA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
     "node_modules/q2-preview-spa": {
       "resolved": "q2-preview-spa",
       "link": true
@@ -9249,6 +9976,12 @@
         "fsevents": "~2.3.2"
       }
     },
+    "node_modules/rope-sequence": {
+      "version": "1.3.4",
+      "resolved": "https://registry.npmjs.org/rope-sequence/-/rope-sequence-1.3.4.tgz",
+      "integrity": "sha512-UT5EDe2cu2E/6O4igUr5PSFs23nvvukicWHx6GnOPlHAiiYbzNuCRQCuiUdHJQcqKalLKlrYJnjY0ySGsXNQXQ==",
+      "license": "MIT"
+    },
     "node_modules/router": {
       "version": "2.2.0",
       "resolved": "https://registry.npmjs.org/router/-/router-2.2.0.tgz",
@@ -10441,6 +11174,12 @@
         "typescript": ">=4.8.4 <6.1.0"
       }
     },
+    "node_modules/uc.micro": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/uc.micro/-/uc.micro-2.1.0.tgz",
+      "integrity": "sha512-ARDJmphmdvUk6Glw7y9DQ2bFkKBHwQHLi2lsaH6PPmz/Ka9sFOBsBluozhDltWmnv9u/cF6Rt87znRTPV+yp/A==",
+      "license": "MIT"
+    },
     "node_modules/unbox-primitive": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/unbox-primitive/-/unbox-primitive-1.1.0.tgz",
@@ -10605,6 +11344,15 @@
         "punycode": "^2.1.0"
       }
     },
+    "node_modules/use-sync-external-store": {
+      "version": "1.6.0",
+      "resolved": "https://registry.npmjs.org/use-sync-external-store/-/use-sync-external-store-1.6.0.tgz",
+      "integrity": "sha512-Pp6GSwGP/NrPIrxVFAIkOQeyw8lFenOHijQWkUTrDvrF4ALqylP2C/KCkeS9dpUM3KvYRQhna5vt7IL95+ZQ9w==",
+      "license": "MIT",
+      "peerDependencies": {
+        "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+      }
+    },
     "node_modules/utrie": {
       "version": "1.0.2",
       "resolved": "https://registry.npmjs.org/utrie/-/utrie-1.0.2.tgz",
@@ -11410,6 +12158,12 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/w3c-keyname": {
+      "version": "2.2.8",
+      "resolved": "https://registry.npmjs.org/w3c-keyname/-/w3c-keyname-2.2.8.tgz",
+      "integrity": "sha512-dpojBhNsCNN7T82Tm7k26A6G9ML3NkhDsnw9n/eoxSRlVBB4CEtIQ/KTCLI2Fwf3ataSXRhYFkQi3SlnFwPvPQ==",
+      "license": "MIT"
+    },
     "node_modules/w3c-xmlserializer": {
       "version": "5.0.0",
       "resolved": "https://registry.npmjs.org/w3c-xmlserializer/-/w3c-xmlserializer-5.0.0.tgz",
@@ -12629,7 +13383,15 @@
         "@quarto/preview-runtime": "*",
         "@quarto/quarto-automerge-schema": "*",
         "@revealjs/react": "0.2.0",
+        "@tiptap/core": "^3.27.1",
+        "@tiptap/extension-subscript": "^3.27.1",
+        "@tiptap/extension-superscript": "^3.27.1",
+        "@tiptap/pm": "^3.27.1",
+        "@tiptap/react": "^3.27.1",
+        "@tiptap/starter-kit": "^3.27.1",
         "morphdom": "^2.7.8",
+        "prosemirror-markdown": "^1.13.1",
+        "prosemirror-model": "^1.24.1",
         "react": "^19.2.0",
         "react-dom": "^19.2.0",
         "reveal.js": "6.0.0"
diff --git a/q2-preview-spa/src/PreviewApp.tsx b/q2-preview-spa/src/PreviewApp.tsx
index a43b5e81d..a8f2db513 100644
--- a/q2-preview-spa/src/PreviewApp.tsx
+++ b/q2-preview-spa/src/PreviewApp.tsx
@@ -201,6 +201,12 @@ interface PreviewAppState {
    * on every render. Read-at-load only (no live toggle via the SPA).
    */
   nestingCursor: boolean;
+  /**
+   * Phase 1a (bd-sjb4pzx8): opt-in rich-text (tiptap) block editor. Read once
+   * at boot from `?richText=1`. When true the SPA passes `richText` to the
+   * iframe so editable paragraphs render the WYSIWYG editor. Read-at-load only.
+   */
+  richText: boolean;
   /**
    * IndexDocument V2 capture sidecar (Phase C.3) — path → CaptureRef
    * mapping. Populated by the server-side eager-capture driver (Phase
@@ -281,6 +287,19 @@ function parseNestingCursorParam(search: string): boolean {
   }
 }
 
+/**
+ * Phase 1a (bd-sjb4pzx8): parse `?richText=1` from the boot URL. Read-at-load;
+ * the SPA does not react to URL changes after mount.
+ */
+function parseRichTextParam(search: string): boolean {
+  if (!search) return false;
+  try {
+    return new URLSearchParams(search).get('richText') === '1';
+  } catch {
+    return false;
+  }
+}
+
 /**
  * P3.2: module-level empty object returned by the nestedEditBuffers memo
  * when nestingCursor is off. Referentially stable so the iframe effect dep
@@ -349,6 +368,9 @@ function buildInitialState(): PreviewAppState {
     nestingCursor: typeof window !== 'undefined'
       ? parseNestingCursorParam(window.location.search)
       : false,
+    richText: typeof window !== 'undefined'
+      ? parseRichTextParam(window.location.search)
+      : false,
     bootAttempt: 1,
     bootLastError: null,
     connection: 'connected',
@@ -1249,6 +1271,8 @@ export default function PreviewApp() {
         editingDisabled={!state.allowEdit}
         // P3.2: nesting-cursor mode + per-key nested buffers.
         unlockNestingCursor={state.nestingCursor}
+        // Phase 1a (bd-sjb4pzx8): opt-in rich-text editor (?richText=1).
+        richText={state.richText}
         nestedEditBuffers={nestedEditBuffers}
       />
       {showStaleOverlay && (
diff --git a/ts-packages/preview-renderer/package.json b/ts-packages/preview-renderer/package.json
index 082b453e4..1d2b10947 100644
--- a/ts-packages/preview-renderer/package.json
+++ b/ts-packages/preview-renderer/package.json
@@ -67,7 +67,15 @@
     "@quarto/preview-runtime": "*",
     "@quarto/quarto-automerge-schema": "*",
     "@revealjs/react": "0.2.0",
+    "@tiptap/core": "^3.27.1",
+    "@tiptap/extension-subscript": "^3.27.1",
+    "@tiptap/extension-superscript": "^3.27.1",
+    "@tiptap/pm": "^3.27.1",
+    "@tiptap/react": "^3.27.1",
+    "@tiptap/starter-kit": "^3.27.1",
     "morphdom": "^2.7.8",
+    "prosemirror-markdown": "^1.13.1",
+    "prosemirror-model": "^1.24.1",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "reveal.js": "6.0.0"
diff --git a/ts-packages/preview-renderer/src/iframe/Q2PreviewIframe.tsx b/ts-packages/preview-renderer/src/iframe/Q2PreviewIframe.tsx
index 7453d882e..87deff48e 100644
--- a/ts-packages/preview-renderer/src/iframe/Q2PreviewIframe.tsx
+++ b/ts-packages/preview-renderer/src/iframe/Q2PreviewIframe.tsx
@@ -84,6 +84,11 @@ interface Q2PreviewIframeProps {
    * (undefined/false). Forwarded unchanged in the UPDATE_AST payload.
    */
   unlockNestingCursor?: boolean;
+  /**
+   * Phase 1a (bd-sjb4pzx8): opt-in rich-text (tiptap) block editor. Forwarded
+   * unchanged in the UPDATE_AST payload into `PreviewContext.richText`.
+   */
+  richText?: boolean;
   /**
    * P3.2: per-siKey clean QMD buffers for nested blocks, produced by
    * the host's `regenerateNestedBuffers` call (gated on
@@ -143,6 +148,7 @@ export function Q2PreviewIframe({
   currentActor,
   editingDisabled,
   unlockNestingCursor,
+  richText,
   nestedEditBuffers,
   currentSlideIndex,
   onSlideChange,
@@ -296,6 +302,8 @@ export function Q2PreviewIframe({
           editingDisabled,
           // P3.2: nesting-cursor mode + per-key nested buffers.
           unlockNestingCursor,
+          // Phase 1a (bd-sjb4pzx8): opt-in rich-text editor.
+          richText,
           nestedEditBuffers,
         },
       },
@@ -314,6 +322,7 @@ export function Q2PreviewIframe({
     currentActor,
     editingDisabled,
     unlockNestingCursor,
+    richText,
     nestedEditBuffers,
   ]);
 
diff --git a/ts-packages/preview-renderer/src/q2-preview/PreviewContext.tsx b/ts-packages/preview-renderer/src/q2-preview/PreviewContext.tsx
index 01d28afad..99b5dafee 100644
--- a/ts-packages/preview-renderer/src/q2-preview/PreviewContext.tsx
+++ b/ts-packages/preview-renderer/src/q2-preview/PreviewContext.tsx
@@ -160,6 +160,32 @@ export interface PreviewContextValue {
      * boot URL query param.
      */
     unlockNestingCursor?: boolean;
+    /**
+     * Phase 1a (bd-sjb4pzx8): opt-in rich-text (tiptap) block editor. When true,
+     * an editable block renders a WYSIWYG tiptap editor instead of the monospaced
+     * textarea. Default-off (undefined/false). Set by the hub-client preference or
+     * the SPA's `?richText=1` boot URL query param, plumbed like
+     * `unlockNestingCursor`. v1 covers single paragraphs; other block types fall
+     * back to the textarea even when this is on.
+     */
+    richText?: boolean;
+    /**
+     * Phase 1a (bd-sjb4pzx8): per-edit-session editor surface choice when
+     * `richText` is on. `'rich'` (default) renders the tiptap editor; `'plain'`
+     * renders the monospaced textarea (the escape hatch for syntax the rich
+     * editor can't express). Reset to `'rich'` each time a new block is opened.
+     * Toggled by the left-margin affordance.
+     */
+    editorMode?: 'rich' | 'plain';
+    /** Set the current edit session's editor surface (rich/plain). */
+    setEditorMode?: (mode: 'rich' | 'plain') => void;
+    /**
+     * True while a rich/plain surface swap is in flight. The outgoing surface's
+     * blur (fired as it unmounts) must NOT commit/close the edit session — the
+     * swap is not a "done editing" gesture. Set by the toggle, cleared on the
+     * next tick. Both surfaces' blur handlers check it.
+     */
+    editorModeSwitchRef?: MutableRefObject<boolean>;
     /**
      * §3: stable ref mirror of `unlockNestingCursor`, updated in PreviewRoot's
      * render body. The hover handlers (`onPointerMove`/`onPointerLeave`) are
diff --git a/ts-packages/preview-renderer/src/q2-preview/PreviewRoot.tsx b/ts-packages/preview-renderer/src/q2-preview/PreviewRoot.tsx
index 7efa17850..2ddf25b3d 100644
--- a/ts-packages/preview-renderer/src/q2-preview/PreviewRoot.tsx
+++ b/ts-packages/preview-renderer/src/q2-preview/PreviewRoot.tsx
@@ -159,6 +159,11 @@ export interface PreviewRootProps {
      * exposes nesting-cursor behaviour. Default-off (undefined/false).
      */
     unlockNestingCursor?: boolean;
+    /**
+     * Phase 1a (bd-sjb4pzx8): opt-in rich-text (tiptap) block editor. When true,
+     * editable paragraphs render a WYSIWYG editor instead of the textarea.
+     */
+    richText?: boolean;
     /**
      * P3.2: per-siKey clean QMD buffers for nested blocks, produced by
      * the host's `regenerateNestedBuffers` call. Undefined when off.
@@ -247,6 +252,12 @@ export function PreviewRoot(props: PreviewRootProps) {
         leafAnchorR0?: number;
         seededDraft?: string;
     } | null>(null);
+    // Phase 1a (bd-sjb4pzx8): the active edit surface when richText is on.
+    // Session-sticky (persists until the user toggles), default 'rich'.
+    const [editorMode, setEditorMode] = useState<'rich' | 'plain'>('rich');
+    // True briefly during a rich/plain swap so the outgoing surface's
+    // unmount-blur doesn't commit/close the session (see PreviewContext).
+    const editorModeSwitchRef = useRef(false);
     // Root-held ref for the in-flight edit draft. Seeded with anchorSlice at
     // activation; reset to null on close. Referentially stable → no extra
     // re-renders from draft changes.
@@ -1498,6 +1509,10 @@ export function PreviewRoot(props: PreviewRootProps) {
                 editingDisabled: props.editingDisabled,
                 unlockNestingCursor: props.unlockNestingCursor,
                 unlockNestingCursorRef,
+                richText: props.richText,
+                editorMode,
+                setEditorMode,
+                editorModeSwitchRef,
                 nestedEditBuffers: props.nestedEditBuffers,
                 requestMove,
                 pendingCaretRef,
diff --git a/ts-packages/preview-renderer/src/q2-preview/dispatchers.tsx b/ts-packages/preview-renderer/src/q2-preview/dispatchers.tsx
index b9dc064fc..c177d2117 100644
--- a/ts-packages/preview-renderer/src/q2-preview/dispatchers.tsx
+++ b/ts-packages/preview-renderer/src/q2-preview/dispatchers.tsx
@@ -13,6 +13,8 @@ import { normalizeLineEndings } from '../utils/normalizeLineEndings';
 import { isOnFirstVisualLine, isOnLastVisualLine, getLogicalColumn, placeCaretAtColumn } from './caretGeometry';
 import { buildNestingCommitDestination, classifyNestingKey, detectPlatform } from './nestingNav';
 import { editBaseline } from './outerBlocks';
+import { RichTextEditor } from './richtext/RichTextEditor';
+import { EditAffordance } from './richtext/EditAffordance';
 
 // P3.3 §3b: detect platform once at module load so classifyNestingKey can
 // distinguish mac (Cmd+Ctrl) from other (Alt+Shift) nesting chords.
@@ -61,11 +63,15 @@ function renderMeasuredEdit(
     node: BlockNode | CustomBlockNode,
     textarea: React.ReactNode,
     editTarget: NonNullable<PreviewContextValue['editTarget']>,
-    activeEditRegionRef?: React.MutableRefObject<HTMLDivElement | null>,
+    activeEditRegionRef: React.MutableRefObject<HTMLDivElement | null> | undefined,
+    ctx: PreviewContextValue,
+    richSupported: boolean,
 ): React.ReactNode {
     const wrapperStyle: React.CSSProperties = {
         ...(editTarget.boxStyle as React.CSSProperties),
         boxSizing: 'content-box',
+        // Positioning context for the left-margin edit affordance.
+        position: 'relative',
     };
     // Lists carry a large left padding (the bullet/number gutter). Replicating
     // it would indent the textarea away from column 0 where the source begins;
@@ -77,7 +83,12 @@ function renderMeasuredEdit(
     }
     return (
         <AttributionWrap node={node} as="div">
-            <div ref={activeEditRegionRef} id="q2-active-edit-region" style={wrapperStyle}>{textarea}</div>
+            <div ref={activeEditRegionRef} id="q2-active-edit-region" style={wrapperStyle}>
+                {/* Left-margin affordance (Editing… + rich/plain toggle), shown only
+                    when the rich editor feature is enabled. */}
+                {ctx.richText && <EditAffordance ctx={ctx} richSupported={richSupported} />}
+                {textarea}
+            </div>
         </AttributionWrap>
     );
 }
@@ -363,6 +374,9 @@ function EditTextarea({
             onBlur={() => {
                 // Do not commit mid-IME-composition (e.g. mobile dismiss before compositionend).
                 if (isComposingRef.current) return;
+                // A rich/plain surface swap is not a commit (Phase 1a) — the swap
+                // unmounts this textarea; its blur must not close the session.
+                if (ctx.editorModeSwitchRef?.current) return;
                 // P2.4d: check for a pending click-switch FIRST. If a dirty switch is in
                 // progress, handleClickSwitchBlur commits A, stashes B's landing, and closes
                 // the editor — all in one shot. Returns true when consumed (skip normal path).
@@ -491,6 +505,33 @@ function renderBlockTextarea(
     return <EditTextarea ctx={ctx} resolved={resolved} />;
 }
 
+/**
+ * Block types the rich-text editor can handle. Everything else falls back to the
+ * textarea even when `richText` is on. 1a: Para. 1b: + Header. (1c: lists/quotes.)
+ */
+const RICHTEXT_SUPPORTED_TYPES = new Set<string>(['Para', 'Header']);
+
+/** True when the rich editor is available for this block (flag on + supported type). */
+function richTextAvailable(ctx: PreviewContextValue, sourceNodeType: string): boolean {
+    return !!ctx.richText && RICHTEXT_SUPPORTED_TYPES.has(sourceNodeType);
+}
+
+/**
+ * Which edit surface to render for the active block: the tiptap editor when rich
+ * text is available AND the session mode is 'rich' (the default); otherwise the
+ * monospaced textarea (flag off, unsupported type, or the user toggled to plain).
+ */
+function renderBlockEditSurface(
+    ctx: PreviewContextValue,
+    resolved: ResolvedSource,
+    sourceNodeType: string,
+): React.ReactNode {
+    if (richTextAvailable(ctx, sourceNodeType) && (ctx.editorMode ?? 'rich') !== 'plain') {
+        return <RichTextEditor ctx={ctx} resolved={resolved} />;
+    }
+    return renderBlockTextarea(ctx, resolved);
+}
+
 // ---------------------------------------------------------------------------
 
 /**
@@ -529,12 +570,17 @@ export const Block = (args: NodeArgs<BlockNode>) => {
     const resolved = ctx?.resolveSource ? ctx.resolveSource(args.node) : null;
 
     if (isBlockEditTarget(ctx, resolved) && ctx) {
-        // Editing: replace the block with a measure-and-set textarea wrapper
-        // that reproduces the element's exact box (see renderMeasuredEdit).
+        // Editing: replace the block with a measure-and-set wrapper that
+        // reproduces the element's exact box (see renderMeasuredEdit). The inner
+        // surface is the rich-text editor (opt-in, paragraphs) or the textarea.
         // Pass activeEditRegionRef so the wrapper div is tracked — used by
         // useBlockEditHover's onPointerUp to suppress parent-climb activation.
-        const textarea = renderBlockTextarea(ctx, resolved!);
-        return renderMeasuredEdit(args.node, textarea, ctx.editTarget!, ctx.activeEditRegionRef);
+        const sourceNodeType = (resolved!.sourceNode as { t: string }).t;
+        const surface = renderBlockEditSurface(ctx, resolved!, sourceNodeType);
+        return renderMeasuredEdit(
+            args.node, surface, ctx.editTarget!, ctx.activeEditRegionRef,
+            ctx, richTextAvailable(ctx, sourceNodeType),
+        );
     }
 
     const Component = registry[args.node.t];
@@ -593,7 +639,8 @@ export const CustomBlock = (args: NodeArgs<CustomBlockNode>) => {
 
     if (isBlockEditTarget(ctx, resolved) && ctx) {
         const textarea = renderBlockTextarea(ctx, resolved!);
-        return renderMeasuredEdit(args.node, textarea, ctx.editTarget!, ctx.activeEditRegionRef);
+        // CustomBlocks are not rich-editable in v1 → always textarea, no toggle.
+        return renderMeasuredEdit(args.node, textarea, ctx.editTarget!, ctx.activeEditRegionRef, ctx, false);
     }
 
     const Component =
diff --git a/ts-packages/preview-renderer/src/q2-preview/entry.tsx b/ts-packages/preview-renderer/src/q2-preview/entry.tsx
index 370037d3f..a8ac88535 100644
--- a/ts-packages/preview-renderer/src/q2-preview/entry.tsx
+++ b/ts-packages/preview-renderer/src/q2-preview/entry.tsx
@@ -197,6 +197,11 @@ interface UpdateAstPayload {
      * `PreviewContext.unlockNestingCursor`. Default-off (undefined/false).
      */
     unlockNestingCursor?: boolean;
+    /**
+     * Phase 1a (bd-sjb4pzx8): opt-in rich-text editor. Forwarded into
+     * `PreviewContext.richText`. Default-off (undefined/false).
+     */
+    richText?: boolean;
     /**
      * P3.2: per-siKey clean QMD buffers for nested blocks. Forwarded
      * into `PreviewContext.nestedEditBuffers`. Undefined when flag is off.
@@ -334,6 +339,7 @@ function updateAst(payload: UpdateAstPayload) {
         currentActor,
         editingDisabled,
         unlockNestingCursor,
+        richText,
         nestedEditBuffers,
     } = payload;
     const rootElement = document.getElementById('root');
@@ -359,6 +365,7 @@ function updateAst(payload: UpdateAstPayload) {
                 currentActor={currentActor ?? null}
                 editingDisabled={editingDisabled}
                 unlockNestingCursor={unlockNestingCursor}
+                richText={richText}
                 nestedEditBuffers={nestedEditBuffers}
                 customRegistry={customRegistry}
                 scrollToAnchor={scrollToAnchorInDocument}
diff --git a/ts-packages/preview-renderer/src/q2-preview/richtext/EditAffordance.tsx b/ts-packages/preview-renderer/src/q2-preview/richtext/EditAffordance.tsx
new file mode 100644
index 000000000..fa40b5628
--- /dev/null
+++ b/ts-packages/preview-renderer/src/q2-preview/richtext/EditAffordance.tsx
@@ -0,0 +1,67 @@
+// Phase 1a (bd-sjb4pzx8) — left-margin edit affordance.
+//
+// Parked in the LEFT MARGIN of the active edit box (absolute-positioned, off the
+// text) so it never hijacks clicking/selecting. Shows "Editing…" plus — when the
+// block supports the rich editor — a rich/plain surface toggle (the escape hatch
+// to the monospaced textarea for syntax the rich editor can't express).
+//
+// Rendered by `renderMeasuredEdit` for BOTH surfaces, so the toggle is reachable
+// from rich AND plain mode. Only shown when `ctx.richText` is on.
+
+import type { MouseEvent } from 'react';
+import type { PreviewContextValue } from './../PreviewContext';
+import { ensureRichTextStyles } from './styles';
+
+export function EditAffordance({
+  ctx,
+  richSupported,
+}: {
+  ctx: PreviewContextValue;
+  richSupported: boolean;
+}) {
+  // Inject the shared stylesheet here too — the affordance renders in plain mode
+  // (textarea), where RichTextEditor (the other injection site) isn't mounted.
+  ensureRichTextStyles();
+  const mode = ctx.editorMode ?? 'rich';
+
+  // mousedown + preventDefault: keep focus in the editor (a real blur would
+  // commit/close the surface before the mode switch lands).
+  const choose = (m: 'rich' | 'plain') => (e: MouseEvent) => {
+    e.preventDefault();
+    e.stopPropagation();
+    if (m === mode) return;
+    // Mark the swap so the outgoing surface's unmount-blur doesn't commit/close.
+    // Cleared on the next tick, after the synchronous unmount-blur has passed.
+    if (ctx.editorModeSwitchRef) ctx.editorModeSwitchRef.current = true;
+    ctx.setEditorMode?.(m);
+    setTimeout(() => {
+      if (ctx.editorModeSwitchRef) ctx.editorModeSwitchRef.current = false;
+    }, 0);
+  };
+
+  return (
+    <div className="q2-edit-affordance" contentEditable={false}>
+      <div className="q2-edit-affordance-label">Editing…</div>
+      {richSupported && (
+        <div className="q2-edit-mode-toggle" role="group" aria-label="Editor mode">
+          <button
+            type="button"
+            className={mode === 'rich' ? 'q2-edit-mode-active' : ''}
+            aria-pressed={mode === 'rich'}
+            onMouseDown={choose('rich')}
+          >
+            rich text
+          </button>
+          <button
+            type="button"
+            className={mode === 'plain' ? 'q2-edit-mode-active' : ''}
+            aria-pressed={mode === 'plain'}
+            onMouseDown={choose('plain')}
+          >
+            plain text
+          </button>
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/ts-packages/preview-renderer/src/q2-preview/richtext/RichTextEditor.tsx b/ts-packages/preview-renderer/src/q2-preview/richtext/RichTextEditor.tsx
new file mode 100644
index 000000000..51214912b
--- /dev/null
+++ b/ts-packages/preview-renderer/src/q2-preview/richtext/RichTextEditor.tsx
@@ -0,0 +1,201 @@
+// Phase 1a (bd-sjb4pzx8) — the WYSIWYG block editor.
+//
+// Drop-in alternative to `EditTextarea`: rendered inside the SAME measured box,
+// seeded from the block's untransformed AST subtree (astToDoc), committing
+// markdown through the UNCHANGED `commitTextEdit` path. Because it lives in the
+// preview iframe — which already has the Bootstrap + Quarto theme CSS loaded —
+// the editor's semantic tags (<p>, <em>, <strong>, <a>) are styled by the theme
+// automatically, so editing looks like the rendered page.
+//
+// Scope (1a): single paragraph, inline editing only. Enter is intercepted (no
+// structural splits yet — that arrives in 1c). Dirtiness is read from
+// ProseMirror's own change signal (`doc.eq`), NOT from comparing serialized text,
+// so an unedited open-and-close is a true no-op (C3) and never reformats.
+
+import { useEffect, useMemo, useRef } from 'react';
+import { useEditor, EditorContent } from '@tiptap/react';
+import StarterKit from '@tiptap/starter-kit';
+import Subscript from '@tiptap/extension-subscript';
+import Superscript from '@tiptap/extension-superscript';
+import type { Editor } from '@tiptap/core';
+import type { Node as PMNode } from '@tiptap/pm/model';
+import type { PreviewContextValue, ResolvedSource } from './../PreviewContext';
+import { buildNestingCommitDestination } from './../nestingNav';
+import { astToDoc } from './astToProseMirror';
+import { docToMarkdown } from './serializer';
+import { Chip } from './chipExtension';
+import { RichTextToolbar } from './RichTextToolbar';
+import type { AstNode, PoolEntry } from './ast';
+import { ensureRichTextStyles } from './styles';
+
+function commitDestination(ctx: PreviewContextValue, resolved: ResolvedSource): string | null {
+  if (ctx.editTargetRef !== undefined) {
+    return buildNestingCommitDestination(ctx.editTargetRef.current);
+  }
+  return JSON.stringify(resolved.sourceEntry);
+}
+
+/** True when this editor is still the active target (guards stale-unmount blur). */
+function isStillActive(ctx: PreviewContextValue, resolved: ResolvedSource): boolean {
+  if (ctx.editTargetRef === undefined) return true;
+  const cur = ctx.editTargetRef.current;
+  return !!cur && cur.anchorR0 === resolved.sourceEntry.r[0];
+}
+
+export function RichTextEditor({
+  ctx,
+  resolved,
+}: {
+  ctx: PreviewContextValue;
+  resolved: ResolvedSource;
+}) {
+  ensureRichTextStyles();
+
+  // Seed the document from the AST subtree once, at mount.
+  const seedJSON = useMemo(() => {
+    const pool = (ctx.pool ?? []) as PoolEntry[];
+    const src = ctx.content ?? '';
+    const { doc } = astToDoc([resolved.sourceNode as unknown as AstNode], pool, src);
+    return doc.toJSON();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  // The seeded doc, captured post-normalization in onCreate — the dirty baseline.
+  const initialDocRef = useRef<PMNode | null>(null);
+  // The original markdown the textarea seeds from (so reverting an unedited rich
+  // doc restores the exact source rather than a re-serialized form).
+  const originalMarkdownRef = useRef<string | null>(null);
+  // Latch so a commit fires at most once (blur can follow a key-commit).
+  const committedRef = useRef(false);
+
+  const editor = useEditor({
+    extensions: [
+      StarterKit.configure({
+        // 1a: paragraphs + inline marks. 1b: + headings. (1c: lists/quotes/code.)
+        heading: { levels: [1, 2, 3, 4, 5, 6] },
+        blockquote: false,
+        bulletList: false,
+        orderedList: false,
+        listItem: false,
+        codeBlock: false,
+        horizontalRule: false,
+        // No phantom trailing paragraph: a single-heading (or any non-paragraph)
+        // block would otherwise get an empty trailing <p> — extra vertical space
+        // in the editor AND a stray blank block on commit.
+        trailingNode: false,
+        link: { openOnClick: false },
+      }),
+      Subscript,
+      Superscript,
+      Chip,
+    ],
+    content: seedJSON,
+    autofocus: 'end',
+    // 1b: edit existing structure only — no markdown auto-conversion (e.g. typing
+    // "## " must not turn a paragraph into a heading, or change a heading's level).
+    // Structural edits are a later phase; bold/italic via Cmd-B/I still work.
+    enableInputRules: false,
+    enablePasteRules: false,
+    onCreate({ editor: ed }) {
+      initialDocRef.current = ed.state.doc;
+      // editDraftRef was seeded with the original markdown at activation; remember
+      // it so we can restore it verbatim if the user reverts their rich edits.
+      originalMarkdownRef.current = ctx.editDraftRef?.current ?? null;
+    },
+    onUpdate({ editor: ed }) {
+      // Keep the shared markdown draft current so a switch to plain text carries
+      // the rich edits across (dirty-aware: when unchanged, restore the verbatim
+      // original so an untouched toggle doesn't reformat the block — C3).
+      if (!ctx.editDraftRef) return;
+      const base = initialDocRef.current;
+      ctx.editDraftRef.current =
+        base && !ed.state.doc.eq(base)
+          ? docToMarkdown(ed.state.doc)
+          : originalMarkdownRef.current ?? docToMarkdown(ed.state.doc);
+    },
+  });
+
+  const commit = (ed: Editor) => {
+    if (committedRef.current) return;
+    // A rich/plain surface swap is not a commit — the content is preserved in
+    // editDraftRef; the swap must not close the edit session.
+    if (ctx.editorModeSwitchRef?.current) return;
+    // Stale-unmount guard (mirrors EditTextarea): a dropped/re-anchored editor's
+    // blur must not write to a byte range it no longer owns.
+    if (!isStillActive(ctx, resolved)) return;
+    committedRef.current = true;
+
+    const base = initialDocRef.current;
+    const changed = base ? !ed.state.doc.eq(base) : false;
+    if (!changed) {
+      // True no-op: unedited open-and-close never reformats (C3).
+      ctx.setEditTarget?.(null);
+      return;
+    }
+    const dest = commitDestination(ctx, resolved);
+    if (dest === null) {
+      ctx.setEditTarget?.(null);
+      return;
+    }
+    ctx.commitTextEdit?.(dest, docToMarkdown(ed.state.doc));
+    ctx.setEditTarget?.(null);
+  };
+
+  const cancel = () => {
+    committedRef.current = true;
+    ctx.requestFocusRestore?.(resolved.sourceEntry.r[0]);
+    ctx.setEditTarget?.(null);
+  };
+
+  // The whole edit box (editor + toolbar + link input) is one focus scope: we
+  // commit only when focus leaves it entirely, so focusing the toolbar's link
+  // input keeps the session open.
+  const rootRef = useRef<HTMLDivElement | null>(null);
+
+  // Keyboard: Esc cancels; Mod-Enter commits; plain Enter is swallowed (no split).
+  // Commit: a focusout from the edit box (focus moved outside it) commits.
+  useEffect(() => {
+    if (!editor) return;
+    const dom = editor.view.dom as HTMLElement;
+    const root = rootRef.current;
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        e.preventDefault();
+        cancel();
+      } else if (e.key === 'Enter' && (e.metaKey || e.ctrlKey)) {
+        e.preventDefault();
+        ctx.requestFocusRestore?.(resolved.sourceEntry.r[0]);
+        commit(editor);
+      } else if (e.key === 'Enter' && !e.shiftKey) {
+        // 1a/1b: no structural split. Swallow plain Enter (Shift+Enter = hard break).
+        e.preventDefault();
+      }
+    };
+    const onFocusOut = (e: FocusEvent) => {
+      // A surface swap fires this as the editor unmounts — not a commit.
+      if (ctx.editorModeSwitchRef?.current) return;
+      const next = e.relatedTarget as Node | null;
+      // Focus stayed within the edit box (toolbar button / link input) — not a commit.
+      if (next && root && root.contains(next)) return;
+      ctx.requestFocusRestore?.(resolved.sourceEntry.r[0]);
+      commit(editor);
+    };
+    dom.addEventListener('keydown', onKeyDown);
+    root?.addEventListener('focusout', onFocusOut);
+    return () => {
+      dom.removeEventListener('keydown', onKeyDown);
+      root?.removeEventListener('focusout', onFocusOut);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [editor]);
+
+  // The left-margin affordance (Editing… + rich/plain toggle) is rendered by
+  // renderMeasuredEdit so it is shared with the plain-text surface. The
+  // formatting toolbar is rich-only and lives here (it needs the editor).
+  return (
+    <div className="q2-richtext-editor" ref={rootRef}>
+      {editor && <RichTextToolbar editor={editor} />}
+      {editor && <EditorContent editor={editor} />}
+    </div>
+  );
+}
diff --git a/ts-packages/preview-renderer/src/q2-preview/richtext/RichTextToolbar.tsx b/ts-packages/preview-renderer/src/q2-preview/richtext/RichTextToolbar.tsx
new file mode 100644
index 000000000..b380a0f54
--- /dev/null
+++ b/ts-packages/preview-renderer/src/q2-preview/richtext/RichTextToolbar.tsx
@@ -0,0 +1,151 @@
+// Phase 1b (bd-sjb4pzx8) — a small formatting toolbar anchored to the top-left
+// of the rich-text edit box.
+//
+// Mark buttons (bold/italic/strike/sub/sup) are second triggers for the same
+// commands Cmd-B/I fire — `toggleMark` over the current selection (ProseMirror
+// applies/removes the mark across the range; an empty selection sets a stored
+// mark so the next typed text gets it). The link button opens a small URL input
+// and uses `extendMarkRange('link')` so an existing link can be edited/removed by
+// placing the cursor anywhere inside it.
+//
+// All buttons use mousedown-preventDefault so clicking them never blurs the
+// editor (which would collapse the selection before the command runs). The link
+// input DOES take focus; the editor's commit is scoped to "focus left the whole
+// edit box" (see RichTextEditor), so focusing the input keeps the session open.
+
+import { useEffect, useRef, useState, type MouseEvent } from 'react';
+import type { Editor } from '@tiptap/core';
+
+interface MarkSpec {
+  name: string;
+  label: string;
+  title: string;
+}
+
+const MARKS: MarkSpec[] = [
+  { name: 'bold', label: 'B', title: 'Bold (⌘B)' },
+  { name: 'italic', label: 'I', title: 'Italic (⌘I)' },
+  { name: 'strike', label: 'S', title: 'Strikethrough' },
+  { name: 'subscript', label: 'x₂', title: 'Subscript' },
+  { name: 'superscript', label: 'x²', title: 'Superscript' },
+];
+
+export function RichTextToolbar({ editor }: { editor: Editor }) {
+  // Re-render on selection/content changes so isActive() highlights stay current.
+  const [, force] = useState(0);
+  useEffect(() => {
+    const bump = () => force((n) => n + 1);
+    editor.on('selectionUpdate', bump);
+    editor.on('transaction', bump);
+    return () => {
+      editor.off('selectionUpdate', bump);
+      editor.off('transaction', bump);
+    };
+  }, [editor]);
+
+  const [linkOpen, setLinkOpen] = useState(false);
+  const [linkUrl, setLinkUrl] = useState('');
+  const linkInputRef = useRef<HTMLInputElement | null>(null);
+
+  // Reliably focus + select the URL input when the link editor opens (more robust
+  // than the autoFocus prop alone).
+  useEffect(() => {
+    if (linkOpen && linkInputRef.current) {
+      linkInputRef.current.focus();
+      linkInputRef.current.select();
+    }
+  }, [linkOpen]);
+
+  const toggleMark = (name: string) => (e: MouseEvent) => {
+    e.preventDefault();
+    editor.chain().focus().toggleMark(name).run();
+  };
+
+  const openLinkEditor = (e: MouseEvent) => {
+    e.preventDefault();
+    const existing = editor.isActive('link') ? (editor.getAttributes('link').href as string) : '';
+    setLinkUrl(existing ?? '');
+    setLinkOpen(true);
+  };
+
+  const applyLink = () => {
+    const url = linkUrl.trim();
+    if (!url) {
+      // Empty URL on an existing link removes it; otherwise just cancel.
+      if (editor.isActive('link')) {
+        editor.chain().focus().extendMarkRange('link').unsetLink().run();
+      }
+    } else if (editor.state.selection.empty && !editor.isActive('link')) {
+      // No selection and not in a link: insert the URL as linked text.
+      editor.chain().focus().insertContent({ type: 'text', text: url, marks: [{ type: 'link', attrs: { href: url } }] }).run();
+    } else {
+      editor.chain().focus().extendMarkRange('link').setLink({ href: url }).run();
+    }
+    setLinkOpen(false);
+  };
+
+  const removeLink = () => {
+    editor.chain().focus().extendMarkRange('link').unsetLink().run();
+    setLinkOpen(false);
+  };
+
+  const cancelLink = () => {
+    setLinkOpen(false);
+    editor.chain().focus().run();
+  };
+
+  return (
+    <div className="q2-rt-toolbar" contentEditable={false}>
+      {!linkOpen ? (
+        <>
+          {MARKS.map((m) => (
+            <button
+              key={m.name}
+              type="button"
+              title={m.title}
+              aria-pressed={editor.isActive(m.name)}
+              className={`q2-rt-tb-btn q2-rt-tb-${m.name}${editor.isActive(m.name) ? ' q2-rt-tb-active' : ''}`}
+              onMouseDown={toggleMark(m.name)}
+            >
+              {m.label}
+            </button>
+          ))}
+          <span className="q2-rt-tb-sep" />
+          <button
+            type="button"
+            title="Link"
+            aria-pressed={editor.isActive('link')}
+            className={`q2-rt-tb-btn q2-rt-tb-link${editor.isActive('link') ? ' q2-rt-tb-active' : ''}`}
+            onMouseDown={openLinkEditor}
+          >
+            🔗
+          </button>
+        </>
+      ) : (
+        <div className="q2-rt-link-editor">
+          <input
+            ref={linkInputRef}
+            type="url"
+            className="q2-rt-link-input"
+            placeholder="https://…"
+            value={linkUrl}
+            onChange={(e) => setLinkUrl(e.currentTarget.value)}
+            onKeyDown={(e) => {
+              if (e.key === 'Enter') {
+                e.preventDefault();
+                applyLink();
+              } else if (e.key === 'Escape') {
+                e.preventDefault();
+                cancelLink();
+              }
+            }}
+          />
+          <button type="button" className="q2-rt-tb-btn" title="Apply" onMouseDown={(e) => { e.preventDefault(); applyLink(); }}>✓</button>
+          {editor.isActive('link') && (
+            <button type="button" className="q2-rt-tb-btn" title="Remove link" onMouseDown={(e) => { e.preventDefault(); removeLink(); }}>✕</button>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/ts-packages/preview-renderer/src/q2-preview/richtext/ast.ts b/ts-packages/preview-renderer/src/q2-preview/richtext/ast.ts
new file mode 100644
index 000000000..1c383a1d9
--- /dev/null
+++ b/ts-packages/preview-renderer/src/q2-preview/richtext/ast.ts
@@ -0,0 +1,55 @@
+// Phase 1 (bd-sjb4pzx8) — minimal Pandoc-AST shapes + source slicing for the
+// rich-text bridge. The untransformed AST nodes carry `s` (a pool index) and the
+// pool entries carry `r` (UTF-8 byte range); opaque constructs are reconstructed
+// verbatim by slicing `content` at that range.
+
+/** A source-info pool entry. Only `r` (byte range) is needed here. */
+export interface PoolEntry {
+  r: [number, number];
+  t?: number;
+  d?: unknown;
+}
+
+/** A node's literal source location (begin/end byte offset in `o`). */
+export interface NodeLoc {
+  b?: { o?: number };
+  e?: { o?: number };
+}
+
+/** Loose annotated Pandoc node: `t` tag, `c` content, `s` pool index, `l` loc. */
+export interface AstNode {
+  t: string;
+  c?: unknown;
+  s?: number;
+  l?: NodeLoc;
+  [k: string]: unknown;
+}
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+/** Slice `src` by UTF-8 byte offsets (pampa's range coordinate space). */
+export function sliceBytes(src: string, start: number, end: number): string {
+  return decoder.decode(encoder.encode(src).subarray(start, end));
+}
+
+/**
+ * Verbatim source text for a node.
+ *
+ * Prefers the node's own literal location (`.l`) over the compact pool entry
+ * (`.s`). The pool range is reliable for leaf inlines (Math/Cite) but is
+ * mis-assigned for container inlines like shortcode spans — there the pool
+ * points at an adjacent space while `.l` points at the actual token
+ * (e.g. `{{< meta key >}}`). Falls back to the pool, then null.
+ */
+export function nodeSource(node: AstNode, pool: PoolEntry[], src: string): string | null {
+  const b = node.l?.b?.o;
+  const e = node.l?.e?.o;
+  if (typeof b === 'number' && typeof e === 'number' && e >= b) {
+    return sliceBytes(src, b, e);
+  }
+  if (node.s == null) return null;
+  const entry = pool[node.s];
+  if (!entry || !entry.r) return null;
+  return sliceBytes(src, entry.r[0], entry.r[1]);
+}
diff --git a/ts-packages/preview-renderer/src/q2-preview/richtext/astToProseMirror.ts b/ts-packages/preview-renderer/src/q2-preview/richtext/astToProseMirror.ts
new file mode 100644
index 000000000..0e4287a0f
--- /dev/null
+++ b/ts-packages/preview-renderer/src/q2-preview/richtext/astToProseMirror.ts
@@ -0,0 +1,195 @@
+// Phase 1 (bd-sjb4pzx8) — Pandoc untransformed AST -> ProseMirror document.
+//
+// The "seed" direction: build the editor's document from the typed AST we already
+// have (resolved.sourceNode + the source-info pool), NOT by re-lexing markdown.
+// Opaque constructs (Math, Cite, Span.quarto-shortcode__, RawInline, and — as a
+// whole-block fallback — Div/RawBlock/Table/Figure/DefinitionList) become verbatim
+// `chip` atoms by slicing source at their byte range.
+//
+// Returns a ProseMirror Node built against `richTextSchema`. The live editor is
+// seeded with `.toJSON()` of this node (tiptap re-parses it against its
+// name-identical schema); tests serialize the node directly.
+
+import type { Mark, Node as PMNode } from '@tiptap/pm/model';
+import { richTextSchema, type ChipKind } from './schema';
+import { type AstNode, type PoolEntry, nodeSource } from './ast';
+
+interface Ctx {
+  pool: PoolEntry[];
+  src: string;
+  /** opaque node types we could not richly represent (reported for diagnostics) */
+  unknown: Set<string>;
+}
+
+const S = richTextSchema;
+const M = S.marks;
+const N = S.nodes;
+
+function chip(node: AstNode, kind: ChipKind, ctx: Ctx, fallback: string): PMNode {
+  const src = nodeSource(node, ctx.pool, ctx.src) ?? fallback;
+  return N.chip.create({ src, kind });
+}
+
+function asArray(c: unknown): AstNode[] {
+  return Array.isArray(c) ? (c as AstNode[]) : [];
+}
+
+// ---- inlines ---------------------------------------------------------------
+
+function inlines(items: AstNode[], marks: readonly Mark[], ctx: Ctx): PMNode[] {
+  const out: PMNode[] = [];
+  for (const node of items) {
+    switch (node.t) {
+      case 'Str':
+        out.push(S.text(node.c as string, marks));
+        break;
+      case 'Space':
+      case 'SoftBreak':
+        // SoftBreak collapses to a space (reformatted-but-equivalent).
+        out.push(S.text(' ', marks));
+        break;
+      case 'LineBreak':
+        out.push(N.hardBreak.create(undefined, undefined, marks));
+        break;
+      case 'Emph':
+        out.push(...inlines(asArray(node.c), marks.concat(M.italic.create()), ctx));
+        break;
+      case 'Strong':
+        out.push(...inlines(asArray(node.c), marks.concat(M.bold.create()), ctx));
+        break;
+      case 'Strikeout':
+        out.push(...inlines(asArray(node.c), marks.concat(M.strike.create()), ctx));
+        break;
+      case 'Subscript':
+        out.push(...inlines(asArray(node.c), marks.concat(M.subscript.create()), ctx));
+        break;
+      case 'Superscript':
+        out.push(...inlines(asArray(node.c), marks.concat(M.superscript.create()), ctx));
+        break;
+      case 'Underline':
+      case 'SmallCaps':
+      case 'Quoted':
+        // Outside the v1 mark set -> chip the whole construct verbatim.
+        out.push(chip(node, 'span', ctx, ''));
+        break;
+      case 'Code': {
+        const [, code] = node.c as [unknown, string];
+        out.push(S.text(code, marks.concat(M.code.create())));
+        break;
+      }
+      case 'Link': {
+        const [, label, target] = node.c as [unknown, AstNode[], [string, string]];
+        const link = M.link.create({ href: target[0], title: target[1] || null });
+        out.push(...inlines(label, marks.concat(link), ctx));
+        break;
+      }
+      case 'Math':
+        out.push(chip(node, 'math', ctx, ''));
+        break;
+      case 'Cite':
+        out.push(chip(node, 'cite', ctx, ''));
+        break;
+      case 'RawInline':
+        out.push(chip(node, 'raw', ctx, (node.c as [string, string])?.[1] ?? ''));
+        break;
+      case 'Span': {
+        const attr = (node.c as [unknown])?.[0] as [string, string[], [string, string][]];
+        const classes = attr?.[1] ?? [];
+        const isShortcode = classes.includes('quarto-shortcode__');
+        out.push(chip(node, isShortcode ? 'shortcode' : 'span', ctx, ''));
+        break;
+      }
+      case 'Image':
+      case 'Note':
+        out.push(chip(node, 'raw', ctx, ''));
+        break;
+      default:
+        ctx.unknown.add(`inline:${node.t}`);
+        out.push(chip(node, 'raw', ctx, ''));
+        break;
+    }
+  }
+  return out;
+}
+
+// ---- blocks ----------------------------------------------------------------
+
+function listItems(itemsC: unknown, ctx: Ctx): PMNode[] {
+  const items = (itemsC as AstNode[][]) ?? [];
+  return items.map((itemBlocks) => N.listItem.create(null, blocks(itemBlocks, ctx)));
+}
+
+/** A Pandoc list is tight when its items hold `Plain` (not `Para`) blocks. */
+function isTight(itemsC: unknown): boolean {
+  const items = (itemsC as AstNode[][]) ?? [];
+  return items.every((item) => !item.some((b) => b.t === 'Para'));
+}
+
+function blocks(items: AstNode[], ctx: Ctx): PMNode[] {
+  const out: PMNode[] = [];
+  for (const node of items) {
+    switch (node.t) {
+      case 'Para':
+      case 'Plain':
+        out.push(N.paragraph.create(null, inlines(asArray(node.c), [], ctx)));
+        break;
+      case 'Header': {
+        const [level, , inl] = node.c as [number, unknown, AstNode[]];
+        out.push(N.heading.create({ level }, inlines(inl, [], ctx)));
+        break;
+      }
+      case 'BulletList':
+        out.push(N.bulletList.create({ tight: isTight(node.c) }, listItems(node.c, ctx)));
+        break;
+      case 'OrderedList': {
+        const [attrs, its] = node.c as [[number, unknown, unknown], unknown];
+        out.push(N.orderedList.create({ start: attrs?.[0] ?? 1, tight: isTight(its) }, listItems(its, ctx)));
+        break;
+      }
+      case 'BlockQuote':
+        out.push(N.blockquote.create(null, blocks(asArray(node.c), ctx)));
+        break;
+      case 'CodeBlock': {
+        const [attr, code] = node.c as [[string, string[], [string, string][]], string];
+        const classes = attr?.[1] ?? [];
+        // pampa stores the fence info string as a class verbatim, INCLUDING braces
+        // for executable cells (```{python} -> "{python}"; ```python -> "python").
+        const language = classes.join(' ');
+        out.push(N.codeBlock.create({ language }, code ? [S.text(code)] : []));
+        break;
+      }
+      case 'RawBlock':
+      case 'Div':
+      case 'Table':
+      case 'Figure':
+      case 'DefinitionList':
+        // v1: whole opaque block -> paragraph wrapping a verbatim chip. (Real
+        // integration "reaches into" a Div and edits inner blocks individually;
+        // this whole-block chip is only the bridge's safe fallback.)
+        out.push(N.paragraph.create(null, [chip(node, 'block', ctx, '')]));
+        break;
+      case 'HorizontalRule':
+      case 'Null':
+        break;
+      default:
+        ctx.unknown.add(`block:${node.t}`);
+        out.push(N.paragraph.create(null, [chip(node, 'block', ctx, '')]));
+        break;
+    }
+  }
+  return out;
+}
+
+export interface AstToDocResult {
+  doc: PMNode;
+  unknown: string[];
+}
+
+/** Build a ProseMirror doc from one or more untransformed Pandoc blocks. */
+export function astToDoc(sourceBlocks: AstNode[], pool: PoolEntry[], src: string): AstToDocResult {
+  const ctx: Ctx = { pool, src, unknown: new Set() };
+  const content = blocks(sourceBlocks, ctx);
+  // A doc must contain at least one block; fall back to an empty paragraph.
+  const doc = N.doc.create(null, content.length ? content : [N.paragraph.create()]);
+  return { doc, unknown: [...ctx.unknown] };
+}
diff --git a/ts-packages/preview-renderer/src/q2-preview/richtext/chipExtension.ts b/ts-packages/preview-renderer/src/q2-preview/richtext/chipExtension.ts
new file mode 100644
index 000000000..5c736cf1c
--- /dev/null
+++ b/ts-packages/preview-renderer/src/q2-preview/richtext/chipExtension.ts
@@ -0,0 +1,44 @@
+// Phase 1 (bd-sjb4pzx8) — tiptap node for opaque "chip" atoms.
+//
+// An inline, atomic, non-editable node that renders as a small pill showing its
+// verbatim qmd source and serializes back to that source unchanged (the
+// serializer's `chip` rule emits `node.attrs.src` unescaped). v1 chips are
+// source-text pills (per user decision); a richer NodeView (KaTeX math, resolved
+// crossref) is a deferred option.
+//
+// The node NAME + attrs (`src`, `kind`) match `richtext/schema.ts` so the seed
+// doc (built by `astToDoc` and handed to tiptap as JSON) parses cleanly here.
+
+import { Node, mergeAttributes } from '@tiptap/core';
+
+export const Chip = Node.create({
+  name: 'chip',
+  group: 'inline',
+  inline: true,
+  atom: true,
+  selectable: true,
+  draggable: false,
+
+  addAttributes() {
+    return {
+      src: { default: '' },
+      kind: { default: 'raw' },
+    };
+  },
+
+  parseHTML() {
+    return [{ tag: 'span.q2-chip' }];
+  },
+
+  renderHTML({ HTMLAttributes, node }) {
+    return [
+      'span',
+      mergeAttributes(HTMLAttributes, {
+        class: `q2-chip q2-chip-${node.attrs.kind as string}`,
+        'data-src': node.attrs.src as string,
+        contenteditable: 'false',
+      }),
+      node.attrs.src as string,
+    ];
+  },
+});
diff --git a/ts-packages/preview-renderer/src/q2-preview/richtext/roundtrip.test.ts b/ts-packages/preview-renderer/src/q2-preview/richtext/roundtrip.test.ts
new file mode 100644
index 000000000..914b1ba5b
--- /dev/null
+++ b/ts-packages/preview-renderer/src/q2-preview/richtext/roundtrip.test.ts
@@ -0,0 +1,59 @@
+// Phase 1 (bd-sjb4pzx8) — production round-trip fidelity guard for the rich-text
+// bridge. Mirrors the Phase-0 spike but exercises the REAL production modules
+// (astToDoc + docToMarkdown against the tiptap-named schema):
+//
+//   qmd -> pampa AST -> astToDoc -> docToMarkdown -> pampa AST -> compare
+//
+// Skips when native pampa can't be built (Rust-less CI). Run locally:
+//   cd ts-packages/preview-renderer && npx vitest run src/q2-preview/richtext/
+
+import { describe, it, expect } from 'vitest';
+import { astToDoc } from './astToProseMirror';
+import { docToMarkdown } from './serializer';
+import { parseUntransformed, astEqual, pampaAvailable } from '../../test-utils/pampaOracle';
+
+const FIXTURES: { name: string; qmd: string }[] = [
+  { name: 'plain-para', qmd: 'A simple paragraph of prose.\n' },
+  { name: 'inline-formatting', qmd: 'A para with **bold**, *italic*, `code`, and a [link](https://example.com).\n' },
+  { name: 'nested-emphasis', qmd: 'Text with **_bold italic_** and a [**bold link**](https://x.com).\n' },
+  { name: 'sub-sup-strike', qmd: 'Water H~2~O, exponent 2^10^, and ~~struck~~ text.\n' },
+  { name: 'atx-heading', qmd: '## A second-level heading\n' },
+  { name: 'heading-with-marks', qmd: '### A **bold** heading with `code` and a [link](https://x.com)\n' },
+  { name: 'bullet-list', qmd: '- first item\n- second item\n- third item\n' },
+  { name: 'ordered-list', qmd: '3. three\n4. four\n5. five\n' },
+  { name: 'blockquote', qmd: '> a quoted line\n> still quoted\n' },
+  { name: 'code-block-quarto', qmd: '```{python}\nprint("hi")\n```\n' },
+  { name: 'shortcode', qmd: 'Watch {{< video https://youtu.be/abc >}} now.\n' },
+  { name: 'inline-math', qmd: 'Identity $e^{i\\pi}+1=0$ is neat.\n' },
+  { name: 'crossref', qmd: 'See @fig-plot for details.\n' },
+  { name: 'citation', qmd: 'Established [@knuth1984].\n' },
+  { name: 'raw-html-inline', qmd: 'Text with <span class="x">raw</span> inside.\n' },
+];
+
+// The hard gate is SEMANTIC equivalence — the round-trip must not drop or change
+// nodes. Byte-exact round-tripping is a nice-to-have, not required (cosmetic
+// reformatting like `***x***` -> `**_x_**`, or `-` -> `*` bullets, is acceptable);
+// we log it for visibility but do not fail on it.
+describe.skipIf(!pampaAvailable())('rich-text bridge round-trip', () => {
+  for (const fx of FIXTURES) {
+    it(`preserves semantics: ${fx.name}`, () => {
+      const astIn = parseUntransformed(fx.qmd);
+      const { doc, unknown } = astToDoc(astIn.blocks, astIn.astContext.p, fx.qmd);
+      const mdOut = docToMarkdown(doc);
+      const astOut = parseUntransformed(mdOut);
+
+      const equivalent = astEqual(astIn.blocks, astOut.blocks, { normalize: true });
+      const exact = astEqual(astIn.blocks, astOut.blocks, { normalize: false });
+
+      if (!equivalent) {
+        // eslint-disable-next-line no-console
+        console.error(`\n${fx.name} SEMANTIC BREAK\n--- qmd ---\n${fx.qmd}\n--- md_out ---\n${mdOut}`);
+      } else if (!exact) {
+        // eslint-disable-next-line no-console
+        console.log(`${fx.name}: equivalent (cosmetic reformat)`);
+      }
+      expect(unknown, `${fx.name}: unmapped node types`).toEqual([]);
+      expect(equivalent, `${fx.name}: round-trip changed/dropped a node`).toBe(true);
+    });
+  }
+});
diff --git a/ts-packages/preview-renderer/src/q2-preview/richtext/schema.ts b/ts-packages/preview-renderer/src/q2-preview/richtext/schema.ts
new file mode 100644
index 000000000..75c67f98c
--- /dev/null
+++ b/ts-packages/preview-renderer/src/q2-preview/richtext/schema.ts
@@ -0,0 +1,151 @@
+// Phase 1 (bd-sjb4pzx8) — ProseMirror schema for the rich-text block editor.
+//
+// Node/mark NAMES match tiptap StarterKit v3 (paragraph, heading, bulletList,
+// orderedList, listItem, blockquote, codeBlock, hardBreak, text; marks bold,
+// italic, code, strike, link) plus a custom `chip` inline atom for opaque
+// Quarto constructs (shortcodes, math, @crossref, [@cite], raw inline). Because
+// the names match, one `astToDoc` builder + one markdown serializer serve BOTH
+// this standalone schema (used in round-trip tests) and the live tiptap editor
+// (which is fed `astToDoc(...).toJSON()` and re-parses it against its own,
+// name-identical schema).
+//
+// We import prosemirror-model from `@tiptap/pm/model` so the Node instances this
+// schema produces are the exact same class the tiptap editor uses.
+
+import { Schema, type NodeSpec, type MarkSpec, type DOMOutputSpec } from '@tiptap/pm/model';
+
+export type ChipKind = 'math' | 'cite' | 'shortcode' | 'span' | 'raw' | 'block';
+
+const pDOM: DOMOutputSpec = ['p', 0];
+const blockquoteDOM: DOMOutputSpec = ['blockquote', 0];
+const ulDOM: DOMOutputSpec = ['ul', 0];
+const olDOM: DOMOutputSpec = ['ol', 0];
+const liDOM: DOMOutputSpec = ['li', 0];
+const brDOM: DOMOutputSpec = ['br'];
+const codeDOM: DOMOutputSpec = ['pre', ['code', 0]];
+
+const nodes: Record<string, NodeSpec> = {
+  doc: { content: 'block+' },
+
+  paragraph: {
+    group: 'block',
+    content: 'inline*',
+    parseDOM: [{ tag: 'p' }],
+    toDOM: () => pDOM,
+  },
+
+  heading: {
+    group: 'block',
+    content: 'inline*',
+    attrs: { level: { default: 1 } },
+    defining: true,
+    parseDOM: [1, 2, 3, 4, 5, 6].map((level) => ({ tag: `h${level}`, attrs: { level } })),
+    toDOM: (node) => [`h${node.attrs.level as number}`, 0],
+  },
+
+  blockquote: {
+    group: 'block',
+    content: 'block+',
+    defining: true,
+    parseDOM: [{ tag: 'blockquote' }],
+    toDOM: () => blockquoteDOM,
+  },
+
+  codeBlock: {
+    group: 'block',
+    content: 'text*',
+    marks: '',
+    code: true,
+    defining: true,
+    attrs: { language: { default: '' } },
+    parseDOM: [{ tag: 'pre', preserveWhitespace: 'full' }],
+    toDOM: () => codeDOM,
+  },
+
+  bulletList: {
+    group: 'block',
+    content: 'listItem+',
+    // `tight` drives prosemirror-markdown's renderList: tight (Pandoc Plain items)
+    // emits single-newline items; loose (Para items) emits blank-line-separated.
+    attrs: { tight: { default: true } },
+    parseDOM: [{ tag: 'ul' }],
+    toDOM: () => ulDOM,
+  },
+
+  orderedList: {
+    group: 'block',
+    content: 'listItem+',
+    attrs: { start: { default: 1 }, tight: { default: true } },
+    parseDOM: [{ tag: 'ol' }],
+    toDOM: () => olDOM,
+  },
+
+  listItem: {
+    content: 'block+',
+    defining: true,
+    parseDOM: [{ tag: 'li' }],
+    toDOM: () => liDOM,
+  },
+
+  text: { group: 'inline' },
+
+  hardBreak: {
+    group: 'inline',
+    inline: true,
+    selectable: false,
+    parseDOM: [{ tag: 'br' }],
+    toDOM: () => brDOM,
+  },
+
+  chip: {
+    group: 'inline',
+    inline: true,
+    atom: true,
+    selectable: true,
+    attrs: { src: {}, kind: { default: 'raw' } },
+    parseDOM: [
+      {
+        tag: 'span.q2-chip',
+        getAttrs(dom) {
+          const el = dom as HTMLElement;
+          return {
+            src: el.getAttribute('data-src') ?? '',
+            kind: (el.className.match(/q2-chip-(\w+)/)?.[1] ?? 'raw') as ChipKind,
+          };
+        },
+      },
+    ],
+    toDOM(node) {
+      const { src, kind } = node.attrs as { src: string; kind: ChipKind };
+      return ['span', { class: `q2-chip q2-chip-${kind}`, 'data-src': src, contenteditable: 'false' }, src];
+    },
+  },
+};
+
+const marks: Record<string, MarkSpec> = {
+  bold: { parseDOM: [{ tag: 'strong' }, { tag: 'b' }], toDOM: () => ['strong', 0] },
+  italic: { parseDOM: [{ tag: 'em' }, { tag: 'i' }], toDOM: () => ['em', 0] },
+  strike: { parseDOM: [{ tag: 's' }, { tag: 'del' }], toDOM: () => ['s', 0] },
+  subscript: { parseDOM: [{ tag: 'sub' }], toDOM: () => ['sub', 0] },
+  superscript: { parseDOM: [{ tag: 'sup' }], toDOM: () => ['sup', 0] },
+  code: { parseDOM: [{ tag: 'code' }], toDOM: () => ['code', 0] },
+  link: {
+    attrs: { href: {}, title: { default: null } },
+    inclusive: false,
+    parseDOM: [
+      {
+        tag: 'a[href]',
+        getAttrs(dom) {
+          const el = dom as HTMLElement;
+          return { href: el.getAttribute('href'), title: el.getAttribute('title') };
+        },
+      },
+    ],
+    toDOM(mark) {
+      const { href, title } = mark.attrs as { href: string; title: string | null };
+      return ['a', { href, title }, 0];
+    },
+  },
+};
+
+export const richTextSchema = new Schema({ nodes, marks });
diff --git a/ts-packages/preview-renderer/src/q2-preview/richtext/serializer.ts b/ts-packages/preview-renderer/src/q2-preview/richtext/serializer.ts
new file mode 100644
index 000000000..1b70b361b
--- /dev/null
+++ b/ts-packages/preview-renderer/src/q2-preview/richtext/serializer.ts
@@ -0,0 +1,79 @@
+// Phase 1 (bd-sjb4pzx8) — ProseMirror document -> markdown text.
+//
+// Reuses prosemirror-markdown's validated default rules, re-keyed to tiptap's
+// node/mark NAMES, with custom rules where tiptap's attrs differ from
+// prosemirror-markdown's (codeBlock.language vs code_block.params; orderedList.start
+// vs ordered_list.order) and for the `chip` atom (verbatim, unescaped). The same
+// serializer runs over both the live tiptap editor's doc and the test schema's doc.
+
+import {
+  MarkdownSerializer,
+  MarkdownSerializerState,
+  defaultMarkdownSerializer,
+} from 'prosemirror-markdown';
+import type { Node as PMNode } from '@tiptap/pm/model';
+
+const d = defaultMarkdownSerializer;
+
+type NodeRule = (state: MarkdownSerializerState, node: PMNode, parent: PMNode, index: number) => void;
+
+const nodes: Record<string, NodeRule> = {
+  paragraph: d.nodes.paragraph as NodeRule,
+  heading: d.nodes.heading as NodeRule,
+  blockquote: d.nodes.blockquote as NodeRule,
+  bulletList: d.nodes.bullet_list as NodeRule,
+  listItem: d.nodes.list_item as NodeRule,
+  hardBreak: d.nodes.hard_break as NodeRule,
+  text: d.nodes.text as NodeRule,
+
+  // tiptap codeBlock carries `language`; prosemirror-markdown's code_block reads
+  // `params`. Emit a fence + the language verbatim (handles ```{python} and ```python).
+  codeBlock(state, node) {
+    const language = (node.attrs.language as string) || '';
+    state.write('```' + language + '\n');
+    state.text(node.textContent, false);
+    state.ensureNewLine();
+    state.write('```');
+    state.closeBlock(node);
+  },
+
+  // tiptap orderedList carries `start`; prosemirror-markdown's ordered_list reads
+  // `order`. Replicate the default rule against `start`.
+  orderedList(state, node) {
+    const start = (node.attrs.start as number) || 1;
+    const maxW = String(start + node.childCount - 1).length;
+    const space = state.repeat(' ', maxW + 2);
+    state.renderList(node, space, (i) => {
+      const nStr = String(start + i);
+      return state.repeat(' ', maxW - nStr.length) + nStr + '. ';
+    });
+  },
+
+  // Opaque construct: emit the verbatim source, UNESCAPED (so `{`, `$`, `@`, `<`
+  // survive). The chip round-trips byte-for-byte.
+  chip(state, node) {
+    state.text(node.attrs.src as string, false);
+  },
+};
+
+const marks = {
+  bold: d.marks.strong,
+  // qmd disallows `***` (triple-star). Use `_` for italic so bold+italic
+  // serializes as `**_…_**` (valid) instead of `***…***` (rejected by pampa).
+  // `_` is intraword-safe, so this is the better qmd choice regardless.
+  italic: { open: '_', close: '_', mixable: true, expelEnclosingWhitespace: true },
+  code: d.marks.code,
+  link: d.marks.link,
+  strike: { open: '~~', close: '~~', mixable: true, expelEnclosingWhitespace: true },
+  // qmd subscript `~x~` / superscript `^x^` (Pandoc). Single tilde for subscript
+  // (double `~~` is strikethrough, above).
+  subscript: { open: '~', close: '~', mixable: true, expelEnclosingWhitespace: true },
+  superscript: { open: '^', close: '^', mixable: true, expelEnclosingWhitespace: true },
+};
+
+export const richTextSerializer = new MarkdownSerializer(nodes, marks);
+
+/** Serialize a ProseMirror document to markdown text. */
+export function docToMarkdown(doc: PMNode): string {
+  return richTextSerializer.serialize(doc);
+}
diff --git a/ts-packages/preview-renderer/src/q2-preview/richtext/styles.ts b/ts-packages/preview-renderer/src/q2-preview/richtext/styles.ts
new file mode 100644
index 000000000..fd8d585ed
--- /dev/null
+++ b/ts-packages/preview-renderer/src/q2-preview/richtext/styles.ts
@@ -0,0 +1,151 @@
+// Phase 1a (bd-sjb4pzx8) — one-time CSS for the rich-text editor.
+//
+// Goal: the editor should look like the rendered page. The heavy lifting is done
+// by the theme stylesheet already loaded in the iframe (it styles the editor's
+// <p>/<em>/<strong>/<a> for free). This sheet only (a) strips ProseMirror's
+// default editor chrome so it doesn't fight the theme, (b) zeroes the inner
+// block margin since the measured box already reproduces the block's spacing,
+// and (c) gives chips a subtle, source-token pill look.
+
+let injected = false;
+
+const CSS = `
+/* Left-margin edit affordance: the "Editing…" label + the rich/plain toggle,
+   parked in the margin (absolute, right-aligned against the edit box's left edge)
+   so it never overlaps the text. The label is inert; the toggle buttons are
+   interactive but use mousedown-preventDefault to avoid blurring the editor. */
+.q2-edit-affordance {
+  position: absolute;
+  right: calc(100% + 0.7rem);
+  top: 0;
+  text-align: right;
+  user-select: none;
+}
+.q2-edit-affordance-label {
+  font-size: 0.72rem;
+  line-height: 1.7;
+  font-style: italic;
+  white-space: nowrap;
+  color: rgba(59, 130, 246, 0.7);
+  pointer-events: none;
+}
+.q2-edit-mode-toggle {
+  margin-top: 0.3rem;
+  display: flex;
+  flex-direction: column;
+  align-items: flex-end;
+  gap: 0.1rem;
+}
+.q2-edit-mode-toggle button {
+  appearance: none;
+  border: none;
+  background: none;
+  padding: 0 0.15rem;
+  font-size: 0.66rem;
+  line-height: 1.4;
+  white-space: nowrap;
+  cursor: pointer;
+  color: rgba(100, 116, 139, 0.7);
+  border-right: 2px solid transparent;
+}
+.q2-edit-mode-toggle button:hover { color: rgba(59, 130, 246, 0.9); }
+.q2-edit-mode-toggle button.q2-edit-mode-active {
+  color: rgba(59, 130, 246, 1);
+  font-weight: 600;
+  border-right-color: rgba(59, 130, 246, 0.8);
+}
+
+.q2-richtext-editor { position: relative; }
+
+/* Formatting toolbar — a small box floating just above the top-left of the edit
+   box. Out of flow (absolute) so it never reflows the content; solid background
+   + shadow so it reads over whatever is behind it. */
+.q2-rt-toolbar {
+  position: absolute;
+  bottom: 100%;
+  left: -2px;
+  margin-bottom: 4px;
+  z-index: 20;
+  display: flex;
+  align-items: center;
+  gap: 1px;
+  padding: 2px 3px;
+  background: #fff;
+  border: 1px solid rgba(59, 130, 246, 0.35);
+  border-radius: 5px;
+  box-shadow: 0 2px 6px rgba(0, 0, 0, 0.12);
+  user-select: none;
+  font-size: 0.8rem;
+  line-height: 1;
+}
+.q2-rt-tb-btn {
+  appearance: none;
+  border: none;
+  background: none;
+  border-radius: 3px;
+  min-width: 1.6em;
+  padding: 0.25em 0.4em;
+  font-size: 0.8rem;
+  cursor: pointer;
+  color: #334155;
+}
+.q2-rt-tb-btn:hover { background: rgba(59, 130, 246, 0.12); }
+.q2-rt-tb-active { background: rgba(59, 130, 246, 0.18); color: rgb(37, 99, 235); }
+.q2-rt-tb-bold { font-weight: 700; }
+.q2-rt-tb-italic { font-style: italic; }
+.q2-rt-tb-strike { text-decoration: line-through; }
+.q2-rt-tb-sep { width: 1px; align-self: stretch; margin: 2px 2px; background: rgba(0, 0, 0, 0.12); }
+.q2-rt-link-editor { display: flex; align-items: center; gap: 2px; }
+.q2-rt-link-input {
+  font-size: 0.78rem;
+  padding: 0.15em 0.4em;
+  border: 1px solid rgba(0, 0, 0, 0.2);
+  border-radius: 3px;
+  width: 16rem;
+  max-width: 40vw;
+}
+
+.q2-richtext-editor .ProseMirror {
+  outline: none;
+  white-space: pre-wrap;
+  word-wrap: break-word;
+  /* "Edit mode" affordance: the WYSIWYG render is faithful enough that the user
+     can't otherwise tell editing is live. A subtle tint + ring signals it. The
+     padding is cancelled by an equal negative margin so the text does NOT shift
+     (zero reflow) — only the tinted area extends slightly around the content. */
+  background: rgba(59, 130, 246, 0.08);
+  box-shadow: 0 0 0 2px rgba(59, 130, 246, 0.35);
+  border-radius: 3px;
+  padding: 2px 5px;
+  margin: -2px -5px;
+}
+.q2-richtext-editor .ProseMirror:focus { outline: none; }
+/* The measured edit box reproduces the original block's margin/padding; the
+   editor's own block must not add a second margin. */
+.q2-richtext-editor .ProseMirror > * { margin-top: 0; margin-bottom: 0; }
+
+/* Opaque source-token chips (v1: pills, not rendered). */
+.q2-chip {
+  font-family: var(--bs-font-monospace, ui-monospace, SFMono-Regular, Menlo, monospace);
+  font-size: 0.85em;
+  background: rgba(120, 120, 160, 0.14);
+  border: 1px solid rgba(120, 120, 160, 0.30);
+  border-radius: 3px;
+  padding: 0 0.25em;
+  white-space: nowrap;
+  cursor: default;
+  user-select: all;
+}
+.q2-chip-math { background: rgba(80, 160, 120, 0.14); border-color: rgba(80, 160, 120, 0.30); }
+.q2-chip-cite, .q2-chip-shortcode { background: rgba(160, 120, 80, 0.14); border-color: rgba(160, 120, 80, 0.30); }
+`;
+
+/** Inject the rich-text editor stylesheet into the document head once. */
+export function ensureRichTextStyles(): void {
+  if (injected || typeof document === 'undefined') return;
+  injected = true;
+  const style = document.createElement('style');
+  style.setAttribute('data-q2-richtext', '1');
+  style.textContent = CSS;
+  document.head.appendChild(style);
+}
diff --git a/ts-packages/preview-renderer/src/q2-preview/tiptap-roundtrip-spike/README.md b/ts-packages/preview-renderer/src/q2-preview/tiptap-roundtrip-spike/README.md
new file mode 100644
index 000000000..810010d6c
--- /dev/null
+++ b/ts-packages/preview-renderer/src/q2-preview/tiptap-roundtrip-spike/README.md
@@ -0,0 +1,45 @@
+# tiptap round-trip spike (THROWAWAY)
+
+Strand **bd-sjb4pzx8** · plan
+`claude-notes/plans/2026-06-23-tiptap-rich-text-block-editor.md`.
+
+**This is a throwaway feasibility spike, not production code.** It answers one
+question: *can we faithfully round-trip prose-rich + Quarto-opaque qmd through a
+ProseMirror document?* Verdict: **yes** (15/16 exact, 1 benign reformat, 0
+broken). Quarantine or delete before any non-experimental merge.
+
+## What it does
+
+```
+qmd → pampa (untransformed, source-tracked AST) → astToPm → ProseMirror doc
+    → prosemirror-markdown serialize → md_out → pampa → AST → compare (semantic)
+```
+
+Opaque constructs (shortcodes, math, `@crossref`, `[@cite]`, raw inline, and —
+for the spike only — whole `Div`/`RawBlock`/`Table` blocks) become atomic
+**chip** nodes that re-emit their exact source bytes.
+
+Note: the spike is **headless ProseMirror** (`prosemirror-model` +
+`prosemirror-markdown`). tiptap itself is the React editing UI on top; it is
+*not* exercised here. The round-trip fidelity question lives in the model +
+serializer, which is what this measures.
+
+## Run
+
+```bash
+cd ts-packages/preview-renderer
+npx vitest run src/q2-preview/tiptap-roundtrip-spike/
+```
+
+Oracle = the native `pampa` binary (built on first run); no WASM init needed.
+Results (per-fixture `qmd → md_out`) are written to `RESULTS.md`.
+
+## Files
+
+- `fixtures.ts` — the qmd corpus
+- `pampa.ts` — native-pampa oracle + byte-slice helpers
+- `schema.ts` — PM schema = markdown schema + `chip` node
+- `astToPm.ts` — Pandoc AST → PM doc (chip detection by typed-AST walk)
+- `pmToMarkdown.ts` — PM doc → markdown (stock serializer + chip rule)
+- `canonical.ts` — source-stripping / whitespace-normalizing comparator
+- `roundtrip.test.ts` — the oracle + findings table + `RESULTS.md` writer
diff --git a/ts-packages/preview-renderer/src/q2-preview/tiptap-roundtrip-spike/RESULTS.md b/ts-packages/preview-renderer/src/q2-preview/tiptap-roundtrip-spike/RESULTS.md
new file mode 100644
index 000000000..d422d53ef
--- /dev/null
+++ b/ts-packages/preview-renderer/src/q2-preview/tiptap-roundtrip-spike/RESULTS.md
@@ -0,0 +1,146 @@
+# tiptap round-trip spike — results
+
+<!-- GENERATED by roundtrip.test.ts (bd-sjb4pzx8). Throwaway spike evidence. -->
+
+Verdicts: exact=15, equivalent=1, broken=0
+
+## plain-para — `exact`
+
+```` qmd in ````
+A simple paragraph of prose with nothing special in it.
+```` md out (PM → markdown) ````
+A simple paragraph of prose with nothing special in it.
+
+## para-inline-formatting — `exact`
+
+```` qmd in ````
+A paragraph with **bold**, *italic*, `inline code`, and a [link](https://example.com).
+```` md out (PM → markdown) ````
+A paragraph with **bold**, *italic*, `inline code`, and a [link](https://example.com).
+
+## atx-heading — `exact`
+
+```` qmd in ````
+## A second-level heading
+```` md out (PM → markdown) ````
+## A second-level heading
+
+## bullet-list — `exact`
+
+```` qmd in ````
+- first item
+- second item
+- third item
+```` md out (PM → markdown) ````
+* first item
+* second item
+* third item
+
+## ordered-list — `exact`
+
+```` qmd in ````
+1. alpha
+2. beta
+3. gamma
+```` md out (PM → markdown) ````
+1. alpha
+2. beta
+3. gamma
+
+## nested-list — `exact`
+
+```` qmd in ````
+- top
+    - nested a
+    - nested b
+- back to top
+```` md out (PM → markdown) ````
+* top
+  * nested a
+  * nested b
+* back to top
+
+## blockquote — `equivalent`
+
+```` qmd in ````
+> a quoted line
+> continued on the next line
+```` md out (PM → markdown) ````
+> a quoted line continued on the next line
+
+## code-block-plain — `exact`
+
+```` qmd in ````
+```
+plain code
+no language
+```
+```` md out (PM → markdown) ````
+```
+plain code
+no language
+```
+
+## code-block-quarto — `exact`
+
+```` qmd in ````
+```{python}
+print("hi")
+```
+```` md out (PM → markdown) ````
+```{python}
+print("hi")
+```
+
+## shortcode — `exact` (1 chip)
+
+```` qmd in ````
+Watch this: {{< video https://youtu.be/abc >}} for details.
+```` md out (PM → markdown) ````
+Watch this: {{< video https://youtu.be/abc >}} for details.
+
+## inline-math — `exact` (1 chip)
+
+```` qmd in ````
+The famous identity $e^{i\pi} + 1 = 0$ is elegant.
+```` md out (PM → markdown) ````
+The famous identity $e^{i\pi} + 1 = 0$ is elegant.
+
+## display-math — `exact` (1 chip)
+
+```` qmd in ````
+$$\int_0^1 x^2 \, dx = \frac{1}{3}$$
+```` md out (PM → markdown) ````
+$$\int_0^1 x^2 \, dx = \frac{1}{3}$$
+
+## crossref — `exact` (1 chip)
+
+```` qmd in ````
+As shown in @fig-plot, the trend is clear.
+```` md out (PM → markdown) ````
+As shown in @fig-plot, the trend is clear.
+
+## citation — `exact` (1 chip)
+
+```` qmd in ````
+This is well established [@knuth1984].
+```` md out (PM → markdown) ````
+This is well established [@knuth1984].
+
+## callout-div — `exact` (1 chip)
+
+```` qmd in ````
+::: {.callout-note}
+This is a note.
+:::
+```` md out (PM → markdown) ````
+::: {.callout-note}
+This is a note.
+:::
+
+## raw-html-inline — `exact` (2 chips)
+
+```` qmd in ````
+Some text with <span class="x">raw html</span> inside.
+```` md out (PM → markdown) ````
+Some text with <span class="x">raw html</span> inside.
diff --git a/ts-packages/preview-renderer/src/q2-preview/tiptap-roundtrip-spike/astToPm.ts b/ts-packages/preview-renderer/src/q2-preview/tiptap-roundtrip-spike/astToPm.ts
new file mode 100644
index 000000000..51371a878
--- /dev/null
+++ b/ts-packages/preview-renderer/src/q2-preview/tiptap-roundtrip-spike/astToPm.ts
@@ -0,0 +1,186 @@
+// THROWAWAY SPIKE (bd-sjb4pzx8) — Pandoc untransformed AST -> ProseMirror doc.
+// The "input/seed" bridge: we build the PM doc from the typed AST we already have
+// (NOT by re-lexing markdown with markdown-it), and lift opaque node types
+// (Math/Cite/Span.shortcode/RawInline/RawBlock/Div) into verbatim chips by slicing
+// source via their byte ranges. Safe to delete.
+
+import type { Mark, Node as PMNode } from 'prosemirror-model';
+import { schema, type ChipKind } from './schema';
+import { type AstNode, type PoolEntry, nodeSource } from './pampa';
+
+interface Ctx {
+  pool: PoolEntry[];
+  src: string;
+  /** constructs that fell back to a chip, for the findings report */
+  chips: { kind: ChipKind; src: string }[];
+  /** node types we did not know how to map (gaps to report) */
+  unknown: Set<string>;
+}
+
+const m = schema.marks;
+const n = schema.nodes;
+
+function chip(node: AstNode, kind: ChipKind, ctx: Ctx, fallbackText: string): PMNode {
+  const src = nodeSource(node, ctx.pool, ctx.src) ?? fallbackText;
+  ctx.chips.push({ kind, src });
+  return n.chip.create({ src, kind });
+}
+
+function asArray(c: unknown): AstNode[] {
+  return Array.isArray(c) ? (c as AstNode[]) : [];
+}
+
+// ---- inlines ---------------------------------------------------------------
+
+function inlines(items: AstNode[], marks: readonly Mark[], ctx: Ctx): PMNode[] {
+  const out: PMNode[] = [];
+  for (const node of items) {
+    switch (node.t) {
+      case 'Str':
+        out.push(schema.text(node.c as string, marks));
+        break;
+      case 'Space':
+      case 'SoftBreak':
+        // SoftBreak collapses to a space (reformatted-but-equivalent; noted in oracle).
+        out.push(schema.text(' ', marks));
+        break;
+      case 'LineBreak':
+        out.push(n.hard_break.create(undefined, undefined, marks));
+        break;
+      case 'Emph':
+        out.push(...inlines(asArray(node.c), marks.concat(m.em.create()), ctx));
+        break;
+      case 'Strong':
+        out.push(...inlines(asArray(node.c), marks.concat(m.strong.create()), ctx));
+        break;
+      case 'Underline':
+      case 'Strikeout':
+      case 'Superscript':
+      case 'Subscript':
+      case 'SmallCaps':
+      case 'Quoted':
+        // Not in the prose-rich v1 mark set -> chip the whole construct verbatim.
+        out.push(chip(node, 'span', ctx, ''));
+        break;
+      case 'Code': {
+        const [, code] = node.c as [unknown, string];
+        out.push(schema.text(code, marks.concat(m.code.create())));
+        break;
+      }
+      case 'Link': {
+        const [, label, target] = node.c as [unknown, AstNode[], [string, string]];
+        const link = m.link.create({ href: target[0], title: target[1] || null });
+        out.push(...inlines(label, marks.concat(link), ctx));
+        break;
+      }
+      case 'Math':
+        out.push(chip(node, 'math', ctx, ''));
+        break;
+      case 'Cite':
+        out.push(chip(node, 'cite', ctx, ''));
+        break;
+      case 'RawInline':
+        out.push(chip(node, 'raw', ctx, (node.c as [string, string])?.[1] ?? ''));
+        break;
+      case 'Span': {
+        const attr = (node.c as [AstNode] )?.[0] as unknown as [string, string[], [string, string][]];
+        const classes = attr?.[1] ?? [];
+        const isShortcode = classes.includes('quarto-shortcode__');
+        out.push(chip(node, isShortcode ? 'shortcode' : 'span', ctx, ''));
+        break;
+      }
+      case 'Image':
+        // Treat as opaque for v1 (attrs/alt fidelity is out of scope for the spike).
+        out.push(chip(node, 'raw', ctx, ''));
+        break;
+      case 'Note':
+        out.push(chip(node, 'raw', ctx, ''));
+        break;
+      default:
+        ctx.unknown.add(`inline:${node.t}`);
+        out.push(chip(node, 'raw', ctx, ''));
+        break;
+    }
+  }
+  return out;
+}
+
+// ---- blocks ----------------------------------------------------------------
+
+function listItems(itemsC: unknown, ctx: Ctx): PMNode[] {
+  // BulletList: Block[][]; each item is Block[].
+  const items = (itemsC as AstNode[][]) ?? [];
+  return items.map((itemBlocks) => n.list_item.create(null, blocks(itemBlocks, ctx)));
+}
+
+function blocks(items: AstNode[], ctx: Ctx): PMNode[] {
+  const out: PMNode[] = [];
+  for (const node of items) {
+    switch (node.t) {
+      case 'Para':
+      case 'Plain':
+        out.push(n.paragraph.create(null, inlines(asArray(node.c), [], ctx)));
+        break;
+      case 'Header': {
+        const [level, , inl] = node.c as [number, unknown, AstNode[]];
+        out.push(n.heading.create({ level }, inlines(inl, [], ctx)));
+        break;
+      }
+      case 'BulletList':
+        out.push(n.bullet_list.create({ tight: true }, listItems(node.c, ctx)));
+        break;
+      case 'OrderedList': {
+        const [attrs, its] = node.c as [[number, unknown, unknown], unknown];
+        out.push(n.ordered_list.create({ order: attrs?.[0] ?? 1, tight: true }, listItems(its, ctx)));
+        break;
+      }
+      case 'BlockQuote':
+        out.push(n.blockquote.create(null, blocks(asArray(node.c), ctx)));
+        break;
+      case 'CodeBlock': {
+        const [attr, code] = node.c as [[string, string[], [string, string][]], string];
+        const classes = attr?.[1] ?? [];
+        // pampa stores the fence info string as a class verbatim, INCLUDING braces
+        // for Quarto executable cells (```{python} -> class "{python}"; ```python ->
+        // class "python"). So the round-trip is just: params = classes joined.
+        // prosemirror-markdown's code_block emits ```${params}\n...code...\n```.
+        // (id / key-value attrs on a code block are out of scope for the spike.)
+        const params = classes.join(' ');
+        out.push(n.code_block.create({ params }, code ? [schema.text(code)] : []));
+        break;
+      }
+      case 'HorizontalRule':
+        out.push(n.horizontal_rule.create());
+        break;
+      case 'RawBlock':
+      case 'Div':
+      case 'Table':
+      case 'Figure':
+      case 'DefinitionList': {
+        // v1: opaque block -> paragraph wrapping a verbatim chip. (In real integration
+        // we "reach into" a Div instead of chipping it; see plan refinement 2.)
+        out.push(n.paragraph.create(null, [chip(node, 'block', ctx, '')]));
+        break;
+      }
+      case 'Null':
+        break;
+      default:
+        ctx.unknown.add(`block:${node.t}`);
+        out.push(n.paragraph.create(null, [chip(node, 'block', ctx, '')]));
+        break;
+    }
+  }
+  return out;
+}
+
+export interface AstToPmResult {
+  doc: PMNode;
+  chips: { kind: ChipKind; src: string }[];
+  unknown: string[];
+}
+
+export function astToPm(ast: { blocks: AstNode[]; astContext: { p: PoolEntry[] } }, src: string): AstToPmResult {
+  const ctx: Ctx = { pool: ast.astContext.p, src, chips: [], unknown: new Set() };
+  const doc = n.doc.create(null, blocks(ast.blocks, ctx));
+  return { doc, chips: ctx.chips, unknown: [...ctx.unknown] };
+}
diff --git a/ts-packages/preview-renderer/src/q2-preview/tiptap-roundtrip-spike/canonical.ts b/ts-packages/preview-renderer/src/q2-preview/tiptap-roundtrip-spike/canonical.ts
new file mode 100644
index 000000000..36caa9a15
--- /dev/null
+++ b/ts-packages/preview-renderer/src/q2-preview/tiptap-roundtrip-spike/canonical.ts
@@ -0,0 +1,91 @@
+// THROWAWAY SPIKE (bd-sjb4pzx8) — canonicalize a Pandoc AST for semantic comparison.
+// The round-trip bar is "re-parses to the same AST", not byte-identity, so we strip
+// source info and (optionally) normalize whitespace the way the writer legitimately may.
+// Safe to delete.
+
+import type { AstNode } from './pampa';
+
+// Source-tracking / volatile fields that must not affect equivalence.
+const STRIP_KEYS = new Set(['s', 'a', 'l', 'targetS']);
+const VOLATILE_CITE_KEYS = new Set(['citationHash', 'citationNoteNum', 'citationIdS']);
+
+function stripObj(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(stripObj);
+  if (value && typeof value === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      if (STRIP_KEYS.has(k) || VOLATILE_CITE_KEYS.has(k)) continue;
+      out[k] = stripObj(v);
+    }
+    return out;
+  }
+  return value;
+}
+
+/** Merge Space/SoftBreak into spaces and coalesce adjacent Str runs, recursively. */
+function normalizeInlines(items: AstNode[]): AstNode[] {
+  const spaced = items.map((node) => {
+    if (node.t === 'Space' || node.t === 'SoftBreak') return { t: 'Str', c: ' ' } as AstNode;
+    if (Array.isArray(node.c)) {
+      // Recurse into inline containers (Emph/Strong/Link label/etc.).
+      const c = node.c as unknown[];
+      const looksInlineList = c.length > 0 && c.every((x) => x && typeof x === 'object' && 't' in (x as object));
+      if (looksInlineList) return { ...node, c: normalizeInlines(c as AstNode[]) };
+      // Link: c = [attr, inlines, target]
+      if (node.t === 'Link' || node.t === 'Image') {
+        const [attr, label, target] = node.c as [unknown, AstNode[], unknown];
+        return { ...node, c: [attr, normalizeInlines(label), target] };
+      }
+    }
+    return node;
+  });
+  // Coalesce adjacent Str.
+  const merged: AstNode[] = [];
+  for (const node of spaced) {
+    const last = merged[merged.length - 1];
+    if (node.t === 'Str' && last && last.t === 'Str') {
+      last.c = (last.c as string) + (node.c as string);
+    } else {
+      merged.push({ ...node });
+    }
+  }
+  // Collapse runs of spaces inside Str and trim the list edges.
+  for (const node of merged) {
+    if (node.t === 'Str') node.c = (node.c as string).replace(/\s+/g, ' ');
+  }
+  return merged;
+}
+
+function normalizeBlocks(items: AstNode[]): AstNode[] {
+  return items.map((node) => {
+    const out = { ...node };
+    if ((node.t === 'Para' || node.t === 'Plain' || node.t === 'Header') && Array.isArray(node.c)) {
+      if (node.t === 'Header') {
+        const [lvl, attr, inl] = node.c as [number, unknown, AstNode[]];
+        out.c = [lvl, attr, normalizeInlines(inl)];
+      } else {
+        out.c = normalizeInlines(node.c as AstNode[]);
+      }
+    } else if (node.t === 'BlockQuote' || node.t === 'Div' || node.t === 'Figure') {
+      const inner = node.t === 'Div' ? (node.c as [unknown, AstNode[]])[1] : (node.c as AstNode[]);
+      const norm = normalizeBlocks(inner);
+      out.c = node.t === 'Div' ? [(node.c as [unknown, AstNode[]])[0], norm] : norm;
+    } else if (node.t === 'BulletList') {
+      out.c = (node.c as AstNode[][]).map(normalizeBlocks);
+    } else if (node.t === 'OrderedList') {
+      const [attrs, its] = node.c as [unknown, AstNode[][]];
+      out.c = [attrs, its.map(normalizeBlocks)];
+    }
+    return out;
+  });
+}
+
+/** Canonical, comparable form of a document's blocks. */
+export function canonical(blocks: AstNode[], opts: { normalize: boolean }): unknown {
+  const stripped = stripObj(blocks) as AstNode[];
+  return opts.normalize ? normalizeBlocks(stripped) : stripped;
+}
+
+export function deepEqual(a: unknown, b: unknown): boolean {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
diff --git a/ts-packages/preview-renderer/src/q2-preview/tiptap-roundtrip-spike/fixtures.ts b/ts-packages/preview-renderer/src/q2-preview/tiptap-roundtrip-spike/fixtures.ts
new file mode 100644
index 000000000..8d5b428c7
--- /dev/null
+++ b/ts-packages/preview-renderer/src/q2-preview/tiptap-roundtrip-spike/fixtures.ts
@@ -0,0 +1,87 @@
+// THROWAWAY SPIKE (bd-sjb4pzx8) — qmd corpus for the markdown round-trip feasibility test.
+// See claude-notes/plans/2026-06-23-tiptap-rich-text-block-editor.md. Safe to delete.
+
+export interface Fixture {
+  name: string;
+  qmd: string;
+  // Constructs we expect to require an opaque "chip" (verbatim passthrough).
+  expectChips?: boolean;
+  notes?: string;
+}
+
+export const FIXTURES: Fixture[] = [
+  {
+    name: 'plain-para',
+    qmd: 'A simple paragraph of prose with nothing special in it.\n',
+  },
+  {
+    name: 'para-inline-formatting',
+    qmd: 'A paragraph with **bold**, *italic*, `inline code`, and a [link](https://example.com).\n',
+  },
+  {
+    name: 'atx-heading',
+    qmd: '## A second-level heading\n',
+  },
+  {
+    name: 'bullet-list',
+    qmd: '- first item\n- second item\n- third item\n',
+  },
+  {
+    name: 'ordered-list',
+    qmd: '1. alpha\n2. beta\n3. gamma\n',
+  },
+  {
+    name: 'nested-list',
+    qmd: '- top\n    - nested a\n    - nested b\n- back to top\n',
+  },
+  {
+    name: 'blockquote',
+    qmd: '> a quoted line\n> continued on the next line\n',
+  },
+  {
+    name: 'code-block-plain',
+    qmd: '```\nplain code\nno language\n```\n',
+  },
+  {
+    name: 'code-block-quarto',
+    qmd: '```{python}\nprint("hi")\n```\n',
+    expectChips: false,
+    notes: 'Quarto executable cell: the `{python}` info string must survive.',
+  },
+  {
+    name: 'shortcode',
+    qmd: 'Watch this: {{< video https://youtu.be/abc >}} for details.\n',
+    expectChips: true,
+  },
+  {
+    name: 'inline-math',
+    qmd: 'The famous identity $e^{i\\pi} + 1 = 0$ is elegant.\n',
+    expectChips: true,
+  },
+  {
+    name: 'display-math',
+    qmd: '$$\\int_0^1 x^2 \\, dx = \\frac{1}{3}$$\n',
+    expectChips: true,
+  },
+  {
+    name: 'crossref',
+    qmd: 'As shown in @fig-plot, the trend is clear.\n',
+    expectChips: true,
+  },
+  {
+    name: 'citation',
+    qmd: 'This is well established [@knuth1984].\n',
+    expectChips: true,
+  },
+  {
+    name: 'callout-div',
+    qmd: '::: {.callout-note}\nThis is a note.\n:::\n',
+    expectChips: true,
+    notes: 'In real integration we reach INTO the div; here we test whole-slice round-trip.',
+  },
+  {
+    name: 'raw-html-inline',
+    qmd: 'Some text with <span class="x">raw html</span> inside.\n',
+    expectChips: true,
+  },
+];
diff --git a/ts-packages/preview-renderer/src/q2-preview/tiptap-roundtrip-spike/pampa.ts b/ts-packages/preview-renderer/src/q2-preview/tiptap-roundtrip-spike/pampa.ts
new file mode 100644
index 000000000..705e44e20
--- /dev/null
+++ b/ts-packages/preview-renderer/src/q2-preview/tiptap-roundtrip-spike/pampa.ts
@@ -0,0 +1,86 @@
+// THROWAWAY SPIKE (bd-sjb4pzx8) — native-pampa oracle + AST helpers.
+// Shells out to the native `pampa` binary to get the source-tracked, untransformed
+// Pandoc AST (the same shape the iframe receives via WASM `parse_qmd_content`).
+// No WASM init needed. Safe to delete.
+
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = fileURLToPath(new URL('.', import.meta.url));
+// .../ts-packages/preview-renderer/src/q2-preview/tiptap-roundtrip-spike/ -> repo root
+export const REPO_ROOT = resolve(HERE, '../../../../..');
+
+/** A source-info pool entry: byte range [start,end), target id, depth. */
+export interface PoolEntry {
+  r: [number, number];
+  t: number;
+  d: unknown;
+}
+
+export interface RustQmdJson {
+  'pandoc-api-version': [number, number, number];
+  meta: Record<string, unknown>;
+  blocks: AstNode[];
+  astContext: { p: PoolEntry[]; files: unknown[] };
+}
+
+/** Loose Pandoc AST node (annotated): `t` tag, `c` content, `s` pool index, etc. */
+export interface AstNode {
+  t: string;
+  c?: unknown;
+  s?: number;
+  a?: unknown;
+  l?: unknown;
+  targetS?: unknown;
+  [k: string]: unknown;
+}
+
+let cachedBinary: string | null = null;
+
+function pampaBinary(): string {
+  if (cachedBinary) return cachedBinary;
+  // Build once (fast no-op if already built), then call the binary directly so
+  // each fixture parse doesn't pay cargo's per-invocation overhead.
+  execFileSync('cargo', ['build', '--quiet', '--bin', 'pampa'], {
+    cwd: REPO_ROOT,
+    stdio: ['ignore', 'inherit', 'inherit'],
+  });
+  cachedBinary = join(REPO_ROOT, 'target', 'debug', 'pampa');
+  return cachedBinary;
+}
+
+/** Parse qmd text into the source-tracked, untransformed Pandoc AST. */
+export function parseUntransformed(qmd: string): RustQmdJson {
+  const bin = pampaBinary();
+  const dir = mkdtempSync(join(tmpdir(), 'pampa-spike-'));
+  try {
+    const f = join(dir, 'in.qmd');
+    writeFileSync(f, qmd, 'utf8');
+    const out = execFileSync(
+      bin,
+      ['-t', 'json', '--json-source-location', 'full', f],
+      { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 },
+    );
+    return JSON.parse(out) as RustQmdJson;
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/** Slice the original source by UTF-8 byte offsets (matches pampa's range space). */
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+export function sliceBytes(src: string, start: number, end: number): string {
+  return decoder.decode(encoder.encode(src).subarray(start, end));
+}
+
+/** Verbatim source text for a node, via its pool entry. Null if no source range. */
+export function nodeSource(node: AstNode, pool: PoolEntry[], src: string): string | null {
+  if (node.s == null) return null;
+  const entry = pool[node.s];
+  if (!entry) return null;
+  return sliceBytes(src, entry.r[0], entry.r[1]);
+}
diff --git a/ts-packages/preview-renderer/src/q2-preview/tiptap-roundtrip-spike/pmToMarkdown.ts b/ts-packages/preview-renderer/src/q2-preview/tiptap-roundtrip-spike/pmToMarkdown.ts
new file mode 100644
index 000000000..7931e24a9
--- /dev/null
+++ b/ts-packages/preview-renderer/src/q2-preview/tiptap-roundtrip-spike/pmToMarkdown.ts
@@ -0,0 +1,22 @@
+// THROWAWAY SPIKE (bd-sjb4pzx8) — ProseMirror doc -> markdown text.
+// Reuses prosemirror-markdown's default serializer rules and adds a `chip` rule that
+// emits the verbatim source UNESCAPED (so shortcodes/math/cites survive byte-exact).
+// This is the C1 "serializer fidelity" probe. Safe to delete.
+
+import { MarkdownSerializer, defaultMarkdownSerializer } from 'prosemirror-markdown';
+import type { Node as PMNode } from 'prosemirror-model';
+
+export const serializer = new MarkdownSerializer(
+  {
+    ...defaultMarkdownSerializer.nodes,
+    chip(state: { text: (s: string, escape?: boolean) => void }, node: PMNode) {
+      // escape=false: do NOT markdown-escape `{`, `$`, `@`, `<`, etc.
+      state.text(node.attrs.src as string, false);
+    },
+  },
+  defaultMarkdownSerializer.marks,
+);
+
+export function pmToMarkdown(doc: PMNode): string {
+  return serializer.serialize(doc);
+}
diff --git a/ts-packages/preview-renderer/src/q2-preview/tiptap-roundtrip-spike/roundtrip.test.ts b/ts-packages/preview-renderer/src/q2-preview/tiptap-roundtrip-spike/roundtrip.test.ts
new file mode 100644
index 000000000..8cd8a9c4b
--- /dev/null
+++ b/ts-packages/preview-renderer/src/q2-preview/tiptap-roundtrip-spike/roundtrip.test.ts
@@ -0,0 +1,108 @@
+// THROWAWAY SPIKE (bd-sjb4pzx8) — the round-trip feasibility oracle.
+//   qmd -> pampa(untransformed AST) -> astToPm -> serialize -> pampa -> compare
+// Bucket each fixture: exact / equivalent (reformatted) / broken. Prints a findings
+// table. See claude-notes/plans/2026-06-23-tiptap-rich-text-block-editor.md.
+//
+// Run: npx vitest run src/q2-preview/tiptap-roundtrip-spike/roundtrip.test.ts
+// (from ts-packages/preview-renderer). Requires a buildable native `pampa`.
+
+import { writeFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, it, expect } from 'vitest';
+import { FIXTURES } from './fixtures';
+import { parseUntransformed } from './pampa';
+import { astToPm } from './astToPm';
+import { pmToMarkdown } from './pmToMarkdown';
+import { canonical, deepEqual } from './canonical';
+
+type Verdict = 'exact' | 'equivalent' | 'broken';
+
+interface Row {
+  name: string;
+  verdict: Verdict;
+  chips: number;
+  unknown: string[];
+  mdOut: string;
+}
+
+function roundtrip(qmd: string): { row: Omit<Row, 'name'>; } {
+  const astIn = parseUntransformed(qmd);
+  const { doc, chips, unknown } = astToPm(astIn, qmd);
+  const mdOut = pmToMarkdown(doc);
+  const astOut = parseUntransformed(mdOut);
+
+  const exact = deepEqual(
+    canonical(astIn.blocks, { normalize: false }),
+    canonical(astOut.blocks, { normalize: false }),
+  );
+  const equivalent = deepEqual(
+    canonical(astIn.blocks, { normalize: true }),
+    canonical(astOut.blocks, { normalize: true }),
+  );
+  const verdict: Verdict = exact ? 'exact' : equivalent ? 'equivalent' : 'broken';
+  return { row: { verdict, chips: chips.length, unknown, mdOut } };
+}
+
+describe('tiptap markdown round-trip spike', () => {
+  const rows: Row[] = [];
+
+  for (const fx of FIXTURES) {
+    it(`round-trips: ${fx.name}`, () => {
+      const { row } = roundtrip(fx.qmd);
+      rows.push({ name: fx.name, ...row });
+      // The spike's purpose is measurement, not a hard gate; we only fail on `broken`
+      // so the suite surfaces real regressions while still printing the full table.
+      if (row.verdict === 'broken') {
+        // eslint-disable-next-line no-console
+        console.error(`\nBROKEN: ${fx.name}\n--- qmd ---\n${fx.qmd}\n--- md_out ---\n${row.mdOut}`);
+      }
+      expect(row.verdict, `${fx.name}: ${row.unknown.join(',')}`).not.toBe('broken');
+    });
+  }
+
+  it('ZZ prints findings table', () => {
+    const pad = (s: string, n: number) => s.padEnd(n);
+    const lines = [
+      '',
+      '=== tiptap round-trip spike — findings ===',
+      `${pad('fixture', 24)} ${pad('verdict', 12)} ${pad('chips', 6)} unknown`,
+      '-'.repeat(70),
+      ...rows.map(
+        (r) => `${pad(r.name, 24)} ${pad(r.verdict, 12)} ${pad(String(r.chips), 6)} ${r.unknown.join(',')}`,
+      ),
+      '-'.repeat(70),
+      `exact:      ${rows.filter((r) => r.verdict === 'exact').length}`,
+      `equivalent: ${rows.filter((r) => r.verdict === 'equivalent').length}`,
+      `broken:     ${rows.filter((r) => r.verdict === 'broken').length}`,
+      '',
+    ];
+    // eslint-disable-next-line no-console
+    console.log(lines.join('\n'));
+
+    // Durable evidence artifact: per-fixture qmd -> md_out + verdict.
+    const report = [
+      '# tiptap round-trip spike — results',
+      '',
+      '<!-- GENERATED by roundtrip.test.ts (bd-sjb4pzx8). Throwaway spike evidence. -->',
+      '',
+      `Verdicts: exact=${rows.filter((r) => r.verdict === 'exact').length}, ` +
+        `equivalent=${rows.filter((r) => r.verdict === 'equivalent').length}, ` +
+        `broken=${rows.filter((r) => r.verdict === 'broken').length}`,
+      '',
+      ...rows.flatMap((r) => {
+        const fx = FIXTURES.find((f) => f.name === r.name)!;
+        return [
+          `## ${r.name} — \`${r.verdict}\`${r.chips ? ` (${r.chips} chip${r.chips > 1 ? 's' : ''})` : ''}`,
+          '',
+          '```` qmd in ````',
+          fx.qmd.replace(/\n$/, ''),
+          '```` md out (PM → markdown) ````',
+          r.mdOut.replace(/\n$/, ''),
+          '',
+        ];
+      }),
+    ];
+    const out = fileURLToPath(new URL('./RESULTS.md', import.meta.url));
+    writeFileSync(out, report.join('\n'), 'utf8');
+  });
+});
diff --git a/ts-packages/preview-renderer/src/q2-preview/tiptap-roundtrip-spike/schema.ts b/ts-packages/preview-renderer/src/q2-preview/tiptap-roundtrip-spike/schema.ts
new file mode 100644
index 000000000..1f531b4d3
--- /dev/null
+++ b/ts-packages/preview-renderer/src/q2-preview/tiptap-roundtrip-spike/schema.ts
@@ -0,0 +1,43 @@
+// THROWAWAY SPIKE (bd-sjb4pzx8) — ProseMirror schema = prosemirror-markdown's schema
+// plus an atomic inline `chip` node carrying verbatim qmd source for opaque constructs.
+// (tiptap is a wrapper over ProseMirror; the round-trip fidelity question lives here,
+//  in the model + serializer, not in the React editing UI.) Safe to delete.
+
+import { schema as mdSchema } from 'prosemirror-markdown';
+import { Schema, type NodeSpec } from 'prosemirror-model';
+
+export type ChipKind = 'math' | 'cite' | 'shortcode' | 'span' | 'raw' | 'block';
+
+// Inline atom: renders as a non-editable pill in the editor; serializes back to its
+// exact source bytes. This is posit-assistant's "mention" pattern, generalized.
+const chipSpec: NodeSpec = {
+  inline: true,
+  atom: true,
+  group: 'inline',
+  selectable: true,
+  attrs: {
+    src: {}, // verbatim qmd source token, e.g. "{{< video x >}}" / "$x^2$" / "@fig-1"
+    kind: { default: 'raw' },
+  },
+  toDOM(node) {
+    const { src, kind } = node.attrs as { src: string; kind: ChipKind };
+    return ['span', { class: `q2-chip q2-chip-${kind}`, 'data-src': src, contenteditable: 'false' }, src];
+  },
+  parseDOM: [
+    {
+      tag: 'span.q2-chip',
+      getAttrs(dom) {
+        const el = dom as HTMLElement;
+        return {
+          src: el.getAttribute('data-src') ?? '',
+          kind: (el.className.match(/q2-chip-(\w+)/)?.[1] ?? 'raw') as ChipKind,
+        };
+      },
+    },
+  ],
+};
+
+export const schema = new Schema({
+  nodes: mdSchema.spec.nodes.addToEnd('chip', chipSpec),
+  marks: mdSchema.spec.marks,
+});
diff --git a/ts-packages/preview-renderer/src/test-utils/pampaOracle.ts b/ts-packages/preview-renderer/src/test-utils/pampaOracle.ts
new file mode 100644
index 000000000..080152459
--- /dev/null
+++ b/ts-packages/preview-renderer/src/test-utils/pampaOracle.ts
@@ -0,0 +1,201 @@
+// Test-only oracle (bd-sjb4pzx8): parse qmd into the source-tracked untransformed
+// Pandoc AST via the native `pampa` binary, and compare two ASTs semantically
+// (source-info-stripped, optionally whitespace-normalized). Used by rich-text
+// round-trip fidelity tests. Skips gracefully when the binary can't be built
+// (e.g. a Rust-less CI runner) — see `pampaAvailable`.
+
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = fileURLToPath(new URL('.', import.meta.url));
+// .../ts-packages/preview-renderer/src/test-utils/ -> repo root
+const REPO_ROOT = resolve(HERE, '../../../..');
+
+export interface PoolEntry {
+  r: [number, number];
+  t: number;
+  d: unknown;
+}
+export interface AstNode {
+  t: string;
+  c?: unknown;
+  s?: number;
+  [k: string]: unknown;
+}
+export interface RustQmdJson {
+  'pandoc-api-version': [number, number, number];
+  meta: Record<string, unknown>;
+  blocks: AstNode[];
+  astContext: { p: PoolEntry[]; files: unknown[] };
+}
+
+let binaryProbe: string | null | undefined;
+
+/** Build (once) and return the native pampa binary path, or null if unavailable. */
+function pampaBinary(): string | null {
+  if (binaryProbe !== undefined) return binaryProbe;
+  try {
+    execFileSync('cargo', ['build', '--quiet', '--bin', 'pampa'], {
+      cwd: REPO_ROOT,
+      stdio: ['ignore', 'ignore', 'inherit'],
+      timeout: 600_000,
+    });
+    binaryProbe = join(REPO_ROOT, 'target', 'debug', 'pampa');
+  } catch {
+    binaryProbe = null;
+  }
+  return binaryProbe;
+}
+
+/** True when round-trip fidelity tests can run (native pampa is buildable). */
+export function pampaAvailable(): boolean {
+  return pampaBinary() !== null;
+}
+
+/** Parse qmd into the source-tracked, untransformed Pandoc AST. */
+export function parseUntransformed(qmd: string): RustQmdJson {
+  const bin = pampaBinary();
+  if (!bin) throw new Error('pampa binary unavailable');
+  const dir = mkdtempSync(join(tmpdir(), 'pampa-oracle-'));
+  try {
+    const f = join(dir, 'in.qmd');
+    writeFileSync(f, qmd, 'utf8');
+    const out = execFileSync(bin, ['-t', 'json', '--json-source-location', 'full', f], {
+      encoding: 'utf8',
+      maxBuffer: 64 * 1024 * 1024,
+    });
+    return JSON.parse(out) as RustQmdJson;
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+// ---- semantic comparison ---------------------------------------------------
+
+const STRIP_KEYS = new Set(['s', 'a', 'l', 'targetS']);
+const VOLATILE_CITE_KEYS = new Set(['citationHash', 'citationNoteNum', 'citationIdS']);
+
+function stripObj(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(stripObj);
+  if (value && typeof value === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      if (STRIP_KEYS.has(k) || VOLATILE_CITE_KEYS.has(k)) continue;
+      out[k] = stripObj(v);
+    }
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Flatten nested inline marks into a per-run mark SET, matching ProseMirror's
+ * flat-mark model. This makes `[**x**](u)` (Link>Strong) and `**[x](u)**`
+ * (Strong>Link) compare equal — both are the run "x" carrying marks {Strong,
+ * Link(u)} — while still detecting a genuinely dropped mark, word, or node
+ * (the run's mark set or text would differ). Whitespace is collapsed; adjacent
+ * runs with identical mark sets are merged.
+ */
+type InlineToken =
+  | { k: 'T'; s: string; m: string[] }
+  | { k: 'BR'; m: string[] }
+  | { k: 'Code'; s: string; m: string[] }
+  | { k: 'Leaf'; t: string; j: string; m: string[] };
+
+function inlineTokens(items: AstNode[], marks: string[] = []): InlineToken[] {
+  const out: InlineToken[] = [];
+  const sorted = () => [...marks].sort();
+  for (const node of items) {
+    switch (node.t) {
+      case 'Emph':
+      case 'Strong':
+      case 'Strikeout':
+      case 'Underline':
+      case 'SmallCaps':
+      case 'Superscript':
+      case 'Subscript':
+        out.push(...inlineTokens(node.c as AstNode[], [...marks, node.t]));
+        break;
+      case 'Quoted': {
+        const inner = (node.c as [unknown, AstNode[]])[1] ?? [];
+        out.push(...inlineTokens(inner, [...marks, 'Quoted']));
+        break;
+      }
+      case 'Link':
+      case 'Image': {
+        const [, label, target] = node.c as [unknown, AstNode[], [string, string]];
+        out.push(...inlineTokens(label, [...marks, `${node.t}(${target?.[0] ?? ''})`]));
+        break;
+      }
+      case 'Space':
+      case 'SoftBreak':
+        out.push({ k: 'T', s: ' ', m: sorted() });
+        break;
+      case 'Str':
+        out.push({ k: 'T', s: node.c as string, m: sorted() });
+        break;
+      case 'LineBreak':
+        out.push({ k: 'BR', m: sorted() });
+        break;
+      case 'Code':
+        out.push({ k: 'Code', s: (node.c as [unknown, string])[1], m: sorted() });
+        break;
+      default:
+        // Opaque leaf (Math/Cite/Span/RawInline/Note/...). Compared by content.
+        out.push({ k: 'Leaf', t: node.t, j: JSON.stringify(node.c ?? null), m: sorted() });
+        break;
+    }
+  }
+  // Merge adjacent text runs with identical mark sets, then collapse whitespace.
+  const merged: InlineToken[] = [];
+  for (const tok of out) {
+    const last = merged[merged.length - 1];
+    if (tok.k === 'T' && last && last.k === 'T' && JSON.stringify(last.m) === JSON.stringify(tok.m)) {
+      last.s += tok.s;
+    } else {
+      merged.push({ ...tok });
+    }
+  }
+  for (const tok of merged) if (tok.k === 'T') tok.s = tok.s.replace(/\s+/g, ' ');
+  return merged;
+}
+
+function normalizeBlocks(items: AstNode[]): AstNode[] {
+  return items.map((node) => {
+    const out = { ...node };
+    if ((node.t === 'Para' || node.t === 'Plain') && Array.isArray(node.c)) {
+      // Compare Para and Plain as the same container (tight-list items are Plain,
+      // a standalone paragraph is Para; they differ only in list tightness, which
+      // is captured structurally elsewhere).
+      out.t = 'Para';
+      out.c = inlineTokens(node.c as AstNode[]) as unknown as AstNode[];
+    } else if (node.t === 'Header') {
+      const [lvl, attr, inl] = node.c as [number, unknown, AstNode[]];
+      out.c = [lvl, attr, inlineTokens(inl)] as unknown as AstNode[];
+    } else if (node.t === 'BlockQuote' || node.t === 'Figure') {
+      out.c = normalizeBlocks(node.c as AstNode[]);
+    } else if (node.t === 'Div') {
+      const [attr, inner] = node.c as [unknown, AstNode[]];
+      out.c = [attr, normalizeBlocks(inner)];
+    } else if (node.t === 'BulletList') {
+      out.c = (node.c as AstNode[][]).map(normalizeBlocks);
+    } else if (node.t === 'OrderedList') {
+      const [attrs, its] = node.c as [unknown, AstNode[][]];
+      out.c = [attrs, its.map(normalizeBlocks)];
+    }
+    return out;
+  });
+}
+
+/** Canonical, comparable form of a document's blocks. */
+export function canonical(blocks: AstNode[], opts: { normalize: boolean }): unknown {
+  const stripped = stripObj(blocks) as AstNode[];
+  return opts.normalize ? normalizeBlocks(stripped) : stripped;
+}
+
+export function astEqual(a: AstNode[], b: AstNode[], opts: { normalize: boolean }): boolean {
+  return JSON.stringify(canonical(a, opts)) === JSON.stringify(canonical(b, opts));
+}