@pellux/goodvibes-tui 0.20.0 → 0.20.2

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to GoodVibes TUI.
 
 ---
 
+## [0.20.2] — 2026-05-12
+
+### Changes
+- Changed QEMU sandbox setup/bootstrap defaults to use `~/.goodvibes/tui/sandbox` instead of writing setup bundles into the current project.
+- Made `/sandbox qemu bootstrap` perform the image build and guest runtime provisioning by default, with `--scaffold-only`, `--no-build`, and `--no-provision` escape hatches for manual workflows.
+- Updated sandbox review guidance and QEMU documentation so first-run setup no longer points users at project-local sandbox paths.
+
+## [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

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.20.0-blue.svg)](https://github.com/mgd34msu/goodvibes-tui)
+[![Version](https://img.shields.io/badge/version-0.20.2-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.
 
@@ -624,7 +624,7 @@ Isolation controls:
 
 The QEMU path includes:
 
-- setup bundle generation
+- setup bundle generation under the user GoodVibes data directory by default
 - first-run bootstrap scaffolding
 - Debian cloud-image download, mutable qcow2 clone, resize, and NoCloud ISO creation through the generated `create-image.sh`
 - host-side wrapper generation
@@ -644,8 +644,8 @@ Key commands:
 - `/sandbox recommend`
 - `/sandbox doctor`
 - `/sandbox probe`
-- `/sandbox qemu setup <dir>`
-- `/sandbox qemu bootstrap <dir> [size-gb]`
+- `/sandbox qemu setup [dir]`
+- `/sandbox qemu bootstrap [dir] [size-gb] [--scaffold-only|--no-build|--no-provision]`
 - `/sandbox qemu inspect-setup <manifest>`
 - `/sandbox qemu apply-setup <manifest>`
 - `/sandbox session ...`
@@ -655,13 +655,13 @@ Key commands:
 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 qemu bootstrap
 /sandbox doctor
 /sandbox guest-test eval-py
 ```
 
+By default, QEMU setup files, the mutable qcow2 image, SSH keys, logs, and runtime state live in `~/.goodvibes/tui/sandbox`, not in the current project. Pass an explicit directory only when you intentionally want a non-default bundle location. Use `/sandbox qemu setup` or `/sandbox qemu bootstrap --scaffold-only` if you want to generate/review the bundle without building the image or provisioning guest runtimes.
+
 See [QEMU sandbox bootstrapping](docs/qemu-sandbox.md) for host prerequisites, generated files, first-boot behavior, guest runtime packages, and troubleshooting logs.
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pellux/goodvibes-tui",
-  "version": "0.20.0",
+  "version": "0.20.2",
   "description": "Terminal-native GoodVibes product for coding, operations, automation, knowledge, channels, and daemon-backed control-plane workflows.",
   "type": "module",
   "main": "src/main.ts",

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

@@ -154,14 +154,12 @@ export function renderSetupSandboxReview(ctx: CommandContext, snapshot: SetupRev
     '  next:',
   ];
   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 qemu bootstrap');
+    lines.push('    default bundle: ~/.goodvibes/tui/sandbox');
     lines.push('    /sandbox doctor');
   } else if (!image || !wrapper) {
-    lines.push('    /sandbox qemu setup .goodvibes/tui/sandbox');
-    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 qemu bootstrap');
+    lines.push('    default bundle: ~/.goodvibes/tui/sandbox');
     lines.push('    /sandbox doctor');
   } else {
     lines.push('    /sandbox guest-test eval-js');

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

@@ -73,7 +73,7 @@ export function registerLocalSetupCommands(registry: CommandRegistry): void {
           ...(`${ctx.platform.configManager.get('sandbox.vmBackend')}` === 'qemu' && !String(ctx.platform.configManager.get('sandbox.qemuImagePath')).trim()
             ? ['  [WARN] sandbox: qemu backend selected without qemuImagePath'] : []),
           ...(`${ctx.platform.configManager.get('sandbox.vmBackend')}` === 'qemu' && !String(ctx.platform.configManager.get('sandbox.qemuExecWrapper')).trim()
-            ? ['  [WARN] sandbox: qemu backend selected without qemuExecWrapper', '    next: /sandbox scaffold-qemu-wrapper .goodvibes/tui/qemu-wrapper.sh'] : []),
+            ? ['  [WARN] sandbox: qemu backend selected without qemuExecWrapper', '    next: /sandbox qemu setup'] : []),
           ...(`${ctx.platform.configManager.get('sandbox.vmBackend')}` === 'qemu' && String(ctx.platform.configManager.get('sandbox.qemuExecWrapper')).trim()
             ? ['  [INFO] sandbox: wrapper bridge can be validated with GV_SANDBOX_WRAPPER_MODE=host-exec before wiring a real guest transport'] : []),
           ...(snapshot.serviceIssues.length > 0

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

@@ -1,5 +1,5 @@
-import { readFileSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
 import type { CommandContext } from '../command-registry.ts';
 import {
   applySandboxQemuSetupManifest,
@@ -11,6 +11,97 @@ import {
 import { requireShellPaths } from './runtime-services.ts';
 import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
 
+const DEFAULT_QEMU_SIZE_GB = 20;
+
+interface ParsedQemuSetupArgs {
+  readonly directory: string;
+}
+
+interface ParsedQemuBootstrapArgs extends ParsedQemuSetupArgs {
+  readonly sizeGb: number;
+  readonly buildImage: boolean;
+  readonly provisionGuest: boolean;
+}
+
+function defaultQemuSandboxDirectory(shellPaths: ReturnType<typeof requireShellPaths>): string {
+  return shellPaths.resolveUserPath('tui', 'sandbox');
+}
+
+function parseSetupArgs(args: string[], shellPaths: ReturnType<typeof requireShellPaths>): ParsedQemuSetupArgs {
+  const directory = args[2] ?? defaultQemuSandboxDirectory(shellPaths);
+  return {
+    directory,
+  };
+}
+
+function parseBootstrapArgs(args: string[], shellPaths: ReturnType<typeof requireShellPaths>): ParsedQemuBootstrapArgs {
+  let directory = defaultQemuSandboxDirectory(shellPaths);
+  let sizeGb = DEFAULT_QEMU_SIZE_GB;
+  let buildImage = true;
+  let provisionGuest = true;
+  for (const arg of args.slice(2)) {
+    if (arg === '--scaffold-only') {
+      buildImage = false;
+      provisionGuest = false;
+      continue;
+    }
+    if (arg === '--no-build') {
+      buildImage = false;
+      continue;
+    }
+    if (arg === '--no-provision') {
+      provisionGuest = false;
+      continue;
+    }
+    if (/^\d+$/.test(arg)) {
+      sizeGb = Number.parseInt(arg, 10);
+      continue;
+    }
+    directory = arg;
+  }
+  return {
+    directory,
+    sizeGb,
+    buildImage,
+    provisionGuest,
+  };
+}
+
+function tailText(value: string, maxLines = 40): string {
+  const lines = value.trim().split(/\r?\n/).filter(Boolean);
+  return lines.slice(Math.max(0, lines.length - maxLines)).join('\n');
+}
+
+function runQemuBootstrapStep(
+  label: string,
+  command: string,
+  args: readonly string[],
+  options: {
+    readonly cwd: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly input?: string;
+    readonly timeoutMs: number;
+  },
+): void {
+  const result = spawnSync(command, [...args], {
+    cwd: options.cwd,
+    env: { ...process.env, ...options.env },
+    input: options.input,
+    timeout: options.timeoutMs,
+    encoding: 'utf8',
+    windowsHide: true,
+  });
+  if (result.status === 0) return;
+  const stderr = tailText(result.stderr || '');
+  const stdout = tailText(result.stdout || '');
+  const reason = result.error instanceof Error ? result.error.message : `exit ${result.status ?? 'unknown'}`;
+  throw new Error([
+    `${label} failed (${reason}).`,
+    stderr ? `stderr:\n${stderr}` : '',
+    stdout ? `stdout:\n${stdout}` : '',
+  ].filter(Boolean).join('\n'));
+}
+
 export async function handleSandboxQemuCommand(args: string[], ctx: CommandContext): Promise<boolean> {
   const shellPaths = requireShellPaths(ctx);
   const sub = (args[1] ?? '').toLowerCase();
@@ -20,12 +111,8 @@ export async function handleSandboxQemuCommand(args: string[], ctx: CommandConte
     return true;
   }
   if (sub === 'setup') {
-    const dirArg = args[2];
-    if (!dirArg) {
-      ctx.print('Usage: /sandbox qemu setup <directory>');
-      return true;
-    }
-    const bundle = scaffoldSandboxQemuSetupBundle(ctx.platform.configManager, shellPaths.workingDirectory, dirArg, { surfaceRoot: 'tui' });
+    const parsed = parseSetupArgs(args, shellPaths);
+    const bundle = scaffoldSandboxQemuSetupBundle(ctx.platform.configManager, shellPaths.workingDirectory, parsed.directory, { surfaceRoot: 'tui' });
     const manifest = loadSandboxQemuSetupManifest(shellPaths.workingDirectory, bundle.manifestPath);
     applySandboxQemuSetupManifest(ctx.platform.configManager, manifest);
     ctx.platform.configManager.setDynamic('sandbox.replIsolation', 'shared-vm');
@@ -45,19 +132,21 @@ export async function handleSandboxQemuCommand(args: string[], ctx: CommandConte
       '  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}`,
+      '',
+      `Default setup location: ${defaultQemuSandboxDirectory(shellPaths)}`,
+      'Pass an explicit directory only when you intentionally want a non-default bundle location.',
     ].join('\n'));
     return true;
   }
   if (sub === 'bootstrap') {
-    const dirArg = args[2];
-    const sizeGb = Number.parseInt(args[3] ?? '20', 10);
-    if (!dirArg || !Number.isInteger(sizeGb) || sizeGb < 1) {
-      ctx.print('Usage: /sandbox qemu bootstrap <directory> [size-gb]');
+    const parsed = parseBootstrapArgs(args, shellPaths);
+    if (!Number.isInteger(parsed.sizeGb) || parsed.sizeGb < 1) {
+      ctx.print('Usage: /sandbox qemu bootstrap [directory] [size-gb] [--scaffold-only|--no-build|--no-provision]');
       return true;
     }
     try {
-      const bundle = bootstrapSandboxQemuSetupBundle(ctx.platform.configManager, shellPaths.workingDirectory, dirArg, sizeGb, { surfaceRoot: 'tui' });
-      ctx.print([
+      const bundle = bootstrapSandboxQemuSetupBundle(ctx.platform.configManager, shellPaths.workingDirectory, parsed.directory, parsed.sizeGb, { surfaceRoot: 'tui' });
+      const lines = [
         `Bootstrapped QEMU sandbox in ${bundle.directory}`,
         `  wrapper: ${bundle.wrapperPath}`,
         `  image path: ${bundle.imagePath}`,
@@ -67,10 +156,45 @@ export async function handleSandboxQemuCommand(args: string[], ctx: CommandConte
         `  projection policy: ${bundle.projectionPolicyPath}`,
         `  manifest: ${bundle.manifestPath}`,
         '  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'));
+      ];
+      if (parsed.buildImage) {
+        ctx.print(`Building QEMU image at ${bundle.imagePath} (${parsed.sizeGb}G). This can download the Debian cloud image on first run.`);
+        runQemuBootstrapStep('QEMU image build', bundle.imageCreateScriptPath, [bundle.imagePath, `${parsed.sizeGb}G`], {
+          cwd: bundle.directory,
+          timeoutMs: 30 * 60 * 1000,
+        });
+        lines.push('  image build: complete');
+      } else {
+        lines.push(`  image build: skipped`);
+        lines.push(`  next: ${bundle.imageCreateScriptPath} ${bundle.imagePath} ${parsed.sizeGb}G`);
+      }
+      if (parsed.provisionGuest) {
+        if (!existsSync(bundle.imagePath)) {
+          lines.push('  guest provisioning: skipped because image does not exist');
+          lines.push(`  next: ${bundle.imageCreateScriptPath} ${bundle.imagePath} ${parsed.sizeGb}G`);
+        } else {
+          ctx.print(`Provisioning guest runtimes through ${bundle.wrapperPath}. First boot can take several minutes.`);
+          runQemuBootstrapStep('QEMU guest runtime provisioning', bundle.wrapperPath, ['bash', '-s'], {
+            cwd: bundle.directory,
+            env: {
+              GV_SANDBOX_SYNC_WORKSPACE: '0',
+              GV_SANDBOX_WRAPPER_MODE: 'launch-qemu-ssh',
+            },
+            input: readFileSync(bundle.guestBootstrapScriptPath, 'utf8'),
+            timeoutMs: 45 * 60 * 1000,
+          });
+          lines.push('  guest provisioning: complete');
+        }
+      } else {
+        lines.push(`  guest provisioning: skipped`);
+        lines.push(`  next: GV_SANDBOX_SYNC_WORKSPACE=0 GV_SANDBOX_WRAPPER_MODE=launch-qemu-ssh ${bundle.wrapperPath} bash -s < ${bundle.guestBootstrapScriptPath}`);
+      }
+      lines.push('  verify: /sandbox doctor');
+      lines.push('  verify: /sandbox guest-test eval-py');
+      lines.push('');
+      lines.push(`Default setup location: ${defaultQemuSandboxDirectory(shellPaths)}`);
+      lines.push('Pass an explicit directory only when you intentionally want a non-default bundle location.');
+      ctx.print(lines.join('\n'));
     } catch (error) {
       ctx.print(summarizeError(error));
     }
@@ -114,6 +238,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]|recover <session-id>|inspect-setup <setup-manifest.json>|apply-setup <setup-manifest.json>>');
+  ctx.print('Usage: /sandbox qemu <setup [directory]|bootstrap [directory] [size-gb] [--scaffold-only|--no-build|--no-provision]|recover <session-id>|inspect-setup <setup-manifest.json>|apply-setup <setup-manifest.json>>');
   return true;
 }

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

@@ -93,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|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 [dir]|bootstrap [dir] [size-gb]|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';
@@ -144,7 +144,7 @@ export function registerPlatformSandboxRuntimeCommands(registry: CommandRegistry
           windowsMode: `${ctx.platform.configManager.get('sandbox.windowsMode')}`,
           secureSandboxReady: renderSandboxReview(ctx.platform.configManager).includes('available'),
           recommendedCommand: `${ctx.platform.configManager.get('sandbox.vmBackend')}` === 'local'
-            ? '/sandbox qemu bootstrap .goodvibes/tui/sandbox 20'
+            ? '/sandbox qemu bootstrap'
             : '/sandbox doctor',
         };
         ctx.print([inspectSandboxProbe(probe), ...backendProbe.warnings.map((warning: string) => `  warning: ${warning}`)].join('\n'));
@@ -207,7 +207,7 @@ export function registerPlatformSandboxRuntimeCommands(registry: CommandRegistry
           `  wrapper: ${bundle.wrapperPath}`,
           `  guest bundle: ${bundle.guestBundlePath}`,
           `  readme: ${bundle.readmePath}`,
-          '  next: /sandbox qemu setup <dir> for the full first-run setup path',
+          '  next: /sandbox qemu setup for the full default setup path',
         ].join('\n'));
         return;
       }
@@ -402,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|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 [dir]|bootstrap [dir] [size-gb]|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 };
+}