@digital-gravy/etch-connector 0.2.0 → 0.2.2

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

@@ -451,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);
@@ -504,6 +506,20 @@ 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
@@ -538,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.

package/dist/guidance.js

@@ -35,7 +35,12 @@ function dynamicDataGuidance(environment) {
             "  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.'
+            '  loopId/loopParams here.',
+            '  The sources themselves are managed through etch.dataSources.*:',
+            '  list(), get(key) and findDataSource(query) read them synchronously;',
+            '  createAsync(), updateAsync() and deleteAsync() persist immediately.',
+            '  Call resolveAsync(key) to see the value a source actually returns',
+            '  before authoring property paths into it — do not guess its shape.'
         ];
     }
     if (hasCapability(environment, 'loops')) {
@@ -44,7 +49,9 @@ function dynamicDataGuidance(environment) {
             '  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.'
+            '  resolves to nothing and etch.dataSources is absent, not merely',
+            '  unavailable: the property does not exist, so feature-detect it',
+            '  rather than calling it and catching.'
         ];
     }
     return [

package/package.json

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