@xingwangzhe/stalux 1.46.5 → 1.47.0

package/README.md

@@ -142,6 +142,10 @@ The desktop tag cloud loads dynamically near the viewport. Switching to mobile,
 
 TypeScript uses ESNext. The theme defaults `vite.build.target` to `"esnext"` to retain modern syntax with minimal compatibility transforms; an explicit consumer target takes precedence. This targets modern browsers, does not polyfill missing Web APIs, and does not move ordinary scripts onto the GPU. Biome enforces `noVar` and `useConst` as errors in maintained source; dependencies and generated bundles are outside this source policy.
 
+### CJK search enhancement
+
+Builds generate both Pagefind and a sharded CJK substring index shared by the dialog and WebMCP. Titles, summaries, tags and categories are searchable. Optional post frontmatter `searchKeywords: [alias, abbreviation]` defaults to an empty array; keywords are published in HTML and static search files, so never put private information there. Unquoted Chinese, Japanese and Korean queries add verified contiguous substring matches, including single characters, NFKC normalization and space-separated terms. Title matches rank first; native results are retained and deduplicated. Quoted queries and active filters retain native Pagefind semantics. Automatic Traditional/Simplified conversion, pinyin, typo correction and semantic search are not included. Search files load on demand, failures fall back to Pagefind and can be retried, with no external search service or new telemetry.
+
 ### Initial CSS and search styles
 
 The theme defaults to Astro's `build.inlineStylesheets: "never"`: hashed shared CSS can be cached across routes, while component styles load on the pages that use them. Normal blocking stylesheets prevent an unstyled first paint. An explicit consumer setting of `build.inlineStylesheets: "always"` restores inline styles at the cost of larger HTML responses.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@xingwangzhe/stalux",
-    "version": "1.46.5",
+    "version": "1.47.0",
     "description": "A powerful, modern Astro blog theme — use as template or install as plugin",
     "keywords": [
         "astro",

package/src/components/stalux/common/search.astro

@@ -2,8 +2,10 @@
 // Pagefind component-ui search modal.
 // Docs: https://pagefind.app/llms-component-ui.txt
 // data-pf-theme must be on a DIRECT parent wrapper of the component.
+import { sitePath } from "../../../utils/site-path";
 ---
 
 <div data-pf-theme="dark">
+    <pagefind-config bundle-path={sitePath("pagefind-enhanced/")}></pagefind-config>
     <pagefind-modal id="search"></pagefind-modal>
 </div>

package/src/components/stalux/posts/ArticleSummary.astro

@@ -16,7 +16,14 @@ const summary = description?.trim();
         aria-label={label}
     >
         <p class="stalux-article-summary-label">{label}</p>
-        <p class="stalux-article-summary-text">{summary}</p>
+        <p
+            class="stalux-article-summary-text"
+            data-pagefind-body
+            data-pagefind-weight="2"
+            data-stalux-search-description
+        >
+            {summary}
+        </p>
     </aside>
 )}
 

package/src/components/stalux/posts/postContent.astro

@@ -13,6 +13,7 @@ interface Props {
     postId?: string | number;
     title: string;
     description?: string;
+    searchKeywords?: string[];
     transitionName?: string;
     titleTransitionName?: string;
     transitionScope?: "article" | "about";
@@ -45,7 +46,12 @@ const mdSourceUrl = exportMd ? `${Astro.url.pathname.replace(/\/$/, "")}.md` : "
 >
     <!-- Article Header -->
     <header class="stalux-post-article-header" data-stalux-motion-region>
-        <h1 class="stalux-post-title" data-stalux-motion-focus>
+        <h1
+            class="stalux-post-title"
+            data-stalux-motion-focus
+            data-pagefind-body
+            data-pagefind-meta="title"
+        >
             {props.title}
         </h1>
         <div class="stalux-post-metadata">
@@ -111,6 +117,14 @@ const mdSourceUrl = exportMd ? `${Astro.url.pathname.replace(/\/$/, "")}.md` : "
         transitionName={`${transitionPrefix}-summary`}
     />
 
+    <span
+        hidden
+        data-pagefind-body
+        data-stalux-search-keywords
+        data-pagefind-index-attrs="data-search-keywords"
+        data-search-keywords={(props.searchKeywords ?? []).join(" ")}
+    ></span>
+
     <!-- Article Body -->
     <section
         class="stalux-post-body stalux-prose"

package/src/index.ts

@@ -29,6 +29,7 @@ import { parse } from "parse5";
 import { parse as parseYaml } from "yaml";
 import type { StaluxOptions } from "./config";
 import { expressiveCode } from "./expressive-code";
+import { writeCjkSearchIndex } from "./internal/cjk-search-index";
 import { staluxComponentsAlias } from "./internal/components-plugin";
 import {
     clearPageFontSubsets,
@@ -126,6 +127,7 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration[] {
     // is served from the page-output cache still finds its file on disk.
     let coverCacheDir = "";
 
+    let searchBase = "/";
     let pageFontData: { fontBuffer: Buffer; outputDir: string; cacheDir: string } | undefined;
 
     const coreIntegration: AstroIntegration = {
@@ -140,6 +142,7 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration[] {
                 command,
                 logger,
             }) => {
+                searchBase = config.base;
                 const started = performance.now();
                 const isPluginMode = isPluginProject(config.root, new URL("../", import.meta.url));
                 const configLogger = logger.fork("stalux/config");
@@ -619,7 +622,9 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration[] {
                     const pagefindStarted = performance.now();
 
                     try {
-                        const { index, errors } = await pagefindCreateIndex();
+                        const { index, errors } = await pagefindCreateIndex({
+                            includeCharacters: "+#._",
+                        });
 
                         if (!index) {
                             throw new Error(
@@ -627,15 +632,22 @@ export function stalux(options: StaluxOptions = {}): AstroIntegration[] {
                             );
                         }
 
-                        const { page_count } = await index.addDirectory({ path: outDir });
+                        const { page_count, errors: crawlErrors } = await index.addDirectory({
+                            path: outDir,
+                        });
+                        if (crawlErrors.length) throw new Error(crawlErrors.join("; "));
                         if (page_count === 0) {
                             throw new Error("Pagefind did not index any pages");
                         }
 
-                        const { outputPath } = await index.writeFiles({
+                        const { outputPath, errors: writeErrors } = await index.writeFiles({
                             outputPath: path.join(outDir, "pagefind"),
                         });
 
+                        if (writeErrors.length) throw new Error(writeErrors.join("; "));
+                        const cjkPages = await writeCjkSearchIndex(outDir, pageEntries, searchBase);
+                        logger.info(`CJK substring index: ${cjkPages} pages`);
+
                         logger.info(
                             `indexed ${page_count} pages → ${outputPath} (${(performance.now() - pagefindStarted).toFixed(1)}ms)`,
                         );

package/src/internal/cjk-search-index.ts

@@ -0,0 +1,130 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { type DefaultTreeAdapterMap, parse } from "parse5";
+import { type CjkDocument, cjkGrams, gramShard, normalizeSearch } from "../utils/cjk-search";
+import { forEachBounded } from "./bounded-tasks";
+
+type Node = DefaultTreeAdapterMap["node"];
+const skipped = new Set(["script", "style", "template", "noscript", "nav", "footer", "form"]);
+const blocks = new Set([
+    "p",
+    "div",
+    "section",
+    "article",
+    "aside",
+    "li",
+    "br",
+    "pre",
+    "tr",
+    "h1",
+    "h2",
+    "h3",
+    "h4",
+    "h5",
+    "h6",
+]);
+const attr = (node: Node, name: string) =>
+    "attrs" in node ? node.attrs.find((item) => item.name === name)?.value : undefined;
+
+/** Extract only real indexed DOM, preserving adjacency across inline emphasis. */
+export function extractCjkDocument(html: string, url: string) {
+    const document = parse(html);
+    let language = "";
+    let title = "";
+    let documentTitle = "";
+    let description = "";
+    let keywords = "";
+    let hasBody = false;
+    const filters: Record<string, string[]> = {};
+    function text(node: Node): string {
+        if (
+            "tagName" in node &&
+            (skipped.has(node.tagName) || attr(node, "data-pagefind-ignore") !== undefined)
+        )
+            return "";
+        if ("value" in node) return node.value;
+        const body = "childNodes" in node ? node.childNodes.map(text).join("") : "";
+        return "tagName" in node && blocks.has(node.tagName) ? ` ${body} ` : body;
+    }
+    const parts: string[] = [];
+    function visit(node: Node, insideBody = false) {
+        if ("tagName" in node) {
+            if (skipped.has(node.tagName) || attr(node, "data-pagefind-ignore") !== undefined)
+                return;
+            if (node.tagName === "title") documentTitle = text(node).trim();
+            if (node.tagName === "html") language = attr(node, "lang") ?? "";
+            if (node.tagName === "h1" && !title) title = text(node).trim();
+            if (attr(node, "data-stalux-search-description") !== undefined)
+                description = text(node).trim();
+            if (attr(node, "data-stalux-search-keywords") !== undefined)
+                keywords = attr(node, "data-search-keywords") ?? "";
+            const filter = attr(node, "data-pagefind-filter");
+            if (filter) {
+                const match = /^([^[\]:]+)\[([^\]]+)\]$/u.exec(filter);
+                if (match) filters[match[1] as string] = [attr(node, match[2] as string) ?? ""];
+            }
+            const body = attr(node, "data-pagefind-body") !== undefined;
+            if (body) {
+                hasBody = true;
+                if (!insideBody) parts.push(text(node));
+                const attrs = attr(node, "data-pagefind-index-attrs")?.split(",") ?? [];
+                for (const name of attrs) parts.push(attr(node, name.trim()) ?? "");
+            }
+            insideBody ||= body;
+        }
+        if ("childNodes" in node) for (const child of node.childNodes) visit(child, insideBody);
+    }
+    visit(document);
+    if (!hasBody) return null;
+    const content = parts.join(" ").replace(/\s+/gu, " ").trim();
+    return {
+        url,
+        title: title || documentTitle || url,
+        description,
+        keywords,
+        language,
+        filters,
+        content,
+    };
+}
+
+/** Content-addressed shards prevent mixed old/new deployments and keep downloads query-specific. */
+export async function writeCjkSearchIndex(outDir: string, htmlFiles: string[], base: string) {
+    const directory = path.join(outDir, "pagefind", "cjk");
+    await mkdir(directory, { recursive: true });
+    async function asset(value: unknown) {
+        const json = JSON.stringify(value);
+        const hash = createHash("sha256").update(json).digest("hex").slice(0, 20);
+        const file = `${hash}.json`;
+        await writeFile(path.join(directory, file), json);
+        return file;
+    }
+    const extracted = new Map<string, NonNullable<ReturnType<typeof extractCjkDocument>>>();
+    await forEachBounded(htmlFiles, 6, async (file) => {
+        const html = await readFile(path.join(outDir, file), "utf8");
+        // Most output pages are archives/tags: don't parse pages without indexed sections.
+        if (!html.includes("data-pagefind-body")) return;
+        const url = `${base.replace(/\/$/u, "")}/${file.replace(/index\.html$/u, "")}`;
+        const record = extractCjkDocument(html, url);
+        if (record) extracted.set(file, record);
+    });
+    const documents: CjkDocument[] = [];
+    const postings: Record<string, Record<string, number[]>> = {};
+    for (const [, record] of [...extracted].sort(([a], [b]) => a.localeCompare(b))) {
+        const { content, ...meta } = record;
+        const id = documents.length;
+        documents.push({ ...meta, file: await asset({ content }) });
+        for (const gram of cjkGrams(normalizeSearch(content))) {
+            const key = gramShard(gram);
+            postings[key] ??= {};
+            const shard = postings[key];
+            shard[gram] ??= [];
+            shard[gram].push(id);
+        }
+    }
+    const shards: Record<string, string> = {};
+    for (const [key, value] of Object.entries(postings)) shards[key] = await asset(value);
+    await writeFile(path.join(directory, "manifest.json"), JSON.stringify({ documents, shards }));
+    return documents.length;
+}

package/src/internal/search-style.ts

@@ -1,4 +1,5 @@
 import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
 import type { Plugin } from "vite";
 
 const publicId = "virtual:stalux-search-style";
@@ -9,8 +10,23 @@ export function searchStylePlugin(development: boolean, base: string): Plugin {
     const stylesheet = createRequire(import.meta.url)
         .resolve("@pagefind/component-ui/css")
         .replaceAll("\\", "/");
+    let building = false;
     return {
         name: "stalux:search-style",
+        configResolved(config) {
+            building = config.command === "build";
+        },
+        buildStart() {
+            if (building && this.environment.name === "client")
+                this.emitFile({
+                    type: "chunk",
+                    id: fileURLToPath(
+                        new URL("../scripts/search-engine-entry.ts", import.meta.url),
+                    ),
+                    fileName: "pagefind-enhanced/pagefind.js",
+                    preserveSignature: "strict",
+                });
+        },
         configureServer(server) {
             // A linked package can be outside the consumer's workspace root.
             server.config.server.fs.allow.push(stylesheet);

package/src/layouts/PostLayout.astro

@@ -14,6 +14,7 @@ import { buildWalineProps } from "@utils/waline";
 interface Props {
     title: string;
     description?: string;
+    searchKeywords?: string[];
     postId?: string | number;
     date?: string;
     updated?: string;
@@ -61,6 +62,7 @@ const walineConfig = walineSection?.serverURL
             postId={props.postId}
             title={props.title}
             description={props.description}
+            searchKeywords={[...tags, ...categories, ...(props.searchKeywords ?? [])]}
             titleTransitionName={props.postId === undefined
                 ? undefined
                 : getPostTitleTransitionName(props.postId)}

package/src/pages/posts/[post].astro

@@ -75,6 +75,7 @@ export async function getStaticPaths() {
     <PostLayout
         title={props.post.data.title}
         description={autoDesc}
+        searchKeywords={props.post.data.searchKeywords ?? []}
         postId={props.post.data.abbrlink}
         date={props.post.data.date}
         updated={props.post.data.updated}

package/src/schemas/collections.ts

@@ -88,6 +88,7 @@ const postSchema = z.object({
     date: datetimeField("date"),
     updated: datetimeField("updated").optional(),
     draft: z.boolean().optional().default(false),
+    searchKeywords: z.array(z.string().trim().min(1)).optional(),
     tags: z.preprocess(
         (val) => (typeof val === "string" ? [val] : val),
         z.array(z.string()).optional(),

package/src/scripts/pagefind-api.ts

@@ -30,7 +30,7 @@ export function createPagefindLoader(
         if (!pending) {
             pending = (async () => {
                 try {
-                    const url = new URL(sitePath("pagefind/pagefind.js", base), origin());
+                    const url = new URL(sitePath("pagefind-enhanced/pagefind.js", base), origin());
                     // Browsers can retain a failed ESM fetch; retry with a fresh module URL.
                     if (failedAttempts)
                         url.searchParams.set("stalux_retry", String(failedAttempts));

package/src/scripts/search-engine-entry.ts

@@ -0,0 +1,48 @@
+import { sitePath } from "../utils/site-path";
+import { createEnhancedSearch, type NativeSearch } from "./search-engine";
+
+const base = import.meta.env.BASE_URL;
+interface PagefindModule {
+    createInstance: (options: Record<string, unknown>) => NativeSearch;
+}
+const moduleUrl = sitePath("pagefind/pagefind.js", base);
+let modulePromise: Promise<PagefindModule> | undefined;
+function loadNative(): Promise<PagefindModule> {
+    if (!modulePromise) {
+        modulePromise = import(/* @vite-ignore */ moduleUrl);
+        void modulePromise?.catch(() => {
+            modulePromise = undefined;
+        });
+    }
+    return modulePromise as Promise<PagefindModule>;
+}
+
+/** Public Component UI bundle contract; no private instance fields or hooks are patched. */
+export function createInstance(options: Record<string, unknown> = {}) {
+    let native: Promise<NativeSearch> | undefined;
+    const load = () => {
+        if (!native) {
+            native = loadNative().then((module) =>
+                module.createInstance({
+                    ranking: { pageLength: 0.4, termFrequency: 0.8 },
+                    ...options,
+                }),
+            );
+            void native.catch(() => {
+                native = undefined;
+            });
+        }
+        return native;
+    };
+    return createEnhancedSearch(load, base);
+}
+let instance: ReturnType<typeof createInstance> | undefined;
+const shared = () => {
+    instance ??= createInstance();
+    return instance;
+};
+export const search = (...args: Parameters<NativeSearch["search"]>) => shared().search(...args);
+export const options = (...args: Parameters<NativeSearch["options"]>) => shared().options(...args);
+export const filters = () => shared().filters();
+export const mergeIndex = (...args: Parameters<NativeSearch["mergeIndex"]>) =>
+    shared().mergeIndex(...args);

package/src/scripts/search-engine.ts

@@ -0,0 +1,219 @@
+import {
+    CJK,
+    type CjkDocument,
+    type CjkManifest,
+    cjkGrams,
+    gramShard,
+    normalizeSearch,
+} from "../utils/cjk-search";
+import { sitePath } from "../utils/site-path";
+import { createClientLogger } from "./logger";
+
+export interface SearchData {
+    url: string;
+    meta?: Record<string, string>;
+    content?: string;
+    excerpt?: string;
+    plain_excerpt?: string;
+    filters?: Record<string, string[]>;
+}
+export interface SearchResult {
+    id: string;
+    data: () => Promise<SearchData>;
+}
+export interface SearchResponse {
+    results: SearchResult[];
+    filters?: Record<string, Record<string, number>>;
+    totalFilters?: Record<string, Record<string, number>>;
+    unfilteredTotalCount?: number;
+}
+export interface SearchOptions {
+    filters?: Record<string, string | string[]>;
+}
+export interface NativeSearch {
+    search: (query: string | null, options?: SearchOptions) => Promise<SearchResponse>;
+    options: (options: Record<string, unknown>) => Promise<void>;
+    filters: () => Promise<Record<string, Record<string, number>>>;
+    mergeIndex: (url: string, options?: Record<string, unknown>) => Promise<void>;
+}
+const logger = createClientLogger("search/cjk");
+const escapeHtml = (text: string) =>
+    text.replace(
+        /[&<>"']/gu,
+        (char) =>
+            ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[char] ?? char,
+    );
+
+function excerpt(content: string, terms: string[]) {
+    const position = Math.max(0, normalizeSearch(content).indexOf(terms[0] ?? ""));
+    const start = Math.max(0, position - 45);
+    const plain = `${start ? "…" : ""}${content.slice(start, start + 180)}${content.length > start + 180 ? "…" : ""}`;
+    const pattern = terms
+        .map((term) => term.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&"))
+        .sort((a, b) => b.length - a.length)
+        .join("|");
+    const regex = new RegExp(pattern, "giu");
+    let end = 0;
+    let highlighted = "";
+    for (const match of plain.matchAll(regex)) {
+        highlighted +=
+            escapeHtml(plain.slice(end, match.index)) + `<mark>${escapeHtml(match[0])}</mark>`;
+        end = match.index + match[0].length;
+    }
+    return { plain_excerpt: plain, excerpt: highlighted + escapeHtml(plain.slice(end)) };
+}
+
+export function createEnhancedSearch(
+    native: Promise<NativeSearch> | (() => Promise<NativeSearch>),
+    base = import.meta.env.BASE_URL,
+    request: typeof fetch = fetch,
+    language = () => document.documentElement.lang,
+) {
+    const getNative = () => (typeof native === "function" ? native() : native);
+    const directory = sitePath("pagefind/cjk/", base);
+    const cache = new Map<string, Promise<unknown>>();
+    function json<T>(file: string): Promise<T> {
+        let pending = cache.get(file);
+        if (!pending) {
+            pending = request(directory + file).then((response) => {
+                if (!response.ok) throw new Error(`CJK index HTTP ${response.status}`);
+                return response.json();
+            });
+            cache.set(file, pending);
+            void pending.catch(() => cache.delete(file));
+        }
+        return pending as Promise<T>;
+    }
+    const ids = new Map<string, Promise<string | undefined>>();
+    async function nativeId(api: NativeSearch, record: CjkDocument, original: SearchResult[]) {
+        const post = record.filters.post?.[0];
+        if (post) {
+            let pending = ids.get(record.url);
+            if (!pending) {
+                pending = api
+                    .search(null, { filters: { post } })
+                    .then((result) => result.results[0]?.id);
+                ids.set(record.url, pending);
+                void pending.catch(() => ids.delete(record.url));
+            }
+            return pending;
+        }
+        // Non-post pages are uncommon; resolve existing hits only to avoid duplicate URLs.
+        for (const result of original) {
+            if ((await result.data()).url.replace(/\/$/u, "") === record.url.replace(/\/$/u, ""))
+                return result.id;
+        }
+    }
+    async function search(query: string | null, options?: SearchOptions): Promise<SearchResponse> {
+        const api = await getNative();
+        if (query === null || !query.trim()) return api.search(query, options);
+        const normalized = normalizeSearch(query);
+        let original = await api.search(query, options);
+        // Keep Pagefind's quoted phrase semantics and compound filter semantics intact.
+        if (
+            /["“”]/u.test(query) ||
+            Object.values(options?.filters ?? {}).some((value) => value.length)
+        )
+            return original;
+        if (normalized !== query) {
+            const variant = await api.search(normalized, options);
+            const originalIds = new Set(original.results.map((result) => result.id));
+            const results = [
+                ...original.results,
+                ...variant.results.filter((result) => !originalIds.has(result.id)),
+            ];
+            original = { ...original, results, unfilteredTotalCount: results.length };
+        }
+        if (!CJK.test(normalized)) return original;
+        try {
+            const manifest = await json<CjkManifest>("manifest.json");
+            const grams = cjkGrams(normalized);
+            const shardKeys = [...new Set(grams.map(gramShard))];
+            const shards = new Map(
+                await Promise.all(
+                    shardKeys.map(
+                        async (key) =>
+                            [
+                                key,
+                                manifest.shards[key]
+                                    ? await json<Record<string, number[]>>(
+                                          manifest.shards[key] as string,
+                                      )
+                                    : {},
+                            ] as const,
+                    ),
+                ),
+            );
+            const lists = grams
+                .map((gram) => shards.get(gramShard(gram))?.[gram] ?? [])
+                .sort((a, b) => a.length - b.length);
+            let candidates = new Set(lists[0] ?? []);
+            for (const list of lists.slice(1)) {
+                const allowed = new Set(list);
+                candidates = new Set([...candidates].filter((id) => allowed.has(id)));
+            }
+            const terms = normalized.split(" ").filter(Boolean);
+            const matches: Array<{ record: CjkDocument; content: string; score: number }> = [];
+            // Bound text downloads independently of result count. Text is fetched only for n-gram candidates.
+            const pending = [...candidates];
+            let cursor = 0;
+            await Promise.all(
+                Array.from({ length: Math.min(6, pending.length) }, async () => {
+                    while (cursor < pending.length) {
+                        const record = manifest.documents[pending[cursor++] as number];
+                        if (!record || record.language.toLowerCase() !== language().toLowerCase())
+                            continue;
+                        const { content } = await json<{ content: string }>(record.file);
+                        const normalizedContent = normalizeSearch(content);
+                        if (!terms.every((term) => normalizedContent.includes(term))) continue;
+                        const title = normalizeSearch(record.title);
+                        const description = normalizeSearch(record.description);
+                        const score =
+                            title === normalized
+                                ? 100
+                                : title.includes(normalized)
+                                  ? 80
+                                  : terms.every((term) => title.includes(term))
+                                    ? 60
+                                    : terms.every((term) => description.includes(term))
+                                      ? 40
+                                      : 20;
+                        matches.push({ record, content, score });
+                    }
+                }),
+            );
+            matches.sort((a, b) => b.score - a.score || a.record.url.localeCompare(b.record.url));
+            const supplemental: SearchResult[] = [];
+            for (const { record, content } of matches) {
+                const id = await nativeId(api, record, original.results);
+                supplemental.push({
+                    id: id ?? `cjk:${record.url}`,
+                    data: () =>
+                        Promise.resolve({
+                            url: record.url,
+                            meta: { title: record.title },
+                            content,
+                            filters: record.filters,
+                            ...excerpt(content, terms),
+                        }),
+                });
+            }
+            const seen = new Set(supplemental.map((result) => result.id));
+            const results = [
+                ...supplemental,
+                ...original.results.filter((result) => !seen.has(result.id)),
+            ];
+            return { ...original, results, unfilteredTotalCount: results.length };
+        } catch {
+            logger.warn("CJK substring index unavailable; using Pagefind");
+            return original;
+        }
+    }
+    return {
+        search,
+        options: async (options: Record<string, unknown>) => (await getNative()).options(options),
+        filters: async () => (await getNative()).filters(),
+        mergeIndex: async (url: string, options?: Record<string, unknown>) =>
+            (await getNative()).mergeIndex(url, options),
+    };
+}

package/src/utils/cjk-search.ts

@@ -0,0 +1,40 @@
+/** Shared by the indexer and browser: keep Unicode normalization identical. */
+export const CJK = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}]/u;
+
+export function normalizeSearch(text: string): string {
+    return text.normalize("NFKC").toLowerCase().replace(/\s+/gu, " ").trim();
+}
+
+export function cjkGrams(text: string): string[] {
+    const grams = new Set<string>();
+    let previous = "";
+    for (const char of normalizeSearch(text)) {
+        if (CJK.test(char)) {
+            grams.add(char);
+            if (previous) grams.add(previous + char);
+            previous = char;
+        } else previous = "";
+    }
+    return [...grams];
+}
+
+export function gramShard(gram: string): string {
+    let hash = 0;
+    for (const char of gram) hash = (hash * 31 + (char.codePointAt(0) ?? 0)) >>> 0;
+    return (hash % 32).toString(16);
+}
+
+export interface CjkDocument {
+    url: string;
+    title: string;
+    description: string;
+    keywords: string;
+    language: string;
+    filters: Record<string, string[]>;
+    file: string;
+}
+
+export interface CjkManifest {
+    documents: CjkDocument[];
+    shards: Record<string, string>;
+}