rift-ds 1.8.0 → 1.10.0

package/chat/demo.css

@@ -44,3 +44,9 @@
 .ds-chat-demo__logo--three {
   background-color: var(--color-chart-series-3);
 }
+
+/* The dashboard artifact: the welcome board, given the inset a panel's
+   live content brings for itself. */
+.ds-chat-demo__artifact-board {
+  padding: var(--padding-400);
+}

package/chat/demo.d.ts

@@ -1,6 +1,7 @@
 import { SimTiming } from './sim';
 import { ChatTransport } from './types';
 export { DEMO_RENDERERS, type DemoProductCard, type DemoChartCard, type DemoSourcesCard, type DemoToolCallCard, type DemoDiffCard, type DemoPlanCard, type DemoInterruptCard, type DemoStackCard, } from './demo-cards';
+export { DEMO_ARTIFACT_RENDERERS, DEMO_DASHBOARD_ARTIFACT, DEMO_PAGE_ARTIFACT, } from './demo-artifacts';
 export { DEMO_SCRIPT, DEMO_STARTERS } from './demo-script';
 export { DEMO_MENTIONS, DEMO_MODELS, DEMO_THREAD_GROUPS, DEMO_PROJECTS, DEMO_THREAD_NAMES, DEMO_THREADS, DEMO_WELCOME_OPTIONS, type DemoWelcomeVariant, } from './demo-fixtures';
 export { demoAgentTabs } from './demo-agent';

package/chat/demo.js

@@ -2,13 +2,17 @@ import { createSimTransport } from "./sim.js";
 import { DEMO_SCRIPT } from "./demo-script.js";
 import { DEMO_STARTERS } from "./demo-script.js";
 import { DEMO_RENDERERS } from "./demo-cards.js";
+import { DEMO_ARTIFACT_RENDERERS, DEMO_DASHBOARD_ARTIFACT, DEMO_PAGE_ARTIFACT } from "./demo-artifacts.js";
 import { DEMO_MENTIONS, DEMO_MODELS, DEMO_PROJECTS, DEMO_THREADS, DEMO_THREAD_GROUPS, DEMO_THREAD_NAMES, DEMO_WELCOME_OPTIONS } from "./demo-fixtures.js";
 import { demoAgentTabs } from "./demo-agent.js";
 import { DemoBoard, DemoWelcome } from "./DemoWelcome.js";
 const createDemoTransport = (timing) => createSimTransport(DEMO_SCRIPT, timing);
 export {
+  DEMO_ARTIFACT_RENDERERS,
+  DEMO_DASHBOARD_ARTIFACT,
   DEMO_MENTIONS,
   DEMO_MODELS,
+  DEMO_PAGE_ARTIFACT,
   DEMO_PROJECTS,
   DEMO_RENDERERS,
   DEMO_SCRIPT,

package/chat/followups.d.ts

@@ -31,8 +31,8 @@ export declare function createFollowupsFetcher(endpoint?: string): FollowupsSour
 /**
  * The turn to ask about, or null when there is nothing to ask about yet:
  * the newest turn must be a committed assistant answer that came from a
- * backend (an exchange id is the marker, as it is for the thumbs) and has
- * not been asked about already.
+ * backend (an exchange id is the marker, as it is for the thumbs), has
+ * not been asked about already, and asks no question of its own.
  */
 export declare function followupTarget(turns: ChatTurn[]): {
     id: string;

package/chat/followups.js

@@ -41,6 +41,7 @@ function followupTarget(turns) {
   const last = turns[turns.length - 1];
   if (!last || last.role !== "assistant") return null;
   if (!last.exchangeId || last.followups || last.text === "") return null;
+  if (last.question) return null;
   const question = turns[turns.length - 2];
   if (!question || question.role !== "user") return null;
   return { id: last.id, question: question.text, answer: last.text };

package/chat/index.d.ts

@@ -19,16 +19,20 @@ export { ChatLauncher, CHAT_PANEL_ID, type ChatLauncherProps } from './ChatLaunc
 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 { ChatArtifactPane, type ChatArtifactPaneProps } from './ChatArtifactPane';
+export { ChatArtifactCard, type ChatArtifactCardProps } from './ChatArtifactCard';
+export { useChatWidget, isInternalPath, createFeedbackPoster, type ChatView, type ChatArtifactRenderers, type ChatCardRenderers, type ChatLinkRenderer, type ChatWidgetContextValue, type FeedbackSink, } from './context';
+export { DOCK_QUERY, TAKEOVER_QUERY, THREADS_RAIL_MIN_WIDTH, ASIDE_RAIL_MIN_WIDTH, ARTIFACT_MIN_COLUMN_WIDTH, ASIDE_WITH_THREADS_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 { sanitizeQuestionSet, describeAnswers, serializeReply, isBlockingQuestion, ASK_USER_INPUT_SCHEMA, MAX_QUESTIONS, MAX_QUESTION_OPTIONS, MIN_QUESTION_OPTIONS, QUESTION_PROMPT_MAX_CHARS, OPTION_DESCRIPTION_MAX_CHARS, } from './questions';
 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 { artifactCard, cardArtifact } from './artifacts';
+export { ARTIFACT_CARD_KIND, CHAT_EVENT_KINDS, type ChatArtifact, type ChatCard, type ChatEvent, type ChatQuestion, type ChatQuestionAnswer, type ChatQuestionSet, type ChatReply, 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

@@ -4,25 +4,35 @@ import { CHAT_PANEL_ID, ChatLauncher } from "./ChatLauncher.js";
 import { ChatThreads } from "./ChatThreads.js";
 import { ChatTabs } from "./ChatTabs.js";
 import { ChatAgentPane } from "./ChatAgentPane.js";
+import { ChatArtifactPane } from "./ChatArtifactPane.js";
+import { ChatArtifactCard } from "./ChatArtifactCard.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 { ARTIFACT_MIN_COLUMN_WIDTH, ASIDE_RAIL_MIN_WIDTH, ASIDE_WITH_THREADS_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 { ASK_USER_INPUT_SCHEMA, MAX_QUESTIONS, MAX_QUESTION_OPTIONS, MIN_QUESTION_OPTIONS, OPTION_DESCRIPTION_MAX_CHARS, QUESTION_PROMPT_MAX_CHARS, describeAnswers, isBlockingQuestion, sanitizeQuestionSet, serializeReply } from "./questions.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 { artifactCard, cardArtifact } from "./artifacts.js";
+import { ARTIFACT_CARD_KIND, CHAT_EVENT_KINDS } from "./types.js";
 import { WIDGET_COUNT, chatWidget, chatWidgetRegistry } from "./registry.js";
 export {
+  ARTIFACT_CARD_KIND,
+  ARTIFACT_MIN_COLUMN_WIDTH,
   ASIDE_RAIL_MIN_WIDTH,
+  ASIDE_WITH_THREADS_MIN_WIDTH,
+  ASK_USER_INPUT_SCHEMA,
   CHAT_EVENT_KINDS,
   CHAT_PANEL_ID,
   CHAT_PLACEMENTS,
   ChatAgentPane,
+  ChatArtifactCard,
+  ChatArtifactPane,
   ChatLauncher,
   ChatProvider,
   ChatTabs,
@@ -42,13 +52,20 @@ export {
   FLOAT_MAX_SCALE,
   FOLLOWUPS_TIMEOUT_MS,
   MAX_FOLLOWUPS,
+  MAX_QUESTIONS,
+  MAX_QUESTION_OPTIONS,
   MAX_TRANSPORT_TURNS,
+  MIN_QUESTION_OPTIONS,
+  OPTION_DESCRIPTION_MAX_CHARS,
+  QUESTION_PROMPT_MAX_CHARS,
   STARTER_COUNT,
   SUGGESTION_MAX_CHARS,
   TAKEOVER_QUERY,
   THREADS_RAIL_MIN_WIDTH,
   THREAD_NAMING_DELAY_MS,
   WIDGET_COUNT,
+  artifactCard,
+  cardArtifact,
   chatPlacement,
   chatWidget,
   chatWidgetRegistry,
@@ -58,11 +75,13 @@ export {
   createFollowupsFetcher,
   createSimTransport,
   defaultFilesReply,
+  describeAnswers,
   dockWidthFromDrag,
   fitsChip,
   followupTarget,
   greetingFor,
   hashString,
+  isBlockingQuestion,
   isFloatDragStart,
   isInternalPath,
   mulberry32,
@@ -70,7 +89,9 @@ export {
   pickFallbackFollowups,
   pickStarters,
   readGreeting,
+  sanitizeQuestionSet,
   scriptChat,
+  serializeReply,
   serverGreeting,
   subscribeClock,
   useChat,

package/chat/queries.d.ts

@@ -1,8 +1,17 @@
-export declare const DOCK_QUERY = "(min-width: 1440px)";
-export declare const TAKEOVER_QUERY = "(max-width: 719px)";
+export declare const DOCK_QUERY: string;
+export declare const TAKEOVER_QUERY: string;
 /** 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;
+/** The trailing seat's threshold, one number for both of its tenants: at
+    this width and up the agent pane and the artifact panel sit beside the
+    conversation, below it each rises as a bottom sheet. */
+export declare const ASIDE_RAIL_MIN_WIDTH = 760;
+/** Below this the inline threads rail yields its room to a trailing panel
+    seated inline, and goes back behind the header's hamburger. */
+export declare const ASIDE_WITH_THREADS_MIN_WIDTH = 1040;
+/** The floor either column keeps while an artifact is dragged wider or
+    narrower: the conversation never loses more than this, nor the panel. */
+export declare const ARTIFACT_MIN_COLUMN_WIDTH = 320;
 /** 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. */

package/chat/queries.js

@@ -1,9 +1,12 @@
 "use client";
 import { useSyncExternalStore } from "react";
-const DOCK_QUERY = "(min-width: 1440px)";
-const TAKEOVER_QUERY = "(max-width: 719px)";
+import { mediaAbove, mediaBelow, BREAKPOINT_CHAT_TAKEOVER_PX, BREAKPOINT_CHAT_DOCK_PX } from "../tokens/breakpoints.js";
+const DOCK_QUERY = mediaAbove(BREAKPOINT_CHAT_DOCK_PX);
+const TAKEOVER_QUERY = mediaBelow(BREAKPOINT_CHAT_TAKEOVER_PX);
 const THREADS_RAIL_MIN_WIDTH = 720;
-const ASIDE_RAIL_MIN_WIDTH = 860;
+const ASIDE_RAIL_MIN_WIDTH = 760;
+const ASIDE_WITH_THREADS_MIN_WIDTH = 1040;
+const ARTIFACT_MIN_COLUMN_WIDTH = 320;
 const subscribeTakeover = (onChange) => {
   const media = window.matchMedia(TAKEOVER_QUERY);
   media.addEventListener("change", onChange);
@@ -14,7 +17,9 @@ function useTakeoverViewport() {
   return useSyncExternalStore(subscribeTakeover, readTakeover, () => false);
 }
 export {
+  ARTIFACT_MIN_COLUMN_WIDTH,
   ASIDE_RAIL_MIN_WIDTH,
+  ASIDE_WITH_THREADS_MIN_WIDTH,
   DOCK_QUERY,
   TAKEOVER_QUERY,
   THREADS_RAIL_MIN_WIDTH,

package/chat/questions.d.ts

@@ -0,0 +1,97 @@
+import { ChatQuestionAnswer, ChatQuestionSet, ChatReply, ChatTurn } from './types';
+/** Questions in one set. A longer interview belongs in a form, not a chat turn. */
+export declare const MAX_QUESTIONS = 4;
+/** Options in one question, before "Something else". */
+export declare const MAX_QUESTION_OPTIONS = 5;
+/** Options in one question at the least: one option is not a choice. */
+export declare const MIN_QUESTION_OPTIONS = 2;
+/** A question's own heading: a few words, one line in a docked panel. */
+export declare const QUESTION_PROMPT_MAX_CHARS = 60;
+/** An option's second line. */
+export declare const OPTION_DESCRIPTION_MAX_CHARS = 80;
+/**
+ * The question set the widget may render, or null. Questions that are
+ * malformed or over budget are dropped one by one; a set left with none,
+ * or with more than `MAX_QUESTIONS`, is dropped whole.
+ */
+export declare function sanitizeQuestionSet(input: unknown, fallbackId?: string): ChatQuestionSet | null;
+/**
+ * Whether a turn's questions hold the composer: a set of more than one,
+ * still open, on the newest turn. One question never does: typing instead
+ * of tapping is a fine answer to it, and leaves the card marked unanswered.
+ */
+export declare function isBlockingQuestion(turn: ChatTurn | undefined, live: boolean): boolean;
+/** What each answered question reads as: its prompt and the labels picked. */
+export declare function describeAnswers(set: ChatQuestionSet, answers: ChatQuestionAnswer[]): ChatReply;
+/**
+ * The answers as the plain message the model reads. One question reads as
+ * the answer alone ("Vite", "Components, Tokens"), because the model's own
+ * reply just asked it; a set names each question so the answers cannot be
+ * paired with the wrong one.
+ */
+export declare function serializeReply(reply: ChatReply): string;
+/**
+ * The `ask_user` tool's input schema, for `createChatHandler`. Exported so
+ * a host running its own loop asks for the same shape the widget renders.
+ */
+export declare const ASK_USER_INPUT_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly questions: {
+            readonly type: "array";
+            readonly minItems: 1;
+            readonly maxItems: 4;
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly id: {
+                        readonly type: "string";
+                        readonly description: "A short stable key for the question, e.g. \"framework\".";
+                    };
+                    readonly prompt: {
+                        readonly type: "string";
+                        readonly description: "The question in a few words, at most 60 characters, e.g. \"Which framework?\".";
+                    };
+                    readonly mode: {
+                        readonly type: "string";
+                        readonly enum: readonly ["single", "multi"];
+                        readonly description: "single when exactly one answer fits; multi when several can be true at once.";
+                    };
+                    readonly options: {
+                        readonly type: "array";
+                        readonly minItems: 2;
+                        readonly maxItems: 5;
+                        readonly items: {
+                            readonly type: "object";
+                            readonly properties: {
+                                readonly label: {
+                                    readonly type: "string";
+                                    readonly description: "The answer as the person would say it, at most 40 characters.";
+                                };
+                                readonly description: {
+                                    readonly type: "string";
+                                    readonly description: "Optional: what choosing it means, at most 80 characters.";
+                                };
+                            };
+                            readonly required: readonly ["label"];
+                        };
+                    };
+                    readonly other: {
+                        readonly type: "boolean";
+                        readonly description: "Offer a free-text \"Something else\" when the options may not cover every answer.";
+                    };
+                    readonly min: {
+                        readonly type: "integer";
+                        readonly description: "multi only: the fewest picks that make an answer.";
+                    };
+                    readonly max: {
+                        readonly type: "integer";
+                        readonly description: "multi only: the most picks allowed.";
+                    };
+                };
+                readonly required: readonly ["prompt", "options"];
+            };
+        };
+    };
+    readonly required: readonly ["questions"];
+};

package/chat/questions.js

@@ -0,0 +1,140 @@
+import { SUGGESTION_MAX_CHARS, fitsChip } from "./suggestions.js";
+const MAX_QUESTIONS = 4;
+const MAX_QUESTION_OPTIONS = 5;
+const MIN_QUESTION_OPTIONS = 2;
+const QUESTION_PROMPT_MAX_CHARS = 60;
+const OPTION_DESCRIPTION_MAX_CHARS = 80;
+const str = (value) => typeof value === "string" ? value.trim() : "";
+const slug = (text, index) => text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 40) || `option-${index + 1}`;
+function sanitizeQuestion(input, index) {
+  if (typeof input !== "object" || input === null) return null;
+  const raw = input;
+  const prompt = str(raw.prompt);
+  if (!prompt || prompt.length > QUESTION_PROMPT_MAX_CHARS) return null;
+  const mode = raw.mode === "multi" ? "multi" : "single";
+  if (!Array.isArray(raw.options)) return null;
+  const options = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const [optionIndex, entry] of raw.options.entries()) {
+    if (typeof entry !== "object" || entry === null) return null;
+    const option = entry;
+    const label = str(option.label);
+    if (!fitsChip(label)) return null;
+    const value = str(option.value) || slug(label, optionIndex);
+    if (seen.has(value) || seen.has(label.toLowerCase())) return null;
+    seen.add(value);
+    seen.add(label.toLowerCase());
+    const description = str(option.description);
+    options.push(
+      description && description.length <= OPTION_DESCRIPTION_MAX_CHARS ? { value, label, description } : { value, label }
+    );
+  }
+  if (options.length < MIN_QUESTION_OPTIONS || options.length > MAX_QUESTION_OPTIONS) return null;
+  const question = {
+    id: str(raw.id) || `q${index + 1}`,
+    prompt,
+    mode,
+    options
+  };
+  if (raw.other === true) question.other = true;
+  if (mode === "multi") {
+    const available = options.length + (question.other ? 1 : 0);
+    const min = typeof raw.min === "number" ? Math.floor(raw.min) : 1;
+    const max = typeof raw.max === "number" ? Math.floor(raw.max) : available;
+    if (min < 1 || max < min || max > available) return null;
+    if (min !== 1) question.min = min;
+    if (max !== available) question.max = max;
+  }
+  return question;
+}
+function sanitizeQuestionSet(input, fallbackId = "questions") {
+  if (typeof input !== "object" || input === null) return null;
+  const raw = input;
+  if (!Array.isArray(raw.questions) || raw.questions.length > MAX_QUESTIONS) return null;
+  const questions = raw.questions.map((question, index) => sanitizeQuestion(question, index)).filter((question) => question !== null);
+  if (questions.length === 0) return null;
+  if (new Set(questions.map((question) => question.id)).size !== questions.length) return null;
+  return { id: str(raw.id) || fallbackId, questions };
+}
+function isBlockingQuestion(turn, live) {
+  return !live && turn?.role === "assistant" && !!turn.question && turn.question.questions.length > 1 && turn.answers === void 0;
+}
+function describeAnswers(set, answers) {
+  return {
+    items: set.questions.map((question) => {
+      const answer = answers.find((entry) => entry.questionId === question.id);
+      const labels = question.options.filter((option) => answer?.values.includes(option.value)).map((option) => option.label);
+      if (answer?.other) labels.push(answer.other);
+      return { prompt: question.prompt, answers: labels };
+    })
+  };
+}
+function serializeReply(reply) {
+  const answered = (labels) => labels.length > 0 ? labels.join(", ") : "(no answer)";
+  if (reply.items.length === 1) return answered(reply.items[0].answers);
+  return reply.items.map((item) => `${item.prompt} ${answered(item.answers)}`).join("\n");
+}
+const ASK_USER_INPUT_SCHEMA = {
+  type: "object",
+  properties: {
+    questions: {
+      type: "array",
+      minItems: 1,
+      maxItems: MAX_QUESTIONS,
+      items: {
+        type: "object",
+        properties: {
+          id: { type: "string", description: 'A short stable key for the question, e.g. "framework".' },
+          prompt: {
+            type: "string",
+            description: `The question in a few words, at most ${QUESTION_PROMPT_MAX_CHARS} characters, e.g. "Which framework?".`
+          },
+          mode: {
+            type: "string",
+            enum: ["single", "multi"],
+            description: "single when exactly one answer fits; multi when several can be true at once."
+          },
+          options: {
+            type: "array",
+            minItems: MIN_QUESTION_OPTIONS,
+            maxItems: MAX_QUESTION_OPTIONS,
+            items: {
+              type: "object",
+              properties: {
+                label: {
+                  type: "string",
+                  description: `The answer as the person would say it, at most ${SUGGESTION_MAX_CHARS} characters.`
+                },
+                description: {
+                  type: "string",
+                  description: `Optional: what choosing it means, at most ${OPTION_DESCRIPTION_MAX_CHARS} characters.`
+                }
+              },
+              required: ["label"]
+            }
+          },
+          other: {
+            type: "boolean",
+            description: 'Offer a free-text "Something else" when the options may not cover every answer.'
+          },
+          min: { type: "integer", description: "multi only: the fewest picks that make an answer." },
+          max: { type: "integer", description: "multi only: the most picks allowed." }
+        },
+        required: ["prompt", "options"]
+      }
+    }
+  },
+  required: ["questions"]
+};
+export {
+  ASK_USER_INPUT_SCHEMA,
+  MAX_QUESTIONS,
+  MAX_QUESTION_OPTIONS,
+  MIN_QUESTION_OPTIONS,
+  OPTION_DESCRIPTION_MAX_CHARS,
+  QUESTION_PROMPT_MAX_CHARS,
+  describeAnswers,
+  isBlockingQuestion,
+  sanitizeQuestionSet,
+  serializeReply
+};

package/chat/registry.json.d.ts

@@ -6,11 +6,11 @@ declare const _default: {
       "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.",
+      "description": "The whole AI chat: the panel, the streaming replies, the history, the cards and questions 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/server": "The streaming chat handler, with an opt-in tool for asking the visitor questions, 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."
@@ -35,6 +35,8 @@ declare const _default: {
         "AgentRail",
         "AgentStatus",
         "AiButton",
+        "ArtifactCard",
+        "ArtifactPanel",
         "AttachmentDropZone",
         "AttachmentGroup",
         "ChatHeader",
@@ -44,11 +46,13 @@ declare const _default: {
         "CodeBlock",
         "Composer",
         "DropdownMenu",
+        "EmptyState",
         "Mention",
         "ModelPicker",
         "PixelAvatar",
         "PromptSuggestions",
         "Prose",
+        "QuestionCard",
         "Reasoning",
         "ThreadPanel",
         "ThreadTabs"
@@ -59,7 +63,9 @@ declare const _default: {
         "ChatLauncher",
         "ChatThreads",
         "ChatTabs",
-        "ChatAgentPane"
+        "ChatAgentPane",
+        "ChatArtifactPane",
+        "ChatArtifactCard"
       ]
     }
   ]

package/chat/registry.json.js

@@ -1,5 +1,5 @@
 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 widgets = [{ "name": "ChatWidget", "slug": "ai-chat", "label": "AI chat", "category": "ai", "description": "The whole AI chat: the panel, the streaming replies, the history, the cards and questions 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, with an opt-in tool for asking the visitor questions, 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", "ArtifactCard", "ArtifactPanel", "AttachmentDropZone", "AttachmentGroup", "ChatHeader", "ChatMessage", "ChatThread", "CircularButton", "CodeBlock", "Composer", "DropdownMenu", "EmptyState", "Mention", "ModelPicker", "PixelAvatar", "PromptSuggestions", "Prose", "QuestionCard", "Reasoning", "ThreadPanel", "ThreadTabs"], "documented": ["ChatWidget", "ChatProvider", "ChatLauncher", "ChatThreads", "ChatTabs", "ChatAgentPane", "ChatArtifactPane", "ChatArtifactCard"] }];
 const registry = {
   $comment,
   widgets

package/chat/server.d.ts

@@ -16,6 +16,13 @@ export interface ChatTool {
     /** The trace point shown while the round runs, e.g. "Checked the Button prop contract". */
     tracePoint?: (input: Record<string, unknown>) => string;
 }
+/** The name of the built-in tool the model asks the visitor questions through. */
+export declare const ASK_USER_TOOL_NAME = "ask_user";
+/**
+ * What the model is told about asking. Lives in the tool's description, not
+ * the system prompt, so switching it on never disturbs a cached prefix.
+ */
+export declare const DEFAULT_ASK_USER_DESCRIPTION: 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
@@ -105,6 +112,8 @@ export interface ChatHandlerCopy {
     thinking: string;
     /** The status label while a tool round runs. */
     lookingUp: string;
+    /** The reply text when the model asks several questions without writing any. One question stands in for itself. */
+    questionsIntro: string;
     /** The error for a busy or overloaded model. */
     busy: string;
     /** The error for a rejected key. */
@@ -140,6 +149,16 @@ export interface ChatHandlerOptions {
     /** The wire value that serves once the budget steps down, and the only one past the lock. Defaults to `defaultModel`. */
     budgetModel?: string;
     tools?: ChatTool[];
+    /**
+     * Give the model the built-in `ask_user` tool, through which a reply can
+     * end in questions the widget draws as answers to pick. Pass an object to
+     * replace the guidance the model reads. Off by default. Calling it ends
+     * the exchange: no further model call is made, so it never counts against
+     * `maxModelCalls` beyond the pass that asked.
+     */
+    askUser?: boolean | {
+        description?: string;
+    };
     /** 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. */

package/chat/server.js

@@ -1,5 +1,15 @@
 import Anthropic from "@anthropic-ai/sdk";
+import { ASK_USER_INPUT_SCHEMA, sanitizeQuestionSet } from "./questions.js";
 import { SUGGESTION_MAX_CHARS, fitsChip } from "./suggestions.js";
+const ASK_USER_TOOL_NAME = "ask_user";
+const DEFAULT_ASK_USER_DESCRIPTION = [
+  "Offer the person answers to pick for a question your reply has just asked in words.",
+  "Use it only when the most useful next step depends on their answer and the likely answers can be listed: which framework, which of these options, which parts apply.",
+  "Do not use it for open questions, for confirming something they already said, or when you can simply answer. Most replies should not ask.",
+  "Write the question in your reply first, then call this once, as your last action. The conversation waits for their answer.",
+  "Prefer one question. Use several (at most 4) only when you need all the answers before you can continue. mode is single when one answer fits and multi when several can be true together.",
+  "Set other to true when the options may not cover every answer."
+].join(" ");
 const DEFAULT_CHAT_LIMITS = {
   maxTurns: 10,
   maxMessageChars: 4e3,
@@ -15,6 +25,7 @@ const DEFAULT_CHAT_COPY = {
   reading: "Reading",
   thinking: "Thinking",
   lookingUp: "Looking it up",
+  questionsIntro: "A few questions before I go on.",
   busy: "The model is busy right now. Give it a moment and ask again.",
   unauthorised: "This chat is not configured correctly at the moment.",
   failed: "Something went wrong reaching the model. Try that again in a moment."
@@ -121,7 +132,15 @@ function createChatHandler(options) {
   const copy = { ...DEFAULT_CHAT_COPY, ...options.copy };
   const sanitise = options.sanitiseContext ?? sanitisePath;
   const tools = options.tools ?? [];
-  const toolDefinitions = tools.map((tool) => tool.definition);
+  const askUserDefinition = options.askUser ? {
+    name: ASK_USER_TOOL_NAME,
+    description: (typeof options.askUser === "object" ? options.askUser.description : void 0) ?? DEFAULT_ASK_USER_DESCRIPTION,
+    input_schema: ASK_USER_INPUT_SCHEMA
+  } : null;
+  const toolDefinitions = [
+    ...tools.map((tool) => tool.definition),
+    ...askUserDefinition ? [askUserDefinition] : []
+  ];
   const toolByName = new Map(tools.map((tool) => [tool.definition.name, tool]));
   const maxModelCalls = options.maxModelCalls ?? 3;
   const maxTokens = options.maxTokens ?? 3e3;
@@ -273,7 +292,30 @@ function createChatHandler(options) {
               (block) => block.type === "tool_use"
             );
             const results = [];
+            const ask = askUserDefinition ? toolUses.find((block) => block.name === ASK_USER_TOOL_NAME) : void 0;
+            const set = ask ? sanitizeQuestionSet(ask.input, `${exchangeId}-questions`) : null;
+            if (set) {
+              if (!streamedText) {
+                const lead = set.questions.length === 1 ? set.questions[0].prompt : copy.questionsIntro;
+                reasoning.close();
+                streamedText = true;
+                firstTextMs = Date.now() - startedAt;
+                answerText += lead;
+                send({ type: "delta", text: lead });
+              }
+              send({ type: "question", set });
+              break;
+            }
             for (const block of toolUses) {
+              if (block.name === ASK_USER_TOOL_NAME) {
+                results.push({
+                  type: "tool_result",
+                  tool_use_id: block.id,
+                  is_error: true,
+                  content: `Those questions could not be shown. Each needs a short prompt and 2 to 5 distinct options of at most ${SUGGESTION_MAX_CHARS} characters, and a set holds at most 4. Fix them, or ask in plain text.`
+                });
+                continue;
+              }
               const args = typeof block.input === "object" && block.input !== null ? block.input : {};
               send({
                 type: "status",
@@ -477,6 +519,8 @@ function createFeedbackHandler(options = {}) {
   };
 }
 export {
+  ASK_USER_TOOL_NAME,
+  DEFAULT_ASK_USER_DESCRIPTION,
   DEFAULT_CHAT_COPY,
   DEFAULT_CHAT_LIMITS,
   createChatHandler,