@vertz/ui 0.2.11 → 0.2.13

package/dist/{internals.d.ts → src/internals.d.ts}

@@ -11,9 +11,36 @@ interface Signal<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;
+}
 /** Dispose function returned by effect(). */
 type DisposeFn = () => void;
 /**
+* Internal: any object that owns a `_subscribers` set.
+* Used by subscribers to track their sources for cleanup.
+*/
+interface SubscriberSource {
+	_subscribers: Set<Subscriber>;
+}
+/** Internal subscriber interface for the reactive graph. */
+interface Subscriber {
+	/** Called when a dependency has changed. */
+	_notify(): void;
+	/** Unique ID for deduplication in batch queue. */
+	_id: number;
+	/** Whether this is an effect (leaf subscriber) or computed (intermediate). */
+	_isEffect: boolean;
+	/** Track a source that this subscriber reads from. */
+	_addSource(source: SubscriberSource): void;
+}
+/**
 * A snapshot of context values at a point in time.
 * Each Provider creates a new scope that inherits from the parent.
 * Effects capture this scope so that useContext works in async callbacks.
@@ -195,7 +222,7 @@ declare function setAdapter(adapter: RenderAdapter | null): void;
 * If no animations are running, calls back immediately.
 * Respects prefers-reduced-motion by skipping the wait.
 */
-declare function onAnimationsComplete(el: HTMLElement, callback: () => void): void;
+declare function onAnimationsComplete(el: Element, callback: () => void): void;
 /**
 * Create a reactive attribute binding.
 * When the value returned by `fn` changes, the attribute is updated.
@@ -429,7 +456,7 @@ 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 };
-/** Simple schema interface for search param parsing. */
+/** Schema interface for parsing and validating values (search params, path params). */
 interface SearchParamSchema<T> {
 	parse(data: unknown): {
 		ok: true;
@@ -439,11 +466,14 @@ interface SearchParamSchema<T> {
 		error: unknown;
 	};
 }
+/** Schema interface for parsing and validating route path params. */
+type ParamSchema<T> = SearchParamSchema<T>;
 /** A route configuration for a single path. */
 interface RouteConfig<
 	TPath extends string = string,
 	TLoaderData = unknown,
-	TSearch = unknown
+	TSearch = unknown,
+	TParams = unknown
 > {
 	/** Component factory (lazy for code splitting). */
 	component: () => Node | Promise<{
@@ -456,6 +486,8 @@ interface RouteConfig<
 	}) => Promise<TLoaderData> | TLoaderData;
 	/** Optional error component rendered when loader throws. */
 	errorComponent?: (error: Error) => Node;
+	/** Optional path params schema for validation/parsing. */
+	params?: ParamSchema<TParams>;
 	/** Optional search params schema for validation/coercion. */
 	searchParams?: SearchParamSchema<TSearch>;
 	/** Nested child routes. */
@@ -476,6 +508,8 @@ interface CompiledRoute {
 		signal: AbortSignal;
 	}) => Promise<unknown> | unknown;
 	errorComponent?: RouteConfig["errorComponent"];
+	/** Optional path params schema for validation/parsing. */
+	params?: ParamSchema<unknown>;
 	searchParams?: RouteConfig["searchParams"];
 	/** Compiled children. */
 	children?: CompiledRoute[];
@@ -489,6 +523,8 @@ interface MatchedRoute {
 interface RouteMatch {
 	/** All params extracted from the full URL path. */
 	params: Record<string, string>;
+	/** Parsed params via schema (set when route has a params schema and parse succeeds). */
+	parsedParams?: Record<string, unknown>;
 	/** The leaf route config that matched. */
 	route: CompiledRoute;
 	/** The chain of matched routes from root to leaf (for nested layouts). */
@@ -585,4 +621,230 @@ declare function domEffect(fn: () => void): DisposeFn;
 * Returns a dispose function to stop the effect.
 */
 declare function lifecycleEffect(fn: () => void): DisposeFn;
-export { stopSignalCollection, startSignalCollection, setContextScope, setAdapter, runCleanups, resolveComponent, removeNode, pushScope, popScope, onCleanup, onAnimationsComplete, matchRoute, matchPath, lifecycleEffect, isRenderNode, insertBefore, getContextScope, getAdapter, executeLoaders, domEffect, deserializeProps, deriveKey, createDOMAdapter, compileTheme, clearChildren, _tryOnCleanup, __text, __staticText, __show, __on, __list, __insert, __exitChildren, __enterChildren, __element, __conditional, __classList, __child, __attr, __append, SPACING_SCALE, SIZE_KEYWORDS, SHADOW_SCALE, RenderText, RenderNode, RenderElement, RenderAdapter, RENDER_NODE_BRAND, RADIUS_SCALE, PropertyMapping, PSEUDO_PREFIXES, PSEUDO_MAP, PROPERTY_MAP, MemoryCache, MatchResult, LINE_HEIGHT_SCALE, KEYWORD_MAP, HEIGHT_AXIS_PROPERTIES, FONT_WEIGHT_SCALE, FONT_SIZE_SCALE, DISPLAY_MAP, CSS_COLOR_KEYWORDS, CSSDeclarationEntry, CONTENT_MAP, COLOR_NAMESPACES, ALIGNMENT_MAP };
+/**
+* QueryResultIndex tracks ordered arrays of entity IDs for list queries.
+* Used to maintain list query results and invalidate on entity removal.
+*/
+declare class QueryResultIndex {
+	private _indices;
+	/**
+	* Set the result IDs for a query key.
+	*/
+	set(queryKey: string, ids: string[]): void;
+	/**
+	* Get the result IDs for a query key.
+	*/
+	get(queryKey: string): string[] | undefined;
+	/**
+	* Remove an entity ID from all indices (called after entity delete).
+	*/
+	removeEntity(entityId: string): void;
+	/**
+	* Clear a specific query's index (for revalidation).
+	*/
+	clear(queryKey: string): void;
+	/**
+	* Snapshot all indices containing the given entity ID.
+	* Returns a Map of queryKey → full ID array (copy) for rollback support.
+	*/
+	snapshotEntity(entityId: string): Map<string, string[]>;
+	/**
+	* Get all query keys (for serialization).
+	*/
+	keys(): string[];
+}
+/**
+* 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, optimistic layers, and query result indices.
+*/
+declare class EntityStore {
+	private _entities;
+	private _typeListeners;
+	private _queryIndices;
+	/** Public accessor for query indices — used by optimistic handlers and tests. */
+	get queryIndices(): QueryResultIndex;
+	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.
+	* Serializes base values only — optimistic layers are transient.
+	*/
+	dehydrate(): SerializedStore;
+	/**
+	* Hydrate from serialized data. Merges into existing store (doesn't replace).
+	*/
+	hydrate(data: SerializedStore): void;
+	/**
+	* Apply an optimistic layer to an entity.
+	* The layer is stacked on top of base, recomputing the visible signal value.
+	*/
+	applyLayer(type: string, id: string, mutationId: string, patch: Record<string, unknown>): void;
+	/**
+	* Increment the reference count for an entity.
+	* Clears orphanedAt timestamp. No-op if entity doesn't exist.
+	*/
+	addRef(type: string, id: string): void;
+	/**
+	* Decrement the reference count for an entity.
+	* Sets orphanedAt when refCount reaches 0. No-op if entity doesn't exist.
+	*/
+	removeRef(type: string, id: string): void;
+	/**
+	* Evict orphaned entities (refCount=0) that have been unreferenced
+	* for longer than maxAge ms. Entities with pending layers are preserved.
+	* Default maxAge: 5 minutes.
+	*/
+	evictOrphans(maxAge?: number): number;
+	/**
+	* Inspect the internal state of an entity — for debugging and testing.
+	* Returns base, layers, visible (computed) state, refCount, and orphanedAt.
+	*/
+	inspect(type: string, id: string): {
+		base: Record<string, unknown>;
+		layers: Map<string, Record<string, unknown>>;
+		visible: unknown;
+		refCount: number;
+		orphanedAt: number | null;
+	} | undefined;
+	/**
+	* Rollback an optimistic layer (mutation failed).
+	* Removes the layer and recomputes visible from base + remaining layers.
+	*/
+	rollbackLayer(type: string, id: string, mutationId: string): void;
+	/**
+	* Optimistically remove an entity (for delete mutations).
+	* Removes the entity from the store and query indices.
+	* Caller should snapshot entity + indices beforehand for rollback.
+	*/
+	removeOptimistic(type: string, id: string, _mutationId: string): void;
+	/**
+	* Restore an entity after a failed optimistic delete.
+	* Re-merges the entity and restores query index positions.
+	*/
+	restoreOptimistic(type: string, _id: string, _mutationId: string, entitySnapshot: unknown, indexSnapshot: Map<string, string[]>): void;
+	/**
+	* Commit an optimistic layer after server confirms the mutation.
+	* Sets base to server data, removes the layer, recomputes visible.
+	*/
+	commitLayer(type: string, id: string, mutationId: string, serverData: Record<string, unknown>): void;
+	/**
+	* Merge a single (already normalized) entity into the store.
+	*/
+	private _mergeOne;
+	/**
+	* Recompute the visible signal value from base + all layers.
+	*/
+	private _recomputeVisible;
+	private _getOrCreateTypeMap;
+	private _getOrCreateListeners;
+	private _notifyTypeChange;
+}
+/** Envelope metadata for list queries (pagination info without entity data). */
+interface QueryEnvelope {
+	total?: number;
+	limit?: number;
+	nextCursor?: string | null;
+	hasNextPage?: boolean;
+	[key: string]: unknown;
+}
+/**
+* Stores list query envelope metadata per query key.
+* Decoupled from entity data — entities live in EntityStore,
+* envelopes live here. Allows list query reconstruction from
+* EntityStore data + envelope metadata.
+*/
+declare class QueryEnvelopeStore {
+	private _envelopes;
+	get(queryKey: string): QueryEnvelope | undefined;
+	set(queryKey: string, envelope: QueryEnvelope): void;
+	clear(): void;
+}
+/** Entry registered by query() during SSR for renderToHTML() to await. */
+interface SSRQueryEntry {
+	promise: Promise<unknown>;
+	timeout: number;
+	resolve: (data: unknown) => void;
+	key: string;
+	resolved?: boolean;
+}
+interface SSRRenderContext {
+	url: string;
+	adapter: RenderAdapter;
+	subscriber: Subscriber | null;
+	readValueCb: ((value: unknown) => void) | null;
+	cleanupStack: DisposeFn[][];
+	batchDepth: number;
+	pendingEffects: Map<number, Subscriber>;
+	contextScope: ContextScope | null;
+	entityStore: EntityStore;
+	envelopeStore: QueryEnvelopeStore;
+	queryCache: MemoryCache<unknown>;
+	inflight: Map<string, Promise<unknown>>;
+	/** SSR queries registered for awaiting before final render. */
+	queries: SSRQueryEntry[];
+	/** Errors collected during SSR rendering. */
+	errors: unknown[];
+	/** Global per-query timeout override (ms). */
+	globalSSRTimeout?: number;
+}
+type SSRContextResolver = () => SSRRenderContext | undefined;
+declare function registerSSRResolver(resolver: SSRContextResolver | null): void;
+declare function getSSRContext(): SSRRenderContext | undefined;
+export { stopSignalCollection, startSignalCollection, setContextScope, setAdapter, runCleanups, resolveComponent, removeNode, registerSSRResolver, pushScope, popScope, onCleanup, onAnimationsComplete, matchRoute, matchPath, lifecycleEffect, isRenderNode, insertBefore, getSSRContext, getContextScope, getAdapter, executeLoaders, domEffect, deserializeProps, deriveKey, createDOMAdapter, compileTheme, clearChildren, _tryOnCleanup, __text, __staticText, __show, __on, __list, __insert, __exitChildren, __enterChildren, __element, __conditional, __classList, __child, __attr, __append, SSRRenderContext, SSRQueryEntry, SPACING_SCALE, SIZE_KEYWORDS, SHADOW_SCALE, RenderText, RenderNode, RenderElement, RenderAdapter, RENDER_NODE_BRAND, RADIUS_SCALE, QueryEnvelopeStore, PropertyMapping, PSEUDO_PREFIXES, PSEUDO_MAP, PROPERTY_MAP, MemoryCache, MatchResult, LINE_HEIGHT_SCALE, KEYWORD_MAP, HEIGHT_AXIS_PROPERTIES, FONT_WEIGHT_SCALE, FONT_SIZE_SCALE, EntityStore, DISPLAY_MAP, CSS_COLOR_KEYWORDS, CSSDeclarationEntry, CONTENT_MAP, COLOR_NAMESPACES, ALIGNMENT_MAP };

package/dist/{internals.js → src/internals.js}

@@ -2,23 +2,25 @@ import {
   deserializeProps,
   onAnimationsComplete,
   resolveComponent
-} from "./shared/chunk-n91rwj2r.js";
+} from "../shared/chunk-2sth83bd.js";
 import {
   __attr,
   __classList,
   __on,
   __show
-} from "./shared/chunk-v3yyf79g.js";
+} from "../shared/chunk-dksg08fq.js";
 import {
   executeLoaders,
   matchPath,
   matchRoute
-} from "./shared/chunk-9e92w0wt.js";
+} from "../shared/chunk-83g4h38e.js";
 import {
+  EntityStore,
   MemoryCache,
+  QueryEnvelopeStore,
   deriveKey
-} from "./shared/chunk-rjjjvmcf.js";
-import"./shared/chunk-jrtrk5z4.js";
+} from "../shared/chunk-hw67ckr3.js";
+import"../shared/chunk-jrtrk5z4.js";
 import {
   ALIGNMENT_MAP,
   COLOR_NAMESPACES,
@@ -38,7 +40,7 @@ import {
   SIZE_KEYWORDS,
   SPACING_SCALE,
   compileTheme
-} from "./shared/chunk-qacth5ah.js";
+} from "../shared/chunk-c9xxsrat.js";
 import {
   __append,
   __child,
@@ -51,30 +53,47 @@ import {
   claimComment,
   claimText,
   getIsHydrating
-} from "./shared/chunk-ryb49346.js";
+} from "../shared/chunk-j6qyxfdc.js";
+import"../shared/chunk-prj7nm08.js";
 import {
   RENDER_NODE_BRAND,
   createDOMAdapter,
   getAdapter,
   isRenderNode,
   setAdapter
-} from "./shared/chunk-g4rch80a.js";
+} from "../shared/chunk-h89w580h.js";
 import {
   _tryOnCleanup,
   domEffect,
   getContextScope,
+  getSSRContext,
   lifecycleEffect,
   onCleanup,
   popScope,
   pushScope,
+  registerSSRResolver,
   runCleanups,
   setContextScope,
   signal,
   startSignalCollection,
   stopSignalCollection
-} from "./shared/chunk-hrd0mft1.js";
-import"./shared/chunk-prj7nm08.js";
+} from "../shared/chunk-8hsz5y4a.js";
 // src/dom/conditional.ts
+function normalizeNode(branchResult) {
+  if (branchResult == null || typeof branchResult === "boolean") {
+    return getAdapter().createComment("empty");
+  }
+  if (isRenderNode(branchResult)) {
+    if (branchResult.nodeType === 11) {
+      const wrap = getAdapter().createElement("span");
+      wrap.style.display = "contents";
+      wrap.appendChild(branchResult);
+      return wrap;
+    }
+    return branchResult;
+  }
+  return getAdapter().createTextNode(String(branchResult));
+}
 function __conditional(condFn, trueFn, falseFn) {
   if (getIsHydrating()) {
     return hydrateConditional(condFn, trueFn, falseFn);
@@ -110,14 +129,7 @@ function hydrateConditional(condFn, trueFn, falseFn) {
     const branchResult = show ? trueFn() : falseFn();
     popScope();
     branchCleanups = scope;
-    let newNode;
-    if (branchResult == null || typeof branchResult === "boolean") {
-      newNode = getAdapter().createComment("empty");
-    } else if (isRenderNode(branchResult)) {
-      newNode = branchResult;
-    } else {
-      newNode = getAdapter().createTextNode(String(branchResult));
-    }
+    const newNode = normalizeNode(branchResult);
     if (currentNode?.parentNode) {
       currentNode.parentNode.replaceChild(newNode, currentNode);
     } else if (anchor.parentNode) {
@@ -148,14 +160,7 @@ function csrConditional(condFn, trueFn, falseFn) {
     const branchResult = show ? trueFn() : falseFn();
     popScope();
     branchCleanups = scope;
-    let newNode;
-    if (branchResult == null || typeof branchResult === "boolean") {
-      newNode = getAdapter().createComment("empty");
-    } else if (isRenderNode(branchResult)) {
-      newNode = branchResult;
-    } else {
-      newNode = getAdapter().createTextNode(String(branchResult));
-    }
+    const newNode = normalizeNode(branchResult);
     if (currentNode?.parentNode) {
       currentNode.parentNode.replaceChild(newNode, currentNode);
     } else if (anchor.parentNode) {
@@ -311,6 +316,7 @@ export {
   runCleanups,
   resolveComponent,
   removeNode,
+  registerSSRResolver,
   pushScope,
   popScope,
   onCleanup,
@@ -320,6 +326,7 @@ export {
   lifecycleEffect,
   isRenderNode,
   insertBefore,
+  getSSRContext,
   getContextScope,
   getAdapter,
   executeLoaders,
@@ -349,6 +356,7 @@ export {
   SHADOW_SCALE,
   RENDER_NODE_BRAND,
   RADIUS_SCALE,
+  QueryEnvelopeStore,
   PSEUDO_PREFIXES,
   PSEUDO_MAP,
   PROPERTY_MAP,
@@ -358,6 +366,7 @@ export {
   HEIGHT_AXIS_PROPERTIES,
   FONT_WEIGHT_SCALE,
   FONT_SIZE_SCALE,
+  EntityStore,
   DISPLAY_MAP,
   CSS_COLOR_KEYWORDS,
   CONTENT_MAP,

package/dist/{jsx-runtime → src/jsx-runtime}/index.d.ts

@@ -3,7 +3,7 @@
 * to understand intrinsic element types and component types.
 */
 declare namespace JSX {
-	type Element = HTMLElement | SVGElement;
+	type Element = HTMLElement | SVGElement | DocumentFragment;
 	type JSXComponent = (props: Record<string, unknown>) => Element;
 	interface HTMLAttributes {
 		[key: string]: unknown;

package/dist/{jsx-runtime → src/jsx-runtime}/index.js

@@ -2,7 +2,7 @@ import {
   SVG_NS,
   isSVGTag,
   normalizeSVGAttr
-} from "../shared/chunk-prj7nm08.js";
+} from "../../shared/chunk-prj7nm08.js";
 
 // src/jsx-runtime/index.ts
 function applyChildren(parent, children) {

package/dist/{query → src/query}/public.d.ts

@@ -10,7 +10,7 @@ interface CacheStore<T = unknown> {
 	delete(key: string): void;
 	clear?(): void;
 }
-import { QueryDescriptor } from "@vertz/fetch";
+import { EntityQueryMeta, QueryDescriptor } from "@vertz/fetch";
 /**
 * A read-only reactive value derived from other signals.
 */
@@ -56,6 +56,8 @@ interface QueryOptions<T> {
 	*   when the function returns `false`).
 	*/
 	refetchInterval?: number | false | ((data: T | undefined, iteration: number) => number | false);
+	/** @internal Entity metadata for entity-backed queries. Set by descriptor overload. */
+	_entityMeta?: EntityQueryMeta;
 }
 /** The reactive object returned by query(). */
 interface QueryResult<

package/dist/src/query/public.js

@@ -0,0 +1,15 @@
+import {
+  query,
+  queryMatch
+} from "../../shared/chunk-hw67ckr3.js";
+import"../../shared/chunk-jrtrk5z4.js";
+import"../../shared/chunk-h89w580h.js";
+import"../../shared/chunk-8hsz5y4a.js";
+
+// src/query/public.ts
+import { isQueryDescriptor } from "@vertz/fetch";
+export {
+  queryMatch,
+  query,
+  isQueryDescriptor
+};

package/dist/{router → src/router}/public.d.ts

@@ -44,7 +44,7 @@ type PathWithParams<T extends string> = T extends `${infer Before}*` ? `${PathWi
 * ```
 */
 type RoutePaths<TRouteMap extends Record<string, unknown>> = { [K in keyof TRouteMap & string] : PathWithParams<K> }[keyof TRouteMap & string];
-/** Simple schema interface for search param parsing. */
+/** Schema interface for parsing and validating values (search params, path params). */
 interface SearchParamSchema<T> {
 	parse(data: unknown): {
 		ok: true;
@@ -54,11 +54,14 @@ interface SearchParamSchema<T> {
 		error: unknown;
 	};
 }
+/** Schema interface for parsing and validating route path params. */
+type ParamSchema<T> = SearchParamSchema<T>;
 /** A route configuration for a single path. */
 interface RouteConfig<
 	TPath extends string = string,
 	TLoaderData = unknown,
-	TSearch = unknown
+	TSearch = unknown,
+	TParams = unknown
 > {
 	/** Component factory (lazy for code splitting). */
 	component: () => Node | Promise<{
@@ -71,6 +74,8 @@ interface RouteConfig<
 	}) => Promise<TLoaderData> | TLoaderData;
 	/** Optional error component rendered when loader throws. */
 	errorComponent?: (error: Error) => Node;
+	/** Optional path params schema for validation/parsing. */
+	params?: ParamSchema<TParams>;
 	/** Optional search params schema for validation/coercion. */
 	searchParams?: SearchParamSchema<TSearch>;
 	/** Nested child routes. */
@@ -101,6 +106,7 @@ interface RouteConfigLike {
 		signal: AbortSignal;
 	}): unknown;
 	errorComponent?: (error: Error) => Node;
+	params?: ParamSchema<unknown>;
 	searchParams?: SearchParamSchema<unknown>;
 	children?: Record<string, RouteConfigLike>;
 }
@@ -131,6 +137,8 @@ interface CompiledRoute {
 		signal: AbortSignal;
 	}) => Promise<unknown> | unknown;
 	errorComponent?: RouteConfig["errorComponent"];
+	/** Optional path params schema for validation/parsing. */
+	params?: ParamSchema<unknown>;
 	searchParams?: RouteConfig["searchParams"];
 	/** Compiled children. */
 	children?: CompiledRoute[];
@@ -144,6 +152,8 @@ interface MatchedRoute {
 interface RouteMatch {
 	/** All params extracted from the full URL path. */
 	params: Record<string, string>;
+	/** Parsed params via schema (set when route has a params schema and parse succeeds). */
+	parsedParams?: Record<string, unknown>;
 	/** The leaf route config that matched. */
 	route: CompiledRoute;
 	/** The chain of matched routes from root to leaf (for nested layouts). */
@@ -304,7 +314,7 @@ type TypedRouter<T extends Record<string, RouteConfigLike> = RouteDefinitionMap>
 * 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__)
+* @param initialUrl - The initial URL to match (optional; auto-detects from window.location or SSR context)
 * @returns Router instance with reactive state and navigation methods
 */
 declare function createRouter<T extends Record<string, RouteConfigLike> = RouteDefinitionMap>(routes: TypedRoutes<T>, initialUrl?: string, options?: RouterOptions): Router<T>;
@@ -351,7 +361,18 @@ declare const OutletContext: Context<OutletContextValue>;
 declare function Outlet(): Node;
 declare const RouterContext: Context<Router>;
 declare function useRouter<T extends Record<string, RouteConfigLike> = RouteDefinitionMap>(): UnwrapSignals<Router<T>>;
+/**
+* Read route params from the current matched route.
+*
+* Overload 1: `useParams<'/tasks/:id'>()` — returns `{ id: string }` (backward compat).
+* Overload 2: `useParams<{ id: number }>()` — returns parsed type assertion
+*   (reads `parsedParams` when a route has a `params` schema).
+*
+* At runtime, both overloads prefer `parsedParams` (schema-parsed) when available,
+* falling back to raw `params` (string values).
+*/
 declare function useParams<TPath extends string = string>(): ExtractParams<TPath>;
+declare function useParams<T extends Record<string, unknown>>(): T;
 interface RouterViewProps {
 	router: Router;
 	fallback?: () => Node;
@@ -384,4 +405,4 @@ declare function parseSearchParams<T = Record<string, string>>(urlParams: URLSea
 * @returns The current search params value
 */
 declare function useSearchParams<T>(searchSignal: ReadonlySignal<T>): T;
-export { useSearchParams, useRouter, useParams, parseSearchParams, defineRoutes, createRouter, createLink, TypedRoutes, TypedRouter, SearchParamSchema, RouterViewProps, RouterView, RouterContext, Router, RoutePaths, RouteMatch, RouteDefinitionMap, RouteConfig, PathWithParams, OutletContextValue, OutletContext, Outlet, NavigateOptions, MatchedRoute, LoaderData, LinkProps, InferRouteMap, ExtractParams, CompiledRoute };
+export { useSearchParams, useRouter, useParams, parseSearchParams, defineRoutes, createRouter, createLink, TypedRoutes, TypedRouter, SearchParamSchema, RouterViewProps, RouterView, RouterContext, Router, RoutePaths, RouteMatch, RouteDefinitionMap, RouteConfig, PathWithParams, ParamSchema, OutletContextValue, OutletContext, Outlet, NavigateOptions, MatchedRoute, LoaderData, LinkProps, InferRouteMap, ExtractParams, CompiledRoute };

package/dist/{router → src/router}/public.js

@@ -8,19 +8,19 @@ import {
   useParams,
   useRouter,
   useSearchParams
-} from "../shared/chunk-0xcmwgdb.js";
-import"../shared/chunk-v3yyf79g.js";
+} from "../../shared/chunk-nn9v1zmk.js";
+import"../../shared/chunk-dksg08fq.js";
 import {
   createRouter
-} from "../shared/chunk-ka5ked7n.js";
+} from "../../shared/chunk-mj7b4t40.js";
 import {
   defineRoutes
-} from "../shared/chunk-9e92w0wt.js";
-import"../shared/chunk-jrtrk5z4.js";
-import"../shared/chunk-ryb49346.js";
-import"../shared/chunk-g4rch80a.js";
-import"../shared/chunk-hrd0mft1.js";
-import"../shared/chunk-prj7nm08.js";
+} from "../../shared/chunk-83g4h38e.js";
+import"../../shared/chunk-jrtrk5z4.js";
+import"../../shared/chunk-j6qyxfdc.js";
+import"../../shared/chunk-prj7nm08.js";
+import"../../shared/chunk-h89w580h.js";
+import"../../shared/chunk-8hsz5y4a.js";
 export {
   useSearchParams,
   useRouter,