Hephaestus plot documents (.hep): render to SVG with brand colors, and live preview in q2 preview / hub-client (bd-3qych45b)

[cscheid]

Summary

Phases 1 and 2 of hephaestus support (bd-3qych45b, plan: claude-notes/plans/2026-09-17-hephaestus-hep-integration.md).

Phase 1 — q2 render (native)

• ![](plot.hep) in html / revealjs output is rendered at render time with hephaestus's renderer-free SVG backend (no wgpu, no GPU), stored as a page-scoped artifact under <stem>_files/figure-html/, and the image is pointed at it. Size comes from width/height attrs, else the document's own hint, else 7in × 5in at 96 dpi; the plot re-flows at that size rather than being scaled.
• Brand colors: with brand: declared, the light brand's background / foreground / primary become the plot's paper / ink / accent. Only hex values cross; anything else warns (Q-19-4).
• Bundled Roboto faces (resources/hephaestus/fonts/, OFL) are registered once per process and mapped onto sans-serif, so the same .hep renders byte-identically on every machine and matches what hephaestus's browser client draws.
• New image diagnostics subsystem, Q-19-1..Q-19-4, each with a docs page and sidebar entry. Failures are warnings and leave the image as written. (Numbered 18 until the merge of main, where the new engine subsystem had taken 18.)
• transforms/image_walk.rs: the mutable body-image walker extracted from responsive_image so both transforms share one container set.
• Runnable example: examples/plots/01-hephaestus-basic (captioned figure, explicit size, missing-file case, dark brand).

Phase 2 — q2 preview and hub-client (bd-sxiv2tio)

• HepImage in @quarto/preview-renderer is the registry's Image entry: for a local .hep target it fetches the asset-walker bytes and mounts a live PlotView from the npm hephaestus-svg-wasm client (0.4.1, exact-pinned to the crate version; parity tests on both sides); anything else delegates to the plain <img>. Covers q2-preview documents and format: revealjs decks in both q2 preview and hub-client, since RevealDeck renders slide content through the same registry.
• The client loads on demand (cached dynamic import); plot-free documents never fetch the 2.4 MB wasm. Its Roboto faces ship as hashed assets in every bundle (SPA, hub-client, sandboxed frame).
• Sizing: width attr → document hint → 672 px, capped at the column, height via CSS aspect-ratio, so narrow columns and slides get a re-solved layout while wide columns match q2 render.
• .hep added to the binary-extension allowlists (quarto-hub::resource and its quarto-automerge-schema mirror) — without it the bytes never reached the preview VFS.
• Manifest miss → "file not found in the project" error box; load failures → error box with the message.
• Not in this PR: the separate-origin sandboxed frame (bd-9t5nmq81) and brand colors in the browser, which need an upstream palette API on the wasm client (bd-qcltc0ll).

Why SVG and not PNG

hephaestus rasterizes through wgpu, which needs a GPU adapter a headless render machine may not have, and GPU output is not byte-stable across machines. The SVG backend needs no GPU, keeps text as real <text>, and is deterministic. PDF/Typst outputs plug into the same transform later (latex → the pdf backend, typst → SVG) — bd-br9bmysi.

Dependency notes

• quarto-core gains hephaestus = 0.4.1 (document-read, svg, png) in the native-only table; both Cargo.locks pick up parley / fontique / skrifa / kurbo / peniko / clipper2-rust / png. All pure Rust. The main WASM bundle does not compile hephaestus.
• On Linux, parley → fontique would link libfontconfig at build time by default. fontique's fontconfig-dlopen feature is enabled for Linux so building q2 does not require libfontconfig1-dev; a missing library at run time just yields an empty system font collection (fine — plot text uses the bundled faces).
• preview-renderer gains hephaestus-svg-wasm = 0.4.1 (npm, MIT); optimizeDeps.exclude in hub-client and the SPA keeps dev pre-bundling from breaking its import.meta.url asset lookups.

Test plan

• crates/quarto-core/tests/integration/hephaestus_render.rs: end-to-end tests through render_to_file (artifact path, determinism, bundled font, sizing, id prefixes, revealjs, untouched non-hep images, missing / invalid file, brand applied / non-hex slot / no brand) + unit tests, incl. the npm-version parity test.
• HepImage.test.tsx (20 cases: mount, delegation, external/data targets, load-once, errors, free() on unmount, remount on new bytes, sizing rules, a11y attrs, registry layering, version pin vs package.json and Cargo.lock); resource.rs + fileType.test.ts for the .hep extension.
• Full cargo xtask verify green (Rust + WASM + hub-client build/tests + SPA), before and after merging main.
• cargo run --bin q2 -- render examples/plots/01-hephaestus-basic, output inspected.
• Browser checks (recorded in the plan): q2 preview html document + revealjs deck; hub-client (q2 preview --ui editor) format: q2-preview document + revealjs deck. Plots mount as reflowed SVG; missing file shows the error box; .png stays an <img>.
• CI green on Linux, macOS and Windows on the phase-1 and phase-2 pushes.

🤖 Generated with Claude Code

[posit-snyk-bot]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.