@estjs/template 0.0.15-beta.13 → 0.0.15-beta.17

package/dist/template.d.ts

@@ -1,224 +1,235 @@
 import { Signal, Computed } from '@estjs/signals';
+import { S as Scope } from './internal-Bz6h0aPa.js';
+export { I as InjectionKey, i as inject, p as provide } from './internal-Bz6h0aPa.js';
+import { normalizeClassName } from '@estjs/shared';
 
-/**
- * InjectionKey is a unique identifier for provided values.
- * Using Symbol ensures type safety and prevents key collisions.
- */
-interface InjectionKey<T> extends Symbol {
+declare enum COMPONENT_STATE {
+    /** Initial state */
+    INITIAL = 0,
+    /** Mounting */
+    MOUNTING = 1,
+    /** MOUNTED */
+    MOUNTED = 2,
+    /** Updating */
+    UPDATING = 3,
+    /** Destroying */
+    DESTROYING = 4,
+    /** destroy */
+    DESTROYED = 5
 }
-/**
- * Provide a value in the current scope.
- * The value can be injected by this scope or any descendant scope.
- *
- * @param key - The injection key
- * @param value - The value to provide
- */
-declare function provide<T>(key: InjectionKey<T> | string | number, value: T): void;
-/**
- * Inject a value from the scope hierarchy.
- * Traverses up the parent chain until finding a matching key.
- *
- * @param key - The injection key
- * @param defaultValue - Default value if key is not found
- * @returns The injected value or default value
- */
-declare function inject<T>(key: InjectionKey<T> | string | number, defaultValue?: T): T;
-
-/**
- * Scope represents an execution context in the component tree.
- * It manages provides, cleanup functions, and lifecycle hooks.
- */
-interface Scope {
-    /** Unique identifier for debugging */
-    readonly id: number;
-    /** Parent scope in the hierarchy */
-    parent: Scope | null;
-    /** Child scopes (lazy initialized) */
-    children: Set<Scope> | null;
-    /** Provided values (lazy initialized) */
-    provides: Map<InjectionKey<unknown> | string | number | symbol, unknown> | null;
-    /** Cleanup functions (lazy initialized) */
-    cleanup: Set<() => void> | null;
-    /** Mount lifecycle hooks (lazy initialized) */
-    onMount: Set<() => void | Promise<void>> | null;
-    /** Update lifecycle hooks (lazy initialized) */
-    onUpdate: Set<() => void | Promise<void>> | null;
-    /** Destroy lifecycle hooks (lazy initialized) */
-    onDestroy: Set<() => void | Promise<void>> | null;
-    /** Whether the scope has been mounted */
-    isMounted: boolean;
-    /** Whether the scope has been destroyed */
-    isDestroyed: boolean;
+declare enum COMPONENT_TYPE {
+    NORMAL = "normal",
+    FRAGMENT = "fragment",
+    PORTAL = "portal",
+    SUSPENSE = "suspense",
+    FOR = "for"
 }
-/**
- * Get the currently active scope.
- * @returns The active scope or null if none is active
- */
-declare function getActiveScope(): Scope | null;
-/**
- * Set the active scope (internal use).
- * @param scope - The scope to set as active
- */
-declare function setActiveScope(scope: Scope | null): void;
-/**
- * Create a new scope with optional parent.
- * If no parent is provided, uses the current active scope as parent.
- *
- * @param parent - Optional parent scope (defaults to active scope)
- * @returns A new scope instance
- */
-declare function createScope(parent?: Scope | null): Scope;
-/**
- * Run a function within a scope, ensuring proper cleanup.
- * The previous active scope is restored even if the function throws.
- *
- * @param scope - The scope to run within
- * @param fn - The function to execute
- * @returns The return value of the function
- */
-declare function runWithScope<T>(scope: Scope, fn: () => T): T;
-/**
- * Dispose a scope and all its children.
- * Children are disposed first (depth-first), then the scope itself.
- *
- * @param scope - The scope to dispose
- */
-declare function disposeScope(scope: Scope): void;
-/**
- * Register a cleanup function in the current scope.
- * The function will be called when the scope is disposed.
- *
- * @param fn - The cleanup function
- */
-declare function onCleanup(fn: () => void): void;
-
-declare const NORMAL_COMPONENT: unique symbol;
 
 type AnyNode = Node | Component<any> | Element | string | number | boolean | null | undefined | AnyNode[] | (() => AnyNode) | Signal<AnyNode> | Computed<AnyNode>;
 type ComponentProps = Record<string, unknown>;
 type ComponentFn<P = ComponentProps> = (props: P) => AnyNode;
 
-declare class Component<P extends ComponentProps = ComponentProps> {
-    component: ComponentFn<P>;
+declare class Component<P extends ComponentProps = {}> {
+    readonly component: ComponentFn<P>;
     props: P;
-    protected renderedNodes: AnyNode[];
-    protected scope: Scope | null;
-    protected parentNode: Node | undefined;
+    readonly [COMPONENT_TYPE.NORMAL] = true;
+    scope: Scope | null;
+    state: COMPONENT_STATE;
     beforeNode: Node | undefined;
-    private reactiveProps;
-    private _propSnapshots;
-    readonly key: string | undefined;
-    protected state: number;
-    protected parentScope: Scope | null;
-    readonly [NORMAL_COMPONENT] = true;
-    get isConnected(): boolean;
-    get firstChild(): Node | undefined;
+    renderedNodes: Node[];
+    firstChild: Node | undefined;
+    protected parentNode: Node | undefined;
+    private readonly parentScope;
+    private readonly reactiveProps;
+    private rootEventCleanups;
+    private rootRefCleanup?;
     constructor(component: ComponentFn<P>, props?: P);
+    /**
+     * Mount the component into `parentNode` (optionally before `beforeNode`).
+     * If already rendered, the existing DOM is re-inserted without re-running
+     * the component function.
+     */
     mount(parentNode: Node, beforeNode?: Node): AnyNode[];
-    update<T extends ComponentProps>(prevNode: Component<T>): Component<T>;
     /**
-     * Update reactive props by comparing with current values
+     * Re-install props into the same `reactiveProps` container (preserving
+     * any closures already holding a reference to it) and re-apply
+     * refs/events against the current root element.
      */
-    private _updateReactiveProps;
-    private unwrapRenderResult;
-    forceUpdate(): void;
+    update(props: P): void;
     /**
-     * Get anchor node for insertion
+     * Tear down and re-mount the component at its current insertion point.
+     * No-op if the component has never been mounted.
      */
-    private _getAnchorNode;
+    forceUpdate(): void;
     /**
-     * Destroy component
+     * Dispose the scope, remove all rendered nodes, and clear bookkeeping.
+     * Idempotent: subsequent calls are no-ops.
      */
     destroy(): void;
-    applyProps(props: P): void;
+    /**
+     * Apply props that bind to the root DOM element rather than flowing into
+     * the component body: `ref` (signal/function) and `onXxx` event handlers.
+     * The render-facing `reactiveProps` already has those keys; here we just
+     * wire them to the actual DOM node.
+     */
+    private syncSpecialProps;
+    /**
+     * Remove all listeners/ref bindings currently attached to the root element.
+     */
+    private releaseSpecialProps;
+    /**
+     * Bind the root ref prop and return a cleanup that restores the previous ref state.
+     */
+    private bindRootRef;
 }
 /**
- * check if a node is a component
- * @param {unknown} node - the node to check
- * @returns {boolean} true if the node is a component, false otherwise
+ * Check if a value is a Component instance.
  */
 declare function isComponent(node: unknown): node is Component;
 /**
- * create a component
- * @param {Function} componentFn - the component function
- * @param {ComponentProps} props - the component props
- * @returns {Component} the component
+ * Wrap a component function in a Component instance, or pass an existing
+ * Component instance through unchanged.
  */
 declare function createComponent<P extends ComponentProps>(componentFn: ComponentFn<P>, props?: P): Component<P>;
 
 /**
- * Create a template factory function from HTML string
+ * Create a template factory function from HTML string.
  *
  * This function creates a reusable template factory that efficiently clones
- * DOM nodes from the provided HTML string. The template is parsed once and
+ * DOM nodes from the provided HTML string. The template is parsed once.
  *
- * @param html - The HTML string to create template from
- * @returns Factory function that returns a cloned node of the template
- * @throws {Error} When template content is empty or invalid
-
+ * Security note: `template(html)` is a raw HTML entrypoint. The caller is
+ * responsible for ensuring `html` is trusted and not derived from unsanitized
+ * user input.
+ *
+ * @param html - The HTML string to create template from.
+ * @returns Factory function that returns a cloned node of the template.
+ * @throws {Error} When template content is empty or invalid.
+ *
+ * @example
+ * ```typescript
+ * const buttonTemplate = template('<button>Click me</button>');
+ * const button1 = buttonTemplate(); // Creates first button instance
+ * const button2 = buttonTemplate(); // Creates second button instance
+ * ```
  */
 declare function template(html: string): () => Node;
 /**
- * Create and mount an application with the specified component
+ * Create and mount an application with the specified component.
  *
  * This function initializes an application by mounting a root component
  * to a target DOM element. It handles target validation and cleanup.
  *
- * @param component - The root component function to mount
- * @param target - CSS selector string or DOM element to mount to
- * @returns The mount root component instance, or undefined if target not found
+ * @param component - The root component function to mount.
+ * @param target - CSS selector string or DOM element to mount to.
+ * @returns Object with root component and unmount function.
+ *
+ * @example
+ * ```typescript
+ * const App = () => template('<div>Hello World</div>')
+ * const app = createApp(App, '#root');
+ *
+ * // Or with DOM element
+ * const container = document.getElementById('app');
+ * const app = createApp(App, container);
+ * ```
  */
-declare function createApp<P extends ComponentProps = {}>(component: ComponentFn<P> | Component<P>, target: string | Element): Component<P> | undefined;
+declare function createApp<P extends ComponentProps = {}>(component: ComponentFn<P>, target: string | Element): {
+    root: Component<{}> | undefined;
+    unmount: () => void;
+} | undefined;
+declare function hydrate<P extends ComponentProps = {}>(component: ComponentFn<P>, target: string | Element): {
+    root: Component<{}> | undefined;
+    unmount: () => void;
+} | undefined;
 
 type LifecycleHook = () => void | Promise<void>;
 /**
  * Register a mount lifecycle hook.
- * Called after the component is mounted to the DOM.
+ * If the scope is already mounted, the hook is executed immediately.
  *
- * @param hook - The hook function to execute on mount
+ * @param hook - The hook function to register.
+ * @returns {void}
  */
 declare function onMount(hook: LifecycleHook): void;
+/**
+ * Register an update lifecycle hook.
+ *
+ * @param hook - The hook function to register.
+ * @returns {void}
+ */
+declare function onUpdate(hook: LifecycleHook): void;
 /**
  * Register a destroy lifecycle hook.
- * Called before the component is removed from the DOM.
  *
- * @param hook - The hook function to execute on destroy
+ * @param hook - The hook function to register.
+ * @returns {void}
  */
 declare function onDestroy(hook: LifecycleHook): void;
+
 /**
- * Register an update lifecycle hook.
- * Called after the component updates.
+ * Modifiers supported by `bind:*` two-way bindings.
  *
- * @param hook - The hook function to execute on update
+ * - `trim`   strip surrounding whitespace from string values
+ * - `number` coerce numeric strings to numbers (no-op on `NaN`)
+ * - `lazy`   commit on `change` instead of `input`
  */
-declare function onUpdate(hook: LifecycleHook): void;
+interface BindModifiers {
+    trim?: boolean;
+    number?: boolean;
+    lazy?: boolean;
+    [key: string]: boolean | undefined;
+}
+/**
+ * Synchronizes a DOM element property with a model getter and setter.
+ *
+ * @param node      The element to bind. `null` is tolerated (no-op).
+ * @param prop      Bound property: `value` / `checked` / `files` / arbitrary.
+ * @param getter    Reactive getter or static initial value.
+ * @param setter    Receives the new value when the user edits the DOM.
+ * @param modifiers Optional `BindModifiers`.
+ */
+declare function bindElement(node: Element | null, prop: 'value' | 'checked' | 'files' | string, getter: (() => unknown) | unknown, setter: (value: unknown) => void, modifiers?: BindModifiers): void;
 
 /**
- * Add event listener with automatic cleanup on scope destruction
+ * Set up event delegation for specified event types.
+ *
+ * @param eventNames - Array of event names to delegate.
+ * @param document - Document to attach events to (defaults to window.document).
+ */
+declare function delegateEvents(eventNames: string[], document?: Document): void;
+/**
+ * Clear all delegated events from document.
  *
- * @param element - Element to attach listener to
- * @param event - Event name
- * @param handler - Event handler function
- * @param options - Event listener options
+ * @param document - Document to clear events from (defaults to window.document).
+ */
+declare function clearDelegatedEvents(document?: Document): void;
+/**
+ * Registers an event listener and scopes its cleanup when needed.
+ *
+ * @param element - The element to add the listener to.
+ * @param event - The event name.
+ * @param handler - The event handler.
+ * @param options - Optional event listener options.
+ * @returns {void}
  */
 declare function addEventListener(element: Element, event: string, handler: EventListener, options?: AddEventListenerOptions): void;
+
 /**
- * Bind an element to a setter function for two-way data binding
+ * Omits props from a target object using a proxy.
  *
- * @param node - The element to bind
- * @param key - The property key (unused, kept for API compatibility)
- * @param defaultValue - Default value (unused, kept for API compatibility)
- * @param setter - The setter function to call when the element's value changes
+ * @param target - The target object.
+ * @param keys - The keys to omit.
+ * @returns A proxy that omits specified keys.
  */
-declare function bindElement(node: Element, key: string, defaultValue: unknown, setter: (value: unknown) => void): void;
+declare function omitProps<T extends object, K extends keyof T>(target: T, keys: K[]): Omit<T, K>;
+
 /**
  * Reactive node insertion with binding support
  *
  * @param parent Parent node
  * @param nodeFactory Node factory function or static node
  * @param before Reference node for insertion position
- * @param options Insertion options
- *
  * @example
  * ```typescript
  * insert(container, () => message.value, null);
@@ -226,212 +237,203 @@ declare function bindElement(node: Element, key: string, defaultValue: unknown,
  * insert(container, "Hello World", null); // Direct string support
  * ```
  */
-declare function insert(parent: Node, nodeFactory: AnyNode, before?: Node): AnyNode[] | undefined;
+declare function insert(parent: Node, nodeFactory: AnyNode, before?: Node): Node[] | undefined;
 /**
- * Map nodes from template by indexes
+ * Returns the first child of a node.
  *
- * @param template - Template node to traverse
- * @param indexes - Array of indexes to map
- * @returns Array of mapped nodes
+ * @param node - The node to get the child from.
+ * @returns The first child node or null.
  */
-declare function mapNodes(template: Node, indexes: number[]): Node[];
-
-/**
- * Set up event delegation for specified event types
- * @param {string[]} eventNames - Array of event names to delegate
- * @param {Document} document - Document to attach events to (defaults to window.document)
- */
-declare function delegateEvents(eventNames: string[], document?: Document): void;
-
+declare function child(node: Node | null): Node | null;
 /**
- * Create a reactive proxy that excludes specified properties
+ * Returns the next sibling after advancing by `step`.
  *
- * @param target - The original reactive object
- * @param keys - List of property names to exclude
- * @returns A reactive proxy with specified properties excluded
+ * @param node - The starting node.
+ * @param step - Number of steps to advance.
+ * @returns The resulting sibling node or null.
  */
-declare function omitProps<T extends object, K extends keyof T>(target: T, keys: K[]): Omit<T, K>;
-
+declare function next(node: Node | null, step?: number): Node | null;
 /**
- * DOM manipulation utilities
+ * Returns the child node at the requested index.
+ *
+ * @param node - The parent node.
+ * @param index - The child index.
+ * @returns The child node at index or null.
  */
+declare function nthChild(node: Node | null, index: number): Node | null;
 
 /**
- * Remove node from its parent
+ * Returns a new hydration key.
  *
- * @param node - Node to remove
+ * @returns The new hydration key as a string.
  */
-declare function removeNode(node: AnyNode): void;
+declare function getHydrationKey(): string;
 /**
- * Insert child node into parent
- * Handles both component nodes and DOM nodes
+ * Resets the client-side hydration key counter.
  *
- * @param parent - Parent node
- * @param child - Child node to insert
- * @param before - Reference node for insertion position
+ * @returns {void}
  */
-declare function insertNode(parent: Node, child: AnyNode, before?: AnyNode): void;
+declare function resetHydrationKey(): void;
 /**
- * Replace child node with a new node
- * Handles both component nodes and DOM nodes
+ * Returns whether the runtime is currently in the hydration first-pass.
  *
- * @param parent - Parent node
- * @param newNode - New node to insert
- * @param oldNode - Old node to be replaced
+ * @returns True while hydrating, false otherwise.
  */
-declare function replaceNode(parent: Node, newNode: AnyNode, oldNode: AnyNode): void;
+declare function isHydrating(): boolean;
+/** Pop the next call-site anchor comment, or `null` if exhausted. */
+declare function consumeTeleportAnchor(): Comment | null;
+/** Pop the next teleport block from `target`, returning start/end markers and inner nodes. */
+declare function consumeTeleportBlock(target: Element): {
+    start: Comment;
+    end: Comment;
+    nodes: Node[];
+} | null;
 /**
- * Get the first DOM node from a node or component
+ * Begins hydration.
  *
- * @param node - Node or component
- * @returns The first DOM node or undefined
- */
-declare function getFirstDOMNode(node: AnyNode): Node | undefined;
-
-/**
- * Node normalization and comparison utilities
+ * @param root - The root element to hydrate.
  */
-
+declare function beginHydration(root: Element): void;
 /**
- * Normalize node for reconciliation
- * Converts primitives to text nodes
+ * Ends hydration.
  *
- * @param node - Node to normalize
- * @returns Normalized DOM node
+ * @returns {void}
  */
-declare function normalizeNode(node: unknown): Node;
+declare function endHydration(): void;
 /**
- * Check if two nodes are the same (for reconciliation)
- * Combines key check and type check
+ * Returns a factory function that, when called at component render time:
+ * - During hydration: increments the key, looks up the pre-built registry,
+ *   and returns the ACTUAL SSR DOM node (no cloneNode).
+ * - During CSR: clones the parsed template as usual.
  *
- * @param a - First node
- * @param b - Second node
- * @returns true if nodes are considered the same
+ * @param html - The HTML template string.
+ * @returns A factory function that returns a DOM element.
  */
-declare function isSameNode(a: AnyNode, b: AnyNode): boolean;
+declare function getRenderedElement(html: string): () => Element;
 /**
- * Shallow compare two objects or arrays
- * Performs strict equality check on top-level properties
+ * Patches class while considering hydration state.
  *
- * @param a - First value to compare
- * @param b - Second value to compare
- * @returns true if values are shallowly equal
- */
-declare function shallowCompare(a: unknown, b: unknown): boolean;
-
-/**
- * Get rendered element by hydration key or create from template
- * @param {string} temp - the template string
- * @returns {Function} a function that returns the element
+ * @param el - The element to patch.
+ * @param prev - Previous class value.
+ * @param next - Next class value.
+ * @param isSVG - Whether the element is an SVG element.
  */
-declare function getRenderedElement(temp: string): () => Node | null;
+declare function patchClassHydrate(el: Element, prev: unknown, next: unknown, isSVG?: boolean): void;
 /**
- * Maps server-side rendered nodes during hydration
- * @param {HTMLElement} templateEl - The root template element
- * @param {number[]} idx - Array of indices to map
- * @returns {Node[]} Array of mapped nodes
+ * Patches attribute while considering hydration state.
+ *
+ * @param el - The element to patch.
+ * @param key - The attribute key.
+ * @param prev - Previous attribute value.
+ * @param next - Next attribute value.
  */
-declare function mapSSRNodes(templateEl: HTMLElement, idx: number[]): Node[];
+declare function patchAttrHydrate(el: Element, key: string, prev: unknown, next: unknown): void;
 /**
- * Hydrate a server-rendered component
- * @param {ComponentFn} component - Component function to hydrate
- * @param {HTMLElement | string} container - Container element or selector
- * @returns {any} Component instance or undefined if hydration fails
+ * Patches style while considering hydration state.
+ *
+ * @param el - The element to patch.
+ * @param prev - Previous style value.
+ * @param next - Next style value.
  */
-declare function hydrate(component: ComponentFn, container: HTMLElement | string): any;
+declare function patchStyleHydrate(el: HTMLElement, prev: unknown, next?: unknown): void;
 
 /**
- * Start hydration mode
- * Called when beginning client-side hydration of server-rendered content
- */
-declare function startHydration(): void;
-/**
- * End hydration mode
- * Called when hydration is complete
- */
-declare function endHydration(): void;
-/**
- * Check if hydration is currently active
- * @returns true if hydration is in progress
- */
-declare function isHydrating(): boolean;
-/**
- * Get the hydration key
- * @returns the hydration key string
+ * Applies a minimal class update to an element.
+ *
+ * Class values are normalized into a string first, then written through
+ * `className` or `setAttribute('class')` depending on the element type.
+ * Hydration stays silent and reuses the server-rendered result by default.
+ *
+ * @param el - The element to patch.
+ * @param prev - Previous class value.
+ * @param next - Next class value.
+ * @param isSVG - Whether the element is an SVG element.
+ * @returns {void}
  */
-declare function getHydrationKey(): string;
+declare function patchClass(el: Element, prev: unknown, next: unknown, isSVG?: boolean): void;
 /**
- * Reset the hydration key counter
+ * Normalizes supported class inputs into a single string.
  */
-declare function resetHydrationKey(): void;
+declare const normalizeClass: typeof normalizeClassName;
 
 /**
- * Patches the class attribute of an element
- * Supports silent hydration (skips DOM updates during hydration phase)
+ * Applies a minimal style update to an element.
  *
- * @param el - The element to patch classes on
- * @param prev - Previous class value for diffing
- * @param next - New class value to apply
- * @param isSVG - Whether the element is an SVG element
- * @public
+ * Supports both string-based and object-based styles, while staying silent
+ * during hydration so the server-rendered DOM can be reused.
+ *
+ * @param el - The element to patch.
+ * @param prev - Previous style value.
+ * @param next - Next style value.
+ * @returns {void}
  */
-declare function patchClass(el: Element, prev: unknown, next: unknown, isSVG?: boolean): void;
+declare function patchStyle(el: HTMLElement, prev: unknown, next?: unknown): void;
 /**
- * Normalizes different class value formats into a single string
- * Re-exports normalizeClassName from shared as normalizeClass for backward compatibility
+ * Sets a single style property.
+ *
+ * Centralizes array-value expansion, CSS variable writes, vendor-prefix
+ * resolution, and `!important` handling in one place.
  *
- * @param value - The class value to normalize
- * @returns A normalized class string
- * @public
+ * @param style - Target style object.
+ * @param name - Style property name.
+ * @param val - Style value.
+ * @private
  */
-declare function normalizeClass(value: unknown): string;
+declare function setStyle(style: CSSStyleDeclaration, name: string, val: string | string[]): void;
 
 /**
- * Patches the style of an element, optimized for different style formats
- * Supports silent hydration (skips DOM updates during hydration phase)
+ * Supported value types for the attribute patch layer.
  *
- * @param el - The element to patch styles on
- * @public
+ * In addition to primitive values, spread objects are also accepted, so the
+ * type keeps `Record<string, unknown>`.
  */
-declare function patchStyle(el: HTMLElement, prev: unknown, next: unknown): void;
+type AttrValue = string | boolean | number | null | undefined | Record<string, unknown>;
 /**
- * Sets an individual style property with various optimizations
+ * Applies a minimal attribute update to an element.
  *
- * @param style - The style object to modify
- * @param name - The style property name
- * @param val - The style property value
- * @private
+ * This is the most general-purpose attribute updater in the template runtime.
+ * It is responsible for:
+ * - skipping internal reserved fields;
+ * - expanding spread attribute objects;
+ * - handling boolean attributes and SVG / xlink / xmlns namespaces;
+ * - applying basic dangerous-URL protection;
+ * - refusing raw HTML sinks such as `innerHTML` / `srcdoc`;
+ * - staying silent during hydration to avoid overwriting SSR DOM.
+ *
+ * @param el - The element to patch.
+ * @param key - The attribute key.
+ * @param prev - Previous attribute value.
+ * @param next - Next attribute value.
  */
-declare function setStyle(style: CSSStyleDeclaration, name: string, val: string | string[]): void;
-
-type AttrValue = string | boolean | number | null | undefined | Record<string, unknown>;
 declare function patchAttr(el: Element, key: string, prev: AttrValue, next: AttrValue): void;
 
 /**
- * Extended event options with delegation support
- * @public
+ * Extended listener options with optional event delegation support.
  */
 interface EventOptions extends AddEventListenerOptions {
     /**
-     * CSS selector for event delegation
-     * When provided, the event will only trigger if the target matches this selector
+     * Selector used for event delegation.
+     *
+     * When provided, the handler only runs if the event target matches the selector.
      */
     delegate?: string;
 }
 /**
- * Event handler cleanup function
- * @public
+ * Cleanup function signature for event listeners.
  */
 type EventCleanup = () => void;
 /**
- * Adds an event listener to an element with optional delegation
+ * Adds an event listener to an element with optional simple delegation.
+ *
+ * Without `delegate`, this is a thin wrapper around native `addEventListener()`.
+ * When `delegate` is provided, the runtime first checks the selector match before
+ * dispatching the real handler to the caller.
  *
- * @param el - The element to attach the event to
- * @param event - The event name (e.g., 'click', 'input')
- * @param handler - The event handler function
- * @param options - Additional event options including delegation
- * @returns A cleanup function to remove the event listener
- * @public
+ * @param el - The element to add the listener to.
+ * @param event - The name of the event to listen for.
+ * @param handler - The event handler function.
+ * @param options - Optional event listener options.
+ * @returns A cleanup function that removes the listener.
  */
 declare function addEvent(el: Element, event: string, handler: EventListener, options?: EventOptions): EventCleanup;
 
@@ -439,15 +441,15 @@ interface FragmentProps extends ComponentProps {
     children?: AnyNode | AnyNode[];
 }
 /**
- * Fragment component - renders multiple children without wrapper elements (Client-side only)
+ * Fragment component - renders multiple children without wrapper elements (Client-side only).
  *
  * **Client-side behavior:**
- * - Returns children directly for rendering
- * - Hydration system matches children using hydration keys
- * - The template system handles array children automatically
+ * - Returns children directly for rendering.
+ * - Hydration system matches children using hydration keys.
+ * - The template system handles array children automatically.
  *
- * @param props - Component props with children
- * @returns Children directly without wrapper
+ * @param props - Component props with children.
+ * @returns {AnyNode} Children directly without wrapper.
  *
  * @example
  * ```tsx
@@ -473,51 +475,66 @@ interface FragmentProps extends ComponentProps {
 declare function Fragment(props?: FragmentProps): AnyNode;
 declare namespace Fragment { }
 /**
- * Check if a node is a Fragment component
- * @param node - Node to check
- * @returns true if node is a Fragment
+ * Check if a node is a Fragment component.
+ *
+ * @param node - Node to check.
+ * @returns {boolean} True if node is a Fragment.
  */
 declare function isFragment(node: unknown): boolean;
 
 interface PortalProps {
+    /** Children to render at the target location. */
     children?: AnyNode | AnyNode[];
-    target: string | HTMLElement;
-    key?: string;
+    /**
+     * Mount target — CSS selector string, `Element`, or reactive getter.
+     * When the getter result changes, the Portal re-mounts at the new target.
+     */
+    target?: string | Element | (() => string | Element | null | undefined);
+    /**
+     * When truthy, children render inline at the call site instead of being teleported.
+     * May be a static value or a reactive getter.
+     */
+    disabled?: boolean | (() => boolean);
 }
 /**
- * Portal component - renders children into a different DOM node
+ * Portal — teleports children into a different DOM node.
+ *
+ * - `disabled=true` renders children inline at the call site.
+ * - Otherwise children are teleported into `target`.
+ * - Both `target` and `disabled` may be reactive; changes trigger re-mount.
  *
- * @param props - Component props with children and target
- * @returns Comment node as placeholder in parent tree
+ * @returns A placeholder comment node that marks the call site.
  *
  * @example
  * ```tsx
- * <Portal target="#modal-root">
+ * <Portal target="#modal-root" disabled={isMobile}>
  *   <div>Modal content</div>
  * </Portal>
+ * ```
  */
-declare function Portal(props: PortalProps): Comment | string;
+declare function Portal(props: PortalProps): Comment;
 declare namespace Portal { }
 /**
- * Check if a node is a Portal component
- * @param node - Node to check
- * @returns true if node is a Portal
+ * Check if a node is a Portal component.
+ *
+ * @param node - Node to check.
+ * @returns True if node is a Portal.
  */
 declare function isPortal(node: unknown): boolean;
 
 interface SuspenseProps {
     /** The content to render. Can be a Promise for async loading. */
-    children?: AnyNode | AnyNode[] | Promise<AnyNode | AnyNode[]>;
+    children?: Node | Node[] | Promise<Node | Node[]>;
     /** Fallback content to display while children is loading (Promise pending). */
-    fallback?: AnyNode;
+    fallback?: Node;
     /** Optional key for reconciliation. */
     key?: string;
 }
 /**
- * Suspense component - handles async content with a fallback UI
+ * Suspense component - handles async content with a fallback UI.
  *
- * @param props - Component props with children, fallback, and optional key
- * @returns Placeholder node or fallback content
+ * @param props - Component props with children, fallback, and optional key.
+ * @returns {AnyNode} Placeholder node or fallback content.
  *
  * @example
  * ```tsx
@@ -526,12 +543,13 @@ interface SuspenseProps {
  * </Suspense>
  * ```
  */
-declare function Suspense(props: SuspenseProps): AnyNode;
+declare function Suspense(props: SuspenseProps): Node;
 declare namespace Suspense { }
 /**
- * Check if a node is a Suspense component
- * @param node - Node to check
- * @returns true if node is a Suspense
+ * Check if a node is a Suspense component.
+ *
+ * @param node - Node to check.
+ * @returns {boolean} True if node is a Suspense.
  */
 declare function isSuspense(node: unknown): boolean;
 
@@ -550,38 +568,102 @@ interface ResourceOptions<T> {
     initialValue?: T;
 }
 /**
- * Create a resource for async data fetching
- * Inspired by SolidJS createResource
+ * Create a resource for async data fetching.
+ * Inspired by SolidJS createResource.
+ *
+ * @param fetcher - Function that returns a Promise with the data.
+ * @param options - Optional configuration.
+ * @returns {[Resource<T>, ResourceActions<T>]} Tuple of [resource, actions].
+ */
+declare function createResource<T>(fetcher: () => Promise<T>, options?: ResourceOptions<T>): [Resource<T>, ResourceActions<T>];
+
+interface AsyncComponentOptions {
+    /**
+     * Component to render while the async component is loading.
+     * Only shown after `delay` ms has elapsed (prevents flash of loading state).
+     */
+    loading?: ComponentFn;
+    /**
+     * Component to render when the async component fails to load.
+     * Receives `{ error, retry }` as props.
+     */
+    error?: ComponentFn<{
+        error: Error;
+        retry: () => void;
+    }>;
+    /**
+     * Delay in ms before showing the `loading` component (default: 200).
+     */
+    delay?: number;
+    /**
+     * Timeout in ms. If loading exceeds this, the error component is shown.
+     */
+    timeout?: number;
+    /**
+     * SSR rendering strategy (default: `'blocking'`).
+     *
+     * - `'blocking'`    — Pre-calls the loader at definition time. If the module
+     *   resolves before the component body runs (e.g. pre-loaded via
+     *   `renderToStringAsync`), the real component is inlined in the HTML.
+     * - `'client-only'` — Renders `null` on the server; loads only in browser.
+     */
+    ssr?: 'blocking' | 'client-only';
+    /**
+     * Called when loading fails. Useful for logging or error tracking.
+     */
+    onError?: (error: Error, retry: () => void) => void;
+}
+type LoaderResult<P> = {
+    default: ComponentFn<P>;
+} | ComponentFn<P>;
+/**
+ * Define an async (lazy-loaded) component.
  *
- * @param fetcher - Function that returns a Promise with the data
- * @param options - Optional configuration
- * @returns Tuple of [resource, actions]
+ * Compatible with client, SSR, and SSG. Integrates with `<Suspense>` via
+ * `SuspenseContext` when rendered inside a Suspense boundary.
  *
- * @example
- * ```typescript
- * const [data, { refetch, mutate }] = createResource(
- *   () => fetch('/api/user').then(r => r.json()),
- *   { initialValue: null }
- * );
  *
- * // Access data
- * console.log(data());
- * console.log(data.loading.value);
- * console.log(data.state.value);
+ * @param loader - The async loader function.
+ * @param options - Configuration options.
+ * @returns {ComponentFn<P>} The async component wrapper function.
  *
- * // Refetch data
- * await refetch();
+ * @example
+ * ```tsx
+ * // Simple
+ * const Chart = defineAsyncComponent(() => import('./Chart'));
+ *
+ * // With options
+ * const Chart = defineAsyncComponent(
+ *   () => import('./Chart'),
+ *   {
+ *     loading: () => <Spinner />,
+ *     error: ({ error, retry }) => (
+ *       <div>
+ *         <p>{error.message}</p>
+ *         <button onClick={retry}>Retry</button>
+ *       </div>
+ *     ),
+ *     delay: 200,
+ *     timeout: 10_000,
+ *   }
+ * );
  *
- * // Update data directly
- * mutate({ name: 'John' });
+ * // Works standalone or inside Suspense
+ * function App() {
+ *   return (
+ *     <Suspense fallback={<div>Loading…</div>}>
+ *       <Chart data={data} />
+ *     </Suspense>
+ *   );
+ * }
  * ```
  */
-declare function createResource<T>(fetcher: () => Promise<T>, options?: ResourceOptions<T>): [Resource<T>, ResourceActions<T>];
+declare function defineAsyncComponent<P extends ComponentProps = ComponentProps>(loader: () => Promise<LoaderResult<P>>, options?: AsyncComponentOptions): ComponentFn<P>;
 
 interface ForProps<T> {
     each: T[] | Signal<T[]> | (() => T[]);
     children: (item: T, index: number) => AnyNode;
-    keyFn?: (item: T) => unknown;
+    key?: (item: T) => unknown;
     fallback?: () => AnyNode;
 }
 /**
@@ -593,4 +675,4 @@ interface ForProps<T> {
 declare function For<T>(props: ForProps<T>): Node;
 declare namespace For { }
 
-export { Component, type ComponentFn, type ComponentProps, For, type ForProps, Fragment, type FragmentProps, type InjectionKey, Portal, type PortalProps, type Scope, Suspense, type SuspenseProps, addEvent, addEventListener, bindElement, createApp, createComponent, createResource, createScope, delegateEvents, disposeScope, endHydration, getActiveScope, getFirstDOMNode, getHydrationKey, getRenderedElement, hydrate, inject, insert, insertNode, isComponent, isFragment, isHydrating, isPortal, isSameNode, isSuspense, mapNodes, mapSSRNodes, normalizeClass, normalizeNode, omitProps, onCleanup, onDestroy, onMount, onUpdate, patchAttr, patchClass, patchStyle, provide, removeNode, replaceNode, resetHydrationKey, runWithScope, setActiveScope, setStyle, shallowCompare, startHydration, template };
+export { type AsyncComponentOptions, Component, type ComponentFn, type ComponentProps, For, Fragment, Portal, Suspense, addEvent, addEventListener, beginHydration, bindElement, child, clearDelegatedEvents, consumeTeleportAnchor, consumeTeleportBlock, createApp, createComponent, createResource, defineAsyncComponent, delegateEvents, endHydration, getHydrationKey, getRenderedElement, hydrate, insert, isComponent, isFragment, isHydrating, isPortal, isSuspense, next, normalizeClass, nthChild, omitProps, onDestroy, onMount, onUpdate, patchAttr, patchAttrHydrate, patchClass, patchClassHydrate, patchStyle, patchStyleHydrate, resetHydrationKey, setStyle, template };