@digital-gravy/etch-connector 0.1.5 → 0.2.1

package/README.md

@@ -122,12 +122,23 @@ 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
@@ -144,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)
@@ -194,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/cdp-client.js

@@ -14,6 +14,7 @@
  * keep the surface small.
  */
 import { WebSocket } from 'ws';
+import { z } from 'zod';
 /** A script evaluated over CDP threw. Distinct from operational failures. */
 export class CdpEvalError extends Error {
     /** The full page-side exception text (description + stack), if any. */
@@ -34,6 +35,62 @@ export class CdpError extends Error {
 const DEFAULT_PORT = 9222;
 const DEFAULT_HOST = '127.0.0.1';
 const DEFAULT_TIMEOUT_MS = 30_000;
+/**
+ * Page-side helpers prepended to the inspection expressions. Etch renders its
+ * canvas inside a same-origin iframe that `document.querySelector` can't see
+ * into, so canvas documents are searched first: `h1` resolves to the page being
+ * built, not the builder UI.
+ */
+const PAGE_HELPERS = `
+	const __etchDocuments = () => [
+		...Array.from(document.querySelectorAll('iframe'), (frame) => frame.contentDocument).filter(Boolean),
+		document
+	];
+	const __etchFind = (selector) => {
+		for (const doc of __etchDocuments()) {
+			const el = doc.querySelector(selector);
+			if (el) return el;
+		}
+		return null;
+	};
+	// Content outside a frame's viewport isn't painted, even with captureBeyondViewport.
+	const __etchClipToFrame = (edges, frame) => ({
+		left: Math.max(edges.left, 0),
+		top: Math.max(edges.top, 0),
+		right: Math.min(edges.right, frame.clientWidth),
+		bottom: Math.min(edges.bottom, frame.clientHeight)
+	});
+	// The canvas is zoomed with a CSS transform, so frame-local pixels are scaled.
+	const __etchToParentFrame = (edges, frame) => {
+		const frameRect = frame.getBoundingClientRect();
+		const scale = frame.offsetWidth ? frameRect.width / frame.offsetWidth : 1;
+		return {
+			left: frameRect.left + (frame.clientLeft + edges.left) * scale,
+			right: frameRect.left + (frame.clientLeft + edges.right) * scale,
+			top: frameRect.top + (frame.clientTop + edges.top) * scale,
+			bottom: frameRect.top + (frame.clientTop + edges.bottom) * scale
+		};
+	};
+	const __etchPageRect = (el) => {
+		const { left, top, right, bottom } = el.getBoundingClientRect();
+		let edges = { left, top, right, bottom };
+		let cropped = false;
+		for (let frame = el.ownerDocument.defaultView.frameElement; frame; frame = frame.ownerDocument.defaultView.frameElement) {
+			const visible = __etchClipToFrame(edges, frame);
+			if (visible.right <= visible.left || visible.bottom <= visible.top) return null;
+			if (Object.keys(visible).some((side) => visible[side] !== edges[side])) cropped = true;
+			edges = __etchToParentFrame(visible, frame);
+		}
+		return { x: edges.left + scrollX, y: edges.top + scrollY, width: edges.right - edges.left, height: edges.bottom - edges.top, cropped };
+	};
+`;
+const PageRectSchema = z.object({
+    x: z.number(),
+    y: z.number(),
+    width: z.number(),
+    height: z.number(),
+    cropped: z.boolean()
+});
 export class CdpClient {
     host;
     port;
@@ -187,7 +244,7 @@ export class CdpClient {
     }
     /** Rendered `outerHTML` of the first element matching `selector`. */
     async outerHtml(selector) {
-        const v = await this.evaluate(`(() => { const el = document.querySelector(${JSON.stringify(selector)}); return el ? el.outerHTML : null; })()`);
+        const v = await this.evaluate(`(() => { ${PAGE_HELPERS} const el = __etchFind(${JSON.stringify(selector)}); return el ? el.outerHTML : null; })()`);
         if (v === null)
             throw new CdpError(`no element matches "${selector}"`);
         return v;
@@ -196,9 +253,10 @@ export class CdpClient {
     async computedStyle(selector, props) {
         const keys = props ? JSON.stringify(props) : 'Array.from(cs)';
         const expr = `(() => {
-			const el = document.querySelector(${JSON.stringify(selector)});
+			${PAGE_HELPERS}
+			const el = __etchFind(${JSON.stringify(selector)});
 			if (!el) return null;
-			const cs = getComputedStyle(el);
+			const cs = el.ownerDocument.defaultView.getComputedStyle(el);
 			const out = {};
 			for (const k of ${keys}) out[k] = cs.getPropertyValue(k);
 			return out;
@@ -217,16 +275,25 @@ export class CdpClient {
         try {
             let clip;
             let captureBeyondViewport = false;
+            let cropped = false;
             if (options.selector) {
-                const rect = (await this.evaluate(`(() => {
-					const el = document.querySelector(${JSON.stringify(options.selector)});
-					if (!el) return null;
-					const b = el.getBoundingClientRect();
-					return { x: b.left + scrollX, y: b.top + scrollY, width: b.width, height: b.height };
-				})()`));
-                if (!rect)
+                const rect = await this.evaluate(`(() => {
+					${PAGE_HELPERS}
+					const el = __etchFind(${JSON.stringify(options.selector)});
+					if (!el) return 'missing';
+					const box = el.getBoundingClientRect();
+					if (!box.width || !box.height) return 'empty';
+					return __etchPageRect(el) ?? 'offscreen';
+				})()`);
+                if (rect === 'missing')
                     throw new CdpError(`no element matches "${options.selector}"`);
-                clip = { ...rect, scale: 1 };
+                if (rect === 'empty')
+                    throw new CdpError(`"${options.selector}" has no rendered size (hidden or empty)`);
+                if (rect === 'offscreen')
+                    throw new CdpError(`"${options.selector}" is outside the visible canvas area — ask the user to scroll it into view in the builder`);
+                const { cropped: partlyVisible, ...box } = PageRectSchema.parse(rect);
+                clip = { ...box, scale: 1 };
+                cropped = partlyVisible;
                 captureBeyondViewport = true;
             }
             else if (options.full) {
@@ -246,7 +313,7 @@ export class CdpClient {
                 ...(clip ? { clip } : {}),
                 captureBeyondViewport
             });
-            return Buffer.from(data, 'base64');
+            return { image: Buffer.from(data, 'base64'), cropped };
         }
         finally {
             if (options.freeze)
@@ -256,29 +323,42 @@ export class CdpClient {
     /** Pause every animation/transition and seek it to a deterministic frame. */
     async freezeAnimations() {
         await this.evaluate(`(() => {
-			let s = document.getElementById('__etch_freeze__');
-			if (!s) {
-				s = document.createElement('style');
+			${PAGE_HELPERS}
+			const documents = __etchDocuments();
+			for (const doc of documents) {
+				if (doc.getElementById('__etch_freeze__')) continue;
+				const s = doc.createElement('style');
 				s.id = '__etch_freeze__';
 				s.textContent = '*,*::before,*::after{transition:none!important}';
-				(document.head || document.documentElement).appendChild(s);
+				(doc.head || doc.documentElement).appendChild(s);
 			}
-			for (const a of document.getAnimations()) {
+			const frozen = [];
+			for (const a of documents.flatMap((doc) => doc.getAnimations())) {
 				try {
+					frozen.push({ animation: a, playState: a.playState, currentTime: a.currentTime });
 					a.pause();
 					const end = a.effect && a.effect.getComputedTiming ? a.effect.getComputedTiming().endTime : 0;
 					a.currentTime = (typeof end === 'number' && isFinite(end)) ? end : 0;
 				} catch (e) { /* leave this one as-is */ }
 			}
+			window.__etchFrozenAnimations = frozen;
 			return true;
 		})()`);
     }
-    /** Undo {@link freezeAnimations}: resume playback and remove the helper style. */
+    /** Undo {@link freezeAnimations}: put each animation back where it was and remove the helper style. */
     async restoreAnimations() {
+        // A blanket play() would restart finished animations (auto-rewind) and resume ones the page paused itself.
         await this.evaluate(`(() => {
-			const s = document.getElementById('__etch_freeze__');
-			if (s) s.remove();
-			for (const a of document.getAnimations()) { try { a.play(); } catch (e) {} }
+			${PAGE_HELPERS}
+			for (const doc of __etchDocuments()) doc.getElementById('__etch_freeze__')?.remove();
+			for (const { animation, playState, currentTime } of window.__etchFrozenAnimations ?? []) {
+				try {
+					animation.currentTime = currentTime;
+					if (playState === 'running') animation.play();
+					if (playState === 'finished') animation.finish();
+				} catch (e) { /* leave this one as-is */ }
+			}
+			delete window.__etchFrozenAnimations;
 			return true;
 		})()`);
     }

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,6 +33,7 @@ const BOOLEAN_FLAGS = new Set([
     'full',
     'jpeg',
     'json',
+    'quiet',
     'unsafe',
     'safe',
     'help',
@@ -275,6 +278,33 @@ async function tabsViaCdp(cdp, flags) {
     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());
@@ -285,8 +315,11 @@ async function tabsViaDaemon(flags) {
         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);
@@ -336,17 +369,51 @@ async function evalViaCdp(cdp, flags, code, timeoutMs) {
         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');
     }
+    // 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)
     });
+    await announced;
     if (!res.ok) {
         const err = (await res.json().catch(() => ({})));
         console.error(`eval failed: ${err.error ?? res.statusText}`);
@@ -384,14 +451,16 @@ async function runShot(flags) {
     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'}`;
-    const buf = await withRequiredCdp(flags, (c) => c.screenshot({ selector, full, format, freeze }));
-    writeFileSync(out, buf);
+    const { image, cropped } = await withRequiredCdp(flags, (c) => c.screenshot({ selector, full, format, freeze }));
+    writeFileSync(out, image);
     const scope = selector
         ? ` — clipped to ${selector}`
         : full
             ? ' — full page'
             : ' — viewport';
-    console.error(`wrote ${out} (${buf.length} bytes)${scope}${freeze ? ' (frozen)' : ''}`);
+    console.error(`wrote ${out} (${image.length} bytes)${scope}${freeze ? ' (frozen)' : ''}`);
+    if (cropped)
+        console.error(`warning: ${selector} extends past the visible canvas area, so the shot only shows the visible part — ask the user to scroll it fully into view`);
 }
 async function runHtml(positional, flags) {
     const selector = requireSelector('html', positional, flags);
@@ -419,7 +488,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)
@@ -437,6 +506,29 @@ 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: EVERY change goes through the public etch.* API — no exceptions, in
+either backend, for anything, inline styles included. NEVER touch the canvas
+directly: no document/DOM manipulation, no injected <style> tags, no setting
+attributes or styles on canvas elements or iframes. Styling goes through
+Etch's styling system by default: etch.styles.* for selectors/classes,
+etch.blocks.addClass() to apply them, etch.stylesheets.* for global CSS.
+When a value genuinely belongs inline (e.g. a per-instance custom property
+bound to a prop, style="--radius: {props.radius};"), it is still authored
+through the API — as the block's style attribute via etch.blocks.* — so it
+lands in the saved document, not just the rendered page. cdp's page access is
+for inspecting (shot, html, computed) — never for writing. Those three already
+look inside the canvas iframe, so inspecting a canvas element never needs a
+hand-written eval.
+
+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.
@@ -462,7 +554,8 @@ Examples:
 
 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.
+withheld); in cdp mode the full page is readable, but changes still go
+through etch.* only.
 
 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.
@@ -539,10 +632,13 @@ 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.`;
 function printHelp() {

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.5",
+	"version": "0.2.1",
 	"publishConfig": {
 		"access": "public"
 	},