sibujs 4.1.0 → 4.2.0

package/dist/index.d.cts

@@ -193,9 +193,15 @@ type RuntimeErrorHandler = (error: unknown, context: RuntimeErrorContext) => voi
  * This is application/runtime-global state, NOT request-scoped: under SSR it is
  * shared by every concurrent request in the process. Install it once at startup
  * and derive any request-specific detail from the error/context instead.
+ *
+ * @returns The previously installed handler, so a caller can restore it.
  */
 declare function setRuntimeErrorHandler(handler: RuntimeErrorHandler | null): RuntimeErrorHandler | null;
-/** The currently installed runtime error handler, if any. */
+/**
+ * Read the currently installed runtime error handler.
+ *
+ * @returns The installed handler, or `null` when none is set.
+ */
 declare function getRuntimeErrorHandler(): RuntimeErrorHandler | null;
 /**
  * Report an error the runtime caught and contained.
@@ -440,45 +446,30 @@ declare function __resetIdCounter(): void;
  * Conditional rendering directive. Shows or hides an element reactively.
  * Unlike `when()`, the element is always created — it just toggles display.
  *
+ * Accepts the element either directly or as a thunk, so the same call shape
+ * works here and in {@link when}. Which one you pass changes nothing: `show`
+ * never rebuilds, so a thunk is invoked exactly once, immediately.
+ *
  * @param condition Reactive getter returning boolean
- * @param element The element to show/hide
- * @returns The element with reactive display binding
+ * @param element The element to show/hide, or a function returning it
+ * @returns The element itself (not a wrapper), with a reactive display binding.
+ * The caller keeps the live node and can mutate it or attach listeners to it.
  *
  * @example
  * ```ts
  * const [visible, setVisible] = signal(true);
  * div([show(() => visible(), span("I toggle!"))]);
+ * div([show(() => visible(), () => span("also fine"))]);
  * ```
- */
-declare function show<T extends Element>(condition: () => boolean, element: T): T;
-/**
- * Conditional rendering directive. Renders content only when condition is true.
- * When false, renders nothing (comment placeholder). Re-evaluates reactively.
- *
- * @param condition Reactive getter returning boolean
- * @param thenBranch Function returning element when true
- * @param elseBranch Optional function returning element when false
- * @returns A Comment anchor that manages the conditional content
  *
- * @example
- * ```ts
- * when(
- *   () => isLoggedIn(),
- *   () => div("Welcome!"),
- *   () => div("Please log in")
- * );
- * ```
- *
- * GOTCHA — branch factories rebuild only when `condition` changes. A signal
- * read *eagerly* inside a branch is captured once and never updates:
- * ```ts
- * when(() => show(), () => div(`Count: ${count()}`));        // ✗ frozen at first count
- * when(() => show(), () => div(() => `Count: ${count()}`));  // ✓ reactive text child
- * ```
- * Drive per-branch reactivity with a nested getter (or a reactive child), not a
- * bare read in the factory body.
+ * TRAP — `show` keeps the element in the DOM and toggles `display`. Use
+ * {@link when} when the content must not exist at all while hidden (an
+ * expensive subtree, or one whose mere presence is observable). Note that
+ * `when` REBUILDS on every condition change, which discards focus and
+ * selection inside the branch — see the note on `when`.
  */
-declare function when<T>(condition: () => T, thenBranch: () => NodeChild, elseBranch?: () => NodeChild): Comment;
+declare function show<T extends Element>(condition: () => boolean, element: T | (() => T)): T;
+declare function when<T>(condition: () => T, thenBranch: NodeChild, elseBranch?: NodeChild): Comment;
 /**
  * Pattern matching directive. Renders content based on matching a reactive value
  * against multiple cases. Similar to a switch statement.
@@ -504,8 +495,25 @@ declare function when<T>(condition: () => T, thenBranch: () => NodeChild, elseBr
  * GOTCHA — like `when()`, a case factory rebuilds only when the matched key
  * changes. A signal read eagerly inside a case is frozen at build time; use a
  * nested getter (`() => div(() => label())`) for reactive per-case content.
+ *
+ * THIS IS THE KEYING PATTERN for subtrees that hold a live edit. Because the
+ * subtree is rebuilt only when the KEY changes — not on every read of every
+ * signal inside it — a form can update its contents through reactive attributes
+ * and text children while its inputs keep focus, selection and IME state:
+ *
+ * ```ts
+ * // Rebuilds only when the form's shape changes, not on every keystroke.
+ * match(
+ *   () => `${entity()}:${mode()}`,
+ *   { "user:edit": () => UserForm(), "user:view": () => UserCard() },
+ * );
+ * ```
+ *
+ * Cases and the fallback accept a bare element as well as a factory, matching
+ * {@link when} and {@link show}. A bare element is re-attached rather than
+ * rebuilt, so it keeps whatever state it accumulated.
  */
-declare function match<T extends string | number>(value: () => T, cases: Record<string, () => NodeChild>, fallback?: () => NodeChild): Comment;
+declare function match<T extends string | number>(value: () => T, cases: Record<string, NodeChild>, fallback?: NodeChild): Comment;
 
 /**
  * Safety ceiling on the **total number of teardowns a single drain may execute**.
@@ -582,7 +590,9 @@ declare function replaceChildrenSafely(parent: ParentNode, ...next: Node[]): voi
 /**
  * Check for potential binding leaks. Returns the number of active DOM bindings.
  * In dev mode, logs a warning if the count exceeds the threshold.
- * In production, _isDev is false so the counter is always 0.
+ * In production, DEV is false so the counter is always 0.
+ *
+ * @returns Diagnostic counts of nodes still holding registered disposers.
  */
 declare function checkLeaks(warnThreshold?: number): number;
 
@@ -699,6 +709,9 @@ declare function Fragment(nodes: NodeChildren[]): DocumentFragment;
  * Templates are parsed once per call site and cached. Subsequent calls at the
  * same source location skip parsing entirely and only replay the cached
  * structure with fresh expression values.
+ *
+ * @returns The live DOM node (or fragment) the template describes — not a
+ * string, and not a virtual node.
  */
 declare function html(strings: TemplateStringsArray, ...values: unknown[]): Element;
 
@@ -1004,6 +1017,15 @@ interface KeepAliveOptions {
  */
 declare function KeepAlive(activeKey: () => string, cases: Record<string, () => Node>, options?: KeepAliveOptions): Comment;
 
+/**
+ * Read and CLEAR an error stashed on a node by an async boundary.
+ *
+ * Consuming is the point: an error handed to one boundary must not also reach
+ * an outer one, so this is deliberately not a plain getter.
+ *
+ * @param node Element the error was stashed on.
+ * @returns The pending error, or `undefined` when there is none.
+ */
 declare function takePendingError(node: Element): Error | undefined;
 type Component = () => HTMLElement;
 type LazyImport = () => Promise<{
@@ -1051,6 +1073,18 @@ interface SuspenseProps {
     nodes: () => HTMLElement;
     fallback: () => HTMLElement;
 }
+/**
+ * Render `fallback` until the async `nodes` factory resolves, then swap it for
+ * the resolved content.
+ *
+ * @param props `nodes` is the async content factory; `fallback` builds the
+ * placeholder shown while it is pending.
+ * @returns The live container element, already holding the fallback.
+ *
+ * TRAP — the swap REPLACES the container's children, so focus and selection in
+ * the fallback are discarded. That is usually harmless (a spinner rarely holds
+ * focus) but matters for a skeleton form; see the note on `when`.
+ */
 declare function Suspense({ nodes, fallback }: SuspenseProps): HTMLElement;
 
 /**
@@ -1119,6 +1153,11 @@ declare function onCleanup(callback: CleanupFn, element: Node): void;
 /**
  * Mounts a root component into a DOM element.
  * Supports both function components and pre-created HTMLElements.
+ *
+ * @param component Component function, or an already-built Element/Node.
+ * @param container Element to mount into.
+ * @returns `{ node, unmount }` — the live root node, and a teardown that
+ * disposes the tree and removes it.
  */
 declare function mount(component: (() => Element) | Element | Node, container: Element | null): {
     node: Node;
@@ -1151,6 +1190,13 @@ declare function Portal(nodes: () => HTMLElement, target?: HTMLElement): Comment
 
 type SlotFn = () => Element | string | number | null | undefined;
 type Slots = Record<string, SlotFn>;
+/**
+ * Look up a named slot factory.
+ *
+ * @param slots The slot map, which may be undefined.
+ * @param name Slot name; defaults to `"default"`.
+ * @returns The slot factory, or `undefined` when the slot was not provided.
+ */
 declare function getSlot(slots: Slots | undefined, name?: string): SlotFn | undefined;
 
 declare const __accessor: unique symbol;
@@ -1184,6 +1230,8 @@ interface SignalOptions<T = unknown> {
  *
  * @param initial Initial value
  * @param options Optional config: `{ name: "count" }` for devtools labeling
+ * @returns A `[getter, setter]` tuple. Calling the getter inside a reactive
+ * context subscribes to the signal; the setter accepts a value or an updater.
  */
 declare function signal<T>(initial: T, options?: SignalOptions<T>): StateTuple<T>;
 /**
@@ -1298,6 +1346,14 @@ interface ArrayActions<T> {
     /** Clear all items */
     clear(): void;
 }
+/**
+ * A signal holding an array, plus mutation helpers that write a NEW array each
+ * time so the signal actually notifies.
+ *
+ * @param initial Starting items; copied, so the caller's array is not aliased.
+ * @returns A `[accessor, actions]` pair — `actions` carries `push`, `remove`,
+ * `insert`, `move`, `clear` and friends.
+ */
 declare function array<T>(initial?: T[]): [Accessor<T[]>, ArrayActions<T>];
 /**
  * Optimized reactive array hook. Uses in-place mutations with a version
@@ -1406,6 +1462,9 @@ interface AsyncDerivedContext {
  *   return r.json();
  * }, []);
  * ```
+ *
+ * @returns An accessor exposing the async result along with its loading and
+ * error state.
  */
 declare function asyncDerived<T>(factory: (context: AsyncDerivedContext) => Promise<T>, initial: T): AsyncDerivedState<T>;
 
@@ -1467,6 +1526,9 @@ declare function deepSignal<T>(initial: T): [Accessor<T>, (next: T | ((prev: T)
  * That keeps the cheap boolean dirty flag AND makes `equals` actually stop
  * propagation, with recomputation still fully lazy: `_validate` only ever runs
  * when an effect is genuinely about to observe the value.
+ *
+ * @returns An accessor for the computed value. It recomputes lazily on read
+ * after any dependency changes.
  */
 declare function derived<T>(getter: () => T, options?: {
     name?: string;
@@ -1522,6 +1584,9 @@ type EffectBody = (onCleanup: OnCleanup) => void;
  *   onCleanup(() => window.removeEventListener("resize", handler));
  * });
  * ```
+ *
+ * @returns A dispose function that stops the effect and releases its
+ * dependencies. Idempotent.
  */
 declare function effect(effectFn: EffectBody | (() => void), options?: EffectOptions): () => void;
 
@@ -1629,6 +1694,8 @@ declare function watch<T>(getter: () => T, callback: (value: T, prev: T | undefi
  * lastName();              // "Smith"
  * fullName();              // "Jane Smith"
  * ```
+ *
+ * @returns A store handle with `subscribe`, `set` and `update`.
  */
 declare function writable<T>(get: () => T, set: (value: T) => void, options?: {
     name?: string;
@@ -2106,20 +2173,74 @@ declare function transition(): TransitionState;
 declare function nextTick(): Promise<void>;
 
 type Subscriber = () => void;
+/**
+ * Stop recording dependency edges until the matching {@link resumeTracking}.
+ * Nestable — the depth is counted, so an inner pair does not resume early.
+ *
+ * Prefer {@link untracked}, which pairs the two calls for you even when the
+ * body throws. Reach for the raw pair only when the suspended region cannot be
+ * expressed as a single function.
+ *
+ * @returns Nothing.
+ */
 declare function suspendTracking(): void;
+/**
+ * Undo one {@link suspendTracking}. Dependency recording resumes only when the
+ * outermost pair closes.
+ *
+ * @returns Nothing.
+ */
 declare function resumeTracking(): void;
 /** Read the "tracking suspended" flag (used by derived's lazy path). */
 declare function isTrackingSuspended(): boolean;
+/**
+ * Run `fn` without recording anything it reads as a dependency.
+ *
+ * The suspension is released even if `fn` throws, which is the reason to prefer
+ * this over a manual suspend/resume pair.
+ *
+ * @param fn Function to run outside dependency tracking.
+ * @returns Whatever `fn` returns.
+ */
 declare function untracked$1<T>(fn: () => T): T;
 declare function retrack$1(effectFn: () => void, subscriber: Subscriber): void;
 declare function track(effectFn: () => void, subscriber?: Subscriber): () => void;
 declare function reactiveBinding(commit: () => void, ownerNode?: unknown): () => void;
 declare function recordDependency(signal: ReactiveSignal): void;
 declare function cleanup(subscriber: Subscriber): void;
+/**
+ * Cap how many times one subscriber may re-run within a single drain before it
+ * is quarantined as a runaway cycle. A safety valve, not a tuning knob.
+ *
+ * @param n New limit; ignored unless finite and positive.
+ * @returns The previous limit, so a caller can restore it.
+ */
 declare function setMaxSubscriberRepeats(n: number): number;
+/**
+ * Cap how many passes one notification drain may make before giving up on a
+ * self-refeeding update cycle.
+ *
+ * @param n New limit; ignored unless finite and positive.
+ * @returns The previous limit, so a caller can restore it.
+ */
 declare function setMaxDrainIterations$1(n: number): number;
+/**
+ * Flush queued signal notifications, running every dirty subscriber.
+ *
+ * Re-entrant calls are ignored: a write performed from inside a subscriber adds
+ * to the queue the current drain is already working through, rather than
+ * starting a nested one.
+ *
+ * @returns Nothing.
+ */
 declare function drainNotificationQueue(): void;
 declare function queueSignalNotification(signal: ReactiveSignal): void;
+/**
+ * Mark every subscriber of `signal` dirty and queue them for the next drain.
+ *
+ * @param signal The signal that changed.
+ * @returns Nothing.
+ */
 declare function notifySubscribers(signal: ReactiveSignal): void;
 /** O(1) subscriber count for devtools / introspection. */
 declare function getSubscriberCount(signal: ReactiveSignal): number;

package/dist/index.d.ts

@@ -193,9 +193,15 @@ type RuntimeErrorHandler = (error: unknown, context: RuntimeErrorContext) => voi
  * This is application/runtime-global state, NOT request-scoped: under SSR it is
  * shared by every concurrent request in the process. Install it once at startup
  * and derive any request-specific detail from the error/context instead.
+ *
+ * @returns The previously installed handler, so a caller can restore it.
  */
 declare function setRuntimeErrorHandler(handler: RuntimeErrorHandler | null): RuntimeErrorHandler | null;
-/** The currently installed runtime error handler, if any. */
+/**
+ * Read the currently installed runtime error handler.
+ *
+ * @returns The installed handler, or `null` when none is set.
+ */
 declare function getRuntimeErrorHandler(): RuntimeErrorHandler | null;
 /**
  * Report an error the runtime caught and contained.
@@ -440,45 +446,30 @@ declare function __resetIdCounter(): void;
  * Conditional rendering directive. Shows or hides an element reactively.
  * Unlike `when()`, the element is always created — it just toggles display.
  *
+ * Accepts the element either directly or as a thunk, so the same call shape
+ * works here and in {@link when}. Which one you pass changes nothing: `show`
+ * never rebuilds, so a thunk is invoked exactly once, immediately.
+ *
  * @param condition Reactive getter returning boolean
- * @param element The element to show/hide
- * @returns The element with reactive display binding
+ * @param element The element to show/hide, or a function returning it
+ * @returns The element itself (not a wrapper), with a reactive display binding.
+ * The caller keeps the live node and can mutate it or attach listeners to it.
  *
  * @example
  * ```ts
  * const [visible, setVisible] = signal(true);
  * div([show(() => visible(), span("I toggle!"))]);
+ * div([show(() => visible(), () => span("also fine"))]);
  * ```
- */
-declare function show<T extends Element>(condition: () => boolean, element: T): T;
-/**
- * Conditional rendering directive. Renders content only when condition is true.
- * When false, renders nothing (comment placeholder). Re-evaluates reactively.
- *
- * @param condition Reactive getter returning boolean
- * @param thenBranch Function returning element when true
- * @param elseBranch Optional function returning element when false
- * @returns A Comment anchor that manages the conditional content
  *
- * @example
- * ```ts
- * when(
- *   () => isLoggedIn(),
- *   () => div("Welcome!"),
- *   () => div("Please log in")
- * );
- * ```
- *
- * GOTCHA — branch factories rebuild only when `condition` changes. A signal
- * read *eagerly* inside a branch is captured once and never updates:
- * ```ts
- * when(() => show(), () => div(`Count: ${count()}`));        // ✗ frozen at first count
- * when(() => show(), () => div(() => `Count: ${count()}`));  // ✓ reactive text child
- * ```
- * Drive per-branch reactivity with a nested getter (or a reactive child), not a
- * bare read in the factory body.
+ * TRAP — `show` keeps the element in the DOM and toggles `display`. Use
+ * {@link when} when the content must not exist at all while hidden (an
+ * expensive subtree, or one whose mere presence is observable). Note that
+ * `when` REBUILDS on every condition change, which discards focus and
+ * selection inside the branch — see the note on `when`.
  */
-declare function when<T>(condition: () => T, thenBranch: () => NodeChild, elseBranch?: () => NodeChild): Comment;
+declare function show<T extends Element>(condition: () => boolean, element: T | (() => T)): T;
+declare function when<T>(condition: () => T, thenBranch: NodeChild, elseBranch?: NodeChild): Comment;
 /**
  * Pattern matching directive. Renders content based on matching a reactive value
  * against multiple cases. Similar to a switch statement.
@@ -504,8 +495,25 @@ declare function when<T>(condition: () => T, thenBranch: () => NodeChild, elseBr
  * GOTCHA — like `when()`, a case factory rebuilds only when the matched key
  * changes. A signal read eagerly inside a case is frozen at build time; use a
  * nested getter (`() => div(() => label())`) for reactive per-case content.
+ *
+ * THIS IS THE KEYING PATTERN for subtrees that hold a live edit. Because the
+ * subtree is rebuilt only when the KEY changes — not on every read of every
+ * signal inside it — a form can update its contents through reactive attributes
+ * and text children while its inputs keep focus, selection and IME state:
+ *
+ * ```ts
+ * // Rebuilds only when the form's shape changes, not on every keystroke.
+ * match(
+ *   () => `${entity()}:${mode()}`,
+ *   { "user:edit": () => UserForm(), "user:view": () => UserCard() },
+ * );
+ * ```
+ *
+ * Cases and the fallback accept a bare element as well as a factory, matching
+ * {@link when} and {@link show}. A bare element is re-attached rather than
+ * rebuilt, so it keeps whatever state it accumulated.
  */
-declare function match<T extends string | number>(value: () => T, cases: Record<string, () => NodeChild>, fallback?: () => NodeChild): Comment;
+declare function match<T extends string | number>(value: () => T, cases: Record<string, NodeChild>, fallback?: NodeChild): Comment;
 
 /**
  * Safety ceiling on the **total number of teardowns a single drain may execute**.
@@ -582,7 +590,9 @@ declare function replaceChildrenSafely(parent: ParentNode, ...next: Node[]): voi
 /**
  * Check for potential binding leaks. Returns the number of active DOM bindings.
  * In dev mode, logs a warning if the count exceeds the threshold.
- * In production, _isDev is false so the counter is always 0.
+ * In production, DEV is false so the counter is always 0.
+ *
+ * @returns Diagnostic counts of nodes still holding registered disposers.
  */
 declare function checkLeaks(warnThreshold?: number): number;
 
@@ -699,6 +709,9 @@ declare function Fragment(nodes: NodeChildren[]): DocumentFragment;
  * Templates are parsed once per call site and cached. Subsequent calls at the
  * same source location skip parsing entirely and only replay the cached
  * structure with fresh expression values.
+ *
+ * @returns The live DOM node (or fragment) the template describes — not a
+ * string, and not a virtual node.
  */
 declare function html(strings: TemplateStringsArray, ...values: unknown[]): Element;
 
@@ -1004,6 +1017,15 @@ interface KeepAliveOptions {
  */
 declare function KeepAlive(activeKey: () => string, cases: Record<string, () => Node>, options?: KeepAliveOptions): Comment;
 
+/**
+ * Read and CLEAR an error stashed on a node by an async boundary.
+ *
+ * Consuming is the point: an error handed to one boundary must not also reach
+ * an outer one, so this is deliberately not a plain getter.
+ *
+ * @param node Element the error was stashed on.
+ * @returns The pending error, or `undefined` when there is none.
+ */
 declare function takePendingError(node: Element): Error | undefined;
 type Component = () => HTMLElement;
 type LazyImport = () => Promise<{
@@ -1051,6 +1073,18 @@ interface SuspenseProps {
     nodes: () => HTMLElement;
     fallback: () => HTMLElement;
 }
+/**
+ * Render `fallback` until the async `nodes` factory resolves, then swap it for
+ * the resolved content.
+ *
+ * @param props `nodes` is the async content factory; `fallback` builds the
+ * placeholder shown while it is pending.
+ * @returns The live container element, already holding the fallback.
+ *
+ * TRAP — the swap REPLACES the container's children, so focus and selection in
+ * the fallback are discarded. That is usually harmless (a spinner rarely holds
+ * focus) but matters for a skeleton form; see the note on `when`.
+ */
 declare function Suspense({ nodes, fallback }: SuspenseProps): HTMLElement;
 
 /**
@@ -1119,6 +1153,11 @@ declare function onCleanup(callback: CleanupFn, element: Node): void;
 /**
  * Mounts a root component into a DOM element.
  * Supports both function components and pre-created HTMLElements.
+ *
+ * @param component Component function, or an already-built Element/Node.
+ * @param container Element to mount into.
+ * @returns `{ node, unmount }` — the live root node, and a teardown that
+ * disposes the tree and removes it.
  */
 declare function mount(component: (() => Element) | Element | Node, container: Element | null): {
     node: Node;
@@ -1151,6 +1190,13 @@ declare function Portal(nodes: () => HTMLElement, target?: HTMLElement): Comment
 
 type SlotFn = () => Element | string | number | null | undefined;
 type Slots = Record<string, SlotFn>;
+/**
+ * Look up a named slot factory.
+ *
+ * @param slots The slot map, which may be undefined.
+ * @param name Slot name; defaults to `"default"`.
+ * @returns The slot factory, or `undefined` when the slot was not provided.
+ */
 declare function getSlot(slots: Slots | undefined, name?: string): SlotFn | undefined;
 
 declare const __accessor: unique symbol;
@@ -1184,6 +1230,8 @@ interface SignalOptions<T = unknown> {
  *
  * @param initial Initial value
  * @param options Optional config: `{ name: "count" }` for devtools labeling
+ * @returns A `[getter, setter]` tuple. Calling the getter inside a reactive
+ * context subscribes to the signal; the setter accepts a value or an updater.
  */
 declare function signal<T>(initial: T, options?: SignalOptions<T>): StateTuple<T>;
 /**
@@ -1298,6 +1346,14 @@ interface ArrayActions<T> {
     /** Clear all items */
     clear(): void;
 }
+/**
+ * A signal holding an array, plus mutation helpers that write a NEW array each
+ * time so the signal actually notifies.
+ *
+ * @param initial Starting items; copied, so the caller's array is not aliased.
+ * @returns A `[accessor, actions]` pair — `actions` carries `push`, `remove`,
+ * `insert`, `move`, `clear` and friends.
+ */
 declare function array<T>(initial?: T[]): [Accessor<T[]>, ArrayActions<T>];
 /**
  * Optimized reactive array hook. Uses in-place mutations with a version
@@ -1406,6 +1462,9 @@ interface AsyncDerivedContext {
  *   return r.json();
  * }, []);
  * ```
+ *
+ * @returns An accessor exposing the async result along with its loading and
+ * error state.
  */
 declare function asyncDerived<T>(factory: (context: AsyncDerivedContext) => Promise<T>, initial: T): AsyncDerivedState<T>;
 
@@ -1467,6 +1526,9 @@ declare function deepSignal<T>(initial: T): [Accessor<T>, (next: T | ((prev: T)
  * That keeps the cheap boolean dirty flag AND makes `equals` actually stop
  * propagation, with recomputation still fully lazy: `_validate` only ever runs
  * when an effect is genuinely about to observe the value.
+ *
+ * @returns An accessor for the computed value. It recomputes lazily on read
+ * after any dependency changes.
  */
 declare function derived<T>(getter: () => T, options?: {
     name?: string;
@@ -1522,6 +1584,9 @@ type EffectBody = (onCleanup: OnCleanup) => void;
  *   onCleanup(() => window.removeEventListener("resize", handler));
  * });
  * ```
+ *
+ * @returns A dispose function that stops the effect and releases its
+ * dependencies. Idempotent.
  */
 declare function effect(effectFn: EffectBody | (() => void), options?: EffectOptions): () => void;
 
@@ -1629,6 +1694,8 @@ declare function watch<T>(getter: () => T, callback: (value: T, prev: T | undefi
  * lastName();              // "Smith"
  * fullName();              // "Jane Smith"
  * ```
+ *
+ * @returns A store handle with `subscribe`, `set` and `update`.
  */
 declare function writable<T>(get: () => T, set: (value: T) => void, options?: {
     name?: string;
@@ -2106,20 +2173,74 @@ declare function transition(): TransitionState;
 declare function nextTick(): Promise<void>;
 
 type Subscriber = () => void;
+/**
+ * Stop recording dependency edges until the matching {@link resumeTracking}.
+ * Nestable — the depth is counted, so an inner pair does not resume early.
+ *
+ * Prefer {@link untracked}, which pairs the two calls for you even when the
+ * body throws. Reach for the raw pair only when the suspended region cannot be
+ * expressed as a single function.
+ *
+ * @returns Nothing.
+ */
 declare function suspendTracking(): void;
+/**
+ * Undo one {@link suspendTracking}. Dependency recording resumes only when the
+ * outermost pair closes.
+ *
+ * @returns Nothing.
+ */
 declare function resumeTracking(): void;
 /** Read the "tracking suspended" flag (used by derived's lazy path). */
 declare function isTrackingSuspended(): boolean;
+/**
+ * Run `fn` without recording anything it reads as a dependency.
+ *
+ * The suspension is released even if `fn` throws, which is the reason to prefer
+ * this over a manual suspend/resume pair.
+ *
+ * @param fn Function to run outside dependency tracking.
+ * @returns Whatever `fn` returns.
+ */
 declare function untracked$1<T>(fn: () => T): T;
 declare function retrack$1(effectFn: () => void, subscriber: Subscriber): void;
 declare function track(effectFn: () => void, subscriber?: Subscriber): () => void;
 declare function reactiveBinding(commit: () => void, ownerNode?: unknown): () => void;
 declare function recordDependency(signal: ReactiveSignal): void;
 declare function cleanup(subscriber: Subscriber): void;
+/**
+ * Cap how many times one subscriber may re-run within a single drain before it
+ * is quarantined as a runaway cycle. A safety valve, not a tuning knob.
+ *
+ * @param n New limit; ignored unless finite and positive.
+ * @returns The previous limit, so a caller can restore it.
+ */
 declare function setMaxSubscriberRepeats(n: number): number;
+/**
+ * Cap how many passes one notification drain may make before giving up on a
+ * self-refeeding update cycle.
+ *
+ * @param n New limit; ignored unless finite and positive.
+ * @returns The previous limit, so a caller can restore it.
+ */
 declare function setMaxDrainIterations$1(n: number): number;
+/**
+ * Flush queued signal notifications, running every dirty subscriber.
+ *
+ * Re-entrant calls are ignored: a write performed from inside a subscriber adds
+ * to the queue the current drain is already working through, rather than
+ * starting a nested one.
+ *
+ * @returns Nothing.
+ */
 declare function drainNotificationQueue(): void;
 declare function queueSignalNotification(signal: ReactiveSignal): void;
+/**
+ * Mark every subscriber of `signal` dirty and queue them for the next drain.
+ *
+ * @param signal The signal that changed.
+ * @returns Nothing.
+ */
 declare function notifySubscribers(signal: ReactiveSignal): void;
 /** O(1) subscriber count for devtools / introspection. */
 declare function getSubscriberCount(signal: ReactiveSignal): number;