@pro-vi/designer 0.3.0

package/dist/mcp-server.js

@@ -0,0 +1,136 @@
+#!/usr/bin/env -S node --import tsx
+import crypto from 'node:crypto';
+import path from 'node:path';
+import fs from 'node:fs';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { DesignerController } from "./designer-controller.js";
+import { sessionDir } from "./artifact-store.js";
+const server = new McpServer({ name: 'designer', version: '0.3.0' });
+const controllers = new Map();
+function getController(key) {
+    const k = key || 'default';
+    if (!controllers.has(k))
+        controllers.set(k, new DesignerController({ key: k, headed: true }));
+    return controllers.get(k);
+}
+function textResult(obj) {
+    return {
+        content: [{ type: 'text', text: typeof obj === 'string' ? obj : JSON.stringify(obj, null, 2) }],
+        structuredContent: typeof obj === 'object' && obj !== null ? obj : undefined
+    };
+}
+server.registerTool('designer_session', {
+    description: "Enter, inspect, or transition a claude.ai/design session. Default action='status' is a pure read — safe to call anytime to orient without side effects. Returns stored state + currentUrl + inSession + availableFiles so you can avoid a follow-up list call. Use this as the first tool in any agent loop.\n\nActions:\n- status (default): read-only, no mutations\n- ensure_ready: navigate to /design if not already there\n- resume: navigate into the stored designUrl for this key (fails if nothing stored)\n- create: new project (requires name)",
+    inputSchema: {
+        key: z.string().optional().describe('Stable key for this loop (e.g., feature name). Defaults to "default".'),
+        action: z.enum(['status', 'ensure_ready', 'resume', 'create']).optional().describe('Default: status'),
+        name: z.string().optional().describe('Required when action=create.'),
+        fidelity: z.enum(['wireframe', 'highfi']).optional().describe('Locked at creation. Default wireframe.')
+    }
+}, async ({ key, action = 'status', name, fidelity }) => textResult(await getController(key).session({ action, name, fidelity })));
+server.registerTool('designer_prompt', {
+    description: "Modify the design. Sends a prompt you expect to change the served HTML (e.g., 'create a login screen', 'add a Remember-me checkbox'). Waits for HTML to change and stabilize. Returns slim metadata — NOT inline HTML (written to disk at htmlPath).\n\n**Default taste path: hand the human `url` from the return.** The URL is the live claude.ai/design surface — fully interactive, tweak sliders work, variant switcher works. Only reach for `designer tasting` when full-viewport comparison matters more than interactivity.\n\nAuto-appended to every prompt: an instruction to keep all generated files at the project root (no subfolders). The live MCP's file-list scrape is flat-only; subfolder-nested files are invisible until `designer_handoff`. If you need nested layouts, explicitly contradict this in your prompt.\n\nKey return fields:\n- url: live URL to show the human (default taste path)\n- done.failureMode: null | 'timeout' | 'unstable' | 'no_change' (no_change means Claude replied text-only — did you want designer_ask?)\n- newFiles / removedFiles: diff vs pre-send\n- activeFile: what's currently rendered\n- htmlPath / screenshotPath: read these only if you need the content\n- chatReply: Claude's commentary",
+    inputSchema: {
+        key: z.string().optional(),
+        prompt: z.string(),
+        file: z.string().optional().describe('Switch to this file before sending (targets the prompt at it).'),
+        timeoutMs: z.number().optional().describe('Default 20m. Hi-fi generations can take 15+ min; bump this for complex multi-variant prompts.'),
+        stabilityMs: z.number().optional().describe('Default 4s.')
+    }
+}, async ({ key, prompt, file, timeoutMs, stabilityMs }) => textResult(await getController(key).iterate(prompt, { file, timeoutMs, stabilityMs })));
+server.registerTool('designer_ask', {
+    description: "Q&A with the design assistant — text-only, doesn't change any file. Use for 'why did you choose X?', 'compare A vs B', 'suggest 3 alternatives before I commit'. Returns the assistant's reply.",
+    inputSchema: {
+        key: z.string().optional(),
+        prompt: z.string(),
+        file: z.string().optional().describe('Switch to this file before asking (gives Claude context).'),
+        timeoutMs: z.number().optional().describe('Default 5m.'),
+        stabilityMs: z.number().optional().describe('Default 2.5s.')
+    }
+}, async ({ key, prompt, file, timeoutMs, stabilityMs }) => textResult(await getController(key).ask(prompt, { file, timeoutMs, stabilityMs })));
+server.registerTool('designer_list', {
+    description: "Inventory. scope='projects' lists all your Claude design projects; scope='files' lists files in the currently-open project. Usually you won't need this — designer_session already returns availableFiles, and designer_prompt returns newFiles.",
+    inputSchema: {
+        key: z.string().optional(),
+        scope: z.enum(['projects', 'files'])
+    }
+}, async ({ key, scope }) => {
+    const c = getController(key);
+    if (scope === 'projects')
+        return textResult(await c.listProjects());
+    const detail = await c.listFilesDetailed();
+    if (!detail.authoritative) {
+        return textResult({
+            files: detail.files,
+            folders: detail.folders,
+            authoritative: false,
+            warning: 'This project has folders (' +
+                detail.folders.join(', ') +
+                '). Files under folders are not visible to the live file-list scrape. Call designer_handoff for an authoritative list.'
+        });
+    }
+    return textResult({ files: detail.files, authoritative: true });
+});
+server.registerTool('designer_snapshot', {
+    description: "Inspect a file's current state. Switches to `filename` first if given. Default returns paths + hash only (no inline HTML — read htmlPath if you need the content). Set includeHtml=true to get the HTML inline.",
+    inputSchema: {
+        key: z.string().optional(),
+        filename: z.string().optional().describe('Switch to this file first. Omit to snapshot whatever is active.'),
+        includeHtml: z.boolean().optional().describe('Default false.'),
+        screenshot: z.boolean().optional().describe('Default true.')
+    }
+}, async ({ key, filename, includeHtml = false, screenshot = true }) => {
+    const c = getController(key);
+    if (filename) {
+        const swap = await c.openFile(filename);
+        if (!swap.ok)
+            return textResult({ ok: false, error: swap.error, file: filename });
+    }
+    const snap = await c.snapshotDesign({});
+    let htmlPath = null;
+    if (snap.html) {
+        htmlPath = path.join(sessionDir(c.key), `snap-${Date.now()}.html`);
+        fs.writeFileSync(htmlPath, snap.html);
+    }
+    return textResult({
+        ok: true,
+        file: filename || extractFileParamFromUrl(snap.url),
+        url: snap.url,
+        iframeSrc: snap.iframeSrc,
+        htmlPath,
+        screenshotPath: screenshot ? snap.screenshotPath : null,
+        htmlBytes: snap.html ? snap.html.length : 0,
+        htmlHash: snap.html ? simpleHash(snap.html) : null,
+        html: includeHtml ? snap.html : undefined
+    });
+});
+server.registerTool('designer_handoff', {
+    description: "Promote: trigger Export → Handoff to Claude Code, download the public tar.gz bundle (no auth), extract under ./artifacts/{key}/handoff-{ts}/. Bundle contains README.md, chat transcripts (decision record — every prompt + reply, verbatim), all design files, standalone HTML, shared CSS, design-canvas.jsx. Call when the human says 'yes, that's it'.",
+    inputSchema: {
+        key: z.string().optional(),
+        openFile: z.string().optional().describe('Set the open file before handoff.')
+    }
+}, async ({ key, openFile }) => textResult(await getController(key).handoff({ openFile })));
+function extractFileParamFromUrl(url) {
+    try {
+        return new URL(url).searchParams.get('file');
+    }
+    catch {
+        return null;
+    }
+}
+function simpleHash(s) {
+    return crypto.createHash('sha256').update(s).digest('hex').slice(0, 16);
+}
+export async function startMcpServer() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+const __isDirectInvoke = import.meta.url === `file://${process.argv[1]}` ||
+    process.argv[1]?.endsWith('mcp-server.ts') ||
+    process.argv[1]?.endsWith('mcp-server.js');
+if (__isDirectInvoke) {
+    await startMcpServer();
+}

package/dist/repo-root.js

@@ -0,0 +1,15 @@
+import fs from 'node:fs';
+import path from 'node:path';
+function findRepoRoot() {
+    let dir = path.dirname(new URL(import.meta.url).pathname);
+    for (let i = 0; i < 8; i++) {
+        if (fs.existsSync(path.join(dir, 'package.json')))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    throw new Error('repo-root: could not find package.json walking up from ' + new URL(import.meta.url).pathname);
+}
+export const REPO_ROOT = findRepoRoot();

package/dist/scripts/probe.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env -S node --import tsx
+import { createBrowser } from "../browser.js";
+const cmd = process.argv[2];
+const arg = process.argv[3];
+const browser = createBrowser({ headed: true });
+if (!process.env.DESIGNER_CDP) {
+    console.error('[probe] DESIGNER_CDP not set — using agent-browser-managed session (may be blocked by Cloudflare/SSO). Prefer: export DESIGNER_CDP=9222 and relaunch Chrome with --remote-debugging-port=9222.');
+}
+async function main() {
+    switch (cmd) {
+        case 'login':
+            console.log('Opening claude.ai/design in a headed browser window.');
+            console.log('Complete Cloudflare + sign in. Session state auto-persists to ~/.agent-browser/.');
+            await browser.open('https://claude.ai/design');
+            break;
+        case 'url':
+            console.log(await browser.url());
+            break;
+        case 'title':
+            console.log(await browser.title());
+            break;
+        case 'snapshot':
+            console.log(await browser.snapshotText({ interactive: true, scope: arg }));
+            break;
+        case 'snapshot-json':
+            console.log(JSON.stringify(await browser.snapshot({ interactive: true, scope: arg }), null, 2));
+            break;
+        case 'screenshot': {
+            const p = arg || `./logs/probe-${Date.now()}.png`;
+            await browser.screenshot(p, { full: true });
+            console.log(p);
+            break;
+        }
+        case 'eval':
+            if (!arg)
+                throw new Error('Usage: probe.ts eval <js>');
+            console.log(await browser.eval(arg));
+            break;
+        case 'open':
+            await browser.open(arg || 'https://claude.ai/design');
+            console.log(await browser.url());
+            break;
+        case 'close':
+            await browser.close();
+            break;
+        default:
+            console.log(`Usage:
+  probe.ts login                  open headed window for manual login
+  probe.ts open <url>             navigate
+  probe.ts url                    print current url
+  probe.ts title                  print current title
+  probe.ts snapshot [scope]       interactive a11y tree (text)
+  probe.ts snapshot-json [scope]  interactive a11y tree (JSON)
+  probe.ts screenshot [path]      full-page screenshot
+  probe.ts eval <js>              evaluate JS in page
+  probe.ts close                  close browser`);
+    }
+}
+main().catch((e) => {
+    console.error(e.message);
+    process.exit(1);
+});

package/dist/session-store.js

@@ -0,0 +1,49 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+const ROOT = process.env.DESIGNER_STATE_DIR || path.join(os.homedir(), '.designer');
+const SESSIONS_FILE = path.join(ROOT, 'sessions.json');
+function ensureRoot() {
+    fs.mkdirSync(ROOT, { recursive: true });
+}
+function readAll() {
+    ensureRoot();
+    if (!fs.existsSync(SESSIONS_FILE))
+        return {};
+    try {
+        return JSON.parse(fs.readFileSync(SESSIONS_FILE, 'utf8')) || {};
+    }
+    catch {
+        return {};
+    }
+}
+function writeAll(data) {
+    ensureRoot();
+    fs.writeFileSync(SESSIONS_FILE, JSON.stringify(data, null, 2));
+}
+export function getSession(key) {
+    return readAll()[key] || null;
+}
+export function upsertSession(key, patch) {
+    const all = readAll();
+    const prev = all[key] || { key, createdAt: new Date().toISOString(), history: [] };
+    const next = { ...prev, ...patch, updatedAt: new Date().toISOString() };
+    all[key] = next;
+    writeAll(all);
+    return next;
+}
+export function listSessions() {
+    return Object.values(readAll());
+}
+export function appendHistory(key, entry) {
+    const all = readAll();
+    const prev = all[key] || { key, createdAt: new Date().toISOString(), history: [] };
+    prev.history = [...(prev.history || []), { ...entry, at: new Date().toISOString() }];
+    prev.updatedAt = new Date().toISOString();
+    all[key] = prev;
+    writeAll(all);
+    return prev;
+}
+export function stateDir() {
+    return ROOT;
+}

package/dist/setup.js

@@ -0,0 +1,258 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { spawn, spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { REPO_ROOT } from "./repo-root.js";
+const SKILL_SRC = path.join(REPO_ROOT, 'skills', 'designer-loop', 'SKILL.md');
+const SKILL_DEST_DIR = path.join(os.homedir(), '.claude', 'skills', 'designer-loop');
+const SKILL_DEST = path.join(SKILL_DEST_DIR, 'SKILL.md');
+const CHROME_BIN = process.env.CHROME_BIN || '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome';
+const DEFAULT_PORT = process.env.DESIGNER_CDP || '9222';
+const PROFILE = path.join(os.homedir(), '.chrome-designer-profile');
+function log(stage, status, msg) {
+    const icon = status === 'ok' ? '✓' : status === 'wait' ? '·' : '✗';
+    console.log(`${icon} [${stage}] ${msg}`);
+}
+async function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+async function isCdpUp(port) {
+    try {
+        const res = await fetch(`http://127.0.0.1:${port}/json/version`, { signal: AbortSignal.timeout(1500) });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+async function getDesignTab(port) {
+    try {
+        const res = await fetch(`http://127.0.0.1:${port}/json/list`, { signal: AbortSignal.timeout(2000) });
+        if (!res.ok)
+            return null;
+        const tabs = (await res.json());
+        for (const t of tabs) {
+            if (t.url && /claude\.ai\/design/.test(t.url) && !/login/i.test(t.url)) {
+                return { url: t.url, title: t.title || '' };
+            }
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function chromeRunning() {
+    const r = spawnSync('pgrep', ['-f', 'Google Chrome.app/Contents/MacOS/Google Chrome'], { stdio: 'pipe' });
+    return r.status === 0 && (r.stdout?.toString().trim().length ?? 0) > 0;
+}
+async function pollUntil(name, fn, opts) {
+    const start = Date.now();
+    let emittedReminder = false;
+    let emittedHint = false;
+    let dots = 0;
+    while (Date.now() - start < opts.timeoutMs) {
+        if (await fn()) {
+            if (dots > 0)
+                process.stdout.write('\n');
+            return true;
+        }
+        const elapsed = Date.now() - start;
+        if (!emittedReminder) {
+            log(name, 'wait', opts.reminder);
+            emittedReminder = true;
+        }
+        else {
+            process.stdout.write('.');
+            dots++;
+        }
+        if (!emittedHint && opts.hint60s && elapsed > 60_000) {
+            process.stdout.write('\n');
+            dots = 0;
+            log(name, 'wait', opts.hint60s);
+            emittedHint = true;
+        }
+        await sleep(opts.intervalMs);
+    }
+    if (dots > 0)
+        process.stdout.write('\n');
+    return false;
+}
+function lockfileHash(p) {
+    try {
+        return createHash('sha1').update(fs.readFileSync(p)).digest('hex');
+    }
+    catch {
+        return null;
+    }
+}
+async function step1NpmInstall() {
+    const nm = path.join(REPO_ROOT, 'node_modules');
+    const rootLock = path.join(REPO_ROOT, 'package-lock.json');
+    const innerLock = path.join(nm, '.package-lock.json');
+    if (!fs.existsSync(rootLock)) {
+        if (fs.existsSync(nm)) {
+            log('deps', 'ok', 'installed-mode (no package-lock to verify)');
+            return true;
+        }
+        log('deps', 'fail', 'no package-lock.json and no node_modules — reinstall the package');
+        return false;
+    }
+    if (fs.existsSync(nm)) {
+        const a = lockfileHash(rootLock);
+        const b = lockfileHash(innerLock);
+        if (a && b && a === b) {
+            log('deps', 'ok', 'node_modules in sync with package-lock');
+            return true;
+        }
+        log('deps', 'wait', b ? 'lockfile mismatch; reinstalling...' : 'no inner lockfile; reinstalling to sync...');
+    }
+    else {
+        log('deps', 'wait', 'running npm install...');
+    }
+    const r = spawnSync('npm', ['install'], { cwd: REPO_ROOT, stdio: 'inherit' });
+    if (r.status !== 0) {
+        log('deps', 'fail', `npm install exited ${r.status}`);
+        return false;
+    }
+    log('deps', 'ok', 'installed');
+    return true;
+}
+function step2AgentBrowser() {
+    const r = spawnSync('agent-browser', ['--version'], { stdio: 'pipe' });
+    if (r.status !== 0) {
+        log('agent-browser', 'fail', 'not found on PATH. Install: brew install agent-browser  OR  npm i -g agent-browser');
+        return false;
+    }
+    log('agent-browser', 'ok', r.stdout?.toString().trim() || 'present');
+    return true;
+}
+async function step3Chrome(port) {
+    if (await isCdpUp(port)) {
+        log('chrome', 'ok', `CDP already up on :${port}`);
+        return true;
+    }
+    if (chromeRunning()) {
+        log('chrome', 'wait', 'A non-debug Chrome is running. Quit it (Cmd+Q on the Chrome menu, then close Activity Monitor entries if any). I am polling.');
+        const quit = await pollUntil('chrome', () => !chromeRunning(), {
+            intervalMs: 1000,
+            timeoutMs: 5 * 60_000,
+            reminder: 'Still waiting for Chrome to fully quit. Cmd+Q on Chrome.'
+        });
+        if (!quit) {
+            log('chrome', 'fail', 'Timed out waiting for Chrome to quit. Quit manually then re-run setup.');
+            return false;
+        }
+    }
+    log('chrome', 'wait', `Launching debug Chrome on :${port} with --user-data-dir=${PROFILE}`);
+    if (!fs.existsSync(CHROME_BIN)) {
+        log('chrome', 'fail', `Chrome not found at ${CHROME_BIN}. Set CHROME_BIN to override.`);
+        return false;
+    }
+    const child = spawn(CHROME_BIN, ['--remote-debugging-port=' + port, '--user-data-dir=' + PROFILE, 'https://claude.ai/design'], {
+        detached: true,
+        stdio: 'ignore'
+    });
+    child.unref();
+    const up = await pollUntil('chrome', () => isCdpUp(port), {
+        intervalMs: 800,
+        timeoutMs: 30_000,
+        reminder: `Waiting for CDP at :${port}...`
+    });
+    if (!up) {
+        log('chrome', 'fail', 'Chrome launched but CDP did not come up. Try `./scripts/designer-chrome.sh` manually.');
+        return false;
+    }
+    log('chrome', 'ok', `CDP up on :${port}`);
+    return true;
+}
+async function step4SignIn(port) {
+    const tab = await getDesignTab(port);
+    if (tab) {
+        log('login', 'ok', `Signed in. Tab on ${tab.url.replace(/\?.*$/, '')}`);
+        return true;
+    }
+    log('login', 'wait', 'Sign in to Claude in the debug Chrome window I just opened, then navigate to claude.ai/design. I am polling.');
+    const ok = await pollUntil('login', async () => (await getDesignTab(port)) !== null, {
+        intervalMs: 2000,
+        timeoutMs: 10 * 60_000,
+        reminder: 'Still waiting for a tab on claude.ai/design (not on /login).',
+        hint60s: "If Chrome shows a Google 'new device' or 2FA prompt, complete that first — setup is waiting on you."
+    });
+    if (!ok) {
+        log('login', 'fail', 'Timed out waiting for sign-in. Re-run setup when ready.');
+        return false;
+    }
+    log('login', 'ok', 'Signed in.');
+    return true;
+}
+function step5Skill() {
+    if (fs.existsSync(SKILL_DEST)) {
+        let detail = `Already at ${SKILL_DEST}`;
+        try {
+            if (fs.lstatSync(SKILL_DEST_DIR).isSymbolicLink()) {
+                detail = `Already at ${SKILL_DEST_DIR} → ${fs.realpathSync(SKILL_DEST_DIR)} (bootstrap-managed, leaving alone)`;
+            }
+        }
+        catch { }
+        log('skill', 'ok', detail);
+        return true;
+    }
+    if (!fs.existsSync(SKILL_SRC)) {
+        log('skill', 'fail', `Source missing at ${SKILL_SRC}; reclone repo?`);
+        return false;
+    }
+    fs.mkdirSync(SKILL_DEST_DIR, { recursive: true });
+    fs.copyFileSync(SKILL_SRC, SKILL_DEST);
+    log('skill', 'ok', `Copied to ${SKILL_DEST}`);
+    return true;
+}
+function step6Mcp(port) {
+    const claudeBin = spawnSync('which', ['claude'], { stdio: 'pipe' });
+    if (claudeBin.status !== 0) {
+        log('mcp', 'wait', 'claude CLI not on PATH; skipping MCP registration. Install Claude Code to register.');
+        return true;
+    }
+    const list = spawnSync('claude', ['mcp', 'list'], { stdio: 'pipe' });
+    const stdout = list.stdout?.toString() || '';
+    if (/(\s|^)designer\b/i.test(stdout)) {
+        log('mcp', 'ok', 'Already registered.');
+        return true;
+    }
+    const wrapper = path.join(REPO_ROOT, 'bin', 'designer');
+    if (!fs.existsSync(wrapper)) {
+        log('mcp', 'fail', `Missing wrapper ${wrapper}`);
+        return false;
+    }
+    const cmd = ['mcp', 'add', '--scope', 'user', '--transport', 'stdio', 'designer', '--', 'env', `DESIGNER_CDP=${port}`, wrapper, 'mcp', 'serve'];
+    log('mcp', 'wait', `Registering: claude ${cmd.join(' ')}`);
+    const reg = spawnSync('claude', cmd, { stdio: 'inherit' });
+    if (reg.status !== 0) {
+        log('mcp', 'fail', `claude mcp add exited ${reg.status}. Run manually:\n   claude ${cmd.join(' ')}`);
+        return false;
+    }
+    log('mcp', 'ok', 'Registered.');
+    return true;
+}
+export async function runSetup() {
+    console.log(`designer setup — port=${DEFAULT_PORT}, profile=${PROFILE}\n`);
+    if (!(await step1NpmInstall()))
+        return 1;
+    if (!step2AgentBrowser())
+        return 1;
+    if (!(await step3Chrome(DEFAULT_PORT)))
+        return 1;
+    if (!(await step4SignIn(DEFAULT_PORT)))
+        return 1;
+    if (!step5Skill())
+        return 1;
+    if (!step6Mcp(DEFAULT_PORT))
+        return 1;
+    console.log('\n✓ designer is ready. Verify:  designer doctor');
+    console.log(`  (or: DESIGNER_CDP=${DEFAULT_PORT} tsx cli.ts doctor)`);
+    if (!process.env.DESIGNER_CDP) {
+        console.log(`\nTip: export DESIGNER_CDP=${DEFAULT_PORT} in your shell rc if you'll invoke the CLI directly (MCP callers don't need this).`);
+    }
+    return 0;
+}

package/dist/tasting.js

@@ -0,0 +1,117 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+export function writeTastingHtml({ projectDir, variants, outPath, title = 'Tasting' }) {
+    const target = outPath || path.join(projectDir, 'tasting.html');
+    const html = renderTastingHtml({ variants, title });
+    fs.writeFileSync(target, html);
+    return target;
+}
+function renderTastingHtml({ variants, title }) {
+    const tabs = variants
+        .map((v, i) => `<button class="tab${i === 0 ? ' active' : ''}" data-src="${encodeURI(v.file)}">${escapeHtml(v.name)}</button>`)
+        .join('');
+    const firstSrc = variants[0] ? encodeURI(variants[0].file) : '';
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>${escapeHtml(title)} — tasting</title>
+<style>
+  :root { color-scheme: light dark; }
+  * { box-sizing: border-box; }
+  html, body { margin: 0; padding: 0; height: 100%; font-family: -apple-system, BlinkMacSystemFont, "Inter", system-ui, sans-serif; background: #0f0f10; color: #e8e6e3; }
+  .bar { position: fixed; top: 0; left: 0; right: 0; height: 44px; display: flex; align-items: center; gap: 0; padding: 0 12px; background: rgba(20,20,22,0.92); backdrop-filter: blur(12px); border-bottom: 1px solid rgba(255,255,255,0.08); z-index: 9999; }
+  .title { font-size: 12px; letter-spacing: 0.05em; text-transform: uppercase; color: #8a8680; margin-right: 18px; }
+  .tabs { display: flex; gap: 2px; }
+  .tab { appearance: none; border: 0; background: transparent; color: #b4b0a9; padding: 8px 14px; font: inherit; font-size: 13px; cursor: pointer; border-bottom: 2px solid transparent; transition: color 120ms, border-color 120ms; }
+  .tab:hover { color: #e8e6e3; }
+  .tab.active { color: #ffffff; border-bottom-color: #ff8a3d; font-weight: 500; }
+  .spacer { flex: 1; }
+  .notes { background: rgba(255,255,255,0.04); border: 1px solid rgba(255,255,255,0.08); border-radius: 6px; padding: 6px 10px; color: #e8e6e3; font: inherit; font-size: 13px; min-width: 280px; }
+  .notes::placeholder { color: #6a665f; }
+  .keys { font-size: 11px; color: #6a665f; margin-left: 12px; }
+  iframe.stage { position: fixed; top: 44px; left: 0; right: 0; bottom: 0; width: 100%; height: calc(100% - 44px); border: 0; background: #fff; }
+</style>
+</head>
+<body>
+  <nav class="bar" role="toolbar" aria-label="Variant switcher">
+    <span class="title">${escapeHtml(title)}</span>
+    <div class="tabs">${tabs}</div>
+    <span class="keys">[1]–[${variants.length}] to switch</span>
+    <span class="spacer"></span>
+    <input class="notes" placeholder="Reaction in your own words — saved to tasting-notes.txt" />
+  </nav>
+  <iframe class="stage" id="stage" src="${firstSrc}" title="variant"></iframe>
+<script>
+  const tabs = document.querySelectorAll('.tab');
+  const stage = document.getElementById('stage');
+  const notes = document.querySelector('.notes');
+  const NOTES_KEY = 'designer-tasting-notes:${encodeURIComponent(title)}';
+  const saved = localStorage.getItem(NOTES_KEY);
+  if (saved) notes.value = saved;
+  notes.addEventListener('input', () => localStorage.setItem(NOTES_KEY, notes.value));
+
+  function activate(tab) {
+    tabs.forEach(t => t.classList.remove('active'));
+    tab.classList.add('active');
+    stage.src = tab.dataset.src;
+  }
+  function onKey(e) {
+    if (e.target === notes) return;
+    const n = parseInt(e.key, 10);
+    if (!Number.isNaN(n) && n >= 1 && n <= tabs.length) {
+      e.preventDefault();
+      activate(tabs[n - 1]);
+    }
+  }
+  tabs.forEach(t => t.addEventListener('click', () => activate(t)));
+  // Parent-document listener handles keys when focus is on the bar/notes/body.
+  document.addEventListener('keydown', onKey);
+  // Iframe content captures keys when the user has interacted with the variant.
+  // Same-origin (we serve via http.server on the same port) so we can reach in.
+  stage.addEventListener('load', () => {
+    try { stage.contentDocument && stage.contentDocument.addEventListener('keydown', onKey); } catch {}
+  });
+</script>
+</body>
+</html>
+`;
+}
+function escapeHtml(s) {
+    return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+const servers = new Map();
+export async function serveAndOpen(projectDir, { file = 'tasting.html', port } = {}) {
+    const chosenPort = port || (await pickFreePort(8765));
+    const child = spawn('python3', ['-m', 'http.server', String(chosenPort)], {
+        cwd: projectDir,
+        stdio: 'ignore',
+        detached: true
+    });
+    child.unref();
+    await sleep(500);
+    const url = `http://127.0.0.1:${chosenPort}/${encodeURI(file)}`;
+    spawn('open', [url], { stdio: 'ignore', detached: true }).unref();
+    const pid = child.pid ?? -1;
+    servers.set(projectDir, { port: chosenPort, pid });
+    return { url, port: chosenPort, pid };
+}
+async function pickFreePort(start) {
+    const net = await import('node:net');
+    for (let p = start; p < start + 100; p++) {
+        const free = await new Promise((resolve) => {
+            const s = net.createServer();
+            s.once('error', () => resolve(false));
+            s.once('listening', () => s.close(() => resolve(true)));
+            s.listen(p, '0.0.0.0');
+        });
+        if (free)
+            return p;
+    }
+    throw new Error(`No free port between ${start} and ${start + 100}`);
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}