omp-onlyne 0.0.0-stage → 0.2.0

package/src/ui/format.ts

@@ -0,0 +1,56 @@
+import { truncateToWidth } from "@oh-my-pi/pi-tui";
+import { t } from "./bootstrap-text.ts";
+
+/** Collapse a body to one line without losing the first useful characters. */
+export function oneLine(text: string): string {
+	return text.replace(/\s+/g, " ").trim();
+}
+
+/** Short elapsed time for a queue row, computed when the snapshot is loaded. */
+export function ageText(at: string | undefined, now = Date.now()): string {
+	if (at === undefined) return "";
+	const time = Date.parse(at);
+	if (!Number.isFinite(time)) return "";
+	const seconds = Math.max(0, Math.floor((now - time) / 1000));
+	if (seconds < 60) return `${seconds}s`;
+	const minutes = Math.floor(seconds / 60);
+	if (minutes < 60) return `${minutes}m`;
+	const hours = Math.floor(minutes / 60);
+	if (hours < 48) return `${hours}h`;
+	return `${Math.floor(hours / 24)}d`;
+}
+
+export function clockText(at: string): string {
+	const time = Date.parse(at);
+	if (!Number.isFinite(time)) return at;
+	return new Date(time).toLocaleTimeString(undefined, { hour: "2-digit", minute: "2-digit" });
+}
+
+/**
+ * How long ago something happened, in words. `ageText` is the compact column
+ * form (`12m`), which stays untranslated because the unit letter is the whole
+ * label; a sentence needs the unit spelled out in the reader's language. The
+ * first minute reads "just now", since "0 min ago" is not what anyone says.
+ */
+export function sinceText(at: string | undefined, now = Date.now()): string {
+	if (at === undefined) return "";
+	const time = Date.parse(at);
+	if (!Number.isFinite(time)) return "";
+	const seconds = Math.max(0, Math.floor((now - time) / 1000));
+	if (seconds < 60) return t("time.justNow");
+	const minutes = Math.floor(seconds / 60);
+	if (minutes < 60) return t("time.minutesAgo", { count: minutes });
+	const hours = Math.floor(minutes / 60);
+	if (hours < 48) return t("time.hoursAgo", { count: hours });
+	return t("time.daysAgo", { count: Math.floor(hours / 24) });
+}
+
+/** The head of a thread alias: its first UUID segment, which is what a narrow row can afford. */
+export function shortAlias(alias: string): string {
+	const head = alias.split("-", 1)[0] ?? alias;
+	return head === "" ? alias : head;
+}
+
+export function fit(text: string, width: number): string {
+	return truncateToWidth(text, Math.max(0, width));
+}

package/src/ui/index.ts

@@ -0,0 +1,156 @@
+import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
+import { ConfigError, loadConfig } from "../config.ts";
+import { getRuntime, startRuntime } from "../runtime.ts";
+import { detectTernSession } from "../tern.ts";
+import type { OnlyneConfig } from "../types.ts";
+import { OnlyneBootstrap, type BootstrapDefaults } from "./bootstrap.ts";
+import { OnlyneViewer } from "./viewer.ts";
+import { LOCALES, setLocale, type Locale } from "@onlyne/node-host/i18n";
+import { saveConfig } from "../config.ts";
+import { commandText as t } from "./command-text.ts";
+import { registerMsgTool } from "../tool.ts";
+import { refreshMailCards } from "./mail-message.ts";
+
+export { attachStatus, OnlyneStatus } from "./status.ts";
+
+/** The subcommands the slash command accepts, with the one-line hint the editor shows. */
+const SUBCOMMANDS = ["init", "config", "menu", "language"] as const;
+
+export function registerUi(pi: ExtensionAPI): void {
+	let active: AbortController | undefined;
+	const cancel = (): void => {
+		active?.abort();
+		active = undefined;
+	};
+	pi.on("session_switch", cancel);
+	pi.on("session_branch", cancel);
+	pi.on("session_tree", cancel);
+	pi.on("session_shutdown", cancel);
+
+	pi.registerCommand("onlyne", {
+		description: t("description"),
+		getArgumentCompletions(argumentPrefix: string) {
+			const prefix = argumentPrefix.trim().toLowerCase();
+			const matches = SUBCOMMANDS.filter(item => item.startsWith(prefix));
+			return matches.length === 0 ? null : matches.map(item => ({ label: item, value: item, description: t(item) }));
+		},
+		handler: async (args, ctx) => {
+			const command = args.trim();
+			if (command === "language" || command.startsWith("language ")) {
+				const language = command.slice("language".length).trim();
+				if (!LOCALES.includes(language as Locale)) { ctx.ui.notify(t("usage"), "warning"); return; }
+				try {
+					const runtime = getRuntime();
+					const config = runtime?.config ?? await loadConfig(ctx.cwd);
+					await saveConfig({ ...config, language: language as Locale });
+					if (runtime !== undefined) runtime.config.language = language as Locale;
+					setLocale(language as Locale);
+					registerMsgTool(pi);
+					refreshMailCards();
+					ctx.ui.notify(t("selected", { language }), "info");
+				} catch (error) { ctx.ui.notify(error instanceof Error ? error.message : String(error), "error"); }
+				return;
+			}
+			if (command !== "" && command !== "init" && command !== "config" && command !== "menu" && command !== "settings") {
+				ctx.ui.notify(t("usage"), "warning");
+				return;
+			}
+			if (!ctx.hasUI) {
+				pi.sendMessage({
+					customType: "onlyne.ui-unavailable",
+					content: t("unavailable"),
+					display: true,
+					attribution: "agent",
+				});
+				return;
+			}
+			if (active !== undefined) return;
+			const controller = new AbortController();
+			active = controller;
+			try {
+				let runtime = getRuntime();
+				if (command === "init") {
+					const existing = runtime?.config ?? (await loadConfig(ctx.cwd).catch(() => undefined));
+					if (existing !== undefined) {
+						ctx.ui.notify(t("configured"), "info");
+						return;
+					}
+				}
+				// A saved config with the runtime down is not a first run: start the node and show
+				// the viewer. Opening the init form here is what made `/onlyne` look like it had
+				// cleared the project.
+				if (runtime === undefined && command !== "init" && command !== "config") {
+					try {
+						runtime = await startRuntime(pi, ctx);
+					} catch (error) {
+						if (!(error instanceof ConfigError && error.code === "missing")) throw error;
+					}
+				}
+				const needsBootstrap = command === "init" || command === "config" || command === "settings" || runtime === undefined;
+				if (needsBootstrap) {
+					const tern = detectTernSession();
+					const current = runtime?.config ?? (await loadConfig(ctx.cwd).catch(() => undefined));
+					const savedRegion = current?.region;
+					const regionSource = savedRegion !== undefined
+						? t("savedRegion")
+						: tern === undefined
+							? t("noTern")
+							: t("ternRegion", { name: tern });
+					const defaults: BootstrapDefaults = {
+						region: savedRegion ?? tern ?? "",
+						regionSource,
+						nodeId: current?.node.id ?? "",
+						bind: current?.server.bind ?? "127.0.0.1",
+						keyScope: current?.node.key_scope ?? "project",
+						pageSize: current?.threads.page_size ?? 50,
+						...(current === undefined ? {} : { current }),
+					};
+					await ctx.ui.custom<void>(
+						(tui, theme, _keys, done) =>
+							new OnlyneBootstrap(
+								pi,
+								ctx,
+								defaults,
+								theme,
+								() => tui.requestRender(),
+								() => done(),
+								controller.signal,
+							),
+						{
+							overlay: true,
+							overlayOptions: { anchor: "center", width: "70%", minWidth: 56, maxHeight: "85%" },
+							signal: controller.signal,
+						},
+					);
+				} else {
+					await ctx.ui.custom<void>(
+						(tui, theme, _keys, done) =>
+							new OnlyneViewer(
+								theme,
+								() => tui.requestRender(),
+								() => done(),
+								controller.signal,
+								() => tui.terminal.rows,
+							),
+						{
+							overlay: true,
+							// Fullscreen is what turns on pointer reporting: a normal overlay never gets mouse
+							// events, so every click on a described node would go nowhere. The alt screen also
+							// gives the sheet the whole pane, which the four columns need.
+							overlayOptions: { margin: 0, fullscreen: true },
+							signal: controller.signal,
+						},
+					);
+				}
+			} catch (error) {
+				if (!controller.signal.aborted) {
+					const message = error instanceof Error ? error.message : String(error);
+					pi.logger.warn("onlyne.ui.failed", { error: message });
+					ctx.ui.notify(message, "error");
+				}
+			} finally {
+				if (active === controller) active = undefined;
+			}
+		},
+	});
+}

package/src/ui/mail-message.ts

@@ -0,0 +1,263 @@
+import type { MessageRenderer } from "@oh-my-pi/pi-coding-agent";
+import { getLocale } from "@onlyne/node-host/i18n";
+import { Markdown, Text, getMarkdownTheme, node, span, text, type Component, type NativeNode, type Theme, type TspSpan } from "@oh-my-pi/pi-tui";
+import type { HistoryMessage, MessageRef, ThreadRef } from "@onlyne/lib";
+import { shortNodeId } from "../config.ts";
+import { getRuntime, type PluginRuntime } from "../runtime.ts";
+import { conversationPath, messagePath } from "../urls.ts";
+import { t } from "./bootstrap-text.ts";
+
+export interface OnlyneMessageDetails {
+	thread_ref: ThreadRef;
+	seq: string;
+	message_ref: MessageRef;
+	/** What the payload can attest: this entry reached this node's inbox. */
+	delivery: string;
+	/** The submission-time consumption fact; the confirmed one is read from history. */
+	consumption: string;
+	mail?: {
+		from: string;
+		at: string;
+		subject: string;
+		body: string;
+		relation?: "reply" | "followup";
+		in_reply_to?: MessageRef;
+	};
+}
+
+/** What the card reports about one message: the live history row, or why it could not read one. */
+interface CardStatus {
+	delivery: string;
+	consumption?: string;
+	error?: string;
+}
+
+/**
+ * The cards currently in a transcript. A message renderer is handed no TUI handle, so the
+ * cards hold themselves weakly and share one subscription: a rebuilt transcript drops its old
+ * components without leaking listeners.
+ */
+const cards = new Set<WeakRef<MailMessage>>();
+let watched: PluginRuntime | undefined;
+/** A status key this card never writes: clearing an unset key is a no-op that asks for a frame. */
+const REPAINT_KEY = "onlyne.mail";
+
+/**
+ * Ask the host to paint again. A message renderer receives no repaint callback, and the one
+ * host call that renders unconditionally is a status write; clearing a key this card never
+ * sets changes nothing on screen and still requests the frame.
+ */
+function repaint(): void {
+	try {
+		getRuntime()?.main.ui.setStatus(REPAINT_KEY, undefined);
+	} catch {
+		// A closed session has no status line; the next host paint still shows the new state.
+	}
+}
+
+/** One subscription per runtime: a card refreshes when the node reports a lifecycle change. */
+function watch(): void {
+	const runtime = getRuntime();
+	if (runtime === undefined || watched === runtime) return;
+	watched = runtime;
+	runtime.onChange(() => refreshMailCards());
+}
+
+/**
+ * Re-read every card still in a transcript. A consumption is recorded without a notification
+ * of its own, so the host calls this when it confirms one.
+ */
+export function refreshMailCards(): void {
+	for (const reference of cards) {
+		const card = reference.deref();
+		if (card === undefined) cards.delete(reference);
+		else void card.refresh();
+	}
+}
+
+class MailMessage implements Component {
+	private status: CardStatus;
+	private native: NativeNode | undefined;
+	private headers: Text | undefined;
+	private footer: Text | undefined;
+	private rendered: readonly string[] | undefined;
+	private refreshing = false;
+	private readonly body: Markdown;
+	private locale = getLocale();
+
+	constructor(
+		private readonly details: OnlyneMessageDetails,
+		private readonly kind: string,
+		private readonly theme: Theme,
+	) {
+		this.body = new Markdown(details.mail?.body ?? "", 0, 0, getMarkdownTheme());
+		this.status = { delivery: details.delivery, consumption: details.consumption };
+		cards.add(new WeakRef(this));
+		watch();
+		void this.refresh();
+	}
+
+	/** Read the message's own row: delivery and consumption are facts, not a guess from the card. */
+	async refresh(): Promise<void> {
+		const runtime = getRuntime();
+		if (runtime === undefined || this.refreshing) return;
+		this.refreshing = true;
+		let next: CardStatus;
+		try {
+			const row: HistoryMessage = await runtime.node.history.message(runtime.node.auth, this.details.message_ref);
+			next = { delivery: row.delivery, ...(row.consumption === undefined ? {} : { consumption: row.consumption }) };
+		} catch (error) {
+			// A failed read is reported as unknown; claiming a state the card cannot see is worse.
+			next = { delivery: "unknown", error: error instanceof Error ? error.message : String(error) };
+		} finally {
+			this.refreshing = false;
+		}
+		if (next.delivery === this.status.delivery && next.consumption === this.status.consumption && next.error === this.status.error) return;
+		this.status = next;
+		this.native = undefined;
+		this.headers = undefined;
+		this.footer = undefined;
+		this.rendered = undefined;
+		repaint();
+	}
+
+	describe(): NativeNode {
+		this.dropLocaleCaches();
+		return this.native ??= this.describeCard();
+	}
+
+	render(width: number): readonly string[] {
+		this.dropLocaleCaches();
+		if (this.rendered !== undefined) return this.rendered;
+		const mail = this.details.mail;
+		if (mail === undefined) return this.rendered = [];
+		const rule = "─".repeat(Math.max(0, Math.min(width, 72)));
+		this.headers ??= new Text(this.headerLines(), 0, 0);
+		this.footer ??= new Text(this.theme.fg("muted", `${this.label()} · #${this.details.seq}\n${messagePath(this.details.message_ref)}`), 0, 0);
+		return this.rendered = [...this.headers.render(width), rule, "", ...this.body.render(width), "", rule, ...this.footer.render(width)];
+	}
+
+	invalidate(): void {
+		this.native = undefined;
+		this.headers = undefined;
+		this.footer = undefined;
+		this.rendered = undefined;
+		this.body.invalidate();
+	}
+
+	private label(): string {
+		return this.kind === "onlyne.supplement"
+			? t("mail.supplement")
+			: this.kind === "onlyne.routing"
+				? t("mail.routing")
+				: t("mail.letter");
+	}
+
+	private heading(): string {
+		const subject = (this.details.mail?.subject ?? "").replace(/[\r\n]+/g, " ");
+		return `${this.details.mail?.relation === "reply" ? "Re: " : ""}${subject}`;
+	}
+
+	private headerLines(): string {
+		const mail = this.details.mail;
+		if (mail === undefined) return "";
+		const fields = [
+			`${this.theme.fg("muted", `${t("mail.from")}:`)} ${shortNodeId(mail.from)} <${mail.from}>`,
+			`${this.theme.fg("muted", `${t("mail.date")}:`)} ${mail.at}`,
+			`${this.theme.fg("muted", `${t("mail.thread")}:`)} ${this.details.thread_ref.owner}/${this.details.thread_ref.id} #${this.details.seq}`,
+			...(mail.relation === undefined ? [] : [`${this.theme.fg("muted", `${t("mail.relation")}:`)} ${mail.relation}`]),
+			...(mail.in_reply_to === undefined
+				? []
+				: [`${this.theme.fg("muted", `${t("mail.inReplyTo")}:`)} ${mail.in_reply_to.sender}/${mail.in_reply_to.id}`]),
+			`${this.theme.fg("muted", `${t("mail.delivery")}:`)} ${this.status.delivery}${
+				this.status.consumption === undefined ? "" : t("mail.consumed", { state: this.status.consumption })
+			}`,
+			...(this.status.error === undefined
+				? []
+				: [`${this.theme.fg("muted", `${t("mail.status")}:`)} unknown (${this.status.error})`]),
+		];
+		return [this.theme.fg("accent", this.theme.bold(this.heading())), ...fields].join("\n");
+	}
+
+	/**
+	 * The mailing-list card: the header block a letter carries, the body, then the two ways to
+	 * read this message again. Every link names a route this node serves, and one that does
+	 * not resolve is not offered.
+	 */
+	private describeCard(): NativeNode {
+		const mail = this.details.mail;
+		if (mail === undefined) return text([span("onlyne", "muted mono")]);
+		const messageHref = messagePath(this.details.message_ref);
+		const replyHref = mail.in_reply_to === undefined ? undefined : messagePath(mail.in_reply_to);
+		const fields: Array<{ k: string; v: TspSpan[] }> = [
+			{
+				k: t("mail.from"),
+				v: [
+					span(shortNodeId(mail.from), "link mono", { href: `onlyne://neighbors/${encodeURIComponent(mail.from)}` }),
+					span(` <${mail.from}>`, "muted mono"),
+				],
+			},
+			{ k: t("mail.date"), v: [span(mail.at, "mono")] },
+			{
+				k: t("mail.thread"),
+				// Both segments are encoded, so a URN owner stays one segment of the route.
+				v: [
+					span(`${this.details.thread_ref.owner}/${this.details.thread_ref.id}`, "link mono", {
+						href: `onlyne://threads/${encodeURIComponent(this.details.thread_ref.owner)}/${encodeURIComponent(this.details.thread_ref.id)}`,
+					}),
+					span(` #${this.details.seq}`, "muted mono"),
+				],
+			},
+			...(mail.relation === undefined ? [] : [{ k: t("mail.relation"), v: [span(mail.relation, "mono")] }]),
+			...(mail.in_reply_to === undefined || replyHref === undefined
+				? []
+				: [{
+						k: t("mail.inReplyTo"),
+						v: [span(`${mail.in_reply_to.sender}/${mail.in_reply_to.id}`, "link mono", { href: replyHref })],
+					}]),
+			{
+				k: t("mail.delivery"),
+				v: [
+					span(this.status.delivery, this.status.delivery === "received" ? "mono" : "warning mono"),
+					...(this.status.consumption === undefined
+						? []
+						: [span(t("mail.consumed", { state: this.status.consumption }), "mono")]),
+				],
+			},
+			...(this.status.error === undefined
+				? []
+				: [{ k: t("mail.status"), v: [span(`unknown (${this.status.error})`, "warning mono")] }]),
+		];
+		return node("card", {
+			role: "onlyne.mail",
+			head: [span("[onlyne] ", "muted mono"), span(this.heading(), "strong")],
+		}, [
+			node("kv", { layout: "grid", items: fields.map(field => ({ k: [span(`${field.k}:`, "muted mono")], v: field.v })) }),
+			node("rule"),
+			node("md", { text: mail.body }),
+			node("rule"),
+			text([
+				span(`${this.label()} · #${this.details.seq} · `, "muted mono"),
+				span(t("mail.rawRecord"), "link mono", { href: messageHref }),
+				span(" · ", "muted mono"),
+				span(t("mail.wholeThread"), "link mono", { href: conversationPath(this.details.message_ref) }),
+			], { wrap: "word" }),
+		]);
+	}
+
+	/** A locale switch rewrites every label, so the frame caches of the old locale are dropped. */
+	private dropLocaleCaches(): void {
+		const locale = getLocale();
+		if (locale === this.locale) return;
+		this.locale = locale;
+		this.native = undefined;
+		this.headers = undefined;
+		this.footer = undefined;
+		this.rendered = undefined;
+	}
+}
+
+export const renderMailMessage: MessageRenderer<OnlyneMessageDetails> = (message, _options, theme) => {
+	if (message.details?.mail === undefined) return undefined;
+	return new MailMessage(message.details, message.customType, theme);
+};

package/src/ui/status.ts

@@ -0,0 +1,213 @@
+import type { ExtensionContext } from "@oh-my-pi/pi-coding-agent";
+import { getLocale } from "@onlyne/node-host/i18n";
+import {
+	type Component,
+	type NativeNode,
+	node,
+	span,
+	text as textNode,
+	type Theme,
+} from "@oh-my-pi/pi-tui";
+import { getRuntime, type PluginRuntime } from "../runtime.ts";
+import type { OnlyneStatus as OnlyneStatusSnapshot } from "../types.ts";
+import { shortNodeId } from "../config.ts";
+import { t } from "./bootstrap-text.ts";
+import { fit, oneLine } from "./format.ts";
+
+const REGION_PREFIX = "urn:onlyne:region:";
+const REFRESH_MS = 2_000;
+const WIDGET_KEY = "onlyne";
+
+/** A region URI is stored for stability; the row shows the short name the user typed. */
+function regionLabel(region: string): string {
+	if (!region.startsWith(REGION_PREFIX)) return region;
+	const name = region.slice(REGION_PREFIX.length);
+	try {
+		return decodeURIComponent(name);
+	} catch {
+		return name;
+	}
+}
+
+/** One `label value` module of the status row. */
+interface Module {
+	label: string;
+	value: string;
+	tone?: string;
+}
+
+/**
+ * One fixed row above the editor: region, node and neighbor counts, pending
+ * alerts and unread messages. The modules are laid out across the full width
+ * (`justify: between`), never left-aligned; the separators are layout gaps, not
+ * drawn characters. `render` and `describe` project the same modules, so the
+ * ANSI row and the Tern card cannot disagree, and neither repeats the line.
+ */
+export class OnlyneStatus implements Component {
+	private readonly theme: Theme;
+	private readonly requestRender: () => void;
+	private runtime: PluginRuntime | undefined;
+	private snapshot: OnlyneStatusSnapshot | undefined;
+	private unsubscribe: (() => void) | undefined;
+	private timer: Timer | undefined;
+	private disposed = false;
+	private refreshing = false;
+	private row: string | undefined;
+	private rows: readonly string[] | undefined;
+	private described: NativeNode | undefined;
+	private locale = getLocale();
+
+	constructor(theme: Theme, requestRender: () => void) {
+		this.theme = theme;
+		this.requestRender = requestRender;
+		void this.refresh();
+		this.timer = setInterval(() => void this.refresh(), REFRESH_MS);
+	}
+
+	/** Re-read the runtime and its status; a restart is a new runtime object and a new subscription. */
+	private async refresh(): Promise<void> {
+		if (this.disposed || this.refreshing) return;
+		this.refreshing = true;
+		try {
+			const runtime = getRuntime();
+			if (runtime !== this.runtime) {
+				this.unsubscribe?.();
+				this.unsubscribe = undefined;
+				this.runtime = runtime;
+				if (runtime !== undefined) this.unsubscribe = runtime.onChange(() => void this.refresh());
+			}
+			const next = await runtime?.status();
+			if (this.disposed) return;
+			// The rendered row is the whole observable state, so an identical row needs no repaint.
+			const before = this.modules();
+			this.snapshot = next;
+			if (JSON.stringify(before) !== JSON.stringify(this.modules())) this.changed();
+		} catch {
+			// The status read is best effort: keep the last good row instead of throwing into the host.
+		} finally {
+			this.refreshing = false;
+		}
+	}
+
+	private changed(): void {
+		if (this.disposed) return;
+		this.row = undefined;
+		this.rows = undefined;
+		this.described = undefined;
+		this.requestRender();
+	}
+
+	private modules(): Module[] {
+		const snapshot = this.snapshot;
+		if (snapshot === undefined) {
+			return this.runtime === undefined
+				? [{ label: "onlyne", value: t("status.unconfigured"), tone: "warning" }]
+				: [{ label: "onlyne", value: t("status.starting"), tone: "muted" }];
+		}
+		const modules: Module[] = [
+			{ label: t("status.nodes"), value: String(snapshot.nodes) },
+			{ label: t("status.neighbors"), value: String(snapshot.neighbors) },
+			{ label: t("status.alert"), value: String(snapshot.alerts) },
+			{ label: t("status.unread"), value: String(snapshot.unread) },
+		];
+		if (snapshot.discovery_error !== undefined) {
+			modules.push({ label: t("status.discovery"), value: oneLine(snapshot.discovery_error), tone: "warning" });
+		}
+		return modules;
+	}
+
+	/** The node id and region lead the row; without a runtime there is nothing to lead with. */
+	private lead(): { text: string; tone: string } {
+		const snapshot = this.snapshot;
+		if (snapshot === undefined) return { text: "", tone: "muted" };
+		const parts = [shortNodeId(snapshot.node_id), regionLabel(snapshot.region)].filter(part => part !== "");
+		return { text: parts.join(" · "), tone: "accent strong" };
+	}
+
+	/** ANSI: one row with the modules spread across the width, region pinned left. */
+	render(width: number): readonly string[] {
+		this.dropLocaleCaches();
+		const lead = this.lead();
+		const cells = this.modules().map(module => `${module.label} ${module.value}`);
+		const head = lead.text === "" ? "" : `${lead.text}  `;
+		// Even columns over the remaining width, so the modules are spread out rather than left-aligned.
+		const each = cells.length === 0 ? 0 : Math.max(1, Math.floor(Math.max(0, width - head.length) / cells.length));
+		let row = head;
+		for (const [index, cell] of cells.entries()) {
+			row += " ".repeat(index === 0 ? 0 : Math.max(0, each - cells[index - 1]!.length)) + cell;
+		}
+		row = fit(row, width);
+		if (row === this.row && this.rows !== undefined) return this.rows;
+		this.row = row;
+		this.rows = [row];
+		return this.rows;
+	}
+
+	describe(): NativeNode {
+		this.dropLocaleCaches();
+		if (this.described !== undefined) return this.described;
+		const lead = this.lead();
+		const children: NativeNode[] = [];
+		if (lead.text !== "") {
+			children.push(textNode([span(lead.text, lead.tone)], { truncate: "end" }));
+		}
+		for (const module of this.modules()) {
+			children.push(
+				textNode([span(`${module.label} `, "muted"), span(module.value, module.tone ?? "strong")], { truncate: "end" }),
+			);
+		}
+		// A plain row, not a card: a card adds head/body chrome and a second visual row,
+		// which pushed the widget taller than the one line it is meant to occupy.
+		this.described = node(
+			"row",
+			{ role: "omp.widget.onlyne", justify: "between", align: "center", gap: "md" },
+			children,
+			"status",
+		);
+		return this.described;
+	}
+
+	/** A locale switch rewrites every label, so the frame caches of the old locale are dropped. */
+	private dropLocaleCaches(): void {
+		const locale = getLocale();
+		if (locale === this.locale) return;
+		this.locale = locale;
+		this.row = undefined;
+		this.rows = undefined;
+		this.described = undefined;
+	}
+
+	dispose(): void {
+		if (this.disposed) return;
+		this.disposed = true;
+		if (this.timer !== undefined) {
+			clearInterval(this.timer);
+			this.timer = undefined;
+		}
+		this.unsubscribe?.();
+		this.unsubscribe = undefined;
+		this.described = undefined;
+	}
+}
+
+/**
+ * Mount the status row above the editor. The returned cleanup removes the
+ * widget and stops the component's timer and runtime subscription.
+ */
+export function attachStatus(ctx: ExtensionContext): () => void {
+	let component: OnlyneStatus | undefined;
+	ctx.ui.setWidget(
+		WIDGET_KEY,
+		(tui, theme) => {
+			component?.dispose();
+			component = new OnlyneStatus(theme, () => tui.requestRender());
+			return component;
+		},
+		{ placement: "aboveEditor" },
+	);
+	return () => {
+		ctx.ui.setWidget(WIDGET_KEY, undefined);
+		component?.dispose();
+		component = undefined;
+	};
+}