mdorigin 0.2.0 → 0.3.0

package/README.md

@@ -135,3 +135,5 @@ Runtime endpoints:
 - CLI: [`docs/site/reference/cli.md`](docs/site/reference/cli.md)
 - Search setup: [`docs/site/guides/getting-started.md`](docs/site/guides/getting-started.md#quick-start)
 - Cloudflare deployment: [`docs/site/guides/cloudflare.md`](docs/site/guides/cloudflare.md)
+
+The docs site at <https://mdorigin.jolestar.workers.dev> is deployed automatically from `main` with GitHub Actions.

package/dist/adapters/cloudflare.d.ts

@@ -1,6 +1,6 @@
 import type { MdoPlugin } from '../core/extensions.js';
 import type { ResolvedSiteConfig } from '../core/site-config.js';
-import { type SearchBundleEntry } from '../search.js';
+import { type ExternalSearchBundleEntry, type SearchBundleEntry } from '../search.js';
 export interface TextCloudflareManifestEntry {
     path: string;
     kind: 'text';
@@ -30,6 +30,7 @@ export interface CloudflareManifest {
     entries: CloudflareManifestEntry[];
     siteConfig?: ResolvedSiteConfig;
     searchEntries?: SearchBundleEntry[];
+    externalSearchEntries?: ExternalSearchBundleEntry[];
     runtime?: CloudflareBundleRuntimeConfig;
 }
 export interface CloudflareAssetsBindingLike {

package/dist/adapters/cloudflare.js

@@ -1,7 +1,7 @@
 import { MemoryContentStore } from '../core/content-store.js';
 import { handleSiteRequest } from '../core/request-handler.js';
 import { resolveRequest } from '../core/router.js';
-import { createSearchApiFromBundle } from '../search.js';
+import { createSearchApiFromBundle, createSearchApiFromExternalBundle, } from '../search.js';
 export function createCloudflareWorker(manifest, options = {}) {
     const storeIndex = new MemoryContentStore(manifest.entries.map((entry) => {
         if (entry.kind === 'text') {
@@ -26,12 +26,18 @@ export function createCloudflareWorker(manifest, options = {}) {
             bytes: decodeBase64(entry.base64 ?? ''),
         };
     }));
-    const searchApi = manifest.searchEntries && manifest.searchEntries.length > 0
+    const inlineSearchApi = manifest.searchEntries && manifest.searchEntries.length > 0
         ? createSearchApiFromBundle(manifest.searchEntries)
         : undefined;
+    const externalSearchApis = new WeakMap();
+    let defaultExternalSearchApi;
     return {
         async fetch(request, env) {
             const url = new URL(request.url);
+            const externalSearchApi = getExternalSearchApi(manifest, env, externalSearchApis, defaultExternalSearchApi);
+            if (env === undefined && externalSearchApi !== undefined) {
+                defaultExternalSearchApi = externalSearchApi;
+            }
             const directBinaryResponse = await tryServeExternalBinary(manifest, request, env);
             if (directBinaryResponse !== null) {
                 return directBinaryResponse;
@@ -60,7 +66,7 @@ export function createCloudflareWorker(manifest, options = {}) {
                 acceptHeader: request.headers.get('accept') ?? undefined,
                 searchParams: url.searchParams,
                 requestUrl: request.url,
-                searchApi,
+                searchApi: inlineSearchApi ?? externalSearchApi,
                 plugins: options.plugins,
             });
             const headers = new Headers(siteResponse.headers);
@@ -76,6 +82,84 @@ export function createCloudflareWorker(manifest, options = {}) {
         },
     };
 }
+function getExternalSearchApi(manifest, env, cache, defaultApi) {
+    if (!manifest.externalSearchEntries || manifest.externalSearchEntries.length === 0) {
+        return undefined;
+    }
+    if (!env) {
+        return (defaultApi ??
+            createSearchApiFromExternalBundle(manifest.externalSearchEntries, async (entry) => loadExternalSearchEntryResponse(entry, undefined, manifest.runtime?.r2Binding)));
+    }
+    const cached = cache.get(env);
+    if (cached) {
+        return cached;
+    }
+    const searchApi = createSearchApiFromExternalBundle(manifest.externalSearchEntries, async (entry) => loadExternalSearchEntryResponse(entry, env, manifest.runtime?.r2Binding));
+    cache.set(env, searchApi);
+    return searchApi;
+}
+async function loadExternalSearchEntryResponse(entry, env, r2Binding) {
+    if (entry.storageKind === 'assets') {
+        const assetsBinding = env?.ASSETS;
+        if (!assetsBinding) {
+            throw new Error(`Cloudflare ASSETS binding is required to serve search bundle file ${entry.path}.`);
+        }
+        const assetResponse = await assetsBinding.fetch(new Request(new URL(`/${entry.storageKey}`, 'https://mdorigin-search.invalid/'), {
+            method: 'GET',
+        }));
+        if (assetResponse.ok) {
+            return assetResponse;
+        }
+        return new Response('Not Found', {
+            status: 404,
+            headers: {
+                'content-type': 'text/plain; charset=utf-8',
+            },
+        });
+    }
+    const bindingName = r2Binding ?? 'MDORIGIN_R2';
+    const bucket = env?.[bindingName];
+    if (!bucket) {
+        throw new Error(`Cloudflare R2 binding ${bindingName} is required to serve search bundle file ${entry.path}.`);
+    }
+    const object = await bucket.get(entry.storageKey);
+    if (!object) {
+        return new Response('Not Found', {
+            status: 404,
+            headers: {
+                'content-type': 'text/plain; charset=utf-8',
+            },
+        });
+    }
+    const headers = new Headers({
+        'content-type': entry.mediaType,
+    });
+    if (object.httpEtag) {
+        headers.set('etag', object.httpEtag);
+    }
+    if (object.body instanceof ReadableStream) {
+        return new Response(object.body, {
+            status: 200,
+            headers,
+        });
+    }
+    if (object.body && 'arrayBuffer' in object.body) {
+        return new Response(await object.body.arrayBuffer(), {
+            status: 200,
+            headers,
+        });
+    }
+    if (typeof object.arrayBuffer === 'function') {
+        return new Response(await object.arrayBuffer(), {
+            status: 200,
+            headers,
+        });
+    }
+    return new Response(null, {
+        status: 200,
+        headers,
+    });
+}
 async function tryServeExternalBinary(manifest, request, env) {
     const resolved = resolveRequest(new URL(request.url).pathname);
     if (resolved.kind !== 'asset' || !resolved.sourcePath) {

package/dist/cli/build-search.js

@@ -5,11 +5,11 @@ import { createFileSystemContentStore } from '../adapters/node.js';
 export async function runBuildSearchCommand(rawArgs) {
     const args = parseArgs(rawArgs);
     if (args.help) {
-        console.log('Usage: mdorigin build search --root <content-dir> [--out ./dist/search] [--embedding-backend model2vec|hashing] [--model sentence-transformers/all-MiniLM-L6-v2] [--config <config-file>]');
+        console.log('Usage: mdorigin build search --root <content-dir> [--out ./dist/search] [--embedding-backend model2vec|hashing] [--model sentence-transformers/all-MiniLM-L6-v2] [--config <config-file>] [--incremental]');
         return;
     }
     if (!args.root) {
-        throw new Error('Usage: mdorigin build search --root <content-dir> [--out ./dist/search] [--embedding-backend model2vec|hashing] [--model sentence-transformers/all-MiniLM-L6-v2] [--config <config-file>]');
+        throw new Error('Usage: mdorigin build search --root <content-dir> [--out ./dist/search] [--embedding-backend model2vec|hashing] [--model sentence-transformers/all-MiniLM-L6-v2] [--config <config-file>] [--incremental]');
     }
     const rootDir = path.resolve(args.root);
     const store = createFileSystemContentStore(rootDir);
@@ -24,18 +24,28 @@ export async function runBuildSearchCommand(rawArgs) {
         siteConfig,
         embeddingBackend: args.embeddingBackend ?? 'model2vec',
         model: args.model,
+        incremental: args.incremental,
     });
-    console.log(`search bundle written to ${result.outputDir} (${result.documentCount} documents, ${result.chunkCount} chunks)`);
+    console.log([
+        `search bundle written to ${result.outputDir} (${result.documentCount} documents, ${result.chunkCount} chunks)`,
+        result.incremental
+            ? `incremental cache: ${result.cachePath} (${result.incremental.newDocumentCount} new, ${result.incremental.changedDocumentCount} changed, ${result.incremental.unchangedDocumentCount} unchanged, ${result.incremental.removedDocumentCount} removed)`
+            : '',
+    ].filter(Boolean).join('\n'));
 }
 function parseArgs(rawArgs) {
     const parsed = {};
-    const supportedFlags = new Set(['root', 'out', 'embedding-backend', 'model', 'config']);
+    const supportedFlags = new Set(['root', 'out', 'embedding-backend', 'model', 'config', 'incremental']);
     for (let index = 0; index < rawArgs.length; index += 1) {
         const arg = rawArgs[index];
         if (arg === '--help' || arg === '-h') {
             parsed.help = 'true';
             continue;
         }
+        if (arg === '--incremental') {
+            parsed.incremental = 'true';
+            continue;
+        }
         if (arg.startsWith('--')) {
             const flag = arg.slice(2);
             if (!supportedFlags.has(flag)) {
@@ -57,6 +67,7 @@ function parseArgs(rawArgs) {
         embeddingBackend: parsed['embedding-backend'],
         model: parsed.model,
         config: parsed.config,
+        incremental: parsed.incremental === 'true',
         help: parsed.help === 'true',
     };
 }

package/dist/cli/help.js

@@ -2,11 +2,11 @@ export const ROOT_USAGE_LINES = [
     'Usage:',
     '  mdorigin dev --root <content-dir> [--port 3000] [--config <config-file>] [--search ./dist/search]',
     '  mdorigin build index (--root <content-dir> | --dir <content-dir>) [--config <config-file>]',
-    '  mdorigin build search --root <content-dir> [--out ./dist/search] [--embedding-backend model2vec|hashing] [--model sentence-transformers/all-MiniLM-L6-v2] [--config <config-file>]',
+    '  mdorigin build search --root <content-dir> [--out ./dist/search] [--embedding-backend model2vec|hashing] [--model sentence-transformers/all-MiniLM-L6-v2] [--config <config-file>] [--incremental]',
     '  mdorigin build cloudflare --root <content-dir> [--out ./dist/cloudflare] [--config <config-file>] [--search ./dist/search] [--binary-mode inline|external] [--assets-max-bytes 26214400] [--r2-binding MDORIGIN_R2]',
     '  mdorigin init cloudflare [--dir .] [--entry ./dist/cloudflare/worker.mjs] [--name <worker-name>] [--compatibility-date 2026-03-20] [--r2-bucket <bucket-name>] [--force]',
     '  mdorigin sync cloudflare-r2 --dir ./dist/cloudflare --bucket <bucket-name> [--force]',
-    '  mdorigin search --index <search-dir> [--top-k 10] <query>',
+    '  mdorigin search --index <search-dir> [--top-k 10] [--meta key=value] <query>',
     '  mdorigin version',
     '',
     'Global options:',
@@ -16,7 +16,7 @@ export const ROOT_USAGE_LINES = [
 export const BUILD_USAGE_LINES = [
     'Usage:',
     '  mdorigin build index (--root <content-dir> | --dir <content-dir>) [--config <config-file>]',
-    '  mdorigin build search --root <content-dir> [--out ./dist/search] [--embedding-backend model2vec|hashing] [--model sentence-transformers/all-MiniLM-L6-v2] [--config <config-file>]',
+    '  mdorigin build search --root <content-dir> [--out ./dist/search] [--embedding-backend model2vec|hashing] [--model sentence-transformers/all-MiniLM-L6-v2] [--config <config-file>] [--incremental]',
     '  mdorigin build cloudflare --root <content-dir> [--out ./dist/cloudflare] [--config <config-file>] [--search ./dist/search] [--binary-mode inline|external] [--assets-max-bytes 26214400] [--r2-binding MDORIGIN_R2]',
 ];
 export const INIT_USAGE_LINES = [

package/dist/cli/search.js

@@ -3,23 +3,25 @@ import { searchBundle } from '../search.js';
 export async function runSearchCommand(rawArgs) {
     const args = parseArgs(rawArgs);
     if (args.help) {
-        console.log('Usage: mdorigin search --index <search-dir> [--top-k 10] <query>');
+        console.log('Usage: mdorigin search --index <search-dir> [--top-k 10] [--meta key=value] <query>');
         return;
     }
     if (!args.indexDir || !args.query) {
-        throw new Error('Usage: mdorigin search --index <search-dir> [--top-k 10] <query>');
+        throw new Error('Usage: mdorigin search --index <search-dir> [--top-k 10] [--meta key=value] <query>');
     }
     const hits = await searchBundle({
         indexDir: path.resolve(args.indexDir),
         query: args.query,
         topK: args.topK,
+        metadata: args.metadata,
     });
     console.log(JSON.stringify(hits, null, 2));
 }
 function parseArgs(rawArgs) {
     const flags = {};
+    const metadata = {};
     const positionals = [];
-    const supportedFlags = new Set(['index', 'top-k']);
+    const supportedFlags = new Set(['index', 'top-k', 'meta']);
     for (let index = 0; index < rawArgs.length; index += 1) {
         const arg = rawArgs[index];
         if (arg === '--help' || arg === '-h') {
@@ -33,7 +35,16 @@ function parseArgs(rawArgs) {
             }
             const value = rawArgs[index + 1];
             if (value && !value.startsWith('--')) {
-                flags[flag] = value;
+                if (flag === 'meta') {
+                    const separator = value.indexOf('=');
+                    if (separator <= 0 || separator === value.length - 1) {
+                        throw new Error(`Invalid value for --meta: ${value}`);
+                    }
+                    metadata[value.slice(0, separator)] = value.slice(separator + 1);
+                }
+                else {
+                    flags[flag] = value;
+                }
                 index += 1;
                 continue;
             }
@@ -46,6 +57,7 @@ function parseArgs(rawArgs) {
         indexDir: flags.index,
         topK: Number.isInteger(topK) && topK > 0 ? topK : undefined,
         query: positionals.join(' ').trim(),
+        metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
         help: flags.help === 'true',
     };
 }

package/dist/cloudflare.d.ts

@@ -18,7 +18,7 @@ export interface WriteCloudflareBundleOptions extends BuildCloudflareManifestOpt
     configModulePath?: string;
 }
 export interface CloudflareBundleMetadata {
-    version: 1;
+    version: 2;
     workerEntry: string;
     binaryMode: CloudflareBinaryMode;
     assetsMaxBytes?: number;
@@ -26,9 +26,11 @@ export interface CloudflareBundleMetadata {
     r2Dir?: string;
     r2Binding?: string;
     siteTitle?: string;
-    r2Objects: Array<{
+    stagedObjects: Array<{
+        kind: 'binary' | 'search';
         path: string;
         mediaType: string;
+        storageKind: 'assets' | 'r2';
         storageKey: string;
         file: string;
         byteSize: number;

package/dist/cloudflare.js

@@ -11,6 +11,7 @@ const DEFAULT_ASSETS_BINDING = 'ASSETS';
 const DEFAULT_R2_BINDING = 'MDORIGIN_R2';
 const BUNDLE_FILE_NAME = 'bundle.json';
 const R2_STATE_FILE_NAME = 'r2-sync-state.json';
+const SEARCH_ASSETS_PREFIX = '__mdorigin/search';
 export async function buildCloudflareManifest(options) {
     const rootDir = path.resolve(options.rootDir);
     const files = await listFiles(rootDir);
@@ -50,15 +51,15 @@ export async function buildCloudflareManifest(options) {
             r2Binding,
         }));
     }
-    const searchEntries = options.searchDir
-        ? await readBundleEntries(path.resolve(options.searchDir))
+    const externalSearchEntries = options.searchDir
+        ? await buildSearchBundleEntries(path.resolve(options.searchDir), assetsMaxBytes)
         : undefined;
     entries.sort((left, right) => left.path.localeCompare(right.path));
     return {
         entries,
         siteConfig: options.siteConfig,
-        searchEntries,
-        runtime: binaryMode === 'external'
+        externalSearchEntries,
+        runtime: binaryMode === 'external' || (externalSearchEntries?.length ?? 0) > 0
             ? {
                 binaryMode,
                 r2Binding,
@@ -118,7 +119,7 @@ export async function writeCloudflareBundle(options) {
         '',
     ].join('\n');
     await mkdir(outDir, { recursive: true });
-    const metadata = await writeExternalBinaryStaging(path.resolve(options.rootDir), outDir, manifest, {
+    const metadata = await writeExternalStaging(path.resolve(options.rootDir), options.searchDir ? path.resolve(options.searchDir) : undefined, outDir, manifest, {
         binaryMode,
         assetsMaxBytes,
         r2Binding,
@@ -140,10 +141,10 @@ export async function initCloudflareProject(options) {
         throw new Error(`Refusing to overwrite ${configFile}. Re-run with --force to replace it.`);
     }
     const bundleMetadata = await readCloudflareBundleMetadata(options.workerEntry);
-    if (bundleMetadata?.binaryMode === 'external' &&
-        bundleMetadata.r2Objects.length > 0 &&
+    if (bundleMetadata &&
+        bundleMetadata.stagedObjects.some((object) => object.storageKind === 'r2') &&
         !options.r2Bucket) {
-        throw new Error('Cloudflare bundle contains R2-backed binaries. Re-run init cloudflare with --r2-bucket <bucket-name>.');
+        throw new Error('Cloudflare bundle contains R2-backed staged objects. Re-run init cloudflare with --r2-bucket <bucket-name>.');
     }
     const workerName = options.workerName ??
         slugifyWorkerName(bundleMetadata?.siteTitle ?? options.siteTitle) ??
@@ -156,7 +157,7 @@ export async function initCloudflareProject(options) {
         `  "main": ${JSON.stringify(toPosixPath(path.relative(projectDir, options.workerEntry)))},`,
         `  "compatibility_date": ${JSON.stringify(compatibilityDate)},`,
         '  "compatibility_flags": ["nodejs_compat"]',
-        bundleMetadata?.binaryMode === 'external' && bundleMetadata.assetsDir
+        bundleMetadata?.assetsDir
             ? [
                 ',',
                 '  "assets": {',
@@ -166,8 +167,8 @@ export async function initCloudflareProject(options) {
                 '  }',
             ].join('\n')
             : '',
-        bundleMetadata?.binaryMode === 'external' &&
-            bundleMetadata.r2Objects.length > 0 &&
+        bundleMetadata &&
+            bundleMetadata.stagedObjects.some((object) => object.storageKind === 'r2') &&
             bundleMetadata.r2Binding &&
             options.r2Bucket
             ? [
@@ -193,15 +194,16 @@ export async function syncCloudflareR2(options) {
     const outDir = path.resolve(options.dir);
     const bundleFile = path.join(outDir, BUNDLE_FILE_NAME);
     const metadata = await readBundleMetadataFile(bundleFile);
-    if (metadata.binaryMode !== 'external' || metadata.r2Objects.length === 0) {
-        throw new Error(`No R2-backed binaries found in ${bundleFile}.`);
+    const r2Objects = metadata.stagedObjects.filter((object) => object.storageKind === 'r2');
+    if (r2Objects.length === 0) {
+        throw new Error(`No R2-backed staged objects found in ${bundleFile}.`);
     }
     const stateFile = path.join(outDir, R2_STATE_FILE_NAME);
     const state = await readR2SyncState(stateFile);
     const runCommand = options.runCommand ?? runWranglerCommand;
     let uploadedCount = 0;
     let skippedCount = 0;
-    for (const object of metadata.r2Objects) {
+    for (const object of r2Objects) {
         const stateKey = `${options.bucketName}:${object.storageKey}`;
         if (!options.force && state.uploaded[stateKey]) {
             skippedCount += 1;
@@ -254,12 +256,14 @@ async function buildExternalBinaryEntry(filePath, normalizedPath, mediaType, byt
         byteSize,
     };
 }
-async function writeExternalBinaryStaging(rootDir, outDir, manifest, options) {
+async function writeExternalStaging(rootDir, searchDir, outDir, manifest, options) {
     const assetsDir = path.join(outDir, 'assets');
     const r2Dir = path.join(outDir, 'r2');
     await rm(assetsDir, { recursive: true, force: true });
     await rm(r2Dir, { recursive: true, force: true });
-    const r2Objects = new Map();
+    const stagedObjects = new Map();
+    let hasAssets = false;
+    let hasR2 = false;
     if (options.binaryMode === 'external') {
         for (const entry of manifest.entries) {
             if (entry.kind !== 'binary' || !('storageKind' in entry)) {
@@ -270,16 +274,66 @@ async function writeExternalBinaryStaging(rootDir, outDir, manifest, options) {
                 const targetFile = path.join(assetsDir, entry.storageKey);
                 await mkdir(path.dirname(targetFile), { recursive: true });
                 await copyFile(sourceFile, targetFile);
+                hasAssets = true;
+                stagedObjects.set(`assets:${entry.storageKey}`, {
+                    kind: 'binary',
+                    path: entry.path,
+                    mediaType: entry.mediaType,
+                    storageKind: 'assets',
+                    storageKey: entry.storageKey,
+                    file: toPosixPath(path.join('assets', entry.storageKey)),
+                    byteSize: entry.byteSize,
+                });
+                continue;
+            }
+            const relativeFile = toPosixPath(path.join('r2', entry.storageKey));
+            const targetFile = path.join(outDir, relativeFile);
+            if (!stagedObjects.has(`r2:${entry.storageKey}`)) {
+                await mkdir(path.dirname(targetFile), { recursive: true });
+                await copyFile(sourceFile, targetFile);
+                hasR2 = true;
+                stagedObjects.set(`r2:${entry.storageKey}`, {
+                    kind: 'binary',
+                    path: entry.path,
+                    mediaType: entry.mediaType,
+                    storageKind: 'r2',
+                    storageKey: entry.storageKey,
+                    file: relativeFile,
+                    byteSize: entry.byteSize,
+                });
+            }
+        }
+    }
+    if (searchDir && manifest.externalSearchEntries) {
+        for (const entry of manifest.externalSearchEntries) {
+            const sourceFile = path.join(searchDir, entry.path);
+            if (entry.storageKind === 'assets') {
+                const targetFile = path.join(assetsDir, entry.storageKey);
+                await mkdir(path.dirname(targetFile), { recursive: true });
+                await copyFile(sourceFile, targetFile);
+                hasAssets = true;
+                stagedObjects.set(`assets:${entry.storageKey}`, {
+                    kind: 'search',
+                    path: entry.path,
+                    mediaType: entry.mediaType,
+                    storageKind: 'assets',
+                    storageKey: entry.storageKey,
+                    file: toPosixPath(path.join('assets', entry.storageKey)),
+                    byteSize: entry.byteSize,
+                });
                 continue;
             }
             const relativeFile = toPosixPath(path.join('r2', entry.storageKey));
             const targetFile = path.join(outDir, relativeFile);
-            if (!r2Objects.has(entry.storageKey)) {
+            if (!stagedObjects.has(`r2:${entry.storageKey}`)) {
                 await mkdir(path.dirname(targetFile), { recursive: true });
                 await copyFile(sourceFile, targetFile);
-                r2Objects.set(entry.storageKey, {
+                hasR2 = true;
+                stagedObjects.set(`r2:${entry.storageKey}`, {
+                    kind: 'search',
                     path: entry.path,
                     mediaType: entry.mediaType,
+                    storageKind: 'r2',
                     storageKey: entry.storageKey,
                     file: relativeFile,
                     byteSize: entry.byteSize,
@@ -288,17 +342,15 @@ async function writeExternalBinaryStaging(rootDir, outDir, manifest, options) {
         }
     }
     return {
-        version: 1,
+        version: 2,
         workerEntry: 'worker.mjs',
         binaryMode: options.binaryMode,
-        assetsMaxBytes: options.binaryMode === 'external' ? options.assetsMaxBytes : undefined,
-        assetsDir: options.binaryMode === 'external' ? 'assets' : undefined,
-        r2Dir: options.binaryMode === 'external' ? 'r2' : undefined,
-        r2Binding: options.binaryMode === 'external' && r2Objects.size > 0
-            ? options.r2Binding
-            : undefined,
+        assetsMaxBytes: options.binaryMode === 'external' || searchDir ? options.assetsMaxBytes : undefined,
+        assetsDir: hasAssets ? 'assets' : undefined,
+        r2Dir: hasR2 ? 'r2' : undefined,
+        r2Binding: hasR2 ? options.r2Binding : undefined,
         siteTitle: options.siteTitle,
-        r2Objects: Array.from(r2Objects.values()).sort((left, right) => left.storageKey.localeCompare(right.storageKey)),
+        stagedObjects: Array.from(stagedObjects.values()).sort((left, right) => left.storageKey.localeCompare(right.storageKey)),
     };
 }
 async function readCloudflareBundleMetadata(workerEntry) {
@@ -309,7 +361,32 @@ async function readCloudflareBundleMetadata(workerEntry) {
     return readBundleMetadataFile(bundleFile);
 }
 async function readBundleMetadataFile(bundleFile) {
-    return JSON.parse(await readFile(bundleFile, 'utf8'));
+    const parsed = JSON.parse(await readFile(bundleFile, 'utf8'));
+    if ('stagedObjects' in parsed && Array.isArray(parsed.stagedObjects)) {
+        return parsed;
+    }
+    if ('r2Objects' in parsed && Array.isArray(parsed.r2Objects)) {
+        return {
+            version: 2,
+            workerEntry: parsed.workerEntry,
+            binaryMode: parsed.binaryMode,
+            assetsMaxBytes: parsed.assetsMaxBytes,
+            assetsDir: parsed.assetsDir,
+            r2Dir: parsed.r2Dir,
+            r2Binding: parsed.r2Binding,
+            siteTitle: parsed.siteTitle,
+            stagedObjects: parsed.r2Objects.map((object) => ({
+                kind: 'binary',
+                path: object.path,
+                mediaType: object.mediaType,
+                storageKind: 'r2',
+                storageKey: object.storageKey,
+                file: object.file,
+                byteSize: object.byteSize,
+            })),
+        };
+    }
+    throw new Error(`Bundle metadata in ${bundleFile} is not supported. Rebuild the Cloudflare bundle with the current mdorigin CLI.`);
 }
 async function readR2SyncState(stateFile) {
     if (!(await pathExists(stateFile))) {
@@ -371,31 +448,39 @@ async function listFiles(directory, visitedRealDirectories = new Set()) {
     }
     return files;
 }
-async function readBundleEntries(directory) {
+async function buildSearchBundleEntries(directory, assetsMaxBytes) {
     const files = await listFiles(directory);
     const entries = [];
     for (const filePath of files) {
         const relativePath = path.relative(directory, filePath).replaceAll(path.sep, '/');
         const mediaType = getMediaTypeForPath(relativePath);
-        if (isLikelyTextPath(relativePath) || relativePath.endsWith('.json')) {
+        const fileStats = await stat(filePath);
+        if (fileStats.size <= assetsMaxBytes) {
             entries.push({
                 path: relativePath,
-                kind: 'text',
                 mediaType,
-                text: await readFile(filePath, 'utf8'),
+                storageKind: 'assets',
+                storageKey: `${SEARCH_ASSETS_PREFIX}/${relativePath}`,
+                byteSize: fileStats.size,
             });
             continue;
         }
         entries.push({
             path: relativePath,
-            kind: 'binary',
             mediaType,
-            base64: (await readFile(filePath)).toString('base64'),
+            storageKind: 'r2',
+            storageKey: await buildSearchStorageKey(filePath, relativePath),
+            byteSize: fileStats.size,
         });
     }
     entries.sort((left, right) => left.path.localeCompare(right.path));
     return entries;
 }
+async function buildSearchStorageKey(filePath, relativePath) {
+    const extension = path.posix.extname(relativePath).toLowerCase();
+    const hash = await hashFile(filePath);
+    return extension ? `search/${hash}${extension}` : `search/${hash}`;
+}
 async function pathExists(filePath) {
     try {
         await stat(filePath);

package/dist/core/api.js

@@ -13,10 +13,15 @@ export async function handleApiRoute(pathname, searchParams, options) {
             });
         }
         const topK = normalizePositiveInteger(searchParams?.get('topK')) ?? 10;
-        const hits = await options.searchApi.search(query, { topK });
+        const metadata = readSearchMetadataFilters(searchParams);
+        const hits = await options.searchApi.search(query, {
+            topK,
+            metadata,
+        });
         return json(200, {
             query,
             topK,
+            metadata,
             count: hits.length,
             hits: hits.map(serializeSearchHit),
         });
@@ -56,6 +61,13 @@ function buildOpenApiDocument(options) {
                             schema: { type: 'integer', minimum: 1, default: 10 },
                             description: 'Maximum number of hits to return.',
                         },
+                        {
+                            name: 'meta.<field>',
+                            in: 'query',
+                            required: false,
+                            schema: { type: 'string' },
+                            description: 'Exact-match metadata filter. Use query parameters such as meta.type=post or meta.section=guides.',
+                        },
                     ],
                     responses: {
                         '200': {
@@ -68,6 +80,10 @@ function buildOpenApiDocument(options) {
                                         properties: {
                                             query: { type: 'string' },
                                             topK: { type: 'integer' },
+                                            metadata: {
+                                                type: 'object',
+                                                additionalProperties: { type: 'string' },
+                                            },
                                             count: { type: 'integer' },
                                             hits: {
                                                 type: 'array',
@@ -130,6 +146,23 @@ function buildOpenApiDocument(options) {
         },
     };
 }
+function readSearchMetadataFilters(searchParams) {
+    if (!searchParams) {
+        return undefined;
+    }
+    const metadata = {};
+    for (const [key, value] of searchParams.entries()) {
+        if (!key.startsWith('meta.') || value.trim() === '') {
+            continue;
+        }
+        const metadataKey = key.slice('meta.'.length).trim();
+        if (metadataKey === '') {
+            continue;
+        }
+        metadata[metadataKey] = value;
+    }
+    return Object.keys(metadata).length > 0 ? metadata : undefined;
+}
 function serializeSearchHit(hit) {
     return {
         docId: hit.docId,

package/dist/core/markdown.d.ts

@@ -28,5 +28,6 @@ export declare function parseMarkdownDocument(sourcePath: string, markdown: stri
 export declare function renderMarkdown(markdown: string): Promise<string>;
 export declare function rewriteMarkdownLinksInHtml(html: string): string;
 export declare function stripManagedIndexBlock(markdown: string): string;
+export declare function stripMachineOnlyMarkdownComments(markdown: string): string;
 export declare function stripManagedIndexLinks(markdown: string, hrefs: ReadonlySet<string>): string;
 export declare function extractManagedIndexEntries(markdown: string): ManagedIndexEntry[];

package/dist/core/markdown.js

@@ -38,6 +38,9 @@ export function rewriteMarkdownLinksInHtml(html) {
 export function stripManagedIndexBlock(markdown) {
     return markdown.replace(/\n?<!-- INDEX:START -->[\s\S]*?<!-- INDEX:END -->\n?/g, '\n').trimEnd();
 }
+export function stripMachineOnlyMarkdownComments(markdown) {
+    return markdown.replace(/<!--\s*mdorigin:[\s\S]*?-->/g, '');
+}
 export function stripManagedIndexLinks(markdown, hrefs) {
     if (hrefs.size === 0) {
         return markdown;

package/dist/search.d.ts

@@ -19,11 +19,13 @@ export interface SearchHit {
         score: number;
     };
 }
+export interface SearchQueryOptions {
+    topK?: number;
+    relativePathPrefix?: string;
+    metadata?: Record<string, string>;
+}
 export interface SearchApi {
-    search(query: string, options?: {
-        topK?: number;
-        relativePathPrefix?: string;
-    }): Promise<SearchHit[]>;
+    search(query: string, options?: SearchQueryOptions): Promise<SearchHit[]>;
 }
 export interface SearchBundleEntry {
     path: string;
@@ -32,6 +34,13 @@ export interface SearchBundleEntry {
     text?: string;
     base64?: string;
 }
+export interface ExternalSearchBundleEntry {
+    path: string;
+    mediaType: string;
+    storageKind: 'assets' | 'r2';
+    storageKey: string;
+    byteSize: number;
+}
 export interface BuildSearchBundleOptions {
     rootDir: string;
     outDir: string;
@@ -39,21 +48,35 @@ export interface BuildSearchBundleOptions {
     draftMode?: 'include' | 'exclude';
     embeddingBackend?: 'hashing' | 'model2vec';
     model?: string;
+    incremental?: boolean;
+    cachePath?: string;
 }
 export interface BuildSearchBundleResult {
     outputDir: string;
     documentCount: number;
     chunkCount: number;
     vectorDimensions: number;
+    cachePath?: string;
+    incremental?: {
+        scannedDocumentCount: number;
+        newDocumentCount: number;
+        changedDocumentCount: number;
+        unchangedDocumentCount: number;
+        removedDocumentCount: number;
+        activeDocumentCount: number;
+        activeChunkCount: number;
+    };
 }
 export interface SearchBundleOptions {
     indexDir: string;
     query: string;
     topK?: number;
     relativePathPrefix?: string;
+    metadata?: Record<string, string>;
 }
 export declare function buildSearchBundle(options: BuildSearchBundleOptions): Promise<BuildSearchBundleResult>;
 export declare function searchBundle(options: SearchBundleOptions): Promise<SearchHit[]>;
 export declare function createSearchApiFromDirectory(indexDir: string): Promise<SearchApi>;
 export declare function createSearchApiFromBundle(bundleEntries: SearchBundleEntry[]): SearchApi;
+export declare function createSearchApiFromExternalBundle(bundleEntries: ExternalSearchBundleEntry[], loadResponse: (entry: ExternalSearchBundleEntry) => Promise<Response>): SearchApi;
 export {};

package/dist/search.js

@@ -1,60 +1,100 @@
-import { readdir, readFile, realpath, stat } from 'node:fs/promises';
+import { rmSync } from 'node:fs';
+import { mkdtemp, mkdir, readdir, readFile, realpath, stat, writeFile, } from 'node:fs/promises';
+import os from 'node:os';
 import path from 'node:path';
 import { inferDirectoryContentType } from './core/content-type.js';
 import { getDirectoryIndexCandidates } from './core/directory-index.js';
-import { getDocumentSummary, getDocumentTitle, parseMarkdownDocument, } from './core/markdown.js';
+import { getDocumentSummary, getDocumentTitle, parseMarkdownDocument, stripMachineOnlyMarkdownComments, stripManagedIndexBlock, } from './core/markdown.js';
 import { isIgnoredContentName } from './core/content-store.js';
+const OVERVIEW_CONTENT_FILENAMES = new Set(['readme.md', 'index.md', 'skill.md']);
+const materializedSearchBundleDirectories = new Set();
+let searchBundleDirectoryCleanupRegistered = false;
 export async function buildSearchBundle(options) {
     const buildModule = await loadIndexbindBuildModule();
     const rootDir = path.resolve(options.rootDir);
+    const outputDir = path.resolve(options.outDir);
     const documents = await collectSearchDocuments(rootDir, options.siteConfig, {
         draftMode: options.draftMode ?? 'exclude',
     });
-    const stats = await buildModule.buildCanonicalBundle(path.resolve(options.outDir), documents, {
+    const buildOptions = {
         embeddingBackend: options.embeddingBackend ?? 'model2vec',
         model: options.model,
         sourceRootId: path.basename(rootDir),
         sourceRootPath: rootDir,
-    });
+    };
+    if (options.incremental) {
+        const cachePath = path.resolve(options.cachePath ?? defaultSearchBuildCachePath(outputDir));
+        await mkdir(path.dirname(cachePath), { recursive: true });
+        const removedRelativePaths = await resolveRemovedRelativePaths(cachePath, documents.map((document) => document.relativePath));
+        const incrementalStats = await buildModule.updateBuildCache(cachePath, documents, buildOptions, removedRelativePaths);
+        const stats = await buildModule.exportCanonicalBundleFromBuildCache(cachePath, outputDir);
+        await writeSearchBuildState(cachePath, documents.map((document) => document.relativePath));
+        return {
+            outputDir,
+            documentCount: stats.documentCount,
+            chunkCount: stats.chunkCount,
+            vectorDimensions: stats.vectorDimensions,
+            cachePath,
+            incremental: incrementalStats,
+        };
+    }
+    const stats = await buildModule.buildCanonicalBundle(outputDir, documents, buildOptions);
     return {
-        outputDir: path.resolve(options.outDir),
+        outputDir,
         documentCount: stats.documentCount,
         chunkCount: stats.chunkCount,
         vectorDimensions: stats.vectorDimensions,
     };
 }
 export async function searchBundle(options) {
-    const webModule = await loadIndexbindWebModule();
-    const index = await webModule.openWebIndex(path.resolve(options.indexDir));
-    return rerankSearchHits(await index.search(options.query, {
+    const searchContext = await openSearchContextFromDirectory(path.resolve(options.indexDir));
+    return rerankSearchHits(hydrateSearchHits(await searchContext.index.search(options.query, buildIndexbindSearchOptions({
         topK: options.topK ?? 10,
         relativePathPrefix: options.relativePathPrefix,
-    }));
+        metadata: options.metadata,
+    })), searchContext.documentsById));
 }
 export async function createSearchApiFromDirectory(indexDir) {
-    const webModule = await loadIndexbindWebModule();
-    const index = await webModule.openWebIndex(path.resolve(indexDir));
+    const searchContext = await openSearchContextFromDirectory(path.resolve(indexDir));
     return {
         async search(query, options) {
-            return rerankSearchHits(await index.search(query, {
+            return rerankSearchHits(hydrateSearchHits(await searchContext.index.search(query, buildIndexbindSearchOptions({
                 topK: options?.topK,
                 relativePathPrefix: options?.relativePathPrefix,
-            }));
+                metadata: options?.metadata,
+            })), searchContext.documentsById));
         },
     };
 }
 export function createSearchApiFromBundle(bundleEntries) {
-    let indexPromise = null;
+    let searchContextPromise = null;
+    return {
+        async search(query, options) {
+            if (searchContextPromise === null) {
+                searchContextPromise = openSearchContextFromBundle(bundleEntries, async (entry) => createInlineSearchBundleResponse(entry));
+            }
+            const searchContext = await searchContextPromise;
+            return rerankSearchHits(hydrateSearchHits(await searchContext.index.search(query, buildIndexbindSearchOptions({
+                topK: options?.topK,
+                relativePathPrefix: options?.relativePathPrefix,
+                metadata: options?.metadata,
+            })), searchContext.documentsById));
+        },
+    };
+}
+export function createSearchApiFromExternalBundle(bundleEntries, loadResponse) {
+    let searchContextPromise = null;
     return {
         async search(query, options) {
-            if (indexPromise === null) {
-                indexPromise = openWebIndexFromBundle(bundleEntries);
+            if (searchContextPromise === null) {
+                searchContextPromise = openSearchContextFromBundle(bundleEntries, loadResponse);
             }
-            const index = await indexPromise;
-            return rerankSearchHits(await index.search(query, {
+            const searchContext = await searchContextPromise;
+            return rerankSearchHits(hydrateSearchHits(await searchContext.index.search(query, buildIndexbindSearchOptions({
                 topK: options?.topK,
                 relativePathPrefix: options?.relativePathPrefix,
-            }));
+                metadata: options?.metadata,
+            })), searchContext.documentsById));
         },
     };
 }
@@ -78,12 +118,15 @@ async function collectSearchDocuments(rootDir, siteConfig, options) {
             canonicalUrl: absoluteCanonicalUrl,
             title: getDocumentTitle(parsed.meta, parsed.body, fallbackTitleFromRelativePath(document.relativePath)),
             summary: getDocumentSummary(parsed.meta, parsed.body),
-            content: markdown,
+            content: buildSearchableMarkdownBody(parsed.body),
             metadata: buildSearchMetadata(document.relativePath, canonicalPath, parsed.meta, siteConfig),
         });
     }
     return documents;
 }
+function buildSearchableMarkdownBody(markdownBody) {
+    return stripMachineOnlyMarkdownComments(stripManagedIndexBlock(markdownBody)).trim();
+}
 async function listSearchDocuments(rootDir) {
     const results = [];
     await walkDirectory(rootDir, '', new Set(), results);
@@ -197,6 +240,8 @@ function buildSearchMetadata(relativePath, canonicalPath, meta, siteConfig) {
         markdownPath: `/${relativePath}`,
         canonicalPath,
         siteTitle: siteConfig.siteTitle,
+        section: getSearchSection(relativePath),
+        isOverview: isOverviewContentPath(relativePath),
     };
     if (meta.type === 'page' || meta.type === 'post') {
         metadata.type = meta.type;
@@ -212,6 +257,17 @@ function buildSearchMetadata(relativePath, canonicalPath, meta, siteConfig) {
     }
     return metadata;
 }
+function getSearchSection(relativePath) {
+    const directory = path.posix.dirname(relativePath.replaceAll('\\', '/'));
+    if (directory === '.') {
+        return '';
+    }
+    const [firstSegment] = directory.split('/', 1);
+    return firstSegment ?? '';
+}
+function isOverviewContentPath(relativePath) {
+    return OVERVIEW_CONTENT_FILENAMES.has(path.posix.basename(relativePath).toLowerCase());
+}
 function fallbackTitleFromRelativePath(relativePath) {
     const baseName = path.posix.basename(relativePath);
     if (DIRECTORY_INDEX_FILENAMES_LOWER.has(baseName.toLowerCase())) {
@@ -250,6 +306,33 @@ async function pathExists(filePath) {
         throw error;
     }
 }
+function defaultSearchBuildCachePath(outputDir) {
+    return path.join(path.dirname(outputDir), `${path.basename(outputDir)}.indexbind-cache.sqlite`);
+}
+function getSearchBuildStatePath(cachePath) {
+    return `${cachePath}.state.json`;
+}
+async function resolveRemovedRelativePaths(cachePath, currentRelativePaths) {
+    const previousRelativePaths = await readSearchBuildState(cachePath);
+    const current = new Set(currentRelativePaths);
+    return previousRelativePaths.filter((relativePath) => !current.has(relativePath));
+}
+async function readSearchBuildState(cachePath) {
+    const statePath = getSearchBuildStatePath(cachePath);
+    if (!(await pathExists(statePath))) {
+        return [];
+    }
+    const parsed = JSON.parse(await readFile(statePath, 'utf8'));
+    return Array.isArray(parsed.relativePaths)
+        ? parsed.relativePaths.filter((value) => typeof value === 'string')
+        : [];
+}
+async function writeSearchBuildState(cachePath, relativePaths) {
+    await writeFile(getSearchBuildStatePath(cachePath), JSON.stringify({
+        version: 1,
+        relativePaths: [...relativePaths].sort((left, right) => left.localeCompare(right)),
+    }, null, 2), 'utf8');
+}
 function isIgnoredSkillSupportDirectory(name) {
     return (name === 'scripts' ||
         name === 'references' ||
@@ -280,8 +363,10 @@ async function loadIndexbindCloudflareModule() {
         throw new Error(`Search query requires the optional package "indexbind". Install it first, for example: npm install indexbind`, { cause: error instanceof Error ? error : undefined });
     }
 }
-async function openWebIndexFromBundle(bundleEntries) {
-    const cloudflareModule = await loadIndexbindCloudflareModule();
+async function openWebIndexFromVirtualBundle(bundleEntries, loadResponse) {
+    if (isNodeRuntime()) {
+        return openWebIndexFromMaterializedBundle(bundleEntries, loadResponse);
+    }
     const baseUrl = 'https://mdorigin-search.invalid/';
     const originalFetch = globalThis.fetch;
     const bundleMap = new Map(bundleEntries.map((entry) => [new URL(entry.path, baseUrl).toString(), entry]));
@@ -293,31 +378,209 @@ async function openWebIndexFromBundle(bundleEntries) {
                 : input.url;
         const entry = bundleMap.get(requestUrl);
         if (entry) {
-            const headers = new Headers({ 'content-type': entry.mediaType });
-            const binaryBody = decodeBase64(entry.base64 ?? '');
-            const body = entry.kind === 'text'
-                ? entry.text ?? ''
-                : new Blob([new Uint8Array(binaryBody)], {
-                    type: entry.mediaType,
-                });
-            return new Response(body, {
-                status: 200,
-                headers,
-            });
+            return loadResponse(entry);
         }
         return originalFetch(input, init);
     };
     try {
-        return await cloudflareModule.openWebIndex(new URL(baseUrl));
+        try {
+            const cloudflareModule = await loadIndexbindCloudflareModule();
+            return await cloudflareModule.openWebIndex(new URL(baseUrl));
+        }
+        catch (error) {
+            if (!isCloudflareWasmImportError(error)) {
+                throw error;
+            }
+            const webModule = await loadIndexbindWebModule();
+            return await webModule.openWebIndex(new URL(baseUrl));
+        }
     }
     finally {
         globalThis.fetch = originalFetch;
     }
 }
+async function openSearchContextFromDirectory(indexDir) {
+    const webModule = await loadIndexbindWebModule();
+    const [index, documentsById] = await Promise.all([
+        webModule.openWebIndex(indexDir),
+        readSearchBundleDocumentsFromDirectory(indexDir),
+    ]);
+    return { index, documentsById };
+}
+async function openSearchContextFromBundle(bundleEntries, loadResponse) {
+    const [index, documentsById] = await Promise.all([
+        openWebIndexFromVirtualBundle(bundleEntries, loadResponse),
+        readSearchBundleDocumentsFromResponses(bundleEntries, loadResponse),
+    ]);
+    return { index, documentsById };
+}
+async function openWebIndexFromMaterializedBundle(bundleEntries, loadResponse) {
+    const tempDir = await mkdtemp(path.join(os.tmpdir(), 'mdorigin-search-bundle-'));
+    registerMaterializedSearchBundleDirectory(tempDir);
+    for (const entry of bundleEntries) {
+        const response = await loadResponse(entry);
+        if (!response.ok) {
+            throw new Error(`Failed to materialize search bundle file ${entry.path}: ${response.status} ${response.statusText}`);
+        }
+        const outputPath = resolveMaterializedSearchBundlePath(tempDir, entry.path);
+        await mkdir(path.dirname(outputPath), { recursive: true });
+        if (entry.mediaType.startsWith('text/') || entry.mediaType.includes('json')) {
+            await writeFile(outputPath, await response.text(), 'utf8');
+            continue;
+        }
+        await writeFile(outputPath, new Uint8Array(await response.arrayBuffer()));
+    }
+    const webModule = await loadIndexbindWebModule();
+    return webModule.openWebIndex(tempDir);
+}
+function createInlineSearchBundleResponse(entry) {
+    const headers = new Headers({ 'content-type': entry.mediaType });
+    const binaryBody = decodeBase64(entry.base64 ?? '');
+    const body = entry.kind === 'text'
+        ? entry.text ?? ''
+        : new Blob([new Uint8Array(binaryBody)], {
+            type: entry.mediaType,
+        });
+    return new Response(body, {
+        status: 200,
+        headers,
+    });
+}
+function isCloudflareWasmImportError(error) {
+    const targetMessages = [
+        'Unknown file extension ".wasm"',
+        'WebAssembly.Module(): Argument 0 must be a buffer source',
+    ];
+    const visited = new Set();
+    let current = error;
+    while (current && typeof current === 'object' && !visited.has(current)) {
+        visited.add(current);
+        if (current instanceof Error) {
+            const currentMessage = current.message;
+            if (targetMessages.some((message) => currentMessage.includes(message))) {
+                return true;
+            }
+        }
+        const cause = current.cause;
+        if (!cause) {
+            break;
+        }
+        current = cause;
+    }
+    return false;
+}
 function decodeBase64(value) {
     const decoded = atob(value);
     return Uint8Array.from(decoded, (character) => character.charCodeAt(0));
 }
+function buildIndexbindSearchOptions(options) {
+    const normalized = {};
+    if (typeof options.topK === 'number' &&
+        Number.isFinite(options.topK) &&
+        Number.isInteger(options.topK) &&
+        options.topK > 0) {
+        normalized.topK = options.topK;
+    }
+    if (typeof options.relativePathPrefix === 'string' && options.relativePathPrefix !== '') {
+        normalized.relativePathPrefix = options.relativePathPrefix;
+    }
+    if (options.metadata && Object.keys(options.metadata).length > 0) {
+        normalized.metadata = options.metadata;
+    }
+    return Object.keys(normalized).length > 0 ? normalized : undefined;
+}
+function hydrateSearchHits(hits, documentsById) {
+    return hits.map((hit) => {
+        const document = documentsById.get(hit.docId);
+        if (!document) {
+            return hit;
+        }
+        return {
+            ...hit,
+            canonicalUrl: hit.canonicalUrl ?? document.canonicalUrl ?? undefined,
+            title: hit.title ?? document.title ?? undefined,
+            summary: hit.summary ?? document.summary ?? undefined,
+            metadata: Object.keys(hit.metadata).length > 0
+                ? hit.metadata
+                : document.metadata ?? hit.metadata,
+        };
+    });
+}
+async function readSearchBundleDocumentsFromDirectory(indexDir) {
+    const manifest = JSON.parse(await readFile(path.join(indexDir, 'manifest.json'), 'utf8'));
+    const documentsFile = manifest.files?.documents;
+    if (!documentsFile) {
+        return new Map();
+    }
+    const documents = JSON.parse(await readFile(path.join(indexDir, documentsFile), 'utf8'));
+    return new Map(documents.map((document) => [document.docId, document]));
+}
+async function readSearchBundleDocumentsFromResponses(bundleEntries, loadResponse) {
+    const manifestEntry = bundleEntries.find((entry) => entry.path === 'manifest.json');
+    if (!manifestEntry) {
+        return new Map();
+    }
+    const manifest = JSON.parse(await loadBundleResponseText(manifestEntry, loadResponse));
+    const documentsFile = manifest.files?.documents;
+    if (!documentsFile) {
+        return new Map();
+    }
+    const documentsEntry = bundleEntries.find((entry) => entry.path === documentsFile);
+    if (!documentsEntry) {
+        return new Map();
+    }
+    const documents = JSON.parse(await loadBundleResponseText(documentsEntry, loadResponse));
+    return new Map(documents.map((document) => [document.docId, document]));
+}
+async function loadBundleResponseText(entry, loadResponse) {
+    const response = await loadResponse(entry);
+    if (!response.ok) {
+        throw new Error(`Failed to read search bundle file ${entry.path}: ${response.status} ${response.statusText}`);
+    }
+    return response.text();
+}
+function isNodeRuntime() {
+    return (typeof process !== 'undefined' &&
+        typeof process.versions === 'object' &&
+        typeof process.versions.node === 'string');
+}
+function resolveMaterializedSearchBundlePath(baseDir, entryPath) {
+    if (path.isAbsolute(entryPath)) {
+        throw new Error(`Search bundle path must be relative: ${entryPath}`);
+    }
+    const normalizedEntryPath = entryPath.replaceAll('/', path.sep);
+    const outputPath = path.resolve(baseDir, normalizedEntryPath);
+    const relativeOutputPath = path.relative(baseDir, outputPath);
+    if (relativeOutputPath === '' ||
+        relativeOutputPath.startsWith(`..${path.sep}`) ||
+        relativeOutputPath === '..' ||
+        path.isAbsolute(relativeOutputPath)) {
+        throw new Error(`Search bundle path escapes materialized bundle directory: ${entryPath}`);
+    }
+    return outputPath;
+}
+function registerMaterializedSearchBundleDirectory(directoryPath) {
+    materializedSearchBundleDirectories.add(directoryPath);
+    if (searchBundleDirectoryCleanupRegistered || !isNodeRuntime()) {
+        return;
+    }
+    const cleanup = () => {
+        for (const stagedDirectory of materializedSearchBundleDirectories) {
+            rmSync(stagedDirectory, { recursive: true, force: true });
+        }
+        materializedSearchBundleDirectories.clear();
+    };
+    process.once('exit', cleanup);
+    process.once('SIGINT', () => {
+        cleanup();
+        process.exit(130);
+    });
+    process.once('SIGTERM', () => {
+        cleanup();
+        process.exit(143);
+    });
+    searchBundleDirectoryCleanupRegistered = true;
+}
 function rerankSearchHits(hits) {
     const remaining = [...hits];
     const ordered = [];
@@ -360,8 +623,7 @@ function compareHits(left, right) {
     return left.relativePath.localeCompare(right.relativePath);
 }
 function isOverviewSearchHit(hit) {
-    const baseName = path.posix.basename(hit.relativePath).toLowerCase();
-    return baseName === 'readme.md' || baseName === 'index.md';
+    return OVERVIEW_CONTENT_FILENAMES.has(path.posix.basename(hit.relativePath).toLowerCase());
 }
 function getTopLevelSection(relativePath) {
     const normalized = relativePath.replaceAll('\\', '/');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdorigin",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "Markdown-first publishing for humans and agents.",
   "repository": {
@@ -78,6 +78,6 @@
     "typescript": "^5.9.2"
   },
   "optionalDependencies": {
-    "indexbind": "^0.2.1"
+    "indexbind": "^0.3.0"
   }
 }