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

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

@@ -1,5 +1,5 @@
 import { type Heap } from "./heap.js";
-import { activeLanes, assignOrMergeLane, findLane } from "./lanes.js";
+import { activeLanes, assignOrMergeLane, findLane, type OptimisticLane } from "./lanes.js";
 import type { Computed, Signal } from "./types.js";
 export { activeLanes, assignOrMergeLane, findLane };
 export { getOrCreateLane, hasActiveOverride, mergeLanes, resolveLane } from "./lanes.js";
@@ -11,8 +11,15 @@ export declare let projectionWriteActive: boolean;
 export declare let _hitUnhandledAsync: boolean;
 export declare function registerTransientStoreNode(node: Signal<any>): void;
 export declare function resetUnhandledAsync(): void;
+/**
+ * Toggles the dev-mode "must be inside a `<Loading>` boundary" enforcement
+ * window. Only `render()` calls this — wrapping the initial mount so that a
+ * top-level uncaught async read surfaces the diagnostic. Not part of the
+ * user-facing API.
+ *
+ * @internal
+ */
 export declare function enforceLoadingBoundary(enabled: boolean): void;
-export declare function shouldReadStashedOptimisticValue(node: Signal<any>): boolean;
 export declare function setProjectionWriteActive(value: boolean): void;
 export declare function setTrackedQueueCallback(value: boolean): void;
 export type QueueCallback = (type: number) => void;
@@ -26,6 +33,7 @@ export interface Transition {
     _asyncReporters: Map<Computed<any>, Set<Computed<any>>>;
     _pendingNodes: Signal<any>[];
     _optimisticNodes: OptimisticNode[];
+    _affectsNodes: OptimisticNode[];
     _optimisticStores: Set<any>;
     _actions: Array<Generator<any, any, any> | AsyncGenerator<any, any, any>>;
     _queueStash: QueueStub;
@@ -33,6 +41,14 @@ export interface Transition {
     _gatedSubs: Set<Computed<any>>;
 }
 export declare function schedule(): void;
+/**
+ * Permanently halts the reactive system. Called when a user error escapes
+ * every boundary — app state is undefined at that point, so scheduling stops
+ * entirely rather than limping along with a half-applied update.
+ */
+export declare function haltReactivity(cause?: unknown): void;
+/** @internal Test/dev-reload hook. Revives scheduling after a halt. */
+export declare function resetErrorHalt(): void;
 export interface IQueue {
     enqueue(type: number, fn: QueueCallback): void;
     run(type: number): boolean | void;
@@ -48,6 +64,7 @@ export declare class Queue implements IQueue {
     _parent: IQueue | null;
     _queues: [QueueCallback[], QueueCallback[]];
     _children: IQueue[];
+    _ranAt: number;
     created: number;
     addChild(child: IQueue): void;
     removeChild(child: IQueue): void;
@@ -59,28 +76,72 @@ export declare class Queue implements IQueue {
 }
 export declare class GlobalQueue extends Queue {
     _running: boolean;
-    _pendingNodes: Signal<any>[];
-    _optimisticNodes: OptimisticNode[];
-    _optimisticStores: Set<any>;
+    _batch: Transition;
     static _update: (el: Computed<unknown>) => void;
     static _dispose: (el: Computed<unknown>, self: boolean, zombie: boolean) => void;
-    static _clearOptimisticStore: ((store: any) => void) | null;
+    static _runEffect: (el: Computed<unknown>) => void;
+    static _clearOptimisticStores: ((stores: Set<any>, completing: Transition | null) => void) | null;
+    static _releaseAffectsScope: ((node: OptimisticNode) => void) | null;
+    static _releaseAffectsMarks: ((nodes: OptimisticNode[]) => void) | null;
+    static _markAffects: ((node: OptimisticNode) => void) | null;
+    static _releaseAffectsMark: ((node: OptimisticNode) => void) | null;
+    static _wireExternalSource: ((self: Computed<any>) => void) | null;
+    static _externalUntrack: (<T>(fn: () => T) => T) | null;
+    static _syncCompanions: (<T>(el: Signal<T> | Computed<T>, value: T) => void) | null;
+    static _updatePendingSignal: ((el: OptimisticNode) => void) | null;
+    static _updateChildCompanions: ((el: Computed<any>) => void) | null;
+    static _snapCompanions: ((el: OptimisticNode) => void) | null;
+    static _latestRead: (<T>(el: Signal<T> | Computed<T>) => T) | null;
+    static _pendingCheck: ((el: OptimisticNode, c: Computed<any> | null, owner: OptimisticNode, firewall: Computed<any> | null) => void) | null;
+    static _recordFresh: ((el: OptimisticNode, value: any) => void) | null;
+    static _applyReask: ((el: Computed<any>, hadReask: boolean) => boolean) | null;
+    static _repollVerdicts: ((el: Computed<any>, snap?: boolean) => void) | null;
+    static _witnessAffects: ((node: OptimisticNode) => void) | null;
+    static _optimisticWrite: (<T>(el: Signal<T> | Computed<T>, v: T | ((prev: T) => T)) => T) | null;
+    static _resolveOptimistic: ((nodes: OptimisticNode[]) => void) | null;
+    static _transitionBlocked: ((transition: Transition) => boolean) | null;
+    static _cleanupLanes: ((completingTransition: Transition | null) => void) | null;
+    static _runLaneEffects: ((type: number) => void) | null;
+    static _gatedRead: ((el: Signal<any>, owner: OptimisticNode, c: Computed<any>) => boolean) | null;
+    static _laneSuspends: ((owner: OptimisticNode) => boolean) | null;
+    static _laneReadsCommitted: ((el: OptimisticNode, owner: OptimisticNode, c: Computed<any>) => boolean) | null;
+    static _recomputeLane: ((el: Computed<any>, own: boolean) => OptimisticLane | null) | null;
+    static _laneAsyncPending: ((el: Computed<any>) => void) | null;
+    static _laneAsyncSettled: ((el: Computed<any>) => void) | null;
+    static _trackOptimisticStore: ((store: any) => void) | null;
     flush(): void;
     notify(node: Computed<any>, mask: number, flags: number, error?: any): boolean;
     initTransition(transition?: Transition | null): void;
 }
+export declare function queuePendingNode(node: Signal<any>): void;
+export declare function armReaskClear(): void;
 export declare function insertSubs(node: Signal<any> | Computed<any>, optimistic?: boolean): void;
 export declare function finalizePureQueue(completingTransition?: Transition | null, incomplete?: boolean): void;
-export declare function trackOptimisticStore(store: any): void;
+/**
+ * Count of live `affects()` registrations across the system (including
+ * store-scope inherited marks). Gates the read-path mark check in `read()` so
+ * graphs that never use the feature pay one integer compare.
+ */
+export declare let activeAffectsMarks: number;
+/**
+ * Counter mutation seam for the mark engine in affects.ts: an imported `let`
+ * binding is read-only, and the read-path gate above must stay a plain module
+ * variable so `read()` pays one integer compare, not a function call.
+ *
+ * @internal
+ */
+export declare function shiftAffectsMarks(delta: 1 | -1): void;
 export declare const globalQueue: GlobalQueue;
 /**
- * Synchronously processes the pending reactive queue: runs every scheduled
- * memo/effect/computation that has dirty inputs, until the graph is settled.
+ * Synchronously processes the pending reactive queue, or runs `fn` in a synchronous
+ * flush scope before draining the queue.
  *
  * Reactive updates are normally batched onto the microtask queue, so multiple
  * writes in a row collapse into a single update pass. Call `flush()` when you
  * need to *observe* the result of those writes synchronously — most commonly
- * in tests, but also at the boundary of imperative integration code.
+ * in tests, but also at the boundary of imperative integration code. Pass a
+ * callback when the writes themselves should bypass microtask scheduling and
+ * drain synchronously when the callback returns.
  *
  * @example
  * ```ts
@@ -90,9 +151,20 @@ export declare const globalQueue: GlobalQueue;
  * setCount(5);
  * flush();
  * expect(doubled()).toBe(10);
+ *
+ * flush(() => setCount(6));
+ * expect(doubled()).toBe(12);
+ *
+ * // Nested flushes drain at each level:
+ * flush(() => {
+ *   setCount(7);
+ *   flush(() => setCount(8)); // inner drain — effects fire here
+ *   // outer continues with up-to-date state
+ * });
  * ```
  */
 export declare function flush(): void;
+export declare function flush<T>(fn: () => T): T;
 export declare function currentTransition(transition: Transition): Transition;
 export declare function setActiveTransition(transition: Transition | null): void;
 export declare function runInTransition<T>(transition: Transition, fn: () => T): T;

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

@@ -10,6 +10,14 @@ export interface Link {
     _nextDep: Link | null;
     _prevSub: Link | null;
     _nextSub: Link | null;
+    /**
+     * `_sub._depGen` at the time this link was created or last revalidated
+     * in-order. A link stamped with the subscriber's current pass generation is
+     * inside the validated `[deps.._depsTail]` prefix — an O(1) replacement for
+     * scanning the dep list to answer membership (see `link()`).
+     */
+    _gen: number;
+    _pendingObserver?: boolean;
 }
 export interface NodeOptions<T> {
     id?: string;
@@ -21,6 +29,17 @@ export interface NodeOptions<T> {
     _noSnapshot?: boolean;
     unobserved?: () => void;
     lazy?: boolean;
+    sync?: boolean;
+    /**
+     * Commit #0. When present (checked with `in`, so an explicit `undefined`
+     * counts), the node is born committed with this value instead of
+     * STATUS_UNINITIALIZED: reads serve it everywhere, nothing suspends to
+     * Loading boundaries, transitions are never held, and the window is
+     * verdict-quiet (`isPending` stays false — commit #0 answers the question
+     * by declaration; first-load affordances live in the value itself). After
+     * the first real answer lands, normal refetch/pending semantics apply.
+     */
+    loadingValue?: T;
 }
 export interface RawSignal<T> {
     _subs: Link | null;
@@ -35,10 +54,29 @@ export interface RawSignal<T> {
     _transition: Transition | null;
     _pendingValue: T | typeof NOT_PENDING;
     _overrideValue?: T | typeof NOT_PENDING;
+    /**
+     * The transaction that owns the active override (stamped at optimistic
+     * write, cleared at settle). Ownership must live on the node: a lane's
+     * _transition is a scheduling affinity that a shared subscriber can merge
+     * across transactions (#2912) — following it would let one action's settle
+     * revert another action's live override. Node-level sibling of the store
+     * layer's STORE_OPTIMISTIC_OWNERS stamps (#2899). `null` = ambient write.
+     */
+    _overrideOwner?: Transition | null;
     _optimisticLane?: OptimisticLane;
     _pendingSignal?: Signal<boolean>;
     _latestValueComputed?: Computed<T>;
     _parentSource?: Signal<any> | Computed<any>;
+    /**
+     * Live `affects()` marks on this node (refcount). Non-zero is declared
+     * motion: the node — and, via the verdict layer's dep-graph coverage walk,
+     * everything derived from it — reads pending regardless of graph state,
+     * until every declaring transaction settles/reverts and releases its mark.
+     * This count is the mark's ONLY graph state: the dedicated channel stores
+     * nothing downstream and never touches status flags, errors, or pending
+     * sources.
+     */
+    _affectsCount?: number;
 }
 export interface FirewallSignal<T> extends RawSignal<T> {
     _firewall: Computed<any>;
@@ -49,6 +87,8 @@ export interface Owner {
     id?: string;
     _config: number;
     _snapshotScope?: boolean;
+    /** Effect-returned cleanup; managed across reruns, invoked at true disposal */
+    _cleanup?: () => void;
     _disposal: Disposable | Disposable[] | null;
     _parent: Owner | null;
     _context: Record<symbol | string, unknown>;
@@ -56,15 +96,17 @@ export interface Owner {
     _queue: IQueue;
     _firstChild: Owner | null;
     _nextSibling: Owner | null;
+    _prevSibling: Owner | null;
     _pendingDisposal: Disposable | Disposable[] | null;
     _pendingFirstChild: Owner | null;
 }
 export interface Computed<T> extends RawSignal<T>, Owner {
     _deps: Link | null;
     _depsTail: Link | null;
+    /** Recompute-pass counter; bumped when dep revalidation starts. */
+    _depGen: number;
     _flags: number;
     _blocked?: boolean;
-    _pendingSource?: Computed<any>;
     _pendingSources?: Set<Computed<any>>;
     _error?: unknown;
     _statusFlags: number;
@@ -75,6 +117,29 @@ export interface Computed<T> extends RawSignal<T>, Owner {
     _inFlight: PromiseLike<T> | AsyncIterable<T> | null;
     _child: FirewallSignal<any> | null;
     _notifyStatus?: (status?: number, error?: any) => void;
+    /**
+     * Question-scoped pending classification of the node's CURRENT pending
+     * window: `true` means the in-flight recompute is a re-ask of the same
+     * question (refresh/poll/confirm — no tracked input changed value), so the
+     * shown answer still answers the question and the node reads NOT pending.
+     * Set by `recompute` from `REACTIVE_REASK`, cleared on landing
+     * (`clearStatus`). Meaningless while not STATUS_PENDING.
+     */
+    _reask: boolean;
+    /**
+     * True while a `loadingValue` node's first real answer hasn't landed: the
+     * node was born committed (commit #0 = the loading value) and `handleAsync`
+     * serves that committed value instead of throwing NotReadyError, so first
+     * flights never suspend readers, trip boundaries, or hold transitions.
+     * The window is verdict-quiet: `isPending` stays false, because commit #0
+     * answers the question by declaration (first-load affordances belong to
+     * the value channel). Cleared by the first value landing on any path (sync
+     * return, sync-resolved promise, first iterator yield, async settle); a
+     * real error leaves it set — errors answer reads but don't enter the value
+     * lineage, so a retry serves the loading value again. Once cleared, normal
+     * pending/refetch semantics apply forever.
+     */
+    _loading: boolean;
 }
 export interface Root extends Owner {
     _root: true;

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

@@ -0,0 +1,2 @@
+export declare function latest<T>(fn: () => T): T;
+export declare function isPending(fn: () => any): boolean;

package/dist/types/index.d.ts

@@ -1,9 +1,10 @@
-export { $REFRESH, ContextNotFoundError, NoOwnerError, NotReadyError, action, createContext, createOwner, createRoot, runWithOwner, flush, getNextChildId, peekNextChildId, getContext, setContext, getOwner, isDisposed, getObserver, isEqual, untrack, isPending, latest, isRefreshing, refresh, SUPPORTS_PROXY, setSnapshotCapture, markSnapshotScope, releaseSnapshotScope, clearSnapshots, enforceLoadingBoundary, enableExternalSource } from "./core/index.js";
+export { $REFRESH, ContextNotFoundError, NoOwnerError, NotReadyError, action, createContext, createOwner, createRoot, runWithOwner, flush, getNextChildId, peekNextChildId, getContext, setContext, getOwner, isDisposed, getObserver, isEqual, untrack, isPending, latest, refresh, SUPPORTS_PROXY, setSnapshotCapture, markSnapshotScope, releaseSnapshotScope, clearSnapshots, enforceLoadingBoundary, enableExternalSource, resetErrorHalt } from "./core/index.js";
 import { type Dev } from "./core/index.js";
 export declare const DEV: Dev | undefined;
 export type { Owner, Context, ContextRecord, IQueue, ExternalSourceFactory, ExternalSource, ExternalSourceConfig, Refreshable, Dev, DevHooks, DiagnosticCapture, DiagnosticCode, DiagnosticEvent, DiagnosticKind, Diagnostics, DiagnosticSeverity } from "./core/index.js";
 export { createSignal, createMemo, createEffect, createRenderEffect, createTrackedEffect, createReaction, createOptimistic, resolve, onSettled, onCleanup } from "./signals.js";
-export type { Accessor, Setter, Signal, ComputeFunction, EffectFunction, EffectBundle, EffectOptions, SignalOptions, MemoOptions, NoInfer } from "./signals.js";
+export type { Accessor, SourceAccessor, Setter, Signal, ComputeFunction, EffectFunction, EffectBundle, EffectOptions, SignalOptions, MemoOptions, NoInfer } from "./signals.js";
+export { affects } from "./affects.js";
 export { mapArray, repeat, type Maybe } from "./map.js";
 export * from "./store/index.js";
 export { createLoadingBoundary, createErrorBoundary, createRevealOrder, flatten, type RevealOrder } from "./boundaries.js";

package/dist/types/map.d.ts

@@ -2,8 +2,14 @@ import { type Accessor } from "./signals.js";
 export type Maybe<T> = T | void | null | undefined | false;
 /**
  * Reactively maps an array, reusing the previously-mapped value for unchanged
- * items. The callback receives `(value, index)` as accessors so individual
- * items and indexes can be subscribed to without re-running the mapper.
+ * items.
+ *
+ * The callback shape follows the keying mode:
+ * - default / `keyed: true` receives `(item, index)` where `item` is the raw
+ *   row value and `index` is an accessor.
+ * - `keyed: false` receives `(item, index)` where `item` is an accessor and
+ *   `index` is a stable number.
+ * - `keyed: item => key` receives accessors for both arguments.
  *
  * This is the underlying helper that powers `<For>`. App code should use
  * `<For>` directly; reach for `mapArray` when implementing custom list
@@ -19,15 +25,25 @@ export type Maybe<T> = T | void | null | undefined | false;
  * ```ts
  * const view = mapArray(
  *   items,
- *   (item, index) => `${index()}: ${item().label}`,
+ *   (item, index) => `${index()}: ${item.label}`,
  *   { fallback: () => "no items" }
  * );
  * ```
  *
  * @description https://docs.solidjs.com/reference/reactive-utilities/map-array
  */
-export declare function mapArray<Item, MappedItem>(list: Accessor<Maybe<readonly Item[]>>, map: (value: Accessor<Item>, index: Accessor<number>) => MappedItem, options?: {
-    keyed?: boolean | ((item: Item) => any);
+export declare function mapArray<Item, MappedItem>(list: Accessor<Maybe<readonly Item[]>>, map: (value: Item, index: Accessor<number>) => MappedItem, options?: {
+    keyed?: true;
+    fallback?: Accessor<any>;
+    name?: string;
+}): Accessor<MappedItem[]>;
+export declare function mapArray<Item, MappedItem>(list: Accessor<Maybe<readonly Item[]>>, map: (value: Accessor<Item>, index: number) => MappedItem, options: {
+    keyed: false;
+    fallback?: Accessor<any>;
+    name?: string;
+}): Accessor<MappedItem[]>;
+export declare function mapArray<Item, MappedItem>(list: Accessor<Maybe<readonly Item[]>>, map: (value: Accessor<Item>, index: Accessor<number>) => MappedItem, options: {
+    keyed: (item: Item) => any;
     fallback?: Accessor<any>;
     name?: string;
 }): Accessor<MappedItem[]>;

package/dist/types/signals.d.ts

@@ -1,4 +1,4 @@
-import type { Disposable } from "./core/index.js";
+import type { Disposable, Refreshable } from "./core/index.js";
 /**
  * Low-level reactive-cleanup primitive. Registers a callback that runs when
  * the surrounding owner is disposed.
@@ -25,6 +25,18 @@ import type { Disposable } from "./core/index.js";
  *
  * Cannot be used inside `createTrackedEffect` or `onSettled` — return a
  * cleanup function from the callback body instead.
+ *
+ * @example
+ * ```ts
+ * // Library shape: thread a resource's disposal into a *captured* owner
+ * // from a factory that has no settle-phase setup of its own. `onSettled`
+ * // would queue a callback we don't need; `onCleanup` is the leaner
+ * // primitive when the only job is "register disposal on this owner".
+ * function bindToOwner<T extends { dispose(): void }>(owner: Owner, resource: T): T {
+ *   runWithOwner(owner, () => onCleanup(() => resource.dispose()));
+ *   return resource;
+ * }
+ * ```
  */
 export declare function onCleanup(fn: Disposable): Disposable;
 /**
@@ -35,7 +47,8 @@ export declare function onCleanup(fn: Disposable): Disposable;
  * creating a subscription.
  */
 export type Accessor<T> = () => T;
-export declare function accessor<T>(node: any): Accessor<T>;
+export type SourceAccessor<T> = Refreshable<Accessor<T>>;
+export declare function accessor<T>(node: any): SourceAccessor<T>;
 /**
  * A signal setter. Accepts either a new value or an updater `(prev) => next`.
  *
@@ -51,11 +64,22 @@ export type Setter<in out T> = {
     <U extends T>(value: Exclude<U, Function> | ((prev: T) => U)): U;
 };
 /** A `[get, set]` pair returned from `createSignal` / `createOptimistic`. */
-export type Signal<T> = [get: Accessor<T>, set: Setter<T>];
+export type Signal<T> = [get: SourceAccessor<T>, set: Setter<T>];
 export type ComputeFunction<Prev, Next extends Prev = Prev> = (v: Prev) => PromiseLike<Next> | AsyncIterable<Next> | Next;
 export type EffectFunction<Prev, Next extends Prev = Prev> = (v: Next, p?: Prev) => (() => void) | void;
 export type EffectBundle<Prev, Next extends Prev = Prev> = {
     effect: EffectFunction<Prev, Next>;
+    /**
+     * Intercepts compute-phase errors (thrown by the compute function or arriving
+     * from upstream sources). Effect-phase throws are NOT routed here — they are
+     * your own imperative code and escalate to the nearest error boundary.
+     *
+     * This is the error arm of the effect phase: it runs on the same queue and
+     * in the same imperative, writable scope as `effect` (signal writes are
+     * legal), receives the error the user code threw, and observes settled
+     * outcomes — an error that recovers before the effect phase runs the
+     * `effect` arm instead, and a held transition defers it like `effect`.
+     */
     error: (err: unknown, cleanup: () => void) => void;
 };
 /** Options shared by every effect primitive. */
@@ -77,12 +101,49 @@ export interface EffectOptions extends BaseEffectOptions {
      * `insert()` in `render()`).
      */
     schedule?: boolean;
+    /**
+     * Advanced. When true, asserts the compute function returns synchronous
+     * values only (never `PromiseLike` / `AsyncIterable`). Skips the
+     * async-shape probe in `recompute` for a small fixed-cost win per run.
+     * Intended for compiler emissions (`_$effect`) and library code that
+     * provably returns sync values. Returning a Promise or async iterable
+     * from a `sync: true` effect is undefined behavior — the value will be
+     * stored as-is and never awaited.
+     */
+    sync?: boolean;
+    /**
+     * Advanced (integration tier). When true, the effect is invisible to the
+     * hydration id scheme: it inherits its parent's id instead of consuming a
+     * child slot, and during hydration its compute runs live instead of
+     * adopting the serialized server value (its first run is not frozen to
+     * the server's decision).
+     *
+     * For **client-only effects created while hydrating** — effects with no
+     * server-rendered counterpart (a router wiring link state, scroll
+     * restoration, etc.). An id-consuming node the server never created would
+     * shift every later sibling's hydration id, making serialized lookups and
+     * template claims after it miss. `transparent` is also the supported
+     * alternative to branching on hydration state
+     * (`if (hydrating) createEffect(...)`), which freezes whatever the first
+     * run decided: create the effect unconditionally and let it observe live
+     * state instead.
+     *
+     * SSR ignores this option (a server-side effect always allocates its id
+     * slot), so only mark effects the server does not create. Outside
+     * hydration it is a no-op.
+     */
+    transparent?: boolean;
 }
 /** Options for plain signals created with `createSignal(value)` or `createOptimistic(value)`. */
 export interface SignalOptions<T> {
     /** Debug name (dev mode only) */
     name?: string;
-    /** Custom equality function, or `false` to always notify subscribers */
+    /**
+     * Custom equality function, or `false` to always notify subscribers.
+     * Defaults to reference equality (`isEqual`). Pass a comparator (e.g.
+     * `(a, b) => a.id === b.id`) for value-based equality, or `false` to
+     * notify on every write regardless of equality.
+     */
     equals?: false | ((prev: T, next: T) => boolean);
     /** Suppress dev-mode warnings when writing inside an owned scope */
     ownedWrite?: boolean;
@@ -99,9 +160,21 @@ export interface MemoOptions<T> {
     id?: string;
     /** Debug name (dev mode only) */
     name?: string;
-    /** When true, the owner is invisible to the ID scheme -- inherits parent ID and doesn't consume a childCount slot */
+    /**
+     * Advanced (integration tier). When true, the memo is invisible to the
+     * hydration id scheme: it inherits its parent's id instead of consuming a
+     * child slot, and during hydration it computes live instead of adopting
+     * the serialized server value. For client-only memos with no
+     * server-rendered counterpart — see {@link EffectOptions.transparent} for
+     * the full semantics. No-op outside hydration.
+     */
     transparent?: boolean;
-    /** Custom equality function, or `false` to always notify subscribers */
+    /**
+     * Custom equality function, or `false` to always notify subscribers.
+     * Defaults to reference equality (`isEqual`). Pass a comparator (e.g.
+     * `(a, b) => a.id === b.id`) for value-based equality, or `false` to
+     * notify on every recompute regardless of equality.
+     */
     equals?: false | ((prev: T, next: T) => boolean);
     /** Callback invoked when the computed loses all subscribers */
     unobserved?: () => void;
@@ -114,6 +187,40 @@ export interface MemoOptions<T> {
      * never autodispose.
      */
     lazy?: boolean;
+    /**
+     * Advanced. When true, asserts the compute function returns synchronous
+     * values only (never `PromiseLike` / `AsyncIterable`). Skips the
+     * async-shape probe in `recompute` for a small fixed-cost win per run.
+     * Intended for compiler emissions (`_$memo`) and library code that
+     * provably returns sync values. Returning a Promise or async iterable
+     * from a `sync: true` memo is undefined behavior — the value will be
+     * stored as-is and never awaited.
+     */
+    sync?: boolean;
+    /**
+     * Commit #0: a committed value the memo is born with, shown until the
+     * compute's first real answer lands. While that first answer is in flight
+     * the memo reads as a settled value everywhere — nothing suspends to a
+     * `<Loading>` boundary, no transition is held (first-flight work is
+     * loading-class, like a boundary fallback), and `isPending(memo)` stays
+     * **false**: commit #0 answers the question by declaration, so first-load
+     * affordances are driven from the value itself (a `null` placeholder, a
+     * `skeleton: true` field, etc.). Once the first answer lands, the loading
+     * value leaves the lineage forever: refetches use normal pending semantics
+     * (stale value shown, `isPending` true, boundaries/transitions coordinate)
+     * — the canonical guard is `data.skeleton || isPending(data)`, whose two
+     * terms cover the two disjoint states.
+     *
+     * Typed strictly as `T`: to use `null`/`undefined` as the placeholder,
+     * declare it in the memo's type (e.g. `createMemo<User | null>(...)`), so
+     * every consumer sees the nullable window honestly. If the placeholder is
+     * shaped data standing in for real data, encode its provenance in the data
+     * (e.g. a `skeleton: true` field) rather than letting it impersonate truth.
+     *
+     * The loading value is also the compute's first `prev`, so `prev`-based
+     * memos fold from it.
+     */
+    loadingValue?: T;
 }
 export type NoInfer<T extends any> = [T][T extends any ? 0 : never];
 /**
@@ -162,7 +269,7 @@ export declare function createSignal<T>(fn: ComputeFunction<T>, options?: Signal
  * const value = createMemo<T>(compute, options?: MemoOptions<T>);
  * ```
  * @param compute a function that receives its previous value and returns a new value used to react on a computation
- * @param options `MemoOptions` -- id, name, equals, unobserved, lazy
+ * @param options `MemoOptions` -- id, name, equals, unobserved, lazy, transparent
  *
  * @example
  * ```ts
@@ -185,7 +292,10 @@ export declare function createSignal<T>(fn: ComputeFunction<T>, options?: Signal
  *
  * @description https://docs.solidjs.com/reference/basic-reactivity/create-memo
  */
-export declare function createMemo<T>(compute: ComputeFunction<undefined | NoInfer<T>, T>, options?: MemoOptions<T>): Accessor<T>;
+export declare function createMemo<T>(compute: ComputeFunction<NoInfer<T>, T>, options: MemoOptions<T> & {
+    loadingValue: T;
+}): SourceAccessor<T>;
+export declare function createMemo<T>(compute: ComputeFunction<undefined | NoInfer<T>, T>, options?: MemoOptions<T>): SourceAccessor<T>;
 /**
  * Creates a reactive effect with **separate compute and effect phases**.
  *
@@ -202,14 +312,31 @@ export declare function createMemo<T>(compute: ComputeFunction<undefined | NoInf
  * `createTrackedEffect` (with the tradeoffs noted there).
  *
  * Pass an `EffectBundle` (`{ effect, error }`) instead of a plain function to
- * intercept errors thrown from the compute or effect phases.
+ * intercept **compute-phase** errors — errors thrown by `compute` or arriving
+ * from upstream reactive sources (including async rejections), which your own
+ * code has no frame to `try/catch`. The `error` handler is the error arm of
+ * the effect phase: it runs on the same schedule and in the same imperative,
+ * writable scope as `effect` (setting error state via signals is fine), and
+ * only for *settled* errors — a transient error that recovers before the
+ * effect phase runs `effect` with the recovered value instead, and a held
+ * transition defers it exactly as it defers `effect`. Without an `error`
+ * handler a compute-phase error is logged and the effect simply skips that
+ * run — a non-render effect's reactivity failing does not crash the app.
+ * Rethrowing from `error` escalates it to the nearest error boundary
+ * (halting the system if none exists).
+ *
+ * The **effect phase is different**: it is your own imperative code, so handle
+ * failures with `try/catch` where they occur. An uncaught effect-phase throw
+ * is treated as an unhandled application error — caught by the nearest
+ * `createErrorBoundary`/`<Errored>`, and permanently halting the reactive
+ * system if there is none. It is *not* routed to the bundle's `error` handler.
  *
  * ```typescript
  * createEffect<T>(compute, effectFn | { effect, error }, options?: EffectOptions);
  * ```
  * @param compute a function that receives its previous value and returns a new value used to react on a computation
  * @param effectFn a function that receives the new value and is used to perform side effects (return a cleanup function), or an `EffectBundle` with `effect` and `error` handlers
- * @param options `EffectOptions` -- name, defer, schedule
+ * @param options `EffectOptions` -- name, defer, schedule, transparent
  *
  * @example
  * ```ts
@@ -253,12 +380,28 @@ export declare function createEffect<T>(compute: ComputeFunction<undefined | NoI
  * Creates a reactive computation that runs during the render phase as DOM elements
  * are created and updated but not necessarily connected.
  *
+ * Same compute / effect split as `createEffect`, but scheduled inside the render
+ * queue rather than after it. Reach for this only when authoring renderer
+ * plumbing (custom DOM bindings, JSX-generated `insert()` / `spread()` calls).
+ * App code should use `createEffect`.
+ *
  * ```typescript
  * createRenderEffect<T>(compute, effectFn, options?: EffectOptions);
  * ```
  * @param compute a function that receives its previous value and returns a new value used to react on a computation
  * @param effectFn a function that receives the new value and is used to perform side effects
- * @param options `EffectOptions` -- name, defer, schedule
+ * @param options `EffectOptions` -- name, defer, schedule, transparent
+ *
+ * @example
+ * ```ts
+ * // Custom directive: bind an element's textContent to a reactive source.
+ * function bindText(el: HTMLElement, source: () => string) {
+ *   createRenderEffect(
+ *     () => source(),
+ *     value => { el.textContent = value; }
+ *   );
+ * }
+ * ```
  *
  * @description https://docs.solidjs.com/reference/secondary-primitives/create-render-effect
  */
@@ -324,7 +467,9 @@ export declare function createReaction(effectFn: EffectFunction<undefined> | Eff
  * Awaits a reactive expression and returns its first fully-settled value as a
  * `Promise`. Pending async reads (`createMemo` returning a promise, etc.) are
  * waited on; once the expression returns synchronously without `NotReadyError`
- * the promise resolves with that value.
+ * the promise resolves with that value. If the expression settles with an
+ * error instead — including an async source that rejects — the promise
+ * rejects with it.
  *
  * Must be called *outside* a tracking scope — it doesn't subscribe, it just
  * resolves the current value once.
@@ -400,6 +545,13 @@ export declare function createOptimistic<T>(fn: ComputeFunction<T>, options?: Si
  * `onCleanup` is **not** allowed inside the callback — return a cleanup
  * function instead. The returned cleanup runs on owner disposal.
  *
+ * A cleanup return is only honored when `onSettled` is called from an **owned**
+ * scope (e.g. a component body). When it fires out of band from an *unowned*
+ * scope — an event handler, a tracked effect, or another `onSettled` — there is
+ * no owner lifecycle to bind a cleanup to; returning one is a dev-mode error
+ * (and is dropped in production). Use the post-settle/event-handler forms below
+ * for one-shot work, and keep setup-with-teardown in an owned scope.
+ *
  * @example
  * ```tsx
  * // Component-level setup + teardown — replaces onMount + onCleanup.

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

@@ -1,4 +1,4 @@
-export type { Store, StoreSetter, StoreNode, StoreOptions, ProjectionOptions, NotWrappable, SolidStore } from "./store.js";
+export type { Store, StoreReturn, ProjectionStoreReturn, StoreSetter, StoreNode, StoreOptions, ProjectionOptions, NotWrappable, SolidStore } from "./store.js";
 export type { Merge, Omit } from "./utils.js";
 export { isWrappable, createStore, $TRACK, $PROXY, $TARGET } from "./store.js";
 export { createProjection } from "./projection.js";

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

@@ -14,8 +14,8 @@ import { type NoFn, type ProjectionOptions, type Store, type StoreSetter } from
  *   optimistic overlay reverts after each transition.
  *
  * `options.key` defaults to `"id"`; specify it only when your data uses a
- * different identity field (e.g. `{ key: "uuid" }` or `{ key: t => t.slug }`).
- * Restating the default just adds noise.
+ * different identity field (e.g. `{ key: "uuid" }` or `{ key: t => t.slug }`),
+ * or `null` to merge positionally. Restating the default just adds noise.
  *
  * @example
  * ```ts
@@ -41,5 +41,5 @@ import { type NoFn, type ProjectionOptions, type Store, type StoreSetter } from
  *
  * @returns `[store: Store<T>, setStore: StoreSetter<T>]`
  */
-export declare function createOptimisticStore<T extends object = {}>(store: NoFn<T> | Store<NoFn<T>>): [get: Store<T>, set: StoreSetter<T>];
+export declare function createOptimisticStore<T extends object = {}>(store: NoFn<T> | Store<NoFn<T>>, options?: ProjectionOptions): [get: Store<T>, set: StoreSetter<T>];
 export declare function createOptimisticStore<T extends object = {}>(fn: (store: T) => void | T | Promise<void | T> | AsyncIterable<void | T>, store: Partial<T> | Store<NoFn<T>>, options?: ProjectionOptions): [get: Refreshable<Store<T>>, set: StoreSetter<T>];