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

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

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

@@ -1,14 +1,34 @@
+/**
+ * Shared body of `reconcile()` and the projection commit. `replace` is the
+ * only difference: a projection commit is a value swap, not a merge — its root
+ * proxy is a cell handed out by `createProjection` that can never change
+ * reference, so a derive returning a different entity is not the slot mistake
+ * `reconcile()` throws on. Nothing below the root survives that swap, which is
+ * the rule the keyed diff already applies at a nested slot on a key mismatch.
+ *
+ * @internal
+ */
+export declare function reconcileState(value: any, state: any, key: any, replace: boolean): void;
 /**
  * Returns a draft-mutating function that smart-merges `value` into a store,
- * preserving the identity of items whose `key` field matches between old and
- * new states. Useful when applying server payloads or full-replacement data
- * onto an existing store without losing fine-grained reactivity.
+ * preserving fine-grained reactivity: only changed leaves trigger updates.
  *
- * Items with the same key are updated in place (only changed properties
- * trigger updates). Items added or removed update the corresponding signals.
+ * With a `key` (default `"id"`), array items whose key matches between old
+ * and new states keep their identity (updated in place, moves and removals
+ * update the corresponding signals) — the shape for keyed server payloads.
+ * Items without the key field fall back to positional matching.
+ *
+ * With `key: null`, matching is purely positional: index N of the new array
+ * merges into index N of the old, and object properties merge recursively —
+ * the classic pattern for fixed-shape data that churns in place (dashboards,
+ * monitors), where no keyed diff pass is needed or wanted.
+ *
+ * Merging into a slot that holds a *different* entity throws — the caller
+ * picked the slot, so a key mismatch there is a bug.
  *
  * @param value the next state to merge in
- * @param key property name (string) or extractor function for stable identity
+ * @param key property name (string) or extractor function for stable
+ * identity (default `"id"`); pass `null` for positional merging
  *
  * @example
  * ```ts
@@ -16,8 +36,11 @@
  *
  * async function refresh() {
  *   const fresh = await api.getTodos();
- *   setTodos(reconcile(fresh, "id")); // diff-merge by `id`
+ *   setTodos(reconcile(fresh)); // diff-merge by `id`
  * }
+ *
+ * // fixed-shape polling data — positional merge
+ * setStats(reconcile(nextStats, null));
  * ```
  */
-export declare function reconcile<T extends U, U>(value: T, key: string | ((item: NonNullable<any>) => any)): (state: U) => void;
+export declare function reconcile<T extends U, U>(value: T, key?: string | ((item: NonNullable<any>) => any) | null): (state: U) => void;

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

@@ -1,4 +1,5 @@
 import { STORE_SNAPSHOT_PROPS, type Computed, type Refreshable, type Signal } from "../core/index.js";
+import { type Transition } from "../core/scheduler.js";
 /** A read-only view of a store's value as seen by consumers. Mutate it via the paired `StoreSetter`. */
 export type Store<T> = Readonly<T>;
 /**
@@ -17,6 +18,10 @@ export type Store<T> = Readonly<T>;
  * whose derive function reconciles its return by `options.key`.
  */
 export type StoreSetter<T> = (fn: (state: T) => T | void) => void;
+/** Tuple returned by the plain `createStore(initialValue)` form. */
+export type StoreReturn<T> = [get: Store<T>, set: StoreSetter<T>];
+/** Tuple returned by the derived `createStore(fn, seed, options?)` form. */
+export type ProjectionStoreReturn<T> = [get: Refreshable<Store<T>>, set: StoreSetter<T>];
 /** Base options for store primitives. */
 export interface StoreOptions {
     /** Debug name (dev mode only) */
@@ -24,26 +29,53 @@ export interface StoreOptions {
 }
 /** Options for derived/projected stores created with `createStore(fn)`, `createProjection`, or `createOptimisticStore(fn)`. */
 export interface ProjectionOptions extends StoreOptions {
-    /** Key property name or function for reconciliation identity */
-    key?: string | ((item: NonNullable<any>) => any);
+    /** Key property name or function for reconciliation identity; `null` merges positionally */
+    key?: string | ((item: NonNullable<any>) => any) | null;
+    /** Single-layer store: root keys reactive, values raw records replaced by reference */
+    shallow?: boolean;
+    /**
+     * Treat the seed as commit #0: the store is born committed with the seed's
+     * contents, shown until the derive's first real answer lands. While that
+     * first answer is in flight, reads serve the seed everywhere — nothing
+     * suspends to a `<Loading>` boundary, no transition is held, and
+     * `isPending` stays false (the seed answers by declaration; first-load
+     * affordances belong to the data, e.g. a `skeleton: true` field in the
+     * seed). Once the first answer lands (reconciled into the seed), refetches
+     * use normal pending semantics with `isPending` true.
+     *
+     * The store equivalent of `MemoOptions.loadingValue`; the seed already
+     * carries the placeholder shape, so this is just the opt-in.
+     */
+    seedLoadingValue?: boolean;
 }
 export type NoFn<T> = T extends Function ? never : T;
 type DataNode = Signal<any>;
 type DataNodes = Record<PropertyKey, DataNode>;
-export declare const $TRACK: unique symbol, $TARGET: unique symbol, $PROXY: unique symbol, $DELETED: unique symbol;
-export declare const STORE_VALUE = "v", STORE_OVERRIDE = "o", STORE_OPTIMISTIC_OVERRIDE = "x", STORE_NODE = "n", STORE_HAS = "h", STORE_WRAP = "w", STORE_LOOKUP = "l", STORE_FIREWALL = "f", STORE_OPTIMISTIC = "p";
+/**
+ * Brand symbols used internally by the store proxy / projection plumbing.
+ * Cross-package wiring; not part of the user-facing API.
+ *
+ * @internal
+ */
+export declare const $TRACK: unique symbol, $TARGET: unique symbol, $PROXY: unique symbol, $DELETED: unique symbol, $AFFECTS: unique symbol;
+export declare const STORE_VALUE = "v", STORE_OVERRIDE = "o", STORE_OPTIMISTIC_OVERRIDE = "x", STORE_NODE = "n", STORE_HAS = "h", STORE_CUSTOM_PROTO = "c", STORE_WRAP = "w", STORE_LOOKUP = "l", STORE_FIREWALL = "f", STORE_OPTIMISTIC = "p", STORE_OPTIMISTIC_OWNERS = "t", STORE_PARENT = "u", STORE_DESC = "d", STORE_SHALLOW = "s";
 export type StoreNode = {
     [$PROXY]: any;
     [STORE_VALUE]: Record<PropertyKey, any>;
     [STORE_OVERRIDE]?: Record<PropertyKey, any>;
     [STORE_OPTIMISTIC_OVERRIDE]?: Record<PropertyKey, any>;
+    [STORE_OPTIMISTIC_OWNERS]?: Record<PropertyKey, Transition | null>;
     [STORE_NODE]?: DataNodes;
     [STORE_HAS]?: DataNodes;
+    [STORE_CUSTOM_PROTO]?: boolean;
     [STORE_WRAP]?: (value: any, target?: StoreNode) => any;
     [STORE_LOOKUP]?: WeakMap<any, any>;
     [STORE_FIREWALL]?: Computed<any>;
     [STORE_OPTIMISTIC]?: boolean;
     [STORE_SNAPSHOT_PROPS]?: Record<PropertyKey, any>;
+    [STORE_PARENT]?: StoreNode;
+    [STORE_SHALLOW]?: boolean;
+    [STORE_DESC]?: boolean;
 };
 export declare namespace SolidStore {
     interface Unwrappable {
@@ -52,11 +84,72 @@ export declare namespace SolidStore {
 export type NotWrappable = string | number | bigint | symbol | boolean | Function | null | undefined | SolidStore.Unwrappable[keyof SolidStore.Unwrappable];
 export declare function createStoreProxy<T extends object>(value: T, traps?: ProxyHandler<StoreNode>, extend?: (target: StoreNode) => void): any;
 export declare const storeLookup: WeakMap<WeakKey, any>;
+export declare const symbolKeyedRecords: WeakSet<object>;
+export declare function lookupTarget(value: any, lookup?: WeakMap<any, any>): StoreNode | undefined;
+/**
+ * Marks a value as raw: no store will ever wrap it — every store presents it
+ * as-is, tracked by reference at whatever slot holds it and updated by
+ * replacement. Useful for class instances and external objects (editors,
+ * scene graphs, Maps) and for record-shaped data updated wholesale. Sticky
+ * for the value's lifetime.
+ */
+export declare let rawValuesUsed: boolean;
+export declare function isRawValue(value: any): boolean;
+export declare function markRaw<T>(value: T): T;
+export declare function markRawIngest(container: any): void;
 export declare function wrap<T extends Record<PropertyKey, any>>(value: T, target?: StoreNode): T;
+export declare function wrapShallow<T extends Record<PropertyKey, any>>(value: T): T;
 export declare function isWrappable<T>(obj: T | NotWrappable): obj is T;
 export declare function setWriteOverride(value: boolean): void;
+export declare function ownEnumerableKeys(o: object): (string | symbol)[];
+/**
+ * Single chokepoint for the store's layered value resolution: returns the
+ * override layer (optimistic first, then regular) that shadows `property`, or
+ * `undefined` when the base `STORE_VALUE` is authoritative. Every trap must
+ * resolve through this — hand-inlining the layer order is how the optimistic
+ * layer gets missed (#2850).
+ */
+export declare function getOverlayLayer(target: StoreNode, property: PropertyKey): Record<PropertyKey, any> | undefined;
+/**
+ * The value a store leaf's backing signal currently shows to readers: active
+ * override, else held pending value, else committed value.
+ */
+export declare function visibleNodeValue(node: DataNode): any;
+/**
+ * Witness live mark coverage of a record into the active isPending() probe.
+ * Tracked reads don't need this — they go through real signal nodes, which
+ * carry marks directly (declaration walk or birth inheritance). This covers
+ * UNTRACKED probes reading through records whose nodes never materialized
+ * (no observer ever subscribed, so no node exists to carry the mark).
+ * Callers guard on `pendingCheckActive`, so plain reads never pay for this.
+ *
+ * @internal
+ */
+export declare function witnessAffectsMark(target: StoreNode, property?: PropertyKey): void;
+/**
+ * Resolves the store nodes an `affects()` declaration marks: with a `key`,
+ * the named slot's leaf node (upserted so the mark has an addressable
+ * carrier); without, the record's $AFFECTS carrier plus every LIVE node in
+ * its subtree (the edges existing readers subscribed through), with the
+ * subtree's identities snapshotted into the mark's scope so nodes created
+ * during the window — and untracked probes over captured proxies — resolve
+ * against it (#2882).
+ *
+ * @internal
+ */
+export declare function getStoreAffectsNodes(target: StoreNode, key?: PropertyKey): DataNode[];
 export declare function trackSelf(target: StoreNode, symbol?: symbol): void;
+export declare function notifySelf(target: StoreNode): void;
+/**
+ * The write overlay a walk must read through: optimistic writes shadow
+ * regular pending writes, the same resolution order as every proxy trap and
+ * `reconcile` (#2850). Merging allocates only in the rare both-present case
+ * (a derived optimistic store with an in-flight projection commit).
+ */
+export declare function mergedOverlay(target: StoreNode): Record<PropertyKey, any> | undefined;
 export declare function getKeys(source: Record<PropertyKey, any>, override: Record<PropertyKey, any> | undefined, enumerable?: boolean): PropertyKey[];
+export declare function getStoreKeys(source: Record<PropertyKey, any>, override: Record<PropertyKey, any> | undefined): PropertyKey[];
+export declare function getStoreSymbols(source: Record<PropertyKey, any>, override: Record<PropertyKey, any> | undefined): symbol[];
 export declare function getPropertyDescriptor(source: Record<PropertyKey, any>, override: Record<PropertyKey, any> | undefined, property: PropertyKey): PropertyDescriptor | undefined;
 export declare const storeTraps: ProxyHandler<StoreNode>;
 export declare function storeSetter<T extends object>(store: Store<T>, fn: (draft: T) => T | void): void;
@@ -113,6 +206,8 @@ export declare function storeSetter<T extends object>(store: Store<T>, fn: (draf
  *
  * @returns `[store: Store<T>, setStore: StoreSetter<T>]`
  */
-export declare function createStore<T extends object = {}>(store: NoFn<T> | Store<NoFn<T>>): [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 createStore<T extends object = {}>(store: NoFn<T> | Store<NoFn<T>>, options?: StoreOptions & {
+    shallow?: boolean;
+}): StoreReturn<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): ProjectionStoreReturn<T>;
 export {};

package/dist/types-cjs/affects.d.cts

@@ -0,0 +1,47 @@
+import type { Accessor } from "./signals.cjs";
+import { type Store } from "./store/store.cjs";
+/**
+ * Declares that in-flight work will change the targeted data: the named
+ * slot(s) — and everything DERIVED from them — read as pending
+ * (`isPending` → `true`) from the declaration until the surrounding
+ * transaction settles or reverts. A mark lives on its own channel — a
+ * refcount on the marked node plus dep-graph reachability in the verdict
+ * layer — so the marked values themselves stay readable (a mark is a promise
+ * of change, not an absence of value), no reader ever suspends on one, and
+ * completion/settlement accounting never sees one. This is the declaration
+ * verb of the pending model — additive only. A mark can turn pending ON for
+ * data the graph can't see changing yet; nothing can turn pending OFF while
+ * a real change is in flight — a quiet `refresh()` re-ask under a mark still
+ * reads pending (declaring the reload is what makes it a real question).
+ *
+ * Targets:
+ * - `affects(store)` — a store proxy (any record, root or nested): every
+ *   record reachable from it at declaration time reads pending, including
+ *   through captured child proxies (e.g. `<For>` rows). Siblings are
+ *   untouched; records added after the declaration are not covered.
+ * - `affects(record, key)` — exactly the named slot of the record. One key
+ *   per call (keys do NOT form a path — target the owning record directly).
+ * - `affects(accessor)` — a source accessor (signal or memo): the source
+ *   reads pending.
+ *
+ * Typically called at the top of an `action` alongside optimistic writes —
+ * both are up-front declarations about the same mutation. Outside any
+ * transaction the mark is released at the end of the current flush.
+ *
+ * @example
+ * ```ts
+ * const send = action(function* (text: string) {
+ *   setState(s => { s.messages.push({ text, status: "sending" }); });
+ *   affects(state.messages.at(-1)!, "status"); // this slot pends until settle
+ *   yield api.send(text);
+ * });
+ *
+ * const reload = action(function* () {
+ *   affects(thing);      // the whole store pends…
+ *   refresh(thing);      // …over this otherwise-quiet re-ask
+ *   yield api.done();
+ * });
+ * ```
+ */
+export declare function affects(target: Accessor<unknown> | Store<object>): void;
+export declare function affects<T extends object>(target: Store<T>, key: keyof T): void;

package/dist/types-cjs/boundaries.d.cts

@@ -1,5 +1,6 @@
 import { Queue, type Computed, type Effect } from "./core/index.cjs";
 import type { Signal } from "./core/index.cjs";
+import { type Accessor } from "./signals.cjs";
 export interface BoundaryComputed<T> extends Computed<T> {
     _propagationMask: number;
 }
@@ -19,18 +20,18 @@ export declare class RevealController {
     _evaluating: boolean;
     constructor(order: OrderAccessor, collapsed: BoolAccessor);
     _forEachOwnedSlot(fn: (slot: RevealSlot) => boolean | void): boolean;
-    isReady(): boolean;
+    _isReady(): boolean;
     /**
      * "Minimally ready" = this group has something visible to show under its own policy.
      * Used by an enclosing `together` group to decide when it can release.
-     * - `together`: fully ready (atomic).
+     * - `together`: every direct slot is minimally ready.
      * - `sequential`: the first owned slot is minimally ready (frontier can advance).
      * - `natural`: any owned slot is minimally ready.
      */
-    isMinimallyReady(): boolean;
-    register(slot: RevealSlot): void;
-    unregister(slot: RevealSlot): void;
-    evaluate(disabledOverride?: boolean, collapsedOverride?: boolean): void;
+    _isMinimallyReady(): boolean;
+    _register(slot: RevealSlot): void;
+    _unregister(slot: RevealSlot): void;
+    _evaluate(disabledOverride?: boolean, collapsedOverride?: boolean): void;
 }
 export declare class CollectionQueue extends Queue {
     _collectionType: number;
@@ -38,6 +39,7 @@ export declare class CollectionQueue extends Queue {
     _tree?: BoundaryComputed<any>;
     _pending: boolean;
     _disabled: Signal<boolean>;
+    _error?: Signal<unknown>;
     _collapsed: Signal<boolean>;
     _revealController?: RevealController;
     _initialized: boolean;
@@ -46,7 +48,7 @@ export declare class CollectionQueue extends Queue {
     constructor(type: number);
     run(type: number): void;
     notify(node: Effect<any>, type: number, flags: number, error?: any): boolean;
-    checkSources(): void;
+    _checkSources(): void;
 }
 /**
  * Lower-level primitive that backs the `<Loading>` flow control. Catches
@@ -59,20 +61,45 @@ export declare class CollectionQueue extends Queue {
  * @param fallback the fallback shown while async reads in `fn` are unresolved
  * @param options `on` — accessor whose value scopes the boundary; when set,
  *   transitions caused by writes to other reactive sources are *not* caught
+ *
+ * @example
+ * ```tsx
+ * // Custom boundary component built on top of the primitive.
+ * function MyLoading(props: { fallback: JSX.Element; children: JSX.Element }) {
+ *   return createLoadingBoundary(
+ *     () => props.children,
+ *     () => props.fallback
+ *   ) as unknown as JSX.Element;
+ * }
+ * ```
  */
-export declare function createLoadingBoundary(fn: () => any, fallback: () => any, options?: {
+export declare function createLoadingBoundary<T, U>(fn: () => T, fallback: () => U, options?: {
     on?: () => any;
-}): import("./signals.cjs").Accessor<unknown>;
+}): Accessor<T | U>;
 /**
  * Lower-level primitive that backs the `<Errored>` flow control. Catches
  * thrown errors inside `fn` and invokes `fallback(error, reset)` instead.
- * `reset()` recomputes the failing sources so the boundary can attempt to
- * recover.
+ * `error` is an accessor for the latest captured error; `reset()` recomputes
+ * the failing sources so the boundary can attempt to recover.
  *
  * App code should use `<Errored fallback={...}>` instead — reach for this only
  * when authoring custom boundary components.
+ *
+ * @example
+ * ```tsx
+ * // Custom boundary that wraps the primitive and adds telemetry.
+ * function TracedErrored(props: { fallback: (e: () => unknown) => JSX.Element; children: JSX.Element }) {
+ *   return createErrorBoundary(
+ *     () => props.children,
+ *     (err, reset) => {
+ *       reportError(err());
+ *       return props.fallback(err);
+ *     }
+ *   ) as unknown as JSX.Element;
+ * }
+ * ```
  */
-export declare function createErrorBoundary<U>(fn: () => any, fallback: (error: unknown, reset: () => void) => U): import("./signals.cjs").Accessor<unknown>;
+export declare function createErrorBoundary<T, U>(fn: () => T, fallback: (error: Accessor<unknown>, reset: () => void) => U): Accessor<T | U>;
 /**
  * Coordinate the reveal timing of sibling loading boundaries.
  *
@@ -101,7 +128,18 @@ export declare function createErrorBoundary<U>(fn: () => any, fallback: (error:
  *   own minimal signal).
  * - `together` — every direct slot is minimally ready.
  * - `natural` — any direct slot has visible content (leaves on resolve; nested
- *   composites when fully ready, since natural treats composites as atomic).
+ *   composites via their own minimal signal).
+ *
+ * @example
+ * ```ts
+ * // Primitive form of `<Reveal>` — coordinate sibling loading boundaries
+ * // programmatically. App code uses the JSX `<Reveal>` component instead.
+ * // Both options are accessors so they can react to state changes.
+ * createRevealOrder(
+ *   () => renderSiblings(),
+ *   { order: () => mode(), collapsed: () => true }
+ * );
+ * ```
  */
 export declare function createRevealOrder<T>(fn: () => T, options?: {
     order?: OrderAccessor;
@@ -120,6 +158,15 @@ export declare function createRevealOrder<T>(fn: () => T, options?: {
  * @param options
  *   - `skipNonRendered` — drop values that won't render
  *   - `doNotUnwrap` — leave function children as-is (caller will resolve)
+ *
+ * @example
+ * ```ts
+ * // Custom renderer walking a children tree manually. Most authors should
+ * // use `children()` from solid-js, which memoizes the resolved value.
+ * function renderChildren(value: unknown): unknown {
+ *   return flatten(value, { skipNonRendered: true });
+ * }
+ * ```
  */
 export declare function flatten(children: any, options?: {
     skipNonRendered?: boolean;

package/dist/types-cjs/core/action.d.cts

@@ -1,13 +1,41 @@
 /**
+ * The primitive for mutations: imperative async workflows whose *writes span
+ * an async gap* — optimistic write, server round-trip, reconciling write —
+ * where intermediate state must not leak and failure must revert cleanly
+ * (pair with `createOptimistic` / `createOptimisticStore`).
+ *
+ * Navigation-shaped updates do not need an action. A plain setter call is
+ * enough: reads pull the async, and downstream async computeds hold their
+ * previous values per-node until the new ones are ready (`isPending` /
+ * `latest` expose the in-flight state). Reach for `action` only when writes
+ * happen *after* async work, not merely upstream of it.
+ *
+ * Framework-level actions (router form actions, server actions) are
+ * specializations of this primitive: they are actions in exactly this sense —
+ * the same transactional semantics — with form binding, serialization, and
+ * submission tracking layered on top. The shared name is deliberate.
+ *
  * Wraps a generator function so each invocation runs as a single transaction
  * (a "transition") that batches every signal/store write between yields. The
  * surrounding UI sees one atomic update per yielded step; nothing is committed
  * until the action either completes or the next `yield` resolves.
  *
- * Yield promises (or any awaitable) inside the generator — the action waits
- * for each before continuing, but the writes you made beforehand are already
- * visible (or held by `<Loading>` if optimistic). Yield bare values for
- * synchronous batched steps.
+ * `yield` is the transaction-safe suspension point: the action waits for a
+ * yielded promise and re-enters the transaction before running the code after
+ * it. A plain `await` does NOT — the runtime has no hook into an async
+ * generator's internal await continuations, so writes to fresh signals
+ * between an `await` and the next `yield` escape the transaction and commit
+ * immediately. `await` is still the ergonomic choice for typed results; just
+ * put a bare `yield` before any writes that follow it:
+ *
+ * ```ts
+ * const saved = await api.createTodo(text); // typed result
+ * yield; // re-enter the transaction before writing
+ * setTodos(t => { ... });
+ * ```
+ *
+ * (For the same reason, don't call `flush()` inside an action body — it
+ * drains the transaction mid-step.)
  *
  * Each call returns a `Promise` that resolves with the generator's return
  * value, or rejects if it throws. Pair with `createOptimistic` /
@@ -18,10 +46,11 @@
  * ```ts
  * const [todos, setTodos] = createOptimisticStore<Todo[]>([]);
  *
- * const addTodo = action(function* (text: string) {
+ * const addTodo = action(async function* (text: string) {
  *   const tempId = crypto.randomUUID();
  *   setTodos(t => { t.push({ id: tempId, text, pending: true }); }); // optimistic
- *   const saved = yield api.createTodo(text); // network round-trip
+ *   const saved = await api.createTodo(text); // network round-trip, typed
+ *   yield; // re-enter the transaction
  *   setTodos(t => {
  *     const i = t.findIndex(x => x.id === tempId);
  *     if (i >= 0) t[i] = saved;

package/dist/types-cjs/core/async.d.cts

@@ -1,6 +1,21 @@
+import { NotReadyError } from "./error.cjs";
 import { type OptimisticLane } from "./lanes.cjs";
-import type { Computed } from "./types.cjs";
+import type { Computed, Link } from "./types.cjs";
+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-cjs/core/constants.d.cts

@@ -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-cjs/core/context.d.cts

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