@perxel/spotlight 0.0.0-stage → 0.1.1

package/dist/server/sources.js

@@ -0,0 +1,315 @@
+import { jsonSchema, tool } from "ai";
+import { buildIndex, fold, search } from "../core/search.js";
+// ---------------------------------------------------------------------------------------------
+// toolSource: the site's own functions
+/**
+ * The site's own AI SDK tools (live numbers, filters over structured data, an outside API), run
+ * in the same route. A function gets the request context (locale, say) and returns the tools.
+ */
+export function toolSource(tools, { name = "site" } = {}) {
+    return { name, tools: (ctx) => (typeof tools === "function" ? tools(ctx) : tools) };
+}
+const STOP = new Set(["the", "and", "for", "you", "your", "what", "which", "how", "does", "did", "are", "was", "with", "about", "from", "this", "that", "have", "has", "can", "any", "all", "who", "why", "when", "where", "much", "many"]);
+/** The query's words worth matching in body text: folded, 3+ characters, common English words out. */
+function terms(query) {
+    return [...new Set(fold(query).split(" ").filter((t) => t.length >= 3 && !STOP.has(t)))];
+}
+/** Up to `count` paragraphs of `body` holding the most terms, each cut around its first match. */
+export function passagesOf(body, words, count, length) {
+    if (!words.length || !count)
+        return [];
+    const paragraphs = body.split(/\n\s*\n/).map((p) => p.replace(/\s+/g, " ").trim()).filter((p) => p.length > 40 && !p.startsWith("#"));
+    const scored = paragraphs
+        .map((p, i) => {
+        const f = fold(p);
+        return { p, i, f, n: words.filter((w) => f.includes(w)).length };
+    })
+        .filter((x) => x.n > 0)
+        .sort((a, b) => b.n - a.n || a.i - b.i)
+        .slice(0, count)
+        .sort((a, b) => a.i - b.i);
+    return scored.map(({ p, f }) => {
+        if (p.length <= length)
+            return p;
+        const at = Math.min(...words.map((w) => f.indexOf(w)).filter((i) => i >= 0));
+        // Folding keeps lengths close enough for a window; cut on spaces.
+        let start = Math.max(0, at - Math.floor(length * 0.3));
+        if (start > 0)
+            start = p.indexOf(" ", start) + 1 || start;
+        let end = Math.min(p.length, start + length);
+        if (end < p.length)
+            end = p.lastIndexOf(" ", end) > start ? p.lastIndexOf(" ", end) : end;
+        return (start > 0 ? "… " : "") + p.slice(start, end).trim() + (end < p.length ? " …" : "");
+    });
+}
+/** A plain-text heading: a short line with no closing punctuation, alone in its paragraph. */
+function plainHeading(lines, i) {
+    const l = lines[i].trim();
+    return l.length > 0 && l.length <= 80 && !/[.:;,!?)]$/.test(l) && !lines[i - 1]?.trim() && !lines[i + 1]?.trim();
+}
+/**
+ * The section of a body under the heading that matches `section`: a markdown heading (until the
+ * next one of its level or higher), else, for plain text where headings became their own lines,
+ * a short heading-like line (until the next one).
+ */
+export function sectionOf(body, section) {
+    const lines = body.split("\n");
+    const want = fold(section);
+    const at = lines.findIndex((l) => /^#{1,6}\s/.test(l) && fold(l.replace(/^#+\s*/, "")).includes(want));
+    if (at >= 0) {
+        const level = lines[at].match(/^#+/)[0].length;
+        let end = lines.findIndex((l, i) => i > at && /^#{1,6}\s/.test(l) && l.match(/^#+/)[0].length <= level);
+        if (end < 0)
+            end = lines.length;
+        return lines.slice(at, end).join("\n").trim();
+    }
+    const plain = lines.findIndex((l, i) => plainHeading(lines, i) && fold(l).includes(want));
+    if (plain < 0)
+        return null;
+    let end = lines.findIndex((_, i) => i > plain && plainHeading(lines, i));
+    if (end < 0)
+        end = lines.length;
+    return lines.slice(plain, end).join("\n").trim();
+}
+function headingsOf(body) {
+    const lines = body.split("\n");
+    const md = lines.filter((l) => /^#{2,3}\s/.test(l)).map((l) => l.replace(/^#+\s*/, "").trim());
+    return md.length ? md : lines.filter((_, i) => plainHeading(lines, i)).map((l) => l.trim());
+}
+/**
+ * Search and read the site's own pages, with no MCP: two tools built from the same documents as
+ * the gate's search plus their full text. Answers stay cheap: a search returns a few short
+ * passages per hit (most answers need nothing more), a page is capped or read one section at a
+ * time.
+ */
+export function contentSource(options) {
+    const { baseUrl, maxHits = 5, passages = 2, passageLength = 320, pageLength = 6000, about = "this website's pages and posts" } = options;
+    const searchName = options.names?.search ?? "search_site";
+    const pageName = options.names?.page ?? "get_page";
+    const abs = (url) => (baseUrl && url.startsWith("/") ? baseUrl.replace(/\/$/, "") + url : url);
+    // Docs and their index are built once per list (per isolate when the list is a constant).
+    const cache = new WeakMap();
+    return {
+        name: options.name ?? "content",
+        async tools(ctx) {
+            const docs = (typeof options.docs === "function" ? await options.docs(ctx) : options.docs).filter((d) => d.url);
+            const bodies = typeof options.bodies === "function" ? await options.bodies(ctx) : options.bodies ?? {};
+            const bodyOf = (d) => d.body ?? bodies[d.id] ?? "";
+            let index = cache.get(docs);
+            if (!index) {
+                index = buildIndex(docs);
+                cache.set(docs, index);
+            }
+            const idx = index;
+            const byUrl = (url) => {
+                const path = url.replace(/^https?:\/\/[^/]+/, "").replace(/\/$/, "") || "/";
+                return docs.find((d) => d.url === url || (d.url.replace(/^https?:\/\/[^/]+/, "").replace(/\/$/, "") || "/") === path);
+            };
+            const searchTool = tool({
+                description: `Searches ${about}: titles, descriptions and full text. Returns the best hits (title, url, kind, excerpt) ` +
+                    `with the passages of each page that match the query. Use ${pageName} only when the passages do not answer.`,
+                inputSchema: jsonSchema({
+                    type: "object",
+                    properties: { query: { type: "string", description: "Keywords to look for", minLength: 1 } },
+                    required: ["query"],
+                    additionalProperties: false,
+                }),
+                execute: async ({ query }) => {
+                    const words = terms(query);
+                    // Title and keyword matches from the search engine, then full-text matches.
+                    const fromIndex = search(idx, query, { limit: 20 });
+                    const scores = new Map();
+                    fromIndex.forEach((r) => scores.set(r.doc, r.score));
+                    if (words.length) {
+                        for (const d of docs) {
+                            const body = bodyOf(d);
+                            if (!body)
+                                continue;
+                            const f = fold(body);
+                            const n = words.filter((w) => f.includes(w)).length;
+                            if (n)
+                                scores.set(d, (scores.get(d) ?? 0) + n * 3);
+                        }
+                    }
+                    const hits = [...scores].sort((a, b) => b[1] - a[1]).slice(0, maxHits);
+                    return {
+                        results: hits.map(([d], i) => {
+                            const excerpt = d.snippets?.at(-1) ?? d.subtitle ?? "";
+                            const p = i < 3 ? passagesOf(bodyOf(d), words, passages, passageLength) : [];
+                            return {
+                                title: d.title,
+                                url: abs(d.url),
+                                kind: d.kind,
+                                ...(excerpt ? { excerpt: excerpt.slice(0, 300) } : {}),
+                                ...(p.length ? { passages: p } : {}),
+                            };
+                        }),
+                    };
+                },
+            });
+            const pageTool = tool({
+                description: `Reads one page of ${about} by its url (from ${searchName}): its text, capped; pass a section heading to read only that section.`,
+                inputSchema: jsonSchema({
+                    type: "object",
+                    properties: {
+                        url: { type: "string", description: "The page's url, as returned by search" },
+                        section: { type: "string", description: "Optional: a section heading to read only that part" },
+                    },
+                    required: ["url"],
+                    additionalProperties: false,
+                }),
+                execute: async ({ url, section }) => {
+                    const d = byUrl(url);
+                    if (!d)
+                        return { error: "No page with that url." };
+                    const body = bodyOf(d) || [d.subtitle, ...(d.snippets ?? [])].filter(Boolean).join("\n\n");
+                    const part = section ? sectionOf(body, section) : null;
+                    const text = part ?? body;
+                    const truncated = text.length > pageLength;
+                    return {
+                        title: d.title,
+                        url: abs(d.url),
+                        text: truncated ? text.slice(0, pageLength) + " …" : text,
+                        ...(truncated ? { truncated: true, sections: headingsOf(body) } : {}),
+                    };
+                },
+            });
+            return { [searchName]: searchTool, [pageName]: pageTool };
+        },
+    };
+}
+let rpcId = 0;
+const lists = new Map();
+const sessions = new Map();
+/** One JSON-RPC call over streamable HTTP; the answer may be JSON or an SSE stream. */
+async function rpc(url, method, params, headers, timeoutMs, fetcher) {
+    const id = ++rpcId;
+    const session = sessions.get(url);
+    const res = await fetcher(url, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            accept: "application/json, text/event-stream",
+            ...(session ? { "mcp-session-id": session } : {}),
+            ...headers,
+        },
+        body: JSON.stringify({ jsonrpc: "2.0", id, method, ...(params === undefined ? {} : { params }) }),
+        signal: AbortSignal.timeout(timeoutMs),
+    });
+    const sid = res.headers.get("mcp-session-id");
+    if (sid)
+        sessions.set(url, sid);
+    if (!res.ok)
+        throw new McpHttpError(res.status, await res.text().catch(() => ""));
+    let msg;
+    if ((res.headers.get("content-type") ?? "").includes("text/event-stream")) {
+        const text = await res.text();
+        for (const block of text.split(/\n\n/)) {
+            const data = block.split("\n").filter((l) => l.startsWith("data:")).map((l) => l.slice(5).trim()).join("\n");
+            if (!data)
+                continue;
+            try {
+                const m = JSON.parse(data);
+                if (m.id === id || (m.id === undefined && (m.result || m.error)))
+                    msg = m;
+            }
+            catch {
+                // Not JSON: skip.
+            }
+        }
+    }
+    else
+        msg = (await res.json());
+    if (!msg)
+        throw new Error(`MCP ${method}: no response`);
+    if (msg.error)
+        throw new Error(`MCP ${method}: ${msg.error.message ?? "error"}`);
+    return msg.result;
+}
+class McpHttpError extends Error {
+    status;
+    constructor(status, body) {
+        super(`MCP HTTP ${status}: ${body.slice(0, 200)}`);
+        this.status = status;
+    }
+}
+/** Calls `method`; a server that needs a session gets `initialize` first, then the call again. */
+async function call(url, method, params, headers, timeoutMs, fetcher) {
+    try {
+        return await rpc(url, method, params, headers, timeoutMs, fetcher);
+    }
+    catch (err) {
+        if (!(err instanceof McpHttpError) || ![400, 404].includes(err.status))
+            throw err;
+        sessions.delete(url);
+        await rpc(url, "initialize", { protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: "@perxel/spotlight", version: "0" } }, headers, timeoutMs, fetcher);
+        await fetcher(url, {
+            method: "POST",
+            headers: { "content-type": "application/json", accept: "application/json, text/event-stream", ...(sessions.get(url) ? { "mcp-session-id": sessions.get(url) } : {}), ...headers },
+            body: JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" }),
+        }).catch(() => undefined);
+        return rpc(url, method, params, headers, timeoutMs, fetcher);
+    }
+}
+/** A tool result's data: `structuredContent`, else its text parsed as JSON, else the text. */
+function resultData(result) {
+    const r = result;
+    if (r?.structuredContent !== undefined)
+        return r.structuredContent;
+    const text = (r?.content ?? []).filter((c) => c.type === "text").map((c) => c.text ?? "").join("\n");
+    const data = (() => {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    })();
+    return r?.isError ? { error: data } : data;
+}
+/**
+ * Tools on a remote MCP server, called over streamable HTTP with no SDK (works on any runtime
+ * with `fetch`). The tool list is fetched once and kept for `listTtlMs`. Use `tools` to allowlist:
+ * an anonymous chat must only reach tools meant for the public.
+ */
+export function mcpSource(options) {
+    const { url, listTtlMs = 5 * 60 * 1000, timeoutMs = 15_000, fetcher = fetch } = options;
+    return {
+        name: options.name ?? "mcp",
+        async tools(ctx) {
+            const headers = typeof options.headers === "function" ? await options.headers(ctx) : options.headers ?? {};
+            let cached = lists.get(url);
+            if (!cached || Date.now() - cached.at > listTtlMs) {
+                const result = (await call(url, "tools/list", {}, headers, timeoutMs, fetcher));
+                cached = { at: Date.now(), tools: result.tools ?? [] };
+                lists.set(url, cached);
+            }
+            const fixed = options.fixed?.(ctx) ?? {};
+            const out = {};
+            for (const def of cached.tools) {
+                if (options.tools && !options.tools.includes(def.name))
+                    continue;
+                const schema = { type: "object", properties: {}, ...def.inputSchema };
+                // Fixed arguments are the site's, not the model's: out of the schema the model sees.
+                const hidden = Object.keys(fixed).filter((k) => k in (schema.properties ?? {}));
+                const properties = Object.fromEntries(Object.entries(schema.properties ?? {}).filter(([k]) => !hidden.includes(k)));
+                const required = (schema.required ?? []).filter((k) => !hidden.includes(k));
+                const { $schema: _drop, ...rest } = schema;
+                out[def.name] = tool({
+                    description: def.description ?? def.name,
+                    inputSchema: jsonSchema({ ...rest, properties, required }),
+                    execute: async (input) => {
+                        const args = { ...input, ...Object.fromEntries(hidden.map((k) => [k, fixed[k]])) };
+                        return resultData(await call(url, "tools/call", { name: def.name, arguments: args }, headers, timeoutMs, fetcher));
+                    },
+                });
+            }
+            return out;
+        },
+    };
+}
+/** Test hook: forget the cached tool lists and sessions. */
+export function resetMcpCache() {
+    lists.clear();
+    sessions.clear();
+}

package/dist/server/turnstile.d.ts

@@ -0,0 +1,15 @@
+import type { AskContext } from "./types.js";
+export interface TurnstileOptions {
+    secret: string | undefined;
+    /** The body field holding the token (default `turnstileToken`). */
+    field?: string;
+    /** Accept only tokens issued on these hostnames (default: any the site key allows). */
+    hostnames?: string[];
+    fetcher?: typeof fetch;
+}
+/**
+ * A `verify` check: Cloudflare Turnstile. The client sends a fresh token with every question (a
+ * token is single use; the client widget makes the next one in the background). No secret: every
+ * request is refused, so a missing environment variable never opens the endpoint.
+ */
+export declare function turnstile({ secret, field, hostnames, fetcher }: TurnstileOptions): (ctx: AskContext) => Promise<boolean>;

package/dist/server/turnstile.js

@@ -0,0 +1,29 @@
+const SITEVERIFY = "https://challenges.cloudflare.com/turnstile/v0/siteverify";
+/**
+ * A `verify` check: Cloudflare Turnstile. The client sends a fresh token with every question (a
+ * token is single use; the client widget makes the next one in the background). No secret: every
+ * request is refused, so a missing environment variable never opens the endpoint.
+ */
+export function turnstile({ secret, field = "turnstileToken", hostnames, fetcher = fetch }) {
+    return async (ctx) => {
+        const token = ctx.body[field];
+        if (!secret || typeof token !== "string" || !token || token.length > 2048)
+            return false;
+        const form = new FormData();
+        form.set("secret", secret);
+        form.set("response", token);
+        const ip = ctx.request.headers.get("cf-connecting-ip") ?? ctx.request.headers.get("x-forwarded-for")?.split(",")[0]?.trim();
+        if (ip)
+            form.set("remoteip", ip);
+        try {
+            const res = await fetcher(SITEVERIFY, { method: "POST", body: form });
+            const out = (await res.json());
+            if (!out.success)
+                return false;
+            return !hostnames || (!!out.hostname && hostnames.includes(out.hostname));
+        }
+        catch {
+            return false;
+        }
+    };
+}

package/dist/server/types.d.ts

@@ -0,0 +1,34 @@
+import type { ToolSet } from "ai";
+/** What every check, source and hook gets about the request. */
+export interface AskContext {
+    request: Request;
+    /** The request body's own fields, `messages` left out (locale, page, a bot-check token). */
+    body: Record<string, unknown>;
+    /** The chat id the client sent, if any. */
+    id: string | null;
+    /** The visitor's question (the last message's text). */
+    question: string;
+    /** The conversation before it, text only. */
+    history: {
+        role: "user" | "assistant";
+        text: string;
+    }[];
+}
+/** A set of tools for the model. `contentSource`, `toolSource` and `mcpSource` make them. */
+export interface AskSource {
+    /** Prefixes this source's tools when a name is already taken by an earlier source. */
+    name: string;
+    tools(ctx: AskContext): ToolSet | Promise<ToolSet>;
+}
+/** A tool run in one turn. */
+export interface ToolRun {
+    name: string;
+    ms: number;
+    ok: boolean;
+    input: unknown;
+}
+/** A cited source. */
+export interface Cited {
+    url: string;
+    title: string;
+}

package/dist/server/types.js

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

package/dist/types.d.ts

@@ -0,0 +1,207 @@
+import type { ComponentType, ReactNode } from "react";
+import type { SearchDoc } from "./core/search.js";
+export type { SearchDoc, SearchIndex, SearchOptions, SearchResult, Snippet } from "./core/search.js";
+/**
+ * A chat message, structurally the AI SDK's `UIMessage` (so `useChat` messages fit), without
+ * importing `ai`: the core and the search parts never load the AI SDK.
+ */
+export interface ChatMessage {
+    id: string;
+    role: "system" | "user" | "assistant";
+    parts: ChatPart[];
+    metadata?: unknown;
+}
+export type ChatPart = {
+    type: string;
+} & Record<string, unknown>;
+export interface SearchConfig {
+    /** The documents, when they are already in the page's code (small sets). */
+    docs?: SearchDoc[];
+    /**
+     * Load the documents lazily (recommended): a dynamic `import()` of a generated JSON file, so
+     * the index is a chunk of its own, fetched when the gate opens. A module with a `default`
+     * export is unwrapped.
+     */
+    load?: () => Promise<SearchDoc[] | {
+        default: SearchDoc[];
+    }>;
+    /** At most this many results (default 8). */
+    limit?: number;
+    /** Result kinds in display order; also breaks score ties. */
+    kindOrder?: string[];
+    /** A snippet longer than this is cut around its first match (default 80 characters). */
+    snippetLength?: number;
+}
+/** Where the conversation is kept between visits. `localStorageAdapter()` is the default. */
+export interface PersistAdapter {
+    read(): StoredConversation | null;
+    write(value: StoredConversation | null): void;
+}
+export interface StoredConversation {
+    id: string;
+    messages: ChatMessage[];
+    /** When the visitor last sent a message (ms). */
+    savedAt: number;
+}
+export interface AskConfig {
+    /**
+     * The chat endpoint for the default transport: any endpoint that speaks the AI SDK UI message
+     * stream and takes the whole conversation (`createAskHandler` from `@perxel/spotlight/server`,
+     * or any `useChat`-compatible route).
+     */
+    endpoint?: string;
+    /**
+     * A custom transport instead of `endpoint`: an AI SDK `ChatTransport` (typed loosely here so
+     * the contracts do not import `ai`). For backends that keep their own history or sessions.
+     */
+    transport?: unknown;
+    /** Extra fields sent with every request (locale, page). A function runs per request. */
+    body?: Record<string, unknown> | (() => Record<string, unknown> | Promise<Record<string, unknown>>);
+    /** Extra headers sent with every request. A function runs per request. */
+    headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+    /**
+     * Called when the gate opens (once per opening): warm the endpoint, mount a bot check. Never
+     * called during page load.
+     */
+    prepare?: () => void | Promise<void>;
+    /** Where the conversation is kept: `localStorageAdapter(...)` (default), `false` for nowhere, or your own. */
+    persist?: PersistAdapter | false;
+    /**
+     * A question from the gate continues the kept conversation if its last question is younger
+     * than this many hours; older, it starts a new one (default 24).
+     */
+    continueHours?: number;
+    /** Characters in one question (default 1000). */
+    maxInput?: number;
+}
+/** What an action's view gets. */
+export interface ActionViewProps<I = unknown> {
+    /** What opened it: the typed text mapped by `fromSearch`, or the tool output mapped by `fromTool`. */
+    input: I;
+    /** The conversation so far (empty when opened from the gate with none). */
+    messages: ChatMessage[];
+    /** The conversation id, for a backend that keeps conversations. */
+    conversationId: string | null;
+    /** Back to the conversation, or to the gate when there is none. */
+    back: () => void;
+    /** Close the panel. */
+    close: () => void;
+}
+/**
+ * Something a visitor can do from the gate or from an answer (contact form, newsletter signup).
+ * Registered by the site; the package ships none.
+ */
+export interface Action<I = any> {
+    /** Unique. A search document with id `action:<id>` opens it too (for indexes built ahead). */
+    id: string;
+    /** Makes it a search result (kind `"action"` unless set). */
+    search?: {
+        title: string;
+        subtitle?: string;
+        keywords?: string[];
+        kind?: string;
+    };
+    /** The input when opened from the gate, from the typed text. Default: `undefined`. */
+    fromSearch?: (query: string, doc: SearchDoc) => I;
+    /** The tool whose output in a finished answer opens it (e.g. `"prepare_lead"`). */
+    tool?: string;
+    /** The input when opened from an answer, from the tool's output. Default: the output itself. */
+    fromTool?: (output: unknown, messages: ChatMessage[]) => I;
+    /** What opens, inside the panel (needs `ask`). */
+    view?: ComponentType<ActionViewProps<I>>;
+    /** Or: run something instead of opening a view (navigate, open the site's own dialog). */
+    run?: (input: I) => void;
+    /** The panel title while the view is open, and the label of the row that reopens it under an answer. */
+    title?: string;
+    label?: string;
+    /** Hint by the gate's Enter key while this action is highlighted ("to open the form"). */
+    hint?: string;
+}
+/** Identity helper, for inference: `defineAction({...})`. */
+export declare function defineAction<I>(action: Action<I>): Action<I>;
+/** What the gate hands the panel. `fresh`: the kept conversation is stale, start a new one. */
+export type SpotlightRequest = {
+    kind: "ask";
+    text: string;
+    fresh: boolean;
+} | {
+    kind: "action";
+    id: string;
+    input: unknown;
+} | {
+    kind: "show";
+};
+/** Which halves are on: `search` given, `ask` given, both, or neither. */
+export type SpotlightMode = "both" | "search" | "ask" | "none";
+export interface SpotlightCopy {
+    /** The gate's accessible title. */
+    gateTitle: string;
+    /** The gate's field, by mode. */
+    placeholder: string;
+    placeholderSearch: string;
+    placeholderAsk: string;
+    /** Hint by Enter: ask, open the highlighted page. */
+    hintAsk: string;
+    hintOpen: string;
+    /** Result kind labels (`page`, `post`…); a kind without one shows as is. */
+    kinds: Record<string, string>;
+    /** Live region: the number of results. */
+    results: (count: number) => string;
+    /** The panel. */
+    panelTitle: string;
+    newChat: string;
+    close: string;
+    back: string;
+    send: string;
+    stop: string;
+    thinking: string;
+    sources: string;
+    /** The button back to the newest message. */
+    scrollToEnd: string;
+    /** Error messages by code (the `code` field of a JSON error response, or `generic`). */
+    errors: Record<string, string>;
+}
+export interface NavigateOptions {
+    /** Open in a new tab (modified click). */
+    newTab?: boolean;
+    /** Where it came from: a search result, a link in an answer or a source. */
+    from: "search" | "answer";
+}
+/** Default: `location.assign` (or `window.open` for a new tab). */
+export type Navigate = (url: string, options: NavigateOptions) => void;
+/** What the gate and the panel modules receive from the provider. */
+export interface GateProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+}
+export interface PanelProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+}
+export type Loader<P> = () => Promise<{
+    default: ComponentType<P>;
+}>;
+export interface SpotlightProps {
+    /** Search: documents or a loader. Omit for an ask-only prompt box. */
+    search?: SearchConfig;
+    /** Ask: an endpoint or a transport. Omit for plain search; the chat code is then never loaded. */
+    ask?: AskConfig;
+    actions?: Action[];
+    /** The gate component's module, loaded lazily (a skin passes its own). */
+    gate: Loader<GateProps>;
+    /** The panel component's module, loaded lazily; needed with `ask`. */
+    panel?: Loader<PanelProps>;
+    navigate?: Navigate;
+    /** The keyboard shortcut: `"mod+k"` (default: ⌘K on Apple keyboards, Ctrl K elsewhere), another `mod+<key>`, or `false`. */
+    shortcut?: string | false;
+    /** Off: nothing renders and the shortcut is unbound (e.g. a page without Ask). Default on. */
+    enabled?: boolean;
+    copy?: Partial<SpotlightCopy>;
+    /**
+     * Fetch the gate's code once the page is idle, so the first open is instant. `true` (default):
+     * 1.5 s after load or on the first input; a number: that many ms after load; `false`: only on a
+     * trigger's `prefetch` (pointer enter, focus).
+     */
+    prefetch?: boolean | number;
+    children?: ReactNode;
+}

package/dist/types.js

@@ -0,0 +1,7 @@
+// The contracts every part codes against: the search config, the Ask config, actions, the
+// request the gate hands the panel, the copy dictionary, persistence. No React values here,
+// only types (and `defineAction`, an identity helper), so any entry point may import it.
+/** Identity helper, for inference: `defineAction({...})`. */
+export function defineAction(action) {
+    return action;
+}