@perxel/spotlight 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Perxel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,175 @@
-# Temporary Holding Version
+# @perxel/spotlight
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Search or ask, like Spotlight. Press ⌘K: the box searches your site as you type, in the browser, with no request and no model call. Press Enter with nothing highlighted and the question goes to an AI chat that answers from your site.
+
+![The liquid skin on perxel.com: results as you type "next", the typed word marked in each row](https://raw.githubusercontent.com/perxel/perxel-spotlight/main/docs/perxel-gate.webp)
+
+- **Search and Ask are independent.** Give it documents, an endpoint, or both. Whatever you leave out is never loaded.
+- **Headless first.** Behaviour, keys, focus, ARIA and state (`data-*`) in React parts you style yourself. A **liquid glass skin** ships as the default, themed with CSS variables.
+- **No platform assumptions.** No Next.js import in the client (navigation is a prop), a Web-standard server helper (`Request` → `Response`: Next route handlers, Workers, Hono, Node), any [AI SDK](https://ai-sdk.dev) model, MCP optional.
+- **Nothing in first load** but the provider and your trigger: the box, the chat, the index and the AI SDK are lazy chunks.
+
+Built for [perxel.com](https://perxel.com) (liquid skin, answers through an MCP server) and [phucbm.com](https://phucbm.com) (its own "research paper" styling on the headless parts, answers from its pages and live data, no MCP).
+
+| perxel.com: the liquid skin's chat panel | phucbm.com: the headless parts, its own styling |
+|---|---|
+| ![The chat panel answering a question, with the pages it used folded under the answer](https://raw.githubusercontent.com/perxel/perxel-spotlight/main/docs/perxel-panel.webp) | ![A plain, paper-like search box on phucbm.com](https://raw.githubusercontent.com/perxel/perxel-spotlight/main/docs/phucbm-gate.webp) |
+
+| Search only | Ask only | Both |
+|---|---|---|
+| Plain site search; Enter opens the first result; the chat code never loads | A prompt box; the search code and index never load | Results as you type; Enter with nothing highlighted asks |
+
+## Install
+
+```sh
+pnpm add @perxel/spotlight
+# for Ask:
+pnpm add ai @ai-sdk/react
+```
+
+React 19. `ai` and `@ai-sdk/react` are optional peers, needed only for Ask.
+
+## Quick start (liquid skin)
+
+```tsx
+"use client"
+import {SpotlightLiquid, Trigger} from "@perxel/spotlight/liquid"
+
+export function Providers({children}: {children: React.ReactNode}) {
+  return (
+    <SpotlightLiquid
+      search={{load: () => fetch("/search.json").then((r) => r.json())}}
+      ask={{endpoint: "/api/ask"}}
+    >
+      {children}
+      <Trigger>Search ⌘K</Trigger>
+    </SpotlightLiquid>
+  )
+}
+```
+
+The skin imports its own CSS from its lazy chunks (`@perxel/spotlight/liquid.css` is exported too, for bundlers that skip CSS imported from packages).
+
+## Search
+
+A document is a `SearchDoc`:
+
+```ts
+{id: "note:og-images", kind: "note", title: "Dynamic OG images", subtitle: "Note", url: "/notes/og-images",
+ keywords: ["satori", "next/og"],          // matched, never shown
+ snippets: ["Fonts", "What broke", "…"]}   // matched, and shown under a result whose title lacks a typed word
+```
+
+Matching: every typed word must match; accents and case are folded (`đ` → `d`, so Vietnamese works typed without accents); one- and two-letter words only match word starts. When nothing matches every word, the documents matching the most words show. Options: `limit` (8), `kindOrder`, `snippetLength` (80).
+
+Give it `search={{docs}}` for a few documents, or `search={{load}}` (recommended) for a lazy file: a dynamic `import()` of a generated JSON, or a `fetch` of a static route. Build helpers for Node: `@perxel/spotlight/build` (`markdownHeadings`, `dropCommonHeadings` for template headings found in many posts, `buildSearchDocs`, `writeSearchIndex`). The package reads no CMS: you map your content.
+
+## Ask
+
+The default transport is the AI SDK UI message stream with the whole conversation in each request, so any `useChat`-compatible endpoint works.
+
+```ts
+ask={{
+  endpoint: "/api/ask",
+  body: async () => ({locale, turnstileToken: await bot.token()}),   // per request
+  prepare: () => bot.prepare(),                                       // when the box opens
+  persist: localStorageAdapter({key: "my-chat", days: 7}),            // default; `false` for none
+  continueHours: 24,      // a question from the box continues a conversation younger than this
+  maxInput: 1000,
+}}
+```
+
+`transport` takes any AI SDK `ChatTransport` instead of `endpoint`, for a backend that keeps its own history or sessions.
+
+### The server helper
+
+```ts
+// app/api/ask/route.ts
+import {createOpenRouter} from "@openrouter/ai-sdk-provider"
+import {contentSource, createAskHandler, mcpSource, toolSource, turnstile} from "@perxel/spotlight/server"
+
+export const POST = createAskHandler({
+  model: createOpenRouter({apiKey: process.env.OPENROUTER_API_KEY})("anthropic/claude-haiku-5.5"),
+  system: "You answer questions about this site, only from tool results…",
+  sources: [
+    contentSource({docs, baseUrl: "https://example.com"}),       // the site's pages: search_site, get_page
+    toolSource({get_stats: tool({...})}),                         // the site's own functions
+    mcpSource({url: "https://mcp.example.com/mcp", tools: ["search_content", "get_item"]}),
+  ],
+  verify: turnstile({secret: process.env.TURNSTILE_SECRET}),
+  rateLimit: async (ctx) => true,          // or false / an error code
+  onFinish: (turn) => log(turn),           // question, answer, tools, sources, tokens, timing
+})
+```
+
+- **Stateless**: the client sends the history; only its text reaches the model (tool results and sources from the client are dropped).
+- **Three kinds of source**, mixed freely. `contentSource` searches and reads your pages with short passages per hit and capped pages (no MCP needed). `toolSource` runs your own AI SDK tools in the route (live numbers, structured data). `mcpSource` calls a remote MCP server over streamable HTTP with no SDK, any runtime with `fetch`; `fixed` sets arguments the model never sees (a locale), `tools` allowlists: an anonymous chat must never reach a private tool.
+- **Sources cited**: `{url, title}` pairs in tool results become `source-url` parts (4 at most, 2 per result; `cite: false` turns it off).
+- **Refusals** are `{code}` JSON (`verify_failed`, `rate_limited`, `conversation_limit`, `budget`, `bad_request`, `origin`); an answer that fails while streaming ends with `config` (no API key, or the provider refused it: fix the route, not a retry) or `upstream` (the provider failed). The panel shows `copy.errors[code]`; the server logs the cause through `onError`.
+- **API keys**: the model is created with the key from wherever the platform keeps secrets (`process.env` on Node and Next, the Worker's env on Cloudflare: with OpenNext, `getCloudflareContext().env`, and `initOpenNextCloudflareForDev()` in `next.config` so `next dev` reads `.dev.vars`). An empty key only fails when a question is asked, so check it in a `model` function (`throw` when it is missing: the handler refuses with `config` before any call).
+- **Limits**: `maxInputChars` (1000), `maxQuestions` (20), `maxHistory` (20), `maxSteps` (4), `maxOutputTokens` (700). CORS only when `origins` is set.
+- On Workers, pass `waitUntil` so `onFinish` outlives the response.
+
+Bot check on the client: `turnstileWidget({siteKey})` from `@perxel/spotlight/react` (script injected on `prepare()`, invisible unless Cloudflare is unsure, a fresh token per question).
+
+## Actions
+
+Things a visitor can do from the box or from an answer (a contact form, a newsletter signup). The package ships none.
+
+```tsx
+const contact = defineAction({
+  id: "contact",
+  search: {title: "Send us a message", keywords: ["contact", "hire"]},  // a search result (or a doc with id "action:contact" in your index)
+  fromSearch: (typed) => ({message: typed}),
+  tool: "prepare_contact",           // a finished answer with this tool's output opens it
+  fromTool: (output) => output,
+  view: ContactForm,                 // shown in the panel: ({input, messages, conversationId, back, close})
+  title: "Contact", label: "Open the contact form", hint: "to open the form",
+})
+```
+
+An action can `run(input)` instead of showing a view (navigate, open your own dialog). Keep views lazy (`React.lazy`) so forms stay out of first load.
+
+## Headless
+
+```tsx
+import {SpotlightProvider, Trigger, useSpotlight} from "@perxel/spotlight/react"
+<SpotlightProvider search={…} ask={…} gate={() => import("./MyGate")} panel={() => import("./MyPanel")}>
+```
+
+The gate module (`@perxel/spotlight/gate`): `Gate.Root` (Radix dialog, focus in and back, Escape clears a highlight first), `Gate.Input`, `Gate.Results` (render function per result), `Gate.Item` (link or button, `data-highlighted`, `data-kind`), `Gate.Marked`, `Gate.Hint` (`data-on` while Enter does something), `Gate.Send`, `Gate.Close`; `useGateContext()` for everything else. The panel module (`@perxel/spotlight/chat`): `useAskChat()` (messages, send, stop, status, `errorCode`, the current view, actions from answers, `textOf`, `sourcesOf`), `Chat.Panel`, `Chat.Title`, `Chat.Close`, `Chat.Messages` + `Chat.Content` (stick to bottom), `Chat.ScrollButton`, `Chat.Composer`, `Chat.Submit`, `Chat.Markdown`. Import these two entries only from your lazy gate and panel modules.
+
+Other props: `navigate(url, {newTab, from})` (default: `location`, other sites in a new tab), `shortcut` (`"mod+k"`, another key, or `false`), `enabled`, `copy` (English defaults; pass your language), `prefetch` (the box's code once the page is idle).
+
+## Theming the liquid skin
+
+Set the variables on `:root` or on the skin's `className`:
+
+| Variable | What |
+|---|---|
+| `--sp-accent` | Marks, the highlight's tint, the tide, the send button's hover |
+| `--sp-ink` | Text on the accent glass |
+| `--sp-text`, `--sp-muted`, `--sp-subtle` | Text tones |
+| `--sp-surface`, `--sp-bubble`, `--sp-quiet` | Panel, the visitor's bubble, quiet fills |
+| `--sp-button`, `--sp-button-text`, `--sp-button-hover` | The round send/stop button |
+| `--sp-glass-fill`, `--sp-glass-edge`, `--sp-glow`, `--sp-lift` | The glass |
+| `--sp-gate-fill`, `--sp-pill-fill` | The box over the page; the panel's header pill |
+| `--sp-font`, `--sp-font-display`, `--sp-display-weight` | Type |
+| `--sp-dim`, `--sp-dim-blur`, `--sp-z` | The page behind the box; stacking |
+
+Skin options: `logo`, `privacyNote`, `handoff(chat)`, `composerExtra(chat)`, `uiTools`, `localHosts`, `tide`, `gateProps` / `panelProps` (attributes on the roots), `className`. Reduced motion and reduced transparency are respected.
+
+## Local development against a site
+
+Link it as a pnpm injected dependency, so the package resolves the site's own React and AI SDK (a plain `link:` brings its dev copies along):
+
+```json
+"dependencies": {"@perxel/spotlight": "file:../perxel-spotlight"},
+"dependenciesMeta": {"@perxel/spotlight": {"injected": true}}
+```
+
+After a change, `scripts/sync.sh ../my-site` rebuilds and copies `dist/` in.
+
+## License
+
+MIT © Perxel

package/dist/build/index.d.ts

@@ -0,0 +1,32 @@
+import type { SearchDoc } from "../core/search.js";
+/**
+ * The plain text of every heading of `levels` (default `##` and `###`) outside code fences: links
+ * keep their text, inline code and emphasis lose their marks.
+ */
+export declare function markdownHeadings(markdown: string, { levels }?: {
+    levels?: number[];
+}): string[];
+/**
+ * Drops headings found in `threshold` (default 3) or more documents of one group: template
+ * sections ("FAQ", "Conclusion") name no topic and would bring up every post that has them.
+ * `group` puts keys in groups (a locale); one group by default.
+ */
+export declare function dropCommonHeadings(headings: Record<string, string[]>, { threshold, group }?: {
+    threshold?: number;
+    group?: (key: string) => string;
+}): Record<string, string[]>;
+/** A content item for `buildSearchDocs`: a document plus the key of its headings. */
+export type SearchItem = SearchDoc & {
+    headingsKey?: string;
+};
+/**
+ * Documents from content items and static pages: each item's headings (by `headingsKey`) go first
+ * in its `snippets` (short, and they name a section), empty fields dropped.
+ */
+export declare function buildSearchDocs({ items, pages, headings }: {
+    items?: SearchItem[];
+    pages?: SearchDoc[];
+    headings?: Record<string, string[]>;
+}): SearchDoc[];
+/** Writes the documents as JSON (one line), only when the content changed. Returns true when it wrote. */
+export declare function writeSearchIndex(docs: SearchDoc[], file: string): boolean;

package/dist/build/index.js

@@ -0,0 +1,68 @@
+// `@perxel/spotlight/build`: build-time helpers for the search index (Node). A site maps its own
+// content to `SearchDoc`s; these read headings out of markdown, drop template headings and write
+// the index file. The package reads no CMS.
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * The plain text of every heading of `levels` (default `##` and `###`) outside code fences: links
+ * keep their text, inline code and emphasis lose their marks.
+ */
+export function markdownHeadings(markdown, { levels = [2, 3] } = {}) {
+    let fence = false;
+    const out = [];
+    for (const line of markdown.split("\n")) {
+        if (/^\s*(```|~~~)/.test(line))
+            fence = !fence;
+        const m = !fence && line.match(/^(#{1,6})\s+(.+?)\s*#*\s*$/);
+        if (!m || !levels.includes(m[1].length))
+            continue;
+        out.push(m[2].replace(/\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/[`*_]/g, "").trim());
+    }
+    return out;
+}
+/**
+ * Drops headings found in `threshold` (default 3) or more documents of one group: template
+ * sections ("FAQ", "Conclusion") name no topic and would bring up every post that has them.
+ * `group` puts keys in groups (a locale); one group by default.
+ */
+export function dropCommonHeadings(headings, { threshold = 3, group = () => "" } = {}) {
+    const seen = new Map();
+    for (const [key, list] of Object.entries(headings)) {
+        for (const h of new Set(list))
+            seen.set(`${group(key)}|${h}`, (seen.get(`${group(key)}|${h}`) ?? 0) + 1);
+    }
+    return Object.fromEntries(Object.entries(headings).map(([key, list]) => [key, list.filter((h) => (seen.get(`${group(key)}|${h}`) ?? 0) < threshold)]));
+}
+/**
+ * Documents from content items and static pages: each item's headings (by `headingsKey`) go first
+ * in its `snippets` (short, and they name a section), empty fields dropped.
+ */
+export function buildSearchDocs({ items = [], pages = [], headings = {} }) {
+    const clean = (d) => {
+        const out = { id: d.id, kind: d.kind, title: d.title };
+        if (d.subtitle)
+            out.subtitle = d.subtitle;
+        if (d.url)
+            out.url = d.url;
+        const keywords = (d.keywords ?? []).filter(Boolean);
+        if (keywords.length)
+            out.keywords = keywords;
+        const snippets = (d.snippets ?? []).filter(Boolean);
+        if (snippets.length)
+            out.snippets = snippets;
+        return out;
+    };
+    return [
+        ...pages.map(clean),
+        ...items.map(({ headingsKey, ...d }) => clean({ ...d, snippets: [...(headingsKey ? headings[headingsKey] ?? [] : []), ...(d.snippets ?? [])] })),
+    ];
+}
+/** Writes the documents as JSON (one line), only when the content changed. Returns true when it wrote. */
+export function writeSearchIndex(docs, file) {
+    const json = JSON.stringify(docs) + "\n";
+    if (fs.existsSync(file) && fs.readFileSync(file, "utf8") === json)
+        return false;
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, json);
+    return true;
+}

package/dist/chat/index.d.ts

@@ -0,0 +1,3 @@
+export { useAskChat, defaultTransport, type AskChat, type ChatView, type UseAskChatOptions } from "./useAskChat.js";
+export { Chat } from "./parts.js";
+export { calledTool, sourcesOf, textOf, toolOutputOf, latestFromVisitor } from "../core/messages.js";

package/dist/chat/index.js

@@ -0,0 +1,5 @@
+// `@perxel/spotlight/chat`: the chat half (imports the AI SDK). Import it only from the panel
+// module the provider loads lazily, so pages never load it until the gate hands over a question.
+export { useAskChat, defaultTransport } from "./useAskChat.js";
+export { Chat } from "./parts.js";
+export { calledTool, sourcesOf, textOf, toolOutputOf, latestFromVisitor } from "../core/messages.js";

package/dist/chat/parts.d.ts

@@ -0,0 +1,57 @@
+import type { ComponentProps, ComponentPropsWithoutRef, ReactNode, Ref } from "react";
+import * as Dialog from "@radix-ui/react-dialog";
+import type { AskChat } from "./useAskChat.js";
+/**
+ * The conversation's scroll box: stays scrolled to the bottom while an answer streams, unless the
+ * visitor scrolled up. `Chat.Content` holds the messages; `Chat.ScrollButton` shows while not at
+ * the bottom.
+ */
+declare function Messages({ children, ...props }: ComponentPropsWithoutRef<"div">): import("react").JSX.Element;
+/** The scrolling element and the content inside it (`viewportProps` go on the scrolling one). */
+declare function Content({ children, viewportProps, ...props }: ComponentPropsWithoutRef<"div"> & {
+    viewportProps?: ComponentPropsWithoutRef<"div">;
+}): import("react").JSX.Element;
+/** Back to the newest message; renders only while scrolled up. */
+declare function ScrollButton({ onClick, ...props }: ComponentPropsWithoutRef<"button">): import("react").JSX.Element | null;
+/**
+ * The composer: a form with a growing textarea; Enter sends, Shift+Enter breaks the line.
+ * `children` render after the textarea (the send or stop button: `Chat.Submit`).
+ */
+declare function Composer({ chat, children, textareaProps, ...props }: {
+    chat: AskChat;
+    children?: ReactNode;
+    textareaProps?: ComponentPropsWithoutRef<"textarea"> & {
+        ref?: Ref<HTMLTextAreaElement>;
+    };
+} & Omit<ComponentProps<"form">, "children">): import("react").JSX.Element;
+/** Send while idle (disabled with nothing typed), stop while an answer runs. `data-action` says which. */
+declare function Submit({ chat, send, stop, ...props }: {
+    chat: AskChat;
+    send?: ReactNode;
+    stop?: ReactNode;
+} & ComponentPropsWithoutRef<"button">): import("react").JSX.Element;
+/**
+ * The panel's dialog (Radix): non-modal by default, so the page stays usable behind it; a press
+ * outside does not close it (only `Chat.Close` or Escape). `modal` for a sheet over the page.
+ * State: `data-state` (open/closed), `data-spotlight-panel`. Put a `Chat.Title` inside.
+ */
+declare function Panel({ open, onOpenChange, modal, children, ...props }: {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    modal?: boolean;
+} & ComponentPropsWithoutRef<"div">): import("react").JSX.Element;
+export declare const Chat: {
+    Panel: typeof Panel;
+    Title: import("react").ForwardRefExoticComponent<Dialog.DialogTitleProps & import("react").RefAttributes<HTMLHeadingElement>>;
+    Close: import("react").ForwardRefExoticComponent<Dialog.DialogCloseProps & import("react").RefAttributes<HTMLButtonElement>>;
+    Messages: typeof Messages;
+    Content: typeof Content;
+    ScrollButton: typeof ScrollButton;
+    Composer: typeof Composer;
+    Submit: typeof Submit;
+    Markdown: import("react").MemoExoticComponent<({ text, className }: {
+        text: string;
+        className?: string;
+    }) => import("react").JSX.Element>;
+};
+export {};

package/dist/chat/parts.js

@@ -0,0 +1,69 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as Dialog from "@radix-ui/react-dialog";
+import { memo } from "react";
+import { Streamdown } from "streamdown";
+import { StickToBottom, useStickToBottomContext } from "use-stick-to-bottom";
+/**
+ * The conversation's scroll box: stays scrolled to the bottom while an answer streams, unless the
+ * visitor scrolled up. `Chat.Content` holds the messages; `Chat.ScrollButton` shows while not at
+ * the bottom.
+ */
+function Messages({ children, ...props }) {
+    return (_jsx(StickToBottom, { initial: "smooth", resize: "smooth", role: "log", "data-spotlight-messages": "", ...props, children: children }));
+}
+/** The scrolling element and the content inside it (`viewportProps` go on the scrolling one). */
+function Content({ children, viewportProps, ...props }) {
+    const { scrollRef, contentRef } = useStickToBottomContext();
+    return (_jsx("div", { ref: scrollRef, "data-spotlight-viewport": "", "data-lenis-prevent": "", ...viewportProps, children: _jsx("div", { ref: contentRef, "data-spotlight-content": "", ...props, children: children }) }));
+}
+/** Back to the newest message; renders only while scrolled up. */
+function ScrollButton({ onClick, ...props }) {
+    const { isAtBottom, scrollToBottom } = useStickToBottomContext();
+    if (isAtBottom)
+        return null;
+    return (_jsx("button", { type: "button", "data-spotlight-scroll-button": "", ...props, onClick: (e) => {
+            onClick?.(e);
+            void scrollToBottom();
+        } }));
+}
+/**
+ * The composer: a form with a growing textarea; Enter sends, Shift+Enter breaks the line.
+ * `children` render after the textarea (the send or stop button: `Chat.Submit`).
+ */
+function Composer({ chat, children, textareaProps, ...props }) {
+    return (_jsxs("form", { "data-spotlight-composer": "", ...props, onSubmit: (e) => {
+            e.preventDefault();
+            chat.send(chat.input);
+        }, children: [_jsx("textarea", { value: chat.input, onChange: (e) => chat.setInput(e.target.value), onKeyDown: (e) => {
+                    if (e.key === "Enter" && !e.shiftKey && !e.nativeEvent.isComposing) {
+                        e.preventDefault();
+                        chat.send(chat.input);
+                    }
+                }, placeholder: chat.copy.placeholderAsk, "aria-label": chat.copy.placeholderAsk, maxLength: chat.maxInput, rows: 1, ...textareaProps }), children] }));
+}
+/** Send while idle (disabled with nothing typed), stop while an answer runs. `data-action` says which. */
+function Submit({ chat, send, stop, ...props }) {
+    return chat.busy ? (_jsx("button", { type: "button", "data-spotlight-submit": "", "data-action": "stop", "aria-label": chat.copy.stop, ...props, onClick: () => void chat.stop(), children: stop })) : (_jsx("button", { type: "submit", "data-spotlight-submit": "", "data-action": "send", "aria-label": chat.copy.send, disabled: !chat.input.trim(), ...props, children: send }));
+}
+/**
+ * An answer's markdown, streamed safely (Streamdown), unstyled: style it through `className`.
+ * Links open in place (the panel decides where they go); memoised on the text.
+ */
+const Markdown = memo(({ text, className }) => (_jsx(Streamdown, { className: className, linkSafety: { enabled: false }, children: text })), (a, b) => a.text === b.text && a.className === b.className);
+/**
+ * The panel's dialog (Radix): non-modal by default, so the page stays usable behind it; a press
+ * outside does not close it (only `Chat.Close` or Escape). `modal` for a sheet over the page.
+ * State: `data-state` (open/closed), `data-spotlight-panel`. Put a `Chat.Title` inside.
+ */
+function Panel({ open, onOpenChange, modal = false, children, ...props }) {
+    return (_jsx(Dialog.Root, { open: open, onOpenChange: onOpenChange, modal: modal, children: _jsx(Dialog.Portal, { children: _jsx(Dialog.Content, { "data-spotlight-panel": "", "aria-describedby": undefined, onInteractOutside: (e) => {
+                    if (!modal)
+                        e.preventDefault();
+                }, ...props, children: children }) }) }));
+}
+/** The panel's accessible title (shown; hide it yourself if you want it for screen readers only). */
+const Title = Dialog.Title;
+/** Closes the panel. */
+const Close = Dialog.Close;
+export const Chat = { Panel, Title, Close, Messages, Content, ScrollButton, Composer, Submit, Markdown };

package/dist/chat/useAskChat.d.ts

@@ -0,0 +1,67 @@
+import { type ChatTransport, type UIMessage } from "ai";
+import { calledTool, sourcesOf } from "../core/messages.js";
+import type { Action, AskConfig, ChatMessage } from "../types.js";
+/**
+ * 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 declare function defaultTransport(ask: AskConfig): ChatTransport<UIMessage>;
+export type ChatView = {
+    kind: "chat";
+} | {
+    kind: "action";
+    action: Action;
+    input: unknown;
+    key: number;
+};
+export interface UseAskChatOptions {
+    /**
+     * Tool names that only drive the interface (an action, a "show the contact options" tool): the
+     * answer text is not cut at them (see `textOf`). The actions' own tools are added.
+     */
+    uiTools?: string[];
+}
+/**
+ * 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 declare function useAskChat({ uiTools }?: UseAskChatOptions): {
+    id: string;
+    messages: ChatMessage[];
+    status: import("ai").ChatStatus;
+    busy: boolean;
+    waiting: boolean;
+    error: Error | undefined;
+    /** The error's code, a key of `copy.errors` (`generic` for unknown ones); null without an error. */
+    errorCode: string | null;
+    input: string;
+    setInput: import("react").Dispatch<import("react").SetStateAction<string>>;
+    send: (value: string) => void;
+    stop: () => Promise<void>;
+    reset: () => void;
+    newChat: () => void;
+    back: () => void;
+    close: () => void;
+    view: ChatView;
+    setView: import("react").Dispatch<import("react").SetStateAction<ChatView>>;
+    openAction: (action: Action, value: unknown) => void;
+    actionOf: (m: ChatMessage) => {
+        action: Action;
+        input: unknown;
+        callId: string;
+    } | null;
+    lastAssistant: ChatMessage | undefined;
+    /** A message's text (answers: after the last content tool call). */
+    textOf: (m: ChatMessage) => string;
+    sourcesOf: typeof sourcesOf;
+    /** True when the message called `tool` (e.g. a handoff tool that shows contact options). */
+    calledTool: typeof calledTool;
+    copy: import("../types.js").SpotlightCopy;
+    /** Characters in one question (`ask.maxInput`). */
+    maxInput: number;
+    chat: import("@ai-sdk/react").UseChatHelpers<UIMessage<unknown, import("ai").UIDataTypes, import("ai").UITools>>;
+};
+export type AskChat = ReturnType<typeof useAskChat>;