@abbox/inspector 0.0.0-stage → 0.3.0

package/dist/runtime/inspector.js

@@ -0,0 +1,137 @@
+import { runtimeElementRefFor } from "./element-ref.js";
+import { extractMetadata, findSourceLocation, sourceKeyFor, sourceMappingStatus, } from "./metadata.js";
+import { createOverlay, hideHighlight, positionHighlight, rectForElement, renderChangeMarkers, } from "./overlay.js";
+export function createInspectorRuntime(options) {
+    const { document: doc, window: win } = options;
+    const overlay = createOverlay(doc);
+    let enabled = false;
+    let hovered = null;
+    const refIdToElement = new Map();
+    let markers = [];
+    let raf = 0;
+    let pendingTarget = null;
+    const teardownListeners = () => {
+        win.removeEventListener("mousemove", onMove, true);
+        win.removeEventListener("click", onClickCapture, true);
+        win.removeEventListener("scroll", onScrollOrResize, true);
+        win.removeEventListener("resize", onScrollOrResize);
+    };
+    const onMove = (event) => {
+        if (!enabled)
+            return;
+        const target = deepestElementAt(doc, event.clientX, event.clientY, event.target);
+        if (!target || !doc.body.contains(target))
+            return;
+        pendingTarget = target;
+        if (raf)
+            return;
+        raf = win.requestAnimationFrame(() => {
+            raf = 0;
+            if (!enabled || !pendingTarget)
+                return;
+            setHover(pendingTarget);
+            pendingTarget = null;
+        });
+    };
+    const onClickCapture = (event) => {
+        if (!enabled)
+            return;
+        event.preventDefault();
+        event.stopPropagation();
+        const target = deepestElementAt(doc, event.clientX, event.clientY, event.target);
+        if (!target || !doc.body.contains(target))
+            return;
+        select(target);
+    };
+    const onScrollOrResize = () => {
+        if (hovered)
+            positionHighlight(overlay.highlight, rectForElement(hovered));
+        if (markers.length) {
+            renderChangeMarkers(overlay.markerLayer, markers, (id) => refIdToElement.get(id) ?? null);
+        }
+    };
+    function payloadFor(el) {
+        const source = findSourceLocation(el);
+        const sourceKey = sourceKeyFor(source);
+        const elementRef = runtimeElementRefFor(el, sourceKey);
+        refIdToElement.set(elementRef.id, el);
+        return {
+            elementRef,
+            rect: rectForElement(el),
+            metadata: extractMetadata(el),
+            source,
+            mappingStatus: sourceMappingStatus(source),
+        };
+    }
+    function setHover(el) {
+        if (hovered === el)
+            return;
+        hovered = el;
+        positionHighlight(overlay.highlight, rectForElement(el));
+        options.onHover?.(payloadFor(el));
+    }
+    function select(el) {
+        hovered = el;
+        positionHighlight(overlay.highlight, rectForElement(el));
+        options.onSelect?.(payloadFor(el));
+    }
+    function clearSelection() {
+        hovered = null;
+        hideHighlight(overlay.highlight);
+        options.onClear?.();
+    }
+    return {
+        enable: () => {
+            if (enabled)
+                return;
+            enabled = true;
+            win.addEventListener("mousemove", onMove, true);
+            win.addEventListener("click", onClickCapture, true);
+            win.addEventListener("scroll", onScrollOrResize, true);
+            win.addEventListener("resize", onScrollOrResize);
+        },
+        disable: () => {
+            if (!enabled)
+                return;
+            enabled = false;
+            teardownListeners();
+            hovered = null;
+            hideHighlight(overlay.highlight);
+            clearSelection();
+        },
+        isEnabled: () => enabled,
+        setChangeMarkers: (next) => {
+            markers = next;
+            renderChangeMarkers(overlay.markerLayer, markers, (id) => refIdToElement.get(id) ?? null);
+        },
+        getElementByRefId: (id) => refIdToElement.get(id) ?? null,
+        destroy: () => {
+            if (enabled) {
+                enabled = false;
+                teardownListeners();
+            }
+            hovered = null;
+            hideHighlight(overlay.highlight);
+            overlay.destroy();
+            refIdToElement.clear();
+        },
+    };
+}
+function deepestElementAt(doc, x, y, fallbackTarget) {
+    if (typeof doc.elementsFromPoint === "function") {
+        const stack = doc.elementsFromPoint(x, y);
+        for (const node of stack) {
+            if (node instanceof Element) {
+                if (node.closest("[data-abbox-inspector]"))
+                    continue;
+                return node;
+            }
+        }
+    }
+    if (fallbackTarget instanceof Element) {
+        if (fallbackTarget.closest("[data-abbox-inspector]"))
+            return null;
+        return fallbackTarget;
+    }
+    return null;
+}

package/dist/runtime/metadata.d.ts

@@ -0,0 +1,6 @@
+import type { ElementMetadata, SourceLocation, SourceMappingStatus } from "../protocol.js";
+export declare function findSourceLocation(el: Element): SourceLocation | null;
+export declare function sourceMappingStatus(source: SourceLocation | null): SourceMappingStatus;
+export declare function extractMetadata(el: Element): ElementMetadata;
+export declare function sourceKeyFor(source: SourceLocation | null): string | null;
+//# sourceMappingURL=metadata.d.ts.map

package/dist/runtime/metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../../src/runtime/metadata.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACd,mBAAmB,EACpB,MAAM,gBAAgB,CAAC;AAYxB,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,OAAO,GAAG,cAAc,GAAG,IAAI,CAarE;AAED,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,cAAc,GAAG,IAAI,GAC5B,mBAAmB,CAGrB;AAED,wBAAgB,eAAe,CAAC,EAAE,EAAE,OAAO,GAAG,eAAe,CAgC5D;AAcD,wBAAgB,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAGzE"}

package/dist/runtime/metadata.js

@@ -0,0 +1,81 @@
+import { ABBBOX_SOURCE_ATTR, parseSourceAttribute, } from "../instrument/constants.js";
+const SENSITIVE_ATTR_PREFIXES = ["data-", "on"];
+const SENSITIVE_ATTR_NAMES = new Set([
+    "value",
+    "nonce",
+    "autocomplete",
+    "name",
+    "href",
+    "src",
+]);
+export function findSourceLocation(el) {
+    let node = el;
+    while (node) {
+        const raw = node.getAttribute(ABBBOX_SOURCE_ATTR);
+        if (raw) {
+            const parsed = parseSourceAttribute(raw);
+            if (parsed) {
+                return { ...parsed, raw };
+            }
+        }
+        node = node.parentElement;
+    }
+    return null;
+}
+export function sourceMappingStatus(source) {
+    if (!source)
+        return "unresolved";
+    return "resolved";
+}
+export function extractMetadata(el) {
+    const tagName = el.tagName.toLowerCase();
+    const id = el.id || null;
+    const classList = Array.from(el.classList);
+    const role = el.getAttribute("role");
+    const ariaLabel = el.getAttribute("aria-label");
+    const textPreview = textPreviewFor(el);
+    const attributes = {};
+    for (const attr of Array.from(el.attributes)) {
+        if (attr.name === ABBBOX_SOURCE_ATTR)
+            continue;
+        if (SENSITIVE_ATTR_NAMES.has(attr.name))
+            continue;
+        if (SENSITIVE_ATTR_PREFIXES.some((p) => attr.name.startsWith(p)) &&
+            attr.name !== "data-testid") {
+            continue;
+        }
+        if (attr.value.length > 120) {
+            attributes[attr.name] = `${attr.value.slice(0, 117)}…`;
+        }
+        else {
+            attributes[attr.name] = attr.value;
+        }
+    }
+    return {
+        tagName,
+        id,
+        classList,
+        role,
+        ariaLabel,
+        textPreview,
+        attributes,
+    };
+}
+function textPreviewFor(el) {
+    const own = Array.from(el.childNodes)
+        .filter((n) => n.nodeType === Node.TEXT_NODE)
+        .map((n) => n.textContent?.trim() ?? "")
+        .join(" ")
+        .trim();
+    if (own)
+        return own.slice(0, 160);
+    const text = el.textContent?.trim() ?? "";
+    if (!text)
+        return null;
+    return text.slice(0, 160);
+}
+export function sourceKeyFor(source) {
+    if (!source)
+        return null;
+    return `${source.file}:${source.line}:${source.column}`;
+}

package/dist/runtime/overlay.d.ts

@@ -0,0 +1,12 @@
+import type { ChangeMarker, ElementRect } from "../protocol.js";
+export type OverlayHandles = {
+    highlight: HTMLDivElement;
+    markerLayer: HTMLDivElement;
+    destroy: () => void;
+};
+export declare function createOverlay(root: Document): OverlayHandles;
+export declare function positionHighlight(highlight: HTMLDivElement, rect: ElementRect): void;
+export declare function hideHighlight(highlight: HTMLDivElement): void;
+export declare function rectForElement(el: Element): ElementRect;
+export declare function renderChangeMarkers(layer: HTMLDivElement, markers: ChangeMarker[], resolveElement: (refId: string) => Element | null): void;
+//# sourceMappingURL=overlay.d.ts.map

package/dist/runtime/overlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay.d.ts","sourceRoot":"","sources":["../../src/runtime/overlay.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAKhE,MAAM,MAAM,cAAc,GAAG;IAC3B,SAAS,EAAE,cAAc,CAAC;IAC1B,WAAW,EAAE,cAAc,CAAC;IAC5B,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CAAC;AAEF,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,GAAG,cAAc,CAiC5D;AAED,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,cAAc,EACzB,IAAI,EAAE,WAAW,GAChB,IAAI,CAQN;AAED,wBAAgB,aAAa,CAAC,SAAS,EAAE,cAAc,GAAG,IAAI,CAE7D;AAED,wBAAgB,cAAc,CAAC,EAAE,EAAE,OAAO,GAAG,WAAW,CAQvD;AAID,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,cAAc,EACrB,OAAO,EAAE,YAAY,EAAE,EACvB,cAAc,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,GAAG,IAAI,GAChD,IAAI,CAoCN"}

package/dist/runtime/overlay.js

@@ -0,0 +1,104 @@
+const HIGHLIGHT_Z = 2147483646;
+const MARKER_Z = 2147483645;
+export function createOverlay(root) {
+    const highlight = root.createElement("div");
+    highlight.setAttribute("data-abbox-inspector", "highlight");
+    Object.assign(highlight.style, {
+        position: "fixed",
+        pointerEvents: "none",
+        border: "2px solid #2563eb",
+        background: "rgba(37, 99, 235, 0.12)",
+        borderRadius: "2px",
+        zIndex: String(HIGHLIGHT_Z),
+        display: "none",
+        boxSizing: "border-box",
+    });
+    const markerLayer = root.createElement("div");
+    markerLayer.setAttribute("data-abbox-inspector", "markers");
+    Object.assign(markerLayer.style, {
+        position: "fixed",
+        inset: "0",
+        pointerEvents: "none",
+        zIndex: String(MARKER_Z),
+    });
+    root.body.append(highlight, markerLayer);
+    return {
+        highlight,
+        markerLayer,
+        destroy: () => {
+            highlight.remove();
+            markerLayer.remove();
+        },
+    };
+}
+export function positionHighlight(highlight, rect) {
+    Object.assign(highlight.style, {
+        display: "block",
+        left: `${rect.x}px`,
+        top: `${rect.y}px`,
+        width: `${rect.width}px`,
+        height: `${rect.height}px`,
+    });
+}
+export function hideHighlight(highlight) {
+    highlight.style.display = "none";
+}
+export function rectForElement(el) {
+    const r = el.getBoundingClientRect();
+    return {
+        x: r.x,
+        y: r.y,
+        width: r.width,
+        height: r.height,
+    };
+}
+const markerNodes = new Map();
+export function renderChangeMarkers(layer, markers, resolveElement) {
+    for (const [id, node] of markerNodes) {
+        if (!markers.some((m) => m.elementRefId === id)) {
+            node.remove();
+            markerNodes.delete(id);
+        }
+    }
+    for (const marker of markers) {
+        const el = resolveElement(marker.elementRefId);
+        if (!el)
+            continue;
+        const rect = el.getBoundingClientRect();
+        let dot = markerNodes.get(marker.elementRefId);
+        if (!dot) {
+            dot = layer.ownerDocument.createElement("div");
+            dot.setAttribute("data-abbox-change-marker", marker.kind);
+            dot.title = marker.label;
+            Object.assign(dot.style, {
+                position: "fixed",
+                width: "12px",
+                height: "12px",
+                borderRadius: "50%",
+                background: marker.kind === "mock" ? "#f59e0b" : "#ef4444",
+                border: "2px solid #fff",
+                boxShadow: "0 0 0 1px rgba(0,0,0,0.2)",
+                pointerEvents: "none",
+            });
+            if (marker.pulse !== false) {
+                dot.style.animation = "abbox-inspector-pulse 1.4s ease-in-out infinite";
+                ensurePulseStyle(layer.ownerDocument);
+            }
+            layer.append(dot);
+            markerNodes.set(marker.elementRefId, dot);
+        }
+        dot.style.left = `${rect.right - 8}px`;
+        dot.style.top = `${rect.top - 4}px`;
+    }
+}
+function ensurePulseStyle(doc) {
+    if (doc.getElementById("abbox-inspector-pulse-style"))
+        return;
+    const style = doc.createElement("style");
+    style.id = "abbox-inspector-pulse-style";
+    style.textContent = `@keyframes abbox-inspector-pulse {
+    0%, 100% { transform: scale(1); opacity: 1; }
+    50% { transform: scale(1.35); opacity: 0.75; }
+  }`;
+    doc.head.append(style);
+}

package/dist/vite-plugin.d.ts

@@ -0,0 +1,8 @@
+import type { Plugin } from "vite";
+export type AbboxInspectorViteOptions = {
+    rootDir?: string;
+    /** When false, instrumentation is skipped (e.g. production builds). */
+    enabled?: boolean;
+};
+export declare function abboxInspectorVitePlugin(options?: AbboxInspectorViteOptions): Plugin;
+//# sourceMappingURL=vite-plugin.d.ts.map

package/dist/vite-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite-plugin.d.ts","sourceRoot":"","sources":["../src/vite-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAGnC,MAAM,MAAM,yBAAyB,GAAG;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF,wBAAgB,wBAAwB,CACtC,OAAO,GAAE,yBAA8B,GACtC,MAAM,CAuBR"}

package/dist/vite-plugin.js

@@ -0,0 +1,29 @@
+import { abboxSourceBabelPlugin } from "./instrument/babel-plugin.js";
+export function abboxInspectorVitePlugin(options = {}) {
+    const enabled = options.enabled ?? true;
+    const rootDir = options.rootDir ?? process.cwd();
+    return {
+        name: "abbox-inspector-vite",
+        enforce: "pre",
+        async transform(code, id) {
+            if (!enabled)
+                return null;
+            if (!/\.(tsx|jsx)$/.test(id))
+                return null;
+            if (id.includes("node_modules"))
+                return null;
+            const babel = await import("@babel/core");
+            const result = await babel.transformAsync(code, {
+                filename: id,
+                cwd: rootDir,
+                babelrc: false,
+                configFile: false,
+                plugins: [[abboxSourceBabelPlugin, { rootDir }]],
+                sourceMaps: true,
+            });
+            if (!result?.code)
+                return null;
+            return { code: result.code, map: result.map ?? undefined };
+        },
+    };
+}

package/docs/TRUST.md

@@ -0,0 +1,25 @@
+# Trust model (Live Preview & production inspection)
+
+## What is protected
+
+- **Default (preview-only install)**: `VERCEL_ENV=production` deploys have no JSX instrumentation, no `frame-ancestors` for the viewer, and client bootstrap does not run.
+- **Preview deployments** (`VERCEL_ENV=preview`): instrumentation and iframe embedding headers at build time; runtime follows baked preview mode.
+- **Production inspection (explicit opt-in via `@abbox/cli init --mode production`)**: production Vercel builds use webpack instrumentation and bake `NEXT_PUBLIC_ABBOX_INSPECTION_MODE=production`. Runtime still requires a baked mode flag — query parameters alone cannot enable inspection.
+- **Production runtime**: requires `abboxSession` **and** `abboxHostOrigin` matching the Viewer origin configured at install (`NEXT_PUBLIC_ABBOX_VIEWER_ORIGIN`). No broad Viewer fallback list.
+- **postMessage**: channel, version, session id, and origin allow-lists on host and client. No `targetOrigin: "*"`.
+- **Viewer**: preview targets use a host allow-list; production website mode accepts customer HTTPS origins (customer must have opted in on their site).
+
+## What is not authentication
+
+- `VERCEL_ENV=preview` only means “this build was a Vercel preview deployment.” Anyone with the preview URL can load that deployment.
+- `abboxSession` is a protocol correlation id generated by the Viewer, not proof that the Viewer user owns the embedded site.
+- **Production inspection opt-in** means the site owner deliberately ships instrumentation and `frame-ancestors` allowing the configured Viewer. That is explicit capability exposure, not cryptographic proof of ownership.
+- Abbox does not receive page contents or credentials in this milestone; inspection stays between the Viewer and the customer origin via `postMessage`.
+
+## CSP
+
+`withAbboxInspector` adds `Content-Security-Policy: frame-ancestors …` without removing other CSP headers you configure. Remove conflicting `X-Frame-Options: DENY` in your platform if embedding fails.
+
+## Server-side authorization
+
+This milestone does **not** include a backend that verifies domain ownership. Customers who need stronger guarantees should treat production inspection as a controlled internal tool or wait for a future domain-verification flow.

package/docs/architecture.md

@@ -0,0 +1,21 @@
+# Architecture
+
+## Layers
+
+1. **Protocol** (`src/protocol.ts`) — versioned `postMessage` envelopes (`abbox-inspector` channel).
+2. **Instrumentation** (`src/instrument/`) — Babel plugin writing `data-abbox-src` on JSX.
+3. **Runtime** (`src/runtime/`) — hover highlight, click-to-select (capture phase, default actions prevented in inspect mode), change-marker dots.
+4. **Host bridge** (`src/host/`) — origin + session validation; client runs inside preview, host runs in Viewer.
+5. **IR match** (`src/ir-match.ts`) — optional file:line index for Product IR records (viewer builds the index).
+
+## Identity
+
+- **Runtime element ref** — assigned per DOM node for the preview session (`el_1`, …).
+- **Source key** — `file:line:column` from instrumentation (not stable across commits).
+- Future PR diffing should attach markers by runtime ref or source key at preview time; diff computation stays outside this package.
+
+## Security
+
+- Messages require matching `sessionId`, `channel`, and `version`.
+- Origins are explicitly allow-listed (preview origin on the host; viewer origin on the client).
+- No `postMessage` target `*`.

package/docs/implementation-report.md

@@ -0,0 +1,23 @@
+# Implementation report (milestone 1)
+
+## Delivered
+
+- Standalone `abbox-inspector` package with protocol, runtime overlay, host/client bridges, Babel JSX instrumentation, IR match helpers, Vitest suite, Vite example on port 5174.
+- **Next.js**: `withAbboxInspector`, `next-babel` helper, `AbboxInspectorBoot`, package `default` export conditions for Next config loading.
+- **TodoDreams** integration (local, uncommitted): `dev:abbox`, Babel + webpack, iframe CSP, client boot.
+- Viewer **Live Preview** workspace; PM sidebar with provenance-labeled compiler/interpreter facts; improved IR match confidence (`exact` / `ambiguous` / `fuzzy` / `none`).
+- Mock change marker button; markers clear when inspect mode disables.
+
+## Onlook
+
+Reviewed overlay and instrumentation approaches under their OSS license. Adopted: capture-phase selection, fixed overlay layers, build-time source attributes. Rejected: bundling Onlook as a dependency; full editor coupling.
+
+## Tests
+
+Run `npm run ci` in `abbox-inspector` and `abbox-viewer` after `npm install` (viewer depends on `file:../abbox-inspector`).
+
+## Future GitHub diff
+
+- Host will supply `ChangeMarker[]` from branch comparison.
+- Inspector positions markers using `elementRefId` from the active preview session.
+- Stable mapping may later combine IR ids (`sec_*`, `elm_*`) with source hashes.

package/docs/integration.md

@@ -0,0 +1,21 @@
+# Integration
+
+## Preview application
+
+1. Add dependency: `"abbox-inspector": "file:../abbox-inspector"` (or published package).
+2. Enable Babel plugin in Vite React config or use `abboxInspectorVitePlugin`.
+3. Call `bootstrapInspectorPreview()` once at startup (see `example/`).
+
+## Abbox Viewer
+
+- New hash route `#/inspector` and **Live Preview** nav item.
+- `VisualInspectorView` embeds an iframe and uses `createInspectorHost`.
+- Product IR sidebar uses `buildProductIrFileLineIndex` + `matchSourceToIr`.
+
+## Environment
+
+Viewer optional env: `VITE_ABBOX_PREVIEW_URL` (default `http://localhost:5174/?abboxSession=local-dev`).
+
+## Change markers (mock)
+
+Host sends `APPLY_CHANGE_MARKERS` with `{ elementRefId, label, kind: "mock" }`. The runtime draws a pulsing dot; this is demonstration-only until a branch diff service exists.

package/docs/known-limitations.md

@@ -0,0 +1,8 @@
+# Known limitations
+
+- **Instrumentation coverage** — only JSX/TSX files processed by the Babel plugin; dynamic `createElement` calls are not mapped.
+- **Source stability** — line/column identities shift when unrelated lines are edited; no cross-commit stable element IDs yet.
+- **Product IR match** — file:line index only; many runtime selections will not match IR until paths align with compiler evidence.
+- **iframe** — auth-gated apps, strict CSP, or `X-Frame-Options` may block embedding; the viewer surfaces load errors without breaking other tabs.
+- **Fiber** — React Fiber mapping is not required and not implemented in this milestone.
+- **Next.js** — example uses Vite; Next.js integration uses the same Babel plugin via `next.config` `babel` customization (documented path, not shipped as a preset here).

package/docs/nextjs-integration.md

@@ -0,0 +1,35 @@
+# Next.js integration
+
+## Requirements
+
+- **App Router** with `app/layout.tsx`
+- **Webpack** for instrumented builds (see `scripts/abbox-vercel-build.mjs` from `@abbox/cli init`)
+- **babel-loader** devDependency (added by CLI)
+
+## Install
+
+```bash
+npx @abbox/cli init
+npx @abbox/cli doctor
+```
+
+## How instrumentation works
+
+- **No root `babel.config.js`** — avoids forcing Babel for the whole app (which breaks `next/font`).
+- `withAbboxInspector()` adds a **webpack `babel-loader` rule** for `app/**` and `components/**` JSX/TSX.
+- **`app/layout.tsx` is excluded** so `next/font` stays on SWC.
+
+## Local dev
+
+```bash
+npm run dev:abbox
+```
+
+## Vercel
+
+- **Preview**: `VERCEL_ENV=preview` → `next build --webpack` + inspector headers/runtime.
+- **Production**: default `next build` (Turbopack) without instrumentation.
+
+## Trust
+
+See [TRUST.md](./TRUST.md).

package/package.json

@@ -1,6 +1,92 @@
 {
   "name": "@abbox/inspector",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Runtime visual inspection for React/Next.js previews with source-backed element selection.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "engines": {
+    "node": ">=22.12"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/browser.d.ts",
+      "import": "./dist/browser.js",
+      "default": "./dist/browser.js"
+    },
+    "./node": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime/bootstrap.d.ts",
+      "import": "./dist/runtime/bootstrap.js",
+      "default": "./dist/runtime/bootstrap.js"
+    },
+    "./vite": {
+      "types": "./dist/vite-plugin.d.ts",
+      "import": "./dist/vite-plugin.js",
+      "default": "./dist/vite-plugin.js"
+    },
+    "./next": {
+      "types": "./dist/next/index.d.ts",
+      "import": "./dist/next/index.js",
+      "default": "./dist/next/index.js"
+    },
+    "./next-babel": "./src/next/babel-config.cjs",
+    "./babel": {
+      "types": "./dist/instrument/babel-plugin.d.ts",
+      "import": "./dist/instrument/babel-plugin.js",
+      "default": "./dist/instrument/babel-plugin.js"
+    },
+    "./react": {
+      "types": "./dist/react/AbboxInspectorBoot.d.ts",
+      "import": "./dist/react/AbboxInspectorBoot.js",
+      "default": "./dist/react/AbboxInspectorBoot.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/next/babel-config.cjs",
+    "src/next/webpack-instrumentation.cjs",
+    "docs",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node -e \"const fs=require('fs');const p='dist/next';fs.mkdirSync(p,{recursive:true});fs.copyFileSync('src/next/webpack-instrumentation.cjs',p+'/webpack-instrumentation.cjs');fs.copyFileSync('src/next/babel-config.cjs',p+'/babel-config.cjs');\"",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && vitest run",
+    "lint": "biome ci .",
+    "format": "biome check --write .",
+    "ci": "npm run typecheck && npm run test && npm run lint && npm run build",
+    "example:dev": "npm run build && npm --prefix example run dev",
+    "example:build": "npm run build && npm --prefix example run build"
+  },
+  "dependencies": {
+    "@babel/core": "^7.28.4",
+    "@babel/types": "^7.28.4"
+  },
+  "peerDependencies": {
+    "babel-loader": "^9.2.1 || ^10.0.0",
+    "next": ">=14.0.0",
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "babel-loader": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.3.0",
+    "react": "^19.3.0",
+    "@biomejs/biome": "2.5.15",
+    "@types/babel__core": "^7.20.5",
+    "@types/node": "^22.20.5",
+    "happy-dom": "^20.0.10",
+    "typescript": "^5.7.3",
+    "vitest": "^5.0.4"
+  }
+}

package/src/next/babel-config.cjs

@@ -0,0 +1,40 @@
+/**
+ * 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.ABBBOX_INSPECTION_MODE === "production" ||
+      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 };