@pellux/goodvibes-tui 0.19.99 → 0.20.1

package/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to GoodVibes TUI.
 
 ---
 
+## [0.20.1] — 2026-05-12
+
+### Changes
+- Added shared fullscreen rendering primitives for frame drawing, text writing, clipping, fills, rules, stable windows, and the workspace palette.
+- Refactored `/config` and `/mcp` to use the same reusable fullscreen workspace base instead of maintaining separate one-off renderers.
+- Updated onboarding to consume the shared primitive layer while preserving its wizard-specific layout and behavior.
+
+## [0.20.0] — 2026-05-11
+
+### Changes
+- Updated `@pellux/goodvibes-sdk` to `0.33.30` for guest-side QEMU REPL execution and exec working-directory fixes.
+- Added generated QEMU sandbox setup docs, runtime bootstrap scripts, cloud-init seed files, and guest runtime provisioning guidance.
+- Wired `sandbox.replJavaScriptCommand` through generated QEMU setup manifests so JavaScript-family REPL snippets use the guest Bun runtime.
+- Removed the obsolete `/sandbox qemu create-image` command in favor of the generated `create-image.sh` bootstrap workflow.
+- Added focused coverage for QEMU setup scaffolding, command-level exec working directories, context auto-compaction thresholds, and retrospective setup-guide intent classification.
+
 ## [0.19.99] — 2026-05-12
 
 ### Changes

package/README.md

@@ -2,7 +2,7 @@
 
 [![CI](https://github.com/mgd34msu/goodvibes-tui/actions/workflows/ci.yml/badge.svg)](https://github.com/mgd34msu/goodvibes-tui/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Version](https://img.shields.io/badge/version-0.19.99-blue.svg)](https://github.com/mgd34msu/goodvibes-tui)
+[![Version](https://img.shields.io/badge/version-0.20.1-blue.svg)](https://github.com/mgd34msu/goodvibes-tui)
 
 A terminal-native AI coding, operations, automation, knowledge, and integration console with a typed runtime, omnichannel surfaces, structured memory/knowledge, and a raw ANSI renderer.
 
@@ -626,13 +626,16 @@ The QEMU path includes:
 
 - setup bundle generation
 - first-run bootstrap scaffolding
-- `qemu-img` image creation helpers
+- Debian cloud-image download, mutable qcow2 clone, resize, and NoCloud ISO creation through the generated `create-image.sh`
 - host-side wrapper generation
+- guest cloud-init seed generation for the `goodvibes` sudo user, SSH key auth, `/workspace`, and `ens3` DHCP
 - guest-test and wrapper-test validation
 - session-backed command execution
 - guest bundle export / inspect flows
 - setup manifest export / apply flows
 - `attach` and `launch-per-command` execution modes
+- REPL/MCP-friendly guest bootstrap packages for Python, JavaScript, TypeScript, SQL, GraphQL, Bun, Deno, DuckDB, Go, Rust, Ruby, and common CLI build/search tools
+- guest JavaScript-family REPL execution through `sandbox.replJavaScriptCommand`, defaulting the generated QEMU setup to `/home/goodvibes/.bun/bin/bun`
 
 Key commands:
 
@@ -643,7 +646,6 @@ Key commands:
 - `/sandbox probe`
 - `/sandbox qemu setup <dir>`
 - `/sandbox qemu bootstrap <dir> [size-gb]`
-- `/sandbox qemu create-image <path> [size-gb]`
 - `/sandbox qemu inspect-setup <manifest>`
 - `/sandbox qemu apply-setup <manifest>`
 - `/sandbox session ...`
@@ -654,10 +656,14 @@ Typical first-run path:
 
 ```sh
 /sandbox qemu bootstrap .goodvibes/tui/sandbox 20
+.goodvibes/tui/sandbox/create-image.sh .goodvibes/tui/sandbox/goodvibes-sandbox.qcow2 20G
+GV_SANDBOX_SYNC_WORKSPACE=0 GV_SANDBOX_WRAPPER_MODE=launch-qemu-ssh .goodvibes/tui/sandbox/qemu-wrapper.sh bash -s < .goodvibes/tui/sandbox/guest-bootstrap.sh
 /sandbox doctor
-/sandbox guest-test eval-js
+/sandbox guest-test eval-py
 ```
 
+See [QEMU sandbox bootstrapping](docs/qemu-sandbox.md) for host prerequisites, generated files, first-boot behavior, guest runtime packages, and troubleshooting logs.
+
 ---
 
 ## Remote, Local Services, And Integration Helpers

package/docs/foundation-artifacts/operator-contract.json

@@ -3,7 +3,7 @@
   "product": {
     "id": "goodvibes",
     "surface": "operator",
-    "version": "0.33.27"
+    "version": "0.33.30"
   },
   "auth": {
     "modes": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pellux/goodvibes-tui",
-  "version": "0.19.99",
+  "version": "0.20.1",
   "description": "Terminal-native GoodVibes product for coding, operations, automation, knowledge, channels, and daemon-backed control-plane workflows.",
   "type": "module",
   "main": "src/main.ts",
@@ -97,7 +97,7 @@
     "@anthropic-ai/vertex-sdk": "^0.16.0",
     "@ast-grep/napi": "^0.42.0",
     "@aws/bedrock-token-generator": "^1.1.0",
-    "@pellux/goodvibes-sdk": "0.33.27",
+    "@pellux/goodvibes-sdk": "0.33.30",
     "bash-language-server": "^5.6.0",
     "fuse.js": "^7.1.0",
     "graphql": "^16.13.2",

package/src/input/commands/local-setup-review.ts

@@ -155,10 +155,13 @@ export function renderSetupSandboxReview(ctx: CommandContext, snapshot: SetupRev
   ];
   if (backend === 'local') {
     lines.push('    /sandbox qemu bootstrap .goodvibes/tui/sandbox 20');
+    lines.push('    .goodvibes/tui/sandbox/create-image.sh .goodvibes/tui/sandbox/goodvibes-sandbox.qcow2 20G');
+    lines.push('    GV_SANDBOX_SYNC_WORKSPACE=0 GV_SANDBOX_WRAPPER_MODE=launch-qemu-ssh .goodvibes/tui/sandbox/qemu-wrapper.sh bash -s < .goodvibes/tui/sandbox/guest-bootstrap.sh');
     lines.push('    /sandbox doctor');
   } else if (!image || !wrapper) {
     lines.push('    /sandbox qemu setup .goodvibes/tui/sandbox');
-    lines.push('    /sandbox qemu create-image .goodvibes/tui/sandbox/images/goodvibes-sandbox.qcow2 20');
+    lines.push('    .goodvibes/tui/sandbox/create-image.sh .goodvibes/tui/sandbox/goodvibes-sandbox.qcow2 20G');
+    lines.push('    GV_SANDBOX_SYNC_WORKSPACE=0 GV_SANDBOX_WRAPPER_MODE=launch-qemu-ssh .goodvibes/tui/sandbox/qemu-wrapper.sh bash -s < .goodvibes/tui/sandbox/guest-bootstrap.sh');
     lines.push('    /sandbox doctor');
   } else {
     lines.push('    /sandbox guest-test eval-js');

package/src/input/commands/platform-sandbox-qemu.ts

@@ -4,7 +4,6 @@ import type { CommandContext } from '../command-registry.ts';
 import {
   applySandboxQemuSetupManifest,
   bootstrapSandboxQemuSetupBundle,
-  createSandboxQemuImage,
   inspectSandboxQemuSetupManifest,
   loadSandboxQemuSetupManifest,
   scaffoldSandboxQemuSetupBundle,
@@ -27,29 +26,25 @@ export async function handleSandboxQemuCommand(args: string[], ctx: CommandConte
       return true;
     }
     const bundle = scaffoldSandboxQemuSetupBundle(ctx.platform.configManager, shellPaths.workingDirectory, dirArg, { surfaceRoot: 'tui' });
-    ctx.platform.configManager.setDynamic('sandbox.vmBackend', 'qemu');
-    ctx.platform.configManager.setDynamic('sandbox.qemuExecWrapper', bundle.wrapperPath);
-    ctx.platform.configManager.setDynamic('sandbox.qemuImagePath', bundle.imagePath);
-    if (!`${ctx.platform.configManager.get('sandbox.qemuGuestHost') ?? ''}`.trim()) {
-      ctx.platform.configManager.setDynamic('sandbox.qemuGuestHost', '127.0.0.1');
-    }
-    if (!`${ctx.platform.configManager.get('sandbox.qemuGuestUser') ?? ''}`.trim()) {
-      ctx.platform.configManager.setDynamic('sandbox.qemuGuestUser', 'goodvibes');
-    }
-    if (!`${ctx.platform.configManager.get('sandbox.qemuWorkspacePath') ?? ''}`.trim()) {
-      ctx.platform.configManager.setDynamic('sandbox.qemuWorkspacePath', '/workspace');
-    }
+    const manifest = loadSandboxQemuSetupManifest(shellPaths.workingDirectory, bundle.manifestPath);
+    applySandboxQemuSetupManifest(ctx.platform.configManager, manifest);
+    ctx.platform.configManager.setDynamic('sandbox.replIsolation', 'shared-vm');
+    ctx.platform.configManager.setDynamic('sandbox.mcpIsolation', 'shared-vm');
     ctx.print([
       `Initialized QEMU sandbox setup bundle in ${bundle.directory}`,
       `  wrapper: ${bundle.wrapperPath}`,
       `  image path: ${bundle.imagePath}`,
       `  image create script: ${bundle.imageCreateScriptPath}`,
       `  guest bootstrap: ${bundle.guestBootstrapScriptPath}`,
+      `  seed directory: ${bundle.seedDirectory}`,
+      `  seed ISO: ${bundle.seedIsoPath}`,
+      `  ssh key: ${bundle.sshKeyPath}`,
       `  projection policy: ${bundle.projectionPolicyPath}`,
       `  ssh config: ${bundle.sshConfigPath}`,
       `  manifest: ${bundle.manifestPath}`,
-      '  applied: backend=qemu, wrapper path, image path, and default guest settings',
-      `  next: /sandbox qemu create-image ${bundle.imagePath} 20`,
+      '  applied: backend=qemu, qemu binary, wrapper path, image path, launch-per-command guest settings, shared VM isolation',
+      `  next: ${bundle.imageCreateScriptPath} ${bundle.imagePath} 20G`,
+      `  then provision runtimes: GV_SANDBOX_SYNC_WORKSPACE=0 GV_SANDBOX_WRAPPER_MODE=launch-qemu-ssh ${bundle.wrapperPath} bash -s < ${bundle.guestBootstrapScriptPath}`,
     ].join('\n'));
     return true;
   }
@@ -67,33 +62,20 @@ export async function handleSandboxQemuCommand(args: string[], ctx: CommandConte
         `  wrapper: ${bundle.wrapperPath}`,
         `  image path: ${bundle.imagePath}`,
         `  guest bootstrap: ${bundle.guestBootstrapScriptPath}`,
+        `  seed ISO: ${bundle.seedIsoPath}`,
+        `  ssh key: ${bundle.sshKeyPath}`,
         `  projection policy: ${bundle.projectionPolicyPath}`,
         `  manifest: ${bundle.manifestPath}`,
-        '  applied: backend=qemu, wrapper path, image path, and guest settings',
-        '  next: boot the image, run the guest bootstrap script, then /sandbox guest-test eval-js',
+        '  applied: backend=qemu, qemu binary, wrapper path, image path, launch-per-command guest settings, shared VM isolation',
+        `  next: ${bundle.imageCreateScriptPath} ${bundle.imagePath} ${sizeGb}G`,
+        `  then provision runtimes: GV_SANDBOX_SYNC_WORKSPACE=0 GV_SANDBOX_WRAPPER_MODE=launch-qemu-ssh ${bundle.wrapperPath} bash -s < ${bundle.guestBootstrapScriptPath}`,
+        '  then: /sandbox guest-test eval-py',
       ].join('\n'));
     } catch (error) {
       ctx.print(summarizeError(error));
     }
     return true;
   }
-  if (sub === 'create-image') {
-    const imagePath = args[2];
-    const sizeGb = Number.parseInt(args[3] ?? '20', 10);
-    if (!imagePath || !Number.isInteger(sizeGb) || sizeGb < 1) {
-      ctx.print('Usage: /sandbox qemu create-image <path> [size-gb]');
-      return true;
-    }
-    try {
-      const created = createSandboxQemuImage(shellPaths.workingDirectory, imagePath, sizeGb);
-      ctx.platform.configManager.setDynamic('sandbox.qemuImagePath', created.path);
-      ctx.platform.configManager.setDynamic('sandbox.vmBackend', 'qemu');
-      ctx.print(`Created QEMU image ${created.path} (${created.sizeGb}G).`);
-    } catch (error) {
-      ctx.print(summarizeError(error));
-    }
-    return true;
-  }
   if (sub === 'recover') {
     const sessionId = args[2];
     if (!sessionId) {
@@ -132,6 +114,6 @@ export async function handleSandboxQemuCommand(args: string[], ctx: CommandConte
     ctx.print(`Applied QEMU sandbox setup from ${shellPaths.resolveWorkspacePath(pathArg)}.`);
     return true;
   }
-  ctx.print('Usage: /sandbox qemu <setup <directory>|bootstrap <directory> [size-gb]|create-image <path> [size-gb]|recover <session-id>|inspect-setup <setup-manifest.json>|apply-setup <setup-manifest.json>>');
+  ctx.print('Usage: /sandbox qemu <setup <directory>|bootstrap <directory> [size-gb]|recover <session-id>|inspect-setup <setup-manifest.json>|apply-setup <setup-manifest.json>>');
   return true;
 }

package/src/input/commands/platform-sandbox-runtime.ts

@@ -61,6 +61,7 @@ function applySandboxPreset(
   configManager.setDynamic('sandbox.qemuGuestUser' as never, preset.config.qemuGuestUser);
   configManager.setDynamic('sandbox.qemuWorkspacePath' as never, preset.config.qemuWorkspacePath);
   configManager.setDynamic('sandbox.qemuSessionMode' as never, preset.config.qemuSessionMode);
+  configManager.setDynamic('sandbox.replJavaScriptCommand' as never, preset.config.replJavaScriptCommand);
   return true;
 }
 
@@ -83,6 +84,7 @@ function renderSandboxPresetDetail(presetId: string): string | null {
     `  qemu guest user: ${preset.config.qemuGuestUser || '(not configured)'}`,
     `  qemu workspace: ${preset.config.qemuWorkspacePath || '(not configured)'}`,
     `  qemu session mode: ${preset.config.qemuSessionMode}`,
+    `  repl JavaScript command: ${preset.config.replJavaScriptCommand || 'bun'}`,
     ...preset.notes.map((note) => `  note: ${note}`),
   ].join('\n');
 }
@@ -91,7 +93,7 @@ export function registerPlatformSandboxRuntimeCommands(registry: CommandRegistry
   registry.register({
     name: 'sandbox',
     description: 'Review and configure VM isolation policy for MCP and evaluation runtimes',
-    usage: '[open|review|recommend|profiles|presets|preset <id>|apply-preset <id>|probe|doctor|wrapper-test <profile>|guest-test <profile>|init-qemu <dir>|qemu <setup|bootstrap|create-image|recover|inspect-setup|apply-setup> ...|session ...|bundle ...|guest-bundle <export|inspect> <path>|scaffold-qemu-wrapper <path>|set-mcp <mode>|set-repl <mode>|set-windows <mode>|set-backend <mode>|set-qemu-binary <path>|set-qemu-image <path>|set-qemu-wrapper <path>|set-qemu-guest-host <host>|set-qemu-guest-port <port>|set-qemu-guest-user <user>|set-qemu-workspace <path>|set-qemu-session-mode <attach|launch-per-command>]',
+    usage: '[open|review|recommend|profiles|presets|preset <id>|apply-preset <id>|probe|doctor|wrapper-test <profile>|guest-test <profile>|init-qemu <dir>|qemu <setup|bootstrap|recover|inspect-setup|apply-setup> ...|session ...|bundle ...|guest-bundle <export|inspect> <path>|scaffold-qemu-wrapper <path>|set-mcp <mode>|set-repl <mode>|set-windows <mode>|set-backend <mode>|set-qemu-binary <path>|set-qemu-image <path>|set-qemu-wrapper <path>|set-qemu-guest-host <host>|set-qemu-guest-port <port>|set-qemu-guest-user <user>|set-qemu-workspace <path>|set-qemu-session-mode <attach|launch-per-command>]',
     async handler(args, ctx) {
       const shellPaths = requireShellPaths(ctx);
       const sub = args[0] ?? 'open';
@@ -400,7 +402,7 @@ export function registerPlatformSandboxRuntimeCommands(registry: CommandRegistry
         ctx.print([`Scaffolded QEMU wrapper to ${targetPath}`, '  bridge test mode: GV_SANDBOX_WRAPPER_MODE=host-exec', '  next: /sandbox set-qemu-wrapper ' + targetPath].join('\n'));
         return;
       }
-      ctx.print('Usage: /sandbox [open|review|recommend|profiles|presets|preset <id>|apply-preset <id>|probe|doctor|wrapper-test <profile>|guest-test <profile>|init-qemu <dir>|qemu <setup|bootstrap|create-image|recover|inspect-setup|apply-setup> ...|session ...|bundle export <path>|bundle inspect <path>|guest-bundle <export|inspect> <path>|scaffold-qemu-wrapper <path>|set-mcp <mode>|set-repl <mode>|set-windows <mode>|set-backend <mode>|set-qemu-binary <path>|set-qemu-image <path>|set-qemu-wrapper <path>|set-qemu-guest-host <host>|set-qemu-guest-port <port>|set-qemu-guest-user <user>|set-qemu-workspace <path>|set-qemu-session-mode <attach|launch-per-command>]');
+      ctx.print('Usage: /sandbox [open|review|recommend|profiles|presets|preset <id>|apply-preset <id>|probe|doctor|wrapper-test <profile>|guest-test <profile>|init-qemu <dir>|qemu <setup|bootstrap|recover|inspect-setup|apply-setup> ...|session ...|bundle export <path>|bundle inspect <path>|guest-bundle <export|inspect> <path>|scaffold-qemu-wrapper <path>|set-mcp <mode>|set-repl <mode>|set-windows <mode>|set-backend <mode>|set-qemu-binary <path>|set-qemu-image <path>|set-qemu-wrapper <path>|set-qemu-guest-host <host>|set-qemu-guest-port <port>|set-qemu-guest-user <user>|set-qemu-workspace <path>|set-qemu-session-mode <attach|launch-per-command>]');
     },
   });
 }

package/src/renderer/fullscreen-primitives.ts

@@ -0,0 +1,130 @@
+import type { Line } from '../types/grid.ts';
+import { createEmptyLine, createStyledCell } from '../types/grid.ts';
+import { getDisplayWidth } from '../utils/terminal-width.ts';
+import { GLYPHS, UI_TONES } from './ui-primitives.ts';
+
+export const FULLSCREEN_PALETTE = {
+  border: '#64748b',
+  title: '#67e8f9',
+  subtitle: '#93c5fd',
+  text: '#e2e8f0',
+  muted: '#94a3b8',
+  dim: '#64748b',
+  selectedBg: '#223049',
+  categoryBg: '#141b25',
+  contextBg: '#121923',
+  controlsBg: '#0f141d',
+  footerBg: '#111827',
+  good: UI_TONES.state.good,
+  warn: UI_TONES.state.warn,
+  bad: UI_TONES.state.bad,
+  info: UI_TONES.state.info,
+} as const;
+
+export type FullscreenTextStyle = Partial<Omit<Line[number], 'char'>>;
+
+export function clamp(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, value));
+}
+
+export function fillRange(line: Line, startX: number, endX: number, bg: string): void {
+  for (let x = Math.max(0, startX); x <= Math.min(line.length - 1, endX); x += 1) {
+    const cell = line[x] ?? createStyledCell(' ');
+    line[x] = createStyledCell(cell.char, {
+      fg: cell.fg,
+      bg,
+      bold: cell.bold,
+      dim: cell.dim,
+      underline: cell.underline,
+      italic: cell.italic,
+      strikethrough: cell.strikethrough,
+      link: cell.link,
+    });
+  }
+}
+
+export function fillWidth(line: Line, startX: number, width: number, bg: string): void {
+  if (width <= 0) return;
+  fillRange(line, startX, startX + width - 1, bg);
+}
+
+export function writeText(
+  line: Line,
+  startX: number,
+  maxWidth: number,
+  text: string,
+  style: FullscreenTextStyle = {},
+): void {
+  let x = startX;
+  let used = 0;
+  for (const ch of text) {
+    const width = getDisplayWidth(ch);
+    if (width <= 0) continue;
+    if (used + width > maxWidth || x >= line.length) break;
+    line[x] = createStyledCell(ch, style);
+    if (width > 1 && x + 1 < line.length) line[x + 1] = createStyledCell(' ', style);
+    x += width;
+    used += width;
+  }
+}
+
+export function makeLine(width: number, bg = ''): Line {
+  const line = createEmptyLine(width);
+  if (bg) fillRange(line, 0, width - 1, bg);
+  return line;
+}
+
+export function borderLine(width: number, left: string, fill: string, right: string, fg: string = FULLSCREEN_PALETTE.border): Line {
+  const line = makeLine(width);
+  if (width <= 0) return line;
+  line[0] = createStyledCell(left, { fg });
+  for (let x = 1; x < width - 1; x += 1) line[x] = createStyledCell(fill, { fg });
+  if (width > 1) line[width - 1] = createStyledCell(right, { fg });
+  return line;
+}
+
+export function contentLine(width: number, bg: string, borderFg: string = FULLSCREEN_PALETTE.border): Line {
+  const line = makeLine(width, bg);
+  if (width > 0) line[0] = createStyledCell(GLYPHS.frame.vertical, { fg: borderFg });
+  if (width > 1) line[width - 1] = createStyledCell(GLYPHS.frame.vertical, { fg: borderFg });
+  return line;
+}
+
+export function drawVerticalRule(line: Line, x: number, fg: string = FULLSCREEN_PALETTE.border, bg = ''): void {
+  if (x < 0 || x >= line.length) return;
+  line[x] = createStyledCell(GLYPHS.frame.vertical, { fg, bg });
+}
+
+export function drawHorizontalRule(line: Line, startX: number, endX: number, fg: string = FULLSCREEN_PALETTE.border, bg = ''): void {
+  for (let x = Math.max(0, startX); x <= Math.min(line.length - 1, endX); x += 1) {
+    line[x] = createStyledCell(GLYPHS.frame.horizontal, { fg, bg });
+  }
+}
+
+export function clipDisplay(text: string, width: number): string {
+  if (width <= 0) return '';
+  let used = 0;
+  let output = '';
+  for (const ch of text) {
+    const chWidth = getDisplayWidth(ch);
+    if (chWidth <= 0) continue;
+    if (used + chWidth > width) break;
+    output += ch;
+    used += chWidth;
+  }
+  return output;
+}
+
+export function padDisplay(text: string, width: number): string {
+  const clipped = clipDisplay(text, width);
+  return `${clipped}${' '.repeat(Math.max(0, width - getDisplayWidth(clipped)))}`;
+}
+
+export function stableWindow(total: number, selectedIndex: number, visibleCount: number): { start: number; end: number } {
+  if (total <= 0 || visibleCount <= 0) return { start: 0, end: 0 };
+  if (total <= visibleCount) return { start: 0, end: total };
+  const selected = clamp(selectedIndex, 0, total - 1);
+  const half = Math.floor(visibleCount / 2);
+  const start = clamp(selected - half, 0, total - visibleCount);
+  return { start, end: start + visibleCount };
+}

package/src/renderer/fullscreen-workspace.ts

@@ -0,0 +1,199 @@
+import type { Line } from '../types/grid.ts';
+import { GLYPHS } from './ui-primitives.ts';
+import {
+  borderLine,
+  clamp,
+  contentLine,
+  drawHorizontalRule,
+  drawVerticalRule,
+  fillRange,
+  FULLSCREEN_PALETTE,
+  makeLine,
+  writeText,
+} from './fullscreen-primitives.ts';
+
+export {
+  borderLine,
+  clamp,
+  contentLine,
+  fillRange,
+  makeLine,
+  padDisplay,
+  stableWindow,
+  writeText,
+} from './fullscreen-primitives.ts';
+export { FULLSCREEN_PALETTE as WORKSPACE_PALETTE } from './fullscreen-primitives.ts';
+
+const WORKSPACE_PALETTE = FULLSCREEN_PALETTE;
+
+export interface WorkspaceRow {
+  readonly text: string;
+  readonly selected?: boolean;
+  readonly bold?: boolean;
+  readonly dim?: boolean;
+  readonly fg?: string;
+  readonly bg?: string;
+  readonly kind?: 'group' | 'item' | 'more' | 'empty';
+}
+
+export interface FullscreenWorkspaceRenderOptions {
+  readonly width: number;
+  readonly height: number;
+  readonly title: string;
+  readonly stateLabel?: string;
+  readonly leftHeader: string;
+  readonly mainHeader: string;
+  readonly leftRows: readonly WorkspaceRow[];
+  readonly contextRows: readonly WorkspaceRow[];
+  readonly controlRows: readonly WorkspaceRow[];
+  readonly footer: string;
+  readonly leftWidth?: number;
+  readonly contextRatio?: number;
+  readonly minContextRows?: number;
+}
+
+export interface FullscreenWorkspaceMetrics {
+  readonly safeWidth: number;
+  readonly safeHeight: number;
+  readonly leftWidth: number;
+  readonly centerWidth: number;
+  readonly bodyRows: number;
+  readonly contextWidth: number;
+  readonly contextRows: number;
+  readonly controlRows: number;
+}
+
+export function drawVertical(line: Line, x: number, bg = ''): void {
+  if (x <= 0 || x >= line.length - 1) return;
+  drawVerticalRule(line, x, WORKSPACE_PALETTE.border, bg);
+}
+
+export function drawHorizontalRange(line: Line, startX: number, endX: number, bg = ''): void {
+  drawHorizontalRule(line, Math.max(1, startX), Math.min(line.length - 2, endX), WORKSPACE_PALETTE.border, bg);
+}
+
+function leftWidthFor(width: number, explicit?: number): number {
+  if (explicit !== undefined) return clamp(explicit, 14, Math.max(14, width - 24));
+  return width < 80
+    ? clamp(Math.round(width * 0.32), 14, Math.max(14, width - 24))
+    : clamp(Math.round(width * 0.22), 24, 34);
+}
+
+export function getFullscreenWorkspaceMetrics(options: Pick<
+  FullscreenWorkspaceRenderOptions,
+  'width' | 'height' | 'leftWidth' | 'contextRatio' | 'minContextRows'
+>): FullscreenWorkspaceMetrics {
+  const safeWidth = Math.max(1, options.width);
+  const safeHeight = Math.max(12, options.height);
+  const leftWidth = leftWidthFor(safeWidth, options.leftWidth);
+  const centerWidth = Math.max(20, safeWidth - leftWidth - 3);
+  const bodyTop = 3;
+  const footerY = safeHeight - 2;
+  const bodyRows = Math.max(4, footerY - bodyTop);
+  const contextWidth = Math.max(10, centerWidth - 2);
+  const maxContextRows = Math.max(3, bodyRows - 4);
+  const minContextRows = clamp(options.minContextRows ?? 10, 3, maxContextRows);
+  const contextRows = clamp(
+    Math.round(bodyRows * (options.contextRatio ?? 0.4)),
+    Math.min(minContextRows, maxContextRows),
+    maxContextRows,
+  );
+  const controlRows = Math.max(3, bodyRows - contextRows - 1);
+  return { safeWidth, safeHeight, leftWidth, centerWidth, bodyRows, contextWidth, contextRows, controlRows };
+}
+
+function rowFg(row: WorkspaceRow, fallback: string): string {
+  if (row.fg) return row.fg;
+  if (row.kind === 'group') return WORKSPACE_PALETTE.subtitle;
+  if (row.kind === 'more') return WORKSPACE_PALETTE.dim;
+  return fallback;
+}
+
+export function renderFullscreenWorkspace(options: FullscreenWorkspaceRenderOptions): Line[] {
+  const { safeWidth, safeHeight, leftWidth, centerWidth, bodyRows, contextWidth, contextRows } = getFullscreenWorkspaceMetrics(options);
+  const leftStart = 1;
+  const dividerX = leftWidth + 1;
+  const centerStart = dividerX + 1;
+  const centerEnd = safeWidth - 2;
+  const bodyTop = 3;
+  const separatorY = bodyTop + contextRows;
+  const lines: Line[] = [];
+
+  const top = borderLine(safeWidth, GLYPHS.frame.topLeft, GLYPHS.frame.horizontal, GLYPHS.frame.topRight);
+  writeText(top, 2, safeWidth - 4, ` ${options.title} `, { fg: WORKSPACE_PALETTE.title, bold: true });
+  if (options.stateLabel) {
+    writeText(top, Math.max(2, safeWidth - options.stateLabel.length - 4), options.stateLabel.length, options.stateLabel, {
+      fg: WORKSPACE_PALETTE.subtitle,
+    });
+  }
+  lines.push(top);
+
+  const header = contentLine(safeWidth, WORKSPACE_PALETTE.footerBg);
+  drawVertical(header, dividerX, WORKSPACE_PALETTE.footerBg);
+  writeText(header, leftStart + 1, leftWidth - 2, options.leftHeader, {
+    fg: WORKSPACE_PALETTE.subtitle,
+    bold: true,
+    bg: WORKSPACE_PALETTE.footerBg,
+  });
+  writeText(header, centerStart + 1, centerWidth - 2, options.mainHeader, {
+    fg: WORKSPACE_PALETTE.subtitle,
+    bold: true,
+    bg: WORKSPACE_PALETTE.footerBg,
+  });
+  lines.push(header);
+
+  const headerSep = contentLine(safeWidth, '');
+  drawVertical(headerSep, dividerX);
+  drawHorizontalRange(headerSep, 1, safeWidth - 2);
+  lines.push(headerSep);
+
+  for (let row = 0; row < bodyRows; row += 1) {
+    const y = bodyTop + row;
+    const inContext = y < separatorY;
+    const inSeparator = y === separatorY;
+    const bg = inSeparator ? '' : inContext ? WORKSPACE_PALETTE.contextBg : WORKSPACE_PALETTE.controlsBg;
+    const line = contentLine(safeWidth, bg);
+    fillRange(line, 1, dividerX - 1, WORKSPACE_PALETTE.categoryBg);
+    drawVertical(line, dividerX, bg);
+
+    const leftRow = options.leftRows[row] ?? { text: '', kind: 'empty' as const };
+    if (leftRow.selected) fillRange(line, leftStart, dividerX - 1, WORKSPACE_PALETTE.selectedBg);
+    writeText(line, leftStart + 1, leftWidth - 3, leftRow.text, {
+      fg: leftRow.selected ? WORKSPACE_PALETTE.text : rowFg(leftRow, WORKSPACE_PALETTE.muted),
+      bg: leftRow.selected ? WORKSPACE_PALETTE.selectedBg : WORKSPACE_PALETTE.categoryBg,
+      bold: leftRow.bold ?? (leftRow.selected || leftRow.kind === 'group'),
+      dim: leftRow.dim,
+    });
+
+    if (inSeparator) {
+      drawHorizontalRange(line, centerStart, centerEnd);
+    } else if (inContext) {
+      const contextRow = options.contextRows[row] ?? { text: '', kind: 'empty' as const };
+      writeText(line, centerStart + 1, contextWidth, contextRow.text, {
+        fg: rowFg(contextRow, WORKSPACE_PALETTE.text),
+        bg,
+        bold: contextRow.bold,
+        dim: contextRow.dim ?? contextRow.text.length === 0,
+      });
+    } else {
+      const controlRow = options.controlRows[row - contextRows - 1] ?? { text: '', kind: 'empty' as const };
+      if (controlRow.selected) fillRange(line, centerStart, centerEnd, WORKSPACE_PALETTE.selectedBg);
+      writeText(line, centerStart + 1, contextWidth, controlRow.text, {
+        fg: controlRow.selected ? WORKSPACE_PALETTE.text : rowFg(controlRow, WORKSPACE_PALETTE.text),
+        bg: controlRow.selected ? WORKSPACE_PALETTE.selectedBg : bg,
+        bold: controlRow.bold ?? controlRow.selected,
+        dim: controlRow.dim ?? controlRow.text.length === 0,
+      });
+    }
+
+    lines.push(line);
+  }
+
+  const footer = contentLine(safeWidth, WORKSPACE_PALETTE.footerBg);
+  writeText(footer, 2, safeWidth - 4, options.footer, { fg: WORKSPACE_PALETTE.muted, bg: WORKSPACE_PALETTE.footerBg });
+  lines.push(footer);
+  lines.push(borderLine(safeWidth, GLYPHS.frame.bottomLeft, GLYPHS.frame.horizontal, GLYPHS.frame.bottomRight));
+
+  while (lines.length < safeHeight) lines.unshift(makeLine(safeWidth));
+  return lines.slice(-safeHeight);
+}