@ammduncan/easel 0.2.2 → 0.2.5

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 All notable changes to easel. This project adheres to [Semantic Versioning](https://semver.org/).
 
+## 0.2.5 — 2026-05-22
+
+### Added
+- **Codex client support: `easel setup --client codex`.** Writes the MCP entry into `~/.codex/config.toml` under `[mcp_servers.easel]` and copies the `using-easel` skill into `~/.codex/skills/using-easel/SKILL.md` so Codex agents have the full style guide in addition to the tool description. Line-based TOML upsert preserves other sections and comments.
+
+### Fixed
+- **`easel setup --help` no longer silently runs the destructive Claude Code setup.** Previously, the `--help` flag fell through the `--client` check and reached `cmdSetup()`, which writes to `~/.claude/settings.json`. Now a dedicated help branch fires before any side effects. Includes a manual-install JSON snippet for clients beyond the four officially supported ones.
+
+## 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

package/dist/cli.js

@@ -23,10 +23,11 @@ Usage:
   easel config preset paper       set preset to paper | aurora | slate
   easel config theme dark         set theme to light | dark
   easel config preset aurora theme light   set both at once
-  easel setup                    install Claude Code hook + register MCP in ~/.claude/settings.json
-  easel setup --client cursor    register the MCP in Cursor's config
-  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 setup                              install Claude Code hook + register MCP in ~/.claude/settings.json
+  easel setup --client cursor              register MCP in ~/.cursor/mcp.json
+  easel setup --client claude-desktop      register MCP in ~/Library/Application Support/Claude/claude_desktop_config.json
+  easel setup --client windsurf            register MCP in ~/.codeium/windsurf/mcp_config.json
+  easel setup --client codex               register MCP in ~/.codex/config.toml + copy skill to ~/.codex/skills/
   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)
@@ -336,6 +337,24 @@ async function main() {
             await cmdUrl();
             return;
         case "setup": {
+            // Catch --help BEFORE doing anything destructive. The default
+            // cmdSetup() writes to ~/.claude/settings.json, so an unguarded
+            // `easel setup --help` would silently reconfigure Claude Code.
+            if (rest.includes("--help") || rest.includes("-h") || rest[0] === "help") {
+                console.log([
+                    "easel setup — install easel into one of the supported MCP clients.",
+                    "",
+                    "Usage:",
+                    "  easel setup                    Claude Code (default): MCP + SessionStart hook + skill",
+                    "  easel setup --client <name>    register MCP in another client",
+                    "",
+                    `Available clients: ${listClients().join(", ")}`,
+                    "",
+                    "Manual install (any other MCP client): drop this into the client's MCP config —",
+                    '  { "mcpServers": { "easel": { "command": "npx", "args": ["-y", "@ammduncan/easel"] } } }',
+                ].join("\n"));
+                return;
+            }
             const clientIdx = rest.indexOf("--client");
             if (clientIdx !== -1) {
                 const name = rest[clientIdx + 1];

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/client-setup.js

@@ -1,36 +1,39 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import { homedir, platform } from "node:os";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = resolve(__dirname, "..");
 const CLIENTS = {
     "claude-desktop": {
         name: "claude-desktop",
         label: "Claude Desktop",
-        configPath: () => {
-            const home = homedir();
-            if (platform() === "darwin") {
-                return join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
-            }
-            if (platform() === "win32") {
-                const appData = process.env.APPDATA ?? join(home, "AppData", "Roaming");
-                return join(appData, "Claude", "claude_desktop_config.json");
-            }
-            return join(home, ".config", "Claude", "claude_desktop_config.json");
-        },
+        run: () => upsertJsonMcpServer(claudeDesktopConfigPath()),
         postSetup: "Quit and relaunch Claude Desktop to load the MCP server.",
     },
     cursor: {
         name: "cursor",
         label: "Cursor",
-        configPath: () => join(homedir(), ".cursor", "mcp.json"),
+        run: () => upsertJsonMcpServer(join(homedir(), ".cursor", "mcp.json")),
         postSetup: "Open Cursor and toggle MCP servers in Settings → Features → MCP, " +
             "or restart Cursor for the registration to take effect.",
     },
     windsurf: {
         name: "windsurf",
         label: "Windsurf",
-        configPath: () => join(homedir(), ".codeium", "windsurf", "mcp_config.json"),
+        run: () => upsertJsonMcpServer(join(homedir(), ".codeium", "windsurf", "mcp_config.json")),
         postSetup: "Restart Windsurf to load the MCP server.",
     },
+    codex: {
+        name: "codex",
+        label: "Codex",
+        run: () => {
+            upsertTomlMcpServer(join(homedir(), ".codex", "config.toml"));
+            installEaselSkillTo(join(homedir(), ".codex", "skills", "using-easel"));
+        },
+        postSetup: "Restart Codex to load the MCP server. The using-easel skill has " +
+            "been copied to ~/.codex/skills/ so Codex will know when to push.",
+    },
 };
 export function listClients() {
     return Object.keys(CLIENTS);
@@ -40,7 +43,17 @@ export function setupClient(name) {
     if (!spec) {
         throw new Error(`unknown client: ${name}`);
     }
-    const configPath = spec.configPath();
+    spec.run();
+    console.log(`[easel] ${spec.label} configured`);
+    console.log(`  - ${spec.postSetup}`);
+}
+/**
+ * Installs the easel MCP entry into a JSON config file with the standard
+ * `mcpServers: { name: { command, args } }` shape — used by Claude Desktop,
+ * Cursor, Windsurf, and friends. Merges into any existing config; preserves
+ * sibling top-level keys and other registered MCP servers.
+ */
+function upsertJsonMcpServer(configPath) {
     const config = readJson(configPath);
     const mcpServers = config.mcpServers ?? {};
     mcpServers.easel = {
@@ -50,9 +63,74 @@ export function setupClient(name) {
     config.mcpServers = mcpServers;
     mkdirSync(dirname(configPath), { recursive: true });
     writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`);
-    console.log(`[easel] ${spec.label} configured`);
     console.log(`  - wrote ${configPath}`);
-    console.log(`  - ${spec.postSetup}`);
+}
+/**
+ * Installs the easel MCP entry into a TOML config file under the
+ * `[mcp_servers.easel]` section — used by Codex. Line-based upsert: replaces
+ * the existing `[mcp_servers.easel]` block in place if it's there, otherwise
+ * appends. Other sections and comments preserved.
+ */
+function upsertTomlMcpServer(configPath) {
+    const newSection = "[mcp_servers.easel]\n" +
+        'command = "npx"\n' +
+        'args = ["-y", "@ammduncan/easel"]\n';
+    const existing = existsSync(configPath) ? readFileSync(configPath, "utf-8") : "";
+    const updated = upsertTomlSection(existing, "mcp_servers.easel", newSection);
+    mkdirSync(dirname(configPath), { recursive: true });
+    writeFileSync(configPath, updated);
+    console.log(`  - wrote ${configPath}`);
+}
+/**
+ * Line-based TOML section upsert. Replaces an existing `[<header>]` block
+ * (defined as the lines from the header up to the next top-level `[...]`
+ * header or EOF) with `newBlock`; appends if no such block exists. Other
+ * sections are left untouched. Adequate for our narrow use case — not a
+ * general-purpose TOML editor.
+ */
+function upsertTomlSection(content, header, newBlock) {
+    const targetHeader = `[${header}]`;
+    const lines = content.split("\n");
+    let startIdx = -1;
+    let endIdx = lines.length;
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].trim() === targetHeader) {
+            startIdx = i;
+            for (let j = i + 1; j < lines.length; j++) {
+                const stripped = lines[j].trim();
+                if (/^\[[^\]]+\]$/.test(stripped)) {
+                    endIdx = j;
+                    break;
+                }
+            }
+            break;
+        }
+    }
+    const newBlockLines = newBlock.replace(/\n+$/, "").split("\n");
+    if (startIdx === -1) {
+        const trailing = content.length === 0 || content.endsWith("\n") ? "" : "\n";
+        const spacer = content.length === 0 ? "" : "\n";
+        return content + trailing + spacer + newBlockLines.join("\n") + "\n";
+    }
+    const before = lines.slice(0, startIdx);
+    const after = lines.slice(endIdx);
+    const trailingBlank = after.length > 0 && after[0] !== "" ? [""] : [];
+    return [...before, ...newBlockLines, ...trailingBlank, ...after].join("\n");
+}
+/**
+ * Copies the bundled `using-easel/SKILL.md` into a target skills directory.
+ * Used by clients that have a skill-discovery mechanism (Claude Code,
+ * Codex).
+ */
+export function installEaselSkillTo(destDir) {
+    const src = resolve(PROJECT_ROOT, "skills", "using-easel", "SKILL.md");
+    if (!existsSync(src)) {
+        console.warn(`  - skipped skill install: source missing at ${src}`);
+        return;
+    }
+    mkdirSync(destDir, { recursive: true });
+    copyFileSync(src, join(destDir, "SKILL.md"));
+    console.log(`  - installed using-easel skill into ${destDir}`);
 }
 function readJson(path) {
     if (!existsSync(path))
@@ -71,3 +149,14 @@ function readJson(path) {
         throw new Error(`couldn't parse existing config at ${path}: ${err.message}`);
     }
 }
+function claudeDesktopConfigPath() {
+    const home = homedir();
+    if (platform() === "darwin") {
+        return join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
+    }
+    if (platform() === "win32") {
+        const appData = process.env.APPDATA ?? join(home, "AppData", "Roaming");
+        return join(appData, "Claude", "claude_desktop_config.json");
+    }
+    return join(home, ".config", "Claude", "claude_desktop_config.json");
+}

package/dist/mcp.js

@@ -85,7 +85,40 @@ export async function main() {
         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,10 +262,13 @@ export async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }
-// Auto-run when invoked directly (e.g. `node dist/mcp.js`), not when imported.
-const invokedDirectly = import.meta.url === `file://${process.argv[1]}` ||
-    import.meta.url.endsWith("/dist/mcp.js");
-if (invokedDirectly) {
+// 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.2",
+  "version": "0.2.5",
   "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",