From 1b924364de697691d8ac6afe0ff726a70b5e9f51 Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Thu, 18 Jun 2026 07:50:52 +1000
Subject: [PATCH 01/27] chore(porch): 1053 init pir

---
 .../status.yaml                                | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)
 create mode 100644 codev/projects/1053-vscode-typography-tokens-for-t/status.yaml

diff --git a/codev/projects/1053-vscode-typography-tokens-for-t/status.yaml b/codev/projects/1053-vscode-typography-tokens-for-t/status.yaml
new file mode 100644
index 000000000..3dcbe0f3c
--- /dev/null
+++ b/codev/projects/1053-vscode-typography-tokens-for-t/status.yaml
@@ -0,0 +1,18 @@
+id: '1053'
+title: vscode-typography-tokens-for-t
+protocol: pir
+phase: plan
+plan_phases: []
+current_plan_phase: null
+gates:
+  plan-approval:
+    status: pending
+  dev-approval:
+    status: pending
+  pr:
+    status: pending
+iteration: 1
+build_complete: false
+history: []
+started_at: '2026-06-17T21:50:52.095Z'
+updated_at: '2026-06-17T21:50:52.096Z'

From 75ce3175c3114c6fa6361ba1a30929f47303f6ab Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Thu, 18 Jun 2026 07:54:19 +1000
Subject: [PATCH 02/27] [PIR #1053] Plan draft

---
 .../1053-vscode-typography-tokens-for-t.md    | 225 ++++++++++++++++++
 codev/state/pir-1053_thread.md                |  14 ++
 2 files changed, 239 insertions(+)
 create mode 100644 codev/plans/1053-vscode-typography-tokens-for-t.md
 create mode 100644 codev/state/pir-1053_thread.md

diff --git a/codev/plans/1053-vscode-typography-tokens-for-t.md b/codev/plans/1053-vscode-typography-tokens-for-t.md
new file mode 100644
index 000000000..5a3e46d4d
--- /dev/null
+++ b/codev/plans/1053-vscode-typography-tokens-for-t.md
@@ -0,0 +1,225 @@
+# PIR Plan: Typography tokens for the Codev Markdown Preview (artifact canvas)
+
+> Issue #1053 · area/vscode · extends the locked 8-token color vocabulary from #945 (spec 945 D4)
+> with a typography token tier so prose (specs, plans, reviews) reads cleanly in the VSCode preview.
+
+## Understanding
+
+The Codev Markdown Preview surfaces the `@cluesmith/codev-artifact-canvas` component inside a
+VSCode `CustomTextEditor` webview (`packages/vscode/src/markdown-preview/`). The canvas ships
+`default-theme.css` with **eight `--codev-canvas-*` tokens that are colors only** (spec 945 D4
+deliberately capped the v1 vocabulary at colors). Everything about *type* — size, family,
+line-height, paragraph rhythm, heading scale, prose width — falls through to the webview's
+inherited defaults, which are tuned for code (the workbench UI font ~13px, line-height ~1.4),
+not for sustained reading of long-form documents.
+
+Concretely, in `packages/artifact-canvas/src/styles/default-theme.css` the
+`.codev-artifact-canvas` block sets only `color`/`background` and the eight color custom
+properties; there is **no rule** that sizes `body`, `p`, `h1`–`h6`, `ul`/`ol`, `blockquote`,
+`pre`/`code`, or `table`. In the VSCode host, `preview-template.ts`'s inline `<style>` binds the
+eight color tokens to `--vscode-*` variables but adds no typography. The webview body therefore
+renders prose at `--vscode-font-size` (UI font, not `--vscode-editor-font-size`) with the
+editor's tight inherited line-height.
+
+The canvas now has real consumers (#859 preview, #863 markers + minimap) and the colors-only
+limit is a daily readability problem. This issue adds a **typography token tier** with
+**github-markdown-css metrics as the chosen baseline** (the familiar mental model for reviewers
+who read PRs in that style all day), and binds those tokens to sensible VSCode-theme defaults in
+the host.
+
+Prose in the preview is rendered into `.codev-artifact-canvas-body` (see
+`ArtifactCanvas.tsx` — the body div holds the sanitized markdown HTML; the standalone
+`MarkdownView` uses `.codev-artifact-canvas-rendered`). New prose CSS rules must target
+descendants of **both** containers so the tokens work in the composed canvas *and* the standalone
+view; scoping to `.codev-artifact-canvas` (the outer container, ancestor of both) covers both.
+
+## Proposed Change
+
+Three tiers, in the issue's order. **Tier 1 + Tier 2 are the committed scope of this PR; Tier 3
+is an optional stretch** (see Decision 5).
+
+### Tier 1 — Package typography tokens (`default-theme.css`)
+
+Add a typography token group to `.codev-artifact-canvas` with github-markdown-css-aligned
+fallbacks, plus the CSS rules that consume them. **Final token list locked here at
+plan-approval** (Decision 1):
+
+| Token | Default | Notes |
+|---|---|---|
+| `--codev-canvas-font-size` | `16px` | prose body; github-markdown-css base |
+| `--codev-canvas-font-family` | `-apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji"` | github system sans stack |
+| `--codev-canvas-line-height` | `1.5` | prose body |
+| `--codev-canvas-paragraph-spacing` | `16px` | margin between paragraphs; lists / blockquotes / tables / `pre` derive from this |
+| `--codev-canvas-prose-max-width` | `none` | optional readable-measure cap; **off by default** (Decision 4) |
+| `--codev-canvas-h1-size` | `2em` | per-level heading sizes (Decision 2) |
+| `--codev-canvas-h2-size` | `1.5em` | |
+| `--codev-canvas-h3-size` | `1.25em` | |
+| `--codev-canvas-h4-size` | `1em` | |
+| `--codev-canvas-h5-size` | `0.875em` | |
+| `--codev-canvas-h6-size` | `0.85em` | github renders h6 muted + smallest |
+| `--codev-canvas-code-font-family` | `ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace` | github mono stack |
+| `--codev-canvas-code-font-size` | `0.85em` | github: code ~85% of prose |
+
+That is **8 prose/code tokens + 6 heading tokens = 14 tokens**. The heading set is bounded
+(one per element, 1:1 with the rendered tag) and reproduces github's *non-geometric* scale
+exactly — see Decision 2 for why per-level beats a single ratio.
+
+CSS rules consuming the tokens (all scoped under `.codev-artifact-canvas`, applied to the prose
+container so they don't disturb the comment cards / overlay / minimap chrome):
+
+- Body: `font-size`, `font-family`, `line-height` on the rendered prose container.
+- Optional measure cap: `max-width: var(--codev-canvas-prose-max-width)` on the prose container
+  (a no-op while the default is `none`).
+- Paragraphs: `p { margin: 0 0 var(--codev-canvas-paragraph-spacing); }` and zero the last
+  child's trailing margin.
+- Lists / blockquotes / tables / `pre`: bottom margin derived from
+  `var(--codev-canvas-paragraph-spacing)` for consistent vertical rhythm.
+- Headings: `h1..h6 { font-size: var(--codev-canvas-hN-size); }` plus deliberate top/bottom
+  margins and `line-height: 1.25` (github's heading line-height), so headings render with a
+  scale instead of user-agent defaults. github's h1/h2 bottom-border is **not** copied (it reads
+  as chrome in a narrow preview pane; out of scope, noted in the review).
+- Code: `pre, code { font-family: var(--codev-canvas-code-font-family); }` and
+  `font-size: var(--codev-canvas-code-font-size)` for inline `code` and `pre` blocks.
+
+The existing color rules (`a`, `pre`/`code` background, marker/minimap chrome) are untouched.
+
+### Tier 2 — Host mapping (`preview-template.ts`)
+
+Extend the inline `<style>` `.codev-artifact-canvas` block to bind the new typography tokens,
+**each binding documented inline** (Decision 3 on which bindings track VSCode vs prose-readability
+defaults):
+
+- `--codev-canvas-code-font-family: var(--vscode-editor-font-family)` — code blocks track the
+  reviewer's **editor** font (the github convention: mono for code).
+- `--codev-canvas-code-font-size` — left to the package default (`0.85em`), so code stays
+  proportional to prose rather than jumping to the editor's absolute size.
+- **Prose tokens (`font-size`, `font-family`, `line-height`, `paragraph-spacing`) are left to the
+  package defaults** — i.e. the preview overrides VSCode's editor/UI font for *prose* and uses the
+  github system sans stack at 16px / 1.5. Rationale (Decision 3): the editor font is frequently a
+  small monospace; inheriting it is exactly the cramped baseline this issue fixes. Code still
+  tracks the editor font via the binding above.
+
+A short inline comment block explains the "prose overrides editor font; code tracks it" split so a
+future maintainer doesn't "helpfully" rebind prose to `--vscode-editor-font-*`.
+
+### Tier 3 — User settings (optional, see Decision 5)
+
+If shipped: register `codev.markdownPreview.fontSize` and `codev.markdownPreview.lineHeight` in
+`packages/vscode/package.json` `contributes.configuration`, read them in `preview-provider.ts`,
+and inject them as inline `--codev-canvas-font-size` / `--codev-canvas-line-height` overrides on
+the webview root (so a user value wins over the package default). Kept to two knobs to avoid a
+sprawling settings surface; documented in the review.
+
+### Spec-amendment doc trail (#945 D4 contract)
+
+Spec 945 D4 calls the token vocabulary "the locked public contract … do not change shapes without
+a spec amendment." This expansion is recorded as a docs-only trail (no protocol gate beyond that,
+per the issue):
+
+- `packages/artifact-canvas/src/types.ts` — extend the contract comment to note the typography
+  tier added by #1053 (the tokens are CSS custom properties, not a TS shape, so no interface
+  changes; the comment is the contract's prose home).
+- `packages/artifact-canvas/README.md` — add the typography tokens to the Theming table with
+  their defaults and the github-markdown-css pin.
+- The plan and review files (this trail) record the amendment, satisfying "recorded in the issue,
+  plan, and review."
+
+### Reference baseline pin
+
+Document, in `default-theme.css` and the README, the exact github-markdown-css version whose
+metrics we mirror (Decision 3 below pins it), so the baseline is reproducible as that project
+evolves.
+
+## Files to Change
+
+- `packages/artifact-canvas/src/styles/default-theme.css` — add the 14 typography tokens (with
+  the version-pin comment) + the prose/heading/code CSS rules.
+- `packages/artifact-canvas/src/types.ts` — amend the D4 contract comment to cover the typography
+  tier (#1053 doc trail).
+- `packages/artifact-canvas/README.md:112-135` — extend the Theming token table + note the
+  github-markdown-css pin.
+- `packages/artifact-canvas/src/__tests__/default-theme.test.ts` *(new)* — vitest snapshot/assertion
+  over the `--codev-canvas-*` token list parsed from `default-theme.css` (AC: "Vitest snapshot
+  covering the default-theme.css token list passes"). Reads the CSS source, extracts declared
+  custom-property names, and snapshots the sorted list so any future token add/remove is a
+  reviewed diff.
+- `packages/vscode/src/markdown-preview/preview-template.ts:36-50` — bind the new typography
+  tokens with inline rationale comments (Tier 2).
+- *(Tier 3, optional)* `packages/vscode/package.json` — register
+  `codev.markdownPreview.fontSize` / `.lineHeight`.
+- *(Tier 3, optional)* `packages/vscode/src/markdown-preview/preview-provider.ts` — read the
+  settings and inject inline token overrides on the webview root.
+
+## Decisions to Lock at plan-approval
+
+**Decision 1 — Final token list.** The 14-token list in the Tier 1 table. Rationale: covers every
+prose lever the issue names (size, family, line-height, paragraph rhythm, optional width, heading
+scale, code family+size) without inventing knobs nobody asked for. *Confirm or trim.*
+
+**Decision 2 — Heading granularity: per-level tokens (RECOMMENDED) vs scale-base + ratio.**
+github-markdown-css's heading sizes are `2 / 1.5 / 1.25 / 1 / 0.875 / 0.85 em` — **not** a clean
+geometric progression. A single `--codev-canvas-heading-scale-ratio` + `calc()` *cannot reproduce
+the chosen baseline* (e.g. a 1.25 ratio gives 2 / 1.6 / 1.28 / 1.024 / … — wrong at every level).
+Since the issue explicitly pins github-markdown-css as the baseline and AC requires "a deliberate
+scale," I recommend **per-level `--codev-canvas-h1-size` … `--codev-canvas-h6-size`** for exact
+fidelity and a direct per-heading override surface. This *overrides the issue's stated lean*
+(scale+ratio for headings) on the grounds that the lean is incompatible with the locked baseline;
+flagging it explicitly for your call. *Alternative if you prefer fewer tokens:* `scale-base` +
+`ratio` (2 tokens), accepting that headings will diverge from github's exact sizes.
+
+**Decision 3 — VSCode-theme alignment vs prose-readability defaults, + baseline pin.** Prose
+tokens override the VSCode editor font (github system sans, 16px, 1.5); `--codev-canvas-code-*`
+track the editor font for code blocks. Baseline pinned to **github-markdown-css v5.8.1** (latest
+stable; exact version recorded in `default-theme.css` + README). *Confirm the version to pin.*
+
+**Decision 4 — `prose-max-width` default.** Ships as `none` (no cap) so it can't break a host
+layout (the issue's stated fallback); the token exists so a host/user can opt into e.g. `72ch`.
+*Confirm off-by-default.*
+
+**Decision 5 — Tier 3 scope.** Recommend **landing Tier 1 + Tier 2 firmly** and treating Tier 3
+(two settings: `fontSize`, `lineHeight`) as an **optional add within this PR** if the dev-approval
+readability review goes smoothly, otherwise spun off to a follow-up issue. Tier 3 is explicitly
+"nice-to-have, not gating" in the issue. *Tell me: include Tier 3 now, or defer it.*
+
+## Risks & Alternatives Considered
+
+- **Risk: prose rules leak into the comment cards / minimap / overlay chrome.** Those use
+  `font-size: 0.9em` (cards) and fixed sizing. Mitigation: scope prose rules to the rendered prose
+  container and its block descendants, not the chrome classes; verify cards/minimap visually at
+  dev-approval (AC: "no regression to marker rendering, minimap, comment cards, or color
+  theming").
+- **Risk: `em`-based heading + code sizes compound unexpectedly** if a parent font-size changes.
+  Mitigation: heading/code sizes are `em` relative to the prose body `font-size` (a single
+  `px` anchor), matching github-markdown-css's own model; no nested `em` chains.
+- **Risk: token bloat on a "locked public contract."** 14 tokens is the upper end. Mitigation:
+  every token maps to a concrete readability lever the issue named; the heading 6 are bounded and
+  1:1 with elements. Decision 2's alternative (scale+ratio) trims 4 tokens if you prefer.
+- **Risk: the spec-amendment is under-recorded.** Mitigation: the doc trail touches types.ts +
+  README + plan + review, exactly the surfaces #945 D4 names.
+- **Alternative: bind prose to `--vscode-editor-font-*`.** Rejected — the editor font is the
+  cramped baseline this issue exists to fix; only code should track it (Decision 3).
+- **Alternative: a single `--codev-canvas-typography` shorthand.** Rejected — defeats per-lever
+  host/user overrides and is un-snapshotable.
+
+## Test Plan
+
+- **Unit (vitest, new `default-theme.test.ts`):** parse `default-theme.css`, assert the full
+  `--codev-canvas-*` token set (colors + new typography) is present and snapshot the sorted list;
+  assert each new token has a non-empty fallback value. Run from the worktree:
+  `pnpm --filter @cluesmith/codev-artifact-canvas test`.
+- **Unit (existing suites):** `pnpm --filter @cluesmith/codev-artifact-canvas test` stays green
+  (renderer, overlay, marker tests unaffected).
+- **Type/build:** `pnpm --filter @cluesmith/codev-artifact-canvas build` and
+  `pnpm --filter @cluesmith/codev-vscode build` (or the package's check-types) succeed.
+- **Manual at dev-approval (load-bearing — this is why PIR):**
+  - Open a long real spec/plan/review in the Codev Markdown Preview (run the worktree:
+    `afx dev pir-1053`, then open the preview on e.g. `codev/specs/945-*.md`).
+  - Confirm prose reads at 16px / 1.5 line-height with paragraph spacing — visibly looser than the
+    cramped v3.2.0 baseline.
+  - Confirm h1–h6 render with the github scale (not user-agent defaults).
+  - Confirm `pre`/inline `code` stay monospace and track the **editor** font.
+  - Resize the pane: confirm `prose-max-width` behavior matches Decision 4 (no cap by default).
+  - Confirm **no regression**: comment cards (#863), right-edge minimap, hover-`+` overlay, and
+    all color theming render unchanged in both light and dark themes.
+  - *(If Tier 3 shipped)* change `codev.markdownPreview.fontSize` / `.lineHeight` and confirm the
+    preview reflows live.
diff --git a/codev/state/pir-1053_thread.md b/codev/state/pir-1053_thread.md
new file mode 100644
index 000000000..f1149e1ff
--- /dev/null
+++ b/codev/state/pir-1053_thread.md
@@ -0,0 +1,14 @@
+# PIR #1053 — typography tokens for the Codev Markdown Preview (artifact canvas)
+
+## Plan phase (in progress)
+
+Investigated the codebase:
+- `packages/artifact-canvas/src/styles/default-theme.css` — ships 8 color-only `--codev-canvas-*` tokens. Prose elements inherit everything else.
+- `packages/artifact-canvas/src/types.ts` — D4 "locked public contract" comment; contract to amend.
+- `packages/vscode/src/markdown-preview/preview-template.ts` — inline `<style>` binds the 8 color tokens to `--vscode-*`. This is the tier-2 host-mapping seam.
+- VSCode preview mounts `<ArtifactCanvas>` (webview/main.ts), whose prose lives under `.codev-artifact-canvas-body`. CSS prose rules must target that container's descendants.
+- Rendered prose elements: h1-h6, p, ul/ol/li, blockquote, pre, code, table (markdown-it output, sanitized).
+
+Key plan-gate decisions captured in the plan: final token list, heading granularity (per-level vs scale+ratio), github-markdown-css version pin, prose-max-width default, tier-3 scope.
+
+Writing plan to `codev/plans/1053-vscode-typography-tokens-for-t.md`.

From 544e318edbe1d9c326cfd15986daac2d59dc8ca5 Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Thu, 18 Jun 2026 07:54:25 +1000
Subject: [PATCH 03/27] chore(porch): 1053 plan-approval gate-requested

---
 codev/projects/1053-vscode-typography-tokens-for-t/status.yaml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/codev/projects/1053-vscode-typography-tokens-for-t/status.yaml b/codev/projects/1053-vscode-typography-tokens-for-t/status.yaml
index 3dcbe0f3c..f5b9d7083 100644
--- a/codev/projects/1053-vscode-typography-tokens-for-t/status.yaml
+++ b/codev/projects/1053-vscode-typography-tokens-for-t/status.yaml
@@ -7,6 +7,7 @@ current_plan_phase: null
 gates:
   plan-approval:
     status: pending
+    requested_at: '2026-06-17T21:54:25.731Z'
   dev-approval:
     status: pending
   pr:
@@ -15,4 +16,4 @@ iteration: 1
 build_complete: false
 history: []
 started_at: '2026-06-17T21:50:52.095Z'
-updated_at: '2026-06-17T21:50:52.096Z'
+updated_at: '2026-06-17T21:54:25.731Z'

From 957655c0590a93381b27d12794b8e38f0a59e43a Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Thu, 18 Jun 2026 08:01:29 +1000
Subject: [PATCH 04/27] chore(porch): 1053 plan-approval gate-approved

---
 .../projects/1053-vscode-typography-tokens-for-t/status.yaml | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/codev/projects/1053-vscode-typography-tokens-for-t/status.yaml b/codev/projects/1053-vscode-typography-tokens-for-t/status.yaml
index f5b9d7083..1d2d99f56 100644
--- a/codev/projects/1053-vscode-typography-tokens-for-t/status.yaml
+++ b/codev/projects/1053-vscode-typography-tokens-for-t/status.yaml
@@ -6,8 +6,9 @@ plan_phases: []
 current_plan_phase: null
 gates:
   plan-approval:
-    status: pending
+    status: approved
     requested_at: '2026-06-17T21:54:25.731Z'
+    approved_at: '2026-06-17T22:01:29.466Z'
   dev-approval:
     status: pending
   pr:
@@ -16,4 +17,4 @@ iteration: 1
 build_complete: false
 history: []
 started_at: '2026-06-17T21:50:52.095Z'
-updated_at: '2026-06-17T21:54:25.731Z'
+updated_at: '2026-06-17T22:01:29.467Z'

From 0e4a3c5cd9ef76f8523e51287fa100cacc65834d Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Thu, 18 Jun 2026 08:01:38 +1000
Subject: [PATCH 05/27] chore(porch): 1053 implement phase-transition

---
 .../projects/1053-vscode-typography-tokens-for-t/status.yaml  | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/codev/projects/1053-vscode-typography-tokens-for-t/status.yaml b/codev/projects/1053-vscode-typography-tokens-for-t/status.yaml
index 1d2d99f56..3b93ea61c 100644
--- a/codev/projects/1053-vscode-typography-tokens-for-t/status.yaml
+++ b/codev/projects/1053-vscode-typography-tokens-for-t/status.yaml
@@ -1,7 +1,7 @@
 id: '1053'
 title: vscode-typography-tokens-for-t
 protocol: pir
-phase: plan
+phase: implement
 plan_phases: []
 current_plan_phase: null
 gates:
@@ -17,4 +17,4 @@ iteration: 1
 build_complete: false
 history: []
 started_at: '2026-06-17T21:50:52.095Z'
-updated_at: '2026-06-17T22:01:29.467Z'
+updated_at: '2026-06-17T22:01:38.682Z'

From 3cc0de12302590c00cd284bcdee9013a09108e9d Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Thu, 18 Jun 2026 08:08:22 +1000
Subject: [PATCH 06/27] [PIR #1053] Add typography token tier to canvas
 default-theme.css

---
 packages/artifact-canvas/README.md            | 19 ++++
 .../src/__tests__/default-theme.test.ts       | 73 ++++++++++++++
 .../src/styles/default-theme.css              | 94 ++++++++++++++++++-
 packages/artifact-canvas/src/types.ts         |  6 ++
 4 files changed, 190 insertions(+), 2 deletions(-)
 create mode 100644 packages/artifact-canvas/src/__tests__/default-theme.test.ts

diff --git a/packages/artifact-canvas/README.md b/packages/artifact-canvas/README.md
index fa8c669ef..5ab556601 100644
--- a/packages/artifact-canvas/README.md
+++ b/packages/artifact-canvas/README.md
@@ -114,6 +114,8 @@ paint pixels.
 Import the default stylesheet and override any subset of the `--codev-canvas-*` tokens on the
 `.codev-artifact-canvas` container. There is no JS theming on the v1 render path.
 
+**Color tokens** (spec 945 D4):
+
 | Token | Default |
 |-------|---------|
 | `--codev-canvas-foreground` | `#1f2328` |
@@ -125,12 +127,29 @@ Import the default stylesheet and override any subset of the `--codev-canvas-*`
 | `--codev-canvas-link` | `#0969da` |
 | `--codev-canvas-comment-marker` | `#bf8700` |
 
+**Typography tokens** (#1053). Defaults mirror [github-markdown-css](https://github.com/sindresorhus/github-markdown-css)
+v5.8.1 so prose reads cleanly instead of inheriting the host's code-tuned font. Theme-invariant
+(dark mode is covered by the color tokens above):
+
+| Token | Default | Controls |
+|-------|---------|----------|
+| `--codev-canvas-font-size` | `16px` | prose body size |
+| `--codev-canvas-font-family` | system sans stack | prose body font |
+| `--codev-canvas-line-height` | `1.5` | prose line-height |
+| `--codev-canvas-paragraph-spacing` | `16px` | gap below paragraphs / lists / blockquotes / tables / `pre` |
+| `--codev-canvas-prose-max-width` | `none` | optional readable-measure cap (e.g. `72ch`); off by default |
+| `--codev-canvas-h1-size` … `--codev-canvas-h6-size` | `2em` / `1.5em` / `1.25em` / `1em` / `0.875em` / `0.85em` | per-level heading sizes |
+| `--codev-canvas-code-font-family` | system monospace stack | `pre` / inline `code` font |
+| `--codev-canvas-code-font-size` | `0.85em` | `pre` / inline `code` size |
+
 ```css
 /* Bind the canvas to the host's theme — e.g. a VSCode webview */
 .codev-artifact-canvas {
   --codev-canvas-foreground: var(--vscode-foreground);
   --codev-canvas-background: var(--vscode-editor-background);
   --codev-canvas-accent: var(--vscode-focusBorder);
+  /* Code blocks track the editor font; prose keeps the readable sans stack. */
+  --codev-canvas-code-font-family: var(--vscode-editor-font-family);
 }
 ```
 
diff --git a/packages/artifact-canvas/src/__tests__/default-theme.test.ts b/packages/artifact-canvas/src/__tests__/default-theme.test.ts
new file mode 100644
index 000000000..d9b5da217
--- /dev/null
+++ b/packages/artifact-canvas/src/__tests__/default-theme.test.ts
@@ -0,0 +1,73 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+/**
+ * Guards the public `--codev-canvas-*` token vocabulary shipped by `default-theme.css` (spec 945
+ * D4 colors + the #1053 typography tier). The vocabulary is a public contract (spec 945 D4 — "do
+ * not change shapes without a spec amendment"), so the snapshot makes any add/remove a reviewed
+ * diff rather than a silent contract change.
+ */
+
+const cssPath = join(dirname(fileURLToPath(import.meta.url)), '../styles/default-theme.css');
+const css = readFileSync(cssPath, 'utf8');
+
+/** Extract `--codev-canvas-*` custom-property *declarations* (name: value;), not `var()` refs. */
+function declaredTokens(source: string): Map<string, string> {
+  const tokens = new Map<string, string>();
+  const re = /(--codev-canvas-[a-z0-9-]+)\s*:\s*([^;]+);/g;
+  let match: RegExpExecArray | null;
+  while ((match = re.exec(source)) !== null) {
+    tokens.set(match[1], match[2].trim().replace(/\s+/g, ' '));
+  }
+  return tokens;
+}
+
+describe('default-theme.css token vocabulary', () => {
+  const tokens = declaredTokens(css);
+
+  it('declares exactly the locked token list (snapshot)', () => {
+    expect([...tokens.keys()].sort()).toMatchInlineSnapshot(`
+      [
+        "--codev-canvas-accent",
+        "--codev-canvas-background",
+        "--codev-canvas-border",
+        "--codev-canvas-code-background",
+        "--codev-canvas-code-font-family",
+        "--codev-canvas-code-font-size",
+        "--codev-canvas-comment-marker",
+        "--codev-canvas-font-family",
+        "--codev-canvas-font-size",
+        "--codev-canvas-foreground",
+        "--codev-canvas-h1-size",
+        "--codev-canvas-h2-size",
+        "--codev-canvas-h3-size",
+        "--codev-canvas-h4-size",
+        "--codev-canvas-h5-size",
+        "--codev-canvas-h6-size",
+        "--codev-canvas-line-height",
+        "--codev-canvas-link",
+        "--codev-canvas-muted",
+        "--codev-canvas-paragraph-spacing",
+        "--codev-canvas-prose-max-width",
+      ]
+    `);
+  });
+
+  it('ships a non-empty fallback for every token', () => {
+    for (const [name, value] of tokens) {
+      expect(value, `${name} should have a fallback value`).not.toBe('');
+    }
+  });
+
+  it('includes each typography token with its github-baseline default', () => {
+    expect(tokens.get('--codev-canvas-font-size')).toBe('16px');
+    expect(tokens.get('--codev-canvas-line-height')).toBe('1.5');
+    expect(tokens.get('--codev-canvas-paragraph-spacing')).toBe('16px');
+    expect(tokens.get('--codev-canvas-prose-max-width')).toBe('none');
+    expect(tokens.get('--codev-canvas-h1-size')).toBe('2em');
+    expect(tokens.get('--codev-canvas-h6-size')).toBe('0.85em');
+    expect(tokens.get('--codev-canvas-code-font-size')).toBe('0.85em');
+  });
+});
diff --git a/packages/artifact-canvas/src/styles/default-theme.css b/packages/artifact-canvas/src/styles/default-theme.css
index 3e8a3c858..0bd177126 100644
--- a/packages/artifact-canvas/src/styles/default-theme.css
+++ b/packages/artifact-canvas/src/styles/default-theme.css
@@ -1,5 +1,8 @@
 /*
- * Default theme for @cluesmith/codev-artifact-canvas (spec D4, Model A).
+ * Default theme for @cluesmith/codev-artifact-canvas (spec 945 D4, Model A).
+ *
+ * Two token tiers: the spec-945 color vocabulary and the #1053 typography tier (sizes, families,
+ * line-height, rhythm, heading scale — github-markdown-css v5.8.1 metrics as the baseline).
  *
  * CSS custom properties are the SOLE v1 theming mechanism. Each token below has a sensible
  * fallback; hosts override any subset by setting the variable on the canvas container, e.g.
@@ -15,7 +18,7 @@
  */
 
 .codev-artifact-canvas {
-  /* v1 token vocabulary (spec D4) */
+  /* v1 color token vocabulary (spec 945 D4) */
   --codev-canvas-foreground: #1f2328;
   --codev-canvas-background: #ffffff;
   --codev-canvas-accent: #0969da;
@@ -25,8 +28,41 @@
   --codev-canvas-link: #0969da;
   --codev-canvas-comment-marker: #bf8700;
 
+  /*
+   * Typography token tier (#1053 — amends the spec-945 D4 "locked public contract").
+   * Defaults mirror github-markdown-css v5.8.1 metrics: it's the familiar mental model for
+   * reviewers who read PRs in that style, and keeps prose (specs, plans, reviews) readable
+   * instead of inheriting the host's code-tuned font/line-height. Typography tokens are
+   * theme-invariant — dark mode is covered entirely by the color tokens above.
+   */
+  --codev-canvas-font-size: 16px;
+  --codev-canvas-font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans",
+    Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji";
+  --codev-canvas-line-height: 1.5;
+  /* Vertical rhythm: the bottom margin of paragraphs; lists / blockquotes / tables / pre derive. */
+  --codev-canvas-paragraph-spacing: 16px;
+  /* Optional readable-measure cap. Off by default (`none`) so it can't break a host layout; a
+     host or user opts into e.g. 72ch. */
+  --codev-canvas-prose-max-width: none;
+  /* Per-level heading sizes. github-markdown-css's scale is non-geometric, so a single ratio
+     can't reproduce it — explicit per-level tokens mirror the baseline exactly (#1053). */
+  --codev-canvas-h1-size: 2em;
+  --codev-canvas-h2-size: 1.5em;
+  --codev-canvas-h3-size: 1.25em;
+  --codev-canvas-h4-size: 1em;
+  --codev-canvas-h5-size: 0.875em;
+  --codev-canvas-h6-size: 0.85em;
+  /* Code (pre + inline). Family is its own token so a host can track its editor font for code
+     while prose keeps the sans stack; size is ~85% of prose, matching github-markdown-css. */
+  --codev-canvas-code-font-family: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas,
+    "Liberation Mono", monospace;
+  --codev-canvas-code-font-size: 0.85em;
+
   color: var(--codev-canvas-foreground);
   background: var(--codev-canvas-background);
+  font-family: var(--codev-canvas-font-family);
+  font-size: var(--codev-canvas-font-size);
+  line-height: var(--codev-canvas-line-height);
   /* Positioning context for the comment overlay, which anchors to the active block. */
   position: relative;
 }
@@ -34,6 +70,60 @@
 /* Left gutter so the anchored "+" affordance sits beside a block, not over its text. */
 .codev-artifact-canvas-body {
   padding-left: 1.9rem;
+  /* Optional readable-measure cap (off by default — token is `none`). When a host/user sets a
+     width (e.g. 72ch) the prose column stops growing with the pane. */
+  max-width: var(--codev-canvas-prose-max-width);
+}
+
+/*
+ * Prose typography (#1053). Scoped to the rendered body so it styles the markdown content
+ * without touching the comment cards, overlay `+`, or minimap chrome (each self-sized below).
+ * Sizes are `em`-relative to the body font-size (a single px anchor), matching how
+ * github-markdown-css avoids compounding nested `em` chains.
+ */
+.codev-artifact-canvas-body p {
+  margin: 0 0 var(--codev-canvas-paragraph-spacing);
+}
+/* Derive list / blockquote / table / pre rhythm from the paragraph-spacing token so block
+   spacing stays consistent when a host retunes it. */
+.codev-artifact-canvas-body ul,
+.codev-artifact-canvas-body ol,
+.codev-artifact-canvas-body blockquote,
+.codev-artifact-canvas-body table,
+.codev-artifact-canvas-body pre {
+  margin: 0 0 var(--codev-canvas-paragraph-spacing);
+}
+/* Don't add trailing space below the final block — it reads as an unbalanced gap. */
+.codev-artifact-canvas-body > *:last-child {
+  margin-bottom: 0;
+}
+/* Headings: a deliberate per-level scale plus github's heading rhythm (tighter line-height,
+   24px top / 16px bottom, semibold) so headings don't fall through to user-agent defaults. */
+.codev-artifact-canvas-body h1,
+.codev-artifact-canvas-body h2,
+.codev-artifact-canvas-body h3,
+.codev-artifact-canvas-body h4,
+.codev-artifact-canvas-body h5,
+.codev-artifact-canvas-body h6 {
+  margin: 24px 0 16px;
+  line-height: 1.25;
+  font-weight: 600;
+}
+.codev-artifact-canvas-body h1 { font-size: var(--codev-canvas-h1-size); }
+.codev-artifact-canvas-body h2 { font-size: var(--codev-canvas-h2-size); }
+.codev-artifact-canvas-body h3 { font-size: var(--codev-canvas-h3-size); }
+.codev-artifact-canvas-body h4 { font-size: var(--codev-canvas-h4-size); }
+.codev-artifact-canvas-body h5 { font-size: var(--codev-canvas-h5-size); }
+.codev-artifact-canvas-body h6 {
+  font-size: var(--codev-canvas-h6-size);
+  color: var(--codev-canvas-muted);
+}
+/* Code: monospace family + ~85% size for both fenced blocks and inline `code`. The background
+   color rule for these lives below with the other color tokens. */
+.codev-artifact-canvas-body pre,
+.codev-artifact-canvas-body code {
+  font-family: var(--codev-canvas-code-font-family);
+  font-size: var(--codev-canvas-code-font-size);
 }
 
 /* Phase 3 — comment overlay + minimal marker rendering */
diff --git a/packages/artifact-canvas/src/types.ts b/packages/artifact-canvas/src/types.ts
index c1b888602..c89ad6206 100644
--- a/packages/artifact-canvas/src/types.ts
+++ b/packages/artifact-canvas/src/types.ts
@@ -4,6 +4,12 @@
  * These are the locked public contract from spec-945 (the adapter interfaces live in
  * ./adapters). Field names are part of the contract — do not change shapes without a
  * spec amendment.
+ *
+ * Contract amendment (#1053): the public `--codev-canvas-*` token vocabulary (spec 945 D4)
+ * gained a typography tier — font size/family, line-height, paragraph spacing, an optional
+ * prose-width cap, per-level heading sizes, and code font family/size. The tokens are CSS
+ * custom properties, not a TypeScript shape, so no interface here changed; the vocabulary and
+ * its github-markdown-css baseline are documented in `styles/default-theme.css` and the README.
  */
 
 import type { FileAdapter } from './adapters/FileAdapter.js';

From 83593f0c22835a7a4bcae6498561e7deda1cebbf Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Thu, 18 Jun 2026 08:08:28 +1000
Subject: [PATCH 07/27] [PIR #1053] Bind typography tokens in VSCode preview +
 add font-size/line-height settings

---
 packages/vscode/package.json                  | 12 ++++++
 .../src/markdown-preview/preview-provider.ts  | 14 +++++++
 .../src/markdown-preview/preview-template.ts  | 42 ++++++++++++++++++-
 3 files changed, 67 insertions(+), 1 deletion(-)

diff --git a/packages/vscode/package.json b/packages/vscode/package.json
index cb76aeb86..f4b295ce3 100644
--- a/packages/vscode/package.json
+++ b/packages/vscode/package.json
@@ -875,6 +875,18 @@
           ],
           "default": "stage",
           "description": "Which axis the Builders view groups by. 'stage' (default) is the action axis; 'area' is the domain axis. Toggleable via the Builders title-bar button."
+        },
+        "codev.markdownPreview.fontSize": {
+          "type": "number",
+          "default": 0,
+          "minimum": 0,
+          "description": "Prose font size (in pixels) for the Codev Markdown Preview. 0 uses the built-in default (16px, the github-markdown-css baseline). Code blocks are sized relative to this."
+        },
+        "codev.markdownPreview.lineHeight": {
+          "type": "number",
+          "default": 0,
+          "minimum": 0,
+          "description": "Prose line-height (unitless multiplier) for the Codev Markdown Preview. 0 uses the built-in default (1.5, the github-markdown-css baseline)."
         }
       }
     },
diff --git a/packages/vscode/src/markdown-preview/preview-provider.ts b/packages/vscode/src/markdown-preview/preview-provider.ts
index 00e9500e5..2e0e71c36 100644
--- a/packages/vscode/src/markdown-preview/preview-provider.ts
+++ b/packages/vscode/src/markdown-preview/preview-provider.ts
@@ -53,6 +53,16 @@ export class MarkdownPreviewProvider implements vscode.CustomTextEditorProvider
     };
     panel.webview.html = this.renderHtml(panel.webview);
 
+    // Live-reflow on a typography settings change (#1053, Tier 3): re-render the document so the
+    // new `--codev-canvas-*` overrides take effect without the reviewer reopening the preview.
+    // The webview re-sends `ready`, which re-pushes the current content + markers.
+    const configSub = vscode.workspace.onDidChangeConfiguration((e) => {
+      if (e.affectsConfiguration('codev.markdownPreview')) {
+        panel.webview.html = this.renderHtml(panel.webview);
+      }
+    });
+    panel.onDidDispose(() => configSub.dispose());
+
     const pushUpdate = (): void => {
       // Send the raw document text: the canvas renderer strips REVIEW/comment lines itself
       // (and keeps blocks intact + data-line accurate), so the host no longer pre-hides them.
@@ -107,10 +117,14 @@ export class MarkdownPreviewProvider implements vscode.CustomTextEditorProvider
       webview
         .asWebviewUri(vscode.Uri.joinPath(this.extensionUri, 'dist', 'webview', file))
         .toString();
+    // User typography overrides (#1053, Tier 3). 0 = "use the built-in github-baseline default".
+    const cfg = vscode.workspace.getConfiguration('codev.markdownPreview');
     return renderMarkdownPreviewHtml({
       cspSource: webview.cspSource,
       scriptUri: asUri('markdown-preview.js'),
       styleUri: asUri('markdown-preview.css'),
+      fontSizePx: cfg.get<number>('fontSize', 0),
+      lineHeight: cfg.get<number>('lineHeight', 0),
     });
   }
 }
diff --git a/packages/vscode/src/markdown-preview/preview-template.ts b/packages/vscode/src/markdown-preview/preview-template.ts
index 2142d4496..9c4c05ee9 100644
--- a/packages/vscode/src/markdown-preview/preview-template.ts
+++ b/packages/vscode/src/markdown-preview/preview-template.ts
@@ -14,11 +14,19 @@ export interface MarkdownPreviewHtmlOptions {
   scriptUri: string;
   /** `asWebviewUri(...)` for the bundled stylesheet (`markdown-preview.css`), stringified. */
   styleUri: string;
+  /**
+   * Optional user typography overrides (#1053, Tier 3) from `codev.markdownPreview.*`. Each is
+   * emitted as a `--codev-canvas-*` declaration that wins over the package default; an omitted
+   * (or zero) value leaves the github-baseline default in place.
+   */
+  fontSizePx?: number;
+  lineHeight?: number;
 }
 
 /** Build the full webview document with a fresh nonce bound into the CSP and the script tag. */
 export function renderMarkdownPreviewHtml(opts: MarkdownPreviewHtmlOptions): string {
   const nonce = getNonce();
+  const userTokens = buildUserTypographyOverrides(opts);
   const csp = [
     `default-src 'none'`,
     `img-src ${opts.cspSource} https: data:`,
@@ -35,7 +43,7 @@ export function renderMarkdownPreviewHtml(opts: MarkdownPreviewHtmlOptions): str
   <link href="${opts.styleUri}" rel="stylesheet" />
   <style>
     html, body { background: var(--vscode-editor-background); margin: 0; padding: 0 14px; }
-    /* Bind the canvas tokens to the active VS Code theme (package Model A). */
+    /* Bind the canvas color tokens to the active VS Code theme (package Model A). */
     .codev-artifact-canvas {
       --codev-canvas-foreground: var(--vscode-foreground);
       --codev-canvas-background: var(--vscode-editor-background);
@@ -45,6 +53,21 @@ export function renderMarkdownPreviewHtml(opts: MarkdownPreviewHtmlOptions): str
       --codev-canvas-code-background: var(--vscode-textCodeBlock-background);
       --codev-canvas-link: var(--vscode-textLink-foreground);
       --codev-canvas-comment-marker: var(--vscode-editorWarning-foreground);
+
+      /*
+       * Typography (#1053). The split is deliberate, mirroring github-markdown-css's own
+       * convention (sans prose, mono code):
+       *  - CODE tracks the reviewer's editor font (--vscode-editor-font-family) so fenced
+       *    blocks and inline code look like the code they're showing.
+       *  - PROSE is intentionally NOT bound to the editor/UI font — it keeps the package's
+       *    github-style sans stack at 16px / 1.5. The editor font is frequently a small
+       *    monospace, and inheriting it is exactly the cramped, code-tuned baseline this
+       *    surface exists to fix. Do not "helpfully" rebind prose to --vscode-editor-font-*.
+       *  - Code SIZE is left to the package default (~85% of prose) so code stays proportional
+       *    rather than jumping to the editor's absolute point size.
+       */
+      --codev-canvas-code-font-family: var(--vscode-editor-font-family);
+${userTokens}
       color: var(--codev-canvas-foreground);
       background: var(--codev-canvas-background);
     }
@@ -58,6 +81,23 @@ export function renderMarkdownPreviewHtml(opts: MarkdownPreviewHtmlOptions): str
 </html>`;
 }
 
+/**
+ * Build the `--codev-canvas-*` override declarations for the user's `codev.markdownPreview.*`
+ * typography settings (#1053, Tier 3). A non-positive / missing value contributes nothing, so
+ * the github-baseline package default stays in effect. The values are numeric (validated by the
+ * VS Code settings schema), so there is no string interpolation of untrusted input into the CSS.
+ */
+function buildUserTypographyOverrides(opts: MarkdownPreviewHtmlOptions): string {
+  const decls: string[] = [];
+  if (typeof opts.fontSizePx === 'number' && opts.fontSizePx > 0) {
+    decls.push(`      --codev-canvas-font-size: ${opts.fontSizePx}px;`);
+  }
+  if (typeof opts.lineHeight === 'number' && opts.lineHeight > 0) {
+    decls.push(`      --codev-canvas-line-height: ${opts.lineHeight};`);
+  }
+  return decls.join('\n');
+}
+
 /** CSP nonce — a fresh 32-char token per render (mirrors the backlog-search webview, #920). */
 function getNonce(): string {
   const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';

From 6e1d0b186fc52c23d8c37553402bacd1dfb220d4 Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Thu, 18 Jun 2026 08:08:47 +1000
Subject: [PATCH 08/27] [PIR #1053] Thread: implement phase notes

---
 codev/state/pir-1053_thread.md | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/codev/state/pir-1053_thread.md b/codev/state/pir-1053_thread.md
index f1149e1ff..7e6ad82ff 100644
--- a/codev/state/pir-1053_thread.md
+++ b/codev/state/pir-1053_thread.md
@@ -12,3 +12,28 @@ Investigated the codebase:
 Key plan-gate decisions captured in the plan: final token list, heading granularity (per-level vs scale+ratio), github-markdown-css version pin, prose-max-width default, tier-3 scope.
 
 Writing plan to `codev/plans/1053-vscode-typography-tokens-for-t.md`.
+
+## Plan approved (silent on the 5 decisions) → proceeded with recommendations.
+
+Locked: 21-token vocabulary (8 color + 13 typography), per-level heading tokens (h1-h6,
+github's non-geometric scale can't be a single ratio), github-markdown-css v5.8.1 pin,
+`prose-max-width: none` default, Tier 3 included (2 settings, low-risk).
+
+## Implement phase — done, awaiting dev-approval
+
+- `default-theme.css`: +13 typography tokens with github v5.8.1 defaults + prose/heading/code
+  CSS rules scoped to `.codev-artifact-canvas-body` (chrome untouched).
+- `types.ts`: D4 contract amendment comment (#1053 doc trail).
+- `README.md`: typography token table + baseline pin (doc trail).
+- `default-theme.test.ts` (new): inline-snapshot of the 21-token list + non-empty + default
+  assertions.
+- `preview-template.ts` (Tier 2): code-font-family → editor font; prose keeps the sans stack
+  (documented why); Tier-3 user overrides emitted into the host `<style>`.
+  Gotcha: backticks inside the CSS comment broke the surrounding template literal — removed them.
+- `preview-provider.ts` + `package.json` (Tier 3): `codev.markdownPreview.fontSize` /
+  `.lineHeight` settings, read in renderHtml, live-reflow via onDidChangeConfiguration.
+
+Tests: canvas 54/54, vscode 442/442 unit; both typechecks + esbuild bundle clean. Verified the
+new tokens + prose rules land in the bundled `dist/webview/markdown-preview.css`.
+(Had to build codev-core + codev-types first — they weren't built in the fresh worktree; the
+resolution errors were environmental, not from my diff.)

From a4c8b8e40f1e7994543aaf951adf4aa94e95c66c Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Thu, 18 Jun 2026 08:09:23 +1000
Subject: [PATCH 09/27] chore(porch): 1053 dev-approval gate-requested

---
 codev/projects/1053-vscode-typography-tokens-for-t/status.yaml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/codev/projects/1053-vscode-typography-tokens-for-t/status.yaml b/codev/projects/1053-vscode-typography-tokens-for-t/status.yaml
index 3b93ea61c..6b78f5139 100644
--- a/codev/projects/1053-vscode-typography-tokens-for-t/status.yaml
+++ b/codev/projects/1053-vscode-typography-tokens-for-t/status.yaml
@@ -11,10 +11,11 @@ gates:
     approved_at: '2026-06-17T22:01:29.466Z'
   dev-approval:
     status: pending
+    requested_at: '2026-06-17T22:09:23.451Z'
   pr:
     status: pending
 iteration: 1
 build_complete: false
 history: []
 started_at: '2026-06-17T21:50:52.095Z'
-updated_at: '2026-06-17T22:01:38.682Z'
+updated_at: '2026-06-17T22:09:23.452Z'

From 7d35fa0b0322bb1c9bfc6d43a172b0bb209de366 Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Thu, 18 Jun 2026 13:29:03 +1000
Subject: [PATCH 10/27] [PIR #1053] Document markdownPreview
 font-size/line-height settings in README

---
 packages/vscode/README.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/packages/vscode/README.md b/packages/vscode/README.md
index 447295b29..eb860709e 100644
--- a/packages/vscode/README.md
+++ b/packages/vscode/README.md
@@ -215,6 +215,8 @@ When a builder reaches a human-approval gate, a toast surfaces it with the issue
 | `codev.gateToasts.enabled` | `true` | Show a toast when a builder reaches a human-approval gate |
 | `codev.buildersAutoCollapse` | `true` | Builders view accordion — expanding one builder auto-collapses the others |
 | `codev.buildersFileViewAsTree` | `true` | Render a builder's changed-files list as a folder tree (`false` for a flat list) |
+| `codev.markdownPreview.fontSize` | `0` | Prose font size (px) for the Codev Markdown Preview. `0` = built-in default (16px). Edit in Settings (Cmd+,) → the open preview reflows live |
+| `codev.markdownPreview.lineHeight` | `0` | Prose line-height (unitless) for the Codev Markdown Preview. `0` = built-in default (1.5). Reflows the open preview live |
 
 ## Advanced
 

From 108d24b82ab25842896b8144d775b24fb4866a34 Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Thu, 18 Jun 2026 13:30:12 +1000
Subject: [PATCH 11/27] [PIR #1053] Thread: dev-approval Q&A, settings doc,
 follow-up #1070

---
 codev/state/pir-1053_thread.md | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/codev/state/pir-1053_thread.md b/codev/state/pir-1053_thread.md
index 7e6ad82ff..47ccb687a 100644
--- a/codev/state/pir-1053_thread.md
+++ b/codev/state/pir-1053_thread.md
@@ -37,3 +37,13 @@ Tests: canvas 54/54, vscode 442/442 unit; both typechecks + esbuild bundle clean
 new tokens + prose rules land in the bundled `dist/webview/markdown-preview.css`.
 (Had to build codev-core + codev-types first — they weren't built in the fresh worktree; the
 resolution errors were environmental, not from my diff.)
+
+## dev-approval gate — reviewer Q&A
+
+Reviewer probed the Tier-3 plumbing (config listener, buildUserTypographyOverrides): all of it
+exists only to make the two `codev.markdownPreview.*` settings reflow live. Reviewer confirmed
+Tier 3 is "essential" → KEEP it. Settings are controlled via VSCode's standard Settings editor /
+settings.json only (no in-preview UI).
+- Per reviewer: documented the two settings in `packages/vscode/README.md` Settings table.
+- Per reviewer: filed #1070 (area/vscode) for an in-preview zoom control affordance + write-back
+  (the UI piece, deliberately out of scope here; tokens + settings already shipped by #1053).

From f2c7d609698738c2102b9c8f79b0f5b65279e030 Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Thu, 18 Jun 2026 14:31:56 +1000
Subject: [PATCH 12/27] [PIR #1053] Add code-foreground token + style
 code/blockquote/table/hr/img elements

---
 packages/artifact-canvas/README.md            |  4 +
 .../src/__tests__/default-theme.test.ts       |  6 ++
 .../src/styles/default-theme.css              | 76 +++++++++++++++++--
 packages/artifact-canvas/src/types.ts         |  8 +-
 4 files changed, 86 insertions(+), 8 deletions(-)

diff --git a/packages/artifact-canvas/README.md b/packages/artifact-canvas/README.md
index 5ab556601..bc132c96f 100644
--- a/packages/artifact-canvas/README.md
+++ b/packages/artifact-canvas/README.md
@@ -124,6 +124,7 @@ Import the default stylesheet and override any subset of the `--codev-canvas-*`
 | `--codev-canvas-border` | `#d0d7de` |
 | `--codev-canvas-muted` | `#656d76` |
 | `--codev-canvas-code-background` | `#f6f8fa` |
+| `--codev-canvas-code-foreground` | `#1f2328` |
 | `--codev-canvas-link` | `#0969da` |
 | `--codev-canvas-comment-marker` | `#bf8700` |
 
@@ -150,6 +151,9 @@ v5.8.1 so prose reads cleanly instead of inheriting the host's code-tuned font.
   --codev-canvas-accent: var(--vscode-focusBorder);
   /* Code blocks track the editor font; prose keeps the readable sans stack. */
   --codev-canvas-code-font-family: var(--vscode-editor-font-family);
+  /* Pair inline-code fg+bg from the same theme group so they always contrast. */
+  --codev-canvas-code-background: var(--vscode-textPreformat-background);
+  --codev-canvas-code-foreground: var(--vscode-textPreformat-foreground);
 }
 ```
 
diff --git a/packages/artifact-canvas/src/__tests__/default-theme.test.ts b/packages/artifact-canvas/src/__tests__/default-theme.test.ts
index d9b5da217..d08aec775 100644
--- a/packages/artifact-canvas/src/__tests__/default-theme.test.ts
+++ b/packages/artifact-canvas/src/__tests__/default-theme.test.ts
@@ -36,6 +36,7 @@ describe('default-theme.css token vocabulary', () => {
         "--codev-canvas-code-background",
         "--codev-canvas-code-font-family",
         "--codev-canvas-code-font-size",
+        "--codev-canvas-code-foreground",
         "--codev-canvas-comment-marker",
         "--codev-canvas-font-family",
         "--codev-canvas-font-size",
@@ -70,4 +71,9 @@ describe('default-theme.css token vocabulary', () => {
     expect(tokens.get('--codev-canvas-h6-size')).toBe('0.85em');
     expect(tokens.get('--codev-canvas-code-font-size')).toBe('0.85em');
   });
+
+  it('gives inline code its own foreground token (dark-mode contrast, #1053)', () => {
+    expect(tokens.has('--codev-canvas-code-foreground')).toBe(true);
+    expect(tokens.get('--codev-canvas-code-foreground')).not.toBe('');
+  });
 });
diff --git a/packages/artifact-canvas/src/styles/default-theme.css b/packages/artifact-canvas/src/styles/default-theme.css
index 0bd177126..6404c7b48 100644
--- a/packages/artifact-canvas/src/styles/default-theme.css
+++ b/packages/artifact-canvas/src/styles/default-theme.css
@@ -25,6 +25,10 @@
   --codev-canvas-border: #d0d7de;
   --codev-canvas-muted: #656d76;
   --codev-canvas-code-background: #f6f8fa;
+  /* Inline-code text. Its own token (not the body foreground) so a host can pair it with the
+     code background for guaranteed contrast — body-fg-on-code-bg pairs poorly in some dark
+     themes (#1053). */
+  --codev-canvas-code-foreground: #1f2328;
   --codev-canvas-link: #0969da;
   --codev-canvas-comment-marker: #bf8700;
 
@@ -118,12 +122,76 @@
   font-size: var(--codev-canvas-h6-size);
   color: var(--codev-canvas-muted);
 }
-/* Code: monospace family + ~85% size for both fenced blocks and inline `code`. The background
-   color rule for these lives below with the other color tokens. */
-.codev-artifact-canvas-body pre,
+/* Lists keep a deliberate indent (github uses 2em) rather than the UA default. */
+.codev-artifact-canvas-body ul,
+.codev-artifact-canvas-body ol {
+  padding-left: 2em;
+}
+/* Inline code: a monospace chip with its OWN foreground (paired with the code background) so it
+   stays legible — body-fg-on-code-bg pairs poorly in some dark themes. ~85% of prose size. */
 .codev-artifact-canvas-body code {
   font-family: var(--codev-canvas-code-font-family);
   font-size: var(--codev-canvas-code-font-size);
+  color: var(--codev-canvas-code-foreground);
+  background: var(--codev-canvas-code-background);
+  padding: 0.2em 0.4em;
+  border-radius: 6px;
+}
+/* Fenced code block: padded, rounded, horizontally scrollable, with a hairline for definition. */
+.codev-artifact-canvas-body pre {
+  font-family: var(--codev-canvas-code-font-family);
+  font-size: var(--codev-canvas-code-font-size);
+  background: var(--codev-canvas-code-background);
+  border: 1px solid var(--codev-canvas-border);
+  border-radius: 6px;
+  padding: 16px;
+  overflow: auto;
+}
+/* Code INSIDE a fence is plain text, not a chip: reset the inline chrome — including the 85%
+   size, which would otherwise compound to ~72% on top of pre's own 85%. */
+.codev-artifact-canvas-body pre code {
+  background: transparent;
+  color: inherit;
+  padding: 0;
+  border-radius: 0;
+  font-size: inherit;
+}
+/* Blockquote: muted text behind a left rule (github convention). */
+.codev-artifact-canvas-body blockquote {
+  padding: 0 1em;
+  color: var(--codev-canvas-muted);
+  border-left: 0.25em solid var(--codev-canvas-border);
+}
+/* Tables: collapsed bordered cells with a subtle zebra stripe; the block becomes horizontally
+   scrollable so a wide table can't blow out the prose column. */
+.codev-artifact-canvas-body table {
+  display: block;
+  width: max-content;
+  max-width: 100%;
+  overflow: auto;
+  border-collapse: collapse;
+}
+.codev-artifact-canvas-body th,
+.codev-artifact-canvas-body td {
+  border: 1px solid var(--codev-canvas-border);
+  padding: 6px 13px;
+}
+.codev-artifact-canvas-body th {
+  font-weight: 600;
+}
+.codev-artifact-canvas-body tr:nth-child(2n) {
+  background: var(--codev-canvas-code-background);
+}
+/* Thematic break: a hairline rule, not the UA inset bevel. */
+.codev-artifact-canvas-body hr {
+  height: 0;
+  border: 0;
+  border-top: 1px solid var(--codev-canvas-border);
+  margin: 24px 0;
+}
+/* Images never overflow the prose column. */
+.codev-artifact-canvas-body img {
+  max-width: 100%;
 }
 
 /* Phase 3 — comment overlay + minimal marker rendering */
@@ -155,8 +223,6 @@
   outline-offset: 2px;
 }
 .codev-artifact-canvas-body a { color: var(--codev-canvas-link); }
-.codev-artifact-canvas-body pre,
-.codev-artifact-canvas-body code { background: var(--codev-canvas-code-background); }
 
 /* Overlay: the "+" add-comment affordance only. Anchored to the active block: positioned
    absolutely in the canvas, with `top` set inline to the first line's vertical center; the
diff --git a/packages/artifact-canvas/src/types.ts b/packages/artifact-canvas/src/types.ts
index c89ad6206..3cffe3efc 100644
--- a/packages/artifact-canvas/src/types.ts
+++ b/packages/artifact-canvas/src/types.ts
@@ -7,9 +7,11 @@
  *
  * Contract amendment (#1053): the public `--codev-canvas-*` token vocabulary (spec 945 D4)
  * gained a typography tier — font size/family, line-height, paragraph spacing, an optional
- * prose-width cap, per-level heading sizes, and code font family/size. The tokens are CSS
- * custom properties, not a TypeScript shape, so no interface here changed; the vocabulary and
- * its github-markdown-css baseline are documented in `styles/default-theme.css` and the README.
+ * prose-width cap, per-level heading sizes, and code font family/size — plus one color token,
+ * `--codev-canvas-code-foreground` (inline-code text, paired with the code background for
+ * dark-mode contrast). The tokens are CSS custom properties, not a TypeScript shape, so no
+ * interface here changed; the vocabulary and its github-markdown-css baseline are documented in
+ * `styles/default-theme.css` and the README.
  */
 
 import type { FileAdapter } from './adapters/FileAdapter.js';

From 1bca06f42474eed68ffee7a7fb7ce17296377505 Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Thu, 18 Jun 2026 14:32:01 +1000
Subject: [PATCH 13/27] [PIR #1053] Pair inline code with VSCode textPreformat
 tokens for dark-mode contrast

---
 packages/vscode/src/markdown-preview/preview-template.ts | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/packages/vscode/src/markdown-preview/preview-template.ts b/packages/vscode/src/markdown-preview/preview-template.ts
index 9c4c05ee9..f9009042a 100644
--- a/packages/vscode/src/markdown-preview/preview-template.ts
+++ b/packages/vscode/src/markdown-preview/preview-template.ts
@@ -50,7 +50,12 @@ export function renderMarkdownPreviewHtml(opts: MarkdownPreviewHtmlOptions): str
       --codev-canvas-accent: var(--vscode-textLink-foreground);
       --codev-canvas-border: var(--vscode-panel-border);
       --codev-canvas-muted: var(--vscode-descriptionForeground);
-      --codev-canvas-code-background: var(--vscode-textCodeBlock-background);
+      /* Inline code pairs VS Code's dedicated preformat tokens (foreground + background are
+       * theme-tuned to contrast each other), fixing low-contrast inline code in dark themes
+       * (#1053). textPreformat.* — not textCodeBlock.background + the general foreground, which
+       * pair poorly because they come from different theme color groups. */
+      --codev-canvas-code-background: var(--vscode-textPreformat-background);
+      --codev-canvas-code-foreground: var(--vscode-textPreformat-foreground);
       --codev-canvas-link: var(--vscode-textLink-foreground);
       --codev-canvas-comment-marker: var(--vscode-editorWarning-foreground);
 

From 28ad8a327ef149c887c3bd2dac4d1459fe7b1cc5 Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Thu, 18 Jun 2026 14:32:21 +1000
Subject: [PATCH 14/27] [PIR #1053] Thread: element styling + dark-mode
 contrast pass

---
 codev/state/pir-1053_thread.md | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/codev/state/pir-1053_thread.md b/codev/state/pir-1053_thread.md
index 47ccb687a..789e39b74 100644
--- a/codev/state/pir-1053_thread.md
+++ b/codev/state/pir-1053_thread.md
@@ -47,3 +47,25 @@ settings.json only (no in-preview UI).
 - Per reviewer: documented the two settings in `packages/vscode/README.md` Settings table.
 - Per reviewer: filed #1070 (area/vscode) for an in-preview zoom control affordance + write-back
   (the UI piece, deliberately out of scope here; tokens + settings already shipped by #1053).
+
+## dev-approval round 2 — element styling + dark-mode contrast fix
+
+Reviewer flagged poor inline-code contrast in dark mode. Root cause: `code` had a background
+token but NO foreground token, so its text fell through to the body foreground — and the host
+paired `textCodeBlock.background` (a code-BLOCK token) with the general foreground (a different
+theme color group), which pairs poorly in dark themes. Reviewer: "must fix properly now, what
+other rules / styling issues still need to be handled" → did a full element pass.
+
+Fixes (now 22 tokens: +`--codev-canvas-code-foreground`):
+- New `--codev-canvas-code-foreground` color token; host binds inline code to VSCode's
+  `textPreformat-foreground/background` pair (theme-tuned to contrast each other).
+- Inline `code`: chip padding + radius + its own fg/bg.
+- `pre`: padding, border, radius, overflow:auto. `pre code` resets the chip chrome INCLUDING
+  font-size (was compounding 0.85em × 0.85em ≈ 72%).
+- `blockquote` (muted + left rule), tables (collapsed borders, zebra, scrollable), `hr`
+  (hairline), `img` (max-width:100%), list indent (2em).
+- Doc trail updated: README color table + binding example, types.ts contract comment.
+- New test: inline-code-foreground token present.
+
+Tests: canvas 55/55, vscode 442/442; typechecks + bundle clean; verified new rules land in
+bundled webview CSS.

From 001ca84721fd2c992df10346ed57a9b2ff2b982b Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Thu, 18 Jun 2026 14:35:31 +1000
Subject: [PATCH 15/27] [PIR #1053] Break long tokens in prose to prevent
 page-level horizontal scroll

---
 packages/artifact-canvas/src/styles/default-theme.css | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/packages/artifact-canvas/src/styles/default-theme.css b/packages/artifact-canvas/src/styles/default-theme.css
index 6404c7b48..e06e9304a 100644
--- a/packages/artifact-canvas/src/styles/default-theme.css
+++ b/packages/artifact-canvas/src/styles/default-theme.css
@@ -77,6 +77,11 @@
   /* Optional readable-measure cap (off by default — token is `none`). When a host/user sets a
      width (e.g. 72ch) the prose column stops growing with the pane. */
   max-width: var(--codev-canvas-prose-max-width);
+  /* Break long unbreakable tokens (a long inline-code span, URL, or file path) instead of
+     letting them overflow the column and force a page-level horizontal scrollbar. `pre` and
+     `table` opt out via their own `overflow: auto` — code lines and wide tables scroll inside
+     their block by design, they don't wrap (#1053). */
+  overflow-wrap: break-word;
 }
 
 /*

From 91a8916787616c32cd7cfd6806caa668fad42cab Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Thu, 18 Jun 2026 14:35:46 +1000
Subject: [PATCH 16/27] [PIR #1053] Thread: horizontal-scroll wrapping fix

---
 codev/state/pir-1053_thread.md | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/codev/state/pir-1053_thread.md b/codev/state/pir-1053_thread.md
index 789e39b74..deefa0eb3 100644
--- a/codev/state/pir-1053_thread.md
+++ b/codev/state/pir-1053_thread.md
@@ -69,3 +69,12 @@ Fixes (now 22 tokens: +`--codev-canvas-code-foreground`):
 
 Tests: canvas 55/55, vscode 442/442; typechecks + bundle clean; verified new rules land in
 bundled webview CSS.
+
+## dev-approval round 3 — horizontal scroll
+
+Reviewer asked how line wrapping works / why a horizontal scrollbar sometimes appears. Two kinds:
+(1) intentional per-block scroll on `pre` (long code lines) + `table` (wide tables) via their own
+`overflow:auto` — correct, github-style; (2) the bug: prose had no rule to break a long
+UNbreakable token (long inline-code span, URL, file path), so it overflowed the column and forced
+a PAGE-level scrollbar. Fix: `overflow-wrap: break-word` on `.codev-artifact-canvas-body`
+(github-markdown-css's own approach); `pre`/`table` opt out by design. Verified in both bundles.

From 497dcc7ef1d28620329735a5028d097a4a4fb5dd Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Thu, 18 Jun 2026 14:37:07 +1000
Subject: [PATCH 17/27] chore(porch): 1053 dev-approval gate-approved

---
 .../projects/1053-vscode-typography-tokens-for-t/status.yaml | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/codev/projects/1053-vscode-typography-tokens-for-t/status.yaml b/codev/projects/1053-vscode-typography-tokens-for-t/status.yaml
index 6b78f5139..0b59b0894 100644
--- a/codev/projects/1053-vscode-typography-tokens-for-t/status.yaml
+++ b/codev/projects/1053-vscode-typography-tokens-for-t/status.yaml
@@ -10,12 +10,13 @@ gates:
     requested_at: '2026-06-17T21:54:25.731Z'
     approved_at: '2026-06-17T22:01:29.466Z'
   dev-approval:
-    status: pending
+    status: approved
     requested_at: '2026-06-17T22:09:23.451Z'
+    approved_at: '2026-06-18T04:37:07.103Z'
   pr:
     status: pending
 iteration: 1
 build_complete: false
 history: []
 started_at: '2026-06-17T21:50:52.095Z'
-updated_at: '2026-06-17T22:09:23.452Z'
+updated_at: '2026-06-18T04:37:07.104Z'

From a3d745d09846baa28f7d0a679302b36c27732169 Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Thu, 18 Jun 2026 14:37:16 +1000
Subject: [PATCH 18/27] chore(porch): 1053 review phase-transition

---
 .../projects/1053-vscode-typography-tokens-for-t/status.yaml  | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/codev/projects/1053-vscode-typography-tokens-for-t/status.yaml b/codev/projects/1053-vscode-typography-tokens-for-t/status.yaml
index 0b59b0894..f8eeb779e 100644
--- a/codev/projects/1053-vscode-typography-tokens-for-t/status.yaml
+++ b/codev/projects/1053-vscode-typography-tokens-for-t/status.yaml
@@ -1,7 +1,7 @@
 id: '1053'
 title: vscode-typography-tokens-for-t
 protocol: pir
-phase: implement
+phase: review
 plan_phases: []
 current_plan_phase: null
 gates:
@@ -19,4 +19,4 @@ iteration: 1
 build_complete: false
 history: []
 started_at: '2026-06-17T21:50:52.095Z'
-updated_at: '2026-06-18T04:37:07.104Z'
+updated_at: '2026-06-18T04:37:16.353Z'

From e4d0c0e91445996573e57e14edf9393d2cb4699b Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Thu, 18 Jun 2026 14:39:23 +1000
Subject: [PATCH 19/27] [PIR #1053] Review: retrospective + 3 UI/UX lessons

---
 codev/resources/lessons-learned.md            |   3 +
 .../1053-vscode-typography-tokens-for-t.md    | 134 ++++++++++++++++++
 2 files changed, 137 insertions(+)
 create mode 100644 codev/reviews/1053-vscode-typography-tokens-for-t.md

diff --git a/codev/resources/lessons-learned.md b/codev/resources/lessons-learned.md
index d4ea76401..b51a064f4 100644
--- a/codev/resources/lessons-learned.md
+++ b/codev/resources/lessons-learned.md
@@ -325,6 +325,9 @@ Generalizable wisdom extracted from review documents, ordered by impact. Updated
 - [From #789] Don't add a "performance" cache before confirming the hot path. A per-version document-symbol cache was added to fix a ~100% CPU spike, but the spike was an unrelated newly-installed extension (the **Extension Test Runner**) walking the `.builders/` worktree farm (`rg --no-ignore --follow` over pnpm symlinks) — the extension-host CPU profile was ~99% idle. `provideCodeLenses` is not a hot path (VSCode caches lenses and only re-queries on invalidation), so the cache bought nothing and risked pinning an empty result when the language server was still warming up on first open. Profile first; cache only a proven-hot, proven-pure path.
 - [From #1060] To programmatically navigate/reveal a file inside VSCode's multi-file diff editor, the public `vscode.changes` command is a dead end: it synthesizes a **random** source URI (`multi-diff-editor:${ms+Math.random()}`), so you can't re-address that editor afterward, and there's no public file-granular nav (`multiDiffEditor.goToNextChange` is *hunk*-granular). The only programmatic reveal is the internal `_workbench.openMultiDiffEditor({ multiDiffSourceUri, resources, reveal:{modifiedUri} })` with a deterministic source URI. But the cheaper, more robust design (chosen here) sidesteps multi-diff internals entirely: reuse the **already-built changed-file list** (the `BuilderDiffCache` that backs the sidebar) and open each file as a per-file `vscode.diff`, resolving "current file" from `activeTextEditor` via the diff-inject registry. Before reaching for an internal `_workbench.*` command, check whether an existing list + the per-file diff surface already gives you what you need.
 - [From #1060] VSCode preview tabs (`TextDocumentShowOptions.preview: true`) are "replaced and reused until set to stay," so a file-walk reuses one tab instead of piling up N — but the flag is **ignored when the user disabled preview editors** (`workbench.editor.enablePreview: false`). Pass `preview: true` for sequential-open UX and respect the user's global setting rather than force-closing tabs yourself. Scope a navigation keybinding to the **feature-specific** context key (`codev.activeEditorIsBuilderFile`), not the generic `isInDiffEditor`: the broad key would fire the command in unrelated diffs where it falls back to stale state and acts on the wrong target.
+- [From #1053] A **`background` design token without a matching `foreground` token is a latent contrast bug.** Inline code shipped with `--codev-canvas-code-background` but no foreground token, so its text fell through to the *general* body foreground; the VSCode host then paired a code-*block* background token (`textCodeBlock.background`) with the general `foreground` — two different theme color groups with no contract that they contrast — and dark themes rendered low-contrast inline code. Model surface fg/bg as a **pair** and bind both from the same theme group (`textPreformat-foreground`/`textPreformat-background`, which the theme tunes to contrast). When you add a background token for a surface, add and bind its foreground in the same change.
+- [From #1053] When styling rendered markdown, **prose and code want opposite overflow behavior.** Long unbreakable tokens in prose (a long inline-code span, URL, or file path) overflow the column and force a *page-level* horizontal scrollbar unless you set `overflow-wrap: break-word` on the prose container — but `pre` and `table` must NOT wrap (wrapping code corrupts it; a wide table shouldn't reflow), so they opt out with their own `overflow: auto` to scroll *within their block*. The correct outcome is: prose never causes page scroll; code/tables scroll locally. (github-markdown-css uses exactly this split.)
+- [From #1053] Watch `em`-on-`em` compounding when sizing nested rendered elements. Sizing both `pre` and `code` to `0.85em` made fenced code (`pre code`) ~72% (0.85 × 0.85); the fix is to size the chip (`code`) and the block (`pre`) but **reset the inner `pre code` to `font-size: inherit`** (plus reset its chip background/padding, since code inside a fence is plain text, not an inline chip). Anchor `em` chains to a single px root and reset where they'd stack.
 
 ## Documentation
 
diff --git a/codev/reviews/1053-vscode-typography-tokens-for-t.md b/codev/reviews/1053-vscode-typography-tokens-for-t.md
new file mode 100644
index 000000000..a2f3c5a11
--- /dev/null
+++ b/codev/reviews/1053-vscode-typography-tokens-for-t.md
@@ -0,0 +1,134 @@
+# PIR Review: Typography tokens for the Codev Markdown Preview (artifact canvas)
+
+> Issue #1053 · area/vscode · Fixes #1053
+
+## Summary
+
+The Codev Markdown Preview (`@cluesmith/codev-artifact-canvas` mounted by `MarkdownPreviewProvider`)
+inherited the host's code-tuned typography: prose rendered at the workbench UI font with a tight
+line-height and no paragraph rhythm, heading scale, or prose-element styling. Spec 945 D4 had
+deliberately capped the v1 `--codev-canvas-*` vocabulary at colors, so there was no lever for any
+of it.
+
+This PR extends the canvas theming contract with a **typography token tier** (github-markdown-css
+v5.8.1 as the pinned baseline) and wires it through the VSCode host, in three tiers:
+
+1. **Package tokens + element styling** (`default-theme.css`) — 13 typography tokens (font
+   size/family, line-height, paragraph spacing, optional prose-width cap, per-level heading sizes,
+   code font family/size) plus the CSS rules that consume them. The element pass also styled the
+   block elements that were falling through to user-agent defaults: inline `code` chips, fenced
+   `pre`, blockquotes, tables, `hr`, images, and list indentation.
+2. **Host mapping** (`preview-template.ts`) — binds code to the editor font while prose keeps the
+   readable sans stack, and pairs inline code with VSCode's theme-tuned `textPreformat-*` tokens.
+3. **User settings** (`package.json` + `preview-provider.ts`) — `codev.markdownPreview.fontSize`
+   and `.lineHeight`, with live reflow on change.
+
+Two color/layout correctness fixes landed during dev-approval review (see Lessons Learned): a
+dark-mode inline-code contrast bug, and a page-level horizontal-scroll bug from unbreakable long
+tokens.
+
+The token vocabulary is a "locked public contract" (spec 945 D4), so the expansion carries a
+spec-amendment doc trail across `types.ts`, the package README, this review, and the issue.
+
+## Architecture Updates
+
+No changes needed to `arch.md` / `arch-critical.md`. This PR extends an existing, documented
+subsystem (the spec-945 canvas theming contract) along the seam it was designed to extend — CSS
+custom properties overridden by the host. It introduces no new module, process boundary, state
+store, or invariant. The canvas's Model-A theming (CSS variables, not JS `resolve()`) is unchanged;
+only the token *vocabulary* grew, which is documented in the package itself (`default-theme.css`,
+README) and in the `types.ts` contract comment, the correct homes for it.
+
+## Lessons Learned Updates
+
+No changes needed to the HOT `lessons-critical.md` (it is capped and these are domain-specific, not
+high-blast-radius cross-cutting rules). Three reusable lessons are recorded in the COLD
+`lessons-learned.md` under **UI/UX** (added in this PR):
+
+- **A `background` token without a matching `foreground` token is a latent contrast bug.** Inline
+  code shipped (pre-#1053) with a background token but no foreground token, so its text fell through
+  to the *general* body foreground; the host then paired a code-*block* background with the general
+  foreground (different theme color groups, no contract that they contrast), and dark themes
+  rendered low-contrast inline code. Model surface fg/bg as a **pair** bound from the same theme
+  group; add the foreground in the same change as the background.
+- **Prose and code want opposite overflow behavior.** Long unbreakable tokens in prose force a
+  *page-level* horizontal scrollbar unless the prose container sets `overflow-wrap: break-word`;
+  `pre`/`table` must not wrap and opt out via their own `overflow: auto` to scroll within the block.
+- **Watch `em`-on-`em` compounding when nesting sized elements.** Sizing both `pre` and `code` to
+  `0.85em` made fenced `pre code` ~72%; reset the inner `pre code` to `font-size: inherit` (and its
+  chip chrome) since code inside a fence is plain text, not an inline chip.
+
+(All three recorded in `codev/resources/lessons-learned.md` under UI/UX.)
+
+## Files Changed
+
+| File | Change |
+|---|---|
+| `packages/artifact-canvas/src/styles/default-theme.css` | +13 typography tokens, +1 color token (`code-foreground`); prose/heading/code/blockquote/table/hr/img rules; `overflow-wrap` wrap fix |
+| `packages/artifact-canvas/src/types.ts` | D4 contract-amendment comment (typography tier + code-foreground) |
+| `packages/artifact-canvas/README.md` | color + typography token tables; VSCode binding example; github-markdown-css v5.8.1 pin |
+| `packages/artifact-canvas/src/__tests__/default-theme.test.ts` | new — token-vocabulary inline snapshot + default + contrast-token assertions |
+| `packages/vscode/src/markdown-preview/preview-template.ts` | Tier-2 token bindings (code→editor font, prose→sans; inline code→`textPreformat-*`); Tier-3 user-override emission |
+| `packages/vscode/src/markdown-preview/preview-provider.ts` | read `codev.markdownPreview.*`; live reflow via `onDidChangeConfiguration` |
+| `packages/vscode/package.json` | register `codev.markdownPreview.fontSize` / `.lineHeight` |
+| `packages/vscode/README.md` | document the two settings |
+
+## Commits
+
+- `[PIR #1053] Add typography token tier to canvas default-theme.css`
+- `[PIR #1053] Bind typography tokens in VSCode preview + add font-size/line-height settings`
+- `[PIR #1053] Document markdownPreview font-size/line-height settings in README`
+- `[PIR #1053] Add code-foreground token + style code/blockquote/table/hr/img elements`
+- `[PIR #1053] Pair inline code with VSCode textPreformat tokens for dark-mode contrast`
+- `[PIR #1053] Break long tokens in prose to prevent page-level horizontal scroll`
+
+(Plus thread-log commits.)
+
+## Test Results
+
+- `pnpm --filter @cluesmith/codev-artifact-canvas test` — **55 passed** (incl. the new
+  `default-theme.test.ts` token-vocabulary snapshot + contrast-token assertion).
+- `pnpm --filter codev-vscode test:unit` — **442 passed**.
+- `pnpm --filter @cluesmith/codev-artifact-canvas build`, vscode `check-types` (host + webview
+  tsconfigs) and the esbuild production bundle — all clean.
+- Verified the typography tokens, prose/element rules, `code-foreground`, and `overflow-wrap` all
+  land in the bundled `packages/vscode/dist/webview/markdown-preview.css`.
+- Manual (dev-approval): readability before/after on a long spec, dark-mode inline-code contrast,
+  pane resize / no page-level horizontal scroll, per-block scroll on `pre`/tables, and live reflow
+  of the two settings.
+
+## Decisions Locked (at plan-approval, confirmed through dev-approval)
+
+1. **Token list** — 13 typography + 1 color (`code-foreground`, added during review) = 22 total.
+2. **Heading granularity** — per-level tokens (`h1-size`…`h6-size`), not scale+ratio:
+   github-markdown-css's scale is non-geometric and a single ratio can't reproduce it.
+3. **Prose vs editor font** — prose overrides the editor font (github sans, 16px/1.5); code tracks
+   the editor font. Baseline pinned to **github-markdown-css v5.8.1**.
+4. **`prose-max-width`** — ships `none` (no cap); opt-in to e.g. `72ch`.
+5. **Tier 3** — included (confirmed essential by the reviewer); two settings only.
+
+## Things to Look At
+
+- The prose/code font split (`preview-template.ts`): code tracks the editor font, prose uses the
+  github sans stack. Documented inline so a future maintainer doesn't rebind prose to the editor
+  font (the cramped baseline this surface fixes).
+- The two horizontal-scroll behaviors are intentionally different: `pre` + `table` scroll *within
+  their block* (long code lines / wide tables shouldn't wrap); prose breaks long tokens
+  (`overflow-wrap`) so it never forces a *page-level* scrollbar.
+
+## Follow-ups
+
+- **#1070** (area/vscode) — in-preview typography controls (zoom buttons / command + write-back).
+  The tokens and the two settings shipped here; #1070 is purely the in-surface UI affordance,
+  deliberately out of this PR's scope.
+
+## How to Test Locally
+
+1. `afx dev pir-1053` (or VSCode → right-click builder → Run Dev Server).
+2. Open a long spec/plan/review in the Codev Markdown Preview (e.g.
+   `codev/specs/945-build-foundational-reusable-pa.md`).
+3. Confirm prose reads at 16px / 1.5 with paragraph spacing and a deliberate heading scale; code
+   blocks are monospace + track the editor font; inline code is legible in both light and dark
+   themes; tables/blockquotes/hr render deliberately.
+4. Resize the pane — no page-level horizontal scrollbar; `pre`/tables scroll within their block.
+5. Change `codev.markdownPreview.fontSize` / `.lineHeight` in Settings — the open preview reflows.

From 2663102ee0c1c9cc25016a68d9f012bcb95a869e Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Thu, 18 Jun 2026 14:39:43 +1000
Subject: [PATCH 20/27] chore(porch): 1053 record PR #1071

---
 .../1053-vscode-typography-tokens-for-t/status.yaml        | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/codev/projects/1053-vscode-typography-tokens-for-t/status.yaml b/codev/projects/1053-vscode-typography-tokens-for-t/status.yaml
index f8eeb779e..fe809bff4 100644
--- a/codev/projects/1053-vscode-typography-tokens-for-t/status.yaml
+++ b/codev/projects/1053-vscode-typography-tokens-for-t/status.yaml
@@ -19,4 +19,9 @@ iteration: 1
 build_complete: false
 history: []
 started_at: '2026-06-17T21:50:52.095Z'
-updated_at: '2026-06-18T04:37:16.353Z'
+updated_at: '2026-06-18T04:39:43.194Z'
+pr_history:
+  - phase: review
+    pr_number: 1071
+    branch: builder/pir-1053
+    created_at: '2026-06-18T04:39:43.192Z'

From d2eb2acb723e016b56b1e70a98662565b1dca121 Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Thu, 18 Jun 2026 14:40:13 +1000
Subject: [PATCH 21/27] chore(porch): 1053 review build-complete

---
 .../projects/1053-vscode-typography-tokens-for-t/status.yaml  | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/codev/projects/1053-vscode-typography-tokens-for-t/status.yaml b/codev/projects/1053-vscode-typography-tokens-for-t/status.yaml
index fe809bff4..4a08390b1 100644
--- a/codev/projects/1053-vscode-typography-tokens-for-t/status.yaml
+++ b/codev/projects/1053-vscode-typography-tokens-for-t/status.yaml
@@ -16,10 +16,10 @@ gates:
   pr:
     status: pending
 iteration: 1
-build_complete: false
+build_complete: true
 history: []
 started_at: '2026-06-17T21:50:52.095Z'
-updated_at: '2026-06-18T04:39:43.194Z'
+updated_at: '2026-06-18T04:40:13.041Z'
 pr_history:
   - phase: review
     pr_number: 1071

From 3ce89195de5a97eaea8a53cfad81ca7a04880ba3 Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Thu, 18 Jun 2026 14:41:21 +1000
Subject: [PATCH 22/27] [PIR #1053] Thread: review phase, PR #1071, consult
 running

---
 codev/state/pir-1053_thread.md | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/codev/state/pir-1053_thread.md b/codev/state/pir-1053_thread.md
index deefa0eb3..79e459e5d 100644
--- a/codev/state/pir-1053_thread.md
+++ b/codev/state/pir-1053_thread.md
@@ -78,3 +78,12 @@ Reviewer asked how line wrapping works / why a horizontal scrollbar sometimes ap
 UNbreakable token (long inline-code span, URL, file path), so it overflowed the column and forced
 a PAGE-level scrollbar. Fix: `overflow-wrap: break-word` on `.codev-artifact-canvas-body`
 (github-markdown-css's own approach); `pre`/`table` opt out by design. Verified in both bundles.
+
+## Review phase — PR #1071 open, 3-way consult running
+
+dev-approval approved. Wrote `codev/reviews/1053-vscode-typography-tokens-for-t.md` (Summary +
+Architecture Updates [none — extends existing canvas theming seam] + 3 UI/UX lessons added to
+COLD lessons-learned.md: bg-without-fg contrast bug, prose-vs-code overflow split, em-on-em
+compounding). PR #1071 opened with review as body, recorded via `porch done --pr 1071`.
+Checks passed. 3-way consult (gemini/codex/claude, type=impl, single advisory pass) running in
+background. Then notify architect + wait at `pr` gate.

From 193a5a279f50b4325e58336469f8b8598d64dd39 Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Thu, 18 Jun 2026 14:50:21 +1000
Subject: [PATCH 23/27] [PIR #1053] Cover standalone MarkdownView surface with
 typography (consult fix)

---
 .../src/__tests__/default-theme.test.ts       |  20 ++++
 .../src/styles/default-theme.css              | 102 ++++++++++--------
 2 files changed, 79 insertions(+), 43 deletions(-)

diff --git a/packages/artifact-canvas/src/__tests__/default-theme.test.ts b/packages/artifact-canvas/src/__tests__/default-theme.test.ts
index d08aec775..b90b0d689 100644
--- a/packages/artifact-canvas/src/__tests__/default-theme.test.ts
+++ b/packages/artifact-canvas/src/__tests__/default-theme.test.ts
@@ -76,4 +76,24 @@ describe('default-theme.css token vocabulary', () => {
     expect(tokens.has('--codev-canvas-code-foreground')).toBe(true);
     expect(tokens.get('--codev-canvas-code-foreground')).not.toBe('');
   });
+
+  it('covers the standalone MarkdownView root, not just the composed canvas (#1053)', () => {
+    // MarkdownView renders `.codev-artifact-canvas-rendered` with no `.codev-artifact-canvas`
+    // ancestor, so the typography must name that root explicitly or the exported standalone
+    // surface gets no prose styling (consult REQUEST_CHANGES, #1053). Guard both halves:
+    // (1) the token + base-font block names the standalone root, and
+    // (2) the prose element rules name it too (via the `:is(...)` container group).
+    expect(css).toMatch(/\.codev-artifact-canvas,\s*\.codev-artifact-canvas-rendered\s*\{/);
+    // Every prose element rule shares the `:is(body, rendered)` container group. Assert the
+    // standalone root appears in a representative prose selector (headings) and the code chip.
+    expect(css).toMatch(
+      /:is\(\.codev-artifact-canvas-body,\s*\.codev-artifact-canvas-rendered\)\s+h1\b/,
+    );
+    expect(css).toMatch(
+      /:is\(\.codev-artifact-canvas-body,\s*\.codev-artifact-canvas-rendered\)\s+code\b/,
+    );
+    // The overlay gutter stays composed-surface-only (MarkdownView has no overlay): the bare
+    // `.codev-artifact-canvas-body` padding rule must NOT pull in the standalone root.
+    expect(css).toMatch(/^\.codev-artifact-canvas-body\s*\{[^}]*padding-left/m);
+  });
 });
diff --git a/packages/artifact-canvas/src/styles/default-theme.css b/packages/artifact-canvas/src/styles/default-theme.css
index e06e9304a..54d5d189f 100644
--- a/packages/artifact-canvas/src/styles/default-theme.css
+++ b/packages/artifact-canvas/src/styles/default-theme.css
@@ -17,7 +17,15 @@
  *   import '@cluesmith/codev-artifact-canvas/default-theme.css';
  */
 
-.codev-artifact-canvas {
+/*
+ * Token vocabulary + base prose styles apply to BOTH render surfaces: the composed
+ * `.codev-artifact-canvas` (ArtifactCanvas → `.codev-artifact-canvas-body`) and the standalone
+ * exported `.codev-artifact-canvas-rendered` (MarkdownView). The standalone root is NOT nested
+ * inside `.codev-artifact-canvas`, so it would inherit neither the tokens nor the base font
+ * unless it's named here too (#1053).
+ */
+.codev-artifact-canvas,
+.codev-artifact-canvas-rendered {
   /* v1 color token vocabulary (spec 945 D4) */
   --codev-canvas-foreground: #1f2328;
   --codev-canvas-background: #ffffff;
@@ -67,13 +75,28 @@
   font-family: var(--codev-canvas-font-family);
   font-size: var(--codev-canvas-font-size);
   line-height: var(--codev-canvas-line-height);
-  /* Positioning context for the comment overlay, which anchors to the active block. */
+}
+
+/* Positioning context for the comment overlay (composed surface only — MarkdownView has none). */
+.codev-artifact-canvas {
   position: relative;
 }
 
-/* Left gutter so the anchored "+" affordance sits beside a block, not over its text. */
+/* Left gutter so the anchored "+" affordance sits beside a block, not over its text. Composed
+   surface only — the gutter exists for the overlay, which MarkdownView doesn't render. */
 .codev-artifact-canvas-body {
   padding-left: 1.9rem;
+}
+
+/*
+ * Prose typography (#1053). Targets BOTH prose containers via `:is(...)` — the composed
+ * `.codev-artifact-canvas-body` and the standalone `.codev-artifact-canvas-rendered`
+ * (MarkdownView) — so the exported standalone surface gets the same prose styling. The comment
+ * cards, overlay `+`, and minimap chrome live OUTSIDE these containers, so they're untouched.
+ * Sizes are `em`-relative to the body font-size (a single px anchor), matching how
+ * github-markdown-css avoids compounding nested `em` chains.
+ */
+:is(.codev-artifact-canvas-body, .codev-artifact-canvas-rendered) {
   /* Optional readable-measure cap (off by default — token is `none`). When a host/user sets a
      width (e.g. 72ch) the prose column stops growing with the pane. */
   max-width: var(--codev-canvas-prose-max-width);
@@ -83,58 +106,51 @@
      their block by design, they don't wrap (#1053). */
   overflow-wrap: break-word;
 }
-
-/*
- * Prose typography (#1053). Scoped to the rendered body so it styles the markdown content
- * without touching the comment cards, overlay `+`, or minimap chrome (each self-sized below).
- * Sizes are `em`-relative to the body font-size (a single px anchor), matching how
- * github-markdown-css avoids compounding nested `em` chains.
- */
-.codev-artifact-canvas-body p {
+:is(.codev-artifact-canvas-body, .codev-artifact-canvas-rendered) p {
   margin: 0 0 var(--codev-canvas-paragraph-spacing);
 }
 /* Derive list / blockquote / table / pre rhythm from the paragraph-spacing token so block
    spacing stays consistent when a host retunes it. */
-.codev-artifact-canvas-body ul,
-.codev-artifact-canvas-body ol,
-.codev-artifact-canvas-body blockquote,
-.codev-artifact-canvas-body table,
-.codev-artifact-canvas-body pre {
+:is(.codev-artifact-canvas-body, .codev-artifact-canvas-rendered) ul,
+:is(.codev-artifact-canvas-body, .codev-artifact-canvas-rendered) ol,
+:is(.codev-artifact-canvas-body, .codev-artifact-canvas-rendered) blockquote,
+:is(.codev-artifact-canvas-body, .codev-artifact-canvas-rendered) table,
+:is(.codev-artifact-canvas-body, .codev-artifact-canvas-rendered) pre {
   margin: 0 0 var(--codev-canvas-paragraph-spacing);
 }
 /* Don't add trailing space below the final block — it reads as an unbalanced gap. */
-.codev-artifact-canvas-body > *:last-child {
+:is(.codev-artifact-canvas-body, .codev-artifact-canvas-rendered) > *:last-child {
   margin-bottom: 0;
 }
 /* Headings: a deliberate per-level scale plus github's heading rhythm (tighter line-height,
    24px top / 16px bottom, semibold) so headings don't fall through to user-agent defaults. */
-.codev-artifact-canvas-body h1,
-.codev-artifact-canvas-body h2,
-.codev-artifact-canvas-body h3,
-.codev-artifact-canvas-body h4,
-.codev-artifact-canvas-body h5,
-.codev-artifact-canvas-body h6 {
+:is(.codev-artifact-canvas-body, .codev-artifact-canvas-rendered) h1,
+:is(.codev-artifact-canvas-body, .codev-artifact-canvas-rendered) h2,
+:is(.codev-artifact-canvas-body, .codev-artifact-canvas-rendered) h3,
+:is(.codev-artifact-canvas-body, .codev-artifact-canvas-rendered) h4,
+:is(.codev-artifact-canvas-body, .codev-artifact-canvas-rendered) h5,
+:is(.codev-artifact-canvas-body, .codev-artifact-canvas-rendered) h6 {
   margin: 24px 0 16px;
   line-height: 1.25;
   font-weight: 600;
 }
-.codev-artifact-canvas-body h1 { font-size: var(--codev-canvas-h1-size); }
-.codev-artifact-canvas-body h2 { font-size: var(--codev-canvas-h2-size); }
-.codev-artifact-canvas-body h3 { font-size: var(--codev-canvas-h3-size); }
-.codev-artifact-canvas-body h4 { font-size: var(--codev-canvas-h4-size); }
-.codev-artifact-canvas-body h5 { font-size: var(--codev-canvas-h5-size); }
-.codev-artifact-canvas-body h6 {
+:is(.codev-artifact-canvas-body, .codev-artifact-canvas-rendered) h1 { font-size: var(--codev-canvas-h1-size); }
+:is(.codev-artifact-canvas-body, .codev-artifact-canvas-rendered) h2 { font-size: var(--codev-canvas-h2-size); }
+:is(.codev-artifact-canvas-body, .codev-artifact-canvas-rendered) h3 { font-size: var(--codev-canvas-h3-size); }
+:is(.codev-artifact-canvas-body, .codev-artifact-canvas-rendered) h4 { font-size: var(--codev-canvas-h4-size); }
+:is(.codev-artifact-canvas-body, .codev-artifact-canvas-rendered) h5 { font-size: var(--codev-canvas-h5-size); }
+:is(.codev-artifact-canvas-body, .codev-artifact-canvas-rendered) h6 {
   font-size: var(--codev-canvas-h6-size);
   color: var(--codev-canvas-muted);
 }
 /* Lists keep a deliberate indent (github uses 2em) rather than the UA default. */
-.codev-artifact-canvas-body ul,
-.codev-artifact-canvas-body ol {
+:is(.codev-artifact-canvas-body, .codev-artifact-canvas-rendered) ul,
+:is(.codev-artifact-canvas-body, .codev-artifact-canvas-rendered) ol {
   padding-left: 2em;
 }
 /* Inline code: a monospace chip with its OWN foreground (paired with the code background) so it
    stays legible — body-fg-on-code-bg pairs poorly in some dark themes. ~85% of prose size. */
-.codev-artifact-canvas-body code {
+:is(.codev-artifact-canvas-body, .codev-artifact-canvas-rendered) code {
   font-family: var(--codev-canvas-code-font-family);
   font-size: var(--codev-canvas-code-font-size);
   color: var(--codev-canvas-code-foreground);
@@ -143,7 +159,7 @@
   border-radius: 6px;
 }
 /* Fenced code block: padded, rounded, horizontally scrollable, with a hairline for definition. */
-.codev-artifact-canvas-body pre {
+:is(.codev-artifact-canvas-body, .codev-artifact-canvas-rendered) pre {
   font-family: var(--codev-canvas-code-font-family);
   font-size: var(--codev-canvas-code-font-size);
   background: var(--codev-canvas-code-background);
@@ -154,7 +170,7 @@
 }
 /* Code INSIDE a fence is plain text, not a chip: reset the inline chrome — including the 85%
    size, which would otherwise compound to ~72% on top of pre's own 85%. */
-.codev-artifact-canvas-body pre code {
+:is(.codev-artifact-canvas-body, .codev-artifact-canvas-rendered) pre code {
   background: transparent;
   color: inherit;
   padding: 0;
@@ -162,40 +178,40 @@
   font-size: inherit;
 }
 /* Blockquote: muted text behind a left rule (github convention). */
-.codev-artifact-canvas-body blockquote {
+:is(.codev-artifact-canvas-body, .codev-artifact-canvas-rendered) blockquote {
   padding: 0 1em;
   color: var(--codev-canvas-muted);
   border-left: 0.25em solid var(--codev-canvas-border);
 }
 /* Tables: collapsed bordered cells with a subtle zebra stripe; the block becomes horizontally
    scrollable so a wide table can't blow out the prose column. */
-.codev-artifact-canvas-body table {
+:is(.codev-artifact-canvas-body, .codev-artifact-canvas-rendered) table {
   display: block;
   width: max-content;
   max-width: 100%;
   overflow: auto;
   border-collapse: collapse;
 }
-.codev-artifact-canvas-body th,
-.codev-artifact-canvas-body td {
+:is(.codev-artifact-canvas-body, .codev-artifact-canvas-rendered) th,
+:is(.codev-artifact-canvas-body, .codev-artifact-canvas-rendered) td {
   border: 1px solid var(--codev-canvas-border);
   padding: 6px 13px;
 }
-.codev-artifact-canvas-body th {
+:is(.codev-artifact-canvas-body, .codev-artifact-canvas-rendered) th {
   font-weight: 600;
 }
-.codev-artifact-canvas-body tr:nth-child(2n) {
+:is(.codev-artifact-canvas-body, .codev-artifact-canvas-rendered) tr:nth-child(2n) {
   background: var(--codev-canvas-code-background);
 }
 /* Thematic break: a hairline rule, not the UA inset bevel. */
-.codev-artifact-canvas-body hr {
+:is(.codev-artifact-canvas-body, .codev-artifact-canvas-rendered) hr {
   height: 0;
   border: 0;
   border-top: 1px solid var(--codev-canvas-border);
   margin: 24px 0;
 }
 /* Images never overflow the prose column. */
-.codev-artifact-canvas-body img {
+:is(.codev-artifact-canvas-body, .codev-artifact-canvas-rendered) img {
   max-width: 100%;
 }
 
@@ -227,7 +243,7 @@
   outline: 2px solid var(--codev-canvas-accent);
   outline-offset: 2px;
 }
-.codev-artifact-canvas-body a { color: var(--codev-canvas-link); }
+:is(.codev-artifact-canvas-body, .codev-artifact-canvas-rendered) a { color: var(--codev-canvas-link); }
 
 /* Overlay: the "+" add-comment affordance only. Anchored to the active block: positioned
    absolutely in the canvas, with `top` set inline to the first line's vertical center; the

From 596e56ff20baa3ceb036492b74fd9ee027f52f89 Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Thu, 18 Jun 2026 14:50:21 +1000
Subject: [PATCH 24/27] [PIR #1053] Review: record 3-way consult disposition +
 MarkdownView fix

---
 .../1053-vscode-typography-tokens-for-t.md    | 26 +++++++++++++++++--
 1 file changed, 24 insertions(+), 2 deletions(-)

diff --git a/codev/reviews/1053-vscode-typography-tokens-for-t.md b/codev/reviews/1053-vscode-typography-tokens-for-t.md
index a2f3c5a11..cbccf7a34 100644
--- a/codev/reviews/1053-vscode-typography-tokens-for-t.md
+++ b/codev/reviews/1053-vscode-typography-tokens-for-t.md
@@ -86,8 +86,9 @@ high-blast-radius cross-cutting rules). Three reusable lessons are recorded in t
 
 ## Test Results
 
-- `pnpm --filter @cluesmith/codev-artifact-canvas test` — **55 passed** (incl. the new
-  `default-theme.test.ts` token-vocabulary snapshot + contrast-token assertion).
+- `pnpm --filter @cluesmith/codev-artifact-canvas test` — **56 passed** (incl. the new
+  `default-theme.test.ts` token-vocabulary snapshot, contrast-token assertion, and the
+  standalone-`MarkdownView`-coverage regression test added after the 3-way consult).
 - `pnpm --filter codev-vscode test:unit` — **442 passed**.
 - `pnpm --filter @cluesmith/codev-artifact-canvas build`, vscode `check-types` (host + webview
   tsconfigs) and the esbuild production bundle — all clean.
@@ -116,6 +117,27 @@ high-blast-radius cross-cutting rules). Three reusable lessons are recorded in t
   their block* (long code lines / wide tables shouldn't wrap); prose breaks long tokens
   (`overflow-wrap`) so it never forces a *page-level* scrollbar.
 
+### 3-way consultation disposition (single advisory pass, `max_iterations: 1`)
+
+- **Codex — REQUEST_CHANGES (HIGH), addressed (real defect).** The typography rules were scoped to
+  `.codev-artifact-canvas-body` only, but the **exported standalone `MarkdownView`** renders
+  `.codev-artifact-canvas-rendered` with no `.codev-artifact-canvas` ancestor — so the standalone
+  public surface received *no* typography (not even the base font), contradicting the approved
+  plan, which required both containers be covered. **Fix:** the token + base-font block now names
+  both roots, and every prose element rule uses an `:is(.codev-artifact-canvas-body,
+  .codev-artifact-canvas-rendered)` container group; overlay-only chrome (gutter, focus outline,
+  cards, minimap) stays composed-surface-only. Added a regression test
+  (`default-theme.test.ts` → "covers the standalone MarkdownView root…") that fails if a prose rule
+  or the token block stops naming the standalone root. The VSCode preview (the only current
+  consumer, which uses `ArtifactCanvas` → `-body`) is unaffected — `-body` is inside the `:is()`
+  group. *Escalated because PIR's single-pass design did not independently re-review this fix.*
+- **Claude — APPROVE (HIGH).** Flagged the same scoping gap as a non-blocking observation; its
+  parenthetical that the standalone view still "gets the font baseline" is incorrect (the base font
+  is on `.codev-artifact-canvas`, not an ancestor of `-rendered`), which is exactly why it was
+  worth fixing rather than rebutting.
+- **Gemini — no usable verdict.** Output was a sandbox/environment message, not a review (no
+  VERDICT line). Nothing to action.
+
 ## Follow-ups
 
 - **#1070** (area/vscode) — in-preview typography controls (zoom buttons / command + write-back).

From 602c08a2df21d0608b0c3fe053ebb0b56cd099e5 Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Thu, 18 Jun 2026 14:50:43 +1000
Subject: [PATCH 25/27] [PIR #1053] Thread: consult disposition + MarkdownView
 fix

---
 codev/state/pir-1053_thread.md | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/codev/state/pir-1053_thread.md b/codev/state/pir-1053_thread.md
index 79e459e5d..a9aefbd05 100644
--- a/codev/state/pir-1053_thread.md
+++ b/codev/state/pir-1053_thread.md
@@ -87,3 +87,23 @@ COLD lessons-learned.md: bg-without-fg contrast bug, prose-vs-code overflow spli
 compounding). PR #1071 opened with review as body, recorded via `porch done --pr 1071`.
 Checks passed. 3-way consult (gemini/codex/claude, type=impl, single advisory pass) running in
 background. Then notify architect + wait at `pr` gate.
+
+## Consult results + fix
+
+- Codex: REQUEST_CHANGES (HIGH) — typography scoped to `.codev-artifact-canvas-body` only, but
+  exported `MarkdownView` renders `.codev-artifact-canvas-rendered` (no `.codev-artifact-canvas`
+  ancestor) → standalone surface got NO typography. Contradicts the approved plan (both containers
+  required). REAL defect.
+- Claude: APPROVE (HIGH) but flagged the SAME gap as non-blocking; its "standalone still gets the
+  base font" aside is factually wrong (base font is on `.codev-artifact-canvas`, not an ancestor
+  of `-rendered`).
+- Gemini: no usable verdict (sandbox/env message, no VERDICT line).
+
+Both substantive reviewers found the same issue → fixed (not rebutted). Token+base-font block
+now names both roots; all prose rules use `:is(.codev-artifact-canvas-body,
+.codev-artifact-canvas-rendered)`; overlay chrome (gutter/focus/cards/minimap) stays body-only.
+Added regression test asserting standalone root is covered + gutter stays body-only. Used `:is()`
+to keep it DRY. canvas 56/56, vscode 442/442, typechecks+bundle clean; verified `:is()` selectors
+land in bundled webview CSS. VSCode preview (uses ArtifactCanvas→`-body`, inside the `:is()`
+group) unaffected. Recorded disposition in review "Things to Look At". Escalating Codex finding to
+architect at pr gate (PIR won't re-review).

From 0157309c744fecbfb68f15b3388a4303ad73ec1e Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Thu, 18 Jun 2026 14:51:52 +1000
Subject: [PATCH 26/27] [PIR #1053] Consultation rebuttals (iteration 1)

---
 .../1053-review-iter1-rebuttals.md            | 68 +++++++++++++++++++
 1 file changed, 68 insertions(+)
 create mode 100644 codev/projects/1053-vscode-typography-tokens-for-t/1053-review-iter1-rebuttals.md

diff --git a/codev/projects/1053-vscode-typography-tokens-for-t/1053-review-iter1-rebuttals.md b/codev/projects/1053-vscode-typography-tokens-for-t/1053-review-iter1-rebuttals.md
new file mode 100644
index 000000000..e3b3755e4
--- /dev/null
+++ b/codev/projects/1053-vscode-typography-tokens-for-t/1053-review-iter1-rebuttals.md
@@ -0,0 +1,68 @@
+# PIR #1053 — Consultation Rebuttals (iteration 1)
+
+Single advisory pass (`max_iterations: 1`). Disposition of each verdict below.
+
+## Codex — REQUEST_CHANGES (HIGH) → ADDRESSED (real defect, fixed)
+
+**Finding:** Typography was scoped to `.codev-artifact-canvas-body` (and base font tokens to
+`.codev-artifact-canvas`), but the exported standalone `MarkdownView` renders
+`.codev-artifact-canvas-rendered` with no `.codev-artifact-canvas` ancestor — so the standalone
+public surface received no typography tokens or prose rules. This contradicts the approved plan,
+which required the rules to cover both containers.
+
+**Assessment:** Valid and HIGH-impact. Verified the facts directly:
+- `MarkdownView` is exported from the package's public `index.ts`.
+- It renders a bare `.codev-artifact-canvas-rendered` root (`renderer/MarkdownView.tsx:16-21`),
+  not nested under `.codev-artifact-canvas`.
+- The tokens + base font were declared only on `.codev-artifact-canvas`, which is **not** an
+  ancestor of `-rendered`, so the standalone surface inherited neither.
+- My own approved plan explicitly stated the rules must cover both containers.
+
+So it ships a known-broken public surface and diverges from the plan. Treated as a real defect and
+fixed (not rebutted).
+
+**Fix (commit `[PIR #1053] Cover standalone MarkdownView surface with typography (consult fix)`):**
+- The token vocabulary + base `color`/`background`/`font-family`/`font-size`/`line-height` now
+  apply to **both** `.codev-artifact-canvas` and `.codev-artifact-canvas-rendered`.
+- Every prose element rule now uses an `:is(.codev-artifact-canvas-body,
+  .codev-artifact-canvas-rendered)` container group (kept DRY with `:is()` rather than duplicating
+  every selector).
+- Overlay-only chrome stays composed-surface-only: the gutter `padding-left`, the
+  `[data-line]:focus-visible` outline, the comment cards, and the minimap remain
+  `.codev-artifact-canvas-body` / `.codev-artifact-canvas` scoped (MarkdownView has no overlay).
+- `position: relative` (overlay anchor) split out to `.codev-artifact-canvas` only.
+
+**Regression test** (`src/__tests__/default-theme.test.ts` → "covers the standalone MarkdownView
+root, not just the composed canvas"): asserts (1) the token/base-font block names the standalone
+root, (2) representative prose selectors (`h1`, `code`) name it via the `:is()` group, and (3) the
+gutter `padding-left` rule stays bare-`-body` (composed-surface-only). Fails if a future change
+drops the standalone root from prose styling or leaks the gutter into the standalone surface.
+
+**No regression to the shipped consumer:** the VSCode preview uses `ArtifactCanvas` →
+`.codev-artifact-canvas-body`, which is inside the `:is()` group, so its rendering is unchanged.
+Verified the `:is()` selectors land in the bundled `dist/webview/markdown-preview.css`.
+
+**Escalation:** PIR's single advisory pass does not independently re-review this fix, so it is
+flagged to the human at the `pr` gate as the remaining reviewer.
+
+## Claude — APPROVE (HIGH) → no action required (but corroborates the Codex fix)
+
+Approved overall. It flagged the *same* `MarkdownView` scoping gap as a non-blocking observation.
+Its parenthetical that the standalone view "gets the font baseline" anyway is factually incorrect —
+the base font is declared on `.codev-artifact-canvas`, which is not an ancestor of
+`.codev-artifact-canvas-rendered` — which is exactly why the gap was worth fixing rather than
+accepting. The fix above resolves the observation. All other points (plan adherence, code quality,
+test coverage, review-file quality) were positive; nothing to action.
+
+## Gemini — no usable verdict → nothing to action
+
+The Gemini output was a sandbox/environment status message, not a review (no `VERDICT` line, no
+findings). Porch defaulted it to REQUEST_CHANGES because no `APPROVE` token was present, but there
+is no substantive feedback to address. The consultation harness produced no review content for
+this model on this run.
+
+## Net
+
+The one substantive finding (Codex, corroborated by Claude) is a real defect and is fixed with a
+regression test. No outstanding REQUEST_CHANGES content remains unaddressed. The human at the `pr`
+gate is the remaining reviewer of the fix (PIR single-pass).

From f467e9673753ecaf18dce35e22e61ab70f1d2448 Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Thu, 18 Jun 2026 14:51:55 +1000
Subject: [PATCH 27/27] chore(porch): 1053 pr gate-requested

---
 .../projects/1053-vscode-typography-tokens-for-t/status.yaml  | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/codev/projects/1053-vscode-typography-tokens-for-t/status.yaml b/codev/projects/1053-vscode-typography-tokens-for-t/status.yaml
index 4a08390b1..50e2a55df 100644
--- a/codev/projects/1053-vscode-typography-tokens-for-t/status.yaml
+++ b/codev/projects/1053-vscode-typography-tokens-for-t/status.yaml
@@ -15,13 +15,15 @@ gates:
     approved_at: '2026-06-18T04:37:07.103Z'
   pr:
     status: pending
+    requested_at: '2026-06-18T04:51:55.413Z'
 iteration: 1
 build_complete: true
 history: []
 started_at: '2026-06-17T21:50:52.095Z'
-updated_at: '2026-06-18T04:40:13.041Z'
+updated_at: '2026-06-18T04:51:55.413Z'
 pr_history:
   - phase: review
     pr_number: 1071
     branch: builder/pir-1053
     created_at: '2026-06-18T04:39:43.192Z'
+pr_ready_for_human: true