@vui-rs/core 0.1.0

package/dist/offscreen-buffer.d.ts

@@ -0,0 +1,28 @@
+import { TextStyle } from "./renderer.js";
+import { Pointer } from "bun:ffi";
+
+//#region src/offscreen-buffer.d.ts
+declare class OffscreenBuffer {
+  #private;
+  constructor(width: number, height: number);
+  get width(): number;
+  get height(): number;
+  /** The native `*mut CellBuffer`. Used by `Renderer.blit`; do not retain across `free()`. */
+  get nativePtr(): Pointer;
+  drawText(x: number, y: number, text: string, style?: TextStyle): void;
+  fillRect(x: number, y: number, w: number, h: number, bg: number): void;
+  setCell(x: number, y: number, ch: number, style?: TextStyle): void;
+  clear(bg?: number): void;
+  /** Reallocate to a new size (clears it). Any previously fetched view dangles after. */
+  resize(width: number, height: number): void;
+  /**
+   * Zero-copy `Uint8Array` view over the native cells (stride `CELL_BYTES`). The
+   * view aliases native memory and dangles after `resize()`/`free()` — fetch a
+   * fresh one each time. Same wide-glyph pairing caveat as `Renderer.backBufferView`.
+   */
+  view(): Uint8Array;
+  /** Free the native buffer. Idempotent; the instance is unusable after. */
+  free(): void;
+}
+//#endregion
+export { OffscreenBuffer };

package/dist/offscreen-buffer.js

@@ -0,0 +1,73 @@
+import { Status } from "./native/ffi-symbols.js";
+import { loadNativeLib } from "./native/load-native-lib.js";
+import "./renderer.js";
+import { toArrayBuffer } from "bun:ffi";
+//#region src/offscreen-buffer.ts
+const DEFAULT_FG = 3857049087;
+const DEFAULT_BG = 255;
+const encoder = new TextEncoder();
+function check(status, op) {
+	if (status !== Status.OK) throw new Error(`vui-core offscreen ${op} failed with status ${status}`);
+}
+var OffscreenBuffer = class {
+	#lib = loadNativeLib();
+	#ptr;
+	#width;
+	#height;
+	constructor(width, height) {
+		const ptr = this.#lib.symbols.vui_cbuf_new(width, height);
+		if (ptr === null) throw new Error("vui-core: failed to allocate offscreen buffer");
+		this.#ptr = ptr;
+		this.#width = width;
+		this.#height = height;
+	}
+	get width() {
+		return this.#width;
+	}
+	get height() {
+		return this.#height;
+	}
+	/** The native `*mut CellBuffer`. Used by `Renderer.blit`; do not retain across `free()`. */
+	get nativePtr() {
+		return this.#ptr;
+	}
+	drawText(x, y, text, style = {}) {
+		const bytes = encoder.encode(text);
+		check(this.#lib.symbols.vui_cbuf_draw_text(this.#ptr, x, y, bytes, bytes.byteLength, style.fg ?? DEFAULT_FG, style.bg ?? DEFAULT_BG, style.attrs ?? 0), "draw_text");
+	}
+	fillRect(x, y, w, h, bg) {
+		check(this.#lib.symbols.vui_cbuf_fill_rect(this.#ptr, x, y, w, h, bg), "fill_rect");
+	}
+	setCell(x, y, ch, style = {}) {
+		check(this.#lib.symbols.vui_cbuf_set_cell(this.#ptr, x, y, ch, style.fg ?? DEFAULT_FG, style.bg ?? DEFAULT_BG, style.attrs ?? 0), "set_cell");
+	}
+	clear(bg = DEFAULT_BG) {
+		check(this.#lib.symbols.vui_cbuf_clear(this.#ptr, bg), "clear");
+	}
+	/** Reallocate to a new size (clears it). Any previously fetched view dangles after. */
+	resize(width, height) {
+		check(this.#lib.symbols.vui_cbuf_resize(this.#ptr, width, height), "resize");
+		this.#width = width;
+		this.#height = height;
+	}
+	/**
+	* Zero-copy `Uint8Array` view over the native cells (stride `CELL_BYTES`). The
+	* view aliases native memory and dangles after `resize()`/`free()` — fetch a
+	* fresh one each time. Same wide-glyph pairing caveat as `Renderer.backBufferView`.
+	*/
+	view() {
+		const ptr = this.#lib.symbols.vui_cbuf_ptr(this.#ptr);
+		if (ptr === null) throw new Error("vui-core: offscreen buffer pointer is null");
+		const cells = Number(this.#lib.symbols.vui_cbuf_len(this.#ptr));
+		return new Uint8Array(toArrayBuffer(ptr, 0, cells * 16));
+	}
+	/** Free the native buffer. Idempotent; the instance is unusable after. */
+	free() {
+		if (this.#ptr !== null) {
+			this.#lib.symbols.vui_cbuf_free(this.#ptr);
+			this.#ptr = null;
+		}
+	}
+};
+//#endregion
+export { OffscreenBuffer };

package/dist/renderer.d.ts

@@ -0,0 +1,106 @@
+import { VuiNode } from "./node.js";
+import { OffscreenBuffer } from "./offscreen-buffer.js";
+import { TextBufferView } from "./text/text-buffer-view.js";
+import { EditorView } from "./text/editor-view.js";
+
+//#region src/renderer.d.ts
+/** Pack 8-bit channels into the `0xRRGGBBAA` u32 the FFI expects. */
+declare function rgba(r: number, g: number, b: number, a?: number): number;
+interface TextStyle {
+  fg?: number;
+  bg?: number;
+  attrs?: number;
+}
+/** Half-open clip rect `[x0,x1) × [y0,y1)`; the JS twin of the native `ClipRect`. */
+interface ClipRect {
+  x0: number;
+  y0: number;
+  x1: number;
+  y1: number;
+}
+/**
+ * Thin, safe wrapper over the native renderer. Owns a `*mut Renderer` and
+ * mirrors the draw primitives. Drawing mutates the back buffer; `render()`
+ * diffs it against the screen and writes the minimal frame to stdout.
+ *
+ * Call `free()` exactly once when done — the instance must not be used after.
+ */
+declare class Renderer {
+  #private;
+  constructor(width: number, height: number);
+  get width(): number;
+  get height(): number;
+  drawText(x: number, y: number, text: string, style?: TextStyle): void;
+  fillRect(x: number, y: number, w: number, h: number, bg: number): void;
+  setCell(x: number, y: number, ch: number, style?: TextStyle): void;
+  clear(bg?: number): void;
+  drawTextClipped(x: number, y: number, text: string, style: TextStyle, clip: ClipRect): void;
+  fillRectClipped(x: number, y: number, w: number, h: number, bg: number, clip: ClipRect): void;
+  setCellClipped(x: number, y: number, ch: number, style: TextStyle, clip: ClipRect): void;
+  /** Composite an offscreen buffer into the back buffer at `(dstX, dstY)`, clipped. */
+  blit(src: OffscreenBuffer, dstX: number, dstY: number, clip: ClipRect): void;
+  /** Draw a native text-buffer view into the back buffer, clipped. */
+  drawTextBuffer(view: TextBufferView, x: number, y: number, style: TextStyle, clip: ClipRect): void;
+  /** Draw a native editor view, including its cursor when focused. */
+  drawEditor(view: EditorView, x: number, y: number, style: TextStyle & {
+    cursorBg?: number;
+  }, clip: ClipRect): void;
+  /** Diff the back buffer and write the frame to stdout. */
+  render(): void;
+  /**
+   * JS-host emit: diff + write the back buffer exactly as it was drawn, WITHOUT
+   * composing the native node tree. The JS paint walk clears + stamps the back
+   * buffer (via the clip-aware prims), then calls this to flush the frame.
+   */
+  flush(): void;
+  /** Drop all staged OSC 8 links; call before re-staging a frame's link table. */
+  clearLinks(): void;
+  /**
+   * Stage raw escape bytes to emit out-of-band on the next frame (image transmit,
+   * OSC 52 clipboard). Host-built sequences ONLY — never user text. A non-empty
+   * channel forces a frame; it clears after emit. Multiple calls concatenate.
+   */
+  stagePassthrough(bytes: Uint8Array): void;
+  /** Drop all Kitty image placements; call before re-staging a frame's placements. */
+  clearImagePlacements(): void;
+  /** Register image `id`'s on-screen top-left cell for placeholder placement. */
+  stageImagePlacement(id: number, x0: number, y0: number): void;
+  /**
+   * Stage one OSC 8 link table entry (`id` → URI). The emitter wraps cells whose
+   * `attrs` high byte equals `id` in the hyperlink. `id` 0 is "no link" (ignored).
+   */
+  stageLink(id: number, uri: string): void;
+  /**
+   * The implicit root node, created with the renderer and sized to the terminal.
+   * Build the UI as its descendants; `render()` lays out and paints the tree.
+   */
+  rootNode(): VuiNode;
+  /** Create a detached node (`"box"`, `"text"`, or `"edit"`); attach under a parent. */
+  createNode(kind: 'box' | 'text' | 'edit'): VuiNode;
+  /** Native structural hash of the tree; compare to `hostTreeHash` for desync. */
+  treeHash(): bigint;
+  /**
+   * Run taffy layout over the node tree (JS-host path) WITHOUT painting, sizing
+   * to the terminal by default. Read each node's box with `VuiNode.layoutRect`.
+   * Dirty-gate on the caller side (skip when no style/text changed).
+   */
+  computeLayout(width?: number, height?: number): void;
+  /** Reallocate to a new size; forces a full repaint on the next `render()`. */
+  resize(width: number, height: number): void;
+  /**
+   * Zero-copy `Uint8Array` view over the native back buffer (stride
+   * `CELL_BYTES`). The view aliases native memory and is NOT lifetime-tracked:
+   * it dangles after `resize()` (reallocates) or `free()` (deallocates). Do not
+   * retain a view across either call — fetch a fresh one each time. Intended for
+   * bulk writes and tests; prefer the draw methods for normal use. Raw writes
+   * must uphold the wide-glyph pairing invariant the draw methods maintain: a
+   * WIDE_CONTINUATION cell sits immediately right of a width-2 leader and only
+   * there — so when clearing a continuation cell, also blank its leader (and
+   * vice versa), or a half-glyph can linger on screen.
+   */
+  backBufferView(): Uint8Array;
+  /** Free the native renderer. Idempotent; the instance is unusable after. */
+  free(): void;
+}
+//#endregion
+export { ClipRect, Renderer, TextStyle, rgba };

package/dist/renderer.js

@@ -0,0 +1,186 @@
+import { NodeKindCode, Status } from "./native/ffi-symbols.js";
+import { loadNativeLib } from "./native/load-native-lib.js";
+import { VuiNode } from "./node.js";
+import "./offscreen-buffer.js";
+import { toArrayBuffer } from "bun:ffi";
+//#region src/renderer.ts
+/** Pack 8-bit channels into the `0xRRGGBBAA` u32 the FFI expects. */
+function rgba(r, g, b, a = 255) {
+	return ((r & 255) << 24 | (g & 255) << 16 | (b & 255) << 8 | a & 255) >>> 0;
+}
+const DEFAULT_FG = rgba(229, 229, 229);
+const DEFAULT_BG = rgba(0, 0, 0);
+const encoder = new TextEncoder();
+function check(status, op) {
+	if (status !== Status.OK) throw new Error(`vui-core ${op} failed with status ${status}`);
+}
+/**
+* Thin, safe wrapper over the native renderer. Owns a `*mut Renderer` and
+* mirrors the draw primitives. Drawing mutates the back buffer; `render()`
+* diffs it against the screen and writes the minimal frame to stdout.
+*
+* Call `free()` exactly once when done — the instance must not be used after.
+*/
+var Renderer = class {
+	#lib = loadNativeLib();
+	#ptr;
+	#width;
+	#height;
+	/** Reused scratch for clip rects passed to the native clipped prims (no per-op alloc). */
+	#clip = new Int32Array(4);
+	constructor(width, height) {
+		const ptr = this.#lib.symbols.vui_renderer_new(width, height);
+		if (ptr === null) throw new Error("vui-core: failed to allocate renderer");
+		this.#ptr = ptr;
+		this.#width = width;
+		this.#height = height;
+	}
+	get width() {
+		return this.#width;
+	}
+	get height() {
+		return this.#height;
+	}
+	drawText(x, y, text, style = {}) {
+		const bytes = encoder.encode(text);
+		check(this.#lib.symbols.vui_buffer_draw_text(this.#ptr, x, y, bytes, bytes.byteLength, style.fg ?? DEFAULT_FG, style.bg ?? DEFAULT_BG, style.attrs ?? 0), "draw_text");
+	}
+	fillRect(x, y, w, h, bg) {
+		check(this.#lib.symbols.vui_buffer_fill_rect(this.#ptr, x, y, w, h, bg), "fill_rect");
+	}
+	setCell(x, y, ch, style = {}) {
+		check(this.#lib.symbols.vui_buffer_set_cell(this.#ptr, x, y, ch, style.fg ?? DEFAULT_FG, style.bg ?? DEFAULT_BG, style.attrs ?? 0), "set_cell");
+	}
+	clear(bg = DEFAULT_BG) {
+		check(this.#lib.symbols.vui_buffer_clear(this.#ptr, bg), "clear");
+	}
+	#packClip(clip) {
+		this.#clip[0] = clip.x0;
+		this.#clip[1] = clip.y0;
+		this.#clip[2] = clip.x1;
+		this.#clip[3] = clip.y1;
+		return this.#clip;
+	}
+	drawTextClipped(x, y, text, style, clip) {
+		const bytes = encoder.encode(text);
+		check(this.#lib.symbols.vui_buffer_draw_text_clipped(this.#ptr, x, y, bytes, bytes.byteLength, style.fg ?? DEFAULT_FG, style.bg ?? DEFAULT_BG, style.attrs ?? 0, this.#packClip(clip)), "draw_text_clipped");
+	}
+	fillRectClipped(x, y, w, h, bg, clip) {
+		check(this.#lib.symbols.vui_buffer_fill_rect_clipped(this.#ptr, x, y, w, h, bg, this.#packClip(clip)), "fill_rect_clipped");
+	}
+	setCellClipped(x, y, ch, style, clip) {
+		check(this.#lib.symbols.vui_buffer_set_cell_clipped(this.#ptr, x, y, ch, style.fg ?? DEFAULT_FG, style.bg ?? DEFAULT_BG, style.attrs ?? 0, this.#packClip(clip)), "set_cell_clipped");
+	}
+	/** Composite an offscreen buffer into the back buffer at `(dstX, dstY)`, clipped. */
+	blit(src, dstX, dstY, clip) {
+		check(this.#lib.symbols.vui_buffer_blit(this.#ptr, src.nativePtr, dstX, dstY, this.#packClip(clip)), "blit");
+	}
+	/** Draw a native text-buffer view into the back buffer, clipped. */
+	drawTextBuffer(view, x, y, style, clip) {
+		check(this.#lib.symbols.vui_buffer_draw_textbuffer(this.#ptr, view.nativePtr, x, y, style.fg ?? DEFAULT_FG, style.bg ?? 0, style.bg === void 0 ? 0 : 1, style.attrs ?? 0, this.#packClip(clip)), "draw_textbuffer");
+	}
+	/** Draw a native editor view, including its cursor when focused. */
+	drawEditor(view, x, y, style, clip) {
+		check(this.#lib.symbols.vui_buffer_draw_editor(this.#ptr, view.nativePtr, x, y, style.fg ?? DEFAULT_FG, style.bg ?? DEFAULT_BG, style.cursorBg ?? style.fg ?? DEFAULT_FG, style.attrs ?? 0, this.#packClip(clip)), "draw_editor");
+	}
+	/** Diff the back buffer and write the frame to stdout. */
+	render() {
+		check(this.#lib.symbols.vui_renderer_render(this.#ptr), "render");
+	}
+	/**
+	* JS-host emit: diff + write the back buffer exactly as it was drawn, WITHOUT
+	* composing the native node tree. The JS paint walk clears + stamps the back
+	* buffer (via the clip-aware prims), then calls this to flush the frame.
+	*/
+	flush() {
+		check(this.#lib.symbols.vui_renderer_flush(this.#ptr), "flush");
+	}
+	/** Drop all staged OSC 8 links; call before re-staging a frame's link table. */
+	clearLinks() {
+		check(this.#lib.symbols.vui_renderer_clear_links(this.#ptr), "clear_links");
+	}
+	/**
+	* Stage raw escape bytes to emit out-of-band on the next frame (image transmit,
+	* OSC 52 clipboard). Host-built sequences ONLY — never user text. A non-empty
+	* channel forces a frame; it clears after emit. Multiple calls concatenate.
+	*/
+	stagePassthrough(bytes) {
+		if (bytes.byteLength === 0) return;
+		check(this.#lib.symbols.vui_renderer_stage_passthrough(this.#ptr, bytes, bytes.byteLength), "stage_passthrough");
+	}
+	/** Drop all Kitty image placements; call before re-staging a frame's placements. */
+	clearImagePlacements() {
+		check(this.#lib.symbols.vui_renderer_clear_image_placements(this.#ptr), "clear_image_placements");
+	}
+	/** Register image `id`'s on-screen top-left cell for placeholder placement. */
+	stageImagePlacement(id, x0, y0) {
+		check(this.#lib.symbols.vui_renderer_stage_image_placement(this.#ptr, id, x0, y0), "stage_image_placement");
+	}
+	/**
+	* Stage one OSC 8 link table entry (`id` → URI). The emitter wraps cells whose
+	* `attrs` high byte equals `id` in the hyperlink. `id` 0 is "no link" (ignored).
+	*/
+	stageLink(id, uri) {
+		const bytes = encoder.encode(uri);
+		check(this.#lib.symbols.vui_renderer_stage_link(this.#ptr, id, bytes, bytes.byteLength), "stage_link");
+	}
+	/**
+	* The implicit root node, created with the renderer and sized to the terminal.
+	* Build the UI as its descendants; `render()` lays out and paints the tree.
+	*/
+	rootNode() {
+		const id = this.#lib.symbols.vui_renderer_set_root(this.#ptr);
+		return new VuiNode(this.#lib, this.#ptr, id, 0);
+	}
+	/** Create a detached node (`"box"`, `"text"`, or `"edit"`); attach under a parent. */
+	createNode(kind) {
+		const code = kind === "text" ? NodeKindCode.Text : kind === "edit" ? NodeKindCode.Edit : NodeKindCode.Box;
+		const id = this.#lib.symbols.vui_node_new(this.#ptr, code);
+		if (id === 0) throw new Error("vui-core: failed to create node");
+		return new VuiNode(this.#lib, this.#ptr, id, code);
+	}
+	/** Native structural hash of the tree; compare to `hostTreeHash` for desync. */
+	treeHash() {
+		return this.#lib.symbols.vui_debug_tree_hash(this.#ptr);
+	}
+	/**
+	* Run taffy layout over the node tree (JS-host path) WITHOUT painting, sizing
+	* to the terminal by default. Read each node's box with `VuiNode.layoutRect`.
+	* Dirty-gate on the caller side (skip when no style/text changed).
+	*/
+	computeLayout(width = this.#width, height = this.#height) {
+		check(this.#lib.symbols.vui_layout_compute(this.#ptr, width, height), "layout_compute");
+	}
+	/** Reallocate to a new size; forces a full repaint on the next `render()`. */
+	resize(width, height) {
+		check(this.#lib.symbols.vui_renderer_resize(this.#ptr, width, height), "resize");
+		this.#width = width;
+		this.#height = height;
+	}
+	/**
+	* Zero-copy `Uint8Array` view over the native back buffer (stride
+	* `CELL_BYTES`). The view aliases native memory and is NOT lifetime-tracked:
+	* it dangles after `resize()` (reallocates) or `free()` (deallocates). Do not
+	* retain a view across either call — fetch a fresh one each time. Intended for
+	* bulk writes and tests; prefer the draw methods for normal use. Raw writes
+	* must uphold the wide-glyph pairing invariant the draw methods maintain: a
+	* WIDE_CONTINUATION cell sits immediately right of a width-2 leader and only
+	* there — so when clearing a continuation cell, also blank its leader (and
+	* vice versa), or a half-glyph can linger on screen.
+	*/
+	backBufferView() {
+		const ptr = this.#lib.symbols.vui_renderer_back_buffer_ptr(this.#ptr);
+		if (ptr === null) throw new Error("vui-core: back buffer pointer is null");
+		const cells = Number(this.#lib.symbols.vui_renderer_buffer_len(this.#ptr));
+		return new Uint8Array(toArrayBuffer(ptr, 0, cells * 16));
+	}
+	/** Free the native renderer. Idempotent; the instance is unusable after. */
+	free() {
+		if (this.#ptr !== null) {
+			this.#lib.symbols.vui_renderer_free(this.#ptr);
+			this.#ptr = null;
+		}
+	}
+};
+//#endregion
+export { Renderer, rgba };

package/dist/style.d.ts

@@ -0,0 +1,48 @@
+//#region src/style.d.ts
+/** A length in cells (number), a percentage, or `auto`. */
+type Dim = number | 'auto' | {
+  pct: number;
+};
+/** One side value, or per-side values; a scalar applies to all four sides. */
+type Sides = Dim | {
+  left?: Dim;
+  right?: Dim;
+  top?: Dim;
+  bottom?: Dim;
+};
+type AlignValue = 'start' | 'end' | 'flex-start' | 'flex-end' | 'center' | 'baseline' | 'stretch';
+type JustifyValue = 'start' | 'end' | 'flex-start' | 'flex-end' | 'center' | 'space-between' | 'space-evenly' | 'space-around';
+interface VuiStyle {
+  display?: 'flex' | 'none';
+  position?: 'relative' | 'absolute';
+  flexDirection?: 'row' | 'column' | 'row-reverse' | 'column-reverse';
+  flexWrap?: 'nowrap' | 'wrap' | 'wrap-reverse';
+  alignItems?: AlignValue;
+  alignSelf?: AlignValue;
+  justifyContent?: JustifyValue;
+  flexGrow?: number;
+  flexShrink?: number;
+  flexBasis?: Dim;
+  width?: Dim;
+  height?: Dim;
+  minWidth?: Dim;
+  minHeight?: Dim;
+  maxWidth?: Dim;
+  maxHeight?: Dim;
+  padding?: Sides;
+  margin?: Sides;
+  border?: Sides;
+  inset?: Sides;
+  gap?: number | {
+    width?: number;
+    height?: number;
+  };
+}
+/**
+ * Pack a `VuiStyle` into the native `StyleFfi` byte layout. Writes every field
+ * (seeding CSS defaults for omitted ones) so the buffer never carries stale
+ * bytes. Returns a `Uint8Array` to pass as the `*const StyleFfi` pointer arg.
+ */
+declare function packStyle(style: VuiStyle): Uint8Array;
+//#endregion
+export { AlignValue, Dim, JustifyValue, Sides, VuiStyle, packStyle };

package/dist/style.js

@@ -0,0 +1,134 @@
+import "./native/ffi-symbols.js";
+//#region src/style.ts
+const DIM_AUTO = 0;
+const DIM_LENGTH = 1;
+const DIM_PERCENT = 2;
+const DISPLAY = {
+	flex: 0,
+	none: 1
+};
+const POSITION = {
+	relative: 0,
+	absolute: 1
+};
+const FLEX_DIR = {
+	row: 0,
+	column: 1,
+	"row-reverse": 2,
+	"column-reverse": 3
+};
+const FLEX_WRAP = {
+	nowrap: 0,
+	wrap: 1,
+	"wrap-reverse": 2
+};
+const ALIGN = {
+	start: 1,
+	end: 2,
+	"flex-start": 3,
+	"flex-end": 4,
+	center: 5,
+	baseline: 6,
+	stretch: 7,
+	"space-between": 8,
+	"space-evenly": 9,
+	"space-around": 10
+};
+/** Resolve a `Dim` to its `(kind, value)` pair. */
+function dimParts(d) {
+	if (d === "auto") return [DIM_AUTO, 0];
+	if (typeof d === "number") return [DIM_LENGTH, d];
+	return [DIM_PERCENT, d.pct];
+}
+/** Expand a `Sides` shorthand into explicit per-side dims. */
+function sides(s, fallback) {
+	if (s === void 0) return {
+		left: fallback,
+		right: fallback,
+		top: fallback,
+		bottom: fallback
+	};
+	if (typeof s === "number" || s === "auto" || "pct" in s) {
+		const d = s;
+		return {
+			left: d,
+			right: d,
+			top: d,
+			bottom: d
+		};
+	}
+	const o = s;
+	return {
+		left: o.left ?? fallback,
+		right: o.right ?? fallback,
+		top: o.top ?? fallback,
+		bottom: o.bottom ?? fallback
+	};
+}
+/**
+* Pack a `VuiStyle` into the native `StyleFfi` byte layout. Writes every field
+* (seeding CSS defaults for omitted ones) so the buffer never carries stale
+* bytes. Returns a `Uint8Array` to pass as the `*const StyleFfi` pointer arg.
+*/
+function packStyle(style) {
+	const buf = /* @__PURE__ */ new ArrayBuffer(236);
+	const view = new DataView(buf);
+	let off = 0;
+	const u32 = (v) => {
+		view.setUint32(off, v >>> 0, true);
+		off += 4;
+	};
+	const f32 = (v) => {
+		view.setFloat32(off, v, true);
+		off += 4;
+	};
+	const dim = (d) => {
+		const [kind, value] = dimParts(d);
+		u32(kind);
+		f32(value);
+	};
+	u32(DISPLAY[style.display ?? "flex"]);
+	u32(POSITION[style.position ?? "relative"]);
+	u32(FLEX_DIR[style.flexDirection ?? "row"]);
+	u32(FLEX_WRAP[style.flexWrap ?? "nowrap"]);
+	u32(style.alignItems ? ALIGN[style.alignItems] : 0);
+	u32(style.alignSelf ? ALIGN[style.alignSelf] : 0);
+	u32(style.justifyContent ? ALIGN[style.justifyContent] : 0);
+	f32(style.flexGrow ?? 0);
+	f32(style.flexShrink ?? 1);
+	dim(style.flexBasis ?? "auto");
+	dim(style.width ?? "auto");
+	dim(style.height ?? "auto");
+	dim(style.minWidth ?? "auto");
+	dim(style.minHeight ?? "auto");
+	dim(style.maxWidth ?? "auto");
+	dim(style.maxHeight ?? "auto");
+	const pad = sides(style.padding, 0);
+	dim(pad.left);
+	dim(pad.right);
+	dim(pad.top);
+	dim(pad.bottom);
+	const mar = sides(style.margin, 0);
+	dim(mar.left);
+	dim(mar.right);
+	dim(mar.top);
+	dim(mar.bottom);
+	const bor = sides(style.border, 0);
+	dim(bor.left);
+	dim(bor.right);
+	dim(bor.top);
+	dim(bor.bottom);
+	const ins = sides(style.inset, "auto");
+	dim(ins.left);
+	dim(ins.right);
+	dim(ins.top);
+	dim(ins.bottom);
+	const gapW = typeof style.gap === "number" ? style.gap : style.gap?.width ?? 0;
+	const gapH = typeof style.gap === "number" ? style.gap : style.gap?.height ?? 0;
+	dim(gapW);
+	dim(gapH);
+	if (off !== 236) throw new Error(`packStyle wrote ${off} bytes, expected 236`);
+	return new Uint8Array(buf);
+}
+//#endregion
+export { packStyle };

package/dist/terminal-session.d.ts

@@ -0,0 +1,43 @@
+//#region src/terminal-session.d.ts
+/** The slice of `process.stdin` this module needs (injectable for tests). */
+interface InputStream {
+  isTTY?: boolean;
+  setRawMode?(mode: boolean): void;
+  resume?(): void;
+  pause?(): void;
+  on(event: string, listener: (...args: unknown[]) => void): void;
+  off(event: string, listener: (...args: unknown[]) => void): void;
+}
+/** The slice of `process.stdout` this module needs (injectable for tests). */
+interface OutputStream {
+  columns?: number;
+  rows?: number;
+  write(data: string): void;
+  on(event: string, listener: (...args: unknown[]) => void): void;
+  off(event: string, listener: (...args: unknown[]) => void): void;
+}
+interface TerminalSessionOptions {
+  input?: InputStream;
+  output?: OutputStream;
+  /** Enter the alt screen on start / leave it on stop. Default true. */
+  altScreen?: boolean;
+  /** Wire exit/signal/uncaught handlers for guaranteed restore. Default true. */
+  installSignalHandlers?: boolean;
+  /** Push the Kitty keyboard protocol (disambiguate flag) on start. Default true. */
+  kittyKeyboard?: boolean;
+}
+interface TerminalSession {
+  /** Enter raw mode + alt screen, begin emitting data/resize callbacks. */
+  start(): void;
+  onData(cb: (data: string) => void): void;
+  onResize(cb: (cols: number, rows: number) => void): void;
+  /** Idempotent restore: leave raw/alt-screen state, detach all listeners. */
+  stop(): void;
+  readonly size: {
+    cols: number;
+    rows: number;
+  };
+}
+declare function createTerminalSession(options?: TerminalSessionOptions): TerminalSession;
+//#endregion
+export { TerminalSession, TerminalSessionOptions, createTerminalSession };