@solidjs/signals 2.0.0-rc.6 → 2.0.0-rc.7

package/dist/types/store/index.d.ts

@@ -4,15 +4,12 @@ export { isWrappable, $TRACK, $PROXY, $TARGET } from "./store.js";
 import type { NoFn, ProjectionOptions, Store, StoreOptions, StoreSetter } from "./store.js";
 import type { Refreshable } from "../core/index.js";
 export { createProjectionNext as createProjection } from "./next/projection.js";
-export { registerPatch, registerRowOps, registerSlotPatchNext as registerSlotPatch, patchableRaw } from "./next/patch.js";
 export { storeIsShallow, storeHasFamily, storeHasOptimisticFamily } from "./next/store.js";
 export { createOptimisticStoreNext as createOptimisticStore } from "./next/optimistic.js";
-/** Public createStore: plain form `(init, options?)` and derived writable
+/** Public createStore: plain form `(initialValue, options?)` and derived writable
  * form `(fn, seed, options?)`. */
-export declare function createStore<T extends object = {}>(store: NoFn<T> | Store<NoFn<T>>, options?: StoreOptions & {
-    shallow?: boolean;
-}): [get: Store<T>, set: StoreSetter<T>];
-export declare function createStore<T extends object = {}>(fn: (store: T) => void | T | Promise<void | T> | AsyncIterable<void | T>, store: Partial<T> | Store<NoFn<T>>, options?: ProjectionOptions): [get: Refreshable<Store<T>>, set: StoreSetter<T>];
+export declare function createStore<T extends object = {}>(initialValue: NoFn<T> | Store<NoFn<T>>, options?: StoreOptions): [get: Store<T>, set: StoreSetter<T>];
+export declare function createStore<T extends object = {}>(fn: (draft: T) => void | T | Promise<void | T> | AsyncIterable<void | T>, seed: Partial<T> | Store<NoFn<T>>, options?: ProjectionOptions): [get: Refreshable<Store<T>>, set: StoreSetter<T>];
 export declare function reconcile<T extends U, U>(value: T, key?: string | ((item: NonNullable<any>) => any) | null): (state: U) => T;
 export declare function snapshot<T>(value: T): T;
 export declare function deep<T>(value: T): T;

package/dist/types/store/next/optimistic.d.ts

@@ -1,5 +1,6 @@
+import { type Refreshable } from "../../core/index.js";
 import { type Transition } from "../../core/scheduler.js";
-import { type NoFn, type ProjectionOptions, type Store, type StoreSetter } from "../store.js";
+import { type NoFn, type ProjectionOptions, type Store, type StoreOptions, type StoreSetter } from "../store.js";
 import type { StoreNextTarget } from "./target.js";
 /** #3164 fold: a stamped truth is HELD (masked from ordinary readers until
  * the reveal) only while its transition is live AND retaining optimism —
@@ -8,7 +9,8 @@ import type { StoreNextTarget } from "./target.js";
  * staged values to converge (normal speculation). Resolves merges first:
  * merge unions optimistic nodes/stores into the target. */
 export declare function transitionHoldsOptimism(transition: Transition): boolean;
-export declare function createOptimisticStoreNext<T extends object = {}>(first: T | ((store: T) => void | T | Promise<void | T> | AsyncIterable<void | T>), second?: NoFn<T> | Store<NoFn<T>>, options?: ProjectionOptions): [get: Store<T>, set: StoreSetter<T>];
+export declare function createOptimisticStoreNext<T extends object = {}>(initialValue: NoFn<T> | Store<NoFn<T>>, options?: StoreOptions): [get: Store<T>, set: StoreSetter<T>];
+export declare function createOptimisticStoreNext<T extends object = {}>(fn: (draft: T) => void | T | Promise<void | T> | AsyncIterable<void | T>, seed: Partial<T> | Store<NoFn<T>>, options?: ProjectionOptions): [get: Refreshable<Store<T>>, set: StoreSetter<T>];
 /** Diff the draft against the current OPTIMISTIC VIEW (committed + active
  * overrides — the same view the draft was seeded from) and emit engine writes
  * for exactly the changed keys. Visible-view diffing keeps no-op writes from

package/dist/types/store/next/reconcile.d.ts

@@ -1,17 +1,10 @@
-import type { RowOps } from "./patch.js";
-import { type StoreNextTarget } from "./target.js";
 type KeyFn = (item: any) => any;
 export declare function reconcileNextState(value: any, state: any, key: string | KeyFn | null | undefined, replace?: boolean): void;
+/** Setter-channel row ops (the fold site calls this for array targets with
+ * ops consumers): structural mutation through the setter — push/splice/index
 /** Key equality for EVERY key comparison in this module (re-audit 2, P1-5):
- * SameValueZero, matching the Map-based matchers (buildRowOps, the adoption
- * window) — NaN keys are equal to themselves, so aligned NaN rows stay
- * aligned in the prefix walk instead of forever misaligning. Adoption and
- * row ops MUST agree on key equality or retained DOM rows go stale. */
+ * SameValueZero, matching the adoption window's Map-based matcher — NaN keys
+ * are equal to themselves, so aligned NaN rows stay aligned in the prefix
+ * walk instead of forever misaligning. */
 export declare function sameKey(a: any, b: any): boolean;
-export declare function emitSetterRowOps(t: StoreNextTarget, prevRows: any[], nextRows: any[]): void;
-/** Identity-keyed structural diff, returned rather than emitted: shared by
- * the setter channel (regular queue) and the OPTIMISTIC write channel (lane
- * queue) — same retention semantics, different dispatch timing. Returns
- * null when the lists are identity-aligned (no structure changed). */
-export declare function buildIdentityRowOps(prevRows: any[], nextRows: any[]): RowOps | null;
 export {};

package/dist/types/store/next/store.d.ts

@@ -1,20 +1,14 @@
 import type { Signal } from "../../core/types.js";
-import { type StoreNextFamily, type StoreNextTarget, type PatchChannel } from "./target.js";
-/** Lazily allocate the patch-channel extension (one literal shape). */
-export declare function pcOf(t: StoreNextTarget): PatchChannel;
+import { type StoreNextFamily, type StoreNextTarget } from "./target.js";
 export declare function wrapNext<T extends Record<PropertyKey, any>>(value: T, parent?: StoreNextTarget | null, parentKey?: PropertyKey | null, fam?: StoreNextFamily | null): T;
 /** Unwrap our own proxies to their current backing; leave everything else. */
 export declare function unwrapValue(v: any): any;
-export declare function getNode(target: StoreNextTarget, key: PropertyKey, current: any): Signal<any>;
+export declare function getNode(target: StoreNextTarget, key: PropertyKey, current: any, accKnown?: -1 | 0 | 1): Signal<any>;
 export declare function getHasNode(target: StoreNextTarget, key: PropertyKey, present: boolean): Signal<boolean>;
 export declare function getKeySetNode(target: StoreNextTarget): Signal<number>;
 /** Deep-witness bump: any value/shape change on a record with a live deep()
  * subscriber notifies it. One null check when unused. */
 export declare function bumpDeep(t: StoreNextTarget): void;
-/** Scanned plainness for patch admission (patchableRaw): runs the one-time
- * accessor scan if it hasn't happened yet — the sticky `a` flag alone is not
- * trustworthy before a scan (it starts false and is discovered lazily). */
-export declare function targetIsPlain(target: StoreNextTarget): boolean;
 /** Downgrade a prototype-overlay pending backing to the clone path: builds
  * the real container (committed + overlay writes − deletes) that fold will
  * SWAP in as the committed backing, exactly as if the draft had started on
@@ -90,7 +84,7 @@ export type SetStoreNextFunction<T> = (fn: (draft: T) => T | void) => void;
  * replacements as adoptions. `guard=false` skips the owned-scope dev guard —
  * projection recomputes legitimately write from inside their computed. */
 export declare function storeSetterNext<T>(proxy: T, fn: (draft: T) => T | void, guard?: boolean): void;
-export declare function createStoreNext<T extends Record<PropertyKey, any>>(init: T, shallow?: boolean): [T, SetStoreNextFunction<T>];
+export declare function createStoreNext<T extends Record<PropertyKey, any>>(initialValue: T, shallow?: boolean): [T, SetStoreNextFunction<T>];
 /** True when `proxy` is a SHALLOW store (children served verbatim, slots
  * replaced by reference — #2932). The list driver uses this to choose the
  * slot-patch channel (collected row bodies) over per-record registration. */

package/dist/types/store/next/target.d.ts

@@ -12,7 +12,7 @@
  * entry per read-through object; zero layer slots; nodes, has-nodes, and the
  * key-set node are lazy, materialized only by subscription.
  */
-import type { Computed, Owner, Signal } from "../../core/types.js";
+import type { Computed, Signal } from "../../core/types.js";
 /** Projection family (§7b): children wrap into the family's own map (writes
  * land in the projection, never the source family), and every node created
  * under the family carries the projection computed as its firewall. */
@@ -53,40 +53,6 @@ export interface StoreNextFamily {
     node: Computed<any> | null;
     shallow?: boolean;
 }
-/** Write-side patch-channel state (stage 2), grouped off the target's named
- * fields — see the shape rule on `StoreNextTarget.pc`. One literal shape,
- * allocated by `pcOf` on first use. */
-export interface PatchChannel {
-    /** Slot-patch hooks for shallow arrays — the reconcile walk emits
-     * (i, next, prev) for key-aligned value-replaced slots through the patch
-     * apply queue (records are raw, no per-record targets exist).
-     * MULTI-CONSUMER (external audit): one array can drive several lists. */
-    sp: {
-        fn: (index: number, next: any, prev: any) => void;
-        owner: Owner | null;
-    }[] | null;
-    /** Patch-channel consumers (next/patch.ts): per-record compiled patch
-     * entries, multi-consumer. null when unpatched (the common case). */
-    p: object[] | null;
-    /** Same-batch coalescing stamp (re-audit 2/3): the container array this
-     * channel last pushed a non-forced SELF entry into, plus that entry. A
-     * later same-batch emission UPDATES the queued entry's `next` in place
-     * (latest state wins — adoption REPLACES the captured object, so dropping
-     * the later emission would apply stale state) while `prev` stays the
-     * batch's earliest. The drain clears both stamps so a quiet record
-     * retains nothing from its last batch. */
-    qa: unknown;
-    qe: unknown;
-    /** Row-ops consumers (next/patch.ts, PR-B): structural list ops —
-     * (nextRows, { prefix, sources, removed }) at apply timing. */
-    ro: object[] | null;
-    /** Keys written through the traps since the last fold commit. Bounds the
-     * setter notify/hold-check to O(written) instead of O(subscribed nodes) —
-     * a record with thousands of per-key subscriptions (selection maps) would
-     * otherwise pay a full node scan on every write. null = no trap writes
-     * this batch (bulk paths fall back to the full scan). */
-    wk: Set<PropertyKey> | null;
-}
 export interface StoreNextTarget {
     /** Committed backing: source object (shared) or owned clone. */
     v: Record<PropertyKey, any>;
@@ -102,15 +68,19 @@ export interface StoreNextTarget {
     h: Record<PropertyKey, Signal<boolean>> | null;
     /** Lazy key-set node: membership/iteration/$TRACK subscriptions (§6). */
     k: Signal<number> | null;
-    /** Patch-channel extension (lazily allocated on first use): groups the
-     * write-side stage-2 fields so they never widen the TARGET's own named
-     * field count. LOAD-BEARING SHAPE RULE: array proxy targets carry their
-     * fields as named properties on a real array, and V8 normalizes an array
-     * to dictionary properties as the named count grows (empirically at
-     * counts ≡ 0 mod 3 from 18 up on V8 13.x) — every trap field read then
-     * becomes a hash lookup (~15% uibench, tree suites worst). New
-     * patch-channel state MUST go inside this object, not on the target. */
-    pc: PatchChannel | null;
+    /** Keys written through the traps since the last fold commit. Bounds the
+     * setter notify/hold-check to O(written) instead of O(subscribed nodes) —
+     * a record with thousands of per-key subscriptions (selection maps) would
+     * otherwise pay a full node scan on every write. null = no trap writes
+     * this batch (bulk paths fall back to the full scan); WK_ALL = bound
+     * unusable (array length write). LOAD-BEARING SHAPE RULE: array proxy
+     * targets carry their fields as named properties on a real array, and V8
+     * normalizes an array to dictionary properties as the named count grows
+     * (empirically at counts ≡ 0 mod 3 from 18 up on V8 13.x) — every trap
+     * field read then becomes a hash lookup (~15% uibench, tree suites
+     * worst). Future write-side state MUST ride an extension object, not new
+     * named fields. */
+    wk: Set<PropertyKey> | null;
     /** Lazy deep-witness node: `deep()` subscribes ONE node per record instead
      * of one per path; write paths bump it only when it exists. Separate from
      * `k` so $TRACK/mapArray never rerun on leaf value changes (R9). */
@@ -130,8 +100,12 @@ export interface StoreNextTarget {
     /** Accessor scan performed (scan-once on first trap read; adopted data is
      * not rescanned — legacy-parity behavior). */
     sc: boolean;
-    /** Backing was swapped by adoption this batch (fold diff-notifies it). */
-    adopted: boolean;
+    /** Adoption diff base, non-null when the backing was swapped by adoption
+     * this batch: the view the nodes were LAST TOLD — the pre-batch committed
+     * backing, or the draft's pending backing when a draft preceded the
+     * adoption (its setter-exit notifications already moved the nodes, #3296).
+     * The deferred fold diffs incoming against this, never against committed. */
+    ab: Record<PropertyKey, any> | null;
     /** Pending backing is a prototype-chain OVERLAY of the committed backing
      * (`Object.create(v)` — own keys are this batch's writes, everything else
      * reads through). O(written) per flush instead of O(container) clones

package/dist/types/store/store.d.ts

@@ -1,7 +1,7 @@
 import { type Signal } from "../core/index.js";
 import type { Refreshable } from "../core/index.js";
-/** A read-only view of a store's value as seen by consumers. Mutate it via the paired `StoreSetter`. */
-export type Store<T> = Readonly<T>;
+/** A reactive view of a store's value. Update it through the paired `StoreSetter`. */
+export type Store<T> = T;
 /**
  * A store setter. The callback receives a writable **draft** of the store.
  *
@@ -14,25 +14,30 @@ export type Store<T> = Readonly<T>;
  *
  * The setter does **not** perform keyed reconciliation. If you need surviving
  * items to keep their store identity across full-array replacement, use the
- * projection form — `createStore(fn, seed, { key })` or `createProjection` —
- * whose derive function reconciles its return by `options.key`.
+ * projection form — `createStore(fn, seed, { key })` or
+ * `createProjection(fn, seed, { key })` — whose derive function reconciles
+ * its return by `options.key`.
  */
 export type StoreSetter<T> = (fn: (state: T) => T | void) => void;
-/** Tuple returned by the plain `createStore(initialValue)` form. */
+/** Tuple returned by the plain `createStore(initialValue, options?)` form. */
 export type StoreReturn<T> = [get: Store<T>, set: StoreSetter<T>];
 /** Tuple returned by the derived `createStore(fn, seed, options?)` form. */
 export type ProjectionStoreReturn<T> = [get: Refreshable<Store<T>>, set: StoreSetter<T>];
-/** Base options for store primitives. */
+/** Options shared by all store primitives. */
 export interface StoreOptions {
     /** Debug name (dev mode only) */
     name?: string;
+    /** Single-layer store: root keys reactive, values raw records replaced by reference */
+    shallow?: boolean;
 }
-/** Options for derived/projected stores created with `createStore(fn)`, `createProjection`, or `createOptimisticStore(fn)`. */
+/**
+ * Options for derived/projected stores created with
+ * `createStore(fn, seed, options?)`, `createProjection(fn, seed, options?)`,
+ * or `createOptimisticStore(fn, seed, options?)`.
+ */
 export interface ProjectionOptions extends StoreOptions {
     /** Key property name or function for reconciliation identity; `null` merges positionally */
     key?: string | ((item: NonNullable<any>) => any) | null;
-    /** Single-layer store: root keys reactive, values raw records replaced by reference */
-    shallow?: boolean;
     /**
      * Treat the seed as commit #0: the store is born committed with the seed's
      * contents, shown until the derive's first real answer lands. While that

package/dist/types-cjs/core/attribution-hooks.d.cts

@@ -1,3 +1,4 @@
+import type { Transition } from "./scheduler.cjs";
 import type { Computed, Signal } from "./types.cjs";
 /**
  * Dev-only observability hook points for the reactive core.
@@ -58,6 +59,69 @@ export interface AttributionHooks {
      * from the node's state against its asyncStart snapshot.
      */
     asyncEnd(el: Computed<any>, prev: unknown, value: unknown, direct: boolean): void;
+    /**
+     * An effect's imperative half (its effect callback) is about to run /
+     * has run. Both fire outside the run's try; `effectRunEnd` fires whether
+     * or not the callback threw. Writes between the two are the effect's.
+     */
+    effectRunStart(el: Computed<any>): void;
+    effectRunEnd(el: Computed<any>): void;
+    /**
+     * One synchronous step of an `action()` generator is about to run / has
+     * run (`it.next()`/`it.throw()` up to the next yield). `it` is the
+     * invocation's iterator — stable identity across its steps; `name` the
+     * generator function's name. Writes between the two are the action's.
+     */
+    actionStepStart(it: object, name: string | undefined): void;
+    actionStepEnd(it: object): void;
+    /**
+     * A flush found `t` incomplete (transitionComplete's false verdict): its
+     * writes stay staged and its queues are about to be parked. Fired BEFORE
+     * this flush's lane effects (the visible acknowledgers — isPending
+     * companions, optimistic values) run; `holdEnd` fires from the root
+     * stashQueues call after them, so effect runs between the two are runs that
+     * painted *during* the hold.
+     */
+    holdStart(t: Transition): void;
+    holdEnd(): void;
+    /**
+     * `t` was judged complete (transitionComplete's true verdict, before `_done`
+     * flips). Fired before its held writes commit, so `t._pendingNodes` still
+     * lists what was staged.
+     */
+    transitionSettled(t: Transition): void;
+    /** `outgoing` was folded into `target` (`outgoing._done = target`). */
+    transitionMerged(target: Transition, outgoing: Transition): void;
+    /**
+     * A store setter batch replaced the container at `path` (e.g. `store.user`)
+     * with a different one (both non-null, same array-ness, not the same
+     * logical slot), and this is the leaf census of the new container against
+     * the old: `total` leaves (own keys, or items) in the new one, `unchanged`
+     * of which are the same value as before (identity, judged on unwrapped
+     * values — object keys compared by key, array items by membership), and
+     * `prevTotal` leaves in the old one. Containers above 64 leaves are not
+     * announced. Fired per written key from the write channel's notify. The
+     * engine decides whether the replacement was a spread-copy worth a
+     * diagnostic.
+     */
+    storeReplaced(path: string, isArray: boolean, total: number, unchanged: number, prevTotal: number): void;
+    /**
+     * A `mapArray` update both disposed and created rows: `removed` are the
+     * items whose rows were disposed, `created` the items that got new rows,
+     * `newLen` the list's new length, `keyed` whether a key function is in use
+     * (false = identity or by-index). Fired after commit. The engine judges
+     * whether the churn replaced equivalent records (unstable identity).
+     */
+    listChurn(el: Computed<any>, removed: unknown[], created: unknown[], newLen: number, keyed: boolean): void;
+    /**
+     * A loading boundary started (`shown` true) or stopped showing its
+     * fallback. `boundary` is the boundary's queue (stable identity); `tree`
+     * its bound subtree computed when already constructed — the first show can
+     * fire while the subtree is still being built — whose owner chain names
+     * the boundary. Fired at the source-set transitions (first pending source
+     * registers / last one clears), not per flush.
+     */
+    boundaryFallback(boundary: object, tree: Computed<any> | undefined, shown: boolean): void;
 }
 export declare let attrHooks: AttributionHooks | null;
 export declare function setAttributionHooks(hooks: AttributionHooks | null): void;

package/dist/types-cjs/core/attribution.d.cts

@@ -22,6 +22,45 @@ import type { Computed } from "./types.cjs";
  * front-ends.
  */
 export type ChangeKind = "write" | "derived" | "async" | "refresh";
+/**
+ * Provenance of a root change: the imperative frame that performed it.
+ *
+ * - `interaction` — a user event handler (the web runtime marks dispatch via
+ *   `withInteraction`). `name` is the event type, `target` the element hit
+ *   (`button#next "Next →"`), `at` the dispatch time on the `performance.now()`
+ *   clock — the base every feedback-latency number is measured from.
+ * - `effect` — an effect callback (`name` = the effect's name; `run` = the
+ *   compute run whose effect phase performed the write, when that run was
+ *   recorded — so a write can be joined to the re-run that produced it).
+ * - `action` — a step of an `action()` generator (`name` = the generator's
+ *   name, when it has one). Writes after an `await` (not a `yield`) run in a
+ *   bare microtask and stamp `external` — the documented escape.
+ * - `async` — an async landing (`name` = the node whose flight landed).
+ * - `external` — none of the above: timers, sockets, promise callbacks, setup.
+ *
+ * `interaction` on a non-interaction frame is the user event the frame runs
+ * under — an action started by a click, an effect whose run was caused by a
+ * click's write, a landing whose flight a click started. It is what lets
+ * every downstream cost be keyed by the interaction that paid for it.
+ */
+export interface ChangeOrigin {
+    kind: "interaction" | "effect" | "action" | "async" | "external";
+    name?: string;
+    target?: string;
+    at?: number;
+    interaction?: ChangeOrigin;
+    /** `effect` only: the `RerunEvent.run` of the compute run this callback belongs to. */
+    run?: number;
+}
+/** A user interaction, as the web runtime describes it to `withInteraction`. */
+export interface InteractionRef {
+    /** Event type — `click`, `keydown`, `input`… */
+    type: string;
+    /** The element hit, e.g. `button#next "Next →"`. */
+    target?: string;
+    /** Dispatch time on the `performance.now()` clock; defaults to now. */
+    at?: number;
+}
 export interface ChangeRecord {
     /** Global monotonic change sequence — orders causes across the app. */
     seq: number;
@@ -34,6 +73,10 @@ export interface ChangeRecord {
     stack?: string[];
     /** For derived changes: the upstream changes that produced this one. */
     causes?: ChangeRecord[];
+    /** Root changes only: who performed the write. */
+    origin?: ChangeOrigin;
+    /** Root changes only: when the write was stamped (`performance.now()` clock). */
+    at?: number;
 }
 export interface RerunEvent {
     /** Global monotonic run sequence. */
@@ -74,19 +117,21 @@ export interface RerunEvent {
     changed: boolean;
     /**
      * Which posture this run executed under. "optimistic" = under an
-     * optimistic lane (overlay recompute); "transition" = a transition was
-     * active or owns the node (the run may be replayed/settled later);
-     * "plain" = an ordinary committed run. Overlay runs are real work (they
-     * count toward time budgets) but are never blamed as waste, and costs()
-     * reports their time separately as `overlayMs`.
+     * optimistic lane (overlay recompute); "held" = a hold was open or owns
+     * the node (the run may be replayed/settled later); "plain" = an ordinary
+     * committed run. Overlay runs are real work (they count toward time
+     * budgets) but are never blamed as waste, and costs() reports their time
+     * separately as `overlayMs`.
      */
-    phase: "plain" | "transition" | "optimistic";
+    phase: "plain" | "held" | "optimistic";
     /**
-     * The changed value was held in `_pendingValue` (a transition hold) rather
-     * than committed directly; its reveal happens on the transition's own
-     * schedule. Held runs are excluded from waste accounting.
+     * The changed value was parked in `_pendingValue` (held) rather than
+     * committed directly; its reveal happens on the hold's own schedule. Held
+     * runs are excluded from waste accounting.
      */
     held: boolean;
+    /** The user interaction this run traces back to through its causes, if any. */
+    interaction?: ChangeOrigin;
 }
 export interface AttributionOptions {
     /** Pretty-print each re-run to the console (default true). */
@@ -161,6 +206,42 @@ export interface AttributionOptions {
     waterfalls?: {
         minFlightMs: number;
     } | false;
+    /**
+     * Silent-hold warning: emit a diagnostic when a user's writes were held
+     * behind async work for at least `infoMs` (default 100ms — RAIL's "feels
+     * instant" ceiling) and the screen never acknowledged the wait — no
+     * `isPending()`/`latest()` reader downstream of the held writes or their
+     * blockers, no optimistic value, no `affects()` mark, and no lane effect
+     * painted while held. Below `warnMs`
+     * (default 200ms — the INP "good" ceiling) the event is advisory
+     * (structured channel only); at or above it the console gets the finding.
+     * The engine measures to the commit, not the paint, so every number is a
+     * floor on what the user saw; the thresholds sit at the strict end of the
+     * band on purpose. Holds that staged no root write (initial loads, bare
+     * `refresh()`) are never judged: nothing the user did went unanswered.
+     * `false` disables hold tracking altogether (`longHolds` included).
+     */
+    holds?: {
+        infoMs: number;
+        warnMs: number;
+    } | false;
+    /**
+     * Long-hold warning: emit a diagnostic when a hold's quiescent tail — the
+     * time from the LAST write to join it until it committed — reached
+     * `infoMs` (default 500ms), `warn` from `warnMs` (default 1000ms, where
+     * RAIL says the user loses the thread). Measured from the last join so a
+     * hold that keeps taking input (typing) is judged by each wait, not by its
+     * lifetime. A hold this long is past what a stale screen should carry,
+     * acknowledged or not: the honest UI is a fallback, which a `Loading`
+     * boundary gives only when it has not revealed yet or its `on` prop
+     * changed. Reported as LONG_HOLD when the hold was acknowledged; a silent
+     * long hold stays one SILENT_HOLD with the boundary repair appended.
+     * `false` disables.
+     */
+    longHolds?: {
+        infoMs: number;
+        warnMs: number;
+    } | false;
 }
 export interface ScopeCost {
     name: string;
@@ -185,6 +266,15 @@ export interface WriteCost {
     /** Summed self-time of every downstream re-run it caused. */
     downstreamMs: number;
 }
+/**
+ * Run `fn` as the handler of a user interaction: every root write it performs
+ * (and every action step or effect the write causes) carries the interaction
+ * as provenance. The web runtime wraps event dispatch in this; it is dev-only
+ * and safe to call with no engine enabled.
+ */
+export declare function withInteraction<T>(ref: InteractionRef, fn: () => T): T;
+/** `click on button#next "Next →"`, `effect "syncTitle"`, `action "save"`, … */
+export declare function formatOrigin(origin: ChangeOrigin): string;
 export declare function formatRerun(event: RerunEvent): string;
 export interface Attribution {
     enable(opts?: AttributionOptions): void;
@@ -211,6 +301,26 @@ export interface Attribution {
      * thresholded view of the same data.
      */
     waterfalls(): readonly WaterfallRecord[];
+    /**
+     * Every settled transition hold that staged at least one root write since
+     * enable() (ring-buffered like history()). Facts, not verdicts: recorded
+     * regardless of duration or acknowledgment — the SILENT_HOLD diagnostic is
+     * the thresholded, unacknowledged subset.
+     */
+    holds(): readonly HoldEvent[];
+    /**
+     * What the user waited on, folded from holds() and the interaction on each
+     * re-run: `sources` ranks async sources by the silent time writes spent
+     * held behind them (with which affordances answered, how often, and which
+     * interactions were held); `interactions` ranks user events by the total
+     * time they cost — re-run work caused (long-flush hazard) beside time held
+     * (silent-hold hazard). Facts at every duration; SILENT_HOLD is the
+     * thresholded verdict. Two more tables round out the picture: `flights`
+     * counts each async source's flights and how many were abandoned before
+     * landing (the re-ask storm), and `fallbacks` measures how long each
+     * loading boundary showed its fallback and how often that was a flash.
+     */
+    feedback(): AttributionFeedbackTables;
     /**
      * Cooperative preload declaration: stamp a flight object (promise or async
      * iterable) with its true kickoff time BEFORE the reactive graph sees it.
@@ -223,7 +333,15 @@ export interface Attribution {
      * later enable()). Dev-only, like the whole DEV surface.
      */
     markFlight(flight: object, startedAt?: number): void;
+    /**
+     * Run `fn` as a user interaction's handler: root writes inside stamp it as
+     * their origin, and actions/effects/flights it causes carry it. The web
+     * runtime wraps every event dispatch in this; custom renderers and test
+     * harnesses call it themselves. Callable while attribution is disabled.
+     */
+    withInteraction: typeof withInteraction;
     format: typeof formatRerun;
+    formatOrigin: typeof formatOrigin;
 }
 /** One landed flight: its node name, wall duration, and upstream chain. */
 export interface FlightLink {
@@ -236,4 +354,142 @@ export interface WaterfallRecord {
     /** Summed wall time of the chain — the serialized cost. */
     sequentialMs: number;
 }
+export interface HeldWrite {
+    name: string;
+    prev?: string;
+    value?: string;
+    origin?: ChangeOrigin;
+}
+export interface HoldEvent {
+    /**
+     * Wall time the user waited: from the interaction that performed the held
+     * writes when one is known (`interaction.at`) or the first flush that
+     * parked them, whichever is earlier, to the commit.
+     */
+    holdMs: number;
+    /**
+     * The quiescent tail: from the LAST held write to join (the user's final
+     * input) to the commit. Equal to `holdMs` for a single write; shorter when
+     * the hold kept taking input. The LONG_HOLD measure.
+     */
+    tailMs: number;
+    /** The user interaction whose writes were held, when the stamp is known. */
+    interaction?: ChangeOrigin;
+    /** Flushes that ended with the hold still open. */
+    flushes: number;
+    /** Root signal writes staged behind the hold (the user's unanswered input). */
+    heldWrites: HeldWrite[];
+    /** Async nodes the hold waited on (union across its parked flushes). */
+    blockers: string[];
+    /**
+     * Feedback the graph provably rendered for this hold, as `"<kind>:<node>"`
+     * — `isPending:posts`, `latest:page`, `optimistic:todos`, `affects:list`.
+     * Empty and `paintedDuringHold === 0` is the SILENT_HOLD signature.
+     */
+    acknowledgedBy: string[];
+    /**
+     * Effect callbacks that ran inside the hold's parked flushes. Mainline
+     * effects are stashed while a hold is open, so these are lane effects —
+     * readers of optimistic values and of `isPending()`/`latest()` companions,
+     * i.e. the screen changing in response to the hold. An unrelated effect
+     * cannot land here: it waits with everything else.
+     */
+    paintedDuringHold: number;
+    /** The hold was opened (or joined) by an `action()`. */
+    action: boolean;
+}
+export interface FeedbackSource {
+    /** The async nodes the holds waited on; empty when an action alone kept them open. */
+    sources: string[];
+    holds: number;
+    /** Summed wait across the holds (ms). */
+    heldMs: number;
+    worstMs: number;
+    /** Holds with no acknowledgment at all — the SILENT_HOLD signature, at any duration. */
+    silent: number;
+    silentMs: number;
+    /** Holds whose only acknowledgment was a `latest()` shadow: the input showed, nothing said "loading". */
+    latestOnly: number;
+    /**
+     * Holds whose quiescent tail (last write to join → commit) reached
+     * `longHolds.infoMs`, acknowledged or not — the LONG_HOLD signature at the
+     * table level. The affordance is not the whole answer there: a fallback
+     * (`Loading` keyed with `on`), a preload, a cache, or a faster source is.
+     * `longMs` sums the tails.
+     */
+    long: number;
+    longMs: number;
+    /** Which affordances answered, and in how many holds — ranked. */
+    acknowledgedBy: {
+        by: string;
+        holds: number;
+    }[];
+    /** Interactions whose writes were held here, ranked by holds. */
+    interactions: {
+        interaction: string;
+        holds: number;
+    }[];
+    /** Distinct root writes that were held. */
+    writes: string[];
+    /** Holds an action opened or joined. */
+    actions: number;
+}
+export interface FeedbackInteraction {
+    /** `click on button#next "Next →"` — type and target; repeated dispatches fold together. */
+    interaction: string;
+    /** Distinct dispatches seen (by dispatch time). */
+    dispatches: number;
+    /** Re-runs traced back to this interaction, and their summed self-time. */
+    runs: number;
+    selfMs: number;
+    /** The most re-run self-time a single dispatch caused — the long-flush hazard. */
+    worstDispatchMs: number;
+    /** Holds this interaction's writes waited in — the silent-hold hazard. */
+    holds: number;
+    heldMs: number;
+    silentMs: number;
+    worstHoldMs: number;
+}
+/** Per async source: how many flights it started, and how many it threw away. */
+export interface FlightStats {
+    source: string;
+    /** Flights registered (a recompute that produced a new promise/iterable). */
+    flights: number;
+    /** Flights that landed (whether or not the value changed). */
+    landed: number;
+    /**
+     * Flights superseded by a newer one before landing — the search-as-you-type
+     * signature when large: every keystroke asked, most answers were discarded.
+     * A debounced/equality-gated derivation between input and fetch is the repair.
+     */
+    abandoned: number;
+    /** Summed and worst wall time of landed flights (ms). */
+    landedMs: number;
+    worstMs: number;
+}
+/** Per loading boundary: how long, and how briefly, it showed its fallback. */
+export interface FallbackStats {
+    /** The boundary's owner path (`<App> › <Feed>`), or `boundary` when unnamed. */
+    boundary: string;
+    /** Times the fallback was shown. */
+    shows: number;
+    /** Summed and worst fallback duration (ms) across completed shows. */
+    shownMs: number;
+    worstMs: number;
+    /**
+     * Shows shorter than the flash window (default 150ms): a spinner that
+     * appeared and vanished — the other end of the SILENT_HOLD spectrum, too
+     * much feedback for too little wait. A preload, a cache, or lifting the
+     * fetch above the boundary removes the flash.
+     */
+    flashes: number;
+}
+export interface AttributionFeedbackTables {
+    sources: FeedbackSource[];
+    interactions: FeedbackInteraction[];
+    /** Async sources ranked by abandoned flights, then by flights. */
+    flights: FlightStats[];
+    /** Loading boundaries ranked by flashes, then by time shown. */
+    fallbacks: FallbackStats[];
+}
 export declare const attribution: Attribution;