@mohasinac/appkit 4.53.0 → 4.53.2

package/dist/ui/index.js

@@ -30,6 +30,7 @@ export { FormErrorSummary } from "./forms/index.js";
 export { buildColumns, createColumnBuilder, renderBoolean, renderCurrency, renderCurrencyCompact, renderCount, renderNullable, renderRating, getStatusTone, getResourceIcon, } from "./columns/index.js";
 export { Section, sectionBackgroundStyle, Article, Main, Aside, Nav, BlockHeader, BlockFooter, Ul, Ol, Li, Table, Thead, Tbody, Tr, Th, Td, Code, Pre, Blockquote, Figure, Figcaption, Dl, Dt, Dd, } from "./components/Semantic.js";
 export { Div } from "./components/Div.js";
+export { SpecTable } from "./components/SpecTable.js";
 export { Heading, Text, Label, Caption, Span } from "./components/Typography.js";
 // --- Filter chip group (SB10-C completion, S8 2026-05-13) --------------------
 export { FilterChipGroup } from "./components/FilterChipGroup.js";
@@ -156,6 +157,7 @@ export { HorizontalRule } from "./components/HorizontalRule.js";
 export { Anchor } from "./components/Anchor.js";
 export { Scrim } from "./components/Scrim.js";
 export { Kbd } from "./components/Kbd.js";
+export { PendingValue } from "./components/PendingValue.js";
 export { StickyToolbar } from "./components/StickyToolbar.js";
 export { Show, Hide } from "./components/Responsive.js";
 export { CollapsibleSection } from "./components/CollapsibleSection.js";

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

@@ -87,6 +87,18 @@ export interface SearchWindowModel {
  *
  * `refineSearchTxt` grew a real-pagination mode, and `products` was the only
  * caller converted — deliberately, so the other eleven stayed byte-identical.
+ *
+ * 🛑 That sentence is now HISTORY, not status. Measured 2026-10-19: ELEVEN
+ * repositories use `beginSearchWindow`, and `audit-listing-search-intact`
+ * (C6) enforces all three parts of the conversion on each of them — doing
+ * parts 1 and 3 without 2 "reads exactly like a working conversion and is
+ * the half that no-ops", which is why the audit checks the triple rather
+ * than the presence of the call.
+ *
+ * `faqs` is the deliberate holdout: it hand-rolls the refine and returns the
+ * legacy page-only shape, which this file's own docstring describes as
+ * "preserved verbatim for unconverted callers". That is a known limitation,
+ * not a defect — do not "fix" it as a bug (Rule #4).
  * The conversion is mechanical and has THREE parts that must all happen:
  *
  *   1. fetch a bounded WINDOW instead of the requested page;

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

@@ -56,6 +56,18 @@ export const SEARCH_REFINE_WINDOW = 250;
  *
  * `refineSearchTxt` grew a real-pagination mode, and `products` was the only
  * caller converted — deliberately, so the other eleven stayed byte-identical.
+ *
+ * 🛑 That sentence is now HISTORY, not status. Measured 2026-10-19: ELEVEN
+ * repositories use `beginSearchWindow`, and `audit-listing-search-intact`
+ * (C6) enforces all three parts of the conversion on each of them — doing
+ * parts 1 and 3 without 2 "reads exactly like a working conversion and is
+ * the half that no-ops", which is why the audit checks the triple rather
+ * than the presence of the call.
+ *
+ * `faqs` is the deliberate holdout: it hand-rolls the refine and returns the
+ * legacy page-only shape, which this file's own docstring describes as
+ * "preserved verbatim for unconverted callers". That is a known limitation,
+ * not a defect — do not "fix" it as a bug (Rule #4).
  * The conversion is mechanical and has THREE parts that must all happen:
  *
  *   1. fetch a bounded WINDOW instead of the requested page;

package/package.json

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

package/scripts/dedupe-peer-deps.mjs

@@ -44,6 +44,24 @@ const TRANSITIVE_RUNTIME_DUPS = [
   // query-core and a parallel QueryClientContext instance ships in the SSR
   // bundle, producing the "No QueryClient set" crash on every page (2026-06-11).
   "@tanstack/query-core",
+  /*
+   * firebase-admin (peer) bundles @google-cloud/storage, which does NOT own a
+   * React context — so the 2026-06-11 runtime crash class does not apply here.
+   * It still has to be pruned, for a different reason: TYPE IDENTITY.
+   *
+   * `Bucket` carries a private member, so TypeScript compares the two copies
+   * nominally and refuses to pass a root-resolved Bucket into a function typed
+   * against appkit's copy. Any appkit module that accepts a Bucket from a
+   * caller is then uncompilable from the consumer, which includes appkit/src
+   * under the file: pin.
+   *
+   * MEASURED rather than assumed: removing the directory fixes it and
+   * restoring it brings the error straight back, with the tsbuildinfo cleared
+   * both times — the first attempt cleared a stale cache in the same step and
+   * could not tell which change was responsible.
+   */
+  "@google-cloud/storage",
+  "@google-cloud/firestore",
 ];
 
 // Peer deps that have NO React context / module-scope singleton and that the

package/scripts/seed-cli.mjs

@@ -181,7 +181,8 @@ const appkit = await import("@mohasinac/appkit");
 // client-safe barrel, only from "@mohasinac/appkit/server". The *_PII_FIELDS
 // / *_PII_INDEX_MAP constants are plain data and stay in the main barrel.
 const appkitServer = await import("@mohasinac/appkit/server");
-const { encryptPiiFields, piiIndicesFor, encryptPayoutDetails, encryptPayoutBankAccount, encryptShippingConfig } = appkitServer;
+const { encryptPiiFields, piiIndicesFor, encryptPayoutDetails, encryptPayoutBankAccount, encryptShippingConfig,
+  buildTokensIndex, BLIND_INDEX_KEY_VERSION_FIELD, CURRENT_BLIND_INDEX_KEY_VERSION } = appkitServer;
 
 const {
   // seed data
@@ -191,9 +192,9 @@ const {
   storeCategoriesSeedData, listingTemplatesSeedData, moderationQueueSeedData, reportsSeedData,
   itemRequestsSeedData, storeGoogleConfigSeedData,
   categoriesSeedData, storesSeedData, sessionsSeedData,
-  productsStandardSeedData, productsAuctionsSeedData, productsPreordersSeedData,
+  productsStandardSeedData, productsBeybladeXSeedData, productsAuctionsSeedData, productsPreordersSeedData,
   productsPrizeDrawsSeedData, productsClassifiedsSeedData, productsDigitalCodesSeedData, productsLiveItemsSeedData,
-  productsArtSeedData, productsStickersSeedData,
+  productsArtSeedData, productsStickersSeedData, productsSparesSeedData,
   productsCatalogueSeedData,
   FRANCHISE_BY_CATEGORY_ROOT,
   ordersSeedData, reviewsSeedData, cartsSeedData, bidsSeedData,
@@ -386,6 +387,104 @@ const COLLECTION_MAP = {
  * A root with no mapping yields NO franchise (living collectibles are not an
  * IP) — see `FRANCHISE_BY_CATEGORY_ROOT`.
  */
+/**
+ * The real, sellable catalogue — everything else in the product seed is demo
+ * furniture and is DROPPED HERE, before anything is written.
+ *
+ * ── 🛑 WHY A FILTER AND NOT A DELETION ────────────────────────────────────
+ *
+ * The fixtures stay in their files on purpose: they are the only coverage
+ * several features have (every `preOrderProductionStatus` value, a sold-out
+ * reservation, a depleted digital-code pool, an ended-unsold auction), and
+ * the tester checklist deep-links to them by id. Deleting them would silently
+ * remove that coverage. Not LOADING them is the part that was wanted.
+ *
+ * ── 🛑 WHY THIS HAD TO EXIST ──────────────────────────────────────────────
+ *
+ * `appkit-seed load` writes every registered row and `purge` deletes
+ * `seedPurpose: "test"` afterwards — so the demo listings came BACK on every
+ * reseed, and anyone who ran `load` to fix imagery silently republished 76
+ * fake products to the live storefront. That happened twice in one session.
+ * The owner's instruction was "delete them from the seed itself and make sure
+ * they do not return"; this is the point where that can be guaranteed, since
+ * every write path funnels through here.
+ *
+ * ── The discriminator is the STORE, not the listing type ──────────────────
+ *
+ * `store-beyblade-arena` is the fictional demo seller; `store-letitrip-
+ * official` is the real one. Keying on the store rather than on a per-file
+ * allow-list means a fixture added to ANY product seed file later is excluded
+ * automatically, which is the failure mode this is replacing — a list that
+ * has to be remembered is a list that drifts.
+ *
+ * Set `SEED_INCLUDE_DEMO=1` to load them anyway, for local demo work.
+ */
+const REAL_STORE_IDS = new Set(["store-letitrip-official"]);
+
+function realListingsOnly(products) {
+  if (process.env.SEED_INCLUDE_DEMO === "1") {
+    console.log("▌ SEED_INCLUDE_DEMO=1 — demo listings INCLUDED");
+    return products;
+  }
+  /*
+   * 🛑 TWO rules, because the store alone is not enough. Six prize-draw
+   * fixtures live under the REAL store and are still demo furniture — their
+   * imagery is a 460-byte generated colour tile from /images/seed-tiles/,
+   * which is the giveaway: a listing nobody photographed is a listing nobody
+   * intends to sell. Measured before writing this: every one of the six, and
+   * nothing real, matches.
+   */
+  const isPlaceholder = (p) => {
+    const urls = [p?.mainImage, ...(Array.isArray(p?.images) ? p.images : [])]
+      .map((v) => (typeof v === "string" ? v : v?.url))
+      .filter(Boolean);
+    return urls.length > 0 && urls.every((u) => String(u).includes("/images/seed-tiles/"));
+  };
+  const kept = products.filter((p) => REAL_STORE_IDS.has(p?.storeId) && !isPlaceholder(p));
+  const dropped = products.length - kept.length;
+  if (dropped > 0) {
+    console.log(`  • ${dropped} demo listing(s) not loaded (set SEED_INCLUDE_DEMO=1 to include)`);
+  }
+  return kept;
+}
+
+/**
+ * Drop bundle categories whose members are not in the loaded catalogue.
+ *
+ * 🛑 A bundle is ALL-OR-NOTHING — `canAddToCart` buys every member together —
+ * so a bundle missing even one member is unsellable, and one missing ALL of
+ * them is a card that opens an empty page. Measured right after the demo
+ * listings stopped loading: of the five seeded bundles, three had zero
+ * surviving members and the other two had 1-of-4 and 2-of-3. All five were
+ * still `isActive: true`, and all five rendered on the HOMEPAGE as collage
+ * cards built from `display.mosaicImages` — which are baked at seed time from
+ * the members' own imagery, so they kept showing pictures of products that no
+ * longer exist. That is 92 placeholder-tile references on the homepage.
+ *
+ * Derived rather than hand-maintained for the same reason as the product
+ * filter: a bundle that becomes valid later starts loading again on its own,
+ * and one that breaks stops, with nobody having to remember either.
+ *
+ * Only `categoryType: "bundle"` rows are considered. Every other category is
+ * taxonomy and is never touched — rebuilding the tree is expensive and is
+ * explicitly not what this is for.
+ */
+function loadableBundlesOnly(categories, loadedProducts) {
+  const live = new Set(loadedProducts.map((p) => p?.id).filter(Boolean));
+  let dropped = 0;
+  const kept = categories.filter((c) => {
+    if (c?.categoryType !== "bundle") return true;
+    const ids = Array.isArray(c.bundleProductIds) ? c.bundleProductIds : [];
+    const ok = ids.length > 0 && ids.every((id) => live.has(id));
+    if (!ok) dropped++;
+    return ok;
+  });
+  if (dropped > 0) {
+    console.log(`  • ${dropped} bundle(s) not loaded — members missing from the catalogue`);
+  }
+  return kept;
+}
+
 function withFranchise(products) {
   let stamped = 0;
   const out = products.map((p) => {
@@ -468,6 +567,56 @@ function withDerivedCategoryFields(products) {
   return out;
 }
 
+/**
+ * The real catalogue, computed ONCE so the bundle filter and the product
+ * loader cannot disagree about what "loaded" means. Deriving it twice is
+ * Root Cause #75's shape — two copies of one rule, one of which learns about
+ * a change and the other does not.
+ */
+const REAL_PRODUCTS = realListingsOnly([
+    ...(productsStandardSeedData || []),
+    // Real, wiki-verified Beyblade X listings under store-letitrip-official —
+    // added 2026-10-19 for PhonePe merchant registration, which requires at
+    // least one genuinely purchasable product. See the file's own header.
+    ...(productsBeybladeXSeedData || []),
+    ...(productsAuctionsSeedData || []), ...(productsPreordersSeedData || []),
+    ...(productsPrizeDrawsSeedData || []), ...(productsClassifiedsSeedData || []), ...(productsDigitalCodesSeedData || []), ...(productsLiveItemsSeedData || []),
+    // art + stickers were written, exported from the seed barrel, and then never
+    // spread here — so 13 fixtures had NEVER reached the database, /art and
+    // /stickers were permanently empty, and listingType=art|stickers returned 0.
+    // Root Cause #58's family one layer down: added everywhere except the runner.
+    ...(productsArtSeedData || []), ...(productsStickersSeedData || []),
+    // 🛑 BOTH sites, every time. This file's own header records 13 art/sticker
+    // fixtures that never reached the database because only the import was
+    // edited and this spread was not — the loader then wrote every OTHER
+    // product and reported success.
+    ...(productsSparesSeedData || []),
+    /*
+     * 🛑 DEREGISTERED 2026-10-19 — productsCatalogueSeedData (1,237 rows, one
+     * per taxonomy leaf) is NOT spread here, on purpose.
+     *
+     * This is a reversal of the comment that used to be here, which said the
+     * opposite: that this spread was "what makes `products` reproducible
+     * after a full wipe." That was true when the catalogue was the only
+     * content under its leaf categories. It stopped being true the moment
+     * real curated listings exist for the SAME leaves — four of them,
+     * confirmed by grep: `category-aeropegasus-3-70a`, `category-
+     * valkyrievolt-s4-70v`, `category-wizardarrow-4-80b`, `category-
+     * knightshield-3-80n` each already carry one generated row. Re-enabling
+     * this spread would not just add filler back — it would put a
+     * hash-priced synthetic duplicate (one measured as a NEGATIVE price,
+     * `-61`) into the exact categories the real BX-53 fixture now occupies,
+     * silently resurrecting the thing a full `appkit-seed purge` was just run
+     * to remove.
+     *
+     * The generator (`scripts/gen-catalogue-listings.mjs`) and the committed
+     * file itself are both left untouched — this is deliberately a one-line
+     * "stop loading it" change, not a deletion. Re-enable only after deciding
+     * what should happen to a leaf that now has BOTH a real listing and a
+     * generated one.
+     */
+  ]);
+
 const SEED_DATA_MAP = {
   users: usersSeedData,
   /*
@@ -491,22 +640,9 @@ const SEED_DATA_MAP = {
   storeAddresses: storeAddressesSeedData,
   // SB-UNI-C: brands were merged into categories (categoryType:"brand") — no
   // standalone brands collection/seed exists anymore.
-  categories: categoriesSeedData,
+  categories: loadableBundlesOnly(categoriesSeedData, REAL_PRODUCTS),
   stores: storesSeedData,
-  products: withFranchise(withDerivedCategoryFields([
-    ...(productsStandardSeedData || []), ...(productsAuctionsSeedData || []), ...(productsPreordersSeedData || []),
-    ...(productsPrizeDrawsSeedData || []), ...(productsClassifiedsSeedData || []), ...(productsDigitalCodesSeedData || []), ...(productsLiveItemsSeedData || []),
-    // art + stickers were written, exported from the seed barrel, and then never
-    // spread here — so 13 fixtures had NEVER reached the database, /art and
-    // /stickers were permanently empty, and listingType=art|stickers returned 0.
-    // Root Cause #58's family one layer down: added everywhere except the runner.
-    ...(productsArtSeedData || []), ...(productsStickersSeedData || []),
-    // The 972 generated catalogue-filler listings (one per taxonomy leaf) —
-    // see scripts/gen-catalogue-listings.mjs. This is what makes `products`
-    // reproducible after a full wipe; without it the collection drops from
-    // 1,039 to 71 the moment someone purges it.
-    ...(productsCatalogueSeedData || []),
-  ])),
+  products: withFranchise(withDerivedCategoryFields(REAL_PRODUCTS)),
   orders: ordersSeedData,
   reviews: reviewsSeedData,
   bids: bidsSeedData,
@@ -596,6 +732,33 @@ async function purgeCollection(path) {
   return removed;
 }
 
+/*
+ * 🛑 `TOKENS_INDEX_MAP` holds ONLY `payouts`, and that is a measured fact
+ * about this file, not an oversight.
+ *
+ * `encryptSeedPii` is called from exactly one place — `loadGeneric`'s
+ * per-doc loop. `users` and `addresses` are seeded by their OWN dedicated
+ * loaders (`loadUsers`, the addresses block near line 1029) that write
+ * straight to Firestore and never call this function — so a `users`/
+ * `addresses` entry here would be dead code, silently unreachable, which is
+ * worse than no entry: it would read as "handled" to the next person who
+ * greps for it.
+ *
+ * It is also the right scope rather than a gap, because `users` and
+ * `addresses` are PRESERVE-tier in the tester harness — never wiped, never
+ * reseeded — so the only two things that can write their `*TokensIndex`
+ * are a REAL write (covered by `UserRepository`/`AddressesRepository`'s
+ * `buildTokensIndexFor`, wired separately) and the one-time bootstrap seed
+ * load `appkit-seed load --collections users` documented in CLAUDE.md's
+ * § "Claude Tester" — which `backfill-blind-index.mjs` exists to catch up
+ * after. `payouts` has no such safety net: it is SEED_TRANSACTIONAL, so it
+ * cascades and RESEEDS on every tester run that touches its store, through
+ * exactly this function — which is why it is the one entry that matters.
+ */
+const TOKENS_INDEX_MAP = {
+  payouts: { field: "sellerTokensIndex", from: ["sellerName", "sellerEmail"] },
+};
+
 function encryptSeedPii(collection, data) {
   const PII_MAP = {
     orders: ORDER_PII_FIELDS,
@@ -607,11 +770,28 @@ function encryptSeedPii(collection, data) {
     eventEntries: EVENT_ENTRY_PII_FIELDS,
   };
   const fields = PII_MAP[collection];
-  if (!fields) return data;
-  let result = encryptPiiFields(data, [...fields]);
+  let result = fields ? encryptPiiFields(data, [...fields]) : { ...data };
   if (collection === "payouts" && result.bankAccount) {
     result.bankAccount = encryptPayoutBankAccount(result.bankAccount);
   }
+
+  /*
+   * 🛑 THIS IS WHAT MAKES `payouts` SURVIVE A TESTER WIPE WITH A WORKING
+   * SEARCH INDEX. `payouts` is SEED_TRANSACTIONAL in the tester harness —
+   * it cascades on `storeId` whenever its store is wiped, then gets
+   * RE-SEEDED by exactly this function. Without this block, the reseeded
+   * documents would carry ciphertext and no `sellerTokensIndex` at all,
+   * silently undoing a one-shot backfill on the very next tester run.
+   */
+  const tokensIndex = TOKENS_INDEX_MAP[collection];
+  if (tokensIndex) {
+    const values = tokensIndex.from.map((f) => data[f]).filter((v) => typeof v === "string");
+    if (values.length > 0) {
+      result[tokensIndex.field] = buildTokensIndex(...values);
+      result[BLIND_INDEX_KEY_VERSION_FIELD] = CURRENT_BLIND_INDEX_KEY_VERSION;
+    }
+  }
+
   return result;
 }
 
@@ -1229,9 +1409,23 @@ async function cmdPurge() {
     const sub = SUBCOLLECTIONS.find((s) => s.key === colName);
     try {
       if (sub) {
-        /* A collection-group query reaches every parent at once. */
-        const snap = await db.collectionGroup(sub.name).where("seedPurpose", "==", "test").get();
-        if (snap.size > 0) plan.push({ colName, docs: snap.docs, isSub: true });
+        /*
+         * 🛑 Unfiltered collection-group read, filtered in memory — NOT
+         * `.where("seedPurpose", "==", "test")` on the group.
+         *
+         * A single-field equality is auto-indexed per COLLECTION, but a
+         * COLLECTION-GROUP query needs an explicit composite/group index that
+         * this project has never deployed, and `purge` must not require a
+         * Firebase deploy just to run (it is a read-then-delete script, not an
+         * infra change). Measured live: `3 FAILED_PRECONDITION: ... requires a
+         * COLLECTION_GROUP_ASC index`. `couponUsage` is small (single digits
+         * per store), so reading the whole group and filtering client-side
+         * costs nothing here — this is not a pattern to reuse on a large
+         * subcollection.
+         */
+        const snap = await db.collectionGroup(sub.name).get();
+        const docs = snap.docs.filter((d) => d.data()?.seedPurpose === "test");
+        if (docs.length > 0) plan.push({ colName, docs, isSub: true });
       } else {
         const snap = await db.collection(path).where("seedPurpose", "==", "test").get();
         if (snap.size > 0) plan.push({ colName, docs: snap.docs, isSub: false });
@@ -1286,19 +1480,40 @@ async function cmdPurge() {
         }
       }
     }
-    for (let i = 0; i < p.docs.length; i += 450) {
-      const chunk = p.docs.slice(i, i + 450);
-      const batch = db.batch();
-      for (const d of chunk) batch.delete(d.ref);
-      try {
-        await batch.commit();
-        stats.deleted += chunk.length;
-        if (VERBOSE) for (const d of chunk) console.log(`    - ${p.colName}/${d.id}`);
-      } catch (err) {
-        console.error(`✗ ${p.colName}: ${err.message}`);
-        stats.errors++;
-      }
+    /*
+     * 🛑 BulkWriter, never a manually-chunked `db.batch()`.
+     *
+     * A 450-document chunk stays under Firestore's 500-OPERATION limit but
+     * says nothing about the 10 MiB per-request PAYLOAD limit — and a rich
+     * document (a product's `searchTxt` array, `customFields`,
+     * `customSections`, `images[]`) can blow that well before 450 count.
+     * Measured live purging this exact `products` collection: `3
+     * INVALID_ARGUMENT: Transaction too big` partway through, which aborted
+     * the whole chunk's commit and silently left every doc in it undeleted —
+     * `stats.deleted` kept counting the chunk as done regardless, so the
+     * printed total was wrong by exactly the size of the failed chunk.
+     *
+     * `db.bulkWriter()` sizes and retries its own requests, so it is correct
+     * regardless of document size — CLAUDE.md documents the identical failure
+     * for a `categories` wipe (1,177 rows, ~100-entry `searchTxt` each) dying
+     * at a 400-doc batch for the same reason.
+     */
+    const writer = db.bulkWriter();
+    let chunkErrors = 0;
+    writer.onWriteError((err) => {
+      chunkErrors += 1;
+      console.error(`✗ ${p.colName}/${err.documentRef.id}: ${err.message}`);
+      // Retry up to the default limit; beyond that, give up on this one doc
+      // rather than retrying forever.
+      return err.failedAttempts < 3;
+    });
+    for (const d of p.docs) {
+      writer.delete(d.ref);
+      if (VERBOSE) console.log(`    - ${p.colName}/${d.id}`);
     }
+    await writer.close();
+    stats.deleted += p.docs.length - chunkErrors;
+    stats.errors += chunkErrors;
   }
 
   console.log(

package/scripts/verify-css-build.mjs

@@ -1,53 +1,134 @@
 /**
- * Post-build guard: verifies that critical responsive Tailwind classes are present
- * in the compiled dist/tailwind-utilities.css. Fails the build if any are missing,
- * catching cases where a stale or incomplete CSS bundle was published.
+ * verify-css-build — the BUILD-TIME guard on appkit's compiled stylesheets.
  *
- * Run via: node scripts/verify-css-build.mjs
- * Called automatically at the end of `npm run build`.
+ * Runs at the end of `npm run build`, before `npm publish` can ship the tarball.
+ *
+ * ── What this is for, and what it is NOT ───────────────────────────────────
+ * This answers "did the build produce a plausible, complete stylesheet?" — a
+ * question about the ARTEFACT. It deliberately does not try to answer "does
+ * every authored class resolve to a rule?", which is a question about the
+ * CODE: `scripts/audit-dead-css-classes.mjs` owns that, reads all three
+ * stylesheets, and runs in `npm run check` and the Stop hook.
+ *
+ * 🛑 It used to be a list of EIGHT hardcoded strings — `{md,lg}:{block,flex,
+ * hidden}` plus two breakpoints — chosen in 2026-08 for one specific nav bug.
+ * That is what it could see, and nothing added since was covered: not a hover,
+ * not a dropdown, not one of the ~980 hand-written `appkit-*` classes. Asked
+ * in 2026-10 whether the CSS was checked "or just a few", the honest answer
+ * was: just those eight.
+ *
+ * The replacement checks properties that hold for ANY correct build, so it
+ * cannot go stale as the class surface grows:
+ *
+ *   1. Each artefact EXISTS and is non-trivially large.
+ *   2. Each carries a floor of rules — catching a half-written `dist/`.
+ *   3. `styles.css` has no unresolved `@import` left in it.
+ *   4. The responsive machinery is present (media queries at the real
+ *      breakpoints), without naming individual classes.
+ *
+ * ── Why (2) exists: the half-written dist is a REAL failure here ───────────
+ * CLAUDE.md records a publish that died inside its own build step and left
+ * `dist/` with `client-entry.js` present and `tailwind-utilities.css` gone.
+ * A guard that only checked for a few class names in a file that existed
+ * would have passed a stylesheet missing most of itself. The floors are set
+ * well below current size so ordinary authoring never trips them; they exist
+ * to catch an order-of-magnitude loss, not a diff.
  */
-import { readFileSync } from "fs";
+import { readFileSync, statSync, existsSync } from "fs";
 import { resolve, dirname } from "path";
 import { fileURLToPath } from "url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const CSS_PATH = resolve(__dirname, "../dist/tailwind-utilities.css");
-
-const REQUIRED_CLASSES = [
-  // Responsive display utilities used by MainNavbar (NavbarLayout) and TitleBar
-  "lg\\:block",
-  "lg\\:flex",
-  "lg\\:hidden",
-  "md\\:block",
-  "md\\:flex",
-  "md\\:hidden",
-  // Responsive breakpoints must exist as @media rules.
-  // Tailwind v4 (2026-08-16 migration) uses rem-based default breakpoints —
-  // 64rem/48rem are the exact same viewport widths as v3's 1024px/768px at the
-  // browser default 16px root font-size (this project does not override
-  // html { font-size }), just expressed in the new unit.
-  "min-width:64rem",
-  "min-width:48rem",
+const DIST = resolve(__dirname, "../dist");
+
+/**
+ * Floors, not targets. Measured 2026-10-19 at 205 KB / 2,400 rules for the
+ * utilities and 495 KB / 7,900 rules for the components; these sit at roughly
+ * a third of that, so deleting a feature is fine and losing the file is not.
+ */
+const ARTEFACTS = [
+  {
+    file: "tailwind-utilities.css",
+    minBytes: 60_000,
+    minRules: 800,
+    what: "Tailwind utilities generated from appkit/src",
+  },
+  {
+    file: "styles.css",
+    minBytes: 150_000,
+    minRules: 2_500,
+    what: "hand-written appkit-* component CSS, flattened from *.style.css",
+  },
 ];
 
-let css;
-try {
-  css = readFileSync(CSS_PATH, "utf8");
-} catch {
-  console.error(`[verify-css-build] ERROR: Could not read ${CSS_PATH}`);
-  console.error("  Run 'npm run build' in appkit/ before publishing.");
-  process.exit(1);
+/**
+ * The breakpoints the layout primitives actually switch on. Expressed as
+ * MEDIA QUERIES rather than class names: a class list has to be maintained
+ * and silently narrows over time, while "the build emitted rules at these
+ * widths" stays true however the classes are spelled.
+ *
+ * rem, not px — Tailwind v4 emits `min-width: 64rem`, the same viewport width
+ * v3's `1024px` meant at the browser default root font-size (this project does
+ * not override `html { font-size }`).
+ */
+const BREAKPOINTS = ["40rem", "48rem", "64rem", "80rem"];
+
+const problems = [];
+
+for (const { file, minBytes, minRules, what } of ARTEFACTS) {
+  const p = resolve(DIST, file);
+  if (!existsSync(p)) {
+    problems.push(`${file} — MISSING (${what})`);
+    continue;
+  }
+  const bytes = statSync(p).size;
+  const css = readFileSync(p, "utf8");
+  // Rule count ≈ declaration blocks. Minified output is one line, so counting
+  // `{` is the only size-independent measure available.
+  const rules = (css.match(/\{/g) ?? []).length;
+
+  if (bytes < minBytes) {
+    problems.push(`${file} — ${bytes} bytes, below the ${minBytes} floor (${what})`);
+  }
+  if (rules < minRules) {
+    problems.push(`${file} — ${rules} rules, below the ${minRules} floor (${what})`);
+  }
+  // An unresolved @import means bundle-css.mjs did not run, or ran against an
+  // already-flattened file. Turbopack does not reliably resolve nested CSS
+  // imports, so one left here ships as missing styles.
+  if (file === "styles.css" && /@import\s+["']\./.test(css)) {
+    problems.push(`${file} — contains an unresolved relative @import; run bundle-css.mjs`);
+  }
 }
 
-const missing = REQUIRED_CLASSES.filter((cls) => !css.includes(cls));
+const utilitiesPath = resolve(DIST, "tailwind-utilities.css");
+if (existsSync(utilitiesPath)) {
+  const css = readFileSync(utilitiesPath, "utf8");
+  const missingBps = BREAKPOINTS.filter((bp) => !css.includes(`min-width:${bp}`) && !css.includes(`min-width: ${bp}`));
+  if (missingBps.length) {
+    problems.push(
+      `tailwind-utilities.css — no @media rule at ${missingBps.join(", ")}; ` +
+        `the responsive layer did not build`,
+    );
+  }
+}
 
-if (missing.length > 0) {
-  console.error("[verify-css-build] FAIL: Missing critical CSS classes in dist/tailwind-utilities.css:");
-  missing.forEach((cls) => console.error(`  - ${cls}`));
+if (problems.length) {
+  console.error("[verify-css-build] FAIL:");
+  for (const p of problems) console.error(`  - ${p}`);
+  console.error("");
+  console.error("  The build did not produce a complete stylesheet. Most likely causes:");
+  console.error("    - a concurrent `npm run build` wrote dist/ at the same time");
+  console.error("      (never run two builds at once — see CLAUDE.md's publish rules)");
+  console.error("    - copy-assets.mjs or bundle-css.mjs did not run");
+  console.error("    - the tailwindcss CLI failed without a non-zero exit");
   console.error("");
-  console.error("  This usually means the Tailwind build ran on stale source files.");
-  console.error("  Fix: rebuild appkit with 'npm run build' and re-verify.");
+  console.error("  For per-class completeness run `npm run audit dead-css-classes`,");
+  console.error("  which compares every authored class against the compiled CSS.");
   process.exit(1);
 }
 
-console.log(`[verify-css-build] OK: all ${REQUIRED_CLASSES.length} required classes/breakpoints present.`);
+console.log(
+  `[verify-css-build] OK — ${ARTEFACTS.length} artefact(s) present, above their size/rule floors, ` +
+    `responsive layer built at ${BREAKPOINTS.join(" / ")}.`,
+);

package/dist/_internal/server/features/search/actions.d.ts

@@ -1,7 +0,0 @@
-import { type ActionResult } from "@mohasinac/appkit/server";
-import type { SearchQuery } from "../../../../features/search/types";
-/**
- * Server action for client-initiated search (debounced as-you-type).
- * Bypasses React.cache() so each call returns fresh results.
- */
-export declare function searchAction(query: SearchQuery): Promise<ActionResult<unknown>>;

package/dist/_internal/server/features/search/actions.js

@@ -1,21 +0,0 @@
-"use server";
-import { wrapAction } from "@mohasinac/appkit/server";
-import { searchProducts } from "../../../../features/search/actions/search-actions.js";
-/**
- * Server action for client-initiated search (debounced as-you-type).
- * Bypasses React.cache() so each call returns fresh results.
- */
-export async function searchAction(query) {
-    return wrapAction(async () => {
-        return searchProducts(query).catch(() => ({
-            items: [],
-            q: query.q ?? "",
-            total: 0,
-            page: 1,
-            pageSize: query.pageSize ?? 20,
-            totalPages: 0,
-            hasMore: false,
-            backend: "in-memory",
-        }));
-    });
-}