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

package/dist/prod/store/store.js

@@ -252,7 +252,7 @@ s) {
     // Callers guard on `pendingCheckActive`, which only flips inside
     // isPending() — the verdict layer is loaded and its hook installed.
     const o = e[STORE_NODE]?.[$AFFECTS];
-    if (o?.o?.t) GlobalQueue.Wt(o);
+    if (o?.o?.t) GlobalQueue.zt(o);
     if (affectsScopes.size) {
         // Chained backings (§7b): a wrapper's STORE_VALUE can be another store's
         // proxy — marks cover by identity of the BASE raw, so resolve the chain
@@ -263,7 +263,7 @@ s) {
                 let t = r;
                 for (;;) {
                     if (s.scope.has(t)) {
-                        GlobalQueue.Wt(e);
+                        GlobalQueue.zt(e);
                         break;
                     }
                     const o = t?.[$TARGET];

package/dist/types/core/attribution-hooks.d.ts

@@ -1,3 +1,4 @@
+import type { Transition } from "./scheduler.js";
 import type { Computed, Signal } from "./types.js";
 /**
  * Dev-only observability hook points for the reactive core.
@@ -36,6 +37,17 @@ export interface AttributionHooks {
     write(el: Signal<any> | Computed<any>, prev: unknown, value: unknown): void;
     /** refresh() invalidated this node (self-invalidation, no dep changed). */
     refreshed(el: Computed<any>): void;
+    /**
+     * A new async flight entered the system (`_inFlight` was just assigned
+     * during a recompute of `el`). Always fired inside the owning recompute —
+     * both call paths (core's recompute and the projection self-registration)
+     * run within one — so the engine can read the current frame stack to link
+     * the flight to the change that caused it (waterfall chaining). `flight`
+     * is the registered thenable/iterable itself: the engine keys a first-seen
+     * origin registry on its identity, so shared and preloader-marked promises
+     * carry their true start time instead of the moment the graph saw them.
+     */
+    flightStart(el: Computed<any>, flight: object): void;
     /** An async landing is about to apply its value (before any branch). */
     asyncStart(el: Computed<any>): void;
     /**
@@ -47,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/core/attribution.d.ts

@@ -22,6 +22,45 @@ import type { Computed } from "./types.js";
  * 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). */
@@ -143,6 +188,60 @@ export interface AttributionOptions {
      * disables.
      */
     wideWrites?: number | false;
+    /**
+     * Async-waterfall warning: emit a diagnostic when an async flight that
+     * could only start after an upstream flight resolved (its recompute's
+     * cause chain reaches the upstream's async landing, and its origin
+     * post-dates that landing) forms a sequential chain of 2+ flights, each
+     * of which took at least `minFlightMs` (default 50ms). The duration gate
+     * is one safety valve for what the graph cannot see: a settled
+     * preload/cache hit resolves fast and never warns. In-flight preloads are
+     * absolved by origin: `markFlight()` stamps (and first-seen identity)
+     * prove work predated the upstream landing — parallel, not sequential.
+     * Chains of 2 emit at `info` severity, structured channel only (a
+     * dependent fetch is sometimes intrinsic, and unmarked external preloads
+     * are invisible); 3+ escalate to `warn` with console output. `false`
+     * disables.
+     */
+    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;
@@ -167,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;
@@ -186,6 +294,202 @@ export interface Attribution {
         scopes: ScopeCost[];
         writes: WriteCost[];
     };
+    /**
+     * Every graph-provable sequential flight chain observed since enable()
+     * (ring-buffered like history()). Facts, not verdicts: chains are recorded
+     * regardless of the duration gate — the ASYNC_WATERFALL diagnostic is the
+     * 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.
+     * A route preloader or query cache calls this on the promise it hands out
+     * (on the WRAPPER it mints, with the original kickoff time — wrapping
+     * defeats identity tracking otherwise); any dependent that later awaits it
+     * is then judged against the real start — work already in the air when its
+     * upstream landed is parallel, never a waterfall link. Callable while
+     * attribution is disabled (marks made at navigation time must survive a
+     * 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 {
+    name: string;
+    ms: number;
+}
+export interface WaterfallRecord {
+    /** Sequential flights, oldest first, ending at the flight that landed. */
+    chain: FlightLink[];
+    /** 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;

package/dist/types/core/constants.d.ts

@@ -105,6 +105,14 @@ export declare const CONFIG_FRESH_READ: number;
  * (A17). Cleared at commit (the commit IS the reveal); subscribers masked
  * during the hold are woken by finalizePureQueue's post-revert pass. */
 export declare const CONFIG_HELD_TRUTH: number;
+/** SLOT node (store leaf): created through `slotSignal` with `_host`/`_key`
+ * backrefs baked into the literal. The unobserved sweep dispatches these to
+ * the ONE shared hook (`setSlotUnobserved`) instead of a per-node closure
+ * held in a per-node extension — store mounts materialize one signal per
+ * touched leaf, so per-node allocations (options object, equals closure,
+ * unobserved closure, NodeExtension) were the measured create-floor bytes
+ * (warm dbmon profile: store node machinery ~36% + GC ~29%). */
+export declare const CONFIG_SLOT_NODE: number;
 export declare const STATUS_NONE = 0;
 export declare const STATUS_PENDING: number;
 export declare const STATUS_ERROR: number;

package/dist/types/core/core.d.ts

@@ -54,6 +54,13 @@ export declare function setEffectStatusNotify(fn: NonNullable<typeof effectStatu
 export declare function statusNotifierOf(el: any): ((this: any, status?: number, error?: any) => void) | undefined;
 export declare function signal<T>(v: T, options?: NodeOptions<T>): Signal<T>;
 export declare function signal<T>(v: T, options?: NodeOptions<T>, firewall?: Computed<any>): FirewallSignal<T>;
+/** The shared slot-node unobserved handler — a live binding read directly by
+ * the sweep sites (no wrapper frame, no null check: a CONFIG_SLOT_NODE node
+ * existing implies the store module loaded and registered the hook). */
+export declare let slotUnobservedHook: (node: Signal<any>) => void;
+/** Install the shared slot-node unobserved handler (store module, once). */
+export declare function setSlotUnobserved(fn: (node: Signal<any>) => void): void;
+export declare function slotSignal<T>(v: T, equals: (a: T, b: T) => boolean, host: object, key: PropertyKey, acc: boolean, firewall?: Computed<unknown> | null): Signal<T>;
 export declare function optimisticSignal<T>(v: T, options?: NodeOptions<T>): Signal<T>;
 export declare function optimisticComputed<T>(fn: (prev?: T) => T | PromiseLike<T> | AsyncIterable<T>, options?: NodeOptions<T>): Computed<T>;
 export declare function isEqual<T>(a: T, b: T): boolean;
@@ -115,9 +122,11 @@ export declare const READ_SLOW: unique symbol;
  * installed at first until() call — apps that never use until() shake it.
  */
 export declare function notifyAuthoritativeObservers(el: Signal<any> | Computed<any>): void;
-/** Installs the until() machinery hook. Idempotent; called by until() before
- * any authoritative-view read happens (same late-binding contract as the
- * optimistic engine). */
+/** Installs the authoritative-reader wakeup hook. Idempotent; called by every
+ * creator of a CONFIG_AUTHORITATIVE_READ computation — until() and refresh() —
+ * before its first read (same late-binding contract as the optimistic engine;
+ * the gating bit is only ever set by such a read, so the `!` call sites are
+ * safe once every setter installs, #3303). */
 export declare function installAuthoritativeRead(): void;
 export declare function readNodeFast<T>(el: Signal<T>): T | typeof READ_SLOW;
 export declare function read<T>(el: Signal<T> | Computed<T>): T;

package/dist/types/core/dev.d.ts

@@ -6,9 +6,17 @@ export interface DevHooks {
     onUpdate?: () => void;
     onStoreNodeUpdate?: (state: any, property: PropertyKey, value: any, prev: any) => void;
 }
-export type DiagnosticSeverity = "warn" | "error";
-export type DiagnosticCode = "STRICT_READ_UNTRACKED" | "PENDING_ASYNC_UNTRACKED_READ" | "PENDING_ASYNC_FORBIDDEN_SCOPE" | "REACTIVE_WRITE_IN_OWNED_SCOPE" | "ACTION_CALLED_IN_OWNED_SCOPE" | "RUN_WITH_DISPOSED_OWNER" | "NO_OWNER_CLEANUP" | "CLEANUP_IN_FORBIDDEN_SCOPE" | "SETTLED_CLEANUP_UNOWNED" | "FLUSH_IN_EFFECT_CALLBACK" | "PRIMITIVE_IN_FORBIDDEN_SCOPE" | "NO_OWNER_EFFECT" | "NO_OWNER_BOUNDARY" | "ASYNC_OUTSIDE_LOADING_BOUNDARY" | "INVALID_REFRESH_TARGET" | "INVALID_AFFECTS_TARGET" | "MISSING_EFFECT_FN" | "SYNC_NODE_RECEIVED_ASYNC" | "REACTIVITY_HALTED" | "INVARIANT_VIOLATION" | "HUGE_FAN_OUT" | "HUGE_FAN_IN" | "HOT_SCOPE_RERUNS" | "HOT_SCOPE_TIME" | "WIDE_SCOPE_DEPS" | "UNSTABLE_MEMO_OUTPUT" | "WIDE_WRITE";
-export type DiagnosticKind = "strict-read" | "async" | "write" | "lifecycle" | "owner" | "error" | "perf" | "graph";
+/**
+ * `info` is the advisory tier: a structural fact worth surfacing that is not
+ * presumptively a bug (e.g. a 2-deep sequential fetch chain, which may be an
+ * intrinsic data dependency). Budget/assertion consumers should treat only
+ * `warn`/`error` as failures unless they opt in to `info`.
+ */
+export type DiagnosticSeverity = "info" | "warn" | "error";
+export type DiagnosticCode = "STRICT_READ_UNTRACKED" | "PENDING_ASYNC_UNTRACKED_READ" | "PENDING_ASYNC_FORBIDDEN_SCOPE" | "REACTIVE_WRITE_IN_OWNED_SCOPE" | "ACTION_CALLED_IN_OWNED_SCOPE" | "RUN_WITH_DISPOSED_OWNER" | "NO_OWNER_CLEANUP" | "CLEANUP_IN_FORBIDDEN_SCOPE" | "SETTLED_CLEANUP_UNOWNED" | "SETTLE_WALK_UNINITIALIZED_SOURCE" | "FLUSH_IN_EFFECT_CALLBACK" | "PRIMITIVE_IN_FORBIDDEN_SCOPE" | "NO_OWNER_EFFECT" | "NO_OWNER_BOUNDARY" | "ASYNC_OUTSIDE_LOADING_BOUNDARY" | "INVALID_REFRESH_TARGET" | "INVALID_AFFECTS_TARGET" | "MISSING_EFFECT_FN" | "SYNC_NODE_RECEIVED_ASYNC" | "REACTIVITY_HALTED" | "INVARIANT_VIOLATION" | "HUGE_FAN_OUT" | "HUGE_FAN_IN" | "HOT_SCOPE_RERUNS" | "HOT_SCOPE_TIME" | "WIDE_SCOPE_DEPS" | "UNSTABLE_MEMO_OUTPUT" | "WIDE_WRITE" | "ASYNC_WATERFALL" | "HOT_SCOPE_FANOUT" | "SILENT_HOLD" | "LONG_HOLD" | "EFFECT_WRITES_OWN_SOURCE" | "EFFECT_RELAY_TEAR" | "IMMUTABLE_UPDATE_IN_STORE" | "UNSTABLE_LIST_IDENTITY";
+export type DiagnosticKind = "strict-read" | "async" | "write" | "lifecycle" | "owner" | "error" | "perf" | "graph"
+/** Perceived responsiveness: the runtime behaved correctly but the user saw no feedback. */
+ | "responsiveness";
 /** First warning when a node's live edge count reaches this size. */
 export declare const GRAPH_SIZE_WARN_AT = 2000;
 /** Repeat the warning at this interval after the first. */
@@ -22,6 +30,15 @@ export interface DiagnosticEvent {
     ownerId?: string;
     ownerName?: string;
     nodeName?: string;
+    /**
+     * Root-first chain of named owners enclosing the subject of the event —
+     * component roots as `<Name>`, computations by their `name` option (or
+     * the `effect`/`computed` default) — e.g. `["<App>", "<TodoRow>", "effect"]`.
+     * Unnamed owners (plain roots) are skipped. Absent when the subject has no
+     * named owner at all (a top-level scope, or an unowned primitive — which
+     * is usually the finding itself).
+     */
+    ownerPath?: string[];
     data?: Record<string, unknown>;
 }
 export type DiagnosticListener = (event: DiagnosticEvent) => void;
@@ -34,10 +51,12 @@ export interface Diagnostics {
     subscribe(listener: DiagnosticListener): () => void;
     capture(): DiagnosticCapture;
     /**
-     * Registers a console footer printed after the first console report of
+     * Registers a console footer appended to the first console report of
      * each diagnostic code — a discovery pointer to deeper guidance (e.g.
-     * solid-js registers its shipped repair skill). Returning undefined for
-     * an event suppresses the footer. Passing undefined unregisters and
+     * solid-js registers its shipped repair skill). Reported events carry
+     * it as trailing lines of the same console entry; events that surface as
+     * a thrown error instead get it as a follow-up line. Returning undefined
+     * for an event suppresses the footer. Passing undefined unregisters and
      * resets the once-per-code memory.
      */
     setConsoleFooter(footer: ((event: DiagnosticEvent) => string | undefined) | undefined): void;
@@ -62,14 +81,42 @@ export declare const DEV: Dev;
  * dev builds so user apps degrade instead of crashing.
  */
 export declare function assertInvariant(condition: boolean, name: string, message: string): void;
-export declare function emitDiagnostic(event: Omit<DiagnosticEvent, "sequence">): DiagnosticEvent;
+/** Anything a diagnostic can be about: an owner (root, computed, effect) or a signal. */
+export type DiagnosticSubject = Owner | Signal<any> | Computed<any>;
+/**
+ * Root-first names of the owners enclosing `subject` (inclusive when the
+ * subject is itself a named owner). Signals hop to their registering owner
+ * (`_owner`, set by registerGraph). Unnamed owners are skipped so the path
+ * reads as the component tree plus the scope: `<App> › <TodoRow> › effect`.
+ */
+export declare function ownerPath(subject: DiagnosticSubject | null | undefined): string[] | undefined;
+/**
+ * Records a diagnostic on the structured channel (listeners, captures) and
+ * returns the entry. `subject` locates it: the current reactive `context` by
+ * default (right for the synchronous rule checks — they fire inside the
+ * scope that misbehaved); pass the node for scheduler-time findings whose
+ * ambient context is the flush, or `null` for events that have no location
+ * by nature. Console output is a separate step — see `reportDiagnostic`.
+ */
+export declare function emitDiagnostic(event: Omit<DiagnosticEvent, "sequence" | "ownerPath">, subject?: DiagnosticSubject | null | undefined): DiagnosticEvent;
+/**
+ * The console face of a diagnostic — ONE entry per finding: the message, the
+ * owner path (`in <App> › <TodoRow> › effect`) so a human can locate it, the
+ * once-per-code footer as trailing lines, and — when the subject is a
+ * binding effect the rendering runtime tagged — the element it writes, as a
+ * second console argument (hover highlights it, click jumps to Elements).
+ * Severity picks the console method. Call sites report the entry
+ * `emitDiagnostic` returned so the structured and console channels never
+ * disagree.
+ */
+export declare function reportDiagnostic(entry: DiagnosticEvent): void;
 /**
  * Shared strict-read diagnostics for core read() and the store proxy traps.
  * Single source for the message text — the #2897 safeguard parity between
  * memos and stores is exactly these firing identically from both paths.
  */
-export declare function throwPendingUntrackedRead(strictReadLabel: string, fields?: Partial<Omit<DiagnosticEvent, "sequence" | "data">>): never;
-export declare function warnStrictReadUntracked(strictReadLabel: string, fields?: Partial<Omit<DiagnosticEvent, "sequence">>): void;
+export declare function throwPendingUntrackedRead(strictReadLabel: string, fields?: Partial<Omit<DiagnosticEvent, "sequence" | "data" | "ownerPath">>): never;
+export declare function warnStrictReadUntracked(strictReadLabel: string, fields?: Partial<Omit<DiagnosticEvent, "sequence" | "ownerPath">>): void;
 export declare function registerGraph(value: any, owner: Owner | null): void;
 export declare function clearSignals(node: Owner): void;
 export declare function getChildren(owner: Owner): Owner[];

package/dist/types/core/heap.d.ts

@@ -2,9 +2,11 @@ import type { Computed } from "./types.js";
 /** The queue a node belongs to, picked from its own zombie flag. */
 export declare function queueFor(n: Computed<any>): Heap;
 /**
- * Schedule one subscriber to re-run on the next flush: tracked effects bypass
- * the heap and go directly to their effect queue; everything else is inserted
- * into its own (zombie-flag-routed) heap with the `_min` cursor pulled down.
+ * Schedule one subscriber to re-run on the next flush: inserted into its own
+ * (zombie-flag-routed) heap with the `_min` cursor pulled down. Tracked
+ * effects ride the heap too — the heap visit is their (empty) compute phase,
+ * which hands the callback to the user queue once the pass has committed
+ * (see GlobalQueue._update, #3291).
  */
 export declare function enqueueSub(node: Computed<any>): void;
 export interface Heap {

package/dist/types/core/invariants.d.ts

@@ -2,7 +2,7 @@ import type { OptimisticLane } from "./lanes.js";
 import type { Computed, Signal } from "./types.js";
 /**
  * Test-mode invariant checks for the async/transition/lane machinery.
- * Catalog and rationale: packages/signals/INTERNALS-ASYNC-STATE.md.
+ * Catalog and rationale: packages/signals/docs/INTERNALS-ASYNC-STATE.md.
  *
  * These are implementation self-consistency checks, not semantic rules: a
  * violation means the reactive system contradicted itself.