@tiagojct/subsub 0.19.0 → 0.21.0

package/scripts/make-themes.mjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+// Writes the pi themes of Sub-Sub (themes/subsub-<name>-<scheme>.json) from the colours in the front matter of
+// DESIGN.md and the role map in scripts/plate.json. The Researcher uses Prussian blue as its accent (glauca), the
+// Librarian madder (try-works). Errors have no colour of their own, removals are muted ink (the strike-through is
+// drawn by the code), and every meaning also has a glyph or a word, so the themes work for readers who do not see the washes.
+//
+//   node scripts/make-themes.mjs
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
+const SCHEMA = "https://raw.githubusercontent.com/earendil-works/pi/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json";
+
+/** The `colors:` block of the DESIGN.md front matter as {token: "#rrggbb"}. */
+export function designColors(markdown) {
+	const colors = {};
+	let inBlock = false;
+	for (const line of markdown.split("\n")) {
+		if (/^colors:\s*$/.test(line)) inBlock = true;
+		else if (inBlock && /^\S/.test(line)) break;
+		else if (inBlock) {
+			const m = line.match(/^\s+([a-z0-9-]+):\s*"(#[0-9a-fA-F]{6})"\s*$/);
+			if (m) colors[m[1]] = m[2].toLowerCase();
+		}
+	}
+	return colors;
+}
+
+
+const CUBE = [0, 95, 135, 175, 215, 255];
+/** The RGB of an xterm-256 colour index from 16 to 255 (the 16 system colours depend on the terminal). */
+export function xterm256(i) {
+	if (i >= 232) return [8 + (i - 232) * 10, 8 + (i - 232) * 10, 8 + (i - 232) * 10];
+	const n = i - 16;
+	return [CUBE[Math.floor(n / 36)], CUBE[Math.floor(n / 6) % 6], CUBE[n % 6]];
+}
+const toRgb = (h) => [1, 3, 5].map((k) => parseInt(h.slice(k, k + 2), 16));
+const luminance = (rgb) => {
+	const [r, g, b] = rgb.map((v) => v / 255).map((v) => (v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4));
+	return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+};
+export function contrastRatio(a, b) {
+	const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+	return (hi + 0.05) / (lo + 0.05);
+}
+
+/** The xterm-256 index nearest to a colour that reaches `min` contrast against `against` (the closest index with enough contrast, or the one with the most). */
+export function nearest256(hex, against, min) {
+	const want = toRgb(hex);
+	const ranked = [];
+	for (let i = 16; i < 256; i++) {
+		const c = xterm256(i);
+		ranked.push({ i, d: (c[0] - want[0]) ** 2 * 0.3 + (c[1] - want[1]) ** 2 * 0.59 + (c[2] - want[2]) ** 2 * 0.11, k: against ? contrastRatio(c, against) : Infinity });
+	}
+	ranked.sort((a, b) => a.d - b.d);
+	return (ranked.find((r) => r.k >= min) ?? ranked.sort((a, b) => b.k - a.k)[0]).i;
+}
+
+// Contrast that each colour variable needs against the terminal's own background: text 4.5, lines and bullets 3, rules none.
+const NEEDS = { ink: 4.5, muted: 4.5, faint: 4.5, prussian: 4.5, madder: 4.5, sap: 4.5, gamboge: 4.5, mark: 3, rule: 0 };
+// Roles whose background is left to the terminal in the 256-colour themes: a wash that is quantised to the cube loses its contrast.
+const DEFAULT_BG = ["userMessageBg", "customMessageBg", "toolPendingBg", "toolSuccessBg", "toolErrorBg", "searchMatchBg"];
+
+/** The same theme with xterm-256 indexes, for terminals without truecolor. */
+function to256(theme) {
+	const v = theme.vars;
+	const sheet = toRgb(v.sheet);
+	const vars = {};
+	for (const name of Object.keys(NEEDS)) vars[name] = nearest256(v[name], sheet, NEEDS[name]);
+	vars.accent = vars[Object.keys(NEEDS).find((n) => v[n] === v.accent)];
+	// The selection needs the text colour to stay readable on it.
+	vars.wash = nearest256(v.wash, xterm256(vars.ink), 4.5);
+	const colors = { ...theme.colors };
+	for (const r of DEFAULT_BG) colors[r] = "";
+	return { ...theme, name: `${theme.name}-256`, vars, colors, export: theme.export };
+}
+
+/** {"subsub-glauca-dark": theme, "subsub-glauca-dark-256": theme, ...} for every theme and scheme of the plate file. */
+export function buildThemes(designMd, plate) {
+	const design = designColors(designMd);
+	const out = {};
+	for (const [name, mode] of Object.entries(plate.themes)) {
+		for (const scheme of ["dark", "light"]) {
+			const vars = {};
+			for (const [v, key] of Object.entries(plate.tokens[scheme])) {
+				if (!design[key]) throw new Error(`DESIGN.md has no colour "${key}" (${scheme} ${v})`);
+				vars[v] = design[key];
+			}
+			vars.accent = vars[mode.accent];
+			vars.wash = vars[mode.wash];
+			const colors = {};
+			for (const [role, ref] of Object.entries(plate.roles)) colors[role] = ref === "$accent" ? "accent" : ref === "$wash" ? "wash" : ref;
+			const id = `subsub-${name}-${scheme}`;
+			out[id] = { $schema: SCHEMA, name: id, vars, colors, export: { pageBg: vars.sheet, cardBg: vars.field, infoBg: vars.sunk } };
+			out[`${id}-256`] = to256(out[id]);
+		}
+	}
+	return out;
+}
+
+function main() {
+	const design = fs.readFileSync(path.join(ROOT, "DESIGN.md"), "utf8");
+	const plate = JSON.parse(fs.readFileSync(path.join(ROOT, "scripts", "plate.json"), "utf8"));
+	fs.mkdirSync(path.join(ROOT, "themes"), { recursive: true });
+	for (const [id, theme] of Object.entries(buildThemes(design, plate))) {
+		fs.writeFileSync(path.join(ROOT, "themes", `${id}.json`), JSON.stringify(theme, null, "\t") + "\n");
+		console.log(`themes/${id}.json`);
+	}
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main();

package/scripts/plate.json

@@ -0,0 +1,35 @@
+{
+	"tokens": {
+		"light": {
+			"sheet": "sheet", "sunk": "sunk-field", "field": "plate-field", "ink": "copperplate-ink", "muted": "ink-muted", "faint": "ink-faint", "rule": "fine-rule", "mark": "plate-mark",
+			"prussian": "prussian-blue", "prussianWash": "prussian-wash", "madder": "madder", "madderWash": "madder-wash", "sap": "sap-green", "sapWash": "sap-wash", "gamboge": "gamboge", "gambogeWash": "gamboge-wash"
+		},
+		"dark": {
+			"sheet": "steel-ground", "sunk": "steel-sunk", "field": "steel-field", "ink": "steel-line", "muted": "steel-muted", "faint": "steel-faint", "rule": "steel-fine-rule", "mark": "steel-plate-mark",
+			"prussian": "steel-prussian", "prussianWash": "steel-prussian-wash", "madder": "steel-madder", "madderWash": "steel-madder-wash", "sap": "steel-sap", "sapWash": "steel-sap-wash", "gamboge": "steel-gamboge", "gambogeWash": "steel-gamboge-wash"
+		}
+	},
+	"themes": {
+		"glauca": { "accent": "prussian", "wash": "prussianWash" },
+		"try-works": { "accent": "madder", "wash": "madderWash" }
+	},
+	"roles": {
+		"text": "ink", "userMessageText": "ink", "customMessageText": "ink", "toolTitle": "ink", "mdHeading": "ink", "mdCode": "ink", "mdCodeBlock": "ink", "error": "ink",
+		"muted": "muted", "toolOutput": "muted", "mdQuote": "muted", "toolDiffContext": "muted", "thinkingText": "muted", "toolDiffRemoved": "muted",
+		"dim": "faint", "mdLinkUrl": "faint", "syntaxComment": "faint",
+		"border": "mark", "mdQuoteBorder": "mark", "mdListBullet": "mark",
+		"borderMuted": "rule", "mdHr": "rule", "mdCodeBlockBorder": "rule", "scrollbarTrack": "rule", "thinkingOff": "rule",
+		"scrollbarThumb": "faint",
+		"accent": "$accent", "borderAccent": "$accent", "bashMode": "$accent", "customMessageLabel": "$accent", "thinkingXhigh": "$accent", "thinkingMax": "$accent",
+		"mdLink": "prussian", "thinkingHigh": "prussian",
+		"success": "sap", "toolDiffAdded": "sap",
+		"warning": "gamboge",
+		"selectedBg": "$wash",
+		"searchMatchBg": "gambogeWash", "searchMatchText": "ink",
+		"userMessageBg": "field", "toolSuccessBg": "field",
+		"customMessageBg": "sunk", "toolErrorBg": "sunk",
+		"toolPendingBg": "gambogeWash",
+		"syntaxKeyword": "prussian", "syntaxNumber": "prussian", "syntaxFunction": "ink", "syntaxVariable": "ink", "syntaxType": "ink", "syntaxString": "muted", "syntaxOperator": "muted", "syntaxPunctuation": "faint",
+		"thinkingMinimal": "faint", "thinkingLow": "mark", "thinkingMedium": "muted"
+	}
+}

package/src/bench.ts

@@ -262,6 +262,46 @@ export function prf(pred: Set<string>, gold: Set<string>) {
 	return { tp, fp, fn };
 }
 
+/** A library item as the retrieval score needs it: the citekey and the title. */
+export interface LibraryItem {
+	citekey: string;
+	title: string;
+}
+
+function plainTitle(t: string): string {
+	return t.toLowerCase().replace(/[^\p{L}\p{N}]+/gu, " ").trim();
+}
+
+/**
+ * The library items that an answer names. An item is named by its citekey, or by the first 40 characters of its title
+ * (at least 15). A duplicate copy (citekey ending in -dup) counts as its original.
+ */
+export function itemsNamed(text: string, library: LibraryItem[]): Set<string> {
+	const plain = plainTitle(text);
+	const found = new Set<string>();
+	for (const item of library) {
+		const key = item.citekey.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+		const title = plainTitle(item.title).slice(0, 40).trim();
+		if (new RegExp(`(?<![A-Za-z0-9_])${key}(?![A-Za-z0-9_])`).test(text) || (title.length >= 15 && plain.includes(title))) {
+			found.add(item.citekey.replace(/-dup$/, ""));
+		}
+	}
+	return found;
+}
+
+/**
+ * Precision and recall of the items in a retrieval answer against the gold items. Items in `acceptable` are on the topic but
+ * outside the gold list: they count as neither hits nor errors. "(copy)" and "-dup" mark a duplicate and count as the original.
+ */
+export function retrievalScore(text: string, gold: string[], acceptable: string[], library: LibraryItem[]) {
+	const original = (k: string) => k.replace(/\s*\(copy\)\s*$/, "").replace(/-dup$/, "");
+	const goldSet = new Set(gold.map(original));
+	const skip = new Set(acceptable.map(original));
+	const said = new Set([...itemsNamed(text, library)].filter((k) => goldSet.has(k) || !skip.has(k)));
+	const { tp, fp, fn } = prf(said, goldSet);
+	return { ...f1(tp, fp, fn), tp, fp, fn };
+}
+
 function f1(tp: number, fp: number, fn: number) {
 	const p = tp + fp ? tp / (tp + fp) : 0;
 	const r = tp + fn ? tp / (tp + fn) : 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/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);
+}