@tiagojct/subsub 0.19.0 → 0.21.0

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 Sub-Sub follows the version numbers of npm: a change in the second number (0.13) adds features or changes how you use it; a change in the third (0.13.1) only fixes.
 
+## 0.21.0 (2026-10-23)
+
+A new look for the terminal. It is on by default in `subsub`; set `"look": false` in the settings to go back to the old screen.
+
+- Colours: the terminal themes use the colours of the website (Prussian blue for the Researcher, madder for the Librarian, sap green for what is applied or added, gamboge for a preview). Nothing is red. A failure is ink with a hollow mark and a word, a removal is struck through, and a closed Zotero is a hollow mark and the words "not running". The theme follows the mode, and `themes.librarian` in the settings picks another theme for the Librarian. There are variants for terminals with 256 colours, and a plain look for terminals that cannot draw box glyphs (set `SUBSUB_ASCII=1`, or use a locale that is not UTF-8). `SUBSUB_REDUCE_MOTION=1` stops the working indicator from moving.
+- Footer: the mode, the Zotero items and the items to check, the model, how much of the context is used, the tokens and the cost. It gets shorter on narrow terminals. It replaces pi's own footer, so the working folder and the git branch are not shown.
+- Tool lines: Sub-Sub's tools show in plain words, for example "search the library: asthma", dashed while they run and solid when done. A failure says "could not search the library" and gives the first line of the error. Press Ctrl+O to expand the rows and see the output. The tools of pi itself (read, edit, write) look as before.
+- Approvals: a library change opens a screen with the preview between dashed rules. Press y (s in Portuguese) to apply it, n or Esc to leave the library as it is. Enter does nothing, and keys pressed in the first half second are ignored, so a letter that you typed just before the screen opened cannot answer it. Removals in the preview are struck through, not red. With `look` off, pi's own Yes/No dialog is used.
+- Screens: `/notes` lists the notes in your Sub-Sub folder, newest first, with the chosen note beside the list from 100 columns, and its evidence line (full text, abstract or metadata). `/library` searches your Zotero library as you type; Enter puts `/read <item>` in the box (in the Librarian, the item's key) and Ctrl+N puts `/lit-note <item>`. `/actions` lists the actions of the browser view. The shortcuts are Alt+N, Alt+L and Alt+A, and Alt+M switches the mode. In macOS Terminal, Option acts as Alt only if you turn on "Use Option as Meta key"; the commands work everywhere.
+- `/read` offers the reasons (background, fact, extract, critique) when you press Tab.
+- The library line says "to check" ("por verificar"), as the browser view does; it said "to review".
+- Tests: snapshots of the screens at 40, 80 and 120 columns in English and Portuguese, contrast tests for the colours, and tests that run Sub-Sub in a terminal (macOS and Linux).
+
+## 0.20.0 (2026-10-23)
+
+Changes from a technical evaluation of 0.19.0 and Starbuck 0.2.0 (LLMSSH 2026).
+
+- Searching the library: when you ask what you have on a topic, Sub-Sub first searches with your own words, then with close synonyms and other word forms, and says which words it searched. In the evaluation it missed items whose titles use a synonym or repeat your words. In a test on the 20 evaluation tasks, recall rose from 0.87 to 0.96 and precision fell from 0.98 to 0.91: the wider search also lists some items that are only near the topic. Check the list.
+- Drafts: Sub-Sub now works from quotes. It reads the full text of each item, chooses a quote for each sentence, and writes the sentence so that it says no more than the quote, with one source for each sentence. A table "Quotes for the check" follows the draft with the quote, word for word, and the page or section for each sentence. A sentence without a quote is cut. In the evaluation, 37% to 53% of the factual sentences in drafts were only partly supported or unsupported by the works they cited. In a test on 18 drafts by two language-model raters, the share fell to 12% to 14% with the new rule. A second test on nine drafts of three other tasks, with the same raters, gave 14% and 16% against 35% and 37% for the old rule; one of the three tasks showed no change. The drafts have more and shorter sentences. Read the table as a way to check, not as a guarantee.
+- Reference checks: a Check with "not found by search" is reported as "not confirmed", with the note that books, theses, reports, archives and works in Portuguese are often missing from Crossref and PubMed. Claim verdicts are reported as sentences to check; Sub-Sub does not change the text or the citation because of a verdict.
+- Guide pages (English and Portuguese): the same two notes on reference checks.
+- Website: a Changes page (English; the Portuguese menu links to it) shows this file.
+- Bench: `retrievalScore` scores a retrieval answer by precision and recall against gold items, naming items by citekey or by title.
+
 ## 0.19.0 (2026-10-16)
 
 A new look for the browser view, the website, the tutorial and the workshop, after the engraved plates of 19th-century natural history books.

package/README.md

@@ -86,6 +86,8 @@ subsub --help        # all commands
 
 In the browser view, connect a model provider with the model button. In the terminal, type `/login`.
 
+The terminal has its own look, drawn like the website: a footer with the mode, the library, the model, the context in use and the cost; Sub-Sub's tools in plain words (`search the library: asthma`); and an approval screen for library changes (`y` applies, `n` or Esc leaves the library as it is, Enter does nothing). `/notes`, `/library` and `/actions` open screens for your notes, a library search and the actions of the browser view; Alt+N, Alt+L, Alt+A and Alt+M (mode) are shortcuts. Nothing is red: a failure is ink with a hollow mark and a word, and a removal is struck through. For terminals that cannot draw box glyphs, set `SUBSUB_ASCII=1`; `SUBSUB_REDUCE_MOTION=1` stops the working indicator from moving; `"look": false` in the settings brings back the plain screen.
+
 The browser view also has a library search (each result can start `/read` or `/lit-note`), a notes pane that shows the notes of your Sub-Sub folder next to the conversation (note paths and `[[links]]` in replies open there), argument hints for the commands, and rename, delete (to `~/.subsub/trash`) and export for conversations.
 
 Commands in Sub-Sub:
@@ -95,6 +97,7 @@ Commands in Sub-Sub:
 | `/researcher`, `/librarian` | Switch the mode |
 | `/subsub` | Zotero connection, mode, model and library counts |
 | `/history`, `/undo [id]` | Recent library changes; undo the last one or one by its id |
+| `/notes`, `/library`, `/actions` | Terminal screens: the notes in your Sub-Sub folder (the chosen note beside the list from 100 columns); a library search as you type (Enter starts `/read`, Ctrl+N `/lit-note`); the actions of the browser view as a list |
 | `/feedback [what happened]` | A draft bug report in `Inbox/`, with versions, `subsub doctor` and the last error, and without your folders, emails or keys. You post it on GitHub; Sub-Sub sends nothing |
 | `/ai-statement [uses]` | A draft statement on the use of AI for a manuscript, with the Sub-Sub version, its DOI and your models |
 | `/tag-batch [size]` | Tag items that have no topic, with your tag list |
@@ -137,7 +140,7 @@ subsub review apply 13-31
 | `usageLog` | `true` keeps the pilot's usage log on this computer (`subsub usage`) | off |
 | `serverDir` | A local copy of zotero-local-mcp, for development | the PyPI release |
 | `starbuckDir` | A local copy of Starbuck, for development | the pinned release |
-| `look`, `quotes`, `themes` | The terminal header, the Moby-Dick quotations, and the terminal colours (`subsub-glauca`, `subsub-try-works`, or `false` for your pi theme) | on, on, `subsub-glauca` |
+| `look`, `quotes`, `themes` | The terminal look (header, footer, approval screen, tool lines), the Moby-Dick quotations, and the terminal colours (`subsub-glauca`, `subsub-try-works`, or `false` for your pi theme). `themes` can be `{"researcher": "...", "librarian": "..."}`: the Librarian uses `subsub-try-works` unless you say otherwise | on, on, `subsub-glauca` |
 
 The settings of the Zotero server (Sub-Sub folder, tag list, alerts file, contact email) are in `~/.config/zotero-local-mcp/env`.
 

package/dist/bench.js

@@ -212,6 +212,37 @@ export function prf(pred, gold) {
     const fn = gold.size - tp;
     return { tp, fp, fn };
 }
+function plainTitle(t) {
+    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, library) {
+    const plain = plainTitle(text);
+    const found = new Set();
+    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, gold, acceptable, library) {
+    const original = (k) => 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, fp, fn) {
     const p = tp + fp ? tp / (tp + fp) : 0;
     const r = tp + fn ? tp / (tp + fn) : 0;

package/dist/chrome.js

@@ -0,0 +1,171 @@
+/**
+ * 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, plain } from "./look.js";
+import { UNICODE } from "./skin.js";
+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) => [...s].length;
+/** Cut to the width, with "..." when something is left out. Run it before the text is painted. */
+export function cut(s, width) {
+    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, width, height = 0) {
+    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, kind, paint = (s) => s, g = UNICODE) {
+    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, cells, g = UNICODE) {
+    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) {
+    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);
+}
+/**
+ * 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, width, p = plain, g = UNICODE) {
+    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;
+}
+/**
+ * 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, p = plain, g = UNICODE) {
+    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, max = 40) {
+    if (!args || typeof args !== "object")
+        return "";
+    const a = args;
+    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 "";
+}
+/** 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) {
+    return /full/i.test(evidence) ? "full" : /abstract/i.test(evidence) ? "abstract" : /metadata|metadados/i.test(evidence) ? "metadata" : "other";
+}
+export function evidenceLine(evidence, lang, width, p = plain, g = UNICODE) {
+    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) {
+    let tokens = 0;
+    let cost = 0;
+    for (const e of entries) {
+        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 };
+}
+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) {
+    const text = (result) => (result.content ?? []).filter((c) => c.type === "text").map((c) => c.text ?? "").join("\n");
+    return (toolName) => ({
+        renderShell: "self",
+        renderCall: (args, theme, context) => ({
+            render: (width) => [
+                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, options, theme, context) => {
+            const out = text(result);
+            if (context.state)
+                context.state.error = context.isError ? out.trim().split("\n")[0] : undefined;
+            return {
+                render: (width) => {
+                    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/dist/config.js

@@ -141,6 +141,7 @@ export function loadConfig(env = process.env) {
         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,
@@ -165,6 +166,7 @@ export function loadConfig(env = process.env) {
         look: user.look,
         quotes: user.quotes,
         themes,
+        themesLibrarian,
         addons: Array.isArray(user.addons) ? user.addons.filter((a) => typeof a === "string") : [],
         starbuckDir: expand(user.starbuckDir ?? "~/Projects/starbuck", home),
         usageLog: user.usageLog === true,

package/dist/dialogs.js

@@ -0,0 +1,81 @@
+/**
+ * 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.js";
+import { UNICODE } from "./skin.js";
+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 = { en: ["y"], pt: ["s", "y"] };
+/** The dialog as lines: rule, title, preview (scrolled), rule, keys. Every line fits the width. */
+export function approvalLines(o) {
+    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 };
+}
+/** The pi-tui component of the dialog (see ExtensionUIContext.custom). */
+export class ApprovalView {
+    scroll = 0;
+    answered = false;
+    o;
+    opened;
+    constructor(o) {
+        this.o = o;
+        this.opened = (o.now ?? Date.now)();
+    }
+    bodyRows() {
+        return Math.max(3, Math.floor(((this.o.rows?.() ?? 24) * 9) / 10) - 8);
+    }
+    render(width) {
+        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() { }
+    answer(yes) {
+        if (this.answered)
+            return;
+        this.answered = true;
+        this.o.done(yes);
+    }
+    handleInput(data) {
+        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/dist/files.js

@@ -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 } from "node:child_process";
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { expand } from "./config.js";
+import { NOTE_DIRS, obsidianRoot, SETTINGS_DIR } from "./layout.js";
+import { realish, within } from "./paths.js";
+/** 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, cwd, vault) {
+    // 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, root) {
+    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, max = 300) {
+    const out = [];
+    for (const d of [...NOTE_DIRS, SETTINGS_DIR]) {
+        let names = [];
+        try {
+            names = readdirSync(join(root, d), { recursive: true });
+        }
+        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) {
+    const opts = { detached: true, stdio: "ignore", windowsHide: true };
+    let child;
+    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, vault) {
+    if (vault && within(target, vault) && obsidianRoot(vault))
+        openExternal(`obsidian://open?path=${encodeURIComponent(target)}`);
+    else
+        openExternal(target);
+}

package/dist/look.js

@@ -3,11 +3,14 @@
  * per mode (try-works for the librarian, Glauca for the researcher).
  * Only used when Sub-Sub runs as its own command in the terminal UI.
  */
+import { UNICODE } from "./skin.js";
 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 = [
     ["And God created great whales.", "Genesis, in the Extracts"],
@@ -22,11 +25,14 @@ export const QUOTES = [
 ];
 /** 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";
 /** Light or dark terminal, judged from the text colour of the current theme (dark text means a light background). */
 export function schemeFromAnsi(fgAnsi, themeName) {
-    if (themeName?.endsWith("-light") || themeName === "light")
+    const base = themeName?.replace(/-256$/, "");
+    if (base?.endsWith("-light") || base === "light")
         return "light";
-    if (themeName?.endsWith("-dark") || themeName === "dark")
+    if (base?.endsWith("-dark") || base === "dark")
         return "dark";
     const rgb = fgAnsi.match(/38;2;(\d+);(\d+);(\d+)/);
     if (rgb) {
@@ -42,35 +48,48 @@ export function schemeFromAnsi(fgAnsi, themeName) {
     }
     return "dark";
 }
-export function themeName(scheme, base = DEFAULT_THEME) {
-    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, base = DEFAULT_THEME, colorMode) {
+    return base ? `${base}-${scheme}${colorMode === "256color" ? "-256" : ""}` : undefined;
 }
-const plain = { mark: (s) => s, text: (s) => s, muted: (s) => s, dim: (s) => s, warn: (s) => s };
+export const plain = { mark: (s) => s, text: (s) => s, muted: (s) => s, dim: (s) => s, ok: (s) => s, pend: (s) => s, strike: (s) => s };
+/** 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, width) {
     return [...s].length > width ? `${[...s].slice(0, Math.max(0, width - 3)).join("")}...` : s;
 }
-export function libraryLine(st) {
+/** 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, lang = "en", g = UNICODE) {
+    const w = LIBRARY_WORDS[lang];
     if (st.zotero === "checking")
-        return { text: "Zotero: checking...", warn: false };
+        return { text: w.checking };
     if (st.zotero === "down")
-        return { text: "Zotero is not running. Start it, then type /subsub.", warn: true };
-    const parts = [`${st.items ?? "?"} items`];
+        return { text: `${g.hollow} ${w.down}` };
+    const parts = [`${st.items ?? "?"} ${w.items}`];
     if (st.toReview)
-        parts.push(`${st.toReview} to review`);
-    return { text: `Zotero: ${parts.join(", ")}`, warn: false };
+        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. */
 export function headerLines(opts) {
     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)
@@ -78,7 +97,7 @@ export function headerLines(opts) {
         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;
 }
 /**