@hashicorp/design-system-mcp 0.1.0

package/dist/stores/docs/lookup.js

@@ -0,0 +1,148 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+// record shapes the store hands out, plus the filter and snippet rules applied to them
+import { normalizeLookupValue } from "../../catalog/normalize.js";
+import { SNIPPET_MAX_LENGTH } from "./constants.js";
+import { tokenize } from "./tokenize.js";
+// a route with no leading or trailing slash, matching the `docsPath` in the component catalog
+export const normalizeRoute = (value) => {
+    return normalizeLookupValue(value).replace(/^\/+|\/+$/g, "");
+};
+export const toPageRecord = (page) => {
+    return {
+        route: page.route,
+        section: page.section,
+        title: page.title,
+        url: page.url,
+        ...(page.caption === undefined ? {} : { caption: page.caption }),
+        ...(page.description === undefined
+            ? {}
+            : { description: page.description }),
+        keywords: page.keywords ?? [],
+        related: page.related ?? [],
+        ...(page.links === undefined ? {} : { links: page.links }),
+        ...(page.status === undefined ? {} : { status: page.status }),
+    };
+};
+export const toChunkRecord = (chunk, page) => {
+    return {
+        id: chunk.id,
+        route: page.route,
+        section: page.section,
+        pageTitle: page.title,
+        pageUrl: page.url,
+        url: chunk.url,
+        ...(chunk.tab === undefined ? {} : { tab: chunk.tab }),
+        headingTrail: chunk.headingTrail ?? [],
+        ...(chunk.level === undefined ? {} : { level: chunk.level }),
+        content: chunk.content,
+        text: chunk.text,
+        symbols: chunk.symbols ?? [],
+    };
+};
+export const getHeadingPath = (chunk) => {
+    return [
+        chunk.pageTitle,
+        ...(chunk.tab === undefined ? [] : [chunk.tab]),
+        ...chunk.headingTrail,
+    ];
+};
+export const getChunkHeading = (chunk) => {
+    return chunk.headingTrail.at(-1);
+};
+// the words a page is called by: its title, plus the terminal segment of its route
+export const getPageNameTerms = (page) => {
+    const terminalSegment = page.route.split("/").at(-1) ?? page.route;
+    return new Set([...tokenize(page.title), ...tokenize(terminalSegment)]);
+};
+export const getAncestorHeadings = (chunk) => {
+    return chunk.headingTrail.slice(0, -1);
+};
+export const matchesDocsPath = (route, docsPath) => {
+    return route === docsPath || route.startsWith(`${docsPath}/`);
+};
+export const matchesFilters = (chunk, filters) => {
+    if (filters.section !== undefined &&
+        normalizeLookupValue(chunk.section) !== filters.section) {
+        return false;
+    }
+    if (filters.tab !== undefined &&
+        (chunk.tab === undefined || normalizeLookupValue(chunk.tab) !== filters.tab)) {
+        return false;
+    }
+    if (filters.docsPath !== undefined &&
+        !matchesDocsPath(normalizeRoute(chunk.route), filters.docsPath)) {
+        return false;
+    }
+    return true;
+};
+const SENTENCE_BOUNDARY_PATTERN = /(?<=[.!?])\s+/;
+const ELLIPSIS = "…";
+const countMatches = (sentence, queryTerms) => {
+    let matches = 0;
+    for (const term of tokenize(sentence)) {
+        if (queryTerms.has(term)) {
+            matches += 1;
+        }
+    }
+    return matches;
+};
+const scoreSentence = (sentence, queryTerms) => {
+    const tokenCount = tokenize(sentence).length;
+    if (tokenCount === 0)
+        return 0;
+    return countMatches(sentence, queryTerms) / Math.sqrt(tokenCount);
+};
+export const buildSnippet = (text, queryTerms, budget = SNIPPET_MAX_LENGTH) => {
+    const trimmed = text.trim();
+    if (trimmed.length <= budget) {
+        return trimmed;
+    }
+    const sentences = trimmed.split(SENTENCE_BOUNDARY_PATTERN);
+    if (sentences.length === 1) {
+        return `${trimmed.slice(0, budget).trimEnd()}${ELLIPSIS}`;
+    }
+    const scores = sentences.map((sentence) => scoreSentence(sentence, queryTerms));
+    let seedIndex = 0;
+    for (const [index, score] of scores.entries()) {
+        if (score > scores[seedIndex])
+            seedIndex = index;
+    }
+    const seed = sentences[seedIndex];
+    if (seed.length > budget) {
+        const prefix = seedIndex > 0 ? ELLIPSIS : "";
+        return `${prefix}${seed.slice(0, budget - prefix.length).trimEnd()}${ELLIPSIS}`;
+    }
+    let start = seedIndex;
+    let end = seedIndex;
+    let length = seed.length;
+    while (true) {
+        const previous = start > 0 ? start - 1 : null;
+        const next = end < sentences.length - 1 ? end + 1 : null;
+        if (previous === null && next === null) {
+            break;
+        }
+        const takePrevious = next === null || (previous !== null && scores[previous] >= scores[next]);
+        const candidate = takePrevious ? previous : next;
+        if (candidate === null) {
+            break;
+        }
+        const candidateLength = sentences[candidate].length + 1;
+        if (length + candidateLength > budget) {
+            break;
+        }
+        length += candidateLength;
+        if (takePrevious) {
+            start = candidate;
+        }
+        else {
+            end = candidate;
+        }
+    }
+    const window = sentences.slice(start, end + 1).join(" ");
+    const prefix = start > 0 ? ELLIPSIS : "";
+    const suffix = end < sentences.length - 1 ? ELLIPSIS : "";
+    return `${prefix}${window}${suffix}`;
+};

package/dist/stores/docs/schema.js

@@ -0,0 +1,60 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+import { z } from "zod";
+import { SITE_BASE_URL } from "./constants.js";
+const siteUrlSchema = z
+    .string()
+    .startsWith(SITE_BASE_URL, `must be a ${SITE_BASE_URL} url`);
+const docsChunkSchema = z
+    .object({
+    id: z.string().min(1),
+    url: siteUrlSchema,
+    // readable markdown, with the <Doc::*> and <Hds::*> usage examples left intact
+    content: z.string(),
+    // the same passage as `content` stripped to prose (for search scoring)
+    text: z.string(),
+    tab: z.string().min(1).optional(),
+    // ancestor headings first, the chunk's own heading last; absent on a tab preamble
+    headingTrail: z.array(z.string()).optional(),
+    level: z.number().int().optional(),
+    // identifiers harvested from the chunk's demo code, such as `@isFullWidth`
+    symbols: z.array(z.string()).optional(),
+})
+    .catchall(z.any());
+const docsPageLinksSchema = z
+    .object({
+    github: z.string().min(1).optional(),
+    figma: z.string().min(1).optional(),
+})
+    .catchall(z.any());
+const docsPageStatusSchema = z
+    .object({
+    updated: z.string().min(1).optional(),
+    deprecated: z.string().min(1).optional(),
+})
+    .catchall(z.any());
+const docsPageSchema = z
+    .object({
+    route: z.string().min(1),
+    section: z.string().min(1),
+    title: z.string().min(1),
+    url: siteUrlSchema,
+    caption: z.string().optional(),
+    description: z.string().optional(),
+    keywords: z.array(z.string()).optional(),
+    related: z.array(z.string()).optional(),
+    links: docsPageLinksSchema.optional(),
+    status: docsPageStatusSchema.optional(),
+    chunks: z.array(docsChunkSchema),
+})
+    .catchall(z.any());
+export const docsCatalogSchema = z
+    .object({
+    // when this snapshot of the docs site was bundled
+    bundledAt: z.string().min(1),
+    siteBaseUrl: z.literal(SITE_BASE_URL),
+    pages: z.record(z.string().min(1), docsPageSchema),
+})
+    .catchall(z.any());

package/dist/stores/docs/search-index.js

@@ -0,0 +1,102 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+// a local BM25 index; scoring never leaves this process
+// https://lucene.apache.org/core/9_12_3/core/org/apache/lucene/search/similarities/BM25Similarity.html
+import { BM25_B, BM25_K1 } from "./constants.js";
+import { tokenize } from "./tokenize.js";
+const toFieldText = (value) => {
+    if (value === undefined) {
+        return "";
+    }
+    else {
+        return Array.isArray(value) ? value.join(" ") : value;
+    }
+};
+export const buildBm25Index = (documents) => {
+    const documentLengths = new Float64Array(documents.length);
+    const postings = new Map();
+    let totalLength = 0;
+    for (const [documentIndex, fields] of documents.entries()) {
+        const termFrequencies = new Map();
+        let documentLength = 0;
+        for (const field of fields) {
+            if (field.weight <= 0) {
+                continue;
+            }
+            for (const term of tokenize(toFieldText(field.value))) {
+                termFrequencies.set(term, (termFrequencies.get(term) ?? 0) + field.weight);
+                documentLength += field.weight;
+            }
+        }
+        documentLengths[documentIndex] = documentLength;
+        totalLength += documentLength;
+        for (const [term, frequency] of termFrequencies) {
+            const termPostings = postings.get(term);
+            if (termPostings === undefined) {
+                postings.set(term, [{ documentIndex, frequency }]);
+            }
+            else {
+                termPostings.push({ documentIndex, frequency });
+            }
+        }
+    }
+    return {
+        documentCount: documents.length,
+        averageLength: documents.length === 0 ? 0 : totalLength / documents.length,
+        documentLengths,
+        postings,
+    };
+};
+// inverse document frequency, the one measure of how much a term narrows the corpus down
+const getIdf = (documentCount, documentFrequency) => {
+    return Math.log(1 + (documentCount - documentFrequency + 0.5) / (documentFrequency + 0.5));
+};
+export const scoreBm25 = (index, queryTerms) => {
+    const scores = new Float64Array(index.documentCount);
+    const matchedTermsByDocument = new Map();
+    if (index.documentCount === 0 || index.averageLength === 0) {
+        return { scores, matchedTermsByDocument };
+    }
+    for (const term of queryTerms) {
+        const termPostings = index.postings.get(term);
+        if (termPostings === undefined) {
+            continue;
+        }
+        const idf = getIdf(index.documentCount, termPostings.length);
+        for (const { documentIndex, frequency } of termPostings) {
+            const normalizedLength = index.documentLengths[documentIndex] / index.averageLength;
+            const denominator = frequency + BM25_K1 * (1 - BM25_B + BM25_B * normalizedLength);
+            scores[documentIndex] +=
+                (idf * (frequency * (BM25_K1 + 1))) / denominator;
+            const matched = matchedTermsByDocument.get(documentIndex);
+            if (matched === undefined) {
+                matchedTermsByDocument.set(documentIndex, new Set([term]));
+            }
+            else {
+                matched.add(term);
+            }
+        }
+    }
+    return { scores, matchedTermsByDocument };
+};
+export const hasTerm = (index, term) => {
+    return index.postings.has(term);
+};
+// how completely a query and a name are the same set of words, as a Jaccard ratio
+// https://www.ibm.com/think/topics/jaccard-similarity
+export const getNameMatchRatio = (queryTerms, nameTerms) => {
+    if (queryTerms.size === 0 || nameTerms.size === 0) {
+        return 0;
+    }
+    let shared = 0;
+    for (const term of nameTerms) {
+        if (queryTerms.has(term))
+            shared += 1;
+    }
+    if (shared === 0) {
+        return 0;
+    }
+    return shared / (queryTerms.size + nameTerms.size - shared);
+};

package/dist/stores/docs/tokenize.js

@@ -0,0 +1,52 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+import { STOPWORDS } from "./constants.js";
+// the single tokenizer both the index and every query run through
+const MIN_TOKEN_LENGTH = 2;
+// version strings are the point of the version-history tab, so they survive as whole tokens
+const VERSION_PATTERN = /\d+\.\d+(?:\.\d+)?/g;
+const NON_ALPHANUMERIC_PATTERN = /[^A-Za-z0-9]+/;
+const CAMEL_BOUNDARY_PATTERN = /[a-z0-9][A-Z]/;
+const CAMEL_SPLIT_PATTERN = /(?<=[a-z0-9])(?=[A-Z])/;
+const NAMESPACE_TOKEN = "hds";
+const NAMESPACE_PREFIX_PATTERN = /\bhds(?:::|[-_])(?=[A-Za-z0-9])/gi;
+const pushToken = (tokens, candidate) => {
+    if (candidate.length < MIN_TOKEN_LENGTH) {
+        return;
+    }
+    else if (STOPWORDS.has(candidate)) {
+        return;
+    }
+    else {
+        tokens.push(candidate);
+    }
+};
+export const tokenize = (value) => {
+    const tokens = [];
+    const withoutNamespace = value.replace(NAMESPACE_PREFIX_PATTERN, "");
+    const withoutVersions = withoutNamespace.replace(VERSION_PATTERN, (version) => {
+        tokens.push(version);
+        return " ";
+    });
+    for (const rawToken of withoutVersions.split(NON_ALPHANUMERIC_PATTERN)) {
+        if (rawToken.length === 0)
+            continue;
+        pushToken(tokens, rawToken.toLowerCase());
+        if (!CAMEL_BOUNDARY_PATTERN.test(rawToken)) {
+            continue;
+        }
+        const parts = rawToken.split(CAMEL_SPLIT_PATTERN);
+        for (const [index, part] of parts.entries()) {
+            if (index === 0 && part.toLowerCase() === NAMESPACE_TOKEN) {
+                continue;
+            }
+            pushToken(tokens, part.toLowerCase());
+        }
+    }
+    return tokens;
+};
+export const tokenizeQuery = (value) => {
+    return [...new Set(tokenize(value))];
+};

package/dist/stores/hds-icons/index.js

@@ -0,0 +1,115 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+import { normalizeLookupValue } from "../../catalog/normalize.js";
+import { DEFAULT_CATALOG_SOURCE, createCatalogLoader, } from "../../catalog/loader.js";
+import { getIconLookupKeys, toIconRecord } from "./lookup.js";
+import { iconCatalogSchema } from "./schema.js";
+import { searchRanked } from "../rank.js";
+const toIconSummary = (icon) => {
+    return {
+        iconName: icon.iconName,
+        description: icon.description,
+        category: icon.category,
+        sizes: icon.sizes,
+        hasMapping: icon.hasMapping,
+    };
+};
+const toSearchBlob = (icon) => {
+    const mappings = icon.variants
+        .map((variant) => variant.mapping ?? "")
+        .join(" ");
+    const fileNames = icon.variants.map((variant) => variant.fileName).join(" ");
+    return [icon.iconName, icon.description, icon.category, mappings, fileNames]
+        .join(" ")
+        .toLowerCase();
+};
+// the `@name` value and the per-size file names; the description keywords stay in the blob so
+// `warning` still reaches `alert-triangle` without outranking an icon actually named for it
+const toRankable = (icon) => {
+    return {
+        identities: [
+            normalizeLookupValue(icon.iconName),
+            ...icon.variants.map((variant) => normalizeLookupValue(variant.fileName)),
+        ],
+        blob: toSearchBlob(icon),
+    };
+};
+export const parseIconCatalog = (value) => {
+    return iconCatalogSchema.parse(value);
+};
+export const createIconCatalogStore = (catalog, source = DEFAULT_CATALOG_SOURCE) => {
+    const assetsByIconName = new Map();
+    for (const asset of catalog.assets) {
+        const normalizedName = normalizeLookupValue(asset.iconName);
+        const existingAssets = assetsByIconName.get(normalizedName) ?? [];
+        assetsByIconName.set(normalizedName, [...existingAssets, asset]);
+    }
+    const iconRecords = [...assetsByIconName.values()].map((assets) => toIconRecord(assets));
+    const iconLookup = new Map();
+    for (const icon of iconRecords) {
+        for (const key of getIconLookupKeys(icon)) {
+            iconLookup.set(key, icon);
+        }
+    }
+    const categories = [
+        ...new Set(iconRecords.map((icon) => icon.category)),
+    ].sort((left, right) => left.localeCompare(right));
+    const sizes = [
+        ...new Set(iconRecords.flatMap((icon) => icon.sizes)),
+    ].sort((left, right) => left.localeCompare(right));
+    return {
+        getMeta: () => ({
+            totalIconCount: iconRecords.length,
+            totalAssetCount: catalog.assets.length,
+            categories,
+            sizes,
+            source,
+        }),
+        listIcons: () => iconRecords.map((icon) => toIconSummary(icon)),
+        listIconAliases: () => iconRecords.map((icon) => ({
+            iconName: icon.iconName,
+            fileNames: icon.variants.map((variant) => variant.fileName),
+        })),
+        getIconByName: (nameOrFileName) => {
+            return iconLookup.get(normalizeLookupValue(nameOrFileName)) ?? null;
+        },
+        searchIcons: ({ query, limit, category, size, hasMapping }) => {
+            const normalizedCategory = category === undefined ? null : normalizeLookupValue(category);
+            const normalizedSize = size === undefined ? null : normalizeLookupValue(size);
+            const { totalMatches, hits } = searchRanked({
+                records: iconRecords,
+                query,
+                limit,
+                toRankable,
+                matches: (icon) => {
+                    if (normalizedCategory !== null &&
+                        normalizeLookupValue(icon.category) !== normalizedCategory) {
+                        return false;
+                    }
+                    if (normalizedSize !== null && !icon.sizes.includes(normalizedSize)) {
+                        return false;
+                    }
+                    return hasMapping === undefined || icon.hasMapping === hasMapping;
+                },
+            });
+            return {
+                totalMatches,
+                hits: hits.map((icon) => toIconSummary(icon)),
+            };
+        },
+    };
+};
+const iconCatalogLoader = createCatalogLoader({
+    specifier: "@hashicorp/flight-icons/catalog.json",
+    // icons reach most consumers through the components package they installed
+    anchors: ["project-root", "components", "default"],
+    create: (value, source) => createIconCatalogStore(parseIconCatalog(value), source),
+});
+export const loadIconCatalog = () => {
+    return iconCatalogLoader.load();
+};
+export const getOrLoadIconStore = () => {
+    return iconCatalogLoader.getOrLoad();
+};

package/dist/stores/hds-icons/lookup.js

@@ -0,0 +1,43 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+import { normalizeLookupValue } from "../../catalog/normalize.js";
+export const getIconLookupKeys = (icon) => {
+    return [
+        normalizeLookupValue(icon.iconName),
+        ...icon.variants.map((variant) => normalizeLookupValue(variant.fileName)),
+    ];
+};
+const compareIconVariantsBySize = (left, right) => {
+    return left.size.localeCompare(right.size, undefined, { numeric: true });
+};
+export const toIconRecord = (assets) => {
+    const firstAsset = assets[0];
+    if (firstAsset === undefined) {
+        throw new Error("Cannot create icon record from an empty assets array.");
+    }
+    const variants = assets
+        .map((asset) => {
+        return {
+            id: asset.id,
+            fileName: asset.fileName,
+            size: asset.size,
+            width: asset.width,
+            height: asset.height,
+            ...(asset.mapping === undefined ? {} : { mapping: asset.mapping }),
+        };
+    })
+        .sort(compareIconVariantsBySize);
+    const description = assets
+        .map((asset) => asset.description?.trim() ?? "")
+        .find((value) => value.length > 0) ?? "";
+    return {
+        iconName: firstAsset.iconName,
+        description,
+        category: firstAsset.category,
+        sizes: variants.map((variant) => variant.size),
+        hasMapping: variants.some((variant) => variant.mapping !== undefined),
+        variants,
+    };
+};

package/dist/stores/hds-icons/schema.js

@@ -0,0 +1,31 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+import { z } from "zod";
+export const iconAssetSchema = z
+    .object({
+    id: z.string().min(1),
+    fileName: z.string().min(1),
+    iconName: z.string().min(1),
+    description: z.string().optional(),
+    category: z.string().min(1),
+    size: z.string().min(1),
+    width: z.number(),
+    height: z.number(),
+    mapping: z.string().min(1).optional(),
+})
+    .catchall(z.any());
+const lastRunFigmaSchema = z
+    .object({
+    id: z.string().min(1),
+    page: z.string().min(1),
+    excludeFrames: z.array(z.string()),
+})
+    .catchall(z.any());
+export const iconCatalogSchema = z
+    .object({
+    lastRunFigma: lastRunFigmaSchema.optional(),
+    assets: z.array(iconAssetSchema),
+})
+    .catchall(z.any());

package/dist/stores/rank.js

@@ -0,0 +1,129 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+// relevance ordering for the substring catalogs: components, tokens and icons
+import { normalizeLookupValue } from "../catalog/normalize.js";
+/**
+ * A match is scored by where the query lands in the entry's identity fields — the names a
+ * caller would actually type. Without this an entry that merely contains the query can push
+ * the entry that *is* the query out of a truncated window: `form` matched 55 components and
+ * returned the 20 alphabetically-first, none of which was `Hds::Form`.
+ */
+export const RANK_EXACT = 500;
+export const RANK_PREFIX = 400;
+export const RANK_SEGMENT = 300;
+export const RANK_IDENTITY = 200;
+export const RANK_BLOB = 100;
+export const RANK_NONE = 0;
+// `hds::form::text-input`, `token-color-foreground-action` and `arrow-right-24` all delimit
+// their parts with one of these
+const SEGMENT_DELIMITER = /[\s:./_-]+/u;
+/**
+ * The same name is delimited differently depending on where it is written: `hds::button` in a
+ * template, `hds/button` in an import, `border.radius.small` as a token key and `border-radius`
+ * as the CSS variable a caller actually types. Comparing on a delimiter-free form lets a query
+ * written in any of those styles reach the others, so `border-radius` still prefix-matches
+ * `border.radius.small` rather than losing to a token that merely contains the words.
+ */
+const canonicalize = (value) => {
+    return value
+        .replace(/[{}]/gu, "")
+        .split(SEGMENT_DELIMITER)
+        .filter(Boolean)
+        .join(" ");
+};
+export const scoreIdentity = (identity, query) => {
+    const canonicalIdentity = canonicalize(identity);
+    const canonicalQuery = canonicalize(query);
+    if (canonicalQuery.length === 0) {
+        return RANK_NONE;
+    }
+    if (identity === query) {
+        return RANK_EXACT;
+    }
+    if (canonicalIdentity === canonicalQuery) {
+        return RANK_EXACT;
+    }
+    if (identity.startsWith(query) ||
+        canonicalIdentity.startsWith(`${canonicalQuery} `)) {
+        return RANK_PREFIX;
+    }
+    // a whole run of segments, so `foreground` matches `color.foreground.action` but `oregon`
+    // does not, and a two-word query stays a phrase rather than two loose terms
+    if (` ${canonicalIdentity} `.includes(` ${canonicalQuery} `)) {
+        return RANK_SEGMENT;
+    }
+    if (identity.includes(query) || canonicalIdentity.includes(canonicalQuery)) {
+        return RANK_IDENTITY;
+    }
+    return RANK_NONE;
+};
+export const scoreEntry = (entry, query) => {
+    let score = RANK_NONE;
+    let identityLength = Number.MAX_SAFE_INTEGER;
+    for (const identity of entry.identities) {
+        const identityScore = scoreIdentity(identity, query);
+        if (identityScore === RANK_NONE) {
+            continue;
+        }
+        if (identityScore > score) {
+            score = identityScore;
+            identityLength = identity.length;
+        }
+        else if (identityScore === score && identity.length < identityLength) {
+            identityLength = identity.length;
+        }
+    }
+    if (score !== RANK_NONE) {
+        return { score, identityLength };
+    }
+    // a keyword-only hit still counts: `warning` reaches `alert-triangle` through its description
+    return entry.blob.includes(query)
+        ? { score: RANK_BLOB, identityLength }
+        : { score: RANK_NONE, identityLength };
+};
+// how far two keys agree from the left, which is what survives a typo in the tail
+export const getCommonPrefixLength = (left, right) => {
+    const limit = Math.min(left.length, right.length);
+    let index = 0;
+    while (index < limit && left[index] === right[index]) {
+        index += 1;
+    }
+    return index;
+};
+export const searchRanked = ({ records, query, limit, toRankable, matches, }) => {
+    const normalizedQuery = normalizeLookupValue(query);
+    const filtered = records.filter((record) => matches === undefined || matches(record));
+    // an all-whitespace query is a browse, not a search, so the catalog keeps its own order
+    if (normalizedQuery.length === 0) {
+        return {
+            totalMatches: filtered.length,
+            hits: filtered.slice(0, limit),
+        };
+    }
+    if (canonicalize(normalizedQuery).length === 0) {
+        return { totalMatches: 0, hits: [] };
+    }
+    const scored = [];
+    for (const [index, record] of filtered.entries()) {
+        const { score, identityLength } = scoreEntry(toRankable(record), normalizedQuery);
+        if (score === RANK_NONE) {
+            continue;
+        }
+        scored.push({ record, score, identityLength, index });
+    }
+    scored.sort((left, right) => {
+        if (right.score !== left.score) {
+            return right.score - left.score;
+        }
+        if (left.identityLength !== right.identityLength) {
+            return left.identityLength - right.identityLength;
+        }
+        return left.index - right.index;
+    });
+    return {
+        totalMatches: scored.length,
+        hits: scored.slice(0, limit).map((entry) => entry.record),
+    };
+};