@mohasinac/appkit 4.59.0 → 4.60.0

package/dist/ui/forms/FormShell.style.css

@@ -3,20 +3,20 @@
 .appkit-formshell {
   display: flex;
   flex-direction: column;
-  gap: var(--appkit-spacing-6, 1.5rem);
+  gap: var(--appkit-space-6, 1.5rem);
 }
 
 /* Header */
 .appkit-formshell__header {
   display: flex;
   flex-direction: column;
-  gap: var(--appkit-spacing-4, 1rem);
+  gap: var(--appkit-space-4, 1rem);
 }
 
 .appkit-formshell__title {
-  font-size: var(--appkit-font-size-lg, 1.125rem);
+  font-size: var(--appkit-text-lg, 1.125rem);
   font-weight: 600;
-  color: var(--appkit-color-text-primary);
+  color: var(--appkit-color-text);
 }
 
 /* ─── Step Indicator ──────────────────────────────────────────────────────── */
@@ -24,22 +24,22 @@
 .appkit-formshell__step-indicator {
   display: flex;
   flex-wrap: wrap;
-  gap: var(--appkit-spacing-1, 0.25rem);
+  gap: var(--appkit-space-1, 0.25rem);
   border-bottom: 1px solid var(--appkit-color-border);
-  padding-bottom: var(--appkit-spacing-3, 0.75rem);
+  padding-bottom: var(--appkit-space-3, 0.75rem);
 }
 
 .appkit-formshell__step-btn {
   display: flex;
   align-items: center;
-  gap: var(--appkit-spacing-2, 0.5rem);
-  padding: var(--appkit-spacing-1-5, 0.375rem) var(--appkit-spacing-3, 0.75rem);
+  gap: var(--appkit-space-2, 0.5rem);
+  padding: var(--appkit-space-1-5, 0.375rem) var(--appkit-space-3, 0.75rem);
   border-radius: var(--appkit-radius-md, 0.375rem);
   background: transparent;
   border: 1px solid transparent;
-  color: var(--appkit-color-text-secondary);
+  color: var(--appkit-color-text-muted);
   cursor: pointer;
-  font-size: var(--appkit-font-size-sm, 0.875rem);
+  font-size: var(--appkit-text-sm, 0.875rem);
   transition: background 0.15s, border-color 0.15s, color 0.15s;
 }
 
@@ -49,7 +49,7 @@
 }
 
 .appkit-formshell__step-btn--active {
-  background: var(--appkit-color-primary-subtle, rgb(from var(--appkit-color-primary) r g b / 0.1));
+  background: var(--appkit-color-primary-surface);
   border-color: var(--appkit-color-primary);
   color: var(--appkit-color-primary);
   font-weight: 500;
@@ -68,8 +68,8 @@
   width: 1.5rem;
   height: 1.5rem;
   border-radius: 9999px;
-  background: var(--appkit-color-surface-secondary);
-  font-size: var(--appkit-font-size-xs, 0.75rem);
+  background: var(--appkit-color-surface-raised);
+  font-size: var(--appkit-text-xs, 0.75rem);
   font-weight: 600;
   flex-shrink: 0;
 }
@@ -103,7 +103,7 @@
   height: auto;
   border-radius: var(--appkit-radius-full, 9999px);
   padding: 0 0.375rem;
-  font-size: var(--appkit-font-size-xs, 0.75rem);
+  font-size: var(--appkit-text-xs, 0.75rem);
   font-weight: 600;
   color: #fff;
   line-height: 1.4;
@@ -125,13 +125,13 @@
 .appkit-formshell__error-summary {
   border: 1px solid var(--appkit-color-error, #dc2626);
   border-radius: var(--appkit-radius-md, 0.375rem);
-  padding: var(--appkit-spacing-3, 0.75rem);
+  padding: var(--appkit-space-3, 0.75rem);
   background: rgb(from var(--appkit-color-error, #dc2626) r g b / 0.05);
 }
 
 .appkit-formshell__error-summary__title {
   font-weight: 600;
-  margin-bottom: var(--appkit-spacing-2, 0.5rem);
+  margin-bottom: var(--appkit-space-2, 0.5rem);
 }
 
 .appkit-formshell__error-summary__list {
@@ -139,7 +139,7 @@
   padding-left: 1.25rem;
   display: flex;
   flex-direction: column;
-  gap: var(--appkit-spacing-1, 0.25rem);
+  gap: var(--appkit-space-1, 0.25rem);
 }
 
 .appkit-formshell__error-summary__step-link {
@@ -171,7 +171,7 @@
 .appkit-formshell__steps {
   display: flex;
   flex-direction: column;
-  gap: var(--appkit-spacing-1, 0.25rem);
+  gap: var(--appkit-space-1, 0.25rem);
 }
 
 .appkit-formshell__step {
@@ -194,13 +194,13 @@
   align-items: center;
   justify-content: space-between;
   width: 100%;
-  padding: var(--appkit-spacing-3, 0.75rem) var(--appkit-spacing-4, 1rem);
-  background: var(--appkit-color-surface-secondary);
+  padding: var(--appkit-space-3, 0.75rem) var(--appkit-space-4, 1rem);
+  background: var(--appkit-color-surface-raised);
   border: none;
   cursor: pointer;
-  font-size: var(--appkit-font-size-sm, 0.875rem);
+  font-size: var(--appkit-text-sm, 0.875rem);
   font-weight: 500;
-  color: var(--appkit-color-text-primary);
+  color: var(--appkit-color-text);
   text-align: left;
 }
 
@@ -244,17 +244,25 @@
  * action row in the codebase. Every live footer had lost it.
  */
 
-/* ─── Dark mode ──────────────────────────────────────────────────────────── */
-
-.dark .appkit-formshell__title {
-  color: var(--appkit-color-text-primary-dark, inherit);
-}
-
-.dark .appkit-formshell__step-accordion-btn {
-  background: var(--appkit-color-surface-secondary-dark, var(--appkit-color-surface-secondary));
-  color: var(--appkit-color-text-primary-dark, inherit);
-}
-
+/* ─── Dark mode ──────────────────────────────────────────────────────────────
+ *
+ * Only the error summary needs a dark rule now. The two that stood here —
+ * `__title` and `__step-accordion-btn` — each restated the base rule's own
+ * tokens once those names were corrected, because `--appkit-color-text` and
+ * `--appkit-color-surface-raised` already invert with the theme.
+ *
+ * What they used to say is the whole reason this file mattered:
+ *
+ *   background: var(--appkit-color-surface-secondary-dark,
+ *                   var(--appkit-color-surface-secondary));
+ *   color:      var(--appkit-color-text-primary-dark, inherit);
+ *
+ * Neither name in that chain exists, so the background fell through to a
+ * second undefined name and the declaration was DROPPED — a transparent
+ * accordion header — while the colour fell through to `inherit`, so the text
+ * took whatever an ancestor happened to set. Every editor screen in the
+ * product renders through this file.
+ */
 .dark .appkit-formshell__error-summary {
   background: rgb(from var(--appkit-color-error, #dc2626) r g b / 0.1);
 }

package/dist/ui/forms/index.d.ts

@@ -1,4 +1,4 @@
-export type { FormShellProviderProps, FormShellStep, FormShellNav, FormShellContextValue, UseFormShellStateResult, } from "./FormShell";
+export type { FormShellProviderProps, FormShellStep, FormShellNav, FormShellContextValue, FormShellStateOptions, UseFormShellStateResult, } from "./FormShell";
 export { FormShellProvider, FormShellContext, useFormShell, useFormShellState } from "./FormShell";
 export { applyZodIssues, hasAttachableIssue } from "./apply-zod-issues";
 export type { FieldInputProps } from "./FieldInput";
@@ -13,5 +13,9 @@ export type { ColorPickerFieldProps } from "./ColorPickerField";
 export { ColorPickerField } from "./ColorPickerField";
 export type { FormErrorSummaryProps } from "./FormErrorSummary";
 export { FormErrorSummary } from "./FormErrorSummary";
+export type { AddAnotherToggleProps } from "./AddAnotherToggle";
+export { AddAnotherToggle, addAnotherSubmitLabel } from "./AddAnotherToggle";
+export type { FieldLabelProps, LabelPlacement } from "./FieldLabel";
+export { FieldLabel, LabelPlacementContext, useLabelPlacement, } from "./FieldLabel";
 export type { FormErrorListProps } from "./FormErrorList";
 export { FormErrorList } from "./FormErrorList";

package/dist/ui/forms/index.js

@@ -6,4 +6,6 @@ export { FieldCheckbox } from "./FieldCheckbox.js";
 export { FieldTextarea } from "./FieldTextarea.js";
 export { ColorPickerField } from "./ColorPickerField.js";
 export { FormErrorSummary } from "./FormErrorSummary.js";
+export { AddAnotherToggle, addAnotherSubmitLabel } from "./AddAnotherToggle.js";
+export { FieldLabel, LabelPlacementContext, useLabelPlacement, } from "./FieldLabel.js";
 export { FormErrorList } from "./FormErrorList.js";

package/dist/ui/icons/icon-registry.d.ts

@@ -65,6 +65,7 @@ export declare const ICONS: {
     readonly stickers: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
     readonly spares: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
     readonly live: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+    readonly points: import("react").ForwardRefExoticComponent<Omit<import("lucide-react").LucideProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
 };
 /** Every valid `iconKey`. A typo is a compile error, not a silent blank. */
 export type IconKey = keyof typeof ICONS;

package/dist/ui/icons/icon-registry.js

@@ -39,7 +39,7 @@
  * @tag consumers:Button,RowActionMenu,BulkActionBar,action-registry
  * @tag sideEffects:none
  */
-import { Archive, ArrowLeft, Ban, Bell, Check, CheckCircle, ChevronDown, Copy, Download, Edit, Eye, EyeOff, FileDown, Filter, Flag, Gavel, HelpCircle, Heart, Link as LinkIcon, Lock, Mail, Menu, MessageSquare, Moon, Package, Pause, Play, Plus, RefreshCw, Reply, RotateCcw, Save, Search, Send, Settings, Share2, ShieldCheck, ShoppingCart, Star, Sun, Scale, Tag, Trash2, TrendingUp, Truck, Upload, User, X, XCircle, CalendarClock, Gift, KeyRound, Palette, Sticker, Puzzle, PawPrint, } from "lucide-react";
+import { Archive, ArrowLeft, Ban, Coins, Bell, Check, CheckCircle, ChevronDown, Copy, Download, Edit, Eye, EyeOff, FileDown, Filter, Flag, Gavel, HelpCircle, Heart, Link as LinkIcon, Lock, Mail, Menu, MessageSquare, Moon, Package, Pause, Play, Plus, RefreshCw, Reply, RotateCcw, Save, Search, Send, Settings, Share2, ShieldCheck, ShoppingCart, Star, Sun, Scale, Tag, Trash2, TrendingUp, Truck, Upload, User, X, XCircle, CalendarClock, Gift, KeyRound, Palette, Sticker, Puzzle, PawPrint, } from "lucide-react";
 /**
  * Semantic name → component.
  *
@@ -134,6 +134,22 @@ export const ICONS = {
      */
     spares: Puzzle,
     live: PawPrint,
+    /*
+     * Buyer points. Minted rather than reused, which this registry's header
+     * allows only when nothing already means it — and nothing did.
+     *
+     * `deals` (Tag) was the closest and is wrong: a tag means a DISCOUNT ON A
+     * LISTING, while points are a buyer's balance. `analytics` (TrendingUp) is a
+     * chart. Reusing either would make the admin row action read as something it
+     * is not, and the glyph is what an operator scans before the label.
+     *
+     * `Coins` over `Wallet` deliberately: `points/schemas/firestore.ts` opens by
+     * stating this is NOT a wallet, and that the distinction is legal rather than
+     * stylistic (a wallet is stored value, which is PPI territory with RBI
+     * authorisation attached). An icon that says "wallet" would undercut the one
+     * property the feature must not have.
+     */
+    points: Coins,
 };
 /**
  * The ONLY sanctioned glyph sizes.

package/dist/utils/id-generators.d.ts

@@ -323,6 +323,35 @@ export declare function validateMediaFilename(filename: string): boolean;
  * without changing the finalize request contract.
  */
 export declare function deriveContextTypeFromFilename(filename: string): string | undefined;
+/**
+ * ── 🛑 BARCODE vs SKU — the two formats, reconciled ─────────────────────────
+ *
+ * `barcodeId` held BOTH of these, which is why the audit found
+ * `LIR-1A99AEA8` printed directly above `LIR-BEY-X-005` in one list:
+ *
+ *   · 23 seeded products carried a hand-authored SEMANTIC code
+ *     (`LIR-BEY-BURS-001`, `LIR-BEY-X-005`) — meaningful, variable width,
+ *     readable by a human, sortable by line.
+ *   · everything created through the app got `generateBarcodeId`'s SHA-1
+ *     form — meaningless, fixed width, verifiable only by scanning.
+ *
+ * One field was doing two jobs, and the jobs have opposite requirements. The
+ * split is the reconciliation:
+ *
+ *   `barcodeId`  THE MACHINE KEY. Fixed shape, uniform width, derived. This
+ *                is what a CODE128 symbol encodes and what a scan resolves
+ *                through `findByBarcodeId`.
+ *   `sku`        THE HUMAN KEY. Author-editable, meaningful, variable width.
+ *                The 23 semantic codes belong here and have moved.
+ *
+ * 🛑 Why the width matters and is not cosmetic: a label's geometry is sized
+ * for its symbol, and Phase 5's thermal presets derive a ~42 mm minimum from
+ * the 12-character `LIR-XXXXXXXX` form. A variable-width code in the same
+ * field means one product's label fits its stock and the next one's does
+ * not — and `labelFitsProfile()` is specified to REPORT rather than scale,
+ * so the failure surfaces as a refusal to print rather than a squashed
+ * barcode. Keeping `barcodeId` uniform is what makes that check meaningful.
+ */
 /**
  * Generates a scannable barcode identifier for a product listing.
  * Returns `LIR-XXXXXXXX` (8 uppercase hex chars) derived from a SHA-1
@@ -331,3 +360,54 @@ export declare function deriveContextTypeFromFilename(filename: string): string
  * Uses `globalThis.crypto.subtle` available in Node ≥18 and modern browsers.
  */
 export declare function generateBarcodeId(productId: string): Promise<string>;
+export interface StorageBoxIdInput {
+    /** `AC60-03` — exactly what is written on the physical label. */
+    code: string;
+    customId?: string;
+}
+/**
+ * `storagebox-ac60-03` — a PURE SLUG, and that is the whole point.
+ *
+ * 🛑 No date, no random suffix, unlike `generateShipmentId` beside it. A
+ * second `AC60-03` *is the same physical box*: two registry rows for one
+ * object means "where is this" has two answers with no way to tell which
+ * shelf was meant. A generated id would permit exactly that, and the
+ * duplicate would look like a legitimate second box in every list.
+ *
+ * The same reasoning the slug table already applies to stores and categories,
+ * and the opposite of `stickersheet-`, where re-scanning one sheet is normal
+ * and a pure slug would make the second scan overwrite the first.
+ */
+export declare function generateStorageBoxId(input: StorageBoxIdInput): string;
+export interface SkuInput {
+    /** The product's own id — the uniqueness source. */
+    productId: string;
+    /** Leaf category slug, for the readable middle segment. */
+    categorySlug?: string;
+    /** Brand name, used when there is no category to read. */
+    brand?: string;
+    /** A seller-authored SKU. Returned as-is when non-empty. */
+    customId?: string;
+}
+/**
+ * `LIR-BURS-K3F9P` — the HUMAN key for a listing.
+ *
+ * 🛑 DETERMINISTIC, not sequential, and that is the decision worth knowing.
+ *
+ * The 23 seeded codes are sequential (`-001`, `-002`), which reads beautifully
+ * and cannot be generated without a per-line counter — i.e. a Firestore read
+ * and a write on every product create, a contended document, and a number
+ * that cannot be reproduced offline. Seed files are re-executed on every
+ * `appkit-seed` invocation, so a counter there would also break idempotency
+ * outright (Root Cause #25).
+ *
+ * So the sequence is replaced by a base36 hash of the product id: unique
+ * without coordination, identical on every run, and still prefixed with a
+ * readable line token so a human can tell a Burst from a Metal Fight at a
+ * glance. Hand-authored sequential codes remain legal — `customId` is
+ * returned untouched, which is how the seeded 23 keep theirs.
+ *
+ * 🛑 NOT fed into `barcodeId`. See the note above `generateBarcodeId`: the
+ * barcode must stay uniform-width for the label geometry to mean anything.
+ */
+export declare function generateSku(input: SkuInput): string;

package/dist/utils/id-generators.js

@@ -545,6 +545,35 @@ export function validateMediaFilename(filename) {
 export function deriveContextTypeFromFilename(filename) {
     return MEDIA_FILENAME_PATTERNS.find(({ pattern }) => pattern.test(filename))?.context;
 }
+/**
+ * ── 🛑 BARCODE vs SKU — the two formats, reconciled ─────────────────────────
+ *
+ * `barcodeId` held BOTH of these, which is why the audit found
+ * `LIR-1A99AEA8` printed directly above `LIR-BEY-X-005` in one list:
+ *
+ *   · 23 seeded products carried a hand-authored SEMANTIC code
+ *     (`LIR-BEY-BURS-001`, `LIR-BEY-X-005`) — meaningful, variable width,
+ *     readable by a human, sortable by line.
+ *   · everything created through the app got `generateBarcodeId`'s SHA-1
+ *     form — meaningless, fixed width, verifiable only by scanning.
+ *
+ * One field was doing two jobs, and the jobs have opposite requirements. The
+ * split is the reconciliation:
+ *
+ *   `barcodeId`  THE MACHINE KEY. Fixed shape, uniform width, derived. This
+ *                is what a CODE128 symbol encodes and what a scan resolves
+ *                through `findByBarcodeId`.
+ *   `sku`        THE HUMAN KEY. Author-editable, meaningful, variable width.
+ *                The 23 semantic codes belong here and have moved.
+ *
+ * 🛑 Why the width matters and is not cosmetic: a label's geometry is sized
+ * for its symbol, and Phase 5's thermal presets derive a ~42 mm minimum from
+ * the 12-character `LIR-XXXXXXXX` form. A variable-width code in the same
+ * field means one product's label fits its stock and the next one's does
+ * not — and `labelFitsProfile()` is specified to REPORT rather than scale,
+ * so the failure surfaces as a refusal to print rather than a squashed
+ * barcode. Keeping `barcodeId` uniform is what makes that check meaningful.
+ */
 /**
  * Generates a scannable barcode identifier for a product listing.
  * Returns `LIR-XXXXXXXX` (8 uppercase hex chars) derived from a SHA-1
@@ -559,3 +588,67 @@ export async function generateBarcodeId(productId) {
         .join("");
     return `LIR-${hex.slice(0, 8).toUpperCase()}`;
 }
+/**
+ * `storagebox-ac60-03` — a PURE SLUG, and that is the whole point.
+ *
+ * 🛑 No date, no random suffix, unlike `generateShipmentId` beside it. A
+ * second `AC60-03` *is the same physical box*: two registry rows for one
+ * object means "where is this" has two answers with no way to tell which
+ * shelf was meant. A generated id would permit exactly that, and the
+ * duplicate would look like a legitimate second box in every list.
+ *
+ * The same reasoning the slug table already applies to stores and categories,
+ * and the opposite of `stickersheet-`, where re-scanning one sheet is normal
+ * and a pure slug would make the second scan overwrite the first.
+ */
+export function generateStorageBoxId(input) {
+    if (input.customId?.trim())
+        return input.customId.trim();
+    return `storagebox-${slugify(input.code)}`;
+}
+/** A short uppercase token from a slug or name — `beyblade-burst` -> `BURS`. */
+function skuToken(input, length) {
+    const letters = (input ?? "").replace(/[^a-zA-Z0-9]/g, "").toUpperCase();
+    return letters.slice(0, length);
+}
+/**
+ * `LIR-BURS-K3F9P` — the HUMAN key for a listing.
+ *
+ * 🛑 DETERMINISTIC, not sequential, and that is the decision worth knowing.
+ *
+ * The 23 seeded codes are sequential (`-001`, `-002`), which reads beautifully
+ * and cannot be generated without a per-line counter — i.e. a Firestore read
+ * and a write on every product create, a contended document, and a number
+ * that cannot be reproduced offline. Seed files are re-executed on every
+ * `appkit-seed` invocation, so a counter there would also break idempotency
+ * outright (Root Cause #25).
+ *
+ * So the sequence is replaced by a base36 hash of the product id: unique
+ * without coordination, identical on every run, and still prefixed with a
+ * readable line token so a human can tell a Burst from a Metal Fight at a
+ * glance. Hand-authored sequential codes remain legal — `customId` is
+ * returned untouched, which is how the seeded 23 keep theirs.
+ *
+ * 🛑 NOT fed into `barcodeId`. See the note above `generateBarcodeId`: the
+ * barcode must stay uniform-width for the label geometry to mean anything.
+ */
+export function generateSku(input) {
+    if (input.customId?.trim())
+        return input.customId.trim();
+    const token = skuToken(input.categorySlug, 4) || skuToken(input.brand, 4) || "GEN";
+    /*
+     * A 5-char base36 hash of the id — ~60M values, which is far past what a
+     * physical inventory needs, and short enough to read aloud down a phone.
+     *
+     * `Math.imul` rather than a crypto digest because this must be callable
+     * SYNCHRONOUSLY from a form and from seed data. `generateBarcodeId` is
+     * async precisely because it uses `crypto.subtle`, and an async SKU would
+     * push a promise into every row builder.
+     */
+    let hash = 0;
+    for (let i = 0; i < input.productId.length; i += 1) {
+        hash = Math.imul(hash ^ input.productId.charCodeAt(i), 0x01000193);
+    }
+    const suffix = (hash >>> 0).toString(36).toUpperCase().padStart(5, "0").slice(-5);
+    return `LIR-${token}-${suffix}`;
+}

package/dist/utils/search-txt-builders.d.ts

@@ -32,6 +32,18 @@ export declare function buildProductSearchTxt(p: Partial<ProductDocument>): stri
 export declare function buildCategorySearchTxt(c: Partial<CategoryDocument>): string[];
 /** stores — name, description, category. No payout details, no contact. */
 export declare function buildStoreSearchTxt(s: Partial<StoreDocument>): string[];
+/**
+ * storageBoxes — the printed code, the type, and where the box is.
+ *
+ * One builder per entity, matching every sibling here. The code is the field
+ * an operator actually types or scans; `location` is free text and is indexed
+ * so "shelf B" finds the boxes on it.
+ */
+export declare function buildStorageBoxSearchTxt(x: {
+    code?: string;
+    boxType?: string;
+    location?: string;
+}): string[];
 /** events — title, description, type, tags. */
 export declare function buildEventSearchTxt(e: Partial<EventDocument>): string[];
 /**

package/dist/utils/search-txt-builders.js

@@ -43,6 +43,13 @@ export function buildProductSearchTxt(p) {
         p.tags,
         p.features,
         p.condition,
+        /*
+         * The human stock key. 🛑 Existing rows keep their stored searchTxt until
+         * something re-saves them, so SKU search is only true after
+         * backfill-sku.mjs runs — which is why the admin placeholder does not
+         * promise it yet.
+         */
+        p.sku,
         p.card?.setName,
         p.card?.cardNumber,
         p.grading?.service,
@@ -163,6 +170,16 @@ export function buildStoreSearchTxt(s) {
         s.storeCategory,
     ]);
 }
+/**
+ * storageBoxes — the printed code, the type, and where the box is.
+ *
+ * One builder per entity, matching every sibling here. The code is the field
+ * an operator actually types or scans; `location` is free text and is indexed
+ * so "shelf B" finds the boxes on it.
+ */
+export function buildStorageBoxSearchTxt(x) {
+    return buildSearchTxt([x.code, x.boxType, x.location]);
+}
 /** events — title, description, type, tags. */
 export function buildEventSearchTxt(e) {
     return buildSearchTxt([

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mohasinac/appkit",
-  "version": "4.59.0",
+  "version": "4.60.0",
   "license": "MIT",
   "publishConfig": {
     "access": "public"

package/scripts/seed-cli.mjs

@@ -273,7 +273,7 @@ const {
   siteSettingsSeedData, faqSeedData,
   wishlistsSeedData, historySeedData,
   groupedListingsSeedData,
-  mediaAssetsSeedData,
+  mediaAssetsSeedData, mediaAssetsEditorialSeedData,
   scammersSeedData, productFeaturesSeedData, taxCodesSeedData,
   authenticityKnowledgeSeedData,
   partGlossarySeedData, modelCompositionSeedData,
@@ -758,7 +758,10 @@ const SEED_DATA_MAP = {
   groupedListings: groupedListingsSeedData,
   // The other half of the wiring — load() short-circuits on an empty array, so
   // the COLLECTION_MAP entry above does nothing on its own (Root Cause #90).
-  mediaAssets: mediaAssetsSeedData,
+  // Two source files, one collection: the taxonomy rows are GENERATED and
+  // rewritten wholesale by upload-taxonomy-images.mjs, so the editorial rows
+  // are kept beside them rather than inside that file.
+  mediaAssets: [...mediaAssetsSeedData, ...mediaAssetsEditorialSeedData],
   scammerProfiles: scammersSeedData,
   productFeatures: productFeaturesSeedData,
   authenticityKnowledge: authenticityKnowledgeSeedData,
@@ -1137,6 +1140,79 @@ function stripAdminOwned(payload, ownedFields) {
 
 const ADMIN_EDIT_PROTECTED = new Set(["partGlossary", "beys"]);
 
+/**
+ * Fields a seed may CREATE but must never OVERWRITE — derived counters.
+ *
+ * 🛑 This exists because seeding silently zeroed the whole taxonomy. Every row
+ * in `categories-seed-data.ts` hard-codes
+ * `metrics: { productCount: 0, totalProductCount: 0, … }`, and `seed-cli`
+ * merge-writes — a merge overwrites any key PRESENT in the payload. So
+ * `appkit-seed load --collections categories` set every counter on every
+ * category to zero.
+ *
+ * Measured 2026-10-21: after a demo purge, all 17 categories that should have
+ * carried stock read `total=0` while their products were filed perfectly --
+ * `category-beyblade-x` stored 0 against an actual 14. Every parent looked
+ * empty. Reseeding to add four bundles then zeroed them a SECOND time,
+ * minutes after they had been repaired.
+ *
+ * Nothing errors, because a wrong number is just a number. The symptom reaches
+ * only a human looking at a page that says a category has nothing in it.
+ *
+ * 🛑 CREATE but not OVERWRITE, not "always strip" — `CategoryDocument.metrics`
+ * is a REQUIRED field with three unguarded readers (`CategoryTableColumns`,
+ * `CategoryTree`, `isFeaturedEligible`). Stripping it unconditionally would
+ * leave a freshly seeded document violating its own type until the reconciler
+ * first ran. Establishing zeros on create is correct; overwriting live counts
+ * is not.
+ *
+ * The authority for these fields is `runCountersReconcile` plus the live
+ * write triggers — see the `countersReconcileNow` Function for the on-demand
+ * run that belongs immediately after a seed.
+ */
+const DERIVED_COUNTER_FIELDS = {
+  categories: ["metrics"],
+  stores: ["stats"],
+};
+
+/**
+ * The ids a collection already holds, when it has derived counters to protect.
+ *
+ * 🛑 A `.select()` projection — ids only, no document bodies — so this costs
+ * reads but transfers almost nothing. It runs ONLY for the two collections in
+ * `DERIVED_COUNTER_FIELDS`, and only when that collection is actually being
+ * loaded; every other collection pays nothing.
+ *
+ * Fails OPEN to an empty set: if the existence probe itself fails we would
+ * rather write the seed's zeros (recoverable by one reconcile) than abort a
+ * load. The reconciler is the backstop either way.
+ */
+async function fetchExistingIds(db, collection) {
+  const fields = DERIVED_COUNTER_FIELDS[collection];
+  if (!fields) return null;
+  try {
+    const snap = await db.collection(collection).select().get();
+    return new Set(snap.docs.map((d) => d.id));
+  } catch (err) {
+    console.log(
+      `  ⚠ could not probe existing ${collection} ids (${err?.message ?? err}) — derived counters may be reset; run countersReconcileNow after this load`,
+    );
+    return null;
+  }
+}
+
+/** Drop derived-counter keys when the document already exists. */
+function stripDerivedCounters(collection, payload, docId, existingIds) {
+  const fields = DERIVED_COUNTER_FIELDS[collection];
+  if (!fields || !existingIds || !existingIds.has(docId)) return payload;
+  const out = {};
+  for (const [k, v] of Object.entries(payload)) {
+    if (fields.includes(k)) continue;
+    out[k] = v;
+  }
+  return out;
+}
+
 /**
  * The fields a human owns, per document id, for one collection.
  *
@@ -1190,6 +1266,20 @@ async function loadGeneric(colName, seed, firestoreCollection, stats) {
     const removed = await purgeCollection(firestoreCollection);
     if (VERBOSE) console.log(`    purged ${removed} pre-existing docs`);
   }
+  /*
+   * 🛑 Probed AFTER any replace-purge, never before. On a `REPLACE_ON_LOAD`
+   * collection the purge removes every document, so an id set taken earlier
+   * would claim rows exist that no longer do — and their derived counters
+   * would then be stripped from a payload that is now a CREATE, leaving the
+   * field absent on a required type. Probing here means a purged collection
+   * correctly reports nothing existing.
+   */
+  const existingIds = await fetchExistingIds(db, colName);
+  if (existingIds && existingIds.size > 0) {
+    console.log(
+      `  • ${colName}: preserving live ${DERIVED_COUNTER_FIELDS[colName].join("/")} on ${existingIds.size} existing doc(s)`,
+    );
+  }
   const items = [];
   for (const docData of seed) {
     let { id, ...data } = docData;
@@ -1236,9 +1326,20 @@ async function loadGeneric(colName, seed, firestoreCollection, stats) {
        * merge-write leaves an absent key exactly as it was, which is how the
        * correction survives.
        */
-      data: stripAdminOwned(
-        encryptSeedPii(colName, stripUndefined(stampSeedPurpose(colName, data, docId))),
-        adminOwned.get(docId),
+      /*
+       * 🛑 Derived counters dropped on an EXISTING document, after everything
+       * else, for the same reason admin-owned keys are: a merge-write leaves
+       * an absent key exactly as it was, which is what preserves the live
+       * value. Stripping earlier would let a later transform re-add it.
+       */
+      data: stripDerivedCounters(
+        colName,
+        stripAdminOwned(
+          encryptSeedPii(colName, stripUndefined(stampSeedPurpose(colName, data, docId))),
+          adminOwned.get(docId),
+        ),
+        docId,
+        existingIds,
       ),
     });
   }

package/dist/features/loyalty/api/admin/loyalty/grant/route.d.ts

@@ -1,12 +0,0 @@
-/**
- * feat-loyalty — POST /api/admin/loyalty/grant
- *
- * Admin endpoint to grant loyalty points.
- *
- * Consumer stub:
- * ```ts
- * export { adminLoyaltyGrantPOST as POST } from "@mohasinac/feat-loyalty";
- * ```
- */
-import { NextResponse } from "next/server.js";
-export declare function POST(request: Request): Promise<NextResponse>;