@mohasinac/appkit 4.30.16 → 4.30.17

package/dist/_internal/shared/types/action-error-reporter.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Registration seam for recording server-action failures.
+ *
+ * WHY A HOOK AND NOT A DIRECT IMPORT
+ *   `wrapAction` lives in `_internal/shared/`, and the module that hosts it also
+ *   exports `isOk` / `unwrap` — type guards that CLIENT components import. A
+ *   static `serverErrorsRepository` import there would drag `firebase-admin`
+ *   into the client bundle graph, which is exactly the Turbopack trap in
+ *   CLAUDE.md Root Cause #6. So the recorder is injected from the server side
+ *   instead, and this module stays dependency-free.
+ *
+ * WHERE IT IS REGISTERED
+ *   `src/instrumentation.ts` — server-only and guaranteed to be loaded by
+ *   Next.js. Deliberately NOT a client bootstrap component: `setErrorTracker`
+ *   was registered that way, the component it lived in was orphaned during a
+ *   refactor, and every error boundary silently lost its digest for months
+ *   (CLAUDE.md Root Cause #78). A registration nothing imports is invisible to
+ *   `tsc`, so `audit-observability-registration.mjs` asserts both hooks keep a
+ *   reachable call site.
+ */
+export interface ActionErrorReport {
+    /** Stable error code from the mapped envelope. */
+    code: string;
+    /** The UNSCRUBBED message — never the client-facing one. */
+    message: string;
+    /** Wrapper stack. Begins at the wrap site; see `cause`. */
+    stack?: string;
+    /** Flattened `Error.cause` chain — where the real frames live. */
+    cause?: string;
+}
+export type ActionErrorReporter = (report: ActionErrorReport) => void;
+export declare function setActionErrorReporter(fn: ActionErrorReporter): void;
+/**
+ * Report a server-action failure. Never throws and never awaits — the caller is
+ * already on a failure path and must not be made slower or more fragile by
+ * observability.
+ */
+export declare function reportActionError(report: ActionErrorReport): void;
+/** Test/introspection helper — true once a reporter has been installed. */
+export declare function hasActionErrorReporter(): boolean;

package/dist/_internal/shared/types/action-error-reporter.js

@@ -0,0 +1,27 @@
+import { normalizeError } from "../../../errors/normalize";
+let reporter = null;
+export function setActionErrorReporter(fn) {
+    reporter = fn;
+}
+/**
+ * Report a server-action failure. Never throws and never awaits — the caller is
+ * already on a failure path and must not be made slower or more fragile by
+ * observability.
+ */
+export function reportActionError(report) {
+    if (!reporter)
+        return;
+    try {
+        reporter(report);
+        // This IS the error-reporting path. A reporter that throws must not turn a
+        // handled action failure into an unhandled one, and there is nowhere left
+        // to escalate to — the thing that would have reported it is what failed.
+    }
+    catch (reporterErr) {
+        void normalizeError(reporterErr);
+    }
+}
+/** Test/introspection helper — true once a reporter has been installed. */
+export function hasActionErrorReporter() {
+    return reporter !== null;
+}

package/dist/_internal/shared/types/action-result.d.ts

@@ -36,6 +36,16 @@ export type ActionResult<T> = {
  * ```
  *
  * `wrapAction` itself never throws. Callers can rely on the returned envelope.
+ *
+ * 🛑 BECAUSE it never throws, it is also the ONLY thing that will ever see the
+ * failure. Next.js calls `onRequestError` only for errors that ESCAPE a server
+ * action; converting the throw into a return value means that hook never fires.
+ * This catch used to be `void normalizeError(err)` — a pure classifier whose
+ * result is discarded — and then a return: no log, no store, no rethrow. All
+ * 222 server actions in this codebase (68 in appkit, 154 in the consumer) were
+ * therefore completely unobserved, which is why the bid failure this was
+ * written for had to be reported from a screenshot. Anything added here must
+ * keep recording; silence is the bug.
  */
 export declare function wrapAction<T>(fn: () => Promise<T>): Promise<ActionResult<T>>;
 /** Type guard for ActionResult success arm. */

package/dist/_internal/shared/types/action-result.js

@@ -1,5 +1,7 @@
 import { normalizeError } from "../../../errors/normalize";
 import { mapToHttpError } from "../../../errors/error-mapping";
+import { describeCauseChain } from "../../../errors/describe-cause";
+import { reportActionError } from "./action-error-reporter";
 /**
  * Wrap a server-action body so any thrown error is converted into the
  * standard `{ ok: false, code, error, issues? }` envelope via `mapToHttpError`.
@@ -16,6 +18,16 @@ import { mapToHttpError } from "../../../errors/error-mapping";
  * ```
  *
  * `wrapAction` itself never throws. Callers can rely on the returned envelope.
+ *
+ * 🛑 BECAUSE it never throws, it is also the ONLY thing that will ever see the
+ * failure. Next.js calls `onRequestError` only for errors that ESCAPE a server
+ * action; converting the throw into a return value means that hook never fires.
+ * This catch used to be `void normalizeError(err)` — a pure classifier whose
+ * result is discarded — and then a return: no log, no store, no rethrow. All
+ * 222 server actions in this codebase (68 in appkit, 154 in the consumer) were
+ * therefore completely unobserved, which is why the bid failure this was
+ * written for had to be reported from a screenshot. Anything added here must
+ * keep recording; silence is the bug.
  */
 export async function wrapAction(fn) {
     try {
@@ -27,6 +39,20 @@ export async function wrapAction(fn) {
         const mapped = mapToHttpError(err, {
             isProduction: process.env.NODE_ENV === "production",
         });
+        // Record 5xx and datastore-level failures. 4xx business outcomes ("bid too
+        // low", "coupon expired") are the action working correctly and would drown
+        // the store — this is the same threshold createRouteHandler applies.
+        if (mapped.status >= 500 || mapped.infrastructure) {
+            // internalMessage ?? message — `message` is scrubbed for 5xx in
+            // production, and recording the scrubbed copy would defeat the point.
+            const cause = describeCauseChain(err);
+            reportActionError({
+                code: mapped.code,
+                message: mapped.internalMessage ?? mapped.message,
+                stack: err instanceof Error ? err.stack : undefined,
+                ...(cause ? { cause } : {}),
+            });
+        }
         return {
             ok: false,
             code: mapped.code,

package/dist/client/api/surface-error.d.ts

@@ -16,12 +16,14 @@
 export interface SurfaceErrorOptions {
     showToast: (message: string, variant?: "error" | "warning" | "info" | "success" | "loading") => void;
     setFieldError?: (field: string, message: string) => void;
-    /** next-intl style translator. Falls back to the raw error message when undefined. */
+    /**
+     * next-intl style translator. When undefined the chain degrades to
+     * `fallbackMessage` and then to generic copy — NEVER to `err.message`.
+     */
     translate?: (key: string) => string;
     /**
-     * Curated copy preferred over `err.message` when the error carries no
-     * mapped display message. Lets a caller keep wording better than the raw
-     * server string WITHOUT adding a second toast of its own.
+     * Curated copy used when the code resolves to no translation. Must be
+     * authored text; never a value derived from an error object.
      *
      * Never overrides field-level `issues` — those are more specific than any
      * caller-supplied sentence.

package/dist/client/api/surface-error.js

@@ -2,7 +2,8 @@ import { isApiError } from "./ApiError";
 import { ApiClientError } from "../../http/ApiClient";
 import { applyZodIssues, hasAttachableIssue } from "../../ui/forms/apply-zod-issues";
 import { normalizeError } from "../../errors/normalize";
-import { getErrorDisplay } from "../../errors/error-display-map";
+import { getErrorDisplay, toUserMessage } from "../../errors/error-display-map";
+import { HTTP_ERROR_CODES } from "../../errors/error-mapping";
 /** True for `ApiError` instances and for `ApiClientError` (the lower-level
  * error `ApiClient.request()` throws) when it carries a stable `code` —
  * both shapes route through the same toast-vs-inline-field-error logic
@@ -39,7 +40,13 @@ export function surfaceError(err, opts) {
     }
     if (hasStableErrorCode(err)) {
         const display = getErrorDisplay(err.code);
-        const message = translate?.(display.messageKey) ?? fallbackMessage ?? err.message;
+        // `?? err.message` used to terminate this chain. With no `translate` and no
+        // `fallbackMessage` — the shape most call sites use — that surfaced the
+        // SERVER's own message, which for a 5xx is its internals. `toUserMessage`
+        // ends at `errors.codes.UNKNOWN` instead.
+        const message = toUserMessage(err.code, translate, {
+            fallback: fallbackMessage,
+        });
         if (display.field && setFieldError) {
             setFieldError(display.field, message);
             return;
@@ -47,16 +54,20 @@ export function surfaceError(err, opts) {
         showToast(message, "error");
         return;
     }
-    // Non-ApiError — this is a programming error or unhandled exception.
-    // Report it (workstream 13) so clientErrors picks it up.
-    const message = err instanceof Error ? err.message : "Something went wrong. Please try again.";
-    const fallback = fallbackMessage ?? translate?.("errors.codes.CLIENT_UNHANDLED") ?? message;
-    showToast(fallback, "error");
+    // Non-ApiError — a programming error or unhandled exception.
+    //
+    // The raw text is REPORTED (below) but never SHOWN. That split is the point:
+    // this branch is where a raw Node/DOM string arrives, and it used to be
+    // toasted verbatim whenever no translator was supplied.
+    const internalMessage = err instanceof Error ? err.message : String(err ?? "unknown error");
+    showToast(toUserMessage(HTTP_ERROR_CODES.CLIENT_UNHANDLED, translate, {
+        fallback: fallbackMessage,
+    }), "error");
     if (report) {
         try {
             report({
                 code: "CLIENT_UNHANDLED",
-                message,
+                message: internalMessage,
                 stack: err instanceof Error ? err.stack : undefined,
             });
         }

package/dist/contracts/realtime-session.d.ts

@@ -0,0 +1,27 @@
+export interface RealtimeToken {
+    customToken: string;
+    expiresAt: number;
+}
+/**
+ * Ensure the shared realtime app is signed in for `scope`, and take a lease.
+ *
+ * @param scope    an identifier for the claim set (e.g. `"messages"`,
+ *                 `"chat:<id>"`). Signing in again for the SAME scope while a
+ *                 valid token is held is a no-op.
+ * @param getToken fetches a fresh custom token. Called only when needed.
+ * @returns a release function. **Always call it** — the session is only torn
+ *          down when every lease is released.
+ */
+export declare function acquireRealtimeSession(scope: string, getToken: () => Promise<RealtimeToken>): Promise<() => void>;
+/**
+ * Take a lease WITHOUT signing in — for a consumer that manages its own
+ * sign-in but must still participate in the reference count.
+ *
+ * `useRealtimeEvent` is the case: its token carries a job-scoped `bulkJobId`
+ * claim it receives from the caller, so it cannot use `acquireRealtimeSession`'s
+ * fetcher. It still must not be able to sign the shared app out from under
+ * another channel, which is precisely what its `cleanup()` used to do.
+ */
+export declare function acquireExternalRealtimeLease(): () => void;
+/** Test/diagnostic only. */
+export declare function activeRealtimeLeases(): number;

package/dist/contracts/realtime-session.js

@@ -0,0 +1,118 @@
+import { normalizeError } from "../errors/normalize";
+import { getClientRealtimeProvider } from "./client-realtime";
+/**
+ * Shared, REFERENCE-COUNTED sign-in for the one client realtime app.
+ *
+ * WHY THIS EXISTS — two distinct bugs, one cause.
+ *
+ * 1. **Nobody signed in for messaging.** `useConversation` and
+ *    `useConversations` subscribed to `chats/...` without ever calling
+ *    `signInWithToken`, so `auth == null` and both RTDB rules evaluated false.
+ *    Every buyer↔seller live update was permission-denied, and both hooks
+ *    swallowed it (one into `setIsConnected(false)`, one into a literal
+ *    `// ignore`), so the channel looked implemented and was inert. Only
+ *    `useChat` and `useRealtimeEvent` ever authenticated.
+ *
+ * 2. **Signing out is a SHARED action.** `FirebaseClientRealtimeProvider` is
+ *    registered once, as a singleton on the `"letitrip-realtime"` app. So
+ *    `useRealtimeEvent.cleanup()` calling `provider.signOut()` when a bulk job
+ *    finished tore the session out from under an admin chat that was still
+ *    open — and, in reverse, `useChat`'s token (carrying `chatIds`) overwrote a
+ *    bulk token (carrying `bulkJobId`), killing an in-flight job subscription.
+ *    Whoever finished last broke whoever was still working.
+ *
+ * The fix for (2) is not "sign out more carefully" — it is that **no individual
+ * consumer may decide to sign out at all**. Each acquires a lease and releases
+ * it; the session ends only when the last lease is gone.
+ *
+ * Tokens differ per channel (different claims), so `acquire` takes a fetcher and
+ * re-signs when the token it holds is for a different scope or has expired.
+ */
+/** Refresh a little early — a token that expires mid-subscription is a silent drop. */
+const EXPIRY_SKEW_MS = 60000;
+let leases = 0;
+let currentScope = null;
+let expiresAt = 0;
+let inFlight = null;
+/**
+ * Ensure the shared realtime app is signed in for `scope`, and take a lease.
+ *
+ * @param scope    an identifier for the claim set (e.g. `"messages"`,
+ *                 `"chat:<id>"`). Signing in again for the SAME scope while a
+ *                 valid token is held is a no-op.
+ * @param getToken fetches a fresh custom token. Called only when needed.
+ * @returns a release function. **Always call it** — the session is only torn
+ *          down when every lease is released.
+ */
+export async function acquireRealtimeSession(scope, getToken) {
+    const lease = { scope };
+    leases++;
+    const needsSignIn = currentScope !== lease.scope || Date.now() > expiresAt - EXPIRY_SKEW_MS;
+    if (needsSignIn) {
+        // Collapse concurrent acquires — several hooks mount in the same tick and
+        // would otherwise each fetch a token and race to sign in.
+        inFlight ?? (inFlight = (async () => {
+            try {
+                const token = await getToken();
+                await getClientRealtimeProvider().signInWithToken(token.customToken);
+                currentScope = lease.scope;
+                expiresAt = token.expiresAt;
+            }
+            finally {
+                inFlight = null;
+            }
+        })());
+        await inFlight;
+    }
+    let released = false;
+    return () => {
+        if (released)
+            return; // React StrictMode double-invokes cleanups
+        released = true;
+        leases = Math.max(0, leases - 1);
+        if (leases > 0)
+            return;
+        currentScope = null;
+        expiresAt = 0;
+        getClientRealtimeProvider()
+            .signOut()
+            .catch((err) => {
+            void normalizeError(err);
+        });
+    };
+}
+/**
+ * Take a lease WITHOUT signing in — for a consumer that manages its own
+ * sign-in but must still participate in the reference count.
+ *
+ * `useRealtimeEvent` is the case: its token carries a job-scoped `bulkJobId`
+ * claim it receives from the caller, so it cannot use `acquireRealtimeSession`'s
+ * fetcher. It still must not be able to sign the shared app out from under
+ * another channel, which is precisely what its `cleanup()` used to do.
+ */
+export function acquireExternalRealtimeLease() {
+    leases++;
+    // Its own sign-in has replaced whatever scope was active; forget the cached
+    // one so the next acquire() re-authenticates rather than trusting a token
+    // that is no longer installed.
+    currentScope = null;
+    expiresAt = 0;
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        leases = Math.max(0, leases - 1);
+        if (leases > 0)
+            return;
+        getClientRealtimeProvider()
+            .signOut()
+            .catch((err) => {
+            void normalizeError(err);
+        });
+    };
+}
+/** Test/diagnostic only. */
+export function activeRealtimeLeases() {
+    return leases;
+}

package/dist/core/unit-of-work.js

@@ -1,7 +1,19 @@
 import { normalizeError } from "../errors/normalize";
-const getAdminDb = () => module.require("../providers/db-firebase").getAdminDb();
+// Static import, deliberately. This used to be
+// `(module as any).require("../providers/db-firebase")` — the bundler-evasion
+// idiom used correctly elsewhere in appkit (admin.ts's firebase-admin loaders),
+// but every OTHER use passes a BARE specifier, which Node resolves from
+// node_modules at any depth. A RELATIVE one is resolved against the emitted
+// chunk, not this source file, so in a bundled Lambda it became
+// `.next/server/chunks/providers/db-firebase` → MODULE_NOT_FOUND, and every
+// runBatch/runTransaction threw before touching Firestore.
+//
+// The lazy form also bought nothing: the 19 repository imports below already
+// pull this module into the graph statically (bid.repository.ts et al), and
+// db-firebase reaches firebase-admin only through `import type` plus its own
+// bare-specifier runtime requires. See CLAUDE.md Root Cause #24.
+import { getAdminDb } from "../providers/db-firebase";
 import { DatabaseError } from "../errors";
-import { serverLogger } from "../monitoring";
 import { userRepository, tokenRepository, sessionRepository, } from "../features/auth/repository";
 import { addressesRepository } from "../features/addresses/repository/addresses.repository";
 import { cartRepository } from "../features/cart/repository/cart.repository";
@@ -81,32 +93,28 @@ export class UnitOfWork {
         return notificationRepository;
     }
     async runTransaction(fn) {
-        serverLogger.debug("[UnitOfWork] Starting transaction");
         try {
-            const result = await this.db.runTransaction(fn);
-            serverLogger.debug("[UnitOfWork] Transaction committed successfully");
-            return result;
+            return await this.db.runTransaction(fn);
         }
         catch (error) {
             void normalizeError(error);
-            serverLogger.error("[UnitOfWork] Transaction failed", {
-                error: error instanceof Error ? error.message : String(error),
-            });
-            throw new DatabaseError("Transaction failed", error);
+            // Interpolate the underlying message. Without it the persisted
+            // serverErrors row reads only "Transaction failed" and the real cause
+            // survives nowhere the store can see — `cause` carries the stack, but
+            // the message is what the admin list actually renders.
+            const detail = error instanceof Error ? error.message : String(error);
+            throw new DatabaseError(`Transaction failed: ${detail}`, error);
         }
     }
     async runBatch(fn) {
-        serverLogger.debug("[UnitOfWork] Starting batch write");
         try {
             const batch = this.db.batch();
             await fn(batch);
             await batch.commit();
-            serverLogger.debug("[UnitOfWork] Batch write committed successfully");
         }
         catch (error) {
             void normalizeError(error);
             const detail = error instanceof Error ? error.message : String(error);
-            serverLogger.error("[UnitOfWork] Batch write failed", { error: detail });
             throw new DatabaseError(`Batch write failed: ${detail}`, error);
         }
     }

package/dist/errors/base-error.js

@@ -1,6 +1,19 @@
 export class AppError extends Error {
     constructor(statusCode, message, code, data) {
-        super(message);
+        // Forward `data` as the standard `cause` when it is itself an Error.
+        //
+        // Every AppError in this codebase is a WRAP — `new DatabaseError("Batch
+        // write failed: …", originalError)` — and until 2026-08-28 the original was
+        // bound only to `data`, never to `cause`. Nothing that walks the cause chain
+        // (util.inspect, the Next error overlay, any APM, our own serverErrors
+        // recorder) could reach it, so the underlying fault was retained in memory
+        // and dropped by every consumer.
+        //
+        // `captureStackTrace` below additionally rebases `.stack` onto this
+        // constructor, so the wrapper's own stack starts at the catch block that
+        // wrapped it — the frames that named the real fault live ONLY on the cause.
+        // That is why preserving it is load-bearing rather than cosmetic.
+        super(message, data instanceof Error ? { cause: data } : undefined);
         this.statusCode = statusCode;
         this.message = message;
         this.code = code;

package/dist/errors/database-error.js

@@ -1,6 +1,16 @@
 import { AppError } from "./base-error";
+import { ERROR_CODES } from "./error-codes";
 export class DatabaseError extends AppError {
     constructor(message, data) {
-        super(500, message, "DATABASE_ERROR", data);
+        // `ERROR_CODES.DB_OPERATION_FAILED` ("DB_001"), NOT the literal
+        // "DATABASE_ERROR" this used to emit.
+        //
+        // That literal had exactly one reference in the entire repo — this line.
+        // It was absent from ERROR_CODES, HTTP_ERROR_CODES, ERROR_DISPLAY_MAP and
+        // messages/en.json, so all ~193 DatabaseError throw sites produced a code
+        // no lookup could resolve and every one of them fell through to the raw
+        // internal message. "DB_001" already has both a display-map entry and the
+        // translation "A database error occurred. Please try again".
+        super(500, message, ERROR_CODES.DB_OPERATION_FAILED, data);
     }
 }

package/dist/errors/describe-cause.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @returns the flattened chain, or `undefined` when there is no cause — so the
+ * caller can omit the Firestore field entirely rather than writing `""`.
+ */
+export declare function describeCauseChain(err: unknown): string | undefined;

package/dist/errors/describe-cause.js

@@ -0,0 +1,76 @@
+import { normalizeError } from "./normalize";
+/**
+ * Flatten an `Error.cause` chain into a single persistable string.
+ *
+ * WHY THIS EXISTS
+ *   Every `AppError` in this codebase is a WRAP — `new DatabaseError("Batch
+ *   write failed: …", originalError)` — and `AppError` calls
+ *   `Error.captureStackTrace(this, this.constructor)`, which rebases `.stack`
+ *   onto the wrapping constructor. So the wrapper's own stack starts at the
+ *   catch block that wrapped it, and the frames that actually name the fault
+ *   live only on the cause.
+ *
+ *   Nothing used to read them. `JSON.stringify(new Error("boom"))` is `"{}"`,
+ *   so the one logger path that tried (`buildServerMeta`) serialised the cause
+ *   to an empty object, and the serverErrors schema had no field for it at all.
+ *   The only reason the original message was ever readable was one call site
+ *   interpolating it into its own message by hand.
+ *
+ * Depth-capped and byte-capped: a cause chain is untrusted in length, and this
+ * value is persisted into a document that must stay inside the 4 KB stack
+ * budget documented on `ServerErrorDocument`.
+ */
+const MAX_DEPTH = 5;
+const MAX_BYTES = 4096;
+/** `cause` is only present on the ES2022 Error shape; read it structurally. */
+function causeOf(value) {
+    return value.cause;
+}
+function messageOf(err) {
+    if (err instanceof Error)
+        return `${err.name}: ${err.message}`;
+    if (typeof err === "string")
+        return err;
+    try {
+        return JSON.stringify(err) ?? String(err);
+        // JSON.stringify throws only on a circular/BigInt value; String() always
+        // succeeds. This runs inside the error path, where throwing would lose the
+        // original error we were trying to describe.
+    }
+    catch (stringifyErr) {
+        void normalizeError(stringifyErr);
+        return String(err);
+    }
+}
+/**
+ * @returns the flattened chain, or `undefined` when there is no cause — so the
+ * caller can omit the Firestore field entirely rather than writing `""`.
+ */
+export function describeCauseChain(err) {
+    if (!(err instanceof Error))
+        return undefined;
+    const parts = [];
+    const seen = new Set([err]);
+    let current = causeOf(err);
+    let depth = 0;
+    while (current !== undefined && current !== null && depth < MAX_DEPTH) {
+        // A cause cycle is rare but cheap to guard, and an infinite loop here would
+        // hang the error path — the one place that must never make things worse.
+        if (seen.has(current)) {
+            parts.push("caused by: <circular>");
+            break;
+        }
+        seen.add(current);
+        const head = messageOf(current);
+        const stack = current instanceof Error ? current.stack : undefined;
+        // Prefer the stack (it contains the message as its first line); fall back
+        // to the message alone for non-Error causes.
+        parts.push(`caused by: ${stack ?? head}`);
+        current = typeof current === "object" ? causeOf(current) : undefined;
+        depth++;
+    }
+    if (parts.length === 0)
+        return undefined;
+    const joined = parts.join("\n\n");
+    return joined.length <= MAX_BYTES ? joined : joined.slice(0, MAX_BYTES);
+}

package/dist/errors/error-display-map.d.ts

@@ -3,7 +3,12 @@
  *  - `field`: when present + a FormShellContext is in scope, the client wrapper
  *    routes the error inline as a field error instead of a toast.
  *  - `messageKey`: a `next-intl` key under `errors.codes.*` resolved at render time.
- *    Falls back to `errors.codes.UNKNOWN` then to the raw `Error.message` if absent.
+ *    Falls back to `errors.codes.UNKNOWN`, and then to `GENERIC_USER_MESSAGE`.
+ *
+ * 🛑 The chain terminates in a CONSTANT. It used to end "…then to the raw
+ * `Error.message` if absent", and that tail is what printed a Node require
+ * stack into the bid modal. Resolve codes through `toUserMessage` below; never
+ * re-add a raw-message fallback.
  */
 export interface ErrorDisplayEntry {
     field?: string;
@@ -12,3 +17,29 @@ export interface ErrorDisplayEntry {
 export declare const ERROR_DISPLAY_MAP: Record<string, ErrorDisplayEntry>;
 /** Look up display metadata; returns a generic entry when the code is unknown. */
 export declare function getErrorDisplay(code: string): ErrorDisplayEntry;
+/** Last-resort copy when no translator is available. Never a server string. */
+export declare const GENERIC_USER_MESSAGE = "Something went wrong. Please try again.";
+/**
+ * The user-facing message for an error code. **Never returns server text.**
+ *
+ * 🛑 This is the whole point: every previous way of doing this ended in a raw
+ * fallback. `ERROR_DISPLAY_MAP[code] ?? error` — the pattern CLAUDE.md Rule #9
+ * §6 itself documented — falls through to the server's own message, and that
+ * is how a Node `MODULE_NOT_FOUND`, complete with
+ * `/var/task/.next/server/chunks/...` and its full require stack, was rendered
+ * as copy inside the "Place your bid" modal. `surfaceError` had the same tail.
+ * There was no shared helper that did this correctly, which is why ~60 call
+ * sites each invented `err.message`.
+ *
+ * The chain is: code -> messageKey -> translation -> `errors.codes.UNKNOWN` ->
+ * `GENERIC_USER_MESSAGE`. It terminates in a constant, deliberately.
+ *
+ * @param code    stable error code from an `ActionResult` / error envelope
+ * @param t       a next-intl translator; omitted, the generic string is used
+ * @param options `fallback` overrides the generic string with FEATURE-SPECIFIC
+ *                copy you have authored ("Could not place your bid"). It must
+ *                never be a value derived from an error object.
+ */
+export declare function toUserMessage(code: string | undefined, t?: (key: string) => string, options?: {
+    fallback?: string;
+}): string;

package/dist/errors/error-display-map.js

@@ -1,3 +1,4 @@
+import { normalizeError } from "./normalize";
 import { ERROR_CODES, BID_ERROR_CODES, OFFER_ERROR_CODES } from "./error-codes";
 import { HTTP_ERROR_CODES } from "./error-mapping";
 const k = (code) => `errors.codes.${code}`;
@@ -240,3 +241,48 @@ export const ERROR_DISPLAY_MAP = {
 export function getErrorDisplay(code) {
     return ERROR_DISPLAY_MAP[code] ?? { messageKey: "errors.codes.UNKNOWN" };
 }
+/** Last-resort copy when no translator is available. Never a server string. */
+export const GENERIC_USER_MESSAGE = "Something went wrong. Please try again.";
+/**
+ * The user-facing message for an error code. **Never returns server text.**
+ *
+ * 🛑 This is the whole point: every previous way of doing this ended in a raw
+ * fallback. `ERROR_DISPLAY_MAP[code] ?? error` — the pattern CLAUDE.md Rule #9
+ * §6 itself documented — falls through to the server's own message, and that
+ * is how a Node `MODULE_NOT_FOUND`, complete with
+ * `/var/task/.next/server/chunks/...` and its full require stack, was rendered
+ * as copy inside the "Place your bid" modal. `surfaceError` had the same tail.
+ * There was no shared helper that did this correctly, which is why ~60 call
+ * sites each invented `err.message`.
+ *
+ * The chain is: code -> messageKey -> translation -> `errors.codes.UNKNOWN` ->
+ * `GENERIC_USER_MESSAGE`. It terminates in a constant, deliberately.
+ *
+ * @param code    stable error code from an `ActionResult` / error envelope
+ * @param t       a next-intl translator; omitted, the generic string is used
+ * @param options `fallback` overrides the generic string with FEATURE-SPECIFIC
+ *                copy you have authored ("Could not place your bid"). It must
+ *                never be a value derived from an error object.
+ */
+export function toUserMessage(code, t, options) {
+    const generic = options?.fallback ?? GENERIC_USER_MESSAGE;
+    if (!code)
+        return generic;
+    const { messageKey } = getErrorDisplay(code);
+    if (!t)
+        return generic;
+    try {
+        const translated = t(messageKey);
+        // next-intl returns the key itself (or throws) when a message is missing;
+        // either way that is not something to show a user.
+        if (translated && translated !== messageKey)
+            return translated;
+        // next-intl throws MISSING_MESSAGE for an absent key. This function's whole
+        // contract is to degrade to generic copy rather than let ANY internal
+        // string — including an i18n internal — reach the user.
+    }
+    catch (translateErr) {
+        void normalizeError(translateErr);
+    }
+    return generic;
+}