@vertz/ui 0.2.14 → 0.2.16

package/dist/src/index.d.ts

@@ -262,6 +262,101 @@ declare function getInjectedCSS(): string[];
 * @returns Object with block names as keys (class name strings) and non-enumerable `css` property.
 */
 declare function css<T extends CSSInput>(input: T & { [K in keyof T & "css"]? : never }, filePath?: string): CSSOutput<T>;
+interface FontSrc {
+	path: string;
+	weight?: string | number;
+	style?: "normal" | "italic";
+}
+type FallbackFontName = "Arial" | "Times New Roman" | "Courier New";
+interface FontFallbackMetrics {
+	/** CSS ascent-override value, e.g., '94.52%' */
+	ascentOverride: string;
+	/** CSS descent-override value, e.g., '24.60%' */
+	descentOverride: string;
+	/** CSS line-gap-override value, e.g., '0.00%' */
+	lineGapOverride: string;
+	/** CSS size-adjust value, e.g., '104.88%' */
+	sizeAdjust: string;
+	/** System font used as fallback base. */
+	fallbackFont: FallbackFontName;
+}
+interface CompileFontsOptions {
+	/** Pre-computed fallback metrics per font key. Provided by @vertz/ui-server at build/SSR time. */
+	fallbackMetrics?: Record<string, FontFallbackMetrics>;
+}
+interface FontOptions {
+	/** Font weight: '100..1000' (variable) or 400 (fixed). */
+	weight: string | number;
+	/** Font style. @default 'normal' */
+	style?: "normal" | "italic";
+	/** Font-display strategy. @default 'swap' */
+	display?: "auto" | "block" | "swap" | "fallback" | "optional";
+	/** URL path(s) for local/self-hosted fonts. */
+	src?: string | FontSrc[];
+	/** Fallback font stack. */
+	fallback?: string[];
+	/** Font subsets (metadata only — subsetting is deferred to a future phase). @default ['latin'] */
+	subsets?: string[];
+	/** Unicode range for subsetting. */
+	unicodeRange?: string;
+	/**
+	* Control automatic fallback font metric adjustment for zero-CLS font loading.
+	* - true: auto-detect fallback base from `fallback` array (default)
+	* - false: disable
+	* - 'Arial' | 'Times New Roman' | 'Courier New': explicit base
+	* @default true
+	*/
+	adjustFontFallback?: boolean | FallbackFontName;
+}
+type FontStyle = "normal" | "italic";
+type FontDisplay = "auto" | "block" | "swap" | "fallback" | "optional";
+interface FontDescriptor {
+	readonly __brand: "FontDescriptor";
+	readonly family: string;
+	readonly weight: string;
+	readonly style: FontStyle;
+	readonly display: FontDisplay;
+	readonly src?: string | FontSrc[];
+	readonly fallback: string[];
+	readonly subsets: string[];
+	readonly unicodeRange?: string;
+	readonly adjustFontFallback: boolean | FallbackFontName;
+}
+/** Structured description of a resource to preload. */
+interface PreloadItem {
+	href: string;
+	as: "font" | "image" | "style" | "script";
+	type?: string;
+	crossorigin?: boolean;
+}
+interface CompiledFonts {
+	/** @font-face declarations. */
+	fontFaceCss: string;
+	/** :root { --font-<key>: ...; } block (for standalone use). */
+	cssVarsCss: string;
+	/** Individual CSS var lines (e.g., '  --font-sans: ...;') for merging into an existing :root. */
+	cssVarLines: string[];
+	/** <link rel="preload"> HTML tags for font files. */
+	preloadTags: string;
+	/** Structured preload data for generating HTTP Link headers. */
+	preloadItems: PreloadItem[];
+}
+/**
+* Create a font descriptor for use in theme definitions.
+*
+* @param family - The font family name (e.g., 'DM Sans').
+* @param options - Font configuration.
+* @returns A FontDescriptor.
+*/
+declare function font(family: string, options: FontOptions): FontDescriptor;
+/**
+* Compile font descriptors into CSS and preload tags.
+*
+* @param fonts - A map of token key → FontDescriptor.
+* @param options - Optional compilation settings (e.g., pre-computed fallback metrics).
+* @returns Compiled @font-face CSS, CSS var lines, and preload link tags.
+*/
+declare function compileFonts(fonts: Record<string, FontDescriptor>, options?: CompileFontsOptions): CompiledFonts;
 /** Input to globalCss(): selector → property-value map. */
 type GlobalCSSInput = Record<string, Record<string, string>>;
 /** Output of globalCss(): extracted CSS string. */
@@ -348,6 +443,8 @@ interface ThemeInput {
 	colors: ColorTokens;
 	/** Spacing scale tokens. */
 	spacing?: SpacingTokens;
+	/** Font descriptors keyed by token name (e.g., sans, mono, display). */
+	fonts?: Record<string, FontDescriptor>;
 }
 /** The structured theme object returned by defineTheme(). */
 interface Theme {
@@ -355,6 +452,8 @@ interface Theme {
 	colors: ColorTokens;
 	/** Spacing scale tokens. */
 	spacing?: SpacingTokens;
+	/** Font descriptors keyed by token name. */
+	fonts?: Record<string, FontDescriptor>;
 }
 /** Output of compileTheme(). */
 interface CompiledTheme {
@@ -362,6 +461,15 @@ interface CompiledTheme {
 	css: string;
 	/** Flat list of token dot-paths (e.g., 'primary.500', 'background'). */
 	tokens: string[];
+	/** Font preload link tags for injection into <head>. */
+	preloadTags: string;
+	/** Structured preload data for generating HTTP Link headers. */
+	preloadItems: PreloadItem[];
+}
+/** Options for compileTheme(). */
+interface CompileThemeOptions {
+	/** Pre-computed font fallback metrics for zero-CLS font loading. */
+	fallbackMetrics?: CompileFontsOptions["fallbackMetrics"];
 }
 /**
 * Define a theme with raw and contextual design tokens.
@@ -380,7 +488,7 @@ declare function defineTheme(input: ThemeInput): Theme;
 * @param theme - A theme object from defineTheme().
 * @returns Compiled CSS and token list.
 */
-declare function compileTheme(theme: Theme): CompiledTheme;
+declare function compileTheme(theme: Theme, options?: CompileThemeOptions): CompiledTheme;
 /** A child node: either a DOM Node or a string (text content). */
 type ThemeChild = Node | string;
 /** Props for ThemeProvider. */
@@ -551,6 +659,17 @@ declare function __enterChildren(el: Element): void;
 * Compiler output target — emitted after all children are appended.
 */
 declare function __exitChildren(): void;
+/**
+* Returns true when running in a real browser environment.
+* Returns false on the server, even if `window` exists (DOM shim).
+*
+* Uses `hasSSRResolver()` — which returns true when an SSR resolver
+* has been registered — instead of `getSSRContext()` which only returns
+* a value inside `ssrStorage.run()`. This correctly identifies server
+* module-scope code (e.g., HMR re-imports where `createRouter()` runs
+* at import time, outside any SSR render context).
+*/
+declare function isBrowser(): boolean;
 interface FieldState<T = unknown> {
 	error: Signal<string | undefined>;
 	dirty: Signal<boolean>;
@@ -620,20 +739,42 @@ interface SdkMethodWithMeta<
 	};
 }
 /** 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]> };
+type ReservedFormNames = "submitting" | "dirty" | "valid" | "action" | "method" | "onSubmit" | "reset" | "setFieldError" | "submit" | "fields" | "__bindElement";
+/** Built-in object types that should NOT recurse into NestedFieldAccessors. */
+type BuiltInObjects = Date | RegExp | File | Blob | Map<unknown, unknown> | Set<unknown>;
+/** FieldState signal/method property names that conflict with nested field names. */
+type FieldSignalReservedNames = "error" | "dirty" | "touched" | "value" | "setValue" | "reset";
+/** Check if any key of T collides with FieldState property names. */
+type HasReservedFieldName<T> = keyof T & FieldSignalReservedNames extends never ? false : true;
+/** Recursive field accessors for nested schemas. */
+type NestedFieldAccessors<T> = { [K in keyof T] : T[K] extends BuiltInObjects ? FieldState<T[K]> : T[K] extends Array<infer U> ? FieldState<T[K]> & ArrayFieldAccessors<U> : T[K] extends Record<string, unknown> ? HasReservedFieldName<T[K]> extends true ? {
+	__error: `Nested field name conflicts with FieldState property: ${keyof T[K] & FieldSignalReservedNames & string}`;
+} : FieldState<T[K]> & NestedFieldAccessors<T[K]> : FieldState<T[K]> };
+/** Array field accessors — numeric index access to element-level fields. */
+type ArrayFieldAccessors<U> = {
+	[index: number]: U extends BuiltInObjects ? FieldState<U> : U extends Record<string, unknown> ? FieldState<U> & NestedFieldAccessors<U> : FieldState<U>;
+};
+/** Deep partial utility for initial values. */
+type DeepPartial<T> = { [K in keyof T]? : T[K] extends Array<infer U> ? Array<DeepPartial<U>> : T[K] extends Record<string, unknown> ? DeepPartial<T[K]> : T[K] };
+/** Union of all valid dot-paths through a nested type. */
+type FieldPath<
+	T,
+	Prefix extends string = ""
+> = `${Prefix}${keyof T & string}` | { [K in keyof T & string] : T[K] extends Record<string, unknown> ? FieldPath<T[K], `${Prefix}${K}.`> : never }[keyof T & string];
+/** Mapped type providing typed field name strings for compile-time input validation. */
+type FieldNames<TBody> = { readonly [K in keyof TBody & string] : 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;
+	setFieldError: (field: FieldPath<TBody>, message: string) => void;
 	submit: (formData?: FormData) => Promise<void>;
 	submitting: Signal<boolean>;
 	dirty: ReadonlySignal<boolean>;
 	valid: ReadonlySignal<boolean>;
+	fields: FieldNames<TBody>;
 	__bindElement: (el: HTMLFormElement) => void;
 }
 /**
@@ -645,7 +786,7 @@ interface FormBaseProperties<TBody> {
 type FormInstance<
 	TBody,
 	_TResult
-> = keyof TBody & ReservedFormNames extends never ? FormBaseProperties<TBody> & FieldAccessors<TBody> : {
+> = keyof TBody & ReservedFormNames extends never ? FormBaseProperties<TBody> & NestedFieldAccessors<TBody> : {
 	__error: `Field name conflicts with reserved form property: ${keyof TBody & ReservedFormNames & string}`;
 };
 /** Options for creating a form instance. */
@@ -655,8 +796,8 @@ interface FormOptions<
 > {
 	/** Explicit schema for client-side validation before submission. */
 	schema?: FormSchema<TBody>;
-	/** Initial values for form fields. */
-	initial?: Partial<TBody> | (() => Partial<TBody>);
+	/** Initial values for form fields. Supports nested partial values. */
+	initial?: DeepPartial<TBody> | (() => DeepPartial<TBody>);
 	/** Callback invoked after a successful submission. */
 	onSuccess?: (result: TResult) => void;
 	/** Callback invoked when validation or submission fails. */
@@ -685,6 +826,8 @@ declare function form<
 interface FormDataOptions {
 	/** When true, coerces numeric strings to numbers and "true"/"false" to booleans. */
 	coerce?: boolean;
+	/** When true, parses dot-separated keys into nested objects (e.g., "address.street" → { address: { street: ... } }). */
+	nested?: boolean;
 }
 /**
 * Convert FormData to a plain object.
@@ -699,8 +842,8 @@ declare function formDataToObject(formData: FormData, options?: FormDataOptions)
 type ComponentLoader = () => Promise<{
 	default: ComponentFunction;
 }>;
-/** A component function that takes props and an element to mount into. */
-type ComponentFunction = (props: Record<string, unknown>, el: Element) => void;
+/** A component function that takes props and optionally an element to mount into. May return a Node. */
+type ComponentFunction = (props: Record<string, unknown>, el?: Element) => Node | void;
 /** Maps component IDs to their dynamic import loaders. */
 type ComponentRegistry = Record<string, ComponentLoader>;
 /**
@@ -718,6 +861,55 @@ type ComponentRegistry = Record<string, ComponentLoader>;
 */
 declare function hydrate(registry: ComponentRegistry): void;
 /**
+* Registry mapping island IDs to lazy component loaders.
+* Each key must match the `id` prop of an `<Island>` component in the SSR output.
+*/
+type IslandRegistry = Record<string, ComponentLoader>;
+/**
+* Client entry point for island-mode hydration.
+*
+* Scans the DOM for elements with `data-v-island` markers placed by the
+* `<Island>` component during SSR. For each, deserializes props and hydrates
+* the component using viewport-based lazy hydration (IntersectionObserver).
+*
+* This is an alternative to `mount()` for pages that are mostly static
+* with a few interactive islands. Never call both `mount()` and
+* `hydrateIslands()` on the same page.
+*/
+declare function hydrateIslands(registry: IslandRegistry): void;
+declare function configureImageOptimizer(baseUrl: string): void;
+declare function buildOptimizedUrl(src: string, width: number, height: number, quality: number, fit: "cover" | "contain" | "fill"): string | null;
+interface ImageProps {
+	src: string;
+	width: number;
+	height: number;
+	alt: string;
+	class?: string;
+	pictureClass?: string;
+	style?: string;
+	loading?: "lazy" | "eager";
+	decoding?: "async" | "sync" | "auto";
+	fetchpriority?: "high" | "low" | "auto";
+	priority?: boolean;
+	quality?: number;
+	fit?: "cover" | "contain" | "fill";
+	[key: string]: unknown;
+}
+declare function Image(props: ImageProps): HTMLImageElement;
+interface IslandProps {
+	/**
+	* Unique identifier matching the client-side registry key.
+	* Auto-generated by the compiler from the file path and component name.
+	* Can be manually specified to override the generated ID.
+	*/
+	id?: string;
+	/** The component function to render */
+	component: (props: Record<string, unknown>) => unknown;
+	/** Props to pass to the component (must be JSON-serializable) */
+	props?: Record<string, unknown>;
+}
+declare function Island({ id, component: Component, props }: IslandProps): HTMLDivElement;
+/**
 * Options for mounting an app to the DOM.
 */
 interface MountOptions {
@@ -915,6 +1107,8 @@ type ExtractParams<T extends string> = [ExtractParamsFromSegments<WithoutWildcar
 * - 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 route pattern keys from a route map. */
+type RoutePattern<TRouteMap extends Record<string, unknown>> = keyof TRouteMap & string;
 /**
 * Union of all valid URL shapes for a route map.
 * Maps each route pattern key through `PathWithParams` to produce the accepted URL shapes.
@@ -924,7 +1118,7 @@ type PathWithParams<T extends string> = T extends `${infer Before}*` ? `${PathWi
 * RoutePaths<{ '/': ..., '/tasks/:id': ... }> = '/' | `/tasks/${string}`
 * ```
 */
-type RoutePaths<TRouteMap extends Record<string, unknown>> = { [K in keyof TRouteMap & string] : PathWithParams<K> }[keyof TRouteMap & string];
+type RoutePaths<TRouteMap extends Record<string, unknown>> = { [K in RoutePattern<TRouteMap>] : PathWithParams<K> }[RoutePattern<TRouteMap>];
 /** Schema interface for parsing and validating values (search params, path params). */
 interface SearchParamSchema<T> {
 	parse(data: unknown): {
@@ -961,6 +1155,8 @@ interface RouteConfig<
 	searchParams?: SearchParamSchema<TSearch>;
 	/** Nested child routes. */
 	children?: RouteDefinitionMap;
+	/** Whether to pre-render this route at build time (default: true for static routes). */
+	prerender?: boolean;
 }
 /** A map of path patterns to route configs (user input format). */
 interface RouteDefinitionMap {
@@ -990,6 +1186,7 @@ interface RouteConfigLike {
 	params?: ParamSchema<unknown>;
 	searchParams?: SearchParamSchema<unknown>;
 	children?: Record<string, RouteConfigLike>;
+	prerender?: boolean;
 }
 /**
 * Phantom branded array that carries the route map type `T`.
@@ -1023,6 +1220,8 @@ interface CompiledRoute {
 	searchParams?: RouteConfig["searchParams"];
 	/** Compiled children. */
 	children?: CompiledRoute[];
+	/** Whether to pre-render this route at build time (default: true for static routes). */
+	prerender?: boolean;
 }
 /** A single matched route entry in the matched chain. */
 interface MatchedRoute {
@@ -1067,8 +1266,8 @@ declare function defineRoutes<const T extends Record<string, RouteConfigLike>>(m
 interface LinkProps<T extends Record<string, RouteConfigLike> = RouteDefinitionMap> {
 	/** The target URL path. */
 	href: RoutePaths<T>;
-	/** Text or content for the link. Thunk may return string or Text node. */
-	children: string | (() => string | Node);
+	/** Text or content for the link. Accepts string, Node, or a thunk returning either. */
+	children: string | Node | (() => string | Node);
 	/** Class applied when the link's href matches the current path. */
 	activeClass?: string;
 	/** Static class name for the anchor element. */
@@ -1089,11 +1288,32 @@ interface LinkFactoryOptions {
 * @returns A Link component function
 */
 declare function createLink(currentPath: ReadonlySignal<string>, navigate: (url: string) => void, factoryOptions?: LinkFactoryOptions): (props: LinkProps) => HTMLAnchorElement;
+/**
+* Context-based Link component for client-side navigation.
+*
+* Reads the router from `RouterContext` automatically — no manual wiring needed.
+* Just use `<Link href="/about">About</Link>` inside a router-provided tree.
+*/
+declare function Link({ href, children, activeClass, className }: LinkProps): HTMLAnchorElement;
+type NavigateSearchValue = string | number | boolean | null | undefined;
+type NavigateSearch = string | URLSearchParams | Record<string, NavigateSearchValue | readonly NavigateSearchValue[]>;
 /** Options for router.navigate(). */
 interface NavigateOptions {
 	/** Use history.replaceState instead of pushState. */
 	replace?: boolean;
-}
+	/** Route params used to interpolate dynamic segments in the route pattern. */
+	params?: Record<string, string>;
+	/** Search params appended to the final URL. */
+	search?: NavigateSearch;
+}
+type NavigateOptionsFor<TPath extends string> = string extends TPath ? NavigateOptions : TPath extends `${string}:${string}` | `${string}*` ? Omit<NavigateOptions, "params"> & {
+	params: ExtractParams<TPath>;
+} : Omit<NavigateOptions, "params"> & {
+	params?: never;
+};
+type NavigateInput<TPath extends string = string> = {
+	to: TPath;
+} & NavigateOptionsFor<TPath>;
 /** Handle returned by prefetchNavData for cancellation. */
 interface PrefetchHandle {
 	abort: () => void;
@@ -1118,13 +1338,14 @@ interface RouterOptions {
 *
 * Generic over the route map `T`. Defaults to `RouteDefinitionMap` (string
 * index signature) for backward compatibility — unparameterized `Router`
-* accepts any string in `navigate()`.
+* accepts any string in `navigate().to`.
 *
 * 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.
+* At call sites, TypeScript still enforces the `RoutePattern<T>` constraint and
+* the params required for each route pattern.
 */
 interface Router<T extends Record<string, RouteConfigLike> = RouteDefinitionMap> {
 	/** Current matched route (reactive signal). */
@@ -1135,8 +1356,8 @@ interface Router<T extends Record<string, RouteConfigLike> = RouteDefinitionMap>
 	loaderError: Signal<Error | null>;
 	/** Parsed search params from the current route (reactive signal). */
 	searchParams: Signal<Record<string, unknown>>;
-	/** Navigate to a new URL path. */
-	navigate(url: RoutePaths<T>, options?: NavigateOptions): Promise<void>;
+	/** Navigate to a route pattern, interpolating params and search into the final URL. */
+	navigate<TPath extends RoutePattern<T>>(input: NavigateInput<TPath>): Promise<void>;
 	/** Re-run all loaders for the current route. */
 	revalidate(): Promise<void>;
 	/** Remove popstate listener and clean up the router. */
@@ -1155,7 +1376,8 @@ type TypedRouter<T extends Record<string, RouteConfigLike> = RouteDefinitionMap>
 * @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>;
+declare function createRouter<T extends Record<string, RouteConfigLike> = RouteDefinitionMap>(routes: TypedRoutes<T>, initialUrl: string, options?: RouterOptions): Router<T>;
+declare function createRouter<T extends Record<string, RouteConfigLike> = RouteDefinitionMap>(routes: TypedRoutes<T>, options?: RouterOptions): Router<T>;
 /** Context value for the Outlet. */
 interface OutletContextValue {
 	/** Reactive child component factory (may return async module). */
@@ -1293,11 +1515,22 @@ interface SerializedStore {
 	}>;
 }
 /**
+* Options for mergeWithSelect — metadata about field selection.
+*/
+interface MergeSelectOptions {
+	/** Fields that were part of the query's select set */
+	fields: string[];
+	/** Query source identifier for diagnostics (e.g., 'GET:/users') */
+	querySource: string;
+}
+/**
 * Options for EntityStore constructor.
 */
 interface EntityStoreOptions {
 	/** Initial data to hydrate from (SSR). */
 	initialData?: SerializedStore;
+	/** Enable dev-mode field selection tracking (zero overhead when false). */
+	devMode?: boolean;
 }
 /**
 * EntityStore - Normalized, signal-backed entity cache for @vertz/ui.
@@ -1309,6 +1542,7 @@ declare class EntityStore {
 	private _entities;
 	private _typeListeners;
 	private _queryIndices;
+	private _fieldTracker;
 	/** Public accessor for query indices — used by optimistic handlers and tests. */
 	get queryIndices(): QueryResultIndex;
 	constructor(options?: EntityStoreOptions);
@@ -1332,6 +1566,14 @@ declare class EntityStore {
 		id: string;
 	}>(type: string, data: T | T[]): void;
 	/**
+	* Merge entities with field selection metadata.
+	* Registers the select set for dev-mode access warnings.
+	* In production (devMode: false), behaves identically to merge().
+	*/
+	mergeWithSelect<T extends {
+		id: string;
+	}>(type: string, data: T | T[], selectOptions: MergeSelectOptions): void;
+	/**
 	* Remove an entity from the store.
 	* Triggers type change listeners and removes from query indices.
 	*/
@@ -1417,8 +1659,15 @@ declare class EntityStore {
 	private _mergeOne;
 	/**
 	* Recompute the visible signal value from base + all layers.
+	* Uses lastPlainVisible for equality check to avoid triggering
+	* field selection Proxy warnings during internal store operations.
 	*/
 	private _recomputeVisible;
+	/**
+	* Wrap entity in dev-mode Proxy for field selection warnings.
+	* No-op when devMode is off or no tracking exists.
+	*/
+	private _wrapWithFieldProxy;
 	private _getOrCreateTypeMap;
 	private _getOrCreateListeners;
 	private _notifyTypeChange;
@@ -1447,6 +1696,48 @@ declare class QueryEnvelopeStore {
 declare function getEntityStore(): EntityStore;
 /** Get the global QueryEnvelopeStore singleton. */
 declare function getQueryEnvelopeStore(): QueryEnvelopeStore;
+type FieldMissCallback = (type: string, id: string, field: string, querySource: string) => void;
+interface FieldSelectionTrackerOptions {
+	onMiss?: FieldMissCallback;
+}
+/**
+* Tracks field selection metadata per entity for dev-mode access warnings.
+*/
+declare class FieldSelectionTracker {
+	private _selectInfo;
+	/** Dedup: tracks which field warnings have already been emitted */
+	private _warned;
+	private _onMiss;
+	constructor(options?: FieldSelectionTrackerOptions);
+	/**
+	* Register that a query with field selection fetched this entity.
+	* Fields are unioned across all queries.
+	*/
+	registerSelect(type: string, id: string, fields: string[], querySource: string): void;
+	/**
+	* Register that a query without field selection fetched this entity.
+	* Disables warnings for this entity (full fetch = all fields known).
+	*/
+	registerFullFetch(type: string, id: string): void;
+	/**
+	* Check if a field access should trigger a warning.
+	*/
+	shouldWarn(type: string, id: string, field: string): boolean;
+	/**
+	* Remove tracking data for an entity (called when entity is removed/evicted).
+	*/
+	removeEntity(type: string, id: string): void;
+	/**
+	* Wrap an entity object in a dev-mode Proxy that warns on non-selected field access.
+	* Returns the original object if no select tracking exists for this entity.
+	* Each unique (type, id, field) combination warns only once.
+	*/
+	createDevProxy<T extends Record<string, unknown>>(entity: T, type: string, id: string): T;
+	/**
+	* Clear all tracking data.
+	*/
+	clear(): void;
+}
 /**
 * MutationEventBus — simple pub/sub for same-type query revalidation.
 *
@@ -1503,4 +1794,4 @@ declare function resetRelationSchemas_TEST_ONLY(): void;
 * ```
 */
 declare function createTestStore(data: Record<string, Record<string, unknown>>): EntityStore;
-export { zoomOut, zoomIn, variants, validate, useSearchParams, useRouter, useParams, useDialogStack, useContext, untrack, slideOutToTop, slideOutToRight, slideOutToLeft, slideOutToBottom, slideInFromTop, slideInFromRight, slideInFromLeft, slideInFromBottom, signal, setAdapter, s, resolveChildren, resetRelationSchemas_TEST_ONLY, resetInjectedStyles, registerRelationSchema, ref, queryMatch, query, parseSearchParams, palettes, onMount2 as onMount, mount, keyframes, isRenderNode, isQueryDescriptor, invalidate, injectCSS, hydrate, globalCss, getRelationSchema, getQueryEnvelopeStore, getInjectedCSS, getEntityStore, getAdapter, formDataToObject, form, fadeOut, fadeIn, defineTheme, defineRoutes, css, createTestStore, createRouter, createOptimisticHandler, createLink, createFieldState, createDialogStack, 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, RelationSchema, RelationFieldDef, Ref, ReadonlySignal, RawDeclaration, RENDER_NODE_BRAND, QueryResult, QueryOptions, QueryMatchHandlers, QueryEnvelopeStore, QueryEnvelope, QueryDescriptor3 as QueryDescriptor, PresenceProps, Presence, PathWithParams, ParamSchema, OutletContextValue, OutletContext, Outlet, NavigateOptions, MountOptions, MountHandle, MatchedRoute, LoaderData, ListTransitionProps, ListTransition, LinkProps, LinkFactoryOptions, InferRouteMap, GlobalCSSOutput, GlobalCSSInput, FormSchema, FormOptions, FormInstance, FormDataOptions, FieldState, ExtractParams, ErrorBoundaryProps, ErrorBoundary, EntityStoreOptions, EntityStore, DisposeFn, DisposalScopeError, DialogStackContext, DialogStack, DialogHandle, DialogDismissedError, DialogComponent, Context, Computed, ComponentRegistry, ComponentLoader, ComponentFunction, CompiledTheme, CompiledRoute, ColorPalette, ChildrenAccessor, ChildValue, CacheStore, CSSOutput, CSSInput, ANIMATION_EASING, ANIMATION_DURATION };
+export { zoomOut, zoomIn, variants, validate, useSearchParams, useRouter, useParams, useDialogStack, useContext, untrack, slideOutToTop, slideOutToRight, slideOutToLeft, slideOutToBottom, slideInFromTop, slideInFromRight, slideInFromLeft, slideInFromBottom, signal, setAdapter, s, resolveChildren, resetRelationSchemas_TEST_ONLY, resetInjectedStyles, registerRelationSchema, ref, queryMatch, query, parseSearchParams, palettes, onMount2 as onMount, mount, keyframes, isRenderNode, isQueryDescriptor, isBrowser, invalidate, injectCSS, hydrateIslands, hydrate, globalCss, getRelationSchema, getQueryEnvelopeStore, getInjectedCSS, getEntityStore, getAdapter, formDataToObject, form, font, fadeOut, fadeIn, defineTheme, defineRoutes, css, createTestStore, createRouter, createOptimisticHandler, createLink, createFieldState, createDialogStack, createDOMAdapter, createContext, configureImageOptimizer, computed, compileTheme, compileFonts, children, buildOptimizedUrl, 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, RoutePattern, RoutePaths, RouteMatch, RouteDefinitionMap, RouteConfig, RenderText, RenderNode, RenderElement, RenderAdapter, RelationSchema, RelationFieldDef, Ref, ReadonlySignal, RawDeclaration, RENDER_NODE_BRAND, QueryResult, QueryOptions, QueryMatchHandlers, QueryEnvelopeStore, QueryEnvelope, QueryDescriptor3 as QueryDescriptor, PresenceProps, Presence, PreloadItem, PathWithParams, ParamSchema, OutletContextValue, OutletContext, Outlet, NavigateOptions, NavigateInput, MountOptions, MountHandle, MergeSelectOptions, MatchedRoute, LoaderData, ListTransitionProps, ListTransition, LinkProps, LinkFactoryOptions, Link, IslandRegistry, IslandProps, Island, InferRouteMap, ImageProps, Image, GlobalCSSOutput, GlobalCSSInput, FormSchema, FormOptions, FormInstance, FormDataOptions, FontSrc, FontOptions, FontFallbackMetrics, FontDescriptor, FieldState, FieldSelectionTracker, FallbackFontName, ExtractParams, ErrorBoundaryProps, ErrorBoundary, EntityStoreOptions, EntityStore, DisposeFn, DisposalScopeError, DialogStackContext, DialogStack, DialogHandle, DialogDismissedError, DialogComponent, Context, Computed, ComponentRegistry, ComponentLoader, ComponentFunction, CompiledTheme, CompiledRoute, CompiledFonts, CompileThemeOptions, CompileFontsOptions, ColorPalette, ChildrenAccessor, ChildValue, CacheStore, CSSOutput, CSSInput, ANIMATION_EASING, ANIMATION_DURATION };