@tiagojct/subsub 0.11.3 → 0.12.0

package/web/app.css

@@ -631,6 +631,11 @@ body.layout-full { --measure: 72rem; }
 .note.mono { font-family: var(--mono); font-size: 0.76rem; line-height: 1.55; }
 .note pre { font-family: var(--mono); font-size: 0.74rem; white-space: pre-wrap; }
 .note button { margin-top: 0.5rem; }
+.note p { margin: 0; }
+.note details { margin-top: 0.4rem; color: var(--muted); }
+.note details summary { cursor: pointer; font-size: 0.78rem; }
+.note details pre { margin: 0.3rem 0 0; overflow-wrap: anywhere; }
+.free-note { border-left: 3px solid var(--accent); padding-left: 0.6rem; }
 
 .working {
 	margin-top: 1rem;
@@ -826,6 +831,14 @@ body > p.empty { text-align: center; color: var(--muted); padding: 30vh 1rem 0;
 .models button:hover { background: var(--bg); }
 .models .current { color: var(--accent); font-weight: 600; background: var(--accent-soft); }
 .models .empty-models { padding: 0.65rem 0.8rem; color: var(--muted); font-size: 0.88rem; }
+.model-search { width: 100%; margin-bottom: 0.5rem; }
+.models { max-height: 20rem; }
+.models .models-group { padding: 0.45rem 0.8rem 0.3rem; font-size: 0.78rem; font-weight: 600; color: var(--muted); background: var(--surface); }
+.models button { display: flex; flex-wrap: wrap; align-items: baseline; gap: 0.25rem 0.6rem; }
+.models .needs-key { opacity: 0.65; }
+.models .model-name { min-width: 0; overflow-wrap: anywhere; }
+.models .model-tag { font-family: var(--sans); font-size: 0.72rem; font-weight: 600; color: var(--accent); border: 1px solid currentColor; border-radius: 999px; padding: 0 0.45rem; }
+.models .model-why { font-family: var(--sans); font-size: 0.75rem; color: var(--muted); }
 
 /* ---------------------------------------------------------------- narrow screens */
 
@@ -870,3 +883,14 @@ body > p.empty { text-align: center; color: var(--muted); padding: 30vh 1rem 0;
 @media (prefers-reduced-motion: reduce) {
 	*, *::before, *::after { animation: none !important; transition: none !important; }
 }
+
+/* First run: what is still missing */
+.setup { margin-block: 1.4rem 1rem; padding: 0.9rem 1rem; border: 1px solid var(--rule); border-left: 3px solid var(--accent); border-radius: 6px; background: var(--raised); text-align: left; max-width: 40rem; }
+.setup h2 { margin: 0 0 0.5rem; font-size: 0.95rem; }
+.setup ol { list-style: none; margin: 0; padding: 0; display: grid; gap: 0.55rem; }
+.setup li { display: grid; grid-template-columns: 4.5rem 1fr auto; gap: 0.6rem; align-items: start; font-size: 0.88rem; line-height: 1.45; }
+.setup li > * { min-width: 0; }
+.setup .mark { font-size: 0.72rem; text-transform: uppercase; letter-spacing: 0.05em; padding-top: 0.15rem; color: var(--muted); }
+.setup li.todo .mark { color: var(--rem); }
+.setup li.ok .step-text { color: var(--muted); }
+@media (max-width: 560px) { .setup li { grid-template-columns: 1fr; gap: 0.2rem; } }

package/web/app.js

@@ -368,6 +368,21 @@ function scrollDown(force = false) {
 	if (force || near) log.scrollTop = log.scrollHeight;
 }
 
+// A provider error in plain words (keep in step with providerTrouble in src/keys.ts), with the raw text below.
+function troubleOf(text) {
+	if (/RESOURCE_EXHAUSTED|\b429\b|quota|rate.?limit|too many requests|usage limit/i.test(text)) return "quota";
+	if (/\b(503|529)\b|UNAVAILABLE|high demand|overloaded/i.test(text)) return "busy";
+	if (/RECITATION|SAFETY|PROHIBITED_CONTENT/.test(text)) return "blocked";
+	if (/\b(401|403)\b|API key not valid|invalid api key|PERMISSION_DENIED|UNAUTHENTICATED/i.test(text)) return "key";
+	return null;
+}
+
+function errorNote(text) {
+	const kind = troubleOf(text);
+	if (!kind) return el("div", { class: "note error", text });
+	return el("div", { class: "note error" }, el("p", { text: t(`trouble_${kind}`) }), el("details", {}, el("summary", { text: t("details") }), el("pre", { text })));
+}
+
 function note(text, kind = "info", mono = false) {
 	clearEmpty();
 	const n = el("div", { class: `note ${kind}${mono ? " mono" : ""}`, text });
@@ -380,6 +395,36 @@ function clearEmpty() {
 	log.querySelector(".empty")?.remove();
 }
 
+/** First run: what is still missing (Zotero, a model, the servers), each with its fix. Hidden when all is ready. */
+function setupList() {
+	const L = state?.library;
+	const m = state?.model ?? session?.model;
+	const steps = [
+		{ ok: L?.zotero === "reachable", wait: !L || L.zotero === "checking", text: t("stepZotero") },
+		{ ok: Boolean(m && m.id && m.id !== "unknown"), text: t("stepModel"), action: { label: t("connect"), run: openModels } },
+		{ ok: !state?.down?.length, text: t("stepServers", { x: (state?.down ?? []).join(", ") }) },
+	];
+	if (steps.every((x) => x.ok || x.wait)) return null;
+	return el(
+		"div",
+		{ class: "setup" },
+		el("h2", { text: t("setupTitle") }),
+		el(
+			"ol",
+			{},
+			steps.map((x) =>
+				el(
+					"li",
+					{ class: x.ok ? "ok" : x.wait ? "wait" : "todo" },
+					el("span", { class: "mark", text: x.ok ? t("stepDone") : x.wait ? "…" : t("stepTodo") }),
+					el("span", { class: "step-text", text: x.ok ? x.text.split(". ")[0] : x.text }),
+					!x.ok && x.action ? el("button", { type: "button", class: "primary small-btn", text: x.action.label, onclick: x.action.run }) : null,
+				),
+			),
+		),
+	);
+}
+
 function renderEmpty() {
 	if (log.children.length) return;
 	const s = SUGGESTIONS[mode()].map((x) => x[lang] ?? x.en);
@@ -390,6 +435,7 @@ function renderEmpty() {
 			el("p", { class: "kicker", text: t(mode()) }),
 			el("h1", { text: t("emptyTitle") }),
 			el("p", { class: "lede", text: t(mode() === "librarian" ? "emptyLibrarian" : "emptyResearcher") }),
+			setupList(),
 			el(
 				"div",
 				{ class: "chips" },
@@ -490,6 +536,23 @@ function finishTool(id, result, isError) {
 	row.querySelector("pre")?.remove();
 	if (text) row.append(el("pre", { text: text.length > 6000 ? `${text.slice(0, 6000)}\n...` : text }));
 	if (isError) row.querySelector(".label").textContent = `${toolLabel(row.dataset.name)} (${t("failed")})`;
+	// An applied library change gets an Undo button; it runs /undo with its id, which previews first.
+	const jid = !isError && !/undo/.test(row.dataset.name) && /"journal_id":\s*"(\d{8}-\d{6}-\d{2}-[a-z_]+)"/.exec(text ?? "")?.[1];
+	if (jid && !row.querySelector(".undo")) {
+		row.querySelector("summary").append(
+			el("button", {
+				type: "button",
+				class: "open undo",
+				text: t("undo"),
+				title: t("undoTitle"),
+				onclick: (e) => {
+					e.preventDefault();
+					if (busy) return note(t("busy"), "warning");
+					sendMessage(`/undo ${jid}`);
+				},
+			}),
+		);
+	}
 }
 
 function attachCopyButtons(root) {
@@ -596,7 +659,7 @@ function renderAssistantFinal(message, msg = startAssistant()) {
 		);
 		msg.box.append(actions);
 	}
-	if (message.stopReason === "error" && message.errorMessage) msg.box.append(el("div", { class: "note error", text: message.errorMessage }));
+	if (message.stopReason === "error" && message.errorMessage) msg.box.append(errorNote(message.errorMessage));
 	if (message.stopReason === "aborted") msg.box.append(el("div", { class: "note", text: t("stopped") }));
 	if (!msg.box.children.length) msg.box.remove();
 	scrollDown();
@@ -907,44 +970,94 @@ async function openModels() {
 	const setLink = () => {
 		const p = providers.find((x) => x.id === sel.value);
 		link.href = p?.url ?? "#";
+		const free = { google: "freeGoogle", openrouter: "freeOpenRouter" }[sel.value];
+		$("login-free").hidden = !free;
+		$("login-free").textContent = free ? t(free) : "";
+		$("login-where").textContent = p?.where ? t(`where_${p.where}`) : "";
 	};
 	sel.onchange = setLink;
 	setLink();
 	if (!dlg.open) dlg.showModal();
 	let models = [];
+	let recommended = [];
 	try {
-		models = (await api("/api/models")).models ?? [];
+		const data = await api("/api/models");
+		models = data.models ?? [];
+		recommended = data.recommended ?? [];
 	} catch (err) {
 		note(err.message, "error");
 	}
-	ul.replaceChildren();
-	if (!models.length) ul.append(el("li", { class: "empty-models", text: t("noModels") }));
 	const cur = state?.model ?? session?.model;
+	const specOf = (m) => `${m.provider}/${m.id}`;
 	const isCurrent = (m) => cur && cur.provider === m.provider && cur.id === m.id;
-	models.sort((a, b) => Number(isCurrent(b)) - Number(isCurrent(a)) || `${a.provider}/${a.id}`.localeCompare(`${b.provider}/${b.id}`));
-	for (const m of models) {
-		const isCur = cur && cur.provider === m.provider && cur.id === m.id;
-		ul.append(
+	const available = new Set(models.map(specOf));
+	// Recommended for this mode first (also when the provider has no key yet), then the rest.
+	const mine = recommended.filter((r) => r.modes.includes(mode()));
+	const recSpecs = new Set(mine.map((r) => r.spec));
+	const others = models
+		.filter((m) => !recSpecs.has(specOf(m)))
+		.sort((a, b) => Number(isCurrent(b)) - Number(isCurrent(a)) || specOf(a).localeCompare(specOf(b)));
+	const choose = async (m) => {
+		if (busy) return note(t("busy"), "warning");
+		try {
+			await api("/api/model", { provider: m.provider, id: m.id, both: $("model-both").checked });
+			dlg.close();
+		} catch (err) {
+			note(err.message, "error");
+		}
+	};
+	const row = (m, rec) => {
+		const spec = specOf(m);
+		const can = available.has(spec);
+		const label = providers.find((p) => p.id === m.provider)?.label ?? m.provider;
+		return el(
+			"li",
+			{ "data-spec": spec.toLowerCase() },
 			el(
-				"li",
-				{},
-				el("button", {
+				"button",
+				{
 					type: "button",
-					class: isCur ? "current" : "",
-					text: `${m.provider}/${m.id}`,
-					onclick: async () => {
-						if (busy) return note(t("busy"), "warning");
-						try {
-							await api("/api/model", { provider: m.provider, id: m.id, both: $("model-both").checked });
-							dlg.close();
-						} catch (err) {
-							note(err.message, "error");
+					class: [isCurrent(m) ? "current" : "", rec ? "rec" : "", can ? "" : "needs-key"].join(" ").trim(),
+					// Without a key, the click goes to the form below: that provider, and the key field.
+					onclick: () => {
+						if (can) return choose(m);
+						if (providers.some((p) => p.id === m.provider)) {
+							sel.value = m.provider;
+							setLink();
 						}
+						$("login-key").focus();
 					},
-				}),
+				},
+				el("span", { class: "model-name", text: spec }),
+				rec ? el("span", { class: "model-tag", text: t(`rec_${rec.why}`) }) : null,
+				rec && !can ? el("span", { class: "model-why", text: t("needsKey", { x: label }) }) : null,
 			),
 		);
-	}
+	};
+	const search = $("model-search");
+	const render = () => {
+		const q = search.value.trim().toLowerCase().split(/\s+/).filter(Boolean);
+		const hit = (spec) => q.every((w) => spec.toLowerCase().includes(w));
+		const recRows = mine.filter((r) => hit(r.spec)).map((r) => {
+			const i = r.spec.indexOf("/");
+			return row({ provider: r.spec.slice(0, i), id: r.spec.slice(i + 1) }, r);
+		});
+		const rest = others.filter((m) => hit(specOf(m))).map((m) => row(m, null));
+		ul.replaceChildren();
+		if (recRows.length) ul.append(el("li", { class: "models-group", text: t("recommended") }), ...recRows);
+		if (rest.length) ul.append(el("li", { class: "models-group", text: t(recRows.length ? "otherModels" : "allModels") }), ...rest);
+		if (!recRows.length && !rest.length) ul.append(el("li", { class: "empty-models", text: models.length ? t("noMatch") : t("noModels") }));
+	};
+	search.value = "";
+	search.oninput = render;
+	search.onkeydown = (e) => {
+		if (e.key === "Enter") {
+			e.preventDefault();
+			ul.querySelector("button:not(.needs-key)")?.click();
+		}
+	};
+	render();
+	search.focus();
 }
 
 $("login-form")?.addEventListener("submit", async (e) => {

package/web/i18n.js

@@ -45,6 +45,16 @@ export const STRINGS = {
 		modelTitleResearcher: "Model for the Researcher",
 		modelTitleLibrarian: "Model for the Librarian",
 		chooseModel: "Choose a model",
+		searchModels: "Search, e.g. flash or openrouter free",
+		recommended: "Recommended for this mode",
+		otherModels: "Other models",
+		allModels: "All models",
+		noMatch: "No model matches.",
+		rec_tested: "tested default",
+		rec_cheaper: "tested, cheaper",
+		rec_free: "tested, free",
+		rec_eu: "tested, EU",
+		needsKey: "needs a key from {x}",
 		noModels: "No models yet. Connect a provider below.",
 		connectProvider: "Connect a provider",
 		provider: "Provider",
@@ -52,6 +62,25 @@ export const STRINGS = {
 		save: "Save",
 		getKey: "Get a key",
 		keyNote: "The key is saved on this computer, in Sub-Sub's settings folder, and is sent only to that provider.",
+		freeGoogle: "Free to try: a Google AI Studio key needs no card. The free tier limits the text sent each minute and the requests each day, enough to try Sub-Sub, and gemini-3.1-flash-lite is the tested free model. You must be 18 or older. In the EU, the UK and Switzerland, Google does not use your prompts to improve its products; elsewhere, on the free tier, it may.",
+		freeOpenRouter: "Free to try: models whose names end in :free cost nothing, with 50 requests a day (1000 after you buy 10 dollars of credit). The providers of some free models may keep your prompts.",
+		trouble_quota: "The model provider refused the request: a limit of your account was reached. Free tiers limit the text sent each minute and the requests each day. Wait a minute and ask Sub-Sub to continue; if it happens again, the daily limit is used up (it resets the next day). Or choose another model with the model button.",
+		trouble_busy: "The model provider is busy at the moment. Try again in a few minutes, or choose another model with the model button.",
+		trouble_blocked: "The model provider stopped the reply (for example, because it repeated a source word for word). Ask again in other words, or choose another model.",
+		trouble_key: "The model provider did not accept the API key. Enter it again with the model button.",
+		details: "Details",
+		undo: "Undo",
+		where_eu: "Where your data goes: servers in the European Union. Covered by the GDPR, the choice for material you would not send outside the EU.",
+		where_us: "Where your data goes: servers outside the EU, mostly in the United States, under the provider's terms for the EU. Read them before you send unpublished or sensitive material.",
+		where_cn: "Where your data goes: servers in China. Do not send unpublished or sensitive material.",
+		where_varies: "Where your data goes: it depends on the model. Each model runs at another company, in the United States, China or elsewhere. For material you would not send outside the EU, choose Mistral.",
+		setupTitle: "Before you start",
+		stepZotero: "Zotero is open and lets Sub-Sub in. If not: start Zotero, then in Settings > Advanced turn on \"Allow other applications on this computer to communicate with Zotero\".",
+		stepModel: "A model is connected. If not: select Connect and paste an API key. To try Sub-Sub for free, choose Google Gemini and get a free key there.",
+		stepServers: "The Zotero servers are running. If not ({x}): close Sub-Sub, open a terminal and type subsub doctor. Each line marked FIX says what to do.",
+		stepDone: "done",
+		stepTodo: "to do",
+		undoTitle: "Undo this change. Sub-Sub shows what it would restore before it changes anything.",
 		oauthNote: "To sign in through a provider's website (for example with a subscription), open a terminal, type subsub, then /login.",
 		saving: "Saving",
 		saved: "Saved.",
@@ -140,6 +169,16 @@ export const STRINGS = {
 		modelTitleResearcher: "Modelo do Investigador",
 		modelTitleLibrarian: "Modelo do Bibliotecário",
 		chooseModel: "Escolha um modelo",
+		searchModels: "Pesquisar, por exemplo flash ou openrouter free",
+		recommended: "Recomendados para este modo",
+		otherModels: "Outros modelos",
+		allModels: "Todos os modelos",
+		noMatch: "Nenhum modelo corresponde.",
+		rec_tested: "testado, por omissão",
+		rec_cheaper: "testado, mais barato",
+		rec_free: "testado, gratuito",
+		rec_eu: "testado, UE",
+		needsKey: "precisa de uma chave de {x}",
 		noModels: "Ainda não há modelos. Ligue um fornecedor abaixo.",
 		connectProvider: "Ligar um fornecedor",
 		provider: "Fornecedor",
@@ -147,6 +186,25 @@ export const STRINGS = {
 		save: "Guardar",
 		getKey: "Obter uma chave",
 		keyNote: "A chave fica guardada neste computador, na pasta de definições do Sub-Sub, e só é enviada a esse fornecedor.",
+		freeGoogle: "Para experimentar sem pagar: uma chave do Google AI Studio não pede cartão. O nível gratuito limita o texto enviado por minuto e os pedidos por dia, o que chega para experimentar o Sub-Sub; o modelo gratuito testado é o gemini-3.1-flash-lite. Tem de ter 18 anos ou mais. Na UE, no Reino Unido e na Suíça, a Google não usa os seus pedidos para melhorar os produtos; noutros países, no nível gratuito, pode usar.",
+		freeOpenRouter: "Para experimentar sem pagar: os modelos cujo nome termina em :free não custam nada, com 50 pedidos por dia (1000 depois de comprar 10 dólares de crédito). Os fornecedores de alguns modelos gratuitos podem guardar os seus pedidos.",
+		trouble_quota: "O fornecedor do modelo recusou o pedido: atingiu um limite da sua conta. Os níveis gratuitos limitam o texto enviado por minuto e os pedidos por dia. Espere um minuto e peça ao Sub-Sub para continuar; se voltar a acontecer, esgotou o limite diário (renova-se no dia seguinte). Ou escolha outro modelo no botão do modelo.",
+		trouble_busy: "O fornecedor do modelo está sobrecarregado neste momento. Tente outra vez dentro de alguns minutos ou escolha outro modelo no botão do modelo.",
+		trouble_blocked: "O fornecedor do modelo interrompeu a resposta (por exemplo, por repetir uma fonte palavra por palavra). Peça outra vez por outras palavras ou escolha outro modelo.",
+		trouble_key: "O fornecedor do modelo não aceitou a chave da API. Volte a introduzi-la no botão do modelo.",
+		details: "Detalhes",
+		undo: "Anular",
+		where_eu: "Para onde vão os seus dados: servidores na União Europeia. Abrangidos pelo RGPD; a escolha para material que não enviaria para fora da UE.",
+		where_us: "Para onde vão os seus dados: servidores fora da UE, sobretudo nos Estados Unidos, com os termos do fornecedor para a UE. Leia-os antes de enviar material inédito ou sensível.",
+		where_cn: "Para onde vão os seus dados: servidores na China. Não envie material inédito ou sensível.",
+		where_varies: "Para onde vão os seus dados: depende do modelo. Cada modelo funciona noutra empresa, nos Estados Unidos, na China ou noutro país. Para material que não enviaria para fora da UE, escolha a Mistral.",
+		setupTitle: "Antes de começar",
+		stepZotero: "O Zotero está aberto e deixa o Sub-Sub entrar. Se não: abra o Zotero e, em Definições > Avançado, ative \"Allow other applications on this computer to communicate with Zotero\".",
+		stepModel: "Há um modelo ligado. Se não: selecione Ligar e cole uma chave de API. Para experimentar sem pagar, escolha Google Gemini e obtenha lá uma chave gratuita.",
+		stepServers: "Os servidores do Zotero estão a funcionar. Se não ({x}): feche o Sub-Sub, abra um terminal e escreva subsub doctor. Cada linha marcada FIX diz o que fazer.",
+		stepDone: "feito",
+		stepTodo: "por fazer",
+		undoTitle: "Anular esta alteração. O Sub-Sub mostra o que repõe antes de alterar alguma coisa.",
 		oauthNote: "Para entrar através do site de um fornecedor (por exemplo, com uma subscrição), abra um terminal, escreva subsub e depois /login.",
 		saving: "A guardar",
 		saved: "Guardado.",

package/web/index.html

@@ -111,6 +111,7 @@
 		</div>
 		<h3 data-i18n="chooseModel">Choose a model</h3>
 		<label class="check"><input type="checkbox" id="model-both"> <span data-i18n="forBoth">Use it in both modes</span></label>
+		<input type="search" id="model-search" class="model-search" data-i18n-placeholder="searchModels" placeholder="Search models" autocomplete="off" spellcheck="false">
 		<ul class="models" id="models"></ul>
 		<h3 data-i18n="connectProvider">Connect a provider</h3>
 		<form id="login-form" class="login">
@@ -121,6 +122,8 @@
 				<input type="password" id="login-key" autocomplete="off" spellcheck="false" required>
 			</label>
 			<p class="small"><a id="login-link" href="#" target="_blank" rel="noopener noreferrer" data-i18n="getKey">Get a key</a></p>
+			<p class="small muted" id="login-where"></p>
+			<p class="small free-note" id="login-free" hidden></p>
 			<p class="small muted" data-i18n="keyNote"></p>
 			<div class="modal-buttons"><button type="submit" class="primary" id="login-save" data-i18n="save">Save</button></div>
 			<p class="small muted" data-i18n="oauthNote"></p>