basalt-ui 1.10.0 → 1.12.0

package/src/agent-chat/tool-chip.tsx

@@ -0,0 +1,219 @@
+/**
+ * ToolChip — a one-line collapsed row for a tool-call part, expanding to its input/output JSON.
+ *
+ * Replaces `thread-message.tsx`'s old always-expanded `ToolRenderer`, which unconditionally
+ * rendered both input and output `<pre>` blocks. Collapsed, it shows a mono micro-label, the tool
+ * name, a state dot, and `durationMs` when present; expanded, it shows whatever the part's state
+ * actually carries — input, output, the surviving `rawInput` for a call whose input never
+ * validated, the error text, the denial reason, or the approve/deny affordances.
+ *
+ * @example
+ * import { ToolChip } from 'basalt-ui/agent-chat'
+ *
+ * <ToolChip
+ *   part={part}
+ *   onApprove={(id) => api.runs.approve.post({ approvalId: id })}
+ *   onDeny={(id, reason) => api.runs.deny.post({ approvalId: id, reason })}
+ * />
+ */
+import { Box, Button, Collapse, Group, Stack, Text, UnstyledButton } from '@mantine/core'
+import { useDisclosure } from '@mantine/hooks'
+import type { JSX } from 'react'
+import { isToolCallSettled } from '../agent'
+import type { ToolCallPart } from '../agent'
+import { alpha, VX } from '../tokens'
+
+// Mirrors thread-message.tsx's micro-label/rail/code-block idiom (docs/DESIGN-SPEC.md §3/§5) —
+// duplicated locally rather than imported, matching the existing part-list.tsx/thread-message.tsx
+// precedent of each Mantine-facing renderer file owning its own copy of these style objects.
+const MICRO_LABEL_STYLE = {
+  fontFamily: 'var(--basalt-font-mono)',
+  fontSize: VX.text.micro,
+  fontWeight: 500,
+  letterSpacing: '0.06em',
+  textTransform: 'uppercase',
+  color: VX.faint,
+} as const
+const RAIL_STYLE = {
+  borderLeft: `2px solid ${VX.divider}`,
+  paddingLeft: 'var(--vx-space-agent-rail-inset-x)',
+} as const
+const CODE_BLOCK_STYLE = {
+  margin: 0,
+  marginTop: 'var(--vx-space-agent-part-gap-top)',
+  fontFamily: 'var(--basalt-font-mono)',
+  backgroundColor: alpha(VX.ink, 0.06),
+  borderRadius: 'var(--vx-radius-card)',
+  padding: 'var(--vx-space-agent-code-inset)',
+  whiteSpace: 'pre-wrap',
+  overflowWrap: 'anywhere',
+} as const
+
+/** Per-state (label, dot color) — the exhaustive switch that drives the collapsed row. */
+function stateMeta(part: ToolCallPart): { readonly label: string; readonly dotToken: string } {
+  switch (part.state) {
+    case 'input-streaming':
+      return { label: 'streaming', dotToken: VX.status.neutral }
+    case 'input-available':
+      // No 'running' state on the wire — 'input-available' IS the running state (input complete,
+      // no output yet). This label is a UI-only gloss on that wire state, not a new state.
+      return { label: 'running', dotToken: VX.status.neutral }
+    case 'approval-requested':
+      return { label: 'needs approval', dotToken: VX.status.warn }
+    case 'approval-responded':
+      return part.approval.approved
+        ? { label: 'approved', dotToken: VX.status.neutral }
+        : { label: 'declined', dotToken: VX.status.bad }
+    case 'output-available':
+      // preliminary vs final must be visually distinguishable — the label carries that here; the
+      // expanded output body below is identical either way.
+      return part.preliminary === true
+        ? { label: 'preliminary', dotToken: VX.status.warn }
+        : { label: 'done', dotToken: VX.status.good }
+    case 'output-error':
+      return { label: 'error', dotToken: VX.status.bad }
+    case 'output-denied':
+      return { label: 'denied', dotToken: VX.status.bad }
+    default: {
+      // `part` is `never` here ONLY at compile time — this switch is genuinely exhaustive today,
+      // so adding an eighth ToolCallPart state without a case above makes this assignment a tsc
+      // error, the same gate `assertNever` provides. But `part` at RUNTIME can be a value this
+      // build never declared: `createThreadsStore` persists to localStorage with no shape
+      // validation, and `edenTransport` trusts the wire with zero validation, so a 1.10.0-shaped
+      // flat tool part (`state` undefined) or a future/foreign `state` string both reach here.
+      // That must never THROW during render — mirrors ThreadTranscript's fallbackRenderer
+      // doctrine (unknown data renders inert, it doesn't blank the transcript) — so, unlike a
+      // genuinely-exhaustive switch elsewhere, this default returns a neutral descriptor instead
+      // of calling assertNever.
+      const exhaustive: never = part
+      void exhaustive
+      return { label: 'unknown', dotToken: VX.status.neutral }
+    }
+  }
+}
+
+function formatDuration(ms: number): string {
+  return ms >= 1000 ? `${(ms / 1000).toFixed(1)}s` : `${Math.round(ms)}ms`
+}
+
+export type ToolChipProps = {
+  readonly part: ToolCallPart
+  readonly defaultExpanded?: boolean
+  /** Rendered only in 'approval-requested'. Omit both to render a read-only chip. */
+  readonly onApprove?: (approvalId: string) => void
+  readonly onDeny?: (approvalId: string, reason?: string) => void
+}
+
+/**
+ * A collapsed-by-default row for a single tool-call part. All seven wire states render something
+ * sane; the switch above still gates an eighth (compile-time-unhandled) state as a tsc error via a
+ * `const _: never = part` assignment, but unlike a truly-closed switch, its `default` branch never
+ * throws at RUNTIME — a value from persisted/wire data that reaches here with a `state` this build
+ * doesn't recognize renders an inert 'unknown' chip instead of blanking the transcript.
+ *
+ * @example
+ * <ToolChip part={part} />
+ */
+export function ToolChip({
+  part,
+  defaultExpanded = false,
+  onApprove,
+  onDeny,
+}: ToolChipProps): JSX.Element {
+  const [expanded, { toggle }] = useDisclosure(defaultExpanded)
+  const { label, dotToken } = stateMeta(part)
+  const settled = isToolCallSettled(part)
+
+  const input = 'input' in part ? part.input : undefined
+  const rawInput = part.state === 'output-error' ? part.rawInput : undefined
+
+  return (
+    <Box style={RAIL_STYLE}>
+      <Stack gap={4}>
+        <UnstyledButton onClick={toggle}>
+          <Group gap={6} align="center" wrap="nowrap">
+            <Box
+              aria-hidden
+              style={{
+                width: 6,
+                height: 6,
+                flexShrink: 0,
+                borderRadius: '50%', // theme-allow: a 6px state dot is a circle, not a surface corner — no radius token expresses it
+                backgroundColor: dotToken,
+              }}
+            />
+            <Text style={MICRO_LABEL_STYLE}>{part.toolName}</Text>
+            <Text size="xs" c="dimmed">
+              {label}
+            </Text>
+            {part.durationMs !== undefined && (
+              <Text
+                style={{
+                  fontFamily: 'var(--basalt-font-mono)',
+                  fontSize: VX.text.micro,
+                  color: VX.faint,
+                }}
+              >
+                {formatDuration(part.durationMs)}
+              </Text>
+            )}
+            {!settled && (
+              <Text size="xs" c="dimmed">
+                …
+              </Text>
+            )}
+          </Group>
+        </UnstyledButton>
+        <Collapse expanded={expanded}>
+          <Stack gap={6}>
+            {input !== undefined && (
+              <Text component="pre" size="xs" style={CODE_BLOCK_STYLE}>
+                {JSON.stringify(input, null, 2)}
+              </Text>
+            )}
+            {rawInput !== undefined && (
+              <Text component="pre" size="xs" style={CODE_BLOCK_STYLE}>
+                {JSON.stringify(rawInput, null, 2)}
+              </Text>
+            )}
+            {part.state === 'output-available' && (
+              <Text component="pre" size="xs" style={CODE_BLOCK_STYLE}>
+                {JSON.stringify(part.output, null, 2)}
+              </Text>
+            )}
+            {part.state === 'output-error' && (
+              <Text size="xs" style={{ color: VX.status.bad }}>
+                {part.errorText}
+              </Text>
+            )}
+            {part.state === 'output-denied' && part.approval.reason !== undefined && (
+              <Text size="xs" c="dimmed">
+                {part.approval.reason}
+              </Text>
+            )}
+            {part.state === 'approval-requested' &&
+              (onApprove !== undefined || onDeny !== undefined) && (
+                <Group gap={6}>
+                  {onApprove !== undefined && (
+                    <Button size="compact-sm" onClick={() => onApprove(part.approval.id)}>
+                      Approve
+                    </Button>
+                  )}
+                  {onDeny !== undefined && (
+                    <Button
+                      size="compact-sm"
+                      variant="light"
+                      color="red"
+                      onClick={() => onDeny(part.approval.id)}
+                    >
+                      Deny
+                    </Button>
+                  )}
+                </Group>
+              )}
+          </Stack>
+        </Collapse>
+      </Stack>
+    </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>
     )
   }