@solidjs/signals 2.0.0-rc.2 → 2.0.0-rc.20

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

@@ -1,24 +1,75 @@
-import type { Computed, Signal } from "./types.js";
+import type { ChangeOrigin } from "./attribution.js";
+import type { Transaction } from "./scheduler.js";
+import type { Computed, Owner, Signal } from "./types.js";
+/** The hold the engine records against (L2: scheduler.ts `Transaction`).
+ * Outward-facing language says *holds*; the engine's hook names keep their
+ * historical `transition` wording. */
+export type Transition = Transaction;
 /**
- * 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__.
+ *
+ * The contract is internal: the built-in engine installs through
+ * `setAttributionHooks`, and nothing public names this interface
+ * (`OBSERVE.attribution.installed` exposes the installed table as an opaque
+ * object). It becomes public surface again the day a second engine exists.
  *
  * 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;
+    /**
+     * The handler returned. `returned` is its return value: a thenable means
+     * the handler continues past this frame (`async () => { await … }`), and
+     * the engine may keep the interaction's record open until it settles —
+     * the wait the person experiences is that continuation, not the frame.
+     */
+    interactionEnd(returned?: unknown): 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: NavigationRef): void;
+    originEnd(): void;
+    /**
+     * A `flush()` drain is starting: work is scheduled or a transition is
+     * active, so the loop will run at least once. Always paired with
+     * `flushEnd` for the same drain, and never nested (`flush()` is a no-op
+     * while the queue is running), so start → end is the wall time of one
+     * drain — the scheduler's own span.
+     */
+    flushStart(): 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).
+     * Always paired with `recomputeEnd` (recompute's one early return — a node
+     * disposed during its own pass, #3621 — fires it before leaving).
      */
     recomputeStart(el: Computed<any>, create: boolean): void;
     /**
@@ -36,6 +87,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 +109,243 @@ 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. `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, 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,
+     * `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.
+     *
+     * A show is the boundary's SWAP, a staged write: `transition` is the one
+     * it lands with (`transitionSettled` is its display instant), or `null`
+     * when this drain commits it (`flushEnd`) — the lane swap included, whose
+     * readers run in this drain. A hide before that commit means the fallback
+     * was never displayed — the content landed first and the sweep cleared the
+     * swap ahead of the frame (#3540).
+     */
+    boundaryFallback(boundary: object, tree: Computed<any> | undefined, shown: boolean, transition?: Transition | null): void;
+    /**
+     * An optimistic override the screen displayed is being replaced by a
+     * different value. `"superseded"`: a new authoritative value landed that
+     * differs from the guess (tracked readers re-derive to it). `"reverted"`:
+     * nothing new landed and the guess lifts back to the committed value it
+     * covered (the action failed, or never wrote what it promised). `shown`
+     * is the override as displayed. Fired when the two differ by identity;
+     * the engine applies the node's own equality before judging.
+     */
+    optimisticReverted(el: Signal<any> | Computed<any>, shown: unknown, truth: unknown, how: "superseded" | "reverted"): 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 →"` — the tag, then `#id` or
+     * `[name=…]`, then the element's text in quotes. Describe fully; the
+     * engine keeps the quoted text as its `values` option allows (the
+     * record's `target` is its own string, this one is never mutated).
+     */
+    target?: string;
+    /** Dispatch time on the `performance.now()` clock; defaults to now. */
+    at?: number;
+    /**
+     * The dispatch this frame handles — the DOM `Event` itself. Frames with the
+     * same `event` are one interaction: the first opens the record (its `type`,
+     * `target` and `at` describe it) and every later one re-enters it, so each
+     * listener of one dispatch adds its work to one record. Such a record stays
+     * open for joining until the next task — every listener of a dispatch runs
+     * within its task — and is recorded no earlier; a frame for the event after
+     * that opens a new interaction. Without `event` the record is the frame's
+     * alone and can settle as it closes.
+     *
+     * A join key only, compared by identity and held weakly: it is never
+     * recorded — no `InteractionEvent`, origin or other record carries it — and
+     * the engine keeps no strong reference to it.
+     */
+    event?: object;
+}
+/**
+ * A navigation, as a router describes it to `withOrigin` around the location
+ * write it is about to perform — what `withOrigin` accepts: a declared unit
+ * of work whose writes the engine attributes as a whole, discriminated by
+ * `kind` so another kind (a form submission, a tab switch) can join without
+ * the seam changing shape; the engine knows `navigation` today. 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;
+    /**
+     * The route the document arrived on — declared by the router around the
+     * work that establishes its initial match (building its context), not
+     * around a write: there is no location write on a fresh document, and
+     * without this a consumer has the route pattern for every navigation
+     * but the first. The record opens at `at`, which defaults to `0` (the
+     * `performance.now()` origin — the document's own navigation start, so
+     * the record joins Navigation Timing); a router mounted long after the
+     * document loaded passes its own start. It settles when the frame closes,
+     * `committed` with no writes: it declares the route, it does not time the
+     * mount — the holds the mount waits in are their own records. `from` is
+     * meaningless for it and ignored.
+     */
+    initial?: boolean;
+    /**
+     * The interaction the navigation is for, when the router already knows it
+     * will not be on the stack at write time. A router that awaits between
+     * the request and the write (guards or loaders resolved in its core before
+     * it publishes the location) captures `OBSERVE.attribution.currentOrigin()`
+     * in the request and hands it back here, and the record — and every hold
+     * and re-run its write causes — joins the click as if the write had been
+     * synchronous. Any origin will do: the engine takes the interaction it
+     * carries. Declared beats ambient: the key's presence is the declaration
+     * — `interaction: currentOrigin()` with nothing in effect at the request
+     * (`undefined`) declares that the navigation was for no interaction, and an
+     * interaction on the stack at write time is used only when the key is absent.
+     */
+    interaction?: ChangeOrigin;
 }
 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: NavigationRef, 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,24 @@
+/**
+ * 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 scope — pass a memo/effect accessor or raw node,
+ * or a scope's name as a string (an out-of-process consumer such as the
+ * diagnostics bridge holds no node, only the `nodeName` the records
+ * carry). Records name their scope by `nodeId`; a node that has never run
+ * under the engine has none, and no history. By name, every scope of that
+ * name answers. A view of `history("rerun")`, so it shares that buffer's
+ * gate: runs nothing wanted a record of (no `rerun` listener, fold or log
+ * at the time) left no record and are not here — a console session that
+ * wants them subscribes or imports a fold first.
+ */
+export declare function why(target: unknown): RerunEvent[];
+/**
+ * Current dependency names of one scope — the devtools subscription view.
+ * Read from the graph, not a record, so it answers with or without an
+ * audience for re-run records (and with the engine disabled).
+ */
+export declare function subscriptions(target: unknown): string[];