@abbox/inspector 0.0.0-stage → 0.2.1

package/README.md

@@ -1,3 +1,52 @@
-# Temporary Holding Version
+# abbox-inspector
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Runtime visual inspection for instrumented React/Next.js previews. Used by **Abbox Viewer** (Live Preview workspace) and embeddable in authorized preview apps.
+
+## Local development
+
+```bash
+cd abbox-inspector
+npm install
+npm run ci
+```
+
+### Example preview (port 5174)
+
+```bash
+npm run example:dev
+```
+
+### With Abbox Viewer
+
+```bash
+# terminal 1
+cd abbox-inspector && npm run example:dev
+
+# terminal 2
+cd abbox-viewer && npm install && npm run dev
+```
+
+Load compiler + interpreter JSON in the viewer, open **Live Preview**, enable **Inspect**, click elements in the iframe.
+
+Query parameters on the preview URL:
+
+- `abboxSession` — must match the viewer session id (default `local-dev`)
+- `abboxHostOrigin` — viewer origin allowed to control inspect mode
+
+## Package exports
+
+| Import | Purpose |
+|--------|---------|
+| `abbox-inspector` | Protocol, host/client bridges, IR match helpers, Babel plugin |
+| `abbox-inspector/runtime` | `bootstrapInspectorPreview()` for preview apps |
+| `abbox-inspector/vite` | Optional Vite transform plugin |
+
+## Instrumentation
+
+Build-time Babel plugin adds `data-abbox-src="relative/path.tsx:line:column"` to JSX opening tags. Paths are relative to the project root; no absolute filesystem paths are emitted.
+
+## Onlook
+
+[Onlook](https://github.com/onlook-dev/onlook) was reviewed for overlay and instrumentation patterns. This package is a small standalone implementation (Apache-2.0); no code was copied wholesale.
+
+See `docs/architecture.md` and `docs/integration.md`.

package/dist/browser.d.ts

@@ -0,0 +1,9 @@
+/** Browser / Viewer-safe entry (no Babel, Vite, or Next build tooling). */
+export * from "./protocol.js";
+export * from "./ir-match.js";
+export * from "./instrument/constants.js";
+export { createInspectorClient } from "./host/client-bridge.js";
+export { createInspectorHost } from "./host/host-bridge.js";
+export { validateIncomingMessage } from "./host/validate.js";
+export { createInspectorRuntime } from "./runtime/inspector.js";
+//# sourceMappingURL=browser.d.ts.map

package/dist/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,2BAA2B,CAAC;AAC1C,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/browser.js

@@ -0,0 +1,8 @@
+/** Browser / Viewer-safe entry (no Babel, Vite, or Next build tooling). */
+export * from "./protocol.js";
+export * from "./ir-match.js";
+export * from "./instrument/constants.js";
+export { createInspectorClient } from "./host/client-bridge.js";
+export { createInspectorHost } from "./host/host-bridge.js";
+export { validateIncomingMessage } from "./host/validate.js";
+export { createInspectorRuntime } from "./runtime/inspector.js";

package/dist/host/client-bridge.d.ts

@@ -0,0 +1,13 @@
+export type InspectorClientOptions = {
+    sessionId: string;
+    /** Origins allowed to control this preview (typically the Viewer origin). */
+    allowedHostOrigins: readonly string[];
+    window?: Window;
+    document?: Document;
+};
+export type InspectorClient = {
+    start: () => void;
+    stop: () => void;
+};
+export declare function createInspectorClient(options: InspectorClientOptions): InspectorClient;
+//# sourceMappingURL=client-bridge.d.ts.map

package/dist/host/client-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-bridge.d.ts","sourceRoot":"","sources":["../../src/host/client-bridge.ts"],"names":[],"mappings":"AAWA,MAAM,MAAM,sBAAsB,GAAG;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB,CAAC;AAEF,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,sBAAsB,GAC9B,eAAe,CAsEjB"}

package/dist/host/client-bridge.js

@@ -0,0 +1,75 @@
+import { ABBBOX_INSPECTOR_CHANNEL, PROTOCOL_VERSION, } from "../protocol.js";
+import { withLocalhostAliases } from "./origin-aliases.js";
+import { createInspectorRuntime } from "../runtime/inspector.js";
+import { validateIncomingMessage } from "./validate.js";
+export function createInspectorClient(options) {
+    const win = options.window ?? globalThis.window;
+    const doc = options.document ?? win.document;
+    const allowedOrigins = withLocalhostAliases(options.allowedHostOrigins);
+    const send = (message) => {
+        if (!win.parent || win.parent === win)
+            return;
+        for (const targetOrigin of allowedOrigins) {
+            win.parent.postMessage(message, targetOrigin);
+        }
+    };
+    const base = () => ({
+        channel: ABBBOX_INSPECTOR_CHANNEL,
+        version: PROTOCOL_VERSION,
+        sessionId: options.sessionId,
+    });
+    const sendReady = () => {
+        const ready = {
+            ...base(),
+            type: "INSPECTOR_READY",
+            previewUrl: win.location.href,
+        };
+        send(ready);
+    };
+    const runtime = createInspectorRuntime({
+        document: doc,
+        window: win,
+        onHover: (payload) => {
+            send({ ...base(), type: "ELEMENT_HOVERED", payload });
+        },
+        onSelect: (payload) => {
+            send({ ...base(), type: "ELEMENT_SELECTED", payload });
+        },
+        onClear: () => {
+            send({ ...base(), type: "ELEMENT_CLEARED" });
+        },
+    });
+    const onMessage = (event) => {
+        const msg = validateIncomingMessage(event.data, event.origin, {
+            sessionId: options.sessionId,
+            allowedOrigins,
+        });
+        if (!msg)
+            return;
+        if (msg.type === "INSPECTOR_HOST_HELLO")
+            sendReady();
+        if (msg.type === "INSPECTOR_ENABLE")
+            runtime.enable();
+        if (msg.type === "INSPECTOR_DISABLE")
+            runtime.disable();
+        if (msg.type === "APPLY_CHANGE_MARKERS") {
+            runtime.setChangeMarkers(msg.markers);
+        }
+    };
+    return {
+        start: () => {
+            win.addEventListener("message", onMessage);
+            sendReady();
+            if (doc.readyState === "complete") {
+                sendReady();
+            }
+            else {
+                win.addEventListener("load", sendReady, { once: true });
+            }
+        },
+        stop: () => {
+            win.removeEventListener("message", onMessage);
+            runtime.destroy();
+        },
+    };
+}

package/dist/host/host-bridge.d.ts

@@ -0,0 +1,34 @@
+import { type ChangeMarker, type ClientToHostMessage } from "../protocol.js";
+export type InspectorHostOptions = {
+    sessionId: string;
+    /** Origin of the embedded preview (iframe src origin). */
+    previewOrigin: string;
+    /** Viewer origin (allowed to receive messages). */
+    hostOrigin: string;
+    getPreviewWindow: () => Window | null;
+};
+type HoverPayload = Extract<ClientToHostMessage, {
+    type: "ELEMENT_HOVERED";
+}>["payload"];
+type SelectPayload = Extract<ClientToHostMessage, {
+    type: "ELEMENT_SELECTED";
+}>["payload"];
+export type InspectorHostHandlers = {
+    onReady?: (previewUrl: string) => void;
+    onHover?: (payload: HoverPayload) => void;
+    onSelect?: (payload: SelectPayload) => void;
+    onCleared?: () => void;
+    onError?: (code: string, message: string) => void;
+};
+export type InspectorHost = {
+    connect: () => void;
+    disconnect: () => void;
+    enableInspect: () => void;
+    disableInspect: () => void;
+    applyChangeMarkers: (markers: ChangeMarker[]) => void;
+    /** Ask the preview to resend INSPECTOR_READY (call after iframe load). */
+    pingPreview: () => void;
+};
+export declare function createInspectorHost(options: InspectorHostOptions, handlers: InspectorHostHandlers): InspectorHost;
+export {};
+//# sourceMappingURL=host-bridge.d.ts.map

package/dist/host/host-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-bridge.d.ts","sourceRoot":"","sources":["../../src/host/host-bridge.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,mBAAmB,EAGzB,MAAM,gBAAgB,CAAC;AAIxB,MAAM,MAAM,oBAAoB,GAAG;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,aAAa,EAAE,MAAM,CAAC;IACtB,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;CACvC,CAAC;AAEF,KAAK,YAAY,GAAG,OAAO,CACzB,mBAAmB,EACnB;IAAE,IAAI,EAAE,iBAAiB,CAAA;CAAE,CAC5B,CAAC,SAAS,CAAC,CAAC;AACb,KAAK,aAAa,GAAG,OAAO,CAC1B,mBAAmB,EACnB;IAAE,IAAI,EAAE,kBAAkB,CAAA;CAAE,CAC7B,CAAC,SAAS,CAAC,CAAC;AAEb,MAAM,MAAM,qBAAqB,GAAG;IAClC,OAAO,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,IAAI,CAAC;IAC1C,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,IAAI,CAAC;IAC5C,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACnD,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,aAAa,EAAE,MAAM,IAAI,CAAC;IAC1B,cAAc,EAAE,MAAM,IAAI,CAAC;IAC3B,kBAAkB,EAAE,CAAC,OAAO,EAAE,YAAY,EAAE,KAAK,IAAI,CAAC;IACtD,0EAA0E;IAC1E,WAAW,EAAE,MAAM,IAAI,CAAC;CACzB,CAAC;AAEF,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,oBAAoB,EAC7B,QAAQ,EAAE,qBAAqB,GAC9B,aAAa,CAwDf"}

package/dist/host/host-bridge.js

@@ -0,0 +1,59 @@
+import { ABBBOX_INSPECTOR_CHANNEL, PROTOCOL_VERSION, } from "../protocol.js";
+import { withLocalhostAliases } from "./origin-aliases.js";
+import { postToTarget, validateIncomingMessage } from "./validate.js";
+export function createInspectorHost(options, handlers) {
+    const base = () => ({
+        channel: ABBBOX_INSPECTOR_CHANNEL,
+        version: PROTOCOL_VERSION,
+        sessionId: options.sessionId,
+    });
+    const send = (message) => {
+        const target = options.getPreviewWindow();
+        if (!target)
+            return;
+        postToTarget(target, message, options.previewOrigin);
+    };
+    const onMessage = (event) => {
+        const msg = validateIncomingMessage(event.data, event.origin, {
+            sessionId: options.sessionId,
+            allowedOrigins: withLocalhostAliases([options.previewOrigin]),
+        });
+        if (!msg)
+            return;
+        if (msg.type === "INSPECTOR_READY") {
+            handlers.onReady?.(msg.previewUrl);
+        }
+        if (msg.type === "ELEMENT_HOVERED") {
+            handlers.onHover?.(msg.payload);
+        }
+        if (msg.type === "ELEMENT_SELECTED") {
+            handlers.onSelect?.(msg.payload);
+        }
+        if (msg.type === "ELEMENT_CLEARED") {
+            handlers.onCleared?.();
+        }
+        if (msg.type === "INSPECTOR_ERROR") {
+            handlers.onError?.(msg.code, msg.message);
+        }
+    };
+    return {
+        connect: () => {
+            globalThis.window.addEventListener("message", onMessage);
+        },
+        disconnect: () => {
+            globalThis.window.removeEventListener("message", onMessage);
+        },
+        enableInspect: () => {
+            send({ ...base(), type: "INSPECTOR_ENABLE" });
+        },
+        disableInspect: () => {
+            send({ ...base(), type: "INSPECTOR_DISABLE" });
+        },
+        applyChangeMarkers: (markers) => {
+            send({ ...base(), type: "APPLY_CHANGE_MARKERS", markers });
+        },
+        pingPreview: () => {
+            send({ ...base(), type: "INSPECTOR_HOST_HELLO" });
+        },
+    };
+}

package/dist/host/origin-aliases.d.ts

@@ -0,0 +1,3 @@
+/** Accept localhost vs 127.0.0.1 when the Viewer and preview disagree on hostname. */
+export declare function withLocalhostAliases(origins: readonly string[]): string[];
+//# sourceMappingURL=origin-aliases.d.ts.map

package/dist/host/origin-aliases.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"origin-aliases.d.ts","sourceRoot":"","sources":["../../src/host/origin-aliases.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,SAAS,MAAM,EAAE,GACzB,MAAM,EAAE,CAWV"}

package/dist/host/origin-aliases.js

@@ -0,0 +1,13 @@
+/** Accept localhost vs 127.0.0.1 when the Viewer and preview disagree on hostname. */
+export function withLocalhostAliases(origins) {
+    const set = new Set(origins);
+    for (const origin of origins) {
+        if (origin.includes("://localhost")) {
+            set.add(origin.replace("://localhost", "://127.0.0.1"));
+        }
+        if (origin.includes("://127.0.0.1")) {
+            set.add(origin.replace("://127.0.0.1", "://localhost"));
+        }
+    }
+    return [...set];
+}

package/dist/host/validate.d.ts

@@ -0,0 +1,8 @@
+import { type InspectorMessage } from "../protocol.js";
+export type ValidateOptions = {
+    sessionId: string;
+    allowedOrigins: readonly string[];
+};
+export declare function validateIncomingMessage(data: unknown, origin: string, options: ValidateOptions): InspectorMessage | null;
+export declare function postToTarget(target: Window, message: InspectorMessage, targetOrigin: string): void;
+//# sourceMappingURL=validate.d.ts.map

package/dist/host/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/host/validate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,gBAAgB,EAAsB,MAAM,gBAAgB,CAAC;AAE3E,MAAM,MAAM,eAAe,GAAG;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC,CAAC;AAEF,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,eAAe,GACvB,gBAAgB,GAAG,IAAI,CAKzB;AAED,wBAAgB,YAAY,CAC1B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,gBAAgB,EACzB,YAAY,EAAE,MAAM,GACnB,IAAI,CAEN"}

package/dist/host/validate.js

@@ -0,0 +1,13 @@
+import { isInspectorMessage } from "../protocol.js";
+export function validateIncomingMessage(data, origin, options) {
+    if (!options.allowedOrigins.includes(origin))
+        return null;
+    if (!isInspectorMessage(data))
+        return null;
+    if (data.sessionId !== options.sessionId)
+        return null;
+    return data;
+}
+export function postToTarget(target, message, targetOrigin) {
+    target.postMessage(message, targetOrigin);
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { createInspectorClient } from "./host/client-bridge.js";
+export { createInspectorHost } from "./host/host-bridge.js";
+export { validateIncomingMessage } from "./host/validate.js";
+export { abboxSourceBabelPlugin } from "./instrument/babel-plugin.js";
+export * from "./instrument/constants.js";
+export * from "./ir-match.js";
+export { type WithAbboxInspectorOptions, withAbboxInspector, } from "./next/with-abbox-inspector.js";
+export * from "./protocol.js";
+export { createInspectorRuntime } from "./runtime/inspector.js";
+export { abboxInspectorVitePlugin } from "./vite-plugin.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AACtE,cAAc,2BAA2B,CAAC;AAC1C,cAAc,eAAe,CAAC;AAC9B,OAAO,EACL,KAAK,yBAAyB,EAC9B,kBAAkB,GACnB,MAAM,gCAAgC,CAAC;AACxC,cAAc,eAAe,CAAC;AAC9B,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,10 @@
+export { createInspectorClient } from "./host/client-bridge.js";
+export { createInspectorHost } from "./host/host-bridge.js";
+export { validateIncomingMessage } from "./host/validate.js";
+export { abboxSourceBabelPlugin } from "./instrument/babel-plugin.js";
+export * from "./instrument/constants.js";
+export * from "./ir-match.js";
+export { withAbboxInspector, } from "./next/with-abbox-inspector.js";
+export * from "./protocol.js";
+export { createInspectorRuntime } from "./runtime/inspector.js";
+export { abboxInspectorVitePlugin } from "./vite-plugin.js";

package/dist/instrument/babel-plugin.d.ts

@@ -0,0 +1,8 @@
+import type { PluginObj } from "@babel/core";
+export type AbboxSourcePluginOptions = {
+    /** Project root used to relativize filenames. */
+    rootDir?: string;
+};
+export declare function abboxSourceBabelPlugin(_api: unknown, opts?: AbboxSourcePluginOptions): PluginObj;
+export default abboxSourceBabelPlugin;
+//# sourceMappingURL=babel-plugin.d.ts.map

package/dist/instrument/babel-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"babel-plugin.d.ts","sourceRoot":"","sources":["../../src/instrument/babel-plugin.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAI7C,MAAM,MAAM,wBAAwB,GAAG;IACrC,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,OAAO,EACb,IAAI,GAAE,wBAA6B,GAClC,SAAS,CA+BX;AAED,eAAe,sBAAsB,CAAC"}

package/dist/instrument/babel-plugin.js

@@ -0,0 +1,26 @@
+import path from "node:path";
+import * as t from "@babel/types";
+import { ABBBOX_SOURCE_ATTR, formatSourceAttribute } from "./constants.js";
+export function abboxSourceBabelPlugin(_api, opts = {}) {
+    const rootDir = opts.rootDir ?? process.cwd();
+    return {
+        name: "abbox-source-instrumentation",
+        visitor: {
+            JSXOpeningElement(nodePath, state) {
+                const loc = nodePath.node.loc;
+                const filename = state.filename;
+                if (!loc || !filename)
+                    return;
+                const rel = path.relative(rootDir, filename).replace(/\\/g, "/");
+                const value = formatSourceAttribute(rel, loc.start.line, loc.start.column);
+                const hasAttr = nodePath.node.attributes.some((attr) => t.isJSXAttribute(attr) &&
+                    t.isJSXIdentifier(attr.name) &&
+                    attr.name.name === ABBBOX_SOURCE_ATTR);
+                if (hasAttr)
+                    return;
+                nodePath.node.attributes.push(t.jsxAttribute(t.jsxIdentifier(ABBBOX_SOURCE_ATTR), t.stringLiteral(value)));
+            },
+        },
+    };
+}
+export default abboxSourceBabelPlugin;

package/dist/instrument/constants.d.ts

@@ -0,0 +1,10 @@
+/** DOM attribute written by build-time JSX instrumentation. */
+export declare const ABBBOX_SOURCE_ATTR = "data-abbox-src";
+/** Format: `relative/path.tsx:line:column` */
+export declare function formatSourceAttribute(relativeFile: string, line: number, column: number): string;
+export declare function parseSourceAttribute(raw: string): {
+    file: string;
+    line: number;
+    column: number;
+} | null;
+//# sourceMappingURL=constants.d.ts.map

package/dist/instrument/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/instrument/constants.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,eAAO,MAAM,kBAAkB,mBAAmB,CAAC;AAEnD,8CAA8C;AAC9C,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GACb,MAAM,CAGR;AAED,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,IAAI,CAOP"}

package/dist/instrument/constants.js

@@ -0,0 +1,17 @@
+/** DOM attribute written by build-time JSX instrumentation. */
+export const ABBBOX_SOURCE_ATTR = "data-abbox-src";
+/** Format: `relative/path.tsx:line:column` */
+export function formatSourceAttribute(relativeFile, line, column) {
+    const normalized = relativeFile.replace(/\\/g, "/");
+    return `${normalized}:${line}:${column}`;
+}
+export function parseSourceAttribute(raw) {
+    const match = /^(.+):(\d+):(\d+)$/.exec(raw.trim());
+    if (!match)
+        return null;
+    const line = Number.parseInt(match[2], 10);
+    const column = Number.parseInt(match[3], 10);
+    if (!Number.isFinite(line) || !Number.isFinite(column))
+        return null;
+    return { file: match[1], line, column };
+}

package/dist/ir-match.d.ts

@@ -0,0 +1,34 @@
+/** Optional mapping from runtime source locations to Product IR records (viewer-side). */
+export type SourceEvidenceLike = {
+    file?: string;
+    line?: number;
+    column?: number;
+};
+export type IrRecordRef = {
+    kind: "section" | "content" | "element" | "interaction" | "form" | "field" | "navigation";
+    id: string;
+    label?: string;
+    route?: string;
+};
+export type IrMatchConfidence = "exact" | "ambiguous" | "fuzzy" | "none";
+export type IrMatchResult = {
+    matches: IrRecordRef[];
+    confidence: IrMatchConfidence;
+    note?: string;
+};
+export declare function normalizeSourcePath(file: string): string;
+export declare function pathsLikelyEqual(a: string, b: string): boolean;
+export declare function matchSourceToIr(source: {
+    file: string;
+    line: number;
+    column?: number;
+} | null, index: {
+    byFileLine: Map<string, IrRecordRef[]>;
+}, options?: {
+    allowFuzzy?: boolean;
+}): IrMatchResult;
+export declare function buildFileLineIndex(entries: Array<{
+    evidence: SourceEvidenceLike;
+    ref: IrRecordRef;
+}>): Map<string, IrRecordRef[]>;
+//# sourceMappingURL=ir-match.d.ts.map

package/dist/ir-match.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ir-match.d.ts","sourceRoot":"","sources":["../src/ir-match.ts"],"names":[],"mappings":"AAAA,0FAA0F;AAE1F,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EACA,SAAS,GACT,SAAS,GACT,SAAS,GACT,aAAa,GACb,MAAM,GACN,OAAO,GACP,YAAY,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,WAAW,GAAG,OAAO,GAAG,MAAM,CAAC;AAEzE,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,UAAU,EAAE,iBAAiB,CAAC;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAU9D;AA8CD,wBAAgB,eAAe,CAC7B,MAAM,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,EAC9D,KAAK,EAAE;IACL,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC;CACxC,EACD,OAAO,CAAC,EAAE;IAAE,UAAU,CAAC,EAAE,OAAO,CAAA;CAAE,GACjC,aAAa,CAmEf;AAED,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,KAAK,CAAC;IAAE,QAAQ,EAAE,kBAAkB,CAAC;IAAC,GAAG,EAAE,WAAW,CAAA;CAAE,CAAC,GACjE,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC,CAU5B"}

package/dist/ir-match.js

@@ -0,0 +1,129 @@
+/** Optional mapping from runtime source locations to Product IR records (viewer-side). */
+export function normalizeSourcePath(file) {
+    return file.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+export function pathsLikelyEqual(a, b) {
+    const na = normalizeSourcePath(a);
+    const nb = normalizeSourcePath(b);
+    if (na === nb)
+        return true;
+    return (na.endsWith(`/${nb}`) ||
+        nb.endsWith(`/${na}`) ||
+        na.endsWith(nb) ||
+        nb.endsWith(na));
+}
+function lineKey(file, line) {
+    return `${normalizeSourcePath(file)}:${line}`;
+}
+function collectForLine(source, index) {
+    const exact = index.get(lineKey(source.file, source.line)) ?? [];
+    if (exact.length > 0)
+        return exact;
+    const pathMatches = [];
+    for (const [key, refs] of index) {
+        const colon = key.lastIndexOf(":");
+        if (colon <= 0)
+            continue;
+        const filePart = key.slice(0, colon);
+        const linePart = key.slice(colon + 1);
+        const lineNum = Number.parseInt(linePart, 10);
+        if (!Number.isFinite(lineNum))
+            continue;
+        if (pathsLikelyEqual(filePart, source.file) && lineNum === source.line) {
+            pathMatches.push(...refs);
+        }
+    }
+    return pathMatches;
+}
+function uniqueRefs(refs) {
+    const seen = new Set();
+    const out = [];
+    for (const ref of refs) {
+        const k = `${ref.kind}:${ref.id}`;
+        if (seen.has(k))
+            continue;
+        seen.add(k);
+        out.push(ref);
+    }
+    return out;
+}
+function isAmbiguous(refs) {
+    if (refs.length <= 1)
+        return false;
+    const kinds = new Set(refs.map((r) => r.kind));
+    return kinds.size > 1 || refs.length > 3;
+}
+export function matchSourceToIr(source, index, options) {
+    const allowFuzzy = options?.allowFuzzy ?? true;
+    if (!source) {
+        return {
+            matches: [],
+            confidence: "none",
+            note: "No source mapping on this element.",
+        };
+    }
+    const exact = uniqueRefs(collectForLine(source, index.byFileLine));
+    if (exact.length > 0) {
+        if (isAmbiguous(exact)) {
+            return {
+                matches: exact,
+                confidence: "ambiguous",
+                note: "Multiple Product IR records share this source location. Review each match.",
+            };
+        }
+        return {
+            matches: exact,
+            confidence: "exact",
+            note: "Exact file and line match to compiler evidence.",
+        };
+    }
+    if (!allowFuzzy) {
+        return {
+            matches: [],
+            confidence: "none",
+            note: "No Product IR record at this source location.",
+        };
+    }
+    const fuzzy = [];
+    for (const [key, refs] of index.byFileLine) {
+        const colon = key.lastIndexOf(":");
+        if (colon <= 0)
+            continue;
+        const filePart = key.slice(0, colon);
+        const linePart = key.slice(colon + 1);
+        const lineNum = Number.parseInt(linePart, 10);
+        if (!Number.isFinite(lineNum))
+            continue;
+        if (pathsLikelyEqual(filePart, source.file) &&
+            Math.abs(lineNum - source.line) <= 2) {
+            fuzzy.push(...refs);
+        }
+    }
+    const fuzzyUnique = uniqueRefs(fuzzy);
+    if (fuzzyUnique.length > 0) {
+        return {
+            matches: fuzzyUnique.slice(0, 12),
+            confidence: fuzzyUnique.length > 1 || isAmbiguous(fuzzyUnique)
+                ? "ambiguous"
+                : "fuzzy",
+            note: "Nearby line match (±2 lines). Treat as tentative — confirm against source.",
+        };
+    }
+    return {
+        matches: [],
+        confidence: "none",
+        note: "No Product IR record at this source location.",
+    };
+}
+export function buildFileLineIndex(entries) {
+    const map = new Map();
+    for (const { evidence, ref } of entries) {
+        if (!evidence.file || evidence.line === undefined)
+            continue;
+        const key = lineKey(evidence.file, evidence.line);
+        const list = map.get(key) ?? [];
+        list.push(ref);
+        map.set(key, list);
+    }
+    return map;
+}

package/dist/next/babel-config.cjs

@@ -0,0 +1,39 @@
+/**
+ * CommonJS babel config fragment for Next.js apps.
+ * Copy or require from babel.config.cjs when ABBBOX_INSPECTOR=1.
+ */
+const { createRequire } = require("node:module");
+const path = require("node:path");
+
+function createNextBabelConfig(options = {}) {
+  const rootDir = options.rootDir ?? process.cwd();
+  const enabled =
+    options.enabled ??
+    (process.env.ABBBOX_INSPECTOR === "1" ||
+      process.env.NEXT_PUBLIC_ABBOX_INSPECTOR === "1" ||
+      process.env.VERCEL_ENV === "preview");
+
+  const req = createRequire(path.join(rootDir, "package.json"));
+  let pluginPath = "@abbox/inspector/babel";
+  try {
+    pluginPath = req.resolve("@abbox/inspector/babel");
+  } catch {
+    try {
+      pluginPath = req.resolve("abbox-inspector/babel");
+    } catch {
+      pluginPath = req.resolve(
+        path.join(
+          rootDir,
+          "node_modules/@abbox/inspector/dist/instrument/babel-plugin.js",
+        ),
+      );
+    }
+  }
+
+  return {
+    presets: ["next/babel"],
+    plugins: enabled ? [[pluginPath, { rootDir }]] : [],
+  };
+}
+
+module.exports = { createNextBabelConfig };

package/dist/next/index.d.ts

@@ -0,0 +1,3 @@
+export { type WithAbboxInspectorOptions, withAbboxInspector, DEFAULT_VIEWER_FRAME_ANCESTORS, } from "./with-abbox-inspector.js";
+export { isAbboxInspectorBuildEnabled, isAbboxInspectorRuntimeEnabled, } from "./preview-env.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/next/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/next/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,yBAAyB,EAC9B,kBAAkB,EAClB,8BAA8B,GAC/B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,4BAA4B,EAC5B,8BAA8B,GAC/B,MAAM,kBAAkB,CAAC"}

package/dist/next/index.js

@@ -0,0 +1,2 @@
+export { withAbboxInspector, DEFAULT_VIEWER_FRAME_ANCESTORS, } from "./with-abbox-inspector.js";
+export { isAbboxInspectorBuildEnabled, isAbboxInspectorRuntimeEnabled, } from "./preview-env.js";