@ammduncan/easel 0.2.29 → 0.3.1

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to easel. This project adheres to [Semantic Versioning](https://semver.org/).
 
+## 0.3.1 — 2026-05-26
+
+### Fixed
+- **Prose measure tightened from ~90 to ~66 characters per line.** The reading-column cap was `max-width: 880px`, which at the 18px body font produces ~90-character lines — past WCAG 1.4.8's 80-char ceiling and well past Bringhurst's 45–75 comfortable range. Changed to `max-width: 56ch`. The `ch` unit is the width of the "0" glyph and proportional Inter averages narrower, so 56ch renders ~66 actual characters — the reading-measure sweet spot. (`ch` scales with font-size, so headings stay proportional; short headings never hit the cap, so it's load-bearing only on body paragraphs, which is correct.)
+- **`.full-bleed` now has vertical breathing room.** It only set horizontal margins, so a paragraph after an embedded mockup hugged the frame with no gap. Added `margin: 32px 0`; it collapses correctly against adjacent prose margins (32px, not 64) and the existing first/last-child margin resets still zero it at the card's top/bottom edge.
+
+## 0.3.0 — 2026-05-26
+
+### Fixed
+- **App-fidelity mode (`kind:"mockup"`/`"app"`) no longer strips the structural primitives — `.window`/`.code`/`.terminal` now render in mockups.** The wrapper has two branches: a normal presentation branch and an app-fidelity branch for UI recreations (which skips presets/tokens/chips/prose-caps/body-bg so the agent controls every pixel). But app-fidelity skipped the *entire* built-in stylesheet — including the self-contained `.window` window chrome and `.code`/`.terminal` code blocks — while the skill and the `push` tool description told agents to use `.window` *for mockups*. So a `kind:"mockup"` push with `<div class="window">` rendered as unstyled serif text with no chrome (the same "I shipped a fix but it doesn't apply here" surprise as the 0.2.29 `.window` washout). Extracted the primitives — which use fixed, theme-independent colours and can't leak the host theme — into a shared `STRUCTURAL_PRIMITIVES_CSS` constant injected into BOTH wrapper branches (single source, no duplication; the normal branch's inline copies and their `@media print` overrides were removed). A mockup can now reach for `.window`/`.code`/`.terminal` and they render, in either kind.
+- **App-fidelity mode now sets a system-sans default font instead of falling back to serif.** It deliberately omits the Inter webfont (so the agent controls typography with no CDN dependency), but it also left no `font-family` at all, so any mockup that didn't set its own font rendered in Times serif. Added a `system-ui, -apple-system, "Segoe UI", sans-serif` floor; the pushed HTML's own `font-family` still wins the cascade.
+
+### Added
+- **Visual-regression test suite (`tests/visual/`).** A fixture battery covering every built-in primitive plus realistic composites, each carrying an injected contrast-audit that walks text nodes, composites translucent backgrounds over the host backdrop, computes WCAG contrast, and reports washout failures. A driver pushes them to a running server; the suite is rendered across the full preset × theme × density matrix (+ print) to catch surface-vs-ink regressions. The two fixes above were both found by this suite. See `tests/visual/README.md`.
+
+### Docs
+- **`push` tool `kind` description and the using-easel skill now state what app-fidelity keeps vs strips** — structural primitives + sans default kept; presentation defaults (preset tokens, chips, prose caps, body bg/color, Inter) stripped — so the "use `.window` for mockups" guidance and the engine no longer contradict each other.
+
 ## 0.2.29 — 2026-05-25
 
 ### Fixed

package/dist/client/viewer.js

@@ -110,6 +110,127 @@
 :root[data-theme="light"] .chip.info { background:#ecfeff; color:#0e7490; border-color:#a5f3fc; box-shadow:0 0 12px -6px rgba(14,116,144,.45); }
 :root[data-theme="dark"]  .chip.info { background:#0a1c22; color:#67e8f9; border-color:#155060; box-shadow:0 0 12px -4px rgba(103,232,249,.4); }
 .chip.accent { background:var(--ds-accent-soft); color:var(--ds-accent); border-color:transparent; box-shadow:0 0 12px -4px color-mix(in srgb, var(--ds-accent) 40%, transparent); }
+`;
+
+  /* Self-contained structural primitives — window chrome + locked code/terminal.
+     These pin their own background and ink with fixed (theme-independent) colours,
+     so unlike the preset-token presentation styles they CAN'T leak the host theme.
+     Injected in BOTH the normal wrapper AND app-fidelity (mockup/app) mode: a UI
+     recreation is exactly where an agent reaches for a window frame or a code
+     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 = `
+/* Skeuomorphic macOS-style window chrome for UI mockups. Usage:
+     <div class="window" data-title="App name"> …mockup content… </div>
+   Draws a 40px title bar with the three traffic-light dots (red/yellow/green)
+   and an optional centred title from data-title. Content sits below the bar.
+   Add the desktop class for a full desktop-screen canvas — min-height 900px,
+   i.e. the 1440x900 (16:10) standard design canvas — so a screen mockup looks
+   like a real window with viewport breathing room rather than a short strip.
+   Omit desktop for dialogs / small components so they stay content-sized.
+
+   A mockup renders an app's own UI, so it owns a STABLE surface that does NOT
+   flip with the host theme — otherwise a light dashboard mockup renders on a dark
+   window in a dark-mode viewer and every subtle gray label washes out (same
+   surface-vs-ink mismatch the .code primitive locks against). Default is a light
+   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 {
+  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;
+}
+.window * { color: inherit; }
+.window::before {
+  content: "";
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  height: 40px;
+  background-color: #f1f1f1;
+  border-bottom: 1px solid #e2e2e2;
+  background-image:
+    radial-gradient(circle at 19px 20px, #ff5f57 6px, transparent 6.5px),
+    radial-gradient(circle at 39px 20px, #febc2e 6px, transparent 6.5px),
+    radial-gradient(circle at 59px 20px, #28c840 6px, transparent 6.5px);
+  background-repeat: no-repeat;
+}
+.window::after {
+  content: attr(data-title);
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  height: 40px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 13px;
+  font-weight: 500;
+  color: #6b6b6b;
+  pointer-events: none;
+}
+.window.dark {
+  border-color: #2a2a2a;
+  background: #161616;
+  color: #e6edf3;
+  box-shadow: 0 14px 48px rgba(0, 0, 0, 0.4);
+}
+.window.dark::before {
+  background-color: #1f1f1f;
+  border-bottom-color: #2a2a2a;
+}
+.window.dark::after { color: #9b9b9b; }
+.window.desktop {
+  min-height: 900px;
+}
+/* Locked-dark code / terminal primitive. Reach for this instead of hand-rolling
+   a dark code container — the recurring failure is a custom dark <div> that sets
+   its own background but lets base text inherit .wrap's light-dark() ink, which
+   resolves to near-black in light host mode and vanishes against the dark panel.
+   This class locks BOTH background and ink, and re-scopes color:inherit to every
+   child so the host theme can never leak in. Ships the verified github-dark token
+   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;
+  border-radius: 12px;
+  padding: 18px 22px;
+  font-family: ui-monospace, "SF Mono", Menlo, monospace;
+  font-size: 13.5px;
+  line-height: 1.7;
+  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 */
+@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; }
+}
 `;
 
   const unreadIds = new Set();
@@ -653,7 +774,11 @@
 <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; }
-html, body { margin: 0; padding: 0; }
+/* Sane sans-serif floor so an unstyled mockup doesn't fall back to Times serif.
+   No CDN font here (that's the agent's call in fidelity mode) — the pushed HTML
+   can override font-family inline / in its own <style>, which wins the cascade. */
+html, body { margin: 0; padding: 0; font-family: system-ui, -apple-system, "Segoe UI", sans-serif; }
+${STRUCTURAL_PRIMITIVES_CSS}
 </style>
 </head>
 <body>
@@ -671,9 +796,10 @@ ${body}
 <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}
-*, *::before, *::after { box-sizing: border-box; }
+${STRUCTURAL_PRIMITIVES_CSS}
 html, body {
   margin: 0;
   background: var(--ds-bg-elev);
@@ -703,7 +829,10 @@ body > h1, body > h2, body > h3, body > h4,
 body > .wrap > p, body > .wrap > .deck, body > .wrap > .lede,
 body > .wrap > ul, body > .wrap > ol, body > .wrap > blockquote,
 body > .wrap > h1, body > .wrap > h2, body > .wrap > h3, body > .wrap > h4 {
-  max-width: 880px;
+  /* ~56ch of "0"-width lands ~66 actual characters in proportional Inter
+     (avg glyph is narrower than "0"), i.e. Bringhurst's reading-measure sweet
+     spot — not 56 literal characters. */
+  max-width: 56ch;
 }
 body > *:first-child { margin-top: 0 !important; }
 body > *:last-child { margin-bottom: 0 !important; }
@@ -714,83 +843,13 @@ body > *:last-child { margin-bottom: 0 !important; }
    stays as a gutter, so neither the mockup nor the surrounding text ever touches
    the card border. (The name is historical — it's "full content width", not
    "bleed to the card edge".) Capped at 100% of the content column, which the
-   body's max-width already limits to desktop-realistic proportions. */
+   body's max-width already limits to desktop-realistic proportions.
+   Vertical margin gives an embedded mockup breathing room from the prose above
+   and below it (without it, the next paragraph hugs the frame). */
 .full-bleed {
   width: 100%;
   max-width: 100% !important;
-  margin-left: 0;
-  margin-right: 0;
-}
-/* Skeuomorphic macOS-style window chrome for UI mockups. Usage:
-     <div class="window" data-title="App name"> …mockup content… </div>
-   Draws a 40px title bar with the three traffic-light dots (red/yellow/green)
-   and an optional centred title from data-title. Content sits below the bar.
-   Add the desktop class for a full desktop-screen canvas — min-height 900px,
-   i.e. the 1440x900 (16:10) standard design canvas — so a screen mockup looks
-   like a real window with viewport breathing room rather than a short strip.
-   Omit desktop for dialogs / small components so they stay content-sized.
-
-   A mockup renders an app's own UI, so it owns a STABLE surface that does NOT
-   flip with the host theme — otherwise a light dashboard mockup renders on a dark
-   window in a dark-mode viewer and every subtle gray label washes out (same
-   surface-vs-ink mismatch the .code primitive locks against). Default is a light
-   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 {
-  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;
-}
-.window * { color: inherit; }
-.window::before {
-  content: "";
-  position: absolute;
-  top: 0;
-  left: 0;
-  right: 0;
-  height: 40px;
-  background-color: #f1f1f1;
-  border-bottom: 1px solid #e2e2e2;
-  background-image:
-    radial-gradient(circle at 19px 20px, #ff5f57 6px, transparent 6.5px),
-    radial-gradient(circle at 39px 20px, #febc2e 6px, transparent 6.5px),
-    radial-gradient(circle at 59px 20px, #28c840 6px, transparent 6.5px);
-  background-repeat: no-repeat;
-}
-.window::after {
-  content: attr(data-title);
-  position: absolute;
-  top: 0;
-  left: 0;
-  right: 0;
-  height: 40px;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  font-size: 13px;
-  font-weight: 500;
-  color: #6b6b6b;
-  pointer-events: none;
-}
-.window.dark {
-  border-color: #2a2a2a;
-  background: #161616;
-  color: #e6edf3;
-  box-shadow: 0 14px 48px rgba(0, 0, 0, 0.4);
-}
-.window.dark::before {
-  background-color: #1f1f1f;
-  border-bottom-color: #2a2a2a;
-}
-.window.dark::after { color: #9b9b9b; }
-.window.desktop {
-  min-height: 900px;
+  margin: 32px 0;
 }
 .wrap { display: block; }
 .kicker {
@@ -858,35 +917,6 @@ pre {
   margin: 16px 0 24px;
 }
 pre code { background: transparent; padding: 0; color: inherit; font-size: inherit; }
-/* Locked-dark code / terminal primitive. Reach for this instead of hand-rolling
-   a dark code container — the recurring failure is a custom dark <div> that sets
-   its own background but lets base text inherit .wrap's light-dark() ink, which
-   resolves to near-black in light host mode and vanishes against the dark panel.
-   This class locks BOTH background and ink, and re-scopes color:inherit to every
-   child so the host theme can never leak in. Ships the verified github-dark token
-   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;
-  border-radius: 12px;
-  padding: 18px 22px;
-  font-family: ui-monospace, "SF Mono", Menlo, monospace;
-  font-size: 13.5px;
-  line-height: 1.7;
-  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 */
 blockquote {
   border-left: 3px solid var(--ds-accent);
   margin: 18px 0;
@@ -933,13 +963,7 @@ img { max-width: 100%; height: auto; border-radius: 10px; }
   body { padding: 24px !important; max-width: none !important; }
   body > p, body > .deck, body > .lede, body > ul, body > ol, body > blockquote,
   body > h1, body > h2, body > h3, body > h4 { max-width: none !important; }
-  pre, code, .code, .terminal { background: #f4f3ed !important; color: #111 !important; border: 1px solid #ddd; }
-  .code *, .terminal * { color: #111 !important; }
-  /* Force the dark window variant light for print — browsers drop background
-     colors by default, which would leave its light ink invisible on white paper
-     (same reason .code/.terminal are forced light above). */
-  .window.dark { background: #ffffff !important; color: #111 !important; }
-  .window.dark * { color: #111 !important; }
+  /* .code/.terminal/.window.dark print overrides live in STRUCTURAL_PRIMITIVES_CSS. */
   .card, .panel { background: #fff !important; border: 1px solid #ddd !important; box-shadow: none !important; }
   a { color: #111 !important; text-decoration: underline; border-bottom: 0 !important; }
 }

package/dist/mcp.js

@@ -72,7 +72,7 @@ const inputSchema = {
         },
         kind: {
             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 (Inter body font, design-token CSS, semantic chips, prose width constraints, body bg/color). Only the box-sizing reset and the html-to-image bridge stay. Use this when the push is a recreation of real UI (app screen, component instance, embedded preview) and you want full control over every pixel without the host theme leaking in. For presentation content (explanations, comparisons, status reports), omit kind or use a non-fidelity value.",
+            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.",
         },
     },
     required: ["html"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ammduncan/easel",
-  "version": "0.2.29",
+  "version": "0.3.1",
   "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/skills/using-easel/SKILL.md

@@ -299,7 +299,7 @@ Most mockups appear *inside* an explanation push — prose intro, embedded UI mo
 `.full-bleed` is injected into every presentation push. Prose is left-aligned and capped at ~880px; `.full-bleed` fills the **content column's full width from the same left edge** — wider than the prose, sharing one left margin down the card. It does *not* bleed to the card's physical edge: the body padding stays as a gutter, so neither the mockup nor the text ever touches the card border.
 
 Two cases, two tools:
-- **Whole push is a mockup / app recreation** → `kind: "mockup"` (or `"app"`) on the push. Strips the entire presentation frame; content owns the canvas.
+- **Whole push is a mockup / app recreation** → `kind: "mockup"` (or `"app"`) on the push. Strips the *presentation* frame (preset tokens, semantic chips, prose-width caps, body bg/color, the Inter webfont) so the content owns the canvas — but **keeps the structural primitives** (`.window`/`.window.dark`, `.code`/`.terminal`) and a neutral system-sans default font, so `.window` and friends still render in a mockup. To match the real app's typeface, **inject its webfont right in the pushed HTML** — a `<link rel="stylesheet" href="…">` or an `@font-face` block loads fine in the sandbox — then set `font-family` on the content; that wins over the sans default.
 - **Mockup embedded in an explanation** → leave the push as-is and wrap the mockup section in `<div class="full-bleed">`.
 
 ### Window chrome for UI mockups