@valyrianjs/terminal 0.2.1 → 0.2.2

package/examples/docs/virtualized-list-workbench.tsx

@@ -0,0 +1,232 @@
+import {
+  Fixed,
+  List,
+  Pane,
+  Row,
+  Screen,
+  Split,
+  Table,
+  Td,
+  Text,
+  mountTerminal
+} from "@valyrianjs/terminal";
+import type { TerminalMountOptions, TerminalSession } from "@valyrianjs/terminal";
+
+type WorkItem = {
+  id: string;
+  title: string;
+  team: string;
+  status: string;
+};
+
+interface VirtualizedListWorkbenchState {
+  items: WorkItem[];
+  activeIndex: number;
+  selectedIndex: number;
+  viewportOffset: number;
+  viewportRows: number;
+  lastAction: string;
+  running: boolean;
+}
+
+export interface VirtualizedListWorkbenchDemo {
+  session: TerminalSession;
+  dispatchKey(key: string): string;
+  output(): string;
+  ansiOutput(): string;
+  isRunning(): boolean;
+  destroy(): void;
+}
+
+function shouldRunSnapshot() {
+  return process.argv.includes("--snapshot") || process.env.VALYRIAN_TERMINAL_EXAMPLE_SNAPSHOT === "1" || !process.stdin.isTTY;
+}
+
+function createItems(count = 2_000): WorkItem[] {
+  const teams = ["Ops", "Support", "Data", "Billing", "Release"];
+  const statuses = ["ready", "queued", "blocked", "review", "done"];
+
+  return Array.from({ length: count }, (_, index) => ({
+    id: `job-${String(index + 1).padStart(4, "0")}`,
+    title: index === 3
+      ? "Long wrapped item proving list text wrapping across multiple terminal rows without losing selection"
+      : `Batch export ${String(index + 1).padStart(4, "0")}`,
+    team: teams[index % teams.length],
+    status: statuses[index % statuses.length]
+  }));
+}
+
+function clampIndex(index: number, length: number) {
+  if (length <= 0) {
+    return 0;
+  }
+
+  return Math.max(0, Math.min(length - 1, index));
+}
+
+function createInitialState(): VirtualizedListWorkbenchState {
+  return {
+    items: createItems(),
+    activeIndex: 0,
+    selectedIndex: 0,
+    viewportOffset: 0,
+    viewportRows: 1,
+    lastAction: "opened workbench",
+    running: true
+  };
+}
+
+function selectedItem(state: VirtualizedListWorkbenchState) {
+  return state.items[clampIndex(state.selectedIndex, state.items.length)]!;
+}
+
+function activeItem(state: VirtualizedListWorkbenchState) {
+  return state.items[clampIndex(state.activeIndex, state.items.length)]!;
+}
+
+function observeListState(state: VirtualizedListWorkbenchState, event: { activeIndex: number; selectedIndex: number | null; viewportOffset: number; viewportRows: number }) {
+  state.activeIndex = event.activeIndex;
+  if (event.selectedIndex !== null) {
+    state.selectedIndex = event.selectedIndex;
+  }
+  state.viewportOffset = event.viewportOffset;
+  state.viewportRows = event.viewportRows;
+}
+
+export function App({ state }: { state: VirtualizedListWorkbenchState }) {
+  const selected = selectedItem(state);
+  const active = activeItem(state);
+
+  return (
+    <Screen title="Virtualized List Workbench">
+      <Fixed position="top" size={1}>
+        <Text>Virtualized List Workbench</Text>
+      </Fixed>
+      <Split gap={1} sizes={["44%", "1fr", "28%"]} breakpoints={[{ maxCols: 82, direction: "column", sizes: ["2fr", "1fr", "1fr"], gap: 1 }]}>
+        <Pane style={{ background: "#111827", padding: { x: 1, y: 0 } }}>
+          <Fixed position="top" size={1}>
+            <Text>2,000 jobs · virtualized viewport</Text>
+          </Fixed>
+          <List
+            id="virtualized-jobs"
+            virtualized
+            wrap
+            items={state.items}
+            itemKey={(item) => item.id}
+            onchange={(event) => {
+              observeListState(state, event);
+              state.lastAction = `active moved to ${event.key}`;
+            }}
+            onpress={(event) => {
+              observeListState(state, event);
+              state.lastAction = `selected ${event.key}`;
+            }}
+            ondoublepress={(event) => {
+              observeListState(state, event);
+              state.lastAction = `double pressed ${event.key}`;
+            }}
+            onviewportchange={(event) => {
+              observeListState(state, event);
+              state.lastAction = `viewport ${event.offset}-${event.offset + Math.max(0, event.rows - 1)}`;
+            }}
+          >
+            {(item, ctx) => `${ctx.active ? "active" : "      "} ${ctx.selected ? "✓" : " "} ${ctx.key} ${item.title} · ${item.status}`}
+          </List>
+        </Pane>
+        <Pane style={{ background: "#1f2937", padding: { x: 1, y: 0 } }}>
+          <Text>Selection detail</Text>
+          <Table>
+            <Row><Td><Text>Selected</Text></Td><Td><Text>{selected.id}</Text></Td></Row>
+            <Row><Td><Text>Title</Text></Td><Td><Text>{selected.title}</Text></Td></Row>
+            <Row><Td><Text>Team</Text></Td><Td><Text>{selected.team}</Text></Td></Row>
+            <Row><Td><Text>Status</Text></Td><Td><Text>{selected.status}</Text></Td></Row>
+          </Table>
+          <Text>Active row: {active.id}</Text>
+          <Text>Active follows J/K, arrow keys, PageUp, PageDown, Home, and End. Enter selects.</Text>
+          <Text>Shift+Up/Down run custom app actions here. The List does not reorder by default.</Text>
+        </Pane>
+        <Pane style={{ background: "#0f172a", padding: { x: 1, y: 0 } }}>
+          <Text>Viewport state</Text>
+          <Text>Offset: {String(state.viewportOffset)}</Text>
+          <Text>Active index: {String(state.activeIndex)}</Text>
+          <Text>Selected index: {String(state.selectedIndex)}</Text>
+          <Text>Last action: {state.lastAction}</Text>
+        </Pane>
+      </Split>
+      <Fixed position="bottom" size={1}>
+        <Text>J/K or Up/Down: move active   Shift+Up/Down: custom action   PageUp/PageDown/Home/End: jump   Enter/click: select   Ctrl+C: quit</Text>
+      </Fixed>
+    </Screen>
+  );
+}
+
+export function createVirtualizedListWorkbenchDemo(options: TerminalMountOptions = {}): VirtualizedListWorkbenchDemo {
+  const state = createInitialState();
+  let session: TerminalSession;
+
+  function quit() {
+    state.running = false;
+    session.destroy();
+  }
+
+  session = mountTerminal(<App state={state} />, {
+    ...options,
+    keymap: {
+      ...options.keymap,
+      bindings: [
+        ...(options.keymap?.bindings || []),
+        { key: "j", command: { id: "list.next" }, scope: "list", when: { focusedTag: "terminal-list" } },
+        { key: "J", command: { id: "list.next" }, scope: "list", when: { focusedTag: "terminal-list" } },
+        { key: "k", command: { id: "list.prev" }, scope: "list", when: { focusedTag: "terminal-list" } },
+        { key: "K", command: { id: "list.prev" }, scope: "list", when: { focusedTag: "terminal-list" } },
+        { key: "SHIFT_UP", command: { id: "app.priorityUp" }, scope: "list", when: { focusedTag: "terminal-list" } },
+        { key: "SHIFT_DOWN", command: { id: "app.priorityDown" }, scope: "list", when: { focusedTag: "terminal-list" } },
+        { key: "CTRL_C", command: { id: "quit" }, scope: "global" }
+      ],
+      onCommand(command, context) {
+        if (command.id === "quit") {
+          quit();
+          return true;
+        }
+        if (command.id === "app.priorityUp" || command.id === "app.priorityDown") {
+          const label = command.id === "app.priorityUp" ? "priority up" : "priority down";
+          state.lastAction = `${label} for ${activeItem(state).id}`;
+          return true;
+        }
+        return options.keymap?.onCommand?.(command, context);
+      }
+    }
+  });
+  session.focus("virtualized-jobs");
+
+  return {
+    session,
+    dispatchKey(key: string) {
+      return session.dispatchKey(key);
+    },
+    output() {
+      return session.output();
+    },
+    ansiOutput() {
+      return session.ansiOutput();
+    },
+    isRunning() {
+      return state.running;
+    },
+    destroy() {
+      state.running = false;
+      session.destroy();
+    }
+  };
+}
+
+if (import.meta.main) {
+  if (shouldRunSnapshot()) {
+    const demo = createVirtualizedListWorkbenchDemo({ runtime: "headless", cols: 104, rows: 18 });
+    process.stdout.write(demo.output());
+    process.stdout.write("\n");
+    demo.destroy();
+  } else {
+    createVirtualizedListWorkbenchDemo();
+  }
+}

package/examples/opencode-dogfood-app.tsx

@@ -0,0 +1,215 @@
+import { Editor, Fixed, List, Overlay, Pane, Screen, ScrollView, Split, Text, mountTerminal } from "../dist/index.js";
+import { createStreamLog } from "../dist/stream-log.js";
+
+const TRANSCRIPT_VIEW_ROWS = 5;
+const DOGFOOD_ACTIONS = [
+  { label: "Summarize conversation", status: "Summary ready", activity: "Summarized conversation" },
+  { label: "Prepare next step", status: "Next step ready", activity: "Prepared next step" },
+  { label: "Review updates", status: "Updates ready", activity: "Reviewed updates" }
+] as const;
+
+function sanitizeBoxLine(value: string) {
+  let sanitized = "";
+  for (const char of value) {
+    if (char.charCodeAt(0) !== 27) {
+      sanitized += char;
+    }
+  }
+  return sanitized;
+}
+
+function physicalBoxLines(lines: string[]) {
+  const rows: string[] = [];
+  for (const line of lines) {
+    const parts = line.split(/\r\n|\r|\n/);
+    for (const part of parts) {
+      rows.push(sanitizeBoxLine(part));
+    }
+  }
+  return rows;
+}
+
+function renderLines(lines: string[]) {
+  return physicalBoxLines(lines).map((line, index) => <Text key={index}>{line}</Text>);
+}
+
+function tailLines(lines: string[], visibleRows: number) {
+  const physical = physicalBoxLines(lines);
+  return physical.slice(Math.max(0, physical.length - visibleRows));
+}
+
+export function createDogfoodDemoState() {
+  return {
+    prompt: "",
+    submitted: "",
+    assistant: "",
+    status: "Ready",
+    hasToolEvent: false,
+    commandPaletteOpen: false,
+    selectedActionIndex: 0,
+    commandPaletteOpenSerial: 0,
+    actionListId: "dogfood-action-list-0",
+    paletteActionSerial: 0,
+    streamLog: createStreamLog()
+  };
+}
+
+export type DogfoodDemoState = ReturnType<typeof createDogfoodDemoState>;
+
+export function runDogfoodAction(state: DogfoodDemoState, actionIndex = state.selectedActionIndex) {
+  const action = DOGFOOD_ACTIONS[actionIndex] || DOGFOOD_ACTIONS[0];
+  const serial = state.paletteActionSerial;
+  state.paletteActionSerial += 1;
+  state.commandPaletteOpen = false;
+  state.status = action.status;
+  state.hasToolEvent = true;
+  state.streamLog.append({ id: `palette-action-${serial}`, type: "log", content: action.activity });
+}
+
+export function openDogfoodCommandPalette(state: DogfoodDemoState) {
+  state.commandPaletteOpen = true;
+  state.selectedActionIndex = 0;
+  state.commandPaletteOpenSerial += 1;
+  state.actionListId = `dogfood-action-list-${state.commandPaletteOpenSerial}`;
+}
+
+export function closeDogfoodCommandPalette(state: DogfoodDemoState) {
+  state.commandPaletteOpen = false;
+}
+
+export function DogfoodDemoApp(props: { state: DogfoodDemoState }) {
+  const { state } = props;
+  const snapshot = state.streamLog.snapshot();
+  const transcript: string[] = [];
+  const activity: string[] = [];
+  for (const entry of snapshot.entries) {
+    if (entry.id === "activity-review-context" || (entry.type === "log" && entry.id !== "user-prompt")) {
+      activity.push(entry.content);
+      continue;
+    }
+    if (entry.id === "user-prompt") {
+      transcript.push("You", entry.content);
+      continue;
+    }
+    if (entry.id === "assistant-response") {
+      transcript.push("Assistant", entry.content);
+      continue;
+    }
+    if (entry.type === "assistant") {
+      transcript.push(entry.content);
+    }
+  }
+  if (transcript.length === 0) {
+    if (state.submitted || state.assistant) {
+      transcript.push(
+        state.submitted ? "You" : "Ready when you are",
+        state.submitted || "",
+        state.assistant ? "Assistant" : "",
+        state.assistant || ""
+      );
+    } else {
+      transcript.push("Ready when you are");
+    }
+  }
+  const visibleTranscript = tailLines(transcript, TRANSCRIPT_VIEW_ROWS);
+  const visibleActivity = tailLines(activity, TRANSCRIPT_VIEW_ROWS);
+
+  function submit(value: string) {
+    state.submitted = value;
+    state.prompt = "";
+    state.streamLog = createStreamLog();
+    if (value) {
+      state.streamLog.append({ id: "user-prompt", type: "log", content: value });
+      state.streamLog.update("assistant-response", "Response complete");
+      state.streamLog.complete("assistant-response");
+      state.streamLog.append({ id: "activity-review-context", type: "log", content: "Review project context" });
+    }
+    state.assistant = value ? "Response complete" : "Write a message, then press Enter.";
+    state.status = value ? "Response complete" : "Ready";
+    state.hasToolEvent = Boolean(value);
+  }
+
+  function cancel() {
+    if (!state.submitted || state.status === "Interrupted") {
+      return;
+    }
+    state.status = "Interrupted";
+  }
+
+  return (
+    <Screen>
+      <Fixed position="top" size={6}>
+        <Pane fill style="pane.header" padding={1}>
+          <Text>Project Assistant</Text>
+          <Text>Status: {state.status}</Text>
+        </Pane>
+      </Fixed>
+      <Split direction="row" fill gap={0}>
+        <Pane fill style="pane.transcript" padding={1}>
+          <Text>Conversation</Text>
+          <ScrollView height={TRANSCRIPT_VIEW_ROWS}>{renderLines(visibleTranscript)}</ScrollView>
+        </Pane>
+        <Pane fill style="pane.tools" padding={1}>
+          <Text>Activity</Text>
+          <ScrollView height={TRANSCRIPT_VIEW_ROWS}>
+            {state.hasToolEvent ? renderLines(visibleActivity.length > 0 ? visibleActivity : ["Review project context"]) : <Text>No activity yet</Text>}
+          </ScrollView>
+        </Pane>
+      </Split>
+      <Fixed position="bottom" size={10}>
+        <Pane fill style="pane.prompt" padding={1}>
+          <Text>Message</Text>
+          <Editor
+            id="prompt"
+            value={state.prompt}
+            height={3}
+            focusable
+            onchange={(event) => (state.prompt = event.value)}
+            onsubmit={(event) => submit(event.value)}
+            oncancel={() => cancel()}
+          />
+          <Text>Enter sends · Esc cancels · Ctrl+C exits</Text>
+          <Text>Shift+Enter adds a new line when supported</Text>
+          <Text>On some terminals, Shift+Enter sends the prompt.</Text>
+        </Pane>
+      </Fixed>
+      {state.commandPaletteOpen ? (
+        <Overlay margin={{ x: "20%", y: "25%" }}>
+          <Pane fill style="pane.tools" padding={1}>
+            <Text>Actions</Text>
+            <List
+              id={state.actionListId}
+              focusable
+              items={DOGFOOD_ACTIONS}
+              renderItem={(action) => action.label}
+              onchange={(event) => (state.selectedActionIndex = event.index)}
+              onpress={(event) => runDogfoodAction(state, event.index)}
+            />
+            <Text>Enter to run · Esc to close</Text>
+          </Pane>
+        </Overlay>
+      ) : null}
+    </Screen>
+  );
+}
+
+if (import.meta.main) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    const session = mountTerminal(<DogfoodDemoApp state={createDogfoodDemoState()} />, {
+      runtime: "headless",
+      cols: process.stdout.columns ?? 90,
+      rows: process.stdout.rows ?? 24
+    });
+    process.stdout.write(`${session.output()}\n`);
+    session.destroy();
+  } else {
+    const { startDogfoodDemoSession } = await import("./opencode-dogfood-lifecycle.js");
+    startDogfoodDemoSession({
+      stdin: process.stdin,
+      stdout: process.stdout,
+      process,
+      mountTerminal,
+      exit: (code) => process.exit(code)
+    });
+  }
+}

package/examples/opencode-dogfood-lifecycle.tsx

@@ -0,0 +1,194 @@
+import type { TerminalCommand, TerminalSession } from "../dist/index.js";
+import {
+  closeDogfoodCommandPalette,
+  DogfoodDemoApp,
+  createDogfoodDemoState,
+  openDogfoodCommandPalette
+} from "./opencode-dogfood-app.js";
+
+const ENHANCED_KEYBOARD_PROTOCOL_ENABLE = "\u001b[>5u";
+const ENHANCED_KEYBOARD_PROTOCOL_DISABLE = "\u001b[<u";
+
+type StdinLike = {
+  on?: (event: "data", listener: (chunk: string | Uint8Array) => void) => unknown;
+  prependListener?: (event: "data", listener: (chunk: string | Uint8Array) => void) => unknown;
+  off?: (event: "data", listener: (chunk: string | Uint8Array) => void) => unknown;
+};
+
+type StdoutLike = {
+  columns?: number;
+  rows?: number;
+  write: (chunk: string) => unknown;
+};
+
+type ProcessSignal = "SIGINT" | "SIGTERM" | "SIGWINCH" | "exit";
+
+type ProcessLike = {
+  on?: (event: ProcessSignal, listener: () => void) => unknown;
+  once?: (event: ProcessSignal, listener: () => void) => unknown;
+  off?: (event: ProcessSignal, listener: () => void) => unknown;
+  removeListener?: (event: ProcessSignal, listener: () => void) => unknown;
+};
+
+function isCtrlC(chunk: string | Uint8Array) {
+  const value = typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
+  return value.length === 1 && value.charCodeAt(0) === 3;
+}
+
+function isEnhancedKeyboardCtrlC(value: string) {
+  if (value.charCodeAt(0) !== 27 || value[1] !== "[" || !value.startsWith("99;", 2) || !value.endsWith("u")) {
+    return false;
+  }
+  const modifier = Number(value.slice(5, -1));
+  return Number.isInteger(modifier) && ((modifier - 1) & 4) === 4;
+}
+
+function isEnhancedKeyboardCtrlCPrefix(value: string) {
+  if (value.length === 0) {
+    return false;
+  }
+  if (
+    value.length <= 5 &&
+    (value.length < 1 || value.charCodeAt(0) === 27) &&
+    (value.length < 2 || value[1] === "[") &&
+    (value.length < 3 || value[2] === "9") &&
+    (value.length < 4 || value[3] === "9") &&
+    (value.length < 5 || value[4] === ";")
+  ) {
+    return true;
+  }
+  return value.charCodeAt(0) === 27 && value[1] === "[" && value.startsWith("99;", 2) && /^\d*$/.test(value.slice(5));
+}
+
+function enableEnhancedKeyboardProtocol(stdout: StdoutLike) {
+  // Request CSI-u/kitty-style enhanced keyboard reporting so Shift+Enter can
+  // arrive as ESC [ 13 ; 2 u instead of the same carriage return as Enter.
+  stdout.write(ENHANCED_KEYBOARD_PROTOCOL_ENABLE);
+}
+
+function disableEnhancedKeyboardProtocol(stdout: StdoutLike) {
+  // Reset enhanced keyboard reporting for the shell when this manual demo exits.
+  stdout.write(ENHANCED_KEYBOARD_PROTOCOL_DISABLE);
+}
+
+function hasValidTerminalDimension(value: number | undefined): value is number {
+  return Number.isInteger(value) && Number(value) >= 1;
+}
+
+export function startDogfoodDemoSession(deps: {
+  stdin: StdinLike;
+  stdout: StdoutLike;
+  process?: ProcessLike;
+  enhancedKeyboard?: boolean;
+  mountTerminal: (node: unknown, options: Record<string, unknown>) => TerminalSession;
+  exit: (code: number) => unknown;
+}) {
+  const state = createDogfoodDemoState();
+  const enhancedKeyboard = deps.enhancedKeyboard !== false;
+
+  let session: TerminalSession;
+  try {
+    session = deps.mountTerminal(() => <DogfoodDemoApp state={state} />, {
+      alternateScreen: true,
+      hideCursor: true,
+      stdin: deps.stdin,
+      stdout: deps.stdout,
+      clipboard: false,
+      keymap: {
+        bindings: [
+          { key: "CTRL_K", command: { id: "palette.open" }, scope: "global" },
+          {
+            key: "ESCAPE",
+            command: { id: "palette.close" },
+            scope: "global",
+            when: { focusedTag: "terminal-list" }
+          }
+        ],
+        onCommand(command: TerminalCommand) {
+          if (command.id === "palette.open") {
+            openDogfoodCommandPalette(state);
+            session.update();
+            session.focus(state.actionListId);
+            return true;
+          }
+          if (command.id === "palette.close") {
+            closeDogfoodCommandPalette(state);
+            session.update();
+            session.focus("prompt");
+            return true;
+          }
+          return false;
+        }
+      }
+    });
+    session.focus("prompt");
+    if (enhancedKeyboard) {
+      enableEnhancedKeyboardProtocol(deps.stdout);
+    }
+  } catch (error) {
+    throw error;
+  }
+
+  let closed = false;
+  let pendingCtrlCChunk = "";
+  function removeProcessListener(event: ProcessSignal, listener: () => void) {
+    if (typeof deps.process?.off === "function") {
+      deps.process.off(event, listener);
+      return;
+    }
+    deps.process?.removeListener?.(event, listener);
+  }
+
+  function cleanup() {
+    if (closed) {
+      return;
+    }
+    closed = true;
+    deps.stdin.off?.("data", onGlobalData);
+    removeProcessListener("SIGINT", shutdown);
+    removeProcessListener("SIGTERM", shutdown);
+    removeProcessListener("SIGWINCH", resizeFromStdout);
+    removeProcessListener("exit", cleanup);
+    if (enhancedKeyboard) {
+      disableEnhancedKeyboardProtocol(deps.stdout);
+    }
+    session.destroy();
+  }
+
+  function shutdown() {
+    cleanup();
+    deps.exit(0);
+  }
+
+  function resizeFromStdout() {
+    const cols = deps.stdout.columns;
+    const rows = deps.stdout.rows;
+    if (!hasValidTerminalDimension(cols) || !hasValidTerminalDimension(rows)) {
+      return;
+    }
+    session.resize(cols, rows);
+  }
+
+  function onGlobalData(chunk: string | Uint8Array) {
+    const value = typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
+    const candidate = pendingCtrlCChunk + value;
+    if (isCtrlC(chunk) || isEnhancedKeyboardCtrlC(candidate)) {
+      shutdown();
+      return;
+    }
+    pendingCtrlCChunk = isEnhancedKeyboardCtrlCPrefix(candidate) ? candidate : "";
+  }
+
+  if (typeof deps.stdin.prependListener === "function") {
+    deps.stdin.prependListener("data", onGlobalData);
+  } else {
+    deps.stdin.on?.("data", onGlobalData);
+  }
+
+  deps.process?.once?.("SIGINT", shutdown);
+  deps.process?.once?.("SIGTERM", shutdown);
+  deps.process?.on?.("SIGWINCH", resizeFromStdout);
+  deps.process?.once?.("exit", cleanup);
+
+  return { cleanup, session, state };
+}

package/examples/opencode-dogfood.tsx

@@ -0,0 +1,11 @@
+#!/usr/bin/env bun
+import { mountTerminal } from "../dist/index.js";
+import { startDogfoodDemoSession } from "./opencode-dogfood-lifecycle.js";
+
+startDogfoodDemoSession({
+  stdin: process.stdin,
+  stdout: process.stdout,
+  process,
+  mountTerminal,
+  exit: (code) => process.exit(code)
+});