@lensmcp/react-instrumentation 1.0.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,100 @@
+# @lensmcp/react-instrumentation
+
+Zero-config React instrumentation for LensMCP — a Babel transform plus a render/flow runtime that lets the LensMCP lens *see* a running React app: which components rendered, which hooks re-ran, and how a click in the browser stitches together with the server request and DB query it triggered.
+
+This package is the React-side half of LensMCP's observability lens. A small **Babel plugin** rewrites your JSX at build time (stamping component identity, wrapping `useEffect`/`useMemo`/`useCallback`, wrapping interaction handlers, and wrapping the root render). A matching **runtime** — traced hooks, a `<LensmcpRoot>` wrapper, and a `fetch` wrapper (*flow-fetch*) — emits structured events and propagates a `flowId` across the network boundary so a single user action can be read end to end (click → fetch → server span → DB query).
+
+You normally don't import any of this by hand. [`@lensmcp/vite-plugin`](https://github.com/kiwiapps-ltd/lensmcp) wires the Babel plugin into your React build, injects the publish channel into the served HTML, and bridges the emitted events to the lens. The exports below are available for projects that can't run the global transform (e.g. opt-in tracing) or want to start a flow manually.
+
+## Install
+
+```sh
+yarn add @lensmcp/react-instrumentation
+```
+
+In practice you don't add it directly — it's pulled in and configured by **`@lensmcp/vite-plugin`**, which applies the Babel plugin and sets up the transport. Install it explicitly only for the opt-in, hand-wired path described under [Usage](#usage).
+
+## Usage
+
+**The realistic path (automatic).** Add `@lensmcp/vite-plugin` to your Vite config. It loads this package's Babel plugin, so every component, hook, conditional, and interaction handler in your source is instrumented with no app-code changes — and it installs the publish channel that the runtime emits into.
+
+If you can't run the global transform, the runtime is usable directly:
+
+```tsx
+import { createRoot } from 'react-dom/client';
+import { LensmcpRoot, installFlowFetch } from '@lensmcp/react-instrumentation';
+
+// Wrap browser fetches so they carry the active flow's headers.
+installFlowFetch();
+
+createRoot(document.getElementById('root')!).render(
+  <LensmcpRoot page="home" route="/">
+    <App />
+  </LensmcpRoot>,
+);
+```
+
+(This is exactly what the Babel plugin generates automatically when `autoWrapRoot` is on.) From there you can opt individual pieces in:
+
+```tsx
+import { withTraceComponent, withFlow, tracedUseEffect } from '@lensmcp/react-instrumentation';
+
+// Trace a single component's renders without the global transform.
+const TracedPanel = withTraceComponent(Panel, { source: 'src/Panel.tsx' });
+
+// Start a correlated flow from a handler the transform didn't reach.
+<button onClick={withFlow(save, { originType: 'user-click', originNodeId: 'ui:save' })}>
+  Save
+</button>;
+
+// Drop-in useEffect that emits effect-run / effect-cleanup events.
+tracedUseEffect('Panel:42:0', () => subscribe(), [topic]);
+```
+
+If you build your own bundler integration, point the runtime at your transport with `setPublisher(fn)`; until a publisher is set, every event is buffered (capped) so the library is safe to import in tests and SSR.
+
+## What it captures
+
+- **Component renders** — the Babel transform stamps each JSX element with `data-agent-component` (the component name) and `data-agent-source` (`file:line`), and wraps the root in `<LensmcpRoot>`, whose React `<Profiler>` emits a `render` event (mount/update, durations, commit times) on every commit. `withTraceComponent` does the same for a single opt-in component.
+- **Hooks** — `useEffect`/`useMemo`/`useCallback` are rewritten to traced variants that emit `effect-run` (plus `effect-cleanup`) and `hook-run` events, including a cheap `depsHash` so the lens can tell whether a hook re-ran because its dependencies changed.
+- **Conditional slots** — `<TraceSlot>` emits `slot-content-changed` when the type of the rendered child changes (e.g. a branch swap in a JSX conditional).
+- **Browser→server flow correlation (flow-fetch)** — interaction handlers are wrapped with `withFlow`, which opens a flow with a generated `flowId`. The patched `fetch` injects `x-lensmcp-flow-id` + `x-lensmcp-origin-node-id` headers so the server-side `@lensmcp/nest-instrumentation` stamps its spans and DB queries with the *same* flowId, and it publishes `fetch-start` / `fetch-done` / `fetch-error` legs. A short causality window (and an auto-started `page-load` flow) attributes async post-response re-renders to the action that caused them.
+- **Identity** — stable `logicalId`s for components, hooks, and slots plus per-mount `instanceId`s, so the lens can attribute every event to a specific component instance across re-renders.
+
+## API
+
+Exports from the package entry (`@lensmcp/react-instrumentation`):
+
+| Export | Description |
+| --- | --- |
+| `LensmcpRoot` / `LensmcpRootProps` | Root wrapper: a `<Profiler>` + context provider that emits `render` events and tags hooks with renderer/page/route. |
+| `LensmcpContext` / `useLensmcpContext` / `LensmcpIdentityContext` | React context (and hook) carrying the active renderer/page/route and component instance identity. |
+| `tracedUseEffect` / `tracedUseMemo` / `tracedUseCallback` | Drop-in hook replacements that emit `effect-run`/`hook-run` events; the transform rewrites bare hooks to these. |
+| `TraceSlot` / `TraceSlotProps` | Wrapper that emits `slot-content-changed` when its primary child's type changes. |
+| `withTraceComponent` / `WithTraceOptions` | HOC for opt-in render tracing when the global transform isn't available. |
+| `installFlowFetch` / `FlowFetchOptions` | Monkeypatches `globalThis.fetch` to inject flow headers and publish network legs; returns an uninstall function. |
+| `withFlow` | Wraps an event handler so each call runs inside a fresh correlated flow (idempotent; passes non-functions through). |
+| `runInFlow` / `beginBackgroundFlow` / `currentFlow` / `activeFlow` / `extendFlowWindow` | Flow-stack and causality-window primitives for starting/inspecting/extending flows manually. |
+| `publish` / `setPublisher` / `drainQueue` | The publish channel: emit an event, install the transport, or drain the buffered queue (tests). |
+| `PublishEnvelope` / `PublishCategory` / `FlowSpec` | Types for the publish envelope, event category, and a flow descriptor. |
+| `componentLogicalId` / `hookLogicalId` / `slotLogicalId` / `makeInstanceId` / `depsHash` / `resetIdentityState` | Identity helpers — build stable logical ids, per-mount instance ids, and dependency hashes. |
+| `RenderRecord` / `EffectRecord` / `HookRecord` / `SlotChangeRecord` / `ComponentMountRecord` / `ReactPublishPayload` | Wire-shape types for the events the library publishes. |
+
+Subpath export `@lensmcp/react-instrumentation/babel-plugin` (also re-exported from the entry as `lensmcpBabelPlugin`, with `LensmcpBabelOptions`): the JSX identity transform. Options: `production`, `includeSource`, `rootDir`, `autoWrapHooks`, `autoWrapRoot`, `autoFlowHandlers`, `flowEvents`. It's dev-only — a no-op when `production` is true or `NODE_ENV === 'production'` — and honors `// @lensmcp-ignore` (file) and `data-lensmcp-ignore` (element) opt-outs.
+
+```ts
+// vite.config.ts — applied for you by @lensmcp/vite-plugin
+import lensmcpBabel from '@lensmcp/react-instrumentation/babel-plugin';
+react({ babel: { plugins: [lensmcpBabel] } });
+```
+
+## How it fits
+
+- **Configured by [`@lensmcp/vite-plugin`](https://github.com/kiwiapps-ltd/lensmcp).** The Vite plugin runs `lensmcpBabelPlugin` over your React source and injects a client runtime that sets `window.__LENSMCP_PUBLISH__` — the transport this package's `publish()` looks for. In dev, events flow over a WebSocket to the lens; in production, over the FrontMCP server transport.
+- **Pairs with [`@lensmcp/valtio-instrumentation`](https://github.com/kiwiapps-ltd/lensmcp).** The Vite plugin aliases `valtio` → `@lensmcp/valtio-instrumentation` so state mutations publish into the same channel, and `flowId` correlation lets a render here be tied to the state change (and the fetch) that caused it.
+- **Server side: [`@lensmcp/nest-instrumentation`](https://github.com/kiwiapps-ltd/lensmcp).** Its `TraceInterceptor` reads the `x-lensmcp-flow-id` header set by flow-fetch and stamps server-request, span, and DB-query events with the matching flowId — completing the browser→server story.
+- **Events use [`@lensmcp/protocol-types`](https://github.com/kiwiapps-ltd/lensmcp).** The published record shapes (`RenderPhase`, `RenderWhy`, etc.) mirror the shared protocol so the lens and reducers can consume them.
+
+---
+
+Part of [LensMCP](https://github.com/kiwiapps-ltd/lensmcp). Apache-2.0.

package/index.d.ts

@@ -0,0 +1,11 @@
+export { LensmcpRoot, type LensmcpRootProps } from './lib/lensmcp-root.js';
+export { LensmcpContext, useLensmcpContext, type LensmcpIdentityContext } from './lib/context.js';
+export { tracedUseEffect, tracedUseMemo, tracedUseCallback, } from './lib/traced-hooks.js';
+export { TraceSlot, type TraceSlotProps } from './lib/trace-slot.js';
+export { withTraceComponent, type WithTraceOptions } from './lib/hoc.js';
+export { installFlowFetch, type FlowFetchOptions } from './lib/flow-fetch.js';
+export { publish, setPublisher, drainQueue, runInFlow, currentFlow, activeFlow, extendFlowWindow, beginBackgroundFlow, withFlow, type PublishEnvelope, type PublishCategory, type FlowSpec, } from './lib/publish.js';
+export { componentLogicalId, hookLogicalId, slotLogicalId, makeInstanceId, depsHash, resetIdentityState, } from './lib/identity.js';
+export type { RenderRecord, EffectRecord, HookRecord, SlotChangeRecord, ComponentMountRecord, ReactPublishPayload, } from './lib/types.js';
+export { default as lensmcpBabelPlugin, type LensmcpBabelOptions } from './lib/babel-plugin.js';
+//# sourceMappingURL=index.d.ts.map

package/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC3E,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,KAAK,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAClG,OAAO,EACL,eAAe,EACf,aAAa,EACb,iBAAiB,GAClB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAAE,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACzE,OAAO,EAAE,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC9E,OAAO,EACL,OAAO,EACP,YAAY,EACZ,UAAU,EACV,SAAS,EACT,WAAW,EACX,UAAU,EACV,gBAAgB,EAChB,mBAAmB,EACnB,QAAQ,EACR,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,QAAQ,GACd,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,kBAAkB,EAClB,aAAa,EACb,aAAa,EACb,cAAc,EACd,QAAQ,EACR,kBAAkB,GACnB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,gBAAgB,EAChB,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,OAAO,IAAI,kBAAkB,EAAE,KAAK,mBAAmB,EAAE,MAAM,uBAAuB,CAAC"}

package/index.js

@@ -0,0 +1,9 @@
+export { LensmcpRoot } from './lib/lensmcp-root.js';
+export { LensmcpContext, useLensmcpContext } from './lib/context.js';
+export { tracedUseEffect, tracedUseMemo, tracedUseCallback, } from './lib/traced-hooks.js';
+export { TraceSlot } from './lib/trace-slot.js';
+export { withTraceComponent } from './lib/hoc.js';
+export { installFlowFetch } from './lib/flow-fetch.js';
+export { publish, setPublisher, drainQueue, runInFlow, currentFlow, activeFlow, extendFlowWindow, beginBackgroundFlow, withFlow, } from './lib/publish.js';
+export { componentLogicalId, hookLogicalId, slotLogicalId, makeInstanceId, depsHash, resetIdentityState, } from './lib/identity.js';
+export { default as lensmcpBabelPlugin } from './lib/babel-plugin.js';

package/lib/babel-plugin.d.ts

@@ -0,0 +1,59 @@
+/**
+ * `@lensmcp/react-instrumentation/babel-plugin`
+ *
+ * JSX identity transform. For every `<Component>` / `<div>` in dev:
+ *
+ *   <CardGrid />
+ *   →
+ *   <CardGrid data-agent-component="CardGrid" data-agent-source="src/App.tsx:42" />
+ *
+ * Plus opt-outs:
+ *   - File-level comment `// @lensmcp-ignore` skips the whole file.
+ *   - Element-level `data-lensmcp-ignore` skips that one element.
+ *   - Element-level leading `// @lensmcp-ignore` comment skips it.
+ *
+ * The transform is dev-only: pass `production: true` (or omit it and
+ * rely on the `NODE_ENV` check) to make the plugin a no-op.
+ *
+ * Usage in `vite.config.ts`:
+ *   import lensmcpBabel from '@lensmcp/react-instrumentation/babel-plugin';
+ *   react({ babel: { plugins: [lensmcpBabel] } })
+ */
+import type { PluginObj, PluginPass, types as t } from '@babel/core';
+export interface LensmcpBabelOptions {
+    /** Skip the transform entirely. Default: `process.env.NODE_ENV === 'production'`. */
+    production?: boolean;
+    /** When true, also inject `data-agent-source`. Default: true. */
+    includeSource?: boolean;
+    /** Root path used to make `data-agent-source` relative. Default: cwd. */
+    rootDir?: string;
+    /** Rewrite useEffect/useMemo/useCallback → traced*. Default: true. */
+    autoWrapHooks?: boolean;
+    /** Wrap `createRoot(x).render(<App/>)` with `<LensmcpRoot>` + installFlowFetch. Default: true. */
+    autoWrapRoot?: boolean;
+    /** Wrap JSX interaction handlers (onClick/onSubmit/…) with `withFlow` so a
+     *  user interaction starts a correlated flow. Default: true. */
+    autoFlowHandlers?: boolean;
+    /** Which JSX `on*` attributes start a flow. Default: the intent set below. */
+    flowEvents?: string[];
+}
+interface State extends PluginPass {
+    opts: LensmcpBabelOptions;
+    fileIgnored?: boolean;
+    relativePath?: string;
+    /** traced* helper names this module needs imported. */
+    needHelpers?: Set<string>;
+    /** A root render was wrapped → also import LensmcpRoot + installFlowFetch. */
+    needRoot?: boolean;
+    hookIndex?: number;
+    /** Which `on*` handlers to auto-wrap with `withFlow`. */
+    flowEvents?: Set<string>;
+    /** Local variables holding a `createRoot(...)` result (for `root.render(...)`). */
+    rootVars?: Set<string>;
+}
+interface BabelApi {
+    types: typeof t;
+}
+export default function lensmcpBabelPlugin(api: BabelApi): PluginObj<State>;
+export {};
+//# sourceMappingURL=babel-plugin.d.ts.map

package/lib/babel-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"babel-plugin.d.ts","sourceRoot":"","sources":["../../src/lib/babel-plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EACV,SAAS,EACT,UAAU,EAEV,KAAK,IAAI,CAAC,EACX,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,mBAAmB;IAClC,qFAAqF;IACrF,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,iEAAiE;IACjE,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sEAAsE;IACtE,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,kGAAkG;IAClG,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;oEACgE;IAChE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,8EAA8E;IAC9E,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAuBD,UAAU,KAAM,SAAQ,UAAU;IAChC,IAAI,EAAE,mBAAmB,CAAC;IAC1B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uDAAuD;IACvD,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC1B,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,UAAU,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACzB,mFAAmF;IACnF,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACxB;AAED,UAAU,QAAQ;IAChB,KAAK,EAAE,OAAO,CAAC,CAAC;CACjB;AAED,MAAM,CAAC,OAAO,UAAU,kBAAkB,CAAC,GAAG,EAAE,QAAQ,GAAG,SAAS,CAAC,KAAK,CAAC,CA4M1E"}

package/lib/babel-plugin.js

@@ -0,0 +1,259 @@
+const HELPER_IMPORT = '@lensmcp/react-instrumentation';
+const HOOK_MAP = {
+    useEffect: 'tracedUseEffect',
+    useMemo: 'tracedUseMemo',
+    useCallback: 'tracedUseCallback',
+};
+// User interactions that constitute a flow origin. Deliberately excludes
+// high-frequency events (mousemove/scroll/pointermove) to avoid flow spam.
+const DEFAULT_FLOW_EVENTS = [
+    'onClick',
+    'onDoubleClick',
+    'onContextMenu',
+    'onSubmit',
+    'onChange',
+];
+const ORIGIN_TYPE = {
+    onSubmit: 'form-submit',
+    onChange: 'input-change',
+};
+export default function lensmcpBabelPlugin(api) {
+    const types = api.types;
+    return {
+        name: '@lensmcp/react-instrumentation/babel-plugin',
+        visitor: {
+            Program: {
+                enter(path, state) {
+                    state.needHelpers = new Set();
+                    state.needRoot = false;
+                    state.hookIndex = 0;
+                    state.flowEvents = new Set(state.opts.flowEvents ?? DEFAULT_FLOW_EVENTS);
+                    state.rootVars = new Set();
+                    if (state.opts.production ?? process.env['NODE_ENV'] === 'production') {
+                        state.fileIgnored = true;
+                        return;
+                    }
+                    const leading = path.node.body[0]?.leadingComments ?? path.node.directives.flatMap((d) => d.leadingComments ?? []);
+                    if ((leading ?? []).some((c) => c.value.includes('@lensmcp-ignore'))) {
+                        state.fileIgnored = true;
+                    }
+                    const file = state.file?.opts?.filename;
+                    const rootDir = state.opts.rootDir ?? process.cwd();
+                    if (file && file.startsWith(rootDir)) {
+                        state.relativePath = file.slice(rootDir.length).replace(/^\/+/, '');
+                    }
+                    else if (file) {
+                        state.relativePath = file;
+                    }
+                },
+                exit(path, state) {
+                    if (state.fileIgnored)
+                        return;
+                    const helpers = [...(state.needHelpers ?? [])];
+                    if (state.needRoot)
+                        helpers.push('LensmcpRoot', 'installFlowFetch');
+                    if (helpers.length === 0)
+                        return;
+                    // Only import helpers not already imported from our package.
+                    const already = collectImported(path.node.body, HELPER_IMPORT, types);
+                    const missing = helpers.filter((h) => !already.has(h));
+                    if (missing.length > 0) {
+                        path.node.body.unshift(types.importDeclaration(missing.map((h) => types.importSpecifier(types.identifier(h), types.identifier(h))), types.stringLiteral(HELPER_IMPORT)));
+                    }
+                    // Install the flow-aware fetch once, after the imports.
+                    if (state.needRoot) {
+                        const firstNonImport = path.node.body.findIndex((n) => !types.isImportDeclaration(n));
+                        const callStmt = types.expressionStatement(types.callExpression(types.identifier('installFlowFetch'), []));
+                        path.node.body.splice(firstNonImport < 0 ? path.node.body.length : firstNonImport, 0, callStmt);
+                    }
+                },
+            },
+            VariableDeclarator(path, state) {
+                if (state.fileIgnored)
+                    return;
+                // Track `const root = createRoot(...)` so the common two-statement
+                // bootstrap (`root.render(<App/>)`, often inside a .then callback)
+                // also gets the LensmcpRoot wrap — not just the fluent one-liner.
+                if (state.opts.autoWrapRoot !== false &&
+                    types.isIdentifier(path.node.id) &&
+                    path.node.init &&
+                    isRootFactoryCall(path.node.init, types)) {
+                    state.rootVars.add(path.node.id.name);
+                }
+            },
+            CallExpression(path, state) {
+                if (state.fileIgnored)
+                    return;
+                const callee = path.node.callee;
+                // 1. Hook auto-wrap: useEffect/useMemo/useCallback(...) → traced*.
+                if (state.opts.autoWrapHooks !== false && types.isIdentifier(callee) && HOOK_MAP[callee.name]) {
+                    const traced = HOOK_MAP[callee.name];
+                    // Skip if already a traced call or first arg is already an id string.
+                    const id = `${state.relativePath ?? '(anon)'}:${path.node.loc?.start.line ?? 0}:${state.hookIndex++}`;
+                    path.node.callee = types.identifier(traced);
+                    path.node.arguments.unshift(types.stringLiteral(id));
+                    state.needHelpers.add(traced);
+                    return;
+                }
+                // 2. Root auto-wrap: createRoot(x).render(EXPR) → .render(<LensmcpRoot>{EXPR}</LensmcpRoot>).
+                if (state.opts.autoWrapRoot !== false &&
+                    types.isMemberExpression(callee) &&
+                    types.isIdentifier(callee.property, { name: 'render' }) &&
+                    (isRootFactoryCall(callee.object, types) ||
+                        (types.isIdentifier(callee.object) && state.rootVars?.has(callee.object.name))) &&
+                    path.node.arguments.length >= 1) {
+                    const arg = path.node.arguments[0];
+                    if (arg && !isAlreadyLensmcpRoot(arg, types)) {
+                        path.node.arguments[0] = types.jsxElement(types.jsxOpeningElement(types.jsxIdentifier('LensmcpRoot'), [], false), types.jsxClosingElement(types.jsxIdentifier('LensmcpRoot')), [types.jsxExpressionContainer(arg)], false);
+                        state.needRoot = true;
+                    }
+                }
+            },
+            JSXOpeningElement(path, state) {
+                if (state.fileIgnored)
+                    return;
+                // Already tagged? Skip.
+                const attrs = path.node.attributes;
+                if (hasAttr(attrs, 'data-agent-component'))
+                    return;
+                if (hasAttr(attrs, 'data-lensmcp-ignore'))
+                    return;
+                const leading = path.parent.leadingComments ?? path.node.leadingComments;
+                if ((leading ?? []).some((c) => c.value.includes('@lensmcp-ignore'))) {
+                    return;
+                }
+                // Auto-wrap user-interaction handlers with `withFlow` so a click/
+                // submit/change starts a correlated flow (origin → backend) with no
+                // app code. Done before tagging so we only walk authored attributes.
+                if (state.opts.autoFlowHandlers !== false) {
+                    const loc = path.node.loc;
+                    const line = loc?.start.line ?? 0;
+                    const file = state.relativePath ?? '(anon)';
+                    for (const attr of path.node.attributes) {
+                        if (attr.type !== 'JSXAttribute' ||
+                            attr.name.type !== 'JSXIdentifier' ||
+                            !state.flowEvents.has(attr.name.name) ||
+                            !attr.value ||
+                            attr.value.type !== 'JSXExpressionContainer') {
+                            continue;
+                        }
+                        const expr = attr.value.expression;
+                        if (expr.type === 'JSXEmptyExpression' ||
+                            isAlreadyWithFlow(expr, types)) {
+                            continue;
+                        }
+                        const event = attr.name.name;
+                        attr.value.expression = types.callExpression(types.identifier('withFlow'), [
+                            expr,
+                            types.objectExpression([
+                                types.objectProperty(types.identifier('originType'), types.stringLiteral(ORIGIN_TYPE[event] ?? 'user-click')),
+                                types.objectProperty(types.identifier('originNodeId'), types.stringLiteral(`ui:${file}:${line}:${event}`)),
+                            ]),
+                        ]);
+                        state.needHelpers.add('withFlow');
+                    }
+                }
+                const name = describeElementName(path.node.name);
+                if (!name)
+                    return;
+                // Never stamp React special element types — they validate their props
+                // (React 19 errors with "Invalid prop supplied to React.Fragment") and
+                // render no DOM to identify anyway. Includes aliased context providers
+                // (`const XProvider = Ctx.Provider`), which a `Fragment`-only check misses.
+                if (isUnstampableElement(name))
+                    return;
+                const newAttrs = [
+                    types.jsxAttribute(types.jsxIdentifier('data-agent-component'), types.stringLiteral(name)),
+                ];
+                if (state.opts.includeSource !== false) {
+                    const loc = path.node.loc;
+                    const line = loc?.start.line ?? 0;
+                    const file = state.relativePath ?? '(anon)';
+                    newAttrs.push(types.jsxAttribute(types.jsxIdentifier('data-agent-source'), types.stringLiteral(`${file}:${line}`)));
+                }
+                path.node.attributes.push(...newAttrs);
+            },
+        },
+    };
+}
+function hasAttr(attrs, name) {
+    return attrs.some((a) => a.type === 'JSXAttribute' &&
+        a.name.type === 'JSXIdentifier' &&
+        a.name.name === name);
+}
+/** Names already imported from `source` in this program body. */
+function collectImported(body, source, types) {
+    const out = new Set();
+    for (const node of body) {
+        if (types.isImportDeclaration(node) && node.source.value === source) {
+            for (const spec of node.specifiers) {
+                if (types.isImportSpecifier(spec) && types.isIdentifier(spec.imported)) {
+                    out.add(spec.imported.name);
+                }
+            }
+        }
+    }
+    return out;
+}
+/** Is `node` a `createRoot(...)` / `hydrateRoot(...)` call (bare or member)? */
+function isRootFactoryCall(node, types) {
+    if (!types.isCallExpression(node))
+        return false;
+    const callee = node.callee;
+    const names = new Set(['createRoot', 'hydrateRoot']);
+    if (types.isIdentifier(callee))
+        return names.has(callee.name);
+    if (types.isMemberExpression(callee) && types.isIdentifier(callee.property)) {
+        return names.has(callee.property.name);
+    }
+    return false;
+}
+/** Already wrapped with `withFlow(...)`? Keeps the transform idempotent. */
+function isAlreadyWithFlow(node, types) {
+    return (types.isCallExpression(node) &&
+        types.isIdentifier(node.callee, { name: 'withFlow' }));
+}
+/** Already wrapped in <LensmcpRoot>? */
+function isAlreadyLensmcpRoot(arg, types) {
+    return (types.isJSXElement(arg) &&
+        types.isJSXIdentifier(arg.openingElement.name, { name: 'LensmcpRoot' }));
+}
+// React special element types reject unknown props (validated like fragments
+// in React 19). `<>…</>` is a JSXFragment and never reaches the visitor; this
+// covers the named forms — including aliases that END in Provider/Consumer
+// (`const NavigationSlotsProvider = Ctx.Provider`), which render no DOM and
+// would otherwise crash the host app's console with prop-validation errors.
+const SPECIAL_UNSTAMPABLE = new Set([
+    'Fragment',
+    'StrictMode',
+    'Suspense',
+    'SuspenseList',
+    'Profiler',
+]);
+function isUnstampableElement(name) {
+    const last = name.split('.').pop() ?? name;
+    if (SPECIAL_UNSTAMPABLE.has(last))
+        return true;
+    return last.endsWith('Provider') || last.endsWith('Consumer');
+}
+function describeElementName(node) {
+    switch (node.type) {
+        case 'JSXIdentifier':
+            return node.name;
+        case 'JSXMemberExpression': {
+            const parts = [];
+            let cur = node;
+            while (cur.type === 'JSXMemberExpression') {
+                parts.unshift(cur.property.name);
+                cur = cur.object;
+            }
+            if (cur.type === 'JSXIdentifier')
+                parts.unshift(cur.name);
+            return parts.join('.');
+        }
+        case 'JSXNamespacedName':
+            return `${node.namespace.name}:${node.name.name}`;
+        default:
+            return undefined;
+    }
+}