@digital-gravy/etch-connector 0.1.4 → 0.2.0

package/README.md

@@ -122,18 +122,31 @@ return groups.length;
 `eval` keeps stdout clean so a harness can capture it as the result:
 
 - **stdout** — the script's return value, as pretty JSON.
-- **stderr** — forwarded `console.*` output, prefixed with the level.
+- **stderr** — forwarded `console.*` output, prefixed with the level, plus
+  connector notes that carry no such prefix (the runtime banner, warnings).
 - **exit code** — `0` success · `2` the script threw · `1` operational failure
   (no such tab, ambiguous target, timeout, daemon unreachable).
 
 ## For AI agents
 
+`etch-connector tabs` reports, per tab, which Etch runtime it is and which
+surfaces that runtime backs (read off `etch.environment`), then prints the
+authoring rules that follow from it: the dynamic-data model (data sources vs
+loops), the media lookup, the namespaces that throw `NOT_AVAILABLE`, and the
+block types the runtime can construct. Not every runtime backs every surface, so
+read that before writing scripts — and branch on a capability, never on the
+product name. `eval` names the runtime it targets on stderr as a reminder, and
+`tabs --quiet` drops the prose when you are only checking that a tab is still
+connected.
+
 The authoritative agent instructions live in **`etch-connector --help`** — read
 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
 
@@ -142,7 +155,7 @@ etch-connector — drive a live Etch tab from the command line
 
 Usage:
   etch-connector serve [--ws-port 7331] [--control-port 7332] [--ws-host 127.0.0.1]
-  etch-connector tabs  [--json] [--control-port 7332] [--cdp]
+  etch-connector tabs  [--json] [--quiet] [--control-port 7332] [--cdp]
   etch-connector eval  [code] [-t|--tab name] [-f|--file path] [--timeout ms] [--cdp]
   etch-connector shot      [-t name] [-s|--selector css] [--full] [--jpeg] [-o|--out file] [--freeze=false]   (CDP)
   etch-connector html      <selector> [-t name]                                              (CDP)
@@ -192,6 +205,8 @@ the same one a future MCP server would call):
   requests, handles timeouts and disconnects. **This is the reusable piece.**
 - [`src/control-server.ts`](src/control-server.ts) — the HTTP control API over
   the core.
+- [`src/guidance.ts`](src/guidance.ts) — turns a tab's `etch.environment`
+  descriptor into the authoring instructions for that runtime.
 - [`src/cli.ts`](src/cli.ts) — the `serve` / `tabs` / `eval` commands.
 
 ## Going to MCP later

package/dist/bridge-server.js

@@ -14,7 +14,7 @@
 import { EventEmitter } from 'node:events';
 import { randomUUID } from 'node:crypto';
 import { WebSocketServer } from 'ws';
-import { DEFAULT_HOST, DEFAULT_WS_PORT, parsePageMessage } from './protocol.js';
+import { DEFAULT_HOST, DEFAULT_WS_PORT, parseEnvironment, parsePageMessage } from './protocol.js';
 const DEFAULT_TIMEOUT_MS = 30_000;
 /**
  * Raised for operational failures (no matching tab, ambiguous target, timeout,
@@ -208,6 +208,7 @@ export class BridgeServer extends EventEmitter {
             hasEtch: hello.hasEtch,
             apiVersion: hello.apiVersion,
             version: hello.version,
+            environment: parseEnvironment(hello.environment),
             meta: hello.meta ?? {},
             connectedAt: Date.now()
         };

package/dist/cli.js

@@ -7,8 +7,9 @@
  *   etch-connector tabs             list connected Etch tabs
  *   etch-connector eval [code]      run a script in a tab; value → stdout
  *
- * `eval` prints forwarded console output to *stderr* and the script's return
- * value as JSON to *stdout*, so an agent can capture stdout as the clean result.
+ * `eval` prints forwarded console output to *stderr* — alongside unprefixed
+ * connector notes such as the runtime banner — and the script's return value as
+ * JSON to *stdout*, so an agent can capture stdout as the clean result.
  * Exit codes: 0 ok · 2 the script threw · 1 everything else (no tab, timeout…).
  */
 import { readFileSync, writeFileSync } from 'node:fs';
@@ -16,6 +17,7 @@ import { BridgeServer } from './bridge-server.js';
 import { createControlServer, controlBaseUrl } from './control-server.js';
 import { CdpClient, CdpError, CdpEvalError } from './cdp-client.js';
 import { DEFAULT_CONTROL_PORT, DEFAULT_HOST, DEFAULT_WS_PORT } from './protocol.js';
+import { backedCapabilities, environmentGuidance, runtimeBanner } from './guidance.js';
 const DEFAULT_CDP_PORT = 9222;
 /**
  * Unsafe mode (scripts get full, unconstrained access to the page) is
@@ -31,54 +33,64 @@ const BOOLEAN_FLAGS = new Set([
     'full',
     'jpeg',
     'json',
+    'quiet',
     'unsafe',
     'safe',
     '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 +117,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 +129,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 +154,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.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"');
+    printServeBanner(wsHost, boundWsPort, controlHost, controlPort, defaultMode);
     const shutdown = () => {
         clearInterval(heartbeat);
         control.close();
@@ -149,6 +169,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,37 +245,85 @@ 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`);
+}
+/** The runtime column: what the tab is and which surfaces it actually backs. */
+function describeRuntime(tab) {
+    if (!tab.hasEtch)
+        return 'no-etch';
+    if (!tab.environment)
+        return 'etch';
+    const backed = backedCapabilities(tab.environment);
+    return `${tab.environment.product}(${backed.join(',') || 'none'})`;
+}
+/**
+ * Instructions for the runtimes actually on the wire, to stderr so stdout stays
+ * the plain listing. Tabs sharing a runtime share one block — an agent needs the
+ * guidance once per runtime, not once per tab.
+ */
+function printRuntimeGuidance(tabs) {
+    const byRuntime = new Map();
+    for (const tab of tabs.filter((t) => t.hasEtch)) {
+        const guidance = environmentGuidance(tab.environment);
+        const names = byRuntime.get(guidance) ?? [];
+        names.push(tab.name);
+        byRuntime.set(guidance, names);
+    }
+    for (const [guidance, names] of byRuntime) {
+        console.error(`\nAGENT — authoring against ${names.join(', ')}:`);
+        console.error(guidance);
+    }
+}
+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;
     }
     for (const tab of tabs) {
-        process.stdout.write(`${tab.name}\t${tab.hasEtch ? 'etch' : 'no-etch'}\t${tab.title}\t${tab.url}\n`);
+        process.stdout.write(`${tab.name}\t${describeRuntime(tab)}\t${tab.title}\t${tab.url}\n`);
     }
+    // `tabs` doubles as the liveness check, so let a poller opt out of the prose.
+    if (!flags['quiet'])
+        printRuntimeGuidance(tabs);
+}
+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']);
@@ -259,132 +333,148 @@ 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);
+    }
+}
+/**
+ * Which tab an eval will land on, mirroring the daemon's own resolution: a named
+ * tab (most recently connected wins), or the only one connected. Anything the
+ * daemon would reject resolves to nothing — the eval reports that itself.
+ */
+function resolveTargetTab(tabs, name) {
+    if (name === undefined)
+        return tabs.length === 1 ? tabs[0] : undefined;
+    return tabs
+        .filter((tab) => tab.name === name)
+        .sort((a, b) => b.connectedAt - a.connectedAt)[0];
+}
+/**
+ * Name the runtime this eval targets, on stderr. Best-effort: a listing we
+ * cannot fetch or a target we cannot pin down just means no banner — never a
+ * failed eval.
+ */
+async function announceTargetRuntime(flags) {
+    try {
+        const res = await controlFetch(flags, '/tabs');
+        if (!res.ok)
+            return;
+        const { tabs } = (await res.json());
+        const target = resolveTargetTab(tabs, str(flags['tab']));
+        if (target)
+            console.error(runtimeBanner(target.environment));
+    }
+    catch {
+        /* the eval itself reports anything that actually matters */
+    }
+}
+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`, {
+    // Started before the eval so naming the runtime costs no wall-clock.
+    const announced = announceTargetRuntime(flags);
+    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})`);
     });
+    await announced;
     if (!res.ok) {
         const err = (await res.json().catch(() => ({})));
         console.error(`eval failed: ${err.error ?? res.statusText}`);
         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
@@ -396,7 +486,7 @@ Or install globally for the bare \`etch-connector\` command:
 
 Usage:
   etch-connector serve [--ws-port ${DEFAULT_WS_PORT}] [--control-port ${DEFAULT_CONTROL_PORT}] [--ws-host ${DEFAULT_HOST}]
-  etch-connector tabs  [--json] [--control-port ${DEFAULT_CONTROL_PORT}] [--cdp]
+  etch-connector tabs  [--json] [--quiet] [--control-port ${DEFAULT_CONTROL_PORT}] [--cdp]
   etch-connector eval  [code] [-t|--tab name] [-f|--file path] [--timeout ms] [--cdp]
   etch-connector shot      [-t name] [-s|--selector css] [--full] [--jpeg] [-o|--out file] [--freeze=false]   (CDP)
   etch-connector html      <selector> [-t name]                                              (CDP)
@@ -414,6 +504,15 @@ 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.
 
+AGENT: \`etch-connector tabs\` prints, per connected tab, which runtime it is and
+which surfaces that runtime backs (from \`etch.environment\`), followed by the
+authoring rules for it — the dynamic-data model, the media lookup, the
+namespaces that throw, and the block types it can construct. Read that before
+writing scripts: not every runtime backs every surface, so the same script does
+not work everywhere. Branch on a capability, never on the product name.
+(\`eval\` names the runtime it targets on stderr as a reminder; \`tabs --quiet\`
+drops the prose when you are only checking a tab is still connected.)
+
 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.
@@ -441,6 +540,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
@@ -448,6 +572,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>),
@@ -488,12 +615,17 @@ render what you author):
           etch.blocks.update(instanceId, { attributes: { image: "10" } })
     • updateAsync({ blocks }) requires styles:[] on every element block
       (validation differs from blocks.create(), which omits styles entirely).
-    • No etch.media API. Resolve a URL → media ID via the WP REST API:
+    • No etch.media API. Where the runtime backs the WordPress media library
+      (capability \`wpMedia\` — see \`tabs\`), resolve a URL → media ID via the WP
+      REST API:
           curl 'http://<site>/?rest_route=/wp/v2/media&per_page=100&_fields=id,source_url'
       (rest_route form works on plain permalinks; /wp-json/wp/v2/media on pretty
-      ones.)
+      ones.) Without it the ids are the product's own asset store and there is
+      nothing to look a URL up against.
 
-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/dist/guidance.js

@@ -0,0 +1,129 @@
+/**
+ * Turns a tab's `etch.environment` descriptor into the instructions for
+ * authoring against *that* runtime.
+ *
+ * The two dynamic-data models are mutually exclusive and are authored
+ * differently, the media lookup depends on whether WordPress is underneath, and
+ * several namespaces are declared everywhere but backed only somewhere — so a
+ * script written for one product silently produces nothing on the other. This
+ * is what turns the descriptor from something the connector relays into
+ * something it acts on.
+ *
+ * Every branch keys off {@link hasCapability}, never `product`: capabilities
+ * move between products, and a product check rots the day one does.
+ */
+import { hasCapability } from './protocol.js';
+/** Namespaces that are declared on every runtime but backed only on some. */
+const GATED_NAMESPACES = [
+    { capability: 'loops', namespace: 'etch.loops.*' },
+    { capability: 'fields', namespace: 'etch.fields.*' },
+    { capability: 'templates', namespace: "etch.navigation.goTo('templates')" }
+];
+const UNKNOWN_RUNTIME = [
+    'Runtime: not reported — this Etch predates etch.environment, so what follows',
+    '  is an ASSUMPTION, not a reading of the runtime: WordPress rules (loops,',
+    '  fields, templates, WP media), and every block type may exist. Confirm with',
+    '  the user before relying on it — a non-WordPress runtime throws on most of',
+    '  that.'
+];
+function dynamicDataGuidance(environment) {
+    if (hasCapability(environment, 'dataSources')) {
+        return [
+            'Dynamic data — data sources. Named project sources (json, api, js) are',
+            "  reached through a data('key') expression. An etch/loop block carries",
+            '  ONLY a required `target`, and that target is any dynamic expression',
+            "  yielding a list: data('products'), a path into one",
+            "  (data('products').items), nested data from an enclosing loop",
+            '  (item.tags), or a generated list (range(1, 10)). There is no',
+            '  loopId/loopParams here.'
+        ];
+    }
+    if (hasCapability(environment, 'loops')) {
+        return [
+            'Dynamic data — loops. etch.loops.* is a registry of named loop',
+            '  definitions. An etch/loop block binds one by `loopId`, passes',
+            '  $-prefixed `loopParams`, and `target` is an optional sub-path within',
+            "  it. There are no data sources here — a data('key') expression",
+            '  resolves to nothing.'
+        ];
+    }
+    return [
+        'Dynamic data: unavailable. This runtime backs neither loops nor data',
+        '  sources — do not author etch/loop blocks against it.'
+    ];
+}
+function mediaGuidance(environment) {
+    const binding = '  Bind an etch/dynamic-image by a numeric `mediaId` attribute, never a URL.';
+    if (hasCapability(environment, 'wpMedia')) {
+        return [
+            'Media — the WordPress library. Media ids resolve against /wp/v2/media, so',
+            '  a URL can be looked up:',
+            "    curl '<site>/?rest_route=/wp/v2/media&per_page=100&_fields=id,source_url'",
+            binding
+        ];
+    }
+    return [
+        "Media — this runtime's own asset store, NOT the WordPress library:",
+        '  /wp/v2/media does not apply and there is nothing to look a URL up against.',
+        binding
+    ];
+}
+function unavailableGuidance(environment) {
+    const throwing = GATED_NAMESPACES.filter((gated) => !hasCapability(environment, gated.capability)).map((gated) => gated.namespace);
+    if (throwing.length === 0)
+        return [];
+    return [
+        'Throws EtchApiError NOT_AVAILABLE here — do not call:',
+        `  ${throwing.join(', ')}`
+    ];
+}
+function blockTypeGuidance(environment) {
+    if (environment.blockTypes.length === 0)
+        return [];
+    return [
+        'Block types this runtime can construct — author nothing outside this list:',
+        `  ${environment.blockTypes.join(', ')}`
+    ];
+}
+/** Which capabilities a runtime actually backs, for a one-line summary. */
+export function backedCapabilities(environment) {
+    return Object.entries(environment.capabilities)
+        .filter(([, backed]) => backed === true)
+        .map(([capability]) => capability)
+        .sort();
+}
+/**
+ * One stderr line naming the runtime a script is about to run against.
+ *
+ * `tabs` is where the full instructions live, but `-t` is optional with a single
+ * tab connected — so an agent can go straight to `eval` and never see them. This
+ * is the line that keeps that agent from silently authoring for the wrong
+ * product, and points at where the rules are.
+ */
+export function runtimeBanner(environment) {
+    if (!environment) {
+        return '[etch] runtime reports no capabilities — assuming WordPress; confirm before relying on it';
+    }
+    const backed = backedCapabilities(environment);
+    return (`[${environment.product}] backs ${backed.join(', ') || 'no optional surface'}` +
+        " — run 'etch-connector tabs' for the authoring rules");
+}
+/**
+ * Agent-facing instructions for one runtime. An absent descriptor is a runtime
+ * too old to report one, which is always a WordPress build.
+ */
+export function environmentGuidance(environment) {
+    if (!environment)
+        return UNKNOWN_RUNTIME.join('\n');
+    const backed = backedCapabilities(environment);
+    const sections = [
+        [
+            `Runtime: ${environment.product} — backs ${backed.length > 0 ? backed.join(', ') : 'no optional surface'}.`
+        ],
+        dynamicDataGuidance(environment),
+        mediaGuidance(environment),
+        unavailableGuidance(environment),
+        blockTypeGuidance(environment)
+    ].filter((section) => section.length > 0);
+    return sections.map((section) => section.join('\n')).join('\n');
+}

package/dist/index.js

@@ -9,3 +9,5 @@
 export { BridgeServer, BridgeError } from './bridge-server.js';
 export { createControlServer, controlBaseUrl } from './control-server.js';
 export { DEFAULT_WS_PORT, DEFAULT_CONTROL_PORT, DEFAULT_HOST } from './protocol.js';
+export { hasCapability, parseEnvironment } from './protocol.js';
+export { backedCapabilities, environmentGuidance, runtimeBanner } from './guidance.js';

package/dist/protocol.js

@@ -10,6 +10,48 @@
  *   server → page :  EvalRequest | PingMessage
  *   page → server :  HelloMessage | LogMessage | ResultMessage | ErrorMessage | PongMessage
  */
+/** Every optional surface a runtime may or may not back. */
+const CAPABILITY_NAMES = [
+    'loops',
+    'dataSources',
+    'fields',
+    'templates',
+    'wpMedia'
+];
+/** Whether a runtime backs a capability. Absent or unknown counts as no. */
+export function hasCapability(environment, capability) {
+    return environment?.capabilities[capability] === true;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+/**
+ * Narrow an `environment` off the wire. The page is untrusted input, so a
+ * malformed descriptor becomes `undefined` (treated as "runtime too old to
+ * report one") rather than propagating a broken shape.
+ */
+export function parseEnvironment(value) {
+    if (!isRecord(value))
+        return undefined;
+    const { product, capabilities, blockTypes } = value;
+    if (typeof product !== 'string')
+        return undefined;
+    if (!isRecord(capabilities))
+        return undefined;
+    if (!Array.isArray(blockTypes))
+        return undefined;
+    const known = {};
+    for (const name of CAPABILITY_NAMES) {
+        const flag = capabilities[name];
+        if (typeof flag === 'boolean')
+            known[name] = flag;
+    }
+    return {
+        product,
+        capabilities: known,
+        blockTypes: blockTypes.filter((type) => typeof type === 'string')
+    };
+}
 /** Default WebSocket port the Etch bridge dials (`ws://127.0.0.1:7331`). */
 export const DEFAULT_WS_PORT = 7331;
 /** Default HTTP control-API port the CLI / AI harness talks to. */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@digital-gravy/etch-connector",
-	"version": "0.1.4",
+	"version": "0.2.0",
 	"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";