@kitn.ai/ui 0.25.2 → 0.26.0

package/src/schemas/tool-defs.ts

@@ -27,9 +27,14 @@
 // `format: "uri"` (link/embed/artifact), `minimum` (tasks/embed/artifact),
 // `maxItems` (confirm/artifact), `pattern` (embed), `if`/`then` (embed), `oneOf`
 // (artifact), a free-form object (form) and untyped `payload`/`allowOther` members
-// (confirm/choice). Non-strict is therefore not merely the default, it is currently
-// the only working mode, and it is also the mode the five-configuration conformance
-// spike actually proved cards in.
+// (confirm/choice). Non-strict is therefore the default and the mode the
+// five-configuration conformance spike actually proved cards in — but since F-20 it
+// is no longer a raw pass-through either: a root combinator (`anyOf` on artifact,
+// `allOf` on embed) gets HTTP 400 from OpenAI and Anthropic even non-strict, so the
+// non-strict projection relaxes those root combinators LOUDLY (constraint restated in
+// the description, console.warn names the relaxation, registry.validate still
+// enforces at render time). The jsonschema projection stays byte-faithful to the
+// authored schema.
 //
 // The alternative was to silently drop the offending keywords. That is rejected for
 // the reason the plan gives: a dropped `maxItems: 4` means the model emits six
@@ -126,6 +131,42 @@ export interface CardToolOptions<P extends ToolProvider = ToolProvider> {
    * When it throws it names the card, the path and the keyword.
    */
   readonly strict?: boolean;
+  /**
+   * Narrow the DERIVED tool schema per card type, after projection (F-23).
+   *
+   * A card's authored schema is deliberately permissive — `files` is optional on an
+   * artifact, its items need only a `path` — because the card CONTRACT must accept
+   * what a host may legitimately render. A model filling the tool in, though, is
+   * often better served by a tighter tool: requiring `code` on every file, or at
+   * least one file at all, moves a class of failures from render time (a card the
+   * registry rejects) to generation time (the model literally cannot emit one).
+   *
+   * This narrows the WIRE projection only — the authored schema and
+   * `registry.validate()` are untouched, so a hand-built envelope still validates.
+   * Applied for every provider, `jsonschema` included, and merged loudly: an
+   * unknown path or a required name the node has no property for is a TypeError
+   * naming the card, the path and the field, because a tool that can never be
+   * satisfied must not ship quietly.
+   */
+  readonly require?: Readonly<Record<string, readonly CardRequireRule[]>>;
+}
+
+/**
+ * One narrowing instruction for one node of one card's projected schema.
+ *
+ * `path` is a dot-path from the envelope-data root through `properties` keys
+ * (`''` names the root node itself). On an ARRAY node, `required` narrows
+ * `items.required` and `minItems` lands on the array; on an object node,
+ * `required` lands on the node's own `required`. Existing requirements merge,
+ * never replace.
+ */
+export interface CardRequireRule {
+  /** Dot-path from the envelope-data root to a schema node, e.g. 'files'. */
+  readonly path: string;
+  /** Property names to require. On an ARRAY node this narrows `items.required`; on an object node, the node's own `required`. */
+  readonly required?: readonly string[];
+  /** Sets `minItems` (array nodes only). */
+  readonly minItems?: number;
 }
 
 /**
@@ -225,7 +266,7 @@ function formatUnsupported(subset: ProviderSubset, cards: readonly UnsupportedCa
   lines.push('');
   lines.push(`  subset source: ${subset.source} (read ${subset.checkedOn})`);
   lines.push(
-    '  Fix: drop `strict: true`. Non-strict is the default and is the mode the kit\'s cards are proven in; both providers accept a loose schema there and ignore what they do not compile. Rewriting a built-in card schema to fit a strict subset would change what a valid card IS, which is a card-contract change, not a projection setting.',
+    '  Fix: drop `strict: true`. Non-strict mode projects a provider-valid schema (root combinators are relaxed with the constraint restated in the description and still enforced by card validation). Rewriting a built-in card schema to fit a strict subset would change what a valid card IS, which is a card-contract change, not a projection setting.',
   );
   return lines.join('\n');
 }
@@ -237,6 +278,227 @@ function formatUnsupported(subset: ProviderSubset, cards: readonly UnsupportedCa
 const isRecord = (v: unknown): v is Record<string, unknown> =>
   typeof v === 'object' && v !== null && !Array.isArray(v);
 
+/**
+ * Root combinators the two largest providers refuse on a tool schema's root node
+ * (measured: OpenAI and Anthropic 400 before the model runs — findings F-20;
+ * DeepSeek's OpenAI-compatible route requires the same workaround). The AUTHORED
+ * schemas keep them — card validation keeps every constraint. Only the WIRE
+ * projection relaxes, loudly: the constraint is restated in the description the
+ * model reads, a console.warn names the relaxation, and a violating envelope
+ * still fails registry.validate() at render time with a hard diagnostic.
+ */
+const ROOT_RELAXATIONS: Readonly<Record<string, string>> = {
+  artifact:
+    'Provide `src` (a preview URL) or `files` — at least one. An envelope with neither is rejected.',
+  embed:
+    "For provider 'generic', include `url`. For 'youtube'/'vimeo', include `id` or `url`.",
+};
+
+/** Strip a banned combinator key from the projected ROOT node only (nested
+ *  combinators are accepted by every provider measured and stay). Returns the
+ *  relaxation note to restate in the TOOL description the model reads. Two
+ *  distinct no-note return paths: `undefined` when NOTHING was banned (the wire
+ *  projection is faithful, nothing was widened), and GENERIC_NOTE when something
+ *  WAS banned but no curated copy exists (a custom card) — that path still
+ *  restates the relaxation, because deleting a combinator without telling the
+ *  model would be a silent widening. */
+const GENERIC_RELAXATION_NOTE =
+  'The root constraint of this schema was relaxed for this provider; consult the card registry for what a valid payload is.';
+
+const BANNED_ROOT_KEYS = ['anyOf', 'allOf', 'oneOf', 'not', 'enum', 'const'] as const;
+
+/**
+ * The object shape a literal `enum` / `const` VALUE implies.
+ *
+ * `const: { op: 'ping' }` is a whole-instance constraint, which a provider refuses
+ * at the root exactly like a combinator. The instance it admits is an object, so
+ * the shape survives the relaxation as `properties: { op: { const: 'ping' } }` with
+ * `op` required — nothing widened that the branch did not already allow.
+ */
+function branchFromLiteral(value: unknown): Record<string, unknown> | null {
+  if (!isRecord(value)) return null;
+  const properties: Record<string, unknown> = {};
+  for (const [key, member] of Object.entries(value)) properties[key] = { const: member };
+  return { type: 'object', properties, required: Object.keys(value) };
+}
+
+/** The branch schemas one banned root keyword contributes, or `[]` for one that has none. */
+function branchesOfRootKeyword(keyword: string, value: unknown): Record<string, unknown>[] {
+  if (keyword === 'anyOf' || keyword === 'oneOf' || keyword === 'allOf') {
+    return Array.isArray(value) ? value.filter(isRecord) : [];
+  }
+  if (keyword === 'const') return [branchFromLiteral(value)].filter((b): b is Record<string, unknown> => b !== null);
+  if (keyword === 'enum') {
+    return Array.isArray(value)
+      ? value.map(branchFromLiteral).filter((b): b is Record<string, unknown> => b !== null)
+      : [];
+  }
+  // `not` is a NEGATIVE constraint: nothing it says is a property the instance may
+  // carry, so there is nothing sound to merge back. It is dropped and restated in
+  // the description like every other relaxation.
+  return [];
+}
+
+/**
+ * Fold a root combinator's branches back into the object root that replaces it.
+ *
+ * The two built-ins showed the shape of the rule and this generalises it rather
+ * than special-casing them. `artifact`'s root `anyOf` is `[{required:['src']},
+ * {required:['files']}]`: a DISJUNCTION guarantees only what EVERY branch
+ * guarantees, so the intersection is empty and `required` stays absent — which is
+ * exactly what the artifact projection already did. `embed`'s root `allOf` is two
+ * `if`/`then` pairs: a CONJUNCTION guarantees every branch's own top-level
+ * `required`, and an `if`/`then` branch declares none, so again nothing is added.
+ * A consumer card whose branches carry real `properties` is the case neither
+ * built-in reaches, and the one this exists for.
+ *
+ * Properties are UNIONed (each branch's shape must remain expressible — dropping
+ * one is the silent narrowing the whole F-20 fix exists to avoid); a name already
+ * on the root keeps the root's definition. `required` is the intersection for
+ * `anyOf`/`oneOf`/`enum`/`const` and the union for `allOf`, unioned in turn with
+ * whatever the root already required, and filtered to names the merged
+ * `properties` actually carries so the tool can never be unsatisfiable.
+ */
+function mergeBranchesIntoRoot(parameters: Record<string, unknown>, banned: readonly string[]): void {
+  const properties: Record<string, unknown> = isRecord(parameters.properties)
+    ? { ...parameters.properties }
+    : {};
+  const guaranteed = new Set<string>(
+    Array.isArray(parameters.required) ? parameters.required.map(String) : [],
+  );
+
+  for (const keyword of banned) {
+    const branches = branchesOfRootKeyword(keyword, parameters[keyword]);
+    if (branches.length === 0) continue;
+
+    for (const branch of branches) {
+      if (!isRecord(branch.properties)) continue;
+      for (const [name, sub] of Object.entries(branch.properties)) {
+        if (!(name in properties)) properties[name] = sub;
+      }
+    }
+
+    const perBranch = branches.map(
+      (branch) => new Set(Array.isArray(branch.required) ? branch.required.map(String) : []),
+    );
+    if (keyword === 'allOf') {
+      for (const set of perBranch) for (const name of set) guaranteed.add(name);
+    } else {
+      // Disjunction: keep only what every branch requires.
+      const [first, ...rest] = perBranch;
+      for (const name of first) {
+        if (rest.every((set) => set.has(name))) guaranteed.add(name);
+      }
+    }
+  }
+
+  if (Object.keys(properties).length > 0) parameters.properties = properties;
+  const required = [...guaranteed].filter((name) => name in properties);
+  if (required.length > 0) parameters.required = required;
+}
+
+/**
+ * Make the projected ROOT the object shape every provider demands.
+ *
+ * Deleting a root combinator is only half of F-20. A schema whose root was NOTHING
+ * BUT the combinator projects to `{"title":…,"description":…}` once it is gone —
+ * accepted by no provider (measured: OpenAI 400, "schema must be a JSON Schema of
+ * type \"object\"") and unfillable by any model. Every built-in declares
+ * `type: "object"` at its root, so nothing in the suite reached this until a
+ * consumer card did.
+ *
+ * A root that declares a NON-object type cannot be a tool schema at all, and
+ * asserting `type: "object"` over it would be a lie about the card. That refuses,
+ * naming the card.
+ */
+function ensureObjectRoot(parameters: Record<string, unknown>, cardType: string): void {
+  const declared = parameters.type;
+  if (declared !== undefined && declared !== 'object') {
+    throw new TypeError(
+      `cardTools: the '${cardType}' card schema declares root type '${String(declared)}', but a provider tool ` +
+        `schema root must be an object (OpenAI and Anthropic reject anything else with HTTP 400). ` +
+        `Wrap the payload in an object, or project this card with provider 'jsonschema'.`,
+    );
+  }
+  parameters.type = 'object';
+}
+
+function relaxRootCombinators(parameters: Record<string, unknown>, cardType: string): string | undefined {
+  const note = ROOT_RELAXATIONS[cardType];
+  const banned = BANNED_ROOT_KEYS.filter((k) => k in parameters);
+  // The object-root guarantee holds for EVERY provider projection, banned keys or
+  // not: it is what the provider requires, not what the relaxation broke.
+  ensureObjectRoot(parameters, cardType);
+  if (banned.length === 0) return undefined;
+  mergeBranchesIntoRoot(parameters, banned);
+  for (const k of banned) delete parameters[k];
+  // eslint-disable-next-line no-console
+  console.warn(
+    `[kai-card-tools] relaxed root ${banned.join('/')} on the projected '${toolNameForCardType(cardType)}' tool schema ` +
+      `for this provider (it would be refused with HTTP 400); the constraint now lives in the ` +
+      `description and is still enforced by card validation.`,
+  );
+  return note ?? GENERIC_RELAXATION_NOTE;
+}
+
+/**
+ * Apply one card's `require` rules to its PROJECTED parameters (F-23).
+ *
+ * Runs after `project()` and `relaxRootCombinators()`, on the copy the projection
+ * built — never on the authored schema, which `registry.validate()` keeps reading.
+ * Merges into whatever `required` already exists rather than replacing it, so a
+ * rule can only ever NARROW what the model may emit, never widen it.
+ */
+function applyRequire(
+  parameters: Record<string, unknown>,
+  cardType: string,
+  rules: readonly CardRequireRule[],
+): void {
+  for (const rule of rules) {
+    // Resolve the dot-path through `properties` keys. `''` names the root node;
+    // every other segment must name a property of the node reached so far.
+    let node: Record<string, unknown> = parameters;
+    if (rule.path !== '') {
+      for (const segment of rule.path.split('.')) {
+        const props = isRecord(node.properties) ? node.properties : undefined;
+        const next = props?.[segment];
+        if (!isRecord(next)) {
+          throw new TypeError(
+            `cardTools: require on '${cardType}': path '${rule.path}' does not resolve in the schema`,
+          );
+        }
+        node = next;
+      }
+    }
+
+    const isArrayNode = node.type === 'array' || (node.type === undefined && 'items' in node);
+    if (isArrayNode && rule.minItems !== undefined) node.minItems = rule.minItems;
+    if (!isArrayNode && rule.minItems !== undefined) {
+      throw new TypeError(
+        `cardTools: minItems at require path '${rule.path}' applies to array nodes only, ` +
+          `but '${rule.path}' in the '${cardType}' schema is not one`,
+      );
+    }
+
+    if (rule.required !== undefined) {
+      // On an array node the requirement lives on the ITEMS (each element must carry
+      // the field), not on the array itself.
+      const target = isArrayNode && isRecord(node.items) ? node.items : node;
+      const props = isRecord(target.properties) ? target.properties : undefined;
+      for (const field of rule.required) {
+        if (!props || !(field in props)) {
+          throw new TypeError(
+            `cardTools: require on '${cardType}' at path '${rule.path}': '${field}' is not a property of that node — ` +
+              `a required name with no property would make the tool unsatisfiable`,
+          );
+        }
+      }
+      const existing = Array.isArray(target.required) ? target.required.map(String) : [];
+      target.required = [...new Set([...existing, ...rule.required])];
+    }
+  }
+}
+
 /**
  * Keywords stripped from every projection, strict or not.
  *
@@ -430,11 +692,40 @@ export function cardTools(a: CardToolInput | CardToolOptions, b?: CardToolOption
   const defs: ToolDef[] = [];
   const failures: UnsupportedCardTool[] = [];
 
+  // A `require` key naming a card the call does not carry is a typo, and a typo here
+  // would otherwise narrow NOTHING while looking like it narrowed something — the
+  // same decide-loudly class as an unknown dot-path below.
+  if (opts.require !== undefined) {
+    for (const key of Object.keys(opts.require)) {
+      if (!(key in schemas)) {
+        throw new TypeError(
+          `cardTools: require names card type '${key}', which this call does not carry ` +
+            `(carries: ${Object.keys(schemas).join(', ') || 'none'})`,
+        );
+      }
+    }
+  }
+
   for (const [cardType, schema] of Object.entries(schemas)) {
     const name = toolNameForCardType(cardType);
     const description = describe(cardType, schema, descriptions);
     const parameters = project(schema, projectOptions) as ToolParameters;
 
+    // F-20: non-strict only. Strict mode already refuses these cards with the full
+    // subset check, so the relaxation must never mask it. The note is restated in the
+    // TOOL description — the envelope field the model reads when choosing the tool.
+    const relaxedNote =
+      subset === null && opts.provider !== 'jsonschema'
+        ? relaxRootCombinators(parameters as Record<string, unknown>, cardType)
+        : undefined;
+    const wireDescription = relaxedNote ? `${description} ${relaxedNote}` : description;
+
+    // F-23: every provider, jsonschema included — a consumer handing the bare schema
+    // to the Vercel AI SDK narrows their tool the same way. Runs BEFORE the strict
+    // subset check so that check judges the schema that actually ships.
+    const requireRules = opts.require?.[cardType];
+    if (requireRules !== undefined) applyRequire(parameters as Record<string, unknown>, cardType, requireRules);
+
     if (subset) {
       const violations = checkProviderSubset(parameters, subset);
       if (violations.length > 0) {
@@ -444,9 +735,9 @@ export function cardTools(a: CardToolInput | CardToolOptions, b?: CardToolOption
     }
 
     if (opts.provider === 'openai') {
-      defs.push({ type: 'function', function: { name, description, parameters, ...(strict ? { strict: true as const } : {}) } });
+      defs.push({ type: 'function', function: { name, description: wireDescription, parameters, ...(strict ? { strict: true as const } : {}) } });
     } else if (opts.provider === 'anthropic') {
-      defs.push({ name, description, input_schema: parameters, ...(strict ? { strict: true as const } : {}) });
+      defs.push({ name, description: wireDescription, input_schema: parameters, ...(strict ? { strict: true as const } : {}) });
     } else {
       defs.push({ name, description, schema: parameters });
     }

package/src/solid.ts

@@ -69,6 +69,8 @@ export { EditableLabel } from './ui/editable-label';
 export type { EditableLabelProps } from './ui/editable-label';
 export { Dialog } from './ui/dialog';
 export type { DialogProps, DialogController } from './ui/dialog';
+export { Dock, DockLauncherGlyph, DockCloseGlyph } from './ui/dock';
+export type { DockProps, DockController, DockPosition, DockFocusOnOpen } from './ui/dock';
 export { Popover } from './ui/popover';
 export type { PopoverProps, PopoverController } from './ui/popover';
 export { Nav } from './ui/nav';
@@ -148,3 +150,6 @@ export type {
   AudioVisualizerProps, VisualizerVariant, ShaderSpec, ShaderVariantProps,
 } from './components/audio-visualizer';
 export type { VisualizerSize } from './components/audio-visualizer/sizes';
+export { WorkspaceShell, type WorkspaceShellProps, type WorkspaceShellController, type WorkspaceAsideSide, type WorkspaceAsideToggleDetail, type WorkspaceAsideResizeDetail } from './components/workspace-shell';
+export { createConversationItemsController, readConversationItemId } from './components/conversation-list';
+export type { ConversationItemsController, ConversationItemsControllerOptions } from './components/conversation-list';

package/src/state/index.ts

@@ -7,6 +7,18 @@ export type { SetMessages, AssistantStream } from './stream';
 export { appendTextPart, appendReasoningPart, upsertToolPart, upsertCardPart, fingerprint } from './parts';
 export type { ReasoningOpts } from './parts';
 
+// Multi-thread mechanics (the workspace recast, spec §3b): the id-bound
+// SetMessages fold + the in-flight-turn bookkeeping. The consumer's record
+// shape and every persistence/retention decision stay outside — see ./threads.
+export { updateThreadMessages, bindThreadMessages, createThreadSessions } from './threads';
+export type { ThreadLike, SetThreads, BindThreadOptions, ThreadSessions } from './threads';
+
+// The persistence SEAM, not persistence: the stored-thread validator (F-18,
+// variant list derived from the MessagePart union) and the debounce/flush
+// shape. No storage backend, no default delay — policy is the consumer's.
+export { parseStoredThread, createSaveScheduler } from './persistence';
+export type { ParsedThread, DroppedStored, SaveScheduler, SaveSchedulerOptions } from './persistence';
+
 // The zero-config mock. Produces SSE frames rather than folding parts directly,
 // so the no-backend preview runs through the SAME parser a real provider does —
 // and is deliberately impossible to mistake for one. See ./mock.

package/src/state/persistence.ts

@@ -0,0 +1,180 @@
+// src/state/persistence.ts — the mechanical halves of the persistence story.
+//
+// The boundary (spec §1, CLAUDE.md): persistence POLICY — what is stored,
+// where, for how long, under what quota — is the app's. What lives here is
+// only the mechanics every such app re-derives by hand: validating a stored
+// thread back into `ChatMessage[]` (F-18), and the debounce/flush shape that
+// keeps a per-token stream from hitting storage per token. No storage call,
+// no fetch, no DOM; the save fn, the delay, and the reaction to a drop are
+// all the consumer's.
+import type { ChatMessage, FeedbackVote, MessagePart } from '../elements/chat-types';
+
+/** One record the parse refused, and why. Deciding loudly is the caller's
+ *  verb (warn, reject the whole record, count it); this is the information
+ *  that a quiet version would withhold. */
+export interface DroppedStored {
+  at: 'thread' | 'message' | 'part';
+  reason: string;
+  value: unknown;
+}
+
+export interface ParsedThread {
+  messages: ChatMessage[];
+  /** Empty on a clean parse. Never silently shorter output than input. */
+  dropped: DroppedStored[];
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null;
+}
+
+/**
+ * One payload check per `MessagePart` variant. The key set is DERIVED from the
+ * union in `src/elements/chat-types.ts` at compile time: `satisfies
+ * Record<MessagePart['type'], …>` makes a missing key (a 7th variant landed)
+ * and a stale key (a variant renamed away) each a type error in THIS file —
+ * the same union `lint:silent-drops` and `verify:scaffold` read, so the lists
+ * cannot disagree. The behavioral cross-check lives in ./persistence.test.ts,
+ * which re-reads the union by a deliberately different method.
+ *
+ * These are shape checks, not a trust boundary for rendering: a rehydrated
+ * part is model output twice over (it was model output before it was
+ * hand-editable storage), and it stays safe to draw because the elements are
+ * what draw it. What this buys is that a truncated or half-written record
+ * reaches the element as a well-formed thread minus the broken piece, instead
+ * of as `parts: undefined` taking the whole app down on first render.
+ */
+const PART_VALIDATORS = {
+  text: (v) => typeof v.text === 'string',
+  reasoning: (v) => typeof v.text === 'string',
+  tool: (v) => isRecord(v.tool),
+  card: (v) => isRecord(v.envelope) && typeof v.envelope.type === 'string' && typeof v.envelope.id === 'string',
+  source: (v) => isRecord(v.source),
+  file: (v) => isRecord(v.attachment),
+} satisfies Record<MessagePart['type'], (v: Record<string, unknown>) => boolean>;
+
+function parsePart(v: unknown, dropped: DroppedStored[]): MessagePart | null {
+  if (!isRecord(v) || typeof v.type !== 'string') {
+    dropped.push({ at: 'part', reason: 'not a part record', value: v });
+    return null;
+  }
+  const validate = (PART_VALIDATORS as Record<string, (v: Record<string, unknown>) => boolean>)[v.type];
+  if (!validate) {
+    // An unknown `type` is dropped rather than passed on: every renderer and
+    // encoder switches on it and has no branch for a made-up one.
+    dropped.push({ at: 'part', reason: `unknown part type "${v.type}"`, value: v });
+    return null;
+  }
+  if (!validate(v)) {
+    dropped.push({ at: 'part', reason: `missing or invalid payload for "${v.type}" part`, value: v });
+    return null;
+  }
+  // Verbatim, not rebuilt: optional fields the variants carry (`raw`,
+  // `signature`, `index`, …) are load-bearing on the wire re-encode, so the
+  // validated record passes through whole.
+  return v as unknown as MessagePart;
+}
+
+function parseMessage(v: unknown, dropped: DroppedStored[]): ChatMessage | null {
+  if (!isRecord(v) || typeof v.id !== 'string' || (v.role !== 'user' && v.role !== 'assistant') || !Array.isArray(v.parts)) {
+    dropped.push({ at: 'message', reason: 'not a message record (id/role/parts)', value: v });
+    return null;
+  }
+  const parts = v.parts
+    .map((p) => parsePart(p, dropped))
+    .filter((p): p is MessagePart => p !== null);
+  if (parts.length === 0) {
+    // A message whose every part was unreadable is an empty bubble, and the
+    // per-part entries above already say what was lost.
+    dropped.push({ at: 'message', reason: 'no readable parts survived', value: v });
+    return null;
+  }
+  const message: ChatMessage = { id: v.id, role: v.role, parts };
+  if (v.feedback === 'like' || v.feedback === 'dislike') message.feedback = v.feedback as FeedbackVote;
+  if (isRecord(v.avatar)) message.avatar = v.avatar;
+  if (Array.isArray(v.actions)) message.actions = v.actions as ChatMessage['actions'];
+  return message;
+}
+
+/**
+ * Validate a stored thread — the JSON-parsed value of one thread's messages
+ * array — back into `ChatMessage[]`. Never throws: unreadable records are
+ * DROPPED and reported in `dropped`, so a truncated write loses one record,
+ * not every conversation. What to DO about a drop (warn, discard the whole
+ * record, telemetry) is the caller's policy.
+ */
+export function parseStoredThread(value: unknown): ParsedThread {
+  const dropped: DroppedStored[] = [];
+  if (!Array.isArray(value)) {
+    return { messages: [], dropped: [{ at: 'thread', reason: 'stored thread is not an array', value }] };
+  }
+  const messages = value
+    .map((m) => parseMessage(m, dropped))
+    .filter((m): m is ChatMessage => m !== null);
+  return { messages, dropped };
+}
+
+export interface SaveSchedulerOptions {
+  /** The quiet period before a scheduled snapshot is written. This is policy
+   *  and therefore REQUIRED — the kit ships no default debounce. */
+  delayMs: number;
+  /** The scheduler the seam runs on. Defaults to the global timers; inject
+   *  your own for tests or a non-timer scheduler. */
+  setTimeout?: (fn: () => void, ms: number) => unknown;
+  clearTimeout?: (handle: unknown) => void;
+}
+
+export interface SaveScheduler<T> {
+  /** Remember `snapshot` as the latest state and (re)start the quiet-period
+   *  timer. Call it on every state change; only the last snapshot inside the
+   *  quiet period is written. */
+  schedule(snapshot: T): void;
+  /** Write the pending snapshot NOW and disarm the timer — the
+   *  `beforeunload`/`visibilitychange` story, so a tab closed mid-stream still
+   *  persists. No-op when nothing is pending: the last write already happened. */
+  flush(): void;
+  /** Drop the pending write unsaved (e.g. unmount-without-persist). */
+  cancel(): void;
+  pending(): boolean;
+}
+
+/**
+ * The debounce/flush seam: a streaming reply lands a state update per token,
+ * and without this shape so would the consumer's storage backend. The kit owns
+ * only the timer dance; `save` (WHAT and WHERE, including its own try/catch
+ * policy for quota errors) and `delayMs` (HOW LONG) are the consumer's.
+ */
+export function createSaveScheduler<T>(save: (snapshot: T) => void, opts: SaveSchedulerOptions): SaveScheduler<T> {
+  const setTimer = opts.setTimeout ?? ((fn: () => void, ms: number) => setTimeout(fn, ms));
+  const clearTimer = opts.clearTimeout ?? ((handle: unknown) => clearTimeout(handle as ReturnType<typeof setTimeout>));
+
+  let latest: T | undefined;
+  let armed = false;
+  let handle: unknown;
+
+  const disarm = () => {
+    if (!armed) return;
+    clearTimer(handle);
+    armed = false;
+  };
+  const write = () => {
+    armed = false;
+    save(latest as T);
+  };
+
+  return {
+    schedule(snapshot) {
+      latest = snapshot;
+      disarm();
+      handle = setTimer(write, opts.delayMs);
+      armed = true;
+    },
+    flush() {
+      if (!armed) return;
+      disarm();
+      save(latest as T);
+    },
+    cancel: disarm,
+    pending: () => armed,
+  };
+}

package/src/state/stream.ts

@@ -116,6 +116,56 @@ export interface AssistantStream {
    * assignability already holds. Measurements and the trade: boundary point 2. */
   addFile(attachment: AttachmentData): AssistantStream;
   done(): void;
+  /** Settles the turn as FAILED and puts `reason` where the reader can find it.
+   *
+   *  WHERE THE REASON LANDS, in order:
+   *  1. every tool part that has NOT produced a result flips to `output-error`
+   *     with `errorText: reason`, so no panel spins forever. A tool ALREADY in
+   *     `output-error` with its own non-empty `errorText` is left exactly as it
+   *     is: "search index offline" is the answer to what went wrong and
+   *     "Connection lost." is the generic outer symptom, so overwriting the
+   *     specific with the generic loses the only actionable thing on the
+   *     message. It still counts as carrying the failure. A tool in
+   *     `output-error` with NO text does get filled in — an error panel with
+   *     nothing in it says no more than a blank bubble does.
+   *  2. if no part was able to carry it, the reason is APPENDED as its own text
+   *     part.
+   *
+   *  Never both — a turn does not report the same failure twice.
+   *
+   *  "Where the reader can FIND it" is deliberate, and rule 1 and rule 2 are not
+   *  equally loud. Rule 2 is text in the thread: read without any interaction.
+   *  Rule 1 is a tool panel, which renders COLLAPSED — the header shows an error
+   *  icon and a badge, so the failure is unmissable, but the `errorText` itself
+   *  is one click away. That is the right default for a failed tool inside an
+   *  otherwise readable answer, and it is why rule 2 exists rather than always
+   *  stamping the panel and calling it reported.
+   *
+   *  Rule 2 is the whole point and it used to be missing. `abort` only ever did
+   *  rule 1, so a TEXT-ONLY turn — every turn of a text-only support widget —
+   *  had nothing to stamp: the string was discarded and a failed request
+   *  rendered an EMPTY assistant bubble, while the consumer that passed a
+   *  perfectly good sentence believed it had reported the failure. That is the
+   *  repo's "decide loudly" rule broken on the one path where being quiet is
+   *  worst, and it shipped because the discard is invisible from the call site.
+   *
+   *  It is a NEW part, never a merge onto the trailing text: gluing "Connection
+   *  lost." onto the model's half-finished sentence reads as the model saying
+   *  it. Text that already streamed stays exactly where it is.
+   *
+   *  The reason is TRIMMED, and `abort()` with no reason — or one that is empty
+   *  or all whitespace — appends nothing: there is no reason to discard, and the
+   *  kit will not invent copy the consumer did not write. Rule 1 still runs,
+   *  with `errorText: undefined`. Whitespace is not a pedantic case here: the
+   *  scaffold hands over `err.message`, and an `Error` is free to carry `''`,
+   *  which would otherwise render an INVISIBLE text part — a blank bubble that
+   *  also claims to have said something.
+   *
+   *  Settled is settled: after `done()` or a first `abort()`, this is a no-op
+   *  like every other mutator, so the reason cannot be appended twice.
+   *
+   *  The reason is CONSUMER-facing text and is rendered as markdown like any
+   *  other text part. Pass a sentence a visitor can read, not a stack trace. */
   abort(reason?: string): void;
 }
 
@@ -151,10 +201,27 @@ export function createAssistantStream(
     addFile(attachment) { mutate((p) => [...p, { type: 'file', attachment }]); return stream; },
     done() { settled = true; },
     abort(reason) {
-      mutate((p) => p.map((part) =>
-        part.type === 'tool' && part.tool.state !== 'output-available'
-          ? { ...part, tool: { ...part.tool, state: 'output-error' as const, errorText: reason } }
-          : part));
+      // Whitespace-only is the same nothing as empty. `err.message` on a thrown
+      // Error is free to be either, and appending it would render an INVISIBLE
+      // text part -- a blank bubble that also claims to have said something.
+      const text = reason?.trim() || undefined;
+      mutate((p) => {
+        let carried = false;
+        const next = p.map((part) => {
+          if (part.type !== 'tool' || part.tool.state === 'output-available') return part;
+          // Already showing its own, more specific failure: keep it, and count
+          // it as carrying. See the note above `abort`.
+          if (part.tool.state === 'output-error' && part.tool.errorText?.trim()) {
+            carried = true;
+            return part;
+          }
+          carried = true;
+          return { ...part, tool: { ...part.tool, state: 'output-error' as const, errorText: text } };
+        });
+        // The reason has to land SOMEWHERE. See the note above `abort`.
+        if (carried || !text) return next;
+        return [...next, { type: 'text', text }];
+      });
       settled = true;
     },
   };