@poodle64/librarian 2026.9.22 → 2026.9.24

package/README.md

@@ -179,6 +179,8 @@ on it fires once and never again.
 | 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                                                           |
+| An answer its own way    | `turn`: a snippet given each turn's `AgentTranscriptProps` in place of `AgentTranscript`. Render your own from the parts, or `AgentTranscript` inside your own to add to it               |
+| What leads a conversation | `lead`: a snippet inside the scroll, under the opening and the scope, so a tall one scrolls with the conversation instead of taking its height                                            |
 
 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
@@ -243,6 +245,13 @@ the room's routes, and the components bound to it:
 
 `chat.list()` reads the list once; after that it follows every answer.
 
+A turn the host asks as a `kind` (`chat.ask(question, 'briefing')`, from
+`Composer`'s `onbriefing`) goes to the route as `client.ask()`'s `kind`, comes
+back on `StoredTurn.kind`, and carries whatever `new Chat(transport, {
+artefact })` says that kind opens, on a live turn and a reopened one alike:
+`{ title: 'Briefing', isAnswer: true }` cards it and opens its prose in the
+column. `again()` asks it as the same kind.
+
 The transport is the app's own client over its routes, and the shapes are
 the routes' own bodies (`ConversationSummary`, `ConversationRead`,
 `StoredTurn`, `Quota`), so the stamped slice returns them as they are and
@@ -568,6 +577,6 @@ Where Playwright's own Chromium will not start (NixOS), name one that does:
 1. Change a component; bump `version` in `package.json` (CalVer).
 2. `pnpm build`, which runs `svelte-package` then `publint`.
 3. Commit, tag `librarian-v<version>`, push the tag.
-4. `.github/workflows/publish.yaml` runs on that push and publishes through
-   npm's trusted publisher. Watch it: `gh run list --workflow=publish.yaml`,
+4. `.github/workflows/publish-kit-typescript.yaml` (repo root) runs on that push and publishes through
+   npm's trusted publisher. Watch it: `gh run list -R radar-hooves/app-factory --workflow=publish-kit-typescript.yaml`,
    then `npm view @poodle64/librarian version`.

package/dist/chat.svelte.d.ts

@@ -21,7 +21,7 @@
  */
 import { type AgentEvent } from './client';
 import type { Citation } from './citations';
-import { type Turn } from './transcript.svelte';
+import { type Artefact, type Turn } from './transcript.svelte';
 /** One conversation in the list. */
 export interface ConversationSummary {
     /** The agent's own session id: what resumes it, what names it in the address. */
@@ -41,6 +41,8 @@ export interface StoredTurn {
     /** ISO 8601, when it was asked. */
     at?: string | null;
     citations?: Citation[];
+    /** What the host asked for, when it was not a plain question. */
+    kind?: string | null;
 }
 /** A conversation reopened. */
 export interface ConversationRead extends ConversationSummary {
@@ -69,6 +71,8 @@ export interface AskRequest {
     /** The conversation this carries on; null starts one. */
     resume: string | null;
     signal: AbortSignal;
+    /** What the host asked for, when it is not a plain question: `client.ask()`'s `kind`. */
+    kind?: string;
 }
 /**
  * A room's routes, as the host's own client reaches them. Every method but
@@ -119,6 +123,10 @@ export interface ChatOptions {
     pollMs?: number;
     /** How often a closed job is asked whether it carries on. */
     rewatchMs?: number;
+    /** What a turn asked as `kind` produces for the reader to open, in the
+     *  host's words (a briefing: `{ title, isAnswer: true }`), on a turn asked
+     *  here and on one read back alike. None for a plain question. */
+    artefact?: (kind: string) => Artefact | undefined;
 }
 export declare class Chat {
     #private;
@@ -162,11 +170,12 @@ export declare class Chat {
      *  from an effect, as `open` is. */
     new(): void;
     /**
-     * Ask `question`, or what is in the box. Resolves once the turn settles:
-     * true if it was asked, false if it was refused, here or by the server, in
-     * which case typed words go back into the box.
+     * Ask `question`, or what is in the box, as a `kind` of turn when it is not
+     * a plain question. Resolves once the turn settles: true if it was asked,
+     * false if it was refused, here or by the server, in which case typed words
+     * go back into the box.
      */
-    ask(question?: string): Promise<boolean>;
+    ask(question?: string, kind?: string): Promise<boolean>;
     /** The last question again, as a new turn: the conversation is append-only,
      *  because the agent's transcript is. */
     again(): Promise<boolean>;

package/dist/chat.svelte.js

@@ -48,6 +48,7 @@ export class Chat {
     #job = null;
     #pollMs;
     #rewatchMs;
+    #artefact;
     #turns = $state([]);
     #version = $state(0);
     #running = $state(false);
@@ -71,6 +72,7 @@ export class Chat {
             this.#room = transport;
         this.#pollMs = options.pollMs ?? 5000;
         this.#rewatchMs = options.rewatchMs ?? 2000;
+        this.#artefact = options.artefact;
     }
     /** Every turn, in order. A live one grows in place; key on `version`. */
     get turns() {
@@ -142,11 +144,12 @@ export class Chat {
         });
     }
     /**
-     * Ask `question`, or what is in the box. Resolves once the turn settles:
-     * true if it was asked, false if it was refused, here or by the server, in
-     * which case typed words go back into the box.
+     * Ask `question`, or what is in the box, as a `kind` of turn when it is not
+     * a plain question. Resolves once the turn settles: true if it was asked,
+     * false if it was refused, here or by the server, in which case typed words
+     * go back into the box.
      */
-    async ask(question) {
+    async ask(question, kind) {
         const typed = question === undefined;
         const text = (question ?? this.draft).trim();
         if (!text)
@@ -160,13 +163,13 @@ export class Chat {
             this.draft = '';
             this.files = [];
         }
-        return this.#ask(text, files, typed);
+        return this.#ask(text, files, typed, kind);
     }
     /** The last question again, as a new turn: the conversation is append-only,
      *  because the agent's transcript is. */
     again() {
-        const last = this.turns.at(-1)?.question;
-        return last ? this.ask(last) : Promise.resolve(false);
+        const last = this.turns.at(-1);
+        return last?.question ? this.ask(last.question, last.kind) : Promise.resolve(false);
     }
     /** Stop the answer being written, wherever it is being written. */
     async stop() {
@@ -298,7 +301,7 @@ export class Chat {
         this.answering = null;
         this.waiting = false;
     }
-    async #ask(text, files, typed) {
+    async #ask(text, files, typed, kind) {
         const room = this.#room;
         const mine = this.#generation;
         const stream = { controller: new AbortController(), stopWanted: false };
@@ -310,7 +313,9 @@ export class Chat {
             blocks: [],
             outcome: null,
             citations: [],
-            suggestions: []
+            suggestions: [],
+            kind,
+            artefact: this.#card(kind)
         });
         const live = this.#turns[this.#turns.length - 1];
         const state = foldState();
@@ -323,7 +328,8 @@ export class Chat {
             question: text,
             files,
             resume: this.conversationId,
-            signal: stream.controller.signal
+            signal: stream.controller.signal,
+            kind
         })) {
             const named = event.type === 'system' && event.subtype === 'init' ? event.session_id : undefined;
             if (stream.stopWanted) {
@@ -400,6 +406,10 @@ export class Chat {
         this.#finish();
         return true;
     }
+    /** What a turn of `kind` opens, if the host says it opens anything. */
+    #card(kind) {
+        return kind ? this.#artefact?.(kind) : undefined;
+    }
     /** A turn this page streamed has settled, one way or another. */
     #finish() {
         this.#stream = null;
@@ -415,7 +425,10 @@ export class Chat {
      *  read again until it settles. */
     #show(read, mine) {
         clearTimeout(this.#poll);
-        const turns = read.turns.map((stored, index) => storedTurn(read.id, index, stored));
+        const turns = read.turns.map((stored, index) => ({
+            ...storedTurn(read.id, index, stored),
+            artefact: this.#card(stored.kind)
+        }));
         this.#held = new Set(turns.map((t) => t.id));
         const since = epoch(read.answering_since);
         if (since !== null) {
@@ -537,7 +550,8 @@ function storedTurn(conversation, index, stored) {
         at: epoch(stored.at) ?? undefined,
         blocks: stored.answer ? [{ kind: 'text', index: 0, text: stored.answer }] : [],
         outcome: null,
-        citations: stored.citations ?? []
+        citations: stored.citations ?? [],
+        kind: stored.kind ?? undefined
     };
 }
 function epoch(value) {

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

@@ -41,7 +41,9 @@
 	import Markdown from '../markdown/markdown.svelte';
 	import SourceList from '../source-list/source-list.svelte';
 
-	interface Props {
+	/** Everything one turn renders from: what `Conversation` hands a host's
+	 *  own `turn` snippet, so it can render this component or its own. */
+	export interface AgentTranscriptProps {
 		question: string;
 		blocks: Block[];
 		outcome: Outcome | null;
@@ -109,7 +111,7 @@
 		waiting = false,
 		answering,
 		onmark
-	}: Props = $props();
+	}: AgentTranscriptProps = $props();
 
 	// The prose IS the artefact: it reads in the column, and the transcript
 	// shows the card alone.
@@ -393,7 +395,7 @@
 
 	.ds-lib-ask {
 		display: flex;
-		max-width: 100%;
+		width: 100%;
 		flex-direction: column;
 		align-items: flex-end;
 		gap: 0.25rem;

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

@@ -2,7 +2,9 @@ import { type Artefact, type Block, type DescribeTool, type Outcome } from '../.
 import { type Citation } from '../../citations';
 import { type LibrarianCopy } from '../../copy';
 import type { Verdict } from '../../chat.svelte';
-interface Props {
+/** Everything one turn renders from: what `Conversation` hands a host's
+ *  own `turn` snippet, so it can render this component or its own. */
+export interface AgentTranscriptProps {
     question: string;
     blocks: Block[];
     outcome: Outcome | null;
@@ -48,6 +50,6 @@ interface Props {
      *  control that records nothing is worse than none. */
     onmark?: (verdict: Verdict) => Promise<boolean>;
 }
-declare const AgentTranscript: import("svelte").Component<Props, {}, "">;
+declare const AgentTranscript: import("svelte").Component<AgentTranscriptProps, {}, "">;
 type AgentTranscript = ReturnType<typeof AgentTranscript>;
 export default AgentTranscript;

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

@@ -1,2 +1,2 @@
-export { default as AgentTranscript } from './agent-transcript.svelte';
+export { default as AgentTranscript, type AgentTranscriptProps } from './agent-transcript.svelte';
 export { default } from './agent-transcript.svelte';

package/dist/components/conversation/conversation.svelte

@@ -16,7 +16,9 @@
 	import type { Citation, LoadDocument } from '../../citations';
 	import { DEFAULT_PERSONA, personaName, resolveCopy, type LibrarianCopy } from '../../copy';
 	import { FollowScroll } from '../../follow-scroll.svelte';
-	import AgentTranscript from '../agent-transcript/agent-transcript.svelte';
+	import AgentTranscript, {
+		type AgentTranscriptProps
+	} 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';
@@ -81,6 +83,15 @@
 		 *  pane narrows it too — a composer the host places outside slides
 		 *  under the pane the moment one opens. */
 		composer?: Snippet;
+		/** Renders each turn in place of `AgentTranscript`, given the props it
+		 *  would have taken: a host that presents an answer its own way (its
+		 *  prose, its citation marks, its links) renders its own, and one that
+		 *  only adds to it renders `AgentTranscript` inside it. */
+		turn?: Snippet<[AgentTranscriptProps]>;
+		/** Before the first turn, inside the scroll and under the opening and
+		 *  the scope: what the host shows ahead of a question, which scrolls
+		 *  with the conversation rather than taking its height. */
+		lead?: Snippet;
 	}
 
 	let {
@@ -104,7 +115,9 @@
 		showing,
 		describeTool,
 		collectionNames = new Set(),
-		composer
+		composer,
+		turn: presentTurn,
+		lead
 	}: Props = $props();
 
 	// Resolved ONCE, here, and handed down whole: every child takes `copy` and
@@ -267,32 +280,38 @@
 						<ScopeStatement statement={scope} expanded={turns.length === 0} copy={words} />
 					{/if}
 
+					{@render lead?.()}
+
 					{#each turns as turn, index (turn.id)}
 						{@const last = index === turns.length - 1}
-						<AgentTranscript
-							question={turn.question}
-							blocks={turn.blocks}
-							outcome={turn.outcome}
-							running={running && last}
-							waiting={waiting && last}
-							answering={last ? (answering ?? undefined) : undefined}
-							citations={turn.citations ?? []}
-							suggestions={turn.suggestions ?? []}
-							{collectionNames}
-							copy={words}
-							name={who}
-							at={turn.at ?? stamps[turn.id]}
-							artefact={turn.artefact}
-							artefactOpen={isShowing(turn)}
-							onopenartefact={opener(turn)}
-							{describeTool}
-							oncite={oncite || loadDocument ? cite : undefined}
-							onregenerate={last && !running ? onregenerate : undefined}
-							onsuggest={last && !running ? onsuggest : undefined}
-							onmark={last && !running && onmark
-								? (verdict) => onmark(turn, verdict)
-								: undefined}
-						/>
+						{@const props = {
+							question: turn.question,
+							blocks: turn.blocks,
+							outcome: turn.outcome,
+							running: running && last,
+							waiting: waiting && last,
+							answering: last ? (answering ?? undefined) : undefined,
+							citations: turn.citations ?? [],
+							suggestions: turn.suggestions ?? [],
+							collectionNames,
+							copy: words,
+							name: who,
+							at: turn.at ?? stamps[turn.id],
+							artefact: turn.artefact,
+							artefactOpen: isShowing(turn),
+							onopenartefact: opener(turn),
+							describeTool,
+							oncite: oncite || loadDocument ? cite : undefined,
+							onregenerate: last && !running ? onregenerate : undefined,
+							onsuggest: last && !running ? onsuggest : undefined,
+							onmark:
+								last && !running && onmark ? (verdict: Verdict) => onmark(turn, verdict) : undefined
+						} satisfies AgentTranscriptProps}
+						{#if presentTurn}
+							{@render presentTurn(props)}
+						{:else}
+							<AgentTranscript {...props} />
+						{/if}
 					{/each}
 				</div>
 			</div>

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

@@ -3,6 +3,7 @@ import type { DescribeTool, Turn } from '../../transcript.svelte';
 import type { Verdict } from '../../chat.svelte';
 import type { Citation, LoadDocument } from '../../citations';
 import { type LibrarianCopy } from '../../copy';
+import { type AgentTranscriptProps } from '../agent-transcript/agent-transcript.svelte';
 interface Props {
     turns: Turn[];
     running: boolean;
@@ -58,6 +59,15 @@ interface Props {
      *  pane narrows it too — a composer the host places outside slides
      *  under the pane the moment one opens. */
     composer?: Snippet;
+    /** Renders each turn in place of `AgentTranscript`, given the props it
+     *  would have taken: a host that presents an answer its own way (its
+     *  prose, its citation marks, its links) renders its own, and one that
+     *  only adds to it renders `AgentTranscript` inside it. */
+    turn?: Snippet<[AgentTranscriptProps]>;
+    /** Before the first turn, inside the scroll and under the opening and
+     *  the scope: what the host shows ahead of a question, which scrolls
+     *  with the conversation rather than taking its height. */
+    lead?: Snippet;
 }
 declare const Conversation: import("svelte").Component<Props, {}, "">;
 type Conversation = ReturnType<typeof Conversation>;

package/dist/transcript.svelte.d.ts

@@ -205,6 +205,9 @@ export interface Turn {
     /** Something this turn produced for the reader to open, carded under the
      *  answer once the turn settles. */
     artefact?: Artefact;
+    /** What the host asked for when this was not a plain question
+     *  (`'briefing'`), in its own word, as `client.ask()` sent it. */
+    kind?: string;
 }
 /** A turn's artefact, in the host's own words. */
 export interface Artefact {

package/package.json

@@ -1,17 +1,18 @@
 {
 	"name": "@poodle64/librarian",
-	"version": "2026.9.22",
+	"version": "2026.9.24",
 	"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",
 	"repository": {
 		"type": "git",
-		"url": "git+https://github.com/radar-hooves/design-system.git"
+		"url": "git+https://github.com/radar-hooves/app-factory.git",
+		"directory": "kits/typescript/packages/librarian"
 	},
 	"publishConfig": {
 		"registry": "https://registry.npmjs.org",
 		"access": "public",
-		"provenance": false
+		"provenance": true
 	},
 	"files": [
 		"dist"