@teaflask/assistant 0.3.0 → 0.6.0

package/dist/components/use-thread-dispatches.js

@@ -1,11 +1,4 @@
 "use client";
-// The widget transcript's ledger read: the thread's dispatch family
-// through the serving door, joined onto the subagent group rows so a
-// child that outlives its turn reads settled instead of spinning on its
-// frozen wire receipt. The read lives in a session-scoped registry cell:
-// every mounted surface shares ONE map and ONE 10s single-flight poll,
-// the union of demands drives the timer, and the last demand leaving
-// stops it. Design record: docs/thread-dispatches.md.
 import { useCallback, useEffect, useMemo } from "react";
 import { dispatchIsPaused, dispatchIsRunning, } from "../contract/dispatches.js";
 import { ObservableCell } from "../core/observable-cell.js";
@@ -13,31 +6,11 @@ import { dispatchReceiptOf } from "../core/subagent-rows.js";
 import { listThreadDispatches } from "../transport/serving-api.js";
 import { resolvedSubagentEntryOf } from "./subagent-group-row.js";
 import { useCell } from "./use-store-cell.js";
-// The dashboard's watch-poll interval — a live view, faster than a safety
-// net; the demand union stops it the moment nothing can move anymore.
 const POLL_INTERVAL_MS = 10_000;
-// The persistent-failure trip (the dashboard twin's fail-closed stance): a
-// read that keeps failing — revoked key, expired token, a gone thread —
-// must not retry every 10s for the life of the page. After this many
-// consecutive failures on one thread the timer stops; a demand change re-arms.
 const MAX_CONSECUTIVE_READ_FAILURES = 3;
-// The roster read's bound: nothing in this transport aborts a stalled GET,
-// so the flight settles at two poll windows and counts toward the trip —
-// docs/thread-dispatches.md, "The read bound".
 const READ_BOUND_MS = 2 * POLL_INTERVAL_MS;
 const EMPTY_LEDGER = new Map();
-// The resume door's tool name. Local on purpose: a resume renders as a
-// PLAIN tool call (grouping collapses dispatch_subagent alone), so the poll
-// reads it off tool-call rows itself; a single-consumer constant lives
-// here.
 const RESUME_SUBAGENT_TOOL_NAME = "resume_subagent";
-/** Whether any resume call on the transcript still awaits the ledger's
- *  truth — the read that DISCOVERS a resume row, since the ledger arm only
- *  keeps a poll alive once the row has been read. A resume receipt carries
- *  the new row's ORDINAL, so a landed receipt whose ordinal is absent from
- *  the map or maps to a still-dispatched row is the signal. A result that
- *  parses to no receipt has no join key and never pins the page to an
- *  indefinite poll; an already_settled receipt was answered in place. */
 function aResumeAwaitsLedgerTruth(rows, ledger) {
     return rows.some((row) => {
         if (row.kind !== "tool-call" ||
@@ -52,11 +25,6 @@ function aResumeAwaitsLedgerTruth(rows, ledger) {
         return dispatched === undefined || dispatchIsRunning(dispatched);
     });
 }
-/** The chain's newest row for one child session: a resumed child has
- *  several ledger rows sharing its handle, and a per-session consumer (the
- *  drill-in panel) wants the child's CURRENT state — the highest ordinal,
- *  exactly what the backend's session-keyed fence answers. Linear over a
- *  per-thread map that is small by construction. */
 function newestRowForSession(map, childSessionId) {
     let newest;
     for (const dispatch of map.values()) {
@@ -69,51 +37,25 @@ function newestRowForSession(map, childSessionId) {
     }
     return newest;
 }
-/** Whether any coworker the TRANSCRIPT joins is still unsettled after the
- *  ledger's word. Transcript-joined rows ONLY, never a bare sweep of the
- *  ledger: a row nothing joins may be one nothing will ever settle (the
- *  backend's unreached-start refusal leaves its row DISPATCHED), and an
- *  entry with no receipt has no join key (the ORDINAL), so its frozen wire
- *  `running` renders as the wire says and the poll ignores it. The
- *  argument: docs/thread-dispatches.md, "The demand predicates". */
 function anySubagentStillRunning(rows, ledger) {
     return rows.some((row) => row.kind === "subagent-group" &&
         row.entries.some((entry) => entry.receipt != null &&
             resolvedSubagentEntryOf(entry, ledger).running));
 }
-/** One session's shared dispatch-ledger read: the cell every mounted
- *  surface renders from, plus the demand-driven poll behind it. */
 class ThreadDispatchLedger {
     session;
     cell = new ObservableCell(null);
     demands = new Map();
     timer = null;
     timerThreadId = null;
-    // One request in flight at a time — a slow read must not stack a
-    // second behind it when the interval fires.
     busy = false;
-    /** The thread the newest read (landed or in flight) was for — the
-     *  one-shot's "already read" mark. A failed read whose thread never
-     *  landed un-marks itself so a later demand change retries. */
     readThreadId = null;
-    /** A different thread asked while a read was in flight (a thread
-     *  switch): remembered and retried once the flight ends — dropping it
-     *  would strand a settled thread's one-shot read forever, since
-     *  nothing else would re-trigger it. */
     pendingThreadId = null;
-    /** The persistent-failure trip's memory: which thread keeps failing,
-     *  and how many times in a row. Reset by any success. */
     failedThreadId = null;
     consecutiveFailures = 0;
     constructor(session) {
         this.session = session;
     }
-    /** Settle listeners: fired once per read that OBSERVES a dispatch
-     *  settle — the signal that a delivery turn may be about to open.
-     *  Plain callbacks, not a store dependency: the ledger stays
-     *  session-only; the transcript hands its store method in. Invoked by
-     *  VALUE through a Set, so N surfaces registering the same stable
-     *  method collapse to one invocation per observed settle. */
     settleListeners = new Map();
     setSettleListener(token, listener) {
         if (listener === null) {
@@ -123,9 +65,6 @@ class ThreadDispatchLedger {
             this.settleListeners.set(token, listener);
         }
     }
-    /** Pause listeners: fired once per read that OBSERVES a row paused —
-     *  its request is on the dispatching turn's snapshot, so the store
-     *  re-reads the conversation. Same shape as the settle relay. */
     pauseListeners = new Map();
     setPauseListener(token, listener) {
         if (listener === null) {
@@ -144,11 +83,6 @@ class ThreadDispatchLedger {
         }
         this._reconcile();
     }
-    /** The settle tap: a child stream that watched its own ending asks the
-     *  ledger to catch up NOW. Resolves once a read whose snapshot
-     *  POSTDATES the tap has landed — or its bound fired. A busy tap chains
-     *  ONE fresh read behind the flight (a joined flight may predate the
-     *  settle); concurrent taps share it. docs/thread-dispatches.md. */
     refresh(threadId) {
         if (!this.busy) {
             return this._readOnce(threadId);
@@ -163,12 +97,9 @@ class ThreadDispatchLedger {
         }
         return this.followUp;
     }
-    /** The one chained catch-up a busy settle tap queues (and shares). */
     followUp = null;
     followUpThreadId = null;
     _reconcile() {
-        // Every surface renders the same store cells, so all demands name the
-        // same thread; the union only genuinely varies on the booleans.
         let threadId = null;
         let delegated = false;
         let stillMoving = false;
@@ -177,10 +108,6 @@ class ThreadDispatchLedger {
             delegated ||= demand.delegated;
             stillMoving ||= demand.stillMoving;
         }
-        // A parked switch is honored only while it is still the demanded
-        // thread: the demand moving on invalidates it here, on the same change
-        // that made it stale. Left standing, it would fire after the flight
-        // lands and overwrite the demanded thread's fresh read with another's.
         if (this.pendingThreadId !== null && this.pendingThreadId !== threadId) {
             this.pendingThreadId = null;
         }
@@ -197,9 +124,6 @@ class ThreadDispatchLedger {
         }
         if (this.timer === null || this.timerThreadId !== threadId) {
             this._stopTimer();
-            // Arming reads immediately — a coworker that just appeared (or a
-            // thread switch mid-flight) must not wait a whole tick for its
-            // first ledger word.
             void this._readOnce(threadId);
             this.timerThreadId = threadId;
             this.timer = window.setInterval(() => {
@@ -217,10 +141,6 @@ class ThreadDispatchLedger {
         }
         for (const [ordinal, dispatch] of next.map) {
             const held = current.map.get(ordinal);
-            // label is authored at the open and never rewritten; status, error
-            // and updated_at are everything a settle can move that any surface
-            // reads. summary is deliberately not compared: no transcript
-            // surface displays it, and its settle moves updated_at.
             if (held?.status !== dispatch.status ||
                 held.error !== dispatch.error ||
                 held.updated_at !== dispatch.updated_at) {
@@ -238,11 +158,6 @@ class ThreadDispatchLedger {
     }
     _readOnce(threadId) {
         if (this.busy) {
-            // Same thread: the tick's normal single-flight skip, joining the
-            // in-flight read (the settle tap never lands here — refresh()
-            // chains a fresh read instead, since a joined flight's snapshot
-            // may predate the settle). A DIFFERENT thread is a switch
-            // mid-flight — park it for the finally below.
             if (threadId !== this.readThreadId) {
                 this.pendingThreadId = threadId;
             }
@@ -252,11 +167,6 @@ class ThreadDispatchLedger {
         this.readThreadId = threadId;
         this.generation += 1;
         const generation = this.generation;
-        // THE FLIGHT IS THE BOUNDED DEFERRED, NOT THE GET: every joiner holds
-        // a hand-settled deferred that settles at READ_BOUND_MS even if the
-        // GET never does; the generation retires a bounded-out read's DUTIES,
-        // and any rejection releases busy through the live finally. Why, and
-        // what breaks otherwise: docs/thread-dispatches.md.
         let settleFlight;
         const flight = new Promise((resolve) => {
             settleFlight = resolve;
@@ -269,34 +179,18 @@ class ThreadDispatchLedger {
         void this._read(threadId, generation, settleFlight);
         return flight;
     }
-    /** The current in-flight read — what the busy path hands back. */
     flight = null;
-    /** Mints per flight; bumped by a bound-out to retire the flight. A
-     *  retired flight loses its DUTIES (busy, trip, replay — the bound
-     *  performs them); its payload is arbitrated by adoptedThrough. */
     generation = 0;
-    /** The bound fired first: perform exactly the duties the dead flight's
-     *  catch/finally may no longer perform — release busy, count the stall
-     *  toward the trip, un-mark the one-shot, replay the parked switch. */
     _releaseBoundedOutRead(threadId, generation) {
         if (generation !== this.generation || !this.busy) {
-            // The read settled inside the bound; this timer is a no-op.
             return;
         }
         this.generation += 1;
         this.busy = false;
         this.flight = null;
-        // The stall counts toward the trip: a wedged endpoint must fail
-        // closed after three bound-outs, not accrete one new wedged socket
-        // per tick forever.
         this._noteReadFailure(threadId);
         this._replayParkedSwitch();
     }
-    /** The trip's one accounting rule, shared by a settled failure and a
-     *  bound-out. Count toward the same-thread streak; stop ONLY the timer
-     *  the trip belongs to — a stale flight's failure landing after a switch
-     *  must not kill the new thread's poll, since nothing would re-arm it;
-     *  un-mark the one-shot only when this thread's truth never landed. */
     _noteReadFailure(threadId) {
         this.consecutiveFailures =
             this.failedThreadId === threadId ? this.consecutiveFailures + 1 : 1;
@@ -309,10 +203,6 @@ class ThreadDispatchLedger {
             this.readThreadId = null;
         }
     }
-    /** A parked switch runs exactly once, and only for a thread the ended
-     *  flight didn't just cover — never a bare reconcile, which would
-     *  tight-loop with the failure path's un-mark. Shared by the live
-     *  flight's finally and the bound-out. */
     _replayParkedSwitch() {
         const pending = this.pendingThreadId;
         this.pendingThreadId = null;
@@ -320,17 +210,8 @@ class ThreadDispatchLedger {
             void this._readOnce(pending);
         }
     }
-    // ADOPTION IS MONOTONIC IN ISSUE ORDER: the newest generation whose
-    // payload adopted. A retired flight's success still ADOPTS when
-    // nothing newer has and the ledger's interest has not moved to another
-    // thread — the bound retires a flight's DUTIES, never its truth. Both
-    // failure directions: docs/thread-dispatches.md, "Adoption".
     adoptedThrough = 0;
     async _read(threadId, generation, settleFlight) {
-        // A retired (bounded-out) flight has lost its DUTIES to the bound —
-        // busy/flight release, the trip, the parked-switch replay all belong
-        // to _releaseBoundedOutRead or a newer flight — but its payload is
-        // arbitrated by adoptedThrough above, not discarded outright.
         const live = () => generation === this.generation;
         try {
             const dispatches = await listThreadDispatches(this.session, threadId);
@@ -338,20 +219,12 @@ class ThreadDispatchLedger {
                 (generation > this.adoptedThrough &&
                     (this.readThreadId === threadId || this.readThreadId === null));
             if (!adopts) {
-                // OUTRUN — fresher truth already adopted, or the interest moved to
-                // another thread. Still proof the endpoint answers, so it clears
-                // the trip's memory for its OWN thread only (a switch's stale
-                // success must not launder the demanded thread's streak).
                 if (this.failedThreadId === threadId) {
                     this.failedThreadId = null;
                     this.consecutiveFailures = 0;
                 }
                 return;
             }
-            // A null readThreadId is the bound-out's un-mark of a one-shot
-            // whose truth never landed; this landing IS that truth — re-mark
-            // it, or the next demand change re-reads a thread the cell
-            // already answers.
             this.readThreadId ??= threadId;
             this.adoptedThrough = generation;
             const previous = this.cell.get();
@@ -359,17 +232,11 @@ class ThreadDispatchLedger {
                 threadId,
                 map: new Map(dispatches.map((dispatch) => [dispatch.ordinal, dispatch])),
             };
-            // The cell's own invariant: publishers set only on real change. An
-            // unchanged ledger must not notify — in exactly this feature's
-            // window (turn ended, stream idle, a child still finishing) every
-            // tick would otherwise re-render the whole transcript for nothing.
             if (!this._sameAsCurrent(next)) {
                 this.cell.set(next);
             }
             this.failedThreadId = null;
             this.consecutiveFailures = 0;
-            // After the cell moved, so a listener re-reading the map sees the
-            // settle it is being told about.
             if (_observedASettle(previous, next)) {
                 _fireEach(this.settleListeners);
             }
@@ -379,27 +246,14 @@ class ThreadDispatchLedger {
         }
         catch {
             if (!live()) {
-                // The bound already counted this flight's failure and released;
-                // its late rejection must not double-count nor trip a newer
-                // thread's timer.
                 return;
             }
-            // Transient by stance: keep the last good read — the wire receipts
-            // stay the honest fallback — and let the next tick retry. But only
-            // transient: a PERSISTENT failure (revoked key, expired token, a gone
-            // thread) never lands a map, so the frozen receipts would keep
-            // stillMoving true forever; the trip fails closed and the next
-            // demand change re-arms.
             this._noteReadFailure(threadId);
         }
         finally {
             if (live()) {
                 this.busy = false;
                 this.flight = null;
-                // Settled inside the bound: resolve the flight's deferred. The
-                // joiners run as microtasks AFTER this finally block, so the
-                // parked-switch replay re-pointing this.flight is harmless —
-                // settleFlight closes over THIS flight's resolver.
                 settleFlight();
                 this._replayParkedSwitch();
             }
@@ -412,21 +266,9 @@ function _fireEach(listeners) {
             listener();
         }
         catch {
-            // A listener's failure is never the read's (it would trip the
-            // roster poll over a consumer bug) and must not rob the
-            // listeners behind it.
         }
     }
 }
-/** Edge-triggered pause observation: a row now paused that the previous
- *  read of the SAME thread did not hold paused WITH THIS STAMP — or a
- *  first read that already holds one, since the request it names may
- *  postdate the conversation read the mount adopted. THE PREMISE: the
- *  ledger re-stamps updated_at on every row update (the table's
- *  set_updated_at trigger), and a coworker's second pause is two flips
- *  (paused → dispatched → paused) that can both land inside one poll
- *  window — status alone would read it as no edge, so the stamp is part of
- *  the observed identity. */
 function _observedAPause(previous, next) {
     const comparable = previous?.threadId === next.threadId ? previous : null;
     for (const [ordinal, dispatch] of next.map) {
@@ -442,10 +284,6 @@ function _observedAPause(previous, next) {
     }
     return false;
 }
-/** Edge-triggered settle observation: a row now terminal that the previous
- *  read of the SAME thread held as running — or had not seen at all
- *  (dispatched and settled inside one poll window fires exactly once). A first
- *  read or a thread switch is historical truth, never an observation. */
 function _observedASettle(previous, next) {
     if (previous?.threadId !== next.threadId) {
         return false;
@@ -461,9 +299,6 @@ function _observedASettle(previous, next) {
     }
     return false;
 }
-// Session-keyed on purpose: the provider registry resolves same-identity
-// surfaces to ONE shared TokenSession, so this is exactly "one poll per
-// conversation store". WeakMap — the ledger's lifetime is the session's.
 const _ledgers = new WeakMap();
 function _ledgerFor(session) {
     let ledger = _ledgers.get(session);
@@ -473,28 +308,13 @@ function _ledgerFor(session) {
     }
     return ledger;
 }
-/**
- * The thread's dispatch rows keyed by ordinal — the ask's identity (a
- * resume chain shares one child_session_id) — shared across every surface
- * of one session. Reads once when a delegation appears, polls while any
- * join-keyed coworker is unsettled, and stops when the family settled, the
- * last surface unmounts, or nothing could be corrected. Transient failures
- * keep the last good map; a persistent one trips the cap (fail closed)
- * until a demand change re-arms. Thread-keyed: a switch reads as the empty
- * map until the new thread's first read lands. onDispatchSettled fires
- * once per read observing a settle on the demanded thread; pass a stable
- * identity — same-valued listeners collapse to one.
- */
 export function useThreadDispatches(session, threadId, rows, onDispatchSettled, onDispatchPaused) {
-    // Render-safe like the registry's entryFor: constructs only, never boots.
     const ledger = _ledgerFor(session);
     const read = useCell(ledger.cell);
     const map = read !== null && read.threadId === threadId ? read.map : EMPTY_LEDGER;
     const delegated = useMemo(() => rows.some((row) => row.kind === "subagent-group") ||
         aResumeAwaitsLedgerTruth(rows, EMPTY_LEDGER), [rows]);
     const stillMoving = useMemo(() => anySubagentStillRunning(rows, map) || aResumeAwaitsLedgerTruth(rows, map), [rows, map]);
-    // This mount's demand key — identity only, safe to recreate (the
-    // cleanup closure holds the same object it registered).
     const token = useMemo(() => ({}), []);
     useEffect(() => {
         if (threadId === null) {
@@ -505,10 +325,6 @@ export function useThreadDispatches(session, threadId, rows, onDispatchSettled,
             ledger.setDemand(token, null);
         };
     }, [ledger, token, threadId, delegated, stillMoving]);
-    // The settle relay's registration — its own effect, so a demand flip
-    // never churns the listener registry. Detection runs only during
-    // ledger reads, so an unmounted listener is simply never invoked
-    // again.
     useEffect(() => {
         if (onDispatchSettled === undefined) {
             return;
@@ -527,12 +343,6 @@ export function useThreadDispatches(session, threadId, rows, onDispatchSettled,
             ledger.setPauseListener(token, null);
         };
     }, [ledger, token, onDispatchPaused]);
-    // The delivery marker's settle tap: a delivery divider proves its
-    // ordinals SETTLED, so a joined ledger row still reading DISPATCHED is
-    // stale by definition — ledger staleness, never the marker's liveness,
-    // is the trigger, which keeps replayed history quiet (every read
-    // postdates mount, so it already reads a historical settle as settled).
-    // Empty or missing join: quiet. docs/thread-dispatches.md.
     const staleDeliveredOrdinals = useMemo(() => {
         const delivered = new Set();
         for (const row of rows) {
@@ -557,22 +367,9 @@ export function useThreadDispatches(session, threadId, rows, onDispatchSettled,
     }, [ledger, threadId, staleDeliveredOrdinals]);
     return map;
 }
-/**
- * One coworker's ledger row, live, for the drill-in panel: the same
- * shared cell and demand-driven poll, but the demand is the panel's own —
- * a member can drill into a running child whose wire receipt never
- * streamed, and the transcript's rows-derived demand would not keep the
- * poll alive for it. refreshLedger is the settle tap: the panel's stream
- * watching its own ending must not wait a poll tick for the row to agree.
- */
 export function useChildDispatch(session, threadId, childSessionId) {
-    // Render-safe like the registry's entryFor: constructs only, never boots.
     const ledger = _ledgerFor(session);
     const read = useCell(ledger.cell);
-    // The chain's NEWEST row for this session: the panel shows the
-    // child's one extended transcript, and its current state is the
-    // newest ask's — the backend's find_dispatch_for_parent_and_child
-    // posture, mirrored.
     const dispatch = read !== null && read.threadId === threadId
         ? newestRowForSession(read.map, childSessionId)
         : undefined;
@@ -582,17 +379,12 @@ export function useChildDispatch(session, threadId, childSessionId) {
         if (threadId === null) {
             return;
         }
-        // delegated: true — the panel only exists because a delegation did,
-        // so the one-shot read must fire even before any group row rendered.
         ledger.setDemand(token, { threadId, delegated: true, stillMoving });
         return () => {
             ledger.setDemand(token, null);
         };
     }, [ledger, token, threadId, stillMoving]);
     const refreshLedger = useCallback(() => {
-        // Read from the cell, not the render: the caller's verdict runs in a
-        // promise callback, and the row THIS read landed is what it must
-        // judge — a stale closure would judge the pre-settle row.
         const newestRow = () => {
             const now = ledger.cell.get();
             return now !== null && now.threadId === threadId
@@ -606,4 +398,3 @@ export function useChildDispatch(session, threadId, childSessionId) {
     }, [ledger, threadId, childSessionId]);
     return { dispatch, refreshLedger };
 }
-//# sourceMappingURL=use-thread-dispatches.js.map

package/dist/components/use-transcript-folds.d.ts

@@ -3,9 +3,6 @@ import { type FoldedBlock, type FoldedTranscriptRow, type RunFoldMember } from "
 import type { MarkerBoundaries } from "../core/transcript-rows.js";
 import type { MessageListSource } from "./message-list-slots.js";
 export type DisplayRow = FoldedTranscriptRow;
-/** MessageList's per-render derivations, read in one place: the fold
- *  pass, the hold window, the blocks-mode offsets, the tail receipts and
- *  the trailing-liveness election. */
 export declare function useMessageListDerivations(source: MessageListSource, { live, typing, turnOpen, markerBoundaries, turnStartIds, decisionSurfacesInShelf, frameClaimsLiveness, emptyFallback, }: {
     live: boolean;
     typing: boolean;
@@ -26,9 +23,4 @@ export declare function useMessageListDerivations(source: MessageListSource, { l
     livenessClaimant: TrailingLivenessClaimant;
 };
 export type TrailingLivenessClaimant = "tail-row" | "standalone-headline" | "typing-dot" | "none";
-/** One live spelling of "this fold reads as running" — ActivityRail's
- *  headline and the trailing-liveness arbiter both read it. The trailing
- *  fold's turnLive bridges the quiet beat between one call's result and
- *  the next call's start, so back-to-back calls don't blink the headline. */
 export declare function _foldClaimsLiveness(members: readonly RunFoldMember[], turnLive: boolean): boolean;
-//# sourceMappingURL=use-transcript-folds.d.ts.map

package/dist/components/use-transcript-folds.js

@@ -5,9 +5,6 @@ import { currentTurnStartOf, foldedBlocksOf, runFoldsOf, } from "../core/run-fol
 import { subagentOutcomeCountsOf } from "../core/subagent-rows.js";
 import { ElicitationsContext } from "./elicitation-context.js";
 import { resolvedSubagentEntryOf, SubagentDispatchesContext, } from "./subagent-group-row.js";
-/** MessageList's per-render derivations, read in one place: the fold
- *  pass, the hold window, the blocks-mode offsets, the tail receipts and
- *  the trailing-liveness election. */
 export function useMessageListDerivations(source, { live, typing, turnOpen, markerBoundaries, turnStartIds, decisionSurfacesInShelf, frameClaimsLiveness, emptyFallback, }) {
     const { cards: elicitationCards } = useContext(ElicitationsContext);
     const { foldedBlocks, flatRows, displayRows } = useTranscriptFolds(source, {
@@ -16,45 +13,14 @@ export function useMessageListDerivations(source, { live, typing, turnOpen, mark
         markerBoundaries,
         turnStartIds,
     });
-    // The current turn's start (the hold window) is the fold pass's own
-    // boundary (core/run-folds.ts): the last user or subagent-delivery row,
-    // or a later DECLARED turn start (agent-mode delivery turns project no
-    // row), so the hold window and the fold window read the same boundaries.
-    // Positional on purpose, never a clock: the optimistic echo is a user
-    // row, so decay fires at send, and a replay renders identically every
-    // time.
     const currentTurnStart = currentTurnStartOf(displayRows, foldedBlocks, turnStartIds);
-    // Blocks mode renders per block, so each row's flat display index —
-    // what the hold window is measured in — is its block's offset plus
-    // its position in the block.
     const blockStarts = _blockStartsOf(foldedBlocks ?? []);
-    // An ANSWERED ask whose call never rendered a row (a wire that named
-    // no tool_call_id, a history whose call never reached the messages)
-    // still renders its Q→A receipt at the tail: the member answered, and
-    // that is content. It is the ONE settled-decision tail render left —
-    // the meta-receipt lines were deleted as a product decision.
     const unrowedAnsweredAsks = decisionSurfacesInShelf
         ? _unrowedAnsweredAsksOf(flatRows, elicitationCards)
         : NO_UNROWED_ASKS;
-    // The liveness anchor is simply the last display row: the only trailing
-    // marker row (turn-failed receipts) trails once the run settled.
     const liveIndex = displayRows.length - 1;
-    // The one trailing-liveness arbiter (a seam, closed at its
-    // mechanism): every element that can claim the beat is decided HERE,
-    // from the same facts its renderer reads, so no host and no tail kind
-    // can double-claim or drop the claim.
     const dispatchesJoin = useContext(SubagentDispatchesContext);
-    // The host's empty surface owns the empty frame: when the host said
-    // "the log is genuinely empty" AND gave the words for it, a package
-    // "Working…" (or the dot) beside those words is a second liveness
-    // claim in one frame — the run viewer's empty streaming state stacked
-    // "No activity yet." over "Working…". The host surface is the claimant
-    // then; the arbiter yields. An empty live log with NO host surface
-    // keeps the standalone headline — one claim either way.
     const hostEmptySurfaceShown = !hostFillDeclines(emptyFallback) && displayRows.length === 0;
-    // One yield rule: the host's empty surface showing, or
-    // the host's declared frame claim, each means the frame already
-    // carries the words — the standalone claimants stand down.
     const livenessClaimant = hostEmptySurfaceShown || frameClaimsLiveness
         ? "none"
         : _trailingLivenessClaimantOf(displayRows, live, typing, dispatchesJoin);
@@ -70,15 +36,8 @@ export function useMessageListDerivations(source, { live, typing, turnOpen, mark
     };
 }
 const NO_UNROWED_ASKS = [];
-/** The fold derivation, pure per render: blocks mode's segmented pass
- *  or rows mode's flat one. All tool calls stay inside their work fold. */
 function useTranscriptFolds(source, { live, turnOpen, markerBoundaries, turnStartIds, }) {
     const { rows, blocks } = source;
-    // Blocks mode: the segmented fold pass, so a host marker
-    // splits folds exactly as a visible row would. Rows mode takes the
-    // branch below it always took — the store surfaces' rendering is
-    // pinned by the pixel suite and the store-composition suites
-    // (the invariant-comment ledger, row 13).
     const foldedBlocks = blocks !== undefined
         ? foldedBlocksOf(blocks, {
             openTailTurn: turnOpen ?? live,
@@ -94,7 +53,6 @@ function useTranscriptFolds(source, { live, turnOpen, markerBoundaries, turnStar
         });
     return { foldedBlocks, flatRows, displayRows };
 }
-/** Each block's offset in the flat display order (blocks mode). */
 function _blockStartsOf(blocks) {
     const starts = [];
     let next = 0;
@@ -104,12 +62,6 @@ function _blockStartsOf(blocks) {
     }
     return starts;
 }
-/** The answered asks with no rendered row to settle on (shelf
- *  composition): a wire that named no tool_call_id, or a history whose
- *  call never reached the messages. Their Q→A receipts render
- *  at the transcript tail — content, never meta-narration. Stale asks
- *  render nothing: the meta-receipt rows were deleted, the quiet
- *  stale line with them. */
 function _unrowedAnsweredAsksOf(rows, elicitationCards) {
     const renderedCallIds = new Set();
     for (const row of rows) {
@@ -120,27 +72,11 @@ function _unrowedAnsweredAsksOf(rows, elicitationCards) {
     return elicitationCards.filter((card) => (card.toolCallId === null || !renderedCallIds.has(card.toolCallId)) &&
         card.status === "answered");
 }
-/** WHO claims the trailing liveness beat — the one arbiter. Exactly one
- *  element may say "work is live" at the transcript tail, across every
- *  host and every tail row kind. Precedence: a claiming tail row (a live
- *  fold, streaming prose, a delegation group with a running member —
- *  resolved through the SAME join the group row renders from); else
- *  `typing` elects the silence-gap dot; else `live` elects the standalone
- *  Working… headline; else none. The full table is in
- *  docs/transcript-surfaces.md and tests/liveness-claimants.test.tsx
- *  executes it. A host-provided empty surface on an empty log outranks
- *  everything here at the call site. The dot OUTRANKS the headline
- *  deliberately: the drill-in preview passes typing alongside live and
- *  keeps its dot; Transcript never passes typing. */
 function _trailingLivenessClaimantOf(displayRows, live, typing, dispatches) {
     const last = displayRows.at(-1);
     const tailClaims = last !== undefined &&
         ((last.kind === "run-fold" && _foldClaimsLiveness(last.members, live)) ||
             (last.kind === "assistant-text" && last.streaming) ||
-            // The group's own headline shimmers exactly when its resolved
-            // counts say a member runs — resolved through the SAME exported
-            // join the group row renders from (never a respelled predicate),
-            // so the arbiter and the row cannot drift.
             (last.kind === "subagent-group" &&
                 subagentOutcomeCountsOf(last.entries.map((entry) => resolvedSubagentEntryOf(entry, dispatches.byOrdinal))).running > 0));
     if (tailClaims) {
@@ -154,13 +90,8 @@ function _trailingLivenessClaimantOf(displayRows, live, typing, dispatches) {
     }
     return "none";
 }
-/** One live spelling of "this fold reads as running" — ActivityRail's
- *  headline and the trailing-liveness arbiter both read it. The trailing
- *  fold's turnLive bridges the quiet beat between one call's result and
- *  the next call's start, so back-to-back calls don't blink the headline. */
 export function _foldClaimsLiveness(members, turnLive) {
     return (turnLive ||
         members.some((row) => (row.kind === "reasoning" && row.streaming) ||
             (row.kind === "tool-call" && row.state === "input-available")));
 }
-//# sourceMappingURL=use-transcript-folds.js.map

package/dist/components/use-transcript.d.ts

@@ -3,39 +3,17 @@ import { type AssistantActivitySnapshot } from "../core/activity.js";
 import type { MarkerAnchorsSnapshot } from "../core/connection-epoch.js";
 import { type TranscriptRow } from "../core/transcript-rows.js";
 import type { UserTurnMeta } from "../core/user-turn-ledger.js";
-/** The transcript read surface: everything a host needs to render the
- *  assistant's replies, derived exactly the way the package chrome derives it. */
 export interface TranscriptSurface {
-    /** transcriptRowsOf(messages, markerAnchors, running, turnMeta) — the
-     *  pure interleave, identity-stable while its four inputs hold. */
     rows: readonly TranscriptRow[];
-    /** `rows` with the composer's optimistic echo appended (withPendingUserEcho).
-     *  Render this; a host that also paints its own bubble would double it. */
     displayRows: readonly TranscriptRow[];
-    /** runReadsAsWorking(activity.newestTurnStatus, decisionsPending) — the
-     *  machine's time. False for the send round trip, so a "working" indicator
-     *  should join the composer contract's pendingSend, as the chrome does. */
     running: boolean;
-    /** The newest turn is non-terminal — broader than `running`: the HITL
-     *  pauses (awaiting_input, parked) count. */
     turnOpen: boolean;
-    /** A member-actionable decision is live — the run is the MEMBER's time. */
     decisionsPending: boolean;
-    /** The four raw store reads, as plain values — so transcriptRowsOf(messages,
-     *  markerAnchors, running, turnMeta) type-checks verbatim for a host's own projection. */
     messages: readonly Message[];
     markerAnchors: MarkerAnchorsSnapshot;
     activity: AssistantActivitySnapshot;
     turnMeta: ReadonlyMap<string, UserTurnMeta>;
 }
-/**
- * The store's read side, projected: the message list and marker anchors
- * folded into the flat row list, plus the run-state facts the rows key on.
- * Mounting registers transcript presence (the lease) — what guarantees the
- * epoch connects and history paints by full replay; unmounting mid-turn changes nothing.
- */
 export declare function useTranscript(options?: {
-    /** The lease label the store's presence ledger records (the chrome's `surface` prop). */
     surface?: string;
 }): TranscriptSurface;
-//# sourceMappingURL=use-transcript.d.ts.map