@vertz/ui 0.2.15 → 0.2.17

package/dist/shared/chunk-mtsvrj9e.js

@@ -0,0 +1,23 @@
+import {
+  createContext,
+  useContext
+} from "./chunk-4fwcwxn6.js";
+
+// src/router/router-context.ts
+var RouterContext = createContext(undefined, "@vertz/ui::RouterContext");
+function useRouter() {
+  const router = useContext(RouterContext);
+  if (!router) {
+    throw new Error("useRouter() must be called within RouterContext.Provider");
+  }
+  return router;
+}
+function useParams() {
+  const router = useContext(RouterContext);
+  if (!router) {
+    throw new Error("useParams() must be called within RouterContext.Provider");
+  }
+  return router.current?.parsedParams ?? router.current?.params ?? {};
+}
+
+export { RouterContext, useRouter, useParams };

package/dist/shared/{chunk-j6qyxfdc.js → chunk-vndfjfdy.js}

@@ -6,10 +6,10 @@ import {
 import {
   getAdapter,
   isRenderNode
-} from "./chunk-h89w580h.js";
+} from "./chunk-afawz764.js";
 import {
   domEffect
-} from "./chunk-8hsz5y4a.js";
+} from "./chunk-4fwcwxn6.js";
 
 // src/hydrate/hydration-context.ts
 var isHydrating = false;
@@ -371,4 +371,4 @@ function __exitChildren() {
   }
 }
 
-export { startHydration, endHydration, getIsHydrating, claimText, claimComment, __text, __child, __insert, __element, __append, __staticText, __enterChildren, __exitChildren };
+export { startHydration, endHydration, getIsHydrating, claimElement, claimText, claimComment, enterChildren, exitChildren, __text, __child, __insert, __element, __append, __staticText, __enterChildren, __exitChildren };

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";
@@ -178,16 +179,6 @@ interface AccessEventClient {
 	dispose(): void;
 }
 declare function createAccessEventClient(options: AccessEventClientOptions): AccessEventClient;
-interface AccessGateProps {
-	fallback?: () => unknown;
-	children: (() => unknown) | unknown;
-}
-/**
-* Gate component that blocks children while the access set is loading.
-* Use this to prevent flicker on initial render when access data
-* hasn't been hydrated yet.
-*/
-declare function AccessGate({ fallback, children }: AccessGateProps): ReadonlySignal<unknown> | unknown;
 import { Result } from "@vertz/fetch";
 /**
 * Minimal schema interface compatible with @vertz/schema.
@@ -263,6 +254,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 +275,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>;
@@ -295,11 +296,6 @@ interface AuthProviderProps {
 	children: (() => unknown) | unknown;
 }
 declare function AuthProvider({ basePath, accessControl, accessEvents, accessEventsUrl, flagEntitlementMap, children }: AuthProviderProps): HTMLElement;
-interface AuthGateProps {
-	fallback?: () => unknown;
-	children: (() => unknown) | unknown;
-}
-declare function AuthGate({ fallback, children }: AuthGateProps): ReadonlySignal<unknown> | unknown;
 /**
 * Create an AccessContextValue for use with AccessContext.Provider.
 * Hydrates from `window.__VERTZ_ACCESS_SET__` when available (SSR).
@@ -313,4 +309,24 @@ 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 };
+/**
+* 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;
+/**
+* Get a display name for a user with a fallback chain.
+* Chain: user.name (if string & non-empty) → user.email → fallback (default: 'Unknown')
+*/
+declare function getUserDisplayName(user: User | null | undefined, fallback?: string): string;
+/**
+* Get initials from a user's name or email (max 2 characters).
+* Chain: first + last word initials from name → first char of email → '?'
+*/
+declare function getUserInitials(user: User | null | undefined): string;
+/**
+* Default user silhouette icon for avatar fallbacks.
+* Returns an inline SVG string — no external requests, works in SSR.
+*/
+declare function getUserIcon(size: number): string;
+export { useAuth, useAccessContext, getUserInitials, getUserIcon, getUserDisplayName, getProviderIcon, createAccessProvider, createAccessEventClient, can, User, SignUpInput, SignOutOptions, SignInInput, ResetInput, OAuthProviderInfo, MfaInput, ForgotInput, EntitlementRegistry, Entitlement, DenialReason, DenialMeta, ClientAccessEvent, AuthStatus, AuthResponse, AuthProviderProps, AuthProvider, AuthErrorCode, AuthContextValue, AuthContext, AuthClientError, AccessSet, AccessEventClientOptions, AccessEventClient, AccessContextValue, AccessContext, AccessCheckData, AccessCheck };

package/dist/src/auth/public.js

@@ -1,10 +1,17 @@
+import {
+  RouterContext
+} from "../../shared/chunk-mtsvrj9e.js";
+import {
+  isBrowser
+} from "../../shared/chunk-14eqne2a.js";
 import {
   _tryOnCleanup,
   computed,
   createContext,
+  getSSRContext,
   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 +76,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`;
     }
@@ -139,26 +146,6 @@ function createAccessEventClient(options) {
   }
   return { connect, disconnect, dispose };
 }
-// src/auth/access-gate.ts
-function AccessGate({
-  fallback,
-  children
-}) {
-  const ctx = useContext(AccessContext);
-  if (!ctx) {
-    return typeof children === "function" ? children() : children;
-  }
-  const isLoaded = computed(() => {
-    const set = ctx.accessSet;
-    return set !== null;
-  });
-  return computed(() => {
-    if (isLoaded.value) {
-      return typeof children === "function" ? children() : children;
-    }
-    return fallback ? fallback() : null;
-  });
-}
 // src/auth/access-event-handler.ts
 function handleAccessEvent(accessSet, event, flagEntitlementMap) {
   const current = accessSet.value;
@@ -454,7 +441,7 @@ function createTokenRefresh({ onRefresh }) {
     pendingOfflineRefresh = false;
   }
   let visibilityHandler;
-  if (typeof document !== "undefined") {
+  if (isBrowser()) {
     visibilityHandler = () => {
       if (document.visibilityState === "hidden") {
         clearTimer();
@@ -465,7 +452,7 @@ function createTokenRefresh({ onRefresh }) {
     document.addEventListener("visibilitychange", visibilityHandler);
   }
   let onlineHandler;
-  if (typeof window !== "undefined") {
+  if (isBrowser()) {
     onlineHandler = () => {
       if (pendingOfflineRefresh) {
         pendingOfflineRefresh = false;
@@ -476,10 +463,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 +489,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 +562,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 +586,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 +650,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 +663,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 +742,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 +754,24 @@ function AuthProvider({
         tokenRefresh.schedule(session.expiresAt);
       }
     } else {
-      statusSignal.value = "unauthenticated";
+      deferredRefreshTimer = setTimeout(() => {
+        deferredRefreshTimer = null;
+        refresh();
+      }, 0);
+    }
+  } else {
+    const ssrCtx = getSSRContext();
+    if (ssrCtx?.ssrAuth) {
+      if (ssrCtx.ssrAuth.status === "authenticated") {
+        userSignal.value = ssrCtx.ssrAuth.user;
+        statusSignal.value = "authenticated";
+      } else {
+        statusSignal.value = "unauthenticated";
+      }
     }
   }
   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;
     }
@@ -760,42 +786,74 @@ function AuthProvider({
   }
   return AuthContext.Provider({ value: contextValue, children });
 }
-// src/auth/auth-gate.ts
-function AuthGate({ fallback, children }) {
-  const ctx = useContext(AuthContext);
-  if (!ctx) {
-    return typeof children === "function" ? children() : children;
-  }
-  const isResolved = computed(() => {
-    const status = ctx.status;
-    return status !== "idle" && status !== "loading";
-  });
-  return computed(() => {
-    if (isResolved.value) {
-      return typeof children === "function" ? children() : children;
-    }
-    return fallback ? fallback() : null;
-  });
-}
 // src/auth/create-access-provider.ts
 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/user-display.ts
+function getUserDisplayName(user, fallback = "Unknown") {
+  if (!user)
+    return fallback;
+  const name = user.name;
+  if (typeof name === "string" && name.trim().length > 0)
+    return name.trim();
+  if (user.email)
+    return user.email;
+  return fallback;
+}
+function getUserInitials(user) {
+  if (!user)
+    return "?";
+  const name = user.name;
+  if (typeof name === "string" && name.trim().length > 0) {
+    const words = name.trim().split(/\s+/);
+    const first = words[0] ?? "";
+    const last = words[words.length - 1] ?? "";
+    if (words.length === 1 || !last)
+      return first.charAt(0).toUpperCase() || "?";
+    return (first.charAt(0) + last.charAt(0)).toUpperCase();
+  }
+  if (user.email && user.email.length > 0)
+    return user.email.charAt(0).toUpperCase();
+  return "?";
+}
+// src/auth/user-icon.ts
+function getUserIcon(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="M19 21v-2a4 4 0 0 0-4-4H9a4 4 0 0 0-4 4v2"/><circle cx="12" cy="7" r="4"/></svg>`;
+}
 export {
   useAuth,
   useAccessContext,
+  getUserInitials,
+  getUserIcon,
+  getUserDisplayName,
+  getProviderIcon,
   createAccessProvider,
   createAccessEventClient,
   can,
   AuthProvider,
-  AuthGate,
   AuthContext,
-  AccessGate,
   AccessContext
 };

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
 };