@solidjs/signals 2.0.0-beta.9 → 2.0.0-rc.0

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

@@ -1,6 +1,21 @@
+import { NotReadyError } from "./error.js";
 import { type OptimisticLane } from "./lanes.js";
-import type { Computed } from "./types.js";
+import type { Computed, Link } from "./types.js";
+export declare function addPendingSource(el: Computed<any>, source: Computed<any>): boolean;
+/**
+ * A loading-window node hit an unready source (sync throw in recompute, or a
+ * NotReadyError-rejected flight): register for the source's settle — the
+ * settlePendingSource walk runs off `_pendingSources` + `_blocked` alone —
+ * with NO read-visible pending status, no downstream propagation, no
+ * transition, no lane registration. Commit #0 keeps serving.
+ */
+export declare function parkLoadingWindow(el: Computed<any>, e: NotReadyError): void;
+export declare function setPendingError(el: Computed<any>, source?: Computed<any>, error?: any): void;
+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 isThenable<T>(value: T | PromiseLike<T>): value is PromiseLike<T>;
 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/constants.d.ts

@@ -9,12 +9,22 @@ export declare const REACTIVE_DISPOSED: number;
 export declare const REACTIVE_OPTIMISTIC_DIRTY: number;
 export declare const REACTIVE_SNAPSHOT_STALE: number;
 export declare const REACTIVE_LAZY: number;
+export declare const REACTIVE_MANUAL_WRITE: number;
+/**
+ * The pending recompute is a re-ask of the same question: `refresh()` dirtied
+ * the node while no tracked input changed value. Cleared whenever a real
+ * value-change notification arrives (`insertSubs`), and consumed by
+ * `recompute` into the node's `_reask` classification — a quiet (re-ask)
+ * pending window does not read as pending (question-scoped pending model).
+ */
+export declare const REACTIVE_REASK: number;
 export declare const CONFIG_OWNED_WRITE: number;
 export declare const CONFIG_NO_SNAPSHOT: number;
 export declare const CONFIG_TRANSPARENT: number;
 export declare const CONFIG_IN_SNAPSHOT_SCOPE: number;
 export declare const CONFIG_CHILDREN_FORBIDDEN: number;
 export declare const CONFIG_AUTO_DISPOSE: number;
+export declare const CONFIG_SYNC: number;
 export declare const STATUS_NONE = 0;
 export declare const STATUS_PENDING: number;
 export declare const STATUS_ERROR: number;
@@ -25,17 +35,36 @@ export declare const EFFECT_USER = 2;
 export declare const EFFECT_TRACKED = 3;
 export declare const NOT_PENDING: {};
 export declare const NO_SNAPSHOT: {};
+/**
+ * Stand-in stored in `_overrideValue` for an optimistic write of literal
+ * `undefined` (#2898). The slot doubles as the optimistic-node brand
+ * (`undefined` = not optimistic, `NOT_PENDING` = at rest), so the raw value
+ * would erase the node's optimistic identity: the write turns invisible and
+ * follow-up writes route off the optimistic path and commit permanently.
+ * Same shape as NO_SNAPSHOT. Sites that surface the override VALUE unwrap
+ * via `visibleOverrideValue`; slot identity tests stay raw.
+ */
+export declare const OVERRIDE_UNDEFINED: {};
+/** Unwrap an active override's stored value for surfacing to readers (#2898). */
+export declare function unwrapOverride<T = any>(v: unknown): T;
 export declare const STORE_SNAPSHOT_PROPS = "sp";
 export declare const SUPPORTS_PROXY: boolean;
 export declare const defaultContext: {};
+/**
+ * Brand symbol used by `Refreshable<T>` values (projection stores, async
+ * memos) to expose their underlying computation to `refresh()`. Not part of
+ * the user-facing API.
+ *
+ * @internal
+ */
 export declare const $REFRESH: unique symbol;
 /**
- * Brand applied to derived/projected stores indicating they participate in
- * the `refresh()` re-run protocol. Use this alias instead of inlining
- * `T & { [$REFRESH]: any }` so that user-defined hooks that wrap
- * `createOptimisticStore` / `createProjection` / projection-form
- * `createStore` can have their return types inferred without leaking the
- * internal `$REFRESH` symbol into public type signatures (TS4058).
+ * Brand applied to values that participate in the `refresh()` re-run protocol.
+ * Accessors receive this handle internally; projected stores expose it through
+ * their public return type so user-defined hooks that wrap `createOptimisticStore`
+ * / `createProjection` / projection-form `createStore` can have their return
+ * types inferred without leaking the internal `$REFRESH` symbol into public type
+ * signatures (TS4058).
  */
 export type Refreshable<T> = T & {
     readonly [$REFRESH]: any;

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

@@ -14,15 +14,23 @@ export type ContextRecord = Record<string | symbol, unknown>;
  */
 export declare function createContext<T>(defaultValue?: T, description?: string): Context<T>;
 /**
- * Attempts to get a context value for the given key.
+ * Low-level owner-targeted context read. The user-facing read API is
+ * `useContext` (in `solid-js`), which wraps this primitive. Exposed here for
+ * cross-package wiring (e.g. hydration-aware context plumbing).
  *
  * @throws `NoOwnerError` if there's no owner at the time of call.
  * @throws `ContextNotFoundError` if a context value has not been set yet.
+ *
+ * @internal
  */
 export declare function getContext<T>(context: Context<T>, owner?: Owner | null): T;
 /**
- * Attempts to set a context value on the parent scope with the given key.
+ * Low-level owner-targeted context write. The user-facing API is
+ * `createContext` (in `solid-js`); its provider component wraps this
+ * primitive. Exposed here for cross-package wiring.
  *
  * @throws `NoOwnerError` if there's no owner at the time of call.
+ *
+ * @internal
  */
 export declare function setContext<T>(context: Context<T>, value?: T, owner?: Owner | null): void;

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

@@ -2,11 +2,17 @@ import { type Refreshable } from "./constants.js";
 import { type OptimisticLane } from "./lanes.js";
 import type { Computed, FirewallSignal, NodeOptions, Owner, Signal } from "./types.js";
 export declare const PRIMITIVE_IN_FORBIDDEN_SCOPE_MESSAGE = "[PRIMITIVE_IN_FORBIDDEN_SCOPE] Cannot create reactive primitives inside createTrackedEffect or owner-backed onSettled";
+export declare const REACTIVE_WRITE_IN_OWNED_SCOPE_SIGNAL_MESSAGE: string;
+export declare const REACTIVE_WRITE_IN_OWNED_SCOPE_REFRESH_MESSAGE: string;
 export declare let tracking: boolean;
+/** @internal verdict-module glue */
+export declare function setPendingCheckActive(v: boolean): void;
+/** @internal verdict-module glue */
+export declare function setLatestReadActive(v: boolean): void;
+/** @internal verdict-module glue */
+export declare function setContextInternal(v: Owner | null): void;
 export declare let stale: boolean;
-export declare let refreshing: boolean;
 export declare let pendingCheckActive: boolean;
-export declare let foundPending: boolean;
 export declare let latestReadActive: boolean;
 export declare let context: Owner | null;
 export declare let currentOptimisticLane: OptimisticLane | null;
@@ -19,6 +25,13 @@ export declare function clearSnapshots(): void;
 export declare function recompute(el: Computed<any>, create?: boolean): void;
 export declare function computed<T>(fn: (prev?: T) => T | PromiseLike<T> | AsyncIterable<T>): Computed<T>;
 export declare function computed<T>(fn: (prev: T) => T | PromiseLike<T> | AsyncIterable<T>, options?: NodeOptions<T>): Computed<T>;
+/**
+ * Build an Effect node with all effect-specific fields baked into a single object literal,
+ * so V8 sees the full hidden class shape at construction time. Effects always run in lazy
+ * mode (recompute is called explicitly by `effect()`), so we hardcode the lazy bits and skip
+ * the auto-dispose CONFIG bit (effect() previously cleared it post-construction).
+ */
+export declare function createEffectNode<T>(fn: (prev?: T) => T, effectFn: (val: T, prev: T | undefined) => void | (() => void), errorFn: ((err: unknown, cleanup: () => void) => void | (() => void)) | undefined, type: number, notifyStatus: ((status?: number, error?: any) => void) | undefined, options: NodeOptions<T> | undefined): any;
 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>;
 export declare function optimisticSignal<T>(v: T, options?: NodeOptions<T>): Signal<T>;
@@ -53,8 +66,44 @@ export declare function setStrictRead(v: string | false): string | false;
  * ```
  */
 export declare function untrack<T>(fn: () => T, strictReadLabel?: string | false): T;
+/**
+ * Bring a computed to a readable state: lazy/disposed nodes are (re)computed;
+ * an isPending() probe (`refresh`) additionally pulls the node fully up to
+ * date so its status flags reflect the current graph.
+ */
+export declare function prepareComputed(comp: Computed<unknown>, refresh: boolean): void;
+/**
+ * Sentinel returned by readNodeFast when the plain-signal fast path does not
+ * apply and the caller must fall back to the full read().
+ */
+export declare const READ_SLOW: unique symbol;
+/**
+ * read()'s plain-signal fast path as a standalone entry for hot callers
+ * (store traps). Safe to substitute for read() only because the bail
+ * conditions mirror read()'s prelude and fast-path guard exactly: the
+ * latestRead and pendingCheck windows run side-effectful hooks before the
+ * fast path, `_fn` nodes need prepareComputed, and firewall / override /
+ * snapshot / transition / lane / dev-strictRead state all take the full
+ * resolution. Anything slow returns READ_SLOW; the caller then calls read().
+ */
+export declare function readNodeFast<T>(el: Signal<T>): T | typeof READ_SLOW;
 export declare function read<T>(el: Signal<T> | Computed<T>): T;
 export declare function setSignal<T>(el: Signal<T> | Computed<T>, v: T | ((prev: T) => T)): T;
+/**
+ * Suppresses automatic recomputation of `el` until the scheduler drains. Used
+ * when a manual write should win over dependency changes queued in the same
+ * tick. The MANUAL_WRITE flag is cleared by the pending-node drain; projection
+ * computeds don't commit values, but they still need the same end-of-tick
+ * cleanup point.
+ */
+export declare function suppressComputedRecompute(el: Computed<unknown>): void;
+/**
+ * User-facing setter for the memo form of `createSignal(fn)`. Behaves like
+ * `setSignal`, but also cancels any pending recompute of the memo so the
+ * manual value wins over a value that would otherwise be produced by an
+ * upstream change in the same tick.
+ */
+export declare function setMemo<T>(el: Computed<T>, v: T | ((prev: T) => T)): T;
 /**
  * Executes `fn` with the given `owner` set as the current owner. Any reactive
  * primitives (`createSignal`, `createMemo`, `createEffect`, `onCleanup`,
@@ -75,56 +124,15 @@ export declare function setSignal<T>(el: Signal<T> | Computed<T>, v: T | ((prev:
  * ```
  */
 export declare function runWithOwner<T>(owner: Owner | null, fn: () => T): T;
-/**
- * Update _pendingSignal when pending state changes. When the override clears
- * (pending -> not pending), merge the sub-lane into the source's lane so
- * isPending effects are blocked until the full scope resolves.
- */
-export declare function updatePendingSignal(el: Signal<any> | Computed<any>): void;
 export declare function staleValues<T>(fn: () => T, set?: boolean): T;
 /**
- * Reads reactive expressions while bypassing any pending async overlay — i.e.
- * always returns the most-recently-committed value, even when newer reads
- * inside `fn` are still in flight.
- *
- * Useful inside a `<Loading>` boundary's children when you want to keep
- * showing the previous resolved data instead of the fallback while the next
- * value loads.
- *
- * @example
- * ```tsx
- * <Loading fallback={<Skeleton />}>
- *   {/* During a transition, render the previous user instead of skeleton: *\/}
- *   <UserCard user={latest(() => user())} />
- * </Loading>
- * ```
- */
-export declare function latest<T>(fn: () => T): T;
-/**
- * Returns `true` if any reactive read inside `fn` is currently in a pending
- * (async, not-yet-settled) state. Does not subscribe — pair with a tracked
- * memo if you want to react to pending status changes.
- *
- * Useful for showing inline transition indicators alongside the previous
- * value (rather than swapping to a `<Loading>` fallback).
- *
- * @example
- * ```tsx
- * const pending = createMemo(() => isPending(() => user()));
- *
- * <button disabled={pending()}>{pending() ? "Saving…" : "Save"}</button>
- * ```
- */
-export declare function isPending(fn: () => any): boolean;
-/**
- * Forces a reactive source to re-execute, even if its inputs haven't changed.
+ * Invalidates one reactive source, forcing it to re-execute even if its inputs
+ * haven't changed.
  *
- * Two forms:
- * - `refresh(memo)` — pass an accessor (memo / signal getter) and its
- *   underlying computation reruns.
- * - `refresh(store)` — pass a *projected* store created from
- *   `createStore(fn, ...)` or `createProjection(...)` and the projection
- *   recomputes.
+ * Pass either a Solid-created accessor or a projected store created from
+ * `createStore(fn, ...)` / `createProjection(...)`. `refresh()` is a
+ * write-like invalidation operation: it does not read the target's value, and
+ * refreshing a plain signal accessor is a no-op.
  *
  * Use it to invalidate cached async values (e.g. force a re-fetch) without
  * tearing the consumer down.
@@ -137,17 +145,4 @@ export declare function isPending(fn: () => any): boolean;
  * <button onClick={() => refresh(user)}>Reload</button>
  * ```
  */
-export declare function refresh<T>(fn: (() => T) | Refreshable<T>): T;
-/**
- * Returns `true` while a `refresh()` call is in progress. Useful for showing
- * a "refreshing" indicator distinct from the initial-load `<Loading>`
- * fallback.
- *
- * @example
- * ```tsx
- * <Show when={isRefreshing()}>
- *   <span class="badge">refreshing…</span>
- * </Show>
- * ```
- */
-export declare function isRefreshing(): boolean;
+export declare function refresh<T>(target: Refreshable<T>): void;

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

@@ -6,8 +6,8 @@ export interface DevHooks {
     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" | "SIGNAL_WRITE_IN_OWNED_SCOPE" | "RUN_WITH_DISPOSED_OWNER" | "NO_OWNER_CLEANUP" | "CLEANUP_IN_FORBIDDEN_SCOPE" | "PRIMITIVE_IN_FORBIDDEN_SCOPE" | "NO_OWNER_EFFECT" | "NO_OWNER_BOUNDARY" | "ASYNC_OUTSIDE_LOADING_BOUNDARY" | "MISSING_EFFECT_FN";
-export type DiagnosticKind = "strict-read" | "async" | "write" | "lifecycle" | "owner";
+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" | "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";
+export type DiagnosticKind = "strict-read" | "async" | "write" | "lifecycle" | "owner" | "error";
 export interface DiagnosticEvent {
     sequence: number;
     code: DiagnosticCode;
@@ -39,7 +39,22 @@ export interface Dev {
     getObservers: typeof getObservers;
 }
 export declare const DEV: Dev;
+/**
+ * Dev-mode internal consistency check. A failure means the reactive system
+ * contradicted itself (not that user code misbehaved) — see
+ * INTERNALS-ASYNC-STATE.md for the invariant catalog. Throws under __TEST__
+ * so the suite (and fuzzing) treats any violation as a hard failure; logs in
+ * 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;
+/**
+ * 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 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/effect.d.ts

@@ -2,10 +2,10 @@ import type { Computed, NodeOptions, Owner } from "./types.js";
 export interface Effect<T> extends Computed<T>, Owner {
     _effectFn: (val: T, prev: T | undefined) => void | (() => void);
     _errorFn?: (err: unknown, cleanup: () => void) => void;
-    _cleanup?: () => void;
     _modified: boolean;
     _prevValue: T | undefined;
     _type: number;
+    _boundRunEffect?: () => void;
 }
 /**
  * Effects are the leaf nodes of our reactive graph. When their sources change, they are
@@ -18,7 +18,6 @@ export declare function effect<T>(compute: (prev: T | undefined) => T, effect: (
     schedule?: boolean;
 }): void;
 export interface TrackedEffect extends Computed<void> {
-    _cleanup?: () => void;
     _modified: boolean;
     _type: number;
     _run: () => void;

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

@@ -1,4 +1,35 @@
+/**
+ * Thrown by a tracked read whose value is currently pending (an async memo /
+ * `createSignal(asyncFn)` / projection / store derivation that hasn't settled
+ * yet). Surfacing through the reactive graph is what suspends the consumer
+ * scope — the nearest enclosing `<Loading>` boundary catches the throw and
+ * renders its fallback until the source resolves.
+ *
+ * App code rarely catches this directly; `<Loading>` is the canonical
+ * handler. The error type is exposed for advanced cases — e.g. interop layers
+ * that bridge Solid's pending-throw protocol to a different async strategy,
+ * or tests that want to assert on the suspension shape.
+ *
+ * @example
+ * ```ts
+ * // Advanced: distinguish "not ready yet" from a real error in custom
+ * // boundary plumbing. App code should rely on `<Loading>` / `<Errored>`.
+ * try {
+ *   const value = readReactiveSource();
+ * } catch (err) {
+ *   if (err instanceof NotReadyError) throw err; // re-throw to suspend
+ *   reportError(err);
+ * }
+ * ```
+ */
 export declare class NotReadyError extends Error {
+    /**
+     * Tags a visibility-only notification on the affects() boundary channel:
+     * boundaries update display state from it, but the root queue never
+     * registers a reporter — marks are invisible to completion accounting by
+     * construction.
+     */
+    _markVisual?: boolean;
     source: any;
     constructor(source: any);
 }
@@ -6,6 +37,8 @@ export declare class StatusError extends Error {
     source: any;
     constructor(source: any, original: any);
 }
+/** Return the user's error from an internal status wrapper. */
+export declare function unwrapStatusError(error: unknown): unknown;
 export declare class NoOwnerError extends Error {
     constructor();
 }

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

@@ -11,16 +11,5 @@ export declare let externalSourceConfig: {
     factory: ExternalSourceFactory;
     untrack: <T>(fn: () => T) => T;
 } | null;
-/**
- * Registers a factory that bridges external reactive systems (e.g. MobX, Vue refs)
- * into Solid's tracking graph. Every computation will be wrapped so that the
- * external library can track its own dependencies alongside Solid's.
- *
- * Multiple calls pipe together: each new factory wraps the previous one.
- *
- * @param config.factory receives `(fn, trigger)` — wrap fn execution in external tracking,
- *   call trigger when external deps change. Return `{ track, dispose }`.
- * @param config.untrack optional wrapper for `untrack` — disables external tracking too.
- */
 export declare function enableExternalSource(config: ExternalSourceConfig): void;
 export declare function _resetExternalSourceConfig(): void;

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

@@ -1,4 +1,5 @@
 import type { Computed, Link, Signal } from "./types.js";
 export declare function unlinkSubs(link: Link): Link | null;
+export declare function trimStaleDeps(el: Computed<any>): void;
 export declare function unobserved(el: Computed<unknown>): void;
-export declare function link(dep: Signal<any> | Computed<any>, sub: Computed<any>): void;
+export declare function link(dep: Signal<any> | Computed<any>, sub: Computed<any>, pendingObserver?: boolean): void;

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

@@ -1,4 +1,12 @@
 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.
+ */
+export declare function enqueueSub(node: Computed<any>): void;
 export interface Heap {
     _heap: (Computed<unknown> | undefined)[];
     _marked: boolean;

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

@@ -1,12 +1,13 @@
 export { ContextNotFoundError, NoOwnerError, NotReadyError } from "./error.js";
-export { isEqual, untrack, runWithOwner, computed, signal, read, setSignal, optimisticSignal, optimisticComputed, isPending, latest, refresh, isRefreshing, staleValues, setSnapshotCapture, markSnapshotScope, releaseSnapshotScope, clearSnapshots } from "./core.js";
+export { isEqual, untrack, runWithOwner, computed, signal, read, setSignal, setMemo, suppressComputedRecompute, optimisticSignal, optimisticComputed, refresh, staleValues, setSnapshotCapture, markSnapshotScope, releaseSnapshotScope, clearSnapshots } from "./core.js";
 export { enableExternalSource, _resetExternalSourceConfig, type ExternalSourceFactory, type ExternalSource, type ExternalSourceConfig } from "./external.js";
 export { createOwner, createRoot, dispose, getNextChildId, getObserver, getOwner, isDisposed, cleanup, peekNextChildId } from "./owner.js";
 export { createContext, getContext, setContext, type Context, type ContextRecord } from "./context.js";
 export { handleAsync } from "./async.js";
+export { isPending, latest } from "./verdict.js";
 export type { Computed, Disposable, FirewallSignal, Link, Owner, Root, Signal, NodeOptions } from "./types.js";
 export { effect, trackedEffect, type Effect, type TrackedEffect } from "./effect.js";
 export { action } from "./action.js";
-export { flush, Queue, GlobalQueue, trackOptimisticStore, enforceLoadingBoundary, type IQueue, type QueueCallback } from "./scheduler.js";
+export { flush, Queue, GlobalQueue, enforceLoadingBoundary, resetErrorHalt, type IQueue, type QueueCallback } from "./scheduler.js";
 export { DEV, type Dev, type DevHooks, type DiagnosticCapture, type DiagnosticCode, type DiagnosticEvent, type DiagnosticKind, type Diagnostics, type DiagnosticSeverity } from "./dev.js";
 export * from "./constants.js";

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

@@ -0,0 +1,59 @@
+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/solid-signals/INTERNALS-ASYNC-STATE.md.
+ *
+ * These are implementation self-consistency checks, not semantic rules: a
+ * violation means the reactive system contradicted itself.
+ *
+ * They are gated on `__TEST__` (not just `__DEV__`): the per-write Set
+ * tracking and per-flush quiescence sweep are too expensive for shipped dev
+ * builds and for benchmarks (they showed up as a 5-21% hit across the
+ * CodSpeed suite when they ran under `__DEV__`). Call sites stay `__DEV__`
+ * guarded so production tree-shakes the calls; each entry point here
+ * early-returns unless `__TEST__` is set, so dev builds pay only a no-op
+ * call. The test suite (vitest run) defines `__TEST__: true`; benchmark mode
+ * defines `__TEST__: false`.
+ */
+type AnyNode = Signal<any> | Computed<any>;
+/** Wired by core.ts at module init to avoid import cycles. */
+export declare const InvariantHooks: {
+    pendingProbeActive: (() => boolean) | null;
+    /** Fresh oracle for what an isPending companion SHOULD read right now. */
+    computePendingState: ((node: AnyNode) => boolean) | null;
+};
+export declare function devTrackHeldPending(node: AnyNode): void;
+export declare function devTrackCompanionOwner(node: AnyNode): void;
+export declare function devTrackOptimistic(node: AnyNode): void;
+export declare function devTrackAffects(node: AnyNode): void;
+/**
+ * Open/close the sanctioned registration window. Call sites are `__DEV__`
+ * guarded (no prod cost); the code inside the window must not throw.
+ */
+export declare function beginAsyncReporterWrites(): void;
+export declare function endAsyncReporterWrites(): void;
+export declare function createAsyncReporters(): Map<Computed<any>, Set<Computed<any>>>;
+/**
+ * INV-2: a node with an *active* override must be registered for reversion in
+ * the queue's or a transition's `_optimisticNodes`. An unregistered active
+ * override would survive transition completion forever. Runs at the end of
+ * every flush (not just quiescence — the invariant holds mid-transition).
+ * (There is no revert-target requirement: authoritative values commit
+ * silently into `_value` under the override mask — A17 — so reverting is
+ * just dropping the override.)
+ */
+export declare function devCheckActiveOverrides(isRegisteredForRevert: (node: AnyNode) => boolean): void;
+/** INV-1: an isPending() probe must never leak past its own call. */
+export declare function devCheckFlushStart(): void;
+/** INV-5: a merged lane's work moved to its root on merge and must stay empty. */
+export declare function devCheckMergedLaneEmpty(lane: OptimisticLane): void;
+export declare function devCensusCompanions(isQueuedForCommit?: (node: AnyNode) => boolean): void;
+/**
+ * Quiescence checks. Run only when the system is fully drained: nothing
+ * scheduled, no active/stashed transitions, no live lanes. At that point no
+ * transition-scoped state may survive, and the lazily-created companions must
+ * agree with a fresh computation of their owner's state.
+ */
+export declare function devCheckQuiescent(isQueuedForCommit: (node: AnyNode) => boolean): void;
+export {};

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

@@ -37,6 +37,8 @@ export declare function resolveLane(el: {
 export declare function resolveTransition(el: {
     _optimisticLane?: OptimisticLane;
     _transition?: Transition | null;
+    _overrideValue?: any;
+    _overrideOwner?: Transition | null;
 }): Transition | null | undefined;
 /**
  * Check if a node has an active optimistic override.

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

@@ -0,0 +1,6 @@
+/**
+ * Installs the engine's hooks. Idempotent; called by every module that can
+ * create optimistic state (verdict.ts at module top level, createOptimistic
+ * and createOptimisticStore at first call) BEFORE any optimistic node exists.
+ */
+export declare function installOptimisticEngine(): void;

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

@@ -2,7 +2,27 @@ import type { Computed, Disposable, Owner, Root } from "./types.js";
 export declare function markDisposal(el: Owner): void;
 export declare function dispose(node: Computed<unknown>): void;
 export declare function disposeChildren(node: Owner, self?: boolean, zombie?: boolean): void;
+/**
+ * Allocates and returns the next stable child id for `owner`. Used by
+ * hydration plumbing and `createUniqueId`. Not part of the user-facing API.
+ *
+ * @internal
+ */
 export declare function getNextChildId(owner: Owner): string;
+/**
+ * The id a freshly-created node inherits: an explicit `options.id` wins;
+ * transparent nodes share their parent's id; otherwise the parent's next
+ * child id is consumed (or `undefined` outside an id-carrying tree).
+ */
+export declare function inheritId(options: {
+    id?: string;
+} | undefined, transparent: boolean, parent: Owner | null | undefined): string | undefined;
+/**
+ * Returns the *next* child id for `owner` without consuming it. Used by
+ * hydration plumbing to peek at the id a future child will receive.
+ *
+ * @internal
+ */
 export declare function peekNextChildId(owner: Owner): string;
 /**
  * Returns the currently-tracking observer (the computation that subscribes to
@@ -10,6 +30,15 @@ export declare function peekNextChildId(owner: Owner): string;
  * Used by reactive primitives that need to know whether they're inside a
  * tracking scope. App code rarely needs this — see `getOwner()` for the
  * lifecycle owner instead.
+ *
+ * @example
+ * ```ts
+ * // Library predicate: only register a hot-path subscription when the
+ * // caller is inside a tracking scope (memo / effect compute / JSX).
+ * function trackIfTracked(source: () => unknown) {
+ *   if (getObserver()) source();
+ * }
+ * ```
  */
 export declare function getObserver(): Owner | null;
 /**
@@ -36,12 +65,30 @@ export declare function getOwner(): Owner | null;
  * checks. `cleanup()` is the unchecked primitive used by internals.
  */
 export declare function cleanup(fn: Disposable): Disposable;
-/** Returns `true` if the owner has been disposed (or marked zombie pending disposal). */
+/**
+ * Returns `true` if the owner has been disposed (or marked zombie pending
+ * disposal). Pair with a captured owner to bail out of late callbacks whose
+ * surrounding component already unmounted.
+ *
+ * @example
+ * ```ts
+ * function onSettleSafe(fn: () => void) {
+ *   const owner = getOwner();
+ *   queueMicrotask(() => {
+ *     if (owner && isDisposed(owner)) return; // component unmounted; skip
+ *     runWithOwner(owner, fn);
+ *   });
+ * }
+ * ```
+ */
 export declare function isDisposed(node: Owner): boolean;
 /**
  * Creates a fresh owner attached as a child of the current owner (or as a
- * detached root if there is none). Mostly used by framework internals to
- * group cleanups; app code should prefer `createRoot()` or `runWithOwner()`.
+ * detached root if there is none). Used by framework internals to group
+ * cleanups; app code should use `createRoot()` (host a reactive scope outside
+ * a component) or `runWithOwner()` (re-enter a captured owner).
+ *
+ * @internal
  */
 export declare function createOwner(options?: {
     id?: string;