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

package/dist/native/bridge/perf/core/constants.js

@@ -0,0 +1,126 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.TRACK_GROUP = exports.TRACK = exports.THRESHOLD = exports.PREFIX = exports.COLOR = void 0;
+/**
+ * constants.js
+ *
+ * Single source of truth for track names, thresholds, and color rules.
+ * All collectors import from here — no magic strings scattered across files.
+ */
+
+// ─── Chrome DevTools track group ─────────────────────────────────────────────
+
+const TRACK_GROUP = exports.TRACK_GROUP = "Catalyst";
+const TRACK = exports.TRACK = {
+  NAVIGATION: "Navigation",
+  SCROLL: "Scroll",
+  INPUT: "Input",
+  KEYBOARD: "Keyboard",
+  // alias kept for backward compat — collectors use TRACK.INPUT
+  RENDER: "Render",
+  MEMORY: "Memory",
+  CACHE: "Cache",
+  NETWORK: "Network",
+  HOOK: "Hook",
+  INTERACTION: "Interaction",
+  INSIGHTS: "Insights",
+  NATIVE_API: "Native API"
+};
+
+// ─── Measure name prefixes ────────────────────────────────────────────────────
+
+const PREFIX = exports.PREFIX = {
+  SESSION_NAV: "catalyst:session/navigation",
+  SESSION_SCROLL: "catalyst:session/scroll",
+  SESSION_INPUT: "catalyst:session/input",
+  SESSION_KEYBOARD: "catalyst:session/keyboard",
+  // alias — KeyboardCollector still uses this
+  LCP: "catalyst:lcp",
+  FCP: "catalyst:fcp",
+  LOAF: "catalyst:loaf",
+  LAYOUT_SHIFT: "catalyst:layout-shift",
+  VIEWPORT_RESIZE: "catalyst:viewport-resize",
+  ROUTE_TRANSITION: "catalyst:route-transition",
+  CACHE: "catalyst:cache",
+  CACHE_GROUP: "catalyst:cache-group",
+  NETWORK_TIMING: "catalyst:network",
+  NATIVE_API: "catalyst:native-api",
+  HOOK_MOUNT: "catalyst:hook/mount",
+  HOOK_LAZY: "catalyst:hook/lazy",
+  INTERACTION: "catalyst:interaction",
+  SESSION_INTERACTION: "catalyst:session/interaction",
+  LONG_PRESS: "catalyst:long-press",
+  INSIGHT: "catalyst:insight",
+  HW_ACCEL: "catalyst:hw-accel",
+  // Native MetricsMonitor events
+  PAGE_LOAD: "catalyst:page-load",
+  COLD_START: "catalyst:cold-start",
+  FPS_DROP: "catalyst:fps-drop",
+  LONG_TASK: "catalyst:long-task",
+  MEMORY_JVM: "catalyst:mem/jvm",
+  MEMORY_NATIVE: "catalyst:mem/native",
+  MEMORY_TOTAL: "catalyst:mem/total"
+};
+
+// ─── Thresholds ───────────────────────────────────────────────────────────────
+
+const THRESHOLD = exports.THRESHOLD = {
+  LCP_BAD_MS: 2500,
+  // LCP > 2.5s = poor (Core Web Vitals)
+  NAV_SESSION_BAD_MS: 2500,
+  // navigation session > 2.5s = slow page
+  FETCH_SLOW_MS: 300,
+  // network fetch > 300ms = slow
+  SCROLL_IDLE_MS: 150,
+  // scroll ends after 150ms of no scroll events
+  VIEWPORT_MIN_DELTA: 50,
+  // ignore viewport resize < 50px (not keyboard)
+  CACHE_GROUP_IDLE_MS: 300,
+  // close cache group after 300ms idle
+  LOAF_WINDOW: 5,
+  // keep last N LoAF entries for overlap detection
+  LONG_PRESS_MS: 500,
+  // pointerdown held > 500ms = long press
+  INTERACTION_SLOW_MS: 100,
+  // tap → paint > 100ms = slow response
+  LAZY_LOAF_WINDOW_MS: 2000,
+  // watch for LoAF bursts up to 2s after interaction
+  CLS_BAD: 0.1 // CLS > 0.1 per entry = significant shift
+};
+
+// ─── Colors ───────────────────────────────────────────────────────────────────
+// Chrome DevTools Extensibility API color values (all 9 values):
+//
+//   primary / primary-light / primary-dark    → blue tones
+//   secondary / secondary-light / secondary-dark → purple/grey tones
+//   tertiary / tertiary-light / tertiary-dark → yellow/orange tones
+//   error                                     → red
+//
+// Usage guide:
+//   error          = bad outcome (LoAF, miss, slow native API, memory critical)
+//   primary        = cache HIT memory (fastest path)
+//   primary-light  = cache HIT disk (good, slightly slower)
+//   primary-dark   = good LCP, clean scroll session
+//   secondary      = informational (native API, keyboard, viewport, mem/total normal)
+//   primary        = mem/jvm (JVM heap — your Kotlin/Java code)
+//   tertiary-dark  = mem/native (V8 + Blink + JNI — WebView proxy; watch for growth)
+//   secondary-light = route transition, hook mount (neutral)
+//   tertiary       = network fetch after miss (expected but slow)
+//   tertiary-light = small CLS, long-press (low signal)
+//   tertiary-dark  = insight warning (non-critical)
+
+const COLOR = exports.COLOR = {
+  ERROR: "error",
+  PRIMARY: "primary",
+  PRIMARY_LIGHT: "primary-light",
+  PRIMARY_DARK: "primary-dark",
+  SECONDARY: "secondary",
+  SECONDARY_LIGHT: "secondary-light",
+  SECONDARY_DARK: "secondary-dark",
+  TERTIARY: "tertiary",
+  TERTIARY_LIGHT: "tertiary-light",
+  TERTIARY_DARK: "tertiary-dark"
+};

package/dist/native/bridge/perf/core/measure.js

@@ -0,0 +1,189 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.Measure = void 0;
+var _constants = require("./constants.js");
+/**
+ * measure.js
+ *
+ * Shared _measure() and _colorFor() logic used by every collector.
+ * Injected as a dependency — collectors never call performance.measure() directly.
+ *
+ * Chrome DevTools Extensibility API rules (Chrome 128+):
+ *   - detail must be { devtools: { dataType:'track-entry', ... } }
+ *   - custom data goes in properties[] as [key, value] pairs
+ *   - start AND end must both be numeric ms timestamps — passing a mark name
+ *     string as start causes silent fallback to Timings row (confirmed Chrome 145)
+ */
+
+const INTERNAL_PROPERTIES = new Set(["simulatorValid"]);
+const PROPERTY_LABELS = {
+  interactionId: "Related tap",
+  parentOperation: "Parent operation",
+  callId: "Call ID",
+  requestId: "Request ID",
+  memoryId: "Memory sample"
+};
+const PROPERTY_PRIORITY = {
+  interactionId: 0,
+  parentOperation: 1,
+  outcome: 2,
+  ok: 3,
+  status: 4,
+  durationMs: 5,
+  roundTripMs: 5,
+  responseMs: 5
+};
+class Measure {
+  constructor() {
+    // Rolling window of recent LoAF entries — shared across all collectors
+    // so any collector can check loafOverlap without knowing about others.
+    this._recentLoafs = [];
+  }
+
+  /**
+   * Record a LoAF entry so overlap detection stays current.
+   * Called by RenderCollector whenever a long-animation-frame fires.
+   */
+  recordLoaf(start, end) {
+    this._recentLoafs.push({
+      start,
+      end
+    });
+    if (this._recentLoafs.length > _constants.THRESHOLD.LOAF_WINDOW) {
+      this._recentLoafs.shift();
+    }
+  }
+  overlapsLoaf(startMs, endMs) {
+    return this._recentLoafs.some(loaf => startMs < loaf.end && endMs > loaf.start);
+  }
+
+  /**
+   * Emit a performance.measure() with Chrome DevTools Extensibility API metadata.
+   *
+   * @param {string} name      - measure name (catalyst:...)
+   * @param {string} startMark - name of the opening performance.mark()
+   * @param {number} endTime   - end time in ms (performance.now()-space)
+   * @param {object} detail    - arbitrary detail fields added as properties[]
+   * @param {string} track     - Chrome DevTools track name (from TRACK constant)
+   * @param {string} [color]   - override color; if omitted, derived from name+detail
+   * @param {string} [trackGroup] - Chrome DevTools track group
+   */
+  emit(name, startMark, endTime, detail = {}, track, color = null, trackGroup = _constants.TRACK_GROUP) {
+    try {
+      const startTime = performance.getEntriesByName(startMark, "mark")[0]?.startTime;
+      if (startTime == null) {
+        console.warn("[CatalystPerf] measure skipped — mark not found:", startMark);
+        return;
+      }
+      const resolvedColor = color ?? this._colorFor(name, detail, startTime, endTime);
+      const properties = this._properties(detail);
+      performance.measure(name, {
+        start: startTime,
+        end: endTime,
+        detail: {
+          devtools: {
+            dataType: "track-entry",
+            trackGroup,
+            track,
+            color: resolvedColor,
+            tooltipText: name,
+            properties
+          }
+        }
+      });
+    } catch (e) {
+      console.warn("[CatalystPerf] measure failed:", name, e.message);
+    }
+  }
+  marker(name, startTime, detail = {}, color = _constants.COLOR.SECONDARY) {
+    try {
+      performance.mark(name, {
+        startTime,
+        detail: {
+          devtools: {
+            dataType: "marker",
+            color,
+            tooltipText: name,
+            properties: this._properties(detail)
+          }
+        }
+      });
+    } catch (e) {
+      console.warn("[CatalystPerf] marker failed:", name, e.message);
+    }
+  }
+  _properties(detail) {
+    return Object.entries(detail).filter(([key, value]) => !INTERNAL_PROPERTIES.has(key) && value != null).sort(([left], [right]) => (PROPERTY_PRIORITY[left] ?? 100) - (PROPERTY_PRIORITY[right] ?? 100)).map(([key, value]) => [this._propertyName(key), this._propertyValue(value)]);
+  }
+  _propertyName(key) {
+    if (PROPERTY_LABELS[key]) return PROPERTY_LABELS[key];
+    return key.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/[._-]+/g, " ").replace(/^./, char => char.toUpperCase());
+  }
+  _propertyValue(value) {
+    if (typeof value === "object") {
+      try {
+        return JSON.stringify(value);
+      } catch {
+        return String(value);
+      }
+    }
+    return String(value);
+  }
+
+  // ─── Color derivation ─────────────────────────────────────────────────────
+
+  _colorFor(name, detail, startTime, endTime) {
+    const duration = endTime - startTime;
+
+    // LoAF — always error (it's a bad frame by definition)
+    if (name.startsWith(_constants.PREFIX.LOAF)) return _constants.COLOR.ERROR;
+
+    // LCP — error if slow
+    if (name.startsWith(_constants.PREFIX.LCP)) return detail.renderTime > _constants.THRESHOLD.LCP_BAD_MS ? _constants.COLOR.ERROR : _constants.COLOR.PRIMARY;
+    if (name.startsWith(_constants.PREFIX.FCP)) return _constants.COLOR.PRIMARY;
+
+    // Navigation session
+    if (name.startsWith(_constants.PREFIX.SESSION_NAV)) return duration > _constants.THRESHOLD.NAV_SESSION_BAD_MS ? _constants.COLOR.ERROR : _constants.COLOR.PRIMARY;
+
+    // Route transition
+    if (name.startsWith(_constants.PREFIX.ROUTE_TRANSITION)) return _constants.COLOR.SECONDARY;
+
+    // Scroll session — error if janky
+    if (name.startsWith(_constants.PREFIX.SESSION_SCROLL)) return detail.loafCount > 0 ? _constants.COLOR.ERROR : _constants.COLOR.PRIMARY;
+
+    // Keyboard / viewport — informational
+    if (name.startsWith(_constants.PREFIX.SESSION_KEYBOARD)) return _constants.COLOR.SECONDARY;
+    if (name.startsWith(_constants.PREFIX.VIEWPORT_RESIZE)) return _constants.COLOR.SECONDARY;
+
+    // Layout shift
+    if (name.startsWith(_constants.PREFIX.LAYOUT_SHIFT)) return detail.value > _constants.THRESHOLD.CLS_BAD ? _constants.COLOR.ERROR : _constants.COLOR.TERTIARY;
+
+    // Cache spans — color passed explicitly by CacheCollector, this is fallback only
+    if (name.startsWith(_constants.PREFIX.CACHE + "/")) {
+      if (name.includes("/hit|memory|")) return _constants.COLOR.PRIMARY;
+      if (name.includes("/hit|disk|")) return _constants.COLOR.PRIMARY_LIGHT;
+      if (name.includes("/miss|")) return _constants.COLOR.ERROR;
+      return _constants.COLOR.TERTIARY;
+    }
+
+    // Browser network calls
+    if (name.startsWith(_constants.PREFIX.NETWORK_TIMING)) {
+      if (detail.ok === false || duration > _constants.THRESHOLD.FETCH_SLOW_MS) return _constants.COLOR.ERROR;
+      return _constants.COLOR.SECONDARY;
+    }
+
+    // Hook spans — error if LoAF burst detected during mount
+    if (name.startsWith(_constants.PREFIX.HOOK_MOUNT) || name.startsWith(_constants.PREFIX.HOOK_LAZY)) return detail.loafCount > 0 ? _constants.COLOR.ERROR : _constants.COLOR.SECONDARY;
+
+    // Interaction
+    if (name.startsWith(_constants.PREFIX.INTERACTION) || Number.isFinite(detail.responseMs)) return (detail.responseMs ?? duration) > _constants.THRESHOLD.INTERACTION_SLOW_MS ? _constants.COLOR.ERROR : _constants.COLOR.PRIMARY;
+
+    // Long press — just informational
+    if (name.startsWith(_constants.PREFIX.LONG_PRESS)) return _constants.COLOR.TERTIARY;
+    return _constants.COLOR.SECONDARY;
+  }
+}
+exports.Measure = Measure;

package/dist/native/bridge/perf/core/session.js

@@ -0,0 +1,100 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.Session = void 0;
+/**
+ * session.js
+ *
+ * Reusable open/close session pattern.
+ * A session is a named span that stays open until explicitly closed.
+ *
+ * Usage:
+ *   const session = new Session('catalyst:session/scroll', measure, TRACK.SCROLL)
+ *   session.open({ loafCount: 0 })
+ *   session.close({ loafCount: 3, janky: true })
+ *
+ * The session owns its own start mark so callers don't track mark names.
+ */
+
+class Session {
+  /**
+   * @param {string}  name    - base measure name (catalyst:session/...)
+   * @param {Measure} measure - shared Measure instance
+   * @param {string}  track   - Chrome DevTools track name
+   */
+  constructor(name, measure, track) {
+    this._name = name;
+    this._measure = measure;
+    this._track = track;
+    this._state = null; // { startMark, startTime, ...extra } | null
+  }
+  get isOpen() {
+    return this._state !== null;
+  }
+  get startTime() {
+    return this._state?.startTime ?? null;
+  }
+
+  /**
+   * Open the session.
+   * @param {object} extra - any fields to carry in state (e.g. loafCount)
+   * @param {number} [atTime] - override start time (default: performance.now())
+   */
+  open(extra = {}, atTime = null) {
+    if (this._state) return; // already open — ignore double-open
+    const startTime = atTime ?? performance.now();
+    const startMark = `${this._name}:start:${Math.round(startTime)}`;
+    performance.mark(startMark, {
+      startTime
+    });
+    this._state = {
+      startMark,
+      startTime,
+      ...extra
+    };
+  }
+
+  /**
+   * Close the session and emit the measure.
+   * @param {object} detail - fields added to properties[] in DevTools
+   * @param {number} [atTime] - override end time (default: performance.now())
+   * @param {string} [color]  - override color
+   */
+  close(detail = {}, atTime = null, color = null) {
+    if (!this._state) return;
+    const {
+      startMark,
+      startTime
+    } = this._state;
+    const endTime = atTime ?? performance.now();
+    this._state = null;
+    this._measure.emit(this._name, startMark, endTime, {
+      duration: Math.round(endTime - startTime),
+      ...detail
+    }, this._track, color);
+  }
+
+  /**
+   * Read a value stored in session state (e.g. loafCount).
+   */
+  get(key) {
+    return this._state?.[key];
+  }
+
+  /**
+   * Update a value in session state without closing.
+   */
+  set(key, value) {
+    if (this._state) this._state[key] = value;
+  }
+
+  /**
+   * Increment a numeric counter in session state.
+   */
+  increment(key) {
+    if (this._state) this._state[key] = (this._state[key] ?? 0) + 1;
+  }
+}
+exports.Session = Session;