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

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

@@ -0,0 +1,215 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.CacheCollector = void 0;
+var _constants = require("../core/constants.js");
+/**
+ * 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
+ */
+
+const TRACK_CACHE_DETAIL = "Cache > Detail";
+class CacheCollector {
+  constructor(measure, nativeToWeb) {
+    this._measure = measure;
+    this._nativeToWeb = nativeToWeb;
+    this._notifyInsights = null; // set by index.js after construction
+  }
+
+  /** Called by index.js to wire up insights notifications for cache-summary. */
+  setInsightsSource(fn) {
+    this._notifyInsights = fn;
+  }
+  init() {
+    // No web-side observers — all events come from native
+  }
+
+  // ── Live path (individual events routed from index.js) ──────────────────
+
+  onNativeEvent(event) {
+    const {
+      type
+    } = event;
+    if (!type?.startsWith("cache-") && type !== "network-fetch-complete") return;
+    this._emitCacheSpan(event, _constants.TRACK.CACHE);
+  }
+
+  // ── Batch path (native buffer flush) ────────────────────────────────────
+
+  onBatchEvent(event) {
+    const {
+      type
+    } = event;
+    if (type === "cache-summary") {
+      this._emitSummarySpan(event);
+      return;
+    }
+    if (!type?.startsWith("cache-") && type !== "network-fetch-complete") return;
+    // Individual cache spans go on the Detail sub-track
+    this._emitCacheSpan(event, TRACK_CACHE_DETAIL);
+  }
+
+  // ── Internal ─────────────────────────────────────────────────────────────
+
+  _emitCacheSpan(event, track) {
+    const {
+      type,
+      url,
+      durationMs,
+      nativeStartMs,
+      resourceType,
+      thread,
+      statusCode
+    } = event;
+    const resType = resourceType ?? "other";
+    const filename = this._filename(url);
+    const endTime = nativeStartMs != null ? this._nativeToWeb(nativeStartMs) + (durationMs ?? 0) : performance.now();
+    const startTime = endTime - (durationMs ?? 0);
+    let measureName, color, detail;
+    const interceptThread = event.interceptThread ?? null;
+    const emitThread = event.emitThread ?? null;
+    if (type === "cache-hit-memory") {
+      measureName = `${_constants.PREFIX.CACHE}/hit|memory|${resType}|${filename}`;
+      color = _constants.COLOR.PRIMARY;
+      detail = {
+        url,
+        source: "memory",
+        resourceType: resType,
+        durationMs,
+        thread: thread ?? null,
+        interceptThread,
+        emitThread,
+        simulatorValid: false
+      };
+    } else if (type === "cache-hit-disk") {
+      measureName = `${_constants.PREFIX.CACHE}/hit|disk|${resType}|${filename}`;
+      color = _constants.COLOR.PRIMARY_LIGHT;
+      detail = {
+        url,
+        source: "disk",
+        resourceType: resType,
+        durationMs,
+        thread: thread ?? null,
+        interceptThread,
+        emitThread,
+        simulatorValid: false
+      };
+    } else if (type === "cache-miss-fetch") {
+      measureName = `${_constants.PREFIX.CACHE}/miss|${resType}|${filename}`;
+      color = _constants.COLOR.ERROR;
+      detail = {
+        url,
+        resourceType: resType,
+        durationMs,
+        thread: thread ?? null,
+        interceptThread,
+        emitThread,
+        simulatorValid: false
+      };
+    } else if (type === "network-fetch-complete") {
+      const slow = (durationMs ?? 0) > _constants.THRESHOLD.FETCH_SLOW_MS;
+      measureName = `${_constants.PREFIX.CACHE}/fetch|${resType}|${filename}`;
+      color = slow ? _constants.COLOR.TERTIARY_DARK : _constants.COLOR.TERTIARY;
+      detail = {
+        url,
+        resourceType: resType,
+        durationMs,
+        statusCode: statusCode ?? null,
+        thread: thread ?? null,
+        emitThread,
+        slow,
+        simulatorValid: false
+      };
+    } else {
+      return;
+    }
+    const startMark = `${measureName}:start:${Math.round(startTime)}`;
+    performance.mark(startMark, {
+      startTime
+    });
+    this._measure.emit(measureName, startMark, endTime, detail, track, color);
+  }
+  _emitSummarySpan(event) {
+    const {
+      hits,
+      misses,
+      fetches,
+      total,
+      hitRatePct,
+      avgFetchMs,
+      topSlowest,
+      nativeTime
+    } = event;
+    if (total === 0) return;
+
+    // Place summary span at current time (post-load, idle phase)
+    const startTime = this._nativeToWeb(nativeTime ?? 0) || performance.now();
+    const endTime = startTime + 1; // point span
+
+    const color = hitRatePct >= 80 ? _constants.COLOR.PRIMARY_DARK : hitRatePct >= 50 ? _constants.COLOR.SECONDARY : _constants.COLOR.ERROR;
+    const topNames = Array.isArray(topSlowest) ? topSlowest.map(e => `${e.filename}(${e.durationMs}ms)`).join(", ") : "";
+    const measureName = `${_constants.PREFIX.CACHE}/summary`;
+    const startMark = `${measureName}:start:${Math.round(startTime)}`;
+    performance.mark(startMark, {
+      startTime
+    });
+    this._measure.emit(measureName, startMark, endTime, {
+      hits,
+      misses,
+      fetches,
+      total,
+      hitRatePct,
+      avgFetchMs,
+      topSlowest: topNames,
+      simulatorValid: false
+    }, _constants.TRACK.CACHE, color);
+
+    // Notify InsightsCollector so it can flag low hit rates
+    this._notifyInsights?.({
+      hitRatePct,
+      total,
+      avgFetchMs,
+      startTime,
+      endTime
+    });
+  }
+  _filename(url) {
+    try {
+      const path = new URL(url).pathname;
+      const name = path.split("/").filter(Boolean).pop() ?? path;
+      return name.slice(0, 40);
+    } catch {
+      return String(url).slice(0, 40);
+    }
+  }
+}
+exports.CacheCollector = CacheCollector;

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

@@ -0,0 +1,165 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.HookCollector = void 0;
+var _constants = require("../core/constants.js");
+/**
+ * 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.
+ */
+
+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 {
+  constructor(measure) {
+    this._measure = measure;
+
+    // Lazy-load detection state
+    this._pendingLazy = null; // { startMark, startTime, target, loafCount, totalBlocking, timer }
+
+    // Computation loop detection state
+    this._loopLoafs = []; // [{ start, end }] in rolling LOOP_WINDOW_MS window
+  }
+  init() {
+    // Watch for taps that might trigger lazy component loads
+    document.addEventListener("pointerdown", this._onPointerDown.bind(this), {
+      passive: true
+    });
+  }
+
+  /** Called by index.js to feed the normalized perf store. */
+  setWaterfallSource(fn) {
+    this._notifyWaterfall = fn;
+  }
+
+  // Called by RenderCollector via addLoafListener() on every LoAF
+  onLoaf(start, end) {
+    // ── Lazy-load window ────────────────────────────────────────────────
+    if (this._pendingLazy) {
+      const p = this._pendingLazy;
+      p.loafCount++;
+      p.totalBlocking += end - start;
+
+      // Reset the close timer — extend window on each LoAF
+      clearTimeout(p.timer);
+      p.timer = setTimeout(() => this._closeLazySpan(), _constants.THRESHOLD.LAZY_LOAF_WINDOW_MS);
+    }
+
+    // ── Computation loop detection ───────────────────────────────────────
+    const now = performance.now();
+    this._loopLoafs.push({
+      start,
+      end
+    });
+    // Evict entries outside the rolling window
+    this._loopLoafs = this._loopLoafs.filter(e => now - e.start < LOOP_WINDOW_MS);
+    if (this._loopLoafs.length >= LOOP_LOAF_COUNT) {
+      this._emitLoopSpan();
+      this._loopLoafs = []; // reset after emitting to avoid duplicate spans
+    }
+  }
+
+  // ─── Lazy-load span ───────────────────────────────────────────────────────
+
+  _onPointerDown(e) {
+    // If a lazy span is already open, let it close naturally
+    if (this._pendingLazy) return;
+    const target = e.target?.tagName?.toLowerCase() ?? "unknown";
+    const startTime = performance.now();
+    const startMark = `${_constants.PREFIX.HOOK_LAZY}:start:${Math.round(startTime)}`;
+    performance.mark(startMark, {
+      startTime
+    });
+    const timer = setTimeout(() => this._closeLazySpan(), _constants.THRESHOLD.LAZY_LOAF_WINDOW_MS);
+    this._pendingLazy = {
+      startMark,
+      startTime,
+      target,
+      loafCount: 0,
+      totalBlocking: 0,
+      timer
+    };
+  }
+  _closeLazySpan() {
+    const p = this._pendingLazy;
+    if (!p) return;
+    this._pendingLazy = null;
+    clearTimeout(p.timer);
+
+    // Only emit if LoAF actually fired — otherwise it was a clean interaction
+    if (p.loafCount === 0) return;
+    const endTime = performance.now();
+    this._measure.emit(`${_constants.PREFIX.HOOK_LAZY}|${p.target}`, p.startMark, endTime, {
+      loafCount: p.loafCount,
+      totalBlockingMs: Math.round(p.totalBlocking),
+      triggerTarget: p.target,
+      likelyCause: "lazy-load",
+      simulatorValid: false
+    }, _constants.TRACK.HOOK);
+    this._notifyWaterfall?.({
+      hookType: "lazy-load",
+      label: `Hook lazy-load ${p.target}`,
+      startTime: p.startTime,
+      endTime,
+      durationMs: Math.round(endTime - p.startTime),
+      loafCount: p.loafCount,
+      totalBlockingMs: Math.round(p.totalBlocking),
+      likelyCause: "lazy-load"
+    });
+  }
+
+  // ─── Computation loop span ────────────────────────────────────────────────
+
+  _emitLoopSpan() {
+    const first = this._loopLoafs[0];
+    const last = this._loopLoafs[this._loopLoafs.length - 1];
+    const markName = `${_constants.PREFIX.HOOK_MOUNT}:loop:${Math.round(first.start)}`;
+    performance.mark(markName, {
+      startTime: first.start
+    });
+    const totalBlocking = this._loopLoafs.reduce((sum, e) => sum + (e.end - e.start), 0);
+    this._measure.emit(`${_constants.PREFIX.HOOK_MOUNT}|loop`, markName, last.end, {
+      loafCount: this._loopLoafs.length,
+      windowMs: Math.round(last.end - first.start),
+      totalBlockingMs: Math.round(totalBlocking),
+      likelyCause: "computation-loop",
+      simulatorValid: false
+    }, _constants.TRACK.HOOK);
+    this._notifyWaterfall?.({
+      hookType: "computation-loop",
+      label: "Hook computation loop",
+      startTime: first.start,
+      endTime: last.end,
+      durationMs: Math.round(last.end - first.start),
+      loafCount: this._loopLoafs.length,
+      totalBlockingMs: Math.round(totalBlocking),
+      likelyCause: "computation-loop"
+    });
+  }
+}
+exports.HookCollector = HookCollector;