@poodle64/librarian 2026.9.1

package/README.md

@@ -0,0 +1,115 @@
+# @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.
+
+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
+  transcript.svelte.ts     Transcript state, the fold/segment/describe helpers
+  history.svelte.ts        the browser-held conversation list, namespaced 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
+```
+
+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
+pnpm add @poodle64/librarian @poodle64/ui @lucide/svelte
+```
+
+`svelte`, `@poodle64/ui`, `@lucide/svelte`, `marked`, `isomorphic-dompurify`
+and `shiki` are peer dependencies: declare them yourself so Renovate tracks
+their versions and `pnpm ls` shows them.
+
+## Consuming the package
+
+Every export is its own subpath, matching `@poodle64/ui`'s convention:
+
+```svelte
+<script lang="ts">
+	import { ask } from '@poodle64/librarian/client';
+	import { Transcript } from '@poodle64/librarian/transcript';
+	import AgentTranscript from '@poodle64/librarian/agent-transcript';
+	import Composer from '@poodle64/librarian/composer';
+
+	let question = $state('');
+	let running = $state(false);
+	const transcript = new Transcript();
+
+	async function submit() {
+		const asked = question.trim();
+		if (!asked || running) return;
+
+		question = '';
+		running = true;
+		transcript.reset();
+
+		try {
+			for await (const event of ask({ question: asked, endpoint: '/api/caller/ask' })) {
+				transcript.apply(event);
+				if (event.type === 'result' || event.type === 'library_error') running = false;
+			}
+		} finally {
+			running = false;
+		}
+	}
+</script>
+
+<AgentTranscript {question} blocks={transcript.blocks} outcome={transcript.outcome} {running} />
+
+<Composer
+	bind:value={question}
+	{running}
+	scope="library"
+	onscope={() => {}}
+	onsubmit={submit}
+	onstop={() => {}}
+/>
+```
+
+`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.
+
+`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:
+
+```ts
+import { createHistory, titleFrom } from '@poodle64/librarian/history';
+
+const history = createHistory('cadmus.rooms.defence-personnel');
+history.load();
+```
+
+## Verifying a change
+
+```bash
+pnpm run build   # svelte-package + publint
+pnpm run check   # svelte-check
+pnpm run test    # build + vitest
+```
+
+## Releasing
+
+1. Change a component; bump `version` in `package.json` (CalVer).
+2. `pnpm build`, which runs `svelte-package` then `publint`.
+3. Commit, tag `librarian-v<version>`, push the tag; CI publishes to public npm.

package/dist/client.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The agent stream.
+ *
+ * Deliberately thin: it frames SSE and hands back Claude Code's OWN events,
+ * unaltered. There is no mapping onto a house vocabulary here or anywhere
+ * else — the backend forwards what the CLI emits and this forwards what the
+ * backend sent, so the Console renders the real thing and a new Claude Code
+ * event type needs no change on either side.
+ */
+/** One Claude Code stream event. Typed only where we branch on it. */
+export interface AgentEvent {
+    type: string;
+    subtype?: string;
+    event?: {
+        type: string;
+        index?: number;
+        delta?: {
+            type: string;
+            text?: string;
+            thinking?: string;
+            partial_json?: string;
+        };
+        content_block?: {
+            type: string;
+            name?: string;
+            id?: string;
+        };
+    };
+    message?: {
+        content?: Array<Record<string, unknown>>;
+    };
+    session_id?: string;
+    result?: string;
+    num_turns?: number;
+    total_cost_usd?: number;
+    duration_ms?: number;
+    is_error?: boolean;
+    error?: string;
+    detail?: string;
+    tools?: string[];
+    model?: string;
+    [key: string]: unknown;
+}
+export interface AskOptions {
+    question: string;
+    resume?: string | null;
+    subtree?: string;
+    /** Collections this question may see. Empty means all of them. */
+    collections?: string[];
+    signal?: AbortSignal;
+    /** Where the ask lands. Each app mounts its own ask route. */
+    endpoint?: string;
+    /** Override for the ambient `fetch`, e.g. a caller-authenticated wrapper. */
+    fetch?: typeof fetch;
+}
+/** Async-iterate the events of one question. */
+export declare function ask(options: AskOptions): AsyncGenerator<AgentEvent>;

package/dist/client.js

@@ -0,0 +1,60 @@
+/**
+ * The agent stream.
+ *
+ * Deliberately thin: it frames SSE and hands back Claude Code's OWN events,
+ * unaltered. There is no mapping onto a house vocabulary here or anywhere
+ * else — the backend forwards what the CLI emits and this forwards what the
+ * backend sent, so the Console renders the real thing and a new Claude Code
+ * event type needs no change on either side.
+ */
+/** 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
+    });
+    if (!response.ok || !response.body) {
+        yield { type: 'library_error', error: `The agent answered ${response.status}.` };
+        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 = '';
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        buffered += 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)
+                continue;
+            try {
+                yield JSON.parse(data);
+            }
+            catch {
+                /* a partial frame at end of stream is not an error */
+            }
+        }
+    }
+}

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

@@ -0,0 +1,63 @@
+<!--
+  A whole investigation, as one line the reader can open.
+
+  Fifteen tool rows stood between the question and the first word of the
+  answer, so the answer had to be scrolled to. While the agent is working the
+  steps are worth watching, so they show live. The moment prose starts
+  arriving they fold to a single summary — the same move Claude makes with
+  "Researched for 49s".
+-->
+<script lang="ts">
+	import ChevronRightIcon from '@lucide/svelte/icons/chevron-right';
+	import { summariseActivity, type ActivityGroup } from '../../transcript.svelte';
+	import ToolRow from '../tool-row/tool-row.svelte';
+	import ThinkingRow from '../thinking-row/thinking-row.svelte';
+
+	interface Props {
+		group: ActivityGroup;
+		/** True while this group is the live one — it stays open. */
+		live: boolean;
+	}
+
+	let { group, live }: Props = $props();
+	let expanded = $state(false);
+	const open = $derived(live || expanded);
+</script>
+
+{#if live}
+	<div class="flex flex-col gap-1.5">
+		{#each group.steps as step (step.block.index)}
+			{#if step.block.kind === 'tool'}
+				<ToolRow block={step.block} repeats={step.repeats} running={true} />
+			{:else}
+				<ThinkingRow
+					block={step.block}
+					active={step.block.index === group.steps.at(-1)?.block.index}
+				/>
+			{/if}
+		{/each}
+	</div>
+{:else}
+	<div>
+		<button
+			type="button"
+			class="text-muted-foreground hover:text-foreground flex items-center gap-1.5 text-sm transition-colors"
+			onclick={() => (expanded = !expanded)}
+			aria-expanded={expanded}
+		>
+			<ChevronRightIcon class="size-3.5 transition-transform {expanded ? 'rotate-90' : ''}" />
+			<span>{summariseActivity(group)}</span>
+		</button>
+		{#if open}
+			<div class="border-border mt-2 ml-1.75 flex flex-col gap-1.5 border-l pl-3">
+				{#each group.steps as step (step.block.index)}
+					{#if step.block.kind === 'tool'}
+						<ToolRow block={step.block} repeats={step.repeats} running={false} />
+					{:else}
+						<ThinkingRow block={step.block} active={false} />
+					{/if}
+				{/each}
+			</div>
+		{/if}
+	</div>
+{/if}

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

@@ -0,0 +1,9 @@
+import { type ActivityGroup } from '../../transcript.svelte';
+interface Props {
+    group: ActivityGroup;
+    /** True while this group is the live one — it stays open. */
+    live: boolean;
+}
+declare const ActivityGroup: import("svelte").Component<Props, {}, "">;
+type ActivityGroup = ReturnType<typeof ActivityGroup>;
+export default ActivityGroup;

package/dist/components/activity-group/index.d.ts

@@ -0,0 +1,2 @@
+export { default as ActivityGroup } from './activity-group.svelte';
+export { default } from './activity-group.svelte';

package/dist/components/activity-group/index.js

@@ -0,0 +1,2 @@
+export { default as ActivityGroup } from './activity-group.svelte';
+export { default } from './activity-group.svelte';

package/dist/components/agent-transcript/agent-transcript.svelte

@@ -0,0 +1,71 @@
+<!--
+  One question and everything the agent did answering it.
+
+  User turn as a rounded bubble, assistant prose led by a status dot, tool
+  calls as rows in the flow, thinking as stacked phase labels that dim once
+  superseded.
+-->
+<script lang="ts">
+	import { segment, type Block, type Outcome } from '../../transcript.svelte';
+	import Working from '../working/working.svelte';
+	import ActivityGroup from '../activity-group/activity-group.svelte';
+	import Markdown from '../markdown/markdown.svelte';
+
+	interface Props {
+		question: string;
+		blocks: Block[];
+		outcome: Outcome | null;
+		running: boolean;
+		/** Forwarded to Markdown; omit if the caller has no collections to chip. */
+		collectionNames?: Set<string>;
+	}
+
+	let { question, blocks, outcome, running, collectionNames = new Set() }: Props = $props();
+
+	// An activity group stays live — and therefore open — only while it is the
+	// last thing in the turn. As soon as prose arrives after it, it folds.
+	const segments = $derived(segment(blocks));
+	const lastIndex = $derived(segments.at(-1)?.index ?? -1);
+</script>
+
+<article class="flex flex-col gap-3">
+	<!-- Right-aligned, following Claude and ChatGPT rather than a VS Code-style
+	     panel: this surface is read by people who arrive with those two as
+	     their model of what a chat looks like. -->
+	<div
+		class="bg-surface-3 text-foreground border-border max-w-[85%] self-end rounded-2xl border px-4 py-2.5 text-base"
+	>
+		{question}
+	</div>
+
+	{#if running && segments.length === 0}
+		<Working />
+	{/if}
+
+	{#each segments as seg (seg.index)}
+		{#if seg.kind === 'activity'}
+			<ActivityGroup group={seg} live={running && seg.index === lastIndex} />
+		{:else}
+			<div class="flex gap-2.5">
+				<span class="bg-muted-foreground/40 mt-2.5 size-1.5 shrink-0 rounded-full"></span>
+				<div class="min-w-0 flex-1">
+					<Markdown
+						content={seg.text}
+						streaming={running && seg.index === lastIndex}
+						{collectionNames}
+					/>
+				</div>
+			</div>
+		{/if}
+	{/each}
+
+	{#if outcome}
+		<p class="text-muted-foreground pl-4 font-mono text-xs tabular-nums">
+			{#if outcome.error}
+				{outcome.error}
+			{:else}
+				{outcome.turns} turns · {((outcome.durationMs ?? 0) / 1000).toFixed(1)}s
+			{/if}
+		</p>
+	{/if}
+</article>

package/dist/components/agent-transcript/agent-transcript.svelte.d.ts

@@ -0,0 +1,12 @@
+import { type Block, type Outcome } from '../../transcript.svelte';
+interface Props {
+    question: string;
+    blocks: Block[];
+    outcome: Outcome | null;
+    running: boolean;
+    /** Forwarded to Markdown; omit if the caller has no collections to chip. */
+    collectionNames?: Set<string>;
+}
+declare const AgentTranscript: import("svelte").Component<Props, {}, "">;
+type AgentTranscript = ReturnType<typeof AgentTranscript>;
+export default AgentTranscript;

package/dist/components/agent-transcript/index.d.ts

@@ -0,0 +1,2 @@
+export { default as AgentTranscript } from './agent-transcript.svelte';
+export { default } from './agent-transcript.svelte';

package/dist/components/agent-transcript/index.js

@@ -0,0 +1,2 @@
+export { default as AgentTranscript } from './agent-transcript.svelte';
+export { default } from './agent-transcript.svelte';

package/dist/components/composer/composer.svelte

@@ -0,0 +1,115 @@
+<!--
+  The composer: one rounded box holding the input AND a footer row.
+
+  Two things carry it: the chips sit BELOW the input inside the same box
+  rather than beside it, and the trailing control is a circular filled accent
+  button. The empty→typing transition lives almost entirely in that control —
+  the box chrome does not resize.
+
+  The composer stays enabled while the agent works. Queuing the next message
+  is not built yet; disabling the box would be a different and worse
+  behaviour than the one being copied, so it is not disabled.
+-->
+<script lang="ts">
+	import ArrowUpIcon from '@lucide/svelte/icons/arrow-up';
+	import SquareIcon from '@lucide/svelte/icons/square';
+
+	export type Scope = 'document' | 'collection' | 'library';
+
+	interface Props {
+		value: string;
+		running: boolean;
+		scope: Scope;
+		/** Names for the two narrower scopes; absent means that scope is unavailable. */
+		documentName?: string;
+		collectionName?: string;
+		onscope: (scope: Scope) => void;
+		onsubmit: () => void;
+		onstop: () => void;
+	}
+
+	let {
+		value = $bindable(),
+		running,
+		scope,
+		documentName,
+		collectionName,
+		onscope,
+		onsubmit,
+		onstop
+	}: Props = $props();
+
+	// What the agent is being asked about — chat with this document, this
+	// collection, or the whole library. Callers that have no narrower scope
+	// pass neither name and only "All collections" ever renders.
+	const choices = $derived(
+		[
+			documentName ? { id: 'document' as const, label: documentName } : null,
+			collectionName ? { id: 'collection' as const, label: collectionName } : null,
+			{ id: 'library' as const, label: 'All collections' }
+		].filter((c) => c !== null)
+	);
+
+	// Three chips in a narrow column clipped all three to fragments
+	// ("defence-s…", "All colle…"). Wrapping beats truncating: a chip a reader
+	// cannot finish reading is not a control, it is decoration.
+
+	function keydown(event: KeyboardEvent) {
+		// Enter sends, Shift+Enter breaks the line — the convention in every
+		// reference and the one a user will try first.
+		if (event.key === 'Enter' && !event.shiftKey) {
+			event.preventDefault();
+			if (value.trim()) onsubmit();
+		}
+	}
+</script>
+
+<div
+	class="border-border bg-surface-1 focus-within:border-primary/60 rounded-xl border transition-colors"
+>
+	<textarea
+		bind:value
+		onkeydown={keydown}
+		rows="2"
+		placeholder={running ? 'Queue another message…' : 'Ask anything'}
+		class="text-foreground placeholder:text-muted-foreground max-h-52 w-full resize-none bg-transparent px-4 pt-3 pb-2 text-base outline-none"
+	></textarea>
+
+	<div class="flex items-center gap-2 px-3 pb-2.5">
+		<div class="flex min-w-0 flex-wrap items-center gap-1">
+			{#each choices as choice (choice.id)}
+				<button
+					type="button"
+					onclick={() => onscope(choice.id)}
+					class="max-w-full truncate rounded-full px-2 py-0.5 text-xs transition-colors {scope ===
+					choice.id
+						? 'bg-primary/15 text-foreground border-primary/40 border'
+						: 'text-muted-foreground hover:text-foreground border border-transparent'}"
+				>
+					{choice.label}
+				</button>
+			{/each}
+		</div>
+		<span class="flex-1"></span>
+		{#if running}
+			<button
+				type="button"
+				onclick={onstop}
+				aria-label="Stop"
+				class="bg-foreground text-background hover:bg-foreground/90 flex size-8 items-center justify-center rounded-full transition-colors"
+			>
+				<SquareIcon class="size-3.5 fill-current" />
+			</button>
+		{:else}
+			<button
+				type="button"
+				onclick={onsubmit}
+				disabled={!value.trim()}
+				aria-label="Send"
+				class="bg-primary text-primary-foreground hover:bg-primary/90 disabled:hover:bg-primary flex size-8 items-center justify-center rounded-full transition-all disabled:opacity-30"
+			>
+				<ArrowUpIcon class="size-4" />
+			</button>
+		{/if}
+	</div>
+</div>

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

@@ -0,0 +1,15 @@
+export type Scope = 'document' | 'collection' | 'library';
+interface Props {
+    value: string;
+    running: boolean;
+    scope: Scope;
+    /** Names for the two narrower scopes; absent means that scope is unavailable. */
+    documentName?: string;
+    collectionName?: string;
+    onscope: (scope: Scope) => void;
+    onsubmit: () => void;
+    onstop: () => void;
+}
+declare const Composer: import("svelte").Component<Props, {}, "value">;
+type Composer = ReturnType<typeof Composer>;
+export default Composer;

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

@@ -0,0 +1,3 @@
+export { default as Composer } from './composer.svelte';
+export { default } from './composer.svelte';
+export type { Scope } from './composer.svelte';

package/dist/components/composer/index.js

@@ -0,0 +1,2 @@
+export { default as Composer } from './composer.svelte';
+export { default } from './composer.svelte';

package/dist/components/markdown/index.d.ts

@@ -0,0 +1,3 @@
+export { default as Markdown } from './markdown.svelte';
+export { default } from './markdown.svelte';
+export { balance, render, markCollections, highlight } from './markdown';

package/dist/components/markdown/index.js

@@ -0,0 +1,3 @@
+export { default as Markdown } from './markdown.svelte';
+export { default } from './markdown.svelte';
+export { balance, render, markCollections, highlight } from './markdown';

package/dist/components/markdown/markdown.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Markdown for a STREAMING agent transcript.
+ *
+ * Two things separate this from calling `marked()` on a string, and both are
+ * what make a streaming transcript look finished rather than glitchy:
+ *
+ * 1. Half-arrived markdown is not valid markdown. A code fence that has opened
+ *    and not yet closed makes `marked` treat the rest of the answer as code, so
+ *    the message visibly flips between prose and a grey slab on every token.
+ *    Unterminated constructs are closed before parsing.
+ * 2. Highlighting every code block on every token is wasted work the user never
+ *    sees — the block changes again a few milliseconds later. Highlighting is a
+ *    separate pass the caller runs once the text has settled.
+ *
+ * Sanitised on the way out, always. The content is model output rendered as
+ * HTML, which is exactly the case DOMPurify exists for.
+ */
+/** Close anything the stream has opened but not yet finished. */
+export declare function balance(markdown: string): string;
+export declare function render(markdown: string, { streaming }?: {
+    streaming?: boolean | undefined;
+}): string;
+/**
+ * Mark every inline `code` span that names a known collection.
+ *
+ * The agent puts identifiers in backticks — document titles, requirement
+ * numbers, collection names — and they all render alike. Matching against
+ * the caller's real list rather than a prompt convention means the prompt
+ * cannot drift out of sync with the rendering.
+ */
+export declare function markCollections(root: HTMLElement, collections: Set<string>): void;
+/**
+ * Replace every `<pre><code>` in a rendered fragment with a highlighted one.
+ * Runs against the DOM node rather than the HTML string so it can be applied
+ * after paint without re-parsing the markdown.
+ */
+export declare function highlight(root: HTMLElement): Promise<void>;