q2 preview (CLI) silently ignores render-components: — feature is hub-client-only

[cscheid]

Tracked internally as braid strand bd-ue80chl0 (discovered during the mermaid work, bd-5m4ga0s1 / #401). Filing here for visibility since the fix belongs with the render-components feature.

Symptom

A document with a render-components: entry in its front matter loads user TSX component overrides in hub-client, but under q2 preview (the CLI) the entries are silently dropped — no warning, no error, the built-in components just render instead. The two preview surfaces diverge without any signal to the author.

How it surfaced: verifying a prototype doc that overrides CodeBlock via render-components. Under q2 preview the diagram rendered with the built-in mermaid component's markers (quarto-mermaid-… SVG id, mermaid-diagram class) rather than the prototype's (mmd-… id, inline styles) — the user override never loaded.

Why it happens

The custom-components pipeline is a two-process design:

1. A parent reads render-components from the document meta, resolves the TSX paths, transpiles them with @babel/standalone, and posts the compiled code into the sandboxed iframe via a LOAD_CUSTOM_COMPONENTS message.
2. The iframe (shared @quarto/preview-renderer package, q2-preview/entry.tsx → loadCustomComponents) imports the code as blob ESM modules and layers the exports over the built-in registry (mergedPreviewRegistry).

The iframe half is shared between hub-client and the CLI preview SPA and fully supports the feature. Only hub-client implements the parent half (hub-client/src/components/render/ReactRenderer.tsx: meta walk → resolveComponentPath → transpileTSX → customComponentsCode prop). The CLI SPA's parent (q2-preview-spa/src/PreviewApp.tsx) never passes customComponentsCode to Q2PreviewIframe at all — it doesn't read the YAML key and has no transpiler in its bundle.

Impact

• Documents authored against hub-client's render-components behavior render differently (built-ins only) under q2 preview, silently.
• Pre-existing; unrelated to Mermaid diagrams as a regular rendering feature (bd-5m4ga0s1) #401 (which actually softened the mermaid-specific case: the built-in mermaid component now renders diagrams the dropped override used to handle).

Possible resolutions

1. Implement the parent half in the CLI SPA: read render-components from the AST meta, fetch TSX sources from the preview file server, transpile, and post the same LOAD_CUSTOM_COMPONENTS message hub-client sends. Cost: @babel/standalone is a heavy addition to the SPA bundle — precompiling server-side in the Rust preview binary is an alternative worth weighing.
2. Declare the feature hub-client-only and document it — and ideally emit a visible warning in q2 preview when a document carries render-components, so the divergence is at least no longer silent.

🤖 Generated with Claude Code