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

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 Signal } from "../core/index.js";
+import type { Refreshable } from "../core/index.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,95 +29,110 @@ 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_NODE = "n", STORE_HAS = "h", STORE_PARENT = "u", STORE_DESC = "d", STORE_SHALLOW = "s";
+/** Structural view of a store target as shared machinery sees it (the real
+ * shape is `StoreNextTarget` in ./next/target.ts). */
 export type StoreNode = {
     [$PROXY]: any;
     [STORE_VALUE]: Record<PropertyKey, any>;
-    [STORE_OVERRIDE]?: Record<PropertyKey, any>;
-    [STORE_OPTIMISTIC_OVERRIDE]?: Record<PropertyKey, any>;
     [STORE_NODE]?: DataNodes;
     [STORE_HAS]?: DataNodes;
-    [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 {
     }
 }
 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 function wrap<T extends Record<PropertyKey, any>>(value: T, target?: StoreNode): T;
+/**
+ * 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 markRawOne(v: any): void;
+export declare function markRawIngest(container: any): void;
 export declare function isWrappable<T>(obj: T | NotWrappable): obj is T;
 export declare function setWriteOverride(value: boolean): void;
-export declare function trackSelf(target: StoreNode, symbol?: symbol): void;
-export declare function getKeys(source: Record<PropertyKey, any>, override: Record<PropertyKey, any> | undefined, enumerable?: boolean): PropertyKey[];
-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;
+export declare function getWriteOverride(): boolean;
+export declare function ownEnumerableKeys(o: object): (string | symbol)[];
 /**
- * Creates a deeply-reactive store backed by a Proxy. Reads track each property
- * accessed; only the parts that change trigger updates.
- *
- * Store properties hold **plain values**, not accessors. The proxy already
- * tracks reads per-property — wrapping a value in `() => state.foo` produces
- * a getter that *won't* track when called, which looks like a reactivity bug
- * but is just a category error. If you have a signal-shaped piece of state,
- * make it a property of the store (`{ foo: 1 }`) rather than nesting an
- * accessor inside (`{ foo: () => signal() }`).
- *
- * The setter takes a **draft-mutating** function — mutate the draft in place
- * (canonical). The callback may also return a new value: arrays are replaced
- * by index (length adjusted), objects are shallow-diffed at the top level
- * (keys present in the returned value are written, missing keys deleted). Use
- * the return form for shapes where mutation is awkward — most commonly
- * removing items via `filter`. The setter does **not** do keyed reconciliation;
- * for that, use the derived/projection form (or `createProjection`).
- *
- * - Plain form: `createStore(initialValue)` — wraps a value in a reactive
- *   proxy.
- * - Derived form: `createStore(fn, seed, options?)` — a *projection store*
- *   whose contents are computed by `fn(draft)`. `fn` may be sync, async, or
- *   an `AsyncIterable`; the projection's result reconciles against the
- *   existing store by `options.key` (default `"id"`) for stable identity.
- *
- * @example
- * ```ts
- * const [state, setState] = createStore({
- *   user: { name: "Ada", age: 36 },
- *   todos: [] as { id: string; text: string; done: boolean }[]
- * });
- *
- * // Canonical: mutate the draft in place.
- * setState(s => { s.user.age = 37; });
- * setState(s => { s.todos.push({ id: "1", text: "x", done: false }); });
- *
- * // Return form: reach for it when mutation is awkward.
- * setState(s => s.todos.filter(t => !t.done));               // remove items
- * setState(s => ({ ...s, user: { name: "Grace", age: 85 } })); // shallow replace
- * ```
+ * Scope inheritance for late-created nodes: every live mark whose identity
+ * scope contains the owning record's raw — and, for keyed marks, whose key
+ * is this property — gets counted on the new node. Inherited marks live
+ * exactly as long as the scope's carrier — the release hook below drops
+ * them with the entry.
+ */
+export declare function inheritAffectsMarks(node: DataNode, raw: object, property: PropertyKey): void;
+/** Next-store node factory for affects carriers/slots: injected by the
+ * rewrite module (next targets alias the legacy field names, so everything
+ * here EXCEPT node creation works on them structurally). */
+export declare let nextAffectsNodeResolver: ((target: any, key: PropertyKey) => DataNode) | null;
+export declare function setNextAffectsNodeResolver(fn: (target: any, key: PropertyKey) => DataNode): void;
+/** Next-store optimistic view for the declaration walk (optimistic rows
+ * pushed before the declaration are in motion too — legacy reads its write
+ * overlays; next composes armed-node overrides). */
+export declare let nextOptimisticViewResolver: ((target: any, raw: any) => any) | null;
+export declare function setNextOptimisticViewResolver(fn: (target: any, raw: any) => any): void;
+/** @internal birth inheritance for nodes created inside a live mark window —
+ * exported for the rewrite's node factories. */
+export declare function affectsScopesLive(): boolean;
+/**
+ * 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.
  *
- * @example
- * ```ts
- * // Derived store — auto-fetches & reconciles by `id`.
- * const [users] = createStore(
- *   async () => fetch("/users").then(r => r.json()),
- *   [] as User[]
- * );
- * ```
+ * @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).
  *
- * @returns `[store: Store<T>, setStore: StoreSetter<T>]`
+ * @internal
  */
-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 getStoreAffectsNodes(target: StoreNode, key?: PropertyKey): DataNode[];
 export {};

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

@@ -1,43 +1,3 @@
-/**
- * Returns a plain (non-proxy, non-reactive) deep copy of a store value.
- * Reading via `snapshot` does **not** subscribe to changes — use this when you
- * need to hand a stable plain object to non-reactive code (logging,
- * serialization, structured-clone, network payloads, etc.).
- *
- * Returns the original object identity for any sub-tree that wasn't modified
- * relative to the proxy's underlying source.
- *
- * @example
- * ```ts
- * const [state] = createStore({ user: { name: "Ada" }, todos: [] });
- *
- * console.log(JSON.stringify(snapshot(state))); // safe, non-reactive copy
- * ```
- */
-export declare function snapshot<T>(item: T): T;
-export declare function snapshot<T>(item: T, map?: Map<unknown, unknown>, lookup?: WeakMap<any, any>): T;
-/**
- * Returns a plain (non-proxy) deep copy **and** subscribes the current
- * tracking scope to every nested change in the source store. Any write
- * anywhere in the subtree invalidates the consumer.
- *
- * Use this when you need plain data inside a reactive scope and want to
- * react to deep mutations (e.g. passing a snapshot to `reconcile()` or to a
- * memo that should rerun on any nested change). For most read paths, prefer
- * direct property access — Solid stores already track per-property reads
- * with no `deep()` wrapper needed.
- *
- * @example
- * ```ts
- * const [state] = createStore({ a: { b: { c: 1 } } });
- *
- * createEffect(
- *   () => deep(state),                  // reruns on any nested change
- *   plain => sendToWorker(plain)        // worker gets a non-proxy copy
- * );
- * ```
- */
-export declare function deep<T extends object>(store: T): T;
 type DistributeOverride<T, F> = T extends undefined ? F : T;
 type Override<T, U> = T extends any ? U extends any ? {
     [K in keyof T]: K extends keyof U ? DistributeOverride<U[K], T[K]> : T[K];

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;