@valyrianjs/terminal 0.1.0 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valyrianjs/terminal",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Terminal adapter for valyrian.js",
   "license": "Apache-2.0",
   "private": false,
@@ -23,22 +23,35 @@
   "files": [
     "dist",
     "docs",
+    "src",
+    "!docs/local-demo.md",
+    "!docs/plans",
     "README.md",
     "tsconfig.json",
-    "tsconfig.build.json"
+    "tsconfig.build.json",
+    "llms-full.txt"
   ],
   "scripts": {
-    "test": "bun test",
+    "test": "bun test --max-concurrency=1",
+    "demo:dogfood": "bun examples/opencode-dogfood.tsx",
+    "llms:full": "bun scripts/generate-llms-full.ts",
+    "replay:ansi": "bun scripts/replay-ansi.ts",
     "typecheck": "bunx tsc -p tsconfig.json --noEmit",
     "build": "rm -rf dist && bunx tsc -p tsconfig.build.json"
   },
   "devDependencies": {
-    "@types/node": "^25.3.3",
-    "bun-types": "latest",
-    "typescript": "^5.9.3",
-    "valyrian.js": "^9.1.3"
+    "@types/node": "^25.9.1",
+    "@xterm/headless": "^6.0.0",
+    "bun-types": "^1.3.14",
+    "schema-shield": "^1.0.5",
+    "typescript": "^6.0.3",
+    "valyrian.js": "^9.1.13"
   },
   "peerDependencies": {
     "valyrian.js": "^9.1.3"
+  },
+  "overrides": {
+    "picomatch": "2.3.2",
+    "postcss": "8.5.15"
   }
-}
+}

package/src/ansi.ts

@@ -0,0 +1,269 @@
+import { resolveTerminalStyle, resolveTerminalStyleToken } from "./theme.js";
+import type { CursorPosition, TerminalFrame, TerminalStyleSpan, TerminalTheme } from "./types.js";
+
+export const ANSI_ENTER_ALTERNATE_SCREEN = "\u001b[?1049h";
+export const ANSI_EXIT_ALTERNATE_SCREEN = "\u001b[?1049l";
+export const ANSI_HIDE_CURSOR = "\u001b[?25l";
+export const ANSI_SHOW_CURSOR = "\u001b[?25h";
+
+type AnsiFrameOptions = {
+  showCursor?: boolean;
+  showCursorWhenFrameHasCursor?: boolean;
+  theme?: TerminalTheme;
+};
+
+export type AnsiFrameDiffResult = {
+  changedLineIndexes: number[];
+  outputChunk: string;
+  restoresCursor: boolean;
+};
+
+export function stripCursorMarker(value: string) {
+  return value.replaceAll("|", "");
+}
+
+function spanLayerPriority(span: TerminalStyleSpan) {
+  return span.kind === "focus" ? 0 : 1;
+}
+
+function lineSpans(spans: TerminalStyleSpan[], y: number) {
+  return spans
+    .map((span, index) => ({ span, index }))
+    .filter(({ span }) => span.y === y)
+    .sort((a, b) => a.span.x1 - b.span.x1 || spanLayerPriority(a.span) - spanLayerPriority(b.span) || b.span.x2 - a.span.x2 || a.index - b.index)
+    .map(({ span }) => span);
+}
+
+function tokenStyle(token: ReturnType<typeof resolveTerminalStyleToken>) {
+  if (!token) return undefined;
+  return token.style || token.color || token.background
+    ? { ...token.style, color: token.color ?? token.style?.color, background: token.background ?? token.style?.background }
+    : undefined;
+}
+
+function styleAnsiOpen(style: { color?: string; background?: string } | undefined) {
+  return `${colorAnsi(style?.color, false)}${colorAnsi(style?.background, true)}`;
+}
+
+function styleAnsiClose(style: { color?: string; background?: string } | undefined) {
+  return `${style?.background ? "\u001b[49m" : ""}${style?.color ? "\u001b[39m" : ""}`;
+}
+
+function spanAnsiOpen(span: TerminalStyleSpan, theme?: TerminalTheme) {
+  const { kind, style } = span;
+  if (style) return styleAnsiOpen(style);
+  const token = resolveTerminalStyleToken(kind, theme);
+  const resolvedTokenStyle = tokenStyle(token);
+  if (resolvedTokenStyle) return styleAnsiOpen(resolvedTokenStyle);
+  if (token?.ansiOpen) return token.ansiOpen;
+  try {
+    return styleAnsiOpen(resolveTerminalStyle(kind, theme));
+  } catch {
+    return "";
+  }
+}
+
+function spanAnsiClose(span: TerminalStyleSpan, theme?: TerminalTheme) {
+  const { kind, style } = span;
+  if (style) return styleAnsiClose(style);
+  const token = resolveTerminalStyleToken(kind, theme);
+  const resolvedTokenStyle = tokenStyle(token);
+  if (resolvedTokenStyle) return styleAnsiClose(resolvedTokenStyle);
+  if (token?.ansiClose) return token.ansiClose;
+  try {
+    return styleAnsiClose(resolveTerminalStyle(kind, theme));
+  } catch {
+    return "";
+  }
+}
+
+function colorAnsi(value: string | undefined, background: boolean) {
+  if (!value) return "";
+  const hex = value.startsWith("#") ? value.slice(1) : "";
+  const full = hex.length === 3
+    ? hex.split("").map((part) => part + part).join("")
+    : hex;
+  if (!/^[0-9a-fA-F]{6}$/.test(full)) {
+    throw new RangeError(`Unsupported terminal style color: ${value}`);
+  }
+  const red = Number.parseInt(full.slice(0, 2), 16);
+  const green = Number.parseInt(full.slice(2, 4), 16);
+  const blue = Number.parseInt(full.slice(4, 6), 16);
+  return `\u001b[${background ? 48 : 38};2;${red};${green};${blue}m`;
+}
+
+function renderAnsiLine(line: string, spans: TerminalStyleSpan[], y: number, theme?: TerminalTheme) {
+  let output = "";
+  let visibleColumn = 1;
+  const rowSpans = lineSpans(spans, y);
+  let activeSpanIndex = 0;
+
+  for (let i = 0; i < line.length; i += 1) {
+    while (rowSpans[activeSpanIndex]?.x1 === visibleColumn) {
+      output += spanAnsiOpen(rowSpans[activeSpanIndex], theme);
+      activeSpanIndex += 1;
+    }
+
+    const char = line[i];
+    if (char === "|") {
+      continue;
+    }
+
+    output += char;
+    visibleColumn += 1;
+
+    for (const span of rowSpans) {
+      if (span.x2 === visibleColumn) {
+        if (span.kind !== "focus") {
+          output += spanAnsiClose(span, theme);
+        }
+      }
+    }
+    for (const span of rowSpans) {
+      if (span.x2 === visibleColumn && span.kind === "focus") {
+        output += spanAnsiClose(span, theme);
+      }
+    }
+  }
+
+  for (const span of rowSpans) {
+    if (span.x1 < visibleColumn && span.x2 > visibleColumn) {
+      if (span.kind !== "focus") {
+        output += spanAnsiClose(span, theme);
+      }
+    }
+  }
+  for (const span of rowSpans) {
+    if (span.x1 < visibleColumn && span.x2 > visibleColumn && span.kind === "focus") {
+      output += spanAnsiClose(span, theme);
+    }
+  }
+
+  return output;
+}
+
+function hasPlainAffordance(token: ReturnType<typeof resolveTerminalStyleToken>) {
+  return typeof token !== "undefined" && ("plainPrefix" in token || "plainSuffix" in token);
+}
+
+function formatPlainLine(line: string, spans: TerminalStyleSpan[], y: number, theme?: TerminalTheme) {
+  let output = "";
+  let visibleColumn = 1;
+  const firstFallbackFocusY = lineSpans(spans, y).some((span) => {
+    const token = resolveTerminalStyleToken(span.kind, theme);
+    return span.kind === "focus" && !hasPlainAffordance(token) && span.x1 === 1;
+  })
+    ? Math.min(...spans.filter((span) => span.kind === "focus" && span.x1 === 1).map((span) => span.y))
+    : null;
+  const rowSpans = lineSpans(spans, y).map((span) => {
+    const token = resolveTerminalStyleToken(span.kind, theme);
+    const fallbackFocusMarker = span.kind === "focus"
+      && !token?.plainPrefix
+      && !token?.plainSuffix
+      && span.x1 === 1
+      && y === firstFallbackFocusY
+      && span.x2 <= line.length + 1
+      && !line.trimStart().startsWith(">")
+      && !line.includes("|")
+      && !line.includes("[>");
+    return {
+      ...span,
+      x2: fallbackFocusMarker ? Math.min(span.x2, line.trimEnd().length + 1) : span.x2,
+      plainPrefix: token?.plainPrefix ?? span.style?.plainPrefix ?? (fallbackFocusMarker ? ">" : ""),
+      plainSuffix: token?.plainSuffix ?? span.style?.plainSuffix ?? (fallbackFocusMarker ? "<" : "")
+    };
+  }).filter((span) => Boolean(span.plainPrefix || span.plainSuffix));
+
+  for (let i = 0; i < line.length; i += 1) {
+    const char = line[i];
+    if (char === "|") {
+      output += char;
+      continue;
+    }
+
+    for (const span of rowSpans) {
+      if (span.x1 === visibleColumn) {
+        output += span.plainPrefix;
+      }
+    }
+
+    output += char;
+    visibleColumn += 1;
+
+    for (const span of rowSpans) {
+      if (span.x2 === visibleColumn) {
+        if (span.kind !== "focus") {
+          output += span.plainSuffix;
+        }
+      }
+    }
+    for (const span of rowSpans) {
+      if (span.x2 === visibleColumn && span.kind === "focus") {
+        output += span.plainSuffix;
+      }
+    }
+  }
+
+  for (const span of rowSpans) {
+    if (span.x1 === visibleColumn) {
+      output += span.plainPrefix + span.plainSuffix;
+    }
+  }
+
+  return output;
+}
+
+export function formatPlainFrame(frame: TerminalFrame, options: AnsiFrameOptions = {}) {
+  return frame.lines.map((line, index) => formatPlainLine(line, frame.spans, index + 1, options.theme)).join("\n");
+}
+
+export function toAnsiFrame(lines: string[], cursor: CursorPosition | null, spans: TerminalStyleSpan[] = [], options: AnsiFrameOptions = {}) {
+  const ansiLines = lines.map((line, index) => `${renderAnsiLine(line, spans, index + 1, options.theme)}\u001b[K`);
+  const showCursor = options.showCursor !== false || (options.showCursorWhenFrameHasCursor === true && cursor);
+  const cursorCode = cursor ? `\u001b[${cursor.y};${cursor.x}H${showCursor ? ANSI_SHOW_CURSOR : ""}` : showCursor ? ANSI_SHOW_CURSOR : "";
+  return `\u001b[?25l\u001b[H${ansiLines.join("\n")}${cursorCode}`;
+}
+
+export function createAnsiFrameDiff(
+  previousAnsiLines: string[],
+  nextAnsiLines: string[],
+  cursor: CursorPosition | null,
+  options: AnsiFrameOptions = {}
+): AnsiFrameDiffResult {
+  const changedLineIndexes: number[] = [];
+  const writes: string[] = ["\u001b[?25l"];
+  const maxLines = Math.max(previousAnsiLines.length, nextAnsiLines.length);
+
+  for (let i = 0; i < maxLines; i += 1) {
+    const nextLine = nextAnsiLines[i] || "";
+    const prevLine = previousAnsiLines[i] || "";
+    if (nextLine !== prevLine) {
+      changedLineIndexes.push(i);
+      writes.push(`\u001b[${i + 1};1H${nextLine}\u001b[0m\u001b[K`);
+    }
+  }
+
+  if (cursor) {
+    writes.push(`\u001b[${cursor.y};${cursor.x}H`);
+  }
+  if (options.showCursor !== false || (options.showCursorWhenFrameHasCursor === true && cursor)) {
+    writes.push(ANSI_SHOW_CURSOR);
+  }
+
+  return {
+    changedLineIndexes,
+    outputChunk: writes.join(""),
+    restoresCursor: Boolean(cursor)
+  };
+}
+
+export function createAnsiDiffWriter(options: AnsiFrameOptions = {}) {
+  let previousAnsiLines: string[] = [];
+
+  return function toAnsiDiff(lines: string[], cursor: CursorPosition | null, spans: TerminalStyleSpan[] = []) {
+    const ansiLines = lines.map((line, index) => renderAnsiLine(line, spans, index + 1, options.theme));
+    const diff = createAnsiFrameDiff(previousAnsiLines, ansiLines, cursor, options);
+    previousAnsiLines = ansiLines.slice();
+    return diff.outputChunk;
+  };
+}

package/src/clipboard.ts

@@ -0,0 +1,76 @@
+import { spawnSync } from "node:child_process";
+
+import type { TerminalClipboardAdapter } from "./types.js";
+
+function tryRead(command: string, args: string[]) {
+  try {
+    const result = spawnSync(command, args, { encoding: "utf8" });
+    if (result.status === 0) {
+      return String(result.stdout || "").replace(/\r\n/g, "\n").replace(/\n$/, "");
+    }
+  } catch {
+    return undefined;
+  }
+  return undefined;
+}
+
+function tryWrite(command: string, args: string[], value: string) {
+  try {
+    const result = spawnSync(command, args, { input: value, encoding: "utf8" });
+    return result.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+function createDarwinClipboard(): TerminalClipboardAdapter {
+  return {
+    readText() {
+      return tryRead("pbpaste", []);
+    },
+    writeText(value: string) {
+      tryWrite("pbcopy", [], value);
+    }
+  };
+}
+
+function createWindowsClipboard(): TerminalClipboardAdapter {
+  return {
+    readText() {
+      return tryRead("powershell.exe", ["-NoProfile", "-Command", "Get-Clipboard"]);
+    },
+    writeText(value: string) {
+      if (!tryWrite("clip.exe", [], value)) {
+        tryWrite("powershell.exe", ["-NoProfile", "-Command", "Set-Clipboard"], value);
+      }
+    }
+  };
+}
+
+function createLinuxClipboard(): TerminalClipboardAdapter {
+  return {
+    readText() {
+      return tryRead("wl-paste", ["-n"]) || tryRead("xclip", ["-selection", "clipboard", "-out"]) || tryRead("xsel", ["--clipboard", "--output"]);
+    },
+    writeText(value: string) {
+      if (tryWrite("wl-copy", [], value)) {
+        return;
+      }
+      if (tryWrite("xclip", ["-selection", "clipboard", "-in"], value)) {
+        return;
+      }
+      tryWrite("xsel", ["--clipboard", "--input"], value);
+    }
+  };
+}
+
+export function createSystemClipboardAdapter(): TerminalClipboardAdapter {
+  switch (process.platform) {
+    case "darwin":
+      return createDarwinClipboard();
+    case "win32":
+      return createWindowsClipboard();
+    default:
+      return createLinuxClipboard();
+  }
+}

package/src/editor-state.ts

@@ -0,0 +1,162 @@
+export interface EditorCursor {
+  line: number;
+  column: number;
+}
+
+export interface EditorState {
+  value: string;
+  lines: string[];
+  cursor: EditorCursor;
+  desiredColumn?: number;
+}
+
+export type EditorCursorDirection = "left" | "right" | "up" | "down" | "home" | "end";
+
+export interface EditorOperationResult {
+  value: string;
+  state: EditorState;
+}
+
+export function createEditorState(value: string, cursor?: EditorCursor, desiredColumn?: number): EditorState {
+  return normalizeEditorState(value, cursor, desiredColumn);
+}
+
+export function normalizeEditorState(value: string, cursor?: EditorCursor, desiredColumn?: number): EditorState {
+  const normalizedValue = normalizeLineEndings(value);
+  const lines = normalizedValue.split("\n");
+  const line = clamp(cursor?.line ?? lines.length - 1, 0, lines.length - 1);
+  const column = clamp(cursor?.column ?? lines[line].length, 0, lines[line].length);
+  const state: EditorState = { value: normalizedValue, lines, cursor: { line, column } };
+
+  if (desiredColumn !== undefined) {
+    state.desiredColumn = Math.max(0, Math.trunc(desiredColumn));
+  }
+
+  return state;
+}
+
+export function insertEditorText(value: string, state: EditorState, text: string): EditorOperationResult {
+  const normalizedText = normalizeLineEndings(text);
+  const normalizedState = normalizeEditorState(value, state.cursor);
+  const index = cursorToIndex(normalizedState.lines, normalizedState.cursor);
+  const nextValue = normalizedState.value.slice(0, index) + normalizedText + normalizedState.value.slice(index);
+  const insertedLines = normalizedText.split("\n");
+  const cursor =
+    insertedLines.length === 1
+      ? { line: normalizedState.cursor.line, column: normalizedState.cursor.column + insertedLines[0].length }
+      : {
+          line: normalizedState.cursor.line + insertedLines.length - 1,
+          column: insertedLines[insertedLines.length - 1].length
+        };
+  const nextState = createEditorState(nextValue, cursor);
+
+  return { value: nextState.value, state: nextState };
+}
+
+export function removeEditorBackward(value: string, state: EditorState): EditorOperationResult {
+  const normalizedState = normalizeEditorState(value, state.cursor);
+  const index = cursorToIndex(normalizedState.lines, normalizedState.cursor);
+
+  if (index === 0) {
+    return { value: normalizedState.value, state: normalizedState };
+  }
+
+  const cursor =
+    normalizedState.cursor.column > 0
+      ? { line: normalizedState.cursor.line, column: normalizedState.cursor.column - 1 }
+      : {
+          line: normalizedState.cursor.line - 1,
+          column: normalizedState.lines[normalizedState.cursor.line - 1].length
+        };
+  const nextValue = normalizedState.value.slice(0, index - 1) + normalizedState.value.slice(index);
+  const nextState = createEditorState(nextValue, cursor);
+
+  return { value: nextState.value, state: nextState };
+}
+
+export function removeEditorForward(value: string, state: EditorState): EditorOperationResult {
+  const normalizedState = normalizeEditorState(value, state.cursor);
+  const index = cursorToIndex(normalizedState.lines, normalizedState.cursor);
+
+  if (index >= normalizedState.value.length) {
+    return { value: normalizedState.value, state: normalizedState };
+  }
+
+  const nextValue = normalizedState.value.slice(0, index) + normalizedState.value.slice(index + 1);
+  const nextState = createEditorState(nextValue, normalizedState.cursor);
+
+  return { value: nextState.value, state: nextState };
+}
+
+export function moveEditorCursor(value: string, state: EditorState, direction: EditorCursorDirection): EditorState {
+  const normalizedState = normalizeEditorState(value, state.cursor);
+  const { cursor, lines } = normalizedState;
+
+  if (direction === "left") {
+    if (cursor.column > 0) {
+      return createEditorState(normalizedState.value, { line: cursor.line, column: cursor.column - 1 });
+    }
+
+    if (cursor.line > 0) {
+      return createEditorState(normalizedState.value, { line: cursor.line - 1, column: lines[cursor.line - 1].length });
+    }
+
+    return normalizedState;
+  }
+
+  if (direction === "right") {
+    if (cursor.column < lines[cursor.line].length) {
+      return createEditorState(normalizedState.value, { line: cursor.line, column: cursor.column + 1 });
+    }
+
+    if (cursor.line < lines.length - 1) {
+      return createEditorState(normalizedState.value, { line: cursor.line + 1, column: 0 });
+    }
+
+    return normalizedState;
+  }
+
+  if (direction === "home") {
+    return createEditorState(normalizedState.value, { line: cursor.line, column: 0 });
+  }
+
+  if (direction === "end") {
+    return createEditorState(normalizedState.value, { line: cursor.line, column: lines[cursor.line].length });
+  }
+
+  const desiredColumn = state.desiredColumn ?? cursor.column;
+  const nextLine = direction === "up" ? cursor.line - 1 : cursor.line + 1;
+
+  if (nextLine < 0 || nextLine >= lines.length) {
+    return withDesiredColumn(normalizedState, desiredColumn);
+  }
+
+  const nextState = createEditorState(normalizedState.value, {
+    line: nextLine,
+    column: Math.min(desiredColumn, lines[nextLine].length)
+  });
+
+  return withDesiredColumn(nextState, desiredColumn);
+}
+
+function normalizeLineEndings(value: string): string {
+  return value.replace(/\r\n?/g, "\n");
+}
+
+function cursorToIndex(lines: string[], cursor: EditorCursor): number {
+  let index = 0;
+
+  for (let line = 0; line < cursor.line; line++) {
+    index += lines[line].length + 1;
+  }
+
+  return index + cursor.column;
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(Math.trunc(value), min), max);
+}
+
+function withDesiredColumn(state: EditorState, desiredColumn: number): EditorState {
+  return { value: state.value, lines: [...state.lines], cursor: { ...state.cursor }, desiredColumn };
+}