@solidjs/signals 2.0.0-beta.8 → 2.0.0-beta.9

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

@@ -1,15 +1,41 @@
 /**
- * Returns a non reactive copy of the store object.
- * It will attempt to preserver the original reference unless the value has been modified.
- * @param item store proxy object
+ * 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 non-reactive snapshot of the store while subscribing to all nested changes.
- * Subscribes to `$TRACK` at every level so that any deep change triggers recomputation,
- * and returns plain (non-proxy) data. Works correctly with `reconcile()`.
- * @param store store proxy object
+ * 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;
@@ -35,9 +61,54 @@ type _Merge<T extends unknown[], Curr = {}> = T extends [
     ...infer Rest
 ] ? _Merge<Rest, Override<Curr, Next>> : T extends [...infer Rest, infer Next | (() => infer Next)] ? Override<_Merge<Rest, Curr>, Next> : T extends [] ? Curr : T extends (infer I | (() => infer I))[] ? OverrideSpread<Curr, I> : Curr;
 export type Merge<T extends unknown[]> = Simplify<_Merge<T>>;
+/**
+ * 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>;
+ * }
+ * ```
+ */
 export declare function merge<T extends unknown[]>(...sources: T): Merge<T>;
 export type Omit<T, K extends readonly (keyof T)[]> = {
     [P in keyof T as Exclude<P, K[number]>]: T[P];
 };
+/**
+ * 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>
+ *   );
+ * }
+ * ```
+ */
 export declare function omit<T extends Record<any, any>, K extends readonly (keyof T)[]>(props: T, ...keys: K): Omit<T, K>;
 export {};

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

@@ -48,9 +48,30 @@ export declare class CollectionQueue extends Queue {
     notify(node: Effect<any>, type: number, flags: number, error?: any): boolean;
     checkSources(): void;
 }
+/**
+ * Lower-level primitive that backs the `<Loading>` flow control. Catches
+ * pending async reads inside `fn` and renders `fallback` until they settle.
+ *
+ * App code should use `<Loading fallback={...}>` instead — reach for this only
+ * when authoring custom boundary components.
+ *
+ * @param fn the tracked subtree
+ * @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
+ */
 export declare function createLoadingBoundary(fn: () => any, fallback: () => any, options?: {
     on?: () => any;
 }): import("./signals.cjs").Accessor<unknown>;
+/**
+ * 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.
+ *
+ * App code should use `<Errored fallback={...}>` instead — reach for this only
+ * when authoring custom boundary components.
+ */
 export declare function createErrorBoundary<U>(fn: () => any, fallback: (error: unknown, reset: () => void) => U): import("./signals.cjs").Accessor<unknown>;
 /**
  * Coordinate the reveal timing of sibling loading boundaries.
@@ -86,6 +107,20 @@ export declare function createRevealOrder<T>(fn: () => T, options?: {
     order?: OrderAccessor;
     collapsed?: BoolAccessor;
 }): T;
+/**
+ * Resolves a children value to its renderable form: unwraps zero-arg functions
+ * (accessors), recursively flattens arrays, and optionally skips
+ * non-rendering values (`null`, `undefined`, `true`, `false`, `""`).
+ *
+ * Used internally by flow components and by the renderer to walk a children
+ * tree. App code rarely needs this directly — see `children()` in `solid-js`
+ * for the user-facing helper that memoizes the result.
+ *
+ * @param children value or array of values to flatten
+ * @param options
+ *   - `skipNonRendered` — drop values that won't render
+ *   - `doNotUnwrap` — leave function children as-is (caller will resolve)
+ */
 export declare function flatten(children: any, options?: {
     skipNonRendered?: boolean;
     doNotUnwrap?: boolean;

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

@@ -1 +1,35 @@
+/**
+ * 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.
+ *
+ * Each call returns a `Promise` that resolves with the generator's return
+ * value, or rejects if it throws. Pair with `createOptimistic` /
+ * `createOptimisticStore` to apply tentative writes that auto-revert if the
+ * action fails.
+ *
+ * @example
+ * ```ts
+ * const [todos, setTodos] = createOptimisticStore<Todo[]>([]);
+ *
+ * const addTodo = action(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
+ *   setTodos(t => {
+ *     const i = t.findIndex(x => x.id === tempId);
+ *     if (i >= 0) t[i] = saved;
+ *   });
+ *   return saved;
+ * });
+ *
+ * await addTodo("buy milk");
+ * ```
+ */
 export declare function action<Args extends any[], Y, R>(genFn: (...args: Args) => Generator<Y, R, any> | AsyncGenerator<Y, R, any>): (...args: Args) => Promise<R>;

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

@@ -9,6 +9,12 @@ 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 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 STATUS_NONE = 0;
 export declare const STATUS_PENDING: number;
 export declare const STATUS_ERROR: number;
@@ -23,3 +29,14 @@ export declare const STORE_SNAPSHOT_PROPS = "sp";
 export declare const SUPPORTS_PROXY: boolean;
 export declare const defaultContext: {};
 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).
+ */
+export type Refreshable<T> = T & {
+    readonly [$REFRESH]: any;
+};

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

@@ -1,6 +1,7 @@
-import { $REFRESH } from "./constants.cjs";
+import { type Refreshable } from "./constants.cjs";
 import { type OptimisticLane } from "./lanes.cjs";
 import type { Computed, FirewallSignal, NodeOptions, Owner, Signal } from "./types.cjs";
+export declare const PRIMITIVE_IN_FORBIDDEN_SCOPE_MESSAGE = "[PRIMITIVE_IN_FORBIDDEN_SCOPE] Cannot create reactive primitives inside createTrackedEffect or owner-backed onSettled";
 export declare let tracking: boolean;
 export declare let stale: boolean;
 export declare let refreshing: boolean;
@@ -30,14 +31,49 @@ export declare function isEqual<T>(a: T, b: T): boolean;
 export declare let strictRead: string | false;
 export declare function setStrictRead(v: string | false): string | false;
 /**
- * Executes `fn` without tracking reactive dependencies.
+ * Runs `fn` outside of any reactive tracking — reads inside `fn` will not
+ * subscribe the current scope. Returns whatever `fn` returns.
  *
- * Pass a `strictReadLabel` string to enable strict-read warnings: any reactive read inside `fn`
- * that is not inside a nested tracking scope will log a warning in dev mode.
+ * Use `untrack` inside a memo or effect when you need to read a signal once
+ * without making the surrounding computation depend on its future changes.
+ *
+ * Pass a `strictReadLabel` string to enable a dev-mode warning: any reactive
+ * read inside `fn` that isn't inside a nested tracking scope will log a
+ * warning naming the label.
+ *
+ * @example
+ * ```ts
+ * createEffect(
+ *   () => trigger(),                 // tracks `trigger` only
+ *   () => {
+ *     const snapshot = untrack(() => state); // read once, untracked
+ *     log(snapshot);
+ *   }
+ * );
+ * ```
  */
 export declare function untrack<T>(fn: () => T, strictReadLabel?: string | false): T;
 export declare function read<T>(el: Signal<T> | Computed<T>): T;
 export declare function setSignal<T>(el: Signal<T> | Computed<T>, v: T | ((prev: T) => T)): T;
+/**
+ * Executes `fn` with the given `owner` set as the current owner. Any reactive
+ * primitives (`createSignal`, `createMemo`, `createEffect`, `onCleanup`,
+ * `cleanup`, etc.) created inside `fn` are attached to that owner, so they
+ * are disposed when the owner is disposed.
+ *
+ * The classic pattern: capture the current owner with `getOwner()` inside a
+ * component, then re-enter it from a callback (event handler, async resolve,
+ * setTimeout) so disposables created in the callback get cleaned up with the
+ * component.
+ *
+ * @example
+ * ```ts
+ * function delayed<T>(ms: number, fn: () => T) {
+ *   const owner = getOwner();
+ *   setTimeout(() => runWithOwner(owner, fn), ms);
+ * }
+ * ```
+ */
 export declare function runWithOwner<T>(owner: Owner | null, fn: () => T): T;
 /**
  * Update _pendingSignal when pending state changes. When the override clears
@@ -46,9 +82,72 @@ export declare function runWithOwner<T>(owner: Owner | null, fn: () => T): T;
  */
 export declare function updatePendingSignal(el: Signal<any> | Computed<any>): void;
 export declare function staleValues<T>(fn: () => T, set?: boolean): T;
+/**
+ * Reads reactive expressions while bypassing any pending async overlay — i.e.
+ * always returns the most-recently-committed value, even when newer reads
+ * inside `fn` are still in flight.
+ *
+ * Useful inside a `<Loading>` boundary's children when you want to keep
+ * showing the previous resolved data instead of the fallback while the next
+ * value loads.
+ *
+ * @example
+ * ```tsx
+ * <Loading fallback={<Skeleton />}>
+ *   {/* During a transition, render the previous user instead of skeleton: *\/}
+ *   <UserCard user={latest(() => user())} />
+ * </Loading>
+ * ```
+ */
 export declare function latest<T>(fn: () => T): T;
+/**
+ * Returns `true` if any reactive read inside `fn` is currently in a pending
+ * (async, not-yet-settled) state. Does not subscribe — pair with a tracked
+ * memo if you want to react to pending status changes.
+ *
+ * Useful for showing inline transition indicators alongside the previous
+ * value (rather than swapping to a `<Loading>` fallback).
+ *
+ * @example
+ * ```tsx
+ * const pending = createMemo(() => isPending(() => user()));
+ *
+ * <button disabled={pending()}>{pending() ? "Saving…" : "Save"}</button>
+ * ```
+ */
 export declare function isPending(fn: () => any): boolean;
-export declare function refresh<T>(fn: (() => T) | (T & {
-    [$REFRESH]: any;
-})): T;
+/**
+ * Forces a reactive source to re-execute, even if its inputs haven't changed.
+ *
+ * Two forms:
+ * - `refresh(memo)` — pass an accessor (memo / signal getter) and its
+ *   underlying computation reruns.
+ * - `refresh(store)` — pass a *projected* store created from
+ *   `createStore(fn, ...)` or `createProjection(...)` and the projection
+ *   recomputes.
+ *
+ * Use it to invalidate cached async values (e.g. force a re-fetch) without
+ * tearing the consumer down.
+ *
+ * @example
+ * ```ts
+ * const user = createMemo(async () => fetch(`/users/${id()}`).then(r => r.json()));
+ *
+ * // Re-fetch on demand
+ * <button onClick={() => refresh(user)}>Reload</button>
+ * ```
+ */
+export declare function refresh<T>(fn: (() => T) | Refreshable<T>): T;
+/**
+ * Returns `true` while a `refresh()` call is in progress. Useful for showing
+ * a "refreshing" indicator distinct from the initial-load `<Loading>`
+ * fallback.
+ *
+ * @example
+ * ```tsx
+ * <Show when={isRefreshing()}>
+ *   <span class="badge">refreshing…</span>
+ * </Show>
+ * ```
+ */
 export declare function isRefreshing(): boolean;

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

@@ -6,7 +6,7 @@ export interface DevHooks {
     onStoreNodeUpdate?: (state: any, property: PropertyKey, value: any, prev: any) => void;
 }
 export type DiagnosticSeverity = "warn" | "error";
-export type DiagnosticCode = "STRICT_READ_UNTRACKED" | "PENDING_ASYNC_UNTRACKED_READ" | "PENDING_ASYNC_FORBIDDEN_SCOPE" | "SIGNAL_WRITE_IN_OWNED_SCOPE" | "RUN_WITH_DISPOSED_OWNER" | "NO_OWNER_CLEANUP" | "CLEANUP_IN_FORBIDDEN_SCOPE" | "NO_OWNER_EFFECT" | "NO_OWNER_BOUNDARY" | "ASYNC_OUTSIDE_LOADING_BOUNDARY";
+export type DiagnosticCode = "STRICT_READ_UNTRACKED" | "PENDING_ASYNC_UNTRACKED_READ" | "PENDING_ASYNC_FORBIDDEN_SCOPE" | "SIGNAL_WRITE_IN_OWNED_SCOPE" | "RUN_WITH_DISPOSED_OWNER" | "NO_OWNER_CLEANUP" | "CLEANUP_IN_FORBIDDEN_SCOPE" | "PRIMITIVE_IN_FORBIDDEN_SCOPE" | "NO_OWNER_EFFECT" | "NO_OWNER_BOUNDARY" | "ASYNC_OUTSIDE_LOADING_BOUNDARY" | "MISSING_EFFECT_FN";
 export type DiagnosticKind = "strict-read" | "async" | "write" | "lifecycle" | "owner";
 export interface DiagnosticEvent {
     sequence: number;

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

@@ -4,19 +4,70 @@ export declare function dispose(node: Computed<unknown>): void;
 export declare function disposeChildren(node: Owner, self?: boolean, zombie?: boolean): void;
 export declare function getNextChildId(owner: Owner): string;
 export declare function peekNextChildId(owner: Owner): string;
+/**
+ * Returns the currently-tracking observer (the computation that subscribes to
+ * reactive reads at this point), or `null` if reads here would be untracked.
+ * Used by reactive primitives that need to know whether they're inside a
+ * tracking scope. App code rarely needs this — see `getOwner()` for the
+ * lifecycle owner instead.
+ */
 export declare function getObserver(): Owner | null;
+/**
+ * Returns the current reactive **owner** — the lifecycle node that the next
+ * `cleanup()` / `onCleanup()` / `createSignal()` etc. will be attached to.
+ *
+ * Returns `null` if called outside any owner. Capture the owner with
+ * `getOwner()` and re-enter it later with `runWithOwner(owner, fn)` to attach
+ * disposables created from a callback (event handler, async resolution, etc.)
+ * back to a component's lifecycle.
+ *
+ * @example
+ * ```ts
+ * function defer<T>(fn: () => T) {
+ *   const owner = getOwner();
+ *   queueMicrotask(() => runWithOwner(owner, fn));
+ * }
+ * ```
+ */
 export declare function getOwner(): Owner | null;
+/**
+ * Low-level: registers `fn` as a disposal callback on the current owner.
+ * Most code should use `onCleanup()` from `solid-js`, which adds dev-mode
+ * checks. `cleanup()` is the unchecked primitive used by internals.
+ */
 export declare function cleanup(fn: Disposable): Disposable;
+/** Returns `true` if the owner has been disposed (or marked zombie pending disposal). */
 export declare function isDisposed(node: Owner): boolean;
+/**
+ * Creates a fresh owner attached as a child of the current owner (or as a
+ * detached root if there is none). Mostly used by framework internals to
+ * group cleanups; app code should prefer `createRoot()` or `runWithOwner()`.
+ */
 export declare function createOwner(options?: {
     id?: string;
     transparent?: boolean;
 }): Root;
 /**
- * Creates a new non-tracked reactive context with manual disposal
+ * Creates a detached reactive root. The callback receives a `dispose()`
+ * function which, when called, tears down every signal, memo, effect, and
+ * `onCleanup` registered inside the root.
+ *
+ * Use this to host long-lived reactive scopes outside of a component (custom
+ * controllers, app bootstrapping, tests). Inside a component, prefer
+ * letting Solid's component lifecycle own things.
+ *
+ * @example
+ * ```ts
+ * const dispose = createRoot(dispose => {
+ *   const [n, setN] = createSignal(0);
+ *   createEffect(() => n(), value => console.log(value));
+ *   setInterval(() => setN(x => x + 1), 1000);
+ *   return dispose;
+ * });
  *
- * @param fn a function in which the reactive state is scoped
- * @returns the output of `fn`.
+ * // Later, to tear everything down:
+ * dispose();
+ * ```
  *
  * @description https://docs.solidjs.com/reference/reactive-utilities/create-root
  */

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

@@ -30,6 +30,7 @@ export interface Transition {
     _actions: Array<Generator<any, any, any> | AsyncGenerator<any, any, any>>;
     _queueStash: QueueStub;
     _done: boolean | Transition;
+    _gatedSubs: Set<Computed<any>>;
 }
 export declare function schedule(): void;
 export interface IQueue {
@@ -73,8 +74,23 @@ export declare function finalizePureQueue(completingTransition?: Transition | nu
 export declare function trackOptimisticStore(store: any): void;
 export declare const globalQueue: GlobalQueue;
 /**
- * By default, changes are batched on the microtask queue which is an async process. You can flush
- * the queue synchronously to get the latest updates by calling `flush()`.
+ * Synchronously processes the pending reactive queue: runs every scheduled
+ * memo/effect/computation that has dirty inputs, until the graph is settled.
+ *
+ * Reactive updates are normally batched onto the microtask queue, so multiple
+ * writes in a row collapse into a single update pass. Call `flush()` when you
+ * need to *observe* the result of those writes synchronously — most commonly
+ * in tests, but also at the boundary of imperative integration code.
+ *
+ * @example
+ * ```ts
+ * const [count, setCount] = createSignal(0);
+ * const doubled = createMemo(() => count() * 2);
+ *
+ * setCount(5);
+ * flush();
+ * expect(doubled()).toBe(10);
+ * ```
  */
 export declare function flush(): void;
 export declare function currentTransition(transition: Transition): Transition;

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

@@ -29,8 +29,7 @@ export interface RawSignal<T> {
     _snapshotValue?: any;
     _name?: string;
     _equals: false | ((a: T, b: T) => boolean);
-    _ownedWrite?: boolean;
-    _noSnapshot?: boolean;
+    _config: number;
     _unobserved?: () => void;
     _time: number;
     _transition: Transition | null;
@@ -48,8 +47,7 @@ export interface FirewallSignal<T> extends RawSignal<T> {
 export type Signal<T> = RawSignal<T> | FirewallSignal<T>;
 export interface Owner {
     id?: string;
-    _transparent?: boolean;
-    _childrenForbidden?: boolean;
+    _config: number;
     _snapshotScope?: boolean;
     _disposal: Disposable | Disposable[] | null;
     _parent: Owner | null;
@@ -65,7 +63,6 @@ export interface Computed<T> extends RawSignal<T>, Owner {
     _deps: Link | null;
     _depsTail: Link | null;
     _flags: number;
-    _inSnapshotScope?: boolean;
     _blocked?: boolean;
     _pendingSource?: Computed<any>;
     _pendingSources?: Set<Computed<any>>;

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

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

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

@@ -1,9 +1,28 @@
 import { type Accessor } from "./signals.cjs";
 export type Maybe<T> = T | void | null | undefined | false;
 /**
- * Reactively transforms an array with a callback function - underlying helper for the `<For>` control flow
+ * Reactively maps an array, reusing the previously-mapped value for unchanged
+ * items. The callback receives `(value, index)` as accessors so individual
+ * items and indexes can be subscribed to without re-running the mapper.
  *
- * similar to `Array.prototype.map`, but gets the value and index as accessors, transforms only values that changed and returns an accessor and reactively tracks changes to the list.
+ * This is the underlying helper that powers `<For>`. App code should use
+ * `<For>` directly; reach for `mapArray` when implementing custom list
+ * components.
+ *
+ * - `options.keyed` — `true` (default for primitives) compares by identity;
+ *   `false` falls back to index-only mapping; pass a function `(item) => key`
+ *   for stable identity by extracted key.
+ * - `options.fallback` — accessor returning a value to show when the input is
+ *   empty.
+ *
+ * @example
+ * ```ts
+ * const view = mapArray(
+ *   items,
+ *   (item, index) => `${index()}: ${item().label}`,
+ *   { fallback: () => "no items" }
+ * );
+ * ```
  *
  * @description https://docs.solidjs.com/reference/reactive-utilities/map-array
  */
@@ -13,7 +32,17 @@ export declare function mapArray<Item, MappedItem>(list: Accessor<Maybe<readonly
     name?: string;
 }): Accessor<MappedItem[]>;
 /**
- * Reactively repeats a callback function the count provided - underlying helper for the `<Repeat>` control flow
+ * Reactively renders a callback `count` times, reusing previously-rendered
+ * entries when only the count changes. Underlying helper for `<Repeat>`.
+ *
+ * - `options.from` — start index (default `0`); useful for offset/windowed
+ *   rendering.
+ * - `options.fallback` — accessor returning a value to show when count is `0`.
+ *
+ * @example
+ * ```ts
+ * const view = repeat(count, i => `Item ${i}`, { fallback: () => "empty" });
+ * ```
  *
  * @description https://docs.solidjs.com/reference/reactive-utilities/repeat
  */