fix(revealjs): apply the document's compiled reveal theme in q2 preview (Level 2)

`q2 preview` of a `format: revealjs` deck never applied the Quarto reveal
theme: it showed reveal's stock `white.css` (centered text, uppercase
headings) regardless of `theme:` / `_brand.yml`, diverging from `q2 render`
(left-aligned, non-uppercase, document theme). bd-y259zb57 Bug 2 / Level 2.

Root cause + fixes:

- CompileThemeCssStage gated its reveal branch on `identifier == Revealjs`,
  but the preview pseudo-format `q2-slides` has `identifier == Html`, so the
  preview compiled Bootstrap, not the reveal theme. Gate is now
  `is_revealjs_target(target_format)` (true for both `revealjs` render and
  `q2-slides` preview; render output unchanged). Preview delivers the compiled
  theme through the existing `css:theme:<fp>` -> styles.css transport the SPA
  already reads (Q2PreviewIframe -> UPDATE_THEME); render still links the full
  `css:revealjs:*` asset set via site_libs.

- MetadataMergeStage flattened `format.html.*` for `q2-slides`, burying
  `format.revealjs.{theme,brand,...}` — so *named* themes and brand silently
  fell back to the default theme in preview. It now maps the reveal preview to
  the `revealjs` base format, matching `q2 render`.

- quarto-hub discovery never synced `_brand.yml` into the preview VFS (only
  `_quarto.yml`/`_metadata.yml` were recognized as config), so brand decks died
  with "Path not found: /project/_brand.yml" — for HTML brand decks too. Added
  `_brand.yml`/`_brand.yaml`.

- Preview SPA: entry.tsx no longer suppresses the theme link for slides (the
  theme is now the reveal theme, not Bootstrap); RevealDeck drops its static
  `white.css` import so the per-document compiled theme applies instead.

E2E verified (`q2 preview` + Chrome computed styles == `q2 render`) for default,
named (`dark`), and `_brand.yml` decks. Tests: compile_theme_css (1), pipeline
(3), quarto-hub discovery (1). `cargo xtask verify` green.

Single-file `q2 preview deck.qmd` with a sibling `_brand.yml` still can't
resolve brand (single-file mode excludes siblings by design) — tracked as
bd-ggvq1j68.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: cscheid

claude-notes/plans/2026-06-16-revealjs-render-preview-theme-parity.md

@@ -66,24 +66,75 @@ async). So the preview can compile the reveal theme on WASM.
 
 ### Work (each TDD; verify through real `q2 preview` + Chrome)
 
-- [ ] **L2.1 (Rust).** Make the preview pipeline compile the document's reveal
-      theme. The reveal branch must fire for the reveal-preview pseudo-format.
-      Decide the detection signal (target_format `q2-slides` /
-      `is_revealjs_target`, vs `ast.meta` `format: revealjs`) since
-      `format.identifier` is `Html` in preview. Register the compiled theme so
-      the WASM extractor + VFS flush find it (either reuse `css:theme:<fp>` +
-      the styles.css artifact path, or extend the extractor for the reveal key).
-- [ ] **L2.2 (WASM).** Ensure `render_page_for_preview` surfaces the reveal
-      theme (fingerprint + bytes flushed to the VFS artifact path the SPA reads).
-- [ ] **L2.3 (hub-client).** The preview reveal renderer must consume the theme
-      (UPDATE_THEME / prop), inject it as a stylesheet, and **drop the static
-      `white.css` import** (keep reset + reveal core + quarto-reveal). Bundle the
-      Source Sans Pro `@import` comes along via the compiled theme automatically.
-      Files: `ts-packages/preview-renderer/src/q2-preview/RevealDeck.tsx`,
-      `Q2PreviewIframe.tsx`, q2-preview-spa entry. **hub-client change → two-commit
-      changelog; WASM/SPA rebuild required.**
-- [ ] **L2.4.** Tests + E2E parity check (`q2 render` vs `q2 preview` on a deck
-      with default, a named theme, and `_brand.yml` — all should match).
+- [x] **L2.1 (Rust).** DONE. Gate changed from `identifier == Revealjs` to
+      `is_revealjs_target(&ctx.format.target_format)` in `CompileThemeCssStage`
+      (`compile_theme_css.rs`), so the reveal branch fires for the `q2-slides`
+      preview pseudo-format (identifier `Html`) as well as `revealjs` render.
+      **Delivery split**: render (`revealjs`) still calls
+      `register_reveal_assets` (linkable `css:revealjs:*` set via site_libs);
+      preview (`q2-slides`) calls `store_css` so the compiled reveal theme rides
+      the *existing* `css:theme:<fp>` → styles.css transport the SPA already
+      consumes. Compile-failure fallback → `stock_reveal_theme_css()` (vendored
+      white). Tests: `reveal_preview_delivers_compiled_theme_via_css_theme_artifact`
+      (compile_theme_css.rs), `q2_preview_pipeline_compiles_reveal_theme_for_slides`
+      (pipeline.rs, exercises the full preview pipeline). Render output unchanged
+      (all 2372 quarto-core tests pass).
+- [x] **L2.2 (WASM).** DONE — **no WASM code change required** for the single-doc
+      path (the `q2 preview` target use case). Because L2.1 routes the reveal
+      theme through `css:theme:<fp>`, `extract_theme_fingerprint` (looks for
+      `css:theme:`) and `flush_artifacts_to_vfs` (writes styles.css) already
+      surface it via `render_page_for_preview` → `RenderResponse.theme_fingerprint`.
+      (Project-of-decks path uses the multi-doc `quarto/quarto-theme-<fp>.css`
+      artifact path rather than styles.css — out of scope for the single-deck
+      "done" criteria; tracked as a follow-up if needed.)
+- [x] **L2.3 (hub-client).** DONE. `entry.tsx`: removed the slides theme-link
+      suppression (`currentDocIsSlides`/`setDocIsSlides`) — `reconcileThemeLink`
+      now always applies `lastThemeCssUrl` (for slides that URL is the compiled
+      reveal theme, not Bootstrap). `RevealDeck.tsx`: dropped the static
+      `theme/white.css` import (kept reset + reveal + quarto-reveal); the
+      per-document theme arrives via the `UPDATE_THEME` → `<link data-q2-theme>`
+      transport. quarto-reveal.css is theme-independent/additive, so the runtime
+      theme link landing after it does not change the cascade.
+      **hub-client change → two-commit changelog; WASM/SPA rebuild required.**
+- [x] **L2.4.** DONE. Tests + E2E parity check across **default, named (`dark`),
+      and `_brand.yml`** — all three match `q2 render`.
+  - **Rust tests** (`cargo nextest`, all green; full workspace 10147 pass):
+    - `compile_theme_css.rs`: `reveal_preview_delivers_compiled_theme_via_css_theme_artifact`.
+    - `pipeline.rs`: `q2_preview_pipeline_compiles_reveal_theme_for_slides`,
+      `…_compiles_named_reveal_theme_for_slides` (guards the metadata-flattening
+      fix), `…_compiles_brand_reveal_theme_for_slides` (real tempdir `_brand.yml`).
+    - `quarto-hub/discovery.rs`: `test_discover_brand_file`.
+  - **Two extra fixes surfaced during E2E** (both were silent before because the
+    default theme needs no `theme:`/brand lookup):
+    1. **Metadata flattening** (`metadata_merge.rs`): `q2-slides` flattened
+       `format.html.*`, burying `format.revealjs.{theme,brand,…}`. Now maps the
+       reveal preview to the `revealjs` base format. Without this, *named* themes
+       and brand silently fell back to the default theme in preview.
+    2. **`_brand.yml` VFS sync** (`quarto-hub/discovery.rs`): the preview server
+       never synced `_brand.yml` into the VFS (only `_quarto.yml`/`_metadata.yml`
+       were recognized as config), so brand resolution died with "Path not found:
+       /project/_brand.yml" — for HTML brand decks too, not just reveal. Added
+       `_brand.yml`/`_brand.yaml` to config-file discovery.
+  - **E2E evidence** (`cargo run --bin q2 -- preview <deck>`, computed styles read
+    from the live iframe via Chrome DevTools; compared to `q2 render`'s compiled
+    `theme-*.css`):
+    - **default** (`.e2e-reveal/default.qmd`): heading `text-transform: none`,
+      content `text-align: left`, `font-family: "Source Sans Pro"`, color `#222` —
+      matches render. `white.css` no longer statically imported; theme arrives via
+      `<link data-q2-theme>`.
+    - **dark** (`theme: dark`): `--r-background-color: #191919`, viewport bg
+      `rgb(25,25,25)`, `--r-main-color: #fff` — matches render `#191919`.
+    - **brand** (`_brand.yml`, run as a project): `--r-background-color: #fdf6ff`,
+      `--r-main-color: #2a1a3a`, `--r-heading-color: #6f42c1`, `--r-main-font:
+      Georgia`; h1 computed `rgb(111,66,193)` — all match render exactly.
+  - **Known limitations (out of scope / follow-ups):**
+    - **Single-file `q2 preview deck.qmd` + sibling `_brand.yml`**: the `bd-tnm3k`
+      single-file watcher deliberately does NOT pull in siblings, so brand only
+      resolves when the deck lives in a *project* (`_quarto.yml` present). Same
+      for HTML brand decks. Tracked separately.
+    - **`[Q-1-20] "Failed to parse metadata value as markdown"`** on `brand:
+      _brand.yml` — pre-existing, appears identically in render *and* preview (so
+      itself a parity success); unrelated to theming.
 
 ### Notes / gotchas
 

crates/quarto-core/src/pipeline.rs

@@ -2514,6 +2514,163 @@ mod tests {
         );
     }
 
+    /// bd-y259zb57 (L2.1): the q2-preview pipeline — the exact path
+    /// `q2 preview` drives in WASM — must compile the deck's reveal theme and
+    /// expose it through the standard `css:theme:<fp>` artifact, so the SPA's
+    /// existing `theme_fingerprint` + styles.css transport delivers it. Before
+    /// the fix the `q2-slides` pseudo-format (identifier `Html`) took the
+    /// Bootstrap branch, so the preview shipped Bootstrap and reveal decks fell
+    /// back to stock `white.css` (centered, uppercase) instead of the Quarto
+    /// reveal theme (left-aligned, non-uppercase).
+    #[test]
+    fn q2_preview_pipeline_compiles_reveal_theme_for_slides() {
+        let content = b"---\ntitle: Slides Test\nformat: revealjs\n---\n\n\
+                        ## First\n\n- a\n- b\n";
+
+        let project = make_test_project();
+        let doc = DocumentInfo::from_path("/project/test.qmd");
+        let format = Format::from_format_string("q2-slides").unwrap();
+        let binaries = BinaryDependencies::new();
+        let mut ctx = RenderContext::new(&project, &doc, &format, &binaries);
+
+        let runtime = make_test_runtime();
+        pollster::block_on(render_qmd_to_preview_ast(
+            content,
+            "test.qmd",
+            &mut ctx,
+            runtime,
+            None,
+            Vec::new(),
+        ))
+        .expect("q2-slides render");
+
+        // The compiled reveal theme is delivered via `css:theme:<fp>` (the same
+        // artifact key + styles.css path the SPA already reads), NOT the
+        // linkable `css:revealjs:*` set (that's the render path's site_libs
+        // delivery — the SPA bundles reset/reveal/quarto-reveal itself).
+        let theme_entries = ctx.artifacts.get_by_prefix("css:theme:");
+        assert_eq!(
+            theme_entries.len(),
+            1,
+            "q2-slides preview should produce exactly one css:theme artifact"
+        );
+        let css = theme_entries[0].1.as_str().expect("theme CSS is UTF-8");
+        assert!(
+            css.contains(".reveal"),
+            "preview must compile the reveal theme (scoped under .reveal), not Bootstrap"
+        );
+        assert!(
+            !css.contains(".navbar"),
+            "preview reveal theme must not be Bootstrap (.navbar present)"
+        );
+        assert!(
+            ctx.artifacts.get_by_prefix("css:revealjs:").is_empty(),
+            "preview should not register linkable css:revealjs:* assets"
+        );
+    }
+
+    /// bd-y259zb57 (L2.1): a *named* reveal theme nested under
+    /// `format.revealjs.theme` must reach the preview's compiled theme. This
+    /// guards the metadata-flattening half of the fix: the `q2-slides`
+    /// pseudo-format has identifier `Html`, so `MetadataMergeStage` would
+    /// flatten `format.html.*` (burying `theme:`) unless it maps the reveal
+    /// preview back to the `revealjs` base format. Before that fix the preview
+    /// silently compiled the *default* theme for every named theme/brand.
+    #[test]
+    fn q2_preview_pipeline_compiles_named_reveal_theme_for_slides() {
+        // `theme: dark` lives under `format.revealjs.theme`, exactly as a real
+        // deck authors it.
+        let content = b"---\ntitle: Dark\nformat:\n  revealjs:\n    theme: dark\n---\n\n\
+                        ## First\n\nBody.\n";
+
+        let project = make_test_project();
+        let doc = DocumentInfo::from_path("/project/test.qmd");
+        let format = Format::from_format_string("q2-slides").unwrap();
+        let binaries = BinaryDependencies::new();
+        let mut ctx = RenderContext::new(&project, &doc, &format, &binaries);
+
+        let runtime = make_test_runtime();
+        pollster::block_on(render_qmd_to_preview_ast(
+            content,
+            "test.qmd",
+            &mut ctx,
+            runtime,
+            None,
+            Vec::new(),
+        ))
+        .expect("q2-slides render");
+
+        let theme_entries = ctx.artifacts.get_by_prefix("css:theme:");
+        assert_eq!(theme_entries.len(), 1, "expected one css:theme artifact");
+        let css = theme_entries[0].1.as_str().expect("theme CSS is UTF-8");
+        // The reveal `dark` theme sets a dark background; the default theme is
+        // white (`#fff`). Asserting the dark background proves the named theme
+        // was resolved (not silently defaulted).
+        assert!(
+            css.contains("#191919"),
+            "named theme `dark` must reach the compiled preview theme \
+             (expected dark background #191919); got default theme?"
+        );
+    }
+
+    /// bd-y259zb57 (L2.1): a `_brand.yml` reveal deck previewed as `q2-slides`
+    /// must fold the brand into the compiled theme — same as `q2 render`. This
+    /// exercises the reveal branch's brand resolution (`resolve_brand_layers`
+    /// against `ctx.project.dir`) through the preview pipeline, plus the
+    /// `format.revealjs.brand` metadata flattening. (E2E `q2 preview` of a brand
+    /// deck is additionally gated on the preview server syncing `_brand.yml`
+    /// into the VFS — a separate, pre-existing infra gap that affects HTML brand
+    /// previews identically; tracked in its own strand.)
+    #[test]
+    fn q2_preview_pipeline_compiles_brand_reveal_theme_for_slides() {
+        // Real tempdir so the NativeRuntime can read `_brand.yml` from disk,
+        // exactly as the reveal branch resolves it against the project dir.
+        let dir = tempfile::TempDir::new().unwrap();
+        let root = dir.path().to_path_buf();
+        std::fs::write(
+            root.join("_brand.yml"),
+            "color:\n  palette:\n    purple: \"#6f42c1\"\n  primary: purple\n  \
+             background: \"#fdf6ff\"\n  foreground: \"#2a1a3a\"\n",
+        )
+        .unwrap();
+
+        let content = b"---\ntitle: Brand\nformat:\n  revealjs:\n    brand: _brand.yml\n---\n\n\
+                        ## First\n\nBody.\n";
+
+        let project = ProjectContext {
+            dir: root.clone(),
+            config: crate::project::ProjectConfig::default(),
+            is_single_file: true,
+            files: vec![DocumentInfo::from_path(root.join("deck.qmd"))],
+            output_dir: root.clone(),
+        };
+        let doc = DocumentInfo::from_path(root.join("deck.qmd"));
+        let format = Format::from_format_string("q2-slides").unwrap();
+        let binaries = BinaryDependencies::new();
+        let mut ctx = RenderContext::new(&project, &doc, &format, &binaries);
+
+        let runtime = make_test_runtime();
+        pollster::block_on(render_qmd_to_preview_ast(
+            content,
+            root.join("deck.qmd").to_str().unwrap(),
+            &mut ctx,
+            runtime,
+            None,
+            Vec::new(),
+        ))
+        .expect("q2-slides brand render");
+
+        let theme_entries = ctx.artifacts.get_by_prefix("css:theme:");
+        assert_eq!(theme_entries.len(), 1, "expected one css:theme artifact");
+        let css = theme_entries[0].1.as_str().expect("theme CSS is UTF-8");
+        // Brand background colour folded into the reveal theme proves the brand
+        // reached the compiled output (default reveal background is `#fff`).
+        assert!(
+            css.contains("#fdf6ff"),
+            "brand background must reach the compiled preview theme; got default?"
+        );
+    }
+
     /// Phase 1 (target-incremental-writes): `render_qmd_to_preview_ast` must
     /// return *both* the transformed AST (`ast_json`) and the untransformed
     /// AST (`untransformed_ast_json`).  An unchanged paragraph must have

crates/quarto-core/src/revealjs/assemble.rs

@@ -38,6 +38,15 @@ const QUARTO_REVEAL_CSS: &str = include_str!("../../../../resources/revealjs/qua
 /// (`crate::revealjs::theme`) defaults to this; `white` aliases to it.
 pub const DEFAULT_THEME: &str = "default";
 
+/// The vendored stock reveal theme CSS (`white.css`), used as the theme-slot
+/// fallback when Quarto's reveal-theme SCSS compilation fails so a deck still
+/// renders. Exposed so the `q2 preview` path can deliver the same fallback
+/// through its `css:theme:` transport (see `CompileThemeCssStage`'s reveal
+/// branch).
+pub fn stock_reveal_theme_css() -> &'static str {
+    THEME_WHITE_CSS
+}
+
 /// Kind of a vendored reveal asset (decides the `css:` / `js:` artifact key
 /// prefix and the emitted tag).
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]

crates/quarto-core/src/revealjs/mod.rs

@@ -26,7 +26,9 @@ mod slides;
 mod theme;
 mod transform;
 
-pub use assemble::{DEFAULT_THEME, register_reveal_assets, render_revealjs_document};
+pub use assemble::{
+    DEFAULT_THEME, register_reveal_assets, render_revealjs_document, stock_reveal_theme_css,
+};
 pub use auto_stretch::RevealAutoStretchTransform;
 pub use columns::RevealColumnsTransform;
 pub use footer_logo::{RevealFooterAliasTransform, RevealFooterLogoTransform};