@tiagojct/subsub 0.20.0 → 0.22.0

package/src/chrome.ts

@@ -0,0 +1,208 @@
+/**
+ * The parts of the terminal screens, as pure functions: (width, paint, glyphs) => lines. They know nothing about pi; the
+ * extension hands them the state and the paint. Every line fits the width, so a snapshot at 40, 80 and 120 columns is a test.
+ */
+
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { libraryLine, LIBRARY_WORDS, type LibraryState, type Paint, plain } from "./look.ts";
+import { type Glyphs, UNICODE } from "./skin.ts";
+
+type Lang = "en" | "pt";
+
+export const CHROME_WORDS = {
+	en: { researcher: "Researcher", librarian: "Librarian", of: "of", tokens: "tokens", unknownUsage: "?", failed: "could not", evidence: "evidence", down: "not running", more: "more lines" },
+	pt: { researcher: "Researcher", librarian: "Librarian", of: "de", tokens: "tokens", unknownUsage: "?", failed: "não foi possível", evidence: "evidência", down: "parados", more: "linhas a mais" },
+};
+
+const len = (s: string) => [...s].length;
+
+/** Cut to the width, with "..." when something is left out. Run it before the text is painted. */
+export function cut(s: string, width: number): string {
+	return len(s) > width ? `${[...s].slice(0, Math.max(0, width - 3)).join("")}...` : s;
+}
+
+/**
+ * Pad lines with spaces to the width, and with empty lines to the height. A screen drawn over the conversation (an overlay) must cover every cell
+ * it has, or the text under it shows through at the end of short lines and below the last one.
+ */
+export function fill(lines: string[], width: number, height = 0): string[] {
+	const out = lines.map((l) => l + " ".repeat(Math.max(0, width - visibleWidth(l))));
+	while (out.length < height) out.push(" ".repeat(width));
+	return height ? out.slice(0, height) : out;
+}
+
+/** A line of one glyph. */
+export function rule(width: number, kind: "solid" | "dashed" | "dotted", paint: (s: string) => string = (s) => s, g: Glyphs = UNICODE): string {
+	return paint(g[kind].repeat(Math.max(0, width)));
+}
+
+/** A context meter: `▰▰▱▱▱ 38%`. null (unknown) is drawn as an empty bar and `?`. */
+export function meter(percent: number | null | undefined, cells: number, g: Glyphs = UNICODE): { bar: string; label: string } {
+	if (percent === null || percent === undefined || Number.isNaN(percent)) return { bar: g.cellEmpty.repeat(cells), label: "?" };
+	const p = Math.min(100, Math.max(0, percent));
+	const full = Math.round((p / 100) * cells);
+	return { bar: g.cell.repeat(full) + g.cellEmpty.repeat(cells - full), label: `${Math.round(p)}%` };
+}
+
+export function compactNumber(n: number): string {
+	if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1).replace(/\.0$/, "")}M`;
+	if (n >= 1000) return `${(n / 1000).toFixed(1).replace(/\.0$/, "")}k`;
+	return String(n);
+}
+
+export interface FooterState {
+	mode: "researcher" | "librarian";
+	lang: Lang;
+	library: LibraryState;
+	model: string;
+	/** Share of the context window in use, 0 to 100; null when pi does not know it yet. */
+	percent?: number | null;
+	/** The size of the context window, in tokens. */
+	window?: number;
+	tokens?: number | null;
+	cost?: number | null;
+	/** Servers that did not start ("zotero", "scholar"). */
+	down?: string[];
+}
+
+/**
+ * The footer, in four tiers: 100 columns and more show everything on two lines; 60 to 99 leave out tokens and cost; 40 to 59 are one line with the
+ * mode, the item count and the meter; below 40 only the mode and the percentage.
+ */
+export function footerLines(st: FooterState, width: number, p: Paint = plain, g: Glyphs = UNICODE): string[] {
+	const w = Math.max(10, width);
+	const words = CHROME_WORDS[st.lang];
+	const lib = LIBRARY_WORDS[st.lang];
+	const mode = st.mode === "librarian" ? words.librarian : words.researcher;
+	const m = meter(st.percent, w >= 100 ? 10 : 5, g);
+	if (w < 40) return [p.mark(mode) + p.muted(cut(` ${m.label}`, Math.max(0, w - len(mode))))];
+	const count = st.library.zotero === "reachable" ? `${st.library.items ?? "?"} ${lib.items}` : st.library.zotero === "down" ? `${g.hollow} ${lib.prefix}` : `${lib.prefix}...`;
+	if (w < 60) {
+		const tail = ` | ${count} | ${m.bar} ${m.label}`;
+		return [p.mark(mode) + p.muted(cut(tail, Math.max(0, w - len(mode))))];
+	}
+	const first = libraryLine(st.library, st.lang, g).text + (st.down?.length ? ` | ${words.down}: ${st.down.join(", ")}` : "");
+	const lines = [p.mark(mode) + p.muted(cut(` | ${first}`, Math.max(0, w - len(mode))))];
+	const window = st.window ? ` ${words.of} ${compactNumber(st.window)}` : "";
+	let second = `${cut(st.model, Math.max(8, Math.floor(w / 3)))}   ${m.bar} ${m.label}${m.label === "?" ? "" : window}`;
+	if (w >= 100) {
+		const tokens = st.tokens === null || st.tokens === undefined ? words.unknownUsage : compactNumber(st.tokens);
+		const cost = st.cost === null || st.cost === undefined ? "" : `   $${st.cost.toFixed(st.cost < 1 ? 3 : 2)}`;
+		second += `   ${tokens} ${words.tokens}${cost}`;
+	}
+	lines.push(p.dim(cut(second, w)));
+	return lines;
+}
+
+export type ToolState = "pending" | "done" | "failed";
+
+/**
+ * One line for a tool call, in plain words: `┄ search the library: asthma` while it runs (dashed), `─ search the library: asthma` when it is done
+ * (solid), `○ could not search the library: first line of the error` when it failed (a hollow mark and a word, in ink).
+ */
+export function toolLine(opts: { state: ToolState; word: string; detail?: string; error?: string; lang: Lang; width: number }, p: Paint = plain, g: Glyphs = UNICODE): string {
+	const w = Math.max(10, opts.width);
+	const words = CHROME_WORDS[opts.lang];
+	if (opts.state === "failed") {
+		const why = opts.error ? `: ${opts.error.split("\n")[0]}` : "";
+		return p.text(cut(`${g.hollow} ${words.failed} ${opts.word}${why}`, w));
+	}
+	const mark = opts.state === "pending" ? p.pend(g.dashed) : p.ok(g.solid);
+	const rest = ` ${opts.word}${opts.detail ? `: ${opts.detail}` : ""}`;
+	return mark + p.muted(cut(rest, w - 1));
+}
+
+/** A short detail for a tool call: the first useful argument (a query, a title, a key, a path), cut to the length. */
+export function toolDetail(args: unknown, max = 40): string {
+	if (!args || typeof args !== "object") return "";
+	const a = args as Record<string, unknown>;
+	for (const k of ["query", "q", "title", "citekey", "key", "keys", "doi", "identifier", "path", "name", "text"]) {
+		const v = a[k];
+		if (v === undefined || v === null || v === "") continue;
+		const s = Array.isArray(v) ? v.filter((x) => typeof x !== "object").join(", ") : String(v);
+		if (s) return cut(s.replace(/\s+/g, " "), max);
+	}
+	return "";
+}
+
+export type EvidenceKind = "full" | "abstract" | "metadata" | "other";
+
+/** What a note was written from, from its `evidence:` field: full text is solid sap, an abstract dashed gamboge, metadata dotted muted. */
+export function evidenceKind(evidence: string): EvidenceKind {
+	return /full/i.test(evidence) ? "full" : /abstract/i.test(evidence) ? "abstract" : /metadata|metadados/i.test(evidence) ? "metadata" : "other";
+}
+
+export function evidenceLine(evidence: string, lang: Lang, width: number, p: Paint = plain, g: Glyphs = UNICODE): string {
+	const kind = evidenceKind(evidence);
+	const label = `${CHROME_WORDS[lang].evidence}: ${evidence}`;
+	const lead = kind === "full" ? p.ok(g.solid.repeat(2)) : kind === "abstract" ? p.pend(g.dashed.repeat(2)) : p.muted(g.dotted.repeat(2));
+	return `${lead}${p.text(cut(` ${label}`, Math.max(0, width - 2)))}`;
+}
+
+/** Tokens and cost of the conversation, from the assistant messages of the session. null when a message has no usage (the provider did not report it). */
+export function usageTotals(entries: unknown[]): { tokens: number | null; cost: number | null } {
+	let tokens = 0;
+	let cost = 0;
+	for (const e of entries as Array<{ type?: string; message?: { role?: string; usage?: { totalTokens?: number; input?: number; output?: number; cacheRead?: number; cacheWrite?: number; cost?: { total?: number } } } }>) {
+		if (e.type !== "message" || e.message?.role !== "assistant") continue;
+		const u = e.message.usage;
+		if (!u) return { tokens: null, cost: null };
+		tokens += u.totalTokens ?? (u.input ?? 0) + (u.output ?? 0) + (u.cacheRead ?? 0) + (u.cacheWrite ?? 0);
+		cost += u.cost?.total ?? 0;
+	}
+	return { tokens, cost };
+}
+
+/** The shape of the pi theme and tool render context that the tool renderers use. */
+interface RenderContext {
+	args?: unknown;
+	isPartial?: boolean;
+	isError?: boolean;
+	expanded?: boolean;
+	state?: Record<string, unknown>;
+}
+
+const EXPANDED_LINES = 60;
+
+/**
+ * Tool renderers for the tools of Sub-Sub's servers: one line in plain words (see toolLine) and no box. The call line follows the state of the
+ * call; the result shows nothing unless it failed (the first line of the error goes on the call line) or the row is expanded (the output, indented).
+ */
+export function toolRenderers(opts: { word: (toolName: string) => string; lang: Lang; glyphs: () => Glyphs; paint: (theme: any) => Paint }) {
+	const text = (result: { content?: Array<{ type?: string; text?: string }> }): string => (result.content ?? []).filter((c) => c.type === "text").map((c) => c.text ?? "").join("\n");
+	return (toolName: string) => ({
+		renderShell: "self" as const,
+		renderCall: (args: unknown, theme: unknown, context: RenderContext) => ({
+			render: (width: number): string[] => [
+				toolLine(
+					{
+						state: context.isError ? "failed" : context.isPartial === false ? "done" : "pending",
+						word: opts.word(toolName),
+						detail: toolDetail(context.args ?? args),
+						error: typeof context.state?.error === "string" ? context.state.error : undefined,
+						lang: opts.lang,
+						width,
+					},
+					opts.paint(theme),
+					opts.glyphs(),
+				),
+			],
+			invalidate() {},
+		}),
+		renderResult: (result: { content?: Array<{ type?: string; text?: string }> }, options: { expanded?: boolean }, theme: unknown, context: RenderContext) => {
+			const out = text(result);
+			if (context.state) context.state.error = context.isError ? out.trim().split("\n")[0] : undefined;
+			return {
+				render: (width: number): string[] => {
+					if (!options.expanded || !out.trim()) return [];
+					const p = opts.paint(theme);
+					const lines = out.split("\n");
+					const shown = lines.slice(0, EXPANDED_LINES).map((l) => p.muted(cut(`  ${l}`, width)));
+					if (lines.length > EXPANDED_LINES) shown.push(p.dim(`  ... ${lines.length - EXPANDED_LINES} ${CHROME_WORDS[opts.lang].more}`));
+					return shown;
+				},
+				invalidate() {},
+			};
+		},
+	});
+}

package/src/cli.ts

@@ -14,6 +14,7 @@
  * - `subsub init` sets Sub-Sub up; `subsub doctor` checks the setup.
  * - `subsub web` (or `subsub serve`) opens Sub-Sub in the browser;
  *   `subsub shortcut` adds a Sub-Sub shortcut that does the same.
+ * - `subsub tui` is Sub-Sub on the whole terminal: a full-screen client of pi's RPC mode, like the web view.
  */
 
 import { spawnSync } from "node:child_process";
@@ -99,6 +100,8 @@ function isEmptyAuth(file: string): boolean {
 export function shareAuth(agentDir: string, piAgentDir: string): boolean {
 	const mine = join(agentDir, "auth.json");
 	const theirs = join(piAgentDir, "auth.json");
+	// The web view and `subsub tui` start pi with PI_CODING_AGENT_DIR set to Sub-Sub's folder: a link to itself would make auth.json unreadable.
+	if (real(mine) === real(theirs)) return false;
 	if (!existsSync(theirs)) return false;
 	try {
 		const st = lstatSync(mine);
@@ -140,6 +143,7 @@ Usage:
   subsub                 Start Sub-Sub in the terminal
   subsub --librarian     Start in the Librarian, which only manages the library
   subsub web             Open Sub-Sub in the browser
+  subsub tui             Sub-Sub on the whole terminal: transcript, side panel, footer (--light or --dark for the colours)
   subsub init            Set up or change the settings (folder, tag list, models)
   subsub doctor          Check the set-up; each line marked FIX says what to do
   subsub usage           The pilot's usage log (if turned on): a summary and where the file is
@@ -182,6 +186,11 @@ export async function run(argv: string[] = process.argv.slice(2)): Promise<void>
 		process.exitCode = await webMain([...args.slice(1), ...(here ? ["--here"] : [])], env);
 		return;
 	}
+	if (args[0] === "tui") {
+		const { runTui } = await import("./tui.ts");
+		// The terminal is given back before this returns; exit so that nothing else keeps the process alive.
+		process.exit(await runTui([...args.slice(1), ...(here ? ["--here"] : [])], env));
+	}
 	if (args[0] === "shortcut") {
 		const { shortcutMain } = await import("./shortcut.ts");
 		process.exitCode = shortcutMain(args.slice(1), env);

package/src/config.ts

@@ -99,6 +99,8 @@ export interface SubsubConfig {
 	quotes?: boolean;
 	/** Theme, without -dark/-light; false keeps your pi theme. */
 	themes?: string | false;
+	/** Theme (without -dark/-light) for the Librarian; the default is subsub-try-works. */
+	themesLibrarian?: string;
 	/** Optional servers to start, e.g. ["starbuck"]. */
 	addons?: string[];
 	/** Local Starbuck folder (used when it has a pyproject.toml). */
@@ -183,6 +185,7 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): SubsubConfig {
 	const models: Partial<Record<Mode, string>> = given ?? (one !== undefined ? { librarian: one || undefined, researcher: one || undefined } : fallback);
 	for (const k of Object.keys(models) as Mode[]) if (!models[k]) delete models[k];
 	const themes = user.themes === false ? false : typeof user.themes === "string" ? user.themes : user.themes?.researcher;
+	const themesLibrarian = user.themes && typeof user.themes === "object" ? user.themes.librarian : undefined;
 	return {
 		configFile: file,
 		userName: typeof user.userName === "string" && user.userName.trim() ? user.userName.trim() : undefined,
@@ -209,6 +212,7 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): SubsubConfig {
 		look: user.look,
 		quotes: user.quotes,
 		themes,
+		themesLibrarian,
 		addons: Array.isArray(user.addons) ? user.addons.filter((a): a is string => typeof a === "string") : [],
 		starbuckDir: expand(user.starbuckDir ?? "~/Projects/starbuck", home),
 		usageLog: user.usageLog === true,

package/src/dialogs.ts

@@ -0,0 +1,107 @@
+/**
+ * The approval dialog of the terminal look: a preview between two dashed rules (dashed means "not done yet"), and keys that answer it.
+ * It replaces pi's confirm dialog when the look is on. Nothing is applied unless the answer is the yes key: Enter does nothing, Esc, n and
+ * Ctrl+C say no, and keys pressed in the first half second are ignored, so a letter typed just before the dialog opened cannot answer it.
+ */
+
+import { matchesKey, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { cut, fill, rule } from "./chrome.ts";
+import type { Paint } from "./look.ts";
+import { type Glyphs, UNICODE } from "./skin.ts";
+
+type Lang = "en" | "pt";
+
+export const APPROVAL_WORDS = {
+	en: { yes: "y apply", no: "n leave it as it is", esc: "Esc leave it", scroll: "up and down: scroll", above: "more lines above", below: "more lines below" },
+	pt: { yes: "s aplicar", no: "n deixar como está", esc: "Esc deixar", scroll: "cima e baixo: deslocar", above: "linhas acima", below: "linhas abaixo" },
+};
+
+/** The same keys as the web view: y, and s in Portuguese. */
+export const YES_KEYS: Record<Lang, string[]> = { en: ["y"], pt: ["s", "y"] };
+
+export interface ApprovalLines {
+	lines: string[];
+	/** Lines of the preview in all. */
+	total: number;
+	/** The largest scroll offset. */
+	maxScroll: number;
+}
+
+/** The dialog as lines: rule, title, preview (scrolled), rule, keys. Every line fits the width. */
+export function approvalLines(o: { title: string; body: string; lang: Lang; width: number; paint: Paint; glyphs?: Glyphs; scroll?: number; bodyRows?: number }): ApprovalLines {
+	const g = o.glyphs ?? UNICODE;
+	const w = Math.max(20, o.width);
+	const words = APPROVAL_WORDS[o.lang];
+	const all = wrapTextWithAnsi(o.body, w - 2);
+	const rows = Math.max(3, o.bodyRows ?? 14);
+	const maxScroll = Math.max(0, all.length - rows);
+	const scroll = Math.min(Math.max(0, o.scroll ?? 0), maxScroll);
+	const shown = all.slice(scroll, scroll + rows).map((l) => `  ${l}`);
+	const below = all.length - scroll - shown.length;
+	const lines = [rule(w, "dashed", o.paint.pend, g), o.paint.text(cut(` ${o.title}`, w)), ""];
+	if (scroll > 0) lines.push(o.paint.dim(cut(`  ... ${scroll} ${words.above}`, w)));
+	lines.push(...shown);
+	if (below > 0) lines.push(o.paint.dim(cut(`  ... ${below} ${words.below} (${words.scroll})`, w)));
+	lines.push("", rule(w, "dashed", o.paint.pend, g));
+	lines.push(...wrapTextWithAnsi(` ${words.yes}   ${words.no}   ${words.esc}`, w).map((l) => o.paint.muted(l)));
+	return { lines, total: all.length, maxScroll };
+}
+
+export interface ApprovalOptions {
+	title: string;
+	body: string;
+	lang: Lang;
+	paint: Paint;
+	glyphs?: Glyphs;
+	done: (yes: boolean) => void;
+	/** Rows of the terminal, for the height of the preview. */
+	rows?: () => number;
+	/** Called after a key changed what the dialog shows. */
+	redraw?: () => void;
+	/** Milliseconds during which keys are ignored. */
+	ignoreMs?: number;
+	now?: () => number;
+}
+
+/** The pi-tui component of the dialog (see ExtensionUIContext.custom). */
+export class ApprovalView {
+	private scroll = 0;
+	private answered = false;
+	private readonly o: ApprovalOptions;
+	private readonly opened: number;
+	constructor(o: ApprovalOptions) {
+		this.o = o;
+		this.opened = (o.now ?? Date.now)();
+	}
+
+	private bodyRows(): number {
+		return Math.max(3, Math.floor(((this.o.rows?.() ?? 24) * 9) / 10) - 8);
+	}
+
+	render(width: number): string[] {
+		const view = approvalLines({ ...this.o, width, scroll: this.scroll, bodyRows: this.bodyRows() });
+		this.scroll = Math.min(this.scroll, view.maxScroll);
+		return fill(view.lines, width);
+	}
+
+	invalidate(): void {}
+
+	private answer(yes: boolean): void {
+		if (this.answered) return;
+		this.answered = true;
+		this.o.done(yes);
+	}
+
+	handleInput(data: string): void {
+		if ((this.o.now ?? Date.now)() - this.opened < (this.o.ignoreMs ?? 500)) return;
+		if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c") || data === "n" || data === "N") return this.answer(false);
+		if (data.length === 1 && YES_KEYS[this.o.lang].includes(data.toLowerCase())) return this.answer(true);
+		const page = this.bodyRows() - 1;
+		if (matchesKey(data, "down")) this.scroll += 1;
+		else if (matchesKey(data, "up")) this.scroll = Math.max(0, this.scroll - 1);
+		else if (matchesKey(data, "pageDown")) this.scroll += page;
+		else if (matchesKey(data, "pageUp")) this.scroll = Math.max(0, this.scroll - page);
+		else return;
+		this.o.redraw?.();
+	}
+}

package/src/files.ts

@@ -0,0 +1,66 @@
+/**
+ * Files that the web view and the terminal screens open: which file a link may point to, which notes exist, and the system's
+ * default program. Moved out of web.ts so that the terminal does not import the web server.
+ */
+
+import { spawn, type ChildProcess } from "node:child_process";
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { expand } from "./config.ts";
+import { NOTE_DIRS, obsidianRoot, SETTINGS_DIR } from "./layout.ts";
+import { realish, within } from "./paths.ts";
+
+/** Files that the Open button may hand to the system (never programs or scripts). */
+export const OPENABLE = new Set([".md", ".markdown", ".txt", ".pdf", ".bib", ".csv", ".qmd"]);
+
+/** A file inside the working folder or the Sub-Sub folder, judged by its real path, so a link cannot point outside. */
+export function allowedFile(raw: string, cwd: string, vault?: string): string | undefined {
+	// expand() resolves against the process folder: use it for "~" only.
+	const target = resolve(cwd, raw.startsWith("~") ? expand(raw) : raw);
+	const real = realish(target);
+	const inside = within(real, realish(cwd)) || Boolean(vault && within(real, realish(vault)));
+	return inside && existsSync(target) && statSync(target).isFile() ? target : undefined;
+}
+
+/** The note a [[wikilink]] names: the first <folder>/<name>.md in the Sub-Sub folder, as Obsidian would find it. */
+export function wikilinkTarget(name: string, root: string): string | undefined {
+	const file = name.endsWith(".md") ? name : `${name}.md`;
+	return ["", ...NOTE_DIRS, SETTINGS_DIR].map((d) => join(root, d, file)).find((f) => existsSync(f));
+}
+
+/** The notes in the Sub-Sub folders, newest first (dot folders such as Research/.plans left out). */
+export function listNotes(root: string, max = 300): Array<{ path: string; rel: string; modified: number }> {
+	const out: Array<{ path: string; rel: string; modified: number }> = [];
+	for (const d of [...NOTE_DIRS, SETTINGS_DIR]) {
+		let names: string[] = [];
+		try {
+			names = readdirSync(join(root, d), { recursive: true }) as string[];
+		} catch {
+			continue;
+		}
+		for (const n of names) {
+			if (!n.endsWith(".md") || n.split(/[\\/]/).some((x) => x.startsWith("."))) continue;
+			const path = join(root, d, n);
+			out.push({ path, rel: join(d, n), modified: statSync(path).mtimeMs });
+		}
+	}
+	return out.sort((a, b) => b.modified - a.modified).slice(0, max);
+}
+
+/** Open a URL or a file with the system's default program. */
+export function openExternal(target: string): void {
+	const opts = { detached: true, stdio: "ignore" as const, windowsHide: true };
+	let child: ChildProcess;
+	if (process.platform === "darwin") child = spawn("open", [target], opts);
+	// rundll32 hands the target to the default program without cmd.exe parsing it.
+	else if (process.platform === "win32") child = spawn("rundll32", ["url.dll,FileProtocolHandler", target], opts);
+	else child = spawn("xdg-open", [target], opts);
+	child.on("error", () => {});
+	child.unref();
+}
+
+/** Open a note or document: in Obsidian when it is in an Obsidian vault, otherwise with the system's default program. */
+export function openFile(target: string, vault?: string): void {
+	if (vault && within(target, vault) && obsidianRoot(vault)) openExternal(`obsidian://open?path=${encodeURIComponent(target)}`);
+	else openExternal(target);
+}

package/src/look.ts

@@ -5,12 +5,17 @@
  */
 
 
+import { type Glyphs, UNICODE } from "./skin.ts";
+
 export const BANNER = [
 	"╔═╗╦ ╦╔╗    ╔═╗╦ ╦╔╗",
 	"╚═╗║ ║╠╩╗───╚═╗║ ║╠╩╗",
 	"╚═╝╚═╝╚═╝   ╚═╝╚═╝╚═╝",
 ];
 
+/** The banner for terminals without box-drawing glyphs (SUBSUB_ASCII=1 or a non-UTF-8 locale). */
+export const BANNER_ASCII = ["+-----------+", "|  Sub-Sub  |", "+-----------+"];
+
 /** Short public-domain lines from Moby-Dick and its Extracts. */
 export const QUOTES: Array<[string, string]> = [
 	["And God created great whales.", "Genesis, in the Extracts"],
@@ -26,13 +31,16 @@ export const QUOTES: Array<[string, string]> = [
 
 /** The terminal theme, without -dark/-light. subsub-try-works is the other one shipped. */
 export const DEFAULT_THEME = "subsub-glauca";
+/** The theme of the Librarian: the same plate with madder as its accent. */
+export const LIBRARIAN_THEME = "subsub-try-works";
 
 export type Scheme = "dark" | "light";
 
 /** Light or dark terminal, judged from the text colour of the current theme (dark text means a light background). */
 export function schemeFromAnsi(fgAnsi: string, themeName?: string): Scheme {
-	if (themeName?.endsWith("-light") || themeName === "light") return "light";
-	if (themeName?.endsWith("-dark") || themeName === "dark") return "dark";
+	const base = themeName?.replace(/-256$/, "");
+	if (base?.endsWith("-light") || base === "light") return "light";
+	if (base?.endsWith("-dark") || base === "dark") return "dark";
 	const rgb = fgAnsi.match(/38;2;(\d+);(\d+);(\d+)/);
 	if (rgb) {
 		const [r, g, b] = rgb.slice(1).map(Number);
@@ -47,8 +55,9 @@ export function schemeFromAnsi(fgAnsi: string, themeName?: string): Scheme {
 	return "dark";
 }
 
-export function themeName(scheme: Scheme, base: string | undefined = DEFAULT_THEME): string | undefined {
-	return base ? `${base}-${scheme}` : undefined;
+/** The 256-colour variant ("-256") when the terminal has no truecolor: its colours are picked from the xterm palette, not rounded to it. */
+export function themeName(scheme: Scheme, base: string | undefined = DEFAULT_THEME, colorMode?: "truecolor" | "256color"): string | undefined {
+	return base ? `${base}-${scheme}${colorMode === "256color" ? "-256" : ""}` : undefined;
 }
 
 export interface LibraryState {
@@ -58,26 +67,39 @@ export interface LibraryState {
 	error?: string;
 }
 
+/** Paint roles. mark is the accent of the mode; ok (sap green) is applied or added, pend (gamboge) is pending or a preview; strike draws a removal. */
 export interface Paint {
 	mark(s: string): string;
 	text(s: string): string;
 	muted(s: string): string;
 	dim(s: string): string;
-	warn(s: string): string;
+	ok(s: string): string;
+	pend(s: string): string;
+	strike(s: string): string;
 }
 
-const plain: Paint = { mark: (s) => s, text: (s) => s, muted: (s) => s, dim: (s) => s, warn: (s) => s };
+export const plain: Paint = { mark: (s) => s, text: (s) => s, muted: (s) => s, dim: (s) => s, ok: (s) => s, pend: (s) => s, strike: (s) => s };
+
+type Lang = "en" | "pt";
+
+/** The words of the library line, as in the web view (web/i18n.js: zoteroChecking, zoteroDown, items, toReview). */
+export const LIBRARY_WORDS = {
+	en: { checking: "Zotero: checking...", down: "Zotero is not running. Start it, then type /subsub.", items: "items", toCheck: "to check", prefix: "Zotero" },
+	pt: { checking: "Zotero: a verificar...", down: "O Zotero não está aberto. Abra-o e escreva /subsub.", items: "itens", toCheck: "por verificar", prefix: "Zotero" },
+};
 
 function cut(s: string, width: number): string {
 	return [...s].length > width ? `${[...s].slice(0, Math.max(0, width - 3)).join("")}...` : s;
 }
 
-export function libraryLine(st: LibraryState): { text: string; warn: boolean } {
-	if (st.zotero === "checking") return { text: "Zotero: checking...", warn: false };
-	if (st.zotero === "down") return { text: "Zotero is not running. Start it, then type /subsub.", warn: true };
-	const parts = [`${st.items ?? "?"} items`];
-	if (st.toReview) parts.push(`${st.toReview} to review`);
-	return { text: `Zotero: ${parts.join(", ")}`, warn: false };
+/** The library line. A closed Zotero is not drawn in a warning colour: a hollow mark and the words say it. */
+export function libraryLine(st: LibraryState, lang: Lang = "en", g: Glyphs = UNICODE): { text: string } {
+	const w = LIBRARY_WORDS[lang];
+	if (st.zotero === "checking") return { text: w.checking };
+	if (st.zotero === "down") return { text: `${g.hollow} ${w.down}` };
+	const parts = [`${st.items ?? "?"} ${w.items}`];
+	if (st.toReview) parts.push(`${st.toReview} ${w.toCheck}`);
+	return { text: `${w.prefix}: ${parts.join(", ")}` };
 }
 
 /** Header lines. Each line is cut to the width before it is coloured. */
@@ -89,23 +111,28 @@ export function headerLines(opts: {
 	quote?: [string, string];
 	width: number;
 	paint?: Paint;
+	lang?: Lang;
+	glyphs?: Glyphs;
 }): string[] {
 	const p = opts.paint ?? plain;
+	const banner = opts.glyphs && opts.glyphs !== UNICODE ? BANNER_ASCII : BANNER;
 	const w = Math.max(10, opts.width);
 	const modeLabel = opts.mode === "librarian" ? "Librarian" : "Researcher";
-	const lib = libraryLine(opts.library);
-	if (w < BANNER[0].length + 2) {
-		return [p.mark(cut(`Sub-Sub ${opts.version}`, w)), p.text(cut(`${modeLabel} | ${opts.model}`, w)), (lib.warn ? p.warn : p.muted)(cut(lib.text, w))];
+	const lib = libraryLine(opts.library, opts.lang, opts.glyphs);
+	if (w < banner[0].length + 2) {
+		return [p.mark(cut(`Sub-Sub ${opts.version}`, w)), p.text(cut(`${modeLabel} | ${opts.model}`, w)), p.muted(cut(lib.text, w))];
 	}
-	const out = ["", ...BANNER.map((l, i) => p.mark(l) + (i === 2 ? p.dim(cut(`  ${opts.version}`, w - l.length)) : "")), ""];
+	const out = ["", ...banner.map((l, i) => p.mark(l) + (i === 2 ? p.dim(cut(`  ${opts.version}`, w - l.length)) : "")), ""];
 	const status = `${modeLabel}  ${opts.model}`;
-	out.push(p.text(cut(status, w)) + (lib.warn ? p.warn : p.muted)(cut(`  |  ${lib.text}`, Math.max(0, w - status.length))));
+	// The library line follows the mode and model on the same line when it fits, otherwise on a line of its own.
+	if ([...status].length + 5 + [...lib.text].length <= w) out.push(p.text(status) + p.muted(`  |  ${lib.text}`));
+	else out.push(p.text(cut(status, w)), p.muted(cut(lib.text, w)));
 	if (opts.quote) {
 		const one = `"${opts.quote[0]}" (${opts.quote[1]})`;
 		if ([...one].length <= w) out.push(p.dim(one));
 		else out.push(p.dim(cut(`"${opts.quote[0]}"`, w)), p.dim(cut(`  (${opts.quote[1]})`, w)));
 	}
-	out.push(p.dim(cut("/researcher  /librarian  /read  /history  /undo  |  / for all commands", w)), "");
+	out.push(p.dim(cut("/researcher  /librarian  /read  /notes  /library  /actions  |  / for all commands", w)), "");
 	return out;
 }