@tiagojct/subsub 0.19.0 → 0.21.0

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;
 }
 

package/src/screens.ts

@@ -0,0 +1,374 @@
+/**
+ * The notes and library screens of the terminal look, as pi-tui components for `ctx.ui.custom()`. Each has a pure function that draws it as
+ * lines (snapshots at 40, 80 and 120 columns) and a class that holds the state and the keys. The notes screen has two columns from 100 columns
+ * up (the list, and the note under the cursor); below that it is a list, and Enter opens a note.
+ */
+
+import { matchesKey, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { cut, evidenceLine, fill, rule } from "./chrome.ts";
+import type { Paint } from "./look.ts";
+import { frontMatter, field } from "./notes.ts";
+import { type Glyphs, UNICODE } from "./skin.ts";
+
+type Lang = "en" | "pt";
+
+export const SCREEN_WORDS = {
+	en: {
+		notes: "Notes", of: "of", filter: "filter", none: "No notes yet. Sub-Sub writes them in Literature/, Research/ and Syntheses/.", noMatch: "No note matches.", empty: "(empty note)",
+		hintNotes: "up and down: choose   type: filter   PgUp PgDn: scroll   ctrl+o: open   Esc: close", hintRead: "up and down: scroll   ctrl+o: open   Esc: back",
+		library: "Library", typeToSearch: "Type to search your library.", searching: "Searching...", noItems: "Nothing found.", failed: "The search failed",
+		hintLibrary: "up and down: choose   Enter: read   ctrl+n: note   Esc: close", hintLibrarian: "up and down: choose   Enter: copy the key   Esc: close",
+	},
+	pt: {
+		notes: "Notas", of: "de", filter: "filtro", none: "Ainda não há notas. O Sub-Sub escreve-as em Literature/, Research/ e Syntheses/.", noMatch: "Nenhuma nota corresponde.", empty: "(nota vazia)",
+		hintNotes: "cima e baixo: escolher   escrever: filtrar   PgUp PgDn: deslocar   ctrl+o: abrir   Esc: fechar", hintRead: "cima e baixo: deslocar   ctrl+o: abrir   Esc: voltar",
+		library: "Biblioteca", typeToSearch: "Escreva para pesquisar na biblioteca.", searching: "A pesquisar...", noItems: "Nada encontrado.", failed: "A pesquisa falhou",
+		hintLibrary: "cima e baixo: escolher   Enter: ler   ctrl+n: nota   Esc: fechar", hintLibrarian: "cima e baixo: escolher   Enter: copiar a chave   Esc: fechar",
+	},
+};
+
+const LEFT = 36;
+const WIDE = 100;
+
+function pad(s: string, width: number): string {
+	return s + " ".repeat(Math.max(0, width - visibleWidth(s)));
+}
+
+/** A key that types text (a letter, a digit, a pasted string), not a control or escape sequence. */
+export function printable(data: string): boolean {
+	return data.length > 0 && !/[\x00-\x1f\x7f]/.test(data);
+}
+
+// ---------------------------------------------------------------- notes
+
+export interface NotesLayout {
+	width: number;
+	/** Lines for the whole screen. */
+	rows: number;
+	lang: Lang;
+	paint: Paint;
+	glyphs?: Glyphs;
+	mode: "list" | "read";
+	/** Paths of the notes that match the filter, relative to the Sub-Sub folder. */
+	entries: string[];
+	total: number;
+	selected: number;
+	filter: string;
+	evidence?: string;
+	/** The chosen note as lines, for a width. */
+	renderBody: (width: number) => string[];
+	bodyScroll: number;
+}
+
+export function notesLines(o: NotesLayout): { lines: string[]; bodyMax: number } {
+	const g = o.glyphs ?? UNICODE;
+	const p = o.paint;
+	const w = Math.max(20, o.width);
+	const words = SCREEN_WORDS[o.lang];
+	const rows = Math.max(3, o.rows - 5);
+	const wide = w >= WIDE && o.mode === "list";
+	const count = o.entries.length === o.total ? `${o.total}` : `${o.entries.length} ${words.of} ${o.total}`;
+	const out = [p.mark(cut(` ${words.notes}`, w)) + p.muted(cut(` (${count})${o.filter ? `   ${words.filter}: ${o.filter}` : ""}`, Math.max(0, w - words.notes.length - 1))), rule(w, "solid", p.muted, g)];
+	let bodyMax = 0;
+	const hint = (text: string) => wrapTextWithAnsi(` ${text}`, w).map((l) => p.muted(l));
+	if (o.total === 0 || o.entries.length === 0) {
+		out.push(p.muted(cut(`  ${o.total === 0 ? words.none : words.noMatch}`, w)), rule(w, "solid", p.muted, g), ...hint(words.hintNotes));
+		return { lines: out, bodyMax };
+	}
+	const list = (width: number): string[] => {
+		const start = Math.max(0, Math.min(o.selected - Math.floor(rows / 2), o.entries.length - rows));
+		return o.entries.slice(start, start + rows).map((rel, k) => {
+			const chosen = start + k === o.selected;
+			return chosen ? `${p.mark(g.pointer)} ${p.text(cut(rel, width - 2))}` : `  ${p.muted(cut(rel, width - 2))}`;
+		});
+	};
+	const body = (width: number): string[] => {
+		const lines = o.renderBody(Math.max(10, width));
+		const head = o.evidence ? [evidenceLine(o.evidence, o.lang, width, p, g), ""] : [];
+		const room = Math.max(1, rows - head.length);
+		bodyMax = Math.max(0, lines.length - room);
+		const from = Math.min(o.bodyScroll, bodyMax);
+		const shown = lines.slice(from, from + room).map((l) => truncateToWidth(l, width));
+		return [...head, ...(shown.length ? shown : [p.dim(words.empty)])];
+	};
+	if (wide) {
+		const right = w - LEFT - 3;
+		const left = list(LEFT);
+		const detail = body(right);
+		for (let i = 0; i < rows; i++) out.push(`${pad(left[i] ?? "", LEFT)} ${p.muted(g.vertical)} ${detail[i] ?? ""}`);
+		out.push(rule(w, "solid", p.muted, g), ...hint(words.hintNotes));
+	} else if (o.mode === "list") {
+		out.push(...list(w), rule(w, "solid", p.muted, g), ...hint(words.hintNotes));
+	} else {
+		out.push(...body(w), rule(w, "solid", p.muted, g), ...hint(words.hintRead));
+	}
+	return { lines: out, bodyMax };
+}
+
+export interface NotesOptions {
+	/** The notes, newest first. */
+	notes: Array<{ path: string; rel: string }>;
+	read: (path: string) => string;
+	/** The text of a note as lines, for a width (pi's Markdown component in the terminal). */
+	markdown: (text: string, width: number) => string[];
+	open: (path: string) => void;
+	done: () => void;
+	lang: Lang;
+	paint: Paint;
+	glyphs?: Glyphs;
+	rows?: () => number;
+	redraw?: () => void;
+}
+
+export class NotesView {
+	private readonly o: NotesOptions;
+	private filter = "";
+	private selected = 0;
+	private mode: "list" | "read" = "list";
+	private bodyScroll = 0;
+	private bodyMax = 0;
+	private lastWidth = 80;
+	private readonly texts = new Map<string, string>();
+	constructor(o: NotesOptions) {
+		this.o = o;
+	}
+
+	private entries() {
+		const f = this.filter.toLowerCase();
+		return f ? this.o.notes.filter((n) => n.rel.toLowerCase().includes(f)) : this.o.notes;
+	}
+
+	private text(): string {
+		const n = this.entries()[this.selected];
+		if (!n) return "";
+		let t = this.texts.get(n.path);
+		if (t === undefined) {
+			try {
+				t = this.o.read(n.path);
+			} catch {
+				t = "";
+			}
+			this.texts.set(n.path, t);
+		}
+		return t;
+	}
+
+	render(width: number): string[] {
+		this.lastWidth = width;
+		const text = this.text();
+		const front = frontMatter(text);
+		const evidence = front ? field(front, "evidence") : undefined;
+		const body = front ? text.slice(text.indexOf("\n---", 3) + 4).replace(/^\r?\n/, "") : text;
+		const entries = this.entries();
+		const view = notesLines({
+			width, rows: this.height(), lang: this.o.lang, paint: this.o.paint, glyphs: this.o.glyphs, mode: this.mode, entries: entries.map((n) => n.rel), total: this.o.notes.length,
+			selected: this.selected, filter: this.filter, evidence, renderBody: (w) => this.o.markdown(body, w), bodyScroll: this.bodyScroll,
+		});
+		this.bodyMax = view.bodyMax;
+		this.bodyScroll = Math.min(this.bodyScroll, this.bodyMax);
+		return fill(view.lines, width, this.height());
+	}
+
+	/** The screen covers the terminal, but for one line. */
+	private height(): number {
+		return Math.max(8, (this.o.rows?.() ?? 24) - 1);
+	}
+
+	invalidate(): void {}
+
+	private move(by: number): void {
+		const n = this.entries().length;
+		if (!n) return;
+		this.selected = Math.min(n - 1, Math.max(0, this.selected + by));
+		this.bodyScroll = 0;
+	}
+
+	handleInput(data: string): void {
+		const page = Math.max(3, this.height() - 6);
+		const wideList = this.lastWidth >= WIDE && this.mode === "list";
+		const scrolls = this.mode === "read" || wideList;
+		if (matchesKey(data, "ctrl+c")) return this.o.done();
+		if (matchesKey(data, "escape")) {
+			if (this.mode === "read") this.mode = "list";
+			else if (this.filter) {
+				this.filter = "";
+				this.selected = 0;
+			} else return this.o.done();
+		} else if (matchesKey(data, "ctrl+o")) {
+			const n = this.entries()[this.selected];
+			if (n) this.o.open(n.path);
+			return;
+		} else if (matchesKey(data, "enter")) {
+			if (this.mode === "list" && !wideList && this.entries().length) {
+				this.mode = "read";
+				this.bodyScroll = 0;
+			}
+		} else if (matchesKey(data, "up")) {
+			if (this.mode === "read") this.bodyScroll = Math.max(0, this.bodyScroll - 1);
+			else this.move(-1);
+		} else if (matchesKey(data, "down")) {
+			if (this.mode === "read") this.bodyScroll = Math.min(this.bodyMax, this.bodyScroll + 1);
+			else this.move(1);
+		} else if (matchesKey(data, "pageUp")) {
+			if (scrolls) this.bodyScroll = Math.max(0, this.bodyScroll - page);
+			else this.move(-page);
+		} else if (matchesKey(data, "pageDown")) {
+			if (scrolls) this.bodyScroll = Math.min(this.bodyMax, this.bodyScroll + page);
+			else this.move(page);
+		} else if (this.mode === "list" && matchesKey(data, "backspace")) {
+			this.filter = this.filter.slice(0, -1);
+			this.selected = 0;
+		} else if (this.mode === "list" && printable(data)) {
+			this.filter += data;
+			this.selected = 0;
+			this.bodyScroll = 0;
+		} else return;
+		this.o.redraw?.();
+	}
+}
+
+// ---------------------------------------------------------------- library
+
+export interface LibraryItem {
+	key: string;
+	citekey?: string;
+	title?: string;
+	authors?: string;
+	year?: string | number;
+}
+
+export interface LibraryLayout {
+	width: number;
+	rows: number;
+	lang: Lang;
+	paint: Paint;
+	glyphs?: Glyphs;
+	researcher: boolean;
+	query: string;
+	items: LibraryItem[];
+	selected: number;
+	state: "idle" | "searching" | "done" | "failed";
+	error?: string;
+}
+
+export function libraryLines(o: LibraryLayout): string[] {
+	const g = o.glyphs ?? UNICODE;
+	const p = o.paint;
+	const w = Math.max(20, o.width);
+	const words = SCREEN_WORDS[o.lang];
+	const room = Math.max(2, o.rows - 5);
+	const out = [p.mark(cut(` ${words.library}`, w)), `${p.muted(" > ")}${p.text(cut(o.query, w - 4))}${p.mark("_")}`, rule(w, "solid", p.muted, g)];
+	if (o.state === "idle" && !o.query) out.push(p.muted(cut(`  ${words.typeToSearch}`, w)));
+	else if (o.state === "searching") out.push(p.muted(cut(`  ${words.searching}`, w)));
+	else if (o.state === "failed") out.push(p.text(cut(`  ${g.hollow} ${words.failed}${o.error ? `: ${o.error.split("\n")[0]}` : ""}`, w)));
+	else if (!o.items.length) out.push(p.muted(cut(`  ${words.noItems}`, w)));
+	else {
+		const per = 2;
+		const fit = Math.max(1, Math.floor(room / per));
+		const start = Math.max(0, Math.min(o.selected - Math.floor(fit / 2), o.items.length - fit));
+		for (const [k, it] of o.items.slice(start, start + fit).entries()) {
+			const chosen = start + k === o.selected;
+			const meta = [it.authors, it.year, it.citekey].filter(Boolean).join(" · ");
+			out.push(chosen ? `${p.mark(g.pointer)} ${p.text(cut(it.title || it.key, w - 2))}` : `  ${p.muted(cut(it.title || it.key, w - 2))}`, `  ${p.dim(cut(meta, w - 2))}`);
+		}
+	}
+	out.push(rule(w, "solid", p.muted, g), ...wrapTextWithAnsi(` ${o.researcher ? words.hintLibrary : words.hintLibrarian}`, w).map((l) => p.muted(l)));
+	return out;
+}
+
+export interface LibraryOptions {
+	search: (query: string) => Promise<LibraryItem[]>;
+	/** Enter: the researcher reads the item, the librarian gets its key. */
+	choose: (item: LibraryItem) => void;
+	note: (item: LibraryItem) => void;
+	done: () => void;
+	lang: Lang;
+	paint: Paint;
+	glyphs?: Glyphs;
+	researcher: boolean;
+	rows?: () => number;
+	redraw?: () => void;
+	/** Milliseconds to wait after the last key before searching. */
+	delay?: number;
+}
+
+export class LibraryView {
+	private readonly o: LibraryOptions;
+	private query = "";
+	private items: LibraryItem[] = [];
+	private selected = 0;
+	private state: LibraryLayout["state"] = "idle";
+	private error: string | undefined;
+	private timer: ReturnType<typeof setTimeout> | undefined;
+	private seq = 0;
+	constructor(o: LibraryOptions) {
+		this.o = o;
+	}
+
+	render(width: number): string[] {
+		const height = Math.max(8, (this.o.rows?.() ?? 24) - 1);
+		return fill(
+			libraryLines({
+				width, rows: height, lang: this.o.lang, paint: this.o.paint, glyphs: this.o.glyphs, researcher: this.o.researcher,
+				query: this.query, items: this.items, selected: this.selected, state: this.state, error: this.error,
+			}),
+			width,
+			height,
+		);
+	}
+
+	invalidate(): void {}
+
+	dispose(): void {
+		clearTimeout(this.timer);
+	}
+
+	private schedule(): void {
+		clearTimeout(this.timer);
+		const q = this.query.replace(/\s+/g, " ").trim();
+		const mine = ++this.seq;
+		if (!q) {
+			this.items = [];
+			this.state = "idle";
+			return;
+		}
+		this.state = "searching";
+		this.timer = setTimeout(async () => {
+			try {
+				const items = await this.o.search(q);
+				if (mine !== this.seq) return; // a newer search is on its way
+				this.items = items;
+				this.state = "done";
+				this.selected = 0;
+			} catch (err) {
+				if (mine !== this.seq) return;
+				this.state = "failed";
+				this.error = (err as Error).message;
+			}
+			this.o.redraw?.();
+		}, this.o.delay ?? 250);
+	}
+
+	handleInput(data: string): void {
+		if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c")) return this.o.done();
+		const item = this.items[this.selected];
+		if (matchesKey(data, "enter")) {
+			if (item) this.o.choose(item);
+			return;
+		}
+		if (matchesKey(data, "ctrl+n")) {
+			if (item && this.o.researcher) this.o.note(item);
+			return;
+		}
+		if (matchesKey(data, "up")) this.selected = Math.max(0, this.selected - 1);
+		else if (matchesKey(data, "down")) this.selected = Math.min(Math.max(0, this.items.length - 1), this.selected + 1);
+		else if (matchesKey(data, "backspace")) {
+			this.query = this.query.slice(0, -1);
+			this.schedule();
+		} else if (printable(data)) {
+			this.query += data;
+			this.schedule();
+		} else return;
+		this.o.redraw?.();
+	}
+}

package/src/skin.ts

@@ -0,0 +1,65 @@
+/**
+ * The skin of the terminal screens: the paint roles drawn from a pi theme, and the glyphs. Meaning is never carried by
+ * colour alone: a rule is solid, dashed or dotted, a failure has a hollow mark and a word, and a terminal that cannot show
+ * the box-drawing glyphs (a non-UTF-8 locale, or SUBSUB_ASCII=1) gets plain ASCII.
+ */
+
+import type { Paint } from "./look.ts";
+
+export interface Glyphs {
+	/** A solid rule: full text, done. */
+	solid: string;
+	/** A dashed rule: an abstract, a preview, pending. */
+	dashed: string;
+	/** A dotted rule: metadata only. */
+	dotted: string;
+	/** The hollow mark of a failure or of something that is not running. */
+	hollow: string;
+	/** A filled and an empty cell of the context meter. */
+	cell: string;
+	cellEmpty: string;
+	/** The line between two columns, and the mark in front of the chosen row of a list. */
+	vertical: string;
+	pointer: string;
+}
+
+export const UNICODE: Glyphs = { solid: "─", dashed: "┄", dotted: "┈", hollow: "○", cell: "▰", cellEmpty: "▱", vertical: "│", pointer: "›" };
+export const ASCII: Glyphs = { solid: "=", dashed: "-", dotted: ".", hollow: "o", cell: "#", cellEmpty: "-", vertical: "|", pointer: ">" };
+
+/** ASCII when SUBSUB_ASCII is set, or when the locale is C, POSIX or names a character set that is not UTF-8 (pt_PT.ISO-8859-1). No locale, or one without a character set, means UTF-8. */
+export function useAscii(env: NodeJS.ProcessEnv = process.env): boolean {
+	if (env.SUBSUB_ASCII && env.SUBSUB_ASCII !== "0") return true;
+	const locale = env.LC_ALL || env.LC_CTYPE || env.LANG;
+	if (!locale || /utf-?8/i.test(locale)) return false;
+	return locale === "C" || locale === "POSIX" || /\.[^.]+$/.test(locale);
+}
+
+export function glyphs(env: NodeJS.ProcessEnv = process.env): Glyphs {
+	return useAscii(env) ? ASCII : UNICODE;
+}
+
+/** The part of pi's Theme that the skin uses. */
+export interface ThemeLike {
+	fg(role: string, text: string): string;
+	strikethrough?(text: string): string;
+}
+
+/** Paint roles from the colours of a pi theme (themes/*.json): accent, text, muted, dim, success (sap) and warning (gamboge). */
+export function paintFromTheme(th: ThemeLike): Paint {
+	return {
+		mark: (x) => th.fg("accent", x),
+		text: (x) => th.fg("text", x),
+		muted: (x) => th.fg("muted", x),
+		dim: (x) => th.fg("dim", x),
+		ok: (x) => th.fg("success", x),
+		pend: (x) => th.fg("warning", x),
+		// A removal has no colour of its own: muted ink, struck through, and the "-" in front stays for terminals that ignore the strike.
+		strike: (x) => (th.strikethrough ? th.strikethrough(th.fg("muted", x)) : th.fg("muted", x)),
+	};
+}
+
+/** Frames of the working indicator: dotted, dashed, solid, dashed. One static frame when motion is reduced (SUBSUB_REDUCE_MOTION=1). */
+export function workingFrames(g: Glyphs, reduceMotion = false): string[] {
+	const dashed = g.dashed.repeat(4);
+	return reduceMotion ? [dashed] : [g.dotted.repeat(4), dashed, g.solid.repeat(4), dashed];
+}