fix(viewer): pin surface iframes to the chrome's resolved color scheme (#103)

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: benvinegar

.changeset/surface-iframe-theme-mode.md

@@ -0,0 +1,16 @@
+---
+"sideshow": patch
+---
+
+Fix surface iframes rendering in the wrong color scheme when it diverges from
+the chrome (e.g. dark chrome with a white, light-inked html part). Light/dark
+was resolved independently in every layer purely from the OS
+`prefers-color-scheme`, but a surface part is a separate iframe document whose
+scheme resolution can diverge from its embedder across the frame boundary. The
+viewer now resolves the scheme once and pins each sandboxed frame to it — html
+parts via a `mode` query param on `/s/:id` (with a forced `color-scheme`), and
+markdown/code/comment frames via `renderSandboxedPart` — so a frame always
+matches the chrome instead of re-deriving the scheme on its own. The theme
+tokens, the kit's teal/coral SVG accents, and shiki's dark flip are all pinned
+together. With no mode passed the OS media query is kept, so self-hosted parity
+is preserved.

e2e/theme.spec.ts

@@ -85,6 +85,82 @@ test("the picked theme persists across a reload", async ({ page, server }) => {
     .toBe("#f9f5d7");
 });
 
+// Regression: the chrome resolves light/dark from the OS via a CSS media query,
+// but an html part is a separate iframe document whose own scheme resolution can
+// diverge from the chrome's across the frame boundary — producing dark chrome
+// with a white, light-inked iframe. The viewer now pins each frame to the mode
+// it resolved (`&mode=` on the src + a forced `color-scheme`), so the iframe
+// renders the SAME scheme as the chrome regardless. The github dark html-part
+// surface (--color-background-primary) is #1c2128 = rgb(28, 33, 40).
+test.describe("with the OS in dark mode", () => {
+  test.use({ colorScheme: "dark" });
+
+  test("the html-part iframe is pinned to dark, matching the chrome", async ({ page, server }) => {
+    await publishParts(server.url, {
+      title: "Themed",
+      agent: "e2e",
+      parts: [{ kind: "html", html: "<p>surface body</p>" }],
+    });
+    await page.goto(server.url);
+
+    const iframe = page.locator(".card iframe[src]");
+    await expect(iframe).toHaveAttribute("src", /mode=dark/);
+
+    // the iframe document actually paints the dark surface — not the light
+    // default it would fall back to if it re-derived the scheme on its own
+    const body = page.locator(".card iframe[src]").contentFrame().locator("body");
+    await expect
+      .poll(() => body.evaluate((el) => getComputedStyle(el).backgroundColor))
+      .toBe("rgb(28, 33, 40)");
+  });
+
+  // The opaque html part forces `color-scheme` (so its UA scrollbars/controls
+  // match), but a markdown part's frame is transparent so the themed card shows
+  // through — forcing `color-scheme:dark` there would paint an opaque UA canvas
+  // behind it. Its tokens are still pinned dark; only color-scheme stays unset.
+  test("a transparent markdown frame is pinned dark but keeps no forced color-scheme", async ({
+    page,
+    server,
+  }) => {
+    await publishParts(server.url, {
+      title: "Prose",
+      agent: "e2e",
+      parts: [{ kind: "markdown", markdown: "regular **prose** body" }],
+    });
+    await page.goto(server.url);
+
+    const frame = page.locator(".card iframe.mdframe").contentFrame();
+    // pinned dark: the chrome text var resolved to the github dark ink
+    await expect
+      .poll(() => frame.locator("body").evaluate((el) => getComputedStyle(el).color))
+      .toBe("rgb(230, 237, 243)");
+    // but the root color-scheme is NOT forced, so the UA canvas stays transparent
+    await expect
+      .poll(() => frame.locator("html").evaluate((el) => getComputedStyle(el).colorScheme))
+      .not.toBe("dark");
+  });
+});
+
+test.describe("with the OS in light mode", () => {
+  test.use({ colorScheme: "light" });
+
+  test("the html-part iframe is pinned to light", async ({ page, server }) => {
+    await publishParts(server.url, {
+      title: "Themed",
+      agent: "e2e",
+      parts: [{ kind: "html", html: "<p>surface body</p>" }],
+    });
+    await page.goto(server.url);
+
+    const iframe = page.locator(".card iframe[src]");
+    await expect(iframe).toHaveAttribute("src", /mode=light/);
+    const body = page.locator(".card iframe[src]").contentFrame().locator("body");
+    await expect
+      .poll(() => body.evaluate((el) => getComputedStyle(el).backgroundColor))
+      .toBe("rgb(255, 255, 255)");
+  });
+});
+
 test("a theme switch in one tab re-themes another open tab via SSE", async ({
   page,
   server,

server/app.ts

@@ -858,12 +858,18 @@ export function createApp({
     // Theme: an explicit ?theme= (the viewer keys iframe srcs by it so a switch
     // reloads the frame) wins; otherwise the persisted board theme; else default.
     const themeId = c.req.query("theme") ?? (await store.getSetting("theme")) ?? DEFAULT_THEME_ID;
+    // Scheme: the viewer passes the light/dark mode it resolved so the iframe is
+    // pinned to it rather than re-deriving from the OS (which can diverge from
+    // the chrome across the frame boundary). Absent/invalid → follow the OS.
+    const modeParam = c.req.query("mode");
+    const mode = modeParam === "light" || modeParam === "dark" ? modeParam : undefined;
     return c.html(
       renderHtmlPage({
         title,
         html: part.html,
         origin: new URL(c.req.url).origin,
         theme: themeById(themeId),
+        mode,
         kits: part.kits,
       }),
     );

server/surfacePage.ts

@@ -1,5 +1,41 @@
 import { kitAssets } from "./kits.ts";
-import { type Theme, themeById, tokenThemeCss, viewerThemeCss } from "./themes.ts";
+import {
+  type Mode,
+  schemeCss,
+  type Theme,
+  themeById,
+  tokenThemeCss,
+  viewerThemeCss,
+} from "./themes.ts";
+
+// The kit's two custom SVG accent ramps (teal, coral) aren't in the theme
+// palette, so they carry their own light/dark values. Like the theme tokens
+// they pin to a forced mode (no media query) when one is given, else flip with
+// the OS — kept in sync via the shared schemeCss. Dark overrides only bg/text;
+// the line color is shared, so it's repeated in both maps.
+const KIT_ACCENTS_LIGHT: Record<string, string> = {
+  "c-teal-bg": "#e1f4f1",
+  "c-teal-line": "#1fa996",
+  "c-teal-text": "#0c6e62",
+  "c-coral-bg": "#fdece5",
+  "c-coral-line": "#e8835e",
+  "c-coral-text": "#a44f28",
+};
+const KIT_ACCENTS_DARK: Record<string, string> = {
+  ...KIT_ACCENTS_LIGHT,
+  "c-teal-bg": "rgba(31, 169, 150, 0.18)",
+  "c-teal-text": "#6fd0c2",
+  "c-coral-bg": "rgba(232, 131, 94, 0.18)",
+  "c-coral-text": "#f0a987",
+};
+const kitAccentCss = (mode?: Mode): string => schemeCss(KIT_ACCENTS_LIGHT, KIT_ACCENTS_DARK, mode);
+
+// When a scheme is pinned, force the document's used color-scheme to match so
+// the UA-painted canvas, scrollbars, and native form controls follow it too
+// (the token vars alone don't drive those). Overrides the static
+// `color-scheme: light dark` default the kit/base CSS sets. Empty when the
+// scheme is left to the OS, preserving the media-query behavior unchanged.
+const colorSchemeCss = (mode?: Mode): string => (mode ? `:root{color-scheme:${mode}}` : "");
 
 // Origins html parts may load external resources from. Mirrors the allowlist
 // agents already know from Claude's inline widget surface.
@@ -63,17 +99,7 @@ body {
 // attributes (fill/font-size on text, etc.) — that's why text styling is
 // opt-in via classes.
 const KIT_CSS = `
-:root {
-  color-scheme: light dark;
-  --c-teal-bg: #e1f4f1; --c-teal-line: #1fa996; --c-teal-text: #0c6e62;
-  --c-coral-bg: #fdece5; --c-coral-line: #e8835e; --c-coral-text: #a44f28;
-}
-@media (prefers-color-scheme: dark) {
-  :root {
-    --c-teal-bg: rgba(31, 169, 150, 0.18); --c-teal-text: #6fd0c2;
-    --c-coral-bg: rgba(232, 131, 94, 0.18); --c-coral-text: #f0a987;
-  }
-}
+:root { color-scheme: light dark; }
 button {
   font: 500 14px/1.4 var(--font-sans);
   color: var(--color-text-primary);
@@ -210,11 +236,18 @@ function buildRichCsp(origin: string): string {
 // mermaid / DOMPurify / @pierre-diffs sanitizer bypass can no longer reach the
 // board. `css` is the part-specific stylesheet (prose/diff/mermaid rules);
 // chrome theme vars come from viewerThemeCss so the part matches the viewer.
+// `mode` PINS those vars (and any shiki dark-flip the css carries) to the
+// scheme the chrome resolved, so this frame can't diverge from it. Unlike an
+// html part, it deliberately does NOT force `color-scheme`: these frames are
+// transparent so the themed card surface shows through, and a forced
+// `color-scheme` would paint an opaque UA canvas behind them. They carry no
+// native scrollbars/controls that need it, so the var pinning alone suffices.
 export function renderSandboxedPart(doc: {
   body: string;
   css: string;
   origin: string;
   theme?: Theme | string;
+  mode?: Mode;
 }): string {
   const theme =
     typeof doc.theme === "string" || doc.theme == null ? themeById(doc.theme) : doc.theme;
@@ -229,7 +262,7 @@ export function renderSandboxedPart(doc: {
      img-src in buildRichCsp allows that origin. (html parts don't need this —
      they load via /s/:id, whose URL is already the base.) -->
 <base href="${doc.origin}/">
-<style>${viewerThemeCss(theme)}${doc.css}</style>
+<style>${viewerThemeCss(theme, doc.mode)}${doc.css}</style>
 </head>
 <body>
 ${doc.body}
@@ -243,6 +276,9 @@ export function renderHtmlPage(doc: {
   html: string;
   origin: string;
   theme?: Theme | string;
+  // Pins the iframe's color scheme to the one the chrome resolved (see Mode).
+  // Omitted → the scheme follows the OS via tokenThemeCss's media query.
+  mode?: Mode;
   // Opt-in kits (kits.ts): their CSS/JS is injected after the base kit. The JS
   // is plain inline script — same trust level as the bridge, already covered by
   // the html-part CSP's `script-src 'unsafe-inline'`. Unknown ids are ignored.
@@ -258,7 +294,7 @@ export function renderHtmlPage(doc: {
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <meta http-equiv="Content-Security-Policy" content="${buildCsp(doc.origin)}">
 <title>${escapeHtml(doc.title)}</title>
-<style>${tokenThemeCss(theme)}${TOKENS_CSS}${KIT_CSS}${kit.css}</style>
+<style>${tokenThemeCss(theme, doc.mode)}${TOKENS_CSS}${KIT_CSS}${kitAccentCss(doc.mode)}${kit.css}${colorSchemeCss(doc.mode)}</style>
 </head>
 <body>
 ${SVG_DEFS}

server/themes.ts

@@ -41,6 +41,12 @@ export interface Theme {
   dark: Palette;
 }
 
+// A resolved color scheme. The chrome resolves this from the OS via a CSS
+// `@media (prefers-color-scheme)` query; surface iframes are separate documents
+// that don't reliably inherit that resolution, so the viewer passes the mode it
+// resolved into each frame to pin it to the chrome (see surfacePage / Card).
+export type Mode = "light" | "dark";
+
 // Viewer chrome variables (styles.css names). Accent maps to the info state.
 function viewerVars(p: Palette): Record<string, string> {
   return {
@@ -105,21 +111,35 @@ const block = (vars: Record<string, string>) =>
     .join("");
 
 // `:root` light + a `prefers-color-scheme: dark` override — emitted as a
-// <style> so the automatic OS light/dark flip keeps working with no JS.
-function schemeCss(light: Record<string, string>, dark: Record<string, string>): string {
+// <style> so the automatic OS light/dark flip keeps working with no JS. When
+// `mode` is given the scheme is PINNED to it instead: a single flat `:root`
+// block with no media query, so the document renders that mode regardless of
+// the OS preference. The viewer uses this to force a surface iframe to the mode
+// the chrome already resolved, since an iframe is a separate document whose
+// `prefers-color-scheme` evaluation can diverge from its embedder's.
+export function schemeCss(
+  light: Record<string, string>,
+  dark: Record<string, string>,
+  mode?: Mode,
+): string {
+  if (mode === "light") return `:root{${block(light)}}`;
+  if (mode === "dark") return `:root{${block(dark)}}`;
   return `:root{${block(light)}}@media (prefers-color-scheme: dark){:root{${block(dark)}}}`;
 }
 
 // Viewer chrome palette CSS (injected into the viewer document head). The
 // scheme-flipping chrome vars, plus the terminal vars which are scheme-
 // independent (always the dark palette) so they sit outside the media query.
-export function viewerThemeCss(t: Theme): string {
-  return `${schemeCss(viewerVars(t.light), viewerVars(t.dark))}:root{${block(termVars(t.dark))}}`;
+// `mode` pins the scheme (see schemeCss) — used for the rich-part iframes the
+// chrome renders via renderSandboxedPart, not the chrome's own <head>.
+export function viewerThemeCss(t: Theme, mode?: Mode): string {
+  return `${schemeCss(viewerVars(t.light), viewerVars(t.dark), mode)}:root{${block(termVars(t.dark))}}`;
 }
 
-// Html-part token CSS (injected into each sandboxed surface iframe).
-export function tokenThemeCss(t: Theme): string {
-  return schemeCss(tokenVars(t.light), tokenVars(t.dark));
+// Html-part token CSS (injected into each sandboxed surface iframe). `mode`
+// pins the scheme so the iframe matches the chrome (see schemeCss).
+export function tokenThemeCss(t: Theme, mode?: Mode): string {
+  return schemeCss(tokenVars(t.light), tokenVars(t.dark), mode);
 }
 
 export const THEMES: Theme[] = [

test/surfacePage.test.ts

@@ -1,6 +1,7 @@
 import assert from "node:assert/strict";
 import { test } from "node:test";
 import { escapeHtml, renderHtmlPage, renderSandboxedPart } from "../server/surfacePage.ts";
+import { themeById } from "../server/themes.ts";
 
 const ORIGIN = "http://localhost:4000";
 
@@ -117,6 +118,47 @@ test("theme tokens are injected and resolve unknown/absent themes to the default
   );
 });
 
+test("a pinned mode forces the scheme into html parts but not transparent rich frames", () => {
+  const gh = renderHtmlPage({ title: "t", html: "<p>x</p>", origin: ORIGIN, mode: "dark" });
+  // the document's used color-scheme is forced so the UA canvas/scrollbars/
+  // controls follow it, overriding the static `color-scheme: light dark` default
+  assert.ok(/:root\{color-scheme:dark\}/.test(gh), "color-scheme must be pinned to dark");
+  // and EVERYTHING that flips by scheme is pinned: the theme tokens AND the kit's
+  // own teal/coral SVG accents — so no `@media (prefers-color-scheme)` survives to
+  // second-guess the scheme inside the frame
+  assert.ok(
+    !gh.includes("@media (prefers-color-scheme: dark)"),
+    "pinned mode drops the media query",
+  );
+  assert.ok(gh.includes("--c-teal-bg: rgba(31, 169, 150, 0.18)"), "kit teal accent pinned to dark");
+
+  // light pins the other way; absent mode keeps the OS-driven media query
+  const light = renderHtmlPage({ title: "t", html: "<p>x</p>", origin: ORIGIN, mode: "light" });
+  assert.ok(/:root\{color-scheme:light\}/.test(light), "color-scheme must be pinned to light");
+  const auto = renderHtmlPage({ title: "t", html: "<p>x</p>", origin: ORIGIN });
+  assert.ok(!auto.includes("color-scheme:dark"), "no mode → no forced scheme");
+  assert.ok(auto.includes("@media (prefers-color-scheme: dark)"), "no mode → OS media query kept");
+
+  // rich/comment frames pin the same way — EXCEPT color-scheme. Those frames are
+  // transparent so the themed card surface shows through; a forced color-scheme
+  // would paint an opaque UA canvas behind them. So the tokens are pinned (flat
+  // :root, dark --text, no media query) but color-scheme is left unset.
+  const rich = renderSandboxedPart({ body: "x", css: "", origin: ORIGIN, mode: "dark" });
+  const dark = themeById("github").dark;
+  assert.ok(
+    !rich.includes("color-scheme:"),
+    "rich frame must NOT force color-scheme (stays transparent)",
+  );
+  assert.ok(
+    !rich.includes("@media (prefers-color-scheme: dark)"),
+    "rich tokens are pinned, no media query",
+  );
+  assert.ok(
+    rich.includes(`--text: ${dark.text}`),
+    "rich frame carries the pinned dark chrome vars",
+  );
+});
+
 test("renderSandboxedPart embeds the body and css inside the sandbox doc", () => {
   const doc = renderSandboxedPart({
     body: "<p>hello</p>",

test/themes.test.ts

@@ -99,3 +99,37 @@ test("tokenThemeCss emits the agent-facing --color-* tokens for each theme", ()
     );
   }
 });
+
+// A pinned mode emits a single flat :root with that scheme's values and NO
+// media query, so a surface iframe renders the mode the chrome resolved rather
+// than re-deriving it from the OS across the frame boundary.
+test("a pinned mode forces the scheme with no prefers-color-scheme media query", () => {
+  const gh = themeById("github");
+
+  const dark = tokenThemeCss(gh, "dark");
+  assert.ok(!dark.includes("@media"), "dark mode must not emit a media query");
+  // github dark surface is the html-part background-primary token
+  assert.ok(dark.includes(`--color-background-primary: ${gh.dark.surface}`), "dark bg token");
+  assert.ok(!dark.includes(gh.light.surface), "dark output must not carry light values");
+
+  const light = tokenThemeCss(gh, "light");
+  assert.ok(!light.includes("@media"), "light mode must not emit a media query");
+  assert.ok(light.includes(`--color-background-primary: ${gh.light.surface}`), "light bg token");
+
+  // viewerThemeCss pins the same way (used for rich-part iframes)
+  const vdark = viewerThemeCss(gh, "dark");
+  assert.ok(!vdark.includes("@media"), "viewer dark mode must not emit a media query");
+  assert.ok(vdark.includes(`--bg: ${gh.dark.bg}`), "viewer dark --bg");
+  // terminal vars still ride along (always the dark palette, scheme-independent)
+  assert.ok(vdark.includes("--term-bg:"), "viewer keeps terminal vars when pinned");
+});
+
+test("omitting the mode preserves the OS media-query behavior unchanged", () => {
+  const gh = themeById("github");
+  for (const css of [tokenThemeCss(gh), tokenThemeCss(gh, undefined), viewerThemeCss(gh)]) {
+    assert.ok(
+      css.includes("@media (prefers-color-scheme: dark)"),
+      "no-mode output keeps the dark-scheme override",
+    );
+  }
+});