claude-design-mode 0.4.0

package/src/serve.mjs

@@ -0,0 +1,70 @@
+import http from 'node:http';
+import path from 'node:path';
+import { createHandler, newToken, configScript, OVERLAY_ROUTE, SELECTION_ROUTE } from './server.js';
+
+const BOOT_ROUTE = '/__design-mode/boot.js';
+
+/**
+ * Standalone Design Mode server for apps that are not on Vite (Next, Remix,
+ * Rails, Django, a static site...). The app adds one script tag in development:
+ *
+ *   <script src="http://localhost:3850/__design-mode/boot.js" referrerpolicy="origin"></script>
+ *
+ * referrerpolicy="origin" is required: the server identifies the requesting app
+ * by its Referer/Origin, and default browser policy strips the Referer on
+ * https -> http requests (and some frameworks set same-origin/no-referrer).
+ *
+ * boot.js carries this boot's token and loads the overlay; selections POST back
+ * here and land in the queue dir exactly as with the Vite plugin. There is no
+ * JSX stamping in this mode, so sources resolve from React debug stacks or the
+ * DOM path plus repo search (the skill handles both).
+ *
+ * Only pages from --app origins get the token: boot.js is served with a token
+ * only when the request's Referer/Origin is an allowed origin, and the
+ * selection endpoint accepts POSTs only from those origins.
+ */
+export function serve({ port = 3850, apps = [], queueDir, root = process.cwd(), log = console.log } = {}) {
+  const token = newToken();
+  const apps_ = apps.map((a) => a.replace(/\/$/, ''));
+  const dir = path.resolve(root, queueDir || path.join('.design-mode', 'queue'));
+  const handle = createHandler({ token, queueDir: dir, root, allowOrigins: apps_, cors: true, log });
+
+  const referrerOrigin = (req) => {
+    const ref = req.headers.origin || req.headers.referer;
+    if (!ref) return null;
+    try { return new URL(ref).origin; } catch { return null; }
+  };
+
+  const server = http.createServer((req, res) => {
+    const url = (req.url || '').split('?')[0];
+    if (url === BOOT_ROUTE && req.method === 'GET') {
+      const from = referrerOrigin(req);
+      const allowed = from && apps_.includes(from);
+      res.setHeader('content-type', 'application/javascript');
+      res.setHeader('cache-control', 'no-store');
+      if (!allowed) {
+        const who = from ? `${JSON.stringify(from).slice(1, -1)} is not an allowed app origin; start the server with --app <origin>` : 'the request carried no Referer or Origin, so the server cannot tell which app is asking; add referrerpolicy="origin" to the boot.js script tag (and check --app <origin>)';
+        res.end(`console.warn(${JSON.stringify(`[design-mode] ${who}`)});`);
+        return;
+      }
+      const self = `http://localhost:${port}`;
+      res.end([
+        configScript({ endpoint: `${self}${SELECTION_ROUTE}`, token }) + ';',
+        `(function(){var s=document.createElement('script');s.src=${JSON.stringify(self + OVERLAY_ROUTE)};s.defer=true;document.head.appendChild(s);})();`,
+      ].join('\n'));
+      return;
+    }
+    if (handle(req, res)) return;
+    res.statusCode = 404;
+    res.end('not found');
+  });
+
+  server.listen(port, '127.0.0.1', () => {
+    log(`[design-mode] serving on http://localhost:${port}`);
+    log(`[design-mode] queue: ${path.relative(root, dir) || '.'}`);
+    if (apps_.length) log(`[design-mode] allowed apps: ${apps_.join(', ')}`);
+    else log('[design-mode] no --app origins given: pages cannot load the overlay until you pass --app http://localhost:<your-port>');
+    log(`[design-mode] add to your app (dev only): <script src="http://localhost:${port}${BOOT_ROUTE}" referrerpolicy="origin"></script>`);
+  });
+  return server;
+}

package/src/server.d.ts

@@ -0,0 +1,45 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+
+export declare const OVERLAY_ROUTE: '/__design-mode/overlay.js';
+export declare const SELECTION_ROUTE: '/__design-mode/selection';
+export declare const HEALTH_ROUTE: '/__design-mode/health';
+export declare const MAX_BODY: number;
+
+/** Absolute filesystem path of the bundled overlay script. */
+export declare function overlayPath(): string;
+/** Absolute filesystem path of the bundled session skill directory. */
+export declare function skillDir(): string;
+/** A fresh per-boot token for the selection endpoint. */
+export declare function newToken(): string;
+
+export interface CreateHandlerOptions {
+  /** Per-boot secret the overlay sends back (see `newToken`). */
+  token: string;
+  /** Absolute directory where payloads are written as JSON files. */
+  queueDir: string;
+  /** Project root, used only to print relative paths. Default: `process.cwd()`. */
+  root?: string;
+  /** Extra Host names besides localhost/127.0.0.1/::1/*.localhost. */
+  allowedHosts?: string[];
+  /** Extra Origins to accept (the standalone server needs the app's origin). */
+  allowOrigins?: string[];
+  /** Answer preflights and echo an allowed Origin back (cross-origin overlay only). */
+  cors?: boolean;
+  log?: (msg: string) => void;
+}
+
+/**
+ * The Design Mode HTTP surface, framework-free. Returns a connect-style
+ * handler that returns true when it handled the request.
+ */
+export declare function createHandler(
+  opts: CreateHandlerOptions
+): (req: IncomingMessage, res: ServerResponse) => boolean;
+
+/** Serialize the plugin's `tokens` option (RegExp or strings) for the browser. */
+export declare function serializeTokenHints(
+  tokens?: Record<string, RegExp | string | null | undefined>
+): Record<string, string>;
+
+/** The inline config the page needs before the overlay script runs. */
+export declare function configScript(config: Record<string, unknown>): string;

package/src/server.js

@@ -0,0 +1,177 @@
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const OVERLAY_ROUTE = '/__design-mode/overlay.js';
+export const SELECTION_ROUTE = '/__design-mode/selection';
+export const HEALTH_ROUTE = '/__design-mode/health';
+export const MAX_BODY = 512 * 1024;
+
+// fileURLToPath, never URL.pathname: pathname is percent-encoded (a space is %20)
+// and carries a leading slash before the drive letter on Windows.
+export const overlayPath = () => fileURLToPath(new URL('./overlay.js', import.meta.url));
+export const skillDir = () => fileURLToPath(new URL('../skills/design-mode/', import.meta.url));
+export const newToken = () => randomBytes(16).toString('hex');
+
+/**
+ * The Design Mode HTTP surface, framework-free so the Vite plugin and the
+ * standalone `claude-design-mode serve` command share one implementation.
+ *
+ * Returns a connect-style handler: (req, res) => boolean (true when handled).
+ *
+ * Security model for the selection endpoint: a localhost URL that ultimately
+ * feeds an agent is a remote prompt-injection surface, so every request must
+ * carry a per-boot random token in a custom header (which also forces a CORS
+ * preflight that cross-origin pages fail), any Origin header must match an
+ * allowed origin (the server's own origin by default), and the Host header must
+ * be a local name (so a DNS rebinding page cannot become same-origin with the
+ * server and read the token out of the HTML). Token comparison is constant-time.
+ *
+ * Options:
+ *   token         per-boot secret the overlay sends back (newToken())
+ *   queueDir      absolute dir where payloads are written as JSON files
+ *   root          project root, used only to print relative paths
+ *   allowedHosts  extra Host names besides localhost/127.0.0.1/::1/*.localhost
+ *   allowOrigins  extra Origins to accept (the standalone server needs the app's origin)
+ *   cors          when true, answer preflights and echo an allowed Origin back
+ *                 (needed only when the overlay lives on a different origin)
+ *   log           (msg) => void
+ */
+export function createHandler(opts) {
+  const { token, queueDir, root = process.cwd(), log = () => {} } = opts;
+  const extraHosts = opts.allowedHosts || [];
+  const extraOrigins = opts.allowOrigins || [];
+  const cors = !!opts.cors;
+  let counter = 0;
+  fs.mkdirSync(queueDir, { recursive: true });
+
+  const selfOrigins = (req) => {
+    const host = req.headers.host;
+    return host ? [`http://${host}`, `https://${host}`] : [];
+  };
+  const originAllowed = (req, origin) => selfOrigins(req).includes(origin) || extraOrigins.includes(origin);
+  const isLocalHost = (host) => {
+    if (!host) return false;
+    const name = host.replace(/:\d+$/, '').replace(/^\[(.*)\]$/, '$1');
+    return name === 'localhost' || name.endsWith('.localhost') || name === '127.0.0.1'
+      || name === '::1' || extraHosts.includes(name);
+  };
+  const tokenMatches = (sent) => {
+    const a = Buffer.from(String(sent || ''));
+    const b = Buffer.from(token);
+    return a.length === b.length && timingSafeEqual(a, b);
+  };
+  const corsHeaders = (req, res) => {
+    const origin = req.headers.origin;
+    if (!cors || !origin || !originAllowed(req, origin)) return;
+    res.setHeader('access-control-allow-origin', origin);
+    res.setHeader('vary', 'Origin');
+    res.setHeader('access-control-allow-headers', 'content-type, x-design-mode-token');
+    res.setHeader('access-control-allow-methods', 'POST, OPTIONS');
+  };
+
+  return function handle(req, res) {
+    const url = (req.url || '').split('?')[0];
+
+    if (url === OVERLAY_ROUTE && req.method === 'GET') {
+      res.setHeader('content-type', 'application/javascript');
+      res.setHeader('cache-control', 'no-store');
+      corsHeaders(req, res);
+      res.end(fs.readFileSync(overlayPath(), 'utf8'));
+      return true;
+    }
+
+    if (url === HEALTH_ROUTE && req.method === 'GET') {
+      const pending = fs.existsSync(queueDir)
+        ? fs.readdirSync(queueDir).filter((f) => f.endsWith('.json')).length
+        : 0;
+      res.setHeader('content-type', 'application/json');
+      res.end(JSON.stringify({ ok: true, pending, queueDir }));
+      return true;
+    }
+
+    if (url !== SELECTION_ROUTE) return false;
+
+    if (req.method === 'OPTIONS') {
+      // Same-origin (Vite plugin) never preflights in practice; the standalone
+      // server does, and only echoes an allowed origin. The token and Origin
+      // checks below hold on their own regardless.
+      corsHeaders(req, res);
+      res.statusCode = 204;
+      res.end();
+      return true;
+    }
+    if (req.method !== 'POST') { res.statusCode = 405; res.end(); return true; }
+    // set CORS headers before any check: the overlay must be able to READ a 403
+    // (to say "reload the page") even when the token rotated; corsHeaders only
+    // ever echoes an allowed origin, so this widens nothing
+    corsHeaders(req, res);
+
+    if (!isLocalHost(req.headers.host)) {
+      res.statusCode = 403;
+      res.end('{"error":"host not allowed"}');
+      return true;
+    }
+    const origin = req.headers.origin;
+    if (origin && !originAllowed(req, origin)) {
+      res.statusCode = 403;
+      res.end('{"error":"origin not allowed"}');
+      return true;
+    }
+    if (!tokenMatches(req.headers['x-design-mode-token'])) {
+      res.statusCode = 403;
+      res.end('{"error":"bad token"}');
+      return true;
+    }
+    if (!String(req.headers['content-type'] || '').includes('application/json')) {
+      res.statusCode = 415;
+      res.end('{"error":"json only"}');
+      return true;
+    }
+
+    let size = 0;
+    const chunks = [];
+    req.on('data', (c) => {
+      size += c.length;
+      if (size > MAX_BODY) { res.statusCode = 413; res.end(); req.destroy(); return; }
+      chunks.push(c);
+    });
+    req.on('end', () => {
+      let payload;
+      try {
+        payload = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+      } catch {
+        res.statusCode = 400;
+        res.end('{"error":"invalid json"}');
+        return;
+      }
+      if (!payload || typeof payload.instruction !== 'string' || typeof payload.seq !== 'number') {
+        res.statusCode = 422;
+        res.end('{"error":"missing instruction/seq"}');
+        return;
+      }
+      // collision-proof, order-stable name; atomic write so the watcher
+      // never wakes on a half-written file
+      counter += 1;
+      fs.mkdirSync(queueDir, { recursive: true });
+      const file = path.join(queueDir, `${Date.now()}-${String(counter).padStart(6, '0')}-${randomBytes(3).toString('hex')}.json`);
+      fs.writeFileSync(`${file}.tmp`, JSON.stringify(payload, null, 2));
+      fs.renameSync(`${file}.tmp`, file);
+      log(`[design-mode] ${payload.kind || 'selection'} #${payload.seq} -> ${path.relative(root, file)}`);
+      res.setHeader('content-type', 'application/json');
+      res.end(JSON.stringify({ ok: true, file: path.relative(root, file) }));
+    });
+    return true;
+  };
+}
+
+/** Serialize the plugin's `tokens` option (RegExp or strings) for the browser. */
+export const serializeTokenHints = (tokens) => Object.fromEntries(
+  Object.entries(tokens || {})
+    .filter(([, v]) => v)
+    .map(([k, v]) => [k, v instanceof RegExp ? v.source : String(v)]),
+);
+
+/** The inline config the page needs before the overlay script runs. */
+export const configScript = (config) => `window.__CDM_CONFIG=${JSON.stringify(config)}`;

package/src/stamp.js

@@ -0,0 +1,32 @@
+/**
+ * Babel visitor that stamps data-claude-source="relpath:line:col" onto JSX host
+ * elements (lowercase tags only). Component call sites are deliberately left
+ * unstamped: passing an unknown data attribute as a prop would either get
+ * forwarded to an unpredictable host (spread props, Radix asChild) or dropped;
+ * component identity comes from the fiber owner chain instead.
+ */
+export default function stampPlugin({ types: t }) {
+  return {
+    name: 'design-mode-stamp',
+    visitor: {
+      JSXOpeningElement(path, state) {
+        const name = path.node.name;
+        if (name.type !== 'JSXIdentifier') return; // <Foo.Bar>, namespaced: skip
+        const first = name.name[0];
+        if (first !== first.toLowerCase()) return; // components: skip
+        if (!path.node.loc) return;
+        const exists = path.node.attributes.some(
+          (a) => a.type === 'JSXAttribute' && a.name && a.name.name === 'data-claude-source'
+        );
+        if (exists) return;
+        const { line, column } = path.node.loc.start;
+        path.node.attributes.push(
+          t.jsxAttribute(
+            t.jsxIdentifier('data-claude-source'),
+            t.stringLiteral(`${state.opts.relFile}:${line}:${column + 1}`)
+          )
+        );
+      },
+    },
+  };
+}

package/src/vite.d.ts

@@ -0,0 +1,38 @@
+import type { Plugin } from 'vite';
+
+export interface DesignModeOptions {
+  /** Where selection payloads are written. Default: `<vite-root>/.design-mode/queue`. */
+  queueDir?: string;
+  /** Extra Host names to accept besides localhost/127.0.0.1/::1/*.localhost. */
+  allowedHosts?: string[];
+  /** Set false to skip JSX stamping (non-React apps). */
+  stamp?: boolean;
+  /**
+   * Optional map of design-token families to the project's own custom-property
+   * patterns, e.g. `{ color: /^--brand-/, spacing: /^--space-/ }`. The overlay
+   * discovers tokens from the page's CSS on its own; these take precedence
+   * when a project's names are unusual.
+   */
+  tokens?: Partial<
+    Record<
+      | 'color'
+      | 'fontFamily'
+      | 'fontWeight'
+      | 'fontSize'
+      | 'lineHeight'
+      | 'tracking'
+      | 'radius'
+      | 'shadow'
+      | 'spacing',
+      RegExp | string
+    >
+  >;
+}
+
+/**
+ * Design Mode Vite plugin. Dev-serve only (and never inside Vitest); production
+ * builds are untouched. Stamps JSX host elements with
+ * `data-claude-source="relpath:line:col"`, serves the inspector overlay from
+ * the app's own origin, and receives selections on a token-checked endpoint.
+ */
+export default function designMode(options?: DesignModeOptions): Plugin;

package/src/vite.js

@@ -0,0 +1,95 @@
+import path from 'node:path';
+import { transformSync } from '@babel/core';
+import stampPlugin from './stamp.js';
+import { createHandler, newToken, serializeTokenHints, configScript, OVERLAY_ROUTE, SELECTION_ROUTE } from './server.js';
+
+/**
+ * Design Mode Vite plugin. Dev-serve only; never touches production builds.
+ *
+ *  - stamps data-claude-source="relpath:line:col" on JSX host elements
+ *  - serves the inspector overlay from the app's own origin
+ *  - receives selection payloads on a token-checked endpoint and writes them
+ *    to .design-mode/queue/ for the agent (`claude-design-mode wait` blocks on it)
+ *
+ * Options:
+ *   queueDir      where selections are written; default <vite-root>/.design-mode/queue
+ *   allowedHosts  extra Host names to accept besides localhost/127.0.0.1/::1/*.localhost
+ *   tokens        optional map of design-token families to the project's own custom-property
+ *                 patterns, e.g. { color: /^--brand-/, spacing: /^--space-/ }. The overlay
+ *                 discovers tokens from the page's CSS on its own (naming conventions, then
+ *                 value type); these patterns take precedence when a project's names are
+ *                 unusual. Families: color, fontFamily, fontWeight, fontSize, lineHeight,
+ *                 tracking, radius, shadow, spacing. Values may be RegExp or regex-source strings.
+ *   stamp         set false to skip JSX stamping (non-React apps); the overlay then resolves
+ *                 sources from React debug stacks or the DOM path instead
+ */
+export default function designMode(options = {}) {
+  const token = newToken();
+  const tokenHints = serializeTokenHints(options.tokens);
+  let root = process.cwd();
+  let queueDir = '';
+  const warned = new Set();
+
+  const stamp = (code, id) => {
+    if (options.stamp === false) return null;
+    const [file] = id.split('?');
+    if (!/\.[jt]sx$/.test(file) || file.includes('node_modules')) return null;
+    const relFile = path.relative(root, file).split(path.sep).join('/');
+    try {
+      const result = transformSync(code, {
+        filename: file,
+        configFile: false,
+        babelrc: false,
+        sourceMaps: true,
+        retainLines: true,
+        // decorators: esbuild accepts them, so the stamping parse must too
+        parserOpts: { sourceType: 'module', plugins: ['jsx', 'typescript', 'decorators-legacy'] },
+        plugins: [[stampPlugin, { relFile }]],
+      });
+      return result ? { code: result.code, map: result.map } : null;
+    } catch (e) {
+      // stamping is an aid, never a gate: an unparseable file loads unstamped
+      if (!warned.has(relFile)) {
+        warned.add(relFile);
+        console.warn(`[design-mode] could not stamp ${relFile} (${e.message ? e.message.split('\n')[0] : e}); serving it unstamped`);
+      }
+      return null;
+    }
+  };
+
+  return {
+    name: 'design-mode',
+    // dev serve only, and never inside Vitest: stamping test renders would
+    // break DOM snapshots, and tests have no use for the endpoint
+    apply: (_config, env) => env.command === 'serve' && env.mode !== 'test' && !process.env.VITEST,
+    enforce: 'pre', // must run before @vitejs/plugin-react compiles JSX away
+
+    configResolved(config) {
+      root = config.root;
+      queueDir = path.resolve(root, options.queueDir || path.join('.design-mode', 'queue'));
+    },
+
+    transform(code, id) {
+      return stamp(code, id);
+    },
+
+    transformIndexHtml() {
+      return [
+        { tag: 'script', injectTo: 'head', children: configScript({ endpoint: SELECTION_ROUTE, token, tokens: tokenHints }) },
+        { tag: 'script', injectTo: 'body', attrs: { src: OVERLAY_ROUTE, defer: true } },
+      ];
+    },
+
+    configureServer(server) {
+      const handle = createHandler({
+        token,
+        queueDir,
+        root,
+        allowedHosts: options.allowedHosts,
+        log: (msg) => server.config.logger.info(msg, { timestamp: true }),
+      });
+      server.middlewares.use((req, res, next) => { if (!handle(req, res)) next(); });
+      server.config.logger.info(`[design-mode] queue: ${path.relative(root, queueDir) || '.'}  (toggle with Cmd+D in the page)`, { timestamp: true });
+    },
+  };
+}

package/src/watch.mjs

@@ -0,0 +1,54 @@
+/**
+ * Wake watcher for agent sessions. Blocks until a selection payload lands in
+ * the queue dir, prints the path(s), and exits 0. The agent runs this as a
+ * background process; the harness re-invokes the agent when it exits.
+ *
+ *   claude-design-mode wait [queueDir] [--timeout <minutes>]
+ *
+ * Exit codes: 0 selection available · 2 timed out (re-arm me) · 1 error
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function wait({ dir, timeoutMin = 15, out = console.log, err = console.error, exit = process.exit } = {}) {
+  const queue = path.resolve(dir || path.join(process.cwd(), '.design-mode', 'queue'));
+  fs.mkdirSync(queue, { recursive: true });
+
+  const pending = () => {
+    try {
+      return fs.readdirSync(queue).filter((f) => f.endsWith('.json')).sort();
+    } catch {
+      fs.mkdirSync(queue, { recursive: true }); // dir was removed (git clean etc.); keep waiting
+      return [];
+    }
+  };
+
+  const finish = (files) => {
+    for (const f of files) out(path.join(queue, f));
+    exit(0);
+  };
+
+  const existing = pending();
+  if (existing.length) return finish(existing);
+
+  const check = () => {
+    const files = pending();
+    if (files.length) finish(files);
+  };
+
+  try {
+    fs.watch(queue, check);
+  } catch {
+    /* fs.watch can be flaky; the poll below still covers us */
+  }
+  const poll = setInterval(check, 2000);
+  poll.unref?.();
+
+  setTimeout(() => {
+    err(`no selection within ${timeoutMin}m`);
+    exit(2);
+  }, timeoutMin * 60 * 1000);
+
+  // keep the process alive while waiting
+  setInterval(() => {}, 1 << 30);
+}