@ammduncan/easel 0.5.1 → 0.6.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to easel. This project adheres to [Semantic Versioning](https://semver.org/).
 
+## 0.6.0 — 2026-06-03
+
+### Fixed
+- **A `100vh` (or `vh`/`dvh`/`svh`) root no longer silently collapses to a stub.** `vh` resolves against the push iframe — which has no intrinsic viewport — so the idiomatic full-screen app shell (`height: 100vh` on the root) measured against the iframe's ~150px default and cropped mid-content; two different local render-window sizes produced pixel-identical collapsed cards, proving the author's intended viewport never reached easel. The self-measure bridge now reports, alongside the existing floored `height`, a **non-floored `content` height** (walks body-child bottoms instead of the viewport-floored `documentElement.scrollHeight`) and the iframe's own **`vp`**. A parent-side phase machine (`applyMeasuredSize`) leaves normal cards untouched — they size to their content exactly as before, keeping the 150px historical floor — but when content **exactly fills** the viewport (the viewport-lock signature) it probes at a distinct viewport (720px) and, if content tracks it, **pins the card to the 900px desktop canvas** (matching `.window.desktop`) instead of letting it collapse. Stale mid-probe measurements are ignored, and a content that *coincidentally* equals the initial viewport is correctly released to its real height rather than mistaken for `100vh`. Covered by `tests/unit/height-autoguard.test.mjs` (shape) and `tests/unit/height-autoguard-behaviour.test.mjs` (drives the real shipped function through full measurement feedback loops).
+
+### Changed
+- **`push` tool description + `using-easel` skill: documented card sizing and mockup-granularity.** Two additions. (1) A **card-height rule**: card height = your content's intrinsic height; there's no `height` knob and you don't need one (the px you write *is* the height), but avoid `100vh` on the root — it's the one unit that doesn't mean what you think inside the iframe; for a full screen use `min-height: 900px` (or the source's real height) explicitly. (2) A **split-by-role rule** for mockups: the mere presence of a mockup isn't a reason to split it onto its own card — keep it inline (`.full-bleed`, optionally `.window`) when it illustrates the prose's point, but give it its own push (one per screen, `kind:"app"`) when the screen is the primary artifact, when comparing 2+ full screens, or when the user will export/share it standalone. Own-push buys real per-card app fidelity (`kind` is per-push), a faithful frame height, and a clean standalone export.
+
 ## 0.5.1 — 2026-05-31
 
 ### Changed

package/dist/client/viewer.js

@@ -274,8 +274,88 @@
      Self-measure message bridge — iframes post their measured body
      height; we apply it. Reliable across font loads, image loads,
      and dynamic content (the iframe knows when its DOM mutates).
+
+     100vh auto-guard: a root sized with viewport units (100vh/dvh/svh)
+     resolves `vh` against THIS iframe, which has no intrinsic viewport,
+     so it would otherwise collapse to the iframe's default ~150px. The
+     bridge reports a non-floored `content` height plus the iframe's own
+     `vp`; when content exactly fills vp (the viewport-lock signature) we
+     probe at a distinct viewport and, if content tracks it, pin the card
+     to the desktop canvas instead of letting it collapse. Normal cards
+     never enter the probe — they size to the measured `height` exactly
+     as before, so this is zero-change for non-viewport-relative content.
      ============================================================ */
 
+  const EASEL_DESKTOP_CANVAS = 900; // matches .window.desktop min-height
+  const EASEL_PROBE_PX = 720; // distinct probe viewport for vh-lock detection
+  const EASEL_MIN_CARD_PX = 150; // historical floor (the iframe's default height)
+  const iframeSizeState = new Map(); // pushId → { phase }
+
+  function setIframeHeight(iframe, px) {
+    iframe.style.height = Math.max(0, Math.ceil(px)) + "px";
+  }
+
+  // Card height = the iframe's NON-floored content height (never the viewport-
+  // floored documentElement.scrollHeight, which would re-inflate short content
+  // to whatever viewport we last set — fatal once the probe bumps it to 720).
+  function trackedHeight(content) {
+    return Math.max(EASEL_MIN_CARD_PX, content);
+  }
+
+  function applyMeasuredSize(iframe, data) {
+    const content = typeof data.content === "number" ? data.content : data.height;
+    const vp = typeof data.vp === "number" ? data.vp : null;
+
+    // Legacy bridge / no viewport signal: size to the measured height, as before.
+    if (vp === null) {
+      setIframeHeight(iframe, data.height);
+      return;
+    }
+
+    let st = iframeSizeState.get(data.pushId);
+    if (!st) {
+      st = { phase: "initial" };
+      iframeSizeState.set(data.pushId, st);
+    }
+
+    if (st.phase === "pinned") {
+      // Viewport-locked root pinned to the desktop canvas; still grow if real
+      // overflow content exceeds it.
+      setIframeHeight(iframe, Math.max(EASEL_DESKTOP_CANVAS, content));
+      return;
+    }
+    if (st.phase === "tracking") {
+      setIframeHeight(iframe, trackedHeight(content));
+      return;
+    }
+    if (st.phase === "probing") {
+      // Trust only measurements taken AT the probe viewport — ignore stale
+      // pre-resize messages still carrying the old (initial) viewport.
+      if (Math.abs(vp - EASEL_PROBE_PX) > 4) return;
+      if (content >= EASEL_PROBE_PX - 2) {
+        // Content grew to fill the probe viewport → viewport-relative root.
+        st.phase = "pinned";
+        setIframeHeight(iframe, Math.max(EASEL_DESKTOP_CANVAS, content));
+      } else {
+        // Content stayed at its intrinsic height → not viewport-locked.
+        st.phase = "tracking";
+        setIframeHeight(iframe, trackedHeight(content));
+      }
+      return;
+    }
+    // st.phase === "initial"
+    if (vp > 0 && Math.abs(content - vp) <= 2) {
+      // Content exactly fills the iframe's natural viewport — ambiguous: a
+      // collapsed viewport-relative (100vh) root, OR content that just happens
+      // to equal this height. Probe at a distinct viewport to disambiguate.
+      st.phase = "probing";
+      setIframeHeight(iframe, EASEL_PROBE_PX);
+    } else {
+      st.phase = "tracking";
+      setIframeHeight(iframe, trackedHeight(content));
+    }
+  }
+
   window.addEventListener("message", (e) => {
     const data = e && e.data;
     if (!data) return;
@@ -285,7 +365,7 @@
         'iframe[data-push-id="' + cssEscape(data.pushId) + '"]',
       );
       if (!iframe) return;
-      iframe.style.height = Math.max(0, Math.ceil(data.height)) + "px";
+      applyMeasuredSize(iframe, data);
       return;
     }
     if (data.type === "easel:click") {
@@ -796,7 +876,7 @@
     return (
       "(function(){var ID=" +
       JSON.stringify(pushId) +
-      ";function measure(){var b=document.body,h=document.documentElement;if(!b)return 0;return Math.max(b.getBoundingClientRect().bottom,b.scrollHeight,h.scrollHeight)}function send(){try{parent.postMessage({type:'easel:size',pushId:ID,height:measure()},'*')}catch(e){}}send();window.addEventListener('load',send);window.addEventListener('resize',send);if(document.fonts&&document.fonts.ready){document.fonts.ready.then(send).catch(function(){})}if(window.ResizeObserver){var ro=new ResizeObserver(send);if(document.body)ro.observe(document.body);ro.observe(document.documentElement)}var mo=new MutationObserver(send);mo.observe(document.documentElement,{subtree:true,childList:true,characterData:true,attributes:true});setTimeout(send,250);setTimeout(send,800);setTimeout(send,1600)})();"
+      ";function measure(){var b=document.body,h=document.documentElement;if(!b)return 0;return Math.max(b.getBoundingClientRect().bottom,b.scrollHeight,h.scrollHeight)}function content(){var b=document.body;if(!b)return 0;var m=Math.max(b.getBoundingClientRect().bottom,b.scrollHeight);var k=b.children;for(var i=0;i<k.length;i++){var bo=k[i].getBoundingClientRect().bottom;if(bo>m){m=bo}}return m}function vp(){return document.documentElement.clientHeight||0}function send(){try{parent.postMessage({type:'easel:size',pushId:ID,height:measure(),content:content(),vp:vp()},'*')}catch(e){}}send();window.addEventListener('load',send);window.addEventListener('resize',send);if(document.fonts&&document.fonts.ready){document.fonts.ready.then(send).catch(function(){})}if(window.ResizeObserver){var ro=new ResizeObserver(send);if(document.body)ro.observe(document.body);ro.observe(document.documentElement)}var mo=new MutationObserver(send);mo.observe(document.documentElement,{subtree:true,childList:true,characterData:true,attributes:true});setTimeout(send,250);setTimeout(send,800);setTimeout(send,1600)})();"
     );
   }
 
@@ -1290,6 +1370,7 @@ ${body}
       obs.disconnect();
       cardObservers.delete(pushId);
     }
+    iframeSizeState.delete(pushId);
     unreadIds.delete(pushId);
     totalPushes = Math.max(0, totalPushes - 1);
     setPushCount(totalPushes);

package/dist/mcp.js

@@ -155,10 +155,12 @@ export async function main() {
                     "• Stack desktop mockups VERTICALLY with labels ('Now', 'Proposed') — don't squeeze them side-by-side. The iframe is ~900px wide; two desktop screens at half-width crush columns, wrap headings to 3 lines, and turn tables unreadable.\n" +
                     "• Side-by-side is fine only for narrow mobile mockups, small cards, or short text columns that genuinely fit in half-width.\n" +
                     "• Mockup embedded mid-explanation? Prose is left-aligned and capped ~880px; wrap JUST the mockup in <div class=\"full-bleed\">…</div> and it fills the content column from the SAME left edge (wider than the prose, sharing one left margin; the body padding stays as a gutter so nothing touches the card edge). (If the WHOLE push is a UI recreation, use kind:'mockup'/'app' instead.)\n" +
+                    "• SPLIT BY ROLE, not by the mere presence of a mockup. A mockup that ILLUSTRATES the prose's point — a fragment (one row, a button, a chip) or a screen the surrounding text is actively walking through — stays INLINE in the prose push (full-bleed, optionally .window); splitting it would fracture one continuous thought into a pile of cards. But give the mockup its OWN push (one card per screen, kind:'app') when: the SCREEN is the primary artifact and the prose is just a caption / lead-in; OR you're comparing 2+ full screens (each its own card → they stack cleanly and export independently); OR the user will export / share the screen standalone (no prose bleeding above and below). Own-push buys what an inline mockup can't: real per-card app fidelity (kind is per-push, so an inline mockup can't get kind:'app'), a faithful frame height, and a clean standalone export. Rule of thumb: same judgment as full-bleed vs kind:'mockup', one level up.\n" +
                     "• Window chrome: wrap a mockup in <div class=\"window\" data-title=\"App name\">…</div> for a macOS window frame (title bar + red/yellow/green traffic-light dots + centred title). Add the `desktop` class (class=\"window desktop\") for the 1440x900 (16:10) desktop canvas via min-height:900px; omit it so dialogs/components size to content. Combine with .full-bleed to fill the column. .window is a STABLE LIGHT canvas — it pins white bg + dark ink + re-scopes color:inherit to children (like .code/.terminal), so it does NOT flip with the host theme and subtle gray-on-white labels stay legible even in a dark-mode viewer; a mockup is a screenshot, it should look the same to everyone. For a genuinely dark-UI mockup add the `dark` class (class=\"window dark\") — don't hand-roll a dark .window. NOTE: .window sets overflow:hidden (to clip its rounded corners) — so NEVER put a fixed `height` on .window or any inner stage, or content past that height is silently guillotined. It's built to grow via min-height.\n" +
                     "• BUILD MOCKUPS FLUID, not fixed-width. Lay the inside out with flex / % / fr widths, not hardcoded width:1440px columns. 1440 is a MAX, not a target. A fluid mockup reflows to fit when the viewer's window is squeezed — no horizontal scroll, nothing clipped, exports stay complete. A fixed-pixel-width mockup gets cut off or needs an awkward horizontal scrollbar when narrowed.\n" +
                     "• NEVER CLIP CONTENT — no fixed `height` + `overflow:hidden` on any container that holds content (cards, panels, device/browser/phone frames, stages, slideovers, toasts). That combo guillotines anything taller than your guessed height — buttons sliced through text, lists cut mid-item. Containers size to their CONTENT: use `min-height` for a floor, NEVER a fixed `height`. `overflow:hidden` is allowed ONLY for genuine cosmetic crops where clipping IS the intent (rounded-corner image masks, decorative bleed) — never on a content region. Decorative frames must grow with their content. When unsure, leave height unset. Mentally render the tallest card: if any text/button could exceed the box, the box is wrong.\n" +
                     "• MATCH THE SOURCE'S REAL FRAME — faithful height, not minimal, in both directions. Mocking a COMPONENT (card, modal, row, toolbar)? Size to content — do NOT pad with min-height:560px to feel 'desktop-y'; that floats content in dead whitespace. Mocking a FULL DESKTOP SCREEN (login page, dashboard)? Give it realistic viewport proportions via MIN-HEIGHT (e.g. min-height:760px or a 16:10 floor — never a fixed `height`, which clips) and lay content out inside as the real screen does (centred form, top nav). Either way copy the source's exact dimensions if it has them, as a min-height. Test: cropped the same way, would your mock look like a screenshot of the real thing? Empty bands = over-padded; a screen squashed to a strip = under-sized.\n" +
+                    "• CARD HEIGHT = YOUR CONTENT'S INTRINSIC HEIGHT. Easel sizes each card to the rendered height of your HTML — give the root a real height via flowing content or a `min-height`/`height` in **px** and the card is exactly that tall. AVOID `100vh` (or `vh`/`dvh`/`svh`) on the root: those units resolve against easel's own iframe, not a real screen, so a viewport-relative root has no meaningful height and would otherwise COLLAPSE to a stub. Easel auto-detects a viewport-filling root and falls back to the 900px desktop canvas, but don't lean on that guess — for a full desktop screen set `min-height: 900px` (or the source's real height) explicitly; for a component, size to content. px in, predictable card out.\n" +
                     "• When recreating real app UI, hug the source — pull exact colors, spacing, sizing, radii, fonts from the component/theme/Figma/DevTools. A close-but-wrong recreation misleads more than no recreation. If you can't reach the actuals, say so in chat and don't pass the mock off as accurate.\n" +
                     "• One accent color, 3–4 instances max per card. Status colors (red/amber/green) only when state genuinely maps to status.\n\n" +
                     "═══ WHEN TO PUSH ═══\n" +

package/package.json

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

@@ -319,6 +319,18 @@ Two cases, two tools. **The deciding question is NOT "does this push contain a m
 - **Whole push is a single mockup / app recreation** (a dashboard, a screen — nothing but the UI, edge to edge) → `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. Because app-fidelity strips the body padding too, a full-bleed app screen must **supply its own page padding** (e.g. a `.page { padding: 48px 40px }` wrapper) or it runs to the card edge.
 - **Prose + embedded mockup(s)** (the common case — intro text, then specimen(s), maybe more text) → leave `kind` **off** so the presentation frame stays on, and wrap each specimen in `<div class="full-bleed">`. You get the best of both: prose lands in the ~56ch reading measure with comfortable side padding, while the specimens fill the full content column (up to 1400px) — **wider** than the prose, never narrower. Tagging this `kind:"mockup"` is the bug: app-fidelity strips the prose-width cap **and** the side padding, so your paragraphs run to the card edge unless you hand-pad — which you will forget.
 
+#### When a mockup should own its push — split by role, not by presence
+
+Having a mockup in the response is *not* itself a reason to split it onto its own card. The trigger is the mockup's **role**:
+
+- **Keep it inline** (prose push, `.full-bleed`, optionally `.window`) when the mockup **illustrates the point the prose is making** — a fragment (one row, a button, a chip) or a screen the surrounding text is actively walking through. The reader needs prose → visual → prose continuity; splitting fractures one thought into a pile of cards.
+- **Give it its own push** (one card per screen, `kind:"app"`) when:
+  - the **screen is the primary artifact** and the prose is just a caption / lead-in;
+  - you're **comparing 2+ full screens** — each its own card, so they stack cleanly and export independently;
+  - the user will **export or share the screen standalone** — a clean PNG with no prose bleeding above and below.
+
+A mockup gets things on its own push it *can't* get inline: real per-card **app fidelity** (`kind` is per-push, so an inline mockup can never be `kind:"app"`), a **faithful frame height**, and a **clean standalone export**. It's the same full-bleed-vs-`kind:"mockup"` judgment you already make — one level up, at the push boundary.
+
 > **Failure mode (seen in the wild, more than once):** a marketing-kit / lookbook review card — eyebrow, H1, two prose lines, then labelled atom specimens — tagged `kind:"mockup"`. App-fidelity stripped the padding; the author's wrapper had only `padding: 8px 4px`; the prose kissed the card edges. **Fix: drop the `kind`, wrap specimens in `.full-bleed`.** And remember: prose only gets the ~56ch cap when it's a **direct `body` child or inside `div.wrap`** — nest it in a bare `<div>` and the cap silently misses.
 
 ### Window chrome for UI mockups
@@ -351,6 +363,17 @@ 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.
 
+### Card height = your content's intrinsic height — never `100vh` on the root
+
+Easel sizes each card to the **rendered height of your HTML**. Give your root real content, or a `min-height` / `height` in **px**, and the card is exactly that tall. There's no `height` knob on `push` and you don't need one — the px you write *is* the height.
+
+The one trap: **`100vh` (or `vh` / `dvh` / `svh`) on the root.** It's the idiomatic way to write a full-screen app shell, but inside easel `vh` resolves against the **push iframe**, which has no real viewport of its own — so a `100vh` root has no meaningful height and would otherwise **collapse to a stub**. Easel auto-detects a viewport-filling root and falls back to the **900px desktop canvas** (the same height as `.window.desktop`), so it no longer silently crops — but don't lean on that guess:
+
+- **Full desktop screen** → set `min-height: 900px` (or the source's real height) explicitly. Same advice as the sizing section above.
+- **Component** → size to content; don't reach for `100vh` at all.
+
+`px`/`min-height` in, predictable card out. `vh` is the only unit that doesn't mean what you think here.
+
 ### 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: