svedocs 0.1.0-beta.2

package/dist/og/types.d.ts

@@ -0,0 +1,59 @@
+export interface OgImageInput {
+    title: string;
+    description?: string;
+    siteName?: string;
+}
+export type OgRenderer = 'svg' | 'satori';
+export interface OgFont {
+    name: string;
+    data: ArrayBuffer | Uint8Array;
+    weight?: 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
+    style?: 'normal' | 'italic';
+}
+export interface OgTemplateNode {
+    type: string;
+    props: {
+        style?: Record<string, string | number>;
+        children?: string | OgTemplateNode | OgTemplateNode[];
+        [key: string]: unknown;
+    };
+}
+export type OgTemplate = (input: OgImageInput) => OgTemplateNode;
+export interface OgRenderOptions {
+    renderer?: OgRenderer;
+    fonts?: OgFont[];
+    template?: OgTemplate;
+}
+export interface OgImageOptions extends OgRenderOptions {
+    format?: 'svg' | 'png';
+}
+export interface SvedocsPageMetadata {
+    title: string;
+    description: string;
+    canonical?: string;
+    image?: string;
+    openGraph: {
+        title: string;
+        description: string;
+        type: string;
+        url?: string;
+        image?: string;
+        siteName: string;
+        author?: string;
+        publishedTime?: string;
+        updatedTime?: string;
+    };
+    twitter: {
+        card: 'summary' | 'summary_large_image';
+        title: string;
+        description: string;
+        image?: string;
+    };
+    jsonLd: Record<string, unknown>;
+}
+export interface SvedocsPageAlternate {
+    lang: string;
+    href: string;
+    locale?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/og/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/og/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,QAAQ,CAAC;AAE1C,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,WAAW,GAAG,UAAU,CAAC;IAC/B,MAAM,CAAC,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;IAC7D,KAAK,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;CAC7B;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE;QACL,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;QACxC,QAAQ,CAAC,EAAE,MAAM,GAAG,cAAc,GAAG,cAAc,EAAE,CAAC;QACtD,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;CACH;AAED,MAAM,MAAM,UAAU,GAAG,CAAC,KAAK,EAAE,YAAY,KAAK,cAAc,CAAC;AAEjE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,UAAU,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,CAAC,EAAE,UAAU,CAAC;CACvB;AAED,MAAM,WAAW,cAAe,SAAQ,eAAe;IACrD,MAAM,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;CACxB;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,EAAE;QACT,KAAK,EAAE,MAAM,CAAC;QACd,WAAW,EAAE,MAAM,CAAC;QACpB,IAAI,EAAE,MAAM,CAAC;QACb,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;IACJ,OAAO,EAAE;QACP,IAAI,EAAE,SAAS,GAAG,qBAAqB,CAAC;QACxC,KAAK,EAAE,MAAM,CAAC;QACd,WAAW,EAAE,MAAM,CAAC;QACpB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}

package/dist/og/types.js

@@ -0,0 +1 @@
+export {};

package/dist/og.d.ts

@@ -0,0 +1,4 @@
+export * from './og/types.js';
+export * from './og/metadata.js';
+export * from './og/image.js';
+//# sourceMappingURL=og.d.ts.map

package/dist/og.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"og.d.ts","sourceRoot":"","sources":["../src/og.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC"}

package/dist/og.js

@@ -0,0 +1,3 @@
+export * from './og/types.js';
+export * from './og/metadata.js';
+export * from './og/image.js';

package/dist/search/algolia.d.ts

@@ -0,0 +1,10 @@
+import type { SearchProvider, SearchQuery } from './types.js';
+export interface AlgoliaSearchProviderOptions {
+    appId: string;
+    apiKey: string;
+    indexName: string;
+    filters?: string | ((query: SearchQuery) => string | undefined);
+    fetch?: typeof fetch;
+}
+export declare function createAlgoliaSearchProvider(options: AlgoliaSearchProviderOptions): SearchProvider;
+//# sourceMappingURL=algolia.d.ts.map

package/dist/search/algolia.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"algolia.d.ts","sourceRoot":"","sources":["../../src/search/algolia.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAgB,MAAM,YAAY,CAAC;AAG5E,MAAM,WAAW,4BAA4B;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE,WAAW,KAAK,MAAM,GAAG,SAAS,CAAC,CAAC;IAChE,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAyBD,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,4BAA4B,GAAG,cAAc,CAgCjG"}

package/dist/search/algolia.js

@@ -0,0 +1,82 @@
+import { matchesSearchScope } from './local.js';
+import { createExcerpt, stringMetadata, stringifyMetadata } from './utils.js';
+export function createAlgoliaSearchProvider(options) {
+    return {
+        name: 'algolia',
+        index() {
+            // Algolia indexing is usually handled by DocSearch crawlers or user CI.
+        },
+        async search(query) {
+            const requestFetch = options.fetch ?? fetch;
+            const filters = createAlgoliaFilters(options, query);
+            const response = await requestFetch(createAlgoliaQueryEndpoint(options), {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    'x-algolia-application-id': options.appId,
+                    'x-algolia-api-key': options.apiKey
+                },
+                body: JSON.stringify({
+                    query: query.query,
+                    hitsPerPage: query.limit ?? 10,
+                    ...(filters ? { filters } : {}),
+                    attributesToSnippet: ['content:30']
+                })
+            });
+            if (!response.ok) {
+                throw new Error(`Algolia search returned ${response.status}: ${(await response.text()).slice(0, 500)}`);
+            }
+            const payload = await response.json();
+            return (payload.hits ?? [])
+                .map((hit, index) => createAlgoliaResult(hit, index, query.query))
+                .filter((result) => matchesSearchScope({ metadata: result.metadata }, query));
+        }
+    };
+}
+function createAlgoliaQueryEndpoint(options) {
+    return `https://${encodeURIComponent(options.appId)}-dsn.algolia.net/1/indexes/${encodeURIComponent(options.indexName)}/query`;
+}
+function createAlgoliaFilters(options, query) {
+    return typeof options.filters === 'function' ? options.filters(query) : options.filters;
+}
+function createAlgoliaResult(hit, index, query) {
+    const metadata = stringifyMetadata({
+        ...(hit.metadata ?? {}),
+        locale: hit.locale ?? hit.metadata?.locale,
+        kind: hit.kind ?? hit.metadata?.kind
+    });
+    const hierarchyTitle = readHierarchy(hit.hierarchy, ['lvl0', 'lvl1', 'lvl2']);
+    const title = hit.title ?? hierarchyTitle ?? 'Result';
+    const section = hit.section ?? readHierarchy(hit.hierarchy, ['lvl6', 'lvl5', 'lvl4', 'lvl3', 'lvl2', 'lvl1']);
+    const content = stripHtml(readSnippet(hit) ?? hit.content ?? title);
+    return {
+        id: hit.objectID ?? `algolia:${index}`,
+        title,
+        url: createAlgoliaUrl(hit),
+        ...(section && section !== title ? { section } : {}),
+        excerpt: createExcerpt(content, query),
+        score: 1 / (index + 1),
+        metadata
+    };
+}
+function createAlgoliaUrl(hit) {
+    const url = hit.url ?? '#';
+    if (!hit.anchor || url.includes('#'))
+        return url;
+    return `${url}#${hit.anchor}`;
+}
+function readSnippet(hit) {
+    return stringMetadata(hit._snippetResult?.content?.value)
+        ?? stringMetadata(hit._highlightResult?.content?.value);
+}
+function readHierarchy(hierarchy, keys) {
+    for (const key of keys) {
+        const value = stringMetadata(hierarchy?.[key]);
+        if (value)
+            return stripHtml(value);
+    }
+    return undefined;
+}
+function stripHtml(value) {
+    return value.replace(/<[^>]+>/g, '').replace(/&nbsp;/g, ' ').trim();
+}

package/dist/search/cloudflare-sync.d.ts

@@ -0,0 +1,5 @@
+import type { SvedocsSearchRecord } from '../core.js';
+import type { CloudflareAiSearchSyncDocument, CloudflareAiSearchSyncOptions, CloudflareAiSearchSyncResult } from './types.js';
+export declare function createCloudflareAiSearchDocuments(records: SvedocsSearchRecord[]): CloudflareAiSearchSyncDocument[];
+export declare function syncCloudflareAiSearchIndex(options: CloudflareAiSearchSyncOptions): Promise<CloudflareAiSearchSyncResult>;
+//# sourceMappingURL=cloudflare-sync.d.ts.map

package/dist/search/cloudflare-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudflare-sync.d.ts","sourceRoot":"","sources":["../../src/search/cloudflare-sync.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,KAAK,EACV,8BAA8B,EAC9B,6BAA6B,EAC7B,4BAA4B,EAC7B,MAAM,YAAY,CAAC;AAGpB,wBAAgB,iCAAiC,CAAC,OAAO,EAAE,mBAAmB,EAAE,GAAG,8BAA8B,EAAE,CAwBlH;AAED,wBAAsB,2BAA2B,CAC/C,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,4BAA4B,CAAC,CAgEvC"}

package/dist/search/cloudflare-sync.js

@@ -0,0 +1,169 @@
+import { chunkArray, stringifyMetadata, uniqueStrings, wait } from './utils.js';
+export function createCloudflareAiSearchDocuments(records) {
+    return records.map((record) => ({
+        id: record.id,
+        title: record.section ? `${record.title}: ${record.section}` : record.title,
+        url: record.url,
+        content: [
+            `# ${record.section ? `${record.title}: ${record.section}` : record.title}`,
+            '',
+            `URL: ${record.url}`,
+            '',
+            record.content
+        ].join('\n'),
+        metadata: stringifyMetadata({
+            svedocs: JSON.stringify({
+                id: record.id,
+                pageId: record.pageId,
+                title: record.title,
+                section: record.section ?? '',
+                url: record.url
+            }),
+            locale: record.metadata.locale,
+            kind: record.metadata.kind
+        })
+    }));
+}
+export async function syncCloudflareAiSearchIndex(options) {
+    const endpoint = options.endpoint ?? createCloudflareAiSearchItemsEndpoint(options);
+    const dryRun = options.dryRun ?? (!options.accountId || !options.apiToken);
+    const documents = createCloudflareAiSearchDocuments(options.records);
+    const uploadIds = documents.map((document) => document.id);
+    const deleteIds = createCloudflareDeletePlan(options, uploadIds);
+    const result = {
+        provider: 'cloudflare-ai-search',
+        instanceName: options.instanceName,
+        endpoint,
+        dryRun,
+        indexed: dryRun ? documents.length : 0,
+        deleted: dryRun ? deleteIds.length : 0,
+        failed: 0,
+        planned: {
+            uploadIds,
+            deleteIds
+        },
+        errors: []
+    };
+    if (dryRun)
+        return result;
+    if (!options.apiToken) {
+        throw new Error('CLOUDFLARE_API_TOKEN is required to index Cloudflare AI Search.');
+    }
+    const requestFetch = options.fetch ?? fetch;
+    const batchSize = options.batchSize ?? 10;
+    const maxRetries = options.maxRetries ?? 2;
+    const retryDelayMs = options.retryDelayMs ?? 250;
+    await processBatches(deleteIds, batchSize, async (itemId) => {
+        try {
+            await withRetry(() => deleteCloudflareAiSearchItem(endpoint, itemId, options.apiToken, requestFetch), {
+                maxRetries,
+                retryDelayMs
+            });
+            result.deleted += 1;
+        }
+        catch (error) {
+            result.failed += 1;
+            result.errors.push({
+                id: itemId,
+                message: error instanceof Error ? error.message : 'Cloudflare AI Search delete failed.'
+            });
+        }
+    });
+    await processBatches(documents, batchSize, async (document) => {
+        try {
+            await withRetry(() => uploadCloudflareAiSearchDocument(endpoint, document, options, requestFetch), {
+                maxRetries,
+                retryDelayMs
+            });
+            result.indexed += 1;
+        }
+        catch (error) {
+            result.failed += 1;
+            result.errors.push({
+                id: document.id,
+                message: error instanceof Error ? error.message : 'Cloudflare AI Search upload failed.'
+            });
+        }
+    });
+    return result;
+}
+function createCloudflareAiSearchItemsEndpoint(options) {
+    if (!options.accountId)
+        return 'https://api.cloudflare.com/client/v4/accounts/<account_id>/ai-search/instances/<instance_name>/items';
+    const account = encodeURIComponent(options.accountId);
+    const instance = encodeURIComponent(options.instanceName);
+    if (options.namespace) {
+        return `https://api.cloudflare.com/client/v4/accounts/${account}/ai-search/namespaces/${encodeURIComponent(options.namespace)}/instances/${instance}/items`;
+    }
+    return `https://api.cloudflare.com/client/v4/accounts/${account}/ai-search/instances/${instance}/items`;
+}
+function createCloudflareAiSearchItemEndpoint(itemsEndpoint, itemId) {
+    return `${itemsEndpoint.replace(/\/$/, '')}/${encodeURIComponent(itemId)}`;
+}
+function createCloudflareDeletePlan(options, uploadIds) {
+    const explicitDeletes = options.deleteIds ?? [];
+    if (options.strategy !== 'replace')
+        return uniqueStrings(explicitDeletes);
+    const uploadSet = new Set(uploadIds);
+    return uniqueStrings([
+        ...explicitDeletes,
+        ...(options.existingIds ?? []).filter((itemId) => !uploadSet.has(itemId))
+    ]);
+}
+function createCloudflareItemFilename(document) {
+    const safe = document.id.replace(/[^a-zA-Z0-9_-]+/g, '-').replace(/^-|-$/g, '') || 'svedocs-page';
+    return `${safe.slice(0, 124)}.md`;
+}
+async function deleteCloudflareAiSearchItem(endpoint, itemId, apiToken, requestFetch) {
+    const response = await requestFetch(createCloudflareAiSearchItemEndpoint(endpoint, itemId), {
+        method: 'DELETE',
+        headers: {
+            authorization: `Bearer ${apiToken}`
+        }
+    });
+    if (!response.ok) {
+        throw new Error(await createCloudflareApiErrorMessage(response, 'delete'));
+    }
+}
+async function uploadCloudflareAiSearchDocument(endpoint, document, options, requestFetch) {
+    const form = new FormData();
+    form.append('file', new Blob([document.content], { type: 'text/markdown' }), createCloudflareItemFilename(document));
+    form.append('metadata', JSON.stringify(document.metadata));
+    if (typeof options.waitForCompletion === 'boolean') {
+        form.append('wait_for_completion', String(options.waitForCompletion));
+    }
+    const response = await requestFetch(endpoint, {
+        method: 'POST',
+        headers: {
+            authorization: `Bearer ${options.apiToken}`
+        },
+        body: form
+    });
+    if (!response.ok) {
+        throw new Error(await createCloudflareApiErrorMessage(response, 'upload'));
+    }
+}
+async function createCloudflareApiErrorMessage(response, action) {
+    const body = await response.text().catch(() => '');
+    return `Cloudflare AI Search ${action} returned ${response.status}${body ? `: ${body.slice(0, 500)}` : ''}`;
+}
+async function processBatches(items, batchSize, handler) {
+    for (const batch of chunkArray(items, batchSize)) {
+        await Promise.all(batch.map((item) => handler(item)));
+    }
+}
+async function withRetry(action, options) {
+    let attempt = 0;
+    while (true) {
+        try {
+            await action();
+            return;
+        }
+        catch (error) {
+            if (attempt >= options.maxRetries)
+                throw error;
+            attempt += 1;
+            await wait(options.retryDelayMs * attempt);
+        }
+    }
+}

package/dist/search/cloudflare.d.ts

@@ -0,0 +1,9 @@
+import type { CloudflareAiSearchInput, CloudflareAiSearchInstance, CloudflareAiSearchOutput, CloudflareAiSearchNamespace, SearchResult, SearchProvider } from './types.js';
+export declare function createCloudflareAiSearchProvider(input: {
+    binding: CloudflareAiSearchInstance | CloudflareAiSearchNamespace;
+    instanceName?: string;
+}): SearchProvider;
+export declare function runCloudflareAiSearch(binding: CloudflareAiSearchInstance | CloudflareAiSearchNamespace, instanceName: string | undefined, input: CloudflareAiSearchInput): Promise<CloudflareAiSearchOutput>;
+export declare function normalizeCloudflareAiSearchResults(result: CloudflareAiSearchOutput, query: string): SearchResult[];
+export declare function resolveAiSearchInstance(binding: CloudflareAiSearchInstance | CloudflareAiSearchNamespace, instanceName?: string): CloudflareAiSearchInstance;
+//# sourceMappingURL=cloudflare.d.ts.map

package/dist/search/cloudflare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudflare.d.ts","sourceRoot":"","sources":["../../src/search/cloudflare.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAEV,uBAAuB,EACvB,0BAA0B,EAE1B,wBAAwB,EACxB,2BAA2B,EAC3B,YAAY,EACZ,cAAc,EACf,MAAM,YAAY,CAAC;AAIpB,wBAAgB,gCAAgC,CAAC,KAAK,EAAE;IACtD,OAAO,EAAE,0BAA0B,GAAG,2BAA2B,CAAC;IAClE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GAAG,cAAc,CA0BjB;AAED,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,0BAA0B,GAAG,2BAA2B,EACjE,YAAY,oBAAY,EACxB,KAAK,EAAE,uBAAuB,GAC7B,OAAO,CAAC,wBAAwB,CAAC,CASnC;AAED,wBAAgB,kCAAkC,CAAC,MAAM,EAAE,wBAAwB,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,EAAE,CAKlH;AAED,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,0BAA0B,GAAG,2BAA2B,EACjE,YAAY,SAAY,GACvB,0BAA0B,CAE5B"}

package/dist/search/cloudflare.js

@@ -0,0 +1,115 @@
+import { matchesSearchScope } from './local.js';
+import { createExcerpt, stringMetadata, stringifyMetadata } from './utils.js';
+export function createCloudflareAiSearchProvider(input) {
+    return {
+        name: 'cloudflare-ai-search',
+        index() {
+            // Cloudflare AI Search indexing is intentionally handled by CLI/provider sync.
+        },
+        async search(query) {
+            const maxResults = query.limit ?? 10;
+            const result = await runCloudflareAiSearch(input.binding, input.instanceName, {
+                messages: [
+                    {
+                        role: 'user',
+                        content: query.query
+                    }
+                ],
+                ai_search_options: {
+                    retrieval: {
+                        retrieval_type: 'hybrid',
+                        max_num_results: maxResults
+                    }
+                }
+            });
+            return normalizeCloudflareAiSearchResults(result, query.query)
+                .filter((record) => matchesSearchScope({ metadata: record.metadata }, query));
+        }
+    };
+}
+export async function runCloudflareAiSearch(binding, instanceName = 'svedocs', input) {
+    const instance = resolveAiSearchInstance(binding, instanceName);
+    const aiSearchOptions = createAiSearchOptions(input);
+    const messages = input.messages;
+    return instance.search({
+        ...(messages ? { messages } : {}),
+        ...(!messages && input.query ? { query: input.query } : {}),
+        ...(aiSearchOptions ? { ai_search_options: aiSearchOptions } : {})
+    });
+}
+export function normalizeCloudflareAiSearchResults(result, query) {
+    if (result.data?.length) {
+        return result.data.map((item, index) => createResultFromItem(item, index, query, result.response ?? result.answer));
+    }
+    return (result.chunks ?? []).map((chunk, index) => createResultFromChunk(chunk, index, query, result.response ?? result.answer));
+}
+export function resolveAiSearchInstance(binding, instanceName = 'svedocs') {
+    return 'get' in binding ? binding.get(instanceName) : binding;
+}
+function mergeRetrieval(options, retrieval) {
+    return {
+        ...(options ?? {}),
+        retrieval: {
+            ...(options?.retrieval ?? {}),
+            ...retrieval
+        }
+    };
+}
+function createAiSearchOptions(input) {
+    const retrieval = typeof input.max_num_results === 'number' ? { max_num_results: input.max_num_results } : {};
+    return input.ai_search_options || Object.keys(retrieval).length > 0
+        ? mergeRetrieval(input.ai_search_options, retrieval)
+        : undefined;
+}
+function createResultFromItem(item, index, query, fallbackContent = '') {
+    const metadata = normalizeCloudflareMetadata(item.metadata ?? {});
+    const section = stringMetadata(metadata.section);
+    return {
+        id: item.id ?? `cloudflare:${index}`,
+        title: item.title ?? stringMetadata(metadata.title) ?? 'Result',
+        url: item.url ?? stringMetadata(metadata.url) ?? '#',
+        ...(section ? { section } : {}),
+        excerpt: createExcerpt(item.content ?? item.text ?? fallbackContent, query),
+        score: typeof item.score === 'number' ? item.score : 1 / (index + 1),
+        metadata
+    };
+}
+function createResultFromChunk(chunk, index, query, fallbackContent = '') {
+    const metadata = normalizeCloudflareMetadata({
+        ...(chunk.attributes ?? {}),
+        ...(chunk.metadata ?? {}),
+        ...(chunk.item?.metadata ?? {})
+    });
+    const section = stringMetadata(metadata.section);
+    return {
+        id: chunk.id ?? stringMetadata(chunk.item?.id) ?? stringMetadata(chunk.item?.key) ?? `cloudflare:${index}`,
+        title: stringMetadata(metadata.title) ??
+            stringMetadata(chunk.item?.title) ??
+            stringMetadata(chunk.item?.filename) ??
+            stringMetadata(chunk.item?.key) ??
+            'Result',
+        url: stringMetadata(metadata.url) ?? stringMetadata(metadata.source_url) ?? '#',
+        ...(section ? { section } : {}),
+        excerpt: createExcerpt(chunk.text ?? chunk.content ?? stringMetadata(metadata.content) ?? fallbackContent, query),
+        score: typeof chunk.score === 'number' ? chunk.score : 1 / (index + 1),
+        metadata
+    };
+}
+function normalizeCloudflareMetadata(metadata) {
+    const stringified = stringifyMetadata(metadata);
+    const embedded = stringMetadata(metadata.svedocs);
+    if (!embedded)
+        return stringified;
+    try {
+        const parsed = JSON.parse(embedded);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return stringified;
+        return {
+            ...stringified,
+            ...stringifyMetadata(parsed)
+        };
+    }
+    catch {
+        return stringified;
+    }
+}

package/dist/search/local.d.ts

@@ -0,0 +1,9 @@
+import type { SvedocsSearchRecord } from '../core.js';
+import type { SearchProvider, SearchQuery, SearchResult, SearchScope } from './types.js';
+export declare function createLocalSearchProvider(records?: SvedocsSearchRecord[]): SearchProvider;
+export declare const localSearchProvider: SearchProvider;
+export declare function searchRecords(records: SvedocsSearchRecord[], input: SearchQuery): SearchResult[];
+export declare function filterSearchRecords(records: SvedocsSearchRecord[], scope?: SearchScope): SvedocsSearchRecord[];
+export declare function matchesSearchScope(record: SvedocsSearchRecord, scope?: SearchScope): boolean;
+export declare function createSearchResponse(records: SvedocsSearchRecord[], request: Request): Promise<Response>;
+//# sourceMappingURL=local.d.ts.map

package/dist/search/local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../src/search/local.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAoBzF,wBAAgB,yBAAyB,CAAC,OAAO,GAAE,mBAAmB,EAAO,GAAG,cAAc,CAW7F;AAED,eAAO,MAAM,mBAAmB,gBAA8B,CAAC;AAE/D,wBAAgB,aAAa,CAAC,OAAO,EAAE,mBAAmB,EAAE,EAAE,KAAK,EAAE,WAAW,GAAG,YAAY,EAAE,CAkChG;AAED,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,mBAAmB,EAAE,EAC9B,KAAK,GAAE,WAAgB,GACtB,mBAAmB,EAAE,CAEvB;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,mBAAmB,EAAE,KAAK,GAAE,WAAgB,GAAG,OAAO,CAGhG;AAED,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,mBAAmB,EAAE,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAa9G"}

package/dist/search/local.js

@@ -0,0 +1,122 @@
+import MiniSearch from 'minisearch';
+import { createExcerpt, jsonResponse, normalizeSearchText } from './utils.js';
+const miniSearchCache = new WeakMap();
+export function createLocalSearchProvider(records = []) {
+    let indexed = records;
+    return {
+        name: 'local-json',
+        index(nextRecords) {
+            indexed = nextRecords;
+        },
+        search(input) {
+            return searchRecords(indexed, input);
+        }
+    };
+}
+export const localSearchProvider = createLocalSearchProvider();
+export function searchRecords(records, input) {
+    const query = normalizeSearchText(input.query);
+    if (!query)
+        return [];
+    const entry = getMiniSearchIndex(records);
+    const scoped = entry.index.search(input.query, {
+        prefix: true,
+        fuzzy: (term) => term.length > 4 ? 0.18 : false,
+        combineWith: 'AND',
+        boost: {
+            title: 5,
+            section: 4,
+            url: 1.5,
+            metadataText: 0.8,
+            content: 1
+        }
+    });
+    return scoped
+        .map((hit) => {
+        const record = entry.recordsById.get(hit.id);
+        return record ? { record, score: Number(hit.score.toFixed(4)) } : undefined;
+    })
+        .filter((item) => Boolean(item))
+        .filter((item) => matchesSearchScope(item.record, input))
+        .slice(0, input.limit ?? 10)
+        .map(({ record, score }) => ({
+        id: record.id,
+        title: record.title,
+        url: record.url,
+        ...(record.section ? { section: record.section } : {}),
+        excerpt: createExcerpt(record.content, input.query),
+        score,
+        metadata: record.metadata
+    }));
+}
+export function filterSearchRecords(records, scope = {}) {
+    return records.filter((record) => matchesSearchScope(record, scope));
+}
+export function matchesSearchScope(record, scope = {}) {
+    return matchesMetadata(record.metadata.locale, scope.locale)
+        && matchesMetadata(record.metadata.kind, scope.kind);
+}
+export async function createSearchResponse(records, request) {
+    const url = new URL(request.url);
+    const query = url.searchParams.get('q') ?? url.searchParams.get('query') ?? '';
+    const limit = clampLimit(Number(url.searchParams.get('limit') ?? 10));
+    const locale = readScopeParam(url, 'locale');
+    const kind = readScopeParam(url, 'kind');
+    const results = searchRecords(records, {
+        query,
+        limit,
+        ...(locale ? { locale } : {}),
+        ...(kind ? { kind } : {})
+    });
+    return jsonResponse({ query, results });
+}
+function getMiniSearchIndex(records) {
+    const cached = miniSearchCache.get(records);
+    if (cached)
+        return cached;
+    const documents = records.map(toMiniSearchDocument);
+    const index = new MiniSearch({
+        fields: ['title', 'section', 'url', 'content', 'metadataText'],
+        storeFields: ['id', 'title', 'section', 'url', 'content', 'metadata'],
+        idField: 'id',
+        searchOptions: {
+            prefix: true,
+            fuzzy: 0.18
+        },
+        processTerm: (term) => normalizeSearchText(term)
+    });
+    index.addAll(documents);
+    const entry = {
+        index,
+        recordsById: new Map(records.map((record) => [record.id, record]))
+    };
+    miniSearchCache.set(records, entry);
+    return entry;
+}
+function toMiniSearchDocument(record) {
+    return {
+        id: record.id,
+        title: record.title,
+        section: record.section ?? '',
+        url: record.url,
+        content: record.content,
+        metadataText: Object.values(record.metadata).flat().join(' '),
+        metadata: record.metadata
+    };
+}
+function matchesMetadata(value, expected) {
+    if (!expected)
+        return true;
+    if (Array.isArray(value))
+        return value.some((item) => String(item) === expected);
+    return value === expected;
+}
+function readScopeParam(url, key) {
+    const value = url.searchParams.get(key);
+    return value?.trim() || undefined;
+}
+function clampLimit(value) {
+    if (!Number.isFinite(value))
+        return 10;
+    return Math.min(50, Math.max(1, Math.floor(value)));
+}

package/dist/search/runtime.d.ts

@@ -0,0 +1,41 @@
+import type { SvedocsResolvedConfig, SvedocsSearchRecord } from '../core.js';
+import type { CloudflareAiSearchInstance, CloudflareAiSearchNamespace, SearchProvider, SearchQuery } from './types.js';
+export interface SvedocsSearchRuntimeEnv {
+    SVEDOCS_AI_SEARCH?: CloudflareAiSearchInstance | CloudflareAiSearchNamespace | undefined;
+    ALGOLIA_APP_ID?: string | undefined;
+    ALGOLIA_SEARCH_KEY?: string | undefined;
+    ALGOLIA_API_KEY?: string | undefined;
+    ALGOLIA_INDEX_NAME?: string | undefined;
+    SVEDOCS_ALGOLIA_APP_ID?: string | undefined;
+    SVEDOCS_ALGOLIA_SEARCH_KEY?: string | undefined;
+    SVEDOCS_ALGOLIA_API_KEY?: string | undefined;
+    SVEDOCS_ALGOLIA_INDEX_NAME?: string | undefined;
+    TYPESENSE_HOST?: string | undefined;
+    TYPESENSE_URL?: string | undefined;
+    TYPESENSE_SEARCH_KEY?: string | undefined;
+    TYPESENSE_API_KEY?: string | undefined;
+    TYPESENSE_COLLECTION?: string | undefined;
+    TYPESENSE_COLLECTION_NAME?: string | undefined;
+    SVEDOCS_TYPESENSE_HOST?: string | undefined;
+    SVEDOCS_TYPESENSE_URL?: string | undefined;
+    SVEDOCS_TYPESENSE_SEARCH_KEY?: string | undefined;
+    SVEDOCS_TYPESENSE_API_KEY?: string | undefined;
+    SVEDOCS_TYPESENSE_COLLECTION?: string | undefined;
+    SVEDOCS_TYPESENSE_COLLECTION_NAME?: string | undefined;
+    [key: string]: unknown;
+}
+export interface CreateConfiguredSearchProviderOptions {
+    config: Pick<SvedocsResolvedConfig, 'search' | 'cloudflare'>;
+    records?: SvedocsSearchRecord[];
+    env?: SvedocsSearchRuntimeEnv;
+    provider?: string;
+    fetch?: typeof fetch;
+}
+export interface CreateConfiguredSearchResponseOptions extends Omit<CreateConfiguredSearchProviderOptions, 'config' | 'records' | 'provider'> {
+    provider?: string;
+}
+export declare function createConfiguredSearchProvider(options: CreateConfiguredSearchProviderOptions): SearchProvider;
+export declare function createConfiguredSearchResponse(config: Pick<SvedocsResolvedConfig, 'search' | 'cloudflare'>, records: SvedocsSearchRecord[], request: Request, options?: CreateConfiguredSearchResponseOptions): Promise<Response>;
+export declare function readSearchQuery(request: Request): SearchQuery;
+export declare function readProviderParam(request: Request): string | undefined;
+//# sourceMappingURL=runtime.d.ts.map