@poodle64/librarian 2026.9.6 → 2026.9.7

package/dist/follow-scroll.svelte.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Follow the stream until the reader disagrees.
+ *
+ * The whole behaviour is one rule stated three ways: a viewport already at the
+ * bottom is following; a reader who scrolls UP has stopped following; a reader
+ * who comes back to the bottom is following again. Nothing else — no timers,
+ * no "was that scroll ours or theirs" bookkeeping — because the auto-scroll
+ * this drives always lands AT the bottom, which the first clause re-affirms
+ * rather than fights.
+ *
+ * Growing content moves the bottom away from a parked reader without moving
+ * their scrollTop, so distance alone cannot say who moved: the direction of
+ * scrollTop can, and that is the only thing `measure` remembers between calls.
+ */
+/** Distance from the bottom, in px, still counted as being at the bottom.
+ *  A line of prose is ~28px; two lines of slack survives sub-pixel layout
+ *  rounding and a caret-height change without unpinning the reader. */
+export declare const FOLLOW_THRESHOLD = 64;
+export interface ScrollMetrics {
+    scrollTop: number;
+    clientHeight: number;
+    scrollHeight: number;
+}
+export declare function distanceFromBottom(m: ScrollMetrics): number;
+export declare function atBottom(m: ScrollMetrics, threshold?: number): boolean;
+export declare class FollowScroll {
+    #private;
+    /** True while the viewport should be dragged along with new content. */
+    following: boolean;
+    /** Feed every scroll event, and the metrics after every content change. */
+    measure(m: ScrollMetrics, threshold?: number): void;
+    /** A new question re-pins: the reader asked for the thing about to arrive. */
+    pin(): void;
+}

package/dist/follow-scroll.svelte.js

@@ -0,0 +1,46 @@
+/**
+ * Follow the stream until the reader disagrees.
+ *
+ * The whole behaviour is one rule stated three ways: a viewport already at the
+ * bottom is following; a reader who scrolls UP has stopped following; a reader
+ * who comes back to the bottom is following again. Nothing else — no timers,
+ * no "was that scroll ours or theirs" bookkeeping — because the auto-scroll
+ * this drives always lands AT the bottom, which the first clause re-affirms
+ * rather than fights.
+ *
+ * Growing content moves the bottom away from a parked reader without moving
+ * their scrollTop, so distance alone cannot say who moved: the direction of
+ * scrollTop can, and that is the only thing `measure` remembers between calls.
+ */
+/** Distance from the bottom, in px, still counted as being at the bottom.
+ *  A line of prose is ~28px; two lines of slack survives sub-pixel layout
+ *  rounding and a caret-height change without unpinning the reader. */
+export const FOLLOW_THRESHOLD = 64;
+export function distanceFromBottom(m) {
+    return m.scrollHeight - m.scrollTop - m.clientHeight;
+}
+export function atBottom(m, threshold = FOLLOW_THRESHOLD) {
+    return distanceFromBottom(m) <= threshold;
+}
+export class FollowScroll {
+    /** True while the viewport should be dragged along with new content. */
+    following = $state(true);
+    #lastTop = 0;
+    /** Feed every scroll event, and the metrics after every content change. */
+    measure(m, threshold = FOLLOW_THRESHOLD) {
+        // 1px of tolerance: a trackpad's fractional scrollTop otherwise reads as
+        // an upward flick on a viewport that has not actually moved.
+        const wentUp = m.scrollTop < this.#lastTop - 1;
+        this.#lastTop = m.scrollTop;
+        if (atBottom(m, threshold)) {
+            this.following = true;
+            return;
+        }
+        if (wentUp)
+            this.following = false;
+    }
+    /** A new question re-pins: the reader asked for the thing about to arrive. */
+    pin() {
+        this.following = true;
+    }
+}

package/dist/transcript.svelte.d.ts

@@ -7,6 +7,7 @@
  * verbatim under `other`, so nothing is silently dropped.
  */
 import type { AgentEvent } from './client';
+import type { Citation } from './citations';
 export interface TextBlock {
     kind: 'text';
     index: number;
@@ -34,6 +35,18 @@ export interface Outcome {
     isError?: boolean;
     error?: string;
 }
+/**
+ * The question as the READER asked it.
+ *
+ * A host prepends a system preamble to every question before it goes to the
+ * library — cadmus sends `{room.preamble}\n\n{question}` — and echoing that
+ * back into the transcript shows a colleague the machine room. Leading
+ * blank-line-separated paragraphs addressed to the model are dropped.
+ *
+ * The LAST paragraph is never dropped, whatever it starts with: someone whose
+ * entire question is "You are wrong about the leave rule" must still see it.
+ */
+export declare function readerQuestion(question: string): string;
 /** What Milton DID, in a reader's own words — never the tool's name or the
  * raw command it ran.
  *
@@ -69,6 +82,8 @@ export declare class Transcript {
     sessionId: string | null;
     model: string | null;
     outcome: Outcome | null;
+    /** Sources for the answer, from the library's own `citations` frame. */
+    citations: Citation[];
     other: AgentEvent[];
     reset(): void;
     apply(event: AgentEvent): void;
@@ -89,6 +104,18 @@ export interface ActivityGroup {
     searches: number;
 }
 export type Segment = ActivityGroup | TextBlock;
+/** One question and the answer to it, as the transcript renders it.
+ *
+ * A finished turn is a plain object the host keeps in a list; the LIVE turn is
+ * a `Transcript` spread into the same shape. Both render identically, which is
+ * what stops a conversation flickering as the last turn settles. */
+export interface Turn {
+    id: string;
+    question: string;
+    blocks: Block[];
+    outcome: Outcome | null;
+    citations?: Citation[];
+}
 /**
  * Fold a turn's flat block list into what a reader should actually see.
  *

package/dist/transcript.svelte.js

@@ -6,6 +6,24 @@
  * deltas that belong to each. An event type this does not know about is kept
  * verbatim under `other`, so nothing is silently dropped.
  */
+/**
+ * The question as the READER asked it.
+ *
+ * A host prepends a system preamble to every question before it goes to the
+ * library — cadmus sends `{room.preamble}\n\n{question}` — and echoing that
+ * back into the transcript shows a colleague the machine room. Leading
+ * blank-line-separated paragraphs addressed to the model are dropped.
+ *
+ * The LAST paragraph is never dropped, whatever it starts with: someone whose
+ * entire question is "You are wrong about the leave rule" must still see it.
+ */
+export function readerQuestion(question) {
+    const parts = question.split(/\n{2,}/);
+    let start = 0;
+    while (start < parts.length - 1 && /^(you are|you're|your role|act as|system:)\b/i.test(parts[start].trim()))
+        start += 1;
+    return parts.slice(start).join('\n\n').trim();
+}
 /** What Milton DID, in a reader's own words — never the tool's name or the
  * raw command it ran.
  *
@@ -118,6 +136,8 @@ export class Transcript {
     sessionId = $state(null);
     model = $state(null);
     outcome = $state(null);
+    /** Sources for the answer, from the library's own `citations` frame. */
+    citations = $state([]);
     other = $state([]);
     /** Content-block index is per MESSAGE, so it repeats across turns; this
      * maps the live index onto a position in the flat list. Cleared whenever a
@@ -130,6 +150,7 @@ export class Transcript {
     reset() {
         this.blocks = [];
         this.outcome = null;
+        this.citations = [];
         this.other = [];
         this.#open.clear();
     }
@@ -149,6 +170,12 @@ export class Transcript {
             };
             return;
         }
+        // Emitted after the final assistant text, so it lands on a turn that is
+        // otherwise complete.
+        if (event.type === 'citations') {
+            this.citations = event.items ?? [];
+            return;
+        }
         if (event.type === 'library_error') {
             this.outcome = { isError: true, error: event.error ?? "Milton can't be reached right now." };
             return;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@poodle64/librarian",
-	"version": "2026.9.6",
+	"version": "2026.9.7",
 	"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",
@@ -30,6 +30,18 @@
 			"types": "./dist/history.svelte.d.ts",
 			"svelte": "./dist/history.svelte.js"
 		},
+		"./citations": {
+			"types": "./dist/citations.d.ts",
+			"svelte": "./dist/citations.js"
+		},
+		"./attachments": {
+			"types": "./dist/attachments.d.ts",
+			"svelte": "./dist/attachments.js"
+		},
+		"./follow-scroll": {
+			"types": "./dist/follow-scroll.svelte.d.ts",
+			"svelte": "./dist/follow-scroll.svelte.js"
+		},
 		"./*": {
 			"types": "./dist/components/*/index.d.ts",
 			"svelte": "./dist/components/*/index.js"
@@ -55,6 +67,7 @@
 		"isomorphic-dompurify": "^3.23.0",
 		"jsdom": "^29.1.1",
 		"marked": "^18.0.11",
+		"playwright": "^1.62.0",
 		"publint": "^0.3.15",
 		"shiki": "^4.4.3",
 		"svelte": "^5.56.2",
@@ -67,7 +80,8 @@
 		"build": "svelte-kit sync && svelte-package && publint",
 		"check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
 		"test": "pnpm run build && vitest run",
-		"prepublishOnly": "pnpm run build"
+		"prepublishOnly": "pnpm run build",
+		"screenshots": "node scripts/screenshots.mjs"
 	},
 	"packageManager": "pnpm@10.28.0"
 }