@poodle64/librarian 2026.10.3 → 2026.10.5

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

@@ -1,5 +1,10 @@
 <!--
-  An artefact that is its answer's own prose, open in the reading column.
+  An artefact that is its answer's own prose, or one version of a document the
+  persona wrote, open in the reading column.
+
+  A written document is shown from its source: Markdown through the package's
+  sanitising renderer, HTML only inside a sandboxed frame with no permissions
+  (no scripts, no same origin), never injected into the page.
 
   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
@@ -7,15 +12,40 @@
   only ever one, in the same place, closing whichever was there.
 -->
 <script lang="ts">
+	import ChevronDownIcon from '@lucide/svelte/icons/chevron-down';
+	import CopyIcon from '@lucide/svelte/icons/copy';
+	import CheckIcon from '@lucide/svelte/icons/check';
+	import DownloadIcon from '@lucide/svelte/icons/download';
 	import XIcon from '@lucide/svelte/icons/x';
+	import { untrack } from 'svelte';
 	import { segment, type TextBlock, type Turn } from '../../transcript.svelte';
 	import { resolveCitations, splitSources, type Citation } from '../../citations';
-	import { resolveCopy, type ChatCopy } from '../../copy';
+	import { fill, resolveCopy, type ChatCopy } from '../../copy';
+	import {
+		downloads,
+		framed,
+		isHtml,
+		kindLabel,
+		stripFrontMatter,
+		writtenKey,
+		type LoadWritten,
+		type Written,
+		type WrittenUrl
+	} from '../../written';
 	import Markdown from '../markdown/markdown.svelte';
 	import SourceList from '../source-list/source-list.svelte';
 
+
 	interface Props {
-		turn: Turn;
+		/** The turn whose answer is the artefact. Absent when `versions` is given. */
+		turn?: Turn;
+		/** Every version of one written document, oldest first: the pane shows
+		 *  `version` of them, with a switcher. */
+		versions?: Written[];
+		version?: number;
+		onversion?: (version: number) => void;
+		loadWritten?: LoadWritten;
+		writtenUrl?: WrittenUrl;
 		onclose: () => void;
 		/** Opens the cited document instead — swapping the column back, never
 		 *  stacking it beside the artefact. Omit and the sources still list, but
@@ -24,14 +54,99 @@
 		copy?: Partial<ChatCopy>;
 	}
 
-	let { turn, onclose, oncite, copy }: Props = $props();
+	let {
+		turn,
+		versions = [],
+		version,
+		onversion,
+		loadWritten,
+		writtenUrl,
+		onclose,
+		oncite,
+		copy
+	}: Props = $props();
 
 	const words = $derived(resolveCopy(copy));
 
-	const texts = $derived(segment(turn.blocks).filter((s): s is TextBlock => s.kind === 'text'));
+	// The newest, until the reader picks another.
+	const current = $derived(versions.find((v) => v.version === version) ?? versions.at(-1));
+	const currentKey = $derived(current ? writtenKey(current) : '');
+	// The one before it, whose blocks this one is marked against.
+	const before = $derived(current ? versions.filter((v) => v.version < current.version).at(-1) : undefined);
+	const beforeKey = $derived(before ? writtenKey(before) : '');
+	let source = $state<{ text: string; mediaType: string } | null>(null);
+	let earlier = $state<string | null>(null);
+	let failed = $state(false);
+
+	// Keyed on the version alone: a new version of the same name arriving in
+	// the stream must not read this one again.
+	$effect(() => {
+		if (!currentKey) return;
+		const shown = untrack(() => current);
+		const load = untrack(() => loadWritten);
+		if (!shown || !load) return;
+		let live = true;
+		source = null;
+		failed = false;
+		load(shown.name, shown.version).then(
+			(read) => live && (source = read),
+			() => live && (failed = true)
+		);
+		return () => (live = false);
+	});
+
+	$effect(() => {
+		earlier = null;
+		if (!beforeKey) return;
+		const prior = untrack(() => before);
+		const load = untrack(() => loadWritten);
+		if (!prior || !load || isHtml(prior.media_type)) return;
+		let live = true;
+		// A version that cannot be read is no reason to mark nothing else.
+		load(prior.name, prior.version).then(
+			(read) => live && (earlier = stripFrontMatter(read.text)),
+			() => {}
+		);
+		return () => (live = false);
+	});
+
+	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));
+	const sources = $derived(resolveCitations(turn?.citations ?? [], split.citations));
+
+	const links = $derived(current && writtenUrl ? downloads(current, words) : []);
+	// The one download the bar offers directly: Word where there is one, else the source.
+	const primary = $derived(links.find((link) => link.format === 'docx') ?? links[0]);
+	const sub = $derived.by(() => {
+		if (!current) return '';
+		const fresh = current.at !== undefined && Date.now() - current.at < 120_000;
+		const when = fresh
+			? fill(current.version > 1 ? words.paneEdited : words.paneWritten, { when: words.justNow })
+			: '';
+		return [kindLabel(current, words), when].filter(Boolean).join(' · ');
+	});
+	const changed = $derived(
+		current?.changes && before
+			? fill(words.changedSince, { n: before.version, changes: current.changes })
+			: ''
+	);
+
+	let menu = $state(false);
+	let copied = $state(false);
+
+	async function copyDocument() {
+		if (!source) return;
+		try {
+			await navigator.clipboard.writeText(stripFrontMatter(source.text));
+			copied = true;
+			setTimeout(() => (copied = false), 1600);
+		} catch {
+			// A denied clipboard is not worth an error state on text the reader can select.
+		}
+	}
 
 	let closeButton = $state<HTMLButtonElement | null>(null);
 
@@ -44,28 +159,22 @@
 	});
 
 	function keydown(event: KeyboardEvent) {
-		if (event.key === 'Escape') {
-			event.stopPropagation();
-			onclose();
-		}
+		if (event.key !== 'Escape') return;
+		event.stopPropagation();
+		if (menu) menu = false;
+		else onclose();
 	}
 </script>
 
 <svelte:window onkeydown={keydown} />
 
-<aside aria-label="Study artefact" class="ds-lib-pane">
+<aside aria-label={current?.title ?? 'Study artefact'} class="ds-lib-pane">
 	<!-- The sheet's grabber. On a phone 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="ds-lib-pane-grabber" aria-hidden="true"><span></span></div>
 
 	<header class="ds-lib-pane-header">
-		<div class="ds-lib-pane-heading">
-			<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}
 			type="button"
@@ -75,33 +184,112 @@
 		>
 			<XIcon size={16} />
 		</button>
+		<div class="ds-lib-pane-heading">
+			{#if current}
+				<h2 class="ds-lib-pane-title">{current.title}</h2>
+				{#if sub}<p class="ds-lib-pane-subtitle">{sub}</p>{/if}
+			{:else}
+				<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}
+			{/if}
+		</div>
+		{#if current}
+			<select
+				class="ds-lib-pane-versions"
+				aria-label={words.writtenVersions}
+				value={current.version}
+				onchange={(event) => onversion?.(Number(event.currentTarget.value))}
+			>
+				{#each versions as option (option.version)}
+					<option value={option.version}>{fill(words.writtenVersion, { n: option.version })}</option>
+				{/each}
+			</select>
+			{#if source && !failed}
+				<button
+					type="button"
+					class="ds-lib-pane-tool ds-lib-pane-copy"
+					onclick={copyDocument}
+					aria-label={copied ? words.copiedDocument : words.copyDocument}
+				>
+					{#if copied}<CheckIcon size={15} />{:else}<CopyIcon size={15} />{/if}
+				</button>
+			{/if}
+			{#if writtenUrl && links.length > 0}
+				<div class="ds-lib-pane-menu">
+					<button
+						type="button"
+						class="ds-lib-pane-tool"
+						aria-haspopup="menu"
+						aria-expanded={menu}
+						onclick={() => (menu = !menu)}
+					>
+						<DownloadIcon size={15} />{words.download}<ChevronDownIcon size={14} />
+					</button>
+					{#if menu}
+						<ul class="ds-lib-pane-links" role="menu" aria-label={words.download}>
+							{#each links as link (link.format)}
+								<li role="none">
+									<a
+										role="menuitem"
+										href={writtenUrl(current.name, current.version, link.format)}
+										onclick={() => (menu = false)}>{link.label}</a
+									>
+								</li>
+							{/each}
+						</ul>
+					{/if}
+				</div>
+				{#if primary}
+					<a
+						class="ds-lib-pane-tool ds-lib-pane-quick"
+						href={writtenUrl(current.name, current.version, primary.format)}
+					>
+						<DownloadIcon size={15} />{primary.label}
+					</a>
+				{/if}
+			{/if}
+		{/if}
 	</header>
 
-	<div class="ds-lib-pane-body">
-		<Markdown content={split.citations.length > 0 ? split.body : rawAnswer} />
+	{#if current}
+		{#if changed}<p class="ds-lib-pane-changed">{changed}</p>{/if}
+		{@const html = source !== null && isHtml(source.mediaType || current.media_type)}
+		<div class="ds-lib-pane-body" class:is-frame={html}>
+			{#if failed}
+				<p class="ds-lib-pane-note">{words.documentUnavailable}</p>
+			{:else if source && html}
+				<iframe class="ds-lib-pane-frame" sandbox="" srcdoc={framed(source.text)} title={current.title}
+				></iframe>
+			{:else if source}
+				<div class="ds-lib-pane-paper">
+					<Markdown content={stripFrontMatter(source.text)} previous={earlier ?? undefined} />
+				</div>
+			{/if}
+		</div>
+	{:else}
+		<div class="ds-lib-pane-body">
+			<Markdown content={split.citations.length > 0 ? split.body : rawAnswer} />
 
-		{#if sources.length > 0}
-			<div class="ds-lib-pane-sources">
-				<SourceList {sources} {words} {oncite} level={3} />
-			</div>
-		{/if}
-	</div>
+			{#if sources.length > 0}
+				<div class="ds-lib-pane-sources">
+					<SourceList {sources} {words} {oncite} level={3} />
+				</div>
+			{/if}
+		</div>
+	{/if}
 </aside>
 
 <style>
 	.ds-lib-pane {
 		position: fixed;
-		inset-inline: 0;
-		bottom: 0;
+		inset: 0;
 		z-index: 40;
 		display: flex;
-		height: 80svh;
+		height: 100dvh;
 		flex-direction: column;
-		border-top: 1px solid var(--ds-color-border);
-		border-start-start-radius: var(--ds-radius-xl);
-		border-start-end-radius: var(--ds-radius-xl);
 		background: var(--ds-color-surface-1);
-		box-shadow: 0 -12px 40px rgb(0 0 0 / 0.25);
 	}
 
 	.ds-lib-pane-grabber {
@@ -118,17 +306,19 @@
 		background: var(--ds-color-border);
 	}
 
+	/* A phone's sheet leads with Close; the column ends with it. */
 	.ds-lib-pane-header {
 		display: flex;
-		align-items: flex-start;
+		align-items: center;
 		gap: 0.5rem;
 		border-bottom: 1px solid var(--ds-color-border);
-		padding: 0.75rem 1rem;
+		padding: 0.5rem 1rem 0.75rem;
 	}
 
 	.ds-lib-pane-heading {
 		min-width: 0;
 		flex: 1;
+		order: 1;
 	}
 
 	.ds-lib-pane-title,
@@ -142,23 +332,24 @@
 	.ds-lib-pane-title {
 		color: var(--ds-color-foreground);
 		font-family: inherit;
-		font-size: 0.875rem;
+		font-size: 0.9375rem;
 		font-weight: 600;
 	}
 
 	.ds-lib-pane-subtitle {
+		display: none;
 		color: var(--ds-color-muted-foreground);
 		font-size: var(--ds-text-2xs);
 	}
 
 	.ds-lib-pane-close {
 		display: flex;
-		width: 2rem;
-		height: 2rem;
+		width: 2.5rem;
+		height: 2.5rem;
 		flex: none;
 		align-items: center;
 		justify-content: center;
-		margin-top: -0.25rem;
+		order: 0;
 		border: 0;
 		border-radius: var(--ds-radius-lg);
 		background: none;
@@ -174,11 +365,109 @@
 		color: var(--ds-color-foreground);
 	}
 
-	.ds-lib-pane-close:focus-visible {
+	.ds-lib-pane-close:focus-visible,
+	.ds-lib-pane-tool:focus-visible,
+	.ds-lib-pane-versions:focus-visible {
 		outline: 2px solid var(--ds-color-ring);
 		outline-offset: 2px;
 	}
 
+	.ds-lib-pane-versions {
+		order: 2;
+		border: 1px solid var(--ds-color-border);
+		border-radius: var(--ds-radius-md);
+		background: var(--ds-color-surface-1);
+		padding: 0.375rem 0.5rem;
+		color: var(--ds-color-foreground);
+		font: inherit;
+		font-size: 0.8125rem;
+	}
+
+	.ds-lib-pane-tool {
+		display: inline-flex;
+		min-height: 2.25rem;
+		align-items: center;
+		gap: 0.375rem;
+		border: 1px solid var(--ds-color-border);
+		border-radius: var(--ds-radius-md);
+		background: none;
+		padding: 0.25rem 0.625rem;
+		color: var(--ds-color-foreground);
+		font: inherit;
+		font-size: 0.8125rem;
+		text-decoration: none;
+		cursor: pointer;
+	}
+
+	.ds-lib-pane-tool:hover {
+		background: var(--ds-color-surface-2);
+	}
+
+	.ds-lib-pane-copy {
+		display: none;
+		order: 3;
+	}
+
+	.ds-lib-pane-menu {
+		position: relative;
+		display: none;
+		order: 4;
+	}
+
+	.ds-lib-pane-quick {
+		order: 3;
+	}
+
+	.ds-lib-pane-links {
+		position: absolute;
+		inset-block-start: calc(100% + 0.25rem);
+		inset-inline-end: 0;
+		z-index: 2;
+		display: flex;
+		min-width: 9rem;
+		flex-direction: column;
+		margin: 0;
+		border: 1px solid var(--ds-color-border);
+		border-radius: var(--ds-radius-md);
+		background: var(--ds-color-surface-1);
+		padding: 0.25rem;
+		box-shadow: 0 8px 24px rgb(0 0 0 / 0.25);
+		list-style: none;
+	}
+
+	.ds-lib-pane-links a {
+		display: block;
+		border-radius: var(--ds-radius-sm);
+		padding: 0.5rem 0.625rem;
+		color: var(--ds-color-foreground);
+		font-size: 0.8125rem;
+		text-decoration: none;
+	}
+
+	.ds-lib-pane-links a:hover,
+	.ds-lib-pane-links a:focus-visible {
+		background: var(--ds-color-surface-2);
+	}
+
+	.ds-lib-pane-changed {
+		display: flex;
+		align-items: center;
+		gap: 0.5rem;
+		margin: 0;
+		border-bottom: 1px solid var(--ds-color-border);
+		padding: 0.5rem 1rem;
+		color: var(--ds-color-muted-foreground);
+		font-size: 0.8125rem;
+	}
+
+	.ds-lib-pane-changed::before {
+		content: '';
+		width: 2px;
+		height: 0.875rem;
+		flex: none;
+		background: var(--ds-color-foreground);
+	}
+
 	.ds-lib-pane-body {
 		min-height: 0;
 		flex: 1;
@@ -187,6 +476,39 @@
 		padding: 0.75rem 1rem;
 	}
 
+	.ds-lib-pane-note {
+		margin: 0;
+		color: var(--ds-color-muted-foreground);
+		font-size: var(--ds-text-2xs);
+	}
+
+	/* The document is paper, light in either theme: its own ink and rules
+	   replace the app's, so a dark page does not paint it grey on grey. */
+	.ds-lib-pane-paper {
+		--ds-color-foreground: var(--ds-paper-ink, #1b1c1e);
+		--ds-color-muted-foreground: var(--ds-paper-muted, #5f6368);
+		--ds-color-border: var(--ds-paper-rule, #c4c7cc);
+		--ds-color-surface-1: var(--ds-paper-shade, #dcdee2);
+		--ds-color-primary-ink: var(--ds-paper-ink, #1b1c1e);
+		border-radius: var(--ds-radius-sm);
+		background: var(--ds-paper, #e9eaec);
+		padding: 1.25rem 1.5rem;
+		color: var(--ds-color-foreground);
+	}
+
+	.ds-lib-pane-body.is-frame {
+		overflow: hidden;
+		padding: 0;
+	}
+
+	.ds-lib-pane-frame {
+		display: block;
+		width: 100%;
+		height: 100%;
+		border: 0;
+		background: #fff;
+	}
+
 	.ds-lib-pane-sources {
 		margin-top: 1.5rem;
 	}
@@ -196,16 +518,38 @@
 			position: relative;
 			inset: auto;
 			height: auto;
-			width: 35rem;
+			width: 42rem;
 			flex: none;
-			border-top: 0;
 			border-inline-start: 1px solid var(--ds-color-border);
-			border-radius: 0;
-			box-shadow: none;
 		}
 
 		.ds-lib-pane-grabber {
 			display: none;
 		}
+
+		.ds-lib-pane-header {
+			padding-top: 0.75rem;
+		}
+
+		.ds-lib-pane-heading {
+			order: 0;
+		}
+
+		.ds-lib-pane-subtitle {
+			display: block;
+		}
+
+		.ds-lib-pane-copy,
+		.ds-lib-pane-menu {
+			display: inline-flex;
+		}
+
+		.ds-lib-pane-quick {
+			display: none;
+		}
+
+		.ds-lib-pane-close {
+			order: 5;
+		}
 	}
 </style>

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

@@ -1,8 +1,17 @@
 import { type Turn } from '../../transcript.svelte';
 import { type Citation } from '../../citations';
 import { type ChatCopy } from '../../copy';
+import { type LoadWritten, type Written, type WrittenUrl } from '../../written';
 interface Props {
-    turn: Turn;
+    /** The turn whose answer is the artefact. Absent when `versions` is given. */
+    turn?: Turn;
+    /** Every version of one written document, oldest first: the pane shows
+     *  `version` of them, with a switcher. */
+    versions?: Written[];
+    version?: number;
+    onversion?: (version: number) => void;
+    loadWritten?: LoadWritten;
+    writtenUrl?: WrittenUrl;
     onclose: () => void;
     /** Opens the cited document instead — swapping the column back, never
      *  stacking it beside the artefact. Omit and the sources still list, but

package/dist/components/conversation/conversation.svelte

@@ -20,19 +20,32 @@
 	import type { DescribeTool, Turn } from '../../transcript.svelte';
 	import type { Verdict } from '../../chat.svelte';
 	import type { Citation, LoadDocument } from '../../citations';
+	import {
+		writtenKey,
+		writtenVersions,
+		type LoadWritten,
+		type Written,
+		type WrittenUrl
+	} from '../../written';
 	import { DEFAULT_PERSONA, personaName, resolveCopy, type ChatCopy } from '../../copy';
 	import { FollowScroll } from '../../follow-scroll.svelte';
 	import AgentTranscript, {
 		type AgentTranscriptProps
 	} from '../agent-transcript/agent-transcript.svelte';
 	import ArtefactPane from '../artefact-pane/artefact-pane.svelte';
+	import type { Visual } from '../../visuals';
 	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;
+	/** What the reading column holds — a cited document, a study artefact or a
+	 *  document the persona wrote, never two at once and never two panes:
+	 *  whichever the reader last opened replaces whatever was there. A written
+	 *  document's `version` is null while the reader follows the newest. */
+	type Column =
+		| { kind: 'document'; citation: Citation }
+		| { kind: 'artefact'; turn: Turn }
+		| { kind: 'written'; name: string; version: number | null }
+		| null;
 
 	interface Props {
 		turns: Turn[];
@@ -86,6 +99,19 @@
 		showing?: string;
 		/** The persona's own words for its tools, and what they read. */
 		describeTool?: DescribeTool;
+		/** Replaces the question at `position` (its place among `turns`) with
+		 *  `text` and asks it again from there (`Chat.edit`). Offered on every
+		 *  plain question while no answer is being written; without it no turn
+		 *  can be edited. */
+		onedit?: (position: number, text: string) => Promise<boolean>;
+		/** Reads one version of a document the persona wrote, to show it in the
+		 *  column. Without it its cards link but do not open. */
+		loadWritten?: LoadWritten;
+		/** Where a version downloads. Without it no download links render. */
+		writtenUrl?: WrittenUrl;
+		/** Renderers by a fence's language (`defaultVisuals`, and the app's own):
+		 *  a block of one is drawn by its component rather than as code. */
+		visuals?: Record<string, Visual>;
 		/** Prices a turn's `outcome.costUsd` in the host's own currency and
 		 *  words ("about A$0.34"), for the footer's cost line beside a turn's
 		 *  duration. The package never converts currency itself; omitted, the
@@ -133,6 +159,10 @@
 		onopenartefact,
 		showing,
 		describeTool,
+		onedit,
+		loadWritten,
+		writtenUrl,
+		visuals,
 		collectionNames = new Set(),
 		composer,
 		turn: presentTurn,
@@ -252,6 +282,24 @@
 		return undefined;
 	}
 
+	/** Opens a written version, following the newest if it is the newest. */
+	function openWritten(written: Written) {
+		const newest = writtenVersions(turns, written.name).at(-1)?.version;
+		column = {
+			kind: 'written',
+			name: written.name,
+			version: written.version === newest ? null : written.version
+		};
+	}
+
+	const shownWritten = $derived.by(() => {
+		const open = column;
+		if (open?.kind !== 'written') return undefined;
+		const versions = writtenVersions(turns, open.name);
+		const shown = versions.find((v) => v.version === open.version) ?? versions.at(-1);
+		return { versions, version: shown?.version, key: shown ? writtenKey(shown) : undefined };
+	});
+
 	function isShowing(turn: Turn): boolean {
 		if (onopenartefact) return showing === turn.id;
 		return column?.kind === 'artefact' && column.turn.id === turn.id;
@@ -333,6 +381,16 @@
 								artefactOpen: isShowing(turn),
 								onopenartefact: opener(turn),
 								describeTool,
+								files: turn.files,
+								written: turn.written,
+								showingWritten: shownWritten?.key,
+								onopenwritten: loadWritten ? openWritten : undefined,
+								writtenUrl,
+								visuals,
+								onedit:
+									onedit && !running && !turn.kind && turn.question
+										? (text: string) => onedit(index, text)
+										: undefined,
 								formatCost,
 								oncite: oncite || loadDocument ? cite : undefined,
 								onregenerate: last && !running ? onregenerate : undefined,
@@ -387,6 +445,18 @@
 			copy={words}
 			onclose={() => (column = null)}
 		/>
+	{:else if column?.kind === 'written' && shownWritten && shownWritten.versions.length > 0}
+		<ArtefactPane
+			versions={shownWritten.versions}
+			version={shownWritten.version}
+			onversion={(version) => {
+				if (column?.kind === 'written') column = { ...column, version };
+			}}
+			{loadWritten}
+			{writtenUrl}
+			copy={words}
+			onclose={() => (column = null)}
+		/>
 	{:else if column?.kind === 'artefact'}
 		<ArtefactPane
 			turn={column.turn}