@digital-gravy/etch-connector 0.1.3 → 0.1.5

package/README.md

@@ -23,7 +23,7 @@ Claude Code / Cowork
       │  shell:  etch-connector eval -t homepage "return ..."
       ▼
   etch-connector  (the `serve` daemon)
-      │  ▲   WebSocket  (tab dials in via etch.connectTo)
+      │  ▲   WebSocket  (tab dials in via etch.connectAs)
       ▼  │
   Etch builder tab  ──►  window.etch.*
 ```
@@ -32,8 +32,7 @@ Claude Code / Cowork
 
 This is an **eval relay**: the harness sends a JavaScript snippet, the page runs
 it as an async function, and the return value + console output come back. It is
-intentionally _not_ an MCP server yet, but it is built so that becoming one is a
-thin add — see [Going to MCP](#going-to-mcp-later).
+not an MCP server yet — see [Going to MCP](#going-to-mcp-later).
 
 Scripts run in a **page-enforced safe mode**: the script sees only `etch` and
 the standard JS built-ins. `window`, `document`, `fetch`, storage, `eval`, … are
@@ -75,13 +74,19 @@ etch-connector serve
 
 ### 2. Connect a tab
 
-Open an Etch builder page and, in the browser console:
+**Primary way — the AI button.** Enable the **AI Connector** in the Etch
+Settings, then open an Etch builder page and click the **AI button** in the left
+sidebar. It connects this tab for you, registering it under your site name (it
+just calls `connectAs` under the hood). Click it again to disconnect.
+
+**Secondary way — the console.** You can also connect manually from the browser
+console:
 
 ```js
-etch.connectTo('homepage');
+etch.connectAs('homepage');
 ```
 
-(`connectTo` is part of the public API; it opens the WebSocket back to the
+(`connectAs` is part of the public API; it opens the WebSocket back to the
 daemon and registers this tab under the given name. Pass `{ port: <n> }` if you
 started the daemon on a non-default WebSocket port.)
 
@@ -127,8 +132,10 @@ The authoritative agent instructions live in **`etch-connector --help`** — rea
 the entire output before interacting with Etch. It covers the backends, commands
 and flags, the stdout/stderr/exit-code contract, how to pull the current Etch
 docs (Context7 MCP or <https://docs.etchwp.com/public-api>), and the conventions
-for structuring pages (e.g. the section/container layout pattern). Project
-conventions for working on this repo live in [`AGENTS.md`](AGENTS.md).
+for structuring pages (e.g. the section/container layout pattern). The public API
+may also expose ready-made skills for common tasks — check the docs before
+improvising. Project conventions for working on this repo live in
+[`AGENTS.md`](AGENTS.md).
 
 ## CLI
 
@@ -144,7 +151,7 @@ Usage:
   etch-connector computed  <selector> [-t name] [--props a,b,c]                               (CDP)
 
 Two backends:
-  bridge  (default) the tab dials in via etch.connectTo(); page-sandboxed.
+  bridge  (default) the tab dials in via etch.connectAs(); page-sandboxed.
           Scripts see only "etch" + the standard JS built-ins.
   cdp     connect OUT to a Chrome started with --remote-debugging-port=9222.
           No daemon. Runs at DevTools privilege: full "window", plus screenshots,
@@ -191,22 +198,10 @@ the same one a future MCP server would call):
 
 ## Going to MCP later
 
-Nothing in the transport changes. An MCP server is `new BridgeServer()` plus two
-tool definitions over the same core:
-
-```ts
-import { BridgeServer } from 'etch-connector';
-
-const bridge = new BridgeServer();
-await bridge.listen();
-
-// list_etch_tabs   -> bridge.listTabs()
-// eval_etch_script -> bridge.evalInTab(code, { tab })
-```
-
-When you want first-class per-tool MCP tools (rather than one eval tool), have
-the Etch tab advertise a tool manifest in its `hello` and register those
-dynamically — keeping a single source of truth in the browser registry.
+Today this is a CLI eval relay. A future version will expose the same bridge as
+a proper MCP server, so an AI harness can call first-class tools (list tabs, run
+a script) directly instead of shelling out — without changing how you connect a
+tab.
 
 ## Security
 
@@ -223,10 +218,5 @@ hardened sandbox**: because the script shares the page's JS realm, a _determined
 author can still reach globals through prototype / constructor chains (e.g.
 `({}).constructor.constructor`). It reliably keeps casual and AI-authored
 scripts on the `etch` surface and closes the obvious escape hatches; it does
-**not** contain hostile code.
-
-For a true boundary against adversarial scripts you would need to harden the
-realm (SES `lockdown()`), which freezes all intrinsics app-wide and is out of
-scope for this relay. The enforcement lives in the Etch page (`bridge.ts`), not
-this connector — the connector only carries the requested mode; a string filter
-here would be theater.
+**not** contain hostile code. For a true boundary against adversarial scripts,
+run the daemon only on a trusted machine.

package/dist/cli.js

@@ -36,49 +36,58 @@ const BOOLEAN_FLAGS = new Set([
     'help',
     'freeze'
 ]);
+/** Single-letter aliases → their long flag name. */
+const SHORT_FLAGS = {
+    t: 'tab',
+    f: 'file',
+    p: 'port',
+    s: 'selector',
+    o: 'out'
+};
+/** A non-flag token is a value iff it exists and isn't itself a flag. */
+function isValueToken(next) {
+    return next !== undefined && !next.startsWith('-');
+}
+/** Record a `--long` flag; returns true if it consumed `next` as its value. */
+function applyLongFlag(flags, arg, next) {
+    // Support --key=value (e.g. --freeze=false) explicitly.
+    const eq = arg.indexOf('=');
+    if (eq !== -1) {
+        flags[arg.slice(2, eq)] = arg.slice(eq + 1);
+        return false;
+    }
+    const key = arg.slice(2);
+    if (!BOOLEAN_FLAGS.has(key) && isValueToken(next)) {
+        flags[key] = next;
+        return true;
+    }
+    flags[key] = true;
+    return false;
+}
+/** Record a `-x` short flag; returns true if it consumed `next` as its value. */
+function applyShortFlag(flags, arg, next) {
+    const key = SHORT_FLAGS[arg.slice(1)] ?? arg.slice(1);
+    if (isValueToken(next)) {
+        flags[key] = next;
+        return true;
+    }
+    flags[key] = true;
+    return false;
+}
 function parseArgs(argv) {
     const command = argv[0] ?? 'help';
     const positional = [];
     const flags = {};
     for (let i = 1; i < argv.length; i++) {
         const arg = argv[i];
+        const next = argv[i + 1];
         if (arg.startsWith('--')) {
-            // Support --key=value (e.g. --freeze=false) explicitly.
-            const eq = arg.indexOf('=');
-            if (eq !== -1) {
-                flags[arg.slice(2, eq)] = arg.slice(eq + 1);
-                continue;
-            }
-            const key = arg.slice(2);
-            const next = argv[i + 1];
-            if (BOOLEAN_FLAGS.has(key)) {
-                flags[key] = true;
-            }
-            else if (next !== undefined && !next.startsWith('-')) {
-                flags[key] = next;
+            if (applyLongFlag(flags, arg, next))
                 i++;
-            }
-            else {
-                flags[key] = true;
-            }
         }
         else if (arg.startsWith('-') && arg.length === 2) {
-            const map = {
-                t: 'tab',
-                f: 'file',
-                p: 'port',
-                s: 'selector',
-                o: 'out'
-            };
-            const key = map[arg.slice(1)] ?? arg.slice(1);
-            const next = argv[i + 1];
-            if (next !== undefined && !next.startsWith('-')) {
-                flags[key] = next;
+            if (applyShortFlag(flags, arg, next))
                 i++;
-            }
-            else {
-                flags[key] = true;
-            }
         }
         else {
             positional.push(arg);
@@ -105,6 +114,10 @@ function bool(flag, fallback) {
         return flag;
     return !/^(false|0|no|off)$/i.test(flag);
 }
+/** Pretty-print a value to stdout as JSON (the clean machine-readable result). */
+function writeJson(value) {
+    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
 function readStdin() {
     return new Promise((resolve) => {
         let data = '';
@@ -113,6 +126,15 @@ function readStdin() {
         process.stdin.on('end', () => resolve(data));
     });
 }
+/** The startup banner printed once both servers are listening. */
+function printServeBanner(wsHost, boundWsPort, controlHost, controlPort, defaultMode) {
+    console.error(`[etch-connector] bridge   ws://${wsHost}:${boundWsPort}`);
+    console.error(`[etch-connector] control  ${controlBaseUrl({ host: controlHost, port: controlPort })}`);
+    console.error(`[etch-connector] default mode: ${defaultMode}${defaultMode === 'unsafe' ? '  ⚠  scripts get full access to the page' : '  (scripts see only window.etch + JS built-ins)'}`);
+    console.error('[etch-connector] In an Etch builder tab, run:');
+    console.error(`[etch-connector]     etch.connectAs('my-tab'${boundWsPort === DEFAULT_WS_PORT ? '' : `, { port: ${boundWsPort} }`})`);
+    console.error('[etch-connector] then drive it with:  etch-connector eval -t my-tab "return window.etch.apiVersion"');
+}
 async function runServe(flags) {
     const wsHost = str(flags['ws-host']) ?? DEFAULT_HOST;
     const wsPort = num(flags['ws-port'], DEFAULT_WS_PORT);
@@ -129,12 +151,7 @@ async function runServe(flags) {
     // Periodic liveness probe so dead tabs that never fired `close` get pruned.
     const heartbeat = setInterval(() => bridge.pingAll(), 30_000);
     heartbeat.unref();
-    console.error(`[etch-connector] bridge   ws://${wsHost}:${boundWsPort}`);
-    console.error(`[etch-connector] control  ${controlBaseUrl({ host: controlHost, port: controlPort })}`);
-    console.error(`[etch-connector] default mode: ${defaultMode}${defaultMode === 'unsafe' ? '  ⚠  scripts get full access to the page' : '  (scripts see only window.etch + JS built-ins)'}`);
-    console.error('[etch-connector] In an Etch builder tab, run:');
-    console.error(`[etch-connector]     etch.connectTo('my-tab'${boundWsPort === DEFAULT_WS_PORT ? '' : `, { port: ${boundWsPort} }`})`);
-    console.error('[etch-connector] then drive it with:  etch-connector eval -t my-tab "return window.etch.apiVersion"');
+    printServeBanner(wsHost, boundWsPort, controlHost, controlPort, defaultMode);
     const shutdown = () => {
         clearInterval(heartbeat);
         control.close();
@@ -149,6 +166,12 @@ function controlUrlFromFlags(flags) {
         port: num(flags['control-port'], DEFAULT_CONTROL_PORT)
     });
 }
+/** Hit a daemon endpoint, turning a connection failure into a friendly error. */
+async function controlFetch(flags, path, init) {
+    return fetch(`${controlUrlFromFlags(flags)}${path}`, init).catch((err) => {
+        throw new Error(`cannot reach the connector daemon — is \`etch-connector serve\` running? (${err})`);
+    });
+}
 /**
  * CDP (Chrome remote-debugging) config when the caller opted in via `--cdp`,
  * `--cdp-port`, `--cdp-host`, or `--remote-debugging-port`; otherwise null.
@@ -219,30 +242,44 @@ function failCdp(err, port = DEFAULT_CDP_PORT) {
     }
     process.exit(1);
 }
-async function runTabs(flags) {
-    const cdp = cdpFromFlags(flags);
-    if (cdp) {
-        const targets = await CdpClient.listTargets(cdp).catch((e) => failCdp(e, cdp.port));
-        if (flags['json']) {
-            process.stdout.write(`${JSON.stringify(targets, null, 2)}\n`);
-            return;
-        }
-        if (targets.length === 0) {
-            console.error('No Chrome page targets open.');
-            return;
-        }
-        for (const t of targets)
-            process.stdout.write(`${t.title}\t${t.url}\n`);
-        return;
+/**
+ * Run a CDP command against the required endpoint (defaulting to localhost:9222
+ * for the CDP-only commands), translating any CDP error into the right exit.
+ */
+async function withRequiredCdp(flags, fn) {
+    const cdp = requireCdp(flags);
+    try {
+        return await withCdp(cdp, str(flags['tab']), fn);
     }
-    const res = await fetch(`${controlUrlFromFlags(flags)}/tabs`).catch((err) => {
-        throw new Error(`cannot reach the connector daemon — is \`etch-connector serve\` running? (${err})`);
-    });
-    const { tabs } = (await res.json());
-    if (flags['json']) {
-        process.stdout.write(`${JSON.stringify(tabs, null, 2)}\n`);
+    catch (err) {
+        failCdp(err, cdp.port);
+    }
+}
+/** Resolve a required CSS selector from `-s/--selector` or the first positional. */
+function requireSelector(command, positional, flags) {
+    const selector = str(flags['selector']) ?? positional[0];
+    if (!selector) {
+        console.error(`${command}: pass a CSS selector (-s/--selector or positional)`);
+        process.exit(1);
+    }
+    return selector;
+}
+async function tabsViaCdp(cdp, flags) {
+    const targets = await CdpClient.listTargets(cdp).catch((e) => failCdp(e, cdp.port));
+    if (flags['json'])
+        return writeJson(targets);
+    if (targets.length === 0) {
+        console.error('No Chrome page targets open.');
         return;
     }
+    for (const t of targets)
+        process.stdout.write(`${t.title}\t${t.url}\n`);
+}
+async function tabsViaDaemon(flags) {
+    const res = await controlFetch(flags, '/tabs');
+    const { tabs } = (await res.json());
+    if (flags['json'])
+        return writeJson(tabs);
     if (tabs.length === 0) {
         console.error('No Etch tabs connected.');
         return;
@@ -251,6 +288,10 @@ async function runTabs(flags) {
         process.stdout.write(`${tab.name}\t${tab.hasEtch ? 'etch' : 'no-etch'}\t${tab.title}\t${tab.url}\n`);
     }
 }
+async function runTabs(flags) {
+    const cdp = cdpFromFlags(flags);
+    return cdp ? tabsViaCdp(cdp, flags) : tabsViaDaemon(flags);
+}
 async function gatherCode(positional, flags) {
     const file = str(flags['file']);
     if (file)
@@ -259,49 +300,52 @@ async function gatherCode(positional, flags) {
         return positional.join(' ');
     return (await readStdin()).trim();
 }
-async function runEval(positional, flags) {
-    const code = await gatherCode(positional, flags);
-    if (!code) {
-        console.error('eval: no script provided (pass code as an argument, --file, or stdin)');
-        process.exit(1);
-    }
-    const timeoutMs = typeof flags['timeout'] === 'string'
+/** `--timeout ms` if given a numeric value, else undefined (daemon default). */
+function timeoutFromFlags(flags) {
+    return typeof flags['timeout'] === 'string'
         ? num(flags['timeout'], 30_000)
         : undefined;
-    // CDP mode: eval over Chrome remote debugging (full window access, no daemon).
-    const cdp = cdpFromFlags(flags);
-    if (cdp) {
-        try {
-            const value = await withCdp(cdp, str(flags['tab']), (c) => c.eval(code, { timeoutMs }));
-            process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
-        }
-        catch (err) {
-            failCdp(err, cdp.port);
-        }
-        return;
-    }
-    // --safe overrides the daemon default; omitting it defers to the daemon.
-    // --unsafe is a dead path (see ALLOW_UNSAFE): it never sets unsafe mode.
-    let mode;
+}
+/**
+ * --safe overrides the daemon default; omitting it defers to the daemon.
+ * --unsafe is a dead path (see ALLOW_UNSAFE): it never sets unsafe mode.
+ */
+function resolveEvalMode(flags) {
     if (ALLOW_UNSAFE && flags['unsafe'])
-        mode = 'unsafe';
-    else if (flags['safe'])
-        mode = 'safe';
+        return 'unsafe';
+    if (flags['safe'])
+        return 'safe';
+    return undefined;
+}
+/** Forwarded console output → stderr, so stdout stays clean for the value. */
+function printForwardedLogs(logs) {
+    for (const log of logs) {
+        const text = log.args
+            .map((a) => (typeof a === 'string' ? a : JSON.stringify(a)))
+            .join(' ');
+        console.error(`[${log.level}] ${text}`);
+    }
+}
+// CDP mode: eval over Chrome remote debugging (full window access, no daemon).
+async function evalViaCdp(cdp, flags, code, timeoutMs) {
+    try {
+        const value = await withCdp(cdp, str(flags['tab']), (c) => c.eval(code, { timeoutMs }));
+        writeJson(value);
+    }
+    catch (err) {
+        failCdp(err, cdp.port);
+    }
+}
+async function evalViaDaemon(flags, code, timeoutMs) {
+    const mode = resolveEvalMode(flags);
     if (mode === 'unsafe') {
         console.error('⚠  running in unsafe mode — the script has full access to the page');
     }
-    const body = {
-        tab: str(flags['tab']),
-        code,
-        timeoutMs,
-        mode
-    };
-    const res = await fetch(`${controlUrlFromFlags(flags)}/eval`, {
+    const body = { tab: str(flags['tab']), code, timeoutMs, mode };
+    const res = await controlFetch(flags, '/eval', {
         method: 'POST',
         headers: { 'content-type': 'application/json' },
         body: JSON.stringify(body)
-    }).catch((err) => {
-        throw new Error(`cannot reach the connector daemon — is \`etch-connector serve\` running? (${err})`);
     });
     if (!res.ok) {
         const err = (await res.json().catch(() => ({})));
@@ -309,82 +353,61 @@ async function runEval(positional, flags) {
         process.exit(1);
     }
     const result = (await res.json());
-    // Forwarded console output → stderr, so stdout stays clean for the value.
-    for (const log of result.logs) {
-        const text = log.args
-            .map((a) => (typeof a === 'string' ? a : JSON.stringify(a)))
-            .join(' ');
-        console.error(`[${log.level}] ${text}`);
-    }
+    printForwardedLogs(result.logs);
     if (!result.ok) {
         console.error(`script error: ${result.error}`);
         if (result.stack)
             console.error(result.stack);
         process.exit(2);
     }
-    process.stdout.write(`${JSON.stringify(result.value, null, 2)}\n`);
+    writeJson(result.value);
+}
+async function runEval(positional, flags) {
+    const code = await gatherCode(positional, flags);
+    if (!code) {
+        console.error('eval: no script provided (pass code as an argument, --file, or stdin)');
+        process.exit(1);
+    }
+    const timeoutMs = timeoutFromFlags(flags);
+    const cdp = cdpFromFlags(flags);
+    return cdp
+        ? evalViaCdp(cdp, flags, code, timeoutMs)
+        : evalViaDaemon(flags, code, timeoutMs);
 }
 /** `shot` / `html` / `computed` are CDP-only; default to localhost:9222. */
 function requireCdp(flags) {
     return (cdpFromFlags(flags) ?? { host: DEFAULT_HOST, port: DEFAULT_CDP_PORT });
 }
 async function runShot(flags) {
-    const cdp = requireCdp(flags);
     const selector = str(flags['selector']);
     const full = Boolean(flags['full']);
     const format = flags['jpeg'] ? 'jpeg' : 'png';
     const freeze = bool(flags['freeze'], true); // default on (animations → deterministic)
     const out = str(flags['out']) ?? `etch-shot.${format === 'jpeg' ? 'jpg' : 'png'}`;
-    try {
-        const buf = await withCdp(cdp, str(flags['tab']), (c) => c.screenshot({ selector, full, format, freeze }));
-        writeFileSync(out, buf);
-        const scope = selector
-            ? ` — clipped to ${selector}`
-            : full
-                ? ' — full page'
-                : ' — viewport';
-        console.error(`wrote ${out} (${buf.length} bytes)${scope}${freeze ? ' (frozen)' : ''}`);
-    }
-    catch (err) {
-        failCdp(err, cdp.port);
-    }
+    const buf = await withRequiredCdp(flags, (c) => c.screenshot({ selector, full, format, freeze }));
+    writeFileSync(out, buf);
+    const scope = selector
+        ? ` — clipped to ${selector}`
+        : full
+            ? ' — full page'
+            : ' — viewport';
+    console.error(`wrote ${out} (${buf.length} bytes)${scope}${freeze ? ' (frozen)' : ''}`);
 }
 async function runHtml(positional, flags) {
-    const selector = str(flags['selector']) ?? positional[0];
-    if (!selector) {
-        console.error('html: pass a CSS selector (-s/--selector or positional)');
-        process.exit(1);
-    }
-    const cdp = requireCdp(flags);
-    try {
-        const html = await withCdp(cdp, str(flags['tab']), (c) => c.outerHtml(selector));
-        process.stdout.write(`${html}\n`);
-    }
-    catch (err) {
-        failCdp(err, cdp.port);
-    }
+    const selector = requireSelector('html', positional, flags);
+    const html = await withRequiredCdp(flags, (c) => c.outerHtml(selector));
+    process.stdout.write(`${html}\n`);
 }
 async function runComputed(positional, flags) {
-    const selector = str(flags['selector']) ?? positional[0];
-    if (!selector) {
-        console.error('computed: pass a CSS selector (-s/--selector or positional)');
-        process.exit(1);
-    }
+    const selector = requireSelector('computed', positional, flags);
     const props = str(flags['props'])
         ?.split(',')
         .map((p) => p.trim())
         .filter(Boolean);
-    const cdp = requireCdp(flags);
-    try {
-        const style = await withCdp(cdp, str(flags['tab']), (c) => c.computedStyle(selector, props));
-        process.stdout.write(`${JSON.stringify(style, null, 2)}\n`);
-    }
-    catch (err) {
-        failCdp(err, cdp.port);
-    }
+    const style = await withRequiredCdp(flags, (c) => c.computedStyle(selector, props));
+    writeJson(style);
 }
-function printHelp() {
-    console.error(`etch-connector — drive a live Etch tab from the command line
+const HELP_TEXT = `etch-connector — drive a live Etch tab from the command line
 
 Run without installing (requires a valid, active Etch license):
   npx @digital-gravy/etch-connector serve
@@ -403,7 +426,7 @@ Usage:
   etch-connector computed  <selector> [-t name] [--props a,b,c]                               (CDP)
 
 Two backends:
-  bridge  (default) the tab dials in via etch.connectTo(); page-sandboxed.
+  bridge  (default) the tab dials in via etch.connectAs(); page-sandboxed.
           Scripts see only "etch" + the standard JS built-ins.
   cdp     connect OUT to a Chrome started with --remote-debugging-port=${DEFAULT_CDP_PORT}.
           No daemon. Runs at DevTools privilege: full "window", plus screenshots,
@@ -414,6 +437,17 @@ AGENT: before running anything, ask the user how they want to connect — bridge
 (API only) or cdp (DevTools privilege: full page access). cdp grants more reach;
 don't assume — let the user choose.
 
+Connecting a bridge tab (AGENT: walk the user through activating it — the AI
+button is the primary path; don't just wait for a tab to appear):
+  1. Tell them to open Etch Settings and enable the AI Connector.
+  2. Tell them to open a builder page and click the AI button in the left
+     sidebar — it connects the tab and registers it under the site name (calls
+     connectAs under the hood); clicking it again disconnects.
+  Fallback — they can connect from the browser console:
+     etch.connectAs('homepage')   (add { port: <n> } for a non-default WS port)
+  cdp needs no connect step — start Chrome with --remote-debugging-port and
+    target a tab with -t.
+
 Examples:
   etch-connector serve
   etch-connector tabs
@@ -430,6 +464,31 @@ The eval body runs as an async function, so it may 'return' a value and use
 top-level 'await'. In bridge mode reference the API as "etch.*" ("window" is
 withheld); in cdp mode the full page is available.
 
+AI presence (AGENT: drive the etch.ai overlay so the human watching the tab
+sees an agent is active — this connector is exactly what etch.ai is built for.
+This overlay is for the human, NOT the user you're chatting with: NEVER mention
+it, narrate it, or explain these state changes — just keep it accurate):
+  etch.ai.setState(state)  shows/updates the presence overlay in the builder.
+  etch.ai.getState()       reads the current state.
+  etch.ai.hide()           removes the overlay (shorthand for setState("idle")).
+  state is one of: "idle" (overlay hidden), "thinking" (reasoning before acting),
+    "working" (a script is actually running against the canvas), "waiting"
+    (paused, needs more input from the human). Any other value throws
+    EtchApiError INVALID_ARGUMENT. Calls are synchronous, in-memory, and NOT
+    persisted — no saveAsync, nothing survives a reload.
+  When to set what:
+    • The MOMENT a user asks you to build/change something — before reading docs,
+      writing scripts, or any other step — put the overlay up: setState('thinking').
+    • setState('thinking') while you reason/plan (no script running yet).
+    • setState('working') right before an eval actually runs against the canvas;
+      back to 'thinking' between scripts if you pause to reason.
+    • hide() the instant the task is finished — never leave it up on completion.
+    • setState('waiting') ONLY when you are NOT done and are handing back to the
+      human for input/a decision; resume 'thinking'/'working' when they reply.
+    Wrap script runs in try/finally so an error still leaves the right state:
+        etch.ai.setState('working');
+        try { /* …drive the builder… */ } finally { etch.ai.setState('thinking'); }
+
 Docs (AGENT: pull these BEFORE writing scripts against etch.* — the API surface
 changes and training data may be stale):
   Context7 MCP (preferred)  resolve-library-id "Etch" → query-docs for the
@@ -437,6 +496,9 @@ changes and training data may be stale):
   Manual fallback           https://docs.etchwp.com/public-api (window.etch.*)
                             https://docs.etchwp.com (everything else)
 
+Skills (AGENT: the public API may expose ready-made skills for common tasks —
+  check the docs before improvising).
+
 Building Etch pages (AGENT: conventions — follow these or the builder won't
 render what you author):
   Images. ALWAYS use the Dynamic Image element (etch/dynamic-image, <etch:img>),
@@ -482,7 +544,9 @@ render what you author):
       (rest_route form works on plain permalinks; /wp-json/wp/v2/media on pretty
       ones.)
 
-See AGENTS.md for project conventions.`);
+See AGENTS.md for project conventions.`;
+function printHelp() {
+    console.error(HELP_TEXT);
 }
 async function main() {
     const { command, positional, flags } = parseArgs(process.argv.slice(2));

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@digital-gravy/etch-connector",
-	"version": "0.1.3",
+	"version": "0.1.5",
 	"publishConfig": {
 		"access": "public"
 	},

package/dist/manual.js

@@ -1,2 +0,0 @@
-// AUTO-GENERATED from README.md by scripts/build-manual.mjs — do not edit by hand.
-export const MANUAL = "# etch-connector\n\nA tiny local bridge that lets an AI harness — Claude Code, Cowork, or any tool\nthat can run a shell command — **drive a live Etch builder tab** by evaluating\nscripts against the [`etch-public-api`](https://www.npmjs.com/package/@digital-gravy/etch-public-api)\nsurface (`window.etch.*`).\n\nEtch's scriptable API only exists *inside the browser*. There is no server you\ncan call directly. So this connector inverts the usual direction: the browser\n**dials out** to the connector over a WebSocket (the same way Chrome remote\ndebugging works, but in reverse), and the connector relays scripts into the tab\nand streams the result back.\n\n```\nClaude Code / Cowork\n      │  shell:  etch-connector eval -t homepage \"return ...\"\n      ▼\n  etch-connector  (the `serve` daemon)\n      │  ▲   WebSocket  (tab dials in via etch.connectTo)\n      ▼  │\n  Etch builder tab  ──►  window.etch.*\n```\n\n## Status\n\nThis is an **eval relay**: the harness sends a JavaScript snippet, the page runs\nit as an async function, and the return value + console output come back. It is\nintentionally *not* an MCP server yet, but it is built so that becoming one is a\nthin add — see [Going to MCP](#going-to-mcp-later).\n\nScripts run in one of two modes, enforced by the page:\n\n- **`safe`** (default) — the script sees only `etch` and the standard JS\n  built-ins. `window`, `document`, `fetch`, storage, `eval`, … are withheld.\n- **`unsafe`** — the script runs with full access to the page. Opt in\n  explicitly.\n\n## Install\n\n```bash\nbun install   # or npm install\n```\n\n## Use\n\n### 1. Start the daemon (once)\n\n```bash\nbun run serve\n# bridge   ws://127.0.0.1:7331\n# control  http://127.0.0.1:7332\n```\n\n### 2. Connect a tab\n\nOpen an Etch builder page and, in the browser console:\n\n```js\netch.connectTo('homepage');\n```\n\n(`connectTo` is part of the public API; it opens the WebSocket back to the\ndaemon and registers this tab under the given name. Pass `{ port: <n> }` if you\nstarted the daemon on a non-default WebSocket port.)\n\n### 3. Drive it\n\n```bash\n# list connected tabs\netch-connector tabs\n\n# run a script (value → stdout, console output → stderr).\n# Default is safe mode: reference the API as `etch.*`.\netch-connector eval -t homepage \"return etch.apiVersion\"\n\n# multi-line / from a file / from stdin\netch-connector eval -t homepage -f ./script.js\necho \"return await etch.blocks.getTree()\" | etch-connector eval -t homepage\n\n# full page access (opt in)\netch-connector eval -t homepage --unsafe \"return document.title\"\n```\n\nThe script body runs as an **async function**, so it can `return` a value and\nuse top-level `await`. In safe mode write scripts against the `etch-public-api`\nsurface via the `etch` binding (`window` is not available). Examples:\n\n```js\nreturn etch.apiVersion;\nreturn await etch.blocks.getTree();\netch.blocks.select('block-id-123');\nconst groups = await etch.fields.listGroupsAsync();\nreturn groups.length;\n```\n\n### Modes\n\n| Mode            | In scope                              | Use for                          |\n| --------------- | ------------------------------------- | -------------------------------- |\n| `safe` (default)| `etch` + standard JS built-ins        | Driving the builder via the API  |\n| `unsafe`        | everything (`window`, `document`, …)  | Debugging, page internals        |\n\nPick per call with `--safe` / `--unsafe`, or change the daemon default with\n`serve --unsafe`. A per-call flag overrides the daemon default.\n\n### Output contract (for agents)\n\n`eval` keeps stdout clean so a harness can capture it as the result:\n\n- **stdout** — the script's return value, as pretty JSON.\n- **stderr** — forwarded `console.*` output, prefixed with the level.\n- **exit code** — `0` success · `2` the script threw · `1` operational failure\n  (no such tab, ambiguous target, timeout, daemon unreachable).\n\n## CLI\n\n```\netch-connector serve [--ws-port 7331] [--control-port 7332] [--ws-host 127.0.0.1] [--unsafe]\netch-connector tabs  [--json] [--control-port 7332]\netch-connector eval  [code] [-t|--tab name] [-f|--file path] [--timeout ms] [--safe|--unsafe]\n```\n\nWhen exactly one tab is connected, `-t` is optional. With several tabs you must\nname one.\n\n## HTTP control API\n\nThe daemon also exposes a loopback HTTP API (this is the seam the CLI uses, and\nthe same one a future MCP server would call):\n\n| Method | Path      | Body                                 | Returns      |\n| ------ | --------- | ------------------------------------ | ------------ |\n| GET    | `/health` | —                                    | `{ ok }`     |\n| GET    | `/tabs`   | —                                    | `{ tabs }`   |\n| POST   | `/eval`   | `{ tab?, code, timeoutMs?, mode? }`  | `EvalResult` |\n\n## Architecture\n\n- [`src/protocol.ts`](src/protocol.ts) — the wire format, mirrored from the\n  Etch-side `bridge.ts`. Keep the two in sync.\n- [`src/bridge-server.ts`](src/bridge-server.ts) — `BridgeServer`, the\n  transport-agnostic core: owns the sockets, tracks tabs by name, correlates\n  requests, handles timeouts and disconnects. **This is the reusable piece.**\n- [`src/control-server.ts`](src/control-server.ts) — the HTTP control API over\n  the core.\n- [`src/cli.ts`](src/cli.ts) — the `serve` / `tabs` / `eval` commands.\n\n## Going to MCP later\n\nNothing in the transport changes. An MCP server is `new BridgeServer()` plus two\ntool definitions over the same core:\n\n```ts\nimport { BridgeServer } from 'etch-connector';\n\nconst bridge = new BridgeServer();\nawait bridge.listen();\n\n// list_etch_tabs   -> bridge.listTabs()\n// eval_etch_script -> bridge.evalInTab(code, { tab })\n```\n\nWhen you want first-class per-tool MCP tools (rather than one eval tool), have\nthe Etch tab advertise a tool manifest in its `hello` and register those\ndynamically — keeping a single source of truth in the browser registry.\n\n## Security\n\nTwo layers, neither a substitute for the other:\n\n**Transport.** Everything binds to `127.0.0.1`, so any local process can reach\nthe daemon. Run it only on a trusted machine and do not expose the ports beyond\nloopback.\n\n**Execution.** `safe` mode (the default) runs the script inside a `with`-bound\nProxy that exposes only `etch` plus the standard JS built-ins and throws on\n`window`, `document`, `fetch`, storage, `eval`, `Function`, … This is a\n**guardrail, not a hardened sandbox**: because the script shares the page's JS\nrealm, a *determined* author can still reach globals through prototype /\nconstructor chains (e.g. `({}).constructor.constructor`). Safe mode reliably\nkeeps casual and AI-authored scripts on the `etch` surface and closes the\nobvious escape hatches; it does **not** contain hostile code.\n\n`unsafe` mode runs the script with full, unconstrained access to the page — only\nuse it for trusted debugging.\n\nFor a true boundary against adversarial scripts you would need to harden the\nrealm (SES `lockdown()`), which freezes all intrinsics app-wide and is out of\nscope for this relay. The enforcement lives in the Etch page (`bridge.ts`), not\nthis connector — the connector only carries the requested mode; a string filter\nhere would be theater.\n";