@kitn.ai/ui 0.25.2 → 0.27.0

package/dist/state/stream.d.ts

@@ -36,6 +36,56 @@ export interface AssistantStream {
     addSource(source: Unmixed<Source>): AssistantStream;
     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;
 }
 /** Start an assistant message and drive it through `set`. New refs on every mutation. */

package/dist/state/threads.d.ts

@@ -0,0 +1,71 @@
+import { ChatMessage } from '../elements/chat-types.js';
+import { SetMessages } from './stream.js';
+/** The minimal thread record the fold needs. The consumer's own record type
+ *  (title, timestamps, whatever its storage keeps) extends this — those fields
+ *  are policy and stay outside the kit. */
+export interface ThreadLike {
+    id: string;
+    messages: ChatMessage[];
+}
+/** The functional-updater setter over the whole thread LIST — the same
+ *  React-setState shape `SetMessages` is, one level up. */
+export type SetThreads<T extends ThreadLike> = (updater: (prev: T[]) => T[]) => void;
+export interface BindThreadOptions<T extends ThreadLike> {
+    /** Stamp the changed record (e.g. `updatedAt`). Runs on a hit only. Kept a
+     *  callback because WHAT gets stamped — and with whose clock — is the
+     *  consumer's record shape, not ours. */
+    touch?: (thread: T) => T;
+    /** A delta arrived for a thread that is no longer in the list (deleted while
+     *  its reply was streaming). The delta is dropped either way — dropping is
+     *  the only correct fold — but the drop is reported, not silent. */
+    onDrop?: (threadId: string) => void;
+}
+/**
+ * Pure fold: apply `updater` to the messages of thread `id` within a list.
+ *
+ * reactivity-two-halves (CLAUDE.md): the hit gets a NEW containing array
+ * (which notifies) and a NEW record object (which makes the change visible);
+ * every other record keeps its reference. A MISS returns `threads` itself —
+ * the same reference — so a late delta for a deleted thread re-renders
+ * nothing and resurrects nothing.
+ */
+export declare function updateThreadMessages<T extends ThreadLike>(threads: T[], id: string, updater: (prev: ChatMessage[]) => ChatMessage[], opts?: BindThreadOptions<T>): T[];
+/**
+ * A `SetMessages` bound to ONE thread. Capture the id when the user hits send
+ * and hand the result to `createAssistantStream`: the reply then lands in the
+ * thread that was open at send time, never whichever one is open when the
+ * tokens arrive — which is what makes switching away mid-reply (and coming
+ * back to a finished answer) safe.
+ */
+export declare function bindThreadMessages<T extends ThreadLike>(setThreads: SetThreads<T>, id: string, opts?: BindThreadOptions<T>): SetMessages;
+/** The in-flight-turn bookkeeping for a multi-thread app: which threads are
+ *  streaming, and the AbortController for each. See `createThreadSessions`. */
+export interface ThreadSessions {
+    /** Register a new in-flight turn. One turn per thread: a prior in-flight
+     *  turn for the SAME thread is aborted first. Pass the returned controller's
+     *  `signal` to your fetch — the fetch line itself stays yours. */
+    begin(threadId: string): AbortController;
+    /** The turn settled (done or failed) — call from your `finally`. `controller`
+     *  is required so a slow old turn's cleanup cannot clear a newer turn that
+     *  has since begun on the same thread: a stale controller is a no-op. */
+    end(threadId: string, controller: AbortController): void;
+    /** Cancel the in-flight turn (the delete-under-stream story): aborts the
+     *  controller and clears the streaming state. Returns whether anything was
+     *  actually in flight. Pair it with the id-bound sink above, which drops any
+     *  deltas that were already past the abort. */
+    abort(threadId: string): boolean;
+    isStreaming(threadId: string): boolean;
+    /** A fresh array snapshot each call — safe to hand straight to a setState. */
+    streamingIds(): string[];
+}
+/**
+ * Create the session tracker. `onChange` fires with a fresh `streamingIds()`
+ * snapshot after every transition — mirror it into your framework's state to
+ * derive `loading` (`sessions.isStreaming(activeId)` is the per-thread flag a
+ * single boolean cannot be, because a stream keeps running when you switch
+ * away).
+ *
+ * This is the one stateful object in the module, because an abort map is
+ * irreducibly stateful; it still does no I/O and owns no timer.
+ */
+export declare function createThreadSessions(onChange?: (streamingIds: string[]) => void): ThreadSessions;