@solidjs/signals 0.13.13 → 2.0.0-beta.11

package/dist/types/boundaries.d.ts

@@ -5,18 +5,29 @@ export interface BoundaryComputed<T> extends Computed<T> {
 }
 type RevealSlot = CollectionQueue | RevealController;
 type BoolAccessor = () => boolean;
+export type RevealOrder = "sequential" | "together" | "natural";
+type OrderAccessor = () => RevealOrder;
 export declare class RevealController {
-    _togetherAccessor: BoolAccessor;
+    _orderAccessor: OrderAccessor;
     _collapsedAccessor: BoolAccessor;
     _slots: RevealSlot[];
     _parentController?: RevealController;
     _disabled: Signal<boolean>;
     _collapsed: Signal<boolean>;
     _ready: boolean;
+    _minimallyReady: boolean;
     _evaluating: boolean;
-    constructor(together: BoolAccessor, collapsed: BoolAccessor);
+    constructor(order: OrderAccessor, collapsed: BoolAccessor);
     _forEachOwnedSlot(fn: (slot: RevealSlot) => boolean | void): 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).
+     * - `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;
@@ -37,14 +48,124 @@ 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
+ *
+ * @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?: {
     on?: () => any;
-}): import("./signals.js").Accessor<unknown>;
-export declare function createErrorBoundary<U>(fn: () => any, fallback: (error: unknown, reset: () => void) => U): import("./signals.js").Accessor<unknown>;
+}): import("./signals.js").SourceAccessor<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.
+ *
+ * @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").SourceAccessor<unknown>;
+/**
+ * Coordinate the reveal timing of sibling loading boundaries.
+ *
+ * Accepts reactive accessors:
+ * - `order`: `"sequential"` (default) | `"together"` | `"natural"`.
+ *   - `"sequential"` — classic frontier reveal: siblings reveal in registration order
+ *     as each resolves; later siblings stay hidden until earlier ones complete.
+ *   - `"together"` — every direct slot stays on its fallback until the whole group
+ *     is "minimally ready" (each direct slot has produced its own first visible
+ *     content under its own order), then the whole group releases at once.
+ *   - `"natural"` — children reveal independently (as each resolves). At the top
+ *     level this is a no-op compared to not using `createRevealOrder`; the mode
+ *     exists for nesting, where the group registers as a single composite slot to
+ *     any enclosing `createRevealOrder`.
+ * - `collapsed`: only meaningful when `order === "sequential"`. When set, tail siblings
+ *   past the frontier suppress their own fallback output. Ignored under `"together"`
+ *   and `"natural"` — those orders have no frontier.
+ *
+ * Nested `createRevealOrder` groups compose: the inner controller registers as a
+ * single slot in the outer controller and is held on its fallbacks until the outer
+ * releases that slot. Once released, the inner controller runs its own order locally
+ * over anything still pending. There is no opt-out from an outer hold.
+ *
+ * "Minimally ready" is what an order considers its first visible content:
+ * - `sequential` — frontier-0 is minimally ready (leaf: on resolve; nested: via its
+ *   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).
+ *
+ * @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?: {
-    together?: BoolAccessor;
+    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)
+ *
+ * @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;
     doNotUnwrap?: boolean;

package/dist/types/core/action.d.ts

@@ -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/core/constants.d.ts

@@ -9,6 +9,14 @@ 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;
+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;
@@ -22,4 +30,22 @@ export declare const NO_SNAPSHOT: {};
 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 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/core/context.d.ts

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

package/dist/types/core/core.d.ts

@@ -1,6 +1,7 @@
-import { $REFRESH } from "./constants.js";
+import { type Refreshable } from "./constants.js";
 import { type OptimisticLane } from "./lanes.js";
 import type { Computed, FirewallSignal, NodeOptions, Owner, Signal } from "./types.js";
+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;
@@ -17,11 +18,18 @@ export declare function releaseSnapshotScope(owner: Owner): void;
 export declare function clearSnapshots(): void;
 export declare function recompute(el: Computed<any>, create?: boolean): void;
 export declare function computed<T>(fn: (prev?: T) => T | PromiseLike<T> | AsyncIterable<T>): Computed<T>;
-export declare function computed<T>(fn: (prev: T) => T | PromiseLike<T> | AsyncIterable<T>, initialValue?: T, options?: NodeOptions<T>): Computed<T>;
+export declare function computed<T>(fn: (prev: T) => T | PromiseLike<T> | AsyncIterable<T>, options?: NodeOptions<T>): Computed<T>;
+/**
+ * Build an Effect node with all effect-specific fields baked into a single object literal,
+ * so V8 sees the full hidden class shape at construction time. Effects always run in lazy
+ * mode (recompute is called explicitly by `effect()`), so we hardcode the lazy bits and skip
+ * the auto-dispose CONFIG bit (effect() previously cleared it post-construction).
+ */
+export declare function createEffectNode<T>(fn: (prev?: T) => T, effectFn: (val: T, prev: T | undefined) => void | (() => void), errorFn: ((err: unknown, cleanup: () => void) => void | (() => void)) | undefined, type: number, notifyStatus: ((status?: number, error?: any) => void) | undefined, options: NodeOptions<T> | undefined): any;
 export declare function signal<T>(v: T, options?: NodeOptions<T>): Signal<T>;
 export declare function signal<T>(v: T, options?: NodeOptions<T>, firewall?: Computed<any>): FirewallSignal<T>;
 export declare function optimisticSignal<T>(v: T, options?: NodeOptions<T>): Signal<T>;
-export declare function optimisticComputed<T>(fn: (prev?: T) => T | PromiseLike<T> | AsyncIterable<T>, initialValue?: T, options?: NodeOptions<T>): Computed<T>;
+export declare function optimisticComputed<T>(fn: (prev?: T) => T | PromiseLike<T> | AsyncIterable<T>, options?: NodeOptions<T>): Computed<T>;
 export declare function isEqual<T>(a: T, b: T): boolean;
 /**
  * When set to a component name string, any reactive read that is not inside a nested tracking
@@ -30,14 +38,64 @@ 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.
+ *
+ * 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.
  *
- * 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.
+ * @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;
+/**
+ * Suppresses automatic recomputation of `el` until the scheduler drains. Used
+ * when a manual write should win over dependency changes queued in the same
+ * tick. The MANUAL_WRITE flag is cleared by the pending-node drain; projection
+ * computeds don't commit values, but they still need the same end-of-tick
+ * cleanup point.
+ */
+export declare function suppressComputedRecompute(el: Computed<unknown>): void;
+/**
+ * User-facing setter for the memo form of `createSignal(fn)`. Behaves like
+ * `setSignal`, but also cancels any pending recompute of the memo so the
+ * manual value wins over a value that would otherwise be produced by an
+ * upstream change in the same tick.
+ */
+export declare function setMemo<T>(el: 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 +104,71 @@ 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;
+/**
+ * Invalidates one reactive source, forcing it to re-execute even if its inputs
+ * haven't changed.
+ *
+ * Pass either a Solid-created accessor or a projected store created from
+ * `createStore(fn, ...)` / `createProjection(...)`. `refresh()` is a
+ * write-like invalidation operation: it does not read the target's value, and
+ * refreshing a plain signal accessor is a no-op.
+ *
+ * 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>(target: Refreshable<T>): void;
+/**
+ * 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/core/dev.d.ts

@@ -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" | "INVALID_REFRESH_TARGET" | "MISSING_EFFECT_FN" | "SYNC_NODE_RECEIVED_ASYNC";
 export type DiagnosticKind = "strict-read" | "async" | "write" | "lifecycle" | "owner";
 export interface DiagnosticEvent {
     sequence: number;

package/dist/types/core/effect.d.ts

@@ -3,6 +3,7 @@ export interface Effect<T> extends Computed<T>, Owner {
     _effectFn: (val: T, prev: T | undefined) => void | (() => void);
     _errorFn?: (err: unknown, cleanup: () => void) => void;
     _cleanup?: () => void;
+    _cleanupRegistered?: boolean;
     _modified: boolean;
     _prevValue: T | undefined;
     _type: number;
@@ -12,9 +13,10 @@ export interface Effect<T> extends Computed<T>, Owner {
  * automatically added to the queue of effects to re-execute, which will cause them to fetch their
  * sources and recompute
  */
-export declare function effect<T>(compute: (prev: T | undefined) => T, effect: (val: T, prev: T | undefined) => void | (() => void), error?: (err: unknown, cleanup: () => void) => void | (() => void), initialValue?: T, options?: NodeOptions<any> & {
-    render?: boolean;
+export declare function effect<T>(compute: (prev: T | undefined) => T, effect: (val: T, prev: T | undefined) => void | (() => void), error?: (err: unknown, cleanup: () => void) => void | (() => void), options?: NodeOptions<any> & {
+    user?: boolean;
     defer?: boolean;
+    schedule?: boolean;
 }): void;
 export interface TrackedEffect extends Computed<void> {
     _cleanup?: () => void;

package/dist/types/core/error.d.ts

@@ -1,3 +1,27 @@
+/**
+ * Thrown by a tracked read whose value is currently pending (an async memo /
+ * `createSignal(asyncFn)` / projection / store derivation that hasn't settled
+ * yet). Surfacing through the reactive graph is what suspends the consumer
+ * scope — the nearest enclosing `<Loading>` boundary catches the throw and
+ * renders its fallback until the source resolves.
+ *
+ * App code rarely catches this directly; `<Loading>` is the canonical
+ * handler. The error type is exposed for advanced cases — e.g. interop layers
+ * that bridge Solid's pending-throw protocol to a different async strategy,
+ * or tests that want to assert on the suspension shape.
+ *
+ * @example
+ * ```ts
+ * // Advanced: distinguish "not ready yet" from a real error in custom
+ * // boundary plumbing. App code should rely on `<Loading>` / `<Errored>`.
+ * try {
+ *   const value = readReactiveSource();
+ * } catch (err) {
+ *   if (err instanceof NotReadyError) throw err; // re-throw to suspend
+ *   reportError(err);
+ * }
+ * ```
+ */
 export declare class NotReadyError extends Error {
     source: any;
     constructor(source: any);

package/dist/types/core/external.d.ts

@@ -21,6 +21,25 @@ export declare let externalSourceConfig: {
  * @param config.factory receives `(fn, trigger)` — wrap fn execution in external tracking,
  *   call trigger when external deps change. Return `{ track, dispose }`.
  * @param config.untrack optional wrapper for `untrack` — disables external tracking too.
+ *
+ * @example
+ * ```ts
+ * // Bridge an external "subscribe / notify" library into Solid's graph.
+ * // `factory` wraps every Solid compute so the external library can attach
+ * // its own dependency tracker; `trigger` re-runs the compute on external
+ * // change. `untrack` mirrors Solid's `untrack()` into the external library
+ * // so that reads inside `untrack(...)` don't get tracked twice.
+ * enableExternalSource({
+ *   factory: (compute, trigger) => {
+ *     const sub = externalLib.subscribe(trigger);
+ *     return {
+ *       track: prev => externalLib.run(() => compute(prev)),
+ *       dispose: () => sub.unsubscribe()
+ *     };
+ *   },
+ *   untrack: fn => externalLib.untracked(fn)
+ * });
+ * ```
  */
 export declare function enableExternalSource(config: ExternalSourceConfig): void;
 export declare function _resetExternalSourceConfig(): void;

package/dist/types/core/graph.d.ts

@@ -1,3 +1,5 @@
 import type { Computed, Link, Signal } from "./types.js";
 export declare function unlinkSubs(link: Link): Link | null;
+export declare function trimStaleDeps(el: Computed<any>): void;
+export declare function unobserved(el: Computed<unknown>): void;
 export declare function link(dep: Signal<any> | Computed<any>, sub: Computed<any>): void;

package/dist/types/core/index.d.ts

@@ -1,5 +1,5 @@
 export { ContextNotFoundError, NoOwnerError, NotReadyError } from "./error.js";
-export { isEqual, untrack, runWithOwner, computed, signal, read, setSignal, optimisticSignal, optimisticComputed, isPending, latest, refresh, isRefreshing, staleValues, setSnapshotCapture, markSnapshotScope, releaseSnapshotScope, clearSnapshots } from "./core.js";
+export { isEqual, untrack, runWithOwner, computed, signal, read, setSignal, setMemo, suppressComputedRecompute, optimisticSignal, optimisticComputed, isPending, latest, refresh, isRefreshing, staleValues, setSnapshotCapture, markSnapshotScope, releaseSnapshotScope, clearSnapshots } from "./core.js";
 export { enableExternalSource, _resetExternalSourceConfig, type ExternalSourceFactory, type ExternalSource, type ExternalSourceConfig } from "./external.js";
 export { createOwner, createRoot, dispose, getNextChildId, getObserver, getOwner, isDisposed, cleanup, peekNextChildId } from "./owner.js";
 export { createContext, getContext, setContext, type Context, type ContextRecord } from "./context.js";

package/dist/types/core/owner.d.ts

@@ -2,21 +2,111 @@ import type { Computed, Disposable, Owner, Root } from "./types.js";
 export declare function markDisposal(el: Owner): void;
 export declare function dispose(node: Computed<unknown>): void;
 export declare function disposeChildren(node: Owner, self?: boolean, zombie?: boolean): void;
+/**
+ * Allocates and returns the next stable child id for `owner`. Used by
+ * hydration plumbing and `createUniqueId`. Not part of the user-facing API.
+ *
+ * @internal
+ */
 export declare function getNextChildId(owner: Owner): string;
+/**
+ * Returns the *next* child id for `owner` without consuming it. Used by
+ * hydration plumbing to peek at the id a future child will receive.
+ *
+ * @internal
+ */
 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.
+ *
+ * @example
+ * ```ts
+ * // Library predicate: only register a hot-path subscription when the
+ * // caller is inside a tracking scope (memo / effect compute / JSX).
+ * function trackIfTracked(source: () => unknown) {
+ *   if (getObserver()) source();
+ * }
+ * ```
+ */
 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). Pair with a captured owner to bail out of late callbacks whose
+ * surrounding component already unmounted.
+ *
+ * @example
+ * ```ts
+ * function onSettleSafe(fn: () => void) {
+ *   const owner = getOwner();
+ *   queueMicrotask(() => {
+ *     if (owner && isDisposed(owner)) return; // component unmounted; skip
+ *     runWithOwner(owner, fn);
+ *   });
+ * }
+ * ```
+ */
 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). Used by framework internals to group
+ * cleanups; app code should use `createRoot()` (host a reactive scope outside
+ * a component) or `runWithOwner()` (re-enter a captured owner).
+ *
+ * @internal
+ */
 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
  */