catalyst-core 0.2.0-beta.2 → 0.3.0-beta.1

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

@@ -0,0 +1,273 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.InteractionCollector = void 0;
+var _constants = require("../core/constants.js");
+var _session = require("../core/session.js");
+/**
+ * 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.
+ */
+
+const SESSION_WINDOW_MS = 2000;
+const MAX_RECENT_INTERACTIONS = 50;
+class InteractionCollector {
+  constructor(measure) {
+    this._measure = measure;
+    this._pendingTaps = new Map(); // pointerId → { startMark, startTime, target }
+    this._session = new _session.Session(_constants.PREFIX.SESSION_INTERACTION, measure, _constants.TRACK.INTERACTION);
+    this._sessionTimer = null;
+    this._sessionId = null;
+    this._sessionNetworkCalls = 0;
+    this._sessionFpsDrop = false;
+    this._activeInteraction = null;
+    this._recentInteractions = [];
+    this._interactionSeq = 0;
+  }
+
+  // ─── Public API — queried by native API and render collectors ──────────────
+
+  get activeInteractionId() {
+    return this._activeInteraction?.id ?? null;
+  }
+  interactionIdForRange(startTime, endTime = startTime) {
+    const interactions = this._activeInteraction ? [...this._recentInteractions, this._activeInteraction] : this._recentInteractions;
+    return interactions.slice().reverse().find(interaction => startTime <= (interaction.endTime ?? performance.now()) && endTime >= interaction.startTime)?.id ?? null;
+  }
+
+  /** Called by index.js to wire up insights notifications. */
+  setInsightsSource(fn) {
+    this._notifyInsights = fn;
+  }
+
+  /** Called by index.js to feed the normalized perf store. */
+  setWaterfallSource(fn) {
+    this._notifyWaterfall = fn;
+  }
+
+  /** Called by RenderCollector when an fps-drop-episode fires. */
+  onFpsDrop() {
+    if (this._session.isOpen) {
+      this._sessionFpsDrop = true;
+      this._session.set("fpsDrop", true);
+    }
+  }
+
+  /** Called by NetworkTimingCollector when a fetch/XHR starts during an interaction. */
+  onNetworkCall() {
+    if (this._session.isOpen) {
+      this._sessionNetworkCalls++;
+      this._session.set("networkCalls", this._sessionNetworkCalls);
+    }
+  }
+  init() {
+    document.addEventListener("pointerdown", this._onPointerDown.bind(this), {
+      passive: true
+    });
+    document.addEventListener("pointerup", this._onPointerUp.bind(this), {
+      passive: true
+    });
+    document.addEventListener("pointercancel", this._onPointerCancel.bind(this), {
+      passive: true
+    });
+  }
+  _openSession(target, startTime) {
+    // Close any existing session immediately — new tap = new session
+    this._closeSession();
+    this._sessionId = `${Math.round(startTime)}`;
+    this._sessionNetworkCalls = 0;
+    this._sessionFpsDrop = false;
+    this._session.open({
+      target,
+      sessionId: this._sessionId,
+      networkCalls: 0,
+      fpsDrop: false
+    }, startTime);
+    this._notifyWaterfall?.({
+      phase: "start",
+      target,
+      sessionId: this._sessionId,
+      startTime
+    });
+
+    // Auto-close after 2s
+    this._sessionTimer = setTimeout(() => this._closeSession(), SESSION_WINDOW_MS);
+  }
+  _closeSession() {
+    if (this._sessionTimer) {
+      clearTimeout(this._sessionTimer);
+      this._sessionTimer = null;
+    }
+    if (this._session.isOpen) {
+      const target = this._session.get("target");
+      const startTime = this._session.startTime;
+      const endTime = performance.now();
+      this._session.close({
+        sessionId: this._sessionId,
+        networkCalls: this._sessionNetworkCalls,
+        fpsDrop: this._sessionFpsDrop
+      }, endTime, this._sessionFpsDrop ? "error" : "secondary");
+      this._notifyWaterfall?.({
+        phase: "end",
+        target,
+        sessionId: this._sessionId,
+        networkCalls: this._sessionNetworkCalls,
+        fpsDrop: this._sessionFpsDrop,
+        startTime,
+        endTime,
+        durationMs: Math.round(endTime - startTime)
+      });
+    }
+    this._sessionId = null;
+  }
+  _onPointerDown(e) {
+    const startTime = performance.now();
+    const target = this._describeTarget(e.target);
+    const startMark = `${_constants.PREFIX.INTERACTION}:${e.pointerId}:start`;
+    const interactionId = `Tap #${++this._interactionSeq}`;
+    performance.mark(startMark, {
+      startTime
+    });
+    this._activeInteraction = {
+      id: interactionId,
+      startTime,
+      endTime: null
+    };
+    this._measure.marker(`${interactionId}: ${target}`, startTime, {
+      interactionId,
+      target
+    }, "secondary");
+
+    // The old 2s parent session
+    // this._openSession(target, startTime)
+
+    // Long-press detection timer
+    const longPressTimer = setTimeout(() => {
+      this._emitLongPress(e.pointerId, target, startTime);
+    }, _constants.THRESHOLD.LONG_PRESS_MS);
+    this._pendingTaps.set(e.pointerId, {
+      startMark,
+      startTime,
+      target,
+      interactionId,
+      longPressTimer
+    });
+
+    // Measure tap → next paint (interaction responsiveness)
+    requestAnimationFrame(() => {
+      const endTime = performance.now();
+      const tap = this._pendingTaps.get(e.pointerId);
+      if (!tap) return;
+      tap.frameComplete = true;
+      if (tap.released) this._pendingTaps.delete(e.pointerId);
+      this._rememberInteraction(interactionId, startTime, endTime);
+      const responseMs = Math.round(endTime - startTime);
+      if (responseMs > _constants.THRESHOLD.INTERACTION_SLOW_MS) {
+        this._notifyInsights?.({
+          target,
+          responseMs,
+          startTime,
+          endTime,
+          interactionId
+        });
+      }
+      this._measure.emit(`${interactionId}: ${target} - ${responseMs}ms`, startMark, endTime, {
+        responseMs,
+        loafOverlap: this._measure.overlapsLoaf(startTime, endTime),
+        target,
+        interactionId,
+        simulatorValid: false
+      }, _constants.TRACK.INTERACTION);
+      this._notifyWaterfall?.({
+        phase: "end",
+        target,
+        sessionId: interactionId,
+        networkCalls: 0,
+        fpsDrop: false,
+        startTime,
+        endTime,
+        durationMs: responseMs,
+        responseMs,
+        shortInteraction: true
+      });
+    });
+  }
+  _onPointerUp(e) {
+    const tap = this._pendingTaps.get(e.pointerId);
+    if (tap) {
+      clearTimeout(tap.longPressTimer);
+      tap.released = true;
+      if (tap.frameComplete) this._pendingTaps.delete(e.pointerId);
+    }
+  }
+  _onPointerCancel(e) {
+    const tap = this._pendingTaps.get(e.pointerId);
+    if (!tap) return;
+    clearTimeout(tap.longPressTimer);
+    this._pendingTaps.delete(e.pointerId);
+    if (this._activeInteraction?.id === tap.interactionId) this._activeInteraction = null;
+  }
+  _rememberInteraction(id, startTime, endTime) {
+    this._recentInteractions.push({
+      id,
+      startTime,
+      endTime
+    });
+    if (this._recentInteractions.length > MAX_RECENT_INTERACTIONS) {
+      this._recentInteractions.shift();
+    }
+    if (this._activeInteraction?.id === id) this._activeInteraction = null;
+  }
+  _emitLongPress(pointerId, target, startTime) {
+    const tap = this._pendingTaps.get(pointerId);
+    if (!tap) return;
+    const endTime = performance.now();
+    const heldMs = Math.round(endTime - startTime);
+    const markName = `${_constants.PREFIX.LONG_PRESS}:${Math.round(startTime)}`;
+    performance.mark(markName, {
+      startTime
+    });
+    this._measure.emit(`${tap.interactionId}: Long press ${target} - ${heldMs}ms`, markName, endTime, {
+      target,
+      heldMs,
+      interactionId: tap.interactionId,
+      simulatorValid: true
+    }, _constants.TRACK.INTERACTION, "tertiary");
+  }
+  _describeTarget(el) {
+    if (!el) return "unknown";
+    const tag = el.tagName?.toLowerCase() ?? "unknown";
+    const id = el.id ? `#${el.id}` : "";
+    const cls = el.classList?.length ? `.${[...el.classList].slice(0, 2).join(".")}` : "";
+    return `${tag}${id}${cls}`.slice(0, 40);
+  }
+}
+exports.InteractionCollector = InteractionCollector;

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

@@ -0,0 +1,124 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.KeyboardCollector = void 0;
+var _constants = require("../core/constants.js");
+var _session = require("../core/session.js");
+/**
+ * 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
+ */
+
+class KeyboardCollector {
+  constructor(measure, nativeToWeb) {
+    this._measure = measure;
+    this._nativeToWeb = nativeToWeb;
+    this._session = new _session.Session(_constants.PREFIX.SESSION_KEYBOARD, measure, _constants.TRACK.INPUT);
+  }
+  init() {
+    this._observeVisualViewport();
+  }
+  setWaterfallSource(fn) {
+    this._notifyWaterfall = fn;
+  }
+
+  // ─── Native event handlers ────────────────────────────────────────────────
+
+  onKeyboardShow(event) {
+    const webNow = this._nativeToWeb(event.nativeTime);
+    this._session.open({
+      keyboardHeight: event.keyboardHeight,
+      hadScroll: false
+    }, webNow);
+  }
+  onKeyboardHide(event) {
+    const webNow = this._nativeToWeb(event.nativeTime);
+    if (this._session.isOpen) {
+      this._closeSession(webNow);
+    }
+    // Emit a point mark so keyboard-hide is visible on the timeline
+    const hideMark = `catalyst:keyboard-hide:${Math.round(webNow)}`;
+    performance.mark(hideMark, {
+      startTime: webNow
+    });
+  }
+
+  // Called by ScrollCollector (via index.js) if scroll fires while keyboard open
+  onScrollDuringKeyboard() {
+    if (this._session.isOpen) {
+      this._session.set("hadScroll", true);
+    }
+  }
+
+  // ─── Viewport resize ──────────────────────────────────────────────────────
+  // Fires when keyboard pushes/pulls the viewport.
+  // Also closes the keyboard session — viewport settling = keyboard done.
+
+  _observeVisualViewport() {
+    if (!window.visualViewport) return;
+    let lastHeight = window.visualViewport.height;
+    window.visualViewport.addEventListener("resize", () => {
+      const now = performance.now();
+      const newHeight = window.visualViewport.height;
+      const delta = Math.abs(newHeight - lastHeight);
+      lastHeight = newHeight;
+      if (delta < _constants.THRESHOLD.VIEWPORT_MIN_DELTA) return;
+      const markName = `${_constants.PREFIX.VIEWPORT_RESIZE}:start:${Math.round(now)}`;
+      performance.mark(markName, {
+        startTime: now
+      });
+      requestAnimationFrame(() => {
+        const endTime = performance.now();
+        const durationMs = Math.round(endTime - now);
+        this._measure.emit(_constants.PREFIX.VIEWPORT_RESIZE, markName, endTime, {
+          deltaHeight: Math.round(delta),
+          simulatorValid: true
+        }, _constants.TRACK.INPUT);
+        this._notifyWaterfall?.({
+          metric: "viewport-resize",
+          startTime: now,
+          endTime,
+          durationMs,
+          deltaHeight: Math.round(delta)
+        });
+        if (this._session.isOpen) {
+          this._closeSession(endTime);
+        }
+      });
+    });
+  }
+  _closeSession(endTime) {
+    const startTime = this._session.startTime;
+    const detail = {
+      keyboardHeight: this._session.get("keyboardHeight"),
+      hadScrollDuringSession: this._session.get("hadScroll"),
+      simulatorValid: false
+    };
+    this._session.close(detail, endTime);
+    this._notifyWaterfall?.({
+      kind: "keyboard",
+      startTime,
+      endTime,
+      durationMs: Math.round(endTime - startTime),
+      ...detail
+    });
+  }
+}
+exports.KeyboardCollector = KeyboardCollector;

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

@@ -0,0 +1,294 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.NavigationCollector = void 0;
+var _constants = require("../core/constants.js");
+var _session = require("../core/session.js");
+/**
+ * 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)
+ */
+
+class NavigationCollector {
+  constructor(measure, nativeToWeb) {
+    this._measure = measure;
+    this._nativeToWeb = nativeToWeb ?? (t => t);
+    this._session = new _session.Session(_constants.PREFIX.SESSION_NAV, measure, _constants.TRACK.NAVIGATION);
+    this._pendingLcp = null; // { entry, label } — buffered until finalized
+    this._lcpFinalized = false;
+    // Track pending native page-load spans: url → { markName, startWeb }
+    this._pendingPageLoads = new Map();
+  }
+  init() {
+    this._session.open();
+    this._observeLCP();
+    this._observeRouteTransitions();
+    this._setupLcpFinalization();
+  }
+
+  /** Called by index.js to feed the normalized perf store. */
+  setWaterfallSource(fn) {
+    this._notifyWaterfall = fn;
+  }
+
+  // Called by other collectors to check if nav is still loading
+  get isLoading() {
+    return this._session.isOpen;
+  }
+
+  // ─── LCP ──────────────────────────────────────────────────────────────────
+
+  _observeLCP() {
+    const types = PerformanceObserver.supportedEntryTypes ?? [];
+    const type = types.includes("largest-contentful-paint") ? "largest-contentful-paint" : types.includes("paint") ? "paint" : null;
+    if (!type) return;
+    const obs = new PerformanceObserver(list => {
+      for (const entry of list.getEntries()) {
+        if (type === "paint" && entry.name !== "first-contentful-paint") continue;
+        const label = type === "largest-contentful-paint" ? "lcp" : "fcp";
+        this._pendingLcp = {
+          entry,
+          label
+        }; // overwrite — keep latest candidate
+      }
+    });
+    obs.observe({
+      type,
+      buffered: true
+    });
+  }
+  _setupLcpFinalization() {
+    // Browser stops updating LCP candidate on first user interaction or page hide
+    const finalize = () => {
+      this._finalizeLcp();
+      document.removeEventListener("pointerdown", finalize);
+      document.removeEventListener("keydown", finalize);
+    };
+    document.addEventListener("pointerdown", finalize);
+    document.addEventListener("keydown", finalize);
+    document.addEventListener("visibilitychange", () => {
+      if (document.visibilityState === "hidden") this._finalizeLcp();
+    });
+  }
+  _finalizeLcp() {
+    if (this._lcpFinalized || !this._pendingLcp) return;
+    this._lcpFinalized = true;
+    const {
+      entry,
+      label
+    } = this._pendingLcp;
+    this._pendingLcp = null;
+    const markName = `${_constants.PREFIX[label.toUpperCase()]}:mark`;
+    performance.mark(markName, {
+      startTime: 0
+    });
+    this._measure.emit(`${_constants.PREFIX[label.toUpperCase()]}|${Math.round(entry.startTime)}ms`, markName, entry.startTime, {
+      renderTime: entry.renderTime ?? null,
+      loadTime: entry.loadTime ?? null,
+      simulatorValid: false
+    }, _constants.TRACK.NAVIGATION);
+    this._notifyWaterfall?.({
+      label: label.toUpperCase(),
+      startTime: 0,
+      endTime: entry.startTime,
+      durationMs: Math.round(entry.startTime)
+    });
+
+    // LCP finalized = page is loaded — close the navigation session
+    this._session.close({
+      simulatorValid: false
+    }, entry.startTime);
+  }
+
+  // ─── Route transitions ────────────────────────────────────────────────────
+  // Detects SPA route changes via popstate + hashchange.
+  // Emits a span from event fire → next rAF (visual settle).
+  //
+  // Covers:
+  //   #7  — if rAF never fires cleanly, transition span shows the gap
+  //   #9  — span fires on back but not on some forward routes → missing spans = broken routes
+  //   #11 — nav session re-opens; layout-shift collector shows shift after session close
+
+  _observeRouteTransitions() {
+    let _fromPath = location.pathname + location.hash;
+    const onTransition = e => {
+      const from = _fromPath;
+      const to = location.pathname + location.hash;
+      _fromPath = to;
+      const startTime = performance.now();
+      const markName = `${_constants.PREFIX.ROUTE_TRANSITION}:start:${Math.round(startTime)}`;
+      performance.mark(markName, {
+        startTime
+      });
+
+      // Re-open nav session for the SPA route change.
+      // LCP only fires once per WebView load — it does not reset on pushState.
+      // So we can't wait for LCP to close the session. Instead, close it after
+      // the next rAF (visual settle) + a short timeout to catch deferred renders.
+      if (!this._session.isOpen) {
+        this._lcpFinalized = false;
+        this._session.open({}, startTime);
+        this._setupLcpFinalization();
+        // Fallback: if LCP doesn't fire (SPA), close after rAF + 1s
+        requestAnimationFrame(() => {
+          setTimeout(() => {
+            if (this._session.isOpen && !this._lcpFinalized) {
+              this._session.close({
+                simulatorValid: true
+              }, performance.now());
+            }
+          }, 1000);
+        });
+      }
+      requestAnimationFrame(() => {
+        const endTime = performance.now();
+        this._measure.emit(`${_constants.PREFIX.ROUTE_TRANSITION}|${from}→${to}`, markName, endTime, {
+          from,
+          to,
+          type: e.type,
+          // 'popstate' or 'hashchange'
+          simulatorValid: true
+        }, _constants.TRACK.NAVIGATION);
+        this._notifyWaterfall?.({
+          label: `Route ${to}`,
+          startTime,
+          endTime,
+          durationMs: Math.round(endTime - startTime)
+        });
+      });
+    };
+    window.addEventListener("popstate", onTransition);
+    window.addEventListener("hashchange", onTransition);
+  }
+
+  // ─── Native page-load events (from CustomWebview.kt) ─────────────────────
+  // page-load-start: fired by onPageStarted, carries nativeTime + url
+  // page-load-end:   fired by onPageFinished, carries nativeTime + url + durationMs
+  // page-load-error: fired by onReceivedError, carries nativeTime + url + errorCode
+
+  onNativeEvent(event) {
+    switch (event.type) {
+      case "page-load-start":
+        {
+          const startWeb = this._nativeToWeb(event.nativeTime);
+          const markName = `${_constants.PREFIX.PAGE_LOAD}:start:${Math.round(startWeb)}`;
+          performance.mark(markName, {
+            startTime: startWeb
+          });
+          this._pendingPageLoads.set(event.url, {
+            markName,
+            startWeb
+          });
+          break;
+        }
+      case "page-load-end":
+        {
+          const pending = this._pendingPageLoads.get(event.url);
+          if (!pending) break;
+          this._pendingPageLoads.delete(event.url);
+          const endWeb = this._nativeToWeb(event.nativeTime);
+          const durMs = event.durationMs ?? Math.round(endWeb - pending.startWeb);
+          const isSlow = durMs > 2500;
+          this._measure.emit(`${_constants.PREFIX.PAGE_LOAD}|${event.url.split("/").pop() || event.url}`, pending.markName, endWeb, {
+            url: event.url,
+            durationMs: durMs,
+            simulatorValid: true
+          }, _constants.TRACK.NAVIGATION, isSlow ? "error" : "primary");
+          break;
+        }
+      case "page-load-error":
+        {
+          const pending = this._pendingPageLoads.get(event.url);
+          const startWeb = pending ? pending.startWeb : this._nativeToWeb(event.nativeTime);
+          const markName = pending ? pending.markName : `${_constants.PREFIX.PAGE_LOAD}:err:${Math.round(startWeb)}`;
+          if (!pending) performance.mark(markName, {
+            startTime: startWeb
+          });
+          this._pendingPageLoads.delete(event.url);
+          const errEnd = this._nativeToWeb(event.nativeTime) + 1;
+          this._measure.emit(`${_constants.PREFIX.PAGE_LOAD}/error|${event.errorCode ?? "?"}`, markName, errEnd, {
+            url: event.url,
+            errorCode: event.errorCode,
+            description: event.description ?? "",
+            simulatorValid: true
+          }, _constants.TRACK.NAVIGATION, "error");
+          break;
+        }
+      case "cold-start":
+        {
+          // emitted by markAppStartComplete() — point-in-time span at page init
+          const startWeb = this._nativeToWeb(event.nativeTime);
+          const markName = `${_constants.PREFIX.COLD_START}:mark`;
+          performance.mark(markName, {
+            startTime: Math.max(0, startWeb - event.durationMs)
+          });
+          this._measure.emit(`${_constants.PREFIX.COLD_START}|${event.durationMs}ms`, markName, startWeb, {
+            durationMs: event.durationMs,
+            simulatorValid: true
+          }, _constants.TRACK.NAVIGATION, event.durationMs > 3000 ? "error" : "secondary");
+          break;
+        }
+    }
+  }
+
+  // ─── Batch boot timing events ─────────────────────────────────────────────
+  // Emitted from PerfEventBuffer flush after onPageFinished.
+  // Each boot-* event is a point-in-time marker on Catalyst > Navigation.
+
+  onBatchEvent(event) {
+    if (event.type === "navigation-back") {
+      const t = this._nativeToWeb(event.nativeTime);
+      const markName = `catalyst:navigation/back:${Math.round(t)}`;
+      performance.mark(markName, {
+        startTime: Math.max(0, t)
+      });
+      this._measure.emit("catalyst:navigation/back", markName, Math.max(0, t) + 1, {
+        simulatorValid: false
+      }, _constants.TRACK.NAVIGATION, _constants.COLOR.SECONDARY);
+      return;
+    }
+    const bootTypeMap = {
+      "boot-activity-created": "activity-created",
+      "boot-webview-constructed": "webview-constructed",
+      "boot-load-url": "load-url",
+      "boot-page-started": "page-started",
+      "boot-page-finished": "page-finished"
+    };
+    const label = bootTypeMap[event.type];
+    if (!label) return;
+    const t = this._nativeToWeb(event.nativeTime);
+    const markName = `catalyst:boot/${label}:${Math.round(t)}`;
+    performance.mark(markName, {
+      startTime: Math.max(0, t)
+    });
+    this._measure.emit(`catalyst:boot/${label}`, markName, Math.max(0, t) + 1,
+    // point span
+    {
+      nativeTime: event.nativeTime,
+      thread: event.thread ?? null,
+      simulatorValid: false
+    }, _constants.TRACK.NAVIGATION, _constants.COLOR.SECONDARY_LIGHT);
+  }
+}
+exports.NavigationCollector = NavigationCollector;