@forgecart/designer-runtime 1.0.0

package/README.md

@@ -0,0 +1,166 @@
+# @forgecart/designer-runtime
+
+The guest half of ForgeCart's visual editor. It ships inside tenant Next.js
+storefronts, boots **dormant**, and is activated exclusively over the iframe
+`postMessage` API by the dashboard host. Once active it resolves spray-stroke
+regions into DOM element descriptors (with `file:line:col` source attribution
+stamped at build time), renders highlight overlays, and reports scroll /
+resize / navigation so the host can keep its canvas in sync.
+
+Three entrypoints:
+
+| Subpath | Environment | Contents |
+|---------|-------------|----------|
+| `.` | Browser (ESM) | `installDesignerRuntime(): () => void` — the storefront mounts this once |
+| `./protocol` | Anywhere (ESM, DOM-free) | Wire types, `MessageCodec`, `ElementReferenceFormatter`, protocol constants — the dashboard host and the agent import **only** this |
+| `./turbo-loader` | Node (CJS) | The Turbopack/webpack loader that stamps `data-fc-source` onto host JSX elements in development |
+
+The browser entrypoints have **zero runtime dependencies**; the loader
+subpath depends on `@babel/parser` + `magic-string` only.
+
+## Wire protocol (v1, namespace `fc-designer`)
+
+Every message carries the envelope `{ ns: 'fc-designer', v: 1 }`; anything
+else on the message bus (payment SDKs, analytics, HMR) is foreign traffic and
+ignored silently. All coordinates are **iframe-viewport CSS pixels** — the
+guest is zoom-agnostic by construction.
+
+```
+GUEST boots dormant ── READY (targetOrigin '*', empty payload) ──▶ HOST
+HOST  ── HELLO { nonce, protocolVersion } ──▶ GUEST    nonce-gated, pins event.origin
+GUEST ── HELLO_ACK { capabilities, url, viewport } ──▶ HOST       state: handshaken
+HOST  ── ACTIVATE ──▶ GUEST ── ACTIVATED ──▶ HOST                 state: active
+HOST  ── REGION_SELECT { requestId, stroke, radius, maxElements } ──▶ GUEST
+GUEST ── REGION_RESOLVED { requestId, elements, regionBounds, truncated } ──▶ HOST
+HOST  ── HIGHLIGHT_SET { refIds } / HIGHLIGHT_CLEAR ──▶ GUEST
+HOST  ── ELEMENT_BOUNDS_QUERY { requestId, refIds } ──▶ GUEST ── ELEMENT_BOUNDS ──▶ HOST
+HOST  ── PING ──▶ GUEST ── PONG { url, scroll } ──▶ HOST          liveness
+GUEST ── SCROLL / RESIZE (rAF-throttled), NAVIGATED ──▶ HOST      while active
+HOST  ── DEACTIVATE ──▶ GUEST ── DEACTIVATED ──▶ HOST             state: handshaken
+GUEST ── ERROR { code, requestId, detail } ──▶ HOST               post-handshake only
+```
+
+Error codes: `INVALID_MESSAGE`, `NOT_ACTIVE`, `REGION_TOO_LARGE`,
+`UNKNOWN_REF`, `INTERNAL` — a wire-level string union; the host maps them to
+its own UX.
+
+### Activation security
+
+- **Inert outside an iframe** — `window.parent === window` makes
+  `installDesignerRuntime` a no-op. The dormant footprint is exactly one
+  `message` listener and zero DOM nodes.
+- **Capability nonce** — the host appends `#fcd=<uuid>` to the preview URL.
+  The fragment never reaches the server; the guest parks the nonce in
+  `sessionStorage` (survives iframe reloads) and strips only the `fcd` key
+  from the hash. Without the nonce, every HELLO is ignored silently.
+- **Origin pinning** — a HELLO is accepted only from `window.parent` with a
+  real (non-`'null'`) origin and the exact nonce; the first success pins
+  `event.origin` and every later post targets that origin. A re-HELLO must
+  come from the pinned origin.
+- **Reload recovery** — an iframe reload boots a fresh runtime that posts a
+  fresh READY beacon; the host re-handshakes and the nonce is still in
+  `sessionStorage`.
+
+### Region resolution
+
+`REGION_SELECT` rasterizes the stroke into grid cells (cell size
+`max(8, radius/2)`, budget 600 cells with coarsening back-off; padded bbox
+beyond 4× the viewport area → `REGION_TOO_LARGE`), stack hit-tests every
+cell center, drops non-meaningful elements (document chrome, invisible,
+zero-area, > 85%-viewport wrappers, Next dev chrome), collapses
+ancestor/descendant stacks by coverage, ranks by coverage then area, caps at
+`min(maxElements ?? 12, 25)`, and stamps survivors with `data-fc-ref` for
+later `HIGHLIGHT_SET` / `ELEMENT_BOUNDS_QUERY`. Stamps accumulate per
+activation and are stripped on `DEACTIVATE`.
+
+## Template integration (tenant storefront)
+
+`next.config.js` — run the stamping loader before SWC (Next 15.1 key;
+renamed `turbopack.rules` in 15.3). `next build` ignores it on 15.1 and the
+loader additionally self-gates on `NODE_ENV === 'development'`, so production
+output is untouched:
+
+```js
+module.exports = {
+  experimental: {
+    turbo: {
+      rules: {
+        'src/**/*.{tsx,jsx}': {
+          loaders: [{ loader: '@forgecart/designer-runtime/turbo-loader' }],
+        },
+      },
+    },
+  },
+};
+```
+
+Mount the runtime last in the root layout's `<body>` via a `'use client'`
+component so it survives App Router client navigations:
+
+```tsx
+'use client';
+import { useEffect } from 'react';
+
+export function ForgecartDesigner(): null {
+  useEffect(() => {
+    if (process.env.NODE_ENV !== 'development') return; // DCE'd from prod bundles
+    if (window.parent === window) return;
+    let dispose: (() => void) | undefined;
+    let cancelled = false;
+    void import('@forgecart/designer-runtime').then((mod) => {
+      if (cancelled) return;
+      dispose = mod.installDesignerRuntime();
+    });
+    return () => {
+      cancelled = true;
+      dispose?.();
+    };
+  }, []);
+  return null;
+}
+```
+
+`installDesignerRuntime` is idempotent across React StrictMode's double
+effect: a second install while a runtime is live returns the live dispose,
+and disposing clears the singleton.
+
+## Host integration (dashboard)
+
+Import **only** `@forgecart/designer-runtime/protocol`. The host:
+
+1. appends `#fcd=<crypto.randomUUID()>` to the preview URL before setting the
+   iframe `src`;
+2. listens for `READY`, then posts `HELLO { nonce, protocolVersion }` to the
+   iframe's content window — and re-handshakes whenever a fresh `READY`
+   arrives (iframe reload);
+3. validates every inbound message with `MessageCodec.parseGuestMessage` and
+   checks `event.source` is the iframe's content window;
+4. correlates request/response pairs by `requestId` with a timeout;
+5. serializes selections for the first message of an anchored AI thread via
+   `ElementReferenceFormatter` (`<fc-selection>{json}</fc-selection>`).
+
+## Contingency: jsx-dev-runtime fallback
+
+If a future Next/Turbopack release breaks `experimental.turbo.rules` for JS
+loaders, the documented fallback is intercepting `jsx-dev-runtime`'s `jsxDEV`
+source argument to inject the same attribute at render time. It is kept as a
+contingency only — it is fragile against React 19.2 dropping `jsxDEV` source
+args, while the loader approach owns its parse and survives React upgrades.
+
+## Develop, build, publish
+
+```bash
+nx run designer-runtime:test        # jsdom unit + loader integration suite
+nx run designer-runtime:typecheck   # lib + loader + spec tsconfigs
+nx run designer-runtime:build       # tsc ESM lib → dist/, tsc CJS loader → dist/loader-cjs/
+nx run designer-runtime:publish     # npm publish --access public (runs build first)
+```
+
+The build stamps `dist/loader-cjs/package.json` with `{ "type": "commonjs" }`
+so the loader subpath `require()`s correctly from this otherwise
+`"type": "module"` package.
+
+Publish order for real workspace pods: publish this package first (the
+pod-image template warmup `npm install`s it through the Nexus npm proxy),
+then bump + commit the storefront template / CLI, then rebuild the
+workspace-pod image.

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Boots the designer runtime inside a tenant storefront. Inert unless the
+ * page is actually embedded (`window.parent !== window`) — on a top-level
+ * page this returns a no-op dispose and registers nothing. When embedded,
+ * the runtime boots dormant (one `message` listener, a READY beacon, zero
+ * DOM nodes) and waits for the dashboard's nonce-gated HELLO.
+ *
+ * @returns a dispose function that fully tears the runtime down.
+ */
+export declare function installDesignerRuntime(): () => void;

package/dist/index.js

@@ -0,0 +1,51 @@
+import { MessageCodec } from './protocol/message-codec.js';
+import { ElementDescriptorExtractor } from './runtime/descriptor/element-descriptor-extractor.js';
+import { DesignerRuntime } from './runtime/designer-runtime.js';
+import { GuestMessenger } from './runtime/guest-messenger.js';
+import { HandshakeGate } from './runtime/handshake-gate.js';
+import { HighlightOverlay } from './runtime/highlight/highlight-overlay.js';
+import { DomHitTester } from './runtime/region/dom-hit-tester.js';
+import { ElementFilter } from './runtime/region/element-filter.js';
+import { RegionSampler } from './runtime/region/region-sampler.js';
+import { SprayRegionResolver } from './runtime/region/spray-region-resolver.js';
+/**
+ * Module-level singleton handle. React StrictMode runs every effect twice
+ * (mount → cleanup → mount), and an App Router layout can re-render the
+ * mounting component without a real page load — so idempotency cannot live
+ * in component state. The module instance is the one thing shared across
+ * those mounts: a second install while a runtime is live returns the live
+ * dispose, and disposing clears the slot so the next install boots fresh.
+ */
+let liveDispose = null;
+const NOOP_DISPOSE = () => undefined;
+/**
+ * Boots the designer runtime inside a tenant storefront. Inert unless the
+ * page is actually embedded (`window.parent !== window`) — on a top-level
+ * page this returns a no-op dispose and registers nothing. When embedded,
+ * the runtime boots dormant (one `message` listener, a READY beacon, zero
+ * DOM nodes) and waits for the dashboard's nonce-gated HELLO.
+ *
+ * @returns a dispose function that fully tears the runtime down.
+ */
+export function installDesignerRuntime() {
+    if (typeof window === 'undefined' || window.parent === window)
+        return NOOP_DISPOSE;
+    if (liveDispose !== null)
+        return liveDispose;
+    const runtime = buildRuntime(window);
+    runtime.install();
+    const dispose = () => {
+        if (liveDispose !== dispose)
+            return;
+        liveDispose = null;
+        runtime.dispose();
+    };
+    liveDispose = dispose;
+    return dispose;
+}
+/** Composition root: wires the runtime object graph for a live window. */
+function buildRuntime(win) {
+    const doc = win.document;
+    return new DesignerRuntime(win, new MessageCodec(), new HandshakeGate(win), new GuestMessenger(win.parent), new SprayRegionResolver(new RegionSampler(), new DomHitTester(doc), new ElementFilter(win), new ElementDescriptorExtractor(win), doc), new HighlightOverlay(doc));
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,EAAE,0BAA0B,EAAE,MAAM,sDAAsD,CAAC;AAClG,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAC5E,OAAO,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AACnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,2CAA2C,CAAC;AAEhF;;;;;;;GAOG;AACH,IAAI,WAAW,GAAwB,IAAI,CAAC;AAE5C,MAAM,YAAY,GAAG,GAAS,EAAE,CAAC,SAAS,CAAC;AAE3C;;;;;;;;GAQG;AACH,MAAM,UAAU,sBAAsB;IACpC,IAAI,OAAO,MAAM,KAAK,WAAW,IAAI,MAAM,CAAC,MAAM,KAAK,MAAM;QAAE,OAAO,YAAY,CAAC;IACnF,IAAI,WAAW,KAAK,IAAI;QAAE,OAAO,WAAW,CAAC;IAE7C,MAAM,OAAO,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IACrC,OAAO,CAAC,OAAO,EAAE,CAAC;IAElB,MAAM,OAAO,GAAG,GAAS,EAAE;QACzB,IAAI,WAAW,KAAK,OAAO;YAAE,OAAO;QACpC,WAAW,GAAG,IAAI,CAAC;QACnB,OAAO,CAAC,OAAO,EAAE,CAAC;IACpB,CAAC,CAAC;IACF,WAAW,GAAG,OAAO,CAAC;IACtB,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,0EAA0E;AAC1E,SAAS,YAAY,CAAC,GAAW;IAC/B,MAAM,GAAG,GAAG,GAAG,CAAC,QAAQ,CAAC;IACzB,OAAO,IAAI,eAAe,CACxB,GAAG,EACH,IAAI,YAAY,EAAE,EAClB,IAAI,aAAa,CAAC,GAAG,CAAC,EACtB,IAAI,cAAc,CAAC,GAAG,CAAC,MAAM,CAAC,EAC9B,IAAI,mBAAmB,CACrB,IAAI,aAAa,EAAE,EACnB,IAAI,YAAY,CAAC,GAAG,CAAC,EACrB,IAAI,aAAa,CAAC,GAAG,CAAC,EACtB,IAAI,0BAA0B,CAAC,GAAG,CAAC,EACnC,GAAG,CACJ,EACD,IAAI,gBAAgB,CAAC,GAAG,CAAC,CAC1B,CAAC;AACJ,CAAC"}

package/dist/loader-cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist/loader-cjs/turbo-loader.d.ts

@@ -0,0 +1,13 @@
+/** Minimal surface of the webpack/Turbopack loader context this loader uses. */
+interface TurboLoaderContext {
+    /** Absolute path of the module being loaded. */
+    resourcePath: string;
+    /** Absolute path of the project root; empty/undefined falls back to ''. */
+    rootContext?: string;
+    /** Marks the loader async and returns the completion callback. */
+    async(): (error: Error | null, content?: string, sourceMap?: object) => void;
+}
+declare const _default: ((this: TurboLoaderContext, source: string, map?: object) => void) & {
+    DATA_ATTRIBUTE: string;
+};
+export = _default;

package/dist/loader-cjs/turbo-loader.js

@@ -0,0 +1,190 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_path_1 = require("node:path");
+const parser_1 = require("@babel/parser");
+const magic_string_1 = __importDefault(require("magic-string"));
+/**
+ * The attribute stamped on host JSX elements, value
+ * `<project-relative-file>:<line>:<col>:<ComponentName>`.
+ *
+ * This is a deliberate local duplicate of the protocol's `SOURCE_ATTRIBUTE`
+ * constant: the loader compiles standalone to CommonJS (`dist/loader-cjs/`,
+ * rootDir `src/loader`) and must not import from `src/protocol`, which
+ * belongs to the ESM browser build. The turbo-loader spec asserts the two
+ * constants are equal, so they cannot drift.
+ */
+const DATA_ATTRIBUTE = 'data-fc-source';
+/**
+ * Stamps `data-fc-source="<file>:<line>:<col>:<Component>"` onto every host
+ * (lowercase) JSX element of one TSX/JSX module via magic-string, tracking
+ * the enclosing component name through a hand-rolled recursive AST walk —
+ * no `@babel/traverse`, keeping the loader's dependency surface at
+ * `@babel/parser` + `magic-string`.
+ */
+class JsxSourceStamper {
+    source;
+    relativePath;
+    magic;
+    stampCount = 0;
+    constructor(source, relativePath) {
+        this.source = source;
+        this.relativePath = relativePath;
+        this.magic = new magic_string_1.default(source);
+    }
+    /**
+     * Runs the stamping pass. Returns null when the module is left unchanged —
+     * either nothing needed stamping, or the module did not parse. A parse
+     * failure must never break the dev server: the file may be mid-edit under
+     * hot reload, and an unstamped module only costs source attribution, so
+     * the deliberate strategy is to pass every unparseable module through
+     * untouched.
+     */
+    stamp() {
+        let parsed;
+        try {
+            parsed = (0, parser_1.parse)(this.source, {
+                sourceType: 'module',
+                plugins: ['typescript', 'jsx'],
+            });
+        }
+        catch {
+            return null;
+        }
+        if (!this.isAstNode(parsed))
+            return null;
+        this.visit(parsed, null);
+        if (this.stampCount === 0)
+            return null;
+        return { code: this.magic.toString(), map: this.magic.generateMap({ hires: true }) };
+    }
+    visit(node, componentName) {
+        const enclosing = this.enclosingComponentName(node) ?? componentName;
+        if (node.type === 'JSXOpeningElement')
+            this.stampIfHostElement(node, enclosing);
+        for (const key of Object.keys(node)) {
+            if (key === 'loc')
+                continue;
+            this.visitChild(node[key], enclosing);
+        }
+    }
+    visitChild(value, componentName) {
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                if (this.isAstNode(item))
+                    this.visit(item, componentName);
+            }
+            return;
+        }
+        if (this.isAstNode(value))
+            this.visit(value, componentName);
+    }
+    /**
+     * A node opens a component scope when it is a `function Component()`
+     * declaration or a `const Component = () => ...` / `function` initializer
+     * — in both cases the identifier must be capitalized, React's own
+     * component convention.
+     */
+    enclosingComponentName(node) {
+        if (node.type === 'FunctionDeclaration') {
+            return this.capitalizedIdentifierName(node.id);
+        }
+        if (node.type !== 'VariableDeclarator')
+            return null;
+        if (!this.isAstNode(node.init))
+            return null;
+        if (node.init.type !== 'ArrowFunctionExpression' && node.init.type !== 'FunctionExpression') {
+            return null;
+        }
+        return this.capitalizedIdentifierName(node.id);
+    }
+    capitalizedIdentifierName(value) {
+        if (!this.isAstNode(value) || value.type !== 'Identifier')
+            return null;
+        const name = value.name;
+        if (typeof name !== 'string' || !/^[A-Z]/.test(name))
+            return null;
+        return name;
+    }
+    /**
+     * Stamps a JSXOpeningElement when it is a host element — a lowercase
+     * `JSXIdentifier` tag (`<div>`, `<my-widget>`); components, fragments,
+     * member expressions (`<Foo.Bar>`) and namespaced names stay untouched —
+     * and does not already carry the attribute (idempotency under double
+     * application). Line is 1-based and column converted to 1-based, both
+     * addressing the opening element's `<`.
+     */
+    stampIfHostElement(node, componentName) {
+        const name = node.name;
+        if (!this.isAstNode(name) || name.type !== 'JSXIdentifier')
+            return;
+        if (typeof name.name !== 'string' || !/^[a-z]/.test(name.name))
+            return;
+        if (this.hasDataAttribute(node))
+            return;
+        const position = this.startPosition(node);
+        const insertAt = name.end;
+        if (position === null || typeof insertAt !== 'number')
+            return;
+        const value = `${this.relativePath}:${String(position.line)}:${String(position.column + 1)}:${componentName ?? ''}`;
+        this.magic.appendLeft(insertAt, ` ${DATA_ATTRIBUTE}="${value.replace(/"/g, '')}"`);
+        this.stampCount++;
+    }
+    hasDataAttribute(openingElement) {
+        const attributes = openingElement.attributes;
+        if (!Array.isArray(attributes))
+            return false;
+        return attributes.some((attribute) => this.isDataAttribute(attribute));
+    }
+    isDataAttribute(attribute) {
+        if (!this.isAstNode(attribute) || attribute.type !== 'JSXAttribute')
+            return false;
+        const name = attribute.name;
+        return this.isAstNode(name) && name.type === 'JSXIdentifier' && name.name === DATA_ATTRIBUTE;
+    }
+    startPosition(node) {
+        const loc = node.loc;
+        if (typeof loc !== 'object' || loc === null || !('start' in loc))
+            return null;
+        const start = loc.start;
+        if (typeof start !== 'object' || start === null)
+            return null;
+        if (!('line' in start) || !('column' in start))
+            return null;
+        const { line, column } = start;
+        if (typeof line !== 'number' || typeof column !== 'number')
+            return null;
+        return { line, column };
+    }
+    isAstNode(value) {
+        return (typeof value === 'object' &&
+            value !== null &&
+            'type' in value &&
+            typeof value.type === 'string');
+    }
+}
+/**
+ * Turbopack/webpack loader entry. Registered in the storefront template via
+ * `experimental.turbo.rules` so it runs before SWC compiles each TSX/JSX
+ * module — identically across the RSC, SSR and client layers, so server and
+ * client markup carry the same attributes and hydration never mismatches.
+ * Self-gates on `NODE_ENV === 'development'`: production builds pass every
+ * module through untouched.
+ */
+const turboLoader = function (source, map) {
+    const callback = this.async();
+    if (process.env.NODE_ENV !== 'development') {
+        callback(null, source, map);
+        return;
+    }
+    const relativePath = (0, node_path_1.relative)(this.rootContext ?? '', this.resourcePath).replace(/\\/g, '/');
+    const result = new JsxSourceStamper(source, relativePath).stamp();
+    if (result === null) {
+        callback(null, source, map);
+        return;
+    }
+    callback(null, result.code, result.map);
+};
+module.exports = Object.assign(turboLoader, { DATA_ATTRIBUTE });
+//# sourceMappingURL=turbo-loader.js.map

package/dist/loader-cjs/turbo-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"turbo-loader.js","sourceRoot":"","sources":["../../src/loader/turbo-loader.ts"],"names":[],"mappings":"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"}

package/dist/protocol/element-reference-formatter.d.ts

@@ -0,0 +1,28 @@
+import type { ElementDescriptor } from './element.types.js';
+/** Opens the machine-readable selection block inside a chat message. */
+export declare const SELECTION_BLOCK_OPEN = "<fc-selection>";
+/** Closes the machine-readable selection block inside a chat message. */
+export declare const SELECTION_BLOCK_CLOSE = "</fc-selection>";
+/**
+ * Serializes resolved element descriptors into the `<fc-selection>` text
+ * block that anchors a visual-editor thread. The block rides verbatim in the
+ * first chat message of the thread (the agent pipeline persists and
+ * rehydrates message text untouched), so this formatter is the single
+ * definition of the format for both the dashboard host and the agent.
+ */
+export declare class ElementReferenceFormatter {
+    /**
+     * Builds the selection block for one spray selection. Stamped elements
+     * carry a `file:line:col` source pointer plus the enclosing component;
+     * unstamped elements fall back to their body-rooted DOM path.
+     */
+    toReferenceBlock(descriptors: readonly ElementDescriptor[], pageUrl: string): string;
+    /**
+     * Prepends the selection block to the user's text — the exact message
+     * shape the dashboard sends as the first message of an anchored thread.
+     */
+    buildSelectionMessage(block: string, userText: string): string;
+    private toReferenceEntry;
+    private formatSource;
+    private formatDomPath;
+}

package/dist/protocol/element-reference-formatter.js

@@ -0,0 +1,60 @@
+import { PROTOCOL_VERSION } from './protocol.constant.js';
+/** Opens the machine-readable selection block inside a chat message. */
+export const SELECTION_BLOCK_OPEN = '<fc-selection>';
+/** Closes the machine-readable selection block inside a chat message. */
+export const SELECTION_BLOCK_CLOSE = '</fc-selection>';
+/**
+ * Serializes resolved element descriptors into the `<fc-selection>` text
+ * block that anchors a visual-editor thread. The block rides verbatim in the
+ * first chat message of the thread (the agent pipeline persists and
+ * rehydrates message text untouched), so this formatter is the single
+ * definition of the format for both the dashboard host and the agent.
+ */
+export class ElementReferenceFormatter {
+    /**
+     * Builds the selection block for one spray selection. Stamped elements
+     * carry a `file:line:col` source pointer plus the enclosing component;
+     * unstamped elements fall back to their body-rooted DOM path.
+     */
+    toReferenceBlock(descriptors, pageUrl) {
+        const payload = {
+            version: PROTOCOL_VERSION,
+            pageUrl,
+            elements: descriptors.map((descriptor) => this.toReferenceEntry(descriptor)),
+        };
+        return `${SELECTION_BLOCK_OPEN}${JSON.stringify(payload)}${SELECTION_BLOCK_CLOSE}`;
+    }
+    /**
+     * Prepends the selection block to the user's text — the exact message
+     * shape the dashboard sends as the first message of an anchored thread.
+     */
+    buildSelectionMessage(block, userText) {
+        return `${block}\n${userText}`;
+    }
+    toReferenceEntry(descriptor) {
+        return {
+            ref: descriptor.refId,
+            tag: descriptor.tagName,
+            source: this.formatSource(descriptor),
+            component: descriptor.source?.componentName ?? null,
+            text: descriptor.text,
+            role: descriptor.role,
+            id: descriptor.id,
+            classes: descriptor.classList,
+            attributes: descriptor.attributes,
+            domPath: this.formatDomPath(descriptor.domPath),
+        };
+    }
+    formatSource(descriptor) {
+        if (descriptor.source === null)
+            return null;
+        const { file, line, column } = descriptor.source;
+        return `${file}:${String(line)}:${String(column)}`;
+    }
+    formatDomPath(segments) {
+        return segments
+            .map((segment) => `${segment.tag}:nth-of-type(${String(segment.nthOfType)})`)
+            .join(' > ');
+    }
+}
+//# sourceMappingURL=element-reference-formatter.js.map

package/dist/protocol/element-reference-formatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"element-reference-formatter.js","sourceRoot":"","sources":["../../src/protocol/element-reference-formatter.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D,wEAAwE;AACxE,MAAM,CAAC,MAAM,oBAAoB,GAAG,gBAAgB,CAAC;AAErD,yEAAyE;AACzE,MAAM,CAAC,MAAM,qBAAqB,GAAG,iBAAiB,CAAC;AAuBvD;;;;;;GAMG;AACH,MAAM,OAAO,yBAAyB;IACpC;;;;OAIG;IACH,gBAAgB,CAAC,WAAyC,EAAE,OAAe;QACzE,MAAM,OAAO,GAA0B;YACrC,OAAO,EAAE,gBAAgB;YACzB,OAAO;YACP,QAAQ,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,IAAI,CAAC,gBAAgB,CAAC,UAAU,CAAC,CAAC;SAC7E,CAAC;QACF,OAAO,GAAG,oBAAoB,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,qBAAqB,EAAE,CAAC;IACrF,CAAC;IAED;;;OAGG;IACH,qBAAqB,CAAC,KAAa,EAAE,QAAgB;QACnD,OAAO,GAAG,KAAK,KAAK,QAAQ,EAAE,CAAC;IACjC,CAAC;IAEO,gBAAgB,CAAC,UAA6B;QACpD,OAAO;YACL,GAAG,EAAE,UAAU,CAAC,KAAK;YACrB,GAAG,EAAE,UAAU,CAAC,OAAO;YACvB,MAAM,EAAE,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC;YACrC,SAAS,EAAE,UAAU,CAAC,MAAM,EAAE,aAAa,IAAI,IAAI;YACnD,IAAI,EAAE,UAAU,CAAC,IAAI;YACrB,IAAI,EAAE,UAAU,CAAC,IAAI;YACrB,EAAE,EAAE,UAAU,CAAC,EAAE;YACjB,OAAO,EAAE,UAAU,CAAC,SAAS;YAC7B,UAAU,EAAE,UAAU,CAAC,UAAU;YACjC,OAAO,EAAE,IAAI,CAAC,aAAa,CAAC,UAAU,CAAC,OAAO,CAAC;SAChD,CAAC;IACJ,CAAC;IAEO,YAAY,CAAC,UAA6B;QAChD,IAAI,UAAU,CAAC,MAAM,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;QAC5C,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAAC,MAAM,CAAC;QACjD,OAAO,GAAG,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;IACrD,CAAC;IAEO,aAAa,CAAC,QAAmC;QACvD,OAAO,QAAQ;aACZ,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,GAAG,OAAO,CAAC,GAAG,gBAAgB,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC;aAC5E,IAAI,CAAC,KAAK,CAAC,CAAC;IACjB,CAAC;CACF"}

package/dist/protocol/element.types.d.ts

@@ -0,0 +1,75 @@
+/**
+ * DOM-free element/geometry shapes that cross the iframe wire. All
+ * coordinates are iframe-viewport CSS pixels — the guest is zoom-agnostic by
+ * construction; the host owns world/zoom transforms.
+ */
+/** A point in iframe-viewport CSS pixels. */
+export interface Point {
+    x: number;
+    y: number;
+}
+/** An axis-aligned rectangle in iframe-viewport CSS pixels. */
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** The iframe's visual viewport size in CSS pixels. */
+export interface Viewport {
+    width: number;
+    height: number;
+}
+/** The iframe document's scroll offset in CSS pixels. */
+export interface ScrollPosition {
+    x: number;
+    y: number;
+}
+/** One `tag:nth-of-type(n)` step of an element's DOM path (body-rooted). */
+export interface DomPathSegment {
+    tag: string;
+    nthOfType: number;
+}
+/**
+ * A parsed `data-fc-source` stamp pointing back at the JSX opening element
+ * in the storefront source tree. `componentName` is null when the stamping
+ * loader could not determine an enclosing component.
+ */
+export interface SourceRef {
+    file: string;
+    line: number;
+    column: number;
+    componentName: string | null;
+}
+/**
+ * Everything the host (and ultimately the AI agent) needs to know about one
+ * element resolved from a spray region. `refId` addresses the element in
+ * later HIGHLIGHT_SET / ELEMENT_BOUNDS_QUERY calls via its `data-fc-ref`
+ * attribute; it is only stable until DEACTIVATE strips the stamps.
+ */
+export interface ElementDescriptor {
+    refId: string;
+    tagName: string;
+    id: string | null;
+    classList: string[];
+    domPath: DomPathSegment[];
+    source: SourceRef | null;
+    text: string | null;
+    role: string | null;
+    attributes: Record<string, string>;
+    bounds: Rect;
+    coverage: number;
+    childCount: number;
+}
+/** What the guest runtime can do for this page, reported in HELLO_ACK. */
+export interface GuestCapabilities {
+    /** True when at least one `data-fc-source` stamp exists in the document. */
+    stamping: boolean;
+    /** True when the highlight overlay is available. */
+    highlight: boolean;
+}
+/** Per-ref answer of an ELEMENT_BOUNDS_QUERY; `bounds` is null for stale refs. */
+export interface ElementBoundsEntry {
+    refId: string;
+    bounds: Rect | null;
+}

package/dist/protocol/element.types.js

@@ -0,0 +1,7 @@
+/**
+ * DOM-free element/geometry shapes that cross the iframe wire. All
+ * coordinates are iframe-viewport CSS pixels — the guest is zoom-agnostic by
+ * construction; the host owns world/zoom transforms.
+ */
+export {};
+//# sourceMappingURL=element.types.js.map

package/dist/protocol/element.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"element.types.js","sourceRoot":"","sources":["../../src/protocol/element.types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/protocol/index.d.ts

@@ -0,0 +1,5 @@
+export * from './protocol.constant.js';
+export * from './element.types.js';
+export * from './message.types.js';
+export * from './message-codec.js';
+export * from './element-reference-formatter.js';

package/dist/protocol/index.js

@@ -0,0 +1,6 @@
+export * from './protocol.constant.js';
+export * from './element.types.js';
+export * from './message.types.js';
+export * from './message-codec.js';
+export * from './element-reference-formatter.js';
+//# sourceMappingURL=index.js.map

package/dist/protocol/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/protocol/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kCAAkC,CAAC"}