@slices.sh/ai-chat 0.1.0

package/dist/fixture/fixture-approval.d.ts

@@ -0,0 +1,4 @@
+import { type UIMessageChunk } from "ai";
+import type { AiChatMessage } from "../services/types";
+export declare function approvalHistory(): AiChatMessage[];
+export declare function approvalTurn(messages: AiChatMessage[]): UIMessageChunk[];

package/dist/fixture/fixture-approval.js

@@ -0,0 +1,59 @@
+import { isToolUIPart } from "ai";
+function approvalHistory() {
+  return [
+    { id: "approval-user", role: "user", parts: [{ type: "text", text: "Count the words in my draft." }] },
+    {
+      id: "approval-answer",
+      role: "assistant",
+      parts: [
+        {
+          type: "tool-count_words",
+          toolCallId: "approval-call",
+          state: "approval-requested",
+          input: { text: "A short draft" },
+          approval: { id: "approval-demo", requestReason: "This tool is configured to ask before it runs." }
+        }
+      ]
+    }
+  ];
+}
+function approvalTurn(messages) {
+  const last = messages.at(-1);
+  const decided = last?.parts.find((part) => isToolUIPart(part) && part.state === "approval-responded");
+  if (decided && isToolUIPart(decided) && decided.state === "approval-responded") {
+    const approved = decided.approval.approved;
+    return [
+      { type: "start", messageId: last.id },
+      approved ? { type: "tool-output-available", toolCallId: decided.toolCallId, output: { words: 3 } } : { type: "tool-output-denied", toolCallId: decided.toolCallId },
+      { type: "text-start", id: "decision" },
+      {
+        type: "text-delta",
+        id: "decision",
+        delta: approved ? "The tool was allowed and counted 3 words." : "The tool was denied and did not run."
+      },
+      { type: "text-end", id: "decision" },
+      { type: "finish" }
+    ];
+  }
+  const id = last?.id ?? "empty";
+  return [
+    { type: "start", messageId: "answer-" + id },
+    {
+      type: "tool-input-available",
+      toolCallId: "call-" + id,
+      toolName: "count_words",
+      input: { text: "A short draft" }
+    },
+    {
+      type: "tool-approval-request",
+      approvalId: "approval-" + id,
+      toolCallId: "call-" + id,
+      reason: "This tool is configured to ask before it runs."
+    },
+    { type: "finish", finishReason: "tool-calls" }
+  ];
+}
+export {
+  approvalHistory,
+  approvalTurn
+};

package/dist/fixture/fixture-artifacts.d.ts

@@ -0,0 +1,2 @@
+import type { AiChatMessage } from "../services/types";
+export declare function artifactHistory(): AiChatMessage[];

package/dist/fixture/fixture-artifacts.js

@@ -0,0 +1,48 @@
+function artifactHistory() {
+  return [
+    {
+      id: "artifact-user",
+      role: "user",
+      parts: [{ type: "text", text: "Build a counter, then increase its initial value." }]
+    },
+    {
+      id: "artifact-first",
+      role: "assistant",
+      parts: [
+        {
+          type: "tool-createArtifact",
+          toolCallId: "artifact-v1",
+          state: "output-available",
+          input: {
+            artifactId: "counter",
+            title: "Counter",
+            code: "import React from 'react'\nexport default function App() { return <button>1</button> }",
+            summary: "First version"
+          },
+          output: { artifactId: "counter", recorded: true }
+        }
+      ]
+    },
+    {
+      id: "artifact-second",
+      role: "assistant",
+      parts: [
+        {
+          type: "tool-updateArtifact",
+          toolCallId: "artifact-v2",
+          state: "output-available",
+          input: {
+            artifactId: "counter",
+            title: "Counter",
+            code: "import React from 'react'\nexport default function App() { return <button>2</button> }",
+            summary: "Second version"
+          },
+          output: { artifactId: "counter", recorded: true }
+        }
+      ]
+    }
+  ];
+}
+export {
+  artifactHistory
+};

package/dist/fixture/fixture-question.d.ts

@@ -0,0 +1,5 @@
+import { type UIMessageChunk } from "ai";
+import { type AiChatMessage, type Questionnaire } from "../services/types";
+export declare const QUESTIONS: Questionnaire;
+export declare function questionHistory(): AiChatMessage[];
+export declare function questionTurn(messages: AiChatMessage[]): UIMessageChunk[];

package/dist/fixture/fixture-question.js

@@ -0,0 +1,93 @@
+import { getToolName, isToolUIPart } from "ai";
+import { isSkippedQuestion } from "../services/types.js";
+const QUESTIONS = {
+  title: "Plan your draft",
+  questions: [
+    {
+      name: "tone",
+      title: "Which tone?",
+      required: true,
+      choices: [
+        { value: "brief", label: "Brief" },
+        { value: "detailed", label: "Detailed" }
+      ]
+    },
+    {
+      name: "topics",
+      title: "Which topics?",
+      multiple: true,
+      choices: [
+        { value: "design", label: "Design" },
+        { value: "engineering", label: "Engineering" }
+      ],
+      other: "Another topic"
+    },
+    {
+      name: "audience",
+      title: "Who is it for?",
+      description: "The closest fit is enough.",
+      choices: [
+        { value: "team", label: "My team", description: "People who know the context" },
+        { value: "public", label: "The public", description: "Readers who start from nothing" }
+      ],
+      other: "Someone else"
+    }
+  ]
+};
+function questionHistory() {
+  return [
+    { id: "question-user", role: "user", parts: [{ type: "text", text: "Help me prepare a draft." }] },
+    {
+      id: "question-answer",
+      role: "assistant",
+      parts: [
+        {
+          type: "tool-askQuestions",
+          toolCallId: "question-call",
+          state: "input-available",
+          input: QUESTIONS
+        }
+      ]
+    }
+  ];
+}
+function questionTurn(messages) {
+  const last = messages.at(-1);
+  const answered = last?.parts.find(
+    (part) => isToolUIPart(part) && getToolName(part) === "askQuestions" && part.state === "output-available"
+  );
+  if (messages.some((message) => message.parts.some(isSkippedQuestion)))
+    return [
+      { type: "start", messageId: last?.role === "assistant" ? last.id : "skipped-" + (last?.id ?? "empty") },
+      { type: "start-step" },
+      { type: "text-start", id: "answer" },
+      { type: "text-delta", id: "answer", delta: "No problem. I will carry on without your answers." },
+      { type: "text-end", id: "answer" },
+      { type: "finish" }
+    ];
+  if (answered)
+    return [
+      { type: "start", messageId: last.id },
+      { type: "start-step" },
+      { type: "text-start", id: "answer" },
+      { type: "text-delta", id: "answer", delta: "Thanks. I will use your answers for the draft." },
+      { type: "text-end", id: "answer" },
+      { type: "finish" }
+    ];
+  const id = last?.id ?? "empty";
+  return [
+    { type: "start", messageId: "answer-" + id },
+    {
+      type: "tool-input-available",
+      toolCallId: "question-" + id,
+      toolName: "askQuestions",
+      input: QUESTIONS
+    },
+    { type: "finish", finishReason: "tool-calls" }
+  ];
+}
+export {
+  QUESTIONS,
+  questionHistory,
+  questionTurn
+};

package/dist/fixture/fixture-script.d.ts

@@ -0,0 +1,35 @@
+import type { UIMessageChunk } from "ai";
+import { type MissingConfigurationAnswer } from "@slices.sh/core/configuration";
+import { ChatError, type AiChatMessage } from "../services/types";
+/**
+ * What a fixture chat does, per scenario.
+ *
+ * A scenario is a state the screen can be in, not a story: `failed` is what the error banner
+ * looks like, `rate-limited` is the one refusal with a different shape of answer, `slow` is
+ * the one where stopping mid-answer is worth trying, `rich` is a turn with everything on it —
+ * markdown, a reasoning trace, a tool call, citations and a token count — and `interrupted`
+ * is what a reply that was stopped looks like after the fact. `missing-configuration` is a
+ * server that has no key for its model, which answers `config/missing` rather than a refusal
+ * of its own.
+ */
+export declare const CHAT_SCENARIOS: readonly ["ready", "approval", "questions", "empty", "rich", "artifacts", "slow", "interrupted", "failed", "rate-limited", "quota-exceeded", "unknown-chat", "missing-configuration"];
+export type ChatScenario = (typeof CHAT_SCENARIOS)[number];
+export type Script = {
+    /** What the transcript already holds when the screen mounts. */
+    history: AiChatMessage[];
+    /** Milliseconds between words. */
+    pace: number;
+    refuse: ChatError | MissingConfigurationAnswer | null;
+    /** Whether the answer arrives with a trace, a tool call, citations and a count. */
+    rich: boolean;
+};
+export declare function scriptFor(scenario: ChatScenario): Script;
+/**
+ * The answer a question gets, as the chunks a route streams for it.
+ *
+ * The same vocabulary a model's turn arrives in, in the same order — a `start`, a trace
+ * opened and closed, a tool call's input and then its output under one id, the prose, the
+ * citations, and a `finish` carrying what it cost — so the chat state the SDK builds from it
+ * is the state it builds from a provider.
+ */
+export declare function turnOf(messages: AiChatMessage[], rich: boolean): UIMessageChunk[];

package/dist/fixture/fixture-script.js

@@ -0,0 +1,280 @@
+import { artifactHistory } from "./fixture-artifacts.js";
+import { questionHistory } from "./fixture-question.js";
+import { approvalHistory } from "./fixture-approval.js";
+import { MISSING_CONFIGURATION } from "@slices.sh/core/configuration";
+import { ChatError } from "../services/types.js";
+const CHAT_SCENARIOS = [
+  "ready",
+  "approval",
+  "questions",
+  "empty",
+  "rich",
+  "artifacts",
+  "slow",
+  "interrupted",
+  "failed",
+  "rate-limited",
+  "quota-exceeded",
+  "unknown-chat",
+  "missing-configuration"
+];
+const CONVERSATION = [
+  said("you-1", "user", "What is in this transcript?"),
+  said(
+    "answer-1",
+    "assistant",
+    "Two messages, so far: yours and this one. Everything you see is the AI SDK's own chat and the real parts \u2014 only the backend is a fixture, so the stream, the stop button and the error states behave the way they will against a model."
+  )
+];
+const RICH = [
+  {
+    id: "you-1",
+    role: "user",
+    parts: [
+      {
+        type: "file",
+        filename: "brief.pdf",
+        mediaType: "application/pdf",
+        url: "https://example.com/brief.pdf"
+      },
+      { type: "text", text: "Show me what a turn can carry." }
+    ]
+  },
+  {
+    id: "answer-1",
+    role: "assistant",
+    parts: [
+      { type: "step-start" },
+      { type: "reasoning", text: "Read the contract, then answer with one of each part.", state: "done" },
+      {
+        type: "tool-search_docs",
+        toolCallId: "search",
+        state: "output-available",
+        input: { query: "error slugs" },
+        output: { found: 3 }
+      },
+      { type: "step-start" },
+      {
+        type: "text",
+        state: "done",
+        text: [
+          "A turn carries **more than prose**. This message has all of it:",
+          "",
+          "| Part | Where it came from |",
+          "|---|---|",
+          "| reasoning | `reasoning-delta`, collapsed once the answer starts |",
+          "| tool | `tool-input-available` then `tool-output-available`, one card either way |",
+          "| source | `source-url`, collected into the footer below |",
+          "",
+          "```ts",
+          "const { messages, status, stop } = useChat({ chat })",
+          "```",
+          "",
+          "- markdown renders while it arrives",
+          "",
+          "An optional formula: $$E = mc^2$$.",
+          "",
+          "```mermaid",
+          "flowchart LR",
+          "  Draft --> Review --> Publish",
+          "```",
+          "- a fence the next token would have closed still renders as code"
+        ].join("\n")
+      },
+      {
+        type: "source-url",
+        sourceId: "s1",
+        url: "https://ai-sdk.dev/docs/ai-sdk-ui/stream-protocol",
+        title: "Stream protocol"
+      },
+      {
+        type: "source-url",
+        sourceId: "s2",
+        url: "https://ai-sdk.dev/docs/ai-sdk-ui/chatbot-tool-usage",
+        title: "Tool usage"
+      },
+      {
+        type: "file",
+        filename: "fixture.png",
+        mediaType: "image/png",
+        url: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+jRzEAAAAASUVORK5CYII="
+      },
+      {
+        type: "file",
+        filename: "guide.pdf",
+        mediaType: "application/pdf",
+        url: "https://example.com/guide.pdf"
+      }
+    ],
+    metadata: {
+      usage: counted(412, 190),
+      contextTokens: 412,
+      contextWindow: 8192,
+      model: "fixture-model",
+      followUps: ["Show a concrete example", "Summarize the key points"],
+      timing: { firstTokenMs: 250, durationMs: 1500 }
+    }
+  }
+];
+const INTERRUPTED = [
+  said("you-1", "user", "Write me the whole contract."),
+  {
+    id: "answer-1",
+    role: "assistant",
+    parts: [
+      {
+        type: "text",
+        text: "The contract is one operation \u2014 run a turn \u2014 over a chat this app has config",
+        state: "streaming"
+      }
+    ]
+  }
+];
+function scriptFor(scenario) {
+  const plain = { refuse: null, rich: false };
+  switch (scenario) {
+    case "artifacts":
+      return { history: artifactHistory(), pace: 5, ...plain };
+    case "questions":
+      return { history: questionHistory(), pace: 5, ...plain };
+    case "approval":
+      return { history: approvalHistory(), pace: 5, ...plain };
+    case "empty":
+      return { history: [], pace: 18, ...plain };
+    case "rich":
+      return { history: RICH, pace: 24, refuse: null, rich: true };
+    case "slow":
+      return { history: CONVERSATION, pace: 90, ...plain };
+    case "interrupted":
+      return { history: INTERRUPTED, pace: 18, ...plain };
+    case "failed":
+      return {
+        history: CONVERSATION,
+        pace: 18,
+        rich: false,
+        refuse: new ChatError("ai-chat/model-unavailable", "The model is not answering right now.")
+      };
+    case "rate-limited":
+      return {
+        history: CONVERSATION,
+        pace: 18,
+        rich: false,
+        refuse: new ChatError("ai-chat/rate-limited", "That is a lot of questions. Try again in a minute.")
+      };
+    case "quota-exceeded":
+      return {
+        history: CONVERSATION,
+        pace: 18,
+        rich: false,
+        refuse: new ChatError(
+          "ai-chat/quota-exceeded",
+          "This workspace has used its messages for the month."
+        )
+      };
+    case "unknown-chat":
+      return {
+        history: [],
+        pace: 18,
+        rich: false,
+        refuse: new ChatError("ai-chat/unknown-chat", "No chat is configured under that name.")
+      };
+    case "missing-configuration":
+      return {
+        history: CONVERSATION,
+        pace: 18,
+        rich: false,
+        refuse: {
+          error: MISSING_CONFIGURATION,
+          scope: "ai-chat",
+          message: "This component requires extra server configuration to work properly. If you're the developer, see the logs. If you're a user, please report it!"
+        }
+      };
+    default:
+      return { history: CONVERSATION, pace: 18, ...plain };
+  }
+}
+function turnOf(messages, rich) {
+  const asked = askedIn(messages);
+  const chunks = [{ type: "start", messageId: `answer-${messages.length}` }];
+  if (rich) {
+    chunks.push(
+      { type: "reasoning-start", id: "plan" },
+      ...pieces("Count the words, then answer in markdown.").map((delta) => ({
+        type: "reasoning-delta",
+        id: "plan",
+        delta
+      })),
+      { type: "reasoning-end", id: "plan" },
+      { type: "tool-input-available", toolCallId: "count", toolName: "count_words", input: { text: asked } },
+      { type: "tool-output-available", toolCallId: "count", output: { words: wordsIn(asked) } }
+    );
+  }
+  chunks.push(
+    { type: "text-start", id: "answer" },
+    ...pieces(answerTo(asked)).map((delta) => ({ type: "text-delta", id: "answer", delta })),
+    { type: "text-end", id: "answer" }
+  );
+  if (rich)
+    chunks.push({
+      type: "source-url",
+      sourceId: "protocol",
+      url: "https://ai-sdk.dev/docs/ai-sdk-ui/stream-protocol",
+      title: "Stream protocol"
+    });
+  chunks.push({
+    type: "finish",
+    finishReason: "stop",
+    ...rich ? {
+      messageMetadata: {
+        usage: counted(412, 190),
+        contextTokens: 412,
+        contextWindow: 8192,
+        model: "fixture-model",
+        followUps: ["Show a concrete example", "Summarize the key points"],
+        timing: { firstTokenMs: 250, durationMs: 1500 }
+      }
+    } : {}
+  });
+  return chunks;
+}
+function answerTo(asked) {
+  const words = wordsIn(asked);
+  return [
+    `You asked ${words} word${words === 1 ? "" : "s"}: **"${asked.trim()}"**`,
+    "",
+    "This preview has no model behind it. What it does have is the same chat, transcript,",
+    "composer, status and error parts the installed component has \u2014 so stopping this",
+    "mid-sentence, or typing again before it finishes, does here what it will do in your app."
+  ].join("\n");
+}
+function askedIn(messages) {
+  const asked = messages.findLast((message) => message.role === "user");
+  return (asked?.parts ?? []).map((part) => part.type === "text" ? part.text : "").join("");
+}
+function wordsIn(text) {
+  return text.trim().split(/\s+/).filter(Boolean).length;
+}
+function pieces(text) {
+  return text.split(/(?<=\s)/);
+}
+function counted(input, output) {
+  return {
+    inputTokens: input,
+    inputTokenDetails: { noCacheTokens: input, cacheReadTokens: void 0, cacheWriteTokens: void 0 },
+    outputTokens: output,
+    outputTokenDetails: { textTokens: output, reasoningTokens: void 0 },
+    totalTokens: input + output
+  };
+}
+function said(id, role, text) {
+  return {
+    id,
+    role,
+    parts: [{ type: "text", text, ...role === "assistant" ? { state: "done" } : {} }]
+  };
+}
+export {
+  CHAT_SCENARIOS,
+  scriptFor,
+  turnOf
+};

package/dist/fixture/fixture-selection.d.ts

@@ -0,0 +1,5 @@
+import type { UIMessageChunk } from "ai";
+import type { ChatChoices, ChatSelection } from "../services/types";
+export declare const fixtureChoices: ChatChoices;
+/** Scripted model variants and actual optional tool chunks, never pretend live inference. */
+export declare function chosenChunks(chunks: UIMessageChunk[], selection?: ChatSelection): UIMessageChunk[];

package/dist/fixture/fixture-selection.js

@@ -0,0 +1,20 @@
+const fixtureChoices = {
+  models: [
+    { id: "", label: "Standard fixture", contextWindow: 8192 },
+    { id: "detailed", label: "Detailed fixture", contextWindow: 8192 }
+  ],
+  tools: [{ id: "count_words", label: "Word count", defaultEnabled: true }]
+};
+function chosenChunks(chunks, selection) {
+  return chunks.flatMap((chunk) => {
+    if (selection?.tools && !selection.tools.includes("count_words") && "toolCallId" in chunk && chunk.toolCallId === "count") return [];
+    if (selection?.model !== "detailed") return [chunk];
+    if (chunk.type === "text-start") return [chunk, { type: "text-delta", id: chunk.id, delta: "Detailed fixture response: " }];
+    if (chunk.type === "finish") return [{ ...chunk, messageMetadata: { ...chunk.messageMetadata, model: "fixture-detailed" } }];
+    return [chunk];
+  });
+}
+export {
+  chosenChunks,
+  fixtureChoices
+};

package/dist/fixture/fixture.d.ts

@@ -0,0 +1,20 @@
+import type { AiChatClient } from "../services/types";
+import { type ChatTransport } from "ai";
+import { CHAT_SCENARIOS, type ChatScenario } from "./fixture-script";
+import { type AiChatMessage } from "../services/types";
+export { CHAT_SCENARIOS };
+export type { ChatScenario };
+/**
+ * A chat backend that answers in the browser, so a preview or a test runs the AI SDK's own
+ * `Chat` and the real parts with no route and no key.
+ *
+ * It is a `ChatTransport` — the SDK's own seam for "something else answers" — rather than a
+ * mock of anything above it: the chat state, the stop, the part states and the error branch
+ * are the SDK's, and the chunks are the ones a route streams. Hand both to a chat:
+ * `new Chat({ transport, messages })`. → docs/concepts/fixtures.md
+ */
+export declare function createAiChatFixture(scenario?: ChatScenario): {
+    transport: ChatTransport<AiChatMessage>;
+    messages: AiChatMessage[];
+    client: AiChatClient;
+};

package/dist/fixture/fixture.js

@@ -0,0 +1,75 @@
+import { fixtureChoices, chosenChunks } from "./fixture-selection.js";
+import { questionTurn } from "./fixture-question.js";
+import { approvalTurn } from "./fixture-approval.js";
+import { APICallError } from "ai";
+import { forgetMissingConfiguration } from "@slices.sh/core/configuration";
+import { CHAT_SCENARIOS, scriptFor, turnOf } from "./fixture-script.js";
+import { refusalText, statusForChatError } from "../services/types.js";
+function createAiChatFixture(scenario = "ready") {
+  const script = scriptFor(scenario);
+  forgetMissingConfiguration();
+  const transport = {
+    async sendMessages({ messages, abortSignal, body }) {
+      await wait(script.pace * 4, abortSignal);
+      if (script.refuse) throw refused(script.refuse);
+      return paced(
+        scenario === "questions" ? questionTurn(messages) : scenario === "approval" ? approvalTurn(messages) : chosenChunks(turnOf(messages, script.rich), body?.selection),
+        script.pace,
+        abortSignal
+      );
+    },
+    // Nothing outlives a page here, so there is never a stream to go back to.
+    async reconnectToStream() {
+      return null;
+    }
+  };
+  const client = {
+    transportFor: () => transport,
+    choicesFor: async () => scenario === "rich" ? fixtureChoices : null
+  };
+  return { transport, messages: script.history, client };
+}
+function refused(error) {
+  const typed = error instanceof Error;
+  const body = typed ? refusalText(error) : JSON.stringify(error);
+  return new APICallError({
+    message: body,
+    url: "fixture",
+    requestBodyValues: void 0,
+    statusCode: typed ? statusForChatError[error.slug] : 503,
+    responseBody: body
+  });
+}
+function paced(chunks, pace, signal) {
+  let next = 0;
+  return new ReadableStream({
+    async pull(controller) {
+      const chunk = chunks[next++];
+      if (!chunk) return controller.close();
+      try {
+        await wait(chunk.type.endsWith("-delta") ? pace : pace * 3, signal);
+      } catch {
+        return;
+      }
+      controller.enqueue(chunk);
+    }
+  });
+}
+function wait(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(signal.reason);
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    function onAbort() {
+      clearTimeout(timer);
+      reject(signal?.reason);
+    }
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+export {
+  CHAT_SCENARIOS,
+  createAiChatFixture
+};

package/dist/fixture/provider.d.ts

@@ -0,0 +1,15 @@
+import type { AiChatClient } from "../services/types";
+import { type ChatScenario } from "./fixture";
+export type FixtureOptions = {
+    /**
+     * ready, approval, questions, empty, rich, artifacts, slow, interrupted, failed, rate-limited,
+     * quota-exceeded, unknown-chat or missing-configuration. Default "ready".
+     */
+    scenario?: ChatScenario;
+};
+/**
+ * A ChatTransport that emits scripted UI message chunks in the browser, for previews and tests.
+ * The parts above it are the shipped ones. No key, no route, no server half:
+ * `aiChat({ provider: fixture(), model: "fixture" })`.
+ */
+export declare function fixture(options?: FixtureOptions): import("@slices.sh/core").Provider<AiChatClient>;