@digital-gravy/etch-connector 0.1.2 → 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
@@ -437,7 +448,23 @@ changes and training data may be stale):
   Manual fallback           https://docs.etchwp.com/public-api (window.etch.*)
                             https://docs.etchwp.com (everything else)
 
-Building Etch pages (AGENT: conventions for structuring content):
+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>),
+    NEVER a plain etch/element with tag "img". Bind it by WP media ID, not a URL:
+        attributes: { mediaId: "{props.image}", useSrcSet: "true", alt: "{props.name}" }
+    The backing prop must be a Media prop, not a text prop:
+        type: { primitive: "string", specialized: "wpMediaId" }
+    (specialized "image" is the URL-based picker — NOT for mediaId.) Instances
+    then pass the numeric media ID, e.g. image: "10" — not the file URL.
+
+  Classes. A block's classes ARE its read-only \`styles\` array, not an HTML
+    attribute. Setting attributes.class in authored JSON is silently dropped, and
+    \`styles\` is rejected on authoring. Assign classes with etch.blocks.addClass()
+    — for component blocks, inside enterComponentEditMode() →
+    saveComponentEditModeAsync() → exitComponentEditMode(). An existing class
+    name re-links to its style record automatically (styling is preserved).
+
   Sections. When you create a top-level section, always tag it
     data-etch-element="section" and nest ONE container inside it as its inner —
     a div block with data-etch-element="container" — and put the section's
@@ -453,6 +480,19 @@ Building Etch pages (AGENT: conventions for structuring content):
     side padding, or inter-section margins — the pair already handles layout
     structure, spacing, and content width.
 
+  Gotchas.
+    • NEVER call etch.*.saveAsync (or otherwise persist) unless the user
+      explicitly asks to save — authored changes stay in the builder until then.
+    • Component instance props are attributes: set them at create()/replace()
+      time, or update an existing instance in place with
+          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:
+          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.)
+
 See AGENTS.md for project conventions.`);
 }
 async function main() {

package/package.json

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