@spexcode/transcript-ui 0.7.0-next.1

package/dist/LiveTail.d.ts

@@ -0,0 +1,7 @@
+import { type AnyTurn } from './segments.js';
+export declare function LiveTail({ turns, lastSaid, revision, className }: {
+    turns: readonly AnyTurn[] | null | undefined;
+    lastSaid?: string | null;
+    revision?: string;
+    className?: string;
+}): import("react").JSX.Element | null;

package/dist/LiveTail.js

@@ -0,0 +1,26 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useMemo } from 'react';
+import { alreadySaid, isRunning, liveSlice } from './segments.js';
+import { TranscriptTurns } from './TranscriptView.js';
+import { useDisclosure } from './useDisclosure.js';
+// THE OPEN INTERVAL'S COLLAPSED FACE: the current turn — the newest prose and every call after it — drawn in
+// the transcript's own grammar from the same merged payload the expanded view renders in full. `lastSaid` is
+// what the host's own record already shows (a declared note); the tail elides the prose that repeats it. The
+// caret marks words still being said: it sits at the end of the newest prose only while that prose is the
+// newest thing in the turn — once a call follows, the words are finished and the running call is the mark.
+export function LiveTail({ turns, lastSaid = null, revision, className = '' }) {
+    const [openIds, toggle] = useDisclosure();
+    const slice = useMemo(() => (turns ? liveSlice(turns) : []), [turns]);
+    if (!slice.length)
+        return null;
+    const repeated = alreadySaid(slice[0].text, lastSaid);
+    const running = slice.some((turn) => (turn.tools || []).some((tool) => isRunning(tool, true)));
+    if (repeated && !running)
+        return null;
+    const shown = repeated ? [{ ...slice[0], text: undefined }, ...slice.slice(1)] : slice;
+    if (!shown.some((turn) => turn.text || turn.tools?.length))
+        return null;
+    const last = shown[shown.length - 1];
+    const speaking = !!last.text && !last.tools?.length;
+    return (_jsx("div", { className: `tx tx-live${speaking ? ' is-speaking' : ''}${className ? ` ${className}` : ''}`, "data-revision": revision, children: _jsx(TranscriptTurns, { turns: shown, openIds: openIds, onToggle: toggle, live: true }) }));
+}

package/dist/Quote.d.ts

@@ -0,0 +1,6 @@
+export declare function Quote({ who, ts, text, className }: {
+    who?: string | null;
+    ts?: number | string | null;
+    text: string;
+    className?: string;
+}): import("react").JSX.Element;

package/dist/Quote.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import { useTranscriptUi } from './context.js';
+import { timeOf } from './vocabulary.js';
+// A long quote is clamped at first sight — the conversation is about what came after it. The trigger is the
+// text itself rather than a measured height, so the row never reflows after paint.
+const isLongQuote = (text) => text.length > 700 || (text.match(/\n/g) || []).length > 10;
+// THE PERSON IS QUOTED: a bubble off to its own side, with one corner squared. The name sits on the bubble
+// when the host knows it; the time shows only in a narrow pane, where there is no ruler beside the flow.
+export function Quote({ who = null, ts = null, text, className = '' }) {
+    const { renderText, labels } = useTranscriptUi();
+    const [open, setOpen] = useState(false);
+    const clamped = !open && isLongQuote(text);
+    return (_jsxs("div", { className: `tx tx-quote${clamped ? ' is-clamped' : ''}${className ? ` ${className}` : ''}`, children: [(who || ts) && (_jsxs("div", { className: "tx-quote-head", children: [who && _jsx("span", { className: "tx-quote-who", children: who }), ts != null && _jsx("time", { className: "tx-time", children: timeOf(ts) })] })), _jsx("div", { className: "tx-quote-text", children: renderText(text) }), clamped && _jsx("button", { type: "button", className: "tx-quote-more", onClick: () => setOpen(true), children: labels.more })] }));
+}

package/dist/ToolLine.d.ts

@@ -0,0 +1,14 @@
+import { type AnyTool } from './vocabulary.js';
+export declare function ToolLine({ tool, open, onToggle, live }: {
+    tool: AnyTool;
+    open: boolean;
+    onToggle: () => void;
+    live?: boolean;
+}): import("react").JSX.Element;
+export declare function ToolRun({ tools, openIds, onToggle, live, fold }: {
+    tools?: readonly AnyTool[];
+    openIds: ReadonlySet<string>;
+    onToggle: (id: string) => void;
+    live?: boolean;
+    fold?: boolean;
+}): import("react").JSX.Element | null;

package/dist/ToolLine.js

@@ -0,0 +1,62 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useState } from 'react';
+import { useTranscriptUi } from './context.js';
+import { Caret, Spinner } from './icons.js';
+import { isRunning } from './segments.js';
+import { runKinds, splitTarget, toolTarget, toolVerb } from './vocabulary.js';
+// A LIVE FRAME WITHHOLDS OUTPUT BODIES: a recorded result is `null` on the wire, its size told, and the body
+// is fetched once when a person opens the call, through the host's loader.
+function WithheldOutput({ tool }) {
+    const { loadToolOutput, labels } = useTranscriptUi();
+    const [fetched, setFetched] = useState(null);
+    useEffect(() => {
+        if (!loadToolOutput)
+            return undefined;
+        let live = true;
+        loadToolOutput(tool.id).then((result) => { if (live)
+            setFetched(result); }, (error) => { if (live)
+            setFetched({ ok: false, error: String(error?.message || error) }); });
+        return () => { live = false; };
+    }, [loadToolOutput, tool.id]);
+    if (!loadToolOutput)
+        return null;
+    if (!fetched)
+        return _jsx("div", { className: "tx-tool-out tx-tool-out-state", children: labels.loading });
+    if (!fetched.ok)
+        return _jsx("div", { className: "tx-tool-out tx-tool-out-state is-error", children: fetched.error });
+    return _jsx("pre", { className: "tx-tool-out", children: fetched.output ?? '' });
+}
+// One tool call as a SENTENCE, not a card: verb, target, and the size of what came back. It is
+// `inline-flex` so a dozen of them read as a list of things that happened rather than a dozen boxes. There
+// is no success mark, because the transcript carries no per-tool status — the past-tense verb is the whole
+// claim. A running call wears a small spinner and the word.
+export function ToolLine({ tool, open, onToggle, live = false }) {
+    const { labels, vocabulary } = useTranscriptUi();
+    const target = toolTarget(tool.input, vocabulary);
+    const { lead, trail } = splitTarget(target);
+    const lines = tool.outputLines || 0;
+    const withheld = tool.output === null;
+    const canOpen = !!tool.input || tool.output !== undefined || withheld;
+    const running = isRunning(tool, live);
+    const row = (_jsxs(_Fragment, { children: [_jsx("span", { className: "tx-tool-verb", children: toolVerb(tool.name, vocabulary) }), lead && _jsx("span", { className: "tx-tool-target", children: lead }), trail && _jsx("span", { className: "tx-tool-trail", children: trail }), lines > 0 && _jsx("span", { className: "tx-tool-size", children: labels.lines(lines) }), running && _jsxs("span", { className: "tx-tool-running", children: [_jsx(Spinner, {}), labels.running] }), canOpen && _jsx(Caret, { open: open, className: "tx-tool-caret" })] }));
+    return (_jsxs("div", { className: `tx-tool${running ? ' is-running' : ''}`, children: [canOpen
+                ? _jsx("button", { type: "button", onClick: onToggle, "aria-expanded": open, className: "tx-tool-row is-openable", children: row })
+                : _jsx("div", { className: "tx-tool-row", children: row }), open && canOpen && _jsxs(_Fragment, { children: [tool.input && _jsx("pre", { className: "tx-tool-in", children: tool.input }), withheld
+                        ? _jsx(WithheldOutput, { tool: tool })
+                        : tool.output !== undefined && _jsx("pre", { className: "tx-tool-out", children: tool.output })] })] }));
+}
+// A turn's tool calls are consecutive by construction, so "a run" is just "this turn's calls". `runMin` or
+// more fold to one row; fewer stay sentences, where the verb and target are worth reading on sight. `fold`
+// is off for the work in progress: calls still landing are sentences whatever their number.
+export function ToolRun({ tools, openIds, onToggle, live = false, fold = true }) {
+    const { labels, vocabulary, runMin, fold: policy } = useTranscriptUi();
+    if (!tools?.length)
+        return null;
+    const line = (tool) => _jsx(ToolLine, { tool: tool, open: openIds.has(tool.id), onToggle: () => onToggle(tool.id), live: live }, tool.id);
+    if (!fold || policy === 'none' || tools.length < runMin)
+        return _jsx("div", { className: "tx-tools", children: tools.map(line) });
+    const id = `run:${tools[0].id}`;
+    const open = openIds.has(id);
+    const running = tools.some((tool) => isRunning(tool, live));
+    return _jsx("div", { className: "tx-tools", children: _jsxs("div", { className: `tx-tool${running ? ' is-running' : ''}`, children: [_jsxs("button", { type: "button", className: "tx-tool-row is-openable is-run", "aria-expanded": open, onClick: () => onToggle(id), children: [_jsx("span", { className: "tx-tool-verb", children: labels.toolUses(tools.length) }), _jsx("span", { className: "tx-tool-trail", children: runKinds(tools, vocabulary) }), _jsx(Caret, { open: open, className: "tx-tool-caret" })] }), open && _jsx("div", { className: "tx-tool-kids", children: tools.map(line) })] }) });
+}

package/dist/TranscriptView.d.ts

@@ -0,0 +1,35 @@
+import { type AnyTurn, type Segment, type WorkSegment as Work } from './segments.js';
+type Disclosure = {
+    openIds: ReadonlySet<string>;
+    onToggle: (id: string) => void;
+};
+export declare function TurnBody({ turn, openIds, onToggle, live, fold }: {
+    turn: AnyTurn;
+    live: boolean;
+    fold?: boolean;
+} & Disclosure): import("react").JSX.Element;
+export declare function WorkSegmentView({ segment, openIds, onToggle, live }: {
+    segment: Work;
+    live: boolean;
+} & Disclosure): import("react").JSX.Element;
+export declare function SegmentView({ segment, ...rest }: {
+    segment: Segment;
+    live: boolean;
+} & Disclosure): import("react").JSX.Element;
+export declare function TranscriptTurns({ turns, openIds, onToggle, live }: {
+    turns: readonly AnyTurn[];
+    live?: boolean;
+} & Disclosure): import("react").JSX.Element;
+export type TranscriptPayload = Readonly<{
+    turns: readonly AnyTurn[];
+    truncated?: boolean;
+    omittedTurns?: number;
+    omittedBytes?: number;
+    outOfOrderEvents?: number;
+}>;
+export declare function TranscriptView({ data, live, className }: {
+    data: TranscriptPayload | null | undefined;
+    live?: boolean;
+    className?: string;
+}): import("react").JSX.Element;
+export {};

package/dist/TranscriptView.js

@@ -0,0 +1,43 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useTranscriptUi } from './context.js';
+import { Caret } from './icons.js';
+import { Quote } from './Quote.js';
+import { segments } from './segments.js';
+import { ToolRun } from './ToolLine.js';
+import { useDisclosure } from './useDisclosure.js';
+import { runKinds } from './vocabulary.js';
+// the agent IS the page: full measure, no bubble, no tint
+export function TurnBody({ turn, openIds, onToggle, live, fold = true }) {
+    const { renderText } = useTranscriptUi();
+    return _jsxs("div", { className: "tx-say", children: [turn.text && _jsx("div", { className: "tx-say-text", children: renderText(turn.text) }), _jsx(ToolRun, { tools: turn.tools, openIds: openIds, onToggle: onToggle, live: live, fold: fold })] });
+}
+export function WorkSegmentView({ segment, openIds, onToggle, live }) {
+    const { labels, vocabulary } = useTranscriptUi();
+    const id = `seg:${segment.work[0]?.id || segment.answer?.id}`;
+    const open = openIds.has(id);
+    const kinds = runKinds(segment.work.flatMap((turn) => turn.tools ?? []), vocabulary);
+    const foldedCalls = segment.work.reduce((n, turn) => n + (turn.tools?.length || 0), 0);
+    // history folds its runs; the work in progress (a live segment's calls after its newest prose) does not
+    const history = !segment.now || !!segment.answer;
+    return _jsxs(_Fragment, { children: [segment.folded ? (_jsxs("div", { className: "tx-work", children: [_jsxs("button", { type: "button", className: "tx-work-row", "aria-expanded": open, onClick: () => onToggle(id), children: [_jsx("span", { className: "tx-work-lead", children: labels.toolUses(foldedCalls) }), kinds && _jsx("span", { className: "tx-work-detail", children: kinds }), _jsx(Caret, { open: open, className: "tx-work-caret" })] }), open && _jsx("div", { className: "tx-work-body", children: segment.work.map((turn) => _jsx(TurnBody, { turn: turn, openIds: openIds, onToggle: onToggle, live: live }, turn.id)) })] })) : segment.work.map((turn) => _jsx(TurnBody, { turn: turn, openIds: openIds, onToggle: onToggle, live: live, fold: history }, turn.id)), segment.answer && _jsx(TurnBody, { turn: segment.answer, openIds: openIds, onToggle: onToggle, live: live, fold: !segment.now }), segment.after.map((turn) => _jsx(TurnBody, { turn: turn, openIds: openIds, onToggle: onToggle, live: live, fold: !segment.now }, turn.id))] });
+}
+export function SegmentView({ segment, ...rest }) {
+    if (segment.kind === 'quote')
+        return _jsx(Quote, { ts: segment.turn.at, text: segment.turn.text || '', className: "tx-quote-nested" });
+    return _jsx(WorkSegmentView, { segment: segment, ...rest });
+}
+// THE TURNS, in the grammar: quotes where the host wants them, work segments folded behind their answers
+export function TranscriptTurns({ turns, openIds, onToggle, live = false }) {
+    const { fold, runMin, userTurns } = useTranscriptUi();
+    return _jsx(_Fragment, { children: segments(turns, { live, fold, runMin, userTurns }).map((segment, index) => _jsx(SegmentView, { segment: segment, openIds: openIds, onToggle: onToggle, live: live }, segment.kind === 'quote' ? `q:${segment.turn.id}` : `w:${segment.work[0]?.id ?? segment.answer?.id ?? index}`)) });
+}
+// THE WHOLE PAYLOAD: one interval's turns, the same shape a closed read returns and a merged live stream
+// holds, so one renderer draws history and the tail alike. `live` adds exactly one truth — a call without a
+// recorded result is still running — and keeps the work in progress unfolded.
+export function TranscriptView({ data, live = false, className = '' }) {
+    const { labels } = useTranscriptUi();
+    const [openIds, toggle] = useDisclosure();
+    if (!data?.turns?.length)
+        return _jsx("div", { className: `tx tx-empty${className ? ` ${className}` : ''}`, children: labels.empty });
+    return _jsxs("div", { className: `tx tx-flow${className ? ` ${className}` : ''}`, children: [_jsx(TranscriptTurns, { turns: data.turns, openIds: openIds, onToggle: toggle, live: live }), data.truncated && _jsx("div", { className: "tx-truncated", children: labels.truncated({ omittedTurns: data.omittedTurns || 0, omittedBytes: data.omittedBytes || 0, outOfOrderEvents: data.outOfOrderEvents || 0 }) })] });
+}

package/dist/context.d.ts

@@ -0,0 +1,41 @@
+import { type ReactNode } from 'react';
+import { type Vocabulary } from './vocabulary.js';
+import type { FoldPolicy, UserTurnPolicy } from './segments.js';
+export type ToolOutputResult = {
+    ok: true;
+    output: string | null;
+} | {
+    ok: false;
+    error: string;
+};
+export type Labels = Readonly<{
+    loading: string;
+    running: string;
+    more: string;
+    toolUses: (n: number) => string;
+    lines: (n: number) => string;
+    empty: string;
+    truncated: (info: {
+        omittedTurns: number;
+        omittedBytes: number;
+        outOfOrderEvents: number;
+    }) => string;
+}>;
+export declare const defaultLabels: Labels;
+export type TranscriptUiOptions = Readonly<{
+    renderText: (text: string) => ReactNode;
+    loadToolOutput: ((toolId: string) => Promise<ToolOutputResult>) | null;
+    labels: Labels;
+    vocabulary: Vocabulary;
+    fold: FoldPolicy;
+    runMin: number;
+    userTurns: UserTurnPolicy;
+}>;
+export declare function PlainText({ text }: {
+    text: string;
+}): import("react").JSX.Element;
+export declare const defaultOptions: TranscriptUiOptions;
+export declare const useTranscriptUi: () => TranscriptUiOptions;
+export declare function TranscriptUi({ children, ...overrides }: Partial<TranscriptUiOptions> & {
+    children: ReactNode;
+}): import("react").JSX.Element;

package/dist/context.js

@@ -0,0 +1,33 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from 'react';
+import { defaultVocabulary } from './vocabulary.js';
+export const defaultLabels = {
+    loading: 'loading…',
+    running: 'running',
+    more: 'more',
+    toolUses: (n) => `${n} tool use${n === 1 ? '' : 's'}`,
+    lines: (n) => `${n} line${n === 1 ? '' : 's'}`,
+    empty: 'nothing in this interval',
+    truncated: ({ omittedTurns, omittedBytes, outOfOrderEvents }) => `truncated: ${omittedTurns} turns and ${omittedBytes} bytes omitted${outOfOrderEvents ? `, ${outOfOrderEvents} records out of order` : ''}`,
+};
+// the default prose renderer: paragraphs on blank lines, line breaks kept — a message was typed, not laid out
+export function PlainText({ text }) {
+    const paragraphs = text.split(/\n{2,}/);
+    return _jsx("div", { className: "tx-prose", children: paragraphs.map((paragraph, index) => (_jsx("p", { children: paragraph.split('\n').flatMap((line, at) => at ? [_jsx("br", {}, `b${at}`), line] : [line]) }, index))) });
+}
+export const defaultOptions = {
+    renderText: (text) => _jsx(PlainText, { text: text }),
+    loadToolOutput: null,
+    labels: defaultLabels,
+    vocabulary: defaultVocabulary,
+    fold: 'segments',
+    runMin: 3,
+    userTurns: 'boundary',
+};
+const Context = createContext(defaultOptions);
+export const useTranscriptUi = () => useContext(Context);
+export function TranscriptUi({ children, ...overrides }) {
+    const parent = useContext(Context);
+    const value = { ...parent, ...Object.fromEntries(Object.entries(overrides).filter(([, v]) => v !== undefined)) };
+    return _jsx(Context.Provider, { value: value, children: children });
+}

package/dist/icons.d.ts

@@ -0,0 +1,9 @@
+export declare function Caret({ open, size, className }: {
+    open?: boolean;
+    size?: number;
+    className?: string;
+}): import("react").JSX.Element;
+export declare function Spinner({ size, className }: {
+    size?: number;
+    className?: string;
+}): import("react").JSX.Element;

package/dist/icons.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// The two marks the transcript needs, as inline SVG: a chevron that trails every disclosure and a spinner
+// for a running call. Stroke icons, one weight, no emoji — a host's icon set may replace them through CSS.
+export function Caret({ open = false, size = 12, className = '' }) {
+    return (_jsx("svg", { className: `tx-caret${open ? ' is-open' : ''}${className ? ` ${className}` : ''}`, width: size, height: size, viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: 2, strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: _jsx("polyline", { points: "9 6 15 12 9 18" }) }));
+}
+export function Spinner({ size = 11, className = '' }) {
+    return (_jsx("svg", { className: `tx-spin${className ? ` ${className}` : ''}`, width: size, height: size, viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: 2, strokeLinecap: "round", "aria-hidden": "true", children: _jsx("path", { d: "M12 2a10 10 0 1 0 10 10" }) }));
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export * from './vocabulary.js';
+export * from './segments.js';
+export * from './context.js';
+export * from './icons.js';
+export * from './useDisclosure.js';
+export * from './useTranscriptFrames.js';
+export * from './Quote.js';
+export * from './ToolLine.js';
+export * from './TranscriptView.js';
+export * from './LiveTail.js';

package/dist/index.js

@@ -0,0 +1,10 @@
+export * from './vocabulary.js';
+export * from './segments.js';
+export * from './context.js';
+export * from './icons.js';
+export * from './useDisclosure.js';
+export * from './useTranscriptFrames.js';
+export * from './Quote.js';
+export * from './ToolLine.js';
+export * from './TranscriptView.js';
+export * from './LiveTail.js';

package/dist/segments.d.ts

@@ -0,0 +1,29 @@
+import type { StreamTurn, TranscriptTurn } from '@spexcode/transcript/frames';
+import type { AnyTool } from './vocabulary.js';
+export type AnyTurn = TranscriptTurn | StreamTurn;
+export declare const isRunning: (tool: AnyTool, live: boolean) => boolean;
+export declare const alreadySaid: (text: string | null | undefined, said: string | null | undefined) => boolean;
+export type WorkSegment = Readonly<{
+    kind: 'work';
+    work: readonly AnyTurn[];
+    answer: AnyTurn | null;
+    after: readonly AnyTurn[];
+    calls: number;
+    folded: boolean;
+    now: boolean;
+}>;
+export type QuoteSegment = Readonly<{
+    kind: 'quote';
+    turn: AnyTurn;
+}>;
+export type Segment = WorkSegment | QuoteSegment;
+export type FoldPolicy = 'segments' | 'runs' | 'none';
+export type UserTurnPolicy = 'quote' | 'boundary';
+export declare function segments(turns: readonly AnyTurn[], options?: {
+    live?: boolean;
+    fold?: FoldPolicy;
+    runMin?: number;
+    userTurns?: UserTurnPolicy;
+}): Segment[];
+export declare function currentTurn(turns: readonly AnyTurn[]): AnyTurn[];
+export declare function liveSlice(turns: readonly AnyTurn[]): AnyTurn[];

package/dist/segments.js

@@ -0,0 +1,79 @@
+// a call is running until the harness recorded its result; only a LIVE reading may say so — a closed
+// interval that ends before the result was written is history, not something still happening
+export const isRunning = (tool, live) => live && tool.output === undefined;
+// THE TRANSCRIPT SAYS NOTHING THE RECORD ALREADY SAID. An adopter whose record draws a message or a declared
+// note as a row of its own elides the same sentence inside the transcript. Either side may be the other's
+// prefix (a note is often clipped), so the test is a prefix match over squashed whitespace.
+const squash = (text) => (text || '').replace(/\s+/g, ' ').trim();
+export const alreadySaid = (text, said) => {
+    const a = squash(text).replace(/(\.\.\.|…)$/, '');
+    const b = squash(said);
+    return !!a && !!b && (b.startsWith(a) || a.startsWith(b));
+};
+// WHERE THE FOLD BELONGS, decided by what a real transcript looks like. Measured against a real session: 39
+// calls spread across 21 assistant turns, one or two each — the repetition is BETWEEN turns, not within
+// them. So the unit is the work SEGMENT: a consecutive run of assistant turns, ending at the last one that
+// actually says something. Everything before that is how the answer was produced; the last turn is the
+// answer. Collapse the process, keep the result.
+//
+// THE WORK IN PROGRESS NEVER FOLDS. The last segment of a LIVE payload is what is happening now: its calls
+// after the newest prose — or all of them, while there is no prose yet — draw as sentences whatever their
+// number. They fold the moment the agent speaks.
+//
+// A user turn is a BOUNDARY: it ends the current run of agent work. Whether it is also DRAWN is the adopter's
+// call — a host whose own record already shows every message (SpexCode's conversation) hides it; a host for
+// which the transcript is the whole conversation quotes it.
+export function segments(turns, options = {}) {
+    const { live = false, fold = 'segments', runMin = 3, userTurns = 'boundary' } = options;
+    const out = [];
+    let run = [];
+    const flush = () => {
+        if (!run.length)
+            return;
+        const calls = run.reduce((n, turn) => n + (turn.tools?.length || 0), 0);
+        let lead = run.length - 1;
+        while (lead > 0 && !run[lead].text)
+            lead -= 1;
+        const answer = run[lead]?.text ? run[lead] : null;
+        const work = answer ? run.slice(0, lead) : run;
+        const after = answer ? run.slice(lead + 1) : [];
+        out.push({ kind: 'work', work, answer, after, calls, folded: fold === 'segments' && calls >= runMin && work.length > 0, now: false });
+        run = [];
+    };
+    for (const turn of turns) {
+        if (turn.role === 'user') {
+            flush();
+            if (userTurns === 'quote' && turn.text)
+                out.push({ kind: 'quote', turn });
+            continue;
+        }
+        run.push(turn);
+    }
+    flush();
+    const last = out[out.length - 1];
+    if (live && last?.kind === 'work') {
+        const now = { ...last, now: true, folded: last.folded && !!last.answer };
+        out[out.length - 1] = now;
+    }
+    return out;
+}
+// the current turn: everything after the newest human message (or the whole payload when the stretch was
+// opened by the agent itself and no message sits in it)
+export function currentTurn(turns) {
+    let start = 0;
+    turns.forEach((turn, index) => { if (turn.role === 'user')
+        start = index + 1; });
+    return turns.slice(start);
+}
+// the compact view of "now": the newest prose and every call after it — the process that produced earlier
+// prose has already folded into history. Before any prose, the calls themselves are the news.
+export function liveSlice(turns) {
+    const turn = currentTurn(turns);
+    let lead = -1;
+    for (let index = turn.length - 1; index >= 0; index--)
+        if (turn[index].text) {
+            lead = index;
+            break;
+        }
+    return lead < 0 ? turn : turn.slice(lead);
+}

package/dist/useDisclosure.d.ts

@@ -0,0 +1 @@
+export declare function useDisclosure(): [ReadonlySet<string>, (id: string) => void];

package/dist/useDisclosure.js

@@ -0,0 +1,15 @@
+import { useCallback, useState } from 'react';
+// one disclosure set per rendered payload: what the reader opened stays open across live refreshes of the
+// same interval, because ids are the transcript's own (tool ids, turn ids), not render positions
+export function useDisclosure() {
+    const [openIds, setOpenIds] = useState(() => new Set());
+    const toggle = useCallback((id) => setOpenIds((prev) => {
+        const next = new Set(prev);
+        if (next.has(id))
+            next.delete(id);
+        else
+            next.add(id);
+        return next;
+    }), []);
+    return [openIds, toggle];
+}

package/dist/useTranscriptFrames.d.ts

@@ -0,0 +1,6 @@
+import { type MergedFrame, type TranscriptFrame } from '@spexcode/transcript/frames';
+export declare function useTranscriptFrames(): {
+    payload: MergedFrame['payload'] | null;
+    receive: (frame: TranscriptFrame) => void;
+    reset: () => void;
+};

package/dist/useTranscriptFrames.js

@@ -0,0 +1,16 @@
+import { useCallback, useRef, useState } from 'react';
+import { mergeTranscriptFrame } from '@spexcode/transcript/frames';
+// THE SUBSCRIBER'S HOOK. Hand it every frame a transport delivers (SSE, IPC, a socket — the hook does not
+// care) and read one complete payload back: the frame protocol's own merge keeps the held turns, so a host
+// writes no merging code and cannot drift from the producer. `reset` is for a stream that starts over.
+export function useTranscriptFrames() {
+    const held = useRef({ turns: [] });
+    const [payload, setPayload] = useState(null);
+    const receive = useCallback((frame) => {
+        const merged = mergeTranscriptFrame(held.current, frame);
+        held.current = merged.state;
+        setPayload(merged.payload);
+    }, []);
+    const reset = useCallback(() => { held.current = { turns: [] }; setPayload(null); }, []);
+    return { payload, receive, reset };
+}

package/dist/vocabulary.d.ts

@@ -0,0 +1,40 @@
+import type { StreamTool, TranscriptTool } from '@spexcode/transcript/frames';
+export type AnyTool = TranscriptTool | StreamTool;
+export type Vocabulary = Readonly<{
+    verbs: Readonly<Record<string, string>>;
+    quiet: ReadonlySet<string>;
+    targetKeys: readonly string[];
+}>;
+export declare const defaultVocabulary: Vocabulary;
+export declare function extendVocabulary(base: Vocabulary, extra: Partial<{
+    verbs: Record<string, string>;
+    quiet: Iterable<string>;
+    targetKeys: readonly string[];
+}>): Vocabulary;
+export declare const toolVerb: (name: string | undefined, vocabulary?: Readonly<{
+    verbs: Readonly<Record<string, string>>;
+    quiet: ReadonlySet<string>;
+    targetKeys: readonly string[];
+}>) => string;
+export declare const isQuietTool: (name: string, vocabulary?: Readonly<{
+    verbs: Readonly<Record<string, string>>;
+    quiet: ReadonlySet<string>;
+    targetKeys: readonly string[];
+}>) => boolean;
+export declare function toolTarget(input: string | undefined, vocabulary?: Readonly<{
+    verbs: Readonly<Record<string, string>>;
+    quiet: ReadonlySet<string>;
+    targetKeys: readonly string[];
+}>): string | null;
+export declare function splitTarget(target: string | null): {
+    lead: string | null;
+    trail: string | null;
+};
+export declare const RUN_MIN = 3;
+export declare function runKinds(tools: readonly AnyTool[], vocabulary?: Readonly<{
+    verbs: Readonly<Record<string, string>>;
+    quiet: ReadonlySet<string>;
+    targetKeys: readonly string[];
+}>): string;
+export declare function elapsed(ms: number): string | null;
+export declare const timeOf: (ts: number | string) => string;

package/dist/vocabulary.js

@@ -0,0 +1,84 @@
+export const defaultVocabulary = {
+    verbs: {
+        Read: 'Read', NotebookRead: 'Read',
+        Grep: 'Searched', Glob: 'Searched', WebSearch: 'Searched the web',
+        Bash: 'Ran', BashOutput: 'Read output',
+        Edit: 'Edited', MultiEdit: 'Edited', NotebookEdit: 'Edited',
+        Write: 'Wrote',
+        WebFetch: 'Fetched',
+        Task: 'Delegated to',
+        TodoWrite: 'Updated the plan',
+    },
+    quiet: new Set(['Read', 'NotebookRead', 'Grep', 'Glob', 'WebFetch', 'WebSearch']),
+    targetKeys: ['file_path', 'filePath', 'path', 'notebook_path', 'pattern', 'query', 'command', 'cmd', 'url', 'description'],
+};
+export function extendVocabulary(base, extra) {
+    return {
+        verbs: { ...base.verbs, ...(extra.verbs ?? {}) },
+        quiet: new Set([...base.quiet, ...(extra.quiet ?? [])]),
+        targetKeys: extra.targetKeys ? [...extra.targetKeys, ...base.targetKeys.filter((key) => !extra.targetKeys.includes(key))] : base.targetKeys,
+    };
+}
+export const toolVerb = (name, vocabulary = defaultVocabulary) => (name && vocabulary.verbs[name]) || name || 'tool';
+export const isQuietTool = (name, vocabulary = defaultVocabulary) => vocabulary.quiet.has(name);
+// The target, from the call's own arguments. `input` is the raw JSON of the arguments (or a bare string), so
+// this reads the field the tool actually names and shows NOTHING when it cannot — a wrong target is worse
+// than no target, and a truncated blob of JSON is not a target at all.
+export function toolTarget(input, vocabulary = defaultVocabulary) {
+    if (typeof input !== 'string' || !input)
+        return null;
+    let parsed = null;
+    try {
+        parsed = JSON.parse(input);
+    }
+    catch {
+        return input.length <= 80 ? input : null;
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return typeof parsed === 'string' ? parsed : null;
+    for (const key of vocabulary.targetKeys) {
+        const value = parsed[key];
+        if (typeof value === 'string' && value.trim())
+            return value.trim();
+    }
+    return null;
+}
+// A path reads better as its basename with the directory trailing quietly behind it.
+export function splitTarget(target) {
+    if (!target || !target.includes('/') || /\s/.test(target))
+        return { lead: target, trail: null };
+    const cut = target.lastIndexOf('/');
+    return { lead: target.slice(cut + 1) || target, trail: target.slice(0, cut) };
+}
+// HOW A RUN COLLAPSES, without claiming anything about what the calls DID. Measured against a real
+// transcript: 39 consecutive calls, every one of them `Bash`; grouping only the names known to be read-only
+// collapsed none of them. So the rule infers nothing: a run collapses because it is a RUN — `runMin` or more
+// calls in a row — and the label says only what is on the record.
+export const RUN_MIN = 3;
+// What KINDS ran, for a row whose count is already stated beside it: the verb when they share one, the kinds
+// when they do not — never the number again.
+export function runKinds(tools, vocabulary = defaultVocabulary) {
+    const counts = new Map();
+    for (const tool of tools) {
+        const verb = toolVerb(tool.name, vocabulary);
+        counts.set(verb, (counts.get(verb) || 0) + 1);
+    }
+    const entries = [...counts.entries()];
+    if (entries.length === 1)
+        return entries[0][0].toLowerCase();
+    return entries.slice(0, 3).map(([verb, n]) => `${n} ${verb.toLowerCase()}`).join(', ');
+}
+// Elapsed time in a shape a reader can absorb at a glance: at most two units, biggest first.
+export function elapsed(ms) {
+    if (!Number.isFinite(ms) || ms < 0)
+        return null;
+    const s = Math.round(ms / 1000);
+    if (s < 60)
+        return `${s}s`;
+    const m = Math.floor(s / 60);
+    const h = Math.floor(m / 60);
+    if (h > 0)
+        return m % 60 ? `${h}h ${m % 60}m` : `${h}h`;
+    return s % 60 ? `${m}m ${s % 60}s` : `${m}m`;
+}
+export const timeOf = (ts) => new Date(ts).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' });

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@spexcode/transcript-ui",
+  "version": "0.7.0-next.1",
+  "type": "module",
+  "description": "React components that draw a normalized agent transcript — the person quoted, the agent as the page, a tool call as a sentence, the work folded behind its answer — with the fold, the prose renderer, the tool vocabulary, the labels and the design tokens all tunable.",
+  "files": [
+    "dist",
+    "styles.css"
+  ],
+  "exports": {
+    ".": "./dist/index.js",
+    "./styles.css": "./styles.css",
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build-dist.mjs",
+    "prepublishOnly": "node ../../scripts/release-publish.mjs --from-package-publish",
+    "test": "npm run build && tsx --test src/*.test.tsx"
+  },
+  "dependencies": {
+    "@spexcode/transcript": "0.7.0-next.1"
+  },
+  "peerDependencies": {
+    "react": "^18.2.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.3"
+  }
+}

package/styles.css

@@ -0,0 +1,122 @@
+/* @spexcode/transcript-ui — the transcript's grammar as one stylesheet.
+   Every colour, face, size and space is a `--tx-*` token with a fallback chain: a host that defines the
+   same-named bare token (`--ink`, `--mono`, `--type-prose`…) is inherited automatically; a host that
+   defines nothing gets the dark defaults; a host that wants something else sets `--tx-*` on `.tx` or any
+   ancestor. Class names are the second customisation surface and are stable. No emoji, no icon font. */
+.tx {
+  --tx-ink: var(--ink, #d1d1d1);
+  --tx-ink2: var(--ink2, #e6e6e6);
+  --tx-muted: var(--muted, #999999);
+  --tx-blue: var(--blue, #6c99bb);
+  --tx-orange: var(--orange, #d5763f);
+  --tx-red: var(--red, #d04255);
+  --tx-paper: var(--paper, #262626);
+  --tx-panel2: var(--panel2, #2c2c2c);
+  --tx-edge: var(--edge, rgba(120, 120, 120, .45));
+  --tx-wash-hover: var(--wash-hover, rgba(255, 255, 255, .06));
+  --tx-mono: var(--mono, 'JetBrains Mono', ui-monospace, 'SF Mono', Menlo, Consolas, monospace);
+  --tx-ui-font: var(--ui-font, var(--tx-mono));
+  --tx-type-caption: var(--type-caption, 11px);
+  --tx-type-meta: var(--type-meta, 12px);
+  --tx-type-prose: var(--type-prose, 14px);
+  --tx-leading-body: var(--leading-body, 1.65);
+  --tx-weight-medium: var(--weight-medium, 500);
+  --tx-weight-semibold: var(--weight-semibold, 600);
+  --tx-radius: var(--radius, 6px);
+  --tx-space-1: 4px; --tx-space-2: 6px; --tx-space-3: 8px; --tx-space-4: 12px; --tx-space-5: 16px; --tx-space-6: 22px;
+  --tx-dur-rise: var(--dur-rise, 120ms);
+  min-width: 0;
+  color: var(--tx-ink);
+}
+
+/* THE FLOW: turns stacked at paragraph distance. Consecutive tool-only turns are ONE list of calls — the
+   harness draws a turn boundary around every call it makes, and that boundary is not a paragraph break. */
+.tx-flow { display: flex; flex-direction: column; gap: var(--tx-space-6); }
+.tx-flow > .tx-say:not(:has(.tx-say-text)) + .tx-say:not(:has(.tx-say-text)) { margin-top: calc(2px - var(--tx-space-6)); }
+.tx-work-body > .tx-say:not(:has(.tx-say-text)) + .tx-say:not(:has(.tx-say-text)) { margin-top: calc(2px - 14px); }
+.tx-empty, .tx-truncated { color: var(--tx-muted); font-family: var(--tx-ui-font); font-size: var(--tx-type-meta); overflow-wrap: anywhere; }
+
+/* THE AGENT IS THE PAGE: full measure, no bubble, no tint. */
+.tx-say { display: flex; flex-direction: column; gap: 8px; min-width: 0; }
+.tx-say-text { max-width: 100%; color: var(--tx-ink); font-size: var(--tx-type-prose); line-height: var(--tx-leading-body); overflow-wrap: anywhere; }
+.tx-prose > p { margin: 0; }
+.tx-prose > p + p { margin-top: .75em; }
+
+/* THE PERSON IS QUOTED: a bubble off to its own side, one corner squared, capped well under the measure. */
+.tx-quote {
+  --tx-quote-bg: color-mix(in srgb, var(--tx-panel2) 72%, var(--tx-paper));
+  position: relative; justify-self: end; margin-left: auto; min-width: 0; max-width: 80%;
+  padding: var(--tx-space-4) var(--tx-space-5); color: var(--tx-ink2); background: var(--tx-quote-bg);
+  border-radius: calc(var(--tx-radius) * 2); border-top-right-radius: 2px;
+}
+.tx-quote-nested { max-width: 88%; }
+.tx-quote-head { display: flex; justify-content: space-between; align-items: baseline; gap: 12px; margin: 0 0 3px; font-family: var(--tx-ui-font); }
+.tx-quote-who { font-size: var(--tx-type-caption); font-weight: var(--tx-weight-semibold); color: var(--tx-blue); }
+.tx-time { display: none; margin-left: auto; flex: none; font-family: var(--tx-ui-font); font-size: var(--tx-type-caption); color: var(--tx-muted); font-variant-numeric: tabular-nums; }
+.tx-quote-text { font-size: var(--tx-type-prose); line-height: var(--tx-leading-body); overflow-wrap: anywhere; }
+.tx-quote.is-clamped { max-height: 13em; overflow: hidden; }
+.tx-quote.is-clamped::after { content: ""; position: absolute; inset: auto 0 0; height: 4.5em; background: linear-gradient(transparent, var(--tx-quote-bg)); pointer-events: none; }
+.tx-quote-more { position: absolute; right: 10px; bottom: 6px; z-index: 1; padding: 0; color: var(--tx-blue); background: none; border: 0; font: inherit; font-family: var(--tx-ui-font); font-size: var(--tx-type-caption); cursor: pointer; }
+
+/* THE WORK SEGMENT'S ONE LINE: a bounded sentence — the count, the kinds, the chevron trailing. */
+.tx-work { display: flex; flex-direction: column; align-items: flex-start; gap: 8px; }
+.tx-work-row {
+  display: inline-flex; align-items: baseline; gap: 7px; max-width: 100%; padding: var(--tx-space-2) var(--tx-space-3); margin-left: calc(var(--tx-space-3) * -1);
+  color: var(--tx-muted); background: none; border: 0; border-radius: var(--tx-radius);
+  font-family: var(--tx-ui-font); font-size: var(--tx-type-meta); text-align: left; cursor: pointer;
+}
+.tx-work-row:hover { background: var(--tx-wash-hover); color: var(--tx-ink2); }
+.tx-work-lead { flex: none; color: var(--tx-ink2); font-weight: var(--tx-weight-medium); }
+.tx-work-detail { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.tx-work-body { align-self: stretch; display: flex; flex-direction: column; gap: 14px; padding-left: 10px; border-left: 1px solid var(--tx-edge); }
+
+/* A TOOL CALL IS A SENTENCE, not a card: inline-flex, exactly as wide as what it says, capped so a long shell
+   command never stretches the row into a full-width bar. The verb IS the status: no tick, no badge. */
+.tx-tools { display: flex; flex-direction: column; gap: 2px; align-items: flex-start; min-width: 0; max-width: 100%; }
+.tx-tool { display: flex; flex-direction: column; gap: 3px; min-width: 0; max-width: 100%; }
+.tx-tool-row {
+  display: inline-flex; align-items: baseline; gap: 6px; min-width: 0; max-width: min(100%, 56ch);
+  padding: 2px 0; color: var(--tx-muted); background: none; border: 0;
+  font-family: var(--tx-ui-font); font-size: var(--tx-type-meta); text-align: left;
+}
+.tx-tool-row.is-openable { cursor: pointer; }
+.tx-tool-row.is-openable:hover { color: var(--tx-ink2); }
+.tx-tool-verb { flex: none; color: var(--tx-ink2); font-weight: var(--tx-weight-medium); }
+.tx-tool-target { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; color: var(--tx-ink); }
+.tx-tool-trail { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; color: var(--tx-muted); }
+.tx-tool-size { flex: none; color: var(--tx-muted); font-variant-numeric: tabular-nums; }
+.tx-tool-row.is-run .tx-tool-verb { color: var(--tx-muted); font-weight: inherit; }
+.tx-tool-kids { display: flex; flex-direction: column; gap: 2px; align-items: flex-start; margin-left: 8px; padding-left: 10px; border-left: 1px solid var(--tx-edge); }
+.tx-tool-in, .tx-tool-out {
+  max-width: 100%; max-height: 220px; overflow: auto; margin: 0 0 2px; padding: 7px 9px;
+  color: var(--tx-ink); background: var(--tx-panel2); border-radius: var(--tx-radius);
+  font: inherit; font-family: var(--tx-mono); font-size: var(--tx-type-meta);
+  white-space: pre-wrap; overflow-wrap: anywhere;
+}
+.tx-tool-out.tx-tool-out-state { font-family: var(--tx-ui-font); font-size: var(--tx-type-meta); color: var(--tx-muted); }
+.tx-tool-out.tx-tool-out-state.is-error { color: var(--tx-red); }
+
+/* THE CHEVRON trails every disclosure; the same shape says open everywhere. */
+.tx-caret { flex: none; align-self: center; transition: transform .12s ease; }
+.tx-caret.is-open { transform: rotate(90deg); }
+
+/* LIVE: a running call wears a spinner and the word; the newest prose rises in; the caret blinks at the end
+   of words still being said. Reduced motion keeps the marks and drops the movement. */
+.tx-tool.is-running .tx-tool-verb { color: var(--tx-ink2); }
+.tx-tool-running { display: inline-flex; align-items: center; gap: 4px; flex: none; color: var(--tx-orange); font-size: var(--tx-type-caption); }
+.tx-spin { animation: tx-spin 1s linear infinite; }
+@keyframes tx-spin { to { transform: rotate(360deg); } }
+.tx-live { margin-top: var(--tx-space-2); min-width: 0; }
+.tx-live .tx-say-text { animation: tx-rise var(--tx-dur-rise) ease; }
+@keyframes tx-rise { from { opacity: 0; transform: translateY(2px); } to { opacity: 1; transform: none; } }
+.tx-live.is-speaking > .tx-say:last-child .tx-say-text > :first-child > :last-child::after { content: '▍'; margin-left: 2px; color: var(--tx-muted); animation: tx-caret 1s steps(2, start) infinite; }
+@keyframes tx-caret { to { visibility: hidden; } }
+@media (prefers-reduced-motion: reduce) {
+  .tx-live .tx-say-text, .tx-live.is-speaking > .tx-say:last-child .tx-say-text > :first-child > :last-child::after, .tx-spin, .tx-caret { animation: none; transition: none; }
+}
+
+/* A NARROW PANE: the quote widens and shows its own time, because there is no ruler beside the flow. */
+@container (max-width: 560px) {
+  .tx-quote { max-width: 88%; }
+  .tx-time { display: inline; }
+}