sigula 1.0.4 → 2.0.1

package/dist/sigula.d.ts

@@ -1,130 +1,726 @@
-//#region src/boundary.d.ts
+//#region src/core/boundary.d.ts
+/**
+ * An inclusive range of sibling nodes (`start` through `end`).
+ *
+ * @group Low-level API
+ */
 export interface Boundary {
+  /** The first node in the range. */
   start: Node;
+  /** The last node in the range. */
   end: Node;
 }
+/**
+ * Visits every node from `b.start` through `b.end`.
+ *
+ * @param b - the boundary to walk.
+ * @param fn - called with each node.
+ * @group Low-level API
+ */
 export declare const walkBoundary: (b: Boundary, fn: (node: Node) => void) => void;
+/**
+ * Removes every node in the boundary. No-op if the boundary has no parent.
+ *
+ * @param b - the boundary to remove.
+ * @group Low-level API
+ */
 export declare const removeBoundary: (b: Boundary) => void;
+/**
+ * Wraps a node in a {@link Boundary}. A `DocumentFragment` spans its first and
+ * last child; any other node covers itself. Throws `E2` on an empty fragment.
+ *
+ * @param node - the node to wrap.
+ * @returns the node's boundary.
+ * @group Low-level API
+ */
 export declare const toBoundary: (node: Node) => Boundary;
+/**
+ * Replaces an entire boundary with `node` and returns the new boundary. Throws
+ * `E3` if the old boundary has no parent.
+ *
+ * @param old - the boundary to replace.
+ * @param node - the replacement node.
+ * @returns the boundary of the inserted node.
+ * @group Low-level API
+ */
 export declare const replaceWithNode: (old: Boundary, node: Node) => Boundary;
 //#endregion
-//#region src/cmd.d.ts
+//#region src/core/cmd.d.ts
+/**
+ * Base type for command contexts: an arbitrary string-keyed record.
+ *
+ * @group Low-level API
+ */
 export interface CmdContext {
+  /** Any string key; values are unconstrained. */
   [key: string]: unknown;
 }
+/**
+ * The unit of work a binding runs: it receives the current value and context.
+ *
+ * @typeParam T - the value type.
+ * @typeParam C - the context type.
+ * @group Low-level API
+ */
 export type Cmd<T, C extends CmdContext> = (val: T, context: C) => void;
+/**
+ * A {@link Cmd} with erased value and context types.
+ *
+ * @group Low-level API
+ */
 export type AnyCmd = Cmd<any, any>;
 //#endregion
-//#region src/eq.d.ts
+//#region src/core/eq.d.ts
+/**
+ * Implement this on a value type to give `eq` custom equality semantics.
+ *
+ * @group Reactivity
+ */
 export interface Equatable {
+  /** Returns whether `this` and `other` are equal. */
   equals(other: unknown): boolean;
 }
+/**
+ * A value equality function.
+ *
+ * @typeParam T - the value type.
+ * @group Reactivity
+ */
+export type Eq<T> = (a: T, b: T) => boolean;
+/**
+ * Convenience alias for an arbitrary string-keyed object.
+ *
+ * @group Reactivity
+ */
 export type UnknownRecord = Record<string, unknown>;
-export declare const isEqual: <T>(a: T, b: T) => boolean;
+/**
+ * Deep structural equality. Compares primitives, arrays, `Date`, `RegExp`,
+ * `Map`, `Set`, and plain objects, and defers to `a.equals(b)` when `a`
+ * implements `Equatable`. This is the default comparator for `Sig.update` and
+ * `repeat`. Values with different prototypes are never equal.
+ *
+ * @typeParam T - the value type.
+ * @param a - the first value.
+ * @param b - the second value.
+ * @returns `true` when `a` and `b` are deeply equal.
+ * @group Reactivity
+ */
+export declare const eq: <T>(a: T, b: T) => boolean;
 //#endregion
-//#region src/sig.bind.d.ts
+//#region src/core/sig.bind.d.ts
+/**
+ * A registered binding: the signal, its command context, and the command that
+ * runs when the signal changes.
+ *
+ * @typeParam T - the signal's value type.
+ * @typeParam C - the command context type.
+ * @group Reactivity
+ */
 export interface Bind<T, C extends CmdContext> {
+  /** The signal this binding observes. */
   sig: Sig<T>;
+  /** The context passed to `cmd` on each run. */
   context: C;
+  /** The command run with the current value and context. */
   cmd: Cmd<T, C>;
+  /** Set when the binding is detached; a removed binding is skipped. */
   removed: boolean;
+  /** Queue flag; true while the binding is queued for the next flush. */
   queued?: boolean;
 }
+/**
+ * A {@link Bind} with erased value and context types.
+ *
+ * @group Reactivity
+ */
 export type AnyBind = Bind<any, any>;
+/**
+ * The core reactive value. A `Sig` holds a value and a set of bindings that run
+ * when it changes; writes are queued and coalesced in a microtask.
+ *
+ * @typeParam T - the value type.
+ * @group Reactivity
+ */
 export declare class Sig<T> implements Equatable {
   private _val;
   private _binds;
-  constructor(val: T);
+  private _eq;
+  constructor(val: T, opts?: {
+    eq?: Eq<T>;
+  });
+  /** `Equatable` implementation; two `Sig`s are equal when their values are deeply equal. */
   equals(b: unknown): boolean;
+  /** Reads the current value. */
   get(): T;
+  /** Enqueues dependents without changing the value; use after in-place mutation. */
+  notify(): void;
+  /** Sets the value and always notifies dependents, even when deeply equal. */
   forceUpdate(v: T): void;
+  /** Sets the value and notifies dependents only when `eq(v, current)` is false. */
   update(v: T): void;
+  /** Applies `fn` to the current value via `update`, so an equal result is skipped. */
   trans(fn: (v: T) => T): void;
+  /** Registers a binding. Prefer `createBind` or the `patch`/`text`/`view` APIs. */
   addBind<C extends CmdContext>(bind: Bind<T, C>): void;
+  /** Unregisters a binding; runs `cleanup()` when the last one goes away. */
   removeBind<C extends CmdContext>(bind: Bind<T, C>): void;
+  /** Returns the current bindings. */
   getBinds(): Bind<T, CmdContext>[];
+  /** Overridable hook called when a signal loses all bindings. No-op on `Sig`. */
   cleanup(): void;
 }
+/**
+ * A `Sig` produced by {@link compute}. Extends `Sig` and additionally tracks the
+ * source bindings that feed it: it detaches from its sources when it loses its
+ * last consumer, and re-links and recomputes once when a consumer is added
+ * again.
+ *
+ * @typeParam T - the derived value type.
+ * @group Reactivity
+ */
 export declare class DerivedSig<T> extends Sig<T> {
   private _fromBinds;
   private _linked;
+  /** Registers a source binding. */
   addFromBind<S, C extends CmdContext>(bind: Bind<S, C>): void;
+  /** Registers a consumer; re-links to sources and recomputes once if detached. */
   addBind<C extends CmdContext>(bind: Bind<T, C>): void;
+  /** Removes every source binding when the derived signal has no consumers. */
   cleanup(): void;
 }
-export declare const sig: <T>(v: T) => Sig<T>;
+/**
+ * Creates a writable signal holding `v`.
+ *
+ * @param v - the initial value.
+ * @param opts - optional settings; `eq` overrides the comparator used by `update`.
+ * @returns a new `Sig` for `v`.
+ * @example
+ * ```ts
+ * const count = sig(0);
+ * count.get();     // 0
+ * count.update(1); // schedules dependents
+ * ```
+ * @group Reactivity
+ */
+export declare const sig: <T>(v: T, opts?: {
+  eq?: Eq<T>;
+}) => Sig<T>;
+/**
+ * Detaches a binding and marks it removed so queued runs are skipped.
+ *
+ * @typeParam T - the signal's value type.
+ * @typeParam C - the command context type.
+ * @param bind - the binding to remove.
+ * @group Reactivity
+ */
 export declare const removeBind: <T, C extends CmdContext>(bind: Bind<T, C>) => void;
+/**
+ * Wires `cmd(sig.get(), context)` to run whenever `sig` changes.
+ *
+ * @typeParam T - the signal's value type.
+ * @typeParam C - the command context type.
+ * @param sig - the signal to observe.
+ * @param context - the context passed to `cmd`.
+ * @param cmd - the command run on change.
+ * @returns the registered binding.
+ * @group Reactivity
+ */
 export declare const createBind: <T, C extends CmdContext>(sig: Sig<T>, context: C, cmd: Cmd<T, C>) => Bind<T, C>;
+/**
+ * A value that may be plain, a `Sig`, or `undefined`.
+ *
+ * @typeParam T - the underlying value type.
+ * @group Reactivity
+ */
+export type Reactive<T> = T | Sig<T> | undefined;
 //#endregion
-//#region src/compute.d.ts
+//#region src/core/compute.d.ts
+/**
+ * A record whose values are signals, used by the record overload of
+ * {@link compute}.
+ *
+ * @group Reactivity
+ */
 export interface SigRecord {
+  /** Each key maps to a signal of any value type. */
   [key: string]: Sig<any>;
 }
+/**
+ * Maps a {@link SigRecord} to a record of the signals' values.
+ *
+ * @typeParam K - the signal record type.
+ * @group Reactivity
+ */
 export type ValRecord<K extends SigRecord> = { [P in keyof K]: K[P] extends Sig<infer U> ? U : never; };
+/**
+ * Derives a signal from one source signal. The result recomputes whenever
+ * `source` changes.
+ *
+ * @typeParam S - the source value type.
+ * @typeParam T - the derived value type.
+ * @param source - the source signal.
+ * @param fn - maps the source value to the derived value.
+ * @returns a `DerivedSig` for the mapped value.
+ * @example
+ * ```ts
+ * const x = sig(1);
+ * const doubled = compute(x, (v) => v * 2);
+ * ```
+ * @group Reactivity
+ */
 export declare function compute<S, T>(source: Sig<S>, fn: (v: S) => T): DerivedSig<T>;
+/**
+ * Derives a signal from a record of signals; `fn` receives the matching record
+ * of values. The result recomputes whenever any source changes.
+ *
+ * @typeParam S - the signal record type.
+ * @typeParam T - the derived value type.
+ * @param source - a record of signals.
+ * @param fn - maps the record of values to the derived value.
+ * @returns a `DerivedSig` for the mapped value.
+ * @example
+ * ```ts
+ * const sum = compute({x, y}, (v) => v.x + v.y);
+ * ```
+ * @group Reactivity
+ */
 export declare function compute<S extends SigRecord, T>(source: S, fn: (v: ValRecord<S>) => T): DerivedSig<T>;
 //#endregion
-//#region src/patch.d.ts
+//#region src/core/err.d.ts
+/**
+ * Throws an `Error` whose message is the short `code` (for example `E2` or
+ * `E11:1:2`). The full text for each code lives in the README error table, so
+ * string tables stay out of the bundle.
+ *
+ * @param code - the coded error message.
+ * @group Low-level API
+ */
+export declare function err(code: string): never;
+//#endregion
+//#region src/core/patch.core.d.ts
+/**
+ * A collection of deferred bindings to apply to one element, produced by
+ * {@link patch}.
+ *
+ * @group DOM bindings
+ */
+export interface Patch {
+  /** Discriminant identifying a patch. */
+  type: 'patch';
+  /** Deferred patch-item factories, resolved against the target element on mount. */
+  toPatchItems: ToAnyPatchItem[];
+  /** Detaches the bindings created when the patch was committed. */
+  cleanBinds: () => void;
+}
+/**
+ * Context passed to patch commands: the target node plus any extra arguments.
+ *
+ * @group DOM bindings
+ */
 export interface PatchContext extends CmdContext {
+  /** The element the binding applies to. */
   node: Node;
+  /** Extra arguments for the command, such as the attribute or style key. */
   extra?: unknown[];
 }
+/**
+ * One resolved patch binding: a source value, its context, and the command.
+ *
+ * @typeParam T - the source value type.
+ * @group DOM bindings
+ */
 export interface PatchItem<T> {
+  /** The plain value or `Sig` the command binds. */
   source: T | Sig<T>;
+  /** The context passed to `cmd`. */
   context: PatchContext;
+  /** The command run with the value and context. */
   cmd: Cmd<T, PatchContext>;
 }
+/**
+ * A factory that defers reading the target element until mount.
+ *
+ * @typeParam T - the source value type.
+ * @group DOM bindings
+ */
 export type ToPatchItem<T> = (el: Element) => PatchItem<T>;
+/**
+ * A {@link PatchItem} with an erased value type.
+ *
+ * @group DOM bindings
+ */
 export type AnyPatchItem = PatchItem<any>;
+/**
+ * A {@link ToPatchItem} with an erased value type.
+ *
+ * @group DOM bindings
+ */
 export type ToAnyPatchItem = (el: Element) => AnyPatchItem;
-export interface Patch {
-  type: 'patch';
-  toPatchItems: ToAnyPatchItem[];
-  cleanBinds: () => void;
-}
-export declare const patch: (...toPatchItems: ToAnyPatchItem[]) => Patch;
-export declare const id: <T>(source: T | Sig<T>) => ToPatchItem<T>;
-export declare const val: <T>(source: T | Sig<T>) => ToPatchItem<T>;
-export declare const attr: <T>(source: T | Sig<T>, key: string) => ToPatchItem<T>;
-export type WritableStyleKey = { [K in keyof CSSStyleDeclaration]: CSSStyleDeclaration[K] extends string ? K : never; }[keyof CSSStyleDeclaration];
-export declare const style: <T>(source: T | Sig<T>, key: WritableStyleKey) => ToPatchItem<T>;
-export declare const styleProperty: <T>(source: T | Sig<T>, key: string) => ToPatchItem<T>;
-export declare const toggleClass: <T>(source: T | Sig<T>, token: string) => ToPatchItem<T>;
-export declare const toggleClasses: <T>(source: T | Sig<T>, ...tokens: string[]) => ToPatchItem<T>;
-export type ActFn<T> = (node: Node, val?: T) => void;
-export declare const act: <T>(source: T | Sig<T>, fn: ActFn<T>) => ToPatchItem<T>;
-type _Listener<K extends keyof HTMLElementEventMap> = (this: HTMLElement, ev: HTMLElementEventMap[K]) => unknown;
-export declare const on: <K extends keyof HTMLElementEventMap>(type: K, listener: _Listener<K>, options?: boolean | AddEventListenerOptions) => ToPatchItem<_Listener<K>>;
 //#endregion
-//#region src/view.d.ts
+//#region src/core/utils.d.ts
+/**
+ * Reads `arr[index]`, throwing `E1:<index>` when it is out of range.
+ *
+ * @typeParam T - the element type.
+ * @param arr - the array to read from.
+ * @param index - the index to read.
+ * @returns the element at `index`.
+ * @group Low-level API
+ */
+export declare const at: <T>(arr: T[], index: number) => T;
+//#endregion
+//#region src/core/view.core.d.ts
+/**
+ * An item that can occupy a slot in a view's children: a view or a patch.
+ *
+ * @group Templates
+ */
 export type ChildView = AnyView | Patch;
+/**
+ * The unit returned by `html`, `text`, `raw`, `view`, `repeat`, `list`, and
+ * `frag`.
+ *
+ * @typeParam T - the bound value type.
+ * @typeParam C - the bind context type.
+ * @group Templates
+ */
 export interface View<T = unknown, C extends CmdContext = any> {
+  /** Discriminant identifying a view. */
   type: 'view';
+  /** The DOM node or `DocumentFragment` the view occupies. */
   node: Node;
+  /** The view's own binding, when it is reactive. */
   bind?: Bind<T, C> | undefined;
+  /** Detaches the view's bindings and, recursively, those of its children. */
   cleanBinds: () => void;
+  /** Returns the nodes the view currently occupies. */
   boundary: () => Boundary;
+  /** The interpolated children of a template view. */
   children?: ChildView[] | undefined;
 }
+/**
+ * A {@link View} with erased value and context types.
+ *
+ * @group Templates
+ */
 export type AnyView = View<any, any>;
+/**
+ * Context for the `view` command: the current inner view and the view factory.
+ *
+ * @typeParam T - the value type.
+ * @group Templates
+ */
 export interface ViewContext<T> extends CmdContext {
+  /** The currently mounted inner view. */
   inner: AnyView;
+  /** Builds the next inner view from a new value. */
   viewFn: (val: T) => AnyView;
 }
-export declare const view: <T>(sig: Sig<T>, viewFn: (val: T) => AnyView) => View<T, ViewContext<T>>;
+/**
+ * Replaces an existing boundary with a view's node and returns the new boundary.
+ *
+ * @param old - the boundary to replace.
+ * @param view - the view to mount.
+ * @returns the boundary of the mounted view.
+ * @group Templates
+ */
 export declare const replaceWithView: (old: Boundary, view: View) => Boundary;
 //#endregion
+//#region src/frag.d.ts
+/**
+ * Composes several views into one content-position view. The views' nodes are
+ * inserted as flat siblings, in order, with no wrapper element; nested
+ * fragments flatten. Reactivity comes from the child views. `frag()` with no
+ * arguments renders nothing.
+ *
+ * @param views - the views to compose.
+ * @returns a `View` rendering the views as siblings.
+ * @example
+ * ```ts
+ * html`<div>${frag(text('a'), html`<b>${text('b')}</b>`)}</div>`;
+ * ```
+ * @group Control flow
+ */
+export declare const frag: (...views: AnyView[]) => View;
+//#endregion
 //#region src/html.d.ts
-export declare const html: (strs: TemplateStringsArray, ...items: (Patch | AnyView)[]) => View;
+type TextValue = string | number | boolean | bigint | null | undefined;
+type HtmlItem = Patch | AnyView | TextValue | Sig<any>;
+/**
+ * Tagged template that parses native HTML and returns a {@link View}. Three
+ * kinds of interpolation are supported:
+ *
+ * - a `View` fills a content position;
+ * - a `Patch` (from `patch(...)`) fills an attribute position;
+ * - a plain value or a `Sig` fills a content position as text — a `Sig` binds
+ *   reactively and any other value becomes `String(value)`.
+ *
+ * Templates are cached per call site, so repeated renders skip parsing. Throws
+ * `E10` for an empty template, `E11:<expected>:<got>` for an interpolation-count
+ * mismatch, and `E12` for an unmatched interpolation (a `patch` in content
+ * position, or a text value in an attribute position).
+ *
+ * @param strs - the static template strings.
+ * @param rawItems - the interpolated views, patches, or text values.
+ * @returns the parsed `View`.
+ * @example
+ * ```ts
+ * html`<p>Hello, ${name}!</p>`;
+ * html`<button ${patch(on('click', handler))}>Go</button>`;
+ * ```
+ * @group Templates
+ */
+export declare const html: (strs: TemplateStringsArray, ...rawItems: HtmlItem[]) => View;
+//#endregion
+//#region src/list.d.ts
+/**
+ * Renders a fixed array in order. `viewFn` is called once per item with the item
+ * and its 0-based index, and each returned `AnyView` is appended in sequence.
+ * There is no keying or reconciliation and no reactive source; any reactivity
+ * comes from the views `viewFn` returns. An empty array renders
+ * `<!--empty-list-->`.
+ *
+ * @typeParam T - the item type.
+ * @param items - the items to render.
+ * @param viewFn - builds the view for an item and its index.
+ * @returns a `View` rendering the items.
+ * @example
+ * ```ts
+ * html`<ul>${list(items, (item, i) => html`<li>${i}: ${text(item)}</li>`)}</ul>`;
+ * ```
+ * @group Control flow
+ */
+export declare const list: <T>(items: readonly T[], viewFn: (item: T, index: number) => AnyView) => View;
+//#endregion
+//#region src/patch.d.ts
+/**
+ * Object form for {@link patch}, desugared into commands in key order:
+ * `id`, `val`, `class` (per entry, via `toggleClass`), `style` (per entry,
+ * via `style`), `styleProp` (per entry), `on` (per entry), and any other key
+ * via `attr`. A key whose value is `undefined` is skipped.
+ *
+ * @group DOM bindings
+ */
+export interface PatchProps {
+  /** Sets the element's `id`. */
+  id?: Reactive<string>;
+  /** Sets the element's `value` property. */
+  val?: Reactive<string>;
+  /** Toggles each class from the truthiness of its value. */
+  class?: Record<string, Reactive<boolean>>;
+  /** Sets inline style properties by typed name. */
+  style?: Partial<Record<WritableStyleKey, Reactive<string>>>;
+  /** Sets style properties via `setProperty` (custom properties, untyped names). */
+  styleProp?: Record<string, Reactive<string>>;
+  /** Registers DOM event listeners. */
+  on?: { [K in keyof HTMLElementEventMap]?: (ev: HTMLElementEventMap[K]) => void; };
+  /** Any other key is set as an attribute via `attr`. */
+  [attr: string]: unknown;
+}
+/**
+ * Declares one or more bindings to apply to the same element; must be
+ * interpolated in an attribute position. Each command receives a plain value
+ * (applied once) or a `Sig` (applied on mount and re-applied on change).
+ *
+ * The first argument may be a {@link PatchProps} object, desugared into the
+ * commands below in key order, optionally followed by command items.
+ *
+ * @param props - a props object.
+ * @param items - command items applied after the props.
+ * @returns a `Patch` for `html` to commit.
+ * @example
+ * ```ts
+ * html`<input ${patch({val: name, placeholder: 'name'})} />`;
+ * ```
+ * @group DOM bindings
+ */
+export declare function patch(props: PatchProps, ...items: ToAnyPatchItem[]): Patch;
+/**
+ * Declares one or more command bindings to apply to the same element.
+ *
+ * @param toPatchItems - the command items to apply.
+ * @returns a `Patch` for `html` to commit.
+ * @example
+ * ```ts
+ * html`<input ${patch(val(name), attr('name', placeholder))} />`;
+ * ```
+ * @group DOM bindings
+ */
+export declare function patch(...toPatchItems: ToAnyPatchItem[]): Patch;
+/**
+ * Sets the element's `id`.
+ *
+ * @typeParam T - the value type.
+ * @param source - a plain value or a `Sig`.
+ * @returns a deferred patch item.
+ * @group DOM bindings
+ */
+export declare const id: <T>(source: T | Sig<T>) => ToPatchItem<T>;
+/**
+ * Sets the element's `value` property (form controls).
+ *
+ * @typeParam T - the value type.
+ * @param source - a plain value or a `Sig`.
+ * @returns a deferred patch item.
+ * @group DOM bindings
+ */
+export declare const val: <T>(source: T | Sig<T>) => ToPatchItem<T>;
+/**
+ * Sets attribute `key`. Use this for boolean/ARIA/data attributes.
+ *
+ * @typeParam T - the value type.
+ * @param key - the attribute name.
+ * @param source - a plain value or a `Sig`.
+ * @returns a deferred patch item.
+ * @group DOM bindings
+ */
+export declare const attr: <T>(key: string, source: T | Sig<T>) => ToPatchItem<T>;
+/**
+ * The union of `CSSStyleDeclaration` keys whose values are strings.
+ *
+ * @group DOM bindings
+ */
+export type WritableStyleKey = { [K in keyof CSSStyleDeclaration]: CSSStyleDeclaration[K] extends string ? K : never; }[keyof CSSStyleDeclaration];
+/**
+ * Sets an inline style property by typed name.
+ *
+ * @typeParam T - the value type.
+ * @param key - the typed style property name.
+ * @param source - a plain value or a `Sig`.
+ * @returns a deferred patch item.
+ * @example
+ * ```ts
+ * html`<span ${patch(style('color', color))}>text</span>`;
+ * ```
+ * @group DOM bindings
+ */
+export declare const style: <T>(key: WritableStyleKey, source: T | Sig<T>) => ToPatchItem<T>;
+/**
+ * Sets a style property via `CSSStyleDeclaration.setProperty`; use this for
+ * custom properties (`--my-var`) or untyped names.
+ *
+ * @typeParam T - the value type.
+ * @param key - the style property name.
+ * @param source - a plain value or a `Sig`.
+ * @returns a deferred patch item.
+ * @example
+ * ```ts
+ * html`<div ${patch(styleProp('--size', size))}></div>`;
+ * ```
+ * @group DOM bindings
+ */
+export declare const styleProp: <T>(key: string, source: T | Sig<T>) => ToPatchItem<T>;
+/**
+ * Toggles a single class from the truthiness of the value.
+ *
+ * @typeParam T - the value type.
+ * @param token - the class token.
+ * @param source - a plain value or a `Sig`.
+ * @returns a deferred patch item.
+ * @group DOM bindings
+ */
+export declare const toggleClass: <T>(token: string, source: T | Sig<T>) => ToPatchItem<T>;
+/**
+ * Toggles several classes from one value.
+ *
+ * @typeParam T - the value type.
+ * @param tokens - the class tokens.
+ * @param source - a plain value or a `Sig`.
+ * @returns a deferred patch item.
+ * @group DOM bindings
+ */
+export declare const toggleClasses: <T>(tokens: readonly string[], source: T | Sig<T>) => ToPatchItem<T>;
+/**
+ * A custom patch callback run on mount and on change.
+ *
+ * @typeParam T - the value type.
+ * @group DOM bindings
+ */
+export type ActFn<T> = (elem: Element, val?: T) => void;
+/**
+ * Runs arbitrary code with the bound node and value, on mount and again on
+ * change. The escape hatch for anything the built-in commands do not cover.
+ *
+ * @typeParam T - the value type.
+ * @param source - a plain value or a `Sig`.
+ * @param fn - called with the node and current value.
+ * @returns a deferred patch item.
+ * @example
+ * ```ts
+ * html`<canvas ${patch(act(frame, (node, v) => draw(node, v)))}></canvas>`;
+ * ```
+ * @group DOM bindings
+ */
+export declare const act: <T>(source: T | Sig<T>, fn: ActFn<T>) => ToPatchItem<T>;
+type _Listener<K extends keyof HTMLElementEventMap> = (this: HTMLElement, ev: HTMLElementEventMap[K]) => unknown;
+/**
+ * Adds a DOM event listener. The listener is registered once at mount and is
+ * not a reactive source; combine it with `sig` writes to drive updates.
+ *
+ * @typeParam K - the event type.
+ * @param type - the event name.
+ * @param listener - the event listener.
+ * @param options - standard `addEventListener` options.
+ * @returns a deferred patch item.
+ * @group DOM bindings
+ */
+export declare const on: <K extends keyof HTMLElementEventMap>(type: K, listener: _Listener<K>, options?: boolean | AddEventListenerOptions) => ToPatchItem<_Listener<K>>;
+//#endregion
+//#region src/raw.d.ts
+/**
+ * Parses its value as HTML and mounts the resulting nodes with no wrapper
+ * element. Unlike `text`, the value is **not** escaped, so only pass trusted
+ * HTML; inline handlers and other vectors still apply once the nodes connect.
+ * A `Sig` re-parses and replaces the content on change; an empty string renders
+ * nothing.
+ *
+ * @param source - an HTML string or a `Sig` of one.
+ * @returns a content-position `View`.
+ * @example
+ * ```ts
+ * html`<article>${raw(post.bodyHtml)}</article>`;
+ * ```
+ * @group Templates
+ */
+export declare const raw: (source: string | Sig<string>) => AnyView;
 //#endregion
 //#region src/render.d.ts
+/**
+ * Mounts a view into `node` by appending its `node`. Accepts a `View` directly
+ * or a factory function that returns one. Returns a disposer that detaches every
+ * bind in the tree and removes the nodes from `node`; calling it twice is a
+ * no-op.
+ *
+ * @param viewArg - the view, or a function returning one.
+ * @param node - the node to mount into.
+ * @returns a disposer that unmounts the view.
+ * @example
+ * ```ts
+ * const dispose = render(App(), document.querySelector('#app')!);
+ * dispose();
+ * ```
+ * @group Rendering
+ */
 export declare const render: (viewArg: AnyView | (() => AnyView), node: Node) => (() => void);
 //#endregion
 //#region src/repeat.d.ts
+/**
+ * Options for {@link repeat}.
+ *
+ * @typeParam T - the item type.
+ * @group Control flow
+ */
 export type RepeatProp<T> = {
+  /** Returns the unique, stable key for an item. */
   key: (item: T) => string;
+  /** Builds the view for an item. */
   view: (item: T) => AnyView;
-  compare?: (a: T, b: T) => boolean;
+  /**
+   * Item comparator.
+   *
+   * @defaultValue `eq`
+   */
+  eq?: (a: T, b: T) => boolean;
 };
 interface Track<T> {
   key: string;
@@ -133,14 +729,74 @@ interface Track<T> {
   checked?: boolean;
   cleaned?: boolean;
 }
+/**
+ * Context for the `repeat` command.
+ *
+ * @typeParam T - the item type.
+ * @group Control flow
+ */
 export interface RepeatContext<T> extends CmdContext {
+  /** The repeat options. */
   prop: RepeatProp<T>;
+  /** The current node boundary. */
   boundary: Boundary;
+  /** The tracked items and their views. */
   tracks: Track<T>[];
 }
+/**
+ * Keyed list rendering. On each change `repeat` matches items by `key`, then
+ * reuses, moves, creates, or removes as few DOM nodes as possible. The item
+ * comparator defaults to `eq`; when an item is deeply equal to the track it
+ * already occupies, the track is reused without rebuilding its view. An empty
+ * array renders `<!--empty-list-->`.
+ *
+ * @typeParam T - the item type.
+ * @param sig - the signal holding the items.
+ * @param prop - the key/view/eq options.
+ * @returns a `View` rendering the list.
+ * @example
+ * ```ts
+ * html`<ul>${repeat(todos, {
+ *   key: (item) => item.id.toString(),
+ *   view: (item) => html`<li>${text(item.label)}</li>`,
+ * })}</ul>`;
+ * ```
+ * @group Control flow
+ */
 export declare const repeat: <T>(sig: Sig<T[]>, prop: RepeatProp<T>) => View<T[], RepeatContext<T>>;
 //#endregion
 //#region src/text.d.ts
+/**
+ * Creates a text-node view. With a `Sig`, the text updates whenever the signal
+ * changes; a plain value is static.
+ *
+ * @typeParam T - the value type.
+ * @param source - a plain value or a `Sig`.
+ * @returns a text `View`.
+ * @example
+ * ```ts
+ * html`<span>${text(count)}</span>`;
+ * ```
+ * @group Templates
+ */
 export declare const text: <T>(source: T | Sig<T>) => View<T, PatchContext>;
 //#endregion
+//#region src/view.d.ts
+/**
+ * Conditionally renders one view or another. Whenever `sig` changes, `viewFn`
+ * runs with the new value, the previous view is torn down, and a new one is
+ * mounted in its place.
+ *
+ * @typeParam T - the value type.
+ * @param sig - the signal to switch on.
+ * @param viewFn - builds the view for a value.
+ * @returns a `View` that swaps its contents.
+ * @example
+ * ```ts
+ * html`<div>${view(isEmpty, (v) => (v ? text('empty') : listView))}</div>`;
+ * ```
+ * @group Control flow
+ */
+export declare const view: <T>(sig: Sig<T>, viewFn: (val: T) => AnyView) => View<T, ViewContext<T>>;
+//#endregion
 //# sourceMappingURL=sigula.d.ts.map