@deckbuilderkit/terminal 0.0.0-stage → 0.1.0

package/src/appearance.ts

@@ -0,0 +1,56 @@
+export const FONT_WEIGHTS = ['normal', 'bold', '100', '200', '300', '400', '500', '600', '700', '800', '900'] as const;
+export const CURSOR_STYLES = ['block', 'bar', 'underline'] as const;
+
+/** The look of one profile; a set field wins over the global terminal setting of the same name. */
+export interface ProfileAppearance {
+  fontFamily?: string;
+  /** Pixels, 8 to 32. */
+  fontSize?: number;
+  fontWeight?: (typeof FONT_WEIGHTS)[number];
+  /** 1 to 2. */
+  lineHeight?: number;
+  /** A preset id or a custom scheme id; an unknown one follows the app. */
+  theme?: string;
+  cursorStyle?: (typeof CURSOR_STYLES)[number];
+  cursorBlink?: boolean;
+  /** Pixels, 0 to 48. */
+  padding?: number;
+}
+
+type Check = (v: unknown) => boolean;
+const range = (min: number, max: number): Check => (v) => typeof v === 'number' && Number.isFinite(v) && v >= min && v <= max;
+const oneOf = (values: readonly string[]): Check => (v) => typeof v === 'string' && values.includes(v);
+const text = (max: number): Check => (v) => typeof v === 'string' && v.length <= max;
+
+/** Same ranges as the flat `terminal.*` settings. */
+const APPEARANCE_SPEC: Record<keyof ProfileAppearance, Check> = {
+  fontFamily: text(300),
+  fontSize: range(8, 32),
+  fontWeight: oneOf(FONT_WEIGHTS),
+  lineHeight: range(1, 2),
+  theme: (v) => typeof v === 'string' && /^[\w.-]{1,64}$/.test(v),
+  cursorStyle: oneOf(CURSOR_STYLES),
+  cursorBlink: (v) => typeof v === 'boolean',
+  padding: range(0, 48),
+};
+
+/** A profile's `appearance` with only known keys and values in range; else null. */
+export function validAppearance(v: unknown): ProfileAppearance | null {
+  if (typeof v !== 'object' || v === null || Array.isArray(v)) return null;
+  for (const [k, x] of Object.entries(v)) {
+    const check = APPEARANCE_SPEC[k as keyof ProfileAppearance];
+    if (!Object.hasOwn(APPEARANCE_SPEC, k) || !check(x)) return null;
+  }
+  return v as ProfileAppearance;
+}
+
+/** `base` with the set fields of `appearance` over it (an empty font family keeps the base one). */
+export function withAppearance<T extends object>(base: T | undefined, appearance: ProfileAppearance | undefined): T | undefined {
+  if (!appearance) return base;
+  const out: Record<string, unknown> = { ...base };
+  for (const [k, v] of Object.entries(appearance)) {
+    if (v === undefined || (k === 'fontFamily' && typeof v === 'string' && !v.trim())) continue;
+    out[k] = v;
+  }
+  return out as T;
+}

package/src/client.ts

@@ -0,0 +1,63 @@
+import { errorOf, request } from '@deckbuilderkit/ui';
+import { TERMINAL_SOCKET_PATH } from './protocol.ts';
+import type { SessionInfo, TerminalProfile, TerminalProfileInfo } from './protocol.ts';
+
+export type { SessionInfo, TerminalProfile, TerminalProfileInfo };
+
+/** A project directory: a root id and a path relative to it. */
+export interface TerminalCwd {
+  root: string;
+  path: string;
+}
+
+/** A program the app registered on the server, with the args its launcher validates. */
+export interface TerminalLaunch {
+  id: string;
+  args?: unknown;
+}
+
+export interface Ticketed {
+  session: string;
+  ticket: string;
+}
+
+/**
+ * Opens a session. `profile` is a profile id (default: the `defaultProfile` setting); `dir` is an
+ * absolute directory to start in (a missing one falls back to the profile/default cwd); `cwd` wins over both.
+ */
+export function openSession(opts: { cols: number; rows: number; cwd?: TerminalCwd; launch?: TerminalLaunch; profile?: string; dir?: string }): Promise<Ticketed> {
+  const { cols, rows, cwd, launch, profile, dir } = opts;
+  return request<Ticketed>('POST', '/api/terminal/open', {}, { cols, rows, root: cwd?.root, path: cwd?.path, launch, profile, dir });
+}
+
+/** Shell ids installed on the server (for the default shell select). */
+export function listShells(): Promise<string[]> {
+  return request<string[]>('GET', '/api/terminal/shells');
+}
+
+/** Built-in profiles (installed shells, overrides applied), then custom ones. */
+export function listProfiles(): Promise<TerminalProfileInfo[]> {
+  return request<TerminalProfileInfo[]>('GET', '/api/terminal/profiles');
+}
+
+export function attachSession(session: string, view: 'interactive' | 'preview' = 'interactive'): Promise<Ticketed> {
+  return request<Ticketed>('POST', '/api/terminal/attach', {}, { session, view });
+}
+
+/** Kills a session (a tab close). Unknown ids are a no-op. */
+export async function closeSession(session: string): Promise<void> {
+  await request('POST', '/api/terminal/close', {}, { session });
+}
+
+export function listSessions(): Promise<SessionInfo[]> {
+  return request<SessionInfo[]>('GET', '/api/terminal/sessions');
+}
+
+/** True for the error `attach` throws when the session is gone. */
+export const isSessionGone = (err: unknown): boolean => errorOf(err).code === 'terminalSession';
+
+/** The socket URL for a ticket, on the page's own origin. */
+export function socketUrl(ticket: string, loc: { protocol: string; host: string } = location): string {
+  const scheme = loc.protocol === 'https:' ? 'wss:' : 'ws:';
+  return `${scheme}//${loc.host}${TERMINAL_SOCKET_PATH}?t=${encodeURIComponent(ticket)}`;
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+export { attachSession, closeSession, isSessionGone, listProfiles, listSessions, openSession, socketUrl, type SessionInfo, type TerminalCwd, type TerminalLaunch, type TerminalProfile, type TerminalProfileInfo, type Ticketed } from './client.ts';
+export { PANE_COMMANDS, terminalKeyAction, type PaneCommand, type TerminalKeyAction } from './keys.ts';
+export { TerminalPane, type TerminalPaneHandle, type TerminalPaneProps } from './TerminalPane.tsx';
+export { DEFAULT_WORD_SEPARATORS, TerminalOptionsContext } from './terminalOptions.ts';
+export { readCssToken, xtermTheme } from './theme.ts';
+export { resolveThemeId, TERMINAL_THEMES, themeOf, type TerminalThemeId } from './themes.ts';
+export { validAppearance, withAppearance, type ProfileAppearance } from './appearance.ts';
+export { parseWindowsTerminalSchemes, schemeTheme, SCHEME_COLORS, validSchemes, type ColorScheme } from './schemes.ts';
+export { continuationOf, pasteNeedsWarning, pasteSummary, sanitizePaste, trimCopied, type PasteWarning } from './paste.ts';
+export { formatTabTitle, parseOsc133, parseOsc7, type PromptMark, type TitleVars } from './shell-integration.ts';
+export type { TerminalView } from './view.ts';
+export { createXtermView, type TerminalFontWeight, type TerminalOptions, type XtermView, type XtermViewOptions } from './xterm-view.ts';
+export { terminalAppKeys } from './app-keys';

package/src/keys.ts

@@ -0,0 +1,48 @@
+import { chordOf, type KeyLike } from '@deckbuilderkit/ui/keybindings';
+
+/**
+ * Commands a terminal pane runs itself, with their default keys (the fallback without a keymap;
+ * the app lists the same ids and keys so they show in its shortcuts).
+ */
+export const PANE_COMMANDS = {
+  'terminal.zoomIn': ['Ctrl+=', 'Ctrl++', 'Ctrl+Shift++'],
+  'terminal.zoomOut': ['Ctrl+-'],
+  'terminal.zoomReset': ['Ctrl+0'],
+  'terminal.scrollLineUp': ['Ctrl+Shift+ArrowUp'],
+  'terminal.scrollLineDown': ['Ctrl+Shift+ArrowDown'],
+  'terminal.scrollPageUp': ['Ctrl+Shift+PageUp'],
+  'terminal.scrollPageDown': ['Ctrl+Shift+PageDown'],
+  'terminal.scrollTop': ['Ctrl+Shift+Home'],
+  'terminal.scrollBottom': ['Ctrl+Shift+End'],
+  'terminal.clear': ['Ctrl+Shift+K'],
+} as const satisfies Record<string, readonly string[]>;
+export type PaneCommand = keyof typeof PANE_COMMANDS;
+
+/** What a key pressed inside the terminal does. */
+export type TerminalKeyAction = 'app' | 'find' | 'prevCommand' | 'nextCommand' | 'copy' | 'paste' | 'terminal' | PaneCommand;
+
+/**
+ * Keys go to the program, except the find chord (opens the find bar), the previous/next command chords, the pane command
+ * chords (`pane`: chord to command), chords of the allowed app commands, Ctrl+C / Ctrl+Shift+C with text selected (copy),
+ * and Ctrl+V / Ctrl+Shift+V (paste).
+ */
+export function terminalKeyAction(
+  e: KeyLike,
+  hasSelection: boolean,
+  appChords: ReadonlySet<string>,
+  findChords: ReadonlySet<string> = new Set(),
+  navChords: { prev: ReadonlySet<string>; next: ReadonlySet<string> } = { prev: new Set(), next: new Set() },
+  pane: ReadonlyMap<string, PaneCommand> = new Map(),
+): TerminalKeyAction {
+  const chord = chordOf(e);
+  if (!chord) return 'terminal';
+  if (findChords.has(chord)) return 'find';
+  if (navChords.prev.has(chord)) return 'prevCommand';
+  if (navChords.next.has(chord)) return 'nextCommand';
+  const own = pane.get(chord);
+  if (own) return own;
+  if (appChords.has(chord)) return 'app';
+  if ((chord === 'Ctrl+C' || chord === 'Ctrl+Shift+C') && hasSelection) return 'copy';
+  if (chord === 'Ctrl+V' || chord === 'Ctrl+Shift+V') return 'paste';
+  return 'terminal';
+}

package/src/paste.ts

@@ -0,0 +1,64 @@
+/** When a paste asks first: 'multiLine' on a line break or a large paste, 'large' only on a large one. */
+export type PasteWarning = 'multiLine' | 'large' | 'never';
+
+/** Whether pasting `text` asks first. */
+export function pasteNeedsWarning(text: string, mode: PasteWarning, largeSize: number): boolean {
+  if (mode === 'never') return false;
+  if (text.length > largeSize) return true;
+  return mode === 'multiLine' && /[\r\n]/.test(text);
+}
+
+/** Line count, size and the first lines (each cut short) of a paste, for the warning. */
+export function pasteSummary(text: string, maxLines = 5, maxWidth = 120): { lines: number; chars: number; preview: string } {
+  const all = text.replace(/\r\n?/g, '\n').replace(/\n$/, '').split('\n');
+  const preview = all
+    .slice(0, maxLines)
+    .map((l) => (l.length > maxWidth ? `${l.slice(0, maxWidth)}…` : l))
+    .join('\n');
+  return { lines: all.length, chars: text.length, preview: all.length > maxLines ? `${preview}\n…` : preview };
+}
+
+/** Line continuation of a shell: what ends a line so the next one joins the same pending command. */
+export function continuationOf(shell: string | undefined): string {
+  switch (shell) {
+    case 'bash':
+    case 'zsh':
+    case 'sh':
+    case 'fish':
+    case 'git-bash':
+    case 'wsl':
+      return ' \\\n';
+    case 'pwsh':
+    case 'powershell':
+      return ' `\n';
+    case 'cmd':
+      return ' ^\n';
+    default:
+      return ' ';
+  }
+}
+
+// eslint-disable-next-line no-control-regex
+const ESCAPES = /\x1b\[[0-?]*[ -/]*[@-~]|\x9b[0-?]*[ -/]*[@-~]|\x1b\][^\x07\x1b\x9c]*(?:\x07|\x1b\\|\x9c)?|\x9d[^\x07\x1b\x9c]*(?:\x07|\x1b\\|\x9c)?|\x1b[PX^_][^\x1b\x9c]*(?:\x1b\\|\x9c)?|\x1b[ -/]*[0-~]?/g;
+// eslint-disable-next-line no-control-regex
+const CONTROLS = /[\x00-\x08\x0b-\x1f\x7f-\x9f]/g;
+
+/**
+ * A paste that cannot run anything before the user presses Enter: escape sequences (injected
+ * bracketed-paste markers too) and control characters other than tab and newline removed, trailing
+ * line breaks dropped. With `bracketed` (the program turned bracketed paste on) the lines stay as
+ * they are, for the terminal to bracket; otherwise they are joined with the shell's line
+ * continuation (`continuationOf`), so they stay one pending command.
+ */
+export function sanitizePaste(text: string, opts: { bracketed: boolean; shell?: string }): string {
+  const lines = text
+    .replace(/\r\n/g, '\n')
+    .replace(ESCAPES, '')
+    .replace(CONTROLS, '')
+    .replace(/\s+$/, '')
+    .split('\n');
+  return opts.bracketed ? lines.join('\n') : lines.join(continuationOf(opts.shell));
+}
+
+/** Copied text without the trailing spaces of each line. */
+export const trimCopied = (text: string): string => text.replace(/ +$/gm, '');

package/src/protocol.ts

@@ -0,0 +1,146 @@
+import type { ProfileAppearance } from './appearance.ts';
+
+export const TERMINAL_SOCKET_PATH = '/api/terminal/socket';
+export const MAX_COLS = 1000;
+export const MAX_ROWS = 1000;
+export const MAX_CONTROL_BYTES = 64 * 1024;
+export const MAX_TITLE = 256;
+
+export const SHELL_IDS = ['auto', 'powershell', 'pwsh', 'cmd', 'git-bash', 'wsl', 'bash', 'zsh', 'fish', 'sh'] as const;
+export type ShellId = (typeof SHELL_IDS)[number];
+
+export const isShellId = (x: unknown): x is ShellId => typeof x === 'string' && (SHELL_IDS as readonly string[]).includes(x);
+
+/** Display names of the built-in profiles (one per installed shell). */
+export const SHELL_NAMES: Record<Exclude<ShellId, 'auto'>, string> = {
+  powershell: 'PowerShell',
+  pwsh: 'PowerShell 7',
+  cmd: 'Command Prompt',
+  'git-bash': 'Git Bash',
+  wsl: 'WSL',
+  bash: 'bash',
+  zsh: 'zsh',
+  fish: 'fish',
+  sh: 'sh',
+};
+
+/** Default icon names of the built-in profiles. */
+export const SHELL_ICONS: Record<Exclude<ShellId, 'auto'>, string> = {
+  powershell: 'terminal-powershell',
+  pwsh: 'terminal-pwsh',
+  cmd: 'terminal-cmd',
+  'git-bash': 'terminal-git-bash',
+  wsl: 'terminal-wsl',
+  bash: 'shell-bash',
+  zsh: 'shell-zsh',
+  fish: 'shell-fish',
+  sh: 'shell-bash',
+};
+
+/**
+ * A terminal profile. Built-ins have a shell id as `id`; a saved entry with that id overrides
+ * name, icon, args (appended to the shell's own), env, cwd, hidden, shellIntegration and appearance.
+ * Other ids are custom: `shell: 'custom'` runs `command` (absolute path) with `args`; a known
+ * `shell` runs that shell with `args` appended.
+ */
+export interface TerminalProfile {
+  id: string;
+  name: string;
+  shell: ShellId | 'custom';
+  command?: string;
+  args?: string[];
+  env?: Record<string, string>;
+  cwd?: string;
+  icon?: string;
+  hidden?: boolean;
+  shellIntegration?: boolean;
+  /** Look of this profile's panes over the global terminal settings. */
+  appearance?: ProfileAppearance;
+}
+
+/** A profile as `GET /api/terminal/profiles` lists it: built-ins first, then custom ones. */
+export interface TerminalProfileInfo extends TerminalProfile {
+  /** False when the shell or command is not on this machine. */
+  available: boolean;
+}
+
+/** `clear` drops the session's scrollback on the server too, so a reattach does not bring it back. */
+export type ClientControl = { type: 'resize'; cols: number; rows: number } | { type: 'close' } | { type: 'clear' };
+
+export type ServerControl =
+  | { type: 'hello'; session: string; cols: number; rows: number }
+  | { type: 'exit'; code: number | null }
+  | { type: 'title'; title: string };
+
+export type ClientMessage = { kind: 'input'; data: Uint8Array } | { kind: 'control'; msg: ClientControl };
+export type ServerMessage = { kind: 'output'; data: Uint8Array } | { kind: 'control'; msg: ServerControl };
+
+/** A session as `GET /api/terminal/sessions` lists it. */
+export interface SessionInfo {
+  id: string;
+  label: string;
+  launcher?: string;
+  meta?: Record<string, unknown>;
+  /** Start directory, then the last one shell integration reported (OSC 7). */
+  cwd: string;
+  /** Profile id the session was opened with, if any. */
+  profile?: string;
+  /** Shell id used (`custom` for a custom command); absent for launchers. */
+  shell?: string;
+  /** Shell integration (OSC 133): true while a command runs; absent without integration. */
+  running?: boolean;
+  cols: number;
+  rows: number;
+  createdAt: number;
+  exited: number | null | undefined;
+  title: string;
+  bells: number;
+  lastOutputAt: number;
+  viewers: { interactive: boolean; previews: number };
+}
+
+type Frame = string | ArrayBuffer | Uint8Array;
+
+export const encodeControl = (msg: ClientControl | ServerControl): string => JSON.stringify(msg);
+
+const isSize = (n: unknown, max: number): n is number => typeof n === 'number' && Number.isInteger(n) && n >= 1 && n <= max;
+
+const parseControl = (text: string): Record<string, unknown> | null => {
+  if (text.length > MAX_CONTROL_BYTES) return null;
+  try {
+    const v: unknown = JSON.parse(text);
+    return typeof v === 'object' && v !== null && !Array.isArray(v) ? (v as Record<string, unknown>) : null;
+  } catch {
+    return null;
+  }
+};
+
+const bytes = (frame: ArrayBuffer | Uint8Array): Uint8Array => (frame instanceof Uint8Array ? frame : new Uint8Array(frame));
+
+export function decodeClientMessage(frame: Frame): ClientMessage | null {
+  if (typeof frame !== 'string') return { kind: 'input', data: bytes(frame) };
+  const m = parseControl(frame);
+  if (!m) return null;
+  if (m.type === 'close') return { kind: 'control', msg: { type: 'close' } };
+  if (m.type === 'clear') return { kind: 'control', msg: { type: 'clear' } };
+  if (m.type === 'resize' && isSize(m.cols, MAX_COLS) && isSize(m.rows, MAX_ROWS)) {
+    return { kind: 'control', msg: { type: 'resize', cols: m.cols, rows: m.rows } };
+  }
+  return null;
+}
+
+export function decodeServerMessage(frame: Frame): ServerMessage | null {
+  if (typeof frame !== 'string') return { kind: 'output', data: bytes(frame) };
+  const m = parseControl(frame);
+  if (!m) return null;
+  if (m.type === 'hello' && typeof m.session === 'string' && isSize(m.cols, MAX_COLS) && isSize(m.rows, MAX_ROWS)) {
+    return { kind: 'control', msg: { type: 'hello', session: m.session, cols: m.cols, rows: m.rows } };
+  }
+  if (m.type === 'exit' && (m.code === null || (typeof m.code === 'number' && Number.isFinite(m.code)))) {
+    return { kind: 'control', msg: { type: 'exit', code: m.code } };
+  }
+  if (m.type === 'title' && typeof m.title === 'string') {
+    return { kind: 'control', msg: { type: 'title', title: m.title.slice(0, MAX_TITLE) } };
+  }
+  return null;
+}

package/src/schemes.ts

@@ -0,0 +1,145 @@
+import type { ITheme } from '@xterm/xterm';
+
+/** The 16 ANSI colors of a scheme, in Windows Terminal's key names (`purple` is xterm's `magenta`). */
+export const SCHEME_COLORS = [
+  'black', 'red', 'green', 'yellow', 'blue', 'purple', 'cyan', 'white',
+  'brightBlack', 'brightRed', 'brightGreen', 'brightYellow', 'brightBlue', 'brightPurple', 'brightCyan', 'brightWhite',
+] as const;
+export type SchemeColor = (typeof SCHEME_COLORS)[number];
+
+/** A custom color scheme (`terminal.schemes`); every color is `#RRGGBB`. */
+export type ColorScheme = {
+  id: string;
+  name: string;
+  foreground: string;
+  background: string;
+  cursor?: string;
+  cursorAccent?: string;
+  selectionBackground?: string;
+} & Record<SchemeColor, string>;
+
+export const MAX_SCHEMES = 100;
+const HEX = /^#[0-9a-fA-F]{6}$/;
+const SCHEME_ID = /^[\w.-]{1,64}$/;
+const OPTIONAL_COLORS = ['cursor', 'cursorAccent', 'selectionBackground'] as const;
+const SCHEME_KEYS = new Set<string>(['id', 'name', 'foreground', 'background', ...OPTIONAL_COLORS, ...SCHEME_COLORS]);
+
+const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
+const isHex = (v: unknown): v is string => typeof v === 'string' && HEX.test(v);
+
+/** A stored scheme with only known keys, a short id and name and `#RRGGBB` colors; else null. */
+export function validScheme(v: unknown): ColorScheme | null {
+  if (!isRecord(v) || !Object.keys(v).every((k) => SCHEME_KEYS.has(k))) return null;
+  if (typeof v.id !== 'string' || !SCHEME_ID.test(v.id)) return null;
+  if (typeof v.name !== 'string' || !v.name || v.name.length > 80) return null;
+  if (!isHex(v.foreground) || !isHex(v.background) || !SCHEME_COLORS.every((k) => isHex(v[k]))) return null;
+  if (!OPTIONAL_COLORS.every((k) => v[k] === undefined || isHex(v[k]))) return null;
+  return v as ColorScheme;
+}
+
+/** Up to MAX_SCHEMES valid schemes with distinct ids, else null. */
+export function validSchemes(raw: unknown): ColorScheme[] | null {
+  if (!Array.isArray(raw) || raw.length > MAX_SCHEMES) return null;
+  const out = raw.map(validScheme);
+  if (out.some((s) => !s)) return null;
+  return new Set(out.map((s) => s!.id)).size === out.length ? (out as ColorScheme[]) : null;
+}
+
+/** The xterm theme of a custom scheme. */
+export function schemeTheme(s: ColorScheme): ITheme {
+  const theme: Record<string, string> = {
+    background: s.background,
+    foreground: s.foreground,
+    cursor: s.cursor ?? s.foreground,
+    cursorAccent: s.cursorAccent ?? s.background,
+  };
+  if (s.selectionBackground) theme.selectionBackground = s.selectionBackground;
+  for (const k of SCHEME_COLORS) theme[k.replace(/purple/i, (m) => (m[0] === 'P' ? 'Magenta' : 'magenta'))] = s[k];
+  return theme as ITheme;
+}
+
+/** JSON text without `//` and `/* *\/` comments and trailing commas (strings left alone). */
+function looseJson(text: string): string {
+  let out = '';
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (c === '"') {
+      let j = i + 1;
+      while (j < text.length && text[j] !== '"') j += text[j] === '\\' ? 2 : 1;
+      out += text.slice(i, j + 1);
+      i = j;
+    } else if (c === '/' && text[i + 1] === '/') {
+      while (i < text.length && text[i] !== '\n') i++;
+      out += '\n';
+    } else if (c === '/' && text[i + 1] === '*') {
+      const end = text.indexOf('*/', i + 2);
+      i = end < 0 ? text.length : end + 1;
+    } else out += c;
+  }
+  return out.replace(/,(\s*[}\]])/g, '$1');
+}
+
+/** `#RGB` / `#RRGGBB` (any case) as lowercase `#rrggbb`; null otherwise. */
+function hexOf(v: unknown): string | null {
+  if (typeof v !== 'string') return null;
+  const s = v.trim();
+  if (/^#[0-9a-fA-F]{6}$/.test(s)) return s.toLowerCase();
+  if (/^#[0-9a-fA-F]{3}$/.test(s)) return `#${[...s.slice(1)].map((x) => x + x).join('')}`.toLowerCase();
+  return null;
+}
+
+const slug = (name: string) =>
+  name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 40) || 'scheme';
+
+/** One Windows Terminal scheme object as a ColorScheme without an id; null when a required color is missing. */
+function fromWindowsTerminal(v: unknown): Omit<ColorScheme, 'id'> | null {
+  if (!isRecord(v) || typeof v.name !== 'string' || !v.name.trim()) return null;
+  const foreground = hexOf(v.foreground);
+  const background = hexOf(v.background);
+  if (!foreground || !background) return null;
+  const out: Record<string, string> = { name: v.name.trim().slice(0, 80), foreground, background };
+  for (const k of SCHEME_COLORS) {
+    const c = hexOf(v[k]);
+    if (!c) return null;
+    out[k] = c;
+  }
+  const cursor = hexOf(v.cursorColor ?? v.cursor);
+  if (cursor) out.cursor = cursor;
+  const accent = hexOf(v.cursorAccent);
+  if (accent) out.cursorAccent = accent;
+  const selection = hexOf(v.selectionBackground);
+  if (selection) out.selectionBackground = selection;
+  return out as Omit<ColorScheme, 'id'>;
+}
+
+/**
+ * Schemes from Windows Terminal JSON: a `schemes` array, one scheme object, or a whole settings.json
+ * (comments and trailing commas allowed). Each gets an id `custom-<name>` unique against `taken` and
+ * the others; invalid entries are skipped, unparsable text gives [].
+ */
+export function parseWindowsTerminalSchemes(json: string, taken: Iterable<string> = []): ColorScheme[] {
+  let data: unknown;
+  try {
+    data = JSON.parse(looseJson(json));
+  } catch {
+    return [];
+  }
+  const list = Array.isArray(data) ? data : isRecord(data) && Array.isArray(data.schemes) ? data.schemes : [data];
+  const used = new Set(taken);
+  const out: ColorScheme[] = [];
+  for (const raw of list) {
+    const s = fromWindowsTerminal(raw);
+    if (!s) continue;
+    const base = `custom-${slug(s.name)}`;
+    let id = base;
+    for (let n = 2; used.has(id); n++) id = `${base}-${n}`;
+    used.add(id);
+    out.push({ id, ...s } as ColorScheme);
+    if (out.length >= MAX_SCHEMES) break;
+  }
+  return out;
+}

package/src/server/index.ts

@@ -0,0 +1,8 @@
+export { isUuid, launchers, type Launcher } from './launchers.ts';
+export { terminalRoutes, type TerminalRoutesOptions } from './routes.ts';
+export { isShellId, SHELL_IDS, type ShellId } from './shells.ts';
+export type { TerminalProfile, TerminalProfileInfo } from '../protocol.ts';
+export { mergeProfiles, profileArgv } from './profiles.ts';
+export { cwdFromOsc7, terminalSessions, type SessionInfo, type TerminalSessions } from './sessions.ts';
+export { validAppearance, withAppearance, type ProfileAppearance } from '../appearance.ts';
+export { parseWindowsTerminalSchemes, validSchemes, type ColorScheme } from '../schemes.ts';

package/src/server/integration/bash.sh

@@ -0,0 +1,62 @@
+# DeckBuilder shell integration for bash (and Git Bash), loaded with --rcfile.
+# Sources the startup files a login shell would, then wraps the prompt with OSC 133 marks and OSC 7.
+if [ -z "${__db_si:-}" ]; then
+  __db_si=1
+  if [ -r /etc/profile ]; then . /etc/profile; fi
+  if [ -r ~/.bash_profile ]; then . ~/.bash_profile
+  elif [ -r ~/.bash_login ]; then . ~/.bash_login
+  elif [ -r ~/.profile ]; then . ~/.profile
+  elif [ -r ~/.bashrc ]; then . ~/.bashrc
+  fi
+
+  __db_first=1
+  __db_ec=0
+  __db_precmd() {
+    __db_ec=$?
+    # A prompt that already emits its own marks (e.g. Windows Terminal's snippet) sends D itself.
+    if [ -z "$__db_first" ] && [ -z "${__db_own_marks:-}" ]; then printf '\033]133;D;%s\007' "$__db_ec"; fi
+    __db_first=
+    local p="$PWD" w
+    if [ -n "${MSYSTEM:-}" ] && w=$(pwd -W 2>/dev/null); then p="/$w"; fi
+    printf '\033]7;file://%s%s\007' "${HOSTNAME:-localhost}" "${p//%/%25}"
+    return $__db_ec
+  }
+  __db_ps1() {
+    case "$PS1" in
+      *'133;D'*) __db_own_marks=1 ;;
+      *) __db_own_marks= ;;
+    esac
+    case "$PS1" in
+      *'133;B'*) ;;
+      *) PS1='\[\e]133;A\a\]'"$PS1"'\[\e]133;B\a\]' ;;
+    esac
+    # Checked every prompt: a PROMPT_COMMAND may reset PS0.
+    if [ -n "${__db_ps0:-}" ]; then
+      case "${PS0:-}" in
+        *'133;C'*) ;;
+        *) PS0="${PS0:-}"$'\e]133;C\a' ;;
+      esac
+    fi
+    return $__db_ec
+  }
+  if [[ "$(declare -p PROMPT_COMMAND 2>/dev/null)" == "declare -a"* ]]; then
+    PROMPT_COMMAND=(__db_precmd "${PROMPT_COMMAND[@]}" __db_ps1)
+  else
+    PROMPT_COMMAND=$'__db_precmd\n'"${PROMPT_COMMAND:-}"$'\n__db_ps1'
+  fi
+
+  if (( BASH_VERSINFO[0] > 4 || (BASH_VERSINFO[0] == 4 && BASH_VERSINFO[1] >= 4) )); then
+    __db_ps0=1
+  elif [ -z "$(trap -p DEBUG)" ]; then
+    __db_at_prompt=
+    __db_preexec() {
+      [ -n "${COMP_LINE:-}" ] && return
+      [ -z "$__db_at_prompt" ] && return
+      __db_at_prompt=
+      [ "$BASH_COMMAND" = __db_precmd ] && return
+      printf '\033]133;C\007'
+    }
+    trap '__db_preexec' DEBUG
+    PROMPT_COMMAND="$PROMPT_COMMAND"$'\n__db_at_prompt=1'
+  fi
+fi

package/src/server/integration/fish.fish

@@ -0,0 +1,21 @@
+# DeckBuilder shell integration for fish, run with --init-command after the user's config.
+if not set -q __db_si
+    set -g __db_si 1
+    function __db_prompt --on-event fish_prompt
+        printf '\e]7;file://%s%s\a' $hostname (string replace -a % %25 -- $PWD)
+    end
+    function __db_preexec --on-event fish_preexec
+        printf '\e]133;C\a'
+    end
+    function __db_postexec --on-event fish_postexec
+        printf '\e]133;D;%s\a' $status
+    end
+    if functions -q fish_prompt
+        functions -c fish_prompt __db_user_prompt
+        function fish_prompt
+            printf '\e]133;A\a'
+            __db_user_prompt
+            printf '\e]133;B\a'
+        end
+    end
+end