@jxsuite/studio 1.1.0 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/studio",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Jx Studio — visual builder for Jx documents",
   "license": "MIT",
   "repository": {
@@ -39,13 +39,13 @@
     "@atlaskit/pragmatic-drag-and-drop": "^2.0.1",
     "@atlaskit/pragmatic-drag-and-drop-hitbox": "^2.0.0",
     "@jxsuite/ai": "^0.33.0",
-    "@jxsuite/collab": "^0.4.0",
-    "@jxsuite/create": "^1.1.0",
-    "@jxsuite/formulas": "^0.0.2",
-    "@jxsuite/markup": "^0.3.0",
-    "@jxsuite/protocol": "^0.5.0",
-    "@jxsuite/runtime": "^1.1.0",
-    "@jxsuite/schema": "^1.1.0",
+    "@jxsuite/collab": "^0.4.1",
+    "@jxsuite/create": "^1.1.1",
+    "@jxsuite/formulas": "^0.0.3",
+    "@jxsuite/markup": "^0.3.1",
+    "@jxsuite/protocol": "^0.5.1",
+    "@jxsuite/runtime": "^1.2.0",
+    "@jxsuite/schema": "^1.2.0",
     "@spectrum-web-components/accordion": "^1.12.2",
     "@spectrum-web-components/action-bar": "1.12.2",
     "@spectrum-web-components/action-button": "^1.12.2",

package/src/canvas/iframe-entry.ts

@@ -6,7 +6,12 @@
  */
 
 import { postMessageChannel } from "./iframe-channel";
-import { installCanvasImageRetry, renderResolvedDocument } from "./iframe-render";
+import {
+  applyPreviewColorScheme,
+  applySiteStyle,
+  installCanvasImageRetry,
+  renderResolvedDocument,
+} from "./iframe-render";
 import { measureHits, startInteraction } from "./iframe-interaction";
 import {
   AUTO_SCROLL_STEP,
@@ -482,9 +487,20 @@ export function startCanvasIframe(opts: {
       clearIframeDrag();
       return;
     }
+    if (msg.kind === "setColorScheme") {
+      // Document-level attribute flip — deliberately patch-free (no render, no gen).
+      applyPreviewColorScheme(container.ownerDocument, msg.scheme);
+      return;
+    }
+    if (msg.kind === "siteStyleUpdate") {
+      // Live design-token edit: swap the site-style sheet in place, no re-render.
+      applySiteStyle(msg.siteStyle, msg.media);
+      return;
+    }
     if (msg.kind !== "render" || msg.gen < latestGen) {
       return;
     }
+    applyPreviewColorScheme(container.ownerDocument, msg.colorScheme ?? null);
     // A render replaces the DOM under a live edit session — COMMIT it first (never discard). The
     // Resulting editCommit/editEnd post synchronously here, so on the FIFO channel they precede
     // This render's renderComplete and the parent routes them by the host's not-yet-flipped tab

package/src/canvas/iframe-host.ts

@@ -24,7 +24,15 @@ import { clearDragGhost, moveDragGhost } from "../panels/drag-ghost";
 import { applyDropInstruction } from "../panels/dnd";
 import { rectOf } from "../utils/geometry";
 import { effect, effectScope } from "../reactivity";
-import { canvasPanels, canvasWrap, pathsEqual, renderOnly, updateCanvas, updateUi } from "../store";
+import {
+  canvasPanels,
+  canvasWrap,
+  pathsEqual,
+  projectState,
+  renderOnly,
+  updateCanvas,
+  updateUi,
+} from "../store";
 import { activeTab, workspace } from "../workspace/workspace";
 import { collabState } from "../collab/collab-state";
 import { getPlatform, hasPlatform } from "../platform";
@@ -1370,6 +1378,7 @@ export async function mountIframeCanvas(
   // oxlint-disable-next-line unicorn/prefer-structured-clone
   const cloneableShadow = JSON.parse(JSON.stringify(doc)) as unknown;
   const message: ParentToIframe = {
+    colorScheme: activeSchemeWire(),
     doc: cloneableDoc,
     docBase: resolved.docBase ?? `${canvasBaseOrigin()}/`,
     gen,
@@ -1419,6 +1428,7 @@ export function mountStylebookCanvas(
   // oxlint-disable-next-line unicorn/prefer-structured-clone
   const cloneableShadow = JSON.parse(JSON.stringify(generated.doc)) as unknown;
   const message: ParentToIframe = {
+    colorScheme: activeSchemeWire(),
     doc: cloneableDoc,
     docBase: `${canvasBaseOrigin()}/`,
     gen,
@@ -1443,6 +1453,57 @@ export function mountStylebookCanvas(
   }
 }
 
+/** The active tab's forced preview scheme as wire data (auto → null). */
+function activeSchemeWire(): "light" | "dark" | null {
+  const s = activeTab.value?.session.ui.previewColorScheme;
+  return s === "light" || s === "dark" ? s : null;
+}
+
+/**
+ * Flip the color-scheme preview on every ready host (page and stylebook alike — both render
+ * scheme-aware CSS). A pure attribute write iframe-side: no render, no patch, no gen.
+ */
+export function postColorSchemeToLiveHosts(scheme: "light" | "dark" | null): void {
+  for (const host of liveHosts) {
+    if (!host.iframe.isConnected) {
+      liveHosts.delete(host);
+      continue;
+    }
+    if (host.ready) {
+      host.channel.post({ kind: "setColorScheme", scheme });
+    }
+  }
+}
+
+/**
+ * Push the project's current site style to every ready PAGE host as an in-place sheet replace (live
+ * design-token editing — stylebook hosts pre-merge site style into the specimen doc and are
+ * skipped). Render-free; the next full render carries the same style via its own siteStyle.
+ */
+export function postSiteStyleToLiveHosts(): void {
+  const config = projectState?.projectConfig;
+  if (!config) {
+    return;
+  }
+  // Site config comes off a reactive store — only plain values may cross postMessage.
+  // oxlint-disable-next-line unicorn/prefer-structured-clone
+  const siteStyle = JSON.parse(JSON.stringify(config.style ?? null)) as Record<
+    string,
+    unknown
+  > | null;
+  // oxlint-disable-next-line unicorn/prefer-structured-clone
+  const media = JSON.parse(JSON.stringify(config.$media ?? {})) as Record<string, string>;
+  for (const host of liveHosts) {
+    if (!host.iframe.isConnected) {
+      liveHosts.delete(host);
+      continue;
+    }
+    if (host.ready && !host.stylebook) {
+      host.channel.post({ kind: "siteStyleUpdate", media, siteStyle });
+    }
+  }
+}
+
 /**
  * Post a live style update to every ready stylebook host (gen-tagged per host so a stale update is
  * dropped iframe-side; the superseding render carries the same style). Returns how many hosts

package/src/canvas/iframe-protocol.ts

@@ -61,8 +61,21 @@ export type ParentToIframe =
       docBase: string;
       mapperCtx: WireMapperCtx;
       siteStyle: Record<string, unknown> | null;
+      // Forced color-scheme preview (spec §9.5): "light"/"dark" sets data-color-scheme on the
+      // Iframe root, null clears it (auto — follow the OS).
+      colorScheme: "light" | "dark" | null;
       gen: number;
     }
+  // Flip the forced color-scheme preview on the iframe root without re-rendering — a document-level
+  // Idempotent attribute write, deliberately gen-less (like endEdit).
+  | { kind: "setColorScheme"; scheme: "light" | "dark" | null }
+  // Replace the injected site-style sheet in place (live design-token editing) — idempotent and
+  // Render-free; the superseding render carries the same style via its own siteStyle.
+  | {
+      kind: "siteStyleUpdate";
+      siteStyle: Record<string, unknown> | null;
+      media: Record<string, string>;
+    }
   // Ask the iframe to measure the given document paths and post their current rects back. Used to
   // Draw the selection overlay regardless of where the selection change originated (canvas click,
   // Layers panel, keyboard) — the parent can't measure iframe nodes itself (cross-origin bridge).

package/src/canvas/iframe-render.ts

@@ -24,6 +24,7 @@ import {
   transposeCanvasUnits,
 } from "@jxsuite/runtime";
 import { classifyRenderNode, serializeJxPath } from "./path-mapping";
+import { SITE_STYLE_ID, buildSiteStyleCSS } from "./site-style-css";
 import type { CanvasMode } from "./iframe-protocol";
 import type { JxDocument } from "@jxsuite/schema/types";
 import type { PathMapCtx } from "./path-mapping";
@@ -294,22 +295,42 @@ export function syncStylebookCss(doc: Document, mode: CanvasMode): void {
   doc.head.append(style);
 }
 
-/** Apply the project's site style: custom properties on :root, plain properties on <body>. */
-export function applySiteStyle(siteStyle: Record<string, unknown> | null | undefined): void {
+/**
+ * Apply the project's site style as a real stylesheet (replace-in-place): custom properties on
+ * `:root`, plain properties on `body`, conditional blocks dual-emitted per the forced-scheme
+ * contract. A stylesheet — not inline root properties — so `:root[data-color-scheme]` override
+ * selectors can win (spec §9.5), and so removed tokens can't linger on reused iframes.
+ */
+export function applySiteStyle(
+  siteStyle: Record<string, unknown> | null | undefined,
+  mediaQueries: Record<string, string> = {},
+): void {
+  const existing = document.head.querySelector(`#${SITE_STYLE_ID}`);
   if (!siteStyle || typeof siteStyle !== "object") {
+    existing?.remove();
     return;
   }
-  const rootStyle = document.documentElement.style;
-  const bodyStyle = document.body.style as unknown as Record<string, string>;
-  for (const [key, value] of Object.entries(siteStyle)) {
-    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
-      continue;
-    }
-    if (key.startsWith("--")) {
-      rootStyle.setProperty(key, transposeCanvasUnits(String(value)));
-    } else {
-      bodyStyle[key] = transposeCanvasUnits(String(value));
-    }
+  const css = buildSiteStyleCSS(siteStyle, mediaQueries, transposeCanvasUnits);
+  if (existing) {
+    existing.textContent = css;
+    return;
+  }
+  const tag = document.createElement("style");
+  tag.id = SITE_STYLE_ID;
+  tag.textContent = css;
+  document.head.append(tag);
+}
+
+/**
+ * Force or clear the color-scheme preview on the iframe's root element (the platform's
+ * data-color-scheme contract, spec §9.5). Survives re-renders and patches — renders only replace
+ * the container's children, never the root element.
+ */
+export function applyPreviewColorScheme(doc: Document, scheme: "light" | "dark" | null): void {
+  if (scheme) {
+    doc.documentElement.dataset.colorScheme = scheme;
+  } else {
+    delete doc.documentElement.dataset.colorScheme;
   }
 }
 
@@ -443,7 +464,7 @@ export async function renderResolvedDocument(opts: {
   // Iframe clears it (page-level templates are inert in design/edit via prepareForEditMode, so only
   // Component internals get stamped).
   setStampPropBindings(opts.mode === "design" || opts.mode === "edit");
-  applySiteStyle(opts.siteStyle);
+  applySiteStyle(opts.siteStyle, (opts.doc as { $media?: Record<string, string> }).$media ?? {});
   injectHead(opts.doc);
   syncEditModeCss(opts.container.ownerDocument, opts.mode);
   syncStylebookCss(opts.container.ownerDocument, opts.mode);

package/src/canvas/site-style-css.ts

@@ -0,0 +1,121 @@
+/// <reference lib="dom" />
+/**
+ * Site-style stylesheet builder — pure functions extracted for testability.
+ *
+ * The canvas iframe injects the project's `style` as a real stylesheet instead of inline properties
+ * on the root element: inline custom properties would defeat the forced-scheme override selectors
+ * (`:root[data-color-scheme]`, spec §9.5), and object-valued `@--name` blocks used to be dropped
+ * entirely. Scheme-query blocks dual-emit through the runtime's schemeSelectors so the canvas
+ * honors both the OS preference and the preview toggle.
+ */
+
+import { pureSchemeOf, schemeSelectors, camelToKebab } from "@jxsuite/runtime";
+
+/** Id of the injected site-style tag (replace-in-place, never accumulate). */
+export const SITE_STYLE_ID = "jx-site-style";
+
+/** Serialize scalar declarations, kebab-casing property names and transposing values. */
+function toDecls(props: Record<string, unknown>, transpose: (value: string) => string): string {
+  return Object.entries(props)
+    .map(([key, value]) => `${camelToKebab(key)}: ${transpose(String(value))}`)
+    .join("; ");
+}
+
+/**
+ * Build the site-style sheet text: custom properties on `:root`, plain properties on `body`,
+ * conditional `@`-blocks resolved against `mediaQueries` (scheme queries dual-emitted per the
+ * forced-scheme contract), and `color-scheme: light dark` declared when a scheme query exists.
+ *
+ * @param {Record<string, unknown>} siteStyle
+ * @param {Record<string, string>} mediaQueries
+ * @param {(value: string) => string} transpose - Unit transposer (canvas vh→cqh etc.)
+ * @returns {string}
+ */
+export function buildSiteStyleCSS(
+  siteStyle: Record<string, unknown>,
+  mediaQueries: Record<string, string>,
+  transpose: (value: string) => string,
+): string {
+  const rules: string[] = [];
+  const rootProps: Record<string, unknown> = {};
+  const bodyProps: Record<string, unknown> = {};
+  const condBlocks: [string, Record<string, unknown>][] = [];
+
+  for (const [key, value] of Object.entries(siteStyle)) {
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+      if (key.startsWith("@")) {
+        condBlocks.push([key, value as Record<string, unknown>]);
+      }
+      // Non-@ objects (nested element selectors) are page-content styling — the resolved doc's
+      // Own style pass covers those; the site sheet handles tokens + conditional overrides.
+      continue;
+    }
+    if (key.startsWith(":") || key.startsWith(".") || key.startsWith("[") || key.startsWith("@")) {
+      continue;
+    }
+    if (key.startsWith("--")) {
+      rootProps[key] = value;
+    } else {
+      bodyProps[key] = value;
+    }
+  }
+
+  const rootCSS = toDecls(rootProps, transpose);
+  if (rootCSS) {
+    rules.push(`:root { ${rootCSS} }`);
+  }
+  const bodyCSS = toDecls(bodyProps, transpose);
+  if (bodyCSS) {
+    rules.push(`body { ${bodyCSS} }`);
+  }
+
+  for (const [atKey, block] of condBlocks) {
+    const query = atKey.startsWith("@--")
+      ? (mediaQueries[atKey.slice(1)] ?? atKey.slice(1))
+      : atKey.startsWith("@(")
+        ? atKey.slice(1)
+        : null;
+    if (query === null) {
+      continue;
+    }
+    const scheme = pureSchemeOf(query);
+    const emit = (selector: string, props: string) => {
+      if (!props) {
+        return;
+      }
+      if (scheme) {
+        const { auto, forced } = schemeSelectors(selector, scheme);
+        rules.push(`@media ${query} { ${auto} { ${props} } }`, `${forced} { ${props} }`);
+      } else {
+        rules.push(`@media ${query} { ${selector} { ${props} } }`);
+      }
+    };
+    const condRoot: Record<string, unknown> = {};
+    const condBody: Record<string, unknown> = {};
+    const condSubs: [string, Record<string, unknown>][] = [];
+    for (const [k, v] of Object.entries(block)) {
+      if (v !== null && typeof v === "object" && !Array.isArray(v)) {
+        if (!k.startsWith("@")) {
+          condSubs.push([k, v as Record<string, unknown>]);
+        }
+        continue;
+      }
+      if (k.startsWith("--")) {
+        condRoot[k] = v;
+      } else {
+        condBody[k] = v;
+      }
+    }
+    emit(":root", toDecls(condRoot, transpose));
+    emit("body", toDecls(condBody, transpose));
+    for (const [sel, sub] of condSubs) {
+      emit(sel, toDecls(sub, transpose));
+    }
+  }
+
+  if (Object.values(mediaQueries).some((q) => pureSchemeOf(q) !== null)) {
+    rules.push(":root { color-scheme: light dark }");
+  }
+
+  return rules.join("\n");
+}

package/src/panels/ai-panel.ts

@@ -21,7 +21,7 @@ import type { TemplateResult } from "lit-html";
 import { getPlatform } from "../platform";
 import { effect, effectScope } from "../reactivity";
 import { createDocumentAssistant } from "../services/document-assistant";
-import { hasOpenAiKey } from "../services/ai-settings";
+import { hasOpenAiKey, setOpenAiKey } from "../services/ai-settings";
 import { fetchAvailableModels, isManagedProxy, isProxyConfigured } from "../services/ai-models";
 import { createAiCredentialsForm } from "../ui/ai-credentials-form";
 import { clearMarkdownCache } from "./ai-chat/chat-markdown";
@@ -263,6 +263,58 @@ export async function seedAssistantPrompt(text: string): Promise<void> {
   await handleAssistantSend(text);
 }
 
+// ─── Automation seeding (screenshot runner) ─────────────────────────────────
+
+/** A canned tool-call chip for {@link seedAssistantMessages}. */
+export interface SeededToolCall {
+  name: string;
+  /** JSON-encoded arguments, e.g. `{"path":["children",0],"text":"…"}`. */
+  arguments: string;
+}
+
+/** A canned transcript entry for {@link seedAssistantMessages}. */
+export interface SeededAssistantMessage {
+  role: "user" | "assistant";
+  content: string;
+  toolCalls?: SeededToolCall[];
+}
+
+let seededCount = 0;
+
+/**
+ * Automation-only seam (scripts/screenshots): stage a canned conversation without ever invoking a
+ * model. Stores an inert demo key so the key gate opens (localStorage-only on the dev server — no
+ * request fires), switches to the chat view, and pushes fully-formed messages straight into the
+ * reactive chat state — the same path session restore uses — so the panel repaints through its
+ * normal watcher.
+ */
+export function seedAssistantMessages(messages: SeededAssistantMessage[]): void {
+  setOpenAiKey("sk-demo");
+  keyEditing = false;
+  view = "chat";
+  stickToBottom = true;
+  for (const msg of messages) {
+    seededCount += 1;
+    const seq = seededCount;
+    assistant.chatState.messages.push({
+      content: msg.content,
+      id: `seeded_${seq}`,
+      role: msg.role,
+      timestamp: seq,
+      ...(msg.toolCalls
+        ? {
+            toolCalls: msg.toolCalls.map((tc, i) => ({
+              arguments: tc.arguments,
+              id: `seeded_${seq}_tc${i}`,
+              name: tc.name,
+            })),
+          }
+        : {}),
+    });
+  }
+  scheduleAiRender();
+}
+
 // ─── Controls ─────────────────────────────────────────────────────────────────
 
 function stop() {

package/src/panels/style-panel.ts

@@ -23,7 +23,7 @@ import {
 import { inferInputType, propLabel } from "../utils/studio-utils";
 import { renderFieldRow } from "../ui/field-row";
 import { renderDynamicSlot } from "../ui/dynamic-slot";
-import { parseMediaEntries } from "../utils/canvas-media";
+import { parseMediaEntries, schemeOfQuery } from "../utils/canvas-media";
 import { getEffectiveMedia, getEffectiveStyle } from "../site-context";
 import { computeInheritedStyle } from "../utils/inherited-style";
 import { mediaDisplayName } from "./shared";
@@ -313,6 +313,20 @@ function styleSidebarTemplate(
   const mediaNames = sizeBreakpoints.map((bp) => bp.name);
   const mediaTab = activeMediaTab || null;
 
+  // ── Scheme-layer routing (spec §9.5) ────────────────────────────────────────
+  // With the tab-bar scheme control forcing a scheme that has a matching declared scheme query,
+  // Base-context edits target that scheme's `@--name` block — no extra sidebar tabs. Breakpoint
+  // Tabs stay breakpoint-scoped (scheme × breakpoint compound blocks are unsupported).
+  const forcedScheme = tab.session.ui.previewColorScheme;
+  const schemeLayer =
+    mediaTab === null && (forcedScheme === "light" || forcedScheme === "dark")
+      ? (Object.entries(getEffectiveMedia(tab.doc.document.$media) ?? {}).find(
+          ([, q]) => schemeOfQuery(String(q)) === forcedScheme,
+        )?.[0] ?? null)
+      : null;
+  // The media context edits actually target: a valid breakpoint tab, else the scheme layer.
+  const editMedia = mediaTab && mediaNames.length > 0 ? mediaTab : schemeLayer;
+
   // ── Media tabs template ──────────────────────────────────────────────────
   const mediaTabsT =
     mediaNames.length > 0
@@ -337,7 +351,9 @@ function styleSidebarTemplate(
       : nothing;
 
   // ── Selector dropdown ──────────────────────────────────────────────────────
-  const contextStyle = mediaTab ? (style[`@${mediaTab}`] as Record<string, unknown>) || {} : style;
+  const contextStyle = editMedia
+    ? (style[`@${editMedia}`] as Record<string, unknown>) || {}
+    : style;
   const existingSelectors = Object.keys(contextStyle).filter((s) => isNestedSelector(s));
   const existingSet = new Set(existingSelectors);
   const commonSet = new Set(COMMON_SELECTORS);
@@ -413,10 +429,21 @@ function styleSidebarTemplate(
     </sp-picker>
   `;
 
-  // ── Combined toolbar (media tabs + selector) ───────────────────────────────
+  // ── Combined toolbar (media tabs + scheme badge + selector) ────────────────
+  // No scheme tabs — the tab-bar control is the one switch; the badge shows where edits land.
+  const schemeBadgeT = schemeLayer
+    ? html`
+        <span
+          class="style-scheme-badge"
+          title="Edits target the @${schemeLayer} variant — set the tab-bar scheme control to Auto to edit base styles"
+        >
+          ${mediaDisplayName(schemeLayer)} variant
+        </span>
+      `
+    : nothing;
   const toolbarT = html`
     <div class="style-toolbar">
-      <div class="style-toolbar-tabs">${mediaTabsT}</div>
+      <div class="style-toolbar-tabs">${mediaTabsT} ${schemeBadgeT}</div>
       ${selectorT}
     </div>
   `;
@@ -450,15 +477,15 @@ function styleSidebarTemplate(
   // ── Determine the active style object ──────────────────────────────────────
   let activeStyle: JxStyle;
   let commitMutate: StyleMutateFn;
-  if (activeSelector && isTagPath(activeSelector) && mediaTab && mediaNames.length > 0) {
-    const mediaObj = getNestedStyle(style, `@${mediaTab}`) ?? {};
+  if (activeSelector && isTagPath(activeSelector) && editMedia) {
+    const mediaObj = getNestedStyle(style, `@${editMedia}`) ?? {};
     activeStyle = resolveNestedTagStyle(mediaObj, activeSelector);
     const stylePath = activeSelector.split(" ");
     commitMutate = (t: Tab, prop: string, val: string | Record<string, unknown> | undefined) =>
       mutateUpdateMediaNestedStylePath(
         t,
         sel,
-        mediaTab,
+        editMedia,
         stylePath,
         prop,
         val as string | undefined,
@@ -468,14 +495,14 @@ function styleSidebarTemplate(
     const stylePath = activeSelector.split(" ");
     commitMutate = (t: Tab, prop: string, val: string | Record<string, unknown> | undefined) =>
       mutateUpdateNestedStylePath(t, sel, stylePath, prop, val as string | undefined);
-  } else if (activeSelector && mediaTab && mediaNames.length > 0) {
-    const mediaObj = getNestedStyle(style, `@${mediaTab}`) ?? {};
+  } else if (activeSelector && editMedia) {
+    const mediaObj = getNestedStyle(style, `@${editMedia}`) ?? {};
     activeStyle = getNestedStyle(mediaObj, activeSelector) ?? {};
     commitMutate = (t: Tab, prop: string, val: string | Record<string, unknown> | undefined) =>
       mutateUpdateMediaNestedStyle(
         t,
         sel,
-        mediaTab,
+        editMedia,
         activeSelector,
         prop,
         val as string | undefined,
@@ -486,29 +513,32 @@ function styleSidebarTemplate(
       mutateUpdateNestedStyle(t, sel, activeSelector, prop, val as string | undefined);
   } else {
     activeStyle = {};
-    const inMediaTab = mediaTab !== null && mediaNames.length > 0;
-    const flatSource = inMediaTab ? (getNestedStyle(style, `@${mediaTab}`) ?? {}) : style;
+    const inMediaCtx = editMedia !== null;
+    const flatSource = inMediaCtx ? (getNestedStyle(style, `@${editMedia}`) ?? {}) : style;
     for (const [p, v] of Object.entries(flatSource)) {
       if (typeof v !== "object") {
         activeStyle[p] = v;
       }
     }
-    commitMutate = inMediaTab
+    commitMutate = inMediaCtx
       ? (t: Tab, prop: string, val: string | Record<string, unknown> | undefined) =>
-          mutateUpdateMediaStyle(t, sel, mediaTab, prop, val as string | undefined)
+          mutateUpdateMediaStyle(t, sel, editMedia, prop, val as string | undefined)
       : (t: Tab, prop: string, val: string | Record<string, unknown> | undefined) =>
           mutateUpdateStyle(t, sel, prop, val as string | undefined);
   }
   const commitStyle = (prop: string, val?: string | Record<string, unknown> | undefined) =>
     transactDoc(activeTab.value, (t) => commitMutate(t, prop, val));
 
-  // ── Compute inherited style from higher breakpoints ──────────────────────
-  const inheritedStyle: Record<string, string | number> = computeInheritedStyle(
-    style,
-    mediaNames,
-    mediaTab,
-    activeSelector,
-  );
+  // ── Compute inherited style ────────────────────────────────────────────────
+  // Scheme layer: the base styles show through as inherited (placeholders); breakpoint tabs
+  // Inherit from higher breakpoints as before.
+  const inheritedStyle: Record<string, string | number> = schemeLayer
+    ? (Object.fromEntries(
+        Object.entries(
+          activeSelector ? (getNestedStyle(style, activeSelector) ?? {}) : style,
+        ).filter(([, v]) => typeof v !== "object"),
+      ) as Record<string, string | number>)
+    : computeInheritedStyle(style, mediaNames, mediaTab, activeSelector);
 
   // Auto-open sections that have properties
   const newSections = autoOpenSections({ style: activeStyle }, tab.session.ui.styleSections);
@@ -683,7 +713,7 @@ function styleSidebarTemplate(
                 sec.$layout === "grid",
                 inheritedStyle[prop] as string | undefined,
                 templateSignals,
-                `style|${sel.join("/")}|${mediaTab ?? ""}|${activeSelector ?? ""}|${prop}`,
+                `style|${sel.join("/")}|${editMedia ?? ""}|${activeSelector ?? ""}|${prop}`,
               ),
             );
           }

package/src/panels/tab-bar.ts

@@ -15,6 +15,7 @@ import { effect, effectScope } from "../reactivity";
 import { activeTab } from "../workspace/workspace";
 import { applyTransform, fitToScreen, resetZoom, setEditZoom } from "../canvas/canvas-utils";
 import { getEffectiveLayoutPath, getEffectiveMedia } from "../site-context";
+import { isSchemeQuery } from "../utils/canvas-media";
 import { dynamicRouteParams, loadParamValues, pagePathsDef } from "../page-params";
 import { componentPropEntries, isComponentDoc } from "../component-props";
 import { mediaDisplayName } from "./shared";
@@ -75,6 +76,7 @@ export function mount(host: HTMLElement, ctx: TabBarCtx) {
         void tab.session.ui.editingFunction;
         void tab.session.ui.featureToggles;
         void tab.session.ui.preview;
+        void tab.session.ui.previewColorScheme;
         void tab.session.ui.previewParams;
         void tab.session.ui.previewProps;
         void tab.session.ui.showLayout;
@@ -308,13 +310,46 @@ function tabBarTemplate(ctx: TabBarCtx): TemplateResult | typeof nothing {
     }
   }
 
-  // ── Right region: media feature toggles ──
+  // ── Right region: color-scheme preview (projects that declare a scheme query, spec §9.5) ──
+  // One switch per tab: drives the canvas data-color-scheme attribute and (in the style
+  // Sidebar) which scheme layer edits target. Ungated — works in every canvas mode.
   const { featureQueries } = ctx.parseMediaEntries(getEffectiveMedia(S.document?.$media));
+  const schemeQueries = featureQueries.filter(({ query }) => isSchemeQuery(query));
+  const plainQueries = featureQueries.filter(({ query }) => !isSchemeQuery(query));
+  const scheme = S.ui.previewColorScheme ?? "auto";
+  const schemeTpl =
+    schemeQueries.length > 0
+      ? html`
+          <sp-action-group compact size="s" class="tb-scheme">
+            ${(
+              [
+                ["auto", "Auto", "Follow the OS color scheme"],
+                ["light", "Light", "Force the light scheme"],
+                ["dark", "Dark", "Force the dark scheme"],
+              ] as const
+            ).map(
+              ([value, label, title]) => html`
+                <sp-action-button
+                  toggles
+                  size="s"
+                  title=${title}
+                  ?selected=${scheme === value}
+                  @click=${() => updateUi("previewColorScheme", value)}
+                >
+                  ${label}
+                </sp-action-button>
+              `,
+            )}
+          </sp-action-group>
+        `
+      : nothing;
+
+  // ── Right region: media feature toggles (non-scheme queries) ──
   const togglesTpl =
-    featureQueries.length > 0
+    plainQueries.length > 0
       ? html`
           <sp-action-group compact size="s">
-            ${featureQueries.map(
+            ${plainQueries.map(
               ({ name, query }: { name: string; query: string }) => html`
                 <sp-action-button
                   toggles
@@ -352,7 +387,7 @@ function tabBarTemplate(ctx: TabBarCtx): TemplateResult | typeof nothing {
     <div class="tab-bar">
       ${navTpl} ${zoomTpl}
       <div class="tb-spacer"></div>
-      ${settingsTpl} ${togglesTpl} ${exportTpl}
+      ${settingsTpl} ${schemeTpl} ${togglesTpl} ${exportTpl}
     </div>
   `;
 }