@mohasinac/appkit 4.45.0 → 4.46.0

package/dist/seed/products-standard-seed-data.js

@@ -656,6 +656,58 @@ const _rawProductsStandardSeedData = [
         createdAt: new Date("2026-08-24"),
         updatedAt: new Date("2026-08-24"),
     },
+    /*
+     * B6 — THE ONLY 18% GST ROW IN THE CATALOGUE.
+     *
+     * 🛑 `tax-hsn-95030010` (electronic toys, 18%) has existed as a `taxCodes`
+     * row since B3 with nothing referencing it, so the 18% arm of
+     * `calculateGst`, `gstByRate` (C0c defect 4), the per-rate invoice table and
+     * the blended-rate payout all had NO DATA that could exercise them. Four
+     * code paths that cannot be wrong because nothing reaches them.
+     *
+     * A BeyPointer is a battery-powered scoring device, which is what 9503 0010
+     * covers — so this is a genuinely electronic good rather than a flag planted
+     * on a convenient row.
+     *
+     * 🛑 No `gstRate`/`hsnCode` HERE, deliberately. They derive from
+     * `category-accessory-counters` through `deriveTaxonomy`, which is the path
+     * that will carry them in production. Hand-writing 18 would satisfy step 1 of
+     * the resolution order and leave the DERIVATION untested — a fixture that
+     * passes while the mechanism it exists to prove is never run, which is the
+     * shape of Root Cause #101.
+     *
+     * It is also what makes a MIXED-RATE cart possible for the first time: this
+     * row at 18% beside any bey at 5% is the one case C0c's §13 check 6b asks for
+     * and the catalogue could not previously express.
+     */
+    {
+        id: "product-beypointer-digital-battle-counter",
+        slug: "product-beypointer-digital-battle-counter",
+        barcodeId: "LIR-BEY-ACC-018",
+        title: "BeyPointer Digital Battle Counter",
+        description: "Battery-powered digital battle counter used for tournament scoring — tracks points across a best-of series, with a reset and a hold. Takes two AAA cells (not included). An electronic accessory, so it is taxed at the 18% electronic-toy rate rather than the 5% that applies to tops and parts.",
+        categorySlugs: ["category-accessory-counters", "category-accessories", "category-spinning-tops"],
+        categoryNames: ["Counters & BeyPointers", "Accessories", "Spinning Tops"],
+        brandSlug: "brand-takara-tomy",
+        brand: "Takara-Tomy",
+        price: 1299,
+        currency: "INR",
+        stockQuantity: 6,
+        availableQuantity: 6,
+        isSold: false,
+        mainImage: seedPhoto("product-image-beypointer-digital-battle-counter-1-20261012", 900, 900),
+        images: [
+            seedPhoto("product-image-beypointer-digital-battle-counter-1-20261012", 900, 900),
+            seedPhoto("product-image-beypointer-digital-battle-counter-2-20261012", 900, 900),
+        ],
+        status: PRODUCT_FIELDS.STATUS_VALUES.PUBLISHED,
+        condition: PRODUCT_FIELDS.CONDITION_VALUES.NEW,
+        tags: ["accessory"],
+        storeId: "store-beyblade-arena",
+        storeName: "Beyblade Arena",
+        createdAt: new Date("2026-10-12"),
+        updatedAt: new Date("2026-10-12"),
+    },
 ];
 export const productsStandardSeedData = [
     ..._rawProductsStandardSeedData.map((p) => withTokens({

package/dist/seed/seed-purpose.d.ts

@@ -133,15 +133,111 @@ export declare const PURGEABLE: Record<SeedPurpose, boolean>;
  * command, and the cost of being unable to clear it is the state this replaced.
  */
 export declare const SEED_COLLECTION_PURPOSE: Record<string, SeedPurpose>;
+/**
+ * Individual rows that differ from their collection's default, by document id.
+ *
+ * 🛑 This is the "clear all out EXCEPT our admin creds and the original single
+ * store" instruction, made declarative. Both collections default to `test` —
+ * every persona and every other store is disposable — and exactly two rows are
+ * not.
+ *
+ * ✅ The precedent already existed and this replaces it: `cmdDelete` has
+ * carried `PROTECTED_USER_UIDS = new Set(["user-admin-letitrip"])` for a long
+ * time, skipping that uid on a wholesale delete. One mechanism is better than a
+ * list the purge path happens to know about privately.
+ *
+ * 🛑 Keyed **`"<collection>:<id>"`**, and the collection half is load-bearing.
+ *
+ * It was a bare id, and a live read-back caught the consequence: `carts`,
+ * `wishlists` and `history` are all keyed on the USER id (CLAUDE.md: "Doc id =
+ * userId"), so `"user-admin-letitrip"` matched the admin's **cart** as well as
+ * the admin's user row — making a disposable cart permanently unpurgeable.
+ * Subtle, silent, and it would have left a stale cart surviving every purge
+ * forever.
+ *
+ * The id half is the DOCUMENT id, which for `users` is the Auth uid (`uid` on
+ * the seed row) and for everything else is `id`. `resolveSeedPurpose` checks
+ * both, because a seeded user row carries `uid` and no `id`.
+ */
+export declare const SEED_ROW_PURPOSE: Record<string, SeedPurpose>;
+/**
+ * Collections whose purpose FOLLOWS a referenced row rather than being declared.
+ *
+ * 🛑 This exists to hold one invariant: **a `permanent` row may not reference a
+ * `test` row**, because the purge would leave it behind as a dangling FK that
+ * still looks like real config.
+ *
+ * Measured in `store-extensions-seed-data.ts`: **14** rows reference
+ * `store-beyblade-arena` (test) and **9** reference `store-letitrip-official`
+ * (permanent). So marking `shippingConfigs` / `analyticsCards` permanent at the
+ * COLLECTION level — which the user's list implies and an earlier draft of the
+ * plan did — would strand 14 rows pointing at a store the purge deletes.
+ *
+ * Deriving is better than 23 hand-maintained per-row overrides for the usual
+ * reason: a hand-kept mirror drifts the moment a store is added (Root Cause
+ * #42), and a derivation is correct for stores that do not exist yet.
+ */
+export declare const SEED_PURPOSE_DERIVED_FROM: Record<string, {
+    readonly field: SeedReferenceField;
+    readonly collection: string;
+}>;
 /** A seeded row may override its collection's default inline. */
 export interface WithSeedPurpose {
     seedPurpose?: SeedPurpose;
 }
 /**
- * The row's own declaration wins; otherwise the collection default; otherwise
- * `test`.
+ * The fields `resolveSeedPurpose` reads off a row — all optional, because it is
+ * handed rows from 47 differently-shaped collections.
+ *
+ * 🛑 Declared explicitly rather than as `Record<string, unknown>`, which
+ * `audit-unknown-leakage` blocks and which is worse anyway: an index signature
+ * accepts ANY field name, so a typo in `SEED_PURPOSE_DERIVED_FROM.field` would
+ * read `undefined` and fall through to `test` silently — the exact mistake
+ * already made once, where `analyticsCards` was declared to derive from
+ * `storeId` and the rows carry `ownerId`.
+ *
+ * `SeedReferenceField` then constrains that `field` to one of these, so the
+ * same typo becomes a compile error.
+ */
+export interface SeedRowIdentity extends WithSeedPurpose {
+    /** Document id, on every collection except `users`. */
+    id?: string;
+    /** `users` seed rows carry the Auth uid and no `id`. */
+    uid?: string;
+    storeId?: string;
+    ownerId?: string;
+    userId?: string;
+    sellerId?: string;
+}
+/** The reference fields a derived collection may follow. */
+export type SeedReferenceField = "storeId" | "ownerId" | "userId" | "sellerId";
+/**
+ * Resolution order, most specific first:
+ *
+ *   1. the row's own inline `seedPurpose`
+ *   2. a per-row override in `SEED_ROW_PURPOSE`, by `id` or `uid`
+ *   3. for a DERIVED collection, the purpose of the row it references
+ *   4. the collection default
+ *   5. `test`
+ *
+ * 🛑 Step 3 is what holds the referential invariant. A `shippingConfig` for
+ * `store-letitrip-official` resolves `permanent`; one for
+ * `store-beyblade-arena` resolves `test` and is purged alongside the store it
+ * configures, rather than outliving it.
+ */
+export declare function resolveSeedPurpose(collection: string, row?: SeedRowIdentity | null, 
+/**
+ * The document id, when the caller has it and the row does not.
+ *
+ * 🛑 Required by `loadGeneric`, which does `let { id, ...data } = docData`
+ * and therefore hands this function a row with **no `id` at all**. Without
+ * this parameter the per-row overrides silently did not apply: measured,
+ * `store-letitrip-official` loaded as `test` — i.e. the platform's own store
+ * would have been purged, which is exactly the row the keep-list exists to
+ * protect. `loadUsers` was unaffected because `{ ...u }` keeps `uid`, which
+ * is why the admin override worked and the store one did not.
  */
-export declare function resolveSeedPurpose(collection: string, row?: WithSeedPurpose | null): SeedPurpose;
+docId?: string | null): SeedPurpose;
 export interface SeedPurposeFields {
     seedPurpose: SeedPurpose;
 }
@@ -167,7 +263,10 @@ export declare function seedPurposeFields(purpose: SeedPurpose): SeedPurposeFiel
  * Returns a NEW object; the seed arrays are module-level constants re-imported
  * on every CLI invocation and must not be mutated.
  */
-export declare function stampSeedPurpose<T extends WithSeedPurpose>(collection: string, row: T): T & SeedPurposeFields;
+export declare function stampSeedPurpose<T extends WithSeedPurpose>(collection: string, row: T, 
+/** Pass this whenever the caller holds the id and the row does not — see
+ *  `resolveSeedPurpose`'s `docId` for why `loadGeneric` must. */
+docId?: string | null): T & SeedPurposeFields;
 /**
  * Mark a whole array as something other than its collection default — the
  * readable way to say "this file is permanent" (or "this file is fixtures")

package/dist/seed/seed-purpose.js

@@ -131,6 +131,23 @@ export const SEED_COLLECTION_PURPOSE = {
     /* Branding, fees, commissions, watermark, legal pages, and the AES-encrypted
      * credentials. 🛑 A purge here would destroy live API keys. */
     siteSettings: "permanent",
+    /*
+     * ── permanent, second tranche: the site's own CONTENT and COMPOSITION ────
+     *
+     * Added on the user's explicit list. The same test applies and they pass it:
+     * clearing any of these means re-AUTHORING, not re-running a loader.
+     *
+     * 🛑 But "permanent" obliges us to make them REAL — see G1c in the plan.
+     * Marking a placeholder permanent only makes the placeholder unpurgeable, so
+     * each of these has to trace to a crawl source: blogPosts to the buying/rules
+     * guide split, homepageSections to worldhobbyshop's generation tiles and
+     * 25-link systems matrix, carouselSlides to beybladeartshop's 5-slide hero
+     * including the anti-counterfeit slide.
+     */
+    blogPosts: "permanent",
+    carousels: "permanent",
+    carouselSlides: "permanent",
+    homepageSections: "permanent",
     /*
      * 🛑 The tester checklist cases are PERMANENT CONTENT, not scaffolding.
      *
@@ -145,6 +162,15 @@ export const SEED_COLLECTION_PURPOSE = {
      * default is for.
      */
     testerChecklistItems: "permanent",
+    /*
+     * E4/D12 — PERMANENT. These are extracted from a corpus by committed
+     * scripts, not fixtures: clearing them means re-running an extraction over a
+     * 7 GB local crawl, which is the test § G1c sets ("if clearing it means
+     * somebody has to WRITE it again rather than re-run a loader"). Re-running
+     * the extractor is possible but needs a corpus a clone will not have.
+     */
+    partGlossary: "permanent",
+    modelComposition: "permanent",
     testerChecklistResponses: "test",
     /*
      * ── test: everything else ───────────────────────────────────────────────
@@ -172,20 +198,14 @@ export const SEED_COLLECTION_PURPOSE = {
     notifications: "test",
     supportTickets: "test",
     catalogueItems: "test",
-    blogPosts: "test",
     events: "test",
     eventEntries: "test",
     groupedListings: "test",
     scammerProfiles: "test",
-    carousels: "test",
-    carouselSlides: "test",
-    homepageSections: "test",
     procurementShipments: "test",
     shipmentLots: "test",
     shipmentItems: "test",
     payoutMethods: "test",
-    shippingConfigs: "test",
-    analyticsCards: "test",
     analyticsAlerts: "test",
     storeCategories: "test",
     listingTemplates: "test",
@@ -195,12 +215,131 @@ export const SEED_COLLECTION_PURPOSE = {
     storeGoogleConfig: "test",
 };
 /**
- * The row's own declaration wins; otherwise the collection default; otherwise
- * `test`.
+ * Individual rows that differ from their collection's default, by document id.
+ *
+ * 🛑 This is the "clear all out EXCEPT our admin creds and the original single
+ * store" instruction, made declarative. Both collections default to `test` —
+ * every persona and every other store is disposable — and exactly two rows are
+ * not.
+ *
+ * ✅ The precedent already existed and this replaces it: `cmdDelete` has
+ * carried `PROTECTED_USER_UIDS = new Set(["user-admin-letitrip"])` for a long
+ * time, skipping that uid on a wholesale delete. One mechanism is better than a
+ * list the purge path happens to know about privately.
+ *
+ * 🛑 Keyed **`"<collection>:<id>"`**, and the collection half is load-bearing.
+ *
+ * It was a bare id, and a live read-back caught the consequence: `carts`,
+ * `wishlists` and `history` are all keyed on the USER id (CLAUDE.md: "Doc id =
+ * userId"), so `"user-admin-letitrip"` matched the admin's **cart** as well as
+ * the admin's user row — making a disposable cart permanently unpurgeable.
+ * Subtle, silent, and it would have left a stale cart surviving every purge
+ * forever.
+ *
+ * The id half is the DOCUMENT id, which for `users` is the Auth uid (`uid` on
+ * the seed row) and for everything else is `id`. `resolveSeedPurpose` checks
+ * both, because a seeded user row carries `uid` and no `id`.
+ */
+export const SEED_ROW_PURPOSE = {
+    /* Our own admin account. Clearing it locks us out of our own site — and the
+     * Auth record is the half most easily missed, since `appkit-seed delete` does
+     * not touch Firebase Auth at all. */
+    "users:user-admin-letitrip": "permanent",
+    /* The platform's own default store. The other three seeded stores
+     * (beyblade-arena, blader-bazaar, vintage-vault-co) are test fixtures. */
+    "stores:store-letitrip-official": "permanent",
+};
+/**
+ * Collections whose purpose FOLLOWS a referenced row rather than being declared.
+ *
+ * 🛑 This exists to hold one invariant: **a `permanent` row may not reference a
+ * `test` row**, because the purge would leave it behind as a dangling FK that
+ * still looks like real config.
+ *
+ * Measured in `store-extensions-seed-data.ts`: **14** rows reference
+ * `store-beyblade-arena` (test) and **9** reference `store-letitrip-official`
+ * (permanent). So marking `shippingConfigs` / `analyticsCards` permanent at the
+ * COLLECTION level — which the user's list implies and an earlier draft of the
+ * plan did — would strand 14 rows pointing at a store the purge deletes.
+ *
+ * Deriving is better than 23 hand-maintained per-row overrides for the usual
+ * reason: a hand-kept mirror drifts the moment a store is added (Root Cause
+ * #42), and a derivation is correct for stores that do not exist yet.
+ */
+export const SEED_PURPOSE_DERIVED_FROM = {
+    shippingConfigs: { field: "storeId", collection: "stores" },
+    /*
+     * 🛑 `ownerId` → `users`, NOT `storeId` → `stores`. I wrote the store form
+     * first and the data disproved it: measured, `analyticsCardsSeedData` carries
+     * **zero** `storeId` fields — every row is `{ scope: "seller", ownerId:
+     * "user-tyson-blader", … }`. So these follow the USER whose dashboard they
+     * compose, and since that user is a test persona all nine correctly resolve
+     * `test`.
+     *
+     * Worth recording because the wrong field does not error: a derived row whose
+     * named field is absent falls to `test`, which happened to be the right
+     * answer here and would have silently been the WRONG one for a card owned by
+     * the admin.
+     */
+    analyticsCards: { field: "ownerId", collection: "users" },
+};
+/**
+ * Resolution order, most specific first:
+ *
+ *   1. the row's own inline `seedPurpose`
+ *   2. a per-row override in `SEED_ROW_PURPOSE`, by `id` or `uid`
+ *   3. for a DERIVED collection, the purpose of the row it references
+ *   4. the collection default
+ *   5. `test`
+ *
+ * 🛑 Step 3 is what holds the referential invariant. A `shippingConfig` for
+ * `store-letitrip-official` resolves `permanent`; one for
+ * `store-beyblade-arena` resolves `test` and is purged alongside the store it
+ * configures, rather than outliving it.
  */
-export function resolveSeedPurpose(collection, row) {
+export function resolveSeedPurpose(collection, row, 
+/**
+ * The document id, when the caller has it and the row does not.
+ *
+ * 🛑 Required by `loadGeneric`, which does `let { id, ...data } = docData`
+ * and therefore hands this function a row with **no `id` at all**. Without
+ * this parameter the per-row overrides silently did not apply: measured,
+ * `store-letitrip-official` loaded as `test` — i.e. the platform's own store
+ * would have been purged, which is exactly the row the keep-list exists to
+ * protect. `loadUsers` was unaffected because `{ ...u }` keeps `uid`, which
+ * is why the admin override worked and the store one did not.
+ */
+docId) {
     if (row && isSeedPurpose(row.seedPurpose))
         return row.seedPurpose;
+    /* `"<collection>:<id>"` — the collection half is what stops a users
+     * override also matching that user's CART, which is keyed on the same id. */
+    const rowKey = (coll, id) => `${coll}:${id}`;
+    if (docId && isSeedPurpose(SEED_ROW_PURPOSE[rowKey(collection, docId)]))
+        return SEED_ROW_PURPOSE[rowKey(collection, docId)];
+    if (row) {
+        /* `users` seed rows carry `uid` and no `id`; everything else carries `id`. */
+        const ownId = typeof row.id === "string" ? row.id : typeof row.uid === "string" ? row.uid : null;
+        if (ownId && isSeedPurpose(SEED_ROW_PURPOSE[rowKey(collection, ownId)]))
+            return SEED_ROW_PURPOSE[rowKey(collection, ownId)];
+        const derived = SEED_PURPOSE_DERIVED_FROM[collection];
+        if (derived) {
+            const refId = row[derived.field];
+            if (typeof refId === "string") {
+                const refOverride = SEED_ROW_PURPOSE[rowKey(derived.collection, refId)];
+                if (isSeedPurpose(refOverride))
+                    return refOverride;
+                const refDefault = SEED_COLLECTION_PURPOSE[derived.collection];
+                return isSeedPurpose(refDefault) ? refDefault : "test";
+            }
+            /*
+             * A derived row with no reference cannot inherit, and guessing
+             * `permanent` would be the dangling-FK failure this map exists to
+             * prevent. `test` is the safe answer: it is re-seedable.
+             */
+            return "test";
+        }
+    }
     const declared = SEED_COLLECTION_PURPOSE[collection];
     return isSeedPurpose(declared) ? declared : "test";
 }
@@ -228,8 +367,20 @@ export function seedPurposeFields(purpose) {
  * Returns a NEW object; the seed arrays are module-level constants re-imported
  * on every CLI invocation and must not be mutated.
  */
-export function stampSeedPurpose(collection, row) {
-    return { ...row, ...seedPurposeFields(resolveSeedPurpose(collection, row)) };
+export function stampSeedPurpose(collection, row, 
+/** Pass this whenever the caller holds the id and the row does not — see
+ *  `resolveSeedPurpose`'s `docId` for why `loadGeneric` must. */
+docId) {
+    /*
+     * The cast is to `Record<string, unknown>` only, which is a WIDENING — every
+     * object satisfies it structurally, and `resolveSeedPurpose` reads `id`,
+     * `uid` and the derived `field` with `typeof` guards rather than trusting the
+     * type. 🛑 Deliberately NOT `as any`: that would silence the `collection`
+     * argument's check too, which is the mistake the plan records at the
+     * `sendNotification`/`as never` sites.
+     */
+    const purpose = resolveSeedPurpose(collection, row, docId);
+    return { ...row, ...seedPurposeFields(purpose) };
 }
 /**
  * Mark a whole array as something other than its collection default — the

package/dist/seo/json-ld.d.ts

@@ -93,7 +93,16 @@ export interface FaqJsonLdInput {
 }
 export interface BreadcrumbJsonLdItem {
     name: string;
-    url: string;
+    /**
+     * Absent on the LAST crumb — the page you are already on.
+     *
+     * 🛑 This was required, and `url.startsWith(...)` threw on a missing one. It
+     * is optional because schema.org's own breadcrumb guidance is that the final
+     * element identifies the current page and its `item` may be omitted; a
+     * self-link there is accepted but says nothing. Every existing caller passes
+     * a url, so widening it breaks none of them.
+     */
+    url?: string;
 }
 export interface BlogPostJsonLdInput {
     title: string;

package/dist/seo/json-ld.js

@@ -174,7 +174,15 @@ export function breadcrumbJsonLd(items) {
             "@type": "ListItem",
             position: index + 1,
             name: item.name,
-            item: item.url.startsWith("http") ? item.url : `${SITE_URL}${item.url}`,
+            /*
+             * `item` is OMITTED rather than emitted empty when there is no url.
+             * `item: ""` would resolve to the site root, so every page's final crumb
+             * would link to the homepage — a wrong link is worse than an absent one,
+             * and absent is what the spec asks for on the current page.
+             */
+            ...(item.url
+                ? { item: item.url.startsWith("http") ? item.url : `${SITE_URL}${item.url}` }
+                : {}),
         })),
     };
 }

package/dist/server.d.ts

@@ -1,4 +1,11 @@
 export { isAuthError } from "./utils/auth-error";
+export { searchEverything } from "./_internal/server/features/search/search-everything";
+export type { SearchHit, SearchGroup, SearchSource, SearchEverythingResult, } from "./_internal/server/features/search/search-everything";
+export { SEARCH_SOURCES } from "./_internal/server/features/search/search-sources";
+export { getPartByKey, getModelsUsingPart, getCompositionById, getPartsForComposition, getCompositionsForCategory, listPartsBySlot, } from "./_internal/server/features/parts/data";
+export { renderPartOg, renderPartClassificationOg, } from "./_internal/server/features/parts/og";
+export { assembleFromComponents, partOutToComponents, planAssembly, assertAssemblyInput, MAX_ASSEMBLY_COMPONENTS, } from "./_internal/server/features/parts/assembly";
+export type { AssemblyComponent, AssembleInput, PartOutInput, AssemblyResult, AssemblyPlan, StockWrite, } from "./_internal/server/features/parts/assembly";
 export { safeRead, installDegradedReadReporter, } from "./errors/safe-read";
 export type { DegradedReadReport } from "./errors/safe-read";
 export { ServerErrorsRepository, serverErrorsRepository, } from "./features/server-errors/repository/server-errors.repository";

package/dist/server.js

@@ -2,6 +2,17 @@
 // isAuthError - Pure util — detects auth errors from caught exceptions (usable in server actions).
 export { isAuthError } from "./utils/auth-error.js";
 // [SERVER-ONLY] safeRead — wraps optional reads whose failure must not break a page.
+// D2 Fix 4 — cross-resource search. Exported from `server.ts` because it takes
+// a Firestore handle and runs only server-side; `_internal/` is not an
+// exported subpath, and a consumer page must not reach into it.
+export { searchEverything } from "./_internal/server/features/search/search-everything.js";
+export { SEARCH_SOURCES } from "./_internal/server/features/search/search-sources.js";
+// D12 — part + composition reads. Every one is by document id or ONE
+// indexed equality; none needs a composite index.
+export { getPartByKey, getModelsUsingPart, getCompositionById, getPartsForComposition, getCompositionsForCategory, listPartsBySlot, } from "./_internal/server/features/parts/data.js";
+export { renderPartOg, renderPartClassificationOg, } from "./_internal/server/features/parts/og.js";
+// D13 — assembly and part-out. Both run in a real transaction that RE-READS.
+export { assembleFromComponents, partOutToComponents, planAssembly, assertAssemblyInput, MAX_ASSEMBLY_COMPONENTS, } from "./_internal/server/features/parts/assembly.js";
 // Persists DEGRADED_READ rows via the installed reporter; returns typed fallback on error.
 export { safeRead, installDegradedReadReporter, } from "./errors/safe-read.js";
 // [SERVER-ONLY] serverErrorsRepository — Firestore-backed persistent log for 5xx + selected 4xx.