@ammduncan/easel 0.5.1 → 0.6.1

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to easel. This project adheres to [Semantic Versioning](https://semver.org/).
 
+## 0.6.1 — 2026-06-04
+
+### Changed
+- **The "different session" push hint now requires the surface-the-tab question to be asked ALONE.** When a push lands while easel is open on another session, the tool result tells the agent to ask the user whether to (a) switch the open tab or (b) open a fresh one. Agents were bundling that question into a multi-question prompt alongside follow-ups that assumed the user had already *seen* the pushed content — which they hadn't, since the tab wasn't surfaced yet. The hint now spells it out: ask this one question first, by itself; once the tab is visible, ask the rest. Prompt-text only; no runtime change.
+
+## 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" +
@@ -312,7 +314,7 @@ export async function main() {
         }
         else if (openResult.kind === "other-session") {
             tabHint =
-                " · easel is open in another tab, but on a DIFFERENT session — so this push isn't visible yet. ASK THE USER how to surface it, and if your client has an interactive question/prompt tool (e.g. AskUserQuestion), USE IT to offer the choice as clickable options rather than burying it in prose: (a) switch the open tab to this session via the topbar 'switch ▾' dropdown, or (b) have you call the `open` tool to launch a fresh tab. Do not auto-open or pick for them.";
+                " · easel is open in another tab, but on a DIFFERENT session — so this push isn't visible yet. ASK THE USER how to surface it, and if your client has an interactive question/prompt tool (e.g. AskUserQuestion), USE IT to offer the choice as clickable options rather than burying it in prose: (a) switch the open tab to this session via the topbar 'switch ▾' dropdown, or (b) have you call the `open` tool to launch a fresh tab. Do not auto-open or pick for them. This question MUST be asked ALONE — never bundle it with other questions in the same prompt call. Any other question you'd ask alongside it almost certainly assumes the user has already seen the pushed content, which they haven't until they surface the tab. Ask this one first, by itself; once the tab is visible, ask the rest.";
         }
         else if (result.sessionTabs === 0) {
             tabHint =

package/package.json

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

@@ -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: