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

package/dist/types/attribution.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `@solidjs/signals/attribution` — the "why did this run" engine.
+ *
+ * A separate entry on purpose: the core ships only the hook slot
+ * (`OBSERVE.attribution.install`) and the interaction frame
+ * (`OBSERVE.attribution.withInteraction`); the engine that turns hook facts
+ * into re-run explanations, cost tables, holds and feedback lives here, so an
+ * observe build carries it only when something imports this module. The dev
+ * and observe tiers resolve to this file; the prod tier resolves to
+ * `attribution.prod.ts`, an inert engine with the same surface, so app code
+ * can import it unconditionally.
+ */
+export { attribution, formatOrigin, formatRerun } from "./core/attribution.js";
+export { costs } from "./core/attribution-costs.js";
+export { feedback } from "./core/attribution-feedback.js";
+export { subscriptions, why } from "./core/attribution-queries.js";
+export type { Acknowledgement, Attribution, AttributionOptions, AttributionRecords, AttributionRecordType, ChangeKind, ChangeOrigin, ChangeRecord, FlightLink, HeldWrite, HoldEvent, InteractionEvent, NavigationEvent, NavigationHop, RerunEvent, WaterfallRecord } from "./core/attribution.js";
+export type { AttributionCostTables, ScopeCost, WriteCost } from "./core/attribution-costs.js";
+export type { AttributionFeedbackTables, FallbackStats, FeedbackInteraction, FeedbackNavigation, FeedbackSource, FlightStats } from "./core/attribution-feedback.js";
+export type { InteractionRef, NavigationRef, OriginRef } from "./core/attribution-hooks.js";

package/dist/types/attribution.prod.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `@solidjs/signals/attribution` as the prod tier resolves it.
+ *
+ * A prod build has no hook sites — `__OBSERVE__` folded every one out — so an
+ * engine installed there would never hear a fact. Rather than make apps guard
+ * the import per tier, prod resolves this inert twin: the same `Attribution`
+ * surface, every query empty, `enable()` a no-op. Type-checked against the
+ * real engine's interface so the two cannot drift.
+ */
+import type { Attribution } from "./core/attribution.js";
+import type * as Engine from "./attribution.js";
+export declare const attribution: Attribution;
+export declare const costs: typeof Engine.costs;
+export declare const feedback: typeof Engine.feedback;
+export declare const why: typeof Engine.why;
+export declare const subscriptions: typeof Engine.subscriptions;
+export declare const formatRerun: typeof Engine.formatRerun;
+export declare const formatOrigin: typeof Engine.formatOrigin;
+export type { Acknowledgement, Attribution, AttributionOptions, AttributionRecords, AttributionRecordType, ChangeKind, ChangeOrigin, ChangeRecord, FlightLink, HeldWrite, HoldEvent, InteractionEvent, NavigationEvent, NavigationHop, RerunEvent, WaterfallRecord } from "./core/attribution.js";
+export type { AttributionCostTables, ScopeCost, WriteCost } from "./core/attribution-costs.js";
+export type { AttributionFeedbackTables, FallbackStats, FeedbackInteraction, FeedbackNavigation, FeedbackSource, FlightStats } from "./core/attribution-feedback.js";
+export type { InteractionRef, NavigationRef, OriginRef } from "./core/attribution-hooks.js";

package/dist/types/boundaries.d.ts

@@ -1,4 +1,4 @@
-import { Queue, type Computed, type Effect } from "./core/index.js";
+import { Queue, type Computed, type Effect, type Owner } from "./core/index.js";
 import type { Signal } from "./core/index.js";
 import { type Accessor } from "./signals.js";
 export interface BoundaryComputed<T> extends Computed<T> {
@@ -45,9 +45,18 @@ export declare class CollectionQueue extends Queue {
     _initialized: boolean;
     _onFn: (() => any) | undefined;
     _prevOn: any;
+    /** The boundary's owner — where a `caught` report locates itself, set before the children are built (a creation-time throw arrives before `_tree`). */
+    _owner?: Owner;
     constructor(type: number);
     run(type: number): void;
+    /** The `on` key, or ON_INIT when it throws. Evaluated mid-propagation,
+     * inside the pending node's own pass: read as a spectator so the key's
+     * sources never become that node's dependencies (#3528). */
+    _readOn(): any;
     notify(node: Effect<any>, type: number, flags: number, error?: any): boolean;
+    /** Is `reporter` live and routed to this boundary — under it, with no
+     * collecting pending-type boundary in between (`reporterBlocksSource`'s test)? */
+    _holds(reporter: Computed<any>): boolean;
     _checkSources(): void;
 }
 /**

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

@@ -23,15 +23,22 @@
  * `yield` is the transaction-safe suspension point: the action waits for a
  * yielded promise and re-enters the transaction before running the code after
  * it. A plain `await` does NOT — the runtime has no hook into an async
- * generator's internal await continuations, so writes to fresh signals
- * between an `await` and the next `yield` escape the transaction and commit
- * immediately. `await` is still the ergonomic choice for typed results; just
- * put a bare `yield` before any writes that follow it:
+ * generator's internal await continuations, so code between an `await` and
+ * the next `yield` runs OUTSIDE the transaction: writes to fresh signals
+ * commit immediately, and anything that creates a reader there — `until()`,
+ * `latest()`, a memo or effect, a mount — is created mainline, where a read of
+ * this action's held state makes it born held (A29): staged with the
+ * transaction and replayed at its commit. For `until()` that commit is the
+ * settle its own promise holds open (#3482). `await` is still the ergonomic
+ * choice for typed results; just put a bare `yield` before any write or
+ * reader creation that follows it — including the expression of the next
+ * `yield`, which is evaluated before the step re-enters:
  *
  * ```ts
  * const saved = await api.createTodo(text); // typed result
- * yield; // re-enter the transaction before writing
+ * yield; // re-enter the transaction before writing or reading
  * setTodos(t => { ... });
+ * yield until(() => todos.some(t => t.id === saved.id));
  * ```
  *
  * (For the same reason, don't call `flush()` inside an action body — it

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

@@ -14,7 +14,7 @@ export declare function setPendingError(el: Computed<any>, source?: Computed<any
 export declare function forEachDependent(el: Computed<any>, fn: (node: Computed<any>, link: Link) => void): void;
 export declare function releaseSettledDependents(el: Computed<any>): void;
 export declare function settleErroredDependents(el: Computed<any>, error: any): void;
-export declare function settlePendingSource(el: Computed<any>): void;
+export declare function settlePendingSource(el: Computed<any>, source?: Computed<any>): void;
 export declare function isThenable<T>(value: T | PromiseLike<T>): value is PromiseLike<T>;
 /** Fire and clear a node's iterator-flight cancellation hook (#3122). */
 export declare function releaseFlightTeardown(el: Computed<any>): void;

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

@@ -0,0 +1,35 @@
+export interface ScopeCost {
+    name: string;
+    kind: "effect" | "memo";
+    runs: number;
+    selfMs: number;
+    /**
+     * Self-time of PLAIN, non-held runs that produced an unchanged value —
+     * the recoverable number. Overlay runs (optimistic/transition) are never
+     * counted here: an optimistic recompute landing back on the committed
+     * value is the mechanism working, not waste.
+     */
+    wastedMs: number;
+    /** Self-time spent in optimistic/transition (overlay) runs. */
+    overlayMs: number;
+}
+export interface WriteCost {
+    /** Root cause name (a signal write, async landing, or refresh target). */
+    name: string;
+    /** Number of downstream re-runs this root triggered. */
+    runs: number;
+    /** Summed self-time of every downstream re-run it caused. */
+    downstreamMs: number;
+}
+export interface AttributionCostTables {
+    /** Ranked by self-time. */
+    scopes: ScopeCost[];
+    /** Ranked by the total downstream re-run time each root write caused. */
+    writes: WriteCost[];
+}
+/**
+ * Aggregated cost tables since `enable()`: `scopes` ranked by self-time
+ * (with `wastedMs` = time spent on unchanged-value runs), `writes` ranked by
+ * total downstream re-run time each root write caused.
+ */
+export declare function costs(): AttributionCostTables;

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

@@ -0,0 +1,133 @@
+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;
+}
+/**
+ * Per route: what navigating to it cost, folded from settled
+ * `NavigationEvent`s — the route-level view a router integration used to
+ * have to build itself, from the runtime's own facts.
+ */
+export interface FeedbackNavigation {
+    /** The route pattern (`/users/:id`), or the concrete `to` when the router gave no pattern. */
+    name: string;
+    navigations: number;
+    /** Summed and worst request-to-settle time (ms) across settled navigations. */
+    settledMs: number;
+    worstMs: number;
+    /** Navigations whose writes waited in a hold, and the time they waited. */
+    held: number;
+    heldMs: number;
+    /** Held navigations the screen acknowledged nothing for — the SILENT_HOLD signature. */
+    silent: number;
+    /** Navigations overwritten by a later one before they landed. */
+    superseded: number;
+    /** Navigations a redirect sent elsewhere on the way (keyed by where they ended up). */
+    redirected: number;
+}
+export interface AttributionFeedbackTables {
+    sources: FeedbackSource[];
+    interactions: FeedbackInteraction[];
+    /** Routes ranked by the time spent held navigating to them, then by total settle time. */
+    navigations: FeedbackNavigation[];
+    /** Async sources ranked by abandoned flights, then by flights. */
+    flights: FlightStats[];
+    /** Loading boundaries ranked by flashes, then by time shown. */
+    fallbacks: FallbackStats[];
+}
+/**
+ * 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. Three more tables round out the picture: `navigations`
+ * ranks routes by the time spent held navigating to them (folded from settled
+ * navigations), `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.
+ */
+export declare function feedback(): AttributionFeedbackTables;

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

@@ -1,22 +1,48 @@
+import type { ChangeOrigin } from "./attribution.js";
 import type { Transition } from "./scheduler.js";
-import type { Computed, Signal } from "./types.js";
+import type { Computed, Owner, Signal } from "./types.js";
 /**
- * Dev-only observability hook points for the reactive core.
+ * Observe-tier hook points for the reactive core.
  *
  * Core's obligation is to call these with true facts at the moments they
  * happen; ALL attribution semantics (stamps, cause chains, timings, warnings)
- * live in the engine that installs them (attribution.ts — same pattern as the
- * GlobalQueue._* feature slots). `attrHooks` is null unless an engine is
- * installed, so the disabled cost is one null check per site, and prod builds
- * fold every site out behind __DEV__.
+ * live in the engine that installs them — `@solidjs/signals/attribution`, a
+ * separate entry so an observe build that never enables it never ships it
+ * (same pattern as the GlobalQueue._* feature slots). `attrHooks` is null
+ * unless an engine is installed, so the disabled cost is one null check per
+ * site, and prod builds fold every site out behind __OBSERVE__.
  *
  * IMPORTANT for implementers of call sites: a hook call must never sit inside
  * a `try` block — rollup's tryCatchDeoptimization retains functions referenced
- * inside `try` even behind a folded __DEV__ guard, which re-couples the dev
+ * inside `try` even behind a folded __OBSERVE__ guard, which re-couples the
  * engine into prod bundles (#2883 harness). Set a local flag inside the try
  * and call the hook after the catch.
  */
 export interface AttributionHooks {
+    /**
+     * `withInteraction` opened a user-interaction frame: root writes until the
+     * matching `interactionEnd` were performed by the handler of `ref`. Frames
+     * nest strictly (synchronous dispatch), so the engine keeps a stack.
+     */
+    interactionStart(ref: InteractionRef): void;
+    interactionEnd(): void;
+    /**
+     * `withOrigin` opened a declared-origin frame: root writes until the
+     * matching `originEnd` are the unit of work `ref` describes (a router's
+     * navigation). Nests inside an interaction frame — a link click that
+     * navigates — or stands alone (a redirect from an action, a programmatic
+     * `navigate()`). Frames nest strictly, so the engine keeps a stack.
+     */
+    originStart(ref: OriginRef): void;
+    originEnd(): void;
+    /**
+     * A `flush()` drain finished: every batch it processed either committed
+     * (its effects have run) or was parked in a held transition (`holdStart`
+     * fired for it). Fires once per drain, after the loop — not per batch, and
+     * not for a `flush()` call that found nothing to do. Gives the engine the
+     * "committed, screen updated" instant for writes no transition ever held.
+     */
+    flushEnd(): void;
     /**
      * A recompute is starting; `el._deps` still holds the previous run's links.
      * Always paired with `recomputeEnd` (recompute has no early returns).
@@ -102,9 +128,12 @@ export interface AttributionHooks {
      * `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.
+     * diagnostic. `owner` is the owner the store root was created under
+     * (undefined when unrecorded): the finding is about the store, not about
+     * whoever wrote it, so an `OBSERVE.exclude`d panel's store stays silent
+     * however its writes arrive.
      */
-    storeReplaced(path: string, isArray: boolean, total: number, unchanged: number, prevTotal: number): void;
+    storeReplaced(path: string, isArray: boolean, total: number, unchanged: number, prevTotal: number, owner: Owner | null | undefined): void;
     /**
      * A `mapArray` update both disposed and created rows: `removed` are the
      * items whose rows were disposed, `created` the items that got new rows,
@@ -122,6 +151,115 @@ export interface AttributionHooks {
      * registers / last one clears), not per flush.
      */
     boundaryFallback(boundary: object, tree: Computed<any> | undefined, shown: boolean): void;
+    /**
+     * The one query on the surface: the provenance a root write performed at
+     * this moment would be stamped with — the innermost open frame (an effect
+     * callback, an action step, a navigation), the interaction the handler
+     * runs under, or, inside a recompute, the origin of the change that caused
+     * it — or `undefined` when none applies (external). For a runtime that
+     * records a fact of its own beside the engine's records — `@solidjs/web`'s
+     * `"call"` record stamps the server-function call it is about to make —
+     * so the fact joins the engine's interaction and navigation records by the
+     * identity of the object returned, not by time.
+     */
+    currentOrigin(): ChangeOrigin | undefined;
+}
+/** A user interaction, as a rendering 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;
 }
+/**
+ * A navigation, as a router describes it to `withOrigin` around the location
+ * write it is about to perform. Match eagerly and describe before writing:
+ * the engine keys the work the write causes — the hold behind route data,
+ * the re-runs, the verdicts — to this record, and names it by the
+ * parametrized route so occurrences fold together.
+ *
+ * The engine keeps the object and reads `name`, `to` and `params` again when
+ * the navigation settles (and when a hold on it is judged), so a router whose
+ * match is not final at write time — a lazy route subtree that resolves inside
+ * the hold — may describe coarsely (`/admin/*`) and assign the exact pattern
+ * and params onto the same object once it knows them. `from` and `at` are
+ * read once, when the frame opens.
+ */
+export interface NavigationRef {
+    kind: "navigation";
+    /** The matched route pattern — `/users/:id`. The name every consumer groups by. */
+    name?: string;
+    /** Concrete destination path. */
+    to?: string;
+    /** Concrete path being left. */
+    from?: string;
+    /** Route params the pattern bound — `{ id: "42" }` (optional params unbound: `undefined`). */
+    params?: Readonly<Record<string, string | undefined>>;
+    /**
+     * When the navigation was requested on the `performance.now()` clock;
+     * defaults to now. A router whose request predates the write (loaders
+     * awaited before the location moves) passes its own start here.
+     */
+    at?: number;
+    /**
+     * `>= 1`: this frame is the Nth redirect hop of the navigation still
+     * pending — a guard or loader sent it elsewhere before it landed — not a
+     * new navigation. The engine folds it onto that pending record: the record
+     * keeps the user's request time and interaction, its destination becomes
+     * this one, and the abandoned destination is kept in `redirects`. Without
+     * a pending navigation to fold onto it opens a navigation of its own.
+     */
+    redirect?: number;
+}
+/**
+ * What `withOrigin` accepts: a declared unit of work whose writes the engine
+ * should attribute as a whole. A discriminated union so kinds can be added
+ * (a form submission, a tab switch) without the seam changing shape; the
+ * engine knows `navigation` today.
+ */
+export type OriginRef = NavigationRef;
 export declare let attrHooks: AttributionHooks | null;
 export declare function setAttributionHooks(hooks: AttributionHooks | null): void;
+/**
+ * Run `fn` as the handler of a user interaction: every root write it performs
+ * (and every action step, effect or flight the write causes) is attributed to
+ * `ref` by whichever engine is installed. The web runtime wraps event
+ * dispatch in this; custom renderers and test harnesses call it themselves.
+ * With no engine installed it is `fn()` — the wiring, not the engine, so it
+ * lives in core and is reachable as `OBSERVE.attribution.withInteraction`.
+ *
+ * The `finally` is deliberate and safe under the try rule above: this
+ * function is referenced only from the `OBSERVE` object, which prod builds
+ * fold to `undefined`, so nothing retains it there.
+ */
+export declare function withInteraction<T>(ref: InteractionRef, fn: () => T): T;
+/**
+ * Run `fn` as a declared unit of work — a router's navigation: every root
+ * write it performs is attributed to `ref` (and, through it, to the enclosing
+ * interaction when there is one), so the hold those writes wait in, the
+ * re-runs they cause and the verdicts on them all carry the route's name
+ * instead of a bare signal's. Same contract as `withInteraction`: the wiring,
+ * not the engine; `fn()` with no engine installed. Reachable as
+ * `OBSERVE.attribution.withOrigin`.
+ *
+ * ```ts
+ * OBSERVE
+ *   ? OBSERVE.attribution.withOrigin(
+ *       { kind: "navigation", name: match.pattern, to, from, params: match.params },
+ *       () => setLocation(to)
+ *     )
+ *   : setLocation(to);
+ * ```
+ */
+export declare function withOrigin<T>(ref: OriginRef, fn: () => T): T;
+/**
+ * The provenance a root write performed now would carry, as the installed
+ * engine sees it (`AttributionHooks.currentOrigin`); `undefined` with no
+ * engine, or when nothing is in effect. Reachable as
+ * `OBSERVE.attribution.currentOrigin` — how a runtime stamps a fact of its
+ * own (a server-function call) with the interaction or navigation it ran
+ * for, so an observer joins the two by identity.
+ */
+export declare function currentOrigin(): ChangeOrigin | undefined;

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

@@ -0,0 +1,10 @@
+/**
+ * Point queries over the engine's live state — the devtools/console view of
+ * one scope. Their own module so a records-only consumer never ships them;
+ * they read the engine's ring buffer and the graph, and register nothing.
+ */
+import { type RerunEvent } from "./attribution.js";
+/** Re-run history for one node — pass a memo/effect accessor or raw node. */
+export declare function why(target: unknown): RerunEvent[];
+/** Current dependency names of one scope — the devtools subscription view. */
+export declare function subscriptions(target: unknown): string[];