Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.
TypeScript browser-shellcontrol-planefile-managerhomelabmobile-firstnextjsptyreactself-hostedserver-managementshadcn-uisysadmintailwindcssterminaltypescriptvpsweb-desktopweb-terminal
feat(tui): pin a pane slot without losing the cycle (#229)
Abdurrahman Fakhrul3e30ba3da9ac
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.mdindex 3c5e994b..07e04b3b 100644--- a/docs/CHANGELOG.md+++ b/docs/CHANGELOG.md@@ -8,7 +8,8 @@ this is the *what*, and it is what Settings → Account → About shows as “Wh**Added**-- `tui` a preferences registry, and settings that survive a restart+- `tui` pin a pane slot without losing the cycle+- `tui` a preferences registry, and settings that survive a restart (#231)- `tui` a vertical tab rail, from the same layout the horizontal row uses (#230)## 2026-11-01diff --git a/scripts/mso-agent-cmd-session.mjs b/scripts/mso-agent-cmd-session.mjsindex 9f46163e..ab0a5828 100644--- a/scripts/mso-agent-cmd-session.mjs+++ b/scripts/mso-agent-cmd-session.mjs@@ -70,18 +70,48 @@ export async function handlePane(ctx, args = []) {const kinds = paneKinds();if (!args.length) {const current = session?.paneKind || "off";+ // When pinned, do not advance the slot; report the pinned slot to the user.+ if (session?.panePinned) {+ print(`${colors.c || ""}side pane: ${current} (pinned)${colors.reset || ""}`);+ return "handled";+ }const next = cyclePane(current);if (session) session.paneKind = next;print(`${colors.c || ""}side pane: ${next}${colors.reset || ""}`);return "handled";}const requested = String(args[0]).toLowerCase();+ if (requested === "pin") {+ // Pin locks the active slot (or requested slot argument) so cycling does not move away.+ // When pane is off, default to the first slot so pinning always presents a visible pane.+ const slot = args[1] ? String(args[1]).toLowerCase() : null;+ let target = slot && kinds.includes(slot) && slot !== "off" ? slot : session?.paneKind;+ if (!target || target === "off") target = kinds[0] || "todos";+ if (session) {+ session.paneKind = target;+ session.panePinned = true;+ }+ print(`${colors.c || ""}side pane: ${target} (pinned)${colors.reset || ""}`);+ return "handled";+ }+ if (requested === "unpin") {+ // Unpin restores regular cycling without altering the currently visible slot.+ if (session) session.panePinned = false;+ const current = session?.paneKind || "off";+ print(`${colors.c || ""}side pane: ${current} (unpinned)${colors.reset || ""}`);+ return "handled";+ }if (kinds.includes(requested)) {- if (session) session.paneKind = requested;+ // Setting an explicit kind restores the standard non-pinned cycling behaviour.+ // Setting "off" clears both the pane and the pin because a hidden pin is invisible state.+ if (session) {+ session.paneKind = requested;+ session.panePinned = false;+ }print(`${colors.c || ""}side pane: ${requested}${colors.reset || ""}`);return "handled";}- print(`usage: /pane [todos|diff|files|off] (current: ${session?.paneKind || "off"})`);+ print(`usage: /pane [todos|diff|files|mcp|context|off|pin|unpin] (current: ${session?.paneKind || "off"})`);return "handled";}diff --git a/scripts/mso-agent-help.mjs b/scripts/mso-agent-help.mjsindex 7e2ff52e..62ce2e45 100644--- a/scripts/mso-agent-help.mjs+++ b/scripts/mso-agent-help.mjs@@ -16,7 +16,7 @@ export const HELP_LINES = [" /context alias for /status"," /diff [ref] [--full] show diff viewer panel for artifact write action"," /todos [--all] show session checklist from todo_write",- " /pane [kind] cycle or set side pane (todos, diff, files, off)",+ " /pane [kind|pin|unpin] cycle, set, or pin side pane (todos, diff, files, off)"," /keybind [sub] view keybindings (sub: reset, conflicts)"," /settings [key] [val] view or set TUI preferences (sub: reset)"," /compact force context compaction and archive history",diff --git a/scripts/mso-agent-pane-slots.test.ts b/scripts/mso-agent-pane-slots.test.tsnew file mode 100644index 00000000..9850e47e--- /dev/null+++ b/scripts/mso-agent-pane-slots.test.ts@@ -0,0 +1,186 @@+import { describe, expect, it } from "vitest";+import { readFileSync } from "node:fs";+import { resolve } from "node:path";+import { cellWidth, stripAnsi } from "./tui/cells.mjs";+import { cyclePane, formatPaneTitle, paneKinds, paneLines } from "./mso-agent-pane.mjs";+import { handleSessionCommand } from "./mso-agent-cmd-session.mjs";+import { mountScreenLoop } from "./mso-agent-screen-loop.mjs";++describe("mso-agent-pane-slots", () => {+ // Test 1: unpinned /pane cycles and wraps+ it("1. unpinned /pane cycles through every kind and wraps", async () => {+ const kinds = paneKinds();+ expect(kinds).toEqual(["todos", "diff", "files", "mcp", "context", "off"]);++ // Pure cyclePane helper checks+ expect(cyclePane("todos", { pinned: false })).toBe("diff");+ expect(cyclePane("diff", { pinned: false })).toBe("files");+ expect(cyclePane("files", { pinned: false })).toBe("mcp");+ expect(cyclePane("mcp", { pinned: false })).toBe("context");+ expect(cyclePane("context", { pinned: false })).toBe("off");+ expect(cyclePane("off", { pinned: false })).toBe("todos");++ // Command dispatch cycling across a session+ const session: any = { paneKind: "off", panePinned: false };+ const logs: string[] = [];+ const ctx = { session, C: {}, write: (s: string) => logs.push(s) };++ const expectedOrder = ["todos", "diff", "files", "mcp", "context", "off", "todos"];+ for (const expected of expectedOrder) {+ const res = await handleSessionCommand(ctx, "/pane", []);+ expect(res).toBe("handled");+ expect(session.paneKind).toBe(expected);+ expect(logs[logs.length - 1]).toContain(`side pane: ${expected}`);+ }+ });++ // Test 2: pin then /pane does not move+ it("2. pin then /pane does not move and reports the pinned slot", async () => {+ const session: any = { paneKind: "diff", panePinned: false };+ const logs: string[] = [];+ const ctx = { session, C: {}, write: (s: string) => logs.push(s) };++ // Explicit pin locks the current slot+ const resPin = await handleSessionCommand(ctx, "/pane", ["pin"]);+ expect(resPin).toBe("handled");+ expect(session.panePinned).toBe(true);+ expect(session.paneKind).toBe("diff");+ expect(logs[logs.length - 1]).toContain("side pane: diff (pinned)");++ // Bare /pane while pinned reports without advancing+ const resBare1 = await handleSessionCommand(ctx, "/pane", []);+ expect(resBare1).toBe("handled");+ expect(session.paneKind).toBe("diff");+ expect(logs[logs.length - 1]).toContain("side pane: diff (pinned)");++ const resBare2 = await handleSessionCommand(ctx, "/pane", []);+ expect(resBare2).toBe("handled");+ expect(session.paneKind).toBe("diff");+ expect(logs[logs.length - 1]).toContain("side pane: diff (pinned)");++ // Pure helper keeps current kind when pinned+ expect(cyclePane("diff", { pinned: true })).toBe("diff");+ expect(cyclePane("context", { pinned: true })).toBe("context");+ });++ // Test 3: pin then /pane todos restores unpinned cycling+ it("3. pin then /pane todos sets the slot and restores non-pinned cycling", async () => {+ const session: any = { paneKind: "diff", panePinned: true };+ const logs: string[] = [];+ const ctx = { session, C: {}, write: (s: string) => logs.push(s) };++ // Direct slot selection sets the requested kind and restores unpinned cycling+ const resSelect = await handleSessionCommand(ctx, "/pane", ["todos"]);+ expect(resSelect).toBe("handled");+ expect(session.paneKind).toBe("todos");+ expect(session.panePinned).toBe(false);+ expect(logs[logs.length - 1]).toContain("side pane: todos");++ // Subsequent bare /pane advances to diff because cycling was restored+ const resNext = await handleSessionCommand(ctx, "/pane", []);+ expect(resNext).toBe("handled");+ expect(session.paneKind).toBe("diff");+ expect(logs[logs.length - 1]).toContain("side pane: diff");+ });++ // Test 4: /pane off clears both+ it("4. /pane off clears both the pane and the pin", async () => {+ const session: any = { paneKind: "mcp", panePinned: true };+ const logs: string[] = [];+ const ctx = { session, C: {}, write: (s: string) => logs.push(s) };++ const resOff = await handleSessionCommand(ctx, "/pane", ["off"]);+ expect(resOff).toBe("handled");+ expect(session.paneKind).toBe("off");+ expect(session.panePinned).toBe(false);+ expect(logs[logs.length - 1]).toContain("side pane: off");++ // Once turned off, bare /pane cycles cleanly to todos without staying pinned+ const resCycle = await handleSessionCommand(ctx, "/pane", []);+ expect(resCycle).toBe("handled");+ expect(session.paneKind).toBe("todos");+ expect(session.panePinned).toBe(false);+ });++ // Test 5: pinned marker appears in the pane title and line still fits width+ it("5. pinned marker appears in the pane title and every line fits width", () => {+ expect(formatPaneTitle("Todos", { pinned: true })).toBe("Todos [pinned]");+ expect(formatPaneTitle("Todos", { pinned: false })).toBe("Todos");+ expect(formatPaneTitle("", { pinned: true })).toBe("");++ const widths = [12, 30, 42, 50];+ const rows = [3, 4, 8, 16];++ for (const w of widths) {+ for (const r of rows) {+ const lines = paneLines({+ kind: "todos",+ pinned: true,+ width: w,+ rows: r,+ });+ expect(lines.length).toBe(r);+ for (const line of lines) {+ expect(cellWidth(line)).toBe(w);+ }+ if (r >= 3 && w >= 30) {+ const stripped = lines.map((l) => stripAnsi(l)).join("\n");+ expect(stripped).toContain("[pinned]");+ }+ }+ }++ // Verify session.panePinned drives pinned marker in paneLines+ const sessionLines = paneLines({+ kind: "context",+ session: { panePinned: true },+ width: 40,+ rows: 6,+ });+ expect(sessionLines.map((l) => stripAnsi(l)).join("\n")).toContain("[pinned]");++ // Off pane never displays a pinned marker+ const offLines = paneLines({+ kind: "off",+ pinned: true,+ width: 40,+ rows: 6,+ });+ expect(offLines.map((l) => stripAnsi(l)).join("\n")).not.toContain("[pinned]");+ });++ // Test 6: session.paneKind remains the only field that decides rendering+ it("6. session.paneKind remains the only field that decides rendering", () => {+ const fakeStdout: any = { isTTY: true, columns: 120, rows: 24, write() {}, on() {}, off() {} };+ const session: any = { paneKind: "off", panePinned: true };++ const loop = mountScreenLoop({+ session,+ enabled: true,+ output: fakeStdout,+ });++ // Pinned alone does not cause pane rendering when paneKind is off+ const geomOff = loop.geometry();+ expect(geomOff.kind).toBeNull();+ expect(geomOff.pWidth).toBe(0);++ // Unpinned todos renders side pane+ session.paneKind = "todos";+ session.panePinned = false;+ const geomUnpinned = loop.geometry();+ expect(geomUnpinned.kind).toBe("todos");+ expect(geomUnpinned.pWidth).toBe(42);++ // Pinning does not alter rendering geometry or kind choice+ session.panePinned = true;+ const geomPinned = loop.geometry();+ expect(geomPinned.kind).toBe("todos");+ expect(geomPinned.pWidth).toBe(42);++ // Assert screen loop source does not consult panePinned or paneSlot+ const loopSrc = readFileSync(resolve(__dirname, "mso-agent-screen-loop.mjs"), "utf8");+ expect(loopSrc).not.toContain("panePinned");+ expect(loopSrc).not.toContain("paneSlot");+ });+});diff --git a/scripts/mso-agent-pane.mjs b/scripts/mso-agent-pane.mjsindex 559920a2..5d726f3b 100644--- a/scripts/mso-agent-pane.mjs+++ b/scripts/mso-agent-pane.mjs@@ -9,11 +9,20 @@ export function paneKinds() {return [...KINDS];}-export function cyclePane(kind) {+export function cyclePane(kind, { pinned = false } = {}) {+ // When pinned, cyclePane keeps the current slot so user-selected content does not cycle away.+ if (pinned) return kind;const idx = KINDS.indexOf(kind);return idx === -1 ? KINDS[0] : KINDS[(idx + 1) % KINDS.length];}+// Pure formatter that appends a [pinned] marker so the title shows cycling is locked.+export function formatPaneTitle(title, { pinned = false } = {}) {+ const base = String(title || "");+ if (!pinned || !base) return base;+ return `${base} [pinned]`;+}+// Side pane width: floor 30 preserves readability; ceiling 50 avoids crowding// the transcript; fraction 0.35 reserves roughly two thirds for the transcript.export function paneWidth(columns, { minColumns = 100 } = {}) {@@ -24,8 +33,7 @@ export function paneWidth(columns, { minColumns = 100 } = {}) {function resolveTodos(todos, session) {if (todos != null) return todos;- if (session?.todos != null) return session.todos;- return latestTodos();+ return session?.todos != null ? session.todos : latestTodos();}function resolveDiff(lastDiff, session) {@@ -106,15 +114,8 @@ function formatKindContent({ kind, session, todos, lastDiff, files, mcpServers }if (!fileList.length) return { title: "Changed files", emptyText: "no changed files", rows: [] };return { title: "Changed files", emptyText: null, rows: fileList.map((f) => ({ text: f, tone: "normal" })) };}-- if (kind === "mcp") {- return formatMcpContent({ session, mcpServers });- }-- if (kind === "context") {- return formatContextContent({ session });- }-+ if (kind === "mcp") return formatMcpContent({ session, mcpServers });+ if (kind === "context") return formatContextContent({ session });return { title: "Pane off", emptyText: "pane is off", rows: [] };}@@ -140,6 +141,7 @@ function styleTone(line, tone, { colors, cDim, cCyan, cErr, cBlue, cBold }) {* colors?: any,* width?: number,* rows?: number,+ * pinned?: boolean | null,* }} [options]*/export function paneLines({@@ -152,6 +154,7 @@ export function paneLines({colors = {},width = 40,rows = 24,+ pinned = null,} = {}) {const r = Math.max(0, Number(rows) || 0), w = Math.max(0, Number(width) || 0);if (r === 0 || w === 0) return [];@@ -159,13 +162,9 @@ export function paneLines({const widths = [w - 2], hasColors = Boolean(colors && Object.keys(colors).length > 0);const palette = {- colors,- cDim: hasColors ? (colors.dim || "") : "",- cReset: hasColors ? (colors.reset || "") : "",- cBold: hasColors ? (colors.bold || "") : "",- cCyan: hasColors ? (colors.cyan || colors.c || "") : "",- cErr: hasColors ? (colors.err || "") : "",- cBlue: hasColors ? (colors.blue || "") : "",+ colors, cDim: hasColors ? (colors.dim || "") : "", cReset: hasColors ? (colors.reset || "") : "",+ cBold: hasColors ? (colors.bold || "") : "", cCyan: hasColors ? (colors.cyan || colors.c || "") : "",+ cErr: hasColors ? (colors.err || "") : "", cBlue: hasColors ? (colors.blue || "") : "",};const { title, emptyText, rows: contentRows } = formatKindContent({@@ -176,10 +175,13 @@ export function paneLines({files,mcpServers,});+ // Pinned state can be passed directly or read from session. Off pane is never marked pinned.+ const isPinned = pinned != null ? Boolean(pinned) : Boolean(session?.panePinned);+ const displayTitle = formatPaneTitle(title, { pinned: isPinned && kind !== "off" });const topBorder = palette.cDim ? `${palette.cDim}${border(widths, "top")}${palette.cReset}` : border(widths, "top");const midBorder = palette.cDim ? `${palette.cDim}${border(widths, "mid")}${palette.cReset}` : border(widths, "mid");const botBorder = palette.cDim ? `${palette.cDim}${border(widths, "bottom")}${palette.cReset}` : border(widths, "bottom");- const titleRow = palette.cBold ? `${palette.cBold}${paneRow([title], widths)}${palette.cReset}` : paneRow([title], widths);+ const titleRow = palette.cBold ? `${palette.cBold}${paneRow([displayTitle], widths)}${palette.cReset}` : paneRow([displayTitle], widths);if (r === 1) return [titleRow];if (r === 2) return [topBorder, botBorder];