@mohasinac/appkit 4.52.5 → 4.53.0

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,65 @@
+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;
+}
+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 };

package/dist/_internal/shared/search/match.js

@@ -0,0 +1,263 @@
+/*
+ * WHY: Searching a 3,730-record artifact in the browser, at zero Firestore
+ *      reads per keystroke. The action-index route already states the
+ *      doctrine this follows: "One request per session per portal, never per
+ *      keystroke… a typeahead has to answer in under 16 ms, which a network
+ *      hop cannot."
+ * WHAT: A pure, isomorphic matcher plus `resolveEntity`, the named primitive
+ *       the /tools surfaces call.
+ *
+ * ## 🛑 ONE normaliser, and it is imported, not reimplemented
+ *
+ * `normalizeSearchText` is the same function the write path and the Firestore
+ * path use. `audit-search-parity`'s R2 exists because a second tokeniser
+ * writes tokens the query side cannot match — "and re-running the backfill
+ * does NOT fix it". A library would have brought a third; this file must not
+ * grow a local lowercase/NFD pipeline. Enforced by that audit.
+ *
+ * ## Why hand-rolled rather than MiniSearch
+ *
+ * Three reasons, in order of weight:
+ *
+ *  1. the normaliser argument above;
+ *  2. typo tolerance is already solved at WRITE time with evidence —
+ *     `alias-variants` derives its suffix swaps from a crawl of a counterfeit
+ *     seller's 1,277 titles, which is better grounded than generic edit
+ *     distance and costs nothing at query time;
+ *  3. ~3,700 records is below where an inverted index earns its complexity. A
+ *     linear scan is a few thousand cheap iterations.
+ *
+ * 🛑 (3) is a claim with a number attached, and the number is checked —
+ * `scripts/verify-search-local.mjs` times it and prints the result. If that
+ * ever stops being true, this comment is the thing to come back and delete.
+ *
+ * ## 🛑 It is NOT BM25 and must not be described as BM25
+ *
+ * BM25's two moving parts are IDF and length normalisation. Titles here
+ * average 20 characters, so length normalisation is degenerate; IDF over one
+ * domain mostly re-derives "beyblade is common", which `weight` already
+ * encodes. Calling an ordered weight sum "BM25-ish" would be decoration
+ * (Root Cause #92). It is a weighted match score, the weights are below, and
+ * they are tuned against the verify script.
+ *
+ * ## What this has that the Firestore path structurally cannot
+ *
+ * SUBSTRING. `search-txt.ts` states the limit outright: "Word-prefix, not
+ * mid-word. 'ariza' will not match 'charizard'." A linear scan gets mid-word
+ * for free, which is why Tier 1 is better at its job than Tier 2, not merely
+ * cheaper.
+ *
+ * @tag domain:search
+ * @tag layer:shared
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:useSiteSearch,/parts,/tools/price-index,verify-search-local
+ * @tag sideEffects:none
+ */
+import { normalizeSearchText, parseSearchTxtQuery } from "../../../utils/search-txt.js";
+import { aliasVariantsForName } from "./alias-variants.js";
+import { partAliasTokens } from "./part-aliases.js";
+import { facetsOf, hrefFor, REC_DETAIL, REC_TITLE, REC_TYPE, } from "./index-record.js";
+/** Field weights. Title dominates; a detail match is corroboration. */
+const W_TITLE = 3;
+const W_DETAIL = 1;
+/** Match-quality weights, highest first. */
+const S_EXACT = 100;
+const S_PREFIX = 60;
+const S_SUBSTRING = 30;
+const S_ALIAS = 15;
+/** Default cap. A dropdown shows ~6 per group; a page shows more. */
+const DEFAULT_LIMIT = 50;
+/**
+ * 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 function prepareIndex(artifact) {
+    return artifact.r.map((rec) => {
+        const title = rec[REC_TITLE] ?? "";
+        const titleFlat = normalizeSearchText(title);
+        const detailFlat = normalizeSearchText(rec[REC_DETAIL] ?? "");
+        /*
+         * 🛑 The alias corpus is expanded against the DOCUMENT, not the query, and
+         * getting this backwards is a real bug I shipped into the first draft.
+         *
+         * `aliasVariantsForName` is DIRECTIONAL: `doubledLetterVariants` collapses
+         * `dragoon -> dragon`, it does not expand `dragon -> dragoon`. The
+         * Firestore path works because `buildProductSearchTxt` runs it over the
+         * TITLE at write time, so the document carries "dragon" as a token.
+         * Expanding the query instead produces nothing for that rule, and the
+         * verify script caught it: searching "dragon" found no "Dragoon Storm".
+         *
+         * So the client does at LOAD what the server does at WRITE — same
+         * function, same direction, same result. It also keeps the variants out
+         * of the artifact, which is why `index-record.ts` does not carry them.
+         *
+         * `partAliasTokens` is symmetric (a code <-> name table), so it would have
+         * worked either way; it runs here too so there is one rule, not two.
+         */
+        const aliasSet = new Set();
+        for (const v of aliasVariantsForName(title))
+            aliasSet.add(normalizeSearchText(v));
+        for (const v of partAliasTokens(`${title} ${rec[REC_DETAIL] ?? ""}`)) {
+            aliasSet.add(normalizeSearchText(v));
+        }
+        aliasSet.delete(titleFlat); // a variant identical to the title adds nothing
+        const aliasFlat = [...aliasSet].filter(Boolean).join(" ");
+        return {
+            rec,
+            titleFlat,
+            detailFlat,
+            aliasFlat,
+            titleWords: titleFlat ? titleFlat.split(" ") : [],
+            detailWords: detailFlat ? detailFlat.split(" ") : [],
+            aliasWords: aliasFlat ? aliasFlat.split(" ") : [],
+        };
+    });
+}
+/** Best match quality for one term against one field. 0 means no match. */
+function fieldScore(term, words, flat) {
+    if (!flat)
+        return 0;
+    for (const w of words)
+        if (w === term)
+            return S_EXACT;
+    for (const w of words)
+        if (w.startsWith(term))
+            return S_PREFIX;
+    // Mid-word. The capability the token index cannot have.
+    if (flat.includes(term))
+        return S_SUBSTRING;
+    return 0;
+}
+function recordScore(p, terms, typeWeight) {
+    let total = 0;
+    for (const term of terms) {
+        /*
+         * An alias match is real but WEAKER than a direct one: `S_ALIAS` is the
+         * ceiling for that field, so "Dragoon Storm" still outranks a record that
+         * only matched through a generated misspelling.
+         */
+        const aliasHit = fieldScore(term, p.aliasWords, p.aliasFlat) > 0 ? S_ALIAS : 0;
+        const best = Math.max(fieldScore(term, p.titleWords, p.titleFlat) * W_TITLE, fieldScore(term, p.detailWords, p.detailFlat) * W_DETAIL, aliasHit);
+        // AND semantics: a record missing any term is out, regardless of how well
+        // it matched the others. "red dranzer" returning everything with "dranzer"
+        // is the exact complaint that made search feel broken.
+        if (best === 0)
+            return 0;
+        total += best;
+    }
+    return total * typeWeight;
+}
+function facetsSatisfied(rec, required) {
+    if (required.length === 0)
+        return true;
+    const have = new Set(facetsOf(rec).map(([k, v]) => `${k}:${v}`));
+    return required.every((f) => have.has(f));
+}
+/**
+ * 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 function searchIndex(artifact, prepared, query, opts = {}) {
+    const terms = parseSearchTxtQuery(query);
+    /*
+     * 🛑 A query that normalises to nothing returns NOTHING, never everything.
+     * "!!!" and "—" have no terms, and treating that as "no filter" is how a
+     * punctuation search returns the whole catalogue AS SEARCH RESULTS — the
+     * bug A2 fixed on /api/products, and the one `plan.empty` exists for.
+     */
+    if (terms.length === 0)
+        return [];
+    const limit = opts.limit ?? DEFAULT_LIMIT;
+    const wantTypes = new Set(opts.types ?? []);
+    const facets = opts.facets ?? [];
+    const collect = (useTerms, aliasPass) => {
+        const hits = [];
+        for (const p of prepared) {
+            const type = artifact.types[p.rec[REC_TYPE]];
+            if (!type)
+                continue;
+            if (wantTypes.size > 0 && !wantTypes.has(type.key))
+                continue;
+            if (!facetsSatisfied(p.rec, facets))
+                continue;
+            const score = recordScore(p, useTerms, type.weight);
+            if (score === 0)
+                continue;
+            hits.push({
+                typeIdx: p.rec[REC_TYPE],
+                typeKey: type.key,
+                title: p.rec[REC_TITLE],
+                detail: p.rec[REC_DETAIL],
+                href: hrefFor(artifact, p.rec),
+                // An alias hit is a weaker signal than a direct one and must not
+                // outrank it when both are present in a later, wider query.
+                score: aliasPass ? score - S_ALIAS : score,
+            });
+        }
+        return hits;
+    };
+    /*
+     * ONE pass. The alias forms live on the prepared record (see
+     * `prepareIndex`), so there is nothing to retry with — an earlier draft had
+     * a second query-expansion pass here and it was both redundant and
+     * directionally wrong.
+     */
+    const hits = collect(terms, false);
+    hits.sort((a, b) => b.score - a.score || a.title.localeCompare(b.title));
+    /*
+     * 🛑 Dedupe by DESTINATION, not by key. Two types can legitimately resolve
+     * to the same page: `model` (a composition) and `category` (the model leaf)
+     * both render `/categories/{s}`, because a composition has no page of its
+     * own. Found running the first real build — 222 model records sit on top of
+     * 1,144 categories, so a bey name could return two rows that go to the same
+     * place, which reads as a duplicate-results bug rather than as two ways of
+     * finding one thing.
+     *
+     * Keeping the HIGHER-scoring one is what preserves the value of both: the
+     * composition's name is often the longer, more specific form ("Aero Knight
+     * MS (Aero Knight Metal Sky)" against the category's "Aero Knight MS"), so
+     * whichever actually matched the query is the one worth showing.
+     *
+     * After the sort, so "first seen" is "best scoring".
+     */
+    const seen = new Set();
+    const deduped = [];
+    for (const hit of hits) {
+        if (seen.has(hit.href))
+            continue;
+        seen.add(hit.href);
+        deduped.push(hit);
+        if (deduped.length >= limit)
+            break;
+    }
+    return deduped;
+}
+/**
+ * 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 function resolveEntity(artifact, prepared, query, opts = {}) {
+    return searchIndex(artifact, prepared, query, opts);
+}

package/dist/client.d.ts

@@ -41,6 +41,8 @@ export { Tabs, TabsList, TabsTrigger, TabsContent } from "./ui/components/Tabs";
 export type { TabsProps, TabsListProps, TabsTriggerProps, TabsContentProps } from "./ui/components/Tabs";
 export { TabBarShell, TabBarButton, TabsNavSelect } from "./ui/components/TabBarShell";
 export type { TabBarShellProps, TabBarButtonProps, TabsNavSelectProps } from "./ui/components/TabBarShell";
+export { OverflowRow } from "./ui/components/OverflowRow";
+export type { OverflowRowProps, OverflowRowItem, OverflowRowDotTone, OverflowRowLinkProps } from "./ui/components/OverflowRow";
 export { SellerProductsView } from "./features/seller/components/SellerProductsView";
 export { SellerOrderDetailPanel } from "./features/seller/components/SellerOrdersView";
 export { SellerPayoutDetailContent } from "./features/seller/components/SellerPayoutsView";
@@ -264,7 +266,7 @@ export { buildEventEntryDetailFields } from "./features/events/components/event-
 export type { EntryFieldRow } from "./features/events/components/event-entry-detail-fields";
 export type { BidDetailViewer } from "./features/auctions/components/bid-detail-fields";
 export type { AuctionBidsTableProps, AuctionWithBids } from "./features/auctions/components/AuctionBidsTable";
-export { ProtectedRoute, AuthStatusPanel, ForgotPasswordView, LoginForm, RegisterForm, ResetPasswordView, VerifyEmailView } from "./features/auth/index";
+export { ProtectedRoute, ForgotPasswordView, LoginForm, RegisterForm, ResetPasswordView, VerifyEmailView } from "./features/auth/index";
 export type { AuthGuardUser, ForgotPasswordViewProps, LoginFormProps, LoginFormValues, RegisterFormProps, RegisterFormValues, ResetPasswordViewProps, VerifyEmailViewProps, } from "./features/auth/index";
 export { useLogout, useLogin, useGoogleLogin, useLinkGoogleAccount, useRegister, useForgotPassword, useResetPassword, useVerifyEmail, useChangeEmail } from "./features/auth/index";
 export type { LoginCredentials, RegisterData, ForgotPasswordData, ResetPasswordData, VerifyEmailData, ChangeEmailData } from "./features/auth/index";
@@ -284,7 +286,6 @@ export { AddressBook, AddressCard, AddressForm } from "./features/account/index"
 export type { AddressCardAddress, AddressCardProps } from "./features/account/index";
 export { useProfile, useUpdateProfile } from "./features/account/index";
 export { updateProfileSchema } from "./features/account/index";
-export { CategoryProductsView } from "./features/categories/index";
 export type { CategoryItem } from "./features/categories/index";
 export { MediaImage } from "./features/media/index";
 export { StoreSidebar } from "./features/seller/components/SellerSidebar";
@@ -293,8 +294,8 @@ export { StoreProductsView, StoreAboutView } from "./features/stores/index";
 export type { StoreProductItem, StoreAboutViewProps, StoreDetail } from "./features/stores/index";
 export { SearchView } from "./features/search/index";
 export type { SearchViewProps } from "./features/search/index";
-export { UserSettingsView } from "./features/account/index";
-export type { UserSettingsViewProps, UserSettingsViewLabels } from "./features/account/index";
+export { useSearchIndex, ensureSearchIndex } from "./features/search/hooks/useSearchIndex";
+export type { SearchIndexState, SearchIndexStatus, LoadedSearchIndex, UseSearchIndexOptions, } from "./features/search/hooks/useSearchIndex";
 export { AdSlot } from "./features/homepage/components/AdSlot";
 export { useActiveAd } from "./features/homepage/hooks/useActiveAd";
 export type { ActiveAdRecord, ActiveAdCreative } from "./features/homepage/hooks/useActiveAd";
@@ -370,8 +371,8 @@ export type { SellerPayoutSettingsViewProps, SellerShippingViewProps, SellerRevi
 export { couponDraftToPayload } from "./features/seller/schemas/coupon-form";
 export type { SellerCouponPayload } from "./features/seller/schemas/coupon-form";
 export type { SellerAnalyticsSummary, SellerAnalyticsTopProduct } from "./features/seller/types/index";
-export { UserAccountHubView, UserOrdersView, UserBidsView, OrderDetailView, UserNotificationsView, UserReturnsView, UserSupportView, useNotifications } from "./features/account/index";
-export type { UserAccountHubViewProps, UserAccountHubViewLabels, UserOrdersViewProps, OrderDetailViewProps, OrderDetailViewLabels, UserNotificationsViewProps, UserNotificationsViewLabels, UserReturnsViewProps, UserSupportViewProps } from "./features/account/index";
+export { UserAccountHubView, UserOrdersView, UserBidsView, OrderDetailView, UserReturnsView, useNotifications } from "./features/account/index";
+export type { UserAccountHubViewProps, UserAccountHubViewLabels, UserOrdersViewProps, OrderDetailViewProps, OrderDetailViewLabels, UserReturnsViewProps } from "./features/account/index";
 export { useOrders, useOrder, OrdersList } from "./features/orders/index";
 export { OrderStatusTimeline } from "./features/orders/components/OrderStatusTimeline";
 export type { OrderStatusTimelineProps } from "./features/orders/components/OrderStatusTimeline";
@@ -407,7 +408,7 @@ export type { TrackArgs as TrackHistoryArgs } from "./features/history/hooks/use
 export { WISHLIST_MAX, HISTORY_MAX, CART_MAX_ITEMS, } from "./constants/limits";
 export { normalizeListingType, isAuctionListing, isPreOrderListing, isStandardListing, isPrizeDrawListing, isClassifiedListing, isDigitalCodeListing, isLiveListing, isArtListing, isStickersListing, } from "./features/products/utils/listing-type";
 export { isFinalSale, acceptsChangeOfMindReturns, } from "./features/products/constants/final-sale";
-export { isListingTypeEnabled, isCategoryTypeEnabled, enabledListingTypes, enabledCategoryTypes, ALL_LISTING_TYPES, } from "./_internal/shared/listing-types/feature-flags";
+export { isListingTypeEnabled, isCategoryTypeEnabled, enabledListingTypes, enabledCategoryTypes, ALL_LISTING_TYPES, isListingType, } from "./_internal/shared/listing-types/feature-flags";
 export { actionTracker, setActionTrackerSink, resetActionTrackerSink, type ActionEvent, type ActionTrackerSink, } from "./_internal/shared/listing-types/action-tracker";
 export { cartRequiresShipping, cartIsDigitalOnly, cartIsChatOnly, } from "./_internal/shared/listing-types/cart-shipping";
 export { ACTIONS, action, act, canPerformAction, actionsForListingType, actionLabel, type ActionDef, type ActionKind, type ActionResource, type ActionTree, type ActionConfirmation, } from "./_internal/shared/actions/action-registry";