@ammduncan/easel 0.6.1 → 0.7.0

package/dist/client/viewer.js

@@ -47,65 +47,6 @@
   const PRESETS = ["paper", "aurora", "slate"];
   const DENSITIES = ["carded", "flat"];
 
-  /* The token block injected into every iframe wrapper — six combos so
-     pushed HTML themes correctly regardless of host preset/mode. */
-  const PRESET_TOKENS_CSS = `
-:root[data-preset="paper"][data-theme="light"] {
-  --ds-bg:#f4efe2;--ds-bg-elev:#f8f3e6;--ds-surface:#faf6ee;--ds-surface-soft:#f0ead9;
-  --ds-ink:#2a261e;--ds-ink-soft:#524b3c;--ds-muted:#756c57;
-  --ds-line:#d5cdb6;--ds-line-soft:#e3dcc6;
-  --ds-accent:#c97a1c;--ds-accent-soft:#f7e8c0;--ds-accent-ink:#fff;
-  --ds-code-bg:#2a261e;--ds-code-ink:#eae5d5;
-  --ds-shadow-md:0 1px 2px rgba(70,50,10,.06),0 18px 36px rgba(70,50,10,.1);
-  color-scheme:light;
-}
-:root[data-preset="paper"][data-theme="dark"] {
-  --ds-bg:#1c1b18;--ds-bg-elev:#25241f;--ds-surface:#25241f;--ds-surface-soft:#20201c;
-  --ds-ink:#ede9e0;--ds-ink-soft:#bbb5a8;--ds-muted:#888273;
-  --ds-line:#423f37;--ds-line-soft:#312f29;
-  --ds-accent:#f4bf5e;--ds-accent-soft:#3d3322;--ds-accent-ink:#1f1d18;
-  --ds-code-bg:#161514;--ds-code-ink:#eae5d5;
-  --ds-shadow-md:inset 0 1px 0 rgba(255,255,255,.045),0 1px 2px rgba(0,0,0,.55),0 18px 38px rgba(0,0,0,.45);
-  color-scheme:dark;
-}
-:root[data-preset="aurora"][data-theme="light"] {
-  --ds-bg:#f5f3fa;--ds-bg-elev:#fafaff;--ds-surface:#fff;--ds-surface-soft:#f0eef7;
-  --ds-ink:#1c1d24;--ds-ink-soft:#4a4d5a;--ds-muted:#7a7d8c;
-  --ds-line:#e1dff0;--ds-line-soft:#ebe9f5;
-  --ds-accent:#6d4eff;--ds-accent-soft:#ebe7ff;--ds-accent-ink:#fff;
-  --ds-code-bg:#1c1d24;--ds-code-ink:#ebe7ff;
-  --ds-shadow-md:0 1px 2px rgba(60,50,120,.05),0 18px 36px rgba(60,50,120,.08);
-  color-scheme:light;
-}
-:root[data-preset="aurora"][data-theme="dark"] {
-  --ds-bg:#0d0f14;--ds-bg-elev:#14171f;--ds-surface:#161a23;--ds-surface-soft:#11141a;
-  --ds-ink:#e7e9ee;--ds-ink-soft:#b9bdc6;--ds-muted:#8b909a;
-  --ds-line:rgba(143,160,200,.14);--ds-line-soft:rgba(143,160,200,.08);
-  --ds-accent:#b8c8ff;--ds-accent-soft:rgba(140,170,255,.12);--ds-accent-ink:#0d0f14;
-  --ds-code-bg:#07080a;--ds-code-ink:#e7e9ee;
-  --ds-shadow-md:inset 0 1px 0 rgba(255,255,255,.045),0 0 0 1px rgba(123,97,255,.06),0 24px 60px rgba(0,0,0,.55),0 0 80px -20px rgba(123,97,255,.25);
-  color-scheme:dark;
-}
-:root[data-preset="slate"][data-theme="light"] {
-  --ds-bg:#ecebe5;--ds-bg-elev:#f6f4ee;--ds-surface:#f6f4ee;--ds-surface-soft:#ecebe3;
-  --ds-ink:#1a1916;--ds-ink-soft:#34322d;--ds-muted:#76746c;
-  --ds-line:#d8d5cb;--ds-line-soft:#e1ddd2;
-  --ds-accent:#2f5fd1;--ds-accent-soft:#e4ebfb;--ds-accent-ink:#fff;
-  --ds-code-bg:#1c1b18;--ds-code-ink:#f1ede1;
-  --ds-shadow-md:0 1px 2px rgba(40,30,10,.05),0 16px 32px rgba(40,30,10,.08);
-  color-scheme:light;
-}
-:root[data-preset="slate"][data-theme="dark"] {
-  --ds-bg:#0c0d10;--ds-bg-elev:#15171c;--ds-surface:#15171c;--ds-surface-soft:#1c1f25;
-  --ds-ink:#f5f5f5;--ds-ink-soft:#d4d4d8;--ds-muted:#9ca3af;
-  --ds-line:#23262d;--ds-line-soft:#1c1f25;
-  --ds-accent:#7dd3fc;--ds-accent-soft:rgba(125,211,252,.16);--ds-accent-ink:#07242e;
-  --ds-code-bg:#07080a;--ds-code-ink:#f5f5f5;
-  --ds-shadow-md:0 1px 2px rgba(0,0,0,.4),0 12px 28px rgba(0,0,0,.45);
-  color-scheme:dark;
-}
-`;
-
   /* Semantic chips — universal across presets. Authors use:
        <span class="chip bug">BUG</span> / .ux / .polish / .ok / .info
      to get accessible, glow-haloed badges that work in both modes. */
@@ -142,12 +83,11 @@
      block, so stripping these in fidelity mode left the skill's own guidance
      ("wrap a mockup in .window") producing unstyled output. */
   const STRUCTURAL_PRIMITIVES_CSS = `
-/* Bind the CSS color-scheme to the host theme so any author CSS that uses
-   light-dark() (text ink, surfaces, borders) tracks the easel light/dark
-   TOGGLE rather than the OS preference. The default wrapper already gets this
-   via PRESET_TOKENS_CSS, but app-fidelity (kind:"mockup") pushes omit the
-   preset tokens — without this rule their light-dark() ink follows the OS
-   scheme and washes out whenever the OS disagrees with the easel toggle. */
+/* Bind the CSS color-scheme to the card's sealed theme so any author CSS that
+   uses light-dark() (text ink, surfaces, borders) — including the kit's token
+   fallbacks — resolves against the frozen mode rather than the OS preference.
+   Injected in every wrapper (default + app-fidelity), the only place the canvas
+   mode is now declared since the preset token block was removed. */
 :root[data-theme="light"] { color-scheme: light; }
 :root[data-theme="dark"]  { color-scheme: dark; }
 
@@ -167,18 +107,19 @@
    canvas with pinned dark ink and color:inherit re-scoped to every child so the
    host's light-dark() ink can never leak in. Add the dark class
    (class="window dark") for a genuinely dark-UI mockup. */
-.window {
+.window, .easel-window, [data-easel="window"] {
   position: relative;
   padding-top: 40px;
   border-radius: 12px;
   border: 1px solid #e2e2e2;
   box-shadow: 0 14px 48px rgba(0, 0, 0, 0.16);
   overflow: hidden;
-  background: #ffffff;
-  color: #1a1a1a;
+  /* Locked surface + ink, !important so .wrap * { color: inherit } can't flip it. */
+  background: #ffffff !important;
+  color: #1a1a1a !important;
 }
-.window * { color: inherit; }
-.window::before {
+.window *, .easel-window *, [data-easel="window"] * { color: inherit; }
+.window::before, .easel-window::before, [data-easel="window"]::before {
   content: "";
   position: absolute;
   top: 0;
@@ -193,7 +134,7 @@
     radial-gradient(circle at 59px 20px, #28c840 6px, transparent 6.5px);
   background-repeat: no-repeat;
 }
-.window::after {
+.window::after, .easel-window::after, [data-easel="window"]::after {
   content: attr(data-title);
   position: absolute;
   top: 0;
@@ -208,18 +149,18 @@
   color: #6b6b6b;
   pointer-events: none;
 }
-.window.dark {
+.window.dark, .easel-window.dark, [data-easel="window"].dark {
   border-color: #2a2a2a;
-  background: #161616;
-  color: #e6edf3;
+  background: #161616 !important;
+  color: #e6edf3 !important;
   box-shadow: 0 14px 48px rgba(0, 0, 0, 0.4);
 }
-.window.dark::before {
+.window.dark::before, .easel-window.dark::before, [data-easel="window"].dark::before {
   background-color: #1f1f1f;
   border-bottom-color: #2a2a2a;
 }
-.window.dark::after { color: #9b9b9b; }
-.window.desktop {
+.window.dark::after, .easel-window.dark::after, [data-easel="window"].dark::after { color: #9b9b9b; }
+.window.desktop, .easel-window.desktop, [data-easel="window"].desktop {
   min-height: 900px;
 }
 /* Locked-dark code / terminal primitive. Reach for this instead of hand-rolling
@@ -231,9 +172,18 @@
    palette so syntax highlighting reads against #0f172a without per-token tuning.
    Usage: <div class="code"><span class="kw">gcloud</span> services enable …</div>
    .terminal is an alias; add .terminal for a prompt feel (same colors). */
-.code, .terminal {
-  background: #0f172a;
-  color: #e6edf3;
+.code, .terminal, .easel-code, .easel-terminal,
+[data-easel="code"], [data-easel="terminal"] {
+  /* Locked dark surface + ink. Committed with !important so the documented
+     .wrap * { color: inherit } can't flip the ink onto this fixed background —
+     that tie (both (0,1,0); author rule later in source) is the recurring
+     invisible dark-on-dark bug. !important is on the CONTAINER only, not on the
+     descendant rules below, so syntax tokens still win by specificity.
+     Generic names collide with author markup like <td class="code"> — prefer the
+     namespaced .easel-code / [data-easel="code"]; bare code/terminal are kept as
+     deprecated aliases. */
+  background: #0f172a !important;
+  color: #e6edf3 !important;
   border-radius: 12px;
   padding: 18px 22px;
   font-family: ui-monospace, "SF Mono", Menlo, monospace;
@@ -242,25 +192,26 @@
   overflow: auto;
   margin: 16px 0 24px;
 }
-.code *, .terminal * { color: inherit; }
-.code .kw,      .terminal .kw      { color: #ff7b72; }  /* keywords, control flow */
-.code .string,  .terminal .string  { color: #a5d6ff; }  /* strings, attr values */
-.code .fn,      .terminal .fn      { color: #d2a8ff; }  /* function names */
-.code .prop,    .terminal .prop    { color: #79c0ff; }  /* identifiers, properties */
-.code .num,     .terminal .num     { color: #ffa657; }  /* numbers, constants */
-.code .comment, .terminal .comment { color: #8b949e; }  /* comments */
-.code .muted,   .terminal .muted   { color: #94a3b8; }  /* dim / secondary */
-.code .accent,  .terminal .accent  { color: #6ee7b7; }  /* highlight / success */
+:is(.code, .terminal, .easel-code, .easel-terminal, [data-easel="code"], [data-easel="terminal"]) * { color: inherit; }
+:is(.code, .terminal, .easel-code, .easel-terminal) .kw      { color: #ff7b72; }  /* keywords, control flow */
+:is(.code, .terminal, .easel-code, .easel-terminal) .string  { color: #a5d6ff; }  /* strings, attr values */
+:is(.code, .terminal, .easel-code, .easel-terminal) .fn      { color: #d2a8ff; }  /* function names */
+:is(.code, .terminal, .easel-code, .easel-terminal) .prop    { color: #79c0ff; }  /* identifiers, properties */
+:is(.code, .terminal, .easel-code, .easel-terminal) .num     { color: #ffa657; }  /* numbers, constants */
+:is(.code, .terminal, .easel-code, .easel-terminal) .comment { color: #8b949e; }  /* comments */
+:is(.code, .terminal, .easel-code, .easel-terminal) .muted   { color: #94a3b8; }  /* dim / secondary */
+:is(.code, .terminal, .easel-code, .easel-terminal) .accent  { color: #6ee7b7; }  /* highlight / success */
 @media print {
   /* Force the locked-dark primitives light for print — browsers drop background
      colours by default, which would otherwise strand their light ink on white
      paper. Applies in both normal and app-fidelity mode. The !important here
      also (intentionally) overrides the normal branch's non-print-gated pre/code
      theming, so code reads as dark-on-light on paper regardless of host theme. */
-  pre, code, .code, .terminal { background: #f4f3ed !important; color: #111 !important; border: 1px solid #ddd; }
-  .code *, .terminal * { color: #111 !important; }
-  .window.dark { background: #ffffff !important; color: #111 !important; }
-  .window.dark * { color: #111 !important; }
+  pre, code, .code, .terminal, .easel-code, .easel-terminal,
+  [data-easel="code"], [data-easel="terminal"] { background: #f4f3ed !important; color: #111 !important; border: 1px solid #ddd; }
+  :is(.code, .terminal, .easel-code, .easel-terminal, [data-easel="code"], [data-easel="terminal"]) * { color: #111 !important; }
+  .window.dark, .easel-window.dark, [data-easel="window"].dark { background: #ffffff !important; color: #111 !important; }
+  :is(.window, .easel-window, [data-easel="window"]).dark * { color: #111 !important; }
 }
 `;
 
@@ -514,7 +465,11 @@
         /* ignore */
       }
     }
-    broadcastConfigToIframes({ preset, theme, density });
+    // NOTE: we deliberately do NOT push theme/preset/density into rendered
+    // iframes. A pushed card is an immutable snapshot — its canvas is sealed at
+    // render time. applyConfig only restyles Easel's own chrome (host <html>
+    // tokens) and the default for FUTURE pushes; it never reaches back into
+    // existing cards.
     if (!opts || !opts.skipServer) {
       pushConfigToServer({ preset, theme, density });
     }
@@ -531,20 +486,6 @@
     });
   }
 
-  function broadcastConfigToIframes(cfg) {
-    iframes.forEach((iframe) => {
-      try {
-        iframe.contentWindow &&
-          iframe.contentWindow.postMessage(
-            { type: "easel:config", ...cfg },
-            "*",
-          );
-      } catch (e) {
-        /* ignore */
-      }
-    });
-  }
-
   async function pushConfigToServer(cfg) {
     try {
       await fetch("/api/config", {
@@ -831,7 +772,12 @@
     iframe.setAttribute("scrolling", "no");
     iframe.setAttribute("title", push.title || "push " + push.index);
     iframe.dataset.pushId = push.id;
-    iframe.srcdoc = wrapPushedHtml(push.html, currentTheme(), push.id, push.kind);
+    // Explicit push.theme wins; absent → snapshot the global at render. Either
+    // way it's frozen — the card never flips on a later global toggle.
+    const sealedTheme = push.theme === "light" || push.theme === "dark"
+      ? push.theme
+      : currentTheme();
+    iframe.srcdoc = wrapPushedHtml(push.html, sealedTheme, push.id, push.kind);
     iframe.addEventListener("load", () => {
       iframes.add(iframe);
       // Primary path: the iframe self-measures and posts back size via
@@ -1051,8 +997,13 @@ window.htmlToImage.toSvg(de,{width:w,height:h,cacheBust:true})
       "function hasDirectText(el){for(var i=0;i<el.childNodes.length;i++){var n=el.childNodes[i];if(n.nodeType===3&&n.nodeValue.trim().length>0)return true}return false}" +
       "function fmt(c){return'rgb('+Math.round(c.r)+','+Math.round(c.g)+','+Math.round(c.b)+')'}" +
       "function scan(){if(!document.body)return;var offenders=[];var seen=0;var all=document.body.querySelectorAll('*');for(var i=0;i<all.length&&seen<2000;i++){var el=all[i];if(!hasDirectText(el))continue;seen++;var cs=getComputedStyle(el);if(cs.visibility==='hidden'||cs.display==='none')continue;var fg=parseColor(cs.color);if(!fg||fg.a<0.05)continue;var bg=effBg(el);var ratio=contrast(fg,bg);if(ratio<3){offenders.push({tag:el.tagName.toLowerCase(),cls:(el.className&&el.className.toString?el.className.toString():'').slice(0,80),text:(el.textContent||'').trim().slice(0,60),ratio:Math.round(ratio*100)/100,fg:fmt(fg),bg:fmt(bg)})}}" +
-      "if(offenders.length){console.warn('[easel] low-contrast text detected ('+offenders.length+' element(s), threshold 3:1). The #1 cause is a hand-rolled dark code container — use <div class=\"code\"> or <div class=\"terminal\"> instead; they lock background AND ink and re-scope color:inherit to children. Offenders:',offenders.slice(0,10));try{parent.postMessage({type:'easel:contrast-warn',pushId:ID,count:offenders.length,samples:offenders.slice(0,5)},'*')}catch(e){}}}" +
-      "function run(){setTimeout(scan,400)}" +
+      "if(offenders.length){console.warn('[easel] low-contrast text detected ('+offenders.length+' element(s), threshold 3:1). Common causes: (1) a reserved primitive class (code/terminal/window) on your own element inheriting its locked dark fill — see the reserved-class warning below; (2) a hand-rolled dark container — use <div class=\"easel-code\"> instead (locks bg AND ink). Offenders:',offenders.slice(0,10));try{parent.postMessage({type:'easel:contrast-warn',pushId:ID,count:offenders.length,samples:offenders.slice(0,5)},'*')}catch(e){}}}" +
+      // Reserved-class collision guard: the primitive names code/terminal/window paint a
+      // locked dark background, so finding one on an inline/table element (span/td/…) is a
+      // strong signal the author reused a generic name and got an unintended dark block.
+      "function scanReserved(){if(!document.body)return;var R={code:1,terminal:1,window:1};var inl={SPAN:1,TD:1,TH:1,A:1,LI:1,LABEL:1,B:1,I:1,EM:1,STRONG:1,SMALL:1};var bad=[];var all=document.body.querySelectorAll('*');for(var i=0;i<all.length;i++){var el=all[i];if(!inl[el.tagName])continue;var cl=(el.className&&el.className.toString?el.className.toString():'').split(/\\s+/);for(var j=0;j<cl.length;j++){if(R[cl[j]]){bad.push({tag:el.tagName.toLowerCase(),cls:cl[j],text:(el.textContent||'').trim().slice(0,40)});break}}}" +
+      "if(bad.length){console.warn('[easel] reserved primitive class on '+bad.length+' inline/table element(s). code/terminal/window are RESERVED easel primitives that paint a locked dark background — on a <span>/<td>/etc. that yields an unintended dark block. Rename your class (e.g. mono, codecell), or use the namespaced .easel-code/.easel-terminal/.easel-window form if you DO want the primitive. Offenders:',bad.slice(0,10))}}" +
+      "function run(){setTimeout(function(){scan();scanReserved()},400)}" +
       "if(document.fonts&&document.fonts.ready){document.fonts.ready.then(run).catch(run)}else{run()}" +
       "})();"
     );
@@ -1092,23 +1043,30 @@ ${body}
 <head>
 <meta charset="utf-8" />
 <base target="_blank" />
-<link rel="preconnect" href="https://rsms.me/" />
-<link rel="stylesheet" href="https://rsms.me/inter/inter.css" />
 <script src="https://cdn.jsdelivr.net/npm/html-to-image@1.11.13/dist/html-to-image.js"></script>
 <style>
 *, *::before, *::after { box-sizing: border-box; }
-${PRESET_TOKENS_CSS}
 ${SEMANTIC_CHIPS_CSS}
 ${STRUCTURAL_PRIMITIVES_CSS}
+/* MINIMAL FLOOR (layer 3 removed): no --ds token block, no Inter webfont, no
+   presentation type scale. The wrapper only commits a base surface + ink for
+   the frozen mode and a system-sans default — the agent owns everything else
+   (or inlines the kit for the presentation scaffold). Primitives + chips +
+   prose-width cap are retained. */
 html, body {
   margin: 0;
-  background: var(--ds-bg-elev);
-  color: var(--ds-ink);
-  font-family: "Inter", -apple-system, "SF Pro Text", system-ui, sans-serif;
-  font-feature-settings: "cv11", "ss01";
+  background: ${theme === "dark" ? "#0e1116" : "#faf7f0"};
+  color: ${theme === "dark" ? "#e8e8e8" : "#1a1a1a"};
+  font-family: -apple-system, "SF Pro Text", system-ui, "Segoe UI", sans-serif;
   line-height: 1.55;
   -webkit-font-smoothing: antialiased;
-  transition: background 200ms ease, color 200ms ease;
+}
+:where(body) :where(*) { color: inherit; }
+/* keep the accent chip working without the dropped --ds-accent token */
+.chip.accent {
+  background: ${theme === "dark" ? "#10241c" : "#eafaf0"};
+  color: ${theme === "dark" ? "#6ee7a8" : "#15803d"};
+  border-color: transparent;
 }
 body {
   padding: 40px clamp(28px, 4vw, 64px) 48px;
@@ -1152,104 +1110,7 @@ body > *:last-child { margin-bottom: 0 !important; }
   margin: 32px 0;
 }
 .wrap { display: block; }
-.kicker {
-  display: block;
-  font-size: 13px;
-  letter-spacing: 0.14em;
-  text-transform: uppercase;
-  color: var(--ds-muted);
-  font-weight: 500;
-  margin-bottom: 14px;
-}
-h1 {
-  font-size: 40px;
-  font-weight: 500;
-  letter-spacing: -0.025em;
-  line-height: 1.08;
-  margin: 0 0 18px;
-}
-.deck, .lede {
-  font-size: 19px;
-  line-height: 1.55;
-  color: var(--ds-ink-soft);
-  margin: 0 0 28px;
-  max-width: 720px;
-}
-h2 {
-  font-size: 26px;
-  font-weight: 500;
-  letter-spacing: -0.02em;
-  margin: 36px 0 12px;
-}
-h3 {
-  font-size: 19px;
-  font-weight: 600;
-  letter-spacing: -0.005em;
-  margin: 24px 0 8px;
-}
-h4 { font-size: 15px; font-weight: 600; margin: 20px 0 6px; }
-p {
-  font-size: 18px;
-  margin: 0 0 14px;
-  color: var(--ds-ink-soft);
-}
-a { color: var(--ds-accent); text-decoration: none; border-bottom: 1px solid color-mix(in srgb, var(--ds-accent) 40%, transparent); }
-a:hover { border-bottom-color: var(--ds-accent); }
-ul, ol { padding-left: 22px; margin: 0 0 18px; }
-li { font-size: 18px; margin-bottom: 6px; color: var(--ds-ink-soft); }
-code {
-  font-family: ui-monospace, "SF Mono", Menlo, monospace;
-  font-size: 0.92em;
-  background: var(--ds-surface-soft);
-  color: var(--ds-ink);
-  padding: 2px 6px;
-  border-radius: 5px;
-}
-pre {
-  background: var(--ds-code-bg);
-  color: var(--ds-code-ink);
-  padding: 18px 22px;
-  border-radius: 12px;
-  overflow: auto;
-  font-family: ui-monospace, "SF Mono", Menlo, monospace;
-  font-size: 13.5px;
-  line-height: 1.7;
-  margin: 16px 0 24px;
-}
-pre code { background: transparent; padding: 0; color: inherit; font-size: inherit; }
-blockquote {
-  border-left: 3px solid var(--ds-accent);
-  margin: 18px 0;
-  padding: 4px 0 4px 20px;
-  color: var(--ds-ink-soft);
-  font-size: 18px;
-}
-.card, .panel {
-  background: var(--ds-surface);
-  border: 1px solid var(--ds-line);
-  border-radius: 14px;
-  padding: 24px 28px;
-  margin: 0 0 20px;
-  box-shadow: 0 1px 2px rgba(0,0,0,0.04), 0 8px 24px rgba(0,0,0,0.04);
-}
-hr {
-  border: 0;
-  border-top: 1px solid var(--ds-line);
-  margin: 36px 0;
-}
-table {
-  width: 100%;
-  border-collapse: collapse;
-  font-size: 15px;
-  margin: 18px 0 24px;
-}
-th, td {
-  text-align: left;
-  padding: 10px 12px;
-  border-bottom: 1px solid var(--ds-line);
-}
-th { color: var(--ds-muted); font-weight: 500; font-size: 13px; text-transform: uppercase; letter-spacing: 0.05em; }
-img { max-width: 100%; height: auto; border-radius: 10px; }
+img { max-width: 100%; height: auto; }
 :root[data-density="flat"] html,
 :root[data-density="flat"] body { background: transparent; }
 
@@ -1272,26 +1133,12 @@ img { max-width: 100%; height: auto; border-radius: 10px; }
 <body>
 ${body}
 <script>
+// Canvas is sealed at render (data-theme/preset/density are baked into <html>
+// above and never change). The only live message this card honours is print —
+// config/theme broadcasts are intentionally ignored so the snapshot is immutable.
 (function(){
-  function apply(cfg){
-    if (!cfg) return;
-    if (cfg.theme === "light" || cfg.theme === "dark") {
-      document.documentElement.setAttribute("data-theme", cfg.theme);
-      window.__claudeDisplayTheme = cfg.theme;
-    }
-    if (cfg.preset === "paper" || cfg.preset === "aurora" || cfg.preset === "slate") {
-      document.documentElement.setAttribute("data-preset", cfg.preset);
-      window.__claudeDisplayPreset = cfg.preset;
-    }
-    if (cfg.density === "carded" || cfg.density === "flat") {
-      document.documentElement.setAttribute("data-density", cfg.density);
-      window.__claudeDisplayDensity = cfg.density;
-    }
-  }
   window.addEventListener("message", function(e){
     if (!e || !e.data) return;
-    if (e.data.type === "easel:config") apply(e.data);
-    if (e.data.type === "easel:theme") apply({ theme: e.data.theme });
     if (e.data.type === "easel:print") {
       try { window.print(); } catch(_) {}
     }
@@ -1310,7 +1157,7 @@ ${body}
     const configScript =
       "<script src='https://cdn.jsdelivr.net/npm/html-to-image@1.11.13/dist/html-to-image.js'></script><script>(function(){function a(c){if(!c)return;if(c.theme==='light'||c.theme==='dark'){document.documentElement.setAttribute('data-theme',c.theme);window.__claudeDisplayTheme=c.theme}if(c.preset==='paper'||c.preset==='aurora'||c.preset==='slate'){document.documentElement.setAttribute('data-preset',c.preset);window.__claudeDisplayPreset=c.preset}if(c.density==='carded'||c.density==='flat'){document.documentElement.setAttribute('data-density',c.density);window.__claudeDisplayDensity=c.density}}a(" +
       JSON.stringify({ theme, preset, density }) +
-      ");window.addEventListener('message',function(e){if(!e||!e.data)return;if(e.data.type==='easel:config')a(e.data);if(e.data.type==='easel:theme')a({theme:e.data.theme});if(e.data.type==='easel:print'){try{window.print()}catch(_){}}})})();</script>";
+      ");window.addEventListener('message',function(e){if(!e||!e.data)return;if(e.data.type==='easel:print'){try{window.print()}catch(_){}}})})();</script>";
     const imageScript = "<script>" + imageExportScript() + "</script>";
     const guardScript = "<script>" + contrastGuardScript(pushId) + "</script>";
     const measureScript = "<script>" + selfMeasureScript(pushId) + "</script>";

package/dist/http-server.js

@@ -159,7 +159,7 @@ export function startHttpServer() {
         res.json({ ok });
     });
     app.post("/api/push", async (req, res) => {
-        const { sessionId, html, title, kind } = req.body ?? {};
+        const { sessionId, html, title, kind, theme } = req.body ?? {};
         if (typeof sessionId !== "string" || !sessionId.trim()) {
             res.status(400).json({ error: "sessionId required" });
             return;
@@ -185,7 +185,7 @@ export function startHttpServer() {
                 console.warn("[easel] image inlining failed; storing original html:", err);
             }
         }
-        const push = appendPush(sessionId, { html: storedHtml, title, kind });
+        const push = appendPush(sessionId, { html: storedHtml, title, kind, theme });
         touchSession(sessionId);
         broadcast(sessionId, "push", push);
         if (Math.random() < 0.05) {

package/dist/mcp.js

@@ -21,6 +21,14 @@ const TOOL_PUSH = "push";
 const TOOL_OPEN = "open";
 const TOOL_CONFIG = "config";
 const TOOL_LABEL = "label";
+// When EASEL_SUPPRESS_SESSION=1 (set by automated/headless consumers like the
+// ammiels-bot dispatcher tick), easel loads normally but registers NO switcher
+// session — every tool short-circuits to a no-op, so the MCP never contacts the
+// HTTP server and the session never appears in the switcher. This keeps churny
+// background sessions out of the switcher WITHOUT disabling the MCP or any OTHER
+// connector. (Contrast `claude --strict-mcp-config`, which also strips the
+// claude.ai account connectors — Slack etc. — and so can't be used for this.)
+const SUPPRESS_SESSION = process.env.EASEL_SUPPRESS_SESSION === "1";
 // One-shot guard: only auto-open once per MCP-child lifetime. If the user
 // closes the tab afterwards, subsequent pushes won't re-open it — the user
 // closing the tab is treated as an explicit dismissal we should respect.
@@ -74,6 +82,11 @@ const inputSchema = {
             type: "string",
             description: "Freeform tag: mockup, app, diff, explanation, comparison, diagram, status, progress, etc. SPECIAL: 'mockup' and 'app' switch the iframe into APP-FIDELITY mode — the wrapper skips its PRESENTATION defaults (preset design-token CSS, semantic chips, prose width constraints, body bg/color, the Inter webfont) so the host theme can't leak in and you control every pixel. It KEEPS the self-contained structural primitives (.window/.window.dark window chrome, .code/.terminal code blocks — all fixed-colour, theme-independent) and a neutral system-sans default font, so you can still reach for <div class=\"window\"> in a mockup and it renders. Set your own font-family/colours in the pushed HTML to override the sans default. Use this kind when the push is a recreation of real UI (app screen, component instance, embedded preview). For presentation content (explanations, comparisons, status reports), omit kind or use a non-fidelity value.",
         },
+        theme: {
+            type: "string",
+            enum: ["light", "dark"],
+            description: "Canvas mode for THIS push — light or dark. SEALED at push time and never flips with the global Easel toggle: a pushed card is an immutable snapshot, like a screenshot. You OWN this canvas — set your own background + text colours in the HTML for the mode you pick here; do NOT write light-dark() / prefers-color-scheme for the page surface (the card is frozen to one mode, so adaptive CSS is dead weight). Omit to snapshot whatever the global theme is at push time (also frozen). Pass 'light' or 'dark' explicitly when you've been told which mode to present in.",
+        },
     },
     required: ["html"],
     additionalProperties: false,
@@ -87,6 +100,7 @@ async function pushToServer(args) {
             html: args.html,
             title: args.title,
             kind: args.kind,
+            theme: args.theme,
         }),
     });
     if (!r.ok) {
@@ -101,7 +115,9 @@ export async function main() {
         tools: [
             {
                 name: TOOL_PUSH,
-                description: "Push an HTML card to this session's live browser tab. Renders in a sandboxed iframe over a host-controlled canvas that can be LIGHT or DARK depending on the user's OS theme. Treat each card as a presentation slide — generous whitespace, presentation-scale type, tangible visuals. Your HTML MUST adapt to both light and dark modes.\n\n" +
+                description: "Push an HTML card to this session's live browser tab. Renders in a sandboxed iframe. Treat each card as a presentation slide — generous whitespace, presentation-scale type, tangible visuals.\n\n" +
+                    "═══ YOU OWN THE CANVAS — COMMIT TO ONE MODE ═══\n" +
+                    "A pushed card is an IMMUTABLE SNAPSHOT, like a screenshot: it's sealed at push time and NEVER reflows when the user toggles Easel's global light/dark theme. So pick ONE mode for this push and own every colour in it — set your own `background` AND `color` on `.wrap`/`body`, and choose surfaces/borders/ink for that single mode. Do NOT write `light-dark()` or `prefers-color-scheme` for the page surface; the card won't flip, so adaptive CSS is dead weight that just risks the wrong branch winning. Use the `theme` param to declare the mode ('light'/'dark') when you've been told which to present in; omit it to snapshot the current global theme (also frozen). Still scope `color: inherit` to descendants so a stray default ink can't leak in, and the locked primitives (.code/.terminal/.window) work exactly as before — the whole surface now just behaves like they already do: one committed mode, fully self-contained.\n\n" +
                     "═══ FIDELITY BAR — SHIP HIGH-FIDELITY BY DEFAULT ═══\n" +
                     "Default to polished, production-grade output that looks like a real screenshot of shipped software or a finished design — NOT a rough sketch, wireframe, or grey-box placeholder. This is the default for EVERY push; you do not need to be asked for quality. Only drop to low-fidelity (wireframe, ASCII-ish boxes, lorem-ipsum, unstyled) when the user EXPLICITLY says rough/lo-fi/wireframe/sketch/quick-and-dirty is fine, or asks for a thumbnail/napkin idea. When in doubt, go high-fidelity.\n" +
                     "What high-fidelity means concretely:\n" +
@@ -111,18 +127,19 @@ export async function main() {
                     "• Visual craft: deliberate hierarchy, aligned grids, consistent spacing scale, real iconography (inline SVG, not emoji-as-icon), proper empty/hover/active states where they matter. Avoid the generic-AI look (one purple gradient, evenly-sized boxes, centered everything).\n" +
                     "• Tangible over abstract (see VISUALS): a mock should read as the actual thing, not labeled rectangles.\n" +
                     "If you genuinely can't reach the bar (missing real values, ambiguous source), say so in ONE line in chat and push your best honest attempt — don't pass a rough draft off as final, and don't silently ship a grey-box.\n\n" +
-                    "═══ ADAPTIVE COLOR (gets wrong most often) ═══\n" +
-                    "• Do NOT set `background` on `body` or your root wrapper. The host paints the canvas — setting bg fights it and creates a wrong-shade block in the opposite mode.\n" +
-                    "• Use `light-dark()` for ALL text colors, card backgrounds, borders, and decorative shades. Add `:root { color-scheme: light dark; }` so the function resolves. Hardcoded `color: #475569` goes invisible in dark mode; hardcoded `border: 1px solid #e5e5e5` becomes a hard white line.\n" +
-                    "• After setting `.wrap { color: light-dark(...); }`, re-scope `color: inherit` to every descendant so child elements don't fall back to the host's default.\n" +
-                    "• Inverse rule: if you DO paint a fixed background on a container (a code block locked to dark, a brand-color hero), you MUST also set its text color AND re-scope `color: inherit` to its children. Background and text are a pair.\n\n" +
-                    "═══ COPY-PASTE STARTER (adaptive) ═══\n" +
-                    "  :root { color-scheme: light dark; }\n" +
-                    "  .wrap { color: light-dark(#111, #e8e8e8); padding: 56px 48px; font-family: -apple-system, 'Inter', system-ui, sans-serif; max-width: 820px; }\n" +
+                    "═══ COMMITTED COLOR — PICK ONE MODE, PAINT IT FULLY ═══\n" +
+                    "The card is frozen to one mode (the `theme` param, or the global theme snapshotted at push time). So:\n" +
+                    "• DO set `background` AND `color` explicitly on your root wrapper. You own the canvas — paint it. (Old guidance said 'leave bg to the host'; that's gone — the host no longer reflows your card, so an unpainted surface just inherits chrome you don't control.)\n" +
+                    "• Pick concrete colours for the ONE mode you chose — `color: #111` for a light card, `color: #e8e8e8` for a dark one. Do NOT use `light-dark()` / `prefers-color-scheme` for the surface; the card won't flip, so the adaptive branch is dead weight and risks resolving to the wrong half.\n" +
+                    "• Still re-scope `color: inherit` to every descendant so a stray default ink can't leak in.\n" +
+                    "• Pairing rule (unchanged): any container with a fixed background (a dark code block, a brand-color hero, a white card) MUST set its own text color and re-scope `color: inherit` to its children. Background and ink are always a pair.\n\n" +
+                    "═══ COPY-PASTE STARTER (light card) ═══\n" +
+                    "  .wrap { background: #faf7f0; color: #1a1a1a; padding: 56px 48px; font-family: -apple-system, 'Inter', system-ui, sans-serif; max-width: 820px; }\n" +
                     "  .wrap *, .wrap h1, .wrap h2, .wrap h3, .wrap p, .wrap li, .wrap span { color: inherit; }\n" +
-                    "  .card { background: light-dark(#fff, #161616); border: 1px solid light-dark(#e0d9c3, #2a2a2a); border-radius: 12px; padding: 24px; }\n\n" +
+                    "  .card { background: #ffffff; border: 1px solid #e0d9c3; border-radius: 12px; padding: 24px; }\n" +
+                    "  (dark card: .wrap { background:#0e1116; color:#e8e8e8 }  .card { background:#161616; border-color:#2a2a2a })\n\n" +
                     "═══ CODE / TERMINAL BLOCKS — USE THE BUILT-IN PRIMITIVE, DON'T HAND-ROLL ═══\n" +
-                    "The #1 recurring bug is a hand-rolled dark code container: you set `background:#0f172a` on a custom div but leave base text inheriting `.wrap`'s `light-dark(#111,…)`, which resolves to near-black in light host mode and VANISHES against the dark panel (only the explicitly-coloured syntax spans survive). Don't hand-roll it. The wrapper ships a baked-in, always-safe primitive:\n" +
+                    "The #1 recurring bug is a hand-rolled dark code container: you set `background:#0f172a` on a custom div but leave base text inheriting `.wrap`'s ink, which on a light card is near-black and VANISHES against the dark panel (only the explicitly-coloured syntax spans survive). Don't hand-roll it. The wrapper ships a baked-in, always-safe primitive:\n" +
                     "  <div class=\"code\"> … </div>   (alias: class=\"terminal\")\n" +
                     "It locks BOTH background (#0f172a) and ink (#e6edf3), re-scopes `color:inherit` to every child, and provides verified github-dark syntax token classes you can drop onto spans — NO per-token tuning needed:\n" +
                     "  .kw (keywords #ff7b72) · .string (#a5d6ff) · .fn (function #d2a8ff) · .prop (identifiers #79c0ff) · .num (#ffa657) · .comment (#8b949e) · .muted (#94a3b8) · .accent (#6ee7b7)\n" +
@@ -130,10 +147,10 @@ export async function main() {
                     "Plain <pre>/<code> are also already safe (bg+ink token pair). Only reach for a fully custom container when .code/.terminal genuinely don't fit — and then obey the locked-mode rule below.\n" +
                     "SAFETY NET: every push self-checks for low-contrast text (WCAG <3:1) after render. If your push trips it, the card gets an amber `⚠ contrast` chip on the meta row with the offender list in the tooltip, and the iframe console.warns with sample rgb pairs. Treat the chip as a build-failure-equivalent — the fix is almost always swapping the hand-rolled container for `.code` / `.terminal` (or, for a non-code locked-bg container, applying the locked-mode rule below).\n\n" +
                     "═══ COPY-PASTE STARTER (any OTHER LOCKED-MODE container — brand hero, custom panel) ═══\n" +
-                    "If a container has a FIXED background (not `light-dark()`), you MUST set its own text color AND re-scope `color: inherit` to its children. Otherwise the children inherit `light-dark(...)` from `.wrap` and the text flips to the wrong shade in one mode (e.g. dark text on a locked-dark panel in light host mode → invisible).\n" +
+                    "If a container has a background that differs from the card surface, you MUST set its own text color AND re-scope `color: inherit` to its children. Otherwise the children inherit `.wrap`'s committed ink, which may not suit the container's bg (e.g. dark text on a dark hero on a light card → invisible).\n" +
                     "  .hero { background: #0f172a; color: #e6edf3; border-radius: 12px; padding: 20px 24px; }\n" +
                     "  .hero * { color: inherit; }\n" +
-                    "• Same pairing applies in the OPPOSITE direction — locked-LIGHT containers (e.g. a white card on the host canvas). A `.card { background: #fff }` with no `color:` inherits `.wrap`'s light-dark() text, which in dark host mode resolves to a light cream/gray → invisible titles on a white card. Commit text too AND re-scope inherit on children. This bites just as often as the dark case.\n" +
+                    "• Same pairing applies in the OPPOSITE direction — a light panel sitting on a DARK card. A `.card { background: #fff }` with no `color:` inherits `.wrap`'s dark-card ink (a light cream/gray) → invisible titles on white. Commit text too AND re-scope inherit on children. This bites just as often as the dark case.\n" +
                     "  .card { background: #ffffff; color: #111111; border: 1px solid #e5e5e5; border-radius: 12px; padding: 24px 32px; }\n" +
                     "  .card * { color: inherit; }\n" +
                     "• Syntax-highlighted code in a locked-bg block: EVERY token color must be verified readable against the bg, not just the body color. Recurring bug: locking to #0f172a then giving 'property' / 'punctuation' / 'comment' tokens something like #2c2c40 because it 'looked subtle' — against #0f172a it's nearly invisible and identifiers disappear. Either use a tested theme designed for your bg (Shiki github-dark / vitesse-dark / one-dark-pro for #0f172a-ish, github-light / vitesse-light for #f5f7fa-ish), or pick from this verified palette for #0f172a: keyword #ff7b72, string #a5d6ff, function #d2a8ff, property #79c0ff, number #ffa657, comment #8b949e, default text #e6edf3. If you can't articulate why each token reads against the bg, drop highlighting and use single-color monospace — that always works.\n\n" +
@@ -232,6 +249,16 @@ export async function main() {
         ],
     }));
     server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        if (SUPPRESS_SESSION) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "easel: session suppressed (EASEL_SUPPRESS_SESSION=1) — no switcher entry created; easel tools are no-ops in this session.",
+                    },
+                ],
+            };
+        }
         const sessionId = resolveClaudeSessionId();
         const { port } = await ensureHttpServer();
         if (req.params.name === TOOL_OPEN) {
@@ -304,6 +331,7 @@ export async function main() {
             html: args.html,
             title: args.title,
             kind: args.kind,
+            theme: args.theme,
             port,
         });
         const url = `http://localhost:${port}/s/${sessionId}`;

package/dist/session-store.js

@@ -63,11 +63,13 @@ export function getSessionView(id) {
 }
 export function appendPush(sessionId, input) {
     const meta = ensureSession(sessionId);
+    const theme = input.theme === "light" || input.theme === "dark" ? input.theme : null;
     const push = {
         id: randomUUID(),
         index: meta.nextIndex,
         title: input.title?.trim() || null,
         kind: input.kind?.trim() || null,
+        theme,
         html: input.html,
         createdAt: Date.now(),
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ammduncan/easel",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "A live browser tab for every Claude Code (and MCP) session. The push MCP tool appends HTML cards to a scrolling feed you keep open in split-screen.",
   "type": "module",
   "license": "MIT",

package/scripts/easel-session-id.mjs

@@ -58,6 +58,14 @@ if (sessionId) {
   writeFileSync(join(hookDir, `cc-session-${process.ppid}.txt`), `${sessionId}\n`);
 }
 
+// Suppressed sessions (e.g. the ammiels-bot dispatcher tick set
+// EASEL_SUPPRESS_SESSION=1) get NO convention reminder: the MCP no-ops every
+// tool, so nagging the agent to label/push would only waste a tool call. Exit
+// before emitting additionalContext.
+if (process.env.EASEL_SUPPRESS_SESSION === "1") {
+  process.exit(0);
+}
+
 // --- staleness check (cached, every 24h) ------------------------------------
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const INSTALL_DIR = resolve(__dirname, "..");