@jxsuite/search 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kevin Shenk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/search-index.js

@@ -1,3 +1,142 @@
+// ../../packages/schema/src/locale.ts
+var RTL_SCRIPTS = new Set([
+  "Adlm",
+  "Arab",
+  "Aran",
+  "Armi",
+  "Avst",
+  "Cprt",
+  "Egyd",
+  "Egyh",
+  "Elym",
+  "Gara",
+  "Hatr",
+  "Hebr",
+  "Hluw",
+  "Hung",
+  "Khar",
+  "Lydi",
+  "Mand",
+  "Mani",
+  "Mend",
+  "Merc",
+  "Mero",
+  "Narb",
+  "Nbat",
+  "Nkoo",
+  "Orkh",
+  "Palm",
+  "Phli",
+  "Phlp",
+  "Phnx",
+  "Prti",
+  "Rohg",
+  "Samr",
+  "Sarb",
+  "Sogd",
+  "Sogo",
+  "Syrc",
+  "Thaa",
+  "Todr",
+  "Yezi"
+]);
+function canonicalizeLocale(tag) {
+  if (typeof tag !== "string" || tag.trim() === "") {
+    return null;
+  }
+  try {
+    return new Intl.Locale(tag.trim()).toString();
+  } catch {
+    return null;
+  }
+}
+var DEFAULT_ROUTING = "prefix-except-default";
+function resolveI18n(projectConfig) {
+  const raw = projectConfig.i18n;
+  const errors = [];
+  if (!raw || typeof raw !== "object") {
+    return { errors, i18n: null };
+  }
+  const declared = Array.isArray(raw.locales) ? raw.locales : [];
+  const locales = [];
+  for (const tag of declared) {
+    const canonical = canonicalizeLocale(tag);
+    if (canonical === null) {
+      errors.push(`i18n.locales: "${String(tag)}" is not a well-formed BCP 47 language tag.`);
+      continue;
+    }
+    if (!locales.includes(canonical)) {
+      locales.push(canonical);
+    }
+  }
+  const defaultLocale = canonicalizeLocale(raw.defaultLocale) ?? locales[0] ?? null;
+  if (raw.defaultLocale !== undefined && canonicalizeLocale(raw.defaultLocale) === null) {
+    errors.push(`i18n.defaultLocale: "${String(raw.defaultLocale)}" is not a well-formed BCP 47 language tag.`);
+  }
+  if (defaultLocale === null) {
+    errors.push("i18n is declared with no usable locale — set `defaultLocale` or `locales`.");
+    return { errors, i18n: null };
+  }
+  if (!locales.includes(defaultLocale)) {
+    locales.unshift(defaultLocale);
+  }
+  const routing = raw.routing === "prefix-always" || raw.routing === "prefix-except-default" ? raw.routing : DEFAULT_ROUTING;
+  return { errors, i18n: { defaultLocale, locales, routing } };
+}
+function localeUrlPrefix(locale, i18n) {
+  if (i18n === null) {
+    return "";
+  }
+  const canonical = canonicalizeLocale(locale);
+  if (canonical === null || !i18n.locales.includes(canonical)) {
+    return "";
+  }
+  if (canonical === i18n.defaultLocale && i18n.routing === "prefix-except-default") {
+    return "";
+  }
+  return `/${canonical.toLowerCase()}`;
+}
+
+// ../../packages/schema/src/guards.ts
+function isJsonObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+var SCHEMA_KEYWORDS = new Set([
+  "type",
+  "enum",
+  "minimum",
+  "maximum",
+  "minLength",
+  "maxLength",
+  "pattern",
+  "format",
+  "items",
+  "properties",
+  "required",
+  "description",
+  "title",
+  "$comment"
+]);
+function isTagExpression(tagName) {
+  return isJsonObject(tagName) && isJsonObject(tagName.$expression);
+}
+function tagNameCandidates(tagName) {
+  if (typeof tagName === "string") {
+    return [tagName];
+  }
+  if (!isTagExpression(tagName)) {
+    return [];
+  }
+  const expression = tagName.$expression;
+  if (expression.operator === "?:") {
+    return [...new Set([expression.value, expression.initial])];
+  }
+  return [...new Set([...Object.values(expression.cases), expression.default])];
+}
+function displayTagName(tagName) {
+  return typeof tagName === "string" ? tagName : tagNameCandidates(tagName).join("|");
+}
+
 // src/shared.ts
 var DEFAULT_OUTPUT = "/search-index.json";
 var DEFAULT_FIELDS = ["title", "heading", "text"];
@@ -85,7 +224,7 @@ function headingOf(node) {
   if (typeof node !== "object" || node === null || !node.tagName) {
     return null;
   }
-  const match = HEADING_TAG.exec(node.tagName);
+  const match = HEADING_TAG.exec(displayTagName(node.tagName));
   if (!match) {
     return null;
   }
@@ -105,6 +244,7 @@ var SearchIndex = {
     const config = normalizeSearchConfig(sectionValue);
     const content = ctx.sections?.content;
     const trailingSlash = ctx.projectConfig?.build?.trailingSlash ?? "always";
+    const { i18n } = resolveI18n(ctx.projectConfig ?? {});
     const documents = [];
     const fields = new Set;
     const boost = {};
@@ -120,31 +260,35 @@ var SearchIndex = {
       Object.assign(boost, collection.boost);
       for (const entry of entries) {
         const data = entry.data ?? {};
-        const url = entryUrl(collection.basePath, entry.id, trailingSlash);
+        const locale = i18n === null ? undefined : canonicalizeLocale(entry._meta?.locale) ?? undefined;
+        const url = entryUrl(`${localeUrlPrefix(locale, i18n)}${collection.basePath}`, entry.id, trailingSlash);
         const title = typeof data.title === "string" ? data.title : entry.id;
         const description = typeof data.description === "string" ? data.description : "";
         const children = entry.$children;
+        const documentId = locale === undefined ? `${name}:${entry.id}` : `${name}:${locale}:${entry.id}`;
         documents.push({
-          id: `${name}:${entry.id}`,
+          id: documentId,
           collection: name,
           slug: entry.id,
           url,
           title,
           description,
           heading: "",
-          text: jxTreeToText(children)
+          text: jxTreeToText(children),
+          ...locale === undefined ? {} : { locale }
         });
         if (collection.sections) {
           for (const section of splitSections(children, collection.sectionDepth)) {
             documents.push({
-              id: `${name}:${entry.id}#${section.anchor}`,
+              id: `${documentId}#${section.anchor}`,
               collection: name,
               slug: entry.id,
               url: `${url}#${section.anchor}`,
               title,
               description,
               heading: section.heading,
-              text: section.text
+              text: section.text,
+              ...locale === undefined ? {} : { locale }
             });
           }
         }

package/dist/search-state.js

@@ -12,6 +12,7 @@ function sidecarAssetPath(specifier) {
   base = base.replace(/^\.\//, "").replace(/\.(js|ts|mjs|mts)$/, "").replaceAll("@", "").replaceAll(/[/\\]+/g, "-").replaceAll(/[^\w.-]/g, "-").replaceAll(/-+/g, "-").replaceAll(/^-|-$/g, "");
   return `${SIDECAR_ASSET_DIR}${base}.js`;
 }
+var URL_TERMINATOR = String.raw`"'\s<>()\\`;
 
 // src/search-state.ts
 var CLIENT_SPECIFIER = "npm:@jxsuite/search/client";
@@ -44,7 +45,8 @@ class Search {
     const query = typeof this.config.query === "string" ? this.config.query : "";
     return client.query(query, {
       group: this.config.group ?? true,
-      limit: this.config.limit ?? 8
+      limit: this.config.limit ?? 8,
+      ...this.config.locale === undefined ? {} : { locale: this.config.locale }
     });
   }
   indexUrl() {
@@ -53,7 +55,11 @@ class Search {
   static lower(def, context = {}) {
     const indexUrl = def.index ?? context.projectConfig?.search?.output ?? "/search-index.json";
     const clientUrl = sidecarAssetPath(CLIENT_SPECIFIER);
-    const opts = JSON.stringify({ group: def.group ?? true, limit: def.limit ?? 8 });
+    const opts = JSON.stringify({
+      group: def.group ?? true,
+      limit: def.limit ?? 8,
+      ...def.locale === undefined ? {} : { locale: def.locale }
+    });
     const body = [
       "void state.__jxSearchReady;",
       "if (!globalThis.__jxSearch) {",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/search",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Static site search for Jx: build-time index emission from content collections and a headless MiniSearch browser client",
   "license": "MIT",
   "repository": {
@@ -26,7 +26,7 @@
     "./Search.class.json": "./src/Search.class.json"
   },
   "publishConfig": {
-    "provenance": false
+    "provenance": true
   },
   "scripts": {
     "prepare": "bun build src/search-index.ts src/search-state.ts --outdir=dist --format=esm --target=node",
@@ -36,7 +36,7 @@
     "upgrade": "bunx npm-check-updates -u && bun install"
   },
   "dependencies": {
-    "@jxsuite/schema": "workspace:^",
+    "@jxsuite/schema": "^1.6.0",
     "minisearch": "^7.2.0"
   },
   "devDependencies": {

package/src/Search.class.json

@@ -32,6 +32,11 @@
         "identifier": "index",
         "type": { "type": "string" },
         "description": "Index URL override (defaults to the project's search.output)"
+      },
+      "locale": {
+        "identifier": "locale",
+        "type": { "type": ["string", "null"] },
+        "description": "Language to search in \u2014 omitted, the page's own (<html lang>); null searches every language"
       }
     },
     "constructor": {
@@ -40,7 +45,8 @@
         { "$ref": "#/$defs/parameters/query" },
         { "$ref": "#/$defs/parameters/limit" },
         { "$ref": "#/$defs/parameters/group" },
-        { "$ref": "#/$defs/parameters/index" }
+        { "$ref": "#/$defs/parameters/index" },
+        { "$ref": "#/$defs/parameters/locale" }
       ],
       "body": ["this.config = config;"]
     },

package/src/client.ts

@@ -3,9 +3,10 @@
  *
  * Bundled into `/assets/` by the site build (spec.md §5.3); no UI. Fetches the emitted index
  * envelope once, builds a MiniSearch index in-memory (tens of milliseconds at docs scale), and
- * answers synchronous queries with page-grouped, section-anchored results. Field boosts and indexed
- * fields come from the envelope — the emitter bakes the project's `search` section in, so the
- * client needs no configuration.
+ * answers synchronous queries with section-anchored results — either grouped under their page, or
+ * flat and presentation-ready (breadcrumbs plus highlight tokens for the title and a body excerpt).
+ * Field boosts and indexed fields come from the envelope — the emitter bakes the project's `search`
+ * section in, so the client needs no configuration.
  *
  * Two integration surfaces: - `preload` / `isReady` / `query` — the core API (used by lowered
  * `Search` defs). - `searchInit` / `runSearch` — state-convention helpers for `$src` use inside
@@ -24,6 +25,37 @@ export interface SearchHit {
   score: number;
 }
 
+/**
+ * One run of display text. `m` is true when the run matched a query term — renderers wrap those in
+ * `<mark>` (or equivalent). Tokens rather than an HTML string so declarative renderers can
+ * highlight without injecting markup.
+ */
+export interface SearchToken {
+  t: string;
+  m: boolean;
+}
+
+/** One flat, presentation-ready result row: a page or one of its heading sections. */
+export interface SearchResult {
+  id: string;
+  collection: string;
+  slug: string;
+  /** Page URL, or page URL + `#anchor` for a section row. */
+  url: string;
+  /** Page title. */
+  title: string;
+  /** Heading text for a section row; `""` for a page row. */
+  heading: string;
+  description: string;
+  score: number;
+  /** Breadcrumb trail: slug ancestors, plus the page title on a section row. */
+  crumbs: string[];
+  /** The row's display title (heading, else page title), highlighted. */
+  titleTokens: SearchToken[];
+  /** A window of body text around the first match, highlighted. */
+  excerptTokens: SearchToken[];
+}
+
 /** One result group: a page and its matching sections, best-score first. */
 export interface SearchResultGroup {
   collection: string;
@@ -39,10 +71,24 @@ export interface SearchResultGroup {
 
 /** Query options. */
 export interface QueryOptions {
-  /** Maximum result groups (default 8). */
+  /** Maximum rows returned (default 8). */
   limit?: number;
-  /** Group section hits under their page (default true); false returns flat documents. */
+  /**
+   * Group section hits under their page (default true), yielding `SearchResultGroup[]`; false
+   * returns flat, presentation-ready `SearchResult[]` — one row per matching page or section.
+   */
   group?: boolean;
+  /**
+   * In flat mode, the most rows one page may contribute (default 3). Keeps long pages from flooding
+   * the list.
+   */
+  pageCap?: number;
+  /**
+   * The language to search in. Omitted, it is the page's own — `<html lang>`, which the build wrote
+   * from the route's locale, so a reader searching a French page is not handed English results.
+   * `null` searches every language.
+   */
+  locale?: string | null;
 }
 
 interface ClientState {
@@ -53,7 +99,162 @@ interface ClientState {
 
 const state: ClientState = { indexUrl: "/search-index.json", loading: null, mini: null };
 
-const STORE_FIELDS = ["collection", "slug", "url", "title", "description", "heading"];
+/** `text` is stored so flat results can carry a highlighted excerpt of the body. */
+const STORE_FIELDS = [
+  "collection",
+  "slug",
+  "url",
+  "title",
+  "description",
+  "heading",
+  "text",
+  "locale",
+];
+
+/**
+ * The language this page is in, from `<html lang>`.
+ *
+ * The document element is the right source and the only one available: the build wrote that
+ * attribute from the route's locale (site-architecture.md §13.4), so it is the same answer the
+ * index was built against, and it is correct inside a component, an island and a fragment alike.
+ *
+ * @returns {string} The tag, or `""` off a document
+ */
+function pageLocale(): string {
+  return globalThis.document?.documentElement?.lang ?? "";
+}
+
+/**
+ * Whether a document in `docLocale` answers a search made in `want`.
+ *
+ * A document with no locale always answers: an unlocalized collection is not in one language, it is
+ * outside the question, and hiding it would empty the search box on a site whose docs are shared.
+ *
+ * Region is ignored when the tags disagree on it alone — a reader on `/fr-ca/` wants the French
+ * posts — which is RFC 4647 Lookup's truncation, at the one length that matters here.
+ */
+/**
+ * What makes two hits the same page.
+ *
+ * The locale is part of it because two translations of one entry **share a slug** (§13.3): without
+ * it, an unscoped search collapses the French copy and the English one into a single group whose
+ * title is whichever was indexed first.
+ */
+function pageKey(hit: RawHit): string {
+  return `${hit.collection}:${hit.locale ?? ""}:${hit.slug}`;
+}
+
+function localeAnswers(docLocale: string | undefined, want: string): boolean {
+  if (docLocale === undefined || want === "") {
+    return true;
+  }
+  const a = docLocale.toLowerCase();
+  const b = want.toLowerCase();
+  return a === b || a.split("-")[0] === b.split("-")[0];
+}
+
+/** A fresh word scanner — regexes with `g` carry `lastIndex`, so never share one. */
+function wordScanner(): RegExp {
+  return /[\p{L}\p{N}_]+/gu;
+}
+
+/** Excerpt window, in characters. */
+const EXCERPT_WIDTH = 160;
+
+/** How much of the excerpt window sits before the first match. */
+const EXCERPT_LEAD = 60;
+
+/** Default cap on rows one page may contribute to a flat result list. */
+const PAGE_CAP = 3;
+
+/** Lowercased needles a word must start with to count as a match. */
+function needlesOf(terms: readonly string[]): string[] {
+  const seen = new Set<string>();
+  for (const term of terms) {
+    if (term) {
+      seen.add(term.toLowerCase());
+    }
+  }
+  return [...seen];
+}
+
+/** `[start, end)` spans of the whole words in `text` that begin with one of `needles`. */
+function matchSpans(text: string, needles: readonly string[]): [number, number][] {
+  const spans: [number, number][] = [];
+  if (!text || needles.length === 0) {
+    return spans;
+  }
+  const lower = text.toLowerCase();
+  const scanner = wordScanner();
+  let match = scanner.exec(lower);
+  while (match !== null) {
+    const [word] = match;
+    if (needles.some((needle) => word.startsWith(needle))) {
+      spans.push([match.index, match.index + word.length]);
+    }
+    match = scanner.exec(lower);
+  }
+  return spans;
+}
+
+/**
+ * Split `text` into alternating plain and matched runs. A word is matched when it starts with one
+ * of the query's terms, so a prefix search for "intro" highlights the whole word "introduction".
+ */
+export function buildTokens(text: string, terms: readonly string[]): SearchToken[] {
+  if (!text) {
+    return [];
+  }
+  const tokens: SearchToken[] = [];
+  let cursor = 0;
+  for (const [start, end] of matchSpans(text, needlesOf(terms))) {
+    if (start > cursor) {
+      tokens.push({ m: false, t: text.slice(cursor, start) });
+    }
+    tokens.push({ m: true, t: text.slice(start, end) });
+    cursor = end;
+  }
+  if (cursor < text.length) {
+    tokens.push({ m: false, t: text.slice(cursor) });
+  }
+  return tokens;
+}
+
+/**
+ * A readable window of `text` around its first match, snapped to word boundaries and elided with
+ * `…` on either side when truncated. With no match in the body, the opening of the text is used.
+ */
+export function buildExcerpt(text: string, terms: readonly string[]): string {
+  const body = text.trim();
+  if (!body) {
+    return "";
+  }
+  const at = matchSpans(body, needlesOf(terms))[0]?.[0] ?? -1;
+  let start = at < 0 ? 0 : Math.max(0, at - EXCERPT_LEAD);
+  if (start > 0) {
+    const space = body.indexOf(" ", start);
+    start = space === -1 || space >= at ? start : space + 1;
+  }
+  let end = Math.min(body.length, start + EXCERPT_WIDTH);
+  if (end < body.length) {
+    const space = body.lastIndexOf(" ", end);
+    if (space > start) {
+      end = space;
+    }
+  }
+  return `${start > 0 ? "…" : ""}${body.slice(start, end).trim()}${end < body.length ? "…" : ""}`;
+}
+
+/** Breadcrumb labels for a slug's ancestor segments: `framework/site/search` → `Framework › Site`. */
+export function crumbsFromSlug(slug: string): string[] {
+  return slug
+    .split("/")
+    .filter(Boolean)
+    .slice(0, -1)
+    .map((segment) =>
+      segment.replaceAll(/[-_]+/g, " ").replaceAll(/\b\p{Ll}/gu, (char) => char.toUpperCase()),
+    );
+}
 
 /** Override the default index URL for subsequent `preload()` calls. */
 export function configure(opts: { indexUrl?: string }): void {
@@ -99,24 +300,53 @@ export function preload(indexUrl?: string): Promise<void> {
   return state.loading;
 }
 
-/** Raw MiniSearch hit with our stored fields. */
+/** Raw MiniSearch hit with our stored fields and the terms it matched on. */
 interface RawHit {
   id: string;
   score: number;
+  terms: string[];
+  queryTerms: string[];
   collection: string;
   slug: string;
   url: string;
   title: string;
   description: string;
   heading: string;
+  text: string;
+  locale?: string;
+}
+
+/** Turn a raw hit into a presentation-ready row: breadcrumbs plus highlighted title and excerpt. */
+function toResult(hit: RawHit): SearchResult {
+  // `terms` holds the matched document words, so a prefix or fuzzy search highlights the whole
+  // `word` it landed on; `queryTerms` holds what the user actually typed.
+  const terms = [...hit.terms, ...hit.queryTerms];
+  const crumbs = crumbsFromSlug(hit.slug);
+  if (hit.heading) {
+    crumbs.push(hit.title);
+  }
+  return {
+    collection: hit.collection,
+    crumbs,
+    description: hit.description,
+    excerptTokens: buildTokens(buildExcerpt(hit.text ?? "", terms), terms),
+    heading: hit.heading,
+    id: hit.id,
+    score: hit.score,
+    slug: hit.slug,
+    title: hit.title,
+    titleTokens: buildTokens(hit.heading || hit.title, terms),
+    url: hit.url,
+  };
 }
 
 /**
  * Search synchronously. Returns `[]` until `preload` completes (and kicks it off if nobody has).
  * With `group: true` (default), section hits nest under their page, groups sorted by best score;
- * `group: false` returns the flat scored documents.
+ * `group: false` returns flat `SearchResult` rows — one per matching page or section, at most
+ * `pageCap` from any one page.
  */
-export function query(q: string, opts: QueryOptions = {}): SearchResultGroup[] | RawHit[] {
+export function query(q: string, opts: QueryOptions = {}): SearchResultGroup[] | SearchResult[] {
   const limit = opts.limit ?? 8;
   const group = opts.group ?? true;
   if (!state.mini) {
@@ -127,14 +357,37 @@ export function query(q: string, opts: QueryOptions = {}): SearchResultGroup[] |
   if (!text) {
     return [];
   }
-  const raw = state.mini.search(text) as unknown as RawHit[];
+  /*
+   * Scoped to the page's language unless the caller says otherwise. A multilingual site's index
+   * holds every translation of every post, so an unscoped search hands a French reader the English
+   * copy of the page they are already on — ranked first, because it matched the same words.
+   */
+  const want = opts.locale === undefined ? pageLocale() : (opts.locale ?? "");
+  const raw = (state.mini.search(text) as unknown as RawHit[]).filter((hit) =>
+    localeAnswers(hit.locale, want),
+  );
   if (!group) {
-    return raw.slice(0, limit);
+    const pageCap = opts.pageCap ?? PAGE_CAP;
+    const perPage = new Map<string, number>();
+    const rows: SearchResult[] = [];
+    for (const hit of raw) {
+      if (rows.length >= limit) {
+        break;
+      }
+      const key = pageKey(hit);
+      const taken = perPage.get(key) ?? 0;
+      if (taken >= pageCap) {
+        continue;
+      }
+      perPage.set(key, taken + 1);
+      rows.push(toResult(hit));
+    }
+    return rows;
   }
 
   const groups = new Map<string, SearchResultGroup>();
   for (const hit of raw) {
-    const key = `${hit.collection}:${hit.slug}`;
+    const key = pageKey(hit);
     let entry = groups.get(key);
     if (!entry) {
       entry = {
@@ -174,22 +427,26 @@ export function searchInit(componentState: Record<string, unknown>): boolean {
   return true;
 }
 
+/** Rows a `$src` component search shows at once. */
+const UI_LIMIT = 20;
+
 /**
  * State-convention query handler for `$src` component use: reads the query from the input event (or
- * `state.searchQuery`), stores grouped results on `state.searchResults`, and resets the active-row
- * index.
+ * `state.searchQuery`), stores flat highlighted rows on `state.searchResults`, publishes the row
+ * count as `state.searchCount`, and resets the active-row index.
  */
 export function runSearch(
   componentState: Record<string, unknown>,
   event?: { target?: { value?: unknown } | null },
-): unknown[] {
+): SearchResult[] {
   const fromEvent =
     event?.target && typeof event.target.value === "string" ? event.target.value : null;
   const q =
     fromEvent ?? (typeof componentState.searchQuery === "string" ? componentState.searchQuery : "");
   componentState.searchQuery = q;
-  const results = query(q);
+  const results = query(q, { group: false, limit: UI_LIMIT }) as SearchResult[];
   componentState.searchResults = results;
+  componentState.searchCount = results.length;
   componentState.searchActive = 0;
   return results;
 }

package/src/search-index.ts

@@ -10,9 +10,10 @@
  * @docs extending/extensions/search
  */
 
+import { canonicalizeLocale, localeUrlPrefix, resolveI18n } from "@jxsuite/schema/locale";
 import { entryUrl, jxTreeToText, normalizeSearchConfig, splitSections } from "./shared.ts";
 import type { NormalizedSearchConfig } from "./shared.ts";
-import type { ContentLoaderEntry, JxElement } from "@jxsuite/schema/types";
+import type { ContentLoaderEntry, JxElement, ProjectConfig } from "@jxsuite/schema/types";
 
 /** One searchable document in the emitted index. */
 export interface SearchDocument {
@@ -29,6 +30,12 @@ export interface SearchDocument {
   /** Section heading text; empty for page-level documents. */
   heading: string;
   text: string;
+  /**
+   * The entry's language, present only for a collection spread over one directory per locale
+   * (site-architecture.md §13.3). Absent means "every language" — an unlocalized collection is not
+   * in one language, it is outside the question.
+   */
+  locale?: string;
 }
 
 /** The emitted index file: engine-tagged envelope around the document list. */
@@ -66,6 +73,13 @@ export const SearchIndex = {
     const config = normalizeSearchConfig(sectionValue);
     const content = ctx.sections?.content as Map<string, ContentLoaderEntry[]> | undefined;
     const trailingSlash = ctx.projectConfig?.build?.trailingSlash ?? "always";
+    /*
+     * A localized entry lives at a locale-prefixed URL, and the index is the only place that knew
+     * the entry without knowing the prefix: every French post was indexed at the English post's
+     * URL, so a reader who searched in French was sent to the English page. The prefix is the
+     * routing rule, read from the same resolver the build reads.
+     */
+    const { i18n } = resolveI18n((ctx.projectConfig ?? {}) as ProjectConfig);
 
     const documents: SearchDocument[] = [];
     const fields = new Set<string>();
@@ -86,13 +100,31 @@ export const SearchIndex = {
 
       for (const entry of entries) {
         const data = (entry.data ?? {}) as Record<string, unknown>;
-        const url = entryUrl(collection.basePath, entry.id, trailingSlash);
+        /*
+         * Only when the project declares locales. An entry cannot carry one otherwise — the loader
+         * stamps it while expanding `{locale}`, which needs a list to expand over — and a stray tag
+         * would make the client filter results away for a language the site does not have.
+         */
+        const locale =
+          i18n === null ? undefined : (canonicalizeLocale(entry._meta?.locale) ?? undefined);
+        const url = entryUrl(
+          `${localeUrlPrefix(locale, i18n)}${collection.basePath}`,
+          entry.id,
+          trailingSlash,
+        );
         const title = typeof data.title === "string" ? data.title : entry.id;
         const description = typeof data.description === "string" ? data.description : "";
         const children = entry.$children as (JxElement | string)[] | undefined;
+        /*
+         * Two translations of one post share an id (§13.3), so the document id has to carry the
+         * locale as well — without it the French entry and the English one are one document and
+         * whichever is indexed second wins.
+         */
+        const documentId =
+          locale === undefined ? `${name}:${entry.id}` : `${name}:${locale}:${entry.id}`;
 
         documents.push({
-          id: `${name}:${entry.id}`,
+          id: documentId,
           collection: name,
           slug: entry.id,
           url,
@@ -100,12 +132,13 @@ export const SearchIndex = {
           description,
           heading: "",
           text: jxTreeToText(children),
+          ...(locale === undefined ? {} : { locale }),
         });
 
         if (collection.sections) {
           for (const section of splitSections(children, collection.sectionDepth)) {
             documents.push({
-              id: `${name}:${entry.id}#${section.anchor}`,
+              id: `${documentId}#${section.anchor}`,
               collection: name,
               slug: entry.id,
               url: `${url}#${section.anchor}`,
@@ -113,6 +146,7 @@ export const SearchIndex = {
               description,
               heading: section.heading,
               text: section.text,
+              ...(locale === undefined ? {} : { locale }),
             });
           }
         }

package/src/search-state.ts

@@ -32,6 +32,12 @@ export interface SearchDef {
   group?: boolean;
   /** Override the index URL (defaults to the project's `search.output`). */
   index?: string;
+  /**
+   * Language to search in. Omitted, the client uses the page's own — `<html lang>`, which the build
+   * wrote from the route's locale — so a search box needs no configuration to stop handing a French
+   * reader the English copy of the page they are on. `null` searches every language.
+   */
+  locale?: string | null;
   default?: unknown;
   [key: string]: unknown;
 }
@@ -75,13 +81,17 @@ export class Search {
     const clientUrl = sidecarAssetPath(CLIENT_SPECIFIER);
     const client = (await import(clientUrl)) as {
       preload: (url?: string) => Promise<void>;
-      query: (q: string, opts?: { limit?: number; group?: boolean }) => unknown;
+      query: (
+        q: string,
+        opts?: { limit?: number; group?: boolean; locale?: string | null },
+      ) => unknown;
     };
     await client.preload(this.indexUrl());
     const query = typeof this.config.query === "string" ? this.config.query : "";
     return client.query(query, {
       group: this.config.group ?? true,
       limit: this.config.limit ?? 8,
+      ...(this.config.locale === undefined ? {} : { locale: this.config.locale }),
     });
   }
 
@@ -98,7 +108,16 @@ export class Search {
   static lower(def: SearchDef, context: LowerContext = {}): Record<string, unknown> {
     const indexUrl = def.index ?? context.projectConfig?.search?.output ?? "/search-index.json";
     const clientUrl = sidecarAssetPath(CLIENT_SPECIFIER);
-    const opts = JSON.stringify({ group: def.group ?? true, limit: def.limit ?? 8 });
+    /*
+     * `locale` is passed only when the def names one. Omitting the key is not the same as passing
+     * `undefined` through JSON — the client reads "absent" as "the page's own language", which is
+     * the default a search box should have and the one nobody has to configure.
+     */
+    const opts = JSON.stringify({
+      group: def.group ?? true,
+      limit: def.limit ?? 8,
+      ...(def.locale === undefined ? {} : { locale: def.locale }),
+    });
     const body = [
       // Reading the ready flag makes the computed re-run when the client finishes loading.
       "void state.__jxSearchReady;",

package/src/shared.ts

@@ -7,6 +7,7 @@
  */
 
 import type { JxElement } from "@jxsuite/schema/types";
+import { displayTagName } from "@jxsuite/schema/guards";
 
 /** One collection's index configuration inside the `search` project section. */
 export interface SearchCollectionConfig {
@@ -159,7 +160,7 @@ function headingOf(
   if (typeof node !== "object" || node === null || !node.tagName) {
     return null;
   }
-  const match = HEADING_TAG.exec(node.tagName);
+  const match = HEADING_TAG.exec(displayTagName(node.tagName));
   if (!match) {
     return null;
   }