@ammduncan/easel 0.2.23 → 0.2.25

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to easel. This project adheres to [Semantic Versioning](https://semver.org/).
 
+## 0.2.25 — 2026-05-23
+
+### Docs
+- **Documented the `.window` primitive and the "build mockups fluid" rule.** Added the `.window` / `.window.desktop` chrome to the skill's helpers section (it shipped in 0.2.24 with CSS but wasn't written up), and a guidance rule: lay desktop mockups 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 narrowed, so there's no horizontal scroll, nothing clipped, and PNG/PDF exports stay complete. (Answers "should desktop mockups scroll horizontally when squeezed?" — no; build fluid so they reflow.) Also corrected the now-stale `.full-bleed` description to match 0.2.24 (fills the content column from the shared left edge, doesn't bleed to the card's physical edge). Skill + inline `push` tool description.
+
+## 0.2.24 — 2026-05-23
+
+### Added
+- **`.window` primitive — skeuomorphic macOS window chrome for mockups.** `<div class="window" data-title="App name">…</div>` draws a 40px title bar with the three traffic-light dots (red/yellow/green) and a centred title from `data-title`; content sits below. Add the `desktop` class (`class="window desktop"`) for the 1440×900 (16:10) standard design canvas via `min-height: 900px` — so a full desktop-screen mockup looks like a real window with viewport breathing room, while a dialog/component in the same chrome (no `desktop`) stays content-sized. Pairs with `.full-bleed` to fill the content column.
+
+### Changed
+- **Reading column is now left-aligned with a shared left edge, instead of per-element centred.** 0.2.22 centred each prose element independently, which produced a ragged left edge when elements had different `max-width`s (e.g. a deck capped narrower than the heading). Reverted to left-aligned prose; `.full-bleed` now fills the content column from the *same* left edge (dropped the viewport-breakout/centring) — so prose and mockups share one left margin down the card, and neither touches the card edge (the body padding stays as a gutter).
+- **Client JS/CSS now sent with `Cache-Control: no-cache`** so a normal reload revalidates and picks up updates, instead of serving a stale cached `viewer.js` that required a hard reload (⌘⇧R). Takes effect after the MCP server restarts.
+
 ## 0.2.23 — 2026-05-23
 
 ### Changed

package/dist/client/viewer.js

@@ -692,46 +692,84 @@ body {
 @media (min-width: 2000px) {
   body { max-width: 1600px; }
 }
-/* Constrain prose to a comfortable reading length, but let visual blocks
-   (cards, grids, tables, mockups) use the full card width. Match prose both
-   as direct body children AND one level deep through a .wrap container —
-   the skill recommends wrapping content in div.wrap, and without the
-   .wrap branch the cap silently misses and prose stretches full width.
-   .full-bleed still escapes via viewport units regardless of nesting. */
+/* Constrain prose to a comfortable reading length and LEFT-ALIGN it to the
+   content column's left edge. Visual blocks (cards, grids, mockups, .full-bleed)
+   fill the wider content column from the SAME left edge — so prose and mockups
+   share one left margin down the card. Match prose both as direct body children
+   AND one level deep through a .wrap container (the skill recommends wrapping
+   content in div.wrap; without the .wrap branch the cap silently misses). */
 body > p, body > .deck, body > .lede, body > ul, body > ol, body > blockquote,
 body > h1, body > h2, body > h3, body > h4,
 body > .wrap > p, body > .wrap > .deck, body > .wrap > .lede,
 body > .wrap > ul, body > .wrap > ol, body > .wrap > blockquote,
 body > .wrap > h1, body > .wrap > h2, body > .wrap > h3, body > .wrap > h4 {
   max-width: 880px;
-  /* Centre the reading column in the card so it stays balanced whether or not
-     a .full-bleed sibling has widened the body. Without auto margins the
-     capped prose sits flush-left with a large empty right gutter next to any
-     full-bleed block. !important is required because authors routinely set an
-     inline margin shorthand like 0 0 16px on prose — that sets the left/right
-     margins to 0 and would otherwise win over the stylesheet, leaving that one
-     element flush-left while its siblings centre (inconsistent column edge).
-     We only force the horizontal margins; inline top/bottom spacing is kept. */
-  margin-left: auto !important;
-  margin-right: auto !important;
 }
 body > *:first-child { margin-top: 0 !important; }
 body > *:last-child { margin-bottom: 0 !important; }
-/* Full-bleed escape hatch for embedded mockups mid-presentation. Wrap a
-   section in <div class="full-bleed"> and it breaks out of the body padding +
-   prose max-width to span the card, while the prose around it stays in the
-   reading column. Inside the iframe, 100vw === the card's width; left:50% +
-   translateX(-50%) re-centres on the card.
-   Capped at 1440px: on a wide monitor the card itself can be ~2000px, but a
-   real desktop screen tops out around 1440 — letting a mockup stretch past
-   that looks unnaturally wide. So full-bleed fills the card up to 1440 and
-   then centres, rather than growing without limit. */
+/* Wide-content escape for embedded mockups mid-presentation. Wrap a section in
+   <div class="full-bleed"> and it fills the content column's full width —
+   wider than the 880px prose cap — while sharing the prose's LEFT edge. It does
+   NOT break out to the card's physical edge: the body's horizontal padding
+   stays as a gutter, so neither the mockup nor the surrounding text ever touches
+   the card border. (The name is historical — it's "full content width", not
+   "bleed to the card edge".) Capped at 100% of the content column, which the
+   body's max-width already limits to desktop-realistic proportions. */
 .full-bleed {
-  width: min(100vw, 1440px);
+  width: 100%;
+  max-width: 100% !important;
+  margin-left: 0;
+  margin-right: 0;
+}
+/* Skeuomorphic macOS-style window chrome for UI mockups. Usage:
+     <div class="window" data-title="App name"> …mockup content… </div>
+   Draws a 40px title bar with the three traffic-light dots (red/yellow/green)
+   and an optional centred title from data-title. Content sits below the bar.
+   Add the desktop class for a full desktop-screen canvas — min-height 900px,
+   i.e. the 1440x900 (16:10) standard design canvas — so a screen mockup looks
+   like a real window with viewport breathing room rather than a short strip.
+   Omit desktop for dialogs / small components so they stay content-sized. */
+.window {
   position: relative;
-  left: 50%;
-  transform: translateX(-50%);
-  max-width: 100vw;
+  padding-top: 40px;
+  border-radius: 12px;
+  border: 1px solid light-dark(#e2e2e2, #2a2a2a);
+  box-shadow: 0 14px 48px rgba(0, 0, 0, 0.16);
+  overflow: hidden;
+  background: light-dark(#ffffff, #161616);
+}
+.window::before {
+  content: "";
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  height: 40px;
+  background-color: light-dark(#f1f1f1, #1f1f1f);
+  border-bottom: 1px solid light-dark(#e2e2e2, #2a2a2a);
+  background-image:
+    radial-gradient(circle at 19px 20px, #ff5f57 6px, transparent 6.5px),
+    radial-gradient(circle at 39px 20px, #febc2e 6px, transparent 6.5px),
+    radial-gradient(circle at 59px 20px, #28c840 6px, transparent 6.5px);
+  background-repeat: no-repeat;
+}
+.window::after {
+  content: attr(data-title);
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  height: 40px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 13px;
+  font-weight: 500;
+  color: light-dark(#6b6b6b, #9b9b9b);
+  pointer-events: none;
+}
+.window.desktop {
+  min-height: 900px;
 }
 .wrap { display: block; }
 .kicker {

package/dist/http-server.js

@@ -51,6 +51,16 @@ export function startHttpServer() {
     app.use("/static", express.static(CLIENT_DIR, {
         fallthrough: false,
         maxAge: "0",
+        etag: true,
+        lastModified: true,
+        // Force the browser to revalidate the client JS/CSS on every load (via
+        // ETag) instead of serving a stale cached copy. Without this a plain
+        // reload after an easel update keeps the old viewer.js — the user has to
+        // hard-reload (⌘⇧R) to pick up new styles, which has bitten us. `no-cache`
+        // means "cached copy is fine ONLY after revalidating it's unchanged".
+        setHeaders: (res) => {
+            res.setHeader("Cache-Control", "no-cache");
+        },
     }));
     app.get("/health", (_req, res) => {
         res.json({ ok: true, pid: process.pid, port });

package/dist/mcp.js

@@ -139,7 +139,9 @@ export async function main() {
                     "═══ LAYOUT ═══\n" +
                     "• 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 has a ~880px reading-width cap, but a mockup section should fill the full card. Wrap JUST the mockup in <div class=\"full-bleed\">…</div> — it breaks out of the body padding + prose cap to span the full card width, while surrounding prose stays in the reading column. (If the WHOLE push is a UI recreation, use kind:'mockup'/'app' instead — that strips the entire frame.)\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" +
+                    "• 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" +
                     "• 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" +

package/package.json

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

@@ -293,12 +293,29 @@ Most mockups appear *inside* an explanation push — prose intro, embedded UI mo
 <p>The left panel uses the existing brand assets…</p>
 ```
 
-`.full-bleed` is injected into every presentation push. It breaks the wrapped element out of the body padding + 1400px prose cap to span the full card width, then everything outside it stays in the reading column. This is the right tool when a mockup is one section of a longer push.
+`.full-bleed` is injected into every presentation push. Prose is left-aligned and capped at ~880px; `.full-bleed` fills the **content column's full width from the same left edge** — wider than the prose, sharing one left margin down the card. It does *not* bleed to the card's physical edge: the body padding stays as a gutter, so neither the mockup nor the text ever touches the card border.
 
 Two cases, two tools:
 - **Whole push is a mockup / app recreation** → `kind: "mockup"` (or `"app"`) on the push. Strips the entire presentation frame; content owns the canvas.
 - **Mockup embedded in an explanation** → leave the push as-is and wrap the mockup section in `<div class="full-bleed">`.
 
+### Window chrome for UI mockups
+
+Wrap a mockup in `.window` to give it a macOS window frame — a title bar with the three traffic-light dots and a centred title:
+
+```html
+<div class="full-bleed">
+  <div class="window desktop" data-title="DVLA Self Service — Login">
+    <!-- mockup content fills the window body, below the 40px title bar -->
+  </div>
+</div>
+```
+
+- `data-title` sets the centred title text (omit for a blank bar).
+- Add the **`desktop`** class for a full desktop-screen canvas — `min-height: 900px`, the standard 1440×900 (16:10) design canvas — so a screen mockup looks like a real window with viewport breathing room. **Omit `desktop`** for a dialog or small component so the chrome sizes to its content (don't pad a small thing to screen height).
+
+**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.
+
 ### Semantic chips
 
 ```html