@perxel/spotlight 0.0.0-stage → 0.1.1

package/dist/chat/useAskChat.js

@@ -0,0 +1,200 @@
+"use client";
+import { useChat } from "@ai-sdk/react";
+import { DefaultChatTransport } from "ai";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { mergeCopy } from "../core/copy.js";
+import { calledTool, sourcesOf, textOf, toolOutputOf } from "../core/messages.js";
+import { useSpotlight } from "../react/provider.js";
+const resolve = async (v) => (typeof v === "function" ? v() : v);
+/**
+ * The default transport: the AI SDK UI message stream, the whole conversation sent each turn,
+ * `ask.body` and `ask.headers` added per request. A JSON error response's `code` becomes the
+ * error's message (mapped to `copy.errors`).
+ */
+export function defaultTransport(ask) {
+    return new DefaultChatTransport({
+        api: ask.endpoint,
+        prepareSendMessagesRequest: async ({ id, messages, body }) => ({
+            body: { ...body, id, messages, ...(await resolve(ask.body)) },
+            headers: (await resolve(ask.headers)) ?? {},
+        }),
+        fetch: async (input, init) => {
+            const res = await fetch(input, init);
+            if (!res.ok) {
+                const code = await res
+                    .json()
+                    .then((b) => (typeof b.code === "string" ? b.code : "generic"))
+                    .catch(() => "generic");
+                throw new Error(code);
+            }
+            return res;
+        },
+    });
+}
+/**
+ * The panel's state: the AI SDK chat on the configured transport, the conversation kept through
+ * `persist`, the gate's requests (ask, open an action, show), actions opened from answers, and
+ * which view shows (the conversation or an action's view). Must be inside `SpotlightProvider`
+ * with `ask`.
+ */
+export function useAskChat({ uiTools = [] } = {}) {
+    const s = useSpotlight();
+    const ask = s.ask ?? {};
+    const persist = s.persist;
+    const maxInput = ask.maxInput ?? 1000;
+    const initial = useMemo(() => persist.read(), [persist]);
+    const [id, setId] = useState(() => initial?.id ?? crypto.randomUUID());
+    // When the visitor last sent a message: the storage time counts from here, not from each visit.
+    const lastSent = useRef(initial?.savedAt ?? 0);
+    const [input, setInput] = useState("");
+    const [view, setView] = useState({ kind: "chat" });
+    const viewKey = useRef(0);
+    const transport = useMemo(() => ask.transport ?? defaultTransport(ask), 
+    // The config object may be recreated per render; the endpoint and transport are what matter.
+    [ask.transport, ask.endpoint]);
+    const askRef = useRef(ask);
+    askRef.current = ask;
+    const chat = useChat({
+        id,
+        messages: initial?.id === id ? initial.messages : [],
+        transport,
+    });
+    const { messages, sendMessage, status, error, stop, setMessages, clearError } = chat;
+    const list = messages;
+    useEffect(() => {
+        persist.write(list.length ? { id, messages: list, savedAt: lastSent.current } : null);
+    }, [id, messages, status]);
+    const actionTools = useMemo(() => new Map(s.actions.filter((a) => a.tool).map((a) => [a.tool, a])), [s.actions]);
+    const ui = useMemo(() => new Set([...uiTools, ...actionTools.keys()]), [uiTools.join("\u0000"), actionTools]);
+    const busy = status === "submitted" || status === "streaming";
+    const copy = useMemo(() => mergeCopy(s.copy), [s.copy]);
+    const errorCode = error ? (error.message in copy.errors ? error.message : "generic") : null;
+    const lastAssistant = [...list].reverse().find((m) => m.role === "assistant");
+    const text = (m) => textOf(m, ui);
+    // Waiting: sent, and no answer text yet.
+    const waiting = busy && !(lastAssistant && status === "streaming" && text(lastAssistant));
+    /** The action an answer prepared (its tool has returned), with its input. */
+    const actionOf = (m) => {
+        if (m.role !== "assistant" || !actionTools.size)
+            return null;
+        const out = toolOutputOf(m, actionTools.keys());
+        if (!out)
+            return null;
+        const action = actionTools.get(out.tool);
+        return { action, input: action.fromTool ? action.fromTool(out.output, list) : out.output, callId: out.callId };
+    };
+    const openAction = (action, value) => {
+        if (action.view)
+            setView({ kind: "action", action, input: value, key: ++viewKey.current });
+        else
+            action.run?.(value);
+    };
+    // An answer that prepared an action opens it once the answer is done. Ones restored from
+    // storage stay closed.
+    const opened = useRef(new Set((initial?.messages ?? []).flatMap((m) => {
+        const out = toolOutputOf(m, s.actions.flatMap((a) => (a.tool ? [a.tool] : [])));
+        return out ? [out.callId] : [];
+    })));
+    const pending = lastAssistant ? actionOf(lastAssistant) : null;
+    useEffect(() => {
+        if (busy || !pending || opened.current.has(pending.callId))
+            return;
+        opened.current.add(pending.callId);
+        openAction(pending.action, pending.input);
+    }, [busy, pending?.callId]);
+    const send = (value) => {
+        const t = value.trim().slice(0, maxInput);
+        if (!t || busy)
+            return;
+        clearError();
+        setInput("");
+        lastSent.current = Date.now();
+        void sendMessage({ text: t });
+    };
+    const reset = () => {
+        stop();
+        setMessages([]);
+        clearError();
+        setView({ kind: "chat" });
+        setId(crypto.randomUUID());
+        persist.write(null);
+    };
+    // The gate's request. A question waits in `queued` until the chat can take it: after a reset
+    // (a new `id`, so a new chat instance next render) or once a running answer has stopped.
+    const [queued, setQueued] = useState(null);
+    const handled = useRef(0);
+    const request = s.request;
+    useEffect(() => {
+        if (!request || request.n === handled.current)
+            return;
+        handled.current = request.n;
+        const r = request.r;
+        if (r.kind === "ask") {
+            if (r.fresh && list.length)
+                reset();
+            else if (busy)
+                void stop();
+            setView({ kind: "chat" });
+            setQueued(r.text);
+        }
+        else if (r.kind === "action") {
+            const action = s.actions.find((a) => a.id === r.id);
+            if (action)
+                openAction(action, r.input);
+        }
+        else
+            setView({ kind: "chat" });
+        // Once per request; the handlers read the current state.
+    }, [request?.n]);
+    useEffect(() => {
+        if (queued === null || busy)
+            return;
+        setQueued(null);
+        send(queued);
+    }, [queued, busy, id]);
+    /** Start over through the gate: the panel has no empty state of its own. */
+    const newChat = () => {
+        reset();
+        s.setPanelOpen(false);
+        s.openGate();
+    };
+    /** An action view's back: to the conversation, or (opened from the gate with none) back to the gate. */
+    const back = () => {
+        if (list.length)
+            return setView({ kind: "chat" });
+        s.setPanelOpen(false);
+        s.openGate();
+    };
+    return {
+        id,
+        messages: list,
+        status,
+        busy,
+        waiting,
+        error,
+        /** The error's code, a key of `copy.errors` (`generic` for unknown ones); null without an error. */
+        errorCode,
+        input,
+        setInput,
+        send,
+        stop,
+        reset,
+        newChat,
+        back,
+        close: () => s.setPanelOpen(false),
+        view,
+        setView,
+        openAction,
+        actionOf,
+        lastAssistant,
+        /** A message's text (answers: after the last content tool call). */
+        textOf: text,
+        sourcesOf,
+        /** True when the message called `tool` (e.g. a handoff tool that shows contact options). */
+        calledTool,
+        copy,
+        /** Characters in one question (`ask.maxInput`). */
+        maxInput,
+        chat,
+    };
+}

package/dist/core/copy.d.ts

@@ -0,0 +1,4 @@
+import type { SpotlightCopy } from "../types.js";
+/** English defaults. A site passes its own strings (any language) through `copy`. */
+export declare const defaultCopy: SpotlightCopy;
+export declare function mergeCopy(copy?: Partial<SpotlightCopy>): SpotlightCopy;

package/dist/core/copy.js

@@ -0,0 +1,40 @@
+/** English defaults. A site passes its own strings (any language) through `copy`. */
+export const defaultCopy = {
+    gateTitle: "Search",
+    placeholder: "Search or ask…",
+    placeholderSearch: "Search…",
+    placeholderAsk: "Ask a question…",
+    hintAsk: "to ask AI",
+    hintOpen: "to open",
+    kinds: {},
+    results: (n) => (n === 1 ? "1 result" : `${n} results`),
+    panelTitle: "Ask",
+    newChat: "New chat",
+    close: "Close",
+    back: "Back",
+    send: "Send",
+    stop: "Stop",
+    thinking: "Looking it up",
+    sources: "Sources",
+    scrollToEnd: "Scroll to the newest message",
+    errors: {
+        generic: "Something went wrong. Please try again.",
+        rate_limited: "Too many questions at once. Please wait a minute.",
+        verify_failed: "We could not check that you are not a bot. Please reload and try again.",
+        conversation_limit: "This conversation is at its limit. Start a new chat.",
+        budget: "Ask is resting for today. Please try again tomorrow.",
+        config: "Ask is not available right now.",
+        upstream: "The answer could not be written. Please try again.",
+        bad_request: "That message could not be sent.",
+    },
+};
+export function mergeCopy(copy) {
+    if (!copy)
+        return defaultCopy;
+    return {
+        ...defaultCopy,
+        ...copy,
+        kinds: { ...defaultCopy.kinds, ...copy.kinds },
+        errors: { ...defaultCopy.errors, ...copy.errors },
+    };
+}

package/dist/core/fold.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Lowercase, accents and other combining marks removed, `đ` folded to `d`, a dot or apostrophe
+ * inside a word dropped ("Next.js" → "nextjs"), anything else that is not a letter or digit
+ * turned into a space. "Dịch vụ & SEO" → "dich vu seo".
+ */
+export declare function fold(text: string): string;
+/** Email addresses in a text (global). */
+export declare const EMAIL_IN_TEXT: RegExp;
+/** The first email address in a text. */
+export declare function emailIn(text: string): string | undefined;

package/dist/core/fold.js

@@ -0,0 +1,23 @@
+// Small text helpers on their own (folding for matching, finding an email), so light modules (an
+// action's `fromSearch`) can use them without the search engine or the message helpers.
+/**
+ * Lowercase, accents and other combining marks removed, `đ` folded to `d`, a dot or apostrophe
+ * inside a word dropped ("Next.js" → "nextjs"), anything else that is not a letter or digit
+ * turned into a space. "Dịch vụ & SEO" → "dich vu seo".
+ */
+export function fold(text) {
+    return text
+        .normalize("NFD")
+        .replace(/\p{M}+/gu, "")
+        .toLowerCase()
+        .replace(/đ/g, "d")
+        .replace(/(?<=[\p{L}\p{N}])[.'’](?=[\p{L}\p{N}])/gu, "")
+        .replace(/[^\p{L}\p{N}]+/gu, " ")
+        .trim();
+}
+/** Email addresses in a text (global). */
+export const EMAIL_IN_TEXT = /[^\s@<>()"',;:]+@[^\s@<>()"',;:]+\.[a-z]{2,}/gi;
+/** The first email address in a text. */
+export function emailIn(text) {
+    return text.match(new RegExp(EMAIL_IN_TEXT.source, "i"))?.[0];
+}

package/dist/core/messages.d.ts

@@ -0,0 +1,24 @@
+import type { ChatMessage, ChatPart } from "../types.js";
+/** A tool part (`tool-<name>`, or `dynamic-tool` with `toolName`). */
+export declare function toolName(part: ChatPart): string | null;
+/**
+ * A message's text. For an answer, only what follows its last content tool call: what a model
+ * writes between tool steps ("let me check…") is not the answer. Tools named in `uiTools` (ones
+ * that only drive the interface, like an action) do not cut the text.
+ */
+export declare function textOf(m: ChatMessage, uiTools?: ReadonlySet<string>): string;
+/** The sources an answer cited (`source-url` parts), deduplicated. */
+export declare function sourcesOf(m: ChatMessage): {
+    url: string;
+    title: string;
+}[];
+/** The first finished call of one of `tools` in a message: its call id, tool name and output. */
+export declare function toolOutputOf(m: ChatMessage, tools: Iterable<string>): {
+    callId: string;
+    tool: string;
+    output: unknown;
+} | null;
+/** True when the message called `tool` (any state). */
+export declare function calledTool(m: ChatMessage, tool: string): boolean;
+/** The latest email (or, for `contact`, email or phone number) in the visitor's own messages. */
+export declare function latestFromVisitor(messages: ChatMessage[], kind: "email" | "contact"): string | undefined;

package/dist/core/messages.js

@@ -0,0 +1,72 @@
+// Helpers that read chat messages (AI SDK `UIMessage`s, structurally). No React, no AI SDK.
+import { EMAIL_IN_TEXT } from "./fold.js";
+/** A tool part (`tool-<name>`, or `dynamic-tool` with `toolName`). */
+export function toolName(part) {
+    if (part.type === "dynamic-tool")
+        return typeof part.toolName === "string" ? part.toolName : null;
+    return part.type.startsWith("tool-") ? part.type.slice(5) : null;
+}
+/**
+ * A message's text. For an answer, only what follows its last content tool call: what a model
+ * writes between tool steps ("let me check…") is not the answer. Tools named in `uiTools` (ones
+ * that only drive the interface, like an action) do not cut the text.
+ */
+export function textOf(m, uiTools = new Set()) {
+    let parts = m.parts;
+    if (m.role === "assistant") {
+        const lastTool = parts.findLastIndex((p) => {
+            const name = toolName(p);
+            return name !== null && !uiTools.has(name);
+        });
+        const after = parts.slice(lastTool + 1);
+        if (lastTool >= 0 && after.some((p) => p.type === "text" && String(p.text ?? "").trim()))
+            parts = after;
+    }
+    return parts.map((p) => (p.type === "text" ? String(p.text ?? "") : "")).join("").trim();
+}
+/** The sources an answer cited (`source-url` parts), deduplicated. */
+export function sourcesOf(m) {
+    const out = [];
+    for (const p of m.parts) {
+        if (p.type !== "source-url" || typeof p.url !== "string")
+            continue;
+        if (out.some((s) => s.url === p.url))
+            continue;
+        out.push({ url: p.url, title: typeof p.title === "string" && p.title ? p.title : p.url });
+    }
+    return out;
+}
+/** The first finished call of one of `tools` in a message: its call id, tool name and output. */
+export function toolOutputOf(m, tools) {
+    const names = new Set(tools);
+    for (const p of m.parts) {
+        const name = toolName(p);
+        if (!name || !names.has(name))
+            continue;
+        if (p.state === "output-available" && p.output !== undefined)
+            return { callId: String(p.toolCallId), tool: name, output: p.output };
+    }
+    return null;
+}
+/** True when the message called `tool` (any state). */
+export function calledTool(m, tool) {
+    return m.parts.some((p) => toolName(p) === tool);
+}
+const PHONE_IN_TEXT = /\+?\d[\d\s.-]{6,}\d/g;
+/** The latest email (or, for `contact`, email or phone number) in the visitor's own messages. */
+export function latestFromVisitor(messages, kind) {
+    for (const m of [...messages].reverse()) {
+        if (m.role !== "user")
+            continue;
+        const text = textOf(m);
+        const email = text.match(EMAIL_IN_TEXT)?.at(-1);
+        if (email)
+            return email;
+        if (kind === "contact") {
+            const phone = text.match(PHONE_IN_TEXT)?.findLast((n) => n.replace(/\D/g, "").length >= 8);
+            if (phone)
+                return phone.trim();
+        }
+    }
+    return undefined;
+}

package/dist/core/search.d.ts

@@ -0,0 +1,73 @@
+import { fold } from "./fold.js";
+export { fold };
+/** One searchable thing. The host builds these (usually at build time) from its own content. */
+export interface SearchDoc {
+    /** Unique across the set. */
+    id: string;
+    /** What it is ("page", "insight", "action"…). Results are grouped and tie-broken by it. */
+    kind: string;
+    /** Shown and ranked first. */
+    title: string;
+    /** Shown under or beside the title (a category, a short label). Matched, weakly. */
+    subtitle?: string;
+    /** Where opening it goes. Omit for things that are not links (actions): the host handles them in `onOpen`. */
+    url?: string;
+    /** Extra text to match but not show (short titles, tags, synonyms). */
+    keywords?: string[];
+    /**
+     * Readable text, matched like `keywords` and shown as the result's `snippet` when the title
+     * does not explain the match (section headings, an excerpt). Ordered by preference: the first
+     * one holding the most of the words missing from the title is shown.
+     */
+    snippets?: string[];
+}
+/** A built index: the docs plus their folded text. Plain data, so it can be serialized. */
+export interface SearchIndex {
+    docs: SearchDoc[];
+    /** Per doc: folded title, folded subtitle, folded keywords and snippets (joined). */
+    text: [title: string, subtitle: string, keywords: string][];
+}
+export interface SearchOptions {
+    /** At most this many results (default 8). */
+    limit?: number;
+    /** Kinds in display order; also breaks score ties. Kinds not listed come after, in first-seen order. */
+    kindOrder?: string[];
+    /** A snippet longer than this many characters is cut to a window around its first match (default 80). */
+    snippetLength?: number;
+}
+/** A doc's snippet with the typed words marked: `[start, end)` ranges into `text`, in order. */
+export interface Snippet {
+    text: string;
+    marks: [start: number, end: number][];
+}
+export interface SearchResult {
+    doc: SearchDoc;
+    score: number;
+    /** Where the typed words are in `doc.title`, as `[start, end)` ranges (see `markTerms`). Empty when only other fields matched. */
+    titleMarks: [start: number, end: number][];
+    /** Set when some typed word is not in the title but is in one of the doc's `snippets`. */
+    snippet?: Snippet;
+}
+export declare function buildIndex(docs: SearchDoc[]): SearchIndex;
+/**
+ * Every query term must match somewhere (title, subtitle, keywords or snippets). Ranking: the whole
+ * query starting the title, then per term: word prefix in the title, substring in the title,
+ * word prefix in keywords, then subtitle, then substring there. Ties go by `kindOrder`, then
+ * the docs' own order. An empty query returns nothing.
+ *
+ * When no doc matches every term ("quote landing page": the action matches "quote", a post
+ * "landing page"), the docs matching the most terms are returned instead, so a query that
+ * mixes an intent and a topic still finds both.
+ */
+export declare function search(index: SearchIndex, query: string, { limit, kindOrder, snippetLength }?: SearchOptions): SearchResult[];
+/**
+ * Where `terms` (folded) match in `text` (not folded), as ranges into `text`: word starts, and
+ * anywhere for terms of 3+ characters, like the search. Folds one character at a time, so each
+ * folded character knows the original it came from ("trình" marks all of "trình" for "trinh").
+ */
+export declare function markTerms(text: string, terms: string[]): [number, number][];
+/** Results in display order: grouped by kind, groups in `kindOrder`, best first inside a group. */
+export declare function groupByKind(results: SearchResult[], kindOrder?: string[]): {
+    kind: string;
+    results: SearchResult[];
+}[];

package/dist/core/search.js

@@ -0,0 +1,210 @@
+// The search engine: instant, client-side search over a small set of documents (a site's pages,
+// posts, actions). No React, no Next, no dependencies: pure functions, safe anywhere.
+// Imports only `fold`.
+import { fold } from "./fold.js";
+export { fold };
+/** The title with in-word dots split ("Next.js" → "next js"), so "next js" finds it too. */
+function splitDots(text) {
+    return fold(text.replace(/[.]/g, " "));
+}
+export function buildIndex(docs) {
+    return {
+        docs,
+        text: docs.map((d) => {
+            const title = fold(d.title);
+            const split = splitDots(d.title);
+            const extra = [...(d.keywords ?? []), ...(d.snippets ?? [])];
+            return [title, fold(d.subtitle ?? ""), [fold(extra.join(" ")), split === title ? "" : split].join(" ").trim()];
+        }),
+    };
+}
+/** True when `term` starts a word in `text` (both folded). */
+function wordPrefix(text, term) {
+    return text.startsWith(term) || text.includes(" " + term);
+}
+/** True when `term` matches `text` (both folded): a word start, or anywhere for terms of 3+ characters. */
+function hits(text, term) {
+    return wordPrefix(text, term) || (term.length >= 3 && text.includes(term));
+}
+/**
+ * How well one query term matches a doc's folded text, 0 for not at all. Terms of one or two
+ * characters only match the start of a word, so "a" does not match every doc.
+ */
+function termScore([title, subtitle, keywords], term) {
+    if (wordPrefix(title, term))
+        return 10;
+    const short = term.length < 3;
+    if (!short && title.includes(term))
+        return 6;
+    if (wordPrefix(keywords, term))
+        return 4;
+    if (wordPrefix(subtitle, term))
+        return 3;
+    if (!short && (keywords.includes(term) || subtitle.includes(term)))
+        return 1;
+    return 0;
+}
+/**
+ * Every query term must match somewhere (title, subtitle, keywords or snippets). Ranking: the whole
+ * query starting the title, then per term: word prefix in the title, substring in the title,
+ * word prefix in keywords, then subtitle, then substring there. Ties go by `kindOrder`, then
+ * the docs' own order. An empty query returns nothing.
+ *
+ * When no doc matches every term ("quote landing page": the action matches "quote", a post
+ * "landing page"), the docs matching the most terms are returned instead, so a query that
+ * mixes an intent and a topic still finds both.
+ */
+export function search(index, query, { limit = 8, kindOrder = [], snippetLength = 80 } = {}) {
+    const q = fold(query);
+    if (!q)
+        return [];
+    const terms = [...new Set(q.split(" "))];
+    const rank = kindRank(index.docs, kindOrder);
+    const all = [];
+    index.text.forEach((text, i) => {
+        let score = 0;
+        let matched = 0;
+        for (const term of terms) {
+            const s = termScore(text, term);
+            if (s)
+                matched++;
+            score += s;
+        }
+        if (!matched)
+            return;
+        if (text[0].startsWith(q))
+            score += 20;
+        else if (text[0].includes(q) && terms.length > 1)
+            score += 8;
+        all.push({ doc: index.docs[i], score, i, matched });
+    });
+    const most = Math.max(0, ...all.map((h) => h.matched));
+    const found = all.filter((h) => h.matched === most);
+    found.sort((a, b) => b.score - a.score || rank(a.doc.kind) - rank(b.doc.kind) || a.i - b.i);
+    return found.slice(0, limit).map(({ doc, score, i }) => {
+        const snippet = snippetFor(doc, index.text[i][0], terms, snippetLength);
+        const titleMarks = markTerms(doc.title, terms);
+        return snippet ? { doc, score, titleMarks, snippet } : { doc, score, titleMarks };
+    });
+}
+/**
+ * The snippet to show under a result: none while every term is in the title (the title explains
+ * the match); else the first of `doc.snippets` holding the most of the missing terms, every
+ * term marked, cut to `max` characters around its first mark.
+ */
+function snippetFor(doc, title, terms, max) {
+    const titleText = title + " " + splitDots(doc.title);
+    const missing = terms.filter((t) => !hits(titleText, t));
+    if (!missing.length || !doc.snippets?.length)
+        return;
+    let best;
+    let bestCount = 0;
+    for (const text of doc.snippets) {
+        const folded = fold(text);
+        const count = missing.filter((t) => hits(folded, t)).length;
+        if (count > bestCount)
+            [best, bestCount] = [text, count];
+    }
+    if (!best)
+        return;
+    return cutAround({ text: best, marks: markTerms(best, terms) }, max);
+}
+/**
+ * Where `terms` (folded) match in `text` (not folded), as ranges into `text`: word starts, and
+ * anywhere for terms of 3+ characters, like the search. Folds one character at a time, so each
+ * folded character knows the original it came from ("trình" marks all of "trình" for "trinh").
+ */
+export function markTerms(text, terms) {
+    let folded = "";
+    const from = [];
+    const to = [];
+    const chars = Array.from(text);
+    let at = 0;
+    chars.forEach((c, k) => {
+        const end = at + c.length;
+        const f = c.normalize("NFD").replace(/\p{M}+/gu, "").toLowerCase().replace(/đ/g, "d");
+        const word = (x) => !!x && /[\p{L}\p{N}]/u.test(x);
+        if (f && /^[\p{L}\p{N}]+$/u.test(f)) {
+            for (const ch of f) {
+                folded += ch;
+                from.push(at);
+                to.push(end);
+            }
+        }
+        else if (!f) {
+            // A combining mark of decomposed text: part of the previous character.
+            if (to.length)
+                to[to.length - 1] = end;
+        }
+        else if (/[.'’]/.test(c) && word(folded.at(-1)) && word(chars[k + 1])) {
+            // A dot or apostrophe inside a word is dropped, as in `fold`.
+        }
+        else if (folded && !folded.endsWith(" ")) {
+            folded += " ";
+            from.push(at);
+            to.push(end);
+        }
+        at = end;
+    });
+    const ranges = [];
+    for (const term of terms) {
+        if (!term)
+            continue;
+        for (let p = folded.indexOf(term); p !== -1; p = folded.indexOf(term, p + 1)) {
+            if (term.length < 3 && p > 0 && folded[p - 1] !== " ")
+                continue;
+            ranges.push([from[p], to[p + term.length - 1]]);
+        }
+    }
+    ranges.sort((a, b) => a[0] - b[0]);
+    const merged = [];
+    for (const r of ranges) {
+        const last = merged.at(-1);
+        // Overlapping, or only a space apart: one mark ("trình duyệt", not two).
+        if (last && (r[0] <= last[1] || !text.slice(last[1], r[0]).trim()))
+            last[1] = Math.max(last[1], r[1]);
+        else
+            merged.push([...r]);
+    }
+    return merged;
+}
+/** Cuts a long snippet to about `max` characters on word boundaries, starting a little before its first mark, with "…" where cut. */
+function cutAround({ text, marks }, max) {
+    if (text.length <= max || !marks.length)
+        return { text, marks };
+    const first = marks[0][0];
+    let start = Math.max(0, Math.min(first - Math.floor(max * 0.3), text.length - max));
+    if (start > 0) {
+        const space = text.indexOf(" ", start);
+        start = space !== -1 && space < first ? space + 1 : start;
+    }
+    let end = Math.min(text.length, start + max);
+    if (end < text.length) {
+        const space = text.lastIndexOf(" ", end);
+        if (space > Math.max(start, marks[0][1]))
+            end = space;
+    }
+    const lead = start > 0 ? "…" : "";
+    const shift = lead.length - start;
+    return {
+        text: lead + text.slice(start, end).trimEnd() + (end < text.length ? "…" : ""),
+        marks: marks
+            .filter(([a, b]) => a >= start && b <= end)
+            .map(([a, b]) => [a + shift, b + shift]),
+    };
+}
+/** Results in display order: grouped by kind, groups in `kindOrder`, best first inside a group. */
+export function groupByKind(results, kindOrder = []) {
+    const groups = new Map();
+    for (const r of results)
+        groups.set(r.doc.kind, [...(groups.get(r.doc.kind) ?? []), r]);
+    const rank = kindRank(results.map((r) => r.doc), kindOrder);
+    return [...groups].sort(([a], [b]) => rank(a) - rank(b)).map(([kind, results]) => ({ kind, results }));
+}
+function kindRank(docs, kindOrder) {
+    const order = [...kindOrder];
+    for (const d of docs)
+        if (!order.includes(d.kind))
+            order.push(d.kind);
+    return (kind) => order.indexOf(kind);
+}