@mohasinac/appkit 4.30.18 → 4.31.0

package/dist/features/auth/components/RegisterForm.js

@@ -1,15 +1,16 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { normalizeError } from "../../../errors/normalize";
-import { useState } from "react";
+import React, { useState } from "react";
 import { z } from "zod";
-import { Alert, Button, Div, Heading, Row, SiteMark, Stack, Text, useToast } from "../../../ui";
-import { Form } from "../../../ui/components/Form";
+import { Alert, Div, Heading, Row, SiteMark, Stack, Text } from "../../../ui";
 import { FieldInput } from "../../../ui/forms/FieldInput";
 import { FieldCheckbox } from "../../../ui/forms/FieldCheckbox";
 import { applyZodIssues } from "../../../ui/forms/apply-zod-issues";
+import { FormShellContext, useFormShellState } from "../../../ui/forms/FormShell";
 import { registerSchema, registerPasswordSchema } from "../schemas";
 import { FormErrorSummary } from "../../../ui/forms/FormErrorSummary";
+import { SectionForm, useSectionFormNav } from "../../shell/SectionForm";
 const registerClientSchema = registerSchema.extend({
     displayName: z.string().min(1, "Enter your name"),
     confirmPassword: registerPasswordSchema,
@@ -20,8 +21,35 @@ const registerClientSchema = registerSchema.extend({
     message: "Passwords do not match",
     path: ["confirmPassword"],
 });
+/*
+ * Hand-authored rather than derived from the schema, which is the exception
+ * here and not the rule.
+ *
+ * Two reasons the generator is the wrong tool for this one form. `labels` is a
+ * PUBLIC prop of a published component — every string below is consumer
+ * overridable, and moving them into schema annotations would silently drop that
+ * override for anyone outside this repo. And `renderPasswordStrength` /
+ * `renderTermsLink` are POSITIONAL slots: a meter that must sit under the
+ * password box, a terms line that must sit under the checkbox. The generator
+ * places fields, not arbitrary nodes between them.
+ *
+ * One section, `required: true` — so it renders open, without a collapse
+ * control, i.e. exactly the flat list it has always been. A five-field signup
+ * form has nothing to group; what it gains here is the error→section
+ * attribution that makes `<FormErrorSummary>` able to jump to a field.
+ */
+function buildSections(labels, renderPasswordStrength, renderTermsLink) {
+    return [
+        {
+            id: "account",
+            label: labels.title ?? "Create Account",
+            required: true,
+            fields: ["displayName", "email", "password", "confirmPassword", "acceptTerms"],
+            render: ({ values, onChange }) => (_jsxs(_Fragment, { children: [_jsx(FieldInput, { name: "displayName", label: labels.displayNameLabel ?? "Full name", type: "text", autoComplete: "name", required: true, placeholder: labels.displayNamePlaceholder ?? "Your name", value: values.displayName, onChange: (v) => onChange({ displayName: v }) }), _jsx(FieldInput, { name: "email", label: labels.emailLabel ?? "Email address", type: "email", autoComplete: "username", required: true, placeholder: labels.emailPlaceholder ?? "you@example.com", value: values.email, onChange: (v) => onChange({ email: v }) }), _jsxs(Div, { children: [_jsx(FieldInput, { name: "password", label: labels.passwordLabel ?? "Password", type: "password", autoComplete: "new-password", required: true, placeholder: labels.passwordPlaceholder ?? "••••••••", value: values.password, onChange: (v) => onChange({ password: v }) }), renderPasswordStrength?.(values.password)] }), _jsx(FieldInput, { name: "confirmPassword", label: labels.confirmPasswordLabel ?? "Confirm password", type: "password", autoComplete: "new-password", required: true, placeholder: labels.confirmPasswordPlaceholder ?? "••••••••", value: values.confirmPassword, onChange: (v) => onChange({ confirmPassword: v }) }), _jsx(FieldCheckbox, { name: "acceptTerms", label: `${labels.acceptTermsLabel ?? "I accept the terms"}`, checked: values.acceptTerms, onChange: (c) => onChange({ acceptTerms: c }) }), renderTermsLink && (_jsx(Text, { size: "xs", variant: "secondary", children: renderTermsLink() }))] })),
+        },
+    ];
+}
 export function RegisterForm({ onSubmit, isLoading = false, error, success, labels = {}, renderSocialButtons, renderLoginLink, renderTermsLink, renderPasswordStrength, className = "", }) {
-    const { showToast } = useToast();
     const [values, setValues] = useState({
         email: "",
         password: "",
@@ -29,19 +57,34 @@ export function RegisterForm({ onSubmit, isLoading = false, error, success, labe
         displayName: "",
         acceptTerms: false,
     });
-    return (_jsx(Row, { className: `min-h-[60vh] ${className}`, align: "center", justify: "center", padding: "x-md", children: _jsxs(Stack, { className: "max-w-md w-full", gap: "lg", children: [_jsxs(Div, { className: "text-center", children: [_jsx(Row, { justify: "center", className: "mb-3", children: _jsx(SiteMark, { size: "lg" }) }), _jsx(Heading, { level: 1, className: "font-extrabold", size: "3xl", children: labels.title ?? "Create Account" }), (labels.subtitle || renderLoginLink) && (_jsxs(Text, { className: "mt-2 text-[var(--appkit-color-text-muted)]", size: "sm", children: [labels.subtitle ?? "Already have an account?", " ", renderLoginLink?.()] }))] }), success && (_jsx(Alert, { variant: "success", compact: true, children: success })), error && (_jsx(Alert, { variant: "error", compact: true, children: error })), _jsx(Form, { schema: registerClientSchema, noValidate: true, onSubmit: (e) => e.preventDefault(), spacing: "md", children: ({ setFieldError, clearErrors }) => (_jsxs(_Fragment, { children: [_jsx(FormErrorSummary, {}), _jsx(FieldInput, { name: "displayName", label: labels.displayNameLabel ?? "Full name", type: "text", autoComplete: "name", required: true, placeholder: labels.displayNamePlaceholder ?? "Your name", value: values.displayName, onChange: (v) => setValues({ ...values, displayName: v }) }), _jsx(FieldInput, { name: "email", label: labels.emailLabel ?? "Email address", type: "email", autoComplete: "username", required: true, placeholder: labels.emailPlaceholder ?? "you@example.com", value: values.email, onChange: (v) => setValues({ ...values, email: v }) }), _jsxs(Div, { children: [_jsx(FieldInput, { name: "password", label: labels.passwordLabel ?? "Password", type: "password", autoComplete: "new-password", required: true, placeholder: labels.passwordPlaceholder ?? "••••••••", value: values.password, onChange: (v) => setValues({ ...values, password: v }) }), renderPasswordStrength?.(values.password)] }), _jsx(FieldInput, { name: "confirmPassword", label: labels.confirmPasswordLabel ?? "Confirm password", type: "password", autoComplete: "new-password", required: true, placeholder: labels.confirmPasswordPlaceholder ?? "••••••••", value: values.confirmPassword, onChange: (v) => setValues({ ...values, confirmPassword: v }) }), _jsx(FieldCheckbox, { name: "acceptTerms", label: `${labels.acceptTermsLabel ?? "I accept the terms"}`, checked: values.acceptTerms, onChange: (c) => setValues({ ...values, acceptTerms: c }) }), renderTermsLink && (_jsx(Text, { size: "xs", variant: "secondary", children: renderTermsLink() })), _jsx(Button, { type: "submit", isLoading: isLoading, disabled: isLoading, className: "w-full", onClick: async () => {
-                                    clearErrors();
-                                    const parsed = registerClientSchema.safeParse(values);
-                                    if (!parsed.success)
-                                        return applyZodIssues(parsed.error.issues, setFieldError);
-                                    try {
-                                        await onSubmit(values);
-                                    }
-                                    catch (err) {
-                                        void normalizeError(err);
-                                        showToast(err instanceof Error ? err.message : "Registration failed", "error");
-                                    }
-                                }, children: isLoading
-                                    ? (labels.submittingLabel ?? "Creating account…")
-                                    : (labels.submitLabel ?? "Create account") })] })) }), renderSocialButtons?.()] }) }));
+    const sections = React.useMemo(() => buildSections(labels, renderPasswordStrength, renderTermsLink), [labels, renderPasswordStrength, renderTermsLink]);
+    const nav = useSectionFormNav(sections, values, { scope: "auth:register" });
+    const { shellCtx, setFieldError, clearErrors } = useFormShellState(registerClientSchema, {
+        sections: nav.sectionMeta,
+        onGoToSection: nav.goToSection,
+        fieldToSectionIndex: nav.fieldToSectionIndex,
+    });
+    const handleSubmit = async () => {
+        clearErrors();
+        const parsed = registerClientSchema.safeParse(values);
+        if (!parsed.success) {
+            applyZodIssues(parsed.error.issues, setFieldError);
+            return;
+        }
+        try {
+            await onSubmit(values);
+        }
+        catch (err) {
+            /*
+             * On a field, not a toast. "Registration failed" told the user nothing
+             * and discarded whatever the caller actually objected to — a taken
+             * email, a rejected password — which is the one thing they can act on.
+             */
+            const normalized = normalizeError(err);
+            setFieldError("email", normalized.message || "Registration failed");
+        }
+    };
+    return (_jsx(Row, { className: `min-h-[60vh] ${className}`, align: "center", justify: "center", padding: "x-md", children: _jsxs(Stack, { className: "max-w-md w-full", gap: "lg", children: [_jsxs(Div, { className: "text-center", children: [_jsx(Row, { justify: "center", className: "mb-3", children: _jsx(SiteMark, { size: "lg" }) }), _jsx(Heading, { level: 1, className: "font-extrabold", size: "3xl", children: labels.title ?? "Create Account" }), (labels.subtitle || renderLoginLink) && (_jsxs(Text, { className: "mt-2 text-[var(--appkit-color-text-muted)]", size: "sm", children: [labels.subtitle ?? "Already have an account?", " ", renderLoginLink?.()] }))] }), success && (_jsx(Alert, { variant: "success", compact: true, children: success })), error && (_jsx(Alert, { variant: "error", compact: true, children: error })), _jsxs(FormShellContext.Provider, { value: shellCtx, children: [_jsx(FormErrorSummary, {}), _jsx(SectionForm, { sections: sections, values: values, onChange: (partial) => setValues((prev) => Object.assign({}, prev, partial)), onSubmit: handleSubmit, schema: registerClientSchema, openIds: nav.openIds, onOpenChange: nav.setOpenIds, isLoading: isLoading, submitLabel: isLoading
+                                ? (labels.submittingLabel ?? "Creating account…")
+                                : (labels.submitLabel ?? "Create account") })] }), renderSocialButtons?.()] }) }));
 }

package/dist/features/auth/components/ResetPasswordView.js

@@ -30,7 +30,7 @@ export function ResetPasswordView({ oobCode, onSubmit, isLoading = false, error,
             }
             catch (err) {
                 void normalizeError(err);
-                showToast(err instanceof Error ? err.message : "Password reset failed", "error");
+                showToast("Password reset failed", "error");
             }
         };
     }

package/dist/features/auth/hooks/useAuth.js

@@ -315,6 +315,9 @@ export function useRegister(options) {
             // fail registration — the user can re-request verification later.
             try {
                 await authProvider.sendEmailVerification();
+                // Non-fatal by design: the account already exists, and the user can
+                // re-request verification from Settings at any time. Firebase surfaces
+                // its own send failures; failing registration here would be worse.
             }
             catch (err) {
                 void normalizeError(err);

package/dist/features/auth/permissions/constants.d.ts

@@ -11,7 +11,33 @@
  * Permission naming: admin:resource:action
  * Ban action naming: plain verb phrase — write_reviews, place_bids, etc.
  */
-export type Permission = "admin:dashboard:view" | "admin:users:read" | "admin:users:write" | "admin:users:delete" | "admin:user-bans:read" | "admin:user-bans:write" | "admin:products:read" | "admin:products:write" | "admin:products:delete" | "admin:orders:read" | "admin:orders:write" | "admin:returns:read" | "admin:returns:write" | "admin:stores:read" | "admin:stores:write" | "admin:store-addresses:read" | "admin:addresses:read" | "admin:addresses:write" | "admin:analytics:view" | "admin:payouts:read" | "admin:payouts:write" | "admin:audit-log:read" | "admin:categories:read" | "admin:categories:write" | "admin:categories:delete" | "admin:brands:read" | "admin:brands:write" | "admin:brands:delete" | "admin:coupons:read" | "admin:coupons:write" | "admin:coupons:delete" | "admin:deals:read" | "admin:deals:write" | "admin:featured:read" | "admin:featured:write" | "admin:reviews:read" | "admin:reviews:write" | "admin:reviews:delete" | "admin:blog:read" | "admin:blog:write" | "admin:blog:delete" | "admin:blog:publish" | "admin:bids:read" | "admin:bids:write" | "admin:offers:read" | "admin:offers:write" | "admin:media:read" | "admin:media:write" | "admin:media:delete" | "admin:site:read" | "admin:site:write" | "admin:settings:write" | "admin:navigation:read" | "admin:navigation:write" | "admin:sections:read" | "admin:sections:write" | "admin:carousel:read" | "admin:carousel:write" | "admin:carousel:delete" | "admin:ads:read" | "admin:ads:write" | "admin:ads:delete" | "admin:faqs:read" | "admin:faqs:write" | "admin:faqs:delete" | "admin:tester-checklist:read" | "admin:tester-checklist:write" | "admin:tester-checklist:delete" | "admin:tester-feedback:read" | "admin:tester-feedback:write" | "admin:newsletter:read" | "admin:newsletter:write" | "admin:contact:read" | "admin:events:read" | "admin:events:write" | "admin:events:delete" | "admin:event-entries:read" | "admin:event-entries:write" | "admin:support-tickets:read" | "admin:support-tickets:write" | "admin:shipments:read" | "admin:shipments:write" | "admin:catalogue:read" | "admin:catalogue:write" | "admin:grouped-listings:read" | "admin:grouped-listings:write" | "admin:support-tickets:assign" | "admin:support-tickets:close" | "admin:scammers:read" | "admin:scammers:write" | "admin:scammers:verify" | "admin:scammers:delete" | "admin:sessions:read" | "admin:sessions:delete" | "admin:notifications:read" | "admin:notifications:write" | "admin:carts:read" | "admin:wishlists:read" | "admin:feature-flags:read" | "admin:feature-flags:write" | "admin:copilot:view" | "admin:team:read" | "admin:team:write" | "admin:maintenance:view-server-errors" | "admin:maintenance:view-client-errors" | "admin:maintenance:view-function-errors" | "admin:maintenance:view-cloud-logs" | "admin:maintenance:view-payment-rollbacks" | "admin:maintenance:run-analysis" | "admin:maintenance:purge-errors";
+export type Permission = "admin:dashboard:view" | "admin:users:read" | "admin:users:write" | "admin:users:delete" | "admin:user-bans:read" | "admin:user-bans:write" | "admin:products:read" | "admin:products:write" | "admin:products:delete" | "admin:orders:read" | "admin:orders:write" | "admin:returns:read" | "admin:returns:write" | "admin:stores:read" | "admin:stores:write" | "admin:store-addresses:read" | "admin:addresses:read" | "admin:addresses:write" | "admin:analytics:view" | "admin:payouts:read" | "admin:payouts:write" | "admin:audit-log:read" | "admin:categories:read" | "admin:categories:write" | "admin:categories:delete" | "admin:brands:read" | "admin:brands:write" | "admin:brands:delete" | "admin:coupons:read" | "admin:coupons:write" | "admin:coupons:delete" | "admin:deals:read" | "admin:deals:write" | "admin:featured:read" | "admin:featured:write" | "admin:reviews:read" | "admin:reviews:write" | "admin:reviews:delete" | "admin:blog:read" | "admin:blog:write" | "admin:blog:delete" | "admin:blog:publish" | "admin:bids:read" | "admin:bids:write" | "admin:offers:read" | "admin:offers:write" | "admin:media:read" | "admin:media:write" | "admin:media:delete" | "admin:site:read" | "admin:site:write" | "admin:settings:write" | "admin:navigation:read" | "admin:navigation:write" | "admin:sections:read" | "admin:sections:write" | "admin:carousel:read" | "admin:carousel:write" | "admin:carousel:delete" | "admin:ads:read" | "admin:ads:write" | "admin:ads:delete" | "admin:faqs:read" | "admin:faqs:write" | "admin:faqs:delete" | "admin:tester-checklist:read" | "admin:tester-checklist:write" | "admin:tester-checklist:delete" | "admin:tester-feedback:read" | "admin:tester-feedback:write" | "admin:newsletter:read" | "admin:newsletter:write" | "admin:contact:read"
+/** Destructive/mutating contact-submission actions. Added 2026-08-29 —
+ * `DELETE /api/admin/contact-submissions/[id]` declared `admin:contact:delete`,
+ * which is not a member of this union and therefore could never be granted. */
+ | "admin:contact:write" | "admin:moderation:read" | "admin:roles:read"
+/**
+ * Skip OTP + payment when placing an order. Replaces
+ * `siteSettings.featureFlags.adminCheckoutBypass`: a capability granted to a
+ * person belongs in the permission system, not in a site-wide toggle that is
+ * either on for every admin or off for all of them.
+ *
+ * Named `admin:checkout:bypass` rather than the bare `checkout:bypass` so it
+ * matches the `admin:resource:action` convention every other member follows
+ * and is picked up by PERMISSION_DOMAINS prefix matching.
+ */
+ | "admin:checkout:bypass"
+/**
+ * Lets a `tester` reach `/admin/**` with real read/write access.
+ *
+ * Replaces the `canTestAdmin` boolean. Not a second role: the hierarchy is
+ * linear, so there is no level meaning "seller-level, plus read admin" that
+ * would not also outrank moderator and employee. Granted through the same
+ * `permissions[]` array employees already use, so there is one grant
+ * mechanism — and revoking it is a permission change, which the admin audit
+ * log already records.
+ */
+ | "tester:admin-surfaces" | "admin:events:read" | "admin:events:write" | "admin:events:delete" | "admin:event-entries:read" | "admin:event-entries:write" | "admin:support-tickets:read" | "admin:support-tickets:write" | "admin:shipments:read" | "admin:shipments:write" | "admin:catalogue:read" | "admin:catalogue:write" | "admin:grouped-listings:read" | "admin:grouped-listings:write" | "admin:support-tickets:assign" | "admin:support-tickets:close" | "admin:scammers:read" | "admin:scammers:write" | "admin:scammers:verify" | "admin:scammers:delete" | "admin:sessions:read" | "admin:sessions:delete" | "admin:notifications:read" | "admin:notifications:write" | "admin:carts:read" | "admin:wishlists:read" | "admin:feature-flags:read" | "admin:feature-flags:write" | "admin:copilot:view" | "admin:team:read" | "admin:team:write" | "admin:maintenance:view-server-errors" | "admin:maintenance:view-client-errors" | "admin:maintenance:view-function-errors" | "admin:maintenance:view-cloud-logs" | "admin:maintenance:view-payment-rollbacks" | "admin:maintenance:run-analysis" | "admin:maintenance:purge-errors";
 /**
  * Granular user actions that can be soft-banned individually.
  * A user may have multiple simultaneous soft bans of different types.

package/dist/features/auth/role-predicates.d.ts

@@ -13,22 +13,90 @@ type RoleCarrier = {
     role?: string | null;
 } | null | undefined;
 export declare const isAdminUser: (input: RoleCarrier) => boolean;
+/**
+ * True for sellers AND testers.
+ *
+ * A QA tester owns a real store — `becomeSeller`/`createStore` auto-approve it —
+ * so every seller-facing surface must admit them. Making `tester` a peer role
+ * of `seller` rather than a boolean is what removed the `isTester` flag; this
+ * predicate is where that peerage is expressed.
+ */
 export declare const isSellerUser: (input: RoleCarrier) => boolean;
+/** Strictly the `seller` role — for the rare case that must EXCLUDE testers. */
+export declare const isStrictSellerUser: (input: RoleCarrier) => boolean;
 export declare const isModeratorUser: (input: RoleCarrier) => boolean;
 export declare const isEmployeeUser: (input: RoleCarrier) => boolean;
 export declare const isBuyerUser: (input: RoleCarrier) => boolean;
 /**
- * True for real admins OR a tester explicitly flagged to test admin areas
- * (`isTester && canTestAdmin`). Used at the two RBAC chokepoints — the API route
- * guard (`createRouteHandler`) and the admin layout guard (`makeAdminSectionLayout`)
- * — so a flagged tester gets real read/write access to `/admin/**` without changing
- * their `role`. Callers must supply `isTester`/`canTestAdmin` from a live Firestore
- * read; these are never present in the session-cookie JWT claims (only `role` is).
+ * ── Tester identity: role first, legacy booleans second ──────────────────────
+ *
+ * `isTester` / `canTestAdmin` are being replaced by the `tester` role and the
+ * `tester:admin-surfaces` permission. Both predicates below read the NEW shape
+ * first and fall back to the OLD one, which is what makes the code safe to ship
+ * before the data migration: a tester whose document still says
+ * `{ role: "seller", isTester: true }` keeps working unchanged, and one already
+ * migrated to `{ role: "tester" }` works too.
+ *
+ * ⛔ Do NOT delete the fallbacks until the backfill has run and been verified.
+ * Removing them early locks every existing tester out of the Tester Hub and out
+ * of the auto-approved store the QA program depends on.
  */
-type EffectiveAdminCarrier = {
+type TesterCarrier = {
     role?: string | null;
     isTester?: boolean;
     canTestAdmin?: boolean;
+    permissions?: readonly string[] | null;
 } | null | undefined;
+/** The `tester` role, or the legacy `isTester` flag. */
+export declare const isTesterUser: (input: TesterCarrier) => boolean;
+/**
+ * May this tester reach `/admin/**`?
+ *
+ * The `tester:admin-surfaces` permission, or the legacy `canTestAdmin` flag.
+ * Granted through the same `permissions[]` array employees already use, so it
+ * is one grant mechanism rather than a bespoke boolean — and revoking it is a
+ * permission change, which the admin audit log already records.
+ */
+export declare const canTestAdminSurfaces: (input: TesterCarrier) => boolean;
+/**
+ * True for real admins OR a tester cleared for admin surfaces. Used at the two
+ * RBAC chokepoints — the API route guard (`createRouteHandler`) and the admin
+ * layout guard (`makeAdminSectionLayout`) — so a cleared tester gets real
+ * read/write access to `/admin/**` without holding the admin role.
+ *
+ * Callers must supply the role/permissions from a live Firestore read; none of
+ * these are present in the session-cookie JWT claims (only `role` is).
+ */
+type EffectiveAdminCarrier = TesterCarrier;
 export declare const isEffectiveAdminUser: (input: EffectiveAdminCarrier) => boolean;
+/**
+ * ── Is this account blocked? ─────────────────────────────────────────────────
+ *
+ * 🛑 There are TWO ban fields on `UserDocument` and, until 2026-08-29, no ban
+ * path wrote the one every guard reads.
+ *
+ *   `disabled`   — required, and read by EVERY server-side guard:
+ *                  auth-server, api-handler, authorization.requireActiveUser,
+ *                  Guards.requireActiveAccount, SessionContext.
+ *                  Its only writers, `userRepository.disable()/enable()`, had
+ *                  ZERO callers.
+ *   `isDisabled` — optional, and what `hardBanCascade` and the bulk-suspend
+ *                  route actually set, alongside the Firebase Auth record.
+ *
+ * The consequence was that **no ban terminated an existing session.** A hard
+ * ban set Firebase Auth `disabled: true`, which blocks a fresh login — and
+ * nothing else. Every authenticated request from a session cookie the user
+ * already held kept passing, because each guard consulted a Firestore field
+ * the ban never touched. Silent, and invisible to anyone testing a ban by
+ * logging out first.
+ *
+ * This predicate reads BOTH so already-banned accounts are enforced from the
+ * moment it ships, without waiting on a backfill. Every write path now sets
+ * both fields too; `isDisabled` is removed once the data is reconciled.
+ */
+type BanCarrier = {
+    disabled?: boolean | null;
+    isDisabled?: boolean | null;
+} | null | undefined;
+export declare const isAccountDisabled: (input: BanCarrier) => boolean;
 export {};

package/dist/features/auth/role-predicates.js

@@ -2,8 +2,34 @@ function normalizeRole(input) {
     return (input?.role ?? "user");
 }
 export const isAdminUser = (input) => normalizeRole(input) === "admin";
-export const isSellerUser = (input) => normalizeRole(input) === "seller";
+/**
+ * True for sellers AND testers.
+ *
+ * A QA tester owns a real store — `becomeSeller`/`createStore` auto-approve it —
+ * so every seller-facing surface must admit them. Making `tester` a peer role
+ * of `seller` rather than a boolean is what removed the `isTester` flag; this
+ * predicate is where that peerage is expressed.
+ */
+export const isSellerUser = (input) => {
+    const role = normalizeRole(input);
+    return role === "seller" || role === "tester";
+};
+/** Strictly the `seller` role — for the rare case that must EXCLUDE testers. */
+export const isStrictSellerUser = (input) => normalizeRole(input) === "seller";
 export const isModeratorUser = (input) => normalizeRole(input) === "moderator";
 export const isEmployeeUser = (input) => normalizeRole(input) === "employee";
 export const isBuyerUser = (input) => normalizeRole(input) === "user";
-export const isEffectiveAdminUser = (input) => isAdminUser(input) || Boolean(input?.isTester && input?.canTestAdmin);
+/** The `tester` role, or the legacy `isTester` flag. */
+export const isTesterUser = (input) => normalizeRole(input) === "tester" || input?.isTester === true;
+/**
+ * May this tester reach `/admin/**`?
+ *
+ * The `tester:admin-surfaces` permission, or the legacy `canTestAdmin` flag.
+ * Granted through the same `permissions[]` array employees already use, so it
+ * is one grant mechanism rather than a bespoke boolean — and revoking it is a
+ * permission change, which the admin audit log already records.
+ */
+export const canTestAdminSurfaces = (input) => Boolean(input?.permissions?.includes("tester:admin-surfaces")) ||
+    input?.canTestAdmin === true;
+export const isEffectiveAdminUser = (input) => isAdminUser(input) || (isTesterUser(input) && canTestAdminSurfaces(input));
+export const isAccountDisabled = (input) => input?.disabled === true || input?.isDisabled === true;

package/dist/features/auth/schemas/firestore.d.ts

@@ -140,6 +140,28 @@ export interface UserDocument extends BaseDocument {
          * stay unique). Absent/missing IDs default to collapsed for a section the
          * user has never interacted with. See useCollapsedSections. */
         collapsedSections?: string[];
+        /**
+         * Which sections are OPEN, namespaced per surface: `scope -> openIds[]`.
+         *
+         * Supersedes `collapsedSections`, and the polarity flip is the point.
+         * Storing what is COLLAPSED cannot express "section 1 open by default"
+         * without a sentinel, and an unseen scope has to be guessed at; storing
+         * what is OPEN makes a never-seen scope default correctly *by absence*.
+         *
+         * Namespaced because the flat list was global: every page's ids shared one
+         * array and were kept apart only by a naming convention. The scope key is
+         * `"{portal}:{surface}"` — deliberately NOT a hash of the section ids,
+         * which would change the moment a section is added and silently reset
+         * every user's layout.
+         *
+         * `collapsedSections` is still written during the migration window; see
+         * `useSectionState`'s one-way dual-read.
+         */
+        sectionState?: Record<string, string[]>;
+        /** Preferred density for list surfaces that offer a view switch.
+         * Was written by the route, the API type and useDataViewMode while being
+         * absent from this interface — declared 2026-08-29. */
+        dataViewMode?: "table" | "grid" | "list";
         /** Which side CTA panels/drawers/sidebars dock to and where close buttons
          * sit. Absent/"right" = default (right-docked). "left" = left-hand mode. */
         handMode?: "left" | "right";

package/dist/features/auth/schemas/index.d.ts

@@ -26,9 +26,9 @@ export declare const loginSchema: z.ZodObject<{
  */
 export declare const registerPasswordSchema: z.ZodString;
 export declare const registerSchema: z.ZodObject<{
+    displayName: z.ZodOptional<z.ZodString>;
     email: z.ZodString;
     password: z.ZodString;
-    displayName: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     email: string;
     password: string;

package/dist/features/auth/schemas/index.js

@@ -1,7 +1,20 @@
 export * from "./firestore";
 import { z } from "zod";
 import { ERROR_MESSAGES } from "../../../errors/messages";
+import { annotate } from "../../shell/field-ui-meta";
 // --- Form schemas -------------------------------------------------------------
+/*
+ * The `annotate()` calls below add UI metadata to a WeakMap keyed on the schema
+ * object; they return the same schema and change nothing about parsing. That is
+ * what makes them safe on `registerSchema`, which the register ROUTE also
+ * parses — the server never reads the registry.
+ *
+ * Every auth form is a single required section. That is not a section in any
+ * interesting sense, and it is not meant to be: `sectionRequired` renders the
+ * panel open and non-collapsible, so the page looks exactly as it does today
+ * and gains the pinned mobile action bar, which is the whole reason to put a
+ * short form through <SectionForm> at all.
+ */
 /**
  * Login form schema — use with react-hook-form + zodResolver.
  *
@@ -10,8 +23,13 @@ import { ERROR_MESSAGES } from "../../../errors/messages";
  * const form = useForm({ resolver: zodResolver(loginSchema) });
  */
 export const loginSchema = z.object({
-    email: z.string().email(),
-    password: z.string().min(6),
+    email: annotate(z.string().email(), {
+        section: "basics", sectionLabel: "Sign in", sectionRequired: true,
+        order: 1, row: "full", inputType: "email", label: "Email",
+    }),
+    password: annotate(z.string().min(6), {
+        section: "basics", order: 2, row: "full", inputType: "password", label: "Password",
+    }),
 });
 /**
  * Matches the server-side complexity rule enforced in
@@ -27,16 +45,34 @@ export const registerPasswordSchema = z
     .regex(/[a-z]/, ERROR_MESSAGES.PASSWORD.NO_LOWERCASE)
     .regex(/[0-9]/, ERROR_MESSAGES.PASSWORD.NO_NUMBER);
 export const registerSchema = z.object({
-    email: z.string().email(),
-    password: registerPasswordSchema,
-    displayName: z.string().min(1).optional(),
+    displayName: annotate(z.string().min(1).optional(), {
+        section: "basics", sectionLabel: "Create your account", sectionRequired: true,
+        order: 1, row: "full", label: "Display name",
+    }),
+    email: annotate(z.string().email(), {
+        section: "basics", order: 2, row: "full", inputType: "email", label: "Email",
+    }),
+    password: annotate(registerPasswordSchema, {
+        section: "basics", order: 3, row: "full", inputType: "password", label: "Password",
+        help: "At least 8 characters, with an uppercase letter, a lowercase letter and a number.",
+    }),
 });
 export const forgotPasswordSchema = z.object({
-    email: z.string().email(),
+    email: annotate(z.string().email(), {
+        section: "basics", sectionLabel: "Reset your password", sectionRequired: true,
+        order: 1, row: "full", inputType: "email", label: "Email",
+    }),
 });
 export const resetPasswordSchema = z.object({
-    token: z.string().min(1),
-    password: z.string().min(6),
+    // Carried in the reset link, never typed. `derived` keeps it out of the
+    // rendered form; the schema still requires it, because the SUBMIT needs it.
+    token: annotate(z.string().min(1), {
+        section: "basics", order: 1, derived: true, tier: "t2-server",
+    }),
+    password: annotate(z.string().min(6), {
+        section: "basics", sectionLabel: "Choose a new password", sectionRequired: true,
+        order: 2, row: "full", inputType: "password", label: "New password",
+    }),
 });
 // --- Auth user schema ---------------------------------------------------------
 export const userRoleSchema = z.enum([

package/dist/features/auth/types/index.d.ts

@@ -1,4 +1,17 @@
-export type UserRole = "user" | "seller" | "moderator" | "employee" | "admin";
+/**
+ * `tester` sits at the SAME level as `seller` (see ROLE_HIERARCHY in
+ * security/authorization.ts) because a QA tester owns a real store and must
+ * pass every seller gate — the Tester QA Program depends on it.
+ *
+ * It replaces the `isTester` boolean. The companion `canTestAdmin` boolean
+ * became the `tester:admin-surfaces` permission rather than a second role,
+ * because this hierarchy is LINEAR: there is no level that means
+ * "seller-level, plus read admin" without also meaning admin.
+ *
+ * Both booleans are still read during the migration window — see
+ * `isTesterUser` / `canTestAdminSurfaces` in ./role-predicates.
+ */
+export type UserRole = "user" | "seller" | "tester" | "moderator" | "employee" | "admin";
 export interface AuthUser {
     id: string;
     email?: string;

package/dist/features/blog/api/route.js

@@ -25,7 +25,15 @@ export async function GET(request) {
     try {
         const url = new URL(request.url);
         const page = numParam(url, "page", 1);
-        const perPage = numParam(url, "perPage", 20);
+        /*
+         * `pageSize` is canonical; `perPage` is still read because this is a public
+         * GET and a link built before 2026-08-31 carries the old spelling. Ignoring
+         * it would silently serve the default page size with a 200 — the shape of
+         * failure this codebase keeps paying for.
+         */
+        const pageSize = url.searchParams.has("perPage")
+            ? numParam(url, "perPage", 20)
+            : numParam(url, "pageSize", 20);
         const sort = param(url, "sort") ?? "-publishedAt";
         const parts = [];
         const category = param(url, "category");
@@ -52,7 +60,7 @@ export async function GET(request) {
         // `blogRepository.listAll` rather than the generic `db.getRepository(...)`:
         // only the feature repository knows how to push a searchTxt clause down and
         // AND-refine the remaining terms.
-        const result = await blogRepository.listAll({ filters, sorts: sort, page, pageSize: perPage }, q ? { search: q } : undefined);
+        const result = await blogRepository.listAll({ filters, sorts: sort, page, pageSize }, q ? { search: q } : undefined);
         const meta = {
             total: result.total,
             page: result.page,

package/dist/features/blog/components/BlogIndexListing.js

@@ -106,7 +106,7 @@ export function BlogIndexListing({ initialData }) {
         tags: table.get(TABLE_KEYS.TAGS) || undefined,
         sort: table.get(TABLE_KEYS.SORT) || DEFAULT_SORT,
         page: table.getNumber(TABLE_KEYS.PAGE, 1),
-        perPage: table.getNumber(TABLE_KEYS.PAGE_SIZE, PAGE_SIZE),
+        pageSize: table.getNumber(TABLE_KEYS.PAGE_SIZE, PAGE_SIZE),
     };
     const { posts, totalPages, isLoading } = useBlogPosts(params, { initialData });
     const currentPage = table.getNumber("page", 1);

package/dist/features/blog/hooks/useBlog.js

@@ -11,8 +11,8 @@ export function useBlogPosts(params = {}, opts) {
         searchParams.set("tags", params.tags);
     if (params.page)
         searchParams.set("page", String(params.page));
-    if (params.perPage)
-        searchParams.set("perPage", String(params.perPage));
+    if (params.pageSize)
+        searchParams.set("pageSize", String(params.pageSize));
     if (params.sort)
         searchParams.set("sort", params.sort);
     if (params.featured !== undefined)

package/dist/features/blog/repository/blog.repository.js

@@ -72,10 +72,12 @@ class BlogRepository extends BaseRepository {
                 .collection(this.collection)
                 .doc(id)
                 .update({ [BLOG_POST_FIELDS.VIEWS]: increment(1) });
+            // Fire-and-forget analytics: a lost view increment changes nothing that
+            // renders and cannot usefully be retried, so it must never fail the blog
+            // post read that triggered it — the count is approximate by design.
         }
         catch (_err) {
             void normalizeError(_err);
-            // Fire-and-forget by design.
         }
     }
     async findRelated(category, excludeId, limit = 3) {

package/dist/features/blog/schemas/index.d.ts

@@ -458,6 +458,8 @@ export declare const blogListParamsSchema: z.ZodObject<{
     tags: z.ZodOptional<z.ZodString>;
     q: z.ZodOptional<z.ZodString>;
     page: z.ZodOptional<z.ZodNumber>;
+    pageSize: z.ZodOptional<z.ZodNumber>;
+    /** Accepted, never emitted — a link built before the 2026-08-31 rename. */
     perPage: z.ZodOptional<z.ZodNumber>;
     sort: z.ZodOptional<z.ZodString>;
     featured: z.ZodOptional<z.ZodBoolean>;
@@ -466,6 +468,7 @@ export declare const blogListParamsSchema: z.ZodObject<{
     page?: number | undefined;
     q?: string | undefined;
     perPage?: number | undefined;
+    pageSize?: number | undefined;
     category?: "news" | "tips" | "guides" | "updates" | "community" | undefined;
     featured?: boolean | undefined;
     tags?: string | undefined;
@@ -474,6 +477,7 @@ export declare const blogListParamsSchema: z.ZodObject<{
     page?: number | undefined;
     q?: string | undefined;
     perPage?: number | undefined;
+    pageSize?: number | undefined;
     category?: "news" | "tips" | "guides" | "updates" | "community" | undefined;
     featured?: boolean | undefined;
     tags?: string | undefined;

package/dist/features/blog/schemas/index.js

@@ -90,6 +90,8 @@ export const blogListParamsSchema = z.object({
     tags: z.string().optional(),
     q: z.string().optional(),
     page: z.coerce.number().optional(),
+    pageSize: z.coerce.number().optional(),
+    /** Accepted, never emitted — a link built before the 2026-08-31 rename. */
     perPage: z.coerce.number().optional(),
     sort: z.string().optional(),
     featured: z.coerce.boolean().optional(),

package/dist/features/blog/types/index.d.ts

@@ -43,7 +43,7 @@ export interface BlogListParams {
     tags?: string;
     q?: string;
     page?: number;
-    perPage?: number;
+    pageSize?: number;
     sort?: string;
     featured?: boolean;
 }

package/dist/features/cart/actions/cart-actions.js

@@ -14,6 +14,7 @@ import { getDefaultCurrency } from "../../../core/baseline-resolver";
 import { CART_LANE, activeLane, canAddNewItems, } from "../../../_internal/shared/checkout/lanes";
 import { CART_MAX_ITEMS } from "../../../constants/limits";
 import { getExpandedDecrements, validateCartItemStock, } from "../../../_internal/server/features/checkout/bundle-expansion";
+import { safeRead } from "../../../errors/safe-read";
 /**
  * Product documents don't always carry a denormalized `storeName` — the
  * create routes only set it when the caller explicitly passes one, so
@@ -26,7 +27,9 @@ import { getExpandedDecrements, validateCartItemStock, } from "../../../_interna
 async function resolveStoreName(storeId, candidate) {
     if (candidate)
         return candidate;
-    const store = await storeRepository.findById(storeId).catch(() => null);
+    const store = await safeRead(() => storeRepository.findById(storeId), {
+        route: "/cart", key: "stores.findById", fallback: null,
+    });
     return store?.storeName ?? storeId;
 }
 /**
@@ -102,7 +105,9 @@ export async function addGroupLineToCart(userId, input) {
     const cart = await assertCanAddNewItems(userId);
     // One batched read for the whole selection — capped at 20 above, so well
     // inside the per-request Firestore budget.
-    const docs = await Promise.all(members.map((m) => productRepository.findById(m.productId).catch(() => null)));
+    const docs = await Promise.all(members.map((m) => safeRead(() => productRepository.findById(m.productId), {
+        route: "/cart", key: "products.findById", fallback: null,
+    })));
     const productById = new Map(members.map((m, i) => [m.productId, docs[i]]));
     const { getListingRule } = await import("../../../_internal/shared/checkout/rules");
     const { ProductStatusValues } = await import("../../products/schemas/firestore");
@@ -209,14 +214,18 @@ export async function addGroupLineToCart(userId, input) {
 /** Is this product listed on that `groupedListings` document? */
 async function isGroupedListingMember(groupId, productId) {
     const { groupedListingsRepository } = await import("../../grouped/repository/grouped-listings.repository");
-    const group = await groupedListingsRepository.findById(groupId).catch(() => null);
+    const group = await safeRead(() => groupedListingsRepository.findById(groupId), {
+        route: "/cart", key: "groupedListings.findById", fallback: null,
+    });
     return Boolean(group?.productIds?.includes(productId));
 }
 /** Display name for the line. Falls back to the parent product's group title. */
 async function resolveGroupTitle(groupId, groupSource, sample) {
     if (groupSource === "grouped-listing") {
         const { groupedListingsRepository } = await import("../../grouped/repository/grouped-listings.repository");
-        const group = await groupedListingsRepository.findById(groupId).catch(() => null);
+        const group = await safeRead(() => groupedListingsRepository.findById(groupId), {
+            route: "/cart", key: "groupedListings.title", fallback: null,
+        });
         if (group?.title)
             return group.title;
     }