@ammduncan/easel 0.2.26 → 0.2.27

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to easel. This project adheres to [Semantic Versioning](https://semver.org/).
 
+## 0.2.27 — 2026-05-23
+
+### Fixed
+- **Stopped steering agents into clipped mockups — `min-height`, never fixed `height`.** The mockup-height guidance recommended a fixed `height: 760px` for full-screen mocks, which is the exact footgun that crops content: a fixed `height` + the `overflow: hidden` that frames carry guillotines anything taller than the guessed value (buttons sliced through text, lists cut mid-item). This was self-inconsistent — the wrapper's own `.window.desktop` already uses `min-height: 900px`, not `height`. Changed the full-screen advice to `min-height` throughout (a floor that still lets content grow), and reproduce a source element's height as a `min-height` too.
+
+### Docs
+- **New "Never clip content" rule, the vertical twin of "build mockups fluid".** Never pair a fixed `height` with `overflow: hidden` on any content container (cards, panels, device/browser/phone frames, stages, slideovers, toasts) — containers size to content via `min-height`; `overflow: hidden` is for genuine cosmetic crops only (rounded-corner image masks, decorative bleed). Decorative frames must grow with their content. Also added a `.window`-specific caveat: it carries `overflow: hidden` to clip its rounded corners, so a fixed `height` on `.window` or an inner stage clips invisibly — let it grow via `min-height`. Skill + inline `push` tool description.
+
 ## 0.2.26 — 2026-05-23
 
 ### Changed

package/dist/mcp.js

@@ -140,9 +140,10 @@ 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" +
-                    "• 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.\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. 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" +
-                    "• 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 / height:100vh to feel 'desktop-y'; that floats content in dead whitespace. Mocking a FULL DESKTOP SCREEN (login page, dashboard)? Give it realistic viewport proportions (e.g. height:760px or 16:10) and lay content out inside as the real screen does (centred form, top nav) — cropping a real screen down to just its content height misrepresents it just as much. Either way copy the source's exact height if it has one. 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" +
+                    "• 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" +
                     "• 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.2.26",
+  "version": "0.2.27",
   "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

@@ -194,13 +194,14 @@ A mockup's height should match what it actually represents — don't fake it tal
 
 **Mocking a component** (a card, modal, row, toolbar, button, an embedded section): size it to its **content**. Do NOT slap `min-height: 560px` / `height: 100vh` on a component to make it "feel desktop-y" — that injects dead whitespace and floats the content unnaturally. If the real component is 320 px tall, the mock is 320 px tall.
 
-**Mocking a full desktop screen / page** (the whole viewport — a login screen, a dashboard, a settings page): give it **realistic desktop viewport proportions**, because the surrounding space *is* part of how that screen looks. A login form genuinely sits in a ~720–800 px-tall viewport with the panel centred — cropping that down to just the form's content height misrepresents it as much as over-padding a component does. Use a fixed frame (e.g. `height: 760px` or a 16:10 box) and lay the content out inside it the way the real screen does (centred form, top nav, sidebar full-height, etc.).
+**Mocking a full desktop screen / page** (the whole viewport — a login screen, a dashboard, a settings page): give it **realistic desktop viewport proportions**, because the surrounding space *is* part of how that screen looks. A login form genuinely sits in a ~720–800 px-tall viewport with the panel centred — cropping that down to just the form's content height misrepresents it as much as over-padding a component does. Use **`min-height`** for the floor (e.g. `min-height: 760px` or a 16:10 box) — **never a fixed `height`**, which clips anything taller — and lay the content out inside it the way the real screen does (centred form, top nav, sidebar full-height, etc.). This mirrors the wrapper's own `.window.desktop`, which is `min-height: 900px`, not `height`.
 
-So the rule is **faithful height, not minimal height**:
+So the rule is **faithful height, not minimal height** — but always expressed as `min-height`, never a fixed `height`:
 - Component → content height (no padding to a fake screen size).
-- Full screen → real viewport proportions (don't crop to content).
-- Either way, if the source element has a specific height/min-height, copy that exact value (per the sizing rule above).
+- Full screen → real viewport proportions via `min-height` (don't crop to content, but don't cap it with a fixed `height` either).
+- Either way, if the source element has a specific height, reproduce it as a `min-height` (a floor that still lets content grow) — per the sizing rule above.
 - Vertical-centring inside a tall box is correct *only* when you're mocking a full screen whose real layout centres its content — not as a way to fill a component you've over-sized.
+- **Never `height: <px>` + `overflow: hidden` on a content container** — that's the guillotine. See the never-clip rule under Built-in helpers.
 
 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.
 
@@ -316,6 +317,17 @@ Wrap a mockup in `.window` to give it a macOS window frame — a title bar with
 
 **Build the mockup fluid, not fixed-width.** Lay the inside out with flex / `%` / `fr` widths, not hardcoded `width: 1440px` columns. The content column caps at a desktop-realistic width, but when the viewer's window is narrower (a "squeezed" screen) a fluid mockup simply **reflows to fit** — no horizontal scroll, nothing clipped, and PNG/PDF export still captures the whole thing. A fixed-pixel-width mockup gets cut off or needs an awkward horizontal scrollbar when squeezed; a fluid one never does. The 1440 is a *max*, not a target.
 
+**`.window` sets `overflow: hidden`** (to clip its own rounded corners) and grows via `min-height`, never a fixed height. So **never put a fixed `height` on `.window` itself, or on an inner "stage" element** — content past that height gets silently guillotined, and because the overflow is on the frame the crop is invisible until you export or scroll. Let it grow.
+
+### Never clip content — `min-height`, never fixed `height`
+
+The width rule above has a vertical twin, and it's the more common footgun: **never pair a fixed `height` with `overflow: hidden` on any container that holds content** — cards, panels, device/browser/phone frames, stages, slideovers, toasts. That combination guillotines anything taller than the height you guessed: buttons slice through text, bullet lists cut off mid-item. Agents reach for a round number (`height: 260px`) to "frame" a mock and lop the bottom off, often unprovoked.
+
+- **Containers size to their content.** Use `min-height` if you need a floor — never a fixed `height` — on anything wrapping real content.
+- **`overflow: hidden` is allowed ONLY for genuine cosmetic crops** where clipping *is* the intent: rounded-corner image masks, a decorative bleed. Never on a content region.
+- **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.
+
 ### Semantic chips
 
 ```html