@mohasinac/appkit 2.8.9 → 3.0.0

package/dist/errors/error-mapping.js

@@ -0,0 +1,213 @@
+import { AppError } from "./base-error";
+import { ApiError } from "./api-error";
+import { ValidationError } from "./validation-error";
+import { AuthenticationError } from "./authentication-error";
+import { AuthorizationError } from "./authorization-error";
+import { NotFoundError } from "./not-found-error";
+import { DatabaseError } from "./database-error";
+/**
+ * Codes emitted by the wire that are not present in the AppError-class enums.
+ * Added so the client display map and i18n keys can resolve them.
+ */
+export const HTTP_ERROR_CODES = {
+    VALIDATION_FAILED: "VALIDATION_FAILED",
+    UNAUTHENTICATED: "UNAUTHENTICATED",
+    FORBIDDEN: "FORBIDDEN",
+    PERMISSION_DENIED: "PERMISSION_DENIED",
+    NOT_FOUND: "NOT_FOUND",
+    ALREADY_EXISTS: "ALREADY_EXISTS",
+    RATE_LIMITED: "RATE_LIMITED",
+    PRECONDITION_FAILED: "PRECONDITION_FAILED",
+    CONCURRENT_MODIFICATION: "CONCURRENT_MODIFICATION",
+    INTERNAL: "INTERNAL",
+    UNAVAILABLE: "UNAVAILABLE",
+    UPSTREAM_UNAVAILABLE: "UPSTREAM_UNAVAILABLE",
+    NETWORK_ERROR: "NETWORK_ERROR",
+    REQUEST_TIMEOUT: "REQUEST_TIMEOUT",
+    DEGRADED_READ: "DEGRADED_READ",
+    PAYMENT_ROLLBACK_ATTEMPTED: "PAYMENT_ROLLBACK_ATTEMPTED",
+    PAYMENT_ROLLBACK_FAILED: "PAYMENT_ROLLBACK_FAILED",
+    VERIFICATION_EMAIL_FAILED: "VERIFICATION_EMAIL_FAILED",
+    CONFIRMATION_EMAIL_FAILED: "CONFIRMATION_EMAIL_FAILED",
+    CLIENT_BOUNDARY: "CLIENT_BOUNDARY",
+    CLIENT_PROMISE_REJECTION: "CLIENT_PROMISE_REJECTION",
+    CLIENT_WINDOW_ERROR: "CLIENT_WINDOW_ERROR",
+    CLIENT_UNHANDLED: "CLIENT_UNHANDLED",
+};
+// audit-unknown-ok: type-narrowing entry point — accepts any value, narrows by typeof/Array.isArray
+function isZodLikeError(err) {
+    return (typeof err === "object" &&
+        err !== null &&
+        "issues" in err &&
+        Array.isArray(err.issues));
+}
+// audit-unknown-ok: type-narrowing entry point — accepts any value, narrows by typeof/Array.isArray
+function isFirestoreLikeError(err) {
+    if (typeof err !== "object" || err === null)
+        return false;
+    const codeVal = err.code;
+    return typeof codeVal === "number" || typeof codeVal === "string";
+}
+const FIRESTORE_NUMERIC_MAP = {
+    5: { status: 404, code: HTTP_ERROR_CODES.NOT_FOUND },
+    6: { status: 409, code: HTTP_ERROR_CODES.ALREADY_EXISTS },
+    7: { status: 403, code: HTTP_ERROR_CODES.PERMISSION_DENIED },
+    8: { status: 429, code: HTTP_ERROR_CODES.RATE_LIMITED },
+    9: { status: 409, code: HTTP_ERROR_CODES.PRECONDITION_FAILED },
+    10: { status: 409, code: HTTP_ERROR_CODES.CONCURRENT_MODIFICATION },
+    13: { status: 500, code: HTTP_ERROR_CODES.INTERNAL },
+    14: { status: 503, code: HTTP_ERROR_CODES.UNAVAILABLE },
+    16: { status: 401, code: HTTP_ERROR_CODES.UNAUTHENTICATED },
+};
+const FIRESTORE_STRING_MAP = {
+    "not-found": { status: 404, code: HTTP_ERROR_CODES.NOT_FOUND },
+    "already-exists": { status: 409, code: HTTP_ERROR_CODES.ALREADY_EXISTS },
+    "permission-denied": {
+        status: 403,
+        code: HTTP_ERROR_CODES.PERMISSION_DENIED,
+    },
+    "resource-exhausted": { status: 429, code: HTTP_ERROR_CODES.RATE_LIMITED },
+    "failed-precondition": {
+        status: 409,
+        code: HTTP_ERROR_CODES.PRECONDITION_FAILED,
+    },
+    aborted: { status: 409, code: HTTP_ERROR_CODES.CONCURRENT_MODIFICATION },
+    internal: { status: 500, code: HTTP_ERROR_CODES.INTERNAL },
+    unavailable: { status: 503, code: HTTP_ERROR_CODES.UNAVAILABLE },
+    unauthenticated: { status: 401, code: HTTP_ERROR_CODES.UNAUTHENTICATED },
+};
+function mapFirestore(err) {
+    const numeric = typeof err.code === "number" ? FIRESTORE_NUMERIC_MAP[err.code] : undefined;
+    const stringy = typeof err.code === "string" ? FIRESTORE_STRING_MAP[err.code] : undefined;
+    const mapped = numeric ?? stringy;
+    if (!mapped)
+        return null;
+    return {
+        status: mapped.status,
+        code: mapped.code,
+        message: err.message ?? mapped.code,
+    };
+}
+/**
+ * Map any thrown value to a stable HTTP error envelope shape.
+ *
+ * Order of precedence:
+ *  - AppError subclasses use their declared statusCode + code
+ *  - DatabaseError unwraps its `data` to look for a wrapped FirestoreError
+ *  - FirestoreError (numeric .code or string .code) maps via the table above
+ *  - ZodError shape maps to 400 VALIDATION_FAILED + issues
+ *  - Unknown Error → 500 INTERNAL; message scrubbed when isProduction
+ */
+export function mapToHttpError(
+// audit-unknown-ok: error-handler entry point — accepts thrown values of any shape
+err, opts) {
+    const isProduction = opts?.isProduction ?? false;
+    // AppError subclasses first — they carry status + code authoritatively
+    if (err instanceof ValidationError) {
+        return {
+            status: 400,
+            code: HTTP_ERROR_CODES.VALIDATION_FAILED,
+            message: err.message,
+            issues: isZodLikeError(err.data) ? err.data.issues : undefined,
+        };
+    }
+    if (err instanceof AuthenticationError) {
+        return {
+            status: 401,
+            code: HTTP_ERROR_CODES.UNAUTHENTICATED,
+            message: err.message,
+        };
+    }
+    if (err instanceof AuthorizationError) {
+        return {
+            status: 403,
+            code: HTTP_ERROR_CODES.FORBIDDEN,
+            message: err.message,
+        };
+    }
+    if (err instanceof NotFoundError) {
+        return {
+            status: 404,
+            code: HTTP_ERROR_CODES.NOT_FOUND,
+            message: err.message,
+        };
+    }
+    if (err instanceof DatabaseError) {
+        // DatabaseError typically wraps an underlying Firestore error in `data`
+        if (isFirestoreLikeError(err.data)) {
+            const mapped = mapFirestore(err.data);
+            if (mapped)
+                return { ...mapped, message: err.message };
+        }
+        return {
+            status: err.statusCode || 500,
+            code: err.code || HTTP_ERROR_CODES.INTERNAL,
+            message: err.message,
+        };
+    }
+    if (err instanceof ApiError) {
+        return {
+            status: err.statusCode,
+            code: err.code,
+            message: err.message,
+        };
+    }
+    if (err instanceof AppError) {
+        return {
+            status: err.statusCode,
+            code: err.code,
+            message: err.message,
+        };
+    }
+    // Bare FirestoreError (thrown without DatabaseError wrap)
+    if (isFirestoreLikeError(err)) {
+        const mapped = mapFirestore(err);
+        if (mapped)
+            return mapped;
+    }
+    // Zod error (thrown without ValidationError wrap)
+    if (isZodLikeError(err)) {
+        return {
+            status: 400,
+            code: HTTP_ERROR_CODES.VALIDATION_FAILED,
+            message: "Validation failed",
+            issues: err.issues,
+        };
+    }
+    // Object with explicit { status, message } shape (legacy throw-with-status)
+    if (typeof err === "object" && err !== null) {
+        // audit-unknown-ok: error-shape predicates (isZodLikeError, etc.) — TS requires unknown for type-guard params
+        const e = err;
+        const status = typeof e.statusCode === "number"
+            ? e.statusCode
+            : typeof e.status === "number"
+                ? e.status
+                : null;
+        if (status !== null) {
+            return {
+                status,
+                code: status === 401
+                    ? HTTP_ERROR_CODES.UNAUTHENTICATED
+                    : status === 403
+                        ? HTTP_ERROR_CODES.FORBIDDEN
+                        : status === 404
+                            ? HTTP_ERROR_CODES.NOT_FOUND
+                            : status >= 500
+                                ? HTTP_ERROR_CODES.INTERNAL
+                                : HTTP_ERROR_CODES.VALIDATION_FAILED,
+                message: typeof e.message === "string" ? e.message : "An error occurred",
+            };
+        }
+    }
+    // Unknown — keep message in dev, scrub in prod
+    const rawMessage = err instanceof Error
+        ? err.message
+        : typeof err === "string"
+            ? err
+            : "An internal error occurred";
+    return {
+        status: 500,
+        code: HTTP_ERROR_CODES.INTERNAL,
+        message: isProduction ? "An internal error occurred" : rawMessage,
+    };
+}

package/dist/errors/index.d.ts

@@ -8,4 +8,10 @@ export { AuthenticationError } from "./authentication-error";
 export { AuthorizationError } from "./authorization-error";
 export { NotFoundError } from "./not-found-error";
 export { DatabaseError } from "./database-error";
+export { RazorpayUnreachableError } from "./razorpay-unreachable";
 export { handleApiError, logError, isAppError } from "./error-handler";
+export { mapToHttpError, HTTP_ERROR_CODES, type MappedError, type HttpErrorCode, } from "./error-mapping";
+export { ERROR_DISPLAY_MAP, getErrorDisplay, type ErrorDisplayEntry, } from "./error-display-map";
+export { safeRead, installDegradedReadReporter, type DegradedReadReport, } from "./safe-read";
+export { normalizeError, getErrorMessage, isAuthError, isApiNormalized, isAppNormalized, isFirebaseAuthNormalized, isFirebaseFirestoreNormalized, isFirebaseStorageNormalized, isNativeNormalized, isNetworkNormalized, isUnknownNormalized, isZodNormalized, } from "./normalize";
+export type { NormalizedError, NormalizedApiError, NormalizedAppError, NormalizedFirebaseAuthError, NormalizedFirebaseFirestoreError, NormalizedFirebaseStorageError, NormalizedNativeError, NormalizedNetworkError, NormalizedUnknownThrownValue, NormalizedZodError, } from "./normalize";

package/dist/errors/index.js

@@ -11,5 +11,16 @@ export { AuthenticationError } from "./authentication-error";
 export { AuthorizationError } from "./authorization-error";
 export { NotFoundError } from "./not-found-error";
 export { DatabaseError } from "./database-error";
+export { RazorpayUnreachableError } from "./razorpay-unreachable";
 // error-handler uses `next/server` — only import in server/API-route contexts
 export { handleApiError, logError, isAppError } from "./error-handler";
+// Code→HTTP mapper (server) — and the i18n / inline-field map (client-safe)
+export { mapToHttpError, HTTP_ERROR_CODES, } from "./error-mapping";
+export { ERROR_DISPLAY_MAP, getErrorDisplay, } from "./error-display-map";
+// safeRead is server-only (uses the persisted log reporter)
+export { safeRead, installDegradedReadReporter, } from "./safe-read";
+// W3 — catch-clause normalizer. Every catch (e: unknown) funnels through
+// normalizeError(e) which returns a NormalizedError discriminated union.
+// `isAuthError` here replaces the legacy keyword matcher at
+// `appkit/src/utils/auth-error.ts` (now a thin re-export shim).
+export { normalizeError, getErrorMessage, isAuthError, isApiNormalized, isAppNormalized, isFirebaseAuthNormalized, isFirebaseFirestoreNormalized, isFirebaseStorageNormalized, isNativeNormalized, isNetworkNormalized, isUnknownNormalized, isZodNormalized, } from "./normalize";

package/dist/errors/normalize.d.ts

@@ -0,0 +1,81 @@
+import { ZodError } from "zod";
+import { ApiError } from "../client/api/ApiError";
+import { AppError } from "./base-error";
+export interface NormalizedZodError {
+    readonly kind: "zod";
+    readonly code: "VALIDATION_FAILED";
+    readonly message: string;
+    readonly issues: ReadonlyArray<{
+        readonly path: ReadonlyArray<string | number>;
+        readonly code: string;
+        readonly message: string;
+    }>;
+    readonly cause: ZodError;
+}
+export interface NormalizedApiError {
+    readonly kind: "api";
+    readonly code: string;
+    readonly status: number;
+    readonly message: string;
+    readonly issues?: ReadonlyArray<unknown>;
+    readonly requestId?: string;
+    readonly cause: ApiError;
+}
+export interface NormalizedAppError {
+    readonly kind: "app";
+    readonly code: string;
+    readonly status: number;
+    readonly message: string;
+    readonly data?: unknown;
+    readonly cause: AppError;
+}
+export interface NormalizedFirebaseAuthError {
+    readonly kind: "firebase-auth";
+    readonly code: string;
+    readonly message: string;
+    readonly cause: Error;
+}
+export interface NormalizedFirebaseFirestoreError {
+    readonly kind: "firebase-firestore";
+    readonly code: string;
+    readonly message: string;
+    readonly cause: Error;
+}
+export interface NormalizedFirebaseStorageError {
+    readonly kind: "firebase-storage";
+    readonly code: string;
+    readonly message: string;
+    readonly cause: Error;
+}
+export interface NormalizedNetworkError {
+    readonly kind: "network";
+    readonly code: "NETWORK_FAILURE";
+    readonly message: string;
+    readonly cause: Error;
+}
+export interface NormalizedNativeError {
+    readonly kind: "native";
+    readonly code: string;
+    readonly message: string;
+    readonly stack?: string;
+    readonly cause: Error;
+}
+export interface NormalizedUnknownThrownValue {
+    readonly kind: "unknown";
+    readonly code: "UNKNOWN_THROWN_VALUE";
+    readonly message: string;
+    readonly value: string;
+}
+export type NormalizedError = NormalizedZodError | NormalizedApiError | NormalizedAppError | NormalizedFirebaseAuthError | NormalizedFirebaseFirestoreError | NormalizedFirebaseStorageError | NormalizedNetworkError | NormalizedNativeError | NormalizedUnknownThrownValue;
+export declare const isZodNormalized: (e: NormalizedError) => e is NormalizedZodError;
+export declare const isApiNormalized: (e: NormalizedError) => e is NormalizedApiError;
+export declare const isAppNormalized: (e: NormalizedError) => e is NormalizedAppError;
+export declare const isFirebaseAuthNormalized: (e: NormalizedError) => e is NormalizedFirebaseAuthError;
+export declare const isFirebaseFirestoreNormalized: (e: NormalizedError) => e is NormalizedFirebaseFirestoreError;
+export declare const isFirebaseStorageNormalized: (e: NormalizedError) => e is NormalizedFirebaseStorageError;
+export declare const isNetworkNormalized: (e: NormalizedError) => e is NormalizedNetworkError;
+export declare const isNativeNormalized: (e: NormalizedError) => e is NormalizedNativeError;
+export declare const isUnknownNormalized: (e: NormalizedError) => e is NormalizedUnknownThrownValue;
+export declare function normalizeError(e: unknown): NormalizedError;
+export declare function getErrorMessage(e: unknown): string;
+export declare function isAuthError(e: unknown, httpStatus?: number): boolean;

package/dist/errors/normalize.js

@@ -0,0 +1,206 @@
+// [SERVER-OR-CLIENT] Catch-clause normalizer (W3).
+//
+// Every `catch (e: unknown)` in the codebase funnels through `normalizeError`
+// to convert the unknown thrown value into a typed `NormalizedError`
+// discriminated union. After the call, the catch site never holds `unknown`
+// — every branch is type-safe.
+//
+// `audit-catch-normalize.mjs` enforces that every catch block calls
+// `normalizeError(e)` (or returns/throws) on its first non-comment statement.
+//
+// Naming note: appkit already has a class named `AppError` exported from
+// `./base-error`. We use `NormalizedError` here to avoid conflict; both
+// represent the same intent (typed error envelope) but `AppError` is a
+// throwable class while `NormalizedError` is the result of catching one.
+import { ZodError } from "zod";
+import { ApiError } from "../client/api/ApiError";
+import { AppError } from "./base-error";
+// ---------------------------------------------------------------------------
+// Type guards on the discriminator.
+// ---------------------------------------------------------------------------
+export const isZodNormalized = (e) => e.kind === "zod";
+export const isApiNormalized = (e) => e.kind === "api";
+export const isAppNormalized = (e) => e.kind === "app";
+export const isFirebaseAuthNormalized = (e) => e.kind === "firebase-auth";
+export const isFirebaseFirestoreNormalized = (e) => e.kind === "firebase-firestore";
+export const isFirebaseStorageNormalized = (e) => e.kind === "firebase-storage";
+export const isNetworkNormalized = (e) => e.kind === "network";
+export const isNativeNormalized = (e) => e.kind === "native";
+export const isUnknownNormalized = (e) => e.kind === "unknown";
+// ---------------------------------------------------------------------------
+// Probes — narrow heuristics for upstream library shapes.
+// ---------------------------------------------------------------------------
+function hasStringProp(value, key) {
+    return typeof value === "object" && value !== null && typeof value[key] === "string";
+}
+function isFirebaseAuthErrorShape(e) {
+    if (!hasStringProp(e, "code"))
+        return false;
+    // audit-unknown-ok: TS structural escape — CodedError
+    return e.code.startsWith("auth/");
+}
+function isFirebaseStorageErrorShape(e) {
+    if (!hasStringProp(e, "code"))
+        return false;
+    // audit-unknown-ok: TS structural escape — CodedError
+    return e.code.startsWith("storage/");
+}
+function isFirebaseFirestoreErrorShape(e) {
+    if (!hasStringProp(e, "code"))
+        return false;
+    // audit-unknown-ok: TS structural escape — CodedError
+    const code = e.code;
+    // Firestore codes are bare strings: "permission-denied", "not-found", etc.
+    return (/^[a-z-]+$/.test(code) &&
+        [
+            "cancelled",
+            "unknown",
+            "invalid-argument",
+            "deadline-exceeded",
+            "not-found",
+            "already-exists",
+            "permission-denied",
+            "resource-exhausted",
+            "failed-precondition",
+            "aborted",
+            "out-of-range",
+            "unimplemented",
+            "internal",
+            "unavailable",
+            "data-loss",
+            "unauthenticated",
+        ].includes(code));
+}
+function isNetworkErrorShape(e) {
+    // The browser fetch API throws `TypeError("Failed to fetch")` on network
+    // failure. Node's `undici` throws `TypeError("fetch failed")`.
+    return (e.name === "TypeError" &&
+        (e.message.toLowerCase().includes("fetch") || e.message.toLowerCase().includes("network")));
+}
+// ---------------------------------------------------------------------------
+// normalizeError — the single funnel for every `catch (e: unknown)`.
+// ---------------------------------------------------------------------------
+// audit-unknown-ok: type-narrowing entry point — accepts any value, narrows by typeof/Array.isArray
+export function normalizeError(e) {
+    // ApiError (client-side API failure with stable code + status).
+    if (e instanceof ApiError) {
+        return {
+            kind: "api",
+            code: e.code,
+            status: e.status,
+            message: e.message,
+            issues: e.issues,
+            requestId: e.requestId,
+            cause: e,
+        };
+    }
+    // AppError (server-side throwable with status + code).
+    if (e instanceof AppError) {
+        return {
+            kind: "app",
+            code: e.code,
+            status: e.statusCode,
+            message: e.message,
+            data: e.data,
+            cause: e,
+        };
+    }
+    // Zod validation failures.
+    if (e instanceof ZodError) {
+        return {
+            kind: "zod",
+            code: "VALIDATION_FAILED",
+            message: e.message,
+            issues: e.issues.map((i) => ({
+                path: i.path,
+                code: i.code,
+                message: i.message,
+            })),
+            cause: e,
+        };
+    }
+    // Native Error subclasses — probe for Firebase / network before falling
+    // through to generic "native".
+    if (e instanceof Error) {
+        if (isFirebaseAuthErrorShape(e)) {
+            return {
+                kind: "firebase-auth",
+                code: e.code,
+                message: e.message,
+                cause: e,
+            };
+        }
+        if (isFirebaseStorageErrorShape(e)) {
+            return {
+                kind: "firebase-storage",
+                code: e.code,
+                message: e.message,
+                cause: e,
+            };
+        }
+        if (isFirebaseFirestoreErrorShape(e)) {
+            return {
+                kind: "firebase-firestore",
+                code: e.code,
+                message: e.message,
+                cause: e,
+            };
+        }
+        if (isNetworkErrorShape(e)) {
+            return {
+                kind: "network",
+                code: "NETWORK_FAILURE",
+                message: e.message,
+                cause: e,
+            };
+        }
+        return {
+            kind: "native",
+            code: e.name || "UNKNOWN_ERROR",
+            message: e.message,
+            stack: e.stack,
+            cause: e,
+        };
+    }
+    // Non-Error thrown value — last resort.
+    const value = String(e);
+    return {
+        kind: "unknown",
+        code: "UNKNOWN_THROWN_VALUE",
+        message: value,
+        value,
+    };
+}
+// ---------------------------------------------------------------------------
+// getErrorMessage — convenience for catch sites that just want a string.
+// Always prefer `normalizeError(e).message` for new code; this is a tiny
+// shortcut for legacy migrations.
+// ---------------------------------------------------------------------------
+export function getErrorMessage(e) {
+    return normalizeError(e).message;
+}
+// ---------------------------------------------------------------------------
+// isAuthError — replacement for the legacy `appkit/src/utils/auth-error.ts`
+// keyword matcher. Uses the normalized error to decide if the failure is
+// an auth/authorization failure (401, 403, Firebase auth/*, or `kind: "api"`
+// with status 401/403).
+// ---------------------------------------------------------------------------
+export function isAuthError(e, httpStatus) {
+    if (httpStatus === 401 || httpStatus === 403)
+        return true;
+    const ne = normalizeError(e);
+    if (ne.kind === "api" && (ne.status === 401 || ne.status === 403))
+        return true;
+    if (ne.kind === "app" && (ne.status === 401 || ne.status === 403))
+        return true;
+    if (ne.kind === "firebase-auth")
+        return true;
+    // Keyword fallback retained for legacy server-side string errors. To be
+    // removed once all server actions throw typed errors.
+    const msg = ne.message.toLowerCase();
+    return (msg.includes("unauthorized") ||
+        msg.includes("not authenticated") ||
+        msg.includes("unauthenticated") ||
+        msg.includes("authentication required") ||
+        msg.includes("invalid or expired session"));
+}

package/dist/errors/not-found-error.js

@@ -1,5 +1,6 @@
 import { AppError } from "./base-error";
 export class NotFoundError extends AppError {
+    // audit-unknown-ok: NotFoundError data
     constructor(message, data) {
         super(404, message, "NOT_FOUND", data);
     }

package/dist/errors/razorpay-unreachable.d.ts

@@ -0,0 +1,4 @@
+import { AppError } from "./base-error";
+export declare class RazorpayUnreachableError extends AppError {
+    constructor(message?: string, data?: unknown);
+}

package/dist/errors/razorpay-unreachable.js

@@ -0,0 +1,7 @@
+import { AppError } from "./base-error";
+export class RazorpayUnreachableError extends AppError {
+    // audit-unknown-ok: RazorpayUnreachable data
+    constructor(message = "Payment provider unreachable", data) {
+        super(503, message, "UPSTREAM_UNAVAILABLE", data);
+    }
+}

package/dist/errors/safe-read.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Hook that downstream consumers (the persisted-log path) register so safeRead
+ * can record degraded reads without taking a hard dependency on the repository.
+ * Default is a no-op so calling safeRead before the reporter is installed
+ * does not crash.
+ */
+export interface DegradedReadReport {
+    route: string;
+    key: string;
+    code: string;
+    message: string;
+    stack?: string;
+}
+type DegradedReadReporter = (report: DegradedReadReport) => void | Promise<void>;
+export declare function installDegradedReadReporter(fn: DegradedReadReporter): void;
+interface SafeReadOptions<T> {
+    /** Used as the `route` field on the persisted degraded-read entry. */
+    route: string;
+    /** Stable identifier for the read site (e.g. "homepage:hero-rail"). */
+    key: string;
+    /**
+     * Typed fallback returned when the read fails. The intent of the original
+     * silent catch is preserved — but the failure is no longer invisible.
+     */
+    fallback: T;
+}
+/**
+ * Wrap an optional read whose failure must not break the surrounding page.
+ *
+ * Required-data reads should NOT use this — they should throw and be caught
+ * by the route handler / server action envelope (mapToHttpError).
+ *
+ * On failure: persists a DEGRADED_READ row via the installed reporter and
+ * returns `opts.fallback`. Never re-throws.
+ */
+export declare function safeRead<T>(fn: () => Promise<T>, opts: SafeReadOptions<T>): Promise<T>;
+export {};

package/dist/errors/safe-read.js

@@ -0,0 +1,39 @@
+import { normalizeError } from "./normalize";
+import { mapToHttpError } from "./error-mapping";
+let reporter = () => {
+    /* installed at server boot by the server-errors repository wiring */
+};
+export function installDegradedReadReporter(fn) {
+    reporter = fn;
+}
+/**
+ * Wrap an optional read whose failure must not break the surrounding page.
+ *
+ * Required-data reads should NOT use this — they should throw and be caught
+ * by the route handler / server action envelope (mapToHttpError).
+ *
+ * On failure: persists a DEGRADED_READ row via the installed reporter and
+ * returns `opts.fallback`. Never re-throws.
+ */
+export async function safeRead(fn, opts) {
+    try {
+        return await fn();
+    }
+    catch (err) {
+        void normalizeError(err);
+        const mapped = mapToHttpError(err);
+        try {
+            await reporter({
+                route: opts.route,
+                key: opts.key,
+                code: "DEGRADED_READ",
+                message: mapped.message,
+                stack: err instanceof Error ? err.stack : undefined,
+            });
+        }
+        catch {
+            // reporter itself must never propagate; safeRead is a safety net.
+        }
+        return opts.fallback;
+    }
+}

package/dist/errors/validation-error.js

@@ -1,5 +1,6 @@
 import { AppError } from "./base-error";
 export class ValidationError extends AppError {
+    // audit-unknown-ok: ValidationError issues from Zod
     constructor(message, fields) {
         super(400, message, "VALIDATION_ERROR", fields);
     }

package/dist/features/_guide-cls.js

@@ -10,5 +10,5 @@ export const GC = {
     textMuted: "text-sm text-[var(--appkit-color-text-muted)]",
     textStrong: "text-[var(--appkit-color-text)]",
     code: "text-xs bg-[var(--appkit-color-border)] px-1 py-0.5 rounded",
-    pageHeaderGradient: "linear-gradient(135deg,var(--appkit-color-primary-700,#4f46e5) 0%,var(--appkit-color-cobalt,#2563eb) 100%)",
+    pageHeaderGradient: "linear-gradient(135deg,var(--appkit-color-primary-700) 0%,var(--appkit-color-cobalt) 100%)",
 };

package/dist/features/about/components/AboutView.d.ts

@@ -3,7 +3,7 @@ export interface AboutHowItem {
     title: string;
     text: string;
     icon: string;
-    color?: string;
+    tone?: "indigo" | "teal" | "amber" | "rose";
 }
 export interface AboutValueItem {
     title: string;
@@ -30,9 +30,8 @@ export interface AboutViewProps {
     howItems?: AboutHowItem[];
     valueItems?: AboutValueItem[];
     milestones?: AboutMilestone[];
-    heroBannerClass?: string;
     ctaBannerClass?: string;
     /** Render the CTA action buttons  */
     renderCtaButtons?: () => React.ReactNode;
 }
-export declare function AboutView({ labels, howItems, valueItems, milestones, heroBannerClass, ctaBannerClass, renderCtaButtons, }: AboutViewProps): import("react/jsx-runtime").JSX.Element;
+export declare function AboutView({ labels, howItems, valueItems, milestones, ctaBannerClass, renderCtaButtons, }: AboutViewProps): import("react/jsx-runtime").JSX.Element;