@flowtty/core 1.0.0-alpha.1 → 1.0.0-alpha.11

package/dist/keys-Ck-RALk_.js

@@ -0,0 +1,40 @@
+//#region src/keys.ts
+/**
+* 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.
+*/
+const 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"
+];
+//#endregion
+export { NAMED_KEYS as t };

package/dist/testing/index.d.ts

@@ -1,30 +1,39 @@
-import { B as Buffer } from '../cells-CaXEx4lH.js';
-import { B as Backend, K as Key } from '../backend-BcB7VR87.js';
-
-declare class TestBackend implements Backend {
-    private readonly cols;
-    private readonly rows;
-    frames: string[];
-    private buffers;
-    private readonly subscribers;
-    constructor(cols?: number, rows?: number);
-    size(): {
-        width: number;
-        height: number;
-    };
-    draw(buffer: Buffer): void;
-    get lastFrame(): string;
-    get lastBuffer(): Buffer | null;
-    onKey(handler: (key: Key) => void): () => void;
-    /** Synchronously deliver one Key to every subscriber. */
-    press(key: Partial<Key> & {
-        name: string;
-    }): void;
-    /** Emit one Key per character; printable chars only. */
-    type(text: string): void;
-    dispose(): void;
+import { t as Buffer } from "../cells-C-GthybI.js";
+import { n as Key, t as Backend } from "../backend-CT8SGLO5.js";
+//#region src/testing/test-backend.d.ts
+export declare class TestBackend implements Backend {
+  private readonly cols;
+  private readonly rows;
+  frames: string[];
+  private buffers;
+  private readonly subscribers;
+  constructor(cols?: number, rows?: number);
+  size(): {
+    width: number;
+    height: number;
+  };
+  draw(buffer: Buffer): void;
+  get lastFrame(): string;
+  get lastBuffer(): Buffer | null;
+  onKey(handler: (key: Key) => void): () => void;
+  /**
+   * 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;
+  /** Emit one Key per character; printable chars only. */
+  type(text: string): void;
+  /** Deliver `text` as ONE 'paste' key — what a TTY backend emits for a bracketed paste. */
+  paste(text: string): void;
+  /** Deliver one mouse-wheel step at cell (x, y) — what a TTY backend with `mouse` on emits. */
+  wheel(direction: "up" | "down", x?: number, y?: number): void;
+  dispose(): void;
 }
-
+//#endregion
+//#region src/testing/index.d.ts
 /**
  * Resolve after pending microtasks have drained. Use after `backend.press(...)`
  * to wait for React's state update + the scheduled repaint:
@@ -33,7 +42,7 @@ declare class TestBackend implements Backend {
  *     await flush();
  *     expect(backend.lastFrame).toBe('a');
  */
-declare function flush(): Promise<void>;
+export declare function flush(): Promise<void>;
 /**
  * Wait for React scheduler-driven re-renders triggered by `setState` inside
  * `useEffect` (e.g. a Form field registering, then the group auto-focusing the
@@ -56,8 +65,7 @@ declare function flush(): Promise<void>;
  * Called with no backend it falls back to a single macrotask round (the legacy
  * behavior) for callers that don't need cascade-settling.
  */
-declare function flushAsync(backend?: {
-    readonly frames: readonly unknown[];
+export declare function flushAsync(backend?: {
+  readonly frames: readonly unknown[];
 }): Promise<void>;
-
-export { TestBackend, flush, flushAsync };
+//#endregion

package/dist/testing/index.js

@@ -1,72 +1,147 @@
-// src/testing/test-backend.ts
+import { t as NAMED_KEYS } from "../keys-Ck-RALk_.js";
+//#region src/testing/test-backend.ts
+const 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 ? ` — 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;
-    this.rows = rows;
-  }
-  cols;
-  rows;
-  frames = [];
-  buffers = [];
-  subscribers = /* @__PURE__ */ new Set();
-  size() {
-    return { width: this.cols, height: this.rows };
-  }
-  draw(buffer) {
-    this.frames.push(buffer.toString());
-    this.buffers.push(buffer);
-  }
-  get lastFrame() {
-    return this.frames[this.frames.length - 1] ?? "";
-  }
-  get lastBuffer() {
-    return this.buffers[this.buffers.length - 1] ?? null;
-  }
-  onKey(handler) {
-    this.subscribers.add(handler);
-    return () => {
-      this.subscribers.delete(handler);
-    };
-  }
-  /** Synchronously deliver one Key to every subscriber. */
-  press(key) {
-    const k = {
-      sequence: key.sequence ?? "",
-      ctrl: key.ctrl ?? false,
-      meta: key.meta ?? false,
-      shift: key.shift ?? false,
-      name: key.name
-    };
-    for (const h of [...this.subscribers]) h(k);
-  }
-  /** Emit one Key per character; printable chars only. */
-  type(text) {
-    for (const ch of text) this.press({ name: ch, sequence: ch });
-  }
-  // eslint-disable-next-line @typescript-eslint/no-empty-function
-  dispose() {
-  }
+	cols;
+	rows;
+	frames = [];
+	buffers = [];
+	subscribers = /* @__PURE__ */ new Set();
+	constructor(cols = 40, rows = 10) {
+		this.cols = cols;
+		this.rows = rows;
+	}
+	size() {
+		return {
+			width: this.cols,
+			height: this.rows
+		};
+	}
+	draw(buffer) {
+		this.frames.push(buffer.toString());
+		this.buffers.push(buffer);
+	}
+	get lastFrame() {
+		return this.frames[this.frames.length - 1] ?? "";
+	}
+	get lastBuffer() {
+		return this.buffers[this.buffers.length - 1] ?? null;
+	}
+	onKey(handler) {
+		this.subscribers.add(handler);
+		return () => {
+			this.subscribers.delete(handler);
+		};
+	}
+	/**
+	* 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 } : {},
+			...key.y !== void 0 ? { y: key.y } : {},
+			sequence: key.sequence ?? "",
+			ctrl: key.ctrl ?? false,
+			meta: key.meta ?? false,
+			shift: key.shift ?? false,
+			name: key.name
+		};
+		for (const h of [...this.subscribers]) h(k);
+	}
+	/** Emit one Key per character; printable chars only. */
+	type(text) {
+		for (const ch of text) this.press({
+			name: ch,
+			sequence: ch
+		});
+	}
+	/** Deliver `text` as ONE 'paste' key — what a TTY backend emits for a bracketed paste. */
+	paste(text) {
+		this.press({
+			name: "paste",
+			text: text.replace(/\r\n?/g, "\n")
+		});
+	}
+	/** Deliver one mouse-wheel step at cell (x, y) — what a TTY backend with `mouse` on emits. */
+	wheel(direction, x = 0, y = 0) {
+		this.press({
+			name: direction === "up" ? "wheelup" : "wheeldown",
+			x,
+			y
+		});
+	}
+	dispose() {}
 };
-
-// src/testing/index.ts
+//#endregion
+//#region src/testing/index.ts
+/**
+* Resolve after pending microtasks have drained. Use after `backend.press(...)`
+* to wait for React's state update + the scheduled repaint:
+*
+*     backend.press({ name: 'a' });
+*     await flush();
+*     expect(backend.lastFrame).toBe('a');
+*/
 async function flush() {
-  await Promise.resolve();
-  await Promise.resolve();
+	await Promise.resolve();
+	await Promise.resolve();
 }
+/**
+* Wait for React scheduler-driven re-renders triggered by `setState` inside
+* `useEffect` (e.g. a Form field registering, then the group auto-focusing the
+* first field) to fully commit.
+*
+* A passive-effect `setState` lands on React's default lane, which the
+* production Scheduler only drains on a macrotask — there is no synchronous
+* escape hatch in react-reconciler. A single `setTimeout(0)` (the old impl)
+* therefore advances only ONE step of a multi-step effect cascade and can also
+* lose the race against the Scheduler's own MessageChannel macrotask; both
+* surface as a stale/empty `lastFrame`.
+*
+* Passing the `TestBackend` makes this deterministic: each round yields one
+* macrotask (draining the Scheduler, which flushes that commit's passive
+* effects exactly as in production) plus a microtask pair (for the coalesced
+* repaint), and we stop once two consecutive rounds add no new frame. Two
+* rounds — not one — so a single macrotask-ordering inversion (Scheduler work
+* landing just after our `setTimeout`) can't read as premature quiescence.
+*
+* Called with no backend it falls back to a single macrotask round (the legacy
+* behavior) for callers that don't need cascade-settling.
+*/
 async function flushAsync(backend) {
-  if (!backend) {
-    await new Promise((resolve) => setTimeout(resolve, 0));
-    return;
-  }
-  const MAX_ROUNDS = 20;
-  let stableRounds = 0;
-  for (let i = 0; i < MAX_ROUNDS && stableRounds < 2; i++) {
-    const before = backend.frames.length;
-    await new Promise((resolve) => setTimeout(resolve, 0));
-    await Promise.resolve();
-    await Promise.resolve();
-    stableRounds = backend.frames.length === before ? stableRounds + 1 : 0;
-  }
+	if (!backend) {
+		await new Promise((resolve) => setTimeout(resolve, 0));
+		return;
+	}
+	const MAX_ROUNDS = 20;
+	let stableRounds = 0;
+	for (let i = 0; i < MAX_ROUNDS && stableRounds < 2; i++) {
+		const before = backend.frames.length;
+		await new Promise((resolve) => setTimeout(resolve, 0));
+		await Promise.resolve();
+		await Promise.resolve();
+		stableRounds = backend.frames.length === before ? stableRounds + 1 : 0;
+	}
 }
-
+//#endregion
 export { TestBackend, flush, flushAsync };

package/dist/wrap-D5f0P1iA.js

@@ -0,0 +1,180 @@
+//#region src/cells.ts
+var Buffer = class {
+	width;
+	height;
+	cells;
+	constructor(width, height) {
+		this.width = Math.max(0, width);
+		this.height = Math.max(0, height);
+		this.cells = Array.from({ length: this.width * this.height }, () => ({
+			char: " ",
+			style: {}
+		}));
+	}
+	set(x, y, char, style = {}) {
+		if (x < 0 || y < 0 || x >= this.width || y >= this.height) return;
+		this.cells[y * this.width + x] = {
+			char,
+			style
+		};
+	}
+	get(x, y) {
+		return this.cells[y * this.width + x] ?? {
+			char: " ",
+			style: {}
+		};
+	}
+	toString() {
+		const lines = [];
+		for (let y = 0; y < this.height; y++) {
+			let line = "";
+			for (let x = 0; x < this.width; x++) line += this.get(x, y).char;
+			lines.push(line.replace(/ +$/u, ""));
+		}
+		return lines.join("\n").replace(/\n+$/u, "");
+	}
+};
+//#endregion
+//#region src/host/borders.ts
+/** The library-wide default for components that draw a box-border chrome
+*  (DialogHost wrappers, Menu panels, Table grids). Declared once so the
+*  default is a single edit, not one per component. */
+const DEFAULT_BORDER_STYLE = "round";
+const GRID_CHARS = {
+	single: {
+		h: "─",
+		v: "│",
+		tl: "┌",
+		tr: "┐",
+		bl: "└",
+		br: "┘",
+		tDown: "┬",
+		tUp: "┴",
+		tRight: "├",
+		tLeft: "┤",
+		cross: "┼"
+	},
+	round: {
+		h: "─",
+		v: "│",
+		tl: "╭",
+		tr: "╮",
+		bl: "╰",
+		br: "╯",
+		tDown: "┬",
+		tUp: "┴",
+		tRight: "├",
+		tLeft: "┤",
+		cross: "┼"
+	},
+	double: {
+		h: "═",
+		v: "║",
+		tl: "╔",
+		tr: "╗",
+		bl: "╚",
+		br: "╝",
+		tDown: "╦",
+		tUp: "╩",
+		tRight: "╠",
+		tLeft: "╣",
+		cross: "╬"
+	},
+	bold: {
+		h: "━",
+		v: "┃",
+		tl: "┏",
+		tr: "┓",
+		bl: "┗",
+		br: "┛",
+		tDown: "┳",
+		tUp: "┻",
+		tRight: "┣",
+		tLeft: "┫",
+		cross: "╋"
+	},
+	classic: {
+		h: "-",
+		v: "|",
+		tl: "+",
+		tr: "+",
+		bl: "+",
+		br: "+",
+		tDown: "+",
+		tUp: "+",
+		tRight: "+",
+		tLeft: "+",
+		cross: "+"
+	}
+};
+const BORDER_CHARS = GRID_CHARS;
+//#endregion
+//#region src/wrap.ts
+const ELLIPSIS = "…";
+/**
+* Lay out `text` into display lines fitting within `width` cells.
+* Assumes 1 code point = 1 cell (no CJK/emoji width awareness in M1d).
+*
+*  - 'wrap'     — word-wrap at spaces; any single word longer than width is char-wrapped.
+*  - 'truncate' — each source line truncated to width, with `…` in the last cell when truncated.
+*  - 'none'     — each source line preserved unchanged (caller is responsible for overflow).
+*
+* Always returns at least one line (empty input → `['']`, matching measureText's height=1 default).
+*/
+function wrapText(text, width, mode) {
+	if (width < 0) width = 0;
+	const out = [];
+	for (const source of text.split("\n")) {
+		if (mode === "none") {
+			out.push(source);
+			continue;
+		}
+		if (mode === "truncate") {
+			out.push(truncateLine(source, width));
+			continue;
+		}
+		wrapLine(source, width, out);
+	}
+	if (out.length === 0) out.push("");
+	return out;
+}
+function truncateLine(line, width) {
+	if (width <= 0) return "";
+	const chars = [...line];
+	if (chars.length <= width) return line;
+	if (width === 1) return ELLIPSIS;
+	return chars.slice(0, width - 1).join("") + ELLIPSIS;
+}
+function wrapLine(line, width, out) {
+	if (width === 0) {
+		out.push("");
+		return;
+	}
+	if (line === "") {
+		out.push("");
+		return;
+	}
+	let current = "";
+	for (const word of line.split(" ")) {
+		const candidate = current ? current + " " + word : word;
+		if ([...candidate].length <= width) {
+			current = candidate;
+			continue;
+		}
+		if (current) {
+			out.push(current);
+			current = "";
+		}
+		if ([...word].length > width) {
+			let remainder = [...word];
+			while (remainder.length > width) {
+				out.push(remainder.slice(0, width).join(""));
+				remainder = remainder.slice(width);
+			}
+			current = remainder.join("");
+		} else current = word;
+	}
+	if (current) out.push(current);
+}
+//#endregion
+export { Buffer as a, GRID_CHARS as i, BORDER_CHARS as n, DEFAULT_BORDER_STYLE as r, wrapText as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowtty/core",
-  "version": "1.0.0-alpha.1",
+  "version": "1.0.0-alpha.11",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -41,13 +41,13 @@
     "dist"
   ],
   "scripts": {
-    "build": "tsup",
+    "build": "tsdown",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
     "yoga-layout": "^3.2.1"
   },
   "devDependencies": {
-    "tsup": "^8"
+    "tsdown": "^0.23.0"
   }
 }

package/dist/backend-BcB7VR87.d.ts

@@ -1,74 +0,0 @@
-import { B as Buffer } from './cells-CaXEx4lH.js';
-
-interface Key {
-    /**
-     * Canonical name of the key. For printable ASCII characters this is the
-     * character itself ('a', '!', ' '). For named keys: 'return', 'escape',
-     * 'tab', 'backspace', 'delete', 'up', 'down', 'left', 'right', 'home',
-     * 'end', 'pageup', 'pagedown'.
-     */
-    name: string;
-    /** Raw byte sequence as received from the source (empty for synthetic keys). */
-    sequence: string;
-    ctrl: boolean;
-    meta: boolean;
-    shift: boolean;
-}
-
-interface Backend {
-    size(): {
-        width: number;
-        height: number;
-    };
-    draw(buffer: Buffer): void;
-    /**
-     * Subscribe to raw key events. Returns an unsubscribe function.
-     * Backends without an input source omit this method.
-     */
-    onKey?(handler: (key: Key) => void): () => void;
-    /**
-     * Subscribe to terminal-resize events. Returns an unsubscribe function.
-     * Handlers are called AFTER `size()` reflects the new dimensions.
-     * Backends with fixed dimensions (e.g. the test backend) omit this method.
-     */
-    onResize?(handler: () => void): () => void;
-    dispose?(): void;
-    /**
-     * Append plain (already-styled, ANSI-ready) lines ABOVE the live region.
-     * The lines scroll naturally into the terminal's scrollback. Backends
-     * that own the whole screen (alt-screen TTY) or are headless (TestBackend)
-     * may omit this; components like <Static> check for presence at runtime
-     * and degrade gracefully when absent.
-     */
-    printStatic?(lines: string[]): void;
-    /**
-     * Whether this backend owns the entire render area — i.e. components can
-     * use the full `size()` for layout and overlay larger panels (Menu cascade,
-     * full-screen DialogHost) on top.
-     *
-     *   true  — TtyBackend (alt-screen), TestBackend (full buffer)
-     *   false — @flowtty/inline-tty-backend (only the live region is yours;
-     *           scrollback above is append-only and out of layout control)
-     *
-     * Defaults to `true` when omitted — preserves the behavior of existing
-     * backends that don't declare the flag. Inline-style backends MUST set
-     * it to `false` so capability-sensitive components (e.g. <Menu>) can
-     * refuse to render rather than produce broken overflow UI.
-     */
-    fullScreen?: boolean;
-    /**
-     * Whether this backend can emit OSC 8 terminal hyperlinks (clickable links).
-     *
-     *   true      — TTY backends (alt-screen + inline) wrap linked cells in the
-     *               OSC 8 escape, so a `<Link>` is clickable in supporting terminals.
-     *   omitted   — treated as false. The headless TestBackend and any output that
-     *     /false    can't render clickable links leave them out, so `<Link>` should
-     *               degrade to styled text plus a visible URL.
-     *
-     * Feature-detected like `fullScreen`: components read it (via useBackend())
-     * rather than assuming a capability.
-     */
-    hyperlinks?: boolean;
-}
-
-export type { Backend as B, Key as K };

package/dist/cells-CaXEx4lH.d.ts

@@ -1,31 +0,0 @@
-interface Style {
-    fg?: string;
-    bg?: string;
-    bold?: boolean;
-    dim?: boolean;
-    underline?: boolean;
-    inverse?: boolean;
-    strikethrough?: boolean;
-    /**
-     * Target URL for an OSC 8 terminal hyperlink. Backends that can emit
-     * clickable links (TTY / inline TTY) wrap this cell's char in the hyperlink
-     * escape; backends that can't (headless test surface) ignore it. Carried in
-     * Style so it threads through the same paint + diff path as visual attrs.
-     */
-    link?: string;
-}
-interface Cell {
-    char: string;
-    style: Style;
-}
-declare class Buffer {
-    readonly width: number;
-    readonly height: number;
-    private readonly cells;
-    constructor(width: number, height: number);
-    set(x: number, y: number, char: string, style?: Style): void;
-    get(x: number, y: number): Cell;
-    toString(): string;
-}
-
-export { Buffer as B, type Cell as C, type Style as S };