@ammduncan/easel 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to easel. This project adheres to [Semantic Versioning](https://semver.org/).
+
+## 0.2.1 — 2026-05-22
+
+### Added
+- `easel setup --client cursor|claude-desktop|windsurf` writes the MCP entry into each client's config file, merging into any existing `mcpServers` map. Sibling top-level keys are preserved. (`src/client-setup.ts`)
+- README leads with the npx install; per-client install commands documented; generic JSON snippet for any other MCP-speaking client.
+- This `CHANGELOG.md`.
+
+### Notes
+- The Claude Code setup path (bare `easel setup`) is unchanged.
+
+## 0.2.0 — 2026-05-22
+
+### Added
+- Published to npm as [`@ammduncan/easel`](https://www.npmjs.com/package/@ammduncan/easel). Any MCP client can now install with `npx -y @ammduncan/easel` — no clone, no build.
+- `EASEL_SESSION_ID` env var as the highest-priority override for session resolution.
+- Synthetic PPID-derived session id as a final fallback when no Claude Code hook fired and no transcript exists — gives Cursor, Claude Desktop, Windsurf, and any other MCP client a stable session per chat with zero setup beyond the MCP entry.
+- MCP-side auto-open: non-CC clients have no `SessionStart` hook to open the tab, so the MCP server now opens it on the first tool call when no hook file exists for this PPID. One-shot guard avoids re-opening if the user closes the tab. Claude Code behaviour unchanged.
+- `LICENCE` file (MIT).
+
+### Changed
+- `resolveClaudeSessionId()` is now total — always returns a string. Dead "no session id" error branches removed from `cli.ts` and `mcp.ts`.
+- `package.json` reshaped for npm publishing: scoped name `@ammduncan/easel`, MIT licence, repo/homepage/bugs URLs, keywords for discovery, `engines.node >=20`, `files` whitelist (only bin/dist/scripts/skills/README/LICENCE in the tarball), `prepublishOnly` script, `publishConfig.access=public`.
+- Package size: 47 kB tarball, 165 kB unpacked, 3 runtime deps.
+
+## 0.1.0 — internal baseline
+
+The pre-publish baseline. Highlights from the unreleased history:
+
+- Renamed project from `claude-display` to `easel`; data root migrated from `~/.claude-display` to `~/.easel` with one-shot `mv` on first start. Browser localStorage keys (`claude-display:*`) and postMessage events migrated to the `easel:*` namespace with a browser-side migration shim. Internal `__CLAUDE_DISPLAY__` window global renamed to `__EASEL__`. Env vars renamed (`CLAUDE_DISPLAY_PORT` → `EASEL_PORT` with legacy fallback).
+- Dropped `jq` as a runtime dependency. Ported `scripts/easel-session-id.sh` to `scripts/easel-session-id.mjs` (Node stdlib only).
+- Added `easel restart` command.
+- MCP tool names finalised as `push`, `open`, `config`, `label` (invoked as `mcp__easel__*`).
+- Skill folder canonicalised at `skills/using-easel/`.

package/README.md

@@ -1,37 +1,68 @@
 # easel
 
-A live browser tab for every Claude Code session. Agents push HTML — explanations, mockups, diagrams, diffs, comparisons — to a scrolling feed you keep open in split-screen. No more wall-of-text in the terminal.
+A live browser tab for every AI coding session. Agents push HTML — explanations, mockups, diagrams, diffs, comparisons — to a scrolling feed you keep open in split-screen. No more wall-of-text in the terminal.
 
 ```
-┌──────────── Claude Code (left) ────────────┐    ┌────── easel (right) ──────────────┐
+┌──────────── agent (left) ──────────────────┐    ┌────── easel (right) ──────────────┐
 │                                            │    │  s/<session-id>  •  3 pushes • live│
 │  > walk me through the new auth flow       │    │  ───────────────────────────────── │
 │                                            │    │  #1  Auth flow overview            │
-│  pushed to display ↗ — #1                  │    │  ┌────────────────────────────────┐│
+│  pushed to easel ↗ — #1                    │    │  ┌────────────────────────────────┐│
 │                                            │    │  │  Three actors talk to each…    ││
 │  > what could break?                       │    │  └────────────────────────────────┘│
 │                                            │    │                                    │
-│  pushed to display ↗ — #2                  │    │  #2  Failure modes                 │
+│  pushed to easel ↗ — #2                    │    │  #2  Failure modes                 │
 └────────────────────────────────────────────┘    └────────────────────────────────────┘
 ```
 
+Works with **Claude Code**, **Cursor**, **Claude Desktop**, **Windsurf**, and any other MCP-speaking client.
+
 ## Why
 
-Long markdown explanations bury what the agent is actually doing. Visual content (mockups, comparisons, diagrams) is even worse in a TTY. `easel` gives each chat session its own browser tab, and a single MCP tool — `push` — that the agent uses proactively. The terminal stays as a conversation log; the browser carries the substance.
+Long markdown explanations bury what the agent is actually doing. Visual content (mockups, comparisons, diagrams) is even worse in a TTY. easel gives each chat session its own browser tab, and a single MCP tool — `push` — that the agent uses proactively. The terminal stays as a conversation log; the browser carries the substance.
 
 ## Install
 
-Requires Node 20+, `git`, and Claude Code.
+Requires Node 20+.
+
+### Claude Code
+
+```bash
+npx -y @ammduncan/easel setup
+```
+
+That registers the MCP at user scope, installs the `using-easel` skill so the agent knows when to push, and adds the `SessionStart` hooks that resolve session IDs and auto-open the tab. Restart Claude Code and you're done.
+
+### Cursor / Claude Desktop / Windsurf
+
+One command per client:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/AmmDuncan/easel/main/scripts/install.sh | bash
+npx -y @ammduncan/easel setup --client cursor
+npx -y @ammduncan/easel setup --client claude-desktop
+npx -y @ammduncan/easel setup --client windsurf
 ```
 
-The installer clones to `~/.local/share/easel` (override with `EASEL_DIR=…`), runs `npm install && npm run build`, then registers the MCP at user scope and adds two `SessionStart` hooks (session-id capture + auto-open tab). Idempotent — safe to re-run to update.
+Each writes the MCP entry to the client's config file (`~/.cursor/mcp.json`, `~/Library/Application Support/Claude/claude_desktop_config.json`, or `~/.codeium/windsurf/mcp_config.json`). Restart the client to load it.
 
-Restart Claude Code afterwards.
+### Any other MCP client
 
-### Manual install
+Drop this snippet into your client's MCP config:
+
+```json
+{
+  "mcpServers": {
+    "easel": {
+      "command": "npx",
+      "args": ["-y", "@ammduncan/easel"]
+    }
+  }
+}
+```
+
+The MCP child mints its own session from its parent process ID — no hook required. Set `EASEL_SESSION_ID` in the client's `env` block if you want to pin a specific session.
+
+### From source (for contributors)
 
 ```bash
 git clone https://github.com/AmmDuncan/easel.git ~/work/tools/easel
@@ -56,20 +87,20 @@ Agents invoke them as `mcp__easel__push`, `mcp__easel__open`, etc.
 - **Presets**: `paper` (warm pitstop-style, amber accent — default), `aurora` (deep canvas + violet glow halos), `slate` (cool neutral, cyan accent)
 - **Themes**: light / dark, with sun-moon toggle in the topbar
 - **Density**: `carded` (bordered cards) or `flat` (no chrome, whitespace separates pushes)
-- Three swatches + density toggle live in the topbar; config persists in `~/.easel/config.json` and SSE-broadcasts across all open tabs
+- Three swatches + density toggle live in the topbar; config persists in `~/.easel/config.json` and SSE-broadcasts across all open tabs.
 
 ## Sessions
 
-- Each Claude Code session gets its own URL: `localhost:7878/s/<session-id>`
-- Session IDs come from Claude Code itself (via the pitstop-style SessionStart hook)
-- Sessions auto-rename to `cwd-basename` by default; you can rename them via the click-to-edit label in the topbar, or the agent can via the `label` tool
-- Idle sessions (>24h since last push) are GC'd every 10 minutes
-- Up to 50 pushes per session; oldest evicted from disk first
-- Per-push delete (trash icon on each card) + per-session delete (hover any row in the switcher or index)
+- Each chat session gets its own URL: `localhost:7878/s/<session-id>`
+- Session IDs come from the agent client. Claude Code provides them via a SessionStart hook; other MCP clients fall through to a stable PPID-derived id for the MCP child. Override either via the `EASEL_SESSION_ID` env var.
+- Sessions auto-rename to `cwd-basename` by default; you can rename them via the click-to-edit label in the topbar, or the agent can via the `label` tool.
+- Idle sessions (>24h since last push) are GC'd every 10 minutes.
+- Up to 50 pushes per session; oldest evicted from disk first.
+- Per-push delete (trash icon on each card) + per-session delete (hover any row in the switcher or index).
 
 ## Tool surface
 
-The MCP exposes one server (`display`) with four tools. HTML is rendered in a sandboxed iframe (`sandbox="allow-scripts"`) with a baseline design system injected — off-white / charcoal, Inter, presentation-scale typography — so plain `<h1>/<h2>/<p>` markup looks right without extra CSS. Authors can also write a full `<!DOCTYPE html>` document and take ownership of styling.
+The MCP exposes one server (`easel`) with four tools. HTML is rendered in a sandboxed iframe (`sandbox="allow-scripts"`) with a baseline design system injected — off-white / charcoal, Inter, presentation-scale typography — so plain `<h1>/<h2>/<p>` markup looks right without extra CSS. Authors can also write a full `<!DOCTYPE html>` document and take ownership of styling.
 
 Inside pushed HTML, semantic chips are available out of the box:
 
@@ -84,6 +115,20 @@ Inside pushed HTML, semantic chips are available out of the box:
 
 Each is themed for both light and dark with a soft outer glow.
 
+## CLI
+
+```
+easel open                     ensure server is running, open this session's tab
+easel url                      print this session's URL
+easel config                   print / set { preset, theme, density }
+easel setup                    Claude Code: hooks + MCP + skill
+easel setup --client <name>    register the MCP in another client (cursor, claude-desktop, windsurf)
+easel restart                  kill + respawn the HTTP server (handy after a build)
+easel update                   git pull + build + setup (clone installs only)
+easel server                   run the HTTP server in the foreground (debug)
+easel version
+```
+
 ## Files
 
 ```
@@ -93,10 +138,11 @@ src/
   http-entry.ts       process entry for the HTTP server
   server-manager.ts   lockfile + spawn coordination
   session-store.ts    disk persistence + retention sweep
-  session-id.ts       3-tier resolver (env / hook file / transcript scan)
+  session-id.ts       5-tier resolver (env / hook file / transcript scan / synthetic PPID)
   config-store.ts     preset / theme / density persistence
-  paths.ts            shared constants
-  cli.ts              `easel open|url|setup|config|server|version`
+  client-setup.ts     per-client config writers (cursor, claude-desktop, windsurf)
+  paths.ts            shared constants + legacy-dir migration
+  cli.ts              `easel open|url|setup|config|server|restart|update|version`
   client/
     viewer.html       single-session feed
     index.html        sessions index page
@@ -106,7 +152,7 @@ src/
     index.js          index page client
 scripts/
   easel-session-id.mjs  SessionStart hook (Node, zero deps)
-  install.sh            one-shot installer
+  install.sh            one-shot installer (clone installs)
   copy-client.mjs       build-time copy of client assets
 bin/
   easel                 shebang → dist/cli.js

package/dist/cli.js

@@ -8,6 +8,7 @@ import { ensureHttpServer, readLock } from "./server-manager.js";
 import { resolveClaudeSessionId } from "./session-id.js";
 import { HOOK_DIR, DATA_ROOT } from "./paths.js";
 import { registerSession } from "./session-store.js";
+import { listClients, setupClient, } from "./client-setup.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PROJECT_ROOT = resolve(__dirname, "..");
 function help() {
@@ -22,7 +23,10 @@ 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 SessionStart hook + register MCP in ~/.claude/settings.json
+  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 update          git pull + npm install + build + setup (re-runs setup to apply new conventions)
   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)
@@ -330,9 +334,32 @@ async function main() {
         case "url":
             await cmdUrl();
             return;
-        case "setup":
+        case "setup": {
+            const clientIdx = rest.indexOf("--client");
+            if (clientIdx !== -1) {
+                const name = rest[clientIdx + 1];
+                if (!name) {
+                    console.error(`[easel] --client requires a name. Available: ${listClients().join(", ")}`);
+                    process.exitCode = 1;
+                    return;
+                }
+                if (!listClients().includes(name)) {
+                    console.error(`[easel] unknown client "${name}". Available: ${listClients().join(", ")}`);
+                    process.exitCode = 1;
+                    return;
+                }
+                try {
+                    setupClient(name);
+                }
+                catch (err) {
+                    console.error(`[easel] setup --client ${name} failed:`, err.message);
+                    process.exitCode = 1;
+                }
+                return;
+            }
             cmdSetup();
             return;
+        }
         case "server":
             await cmdServer();
             return;

package/dist/client-setup.js

@@ -0,0 +1,73 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir, platform } from "node:os";
+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");
+        },
+        postSetup: "Quit and relaunch Claude Desktop to load the MCP server.",
+    },
+    cursor: {
+        name: "cursor",
+        label: "Cursor",
+        configPath: () => 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"),
+        postSetup: "Restart Windsurf to load the MCP server.",
+    },
+};
+export function listClients() {
+    return Object.keys(CLIENTS);
+}
+export function setupClient(name) {
+    const spec = CLIENTS[name];
+    if (!spec) {
+        throw new Error(`unknown client: ${name}`);
+    }
+    const configPath = spec.configPath();
+    const config = readJson(configPath);
+    const mcpServers = config.mcpServers ?? {};
+    mcpServers.easel = {
+        command: "npx",
+        args: ["-y", "@ammduncan/easel"],
+    };
+    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}`);
+}
+function readJson(path) {
+    if (!existsSync(path))
+        return {};
+    try {
+        const text = readFileSync(path, "utf-8").trim();
+        if (!text)
+            return {};
+        const parsed = JSON.parse(text);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return parsed;
+        }
+        return {};
+    }
+    catch (err) {
+        throw new Error(`couldn't parse existing config at ${path}: ${err.message}`);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ammduncan/easel",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "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",
@@ -36,6 +36,7 @@
     "scripts/easel-session-id.mjs",
     "skills/",
     "README.md",
+    "CHANGELOG.md",
     "LICENCE"
   ],
   "scripts": {