@valyrianjs/terminal 0.1.1 → 0.2.0

package/src/events.ts

@@ -0,0 +1,163 @@
+import type { InputInteractionState } from "./types.js";
+
+function clamp(value: number, min: number, max: number) {
+  return Math.max(min, Math.min(max, value));
+}
+
+export function normalizeInputState(state: InputInteractionState | undefined, valueLength: number): InputInteractionState {
+  const cursor = clamp(Number(state?.cursor ?? valueLength), 0, valueLength);
+  const anchor = clamp(Number(state?.anchor ?? cursor), 0, valueLength);
+  return { cursor, anchor };
+}
+
+export function hasSelection(state: InputInteractionState) {
+  return state.cursor !== state.anchor;
+}
+
+export function getSelectionRange(state: InputInteractionState) {
+  return {
+    start: Math.min(state.cursor, state.anchor),
+    end: Math.max(state.cursor, state.anchor)
+  };
+}
+
+function moveTo(state: InputInteractionState, valueLength: number, nextCursor: number, extendSelection = false) {
+  const cursor = clamp(nextCursor, 0, valueLength);
+  return extendSelection ? { cursor, anchor: state.anchor } : { cursor, anchor: cursor };
+}
+
+export function moveCursorLeft(state: InputInteractionState, valueLength: number, extendSelection = false) {
+  if (!extendSelection && hasSelection(state)) {
+    const { start } = getSelectionRange(state);
+    return moveTo(state, valueLength, start, false);
+  }
+  return moveTo(state, valueLength, state.cursor - 1, extendSelection);
+}
+
+export function moveCursorRight(state: InputInteractionState, valueLength: number, extendSelection = false) {
+  if (!extendSelection && hasSelection(state)) {
+    const { end } = getSelectionRange(state);
+    return moveTo(state, valueLength, end, false);
+  }
+  return moveTo(state, valueLength, state.cursor + 1, extendSelection);
+}
+
+export function moveCursorHome(state: InputInteractionState, valueLength: number, extendSelection = false) {
+  return moveTo(state, valueLength, 0, extendSelection);
+}
+
+export function moveCursorEnd(state: InputInteractionState, valueLength: number, extendSelection = false) {
+  return moveTo(state, valueLength, valueLength, extendSelection);
+}
+
+export function moveCursorWordLeft(value: string, state: InputInteractionState, extendSelection = false) {
+  if (!extendSelection && hasSelection(state)) {
+    const { start } = getSelectionRange(state);
+    return moveTo(state, value.length, start, false);
+  }
+
+  let cursor = state.cursor;
+  while (cursor > 0 && /\s/.test(value[cursor - 1])) {
+    cursor -= 1;
+  }
+  while (cursor > 0 && !/\s/.test(value[cursor - 1])) {
+    cursor -= 1;
+  }
+  return moveTo(state, value.length, cursor, extendSelection);
+}
+
+export function moveCursorWordRight(value: string, state: InputInteractionState, extendSelection = false) {
+  if (!extendSelection && hasSelection(state)) {
+    const { end } = getSelectionRange(state);
+    return moveTo(state, value.length, end, false);
+  }
+
+  let cursor = state.cursor;
+  while (cursor < value.length && /\s/.test(value[cursor])) {
+    cursor += 1;
+  }
+  while (cursor < value.length && !/\s/.test(value[cursor])) {
+    cursor += 1;
+  }
+  return moveTo(state, value.length, cursor, extendSelection);
+}
+
+export function selectAll(value: string) {
+  return { cursor: value.length, anchor: 0 };
+}
+
+export function copySelection(value: string, state: InputInteractionState) {
+  if (!hasSelection(state)) {
+    return "";
+  }
+  const { start, end } = getSelectionRange(state);
+  return value.slice(start, end);
+}
+
+function replaceRange(value: string, start: number, end: number, insert: string) {
+  const nextValue = `${value.slice(0, start)}${insert}${value.slice(end)}`;
+  const nextCursor = start + insert.length;
+  return { value: nextValue, state: { cursor: nextCursor, anchor: nextCursor } };
+}
+
+export function insertText(value: string, state: InputInteractionState, text: string) {
+  const { start, end } = getSelectionRange(state);
+  return replaceRange(value, start, end, text);
+}
+
+export function removeBackward(value: string, state: InputInteractionState) {
+  if (hasSelection(state)) {
+    const { start, end } = getSelectionRange(state);
+    return replaceRange(value, start, end, "");
+  }
+  if (state.cursor === 0) {
+    return { value, state };
+  }
+  return replaceRange(value, state.cursor - 1, state.cursor, "");
+}
+
+export function removeForward(value: string, state: InputInteractionState) {
+  if (hasSelection(state)) {
+    const { start, end } = getSelectionRange(state);
+    return replaceRange(value, start, end, "");
+  }
+  if (state.cursor >= value.length) {
+    return { value, state };
+  }
+  return replaceRange(value, state.cursor, state.cursor + 1, "");
+}
+
+export function parseTerminalKey(chunk: string | Uint8Array) {
+  const value = typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
+  if (value === "\r" || value === "\n") return "ENTER";
+  if (value === "\t") return "TAB";
+  if (value === "\u001b") return "ESCAPE";
+  if (value === "\u001b[27~") return "ESCAPE";
+  if (value === "\u001b[13;2u" || value === "\u001b[27;2;13~" || value === "\u001b[13;2~") return "SHIFT_ENTER";
+  const kittyEnter = /^\u001b\[13;(\d+)u$/.exec(value);
+  if (kittyEnter) {
+    const modifier = Number(kittyEnter[1]);
+    if (Number.isInteger(modifier)) {
+      return ((modifier - 1) & 1) === 1 ? "SHIFT_ENTER" : "ENTER";
+    }
+  }
+  if (value === "\u001b[Z") return "SHIFT_TAB";
+  if (value === "\u001b[A") return "UP";
+  if (value === "\u001b[B") return "DOWN";
+  if (value === "\u001b[C") return "RIGHT";
+  if (value === "\u001b[D") return "LEFT";
+  if (value === "\u001b[1;2C") return "SHIFT_RIGHT";
+  if (value === "\u001b[1;2D") return "SHIFT_LEFT";
+  if (value === "\u001b[1;3C" || value === "\u001bf") return "ALT_RIGHT";
+  if (value === "\u001b[1;3D" || value === "\u001bb") return "ALT_LEFT";
+  if (value === "\u001b[3~") return "DELETE";
+  if (value === "\u0008" || value === "\u007f") return "BACKSPACE";
+  if (value === "\u001b[H") return "HOME";
+  if (value === "\u001b[F") return "END";
+  if (value === "\u0001") return "CTRL_A";
+  if (value === "\u0003") return "CTRL_C";
+  if (value === "\u000b") return "CTRL_K";
+  if (value === "\u0016") return "CTRL_V";
+  if (value === "\u0018") return "CTRL_X";
+  return value;
+}

package/src/index.ts

@@ -0,0 +1,95 @@
+export type {
+  TerminalBoxProps,
+  TerminalButtonPressEventPayload,
+  TerminalButtonProps,
+  TerminalChangeEventPayload,
+  TerminalCommand,
+  TerminalCommandContext,
+  TerminalCommandId,
+  TerminalCommandScope,
+  InputInteractionState,
+  TerminalClipboardAdapter,
+  TerminalCaptureEventPayload,
+  TerminalDirectiveProps,
+  TerminalElementNode,
+  TerminalEditorCancelEventPayload,
+  TerminalEditorChangeEventPayload,
+  TerminalEditorProps,
+  TerminalEditorSubmitEventPayload,
+  TerminalFrame,
+  TerminalHitbox,
+  TerminalInputChangeEventPayload,
+  TerminalInputContextPressEventPayload,
+  TerminalInputProps,
+  TerminalInputSubmitEventPayload,
+  TerminalKeyBinding,
+  TerminalKeyBindingCondition,
+  TerminalKeymapOptions,
+  TerminalListPointerEventPayload,
+  TerminalListChangeEventPayload,
+  TerminalListProps,
+  TerminalListPressEventPayload,
+  TerminalLayoutProps,
+  TerminalLogViewEntry,
+  TerminalLogViewProps,
+  TerminalMountOptions,
+  TerminalMouseEventType,
+  TerminalNode,
+  TerminalOverlayProps,
+  TerminalOutputStream,
+  TerminalPaneProps,
+  TerminalPointerCoordinates,
+  TerminalPointerCaptureProps,
+  TerminalPressEventPayload,
+  TerminalPointerSource,
+  TerminalRowPointerEventPayload,
+  TerminalRowPointerEventPayloadBase,
+  TerminalRowProps,
+  TerminalScreenProps,
+  TerminalScrollPointerEventPayload,
+  TerminalScrollContextPressEventPayload,
+  TerminalScrollViewProps,
+  TerminalSemanticStyleKind,
+  TerminalSession,
+  TerminalSize,
+  TerminalSplitBreakpoint,
+  TerminalSplitProps,
+  TerminalSplitSize,
+  TerminalStyleSpan,
+  TerminalStyleToken,
+  TerminalStyleDefinition,
+  TerminalStyleProps,
+  TerminalStyleReference,
+  TerminalStyleTree,
+  TerminalStyleValue,
+  TerminalStateStyles,
+  TerminalVisualState,
+  TerminalColor,
+  TerminalSpacing,
+  TerminalBorder,
+  TerminalBorderStyle,
+  TerminalTableProps,
+  TerminalTdProps,
+  TerminalTheme,
+  TerminalTextProps,
+  TerminalValueEventPayloadBase,
+  TerminalFocusableProps,
+  TerminalEventPayloadBase,
+  TerminalFocusScopeProps,
+  TerminalFixedProps,
+  TerminalViewProps,
+  TerminalTextNode
+} from "./types.js";
+
+export { Box, Button, Editor, Fixed, FocusScope, Input, List, LogView, Overlay, Pane, Row, Screen, ScrollView, Split, Table, Td, Text, View } from "./primitives.js";
+export {
+  createResolvedTerminalKeymap,
+  createTerminalKeyBindings,
+  defaultTerminalKeyBindings,
+  resolveTerminalKeyBinding,
+  validateTerminalKeyBindings
+} from "./keymap.js";
+export { defaultTerminalTheme, highContrastTerminalTheme, mergeTerminalTheme, resolveTerminalStyle, resolveTerminalStyleToken } from "./theme.js";
+export { renderTerminal } from "./render.js";
+export type { TerminalRenderContext } from "./render.js";
+export { mountTerminal } from "./session.js";

package/src/keymap.ts

@@ -0,0 +1,151 @@
+import type { TerminalCommand, TerminalCommandContext, TerminalKeyBinding } from "./types.js";
+
+export const defaultTerminalKeyBindings: TerminalKeyBinding[] = [
+  { key: "TAB", command: { id: "focus.next" }, scope: "focus" },
+  { key: "SHIFT_TAB", command: { id: "focus.prev" }, scope: "focus" },
+  { key: "ENTER", command: { id: "input.submit" }, scope: "input", when: { focusedTag: "terminal-input" } },
+  { key: "LEFT", command: { id: "input.cursorLeft" }, scope: "input", when: { focusedTag: "terminal-input" } },
+  { key: "RIGHT", command: { id: "input.cursorRight" }, scope: "input", when: { focusedTag: "terminal-input" } },
+  { key: "SHIFT_LEFT", command: { id: "input.selectLeft" }, scope: "input", when: { focusedTag: "terminal-input" } },
+  { key: "SHIFT_RIGHT", command: { id: "input.selectRight" }, scope: "input", when: { focusedTag: "terminal-input" } },
+  { key: "ALT_LEFT", command: { id: "input.wordLeft" }, scope: "input", when: { focusedTag: "terminal-input" } },
+  { key: "ALT_RIGHT", command: { id: "input.wordRight" }, scope: "input", when: { focusedTag: "terminal-input" } },
+  { key: "BACKSPACE", command: { id: "input.backspace" }, scope: "input", when: { focusedTag: "terminal-input" } },
+  { key: "DELETE", command: { id: "input.delete" }, scope: "input", when: { focusedTag: "terminal-input" } },
+  { key: "HOME", command: { id: "input.home" }, scope: "input", when: { focusedTag: "terminal-input" } },
+  { key: "END", command: { id: "input.end" }, scope: "input", when: { focusedTag: "terminal-input" } },
+  { key: "CTRL_A", command: { id: "input.selectAll" }, scope: "input", when: { focusedTag: "terminal-input" } },
+  { key: "CTRL_C", command: { id: "input.copy" }, scope: "input", when: { focusedTag: "terminal-input" } },
+  { key: "CTRL_V", command: { id: "input.paste" }, scope: "input", when: { focusedTag: "terminal-input" } },
+  { key: "CTRL_X", command: { id: "input.cut" }, scope: "input", when: { focusedTag: "terminal-input" } },
+  { key: "ENTER", command: { id: "editor.submit" }, scope: "editor", when: { focusedTag: "terminal-editor" } },
+  { key: "ESCAPE", command: { id: "editor.cancel" }, scope: "editor", when: { focusedTag: "terminal-editor" } },
+  { key: "SHIFT_ENTER", command: { id: "editor.newline" }, scope: "editor", when: { focusedTag: "terminal-editor" } },
+  { key: "BACKSPACE", command: { id: "editor.backspace" }, scope: "editor", when: { focusedTag: "terminal-editor" } },
+  { key: "DELETE", command: { id: "editor.delete" }, scope: "editor", when: { focusedTag: "terminal-editor" } },
+  { key: "LEFT", command: { id: "editor.cursorLeft" }, scope: "editor", when: { focusedTag: "terminal-editor" } },
+  { key: "RIGHT", command: { id: "editor.cursorRight" }, scope: "editor", when: { focusedTag: "terminal-editor" } },
+  { key: "UP", command: { id: "editor.cursorUp" }, scope: "editor", when: { focusedTag: "terminal-editor" } },
+  { key: "DOWN", command: { id: "editor.cursorDown" }, scope: "editor", when: { focusedTag: "terminal-editor" } },
+  { key: "HOME", command: { id: "editor.home" }, scope: "editor", when: { focusedTag: "terminal-editor" } },
+  { key: "END", command: { id: "editor.end" }, scope: "editor", when: { focusedTag: "terminal-editor" } },
+  { key: "ENTER", command: { id: "button.press" }, scope: "button", when: { focusedTag: "terminal-button" } },
+  { key: "SPACE", command: { id: "button.press" }, scope: "button", when: { focusedTag: "terminal-button" } },
+  { key: "UP", command: { id: "list.prev" }, scope: "list", when: { focusedTag: "terminal-list" } },
+  { key: "LEFT", command: { id: "list.prev" }, scope: "list", when: { focusedTag: "terminal-list" } },
+  { key: "DOWN", command: { id: "list.next" }, scope: "list", when: { focusedTag: "terminal-list" } },
+  { key: "RIGHT", command: { id: "list.next" }, scope: "list", when: { focusedTag: "terminal-list" } },
+  { key: "ENTER", command: { id: "list.press" }, scope: "list", when: { focusedTag: "terminal-list" } },
+  { key: "UP", command: { id: "scroll.up" }, scope: "scroll", when: { focusedTag: "terminal-scroll" } },
+  { key: "DOWN", command: { id: "scroll.down" }, scope: "scroll", when: { focusedTag: "terminal-scroll" } }
+];
+
+export function validateTerminalKeyBindings(bindings: readonly TerminalKeyBinding[]) {
+  const seen = new Set<string>();
+
+  for (const binding of bindings) {
+    const signature = bindingSignature(binding);
+    if (seen.has(signature)) {
+      throw new RangeError(`Duplicate terminal key binding for ${signature}`);
+    }
+    seen.add(signature);
+  }
+}
+
+export function createResolvedTerminalKeymap(customBindings: readonly TerminalKeyBinding[] = []) {
+  validateTerminalKeyBindings(defaultTerminalKeyBindings);
+  validateTerminalKeyBindings(customBindings);
+
+  const customSignatures = new Set(customBindings.map(bindingSignature));
+  const defaults = defaultTerminalKeyBindings.filter((binding) => !customSignatures.has(bindingSignature(binding)));
+  return [...customBindings, ...defaults];
+}
+
+export const createTerminalKeyBindings = createResolvedTerminalKeymap;
+
+export function resolveTerminalKeyBinding(
+  bindings: readonly TerminalKeyBinding[],
+  context: TerminalCommandContext
+): TerminalCommand | undefined {
+  let bestBinding: TerminalKeyBinding | undefined;
+  let bestScore = -1;
+
+  for (const binding of bindings) {
+    if (!matchesBinding(binding, context)) {
+      continue;
+    }
+
+    const score = bindingTier(binding) + bindingSpecificity(binding);
+    if (score > bestScore) {
+      bestBinding = binding;
+      bestScore = score;
+    }
+  }
+
+  if (bestBinding) {
+    return bestBinding.command;
+  }
+
+  if (context.focusedTag === "terminal-input" && context.key.length === 1) {
+    return { id: "input.insertText", text: context.key };
+  }
+
+  if (context.focusedTag === "terminal-editor" && context.key.includes("\n")) {
+    return { id: "editor.pasteText", text: context.key };
+  }
+
+  return undefined;
+}
+
+function matchesBinding(binding: TerminalKeyBinding, context: TerminalCommandContext) {
+  if (binding.key !== context.key) {
+    return false;
+  }
+  if (!matchesScope(binding, context)) {
+    return false;
+  }
+  if (binding.when?.focusedId !== undefined && binding.when.focusedId !== context.focusedId) {
+    return false;
+  }
+  if (binding.when?.focusedTag !== undefined && binding.when.focusedTag !== context.focusedTag) {
+    return false;
+  }
+  return true;
+}
+
+function bindingSpecificity(binding: TerminalKeyBinding) {
+  let score = 0;
+  if (binding.scope && binding.scope !== "global" && binding.scope !== "focus") score += 1;
+  if (binding.when?.focusedTag !== undefined) score += 1;
+  if (binding.when?.focusedId !== undefined) score += 2;
+  return score;
+}
+
+function matchesScope(binding: TerminalKeyBinding, context: TerminalCommandContext) {
+  switch (binding.scope) {
+    case undefined:
+    case "global":
+    case "focus":
+      return true;
+    case "input":
+      return context.focusedTag === "terminal-input";
+    case "editor":
+      return context.focusedTag === "terminal-editor";
+    case "button":
+      return context.focusedTag === "terminal-button";
+    case "list":
+      return context.focusedTag === "terminal-list";
+    case "scroll":
+      return context.focusedTag === "terminal-scroll";
+    default:
+      return false;
+  }
+}
+
+function bindingTier(binding: TerminalKeyBinding) {
+  return defaultTerminalKeyBindings.includes(binding) ? 0 : 100;
+}
+
+function bindingSignature(binding: TerminalKeyBinding) {
+  return [binding.key, binding.scope ?? "global", binding.when?.focusedId ?? "", binding.when?.focusedTag ?? ""].join("\u0000");
+}

package/src/layout.ts

@@ -0,0 +1,282 @@
+import type { CursorPosition, TerminalFrame, TerminalHitbox, TerminalStyleSpan } from "./types.js";
+
+function repeat(char: string, count: number) {
+  return char.repeat(Math.max(0, count));
+}
+
+export function createFrame(lines: string[], hitboxes: TerminalHitbox[] = [], cursor: CursorPosition | null = null, spans: TerminalStyleSpan[] = []): TerminalFrame {
+  return { lines: lines.length ? lines : [""], hitboxes, cursor, spans };
+}
+
+export function getFrameWidth(frame: TerminalFrame) {
+  return frame.lines.reduce((max, line) => Math.max(max, line.length), 0);
+}
+
+export function getFrameHeight(frame: TerminalFrame) {
+  return frame.lines.length;
+}
+
+export function shiftFrame(frame: TerminalFrame, dx: number, dy: number): TerminalFrame {
+  return {
+    lines: frame.lines,
+    hitboxes: frame.hitboxes.map((box) => ({
+      ...box,
+      x1: box.x1 + dx,
+      x2: box.x2 + dx,
+      y1: box.y1 + dy,
+      y2: box.y2 + dy,
+      textStartX: typeof box.textStartX === "number" ? box.textStartX + dx : undefined
+    })),
+    cursor: frame.cursor ? { x: frame.cursor.x + dx, y: frame.cursor.y + dy } : null,
+    spans: frame.spans.map((span) => ({ ...span, x1: span.x1 + dx, x2: span.x2 + dx, y: span.y + dy }))
+  };
+}
+
+function normalizeLines(frame: TerminalFrame, width: number, height: number) {
+  const lines = frame.lines.map((line) => line.padEnd(width, " "));
+  while (lines.length < height) {
+    lines.push(repeat(" ", width));
+  }
+  return lines;
+}
+
+export function mergeVertical(frames: TerminalFrame[], options: { gap?: number } = {}): TerminalFrame {
+  const filtered = frames.filter(Boolean);
+  if (!filtered.length) {
+    return createFrame([""]);
+  }
+
+  const gap = Math.max(0, Number(options.gap || 0));
+  const width = filtered.reduce((max, frame) => Math.max(max, getFrameWidth(frame)), 0);
+  const lines: string[] = [];
+  const hitboxes: TerminalHitbox[] = [];
+  const spans: TerminalStyleSpan[] = [];
+  let cursor: CursorPosition | null = null;
+  let rowOffset = 0;
+
+  for (let i = 0; i < filtered.length; i += 1) {
+    const frame = filtered[i];
+    const normalized = normalizeLines(frame, width, getFrameHeight(frame));
+    lines.push(...normalized);
+    const shifted = shiftFrame(frame, 0, rowOffset);
+    hitboxes.push(...shifted.hitboxes);
+    spans.push(...shifted.spans);
+    if (!cursor && frame.cursor) {
+      cursor = { x: frame.cursor.x, y: frame.cursor.y + rowOffset };
+    }
+    rowOffset += normalized.length;
+    if (i < filtered.length - 1 && gap > 0) {
+      for (let j = 0; j < gap; j += 1) {
+        lines.push(repeat(" ", width));
+      }
+      rowOffset += gap;
+    }
+  }
+
+  return createFrame(lines, hitboxes, cursor, spans);
+}
+
+export function mergeHorizontal(frames: TerminalFrame[], options: { gap?: number } = {}): TerminalFrame {
+  const filtered = frames.filter(Boolean);
+  if (!filtered.length) {
+    return createFrame([""]);
+  }
+
+  const gap = Math.max(0, Number(options.gap || 0));
+  const widths = filtered.map(getFrameWidth);
+  const height = filtered.reduce((max, frame) => Math.max(max, getFrameHeight(frame)), 0);
+  const normalizedFrames = filtered.map((frame, index) => ({
+    frame,
+    width: widths[index],
+    lines: normalizeLines(frame, widths[index], height)
+  }));
+  const gapText = repeat(" ", gap);
+  const lines = new Array<string>(height).fill("");
+  const hitboxes: TerminalHitbox[] = [];
+  const spans: TerminalStyleSpan[] = [];
+  let cursor: CursorPosition | null = null;
+  let xOffset = 0;
+
+  for (let index = 0; index < normalizedFrames.length; index += 1) {
+    const part = normalizedFrames[index];
+    for (let row = 0; row < height; row += 1) {
+      lines[row] += part.lines[row];
+      if (index < normalizedFrames.length - 1) {
+        lines[row] += gapText;
+      }
+    }
+    const shifted = shiftFrame(part.frame, xOffset, 0);
+    hitboxes.push(...shifted.hitboxes);
+    spans.push(...shifted.spans);
+    if (!cursor && part.frame.cursor) {
+      cursor = { x: part.frame.cursor.x + xOffset, y: part.frame.cursor.y };
+    }
+    xOffset += part.width + (index < normalizedFrames.length - 1 ? gap : 0);
+  }
+
+  return createFrame(lines, hitboxes, cursor, spans);
+}
+
+export function padFrame(frame: TerminalFrame, padding: number) {
+  const amount = Math.max(0, Number(padding || 0));
+  if (!amount) {
+    return frame;
+  }
+
+  const width = getFrameWidth(frame);
+  const middle = frame.lines.map((line) => `${repeat(" ", amount)}${line.padEnd(width, " ")}${repeat(" ", amount)}`);
+  const blank = repeat(" ", width + amount * 2);
+  const lines = [...new Array<string>(amount).fill(blank), ...middle, ...new Array<string>(amount).fill(blank)];
+  const shifted = shiftFrame(frame, amount, amount);
+  return createFrame(lines, shifted.hitboxes, frame.cursor ? { x: frame.cursor.x + amount, y: frame.cursor.y + amount } : null, shifted.spans);
+}
+
+export function fitFrame(frame: TerminalFrame, width?: number, height?: number) {
+  const nextWidth = Math.max(getFrameWidth(frame), Number(width || 0));
+  const nextHeight = Math.max(getFrameHeight(frame), Number(height || 0));
+  if (nextWidth === getFrameWidth(frame) && nextHeight === getFrameHeight(frame)) {
+    return frame;
+  }
+  return createFrame(normalizeLines(frame, nextWidth, nextHeight), frame.hitboxes, frame.cursor, frame.spans);
+}
+
+function constraintSize(value: number | undefined, fallback: number) {
+  if (typeof value === "undefined") {
+    return fallback;
+  }
+  const size = Number(value);
+  if (!Number.isFinite(size) || size <= 0) {
+    throw new RangeError("Frame constraints must be greater than zero");
+  }
+  return size;
+}
+
+function overlaps(start: number, end: number, min: number, max: number) {
+  return end >= min && start <= max;
+}
+
+function clamp(value: number, min: number, max: number) {
+  return Math.min(max, Math.max(min, value));
+}
+
+export function constrainFrame(frame: TerminalFrame, options: { width?: number; height?: number } = {}): TerminalFrame {
+  const width = constraintSize(options.width, getFrameWidth(frame));
+  const height = constraintSize(options.height, getFrameHeight(frame));
+  const lines: string[] = [];
+
+  for (let row = 0; row < height; row += 1) {
+    lines.push((frame.lines[row] || "").slice(0, width).padEnd(width, " "));
+  }
+
+  const hitboxes = frame.hitboxes
+    .filter((box) => width > 0 && height > 0 && overlaps(box.x1, box.x2, 1, width) && overlaps(box.y1, box.y2, 1, height))
+    .map((box) => ({
+      ...box,
+      x1: clamp(box.x1, 1, width),
+      x2: clamp(box.x2, 1, width),
+      y1: clamp(box.y1, 1, height),
+      y2: clamp(box.y2, 1, height),
+      ...(typeof box.textStartX === "number" ? { textStartX: clamp(box.textStartX, 1, width) } : {})
+    }));
+
+  const cursor = frame.cursor && frame.cursor.x >= 1 && frame.cursor.x <= width && frame.cursor.y >= 1 && frame.cursor.y <= height
+    ? { x: frame.cursor.x, y: frame.cursor.y }
+    : null;
+
+  const spanRightEdge = width + 1;
+  const spans = frame.spans.flatMap((span) => {
+    if (width <= 0 || span.y < 1 || span.y > height || span.x2 <= 1 || span.x1 >= spanRightEdge) {
+      return [];
+    }
+
+    const clippedX1 = clamp(span.x1, 1, spanRightEdge);
+    const clippedX2 = clamp(span.x2, 1, spanRightEdge);
+    if (clippedX1 >= clippedX2) {
+      return [];
+    }
+
+    return [{ ...span, x1: clippedX1, x2: clippedX2 }];
+  });
+
+  return createFrame(lines, hitboxes, cursor, spans);
+}
+
+function overlayMetric(value: number, name: string) {
+  const metric = Number(value);
+  if (!Number.isFinite(metric) || !Number.isInteger(metric) || metric <= 0) {
+    throw new RangeError(`${name} must be a positive finite integer`);
+  }
+  return metric;
+}
+
+function nextPointerLayer(hitboxes: TerminalHitbox[]) {
+  let layer = 0;
+  for (const box of hitboxes) {
+    layer = Math.max(layer, box.pointerLayer ?? 0);
+  }
+  return layer + 1;
+}
+
+export function overlayFrame(base: TerminalFrame, overlay: TerminalFrame, options: { x: number; y: number; width: number; height: number }): TerminalFrame {
+  const x = overlayMetric(options.x, "Overlay x");
+  const y = overlayMetric(options.y, "Overlay y");
+  const width = overlayMetric(options.width, "Overlay width");
+  const height = overlayMetric(options.height, "Overlay height");
+  const constrainedOverlay = constrainFrame(overlay, { width, height });
+  const lines = base.lines.slice();
+
+  for (let row = 0; row < constrainedOverlay.lines.length; row += 1) {
+    const baseRow = y + row - 1;
+    if (baseRow < 0 || baseRow >= lines.length) {
+      continue;
+    }
+
+    const baseLine = lines[baseRow];
+    const start = x - 1;
+    if (start >= baseLine.length) {
+      continue;
+    }
+
+    const visibleWidth = Math.min(constrainedOverlay.lines[row].length, baseLine.length - start);
+    if (visibleWidth <= 0) {
+      continue;
+    }
+
+    lines[baseRow] = `${baseLine.slice(0, start)}${constrainedOverlay.lines[row].slice(0, visibleWidth)}${baseLine.slice(start + visibleWidth)}`;
+  }
+
+  const shiftedOverlay = shiftFrame(constrainedOverlay, x - 1, y - 1);
+  const visibleOverlay = constrainFrame(shiftedOverlay, { width: Math.max(1, getFrameWidth(base)), height: Math.max(1, getFrameHeight(base)) });
+  const overlayLayer = nextPointerLayer(base.hitboxes);
+  const overlayHitboxes = visibleOverlay.hitboxes.map((box) => ({
+    ...box,
+    pointerLayer: overlayLayer + (box.pointerLayer ?? 0)
+  }));
+  const cursor = visibleOverlay.cursor || base.cursor;
+
+  return createFrame(lines, [...overlayHitboxes, ...base.hitboxes], cursor, [...base.spans, ...visibleOverlay.spans]);
+}
+
+export function cropFrame(frame: TerminalFrame, offset: number, height: number) {
+  const start = Math.max(0, Number(offset || 0));
+  const size = Math.max(0, Number(height || 0));
+  const lines = frame.lines.slice(start, start + size);
+  const hitboxes = frame.hitboxes
+    .filter((box) => box.y2 > start && box.y1 <= start + size)
+    .map((box) => ({
+      ...box,
+      y1: Math.max(1, box.y1 - start),
+      y2: Math.max(1, box.y2 - start)
+    }));
+  const spans = frame.spans
+    .filter((span) => span.y > start && span.y <= start + size)
+    .map((span) => ({
+      ...span,
+      y: span.y - start
+    }));
+  const cursor = frame.cursor && frame.cursor.y > start && frame.cursor.y <= start + size
+    ? { x: frame.cursor.x, y: frame.cursor.y - start }
+    : null;
+
+  return createFrame(lines.length ? lines : [""], hitboxes, cursor, spans);
+}