@flowtty/core 1.0.0-alpha.6 → 1.0.0-alpha.8

package/dist/{backend-ode0Vc7y.d.ts → backend-BYzQoXfC.d.ts}

@@ -1,5 +1,17 @@
 import { B as Buffer } from './cells-CaXEx4lH.js';
 
+/**
+ * Every multi-character key name a backend produces. A printable key's name is
+ * the character itself (`' '`, `':'`, `'a'`) — there is no `'space'`, `'enter'`
+ * or `'colon'`. Sequences the key parser does not recognize surface under a
+ * `csi-…` name, which is deliberately not listed here.
+ */
+declare const NAMED_KEYS: readonly ["return", "escape", "tab", "backspace", "delete", "insert", "up", "down", "left", "right", "home", "end", "pageup", "pagedown", "f1", "f2", "f3", "f4", "f5", "f6", "f7", "f8", "f9", "f10", "f11", "f12", "paste", "wheelup", "wheeldown"];
+type NamedKey = typeof NAMED_KEYS[number];
+/** A key name: a named key, or the character itself for a printable key. The
+ *  `string & {}` arm keeps any character valid while editors still complete the
+ *  named ones — it cannot reject a typo like `'space'`; `TestBackend.press` does. */
+type KeyName = NamedKey | (string & {});
 interface Key {
     /**
      * Canonical name of the key. For printable ASCII characters this is the
@@ -9,7 +21,7 @@ interface Key {
      * whose content is in `text`. Mouse wheel steps are 'wheelup' / 'wheeldown',
      * positioned by `x` / `y`.
      */
-    name: string;
+    name: KeyName;
     /**
      * Payload of a 'paste' key: the pasted text, line endings normalized to `\n`.
      * A paste is delivered whole — its newlines and letters are text, never
@@ -87,4 +99,4 @@ interface Backend {
     hyperlinks?: boolean;
 }
 
-export type { Backend as B, Key as K };
+export { type Backend as B, type Key as K, NAMED_KEYS as N, type KeyName as a, type NamedKey as b };

package/dist/chunk-AQ33T2P5.js

@@ -0,0 +1,34 @@
+// src/keys.ts
+var NAMED_KEYS = [
+  "return",
+  "escape",
+  "tab",
+  "backspace",
+  "delete",
+  "insert",
+  "up",
+  "down",
+  "left",
+  "right",
+  "home",
+  "end",
+  "pageup",
+  "pagedown",
+  "f1",
+  "f2",
+  "f3",
+  "f4",
+  "f5",
+  "f6",
+  "f7",
+  "f8",
+  "f9",
+  "f10",
+  "f11",
+  "f12",
+  "paste",
+  "wheelup",
+  "wheeldown"
+];
+
+export { NAMED_KEYS };

package/dist/host/index.d.ts

@@ -1,5 +1,5 @@
-import { C as Container } from '../host-zpuR6C1c.js';
-export { B as BORDER_CHARS, H as HostType, I as Instance, R as Rect, T as TextInstance, Y as Yoga, a as YogaNode, b as appendChild, c as applyProps, d as computeLayout, e as createInstance, f as createTextInstance, g as getYoga, i as insertBefore, l as layoutOf, m as measureText, o as ownText, r as refreshMeasure, h as removeChild } from '../host-zpuR6C1c.js';
+import { C as Container } from '../host-6NVC0_E3.js';
+export { B as BORDER_CHARS, H as HostType, I as Instance, R as Rect, T as TextInstance, Y as Yoga, a as YogaNode, b as appendChild, c as applyProps, d as computeLayout, e as createInstance, f as createTextInstance, g as getYoga, i as insertBefore, l as layoutOf, m as measureText, o as ownText, r as refreshMeasure, h as removeChild } from '../host-6NVC0_E3.js';
 import { B as Buffer } from '../cells-CaXEx4lH.js';
 import 'yoga-layout/load';
 

package/dist/host/index.js

@@ -315,13 +315,22 @@ function contentRectOf(inst, box) {
     height: Math.max(0, box.height - padT - padB)
   };
 }
+function paddingRectOf(inst, box) {
+  const n = inst.yogaNode;
+  const t = n.getComputedBorder(Edge.Top);
+  const r = n.getComputedBorder(Edge.Right);
+  const b = n.getComputedBorder(Edge.Bottom);
+  const l = n.getComputedBorder(Edge.Left);
+  return { left: box.left + l, top: box.top + t, width: Math.max(0, box.width - l - r), height: Math.max(0, box.height - t - b) };
+}
 function paintInstance(inst, buffer, offsetX, offsetY, inheritedBg = void 0, clip = null) {
   if (inst.props.display === "none") return;
   const box = layoutOf(inst, offsetX, offsetY);
   inst.props.onLayout?.(box);
   const ownBg = inst.props.backgroundColor;
   const effectiveBg = ownBg ?? inheritedBg;
-  if (ownBg !== void 0) {
+  const offscreen = clip !== null && (box.left >= clip.left + clip.width || box.left + box.width <= clip.left || box.top >= clip.top + clip.height || box.top + box.height <= clip.top);
+  if (!offscreen && ownBg !== void 0) {
     const fillStyle = ownBg === "default" ? {} : { bg: ownBg };
     for (let y = box.top; y < box.top + box.height; y++) {
       for (let x = box.left; x < box.left + box.width; x++) {
@@ -329,8 +338,8 @@ function paintInstance(inst, buffer, offsetX, offsetY, inheritedBg = void 0, cli
       }
     }
   }
-  paintBorder(inst, buffer, box, clip, effectiveBg);
-  const text = ownText(inst);
+  if (!offscreen) paintBorder(inst, buffer, box, clip, effectiveBg);
+  const text = offscreen ? "" : ownText(inst);
   if (text) {
     const content = contentRectOf(inst, box);
     const mode = inst.props.wrap ?? "none";
@@ -350,7 +359,23 @@ function paintInstance(inst, buffer, offsetX, offsetY, inheritedBg = void 0, cli
       }
     }
   }
-  const childClip = inst.props.overflow === "hidden" ? intersectRects(clip, contentRectOf(inst, box)) : clip;
+  const scrolls = inst.props.scrollTop !== void 0 || inst.props.scrollBottom !== void 0;
+  let scrollTop = 0;
+  if (scrolls || inst.props.onScrollMetrics) {
+    const viewport = contentRectOf(inst, box);
+    let contentBottom = 0;
+    for (const child of inst.children) {
+      if (child.type !== "box" || child.props.position === "absolute" || child.props.display === "none") continue;
+      const n = child.yogaNode;
+      contentBottom = Math.max(contentBottom, n.getComputedTop() + n.getComputedHeight() + n.getComputedMargin(Edge.Bottom));
+    }
+    const contentHeight = Math.max(0, contentBottom - (viewport.top - box.top));
+    const maxScrollTop = Math.max(0, contentHeight - viewport.height);
+    const wanted = inst.props.scrollBottom !== void 0 ? maxScrollTop - inst.props.scrollBottom : inst.props.scrollTop ?? 0;
+    scrollTop = Math.max(0, Math.min(maxScrollTop, Math.round(wanted)));
+    inst.props.onScrollMetrics?.({ contentHeight, viewportHeight: viewport.height, scrollTop, maxScrollTop });
+  }
+  const childClip = inst.props.overflow === "hidden" || scrolls ? intersectRects(clip, contentRectOf(inst, box)) : clip;
   const stackFlow = [];
   const absolutes = [];
   for (const child of inst.children) {
@@ -360,8 +385,9 @@ function paintInstance(inst, buffer, offsetX, offsetY, inheritedBg = void 0, cli
   const byZ = (a, b) => (a.props.zIndex ?? 0) - (b.props.zIndex ?? 0);
   stackFlow.sort(byZ);
   absolutes.sort(byZ);
-  for (const child of stackFlow) paintInstance(child, buffer, box.left, box.top, effectiveBg, childClip);
-  for (const child of absolutes) paintInstance(child, buffer, box.left, box.top, effectiveBg, childClip);
+  for (const child of stackFlow) paintInstance(child, buffer, box.left, box.top - scrollTop, effectiveBg, childClip);
+  const overlayClip = scrolls ? intersectRects(clip, paddingRectOf(inst, box)) : childClip;
+  for (const child of absolutes) paintInstance(child, buffer, box.left, box.top, effectiveBg, overlayClip);
 }
 
 export { appendChild, applyProps, computeLayout, createInstance, createTextInstance, getYoga, insertBefore, layoutOf, measureText, ownText, paint, refreshMeasure, removeChild };

package/dist/{host-zpuR6C1c.d.ts → host-6NVC0_E3.d.ts}

@@ -114,6 +114,28 @@ interface BoxProps {
      *  'hidden' clips ALL descendant writes including their backgrounds and borders.
      *  Does NOT clip this box's own background or border (those are this box's own area). */
     overflow?: 'visible' | 'hidden';
+    /** Scroll the content up by this many rows (0 = top). Setting either scroll
+     *  prop makes the box a scroll viewport: it clips like `overflow: 'hidden'`
+     *  and paints its flow children shifted. The value is clamped to the scrollable
+     *  range at paint time, against the content's CURRENT height — so it never
+     *  needs a second frame to catch up. `position: 'absolute'` children are
+     *  overlays: they neither scroll nor count as content (a scrollbar, a
+     *  "new messages" badge). */
+    scrollTop?: number;
+    /** Like `scrollTop`, but counted from the END of the content: 0 pins the last
+     *  rows into view and keeps them there as content grows. Wins over `scrollTop`
+     *  when both are set. */
+    scrollBottom?: number;
+    /** Fires every paint (diff before setState, like onLayout) with the numbers a
+     *  scrolling component needs: content and viewport heights, the effective
+     *  (clamped) `scrollTop`, and its maximum. */
+    onScrollMetrics?: (metrics: ScrollMetrics) => void;
+}
+interface ScrollMetrics {
+    contentHeight: number;
+    viewportHeight: number;
+    scrollTop: number;
+    maxScrollTop: number;
 }
 interface Instance {
     type: 'box';
@@ -149,4 +171,4 @@ declare function appendChild(parent: Instance, child: Instance | TextInstance, Y
 declare function removeChild(parent: Instance, child: Instance | TextInstance, Yoga: Yoga): void;
 declare function insertBefore(parent: Instance, child: Instance | TextInstance, before: Instance | TextInstance, Yoga: Yoga): void;
 
-export { BORDER_CHARS as B, type Container as C, DEFAULT_BORDER_STYLE as D, GRID_CHARS as G, type HostType as H, type Instance as I, type Rect as R, type TextInstance as T, type Yoga as Y, type YogaNode as a, appendChild as b, applyProps as c, computeLayout as d, createInstance as e, createTextInstance as f, getYoga as g, removeChild as h, insertBefore as i, type BorderChars as j, type BorderStyle as k, layoutOf as l, measureText as m, type BoxProps as n, ownText as o, type GridChars as p, refreshMeasure as r };
+export { BORDER_CHARS as B, type Container as C, DEFAULT_BORDER_STYLE as D, GRID_CHARS as G, type HostType as H, type Instance as I, type Rect as R, type ScrollMetrics as S, type TextInstance as T, type Yoga as Y, type YogaNode as a, appendChild as b, applyProps as c, computeLayout as d, createInstance as e, createTextInstance as f, getYoga as g, removeChild as h, insertBefore as i, type BorderChars as j, type BorderStyle as k, layoutOf as l, measureText as m, type BoxProps as n, ownText as o, type GridChars as p, refreshMeasure as r };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { B as Buffer, C as Cell, S as Style } from './cells-CaXEx4lH.js';
-import { K as Key } from './backend-ode0Vc7y.js';
-export { B as Backend } from './backend-ode0Vc7y.js';
-export { j as BorderChars, k as BorderStyle, n as BoxProps, D as DEFAULT_BORDER_STYLE, G as GRID_CHARS, p as GridChars } from './host-zpuR6C1c.js';
+import { K as Key } from './backend-BYzQoXfC.js';
+export { B as Backend, a as KeyName, N as NAMED_KEYS, b as NamedKey } from './backend-BYzQoXfC.js';
+export { j as BorderChars, k as BorderStyle, n as BoxProps, D as DEFAULT_BORDER_STYLE, G as GRID_CHARS, p as GridChars, S as ScrollMetrics } from './host-6NVC0_E3.js';
 import 'yoga-layout/load';
 
 type WrapMode = 'wrap' | 'truncate' | 'none';
@@ -82,6 +82,10 @@ declare function stringWidth(str: string): number;
 
 interface EditorState {
     value: string;
+    /** UTF-16 index into `value` (so `value.slice(0, cursor)` is the text before
+     *  the caret). It only ever rests on a character boundary: movement and
+     *  deletion step over a whole code point, and a cursor handed in between the
+     *  two halves of a surrogate pair is snapped back before anything else. */
     cursor: number;
 }
 type EditorAction = {
@@ -94,7 +98,33 @@ type EditorAction = {
 } | {
     kind: 'noop';
 };
-declare function reduce$2(state: EditorState, key: Key): EditorAction;
+interface EditorOptions {
+    /** Multi-line editing: line breaks are part of the value. Shift+Enter,
+     *  Alt+Enter and backslash-then-Enter insert one (plain Enter still submits),
+     *  up/down move between visual rows, Home/End and the kill bindings work
+     *  within the current line, and a paste keeps its line breaks. */
+    multiline?: boolean;
+    /** Wrap width in cells — what up/down use to walk soft-wrapped rows. Only
+     *  read when `multiline`; without it each source line counts as one row. */
+    width?: number;
+}
+declare function reduce$2(state: EditorState, key: Key, opts?: EditorOptions): EditorAction;
+
+interface InputRow {
+    /** Text of this visual row (no line break). */
+    text: string;
+    /** Index into the value where this row starts. */
+    start: number;
+    /** True for a soft-wrap continuation of the previous row's source line. */
+    continuation: boolean;
+}
+declare function inputRows(value: string, width: number, cursor?: number): InputRow[];
+/** UTF-16 index of character column `col` within `row` (clamped to its end). */
+declare function rowIndexAt(row: InputRow, col: number): number;
+declare function caretPosition(value: string, cursor: number, width: number): {
+    row: number;
+    col: number;
+};
 
 interface SelectItem<T> {
     label: string;
@@ -140,4 +170,4 @@ type MultiSelectAction = {
 };
 declare function reduce<T>(items: SelectItem<T>[], state: MultiSelectState, key: Key): MultiSelectAction;
 
-export { type EditorAction, type EditorState, Key, type MultiSelectAction, type MultiSelectState, type SelectAction, type SelectItem, type SelectState, type VisualLine, type WrapMode, charWidth, reduce$2 as editorReducer, reduce as multiSelectReducer, reduce$1 as selectReducer, splitVisualLines, stringWidth, visibleIndices, windowAround, wrapText };
+export { type EditorAction, type EditorOptions, type EditorState, type InputRow, Key, type MultiSelectAction, type MultiSelectState, type SelectAction, type SelectItem, type SelectState, type VisualLine, type WrapMode, caretPosition, charWidth, reduce$2 as editorReducer, inputRows, reduce as multiSelectReducer, rowIndexAt, reduce$1 as selectReducer, splitVisualLines, stringWidth, visibleIndices, windowAround, wrapText };

package/dist/index.js

@@ -1,4 +1,5 @@
 export { Buffer, DEFAULT_BORDER_STYLE, GRID_CHARS, wrapText } from './chunk-D6HW2BNM.js';
+export { NAMED_KEYS } from './chunk-AQ33T2P5.js';
 
 // src/visualLines.ts
 function splitVisualLines(text, mode, width) {
@@ -280,7 +281,50 @@ function stringWidth(str) {
   return w;
 }
 
+// src/inputRows.ts
+function inputRows(value, width, cursor) {
+  const w = Math.max(1, Math.floor(width));
+  const rows = [];
+  let lineStart = 0;
+  for (const line of value.split("\n")) {
+    const chars = [...line];
+    if (chars.length === 0) {
+      rows.push({ text: "", start: lineStart, continuation: false });
+    } else {
+      let start = lineStart;
+      for (let at = 0; at < chars.length; at += w) {
+        const text = chars.slice(at, at + w).join("");
+        rows.push({ text, start, continuation: at > 0 });
+        start += text.length;
+      }
+      if (cursor === lineStart + line.length && chars.length % w === 0) {
+        rows.push({ text: "", start: cursor, continuation: true });
+      }
+    }
+    lineStart += line.length + 1;
+  }
+  return rows;
+}
+function rowIndexAt(row, col) {
+  return row.start + [...row.text].slice(0, Math.max(0, col)).join("").length;
+}
+function caretPosition(value, cursor, width) {
+  const c = Math.max(0, Math.min(value.length, cursor));
+  const rows = inputRows(value, width, c);
+  for (let r = rows.length - 1; r >= 0; r--) {
+    const row = rows[r];
+    if (row.start <= c && c <= row.start + row.text.length) {
+      return { row: r, col: [...value.slice(row.start, c)].length };
+    }
+  }
+  return { row: 0, col: 0 };
+}
+
 // src/editor.ts
+var isHigh = (u) => u !== void 0 && u >= "\uD800" && u <= "\uDBFF";
+var isLow = (u) => u !== void 0 && u >= "\uDC00" && u <= "\uDFFF";
+var prevIndex = (v, i) => i >= 2 && isLow(v[i - 1]) && isHigh(v[i - 2]) ? i - 2 : Math.max(0, i - 1);
+var nextIndex = (v, i) => isHigh(v[i]) && isLow(v[i + 1]) ? i + 2 : Math.min(v.length, i + 1);
 var OPT_MAP = {
   " ": ["\xA0"],
   // U+00A0 NBSP
@@ -304,24 +348,50 @@ function wordRight(value, cursor) {
   while (c < value.length && isWord(value[c])) c++;
   return c;
 }
-function reduce(state, key) {
-  const { value, cursor } = state;
-  const clamp = (n) => Math.max(0, Math.min(value.length, n));
+function reduce(state, key, opts = {}) {
+  const { value } = state;
+  let cursor = Math.max(0, Math.min(value.length, state.cursor));
+  if (isLow(value[cursor]) && isHigh(value[cursor - 1])) cursor--;
+  const multiline = opts.multiline === true;
+  const lineStart = multiline ? value.lastIndexOf("\n", cursor - 1) + 1 : 0;
+  const nextBreak = multiline ? value.indexOf("\n", cursor) : -1;
+  const lineEnd = nextBreak < 0 ? value.length : nextBreak;
+  const insert = (text) => ({
+    kind: "edit",
+    state: { value: value.slice(0, cursor) + text + value.slice(cursor), cursor: cursor + text.length }
+  });
   if (key.name === "paste") {
-    const text = (key.text ?? "").replace(/\n/g, " ");
+    const pasted = (key.text ?? "").replace(/\r\n?/g, "\n");
+    const text = multiline ? pasted : pasted.replace(/\n/g, " ");
     if (text === "") return { kind: "noop" };
-    return { kind: "edit", state: { value: value.slice(0, cursor) + text + value.slice(cursor), cursor: cursor + text.length } };
+    return insert(text);
+  }
+  if (multiline) {
+    if (key.name === "return" && (key.shift || key.meta)) return insert("\n");
+    if (key.name === "return" && cursor > 0 && value[cursor - 1] === "\\") {
+      return { kind: "edit", state: { value: value.slice(0, cursor - 1) + "\n" + value.slice(cursor), cursor } };
+    }
+    if (key.name === "up" || key.name === "down") {
+      const width = opts.width ?? Number.MAX_SAFE_INTEGER;
+      const rows = inputRows(value, width, cursor);
+      const at = caretPosition(value, cursor, width);
+      const target = at.row + (key.name === "up" ? -1 : 1);
+      if (target < 0) return { kind: "edit", state: { value, cursor: 0 } };
+      if (target >= rows.length) return { kind: "edit", state: { value, cursor: value.length } };
+      const row = rows[target];
+      return { kind: "edit", state: { value, cursor: rowIndexAt(row, at.col) } };
+    }
   }
   if (key.name === "left" && key.meta) return { kind: "edit", state: { value, cursor: wordLeft(value, cursor) } };
   if (key.name === "b" && key.meta) return { kind: "edit", state: { value, cursor: wordLeft(value, cursor) } };
   if (key.name === "right" && key.meta) return { kind: "edit", state: { value, cursor: wordRight(value, cursor) } };
   if (key.name === "f" && key.meta) return { kind: "edit", state: { value, cursor: wordRight(value, cursor) } };
-  if (key.name === "left") return { kind: "edit", state: { value, cursor: clamp(cursor - 1) } };
-  if (key.name === "right") return { kind: "edit", state: { value, cursor: clamp(cursor + 1) } };
-  if (key.name === "home") return { kind: "edit", state: { value, cursor: 0 } };
-  if (key.name === "end") return { kind: "edit", state: { value, cursor: value.length } };
-  if (key.name === "a" && key.ctrl) return { kind: "edit", state: { value, cursor: 0 } };
-  if (key.name === "e" && key.ctrl) return { kind: "edit", state: { value, cursor: value.length } };
+  if (key.name === "left") return { kind: "edit", state: { value, cursor: prevIndex(value, cursor) } };
+  if (key.name === "right") return { kind: "edit", state: { value, cursor: nextIndex(value, cursor) } };
+  if (key.name === "home") return { kind: "edit", state: { value, cursor: lineStart } };
+  if (key.name === "end") return { kind: "edit", state: { value, cursor: lineEnd } };
+  if (key.name === "a" && key.ctrl) return { kind: "edit", state: { value, cursor: lineStart } };
+  if (key.name === "e" && key.ctrl) return { kind: "edit", state: { value, cursor: lineEnd } };
   if (key.name === "backspace" && key.meta) {
     const start = wordLeft(value, cursor);
     return { kind: "edit", state: { value: value.slice(0, start) + value.slice(cursor), cursor: start } };
@@ -339,10 +409,10 @@ function reduce(state, key) {
     return { kind: "edit", state: { value: value.slice(0, cursor) + value.slice(end), cursor } };
   }
   if (key.name === "k" && key.ctrl) {
-    return { kind: "edit", state: { value: value.slice(0, cursor), cursor } };
+    return { kind: "edit", state: { value: value.slice(0, cursor) + value.slice(lineEnd), cursor } };
   }
   if (key.name === "u" && key.ctrl) {
-    return { kind: "edit", state: { value: value.slice(cursor), cursor: 0 } };
+    return { kind: "edit", state: { value: value.slice(0, lineStart) + value.slice(cursor), cursor: lineStart } };
   }
   if (key.meta && OPT_MAP[key.name]) {
     const entry = OPT_MAP[key.name];
@@ -350,19 +420,17 @@ function reduce(state, key) {
     return { kind: "edit", state: { value: value.slice(0, cursor) + ch + value.slice(cursor), cursor: cursor + 1 } };
   }
   if (key.name === "backspace") {
-    if (cursor === 0) return { kind: "edit", state };
-    return { kind: "edit", state: { value: value.slice(0, cursor - 1) + value.slice(cursor), cursor: cursor - 1 } };
+    if (cursor === 0) return { kind: "edit", state: { value, cursor } };
+    const from = prevIndex(value, cursor);
+    return { kind: "edit", state: { value: value.slice(0, from) + value.slice(cursor), cursor: from } };
   }
   if (key.name === "delete" || key.name === "d" && key.ctrl) {
-    if (cursor === value.length) return { kind: "edit", state };
-    return { kind: "edit", state: { value: value.slice(0, cursor) + value.slice(cursor + 1), cursor } };
+    if (cursor === value.length) return { kind: "edit", state: { value, cursor } };
+    return { kind: "edit", state: { value: value.slice(0, cursor) + value.slice(nextIndex(value, cursor)), cursor } };
   }
   if (key.name === "return") return { kind: "submit" };
   if (key.name === "escape") return { kind: "cancel" };
-  if (!key.ctrl && !key.meta && key.name.length === 1) {
-    const ch = key.name;
-    return { kind: "edit", state: { value: value.slice(0, cursor) + ch + value.slice(cursor), cursor: cursor + 1 } };
-  }
+  if (!key.ctrl && !key.meta && [...key.name].length === 1) return insert(key.name);
   return { kind: "noop" };
 }
 
@@ -422,4 +490,4 @@ function reduce3(items, state, key) {
   return { kind: "noop" };
 }
 
-export { charWidth, reduce as editorReducer, reduce3 as multiSelectReducer, reduce2 as selectReducer, splitVisualLines, stringWidth, visibleIndices, windowAround };
+export { caretPosition, charWidth, reduce as editorReducer, inputRows, reduce3 as multiSelectReducer, rowIndexAt, reduce2 as selectReducer, splitVisualLines, stringWidth, visibleIndices, windowAround };

package/dist/testing/index.d.ts

@@ -1,5 +1,5 @@
 import { B as Buffer } from '../cells-CaXEx4lH.js';
-import { B as Backend, K as Key } from '../backend-ode0Vc7y.js';
+import { B as Backend, K as Key } from '../backend-BYzQoXfC.js';
 
 declare class TestBackend implements Backend {
     private readonly cols;
@@ -16,7 +16,11 @@ declare class TestBackend implements Backend {
     get lastFrame(): string;
     get lastBuffer(): Buffer | null;
     onKey(handler: (key: Key) => void): () => void;
-    /** Synchronously deliver one Key to every subscriber. */
+    /**
+     * Synchronously deliver one Key to every subscriber. Throws on a name no
+     * terminal can produce (`'space'`, `'enter'`): a test that presses such a key
+     * exercises a branch real input never reaches, and would pass anyway.
+     */
     press(key: Partial<Key> & {
         name: string;
     }): void;

package/dist/testing/index.js

@@ -1,4 +1,25 @@
+import { NAMED_KEYS } from '../chunk-AQ33T2P5.js';
+
 // src/testing/test-backend.ts
+var KEY_NAME_HINTS = {
+  space: " ",
+  enter: "return",
+  esc: "escape",
+  del: "delete",
+  ins: "insert",
+  pgup: "pageup",
+  pgdn: "pagedown",
+  pgdown: "pagedown",
+  bs: "backspace"
+};
+function assertRealKeyName(name) {
+  if ([...name].length === 1 || name.startsWith("csi-")) return;
+  if (NAMED_KEYS.includes(name)) return;
+  const hint = KEY_NAME_HINTS[name.toLowerCase()];
+  throw new Error(
+    `TestBackend.press: '${name}' is not a key name any terminal produces` + (hint !== void 0 ? ` \u2014 use '${hint}'.` : `. A printable key is named by its character (':' not 'colon'); named keys: ${NAMED_KEYS.join(", ")}.`)
+  );
+}
 var TestBackend = class {
   constructor(cols = 40, rows = 10) {
     this.cols = cols;
@@ -28,8 +49,13 @@ var TestBackend = class {
       this.subscribers.delete(handler);
     };
   }
-  /** Synchronously deliver one Key to every subscriber. */
+  /**
+   * Synchronously deliver one Key to every subscriber. Throws on a name no
+   * terminal can produce (`'space'`, `'enter'`): a test that presses such a key
+   * exercises a branch real input never reaches, and would pass anyway.
+   */
   press(key) {
+    assertRealKeyName(key.name);
     const k = {
       ...key.text !== void 0 ? { text: key.text } : {},
       ...key.x !== void 0 ? { x: key.x } : {},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowtty/core",
-  "version": "1.0.0-alpha.6",
+  "version": "1.0.0-alpha.8",
   "type": "module",
   "license": "MIT",
   "repository": {