@getforma/core 1.0.7 → 1.0.9

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 /// <reference path="./jsx.d.ts" />
-import { S as SignalGetter } from './signal-YlS1kgfh.cjs';
-export { a as SignalOptions, b as SignalSetter, c as createSignal } from './signal-YlS1kgfh.cjs';
-export { R as Resource, a as ResourceOptions, c as createResource } from './resource-DK98lW5e.cjs';
+import { S as SignalGetter } from './signal-C9v4akyJ.cjs';
+export { a as SignalOptions, b as SignalSetter, c as createSignal } from './signal-C9v4akyJ.cjs';
+export { R as Resource, a as ResourceOptions, c as createResource } from './resource-DeEzxUz6.cjs';
 export { getBatchDepth, isComputed, isEffect, isEffectScope, isSignal, trigger } from 'alien-signals';
 
 declare function createEffect(fn: () => void | (() => void)): () => void;
@@ -134,6 +134,11 @@ declare function untrack<T>(fn: () => T): T;
  * Uses alien-signals' `effectScope` under the hood for native graph-level
  * effect tracking, with a userland disposer list for non-effect cleanup
  * (e.g., event listeners, DOM references, timers).
+ *
+ * Roots created inside another root are automatically owned by the parent
+ * (Solid-style). When the parent is disposed, all child roots are disposed
+ * too. Use {@link createUnownedRoot} for roots that must outlive their
+ * lexical parent (e.g., mount points, test harnesses).
  */
 /**
  * Create a reactive root scope.
@@ -143,6 +148,9 @@ declare function untrack<T>(fn: () => T): T;
  * userland level (via registerDisposer). The returned `dispose` function
  * tears down everything.
  *
+ * Roots created inside another root are automatically owned by the parent.
+ * When the parent is disposed, this root is disposed too.
+ *
  * ```ts
  * const dispose = createRoot(() => {
  *   createEffect(() => console.log(count()));
@@ -152,6 +160,22 @@ declare function untrack<T>(fn: () => T): T;
  * ```
  */
 declare function createRoot<T>(fn: (dispose: () => void) => T): T;
+/**
+ * Create a reactive root that is NOT owned by any parent root.
+ *
+ * Use this for roots that must outlive their lexical parent:
+ * top-level mount points, island hydration, test harnesses, etc.
+ *
+ * ```ts
+ * createRoot(() => {
+ *   // This root outlives the parent even though it's nested:
+ *   createUnownedRoot((dispose) => {
+ *     // effects here survive parent disposal
+ *   });
+ * });
+ * ```
+ */
+declare function createUnownedRoot<T>(fn: (dispose: () => void) => T): T;
 
 /**
  * Register a cleanup function in the current reactive scope.
@@ -223,7 +247,9 @@ declare function on<T, U>(deps: () => T, fn: (value: T, prev: T | undefined) =>
  * React equivalent: useRef
  * SolidJS equivalent: (none — uses plain variables in setup)
  */
+/** A mutable container that does NOT trigger reactivity when written to. */
 interface Ref<T> {
+    /** The stored value. Mutating this does not notify effects. */
     current: T;
 }
 /**
@@ -257,6 +283,7 @@ declare function createRef<T>(initialValue: T): Ref<T>;
  * SolidJS equivalent: (none — uses createSignal + helpers)
  */
 
+/** A function that dispatches an action to a reducer. */
 type Dispatch<A> = (action: A) => void;
 /**
  * Create a reducer — predictable state updates via dispatched actions.
@@ -285,6 +312,7 @@ type Dispatch<A> = (action: A) => void;
  */
 declare function createReducer<S, A>(reducer: (state: S, action: A) => S, initialState: S): [state: SignalGetter<S>, dispatch: Dispatch<A>];
 
+/** Callback signature for the global {@link onError} handler. */
 type ErrorHandler = (error: unknown, info?: {
     source?: string;
 }) => void;
@@ -428,12 +456,18 @@ declare function mount(component: () => HTMLElement | DocumentFragment, containe
  *
  * Total module budget: <2KB minified.
  */
+/** Return value from {@link reconcileList} — the new nodes and items arrays. */
 interface ReconcileResult<T> {
+    /** The DOM nodes currently in the list, in order. */
     nodes: Node[];
+    /** The items array corresponding to the current nodes. */
     items: T[];
 }
+/** Animation hooks for list transitions. */
 interface ListTransitionHooks {
+    /** Called after a new node is inserted into the DOM. */
     onInsert?: (node: Node) => void;
+    /** Called before a node is removed. Call `done()` when the exit animation finishes. */
     onBeforeRemove?: (node: Node, done: () => void) => void;
 }
 interface CreateListOptions {
@@ -530,7 +564,7 @@ declare function createList<T>(items: () => T[], keyFn: (item: T) => string | nu
  * Returns a DocumentFragment with comment markers. The content between
  * markers is swapped reactively when `when()` changes.
  */
-declare function createShow(when: () => unknown, thenFn: () => Node, elseFn?: () => Node): DocumentFragment;
+declare function createShow(when: () => unknown, thenFn: () => Node, elseFn?: () => Node | null): DocumentFragment;
 
 /**
  * Forma DOM - Switch (Multi-branch Conditional)
@@ -546,8 +580,11 @@ declare function createShow(when: () => unknown, thenFn: () => Node, elseFn?: ()
  *
  * SolidJS equivalent: <Switch><Match when={}>
  */
+/** A single branch for {@link createSwitch}. */
 interface SwitchCase<T> {
+    /** The value that activates this branch. */
     match: T;
+    /** Factory function that renders this branch's DOM. */
     render: () => Node;
 }
 /**
@@ -747,10 +784,15 @@ declare function deactivateAllIslands(root?: Element | Document): void;
  * Reactivity comes from signals, not re-rendering.
  * Backed by alien-signals via forma/reactive.
  */
+/** A teardown function that disposes effects and cleans up resources. */
 type CleanupFn = () => void;
+/** A function that runs once to build the component's DOM tree. */
 type SetupFn = () => HTMLElement | DocumentFragment;
+/** Definition object passed to {@link defineComponent}. */
 interface ComponentDef {
+    /** The setup function that builds the component's DOM and reactive bindings. */
     setup: SetupFn;
+    /** Optional debug name for devtools inspection. */
     name?: string;
 }
 /**
@@ -793,6 +835,7 @@ declare function trackDisposer(dispose: () => void): void;
  * inject() reads the top, component teardown pops automatically.
  * Zero dependencies -- native browser APIs only.
  */
+/** A typed dependency injection context created by {@link createContext}. */
 interface Context<T> {
     /** Unique identifier for this context. */
     readonly id: symbol;
@@ -850,6 +893,7 @@ declare function unprovide<T>(ctx: Context<T>): void;
  *
  * Backed by alien-signals via forma/reactive.
  */
+/** Setter for a reactive store — accepts a partial update object or updater function. */
 type StoreSetter<T extends object> = (partial: Partial<T> | ((prev: T) => Partial<T>)) => void;
 /**
  * Create a deep reactive store.
@@ -897,6 +941,7 @@ declare function createStore<T extends object>(initial: T): [get: T, set: StoreS
  * with reactive canUndo/canRedo signals.
  * Zero dependencies -- native browser APIs only.
  */
+/** Undo/redo controls returned by {@link createHistory}. */
 interface HistoryControls<T> {
     /** Undo the last change, restoring the previous value. */
     undo: () => void;
@@ -938,6 +983,7 @@ declare function createHistory<T>(source: [get: () => T, set: (v: T) => void], o
  * Reads stored value on creation; writes on every signal change.
  * Zero dependencies -- native browser APIs only.
  */
+/** Options for {@link persist} — storage backend, serialization, and validation. */
 interface PersistOptions<T> {
     /** Storage backend. Defaults to localStorage. */
     storage?: Storage;
@@ -963,39 +1009,126 @@ interface PersistOptions<T> {
  */
 declare function persist<T>(source: [get: () => T, set: (v: T) => void], key: string, options?: PersistOptions<T>): void;
 
+/**
+ * A typed publish/subscribe event bus.
+ *
+ * The type parameter `T` maps event names to their payload types,
+ * ensuring type-safe event emission and subscription.
+ */
 interface EventBus<T extends Record<string, unknown>> {
+    /** Subscribe to an event. Returns an unsubscribe function. */
     on<K extends keyof T>(event: K, handler: (payload: T[K]) => void): () => void;
+    /** Subscribe to an event, automatically unsubscribing after the first firing. */
     once<K extends keyof T>(event: K, handler: (payload: T[K]) => void): () => void;
+    /** Emit an event to all current subscribers. */
     emit<K extends keyof T>(event: K, payload: T[K]): void;
+    /** Remove a specific handler from an event. */
     off<K extends keyof T>(event: K, handler: (payload: T[K]) => void): void;
+    /** Remove all handlers for all events. */
     clear(): void;
 }
+/**
+ * Create a typed event bus for publish/subscribe messaging.
+ *
+ * ```ts
+ * type Events = { save: { id: number }; delete: { id: number } };
+ * const bus = createBus<Events>();
+ *
+ * const unsub = bus.on('save', (payload) => console.log(payload.id));
+ * bus.emit('save', { id: 42 });
+ * unsub();
+ * ```
+ */
 declare function createBus<T extends Record<string, unknown> = Record<string, unknown>>(): EventBus<T>;
 
+/**
+ * Attach a single event listener on a parent that fires for children matching
+ * a CSS selector. Efficient for large/dynamic lists — one listener instead of
+ * one per child.
+ *
+ * ```ts
+ * const unsub = delegate(ul, 'li', 'click', (e, li) => {
+ *   console.log('Clicked:', li.textContent);
+ * });
+ * ```
+ *
+ * @param container  The parent element or document to listen on.
+ * @param selector   CSS selector to match against delegated targets.
+ * @param event      DOM event name (e.g. `'click'`, `'input'`).
+ * @param handler    Called with the event and the matched child element.
+ * @param options    Standard `addEventListener` options (capture, passive, etc.).
+ * @returns An unsubscribe function that removes the listener.
+ */
 declare function delegate<K extends keyof HTMLElementEventMap>(container: HTMLElement | Document, selector: string, event: K, handler: (e: HTMLElementEventMap[K], matchedEl: HTMLElement) => void, options?: AddEventListenerOptions): () => void;
 
 type KeyCombo = string;
+/** Options for the {@link onKey} keyboard shortcut handler. */
 interface KeyOptions {
+    /** Element or document to listen on. Defaults to `document`. */
     target?: EventTarget;
+    /** Whether to call `e.preventDefault()`. Defaults to `true`. */
     preventDefault?: boolean;
 }
+/**
+ * Listen for a keyboard shortcut and invoke a handler when it fires.
+ *
+ * Supports modifier keys: `ctrl`, `shift`, `alt`, `meta`/`cmd`.
+ *
+ * ```ts
+ * const unsub = onKey('ctrl+s', (e) => save());
+ * const unsub2 = onKey('escape', () => close(), { target: modal });
+ * ```
+ *
+ * @param combo    Key combination string (e.g. `'ctrl+s'`, `'shift+enter'`).
+ * @param handler  Called when the combo is pressed.
+ * @param options  Optional target element and preventDefault behavior.
+ * @returns An unsubscribe function that removes the listener.
+ */
 declare function onKey(combo: KeyCombo, handler: (e: KeyboardEvent) => void, options?: KeyOptions): () => void;
 
+/**
+ * Select a single element by CSS selector. Returns `null` if not found.
+ *
+ * ```ts
+ * const btn = $<HTMLButtonElement>('.submit-btn');
+ * const inner = $('span', container);
+ * ```
+ */
 declare function $<T extends HTMLElement = HTMLElement>(selector: string, parent?: ParentNode): T | null;
+/**
+ * Select all elements matching a CSS selector, returned as a plain array.
+ *
+ * ```ts
+ * const items = $$<HTMLLIElement>('ul > li');
+ * items.forEach((li) => li.classList.add('active'));
+ * ```
+ */
 declare function $$<T extends HTMLElement = HTMLElement>(selector: string, parent?: ParentNode): T[];
 
+/** Add one or more CSS classes to an element. */
 declare function addClass(el: HTMLElement, ...classes: string[]): void;
+/** Remove one or more CSS classes from an element. */
 declare function removeClass(el: HTMLElement, ...classes: string[]): void;
+/** Toggle a CSS class on an element. Returns the resulting state. */
 declare function toggleClass(el: HTMLElement, className: string, force?: boolean): boolean;
-declare function setStyle(el: HTMLElement, styles: Partial<CSSStyleDeclaration>): void;
-declare function setAttr(el: HTMLElement, attrs: Record<string, string | boolean | null>): void;
-declare function setText(el: HTMLElement, text: string): void;
 /**
- * Set raw HTML on an element. **No sanitization is performed.**
+ * Apply multiple inline styles to an element at once.
  *
- * Prefer `setText()` for user-controlled content. Only use this when you
- * trust the HTML source (e.g., server-rendered markup you control).
+ * ```ts
+ * setStyle(el, { opacity: '0', transform: 'translateY(-10px)' });
+ * ```
+ */
+declare function setStyle(el: HTMLElement, styles: Partial<CSSStyleDeclaration>): void;
+/**
+ * Set or remove multiple attributes on an element.
  *
+ * - `false` / `null` removes the attribute.
+ * - `true` sets it as a boolean attribute (empty string).
+ * - A string sets the attribute value.
+ */
+declare function setAttr(el: HTMLElement, attrs: Record<string, string | boolean | null>): void;
+/** Set an element's text content. Safe for user-controlled strings. */
+declare function setText(el: HTMLElement, text: string): void;
 /**
  * Set raw HTML on an element. **No sanitization is performed.**
  *
@@ -1004,15 +1137,37 @@ declare function setText(el: HTMLElement, text: string): void;
  */
 declare function setHTMLUnsafe(el: HTMLElement, html: string): void;
 
+/** Find the closest ancestor matching a CSS selector. */
 declare function closest<T extends HTMLElement = HTMLElement>(el: HTMLElement, selector: string): T | null;
+/** Get direct child elements, optionally filtered by a CSS selector. */
 declare function children<T extends HTMLElement = HTMLElement>(el: HTMLElement, selector?: string): T[];
+/** Get sibling elements (excluding the element itself), optionally filtered. */
 declare function siblings<T extends HTMLElement = HTMLElement>(el: HTMLElement, selector?: string): T[];
+/** Get the parent element, or `null` if detached. */
 declare function parent<T extends HTMLElement = HTMLElement>(el: HTMLElement): T | null;
+/** Find the next sibling element, optionally matching a CSS selector. */
 declare function nextSibling<T extends HTMLElement = HTMLElement>(el: HTMLElement, selector?: string): T | null;
+/** Find the previous sibling element, optionally matching a CSS selector. */
 declare function prevSibling<T extends HTMLElement = HTMLElement>(el: HTMLElement, selector?: string): T | null;
 
+/**
+ * Observe element size changes via `ResizeObserver`.
+ *
+ * @returns A disconnect function that stops observing.
+ */
 declare function onResize(el: HTMLElement, handler: (entry: ResizeObserverEntry) => void): () => void;
+/**
+ * Observe element visibility changes via `IntersectionObserver`.
+ *
+ * @returns A disconnect function that stops observing.
+ */
 declare function onIntersect(el: HTMLElement, handler: (entry: IntersectionObserverEntry) => void, options?: IntersectionObserverInit): () => void;
+/**
+ * Observe DOM mutations (child additions/removals, attribute changes) via
+ * `MutationObserver`. Defaults to `{ childList: true, subtree: true }`.
+ *
+ * @returns A disconnect function that stops observing.
+ */
 declare function onMutation(el: HTMLElement, handler: (mutations: MutationRecord[]) => void, options?: MutationObserverInit): () => void;
 
-export { $, $$, type CleanupFn, type ComponentDef, type Context, type CreateListOptions, type Dispatch, type ErrorHandler, type EventBus, Fragment, type HistoryControls, type IslandHydrateFn, type KeyOptions, type ListTransitionHooks, type PersistOptions, type ReconcileResult, type Ref, type SetupFn, SignalGetter, type StoreSetter, type SwitchCase, activateIslands, addClass, batch, children, cleanup, closest, createBus, createComputed, createContext, createEffect, createErrorBoundary, createHistory, createList, createMemo, createPortal, createReducer, createRef, createRoot, createShow, createStore, createSuspense, createSwitch, createText, deactivateAllIslands, deactivateIsland, defineComponent, delegate, disposeComponent, fragment, h, hydrateIsland, inject, mount, nextSibling, on, onCleanup, onError, onIntersect, onKey, onMount, onMutation, onResize, onUnmount, parent, persist, prevSibling, provide, reconcileList, removeClass, setAttr, setHTMLUnsafe, setStyle, setText, siblings, template, templateMany, toggleClass, trackDisposer, unprovide, untrack };
+export { $, $$, type CleanupFn, type ComponentDef, type Context, type CreateListOptions, type Dispatch, type ErrorHandler, type EventBus, Fragment, type HistoryControls, type IslandHydrateFn, type KeyOptions, type ListTransitionHooks, type PersistOptions, type ReconcileResult, type Ref, type SetupFn, SignalGetter, type StoreSetter, type SwitchCase, activateIslands, addClass, batch, children, cleanup, closest, createBus, createComputed, createContext, createEffect, createErrorBoundary, createHistory, createList, createMemo, createPortal, createReducer, createRef, createRoot, createShow, createStore, createSuspense, createSwitch, createText, createUnownedRoot, deactivateAllIslands, deactivateIsland, defineComponent, delegate, disposeComponent, fragment, h, hydrateIsland, inject, mount, nextSibling, on, onCleanup, onError, onIntersect, onKey, onMount, onMutation, onResize, onUnmount, parent, persist, prevSibling, provide, reconcileList, removeClass, setAttr, setHTMLUnsafe, setStyle, setText, siblings, template, templateMany, toggleClass, trackDisposer, unprovide, untrack };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 /// <reference path="./jsx.d.ts" />
-import { S as SignalGetter } from './signal-YlS1kgfh.js';
-export { a as SignalOptions, b as SignalSetter, c as createSignal } from './signal-YlS1kgfh.js';
-export { R as Resource, a as ResourceOptions, c as createResource } from './resource-Cd0cGOxS.js';
+import { S as SignalGetter } from './signal-C9v4akyJ.js';
+export { a as SignalOptions, b as SignalSetter, c as createSignal } from './signal-C9v4akyJ.js';
+export { R as Resource, a as ResourceOptions, c as createResource } from './resource-BHsgURy0.js';
 export { getBatchDepth, isComputed, isEffect, isEffectScope, isSignal, trigger } from 'alien-signals';
 
 declare function createEffect(fn: () => void | (() => void)): () => void;
@@ -134,6 +134,11 @@ declare function untrack<T>(fn: () => T): T;
  * Uses alien-signals' `effectScope` under the hood for native graph-level
  * effect tracking, with a userland disposer list for non-effect cleanup
  * (e.g., event listeners, DOM references, timers).
+ *
+ * Roots created inside another root are automatically owned by the parent
+ * (Solid-style). When the parent is disposed, all child roots are disposed
+ * too. Use {@link createUnownedRoot} for roots that must outlive their
+ * lexical parent (e.g., mount points, test harnesses).
  */
 /**
  * Create a reactive root scope.
@@ -143,6 +148,9 @@ declare function untrack<T>(fn: () => T): T;
  * userland level (via registerDisposer). The returned `dispose` function
  * tears down everything.
  *
+ * Roots created inside another root are automatically owned by the parent.
+ * When the parent is disposed, this root is disposed too.
+ *
  * ```ts
  * const dispose = createRoot(() => {
  *   createEffect(() => console.log(count()));
@@ -152,6 +160,22 @@ declare function untrack<T>(fn: () => T): T;
  * ```
  */
 declare function createRoot<T>(fn: (dispose: () => void) => T): T;
+/**
+ * Create a reactive root that is NOT owned by any parent root.
+ *
+ * Use this for roots that must outlive their lexical parent:
+ * top-level mount points, island hydration, test harnesses, etc.
+ *
+ * ```ts
+ * createRoot(() => {
+ *   // This root outlives the parent even though it's nested:
+ *   createUnownedRoot((dispose) => {
+ *     // effects here survive parent disposal
+ *   });
+ * });
+ * ```
+ */
+declare function createUnownedRoot<T>(fn: (dispose: () => void) => T): T;
 
 /**
  * Register a cleanup function in the current reactive scope.
@@ -223,7 +247,9 @@ declare function on<T, U>(deps: () => T, fn: (value: T, prev: T | undefined) =>
  * React equivalent: useRef
  * SolidJS equivalent: (none — uses plain variables in setup)
  */
+/** A mutable container that does NOT trigger reactivity when written to. */
 interface Ref<T> {
+    /** The stored value. Mutating this does not notify effects. */
     current: T;
 }
 /**
@@ -257,6 +283,7 @@ declare function createRef<T>(initialValue: T): Ref<T>;
  * SolidJS equivalent: (none — uses createSignal + helpers)
  */
 
+/** A function that dispatches an action to a reducer. */
 type Dispatch<A> = (action: A) => void;
 /**
  * Create a reducer — predictable state updates via dispatched actions.
@@ -285,6 +312,7 @@ type Dispatch<A> = (action: A) => void;
  */
 declare function createReducer<S, A>(reducer: (state: S, action: A) => S, initialState: S): [state: SignalGetter<S>, dispatch: Dispatch<A>];
 
+/** Callback signature for the global {@link onError} handler. */
 type ErrorHandler = (error: unknown, info?: {
     source?: string;
 }) => void;
@@ -428,12 +456,18 @@ declare function mount(component: () => HTMLElement | DocumentFragment, containe
  *
  * Total module budget: <2KB minified.
  */
+/** Return value from {@link reconcileList} — the new nodes and items arrays. */
 interface ReconcileResult<T> {
+    /** The DOM nodes currently in the list, in order. */
     nodes: Node[];
+    /** The items array corresponding to the current nodes. */
     items: T[];
 }
+/** Animation hooks for list transitions. */
 interface ListTransitionHooks {
+    /** Called after a new node is inserted into the DOM. */
     onInsert?: (node: Node) => void;
+    /** Called before a node is removed. Call `done()` when the exit animation finishes. */
     onBeforeRemove?: (node: Node, done: () => void) => void;
 }
 interface CreateListOptions {
@@ -530,7 +564,7 @@ declare function createList<T>(items: () => T[], keyFn: (item: T) => string | nu
  * Returns a DocumentFragment with comment markers. The content between
  * markers is swapped reactively when `when()` changes.
  */
-declare function createShow(when: () => unknown, thenFn: () => Node, elseFn?: () => Node): DocumentFragment;
+declare function createShow(when: () => unknown, thenFn: () => Node, elseFn?: () => Node | null): DocumentFragment;
 
 /**
  * Forma DOM - Switch (Multi-branch Conditional)
@@ -546,8 +580,11 @@ declare function createShow(when: () => unknown, thenFn: () => Node, elseFn?: ()
  *
  * SolidJS equivalent: <Switch><Match when={}>
  */
+/** A single branch for {@link createSwitch}. */
 interface SwitchCase<T> {
+    /** The value that activates this branch. */
     match: T;
+    /** Factory function that renders this branch's DOM. */
     render: () => Node;
 }
 /**
@@ -747,10 +784,15 @@ declare function deactivateAllIslands(root?: Element | Document): void;
  * Reactivity comes from signals, not re-rendering.
  * Backed by alien-signals via forma/reactive.
  */
+/** A teardown function that disposes effects and cleans up resources. */
 type CleanupFn = () => void;
+/** A function that runs once to build the component's DOM tree. */
 type SetupFn = () => HTMLElement | DocumentFragment;
+/** Definition object passed to {@link defineComponent}. */
 interface ComponentDef {
+    /** The setup function that builds the component's DOM and reactive bindings. */
     setup: SetupFn;
+    /** Optional debug name for devtools inspection. */
     name?: string;
 }
 /**
@@ -793,6 +835,7 @@ declare function trackDisposer(dispose: () => void): void;
  * inject() reads the top, component teardown pops automatically.
  * Zero dependencies -- native browser APIs only.
  */
+/** A typed dependency injection context created by {@link createContext}. */
 interface Context<T> {
     /** Unique identifier for this context. */
     readonly id: symbol;
@@ -850,6 +893,7 @@ declare function unprovide<T>(ctx: Context<T>): void;
  *
  * Backed by alien-signals via forma/reactive.
  */
+/** Setter for a reactive store — accepts a partial update object or updater function. */
 type StoreSetter<T extends object> = (partial: Partial<T> | ((prev: T) => Partial<T>)) => void;
 /**
  * Create a deep reactive store.
@@ -897,6 +941,7 @@ declare function createStore<T extends object>(initial: T): [get: T, set: StoreS
  * with reactive canUndo/canRedo signals.
  * Zero dependencies -- native browser APIs only.
  */
+/** Undo/redo controls returned by {@link createHistory}. */
 interface HistoryControls<T> {
     /** Undo the last change, restoring the previous value. */
     undo: () => void;
@@ -938,6 +983,7 @@ declare function createHistory<T>(source: [get: () => T, set: (v: T) => void], o
  * Reads stored value on creation; writes on every signal change.
  * Zero dependencies -- native browser APIs only.
  */
+/** Options for {@link persist} — storage backend, serialization, and validation. */
 interface PersistOptions<T> {
     /** Storage backend. Defaults to localStorage. */
     storage?: Storage;
@@ -963,39 +1009,126 @@ interface PersistOptions<T> {
  */
 declare function persist<T>(source: [get: () => T, set: (v: T) => void], key: string, options?: PersistOptions<T>): void;
 
+/**
+ * A typed publish/subscribe event bus.
+ *
+ * The type parameter `T` maps event names to their payload types,
+ * ensuring type-safe event emission and subscription.
+ */
 interface EventBus<T extends Record<string, unknown>> {
+    /** Subscribe to an event. Returns an unsubscribe function. */
     on<K extends keyof T>(event: K, handler: (payload: T[K]) => void): () => void;
+    /** Subscribe to an event, automatically unsubscribing after the first firing. */
     once<K extends keyof T>(event: K, handler: (payload: T[K]) => void): () => void;
+    /** Emit an event to all current subscribers. */
     emit<K extends keyof T>(event: K, payload: T[K]): void;
+    /** Remove a specific handler from an event. */
     off<K extends keyof T>(event: K, handler: (payload: T[K]) => void): void;
+    /** Remove all handlers for all events. */
     clear(): void;
 }
+/**
+ * Create a typed event bus for publish/subscribe messaging.
+ *
+ * ```ts
+ * type Events = { save: { id: number }; delete: { id: number } };
+ * const bus = createBus<Events>();
+ *
+ * const unsub = bus.on('save', (payload) => console.log(payload.id));
+ * bus.emit('save', { id: 42 });
+ * unsub();
+ * ```
+ */
 declare function createBus<T extends Record<string, unknown> = Record<string, unknown>>(): EventBus<T>;
 
+/**
+ * Attach a single event listener on a parent that fires for children matching
+ * a CSS selector. Efficient for large/dynamic lists — one listener instead of
+ * one per child.
+ *
+ * ```ts
+ * const unsub = delegate(ul, 'li', 'click', (e, li) => {
+ *   console.log('Clicked:', li.textContent);
+ * });
+ * ```
+ *
+ * @param container  The parent element or document to listen on.
+ * @param selector   CSS selector to match against delegated targets.
+ * @param event      DOM event name (e.g. `'click'`, `'input'`).
+ * @param handler    Called with the event and the matched child element.
+ * @param options    Standard `addEventListener` options (capture, passive, etc.).
+ * @returns An unsubscribe function that removes the listener.
+ */
 declare function delegate<K extends keyof HTMLElementEventMap>(container: HTMLElement | Document, selector: string, event: K, handler: (e: HTMLElementEventMap[K], matchedEl: HTMLElement) => void, options?: AddEventListenerOptions): () => void;
 
 type KeyCombo = string;
+/** Options for the {@link onKey} keyboard shortcut handler. */
 interface KeyOptions {
+    /** Element or document to listen on. Defaults to `document`. */
     target?: EventTarget;
+    /** Whether to call `e.preventDefault()`. Defaults to `true`. */
     preventDefault?: boolean;
 }
+/**
+ * Listen for a keyboard shortcut and invoke a handler when it fires.
+ *
+ * Supports modifier keys: `ctrl`, `shift`, `alt`, `meta`/`cmd`.
+ *
+ * ```ts
+ * const unsub = onKey('ctrl+s', (e) => save());
+ * const unsub2 = onKey('escape', () => close(), { target: modal });
+ * ```
+ *
+ * @param combo    Key combination string (e.g. `'ctrl+s'`, `'shift+enter'`).
+ * @param handler  Called when the combo is pressed.
+ * @param options  Optional target element and preventDefault behavior.
+ * @returns An unsubscribe function that removes the listener.
+ */
 declare function onKey(combo: KeyCombo, handler: (e: KeyboardEvent) => void, options?: KeyOptions): () => void;
 
+/**
+ * Select a single element by CSS selector. Returns `null` if not found.
+ *
+ * ```ts
+ * const btn = $<HTMLButtonElement>('.submit-btn');
+ * const inner = $('span', container);
+ * ```
+ */
 declare function $<T extends HTMLElement = HTMLElement>(selector: string, parent?: ParentNode): T | null;
+/**
+ * Select all elements matching a CSS selector, returned as a plain array.
+ *
+ * ```ts
+ * const items = $$<HTMLLIElement>('ul > li');
+ * items.forEach((li) => li.classList.add('active'));
+ * ```
+ */
 declare function $$<T extends HTMLElement = HTMLElement>(selector: string, parent?: ParentNode): T[];
 
+/** Add one or more CSS classes to an element. */
 declare function addClass(el: HTMLElement, ...classes: string[]): void;
+/** Remove one or more CSS classes from an element. */
 declare function removeClass(el: HTMLElement, ...classes: string[]): void;
+/** Toggle a CSS class on an element. Returns the resulting state. */
 declare function toggleClass(el: HTMLElement, className: string, force?: boolean): boolean;
-declare function setStyle(el: HTMLElement, styles: Partial<CSSStyleDeclaration>): void;
-declare function setAttr(el: HTMLElement, attrs: Record<string, string | boolean | null>): void;
-declare function setText(el: HTMLElement, text: string): void;
 /**
- * Set raw HTML on an element. **No sanitization is performed.**
+ * Apply multiple inline styles to an element at once.
  *
- * Prefer `setText()` for user-controlled content. Only use this when you
- * trust the HTML source (e.g., server-rendered markup you control).
+ * ```ts
+ * setStyle(el, { opacity: '0', transform: 'translateY(-10px)' });
+ * ```
+ */
+declare function setStyle(el: HTMLElement, styles: Partial<CSSStyleDeclaration>): void;
+/**
+ * Set or remove multiple attributes on an element.
  *
+ * - `false` / `null` removes the attribute.
+ * - `true` sets it as a boolean attribute (empty string).
+ * - A string sets the attribute value.
+ */
+declare function setAttr(el: HTMLElement, attrs: Record<string, string | boolean | null>): void;
+/** Set an element's text content. Safe for user-controlled strings. */
+declare function setText(el: HTMLElement, text: string): void;
 /**
  * Set raw HTML on an element. **No sanitization is performed.**
  *
@@ -1004,15 +1137,37 @@ declare function setText(el: HTMLElement, text: string): void;
  */
 declare function setHTMLUnsafe(el: HTMLElement, html: string): void;
 
+/** Find the closest ancestor matching a CSS selector. */
 declare function closest<T extends HTMLElement = HTMLElement>(el: HTMLElement, selector: string): T | null;
+/** Get direct child elements, optionally filtered by a CSS selector. */
 declare function children<T extends HTMLElement = HTMLElement>(el: HTMLElement, selector?: string): T[];
+/** Get sibling elements (excluding the element itself), optionally filtered. */
 declare function siblings<T extends HTMLElement = HTMLElement>(el: HTMLElement, selector?: string): T[];
+/** Get the parent element, or `null` if detached. */
 declare function parent<T extends HTMLElement = HTMLElement>(el: HTMLElement): T | null;
+/** Find the next sibling element, optionally matching a CSS selector. */
 declare function nextSibling<T extends HTMLElement = HTMLElement>(el: HTMLElement, selector?: string): T | null;
+/** Find the previous sibling element, optionally matching a CSS selector. */
 declare function prevSibling<T extends HTMLElement = HTMLElement>(el: HTMLElement, selector?: string): T | null;
 
+/**
+ * Observe element size changes via `ResizeObserver`.
+ *
+ * @returns A disconnect function that stops observing.
+ */
 declare function onResize(el: HTMLElement, handler: (entry: ResizeObserverEntry) => void): () => void;
+/**
+ * Observe element visibility changes via `IntersectionObserver`.
+ *
+ * @returns A disconnect function that stops observing.
+ */
 declare function onIntersect(el: HTMLElement, handler: (entry: IntersectionObserverEntry) => void, options?: IntersectionObserverInit): () => void;
+/**
+ * Observe DOM mutations (child additions/removals, attribute changes) via
+ * `MutationObserver`. Defaults to `{ childList: true, subtree: true }`.
+ *
+ * @returns A disconnect function that stops observing.
+ */
 declare function onMutation(el: HTMLElement, handler: (mutations: MutationRecord[]) => void, options?: MutationObserverInit): () => void;
 
-export { $, $$, type CleanupFn, type ComponentDef, type Context, type CreateListOptions, type Dispatch, type ErrorHandler, type EventBus, Fragment, type HistoryControls, type IslandHydrateFn, type KeyOptions, type ListTransitionHooks, type PersistOptions, type ReconcileResult, type Ref, type SetupFn, SignalGetter, type StoreSetter, type SwitchCase, activateIslands, addClass, batch, children, cleanup, closest, createBus, createComputed, createContext, createEffect, createErrorBoundary, createHistory, createList, createMemo, createPortal, createReducer, createRef, createRoot, createShow, createStore, createSuspense, createSwitch, createText, deactivateAllIslands, deactivateIsland, defineComponent, delegate, disposeComponent, fragment, h, hydrateIsland, inject, mount, nextSibling, on, onCleanup, onError, onIntersect, onKey, onMount, onMutation, onResize, onUnmount, parent, persist, prevSibling, provide, reconcileList, removeClass, setAttr, setHTMLUnsafe, setStyle, setText, siblings, template, templateMany, toggleClass, trackDisposer, unprovide, untrack };
+export { $, $$, type CleanupFn, type ComponentDef, type Context, type CreateListOptions, type Dispatch, type ErrorHandler, type EventBus, Fragment, type HistoryControls, type IslandHydrateFn, type KeyOptions, type ListTransitionHooks, type PersistOptions, type ReconcileResult, type Ref, type SetupFn, SignalGetter, type StoreSetter, type SwitchCase, activateIslands, addClass, batch, children, cleanup, closest, createBus, createComputed, createContext, createEffect, createErrorBoundary, createHistory, createList, createMemo, createPortal, createReducer, createRef, createRoot, createShow, createStore, createSuspense, createSwitch, createText, createUnownedRoot, deactivateAllIslands, deactivateIsland, defineComponent, delegate, disposeComponent, fragment, h, hydrateIsland, inject, mount, nextSibling, on, onCleanup, onError, onIntersect, onKey, onMount, onMutation, onResize, onUnmount, parent, persist, prevSibling, provide, reconcileList, removeClass, setAttr, setHTMLUnsafe, setStyle, setText, siblings, template, templateMany, toggleClass, trackDisposer, unprovide, untrack };