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

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
  */
@@ -271,6 +414,12 @@ export declare function createRenderEffect<T>(compute: ComputeFunction<undefined
  * may run multiple times for a single change or show tearing (reading inconsistent
  * state). Use only when dynamic subscription patterns require same-scope tracking.
  *
+ * The callback runs during the flush itself: writes made inside it are queued
+ * into the same flush's continuation and are never visible to the callback's
+ * own reads (reads return settled values, as in every effect-phase scope), and
+ * `flush()` cannot be called from inside it (dev throws; production is a
+ * no-op) — defer with `queueMicrotask(() => flush())` if needed.
+ *
  * ```typescript
  * createTrackedEffect(compute, options?: { name?: string });
  * ```
@@ -324,7 +473,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.
@@ -397,9 +548,29 @@ export declare function createOptimistic<T>(fn: ComputeFunction<T>, options?: Si
  * Reactive reads inside the callback are *not* tracked — to react to
  * subsequent settles, register a new `onSettled` each time.
  *
+ * The callback runs during the settle flush itself, which gives it the same
+ * write semantics as every other effect-phase scope (the effect half of
+ * `createEffect`, event handlers):
+ *
+ * - **Writes** are queued into the same flush's continuation — dependent memos
+ *   and effects update before the flush returns — but reads inside the
+ *   callback keep returning the settled (pre-write) values. A callback never
+ *   observes its own unsettled write. Functional setters still compose:
+ *   `set(v => v + 1)` twice increments twice.
+ * - **`flush()` cannot be called** from inside the callback — the flush is
+ *   already running (dev throws; production is a no-op). To force a drain
+ *   after this settle, defer it: `queueMicrotask(() => flush())`.
+ *
  * `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,9 +1,19 @@
-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";
-export { createOptimisticStore } from "./optimistic.js";
-export { reconcile } from "./reconcile.js";
+export { isWrappable, $TRACK, $PROXY, $TARGET } from "./store.js";
+import type { NoFn, ProjectionOptions, Store, StoreOptions, StoreSetter } from "./store.js";
+import type { Refreshable } from "../core/index.js";
+export { createProjectionNext as createProjection } from "./next/projection.js";
+export { createOptimisticStoreNext as createOptimisticStore } from "./next/optimistic.js";
+/** Public createStore: plain form `(init, options?)` and derived writable
+ * form `(fn, seed, options?)`. */
+export declare function createStore<T extends object = {}>(store: NoFn<T> | Store<NoFn<T>>, options?: StoreOptions & {
+    shallow?: boolean;
+}): [get: Store<T>, set: StoreSetter<T>];
+export declare function createStore<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>];
+export declare function reconcile<T extends U, U>(value: T, key?: string | ((item: NonNullable<any>) => any) | null): (state: U) => T;
+export declare function snapshot<T>(value: T): T;
+export declare function deep<T>(value: T): T;
 export { storePath } from "./storePath.js";
 export type { PathSetter, Part, StorePathRange, ArrayFilterFn, CustomPartial } from "./storePath.js";
-export { snapshot, deep, merge, omit } from "./utils.js";
+export { merge, omit } from "./utils.js";

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

@@ -0,0 +1,20 @@
+import { type NoFn, type ProjectionOptions, type Store, type StoreSetter } from "../store.js";
+import type { StoreNextFamily, StoreNextTarget } from "./target.js";
+export declare function createOptimisticStoreNext<T extends object = {}>(first: T | ((store: T) => void | T | Promise<void | T> | AsyncIterable<void | T>), second?: NoFn<T> | Store<NoFn<T>>, options?: ProjectionOptions): [get: Store<T>, set: StoreSetter<T>];
+/** Diff the draft against the current OPTIMISTIC VIEW (committed + active
+ * overrides — the same view the draft was seeded from) and emit engine writes
+ * for exactly the changed keys. Visible-view diffing keeps no-op writes from
+ * entangling lanes (RUL-10 / opt R38). */
+export declare function notifyOptimisticWrites(t: StoreNextTarget, pb: Record<PropertyKey, any>): void;
+/**
+ * Landing consumption (RUL-2): fresh authoritative data supersedes every
+ * tentative override in the family. Mirrors legacy clearProjectionOverride —
+ * drop the override, clear lane/ownership, notify subscribers whose visible
+ * value changes (reversion effects go to regular queues via the projection
+ * write posture the caller holds).
+ */
+export declare function consumeOverridesNext(fam: StoreNextFamily): void;
+/** Optimistic-view composition for snapshot/deep (O1: snapshot is the CURRENT
+ * view, lane values included; a fresh copy per call during pending windows —
+ * RUL-12). Returns `src` untouched when no override is active on `t`. */
+export declare function optimisticView(t: StoreNextTarget, src: Record<PropertyKey, any>): Record<PropertyKey, any>;

package/dist/types/store/next/projection.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Store rewrite — projections (§7/§7b): a projection is a computed store.
+ * The derive runs inside a computed whose recompute merges its output into
+ * the projection's backing through the adoption channel (replace-mode root:
+ * entity changes merge in place, the root proxy is stable for life). Children
+ * wrap into the projection's own FAMILY (writes land here, never in a source
+ * family), and every family node carries the projection computed as its
+ * firewall — reads link the derive's status and lifecycle natively. The §6c
+ * status gate in the traps makes an uninitialized async derive's seed
+ * unobservable through every read surface.
+ *
+ * Mirrors the legacy runProjectionComputed shape (shadow runs for open
+ * loading windows, handleAsync landings, commit-through-setter) on next
+ * primitives; the generic draft write-traps are reused from the legacy
+ * module unchanged.
+ */
+import { type Computed, type Refreshable } from "../../core/index.js";
+import { type NoFn, type ProjectionOptions, type Store } from "../store.js";
+export declare function createProjectionNext<T extends object = {}>(fn: (draft: T) => void | T | Promise<void | T> | AsyncIterable<void | T>, seed: Partial<T> | Store<NoFn<T>>, options?: ProjectionOptions): Refreshable<Store<T>>;
+/** Derived writable store (legacy parity): a projection whose public setter
+ * masks the recompute for the tick (core R31 — the manual write wins over a
+ * same-flush dependency change). */
+export declare function createStoreDerivedNext<T extends object = {}>(fn: (draft: T) => void | T | Promise<void | T> | AsyncIterable<void | T>, seed: Partial<T> | Store<NoFn<T>>, options?: ProjectionOptions): [Refreshable<Store<T>>, (f: (draft: T) => T | void) => void];
+export declare function runProjectionComputedNext<T extends object>(wrappedStore: Store<T>, fn: (draft: T) => void | T | Promise<void | T> | AsyncIterable<void | T>, key: string | ((item: NonNullable<any>) => any) | null, wrapCommit?: (write: () => void) => void, onDraftWrite?: () => void): Computed<void | T>;

package/dist/types/store/next/reconcile.d.ts

@@ -0,0 +1,3 @@
+type KeyFn = (item: any) => any;
+export declare function reconcileNextState(value: any, state: any, key: string | KeyFn | null | undefined, replace?: boolean): void;
+export {};

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

@@ -0,0 +1,71 @@
+import type { Signal } from "../../core/types.js";
+import { type StoreNextFamily, type StoreNextTarget } from "./target.js";
+export declare function wrapNext<T extends Record<PropertyKey, any>>(value: T, parent?: StoreNextTarget | null, parentKey?: PropertyKey | null, fam?: StoreNextFamily | null): T;
+/** Unwrap our own proxies to their current backing; leave everything else. */
+export declare function unwrapValue(v: any): any;
+export declare function getNode(target: StoreNextTarget, key: PropertyKey, current: any): Signal<any>;
+export declare function getHasNode(target: StoreNextTarget, key: PropertyKey, present: boolean): Signal<boolean>;
+export declare function getKeySetNode(target: StoreNextTarget): Signal<number>;
+/** Deep-witness bump: any value/shape change on a record with a live deep()
+ * subscriber notifies it. One null check when unused. */
+export declare function bumpDeep(t: StoreNextTarget): void;
+/**
+ * Adoption (2026-08-16c): the incoming object becomes the committed backing
+ * IMMEDIATELY — reconcile is eagerly visible to every reader (shipped
+ * contract; only its notifications batch), unlike setter writes which stay
+ * pending until flush. Ownership resets (incoming is unowned/user data). Any
+ * staged draft clone folds into the diff and is discarded — next is the
+ * authoritative base (R21/R32).
+ */
+export declare function adoptPB(target: StoreNextTarget, incoming: Record<PropertyKey, any>, eager?: boolean): void;
+/** Same logical slot: both values resolve to one (re-pointed) child target —
+ * adoption preserved identity, so the slot did not change (R9). */
+export declare function targetsEqual(ov: any, nv: any): boolean;
+/**
+ * The fold diff walks SUBSCRIPTION KEYS ONLY (legacy parity: `for key in
+ * nodes`): nodes exist exactly where something tracked, so unobserved data
+ * costs nothing here regardless of object size. Accessor safety rides the
+ * sticky `t.a` flag — a node's key was necessarily read, so the get trap has
+ * already seen whether it is an accessor.
+ */
+/** One node's fold notification (shared by notifyFold's walk and the fused
+ * adoption walk): accessor-aware compare + equality/identity-gated setSignal. */
+export declare function notifyKeyDiff(node: Signal<any>, key: PropertyKey, old: Record<PropertyKey, any>, neu: Record<PropertyKey, any>, probe?: boolean): void;
+/** Accessor-flag probe for the fused walk's early-continue (accessor keys
+ * can never identity-skip: their VALUE is the descriptor's product). */
+export declare function hasAccessorFlag(node: Signal<any>): boolean;
+/** Fused-walk per-key notification with values already in hand: the caller
+ * fetched both sides and handled the identity skip; this applies the
+ * accessor branch (cached flag only — reconcile channel) or the plain
+ * equality/identity-gated write. */
+export declare function notifyKeyValue(node: Signal<any>, key: PropertyKey, ov: any, nv: any, old: Record<PropertyKey, any>, neu: Record<PropertyKey, any>): void;
+/** Presence + membership halves of a fold notification (shared tail). */
+export declare function notifyFoldTail(t: StoreNextTarget, old: Record<PropertyKey, any>, neu: Record<PropertyKey, any>): void;
+export declare function notifyFold(t: StoreNextTarget, old: Record<PropertyKey, any>, neu: Record<PropertyKey, any>): void;
+/** Authoritative-write wrapper exported for the optimistic module: sets the
+ * scheduler's projectionWriteActive through THIS module's binding (proven to
+ * share the instance core reads — cross-module live-binding writes from other
+ * store modules were observed not to propagate under the test transform). */
+export declare function runAuthoritative<T>(fn: () => T): T;
+/** Active optimistic override on an armed node (armed slot idles at
+ * NOT_PENDING; undefined = unarmed plain node). */
+export declare function hasActiveOverride(node: Signal<any>): boolean;
+export type SetStoreNextFunction<T> = (fn: (draft: T) => T | void) => void;
+/** Low-level setter primitive: opens write mode on a next proxy, runs `fn`,
+ * emits write-time notifications at outermost exit, applies returned
+ * replacements as adoptions. `guard=false` skips the owned-scope dev guard —
+ * projection recomputes legitimately write from inside their computed. */
+export declare function storeSetterNext<T>(proxy: T, fn: (draft: T) => T | void, guard?: boolean): void;
+export declare function createStoreNext<T extends Record<PropertyKey, any>>(init: T, shallow?: boolean): [T, SetStoreNextFunction<T>];
+/** Tracking deep snapshot (`deep()` for next targets): subscribes to the
+ * key-set and every property node at every reachable level, then returns the
+ * plain view. Shared references and cycles handled via the visited set. */
+export declare function deepNext<T>(value: T): T;
+/**
+ * Snapshot with per-object registration resolution (RUL-12 DAG ruling): every
+ * reachable wrappable resolves through its target's CURRENT backing, so
+ * privatized subtrees are seen through any parent path. Identity-preserving:
+ * a subtree with no substitutions below returns its own object (zero copy for
+ * settled, never-diverged graphs).
+ */
+export declare function snapshotNext<T>(value: T): T;

package/dist/types/store/next/target.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Store rewrite — target & ownership (INTERNALS-STORE-STATE.md §1, §5b).
+ *
+ * The proxy wraps this internal target, never the raw (proxy-target
+ * indirection, decision 2026-08-16d). `b` is the single committed home; `pb`
+ * is the per-target pending backing (RUL-1's pending home): the CoW clone
+ * created at first draft write, mutated natively by the draft, folded into
+ * `b` at flush commit. Adoption (setter replacement / reconcile) parks an
+ * UNOWNED incoming object in `pb` — fold swaps it in and ownership resets.
+ *
+ * Creation budget (§5b): one minimal target + one proxy + one storeLookup
+ * entry per read-through object; zero layer slots; nodes, has-nodes, and the
+ * key-set node are lazy, materialized only by subscription.
+ */
+import type { Computed, Signal } from "../../core/types.js";
+/** Projection family (§7b): children wrap into the family's own map (writes
+ * land in the projection, never the source family), and every node created
+ * under the family carries the projection computed as its firewall. */
+export interface StoreNextFamily {
+    /** Optimistic family: nodes are born armed (`_overrideValue` slot) so every
+     * write rides the core optimistic engine — lanes, per-transaction ownership,
+     * reverts all core-native (§3, RUL-3). */
+    opt?: boolean;
+    /** Root proxy (registered with the scheduler's optimistic-store set for the
+     * transitionBlocked store-half, #2951). */
+    px?: any;
+    /** Targets currently carrying active node overrides (landing-consumption
+     * walk, RUL-2: visible landed truth replaces optimism). */
+    overlaid?: Set<any>;
+    map: WeakMap<object, StoreNextTarget>;
+    /** The projection computed — assigned after creation (accessor pattern). */
+    node: Computed<any> | null;
+    shallow?: boolean;
+}
+export interface StoreNextTarget {
+    /** Committed backing: source object (shared) or owned clone. */
+    v: Record<PropertyKey, any>;
+    /** Pending backing for the current flush (null when settled). */
+    pb: Record<PropertyKey, any> | null;
+    /** cached: committed backing is another store's proxy (§7b chained). */
+    ch: boolean;
+    /** live value-node count (deleted-key sweep fast-out in the fused walk). */
+    nc: number;
+    /** Lazy per-property subscription nodes (real core signals). */
+    n: Record<PropertyKey, Signal<any>> | null;
+    /** Lazy per-key presence nodes (`in` tracks presence, not value — R13). */
+    h: Record<PropertyKey, Signal<boolean>> | null;
+    /** Lazy key-set node: membership/iteration/$TRACK subscriptions (§6). */
+    k: Signal<number> | null;
+    /** Lazy deep-witness node: `deep()` subscribes ONE node per record instead
+     * of one per path; write paths bump it only when it exists. Separate from
+     * `k` so $TRACK/mapArray never rerun on leaf value changes (R9). */
+    dk: Signal<number> | null;
+    /** Parent target (path copying walks this at commit). */
+    u: StoreNextTarget | null;
+    /** Property key of this target in the parent's backing. */
+    pk: PropertyKey | null;
+    /** The proxy for this target (stable outward identity). */
+    px: any;
+    /** Sticky descendants flag (§6d). */
+    d: boolean;
+    /** Sticky accessors-seen flag: an own accessor property was observed on
+     * this target (first-read scan, defineProperty, or clone scan). Gates the
+     * fold diff's descriptor-safe path and the get trap's descriptor path. */
+    a: boolean;
+    /** Accessor scan performed (scan-once on first trap read; adopted data is
+     * not rescanned — legacy-parity behavior). */
+    sc: boolean;
+    /** Backing was swapped by adoption this batch (fold diff-notifies it). */
+    adopted: boolean;
+    /** Projection family, null for plain stores (§7b). */
+    fam: StoreNextFamily | null;
+    /** Shallow store root (values served raw). */
+    s: boolean;
+}
+/**
+ * Ownership (first cut, decision 2026-08-16d): one WeakSet of store-owned
+ * backings serving both the production identity-skip guard and the __TEST__
+ * no-mutation oracle.
+ */
+export declare const ownedRaw: WeakSet<object>;
+/** raw → target. The only raw-keyed lookup; boundary mechanism (O8). */
+export declare const storeNextLookup: WeakMap<object, StoreNextTarget>;
+/** __TEST__ oracle: every object ingested from a user (never mutate). */
+export declare const ingestedRaw: WeakSet<object> | null;
+export declare function devAssertNeverUserMutation(target: object): void;
+/** Injection table for optimistic-only store machinery (next/optimistic.ts).
+ * Every call site is gated on `fam?.opt`, and optimistic families can only
+ * be created by createOptimisticStore — whose install populates this — so
+ * the non-null assertions at the sites hold by construction. Keeping the
+ * implementations out of next/store.ts lets plain-store bundles tree-shake
+ * the optimistic channel entirely. */
+export interface OptStoreHooks {
+    notifyOptimisticWrites(t: any, pb: Record<PropertyKey, any>): void;
+    optimisticView(t: any, src: Record<PropertyKey, any>): Record<PropertyKey, any>;
+    applyTentative(t: any, incoming: any, keyFn: ((item: any) => any) | null): void;
+}
+export declare let optHooks: OptStoreHooks | null;
+export declare function setOptHooks(h: OptStoreHooks): void;

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>];

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

@@ -1,5 +1,5 @@
 import { type Computed, type Refreshable } from "../core/index.js";
-import { type ProjectionOptions, type Store } from "./store.js";
+import { type NoFn, type ProjectionOptions, type Store } from "./store.js";
 export declare function createProjectionInternal<T extends object = {}>(fn: (draft: T) => void | T | Promise<void | T> | AsyncIterable<void | T>, seed: Partial<T>, options?: ProjectionOptions): {
     store: Refreshable<Store<T>>;
     node: Computed<void | T>;
@@ -12,6 +12,10 @@ export declare function createProjectionInternal<T extends object = {}>(fn: (dra
  * items keep their proxy identity — only added/removed items are
  * created/disposed.
  *
+ * If the derive returns a different entity than the one currently held (the
+ * `/users/1` → `/users/2` shape), the store swaps to it rather than merging,
+ * and nothing below it is treated as surviving.
+ *
  * Returns the projected store directly (no setter — reads only).
  *
  * Use this when you want the structural-sharing / per-property tracking
@@ -24,7 +28,8 @@ export declare function createProjectionInternal<T extends object = {}>(fn: (dra
  * @param seed the backing store value to wrap and reconcile into
  * @param options `ProjectionOptions` — `name`, `key`. `key` defaults to
  *   `"id"`; specify it only when your data uses a different identity field
- *   (e.g. `{ key: "uuid" }` or `{ key: u => u.slug }`).
+ *   (e.g. `{ key: "uuid" }` or `{ key: u => u.slug }`), or `null` to merge
+ *   positionally with no keyed pass.
  *
  * @example
  * ```ts
@@ -47,7 +52,7 @@ export declare function createProjectionInternal<T extends object = {}>(fn: (dra
  *
  * @see {@link https://github.com/solidjs/x-reactivity#createprojection}
  */
-export declare function createProjection<T extends object = {}>(fn: (draft: T) => void | T | Promise<void | T> | AsyncIterable<void | T>, seed: Partial<T>, options?: ProjectionOptions): Refreshable<Store<T>>;
+export declare function createProjection<T extends object = {}>(fn: (draft: T) => void | T | Promise<void | T> | AsyncIterable<void | T>, seed: Partial<T> | Store<NoFn<T>>, options?: ProjectionOptions): Refreshable<Store<T>>;
 /**
  * Shared projection computed body used by both `createProjection` and the derived
  * form of `createOptimisticStore`. Encapsulates the write-trap draft, `storeSetter`
@@ -61,6 +66,5 @@ export declare function createProjection<T extends object = {}>(fn: (draft: T) =
  * instead of `STORE_OPTIMISTIC_OVERRIDE` even when an async yield fires outside
  * the outer `setProjectionWriteActive` scope.
  */
-export declare function runProjectionComputed<T extends object>(wrappedStore: Store<T>, fn: (draft: T) => void | T | Promise<void | T> | AsyncIterable<void | T>, key: string | ((item: NonNullable<any>) => any), wrapCommit?: (write: () => void) => void): Computed<void | T>;
-export declare function createWriteTraps(isActive?: () => boolean): ProxyHandler<any>;
-export declare const writeTraps: ProxyHandler<any>;
+export declare function runProjectionComputed<T extends object>(wrappedStore: Store<T>, fn: (draft: T) => void | T | Promise<void | T> | AsyncIterable<void | T>, key: string | ((item: NonNullable<any>) => any) | null, wrapCommit?: (write: () => void) => void, onDraftWrite?: () => void): Computed<void | T>;
+export declare function createWriteTraps(isActive?: () => boolean, onDraftWrite?: () => void): ProxyHandler<any>;