@lensmcp/react-instrumentation 1.16.31 → 1.17.0

package/index.d.ts

@@ -4,6 +4,7 @@ export { tracedUseEffect, tracedUseMemo, tracedUseCallback, } from './lib/traced
 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 { installFiberRenderPublisher, resetFiberRenderPublisherForTests } from './lib/fiber-renders.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';

package/index.d.ts.map

@@ -1 +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"}
+{"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,EAAE,2BAA2B,EAAE,iCAAiC,EAAE,MAAM,wBAAwB,CAAC;AACxG,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

@@ -4,6 +4,7 @@ export { tracedUseEffect, tracedUseMemo, tracedUseCallback, } from './lib/traced
 export { TraceSlot } from './lib/trace-slot.js';
 export { withTraceComponent } from './lib/hoc.js';
 export { installFlowFetch } from './lib/flow-fetch.js';
+export { installFiberRenderPublisher, resetFiberRenderPublisherForTests } from './lib/fiber-renders.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/fiber-renders.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Install the fiber-commit subscriber. Idempotent; a no-op outside the
+ * browser or when the client runtime's hook bus is absent (old runtime).
+ */
+export declare function installFiberRenderPublisher(): void;
+/** Test seam: reset module state between specs. */
+export declare function resetFiberRenderPublisherForTests(): void;
+//# sourceMappingURL=fiber-renders.d.ts.map

package/lib/fiber-renders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fiber-renders.d.ts","sourceRoot":"","sources":["../../src/lib/fiber-renders.ts"],"names":[],"mappings":"AAuMA;;;GAGG;AACH,wBAAgB,2BAA2B,IAAI,IAAI,CAsDlD;AAED,mDAAmD;AACnD,wBAAgB,iCAAiC,IAAI,IAAI,CAGxD"}

package/lib/fiber-renders.js

@@ -0,0 +1,237 @@
+/**
+ * Per-component render attribution — the fiber-walk publisher.
+ *
+ * `LensmcpRoot`'s single root `<Profiler>` can only say "the tree
+ * committed" (every record lands as `lensmcp-root` with
+ * `why: profiler-onrender`), so `react://components/hot`,
+ * `react://renders/slow` and `graph_explain_rerender` cannot name a
+ * component. This module closes that gap the way React DevTools /
+ * react-scan do: the injected client runtime installs (or patches) the
+ * `__REACT_DEVTOOLS_GLOBAL_HOOK__` BEFORE react-dom evaluates and
+ * re-publishes every `onCommitFiberRoot` through a tiny pub/sub
+ * (`window.__LENSMCP_FIBER__`); this module subscribes, walks the
+ * committed fiber tree, and publishes one `RenderRecord` per component
+ * render — real names, real `actualDuration`, and a best-effort `why`
+ * (changed prop keys / parent-render / own state).
+ *
+ * FLOOD CONTROL (the valtio-instrumentation lesson: a 26k-event storm
+ * from 22 renders): per commit only the top `MAX_RECORDS_PER_COMMIT`
+ * renders by duration are published, and a token bucket caps attributed
+ * commits per second — beyond it, renders are folded into ONE
+ * "render-storm" warning per second naming the hottest components.
+ * That warning is itself the signal a timer-driven progress indicator
+ * (a 500ms setInterval → setState per row) should be a DOM mutation.
+ *
+ * Strictly passive and defensive: every entry point is wrapped, and any
+ * throw disables the walker for the rest of the session.
+ */
+import { makeInstanceId } from './identity.js';
+import { publish } from './publish.js';
+/** react-reconciler ReactFiberFlags.PerformedWork — stable at 0b1 since React 16. */
+const PERFORMED_WORK = 0b1;
+/** react-reconciler ReactWorkTags for renderable user components. */
+const TAG_FUNCTION = 0; // FunctionComponent
+const TAG_CLASS = 1; // ClassComponent
+const TAG_FORWARD_REF = 11;
+const TAG_MEMO = 14; // MemoComponent
+const TAG_SIMPLE_MEMO = 15; // SimpleMemoComponent
+const MAX_NODES_PER_COMMIT = 15_000;
+const MAX_RECORDS_PER_COMMIT = 25;
+/** Attributed commits per second; beyond this, fold into the storm summary. */
+const COMMIT_BUDGET_PER_SEC = 15;
+const MAX_CHANGED_KEYS = 8;
+let installed = false;
+let disabled = false;
+/** Extract a human component name from a fiber, unwrapping memo/forwardRef. */
+function componentNameOf(fiber) {
+    const t = fiber.type;
+    if (t == null || typeof t === 'string')
+        return undefined; // host / text
+    switch (fiber.tag) {
+        case TAG_FUNCTION:
+        case TAG_CLASS:
+            return t.displayName || t.name || undefined;
+        case TAG_FORWARD_REF:
+            return t.displayName || t.render?.displayName || t.render?.name || undefined;
+        case TAG_MEMO:
+        case TAG_SIMPLE_MEMO:
+            return t.displayName || t.type?.displayName || t.type?.name || t.name || undefined;
+        default:
+            return undefined;
+    }
+}
+/** Shallow prop diff against the alternate — the changed keys, capped. */
+function changedPropKeys(fiber) {
+    const prev = fiber.alternate?.memoizedProps;
+    const next = fiber.memoizedProps;
+    if (!prev || !next || prev === next)
+        return [];
+    const keys = [];
+    for (const k of Object.keys(next)) {
+        if (k === 'children')
+            continue;
+        if (!Object.is(prev[k], next[k])) {
+            keys.push(k);
+            if (keys.length >= MAX_CHANGED_KEYS)
+                break;
+        }
+    }
+    return keys;
+}
+/** Walk one committed tree; collect every component render (bounded). */
+function collectCommitRenders(root) {
+    const out = [];
+    let visited = 0;
+    // Iterative DFS (child → sibling), tracking the nearest RENDERED component ancestor.
+    const stack = [];
+    if (root.current.child)
+        stack.push({ node: root.current.child, parentName: undefined });
+    while (stack.length > 0) {
+        const { node, parentName } = stack.pop();
+        visited += 1;
+        if (visited > MAX_NODES_PER_COMMIT)
+            break;
+        let ownParentName = parentName;
+        const name = componentNameOf(node);
+        const rendered = (node.flags & PERFORMED_WORK) !== 0;
+        if (name && rendered) {
+            const isMount = node.alternate == null;
+            const why = [];
+            if (!isMount) {
+                const keys = changedPropKeys(node);
+                if (keys.length > 0)
+                    why.push({ type: 'props', changedKeys: keys });
+                if (parentName)
+                    why.push({ type: 'parent-render', parentRenderId: parentName });
+                if (why.length === 0)
+                    why.push({ type: 'react-state', hookIndex: -1 }); // own update, hook unknown
+            }
+            out.push({
+                name,
+                phase: isMount ? 'mount' : 'update',
+                durationMs: typeof node.actualDuration === 'number' ? node.actualDuration : 0,
+                why,
+                parentName,
+            });
+            ownParentName = name;
+        }
+        if (node.sibling)
+            stack.push({ node: node.sibling, parentName });
+        if (node.child)
+            stack.push({ node: node.child, parentName: ownParentName });
+    }
+    return out;
+}
+function publishRecords(renders, commitAt) {
+    // Rank by duration so a capped commit keeps the expensive renders.
+    const ranked = renders.length > MAX_RECORDS_PER_COMMIT
+        ? [...renders].sort((a, b) => b.durationMs - a.durationMs).slice(0, MAX_RECORDS_PER_COMMIT)
+        : renders;
+    for (const r of ranked) {
+        const logicalId = `react:component:(fiber):${r.name}`;
+        const { instanceId } = makeInstanceId(logicalId);
+        const record = {
+            id: instanceId,
+            componentInstanceId: instanceId,
+            componentLogicalId: logicalId,
+            componentName: r.name,
+            rendererId: 'fiber',
+            phase: r.phase,
+            actualDurationMs: r.durationMs,
+            baseDurationMs: r.durationMs,
+            startTime: commitAt,
+            commitTime: commitAt,
+            why: r.why,
+        };
+        publish({
+            source: 'react',
+            category: 'render',
+            severity: 'info',
+            title: `render ${r.name} (${r.phase})`,
+            fingerprint: `react-render:${logicalId}`,
+            raw: { kind: 'render', render: record },
+        });
+    }
+    if (renders.length > ranked.length) {
+        publish({
+            source: 'react',
+            category: 'render',
+            severity: 'debug',
+            title: `render commit truncated: ${renders.length - ranked.length} of ${renders.length} renders dropped (per-commit cap)`,
+            fingerprint: 'react-render:commit-truncated',
+            raw: { kind: 'render-commit-truncated', total: renders.length, published: ranked.length },
+        });
+    }
+}
+/**
+ * Install the fiber-commit subscriber. Idempotent; a no-op outside the
+ * browser or when the client runtime's hook bus is absent (old runtime).
+ */
+export function installFiberRenderPublisher() {
+    if (installed || disabled)
+        return;
+    if (typeof window === 'undefined')
+        return;
+    const bus = window.__LENSMCP_FIBER__;
+    if (!bus || typeof bus.subscribe !== 'function')
+        return; // runtime predates the hook shim
+    installed = true;
+    // Storm accounting: a token bucket for fully-attributed commits; the
+    // overflow folds into one warning per second naming the hottest components.
+    let tokens = COMMIT_BUDGET_PER_SEC;
+    let stormCommits = 0;
+    const stormCounts = new Map();
+    let flushTimer;
+    const flushStorm = () => {
+        flushTimer = undefined;
+        tokens = COMMIT_BUDGET_PER_SEC;
+        if (stormCommits === 0)
+            return;
+        const top = [...stormCounts.entries()].sort((a, b) => b[1] - a[1]).slice(0, 5);
+        publish({
+            source: 'react',
+            category: 'render',
+            severity: 'warning',
+            title: `render storm: ${stormCommits} commits/s over budget — top: ${top.map(([n, c]) => `${n}×${c}`).join(', ')}`,
+            fingerprint: 'react-render:storm',
+            raw: {
+                kind: 'render-storm',
+                commits: stormCommits,
+                components: Object.fromEntries(top),
+            },
+        });
+        stormCommits = 0;
+        stormCounts.clear();
+    };
+    bus.subscribe((_rendererID, root) => {
+        if (disabled)
+            return;
+        try {
+            if (!root || !root.current)
+                return;
+            const renders = collectCommitRenders(root);
+            if (renders.length === 0)
+                return;
+            if (tokens > 0) {
+                tokens -= 1;
+                publishRecords(renders, Date.now());
+            }
+            else {
+                stormCommits += 1;
+                for (const r of renders)
+                    stormCounts.set(r.name, (stormCounts.get(r.name) ?? 0) + 1);
+            }
+            if (!flushTimer)
+                flushTimer = setTimeout(flushStorm, 1_000);
+        }
+        catch {
+            // Never risk the host app: one throw disables the walker for the session.
+            disabled = true;
+        }
+    });
+}
+/** Test seam: reset module state between specs. */
+export function resetFiberRenderPublisherForTests() {
+    installed = false;
+    disabled = false;
+}

package/lib/flow-fetch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flow-fetch.d.ts","sourceRoot":"","sources":["../../src/lib/flow-fetch.ts"],"names":[],"mappings":"AAgBA,MAAM,WAAW,gBAAgB;IAC/B,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8EAA8E;IAC9E,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAWD,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,gBAAqB,GAAG,MAAM,IAAI,CA2C3E"}
+{"version":3,"file":"flow-fetch.d.ts","sourceRoot":"","sources":["../../src/lib/flow-fetch.ts"],"names":[],"mappings":"AAgBA,MAAM,WAAW,gBAAgB;IAC/B,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8EAA8E;IAC9E,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAWD,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,gBAAqB,GAAG,MAAM,IAAI,CA+C3E"}

package/lib/flow-fetch.js

@@ -35,6 +35,10 @@ export function installFlowFetch(options = {}) {
     const flowHeader = options.flowHeader ?? 'x-lensmcp-flow-id';
     const originHeader = options.originHeader ?? 'x-lensmcp-origin-node-id';
     const original = g.fetch.bind(globalThis);
+    // Tell the injected client runtime's own (inner) fetch wrapper to stop
+    // emitting: from here on THIS wrapper publishes the network events, and
+    // both firing double-counts every request in the timeline.
+    globalThis['__LENSMCP_FLOW_FETCH__'] = true;
     const patched = ((input, init) => {
         // Sync stack (a wrapped handler) OR the causality window (page-load,
         // post-response continuations) — both mean this fetch belongs to a flow.

package/lib/lensmcp-root.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lensmcp-root.d.ts","sourceRoot":"","sources":["../../src/lib/lensmcp-root.tsx"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,SAAS,EAGf,MAAM,OAAO,CAAC;AAMf,MAAM,WAAW,gBAAgB;IAC/B,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,SAAS,CAuD9D"}
+{"version":3,"file":"lensmcp-root.d.ts","sourceRoot":"","sources":["../../src/lib/lensmcp-root.tsx"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,SAAS,EAGf,MAAM,OAAO,CAAC;AAYf,MAAM,WAAW,gBAAgB;IAC/B,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,SAAS,CAuD9D"}

package/lib/lensmcp-root.js

@@ -3,6 +3,12 @@ import { Profiler, useMemo, useRef, } from 'react';
 import { LensmcpContext } from './context.js';
 import { publish } from './publish.js';
 import { makeInstanceId } from './identity.js';
+import { installFiberRenderPublisher } from './fiber-renders.js';
+// Per-component render attribution rides the client runtime's DevTools-hook
+// bus (see fiber-renders.ts). Module-scope so importing LensmcpRoot (the
+// babel autoWrapRoot path) is enough — no API change for consumers.
+if (typeof window !== 'undefined')
+    installFiberRenderPublisher();
 /**
  * Wraps the React tree in a `<Profiler>` and a context provider so the
  * hook helpers can tag their events with the right renderer / page /

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lensmcp/react-instrumentation",
-  "version": "1.16.31",
+  "version": "1.17.0",
   "type": "module",
   "main": "./index.js",
   "module": "./index.js",
@@ -19,7 +19,7 @@
     }
   },
   "dependencies": {
-    "@lensmcp/protocol-types": "1.16.31",
+    "@lensmcp/protocol-types": "1.17.0",
     "tslib": "^2.3.0"
   },
   "peerDependencies": {