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

package/dist/prod/store/storePath.js

@@ -0,0 +1,103 @@
+import { isWrappable, ownEnumerableKeys } from "./store.js";
+
+const DELETE = Symbol(0);
+
+function isPrototypePollutionKey(t) {
+    return t === "__proto__" || t === "constructor" || t === "prototype";
+}
+
+function updatePath(t, e, o = 0) {
+    let r, n = t;
+    if (o < e.length - 1) {
+        r = e[o];
+        const i = typeof r;
+        const f = Array.isArray(t);
+        if (i === "string" && isPrototypePollutionKey(r)) return;
+        if (Array.isArray(r)) {
+            for (let n = 0; n < r.length; n++) {
+                e[o] = r[n];
+                updatePath(t, e, o);
+            }
+            e[o] = r;
+            return;
+        } else if (f && i === "function") {
+            for (let n = 0; n < t.length; n++) {
+                if (r(t[n], n)) {
+                    e[o] = n;
+                    updatePath(t, e, o);
+                }
+            }
+            e[o] = r;
+            return;
+        } else if (f && i === "object") {
+            const {from: n = 0, to: i = t.length - 1, by: f = 1} = r;
+            for (let r = n; r <= i; r += f) {
+                e[o] = r;
+                updatePath(t, e, o);
+            }
+            e[o] = r;
+            return;
+        } else if (o < e.length - 2) {
+            updatePath(t[r], e, o + 1);
+            return;
+        }
+        n = t[r];
+    }
+    let i = e[e.length - 1];
+    if (typeof i === "function") {
+        i = i(n);
+        if (i === n) return;
+    }
+    if (r === undefined && i == undefined) return;
+    if (i === DELETE) {
+        delete t[r];
+    } else if (r === undefined || isWrappable(n) && isWrappable(i) && !Array.isArray(i)) {
+        const e = r !== undefined ? t[r] : t;
+        const o = ownEnumerableKeys(i);
+        for (let t = 0; t < o.length; t++) {
+            const r = o[t];
+            if (typeof r === "string" && isPrototypePollutionKey(r)) continue;
+            const n = Object.getOwnPropertyDescriptor(i, r);
+            if (n.get || n.set) Object.defineProperty(e, r, n); else e[r] = n.value;
+        }
+    } else {
+        t[r] = i;
+    }
+}
+
+/**
+ * Path-based setter helper for `createStore`. Call `storePath(...path, value)`
+ * to produce a draft-mutating function suitable for passing to `setStore`.
+ *
+ * The canonical setter form in Solid 2.0 is the draft-mutating callback
+ * (`setStore(s => { s.user.name = "Ada"; })`). `storePath` is a backwards-
+ * compatibility helper for users porting from Solid 1.x's
+ * `setStore("user", "name", "Ada")` style — it's optional and you can mix the
+ * two styles freely.
+ *
+ * Path parts can be:
+ * - a single key — `"user"`, `0`
+ * - an array of keys — `[0, 1, 2]`
+ * - a range over an array — `{ from?, to?, by? }`
+ * - a filter `(item, index) => boolean` for arrays
+ *
+ * The final argument is the new value or an updater `(prev) => next`. Use
+ * `storePath.DELETE` to remove a property.
+ *
+ * @example
+ * ```ts
+ * const [state, setState] = createStore({ user: { name: "Ada" }, todos: [] });
+ *
+ * setState(storePath("user", "name", "Grace"));
+ * setState(storePath("todos", t => !t.done, "done", true)); // mark all undone as done
+ * setState(storePath("user", "nickname", storePath.DELETE));
+ * ```
+ */ const storePath = /* @__PURE__ */ Object.assign(function storePath(...t) {
+    return e => {
+        updatePath(e, t);
+    };
+}, {
+    DELETE: DELETE
+});
+
+export { storePath };

package/dist/prod/store/utils.js

@@ -0,0 +1,328 @@
+import { pendingCheckActive } from "../core/core.js";
+
+import { SUPPORTS_PROXY } from "../core/constants.js";
+
+import "../core/scheduler.js";
+
+import "../core/invariants.js";
+
+import "../core/verdict.js";
+
+import "../core/effect.js";
+
+import { createMemo } from "../signals.js";
+
+import { ownEnumerableKeys, $PROXY, isWrappable, $TARGET, lookupTarget, trackSelf, witnessAffectsMark, mergedOverlay, STORE_VALUE, storeLookup, STORE_LOOKUP, $DELETED, wrap, getStoreSymbols, getPropertyDescriptor, getStoreKeys, getKeys, $TRACK, rawValuesUsed, isRawValue } from "./store.js";
+
+function snapshotImpl(e, t, r, n) {
+    let o, s, i, c, f, u;
+    if (!isWrappable(e)) return e;
+    if (r && r.has(e)) return r.get(e);
+    if (!r) r = new Map;
+    if (o = e[$TARGET] || lookupTarget(e, n)) {
+        if (t) {
+            trackSelf(o, $TRACK);
+            // A tracked walk reads THROUGH the record without touching the proxy
+            // traps — witness the record's affects() channel like a trap read would.
+                        if (pendingCheckActive) witnessAffectsMark(o);
+        }
+        i = mergedOverlay(o);
+        // A derived store's STORE_VALUE is the inner store's live proxy
+        // (store-in-store: createOptimisticStore/createProjection over a store).
+        // Without an overlay of its own, the fast path below would map to — and
+        // could return — that proxy verbatim. Recurse instead so the
+        // inner store's own target branch unwraps it (chains of any depth).
+        // With an overlay, a fresh `result` is always built, so the walk over the
+        // inner proxy already copies plain values.
+                if (!i && o[STORE_VALUE][$TARGET]) {
+            f = snapshotImpl(o[STORE_VALUE], t, r, n);
+            r.set(e, f);
+            return f;
+        }
+        s = Array.isArray(o[STORE_VALUE]);
+        r.set(e, i ? c = s ? [] : Object.create(Object.getPrototypeOf(o[STORE_VALUE])) : o[STORE_VALUE]);
+        e = o[STORE_VALUE];
+        n = o[STORE_LOOKUP] ?? storeLookup;
+    } else {
+        s = Array.isArray(e);
+        r.set(e, e);
+    }
+    if (s) {
+        const s = i?.length ?? e.length;
+        for (let a = 0; a < s; a++) {
+            u = i && a in i ? i[a] : e[a];
+            if (u === $DELETED) continue;
+            if (t && isWrappable(u) && !(rawValuesUsed && isRawValue(u))) wrap(u, o);
+            if ((f = snapshotImpl(u, t, r, n)) !== u || c) {
+                if (!c) r.set(e, c = [ ...e ]);
+                c[a] = f;
+            }
+        }
+        // Enumerate array symbols separately to avoid scanning indices twice.
+        // Spread copies omit symbols, so assign them after the numeric walk.
+                const a = n ? getStoreSymbols(e, i) : [];
+        for (let s = 0, l = a.length; s < l; s++) {
+            const l = a[s];
+            const p = getPropertyDescriptor(e, i, l);
+            if (!p || p.get) continue;
+            u = i && l in i ? i[l] : e[l];
+            if (t && isWrappable(u) && !(rawValuesUsed && isRawValue(u))) wrap(u, o);
+            f = snapshotImpl(u, t, r, n);
+            if (f !== u || c) {
+                if (!c) r.set(e, c = Object.assign([ ...e ], e));
+                c[l] = f;
+            }
+        }
+        // Deleted trailing slots are skipped above, so restore length to preserve
+        // holes instead of truncating the copy (#2846) — mirrors unwrapStoreValue.
+                if (c) c.length = s;
+    } else if (!i) {
+        // Specialized walk for the common no-overlay case (from #2756): the own
+        // descriptor gives the value directly, so each property is read once with
+        // no overlay membership checks.
+        // A lookup means this object belongs to an immutable store backing tree,
+        // even if that nested value has not needed its own proxy yet.
+        const s = n ? getStoreKeys(e, undefined) : getKeys(e, undefined);
+        for (let i = 0, a = s.length; i < a; i++) {
+            const a = s[i];
+            const l = Object.getOwnPropertyDescriptor(e, a);
+            if (l.get) continue;
+            u = l.value;
+            if (t && isWrappable(u) && !(rawValuesUsed && isRawValue(u))) wrap(u, o);
+            if ((f = snapshotImpl(u, t, r, n)) !== u || c) {
+                if (!c) {
+                    c = Object.create(Object.getPrototypeOf(e));
+                    Object.assign(c, e);
+                }
+                c[a] = f;
+            }
+        }
+    } else {
+        // An override only exists on a store record, and the target branch above
+        // always set `lookup` alongside it — so this branch is always store-keyed.
+        const s = getStoreKeys(e, i);
+        for (let a = 0, l = s.length; a < l; a++) {
+            let l = s[a];
+            const p = getPropertyDescriptor(e, i, l);
+            if (p.get) continue;
+            u = l in i ? i[l] : e[l];
+            if (t && isWrappable(u) && !(rawValuesUsed && isRawValue(u))) wrap(u, o);
+            if ((f = snapshotImpl(u, t, r, n)) !== e[l] || c) {
+                if (!c) {
+                    c = Object.create(Object.getPrototypeOf(e));
+                    Object.assign(c, e);
+                }
+                c[l] = f;
+            }
+        }
+    }
+    return c || e;
+}
+
+function snapshot(e, t, r) {
+    return snapshotImpl(e, false, t, r);
+}
+
+/**
+ * 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
+ * );
+ * ```
+ */ function deep(e) {
+    return snapshotImpl(e, true);
+}
+
+function trueFn() {
+    return true;
+}
+
+const propTraps = {
+    get(e, t, r) {
+        if (t === $PROXY) return r;
+        return e.get(t);
+    },
+    has(e, t) {
+        if (t === $PROXY) return true;
+        return e.has(t);
+    },
+    set: trueFn,
+    deleteProperty: trueFn,
+    getOwnPropertyDescriptor(e, t) {
+        return {
+            configurable: true,
+            enumerable: true,
+            get() {
+                return e.get(t);
+            },
+            set: trueFn,
+            deleteProperty: trueFn
+        };
+    },
+    ownKeys(e) {
+        return e.keys();
+    }
+};
+
+function resolveSource(e) {
+    return !(e = typeof e === "function" ? e() : e) ? {} : e;
+}
+
+const $SOURCES = Symbol(0);
+
+/**
+ * Merges multiple props-like objects into a single proxy that *preserves
+ * reactivity*. Reads are forwarded to the right-most source that defines the
+ * property, so later sources override earlier ones (like `Object.assign`).
+ *
+ * Function arguments are treated as memo-backed sources — useful for passing
+ * derived defaults whose computation should track reactively.
+ *
+ * Use this in component bodies to merge defaults / overrides without losing
+ * Solid's per-property tracking.
+ *
+ * @example
+ * ```tsx
+ * function Button(_props: { label: string; type?: string; disabled?: boolean }) {
+ *   const props = merge({ type: "button", disabled: false }, _props);
+ *
+ *   return <button type={props.type} disabled={props.disabled}>{props.label}</button>;
+ * }
+ * ```
+ */ function merge(...e) {
+    if (e.length === 1 && typeof e[0] !== "function") return e[0];
+    let t = false;
+    const r = [];
+    for (let n = 0; n < e.length; n++) {
+        const o = e[n];
+        t = t || !!o && $PROXY in o;
+        const s = !!o && o[$SOURCES];
+        if (s) {
+            for (let e = 0; e < s.length; e++) r.push(s[e]);
+        } else r.push(typeof o === "function" ? (t = true, createMemo(o)) : o);
+    }
+    if (SUPPORTS_PROXY && t) {
+        return new Proxy({
+            get(e) {
+                if (e === $SOURCES) return r;
+                for (let t = r.length - 1; t >= 0; t--) {
+                    const n = resolveSource(r[t]);
+                    if (e in n) return n[e];
+                }
+            },
+            has(e) {
+                for (let t = r.length - 1; t >= 0; t--) {
+                    if (e in resolveSource(r[t])) return true;
+                }
+                return false;
+            },
+            keys() {
+                const e = new Set;
+                for (let t = 0; t < r.length; t++) {
+                    const n = ownEnumerableKeys(resolveSource(r[t]));
+                    for (let t = 0; t < n.length; t++) e.add(n[t]);
+                }
+                return [ ...e ];
+            }
+        }, propTraps);
+    }
+    const n = Object.create(null);
+    let o = false;
+    let s = r.length - 1;
+    for (let e = s; e >= 0; e--) {
+        const t = r[e];
+        if (!t) {
+            e === s && s--;
+            continue;
+        }
+        const i = Object.getOwnPropertyNames(t);
+        for (let r = i.length - 1; r >= 0; r--) {
+            const c = i[r];
+            if (c === "__proto__" || c === "constructor") continue;
+            if (!n[c]) {
+                o = o || e !== s;
+                const r = Object.getOwnPropertyDescriptor(t, c);
+                n[c] = r.get ? {
+                    enumerable: true,
+                    configurable: true,
+                    get: r.get.bind(t)
+                } : r;
+            }
+        }
+    }
+    if (!o) return r[s];
+    const i = {};
+    const c = Object.keys(n);
+    for (let e = c.length - 1; e >= 0; e--) {
+        const t = c[e], r = n[t];
+        if (r.get) Object.defineProperty(i, t, r); else i[t] = r.value;
+    }
+    i[$SOURCES] = r;
+    return i;
+}
+
+/**
+ * Returns a reactive proxy of `props` with the listed keys hidden. Tracking
+ * on the remaining keys is preserved.
+ *
+ * Use it to forward "rest" props to a child element while pulling out the
+ * keys your component handles itself — the equivalent of `splitProps(p, ["a","b"])[1]`.
+ *
+ * @example
+ * ```tsx
+ * function Input(props: { label: string; value: string; onInput: (v: string) => void } & JSX.HTMLAttributes<HTMLInputElement>) {
+ *   const rest = omit(props, "label", "value", "onInput");
+ *
+ *   return (
+ *     <label>
+ *       {props.label}
+ *       <input
+ *         {...rest}
+ *         value={props.value}
+ *         onInput={e => props.onInput(e.currentTarget.value)}
+ *       />
+ *     </label>
+ *   );
+ * }
+ * ```
+ */ function omit(e, ...t) {
+    if (SUPPORTS_PROXY && $PROXY in e) {
+        return new Proxy({
+            get(r) {
+                return t.includes(r) ? undefined : e[r];
+            },
+            has(r) {
+                return !t.includes(r) && r in e;
+            },
+            keys() {
+                return ownEnumerableKeys(e).filter(e => !t.includes(e));
+            }
+        }, propTraps);
+    }
+    const r = {};
+    const n = Object.getOwnPropertyNames(e);
+    const o = t.length > 4 && n.length > t.length ? new Set(t) : undefined;
+    for (const s of n) {
+        if (o ? !o.has(s) : !t.includes(s)) {
+            const t = Object.getOwnPropertyDescriptor(e, s);
+            !t.get && !t.set && t.enumerable && t.writable && t.configurable ? r[s] = t.value : Object.defineProperty(r, s, t);
+        }
+    }
+    return r;
+}
+
+export { deep, merge, omit, snapshot };

package/dist/types/affects.d.ts

@@ -0,0 +1,47 @@
+import type { Accessor } from "./signals.js";
+import { type Store } from "./store/store.js";
+/**
+ * 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/boundaries.d.ts

@@ -1,5 +1,6 @@
 import { Queue, type Computed, type Effect } from "./core/index.js";
 import type { Signal } from "./core/index.js";
+import { type Accessor } from "./signals.js";
 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.js").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.js").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/core/action.d.ts

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