catalyst-core 0.3.0-beta.5 → 0.3.0-canary.2

package/dist/native/bridge/hooks/useVideoStream.js

@@ -8,6 +8,7 @@ var _react = require("react");
 var _NativeBridge = _interopRequireDefault(require("../utils/NativeBridge.js"));
 var _NativeInterfaces = require("../constants/NativeInterfaces.js");
 var _useBaseHook = require("../useBaseHook.js");
+var _errors = require("../errors.js");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 /* eslint-disable react-compiler/react-compiler, react-hooks/exhaustive-deps */
 
@@ -19,6 +20,11 @@ const STREAM_STATE_DEFAULT = {
   fpsMin: null,
   fpsMax: null
 };
+
+/** Options accepted when starting the native or web video stream. */
+
+/** Options accepted by {@link useVideoStream}. */
+
 const useVideoStream = ({
   onQRDetected,
   webFallback
@@ -66,22 +72,16 @@ const useVideoStream = ({
     try {
       await track.applyConstraints(constraints);
     } catch (e) {
-      base.setError({
-        message: `applyConstraints failed: ${e.message}`
-      });
+      base.setError((0, _errors.createStandardError)(_errors.ERROR_CODES.INTERNAL_ERROR, `applyConstraints failed: ${e.message}`, e));
     }
   }, [base]);
   const webStart = (0, _react.useCallback)(async (options = {}) => {
     if (!window.isSecureContext) {
-      base.setError({
-        message: "getUserMedia requires a secure context (HTTPS or localhost)"
-      });
+      base.setError((0, _errors.createStandardError)(_errors.ERROR_CODES.FEATURE_UNSUPPORTED, "getUserMedia requires a secure context (HTTPS or localhost)"));
       return;
     }
     if (!navigator.mediaDevices?.getUserMedia) {
-      base.setError({
-        message: "getUserMedia is not available in this browser"
-      });
+      base.setError((0, _errors.createStandardError)(_errors.ERROR_CODES.FEATURE_UNSUPPORTED, "getUserMedia is not available in this browser"));
       return;
     }
     try {
@@ -114,9 +114,8 @@ const useVideoStream = ({
       }));
     } catch (e) {
       base.setLoading(false);
-      base.setError({
-        message: e.message || "getUserMedia failed"
-      });
+      const code = e?.name === "NotAllowedError" ? _errors.ERROR_CODES.PERMISSION_DENIED : e?.name === "NotReadableError" ? _errors.ERROR_CODES.CAMERA_IN_USE : _errors.ERROR_CODES.CAMERA_UNAVAILABLE;
+      base.setError((0, _errors.createStandardError)(code, e.message || "getUserMedia failed", e));
     }
   }, [base]);
   const webStop = (0, _react.useCallback)(() => {
@@ -135,18 +134,14 @@ const useVideoStream = ({
   }, [webStart, webStop]);
   const webSendCommand = (0, _react.useCallback)(async (type, value) => {
     if (!isStreamingWeb) {
-      base.setError({
-        message: `sendCommand('${type}') called but stream is not active`
-      });
+      base.setError((0, _errors.createStandardError)(_errors.ERROR_CODES.INVALID_PARAMETERS, `sendCommand('${type}') called but stream is not active`));
       return;
     }
     switch (type) {
       case "zoom":
         {
           if (typeof value !== "number" || value < 1.0) {
-            base.setError({
-              message: `sendCommand zoom: value must be a multiplier >= 1.0, got ${value}`
-            });
+            base.setError((0, _errors.createStandardError)(_errors.ERROR_CODES.INVALID_PARAMETERS, `sendCommand zoom: value must be a multiplier >= 1.0, got ${value}`));
             return;
           }
           await applyTrackConstraints({
@@ -163,9 +158,7 @@ const useVideoStream = ({
       case "torch":
         {
           if (typeof value !== "boolean") {
-            base.setError({
-              message: `sendCommand torch: value must be boolean, got ${value}`
-            });
+            base.setError((0, _errors.createStandardError)(_errors.ERROR_CODES.INVALID_PARAMETERS, `sendCommand torch: value must be boolean, got ${value}`));
             return;
           }
           await applyTrackConstraints({
@@ -182,9 +175,7 @@ const useVideoStream = ({
       case "fps":
         {
           if (typeof value !== "object" || value === null) {
-            base.setError({
-              message: `sendCommand fps: value must be { min, max }, got ${value}`
-            });
+            base.setError((0, _errors.createStandardError)(_errors.ERROR_CODES.INVALID_PARAMETERS, `sendCommand fps: value must be { min, max }, got ${value}`));
             return;
           }
           const {
@@ -205,9 +196,7 @@ const useVideoStream = ({
           break;
         }
       default:
-        base.setError({
-          message: `sendCommand: unknown type '${type}'`
-        });
+        base.setError((0, _errors.createStandardError)(_errors.ERROR_CODES.INVALID_PARAMETERS, `sendCommand: unknown type '${type}'`));
     }
   }, [isStreamingWeb, applyTrackConstraints, base]);
 
@@ -292,9 +281,7 @@ const useVideoStream = ({
   }, []);
   const nativeSendCommand = (0, _react.useCallback)((type, value) => {
     if (!isStreaming) {
-      base.setError({
-        message: `sendCommand('${type}') called but stream is not active`
-      });
+      base.setError((0, _errors.createStandardError)(_errors.ERROR_CODES.INVALID_PARAMETERS, `sendCommand('${type}') called but stream is not active`));
       return;
     }
     console.log(`[useVideoStream] sendCommand(${type}, ${value})`);
@@ -302,9 +289,7 @@ const useVideoStream = ({
       case "zoom":
         {
           if (typeof value !== "number" || value < 1.0) {
-            base.setError({
-              message: `sendCommand zoom: value must be a multiplier >= 1.0 (e.g. 1.0=1x, 2.0=2x), got ${value}`
-            });
+            base.setError((0, _errors.createStandardError)(_errors.ERROR_CODES.INVALID_PARAMETERS, `sendCommand zoom: value must be a multiplier >= 1.0 (e.g. 1.0=1x, 2.0=2x), got ${value}`));
             return;
           }
           _NativeBridge.default.videoStream.setZoom(value);
@@ -313,9 +298,7 @@ const useVideoStream = ({
       case "torch":
         {
           if (typeof value !== "boolean") {
-            base.setError({
-              message: `sendCommand torch: value must be boolean, got ${value}`
-            });
+            base.setError((0, _errors.createStandardError)(_errors.ERROR_CODES.INVALID_PARAMETERS, `sendCommand torch: value must be boolean, got ${value}`));
             return;
           }
           _NativeBridge.default.videoStream.setTorch(value);
@@ -324,9 +307,7 @@ const useVideoStream = ({
       case "fps":
         {
           if (typeof value !== "object" || value === null) {
-            base.setError({
-              message: `sendCommand fps: value must be { min, max }, got ${value}`
-            });
+            base.setError((0, _errors.createStandardError)(_errors.ERROR_CODES.INVALID_PARAMETERS, `sendCommand fps: value must be { min, max }, got ${value}`));
             return;
           }
           const {
@@ -334,21 +315,15 @@ const useVideoStream = ({
             max = null
           } = value;
           if (min !== null && (typeof min !== "number" || min < 1)) {
-            base.setError({
-              message: `sendCommand fps: min must be a positive number, got ${min}`
-            });
+            base.setError((0, _errors.createStandardError)(_errors.ERROR_CODES.INVALID_PARAMETERS, `sendCommand fps: min must be a positive number, got ${min}`));
             return;
           }
           if (max !== null && (typeof max !== "number" || max < 1)) {
-            base.setError({
-              message: `sendCommand fps: max must be a positive number, got ${max}`
-            });
+            base.setError((0, _errors.createStandardError)(_errors.ERROR_CODES.INVALID_PARAMETERS, `sendCommand fps: max must be a positive number, got ${max}`));
             return;
           }
           if (min !== null && max !== null && min > max) {
-            base.setError({
-              message: `sendCommand fps: min (${min}) must be <= max (${max})`
-            });
+            base.setError((0, _errors.createStandardError)(_errors.ERROR_CODES.INVALID_PARAMETERS, `sendCommand fps: min (${min}) must be <= max (${max})`));
             return;
           }
           _NativeBridge.default.videoStream.setFps(min, max);
@@ -360,20 +335,22 @@ const useVideoStream = ({
           break;
         }
       default:
-        base.setError({
-          message: `sendCommand: unknown type '${type}'`
-        });
+        base.setError((0, _errors.createStandardError)(_errors.ERROR_CODES.INVALID_PARAMETERS, `sendCommand: unknown type '${type}'`));
     }
   }, [isStreaming, base.setError]);
   if (typeof window === "undefined") {
     return {
       isStreaming: false,
       streamState: STREAM_STATE_DEFAULT,
+      loading: false,
       error: null,
       isNative: false,
-      webFallbackActive: false,
+      isWeb: true,
+      webFallbackActive: base.webFallbackActive,
       webFallbackDisabled: false,
       setWebFallback: () => {},
+      mediaStream: null,
+      viewfinderRef,
       start: () => {},
       stop: () => {},
       sendCommand: () => {},
@@ -385,11 +362,15 @@ const useVideoStream = ({
     return {
       isStreaming: false,
       streamState: STREAM_STATE_DEFAULT,
+      loading: base.loading,
       error: null,
       isNative: false,
+      isWeb: base.isWeb,
       webFallbackActive: false,
       webFallbackDisabled: true,
       setWebFallback: base.setWebFallback,
+      mediaStream: null,
+      viewfinderRef,
       start: () => {},
       stop: () => {},
       sendCommand: () => {},
@@ -401,8 +382,10 @@ const useVideoStream = ({
     return {
       isStreaming: isStreamingWeb,
       streamState: streamStateWeb,
+      loading: base.loading,
       error: base.error,
       isNative: false,
+      isWeb: base.isWeb,
       webFallbackActive: true,
       webFallbackDisabled: false,
       setWebFallback: base.setWebFallback,
@@ -418,11 +401,14 @@ const useVideoStream = ({
   return {
     isStreaming,
     streamState,
+    loading: base.loading,
     error: base.error,
     isNative: base.isNative,
+    isWeb: base.isWeb,
     webFallbackActive: false,
     webFallbackDisabled: false,
     setWebFallback: base.setWebFallback,
+    mediaStream: null,
     viewfinderRef,
     start: nativeStart,
     stop: nativeStop,

package/dist/native/bridge/hooks/utils.d.ts

@@ -0,0 +1,4 @@
+export declare const noop: () => void;
+export declare const createSSRUnavailable: (methodName: any) => () => Promise<never>;
+export declare const parseNativePayload: (payload: any) => any;
+export declare const registerNativeHandlers: (handlers: any) => () => void;

package/dist/native/bridge/hooks.d.ts

@@ -0,0 +1 @@
+export * from "./hooks/index.js";

package/dist/native/bridge/perf/collectors/ApiCollector.d.ts

@@ -0,0 +1,30 @@
+/**
+ * ApiCollector.js
+ *
+ * Instruments native API call timing — how long each @JavascriptInterface
+ * method takes from native receipt until its immediate native handler work is
+ * dispatched. It does not measure JS-to-native transport, JS callback delivery,
+ * or UI completion.
+ *
+ * Native events received (via __catalystPerfBatch drain):
+ *   api-call { callId, method, nativeStartMs, nativeEndMs, durationMs, thread }
+ *
+ * Spans emitted (one per call, on Catalyst > Native API track):
+ *   catalyst:api/<method>  — nativeStart → nativeEnd
+ *                            color: primary-dark (<50ms), secondary (<200ms), error (>200ms)
+ *   properties: method, durationMs, callId, thread, simulatorValid: false
+ *
+ * Reading the track:
+ *   Blue  = fast native call (<50ms)   — expected for sync APIs (getDeviceInfo, haptic)
+ *   Grey  = medium native call (<200ms) — native work worth inspecting
+ *   Red   = slow native call (>200ms)  — native work worth inspecting
+ */
+export declare class ApiCollector {
+    [key: string]: any;
+    constructor(measure: any, nativeToWeb: any);
+    init(): void;
+    /** Called by index.js to feed the normalized perf store. */
+    setWaterfallSource(fn: any): void;
+    setInteractionSource(fn: any): void;
+    onBatchEvent(event: any): void;
+}

package/dist/native/bridge/perf/collectors/ApiCollector.js

@@ -28,6 +28,10 @@ var _constants = require("../core/constants.js");
  */
 
 class ApiCollector {
+  // Internal collector state, assigned in the constructor. The perf module is
+  // internal to the bridge and deliberately left loosely typed during the
+  // migration, so an index signature stands in for per-field declarations.
+
   constructor(measure, nativeToWeb) {
     this._measure = measure;
     this._nativeToWeb = nativeToWeb;

package/dist/native/bridge/perf/collectors/CacheCollector.d.ts

@@ -0,0 +1,43 @@
+/**
+ * CacheCollector.js
+ *
+ * Instruments: bugs #1, #2, #10
+ *   #1  page slowness OTC pages     → cache miss → slow fetch → resource blocks render
+ *   #2  back-forward reloads screen → back navigation triggers a burst of cache misses
+ *   #10 footer flash on Drug/OTC    → cache miss for footer chunk → layout shift after load
+ *
+ * Native events received in two modes:
+ *
+ * 1. Live (legacy path — only used if buffer disabled):
+ *   cache-hit-memory / cache-hit-disk / cache-miss-fetch / network-fetch-complete
+ *   → Each emits immediately to Catalyst > Cache track via onNativeEvent()
+ *
+ * 2. Batched (primary path via __catalystPerfBatch drain in index.js):
+ *   Same event types arrive as part of the native buffer flush after onPageFinished.
+ *   JS drains via requestIdleCallback → onBatchEvent() → emits spans on Catalyst > Cache > Detail
+ *
+ *   cache-summary { hits, misses, fetches, total, hitRatePct, avgFetchMs, topSlowest[] }
+ *   → One summary span emitted on main Catalyst > Cache track for InsightsCollector
+ *
+ * Spans emitted:
+ *   Catalyst > Cache > Detail  individual spans (one per file) during idle drain
+ *   Catalyst > Cache           summary span (hit rate, avg fetch, top slowest)
+ *
+ * Reading the track:
+ *   Blue        = cache HIT memory — fastest path
+ *   Blue-light  = cache HIT disk   — good, slightly slower
+ *   Red         = cache MISS       — matched pattern but not cached
+ *   Yellow/Orange = network fetch  — orange if slow >300ms
+ */
+export declare class CacheCollector {
+    [key: string]: any;
+    constructor(measure: any, nativeToWeb: any);
+    /** Called by index.js to wire up insights notifications for cache-summary. */
+    setInsightsSource(fn: any): void;
+    init(): void;
+    onNativeEvent(event: any): void;
+    onBatchEvent(event: any): void;
+    _emitCacheSpan(event: any, track: any): void;
+    _emitSummarySpan(event: any): void;
+    _filename(url: any): string;
+}

package/dist/native/bridge/perf/collectors/CacheCollector.js

@@ -39,6 +39,10 @@ var _constants = require("../core/constants.js");
 
 const TRACK_CACHE_DETAIL = "Cache > Detail";
 class CacheCollector {
+  // Internal collector state, assigned in the constructor. The perf module is
+  // internal to the bridge and deliberately left loosely typed during the
+  // migration, so an index signature stands in for per-field declarations.
+
   constructor(measure, nativeToWeb) {
     this._measure = measure;
     this._nativeToWeb = nativeToWeb;

package/dist/native/bridge/perf/collectors/HookCollector.d.ts

@@ -0,0 +1,37 @@
+/**
+ * HookCollector.js — Option A (symptom detection only)
+ *
+ * Instruments: bugs #13, #15, #16
+ *   #13 cart computation loop jank    → LoAF bursts sustained over time, not tied to a single interaction
+ *                                       detected as: LoAF count > threshold within a rolling window
+ *   #15 quantity selector slow first  → interaction → first LoAF burst → long gap → paint
+ *                                       detected as: LoAF fires within LAZY_LOAF_WINDOW_MS after tap
+ *   #16 prescription screen touch lag → same pattern as #15
+ *
+ * Option A strategy (no React hooks needed):
+ *   - Watch for LoAF bursts within 2s of a pointerdown (taps that might trigger lazy load)
+ *   - If LoAF count > 0 in that window → emit hook/lazy span showing the blocked period
+ *   - Sustained LoAF (3+ frames in 5s with no user interaction) → emit hook/mount span
+ *     flagging a background computation loop
+ *
+ * Spans emitted:
+ *   catalyst:hook/lazy|<label>    — LoAF burst after interaction (Track: Hook)
+ *                                   detail: loafCount, totalBlockingMs, triggerTarget
+ *   catalyst:hook/mount|loop      — sustained background LoAF (Track: Hook)
+ *                                   detail: loafCount, windowMs, likelyCause='computation-loop'
+ *
+ * TODO (Option B — future):
+ *   Expose window.catalyst.markComponentMount(name) / markComponentReady(name)
+ *   for precise hook-lifecycle spans without symptom inference.
+ */
+export declare class HookCollector {
+    [key: string]: any;
+    constructor(measure: any);
+    init(): void;
+    /** Called by index.js to feed the normalized perf store. */
+    setWaterfallSource(fn: any): void;
+    onLoaf(start: any, end: any): void;
+    _onPointerDown(e: any): void;
+    _closeLazySpan(): void;
+    _emitLoopSpan(): void;
+}

package/dist/native/bridge/perf/collectors/HookCollector.js

@@ -36,6 +36,10 @@ const LOOP_LOAF_COUNT = 3; // ≥3 LoAFs in the loop window = computation loop
 const LOOP_WINDOW_MS = 5000; // rolling window to count sustained LoAFs
 
 class HookCollector {
+  // Internal collector state, assigned in the constructor. The perf module is
+  // internal to the bridge and deliberately left loosely typed during the
+  // migration, so an index signature stands in for per-field declarations.
+
   constructor(measure) {
     this._measure = measure;
 

package/dist/native/bridge/perf/collectors/InsightsCollector.d.ts

@@ -0,0 +1,103 @@
+/**
+ * InsightsCollector.js
+ *
+ * Watches accumulated perf data and emits actionable warnings to the
+ * Catalyst > Insights track in Chrome DevTools.
+ *
+ * Each insight is a point-in-time span with:
+ *   - severity: 'critical' | 'warning' | 'info'
+ *   - rule:     short machine-readable id (e.g. 'slow-page-load')
+ *   - message:  one-sentence human diagnosis
+ *   - fix:      immediate actionable recommendation
+ *   - evidence: the numbers that triggered the rule
+ *
+ * Insights are emitted in two modes:
+ *   1. Reactive — emitted immediately when a threshold breach is detected
+ *      (e.g. an fps-drop episode during interaction)
+ *   2. Summary — emitted once after SESSION_SUMMARY_DELAY_MS of inactivity
+ *      to give a rolled-up view of what happened in the last session
+ *
+ * How to read this in DevTools:
+ *   Performance tab → Catalyst > Insights track
+ *   Click any span → Tooltip shows: severity, rule, message, fix, evidence
+ *   Red spans = critical (user-visible jank/failure)
+ *   Yellow (tertiary) = warning
+ *   Blue (secondary) = info / optimization opportunity
+ */
+export declare class InsightsCollector {
+    [key: string]: any;
+    constructor(measure: any);
+    init(): void;
+    setStoreSource(fn: any): void;
+    notifyFpsDrop({ minFps, avgFps, durationMs, duringInteraction, deltaFps, baselineFps, startTime, endTime, interactionId, }: {
+        avgFps: any;
+        baselineFps: any;
+        deltaFps: any;
+        durationMs: any;
+        duringInteraction: any;
+        endTime: any;
+        interactionId: any;
+        minFps: any;
+        startTime: any;
+    }): void;
+    notifySlowLoad({ url, durationMs, startTime, endTime }: {
+        durationMs: any;
+        endTime: any;
+        startTime: any;
+        url: any;
+    }): void;
+    notifyColdStart({ durationMs, startTime, endTime }: {
+        durationMs: any;
+        endTime: any;
+        startTime: any;
+    }): void;
+    notifyLoafDuringNav({ durationMs, startTime, endTime }: {
+        durationMs: any;
+        endTime: any;
+        startTime: any;
+    }): void;
+    notifySlowInteraction({ target, responseMs, startTime, endTime, interactionId }: {
+        endTime: any;
+        interactionId: any;
+        responseMs: any;
+        startTime: any;
+        target: any;
+    }): void;
+    notifyHighMemory({ currentMb, startTime, endTime, memoryId }: {
+        currentMb: any;
+        endTime: any;
+        memoryId: any;
+        startTime: any;
+    }): void;
+    notifyHwAccelDuringFrame({ durationMs, thread, trigger, startTime, endTime }: {
+        durationMs: any;
+        endTime: any;
+        startTime: any;
+        thread: any;
+        trigger: any;
+    }): void;
+    notifyLayoutShift({ value, sessionContext, startTime, endTime }: {
+        endTime: any;
+        sessionContext: any;
+        startTime: any;
+        value: any;
+    }): void;
+    notifyScrollJank({ minFps, frameDropCount, startTime, endTime }: {
+        endTime: any;
+        frameDropCount: any;
+        minFps: any;
+        startTime: any;
+    }): void;
+    notifyCacheSummary({ hitRatePct, total, avgFetchMs, startTime, endTime }: {
+        avgFetchMs: any;
+        endTime: any;
+        hitRatePct: any;
+        startTime: any;
+        total: any;
+    }): void;
+    _emitReactive({ severity, rule, message, fix, evidence, startTime, endTime, related }: any): void;
+    _titleFor(rule: any, evidence: any, message: any): any;
+    _categoryFor(rule: any): "cache" | "general" | "interaction" | "memory" | "navigation" | "render" | "scroll" | "session";
+    _scheduleSummary(): void;
+    _emitSummary(): void;
+}

package/dist/native/bridge/perf/collectors/InsightsCollector.js

@@ -37,6 +37,10 @@ function round(value) {
   return Number.isFinite(value) ? Math.round(value) : value;
 }
 class InsightsCollector {
+  // Internal collector state, assigned in the constructor. The perf module is
+  // internal to the bridge and deliberately left loosely typed during the
+  // migration, so an index signature stands in for per-field declarations.
+
   constructor(measure) {
     this._measure = measure;
     this._summaryTimer = null;

package/dist/native/bridge/perf/collectors/InteractionCollector.d.ts

@@ -0,0 +1,53 @@
+/**
+ * InteractionCollector.js
+ *
+ * Instruments: bugs #6, #8, #13, #17
+ *   #6  blank screens              → tap → no paint → LoAF blocked first render
+ *                                    detected as: interaction span with no following rAF / LoAF overlap
+ *   #8  long press context menu    → pointerdown held > 500ms = native context menu will appear
+ *                                    detected as: long-press span so devs see which elements trigger it
+ *   #13 cart jank haywire clicks   → interaction timestamps vs render timestamps diverge
+ *                                    detected as: tap → paint delta > INTERACTION_SLOW_MS
+ *   #17 prescription modal wrong   → event queue backed up: pointerdown fires long after it was queued
+ *                                    detected as: slow interaction span overlapping LoAF
+ *
+ * Spans emitted:
+ *   catalyst:session/interaction|<tag>#<id>  — currently disabled; preserved below as the
+ *                                              old 2s grouping window for future re-enable.
+ *   catalyst:interaction|<tag>#<id>          — pointerdown → next rAF (Track: Interaction)
+ *                                              detail: responseMs, loafOverlap, target, sessionId
+ *   catalyst:long-press|<tag>                — pointerdown held > 500ms (Track: Interaction)
+ *                                              detail: target, heldMs
+ *
+ * Correlation:
+ *   A lightweight interaction ID remains active from pointerdown to the next frame.
+ *   Related work is tagged without emitting a parent session track.
+ *
+ * Disabled session nesting:
+ *   On pointerdown, a 2-second interaction session opens.
+ *   RenderCollector queries activeSessionId to tag its spans.
+ *   Session closes after SESSION_WINDOW_MS (2s) or next pointerdown, whichever comes first.
+ */
+export declare class InteractionCollector {
+    [key: string]: any;
+    constructor(measure: any);
+    get activeInteractionId(): any;
+    interactionIdForRange(startTime: any, endTime?: any): any;
+    /** Called by index.js to wire up insights notifications. */
+    setInsightsSource(fn: any): void;
+    /** Called by index.js to feed the normalized perf store. */
+    setWaterfallSource(fn: any): void;
+    /** Called by RenderCollector when an fps-drop-episode fires. */
+    onFpsDrop(): void;
+    /** Called by NetworkTimingCollector when a fetch/XHR starts during an interaction. */
+    onNetworkCall(): void;
+    init(): void;
+    _openSession(target: any, startTime: any): void;
+    _closeSession(): void;
+    _onPointerDown(e: any): void;
+    _onPointerUp(e: any): void;
+    _onPointerCancel(e: any): void;
+    _rememberInteraction(id: any, startTime: any, endTime: any): void;
+    _emitLongPress(pointerId: any, target: any, startTime: any): void;
+    _describeTarget(el: any): string;
+}

package/dist/native/bridge/perf/collectors/InteractionCollector.js

@@ -40,6 +40,10 @@ var _session = require("../core/session.js");
 const SESSION_WINDOW_MS = 2000;
 const MAX_RECENT_INTERACTIONS = 50;
 class InteractionCollector {
+  // Internal collector state, assigned in the constructor. The perf module is
+  // internal to the bridge and deliberately left loosely typed during the
+  // migration, so an index signature stands in for per-field declarations.
+
   constructor(measure) {
     this._measure = measure;
     this._pendingTaps = new Map(); // pointerId → { startMark, startTime, target }

package/dist/native/bridge/perf/collectors/KeyboardCollector.d.ts

@@ -0,0 +1,30 @@
+/**
+ * KeyboardCollector.js
+ *
+ * Instruments: bugs #3, #12
+ *   #3  keyboard sticky scroll   → keyboard-show → viewport-resize → scroll fires during session
+ *                                   if sticky element recalcs during this window it causes thrash
+ *   #12 search input no auto-focus → keyboard-show event should fire after route transition to search
+ *                                    if it doesn't, the native WebView suppressed programmatic focus
+ *
+ * Native events received (via index.js router):
+ *   keyboard-show  { nativeTime, keyboardHeight }
+ *   keyboard-hide  { nativeTime }
+ *
+ * Spans emitted:
+ *   catalyst:session/keyboard   — keyboard-show → viewport settled (Track: Keyboard)
+ *                                 detail: keyboardHeight, viewportDelta, hadScrollDuringSession
+ *   catalyst:viewport-resize    — visualViewport resize → next rAF (Track: Keyboard)
+ *                                 detail: deltaHeight
+ */
+export declare class KeyboardCollector {
+    [key: string]: any;
+    constructor(measure: any, nativeToWeb: any);
+    init(): void;
+    setWaterfallSource(fn: any): void;
+    onKeyboardShow(event: any): void;
+    onKeyboardHide(event: any): void;
+    onScrollDuringKeyboard(): void;
+    _observeVisualViewport(): void;
+    _closeSession(endTime: any): void;
+}

package/dist/native/bridge/perf/collectors/KeyboardCollector.js

@@ -27,6 +27,10 @@ var _session = require("../core/session.js");
  */
 
 class KeyboardCollector {
+  // Internal collector state, assigned in the constructor. The perf module is
+  // internal to the bridge and deliberately left loosely typed during the
+  // migration, so an index signature stands in for per-field declarations.
+
   constructor(measure, nativeToWeb) {
     this._measure = measure;
     this._nativeToWeb = nativeToWeb;

package/dist/native/bridge/perf/collectors/NavigationCollector.d.ts

@@ -0,0 +1,37 @@
+/**
+ * NavigationCollector.js
+ *
+ * Instruments: bugs #2, #7, #9, #11, #14
+ *   #2  back-forward reloads screen     → new nav session opens, cache miss burst follows
+ *   #7  header disappears on back       → route-transition span shows animation torn down early
+ *   #9  forward transition broken       → route-transition fires but no visual end mark
+ *   #11 banner overlaps search box      → nav session ends but layout-shift fires after
+ *   #14 transitions not soft            → skeleton→content swap visible as layout-shift during nav
+ *
+ * Spans emitted:
+ *   catalyst:session/navigation         — page start → LCP finalized (Track: Navigation)
+ *   catalyst:route-transition|<from→to> — popstate/hashchange → rAF settle (Track: Navigation)
+ *   catalyst:lcp|<ms>ms                 — LCP candidate finalized (Track: Navigation)
+ *   catalyst:fcp|<ms>ms                 — FCP (iOS fallback) (Track: Navigation)
+ *   catalyst:page-load|<url>            — native page-load-start → page-load-end (Track: Navigation)
+ *   catalyst:cold-start|<ms>ms          — native app cold start duration (Track: Navigation)
+ *   catalyst:boot/activity-created      — batch: MainActivity.onCreate (Track: Navigation)
+ *   catalyst:boot/webview-constructed   — batch: CustomWebView init{} (Track: Navigation)
+ *   catalyst:boot/load-url              — batch: WebView.loadUrl() call (Track: Navigation)
+ *   catalyst:boot/page-started          — batch: onPageStarted callback (Track: Navigation)
+ *   catalyst:boot/page-finished         — batch: onPageFinished callback (Track: Navigation)
+ */
+export declare class NavigationCollector {
+    [key: string]: any;
+    constructor(measure: any, nativeToWeb: any);
+    init(): void;
+    /** Called by index.js to feed the normalized perf store. */
+    setWaterfallSource(fn: any): void;
+    get isLoading(): any;
+    _observeLCP(): void;
+    _setupLcpFinalization(): void;
+    _finalizeLcp(): void;
+    _observeRouteTransitions(): void;
+    onNativeEvent(event: any): void;
+    onBatchEvent(event: any): void;
+}