@jxsuite/search 0.3.1 → 0.4.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Kevin Shenk
+Copyright (c) 2026 Avunu LLC and Jx Suite contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/dist/search-index.js

@@ -1,3 +1,68 @@
+// ../../packages/schema/src/guards.ts
+function isString(value) {
+  return typeof value === "string";
+}
+function isBoolean(value) {
+  return typeof value === "boolean";
+}
+function isFunction(value) {
+  return typeof value === "function";
+}
+function isNonNullObject(value) {
+  return typeof value === "object" && value !== null;
+}
+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 isPlainTagName(tagName) {
+  return typeof tagName === "string";
+}
+function isTagExpression(tagName) {
+  if (typeof tagName !== "object" || tagName === null || Array.isArray(tagName) || !isJsonObject(tagName.$expression)) {
+    return false;
+  }
+  const expression = tagName.$expression;
+  if (expression.operator === "?:") {
+    return typeof expression.value === "string" && typeof expression.initial === "string";
+  }
+  if (expression.operator === "switch") {
+    return isJsonObject(expression.cases) && Object.values(expression.cases).every((tag) => isString(tag)) && typeof expression.default === "string";
+  }
+  return false;
+}
+function tagNameCandidates(tagName) {
+  if (isPlainTagName(tagName)) {
+    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 isPlainTagName(tagName) ? tagName : tagNameCandidates(tagName).join("|");
+}
+
 // ../../packages/schema/src/locale.ts
 var RTL_SCRIPTS = new Set([
   "Adlm",
@@ -41,7 +106,7 @@ var RTL_SCRIPTS = new Set([
   "Yezi"
 ]);
 function canonicalizeLocale(tag) {
-  if (typeof tag !== "string" || tag.trim() === "") {
+  if (!isString(tag) || tag.trim() === "") {
     return null;
   }
   try {
@@ -54,7 +119,7 @@ var DEFAULT_ROUTING = "prefix-except-default";
 function resolveI18n(projectConfig) {
   const raw = projectConfig.i18n;
   const errors = [];
-  if (!raw || typeof raw !== "object") {
+  if (!isNonNullObject(raw)) {
     return { errors, i18n: null };
   }
   const declared = Array.isArray(raw.locales) ? raw.locales : [];
@@ -97,62 +162,12 @@ function localeUrlPrefix(locale, i18n) {
   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) {
-  if (!isJsonObject(tagName) || !isJsonObject(tagName.$expression)) {
-    return false;
-  }
-  const expression = tagName.$expression;
-  if (expression.operator === "?:") {
-    return typeof expression.value === "string" && typeof expression.initial === "string";
-  }
-  if (expression.operator === "switch") {
-    return isJsonObject(expression.cases) && Object.values(expression.cases).every((tag) => typeof tag === "string") && typeof expression.default === "string";
-  }
-  return false;
-}
-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"];
 var DEFAULT_SECTION_DEPTH = 3;
 function normalizeSearchConfig(sectionValue) {
-  const section = sectionValue ?? {};
+  const section = isJsonObject(sectionValue) ? sectionValue : {};
   const collections = {};
   for (const [name, raw] of Object.entries(section.collections ?? {})) {
     collections[name] = {
@@ -183,18 +198,30 @@ function entryUrl(basePath, id, trailingSlash) {
 function jxTreeToText(children) {
   return collectText(children).join(" ").replaceAll(/\s+/g, " ").trim();
 }
+var ENTITIES = new Map([
+  ["$", "$"],
+  ["&", "&"],
+  [">", ">"],
+  ["&lt;", "<"],
+  ["&quot;", '"']
+]);
+function innerHtmlText(html) {
+  return html.replaceAll(/<[^>]*>/g, " ").replaceAll(/&#36;|&amp;|&gt;|&lt;|&quot;/g, (entity) => ENTITIES.get(entity) ?? entity);
+}
 function collectText(children) {
   const parts = [];
   for (const node of children ?? []) {
-    if (typeof node === "string") {
+    if (isString(node)) {
       parts.push(node);
       continue;
     }
-    if (typeof node !== "object" || node === null) {
+    if (!isNonNullObject(node)) {
       continue;
     }
-    if (typeof node.textContent === "string") {
+    if (isString(node.textContent)) {
       parts.push(node.textContent);
+    } else if (isString(node.innerHTML)) {
+      parts.push(innerHtmlText(node.innerHTML));
     }
     if (Array.isArray(node.children)) {
       parts.push(...collectText(node.children));
@@ -217,9 +244,9 @@ function splitEntry(children, sectionDepth) {
       continue;
     }
     const parts = current ? current.parts : preambleParts;
-    if (typeof node === "string") {
+    if (isString(node)) {
       parts.push(node);
-    } else if (typeof node === "object" && node !== null) {
+    } else if (isNonNullObject(node)) {
       parts.push(jxTreeToText([node]));
     }
   }
@@ -236,7 +263,7 @@ function normalizeText(parts) {
   return parts.join(" ").replaceAll(/\s+/g, " ").trim();
 }
 function headingOf(node) {
-  if (typeof node !== "object" || node === null || !node.tagName) {
+  if (!isNonNullObject(node) || !node.tagName) {
     return null;
   }
   const match = HEADING_TAG.exec(displayTagName(node.tagName));
@@ -244,7 +271,7 @@ function headingOf(node) {
     return null;
   }
   return {
-    anchor: typeof node.id === "string" ? node.id : "",
+    anchor: isString(node.id) ? node.id : "",
     depth: Number(match[1]),
     heading: jxTreeToText([node])
   };
@@ -252,7 +279,7 @@ function headingOf(node) {
 
 // src/search-index.ts
 function isOptedOut(collection, entryId, value) {
-  if (value === undefined || typeof value === "boolean") {
+  if (value === undefined || isBoolean(value)) {
     return value === false;
   }
   console.warn(`@jxsuite/search: "${collection}/${entryId}" sets search to ${JSON.stringify(value)}; ` + `only the boolean false opts a page out of the index — it stays indexed`);
@@ -265,7 +292,8 @@ var SearchIndex = {
   emit(sectionValue, ctx) {
     const config = normalizeSearchConfig(sectionValue);
     const content = ctx.sections?.content;
-    const trailingSlash = ctx.projectConfig?.build?.trailingSlash ?? "always";
+    const trailingSlashSetting = ctx.projectConfig?.build?.trailingSlash;
+    const trailingSlash = isString(trailingSlashSetting) ? trailingSlashSetting : "always";
     const { i18n } = resolveI18n(ctx.projectConfig ?? {});
     const documents = [];
     const fields = new Set;
@@ -281,19 +309,20 @@ var SearchIndex = {
       }
       Object.assign(boost, collection.boost);
       for (const entry of entries) {
-        const data = entry.data ?? {};
+        const { data } = entry;
         if (isOptedOut(name, entry.id, data.search)) {
           continue;
         }
         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 stamped = entry._meta?.url;
+        const url = stamped !== undefined && stamped.startsWith("/") ? stamped : entryUrl(`${localeUrlPrefix(locale, i18n)}${collection.basePath}`, entry.id, trailingSlash);
+        const title = isString(data.title) ? data.title : entry.id;
+        const description = isString(data.description) ? data.description : "";
         const children = entry.$children;
         const documentId = locale === undefined ? `${name}:${entry.id}` : `${name}:${locale}:${entry.id}`;
         const split = collection.sections ? splitEntry(children, collection.sectionDepth) : undefined;
         const sections = split?.sections ?? [];
-        documents.push({
+        const page = {
           id: documentId,
           collection: name,
           slug: entry.id,
@@ -301,11 +330,14 @@ var SearchIndex = {
           title,
           description,
           heading: "",
-          text: sections.length > 0 && split ? split.preamble : jxTreeToText(children),
-          ...locale === undefined ? {} : { locale }
-        });
+          text: sections.length > 0 && split ? split.preamble : jxTreeToText(children)
+        };
+        if (locale !== undefined) {
+          page.locale = locale;
+        }
+        documents.push(page);
         for (const section of sections) {
-          documents.push({
+          const sectionDocument = {
             id: `${documentId}#${section.anchor}`,
             collection: name,
             slug: entry.id,
@@ -313,9 +345,12 @@ var SearchIndex = {
             title,
             description,
             heading: section.heading,
-            text: section.text,
-            ...locale === undefined ? {} : { locale }
-          });
+            text: section.text
+          };
+          if (locale !== undefined) {
+            sectionDocument.locale = locale;
+          }
+          documents.push(sectionDocument);
         }
       }
     }

package/dist/search-state.js

@@ -1,3 +1,68 @@
+// ../../packages/schema/src/guards.ts
+function isString(value) {
+  return typeof value === "string";
+}
+function isBoolean(value) {
+  return typeof value === "boolean";
+}
+function isFunction(value) {
+  return typeof value === "function";
+}
+function isNonNullObject(value) {
+  return typeof value === "object" && value !== null;
+}
+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 isPlainTagName(tagName) {
+  return typeof tagName === "string";
+}
+function isTagExpression(tagName) {
+  if (typeof tagName !== "object" || tagName === null || Array.isArray(tagName) || !isJsonObject(tagName.$expression)) {
+    return false;
+  }
+  const expression = tagName.$expression;
+  if (expression.operator === "?:") {
+    return typeof expression.value === "string" && typeof expression.initial === "string";
+  }
+  if (expression.operator === "switch") {
+    return isJsonObject(expression.cases) && Object.values(expression.cases).every((tag) => isString(tag)) && typeof expression.default === "string";
+  }
+  return false;
+}
+function tagNameCandidates(tagName) {
+  if (isPlainTagName(tagName)) {
+    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 isPlainTagName(tagName) ? tagName : tagNameCandidates(tagName).join("|");
+}
+
 // ../../packages/schema/src/asset-paths.ts
 var NPM_SPECIFIER_PREFIX = "npm:";
 var SIDECAR_ASSET_DIR = "/assets/";
@@ -17,16 +82,16 @@ var URL_TERMINATOR = String.raw`"'\s<>()\\`;
 // src/search-state.ts
 var CLIENT_SPECIFIER = "npm:@jxsuite/search/client";
 function inBrowser() {
-  return typeof document !== "undefined" && typeof fetch === "function";
+  return typeof document !== "undefined" && isFunction(globalThis.fetch);
 }
 function queryExpression(query) {
-  if (typeof query === "object" && query !== null && typeof query.$ref === "string") {
+  if (isNonNullObject(query) && isString(query.$ref)) {
     const path = query.$ref.replace(/^#\//, "").split("/");
     if (path[0] === "state" && path.length > 1) {
       return ["state", ...path.slice(1)].join(".");
     }
   }
-  return JSON.stringify(typeof query === "string" ? query : "");
+  return JSON.stringify(isString(query) ? query : "");
 }
 
 class Search {
@@ -42,12 +107,15 @@ class Search {
     const clientUrl = sidecarAssetPath(CLIENT_SPECIFIER);
     const client = await import(clientUrl);
     await client.preload(this.indexUrl());
-    const query = typeof this.config.query === "string" ? this.config.query : "";
-    return client.query(query, {
+    const query = isString(this.config.query) ? this.config.query : "";
+    const opts = {
       group: this.config.group ?? true,
-      limit: this.config.limit ?? 8,
-      ...this.config.locale === undefined ? {} : { locale: this.config.locale }
-    });
+      limit: this.config.limit ?? 8
+    };
+    if (this.config.locale !== undefined) {
+      opts.locale = this.config.locale;
+    }
+    return client.query(query, opts);
   }
   indexUrl() {
     return this.config.index ?? this.config._project?.search?.output ?? "/search-index.json";
@@ -55,11 +123,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,
-      ...def.locale === undefined ? {} : { locale: def.locale }
-    });
+    const queryOptions = { group: def.group ?? true, limit: def.limit ?? 8 };
+    if (def.locale !== undefined) {
+      queryOptions.locale = def.locale;
+    }
+    const opts = JSON.stringify(queryOptions);
     const body = [
       "void state.__jxSearchReady;",
       "if (!globalThis.__jxSearch) {",
@@ -73,13 +141,16 @@ class Search {
       `return m && m.isReady() ? m.query(${queryExpression(def.query)}, ${opts}) : [];`
     ].join(`
 `);
-    return {
+    const lowered = {
       $bundle: [CLIENT_SPECIFIER],
       $prototype: "Function",
       body,
-      timing: "client",
-      ...def.default === undefined ? {} : { default: def.default }
+      timing: "client"
     };
+    if (def.default !== undefined) {
+      lowered.default = def.default;
+    }
+    return lowered;
   }
 }
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/search",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Static site search for Jx: build-time index emission from content collections and a headless MiniSearch browser client",
   "license": "MIT",
   "repository": {
@@ -36,7 +36,7 @@
     "upgrade": "bun update --latest && bun install"
   },
   "dependencies": {
-    "@jxsuite/schema": "^2.3.0",
+    "@jxsuite/schema": "^4.0.0",
     "minisearch": "^7.2.0"
   },
   "devDependencies": {

package/src/client.ts

@@ -15,7 +15,10 @@
  * @docs framework/site/search
  */
 
+import { isString } from "@jxsuite/schema/guards";
+import type { JsonValue } from "@jxsuite/schema/types";
 import MiniSearch from "minisearch";
+import type { SearchResult as MiniSearchResult } from "minisearch";
 import type { SearchDocument, SearchIndexEnvelope } from "./search-index.ts";
 
 /** One section hit inside a result group. */
@@ -129,7 +132,7 @@ const STORE_FIELDS = [
  * @returns {string} The tag, or `""` off a document
  */
 function pageLocale(): string {
-  return globalThis.document?.documentElement?.lang ?? "";
+  return typeof document === "undefined" ? "" : document.documentElement.lang;
 }
 
 /**
@@ -289,6 +292,10 @@ export function preload(indexUrl?: string): Promise<void> {
     if (!response.ok) {
       throw new Error(`search index fetch failed: ${response.status} ${state.indexUrl}`);
     }
+    /*
+     * SAFETY: `state.indexUrl` names the file `SearchIndex.emit` wrote at build time, whose content
+     * is `JSON.stringify` of a SearchIndexEnvelope; the client reads no other index.
+     */
     const envelope = (await response.json()) as SearchIndexEnvelope;
     const mini = new MiniSearch<SearchDocument>({
       fields: envelope.fields,
@@ -308,7 +315,7 @@ export function preload(indexUrl?: string): Promise<void> {
      */
     await mini.addAllAsync(envelope.documents, { chunkSize: INDEX_CHUNK_SIZE });
     state.mini = mini;
-  })().catch((error: unknown) => {
+  })().catch((error) => {
     state.loading = null;
     throw error;
   });
@@ -316,18 +323,19 @@ export function preload(indexUrl?: string): Promise<void> {
 }
 
 /** Raw MiniSearch hit with our stored fields and the terms it matched on. */
-interface RawHit {
+interface RawHit extends MiniSearchResult {
   id: string;
-  score: number;
-  terms: string[];
-  queryTerms: string[];
   collection: string;
   slug: string;
   url: string;
   title: string;
   description: string;
   heading: string;
-  text: string;
+  /**
+   * Optional because it is read defensively: stored fields are copied from the fetched index JSON,
+   * and an excerpt of a missing body is simply empty.
+   */
+  text?: string;
   locale?: string;
 }
 
@@ -361,6 +369,9 @@ function toResult(hit: RawHit): SearchResult {
  * `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 & { group: false }): SearchResult[];
+export function query(q: string, opts?: QueryOptions & { group?: true }): SearchResultGroup[];
+export function query(q: string, opts?: QueryOptions): SearchResultGroup[] | SearchResult[];
 export function query(q: string, opts: QueryOptions = {}): SearchResultGroup[] | SearchResult[] {
   const limit = opts.limit ?? 8;
   const group = opts.group ?? true;
@@ -378,7 +389,14 @@ export function query(q: string, opts: QueryOptions = {}): SearchResultGroup[] |
    * 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) =>
+  /*
+   * SAFETY: MiniSearch copies every name in STORE_FIELDS from the indexed document onto its hit,
+   * and every document came from the emitted envelope, whose SearchDocuments carry collection,
+   * slug, url, title, description and heading as strings (`locale` and, read defensively, `text`
+   * are optional in RawHit). MiniSearch types the hit's `id` as `any`; it is the document's own
+   * `id`, which SearchDocument declares a string.
+   */
+  const raw = (state.mini.search(text) as RawHit[]).filter((hit) =>
     localeAnswers(hit.locale, want),
   );
   if (!group) {
@@ -424,21 +442,38 @@ export function query(q: string, opts: QueryOptions = {}): SearchResultGroup[] |
   return [...groups.values()].toSorted((a, b) => b.score - a.score).slice(0, limit);
 }
 
+/**
+ * The component state keys the `$src` conventions read and write. The two the author declares are
+ * document JSON, so each is honored only when it is a string.
+ */
+export interface SearchComponentState {
+  /** Index URL override for `preload`. */
+  searchIndexUrl?: JsonValue | undefined;
+  /** The query text; `runSearch` writes back the query it ran. */
+  searchQuery?: JsonValue | undefined;
+  /** Set true once the index is loaded. */
+  searchReady?: boolean;
+  /** The flat, highlighted rows of the last query. */
+  searchResults?: SearchResult[];
+  /** `searchResults.length`. */
+  searchCount?: number;
+  /** The active row index, reset to 0 by every query. */
+  searchActive?: number;
+}
+
 /**
  * State-convention init for `$src` component use: preload the index and flip `state.searchReady`;
  * re-runs the pending query once ready.
  */
-export function searchInit(componentState: Record<string, unknown>): boolean {
-  void preload(
-    typeof componentState.searchIndexUrl === "string" ? componentState.searchIndexUrl : undefined,
-  )
+export function searchInit(componentState: SearchComponentState): boolean {
+  void preload(isString(componentState.searchIndexUrl) ? componentState.searchIndexUrl : undefined)
     .then(() => {
       componentState.searchReady = true;
-      if (typeof componentState.searchQuery === "string" && componentState.searchQuery) {
+      if (isString(componentState.searchQuery) && componentState.searchQuery) {
         runSearch(componentState);
       }
     })
-    .catch((error: unknown) => console.warn("search client failed to load:", error));
+    .catch((error) => console.warn("search client failed to load:", error));
   return true;
 }
 
@@ -451,15 +486,13 @@ const UI_LIMIT = 20;
  * count as `state.searchCount`, and resets the active-row index.
  */
 export function runSearch(
-  componentState: Record<string, unknown>,
+  componentState: SearchComponentState,
   event?: { target?: { value?: unknown } | null },
 ): SearchResult[] {
-  const fromEvent =
-    event?.target && typeof event.target.value === "string" ? event.target.value : null;
-  const q =
-    fromEvent ?? (typeof componentState.searchQuery === "string" ? componentState.searchQuery : "");
+  const fromEvent = event?.target && isString(event.target.value) ? event.target.value : null;
+  const q = fromEvent ?? (isString(componentState.searchQuery) ? componentState.searchQuery : "");
   componentState.searchQuery = q;
-  const results = query(q, { group: false, limit: UI_LIMIT }) as SearchResult[];
+  const results = query(q, { group: false, limit: UI_LIMIT });
   componentState.searchResults = results;
   componentState.searchCount = results.length;
   componentState.searchActive = 0;

package/src/search-index.ts

@@ -11,10 +11,12 @@
  * @docs extending/extensions/search
  */
 
+import { isBoolean, isString } from "@jxsuite/schema/guards";
 import { canonicalizeLocale, localeUrlPrefix, resolveI18n } from "@jxsuite/schema/locale";
 import { entryUrl, jxTreeToText, normalizeSearchConfig, splitEntry } from "./shared.ts";
 import type { NormalizedSearchConfig } from "./shared.ts";
-import type { ContentLoaderEntry, JxElement, ProjectConfig } from "@jxsuite/schema/types";
+import type { EmitHostContext } from "@jxsuite/schema/format-registry";
+import type { ContentFieldValue, ContentLoaderEntry, JsonValue } from "@jxsuite/schema/types";
 
 /** One searchable document in the emitted index. */
 export interface SearchDocument {
@@ -50,13 +52,11 @@ export interface SearchIndexEnvelope {
   documents: SearchDocument[];
 }
 
-/** Host context passed to `emit` (extensions.md §8.4). */
-export interface EmitContext {
-  projectConfig?: { build?: { trailingSlash?: string } } & Record<string, unknown>;
-  root?: string;
-  sections?: Record<string, unknown>;
-  routes?: unknown[];
-}
+/**
+ * The host's `emit` context (extensions.md §8.4) as `SearchIndex.emit` accepts it: any part of
+ * {@link EmitHostContext}. The published name, kept for existing importers.
+ */
+export type EmitContext = Partial<EmitHostContext>;
 
 /**
  * Whether an entry's frontmatter keeps it out of the index (`search: false`).
@@ -73,8 +73,12 @@ export interface EmitContext {
  * INDEXED — the safe failure, because a page that is present can be found and a page that is absent
  * cannot say why — and reported once per entry, not once per document it yields.
  */
-function isOptedOut(collection: string, entryId: string, value: unknown): boolean {
-  if (value === undefined || typeof value === "boolean") {
+function isOptedOut(
+  collection: string,
+  entryId: string,
+  value: ContentFieldValue | undefined,
+): boolean {
+  if (value === undefined || isBoolean(value)) {
     return value === false;
   }
   console.warn(
@@ -91,22 +95,30 @@ function isOptedOut(collection: string, entryId: string, value: unknown): boolea
  */
 export const SearchIndex = {
   /** Normalize the `search` section into `_project.search` (defaults applied). */
-  projectData(sectionValue: unknown): NormalizedSearchConfig {
+  projectData(sectionValue: JsonValue | undefined): NormalizedSearchConfig {
     return normalizeSearchConfig(sectionValue);
   },
 
   /** Build the search index from the loaded content collections. */
-  emit(sectionValue: unknown, ctx: EmitContext): { path: string; content: string }[] {
+  emit(sectionValue: JsonValue | undefined, ctx: EmitContext): { path: string; content: string }[] {
     const config = normalizeSearchConfig(sectionValue);
+    /* SAFETY: the `content` section's owner (the parser's `Content.projectData`) answers a
+       Map of collection name to loaded entries (specs/extensions.md §8.4), and the host forwards
+       each section's answer unchanged. */
     const content = ctx.sections?.content as Map<string, ContentLoaderEntry[]> | undefined;
-    const trailingSlash = ctx.projectConfig?.build?.trailingSlash ?? "always";
+    /*
+     * `entryUrl` drops the trailing slash only for the exact string "never", so a setting that is
+     * absent or not a string means "always", which is the default.
+     */
+    const trailingSlashSetting = ctx.projectConfig?.build?.trailingSlash;
+    const trailingSlash = isString(trailingSlashSetting) ? trailingSlashSetting : "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 { i18n } = resolveI18n(ctx.projectConfig ?? {});
 
     const documents: SearchDocument[] = [];
     const fields = new Set<string>();
@@ -126,7 +138,7 @@ export const SearchIndex = {
       Object.assign(boost, collection.boost);
 
       for (const entry of entries) {
-        const data = (entry.data ?? {}) as Record<string, unknown>;
+        const { data } = entry;
         if (isOptedOut(name, entry.id, data.search)) {
           continue;
         }
@@ -137,14 +149,24 @@ export const SearchIndex = {
          */
         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;
+        /*
+         * An entry of a content type with a `route` carries its URL (`_meta.url`), stamped by the
+         * loader from the template its page and its links were generated from, so the index cannot
+         * point at a URL the site does not have. Only an entry with none is placed by the
+         * collection's `basePath` + id, the older, flat rule.
+         */
+        const stamped = entry._meta?.url;
+        const url =
+          stamped !== undefined && stamped.startsWith("/")
+            ? stamped
+            : entryUrl(
+                `${localeUrlPrefix(locale, i18n)}${collection.basePath}`,
+                entry.id,
+                trailingSlash,
+              );
+        const title = isString(data.title) ? data.title : entry.id;
+        const description = isString(data.description) ? data.description : "";
+        const children = entry.$children;
         /*
          * 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
@@ -167,7 +189,8 @@ export const SearchIndex = {
           : undefined;
         const sections = split?.sections ?? [];
 
-        documents.push({
+        // `locale` is the last key of every document, and present only for a localized entry.
+        const page: SearchDocument = {
           id: documentId,
           collection: name,
           slug: entry.id,
@@ -176,11 +199,14 @@ export const SearchIndex = {
           description,
           heading: "",
           text: sections.length > 0 && split ? split.preamble : jxTreeToText(children),
-          ...(locale === undefined ? {} : { locale }),
-        });
+        };
+        if (locale !== undefined) {
+          page.locale = locale;
+        }
+        documents.push(page);
 
         for (const section of sections) {
-          documents.push({
+          const sectionDocument: SearchDocument = {
             id: `${documentId}#${section.anchor}`,
             collection: name,
             slug: entry.id,
@@ -189,8 +215,11 @@ export const SearchIndex = {
             description,
             heading: section.heading,
             text: section.text,
-            ...(locale === undefined ? {} : { locale }),
-          });
+          };
+          if (locale !== undefined) {
+            sectionDocument.locale = locale;
+          }
+          documents.push(sectionDocument);
         }
       }
     }

package/src/search-state.ts

@@ -16,6 +16,10 @@
  */
 
 import { sidecarAssetPath } from "@jxsuite/schema/asset-paths";
+import { isFunction, isNonNullObject, isString } from "@jxsuite/schema/guards";
+import type { JsonValue } from "@jxsuite/schema/types";
+import type * as ClientModule from "./client.ts";
+import type { QueryOptions, SearchResult, SearchResultGroup } from "./client.ts";
 
 /** The npm specifier of the headless browser client, bundled by the site build. */
 export const CLIENT_SPECIFIER = "npm:@jxsuite/search/client";
@@ -38,31 +42,47 @@ export interface SearchDef {
    * reader the English copy of the page they are on. `null` searches every language.
    */
   locale?: string | null;
-  default?: unknown;
-  [key: string]: unknown;
+  default?: JsonValue;
+  /** Any other key an author wrote on the def: document JSON this class does not read. */
+  [key: string]: JsonValue | undefined;
 }
 
 /** The context object hosts pass to `lower(def, context)`. */
 export interface LowerContext {
-  projectConfig?: { search?: { output?: string } } & Record<string, unknown>;
+  /** The project config. `lower` reads only the raw `search` section's `output`. */
+  projectConfig?: { search?: { output?: string } };
   root?: string;
-  route?: Record<string, unknown>;
+  /** The route being compiled (prototype-resolver.ts passes its source path and path params). */
+  route?: { sourcePath?: string; _pathParams?: Record<string, string> };
 }
 
+/** The core `Function` def a `Search` def lowers into, plus the `$bundle` host hint. */
+export interface LoweredSearchDef {
+  /** Client modules the site build must bundle; the host strips the key after reading it. */
+  $bundle: string[];
+  $prototype: "Function";
+  body: string;
+  timing: "client";
+  default?: JsonValue;
+}
+
+/** The part of the bundled client module `resolve` calls. */
+type SearchClient = Pick<typeof ClientModule, "preload" | "query">;
+
 /** True when running in a browser; node hosts degrade to empty results. */
 function inBrowser(): boolean {
-  return typeof document !== "undefined" && typeof fetch === "function";
+  return typeof document !== "undefined" && isFunction(globalThis.fetch);
 }
 
 /** Compile a def's `query` into a client JS expression (`$ref` → state path, literal → string). */
 function queryExpression(query: SearchDef["query"]): string {
-  if (typeof query === "object" && query !== null && typeof query.$ref === "string") {
+  if (isNonNullObject(query) && isString(query.$ref)) {
     const path = query.$ref.replace(/^#\//, "").split("/");
     if (path[0] === "state" && path.length > 1) {
       return ["state", ...path.slice(1)].join(".");
     }
   }
-  return JSON.stringify(typeof query === "string" ? query : "");
+  return JSON.stringify(isString(query) ? query : "");
 }
 
 export class Search {
@@ -73,26 +93,28 @@ export class Search {
   }
 
   /** Grouped search results for the configured query — browser only. */
-  async resolve(): Promise<unknown> {
+  async resolve(): Promise<SearchResultGroup[] | SearchResult[]> {
     if (!inBrowser()) {
       console.warn("Search resolves to [] outside the browser — search is a client interaction");
       return [];
     }
     const clientUrl = sidecarAssetPath(CLIENT_SPECIFIER);
-    const client = (await import(clientUrl)) as {
-      preload: (url?: string) => Promise<void>;
-      query: (
-        q: string,
-        opts?: { limit?: number; group?: boolean; locale?: string | null },
-      ) => unknown;
-    };
+    /*
+     * SAFETY: `clientUrl` is the sidecar asset path of CLIENT_SPECIFIER, which the site build
+     * bundles from ./client.ts (the `$bundle` hint `lower` emits), so the module it serves exports
+     * that file's `preload` and `query`.
+     */
+    const client = (await import(clientUrl)) as SearchClient;
     await client.preload(this.indexUrl());
-    const query = typeof this.config.query === "string" ? this.config.query : "";
-    return client.query(query, {
+    const query = isString(this.config.query) ? this.config.query : "";
+    const opts: QueryOptions = {
       group: this.config.group ?? true,
       limit: this.config.limit ?? 8,
-      ...(this.config.locale === undefined ? {} : { locale: this.config.locale }),
-    });
+    };
+    if (this.config.locale !== undefined) {
+      opts.locale = this.config.locale;
+    }
+    return client.query(query, opts);
   }
 
   /** The index URL: def override, then the project's `search.output`, then the default. */
@@ -105,7 +127,7 @@ export class Search {
    * bundled client + index, then queries reactively. `$bundle` registers the client module with the
    * sidecar bundler (extensions.md §8.3).
    */
-  static lower(def: SearchDef, context: LowerContext = {}): Record<string, unknown> {
+  static lower(def: SearchDef, context: LowerContext = {}): LoweredSearchDef {
     const indexUrl = def.index ?? context.projectConfig?.search?.output ?? "/search-index.json";
     const clientUrl = sidecarAssetPath(CLIENT_SPECIFIER);
     /*
@@ -113,11 +135,11 @@ export class Search {
      * `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 queryOptions: QueryOptions = { group: def.group ?? true, limit: def.limit ?? 8 };
+    if (def.locale !== undefined) {
+      queryOptions.locale = def.locale;
+    }
+    const opts = JSON.stringify(queryOptions);
     const body = [
       // Reading the ready flag makes the computed re-run when the client finishes loading.
       "void state.__jxSearchReady;",
@@ -131,12 +153,15 @@ export class Search {
       "const m = globalThis.__jxSearch.m;",
       `return m && m.isReady() ? m.query(${queryExpression(def.query)}, ${opts}) : [];`,
     ].join("\n");
-    return {
+    const lowered: LoweredSearchDef = {
       $bundle: [CLIENT_SPECIFIER],
       $prototype: "Function",
       body,
       timing: "client",
-      ...(def.default === undefined ? {} : { default: def.default }),
     };
+    if (def.default !== undefined) {
+      lowered.default = def.default;
+    }
+    return lowered;
   }
 }

package/src/shared.ts

@@ -6,8 +6,8 @@
  * @docs extending/extensions/search
  */
 
-import type { JxElement } from "@jxsuite/schema/types";
-import { displayTagName } from "@jxsuite/schema/guards";
+import type { JsonValue, JxElement } from "@jxsuite/schema/types";
+import { displayTagName, isJsonObject, isNonNullObject, isString } from "@jxsuite/schema/guards";
 
 /** One collection's index configuration inside the `search` project section. */
 export interface SearchCollectionConfig {
@@ -23,11 +23,17 @@ export interface SearchCollectionConfig {
   sectionDepth?: number;
 }
 
-/** The raw `search` project section (schemas/project.fragment.schema.json). */
+/**
+ * The raw `search` project section (schemas/project.fragment.schema.json).
+ *
+ * A collection's members are all optional here, `basePath` included: the schema requires it, but
+ * this is the value before anything validated it, and {@link normalizeSearchConfig} defaults a
+ * missing one to `/` rather than rejecting it.
+ */
 export interface SearchSection {
   engine?: "minisearch";
   output?: string;
-  collections?: Record<string, SearchCollectionConfig>;
+  collections?: Record<string, Partial<SearchCollectionConfig>>;
 }
 
 /** A fully-defaulted collection config. */
@@ -45,8 +51,15 @@ export const DEFAULT_FIELDS = ["title", "heading", "text"];
 export const DEFAULT_SECTION_DEPTH = 3;
 
 /** Apply schema defaults to a raw `search` section value. */
-export function normalizeSearchConfig(sectionValue?: unknown): NormalizedSearchConfig {
-  const section = (sectionValue ?? {}) as SearchSection;
+export function normalizeSearchConfig(sectionValue?: JsonValue): NormalizedSearchConfig {
+  /*
+   * SAFETY: a JSON object here is the project's `search` section, whose member shapes
+   * schemas/project.fragment.schema.json defines and `jx validate` and the editor enforce. This
+   * normalizer only fills defaults for absent members; it never re-validates member types. Any
+   * other value (absent, null, a scalar, an array) has none of the section's members, so it reads
+   * as an empty section.
+   */
+  const section: SearchSection = isJsonObject(sectionValue) ? (sectionValue as SearchSection) : {};
   const collections: Record<string, NormalizedCollectionConfig> = {};
   for (const [name, raw] of Object.entries(section.collections ?? {})) {
     collections[name] = {
@@ -84,21 +97,49 @@ export function jxTreeToText(children?: (JxElement | string)[]): string {
   return collectText(children).join(" ").replaceAll(/\s+/g, " ").trim();
 }
 
+/** The five entities the parser's escaping and an author's markup commonly leave in `innerHTML`. */
+const ENTITIES = new Map<string, string>([
+  ["&#36;", "$"],
+  ["&amp;", "&"],
+  ["&gt;", ">"],
+  ["&lt;", "<"],
+  ["&quot;", '"'],
+]);
+
+/**
+ * The text of an `innerHTML` string: tags dropped, the common entities decoded.
+ *
+ * The content loader writes text that contains `${` as escaped `innerHTML` so the build does not
+ * read it as a template (parser.md §3.5), which means the words of a code sample live there and not
+ * in `textContent`. An index that skipped `innerHTML` would silently stop finding them.
+ */
+function innerHtmlText(html: string): string {
+  return html
+    .replaceAll(/<[^>]*>/g, " ")
+    .replaceAll(/&#36;|&amp;|&gt;|&lt;|&quot;/g, (entity) => ENTITIES.get(entity) ?? entity);
+}
+
 function collectText(children: (JxElement | string)[] | undefined): string[] {
   const parts: string[] = [];
   for (const node of children ?? []) {
-    if (typeof node === "string") {
+    if (isString(node)) {
       parts.push(node);
       continue;
     }
-    if (typeof node !== "object" || node === null) {
+    /*
+     * The tree is a format class's `load` output, which nothing validates: a `null` child in
+     * hand-written JSON is skipped rather than allowed to throw on the reads below.
+     */
+    if (!isNonNullObject(node)) {
       continue;
     }
-    if (typeof node.textContent === "string") {
+    if (isString(node.textContent)) {
       parts.push(node.textContent);
+    } else if (isString(node.innerHTML)) {
+      parts.push(innerHtmlText(node.innerHTML));
     }
     if (Array.isArray(node.children)) {
-      parts.push(...collectText(node.children as (JxElement | string)[]));
+      parts.push(...collectText(node.children));
     }
   }
   return parts;
@@ -150,9 +191,9 @@ export function splitEntry(
       continue;
     }
     const parts = current ? current.parts : preambleParts;
-    if (typeof node === "string") {
+    if (isString(node)) {
       parts.push(node);
-    } else if (typeof node === "object" && node !== null) {
+    } else if (isNonNullObject(node)) {
       parts.push(jxTreeToText([node]));
     }
   }
@@ -183,7 +224,7 @@ function normalizeText(parts: readonly string[]): string {
 function headingOf(
   node: JxElement | string,
 ): { heading: string; anchor: string; depth: number } | null {
-  if (typeof node !== "object" || node === null || !node.tagName) {
+  if (!isNonNullObject(node) || !node.tagName) {
     return null;
   }
   const match = HEADING_TAG.exec(displayTagName(node.tagName));
@@ -191,7 +232,7 @@ function headingOf(
     return null;
   }
   return {
-    anchor: typeof node.id === "string" ? node.id : "",
+    anchor: isString(node.id) ? node.id : "",
     depth: Number(match[1]),
     heading: jxTreeToText([node]),
   };