@nanisoft/prism-ui 0.16.0 → 1.0.0

package/dist/live/message-thread-01/message-thread.d.ts

@@ -0,0 +1,282 @@
+import { type ReactNode } from 'react';
+import { type RunStatus } from '../status.js';
+import type { ToolCall } from '../tool-ledger-01/tool-ledger.js';
+/**
+ * Who a message is from, as a closed set.
+ *
+ * The four are the ones a conversation actually has, and they are closed for the
+ * reason `RunEventRole` is: a sender is a slot for a mark and an ink, and a
+ * free-text sender would be a string with no rendering behind it. The **words**
+ * are still the caller's, in `senderLabel`. Prism owns which sender looks like
+ * what, and ships none of the labels.
+ */
+export type MessageSender = 'user' | 'assistant' | 'system' | 'tool';
+/** A run of text, in the consumer's words. */
+export type MessageTextPart = {
+    kind: 'text';
+    /** What the sender said. */
+    text: string;
+};
+/**
+ * A reasoning block: the model's own working, shown collapsed.
+ *
+ * `label` is required because a disclosure whose summary has no words is announced
+ * as a disclosure and nothing else, and the word on it is the consumer's.
+ */
+export type MessageReasoningPart = {
+    kind: 'reasoning';
+    /** The words on the disclosure's summary. */
+    label: string;
+    /** The reasoning itself. */
+    text: string;
+};
+/**
+ * A tool call inside a message, drawn through the ledger's own row.
+ *
+ * The call is a `ToolCall`, which is the shape `ToolLedger01` already receives, so
+ * a tool call is drawn the same way in a message as in the ledger and there is no
+ * second tool-call shape.
+ */
+export type MessageToolPart = {
+    kind: 'tool';
+    /** The call, in the vocabulary `ToolLedger01` already publishes. */
+    call: ToolCall;
+};
+/** A citation: a labelled destination for a claim in the message. */
+export type MessageCitationPart = {
+    kind: 'citation';
+    /** The words on the link, required because a link with no name announces as a link. */
+    label: string;
+    /** Where it goes. */
+    href: string;
+    /** Anything the label cannot hold: a page, a line, a quote. */
+    detail?: string;
+};
+/**
+ * An attachment in the thread.
+ *
+ * `preview` is the consumer's own node, because the media an attachment shows is
+ * drawn by Items this package already ships rather than by this surface. It is
+ * placed above the name and never inside the link, so a preview that holds a
+ * control cannot nest one inside the anchor.
+ */
+export type MessageAttachmentPart = {
+    kind: 'attachment';
+    /** The name a reader recognises it by. */
+    name: string;
+    /** Where the attachment lives, absent for one that is only named. */
+    href?: string;
+    /** The consumer's own rendering of the attachment's contents. */
+    preview?: ReactNode;
+};
+/**
+ * One part of a message, as the surface receives it.
+ *
+ * The five are the ones every surveyed stream converges on, and the set is closed
+ * because a part is a slot for a rendering rather than a free-text kind. Several
+ * tool calls fit in one message without a second key, which is the reason the
+ * content shape is a message with ordered parts rather than a flat event list.
+ */
+export type MessagePart = MessageTextPart | MessageReasoningPart | MessageToolPart | MessageCitationPart | MessageAttachmentPart;
+/**
+ * One message, as the surface receives it.
+ *
+ * A message has a stable identity, a sender, an optional metadata node and an
+ * ordered list of parts. The `id` is stable across deliveries, so a transport that
+ * reports the same message again as more parts arrive updates one message rather
+ * than appending a second. `at` is the consumer's own epoch milliseconds and the
+ * only value the surface orders by.
+ */
+export type ChatMessage = {
+    /** Stable across deliveries, so a re-reported message updates in place. */
+    id: string;
+    /** Who sent it. See `MessageSender`. */
+    sender: MessageSender;
+    /** The sender's own name for the reader, absent for a surface that draws only the mark. */
+    senderLabel?: string;
+    /** Epoch milliseconds, used for order. */
+    at: number;
+    /**
+     * The caller's own per-message metadata, drawn in the message's header.
+     *
+     * A message carries one node of the caller's choosing beside the sender and the
+     * time: the model a provider stated for the turn, a token count it reported, and
+     * the cost or the latency the caller derived. It is a node rather than a set of
+     * Prism fields because the last two are the consumer's own derivation, which the
+     * conversation decision in `DESIGN.md` rules: no provider read publishes a cost
+     * or a latency, so the surface draws only what the caller hands it and states no
+     * model, no count and no figure for itself. The parts are content a reader reads
+     * as the message; this is metadata about the message and sits above its parts.
+     *
+     * It is the same `meta` shape `ItemEntry` takes, read at the message.
+     */
+    meta?: ReactNode;
+    /** The message's parts, in the order they are drawn and never re-sorted. */
+    parts: readonly MessagePart[];
+};
+/**
+ * How the surface receives messages.
+ *
+ * The consumer owns the socket, the transport and the persistence, so this is a
+ * function it supplies rather than a connection Prism opens. It is called once on
+ * mount and must return an unsubscribe, which is what makes a WebSocket, an
+ * `EventSource`, a polling timer or a test's own array all the same shape to the
+ * surface. Nothing here knows which one it got.
+ */
+export type MessageSubscribe = (emit: (message: ChatMessage) => void) => () => void;
+export type MessageThread01Props = {
+    /**
+     * Called once to begin receiving, and again whenever `resubscribeKey` changes.
+     * Must return an unsubscribe; the surface calls it on unmount and before
+     * re-subscribing, so a consumer that returns nothing leaks its connection.
+     */
+    subscribe: MessageSubscribe;
+    /**
+     * The messages already known when this thread is opened, so a surface opened
+     * mid-thread is not blank. Oldest first.
+     *
+     * Read when the thread is opened, and again whenever `resubscribeKey` changes. It
+     * is **not** read on every render: a prop that looked like the current message
+     * list and quietly seeded only once would be a trap, and a prop that re-seeded on
+     * every render would discard the stream. This seeds, and the stream takes over.
+     *
+     * It is also the whole of the resumption seam: the durable buffer that outlives
+     * a mount is the consumer's, and a surface opened after a reconnect is seeded
+     * from the consumer's own record rather than from anything Prism kept.
+     */
+    initial?: readonly ChatMessage[];
+    /**
+     * Which thread this surface is showing, and the reset lever.
+     *
+     * Changing it **clears the thread and reseeds it from `initial`**, as well as
+     * tearing the subscription down and opening a new one. A thread is identified by
+     * whatever the consumer already uses to identify it, so a second thread in the
+     * same surface is a new subscription rather than two consumers of one, and it is
+     * a new thread rather than the old messages with the new ones appended.
+     */
+    resubscribeKey?: string | number;
+    /** Where the thread has got to. The tiers are the `live` Kind's own. */
+    status?: RunStatus;
+    /** The word beside the status. Required when a status is passed. */
+    statusLabel?: string;
+    /** Optional label above the surface's heading. See the No-Default-Eyebrow Rule. */
+    eyebrow?: string;
+    /** The surface's heading. Omit it for one composed under its own. */
+    title?: string;
+    /** One or two sentences under the heading. */
+    description?: string;
+    /** What the surface says when it holds no messages yet. */
+    emptyLabel?: string;
+    /**
+     * The accessible name of the scrolling region.
+     *
+     * Required, because `ScrollArea` requires it and the reason is the right one: a
+     * scroll region with no name is announced as a group of focusable nothing, and a
+     * keyboard reader who tabs into it cannot tell what is in it or what is past the
+     * edge. The name is the consumer's word, as every other word here is.
+     */
+    messagesLabel: string;
+    /** Announced to assistive technology as messages arrive. */
+    liveLabel?: string;
+    /** How many messages to keep. Older messages fall off the top. @defaultValue 200 */
+    limit?: number;
+    /**
+     * Whether the surface opens paused.
+     *
+     * Read when the thread opens, and the control below owns it from the first press
+     * after that. It pauses the **surface** and never the run: the subscription stays
+     * open, because the connection is the consumer's and they may be sharing it with
+     * a `RunStream01` beside it.
+     */
+    paused?: boolean;
+    /** Layout only. Changing a Prism-owned visual property from here is prohibited. */
+    className?: string;
+} & ({
+    pauseControl?: false;
+    pauseLabel?: never;
+    resumeLabel?: never;
+} | {
+    pauseControl: true;
+    pauseLabel: string;
+    resumeLabel: string;
+});
+/**
+ * The message thread of a conversation, receiving messages as they arrive.
+ *
+ * **This is the `live` Kind's second family, and it is the second client surface in
+ * the package beside `RunStream01`.** A conversation's content changes over time
+ * without a navigation event, which is the definition of the Kind, and a chat that
+ * cannot stream is not a chat. So this surface owns a subscription and the bounded
+ * window behind it, exactly as the run log does.
+ *
+ * **Prism owns the surface, the consumer owns the transport.** `subscribe` is a
+ * function the consumer supplies and a function it tears down. There is no socket
+ * in this file, no endpoint, no retry policy, no persistence and no provider to
+ * mount, so a WebSocket, an `EventSource`, a polling timer and a test's own array
+ * are all the same shape to this surface. A consumer that already has a connection
+ * passes it in, and one that does not has not acquired a client runtime by
+ * importing this.
+ *
+ * **The content is a message list with ordered parts, and neither an event list nor
+ * a turn list is taken.** A message is an artifact a reader reads and addresses,
+ * where an occurrence is not, so the run's flat `RunEvent` stays the run log's own
+ * vocabulary. A turn is a derived grouping of a request and its answers, the
+ * transport does not preserve it as a unit, and the order of a stream after a
+ * reconnect is unsettled, so a surface that grouped by turn would impose a
+ * structure the consumer's data may not have. The message and part vocabulary lives
+ * here, beside `RunEvent` and `ToolCall`, and is deliberately not a member of the
+ * shared specification module.
+ *
+ * **Per-message metadata is the caller's own node.** The model a provider stated
+ * for a turn, a token count it reported, and the cost and the latency a consumer
+ * derived are metadata about a message rather than content a reader reads as it, so
+ * a message carries an optional `meta` the surface draws in its header beside the
+ * sender and the time. It is a node, and deliberately not a set of Prism fields:
+ * cost and latency are the consumer's own derivation, because no provider read
+ * publishes either, so the surface draws what it was handed and states no figure
+ * for itself. This is the `ItemEntry.meta` shape read at the message.
+ *
+ * **The four things the Kind already names are reused rather than answered twice.**
+ * A tool-call part is drawn through `ToolLedger01`'s own row, so there is no second
+ * tool-call shape. The status tiers are the ones `RunStatus` already publishes. The
+ * run controls are `PromptComposer`'s send, stop, retry and attach, which the
+ * consumer composes beside this surface rather than this surface drawing a second
+ * set of them. The one surface it does not reuse is `RunStream01`, because a run's
+ * log is a sequence of occurrences and a conversation is a sequence of messages.
+ *
+ * **The surface draws no control it cannot act on.** The only control in it is the
+ * pause control, which pauses this surface and never the run, and which a consumer
+ * opts into with `pauseControl`. Send, stop, retry and attach are not here: they are
+ * `PromptComposer`'s, and a settled thread composed outside the live module reaches
+ * a decision through a `CtaLink` with its required `href` or a slot the consumer
+ * fills.
+ *
+ * **Prism holds a bounded in-memory window and promises no resumption.** The
+ * durable buffer that outlives a mount is the consumer's, because Prism ships no
+ * permanent client runtime and cannot assume a server framework. The seam is
+ * `initial` and `resubscribeKey`: a surface opened mid-thread is seeded from the
+ * consumer's own record, a reconnect is a new key over a fresh seed, and the
+ * surface promises no resumption so it cannot fail to keep one.
+ *
+ * **Messages are kept sorted by `at`, not by arrival.** A transport decides when a
+ * message is delivered, and a reconnect can deliver an older message after a newer
+ * one. Ties break on `id`, so the order is total and the same thread renders the
+ * same way every time. The same `id` is also the same message, so a transport that
+ * reports it again as more parts arrive updates one message rather than adding a
+ * second.
+ *
+ * **New messages are announced once, politely, and the thread itself is not a live
+ * region.** Announcing a growing list would make a screen reader read the whole
+ * thread again on every arrival, which is the failure a live region on a list
+ * guarantees. `LiveRegion` carries the newest message's first readable part alone,
+ * and the thread is an ordinary scrollable list a reader moves through at their own
+ * pace.
+ *
+ * `limit` bounds what is held, because a long conversation produces thousands of
+ * messages and a surface that grows without bound eventually stops repainting.
+ * Older messages fall off the top, which is the direction a reader wants: the
+ * thread's beginning is the part they can scroll back to in the consumer's store.
+ */
+export declare function MessageThread01({ subscribe, initial, resubscribeKey, status, statusLabel, eyebrow, title, description, emptyLabel, messagesLabel, liveLabel, limit, paused, pauseControl, pauseLabel, resumeLabel, className, }: MessageThread01Props): import("react").JSX.Element;
+export default MessageThread01;
+//# sourceMappingURL=message-thread.d.ts.map

package/dist/live/message-thread-01/message-thread.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-thread.d.ts","sourceRoot":"","sources":["../../../src/live/message-thread-01/message-thread.tsx"],"names":[],"mappings":"AAEA,OAAO,EAA+B,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAOnE,OAAO,EAAc,KAAK,SAAS,EAAE,MAAM,WAAW,CAAA;AAEtD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAA;AAE7D;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,WAAW,GAAG,QAAQ,GAAG,MAAM,CAAA;AAEpE,8CAA8C;AAC9C,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,WAAW,CAAA;IACjB,6CAA6C;IAC7C,KAAK,EAAE,MAAM,CAAA;IACb,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,oEAAoE;IACpE,IAAI,EAAE,QAAQ,CAAA;CACf,CAAA;AAED,qEAAqE;AACrE,MAAM,MAAM,mBAAmB,GAAG;IAChC,IAAI,EAAE,UAAU,CAAA;IAChB,uFAAuF;IACvF,KAAK,EAAE,MAAM,CAAA;IACb,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAA;IACZ,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,IAAI,EAAE,YAAY,CAAA;IAClB,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAA;IACZ,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,iEAAiE;IACjE,OAAO,CAAC,EAAE,SAAS,CAAA;CACpB,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GACnB,eAAe,GACf,oBAAoB,GACpB,eAAe,GACf,mBAAmB,GACnB,qBAAqB,CAAA;AAEzB;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,2EAA2E;IAC3E,EAAE,EAAE,MAAM,CAAA;IACV,wCAAwC;IACxC,MAAM,EAAE,aAAa,CAAA;IACrB,2FAA2F;IAC3F,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,0CAA0C;IAC1C,EAAE,EAAE,MAAM,CAAA;IACV;;;;;;;;;;;;;OAaG;IACH,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,4EAA4E;IAC5E,KAAK,EAAE,SAAS,WAAW,EAAE,CAAA;CAC9B,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI,KAAK,MAAM,IAAI,CAAA;AAEnF,MAAM,MAAM,oBAAoB,GAAG;IACjC;;;;OAIG;IACH,SAAS,EAAE,gBAAgB,CAAA;IAC3B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,EAAE,SAAS,WAAW,EAAE,CAAA;IAChC;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IAChC,wEAAwE;IACxE,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,mFAAmF;IACnF,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,8CAA8C;IAC9C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;;;;OAOG;IACH,aAAa,EAAE,MAAM,CAAA;IACrB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,oFAAoF;IACpF,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,mFAAmF;IACnF,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,GAAG,CACA;IAAE,YAAY,CAAC,EAAE,KAAK,CAAC;IAAC,UAAU,CAAC,EAAE,KAAK,CAAC;IAAC,WAAW,CAAC,EAAE,KAAK,CAAA;CAAE,GACjE;IAAE,YAAY,EAAE,IAAI,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAClE,CAAA;AAiED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4EG;AACH,wBAAgB,eAAe,CAAC,EAC9B,SAAS,EACT,OAAO,EACP,cAAc,EACd,MAAM,EACN,WAAW,EACX,OAAO,EACP,KAAK,EACL,WAAW,EACX,UAAU,EACV,aAAa,EACb,SAAS,EACT,KAAW,EACX,MAAM,EACN,YAAY,EACZ,UAAU,EACV,WAAW,EACX,SAAS,GACV,EAAE,oBAAoB,+BA4KtB;AA+DD,eAAe,eAAe,CAAA"}

package/dist/live/message-thread-01/message-thread.js

@@ -0,0 +1,221 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from 'react';
+import { Button } from '../../components/ui/button.js';
+import { LiveRegion } from '../../components/ui/live-region.js';
+import { ScrollArea } from '../../components/ui/scroll-area.js';
+import { headingSizeClass } from '../../components/ui/section.js';
+import { cn } from '../../lib/utils.js';
+import { STATUS_INK } from '../status.js';
+import { ToolCallRow } from '../tool-call-row.js';
+/** The ink each sender is stated in. */
+const SENDER_INK = {
+    user: 'text-foreground',
+    assistant: 'text-foreground',
+    system: 'text-muted-foreground',
+    tool: 'text-muted-foreground',
+};
+/** The mark each sender draws, so the four are told apart without relying on colour. */
+const SENDER_MARK = {
+    user: 'u',
+    assistant: 'a',
+    system: 's',
+    tool: 't',
+};
+/** The clock a message reads, in UTC, because the surface holds no locale to format in. */
+const clockOf = (at) => new Date(at).toISOString().slice(11, 19);
+/** The one source of truth for order, so a late message with an earlier `at` sorts there. */
+const byTimeThenId = (a, b) => a.at - b.at || a.id.localeCompare(b.id);
+/** The seed a thread opens with, already sorted and trimmed to the window. */
+function seedOf(messages, limit) {
+    const sorted = [...messages].sort(byTimeThenId);
+    return sorted.length > limit ? sorted.slice(sorted.length - limit) : sorted;
+}
+/** One message merged into the thread, and the window applied. */
+function merge(messages, message, limit) {
+    const at = messages.findIndex((current) => current.id === message.id);
+    const next = at === -1
+        ? [...messages, message]
+        : messages.map((current, index) => (index === at ? message : current));
+    next.sort(byTimeThenId);
+    return next.length > limit ? next.slice(next.length - limit) : next;
+}
+/**
+ * The one line the live region announces for an arriving message.
+ *
+ * The region carries a single short string rather than the message, because a live
+ * region around a growing list makes a screen reader read the whole thread again
+ * on every arrival. The string is the message's own first readable part, in the
+ * consumer's words: the first text, reasoning, tool name, citation or attachment
+ * name it carries.
+ */
+function announcementOf(message) {
+    for (const part of message.parts) {
+        if (part.kind === 'text' || part.kind === 'reasoning')
+            return part.text;
+        if (part.kind === 'tool')
+            return part.call.name;
+        if (part.kind === 'citation')
+            return part.label;
+        if (part.kind === 'attachment')
+            return part.name;
+    }
+    return undefined;
+}
+/**
+ * The message thread of a conversation, receiving messages as they arrive.
+ *
+ * **This is the `live` Kind's second family, and it is the second client surface in
+ * the package beside `RunStream01`.** A conversation's content changes over time
+ * without a navigation event, which is the definition of the Kind, and a chat that
+ * cannot stream is not a chat. So this surface owns a subscription and the bounded
+ * window behind it, exactly as the run log does.
+ *
+ * **Prism owns the surface, the consumer owns the transport.** `subscribe` is a
+ * function the consumer supplies and a function it tears down. There is no socket
+ * in this file, no endpoint, no retry policy, no persistence and no provider to
+ * mount, so a WebSocket, an `EventSource`, a polling timer and a test's own array
+ * are all the same shape to this surface. A consumer that already has a connection
+ * passes it in, and one that does not has not acquired a client runtime by
+ * importing this.
+ *
+ * **The content is a message list with ordered parts, and neither an event list nor
+ * a turn list is taken.** A message is an artifact a reader reads and addresses,
+ * where an occurrence is not, so the run's flat `RunEvent` stays the run log's own
+ * vocabulary. A turn is a derived grouping of a request and its answers, the
+ * transport does not preserve it as a unit, and the order of a stream after a
+ * reconnect is unsettled, so a surface that grouped by turn would impose a
+ * structure the consumer's data may not have. The message and part vocabulary lives
+ * here, beside `RunEvent` and `ToolCall`, and is deliberately not a member of the
+ * shared specification module.
+ *
+ * **Per-message metadata is the caller's own node.** The model a provider stated
+ * for a turn, a token count it reported, and the cost and the latency a consumer
+ * derived are metadata about a message rather than content a reader reads as it, so
+ * a message carries an optional `meta` the surface draws in its header beside the
+ * sender and the time. It is a node, and deliberately not a set of Prism fields:
+ * cost and latency are the consumer's own derivation, because no provider read
+ * publishes either, so the surface draws what it was handed and states no figure
+ * for itself. This is the `ItemEntry.meta` shape read at the message.
+ *
+ * **The four things the Kind already names are reused rather than answered twice.**
+ * A tool-call part is drawn through `ToolLedger01`'s own row, so there is no second
+ * tool-call shape. The status tiers are the ones `RunStatus` already publishes. The
+ * run controls are `PromptComposer`'s send, stop, retry and attach, which the
+ * consumer composes beside this surface rather than this surface drawing a second
+ * set of them. The one surface it does not reuse is `RunStream01`, because a run's
+ * log is a sequence of occurrences and a conversation is a sequence of messages.
+ *
+ * **The surface draws no control it cannot act on.** The only control in it is the
+ * pause control, which pauses this surface and never the run, and which a consumer
+ * opts into with `pauseControl`. Send, stop, retry and attach are not here: they are
+ * `PromptComposer`'s, and a settled thread composed outside the live module reaches
+ * a decision through a `CtaLink` with its required `href` or a slot the consumer
+ * fills.
+ *
+ * **Prism holds a bounded in-memory window and promises no resumption.** The
+ * durable buffer that outlives a mount is the consumer's, because Prism ships no
+ * permanent client runtime and cannot assume a server framework. The seam is
+ * `initial` and `resubscribeKey`: a surface opened mid-thread is seeded from the
+ * consumer's own record, a reconnect is a new key over a fresh seed, and the
+ * surface promises no resumption so it cannot fail to keep one.
+ *
+ * **Messages are kept sorted by `at`, not by arrival.** A transport decides when a
+ * message is delivered, and a reconnect can deliver an older message after a newer
+ * one. Ties break on `id`, so the order is total and the same thread renders the
+ * same way every time. The same `id` is also the same message, so a transport that
+ * reports it again as more parts arrive updates one message rather than adding a
+ * second.
+ *
+ * **New messages are announced once, politely, and the thread itself is not a live
+ * region.** Announcing a growing list would make a screen reader read the whole
+ * thread again on every arrival, which is the failure a live region on a list
+ * guarantees. `LiveRegion` carries the newest message's first readable part alone,
+ * and the thread is an ordinary scrollable list a reader moves through at their own
+ * pace.
+ *
+ * `limit` bounds what is held, because a long conversation produces thousands of
+ * messages and a surface that grows without bound eventually stops repainting.
+ * Older messages fall off the top, which is the direction a reader wants: the
+ * thread's beginning is the part they can scroll back to in the consumer's store.
+ */
+export function MessageThread01({ subscribe, initial, resubscribeKey, status, statusLabel, eyebrow, title, description, emptyLabel, messagesLabel, liveLabel, limit = 200, paused, pauseControl, pauseLabel, resumeLabel, className, }) {
+    /**
+     * The thread, held against the key that produced it.
+     *
+     * Adjusting state during render when the key changes is React's documented
+     * pattern for "a prop changed, start over", and it is the right one here: the
+     * alternative is an effect, and an effect that clears the thread runs *after* a
+     * render, so the surface would paint one frame holding the previous thread's
+     * messages under the new thread's heading.
+     */
+    const [newest, setNewest] = useState(undefined);
+    const [thread, setThread] = useState(() => ({
+        key: resubscribeKey,
+        messages: seedOf(initial ?? [], limit),
+    }));
+    if (thread.key !== resubscribeKey) {
+        setThread({ key: resubscribeKey, messages: seedOf(initial ?? [], limit) });
+        // The announcement is cleared with the thread it announced, so a thread switch
+        // does not leave the previous thread's last message in the live region saying so.
+        setNewest(undefined);
+    }
+    const messages = thread.messages;
+    /**
+     * Whether this surface is holding still, kept in a ref as well as in state.
+     *
+     * The ref is what the arrival path reads, and it is why the subscription effect
+     * does not list the pause among its dependencies: an effect that depended on the
+     * pause would tear the consumer's connection down and open a new one every time a
+     * reader pressed the control. The button writes both, so the value the effect
+     * reads is the value the reader set.
+     */
+    const [held, setHeldState] = useState(paused === true);
+    const heldRef = useRef(held);
+    const setHeld = (next) => {
+        heldRef.current = next;
+        setHeldState(next);
+    };
+    // A ref rather than state, so the effect does not re-subscribe because a message
+    // arrived. An effect that depended on the value it writes re-runs itself, and the
+    // surface would open a new subscription per message.
+    const emit = useRef(() => { });
+    useEffect(() => {
+        emit.current = (message) => {
+            // Read through the ref, so a paused surface decides without re-subscribing.
+            if (heldRef.current)
+                return;
+            setThread((current) => ({
+                ...current,
+                messages: merge(current.messages, message, limit),
+            }));
+            setNewest(announcementOf(message));
+        };
+        const stop = subscribe(emit.current);
+        return () => {
+            // Calling an unsubscribe the consumer did not return would throw during
+            // unmount, so a missing one is stepped over and the leak is the consumer's to
+            // fix rather than a crash in someone else's teardown.
+            if (typeof stop === 'function')
+                stop();
+        };
+    }, [subscribe, resubscribeKey, limit]);
+    return (_jsxs("section", { "data-slot": "message-thread", className: cn('border-border flex flex-col gap-4 rounded-lg border p-4', className), children: [LiveRegion({ politeness: 'polite', label: liveLabel, children: newest }), title !== undefined || eyebrow !== undefined || description !== undefined ? (_jsxs("header", { className: "flex flex-col gap-1", children: [eyebrow ? (_jsx("span", { className: "text-muted-foreground text-xs font-medium tracking-wide uppercase", children: eyebrow })) : null, title ? (_jsx("h2", { className: cn('font-semibold tracking-tight text-balance', headingSizeClass('h2')), children: title })) : null, description ? (_jsx("p", { className: "text-muted-foreground text-pretty text-sm", children: description })) : null] })) : null, status !== undefined ? (_jsx("p", { "data-slot": "thread-status", className: cn('font-mono text-xs', STATUS_INK[status]), children: statusLabel })) : null, pauseControl === true ? (_jsx("div", { "data-slot": "thread-bar", className: "flex flex-wrap items-center gap-3", children: _jsx(Button, { "data-slot": "thread-pause", type: "button", variant: "outline", size: "sm", "aria-pressed": held, className: "ml-auto", onClick: () => setHeld(!heldRef.current), children: held ? resumeLabel : pauseLabel }) })) : null, messages.length === 0 ? (_jsx("p", { "data-slot": "message-thread-empty", className: "text-muted-foreground text-sm", children: emptyLabel })) : (_jsx(ScrollArea, { label: messagesLabel, className: "max-h-96", children: _jsx("ol", { "data-slot": "thread-messages", className: "flex flex-col gap-4", children: messages.map((message) => (_jsxs("li", { "data-slot": "thread-message", "data-sender": message.sender, className: "flex flex-col gap-2", children: [_jsxs("div", { className: "flex items-baseline gap-x-2", children: [_jsx("span", { "aria-hidden": "true", className: cn('font-mono text-xs', SENDER_INK[message.sender]), children: SENDER_MARK[message.sender] }), message.senderLabel ? (_jsx("span", { className: "text-foreground text-xs font-medium", children: message.senderLabel })) : null, _jsx("time", { dateTime: new Date(message.at).toISOString(), className: "text-muted-foreground font-mono text-xs tabular-nums", children: clockOf(message.at) }), message.meta === undefined ? null : (_jsx("span", { "data-slot": "thread-message-meta", className: "text-muted-foreground text-xs", children: message.meta }))] }), _jsx("ol", { "data-slot": "message-parts", className: "flex flex-col gap-2", children: message.parts.map((part, index) => (_jsx("li", { "data-slot": "message-part", "data-kind": part.kind, className: "text-sm", children: renderPart(part) }, `${message.id}-${index}`))) })] }, message.id))) }) }))] }));
+}
+/** One part, drawn by its kind. */
+function renderPart(part) {
+    if (part.kind === 'text') {
+        return _jsx("p", { className: "text-foreground text-pretty text-sm", children: part.text });
+    }
+    if (part.kind === 'reasoning') {
+        return (_jsxs("details", { "data-slot": "message-reasoning", className: "text-muted-foreground text-sm", children: [_jsx("summary", { className: "cursor-pointer text-xs font-medium", children: part.label }), _jsx("p", { className: "text-muted-foreground text-pretty text-sm", children: part.text })] }));
+    }
+    if (part.kind === 'tool') {
+        return (_jsx("div", { className: "border-border flex flex-col gap-1 rounded-md border p-2", children: _jsx(ToolCallRow, { call: part.call, openedAt: part.call.at }) }));
+    }
+    if (part.kind === 'citation') {
+        return (_jsxs("span", { className: "flex flex-col gap-0.5", children: [_jsx("a", { "data-slot": "message-citation", href: part.href, className: "text-foreground self-start rounded-sm text-sm underline-offset-4 hover:underline", children: part.label }), part.detail ? (_jsx("span", { className: "text-muted-foreground text-pretty text-xs", children: part.detail })) : null] }));
+    }
+    return (_jsxs("span", { "data-slot": "message-attachment", className: "border-border flex flex-col gap-1 rounded-md border p-2", children: [part.preview ? _jsx("span", { className: "block", children: part.preview }) : null, part.href ? (_jsx("a", { "data-slot": "message-attachment-link", href: part.href, className: "text-foreground self-start rounded-sm text-sm underline-offset-4 hover:underline", children: part.name })) : (_jsx("span", { className: "text-foreground text-sm", children: part.name }))] }));
+}
+export default MessageThread01;

package/dist/live/run-stream-01/run-stream.d.ts

@@ -1,3 +1,4 @@
+import { type RunStatus } from '../status.js';
 /**
  * Who produced an event, as a closed set.
  *
@@ -21,7 +22,7 @@ export type RunEvent = {
     detail?: string;
 };
 /** Where a run has got to. The tiers are Prism's; the words beside them are the caller's. */
-export type RunStatus = 'queued' | 'running' | 'waiting' | 'done' | 'failed';
+export type { RunStatus };
 /**
  * How the surface receives events.
  *

package/dist/live/run-stream-01/run-stream.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-stream.d.ts","sourceRoot":"","sources":["../../../src/live/run-stream-01/run-stream.tsx"],"names":[],"mappings":"AASA;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAA;AAEhE,6CAA6C;AAC7C,MAAM,MAAM,QAAQ,GAAG;IACrB,2FAA2F;IAC3F,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,YAAY,CAAA;IAClB,qEAAqE;IACrE,EAAE,EAAE,MAAM,CAAA;IACV,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAA;IACf,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,6FAA6F;AAC7F,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,CAAA;AAE5E;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,KAAK,MAAM,IAAI,CAAA;AAE1E,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;;;OAIG;IACH,SAAS,EAAE,YAAY,CAAA;IACvB;;;;;;;;;OASG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IAChC;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAA;IAC7B,gCAAgC;IAChC,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,mFAAmF;IACnF,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,8CAA8C;IAC9C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;;;;OAOG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AA8BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,WAAW,CAAC,EAC1B,SAAS,EACT,cAAc,EACd,OAAO,EACP,MAAM,EACN,WAAW,EACX,OAAO,EACP,KAAK,EACL,WAAW,EACX,UAAU,EACV,WAAW,EACX,SAAS,EACT,KAAW,EACX,SAAS,GACV,EAAE,gBAAgB,+BA0IlB;AAED,eAAe,WAAW,CAAA"}
+{"version":3,"file":"run-stream.d.ts","sourceRoot":"","sources":["../../../src/live/run-stream-01/run-stream.tsx"],"names":[],"mappings":"AAQA,OAAO,EAAc,KAAK,SAAS,EAAE,MAAM,WAAW,CAAA;AAEtD;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAA;AAEhE,6CAA6C;AAC7C,MAAM,MAAM,QAAQ,GAAG;IACrB,2FAA2F;IAC3F,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,YAAY,CAAA;IAClB,qEAAqE;IACrE,EAAE,EAAE,MAAM,CAAA;IACV,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAA;IACf,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,6FAA6F;AAC7F,YAAY,EAAE,SAAS,EAAE,CAAA;AAEzB;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,KAAK,MAAM,IAAI,CAAA;AAE1E,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;;;OAIG;IACH,SAAS,EAAE,YAAY,CAAA;IACvB;;;;;;;;;OASG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IAChC;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAA;IAC7B,gCAAgC;IAChC,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,mFAAmF;IACnF,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,8CAA8C;IAC9C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;;;;OAOG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAsBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,WAAW,CAAC,EAC1B,SAAS,EACT,cAAc,EACd,OAAO,EACP,MAAM,EACN,WAAW,EACX,OAAO,EACP,KAAK,EACL,WAAW,EACX,UAAU,EACV,WAAW,EACX,SAAS,EACT,KAAW,EACX,SAAS,GACV,EAAE,gBAAgB,+BA0IlB;AAED,eAAe,WAAW,CAAA"}

package/dist/live/run-stream-01/run-stream.js

@@ -5,6 +5,7 @@ import { LiveRegion } from '../../components/ui/live-region.js';
 import { ScrollArea } from '../../components/ui/scroll-area.js';
 import { headingSizeClass } from '../../components/ui/section.js';
 import { cn } from '../../lib/utils.js';
+import { STATUS_INK } from '../status.js';
 /** The ink each role is stated in, and the tick beside it. */
 const ROLE_INK = {
     agent: 'text-foreground',
@@ -19,13 +20,6 @@ const ROLE_MARK = {
     system: '·',
     error: '×',
 };
-const STATUS_INK = {
-    queued: 'text-muted-foreground',
-    running: 'text-foreground',
-    waiting: 'text-warning',
-    done: 'text-success',
-    failed: 'text-destructive',
-};
 /** The one source of truth for order, so a late event with an earlier `at` sorts there. */
 const byTimeThenId = (a, b) => a.at - b.at || a.id.localeCompare(b.id);
 /**

package/dist/live/status.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Where a live surface has got to, as the Kind's one closed set of tiers.
+ *
+ * A run and a conversation are two families of the same Kind, and a reader
+ * watching either one asks the same question: is this queued, running, waiting,
+ * done or failed. The tiers are therefore declared once, here, and every live
+ * surface draws its state from them rather than minting a vocabulary of its own.
+ * A second status word invented for a conversation would be a second answer to a
+ * question this set already answers, and two answers that agree today are a
+ * catalogue drifting a second list.
+ *
+ * The **words** beside a tier are still the consumer's: Prism owns which tier
+ * looks like what, and ships none of the labels. The ink below is the whole of
+ * what the Kind states about a tier, and it is stated once so the run log and the
+ * message thread cannot disagree about what a failure looks like.
+ */
+export type RunStatus = 'queued' | 'running' | 'waiting' | 'done' | 'failed';
+/**
+ * The ink each tier is stated in.
+ *
+ * The five roles are the ones an agent surface actually reports, and the ink is
+ * the one Prism-owned visual fact about a tier. `waiting` and `failed` are the
+ * two that carry a colour a reader acts on, which is why they are the two that
+ * are not the foreground or the muted ink.
+ */
+export declare const STATUS_INK: Record<RunStatus, string>;
+//# sourceMappingURL=status.d.ts.map

package/dist/live/status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../src/live/status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,CAAA;AAE5E;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAMhD,CAAA"}

package/dist/live/status.js

@@ -0,0 +1,15 @@
+/**
+ * The ink each tier is stated in.
+ *
+ * The five roles are the ones an agent surface actually reports, and the ink is
+ * the one Prism-owned visual fact about a tier. `waiting` and `failed` are the
+ * two that carry a colour a reader acts on, which is why they are the two that
+ * are not the foreground or the muted ink.
+ */
+export const STATUS_INK = {
+    queued: 'text-muted-foreground',
+    running: 'text-foreground',
+    waiting: 'text-warning',
+    done: 'text-success',
+    failed: 'text-destructive',
+};

package/dist/live/tool-call-row.d.ts

@@ -0,0 +1,26 @@
+import type { ToolCall } from './tool-ledger-01/tool-ledger.js';
+/** The clock a row reads, in UTC, because the surface holds no locale to format in. */
+export declare const clockOf: (at: number) => string;
+/**
+ * One tool call, drawn as the ledger draws it.
+ *
+ * **This is the tool-call row the `live` Kind owns, and it is shared rather than
+ * copied.** `ToolLedger01` draws one row per call in its ledger, and a
+ * conversation's tool-call part draws the same row inside a message, so the two
+ * surfaces cannot drift into two shapes for one call. `ToolLedger01` renders this
+ * inside its own `<li>`; the message thread renders it inside a part. The
+ * Component owns no `<li>`, so it can sit in either list without nesting one.
+ *
+ * **The duration is the difference between two sightings of the same call, and
+ * only when there are two.** `openedAt` is the moment the surface first saw the
+ * call's `id`; a call seen once has no second timestamp and draws no duration,
+ * because a zero is a claim that a call took no time. The sentence is the
+ * consumer's, on `call.durationLabel`, and the arithmetic is one subtraction of
+ * the consumer's own `at` values. There is no clock in this file.
+ */
+export declare function ToolCallRow({ call, openedAt }: {
+    call: ToolCall;
+    openedAt: number;
+}): import("react").JSX.Element;
+export default ToolCallRow;
+//# sourceMappingURL=tool-call-row.d.ts.map

package/dist/live/tool-call-row.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-call-row.d.ts","sourceRoot":"","sources":["../../src/live/tool-call-row.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAiB,MAAM,8BAA8B,CAAA;AAgC3E,uFAAuF;AACvF,eAAO,MAAM,OAAO,GAAI,IAAI,MAAM,KAAG,MAAkD,CAAA;AAEvF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,+BAqFnF;AAED,eAAe,WAAW,CAAA"}