rift-ds 1.6.0 → 1.8.0

package/chat/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * rift-ds/chat: the composed chat widget and the engine under it.
+ *
+ * The widget: ChatProvider (the state), ChatWidget (the surface), ChatLauncher
+ * (the floating button and the docked / overlay / floating / takeover panel).
+ * The engine, importable on its own under your own markup: useChat, the
+ * transports, useThreads, and the event contract. The server half lives in
+ * rift-ds/chat/server; a scripted conversation for previews in
+ * rift-ds/chat/demo.
+ *
+ * Hand-written, unlike the component barrels: the registry generator never
+ * reaches src/chat, and this file is the one place the widget's public
+ * surface is declared (src/chat/registry.json names the same exports for the
+ * documentation, and validate-chat-widget.mjs holds the two together).
+ */
+export { ChatProvider, type ChatProviderProps } from './ChatProvider';
+export { ChatWidget, type ChatWidgetProps, type ChatAgentOptions, type RailSlot } from './ChatWidget';
+export { ChatLauncher, CHAT_PANEL_ID, type ChatLauncherProps } from './ChatLauncher';
+export { ChatThreads, type ChatThreadsProps } from './ChatThreads';
+export { ChatTabs, type ChatTabsProps } from './ChatTabs';
+export { ChatAgentPane, type ChatAgentPaneProps } from './ChatAgentPane';
+export { useChatWidget, isInternalPath, createFeedbackPoster, type ChatView, type ChatCardRenderers, type ChatLinkRenderer, type ChatWidgetContextValue, type FeedbackSink, } from './context';
+export { DOCK_QUERY, TAKEOVER_QUERY, THREADS_RAIL_MIN_WIDTH, ASIDE_RAIL_MIN_WIDTH, useTakeoverViewport, } from './queries';
+export { useChat, DEFAULT_PLACEHOLDER_COPY, type ChatState, type ChatPlaceholderCopy, } from './useChat';
+export { useThreads, THREAD_NAMING_DELAY_MS, type ThreadsOptions, type ThreadsState } from './threads';
+export { createFetchTransport, DEFAULT_FETCH_COPY, FIRST_BYTE_TIMEOUT_MS, MAX_TRANSPORT_TURNS, type FetchTransportOptions, type FetchTransportCopy, } from './transport';
+export { scriptChat, createSimTransport, defaultFilesReply, DEFAULT_FALLBACK_REPLY, DEFAULT_SIM_TIMING, type ChatScript, type ChatScriptBuilder, type ScriptNode, type ScriptStep, type ScriptedReply, type SimTiming, } from './sim';
+export { createFollowupsFetcher, followupTarget, pickFallbackFollowups, DEFAULT_FALLBACK_FOLLOWUPS, MAX_FOLLOWUPS, FOLLOWUPS_TIMEOUT_MS, type FollowupsSource, } from './followups';
+export { SUGGESTION_MAX_CHARS, fitsChip } from './suggestions';
+export { STARTER_COUNT, pickStarters, namedStarter, hashString, mulberry32, } from './starters';
+export { greetingFor, readGreeting, serverGreeting, subscribeClock, DEFAULT_GREETING_COPY, type GreetingCopy, } from './greeting';
+export { CHAT_PLACEMENTS, chatPlacement, DOCK_MIN_WIDTH, DOCK_MAX_WIDTH, FLOAT_MAX_SCALE, FLOAT_EDGE_GAP, dockWidthFromDrag, isFloatDragStart, clampFloatPosition, type ChatPlacement, type ChatSide, } from './placement';
+export { CHAT_EVENT_KINDS, type ChatCard, type ChatEvent, type ChatTransport, type ChatTransportMessage, type ChatTurn, type ChatModelOption, type ChatFeedbackVerdict, type LivePhase, type LiveResponse, type Starter, } from './types';
+export { chatWidget, chatWidgetRegistry, WIDGET_COUNT, type ChatWidgetMeta } from './registry';

package/chat/index.js

@@ -0,0 +1,80 @@
+import { ChatProvider } from "./ChatProvider.js";
+import { ChatWidget } from "./ChatWidget.js";
+import { CHAT_PANEL_ID, ChatLauncher } from "./ChatLauncher.js";
+import { ChatThreads } from "./ChatThreads.js";
+import { ChatTabs } from "./ChatTabs.js";
+import { ChatAgentPane } from "./ChatAgentPane.js";
+import { createFeedbackPoster, isInternalPath, useChatWidget } from "./context.js";
+import { ASIDE_RAIL_MIN_WIDTH, DOCK_QUERY, TAKEOVER_QUERY, THREADS_RAIL_MIN_WIDTH, useTakeoverViewport } from "./queries.js";
+import { DEFAULT_PLACEHOLDER_COPY, useChat } from "./useChat.js";
+import { THREAD_NAMING_DELAY_MS, useThreads } from "./threads.js";
+import { DEFAULT_FETCH_COPY, FIRST_BYTE_TIMEOUT_MS, MAX_TRANSPORT_TURNS, createFetchTransport } from "./transport.js";
+import { DEFAULT_FALLBACK_REPLY, DEFAULT_SIM_TIMING, createSimTransport, defaultFilesReply, scriptChat } from "./sim.js";
+import { DEFAULT_FALLBACK_FOLLOWUPS, FOLLOWUPS_TIMEOUT_MS, MAX_FOLLOWUPS, createFollowupsFetcher, followupTarget, pickFallbackFollowups } from "./followups.js";
+import { SUGGESTION_MAX_CHARS, fitsChip } from "./suggestions.js";
+import { STARTER_COUNT, hashString, mulberry32, namedStarter, pickStarters } from "./starters.js";
+import { DEFAULT_GREETING_COPY, greetingFor, readGreeting, serverGreeting, subscribeClock } from "./greeting.js";
+import { CHAT_PLACEMENTS, DOCK_MAX_WIDTH, DOCK_MIN_WIDTH, FLOAT_EDGE_GAP, FLOAT_MAX_SCALE, chatPlacement, clampFloatPosition, dockWidthFromDrag, isFloatDragStart } from "./placement.js";
+import { CHAT_EVENT_KINDS } from "./types.js";
+import { WIDGET_COUNT, chatWidget, chatWidgetRegistry } from "./registry.js";
+export {
+  ASIDE_RAIL_MIN_WIDTH,
+  CHAT_EVENT_KINDS,
+  CHAT_PANEL_ID,
+  CHAT_PLACEMENTS,
+  ChatAgentPane,
+  ChatLauncher,
+  ChatProvider,
+  ChatTabs,
+  ChatThreads,
+  ChatWidget,
+  DEFAULT_FALLBACK_FOLLOWUPS,
+  DEFAULT_FALLBACK_REPLY,
+  DEFAULT_FETCH_COPY,
+  DEFAULT_GREETING_COPY,
+  DEFAULT_PLACEHOLDER_COPY,
+  DEFAULT_SIM_TIMING,
+  DOCK_MAX_WIDTH,
+  DOCK_MIN_WIDTH,
+  DOCK_QUERY,
+  FIRST_BYTE_TIMEOUT_MS,
+  FLOAT_EDGE_GAP,
+  FLOAT_MAX_SCALE,
+  FOLLOWUPS_TIMEOUT_MS,
+  MAX_FOLLOWUPS,
+  MAX_TRANSPORT_TURNS,
+  STARTER_COUNT,
+  SUGGESTION_MAX_CHARS,
+  TAKEOVER_QUERY,
+  THREADS_RAIL_MIN_WIDTH,
+  THREAD_NAMING_DELAY_MS,
+  WIDGET_COUNT,
+  chatPlacement,
+  chatWidget,
+  chatWidgetRegistry,
+  clampFloatPosition,
+  createFeedbackPoster,
+  createFetchTransport,
+  createFollowupsFetcher,
+  createSimTransport,
+  defaultFilesReply,
+  dockWidthFromDrag,
+  fitsChip,
+  followupTarget,
+  greetingFor,
+  hashString,
+  isFloatDragStart,
+  isInternalPath,
+  mulberry32,
+  namedStarter,
+  pickFallbackFollowups,
+  pickStarters,
+  readGreeting,
+  scriptChat,
+  serverGreeting,
+  subscribeClock,
+  useChat,
+  useChatWidget,
+  useTakeoverViewport,
+  useThreads
+};

package/chat/placement.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Where a chat panel sits: docked to either edge, or popped out as a
+ * floating card the visitor moves and sizes. One roster, so the header menu
+ * (ChatWidget), the launcher and any host stage all name the same three
+ * seats the same way. design.md's ChatWidget spec owns the behaviour each
+ * seat promises.
+ *
+ * No React and no component imports, like the dock query's home in
+ * ChatProvider: hosts deep in the tree read it without pulling the widget.
+ */
+/** The edge a docked panel takes, and the edge it overlays from below the dock threshold. */
+export type ChatSide = 'left' | 'right';
+/** A panel's seat: a dock edge, or floating free of both. */
+export type ChatPlacement = ChatSide | 'floating';
+export declare const CHAT_PLACEMENTS: readonly {
+    id: ChatPlacement;
+    label: string;
+    icon: string;
+}[];
+/** The roster entry for a placement: the header trigger wears its icon. */
+export declare const chatPlacement: (id: ChatPlacement) => {
+    id: ChatPlacement;
+    label: string;
+    icon: string;
+};
+export declare const DOCK_MIN_WIDTH = 420;
+export declare const DOCK_MAX_WIDTH = 655;
+/** A docked panel's width after a grip drag: the inner edge is the one
+    that moves, and it faces the other way on the left dock. */
+export declare function dockWidthFromDrag(startWidth: number, pointerDelta: number, side: ChatSide): number;
+export declare const FLOAT_MAX_SCALE = 1.2;
+export declare const FLOAT_EDGE_GAP = 8;
+/** Whether a pointerdown on `target` should start moving a floating card. */
+export declare function isFloatDragStart(target: EventTarget | null): boolean;
+/** Holds a moved card inside `bounds`, FLOAT_EDGE_GAP off each edge. A card
+    larger than the bounds pins to the leading edge rather than oscillating. */
+export declare function clampFloatPosition(x: number, y: number, size: {
+    width: number;
+    height: number;
+}, bounds: {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+}): {
+    x: number;
+    y: number;
+};

package/chat/placement.js

@@ -0,0 +1,39 @@
+const CHAT_PLACEMENTS = [
+  { id: "right", label: "Dock right", icon: "dock_to_left" },
+  { id: "left", label: "Dock left", icon: "dock_to_right" },
+  { id: "floating", label: "Floating", icon: "picture_in_picture" }
+];
+const chatPlacement = (id) => CHAT_PLACEMENTS.find((placement) => placement.id === id) ?? CHAT_PLACEMENTS[0];
+const DOCK_MIN_WIDTH = 420;
+const DOCK_MAX_WIDTH = 655;
+function dockWidthFromDrag(startWidth, pointerDelta, side) {
+  const grown = startWidth + (side === "left" ? pointerDelta : -pointerDelta);
+  return Math.round(Math.min(DOCK_MAX_WIDTH, Math.max(DOCK_MIN_WIDTH, grown)));
+}
+const FLOAT_MAX_SCALE = 1.2;
+const FLOAT_EDGE_GAP = 8;
+const FLOAT_DRAG_ZONE = ".ds-chat-header";
+const FLOAT_DRAG_EXEMPT = "button, a, input, textarea, select, [role='button'], [role='menu']";
+function isFloatDragStart(target) {
+  if (!(target instanceof Element)) return false;
+  return Boolean(target.closest(FLOAT_DRAG_ZONE)) && !target.closest(FLOAT_DRAG_EXEMPT);
+}
+function clampFloatPosition(x, y, size, bounds) {
+  const minX = bounds.left + FLOAT_EDGE_GAP;
+  const minY = bounds.top + FLOAT_EDGE_GAP;
+  return {
+    x: Math.round(Math.min(Math.max(minX, bounds.right - size.width - FLOAT_EDGE_GAP), Math.max(minX, x))),
+    y: Math.round(Math.min(Math.max(minY, bounds.bottom - size.height - FLOAT_EDGE_GAP), Math.max(minY, y)))
+  };
+}
+export {
+  CHAT_PLACEMENTS,
+  DOCK_MAX_WIDTH,
+  DOCK_MIN_WIDTH,
+  FLOAT_EDGE_GAP,
+  FLOAT_MAX_SCALE,
+  chatPlacement,
+  clampFloatPosition,
+  dockWidthFromDrag,
+  isFloatDragStart
+};

package/chat/queries.d.ts

@@ -0,0 +1,9 @@
+export declare const DOCK_QUERY = "(min-width: 1440px)";
+export declare const TAKEOVER_QUERY = "(max-width: 719px)";
+/** The widget's own width thresholds for seating its rails inline. */
+export declare const THREADS_RAIL_MIN_WIDTH = 720;
+export declare const ASIDE_RAIL_MIN_WIDTH = 860;
+/** Whether the viewport is a phone width (TAKEOVER_QUERY), false on the
+    server and for the first client render. Shared by the launcher and any
+    host stage, which both hand the widget its phone layout. */
+export declare function useTakeoverViewport(): boolean;

package/chat/queries.js

@@ -0,0 +1,22 @@
+"use client";
+import { useSyncExternalStore } from "react";
+const DOCK_QUERY = "(min-width: 1440px)";
+const TAKEOVER_QUERY = "(max-width: 719px)";
+const THREADS_RAIL_MIN_WIDTH = 720;
+const ASIDE_RAIL_MIN_WIDTH = 860;
+const subscribeTakeover = (onChange) => {
+  const media = window.matchMedia(TAKEOVER_QUERY);
+  media.addEventListener("change", onChange);
+  return () => media.removeEventListener("change", onChange);
+};
+const readTakeover = () => window.matchMedia(TAKEOVER_QUERY).matches;
+function useTakeoverViewport() {
+  return useSyncExternalStore(subscribeTakeover, readTakeover, () => false);
+}
+export {
+  ASIDE_RAIL_MIN_WIDTH,
+  DOCK_QUERY,
+  TAKEOVER_QUERY,
+  THREADS_RAIL_MIN_WIDTH,
+  useTakeoverViewport
+};

package/chat/registry.d.ts

@@ -0,0 +1,25 @@
+/** One widget's metadata, as the registry records it. */
+export interface ChatWidgetMeta {
+    name: string;
+    slug: string;
+    label: string;
+    description: string;
+    /** The component category whose /components section and sidebar group the widget's page joins. */
+    category: string;
+    /** The init bin's subcommand that scaffolds it. */
+    command: string;
+    /** Each package subpath the widget occupies, with what it holds. */
+    subpaths: Record<string, string>;
+    /** The optional peer dependencies each subpath needs. */
+    peers: Record<string, string[]>;
+    /** The library components the widget composes. */
+    parts: string[];
+    /** The exported components whose props are documented through docgen. */
+    documented: string[];
+}
+export declare const chatWidgetRegistry: {
+    widgets: ChatWidgetMeta[];
+};
+/** The one widget, by design. */
+export declare const chatWidget: ChatWidgetMeta;
+export declare const WIDGET_COUNT: number;

package/chat/registry.js

@@ -0,0 +1,9 @@
+import registry from "./registry.json.js";
+const chatWidgetRegistry = registry;
+const chatWidget = registry.widgets[0];
+const WIDGET_COUNT = registry.widgets.length;
+export {
+  WIDGET_COUNT,
+  chatWidget,
+  chatWidgetRegistry
+};

package/chat/registry.json.d.ts

@@ -0,0 +1,69 @@
+declare const _default: {
+  "$comment": "The widget registry: the fourth kind of thing the package ships, between the components and the templates. One member by design. `parts` names the library components the widget composes (held to src/components/registry.json by scripts/validate-chat-widget.mjs), `subpaths` the package exports it occupies (held to scripts/package-manifest.mjs), `category` the component category whose section and sidebar group its page joins (held to src/components/registry.json), `peers` the optional peer dependencies each subpath needs (held to package.json). The widget's page under /components, the /docs/chat page, the chat corpus and the MCP tools read this file; never type its facts elsewhere.",
+  "widgets": [
+    {
+      "name": "ChatWidget",
+      "slug": "ai-chat",
+      "label": "AI chat",
+      "category": "ai",
+      "description": "The whole AI chat, assembled: the panel, the streaming replies, the history, the cards a reply can carry and the server handlers, set up with props.",
+      "command": "init chat",
+      "subpaths": {
+        "./chat": "The widget, the provider, the launcher and the engine under them.",
+        "./chat/server": "The streaming chat handler and its follow-ups and feedback siblings, for any web-standard route.",
+        "./chat/upstash": "Rate limits, a daily budget and the exchange log over Upstash Redis, as the handlers' guardrails.",
+        "./chat/demo": "A scripted conversation with rich cards and fixtures, for a preview that needs no key.",
+        "./chat/chat.css": "The widget's stylesheet."
+      },
+      "peers": {
+        "./chat": [
+          "react-markdown",
+          "remark-gfm"
+        ],
+        "./chat/server": [
+          "@anthropic-ai/sdk"
+        ],
+        "./chat/upstash": [
+          "@upstash/ratelimit",
+          "@upstash/redis"
+        ],
+        "./chat/demo": [
+          "recharts"
+        ]
+      },
+      "parts": [
+        "AgentRail",
+        "AgentStatus",
+        "AiButton",
+        "AttachmentDropZone",
+        "AttachmentGroup",
+        "ChatHeader",
+        "ChatMessage",
+        "ChatThread",
+        "CircularButton",
+        "CodeBlock",
+        "Composer",
+        "DropdownMenu",
+        "Mention",
+        "ModelPicker",
+        "PixelAvatar",
+        "PromptSuggestions",
+        "Prose",
+        "Reasoning",
+        "ThreadPanel",
+        "ThreadTabs"
+      ],
+      "documented": [
+        "ChatWidget",
+        "ChatProvider",
+        "ChatLauncher",
+        "ChatThreads",
+        "ChatTabs",
+        "ChatAgentPane"
+      ]
+    }
+  ]
+}
+;
+
+export default _default;

package/chat/registry.json.js

@@ -0,0 +1,11 @@
+const $comment = "The widget registry: the fourth kind of thing the package ships, between the components and the templates. One member by design. `parts` names the library components the widget composes (held to src/components/registry.json by scripts/validate-chat-widget.mjs), `subpaths` the package exports it occupies (held to scripts/package-manifest.mjs), `category` the component category whose section and sidebar group its page joins (held to src/components/registry.json), `peers` the optional peer dependencies each subpath needs (held to package.json). The widget's page under /components, the /docs/chat page, the chat corpus and the MCP tools read this file; never type its facts elsewhere.";
+const widgets = [{ "name": "ChatWidget", "slug": "ai-chat", "label": "AI chat", "category": "ai", "description": "The whole AI chat, assembled: the panel, the streaming replies, the history, the cards a reply can carry and the server handlers, set up with props.", "command": "init chat", "subpaths": { "./chat": "The widget, the provider, the launcher and the engine under them.", "./chat/server": "The streaming chat handler and its follow-ups and feedback siblings, for any web-standard route.", "./chat/upstash": "Rate limits, a daily budget and the exchange log over Upstash Redis, as the handlers' guardrails.", "./chat/demo": "A scripted conversation with rich cards and fixtures, for a preview that needs no key.", "./chat/chat.css": "The widget's stylesheet." }, "peers": { "./chat": ["react-markdown", "remark-gfm"], "./chat/server": ["@anthropic-ai/sdk"], "./chat/upstash": ["@upstash/ratelimit", "@upstash/redis"], "./chat/demo": ["recharts"] }, "parts": ["AgentRail", "AgentStatus", "AiButton", "AttachmentDropZone", "AttachmentGroup", "ChatHeader", "ChatMessage", "ChatThread", "CircularButton", "CodeBlock", "Composer", "DropdownMenu", "Mention", "ModelPicker", "PixelAvatar", "PromptSuggestions", "Prose", "Reasoning", "ThreadPanel", "ThreadTabs"], "documented": ["ChatWidget", "ChatProvider", "ChatLauncher", "ChatThreads", "ChatTabs", "ChatAgentPane"] }];
+const registry = {
+  $comment,
+  widgets
+};
+export {
+  $comment,
+  registry as default,
+  widgets
+};

package/chat/server.d.ts

@@ -0,0 +1,217 @@
+import { default as Anthropic } from '@anthropic-ai/sdk';
+import { ChatCard, ChatFeedbackVerdict, ChatModelOption } from './types';
+/** What a tool hands back: text for the model, and optionally a card for the visitor. */
+export interface ChatToolResult {
+    /** The tool result the model reads. */
+    text: string;
+    /** Rich content streamed to the widget as a `card` event, drawn by the provider's renderers. */
+    card?: ChatCard;
+}
+/** One deterministic tool the model may call. */
+export interface ChatTool {
+    /** The Anthropic tool definition: name, description, input schema. */
+    definition: Anthropic.Messages.Tool;
+    /** Runs the tool. Return a string for the model, or a result with a card for the visitor too. Never throw for bad input: return an error string the model can recover from. */
+    execute: (input: Record<string, unknown>) => string | ChatToolResult | Promise<string | ChatToolResult>;
+    /** The trace point shown while the round runs, e.g. "Checked the Button prop contract". */
+    tracePoint?: (input: Record<string, unknown>) => string;
+}
+/**
+ * How much of the day's budget remains, as a model policy: `open` means the
+ * default model serves, `reduced` means the budget model is the default (the
+ * better one stays selectable), `locked` means only the budget model serves.
+ */
+export type ModelTier = 'open' | 'reduced' | 'locked';
+export type GuardrailVerdict = {
+    allowed: true;
+    tier: ModelTier;
+} | {
+    allowed: false;
+    notice: string;
+};
+/** Anthropic's usage block, narrowed to the fields a spend estimate needs. */
+export interface TokenUsage {
+    input_tokens?: number | null;
+    output_tokens?: number | null;
+    cache_creation_input_tokens?: number | null;
+    cache_read_input_tokens?: number | null;
+}
+/** One logged exchange: what was asked, what came back, and the numbers. */
+export interface ExchangeLog {
+    /** Minted per request and streamed to the widget, so a feedback verdict can be joined back to this line. */
+    id: string;
+    question: string;
+    answer: string;
+    /** The sanitised context the request carried, or null. */
+    path: string | null;
+    /** The model id that served, absent on guardrail notices. */
+    model?: string;
+    usage?: TokenUsage;
+    /** Milliseconds from request to the stream closing. */
+    latencyMs: number;
+    /** Milliseconds to the first response text, what the visitor feels. */
+    firstTextMs: number | null;
+    /** True when the answer is a guardrail notice, not a model response. */
+    notice: boolean;
+    /** The opaque per-visitor key. */
+    visitor: string;
+}
+/**
+ * The hooks the handlers call around a request. Every member is optional
+ * and every one fails open: a missing hook means no limit, no log, no
+ * tiering. `rift-ds/chat/upstash` implements the set over Redis.
+ */
+export interface ChatGuardrails {
+    /** Rate limits and the daily breaker. Return a notice to answer with instead of calling the model. */
+    check?: (request: Request) => Promise<GuardrailVerdict>;
+    /** A stable, opaque key for the visitor (a salted hash, never an address). */
+    visitorKey?: (request: Request) => Promise<string> | string;
+    /** Called with the real token counts after every model call. */
+    onUsage?: (usage: TokenUsage, modelId: string) => Promise<void>;
+    /** Called once per exchange. Its presence is what makes the handler stream an `exchange` id, and so what shows the thumbs. */
+    onExchange?: (entry: ExchangeLog) => Promise<void>;
+    /** Per-visitor limit for the follow-ups handler. */
+    checkFollowups?: (request: Request) => Promise<boolean>;
+    /** Per-visitor limit for the feedback handler. */
+    checkFeedback?: (request: Request) => Promise<boolean>;
+    /** Stores one verdict per exchange id. */
+    onFeedback?: (exchangeId: string, verdict: ChatFeedbackVerdict, visitor: string) => Promise<void>;
+}
+export interface ChatLimits {
+    /** Turns kept from the client's history. Older context is dropped. */
+    maxTurns: number;
+    /** Longest single message accepted, in characters. */
+    maxMessageChars: number;
+    /** Longest whole conversation accepted, summed across every kept turn. */
+    maxTotalChars: number;
+    /** Hard ceiling on the raw request body, rejected before it is parsed. */
+    maxBodyChars: number;
+    /** Trace points shown under the status label before the rest is dropped. */
+    maxTracePoints: number;
+}
+export declare const DEFAULT_CHAT_LIMITS: ChatLimits;
+export interface ChatHandlerCopy {
+    /** The reply when the chat is switched off or unconfigured. */
+    disabled: string;
+    /** The reply to a message over `maxMessageChars`. */
+    tooLong: string;
+    /** The reply when the model refuses and nothing was streamed. */
+    refusal: string;
+    /** Appended when the answer hit the token cap. */
+    cutOff: string;
+    /** The first status label, proving the stream opened. */
+    reading: string;
+    /** The status label while thinking. */
+    thinking: string;
+    /** The status label while a tool round runs. */
+    lookingUp: string;
+    /** The error for a busy or overloaded model. */
+    busy: string;
+    /** The error for a rejected key. */
+    unauthorised: string;
+    /** The error for anything else before the first text. */
+    failed: string;
+}
+export declare const DEFAULT_CHAT_COPY: ChatHandlerCopy;
+export type SystemBlocks = Anthropic.Messages.TextBlockParam[];
+export interface ChatHandlerOptions {
+    /** An Anthropic client to reuse, or `apiKey` to build one from. */
+    client?: Anthropic;
+    apiKey?: string;
+    /** The off switch. Defaults to whether a client or key is present. */
+    enabled?: boolean;
+    /**
+     * The system prompt, as blocks. A string is one block; a function builds
+     * them per request from the sanitised context. Put `cache_control` on the
+     * block that holds your corpus, and nothing volatile before it.
+     */
+    system: string | SystemBlocks | ((context: {
+        path: string | null;
+    }) => string | SystemBlocks);
+    /**
+     * An uncached trailing block built from the request's context, after the
+     * cache breakpoint. Defaults to naming the page; return null for none.
+     */
+    contextBlock?: (path: string) => string | null;
+    /** The models on offer. The client sends a `value`; the handler calls the matching `id`. */
+    models: ChatModelOption[];
+    /** The wire value that serves when the budget has headroom and the visitor has not chosen. Defaults to the first model. */
+    defaultModel?: string;
+    /** The wire value that serves once the budget steps down, and the only one past the lock. Defaults to `defaultModel`. */
+    budgetModel?: string;
+    tools?: ChatTool[];
+    /** Model calls per exchange: the first pass plus tool rounds. The last allowed pass withholds the tools. */
+    maxModelCalls?: number;
+    /** Caps thinking and response text together. */
+    maxTokens?: number;
+    /** Adaptive thinking's effort dial, for models that take it. */
+    effort?: 'low' | 'medium' | 'high';
+    guardrails?: ChatGuardrails;
+    limits?: Partial<ChatLimits>;
+    copy?: Partial<ChatHandlerCopy>;
+    /** Turns the request's raw `path` into context, or null to drop it. The default accepts lowercase slug paths only. */
+    sanitiseContext?: (value: unknown) => string | null;
+    /** Keeps a fire-and-forget promise alive on platforms that end work with the response. */
+    waitUntil?: (promise: Promise<unknown>) => void;
+}
+/**
+ * The request's context, sanitised as untrusted input: it lands in a system
+ * block, a stronger position than the user turn. Lowercase slug segments
+ * only, capped short; nothing expressible in that alphabet can carry an
+ * instruction. Anything else is dropped, never rejected.
+ */
+export declare function sanitisePath(value: unknown): string | null;
+/**
+ * The chat handler: `(request) => Response`, streaming NDJSON `ChatEvent`s.
+ */
+export declare function createChatHandler(options: ChatHandlerOptions): (request: Request) => Promise<Response>;
+export interface FollowupsHandlerOptions {
+    client?: Anthropic;
+    apiKey?: string;
+    enabled?: boolean;
+    /** The model id that writes the questions. A small one: the job is three short lines. */
+    model: string;
+    /**
+     * What the chat is about, in a phrase the prompt can use: "the Acme
+     * workspace app and its documentation". Ignored when `system` is given.
+     */
+    about?: string;
+    /** A complete system prompt, replacing the built-in one. */
+    system?: string;
+    /** Example questions in the voice wanted, shown to the model. */
+    examples?: string[];
+    guardrails?: Pick<ChatGuardrails, 'checkFollowups' | 'onUsage'>;
+    /** Chips shown. */
+    wanted?: number;
+    /** Candidates asked for, so a few long ones still leave a full row. */
+    candidates?: number;
+    /** Cap on the upstream call, inside the widget's own wait. */
+    timeoutMs?: number;
+}
+/** The built-in follow-ups prompt. */
+export declare function followupsSystemPrompt({ about, candidates, examples, }: {
+    about: string;
+    candidates: number;
+    examples: string[];
+}): string;
+/**
+ * The model's lines to the chips that are safe to show: plain text, one
+ * short question each, no duplicates, at most `wanted`. Anything that does
+ * not fit the shape is dropped rather than repaired.
+ */
+export declare function parseFollowups(text: string, wanted?: number): string[];
+/**
+ * The follow-ups handler: POST `{ question, answer }`, respond
+ * `{ suggestions: string[] }`, empty on every failure. A second call rather
+ * than part of the answer's stream, because the questions are written from
+ * the completed answer.
+ */
+export declare function createFollowupsHandler(options: FollowupsHandlerOptions): (request: Request) => Promise<Response>;
+/**
+ * The feedback handler: POST `{ id, verdict }`, respond 204. The id is never
+ * trusted to exist; a verdict for an id no exchange used is a write nothing
+ * will join against, so validation is a shape check, not a lookup.
+ */
+export declare function createFeedbackHandler(options?: {
+    guardrails?: Pick<ChatGuardrails, 'checkFeedback' | 'onFeedback' | 'visitorKey'>;
+}): (request: Request) => Promise<Response>;