@vertz/ui 0.2.0 → 0.2.1

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-/** A single child value: DOM node, string, number, null, undefined, or nested array. */
-type ChildValue = Node | string | number | null | undefined | ChildValue[];
+/** A single child value: DOM node, string, number, null, undefined, thunk, or nested array. */
+type ChildValue = Node | string | number | null | undefined | ChildValue[] | (() => ChildValue);
 /** A function that returns children (slot accessor). */
 type ChildrenAccessor = () => ChildValue;
 /**
@@ -7,18 +7,88 @@ type ChildrenAccessor = () => ChildValue;
 * Strings and numbers are converted to Text nodes.
 * Null and undefined are filtered out.
 * Arrays are flattened recursively.
+* Thunks (functions) are called and their results re-resolved.
 */
-declare function resolveChildren(value: ChildValue): Node[];
+declare function resolveChildren(value: ChildValue, _depth?: number): Node[];
 /**
 * Create a children resolver from a children accessor.
 * Returns a function that, when called, resolves the children
 * to a flat array of DOM nodes.
 */
 declare function children(accessor: ChildrenAccessor): () => Node[];
+/**
+* A reactive signal that holds a value and notifies subscribers on change.
+*/
+interface Signal<T> {
+	/** Get the current value and subscribe to changes (when inside a tracking context). */
+	get value(): T;
+	/** Set the current value and notify subscribers if changed. */
+	set value(newValue: T);
+	/** Read the current value without subscribing (no tracking). */
+	peek(): T;
+	/** Manually notify all subscribers (useful after mutating the value in place). */
+	notify(): void;
+}
+/**
+* A read-only reactive value derived from other signals.
+*/
+interface ReadonlySignal<T> {
+	/** Get the current value and subscribe to changes. */
+	readonly value: T;
+	/** Read the current value without subscribing. */
+	peek(): T;
+}
+/**
+* Unwraps a ReadonlySignal to its value type.
+* Used by signal APIs (like query()) to expose plain values in TypeScript
+* while the compiler auto-unwraps them at runtime.
+*
+* @example
+* type UnwrappedData = Unwrapped<ReadonlySignal<Task | undefined>>; // → Task | undefined
+*/
+type Unwrapped<T> = T extends ReadonlySignal<infer U> ? U : T;
+/**
+* Unwraps all signal properties of an object type.
+* Properties that are signals become their inner value type.
+* Non-signal properties and primitive types pass through unchanged.
+*
+* Used by `useContext` to present context values without the Signal wrapper.
+*
+* @example
+* type Settings = { theme: Signal<string>; setTheme: (t: string) => void };
+* type Unwrapped = UnwrapSignals<Settings>; // { theme: string; setTheme: (t: string) => void }
+*/
+type UnwrapSignals<T> = T extends object ? { [K in keyof T] : Unwrapped<T[K]> } : T;
+/**
+* A computed signal — lazily evaluated, cached, and automatically re-computed
+* when dependencies change.
+*/
+interface Computed<T> extends ReadonlySignal<T> {
+	/** Get the current value, re-computing if dirty. Subscribes in tracking context. */
+	readonly value: T;
+	/** Read the current value without subscribing. */
+	peek(): T;
+}
+/** Dispose function returned by effect(). */
+type DisposeFn = () => void;
+/**
+* Props for the JSX pattern of Context.Provider.
+*
+* `children` accepts both raw values (what TypeScript sees in JSX) and
+* thunks (what the compiler produces). At compile time the compiler wraps
+* JSX children in `() => ...`, but TypeScript checks the pre-compilation
+* source where children are plain elements.
+*/
+interface ProviderJsxProps<T> {
+	value: T;
+	children: (() => unknown) | unknown;
+}
 /** A context object created by `createContext`. */
 interface Context<T> {
-	/** Provide a value to all `useContext` calls within the scope. */
-	Provider: (value: T, fn: () => void) => void;
+	/** Provide a value via callback pattern. */
+	Provider(value: T, fn: () => void): void;
+	/** Provide a value via JSX pattern (single-arg object with children thunk). */
+	Provider(props: ProviderJsxProps<T>): HTMLElement;
 	/** @internal — current value stack */
 	_stack: T[];
 	/** @internal — default value */
@@ -27,15 +97,20 @@ interface Context<T> {
 /**
 * Create a context with an optional default value.
 * Returns an object with a `Provider` function.
+*
+* The optional `__stableId` parameter is injected by the compiler for HMR
+* support. When provided, the context object is cached in a global registry
+* so that bundle re-evaluation returns the same object — preserving identity
+* for ContextScope Map lookups. Users never pass this parameter directly.
 */
-declare function createContext<T>(defaultValue?: T): Context<T>;
+declare function createContext<T>(defaultValue?: T, __stableId?: string): Context<T>;
 /**
 * Retrieve the current value from the nearest Provider.
 * Checks the synchronous call stack first, then falls back to
 * the captured context scope (for async callbacks like watch/effect).
 * Returns the default value if no Provider is active.
 */
-declare function useContext<T>(ctx: Context<T>): T | undefined;
+declare function useContext<T>(ctx: Context<T>): UnwrapSignals<T> | undefined;
 /** Props for the ErrorBoundary component. */
 interface ErrorBoundaryProps {
 	/** Function that returns the children to render. */
@@ -57,16 +132,28 @@ interface ErrorBoundaryProps {
 declare function ErrorBoundary(props: ErrorBoundaryProps): Node;
 /**
 * Runs callback once on mount. Never re-executes.
-* Supports `onCleanup` inside for teardown on unmount.
+* Return a function to register cleanup that runs on unmount.
+*
+* ```tsx
+* onMount(() => {
+*   const id = setInterval(() => seconds++, 1000);
+*   return () => clearInterval(id);
+* });
+* ```
 */
-declare function onMount(callback: () => void): void;
+declare function onMount2(callback: () => (() => void) | void): void;
+interface PresenceProps {
+	when: boolean;
+	children: () => HTMLElement;
+}
 /**
-* Watches a dependency accessor and runs callback whenever it changes.
-* Always takes TWO arguments: a dependency accessor and a callback.
-* Runs callback immediately with current value.
-* Before each re-run, any `onCleanup` from previous run executes first.
+* Presence component for mount/unmount animations.
+* Defers unmounting until CSS exit animations complete.
+*
+* Props are accessed as getters (not destructured) so the compiler-generated
+* reactive getters are tracked by domEffect.
 */
-declare function watch<T>(dep: () => T, callback: (value: T) => void): void;
+declare function Presence(props: PresenceProps): Node;
 /** A ref container for DOM element access. */
 interface Ref<T> {
 	current: T | undefined;
@@ -96,17 +183,51 @@ interface SuspenseProps {
 * globally via queueMicrotask to avoid silent swallowing.
 */
 declare function Suspense(props: SuspenseProps): Node;
+declare const ANIMATION_DURATION: string;
+declare const ANIMATION_EASING: string;
+declare const fadeIn: string;
+declare const fadeOut: string;
+declare const zoomIn: string;
+declare const zoomOut: string;
+declare const slideInFromTop: string;
+declare const slideInFromBottom: string;
+declare const slideOutToTop: string;
+declare const slideOutToBottom: string;
+declare const slideInFromLeft: string;
+declare const slideInFromRight: string;
+declare const slideOutToLeft: string;
+declare const slideOutToRight: string;
+declare const accordionDown: string;
+declare const accordionUp: string;
+/** A raw CSS declaration: { property, value } for styles that can't be expressed as shorthands. */
+interface RawDeclaration {
+	property: string;
+	value: string;
+}
+/** A value within a nested selector array: shorthand string or raw declaration. */
+type StyleValue = string | RawDeclaration;
 /** A style entry in the array: either a shorthand string or an object for nested selectors. */
-type StyleEntry = string | Record<string, string[]>;
+type StyleEntry = string | Record<string, StyleValue[]>;
 /** Input to css(): a record of named style blocks. */
 type CSSInput = Record<string, StyleEntry[]>;
-/** Output of css(): a record of block names to class names, plus extracted CSS. */
-interface CSSOutput {
-	/** Map of block name → generated class name. */
-	classNames: Record<string, string>;
-	/** The extracted CSS string. */
-	css: string;
-}
+/** Output of css(): block names as top-level properties, plus non-enumerable `css`. */
+type CSSOutput<T extends CSSInput = CSSInput> = { readonly [K in keyof T & string] : string } & {
+	readonly css: string;
+};
+/**
+* Inject CSS text into the document head via a <style> tag.
+* Only runs in browser environments. Deduplicates by CSS content.
+*
+* In SSR, document.head is freshly created per request by installDomShim().
+* The module-level dedup Set would incorrectly block injection on request 2+
+* since the Set persists across requests while document.head is replaced.
+* We bypass dedup when __SSR_URL__ is set (SSR context).
+*/
+declare function injectCSS(cssText: string): void;
+/** Reset injected styles tracking. Used in tests. */
+declare function resetInjectedStyles(): void;
+/** Get all CSS strings that have been injected. Used by SSR to collect styles. */
+declare function getInjectedCSS(): string[];
 /**
 * Process a css() call and produce class names + extracted CSS.
 *
@@ -118,9 +239,9 @@ interface CSSOutput {
 *
 * @param input - Named style blocks.
 * @param filePath - Source file path for deterministic hashing.
-* @returns Class names map and extracted CSS.
+* @returns Object with block names as keys (class name strings) and non-enumerable `css` property.
 */
-declare function css(input: CSSInput, filePath?: string): CSSOutput;
+declare function css<T extends CSSInput>(input: T & { [K in keyof T & "css"]? : never }, filePath?: string): CSSOutput<T>;
 /** Input to globalCss(): selector → property-value map. */
 type GlobalCSSInput = Record<string, Record<string, string>>;
 /** Output of globalCss(): extracted CSS string. */
@@ -139,6 +260,54 @@ interface GlobalCSSOutput {
 */
 declare function globalCss(input: GlobalCSSInput): GlobalCSSOutput;
 /**
+* Register a CSS @keyframes animation and return its name.
+* The CSS is injected into the DOM (deduped by injectCSS).
+*/
+declare function keyframes(name: string, frames: Record<string, Record<string, string>>): string;
+/**
+* Tailwind v4 oklch color palettes.
+*
+* All 22 palettes with shades 50-950 in oklch format.
+* Sourced from: https://github.com/tailwindlabs/tailwindcss/blob/main/packages/tailwindcss/theme.css
+*/
+interface ColorPalette {
+	50: string;
+	100: string;
+	200: string;
+	300: string;
+	400: string;
+	500: string;
+	600: string;
+	700: string;
+	800: string;
+	900: string;
+	950: string;
+}
+declare const palettes: Readonly<{
+	slate: ColorPalette;
+	gray: ColorPalette;
+	zinc: ColorPalette;
+	neutral: ColorPalette;
+	stone: ColorPalette;
+	red: ColorPalette;
+	orange: ColorPalette;
+	amber: ColorPalette;
+	yellow: ColorPalette;
+	lime: ColorPalette;
+	green: ColorPalette;
+	emerald: ColorPalette;
+	teal: ColorPalette;
+	cyan: ColorPalette;
+	sky: ColorPalette;
+	blue: ColorPalette;
+	indigo: ColorPalette;
+	violet: ColorPalette;
+	purple: ColorPalette;
+	fuchsia: ColorPalette;
+	pink: ColorPalette;
+	rose: ColorPalette;
+}>;
+/**
 * Convert an array of shorthand strings into a CSS properties object
 * suitable for inline styles.
 *
@@ -192,34 +361,27 @@ declare function defineTheme(input: ThemeInput): Theme;
 * @returns Compiled CSS and token list.
 */
 declare function compileTheme(theme: Theme): CompiledTheme;
-/**
-* ThemeProvider — Sets `data-theme` attribute for contextual token switching.
-*
-* Creates a wrapper div element with the appropriate `data-theme` attribute
-* so that contextual CSS custom properties (generated by compileTheme) resolve
-* to the correct variant values.
-*
-* Usage:
-* ```ts
-* ThemeProvider({ theme: 'dark', children: [myApp] });
-* ```
-*/
 /** A child node: either a DOM Node or a string (text content). */
 type ThemeChild = Node | string;
 /** Props for ThemeProvider. */
 interface ThemeProviderProps {
 	/** The theme variant name (e.g., 'light', 'dark'). Defaults to 'light'. */
 	theme?: string;
-	/** Child elements to render inside the provider. */
-	children: ThemeChild[];
+	/**
+	* Child elements to render inside the provider.
+	*
+	* Accepts a single child (what TypeScript sees in JSX), an array, or a
+	* thunk (what the compiler produces after wrapping JSX children).
+	*/
+	children: ThemeChild | ThemeChild[] | (() => ThemeChild | ThemeChild[]);
 }
 /**
 * Create a wrapper div with `data-theme` attribute for theme switching.
 *
-* @param props - Theme and children.
-* @returns A div element with `data-theme` set and children appended.
+* Uses __element() directly (instead of jsx()) so the hydration cursor
+* walker can claim the existing SSR node during mount().
 */
-declare function ThemeProvider(props: ThemeProviderProps): HTMLDivElement;
+declare function ThemeProvider({ theme, children }: ThemeProviderProps): HTMLElement;
 /** A record of variant names to their possible values (each value maps to style entries). */
 type VariantDefinitions = Record<string, Record<string, StyleEntry[]>>;
 /** Extract the variant props type from a variant definitions object. */
@@ -253,45 +415,116 @@ interface VariantFunction<V extends VariantDefinitions> {
 */
 declare function variants<V extends VariantDefinitions>(config: VariantsConfig<V>): VariantFunction<V>;
 /**
-* A reactive signal that holds a value and notifies subscribers on change.
+* Brand symbol for render nodes.
+* SSR nodes add this to their prototype for fast identification.
+* Browser DOM nodes use the `instanceof Node` fallback in `isRenderNode`.
 */
-interface Signal<T> {
-	/** Get the current value and subscribe to changes (when inside a tracking context). */
-	get value(): T;
-	/** Set the current value and notify subscribers if changed. */
-	set value(newValue: T);
-	/** Read the current value without subscribing (no tracking). */
-	peek(): T;
-	/** Manually notify all subscribers (useful after mutating the value in place). */
-	notify(): void;
+declare const RENDER_NODE_BRAND: unique symbol;
+interface RenderNode {}
+interface RenderElement extends RenderNode {
+	setAttribute(name: string, value: string): void;
+	removeAttribute(name: string): void;
+	getAttribute(name: string): string | null;
+	style: {
+		display: string;
+		[key: string]: any;
+	};
+	classList: {
+		add(cls: string): void;
+		remove(cls: string): void;
+	};
+	addEventListener(event: string, handler: EventListener): void;
+	removeEventListener(event: string, handler: EventListener): void;
+}
+interface RenderText extends RenderNode {
+	data: string;
+}
+interface RenderAdapter {
+	createElement(tag: string): RenderElement;
+	createElementNS(ns: string, tag: string): RenderElement;
+	createTextNode(text: string): RenderText;
+	createComment(text: string): RenderNode;
+	createDocumentFragment(): RenderNode;
+	isNode(value: unknown): value is RenderNode;
 }
 /**
-* A read-only reactive value derived from other signals.
+* Type guard: checks if a value is a RenderNode.
+* Fast path: brand check for SSR nodes.
+* Fallback: instanceof Node for browser DOM nodes.
 */
-interface ReadonlySignal<T> {
-	/** Get the current value and subscribe to changes. */
-	readonly value: T;
-	/** Read the current value without subscribing. */
-	peek(): T;
-}
+declare function isRenderNode(value: unknown): value is RenderNode;
 /**
-* A computed signal — lazily evaluated, cached, and automatically re-computed
-* when dependencies change.
+* Get the current render adapter.
+* Auto-detects DOMAdapter if document exists and no adapter has been set.
 */
-interface Computed<T> extends ReadonlySignal<T> {
-	/** Get the current value, re-computing if dirty. Subscribes in tracking context. */
-	readonly value: T;
-	/** Read the current value without subscribing. */
-	peek(): T;
+declare function getAdapter(): RenderAdapter;
+/**
+* Set the current render adapter.
+* Pass null to reset to auto-detect.
+*/
+declare function setAdapter(adapter: RenderAdapter | null): void;
+/**
+* Create a DOM adapter that delegates to real browser DOM APIs.
+* Zero overhead — no branding, no wrapping.
+* Browser `Node` instances pass `isRenderNode()` via the `instanceof Node` fallback.
+*/
+declare function createDOMAdapter(): RenderAdapter;
+/**
+* Create a DOM element with optional static properties.
+*
+* This is a compiler output target — the compiler generates calls
+* to __element for each JSX element.
+*/
+declare function __element<K extends keyof HTMLElementTagNameMap>(tag: K, props?: Record<string, string>): HTMLElementTagNameMap[K];
+declare function __element(tag: string, props?: Record<string, string>): Element;
+/**
+* Append a child to a parent node.
+* During hydration, this is a no-op — the child is already in the DOM.
+* During CSR, delegates to appendChild.
+*
+* Compiler output target — replaces direct `parent.appendChild(child)`.
+*/
+declare function __append(parent: Node, child: Node): void;
+/**
+* Create a static text node.
+* During hydration, claims an existing text node from the SSR output.
+* During CSR, creates a new text node.
+*
+* Compiler output target — replaces `document.createTextNode(str)`.
+*/
+declare function __staticText(text: string): Text;
+/**
+* Push the hydration cursor into an element's children.
+* Compiler output target — emitted around child construction.
+*/
+declare function __enterChildren(el: Element): void;
+/**
+* Pop the hydration cursor back to the parent scope.
+* Compiler output target — emitted after all children are appended.
+*/
+declare function __exitChildren(): void;
+interface FieldState<T = unknown> {
+	error: Signal<string | undefined>;
+	dirty: Signal<boolean>;
+	touched: Signal<boolean>;
+	value: Signal<T>;
+	setValue: (value: T) => void;
+	reset: () => void;
 }
-/** Dispose function returned by effect(). */
-type DisposeFn = () => void;
+declare function createFieldState<T>(_name: string, initialValue?: T): FieldState<T>;
+import { Result } from "@vertz/fetch";
 /**
 * Minimal schema interface compatible with @vertz/schema.
-* Any object with a `parse(data: unknown): T` method satisfies this.
+* Any object with a `parse(data: unknown): Result` method satisfies this.
 */
 interface FormSchema<T> {
-	parse(data: unknown): T;
+	parse(data: unknown): {
+		ok: true;
+		data: T;
+	} | {
+		ok: false;
+		error: unknown;
+	};
 }
 /** Result of a validation attempt. */
 type ValidationResult<T> = {
@@ -319,56 +552,87 @@ interface SdkMethod<
 	TBody,
 	TResult
 > {
-	(body: TBody): Promise<TResult>;
+	(body: TBody): PromiseLike<Result<TResult, Error>>;
 	url: string;
 	method: string;
+	meta?: {
+		bodySchema?: FormSchema<TBody>;
+	};
 }
-/** Options for creating a form instance. */
-interface FormOptions<TBody> {
-	/** Explicit schema for client-side validation before submission. */
-	schema: FormSchema<TBody>;
+/**
+* An SDK method with embedded schema metadata.
+* Generated by `@vertz/codegen` — carries `.meta.bodySchema` for auto-validation.
+*/
+interface SdkMethodWithMeta<
+	TBody,
+	TResult
+> extends SdkMethod<TBody, TResult> {
+	meta: {
+		bodySchema: FormSchema<TBody>;
+	};
 }
-/** Callbacks for form submission. Both are optional per spec. */
-interface SubmitCallbacks<TResult> {
-	onSuccess?: (result: TResult) => void;
-	onError?: (errors: Record<string, string>) => void;
+/** Reserved property names that cannot be used as field names on FormInstance. */
+type ReservedFormNames = "submitting" | "dirty" | "valid" | "action" | "method" | "onSubmit" | "reset" | "setFieldError" | "submit" | "__bindElement";
+/** Mapped type providing FieldState for each field in TBody. */
+type FieldAccessors<TBody> = { [K in keyof TBody] : FieldState<TBody[K]> };
+/** Base properties available on every form instance. */
+interface FormBaseProperties<TBody> {
+	action: string;
+	method: string;
+	onSubmit: (e: Event) => Promise<void>;
+	reset: () => void;
+	setFieldError: (field: keyof TBody & string, message: string) => void;
+	submit: (formData?: FormData) => Promise<void>;
+	submitting: Signal<boolean>;
+	dirty: ReadonlySignal<boolean>;
+	valid: ReadonlySignal<boolean>;
+	__bindElement: (el: HTMLFormElement) => void;
 }
-/** A form instance bound to an SDK method. */
-interface FormInstance<
+/**
+* A form instance bound to an SDK method.
+* Combines base properties with per-field reactive state via Proxy.
+* If TBody has any key that conflicts with ReservedFormNames, it produces a type error.
+* TResult is used by form() overloads for return type inference.
+*/
+type FormInstance<
+	TBody,
+	_TResult
+> = keyof TBody & ReservedFormNames extends never ? FormBaseProperties<TBody> & FieldAccessors<TBody> : {
+	__error: `Field name conflicts with reserved form property: ${keyof TBody & ReservedFormNames & string}`;
+};
+/** Options for creating a form instance. */
+interface FormOptions<
 	TBody,
 	TResult
 > {
-	/** Returns `{ action, method }` for progressive enhancement in HTML forms. */
-	attrs(): {
-		action: string;
-		method: string;
-	};
-	/** Reactive signal indicating whether a submission is in progress. */
-	submitting: Signal<boolean>;
-	/**
-	* Returns an event handler that extracts FormData, validates, and submits.
-	* Assignable to onSubmit: `onSubmit={userForm.handleSubmit({ onSuccess })}`.
-	*
-	* Can also be called directly with FormData for non-DOM usage:
-	* `userForm.handleSubmit({ onSuccess })(formData)`.
-	*/
-	handleSubmit(callbacks?: SubmitCallbacks<TResult>): (formDataOrEvent: FormData | Event) => Promise<void>;
-	/** Returns the error message for a field reactively, or undefined if no error. Type-safe field names. */
-	error(field: keyof TBody & string): string | undefined;
+	/** Explicit schema for client-side validation before submission. */
+	schema?: FormSchema<TBody>;
+	/** Initial values for form fields. */
+	initial?: Partial<TBody> | (() => Partial<TBody>);
+	/** Callback invoked after a successful submission. */
+	onSuccess?: (result: TResult) => void;
+	/** Callback invoked when validation or submission fails. */
+	onError?: (errors: Record<string, string>) => void;
+	/** When true, reset the form after a successful submission. */
+	resetOnSuccess?: boolean;
 }
 /**
-* Create a form instance bound to an SDK method with schema validation.
+* Create a form instance bound to an SDK method.
 *
-* The form provides:
-* - `attrs()` for progressive enhancement (returns action/method from SDK metadata)
-* - `handleSubmit()` returns an event handler for FormData extraction, validation, and SDK submission
-* - `error()` for reactive field-level error access
-* - `submitting` signal for loading state
+* The form provides direct properties for progressive enhancement (action, method, onSubmit),
+* per-field reactive state via Proxy, and submission handling with validation.
+*
+* When the SDK method has `.meta.bodySchema` (generated by `@vertz/codegen`),
+* the schema option is optional. When the SDK method lacks `.meta`, the schema option is required.
 */
 declare function form<
 	TBody,
 	TResult
->(sdkMethod: SdkMethod<TBody, TResult>, options: FormOptions<TBody>): FormInstance<TBody, TResult>;
+>(sdkMethod: SdkMethodWithMeta<TBody, TResult>, options?: FormOptions<TBody, TResult>): FormInstance<TBody, TResult>;
+declare function form<
+	TBody,
+	TResult
+>(sdkMethod: SdkMethod<TBody, TResult>, options: Required<Pick<FormOptions<TBody, TResult>, "schema">> & FormOptions<TBody, TResult>): FormInstance<TBody, TResult>;
 /** Options for formDataToObject conversion. */
 interface FormDataOptions {
 	/** When true, coerces numeric strings to numbers and "true"/"false" to booleans. */
@@ -395,7 +659,8 @@ type ComponentRegistry = Record<string, ComponentLoader>;
 * Client entry point for atomic per-component hydration.
 *
 * Scans the DOM for elements with `data-v-id` markers placed by the SSR pass,
-* deserializes their props, and applies the appropriate hydration strategy.
+* deserializes their props, and applies automatic hydration based on viewport
+* proximity (IntersectionObserver with 200px rootMargin).
 *
 * Components without `data-v-id` markers are static and ship zero JS.
 *
@@ -405,30 +670,40 @@ type ComponentRegistry = Record<string, ComponentLoader>;
 */
 declare function hydrate(registry: ComponentRegistry): void;
 /**
-* Hydration strategies determine WHEN a component gets hydrated.
-*
-* - eager: immediately on page load
-* - lazy (default): when element becomes visible (IntersectionObserver, 200px rootMargin)
-* - interaction: on first user event (click, focus, pointerenter)
-* - idle: during browser idle time (requestIdleCallback, falls back to setTimeout)
-* - media(query): when a CSS media query matches
-* - visible: when element enters the viewport (IntersectionObserver, no rootMargin)
+* Options for mounting an app to the DOM.
 */
-/** Eager -- hydrate immediately on page load. */
-declare function eagerStrategy(el: Element, hydrateFn: () => void): void;
-/** Lazy (default) -- hydrate when element becomes visible via IntersectionObserver with 200px rootMargin. */
-declare function lazyStrategy(el: Element, hydrateFn: () => void): void;
-/** Interaction -- hydrate on first user event (click, focus, pointerenter). */
-declare function interactionStrategy(el: Element, hydrateFn: () => void): void;
-/** Idle -- hydrate during browser idle time via requestIdleCallback. Falls back to setTimeout(fn, 0). */
-declare function idleStrategy(el: Element, hydrateFn: () => void): void;
+interface MountOptions {
+	/** Theme definition for CSS vars */
+	theme?: Theme;
+	/** Global CSS strings to inject */
+	styles?: string[];
+	/** Callback after mount completes */
+	onMount?: (root: HTMLElement) => void;
+}
 /**
-* Media -- hydrate when a CSS media query matches.
-* Returns a strategy function bound to the given query string.
+* Handle returned from mount() for controlling the mounted app.
 */
-declare function mediaStrategy(query: string): (el: Element, hydrateFn: () => void) => void;
-/** Visible -- hydrate when element enters the viewport via IntersectionObserver (no rootMargin). */
-declare function visibleStrategy(el: Element, hydrateFn: () => void): void;
+interface MountHandle {
+	/** Unmount the app and cleanup */
+	unmount: () => void;
+	/** Root HTMLElement */
+	root: HTMLElement;
+}
+/**
+* Mount an app to a DOM element.
+*
+* Uses tolerant hydration automatically: if the root element has SSR content,
+* it walks the existing DOM and attaches reactivity without re-creating nodes.
+* If the root is empty (CSR), it renders from scratch.
+*
+* @param app - App function that returns an HTMLElement
+* @param selector - CSS selector string or HTMLElement
+* @param options - Mount options (theme, styles, onMount, etc.)
+* @returns MountHandle with unmount function and root element
+*/
+declare function mount<AppFn extends () => Element>(app: AppFn, selector: string | HTMLElement, options?: MountOptions): MountHandle;
+import { QueryDescriptor as QueryDescriptor2 } from "@vertz/fetch";
+import { isQueryDescriptor } from "@vertz/fetch";
 /**
 * Interface for cache stores used by query().
 * Consumers can provide custom implementations (e.g. LRU, persistent storage).
@@ -437,7 +712,9 @@ interface CacheStore<T = unknown> {
 	get(key: string): T | undefined;
 	set(key: string, value: T): void;
 	delete(key: string): void;
+	clear?(): void;
 }
+import { QueryDescriptor } from "@vertz/fetch";
 /** Options for query(). */
 interface QueryOptions<T> {
 	/** Pre-populated data — skips the initial fetch when provided. */
@@ -450,15 +727,22 @@ interface QueryOptions<T> {
 	key?: string;
 	/** Custom cache store. Defaults to a shared in-memory Map. */
 	cache?: CacheStore<T>;
+	/** Timeout in ms for SSR data loading. Default: 300. Set to 0 to disable. */
+	ssrTimeout?: number;
 }
 /** The reactive object returned by query(). */
-interface QueryResult<T> {
+interface QueryResult<
+	T,
+	E = unknown
+> {
 	/** The fetched data, or undefined while loading. */
-	readonly data: ReadonlySignal<T | undefined>;
-	/** True while a fetch is in progress. */
-	readonly loading: ReadonlySignal<boolean>;
+	readonly data: Unwrapped<ReadonlySignal<T | undefined>>;
+	/** True only on the initial load (no data yet). False during revalidation. */
+	readonly loading: Unwrapped<ReadonlySignal<boolean>>;
+	/** True when refetching while stale data is already available. */
+	readonly revalidating: Unwrapped<ReadonlySignal<boolean>>;
 	/** The error from the latest failed fetch, or undefined. */
-	readonly error: ReadonlySignal<unknown>;
+	readonly error: Unwrapped<ReadonlySignal<E | undefined>>;
 	/** Manually trigger a refetch (clears cache for this key). */
 	refetch: () => void;
 	/** Alias for refetch — revalidate the cached data. */
@@ -472,11 +756,44 @@ interface QueryResult<T> {
 * The thunk is wrapped in an effect so that when reactive dependencies
 * used *before* the async call change, the query automatically re-fetches.
 *
-* @param thunk - An async function that returns the data.
+* @param source - A QueryDescriptor or an async function that returns the data.
 * @param options - Optional configuration.
 * @returns A QueryResult with reactive signals for data, loading, and error.
 */
+declare function query<
+	T,
+	E
+>(descriptor: QueryDescriptor<T, E>, options?: Omit<QueryOptions<T>, "key">): QueryResult<T, E>;
 declare function query<T>(thunk: () => Promise<T>, options?: QueryOptions<T>): QueryResult<T>;
+interface QueryMatchHandlers<
+	T,
+	E
+> {
+	loading: () => Node | null;
+	error: (error: E) => Node | null;
+	data: (data: T) => Node | null;
+}
+/**
+* Pattern-match on a QueryResult's exclusive state.
+*
+* Returns a stable `<span style="display:contents">` wrapper that internally
+* manages branch switching (loading/error/data) via a reactive effect.
+* The same wrapper is returned for repeated calls with the same queryResult
+* (cached via WeakMap), enabling __child's stable-node optimization.
+*
+* Priority: loading → error → data.
+*
+* `loading` only fires on the initial load (no data yet).
+* When revalidating with existing data, the `data` handler receives the
+* current data. Access `query.revalidating` from the component scope for
+* revalidation state.
+*/
+declare function queryMatch<
+	T,
+	E
+>(queryResult: QueryResult<T, E>, handlers: QueryMatchHandlers<T, E>): HTMLElement & {
+	dispose: DisposeFn;
+};
 /**
 * Template literal type utility that extracts route parameter names from a path pattern.
 *
@@ -504,9 +821,34 @@ type ExtractParams<T extends string> = [ExtractParamsFromSegments<WithoutWildcar
 } : Record<string, never> : HasWildcard<T> extends true ? { [K in ExtractParamsFromSegments<WithoutWildcard<T>>] : string } & {
 	"*": string;
 } : { [K in ExtractParamsFromSegments<WithoutWildcard<T>>] : string };
+/**
+* Convert a route pattern to the union of URL shapes it accepts.
+* - Static: `'/'` → `'/'`
+* - Param: `'/tasks/:id'` → `` `/tasks/${string}` ``
+* - Wildcard: `'/files/*'` → `` `/files/${string}` ``
+* - Multi: `'/users/:id/posts/:postId'` → `` `/users/${string}/posts/${string}` ``
+* - Fallback: `string` → `string` (backward compat)
+*/
+type PathWithParams<T extends string> = T extends `${infer Before}*` ? `${PathWithParams<Before>}${string}` : T extends `${infer Before}:${string}/${infer After}` ? `${Before}${string}/${PathWithParams<`${After}`>}` : T extends `${infer Before}:${string}` ? `${Before}${string}` : T;
+/**
+* Union of all valid URL shapes for a route map.
+* Maps each route pattern key through `PathWithParams` to produce the accepted URL shapes.
+*
+* Example:
+* ```
+* RoutePaths<{ '/': ..., '/tasks/:id': ... }> = '/' | `/tasks/${string}`
+* ```
+*/
+type RoutePaths<TRouteMap extends Record<string, unknown>> = { [K in keyof TRouteMap & string] : PathWithParams<K> }[keyof TRouteMap & string];
 /** Simple schema interface for search param parsing. */
 interface SearchParamSchema<T> {
-	parse(data: unknown): T;
+	parse(data: unknown): {
+		ok: true;
+		data: T;
+	} | {
+		ok: false;
+		error: unknown;
+	};
 }
 /** A route configuration for a single path. */
 interface RouteConfig<
@@ -534,6 +876,46 @@ interface RouteConfig<
 interface RouteDefinitionMap {
 	[pattern: string]: RouteConfig;
 }
+/**
+* Loose route config used as the generic constraint for `defineRoutes`.
+* Uses `Record<string, string>` for loader params so any concrete loader
+* that accesses string params (e.g., `params.id`) satisfies the constraint.
+*/
+interface RouteConfigLike {
+	component: () => Node | Promise<{
+		default: () => Node;
+	}>;
+	/**
+	* Method syntax (`loader?(ctx): R`) is intentional — it enables **bivariant**
+	* parameter checking under `strictFunctionTypes`. Property syntax
+	* (`loader?: (ctx) => R`) would be contravariant, causing `RouteConfig<string>`
+	* (whose loader has `params: Record<string, never>`) to fail assignability
+	* against this constraint's `params: Record<string, string>`.
+	*/
+	loader?(ctx: {
+		params: Record<string, string>;
+		signal: AbortSignal;
+	}): unknown;
+	errorComponent?: (error: Error) => Node;
+	searchParams?: SearchParamSchema<unknown>;
+	children?: Record<string, RouteConfigLike>;
+}
+/**
+* Phantom branded array that carries the route map type `T`.
+* The `__routes` property never exists at runtime — it is a type-level
+* marker used to thread the developer's literal route keys through
+* `createRouter`, `useRouter`, etc.
+*/
+type TypedRoutes<T extends Record<string, RouteConfigLike> = RouteDefinitionMap> = CompiledRoute[] & {
+	readonly __routes: T;
+};
+/**
+* Extract the route map type from `TypedRoutes<T>`.
+* If `T` is not a `TypedRoutes`, returns `T` as-is (passthrough).
+*
+* Usage: `useRouter<InferRouteMap<typeof routes>>()`
+*/
+type InferRouteMap<T> = T extends TypedRoutes<infer R> ? R : T;
 /** Internal compiled route. */
 interface CompiledRoute {
 	/** The original path pattern. */
@@ -579,17 +961,30 @@ type LoaderData<T> = T extends {
 * Define routes from a configuration map.
 * Returns an array of compiled routes preserving definition order.
 */
-declare function defineRoutes(map: RouteDefinitionMap): CompiledRoute[];
-/** Props for the Link component. */
-interface LinkProps {
+declare function defineRoutes<const T extends Record<string, RouteConfigLike>>(map: T): TypedRoutes<T>;
+/**
+* Props for the Link component.
+*
+* Generic over the route map `T`. Defaults to `RouteDefinitionMap` (string
+* index signature) for backward compatibility — unparameterized `LinkProps`
+* accepts any string href.
+*/
+interface LinkProps<T extends Record<string, RouteConfigLike> = RouteDefinitionMap> {
 	/** The target URL path. */
-	href: string;
-	/** Text or content for the link. */
-	children: string;
+	href: RoutePaths<T>;
+	/** Text or content for the link. Thunk may return string or Text node. */
+	children: string | (() => string | Node);
 	/** Class applied when the link's href matches the current path. */
 	activeClass?: string;
 	/** Static class name for the anchor element. */
 	className?: string;
+	/** Prefetch strategy. 'hover' triggers server pre-fetch on mouseenter/focus. */
+	prefetch?: "hover";
+}
+/** Options for createLink(). */
+interface LinkFactoryOptions {
+	/** Callback fired when a link wants to prefetch its target URL. */
+	onPrefetch?: (url: string) => void;
 }
 /**
 * Create a Link component factory bound to the router's state.
@@ -598,14 +993,43 @@ interface LinkProps {
 * @param navigate - Navigation function from the router
 * @returns A Link component function
 */
-declare function createLink(currentPath: ReadonlySignal<string>, navigate: (url: string) => void): (props: LinkProps) => HTMLAnchorElement;
+declare function createLink(currentPath: ReadonlySignal<string>, navigate: (url: string) => void, factoryOptions?: LinkFactoryOptions): (props: LinkProps) => HTMLAnchorElement;
 /** Options for router.navigate(). */
 interface NavigateOptions {
 	/** Use history.replaceState instead of pushState. */
 	replace?: boolean;
 }
-/** The router instance returned by createRouter. */
-interface Router {
+/** Handle returned by prefetchNavData for cancellation. */
+interface PrefetchHandle {
+	abort: () => void;
+	/** Resolves when SSE stream completes (data or done event). */
+	done?: Promise<void>;
+}
+/** Options for createRouter(). */
+interface RouterOptions {
+	/** Enable server-side navigation pre-fetch. When true, uses default timeout. */
+	serverNav?: boolean | {
+		timeout?: number;
+	};
+	/** @internal — injected for testing. Production uses the real module. */
+	_prefetchNavData?: (url: string, options?: {
+		timeout?: number;
+	}) => PrefetchHandle;
+}
+/**
+* The router instance returned by createRouter.
+*
+* Generic over the route map `T`. Defaults to `RouteDefinitionMap` (string
+* index signature) for backward compatibility — unparameterized `Router`
+* accepts any string in `navigate()`.
+*
+* Method syntax on `navigate`, `revalidate`, and `dispose` enables bivariant
+* parameter checking under `strictFunctionTypes`. This means `Router<T>` is
+* assignable to `Router` (the unparameterized default), which is required for
+* storing typed routers in the `RouterContext` without contravariance errors.
+* At call sites, TypeScript still enforces the `RoutePaths<T>` constraint.
+*/
+interface Router<T extends Record<string, RouteConfigLike> = RouteDefinitionMap> {
 	/** Current matched route (reactive signal). */
 	current: Signal<RouteMatch | null>;
 	/** Loader data from the current route's loaders (reactive signal). */
@@ -615,34 +1039,52 @@ interface Router {
 	/** Parsed search params from the current route (reactive signal). */
 	searchParams: Signal<Record<string, unknown>>;
 	/** Navigate to a new URL path. */
-	navigate: (url: string, options?: NavigateOptions) => Promise<void>;
+	navigate(url: RoutePaths<T>, options?: NavigateOptions): Promise<void>;
 	/** Re-run all loaders for the current route. */
-	revalidate: () => Promise<void>;
+	revalidate(): Promise<void>;
 	/** Remove popstate listener and clean up the router. */
-	dispose: () => void;
+	dispose(): void;
 }
 /**
+* Convenience alias for a typed router.
+* `TypedRouter<T>` is identical to `Router<T>` — it exists for readability
+* when the generic parameter makes the intent clearer.
+*/
+type TypedRouter<T extends Record<string, RouteConfigLike> = RouteDefinitionMap> = Router<T>;
+/**
 * Create a router instance.
 *
 * @param routes - Compiled route list from defineRoutes()
 * @param initialUrl - The initial URL to match (optional; auto-detects from window.location or __SSR_URL__)
 * @returns Router instance with reactive state and navigation methods
 */
-declare function createRouter(routes: CompiledRoute[], initialUrl?: string): Router;
+declare function createRouter<T extends Record<string, RouteConfigLike> = RouteDefinitionMap>(routes: TypedRoutes<T>, initialUrl?: string, options?: RouterOptions): Router<T>;
 /** Context value for the Outlet. */
-interface OutletContext {
-	/** The child component factory to render, or undefined if no child. */
-	childComponent: (() => Node) | undefined;
-	/** The nesting depth (for debugging/tracking). */
-	depth: number;
+interface OutletContextValue {
+	/** Reactive child component factory (may return async module). */
+	childComponent: Signal<(() => Node | Promise<{
+		default: () => Node;
+	}>) | undefined>;
+	/** Router instance for restoring context in async resolution. */
+	router: Router;
 }
+/** Shared context used by RouterView and Outlet. */
+declare const OutletContext: Context<OutletContextValue>;
 /**
-* Create an Outlet component bound to a specific outlet context.
+* Outlet component — renders the nested child route.
 *
-* @param outletCtx - The context that holds the child component
-* @returns An Outlet component function
+* Must be called inside a layout component rendered by RouterView.
+* Reads from OutletContext to determine which child to render.
 */
-declare function createOutlet(outletCtx: Context<OutletContext>): () => Node;
+declare function Outlet(): Node;
+declare const RouterContext: Context<Router>;
+declare function useRouter<T extends Record<string, RouteConfigLike> = RouteDefinitionMap>(): UnwrapSignals<Router<T>>;
+declare function useParams<TPath extends string = string>(): ExtractParams<TPath>;
+interface RouterViewProps {
+	router: Router;
+	fallback?: () => Node;
+}
+declare function RouterView({ router, fallback }: RouterViewProps): HTMLElement;
 /**
 * Parse URLSearchParams into a typed object, optionally through a schema.
 *
@@ -668,12 +1110,6 @@ declare class DisposalScopeError extends Error {
 	constructor();
 }
 /**
-* Register a cleanup function with the current disposal scope.
-* Throws `DisposalScopeError` if no scope is active — fail-fast
-* so developers know their cleanup callback was not registered.
-*/
-declare function onCleanup(fn: DisposeFn): void;
-/**
 * Group multiple signal writes into a single update flush.
 * Nested batches are supported — only the outermost batch triggers the flush.
 */
@@ -688,13 +1124,106 @@ declare function signal<T>(initial: T): Signal<T>;
 */
 declare function computed<T>(fn: () => T): Computed<T>;
 /**
-* Create a reactive effect that re-runs whenever its dependencies change.
-* Returns a dispose function to stop the effect.
-*/
-declare function effect(fn: () => void): DisposeFn;
-/**
 * Execute a function without tracking any signal reads.
 * Useful for reading signals without creating subscriptions.
 */
 declare function untrack<T>(fn: () => T): T;
-export { watch, visibleStrategy, variants, validate, useSearchParams, useContext, untrack, signal, s, resolveChildren, ref, query, parseSearchParams, onMount, onCleanup, mediaStrategy, lazyStrategy, interactionStrategy, idleStrategy, hydrate, globalCss, formDataToObject, form, effect, eagerStrategy, defineTheme, defineRoutes, css, createRouter, createOutlet, createLink, createContext, computed, compileTheme, children, batch, VariantsConfig, VariantProps, VariantFunction, ValidationResult, ThemeProviderProps, ThemeProvider, ThemeInput, Theme, SuspenseProps, Suspense, SubmitCallbacks, StyleEntry, Signal, SearchParamSchema, SdkMethod, Router, RouteMatch, RouteDefinitionMap, RouteConfig, Ref, ReadonlySignal, QueryResult, QueryOptions, OutletContext, NavigateOptions, MatchedRoute, LoaderData, LinkProps, GlobalCSSOutput, GlobalCSSInput, FormSchema, FormOptions, FormInstance, FormDataOptions, ExtractParams, ErrorBoundaryProps, ErrorBoundary, DisposeFn, DisposalScopeError, Context, Computed, ComponentRegistry, ComponentLoader, ComponentFunction, CompiledTheme, CompiledRoute, ChildrenAccessor, ChildValue, CacheStore, CSSOutput, CSSInput };
+/**
+* Serialized format for EntityStore - used for SSR transfer and hydration.
+*/
+interface SerializedStore {
+	/** Entity data keyed by type → id → entity */
+	entities: Record<string, Record<string, unknown>>;
+	/** Query result indices (optional) */
+	queries?: Record<string, {
+		ids: string[];
+		nextCursor?: string | null;
+	}>;
+}
+/**
+* Options for EntityStore constructor.
+*/
+interface EntityStoreOptions {
+	/** Initial data to hydrate from (SSR). */
+	initialData?: SerializedStore;
+}
+/**
+* EntityStore - Normalized, signal-backed entity cache for @vertz/ui.
+* 
+* Stores entities by type and ID, with signal-per-entity reactivity.
+* Supports field-level merge, SSR hydration, and query result indices.
+*/
+declare class EntityStore {
+	private _entities;
+	private _typeListeners;
+	private _queryIndices;
+	constructor(options?: EntityStoreOptions);
+	/**
+	* Read a single entity. Returns a signal that updates on merge.
+	* Returns the same signal instance on repeated calls (identity stability).
+	*/
+	get<T>(type: string, id: string): ReadonlySignal<T | undefined>;
+	/**
+	* Read multiple entities by IDs. Returns a computed signal of the array.
+	* Returns a NEW computed signal each call (not cached).
+	*/
+	getMany<T>(type: string, ids: string[]): ReadonlySignal<(T | undefined)[]>;
+	/**
+	* Merge one or more entities into the store.
+	* Field-level merge with shallow diff - only updates signals if data changed.
+	* Uses batch() to coalesce multiple updates into single reactive flush.
+	* Uses untrack() to prevent circular re-triggering when called from effects.
+	*/
+	merge<T extends {
+		id: string;
+	}>(type: string, data: T | T[]): void;
+	/**
+	* Remove an entity from the store.
+	* Triggers type change listeners and removes from query indices.
+	*/
+	remove(type: string, id: string): void;
+	/**
+	* Subscribe to type-level changes (create/delete, not field updates).
+	* Returns an unsubscribe function.
+	*/
+	onTypeChange(type: string, callback: () => void): () => void;
+	/**
+	* Check if an entity exists in the store.
+	*/
+	has(type: string, id: string): boolean;
+	/**
+	* Get count of entities for a type.
+	*/
+	size(type: string): number;
+	/**
+	* Serialize the store for SSR transfer.
+	*/
+	dehydrate(): SerializedStore;
+	/**
+	* Hydrate from serialized data. Merges into existing store (doesn't replace).
+	*/
+	hydrate(data: SerializedStore): void;
+	private _getOrCreateTypeMap;
+	private _getOrCreateListeners;
+	private _notifyTypeChange;
+}
+/**
+* Create a pre-populated EntityStore for testing.
+* 
+* @param data - Entity data keyed by type → id → entity
+* @returns A new EntityStore with the data already merged
+* 
+* @example
+* ```ts
+* const store = createTestStore({
+*   User: {
+*     '1': { id: '1', name: 'Alice' },
+*     '2': { id: '2', name: 'Bob' }
+*   }
+* });
+* 
+* expect(store.get('User', '1').value).toEqual({ id: '1', name: 'Alice' });
+* ```
+*/
+declare function createTestStore(data: Record<string, Record<string, unknown>>): EntityStore;
+export { zoomOut, zoomIn, variants, validate, useSearchParams, useRouter, useParams, useContext, untrack, slideOutToTop, slideOutToRight, slideOutToLeft, slideOutToBottom, slideInFromTop, slideInFromRight, slideInFromLeft, slideInFromBottom, signal, setAdapter, s, resolveChildren, resetInjectedStyles, ref, queryMatch, query, parseSearchParams, palettes, onMount2 as onMount, mount, keyframes, isRenderNode, isQueryDescriptor, injectCSS, hydrate, globalCss, getInjectedCSS, getAdapter, formDataToObject, form, fadeOut, fadeIn, defineTheme, defineRoutes, css, createTestStore, createRouter, createLink, createFieldState, createDOMAdapter, createContext, computed, compileTheme, children, batch, accordionUp, accordionDown, __staticText, __exitChildren, __enterChildren, __element, __append, VariantsConfig, VariantProps, VariantFunction, ValidationResult, UnwrapSignals, TypedRoutes, TypedRouter, ThemeProviderProps, ThemeProvider, ThemeInput, Theme, SuspenseProps, Suspense, StyleValue, StyleEntry, Signal, SerializedStore, SearchParamSchema, SdkMethodWithMeta, SdkMethod, RouterViewProps, RouterView, RouterOptions, RouterContext, Router, RoutePaths, RouteMatch, RouteDefinitionMap, RouteConfig, RenderText, RenderNode, RenderElement, RenderAdapter, Ref, ReadonlySignal, RawDeclaration, RENDER_NODE_BRAND, QueryResult, QueryOptions, QueryMatchHandlers, QueryDescriptor2 as QueryDescriptor, PresenceProps, Presence, PathWithParams, OutletContextValue, OutletContext, Outlet, NavigateOptions, MountOptions, MountHandle, MatchedRoute, LoaderData, LinkProps, LinkFactoryOptions, InferRouteMap, GlobalCSSOutput, GlobalCSSInput, FormSchema, FormOptions, FormInstance, FormDataOptions, FieldState, ExtractParams, ErrorBoundaryProps, ErrorBoundary, EntityStoreOptions, EntityStore, DisposeFn, DisposalScopeError, Context, Computed, ComponentRegistry, ComponentLoader, ComponentFunction, CompiledTheme, CompiledRoute, ColorPalette, ChildrenAccessor, ChildValue, CacheStore, CSSOutput, CSSInput, ANIMATION_EASING, ANIMATION_DURATION };