@ammduncan/easel 0.2.1 → 0.2.4

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 All notable changes to easel. This project adheres to [Semantic Versioning](https://semver.org/).
 
+## 0.2.4 — 2026-05-22
+
+### Fixed
+- **Pushes from non-Claude-Code clients (Claude Desktop, Cursor, Windsurf, etc.) ignored the easel style guide.** The full guide lives in the `using-easel` skill — but skills are a Claude Code feature; other MCP clients never see them. The MCP `push` tool's description only said "Pass full HTML" and contained none of the styling rules, so agents in non-CC clients hardcoded one mode's colors. Result: lede text colored `#475569` went invisible in dark mode, hardcoded `#e5e5e5` borders became hard white lines, mockups crammed into half-width columns, etc.
+- The `push` tool description now carries the essentials inline: adaptive-color rules (`light-dark()` + `color: inherit` re-scoping + locked-mode container inverse rule), a copy-paste starter pattern, presentation-scale typography, whitespace, tangible-visual heuristics, vertical stacking of desktop mockups, and the proactive-push convention. Every MCP client surfaces tool descriptions to its agent, so this lands cross-client.
+
+## 0.2.3 — 2026-05-22
+
+### Fixed
+- **Every push was being delivered twice.** The auto-run guard in `dist/mcp.js` had a sloppy fallback (`endsWith("/dist/mcp.js")`) that matched even when the file was imported, not just when it was invoked directly. Result: when the CLI's no-TTY path dynamically imported `mcp.js`, the guard fired AND the CLI explicitly called `main()`, so two MCP servers ran in the same process attached to the same stdin. Every tool call was processed twice. Guard now uses strict equality only.
+- **Sessions index — trash icon overlapped the count/timestamp on short rows.** The hover-revealed delete button was absolutely positioned and collided with the right-column text whenever the row was tight. Promoted to its own grid column so it sits cleanly to the right of the count/when stack regardless of row height.
+
+## 0.2.2 — 2026-05-22
+
+### Fixed
+- **MCP servers wired via `npx -y @ammduncan/easel` now boot the MCP server instead of printing CLI help.** When stdin isn't a TTY (i.e. the process is launched over a pipe by an MCP client), the bin transparently boots the MCP server. Interactive terminal use still shows help. Previously, Claude Desktop, Cursor, and Windsurf saw the CLI's help text on stdout and reported `Unexpected token 'e' is not valid JSON` for every line.
+
+### Added
+- Explicit `easel mcp` subcommand that runs the stdio MCP server in the foreground (used internally by the no-TTY auto-detection; available as an explicit entry point for clients that want it).
+
+### Changed
+- `dist/mcp.js` now exports `main()` and only auto-runs when invoked directly (not when imported), so the CLI can route to it without double-booting.
+
 ## 0.2.1 — 2026-05-22
 
 ### Added

package/dist/cli.js

@@ -28,6 +28,7 @@ Usage:
   easel setup --client claude-desktop    register the MCP in Claude Desktop's config
   easel setup --client windsurf  register the MCP in Windsurf's config
   easel update          git pull + npm install + build + setup (re-runs setup to apply new conventions)
+  easel mcp             run the stdio MCP server in the foreground (used by clients)
   easel restart         kill the running HTTP server and respawn it (picks up new builds/paths)
   easel server          run the HTTP server in the foreground (debug)
   easel version
@@ -377,7 +378,23 @@ async function main() {
         case "-v":
             cmdVersion();
             return;
-        case undefined:
+        case "mcp": {
+            const { main: mcpMain } = await import("./mcp.js");
+            await mcpMain();
+            return;
+        }
+        case undefined: {
+            // When invoked over a pipe (no TTY on stdin) — e.g. an MCP client
+            // launching us via `npx -y @ammduncan/easel` — boot the MCP server.
+            // Interactive terminal use still gets the help text.
+            if (!process.stdin.isTTY) {
+                const { main: mcpMain } = await import("./mcp.js");
+                await mcpMain();
+                return;
+            }
+            help();
+            return;
+        }
         case "help":
         case "--help":
         case "-h":

package/dist/client/index.css

@@ -40,9 +40,9 @@
 .session-row {
   position: relative;
   display: grid;
-  grid-template-columns: 1fr auto;
+  grid-template-columns: 1fr auto auto;
   gap: 18px;
-  align-items: start;
+  align-items: center;
   padding: 20px 22px;
   background: var(--ds-surface);
   border: 1px solid var(--ds-line);
@@ -55,14 +55,11 @@
 }
 
 .session-del {
-  position: absolute;
-  top: 14px;
-  right: 14px;
   display: inline-flex;
   align-items: center;
   justify-content: center;
-  width: 22px;
-  height: 22px;
+  width: 28px;
+  height: 28px;
   background: transparent;
   border: 0;
   border-radius: 6px;
@@ -70,8 +67,9 @@
   cursor: pointer;
   opacity: 0;
   transition: opacity 120ms ease, background 120ms ease, color 120ms ease;
+  align-self: center;
 }
-.session-row:hover .session-del { opacity: 0.6; }
+.session-row:hover .session-del { opacity: 0.55; }
 .session-del:hover {
   background: var(--ds-surface-soft);
   color: var(--ds-danger);
@@ -178,7 +176,6 @@
   align-items: flex-end;
   gap: 6px;
   white-space: nowrap;
-  padding-right: 34px;
 }
 
 .session-pushcount {

package/dist/client/index.js

@@ -179,8 +179,10 @@
     when.textContent = relTime(session.lastActivity);
     right.appendChild(when);
 
-    // Hover-revealed delete — placed inside the right column so it sits
-    // above the count text in the reserved 22px slot.
+    a.appendChild(right);
+
+    // Hover-revealed delete — sits in its own grid column to the right of
+    // the count/when stack so it never overlaps the text on short rows.
     const del = document.createElement("button");
     del.className = "session-del";
     del.type = "button";
@@ -197,9 +199,7 @@
       });
       load();
     });
-    right.appendChild(del);
-
-    a.appendChild(right);
+    a.appendChild(del);
 
     return a;
   }

package/dist/mcp.js

@@ -79,13 +79,46 @@ async function pushToServer(args) {
     }
     return (await r.json());
 }
-async function main() {
+export async function main() {
     const server = new Server({ name: "easel", version: "0.1.0" }, { capabilities: { tools: {} } });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools: [
             {
                 name: TOOL_PUSH,
-                description: "Push an HTML card to this session's live browser tab (easel). Every card appends to a single scrolling page that the user keeps open in split-screen. Use proactively (per global Rule 33) for wordy explanations, mockups, diagrams, diffs, ≥3-option comparisons, or progress views — do NOT ask permission. Pass full HTML (not Markdown).",
+                description: "Push an HTML card to this session's live browser tab. Renders in a sandboxed iframe over a host-controlled canvas that can be LIGHT or DARK depending on the user's OS theme. Treat each card as a presentation slide — generous whitespace, presentation-scale type, tangible visuals. Your HTML MUST adapt to both light and dark modes.\n\n" +
+                    "═══ ADAPTIVE COLOR (gets wrong most often) ═══\n" +
+                    "• Do NOT set `background` on `body` or your root wrapper. The host paints the canvas — setting bg fights it and creates a wrong-shade block in the opposite mode.\n" +
+                    "• Use `light-dark()` for ALL text colors, card backgrounds, borders, and decorative shades. Add `:root { color-scheme: light dark; }` so the function resolves. Hardcoded `color: #475569` goes invisible in dark mode; hardcoded `border: 1px solid #e5e5e5` becomes a hard white line.\n" +
+                    "• After setting `.wrap { color: light-dark(...); }`, re-scope `color: inherit` to every descendant so child elements don't fall back to the host's default.\n" +
+                    "• Inverse rule: if you DO paint a fixed background on a container (a code block locked to dark, a brand-color hero), you MUST also set its text color AND re-scope `color: inherit` to its children. Background and text are a pair.\n\n" +
+                    "═══ COPY-PASTE STARTER ═══\n" +
+                    "  :root { color-scheme: light dark; }\n" +
+                    "  .wrap { color: light-dark(#111, #e8e8e8); padding: 56px 48px; font-family: -apple-system, 'Inter', system-ui, sans-serif; max-width: 820px; }\n" +
+                    "  .wrap *, .wrap h1, .wrap h2, .wrap h3, .wrap p, .wrap li, .wrap span { color: inherit; }\n" +
+                    "  .card { background: light-dark(#fff, #161616); border: 1px solid light-dark(#e0d9c3, #2a2a2a); border-radius: 12px; padding: 24px; }\n\n" +
+                    "═══ TYPOGRAPHY (presentation scale, NOT dashboard) ═══\n" +
+                    "• Hero title: 44–52px, weight 500, letter-spacing -0.025em\n" +
+                    "• Section titles: 28–36px, weight 500\n" +
+                    "• Body: 18–22px, line-height 1.55+\n" +
+                    "• Eyebrow / kicker: 13–14px uppercase, letter-spacing 0.14em+, colored as a muted accent\n" +
+                    "• Inter or system sans-serif. Never go below 13px for readable content.\n\n" +
+                    "═══ WHITESPACE ═══\n" +
+                    "• Page padding: 56–80px vertical, 40–56px horizontal\n" +
+                    "• Card padding: 24–32px\n" +
+                    "• Between major sections: 56–96px\n\n" +
+                    "═══ VISUALS — tangible beats abstract ═══\n" +
+                    "The test: 'Could a bullet list communicate this just as well?' If yes, the visual is decoration not explanation — rebuild it as something tangible.\n" +
+                    "• YES: skeuomorphic browser chrome (3 traffic-light dots + URL bar), terminal windows with monospace + prompt, code-editor frames with line gutters, real device mockups, proportional timeline bars with phase markers, pipe-shaped funnels.\n" +
+                    "• NO: 5 labeled rectangles connected by arrows; abstract 'sequence diagrams' of thin lines with text labels; numbered-box explainers where each box is just a title + 1 sentence.\n\n" +
+                    "═══ 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" +
+                    "• 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" +
+                    "A response that would otherwise contain: >2 paragraphs of explanation, any UI mockup, a diagram, a code diff, a ≥3-option comparison, or a multi-step progress view. Do NOT ask permission — push proactively. After pushing, reply in chat with ONE LINE: 'pushed to easel ↗ — #<index>'. Don't restate the card's content.\n\n" +
+                    "═══ OTHER ═══\n" +
+                    "• Pass full HTML only — no Markdown. The iframe injects baseline typography so plain `<h1>/<p>` works without extra CSS, but for anything multi-section define your own `<style>` block.\n" +
+                    "• `<script>` tags trying to mutate the parent window are sandbox-blocked; in-iframe `<script>` (for animations, charts, interactivity) is fine.",
                 inputSchema,
             },
             {
@@ -229,7 +262,15 @@ async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }
-main().catch((err) => {
-    console.error("[easel mcp] fatal:", err);
-    process.exit(1);
-});
+// Auto-run only when invoked directly (e.g. `node dist/mcp.js`), not when
+// imported (e.g. by the CLI's no-arg / `mcp` subcommand path). The strict
+// equality is what guarantees this — anything fuzzier (like an endsWith
+// check) matches on import too and ends up running main() twice, which the
+// stdio transport then connects to the same stdin → every message
+// processed twice → every push duplicated. Don't add fallbacks here.
+if (import.meta.url === `file://${process.argv[1]}`) {
+    main().catch((err) => {
+        console.error("[easel mcp] fatal:", err);
+        process.exit(1);
+    });
+}

package/package.json

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