@poodle64/librarian 2026.9.18 → 2026.9.19

package/dist/components/artefact-pane/artefact-pane.svelte

@@ -1,5 +1,5 @@
 <!--
-  A study artefact, open in the reading column.
+  An artefact that is its answer's own prose, open in the reading column.
 
   The same shell shape `DocumentPane` uses (a column at 64rem, a bottom sheet
   below it) because decision 2 of the agent surface is that a colleague never
@@ -61,10 +61,10 @@
 
 	<header class="ds-lib-pane-header">
 		<div class="ds-lib-pane-heading">
-			<h2 class="ds-lib-pane-title">{turn.title ?? 'Briefing'}</h2>
-			<p class="ds-lib-pane-subtitle">
-				Briefing doc · {sources.length} source{sources.length === 1 ? '' : 's'}
-			</p>
+			<h2 class="ds-lib-pane-title">{turn.artefact?.title}</h2>
+			{#if turn.artefact?.summary}
+				<p class="ds-lib-pane-subtitle">{turn.artefact.summary}</p>
+			{/if}
 		</div>
 		<button
 			bind:this={closeButton}

package/dist/components/composer/composer.svelte

@@ -30,7 +30,9 @@
 	interface Props {
 		value: string;
 		running: boolean;
-		scope: Scope;
+		/** What the next message is about. A surface with one scope — a
+		 *  session over one document — passes none and offers no choice. */
+		scope?: Scope;
 		/** Files to send with the next question. Cleared by the caller on send. */
 		files?: File[];
 		/** Names for the two narrower scopes; absent means that scope is unavailable. */
@@ -38,7 +40,7 @@
 		collectionName?: string;
 		/** Hides the paperclip for a host whose ask route takes no files. */
 		attachments?: boolean;
-		onscope: (scope: Scope) => void;
+		onscope?: (scope: Scope) => void;
 		onsubmit: () => void;
 		onstop: () => void;
 		/** Asks for a study artefact instead of an ordinary answer. Omit and no
@@ -50,6 +52,10 @@
 		name?: string;
 		/** Overrides for the package's own words. */
 		copy?: Partial<LibrarianCopy>;
+		/** One quiet line in the box's footer, where a scope choice would
+		 *  sit, in the host's words: what sending does here ("It carries on
+		 *  from where it stopped."). */
+		note?: string;
 	}
 
 	let {
@@ -65,7 +71,8 @@
 		onstop,
 		onbriefing,
 		name = DEFAULT_PERSONA,
-		copy
+		copy,
+		note
 	}: Props = $props();
 
 	const words = $derived(resolveCopy(copy, name));
@@ -87,7 +94,7 @@
 	// passing a name — no pick to make, so the row renders nothing rather
 	// than a chip that only ever reselects itself (design-system, the
 	// fixed-scope Composer defect).
-	const hasChoice = $derived(choices.length > 1);
+	const hasChoice = $derived(scope !== undefined && choices.length > 1);
 
 	// Three chips in a narrow column clipped all three to fragments
 	// ("defence-s…", "All colle…"). Wrapping beats truncating: a chip a reader
@@ -266,12 +273,14 @@
 							type="button"
 							class="ds-lib-scope-chip"
 							class:is-chosen={scope === choice.id}
-							onclick={() => onscope(choice.id)}
+							onclick={() => onscope?.(choice.id)}
 						>
 							{choice.label}
 						</button>
 					{/each}
 				</div>
+			{:else if note}
+				<span class="ds-lib-note">{note}</span>
 			{/if}
 			<span class="ds-lib-spacer"></span>
 			{#if running}
@@ -502,6 +511,12 @@
 		flex: 1;
 	}
 
+	.ds-lib-note {
+		min-width: 0;
+		color: var(--ds-color-muted-foreground);
+		font-size: var(--ds-text-2xs);
+	}
+
 	.ds-lib-rejected {
 		margin: 0;
 		padding: 0.375rem 0.25rem 0;

package/dist/components/composer/composer.svelte.d.ts

@@ -3,7 +3,9 @@ export type Scope = 'document' | 'collection' | 'library';
 interface Props {
     value: string;
     running: boolean;
-    scope: Scope;
+    /** What the next message is about. A surface with one scope — a
+     *  session over one document — passes none and offers no choice. */
+    scope?: Scope;
     /** Files to send with the next question. Cleared by the caller on send. */
     files?: File[];
     /** Names for the two narrower scopes; absent means that scope is unavailable. */
@@ -11,7 +13,7 @@ interface Props {
     collectionName?: string;
     /** Hides the paperclip for a host whose ask route takes no files. */
     attachments?: boolean;
-    onscope: (scope: Scope) => void;
+    onscope?: (scope: Scope) => void;
     onsubmit: () => void;
     onstop: () => void;
     /** Asks for a study artefact instead of an ordinary answer. Omit and no
@@ -23,6 +25,10 @@ interface Props {
     name?: string;
     /** Overrides for the package's own words. */
     copy?: Partial<LibrarianCopy>;
+    /** One quiet line in the box's footer, where a scope choice would
+     *  sit, in the host's words: what sending does here ("It carries on
+     *  from where it stopped."). */
+    note?: string;
 }
 declare const Composer: import("svelte").Component<Props, {}, "value" | "files">;
 type Composer = ReturnType<typeof Composer>;

package/dist/components/conversation/conversation.svelte

@@ -11,7 +11,7 @@
 <script lang="ts">
 	import type { Snippet } from 'svelte';
 	import ArrowDownIcon from '@lucide/svelte/icons/arrow-down';
-	import type { Turn } from '../../transcript.svelte';
+	import type { DescribeTool, Turn } from '../../transcript.svelte';
 	import type { Citation, LoadDocument } from '../../citations';
 	import { DEFAULT_PERSONA, personaName, resolveCopy, type LibrarianCopy } from '../../copy';
 	import { FollowScroll } from '../../follow-scroll.svelte';
@@ -55,6 +55,18 @@
 		copy?: Partial<LibrarianCopy>;
 		/** Enables the source pane. Without it, chips render but do not open. */
 		loadDocument?: LoadDocument;
+		/** Takes every citation tap instead, for a host that shows the source
+		 *  in a viewer of its own. */
+		oncite?: (citation: Citation) => void;
+		/** Takes every artefact card's tap, for a host that shows an artefact
+		 *  in a column of its own. Without it, an artefact that IS its answer
+		 *  opens in this surface's own pane, and any other informs and does
+		 *  not open. */
+		onopenartefact?: (turn: Turn) => void;
+		/** The id of the turn whose artefact the host is showing now. */
+		showing?: string;
+		/** The persona's own words for its tools, and what they read. */
+		describeTool?: DescribeTool;
 		collectionNames?: Set<string>;
 		/** The composer, rendered INSIDE the transcript column so the source
 		 *  pane narrows it too — a composer the host places outside slides
@@ -75,6 +87,10 @@
 		onsuggest,
 		copy,
 		loadDocument,
+		oncite,
+		onopenartefact,
+		showing,
+		describeTool,
 		collectionNames = new Set(),
 		composer
 	}: Props = $props();
@@ -140,7 +156,8 @@
 	// colleague who just asked for one is asking to read it, not merely to
 	// see that it exists. Fires on the RUNNING → settled transition only, so
 	// reopening a past conversation whose last turn happens to be an
-	// artefact does not reopen a pane the reader may have since closed.
+	// artefact does not reopen a pane the reader may have since closed. A
+	// host that opens artefacts itself decides this for itself.
 	//
 	// Plain, not `$state`: read and written in the same effect, which would
 	// otherwise re-trigger itself forever (the pattern this file's `seen`
@@ -148,7 +165,13 @@
 	let wasRunning = false;
 	$effect(() => {
 		const last = turns.at(-1);
-		if (wasRunning && !running && last?.kind === 'artefact' && !last.outcome?.isError) {
+		if (
+			!onopenartefact &&
+			wasRunning &&
+			!running &&
+			last?.artefact?.isAnswer &&
+			!last.outcome?.isError
+		) {
 			column = { kind: 'artefact', turn: last };
 		}
 		wasRunning = running;
@@ -165,14 +188,23 @@
 	}
 
 	function cite(citation: Citation) {
+		if (oncite) return oncite(citation);
 		// A citation derived from the prose has no id to read, so its chip is
 		// legible but inert rather than opening an empty pane. Replaces
 		// whatever the column held, artefact included — never a second pane.
 		if (loadDocument && citation.document_id) column = { kind: 'document', citation };
 	}
 
-	function openArtefact(turn: Turn) {
-		column = { kind: 'artefact', turn };
+	/** Who opens this turn's artefact, if anyone can. */
+	function opener(turn: Turn): (() => void) | undefined {
+		if (onopenartefact) return () => onopenartefact(turn);
+		if (turn.artefact?.isAnswer) return () => (column = { kind: 'artefact', turn });
+		return undefined;
+	}
+
+	function isShowing(turn: Turn): boolean {
+		if (onopenartefact) return showing === turn.id;
+		return column?.kind === 'artefact' && column.turn.id === turn.id;
 	}
 </script>
 
@@ -235,10 +267,11 @@
 							copy={words}
 							name={who}
 							at={turn.at ?? stamps[turn.id]}
-							kind={turn.kind}
-							title={turn.title}
-							onopenartefact={() => openArtefact(turn)}
-							oncite={cite}
+							artefact={turn.artefact}
+							artefactOpen={isShowing(turn)}
+							onopenartefact={opener(turn)}
+							{describeTool}
+							oncite={oncite || loadDocument ? cite : undefined}
 							onregenerate={index === turns.length - 1 && !running ? onregenerate : undefined}
 							onsuggest={index === turns.length - 1 && !running ? onsuggest : undefined}
 						/>
@@ -282,8 +315,12 @@
 </div>
 
 <style>
+	/* `min-width: 0` for a host that sets this in a row beside columns of its
+	   own: a flex item's automatic minimum is its widest content, and a table
+	   in an answer then pushed the whole page sideways at 390. */
 	.ds-lib-surface {
 		display: flex;
+		min-width: 0;
 		min-height: 0;
 		flex: 1;
 	}

package/dist/components/conversation/conversation.svelte.d.ts

@@ -1,6 +1,6 @@
 import type { Snippet } from 'svelte';
-import type { Turn } from '../../transcript.svelte';
-import type { LoadDocument } from '../../citations';
+import type { DescribeTool, Turn } from '../../transcript.svelte';
+import type { Citation, LoadDocument } from '../../citations';
 import { type LibrarianCopy } from '../../copy';
 interface Props {
     turns: Turn[];
@@ -32,6 +32,18 @@ interface Props {
     copy?: Partial<LibrarianCopy>;
     /** Enables the source pane. Without it, chips render but do not open. */
     loadDocument?: LoadDocument;
+    /** Takes every citation tap instead, for a host that shows the source
+     *  in a viewer of its own. */
+    oncite?: (citation: Citation) => void;
+    /** Takes every artefact card's tap, for a host that shows an artefact
+     *  in a column of its own. Without it, an artefact that IS its answer
+     *  opens in this surface's own pane, and any other informs and does
+     *  not open. */
+    onopenartefact?: (turn: Turn) => void;
+    /** The id of the turn whose artefact the host is showing now. */
+    showing?: string;
+    /** The persona's own words for its tools, and what they read. */
+    describeTool?: DescribeTool;
     collectionNames?: Set<string>;
     /** The composer, rendered INSIDE the transcript column so the source
      *  pane narrows it too — a composer the host places outside slides

package/dist/components/tool-row/tool-row.svelte

@@ -6,12 +6,13 @@
   five separate events rather than one train of thought.
 
   The row says what the persona DID, in a reader's own words — never the
-  tool's name or the raw command it ran. Expanding a settled row shows what
-  came back, never what was typed.
+  tool's name or the raw command it ran: the host's `DescribeTool`, or the
+  package's own `describe()`. Expanding a settled row shows what came back,
+  never what was typed.
 -->
 <script lang="ts">
 	import ChevronRightIcon from '@lucide/svelte/icons/chevron-right';
-	import { describe, type ToolBlock } from '../../transcript.svelte';
+	import { describe, type ToolBlock, type ToolWords } from '../../transcript.svelte';
 
 	interface Props {
 		block: ToolBlock;
@@ -19,15 +20,21 @@
 		/** Identical consecutive steps folded into this row — five pages of one
 		 *  document is one act of reading to a human. */
 		repeats?: number;
+		/** The call in the persona's words. Absent takes the package's own. */
+		words?: ToolWords;
 	}
 
-	let { block, running, repeats = 1 }: Props = $props();
+	let { block, running, repeats = 1, words }: Props = $props();
 	let open = $state(false);
 
 	const settled = $derived(block.result !== undefined);
-	const said = $derived(describe(block));
+	const said = $derived(words ?? describe(block));
 	const tone = $derived(block.isError ? 'error' : settled ? 'success' : 'info');
-	const lines = $derived(block.result ? block.result.split('\n').length : 0);
+	const again = $derived(
+		said.repeat
+			? `· ${repeats} ${repeats === 1 ? said.repeat[0] : said.repeat[1]}`
+			: `× ${repeats}`
+	);
 </script>
 
 <div class="ds-lib-tool">
@@ -45,7 +52,7 @@
 		<span class="ds-lib-tool-said">
 			<span class="ds-lib-tool-verb">{said.verb}</span>
 			{#if said.object}<span class="ds-lib-tool-object">{said.object}</span>{/if}
-			{#if repeats > 1}<span>· {repeats} pages</span>{/if}
+			{#if repeats > 1}<span>{again}</span>{/if}
 		</span>
 	</button>
 
@@ -55,8 +62,8 @@
 				<pre class="ds-lib-tool-result">{block.result}</pre>
 			{/if}
 		</div>
-	{:else if settled && lines > 0}
-		<p class="ds-lib-tool-lines">{lines === 1 ? '1 line' : `${lines} lines`}</p>
+	{:else if said.detail}
+		<p class="ds-lib-tool-lines">{said.detail}</p>
 	{/if}
 </div>
 

package/dist/components/tool-row/tool-row.svelte.d.ts

@@ -1,10 +1,12 @@
-import { type ToolBlock } from '../../transcript.svelte';
+import { type ToolBlock, type ToolWords } from '../../transcript.svelte';
 interface Props {
     block: ToolBlock;
     running: boolean;
     /** Identical consecutive steps folded into this row — five pages of one
      *  document is one act of reading to a human. */
     repeats?: number;
+    /** The call in the persona's words. Absent takes the package's own. */
+    words?: ToolWords;
 }
 declare const ToolRow: import("svelte").Component<Props, {}, "">;
 type ToolRow = ReturnType<typeof ToolRow>;

package/dist/copy.d.ts

@@ -52,6 +52,9 @@ export interface LibrarianCopy {
     jumpToLatest: string;
     closeSource: string;
     documentUnavailable: string;
+    /** An artefact card's action, and the same action while it is open. */
+    openArtefact: string;
+    showingArtefact: string;
 }
 /**
  * The display name for a persona a host identified by its slug.

package/dist/copy.js

@@ -72,7 +72,9 @@ export function copyFor(name = DEFAULT_PERSONA) {
         askAgain: 'Ask again',
         jumpToLatest: 'Jump to latest',
         closeSource: 'Close source',
-        documentUnavailable: "That document can't be opened right now."
+        documentUnavailable: "That document can't be opened right now.",
+        openArtefact: 'Open',
+        showingArtefact: 'Showing'
     };
 }
 /** The library's own words, for a host that names no persona. */

package/dist/session.svelte.d.ts

@@ -0,0 +1,31 @@
+/**
+ * A whole session as a conversation: every run a stream carries, each one a
+ * turn with the reader's words on one side and the persona's on the other.
+ *
+ * `Transcript` folds the events of ONE question the host asked. A session the
+ * APP started — a job that reads a document with nobody asking — is a
+ * different stream: its prompt and every later message arrive as the CLI
+ * echoes each one back (`--replay-user-messages`), and each run ends in its
+ * own `result`. So a replayed user frame opens a turn, everything after it
+ * folds into that turn, and its `result` settles it.
+ *
+ * Every Claude Code event carries a `uuid`, and one already folded is
+ * skipped: a watch route replays from the first event, so opening it again
+ * after the session moves on folds only what is new. A frame the server adds
+ * itself (an error, the library's citations) carries none, and is known by
+ * the event it follows.
+ */
+import type { AgentEvent } from './client';
+import { type Turn } from './transcript.svelte';
+export declare class Session {
+    #private;
+    /** One per run, in order: plain objects, so a host may spread one to add
+     *  its own `artefact`. */
+    turns: Turn[];
+    /** Bumped on every applied event — see `Transcript.version`. */
+    version: number;
+    /** The last run has started and not settled. A run the reader stopped
+     *  never settles, so a host ANDs this with its own "the stream is open". */
+    get working(): boolean;
+    apply(event: AgentEvent): void;
+}

package/dist/session.svelte.js

@@ -0,0 +1,105 @@
+/**
+ * A whole session as a conversation: every run a stream carries, each one a
+ * turn with the reader's words on one side and the persona's on the other.
+ *
+ * `Transcript` folds the events of ONE question the host asked. A session the
+ * APP started — a job that reads a document with nobody asking — is a
+ * different stream: its prompt and every later message arrive as the CLI
+ * echoes each one back (`--replay-user-messages`), and each run ends in its
+ * own `result`. So a replayed user frame opens a turn, everything after it
+ * folds into that turn, and its `result` settles it.
+ *
+ * Every Claude Code event carries a `uuid`, and one already folded is
+ * skipped: a watch route replays from the first event, so opening it again
+ * after the session moves on folds only what is new. A frame the server adds
+ * itself (an error, the library's citations) carries none, and is known by
+ * the event it follows.
+ */
+import { contentOf, fold, foldState } from './transcript.svelte';
+/** The events a run is made of. One arriving after its turn settled is the
+ *  next run, whether or not its prompt was echoed. */
+const RUN = new Set(['stream_event', 'assistant', 'user', 'result']);
+/** Everything else that lands on a turn: the library's trailing frames, and
+ *  a stream that broke. Anything else (`system`, rate limits) is the CLI
+ *  talking about itself. */
+const FOLDED = new Set([...RUN, 'library_error', 'citations', 'suggestions']);
+export class Session {
+    /** One per run, in order: plain objects, so a host may spread one to add
+     *  its own `artefact`. */
+    turns = $state([]);
+    /** Bumped on every applied event — see `Transcript.version`. */
+    version = $state(0);
+    #folds = [];
+    // A plain Set, as `Transcript`'s fold map is: nothing renders it.
+    // eslint-disable-next-line svelte/prefer-svelte-reactivity
+    #seen = new Set();
+    /** The last `uuid` in stream order, folded or skipped. */
+    #after = '';
+    /** The last run has started and not settled. A run the reader stopped
+     *  never settles, so a host ANDs this with its own "the stream is open". */
+    get working() {
+        const last = this.turns.at(-1);
+        return last !== undefined && last.outcome === null;
+    }
+    apply(event) {
+        const key = event.uuid ?? `${this.#after}|${JSON.stringify(event)}`;
+        if (event.uuid)
+            this.#after = event.uuid;
+        if (this.#seen.has(key))
+            return;
+        this.#seen.add(key);
+        if (event.type === 'user' && event.isReplay) {
+            this.#open(event.uuid ?? `turn-${this.turns.length}`, said(event), stamp(event));
+            this.version += 1;
+            return;
+        }
+        if (!FOLDED.has(event.type))
+            return;
+        // Settled by its own `result`. A stream that broke mid-run is not: the
+        // run goes on, and a watch opened again folds the rest onto it.
+        const last = this.turns.at(-1);
+        const settled = last?.outcome != null && !last.outcome.unreachable;
+        // The watch broke while nothing was running, and no run failed.
+        if (event.type === 'library_error' && settled)
+            return;
+        // A run whose prompt was never echoed — a session started without the
+        // replay flag, or one that failed before it said anything — still has
+        // an answer to show; its question is simply not on the wire.
+        if (!last || (settled && RUN.has(event.type))) {
+            this.#open(`turn-${this.turns.length}`, '', undefined);
+        }
+        else if (last.outcome?.unreachable && RUN.has(event.type)) {
+            // The stream came back and the run is still going.
+            last.outcome = null;
+        }
+        fold(this.turns[this.turns.length - 1], this.#folds[this.#folds.length - 1], event);
+        this.version += 1;
+    }
+    #open(id, question, at) {
+        this.turns.push({
+            id,
+            question,
+            at,
+            blocks: [],
+            outcome: null,
+            citations: [],
+            suggestions: []
+        });
+        this.#folds.push(foldState());
+    }
+}
+/** The words of a replayed frame: a bare string, or its text blocks. */
+function said(event) {
+    const content = event.message?.content;
+    if (typeof content === 'string')
+        return content;
+    return contentOf(event)
+        .filter((block) => block.type === 'text' && typeof block.text === 'string')
+        .map((block) => block.text)
+        .join('\n\n');
+}
+/** When the CLI consumed the frame, which is when this run began. */
+function stamp(event) {
+    const at = event.timestamp ? Date.parse(event.timestamp) : NaN;
+    return Number.isNaN(at) ? undefined : at;
+}