@ammduncan/easel 0.2.27 → 0.2.28

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to easel. This project adheres to [Semantic Versioning](https://semver.org/).
 
+## 0.2.28 — 2026-05-25
+
+### Added
+- **Built-in `.code` / `.terminal` code-block primitive — kills the invisible-code-block bug at the source.** The single most recurring failure was a hand-rolled dark code container: an agent sets `background:#0f172a` on a custom div but leaves 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). The guidance to lock bg+ink as a pair was correct but purely advisory — it relied on the agent remembering it every push. Now the wrapper ships a baked-in primitive: `<div class="code">` (alias `.terminal`) locks both background and ink, re-scopes `color: inherit` to every child, and provides the verified github-dark token classes (`.kw .string .fn .prop .num .comment .muted .accent`) so syntax highlighting reads against `#0f172a` with no per-token tuning. Same lever as the existing `.window` chrome — a safe primitive agents reach for instead of hand-rolling. Prints on white paper with dark text like `pre`/`code`.
+
+### Docs
+- **Steered the `push` tool description and skill toward the new primitive.** The locked-mode section now leads with "use the built-in `.code`/`.terminal`, don't hand-roll", demoting the hand-rolled CSS to a fallback for other locked containers (brand heroes, custom callouts). Added a "Code & terminal blocks" entry to the skill's Built-in helpers. Plain `<pre>`/`<code>` remain safe (bg+ink token pair) as before.
+
 ## 0.2.27 — 2026-05-23
 
 ### Fixed

package/dist/client/viewer.js

@@ -837,6 +837,35 @@ 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;
@@ -883,7 +912,8 @@ 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 { background: #f4f3ed !important; color: #111 !important; border: 1px solid #ddd; }
+  pre, code, .code, .terminal { background: #f4f3ed !important; color: #111 !important; border: 1px solid #ddd; }
+  .code *, .terminal * { color: #111 !important; }
   .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

@@ -112,12 +112,17 @@ export async function main() {
                     "  .wrap { color: light-dark(#111, #e8e8e8); 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" +
-                    "═══ COPY-PASTE STARTER (LOCKED-MODE container — terminal, code block, brand hero) ═══\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 terminal in light host mode → invisible). This is the #1 thing that goes wrong on terminals and code blocks.\n" +
-                    "  .terminal { background: #0f172a; color: #e6edf3; border-radius: 12px; padding: 20px 24px; font-family: ui-monospace, 'SF Mono', Menlo, monospace; font-size: 13.5px; line-height: 1.7; }\n" +
-                    "  .terminal *, .terminal span, .terminal pre { color: inherit; }\n" +
-                    "  .terminal .muted { color: #94a3b8; }\n" +
-                    "  .terminal .accent { color: #6ee7b7; }\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" +
+                    "  <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" +
+                    "  e.g. <div class=\"code\"><span class=\"kw\">gcloud</span> services enable run.googleapis.com</div>\n" +
+                    "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\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" +
+                    "  .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" +
                     "  .card { background: #ffffff; color: #111111; border: 1px solid #e5e5e5; border-radius: 12px; padding: 24px 32px; }\n" +
                     "  .card * { color: inherit; }\n" +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ammduncan/easel",
-  "version": "0.2.27",
+  "version": "0.2.28",
   "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

@@ -205,8 +205,10 @@ So the rule is **faithful height, not minimal height** — but always expressed
 
 The test: cropped the same way, would your mock look like a screenshot of the real thing? Empty bands the real screen doesn't have = over-padded. A desktop screen squashed to a short strip = under-sized.
 
+**For code / terminal blocks, don't hand-roll — use the built-in `.code` / `.terminal` primitive** (see Built-in helpers below). It already locks bg + ink, re-scopes `color: inherit` to children, and ships the verified github-dark token palette. The hand-rolled patterns below are the fallback for *other* locked containers (brand heroes, custom dark callouts) where no primitive fits.
+
 ```css
-/* Locked-dark container (terminal, dark code block, dark callout). */
+/* Locked-dark container (custom dark callout, brand hero). */
 .terminal {
   background: #0f172a;  /* locked dark, ignores host mode */
   color: #e6edf3;       /* MUST set text too */
@@ -328,6 +330,20 @@ The width rule above has a vertical twin, and it's the more common footgun: **ne
 - **Decorative frames** (browser chrome, phone bezel, device frame) must grow with their content — give the frame `min-height` and let it expand, or don't constrain height at all.
 - **The mental test:** render the tallest card in your head. If any text or button could exceed the container, the container is wrong. When unsure, leave height unset. A mockup exists to show the design *fully* — uniform-looking rectangles are never worth clipped content; let frames be different heights.
 
+### Code & terminal blocks
+
+Reach for the built-in **`.code`** (alias **`.terminal`**) class instead of hand-rolling a dark code container — that hand-roll is the single most recurring failure (custom `background:#0f172a` div + base text inheriting `.wrap`'s `light-dark(#111,…)` → invisible in light host mode). The primitive locks bg + ink, re-scopes `color: inherit` to children, and ships the verified github-dark token palette so syntax highlighting reads against `#0f172a` with no per-token tuning:
+
+```html
+<div class="code">
+  <span class="kw">gcloud</span> services enable run.googleapis.com
+  <span class="comment"># dvla artifact registry</span>
+  <span class="prop">--location=</span><span class="string">europe-west1</span>
+</div>
+```
+
+Token classes: `.kw` (keywords) · `.string` · `.fn` (functions) · `.prop` (identifiers/properties) · `.num` · `.comment` · `.muted` · `.accent`. Plain `<pre>`/`<code>` are already safe too (bg + ink token pair). Only hand-roll a custom dark container when neither fits — and then obey the locked-mode pairing rule above.
+
 ### Semantic chips
 
 ```html