@forgecart/designer-runtime 1.0.0

package/dist/protocol/message-codec.d.ts

@@ -0,0 +1,50 @@
+import type { GuestMessage, HostMessage } from './message.types.js';
+/**
+ * Structural decoder for the wire protocol. Both sides receive arbitrary
+ * `message` events (payment SDKs, analytics pixels, HMR sockets), so every
+ * payload is treated as `unknown` and validated field by field — no casts.
+ * Anything that fails validation parses to null; the caller decides whether
+ * that is silence (foreign traffic) or an INVALID_MESSAGE error (namespaced
+ * traffic with a malformed payload).
+ */
+export declare class MessageCodec {
+    private readonly hostValidators;
+    private readonly guestValidators;
+    /** Parses a host→guest payload; null for foreign or malformed traffic. */
+    parseHostMessage(data: unknown): HostMessage | null;
+    /** Parses a guest→host payload; null for foreign or malformed traffic. */
+    parseGuestMessage(data: unknown): GuestMessage | null;
+    /**
+     * True when the payload claims our namespace, regardless of validity.
+     * Lets the runtime distinguish "foreign traffic — stay silent" from
+     * "namespaced but malformed — answer with INVALID_MESSAGE".
+     */
+    hasProtocolNamespace(data: unknown): boolean;
+    private isHostMessage;
+    private isGuestMessage;
+    private isEnvelopedRecord;
+    private isRecord;
+    private isString;
+    private isStringOrNull;
+    private isNonEmptyString;
+    private isFiniteNumber;
+    private isPositiveNumber;
+    private isOptionalPositiveNumber;
+    private isStringArray;
+    private isPoint;
+    private isPointArray;
+    private isViewport;
+    private isRect;
+    private isCapabilities;
+    private isBoundsEntryArray;
+    private isBoundsEntry;
+    private isElementDescriptorArray;
+    private isElementDescriptor;
+    private hasDescriptorIdentity;
+    private hasDescriptorContent;
+    private hasDescriptorGeometry;
+    private isDomPath;
+    private isDomPathSegment;
+    private isSourceRefOrNull;
+    private isStringRecord;
+}

package/dist/protocol/message-codec.js

@@ -0,0 +1,209 @@
+import { PROTOCOL_NAMESPACE, PROTOCOL_VERSION } from './protocol.constant.js';
+const RUNTIME_ERROR_CODES = new Set([
+    'INVALID_MESSAGE',
+    'NOT_ACTIVE',
+    'REGION_TOO_LARGE',
+    'UNKNOWN_REF',
+    'INTERNAL',
+]);
+/**
+ * Structural decoder for the wire protocol. Both sides receive arbitrary
+ * `message` events (payment SDKs, analytics pixels, HMR sockets), so every
+ * payload is treated as `unknown` and validated field by field — no casts.
+ * Anything that fails validation parses to null; the caller decides whether
+ * that is silence (foreign traffic) or an INVALID_MESSAGE error (namespaced
+ * traffic with a malformed payload).
+ */
+export class MessageCodec {
+    hostValidators = new Map([
+        ['HELLO', (m) => this.isNonEmptyString(m.nonce) && this.isFiniteNumber(m.protocolVersion)],
+        ['ACTIVATE', () => true],
+        ['DEACTIVATE', () => true],
+        ['PING', () => true],
+        [
+            'REGION_SELECT',
+            (m) => this.isNonEmptyString(m.requestId) &&
+                this.isPointArray(m.stroke) &&
+                this.isPositiveNumber(m.radius) &&
+                this.isOptionalPositiveNumber(m.maxElements),
+        ],
+        ['HIGHLIGHT_SET', (m) => this.isStringArray(m.refIds)],
+        ['HIGHLIGHT_CLEAR', () => true],
+        [
+            'ELEMENT_BOUNDS_QUERY',
+            (m) => this.isNonEmptyString(m.requestId) && this.isStringArray(m.refIds),
+        ],
+    ]);
+    guestValidators = new Map([
+        ['READY', () => true],
+        [
+            'HELLO_ACK',
+            (m) => this.isCapabilities(m.capabilities) &&
+                this.isString(m.url) &&
+                this.isViewport(m.viewport),
+        ],
+        ['ACTIVATED', () => true],
+        ['DEACTIVATED', () => true],
+        ['PONG', (m) => this.isString(m.url) && this.isPoint(m.scroll)],
+        [
+            'REGION_RESOLVED',
+            (m) => this.isNonEmptyString(m.requestId) &&
+                this.isElementDescriptorArray(m.elements) &&
+                this.isRect(m.regionBounds) &&
+                typeof m.truncated === 'boolean',
+        ],
+        [
+            'ELEMENT_BOUNDS',
+            (m) => this.isNonEmptyString(m.requestId) && this.isBoundsEntryArray(m.entries),
+        ],
+        ['SCROLL', (m) => this.isPoint(m.scroll)],
+        ['RESIZE', (m) => this.isViewport(m.viewport)],
+        ['NAVIGATED', (m) => this.isString(m.url)],
+        [
+            'ERROR',
+            (m) => this.isString(m.code) &&
+                RUNTIME_ERROR_CODES.has(m.code) &&
+                this.isStringOrNull(m.requestId) &&
+                this.isStringOrNull(m.detail),
+        ],
+    ]);
+    /** Parses a host→guest payload; null for foreign or malformed traffic. */
+    parseHostMessage(data) {
+        return this.isHostMessage(data) ? data : null;
+    }
+    /** Parses a guest→host payload; null for foreign or malformed traffic. */
+    parseGuestMessage(data) {
+        return this.isGuestMessage(data) ? data : null;
+    }
+    /**
+     * True when the payload claims our namespace, regardless of validity.
+     * Lets the runtime distinguish "foreign traffic — stay silent" from
+     * "namespaced but malformed — answer with INVALID_MESSAGE".
+     */
+    hasProtocolNamespace(data) {
+        return this.isRecord(data) && data.ns === PROTOCOL_NAMESPACE;
+    }
+    isHostMessage(data) {
+        if (!this.isEnvelopedRecord(data))
+            return false;
+        return this.hostValidators.get(data.type)?.(data) ?? false;
+    }
+    isGuestMessage(data) {
+        if (!this.isEnvelopedRecord(data))
+            return false;
+        return this.guestValidators.get(data.type)?.(data) ?? false;
+    }
+    isEnvelopedRecord(data) {
+        if (!this.isRecord(data))
+            return false;
+        if (data.ns !== PROTOCOL_NAMESPACE || data.v !== PROTOCOL_VERSION)
+            return false;
+        return this.isNonEmptyString(data.type);
+    }
+    isRecord(value) {
+        return typeof value === 'object' && value !== null;
+    }
+    isString(value) {
+        return typeof value === 'string';
+    }
+    isStringOrNull(value) {
+        return value === null || typeof value === 'string';
+    }
+    isNonEmptyString(value) {
+        return typeof value === 'string' && value.length > 0;
+    }
+    isFiniteNumber(value) {
+        return typeof value === 'number' && Number.isFinite(value);
+    }
+    isPositiveNumber(value) {
+        return this.isFiniteNumber(value) && value > 0;
+    }
+    isOptionalPositiveNumber(value) {
+        return value === undefined || this.isPositiveNumber(value);
+    }
+    isStringArray(value) {
+        return Array.isArray(value) && value.every((item) => this.isString(item));
+    }
+    isPoint(value) {
+        return this.isRecord(value) && this.isFiniteNumber(value.x) && this.isFiniteNumber(value.y);
+    }
+    isPointArray(value) {
+        return Array.isArray(value) && value.every((item) => this.isPoint(item));
+    }
+    isViewport(value) {
+        return (this.isRecord(value) &&
+            this.isFiniteNumber(value.width) &&
+            this.isFiniteNumber(value.height));
+    }
+    isRect(value) {
+        if (!this.isRecord(value))
+            return false;
+        return (this.isFiniteNumber(value.x) &&
+            this.isFiniteNumber(value.y) &&
+            this.isFiniteNumber(value.width) &&
+            this.isFiniteNumber(value.height));
+    }
+    isCapabilities(value) {
+        return (this.isRecord(value) &&
+            typeof value.stamping === 'boolean' &&
+            typeof value.highlight === 'boolean');
+    }
+    isBoundsEntryArray(value) {
+        return Array.isArray(value) && value.every((item) => this.isBoundsEntry(item));
+    }
+    isBoundsEntry(value) {
+        if (!this.isRecord(value))
+            return false;
+        return this.isNonEmptyString(value.refId) && (value.bounds === null || this.isRect(value.bounds));
+    }
+    isElementDescriptorArray(value) {
+        return Array.isArray(value) && value.every((item) => this.isElementDescriptor(item));
+    }
+    isElementDescriptor(value) {
+        if (!this.isRecord(value))
+            return false;
+        return (this.hasDescriptorIdentity(value) &&
+            this.hasDescriptorContent(value) &&
+            this.hasDescriptorGeometry(value));
+    }
+    hasDescriptorIdentity(value) {
+        return (this.isNonEmptyString(value.refId) &&
+            this.isNonEmptyString(value.tagName) &&
+            this.isStringOrNull(value.id) &&
+            this.isStringArray(value.classList));
+    }
+    hasDescriptorContent(value) {
+        return (this.isDomPath(value.domPath) &&
+            this.isSourceRefOrNull(value.source) &&
+            this.isStringOrNull(value.text) &&
+            this.isStringOrNull(value.role) &&
+            this.isStringRecord(value.attributes));
+    }
+    hasDescriptorGeometry(value) {
+        return (this.isRect(value.bounds) &&
+            this.isFiniteNumber(value.coverage) &&
+            this.isFiniteNumber(value.childCount));
+    }
+    isDomPath(value) {
+        return Array.isArray(value) && value.every((item) => this.isDomPathSegment(item));
+    }
+    isDomPathSegment(value) {
+        if (!this.isRecord(value))
+            return false;
+        return this.isNonEmptyString(value.tag) && this.isFiniteNumber(value.nthOfType);
+    }
+    isSourceRefOrNull(value) {
+        if (value === null)
+            return true;
+        if (!this.isRecord(value))
+            return false;
+        return (this.isNonEmptyString(value.file) &&
+            this.isFiniteNumber(value.line) &&
+            this.isFiniteNumber(value.column) &&
+            this.isStringOrNull(value.componentName));
+    }
+    isStringRecord(value) {
+        return this.isRecord(value) && Object.values(value).every((item) => this.isString(item));
+    }
+}
+//# sourceMappingURL=message-codec.js.map

package/dist/protocol/message-codec.js.map

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

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

@@ -0,0 +1,122 @@
+import type { ElementBoundsEntry, ElementDescriptor, GuestCapabilities, Point, Rect, ScrollPosition, Viewport } from './element.types.js';
+import type { PROTOCOL_NAMESPACE, PROTOCOL_VERSION } from './protocol.constant.js';
+/**
+ * Protocol error codes carried by guest ERROR messages. This is a wire-level
+ * string union by design: the runtime is a published browser package with no
+ * access to the backend `ErrorCode` enum, and the host resolves these codes
+ * into its own UX (retry, re-handshake, toast) — they never reach GraphQL.
+ */
+export type RuntimeErrorCode = 'INVALID_MESSAGE' | 'NOT_ACTIVE' | 'REGION_TOO_LARGE' | 'UNKNOWN_REF' | 'INTERNAL';
+/** Envelope present on every message; both sides reject anything else. */
+export interface ProtocolEnvelope {
+    ns: typeof PROTOCOL_NAMESPACE;
+    v: typeof PROTOCOL_VERSION;
+}
+/** Opens the handshake. Only accepted with the capability nonce. */
+export interface HelloMessage extends ProtocolEnvelope {
+    type: 'HELLO';
+    nonce: string;
+    protocolVersion: number;
+}
+/** Arms the runtime: region selection, highlights and emitters turn on. */
+export interface ActivateMessage extends ProtocolEnvelope {
+    type: 'ACTIVATE';
+}
+/** Disarms the runtime: overlay, `data-fc-ref` stamps and emitters are stripped. */
+export interface DeactivateMessage extends ProtocolEnvelope {
+    type: 'DEACTIVATE';
+}
+/** Liveness probe; answered with PONG while handshaken or active. */
+export interface PingMessage extends ProtocolEnvelope {
+    type: 'PING';
+}
+/** A completed spray stroke to resolve into elements. */
+export interface RegionSelectMessage extends ProtocolEnvelope {
+    type: 'REGION_SELECT';
+    requestId: string;
+    stroke: Point[];
+    radius: number;
+    maxElements?: number;
+}
+/** Replaces the highlight boxes with the given refs' current bounds. */
+export interface HighlightSetMessage extends ProtocolEnvelope {
+    type: 'HIGHLIGHT_SET';
+    refIds: string[];
+}
+/** Removes every highlight box (the overlay container stays mounted). */
+export interface HighlightClearMessage extends ProtocolEnvelope {
+    type: 'HIGHLIGHT_CLEAR';
+}
+/** Asks for the current bounds of previously resolved refs. */
+export interface ElementBoundsQueryMessage extends ProtocolEnvelope {
+    type: 'ELEMENT_BOUNDS_QUERY';
+    requestId: string;
+    refIds: string[];
+}
+export type HostMessage = HelloMessage | ActivateMessage | DeactivateMessage | PingMessage | RegionSelectMessage | HighlightSetMessage | HighlightClearMessage | ElementBoundsQueryMessage;
+/**
+ * Pre-handshake boot beacon. The only message ever posted with
+ * targetOrigin '*'; it carries zero payload beyond the envelope so an
+ * arbitrary embedder learns nothing. The host answers with HELLO.
+ */
+export interface ReadyMessage extends ProtocolEnvelope {
+    type: 'READY';
+}
+/** Successful handshake reply; the guest has pinned the host origin. */
+export interface HelloAckMessage extends ProtocolEnvelope {
+    type: 'HELLO_ACK';
+    capabilities: GuestCapabilities;
+    url: string;
+    viewport: Viewport;
+}
+/** Acknowledges ACTIVATE (idempotent — re-sent for duplicate ACTIVATEs). */
+export interface ActivatedMessage extends ProtocolEnvelope {
+    type: 'ACTIVATED';
+}
+/** Acknowledges DEACTIVATE after overlay/stamp/listener teardown. */
+export interface DeactivatedMessage extends ProtocolEnvelope {
+    type: 'DEACTIVATED';
+}
+/** Liveness answer; `url` lets the host detect soft (push-state) navigations. */
+export interface PongMessage extends ProtocolEnvelope {
+    type: 'PONG';
+    url: string;
+    scroll: ScrollPosition;
+}
+/** The resolved elements for one REGION_SELECT request. */
+export interface RegionResolvedMessage extends ProtocolEnvelope {
+    type: 'REGION_RESOLVED';
+    requestId: string;
+    elements: ElementDescriptor[];
+    regionBounds: Rect;
+    truncated: boolean;
+}
+/** Answer to ELEMENT_BOUNDS_QUERY; entries keep the request's ref order. */
+export interface ElementBoundsMessage extends ProtocolEnvelope {
+    type: 'ELEMENT_BOUNDS';
+    requestId: string;
+    entries: ElementBoundsEntry[];
+}
+/** rAF-throttled scroll notification, emitted while active. */
+export interface ScrollMessage extends ProtocolEnvelope {
+    type: 'SCROLL';
+    scroll: ScrollPosition;
+}
+/** rAF-throttled viewport resize notification, emitted while active. */
+export interface ResizeMessage extends ProtocolEnvelope {
+    type: 'RESIZE';
+    viewport: Viewport;
+}
+/** popstate/hashchange navigation notification, emitted while active. */
+export interface NavigatedMessage extends ProtocolEnvelope {
+    type: 'NAVIGATED';
+    url: string;
+}
+/** Post-handshake failure report; pre-handshake failures stay silent. */
+export interface ErrorMessage extends ProtocolEnvelope {
+    type: 'ERROR';
+    code: RuntimeErrorCode;
+    requestId: string | null;
+    detail: string | null;
+}
+export type GuestMessage = ReadyMessage | HelloAckMessage | ActivatedMessage | DeactivatedMessage | PongMessage | RegionResolvedMessage | ElementBoundsMessage | ScrollMessage | ResizeMessage | NavigatedMessage | ErrorMessage;

package/dist/protocol/message.types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=message.types.js.map

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

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

package/dist/protocol/protocol.constant.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Wire-protocol constants shared by the guest runtime (tenant storefront
+ * iframe) and the dashboard host. Both sides validate `ns` + `v` on every
+ * message; anything else on the window message bus (payment SDKs, analytics,
+ * HMR sockets) is foreign traffic and must be ignored silently.
+ */
+export declare const PROTOCOL_NAMESPACE = "fc-designer";
+/** Bumped on breaking wire changes; HELLO carries the host's version. */
+export declare const PROTOCOL_VERSION = 1;
+/**
+ * URL-fragment key carrying the activation nonce (`#fcd=<uuid>`). The
+ * fragment never reaches the server; the guest strips it on boot and parks
+ * the nonce in sessionStorage so it survives iframe reloads.
+ */
+export declare const FRAGMENT_KEY = "fcd";
+/** sessionStorage key the guest stores the captured nonce under. */
+export declare const NONCE_STORAGE_KEY = "fc-designer:nonce";
+/**
+ * Attribute stamped at build time by the turbo-loader, value
+ * `<project-relative-file>:<line>:<col>:<ComponentName>` (1-based line and
+ * column of the JSX opening element's `<`).
+ */
+export declare const SOURCE_ATTRIBUTE = "data-fc-source";
+/**
+ * Attribute stamped on resolved elements during REGION_SELECT so later
+ * HIGHLIGHT_SET / ELEMENT_BOUNDS_QUERY calls can address them by refId.
+ */
+export declare const REF_ATTRIBUTE = "data-fc-ref";
+/** Attribute marking the highlight overlay container element. */
+export declare const OVERLAY_ATTRIBUTE = "data-fc-designer-overlay";

package/dist/protocol/protocol.constant.js

@@ -0,0 +1,31 @@
+/**
+ * Wire-protocol constants shared by the guest runtime (tenant storefront
+ * iframe) and the dashboard host. Both sides validate `ns` + `v` on every
+ * message; anything else on the window message bus (payment SDKs, analytics,
+ * HMR sockets) is foreign traffic and must be ignored silently.
+ */
+export const PROTOCOL_NAMESPACE = 'fc-designer';
+/** Bumped on breaking wire changes; HELLO carries the host's version. */
+export const PROTOCOL_VERSION = 1;
+/**
+ * URL-fragment key carrying the activation nonce (`#fcd=<uuid>`). The
+ * fragment never reaches the server; the guest strips it on boot and parks
+ * the nonce in sessionStorage so it survives iframe reloads.
+ */
+export const FRAGMENT_KEY = 'fcd';
+/** sessionStorage key the guest stores the captured nonce under. */
+export const NONCE_STORAGE_KEY = 'fc-designer:nonce';
+/**
+ * Attribute stamped at build time by the turbo-loader, value
+ * `<project-relative-file>:<line>:<col>:<ComponentName>` (1-based line and
+ * column of the JSX opening element's `<`).
+ */
+export const SOURCE_ATTRIBUTE = 'data-fc-source';
+/**
+ * Attribute stamped on resolved elements during REGION_SELECT so later
+ * HIGHLIGHT_SET / ELEMENT_BOUNDS_QUERY calls can address them by refId.
+ */
+export const REF_ATTRIBUTE = 'data-fc-ref';
+/** Attribute marking the highlight overlay container element. */
+export const OVERLAY_ATTRIBUTE = 'data-fc-designer-overlay';
+//# sourceMappingURL=protocol.constant.js.map

package/dist/protocol/protocol.constant.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.constant.js","sourceRoot":"","sources":["../../src/protocol/protocol.constant.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,aAAa,CAAC;AAEhD,yEAAyE;AACzE,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAElC;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,KAAK,CAAC;AAElC,oEAAoE;AACpE,MAAM,CAAC,MAAM,iBAAiB,GAAG,mBAAmB,CAAC;AAErD;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,gBAAgB,CAAC;AAEjD;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,aAAa,CAAC;AAE3C,iEAAiE;AACjE,MAAM,CAAC,MAAM,iBAAiB,GAAG,0BAA0B,CAAC"}

package/dist/runtime/descriptor/element-descriptor-extractor.d.ts

@@ -0,0 +1,38 @@
+import type { ElementDescriptor } from '../../protocol/element.types.js';
+/**
+ * Projects a resolved DOM element into the wire {@link ElementDescriptor} —
+ * everything the host (and ultimately the AI agent) needs to identify the
+ * element in the storefront source tree without access to the live DOM.
+ */
+export declare class ElementDescriptorExtractor {
+    private readonly win;
+    constructor(win: Window);
+    extract(element: Element, refId: string, coverage: number): ElementDescriptor;
+    /**
+     * Finds the nearest `data-fc-source` stamp on the element or up to three
+     * ancestors (components often render a stamped wrapper around unstamped
+     * children). The first stamp found is authoritative: a malformed stamp
+     * yields null instead of climbing further, which would misattribute the
+     * element to an outer component.
+     */
+    private resolveSource;
+    /**
+     * Parses `<file>:<line>:<col>:<ComponentName>` by splitting from the
+     * right — the trailing three segments are component, column and line; the
+     * rest re-joins as the file path, so colon-bearing paths survive.
+     */
+    private parseSource;
+    private parsePosition;
+    /**
+     * Body-rooted `tag:nth-of-type` path. `nthOfType` counts same-tag element
+     * siblings, 1-based. Paths deeper than 14 segments keep the first 6 and
+     * last 7 with {@link DOM_PATH_ELISION_SEGMENT} marking the elided middle.
+     */
+    private buildDomPath;
+    private nthOfType;
+    private extractText;
+    private resolveRole;
+    private inputRole;
+    private collectAttributes;
+    private toRect;
+}