@torpor/view 0.4.17 → 1.0.0

package/dist/index.d.mts

@@ -1,8 +1,7 @@
-import { n as SlotRender, t as Component } from "./Component-DmWGMgak.mjs";
-import { t as Cleanup } from "./Cleanup-CgjyN0lW.mjs";
-import { n as Effect, t as Region } from "./Region-CTchywkr.mjs";
-import { a as ClassValue, i as buildClasses, n as buildStyles, r as StyleValue, t as formatText } from "./formatText-D6Ov8Ub0.mjs";
-
+import { n as SlotRender, t as Component } from "./Component-0MH0zd-m.mjs";
+import { t as Cleanup } from "./Cleanup-D0wvGW5d.mjs";
+import { n as Region, t as Effect } from "./Effect-BTKurOpr.mjs";
+import { a as buildStyles, c as ClassValue, i as StreamSource, n as fromServer, o as StyleValue, r as fromElement, s as buildClasses, t as fromWebSocket } from "./fromWebSocket-B52kN3-W.mjs";
 //#region src/types/Animation.d.ts
 interface Animation {
   keyframes: Keyframe[] | PropertyIndexedKeyframes;
@@ -15,46 +14,154 @@ declare function addAnimation(el: HTMLElement, entry?: Animation, exit?: Animati
 //#region src/render/addEvent.d.ts
 declare function addEvent(el: Element, type: string, listener: ((this: Element, ev: any) => any) | undefined | null): void;
 //#endregion
+//#region src/render/addElement.d.ts
+/**
+ * Companion to `addFragment` for the single-root-element codegen path. Wires
+ * a cloned root element (produced by `getElementFragment`) into the live DOM
+ * tree, sets the active region's start/end nodes, and runs the same
+ * mount-time side effects as `addFragment` (`$onmount` effects, stashed event
+ * listeners, stashed animations).
+ *
+ * Differences from `addFragment`:
+ * - `node` is both the start and end of the region (no
+ *   `fragment.firstChild`/`fragment.lastChild` indirection).
+ * - When hydrating, the existing DOM node is reused (the cloned `node` is
+ *   discarded); `endNode` is still `node` because `nodeRootElement` returns
+ *   the hydration cursor's node in that case, not the cloned one.
+ *
+ * @param node The root element (cloned by `getElementFragment`, or the
+ *   hydration cursor's node when hydrating).
+ * @param parent The intended parent element.
+ * @param before The sibling to insert before (or `null` to append).
+ */
+declare function addElement(node: Element, parent: ParentNode, before: Node | null): void;
+//#endregion
 //#region src/render/addFragment.d.ts
-declare function addFragment(fragment: DocumentFragment, parent: ParentNode, before: Node | null, endNode?: ChildNode): void;
+declare function addFragment(fragment: DocumentFragment, parent: ParentNode, before: Node | null, endNode?: ChildNode, startNode?: ChildNode): void;
 //#endregion
 //#region src/render/applyProps.d.ts
 declare function applyProps(el: Element, props: Record<string, any> | undefined, propNamesUsed: string[]): void;
 //#endregion
 //#region src/render/clearLayoutSlot.d.ts
+/**
+ * Clears a region that was created by `fillLayoutSlot`: tears down the
+ * rendered content and its effects, leaving the surrounding layout intact
+ * so the slot can be refilled.
+ *
+ * @param region The region to clear
+ */
 declare function clearLayoutSlot(region: Region): void;
 //#endregion
 //#region src/render/fillLayoutSlot.d.ts
-declare function fillLayoutSlot(component: Component, slot: SlotRender, parent: ParentNode, anchor: Node | null, $props?: Record<string, string>, $context?: Record<PropertyKey, any>): Region;
+/**
+ * Renders a component into a persistent layout slot, and returns the region
+ * it was rendered into. Used by the layout engine during navigation: the
+ * component is created inside `parent` at `anchor`, with `slot` as its child
+ * slot render, and the returned region can later be passed to
+ * `clearLayoutSlot` to tear the page down — leaving the layout itself
+ * intact — before refilling the slot.
+ *
+ * @param component The component to render into the slot
+ * @param slot The slot render to pass to the component
+ * @param parent The parent node to render into
+ * @param anchor The node to insert content before, or null to append
+ * @param $props Optional props to pass to the component
+ * @param $context Optional context to pass to the component
+ */
+declare function fillLayoutSlot(component: Component, slot: SlotRender, parent: ParentNode, anchor: Node | null, $props?: Record<PropertyKey, any>, $context?: Record<PropertyKey, any>): Region;
+//#endregion
+//#region src/render/formatText.d.ts
+declare function formatText(value: any): string;
 //#endregion
 //#region src/render/getFragment.d.ts
 declare function getFragment(document: Document, array: DocumentFragment[], index: number, html: string, ns?: boolean): DocumentFragment;
 //#endregion
+//#region src/render/getElementFragment.d.ts
+/**
+ * Returns a clone of the cached template's single root element, bypassing the
+ * `DocumentFragment` wrapper that `getFragment` produces.
+ *
+ * Used by the compiler-emitted `createListItem` for `@for` bodies (and other
+ * fragments) whose template has exactly one rendering root child — e.g.
+ * `<tr><td>...</td>...</tr>`. Cloning `template.content.firstElementChild`
+ * directly saves the per-row `DocumentFragment` allocation that `getFragment`'s
+ * `cloneNode(true)` on the cached template's content would otherwise produce,
+ * which dominates the cost of bulk-row creates (`run`/`add`/`runlots`).
+ *
+ * Contract: the compiler only emits `t_fragment_el` for fragment indices whose
+ * template has exactly one rendering root, and that root is an `Element`. The
+ * cache array (`t_fragment_els`) is separate from `t_fragments` so each helper
+ * only ever sees its own cached type at a given index.
+ *
+ * @param document The owner document (used to build the cached `<template>`).
+ * @param array The per-component `t_fragment_els` cache.
+ * @param index The fragment's index in the cache.
+ * @param html The fragment's HTML source, with `#` placeholders for reactive
+ *   text and `<!>` for anchor comments.
+ * @param ns When true, the template is created in the SVG namespace (its
+ *   `firstElementChild` is then an SVG element).
+ */
+declare function getElementFragment(document: Document, array: Element[], index: number, html: string, ns?: boolean): Element;
+//#endregion
 //#region src/render/hydrate.d.ts
 /**
-* Hydrates a component into an existing DOM tree
-* @param parent The parent node
-* @param component The component to mount
-* @param props An object containing component props
-*/
+ * Hydrates a component into an existing DOM tree
+ * @param parent The parent node
+ * @param component The component to mount
+ * @param props An object containing component props
+ */
 declare function hydrate(parent: ParentNode, component: Component, props?: Record<string, any>, slots?: Record<string, SlotRender>): void;
 //#endregion
 //#region src/render/mount.d.ts
 /**
-* Mounts a component into a DOM node
-*
-* @param parent The node to mount the component into
-* @param component The component to mount
-* @param props An object containing component props
-*/
+ * Mounts a component into a DOM node
+ *
+ * @param parent The node to mount the component into
+ * @param component The component to mount
+ * @param props An object containing component props
+ */
 declare function mount(parent: ParentNode, component: Component, props?: Record<string, any>, slots?: Record<string, SlotRender>): void;
 //#endregion
-//#region src/types/ListItem.d.ts
-interface ListItem extends Region {
-  data: Record<string, any>;
+//#region src/render/unmount.d.ts
+/**
+ * Tears down the current UI: disposes the root region tree (running effect
+ * cleanups and detaching subscriptions), resets the render context, and
+ * removes any remaining child nodes from `parent`.
+ *
+ * Call this before `mount`ing a fresh component tree into the same container
+ * (e.g. when client-side navigating to a route whose layout chain differs
+ * from the previous one). `mount` refuses to mount into a non-empty parent
+ * and reuses an existing root region, so both must be cleared first.
+ *
+ * @param parent The container that the previous UI was mounted into
+ */
+declare function unmount(parent: ParentNode): void;
+//#endregion
+//#region src/types/ListItemSpec.d.ts
+/**
+ * A lightweight, per-row descriptor emitted by the compiler's `@for`
+ * `buildItems` callback: just the key (for reconciliation) and the data bag
+ * (the loop variables). Unlike a full {@link ListItem}, a spec carries no DOM
+ * nodes, no effects, and no sibling-chain pointers — so allocating one per row
+ * on every list update is cheap.
+ *
+ * The keyed-list reconciler (`runListItems`) maps each spec to either an
+ * existing `ListItem` (matched by key, reused wholesale) or a freshly mounted
+ * one (for genuinely new keys), keeping the per-update cost proportional to
+ * what actually changed instead of to the list size.
+ *
+ * NOTE: `data` is `any` rather than `Record<string, any>` -- when a `@for`
+ * body binds a single loop variable and is proxy-safe, the variable is stored
+ * directly (e.g. `data: page` for a number), not as a bag.
+ */
+interface ListItemSpec {
   key: any;
+  data: any;
 }
 //#endregion
+//#region src/types/ListItem.d.ts
+interface ListItem extends Region, ListItemSpec {}
+//#endregion
 //#region src/render/newListItem.d.ts
 declare function newListItem(data: Record<PropertyKey, any>, key?: any, name?: string): ListItem;
 //#endregion
@@ -63,62 +170,91 @@ declare function newRegion(name?: string): Region;
 //#endregion
 //#region src/render/nodeAnchor.d.ts
 /**
-* Gets the anchor node for a control statement or component.
-*
-* When mounting, this just returns the anchor node parameter (because it was
-* created).
-*
-* When hydrating, there should be matched <![> and <!]> comments in the HTML,
-* and the anchor node should be after the end comment. The matched comment
-* nodes will be deleted, and the hydration node set to the first node inside
-* the matched comments.
-*
-* @param node The potential anchor node.
-* @returns The anchor node.
-*/
+ * Gets the anchor node for a control statement or component.
+ *
+ * When mounting, this just returns the anchor node parameter (because it was
+ * created).
+ *
+ * When hydrating, there should be matched <![> and <!]> comments in the HTML,
+ * and the anchor node should be after the end comment. The matched comment
+ * nodes will be deleted, and the hydration node set to the first node inside
+ * the matched comments.
+ *
+ * @param node The potential anchor node.
+ * @returns The anchor node.
+ */
 declare function nodeAnchor(node: ChildNode): ChildNode;
 //#endregion
 //#region src/render/nodeChild.d.ts
 /**
-* Gets the first child of a node.
-*
-* Sets the hydration node.
-*
-* @param parent The parent node.
-*/
+ * Gets the first child of a node.
+ *
+ * Sets the hydration node.
+ *
+ * @param parent The parent node.
+ */
 declare function nodeChild(parent: Node): ChildNode;
 //#endregion
 //#region src/render/nodeNext.d.ts
 /**
-* Gets the next sibling of a node.
-*
-* When hydrating, sets the hydration node.
-*
-* @param node The node.
-* @param text Whether we require a text node.
-*/
+ * Gets the next sibling of a node.
+ *
+ * When hydrating, sets the hydration node.
+ *
+ * @param node The node.
+ * @param text Whether we require a text node.
+ */
 declare function nodeNext(node: ChildNode, text?: boolean): ChildNode;
 //#endregion
+//#region src/render/nodeRootElement.d.ts
+/**
+ * Gets the root element of a single-root fragment built via `getElementFragment`.
+ *
+ * Companion to `nodeRoot`, for the codegen path where the compiler has emitted
+ * `t_fragment_el` (cloning the cached template's `firstElementChild` directly)
+ * instead of `t_fragment` (cloning into a `DocumentFragment`). In the
+ * non-hydrating case the cloned element is already the root, so this is a
+ * no-op pass-through. In the hydrating case we perform the same cursor walk as
+ * `nodeRoot`'s non-text branch so the region's `startNode` lands on the
+ * existing DOM node and the hydration cursor advances past any leading
+ * whitespace, branch-break markers, and auto-inserted `<tbody>` wrappers.
+ *
+ * @param node The cloned root element (ignored when hydrating).
+ */
+declare function nodeRootElement(node: Element): ChildNode;
+//#endregion
 //#region src/render/nodeRoot.d.ts
 /**
-* Gets the first child in a fragment.
-*
-* When hydrating, also sets the active range's start node, while we have it.
-*
-* @param parent The parent of the fragment.
-* @param text Whether we require a text node.
-*/
+ * Gets the first child in a fragment.
+ *
+ * When hydrating, also sets the active region's start node, while we have it.
+ *
+ * If the hydration cursor is on a control-start marker (`<![>`), the node is
+ * left in place for `nodeAnchor` (called next as `t_anchor(t_root(...))`) to
+ * walk — it consumes the matched `<![>...<!]>` pair, removes the markers and
+ * sets the region's start node to the first node inside the block.
+ *
+ * For non-text fragments, leading branch-break markers (`<!^>`), empty anchor
+ * comments left by preceding siblings, and residual whitespace-only text nodes
+ * are skipped (break markers removed) so the region's start node lands on real
+ * content. This replaces the per-sibling `t_next` calls that the codegen used
+ * to emit when leading whitespace separated siblings; with whitespace trimmed
+ * those calls are gone, so the advancement happens here.
+ *
+ * @param parent The parent of the fragment.
+ * @param text Whether we require a text node.
+ */
 declare function nodeRoot(parent: Node, text?: boolean): ChildNode;
 //#endregion
 //#region src/render/nodeSkip.d.ts
 /**
-* Gets the sibling of a node, x nodes after it.
-*
-* When hydrating, sets the hydration node.
-*
-* @param node The node.
-* @param count The number of nodes to skip.
-*/
+ * Gets the sibling of a node, x nodes after it.
+ *
+ * When hydrating, sets the hydration node.
+ *
+ * @param node The node.
+ * @param count The number of nodes to skip.
+ */
 declare function nodeSkip(node: ChildNode, count: number): ChildNode;
 //#endregion
 //#region src/render/popRegion.d.ts
@@ -127,11 +263,54 @@ declare function popRegion(oldRegion: Region): void;
 //#region src/render/pushRegion.d.ts
 declare function pushRegion(region: Region, toParent?: boolean): Region;
 //#endregion
+//#region src/render/rerunRegionEffects.d.ts
+/**
+ * Force re-runs every effect owned by `region` and its descendant regions
+ * that depends on at least one of the for-vars set in `changedMask`.
+ *
+ * Used by keyed-list `updateListItem` callbacks emitted by the compiler when
+ * the `@for` body has been classified "no-proxy safe" — i.e. the per-item
+ * data bag is *not* wrapped in a shallow `$watch` Proxy. Without that Proxy,
+ * a write such as `t_old_item.data.row = newRow` doesn't propagate through a
+ * signal, so any effects that read `data.row` must be re-run manually.
+ *
+ * `changedMask` is a bitmask of the for-var positions whose references
+ * actually changed in this update. Each effect carries `forVarMask`
+ * (computed at compile time) listing the for-vars its body reads; effects
+ * whose `forVarMask & changedMask === 0` are skipped. Mount callbacks
+ * (`isMountEffect` — `$onmount`/`onmount`) are always skipped: they run
+ * once per DOM mount and their bodies are untracked.
+ *
+ * Equivalent to what `checkEffect` does when a signal has propagated, but
+ * unconditional for the effects that do match: cleanup → deactivate sources
+ * → run → clear unused sources, for every matching effect on the region and
+ * on every descendant region (`depth > region.depth`, the same chain shape
+ * `clearRegion` walks).
+ */
+declare function rerunRegionEffects(region: Region, changedMask: number): void;
+//#endregion
+//#region src/render/restoreHydration.d.ts
+/**
+ * Restores the hydration cursor to a previously-snapshotted node. Used by
+ * `@try`/`@catch`: if the try branch throws partway through its hydration
+ * walk, the catch branch must resume hydrating from where the try group
+ * started, not from wherever the failed branch left the cursor.
+ *
+ * The cursor is set unconditionally: a failed try-branch build can walk the
+ * cursor past the last node (setting it to `null` via `nodeNext`), and the
+ * rewind must still restore it — otherwise the catch branch would think it
+ * isn't hydrating and insert fresh nodes alongside the server's. When not
+ * hydrating at all, the snapshot itself is `null`, so this is a no-op.
+ *
+ * @param node The snapshotted cursor node (from `saveHydration`).
+ */
+declare function restoreHydration(node: ChildNode | null): void;
+//#endregion
 //#region src/render/runControl.d.ts
 /**
-* Runs an `if`, `switch` or `await` control statement
-* @param create A function that creates the control statement's branches
-*/
+ * Runs an `if`, `switch` or `await` control statement
+ * @param create A function that creates the control statement's branches
+ */
 declare function runControl(region: Region, anchor: Node | null, create: (anchor: Node | null) => void, name?: string): void;
 //#endregion
 //#region src/render/runControlBranch.d.ts
@@ -139,10 +318,103 @@ declare function runControlBranch(region: Region, oldIndex: number, index: numbe
 //#endregion
 //#region src/render/runList.d.ts
 /**
-* Runs a `for` control statement
-* @param create A function that creates the control statement's branches
-*/
-declare function runList(region: Region, parent: ParentNode, anchor: Node | null, buildItems: () => ListItem[], create: (item: ListItem, anchor: Node | null) => void, update: (oldItem: ListItem, newItem: ListItem) => void): void;
+ * Runs a `for` control statement
+ * @param buildItems A function that returns the current list of lightweight
+ *   `{key, data}` specs (one per row of the source data)
+ * @param create A function that creates the control statement's branches
+ * @param noWatch When true, the compiler has determined the `@for` body never
+ *   writes to its loop variables, so each item's `data` bag can be left
+ *   unwrapped (skipping the per-item shallow `$watch` Proxy + ProxyData +
+ *   signals Map allocations). The compiler-emitted `update` callback is then
+ *   responsible for re-running item effects when a loop variable's reference
+ *   actually changes (via `t_rerun_region_effects`).
+ */
+declare function runList(region: Region, parent: ParentNode, anchor: Node | null, buildItems: () => ListItemSpec[], create: (item: ListItem, anchor: Node | null) => void, update: (oldItem: ListItem, newSpec: ListItemSpec) => void, noWatch?: boolean): void;
+//#endregion
+//#region src/render/runAwait.d.ts
+/**
+ * Renders an `@await` boundary. On the first run, content is rendered
+ * speculatively; if any read inside suspends (`didSuspend`), the boundary
+ * discards the partial render and shows the `with` branch instead.
+ *
+ * Fine-grained updates: on subsequent runs the boundary only decides whether
+ * to SWITCH branches. It does so from its `pending` set — the suspended
+ * computeds recorded by `suspendRead` — dropping entries that resolved and
+ * re-subscribing the still-suspended ones (a re-run deactivates all of the
+ * effect's source subscriptions, so they must be re-tracked to survive
+ * `clearSources`). That check is O(pending reads), not O(all sources), and
+ * non-suspend dependency changes inside content are left to the child
+ * effects that read them — the boundary isn't re-run by them at all.
+ *
+ * Stale-while-revalidate (ASYNC.md §6.2): once content has been produced
+ * (`hasContent`), a subsequent suspend during a refresh does NOT switch to
+ * the `with` branch — the boundary keeps the stale content mounted. `$async`
+ * retains the previous resolved value (`Computed.staleValue`) and
+ * `suspendRead` returns it, so child effects keep displaying the old value
+ * until the new promise resolves and updates them in place. The `with` branch
+ * is shown only on the first load, before content has ever rendered
+ * successfully.
+ *
+ * @param renderContent Builds the content children (may read $async getters).
+ * @param renderWith Builds the `with`-branch children, or null for empty.
+ */
+declare function runAwait(region: Region, anchor: Node | null, renderContent: (anchor: Node | null) => void, renderWith: ((anchor: Node | null) => void) | null, name?: string): void;
+//#endregion
+//#region src/render/runTry.d.ts
+/**
+ * Renders a `@try`/`@catch` group, or a top-level `@error` block (which the
+ * compiler wraps around the whole render).
+ *
+ * Like `runAwait`, the boundary is a control effect that renders one branch
+ * at a time into a fresh child region (`runControlBranch` clears the old
+ * branch on switch). Unlike the old compiled form, the try/catch lives in
+ * this runtime, which gives it three capabilities the compiled form lacked:
+ *
+ * - **Effect-rerun error routing.** The boundary registers itself on its
+ *   region (`region.errorBoundary`); when an effect inside the try content
+ *   throws on a later re-run, `triggerEffects` → `routeEffectError` stores
+ *   the error here and force re-runs the boundary effect, which renders the
+ *   catch branch with it.
+ * - **Recovery outside direct reads.** Reactive reads wrapped in nested
+ *   `$run` effects (text/attribute interpolation) are tracked by those
+ *   effects, not the boundary. When an error is routed, the boundary holds
+ *   the erroring effect's source signals (`heldSignals`) and re-subscribes
+ *   to them on every run that shows the catch branch, so a later change
+ *   re-attempts the try branch.
+ * - **Top-level `@error` recovery.** Because the whole render is a
+ *   re-runnable branch, a later re-render error (from a nested control
+ *   re-running after a prop change) is caught by the same routing, and a
+ *   recovery re-render clears the error content and restores the normal
+ *   content.
+ *
+ * Semantics preserved from the compiled form:
+ *
+ * - Synchronous build errors in the try content render the catch branch
+ *   (rewinding the hydration cursor and restoring the control region, which
+ *   the failed partial build left active).
+ * - While the try branch is showing, a boundary re-run with no routed error
+ *   does NOT rebuild it (`runControlBranch` same-index skip) — exactly like
+ *   `@if`/`@switch` branches.
+ * - While the catch branch is showing, any boundary re-run re-attempts the
+ *   try branch (the recovery path for errors read directly by the boundary
+ *   effect, e.g. via `@const`).
+ * - With no catch branch, errors propagate up to the nearest outer boundary
+ *   and no boundary is registered on the region.
+ *
+ * @param renderTry Builds the try content. May read reactive state.
+ * @param renderCatch Builds the catch content, or null for `@try` without
+ *   `@catch`. Receives the error (the `@catch (err)` variable).
+ */
+declare function runTry(region: Region, anchor: Node | null, renderTry: (anchor: Node | null) => void, renderCatch: ((anchor: Node | null, error: any) => void) | null, name?: string): void;
+//#endregion
+//#region src/render/saveHydration.d.ts
+/**
+ * Snapshots the hydration cursor so a `@try` branch's partial hydration walk
+ * can be rewound if the branch throws and the `@catch` branch renders instead.
+ *
+ * @returns The current hydration cursor node, or `null` when not hydrating.
+ */
+declare function saveHydration(): ChildNode | null;
 //#endregion
 //#region src/render/setAttribute.d.ts
 declare function setAttribute(el: Element, name: string, value: any): void;
@@ -150,77 +422,293 @@ declare function setAttribute(el: Element, name: string, value: any): void;
 //#region src/render/setDynamicElement.d.ts
 declare function setDynamicElement(el: HTMLElement, tag: string): HTMLElement;
 //#endregion
+//#region src/types/Bindable.d.ts
+/**
+ * Type-level marker that documents a component prop as supporting two-way
+ * binding via the `&` prefix at the call site.
+ *
+ * `Bindable<T>` is structurally just `T` — it has no runtime effect. It tells
+ * component authors and consumers "this prop is intended to be bound with
+ * `&prop={expr}`." Inside the component, use `$bind($state, $props, [...])`
+ * to wire up the actual two-way sync.
+ *
+ * Example:
+ * ```ts
+ * interface MyProps {
+ *     value: Bindable<string>;
+ * }
+ * ```
+ */
+type Bindable<T> = T;
+//#endregion
 //#region src/watch/$batch.d.ts
 /**
-* Runs updates to proxy values in a batch, where the updates are stored in
-* context, and dependent effects are run all at once at the end.
-*
-* @param fn The function containing the batched updates to run.
-*/
+ * Runs updates to proxy values in a batch, where the updates are stored in
+ * context, and dependent effects are run all at once at the end.
+ *
+ * @param fn The function containing the batched updates to run.
+ */
 declare function $batch<T>(fn: () => T): T;
 //#endregion
+//#region src/watch/$async.d.ts
+/**
+ * Caches an async computed value from a thunk that returns a Promise. A peer
+ * of `$cache` for async getters: the returned Computed carries a `didSuspend`
+ * indicator that the proxy get trap reads to suspend callers until the promise
+ * resolves.
+ *
+ * The thenable check and `.then` wiring live inside `computed.run` (a closure
+ * over the computed object), so they fire on both the initial run and every
+ * recalculation — `runComputed` and `checkComputed` are unchanged.
+ *
+ * @param fn A thunk returning the Promise to await. Signal reads inside `fn`
+ *   are tracked, so the fetch re-runs when dependencies change.
+ */
+declare function $async<T>(fn: () => Promise<T>): T;
+//#endregion
+//#region src/watch/$bind.d.ts
+/**
+ * Establishes two-way reactive sync between matching keys on a state object
+ * and a props object.
+ *
+ * For each key, `$bind` creates:
+ * - **Forward sync** (`props → state`): when the parent pushes a new value via
+ *   `$props[key]`, it flows into `$state[key]`. Skips `undefined` values so
+ *   that defaults set in the initial `$watch(...)` are preserved when the
+ *   parent doesn't provide a value.
+ * - **Backward sync** (`state → props`): when the component mutates
+ *   `$state[key]`, the new value is written back to `$props[key]`, which the
+ *   call site's `&key={...}` binding picks up and propagates to the parent.
+ *
+ * Same-value writes are no-ops (handled by the proxy layer), so two-way sync
+ * stabilises without infinite loops.
+ *
+ * `$bind` syncs same-named keys, so the key must exist on the state object.
+ * A state key named differently from the prop (e.g. `values` against a
+ * `value` prop) would silently do nothing -- the binding reads and writes
+ * keys that nothing else touches -- which is almost impossible to debug. The
+ * key is therefore required to exist on the state object, and `$bind` throws
+ * at setup otherwise.
+ *
+ * The prop does *not* need to exist on `props` yet: when the parent doesn't
+ * pass an optional prop, the compiled props object has no key for it, and
+ * the binding is simply inert (uncontrolled mode) until a value is pushed.
+ *
+ * @param state The component's reactive state (created via `$watch`).
+ * @param props The component's `$props` proxy. When `undefined` (component
+ *   called with no props), `$bind` does nothing.
+ * @param keys Keys to sync. Each key must exist on `state`.
+ * @throws When a key does not exist on the state object.
+ */
+declare function $bind(state: Record<PropertyKey, any>, props: Record<PropertyKey, any> | undefined, ...keys: (string | string[])[]): void;
+//#endregion
 //#region src/watch/$cache.d.ts
 /**
-* Caches a computed value from signals accessed in a property getter.
-*
-* @param fn The function containing the signals to compute and cache.
-*/
+ * Caches a computed value from signals accessed in a property getter.
+ *
+ * @param fn The function containing the signals to compute and cache.
+ */
 declare function $cache<T>(fn: () => T): T;
 //#endregion
-//#region src/watch/$mount.d.ts
+//#region src/watch/$onmount.d.ts
 /**
-* Runs and re-runs a function on component mount
-*
-* @param fn The function to run, which may return a cleanup function
-*/
-declare function $mount(fn: () => Cleanup | void): void;
+ * Runs `fn` once after the component is mounted to the DOM. May return a
+ * cleanup function that runs on unmount / region clear.
+ *
+ * The callback is **not reactive**: it runs exactly once per mount, and
+ * reactive values it reads are not tracked. To set up something that should
+ * keep updating, wrap the reactive part in `$run`:
+ *
+ * ```ts
+ * $onmount(() => {
+ * 	$run(() => {
+ * 		label.textContent = $state.count > 0 ? "+" : "";
+ * 	});
+ * });
+ * ```
+ *
+ * The element-level equivalent is the `onmount` attribute:
+ * `<input onmount={(el) => el.focus()} />`.
+ *
+ * @param fn The function to run, which may return a cleanup function
+ */
+declare function $onmount(fn: () => Cleanup | void): void;
 //#endregion
 //#region src/watch/$peek.d.ts
+/**
+ * Runs a function without tracking the reactive values it reads: `$watch`'d
+ * state accessed inside `fn` does not become a dependency of the currently
+ * running effect or computed. Useful for reading state inside an effect
+ * without re-running it when that state changes.
+ *
+ * @param fn The function to run untracked.
+ */
 declare function $peek<T>(fn: () => T): T;
 //#endregion
+//#region src/watch/$pending.d.ts
+/**
+ * Returns `true` if any value read inside `fn` is currently suspended in a
+ * "loud" way — a `$async` getter whose promise hasn't resolved yet. A reactive
+ * query for inline "loading…" indicators: the calling effect subscribes to the
+ * same computeds, so `$pending` re-evaluates when they resolve.
+ *
+ * Uses a "peek mode" internally: reads during `fn` are tracked for
+ * subscription but don't propagate taint or notify a `@await` boundary.
+ * This lets `$pending` return a plain boolean without itself suspending.
+ *
+ * Quiet-on-refresh semantics (ASYNC.md §7.4): a suspend is *quiet* — and
+ * therefore `$pending` returns `false` for it — when the computed has resolved
+ * before and the re-fetch was a *silent* `$refresh(fn, { silent: true })` (a
+ * bare refresh with no tracked dependency change, used for background
+ * revalidation). This matches Solid's stale-while-revalidate default: quietly
+ * re-asking the same question shouldn't ping the user. First loads and
+ * dependency-change refreshes are loud (`true`), as is the default (loud)
+ * `$refresh(fn)`. Quiet-ness is captured per computed at suspend time via
+ * `suspendQuiet` (computed in `$async`'s run from `hasResolved` and `recalc`).
+ *
+ * @param fn A function that reads the reactive values to check.
+ */
+declare function $pending(fn: () => any): boolean;
+//#endregion
+//#region src/watch/$refresh.d.ts
+/**
+ * Options for `$refresh`.
+ */
+interface RefreshOptions {
+  /**
+   * Re-fetch silently — stale-while-revalidate. The suspend is *quiet*
+   * (`$pending` stays `false`) and subscribers aren't notified until the new
+   * promise resolves. For background revalidation: polling, refetch-on-
+   * focus. Defaults to `false` — a refresh is loud, so `$pending` reads
+   * `true` and inline "updating…" indicators flip on at refresh start.
+   */
+  silent?: boolean;
+}
+/**
+ * Re-fetches the `$async` getters read inside `fn` without changing a
+ * dependency. A companion to `$pending` (ASYNC.md §6.2): pull-to-refresh,
+ * refresh buttons, refetch-on-focus, polling, retry-after-error.
+ *
+ * `fn` is run in a tracking context that collects every `$async` computed it
+ * reads (`$cache` computeds are ignored). Each collected computed is then
+ * re-run with `recalc` left true — a "bare refresh" — so the suspend is
+ * *loud*: `$pending(fn)` returns `true` while the re-fetch is in flight and
+ * subscribers are notified at suspend *start*, so an inline "updating…"
+ * indicator appears immediately. Readers keep displaying the previous
+ * resolved value (`Computed.staleValue`) until the new promise resolves and
+ * propagates through the reactive graph; an `@await` boundary keeps its
+ * content mounted instead of flashing fallback.
+ *
+ * Pass `{ silent: true }` to re-fetch quietly (stale-while-revalidate):
+ * `$pending(fn)` stays `false` and nothing re-runs until the new promise
+ * resolves. For background revalidation where feedback would be noise —
+ * polling, refetch-on-focus:
+ *
+ * ```torp
+ * // poll quietly every 30s
+ * $run(() => {
+ * 	const id = setInterval(() => $refresh(() => $state.data, { silent: true }), 30_000);
+ * 	return () => clearInterval(id);
+ * });
+ * ```
+ *
+ * A refresh is loud regardless of `silent` when the computed has never
+ * resolved — e.g. retrying after an error that left `didError` set on a first
+ * load — or when the re-fetch is triggered by a dependency change, which
+ * flows through the normal `recalc` path instead of here.
+ *
+ * If `fn` reads a getter the UI has never read, the collection read
+ * initializes it — and that fetch IS the refresh: the computed is not re-run
+ * (a second fetch would be a duplicate whose resolve the generation guard
+ * drops). Getters already read (pending, resolved, or errored) are re-run as
+ * usual.
+ *
+ * The returned value of `fn` is ignored; use `fn` to reference the getters.
+ */
+declare function $refresh(fn: () => any, options?: RefreshOptions): void;
+//#endregion
 //#region src/watch/$run.d.ts
 /**
-* Runs and re-runs a function that depends on a watched object
-*
-* @param fn The function to run, which may return a cleanup function.
-*/
-declare function $run(fn: () => Cleanup | void, name?: string): Effect;
+ * Runs and re-runs a function that depends on a watched object
+ *
+ * @param fn The function to run, which may return a cleanup function.
+ * @param options Internal fields to set on the constructed Effect (e.g.
+ *   `isMountEffect`, `forVarDeps`). Not part of the public API.
+ */
+declare function $run(fn: () => Cleanup | void, name?: string, options?: Pick<Effect, "isMountEffect" | "forVarMask">): Effect;
+//#endregion
+//#region src/watch/$stream.d.ts
+/**
+ * Subscribes to an external source of events — server-sent events,
+ * WebSockets, DOM events, or any custom `StreamSource` — and calls
+ * `handler` for each event it pushes. Events are typically written into
+ * reactive state, which keeps templates, computeds and effects updating
+ * through the normal reactivity model:
+ *
+ * ```torp
+ * let $state = $watch({ messages: [] as string[] });
+ *
+ * $stream(fromServer(`/sse/${$props.id}`), (e) => {
+ * 	$state.messages.push(e.data);
+ * });
+ * ```
+ *
+ * The subscription is managed by the framework:
+ *
+ * - It starts when the component is mounted to the DOM (so `&ref`-bound
+ *   elements are available), and is unsubscribed when the component
+ *   unmounts or its region is cleared.
+ * - Reactive state read *inside* the source is tracked: when it changes,
+ *   the source is unsubscribed and re-subscribed with fresh values (e.g.
+ *   re-opening a connection when a user id changes). A pending debounced
+ *   call is dropped on re-subscribe.
+ * - The source is never invoked during a server render, so browser-only
+ *   APIs are safe to use.
+ *
+ * Errors are values like any other: a source that can fail should push an
+ * error-shaped value and own its own reconnection (e.g. `EventSource`
+ * reconnects automatically).
+ *
+ * @param source The stream source to subscribe to
+ * @param handler Called for each event the source pushes
+ * @param options Timing options. `debounce` delays each handler call until
+ *   the source has been quiet for that many milliseconds, resetting on
+ *   every event (only the last event in a burst is handled).
+ */
+declare function $stream<T>(source: StreamSource<T>, handler: (value: T) => void, options?: {
+  debounce?: number;
+}): void;
 //#endregion
 //#region src/watch/$unwrap.d.ts
 /**
-* Returns the target object of a proxy
-*
-* @param object The proxy object
-*/
+ * Returns the target object of a proxy
+ *
+ * @param object The proxy object
+ */
 declare function $unwrap<T extends Record<PropertyKey, any>>(object: T): T;
 //#endregion
 //#region src/types/WatchOptions.d.ts
 /**
-* Options for $watch.
-*/
+ * Options for $watch.
+ */
 interface WatchOptions {
   /**
-  * Only watch top-level properties, don't recursively watch children.
-  */
+   * Only watch top-level properties, don't recursively watch children.
+   */
   shallow?: boolean;
 }
 //#endregion
 //#region src/watch/$watch.d.ts
 /**
-* Watches an object and runs effects when its properties are changed
-*
-* @param object The object to watch
-*/
-declare function $watch<T extends Record<PropertyKey, any>>(object: T, options?: WatchOptions): T;
-//#endregion
-//#region src/wrappers/ReactiveDate.d.ts
-/**
-* Wraps a Date object for $watching.
-*/
-declare class ReactiveDate extends Date {
-  #private;
-  constructor(...params: any[]);
-}
-//#endregion
-export { $batch, $cache, $mount, $peek, $run, $unwrap, $watch, type Animation, type ClassValue, type Component, type ListItem, ReactiveDate, type SlotRender, type StyleValue, clearLayoutSlot, fillLayoutSlot, hydrate, mount, addFragment as t_add_fragment, nodeAnchor as t_anchor, addAnimation as t_animate, applyProps as t_apply_props, setAttribute as t_attribute, nodeChild as t_child, buildClasses as t_class, setDynamicElement as t_dynamic, addEvent as t_event, formatText as t_fmt, getFragment as t_fragment, newListItem as t_list_item, nodeNext as t_next, popRegion as t_pop_region, pushRegion as t_push_region, newRegion as t_region, nodeRoot as t_root, runControlBranch as t_run_branch, runControl as t_run_control, runList as t_run_list, nodeSkip as t_skip, buildStyles as t_style };
+ * Watches an object and runs effects when its properties are changed.
+ *
+ * Dates, Maps and Sets are supported too: their methods are reactive (reads
+ * track, writes notify), so `new Date()`, `new Map()` and `new Set()` can be
+ * used in watched state directly.
+ *
+ * @param object The object to watch
+ */
+declare function $watch<T extends object>(object: T, options?: WatchOptions): T;
+//#endregion
+export { $async, $batch, $bind, $cache, $onmount, $peek, $pending, $refresh, $run, $stream, $unwrap, $watch, type Animation, type Bindable, type ClassValue, type Component, type ListItem, type ListItemSpec, type SlotRender, type StreamSource, type StyleValue, clearLayoutSlot, fillLayoutSlot, fromElement, fromServer, fromWebSocket, hydrate, mount, addElement as t_add_element, addFragment as t_add_fragment, nodeAnchor as t_anchor, addAnimation as t_animate, applyProps as t_apply_props, setAttribute as t_attribute, nodeChild as t_child, buildClasses as t_class, setDynamicElement as t_dynamic, addEvent as t_event, formatText as t_fmt, getFragment as t_fragment, getElementFragment as t_fragment_el, newListItem as t_list_item, nodeNext as t_next, popRegion as t_pop_region, pushRegion as t_push_region, newRegion as t_region, rerunRegionEffects as t_rerun_region_effects, restoreHydration as t_restore_hydration, nodeRoot as t_root, nodeRootElement as t_root_el, runAwait as t_run_await, runControlBranch as t_run_branch, runControl as t_run_control, runList as t_run_list, runTry as t_run_try, saveHydration as t_save_hydration, nodeSkip as t_skip, buildStyles as t_style, unmount };
 //# sourceMappingURL=index.d.mts.map