@mohasinac/appkit 2.8.9 → 3.0.0

package/dist/client/api/useApiMutation.d.ts

@@ -0,0 +1,31 @@
+import { type UseMutationOptions, type UseMutationResult } from "@tanstack/react-query";
+import { ApiError } from "./ApiError";
+/**
+ * Wrap @tanstack/react-query's useMutation so every mutation failure surfaces
+ * automatically — toast by default, inline field error when the error code
+ * maps to a form field via ERROR_DISPLAY_MAP.
+ *
+ * The default `onError` runs FIRST and the caller's `onError` runs after so
+ * extension semantics work: the user always sees something; the caller can
+ * still do optimistic rollback / analytics.
+ *
+ * `loadingMessage` shows a pinned "loading" toast on mutate that resolves to
+ * success / error variant on settle. Use for the few ops > ~1s.
+ */
+export interface UseApiMutationOptions<TData, TError, TVariables, TContext> extends UseMutationOptions<TData, TError, TVariables, TContext> {
+    /** When set, a `loading` toast is shown on mutate and finalized on settle. */
+    loadingMessage?: string;
+    successMessage?: string;
+    /** Translation function (next-intl style); falls back to raw message. */
+    translate?: (key: string) => string;
+    /** Form field error setter (FormShell context). Optional. */
+    setFieldError?: (field: string, message: string) => void;
+    /** Client-error reporter (workstream 13). Optional. */
+    reportClientError?: (payload: {
+        code: string;
+        message: string;
+        stack?: string;
+        requestId?: string;
+    }) => void;
+}
+export declare function useApiMutation<TData = unknown, TError = ApiError, TVariables = void, TContext = unknown>(options: UseApiMutationOptions<TData, TError, TVariables, TContext>): UseMutationResult<TData, TError, TVariables, TContext>;

package/dist/client/api/useApiMutation.js

@@ -0,0 +1,52 @@
+"use client";
+import * as React from "react";
+import { useMutation, } from "@tanstack/react-query";
+import { useToast } from "../../ui/components/Toast";
+import { surfaceError } from "./surface-error";
+export function useApiMutation(options) {
+    const { showToast, updateToast } = useToast();
+    const loadingIdRef = React.useRef(null);
+    const { loadingMessage, successMessage, translate, setFieldError, reportClientError, onMutate, onError, onSuccess, onSettled, ...rest } = options;
+    return useMutation({
+        ...rest,
+        onMutate: (async (variables, ctx) => {
+            if (loadingMessage) {
+                loadingIdRef.current = showToast(loadingMessage, "loading", 0);
+            }
+            return (await onMutate?.(variables, ctx));
+        }),
+        onError: (err, variables, context, ctx) => {
+            surfaceError(err, {
+                showToast,
+                setFieldError,
+                translate,
+                report: reportClientError,
+            });
+            onError?.(err, variables, context, ctx);
+        },
+        onSuccess: (data, variables, context, ctx) => {
+            if (successMessage) {
+                if (loadingIdRef.current) {
+                    updateToast(loadingIdRef.current, "success", successMessage);
+                    loadingIdRef.current = null;
+                }
+                else {
+                    showToast(successMessage, "success");
+                }
+            }
+            onSuccess?.(data, variables, context, ctx);
+        },
+        onSettled: (data, err, variables, context, ctx) => {
+            if (loadingIdRef.current) {
+                if (err) {
+                    updateToast(loadingIdRef.current, "error", err instanceof Error ? err.message : "Action failed");
+                }
+                else if (!successMessage) {
+                    updateToast(loadingIdRef.current, "success", "Done");
+                }
+                loadingIdRef.current = null;
+            }
+            onSettled?.(data, err, variables, context, ctx);
+        },
+    });
+}

package/dist/client/api/useApiQuery.d.ts

@@ -0,0 +1,20 @@
+import { type UseQueryOptions, type UseQueryResult } from "@tanstack/react-query";
+import { ApiError } from "./ApiError";
+/**
+ * Wrap @tanstack/react-query's useQuery so background refetch failures are
+ * never silent. Initial-load failures bubble to error boundary (via the
+ * default Suspense behavior); background refetch errors fire a quiet
+ * "warning" toast so the user knows the data they're looking at is stale.
+ */
+export interface UseApiQueryOptions<TQueryFnData, TError, TData, TQueryKey extends readonly unknown[]> extends UseQueryOptions<TQueryFnData, TError, TData, TQueryKey> {
+    /** Suppress the background-failure toast for this query. */
+    silentBackgroundFailures?: boolean;
+    translate?: (key: string) => string;
+    reportClientError?: (payload: {
+        code: string;
+        message: string;
+        stack?: string;
+        requestId?: string;
+    }) => void;
+}
+export declare function useApiQuery<TQueryFnData = unknown, TError = ApiError, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: UseApiQueryOptions<TQueryFnData, TError, TData, TQueryKey>): UseQueryResult<TData, TError>;

package/dist/client/api/useApiQuery.js

@@ -0,0 +1,56 @@
+"use client";
+import * as React from "react";
+import { useQuery, } from "@tanstack/react-query";
+import { useToast } from "../../ui/components/Toast";
+import { ApiError } from "./ApiError";
+import { getErrorDisplay } from "../../errors/error-display-map";
+export function useApiQuery(options) {
+    const { showToast } = useToast();
+    const { silentBackgroundFailures, translate, reportClientError, ...rest } = options;
+    const result = useQuery(rest);
+    const lastReportedErrorRef = React.useRef(null);
+    React.useEffect(() => {
+        if (!result.isError || !result.error || silentBackgroundFailures)
+            return;
+        if (result.error === lastReportedErrorRef.current)
+            return;
+        lastReportedErrorRef.current = result.error;
+        // Initial-load failures: let the error boundary handle it (don't toast on first paint).
+        // Background refetch failures: toast a quiet warning.
+        if (result.isFetching || !result.data)
+            return;
+        // audit-unknown-ok: TS structural escape
+        const err = result.error;
+        if (err instanceof ApiError) {
+            const display = getErrorDisplay(err.code);
+            const message = translate?.(display.messageKey) ?? err.message;
+            showToast(`Couldn't refresh latest data: ${message}`, "warning");
+            if (reportClientError) {
+                try {
+                    reportClientError({
+                        code: err.code,
+                        message: err.message,
+                        requestId: err.requestId,
+                    });
+                }
+                catch {
+                    /* never propagate from the reporter */
+                }
+            }
+        }
+        else {
+            const message = err instanceof Error ? err.message : "Unknown error";
+            showToast(`Couldn't refresh latest data: ${message}`, "warning");
+        }
+    }, [
+        result.isError,
+        result.error,
+        result.isFetching,
+        result.data,
+        showToast,
+        silentBackgroundFailures,
+        translate,
+        reportClientError,
+    ]);
+    return result;
+}

package/dist/client/observability/installClientErrorReporter.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Mount the window.onerror + window.onunhandledrejection listeners exactly once.
+ * Designed to be called from `[locale]/layout.tsx` inside a "use client" effect.
+ *
+ * Multiple invocations are no-ops — the install guard ensures we never double-
+ * install (e.g. across hot reloads or remounted layouts).
+ */
+export declare function installClientErrorReporter(): () => void;
+/** React hook variant — mounts the reporter once and unmounts on unload. */
+export declare function useClientErrorReporter(): void;

package/dist/client/observability/installClientErrorReporter.js

@@ -0,0 +1,48 @@
+"use client";
+import * as React from "react";
+import { reportClientError } from "./reportClientError";
+let installed = false;
+/**
+ * Mount the window.onerror + window.onunhandledrejection listeners exactly once.
+ * Designed to be called from `[locale]/layout.tsx` inside a "use client" effect.
+ *
+ * Multiple invocations are no-ops — the install guard ensures we never double-
+ * install (e.g. across hot reloads or remounted layouts).
+ */
+export function installClientErrorReporter() {
+    if (typeof window === "undefined")
+        return () => { };
+    if (installed)
+        return () => { };
+    installed = true;
+    const onError = (event) => {
+        reportClientError({
+            code: "CLIENT_WINDOW_ERROR",
+            message: event.message ?? "Window error",
+            stack: event.error instanceof Error ? event.error.stack : undefined,
+        });
+    };
+    const onUnhandled = (event) => {
+        const reason = event.reason;
+        reportClientError({
+            code: "CLIENT_PROMISE_REJECTION",
+            message: reason instanceof Error
+                ? reason.message
+                : typeof reason === "string"
+                    ? reason
+                    : "Unhandled promise rejection",
+            stack: reason instanceof Error ? reason.stack : undefined,
+        });
+    };
+    window.addEventListener("error", onError);
+    window.addEventListener("unhandledrejection", onUnhandled);
+    return () => {
+        window.removeEventListener("error", onError);
+        window.removeEventListener("unhandledrejection", onUnhandled);
+        installed = false;
+    };
+}
+/** React hook variant — mounts the reporter once and unmounts on unload. */
+export function useClientErrorReporter() {
+    React.useEffect(() => installClientErrorReporter(), []);
+}

package/dist/client/observability/reportClientError.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Send a client-side error to the persisted log. POSTs `/api/client-errors`
+ * fire-and-forget; never throws (errors inside the reporter are swallowed
+ * so reporting itself can't break the boundary that called it).
+ *
+ * Dedupe: short rolling cache by hash of (code + message + topStack).
+ * Garbage filter: skips errors whose stack comes only from browser extensions.
+ */
+export interface ClientErrorPayload {
+    code: string;
+    message: string;
+    stack?: string;
+    componentStack?: string;
+    requestId?: string;
+}
+export declare function reportClientError(payload: ClientErrorPayload): void;

package/dist/client/observability/reportClientError.js

@@ -0,0 +1,70 @@
+"use client";
+const SEEN = new Map();
+const DEDUPE_WINDOW_MS = 5000;
+const MAX_SEEN = 32;
+function topFrame(stack) {
+    if (!stack)
+        return "";
+    const lines = stack.split("\n").map((l) => l.trim());
+    // First frame that isn't the error message line
+    return lines.find((l) => l.startsWith("at ")) ?? "";
+}
+function looksLikeExtensionStack(stack) {
+    if (!stack)
+        return false;
+    return /chrome-extension:|moz-extension:|safari-extension:/i.test(stack);
+}
+function hash(payload) {
+    return `${payload.code}|${payload.message}|${topFrame(payload.stack)}`;
+}
+function shouldSkipDuplicate(key) {
+    const now = Date.now();
+    // Cull stale entries
+    for (const [k, t] of SEEN) {
+        if (now - t > DEDUPE_WINDOW_MS)
+            SEEN.delete(k);
+    }
+    if (SEEN.has(key))
+        return true;
+    if (SEEN.size >= MAX_SEEN)
+        SEEN.delete(SEEN.keys().next().value);
+    SEEN.set(key, now);
+    return false;
+}
+export function reportClientError(payload) {
+    try {
+        if (looksLikeExtensionStack(payload.stack))
+            return;
+        const key = hash(payload);
+        if (shouldSkipDuplicate(key))
+            return;
+        const body = JSON.stringify({
+            code: payload.code,
+            message: payload.message,
+            stack: payload.stack?.slice(0, 4096),
+            componentStack: payload.componentStack?.slice(0, 4096),
+            requestId: payload.requestId,
+            route: typeof window !== "undefined" ? window.location.pathname : undefined,
+            userAgent: typeof navigator !== "undefined" ? navigator.userAgent : undefined,
+        });
+        // Prefer sendBeacon — survives navigation and never blocks the unload path.
+        if (typeof navigator !== "undefined" &&
+            typeof navigator.sendBeacon === "function") {
+            const blob = new Blob([body], { type: "application/json" });
+            navigator.sendBeacon("/api/client-errors", blob);
+            return;
+        }
+        // Fallback to fetch keepalive
+        void fetch("/api/client-errors", {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body,
+            keepalive: true,
+        }).catch(() => {
+            /* swallow — reporting must never throw */
+        });
+    }
+    catch {
+        /* swallow — reporting must never throw */
+    }
+}

package/dist/client.d.ts

@@ -1,6 +1,29 @@
+export { HTTP_ERROR_CODES, mapToHttpError } from "./errors/error-mapping";
+export type { HttpErrorCode, MappedError } from "./errors/error-mapping";
+export { ERROR_DISPLAY_MAP, getErrorDisplay } from "./errors/error-display-map";
+export type { ErrorDisplayEntry } from "./errors/error-display-map";
+export { RazorpayUnreachableError } from "./errors/razorpay-unreachable";
+export type { ActionResult } from "./utils/action-result";
+export { isOk, unwrap } from "./utils/action-result";
+export { ApiError, isApiError } from "./client/api/ApiError";
+export { surfaceError } from "./client/api/surface-error";
+export type { SurfaceErrorOptions } from "./client/api/surface-error";
+export { reportClientError, } from "./client/observability/reportClientError";
+export type { ClientErrorPayload } from "./client/observability/reportClientError";
+export { installClientErrorReporter, useClientErrorReporter, } from "./client/observability/installClientErrorReporter";
+export { useApiMutation } from "./client/api/useApiMutation";
+export type { UseApiMutationOptions } from "./client/api/useApiMutation";
+export { useApiQuery } from "./client/api/useApiQuery";
+export type { UseApiQueryOptions } from "./client/api/useApiQuery";
+export { ServerErrorsListView, ServerErrorDetailView, MaintenanceDashboardView, AnalysisRunnerView, } from "./_internal/client/features/maintenance";
+export type { ServerErrorsListViewProps, ServerErrorDetailViewProps, MaintenanceDashboardViewProps, } from "./_internal/client/features/maintenance";
 export { registerClientAuthProvider, getClientAuthProvider, type IClientAuthProvider, } from "./contracts/client-auth";
 export { registerClientRealtimeProvider, getClientRealtimeProvider, type IClientRealtimeProvider, type RealtimeSnapshot, type Unsubscribe, } from "./contracts/client-realtime";
 export { registerClientSessionAdapter, getClientSessionAdapter, type IClientSessionAdapter, type AdapterAuthUser, type AuthUnsubscribe, } from "./contracts/client-session";
+export { ThemeProvider, useTheme, buildThemeRegistry } from "./theme";
+export type { ModePreference, SiteSettingsThemeInput, ThemeContextValue, ThemeProviderProps, ThemeRegistry, } from "./theme";
+export { BUILT_IN_THEMES, DEFAULT_DARK_THEME, DEFAULT_LIGHT_THEME, REQUIRED_GRADIENT_KEYS, REQUIRED_THEME_TOKENS, getDefaultBuiltInTheme, } from "./tokens/themes";
+export type { GradientKey, RequiredThemeToken, ThemeMode, ThemeRecord, } from "./tokens/themes";
 export { ConfirmDeleteModal } from "./ui/components/ConfirmDeleteModal";
 export { EmptyState } from "./ui/components/EmptyState";
 export { Skeleton } from "./ui/components/Skeleton";
@@ -11,6 +34,7 @@ export { SellerProductsView } from "./features/seller/components/SellerProductsV
 export { Drawer } from "./ui/components/Drawer";
 export { FilterDrawer } from "./ui/components/FilterDrawer";
 export { Modal } from "./ui/components/Modal";
+export { Form } from "./ui/components/Form";
 export { QuickCreateModal } from "./ui/components/QuickCreateModal";
 export type { QuickCreateModalProps } from "./ui/components/QuickCreateModal";
 export { VacationBanner } from "./ui/components/VacationBanner";
@@ -37,7 +61,6 @@ export { usePullToRefresh } from "./react/hooks/usePullToRefresh";
 export { useSwipe } from "./react/hooks/useSwipe";
 export { useInfiniteScroll } from "./react/hooks/useInfiniteScroll";
 export type { UseInfiniteScrollOptions, UseInfiniteScrollResult, } from "./react/hooks/useInfiniteScroll";
-export { useTheme } from "./react/contexts/ThemeContext";
 export { useUnsavedChanges } from "./react/hooks/useUnsavedChanges";
 export { useVisibleItems } from "./react/hooks/useVisibleItems";
 export { FirebaseClientAuthProvider } from "./providers/firebase-client/index";
@@ -56,7 +79,6 @@ export { useMediaTrim } from "./features/media/index";
 export { useMediaUpload } from "./features/media/index";
 export { SessionProvider, useSession } from "./react/contexts/SessionContext";
 export type { SessionProviderProps } from "./react/contexts/SessionContext";
-export { ThemeProvider } from "./react/contexts/ThemeContext";
 export { useUrlTable } from "./react/hooks/useUrlTable";
 export type { UseUrlTableOptions } from "./react/hooks/useUrlTable";
 export { useBulkSelection } from "./react/hooks/useBulkSelection";
@@ -68,7 +90,7 @@ export { SORT_DIR, sortBy } from "./constants/sort";
 export { SIEVE_OP, sieveFilter, sieveAnd, sieveMultiEq } from "./utils/sieve-builder";
 export { Container, Grid, Row, Stack } from "./ui/components/Layout";
 export { Div } from "./ui/components/Div";
-export { Main, Section, Nav, Ul, Ol, Li, Table, Thead, Tbody, Tr, Th, Td } from "./ui/components/Semantic";
+export { Main, Section, Nav, Ul, Ol, Li, Table, Thead, Tbody, Tr, Th, Td, Code, Pre, Blockquote } from "./ui/components/Semantic";
 export { Badge } from "./ui/components/Badge";
 export { Button } from "./ui/components/Button";
 export { ClaimCouponButton } from "./ui/components/ClaimCouponButton";
@@ -87,6 +109,8 @@ export type { FieldSelectProps } from "./ui/forms";
 export { FieldSelect } from "./ui/forms";
 export type { FieldCheckboxProps } from "./ui/forms";
 export { FieldCheckbox } from "./ui/forms";
+export type { ColorPickerFieldProps } from "./ui/forms";
+export { ColorPickerField } from "./ui/forms";
 export { Select } from "./ui/components/Select";
 export type { SelectOption, SelectProps } from "./ui/components/Select";
 export { Heading } from "./ui/components/Typography";
@@ -282,3 +306,7 @@ export { SellerDigitalCodesView } from "./features/seller/components/SellerDigit
 export type { SellerDigitalCodesViewProps } from "./features/seller/components/SellerDigitalCodesView";
 export { SellerLiveView } from "./features/seller/components/SellerLiveView";
 export type { SellerLiveViewProps } from "./features/seller/components/SellerLiveView";
+export { SCHEMAS, lookupApiSchema, lookupFirestoreSchema, } from "./schemas/index";
+export type { ApiRouteKey, ApiRouteSchema, FirestoreDocument, FirestoreValue, FormFieldValue, FormValues, HttpVerb, JsonArray, JsonObject, JsonObjectWithUndefined, JsonPrimitive, JsonValue, JsonValueWithUndefined, RegisteredApiRouteKey, RegisteredFirestoreCollection, RegisteredFormId, RegisteredRtdbChannel, RegisteredSieveCollection, RegisteredStorageOp, RegisteredWebhookProvider, RegistryEntry, SchemaRegistry, SchemasShape, WebhookSchemaBucket, } from "./schemas/index";
+export { normalizeError, getErrorMessage, isApiNormalized, isAppNormalized, isFirebaseAuthNormalized, isFirebaseFirestoreNormalized, isFirebaseStorageNormalized, isNativeNormalized, isNetworkNormalized, isUnknownNormalized, isZodNormalized, } from "./errors/normalize";
+export type { NormalizedError, NormalizedApiError, NormalizedAppError, NormalizedFirebaseAuthError, NormalizedFirebaseFirestoreError, NormalizedFirebaseStorageError, NormalizedNativeError, NormalizedNetworkError, NormalizedUnknownThrownValue, NormalizedZodError, } from "./errors/normalize";

package/dist/client.js

@@ -1,11 +1,37 @@
 "use client";
 // Client-only public exports
+// [CLIENT-SAFE] Error code map + display lookup — pure constants, no server deps.
+// Used by useApiMutation / useApiQuery / Button surface-error to route ApiError → toast or inline field error.
+export { HTTP_ERROR_CODES, mapToHttpError } from "./errors/error-mapping";
+export { ERROR_DISPLAY_MAP, getErrorDisplay } from "./errors/error-display-map";
+export { RazorpayUnreachableError } from "./errors/razorpay-unreachable";
+export { isOk, unwrap } from "./utils/action-result";
+// [CLIENT-SAFE] Client error class + surface-error router + reporter primitives.
+// Used by useApiMutation / useApiQuery and Button's async-onclick catch.
+export { ApiError, isApiError } from "./client/api/ApiError";
+export { surfaceError } from "./client/api/surface-error";
+export { reportClientError, } from "./client/observability/reportClientError";
+export { installClientErrorReporter, useClientErrorReporter, } from "./client/observability/installClientErrorReporter";
+// [CLIENT-SAFE] React Query wrappers — auto-toast / auto-inline-field-error
+// on failure, optional `loadingMessage` for long ops.
+export { useApiMutation } from "./client/api/useApiMutation";
+export { useApiQuery } from "./client/api/useApiQuery";
+// [CLIENT-ONLY] Maintenance UI — listing + detail + dashboard + analysis runner.
+// Consumed by the /admin/maintenance/* page shims.
+export { ServerErrorsListView, ServerErrorDetailView, MaintenanceDashboardView, AnalysisRunnerView, } from "./_internal/client/features/maintenance";
 // Provider registration — pure contract modules with zero server dependencies.
 // Exported here so consumers can import registration functions from
 // @mohasinac/appkit/client without pulling in firebase-admin or other server code.
 export { registerClientAuthProvider, getClientAuthProvider, } from "./contracts/client-auth";
 export { registerClientRealtimeProvider, getClientRealtimeProvider, } from "./contracts/client-realtime";
 export { registerClientSessionAdapter, getClientSessionAdapter, } from "./contracts/client-session";
+// [CLIENT-ONLY] ThemeProvider — applies a theme record to `<html>` via
+// `data-theme` + inline CSS-variable writes. Tracks `prefers-color-scheme`
+// when the user picks `"auto"` mode. Built-in themes ship via `./tokens/themes`.
+// Re-exported through the public `./theme` barrel to keep audit-appkit-reexports
+// clean (no `_internal/` symbols may surface through public barrels).
+export { ThemeProvider, useTheme, buildThemeRegistry } from "./theme";
+export { BUILT_IN_THEMES, DEFAULT_DARK_THEME, DEFAULT_LIGHT_THEME, REQUIRED_GRADIENT_KEYS, REQUIRED_THEME_TOKENS, getDefaultBuiltInTheme, } from "./tokens/themes";
 // [CLIENT-ONLY]-Cannot run in SSR mode â€" uses browser-only APIs (window, navigator, localStorage, matchMedia, DOM events) that do not exist in Node.js.
 // ConfirmDeleteModal - Component for confirm delete modal.
 export { ConfirmDeleteModal } from "./ui/components/ConfirmDeleteModal";
@@ -24,6 +50,7 @@ export { FilterDrawer } from "./ui/components/FilterDrawer";
 // [CLIENT-ONLY]-Cannot run in SSR mode â€" uses browser-only APIs (window, navigator, localStorage, matchMedia, DOM events) that do not exist in Node.js.
 // Modal - Component for modal.
 export { Modal } from "./ui/components/Modal";
+export { Form } from "./ui/components/Form";
 export { QuickCreateModal } from "./ui/components/QuickCreateModal";
 export { VacationBanner } from "./ui/components/VacationBanner";
 export { useInlineToggle, useInlineTextEdit } from "./react/hooks/useInlineRowEdit";
@@ -75,9 +102,7 @@ export { useSwipe } from "./react/hooks/useSwipe";
 // [CLIENT-ONLY]-Cannot run in SSR mode — uses IntersectionObserver.
 // useInfiniteScroll - IntersectionObserver primitive for cursor-based listings (Q6 — S13).
 export { useInfiniteScroll } from "./react/hooks/useInfiniteScroll";
-// [CLIENT-ONLY]-Cannot run in SSR mode â€" uses browser-only APIs (window, navigator, localStorage, matchMedia, DOM events) that do not exist in Node.js.
-// useTheme - React hook for use theme.
-export { useTheme } from "./react/contexts/ThemeContext";
+// useTheme — exported above alongside the registry-aware ThemeProvider.
 // [CLIENT-ONLY]-Cannot run in SSR mode â€" uses browser-only APIs (window, navigator, localStorage, matchMedia, DOM events) that do not exist in Node.js.
 // useUnsavedChanges - React hook for use unsaved changes.
 export { useUnsavedChanges } from "./react/hooks/useUnsavedChanges";
@@ -120,7 +145,7 @@ export { useMediaTrim } from "./features/media/index";
 export { useMediaUpload } from "./features/media/index";
 // Client-side context providers
 export { SessionProvider, useSession } from "./react/contexts/SessionContext";
-export { ThemeProvider } from "./react/contexts/ThemeContext";
+// ThemeProvider — exported above alongside the registry-aware variant.
 export { useUrlTable } from "./react/hooks/useUrlTable";
 export { useBulkSelection } from "./react/hooks/useBulkSelection";
 export { useEntityDelete } from "./react/hooks/useEntityDelete";
@@ -130,7 +155,7 @@ export { SORT_DIR, sortBy } from "./constants/sort";
 export { SIEVE_OP, sieveFilter, sieveAnd, sieveMultiEq } from "./utils/sieve-builder";
 export { Container, Grid, Row, Stack } from "./ui/components/Layout";
 export { Div } from "./ui/components/Div";
-export { Main, Section, Nav, Ul, Ol, Li, Table, Thead, Tbody, Tr, Th, Td } from "./ui/components/Semantic";
+export { Main, Section, Nav, Ul, Ol, Li, Table, Thead, Tbody, Tr, Th, Td, Code, Pre, Blockquote } from "./ui/components/Semantic";
 export { Badge } from "./ui/components/Badge";
 export { Button } from "./ui/components/Button";
 export { ClaimCouponButton } from "./ui/components/ClaimCouponButton";
@@ -142,6 +167,7 @@ export { FormShell, FormShellProvider, FormShellContext, useFormShell, useFormSh
 export { FieldInput } from "./ui/forms";
 export { FieldSelect } from "./ui/forms";
 export { FieldCheckbox } from "./ui/forms";
+export { ColorPickerField } from "./ui/forms";
 export { Select } from "./ui/components/Select";
 export { Heading } from "./ui/components/Typography";
 export { Label, Text, Span, Caption } from "./ui/components/Typography";
@@ -279,3 +305,9 @@ export { SellerBundlesView } from "./features/seller/components/SellerBundlesVie
 export { SellerClassifiedView } from "./features/seller/components/SellerClassifiedView";
 export { SellerDigitalCodesView } from "./features/seller/components/SellerDigitalCodesView";
 export { SellerLiveView } from "./features/seller/components/SellerLiveView";
+// ── Central schema registry (W1) ──────────────────────────────────────────────
+// Pure Zod, isomorphic — re-exported here so client code can resolve schemas
+// without pulling in the full server barrel.
+export { SCHEMAS, lookupApiSchema, lookupFirestoreSchema, } from "./schemas/index";
+// ── W3 catch-clause normalizer ──────────────────────────────────────────────
+export { normalizeError, getErrorMessage, isApiNormalized, isAppNormalized, isFirebaseAuthNormalized, isFirebaseFirestoreNormalized, isFirebaseStorageNormalized, isNativeNormalized, isNetworkNormalized, isUnknownNormalized, isZodNormalized, } from "./errors/normalize";

package/dist/configs/eslint.js

@@ -11,6 +11,55 @@
  * module.exports = defineEslintConfig();
  * ```
  */
+/**
+ * `no-restricted-syntax` selectors that mirror the variant-catalogue audits
+ * (`audit-html-wrappers.mjs` raw-tag rules + `audit-variant-prop-coverage.mjs`).
+ *
+ * Surfaces in-editor red squiggles for the highest-impact raw HTML patterns
+ * so consumers see violations as they type, instead of only at `npm run check`
+ * time. Severity is `"warn"` for now so the IDE flags but doesn't block;
+ * the runtime audits are the authoritative gate.
+ *
+ * The selectors deliberately mirror the file-level audits — drift between
+ * the two would defeat the in-editor / audit alignment promise.
+ */
+const VARIANT_CATALOGUE_RULES = [
+    {
+        // Hardcoded route strings — use ROUTES.* constants.
+        selector: "Literal[value=/^\\/[a-z]+(\\?|#|$)/]",
+        message: "Use ROUTES.* constants from @mohasinac/appkit instead of hardcoded route strings.",
+    },
+    {
+        // Raw <div className=…> — use <Div>/<Stack>/<Row>/<Container>/<Section>.
+        selector: "JSXOpeningElement[name.name='div'] > JSXAttribute[name.name='className']",
+        message: "Variant catalogue: raw <div className=…> bypasses the primitive surface. Use <Div surface=… padding=…>, <Stack>, <Row>, <Container>, or <Section> from @mohasinac/appkit.",
+    },
+    {
+        // Raw <span className=…> — use <Span color=… size=… weight=…>.
+        selector: "JSXOpeningElement[name.name='span'] > JSXAttribute[name.name='className']",
+        message: "Variant catalogue: raw <span className=…> bypasses Typography. Use <Span color=… size=… weight=…> from @mohasinac/appkit.",
+    },
+    {
+        // Raw <button>.
+        selector: "JSXOpeningElement[name.name='button']",
+        message: "Variant catalogue: raw <button> bypasses the action registry. Use <Button variant=…> / <IconButton> from @mohasinac/appkit, or <Toggle> for switch UIs.",
+    },
+    {
+        // Raw <a>.
+        selector: "JSXOpeningElement[name.name='a']",
+        message: "Variant catalogue: raw <a> bypasses internal-route + external-URL handling. Use <TextLink> for internal Next.js routes or <Anchor> for external/mailto/tel.",
+    },
+    {
+        // Raw <img>.
+        selector: "JSXOpeningElement[name.name='img']",
+        message: "Variant catalogue: raw <img> bypasses the watermark proxy. Use <MediaImage src=… alt=… size=…> from @mohasinac/appkit.",
+    },
+    {
+        // Raw <input>, <textarea>, <select>, <form>.
+        selector: "JSXOpeningElement[name.name=/^(input|textarea|select|form)$/]",
+        message: "Variant catalogue: raw <input>/<textarea>/<select>/<form> bypasses the form primitives. Use <Form>, <FieldInput>, <FieldTextarea>, <FieldSelect> from @mohasinac/appkit.",
+    },
+];
 export function defineEslintConfig(override = {}) {
     return [
         {
@@ -23,14 +72,7 @@ export function defineEslintConfig(override = {}) {
         },
         {
             rules: {
-                // Prohibit hardcoded route strings — use ROUTES.* constants
-                "no-restricted-syntax": [
-                    "warn",
-                    {
-                        selector: "Literal[value=/^\\/[a-z]+(\\?|#|$)/]",
-                        message: "Use ROUTES.* constants from @mohasinac/appkit instead of hardcoded route strings.",
-                    },
-                ],
+                "no-restricted-syntax": ["warn", ...VARIANT_CATALOGUE_RULES],
                 ...override.rules,
             },
         },

package/dist/configs/next.d.ts

@@ -1,8 +1,9 @@
+import type { JsonValue } from "@mohasinac/appkit";
 export interface NextConfigOverride {
     serverExternalPackages?: string[];
-    experimental?: Record<string, unknown>;
+    experimental?: Record<string, JsonValue>;
     outputFileTracingIncludes?: Record<string, string[]>;
-    images?: Record<string, unknown>;
+    images?: Record<string, JsonValue>;
     webpack?: (config: unknown, ctx: unknown) => unknown;
     [key: string]: unknown;
 }
@@ -15,7 +16,7 @@ export interface NextConfigOverride {
  * // next.config.js
  * const { defineNextConfig } = require("@mohasinac/appkit/configs");
  * module.exports = defineNextConfig({
- *   images: { domains: ["lh3.googleusercontent.com"] }
+ * images: { domains: ["lh3.googleusercontent.com"] }
  * });
  * ```
  */

package/dist/configs/next.js

@@ -60,7 +60,7 @@ const FIREBASE_EXTERNAL_PACKAGES = [
  * // next.config.js
  * const { defineNextConfig } = require("@mohasinac/appkit/configs");
  * module.exports = defineNextConfig({
- *   images: { domains: ["lh3.googleusercontent.com"] }
+ * images: { domains: ["lh3.googleusercontent.com"] }
  * });
  * ```
  */
@@ -183,8 +183,8 @@ export function defineNextConfig(override = {}) {
             ...patterns.filter((p) => !existing.includes(p)),
         ];
     }
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     function mergedWebpack(config, ctx) {
+        // audit-unknown-ok: Next.js config callback — third-party shape
         const { isServer, webpack } = ctx;
         // Deduplicate firebase client SDK across the monorepo.
         // appkit ships its own node_modules/firebase (from standalone dev). Without

package/dist/configs/tailwind.d.ts

@@ -12,7 +12,7 @@
  * // tailwind.config.js
  * const { defineTailwindConfig } = require("@mohasinac/appkit/configs");
  * module.exports = defineTailwindConfig({
- *   content: ["./src/**\/*.{ts,tsx}"],
+ * content: ["./src/**\/*.{ts,tsx}"],
  * });
  * ```
  */

package/dist/configs/tailwind.js

@@ -12,7 +12,7 @@
  * // tailwind.config.js
  * const { defineTailwindConfig } = require("@mohasinac/appkit/configs");
  * module.exports = defineTailwindConfig({
- *   content: ["./src/**\/*.{ts,tsx}"],
+ * content: ["./src/**\/*.{ts,tsx}"],
  * });
  * ```
  */
@@ -65,6 +65,7 @@ export function defineTailwindConfig(override = {}) {
                         surface: "var(--appkit-color-info-surface)",
                     },
                 },
+                // audit-unknown-ok: Tailwind config — third-party shape, plugins can be functions
                 ...(consumerTheme.extend ?? {}),
             },
             ...Object.fromEntries(Object.entries(consumerTheme).filter(([k]) => k !== "extend")),

package/dist/constants/api-endpoint-resolver.d.ts

@@ -25,9 +25,9 @@ export declare function resolveEndpoint(defaultEndpoint: string, override?: stri
  * @example
  * ```ts
  * const url = resolveEndpointFn(
- *   API_ENDPOINTS.ACCOUNT.BY_ID,
- *   userId,
- *   options?.accountEndpoint,
+ * API_ENDPOINTS.ACCOUNT.BY_ID,
+ * userId,
+ * options?.accountEndpoint,
  * );
  * ```
  */