@poodle64/librarian 2026.10.4 → 2026.10.5

package/dist/steps.js

@@ -0,0 +1,168 @@
+/**
+ * A turn's steps, said in one sentence.
+ *
+ * The turn folds its steps behind one line composed from them ("Read your
+ * attachment, searched the library and the web, and wrote a minute"), the way
+ * Claude.ai folds its own. Composed here from what each step IS (its tool and,
+ * for a document, the document's own kind), never from the persona's words.
+ */
+import { fill } from './copy';
+const WEB = new Set(['mcp__supacrawl__supacrawl_search', 'mcp__supacrawl__supacrawl_scrape']);
+/** What sort of step a block is. */
+export function stepKind(block) {
+    if (block.kind !== 'tool')
+        return 'thought';
+    const { name } = block;
+    if (name === 'mcp__library__search')
+        return 'library';
+    if (name === 'mcp__library__document_content' || name === 'mcp__library__document_detail')
+        return 'open';
+    if (WEB.has(name))
+        return 'web';
+    if (name === 'Write')
+        return 'write';
+    if (name === 'Edit')
+        return 'edit';
+    if (name.startsWith('mcp__') && name.endsWith('__ocr'))
+        return 'attachment';
+    if (name === 'Read') {
+        // A staged library page reads as a document opened; anything else Read
+        // takes is what the person attached.
+        const path = pathOf(block);
+        return /page-\d+\.md$/.test(path) ? 'open' : 'attachment';
+    }
+    return 'other';
+}
+function inputOf(block) {
+    try {
+        const parsed = JSON.parse(block.rawInput);
+        return typeof parsed === 'object' && parsed !== null ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+const pathOf = (block) => {
+    const input = inputOf(block);
+    const path = input.file_path ?? input.path;
+    return typeof path === 'string' ? path : '';
+};
+/** The document a Write or Edit step made a version of, by the name it wrote to. */
+function documentOf(block, written) {
+    const path = pathOf(block);
+    if (!path)
+        return undefined;
+    return written.filter((w) => path === w.name || path.endsWith(`/${w.name}`)).at(-1);
+}
+const kindWord = (doc, words) => ((doc?.kind ?? '').trim() || words.documentKind).toLowerCase();
+const upper = (text) => text.charAt(0).toUpperCase() + text.slice(1);
+function join(phrases, and) {
+    if (phrases.length <= 2)
+        return phrases.join(` ${and} `);
+    return `${phrases.slice(0, -1).join(', ')}, ${and} ${phrases.at(-1)}`;
+}
+/**
+ * The fold's line: the sentence, and what trails it ("6 steps", or the
+ * version a lone edit made).
+ */
+export function stepsSummary(steps, written, words) {
+    let library = false;
+    let web = false;
+    let searchAt = -1;
+    const phrases = [];
+    const add = (phrase) => {
+        if (!phrases.includes(phrase))
+            phrases.push(phrase);
+    };
+    for (const { block } of steps) {
+        const kind = stepKind(block);
+        const doc = block.kind === 'tool' ? documentOf(block, written) : undefined;
+        if (kind === 'library' || kind === 'web') {
+            if (kind === 'library')
+                library = true;
+            else
+                web = true;
+            if (searchAt < 0) {
+                searchAt = phrases.length;
+                phrases.push('');
+            }
+        }
+        else if (kind === 'attachment')
+            add(words.stepsRead);
+        else if (kind === 'open')
+            add(words.stepsOpened);
+        else if (kind === 'write')
+            add(fill(words.stepsWrote, { kind: kindWord(doc, words) }));
+        else if (kind === 'edit')
+            add(fill(words.stepsEdited, { kind: kindWord(doc, words) }));
+        else if (kind === 'other')
+            add(words.stepsOther);
+    }
+    if (searchAt >= 0)
+        phrases[searchAt] =
+            library && web ? words.stepsSearchedBoth : library ? words.stepsSearchedLibrary : words.stepsSearchedWeb;
+    // Thinking is told only where it is all there was.
+    if (phrases.length === 0)
+        phrases.push(words.stepsThought);
+    const only = steps.length === 1 ? steps[0].block : undefined;
+    const lone = only?.kind === 'tool' && stepKind(only) === 'edit' ? documentOf(only, written) : undefined;
+    return {
+        sentence: upper(join(phrases, words.stepsAnd)),
+        trail: lone
+            ? fill(words.writtenVersion, { n: lone.version })
+            : steps.length === 1
+                ? words.stepCountOne
+                : fill(words.stepCount, { n: steps.length })
+    };
+}
+/** What is happening now: the step still running, or the latest one. */
+export function stepsNow(steps, written, words) {
+    const step = steps.findLast(({ block }) => block.kind === 'tool' && block.result === undefined)
+        ?? steps.at(-1);
+    if (!step)
+        return words.nowOther;
+    const kind = stepKind(step.block);
+    const doc = step.block.kind === 'tool' ? documentOf(step.block, written) : undefined;
+    const now = {
+        attachment: words.nowRead,
+        library: words.nowLibrary,
+        web: words.nowWeb,
+        open: words.nowOpen,
+        write: fill(words.nowWrite, { kind: kindWord(doc, words) }),
+        edit: fill(words.nowEdit, { kind: kindWord(doc, words) }),
+        thought: words.nowThought,
+        other: words.nowOther
+    };
+    return now[kind];
+}
+function parse(text) {
+    try {
+        return text ? JSON.parse(text) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The count at a step's right hand, where its result shows one. */
+export function stepMeta(block, words) {
+    if (block.kind !== 'tool' || block.isError || block.result === undefined)
+        return '';
+    if (block.name === 'mcp__library__search') {
+        const found = parse(block.result);
+        const list = Array.isArray(found) ? found : (found?.hits ?? found?.results);
+        return Array.isArray(list) ? fill(words.stepFound, { n: list.length }) : '';
+    }
+    if (block.name === 'mcp__supacrawl__supacrawl_search') {
+        const found = parse(block.result)?.results;
+        if (!Array.isArray(found))
+            return '';
+        return found.length === 1 ? words.stepPageRead : fill(words.stepPagesRead, { n: found.length });
+    }
+    return '';
+}
+/** How long a thinking block ran, in whole seconds, where it was timed. */
+export function thoughtSeconds(block) {
+    if (block.kind !== 'thinking' || block.startedAt === undefined || block.endedAt === undefined)
+        return undefined;
+    return Math.max(1, Math.round((block.endedAt - block.startedAt) / 1000));
+}

package/dist/transcript.svelte.d.ts

@@ -18,6 +18,10 @@ export interface ThinkingBlock {
     kind: 'thinking';
     index: number;
     text: string;
+    /** Epoch ms the block opened and closed on this page, measured live; absent
+     *  for one the stream delivered whole or read back. */
+    startedAt?: number;
+    endedAt?: number;
 }
 export interface ToolBlock {
     kind: 'tool';

package/dist/transcript.svelte.js

@@ -235,7 +235,12 @@ export function fold(into, state, event) {
                 version: event.version,
                 media_type: typeof event.media_type === 'string' ? event.media_type : '',
                 bytes: typeof event.bytes === 'number' ? event.bytes : undefined,
-                formats: Array.isArray(event.formats) ? event.formats.map(String) : []
+                formats: Array.isArray(event.formats) ? event.formats.map(String) : [],
+                title: typeof event.title === 'string' && event.title ? event.title : event.name,
+                kind: typeof event.kind === 'string' ? event.kind : null,
+                changes: typeof event.changes === 'string' ? event.changes : null,
+                pages: typeof event.pages === 'number' ? event.pages : 0,
+                at: Date.now()
             });
         }
         return true;
@@ -293,7 +298,7 @@ export function fold(into, state, event) {
         if (cb.type === 'text')
             into.blocks.push({ kind: 'text', index: position, text: '' });
         else if (cb.type === 'thinking')
-            into.blocks.push({ kind: 'thinking', index: position, text: '' });
+            into.blocks.push({ kind: 'thinking', index: position, text: '', startedAt: Date.now() });
         else if (cb.type === 'tool_use')
             into.blocks.push({
                 kind: 'tool',
@@ -304,6 +309,12 @@ export function fold(into, state, event) {
             });
         return true;
     }
+    if (inner.type === 'content_block_stop' && inner.index !== undefined) {
+        const block = into.blocks[state.open.get(inner.index) ?? -1];
+        if (block?.kind === 'thinking' && block.startedAt !== undefined)
+            block.endedAt = Date.now();
+        return true;
+    }
     if (inner.type === 'content_block_delta' && inner.index !== undefined) {
         const position = state.open.get(inner.index);
         if (position === undefined)

package/dist/visuals.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The renderers for a persona's in-answer visuals, keyed on a fence's language.
+ *
+ * The persona writes a fenced block and the page draws it: the data is the
+ * persona's, every colour, face and size is the app's. A renderer is a
+ * component and the `parse` that turns the block's text into the `value` it
+ * draws, throwing on a block that is not one (the page then shows the code).
+ * `parse` returns anything, not JSON alone, so a renderer for a language that
+ * is not JSON registers the same way.
+ */
+import type { Component } from 'svelte';
+export interface Visual {
+    component: Component<{
+        value: unknown;
+        source: string;
+    }>;
+    /** The block's text as the value its component draws; throws on a block that is invalid. */
+    parse: (source: string) => unknown;
+}
+export interface TimelineValue {
+    title: string;
+    events: Array<{
+        date: string;
+        title: string;
+        detail: string;
+    }>;
+}
+export interface CardValue {
+    name: string;
+    kind: string;
+    summary: string;
+    facts: Array<{
+        label: string;
+        value: string;
+    }>;
+}
+/** A chart, a timeline and an entity card. An app adds to these or replaces one through `ChatExtensions.visuals`. */
+export declare const defaultVisuals: Record<string, Visual>;

package/dist/visuals.js

@@ -0,0 +1,82 @@
+/**
+ * The renderers for a persona's in-answer visuals, keyed on a fence's language.
+ *
+ * The persona writes a fenced block and the page draws it: the data is the
+ * persona's, every colour, face and size is the app's. A renderer is a
+ * component and the `parse` that turns the block's text into the `value` it
+ * draws, throwing on a block that is not one (the page then shows the code).
+ * `parse` returns anything, not JSON alone, so a renderer for a language that
+ * is not JSON registers the same way.
+ */
+import EntityCard from './components/visual-block/entity-card.svelte';
+import Timeline from './components/visual-block/timeline.svelte';
+import VegaChart from './components/visual-block/vega-chart.svelte';
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const text = (value) => typeof value === 'string' ? value : typeof value === 'number' ? String(value) : '';
+const object = (source) => {
+    const value = JSON.parse(source);
+    if (!isRecord(value))
+        throw new Error('not an object');
+    return value;
+};
+/** Any string naming an address: a spec that carries one could fetch it, or link to it carrying the conversation out. */
+const ADDRESS = /^[a-z][a-z0-9+.-]*:|\/\//i;
+/**
+ * A spec that names an address anywhere, by key or by value, or carries
+ * `usermeta`, whose `embedOptions` vega-embed merges over the app's own
+ * (`config` or `patch` as a URL is fetched, `actions` turns the export menu back on).
+ */
+function addressed(value) {
+    if (typeof value === 'string')
+        return ADDRESS.test(value.trim());
+    if (Array.isArray(value))
+        return value.some(addressed);
+    if (!isRecord(value))
+        return false;
+    return Object.entries(value).some(
+    // `$schema` names the spec's own version and is never drawn or fetched (`vega-chart` drops it).
+    ([key, inner]) => key !== '$schema' && (key === 'url' || key === 'href' || key === 'usermeta' || addressed(inner)));
+}
+const VIEWS = ['mark', 'layer', 'hconcat', 'vconcat', 'concat', 'facet', 'repeat'];
+function parseVega(source) {
+    const spec = object(source);
+    if (!VIEWS.some((key) => key in spec))
+        throw new Error('not a view');
+    if (addressed(spec))
+        throw new Error('names an address');
+    return spec;
+}
+function parseTimeline(source) {
+    const value = object(source);
+    if (!Array.isArray(value.events))
+        throw new Error('no events');
+    return {
+        title: text(value.title),
+        events: value.events.map((event) => {
+            if (!isRecord(event) || !text(event.title))
+                throw new Error('an event with no title');
+            return { date: text(event.date), title: text(event.title), detail: text(event.detail) };
+        })
+    };
+}
+function parseCard(source) {
+    const value = object(source);
+    if (!text(value.name))
+        throw new Error('no name');
+    const facts = Array.isArray(value.facts) ? value.facts : [];
+    return {
+        name: text(value.name),
+        kind: text(value.kind),
+        summary: text(value.summary),
+        facts: facts
+            .filter(isRecord)
+            .map((fact) => ({ label: text(fact.label), value: text(fact.value) }))
+            .filter((fact) => fact.label || fact.value)
+    };
+}
+/** A chart, a timeline and an entity card. An app adds to these or replaces one through `ChatExtensions.visuals`. */
+export const defaultVisuals = {
+    'vega-lite': { component: VegaChart, parse: parseVega },
+    timeline: { component: Timeline, parse: parseTimeline },
+    card: { component: EntityCard, parse: parseCard }
+};

package/dist/web-sources.d.ts

@@ -2,17 +2,33 @@
  * The web pages an answer drew on, listed apart from the library's numbered
  * sources: the pages the turn's supacrawl calls read, and the Markdown links
  * in the answer itself. A search's results are what it found, not what the
- * answer drew on, so they stay in the search's own row. Never numbered,
- * because nothing here is a passage the persona was handed to cite.
+ * answer drew on, so they stay in the search's own row (`searchPages`). The
+ * page numbers them after the library's, since the persona cites a page by its
+ * link and nothing here is a passage it was handed with a number.
  */
-import type { Block } from './transcript.svelte';
+import type { Block, ToolBlock } from './transcript.svelte';
 export interface WebSource {
     url: string;
     /** The page's title, or its host where nothing gave one. */
     title: string;
     host: string;
+    /** The turn read this page whole (a scrape), rather than only linking it. */
+    read?: true;
+    /** The page's own date, as it gave it, where it gave one. */
+    date?: string;
 }
+/** A page a search found, for its step's expansion. */
+export interface FoundPage {
+    url: string;
+    title: string;
+    host: string;
+    snippet: string;
+}
+/** The key two spellings of one page share. */
+export declare const webKey: (url: string) => string;
 /** A URL's host without a leading `www.`; the text as given where it is no URL. */
 export declare function hostOf(url: string): string;
+/** The pages a successful web search step found. */
+export declare function searchPages(block: ToolBlock): FoundPage[];
 /** The pages, once each, in the order the turn met them. */
 export declare function webSources(blocks: Block[], answer: string): WebSource[];

package/dist/web-sources.js

@@ -2,9 +2,12 @@
  * The web pages an answer drew on, listed apart from the library's numbered
  * sources: the pages the turn's supacrawl calls read, and the Markdown links
  * in the answer itself. A search's results are what it found, not what the
- * answer drew on, so they stay in the search's own row. Never numbered,
- * because nothing here is a passage the persona was handed to cite.
+ * answer drew on, so they stay in the search's own row (`searchPages`). The
+ * page numbers them after the library's, since the persona cites a page by its
+ * link and nothing here is a passage it was handed with a number.
  */
+/** The key two spellings of one page share. */
+export const webKey = (url) => url.replace(/#.*$/, '').replace(/\/$/, '');
 /** A URL's host without a leading `www.`; the text as given where it is no URL. */
 export function hostOf(url) {
     try {
@@ -26,6 +29,24 @@ function parse(text) {
         return undefined;
     }
 }
+/** The pages a successful web search step found. */
+export function searchPages(block) {
+    if (block.name !== 'mcp__supacrawl__supacrawl_search' || block.isError)
+        return [];
+    const found = parse(block.result);
+    if (!Array.isArray(found?.results))
+        return [];
+    const pages = [];
+    for (const item of found.results) {
+        if (typeof item !== 'object' || item === null || !isWeb(item.url))
+            continue;
+        const host = hostOf(item.url);
+        const title = [item.title, host].find((t) => typeof t === 'string' && t.trim());
+        const snippet = [item.snippet, item.description, item.content].find((t) => typeof t === 'string' && t.trim());
+        pages.push({ url: item.url, title: title.trim(), host, snippet: (snippet ?? '').trim() });
+    }
+    return pages;
+}
 function fromTool(block) {
     if (!block.name.startsWith('mcp__supacrawl__') || !block.name.endsWith('_scrape') || block.isError)
         return [];
@@ -34,24 +55,35 @@ function fromTool(block) {
         return [];
     const page = parse(block.result);
     const title = [page?.title, page?.metadata?.title].find((t) => typeof t === 'string');
-    return [{ url: input.url, title: title }];
+    const date = [
+        page?.metadata?.publishedTime,
+        page?.metadata?.published,
+        page?.metadata?.date,
+        page?.metadata?.modifiedTime
+    ].find((d) => typeof d === 'string' && !Number.isNaN(Date.parse(d)));
+    return [{ url: input.url, title: title, date: date }];
 }
 /** The pages, once each, in the order the turn met them. */
 export function webSources(blocks, answer) {
     const seen = new Map();
-    const add = (url, title) => {
-        const key = url.replace(/#.*$/, '').replace(/\/$/, '');
+    const add = (url, title, read) => {
+        const key = webKey(url);
         if (seen.has(key))
             return;
         const host = hostOf(url);
         if (host === url)
             return;
-        seen.set(key, { url, title: title?.trim() || host, host });
+        seen.set(key, {
+            url,
+            title: title?.trim() || host,
+            host,
+            ...(read ? { read: true, date: read.date } : {})
+        });
     };
     for (const block of blocks)
         if (block.kind === 'tool')
             for (const p of fromTool(block))
-                add(p.url, p.title);
+                add(p.url, p.title, { date: p.date });
     for (const match of answer.matchAll(LINK))
         add(match[2], match[1]);
     return [...seen.values()];

package/dist/written.d.ts

@@ -6,7 +6,7 @@
  * each version in the reading column and links it for download; the bytes
  * come from the host's own route, never from this package.
  */
-import type { ChatCopy } from './copy';
+import { type ChatCopy } from './copy';
 import type { Turn } from './transcript.svelte';
 /** One version of one document, as the wire names it. */
 export interface Written {
@@ -20,6 +20,17 @@ export interface Written {
     /** What the app can render it as beyond the source (`docx`, `pdf`); empty
      *  where it has no renderer. */
     formats: string[];
+    /** What a reader calls it: "Minute: increased rent ceiling". */
+    title: string;
+    /** What sort of document it is ("minute"); null where nothing says. */
+    kind: string | null;
+    /** What this version changed since the one before it, in a phrase; null
+     *  for the first, or where nothing says. */
+    changes: string | null;
+    /** How many pages it runs to; 0 where the app cannot tell. */
+    pages: number;
+    /** When this page saw the version arrive, epoch ms. Absent for one read back. */
+    at?: number;
 }
 /** The source of one version, to show it in the pane. */
 export type LoadWritten = (name: string, version: number) => Promise<{
@@ -30,6 +41,20 @@ export type LoadWritten = (name: string, version: number) => Promise<{
 export type WrittenUrl = (name: string, version: number, format: string) => string;
 export declare const writtenKey: (written: Written) => string;
 export declare const isHtml: (mediaType: string) => boolean;
+/** The newest version of each document in `written`, in the order they first appear. */
+export declare function newestPerName(written: Written[]): Written[];
+/** "Minute", or "Document" where the document has no kind. */
+export declare function kindLabel(written: Written, words: ChatCopy): string;
+/** "Minute · 1 page · v1": kind, pages where known, version. */
+export declare function writtenMeta(written: Written, words: ChatCopy): string;
+/** The download a card's chip offers: Word where the app renders it, else the source as written. */
+export declare function chipFor(written: Written, words: ChatCopy): {
+    format: string;
+    file: string;
+    label: string;
+};
+/** A leading `---` front matter block is metadata, not the document. */
+export declare function stripFrontMatter(text: string): string;
 /** Every version of `name` across the conversation, oldest first. */
 export declare function writtenVersions(turns: Turn[], name: string): Written[];
 /** What a version downloads as: its source, then each format the app renders. */

package/dist/written.js

@@ -6,8 +6,50 @@
  * each version in the reading column and links it for download; the bytes
  * come from the host's own route, never from this package.
  */
+import { fill } from './copy';
 export const writtenKey = (written) => `${written.name}@${written.version}`;
 export const isHtml = (mediaType) => mediaType.toLowerCase().startsWith('text/html');
+/** The newest version of each document in `written`, in the order they first appear. */
+export function newestPerName(written) {
+    const newest = new Map();
+    for (const w of written) {
+        const had = newest.get(w.name);
+        if (!had || w.version >= had.version)
+            newest.set(w.name, w);
+    }
+    return [...newest.values()];
+}
+/** "Minute", or "Document" where the document has no kind. */
+export function kindLabel(written, words) {
+    const kind = (written.kind ?? '').trim() || words.documentKind;
+    return kind.charAt(0).toUpperCase() + kind.slice(1);
+}
+/** "Minute · 1 page · v1": kind, pages where known, version. */
+export function writtenMeta(written, words) {
+    const parts = [kindLabel(written, words)];
+    if (written.pages > 0)
+        parts.push(written.pages === 1 ? words.pageCount : fill(words.pagesCount, { n: written.pages }));
+    parts.push(fill(words.writtenVersion, { n: written.version }));
+    return parts.join(' · ');
+}
+const baseName = (name) => name.split('/').filter(Boolean).at(-1) ?? name;
+/** The download a card's chip offers: Word where the app renders it, else the source as written. */
+export function chipFor(written, words) {
+    const file = baseName(written.name);
+    if (written.formats.includes('docx')) {
+        const stem = file.replace(/\.[^.]+$/, '');
+        return { format: 'docx', file: `${stem}.docx`, label: words.formatWord };
+    }
+    return {
+        format: 'source',
+        file,
+        label: isHtml(written.media_type) ? words.formatHtml : words.formatMarkdown
+    };
+}
+/** A leading `---` front matter block is metadata, not the document. */
+export function stripFrontMatter(text) {
+    return text.replace(/^\uFEFF?---[ \t]*\r?\n[\s\S]*?\r?\n---[ \t]*(?:\r?\n|$)/, '').replace(/^\s*\n/, '');
+}
 /** Every version of `name` across the conversation, oldest first. */
 export function writtenVersions(turns, name) {
     const found = new Map();

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@poodle64/librarian",
-	"version": "2026.10.4",
+	"version": "2026.10.5",
 	"description": "An agent's conversation surface as a consumable Svelte 5 package: the stream client, transcript state and self-styling chat components (transcript, composer, markdown) every household app renders instead of rebuilding, speaking as whichever persona the app names.",
 	"type": "module",
 	"license": "MIT",
@@ -47,6 +47,10 @@
 			"types": "./dist/written.d.ts",
 			"svelte": "./dist/written.js"
 		},
+		"./visuals": {
+			"types": "./dist/visuals.d.ts",
+			"svelte": "./dist/visuals.js"
+		},
 		"./attachments": {
 			"types": "./dist/attachments.d.ts",
 			"svelte": "./dist/attachments.js"
@@ -68,6 +72,11 @@
 		"isomorphic-dompurify": "^3.23.0",
 		"shiki": "^4.4.3"
 	},
+	"dependencies": {
+		"vega": "6.4.0",
+		"vega-embed": "7.3.0",
+		"vega-lite": "6.4.3"
+	},
 	"devDependencies": {
 		"@lucide/svelte": "^1.7.0",
 		"@poodle64/design-tokens": "workspace:*",

package/dist/components/web-list/index.d.ts

@@ -1,2 +0,0 @@
-export { default as WebList } from './web-list.svelte';
-export { default } from './web-list.svelte';

package/dist/components/web-list/index.js

@@ -1,2 +0,0 @@
-export { default as WebList } from './web-list.svelte';
-export { default } from './web-list.svelte';