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

package/lib/storybook/preview.js

@@ -0,0 +1,298 @@
+import { addons } from 'storybook/preview-api';
+import { FORCE_REMOUNT, STORY_CHANGED, STORY_HOT_UPDATED } from 'storybook/internal/core-events';
+import { EVENTS, PREVIEW_MESSAGE_SOURCE } from './constants.js';
+import { OWNER_ID, avalancheArmReady, ownerResult } from './setup.js';
+
+import '../extension/inspect-react.js';
+import '../extension/panel-dom.js';
+import '../extension/layout-lab.js';
+import '../extension/resolve-probes.js';
+import avalanche from '../extension/avalanche.es.js';
+import '../extension/chippy-page-bridge.js';
+
+if (ownerResult.ok) {
+  globalThis.__AVALANCHE__ = globalThis.__AVALANCHE__ || avalanche;
+}
+
+function emit(channel, event, payload) {
+  try {
+    channel.emit(event, payload);
+  } catch {
+    // Storybook channel can be briefly unavailable during preview reloads.
+  }
+}
+
+function getBridge() {
+  return globalThis.__CHIPPY?.pageBridge || null;
+}
+
+function getAvalancheApi() {
+  return globalThis.__AVALANCHE__ || avalanche || null;
+}
+
+function runAvalanche(action, command = {}) {
+  const api = getAvalancheApi();
+  const dispatcher = api?.bridge?.evalAvalanche;
+  if (typeof dispatcher !== 'function') {
+    return { ok: false, available: !!api, action, error: 'avalanche dispatcher unavailable' };
+  }
+  return dispatcher({ action, ...command }, api, api);
+}
+
+let avalancheStoryId = null;
+let avalancheAutoCache = null;
+
+function currentStoryId() {
+  return globalThis.__STORYBOOK_PREVIEW__?.selectionStore?.selection?.storyId
+    || new URLSearchParams(globalThis.location.search || '').get('id')
+    || globalThis.__STORYBOOK_STORY_STORE__?.selection?.storyId
+    || null;
+}
+
+// Storybook remounts only the render whose id matches FORCE_REMOUNT's storyId.
+// Return that id, or null when no rendered story matches.
+function remountTargetId() {
+  const storyId = currentStoryId();
+  const renders = globalThis.__STORYBOOK_PREVIEW__?.storyRenders;
+  if (!Array.isArray(renders)) return storyId;
+  return renders.some((render) => render.id === storyId) ? storyId : null;
+}
+
+// Install Avalanche with the options of a reload-with-avalanche arm. Returns
+// true when this call installed it.
+function installFromArm(arm) {
+  const api = getAvalancheApi();
+  if (!ownerResult.ok || !arm?.autoStart || typeof api?.install !== 'function' || api.status?.().installed) return false;
+  try {
+    api.install({
+      detectionMode: arm.options?.detectionMode || 'sources',
+      historySize: arm.max || 1000,
+      captureFibers: arm.options?.captureFibers !== false,
+    });
+  } catch (_) {
+    return false;
+  }
+  avalancheStoryId = currentStoryId();
+  avalancheAutoCache = null;
+  return true;
+}
+
+// The arm lookup in setup.js resolves after module evaluation; the global
+// loader below holds the first story render until it has been applied.
+const armApplied = avalancheArmReady.then(installFromArm, () => false);
+
+function ensureAvalancheInstalled({ resetForStory = false } = {}) {
+  const storyId = currentStoryId();
+  const status = runAvalanche('status');
+  const installed = status?.status?.installed || status?.result?.status?.installed;
+  if (!installed) {
+    runAvalanche('install', { options: { detectionMode: 'sources', historySize: 5000, captureFibers: true } });
+    avalancheStoryId = storyId;
+    avalancheAutoCache = null;
+    return;
+  }
+  if (resetForStory && storyId && storyId !== avalancheStoryId) {
+    runAvalanche('clear');
+    avalancheStoryId = storyId;
+    avalancheAutoCache = null;
+  }
+}
+
+function refreshAvalancheAuto() {
+  ensureAvalancheInstalled({ resetForStory: true });
+  avalancheAutoCache = {
+    storyId: currentStoryId(),
+    status: runAvalanche('status'),
+    hotSources: runAvalanche('hot-sources', { limit: 50 }),
+    commitList: runAvalanche('commit-list', { top: 1000, by: 'collateral' }),
+  };
+  return avalancheAutoCache;
+}
+
+function statePayload(extra = {}) {
+  const bridge = getBridge();
+  const mode = globalThis.__CHIPPY_OWNER__?.mode || bridge?.getState?.()?.config?.mode;
+  const avalancheAuto = mode === 'avalanche' ? refreshAvalancheAuto() : avalancheAutoCache;
+  return {
+    ok: !!bridge,
+    owner: globalThis.__CHIPPY_OWNER__ || null,
+    blocked: globalThis.__CHIPPY_BLOCKED__ || null,
+    state: bridge?.getState?.() || null,
+    avalancheStatus: avalancheAuto?.status || runAvalanche('status'),
+    avalancheAuto,
+    ...extra,
+  };
+}
+
+function activeMode() {
+  return globalThis.__CHIPPY_OWNER__?.mode || globalThis.__CHIPPY?.pageBridge?.getState?.()?.config?.mode;
+}
+
+function resetAvalancheForBoundary(reason) {
+  runAvalanche('clear');
+  avalancheStoryId = currentStoryId();
+  avalancheAutoCache = null;
+  if (activeMode() === 'avalanche') {
+    ensureAvalancheInstalled();
+    refreshAvalancheAuto();
+    publishState(channel, `avalanche-reset:${reason}`);
+  }
+}
+
+function syncActiveLifecycle() {
+  if (activeMode() === 'avalanche') ensureAvalancheInstalled({ resetForStory: true });
+}
+
+function publishState(channel, reason = 'state') {
+  syncActiveLifecycle();
+  emit(channel, EVENTS.STATE, statePayload({ reason }));
+}
+
+function executeCommand(command) {
+  const bridge = getBridge();
+  if (!bridge) return { ok: false, error: 'bridge-not-ready' };
+  switch (command?.type) {
+    case 'activate':
+      bridge.activate?.();
+      return { ok: true };
+    case 'deactivate':
+      bridge.deactivate?.();
+      return { ok: true };
+    case 'ensure-probes':
+      bridge.activate?.();
+      bridge.ensureProbes?.();
+      return { ok: true };
+    case 'clear-probes':
+      bridge.clearProbes?.();
+      return { ok: true };
+    case 'set-probe-annotation': {
+      const annotation = bridge.setProbeAnnotation?.(command.markerId, {
+        intent: command.intent ?? null,
+        comment: command.comment ?? '',
+      });
+      return annotation
+        ? { ok: true, markerId: command.markerId, annotation }
+        : { ok: false, error: `probe-not-found:${command.markerId || 'missing'}` };
+    }
+    case 'avalanche-install': {
+      globalThis.__CHIPPY_LOCK__?.heartbeat?.(OWNER_ID, { mode: 'avalanche' });
+      bridge.applyConfig?.({ mode: 'avalanche', activated: false });
+      ensureAvalancheInstalled({ resetForStory: true });
+      return runAvalanche('status');
+    }
+    case 'avalanche-stop':
+      return runAvalanche('uninstall');
+    case 'avalanche-clear':
+      ensureAvalancheInstalled();
+      return runAvalanche('clear');
+    case 'avalanche-status':
+      ensureAvalancheInstalled();
+      return runAvalanche('status');
+    case 'avalanche-export':
+      ensureAvalancheInstalled();
+      return runAvalanche('export');
+    case 'avalanche-hot-sources':
+      ensureAvalancheInstalled();
+      return runAvalanche('hot-sources', { limit: command.limit || 50 });
+    case 'avalanche-commit-list':
+      ensureAvalancheInstalled();
+      return runAvalanche('commit-list', { top: command.top || 1000, by: command.by || 'collateral' });
+    case 'avalanche-commit-peek':
+      ensureAvalancheInstalled();
+      return runAvalanche('commit-peek', {
+        commitId: command.commitId,
+        include: command.include || ['stats', 'sources', 'timing', 'metrics', 'actions'],
+        maxItems: command.maxItems || 20,
+      });
+    case 'inspect-boundary':
+      // Report the selected collateral boundary (owner/error/suspense) + its
+      // fiber-hop distance back to the backend. The click already carries the
+      // resolved descriptor; the addon acknowledges it as a first-class result
+      // so downstream consumers can act on the collateral boundary.
+      return {
+        ok: true,
+        markerId: command.markerId ?? null,
+        boundaryKind: command.boundaryKind ?? null,
+        boundary: command.boundary ?? null,
+        distance: command.distance ?? command.boundary?.distance ?? null,
+      };
+    default:
+      return { ok: false, error: `unknown-command:${command?.type || 'missing'}` };
+  }
+}
+
+const channel = addons.getChannel();
+
+function handleMode(mode) {
+  globalThis.__CHIPPY_LOCK__?.heartbeat?.(OWNER_ID, { mode });
+  const bridge = getBridge();
+  if (bridge?.applyConfig) bridge.applyConfig(mode === 'chippy' ? { mode } : { mode, activated: false });
+  if (mode !== 'chippy') {
+    bridge?.clearProbes?.();
+  }
+  if (mode === 'avalanche') ensureAvalancheInstalled({ resetForStory: true });
+  publishState(channel, 'mode');
+}
+
+function handleCommand(command) {
+  const result = executeCommand(command);
+  emit(channel, EVENTS.RESULT, { command, result, state: statePayload({ reason: 'command' }) });
+  publishState(channel, `command:${command?.type || 'unknown'}`);
+}
+
+channel.on(EVENTS.REQUEST_STATE, () => publishState(channel, 'request'));
+channel.on(EVENTS.SET_MODE, handleMode);
+channel.on(EVENTS.COMMAND, handleCommand);
+channel.on(STORY_CHANGED, () => resetAvalancheForBoundary('story-changed'));
+channel.on(FORCE_REMOUNT, () => resetAvalancheForBoundary('force-remount'));
+channel.on(STORY_HOT_UPDATED, () => resetAvalancheForBoundary('story-hot-updated'));
+window.addEventListener('message', (event) => {
+  const data = event.data || {};
+  if (data.source !== PREVIEW_MESSAGE_SOURCE) return;
+  if (data.event === EVENTS.SET_MODE) handleMode(data.payload);
+  if (data.event === EVENTS.COMMAND) handleCommand(data.payload);
+});
+
+window.addEventListener('chippy-storybook-force-remount', (event) => {
+  // Keep Storybook's manager and preview alive. FORCE_REMOUNT replaces only
+  // the rendered SUT, unlike reloading the preview iframe document. The event
+  // stays unhandled, and the helper reports the remount as failed, when no
+  // rendered story can be remounted.
+  const storyId = remountTargetId();
+  if (!storyId) return;
+  // An armed remount installs Avalanche first; the FORCE_REMOUNT listener
+  // above then clears history, so the capture starts with the remount.
+  installFromArm(event.detail?.avalanche);
+  emit(channel, FORCE_REMOUNT, { storyId });
+  event.preventDefault();
+});
+
+window.addEventListener('chippy-conn-state', () => publishState(channel, 'conn-state'));
+window.addEventListener('layout-lab:update', () => publishState(channel, 'layout-lab'));
+
+// A marker starts life after a manager-panel button was focused. Because the
+// shared drag handler prevents pointerdown's default, Storybook would otherwise
+// keep keyboard focus in the manager document and arrow navigation would never
+// reach the preview iframe.
+document.addEventListener('pointerdown', (event) => {
+  const marker = event.target?.closest?.('[data-layout-lab-marker]');
+  marker?.focus?.({ preventScroll: true });
+}, true);
+
+setInterval(() => {
+  globalThis.__CHIPPY_LOCK__?.heartbeat?.(OWNER_ID);
+  publishState(channel, 'heartbeat');
+}, 5000);
+
+publishState(channel, ownerResult.ok ? 'ready' : 'blocked');
+
+export const decorators = [
+  (Story) => Story(),
+];
+
+export const loaders = [
+  async () => {
+    await armApplied;
+    return {};
+  },
+];

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,104 @@
+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;
+  }
+}
+
+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: null,
+    staleAfterMs: STALE_AFTER_MS,
+  };
+  globalThis.__CHIPPY = globalThis.__CHIPPY || {};
+  globalThis.__CHIPPY.config = { ...(globalThis.__CHIPPY.config || {}), ...globalThis.__CHIPPY_STARTUP_CONFIG };
+}
+
+// The arm lookup must not block module evaluation: top-level await fails
+// `storybook build` under Vite's default browser targets. preview.js waits on
+// this promise in a global loader, so the first story renders after the arm is
+// known and its mount is captured.
+function applyAvalancheArm(arm) {
+  if (!arm || !ownerResult.ok) return null;
+  globalThis.__CHIPPY_STARTUP_CONFIG = { ...(globalThis.__CHIPPY_STARTUP_CONFIG || {}), avalanche: arm };
+  globalThis.__CHIPPY.config = { ...(globalThis.__CHIPPY.config || {}), avalanche: arm };
+  return arm;
+}
+
+const avalancheArmReady = ownerResult.ok ? lookupAvalancheArm().then(applyAvalancheArm) : Promise.resolve(null);
+
+export { HELPER_BASE_URL, INTEGRATION, OWNER_ID, OWNER_TYPE, STALE_AFTER_MS, avalancheArmReady, 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;
+};