Skip to content

armgit / mso

Public Imported from GitHub
0

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.

feat(tui): pin a pane slot without losing the cycle (#229)

Abdurrahman Fakhrul3e30ba3da9ac
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index 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-01
diff --git a/scripts/mso-agent-cmd-session.mjs b/scripts/mso-agent-cmd-session.mjs
index 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.mjs
index 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.ts
new file mode 100644
index 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.mjs
index 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];