@assistant-ui/core 0.3.3 → 0.3.4

package/dist/utils/image-media-type.js

@@ -0,0 +1,141 @@
+//#region src/utils/image-media-type.ts
+/**
+* Leading-byte signatures for the image formats a browser or attachment
+* adapter realistically produces. `null` matches any byte, which WebP needs
+* because its four size bytes sit between the two markers, and AVIF and HEIC
+* need because their leading `ftyp` box size varies by encoder.
+*
+* These are file format constants rather than an evolving API, so the table
+* mirrors the one the AI SDK applies on the far side of several adapters
+* without taking a dependency to reach it.
+*/
+const IMAGE_SIGNATURES = [
+	{
+		mediaType: "image/gif",
+		prefix: [
+			71,
+			73,
+			70
+		]
+	},
+	{
+		mediaType: "image/png",
+		prefix: [
+			137,
+			80,
+			78,
+			71
+		]
+	},
+	{
+		mediaType: "image/jpeg",
+		prefix: [255, 216]
+	},
+	{
+		mediaType: "image/webp",
+		prefix: [
+			82,
+			73,
+			70,
+			70,
+			null,
+			null,
+			null,
+			null,
+			87,
+			69,
+			66,
+			80
+		]
+	},
+	{
+		mediaType: "image/bmp",
+		prefix: [66, 77]
+	},
+	{
+		mediaType: "image/tiff",
+		prefix: [
+			73,
+			73,
+			42,
+			0
+		]
+	},
+	{
+		mediaType: "image/tiff",
+		prefix: [
+			77,
+			77,
+			0,
+			42
+		]
+	},
+	{
+		mediaType: "image/avif",
+		prefix: [
+			null,
+			null,
+			null,
+			null,
+			102,
+			116,
+			121,
+			112,
+			97,
+			118,
+			105,
+			102
+		]
+	},
+	{
+		mediaType: "image/heic",
+		prefix: [
+			null,
+			null,
+			null,
+			null,
+			102,
+			116,
+			121,
+			112,
+			104,
+			101,
+			105,
+			99
+		]
+	}
+];
+/** 16 base64 characters decode to the 12 bytes the longest signature needs. */
+const PREFIX_CHARS = 16;
+const decodePrefix = (base64) => {
+	const prefix = base64.slice(0, PREFIX_CHARS);
+	const aligned = prefix.slice(0, prefix.length - prefix.length % 4);
+	if (aligned.length === 0) return void 0;
+	const nodeBuffer = globalThis.Buffer;
+	if (nodeBuffer) return new Uint8Array(nodeBuffer.from(aligned, "base64"));
+	try {
+		const binary = atob(aligned);
+		const bytes = new Uint8Array(binary.length);
+		for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+		return bytes;
+	} catch {
+		return;
+	}
+};
+/**
+* The image media type a base64 payload's leading bytes identify, or
+* `undefined` when they match no known signature or the input is not base64.
+*
+* An `ImageMessagePart` carries no media type, so an adapter that must declare
+* one on the wire reads it from the bytes rather than assuming a format. Never
+* throws: the input is whatever a caller put on the part.
+*/
+function detectImageMediaType(base64) {
+	const bytes = decodePrefix(base64);
+	if (!bytes) return void 0;
+	return IMAGE_SIGNATURES.find(({ prefix }) => bytes.length >= prefix.length && prefix.every((byte, index) => byte === null || bytes[index] === byte))?.mediaType;
+}
+//#endregion
+export { detectImageMediaType };
+
+//# sourceMappingURL=image-media-type.js.map

package/dist/utils/image-media-type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-media-type.js","names":["IMAGE_SIGNATURES","mediaType","prefix","PREFIX_CHARS","decodePrefix","base64","Uint8Array","slice","aligned","length","undefined","nodeBuffer","globalThis","Buffer","from","data","encoding","binary","atob","bytes","i","charCodeAt","detectImageMediaType","find","every","byte","index"],"sources":["../../src/utils/image-media-type.ts"],"sourcesContent":["/**\n * Leading-byte signatures for the image formats a browser or attachment\n * adapter realistically produces. `null` matches any byte, which WebP needs\n * because its four size bytes sit between the two markers, and AVIF and HEIC\n * need because their leading `ftyp` box size varies by encoder.\n *\n * These are file format constants rather than an evolving API, so the table\n * mirrors the one the AI SDK applies on the far side of several adapters\n * without taking a dependency to reach it.\n */\nconst IMAGE_SIGNATURES: readonly {\n  readonly mediaType: string;\n  readonly prefix: readonly (number | null)[];\n}[] = [\n  { mediaType: \"image/gif\", prefix: [0x47, 0x49, 0x46] },\n  { mediaType: \"image/png\", prefix: [0x89, 0x50, 0x4e, 0x47] },\n  { mediaType: \"image/jpeg\", prefix: [0xff, 0xd8] },\n  {\n    mediaType: \"image/webp\",\n    prefix: [\n      0x52,\n      0x49,\n      0x46,\n      0x46,\n      null,\n      null,\n      null,\n      null,\n      0x57,\n      0x45,\n      0x42,\n      0x50,\n    ],\n  },\n  { mediaType: \"image/bmp\", prefix: [0x42, 0x4d] },\n  { mediaType: \"image/tiff\", prefix: [0x49, 0x49, 0x2a, 0x00] },\n  { mediaType: \"image/tiff\", prefix: [0x4d, 0x4d, 0x00, 0x2a] },\n  {\n    mediaType: \"image/avif\",\n    prefix: [\n      null,\n      null,\n      null,\n      null,\n      0x66,\n      0x74,\n      0x79,\n      0x70,\n      0x61,\n      0x76,\n      0x69,\n      0x66,\n    ],\n  },\n  {\n    mediaType: \"image/heic\",\n    prefix: [\n      null,\n      null,\n      null,\n      null,\n      0x66,\n      0x74,\n      0x79,\n      0x70,\n      0x68,\n      0x65,\n      0x69,\n      0x63,\n    ],\n  },\n];\n\n/** 16 base64 characters decode to the 12 bytes the longest signature needs. */\nconst PREFIX_CHARS = 16;\n\nconst decodePrefix = (base64: string): Uint8Array | undefined => {\n  const prefix = base64.slice(0, PREFIX_CHARS);\n  const aligned = prefix.slice(0, prefix.length - (prefix.length % 4));\n  if (aligned.length === 0) return undefined;\n\n  const nodeBuffer = (\n    globalThis as {\n      Buffer?: {\n        from(data: string, encoding: string): Uint8Array;\n      };\n    }\n  ).Buffer;\n  if (nodeBuffer) return new Uint8Array(nodeBuffer.from(aligned, \"base64\"));\n\n  try {\n    const binary = atob(aligned);\n    const bytes = new Uint8Array(binary.length);\n    for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);\n    return bytes;\n  } catch {\n    return undefined;\n  }\n};\n\n/**\n * The image media type a base64 payload's leading bytes identify, or\n * `undefined` when they match no known signature or the input is not base64.\n *\n * An `ImageMessagePart` carries no media type, so an adapter that must declare\n * one on the wire reads it from the bytes rather than assuming a format. Never\n * throws: the input is whatever a caller put on the part.\n */\nexport function detectImageMediaType(base64: string): string | undefined {\n  const bytes = decodePrefix(base64);\n  if (!bytes) return undefined;\n\n  return IMAGE_SIGNATURES.find(\n    ({ prefix }) =>\n      bytes.length >= prefix.length &&\n      prefix.every((byte, index) => byte === null || bytes[index] === byte),\n  )?.mediaType;\n}\n"],"mappings":";;;;;;;;;;;AAUA,MAAMA,mBAGA;CACJ;EAAEC,WAAW;EAAaC,QAAQ;GAAC;GAAM;GAAM;EAAI;CAAE;CACrD;EAAED,WAAW;EAAaC,QAAQ;GAAC;GAAM;GAAM;GAAM;EAAI;CAAE;CAC3D;EAAED,WAAW;EAAcC,QAAQ,CAAC,KAAM,GAAI;CAAE;CAChD;EACED,WAAW;EACXC,QAAQ;GACN;GACA;GACA;GACA;GACA;GACA;GACA;GACA;GACA;GACA;GACA;GACA;EAAI;CAER;CACA;EAAED,WAAW;EAAaC,QAAQ,CAAC,IAAM,EAAI;CAAE;CAC/C;EAAED,WAAW;EAAcC,QAAQ;GAAC;GAAM;GAAM;GAAM;EAAI;CAAE;CAC5D;EAAED,WAAW;EAAcC,QAAQ;GAAC;GAAM;GAAM;GAAM;EAAI;CAAE;CAC5D;EACED,WAAW;EACXC,QAAQ;GACN;GACA;GACA;GACA;GACA;GACA;GACA;GACA;GACA;GACA;GACA;GACA;EAAI;CAER;CACA;EACED,WAAW;EACXC,QAAQ;GACN;GACA;GACA;GACA;GACA;GACA;GACA;GACA;GACA;GACA;GACA;GACA;EAAI;CAER;AAAC;;AAIH,MAAMC,eAAe;AAErB,MAAMC,gBAAgBC,WAA2C;CAC/D,MAAMH,SAASG,OAAOE,MAAM,GAAGJ,YAAY;CAC3C,MAAMK,UAAUN,OAAOK,MAAM,GAAGL,OAAOO,SAAUP,OAAOO,SAAS,CAAE;CACnE,IAAID,QAAQC,WAAW,GAAG,OAAOC,KAAAA;CAEjC,MAAMC,aACJC,WAKAC;CACF,IAAIF,YAAY,OAAO,IAAIL,WAAWK,WAAWG,KAAKN,SAAS,QAAQ,CAAC;CAExE,IAAI;EACF,MAAMS,SAASC,KAAKV,OAAO;EAC3B,MAAMW,QAAQ,IAAIb,WAAWW,OAAOR,MAAM;EAC1C,KAAK,IAAIW,IAAI,GAAGA,IAAIH,OAAOR,QAAQW,KAAKD,MAAMC,KAAKH,OAAOI,WAAWD,CAAC;EACtE,OAAOD;CACT,QAAQ;EACN;CACF;AACF;;;;;;;;;AAUA,SAAgBG,qBAAqBjB,QAAoC;CACvE,MAAMc,QAAQf,aAAaC,MAAM;CACjC,IAAI,CAACc,OAAO,OAAOT,KAAAA;CAEnB,OAAOV,iBAAiBuB,MACrB,EAAErB,aACDiB,MAAMV,UAAUP,OAAOO,UACvBP,OAAOsB,OAAOC,MAAMC,UAAUD,SAAS,QAAQN,MAAMO,WAAWD,IAAI,CACxE,CAAC,EAAExB;AACL"}

package/dist/utils/wire-media.d.ts

@@ -0,0 +1,35 @@
+//#region src/utils/wire-media.d.ts
+/**
+ * The media type to declare for an `ImageMessagePart`, which carries none of
+ * its own: an attachment's content type, then the payload's data URL
+ * declaration, then its leading bytes, then `image/png`.
+ *
+ * The floor cannot be a wildcard. `image/*` is rejected outright by the AI SDK
+ * for a url source and whenever inline bytes fail to sniff, so it fails exactly
+ * where a fallback is needed.
+ */
+declare function resolveImageMediaType(image: string, contentType?: string | undefined): string;
+/**
+ * The media type to declare for a `FileMessagePart`: its own `mimeType`, then
+ * the payload's data URL declaration, then `application/octet-stream`.
+ *
+ * `mimeType` is a plain string, and an adapter reading `file.type` on a file
+ * the OS cannot type yields `""`, so the declared value is not always present.
+ */
+declare function resolveFileMediaType(data: string, mimeType?: string | undefined): string;
+/**
+ * A payload placed into a wire field that is contractually a url.
+ *
+ * Two hazards drive this. A consumer may hand the value to an unguarded
+ * `new URL()`, so a payload that is not a url has to be wrapped; and a data
+ * URL's own media type wins over a separately declared one downstream, so a
+ * base64 envelope that disagrees with `mediaType` is rebuilt around the same
+ * bytes. Everything else passes through byte for byte: an envelope that agrees,
+ * a url of any other scheme, and a percent-encoded data URL, whose declaration
+ * cannot be corrected without transcoding the payload and is authoritative for
+ * the bytes it carries anyway.
+ */
+declare function toMediaWireUrl(payload: string, mediaType: string): string;
+//#endregion
+export { resolveFileMediaType, resolveImageMediaType, toMediaWireUrl };
+//# sourceMappingURL=wire-media.d.ts.map

package/dist/utils/wire-media.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire-media.d.ts","names":[],"sources":["../../src/utils/wire-media.ts"],"mappings":";;;;;;;;;;iBAYgB,sBACd,eACA;;;;;;;;iBA2Bc,qBACd,cACA;;;;;;;;;;;;;iBAiBc,eAAe,iBAAiB"}

package/dist/utils/wire-media.js

@@ -0,0 +1,55 @@
+import { dataUrlMediaType, isParsableUrl, parseDataUrl } from "./data-url.js";
+import { detectImageMediaType } from "./image-media-type.js";
+//#region src/utils/wire-media.ts
+/**
+* The media type to declare for an `ImageMessagePart`, which carries none of
+* its own: an attachment's content type, then the payload's data URL
+* declaration, then its leading bytes, then `image/png`.
+*
+* The floor cannot be a wildcard. `image/*` is rejected outright by the AI SDK
+* for a url source and whenever inline bytes fail to sniff, so it fails exactly
+* where a fallback is needed.
+*/
+function resolveImageMediaType(image, contentType) {
+	if (contentType?.startsWith("image/")) return contentType;
+	const declared = dataUrlMediaType(image);
+	if (declared?.startsWith("image/")) return declared;
+	const payload = parseDataUrl(image)?.data ?? (isParsableUrl(image) ? void 0 : image);
+	if (payload !== void 0) {
+		const sniffed = detectImageMediaType(payload);
+		if (sniffed) return sniffed;
+	}
+	return "image/png";
+}
+/**
+* The media type to declare for a `FileMessagePart`: its own `mimeType`, then
+* the payload's data URL declaration, then `application/octet-stream`.
+*
+* `mimeType` is a plain string, and an adapter reading `file.type` on a file
+* the OS cannot type yields `""`, so the declared value is not always present.
+*/
+function resolveFileMediaType(data, mimeType) {
+	return mimeType || dataUrlMediaType(data) || "application/octet-stream";
+}
+/**
+* A payload placed into a wire field that is contractually a url.
+*
+* Two hazards drive this. A consumer may hand the value to an unguarded
+* `new URL()`, so a payload that is not a url has to be wrapped; and a data
+* URL's own media type wins over a separately declared one downstream, so a
+* base64 envelope that disagrees with `mediaType` is rebuilt around the same
+* bytes. Everything else passes through byte for byte: an envelope that agrees,
+* a url of any other scheme, and a percent-encoded data URL, whose declaration
+* cannot be corrected without transcoding the payload and is authoritative for
+* the bytes it carries anyway.
+*/
+function toMediaWireUrl(payload, mediaType) {
+	const parsed = parseDataUrl(payload);
+	if (parsed) return parsed.mimeType === mediaType ? payload : `data:${mediaType};base64,${parsed.data}`;
+	if (isParsableUrl(payload)) return payload;
+	return `data:${mediaType};base64,${payload}`;
+}
+//#endregion
+export { resolveFileMediaType, resolveImageMediaType, toMediaWireUrl };
+
+//# sourceMappingURL=wire-media.js.map

package/dist/utils/wire-media.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire-media.js","names":["dataUrlMediaType","isParsableUrl","parseDataUrl","detectImageMediaType","resolveImageMediaType","image","contentType","startsWith","declared","parsed","payload","data","undefined","sniffed","resolveFileMediaType","mimeType","toMediaWireUrl","mediaType"],"sources":["../../src/utils/wire-media.ts"],"sourcesContent":["import { dataUrlMediaType, isParsableUrl, parseDataUrl } from \"./data-url\";\nimport { detectImageMediaType } from \"./image-media-type\";\n\n/**\n * The media type to declare for an `ImageMessagePart`, which carries none of\n * its own: an attachment's content type, then the payload's data URL\n * declaration, then its leading bytes, then `image/png`.\n *\n * The floor cannot be a wildcard. `image/*` is rejected outright by the AI SDK\n * for a url source and whenever inline bytes fail to sniff, so it fails exactly\n * where a fallback is needed.\n */\nexport function resolveImageMediaType(\n  image: string,\n  contentType?: string | undefined,\n): string {\n  if (contentType?.startsWith(\"image/\")) return contentType;\n\n  const declared = dataUrlMediaType(image);\n  if (declared?.startsWith(\"image/\")) return declared;\n\n  // Read through a data URL envelope too, so a generic one such as\n  // `application/octet-stream` does not mask the format. A url of any other\n  // scheme has no local bytes to read.\n  const parsed = parseDataUrl(image);\n  const payload = parsed?.data ?? (isParsableUrl(image) ? undefined : image);\n  if (payload !== undefined) {\n    const sniffed = detectImageMediaType(payload);\n    if (sniffed) return sniffed;\n  }\n\n  return \"image/png\";\n}\n\n/**\n * The media type to declare for a `FileMessagePart`: its own `mimeType`, then\n * the payload's data URL declaration, then `application/octet-stream`.\n *\n * `mimeType` is a plain string, and an adapter reading `file.type` on a file\n * the OS cannot type yields `\"\"`, so the declared value is not always present.\n */\nexport function resolveFileMediaType(\n  data: string,\n  mimeType?: string | undefined,\n): string {\n  return mimeType || dataUrlMediaType(data) || \"application/octet-stream\";\n}\n\n/**\n * A payload placed into a wire field that is contractually a url.\n *\n * Two hazards drive this. A consumer may hand the value to an unguarded\n * `new URL()`, so a payload that is not a url has to be wrapped; and a data\n * URL's own media type wins over a separately declared one downstream, so a\n * base64 envelope that disagrees with `mediaType` is rebuilt around the same\n * bytes. Everything else passes through byte for byte: an envelope that agrees,\n * a url of any other scheme, and a percent-encoded data URL, whose declaration\n * cannot be corrected without transcoding the payload and is authoritative for\n * the bytes it carries anyway.\n */\nexport function toMediaWireUrl(payload: string, mediaType: string): string {\n  const parsed = parseDataUrl(payload);\n  if (parsed) {\n    return parsed.mimeType === mediaType\n      ? payload\n      : `data:${mediaType};base64,${parsed.data}`;\n  }\n  if (isParsableUrl(payload)) return payload;\n  return `data:${mediaType};base64,${payload}`;\n}\n"],"mappings":";;;;;;;;;;;;AAYA,SAAgBI,sBACdC,OACAC,aACQ;CACR,IAAIA,aAAaC,WAAW,QAAQ,GAAG,OAAOD;CAE9C,MAAME,WAAWR,iBAAiBK,KAAK;CACvC,IAAIG,UAAUD,WAAW,QAAQ,GAAG,OAAOC;CAM3C,MAAME,UADSR,aAAaG,KACZI,CAAM,EAAEE,SAASV,cAAcI,KAAK,IAAIO,KAAAA,IAAYP;CACpE,IAAIK,YAAYE,KAAAA,GAAW;EACzB,MAAMC,UAAUV,qBAAqBO,OAAO;EAC5C,IAAIG,SAAS,OAAOA;CACtB;CAEA,OAAO;AACT;;;;;;;;AASA,SAAgBC,qBACdH,MACAI,UACQ;CACR,OAAOA,YAAYf,iBAAiBW,IAAI,KAAK;AAC/C;;;;;;;;;;;;;AAcA,SAAgBK,eAAeN,SAAiBO,WAA2B;CACzE,MAAMR,SAASP,aAAaQ,OAAO;CACnC,IAAID,QACF,OAAOA,OAAOM,aAAaE,YACvBP,UACA,QAAQO,UAAS,UAAWR,OAAOE;CAEzC,IAAIV,cAAcS,OAAO,GAAG,OAAOA;CACnC,OAAO,QAAQO,UAAS,UAAWP;AACrC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assistant-ui/core",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "Framework-agnostic core runtime for assistant-ui",
   "keywords": [
     "assistant",
@@ -59,7 +59,7 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "assistant-stream": "^0.3.31",
+    "assistant-stream": "^0.3.32",
     "nanoid": "^6.0.0"
   },
   "optionalDevDependencies": {
@@ -95,7 +95,7 @@
     "react-dom": "^19.2.8",
     "vitest": "^4.1.10",
     "zustand": "^5.0.14",
-    "@assistant-ui/store": "0.3.2",
+    "@assistant-ui/store": "0.3.3",
     "@assistant-ui/tap": "0.9.9",
     "@assistant-ui/vite": "0.0.11",
     "@assistant-ui/x-buildutils": "0.0.20",

package/src/internal.ts

@@ -57,7 +57,18 @@ export { isJSONValue, isRecord } from "./utils/json/is-json";
 
 // Data-URL decoder and http(s) matcher, reused by framework adapters so the
 // outbound part conversion lives in one place.
-export { httpUrlPattern, parseDataUrl } from "./utils/data-url";
+export {
+  dataUrlMediaType,
+  httpUrlPattern,
+  isParsableUrl,
+  parseDataUrl,
+} from "./utils/data-url";
+export { detectImageMediaType } from "./utils/image-media-type";
+export {
+  resolveFileMediaType,
+  resolveImageMediaType,
+  toMediaWireUrl,
+} from "./utils/wire-media";
 
 export * from "./runtime/internal";
 export * from "./runtimes/internal";

package/src/react/primitive-hooks/useSuggestionTrigger.test.ts

@@ -0,0 +1,148 @@
+/** @vitest-environment jsdom */
+import { cleanup, renderHook } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => {
+  const append = vi.fn();
+  const setText = vi.fn();
+
+  const state = {
+    thread: {
+      isDisabled: false,
+      isRunning: false,
+      capabilities: { queue: false },
+    },
+  };
+  const composerState = {
+    text: "",
+    runConfig: { custom: { model: "gpt-test" } },
+  };
+
+  return {
+    append,
+    setText,
+    state,
+    composerState,
+    aui: {
+      thread: {
+        getState: () => state.thread,
+        append,
+      },
+      composer: {
+        getState: () => composerState,
+        setText,
+      },
+    },
+  };
+});
+
+vi.mock("@assistant-ui/store", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("@assistant-ui/store")>()),
+  useAui: () => mocks.aui,
+  useAuiState: ((selector: (state: typeof mocks.state) => unknown) =>
+    selector(mocks.state)) as typeof import("@assistant-ui/store").useAuiState,
+}));
+
+import { useSuggestionTrigger } from "./useSuggestionTrigger";
+
+afterEach(() => {
+  cleanup();
+  vi.clearAllMocks();
+  mocks.state.thread.isDisabled = false;
+  mocks.state.thread.isRunning = false;
+  mocks.state.thread.capabilities = { queue: false };
+  mocks.composerState.text = "";
+});
+
+describe("useSuggestionTrigger", () => {
+  it("appends the prompt and clears the composer when sending while idle", () => {
+    const { result } = renderHook(() =>
+      useSuggestionTrigger({ prompt: "Hello", send: true }),
+    );
+
+    result.current.trigger();
+
+    expect(result.current.disabled).toBe(false);
+    expect(mocks.append).toHaveBeenCalledWith({
+      content: [{ type: "text", text: "Hello" }],
+      runConfig: { custom: { model: "gpt-test" } },
+    });
+    expect(mocks.setText).toHaveBeenCalledWith("");
+  });
+
+  it("disables and no-ops when sending while running without queue support", () => {
+    mocks.state.thread.isRunning = true;
+    mocks.composerState.text = "my draft";
+    const { result } = renderHook(() =>
+      useSuggestionTrigger({ prompt: "Hello", send: true }),
+    );
+
+    result.current.trigger();
+
+    expect(result.current.disabled).toBe(true);
+    expect(mocks.append).not.toHaveBeenCalled();
+    expect(mocks.setText).not.toHaveBeenCalled();
+  });
+
+  it("queues without touching the composer while running when the thread supports queueing", () => {
+    mocks.state.thread.isRunning = true;
+    mocks.state.thread.capabilities = { queue: true };
+    mocks.composerState.text = "my draft";
+    const { result } = renderHook(() =>
+      useSuggestionTrigger({ prompt: "Hello", send: true }),
+    );
+
+    result.current.trigger();
+
+    expect(result.current.disabled).toBe(false);
+    expect(mocks.append).toHaveBeenCalledWith({
+      content: [{ type: "text", text: "Hello" }],
+      runConfig: { custom: { model: "gpt-test" } },
+    });
+    expect(mocks.setText).not.toHaveBeenCalled();
+  });
+
+  it("replaces the composer text when send is false, even while running", () => {
+    mocks.state.thread.isRunning = true;
+    mocks.composerState.text = "my draft";
+    const { result } = renderHook(() =>
+      useSuggestionTrigger({ prompt: "Hello" }),
+    );
+
+    result.current.trigger();
+
+    expect(result.current.disabled).toBe(false);
+    expect(mocks.append).not.toHaveBeenCalled();
+    expect(mocks.setText).toHaveBeenCalledWith("Hello");
+  });
+
+  it("appends to the composer text when clearComposer is false", () => {
+    mocks.composerState.text = "my draft";
+    const { result } = renderHook(() =>
+      useSuggestionTrigger({ prompt: "Hello", clearComposer: false }),
+    );
+
+    result.current.trigger();
+
+    expect(mocks.setText).toHaveBeenCalledWith("my draft Hello");
+  });
+
+  it("inserts the prompt alone when the composer is empty and clearComposer is false", () => {
+    const { result } = renderHook(() =>
+      useSuggestionTrigger({ prompt: "Hello", clearComposer: false }),
+    );
+
+    result.current.trigger();
+
+    expect(mocks.setText).toHaveBeenCalledWith("Hello");
+  });
+
+  it("disables when the thread is disabled", () => {
+    mocks.state.thread.isDisabled = true;
+    const { result } = renderHook(() =>
+      useSuggestionTrigger({ prompt: "Hello" }),
+    );
+
+    expect(result.current.disabled).toBe(true);
+  });
+});

package/src/react/primitive-hooks/useSuggestionTrigger.ts

@@ -13,18 +13,24 @@ export const useSuggestionTrigger = ({
   clearComposer = true,
 }: UseSuggestionTriggerOptions) => {
   const aui = useAui();
-  const disabled = useAuiState((s) => s.thread.isDisabled);
   const resolvedSend = send ?? false;
+  const disabled = useAuiState(
+    (s) =>
+      s.thread.isDisabled ||
+      (resolvedSend && s.thread.isRunning && !s.thread.capabilities.queue),
+  );
 
   const trigger = useCallback(() => {
-    const isRunning = aui.thread.getState().isRunning;
+    if (resolvedSend) {
+      const { isRunning, capabilities } = aui.thread.getState();
+      if (isRunning && !capabilities.queue) return;
 
-    if (resolvedSend && !isRunning) {
       aui.thread.append({
         content: [{ type: "text", text: prompt }],
         runConfig: aui.composer.getState().runConfig,
       });
-      if (clearComposer) {
+      // A queued send must not clear the draft the user is still composing.
+      if (clearComposer && !isRunning) {
         aui.composer.setText("");
       }
     } else {

package/src/react/primitives/message/MessageParts.tsx

@@ -214,7 +214,12 @@ export namespace MessagePrimitiveParts {
     Image?: ImageMessagePartComponent | undefined;
     /** Component for rendering file content */
     File?: FileMessagePartComponent | undefined;
-    /** Component for rendering audio content (experimental) */
+    /**
+     * Component for rendering audio content.
+     *
+     * @deprecated Render audio through the `File` slot instead, branching on an
+     * `audio/*` mime type.
+     */
     Unstable_Audio?: Unstable_AudioMessagePartComponent | undefined;
     /** Configuration for data part rendering */
     data?: DataConfig | undefined;

package/src/react/providers/ReadonlyThreadProvider.tsx

@@ -26,6 +26,7 @@ const READONLY_THREAD_LIST_ITEM: ThreadListItemState = Object.freeze({
   remoteId: undefined,
   externalId: undefined,
   isMain: true,
+  isRunning: false,
   status: "regular" as const,
   title: undefined,
 });

package/src/react/runtimes/RemoteThreadListHookInstanceManager.running.test.tsx

@@ -0,0 +1,157 @@
+import { describe, expect, it, vi } from "vitest";
+import type { ThreadListRuntimeCore } from "../../runtime/interfaces/thread-list-runtime-core";
+import type { ThreadRuntimeCore } from "../../runtime/interfaces/thread-runtime-core";
+import type { ThreadMessage } from "../../types/message";
+import { RemoteThreadListHookInstanceManager } from "./RemoteThreadListHookInstanceManager";
+
+const makeRuntime = (
+  initial: Partial<Pick<ThreadRuntimeCore, "isRunning" | "messages">> = {},
+) => {
+  const subscribers = new Set<() => void>();
+  const runtime = {
+    isRunning: initial.isRunning,
+    messages: initial.messages ?? [],
+    subscribe: (callback: () => void) => {
+      subscribers.add(callback);
+      return () => subscribers.delete(callback);
+    },
+  } as unknown as ThreadRuntimeCore & {
+    isRunning: boolean | undefined;
+    messages: readonly ThreadMessage[];
+  };
+
+  return {
+    runtime,
+    subscriberCount: () => subscribers.size,
+    setRunning: (isRunning: boolean | undefined) => {
+      runtime.isRunning = isRunning;
+      for (const callback of subscribers) callback();
+    },
+  };
+};
+
+const makeManager = () =>
+  new RemoteThreadListHookInstanceManager(
+    () => ({}) as never,
+    {} as ThreadListRuntimeCore,
+  );
+
+// mirrors what the React binder does on every publication
+const publish = (
+  manager: RemoteThreadListHookInstanceManager,
+  threadId: string,
+  runtime: ThreadRuntimeCore,
+) => {
+  const internals = manager as unknown as {
+    instances: Map<string, { generation: number }>;
+    _publishThreadRuntime: (
+      threadId: string,
+      runtime: ThreadRuntimeCore,
+      generation: number,
+    ) => void;
+  };
+  const generation = internals.instances.get(threadId)!.generation;
+  internals._publishThreadRuntime(threadId, runtime, generation);
+};
+
+const start = (manager: RemoteThreadListHookInstanceManager, id: string) => {
+  manager.startThreadRuntime(id).catch(() => {});
+};
+
+describe("RemoteThreadListHookInstanceManager run tracking", () => {
+  it("reports a thread with no attached runtime as not running", () => {
+    const manager = makeManager();
+    start(manager, "thread-1");
+
+    expect(manager.__internal_isThreadRunning("thread-1")).toBe(false);
+    expect(manager.__internal_isThreadRunning("never-started")).toBe(false);
+  });
+
+  it("adopts the run state of the published runtime", () => {
+    const manager = makeManager();
+    start(manager, "thread-1");
+    const { runtime } = makeRuntime({ isRunning: true });
+
+    publish(manager, "thread-1", runtime);
+
+    expect(manager.__internal_isThreadRunning("thread-1")).toBe(true);
+  });
+
+  it("falls back to the trailing assistant message when the runtime does not track runs", () => {
+    const manager = makeManager();
+    start(manager, "thread-1");
+    const { runtime } = makeRuntime({
+      messages: [
+        { role: "assistant", status: { type: "running" } },
+      ] as unknown as readonly ThreadMessage[],
+    });
+
+    publish(manager, "thread-1", runtime);
+
+    expect(manager.__internal_isThreadRunning("thread-1")).toBe(true);
+  });
+
+  it("tracks a thread the user has switched away from", () => {
+    const manager = makeManager();
+    start(manager, "background");
+    start(manager, "main");
+    const background = makeRuntime({ isRunning: false });
+    publish(manager, "background", background.runtime);
+    publish(manager, "main", makeRuntime({ isRunning: false }).runtime);
+
+    background.setRunning(true);
+
+    expect(manager.__internal_isThreadRunning("background")).toBe(true);
+    expect(manager.__internal_isThreadRunning("main")).toBe(false);
+  });
+
+  it("notifies the thread list only when the thread crosses the running boundary", () => {
+    const manager = makeManager();
+    start(manager, "thread-1");
+    const thread = makeRuntime({ isRunning: false });
+    publish(manager, "thread-1", thread.runtime);
+
+    const onChange = vi.fn();
+    manager.__internal_subscribeRunningChanged(onChange);
+
+    thread.setRunning(false);
+    expect(onChange).not.toHaveBeenCalled();
+
+    thread.setRunning(true);
+    expect(onChange).toHaveBeenCalledTimes(1);
+
+    thread.setRunning(true);
+    expect(onChange).toHaveBeenCalledTimes(1);
+
+    thread.setRunning(false);
+    expect(onChange).toHaveBeenCalledTimes(2);
+  });
+
+  it("moves tracking to the runtime a restart publishes", () => {
+    const manager = makeManager();
+    start(manager, "thread-1");
+    const before = makeRuntime({ isRunning: true });
+    publish(manager, "thread-1", before.runtime);
+
+    const after = makeRuntime({ isRunning: false });
+    publish(manager, "thread-1", after.runtime);
+
+    expect(manager.__internal_isThreadRunning("thread-1")).toBe(false);
+    expect(before.subscriberCount()).toBe(0);
+
+    after.setRunning(true);
+    expect(manager.__internal_isThreadRunning("thread-1")).toBe(true);
+  });
+
+  it("releases the run subscription when the thread runtime stops", () => {
+    const manager = makeManager();
+    start(manager, "thread-1");
+    const thread = makeRuntime({ isRunning: true });
+    publish(manager, "thread-1", thread.runtime);
+
+    manager.stopThreadRuntime("thread-1");
+
+    expect(thread.subscriberCount()).toBe(0);
+    expect(manager.__internal_isThreadRunning("thread-1")).toBe(false);
+  });
+});