@solidjs/signals 2.0.0-rc.1 → 2.0.0-rc.11

package/dist/types/attribution.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `@solidjs/signals/attribution` — the "why did this run" engine.
+ *
+ * A separate entry on purpose: the core ships only the hook slot
+ * (`OBSERVE.attribution`, which `enable()` installs into) and the declared
+ * frames (`withInteraction`, `withOrigin`); 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, graphSize } 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, AttributionValues, ChangeKind, ChangeOrigin, ChangeRecord, CreateEvent, EffectRunEvent, FallbackEvent, FlightEvent, FlightLink, FlushEvent, GraphEvent, GraphSize, HeldWrite, HistoryRecords, HistoryType, 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";

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 declare const graphSize: typeof Engine.graphSize;
+export type { Acknowledgement, Attribution, AttributionOptions, AttributionValues, ChangeKind, ChangeOrigin, ChangeRecord, CreateEvent, EffectRunEvent, FallbackEvent, FlightEvent, FlightLink, FlushEvent, GraphEvent, GraphSize, HeldWrite, HistoryRecords, HistoryType, 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";

package/dist/types/boundaries.d.ts

@@ -1,4 +1,5 @@
-import { Queue, type Computed, type Effect } from "./core/index.js";
+import type { OptimisticLane } from "./core/lanes.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> {
@@ -37,17 +38,70 @@ export declare class CollectionQueue extends Queue {
     _collectionType: number;
     _sources: Set<Computed<any>>;
     _tree?: BoundaryComputed<any>;
+    /** The output pass — fallback or content (createCollectionBoundary). */
+    _output?: Computed<any>;
     _pending: boolean;
     _disabled: Signal<boolean>;
     _error?: Signal<unknown>;
     _collapsed: Signal<boolean>;
     _revealController?: RevealController;
     _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;
+    /** The lane the `on` pass that queued this re-arm ran under (onNode), if
+     * any: the fallback swap is display-ahead — shown through the lane. */
+    _rearmLane: OptimisticLane | null;
     constructor(type: number);
     run(type: number): void;
+    /** An `on` dependency notified (onNode → scheduler `pendingRearms`);
+     * drained after the heap, before the verdict, under the notifying write's
+     * transaction (#3540). A boundary showing content is fresh again: it
+     * releases its hold now and, if anything under it is still pending, swaps
+     * to its fallback. The swap is staged, so it lands with the write's frame
+     * — at once when nothing else holds it, with the rest of the new page
+     * when something outside the boundary does; if the pending lands first,
+     * `_checkSources` clears it and no fallback is shown. An `on` that read a
+     * lane (`latest()`, an optimistic write) asked for the change now:
+     * `_rearmLane` shows the swap through the lane, beside the held frame.
+     * Children stay alive behind the fallback. */
+    _rearm(): void;
+    /** Show the fallback: the swap the output pass selects on. Staged, it is
+     * the frame's and lands with its commit. Re-armed from a lane pass
+     * (`lane`), it is the current frame's — committed outright, as the lane's
+     * view already is on screen — and shown through the lane: the output pass
+     * publishes a derived override and its readers run from the lane's queue,
+     * at the park, ahead of the transaction (a lane pass reads staged plain
+     * writes committed, so a staged swap would be invisible to it). */
+    _swap(lane: OptimisticLane | null): void;
+    /** Retry the collected failures of an error boundary: recompute each
+     * source that threw, so the boundary can recover. */
+    _retry(): void;
     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;
+    /** Has a collected source stopped counting for this boundary? A source
+     * with a live affects() mark holds display state for the mark's lifetime
+     * (the visual channel): the marked node carries no status of its own, so
+     * the count is the liveness test. The release sweep (finalizePureQueue
+     * after mark release) re-runs this check. A source born held under this
+     * boundary (recompute, #3540) carries no status either: it is collected
+     * while it has a staged value and no committed one, and released by the
+     * commit that initializes it. */
+    _settled(source: Computed<any>): boolean;
+    /** The pre-verdict sweep (scheduler run(), #3540): a collecting boundary
+     * whose OUTPUT is pending — its fallback read something not ready — is
+     * judged here, under the transaction. That output is what an initialized
+     * parent holds the frame on, and it derives from `_disabled`, not the
+     * tree: the tree settling never re-runs it, only a sweep does, and the
+     * commit sweep runs after the verdict the output's own read keeps parking
+     * — the content waited for the fallback's flight. Judged ready here, the
+     * boundary stages `_disabled` false with the frame and the output re-runs
+     * in this heap: it reads the tree and drops the fallback's read (recompute
+     * settles a pass's outgoing pending sources), so the verdict sees the
+     * release. A boundary showing a ready fallback parks nothing and keeps the
+     * commit sweep's reveal. */
+    _judgeHeld(): void;
     _checkSources(): void;
 }
 /**
@@ -59,8 +113,27 @@ export declare class CollectionQueue extends Queue {
  *
  * @param fn the tracked subtree
  * @param fallback the fallback shown while async reads in `fn` are unresolved
- * @param options `on` — accessor whose value scopes the boundary; when set,
- *   transitions caused by writes to other reactive sources are *not* caught
+ * @param options `on` — a dependency list: a tracked function whose reads
+ *   re-arm the boundary. Its return value is irrelevant (never compared);
+ *   what matters is what it reads. Without `on`, a boundary that has shown
+ *   content keeps it through a refetch (the pending holds with the
+ *   transaction). With `on`, a write to anything it reads makes the boundary
+ *   fresh again: it stops waiting on its current content, and if something
+ *   under it is pending it shows `fallback` until the new content is ready;
+ *   if nothing is pending, the notification is a no-op. The fallback lands
+ *   with the same frame as the change that caused it — now, when nothing
+ *   else holds that frame; together with the rest of the new page during a
+ *   held navigation, not before it. If the same data is also read outside
+ *   the boundary, the frame waits on it and the fallback can never be seen
+ *   (DEV warns `LOADING_ON_OUTSIDE_HOLD`); the fix is structural — move the
+ *   outside read under the boundary so one hold owns the data. A frame held
+ *   past the content's landing by something else (the write's action, other
+ *   pending data) also shows no fallback; that is a race the fallback may
+ *   lose, a legitimate outcome, and not reported. A display-ahead read in
+ *   `on` (`latest()`) shows the fallback now, beside the held frame; that
+ *   is a capability, not the recommended shape. Optimistic writes and a
+ *   source going pending notify like any other. The children are not
+ *   re-created — they stay alive behind the fallback.
  *
  * @example
  * ```tsx

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,8 +14,10 @@ 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;
 export declare function handleAsync<T>(el: Computed<T>, result: T | PromiseLike<T> | AsyncIterable<T>, setter?: (value: T) => void): T;
 export declare function clearStatus(el: Computed<any>, clearUninitialized?: boolean): void;
 export declare function notifyStatus(el: Computed<any>, status: number, error: any, blockStatus?: boolean, lane?: OptimisticLane): 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;