@atlassian/chippy 0.0.0-stage → 0.0.1-beta.1

package/lib/storybook/probe-annotation-editor.jsx

@@ -0,0 +1,52 @@
+import React, { useEffect, useState } from 'react';
+import { PROBE_INTENTS, normalizeProbeAnnotation } from './probe-intent.js';
+
+const INTENT_LABELS = {
+  explain: 'Explain',
+  investigate: 'Investigate',
+  change: 'Change',
+};
+
+export function ProbeAnnotationEditor({ markerId, intent, comment, onAttach }) {
+  const [draft, setDraft] = useState(() => normalizeProbeAnnotation({ intent, comment }));
+
+  useEffect(() => {
+    setDraft(normalizeProbeAnnotation({ intent, comment }));
+  }, [intent, comment]);
+
+  const changeIntent = (event) => {
+    const next = normalizeProbeAnnotation({ ...draft, intent: event.target.value || null });
+    setDraft(next);
+    onAttach?.(next);
+  };
+
+  const commitComment = (event) => {
+    if (event.key !== 'Enter' || event.shiftKey || event.nativeEvent?.isComposing) return;
+    event.preventDefault();
+    event.stopPropagation();
+    onAttach?.(normalizeProbeAnnotation({ ...draft, comment: event.currentTarget.value }));
+  };
+
+  return (
+    <div style={{ display: 'grid', gap: 6, marginTop: 8 }}>
+      <select
+        aria-label={`P${markerId} intent`}
+        value={draft.intent || ''}
+        onChange={changeIntent}
+        style={{ width: '100%', padding: '5px 7px', borderRadius: 6 }}
+      >
+        <option value="">Choose intent</option>
+        {PROBE_INTENTS.map((value) => <option key={value} value={value}>{INTENT_LABELS[value]}</option>)}
+      </select>
+      <textarea
+        aria-label={`P${markerId} comment`}
+        maxLength={2000}
+        placeholder="What should Chippy do with this probe?"
+        value={draft.comment}
+        onChange={(event) => setDraft((current) => ({ ...current, comment: event.target.value }))}
+        onKeyDown={commitComment}
+        style={{ boxSizing: 'border-box', width: '100%', minHeight: 58, resize: 'vertical', padding: '6px 7px', borderRadius: 6 }}
+      />
+    </div>
+  );
+}

package/lib/storybook/probe-intent.js

@@ -0,0 +1,23 @@
+// src/layout-lab/probe-intent.ts
+var PROBE_INTENTS = ["explain", "investigate", "change"];
+var MAX_COMMENT_LENGTH = 2e3;
+var INTENT_SET = new Set(PROBE_INTENTS);
+function normalizeProbeAnnotation(value) {
+  const input = value && typeof value === "object" ? value : {};
+  const rawIntent = typeof input.intent === "string" ? input.intent.trim().toLowerCase() : "";
+  return {
+    intent: INTENT_SET.has(rawIntent) ? rawIntent : null,
+    comment: typeof input.comment === "string" ? input.comment.slice(0, MAX_COMMENT_LENGTH) : ""
+  };
+}
+function updateProbeAnnotation(current, patch) {
+  return normalizeProbeAnnotation({
+    intent: patch.intent === void 0 ? current.intent : patch.intent,
+    comment: patch.comment === void 0 ? current.comment : patch.comment
+  });
+}
+export {
+  PROBE_INTENTS,
+  normalizeProbeAnnotation,
+  updateProbeAnnotation
+};

package/lib/storybook/setup.js

@@ -0,0 +1,93 @@
+const OWNER_ID = 'storybook-addon';
+const OWNER_TYPE = 'storybook-addon';
+const HELPER_BASE_URL = 'http://127.0.0.1:7823';
+const STALE_AFTER_MS = 15_000;
+const INTEGRATION = Object.freeze({
+  kind: 'storybook',
+  who: 'Chippy Storybook addon',
+  source: '.storybook/chippy-addon/setup.js',
+  reinjectsOnReload: true,
+  reloadAction: 'Chippy remounts the current SUT through Storybook FORCE_REMOUNT without reloading the preview iframe.',
+});
+
+async function lookupAvalancheArm() {
+  try {
+    const url = `${HELPER_BASE_URL.replace(/\/+$/, '')}/__chippy/api/avalanche-arm?origin=${encodeURIComponent(location.href)}`;
+    const response = await fetch(url, { signal: AbortSignal.timeout(1000) });
+    if (!response.ok) return null;
+    const data = await response.json();
+    return data && data.armed && data.config ? data.config : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+const avalancheArm = await lookupAvalancheArm();
+
+function acquireOwner(mode = 'chippy') {
+  const now = Date.now();
+  const current = globalThis.__CHIPPY_OWNER__ || null;
+  if (
+    !current ||
+    current.ownerId === OWNER_ID ||
+    (current.heartbeatAt && now - current.heartbeatAt > STALE_AFTER_MS)
+  ) {
+    const owner = {
+      ...(current?.ownerId === OWNER_ID ? current : {}),
+      ownerId: OWNER_ID,
+      ownerType: OWNER_TYPE,
+      transport: 'storybook-static',
+      ui: 'storybook-panel',
+      mode,
+      helperBaseUrl: HELPER_BASE_URL,
+      integration: INTEGRATION,
+      staleAfterMs: STALE_AFTER_MS,
+      startedAt: current?.ownerId === OWNER_ID ? current.startedAt || now : now,
+      heartbeatAt: now,
+    };
+    globalThis.__CHIPPY_OWNER__ = owner;
+    globalThis.__CHIPPY_LOCK__ = globalThis.__CHIPPY_LOCK__ || {};
+    globalThis.__CHIPPY_LOCK__.get = () => globalThis.__CHIPPY_OWNER__ || null;
+    globalThis.__CHIPPY_LOCK__.heartbeat = (ownerId, patch = {}) => {
+      if (globalThis.__CHIPPY_OWNER__?.ownerId !== ownerId) {
+        return { ok: false, reason: 'not-owner', owner: globalThis.__CHIPPY_OWNER__ || null };
+      }
+      globalThis.__CHIPPY_OWNER__ = { ...globalThis.__CHIPPY_OWNER__, ...patch, heartbeatAt: Date.now() };
+      return { ok: true, owner: globalThis.__CHIPPY_OWNER__ };
+    };
+    globalThis.__CHIPPY_LOCK__.release = (ownerId) => {
+      if (globalThis.__CHIPPY_OWNER__?.ownerId !== ownerId) {
+        return { ok: false, reason: 'not-owner', owner: globalThis.__CHIPPY_OWNER__ || null };
+      }
+      const owner = globalThis.__CHIPPY_OWNER__;
+      delete globalThis.__CHIPPY_OWNER__;
+      return { ok: true, owner };
+    };
+    return { ok: true, owner, reused: current?.ownerId === OWNER_ID, replacedStale: !!(current && current.ownerId !== OWNER_ID) };
+  }
+  return { ok: false, reason: 'owned-by-other-chippy', owner: current };
+}
+
+const ownerResult = acquireOwner('chippy');
+globalThis.__CHIPPY_OWNER_RESULT__ = ownerResult;
+if (!ownerResult.ok) {
+  globalThis.__CHIPPY_BLOCKED__ = ownerResult;
+} else {
+  globalThis.__CHIPPY_STARTUP_CONFIG = {
+    ...(globalThis.__CHIPPY_STARTUP_CONFIG || {}),
+    helperBaseUrl: HELPER_BASE_URL,
+    activated: false,
+    ui: 'storybook-panel',
+    ownerType: OWNER_TYPE,
+    ownerId: OWNER_ID,
+    transport: 'storybook-static',
+    mode: 'chippy',
+    integration: INTEGRATION,
+    avalanche: avalancheArm,
+    staleAfterMs: STALE_AFTER_MS,
+  };
+  globalThis.__CHIPPY = globalThis.__CHIPPY || {};
+  globalThis.__CHIPPY.config = { ...(globalThis.__CHIPPY.config || {}), ...globalThis.__CHIPPY_STARTUP_CONFIG };
+}
+
+export { HELPER_BASE_URL, INTEGRATION, OWNER_ID, OWNER_TYPE, STALE_AFTER_MS, ownerResult };

package/lib/types/avalanche/commit-metrics-adapter.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Commit metrics adapter: an optional per-commit counter source that sits next
+ * to the DevTools fiber walk.
+ *
+ * The detector always captures commits through the DevTools hook. Some hosts
+ * also run an instrumented react-dom that exposes render counters and calls a
+ * commit callback of its own. An adapter wraps one such host surface: it seeds
+ * and protects the surface, snapshots its counters, turns two snapshots into a
+ * per-commit delta plus a restart count, and wires the host's commit callback
+ * to the detector. Without an adapter the detector runs in `devtools` mode and
+ * reports restarts as unavailable.
+ *
+ * One adapter is active at a time. Product adapters live in `src/plugins/`.
+ */
+import type { Fiber } from './internals.js';
+export type CommitMetricsRoot = {
+    current: Fiber;
+    memoizedUpdaters?: Set<Fiber>;
+};
+/** Raw counters read from the host surface at one point in time. */
+export type CommitMetricsSnapshot = Record<string, unknown>;
+/** Counter deltas for one commit, keyed by counter name. */
+export type CommitMetricsDelta = {
+    [counter: string]: number | undefined;
+};
+export type CommitMetricsMeasurement = {
+    delta: CommitMetricsDelta;
+    /** Render passes React performed but did not commit. Never negative. */
+    restarts: number;
+};
+export interface CommitMetricsAdapter {
+    /** Stable id; the detector reports `integrationMode: 'adapter:<id>'`. */
+    readonly id: string;
+    /**
+     * Stack frame names the host surface adds to every render. Hook ancestry
+     * hides them like other renderer internals.
+     */
+    readonly frameFilters?: readonly string[];
+    /**
+     * Setup that must run before React evaluates, such as installing an accessor
+     * that survives host cleanup. Called by the extension's early bootstrap
+     * through `__AVALANCHE__.runPrePageHooks(config)`.
+     */
+    prePage?(config: unknown): void;
+    /** Seed the host surface before a detector installs, unless the host owns it. */
+    prepare?(): void;
+    /** Whether the host surface is present right now. */
+    isAvailable(): boolean;
+    snapshot(): CommitMetricsSnapshot | null;
+    measure(before: CommitMetricsSnapshot, after: CommitMetricsSnapshot, committedComponents: number, commitId: number): CommitMetricsMeasurement;
+    /**
+     * Route the host's commit callback to `onCommit`. Returns false when the
+     * surface is absent. A callback is proof that the host surface is live.
+     */
+    attach(onCommit: (root: CommitMetricsRoot) => void): boolean;
+    /** True while the callback from attach() is still wired into the live surface. */
+    isAttached(): boolean;
+    /** Re-seed and re-wire after the host wiped or replaced its surface. */
+    reattach(): void;
+    /** Remove the callback from attach(), only if it is still ours. */
+    detach(): void;
+}
+/**
+ * Make `adapter` the active commit metrics adapter for detectors installed
+ * afterwards. Replaces any earlier adapter. Returns an unregister function.
+ */
+export declare function registerCommitMetricsAdapter(adapter: CommitMetricsAdapter): () => void;
+export declare function getCommitMetricsAdapter(): CommitMetricsAdapter | null;
+/**
+ * Run the active adapter's pre-page hook. Returns the adapter id when a hook
+ * ran, or null. A failing hook is swallowed: the detector falls back to
+ * DevTools capture.
+ */
+export declare function runPrePageHooks(config?: unknown): string | null;
+export type IntegrationMode = `adapter:${string}` | 'devtools' | 'none';
+export declare function adapterIdFromMode(mode: IntegrationMode | string | null | undefined): string | null;

package/lib/types/avalanche/commit-stats-indices.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Named constants for CommitStats tuple indices.
+ *
+ * CommitStats is a fixed 10-position tuple per commit. This module provides
+ * human-readable names for each index to replace magic numbers in code.
+ *
+ * Tuple structure:
+ * [0] collateral        — total updates caused by this source (collateral damage)
+ * [1] sources           — number of distinct sources that fired in this commit
+ * [2] restarts          — render count from ATL render-counter delta (or 0 if not available)
+ * [3] performedWork     — components with PerformedWork flag set
+ * [4] effects           — effect count
+ * [5] memos             — memo count
+ * [6] callbacks         — callback count
+ * [7] contextUpdates    — context update count
+ * [8] unmountedComponents — number of unmounted components
+ * [9] unmountedSubtrees — number of unmounted subtrees
+ *
+ * This positional layout is shared by the detector, serializer, bridge, and
+ * offline readers. Changing an index is a wire-format change even though the
+ * tuple remains valid TypeScript, so keep the names and length together.
+ */
+export declare const CS_COLLATERAL = 0;
+export declare const CS_SOURCES = 1;
+export declare const CS_RESTARTS = 2;
+export declare const CS_PERFORMED_WORK = 3;
+export declare const CS_EFFECTS = 4;
+export declare const CS_MEMOS = 5;
+export declare const CS_CALLBACKS = 6;
+export declare const CS_CONTEXT_UPDATES = 7;
+export declare const CS_UNMOUNTED_COMPONENTS = 8;
+export declare const CS_UNMOUNTED_SUBTREES = 9;
+/**
+ * Total length of the CommitStats tuple.
+ * Used for validation and bounds checking.
+ */
+export declare const COMMIT_STATS_LENGTH = 10;
+/**
+ * Array of all commitStats indices for iteration/validation.
+ */
+export declare const ALL_COMMIT_STATS_INDICES: readonly [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];

package/lib/types/avalanche/commit-surface-ownership.d.ts

@@ -0,0 +1,9 @@
+export interface CommitRoot {
+    current: object;
+}
+export declare function createCommitSurfaceOwnership<T>(): {
+    readonly adapterObserved: boolean;
+    recordDevtools(root: CommitRoot, capture: T): void;
+    observeAdapter(root: CommitRoot): T | null;
+    reset(): void;
+};

package/lib/types/avalanche/detector.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Headless Profiler - React commit profiler (headless / no UI).
+ *
+ * This file intentionally keeps the commit traversal (`recordTree`) monolithic.
+ * It runs on every React commit, and even small function-call overhead inside the
+ * fiber-walk loops shows up in perf. We refactor everything *around* it.
+ *
+ * Detection Levels:
+ * - Level 1 (STATS): Only commitStats - <1% overhead (~0.8ms avg)
+ * - Level 2 (SOURCES): + source tracking - ~1-2% overhead (~1.3ms avg)
+ * - Level 3 (AMPLIFIERS/FULL): + amplifier detection - ~2-3% overhead (~2.4ms avg)
+ *
+ * Peer FAQ
+ * - Why is `recordTree()` huge? Performance: it's on the hot path (every commit).
+ * - Why per-hook actionability? React can leave alternate hook memoizedState
+ *   undefined (Suspense/Offscreen/concurrent artifacts) causing false positives.
+ * - Why WeakMaps everywhere? To auto-GC tracked values/fibers without leaks.
+ * - Why so few null checks? Debug tool: fail fast and loud on misuse/internals drift.
+ * - Production? Use LEVEL1_STATS or LEVEL2_SOURCES for minimal overhead.
+ */
+import { type DetectorOptions, type Report, type ReportOptions, type SortBy } from './reporter.js';
+import { type HookCallEvent, type StackFrame } from '../debug-render/core.js';
+import { type IntegrationMode } from './commit-metrics-adapter.js';
+/**
+ * Installable detector.
+ */
+export declare function createAvalancheDetector(options?: DetectorOptions): {
+    /**
+     * Start profiling React commits.
+     *
+     * Integration model is OBSERVED at runtime, not declared at install time.
+     *
+     *   'devtools'     — DevTools `onCommitFiberRoot` is the canonical entry
+     *                    point. We define the hook if absent, augment (chain)
+     *                    if present. On every commit we capture the fiber tree.
+     *
+     *   'adapter:<id>' — Promoted from 'devtools' the first time the commit
+     *                    metrics adapter's host callback actually fires for a
+     *                    real commit. From then on the adapter is the
+     *                    authoritative processor and the DevTools surface is
+     *                    chained-observer-only. The adapter is preferred when
+     *                    alive because it carries render-counter deltas
+     *                    (restart math, metricsByCommit).
+     *
+     *   'none'         — Only when no DevTools hook surface can be created and
+     *                    no adapter surface is reachable. Practically never
+     *                    hit, since the content-script ships a
+     *                    devtools-hook-shim before react-dom.
+     *
+     * Double-invocation safety:
+     *   Once an adapter callback has fired, DevTools remains chained for
+     *   existing tooling but does not capture commits; the adapter alone calls
+     *   `handleCommit`. Without a live adapter, DevTools is the capture
+     *   surface. This avoids duplicate capture without relying on per-root
+     *   timing heuristics.
+     *
+     * Side effects:
+     *   - Defines `__REACT_DEVTOOLS_GLOBAL_HOOK__` if it does not already exist
+     *     (minimal contract: `onCommitFiberRoot` only). React reads the hook at
+     *     module-eval time; the content-script shim handles ordering.
+     *   - Asks the adapter (when one is registered) to route its host commit
+     *     callback here, *if and when* the host calls it.
+     *
+     * Safe to call multiple times (idempotent: chains skipped when our wrappers
+     * are already in place).
+     */
+    install(): void;
+    /**
+     * Stop profiling React commits. Does not clear accumulated state.
+     * Call reset() to clear state.
+     *
+     * Restores the DevTools hook to its prior state:
+     *   - hook was created by us → delete the hook entirely
+     *   - hook had a prior onCommitFiberRoot → restore it
+     *   - hook had no handler → delete the property
+     *
+     * Asks the adapter to remove its host callback only if it is still ours
+     * (don't stomp a concurrent installer).
+     */
+    uninstall(): void;
+    /**
+     * Clear all accumulated profiling state. Useful for starting fresh measurements.
+     * Does not uninstall the profiler - call uninstall() separately if needed.
+     */
+    reset(): void;
+    /**
+     * Generate a report of top update sources and thrashing components.
+     * @param topN - Number of top sources to include (default: 10)
+     * @param sortBy - Sort thrashers by 'effect', 'callback', 'memo', or 'total' (default: 'effect')
+     * @param options - Report filtering options (e.g., minCollateral to hide low-impact sources)
+     * @returns Report containing sources, blast radius, and optional thrashing data
+     */
+    report(topN?: number, sortBy?: SortBy, reportOptions?: ReportOptions): Report;
+    /**
+     * Raw passive hook events captured for a component (debug surface).
+     */
+    _debugRawHookEvents(componentName: string): {
+        ok: boolean;
+        componentName: string;
+        status: import("../debug-render/core").CaptureEngineStatus;
+        components: string[];
+        events: HookCallEvent[];
+    };
+    _debugInjectHookEventsForTest(componentName: string, events: HookCallEvent[]): void;
+    _debugSetSourceForTest(sourceId: string, source: unknown): void;
+    debugHook(sourceId: string, hookIndex: number, windowSize?: number): {
+        ok: boolean;
+        error: string;
+        sourceId: string;
+        requestedSourceId?: undefined;
+        componentName?: undefined;
+        resolvedComponentName?: undefined;
+        hookIndex?: undefined;
+        eventIndex?: undefined;
+        sourceHookIndices?: undefined;
+        eventCount?: undefined;
+        status?: undefined;
+        caveat?: undefined;
+        primitive?: undefined;
+        parents?: undefined;
+        neighborhood?: undefined;
+    } | {
+        ok: boolean;
+        error: string;
+        sourceId: string;
+        requestedSourceId: string;
+        componentName: string;
+        resolvedComponentName: string;
+        hookIndex: number;
+        eventIndex: number;
+        sourceHookIndices: number[];
+        eventCount: number;
+        status: import("../debug-render/core").CaptureEngineStatus;
+        caveat: string;
+        primitive?: undefined;
+        parents?: undefined;
+        neighborhood?: undefined;
+    } | {
+        ok: boolean;
+        sourceId: string;
+        requestedSourceId: string;
+        componentName: string;
+        resolvedComponentName: string;
+        hookIndex: number;
+        eventIndex: number;
+        sourceHookIndices: number[];
+        primitive: string;
+        parents: StackFrame[];
+        neighborhood: {
+            hookIndex: number;
+            eventIndex: number;
+            primitive: string;
+            parents: StackFrame[];
+        }[];
+        eventCount: number;
+        status: import("../debug-render/core").CaptureEngineStatus;
+        caveat: string;
+        error?: undefined;
+    };
+    /**
+     * Returns which commit-hook integration model is currently observed.
+     *   'devtools'     — DevTools hook is the active processor (no proven adapter callbacks).
+     *   'adapter:<id>' — The adapter's host surface has fired; it owns the math now.
+     *   'none'         — Detector not installed.
+     */
+    getIntegrationMode(): IntegrationMode;
+    /** Id of the commit metrics adapter resolved on install, or null. */
+    getMetricsAdapterId(): string | null;
+};
+/**
+ * Detection level constants - use these for clarity about the hierarchy.
+ * Higher levels include all features from lower levels.
+ */
+export declare const DETECTION_LEVEL: {
+    /** Level 1: Only commitStats (performedWork for restarts) - minimal overhead */
+    readonly LEVEL1_STATS: "stats";
+    /** Level 2: Stats + source tracking (which components caused updates) */
+    readonly LEVEL2_SOURCES: "sources";
+    /** Level 3a: Sources + aggregate amplifier counts only (meta.amplifiersMetrics) */
+    readonly LEVEL3_AMPLIFIER_METRICS: "amplifierMetrics";
+    /** Level 3b: Sources + full amplifier arrays (report.amplifiers, report.amplifierSources) */
+    readonly LEVEL3_AMPLIFIERS: "amplifiers";
+};

package/lib/types/avalanche/interaction-capture.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Records user-side interaction anchors while Avalanche records commits.
+ * Capture is intentionally DOM-event based: the detector owns fiber/commit
+ * evidence, while this module owns the only signal that a human interaction
+ * preceded it. `linkRecent` joins the two later using performance timestamps;
+ * it is evidence of temporal proximity, not proof that the event caused every
+ * render in the commit.
+ */
+import type { CommitInteractionAction, InteractionAction, InteractionCaptureLevel } from './reporter.js';
+export interface InteractionCaptureOptions {
+    interactionCapture?: InteractionCaptureLevel;
+    interactionEvents?: string[];
+    interactionWindowMs?: number;
+}
+export interface InteractionCaptureState {
+    actions: InteractionAction[];
+    byCommit: Record<number, CommitInteractionAction[]>;
+}
+export declare function createInteractionCapture(options?: InteractionCaptureOptions): {
+    state: InteractionCaptureState;
+    install(): void;
+    uninstall(): void;
+    reset(): void;
+    linkRecent(commitId: number, commitTime: number): void;
+};