@mohasinac/appkit 4.52.5 → 4.53.1

package/dist/_internal/shared/listing-types/spares/config.d.ts

@@ -0,0 +1,74 @@
+import { alwaysAvailable } from "../availability";
+export declare const LISTING_TYPE: "spares";
+export declare const capability: import("../capabilities").ListingTypeCapability;
+export declare const config: {
+    listingType: "spares";
+    slugPrefix: string;
+    cartLine: "single-product";
+    detailRoute: (idOrSlug: string) => string;
+    badge: {
+        label: string;
+        className: string;
+    };
+    priceLabel: string;
+    typeLabel: string;
+    showsStockQuantity: boolean;
+    tabSlug: string;
+    pluralLabel: string;
+    chipLabel: string;
+    browseRoute: string;
+    inGeneralCatalogue: boolean;
+    canJoinProductGroup: boolean;
+    iconKey: "spares";
+    hideDefault: "sold";
+    isAvailable: typeof alwaysAvailable;
+    unavailableClauses: readonly import("../availability").UnavailableClause[];
+    sortOptions: readonly [{
+        readonly value: string;
+        readonly label: "Newest First";
+    }, {
+        readonly value: string;
+        readonly label: "Oldest First";
+    }, {
+        readonly value: string;
+        readonly label: "Price: Low to High";
+    }, {
+        readonly value: string;
+        readonly label: "Price: High to Low";
+    }, {
+        readonly value: string;
+        readonly label: "Name: A–Z";
+    }, {
+        readonly value: string;
+        readonly label: "Name: Z–A";
+    }, {
+        readonly value: string;
+        readonly label: "Featured First";
+    }, {
+        readonly value: string;
+        readonly label: "Promoted First";
+    }, {
+        readonly value: string;
+        readonly label: "Recently Updated";
+    }];
+    publicSortOptions: readonly [{
+        readonly value: string;
+        readonly label: "Newest First";
+    }, {
+        readonly value: string;
+        readonly label: "Oldest First";
+    }, {
+        readonly value: string;
+        readonly label: "Price: Low to High";
+    }, {
+        readonly value: string;
+        readonly label: "Price: High to Low";
+    }, {
+        readonly value: string;
+        readonly label: "Name: A–Z";
+    }, {
+        readonly value: string;
+        readonly label: "Name: Z–A";
+    }];
+    extraFacetKeys: readonly string[];
+};

package/dist/_internal/shared/listing-types/spares/config.js

@@ -0,0 +1,60 @@
+import { LISTING_TYPE_CAPABILITIES } from "../capabilities.js";
+import { alwaysAvailable, STOCK_ONLY_UNAVAILABLE_CLAUSES, } from "../availability.js";
+import { ROUTES } from "../../../../next/routing/route-map.js";
+import { STANDARD_SORT_OPTIONS, STANDARD_PUBLIC_SORT_OPTIONS, } from "../../../../features/products/constants/sieve.js";
+export const LISTING_TYPE = "spares";
+export const capability = LISTING_TYPE_CAPABILITIES.spares;
+export const config = {
+    listingType: LISTING_TYPE,
+    /*
+     * Singular, matching `sticker-` rather than the plural type name.
+     *
+     * 🛑 Matched by `startsWith`, so this exact string must open every seeded id
+     * or `audit-seed-listing-type`'s R3 fails on every row — that audit calls the
+     * shipped `detectListingTypeFromSlug` rather than re-deriving the map, which
+     * is how it caught five `stickers-` ids against a registered `sticker-`.
+     */
+    slugPrefix: "spare-",
+    cartLine: "single-product",
+    detailRoute: (idOrSlug) => String(ROUTES.PUBLIC.PRODUCT_DETAIL(idOrSlug)),
+    badge: { label: "Spare Part", className: "bg-primary-700 text-white" },
+    priceLabel: "Price (₹)",
+    typeLabel: "Spares",
+    showsStockQuantity: true,
+    tabSlug: "spares",
+    pluralLabel: "Spares",
+    chipLabel: "Spares",
+    browseRoute: String(ROUTES.PUBLIC.SPARES),
+    /*
+     * 🛑 `false`, and it obliges the nav entry that lands in the same change.
+     *
+     * The rule for this flag is nav reachability, not taste: a type kept out of
+     * the general catalogue must own a page that `MAIN_NAV_ITEMS` links, or it is
+     * reachable from nowhere (Root Cause #61). `/spares` is that page.
+     *
+     * The reason to keep it out is the catalogue itself. A seller who strips one
+     * Beyblade lists eight parts, so a few disassembled items would outnumber
+     * every complete listing on `/products` — and a buyer looking for a loose
+     * attack ring wants a page where everything is a loose part, not one where
+     * they are scattered among bundles and sealed boxes.
+     */
+    inGeneralCatalogue: false,
+    /*
+     * A sheet-plus-parts group is the shape this exists for on the sticker side,
+     * and the same shape sells a stripped bey: the whole item as the parent, each
+     * salvaged part as a child, buyer takes any mix.
+     */
+    canJoinProductGroup: true,
+    iconKey: "spares",
+    hideDefault: "sold",
+    /*
+     * A spare runs out rather than ending — there is no time dimension at all, so
+     * the shared stock-only rules are the whole story. Usually quantity 1: it is
+     * one physical object the seller happens to have.
+     */
+    isAvailable: alwaysAvailable,
+    unavailableClauses: STOCK_ONLY_UNAVAILABLE_CLAUSES,
+    sortOptions: STANDARD_SORT_OPTIONS,
+    publicSortOptions: STANDARD_PUBLIC_SORT_OPTIONS,
+    extraFacetKeys: [],
+};

package/dist/_internal/shared/listing-types/spares/ctas.d.ts

@@ -0,0 +1 @@
+export declare const ctas: readonly string[];

package/dist/_internal/shared/listing-types/spares/ctas.js

@@ -0,0 +1,4 @@
+// Spares reuse the standard "Add to Cart" / "Buy Now" CTAs — plus the shared
+// Make-an-Offer control, which is driven by `capability.canMakeOffer` rather
+// than by anything here (mirrors the art/stickers/live placeholders).
+export const ctas = [];

package/dist/_internal/shared/listing-types/spares/og.js

@@ -0,0 +1 @@
+export {};

package/dist/_internal/shared/listing-types/spares/schema.d.ts

@@ -0,0 +1,2 @@
+import type { ProductDocument } from "../../../../features/products/schemas/firestore";
+export declare function isSparesProduct(doc: ProductDocument): boolean;

package/dist/_internal/shared/listing-types/spares/schema.js

@@ -0,0 +1,3 @@
+export function isSparesProduct(doc) {
+    return doc.listingType === "spares";
+}

package/dist/_internal/shared/listing-types/spares/seed-factory.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/_internal/shared/listing-types/spares/seed-factory.js

@@ -0,0 +1 @@
+export {};

package/dist/_internal/shared/listing-types/standard/config.d.ts

@@ -18,6 +18,8 @@ export declare const config: {
     chipLabel: string;
     browseRoute: string;
     inGeneralCatalogue: boolean;
+    canJoinProductGroup: boolean;
+    iconKey: "order";
     hideDefault: "sold";
     isAvailable: typeof alwaysAvailable;
     unavailableClauses: readonly import("../availability").UnavailableClause[];

package/dist/_internal/shared/listing-types/standard/config.js

@@ -19,6 +19,9 @@ export const config = {
     browseRoute: String(ROUTES.PUBLIC.PRODUCTS),
     // The general catalogue IS this type's page.
     inGeneralCatalogue: true,
+    // the ordinary case — a complete item whose parts can be sold beside it
+    canJoinProductGroup: true,
+    iconKey: "order",
     hideDefault: "sold",
     // Runs out rather than ending — no time dimension, so the shared
     // stock-only rules are the whole story for this type.

package/dist/_internal/shared/listing-types/stickers/config.d.ts

@@ -18,6 +18,8 @@ export declare const config: {
     chipLabel: string;
     browseRoute: string;
     inGeneralCatalogue: boolean;
+    canJoinProductGroup: boolean;
+    iconKey: "stickers";
     hideDefault: "sold";
     isAvailable: typeof alwaysAvailable;
     unavailableClauses: readonly import("../availability").UnavailableClause[];

package/dist/_internal/shared/listing-types/stickers/config.js

@@ -22,6 +22,9 @@ export const config = {
     browseRoute: String(ROUTES.PUBLIC.ART),
     // /art ("Art & Stickers") is in MAIN_NAV_ITEMS and spans art + stickers.
     inGeneralCatalogue: false,
+    // THE case this exists for: a sheet plus its individual cut-out stickers
+    canJoinProductGroup: true,
+    iconKey: "stickers",
     hideDefault: "sold",
     // Runs out rather than ending — no time dimension, so the shared
     // stock-only rules are the whole story for this type.

package/dist/_internal/shared/media/limits.d.ts

@@ -13,8 +13,18 @@ export declare const MAX_IMAGE_BYTES: number;
 export declare const MAX_PDF_BYTES: number;
 export declare const MAX_VIDEO_BYTES: number;
 export type MediaKind = "image" | "video" | "pdf";
-/** Gallery images per listing. */
-export declare const PRODUCT_MAX_IMAGES = 10;
+/**
+ * Gallery images per listing.
+ *
+ * 24, raised from 10 on 2026-10-19 against measured competitor data
+ * (docs/research/competitor-crawl-2026-10/images.md): sampled maxima are
+ * raikagesbeybladestore 21, hobsoncollectibles 20, toycollectorsindia 31.
+ * 24 covers a pre-owned lot with headroom; 31 is a single outlier and sizing
+ * for it would be sizing for one listing.
+ *
+ * The market MEDIAN is 1-4, so this is a ceiling, not a target.
+ */
+export declare const PRODUCT_MAX_IMAGES = 24;
 /** Videos per listing. Bounded by `ProductDocument.video` being singular. */
 export declare const PRODUCT_MAX_VIDEOS = 1;
 /**

package/dist/_internal/shared/media/limits.js

@@ -27,8 +27,18 @@ export const MAX_VIDEO_BYTES = 50 * MEGABYTE;
 // The video cap is 1 because `ProductDocument.video` is a single field, not an
 // array — raising it is a schema change, not a constant change.
 // ---------------------------------------------------------------------------
-/** Gallery images per listing. */
-export const PRODUCT_MAX_IMAGES = 10;
+/**
+ * Gallery images per listing.
+ *
+ * 24, raised from 10 on 2026-10-19 against measured competitor data
+ * (docs/research/competitor-crawl-2026-10/images.md): sampled maxima are
+ * raikagesbeybladestore 21, hobsoncollectibles 20, toycollectorsindia 31.
+ * 24 covers a pre-owned lot with headroom; 31 is a single outlier and sizing
+ * for it would be sizing for one listing.
+ *
+ * The market MEDIAN is 1-4, so this is a ceiling, not a target.
+ */
+export const PRODUCT_MAX_IMAGES = 24;
 /** Videos per listing. Bounded by `ProductDocument.video` being singular. */
 export const PRODUCT_MAX_VIDEOS = 1;
 /**

package/dist/_internal/shared/search/artifact-url.d.ts

@@ -0,0 +1,35 @@
+/** `search-index/v{n}.json` — the version IS the cache key. */
+export declare const SEARCH_INDEX_PREFIX = "search-index";
+/**
+ * The manifest mirror's object name.
+ *
+ * 🛑 A MIRROR of `searchIndex/manifest` in Firestore, never the source of
+ * truth. The build writes Firestore first and this second, because the
+ * Firestore document is what the next build reads to decide its mode — a
+ * mirror that disagrees costs a stale client for 60 seconds, whereas a
+ * manifest the builder cannot trust costs a full rebuild.
+ *
+ * It exists so the client bootstrap is two plain `fetch`es and no Firebase
+ * SDK: pulling in the client SDK to read one small document would cost more
+ * bytes than the index it is pointing at.
+ */
+export declare const SEARCH_MANIFEST_OBJECT = "search-index/manifest.json";
+export declare function searchIndexObjectPath(version: number): string;
+/** Public download URL for any object in the app's Storage bucket. */
+export declare function firebaseDownloadUrl(bucket: string, objectPath: string): string;
+export declare function searchManifestUrl(bucket: string): string;
+export declare function searchArtifactUrl(bucket: string, version: number): string;
+/**
+ * What the client needs out of the manifest, and nothing more.
+ *
+ * Deliberately NOT the server's `SearchIndexManifest`: that one carries
+ * `dirty`, `lastFullAt` and `perType`, which are build bookkeeping. A client
+ * type that structurally accepts them would invite someone to render build
+ * state in the UI, and then the mirror could never drop a field.
+ */
+export interface SearchIndexManifestPublic {
+    readonly schema: number;
+    readonly version: number;
+    readonly builtAt: string;
+    readonly recordCount: number;
+}

package/dist/_internal/shared/search/artifact-url.js

@@ -0,0 +1,119 @@
+/*
+ * WHY: The browser and the builder must agree on where the search artifact
+ *      lives, and the obvious URL for a public Storage object is the wrong
+ *      one.
+ * WHAT: The two public URLs — the manifest and a versioned artifact — derived
+ *       from the bucket name alone, with no Firebase SDK on either side.
+ *
+ * ## 🛑 The plain `GCS_HOST` URL does NOT work. Measured.
+ *
+ * It is the first one anyone reaches for and it returns **403**:
+ *
+ *   GET https://{GCS_HOST}/<bucket>/search-index/v3.json              -> 403
+ *   GET https://{FIREBASE_STORAGE_HOST}/v0/b/<bucket>/o/
+ *       search-index%2Fv3.json?alt=media                              -> 200
+ *
+ * (Both hosts are named by their constants rather than spelled out, because
+ * `audit-firestore-storage-urls` is strict-zero on the literals and does not
+ * strip comments. That is the correct constraint, not a nuisance: the hosts
+ * have exactly one declaration, in `utils/media-url.ts`, and this file
+ * imports it rather than becoming a second.)
+ *
+ * `storage.rules`'s `allow read: if true` is a **Firebase Storage** rule. It
+ * is evaluated by the Firebase download endpoint and has no bearing on the
+ * plain GCS JSON/XML API, which answers to IAM and object ACLs — neither of
+ * which grants `allUsers`. So the rule that makes this artifact public only
+ * applies on one of the two hosts.
+ *
+ * ## 🛑 Why this is NOT a `/media/<slug>` reference
+ *
+ * That audit's stated rule is "every MEDIA reference flows through
+ * `/media/<slug>`", and this is not media. Two reasons it must not be routed
+ * that way:
+ *
+ *  1. the proxy resolves a slug through a `mediaAssets/{slug}` Firestore read
+ *     and then watermarks images — neither of which means anything for a JSON
+ *     data file;
+ *  2. it would put a Vercel function in the path of a 405 KB download for
+ *     every cold visitor. Root Cause #104 is precisely that bill — 52.52 GB
+ *     of Fast Origin Transfer against a 10 GB allowance — and the whole point
+ *     of an immutable version-addressed object is that nothing of ours serves
+ *     it twice.
+ *
+ * Verified on the live bucket 2026-10-19, on the second host:
+ *
+ *   Cache-Control: public, max-age=31536000, immutable   (passed through)
+ *   Access-Control-Allow-Origin: https://www.letitrip.in
+ *   Vary: Origin
+ *   Content-Length: 418830
+ *
+ * So the response is cacheable, CORS-readable and non-opaque — which is the
+ * whole precondition for the service worker rule and for being able to tell a
+ * 404 apart from an empty index.
+ *
+ * ## 🛑 The tracked CORS config had drifted from the live bucket
+ *
+ * Found while verifying the above. `appkit/firebase/base/storage-cors.json`
+ * is the tracked source of truth and `npm run storage:cors` applies it — but
+ * the live bucket had an origin (`letitrip-in-app.vercel.app`), a method
+ * (`POST`) and two response headers (`x-goog-resumable`,
+ * `x-goog-content-length-range`) the file did not, all of which the
+ * resumable-upload path uses. So running the script to "sync" it would have
+ * NARROWED the live config and broken uploads, in a repo where that command
+ * reads like the safe, idempotent thing to do.
+ *
+ * The file is now a strict SUPERSET of what was measured live, so applying it
+ * can only widen. The config was NOT re-applied as part of this work: GET
+ * from the app origins already worked, and re-applying is an upload-path
+ * change that has no business riding along with a search feature.
+ *
+ * ## The path must be percent-encoded WHOLE
+ *
+ * `/v0/b/<bucket>/o/<object>` takes the object name as ONE path segment, so
+ * the `/` inside `search-index/v3.json` has to become `%2F`. `encodeURIComponent`
+ * does exactly that; `encodeURI` does not, and would 404 in a way that reads
+ * like a missing artifact rather than a malformed URL.
+ *
+ * @tag domain:search
+ * @tag layer:shared
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:useSearchIndex,artifact-store,verify-search-serving
+ * @tag sideEffects:none
+ */
+/*
+ * The host comes from its ONE declaration. `utils/media-url.ts` is named in
+ * `audit-firestore-storage-urls`'s allowlist as the sole place these strings
+ * may appear, with every other module importing from it — so importing is
+ * the sanctioned mechanism here, not an exemption carved out for search.
+ */
+import { FIREBASE_STORAGE_HOST } from "../../../utils/media-url.js";
+/** `search-index/v{n}.json` — the version IS the cache key. */
+export const SEARCH_INDEX_PREFIX = "search-index";
+/**
+ * The manifest mirror's object name.
+ *
+ * 🛑 A MIRROR of `searchIndex/manifest` in Firestore, never the source of
+ * truth. The build writes Firestore first and this second, because the
+ * Firestore document is what the next build reads to decide its mode — a
+ * mirror that disagrees costs a stale client for 60 seconds, whereas a
+ * manifest the builder cannot trust costs a full rebuild.
+ *
+ * It exists so the client bootstrap is two plain `fetch`es and no Firebase
+ * SDK: pulling in the client SDK to read one small document would cost more
+ * bytes than the index it is pointing at.
+ */
+export const SEARCH_MANIFEST_OBJECT = `${SEARCH_INDEX_PREFIX}/manifest.json`;
+export function searchIndexObjectPath(version) {
+    return `${SEARCH_INDEX_PREFIX}/v${version}.json`;
+}
+/** Public download URL for any object in the app's Storage bucket. */
+export function firebaseDownloadUrl(bucket, objectPath) {
+    return `https://${FIREBASE_STORAGE_HOST}/v0/b/${bucket}/o/${encodeURIComponent(objectPath)}?alt=media`;
+}
+export function searchManifestUrl(bucket) {
+    return firebaseDownloadUrl(bucket, SEARCH_MANIFEST_OBJECT);
+}
+export function searchArtifactUrl(bucket, version) {
+    return firebaseDownloadUrl(bucket, searchIndexObjectPath(version));
+}

package/dist/_internal/shared/search/index-record.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Bumped when the tuple or the envelope changes shape.
+ *
+ * 🛑 The client REFUSES an artifact whose schema it does not recognise and
+ * falls back to the server path, rather than rendering a half-understood one.
+ * That is why this is in the envelope and not implied by the URL.
+ */
+export declare const SEARCH_INDEX_SCHEMA_VERSION = 1;
+/**
+ * The incremental build's watermark field.
+ *
+ * 🛑 ONE shared constant for the same reason `SEARCH_TXT_FIELD` is one:
+ * `updatedAt` is a CROSS-COLLECTION convention declared on `BaseDocument`, and
+ * `field-names.ts` repeats it in four separate per-feature blocks. A builder
+ * that queries THIRTEEN collections cannot honestly borrow any single
+ * feature's copy — `PRODUCT_FIELDS.UPDATED_AT` naming the field on a `faqs`
+ * query is a true string and a false statement.
+ */
+export declare const INDEX_UPDATED_AT_FIELD = "updatedAt";
+/** One searchable kind. The artifact carries the table so the client needs no map. */
+export interface SearchIndexType {
+    /** Stable key — `product`, `category`, `part`, … Also the i18n label key. */
+    readonly key: string;
+    /** `"/products/{s}"` — exactly one substitution, `{s}`, the record's slug. */
+    readonly hrefTemplate: string;
+    /** The indexable browse page, for the group's "see all" footer. */
+    readonly moreHref: string;
+    /** Type-level ranking nudge. A product outranks a review for the same score. */
+    readonly weight: number;
+}
+/** Tuple positions, named once so no call site indexes by magic number. */
+export declare const REC_TYPE = 0;
+export declare const REC_TITLE = 1;
+export declare const REC_DETAIL = 2;
+export declare const REC_SLUG = 3;
+export declare const REC_FACETS = 4;
+/**
+ * `[typeIdx, title, detail, slug, facets?]`
+ *
+ * `facets` is a compact pipe-joined string (`"lt:auction|br:takara-tomy"`) and
+ * is absent rather than empty when a record has none — an omitted trailing
+ * element costs two bytes, `""` costs four, times 3,730.
+ */
+export type SearchIndexRecord = readonly [
+    number,
+    string,
+    string,
+    string,
+    string?
+];
+export interface SearchIndexArtifact {
+    readonly schema: number;
+    /** Monotonic build number. The artifact is addressed by it and immutable. */
+    readonly version: number;
+    readonly builtAt: string;
+    readonly types: readonly SearchIndexType[];
+    readonly r: readonly SearchIndexRecord[];
+}
+/** Resolve a record's destination from the type table. */
+export declare function hrefFor(artifact: Pick<SearchIndexArtifact, "types">, rec: SearchIndexRecord): string;
+/**
+ * Parse the compact facet string into pairs.
+ *
+ * Returns an empty array for an absent or malformed field rather than
+ * throwing: a facet is a refinement, and a record whose facets cannot be read
+ * is still a record somebody should be able to find.
+ */
+export declare function facetsOf(rec: SearchIndexRecord): ReadonlyArray<readonly [string, string]>;

package/dist/_internal/shared/search/index-record.js

@@ -0,0 +1,96 @@
+/*
+ * WHY: The public search index is one artifact fetched once per visitor and
+ *      searched in the browser, so its shape is a wire format — every field
+ *      costs bytes on every download, and every field that can be DERIVED
+ *      instead of stored should be.
+ * WHAT: The record tuple, the type table, and the artifact envelope. Shared by
+ *       the builder (server) and the matcher (browser) so the two cannot drift.
+ *
+ * ## 🛑 Why a tuple and not an object
+ *
+ * 3,730 records. An object repeats its keys on every row; a tuple does not.
+ * Measured on the real corpus: 373 KB raw / 63 KB gzip / 46 KB brotli as
+ * tuples. The readability cost is paid once, here, by naming the positions.
+ *
+ * ## What is deliberately ABSENT, and why each
+ *
+ *   href        derivable from `types[typeIdx].hrefTemplate`
+ *   normalised  derived once at load with the SAME `normalizeSearchText` the
+ *   title       write path uses — storing it would be a second copy of a
+ *               string we already ship
+ *   tokens      derived by calling the SAME `aliasVariantsForName` /
+ *               `partAliasTokens` that are already in the bundle. Shipping
+ *               them would duplicate a corpus the client already has
+ *   label       🛑 NOT on the type table. A human-readable group heading baked
+ *               into the artifact is untranslatable, and this app is
+ *               `[locale]`-routed with every other UI string going through the
+ *               label system. The client maps `key` -> label at render time
+ *   price       § Guest price gating is a CLIENT gate; it reaches the rendered
+ *               DOM and nothing else. This artifact is unauthenticated and
+ *               immutable-cached, so no gate can reach it — an amount here is
+ *               published to everyone, permanently, for that version
+ *   PII         same argument, one step worse. Includes blind-index digests: a
+ *               deterministic per-person identifier is cross-referenceable
+ *               even unbroken
+ *
+ * The last two are enforced, not merely documented — see
+ * scripts/audit-search-index-artifact.mjs.
+ *
+ * @tag domain:search
+ * @tag layer:shared
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:index-build,match,verify-search-local
+ * @tag sideEffects:none
+ */
+/**
+ * Bumped when the tuple or the envelope changes shape.
+ *
+ * 🛑 The client REFUSES an artifact whose schema it does not recognise and
+ * falls back to the server path, rather than rendering a half-understood one.
+ * That is why this is in the envelope and not implied by the URL.
+ */
+export const SEARCH_INDEX_SCHEMA_VERSION = 1;
+/**
+ * The incremental build's watermark field.
+ *
+ * 🛑 ONE shared constant for the same reason `SEARCH_TXT_FIELD` is one:
+ * `updatedAt` is a CROSS-COLLECTION convention declared on `BaseDocument`, and
+ * `field-names.ts` repeats it in four separate per-feature blocks. A builder
+ * that queries THIRTEEN collections cannot honestly borrow any single
+ * feature's copy — `PRODUCT_FIELDS.UPDATED_AT` naming the field on a `faqs`
+ * query is a true string and a false statement.
+ */
+export const INDEX_UPDATED_AT_FIELD = "updatedAt";
+/** Tuple positions, named once so no call site indexes by magic number. */
+export const REC_TYPE = 0;
+export const REC_TITLE = 1;
+export const REC_DETAIL = 2;
+export const REC_SLUG = 3;
+export const REC_FACETS = 4;
+/** Resolve a record's destination from the type table. */
+export function hrefFor(artifact, rec) {
+    const type = artifact.types[rec[REC_TYPE]];
+    if (!type)
+        return "/";
+    return type.hrefTemplate.replace("{s}", rec[REC_SLUG]);
+}
+/**
+ * Parse the compact facet string into pairs.
+ *
+ * Returns an empty array for an absent or malformed field rather than
+ * throwing: a facet is a refinement, and a record whose facets cannot be read
+ * is still a record somebody should be able to find.
+ */
+export function facetsOf(rec) {
+    const raw = rec[REC_FACETS];
+    if (!raw)
+        return [];
+    const out = [];
+    for (const part of raw.split("|")) {
+        const i = part.indexOf(":");
+        if (i > 0)
+            out.push([part.slice(0, i), part.slice(i + 1)]);
+    }
+    return out;
+}

package/dist/_internal/shared/search/match.d.ts

@@ -0,0 +1,76 @@
+import { type SearchIndexArtifact, type SearchIndexRecord } from "./index-record";
+export interface ResolvedEntity {
+    /** Index into `artifact.types`. */
+    readonly typeIdx: number;
+    readonly typeKey: string;
+    readonly title: string;
+    readonly detail: string;
+    readonly href: string;
+    readonly score: number;
+    /**
+     * The record's raw compact facet string (`"lt:auction|br:takara-tomy"`), or
+     * `""`. Carried on the hit so a facet rail can count what the CURRENT result
+     * set contains without going back to the artifact and re-finding each row.
+     *
+     * 🛑 Raw rather than parsed, on purpose. Parsing is `facetsOf(rec)` and it
+     * allocates an array per record; a rail counts over every hit on every
+     * keystroke, and most queries never render one. The consumer parses the
+     * handful it actually needs.
+     */
+    readonly facets: string;
+}
+export interface ResolveOptions {
+    readonly limit?: number;
+    /** Restrict to these type keys. Empty/absent means every type. */
+    readonly types?: readonly string[];
+    /** Require every one of these `k:v` facet pairs. */
+    readonly facets?: readonly string[];
+}
+/** One record's searchable text, prepared once at load. */
+interface Prepared {
+    readonly rec: SearchIndexRecord;
+    readonly titleWords: readonly string[];
+    readonly titleFlat: string;
+    readonly detailWords: readonly string[];
+    readonly detailFlat: string;
+    /** Alias + misspelling forms of the TITLE. See `prepareIndex`. */
+    readonly aliasWords: readonly string[];
+    readonly aliasFlat: string;
+}
+/**
+ * Prepare an artifact for searching.
+ *
+ * 🛑 Call this ONCE per artifact, not per query. It normalises every title and
+ * detail up front — ~3,700 × 2 `normalizeSearchText` calls, a few milliseconds
+ * — so that the per-keystroke path does no allocation beyond the query's own
+ * terms. Doing it inside `search` would move that cost onto every keystroke,
+ * which is the one thing this design exists to avoid.
+ */
+export declare function prepareIndex(artifact: SearchIndexArtifact): readonly Prepared[];
+/**
+ * Search a prepared artifact.
+ *
+ * Returns a flat, score-ordered list. Grouping by type is the caller's job —
+ * the dropdown and the results page group differently, and a tool wants
+ * neither.
+ */
+export declare function searchIndex(artifact: SearchIndexArtifact, prepared: readonly Prepared[], query: string, opts?: ResolveOptions): readonly ResolvedEntity[];
+/**
+ * The named primitive the tools call.
+ *
+ * 🛑 `types` is a parameter from day one BECAUSE the tools exist. `/parts`
+ * wants parts, the price index wants category leaves, the authenticity
+ * typeahead wants canonical models — three consumers, three subsets. Adding
+ * the filter later would mean changing every call site that had already been
+ * written without it.
+ *
+ * 🛑 It must NOT be wired into `/tools/authenticity`'s VERDICT path. That
+ * engine's fuzzy matching is evidence — a near-miss fires a trademark-evasion
+ * warning — and this matcher's alias corpus is built from a counterfeit
+ * seller's own spellings. Feeding one into the other would silence the warning
+ * by construction. The typeahead may propose a canonical entity; the engine
+ * must still analyse what the user actually typed. Enforced by
+ * audit-entity-resolver-consumers R2.
+ */
+export declare function resolveEntity(artifact: SearchIndexArtifact, prepared: readonly Prepared[], query: string, opts?: ResolveOptions): readonly ResolvedEntity[];
+export type { Prepared as PreparedIndex };