@jxsuite/search 0.1.0

package/dist/search-index.js

@@ -0,0 +1,165 @@
+// 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 collections = {};
+  for (const [name, raw] of Object.entries(section.collections ?? {})) {
+    collections[name] = {
+      basePath: normalizeBasePath(raw.basePath ?? "/"),
+      boost: raw.boost ?? {},
+      fields: raw.fields ?? DEFAULT_FIELDS,
+      sectionDepth: raw.sectionDepth ?? DEFAULT_SECTION_DEPTH,
+      sections: raw.sections ?? true
+    };
+  }
+  return {
+    engine: section.engine ?? "minisearch",
+    output: section.output ?? DEFAULT_OUTPUT,
+    collections
+  };
+}
+function normalizeBasePath(basePath) {
+  let path = basePath.startsWith("/") ? basePath : `/${basePath}`;
+  if (!path.endsWith("/")) {
+    path = `${path}/`;
+  }
+  return path;
+}
+function entryUrl(basePath, id, trailingSlash) {
+  const base = `${basePath}${id.replace(/^\//, "")}`;
+  return trailingSlash === "never" ? base : `${base}/`;
+}
+function jxTreeToText(children) {
+  return collectText(children).join(" ").replaceAll(/\s+/g, " ").trim();
+}
+function collectText(children) {
+  const parts = [];
+  for (const node of children ?? []) {
+    if (typeof node === "string") {
+      parts.push(node);
+      continue;
+    }
+    if (typeof node !== "object" || node === null) {
+      continue;
+    }
+    if (typeof node.textContent === "string") {
+      parts.push(node.textContent);
+    }
+    if (Array.isArray(node.children)) {
+      parts.push(...collectText(node.children));
+    }
+  }
+  return parts;
+}
+var HEADING_TAG = /^h([1-6])$/;
+function splitSections(children, sectionDepth) {
+  const sections = [];
+  let current = null;
+  for (const node of children ?? []) {
+    const heading = headingOf(node);
+    if (heading && heading.depth <= sectionDepth && heading.anchor) {
+      if (current) {
+        sections.push(finishSection(current));
+      }
+      current = { ...heading, parts: [], text: "" };
+      continue;
+    }
+    if (current && typeof node === "string") {
+      current.parts.push(node);
+    } else if (current && typeof node === "object" && node !== null) {
+      current.parts.push(jxTreeToText([node]));
+    }
+  }
+  if (current) {
+    sections.push(finishSection(current));
+  }
+  return sections;
+}
+function finishSection(section) {
+  const { heading, anchor, depth } = section;
+  return { anchor, depth, heading, text: section.parts.join(" ").replaceAll(/\s+/g, " ").trim() };
+}
+function headingOf(node) {
+  if (typeof node !== "object" || node === null || !node.tagName) {
+    return null;
+  }
+  const match = HEADING_TAG.exec(node.tagName);
+  if (!match) {
+    return null;
+  }
+  return {
+    anchor: typeof node.id === "string" ? node.id : "",
+    depth: Number(match[1]),
+    heading: jxTreeToText([node])
+  };
+}
+
+// src/search-index.ts
+var SearchIndex = {
+  projectData(sectionValue) {
+    return normalizeSearchConfig(sectionValue);
+  },
+  emit(sectionValue, ctx) {
+    const config = normalizeSearchConfig(sectionValue);
+    const content = ctx.sections?.content;
+    const trailingSlash = ctx.projectConfig?.build?.trailingSlash ?? "always";
+    const documents = [];
+    const fields = new Set;
+    const boost = {};
+    for (const [name, collection] of Object.entries(config.collections)) {
+      const entries = content?.get(name);
+      if (!entries) {
+        console.warn(`@jxsuite/search: collection "${name}" is not a loaded content collection — skipped`);
+        continue;
+      }
+      for (const field of collection.fields) {
+        fields.add(field);
+      }
+      Object.assign(boost, collection.boost);
+      for (const entry of entries) {
+        const data = entry.data ?? {};
+        const url = entryUrl(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;
+        documents.push({
+          id: `${name}:${entry.id}`,
+          collection: name,
+          slug: entry.id,
+          url,
+          title,
+          description,
+          heading: "",
+          text: jxTreeToText(children)
+        });
+        if (collection.sections) {
+          for (const section of splitSections(children, collection.sectionDepth)) {
+            documents.push({
+              id: `${name}:${entry.id}#${section.anchor}`,
+              collection: name,
+              slug: entry.id,
+              url: `${url}#${section.anchor}`,
+              title,
+              description,
+              heading: section.heading,
+              text: section.text
+            });
+          }
+        }
+      }
+    }
+    const envelope = {
+      version: 1,
+      engine: config.engine,
+      fields: [...fields],
+      boost,
+      documents
+    };
+    return [{ path: config.output, content: JSON.stringify(envelope) }];
+  }
+};
+export {
+  SearchIndex
+};

package/dist/search-state.js

@@ -0,0 +1,82 @@
+// ../../packages/schema/src/asset-paths.ts
+var NPM_SPECIFIER_PREFIX = "npm:";
+var SIDECAR_ASSET_DIR = "/assets/";
+function isNpmSpecifier(specifier) {
+  return specifier.startsWith(NPM_SPECIFIER_PREFIX);
+}
+function sidecarAssetPath(specifier) {
+  let base = specifier;
+  if (isNpmSpecifier(base)) {
+    base = base.slice(NPM_SPECIFIER_PREFIX.length);
+  }
+  base = base.replace(/^\.\//, "").replace(/\.(js|ts|mjs|mts)$/, "").replaceAll("@", "").replaceAll(/[/\\]+/g, "-").replaceAll(/[^\w.-]/g, "-").replaceAll(/-+/g, "-").replaceAll(/^-|-$/g, "");
+  return `${SIDECAR_ASSET_DIR}${base}.js`;
+}
+
+// src/search-state.ts
+var CLIENT_SPECIFIER = "npm:@jxsuite/search/client";
+function inBrowser() {
+  return typeof document !== "undefined" && typeof fetch === "function";
+}
+function queryExpression(query) {
+  if (typeof query === "object" && query !== null && typeof query.$ref === "string") {
+    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 : "");
+}
+
+class Search {
+  config;
+  constructor(config) {
+    this.config = config;
+  }
+  async resolve() {
+    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);
+    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
+    });
+  }
+  indexUrl() {
+    return this.config.index ?? this.config._project?.search?.output ?? "/search-index.json";
+  }
+  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 body = [
+      "void state.__jxSearchReady;",
+      "if (!globalThis.__jxSearch) {",
+      "  globalThis.__jxSearch = {};",
+      `  import(${JSON.stringify(clientUrl)})`,
+      `    .then((m) => { globalThis.__jxSearch.m = m; return m.preload(${JSON.stringify(indexUrl)}); })`,
+      "    .then(() => { state.__jxSearchReady = true; })",
+      "    .catch((err) => console.warn('search client failed to load:', err));",
+      "}",
+      "const m = globalThis.__jxSearch.m;",
+      `return m && m.isReady() ? m.query(${queryExpression(def.query)}, ${opts}) : [];`
+    ].join(`
+`);
+    return {
+      $bundle: [CLIENT_SPECIFIER],
+      $prototype: "Function",
+      body,
+      timing: "client",
+      ...def.default === undefined ? {} : { default: def.default }
+    };
+  }
+}
+export {
+  Search,
+  CLIENT_SPECIFIER
+};

package/jx-extension.json

@@ -0,0 +1,12 @@
+{
+  "name": "@jxsuite/search",
+  "title": "Search",
+  "description": "Build-time search index emission from content collections (MiniSearch) with section-level deep links and a headless browser client",
+  "classes": {
+    "SearchIndex": "./src/SearchIndex.class.json",
+    "Search": "./src/Search.class.json"
+  },
+  "schemas": {
+    "project": "./schemas/project.fragment.schema.json"
+  }
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@jxsuite/search",
+  "version": "0.1.0",
+  "description": "Static site search for Jx: build-time index emission from content collections and a headless MiniSearch browser client",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jxsuite/jx.git",
+    "directory": "extensions/search"
+  },
+  "files": [
+    "src/",
+    "dist",
+    "jx-extension.json",
+    "schemas/"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/search-index.ts",
+    "./client": "./src/client.ts",
+    "./search-state": "./src/search-state.ts",
+    "./shared": "./src/shared.ts",
+    "./jx-extension.json": "./jx-extension.json",
+    "./schemas/project.fragment.schema.json": "./schemas/project.fragment.schema.json",
+    "./SearchIndex.class.json": "./src/SearchIndex.class.json",
+    "./Search.class.json": "./src/Search.class.json"
+  },
+  "publishConfig": {
+    "provenance": false
+  },
+  "scripts": {
+    "prepare": "bun build src/search-index.ts src/search-state.ts --outdir=dist --format=esm --target=node",
+    "build": "bun run prepare",
+    "test": "bun test --isolate",
+    "test:coverage": "bun test --isolate --coverage",
+    "upgrade": "bunx npm-check-updates -u && bun install"
+  },
+  "dependencies": {
+    "@jxsuite/schema": "workspace:^",
+    "minisearch": "^7.2.0"
+  },
+  "devDependencies": {
+    "ajv": "^8.20.0"
+  },
+  "jx": "./jx-extension.json"
+}

package/schemas/project.fragment.schema.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jxsuite.com/schema/ext/search/project/v1",
+  "title": "Jx search section",
+  "description": "Site search: which content collections to index at build time and where the index is emitted",
+  "type": "object",
+  "properties": {
+    "search": {
+      "type": "object",
+      "description": "Build-time search index configuration (@jxsuite/search)",
+      "properties": {
+        "engine": {
+          "type": "string",
+          "enum": ["minisearch"],
+          "default": "minisearch",
+          "description": "Client search engine the emitted index targets"
+        },
+        "output": {
+          "type": "string",
+          "default": "/search-index.json",
+          "description": "Site-relative path of the emitted index file"
+        },
+        "collections": {
+          "type": "object",
+          "description": "Content collections to index, keyed by collection name",
+          "minProperties": 1,
+          "additionalProperties": {
+            "type": "object",
+            "properties": {
+              "basePath": {
+                "type": "string",
+                "description": "URL prefix mapping entry ids to routes, e.g. \"/docs/\""
+              },
+              "fields": {
+                "type": "array",
+                "items": { "type": "string" },
+                "default": ["title", "heading", "text"],
+                "description": "Document fields the index searches"
+              },
+              "boost": {
+                "type": "object",
+                "additionalProperties": { "type": "number" },
+                "description": "Per-field score boosts, e.g. { \"title\": 4, \"heading\": 2 }"
+              },
+              "sections": {
+                "type": "boolean",
+                "default": true,
+                "description": "Also index one document per heading section with #anchor deep links"
+              },
+              "sectionDepth": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 6,
+                "default": 3,
+                "description": "Deepest heading level that starts its own section document"
+              }
+            },
+            "required": ["basePath"],
+            "additionalProperties": false
+          }
+        }
+      },
+      "required": ["collections"],
+      "additionalProperties": false
+    }
+  }
+}

package/src/Search.class.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jxsuite.com/schemas/search/Search.class.json",
+  "title": "Search",
+  "description": "Reactive site-search results for a query — lazily loads the bundled headless client in browsers and lowers to a core Function computed in compiled sites",
+  "$prototype": "Class",
+  "extends": "Object",
+  "$implementation": "./search-state.js",
+
+  "$studio": {
+    "stateDefaults": { "timing": "client" }
+  },
+
+  "$defs": {
+    "parameters": {
+      "query": {
+        "identifier": "query",
+        "type": { "type": "string" },
+        "description": "Query text: a literal string or a $ref into page state (e.g. #/state/q)"
+      },
+      "limit": {
+        "identifier": "limit",
+        "type": { "type": "integer", "default": 8 },
+        "description": "Maximum result groups returned"
+      },
+      "group": {
+        "identifier": "group",
+        "type": { "type": "boolean", "default": true },
+        "description": "Group section hits under their page"
+      },
+      "index": {
+        "identifier": "index",
+        "type": { "type": "string" },
+        "description": "Index URL override (defaults to the project's search.output)"
+      }
+    },
+    "constructor": {
+      "role": "constructor",
+      "parameters": [
+        { "$ref": "#/$defs/parameters/query" },
+        { "$ref": "#/$defs/parameters/limit" },
+        { "$ref": "#/$defs/parameters/group" },
+        { "$ref": "#/$defs/parameters/index" }
+      ],
+      "body": ["this.config = config;"]
+    },
+    "methods": {
+      "resolve": {
+        "role": "method",
+        "scope": "instance",
+        "identifier": "resolve",
+        "returnType": { "type": "array" },
+        "description": "Grouped search results for the configured query (browser only; [] under node)"
+      },
+      "lower": {
+        "role": "lower",
+        "$prototype": "Function",
+        "access": "public",
+        "scope": "static",
+        "identifier": "lower",
+        "timing": ["compiler"],
+        "parameters": [
+          { "identifier": "def", "type": { "type": "object" } },
+          { "identifier": "context", "type": { "type": "object" } }
+        ],
+        "returnType": { "type": "object" },
+        "description": "Rewrite into a core Function computed that lazy-imports the bundled client, preloads the index, and queries reactively; registers the client bundle via $bundle"
+      }
+    }
+  }
+}

package/src/SearchIndex.class.json

@@ -0,0 +1,95 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jxsuite.com/schemas/search/SearchIndex.class.json",
+  "title": "SearchIndex",
+  "description": "Search project section for Jx: normalizes the project.json `search` section into _project.search and emits the site's search index into the build output",
+  "$prototype": "Class",
+  "extends": "Object",
+  "$implementation": "./search-index.js",
+
+  "project": {
+    "key": "search",
+    "title": "Site Search",
+    "description": "Build-time search index generated from content collections"
+  },
+
+  "$studio": {
+    "settings": {
+      "icon": "sp-icon-search",
+      "label": "Site Search",
+      "order": 70,
+      "layout": "form"
+    }
+  },
+
+  "$defs": {
+    "returnTypes": {
+      "NormalizedSearchConfig": {
+        "type": "object",
+        "description": "The search section with schema defaults applied (engine, output, per-collection fields/boost/sections)"
+      },
+      "EmitFiles": {
+        "type": "array",
+        "description": "One emitted file: the search-index JSON envelope at the configured output path",
+        "items": {
+          "type": "object",
+          "properties": {
+            "path": { "type": "string" },
+            "content": { "type": "string" }
+          },
+          "required": ["path", "content"]
+        }
+      }
+    },
+
+    "methods": {
+      "projectData": {
+        "role": "projectData",
+        "$prototype": "Function",
+        "access": "public",
+        "scope": "static",
+        "identifier": "projectData",
+        "timing": ["compiler", "server"],
+        "parameters": [
+          {
+            "identifier": "sectionValue",
+            "type": { "type": "object" },
+            "description": "The project.json `search` section value"
+          }
+        ],
+        "returnType": { "$ref": "#/$defs/returnTypes/NormalizedSearchConfig" },
+        "description": "Normalize the search section (defaults applied) into _project.search"
+      },
+      "emit": {
+        "role": "emit",
+        "$prototype": "Function",
+        "access": "public",
+        "scope": "static",
+        "identifier": "emit",
+        "timing": ["compiler"],
+        "parameters": [
+          {
+            "identifier": "sectionValue",
+            "type": { "type": "object" },
+            "description": "The project.json `search` section value"
+          },
+          {
+            "identifier": "ctx",
+            "type": {
+              "type": "object",
+              "properties": {
+                "projectConfig": { "type": "object" },
+                "root": { "type": "string" },
+                "sections": { "type": "object" },
+                "routes": { "type": "array" }
+              }
+            },
+            "description": "Host context: { projectConfig, root, sections, routes } (extensions.md §8.4)"
+          }
+        ],
+        "returnType": { "$ref": "#/$defs/returnTypes/EmitFiles" },
+        "description": "Build the search-index JSON from the loaded content collections; the host writes it into dist"
+      }
+    }
+  }
+}

package/src/client.ts

@@ -0,0 +1,195 @@
+/**
+ * Client — the headless browser search client.
+ *
+ * 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.
+ *
+ * Two integration surfaces: - `preload` / `isReady` / `query` — the core API (used by lowered
+ * `Search` defs). - `searchInit` / `runSearch` — state-convention helpers for `$src` use inside
+ * compiled components (export name = state key; spec.md §5.3).
+ *
+ * @docs framework/site/search
+ */
+
+import MiniSearch from "minisearch";
+import type { SearchDocument, SearchIndexEnvelope } from "./search-index.ts";
+
+/** One section hit inside a result group. */
+export interface SearchHit {
+  heading: string;
+  url: string;
+  score: number;
+}
+
+/** One result group: a page and its matching sections, best-score first. */
+export interface SearchResultGroup {
+  collection: string;
+  slug: string;
+  title: string;
+  description: string;
+  /** Page URL without a fragment. */
+  url: string;
+  /** Best score across the page and its section hits. */
+  score: number;
+  hits: SearchHit[];
+}
+
+/** Query options. */
+export interface QueryOptions {
+  /** Maximum result groups (default 8). */
+  limit?: number;
+  /** Group section hits under their page (default true); false returns flat documents. */
+  group?: boolean;
+}
+
+interface ClientState {
+  mini: MiniSearch<SearchDocument> | null;
+  loading: Promise<void> | null;
+  indexUrl: string;
+}
+
+const state: ClientState = { indexUrl: "/search-index.json", loading: null, mini: null };
+
+const STORE_FIELDS = ["collection", "slug", "url", "title", "description", "heading"];
+
+/** Override the default index URL for subsequent `preload()` calls. */
+export function configure(opts: { indexUrl?: string }): void {
+  if (opts.indexUrl) {
+    state.indexUrl = opts.indexUrl;
+  }
+}
+
+/** True once the index is fetched and built. */
+export function isReady(): boolean {
+  return state.mini !== null;
+}
+
+/**
+ * Fetch the index envelope and build the MiniSearch index. Memoized: concurrent and repeat calls
+ * share one load. A failed load clears the memo so a later call can retry.
+ */
+export function preload(indexUrl?: string): Promise<void> {
+  if (indexUrl) {
+    state.indexUrl = indexUrl;
+  }
+  state.loading ??= (async () => {
+    const response = await fetch(state.indexUrl);
+    if (!response.ok) {
+      throw new Error(`search index fetch failed: ${response.status} ${state.indexUrl}`);
+    }
+    const envelope = (await response.json()) as SearchIndexEnvelope;
+    const mini = new MiniSearch<SearchDocument>({
+      fields: envelope.fields,
+      searchOptions: {
+        boost: envelope.boost,
+        fuzzy: 0.2,
+        prefix: true,
+      },
+      storeFields: STORE_FIELDS,
+    });
+    mini.addAll(envelope.documents);
+    state.mini = mini;
+  })().catch((error: unknown) => {
+    state.loading = null;
+    throw error;
+  });
+  return state.loading;
+}
+
+/** Raw MiniSearch hit with our stored fields. */
+interface RawHit {
+  id: string;
+  score: number;
+  collection: string;
+  slug: string;
+  url: string;
+  title: string;
+  description: string;
+  heading: string;
+}
+
+/**
+ * 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.
+ */
+export function query(q: string, opts: QueryOptions = {}): SearchResultGroup[] | RawHit[] {
+  const limit = opts.limit ?? 8;
+  const group = opts.group ?? true;
+  if (!state.mini) {
+    void preload().catch(() => {});
+    return [];
+  }
+  const text = q.trim();
+  if (!text) {
+    return [];
+  }
+  const raw = state.mini.search(text) as unknown as RawHit[];
+  if (!group) {
+    return raw.slice(0, limit);
+  }
+
+  const groups = new Map<string, SearchResultGroup>();
+  for (const hit of raw) {
+    const key = `${hit.collection}:${hit.slug}`;
+    let entry = groups.get(key);
+    if (!entry) {
+      entry = {
+        collection: hit.collection,
+        description: hit.description,
+        hits: [],
+        score: hit.score,
+        slug: hit.slug,
+        title: hit.title,
+        url: hit.url.replace(/#.*$/, ""),
+      };
+      groups.set(key, entry);
+    }
+    entry.score = Math.max(entry.score, hit.score);
+    if (hit.heading) {
+      entry.hits.push({ heading: hit.heading, score: hit.score, url: hit.url });
+    }
+  }
+  return [...groups.values()].toSorted((a, b) => b.score - a.score).slice(0, limit);
+}
+
+/**
+ * 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,
+  )
+    .then(() => {
+      componentState.searchReady = true;
+      if (typeof componentState.searchQuery === "string" && componentState.searchQuery) {
+        runSearch(componentState);
+      }
+    })
+    .catch((error: unknown) => console.warn("search client failed to load:", error));
+  return true;
+}
+
+/**
+ * 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.
+ */
+export function runSearch(
+  componentState: Record<string, unknown>,
+  event?: { target?: { value?: unknown } | null },
+): unknown[] {
+  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);
+  componentState.searchResults = results;
+  componentState.searchActive = 0;
+  return results;
+}

package/src/search-index.ts

@@ -0,0 +1,131 @@
+/**
+ * Search-index — the `search` project-section owner.
+ *
+ * `projectData` normalizes the section into `_project.search`; `emit` (extensions.md §8.4) builds
+ * the site's search index from the loaded content collections and returns it for the host to write
+ * into the build output. Documents come in two granularities: one per content entry (full text)
+ * and, when `sections` is on, one per heading section carrying a `#anchor` deep link (heading ids
+ * are assigned by the parser — parser.md §3.2).
+ *
+ * @docs extending/extensions/search
+ */
+
+import { entryUrl, jxTreeToText, normalizeSearchConfig, splitSections } from "./shared.ts";
+import type { NormalizedSearchConfig } from "./shared.ts";
+import type { ContentLoaderEntry, JxElement } from "@jxsuite/schema/types";
+
+/** One searchable document in the emitted index. */
+export interface SearchDocument {
+  /**
+   * Unique id: `<collection>:<entry-id>` for pages, `<collection>:<entry-id>#<anchor>` for
+   * sections.
+   */
+  id: string;
+  collection: string;
+  slug: string;
+  url: string;
+  title: string;
+  description: string;
+  /** Section heading text; empty for page-level documents. */
+  heading: string;
+  text: string;
+}
+
+/** The emitted index file: engine-tagged envelope around the document list. */
+export interface SearchIndexEnvelope {
+  version: 1;
+  engine: "minisearch";
+  /** Fields the client indexes (union across collections). */
+  fields: string[];
+  /** Per-field score boosts (merged across collections). */
+  boost: Record<string, number>;
+  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 `SearchIndex` capability surface. The extension host dispatches capability methods on the
+ * export named by the descriptor title (specs/extensions.md §6.1); a plain object serves the
+ * static-dispatch contract exactly like a class with static methods.
+ */
+export const SearchIndex = {
+  /** Normalize the `search` section into `_project.search` (defaults applied). */
+  projectData(sectionValue: unknown): NormalizedSearchConfig {
+    return normalizeSearchConfig(sectionValue);
+  },
+
+  /** Build the search index from the loaded content collections. */
+  emit(sectionValue: unknown, ctx: EmitContext): { path: string; content: string }[] {
+    const config = normalizeSearchConfig(sectionValue);
+    const content = ctx.sections?.content as Map<string, ContentLoaderEntry[]> | undefined;
+    const trailingSlash = ctx.projectConfig?.build?.trailingSlash ?? "always";
+
+    const documents: SearchDocument[] = [];
+    const fields = new Set<string>();
+    const boost: Record<string, number> = {};
+
+    for (const [name, collection] of Object.entries(config.collections)) {
+      const entries = content?.get(name);
+      if (!entries) {
+        console.warn(
+          `@jxsuite/search: collection "${name}" is not a loaded content collection — skipped`,
+        );
+        continue;
+      }
+      for (const field of collection.fields) {
+        fields.add(field);
+      }
+      Object.assign(boost, collection.boost);
+
+      for (const entry of entries) {
+        const data = (entry.data ?? {}) as Record<string, unknown>;
+        const url = entryUrl(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;
+
+        documents.push({
+          id: `${name}:${entry.id}`,
+          collection: name,
+          slug: entry.id,
+          url,
+          title,
+          description,
+          heading: "",
+          text: jxTreeToText(children),
+        });
+
+        if (collection.sections) {
+          for (const section of splitSections(children, collection.sectionDepth)) {
+            documents.push({
+              id: `${name}:${entry.id}#${section.anchor}`,
+              collection: name,
+              slug: entry.id,
+              url: `${url}#${section.anchor}`,
+              title,
+              description,
+              heading: section.heading,
+              text: section.text,
+            });
+          }
+        }
+      }
+    }
+
+    const envelope: SearchIndexEnvelope = {
+      version: 1,
+      engine: config.engine,
+      fields: [...fields],
+      boost,
+      documents,
+    };
+    return [{ path: config.output, content: JSON.stringify(envelope) }];
+  },
+};

package/src/search-state.ts

@@ -0,0 +1,123 @@
+/**
+ * Search-state — the `Search` state class.
+ *
+ * An ordinary external class (constructor + resolve) with a static `lower` capability
+ * (extensions.md §8.3). In browsers, resolve() lazily imports the bundled headless client and
+ * queries the emitted index. Under node (compiler-timing bakes, dev-server resolve proxy) it
+ * degrades to an empty result — search is a client-side interaction.
+ *
+ * Lowering: in compiled sites a `timing: "client"` Search def becomes a core `Function` computed
+ * that lazy-imports the client bundle, preloads the index once per page, and re-runs reactively
+ * when the query state or the ready flag changes. The client module itself reaches the browser
+ * through the sidecar bundler via the `$bundle` hint (spec.md §5.3).
+ *
+ * @docs extending/extensions/search
+ * @docs framework/site/search
+ */
+
+import { sidecarAssetPath } from "@jxsuite/schema/asset-paths";
+
+/** The npm specifier of the headless browser client, bundled by the site build. */
+export const CLIENT_SPECIFIER = "npm:@jxsuite/search/client";
+
+/** A `Search` state def as authored in page state. */
+export interface SearchDef {
+  $prototype?: string;
+  timing?: string;
+  /** Query text: a literal string or a `$ref` into page state. */
+  query?: string | { $ref: string };
+  /** Maximum result groups returned. */
+  limit?: number;
+  /** Group section hits under their page (default true). */
+  group?: boolean;
+  /** Override the index URL (defaults to the project's `search.output`). */
+  index?: string;
+  default?: unknown;
+  [key: string]: unknown;
+}
+
+/** The context object hosts pass to `lower(def, context)`. */
+export interface LowerContext {
+  projectConfig?: { search?: { output?: string } } & Record<string, unknown>;
+  root?: string;
+  route?: Record<string, unknown>;
+}
+
+/** True when running in a browser; node hosts degrade to empty results. */
+function inBrowser(): boolean {
+  return typeof document !== "undefined" && typeof fetch === "function";
+}
+
+/** 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") {
+    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 : "");
+}
+
+export class Search {
+  config: SearchDef & { _project?: { search?: { output?: string } } };
+
+  constructor(config: SearchDef) {
+    this.config = config;
+  }
+
+  /** Grouped search results for the configured query — browser only. */
+  async resolve(): Promise<unknown> {
+    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 }) => 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,
+    });
+  }
+
+  /** The index URL: def override, then the project's `search.output`, then the default. */
+  indexUrl(): string {
+    return this.config.index ?? this.config._project?.search?.output ?? "/search-index.json";
+  }
+
+  /**
+   * Static `lower` capability: compile away into a core Function computed that lazily loads the
+   * 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> {
+    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 body = [
+      // Reading the ready flag makes the computed re-run when the client finishes loading.
+      "void state.__jxSearchReady;",
+      "if (!globalThis.__jxSearch) {",
+      "  globalThis.__jxSearch = {};",
+      `  import(${JSON.stringify(clientUrl)})`,
+      `    .then((m) => { globalThis.__jxSearch.m = m; return m.preload(${JSON.stringify(indexUrl)}); })`,
+      "    .then(() => { state.__jxSearchReady = true; })",
+      "    .catch((err) => console.warn('search client failed to load:', err));",
+      "}",
+      "const m = globalThis.__jxSearch.m;",
+      `return m && m.isReady() ? m.query(${queryExpression(def.query)}, ${opts}) : [];`,
+    ].join("\n");
+    return {
+      $bundle: [CLIENT_SPECIFIER],
+      $prototype: "Function",
+      body,
+      timing: "client",
+      ...(def.default === undefined ? {} : { default: def.default }),
+    };
+  }
+}

package/src/shared.ts

@@ -0,0 +1,171 @@
+/**
+ * Shared — search section normalization and content-tree text extraction.
+ *
+ * Pure helpers used by the build-time emitter (search-index.ts) and tests. Browser-safe.
+ *
+ * @docs extending/extensions/search
+ */
+
+import type { JxElement } from "@jxsuite/schema/types";
+
+/** One collection's index configuration inside the `search` project section. */
+export interface SearchCollectionConfig {
+  /** URL prefix mapping entry ids to routes, e.g. `"/docs/"`. */
+  basePath: string;
+  /** Document fields the index searches. */
+  fields?: string[];
+  /** Per-field score boosts. */
+  boost?: Record<string, number>;
+  /** Also index one document per heading section. */
+  sections?: boolean;
+  /** Deepest heading level that starts its own section document. */
+  sectionDepth?: number;
+}
+
+/** The raw `search` project section (schemas/project.fragment.schema.json). */
+export interface SearchSection {
+  engine?: "minisearch";
+  output?: string;
+  collections?: Record<string, SearchCollectionConfig>;
+}
+
+/** A fully-defaulted collection config. */
+export type NormalizedCollectionConfig = Required<SearchCollectionConfig>;
+
+/** The normalized section, as stored in `_project.search` and consumed by `emit`. */
+export interface NormalizedSearchConfig {
+  engine: "minisearch";
+  output: string;
+  collections: Record<string, NormalizedCollectionConfig>;
+}
+
+export const DEFAULT_OUTPUT = "/search-index.json";
+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;
+  const collections: Record<string, NormalizedCollectionConfig> = {};
+  for (const [name, raw] of Object.entries(section.collections ?? {})) {
+    collections[name] = {
+      basePath: normalizeBasePath(raw.basePath ?? "/"),
+      boost: raw.boost ?? {},
+      fields: raw.fields ?? DEFAULT_FIELDS,
+      sectionDepth: raw.sectionDepth ?? DEFAULT_SECTION_DEPTH,
+      sections: raw.sections ?? true,
+    };
+  }
+  return {
+    engine: section.engine ?? "minisearch",
+    output: section.output ?? DEFAULT_OUTPUT,
+    collections,
+  };
+}
+
+/** Ensure a basePath starts and ends with `/`. */
+function normalizeBasePath(basePath: string): string {
+  let path = basePath.startsWith("/") ? basePath : `/${basePath}`;
+  if (!path.endsWith("/")) {
+    path = `${path}/`;
+  }
+  return path;
+}
+
+/** Route URL of a content entry: basePath + id, honoring the site's trailingSlash setting. */
+export function entryUrl(basePath: string, id: string, trailingSlash: string): string {
+  const base = `${basePath}${id.replace(/^\//, "")}`;
+  return trailingSlash === "never" ? base : `${base}/`;
+}
+
+/** Concatenated visible text of a Jx node tree, whitespace-collapsed. */
+export function jxTreeToText(children?: (JxElement | string)[]): string {
+  return collectText(children).join(" ").replaceAll(/\s+/g, " ").trim();
+}
+
+function collectText(children: (JxElement | string)[] | undefined): string[] {
+  const parts: string[] = [];
+  for (const node of children ?? []) {
+    if (typeof node === "string") {
+      parts.push(node);
+      continue;
+    }
+    if (typeof node !== "object" || node === null) {
+      continue;
+    }
+    if (typeof node.textContent === "string") {
+      parts.push(node.textContent);
+    }
+    if (Array.isArray(node.children)) {
+      parts.push(...collectText(node.children as (JxElement | string)[]));
+    }
+  }
+  return parts;
+}
+
+/** One heading-delimited slice of a content entry. */
+export interface ContentSection {
+  heading: string;
+  anchor: string;
+  depth: number;
+  text: string;
+}
+
+const HEADING_TAG = /^h([1-6])$/;
+
+/**
+ * Split a content entry's rendered tree into heading sections for section-level search documents. A
+ * heading of depth ≤ `sectionDepth` (with an assigned `id` — see parser.md §3.2) starts a section;
+ * its text runs until the next section-starting heading. Content before the first heading belongs
+ * to no section (the page-level document already indexes the full text). Deeper headings' text
+ * stays inside the enclosing section.
+ */
+export function splitSections(
+  children: (JxElement | string)[] | undefined,
+  sectionDepth: number,
+): ContentSection[] {
+  const sections: ContentSection[] = [];
+  let current: (ContentSection & { parts: string[] }) | null = null;
+
+  for (const node of children ?? []) {
+    const heading = headingOf(node);
+    if (heading && heading.depth <= sectionDepth && heading.anchor) {
+      if (current) {
+        sections.push(finishSection(current));
+      }
+      current = { ...heading, parts: [], text: "" };
+      continue;
+    }
+    if (current && typeof node === "string") {
+      current.parts.push(node);
+    } else if (current && typeof node === "object" && node !== null) {
+      current.parts.push(jxTreeToText([node]));
+    }
+  }
+  if (current) {
+    sections.push(finishSection(current));
+  }
+  return sections;
+}
+
+function finishSection(section: ContentSection & { parts: string[] }): ContentSection {
+  const { heading, anchor, depth } = section;
+  return { anchor, depth, heading, text: section.parts.join(" ").replaceAll(/\s+/g, " ").trim() };
+}
+
+function headingOf(
+  node: JxElement | string,
+): { heading: string; anchor: string; depth: number } | null {
+  if (typeof node !== "object" || node === null || !node.tagName) {
+    return null;
+  }
+  const match = HEADING_TAG.exec(node.tagName);
+  if (!match) {
+    return null;
+  }
+  return {
+    anchor: typeof node.id === "string" ? node.id : "",
+    depth: Number(match[1]),
+    heading: jxTreeToText([node]),
+  };
+}