@vertz/ui 0.2.15 → 0.2.16

package/dist/src/auth/public.d.ts

@@ -114,6 +114,13 @@ declare const AccessContext: Context<AccessContextValue>;
 */
 declare function useAccessContext(): UnwrapSignals<AccessContextValue>;
 /**
+* Entitlement registry — augmented by @vertz/codegen to narrow entitlement strings.
+* When empty (no codegen), Entitlement falls back to `string`.
+*/
+interface EntitlementRegistry {}
+/** Entitlement type — narrows to literal union when codegen populates EntitlementRegistry. */
+type Entitlement = keyof EntitlementRegistry extends never ? string : Extract<keyof EntitlementRegistry, string>;
+/**
 * Check if the current user has a specific entitlement.
 *
 * Must be called in the component body (like query()/form()).
@@ -126,15 +133,9 @@ declare function useAccessContext(): UnwrapSignals<AccessContextValue>;
 * @param entitlement - The entitlement to check
 * @param entity - Optional entity with pre-computed `__access` metadata
 */
-declare function can(entitlement: string, entity?: {
+declare function can(entitlement: Entitlement, entity?: {
 	__access?: Record<string, AccessCheckData>;
 }): AccessCheck;
-/**
-* Access Event Client — WebSocket client for real-time access invalidation.
-*
-* Connects to the access event WebSocket endpoint, handles reconnection
-* with exponential backoff, and delivers parsed events to the caller.
-*/
 /** Client-side access events (no orgId/userId — server scopes the broadcast) */
 type ClientAccessEvent = {
 	type: "access:flag_toggled";
@@ -263,6 +264,15 @@ interface ResetInput {
 	token: string;
 	password: string;
 }
+interface SignOutOptions {
+	/** Path to navigate to after sign-out completes. Uses SPA navigation (replace). */
+	redirectTo?: string;
+}
+interface OAuthProviderInfo {
+	id: string;
+	name: string;
+	authUrl: string;
+}
 interface AuthResponse {
 	user: User;
 	expiresAt: number;
@@ -275,11 +285,12 @@ interface AuthContextValue {
 	error: Signal<AuthClientError | null>;
 	signIn: SdkMethodWithMeta<SignInInput, AuthResponse>;
 	signUp: SdkMethodWithMeta<SignUpInput, AuthResponse>;
-	signOut: () => Promise<void>;
+	signOut: (options?: SignOutOptions) => Promise<void>;
 	refresh: () => Promise<void>;
 	mfaChallenge: SdkMethodWithMeta<MfaInput, AuthResponse>;
 	forgotPassword: SdkMethodWithMeta<ForgotInput, void>;
 	resetPassword: SdkMethodWithMeta<ResetInput, void>;
+	providers: Signal<OAuthProviderInfo[]>;
 }
 declare const AuthContext: Context<AuthContextValue>;
 declare function useAuth(): UnwrapSignals<AuthContextValue>;
@@ -313,4 +324,40 @@ declare function AuthGate({ fallback, children }: AuthGateProps): ReadonlySignal
 * ```
 */
 declare function createAccessProvider(): AccessContextValue;
-export { useAuth, useAccessContext, createAccessProvider, createAccessEventClient, can, User, SignUpInput, SignInInput, ResetInput, MfaInput, ForgotInput, DenialReason, DenialMeta, ClientAccessEvent, AuthStatus, AuthResponse, AuthProviderProps, AuthProvider, AuthGateProps, AuthGate, AuthErrorCode, AuthContextValue, AuthContext, AuthClientError, AccessSet, AccessGateProps, AccessGate, AccessEventClientOptions, AccessEventClient, AccessContextValue, AccessContext, AccessCheckData, AccessCheck };
+interface OAuthButtonProps {
+	/** Provider ID (e.g., 'github', 'google') */
+	provider: string;
+	/** Custom label text. Defaults to "Continue with {Name}". */
+	label?: string;
+	/** Render icon only, no text. */
+	iconOnly?: boolean;
+	/** @internal — injected providers array for testing. Uses useAuth() in production. */
+	_providers?: OAuthProviderInfo[];
+}
+declare function OAuthButton({ provider, label, iconOnly, _providers }: OAuthButtonProps): Element;
+interface OAuthButtonsProps {
+	/** @internal — injected providers array for testing. Uses useAuth() in production. */
+	_providers?: OAuthProviderInfo[];
+}
+declare function OAuthButtons({ _providers }?: OAuthButtonsProps): HTMLDivElement;
+interface ProtectedRouteProps {
+	/** Path to redirect to when unauthenticated. Default: '/login' */
+	loginPath?: string;
+	/** Rendered while auth is resolving (idle/loading). Default: null */
+	fallback?: () => unknown;
+	/** Rendered when authenticated */
+	children: (() => unknown) | unknown;
+	/** Optional: required entitlements (integrates with can()) */
+	requires?: Entitlement[];
+	/** Rendered when authenticated but lacking required entitlements. Default: null */
+	forbidden?: () => unknown;
+	/** Append ?returnTo=<currentPath> when redirecting. Default: true */
+	returnTo?: boolean;
+}
+declare function ProtectedRoute({ loginPath, fallback, children, requires, forbidden, returnTo }: ProtectedRouteProps): ReadonlySignal<unknown> | unknown;
+/**
+* Get an SVG icon string for a provider.
+* Returns the built-in icon for known providers, or a generic fallback for unknown.
+*/
+declare function getProviderIcon(providerId: string, size: number): string;
+export { useAuth, useAccessContext, getProviderIcon, createAccessProvider, createAccessEventClient, can, User, SignUpInput, SignOutOptions, SignInInput, ResetInput, ProtectedRouteProps, ProtectedRoute, OAuthProviderInfo, OAuthButtonsProps, OAuthButtons, OAuthButtonProps, OAuthButton, MfaInput, ForgotInput, EntitlementRegistry, Entitlement, DenialReason, DenialMeta, ClientAccessEvent, AuthStatus, AuthResponse, AuthProviderProps, AuthProvider, AuthGateProps, AuthGate, AuthErrorCode, AuthContextValue, AuthContext, AuthClientError, AccessSet, AccessGateProps, AccessGate, AccessEventClientOptions, AccessEventClient, AccessContextValue, AccessContext, AccessCheckData, AccessCheck };

package/dist/src/auth/public.js

@@ -1,10 +1,29 @@
+import {
+  RouterContext
+} from "../../shared/chunk-mtsvrj9e.js";
+import {
+  __on
+} from "../../shared/chunk-pnv25zep.js";
+import {
+  isBrowser
+} from "../../shared/chunk-14eqne2a.js";
+import {
+  __append,
+  __element,
+  __enterChildren,
+  __exitChildren,
+  __staticText
+} from "../../shared/chunk-vndfjfdy.js";
+import"../../shared/chunk-prj7nm08.js";
+import"../../shared/chunk-afawz764.js";
 import {
   _tryOnCleanup,
   computed,
   createContext,
+  domEffect,
   signal,
   useContext
-} from "../../shared/chunk-8hsz5y4a.js";
+} from "../../shared/chunk-4fwcwxn6.js";
 
 // src/auth/access-context.ts
 var AccessContext = createContext(undefined, "@vertz/ui::AccessContext");
@@ -69,7 +88,7 @@ function createAccessEventClient(options) {
   function getUrl() {
     if (options.url)
       return options.url;
-    if (typeof window !== "undefined") {
+    if (isBrowser()) {
       const protocol = window.location.protocol === "https:" ? "wss:" : "ws:";
       return `${protocol}//${window.location.host}/api/auth/access-events`;
     }
@@ -454,7 +473,7 @@ function createTokenRefresh({ onRefresh }) {
     pendingOfflineRefresh = false;
   }
   let visibilityHandler;
-  if (typeof document !== "undefined") {
+  if (isBrowser()) {
     visibilityHandler = () => {
       if (document.visibilityState === "hidden") {
         clearTimer();
@@ -465,7 +484,7 @@ function createTokenRefresh({ onRefresh }) {
     document.addEventListener("visibilitychange", visibilityHandler);
   }
   let onlineHandler;
-  if (typeof window !== "undefined") {
+  if (isBrowser()) {
     onlineHandler = () => {
       if (pendingOfflineRefresh) {
         pendingOfflineRefresh = false;
@@ -476,10 +495,10 @@ function createTokenRefresh({ onRefresh }) {
   }
   function dispose() {
     cancel();
-    if (visibilityHandler && typeof document !== "undefined") {
+    if (visibilityHandler && isBrowser()) {
       document.removeEventListener("visibilitychange", visibilityHandler);
     }
-    if (onlineHandler && typeof window !== "undefined") {
+    if (onlineHandler && isBrowser()) {
       window.removeEventListener("online", onlineHandler);
     }
   }
@@ -502,9 +521,19 @@ function AuthProvider({
   flagEntitlementMap,
   children
 }) {
+  const router = useContext(RouterContext);
   const userSignal = signal(null);
   const statusSignal = signal("idle");
   const errorSignal = signal(null);
+  const providersSignal = signal([]);
+  if (isBrowser()) {
+    setTimeout(() => {
+      fetch(`${basePath}/providers`).then((res) => res.ok ? res.json() : []).then((data) => {
+        providersSignal.value = data;
+      }).catch(() => {});
+    }, 0);
+  }
+  let deferredRefreshTimer = null;
   const isAuthenticated = computed(() => statusSignal.value === "authenticated");
   const isLoading = computed(() => statusSignal.value === "loading");
   const accessSetSignal = accessControl ? signal(null) : null;
@@ -565,6 +594,10 @@ function AuthProvider({
     onSuccess: handleAuthSuccess
   });
   const signIn = Object.assign(async (body) => {
+    if (deferredRefreshTimer) {
+      clearTimeout(deferredRefreshTimer);
+      deferredRefreshTimer = null;
+    }
     statusSignal.value = "loading";
     errorSignal.value = null;
     const result = await signInMethod(body);
@@ -585,6 +618,10 @@ function AuthProvider({
     onSuccess: handleAuthSuccess
   });
   const signUp = Object.assign(async (body) => {
+    if (deferredRefreshTimer) {
+      clearTimeout(deferredRefreshTimer);
+      deferredRefreshTimer = null;
+    }
     statusSignal.value = "loading";
     errorSignal.value = null;
     const result = await signUpMethod(body);
@@ -645,7 +682,7 @@ function AuthProvider({
     method: resetPasswordMethod.method,
     meta: resetPasswordMethod.meta
   });
-  const signOut = async () => {
+  const signOut = async (options) => {
     tokenRefresh.cancel();
     try {
       await fetch(`${basePath}/signout`, {
@@ -658,9 +695,16 @@ function AuthProvider({
     statusSignal.value = "unauthenticated";
     errorSignal.value = null;
     clearAccessSet();
-    if (typeof window !== "undefined") {
+    if (isBrowser()) {
       delete window.__VERTZ_SESSION__;
     }
+    if (options?.redirectTo) {
+      if (router) {
+        router.navigate({ to: options.redirectTo, replace: true }).catch(() => {});
+      } else if (typeof console !== "undefined") {
+        console.warn("[vertz] signOut({ redirectTo }) was called but no RouterContext is available. Navigation was skipped.");
+      }
+    }
   };
   let refreshInFlight = null;
   const doRefresh = async () => {
@@ -730,9 +774,10 @@ function AuthProvider({
     refresh,
     mfaChallenge,
     forgotPassword,
-    resetPassword
+    resetPassword,
+    providers: providersSignal
   };
-  if (typeof window !== "undefined") {
+  if (isBrowser()) {
     if (window.__VERTZ_SESSION__?.user) {
       const session = window.__VERTZ_SESSION__;
       userSignal.value = session.user;
@@ -741,11 +786,14 @@ function AuthProvider({
         tokenRefresh.schedule(session.expiresAt);
       }
     } else {
-      statusSignal.value = "unauthenticated";
+      deferredRefreshTimer = setTimeout(() => {
+        deferredRefreshTimer = null;
+        refresh();
+      }, 0);
     }
   }
   if (accessControl && accessSetSignal && accessLoadingSignal) {
-    if (typeof window !== "undefined" && window.__VERTZ_ACCESS_SET__ && typeof window.__VERTZ_ACCESS_SET__.entitlements === "object" && window.__VERTZ_ACCESS_SET__.entitlements !== null) {
+    if (isBrowser() && window.__VERTZ_ACCESS_SET__ && typeof window.__VERTZ_ACCESS_SET__.entitlements === "object" && window.__VERTZ_ACCESS_SET__.entitlements !== null) {
       accessSetSignal.value = window.__VERTZ_ACCESS_SET__;
       accessLoadingSignal.value = false;
     }
@@ -781,18 +829,146 @@ function AuthGate({ fallback, children }) {
 function createAccessProvider() {
   const accessSet = signal(null);
   const loading = signal(true);
-  if (typeof window !== "undefined" && window.__VERTZ_ACCESS_SET__ && typeof window.__VERTZ_ACCESS_SET__.entitlements === "object" && window.__VERTZ_ACCESS_SET__.entitlements !== null) {
+  if (isBrowser() && window.__VERTZ_ACCESS_SET__ && typeof window.__VERTZ_ACCESS_SET__.entitlements === "object" && window.__VERTZ_ACCESS_SET__.entitlements !== null) {
     accessSet.value = window.__VERTZ_ACCESS_SET__;
     loading.value = false;
   }
   return { accessSet, loading };
 }
+// src/auth/provider-icons.ts
+var icons = {
+  github: (size) => `<svg xmlns="http://www.w3.org/2000/svg" width="${size}" height="${size}" viewBox="0 0 24 24" fill="currentColor"><path d="M12 0C5.37 0 0 5.37 0 12c0 5.31 3.435 9.795 8.205 11.385.6.105.825-.255.825-.57 0-.285-.015-1.23-.015-2.235-3.015.555-3.795-.735-4.035-1.41-.135-.345-.72-1.41-1.23-1.695-.42-.225-1.02-.78-.015-.795.945-.015 1.62.87 1.845 1.23 1.08 1.815 2.805 1.305 3.495.99.105-.78.42-1.305.765-1.605-2.67-.3-5.46-1.335-5.46-5.925 0-1.305.465-2.385 1.23-3.225-.12-.3-.54-1.53.12-3.18 0 0 1.005-.315 3.3 1.23.96-.27 1.98-.405 3-.405s2.04.135 3 .405c2.295-1.56 3.3-1.23 3.3-1.23.66 1.65.24 2.88.12 3.18.765.84 1.23 1.905 1.23 3.225 0 4.605-2.805 5.625-5.475 5.925.435.375.81 1.095.81 2.22 0 1.605-.015 2.895-.015 3.3 0 .315.225.69.825.57A12.02 12.02 0 0 0 24 12c0-6.63-5.37-12-12-12Z"/></svg>`,
+  google: (size) => `<svg xmlns="http://www.w3.org/2000/svg" width="${size}" height="${size}" viewBox="0 0 24 24"><path fill="#4285F4" d="M22.56 12.25c0-.78-.07-1.53-.2-2.25H12v4.26h5.92a5.06 5.06 0 0 1-2.2 3.32v2.77h3.57c2.08-1.92 3.28-4.74 3.28-8.1Z"/><path fill="#34A853" d="M12 23c2.97 0 5.46-.98 7.28-2.66l-3.57-2.77c-.98.66-2.23 1.06-3.71 1.06-2.86 0-5.29-1.93-6.16-4.53H2.18v2.84C3.99 20.53 7.7 23 12 23Z"/><path fill="#FBBC05" d="M5.84 14.09c-.22-.66-.35-1.36-.35-2.09s.13-1.43.35-2.09V7.07H2.18C1.43 8.55 1 10.22 1 12s.43 3.45 1.18 4.93l2.85-2.22.81-.62Z"/><path fill="#EA4335" d="M12 5.38c1.62 0 3.06.56 4.21 1.64l3.15-3.15C17.45 2.09 14.97 1 12 1 7.7 1 3.99 3.47 2.18 7.07l3.66 2.84c.87-2.6 3.3-4.53 6.16-4.53Z"/></svg>`,
+  discord: (size) => `<svg xmlns="http://www.w3.org/2000/svg" width="${size}" height="${size}" viewBox="0 0 24 24" fill="currentColor"><path d="M20.317 4.37a19.791 19.791 0 0 0-4.885-1.515.074.074 0 0 0-.079.037c-.21.375-.444.864-.608 1.25a18.27 18.27 0 0 0-5.487 0 12.64 12.64 0 0 0-.617-1.25.077.077 0 0 0-.079-.037A19.736 19.736 0 0 0 3.677 4.37a.07.07 0 0 0-.032.027C.533 9.046-.32 13.58.099 18.057a.082.082 0 0 0 .031.057 19.9 19.9 0 0 0 5.993 3.03.078.078 0 0 0 .084-.028c.462-.63.874-1.295 1.226-1.994a.076.076 0 0 0-.041-.106 13.107 13.107 0 0 1-1.872-.892.077.077 0 0 1-.008-.128 10.2 10.2 0 0 0 .372-.292.074.074 0 0 1 .077-.01c3.928 1.793 8.18 1.793 12.062 0a.074.074 0 0 1 .078.01c.12.098.246.198.373.292a.077.077 0 0 1-.006.127 12.299 12.299 0 0 1-1.873.892.077.077 0 0 0-.041.107c.36.698.772 1.362 1.225 1.993a.076.076 0 0 0 .084.028 19.839 19.839 0 0 0 6.002-3.03.077.077 0 0 0 .032-.054c.5-5.177-.838-9.674-3.549-13.66a.061.061 0 0 0-.031-.03ZM8.02 15.33c-1.183 0-2.157-1.085-2.157-2.419 0-1.333.956-2.419 2.157-2.419 1.21 0 2.176 1.096 2.157 2.42 0 1.333-.956 2.418-2.157 2.418Zm7.975 0c-1.183 0-2.157-1.085-2.157-2.419 0-1.333.955-2.419 2.157-2.419 1.21 0 2.176 1.096 2.157 2.42 0 1.333-.946 2.418-2.157 2.418Z"/></svg>`,
+  apple: (size) => `<svg xmlns="http://www.w3.org/2000/svg" width="${size}" height="${size}" viewBox="0 0 24 24" fill="currentColor"><path d="M17.05 20.28c-.98.95-2.05.88-3.08.4-1.09-.5-2.08-.48-3.24 0-1.44.62-2.2.44-3.06-.4C2.79 15.25 3.51 7.59 9.05 7.31c1.35.07 2.29.74 3.08.8 1.18-.24 2.31-.93 3.57-.84 1.51.12 2.65.72 3.4 1.8-3.12 1.87-2.38 5.98.48 7.13-.57 1.5-1.31 2.99-2.54 4.09ZM12.03 7.25c-.15-2.23 1.66-4.07 3.74-4.25.32 2.32-1.55 4.25-3.74 4.25Z"/></svg>`,
+  microsoft: (size) => `<svg xmlns="http://www.w3.org/2000/svg" width="${size}" height="${size}" viewBox="0 0 24 24"><rect fill="#F25022" x="1" y="1" width="10" height="10"/><rect fill="#7FBA00" x="13" y="1" width="10" height="10"/><rect fill="#00A4EF" x="1" y="13" width="10" height="10"/><rect fill="#FFB900" x="13" y="13" width="10" height="10"/></svg>`,
+  twitter: (size) => `<svg xmlns="http://www.w3.org/2000/svg" width="${size}" height="${size}" viewBox="0 0 24 24" fill="currentColor"><path d="M18.244 2.25h3.308l-7.227 8.26 8.502 11.24H16.17l-5.214-6.817L4.99 21.75H1.68l7.73-8.835L1.254 2.25H8.08l4.713 6.231zm-1.161 17.52h1.833L7.084 4.126H5.117z"/></svg>`
+};
+function fallbackIcon(size) {
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${size}" height="${size}" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 2l-2 2m-7.61 7.61a5.5 5.5 0 1 1-7.778 7.778 5.5 5.5 0 0 1 7.777-7.777zm0 0L15.5 7.5m0 0l3 3L22 7l-3-3m-3.5 3.5L19 4"/></svg>`;
+}
+function getProviderIcon(providerId, size) {
+  const iconFn = icons[providerId];
+  return iconFn ? iconFn(size) : fallbackIcon(size);
+}
+
+// src/auth/oauth-button.ts
+var DANGEROUS_SCHEMES = ["javascript:", "data:", "vbscript:"];
+function isSafeUrl(url) {
+  const normalized = url.replace(/\s/g, "").toLowerCase();
+  if (normalized.startsWith("//"))
+    return false;
+  for (const scheme of DANGEROUS_SCHEMES) {
+    if (normalized.startsWith(scheme))
+      return false;
+  }
+  return true;
+}
+function OAuthButton({ provider, label, iconOnly, _providers }) {
+  const providers = _providers ?? useAuth().providers;
+  const providerInfo = providers.find((p) => p.id === provider);
+  if (!providerInfo) {
+    return __element("span");
+  }
+  const safeAuthUrl = isSafeUrl(providerInfo.authUrl) ? providerInfo.authUrl : "#";
+  const props = { type: "button" };
+  if (iconOnly) {
+    props["aria-label"] = `Continue with ${providerInfo.name}`;
+  }
+  const el = __element("button", props);
+  __on(el, "click", () => {
+    window.location.href = safeAuthUrl;
+  });
+  __enterChildren(el);
+  const iconSpan = __element("span");
+  iconSpan.innerHTML = getProviderIcon(provider, 20);
+  __append(el, iconSpan);
+  if (!iconOnly) {
+    const text = label ?? `Continue with ${providerInfo.name}`;
+    const textSpan = __element("span");
+    __enterChildren(textSpan);
+    __append(textSpan, __staticText(text));
+    __exitChildren();
+    __append(el, textSpan);
+  }
+  __exitChildren();
+  return el;
+}
+// src/auth/oauth-buttons.ts
+function OAuthButtons({ _providers } = {}) {
+  const providers = _providers ?? useAuth().providers;
+  const container = __element("div");
+  __enterChildren(container);
+  for (const provider of providers) {
+    const button = OAuthButton({
+      provider: provider.id,
+      _providers: providers
+    });
+    __append(container, button);
+  }
+  __exitChildren();
+  return container;
+}
+// src/auth/protected-route.ts
+var __DEV__2 = typeof process !== "undefined" && true;
+function ProtectedRoute({
+  loginPath = "/login",
+  fallback,
+  children,
+  requires,
+  forbidden,
+  returnTo = true
+}) {
+  const ctx = useContext(AuthContext);
+  if (!ctx) {
+    if (__DEV__2) {
+      console.warn("ProtectedRoute used without AuthProvider — rendering children unprotected");
+    }
+    return typeof children === "function" ? children() : children;
+  }
+  const router = useContext(RouterContext);
+  const checks = requires?.map((e) => can(e));
+  const allAllowed = computed(() => !checks || checks.every((c) => c.allowed.value));
+  const isResolved = computed(() => {
+    const status = ctx.status;
+    return status !== "idle" && status !== "loading";
+  });
+  const shouldRedirect = computed(() => {
+    if (!isResolved.value)
+      return false;
+    return !ctx.isAuthenticated;
+  });
+  if (router) {
+    domEffect(() => {
+      if (shouldRedirect.value) {
+        const search = returnTo && isBrowser() ? `?returnTo=${encodeURIComponent(window.location.pathname + window.location.search)}` : "";
+        router.navigate({ to: `${loginPath}${search}`, replace: true });
+      }
+    });
+  }
+  return computed(() => {
+    if (!isResolved.value) {
+      return fallback ? fallback() : null;
+    }
+    if (shouldRedirect.value) {
+      return fallback ? fallback() : null;
+    }
+    if (!allAllowed.value) {
+      return forbidden ? forbidden() : null;
+    }
+    return typeof children === "function" ? children() : children;
+  });
+}
 export {
   useAuth,
   useAccessContext,
+  getProviderIcon,
   createAccessProvider,
   createAccessEventClient,
   can,
+  ProtectedRoute,
+  OAuthButtons,
+  OAuthButton,
   AuthProvider,
   AuthGate,
   AuthContext,

package/dist/src/css/public.d.ts

@@ -27,6 +27,101 @@ type CSSOutput<T extends CSSInput = CSSInput> = { readonly [K in keyof T & strin
 * @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. */
@@ -65,6 +160,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 {
@@ -72,6 +169,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 {
@@ -79,6 +178,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.
@@ -97,7 +205,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. */
@@ -151,4 +259,4 @@ interface VariantFunction<V extends VariantDefinitions> {
 * @returns A function that accepts variant props and returns a className string.
 */
 declare function variants<V extends VariantDefinitions>(config: VariantsConfig<V>): VariantFunction<V>;
-export { variants, s, globalCss, defineTheme, css, compileTheme, VariantsConfig, VariantProps, VariantFunction, ThemeProviderProps, ThemeProvider, ThemeInput, Theme, StyleEntry, GlobalCSSOutput, GlobalCSSInput, CompiledTheme, CSSOutput, CSSInput };
+export { variants, s, globalCss, font, defineTheme, css, compileTheme, compileFonts, VariantsConfig, VariantProps, VariantFunction, ThemeProviderProps, ThemeProvider, ThemeInput, Theme, StyleEntry, PreloadItem, GlobalCSSOutput, GlobalCSSInput, FontSrc, FontOptions, FontFallbackMetrics, FontDescriptor, FallbackFontName, CompiledTheme, CompiledFonts, CompileThemeOptions, CompileFontsOptions, CSSOutput, CSSInput };

package/dist/src/css/public.js

@@ -1,22 +1,26 @@
 import {
   ThemeProvider,
+  compileFonts,
   compileTheme,
   css,
   defineTheme,
+  font,
   globalCss,
   s,
   variants
-} from "../../shared/chunk-1wby7nex.js";
-import"../../shared/chunk-j6qyxfdc.js";
+} from "../../shared/chunk-dhehvmj0.js";
+import"../../shared/chunk-vndfjfdy.js";
 import"../../shared/chunk-prj7nm08.js";
-import"../../shared/chunk-h89w580h.js";
-import"../../shared/chunk-8hsz5y4a.js";
+import"../../shared/chunk-afawz764.js";
+import"../../shared/chunk-4fwcwxn6.js";
 export {
   variants,
   s,
   globalCss,
+  font,
   defineTheme,
   css,
   compileTheme,
+  compileFonts,
   ThemeProvider
 };

package/dist/src/form/public.d.ts

@@ -90,8 +90,29 @@ 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" | "fields" | "__bindElement";
-/** Mapped type providing FieldState for each field in TBody. */
+/** Mapped type providing FieldState for each field in TBody (flat — no nested access). */
 type FieldAccessors<TBody> = { [K in keyof TBody] : FieldState<TBody[K]> };
+/** 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. */
@@ -100,7 +121,7 @@ interface FormBaseProperties<TBody> {
 	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>;
@@ -117,7 +138,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. */
@@ -127,8 +148,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. */
@@ -157,6 +178,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.
@@ -167,4 +190,4 @@ interface FormDataOptions {
 *   "true"/"false" become booleans.
 */
 declare function formDataToObject(formData: FormData, options?: FormDataOptions): Record<string, unknown>;
-export { validate, formDataToObject, form, createFieldState, ValidationResult, SdkMethodWithMeta, SdkMethod, FormSchema, FormOptions, FormInstance, FormDataOptions, FieldState, FieldNames };
+export { validate, formDataToObject, form, createFieldState, ValidationResult, SdkMethodWithMeta, SdkMethod, NestedFieldAccessors, FormSchema, FormOptions, FormInstance, FormDataOptions, FieldState, FieldPath, FieldNames, FieldAccessors, DeepPartial, ArrayFieldAccessors };