@digital-gravy/etch-connector 0.1.3 → 0.1.4

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.)
 
@@ -144,7 +149,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 +196,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 +216,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

@@ -133,7 +133,7 @@ async function runServe(flags) {
     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]     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"');
     const shutdown = () => {
         clearInterval(heartbeat);
@@ -403,7 +403,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 +414,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

package/package.json

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