@forgecart/designer-runtime 1.0.0

package/dist/runtime/guest-messenger.js

@@ -0,0 +1,41 @@
+import { PROTOCOL_NAMESPACE, PROTOCOL_VERSION } from '../protocol/protocol.constant.js';
+/**
+ * The guest's only postMessage exit. Every message except the boot READY
+ * beacon is posted with the origin pinned by the handshake — the browser
+ * drops the message if the embedding page navigated elsewhere, so guest data
+ * can never leak to a window that is no longer the dashboard.
+ */
+export class GuestMessenger {
+    targetWindow;
+    pinnedOrigin = null;
+    constructor(targetWindow) {
+        this.targetWindow = targetWindow;
+    }
+    /**
+     * The pre-handshake boot beacon — the single message ever posted with
+     * targetOrigin `'*'`. It carries zero payload beyond the envelope, so an
+     * arbitrary embedder learns nothing it could not infer from the public
+     * storefront template.
+     */
+    postReady() {
+        this.targetWindow.postMessage({ ns: PROTOCOL_NAMESPACE, v: PROTOCOL_VERSION, type: 'READY' }, '*');
+    }
+    /** Pin the host origin after a validated HELLO; later pins must match. */
+    pinOrigin(origin) {
+        this.pinnedOrigin = origin;
+    }
+    getPinnedOrigin() {
+        return this.pinnedOrigin;
+    }
+    /**
+     * Post a protocol message to the pinned host origin. Before the handshake
+     * pinned an origin this is a silent no-op — pre-handshake the guest says
+     * nothing but READY.
+     */
+    post(body) {
+        if (this.pinnedOrigin === null)
+            return;
+        this.targetWindow.postMessage({ ns: PROTOCOL_NAMESPACE, v: PROTOCOL_VERSION, ...body }, this.pinnedOrigin);
+    }
+}
+//# sourceMappingURL=guest-messenger.js.map

package/dist/runtime/guest-messenger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guest-messenger.js","sourceRoot":"","sources":["../../src/runtime/guest-messenger.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAUxF;;;;;GAKG;AACH,MAAM,OAAO,cAAc;IAGI;IAFrB,YAAY,GAAkB,IAAI,CAAC;IAE3C,YAA6B,YAAoB;QAApB,iBAAY,GAAZ,YAAY,CAAQ;IAAG,CAAC;IAErD;;;;;OAKG;IACH,SAAS;QACP,IAAI,CAAC,YAAY,CAAC,WAAW,CAC3B,EAAE,EAAE,EAAE,kBAAkB,EAAE,CAAC,EAAE,gBAAgB,EAAE,IAAI,EAAE,OAAO,EAAE,EAC9D,GAAG,CACJ,CAAC;IACJ,CAAC;IAED,0EAA0E;IAC1E,SAAS,CAAC,MAAc;QACtB,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC;IAC7B,CAAC;IAED,eAAe;QACb,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;IAED;;;;OAIG;IACH,IAAI,CAAC,IAAsB;QACzB,IAAI,IAAI,CAAC,YAAY,KAAK,IAAI;YAAE,OAAO;QACvC,IAAI,CAAC,YAAY,CAAC,WAAW,CAC3B,EAAE,EAAE,EAAE,kBAAkB,EAAE,CAAC,EAAE,gBAAgB,EAAE,GAAG,IAAI,EAAE,EACxD,IAAI,CAAC,YAAY,CAClB,CAAC;IACJ,CAAC;CACF"}

package/dist/runtime/handshake-gate.d.ts

@@ -0,0 +1,35 @@
+import type { HelloMessage } from '../protocol/message.types.js';
+/**
+ * Guards the handshake with the capability nonce the host appended to the
+ * preview URL as `#fcd=<uuid>`. The fragment never reaches the server; the
+ * gate captures it on construction, parks it in sessionStorage (so it
+ * survives iframe reloads and client-side navigations) and strips only the
+ * `fcd` key from the hash. Without a nonce every HELLO is ignored silently —
+ * an arbitrary page embedding the storefront learns nothing.
+ */
+export declare class HandshakeGate {
+    private readonly win;
+    private readonly nonce;
+    private pinnedOrigin;
+    constructor(win: Window);
+    /** True when a nonce was captured from the fragment or sessionStorage. */
+    get hasNonce(): boolean;
+    /**
+     * Validates a HELLO against the full rejection matrix: the sender must be
+     * the direct parent window, carry a real (non-opaque) origin, present the
+     * exact nonce and speak our protocol version. The first success pins the
+     * sender's origin; a re-HELLO (host re-handshake after an iframe reload it
+     * did not observe) must come from that same pinned origin.
+     */
+    acceptHello(event: MessageEvent, message: HelloMessage): boolean;
+    /** The origin pinned by the first accepted HELLO, or null before that. */
+    getPinnedOrigin(): string | null;
+    private captureNonce;
+    private extractFragmentNonce;
+    /**
+     * Removes only the `fcd` key from the hash via history.replaceState —
+     * sibling fragment keys (`#a=b&fcd=x`) and the rest of the URL stay
+     * untouched, and no navigation or hashchange event is triggered.
+     */
+    private stripFragmentKey;
+}

package/dist/runtime/handshake-gate.js

@@ -0,0 +1,81 @@
+import { FRAGMENT_KEY, NONCE_STORAGE_KEY, PROTOCOL_VERSION, } from '../protocol/protocol.constant.js';
+/**
+ * Guards the handshake with the capability nonce the host appended to the
+ * preview URL as `#fcd=<uuid>`. The fragment never reaches the server; the
+ * gate captures it on construction, parks it in sessionStorage (so it
+ * survives iframe reloads and client-side navigations) and strips only the
+ * `fcd` key from the hash. Without a nonce every HELLO is ignored silently —
+ * an arbitrary page embedding the storefront learns nothing.
+ */
+export class HandshakeGate {
+    win;
+    nonce;
+    pinnedOrigin = null;
+    constructor(win) {
+        this.win = win;
+        this.nonce = this.captureNonce();
+    }
+    /** True when a nonce was captured from the fragment or sessionStorage. */
+    get hasNonce() {
+        return this.nonce !== null;
+    }
+    /**
+     * Validates a HELLO against the full rejection matrix: the sender must be
+     * the direct parent window, carry a real (non-opaque) origin, present the
+     * exact nonce and speak our protocol version. The first success pins the
+     * sender's origin; a re-HELLO (host re-handshake after an iframe reload it
+     * did not observe) must come from that same pinned origin.
+     */
+    acceptHello(event, message) {
+        if (this.nonce === null)
+            return false;
+        if (event.source !== this.win.parent)
+            return false;
+        if (!event.origin || event.origin === 'null')
+            return false;
+        if (message.nonce !== this.nonce)
+            return false;
+        if (message.protocolVersion !== PROTOCOL_VERSION)
+            return false;
+        if (this.pinnedOrigin !== null && event.origin !== this.pinnedOrigin)
+            return false;
+        this.pinnedOrigin = event.origin;
+        return true;
+    }
+    /** The origin pinned by the first accepted HELLO, or null before that. */
+    getPinnedOrigin() {
+        return this.pinnedOrigin;
+    }
+    captureNonce() {
+        const fromFragment = this.extractFragmentNonce();
+        if (fromFragment === null) {
+            return this.win.sessionStorage.getItem(NONCE_STORAGE_KEY);
+        }
+        this.win.sessionStorage.setItem(NONCE_STORAGE_KEY, fromFragment);
+        this.stripFragmentKey();
+        return fromFragment;
+    }
+    extractFragmentNonce() {
+        const hash = this.win.location.hash;
+        if (!hash.startsWith('#'))
+            return null;
+        const value = new URLSearchParams(hash.slice(1)).get(FRAGMENT_KEY);
+        if (value === null || value.length === 0)
+            return null;
+        return value;
+    }
+    /**
+     * Removes only the `fcd` key from the hash via history.replaceState —
+     * sibling fragment keys (`#a=b&fcd=x`) and the rest of the URL stay
+     * untouched, and no navigation or hashchange event is triggered.
+     */
+    stripFragmentKey() {
+        const { location, history } = this.win;
+        const params = new URLSearchParams(location.hash.slice(1));
+        params.delete(FRAGMENT_KEY);
+        const remaining = params.toString();
+        const hash = remaining.length > 0 ? `#${remaining}` : '';
+        history.replaceState(history.state, '', `${location.pathname}${location.search}${hash}`);
+    }
+}
+//# sourceMappingURL=handshake-gate.js.map

package/dist/runtime/handshake-gate.js.map

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

package/dist/runtime/highlight/highlight-overlay.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Visual highlight for host-selected elements. One container `<div>` marked
+ * with `data-fc-designer-overlay` is lazily appended to `<body>` (fixed,
+ * full-viewport, pointer-events none — invisible to hit-testing via the
+ * overlay-skip in DomHitTester) and filled with absolutely positioned boxes
+ * at each shown element's current rect. The shown element list is retained
+ * so `refresh()` can re-position the boxes after scroll/resize.
+ */
+export declare class HighlightOverlay {
+    private readonly doc;
+    private container;
+    private shown;
+    constructor(doc: Document);
+    /** Replaces all highlight boxes with boxes for `elements`. */
+    show(elements: Element[]): void;
+    /** Re-positions the boxes at the shown elements' current rects. */
+    refresh(): void;
+    /** Removes every box; the container stays mounted for the next show. */
+    clear(): void;
+    /** Full teardown: boxes and container are removed from the document. */
+    dispose(): void;
+    private renderBoxes;
+    private ensureContainer;
+    private createBox;
+}

package/dist/runtime/highlight/highlight-overlay.js

@@ -0,0 +1,80 @@
+import { OVERLAY_ATTRIBUTE } from '../../protocol/protocol.constant.js';
+/** z-index one below the maximum, leaving room for true emergency chrome. */
+const OVERLAY_Z_INDEX = '2147483646';
+const BOX_BORDER = '2px solid rgba(99, 102, 241, 0.95)';
+const BOX_FILL = 'rgba(99, 102, 241, 0.12)';
+/**
+ * Visual highlight for host-selected elements. One container `<div>` marked
+ * with `data-fc-designer-overlay` is lazily appended to `<body>` (fixed,
+ * full-viewport, pointer-events none — invisible to hit-testing via the
+ * overlay-skip in DomHitTester) and filled with absolutely positioned boxes
+ * at each shown element's current rect. The shown element list is retained
+ * so `refresh()` can re-position the boxes after scroll/resize.
+ */
+export class HighlightOverlay {
+    doc;
+    container = null;
+    shown = [];
+    constructor(doc) {
+        this.doc = doc;
+    }
+    /** Replaces all highlight boxes with boxes for `elements`. */
+    show(elements) {
+        this.shown = [...elements];
+        this.renderBoxes();
+    }
+    /** Re-positions the boxes at the shown elements' current rects. */
+    refresh() {
+        if (this.shown.length === 0)
+            return;
+        this.renderBoxes();
+    }
+    /** Removes every box; the container stays mounted for the next show. */
+    clear() {
+        this.shown = [];
+        this.container?.replaceChildren();
+    }
+    /** Full teardown: boxes and container are removed from the document. */
+    dispose() {
+        this.shown = [];
+        this.container?.remove();
+        this.container = null;
+    }
+    renderBoxes() {
+        const container = this.ensureContainer();
+        container.replaceChildren();
+        for (const element of this.shown) {
+            const rect = element.getBoundingClientRect();
+            if (rect.width <= 0 || rect.height <= 0)
+                continue;
+            container.appendChild(this.createBox(rect));
+        }
+    }
+    ensureContainer() {
+        if (this.container !== null)
+            return this.container;
+        const container = this.doc.createElement('div');
+        container.setAttribute(OVERLAY_ATTRIBUTE, '');
+        container.style.position = 'fixed';
+        container.style.inset = '0';
+        container.style.pointerEvents = 'none';
+        container.style.zIndex = OVERLAY_Z_INDEX;
+        this.doc.body.appendChild(container);
+        this.container = container;
+        return container;
+    }
+    createBox(rect) {
+        const box = this.doc.createElement('div');
+        box.style.position = 'absolute';
+        box.style.left = `${String(rect.left)}px`;
+        box.style.top = `${String(rect.top)}px`;
+        box.style.width = `${String(rect.width)}px`;
+        box.style.height = `${String(rect.height)}px`;
+        box.style.boxSizing = 'border-box';
+        box.style.border = BOX_BORDER;
+        box.style.backgroundColor = BOX_FILL;
+        box.style.borderRadius = '2px';
+        return box;
+    }
+}
+//# sourceMappingURL=highlight-overlay.js.map

package/dist/runtime/highlight/highlight-overlay.js.map

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

package/dist/runtime/region/dom-hit-tester.d.ts

@@ -0,0 +1,28 @@
+import type { Point } from '../../protocol/element.types.js';
+/**
+ * Hit-testing seam between the region pipeline and the live document.
+ * jsdom does not implement `elementsFromPoint`, so tests inject a fake that
+ * resolves points against scripted bounds instead of a layout engine.
+ */
+export interface HitTester {
+    /** The full element stack under `point`, topmost first. */
+    elementsAt(point: Point): Element[];
+}
+/**
+ * Production {@link HitTester} backed by `document.elementsFromPoint`. The
+ * raw stack is normalized for selection: our own highlight overlay subtree
+ * is invisible to hit-testing, and SVG-internal elements (paths, groups,
+ * uses) collapse onto their owning `<svg>` root — an icon is one selectable
+ * thing, not a stack of vector primitives.
+ */
+export declare class DomHitTester implements HitTester {
+    private readonly doc;
+    constructor(doc: Document);
+    elementsAt(point: Point): Element[];
+    /**
+     * Climbs an SVG-namespace element to the outermost `<svg>` ancestor.
+     * Namespace comparison (instead of instanceof) is realm-safe and stops at
+     * `<foreignObject>` boundaries, where children are HTML again.
+     */
+    private resolveSvgOwner;
+}

package/dist/runtime/region/dom-hit-tester.js

@@ -0,0 +1,45 @@
+import { OVERLAY_ATTRIBUTE } from '../../protocol/protocol.constant.js';
+const SVG_NAMESPACE = 'http://www.w3.org/2000/svg';
+/**
+ * Production {@link HitTester} backed by `document.elementsFromPoint`. The
+ * raw stack is normalized for selection: our own highlight overlay subtree
+ * is invisible to hit-testing, and SVG-internal elements (paths, groups,
+ * uses) collapse onto their owning `<svg>` root — an icon is one selectable
+ * thing, not a stack of vector primitives.
+ */
+export class DomHitTester {
+    doc;
+    constructor(doc) {
+        this.doc = doc;
+    }
+    elementsAt(point) {
+        const stack = this.doc.elementsFromPoint(point.x, point.y);
+        const seen = new Set();
+        const elements = [];
+        for (const element of stack) {
+            if (element.closest(`[${OVERLAY_ATTRIBUTE}]`) !== null)
+                continue;
+            const resolved = this.resolveSvgOwner(element);
+            if (seen.has(resolved))
+                continue;
+            seen.add(resolved);
+            elements.push(resolved);
+        }
+        return elements;
+    }
+    /**
+     * Climbs an SVG-namespace element to the outermost `<svg>` ancestor.
+     * Namespace comparison (instead of instanceof) is realm-safe and stops at
+     * `<foreignObject>` boundaries, where children are HTML again.
+     */
+    resolveSvgOwner(element) {
+        if (element.namespaceURI !== SVG_NAMESPACE)
+            return element;
+        let owner = element;
+        while (owner.parentElement !== null && owner.parentElement.namespaceURI === SVG_NAMESPACE) {
+            owner = owner.parentElement;
+        }
+        return owner;
+    }
+}
+//# sourceMappingURL=dom-hit-tester.js.map

package/dist/runtime/region/dom-hit-tester.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom-hit-tester.js","sourceRoot":"","sources":["../../../src/runtime/region/dom-hit-tester.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AAYxE,MAAM,aAAa,GAAG,4BAA4B,CAAC;AAEnD;;;;;;GAMG;AACH,MAAM,OAAO,YAAY;IACM;IAA7B,YAA6B,GAAa;QAAb,QAAG,GAAH,GAAG,CAAU;IAAG,CAAC;IAE9C,UAAU,CAAC,KAAY;QACrB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;QAC3D,MAAM,IAAI,GAAG,IAAI,GAAG,EAAW,CAAC;QAChC,MAAM,QAAQ,GAAc,EAAE,CAAC;QAC/B,KAAK,MAAM,OAAO,IAAI,KAAK,EAAE,CAAC;YAC5B,IAAI,OAAO,CAAC,OAAO,CAAC,IAAI,iBAAiB,GAAG,CAAC,KAAK,IAAI;gBAAE,SAAS;YACjE,MAAM,QAAQ,GAAG,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;YAC/C,IAAI,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC;gBAAE,SAAS;YACjC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YACnB,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC1B,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED;;;;OAIG;IACK,eAAe,CAAC,OAAgB;QACtC,IAAI,OAAO,CAAC,YAAY,KAAK,aAAa;YAAE,OAAO,OAAO,CAAC;QAC3D,IAAI,KAAK,GAAG,OAAO,CAAC;QACpB,OAAO,KAAK,CAAC,aAAa,KAAK,IAAI,IAAI,KAAK,CAAC,aAAa,CAAC,YAAY,KAAK,aAAa,EAAE,CAAC;YAC1F,KAAK,GAAG,KAAK,CAAC,aAAa,CAAC;QAC9B,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;CACF"}

package/dist/runtime/region/element-filter.d.ts

@@ -0,0 +1,60 @@
+import type { Rect, Viewport } from '../../protocol/element.types.js';
+/** One element surviving hit-testing, with its spray-coverage evidence. */
+export interface RegionCandidate {
+    element: Element;
+    bounds: Rect;
+    /** Indices of the sampled grid cells whose hit stack contained the element. */
+    hitCells: ReadonlySet<number>;
+    /** Painted fraction of the element: hit cells / cells inside its bounds. */
+    coverage: number;
+}
+/** Ranked, capped selection plus whether candidates were cut by the cap. */
+export interface RankedSelection {
+    candidates: RegionCandidate[];
+    truncated: boolean;
+}
+/**
+ * Selection heuristics for the spray-region pipeline: rejects elements that
+ * can never be meaningful targets, collapses ancestor/descendant stacks down
+ * to the elements the admin plausibly meant, and ranks what is left.
+ */
+export declare class ElementFilter {
+    private readonly win;
+    constructor(win: Window);
+    /**
+     * True when the element is a plausible selection target: visible, has
+     * area, is not document chrome (html/body/head metadata), not a
+     * page-spanning wrapper and not Next.js dev-overlay chrome.
+     */
+    isMeaningful(element: Element, viewport: Viewport): boolean;
+    /**
+     * Collapses ancestor/descendant stacks. Candidates are processed
+     * ancestors-first (sorted by DOM depth) and each surviving parent is
+     * weighed against its surviving candidate descendants:
+     *
+     * 1. Parent wins — the parent itself is well painted (coverage ≥ 0.6) and
+     *    absorbs ≥ 2 candidate descendants: the admin sprayed the group.
+     * 2. Children win — the parent's hit cells are a subset of its candidate
+     *    descendants' union (≤ 1 exclusive cell of tolerance): the parent was
+     *    only ever hit through its children.
+     * 3. Pure-wrapper collapse — exactly one descendant fills ≥ 90% of the
+     *    parent's rect: the parent is a layout wrapper. Wrapper chains unwind
+     *    across the ancestors-first pass because each level sees exactly one
+     *    near-full-size descendant.
+     * 4. Otherwise both genuinely overlap the spray — keep both.
+     */
+    dedupeAncestors(candidates: RegionCandidate[]): RegionCandidate[];
+    /**
+     * Orders survivors by coverage (descending) then area (ascending —
+     * tighter elements over loose containers) and cuts at the cap.
+     */
+    rankAndCap(survivors: RegionCandidate[], maxElements: number | undefined): RankedSelection;
+    private resolveOverlap;
+    /** Cells the parent was hit in that none of its descendants were. */
+    private exclusiveCellCount;
+    private isPureWrapper;
+    private isInvisible;
+    private isNextDevChrome;
+    private domDepth;
+    private rectArea;
+}

package/dist/runtime/region/element-filter.js

@@ -0,0 +1,146 @@
+/** Tags that are never meaningful selection targets. */
+const EXCLUDED_TAGS = new Set([
+    'html',
+    'body',
+    'script',
+    'style',
+    'template',
+    'noscript',
+    'link',
+    'meta',
+    'nextjs-portal',
+]);
+/** Elements covering more than this viewport fraction are page wrappers. */
+const VIEWPORT_COVER_LIMIT = 0.85;
+/** Parent-wins threshold: painted fraction at which a parent absorbs children. */
+const PARENT_COVERAGE_THRESHOLD = 0.6;
+/** Children-win tolerance: cells a parent may own beyond its children's union. */
+const EXCLUSIVE_CELL_TOLERANCE = 1;
+/** Wrapper collapse: child rect fraction at which the parent adds nothing. */
+const WRAPPER_AREA_RATIO = 0.9;
+/** Default and hard maximum for the selection cap. */
+const DEFAULT_MAX_ELEMENTS = 12;
+const HARD_MAX_ELEMENTS = 25;
+/**
+ * Selection heuristics for the spray-region pipeline: rejects elements that
+ * can never be meaningful targets, collapses ancestor/descendant stacks down
+ * to the elements the admin plausibly meant, and ranks what is left.
+ */
+export class ElementFilter {
+    win;
+    constructor(win) {
+        this.win = win;
+    }
+    /**
+     * True when the element is a plausible selection target: visible, has
+     * area, is not document chrome (html/body/head metadata), not a
+     * page-spanning wrapper and not Next.js dev-overlay chrome.
+     */
+    isMeaningful(element, viewport) {
+        if (EXCLUDED_TAGS.has(element.tagName.toLowerCase()))
+            return false;
+        if (this.isNextDevChrome(element))
+            return false;
+        if (this.isInvisible(element))
+            return false;
+        const rect = element.getBoundingClientRect();
+        if (rect.width <= 0 || rect.height <= 0)
+            return false;
+        const viewportArea = viewport.width * viewport.height;
+        if (viewportArea > 0 && rect.width * rect.height > VIEWPORT_COVER_LIMIT * viewportArea) {
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Collapses ancestor/descendant stacks. Candidates are processed
+     * ancestors-first (sorted by DOM depth) and each surviving parent is
+     * weighed against its surviving candidate descendants:
+     *
+     * 1. Parent wins — the parent itself is well painted (coverage ≥ 0.6) and
+     *    absorbs ≥ 2 candidate descendants: the admin sprayed the group.
+     * 2. Children win — the parent's hit cells are a subset of its candidate
+     *    descendants' union (≤ 1 exclusive cell of tolerance): the parent was
+     *    only ever hit through its children.
+     * 3. Pure-wrapper collapse — exactly one descendant fills ≥ 90% of the
+     *    parent's rect: the parent is a layout wrapper. Wrapper chains unwind
+     *    across the ancestors-first pass because each level sees exactly one
+     *    near-full-size descendant.
+     * 4. Otherwise both genuinely overlap the spray — keep both.
+     */
+    dedupeAncestors(candidates) {
+        const sorted = [...candidates].sort((a, b) => this.domDepth(a.element) - this.domDepth(b.element));
+        const dropped = new Set();
+        for (const parent of sorted) {
+            if (dropped.has(parent))
+                continue;
+            const descendants = sorted.filter((candidate) => candidate !== parent &&
+                !dropped.has(candidate) &&
+                parent.element.contains(candidate.element));
+            if (descendants.length === 0)
+                continue;
+            this.resolveOverlap(parent, descendants, dropped);
+        }
+        return sorted.filter((candidate) => !dropped.has(candidate));
+    }
+    /**
+     * Orders survivors by coverage (descending) then area (ascending —
+     * tighter elements over loose containers) and cuts at the cap.
+     */
+    rankAndCap(survivors, maxElements) {
+        const cap = Math.min(maxElements ?? DEFAULT_MAX_ELEMENTS, HARD_MAX_ELEMENTS);
+        const ranked = [...survivors].sort((a, b) => b.coverage - a.coverage || this.rectArea(a.bounds) - this.rectArea(b.bounds));
+        return { candidates: ranked.slice(0, cap), truncated: ranked.length > cap };
+    }
+    resolveOverlap(parent, descendants, dropped) {
+        if (parent.coverage >= PARENT_COVERAGE_THRESHOLD && descendants.length >= 2) {
+            for (const descendant of descendants)
+                dropped.add(descendant);
+            return;
+        }
+        if (this.exclusiveCellCount(parent, descendants) <= EXCLUSIVE_CELL_TOLERANCE) {
+            dropped.add(parent);
+            return;
+        }
+        if (this.isPureWrapper(parent, descendants))
+            dropped.add(parent);
+    }
+    /** Cells the parent was hit in that none of its descendants were. */
+    exclusiveCellCount(parent, descendants) {
+        let exclusive = 0;
+        for (const cell of parent.hitCells) {
+            if (!descendants.some((descendant) => descendant.hitCells.has(cell)))
+                exclusive++;
+        }
+        return exclusive;
+    }
+    isPureWrapper(parent, descendants) {
+        const parentArea = this.rectArea(parent.bounds);
+        const nearFullSize = descendants.filter((descendant) => this.rectArea(descendant.bounds) >= WRAPPER_AREA_RATIO * parentArea);
+        return nearFullSize.length === 1;
+    }
+    isInvisible(element) {
+        const style = this.win.getComputedStyle(element);
+        if (style.visibility === 'hidden' || style.display === 'none')
+            return true;
+        return style.opacity.length > 0 && Number(style.opacity) === 0;
+    }
+    isNextDevChrome(element) {
+        return element
+            .getAttributeNames()
+            .some((attribute) => attribute.startsWith('data-nextjs-'));
+    }
+    domDepth(element) {
+        let depth = 0;
+        let current = element.parentElement;
+        while (current !== null) {
+            depth++;
+            current = current.parentElement;
+        }
+        return depth;
+    }
+    rectArea(rect) {
+        return rect.width * rect.height;
+    }
+}
+//# sourceMappingURL=element-filter.js.map

package/dist/runtime/region/element-filter.js.map

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

package/dist/runtime/region/region-sampler.d.ts

@@ -0,0 +1,41 @@
+import type { Point, Viewport } from '../../protocol/element.types.js';
+/** A successfully rasterized spray region. */
+export interface RegionSampleOk {
+    kind: 'ok';
+    /** Viewport-clamped centers of every grid cell covered by the stroke. */
+    cellCenters: Point[];
+    /** The cell size the budget loop settled on, in CSS pixels. */
+    cellSize: number;
+}
+/** The stroke's padded bounding box exceeds the region budget. */
+export interface RegionSampleTooLarge {
+    kind: 'too-large';
+}
+export type RegionSampleResult = RegionSampleOk | RegionSampleTooLarge;
+/**
+ * Pure stroke-to-grid rasterizer for spray selection. The stroke is walked
+ * at a fixed step and every grid cell whose center lies within the spray
+ * radius of a step point is marked. The grid covers the stroke's padded
+ * bounding box; when the marked-cell count blows the budget the cell size is
+ * doubled and the stroke re-rasterized, trading sampling density for a
+ * bounded number of elementsFromPoint calls downstream.
+ */
+export declare class RegionSampler {
+    sample(stroke: readonly Point[], radius: number, viewport: Viewport): RegionSampleResult;
+    /**
+     * Resamples the stroke polyline at `step`-pixel intervals. Both endpoints
+     * of every segment are included; a single-point stroke yields that point,
+     * so a click-without-drag still samples around the click.
+     */
+    private walkPolyline;
+    /**
+     * Marks the cells covered by the stroke. Instead of testing every grid
+     * cell against every step point, each step point only visits the cell
+     * window its radius can reach — O(steps × (radius / cellSize)²) — and the
+     * covered set is deduplicated through linear cell indices.
+     */
+    private rasterize;
+    private cellCenter;
+    private clampIndex;
+    private isInsideViewport;
+}