@ammduncan/easel 0.2.12 → 0.2.14

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to easel. This project adheres to [Semantic Versioning](https://semver.org/).
 
+## 0.2.14 — 2026-05-23
+
+### Changed
+- **First-push auto-open is now actually the only trigger.** 0.2.10 moved the MCP-side auto-open from "first tool call" to "first push when no tab is alive". But Claude Code launches were still opening a tab because `easel setup` also installed a `SessionStart` hook that ran `easel open --quiet`. Two changes:
+  - `easel setup` no longer installs the `easel open --quiet` SessionStart block, and actively strips any pre-existing one from `~/.claude/settings.json`. The `idCaptureBlock` (which writes the per-PPID session-id file) stays — it's needed for PPID → session correlation and has no UI side effect.
+  - `mcp.ts` `autoOpenIfNeeded` drops the `hookHasFiredForThisPpid()` short-circuit. That check was a proxy for "the hook already opened a tab"; now that the hook doesn't open tabs, `sessionTabs > 0` is the truthful signal.
+- After upgrading, run `easel update` once so setup re-runs and cleans your existing `~/.claude/settings.json`.
+
+## 0.2.13 — 2026-05-23
+
+### Added
+- **`kind: "mockup"` and `kind: "app"` switch the iframe into app-fidelity mode.** The wrapper skips its presentation defaults (Inter body font, design-token CSS, semantic chips, body bg/color, prose width constraints) and only keeps the box-sizing reset and the html-to-image bridge. Agent paints everything. Makes the existing "App/UI recreations are always locked-mode" rule structural — for a true mockup, opt in via `kind` and the wrapper stops fighting you instead of relying on the agent remembering to override every default. Presentation pushes (explanations, comparisons, status reports) keep the existing wrapper as before.
+
 ## 0.2.12 — 2026-05-23
 
 ### Docs

package/dist/cli.js

@@ -124,7 +124,8 @@ function cmdSetup() {
     const hooks = settings.hooks ?? {};
     let sessionStart = hooks.SessionStart ?? [];
     // Drop legacy entries from prior versions (the old bash hook, paths under the
-    // claude-display name) before re-adding the current Node-based hook.
+    // claude-display name) AND the prior autoOpenBlock (which opened a tab at
+    // SessionStart — replaced by MCP-side auto-open on first push as of 0.2.14).
     const isLegacy = (block) => {
         const inner = block?.hooks ?? [block];
         if (!Array.isArray(inner))
@@ -135,16 +136,16 @@ function cmdSetup() {
                 return false;
             return (cmd.includes("claude-display-session-id.sh") ||
                 cmd.includes("easel-session-id.sh") ||
-                cmd.includes("bin/claude-display "));
+                cmd.includes("bin/claude-display ") ||
+                // Prior `easel open --quiet` SessionStart hook — superseded by
+                // MCP-side first-push auto-open.
+                (cmd.includes("easel") && cmd.includes("open --quiet")));
         });
     };
     sessionStart = sessionStart.filter((b) => !isLegacy(b));
     const idCaptureBlock = {
         hooks: [{ type: "command", command: `node ${hookScript}` }],
     };
-    const autoOpenBlock = {
-        hooks: [{ type: "command", command: `${cliEntry} open --quiet` }],
-    };
     const containsBlockMatching = (substr) => sessionStart.some((block) => {
         const inner = block?.hooks ?? [block];
         return (Array.isArray(inner) ? inner : []).some((h) => typeof h === "object" &&
@@ -155,9 +156,6 @@ function cmdSetup() {
     if (!containsBlockMatching("easel-session-id.mjs")) {
         sessionStart.push(idCaptureBlock);
     }
-    if (!containsBlockMatching("easel") || !containsBlockMatching("open --quiet")) {
-        sessionStart.push(autoOpenBlock);
-    }
     hooks.SessionStart = sessionStart;
     settings.hooks = hooks;
     mkdirSync(dirname(settingsPath), { recursive: true });

package/dist/client/viewer.js

@@ -585,7 +585,7 @@
     iframe.setAttribute("scrolling", "no");
     iframe.setAttribute("title", push.title || "push " + push.index);
     iframe.dataset.pushId = push.id;
-    iframe.srcdoc = wrapPushedHtml(push.html, currentTheme(), push.id);
+    iframe.srcdoc = wrapPushedHtml(push.html, currentTheme(), push.id, push.kind);
     iframe.addEventListener("load", () => {
       iframes.add(iframe);
       // Primary path: the iframe self-measures and posts back size via
@@ -607,7 +607,7 @@
        - write plain HTML (<h1>, <h2>, <p>, etc.) — gets styled for free, OR
        - write their own <style> and override anything.
      ============================================================ */
-  function wrapPushedHtml(html, theme, pushId) {
+  function wrapPushedHtml(html, theme, pushId, kind) {
     // Authors sometimes wrap payloads in <![CDATA[ ... ]]> (treating html
     // like CDATA-in-XML). Strip the XML-ism before doing anything else —
     // otherwise the iframe renders the CDATA tags as visible text.
@@ -620,7 +620,8 @@
     if (lower.startsWith("<!doctype") || lower.startsWith("<html")) {
       return injectBridge(cleaned, theme, preset, pushId);
     }
-    return buildDefaultWrapper(cleaned, theme, preset, pushId);
+    const isAppFidelity = kind === "mockup" || kind === "app";
+    return buildDefaultWrapper(cleaned, theme, preset, pushId, isAppFidelity);
   }
 
   function selfMeasureScript(pushId) {
@@ -631,8 +632,29 @@
     );
   }
 
-  function buildDefaultWrapper(body, theme, preset, pushId) {
+  function buildDefaultWrapper(body, theme, preset, pushId, appFidelity) {
     const density = currentDensity();
+    // app-fidelity mode: skip presentation defaults (presets, semantic chips,
+    // body font/bg/color, prose constraints). Agent paints everything. Only
+    // keeps box-sizing reset + the html-to-image bridge script.
+    if (appFidelity) {
+      return `<!DOCTYPE html>
+<html data-theme="${theme}" data-preset="${preset}" data-density="${density}" data-app-fidelity="true">
+<head>
+<meta charset="utf-8" />
+<base target="_blank" />
+<script src="https://cdn.jsdelivr.net/npm/html-to-image@1.11.13/dist/html-to-image.js"></script>
+<style>
+*, *::before, *::after { box-sizing: border-box; }
+html, body { margin: 0; padding: 0; }
+</style>
+</head>
+<body>
+${body}
+<script>${selfMeasureScript(pushId)}</script>
+</body>
+</html>`;
+    }
     return `<!DOCTYPE html>
 <html data-theme="${theme}" data-preset="${preset}" data-density="${density}">
 <head>

package/dist/mcp.js

@@ -3,11 +3,8 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
-import { join } from "node:path";
 import { ensureHttpServer } from "./server-manager.js";
 import { resolveClaudeSessionId } from "./session-id.js";
-import { HOOK_DIR } from "./paths.js";
 function openUrlInBrowser(url) {
     const platform = process.platform;
     const cmd = platform === "darwin" ? "open" : platform === "win32" ? "start" : "xdg-open";
@@ -24,14 +21,6 @@ const TOOL_PUSH = "push";
 const TOOL_OPEN = "open";
 const TOOL_CONFIG = "config";
 const TOOL_LABEL = "label";
-/**
- * True if a SessionStart hook (e.g. Claude Code's) has already written a
- * session-id file for this MCP child's PPID. Tells us a hook-aware client is
- * managing tab lifecycle, so the MCP server should NOT also auto-open.
- */
-function hookHasFiredForThisPpid() {
-    return existsSync(join(HOOK_DIR, `cc-session-${process.ppid}.txt`));
-}
 // One-shot guard: only auto-open once per MCP-child lifetime. If the user
 // closes the tab afterwards, subsequent pushes won't re-open it — the user
 // closing the tab is treated as an explicit dismissal we should respect.
@@ -43,10 +32,16 @@ let autoOpenAttempted = false;
  * - `otherTabs > 0`: easel is open, but on a different session. Don't surprise
  *   the user with another window — return "other-session" so the caller can
  *   tell the agent to ask whether to use the topbar switcher or open a new tab.
- * - both 0 + no hook-managed tab: auto-open one tab.
+ * - both 0: auto-open one tab.
  *
  * One-shot per MCP child lifetime. Closing the tab counts as dismissal;
  * subsequent pushes won't re-open.
+ *
+ * Note: until 0.2.13, this also short-circuited when the Claude Code
+ * SessionStart hook had fired (`hookHasFiredForThisPpid`), because the hook
+ * itself opened a tab. As of 0.2.14 `easel setup` no longer installs that
+ * hook, so the MCP-side decision is reactive to actual tab presence only —
+ * `sessionTabs` is the truthful signal.
  */
 function autoOpenIfNeeded(url, sessionTabs, otherTabs) {
     if (autoOpenAttempted)
@@ -60,11 +55,6 @@ function autoOpenIfNeeded(url, sessionTabs, otherTabs) {
         autoOpenAttempted = true;
         return { kind: "other-session" };
     }
-    if (hookHasFiredForThisPpid()) {
-        // Claude Code's SessionStart hook handled it (or tried to).
-        autoOpenAttempted = true;
-        return { kind: "noop" };
-    }
     autoOpenAttempted = true;
     openUrlInBrowser(url);
     return { kind: "opened" };
@@ -82,7 +72,7 @@ const inputSchema = {
         },
         kind: {
             type: "string",
-            description: "Freeform tag: mockup, diff, explanation, comparison, diagram, status, progress, etc.",
+            description: "Freeform tag: mockup, app, diff, explanation, comparison, diagram, status, progress, etc. SPECIAL: 'mockup' and 'app' switch the iframe into APP-FIDELITY mode — the wrapper skips its presentation defaults (Inter body font, design-token CSS, semantic chips, prose width constraints, body bg/color). Only the box-sizing reset and the html-to-image bridge stay. Use this when the push is a recreation of real UI (app screen, component instance, embedded preview) and you want full control over every pixel without the host theme leaking in. For presentation content (explanations, comparisons, status reports), omit kind or use a non-fidelity value.",
         },
     },
     required: ["html"],

package/package.json

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