@poodle64/librarian 2026.9.6 → 2026.9.8

package/README.md

@@ -1,34 +1,35 @@
 # @poodle64/librarian
 
 Milton's conversation surface, as a Svelte 5 package: the stream client, the
-transcript state, and the chat components (transcript, composer, markdown,
-tool/thinking rows, the working indicator). An app renders the librarian
-instead of rebuilding it.
+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.
+Owned by the library. This is Milton's surface; design-system is its press.
 Change it here, consume it there.
 
 ## What is here
 
 ```text
 src/lib/
-  client.ts               ask(): streams Claude Code's OWN events, unaltered
+  client.ts                ask(): streams Claude Code's OWN events, unaltered
   transcript.svelte.ts     Transcript state, the fold/segment/describe helpers
-  history.svelte.ts        the browser-held conversation list, namespaced per caller
+  citations.ts             the Citation shape, `[n]` markers, "## Sources"
+  attachments.ts           what a reader may attach, and the limits
+  follow-scroll.svelte.ts  follow the stream until the reader disagrees
+  history.svelte.ts        the browser-held conversation list, per caller
   components/
-    agent-transcript/       one question and everything the agent did answering it
-    composer/                the input box: value, scope chips, send/stop
-    markdown/                sanitised, streaming-safe markdown + syntax highlighting
-    activity-group/          a run of tool calls, collapsed to one line
-    tool-row/                one tool call
-    thinking-row/            one thinking block
-    working/                 the pre-first-token "something is happening" indicator
+    conversation/          the whole reading surface: scroll, pill, pane, composer slot
+    agent-transcript/      one question and everything Milton did answering it
+    document-pane/         the cited document, open at the cited passage
+    composer/              the input box: attachments, scope chips, send/stop
+    markdown/              sanitised, streaming-safe markdown + highlighting
+    activity-group/        a whole investigation, as one quiet line
+    tool-row/              one tool call
+    thinking-row/          one thinking block
+    working/               the pre-first-token "something is happening" indicator
 ```
 
-Deliberately excluded: the library console's own `CorpusTree`, `DocumentPane`
-and collection picker. Those are furniture for browsing a corpus, not part of
-talking to Milton, and stay in the library's own frontend.
-
 ## Installation
 
 ```bash
@@ -52,37 +53,53 @@ lint hit, just an unstyled transcript.
 
 ## Consuming the package
 
-Every export is its own subpath, matching `@poodle64/ui`'s convention:
+Every export is its own subpath, matching `@poodle64/ui`'s convention.
+`Conversation` owns the scroll container and the source pane, so the host
+gives it a height and a composer and nothing else:
 
 ```svelte
 <script lang="ts">
 	import { ask } from '@poodle64/librarian/client';
-	import { Transcript } from '@poodle64/librarian/transcript';
-	import AgentTranscript from '@poodle64/librarian/agent-transcript';
+	import { Transcript, type Turn } from '@poodle64/librarian/transcript';
+	import Conversation from '@poodle64/librarian/conversation';
 	import Composer from '@poodle64/librarian/composer';
 
 	let question = $state('');
+	let files = $state<File[]>([]);
 	let running = $state(false);
+	let turns = $state<Turn[]>([]);
+	let asked = $state('');
 	const transcript = new Transcript();
 	let controller: AbortController | null = null;
 
 	async function submit() {
-		const asked = question.trim();
+		asked = question.trim();
 		if (!asked || running) return;
+		await run(asked, files);
+	}
 
+	async function run(text: string, attached: File[]) {
 		question = '';
+		files = [];
 		running = true;
 		transcript.reset();
+		turns = [...turns, { id: crypto.randomUUID(), question: text, blocks: [], outcome: null }];
 		controller = new AbortController();
 
 		try {
 			for await (const event of ask({
-				question: asked,
+				question: text,
+				files: attached,
 				endpoint: '/api/caller/ask',
 				signal: controller.signal
 			})) {
 				transcript.apply(event);
-				if (event.type === 'result' || event.type === 'library_error') running = false;
+				const live = turns.at(-1);
+				if (live) {
+					live.blocks = transcript.blocks;
+					live.outcome = transcript.outcome;
+					live.citations = transcript.citations;
+				}
 			}
 		} finally {
 			running = false;
@@ -90,31 +107,86 @@ Every export is its own subpath, matching `@poodle64/ui`'s convention:
 		}
 	}
 
-	function stop() {
-		controller?.abort();
-		running = false;
+	async function loadDocument(id: string) {
+		const response = await fetch(`/api/sources/documents/${id}/content?page=all`);
+		const doc = await response.json();
+		return { title: doc.document_title, sections: sectionsFrom(doc) };
 	}
 </script>
 
-<AgentTranscript {question} blocks={transcript.blocks} outcome={transcript.outcome} {running} />
+<div class="flex h-dvh flex-col">
+	<Conversation
+		{turns}
+		{running}
+		version={transcript.version}
+		welcome="Ask Milton about pay, allowances, leave and conditions of service."
+		examples={['How much recreation leave do I get?']}
+		onexample={(q) => (question = q)}
+		onregenerate={() => run(asked, [])}
+		{loadDocument}
+	>
+		{#snippet composer()}
+			<Composer
+				bind:value={question}
+				bind:files
+				{running}
+				scope="library"
+				onscope={() => {}}
+				onsubmit={submit}
+				onstop={() => controller?.abort()}
+			/>
+		{/snippet}
+	</Conversation>
+</div>
+```
+
+`version` is what keeps the scroll following: streaming grows an EXISTING
+block's text in place, so a count of turns never changes and an effect keyed
+on it fires once and never again.
+
+### What the host must wire
+
+| Concern                  | How                                                                                                                                                                                         |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| The ask route            | `ask({ endpoint })`: a room's `/api/rooms/{id}/ask`, a caller's `/api/caller/ask`                                                                                                          |
+| Attachments              | nothing: `ask()` posts multipart (`question`, `resume`, `collections[]`, `files[]`) whenever `files` is non-empty, and JSON when it is not. The route must accept both                      |
+| Reading a cited document | `loadDocument(document_id) => Promise<{title, sections: [{anchor, heading, text}]}>`, proxied through the app's own authenticated route (cadmus: `GET /api/sources/documents/{id}/content`) |
+| Asking again             | `onregenerate`: re-send the last question as a NEW turn; the package exposes the action and never re-asks by itself                                                                        |
+| The empty state          | `welcome` and up to three `examples`                                                                                                                                                        |
+
+Nothing here fetches on its own behalf. The library's document read is
+authenticated, and a package that called it directly would be reaching past
+the app's proxy with a session it has no business holding.
+
+### Citations
 
-<Composer
-	bind:value={question}
-	{running}
-	scope="library"
-	onscope={() => {}}
-	onsubmit={submit}
-	onstop={stop}
-/>
+The library emits one SSE frame after the final assistant text:
+
+```json
+{
+	"type": "citations",
+	"items": [
+		{ "n": 1, "document_id": "…", "title": "…", "section": "…", "anchor": "…", "snippet": "…" }
+	]
+}
 ```
 
-`ask()`'s `endpoint` defaults to `/api/agent/ask`; pass whatever route the
-consuming app mounts (a room's `/api/rooms/{id}/ask`, a caller's
-`/api/caller/ask`) and an optional `fetch` for a caller-authenticated wrapper.
+`Transcript.apply()` puts it on `transcript.citations`; inline `[n]` markers
+in the prose become chips, and the chip opens `DocumentPane` at the cited
+section. Until that frame ships everywhere, the same chips are DERIVED from
+a trailing "## Sources" block in the answer: those render and read, and are
+inert, because a title and a section are not an id.
+
+### The system preamble
+
+A host prepends its own instruction to every question (cadmus sends
+`{room.preamble}\n\n{question}`). `readerQuestion()` strips leading
+paragraphs addressed to the model before the question renders, so a
+colleague never sees it. Pass the question as it went on the wire; the
+transcript shows what they asked.
 
 `createHistory(namespace)` from `@poodle64/librarian/history` gives each app,
-or each room inside an app, its own `localStorage` key, so two consumers
-never collide on one conversation list:
+or each room inside an app, its own `localStorage` key:
 
 ```ts
 import { createHistory, titleFrom } from '@poodle64/librarian/history';
@@ -126,9 +198,22 @@ history.load();
 ## Verifying a change
 
 ```bash
-pnpm run build   # svelte-package + publint
-pnpm run check   # svelte-check
-pnpm run test    # build + vitest
+pnpm run build        # svelte-package + publint
+pnpm run check        # svelte-check
+pnpm run test         # build + vitest
+pnpm run screenshots  # the state grid, real engine (see below)
+```
+
+`docs/screenshots/` is eight 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, and that the source pane
+opens and closes from the keyboard with focus returning to the chip. It
+exits non-zero on either.
+
+```bash
+pnpm --filter @poodle64/console run build
+pnpm --filter @poodle64/librarian run screenshots
 ```
 
 ## Releasing

package/dist/attachments.d.ts

@@ -0,0 +1,30 @@
+/**
+ * What a reader may hand Milton with a question.
+ *
+ * Session-scoped by design: these files are read for THIS conversation and
+ * never filed into a shelf, so the limits here are about what a browser can
+ * post and a model can read in one turn, not about a corpus.
+ */
+export declare const MAX_FILES = 10;
+export declare const MAX_BYTES: number;
+export declare const ACCEPTED_TYPES: readonly ["image/png", "image/jpeg", "image/webp", "application/pdf", "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "text/plain", "text/markdown"];
+export declare const ACCEPT_ATTRIBUTE: string;
+export interface RejectedFile {
+    name: string;
+    reason: 'type' | 'size' | 'count';
+}
+export interface FileCheck {
+    accepted: File[];
+    rejected: RejectedFile[];
+}
+/**
+ * Merge a drop or a picker's selection into the files already attached.
+ *
+ * Returns the WHOLE new list rather than only the additions, because the count
+ * limit is a property of the list and a caller that appended the return value
+ * would silently exceed it.
+ */
+export declare function acceptFiles(existing: File[], incoming: File[] | FileList): FileCheck;
+/** One line a reader can act on, or empty when everything was taken. */
+export declare function rejectionMessage(rejected: RejectedFile[]): string;
+export declare function formatSize(bytes: number): string;

package/dist/attachments.js

@@ -0,0 +1,80 @@
+/**
+ * What a reader may hand Milton with a question.
+ *
+ * Session-scoped by design: these files are read for THIS conversation and
+ * never filed into a shelf, so the limits here are about what a browser can
+ * post and a model can read in one turn, not about a corpus.
+ */
+export const MAX_FILES = 10;
+export const MAX_BYTES = 20 * 1024 * 1024;
+const DOCX = 'application/vnd.openxmlformats-officedocument.wordprocessingml.document';
+export const ACCEPTED_TYPES = [
+    'image/png',
+    'image/jpeg',
+    'image/webp',
+    'application/pdf',
+    DOCX,
+    'text/plain',
+    'text/markdown'
+];
+/** Browsers disagree about a `.md` file's type — Safari says `text/markdown`,
+ *  Chrome on some platforms says `''` — so the extension is checked too, and
+ *  the `accept` attribute lists both forms for the same reason. */
+const ACCEPTED_EXTENSIONS = ['.png', '.jpg', '.jpeg', '.webp', '.pdf', '.docx', '.txt', '.md'];
+export const ACCEPT_ATTRIBUTE = [...ACCEPTED_TYPES, ...ACCEPTED_EXTENSIONS].join(',');
+function typeAllowed(file) {
+    if (ACCEPTED_TYPES.includes(file.type))
+        return true;
+    const name = file.name.toLowerCase();
+    return ACCEPTED_EXTENSIONS.some((ext) => name.endsWith(ext));
+}
+/**
+ * Merge a drop or a picker's selection into the files already attached.
+ *
+ * Returns the WHOLE new list rather than only the additions, because the count
+ * limit is a property of the list and a caller that appended the return value
+ * would silently exceed it.
+ */
+export function acceptFiles(existing, incoming) {
+    const accepted = [...existing];
+    const rejected = [];
+    for (const file of Array.from(incoming)) {
+        if (!typeAllowed(file)) {
+            rejected.push({ name: file.name, reason: 'type' });
+            continue;
+        }
+        if (file.size > MAX_BYTES) {
+            rejected.push({ name: file.name, reason: 'size' });
+            continue;
+        }
+        if (accepted.length >= MAX_FILES) {
+            rejected.push({ name: file.name, reason: 'count' });
+            continue;
+        }
+        if (accepted.some((f) => f.name === file.name && f.size === file.size))
+            continue;
+        accepted.push(file);
+    }
+    return { accepted, rejected };
+}
+/** One line a reader can act on, or empty when everything was taken. */
+export function rejectionMessage(rejected) {
+    if (rejected.length === 0)
+        return '';
+    const reasons = {
+        type: "isn't a file type Milton can read",
+        size: 'is over 20 MB',
+        count: `won't fit — ${MAX_FILES} files is the limit`
+    };
+    const [first] = rejected;
+    const rest = rejected.length - 1;
+    return `${first.name} ${reasons[first.reason]}${rest ? `, and ${rest} more` : ''}.`;
+}
+export function formatSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    const kb = bytes / 1024;
+    if (kb < 1024)
+        return `${Math.round(kb)} KB`;
+    return `${(kb / 1024).toFixed(kb / 1024 < 10 ? 1 : 0)} MB`;
+}

package/dist/citations.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Where an answer came from.
+ *
+ * Two sources, one shape. The library emits a `citations` event after the
+ * final assistant text, and that is the real one — it carries a document id,
+ * so a chip can open the document. Until it ships everywhere, the same chips
+ * are DERIVED from the "## Sources" block Milton already writes, which names
+ * a title and a section but no id: those chips render and read, and cannot
+ * open a pane. A derived citation is marked `derived` so the UI can tell.
+ */
+export interface Citation {
+    n: number;
+    document_id: string;
+    title: string;
+    section?: string;
+    anchor?: string;
+    snippet?: string;
+    /** True when this came from the prose block rather than the wire event. */
+    derived?: boolean;
+}
+/** Inline `[n]` markers, in order of first appearance.
+ *
+ * Deliberately not a global "[digits]" match: `[1](…)` is a markdown link and
+ * `[1]: …` a link definition, and both appear in real answers.
+ *
+ * A following `[` is NOT excluded, and that is the point: `[1][2]` is how an
+ * answer cites two sources for one claim, and a lookahead that rejected it
+ * dropped the FIRST of the pair — `matchAll` resumes after the failed attempt
+ * rather than backtracking, so `[1]` was never seen at all and rendered as
+ * dead text beside a live `[2]`. */
+export declare function citationMarkers(markdown: string): number[];
+export interface SplitAnswer {
+    /** The prose, with any trailing Sources block removed. */
+    body: string;
+    /** Citations read out of that block; empty when there was none. */
+    citations: Citation[];
+}
+/**
+ * Split a trailing "## Sources" block off an answer.
+ *
+ * The block is rendered by the Sources list instead, so leaving it in the
+ * prose would print every source twice. A block that parses to nothing is left
+ * where it was rather than silently deleted.
+ */
+export declare function splitSources(markdown: string): SplitAnswer;
+/**
+ * The citations a turn should render.
+ *
+ * The wire event wins outright whenever it arrived — it is the same list with
+ * ids attached — so a turn never shows both.
+ */
+export declare function resolveCitations(fromEvent: Citation[], fromProse: Citation[]): Citation[];
+/** One addressable slice of a document — the granularity a citation names. */
+export interface DocumentSection {
+    anchor: string;
+    heading: string;
+    text: string;
+}
+export interface LoadedDocument {
+    title: string;
+    sections: DocumentSection[];
+}
+/**
+ * How the pane reads a document. The host supplies it, because the host is the
+ * one holding the caller's session: the library's document read is
+ * authenticated, and a package that fetched it directly would be reaching past
+ * the app's own proxy with credentials it has no business holding.
+ */
+export type LoadDocument = (documentId: string) => Promise<LoadedDocument>;

package/dist/citations.js

@@ -0,0 +1,102 @@
+/**
+ * Where an answer came from.
+ *
+ * Two sources, one shape. The library emits a `citations` event after the
+ * final assistant text, and that is the real one — it carries a document id,
+ * so a chip can open the document. Until it ships everywhere, the same chips
+ * are DERIVED from the "## Sources" block Milton already writes, which names
+ * a title and a section but no id: those chips render and read, and cannot
+ * open a pane. A derived citation is marked `derived` so the UI can tell.
+ */
+/** Inline `[n]` markers, in order of first appearance.
+ *
+ * Deliberately not a global "[digits]" match: `[1](…)` is a markdown link and
+ * `[1]: …` a link definition, and both appear in real answers.
+ *
+ * A following `[` is NOT excluded, and that is the point: `[1][2]` is how an
+ * answer cites two sources for one claim, and a lookahead that rejected it
+ * dropped the FIRST of the pair — `matchAll` resumes after the failed attempt
+ * rather than backtracking, so `[1]` was never seen at all and rendered as
+ * dead text beside a live `[2]`. */
+export function citationMarkers(markdown) {
+    const seen = [];
+    for (const match of markdown.matchAll(/\[(\d{1,3})\](?![(:])/g)) {
+        const n = Number(match[1]);
+        if (!seen.includes(n))
+            seen.push(n);
+    }
+    return seen;
+}
+const SOURCES_HEADING = /^[ \t]{0,3}#{1,6}[ \t]*sources[ \t]*:?[ \t]*$/im;
+/**
+ * Split a trailing "## Sources" block off an answer.
+ *
+ * The block is rendered by the Sources list instead, so leaving it in the
+ * prose would print every source twice. A block that parses to nothing is left
+ * where it was rather than silently deleted.
+ */
+export function splitSources(markdown) {
+    const heading = markdown.match(SOURCES_HEADING);
+    if (!heading || heading.index === undefined)
+        return { body: markdown, citations: [] };
+    // The block runs to the NEXT heading, not to the end of the answer. Cutting
+    // to the end loses anything Milton wrote after his sources — a closing note,
+    // a caveat — and loses it silently, which is the worst way to lose it.
+    const after = markdown.slice(heading.index + heading[0].length);
+    const next = after.search(/^[ \t]{0,3}#{1,6}[ \t]/m);
+    const block = next === -1 ? after : after.slice(0, next);
+    const tail = next === -1 ? '' : after.slice(next).trim();
+    const citations = parseSourceLines(block);
+    if (citations.length === 0)
+        return { body: markdown, citations: [] };
+    const before = markdown.slice(0, heading.index).trimEnd();
+    return { body: tail ? `${before}\n\n${tail}` : before, citations };
+}
+/** One list item per source; anything else in the block is ignored. */
+function parseSourceLines(block) {
+    const out = [];
+    for (const raw of block.split('\n')) {
+        const line = raw.trim();
+        if (!line)
+            continue;
+        // A second heading ends the block — the Sources list is the tail of the
+        // answer, not a section anything follows.
+        if (/^#{1,6}\s/.test(line))
+            break;
+        const item = line.match(/^(?:[-*+]|\[?(\d{1,3})\]?[.)])\s+(.*)$/);
+        if (!item)
+            continue;
+        const numbered = item[1] ? Number(item[1]) : undefined;
+        const parsed = parseSource(item[2]);
+        if (!parsed.title)
+            continue;
+        out.push({
+            n: numbered ?? out.length + 1,
+            document_id: '',
+            derived: true,
+            ...parsed
+        });
+    }
+    return out;
+}
+/** `**Title** — Section`, `Title – Section`, `Title: Section`, or just a title. */
+function parseSource(text) {
+    const plain = text
+        .replace(/\[(\d{1,3})\]\s*/, '')
+        .replace(/\*\*/g, '')
+        .replace(/[`*_]/g, '')
+        .trim();
+    const split = plain.match(/^(.+?)\s*(?:—|–|\s-\s|:)\s*(.+)$/);
+    if (!split)
+        return { title: plain };
+    return { title: split[1].trim(), section: split[2].trim() };
+}
+/**
+ * The citations a turn should render.
+ *
+ * The wire event wins outright whenever it arrived — it is the same list with
+ * ids attached — so a turn never shows both.
+ */
+export function resolveCitations(fromEvent, fromProse) {
+    return fromEvent.length > 0 ? fromEvent : fromProse;
+}

package/dist/client.d.ts

@@ -7,6 +7,7 @@
  * backend sent, so the Console renders the real thing and a new Claude Code
  * event type needs no change on either side.
  */
+import type { Citation } from './citations';
 /** One Claude Code stream event. Typed only where we branch on it. */
 export interface AgentEvent {
     type: string;
@@ -39,6 +40,8 @@ export interface AgentEvent {
     detail?: string;
     tools?: string[];
     model?: string;
+    /** `citations` frames only: the library's sources for the answer just sent. */
+    items?: Citation[];
     [key: string]: unknown;
 }
 export interface AskOptions {
@@ -47,6 +50,8 @@ export interface AskOptions {
     subtree?: string;
     /** Collections this question may see. Empty means all of them. */
     collections?: string[];
+    /** Files Milton reads for this question. Switches the request to multipart. */
+    files?: File[];
     signal?: AbortSignal;
     /** Where the ask lands. Each app mounts its own ask route. */
     endpoint?: string;

package/dist/client.js

@@ -7,21 +7,47 @@
  * backend sent, so the Console renders the real thing and a new Claude Code
  * event type needs no change on either side.
  */
+/**
+ * The request body for one ask.
+ *
+ * JSON when there are no files, multipart when there are — one endpoint, two
+ * encodings, because a `File` cannot cross a JSON body and base64 would double
+ * a 20 MB attachment on the wire for nothing. The multipart field names are
+ * the form convention (`collections[]`, `files[]`) rather than the JSON keys.
+ *
+ * `Content-Type` is deliberately absent for multipart: setting it by hand
+ * omits the boundary the browser generates, and the server then reads zero
+ * fields from a body that is on the wire perfectly.
+ */
+function requestInit(options, signal) {
+    if (!options.files?.length) {
+        return {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            credentials: 'include',
+            body: JSON.stringify({
+                question: options.question,
+                resume: options.resume ?? null,
+                subtree: options.subtree ?? '',
+                collections: options.collections ?? []
+            }),
+            signal
+        };
+    }
+    const form = new FormData();
+    form.append('question', options.question);
+    if (options.resume)
+        form.append('resume', options.resume);
+    for (const collection of options.collections ?? [])
+        form.append('collections[]', collection);
+    for (const file of options.files)
+        form.append('files[]', file, file.name);
+    return { method: 'POST', credentials: 'include', body: form, signal };
+}
 /** Async-iterate the events of one question. */
 export async function* ask(options) {
     const doFetch = options.fetch ?? fetch;
-    const response = await doFetch(options.endpoint ?? '/api/agent/ask', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        credentials: 'include',
-        body: JSON.stringify({
-            question: options.question,
-            resume: options.resume ?? null,
-            subtree: options.subtree ?? '',
-            collections: options.collections ?? []
-        }),
-        signal: options.signal
-    });
+    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." };
         return;