@mohasinac/appkit 4.30.17 → 4.30.19

package/dist/features/tester/seed-data/tester-checklist-seed-data.js

@@ -3728,7 +3728,22 @@ const rawTesterChecklistItems = [
                     href: "/admin/site",
                 },
                 { key: "admin-dashboard-widgets", label: "Admin dashboard widgets show accurate data", href: "/admin/dashboard" },
-                { key: "analytics-admin", label: "Admin analytics dashboard shows accurate data", href: "/admin/analytics" },
+                {
+                    key: "analytics-admin",
+                    label: "Admin analytics dashboard shows accurate data",
+                    href: "/admin/analytics",
+                },
+                {
+                    key: "analytics-traffic-card-has-numbers",
+                    label: "The \"Traffic today\" card shows a real number, and it MATCHES the Page Views tab beside it",
+                    description: "Fixed 2026-08-29. BEFORE: the card showed an em-dash forever — never even a 0. It subscribed to two Realtime Database paths written by a presence hook whose writes had been denied since the day it shipped (the RTDB rules are backend-write-only), and both subscriptions passed no error callback, so a permission denial fired nothing at all and the tiles simply never left their initial state. AFTER: the card reads the same Firestore pageview counter that backs the Page Views tab in the same tab strip, so the two figures must agree — compare them. If the card errors it now SAYS so instead of showing a dash.",
+                },
+                {
+                    key: "analytics-no-permission-denied",
+                    label: "Opening /admin/analytics logs no PERMISSION_DENIED in the browser console",
+                    description: "Fixed 2026-08-29. BEFORE: every admin page load produced two Firebase permission_denied warnings from the dead presence/analytics subscriptions. AFTER: none — those subscriptions are gone entirely. Open devtools, hard-reload the page, and confirm the console is clean of Firebase permission errors.",
+                    href: "/admin/analytics",
+                },
                 {
                     key: "pageviews-report-listing-standard",
                     label: "The \"Page Views\" tab in Admin Analytics is a full standard listing — a search box (by entity id or URL), an entity-type filter drawer, a \"Most views\"/\"Fewest views\" sort dropdown, and real pagination — not a bare unsearchable table",

package/dist/features/whatsapp-bot/components/SellerWhatsAppSettingsView.js

@@ -3,6 +3,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useApiMutation, useBulkEvent, RTDB_PATHS } from "@mohasinac/appkit/client";
 import React from "react";
 import { normalizeError } from "../../../errors/normalize";
+import { toUserMessage } from "../../../errors/error-display-map";
 const __P = {
     p3: "p-[var(--appkit-space-3)]",
 };
@@ -156,9 +157,9 @@ export function SellerWhatsAppSettingsView({ hasCapability }) {
             }
         }
         catch (err) {
-            void normalizeError(err);
+            const e = normalizeError(err);
             setImporting(false);
-            showToast(err instanceof Error ? err.message : "Import failed", "error");
+            showToast(toUserMessage(e.code, undefined, { fallback: "Failed to start catalog import." }), "error");
         }
     };
     React.useEffect(() => {

package/dist/features/wishlist/hooks/useWishlistToggle.js

@@ -1,6 +1,8 @@
 "use client";
 import { useCallback, useState } from "react";
 import { useToast } from "../../../ui";
+import { normalizeError } from "../../../errors/normalize";
+import { toUserMessage } from "../../../errors/error-display-map";
 export function useWishlistToggle(productId, initial = false, actions) {
     const [inWishlist, setInWishlist] = useState(initial);
     const [isLoading, setIsLoading] = useState(false);
@@ -25,8 +27,13 @@ export function useWishlistToggle(productId, initial = false, actions) {
             }
         }
         catch (err) {
+            const e = normalizeError(err);
             setInWishlist(prev);
-            showToast(err instanceof Error ? err.message : "Something went wrong.", "error");
+            showToast(toUserMessage(e.code, undefined, {
+                fallback: prev
+                    ? "Could not remove this item from your wishlist."
+                    : "Could not add this item to your wishlist.",
+            }), "error");
             throw err;
         }
         finally {

package/dist/index.d.ts

@@ -333,6 +333,7 @@ export { RazorpayUnreachableError } from "./errors/index";
 export { mapToHttpError, HTTP_ERROR_CODES } from "./errors/index";
 export type { MappedError, HttpErrorCode } from "./errors/index";
 export { ERROR_DISPLAY_MAP, getErrorDisplay } from "./errors/index";
+export { toUserMessage, GENERIC_USER_MESSAGE } from "./errors/index";
 export type { ErrorDisplayEntry } from "./errors/index";
 export { parseJsonBody } from "./next/api/parseJsonBody";
 export { SEO_CONFIG } from "./seo/index";
@@ -849,7 +850,6 @@ export { requireRoleUser } from "./providers/auth-firebase/index";
 export { revokeUserTokens } from "./providers/auth-firebase/index";
 export { verifyIdToken } from "./providers/auth-firebase/index";
 export { verifySessionCookie } from "./providers/auth-firebase/index";
-export { FirebaseRealtimeRepository } from "./providers/db-firebase/index";
 export { FirebaseRepository } from "./providers/db-firebase/index";
 export { FirebaseSieveRepository } from "./providers/db-firebase/index";
 export { RTDB_PATHS } from "./providers/db-firebase/index";

package/dist/index.js

@@ -568,6 +568,11 @@ export { mapToHttpError, HTTP_ERROR_CODES } from "./errors/index";
 // [UTIL]-Pure utility — client-safe lookup of inline-field + i18n key per error code.
 // ERROR_DISPLAY_MAP - CLAUDE.md Rule #9 source-of-truth for client error rendering.
 export { ERROR_DISPLAY_MAP, getErrorDisplay } from "./errors/index";
+// [UTIL]-Pure utility — the ONLY sanctioned way to turn a failure into user copy.
+// toUserMessage - resolves a stable error code through errors.codes.*; terminates
+// in a constant, so a thrown value's own .message can never reach a user
+// (audit-raw-error-text).
+export { toUserMessage, GENERIC_USER_MESSAGE } from "./errors/index";
 // [SERVER-ONLY] parseJsonBody — strict JSON request-body parser for API routes.
 // Replaces the silent `request.json().catch(() => ({}))` anti-pattern. Throws
 // ValidationError on malformed JSON → routeHandler wrapper maps to 400.
@@ -1726,8 +1731,6 @@ export { verifyIdToken } from "./providers/auth-firebase/index";
 export { verifySessionCookie } from "./providers/auth-firebase/index";
 // ./providers/db-firebase/index
 // [DB]-Database layer â€" uses firebase-admin or another server-side DB SDK; can only run in a trusted server environment.
-// FirebaseRealtimeRepository - Shared export for firebase realtime repository.
-export { FirebaseRealtimeRepository } from "./providers/db-firebase/index";
 // [DB]-Database layer â€" uses firebase-admin or another server-side DB SDK; can only run in a trusted server environment.
 // FirebaseRepository - Shared export for firebase repository.
 export { FirebaseRepository } from "./providers/db-firebase/index";

package/dist/next/api/routeHandler.js

@@ -182,10 +182,12 @@ export function createRouteHandler(options) {
             else if (options.authOptional) {
                 try {
                     user = await verifySession(request);
+                    // Deliberate: this is the OPTIONAL-auth path. A bad or absent session means
+                    // anonymous, which is a legitimate outcome here — routes that require a
+                    // user use `auth: true`, which throws instead.
                 }
                 catch (_err) {
                     void normalizeError(_err);
-                    // anonymous
                 }
             }
             // -- Role check --------------------------------------------------------

package/dist/providers/auth-firebase/session.js

@@ -71,8 +71,10 @@ export const firebaseSessionProvider = {
             await getAdminAuthLite().revokeRefreshTokens(decoded.uid);
         }
         catch (_err) {
+            // Best-effort teardown: an expired/revoked/malformed cookie cannot be
+            // verified, and that is the state destroySession is trying to reach —
+            // reporting it would alarm on the success case.
             void normalizeError(_err);
-            // Best-effort: if cookie is already invalid, treat as already destroyed
         }
     },
 };

package/dist/providers/db-firebase/admin-app-lite.js

@@ -1,4 +1,9 @@
 import { initializeApp, getApps, cert } from "firebase-admin/app";
+// One resolver, not a second copy — this file duplicated admin.ts's URL
+// logic byte-for-byte, so the region-wrong fallback bug existed twice.
+// Imported from its own dependency-free module, NOT from ./admin, because the
+// whole point of admin-app-lite is not pulling the full admin module in.
+import { resolveRtdbUrl } from "./rtdb-url";
 function nodePath() { return require("path"); }
 function nodeFs() { return require("fs"); }
 // process.cwd() is Node.js-only; access via module.require so the Edge
@@ -26,17 +31,14 @@ export function getAdminAppLite() {
     let app;
     if (nodeFs().existsSync(keyPath)) {
         const sa = JSON.parse(nodeFs().readFileSync(keyPath, "utf8"));
-        const dbUrl = process.env.NEXT_PUBLIC_FIREBASE_DATABASE_URL ??
-            `https://${sa.project_id}-default-rtdb.firebaseio.com`;
+        const dbUrl = resolveRtdbUrl();
         app = initializeApp({ credential: cert(keyPath), databaseURL: dbUrl, ...(storageBucket && { storageBucket }) });
     }
     else if (process.env.FIREBASE_ADMIN_PROJECT_ID &&
         process.env.FIREBASE_ADMIN_CLIENT_EMAIL &&
         process.env.FIREBASE_ADMIN_PRIVATE_KEY) {
         const projectId = process.env.FIREBASE_ADMIN_PROJECT_ID.trim();
-        const dbUrl = process.env.FIREBASE_ADMIN_DATABASE_URL?.trim() ??
-            process.env.NEXT_PUBLIC_FIREBASE_DATABASE_URL?.trim() ??
-            `https://${projectId}-default-rtdb.firebaseio.com`;
+        const dbUrl = resolveRtdbUrl();
         app = initializeApp({
             credential: cert({
                 projectId,
@@ -63,9 +65,7 @@ export function getAdminAppLite() {
             : {};
         const projectId = firebaseConfig.projectId ?? process.env.GCLOUD_PROJECT ?? "";
         const dbUrl = firebaseConfig.databaseURL ??
-            process.env.FIREBASE_ADMIN_DATABASE_URL ??
-            process.env.NEXT_PUBLIC_FIREBASE_DATABASE_URL ??
-            (projectId ? `https://${projectId}-default-rtdb.firebaseio.com` : undefined);
+            resolveRtdbUrl();
         app = initializeApp({
             ...(dbUrl && { databaseURL: dbUrl }),
             ...(storageBucket && { storageBucket }),

package/dist/providers/db-firebase/admin.js

@@ -1,4 +1,5 @@
 import { normalizeError } from "../../errors/normalize";
+import { resolveRtdbUrl } from "./rtdb-url";
 function nodePath() { return require("path"); }
 function nodeFs() { return require("fs"); }
 // process.cwd() is Node.js-only; access via module.require so the Edge
@@ -69,17 +70,16 @@ export function getAdminApp() {
     try {
         if (nodeFs().existsSync(keyPath)) {
             const sa = JSON.parse(nodeFs().readFileSync(keyPath, "utf8"));
-            const dbUrl = process.env.NEXT_PUBLIC_FIREBASE_DATABASE_URL ??
-                `https://${sa.project_id}-default-rtdb.firebaseio.com`;
+            // Was NEXT_PUBLIC-only here while the other two branches honoured
+            // FIREBASE_ADMIN_DATABASE_URL, so setting it had no effect on this path.
+            const dbUrl = resolveRtdbUrl();
             app = initializeApp({ credential: cert(keyPath), databaseURL: dbUrl, ...(storageBucket && { storageBucket }) });
         }
         else if (process.env.FIREBASE_ADMIN_PROJECT_ID &&
             process.env.FIREBASE_ADMIN_CLIENT_EMAIL &&
             process.env.FIREBASE_ADMIN_PRIVATE_KEY) {
             const projectId = process.env.FIREBASE_ADMIN_PROJECT_ID.trim();
-            const dbUrl = process.env.FIREBASE_ADMIN_DATABASE_URL?.trim() ??
-                process.env.NEXT_PUBLIC_FIREBASE_DATABASE_URL?.trim() ??
-                `https://${projectId}-default-rtdb.firebaseio.com`;
+            const dbUrl = resolveRtdbUrl();
             app = initializeApp({
                 credential: cert({
                     projectId,
@@ -105,12 +105,9 @@ export function getAdminApp() {
                 ? JSON.parse(process.env.FIREBASE_CONFIG)
                 : {};
             const projectId = firebaseConfig.projectId ?? process.env.GCLOUD_PROJECT ?? "";
-            const dbUrl = firebaseConfig.databaseURL ??
-                process.env.FIREBASE_ADMIN_DATABASE_URL ??
-                process.env.NEXT_PUBLIC_FIREBASE_DATABASE_URL ??
-                (projectId
-                    ? `https://${projectId}-default-rtdb.firebaseio.com`
-                    : undefined);
+            // FIREBASE_CONFIG is injected by the Functions runtime and is
+            // authoritative there; env vars are the fallback for other runtimes.
+            const dbUrl = firebaseConfig.databaseURL || resolveRtdbUrl();
             app = initializeApp({
                 ...(dbUrl && { databaseURL: dbUrl }),
                 ...(storageBucket && { storageBucket }),
@@ -153,8 +150,11 @@ export function getAdminDb() {
         db.settings({ ignoreUndefinedProperties: true });
     }
     catch (_err) {
+        // Firestore rejects a second settings() call on an already-initialised
+        // instance, which is the only way this throws (HMR reload / duplicate
+        // module instance re-entering the memoised bootstrap). The instance is
+        // fully usable either way, so there is nothing degraded to report.
         void normalizeError(_err);
-        // Already configured — safe to ignore.
     }
     set("__mohasinac_firebase_admin_db__", db);
     return db;

package/dist/providers/db-firebase/browser-stub.d.ts

@@ -22,17 +22,7 @@ export declare function prepareForFirestore(data: any): any;
 export declare function deserializeTimestamps<T>(data: any): T;
 export declare const FirebaseRepository: any;
 export declare const FirebaseSieveRepository: any;
-export declare const FirebaseRealtimeRepository: any;
 export declare const firebaseDbProvider: any;
-export declare const RTDB_PATHS: {
-    readonly PRESENCE: "presence";
-    readonly CHAT: "chat";
-    readonly NOTIFICATIONS: "notifications";
-    readonly LIVE_UPDATES: "live_updates";
-    readonly AUTH_EVENTS: "auth_events";
-    readonly PAYMENT_EVENTS: "payment_events";
-    readonly BULK_EVENTS: "bulk_events";
-    readonly SEED_EVENTS: "seed_events";
-};
+export { RTDB_PATHS } from "./rtdb-paths";
 export { buildFirebaseClientConfig, normalizeFirebaseConfigValue } from './client-config';
 export type { FirebaseClientConfig } from './client-config';

package/dist/providers/db-firebase/browser-stub.js

@@ -40,17 +40,12 @@ export function deserializeTimestamps(data) {
 }
 export const FirebaseRepository = null;
 export const FirebaseSieveRepository = null;
-export const FirebaseRealtimeRepository = null;
 export const firebaseDbProvider = null;
-export const RTDB_PATHS = {
-    PRESENCE: "presence",
-    CHAT: "chat",
-    NOTIFICATIONS: "notifications",
-    LIVE_UPDATES: "live_updates",
-    AUTH_EVENTS: "auth_events",
-    PAYMENT_EVENTS: "payment_events",
-    BULK_EVENTS: "bulk_events",
-    SEED_EVENTS: "seed_events",
-};
+// Re-exported, NOT re-declared. This file is the `browser` resolution target, so
+// the byte-for-byte copy that used to live here meant client code and server
+// code read two independently-maintained definitions of the same constant, with
+// nothing guarding the drift. `rtdb-paths.ts` has no imports, so it is safe to
+// pull into a browser bundle directly.
+export { RTDB_PATHS } from "./rtdb-paths";
 // Client config builder � safe in all environments
 export { buildFirebaseClientConfig, normalizeFirebaseConfigValue } from './client-config';

package/dist/providers/db-firebase/index.d.ts

@@ -20,7 +20,6 @@ export type { DocumentSnapshot } from "firebase-admin/firestore";
 export { FirebaseRepository } from "./base";
 export { BaseRepository } from "./base.repository";
 export { FirebaseSieveRepository } from "./sieve";
-export { FirebaseRealtimeRepository } from "./realtime";
 export { RTDB_PATHS } from "./rtdb-paths";
 import type { IDbProvider } from "../../contracts";
 export declare const firebaseDbProvider: IDbProvider;

package/dist/providers/db-firebase/index.js

@@ -27,7 +27,6 @@ export { firebaseFieldOps } from "./field-ops";
 export { FirebaseRepository } from "./base";
 export { BaseRepository } from "./base.repository";
 export { FirebaseSieveRepository } from "./sieve";
-export { FirebaseRealtimeRepository } from "./realtime";
 // Re-export RTDB paths
 export { RTDB_PATHS } from "./rtdb-paths";
 import { FirebaseRepository as _FirebaseRepository } from "./base";

package/dist/providers/db-firebase/rtdb-paths.d.ts

@@ -1,13 +1,22 @@
 /**
- * Shared Realtime Database path constants for auth/payment/bulk event channels.
+ * Shared Realtime Database path constants for the auth/payment/bulk event channels.
+ *
+ * 🛑 Only paths that are actually referenced through this constant belong here.
+ * Five keys were removed on 2026-08-29 — `PRESENCE`, `CHAT`, `NOTIFICATIONS`,
+ * `LIVE_UPDATES`, `SEED_EVENTS` — every one with **zero consumers**, because
+ * each live call site hardcodes its path string instead. A constant nobody uses
+ * is not a source of truth; it is a second place for the value to be wrong, and
+ * three of those five named RTDB nodes that no longer exist at all.
+ *
+ * If you add a key, migrate the call sites to it in the same change.
+ *
+ * This module has NO imports on purpose — that is what lets `browser-stub.ts`
+ * re-export it rather than keep the byte-for-byte duplicate it used to carry.
+ * The stub is the `browser` resolution target, so that duplicate meant client
+ * code and server code were reading two independently-maintained copies.
  */
 export declare const RTDB_PATHS: {
-    readonly PRESENCE: "presence";
-    readonly CHAT: "chat";
-    readonly NOTIFICATIONS: "notifications";
-    readonly LIVE_UPDATES: "live_updates";
     readonly AUTH_EVENTS: "auth_events";
     readonly PAYMENT_EVENTS: "payment_events";
     readonly BULK_EVENTS: "bulk_events";
-    readonly SEED_EVENTS: "seed_events";
 };

package/dist/providers/db-firebase/rtdb-paths.js

@@ -1,13 +1,22 @@
 /**
- * Shared Realtime Database path constants for auth/payment/bulk event channels.
+ * Shared Realtime Database path constants for the auth/payment/bulk event channels.
+ *
+ * 🛑 Only paths that are actually referenced through this constant belong here.
+ * Five keys were removed on 2026-08-29 — `PRESENCE`, `CHAT`, `NOTIFICATIONS`,
+ * `LIVE_UPDATES`, `SEED_EVENTS` — every one with **zero consumers**, because
+ * each live call site hardcodes its path string instead. A constant nobody uses
+ * is not a source of truth; it is a second place for the value to be wrong, and
+ * three of those five named RTDB nodes that no longer exist at all.
+ *
+ * If you add a key, migrate the call sites to it in the same change.
+ *
+ * This module has NO imports on purpose — that is what lets `browser-stub.ts`
+ * re-export it rather than keep the byte-for-byte duplicate it used to carry.
+ * The stub is the `browser` resolution target, so that duplicate meant client
+ * code and server code were reading two independently-maintained copies.
  */
 export const RTDB_PATHS = {
-    PRESENCE: "presence",
-    CHAT: "chat",
-    NOTIFICATIONS: "notifications",
-    LIVE_UPDATES: "live_updates",
     AUTH_EVENTS: "auth_events",
     PAYMENT_EVENTS: "payment_events",
     BULK_EVENTS: "bulk_events",
-    SEED_EVENTS: "seed_events",
 };

package/dist/providers/db-firebase/rtdb-url.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Resolve the Realtime Database URL from the environment.
+ *
+ * Its own module, with **no imports**, because both `admin.ts` and
+ * `admin-app-lite.ts` need it and `admin-app-lite` exists precisely to avoid
+ * pulling in the full admin module. They previously carried byte-for-byte
+ * duplicate resolution logic, which meant the bug below existed twice.
+ *
+ * 🛑 Returns `undefined` rather than guessing.
+ *
+ * All six copies used to fall back to `https://${projectId}-default-rtdb.firebaseio.com`.
+ * That is the **us-central1** URL shape; this project's instance lives at
+ * `…-default-rtdb.asia-southeast1.firebasedatabase.app`. So whenever the env var
+ * was missing, every server RTDB write silently targeted a database that does
+ * not exist — and since all nine RTDB writers wrap their call in a swallowing
+ * try/catch, messaging, bids, job status and payment signalling would every one
+ * of them degrade to "nothing ever updates", with clean warn-level logs.
+ *
+ * A guessed URL cannot be correct for a non-default region, so guessing buys
+ * nothing and costs the ability to notice. With no `databaseURL`,
+ * `getAdminRealtimeDb()` fails loudly at first use instead, which is the
+ * outcome you want.
+ *
+ * `||` not `??`: an env var that is present but empty must fall through, and
+ * `??` only falls through on null/undefined.
+ */
+export declare function resolveRtdbUrl(): string | undefined;

package/dist/providers/db-firebase/rtdb-url.js

@@ -0,0 +1,50 @@
+/**
+ * Resolve the Realtime Database URL from the environment.
+ *
+ * Its own module, with **no imports**, because both `admin.ts` and
+ * `admin-app-lite.ts` need it and `admin-app-lite` exists precisely to avoid
+ * pulling in the full admin module. They previously carried byte-for-byte
+ * duplicate resolution logic, which meant the bug below existed twice.
+ *
+ * 🛑 Returns `undefined` rather than guessing.
+ *
+ * All six copies used to fall back to `https://${projectId}-default-rtdb.firebaseio.com`.
+ * That is the **us-central1** URL shape; this project's instance lives at
+ * `…-default-rtdb.asia-southeast1.firebasedatabase.app`. So whenever the env var
+ * was missing, every server RTDB write silently targeted a database that does
+ * not exist — and since all nine RTDB writers wrap their call in a swallowing
+ * try/catch, messaging, bids, job status and payment signalling would every one
+ * of them degrade to "nothing ever updates", with clean warn-level logs.
+ *
+ * A guessed URL cannot be correct for a non-default region, so guessing buys
+ * nothing and costs the ability to notice. With no `databaseURL`,
+ * `getAdminRealtimeDb()` fails loudly at first use instead, which is the
+ * outcome you want.
+ *
+ * `||` not `??`: an env var that is present but empty must fall through, and
+ * `??` only falls through on null/undefined.
+ */
+export function resolveRtdbUrl() {
+    // 🛑 Emulator first.
+    //
+    // `firebase.json` has declared a database emulator on port 9000 for a long
+    // time and NOTHING ever connected to it. Client writes were shielded only
+    // because every rule is `.write: false`; server writes use the Admin SDK and
+    // bypass rules entirely — so `npm run dev` wrote to PRODUCTION. A local bid
+    // overwrote the prod `auction-bids` node that live auction pages subscribe to,
+    // and a local message send wrote prod `chats/**`.
+    //
+    // `FIREBASE_DATABASE_EMULATOR_HOST` is the standard variable the Firebase CLI
+    // exports for exactly this, so honouring it costs one branch and makes
+    // `firebase emulators:start` do what everyone already assumed it did.
+    const emulatorHost = process.env.FIREBASE_DATABASE_EMULATOR_HOST?.trim();
+    if (emulatorHost) {
+        const ns = process.env.FIREBASE_ADMIN_PROJECT_ID?.trim() ||
+            process.env.NEXT_PUBLIC_FIREBASE_PROJECT_ID?.trim() ||
+            "default";
+        return `http://${emulatorHost}?ns=${ns}`;
+    }
+    return (process.env.FIREBASE_ADMIN_DATABASE_URL?.trim() ||
+        process.env.NEXT_PUBLIC_FIREBASE_DATABASE_URL?.trim() ||
+        undefined);
+}

package/dist/providers/firebase-client/realtime.d.ts

@@ -11,7 +11,27 @@ export interface FirebaseClientRealtimeConfig {
 export declare class FirebaseClientRealtimeProvider implements IClientRealtimeProvider {
     private app;
     private db;
+    private readonly config;
+    private readonly appName;
+    private readonly scoped;
     constructor(config: FirebaseClientRealtimeConfig);
+    /**
+     * A provider bound to its OWN Firebase app for this claim scope.
+     *
+     * 🛑 This is what makes concurrent channels safe. Firebase Auth state is
+     * per-app, so with one shared app every `signInWithToken` REPLACED the claims
+     * of every other live subscriber: a bulk job signing in with a
+     * `{ bulkJobId }`-only token instantly stripped `conversationIds` from an open
+     * messages subscription, and vice versa. Whoever signed in last won.
+     *
+     * Reference-counting fixed only the sign-OUT half of that (a finishing job no
+     * longer ends someone else's session). Sign-IN needed separate apps, because
+     * there is nothing to coordinate — two channels legitimately need two
+     * different claim sets at the same time.
+     *
+     * Apps are cached per scope and reused, so a remount does not leak one.
+     */
+    forScope(scope: string): IClientRealtimeProvider;
     signInWithToken(token: string): Promise<void>;
     signOut(): Promise<void>;
     subscribe(path: string, onData: (snapshot: RealtimeSnapshot) => void, onError?: (error: Error) => void): Unsubscribe;

package/dist/providers/firebase-client/realtime.js

@@ -7,12 +7,44 @@ import { getAuth, signInWithCustomToken, signOut } from "firebase/auth";
  */
 export class FirebaseClientRealtimeProvider {
     constructor(config) {
+        this.scoped = new Map();
         const appName = config.appName ?? "appkit-realtime";
+        this.config = config;
+        this.appName = appName;
         this.app =
             getApps().find((a) => a.name === appName) ??
                 initializeApp(config.firebaseConfig, appName);
         this.db = getDatabase(this.app);
     }
+    /**
+     * A provider bound to its OWN Firebase app for this claim scope.
+     *
+     * 🛑 This is what makes concurrent channels safe. Firebase Auth state is
+     * per-app, so with one shared app every `signInWithToken` REPLACED the claims
+     * of every other live subscriber: a bulk job signing in with a
+     * `{ bulkJobId }`-only token instantly stripped `conversationIds` from an open
+     * messages subscription, and vice versa. Whoever signed in last won.
+     *
+     * Reference-counting fixed only the sign-OUT half of that (a finishing job no
+     * longer ends someone else's session). Sign-IN needed separate apps, because
+     * there is nothing to coordinate — two channels legitimately need two
+     * different claim sets at the same time.
+     *
+     * Apps are cached per scope and reused, so a remount does not leak one.
+     */
+    forScope(scope) {
+        const existing = this.scoped.get(scope);
+        if (existing)
+            return existing;
+        // Firebase app names are freeform, but keep them predictable in devtools.
+        const safe = scope.replace(/[^a-zA-Z0-9_-]/g, "-");
+        const child = new FirebaseClientRealtimeProvider({
+            ...this.config,
+            appName: `${this.appName}-${safe}`,
+        });
+        this.scoped.set(scope, child);
+        return child;
+    }
     async signInWithToken(token) {
         await signInWithCustomToken(getAuth(this.app), token);
     }
@@ -21,8 +53,9 @@ export class FirebaseClientRealtimeProvider {
             await signOut(getAuth(this.app));
         }
         catch (_err) {
+            // A secondary Firebase app that was never signed in has nothing to sign
+            // out of; the caller's goal (no credential on this app) already holds.
             void normalizeError(_err);
-            // no-op — signing out of a secondary app can fail harmlessly
         }
     }
     subscribe(path, onData, onError) {

package/dist/providers.d.ts

@@ -12,7 +12,7 @@
 export { registerProviders, getProviders } from "./contracts/index";
 export { configureMarketDefaults } from "./core/baseline-resolver";
 export { firebaseAuthProvider, firebaseSessionProvider, createSessionCookieFromToken, createSessionCookie, verifyIdToken, verifySessionCookie, createMiddlewareAuthChain, requireAuth, requireRole, requireAuthUser, requireRoleUser, getUserFromRequest, requireAuthFromRequest, requireRoleFromRequest, revokeUserTokens, } from "./providers/auth-firebase/index";
-export { firebaseDbProvider, getAdminApp, getAdminAuth, getAdminDb, getAdminStorage, getAdminRealtimeDb, _resetAdminSingletons, FirebaseRepository, BaseRepository, FirebaseSieveRepository, FirebaseRealtimeRepository, RTDB_PATHS, firebaseFieldOps, removeUndefined, prepareForFirestore, deserializeTimestamps, } from "./providers/db-firebase/index";
+export { firebaseDbProvider, getAdminApp, getAdminAuth, getAdminDb, getAdminStorage, getAdminRealtimeDb, _resetAdminSingletons, FirebaseRepository, BaseRepository, FirebaseSieveRepository, RTDB_PATHS, firebaseFieldOps, removeUndefined, prepareForFirestore, deserializeTimestamps, } from "./providers/db-firebase/index";
 export type { DocumentSnapshot } from "firebase-admin/firestore";
 export { firebaseStorageProvider } from "./providers/storage-firebase/index";
 export { createResendProvider } from "./providers/email-resend/index";

package/dist/providers.js

@@ -15,7 +15,7 @@ export { configureMarketDefaults } from "./core/baseline-resolver";
 // Auth (Firebase Admin)
 export { firebaseAuthProvider, firebaseSessionProvider, createSessionCookieFromToken, createSessionCookie, verifyIdToken, verifySessionCookie, createMiddlewareAuthChain, requireAuth, requireRole, requireAuthUser, requireRoleUser, getUserFromRequest, requireAuthFromRequest, requireRoleFromRequest, revokeUserTokens, } from "./providers/auth-firebase/index";
 // Database (Firebase Firestore / RTDB)
-export { firebaseDbProvider, getAdminApp, getAdminAuth, getAdminDb, getAdminStorage, getAdminRealtimeDb, _resetAdminSingletons, FirebaseRepository, BaseRepository, FirebaseSieveRepository, FirebaseRealtimeRepository, RTDB_PATHS, firebaseFieldOps, removeUndefined, prepareForFirestore, deserializeTimestamps, } from "./providers/db-firebase/index";
+export { firebaseDbProvider, getAdminApp, getAdminAuth, getAdminDb, getAdminStorage, getAdminRealtimeDb, _resetAdminSingletons, FirebaseRepository, BaseRepository, FirebaseSieveRepository, RTDB_PATHS, firebaseFieldOps, removeUndefined, prepareForFirestore, deserializeTimestamps, } from "./providers/db-firebase/index";
 // Storage (Firebase Admin)
 export { firebaseStorageProvider } from "./providers/storage-firebase/index";
 // Email (Resend)

package/dist/react/hooks/use-action-dispatch.js

@@ -1,5 +1,6 @@
 "use client";
 import { normalizeError } from "../../errors/normalize";
+import { toUserMessage } from "../../errors/error-display-map";
 import { useCallback } from "react";
 import { useRouter } from "next/navigation";
 import { useToast } from "../../ui";
@@ -33,8 +34,13 @@ export function useActionDispatch(options) {
                         showToast(action.successMessage, "success");
                 }
                 catch (err) {
-                    void normalizeError(err);
-                    showToast(action.errorMessage ?? (err instanceof Error ? err.message : "Something went wrong."), "error");
+                    const e = normalizeError(err);
+                    // The action's own errorMessage still wins — it is the most
+                    // specific authored copy available. Only the tail changed: it now
+                    // resolves the error's CODE and ends in a constant, instead of
+                    // ending in the thrown value's developer-facing text.
+                    showToast(action.errorMessage ??
+                        toUserMessage(e.code, undefined, { fallback: "Something went wrong." }), "error");
                 }
                 break;
         }

package/dist/react/hooks/useFormStatePreservation.js

@@ -28,10 +28,12 @@ export function useFormStatePreservation({ values, onRestore, stripFields = [],
         try {
             const decoded = JSON.parse(atob(encoded));
             onRestore(decoded);
+            // The payload is user-supplied via the URL, so corrupt input is expected
+            // rather than exceptional. Discarding it restores the empty form, which is
+            // the same state as arriving without one.
         }
         catch (_err) {
             void normalizeError(_err);
-            // ignore corrupt payloads
         }
     }, [paramName, onRestore]);
     useEffect(() => {