npm - @ammduncan/easel - Versions diffs - 0.2.11 → 0.2.13 - Mend

@ammduncan/easel 0.2.11 → 0.2.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/CHANGELOG.md +10 -0
package/dist/client/viewer.js +26 -4
package/dist/mcp.js +4 -1
package/package.json +1 -1
package/skills/using-easel/SKILL.md +15 -1

package/CHANGELOG.md CHANGED Viewed

@@ -2,6 +2,16 @@
 All notable changes to easel. This project adheres to [Semantic Versioning](https://semver.org/).
+## 0.2.13 — 2026-05-23
+### Added
+- **`kind: "mockup"` and `kind: "app"` switch the iframe into app-fidelity mode.** The wrapper skips its presentation defaults (Inter body font, design-token CSS, semantic chips, body bg/color, prose width constraints) and only keeps the box-sizing reset and the html-to-image bridge. Agent paints everything. Makes the existing "App/UI recreations are always locked-mode" rule structural — for a true mockup, opt in via `kind` and the wrapper stops fighting you instead of relying on the agent remembering to override every default. Presentation pushes (explanations, comparisons, status reports) keep the existing wrapper as before.
+## 0.2.12 — 2026-05-23
+### Docs
+- **Locked-mode guidance now ships a paired light example next to the dark one.** The existing rule — "background and text are a pair, commit both, re-scope `color: inherit` to children" — was illustrated only with a dark `.terminal` block. Agents (and people) generalized the rule to "lock your dark containers" and missed the equally-common inverse: a white `.card` on the host canvas with no `color:` of its own, which in dark host mode inherits `.wrap`'s `light-dark()` and resolves to light gray → invisible titles on white. The skill and inline `push` tool description now show both shapes side by side so agents see the rule is direction-agnostic.
 ## 0.2.11 — 2026-05-22
 ### Docs

package/dist/client/viewer.js CHANGED Viewed

@@ -585,7 +585,7 @@
     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);
+    iframe.srcdoc = wrapPushedHtml(push.html, currentTheme(), push.id, push.kind);
     iframe.addEventListener("load", () => {
       iframes.add(iframe);
       // Primary path: the iframe self-measures and posts back size via
@@ -607,7 +607,7 @@
        - write plain HTML (<h1>, <h2>, <p>, etc.) — gets styled for free, OR
        - write their own <style> and override anything.
      ============================================================ */
-  function wrapPushedHtml(html, theme, pushId) {
+  function wrapPushedHtml(html, theme, pushId, kind) {
     // Authors sometimes wrap payloads in <![CDATA[ ... ]]> (treating html
     // like CDATA-in-XML). Strip the XML-ism before doing anything else —
     // otherwise the iframe renders the CDATA tags as visible text.
@@ -620,7 +620,8 @@
     if (lower.startsWith("<!doctype") || lower.startsWith("<html")) {
       return injectBridge(cleaned, theme, preset, pushId);
     }
-    return buildDefaultWrapper(cleaned, theme, preset, pushId);
+    const isAppFidelity = kind === "mockup" || kind === "app";
+    return buildDefaultWrapper(cleaned, theme, preset, pushId, isAppFidelity);
   }
   function selfMeasureScript(pushId) {
@@ -631,8 +632,29 @@
     );
   }
-  function buildDefaultWrapper(body, theme, preset, pushId) {
+  function buildDefaultWrapper(body, theme, preset, pushId, appFidelity) {
     const density = currentDensity();
+    // app-fidelity mode: skip presentation defaults (presets, semantic chips,
+    // body font/bg/color, prose constraints). Agent paints everything. Only
+    // keeps box-sizing reset + the html-to-image bridge script.
+    if (appFidelity) {
+      return `<!DOCTYPE html>
+<html data-theme="${theme}" data-preset="${preset}" data-density="${density}" data-app-fidelity="true">
+<head>
+<meta charset="utf-8" />
+<base target="_blank" />
+<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; }
+</style>
+</head>
+<body>
+${body}
+<script>${selfMeasureScript(pushId)}</script>
+</body>
+</html>`;
+    }
     return `<!DOCTYPE html>
 <html data-theme="${theme}" data-preset="${preset}" data-density="${density}">
 <head>

package/dist/mcp.js CHANGED Viewed

@@ -82,7 +82,7 @@ const inputSchema = {
         },
         kind: {
             type: "string",
-            description: "Freeform tag: mockup, diff, explanation, comparison, diagram, status, progress, etc.",
+            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.",
         },
     },
     required: ["html"],
@@ -128,6 +128,9 @@ export async function main() {
                     "  .terminal *, .terminal span, .terminal pre { color: inherit; }\n" +
                     "  .terminal .muted { color: #94a3b8; }\n" +
                     "  .terminal .accent { color: #6ee7b7; }\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" +
                     "• 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" +
                     "═══ TYPOGRAPHY (presentation scale, NOT dashboard) ═══\n" +
                     "• Hero title: 44–52px, weight 500, letter-spacing -0.025em\n" +

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@ammduncan/easel",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "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 CHANGED Viewed

@@ -189,14 +189,28 @@ When the mockup references a real thing — a real app, a real component, a real
 **If you can't reach the actuals**, say so explicitly in the chat reply (e.g. *"Couldn't find the project's theme file — colors and sizing in this mock are estimates"*) and skip the mock if it would mislead. A recreation labelled "approximation" is fine; one passed off as accurate is a trap.
 ```css
+/* Locked-dark container (terminal, dark code block, dark callout). */
 .terminal {
   background: #0f172a;  /* locked dark, ignores host mode */
   color: #e6edf3;       /* MUST set text too */
 }
 .terminal * { color: inherit; }  /* re-scope so .wrap's light-dark() doesn't leak in */
+/* Locked-LIGHT container (white card on the host canvas). Just as common a
+ * failure as the dark case: a white `.card` with no `color:` of its own
+ * inherits `.wrap`'s light-dark() text → in dark host mode that resolves to
+ * light gray → invisible titles on a white card. Commit the same way. */
+.card {
+  background: #ffffff;  /* locked white, ignores host mode */
+  color: #111111;       /* MUST set text too */
+  border: 1px solid #e5e5e5;
+  border-radius: 12px;
+  padding: 24px 32px;
+}
+.card * { color: inherit; }
 ```
-The rule of thumb: background and text are a pair — commit one, commit the other.
+The rule of thumb: background and text are a pair — commit one, commit the other. The direction (dark or light) doesn't matter; the pairing does.
 **Syntax highlighting in locked-bg code blocks needs *every token* verified.** "Bg + text are a pair" extends to every token color you use. The recurring failure: lock a code block to `#0f172a`, then layer syntax tokens where one (usually `property`, `punctuation`, or `comment`) is colored `#2c2c40` or `#3b4252` because it "looked subtle" — against `#0f172a` it's nearly invisible and whole identifiers disappear from the block. Two ways out: