@poodle64/librarian 2026.9.11 → 2026.9.13

package/README.md

@@ -24,6 +24,8 @@ src/lib/
     scope-statement/       what this room answers from, and what it does not hold
     agent-transcript/      one question and everything Milton did answering it
     document-pane/         the cited document, open at the cited passage
+    artefact-card/         a study artefact's card in the transcript
+    artefact-pane/         a study artefact, open in the reading column
     composer/              the input box: attachments, scope chips, send/stop
     markdown/              sanitised, streaming-safe markdown + highlighting
     activity-group/        a whole investigation, as one quiet line
@@ -153,14 +155,14 @@ on it fires once and never again.
 
 | Concern                  | How                                                                                                                                                                                         |
 | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| The ask route            | `ask({ endpoint })`: a room's `/api/rooms/{id}/ask`, a caller's `/api/caller/ask`                                                                                                          |
+| 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                                                                        |
+| Asking again             | `onregenerate`: re-send the last question as a NEW turn; the package exposes the action and never re-asks by itself                                                                         |
 | Asking a follow-up       | `onsuggest(question)`: ask it as a NEW turn. Without the handler the chips do not render at all — a chip that does nothing is worse than no chip                                            |
 | The empty state          | `welcome` and up to three `examples`                                                                                                                                                        |
 | What this surface covers | `scope`: one statement per room, in the host's own words. Rendered above the first turn and folded to a line once the conversation starts                                                   |
-| The words themselves     | `copy`: a partial of `LibrarianCopy`. Every component resolves it itself, so overriding one line does not mean restating the rest                                                            |
+| The words themselves     | `copy`: a partial of `LibrarianCopy`. Every component resolves it itself, so overriding one line does not mean restating the rest                                                           |
 
 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

package/dist/client.d.ts

@@ -57,6 +57,11 @@ export interface AskOptions {
     collections?: string[];
     /** Files Milton reads for this question. Switches the request to multipart. */
     files?: File[];
+    /** What kind of turn this ask should become. Absent means an ordinary
+     *  question; a host that offers a study artefact sends its own kind
+     *  (`'briefing'`) and interprets what comes back accordingly — the wire
+     *  vocabulary is the host's own, never a fixed set here. */
+    kind?: string;
     signal?: AbortSignal;
     /** Where the ask lands. Each app mounts its own ask route. */
     endpoint?: string;

package/dist/client.js

@@ -29,7 +29,8 @@ function requestInit(options, signal) {
                 question: options.question,
                 resume: options.resume ?? null,
                 subtree: options.subtree ?? '',
-                collections: options.collections ?? []
+                collections: options.collections ?? [],
+                kind: options.kind
             }),
             signal
         };
@@ -42,6 +43,8 @@ function requestInit(options, signal) {
         form.append('collections[]', collection);
     for (const file of options.files)
         form.append('files[]', file, file.name);
+    if (options.kind)
+        form.append('kind', options.kind);
     return { method: 'POST', credentials: 'include', body: form, signal };
 }
 /** Async-iterate the events of one question. */

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

@@ -28,6 +28,7 @@
 	import { resolveCopy, type LibrarianCopy } from '../../copy';
 	import Working from '../working/working.svelte';
 	import ActivityGroup from '../activity-group/activity-group.svelte';
+	import ArtefactCard from '../artefact-card/artefact-card.svelte';
 	import Markdown from '../markdown/markdown.svelte';
 
 	interface Props {
@@ -51,6 +52,14 @@
 		 *  no chip. */
 		onsuggest?: (question: string) => void;
 		copy?: Partial<LibrarianCopy>;
+		/** A study artefact rather than an ordinary answer: once settled, this
+		 *  renders as a card instead of prose. */
+		kind?: 'answer' | 'artefact';
+		/** The artefact's own name, for the card. */
+		title?: string;
+		/** Opens the artefact in the reading column. Required wherever `kind`
+		 *  is `'artefact'`. */
+		onopenartefact?: () => void;
 	}
 
 	let {
@@ -64,9 +73,14 @@
 		oncite,
 		onregenerate,
 		onsuggest,
-		copy
+		copy,
+		kind = 'answer',
+		title,
+		onopenartefact
 	}: Props = $props();
 
+	const isArtefact = $derived(kind === 'artefact');
+
 	const words = $derived(resolveCopy(copy));
 
 	const asked = $derived(readerQuestion(question));
@@ -181,7 +195,7 @@
 	{#each segments as seg (seg.index)}
 		{#if seg.kind === 'activity'}
 			<ActivityGroup group={seg} live={running && seg.index === lastIndex} />
-		{:else}
+		{:else if !isArtefact}
 			<div class="max-w-[72ch] min-w-0">
 				<Markdown
 					content={seg.index === lastTextIndex && split.citations.length > 0
@@ -199,7 +213,11 @@
 		{/if}
 	{/each}
 
-	{#if sources.length > 0}
+	{#if isArtefact && settled}
+		<ArtefactCard title={title ?? 'Briefing'} citationCount={sources.length} onopen={() => onopenartefact?.()} />
+	{/if}
+
+	{#if !isArtefact && sources.length > 0}
 		<section class="max-w-[72ch]">
 			<h2 class="text-muted-foreground mb-1.5 text-xs font-medium tracking-wide uppercase">
 				{words.sources}
@@ -237,11 +255,11 @@
 		</section>
 	{/if}
 
-	{#if notHeld}
+	{#if !isArtefact && notHeld}
 		<p class="text-muted-foreground max-w-[72ch] text-sm">{words.notHeld}</p>
 	{/if}
 
-	{#if followUps.length > 0}
+	{#if !isArtefact && followUps.length > 0}
 		<section class="max-w-[72ch]">
 			<h2 class="text-muted-foreground mb-1.5 text-xs font-medium tracking-wide uppercase">
 				{words.suggestions}
@@ -276,7 +294,7 @@
 		</p>
 	{/if}
 
-	{#if settled}
+	{#if !isArtefact && settled}
 		<div class="text-muted-foreground -ml-1.5 flex items-center gap-1">
 			{#if hasAnswer}
 				<button

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

@@ -22,6 +22,14 @@ interface Props {
      *  no chip. */
     onsuggest?: (question: string) => void;
     copy?: Partial<LibrarianCopy>;
+    /** A study artefact rather than an ordinary answer: once settled, this
+     *  renders as a card instead of prose. */
+    kind?: 'answer' | 'artefact';
+    /** The artefact's own name, for the card. */
+    title?: string;
+    /** Opens the artefact in the reading column. Required wherever `kind`
+     *  is `'artefact'`. */
+    onopenartefact?: () => void;
 }
 declare const AgentTranscript: import("svelte").Component<Props, {}, "">;
 type AgentTranscript = ReturnType<typeof AgentTranscript>;

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

@@ -0,0 +1,40 @@
+<!--
+  A study artefact's card in the transcript: what a colleague taps to read it.
+  It is not the artefact itself — that lives in the reading column
+  (`ArtefactPane`), never stacked beside this card and never inline as prose,
+  which is the whole of the one-surface decision this package exists to keep
+  every consumer honest about.
+-->
+<script lang="ts">
+	import FileTextIcon from '@lucide/svelte/icons/file-text';
+	import Panel from '@poodle64/ui/panel';
+
+	interface Props {
+		title: string;
+		citationCount: number;
+		onopen: () => void;
+	}
+
+	let { title, citationCount, onopen }: Props = $props();
+</script>
+
+<Panel
+	icon={FileTextIcon}
+	{title}
+	subtitle="Briefing doc"
+	role="button"
+	tabindex={0}
+	onclick={onopen}
+	onkeydown={(event: KeyboardEvent) => {
+		if (event.key !== 'Enter' && event.key !== ' ') return;
+		event.preventDefault();
+		onopen();
+	}}
+	class="hover:border-border-strong focus-visible:ring-ring w-full max-w-[28rem] cursor-pointer text-left transition-colors focus-visible:ring-2 focus-visible:outline-none"
+>
+	{#snippet children()}
+		<p class="text-muted-foreground text-xs">
+			{citationCount} source{citationCount === 1 ? '' : 's'}
+		</p>
+	{/snippet}
+</Panel>

package/dist/components/artefact-card/artefact-card.svelte.d.ts

@@ -0,0 +1,8 @@
+interface Props {
+    title: string;
+    citationCount: number;
+    onopen: () => void;
+}
+declare const ArtefactCard: import("svelte").Component<Props, {}, "">;
+type ArtefactCard = ReturnType<typeof ArtefactCard>;
+export default ArtefactCard;

package/dist/components/artefact-card/index.d.ts

@@ -0,0 +1 @@
+export { default } from './artefact-card.svelte';

package/dist/components/artefact-card/index.js

@@ -0,0 +1 @@
+export { default } from './artefact-card.svelte';

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

@@ -0,0 +1,120 @@
+<!--
+  A study artefact, open in the reading column.
+
+  The same shell shape `DocumentPane` uses (a column at `lg`, a bottom sheet
+  below it) because decision 2 of the ask-milton surface is that a colleague
+  never has to learn which of the two things is in the column before they
+  open it — only ever one, in the same place, closing whichever was there.
+-->
+<script lang="ts">
+	import XIcon from '@lucide/svelte/icons/x';
+	import { segment, type TextBlock, type Turn } from '../../transcript.svelte';
+	import { resolveCitations, splitSources, trustMark, type Citation } from '../../citations';
+	import { resolveCopy, type LibrarianCopy } from '../../copy';
+	import Markdown from '../markdown/markdown.svelte';
+
+	interface Props {
+		turn: Turn;
+		onclose: () => void;
+		/** Opens the cited document instead — swapping the column back, never
+		 *  stacking it beside the artefact. Omit and the sources still list, but
+		 *  do not open. */
+		oncite?: (citation: Citation) => void;
+		copy?: Partial<LibrarianCopy>;
+	}
+
+	let { turn, onclose, oncite, copy }: Props = $props();
+
+	const words = $derived(resolveCopy(copy));
+
+	const texts = $derived(segment(turn.blocks).filter((s): s is TextBlock => s.kind === 'text'));
+	const rawAnswer = $derived(texts.map((t) => t.text).join('\n\n'));
+	const split = $derived(splitSources(rawAnswer));
+	const sources = $derived(resolveCitations(turn.citations ?? [], split.citations));
+
+	let closeButton = $state<HTMLButtonElement | null>(null);
+
+	// Opening a pane a reader reached with the keyboard must move focus into
+	// it, or Escape and Tab both act on the transcript behind it.
+	$effect(() => {
+		const returnTo = globalThis.document?.activeElement as HTMLElement | null;
+		closeButton?.focus();
+		return () => returnTo?.focus?.();
+	});
+
+	function keydown(event: KeyboardEvent) {
+		if (event.key === 'Escape') {
+			event.stopPropagation();
+			onclose();
+		}
+	}
+</script>
+
+<svelte:window onkeydown={keydown} />
+
+<aside
+	aria-label="Study artefact"
+	class="bg-surface-1 border-border fixed inset-x-0 bottom-0 z-40 flex h-[80svh] flex-col rounded-t-2xl border-t shadow-2xl lg:relative lg:h-auto lg:w-[560px] lg:shrink-0 lg:rounded-none lg:border-t-0 lg:border-l lg:shadow-none"
+>
+	<!-- The sheet's grabber. Below `lg` this is an overlay a reader has to be
+	     able to see the top edge of; on a desktop it is a column, so there is
+	     nothing here to grab. -->
+	<div class="flex justify-center pt-2 pb-1 lg:hidden" aria-hidden="true">
+		<span class="bg-border h-1 w-9 rounded-full"></span>
+	</div>
+
+	<header class="border-border flex items-start gap-2 border-b px-4 py-3 lg:pt-3">
+		<div class="min-w-0 flex-1">
+			<h2 class="text-foreground truncate text-sm font-semibold">{turn.title ?? 'Briefing'}</h2>
+			<p class="text-muted-foreground truncate text-xs">
+				Briefing doc · {sources.length} source{sources.length === 1 ? '' : 's'}
+			</p>
+		</div>
+		<button
+			bind:this={closeButton}
+			type="button"
+			onclick={onclose}
+			aria-label={words.closeSource}
+			class="text-muted-foreground hover:text-foreground hover:bg-surface-2 focus-visible:ring-ring -mt-1 flex size-8 shrink-0 items-center justify-center rounded-lg transition-colors focus-visible:ring-2 focus-visible:outline-none"
+		>
+			<XIcon class="size-4" />
+		</button>
+	</header>
+
+	<div class="min-h-0 flex-1 overflow-y-auto overscroll-contain px-4 py-3">
+		<Markdown content={split.citations.length > 0 ? split.body : rawAnswer} />
+
+		{#if sources.length > 0}
+			<section class="mt-6">
+				<h3 class="text-muted-foreground mb-1.5 text-xs font-medium tracking-wide uppercase">
+					{words.sources}
+				</h3>
+				<ol class="flex flex-col gap-1">
+					{#each sources as source (source.n)}
+						{@const mark = trustMark(source, words)}
+						<li>
+							<button
+								type="button"
+								onclick={() => oncite?.(source)}
+								disabled={!source.document_id || !oncite}
+								class="border-border hover:border-border-strong hover:bg-surface-2 focus-visible:ring-ring flex w-full items-baseline gap-2 rounded-lg border px-2.5 py-1.5 text-left text-sm transition-colors focus-visible:ring-2 focus-visible:outline-none disabled:cursor-default disabled:hover:bg-transparent"
+							>
+								<span
+									class="bg-primary/15 text-foreground shrink-0 rounded px-1.5 font-mono text-xs tabular-nums"
+									>{source.n}</span
+								>
+								<span class="min-w-0">
+									<span class="text-foreground">{source.title}</span>
+									{#if source.section}<span class="text-muted-foreground">
+											· {source.section}</span
+										>{/if}
+									{#if mark}<span class="text-muted-foreground/80"> · {mark}</span>{/if}
+								</span>
+							</button>
+						</li>
+					{/each}
+				</ol>
+			</section>
+		{/if}
+	</div>
+</aside>

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

@@ -0,0 +1,15 @@
+import { type Turn } from '../../transcript.svelte';
+import { type Citation } from '../../citations';
+import { type LibrarianCopy } from '../../copy';
+interface Props {
+    turn: Turn;
+    onclose: () => void;
+    /** Opens the cited document instead — swapping the column back, never
+     *  stacking it beside the artefact. Omit and the sources still list, but
+     *  do not open. */
+    oncite?: (citation: Citation) => void;
+    copy?: Partial<LibrarianCopy>;
+}
+declare const ArtefactPane: import("svelte").Component<Props, {}, "">;
+type ArtefactPane = ReturnType<typeof ArtefactPane>;
+export default ArtefactPane;

package/dist/components/artefact-pane/index.d.ts

@@ -0,0 +1 @@
+export { default } from './artefact-pane.svelte';

package/dist/components/artefact-pane/index.js

@@ -0,0 +1 @@
+export { default } from './artefact-pane.svelte';

package/dist/components/composer/composer.svelte

@@ -12,6 +12,7 @@
 -->
 <script lang="ts">
 	import ArrowUpIcon from '@lucide/svelte/icons/arrow-up';
+	import FileTextIcon from '@lucide/svelte/icons/file-text';
 	import PaperclipIcon from '@lucide/svelte/icons/paperclip';
 	import SquareIcon from '@lucide/svelte/icons/square';
 	import XIcon from '@lucide/svelte/icons/x';
@@ -39,6 +40,10 @@
 		onscope: (scope: Scope) => void;
 		onsubmit: () => void;
 		onstop: () => void;
+		/** Asks for a study artefact instead of an ordinary answer. Omit and no
+		 *  control renders — studying is a mode of asking, never a tab, so a
+		 *  host with nothing to build offers none rather than a disabled one. */
+		onbriefing?: () => void;
 	}
 
 	let {
@@ -51,7 +56,8 @@
 		attachments = true,
 		onscope,
 		onsubmit,
-		onstop
+		onstop,
+		onbriefing
 	}: Props = $props();
 
 	// What Milton is being asked about — this document, this collection, or
@@ -235,6 +241,19 @@
 				</button>
 			{/if}
 
+			{#if onbriefing}
+				<button
+					type="button"
+					onclick={onbriefing}
+					disabled={running}
+					aria-label="Ask for a briefing"
+					title="Ask for a briefing"
+					class="text-muted-foreground hover:text-foreground hover:bg-surface-2 focus-visible:ring-ring flex size-8 shrink-0 items-center justify-center rounded-full transition-colors focus-visible:ring-2 focus-visible:outline-none disabled:opacity-30"
+				>
+					<FileTextIcon class="size-4" />
+				</button>
+			{/if}
+
 			{#if hasChoice}
 				<div class="flex min-w-0 flex-wrap items-center gap-1">
 					{#each choices as choice (choice.id)}

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

@@ -13,6 +13,10 @@ interface Props {
     onscope: (scope: Scope) => void;
     onsubmit: () => void;
     onstop: () => void;
+    /** Asks for a study artefact instead of an ordinary answer. Omit and no
+     *  control renders — studying is a mode of asking, never a tab, so a
+     *  host with nothing to build offers none rather than a disabled one. */
+    onbriefing?: () => void;
 }
 declare const Composer: import("svelte").Component<Props, {}, "value" | "files">;
 type Composer = ReturnType<typeof Composer>;

package/dist/components/conversation/conversation.svelte

@@ -16,9 +16,15 @@
 	import { resolveCopy, type LibrarianCopy } from '../../copy';
 	import { FollowScroll } from '../../follow-scroll.svelte';
 	import AgentTranscript from '../agent-transcript/agent-transcript.svelte';
+	import ArtefactPane from '../artefact-pane/artefact-pane.svelte';
 	import DocumentPane from '../document-pane/document-pane.svelte';
 	import ScopeStatement from '../scope-statement/scope-statement.svelte';
 
+	/** What the reading column holds — a cited document or a study artefact,
+	 *  never both and never two panes: whichever the reader last opened
+	 *  replaces whatever was there. */
+	type Column = { kind: 'document'; citation: Citation } | { kind: 'artefact'; turn: Turn } | null;
+
 	interface Props {
 		turns: Turn[];
 		running: boolean;
@@ -68,7 +74,7 @@
 	const words = $derived(resolveCopy(copy));
 
 	let viewport = $state<HTMLElement | null>(null);
-	let open = $state<Citation | null>(null);
+	let column = $state<Column>(null);
 	const follow = new FollowScroll();
 
 	function metrics(el: HTMLElement) {
@@ -101,6 +107,25 @@
 		viewport.scrollTop = viewport.scrollHeight;
 	});
 
+	// Asking for a briefing puts its card in the transcript AND opens the
+	// artefact in the column, closing whatever document was there — a
+	// 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.
+	//
+	// Plain, not `$state`: read and written in the same effect, which would
+	// otherwise re-trigger itself forever (the pattern this file's `seen`
+	// already uses for the same reason).
+	let wasRunning = false;
+	$effect(() => {
+		const last = turns.at(-1);
+		if (wasRunning && !running && last?.kind === 'artefact' && !last.outcome?.isError) {
+			column = { kind: 'artefact', turn: last };
+		}
+		wasRunning = running;
+	});
+
 	function scrolled() {
 		if (viewport) follow.measure(metrics(viewport));
 	}
@@ -113,8 +138,13 @@
 
 	function cite(citation: 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.
-		if (loadDocument && citation.document_id) open = citation;
+		// 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 };
 	}
 </script>
 
@@ -173,6 +203,9 @@
 						suggestions={turn.suggestions ?? []}
 						{collectionNames}
 						{copy}
+						kind={turn.kind}
+						title={turn.title}
+						onopenartefact={() => openArtefact(turn)}
 						oncite={cite}
 						onregenerate={index === turns.length - 1 && !running ? onregenerate : undefined}
 						onsuggest={index === turns.length - 1 && !running ? onsuggest : undefined}
@@ -201,7 +234,14 @@
 
 	</div>
 
-	{#if open && loadDocument}
-		<DocumentPane citation={open} {loadDocument} {copy} onclose={() => (open = null)} />
+	{#if column?.kind === 'document' && loadDocument}
+		<DocumentPane citation={column.citation} {loadDocument} {copy} onclose={() => (column = null)} />
+	{:else if column?.kind === 'artefact'}
+		<ArtefactPane
+			turn={column.turn}
+			{copy}
+			onclose={() => (column = null)}
+			oncite={(citation) => cite(citation)}
+		/>
 	{/if}
 </div>

package/dist/transcript.svelte.d.ts

@@ -123,6 +123,12 @@ export interface Turn {
     /** Follow-ups offered after this answer. Absent on a turn read back from
      *  history: they belonged to the moment it was asked. */
     suggestions?: string[];
+    /** A study artefact rather than an ordinary answer: renders as a card once
+     *  settled, never as prose, and opens the reading column instead of a
+     *  citation. Absent (or `'answer'`) is every ordinary turn. */
+    kind?: 'answer' | 'artefact';
+    /** The artefact's own name. Only meaningful when `kind` is `'artefact'`. */
+    title?: string;
 }
 /**
  * Fold a turn's flat block list into what a reader should actually see.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@poodle64/librarian",
-	"version": "2026.9.11",
+	"version": "2026.9.13",
 	"description": "Milton's conversation surface as a consumable Svelte 5 package: the stream client, transcript state and chat components (transcript, composer, markdown) every household app renders instead of rebuilding.",
 	"type": "module",
 	"license": "MIT",