@poodle64/librarian 2026.9.13 → 2026.9.15

package/dist/components/source-list/source-list.svelte

@@ -0,0 +1,137 @@
+<!--
+  What an answer cited, as a list a reader can open.
+
+  One component rather than the same twenty lines in the transcript and again
+  in the artefact pane: the trust mark, the number chip and the disabled state
+  of a citation with no document behind it are one decision, and two copies of
+  it is two places for them to drift apart.
+-->
+<script lang="ts">
+	import { trustMark, type Citation } from '../../citations';
+	import type { LibrarianCopy } from '../../copy';
+
+	interface Props {
+		sources: Citation[];
+		words: LibrarianCopy;
+		/** Opens the document. Omit and the rows list but do not open. */
+		oncite?: (citation: Citation) => void;
+		/** `h2` in a transcript turn, `h3` under the artefact's own title. */
+		level?: 2 | 3;
+	}
+
+	let { sources, words, oncite, level = 2 }: Props = $props();
+</script>
+
+<section class="ds-lib-sources">
+	{#if level === 2}
+		<h2 class="ds-lib-sources-heading">{words.sources}</h2>
+	{:else}
+		<h3 class="ds-lib-sources-heading">{words.sources}</h3>
+	{/if}
+	<ol class="ds-lib-sources-list">
+		{#each sources as source (source.n)}
+			{@const mark = trustMark(source, words)}
+			<li>
+				<button
+					type="button"
+					class="ds-lib-source"
+					onclick={() => oncite?.(source)}
+					disabled={!source.document_id || !oncite}
+				>
+					<span class="ds-lib-source-n">{source.n}</span>
+					<span class="ds-lib-source-text">
+						<span class="ds-lib-source-title">{source.title}</span>
+						{#if source.section}<span class="ds-lib-source-section"> · {source.section}</span>{/if}
+						<!-- Same muted register as the section, deliberately. An
+						     unverified source is not an error and must not be dressed
+						     as one; the words carry the difference, and a red one
+						     would have a colleague discount a document that is
+						     simply new. -->
+						{#if mark}<span class="ds-lib-source-mark"> · {mark}</span>{/if}
+					</span>
+				</button>
+			</li>
+		{/each}
+	</ol>
+</section>
+
+<style>
+	.ds-lib-sources-heading {
+		margin: 0 0 0.375rem;
+		color: var(--ds-color-muted-foreground);
+		font-family: inherit;
+		font-size: var(--ds-text-2xs);
+		font-weight: 500;
+		letter-spacing: 0.05em;
+		text-transform: uppercase;
+	}
+
+	.ds-lib-sources-list {
+		display: flex;
+		flex-direction: column;
+		gap: 0.25rem;
+		margin: 0;
+		padding: 0;
+		list-style: none;
+	}
+
+	.ds-lib-source {
+		display: flex;
+		width: 100%;
+		align-items: baseline;
+		gap: 0.5rem;
+		border: 1px solid var(--ds-color-border);
+		border-radius: var(--ds-radius-lg);
+		background: none;
+		padding: 0.375rem 0.625rem;
+		color: inherit;
+		font: inherit;
+		font-size: 0.875rem;
+		text-align: start;
+		cursor: pointer;
+		transition:
+			background-color 150ms ease,
+			border-color 150ms ease;
+	}
+
+	.ds-lib-source:hover:not(:disabled) {
+		border-color: var(--ds-color-border-strong);
+		background: var(--ds-color-surface-2);
+	}
+
+	.ds-lib-source:focus-visible {
+		outline: 2px solid var(--ds-color-ring);
+		outline-offset: 2px;
+	}
+
+	.ds-lib-source:disabled {
+		cursor: default;
+	}
+
+	.ds-lib-source-n {
+		flex: none;
+		border-radius: var(--ds-radius-sm);
+		background: color-mix(in oklab, var(--ds-color-primary) 15%, transparent);
+		padding-inline: 0.375rem;
+		color: var(--ds-color-foreground);
+		font-family: var(--ds-font-code);
+		font-size: var(--ds-text-2xs);
+		font-variant-numeric: tabular-nums;
+	}
+
+	.ds-lib-source-text {
+		min-width: 0;
+	}
+
+	.ds-lib-source-title {
+		color: var(--ds-color-foreground);
+	}
+
+	.ds-lib-source-section {
+		color: var(--ds-color-muted-foreground);
+	}
+
+	.ds-lib-source-mark {
+		color: color-mix(in oklab, var(--ds-color-muted-foreground) 80%, transparent);
+	}
+</style>

package/dist/components/source-list/source-list.svelte.d.ts

@@ -0,0 +1,13 @@
+import { type Citation } from '../../citations';
+import type { LibrarianCopy } from '../../copy';
+interface Props {
+    sources: Citation[];
+    words: LibrarianCopy;
+    /** Opens the document. Omit and the rows list but do not open. */
+    oncite?: (citation: Citation) => void;
+    /** `h2` in a transcript turn, `h3` under the artefact's own title. */
+    level?: 2 | 3;
+}
+declare const SourceList: import("svelte").Component<Props, {}, "">;
+type SourceList = ReturnType<typeof SourceList>;
+export default SourceList;

package/dist/components/thinking-row/thinking-row.svelte

@@ -1,13 +1,13 @@
 <!--
-  One line of Milton's working-out, behind a chevron.
+  One line of the persona's working-out, behind a chevron.
 
   Two different blocks render as this row and deliberately read the same. A
-  real `thinking` block is one; the other is a `text` block Milton wrote
-  BETWEEN two tool calls — "Let me also check whether…" — which the caller
-  stream gives no way to tell from the answer except by position, and which
-  read as answer prose on production until `segment()` started re-homing it
-  here. To a reader both are the same thing: what he was working through, not
-  what he concluded. So both fold, and both fold by default.
+  real `thinking` block is one; the other is a `text` block written BETWEEN two
+  tool calls — "Let me also check whether…" — which the caller stream gives no
+  way to tell from the answer except by position, and which read as answer
+  prose on production until `segment()` started re-homing it here. To a reader
+  both are the same thing: what was being worked through, not what was
+  concluded. So both fold, and both fold by default.
 -->
 <script lang="ts">
 	import ChevronRightIcon from '@lucide/svelte/icons/chevron-right';
@@ -22,25 +22,76 @@
 	let open = $state(false);
 </script>
 
-<div class="text-sm">
+<div class="ds-lib-thinking">
 	<button
 		type="button"
-		class="flex items-center gap-2 py-0.5 text-left"
+		class="ds-lib-thinking-row"
 		onclick={() => (open = !open)}
 		aria-expanded={open}
 	>
-		<ChevronRightIcon
-			class="text-muted-foreground size-3 transition-transform {open ? 'rotate-90' : ''}"
-		/>
-		<span class={active ? 'text-foreground font-medium' : 'text-muted-foreground'}>
+		<span class="ds-lib-thinking-chevron" class:is-open={open}>
+			<ChevronRightIcon size={12} />
+		</span>
+		<span class="ds-lib-thinking-label" class:is-active={active}>
 			{active ? 'Thinking…' : 'Thought'}
 		</span>
 	</button>
 	{#if open}
-		<p
-			class="text-muted-foreground border-border mt-1 ml-1.25 border-l pl-3 text-sm whitespace-pre-wrap"
-		>
-			{block.text}
-		</p>
+		<p class="ds-lib-thinking-text">{block.text}</p>
 	{/if}
 </div>
+
+<style>
+	.ds-lib-thinking {
+		font-size: 0.875rem;
+		line-height: 1.25rem;
+	}
+
+	.ds-lib-thinking-row {
+		display: flex;
+		align-items: center;
+		gap: 0.5rem;
+		padding-block: 0.125rem;
+		border: 0;
+		background: none;
+		color: inherit;
+		font: inherit;
+		text-align: start;
+		cursor: pointer;
+	}
+
+	.ds-lib-thinking-chevron {
+		display: flex;
+		flex: none;
+		color: var(--ds-color-muted-foreground);
+		transition: transform 150ms ease;
+	}
+
+	.ds-lib-thinking-chevron.is-open {
+		transform: rotate(90deg);
+	}
+
+	.ds-lib-thinking-label {
+		color: var(--ds-color-muted-foreground);
+	}
+
+	.ds-lib-thinking-label.is-active {
+		color: var(--ds-color-foreground);
+		font-weight: 500;
+	}
+
+	.ds-lib-thinking-text {
+		margin: 0.25rem 0 0;
+		margin-inline-start: 0.3125rem;
+		border-inline-start: 1px solid var(--ds-color-border);
+		padding-inline-start: 0.75rem;
+		color: var(--ds-color-muted-foreground);
+		white-space: pre-wrap;
+	}
+
+	@media (prefers-reduced-motion: reduce) {
+		.ds-lib-thinking-chevron {
+			transition: none;
+		}
+	}
+</style>

package/dist/components/tool-row/tool-row.svelte

@@ -5,9 +5,9 @@
   dimmed sub-line. Borders and badge pills make a run of five calls read as
   five separate events rather than one train of thought.
 
-  The row says what Milton DID, in a reader's own words — never the tool's
-  name or the raw command it ran. Expanding a settled row shows what came
-  back, never what was typed.
+  The row says what the persona DID, in a reader's own words — never the
+  tool's name or the raw command it ran. Expanding a settled row shows what
+  came back, never what was typed.
 -->
 <script lang="ts">
 	import ChevronRightIcon from '@lucide/svelte/icons/chevron-right';
@@ -26,46 +26,152 @@
 
 	const settled = $derived(block.result !== undefined);
 	const said = $derived(describe(block));
-	const tone = $derived(
-		block.isError ? 'bg-status-error' : settled ? 'bg-status-success' : 'bg-status-info'
-	);
+	const tone = $derived(block.isError ? 'error' : settled ? 'success' : 'info');
 	const lines = $derived(block.result ? block.result.split('\n').length : 0);
 </script>
 
-<div class="text-sm">
+<div class="ds-lib-tool">
 	<button
 		type="button"
-		class="flex w-full items-center gap-2 rounded py-0.5 text-left"
+		class="ds-lib-tool-row"
 		onclick={() => (open = !open)}
 		disabled={!settled}
 		aria-expanded={open}
 	>
-		<span class="flex w-3 shrink-0 items-center justify-center">
-			{#if settled}
-				<ChevronRightIcon
-					class="text-muted-foreground size-3 transition-transform {open ? 'rotate-90' : ''}"
-				/>
-			{/if}
+		<span class="ds-lib-tool-chevron" class:is-open={open}>
+			{#if settled}<ChevronRightIcon size={12} />{/if}
 		</span>
-		<span class="size-1.5 shrink-0 rounded-full {tone} {!settled && running ? 'animate-pulse' : ''}"
-		></span>
-		<span class="text-muted-foreground truncate">
-			<span class="text-foreground font-medium">{said.verb}</span>
-			{#if said.object}<span class="text-foreground/80">{said.object}</span>{/if}
-			{#if repeats > 1}<span class="text-muted-foreground">· {repeats} pages</span>{/if}
+		<span class="ds-lib-tool-dot" data-tone={tone} class:is-live={!settled && running}></span>
+		<span class="ds-lib-tool-said">
+			<span class="ds-lib-tool-verb">{said.verb}</span>
+			{#if said.object}<span class="ds-lib-tool-object">{said.object}</span>{/if}
+			{#if repeats > 1}<span>· {repeats} pages</span>{/if}
 		</span>
 	</button>
 
 	{#if open}
-		<div class="border-border mt-1 ml-5.5 border-l pl-3">
+		<div class="ds-lib-tool-body">
 			{#if block.result}
-				<pre
-					class="text-muted-foreground mt-1 max-h-72 overflow-auto font-mono text-xs whitespace-pre-wrap">{block.result}</pre>
+				<pre class="ds-lib-tool-result">{block.result}</pre>
 			{/if}
 		</div>
 	{:else if settled && lines > 0}
-		<p class="text-muted-foreground pl-5.5 text-xs">
-			{lines === 1 ? '1 line' : `${lines} lines`}
-		</p>
+		<p class="ds-lib-tool-lines">{lines === 1 ? '1 line' : `${lines} lines`}</p>
 	{/if}
 </div>
+
+<style>
+	.ds-lib-tool {
+		font-size: 0.875rem;
+		line-height: 1.25rem;
+	}
+
+	.ds-lib-tool-row {
+		display: flex;
+		width: 100%;
+		align-items: center;
+		gap: 0.5rem;
+		padding-block: 0.125rem;
+		border: 0;
+		background: none;
+		color: inherit;
+		font: inherit;
+		text-align: start;
+		cursor: pointer;
+	}
+
+	.ds-lib-tool-row:disabled {
+		cursor: default;
+	}
+
+	.ds-lib-tool-chevron {
+		display: flex;
+		width: 0.75rem;
+		flex: none;
+		align-items: center;
+		justify-content: center;
+		color: var(--ds-color-muted-foreground);
+		transition: transform 150ms ease;
+	}
+
+	.ds-lib-tool-chevron.is-open {
+		transform: rotate(90deg);
+	}
+
+	.ds-lib-tool-dot {
+		width: 0.375rem;
+		height: 0.375rem;
+		flex: none;
+		border-radius: var(--ds-radius-full);
+		background: var(--ds-color-status-info);
+	}
+
+	.ds-lib-tool-dot[data-tone='error'] {
+		background: var(--ds-color-status-error);
+	}
+
+	.ds-lib-tool-dot[data-tone='success'] {
+		background: var(--ds-color-status-success);
+	}
+
+	.ds-lib-tool-dot.is-live {
+		animation: ds-lib-tool-pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
+	}
+
+	.ds-lib-tool-said {
+		min-width: 0;
+		overflow: hidden;
+		text-overflow: ellipsis;
+		white-space: nowrap;
+		color: var(--ds-color-muted-foreground);
+	}
+
+	.ds-lib-tool-verb {
+		color: var(--ds-color-foreground);
+		font-weight: 500;
+	}
+
+	.ds-lib-tool-object {
+		color: color-mix(in oklab, var(--ds-color-foreground) 80%, transparent);
+	}
+
+	.ds-lib-tool-body {
+		margin-top: 0.25rem;
+		margin-inline-start: 1.375rem;
+		border-inline-start: 1px solid var(--ds-color-border);
+		padding-inline-start: 0.75rem;
+	}
+
+	.ds-lib-tool-result {
+		margin-top: 0.25rem;
+		max-height: 18rem;
+		overflow: auto;
+		color: var(--ds-color-muted-foreground);
+		font-family: var(--ds-font-code);
+		font-size: var(--ds-text-2xs);
+		white-space: pre-wrap;
+	}
+
+	.ds-lib-tool-lines {
+		margin: 0;
+		padding-inline-start: 1.375rem;
+		color: var(--ds-color-muted-foreground);
+		font-size: var(--ds-text-2xs);
+	}
+
+	@keyframes ds-lib-tool-pulse {
+		50% {
+			opacity: 0.4;
+		}
+	}
+
+	@media (prefers-reduced-motion: reduce) {
+		.ds-lib-tool-dot.is-live {
+			animation: none;
+		}
+
+		.ds-lib-tool-chevron {
+			transition: none;
+		}
+	}
+</style>

package/dist/components/working/working.svelte

@@ -8,17 +8,22 @@
 
   Two moving parts, deliberately: a word that changes so the page is evidently
   alive, and a clock that only goes up so a long wait still reads as progress
-  rather than as a hang.
+  rather than as a hang. The words name whoever is answering — they came from
+  `copy`, which the host's `name` composed, so this component knows no persona.
 -->
 <script lang="ts">
+	import { resolveCopy, type LibrarianCopy } from '../../copy';
+
 	interface Props {
 		/** Shown instead of the cycling word once real work is identifiable. */
 		label?: string;
+		/** The persona's words. Resolved from `name` upstream. */
+		copy?: Partial<LibrarianCopy>;
 	}
 
-	let { label }: Props = $props();
+	let { label, copy }: Props = $props();
 
-	const WORDS = ['Milton is looking', 'Milton is reading'];
+	const words = $derived(resolveCopy(copy));
 
 	let tick = $state(0);
 	let elapsed = $state(0);
@@ -32,11 +37,50 @@
 		};
 	});
 
-	const word = $derived(label ?? WORDS[tick % WORDS.length]);
+	const word = $derived(label ?? words.working[tick % words.working.length]);
 </script>
 
-<div class="text-muted-foreground flex items-center gap-2 text-sm">
-	<span class="bg-status-info size-1.5 animate-pulse rounded-full"></span>
+<div class="ds-lib-working">
+	<span class="ds-lib-working-dot"></span>
 	<span>{word}…</span>
-	<span class="text-muted-foreground/70 font-mono text-xs tabular-nums">{elapsed}s</span>
+	<span class="ds-lib-working-clock">{elapsed}s</span>
 </div>
+
+<style>
+	.ds-lib-working {
+		display: flex;
+		align-items: center;
+		gap: 0.5rem;
+		color: var(--ds-color-muted-foreground);
+		font-size: 0.875rem;
+		line-height: 1.25rem;
+	}
+
+	.ds-lib-working-dot {
+		width: 0.375rem;
+		height: 0.375rem;
+		flex: none;
+		border-radius: var(--ds-radius-full);
+		background: var(--ds-color-status-info);
+		animation: ds-lib-pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
+	}
+
+	.ds-lib-working-clock {
+		font-family: var(--ds-font-code);
+		font-size: var(--ds-text-2xs);
+		font-variant-numeric: tabular-nums;
+		opacity: 0.7;
+	}
+
+	@keyframes ds-lib-pulse {
+		50% {
+			opacity: 0.4;
+		}
+	}
+
+	@media (prefers-reduced-motion: reduce) {
+		.ds-lib-working-dot {
+			animation: none;
+		}
+	}
+</style>

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

@@ -1,6 +1,9 @@
+import { type LibrarianCopy } from '../../copy';
 interface Props {
     /** Shown instead of the cycling word once real work is identifiable. */
     label?: string;
+    /** The persona's words. Resolved from `name` upstream. */
+    copy?: Partial<LibrarianCopy>;
 }
 declare const Working: import("svelte").Component<Props, {}, "">;
 type Working = ReturnType<typeof Working>;

package/dist/copy.d.ts

@@ -2,16 +2,24 @@
  * Every word this package puts in front of a reader, in one place.
  *
  * Here rather than inline in each component because these sentences are the
- * package's opinion about how Milton talks to a colleague, and an app that
- * needs a different register — a different name for the librarian, a room
- * whose boundary is worded by its own subject-matter owner — must be able to
- * change one string without forking a component.
+ * package's opinion about how an agent talks to a colleague, and an app that
+ * needs a different register — a room whose boundary is worded by its own
+ * subject-matter owner — must be able to change one string without forking a
+ * component.
+ *
+ * NO STRING HERE NAMES A PERSONA. The name is an argument: a consuming app
+ * says who is speaking once, and every sentence the package renders is built
+ * from that. Milton is the library's own persona and therefore the default,
+ * which is a different thing from being baked in — a package that hardcodes
+ * one app's persona is a package that lies in every other app, and did:
+ * Pebblestone's Penny introduced herself as Milton for a fortnight.
  *
  * Every component takes `copy` as a PARTIAL and resolves it itself, so a host
- * overriding one line does not have to restate the other eleven, and a
- * component used directly behaves the same as one reached through
- * `Conversation`.
+ * overriding one line does not have to restate the others, and a component
+ * used directly behaves the same as one reached through `Conversation`.
  */
+/** The library's own persona: the default wherever a consumer names none. */
+export declare const DEFAULT_PERSONA = "Milton";
 export interface LibrarianCopy {
     /** Prefixes the date on a verified source: "verified 23 Jun 2026". */
     verified: string;
@@ -21,12 +29,23 @@ export interface LibrarianCopy {
     notHeld: string;
     /** Shown when the run itself ended in error and said nothing about why. */
     answerFailed: string;
+    /** Shown when the stream never opened, or died mid-answer. */
+    unreachable: string;
     /** Heading over the list of what an answer cited. */
     sources: string;
-    /** Heading over the follow-up questions the librarian offered. */
+    /** Heading over the follow-up questions the persona offered. */
     suggestions: string;
     /** The collapsed scope statement's own label. */
     scope: string;
+    /** The empty transcript's opening line. */
+    welcome: string;
+    /** The composer's placeholder, idle and while an answer streams. */
+    askPlaceholder: string;
+    answeringPlaceholder: string;
+    /** The pre-first-token words, cycled one every 2.6s. */
+    working: string[];
+    /** The scroll region's accessible name. */
+    conversationLabel: string;
     copyAnswer: string;
     copiedAnswer: string;
     askAgain: string;
@@ -34,13 +53,29 @@ export interface LibrarianCopy {
     closeSource: string;
     documentUnavailable: string;
 }
+/**
+ * The display name for a persona a host identified by its slug.
+ *
+ * A route parameter is `penny`, and a colleague reading the screen is talking
+ * to Penny. A host that already wrote the name the way it should read — any
+ * capital at all — is left alone, so "McTavish" and "eight" both survive.
+ */
+export declare function personaName(name: string): string;
+/**
+ * The package's words, spoken by one named persona.
+ *
+ * Deliberately free of pronouns: the persona is whoever the consuming app
+ * says it is, and a sentence that guesses is wrong for half of them.
+ */
+export declare function copyFor(name?: string): LibrarianCopy;
+/** The library's own words, for a host that names no persona. */
 export declare const DEFAULT_COPY: LibrarianCopy;
 /**
- * The package's words with a host's overrides on top.
+ * One persona's words with a host's overrides on top.
  *
  * An explicitly `undefined` key is dropped rather than spread, because
  * `{...defaults, ...{ sources: undefined }}` leaves a component rendering
  * nothing at all — and that is exactly the shape a host produces by passing a
  * value it computed from state that has not loaded yet.
  */
-export declare function resolveCopy(overrides?: Partial<LibrarianCopy>): LibrarianCopy;
+export declare function resolveCopy(overrides?: Partial<LibrarianCopy>, name?: string): LibrarianCopy;