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

package/lib/types/chippy-bridge/react-renderer.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Shared React DevTools renderer discovery.
+ *
+ * React-DOM registers a renderer object into
+ * `window.__REACT_DEVTOOLS_GLOBAL_HOOK__.renderers` at injection time (only when
+ * the hook exists before react-dom evaluates). That renderer object is the single
+ * entry point for several Chippy capabilities:
+ *
+ *   - `currentDispatcherRef` → debug-render hook replay (see debug-render/core.ts)
+ *   - `scheduleUpdate`        → fiber-schedule-update nudge (see fiber-schedule-update.ts)
+ *
+ * Both used to walk `hook.renderers` themselves. This module is the one place that
+ * knows how to enumerate renderers, so capabilities select the field they need
+ * without duplicating the iteration (and its Map/entries quirks).
+ */
+export type ReactRenderer = {
+    /** `{ current }` on React <=18; `ReactSharedInternals` (`H`) on React 19. */
+    currentDispatcherRef?: Record<string, unknown> | null;
+    scheduleUpdate?: (fiber: unknown) => void;
+    version?: string;
+    rendererPackageName?: string;
+    [key: string]: unknown;
+};
+export type DevtoolsHookLike = {
+    renderers?: Map<number, ReactRenderer> | {
+        entries(): IterableIterator<[number, ReactRenderer]>;
+    };
+};
+/**
+ * Enumerate every registered React renderer. Returns [] when the DevTools hook
+ * is absent or empty (production builds without the shim, or hook installed too
+ * late for react-dom to register).
+ */
+export declare function getReactRenderers(scope?: typeof globalThis): ReactRenderer[];
+/**
+ * The writable property that holds React's active hooks dispatcher.
+ *
+ * React <=18 injects `ReactCurrentDispatcher`, whose dispatcher lives at
+ * `current`. React 19 injects `ReactSharedInternals`, whose dispatcher lives
+ * at `H` (`current` does not exist there). React DevTools makes the same
+ * distinction in its own `getDispatcherRef`.
+ */
+export type DispatcherSlot = {
+    owner: Record<string, unknown>;
+    key: 'current' | 'H';
+};
+export declare function dispatcherSlotOf(injected: unknown): DispatcherSlot | null;
+/**
+ * First renderer that exposes a usable dispatcher slot. Used by debug-render
+ * when it must trap writes to the exact property React assigns.
+ */
+export declare function getDispatcherSlot(scope?: typeof globalThis): DispatcherSlot | null;
+/**
+ * Normalize a slot to a `{ current }` ref. A legacy ref is returned as-is; a
+ * React 19 internals object gets one stable accessor view that reads and
+ * writes `H`.
+ */
+export declare function dispatcherRefOf(slot: DispatcherSlot): {
+    current: unknown;
+};
+/**
+ * First renderer's hooks dispatcher as a `{ current }` ref, across React
+ * versions. Used by debug replay to swap in its stub dispatcher.
+ */
+export declare function getDispatcherRef(scope?: typeof globalThis): {
+    current: unknown;
+} | null;
+/**
+ * First renderer that exposes a callable `scheduleUpdate`. This is the exact
+ * function React DevTools uses to force a re-render on a fiber. It is only
+ * present on development React builds. Returns null on production builds (or
+ * when the DevTools-hook shim was missing at page boot).
+ */
+export declare function getScheduleUpdate(scope?: typeof globalThis): ((fiber: unknown) => void) | null;

package/lib/types/chippy-bridge/recorded-source.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Correct React <=18 `_debugSource` lines through the served module.
+ *
+ * The JSX transform records `lineNumber`/`columnNumber` from the code it
+ * receives. When an earlier transform adds lines first, the recorded position
+ * points into that intermediate code rather than the authored file. For
+ * example, `@vitejs/plugin-react` adds a Fast Refresh header before esbuild
+ * compiles JSX, which shifts every recorded line in the module.
+ *
+ * The served module still contains the recorded literal, and its source map
+ * maps that literal to the JSX element in the authored file. This module finds
+ * the literal and the URLs that may serve the recorded file; the call-site
+ * resolver in fiber-source.ts fetches the module and applies the map.
+ */
+export type RecordedSource = {
+    fileName: string;
+    lineNumber: number;
+    columnNumber: number | null;
+};
+export type ServedPosition = {
+    line: number;
+    column: number;
+};
+export type PageModules = {
+    origin: string;
+    /** Script and module URLs the page loaded, oldest first. */
+    resourceUrls: readonly string[];
+    /** Vite serves any allowed file from `/@fs/<absolute path>`. */
+    vite: boolean;
+};
+/**
+ * The position of the single debug literal for `source` in served code, or
+ * null when the literal is missing or appears more than once.
+ */
+export declare function recordedLiteralPosition(code: string, source: RecordedSource): ServedPosition | null;
+/**
+ * Same-origin URLs that may serve `fileName`, best match first: loaded modules
+ * whose path ends the recorded file path, newest first, then Vite's `/@fs`
+ * URL when the page runs on Vite.
+ */
+export declare function servedModuleUrls(fileName: string, page: PageModules): string[];
+/** Candidate module URLs for a recorded file on the current page. */
+export declare function pageModuleUrls(fileName: string): string[];
+export declare function baseName(path: string): string;

package/lib/types/chippy-bridge/source-map.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Small, dependency-free Source Map v3 reader.
+ *
+ * Chippy only needs the generated-position lookup used by React 19's
+ * `_debugStack` source path, so it deliberately omits names and source contents.
+ */
+type Segment = {
+    generatedColumn: number;
+    sourceIndex: number | null;
+    originalLine: number | null;
+    originalColumn: number | null;
+};
+export type SourceMap = {
+    sources: readonly string[];
+    lines: readonly (readonly Segment[])[];
+    offset: {
+        line: number;
+        column: number;
+    };
+};
+export type OriginalPosition = {
+    source: string;
+    line: number;
+    column: number;
+};
+export declare function parseSourceMap(text: string): SourceMap[];
+export declare function originalPositionFor(maps: readonly SourceMap[], line: number, column: number): OriginalPosition | null;
+export declare function sourceMappingUrlOf(code: string): string | null;
+export declare function inlineSourceMapOf(url: string): string | null;
+export {};

package/lib/types/debug-render/core.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Debug-render module.
+ *
+ * Single responsibility: capture per-render hook events for components, and
+ * expose them losslessly to higher layers (the detector projects them).
+ *
+ * Capture strategy: dispatcher interception via the DevTools global hook.
+ *
+ * React 18 routes every hook call through `ReactCurrentDispatcher.current`,
+ * which is swapped per render phase by react-dom. We do NOT patch
+ * `React.useX` (those are facades to the dispatcher) and we do NOT import
+ * React here — this module must not pin a React identity.
+ *
+ * We discover the *page's* `ReactCurrentDispatcher` ref via the React DevTools
+ * global hook contract:
+ *
+ *   __REACT_DEVTOOLS_GLOBAL_HOOK__.renderers.get(id).currentDispatcherRef
+ *
+ * That ref is page-React-owned and lives where react-dom actually writes.
+ * Bootstrap requirement: a DevTools hook shim must already be installed when
+ * react-dom evaluates so it calls `hook.inject(internals)`. That bootstrap is
+ * Chippy's responsibility (handled by the extension content-script / helper
+ * inject path); this module only consumes the result.
+ *
+ * Capture is intentionally lossless: raw stack + parsed frames are stored.
+ * Projection (component name, custom-hook path, loc) is done downstream so
+ * the original evidence can be re-projected without re-capturing.
+ */
+export type StackFrame = {
+    name: string;
+    loc: string;
+};
+export type HookCallEvent = {
+    primitive: string;
+    stack: string;
+    frames: StackFrame[];
+    componentName: string;
+    args: unknown[];
+};
+export type CaptureEngineStatus = {
+    ok: boolean;
+    installed: boolean;
+    hasDevtoolsHook: boolean;
+    rendererCount: number;
+    hasDispatcherRef: boolean;
+    totalCapturedComponents: number;
+    totalCapturedEvents: number;
+    reason?: string;
+    hint?: string;
+};
+export type DebugRenderModule = {
+    install(): {
+        ok: boolean;
+        reason?: string;
+    };
+    uninstall(): void;
+    reset(): void;
+    isInstalled(): boolean;
+    dispatcherRef(): DispatcherRef | null;
+    rawEvents(componentName: string): HookCallEvent[];
+    allComponents(): string[];
+    status(): CaptureEngineStatus;
+    recordEventForTest?(event: HookCallEvent): void;
+};
+export declare function parseStackFrames(stack: string): StackFrame[];
+type DispatcherRef = {
+    current: unknown;
+};
+/**
+ * True for a hook frame, including qualified names. React 19's CommonJS build
+ * defines `exports.useState = function (...) {}`, which V8 names
+ * `exports.useState`; bundlers can produce similar `ns.useX` names.
+ */
+export declare function isHookFrameName(name: string): boolean;
+export declare function createDebugRender(options?: {
+    maxEventsPerComponent?: number;
+}): DebugRenderModule;
+export {};

package/lib/types/layout-lab/fiber-boundaries.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Fiber-native declarative boundaries.
+ *
+ * Error boundaries and Suspense are React primitives — they exist on every
+ * React page. This module detects them generically from the fiber tree,
+ * independent of any product. App-specific enrichment (ownership markers,
+ * error-boundary props) is layered on top by context providers registered
+ * with ./marker-context.
+ *
+ * "Distance" is the signal: how many fiber hops above the probed fiber the
+ * boundary sits. Together, the nearest error + suspense boundaries define the
+ * collateral scope around a probe.
+ */
+import { type Fiber } from './fiber-walk.js';
+export type ErrorBoundaryInfo = {
+    componentName: string;
+    /** How the boundary was identified — lifecycle proof vs. name heuristic. */
+    detectedBy: 'lifecycle' | 'name';
+};
+export type SuspenseBoundaryInfo = {
+    componentName: string;
+};
+/** A boundary plus its fiber-hop distance from the probed fiber. */
+export type BoundaryRef<T> = T & {
+    distance: number;
+};
+export type FiberBoundaries = {
+    error: BoundaryRef<ErrorBoundaryInfo> | null;
+    suspense: BoundaryRef<SuspenseBoundaryInfo> | null;
+};
+export declare const MAX_BOUNDARY_FIBERS = 400;
+/**
+ * Generic error-boundary detection. An error boundary is a class component that
+ * implements getDerivedStateFromError and/or componentDidCatch. That lifecycle
+ * check is the React-native definition and works on any React app. As a
+ * fallback for minified/edge builds where the constructor is not introspectable,
+ * a display name ending in "ErrorBoundary" is accepted.
+ */
+export declare function describeErrorBoundary(fiber: Fiber): ErrorBoundaryInfo | null;
+/**
+ * Generic Suspense detection. React marks a Suspense fiber with tag 13; we also
+ * accept a display name resolving to Suspense/SuspenseList for builds where the
+ * tag is unavailable.
+ */
+export declare function describeSuspenseBoundary(fiber: Fiber): SuspenseBoundaryInfo | null;
+/**
+ * Walk an ordered ancestry list and return the nearest error + suspense
+ * boundaries with their distances. The list is expected to be ordered from the
+ * probed fiber outward, so the index is the fiber-hop distance.
+ */
+export declare function collectFiberBoundaries(fibers: Fiber[]): FiberBoundaries;

package/lib/types/layout-lab/fiber-walk.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Pure fiber-walk helpers extracted from layout-lab.js.
+ * No DOM writes, no side effects — read-only introspection of React fiber trees.
+ */
+/**
+ * Minimal duck-typed Fiber shape.
+ * Only fields used by these helpers are typed; rest may exist but are not read.
+ */
+export type Fiber = {
+    type?: unknown;
+    elementType?: unknown;
+    key?: string | null;
+    memoizedState?: unknown;
+    memoizedProps?: Record<string, unknown> | null;
+    stateNode?: Element | null;
+    return?: Fiber | null;
+    child?: Fiber | null;
+    sibling?: Fiber | null;
+    _debugOwner?: Fiber | null;
+    _debugSource?: SourceLocation | null;
+    _debugStack?: unknown;
+};
+export type SourceLocation = {
+    fileName?: string | null;
+    lineNumber?: number | null;
+    columnNumber?: number | null;
+};
+export type DescribedSource = {
+    fileName: string | null;
+    lineNumber: number | null;
+    columnNumber: number | null;
+};
+export type HookSummary = {
+    hookCount: number;
+    hookCountTruncated: boolean;
+    hookCountMax: number;
+};
+export type OwnerEntry = {
+    name: string | null;
+    key: string | null;
+    props: string[];
+} & HookSummary & {
+    source: DescribedSource | null;
+};
+export type FiberTarget = {
+    domTag: string | null;
+    domText: string;
+    fiberType: string | null;
+    source: DescribedSource | null;
+};
+export type ComponentDescription = {
+    name: string | null;
+    key: string | null;
+    props: Record<string, unknown>;
+    source: DescribedSource | null;
+    stateNode: string | null;
+    owners: OwnerEntry[];
+    parents: OwnerEntry[];
+} & HookSummary;
+/**
+ * Find the React fiber key in a DOM node's own properties.
+ * Returns the property name (e.g. '__reactFiber$abc123') or null.
+ */
+export declare function getFiberKey(node: Node | Element | null | undefined): string | null;
+/**
+ * Get the React fiber attached to a DOM node, or null if not a React host node.
+ */
+export declare function getFiber(node: Node | Element | null | undefined): Fiber | null;
+/**
+ * Extract display name from a React type (class, function, or string).
+ * Returns displayName > name > null for functions; 'string' for primitives.
+ */
+export declare function getDisplayName(type: unknown): string | null;
+/**
+ * True if fiber is a user-defined component (not a DOM string, not a hook-internal wrapper).
+ */
+export declare function isUserComponent(fiber: Fiber | null | undefined): boolean;
+/**
+ * Walk DOM parents to find the nearest fiber-attached element.
+ */
+export declare function getNearestFiber(domNode: Node | Element | null | undefined): Fiber | null;
+/**
+ * Walk DOM parents, then walk fiber return chain, to find the nearest user component.
+ */
+export declare function getNearestComponent(domNode: Node | Element | null | undefined): Fiber | null;
+/**
+ * Count hooks in fiber.memoizedState linked list; detect cycle.
+ */
+export declare function getHookSummary(fiber: Fiber | null | undefined): HookSummary;
+/**
+ * Walk fiber._debugOwner chain; collect all user components with metadata.
+ * Returns empty array if fiber or owner chain is null.
+ */
+export declare function getOwnerChain(fiber: Fiber | null | undefined): OwnerEntry[];
+/**
+ * Walk fiber._debugOwner chain; return raw fiber nodes (for navigation).
+ */
+export declare function getOwnerFibers(fiber: Fiber | null | undefined): Fiber[];
+/**
+ * Recursively walk fiber.child/sibling to find the first host DOM element rendered by this subtree.
+ */
+export declare function getFiberDomNode(fiber: Fiber | null | undefined): Element | null;
+/**
+ * Walk fiber.return chain; collect all user component parents with metadata.
+ */
+export declare function getReturnComponentChain(fiber: Fiber | null | undefined): OwnerEntry[];
+/**
+ * Walk fiber.return chain; return raw fiber nodes (for navigation).
+ */
+export declare function getReturnComponentFibers(fiber: Fiber | null | undefined): Fiber[];
+/**
+ * Normalize source location object to canonical shape.
+ */
+export declare function describeSource(source: SourceLocation | null | undefined): DescribedSource | null;
+/**
+ * Read a fiber source across React versions.
+ *
+ * React <=18 exposes `_debugSource`. React 19 exposes `_debugStack`; its first
+ * non-vendor frame is returned synchronously and may later be upgraded from the
+ * bundle position to the original source position by `resolveFiberSource`.
+ */
+export declare function describeFiberSource(fiber: Fiber | null | undefined): DescribedSource | null;
+export declare function resolveFiberSource(fiber: Fiber | null | undefined): Promise<DescribedSource | null>;
+/**
+ * Describe a fiber + DOM node pair; used for inspection UI.
+ */
+export declare function describeFiberTarget(fiber: Fiber | null | undefined, domNode: Element | null | undefined): FiberTarget | null;
+/**
+ * Full component description: name, props, hook summary, source, owners, parents.
+ */
+export declare function describeComponent(fiber: Fiber | null | undefined): ComponentDescription | null;

package/lib/types/layout-lab/marker-context.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Product-neutral marker context: the declarative boundaries around a probed
+ * fiber, plus whatever registered context providers add on top.
+ *
+ * The core detects Error and Suspense boundaries from fiber-native signals
+ * (./fiber-boundaries). A context provider is a plugin that recognizes
+ * app-specific conventions (for example an ownership marker component) and
+ * contributes named boundary kinds, error-boundary enrichment, and display
+ * hints. Providers never become a prerequisite for inspection: with none
+ * registered, a context still reports Error and Suspense boundaries.
+ */
+import type { Fiber } from './fiber-walk.js';
+import { type BoundaryRef, type ErrorBoundaryInfo, type SuspenseBoundaryInfo } from './fiber-boundaries.js';
+/** A boundary kind a provider adds next to the core `error` and `suspense`. */
+export type ContextBoundaryKind = {
+    kind: string;
+    /** Short lozenge label shown in the probe UI, e.g. `owner`. */
+    label: string;
+    /** CSS color for the lozenge; UIs fall back to a neutral color. */
+    accent?: string;
+};
+export type ContextField = {
+    label: string;
+    value: string;
+};
+/** What one provider found for one probed fiber. Every part is optional. */
+export type ContextContribution = {
+    /** Boundaries of this provider's declared kinds; `null` records "looked, not found". */
+    boundaries?: Record<string, BoundaryRef<Record<string, unknown>> | null>;
+    /** Fields merged onto the generic error boundary when one was found. */
+    errorEnrichment?: Record<string, unknown> | null;
+    /** Display title per boundary kind (core or provider kind). */
+    titles?: Record<string, string>;
+    /** Display fields per boundary kind (core or provider kind). */
+    fields?: Record<string, ContextField[]>;
+    /** Show the error row even when no error boundary fiber was found. */
+    showError?: boolean;
+    /** Extra top-level fields on the context, kept for provider-specific consumers. */
+    extra?: Record<string, unknown>;
+};
+export type ContextProvider = {
+    id: string;
+    kinds?: ContextBoundaryKind[];
+    /** Inspect the probed fiber's ancestry (nearest first). */
+    describe(fibers: Fiber[]): ContextContribution | null;
+    /** Return the provider kind this fiber is a boundary of, or null. Used for DOM highlighting. */
+    matchBoundary?(fiber: Fiber): string | null;
+};
+export type ContextDisplay = {
+    /** Provider kinds that have a boundary on this context, in registration order. */
+    kinds: ContextBoundaryKind[];
+    titles: Record<string, string>;
+    fields: Record<string, ContextField[]>;
+    showError: boolean;
+};
+export type MarkerContext = {
+    boundaries: {
+        error: BoundaryRef<ErrorBoundaryInfo & Record<string, unknown>> | null;
+        suspense: BoundaryRef<SuspenseBoundaryInfo> | null;
+        [kind: string]: BoundaryRef<Record<string, unknown>> | null;
+    };
+    display: ContextDisplay;
+    /** Ids of the providers that contributed to this context. */
+    providers: string[];
+    [extra: string]: unknown;
+};
+/**
+ * Register a context provider. Registering an id again replaces the earlier
+ * provider, so a re-injected bundle cannot double-count. Returns an unregister
+ * function.
+ */
+export declare function registerContextProvider(provider: ContextProvider): () => void;
+export declare function getContextProviders(): Array<{
+    id: string;
+    kinds: ContextBoundaryKind[];
+}>;
+/**
+ * Collect the selected fiber first, then its rendered parent path, then its
+ * debug-owner path. Production builds often lack `_debugOwner`, while
+ * development builds benefit from both signals.
+ */
+export declare function collectContextFibers(fiber: Fiber | null | undefined): Fiber[];
+/**
+ * Describe the boundaries around a probed fiber. Returns null when neither the
+ * core nor any provider found anything, so non-matching trees pay only one
+ * bounded ancestry walk.
+ */
+export declare function describeContext(fiber: Fiber | null | undefined): MarkerContext | null;
+/**
+ * Locate the actual boundary FIBERS (not serialized descriptors) for every
+ * known kind around a probed fiber. Used in-page to resolve a boundary's DOM
+ * node for highlighting; it is not part of the serialized snapshot.
+ */
+export declare function findBoundaryFibers(fiber: Fiber | null | undefined): Record<string, Fiber | null>;

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

@@ -0,0 +1,6 @@
+/** Standalone commit detector. Install the bootstrap before React DOM loads. */
+export { createAvalancheDetector, DETECTION_LEVEL } from '../avalanche/detector.js';
+export type { DetectorOptions, Report, ReportOptions, SortBy } from '../avalanche/reporter.js';
+export { type CommitMetricsAdapter, type IntegrationMode, registerCommitMetricsAdapter, } from '../avalanche/commit-metrics-adapter.js';
+/** Opt-in adapter for hosts whose react-dom writes `__ATL_REACT_METRICS`. */
+export { atlCommitMetricsAdapter, createATLCommitMetricsAdapter, } from '../plugins/atl/commit-metrics-adapter.js';

package/lib/types/package/browser.d.ts

@@ -0,0 +1,10 @@
+export interface BrowserConnection {
+    chippy: unknown;
+    avalanche: unknown;
+    connState: string | null;
+    integration: unknown;
+    activated: boolean | null;
+    probesActive: boolean | null;
+}
+/** Connect this document through a running Chippy helper. Reconnect after navigation. */
+export declare function connectChippy(helperUrl?: string): Promise<BrowserConnection>;

package/lib/types/package/plugin.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Types and helpers for writing a Chippy plugin. `chippy pack` bundles a
+ * plugin module's default export into a custom skill and extension build.
+ */
+import type { ChippyPlugin } from '../plugins/index.js';
+export type { ChippyPlugin, PluginStatus } from '../plugins/index.js';
+export type { ContextBoundaryKind, ContextContribution, ContextField, ContextProvider, } from '../layout-lab/marker-context.js';
+export type { Fiber } from '../layout-lab/fiber-walk.js';
+export type { CommitMetricsAdapter, CommitMetricsDelta, CommitMetricsMeasurement, CommitMetricsRoot, CommitMetricsSnapshot, } from '../avalanche/commit-metrics-adapter.js';
+/** Display name of a fiber's `type`: function, class, memo, or forwardRef. */
+export { getDisplayName } from '../layout-lab/fiber-walk.js';
+/** Fiber name helpers that commit metrics adapters use for hook ancestry. */
+export { getComponentName, isComponentFiber } from '../avalanche/internals.js';
+/** Identity helper that type-checks a plugin definition. */
+export declare function definePlugin(plugin: ChippyPlugin): ChippyPlugin;

package/lib/types/plugins/atl/commit-metrics-adapter.d.ts

@@ -0,0 +1,65 @@
+/**
+ * ATL commit metrics adapter: reads the render counters that Atlassian's
+ * patched react-dom writes into `__ATL_REACT_METRICS` and routes that slot's
+ * `onCommitFiberRoot` callback to the detector.
+ *
+ * The slot name is configurable, so a renamed slot needs no core change.
+ */
+import type { CommitMetricsAdapter, CommitMetricsSnapshot } from '../../avalanche/commit-metrics-adapter.js';
+/**
+ * Per-commit ATL delta - work done in a single commit.
+ * Enables full reconciliation: ATL work counts ↔ Avalanche component counts.
+ *
+ * Key relationship (should hold for any commit):
+ *   componentRenderWithHooksCount + finishClassComponentCount === collateral + sources
+ */
+export type ATLCommitDelta = {
+    /** Function components mounted this commit (should be 0 during pure updates!) */
+    mountWorkCount: number;
+    /** Fiber update work this commit */
+    updateWorkCount: number;
+    /** Work that reached commit phase */
+    commitWorkCount: number;
+    performedWorkCount: number;
+    /** Work interrupted (priority change) */
+    interruptedWorkCount: number;
+    /** Component fiber work (class + function) */
+    componentWorkCount: number;
+    /** Components mounted (should be 0 during pure updates!) */
+    componentMountWorkCount: number;
+    /** Components updated */
+    componentUpdateWorkCount: number;
+    /** DOM work (host fibers) */
+    domWorkCount: number;
+    ticksCount: number;
+    /** Context propagation waves */
+    contextUpdateCount: number;
+    /** Legacy context propagations (tech debt indicator) */
+    legacyContextUpdateCount: number;
+    /** ALL function components rendered (including hookless) */
+    componentRenderWithHooksCount: number;
+    /** Class components rendered */
+    finishClassComponentCount: number;
+    /** useSES-triggered restarts (store mutation detected after concurrent render) */
+    externalStoreRestartCount?: number;
+    /** Work abandoned due to priority preemption (fibers unwound in prepareFreshStack) */
+    priorityInterruptedWorkCount?: number;
+    /** Number of sync renderRoot passes in this commit window */
+    renderRootSyncCount?: number;
+    /** Number of concurrent renderRoot passes in this commit window */
+    renderRootConcurrentCount?: number;
+    /** useState/useReducer dispatches during this commit (react-dom patch; optional) */
+    setStateCount?: number;
+};
+export declare const ATL_DISPATCHER_FRAME = "atlDispatcherHook";
+/** Counter delta between two ATL snapshots. */
+export declare function calculateATLDelta(before: CommitMetricsSnapshot, after: CommitMetricsSnapshot): ATLCommitDelta;
+export type ATLCommitMetricsAdapterOptions = {
+    /** Global slot the patched react-dom writes. Default `__ATL_REACT_METRICS`. */
+    slotName?: string;
+    /** Object that holds the slot. Default `globalThis`. */
+    target?: Record<string, unknown>;
+};
+export declare function createATLCommitMetricsAdapter(options?: ATLCommitMetricsAdapterOptions): CommitMetricsAdapter;
+/** The adapter the shipped bundle registers. */
+export declare const atlCommitMetricsAdapter: CommitMetricsAdapter;

package/lib/types/plugins/atl/metrics-slot.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Seed, protect, and guard a host metrics slot such as `__ATL_REACT_METRICS`.
+ *
+ * The host page owns the slot. Its instrumented react-dom reads the slot before
+ * it calls `onCommitFiberRoot`, and its runtime may zero-fill or delete the slot
+ * during hydration cleanup. These helpers never lock the slot: every descriptor
+ * they write stays `configurable: true`, and a slot the host already locked is
+ * left alone.
+ */
+export declare const DEFAULT_METRICS_SLOT = "__ATL_REACT_METRICS";
+/** Counters a zeroed slot starts with. */
+export declare const METRICS_COUNTER_KEYS: readonly ["mountWorkCount", "updateWorkCount", "commitWorkCount", "interruptedWorkCount", "priorityInterruptedWorkCount", "externalStoreRestartCount", "renderRootSyncCount", "renderRootConcurrentCount", "componentWorkCount", "componentMountWorkCount", "componentUpdateWorkCount", "componentRenderWithHooksCount", "finishClassComponentCount", "domWorkCount", "totalTickCount", "totalCommitCount", "contextUpdateCount", "legacyContextUpdateCount"];
+type SlotTarget = Record<string, unknown>;
+export type MetricsSlotValue = Record<string, unknown>;
+export declare function createZeroMetrics(): MetricsSlotValue;
+/** True when the host owns the slot: non-configurable, or an accessor. */
+export declare function isSlotHostLocked(target: SlotTarget, slotName?: string): boolean;
+/**
+ * Write `metrics` as a plain, deletable data property. Honors a host lock
+ * (configurable: false). Falls back to plain assignment.
+ */
+export declare function protectMetricsSlot(target: SlotTarget, metrics: MetricsSlotValue, slotName?: string): void;
+/** Seed a fresh zeroed slot. Returns the new metrics object. */
+export declare function seedMetricsSlot(target: SlotTarget, slotName?: string): MetricsSlotValue;
+/**
+ * Install a configurable accessor on the slot before React evaluates.
+ *
+ * - `configurable: true`, so a host `delete` succeeds without a TypeError.
+ *   After a delete the slot is gone until the next detector install re-seeds it.
+ * - `set()` ignores null, undefined, and all-zero writes, so host hydration
+ *   cleanup that zero-fills the slot cannot orphan the live metrics object.
+ * - A slot the host already locked is left alone.
+ *
+ * Returns true when the accessor was installed.
+ */
+export declare function installMetricsAccessor(target: SlotTarget, slotName?: string): boolean;
+export {};