@ammduncan/easel 0.2.0

package/dist/config-store.js

@@ -0,0 +1,36 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { DATA_ROOT } from "./paths.js";
+const CONFIG_PATH = join(DATA_ROOT, "config.json");
+const DEFAULT = { preset: "paper", theme: "dark", density: "carded" };
+const PRESETS = ["paper", "aurora", "slate"];
+const THEMES = ["light", "dark"];
+const DENSITIES = ["carded", "flat"];
+function coerce(raw) {
+    const c = (raw && typeof raw === "object" ? raw : {});
+    const preset = PRESETS.includes(c.preset) ? c.preset : DEFAULT.preset;
+    const theme = THEMES.includes(c.theme) ? c.theme : DEFAULT.theme;
+    const density = DENSITIES.includes(c.density)
+        ? c.density
+        : DEFAULT.density;
+    return { preset, theme, density };
+}
+export function readConfig() {
+    if (!existsSync(CONFIG_PATH))
+        return { ...DEFAULT };
+    try {
+        return coerce(JSON.parse(readFileSync(CONFIG_PATH, "utf-8")));
+    }
+    catch {
+        return { ...DEFAULT };
+    }
+}
+export function writeConfig(patch) {
+    const current = readConfig();
+    const next = coerce({ ...current, ...patch });
+    mkdirSync(dirname(CONFIG_PATH), { recursive: true });
+    writeFileSync(CONFIG_PATH, JSON.stringify(next, null, 2));
+    return next;
+}
+export const ALL_PRESETS = PRESETS;
+export const ALL_THEMES = THEMES;

package/dist/http-entry.js

@@ -0,0 +1,2 @@
+import { startHttpServer } from "./http-server.js";
+startHttpServer();

package/dist/http-server.js

@@ -0,0 +1,202 @@
+import express from "express";
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { appendPush, deletePush, deleteSession, getSessionView, listSessionSummaries, registerSession, sessionExists, sweepIdleSessions, touchSession, updateSessionMeta, } from "./session-store.js";
+import { readConfig, writeConfig } from "./config-store.js";
+import { clearLockIfMine, writeLock } from "./server-manager.js";
+import { resolvePort } from "./paths.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CLIENT_DIR = resolve(__dirname, "client");
+const clients = new Map();
+let nextClientId = 1;
+function broadcast(sessionId, event, payload) {
+    const data = `event: ${event}\ndata: ${JSON.stringify(payload)}\n\n`;
+    for (const c of clients.values()) {
+        if (c.sessionId === sessionId) {
+            try {
+                c.res.write(data);
+            }
+            catch {
+                /* client gone — cleanup on next disconnect */
+            }
+        }
+    }
+}
+function broadcastAll(event, payload) {
+    const data = `event: ${event}\ndata: ${JSON.stringify(payload)}\n\n`;
+    for (const c of clients.values()) {
+        try {
+            c.res.write(data);
+        }
+        catch {
+            /* swallow */
+        }
+    }
+}
+function renderViewerHtml(sessionId, port) {
+    const tpl = readFileSync(resolve(CLIENT_DIR, "viewer.html"), "utf-8");
+    return tpl
+        .replace(/__SESSION_ID__/g, sessionId)
+        .replace(/__PORT__/g, String(port));
+}
+function renderIndexHtml(port) {
+    const tpl = readFileSync(resolve(CLIENT_DIR, "index.html"), "utf-8");
+    return tpl.replace(/__PORT__/g, String(port));
+}
+export function startHttpServer() {
+    const port = resolvePort();
+    const app = express();
+    app.use(express.json({ limit: "8mb" }));
+    app.use("/static", express.static(CLIENT_DIR, {
+        fallthrough: false,
+        maxAge: "0",
+    }));
+    app.get("/health", (_req, res) => {
+        res.json({ ok: true, pid: process.pid, port });
+    });
+    app.get("/", (_req, res) => {
+        res.type("text/html").send(renderIndexHtml(port));
+    });
+    app.get("/api/presence", (_req, res) => {
+        res.json({ tabs: clients.size });
+    });
+    app.get("/api/sessions", (_req, res) => {
+        res.json({ sessions: listSessionSummaries() });
+    });
+    app.get("/api/config", (_req, res) => {
+        res.json({ config: readConfig() });
+    });
+    app.post("/api/config", (req, res) => {
+        const { preset, theme, density } = req.body ?? {};
+        const patch = {};
+        if (typeof preset === "string")
+            patch.preset = preset;
+        if (typeof theme === "string")
+            patch.theme = theme;
+        if (typeof density === "string")
+            patch.density = density;
+        const next = writeConfig(patch);
+        broadcastAll("config", next);
+        res.json({ config: next });
+    });
+    app.post("/api/register", (req, res) => {
+        const { sessionId, cwd, label } = req.body ?? {};
+        if (typeof sessionId !== "string" || !sessionId.trim()) {
+            res.status(400).json({ error: "sessionId required" });
+            return;
+        }
+        registerSession(sessionId);
+        const patch = {};
+        if (typeof cwd === "string")
+            patch.cwd = cwd;
+        if (typeof label === "string")
+            patch.label = label;
+        const meta = Object.keys(patch).length
+            ? updateSessionMeta(sessionId, patch)
+            : getSessionView(sessionId).meta;
+        res.json({ ok: true, meta });
+    });
+    app.get("/s/:id", (req, res) => {
+        const id = String(req.params.id);
+        registerSession(id);
+        res.type("text/html").send(renderViewerHtml(id, port));
+    });
+    app.get("/s/:id/state", (req, res) => {
+        const id = String(req.params.id);
+        if (!sessionExists(id)) {
+            registerSession(id);
+        }
+        res.json(getSessionView(id));
+    });
+    app.get("/s/:id/events", (req, res) => {
+        const id = String(req.params.id);
+        res.set({
+            "Content-Type": "text/event-stream",
+            "Cache-Control": "no-cache, no-transform",
+            Connection: "keep-alive",
+            "X-Accel-Buffering": "no",
+        });
+        res.flushHeaders();
+        res.write(`event: hello\ndata: ${JSON.stringify({ sessionId: id, config: readConfig() })}\n\n`);
+        const client = { id: nextClientId++, sessionId: id, res };
+        clients.set(client.id, client);
+        const ka = setInterval(() => {
+            try {
+                res.write(`: keep-alive ${Date.now()}\n\n`);
+            }
+            catch {
+                /* ignore */
+            }
+        }, 25_000);
+        req.on("close", () => {
+            clearInterval(ka);
+            clients.delete(client.id);
+        });
+    });
+    app.delete("/api/sessions/:id/pushes/:pushId", (req, res) => {
+        const id = String(req.params.id);
+        const pushId = String(req.params.pushId);
+        const ok = deletePush(id, pushId);
+        if (ok)
+            broadcast(id, "remove", { pushId });
+        res.json({ ok });
+    });
+    app.delete("/api/sessions/:id", (req, res) => {
+        const id = String(req.params.id);
+        const ok = deleteSession(id);
+        res.json({ ok });
+    });
+    app.post("/api/push", (req, res) => {
+        const { sessionId, html, title, kind } = req.body ?? {};
+        if (typeof sessionId !== "string" || !sessionId.trim()) {
+            res.status(400).json({ error: "sessionId required" });
+            return;
+        }
+        if (typeof html !== "string" || !html.length) {
+            res.status(400).json({ error: "html required" });
+            return;
+        }
+        const push = appendPush(sessionId, { html, title, kind });
+        touchSession(sessionId);
+        broadcast(sessionId, "push", push);
+        if (Math.random() < 0.05) {
+            sweepIdleSessions();
+        }
+        let sessionTabs = 0;
+        for (const c of clients.values()) {
+            if (c.sessionId === sessionId)
+                sessionTabs++;
+        }
+        res.json({
+            url: `http://localhost:${port}/s/${sessionId}`,
+            slide_id: push.id,
+            index: push.index,
+            sessionTabs,
+        });
+    });
+    const server = app.listen(port, "127.0.0.1", () => {
+        writeLock(port);
+        sweepIdleSessions();
+    });
+    // Periodic GC of idle sessions every 10 minutes (in addition to the
+    // probabilistic sweep on each push). Without this, low-traffic servers
+    // can hoard sessions long past the 24h TTL.
+    const sweepTimer = setInterval(() => {
+        try {
+            sweepIdleSessions();
+        }
+        catch {
+            /* swallow */
+        }
+    }, 10 * 60 * 1000);
+    sweepTimer.unref();
+    const shutdown = () => {
+        clearLockIfMine();
+        server.close(() => process.exit(0));
+        setTimeout(() => process.exit(0), 1500).unref();
+    };
+    process.on("SIGTERM", shutdown);
+    process.on("SIGINT", shutdown);
+    process.on("exit", clearLockIfMine);
+}

package/dist/mcp.js

@@ -0,0 +1,235 @@
+#!/usr/bin/env node
+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";
+    const args = platform === "win32" ? ["", url] : [url];
+    try {
+        const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+        child.unref();
+    }
+    catch {
+        /* swallow */
+    }
+}
+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.
+let autoOpenAttempted = false;
+function maybeAutoOpenTab(url) {
+    if (autoOpenAttempted)
+        return;
+    autoOpenAttempted = true;
+    if (hookHasFiredForThisPpid())
+        return; // Claude Code already opened it
+    openUrlInBrowser(url);
+}
+const inputSchema = {
+    type: "object",
+    properties: {
+        html: {
+            type: "string",
+            description: "HTML body to render. Sandboxed in an iframe (allow-scripts). Style for off-white background; assume Rule 30 typography defaults are injected.",
+        },
+        title: {
+            type: "string",
+            description: "Short title shown in the card header.",
+        },
+        kind: {
+            type: "string",
+            description: "Freeform tag: mockup, diff, explanation, comparison, diagram, status, progress, etc.",
+        },
+    },
+    required: ["html"],
+    additionalProperties: false,
+};
+async function pushToServer(args) {
+    const r = await fetch(`http://127.0.0.1:${args.port}/api/push`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+            sessionId: args.sessionId,
+            html: args.html,
+            title: args.title,
+            kind: args.kind,
+        }),
+    });
+    if (!r.ok) {
+        const text = await r.text();
+        throw new Error(`display_push HTTP ${r.status}: ${text}`);
+    }
+    return (await r.json());
+}
+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).",
+                inputSchema,
+            },
+            {
+                name: TOOL_OPEN,
+                description: "Force-open a fresh browser tab for the current easel session. Call this when the user asks for a new window, side-by-side view, or to re-open a closed tab. The default SessionStart hook only opens a tab if none are alive; this tool overrides that.",
+                inputSchema: {
+                    type: "object",
+                    properties: {},
+                    additionalProperties: false,
+                },
+            },
+            {
+                name: TOOL_LABEL,
+                description: "Set or update this Claude session's display label — a short, human phrase that names what the session is about (e.g. 'Roadworthy 401 fix', 'Bulk-add cost items redesign', 'Investigating slow query'). The label appears in the topbar, switcher dropdown, and session index, replacing the cwd basename. Call this proactively whenever the work's theme shifts so the user can navigate sessions by what they ARE, not where they live. Pass an empty string to clear back to cwd basename.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        label: {
+                            type: "string",
+                            description: "Short human label (1–8 words). Pass empty string to clear.",
+                        },
+                    },
+                    required: ["label"],
+                    additionalProperties: false,
+                },
+            },
+            {
+                name: TOOL_CONFIG,
+                description: "Update the easel viewer's preset, theme, and/or density. Changes apply live across every open tab (SSE-broadcast) and persist. Presets: `paper` (pitstop warm canvas, amber accent — default), `aurora` (deep canvas + violet/blue glow halos), `slate` (cool slate, cyan accent). Themes: `light` or `dark`. Density: `carded` (default — each push is a bordered card) or `flat` (no card chrome — pushes flow as sections with whitespace between). Pass only the field(s) you want to change.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        preset: {
+                            type: "string",
+                            enum: ["paper", "aurora", "slate"],
+                            description: "Visual preset to apply globally.",
+                        },
+                        theme: {
+                            type: "string",
+                            enum: ["light", "dark"],
+                            description: "Light or dark mode.",
+                        },
+                        density: {
+                            type: "string",
+                            enum: ["carded", "flat"],
+                            description: "Layout density. `flat` removes card borders/shadow/bg and uses whitespace to separate pushes.",
+                        },
+                    },
+                    additionalProperties: false,
+                },
+            },
+        ],
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const sessionId = resolveClaudeSessionId();
+        const { port } = await ensureHttpServer();
+        // Non-Claude-Code clients have no SessionStart hook to open the tab —
+        // we do it ourselves on the first tool call instead.
+        maybeAutoOpenTab(`http://localhost:${port}/s/${sessionId}`);
+        if (req.params.name === TOOL_OPEN) {
+            const url = `http://localhost:${port}/s/${sessionId}`;
+            openUrlInBrowser(url);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `opened a new tab → ${url}`,
+                    },
+                ],
+            };
+        }
+        if (req.params.name === TOOL_LABEL) {
+            const args = (req.params.arguments ?? {});
+            const label = typeof args.label === "string" ? args.label.trim() : "";
+            await fetch(`http://127.0.0.1:${port}/api/register`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ sessionId, label }),
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: label
+                            ? `session labelled: ${label}`
+                            : `session label cleared`,
+                    },
+                ],
+            };
+        }
+        if (req.params.name === TOOL_CONFIG) {
+            const args = (req.params.arguments ?? {});
+            const body = {};
+            if (args.preset)
+                body.preset = args.preset;
+            if (args.theme)
+                body.theme = args.theme;
+            if (args.density)
+                body.density = args.density;
+            const r = await fetch(`http://127.0.0.1:${port}/api/config`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify(body),
+            });
+            const data = (await r.json());
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `display config now ${JSON.stringify(data.config)}`,
+                    },
+                ],
+            };
+        }
+        if (req.params.name !== TOOL_PUSH) {
+            throw new Error(`unknown tool: ${req.params.name}`);
+        }
+        const args = (req.params.arguments ?? {});
+        if (typeof args.html !== "string" || !args.html.length) {
+            throw new Error("easel.push: `html` is required");
+        }
+        const result = await pushToServer({
+            sessionId,
+            html: args.html,
+            title: args.title,
+            kind: args.kind,
+            port,
+        });
+        const tabHint = result.sessionTabs === 0
+            ? " · NO TAB OPEN for this session — ask the user if you should open one (call `open`)"
+            : "";
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `pushed #${result.index} → ${result.url}${tabHint}`,
+                },
+            ],
+        };
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error("[easel mcp] fatal:", err);
+    process.exit(1);
+});

package/dist/paths.js

@@ -0,0 +1,45 @@
+import { existsSync, renameSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** Root for runtime state — sessions, lockfile, hook session-id files. */
+export const DATA_ROOT = join(homedir(), ".easel");
+/** Directory the SessionStart hook writes per-PPID session-id files into. */
+export const HOOK_DIR = join(DATA_ROOT, "hook");
+/** Directory containing one folder per session. */
+export const SESSIONS_DIR = join(DATA_ROOT, "sessions");
+/** Lockfile coordinating which process owns the shared HTTP server. */
+export const LOCK_FILE = join(DATA_ROOT, "server.lock");
+/** Default HTTP port — overridable via EASEL_PORT (legacy: CLAUDE_DISPLAY_PORT). */
+export const DEFAULT_PORT = 7878;
+/** Max pushes retained per session before oldest is evicted. */
+export const MAX_PUSHES_PER_SESSION = 50;
+/** Idle TTL for sessions, in ms (24h). */
+export const SESSION_IDLE_TTL_MS = 24 * 60 * 60 * 1000;
+const LEGACY_DATA_ROOT = join(homedir(), ".claude-display");
+let migrationChecked = false;
+/**
+ * One-time migration from the project's prior name. Renames `~/.claude-display`
+ * to `~/.easel` if the legacy dir exists and the new dir doesn't. Safe to call
+ * repeatedly — short-circuits after the first call.
+ */
+export function migrateLegacyDataRoot() {
+    if (migrationChecked)
+        return;
+    migrationChecked = true;
+    if (existsSync(DATA_ROOT))
+        return;
+    if (!existsSync(LEGACY_DATA_ROOT))
+        return;
+    try {
+        renameSync(LEGACY_DATA_ROOT, DATA_ROOT);
+    }
+    catch {
+        // best-effort; the caller will mkdirSync DATA_ROOT and proceed
+    }
+}
+/** Read the configured port, preferring EASEL_PORT and falling back to the legacy env var. */
+export function resolvePort() {
+    return (Number(process.env.EASEL_PORT) ||
+        Number(process.env.CLAUDE_DISPLAY_PORT) ||
+        DEFAULT_PORT);
+}

package/dist/server-manager.js

@@ -0,0 +1,94 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import { DATA_ROOT, LOCK_FILE, migrateLegacyDataRoot, resolvePort, } from "./paths.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+export function readLock() {
+    if (!existsSync(LOCK_FILE))
+        return undefined;
+    try {
+        return JSON.parse(readFileSync(LOCK_FILE, "utf-8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function serverResponding(port) {
+    try {
+        const r = await fetch(`http://127.0.0.1:${port}/health`, {
+            signal: AbortSignal.timeout(800),
+        });
+        return r.ok;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Ensure exactly one HTTP server is running and return its port. If the
+ * lockfile points at a live, responding pid we reuse it; otherwise we spawn
+ * a detached child running `dist/http-entry.js` and wait for /health.
+ */
+export async function ensureHttpServer() {
+    migrateLegacyDataRoot();
+    mkdirSync(DATA_ROOT, { recursive: true });
+    const existing = readLock();
+    if (existing && pidAlive(existing.pid) && (await serverResponding(existing.port))) {
+        return { port: existing.port, reused: true };
+    }
+    if (existing) {
+        try {
+            rmSync(LOCK_FILE);
+        }
+        catch {
+            /* swallow */
+        }
+    }
+    const port = resolvePort();
+    const entry = resolve(__dirname, "http-entry.js");
+    const child = spawn(process.execPath, [entry], {
+        detached: true,
+        stdio: ["ignore", "ignore", "ignore"],
+        env: { ...process.env, EASEL_PORT: String(port) },
+    });
+    child.unref();
+    const deadline = Date.now() + 4000;
+    while (Date.now() < deadline) {
+        if (await serverResponding(port)) {
+            return { port, reused: false };
+        }
+        await new Promise((r) => setTimeout(r, 120));
+    }
+    throw new Error(`easel HTTP server failed to start on port ${port}`);
+}
+export function writeLock(port) {
+    migrateLegacyDataRoot();
+    mkdirSync(DATA_ROOT, { recursive: true });
+    const record = {
+        pid: process.pid,
+        port,
+        startedAt: Date.now(),
+    };
+    writeFileSync(LOCK_FILE, JSON.stringify(record, null, 2));
+}
+export function clearLockIfMine() {
+    const lock = readLock();
+    if (lock && lock.pid === process.pid) {
+        try {
+            rmSync(LOCK_FILE);
+        }
+        catch {
+            /* swallow */
+        }
+    }
+}