@mohasinac/appkit 4.52.4 → 4.53.0

package/dist/index.js

@@ -1875,11 +1875,7 @@ export { ProfileView } from "./features/account/index.js";
 // UserAccountHubView - Component for user account hub view.
 export { UserAccountHubView } from "./features/account/index.js";
 // [CLIENT-SSR]-Runs in both SSR and browser â€" React component or hook that does not depend on browser-only APIs.
-// UserAddressesView - Component for user addresses view.
-export { UserAddressesView } from "./features/account/index.js";
 // [CLIENT-SSR]-Runs in both SSR and browser â€" React component or hook that does not depend on browser-only APIs.
-// UserNotificationsView - Component for user notifications view.
-export { UserNotificationsView } from "./features/account/index.js";
 // [CLIENT-SSR]-Runs in both SSR and browser â€" React component or hook that does not depend on browser-only APIs.
 // [CLIENT]-Runs in browser only â€" interactive buyer offers panel with accept/withdraw actions.
 // UserOffersPanel - Interactive buyer offers panel.
@@ -1891,8 +1887,6 @@ export { UserOrderTrackView } from "./features/account/index.js";
 // UserOrdersView - Component for user orders view.
 export { UserOrdersView } from "./features/account/index.js";
 // [CLIENT-SSR]-Runs in both SSR and browser â€" React component or hook that does not depend on browser-only APIs.
-// UserSettingsView - Component for user settings view.
-export { UserSettingsView } from "./features/account/index.js";
 // [CLIENT-SSR]-Runs in both SSR and browser — React component that lets users manage their notification channel and type preferences.
 // NotificationPreferencesPanel - Panel for user notification preferences.
 export { NotificationPreferencesPanel } from "./features/account/index.js";
@@ -1952,6 +1946,10 @@ export { useUpdateProfile } from "./features/account/index.js";
 // [CLIENT-SSR]-Runs in both SSR and browser â€" React component or hook that does not depend on browser-only APIs.
 // userProfileSchema - Model for user profile schema.
 export { userProfileSchema } from "./features/account/index.js";
+// [TYPE]-TypeScript type-only export â€" erased at compile time, zero runtime cost.
+// UserSettingsViewLabels - Type contract for user settings view labels.
+// [TYPE]-TypeScript type-only export â€" erased at compile time, zero runtime cost.
+// UserSettingsViewProps - Type contract for user settings view props.
 // ./features/account/server
 // [DB]-Database layer â€" uses firebase-admin or another server-side DB SDK; can only run in a trusted server environment.
 // AccountRepository - Shared export for account repository.
@@ -2194,7 +2192,6 @@ export { DEFAULT_TRUST_BAR_ITEMS } from "./features/admin/index.js";
 // DashboardStatsGrid - Component for dashboard stats grid.
 export { DashboardStatsGrid } from "./features/admin/index.js";
 // [CLIENT-SSR]-Runs in both SSR and browser â€" React component or hook that does not depend on browser-only APIs.
-// DemoSeedView — removed from main barrel (dev-only, load via dynamic import)
 // AdminTeamView - Employee management list view.
 export { AdminTeamView } from "./features/admin/index.js";
 // AdminEmployeeEditorView - Invite/edit employee permissions SideDrawer.
@@ -2874,8 +2871,6 @@ export { CategoryForm } from "./features/categories/index.js";
 // CategoryGrid - Component for category grid.
 export { CategoryGrid } from "./features/categories/index.js";
 // [CLIENT-SSR]-Runs in both SSR and browser â€" React component or hook that does not depend on browser-only APIs.
-// CategoryProductsView - Component for category products view.
-export { CategoryProductsView } from "./features/categories/index.js";
 // CategoryProductsListing - Client toolbar listing for category detail pages.
 export { CategoryProductsListing } from "./features/categories/index.js";
 export { CategoriesIndexListing } from "./features/categories/index.js";
@@ -3174,6 +3169,15 @@ export { AdminEventEditorView } from "./features/events/index.js";
 // [SCHEMA]-Schema / data-shape constant â€" Zod validator, default-value object, or Firestore collection/field name constant.
 // EVENTS_COLLECTION - Constant used across modules.
 export { EVENTS_COLLECTION } from "./features/events/index.js";
+/*
+ * [SHARED] RAFFLE_MAX_ENTRIES_PER_USER — one entry per person in a raffle.
+ *
+ * Public because the consumer's participate page must hand the SAME number to
+ * `EventRaffleEntryForm` that `enterEvent` enforces server-side. Two mirrored
+ * literals is the shape that caused the bug: the form already said "you've
+ * used all 1 entry slot" while the server enforced nothing at all.
+ */
+export { RAFFLE_MAX_ENTRIES_PER_USER } from "./_internal/shared/features/events/config.js";
 // [CLIENT-SSR]-Runs in both SSR and browser â€" React component or hook that does not depend on browser-only APIs.
 // EVENT_ADMIN_SORT_OPTIONS - Constant used across modules.
 export { EVENT_ADMIN_SORT_OPTIONS } from "./features/events/index.js";
@@ -3593,8 +3597,6 @@ export { HomepageSkeleton } from "./features/homepage/index.js";
 // HomepageView - Component for homepage view.
 export { HomepageView } from "./features/homepage/index.js";
 // [CLIENT-SSR]-Runs in both SSR and browser â€" React component or hook that does not depend on browser-only APIs.
-// HowItWorksInfoView - Component for how it works info view.
-export { HowItWorksInfoView } from "./features/homepage/index.js";
 // [CLIENT-SSR]-Runs in both SSR and browser â€" React component or hook that does not depend on browser-only APIs.
 // HowItWorksSection - Shared export for how it works section.
 export { HowItWorksSection } from "./features/homepage/index.js";
@@ -3760,8 +3762,13 @@ export { AutoBreadcrumbs } from "./features/layout/index.js";
 // BackToTop - Shared export for back to top.
 export { BackToTop } from "./features/layout/index.js";
 // [CLIENT-SSR]-Runs in both SSR and browser â€" React component or hook that does not depend on browser-only APIs.
-// BottomActions - Shared export for bottom actions.
+// BottomActions - Shared export for bottom actions. @deprecated — alias of SideActionDock.
 export { BottomActions } from "./features/layout/index.js";
+// [CLIENT-SSR]-Runs in both SSR and browser — React component or hook that does not depend on browser-only APIs.
+// SideActionDock - The floating action dock that replaced the bottom action bar.
+export { SideActionDock } from "./features/layout/index.js";
+// [SHARED]-Pure helper — marks a page's inline primary CTA so the dock reveals only after it scrolls out of view.
+export { ctaAnchorProps, CTA_ANCHOR_ATTR } from "./features/layout/index.js";
 // [CLIENT-SSR]-Runs in both SSR and browser â€" React component or hook that does not depend on browser-only APIs.
 // BottomActionsProvider - Component for bottom actions provider.
 export { BottomActionsProvider } from "./features/layout/index.js";
@@ -4302,8 +4309,6 @@ export { ProductTabs } from "./features/products/index.js";
 // [CLIENT-SSR]-Runs in both SSR and browser â€" React component or hook that does not depend on browser-only APIs.
 // ProductsIndexPageView - Component for products index page view.
 // [CLIENT-SSR]-Runs in both SSR and browser â€" React component or hook that does not depend on browser-only APIs.
-// ProductsView - Component for products view.
-export { ProductsView } from "./features/products/index.js";
 // [CLIENT-SSR]-Runs in both SSR and browser â€" React component or hook that does not depend on browser-only APIs.
 // RelatedProducts - Shared export for related products.
 export { RelatedProducts } from "./features/products/index.js";
@@ -4336,7 +4341,7 @@ export { normalizeListingType, isAuctionListing, isPreOrderListing, isStandardLi
 // `finalSale` field. See the module docstring for why `!p.finalSale` is wrong.
 export { isFinalSale, acceptsChangeOfMindReturns, } from "./features/products/constants/final-sale.js";
 // SB-UNI-X4 2026-05-13 â€" per-type feature-flag helpers.
-export { isListingTypeEnabled, isCategoryTypeEnabled, enabledListingTypes, enabledCategoryTypes, ALL_LISTING_TYPES, } from "./_internal/shared/listing-types/feature-flags.js";
+export { isListingTypeEnabled, isCategoryTypeEnabled, enabledListingTypes, enabledCategoryTypes, ALL_LISTING_TYPES, isListingType, } from "./_internal/shared/listing-types/feature-flags.js";
 // SB-UNI-X5 2026-05-13 â€" action telemetry sink.
 export { actionTracker, setActionTrackerSink, resetActionTrackerSink, } from "./_internal/shared/listing-types/action-tracker.js";
 // SB-UNI-S 2026-05-13 â€" cart-level shipping-requirement helpers.
@@ -4733,6 +4738,9 @@ export { useNavSuggestions } from "./features/search/index.js";
 // [CLIENT-SSR]-Runs in both SSR and browser â€" React component or hook that does not depend on browser-only APIs.
 // useSearch - React hook for use search.
 export { useSearch } from "./features/search/index.js";
+// [CLIENT]-Browser only. Fetches the public search artifact once per page session.
+// Exported from the defining module, not the feature barrel — see client.ts.
+export { useSearchIndex, ensureSearchIndex } from "./features/search/hooks/useSearchIndex.js";
 // ./features/search/server
 // [DB]-Database layer â€" uses firebase-admin or another server-side DB SDK; can only run in a trusted server environment.
 // SearchRepository - Shared export for search repository.
@@ -4832,8 +4840,6 @@ export { SellerShippingView } from "./features/seller/index.js";
 // SellerStoreSetupView - Component for seller store setup view.
 export { SellerStoreSetupView } from "./features/seller/index.js";
 // [CLIENT-SSR]-Runs in both SSR and browser â€" React component or hook that does not depend on browser-only APIs.
-// SellerStoreView - Component for seller store view.
-export { SellerStoreView } from "./features/seller/index.js";
 // [CLIENT-SSR]-Runs in both SSR and browser â€" React component or hook that does not depend on browser-only APIs.
 // SellerStorefrontView - Component for seller storefront view.
 export { SellerStorefrontView } from "./features/seller/index.js";
@@ -4869,7 +4875,6 @@ export { SellerProductsView as StoreProductListingsView } from "./features/selle
 // StoreShippingView - Alias for SellerShippingView.
 export { SellerShippingView as StoreShippingView } from "./features/seller/index.js";
 // StoreStorefrontView - Alias for SellerStorefrontView.
-export { SellerStorefrontView as StoreStorefrontView } from "./features/seller/index.js";
 // [CLIENT-SSR]-Runs in both SSR and browser â€" React component or hook that does not depend on browser-only APIs.
 // buildPayoutColumns - Helper for build payout columns.
 export { buildPayoutColumns } from "./features/seller/index.js";
@@ -5349,6 +5354,8 @@ export { CardBody, MenuTrigger, MenuContent, MenuSeparator, RoleBadge, SkipToMai
 export { Tabs, TabsList, TabsTrigger, TabsContent, PasswordStrengthIndicator, TablePagination } from "./ui/index.js";
 // TabBarShell - rail + overflow scroll arrows around a role="tablist"; TabBarButton / TabsNavSelect - its two trigger flavours
 export { TabBarShell, TabBarButton, TabsNavSelect } from "./ui/index.js";
+// OverflowRow - pill/tab row that collapses into a searchable dropdown when it measures wider than its container
+export { OverflowRow } from "./ui/index.js";
 export { Stack, classNames, mergeTailwindClasses, SideModal, SideDrawer, RichText, RichTextRenderer } from "./ui/index.js";
 export { SlottedListingView, DetailViewShell, StackedViewShell } from "./ui/index.js";
 export { buildColumns, createColumnBuilder } from "./ui/index.js";
@@ -5367,7 +5374,7 @@ export { historyRepository, UserHistoryRepository, trackHistoryView, getHistoryF
 export { useMediaQuery, useBreakpoint, useClickOutside, useKeyPress, useLongPress, useGesture, useSwipe, useSession, useAuth, useCountdown, useCamera, useBulkSelection, useUrlTable, usePendingFilters, usePendingTable, useUnsavedChanges, UNSAVED_CHANGES_EVENT, useBulkAction, useEntityDelete, useContainerGrid, useMessage, useModalStack, RTDBPayloadStatus, } from "./react/index.js";
 // Missing core types (already exported above; skipped to avoid duplicates)
 // Missing auth feature components
-export { RoleGate, ProtectedRoute, SocialAuthButtons, AuthStatusPanel, LoginForm, RegisterForm, ForgotPasswordView, ResetPasswordView, VerifyEmailView, OAuthLoadingView, } from "./features/auth/index.js";
+export { RoleGate, ProtectedRoute, SocialAuthButtons, LoginForm, RegisterForm, ForgotPasswordView, ResetPasswordView, VerifyEmailView, OAuthLoadingView } from "./features/auth/index.js";
 // Missing cart and checkout feature components
 export { CartItemRow, CartDrawer, CartView, CartSummary, ShippingPicker } from "./features/cart/index.js";
 export { CheckoutView, CheckoutAddressStep, CheckoutSuccessView } from "./features/cart/index.js";
@@ -5454,6 +5461,7 @@ export { groupedListingFormSchema, groupedListingCreateSchema, groupedListingUpd
 export { scammersSeedData } from "./seed/index.js";
 // Product features â€" seed data (FI2)
 export { productFeaturesSeedData } from "./seed/index.js";
+export { authenticityKnowledgeSeedData, AUTHENTICITY_KNOWLEDGE_COLLECTION, AUTHENTICITY_KNOWLEDGE_COUNT, } from "./seed/index.js";
 /*
  * 🛑 Registering a seed collection takes FOUR edits and three of them are
  * silent if missed: seed/index.ts, THIS re-export, and seed-cli's own import

package/dist/next/api/routeHandler.js

@@ -116,6 +116,15 @@ function shouldPersist(mapped) {
 function resolveBodySchema(schema) {
     if (typeof schema !== "string")
         return schema;
+    /*
+     * `SCHEMAS.api` is empty by design (see its own comment in registry.ts):
+     * the key form had 6 registered keys and ZERO routes passing one, so the
+     * lookup is kept for the contract while `RegisteredApiRouteKey` narrows to
+     * `never`. The cast is what lets an indexed read of an empty literal type
+     * compile; the `!entry` branch below is the whole behaviour — a key string
+     * resolves to nothing and `createRouteHandler` throws "Route schema not
+     * registered", which is the correct answer for a key nobody registered.
+     */
     const entry = SCHEMAS.api[schema];
     if (!entry || !("body" in entry) || !entry.body)
         return null;

package/dist/next/routing/require-record.d.ts

@@ -0,0 +1,13 @@
+export interface RequireRecordOptions {
+    /** `route` field on the persisted degraded-read entry, e.g. "/admin/events/[id]/edit". */
+    route: string;
+    /** Stable identifier for the read site, e.g. "events.findById". */
+    key: string;
+}
+/**
+ * Calls `notFound()` when `read()` resolves to `null` / `undefined`.
+ *
+ * Returns the record when it exists, so a caller that already needs the
+ * document does not pay for a second read.
+ */
+export declare function requireRecord<T>(read: () => Promise<T | null | undefined>, opts: RequireRecordOptions): Promise<T | null>;

package/dist/next/routing/require-record.js

@@ -0,0 +1,62 @@
+import { notFound } from "next/navigation.js";
+import { safeRead } from "../../errors/safe-read.js";
+/**
+ * 404 a dynamic detail page whose record does not exist.
+ *
+ * ## The defect this closes
+ *
+ * `/admin/coupons/zzzznope-not-a-coupon-42/edit` rendered a fully editable
+ * coupon form — twelve inputs, "Save changes", "Delete coupon" — because its
+ * `page.tsx` was a bare shim that passed the id straight to an editor. The
+ * sibling `/admin/orders/[id]/view` fetched server-side and 404'd correctly;
+ * the two differed only because one never grew the check. `audit-admin-detail-notfound`
+ * found **fourteen** more, and the danger is Root Cause #98's: the form looks
+ * ready to save, and what it saves is a record keyed on an id nobody meant to
+ * create.
+ *
+ * ## 🛑 A FAILED read is not an ABSENT record
+ *
+ * This is the whole subtlety, and it is why the helper exists rather than each
+ * page writing `if (!(await repo.findById(id))) notFound()`.
+ *
+ * Dashboard pages sit under a layout that `await`s the session, so Next still
+ * ATTEMPTS to prerender them and an unguarded throw there is **fatal to the
+ * build** (§ "a dynamic API in a DASHBOARD layout is the correct lever"). The
+ * read therefore has to go through `safeRead`. But `safeRead` returns its
+ * fallback on failure — so a naive `fallback: null` would turn a transient
+ * Firestore error, a missing composite index, or a quota exception into a
+ * **404 on a record that exists**. That is strictly worse than the bug being
+ * fixed: the admin is told their data is gone.
+ *
+ * So failure and absence are separated by a sentinel. `notFound()` fires ONLY
+ * when the read succeeded and returned nothing. When the read fails the page
+ * renders, the degradation is recorded as a `DEGRADED_READ` row by `safeRead`
+ * itself, and the editor's own fetch surfaces whatever is really wrong.
+ *
+ * ## Cost
+ *
+ * One document read, on a route that is per-request anyway. Well inside Rule
+ * #6's ~3-round-trip budget, and the editor's client fetch is unchanged — this
+ * does not replace it, because the editor is also reachable from a drawer.
+ */
+/** Distinguishes "the read threw" from "the record is absent". */
+const READ_FAILED = Symbol("read-failed");
+/**
+ * Calls `notFound()` when `read()` resolves to `null` / `undefined`.
+ *
+ * Returns the record when it exists, so a caller that already needs the
+ * document does not pay for a second read.
+ */
+export async function requireRecord(read, opts) {
+    const result = await safeRead(read, {
+        route: opts.route,
+        key: opts.key,
+        fallback: READ_FAILED,
+    });
+    // The read itself broke. Render the page; `safeRead` has already recorded it.
+    if (result === READ_FAILED)
+        return null;
+    if (result === null || result === undefined)
+        notFound();
+    return result;
+}

package/dist/next/routing/route-map.d.ts

@@ -63,7 +63,6 @@ export declare const DEFAULT_ROUTE_MAP: {
         readonly ABOUT: "/about";
         readonly DEVELOPER: "/developer";
         readonly CONTACT: "/contact";
-        readonly BLOG: "/blog";
         readonly HELP: "/help";
         readonly HELP_SHOPPING: "/help/shopping";
         readonly HELP_AUCTIONS: "/help/auctions";
@@ -100,7 +99,6 @@ export declare const DEFAULT_ROUTE_MAP: {
         readonly EVENT_SPIN_RESULTS: (id: string) => string;
         readonly LOTTERIES: "/lottery";
         readonly LOTTERY_DETAIL: (id: string) => string;
-        readonly SUBLISTING_CATEGORIES: "/sublisting-categories";
         readonly SUBLISTING_CATEGORY: (slug: string) => string;
         readonly SUPPORT: "/support";
         readonly SCAMS: "/scams";
@@ -112,6 +110,8 @@ export declare const DEFAULT_ROUTE_MAP: {
         readonly ITEM_REQUESTS_NEW: "/item-requests/new";
         readonly TOOLS: "/tools";
         readonly TOOL_PRICE_INDEX: "/tools/price-index";
+        readonly TOOL_STICKER_TRACER: "/tools/sticker-tracer";
+        readonly TOOL_STICKER_SHEET: (sheetId: string) => string;
         readonly PARTS: "/parts";
         readonly PART_CLASSIFICATION: (classification: string) => string;
         readonly PART_DETAIL: (classification: string, code: string) => string;
@@ -479,7 +479,6 @@ export declare const ROUTES: {
         readonly ABOUT: "/about";
         readonly DEVELOPER: "/developer";
         readonly CONTACT: "/contact";
-        readonly BLOG: "/blog";
         readonly HELP: "/help";
         readonly HELP_SHOPPING: "/help/shopping";
         readonly HELP_AUCTIONS: "/help/auctions";
@@ -516,7 +515,6 @@ export declare const ROUTES: {
         readonly EVENT_SPIN_RESULTS: (id: string) => string;
         readonly LOTTERIES: "/lottery";
         readonly LOTTERY_DETAIL: (id: string) => string;
-        readonly SUBLISTING_CATEGORIES: "/sublisting-categories";
         readonly SUBLISTING_CATEGORY: (slug: string) => string;
         readonly SUPPORT: "/support";
         readonly SCAMS: "/scams";
@@ -528,6 +526,8 @@ export declare const ROUTES: {
         readonly ITEM_REQUESTS_NEW: "/item-requests/new";
         readonly TOOLS: "/tools";
         readonly TOOL_PRICE_INDEX: "/tools/price-index";
+        readonly TOOL_STICKER_TRACER: "/tools/sticker-tracer";
+        readonly TOOL_STICKER_SHEET: (sheetId: string) => string;
         readonly PARTS: "/parts";
         readonly PART_CLASSIFICATION: (classification: string) => string;
         readonly PART_DETAIL: (classification: string, code: string) => string;

package/dist/next/routing/route-map.js

@@ -63,7 +63,14 @@ export const DEFAULT_ROUTE_MAP = {
         ABOUT: "/about",
         DEVELOPER: "/developer",
         CONTACT: "/contact",
-        BLOG: "/blog",
+        /*
+         * 🛑 No `PUBLIC.BLOG`. `BLOG.LIST` is the one key for "/blog", and it sits
+         * beside `BLOG.ARTICLE` — which is the ONLY blog detail key, so `BLOG` was
+         * always the canonical section and `PUBLIC.BLOG` was an alias of its index.
+         * Two keys for one path is Root Cause #61's family: the duplicate was
+         * reported by `audit-dead-route-key` on every run, and nine call sites had
+         * drifted onto the alias while one used the real key.
+         */
         HELP: "/help",
         HELP_SHOPPING: "/help/shopping",
         HELP_AUCTIONS: "/help/auctions",
@@ -119,7 +126,14 @@ export const DEFAULT_ROUTE_MAP = {
         EVENT_SPIN_RESULTS: (id) => `/events/${id}/spin-results`,
         LOTTERIES: "/lottery",
         LOTTERY_DETAIL: (id) => `/lottery/${id}`,
-        SUBLISTING_CATEGORIES: "/sublisting-categories",
+        /*
+          * 🛑 There is deliberately NO public `SUBLISTING_CATEGORIES` index key.
+          * `src/app/[locale]/sublisting-categories/` holds only `[slug]/`, so the
+          * index has never existed; the key promised a route with no page behind
+          * it, had zero references anywhere, and `audit-dead-route-key` carried it
+          * as its one grandfathered entry. A sub-listing is reached from the
+          * category or product it belongs to, not from a top-level list.
+          */
         SUBLISTING_CATEGORY: (slug) => `/sublisting-categories/${slug}`,
         SUPPORT: "/support",
         SCAMS: "/scams",
@@ -138,6 +152,14 @@ export const DEFAULT_ROUTE_MAP = {
          */
         TOOLS: "/tools",
         TOOL_PRICE_INDEX: "/tools/price-index",
+        /*
+         * Admin-only, and under a PUBLIC prefix on purpose — it is a tool, and
+         * /tools is where tools live. The guard is the layout, not the path: a
+         * non-admin is redirected server-side before any HTML is produced, so
+         * there is nothing indexable at this URL regardless of robots.txt.
+         */
+        TOOL_STICKER_TRACER: "/tools/sticker-tracer",
+        TOOL_STICKER_SHEET: (sheetId) => `/tools/sticker-tracer/${sheetId}`,
         /*
          * The PARTS database. A reference surface, so it lives beside the other
          * two things that answer a question rather than sell you something.
@@ -552,7 +574,7 @@ export const PUBLIC_ROUTES = [
     ROUTES.PUBLIC.PROMOTIONS,
     ROUTES.PUBLIC.ABOUT,
     ROUTES.PUBLIC.CONTACT,
-    ROUTES.PUBLIC.BLOG,
+    ROUTES.BLOG.LIST,
     ROUTES.PUBLIC.HELP,
     ROUTES.PUBLIC.TERMS,
     ROUTES.PUBLIC.PRIVACY,

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

@@ -19,6 +19,7 @@
  */
 import type { CollectionReference, DocumentData, DocumentSnapshot, Firestore } from "firebase-admin/firestore";
 import type { IRepository, PagedResult, SieveQuery, WhereOp } from "../../contracts";
+import type { Plaintext } from "../../security/encrypted";
 export declare class FirebaseRepository<T extends DocumentData> implements IRepository<T> {
     protected readonly collection: string;
     constructor(collectionName: string);
@@ -29,8 +30,9 @@ export declare class FirebaseRepository<T extends DocumentData> implements IRepo
     findById(id: string): Promise<T | null>;
     findAll(query?: SieveQuery): Promise<PagedResult<T>>;
     findWhere(field: keyof T, op: WhereOp, value: unknown): Promise<T[]>;
-    create(data: Omit<T, "id" | "createdAt" | "updatedAt">): Promise<T>;
-    update(id: string, data: Partial<T>): Promise<T>;
+    create(data: Omit<Plaintext<T>, "id" | "createdAt" | "updatedAt">): Promise<T>;
+    /** Accepts the PLAINTEXT shape — see `create` for why. */
+    update(id: string, data: Partial<Plaintext<T>>): Promise<T>;
     delete(id: string): Promise<void>;
     batchCreate(items: Array<Omit<T, "id" | "createdAt" | "updatedAt">>): Promise<T[]>;
     batchDelete(ids: string[]): Promise<void>;

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

@@ -46,7 +46,7 @@ export class FirebaseRepository {
     }
     async findAll(query) {
         const page = Math.max(1, query?.page ?? 1);
-        const perPage = Math.max(1, Math.min(query?.perPage ?? 20, 500));
+        const pageSize = Math.max(1, Math.min(query?.pageSize ?? 20, 500));
         let q = this.getCollection();
         // -- Sort ------------------------------------------------------------------
         // SieveQuery.sort supports a leading "-" prefix for descending order
@@ -89,11 +89,11 @@ export class FirebaseRepository {
         // -- Count -----------------------------------------------------------------
         const total = await getFirestoreCount(q);
         // -- Paginate --------------------------------------------------------------
-        const offset = (page - 1) * perPage;
-        const pagedSnap = await q.offset(offset).limit(perPage).get();
+        const offset = (page - 1) * pageSize;
+        const pagedSnap = await q.offset(offset).limit(pageSize).get();
         const data = pagedSnap.docs.map((d) => this.mapDoc(d));
-        const totalPages = total === 0 ? 0 : Math.max(1, Math.ceil(total / perPage));
-        return { data, total, page, perPage, totalPages };
+        const totalPages = total === 0 ? 0 : Math.max(1, Math.ceil(total / pageSize));
+        return { data, total, page, pageSize, totalPages };
     }
     async findWhere(field, op, value) {
         const snap = await this.getCollection()
@@ -102,6 +102,21 @@ export class FirebaseRepository {
         return snap.docs.map((d) => this.mapDoc(d));
     }
     // -- IWriteRepository -------------------------------------------------------
+    /*
+     * 🛑 Accepts the PLAINTEXT shape, because this method ENCRYPTS.
+     *
+     * `applyWriteHooks` runs `encryptPiiFields` over the subclass's `piiFields`,
+     * so a caller legitimately hands over a real email and gets ciphertext in
+     * Firestore. Typing the parameter `Omit<T, …>` demanded `Encrypted<string>`
+     * from every caller — and the only way to produce one without encrypting is
+     * `asEncrypted(value)`, which labels plaintext as ciphertext and is the
+     * misuse that helper's own docstring forbids. The alternative was a cast at
+     * each of the dozens of write sites across fourteen repositories; one honest
+     * signature here is the same change made once.
+     *
+     * `Plaintext<T>` is the identity on any document with no branded field, so
+     * this is a no-op for every repository that holds no PII.
+     */
     async create(data) {
         const now = new Date();
         const payload = prepareForFirestore({
@@ -113,6 +128,7 @@ export class FirebaseRepository {
         const snap = await ref.get();
         return this.mapDoc(snap);
     }
+    /** Accepts the PLAINTEXT shape — see `create` for why. */
     async update(id, data) {
         const payload = prepareForFirestore({
             ...data,

package/dist/providers/db-firebase/base.repository.d.ts

@@ -1,3 +1,4 @@
+import type { Plaintext } from "../../security/encrypted";
 import type { FirestoreDocument } from "@mohasinac/appkit";
 import type { CollectionReference, DocumentData, DocumentReference, DocumentSnapshot, Firestore, Query, Transaction, WriteBatch } from "firebase-admin/firestore";
 import { type FirebaseSieveFields, type FirebaseSieveOptions, type FirebaseSieveResult, type SieveModel } from "./sieve";
@@ -111,7 +112,7 @@ export declare abstract class BaseRepository<T extends DocumentData> {
         doc: T | null | undefined;
         patch: Partial<T>;
     }>): Promise<number>;
-    create(data: Partial<T> | FirestoreDocument): Promise<T>;
+    create(data: Partial<Plaintext<T>> | FirestoreDocument): Promise<T>;
     /**
      * Write a document at a CALLER-CHOSEN id.
      *
@@ -143,8 +144,9 @@ export declare abstract class BaseRepository<T extends DocumentData> {
      * NAME: `createWithId` reads as "create" and behaves as "replace", and that
      * gap is what made the wrong conclusion so easy to reach.
      */
-    createWithId(id: string, data: Partial<T>): Promise<T>;
-    update(id: string, data: Partial<T>): Promise<T>;
+    createWithId(id: string, data: Partial<Plaintext<T>>): Promise<T>;
+    /** Accepts the PLAINTEXT shape — see `create` for why. */
+    update(id: string, data: Partial<Plaintext<T>>): Promise<T>;
     delete(id: string): Promise<void>;
     exists(id: string): Promise<boolean>;
     /**
@@ -195,12 +197,12 @@ export declare abstract class BaseRepository<T extends DocumentData> {
     }): Promise<Record<string, number | undefined>>;
     findByIdInTx(tx: Transaction, id: string): Promise<T | null>;
     findByIdOrFailInTx(tx: Transaction, id: string): Promise<T>;
-    createInTx(tx: Transaction, data: Partial<T> | FirestoreDocument): DocumentReference;
-    createWithIdInTx(tx: Transaction, id: string, data: Partial<T> | FirestoreDocument): DocumentReference;
-    updateInTx(tx: Transaction, id: string, data: Partial<T>): void;
+    createInTx(tx: Transaction, data: Partial<Plaintext<T>> | FirestoreDocument): DocumentReference;
+    createWithIdInTx(tx: Transaction, id: string, data: Partial<Plaintext<T>> | FirestoreDocument): DocumentReference;
+    updateInTx(tx: Transaction, id: string, data: Partial<Plaintext<T>>): void;
     deleteInTx(tx: Transaction, id: string): void;
-    createInBatch(batch: WriteBatch, data: Partial<T> | FirestoreDocument): DocumentReference;
-    createWithIdInBatch(batch: WriteBatch, id: string, data: Partial<T> | FirestoreDocument): void;
-    updateInBatch(batch: WriteBatch, id: string, data: Partial<T>): void;
+    createInBatch(batch: WriteBatch, data: Partial<Plaintext<T>> | FirestoreDocument): DocumentReference;
+    createWithIdInBatch(batch: WriteBatch, id: string, data: Partial<Plaintext<T>> | FirestoreDocument): void;
+    updateInBatch(batch: WriteBatch, id: string, data: Partial<Plaintext<T>>): void;
     deleteInBatch(batch: WriteBatch, id: string): void;
 }

package/dist/providers/db-firebase/base.repository.js

@@ -268,6 +268,21 @@ export class BaseRepository {
         await batch.commit();
         return present.length;
     }
+    /*
+     * 🛑 Accepts the PLAINTEXT shape, because this method ENCRYPTS.
+     *
+     * `applyWriteHooks` runs `encryptPiiFields` over the subclass's `piiFields`,
+     * so a caller legitimately hands over a real email and Firestore holds
+     * ciphertext. Typing this `Partial<T>` demanded `Encrypted<string>` from
+     * every caller once the PII fields were branded — and the only way to make
+     * one without encrypting is `asEncrypted(value)`, which labels plaintext as
+     * ciphertext and is the misuse that helper's docstring forbids. The
+     * alternative was a cast at each of the dozens of write sites across
+     * fourteen repositories; one honest signature here is that change made once.
+     *
+     * `Plaintext<T>` is the identity on a document with no branded member, so
+     * this is a no-op for every repository holding no PII.
+     */
     async create(data) {
         try {
             const cleanData = prepareForFirestore({
@@ -315,6 +330,7 @@ export class BaseRepository {
      * NAME: `createWithId` reads as "create" and behaves as "replace", and that
      * gap is what made the wrong conclusion so easy to reach.
      */
+    // Plaintext<T> — these methods ENCRYPT via applyWriteHooks; see `create`.
     async createWithId(id, data) {
         try {
             const now = new Date();
@@ -339,6 +355,7 @@ export class BaseRepository {
             throw new DatabaseError(`Failed to create document with ID: ${id}: ${detailOf(error)}`, error);
         }
     }
+    /** Accepts the PLAINTEXT shape — see `create` for why. */
     async update(id, data) {
         try {
             const cleanData = prepareForFirestore({
@@ -496,6 +513,7 @@ export class BaseRepository {
         }));
         return docRef;
     }
+    // Plaintext<T> — these methods ENCRYPT via applyWriteHooks; see `create`.
     updateInTx(tx, id, data) {
         const docRef = this.getCollection().doc(id);
         tx.update(docRef, prepareForFirestore({ ...this.applyWriteHooks(data), updatedAt: new Date() }));
@@ -523,6 +541,7 @@ export class BaseRepository {
             updatedAt: now,
         }));
     }
+    // Plaintext<T> — these methods ENCRYPT via applyWriteHooks; see `create`.
     updateInBatch(batch, id, data) {
         const docRef = this.getCollection().doc(id);
         batch.update(docRef, prepareForFirestore({ ...this.applyWriteHooks(data), updatedAt: new Date() }));

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

@@ -34,4 +34,16 @@ export declare const RTDB_PATHS: {
      * Pruned by `cleanupRtdbEvents`'s sixth block.
      */
     readonly CHAT_EVENTS: "chat_events";
+    /**
+     * Per-run progress for the sticker kiss-cut tracer — stage, pct, parts and
+     * shards done. The DURABLE record is `stickerTraceRuns.events[]`; this is
+     * only the live bar, which is why losing it is survivable and why the run
+     * document is what a failure is diagnosed from weeks later.
+     *
+     * 🛑 Pruned at SIXTY minutes, not fifteen. A `max`-tier fan-out across sixty
+     * parts can outlast a fifteen-minute window, and a channel pruned mid-run
+     * reads to the client as "it died" — the same false negative `EMAIL_EVENTS`
+     * carries a longer window to avoid.
+     */
+    readonly STICKER_TRACE: "sticker_trace";
 };

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

@@ -34,4 +34,16 @@ export const RTDB_PATHS = {
      * Pruned by `cleanupRtdbEvents`'s sixth block.
      */
     CHAT_EVENTS: "chat_events",
+    /**
+     * Per-run progress for the sticker kiss-cut tracer — stage, pct, parts and
+     * shards done. The DURABLE record is `stickerTraceRuns.events[]`; this is
+     * only the live bar, which is why losing it is survivable and why the run
+     * document is what a failure is diagnosed from weeks later.
+     *
+     * 🛑 Pruned at SIXTY minutes, not fifteen. A `max`-tier fan-out across sixty
+     * parts can outlast a fifteen-minute window, and a channel pruned mid-run
+     * reads to the client as "it died" — the same false negative `EMAIL_EVENTS`
+     * carries a longer window to avoid.
+     */
+    STICKER_TRACE: "sticker_trace",
 };

package/dist/react/ErrorBoundary.js

@@ -10,7 +10,12 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  */
 import { Component } from "react";
 import { Logger } from "../core/Logger.js";
-import { Button, Heading, Text } from "../ui/index.js";
+// Defining modules, not the sibling barrel — Root Cause #18. `ui/index.ts` and
+// `react/index.ts` re-exported into each other, which is the whole of
+// `audit-import-cycles` component 1: an 18-module knot held together entirely
+// by barrel hops, none of which needed the barrel.
+import { Button } from "../ui/components/Button.js";
+import { Heading, Text } from "../ui/components/Typography.js";
 import { trackError, ErrorCategory, ErrorSeverity, } from "../monitoring/error-tracking.js";
 function DefaultFallback({ error, onReset, }) {
     return (_jsxs("div", { role: "alert", style: {

package/dist/react/hooks/realtime-event-constants.d.ts

@@ -20,6 +20,7 @@ export declare const RealtimeEventType: {
     readonly CHAT: "chat";
     readonly BID: "bid";
     readonly BULK: "bulk";
+    readonly STICKER_TRACE: "sticker-trace";
 };
 export type RealtimeEventType = (typeof RealtimeEventType)[keyof typeof RealtimeEventType];
 export declare const RealtimeEventStatus: {

package/dist/react/hooks/realtime-event-constants.js

@@ -19,6 +19,14 @@ export const RealtimeEventType = {
     CHAT: "chat",
     BID: "bid",
     BULK: "bulk",
+    /*
+     * The sticker kiss-cut tracer's per-run progress channel. Added rather than
+     * reusing BULK: the type selects this event's message strings and its
+     * claim/path conventions, and a trace reports a STAGE out of eleven where a
+     * bulk job reports a count — borrowing BULK's vocabulary would make the
+     * progress row say the wrong thing about every failure.
+     */
+    STICKER_TRACE: "sticker-trace",
 };
 export const RealtimeEventStatus = {
     IDLE: "idle",

package/dist/react/hooks/useEntityDelete.js

@@ -1,7 +1,11 @@
 "use client";
 import { normalizeError } from "../../errors/normalize.js";
 import { useState, useCallback } from "react";
-import { useToast } from "../../ui/index.js";
+// Defining modules, not the sibling barrel — Root Cause #18. `ui/index.ts` and
+// `react/index.ts` re-exported into each other, which is the whole of
+// `audit-import-cycles` component 1: an 18-module knot held together entirely
+// by barrel hops, none of which needed the barrel.
+import { useToast } from "../../ui/components/toast-context.js";
 export function useEntityDelete(opts) {
     const [deletingId, setDeletingId] = useState(null);
     const { showToast } = useToast();

package/dist/react/hooks/useMessage.js

@@ -10,7 +10,11 @@
  * inline (e.g. reviews, settings views).
  */
 import { useState, useCallback, useRef, useEffect } from "react";
-import { useToast } from "../../ui/index.js";
+// Defining modules, not the sibling barrel — Root Cause #18. `ui/index.ts` and
+// `react/index.ts` re-exported into each other, which is the whole of
+// `audit-import-cycles` component 1: an 18-module knot held together entirely
+// by barrel hops, none of which needed the barrel.
+import { useToast } from "../../ui/components/toast-context.js";
 export function useMessage() {
     const { showToast } = useToast();
     const [message, setMessage] = useState(null);