@poodle64/librarian 2026.9.14 → 2026.9.16

package/README.md

@@ -1,12 +1,16 @@
 # @poodle64/librarian
 
-Milton's conversation surface, as a Svelte 5 package: the stream client, the
+An agent's conversation surface, as a Svelte 5 package: the stream client, the
 transcript state, and the chat components an app renders instead of
 rebuilding: the transcript with its own follow-scroll, the composer with
 attachments, citation chips and the source pane they open.
 
-Owned by the library. This is Milton's surface; design-system is its press.
-Change it here, consume it there.
+The persona is an argument. Name it once — `name="penny"` — and every word the
+package says is composed from it. Milton is the library's own persona and the
+default; no string in this package names him.
+
+Owned by the library. Design-system is its press: change it here, consume it
+there.
 
 ## What is here
 
@@ -44,16 +48,28 @@ pnpm add @poodle64/librarian @poodle64/ui @lucide/svelte
 and `shiki` are peer dependencies: declare them yourself so Renovate tracks
 their versions and `pnpm ls` shows them.
 
-The components style themselves with Tailwind utility classes, same as
-`@poodle64/ui`, so the same line is needed in the app's `app.css`:
+**No Tailwind content-scan line, and deliberately none.** These components
+carry their own CSS, written against the `--ds-*` tokens and compiled by
+whatever bundler the app already runs, so the transcript looks the same in
+every consumer whether or not that consumer scans `node_modules`. It did not
+always: the package styled itself with Tailwind utilities and asked each app
+for an `@source` line, Pebblestone's `app.css` never had one, and the console
+shipped a 2302px-wide transcript with no cards, no measure and unstyled
+tables — no build error, no lint hit, nothing failing. A package whose
+appearance depends on a line in its consumer's stylesheet does not have a
+look; it has a hope.
+
+What it does need is the token layer every app already imports:
 
 ```css
-@source '../node_modules/@poodle64/librarian/dist'; /* Tailwind content scan */
+@import '@poodle64/design-tokens/tokens.css';
 ```
 
-Without it the classes ship in `dist` but Tailwind's default content scan
-never sees `node_modules`, so nothing compiles for them — no build error, no
-lint hit, just an unstyled transcript.
+The composed page chrome this package borrows from `@poodle64/ui` (`Panel`)
+still follows that package's own `@source` line, which every app has.
+
+One knob: `--ds-lib-measure` (default `46rem`) sets the transcript's reading
+column. Set it on any ancestor.
 
 ## Consuming the package
 
@@ -213,7 +229,7 @@ behind it, so "not verified" would be a claim about a record nothing here
 ever read.
 
 An answer that settles having cited nothing says so, once, under the prose:
-"Milton answered this one without a source. He may not hold a document that
+"Milton answered this one without a source. There may be no document here that
 covers it." Only on a turn whose stream this surface actually watched finish
 — a turn read back out of `createHistory()` has no citations because history
 stores none, and labelling it as holding nothing would be a lie about an
@@ -235,7 +251,7 @@ second question by mistake.
 
 ### Where the answer starts
 
-Milton narrates between tool calls — "Let me also check whether…" — and the
+The persona narrates between tool calls — "Let me also check whether…" — and the
 caller stream gives that nowhere to arrive: it carries no `thinking` blocks
 at all, so narration is an ordinary `text` block, identical to the answer
 except in POSITION. `segment()` reads that position: a text block with any
@@ -246,23 +262,60 @@ is currently last renders as prose, and a tool call arriving after it
 re-homes it — which is why `segment()` is pure and re-derived per event
 rather than deciding once.
 
-The cost is an answer Milton interrupts to go back to the shelf: its first
+The cost is an answer the persona interrupts to go back to the shelf: its first
 half folds away. Position is the only signal the stream gives, and a rule
 read off the prose itself would be unexplainable the first time it misfired.
 
-### Changing the words
+### Who is speaking, and in what words
+
+Every user-visible string lives in `@poodle64/librarian/copy`, and every one
+of them is composed from the persona's name:
+
+```svelte
+<Conversation {turns} {running} name="penny" />
+<Composer bind:value {running} name="penny" {scope} {onscope} {onsubmit} {onstop} />
+```
+
+That one prop carries the working line ("Penny is looking…"), both composer
+placeholders, the uncited-answer note, both failure sentences, the scope
+label, the opening line, the name signed on every answer card and the
+accessible name of the scroll region. A slug is fine: `penny` renders as
+"Penny", `chief-engineer` as "Chief Engineer", and a name the host already
+capitalised is left exactly as written.
 
-Every user-visible string this package renders lives in
-`@poodle64/librarian/copy`, and every component takes a partial of it:
+A host that wants different words still overrides one at a time:
 
 ```svelte
-<Conversation {turns} {running} copy={{ notVerified: 'not checked yet' }} />
+<Conversation {turns} {running} name="penny" copy={{ notVerified: 'not checked yet' }} />
 ```
 
 Overriding one line leaves the rest as the package wrote them, and a key
 passed as `undefined` — the shape a host produces from state that has not
 loaded — is ignored rather than rendering nothing where a word belongs.
 
+### When the stream fails
+
+`ask()` never throws. A refused route, a `fetch` the browser blocks on CORS
+after an expired session redirects it, a 200 that turns out to be a login
+page, a connection that dies mid-answer and a stream that simply stops
+without a terminal frame all arrive as one `library_error` event and a
+finished iteration. That matters because the host's `for await` loop is what
+re-enables its Send button: a thrown generator left Pebblestone's console
+disabled, silent and waiting indefinitely every time a session expired.
+
+The event carries no words — this layer does not know whose voice to say them
+in — so the turn renders `copy.unreachable` in the persona's own name and
+settles, offering "Ask again".
+
+### Timestamps
+
+`Turn.at` (epoch ms) renders as a clock time on the question and the answer
+card, which is a different fact from the duration badge beside the actions. A
+host that persists conversations sets it; a host that does not gets one
+stamped when the turn first appears, and a turn already on screen at mount —
+one read back out of history — deliberately shows none rather than claiming
+it was asked this afternoon.
+
 ### The system preamble
 
 A host prepends its own instruction to every question (cadmus sends
@@ -290,16 +343,21 @@ pnpm run test         # build + vitest
 pnpm run screenshots  # the state grid, real engine (see below)
 ```
 
-`docs/screenshots/` is eleven states x three widths x both themes, taken by
+`docs/screenshots/` is thirteen states x three widths x both themes, taken by
 `scripts/screenshots.mjs` against the console's `/librarian` lab route
 running from its own static build. The same script asserts what a screenshot
 cannot: that nothing scrolls sideways at any width, that the source pane
 opens and closes from the keyboard with focus returning to the chip and is
 really draggable, that the scope statement folds once there is a
 conversation over it and reopens from that line, that a follow-up chip asks
-its question and takes the rest of the row with it, and that Milton's
+its question and takes the rest of the row with it, that the persona's
 between-tool narration is nowhere in the answer prose before the activity
-line is opened. It exits non-zero on any of them.
+line is opened, and that the reading column holds its 46rem measure and stays
+centred at every width. It exits non-zero on any of them.
+
+The console's `app.css` deliberately does NOT scan this package's `dist`, so
+the grid is taken in a consumer that compiles none of its Tailwind classes —
+which is the only way the measure claim above means anything.
 
 ```bash
 pnpm --filter @poodle64/console run build

package/dist/client.d.ts

@@ -68,5 +68,20 @@ export interface AskOptions {
     /** Override for the ambient `fetch`, e.g. a caller-authenticated wrapper. */
     fetch?: typeof fetch;
 }
-/** Async-iterate the events of one question. */
+/**
+ * Async-iterate the events of one question.
+ *
+ * It never throws. Every way a stream can fail to open or die half-way through
+ * — the network dropping, an expired session redirecting the POST to an
+ * identity provider the browser then blocks on CORS, a server closing the
+ * connection mid-answer — comes back as one `library_error` event and a
+ * finished iteration, because a host's loop is what re-enables its Send
+ * button. A thrown generator leaves that loop unfinished: Pebblestone's
+ * console sat with Send disabled and no message on screen, indefinitely,
+ * every time a session expired mid-conversation.
+ *
+ * The event carries no words. The words name a persona and this layer has no
+ * idea which one is speaking, so `copyFor(name).unreachable` supplies them
+ * where the turn is rendered.
+ */
 export declare function ask(options: AskOptions): AsyncGenerator<AgentEvent>;

package/dist/client.js

@@ -47,43 +47,113 @@ function requestInit(options, signal) {
         form.append('kind', options.kind);
     return { method: 'POST', credentials: 'include', body: form, signal };
 }
-/** Async-iterate the events of one question. */
+/**
+ * Async-iterate the events of one question.
+ *
+ * It never throws. Every way a stream can fail to open or die half-way through
+ * — the network dropping, an expired session redirecting the POST to an
+ * identity provider the browser then blocks on CORS, a server closing the
+ * connection mid-answer — comes back as one `library_error` event and a
+ * finished iteration, because a host's loop is what re-enables its Send
+ * button. A thrown generator leaves that loop unfinished: Pebblestone's
+ * console sat with Send disabled and no message on screen, indefinitely,
+ * every time a session expired mid-conversation.
+ *
+ * The event carries no words. The words name a persona and this layer has no
+ * idea which one is speaking, so `copyFor(name).unreachable` supplies them
+ * where the turn is rendered.
+ */
 export async function* ask(options) {
     const doFetch = options.fetch ?? fetch;
-    const response = await doFetch(options.endpoint ?? '/api/agent/ask', requestInit(options, options.signal));
-    if (!response.ok || !response.body) {
-        yield { type: 'library_error', error: "Milton can't be reached right now." };
+    let response;
+    try {
+        response = await doFetch(options.endpoint ?? '/api/agent/ask', requestInit(options, options.signal));
+    }
+    catch {
+        // A reader who pressed stop asked for this one; it is not a failure.
+        if (options.signal?.aborted)
+            return;
+        yield { type: 'library_error' };
+        return;
+    }
+    // A session that expired mid-conversation is the shape this catches: the
+    // POST is redirected to a login page, which answers 200 with HTML, and a
+    // reader whose stream "opened" then waits for frames that can never come.
+    //
+    // A response that DECLARES something other than an event stream is refused;
+    // one that declares nothing is read anyway. A route behind a proxy that
+    // drops the header is still streaming, and refusing it here would be this
+    // layer breaking a working consumer over a header — the terminal-frame
+    // check at the end of this function catches it if it really says nothing.
+    const kind = (response.headers.get('content-type') ?? '').toLowerCase();
+    if (!response.ok || !response.body || (kind && !kind.includes('text/event-stream'))) {
+        yield { type: 'library_error' };
         return;
     }
     const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
     // Frames are separated by a blank line and split across network reads at
     // arbitrary points, so the tail of each read is carried rather than parsed.
     let buffered = '';
+    // A turn that ends with no terminal frame ended by accident. Tracked here
+    // rather than left to the renderer, which cannot tell a stream that died
+    // from one still arriving.
+    let terminal = false;
+    /** One frame's `data:` lines, as the event they carry. */
+    function parse(frame) {
+        // `data:` only — the type lives inside the payload where Claude Code
+        // puts it, so there is no second place to look.
+        const data = frame
+            .split('\n')
+            .filter((l) => l.startsWith('data:'))
+            .map((l) => l.slice(5).trim())
+            .join('');
+        if (!data)
+            return null;
+        try {
+            return JSON.parse(data);
+        }
+        catch {
+            // A partial frame at the end of a stream is not an error.
+            return null;
+        }
+    }
     for (;;) {
-        const { done, value } = await reader.read();
-        if (done)
+        let chunk;
+        try {
+            chunk = await reader.read();
+        }
+        catch {
+            if (options.signal?.aborted)
+                return;
+            yield { type: 'library_error' };
+            return;
+        }
+        if (chunk.done)
             break;
-        buffered += value;
+        buffered += chunk.value;
         let boundary = buffered.indexOf('\n\n');
         while (boundary !== -1) {
             const frame = buffered.slice(0, boundary);
             buffered = buffered.slice(boundary + 2);
             boundary = buffered.indexOf('\n\n');
-            // `data:` only — the type lives inside the payload where Claude Code
-            // puts it, so there is no second place to look.
-            const data = frame
-                .split('\n')
-                .filter((l) => l.startsWith('data:'))
-                .map((l) => l.slice(5).trim())
-                .join('');
-            if (!data)
+            const event = parse(frame);
+            if (!event)
                 continue;
-            try {
-                yield JSON.parse(data);
-            }
-            catch {
-                /* a partial frame at end of stream is not an error */
-            }
+            if (event.type === 'result' || event.type === 'library_error')
+                terminal = true;
+            yield event;
         }
     }
+    // The last frame of a stream that closed cleanly without its blank line.
+    // It is usually the terminal `result`, carrying the duration and the
+    // sources, so dropping it both loses the answer's furniture and makes a
+    // finished turn look like one that died.
+    const last = parse(buffered);
+    if (last) {
+        if (last.type === 'result' || last.type === 'library_error')
+            terminal = true;
+        yield last;
+    }
+    if (!terminal && !options.signal?.aborted)
+        yield { type: 'library_error' };
 }

package/dist/components/activity-group/activity-group.svelte

@@ -3,10 +3,10 @@
 
   Not a stack. Fifteen tool rows between the question and the first word of the
   answer is the machine room on show, and a running commentary of "Let me
-  check…" is worse: it narrates a mechanism Milton is under instruction never
-  to mention. So there is exactly one row in every state — "Working…" while it
-  runs, a count of what was done once it settles — and the steps are behind a
-  disclosure for the reader who wants them.
+  check…" is worse: it narrates a mechanism the persona is under instruction
+  never to mention. So there is exactly one row in every state — "Working…"
+  while it runs, a count of what was done once it settles — and the steps are
+  behind a disclosure for the reader who wants them.
 
   That commentary is a step in here too. It reaches the caller as an ordinary
   `text` block, not a `thinking` one, so `segment()` re-homes any text with a
@@ -36,18 +36,20 @@
 <div>
 	<button
 		type="button"
-		class="text-muted-foreground hover:text-foreground flex items-center gap-1.5 text-sm transition-colors"
+		class="ds-lib-activity-toggle"
 		onclick={() => (expanded = !expanded)}
 		aria-expanded={expanded}
 	>
-		<ChevronRightIcon class="size-3.5 transition-transform {expanded ? 'rotate-90' : ''}" />
+		<span class="ds-lib-activity-chevron" class:is-open={expanded}>
+			<ChevronRightIcon size={14} />
+		</span>
 		{#if live}
-			<span class="bg-status-info size-1.5 shrink-0 animate-pulse rounded-full"></span>
+			<span class="ds-lib-activity-dot"></span>
 		{/if}
 		<span>{label}</span>
 	</button>
 	{#if expanded}
-		<div class="border-border mt-2 ml-1.75 flex flex-col gap-1.5 border-l pl-3">
+		<div class="ds-lib-activity-steps">
 			{#each group.steps as step (step.block.index)}
 				{#if step.block.kind === 'tool'}
 					<ToolRow block={step.block} repeats={step.repeats} running={live} />
@@ -58,3 +60,69 @@
 		</div>
 	{/if}
 </div>
+
+<style>
+	.ds-lib-activity-toggle {
+		display: flex;
+		align-items: center;
+		gap: 0.375rem;
+		border: 0;
+		background: none;
+		padding: 0;
+		color: var(--ds-color-muted-foreground);
+		font: inherit;
+		font-size: 0.875rem;
+		line-height: 1.25rem;
+		cursor: pointer;
+		transition: color 150ms ease;
+	}
+
+	.ds-lib-activity-toggle:hover {
+		color: var(--ds-color-foreground);
+	}
+
+	.ds-lib-activity-chevron {
+		display: flex;
+		flex: none;
+		transition: transform 150ms ease;
+	}
+
+	.ds-lib-activity-chevron.is-open {
+		transform: rotate(90deg);
+	}
+
+	.ds-lib-activity-dot {
+		width: 0.375rem;
+		height: 0.375rem;
+		flex: none;
+		border-radius: var(--ds-radius-full);
+		background: var(--ds-color-status-info);
+		animation: ds-lib-activity-pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
+	}
+
+	.ds-lib-activity-steps {
+		display: flex;
+		flex-direction: column;
+		gap: 0.375rem;
+		margin-top: 0.5rem;
+		margin-inline-start: 0.4375rem;
+		border-inline-start: 1px solid var(--ds-color-border);
+		padding-inline-start: 0.75rem;
+	}
+
+	@keyframes ds-lib-activity-pulse {
+		50% {
+			opacity: 0.4;
+		}
+	}
+
+	@media (prefers-reduced-motion: reduce) {
+		.ds-lib-activity-dot {
+			animation: none;
+		}
+
+		.ds-lib-activity-chevron {
+			transition: none;
+		}
+	}
+</style>