@cel-tui/core 0.3.0 → 0.4.1

package/src/keys.ts

@@ -1,7 +1,7 @@
 /**
- * Key parsing for the Kitty keyboard protocol (level 1 — disambiguate).
+ * Key parsing for Kitty-first terminal input with legacy compatibility.
  *
- * At level 1, the terminal sends:
+ * The decoder accepts a mixed keyboard stream containing:
  * - **CSI u** (`ESC [ codepoint ; modifiers u`) for modified special keys
  *   and modifier combos (Ctrl+letter, Alt+letter, Shift+Tab, Ctrl+Enter, etc.)
  * - **CSI letter** (`ESC [ A/B/C/D/H/F` or `ESC [ 1 ; modifiers letter`) for
@@ -9,16 +9,26 @@
  * - **CSI tilde** (`ESC [ number ~` or `ESC [ number ; modifiers ~`) for
  *   Delete, PageUp, PageDown, and function keys
  * - **Legacy bytes** for unmodified special keys (Tab=0x09, Enter=0x0D,
- *   Escape=0x1B, Backspace=0x7F) — these retain their traditional encoding
- * - **Raw bytes** for unmodified printable characters
+ *   Escape=0x1B, Backspace=0x7F)
+ * - **Recoverable control bytes** for legacy `ctrl+letter` shortcuts
+ * - **ESC-prefixed Alt combinations** such as `ESC x`
+ * - **Raw printable text**
  *
  * Modifier bitmask (wire value = bitmask + 1):
- * shift=1, alt=2, ctrl=4 → e.g., ctrl = bitmask 4, wire param = 5
+ * shift=1, alt=2, ctrl=4 -> e.g., ctrl = bitmask 4, wire param = 5
  *
  * @module
  */
 
-// --- Codepoint → named key mappings ---
+/** A decoded keyboard event from the terminal input stream. */
+export interface KeyInput {
+  /** Normalized semantic key string (e.g. `"ctrl+s"`, `"enter"`, `"a"`). */
+  key: string;
+  /** Original insertable text, when this key should insert text. */
+  text?: string;
+}
+
+// --- Codepoint -> named key mappings ---
 
 /** Named key lookup from Unicode codepoint (for CSI u sequences). */
 const CODEPOINT_NAMES: Record<number, string> = {
@@ -60,7 +70,7 @@ const TILDE_NAMES: Record<number, string> = {
 };
 
 /**
- * Legacy byte → named key mapping for unmodified special keys.
+ * Legacy byte -> named key mapping for unmodified special keys.
  *
  * At Kitty level 1, unmodified special keys that have well-known legacy
  * encodings retain those encodings. Only modified variants (e.g., Shift+Tab,
@@ -68,8 +78,8 @@ const TILDE_NAMES: Record<number, string> = {
  * bytes that arrive for the unmodified case.
  */
 const LEGACY_BYTE_NAMES: Record<number, string> = {
-  9: "tab", // \t — also Ctrl+I in legacy, but at level 1 Ctrl+I → CSI u
-  13: "enter", // \r — also Ctrl+M in legacy, but at level 1 Ctrl+M → CSI u
+  9: "tab", // \t — also Ctrl+I in legacy, but collapsed to tab here
+  13: "enter", // \r — also Ctrl+M in legacy, but collapsed to enter here
   27: "escape", // \x1b — bare ESC byte
   127: "backspace", // \x7f — DEL byte
 };
@@ -99,9 +109,7 @@ function decodeModifiers(param: number): string {
   return parts.length > 0 ? parts.join("+") + "+" : "";
 }
 
-/**
- * Build a key string from a modifier prefix and base key name.
- */
+/** Build a key string from a modifier prefix and base key name. */
 function withModifiers(modParam: number, base: string): string {
   return decodeModifiers(modParam) + base;
 }
@@ -117,88 +125,157 @@ const CSI_LETTER_RE = /^(?:1;(\d+))?([A-H])$/;
 /** Match CSI tilde format: ESC [ <number> ; <modifiers> ~ */
 const CSI_TILDE_RE = /^(\d+)(?:;(\d+))?~$/;
 
-function parseCsiSequence(seq: string): string {
+function parseCsiSequence(seq: string): KeyInput {
   // Legacy Shift+Tab (CSI Z) — sent by tmux and some terminals
-  if (seq === "Z") return "shift+tab";
+  if (seq === "Z") return { key: "shift+tab" };
 
   // CSI u format: codepoint [; modifiers] u
   let match = CSI_U_RE.exec(seq);
   if (match) {
     const codepoint = parseInt(match[1]!, 10);
-    const modParam = match[2] ? parseInt(match[2], 10) : 0;
+    const modParam = match[2] ? parseInt(match[2]!, 10) : 0;
 
-    // Check named keys first
     const name = CODEPOINT_NAMES[codepoint];
-    if (name) return withModifiers(modParam, name);
-
-    // Printable character — convert codepoint to char, lowercase
-    const char = String.fromCodePoint(codepoint).toLowerCase();
-    return withModifiers(modParam, char);
+    if (name) {
+      return { key: withModifiers(modParam, name) };
+    }
+
+    const char = String.fromCodePoint(codepoint);
+    const key = withModifiers(modParam, char.toLowerCase());
+    if (modParam <= 1) {
+      return { key, text: char };
+    }
+    return { key };
   }
 
   // CSI letter format: [1 ; modifiers] <letter>
   match = CSI_LETTER_RE.exec(seq);
   if (match) {
-    const modParam = match[1] ? parseInt(match[1], 10) : 0;
+    const modParam = match[1] ? parseInt(match[1]!, 10) : 0;
     const letter = match[2]!;
     const name = LETTER_NAMES[letter];
-    if (name) return withModifiers(modParam, name);
+    if (name) return { key: withModifiers(modParam, name) };
   }
 
   // CSI tilde format: number [; modifiers] ~
   match = CSI_TILDE_RE.exec(seq);
   if (match) {
     const num = parseInt(match[1]!, 10);
-    const modParam = match[2] ? parseInt(match[2], 10) : 0;
+    const modParam = match[2] ? parseInt(match[2]!, 10) : 0;
     const name = TILDE_NAMES[num];
-    if (name) return withModifiers(modParam, name);
+    if (name) return { key: withModifiers(modParam, name) };
   }
 
-  return `unknown:${seq}`;
+  return { key: `unknown:${seq}` };
 }
 
-// --- Public API ---
-
-/**
- * Parse raw terminal input data into a normalized key string.
- *
- * Handles the Kitty keyboard protocol level 1 (disambiguate) encoding:
- * - CSI u sequences for special keys and modifier combos
- * - CSI letter sequences for arrow keys and Home/End (with optional modifiers)
- * - CSI tilde sequences for Delete, PageUp/Down, and function keys
- * - Raw printable characters (unmodified, arrive as raw bytes at level 1)
- *
- * @param data - Raw terminal input string.
- * @returns Normalized key string (e.g., `"ctrl+s"`, `"escape"`, `"alt+up"`).
- */
-export function parseKey(data: string): string {
-  // CSI sequences: ESC [ ...
-  if (data.startsWith("\x1b[")) {
-    return parseCsiSequence(data.slice(2));
+function decodeLegacyControlByte(code: number): string | null {
+  if (code >= 1 && code <= 26) {
+    return `ctrl+${String.fromCharCode(code + 96)}`;
   }
+  return null;
+}
 
-  // Single-character input
-  if (data.length === 1) {
-    const code = data.charCodeAt(0);
+function parseRawKeyInput(data: string): KeyInput {
+  const code = data.charCodeAt(0);
 
-    // Legacy bytes for unmodified special keys (Kitty level 1 retains these)
-    const legacy = LEGACY_BYTE_NAMES[code];
-    if (legacy) return legacy;
+  const legacy = LEGACY_BYTE_NAMES[code];
+  if (legacy) return { key: legacy };
 
-    // Named printable characters
-    const named = CHAR_NAMES[data];
-    if (named) return named;
+  const ctrl = decodeLegacyControlByte(code);
+  if (ctrl) return { key: ctrl };
+
+  const named = CHAR_NAMES[data];
+  if (named) return { key: named, text: data };
+
+  return { key: data.toLowerCase(), text: data };
+}
+
+function parseAltKeyInput(data: string): KeyInput {
+  const base = parseRawKeyInput(data);
+  return { key: normalizeKey(`alt+${base.key}`) };
+}
 
-    // Printable characters — return lowercase
-    return data.toLowerCase();
+function readCodePoint(
+  data: string,
+  index: number,
+): { value: string; nextIndex: number } | null {
+  if (index >= data.length) return null;
+  const codepoint = data.codePointAt(index);
+  if (codepoint === undefined) return null;
+  const value = String.fromCodePoint(codepoint);
+  return { value, nextIndex: index + value.length };
+}
+
+function readCsiSequence(
+  data: string,
+  index: number,
+): { value: string; nextIndex: number } | null {
+  if (!data.startsWith("\x1b[", index)) return null;
+
+  for (let i = index + 2; i < data.length; i++) {
+    const code = data.charCodeAt(i);
+    if (code >= 0x40 && code <= 0x7e) {
+      return { value: data.slice(index + 2, i + 1), nextIndex: i + 1 };
+    }
   }
 
-  // Multi-byte UTF-8 (e.g., emoji, CJK) — return as-is lowercase
-  if (data.length > 1) {
-    return data.toLowerCase();
+  return null;
+}
+
+/**
+ * Decode a raw keyboard data chunk into ordered key events.
+ *
+ * A single chunk may contain multiple key presses batched together.
+ */
+export function decodeKeyEvents(data: string): KeyInput[] {
+  const events: KeyInput[] = [];
+  let index = 0;
+
+  while (index < data.length) {
+    const csi = readCsiSequence(data, index);
+    if (csi) {
+      events.push(parseCsiSequence(csi.value));
+      index = csi.nextIndex;
+      continue;
+    }
+
+    const char = data[index]!;
+    if (char === "\x1b") {
+      const next = readCodePoint(data, index + 1);
+      if (next && next.value !== "[") {
+        events.push(parseAltKeyInput(next.value));
+        index = next.nextIndex;
+      } else {
+        events.push({ key: "escape" });
+        index += 1;
+      }
+      continue;
+    }
+
+    const codePoint = readCodePoint(data, index);
+    if (!codePoint) break;
+    events.push(parseRawKeyInput(codePoint.value));
+    index = codePoint.nextIndex;
   }
 
-  return `unknown:${data}`;
+  return events;
+}
+
+// --- Public API ---
+
+/**
+ * Parse a single raw key sequence into a normalized key string.
+ *
+ * This is a convenience wrapper around {@link decodeKeyEvents} for callers that
+ * already know the input contains one logical key event.
+ *
+ * @param data - Raw terminal input string.
+ * @returns Normalized key string (e.g., `"ctrl+s"`, `"escape"`, `"alt+up"`).
+ */
+export function parseKey(data: string): string {
+  const events = decodeKeyEvents(data);
+  return events[0]?.key ?? `unknown:${data}`;
 }
 
 /**
@@ -217,7 +294,6 @@ export function normalizeKey(key: string): string {
   const base = parts[parts.length - 1]!;
   const mods = parts.slice(0, -1);
 
-  // Canonical order: ctrl, alt, shift
   const ordered: string[] = [];
   if (mods.includes("ctrl")) ordered.push("ctrl");
   if (mods.includes("alt")) ordered.push("alt");
@@ -227,14 +303,15 @@ export function normalizeKey(key: string): string {
 }
 
 /**
- * Check if a parsed key is a text-editing key that TextInput should consume.
- * Modifier combos (ctrl+s, alt+x) are NOT editing keys and should bubble.
+ * Check whether a semantic key represents TextInput editing/navigation.
+ *
+ * Single-character semantic keys represent insertable text, while named keys
+ * like `"enter"` and `"left"` represent editing/navigation actions. Modifier
+ * combos (`ctrl+s`, `alt+x`) are NOT editing keys and should bubble.
  */
 export function isEditingKey(key: string): boolean {
-  // Single printable characters
   if (key.length === 1) return true;
 
-  // Navigation and editing keys consumed by TextInput
   const editingKeys = new Set([
     "enter",
     "backspace",

package/src/layout.ts

@@ -1,4 +1,5 @@
 import type { Node, ContainerProps, SizeValue } from "@cel-tui/types";
+import { layoutText } from "./text-layout.js";
 import { visibleWidth } from "./width.js";
 
 /**
@@ -58,20 +59,11 @@ function intrinsicMainSize(
 ): number {
   if (node.type === "text") {
     if (isVertical) {
-      // Height = number of lines
-      if (node.content.length === 0) return 1;
-      const lines = node.content.split("\n");
-      if (node.props.wrap === "word") {
-        let total = 0;
-        for (const line of lines) {
-          total += Math.max(
-            1,
-            Math.ceil(visibleWidth(line) / Math.max(1, crossSize)),
-          );
-        }
-        return total;
-      }
-      return lines.length;
+      return layoutText(
+        node.content,
+        Math.max(1, crossSize),
+        node.props.wrap ?? "none",
+      ).lineCount;
     }
     // Width (intrinsic)
     if (node.props.repeat === "fill") return 0;
@@ -91,16 +83,7 @@ function intrinsicMainSize(
     if (isVertical) {
       const val = node.props.value || "";
       const innerCrossForTI = Math.max(1, crossSize - tiPadX);
-      if (val.length === 0) return 1 + tiPadY;
-      const lines = val.split("\n");
-      let total = 0;
-      for (const line of lines) {
-        total += Math.max(
-          1,
-          Math.ceil(visibleWidth(line) / Math.max(1, innerCrossForTI)),
-        );
-      }
-      return total + tiPadY;
+      return layoutText(val, innerCrossForTI, "word").lineCount + tiPadY;
     }
     return 0 + tiPadX;
   }

package/src/paint.ts

@@ -2,6 +2,8 @@ import type { Color, StyleProps, TextInputProps } from "@cel-tui/types";
 import type { Cell } from "./cell-buffer.js";
 import { CellBuffer } from "./cell-buffer.js";
 import type { LayoutNode, Rect } from "./layout.js";
+import { getMaxScrollOffset } from "./scroll.js";
+import { layoutText } from "./text-layout.js";
 import { visibleWidth } from "./width.js";
 
 const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
@@ -104,32 +106,6 @@ function fillBackground(
   }
 }
 
-/**
- * Compute the maximum scroll offset for a scrollable container.
- * This is the content size minus the viewport size along the main axis.
- */
-function computeMaxScrollOffset(ln: LayoutNode, isVertical: boolean): number {
-  const { rect, children } = ln;
-  const props = ln.node.type !== "text" ? ln.node.props : null;
-  const padX = (props as any)?.padding?.x ?? 0;
-  const padY = (props as any)?.padding?.y ?? 0;
-
-  if (isVertical) {
-    let contentHeight = 0;
-    for (const child of children) {
-      const childBottom = child.rect.y + child.rect.height - rect.y;
-      if (childBottom > contentHeight) contentHeight = childBottom;
-    }
-    return Math.max(0, contentHeight + padY - rect.height);
-  }
-  let contentWidth = 0;
-  for (const child of children) {
-    const childRight = child.rect.x + child.rect.width - rect.x;
-    if (childRight > contentWidth) contentWidth = childRight;
-  }
-  return Math.max(0, contentWidth + padX - rect.width);
-}
-
 function paintLayoutNode(
   ln: LayoutNode,
   buf: CellBuffer,
@@ -203,7 +179,7 @@ function paintLayoutNode(
   if (isScrollable) {
     const raw = containerProps.scrollOffset ?? 0;
     // Clamp to valid range so apps can pass large values to mean "scroll to end"
-    const maxOffset = computeMaxScrollOffset(ln, isVertical);
+    const maxOffset = getMaxScrollOffset(ln);
     scrollOffset = Math.max(0, Math.min(raw, maxOffset));
   }
 
@@ -434,26 +410,11 @@ function paintText(
     text = content.repeat(props.repeat);
   }
 
-  // Split into lines
-  const rawLines = text.split("\n");
-
-  // Word-wrap if enabled
-  const lines: string[] = [];
-  if (props.wrap === "word") {
-    for (const rawLine of rawLines) {
-      if (visibleWidth(rawLine) <= w) {
-        lines.push(rawLine);
-      } else {
-        wrapLine(rawLine, w, lines);
-      }
-    }
-  } else {
-    lines.push(...rawLines);
-  }
+  const textLayout = layoutText(text, w, props.wrap ?? "none");
 
   // Paint lines, clipped to rect (grapheme-aware)
-  for (let row = 0; row < lines.length && row < h; row++) {
-    const line = lines[row]!;
+  for (let row = 0; row < textLayout.lineCount && row < h; row++) {
+    const line = textLayout.lines[row]!.text;
     paintLineGraphemes(line, x, y + row, w, clipRect, props, buf);
   }
 }
@@ -510,22 +471,14 @@ function paintTextInput(
     return;
   }
 
-  // Word-wrap value (always on for TextInput) using content width
-  const lines: string[] = [];
-  for (const rawLine of value.split("\n")) {
-    if (visibleWidth(rawLine) <= cw) {
-      lines.push(rawLine);
-    } else {
-      wrapLine(rawLine, cw, lines);
-    }
-  }
+  const textLayout = layoutText(value, cw, "word");
 
   // Framework-managed scroll: auto-scroll to keep cursor visible
   let scrollOffset = getTextInputScroll(props);
 
   if (props.focused) {
     const cursorOffset = getTextInputCursor(props);
-    const cursorPos = offsetToWrappedPos(value, cursorOffset, cw);
+    const cursorPos = textLayout.offsetToPosition(cursorOffset);
     // Scroll down if cursor is below viewport
     if (cursorPos.line >= scrollOffset + ch) {
       scrollOffset = cursorPos.line - ch + 1;
@@ -540,8 +493,8 @@ function paintTextInput(
   // Paint visible lines (grapheme-aware) in content area
   for (let row = 0; row < ch; row++) {
     const lineIdx = scrollOffset + row;
-    if (lineIdx >= lines.length) break;
-    const line = lines[lineIdx]!;
+    if (lineIdx >= textLayout.lineCount) break;
+    const line = textLayout.lines[lineIdx]!.text;
     paintLineGraphemes(line, cx, cy + row, cw, clipRect, props, buf);
   }
 
@@ -551,7 +504,7 @@ function paintTextInput(
   // for blinking.
   if (props.focused) {
     const cursorOffset = getTextInputCursor(props);
-    const pos = offsetToWrappedPos(value, cursorOffset, cw);
+    const pos = textLayout.offsetToPosition(cursorOffset);
     const screenRow = pos.line - scrollOffset;
     if (screenRow >= 0 && screenRow < ch && pos.col < cw) {
       const absX = cx + pos.col;
@@ -581,43 +534,6 @@ function paintTextInput(
   }
 }
 
-/**
- * Map a cursor offset in the raw value to a (line, col) position
- * in the word-wrapped output.
- */
-function offsetToWrappedPos(
-  value: string,
-  cursor: number,
-  width: number,
-): { line: number; col: number } {
-  const rawLines = value.split("\n");
-  let offset = 0;
-  let wrappedLine = 0;
-
-  for (const rawLine of rawLines) {
-    if (cursor <= offset + rawLine.length) {
-      // Cursor is in this raw line
-      const colInRaw = cursor - offset;
-      if (width <= 0) return { line: wrappedLine, col: colInRaw };
-      // Compute visible width of text before cursor
-      const textBeforeCursor = rawLine.slice(0, colInRaw);
-      const vw = visibleWidth(textBeforeCursor);
-      const extraLines = Math.floor(vw / width);
-      return { line: wrappedLine + extraLines, col: vw % width };
-    }
-    // Count wrapped lines for this raw line
-    const lineVW = visibleWidth(rawLine);
-    if (lineVW <= width || width <= 0) {
-      wrappedLine += 1;
-    } else {
-      wrappedLine += Math.ceil(lineVW / width);
-    }
-    offset += rawLine.length + 1; // +1 for \n
-  }
-
-  return { line: wrappedLine, col: 0 };
-}
-
 // --- Framework-managed state ---
 
 import type { ContainerProps } from "@cel-tui/types";
@@ -653,7 +569,8 @@ export function getTextInputCursorScreenPos(
   if (cw <= 0 || ch <= 0) return null;
 
   const cursorOffset = getTextInputCursor(props);
-  const pos = offsetToWrappedPos(props.value, cursorOffset, cw);
+  const textLayout = layoutText(props.value, cw, "word");
+  const pos = textLayout.offsetToPosition(cursorOffset);
   const scrollOffset = getTextInputScroll(props);
   const screenRow = pos.line - scrollOffset;
 
@@ -692,58 +609,3 @@ export function setTextInputScroll(
 ): void {
   textInputScrolls.set(props.onChange, scroll);
 }
-
-/**
- * Simple word-wrap: break a line into multiple lines at word boundaries.
- */
-function wrapLine(line: string, width: number, out: string[]): void {
-  if (width <= 0) return;
-
-  let current = "";
-  let currentW = 0;
-  const words = line.split(" ");
-
-  for (const word of words) {
-    const wordW = visibleWidth(word);
-    if (currentW === 0) {
-      current = word;
-      currentW = wordW;
-    } else if (currentW + 1 + wordW <= width) {
-      current += " " + word;
-      currentW += 1 + wordW;
-    } else {
-      out.push(current);
-      current = word;
-      currentW = wordW;
-    }
-
-    // Handle words longer than width (break by grapheme)
-    while (currentW > width) {
-      let taken = "";
-      let takenW = 0;
-      let rest = "";
-      let inRest = false;
-      for (const { segment } of segmenter.segment(current)) {
-        if (inRest) {
-          rest += segment;
-          continue;
-        }
-        const gw = visibleWidth(segment);
-        if (takenW + gw > width) {
-          rest += segment;
-          inRest = true;
-        } else {
-          taken += segment;
-          takenW += gw;
-        }
-      }
-      out.push(taken);
-      current = rest;
-      currentW = visibleWidth(rest);
-    }
-  }
-
-  if (current.length > 0) {
-    out.push(current);
-  }
-}

package/src/primitives/text-input.ts

@@ -11,12 +11,14 @@ import type { TextInputNode, TextInputProps } from "@cel-tui/types";
  * Scroll is always uncontrolled — the view follows the cursor and
  * responds to mouse wheel automatically.
  *
- * TextInput is always focusable. When focused, text-editing keys
- * (printable characters, arrows, backspace, Enter, Tab) are consumed.
- * Modifier combos (e.g., `ctrl+s`) bubble up to ancestor `onKeyPress` handlers.
+ * TextInput is always focusable. When focused, it consumes insertable text
+ * plus editing/navigation keys (arrows, backspace, delete, Enter, Tab).
+ * Modifier combos (e.g., `ctrl+s`) and non-insertable control keys bubble
+ * up to ancestor `onKeyPress` handlers.
  *
- * Use `onKeyPress` to intercept keys before editing. Return `false` to
- * prevent the default editing action for that key.
+ * Use `onKeyPress` to intercept keys before editing. The handler receives a
+ * normalized semantic key string; inserted text preserves the original
+ * characters. Return `false` to prevent the default editing action.
  *
  * @param props - Value, callbacks, sizing, styling, and focus props.
  * @returns A text input node for the UI tree.

package/src/scroll.ts

@@ -0,0 +1,77 @@
+import type { LayoutNode } from "./layout.js";
+import { layoutText } from "./text-layout.js";
+
+function isVerticalScrollTarget(target: LayoutNode): boolean {
+  return target.node.type === "vstack" || target.node.type === "textinput";
+}
+
+function getScrollTargetProps(target: LayoutNode): Record<string, any> {
+  return target.node.props as Record<string, any>;
+}
+
+function getScrollViewportMainAxisSize(target: LayoutNode): number {
+  const props = getScrollTargetProps(target);
+  const isVertical = isVerticalScrollTarget(target);
+  const mainAxisSize = isVertical ? target.rect.height : target.rect.width;
+  const mainAxisPadding = isVertical
+    ? (props.padding?.y ?? 0) * 2
+    : (props.padding?.x ?? 0) * 2;
+  return Math.max(1, mainAxisSize - mainAxisPadding);
+}
+
+/**
+ * Resolve the mouse wheel scroll step for a scrollable layout node.
+ * Uses the explicit `scrollStep` prop when provided, otherwise an
+ * adaptive default based on the visible main-axis viewport size.
+ */
+export function getScrollStep(target: LayoutNode): number {
+  const rawStep = getScrollTargetProps(target).scrollStep;
+  if (Number.isFinite(rawStep) && rawStep > 0) {
+    return Math.max(1, Math.floor(rawStep));
+  }
+
+  const viewport = getScrollViewportMainAxisSize(target);
+  return Math.max(3, Math.min(8, Math.floor(viewport / 3)));
+}
+
+/**
+ * Compute the maximum scroll offset for a scrollable layout node.
+ * Returns 0 if content fits within the viewport.
+ */
+export function getMaxScrollOffset(target: LayoutNode): number {
+  const { rect, children } = target;
+
+  if (target.node.type === "textinput") {
+    const padX = (target.node.props.padding?.x ?? 0) * 2;
+    const padY = (target.node.props.padding?.y ?? 0) * 2;
+    const contentWidth = Math.max(1, rect.width - padX);
+    const contentHeight = Math.max(0, rect.height - padY);
+    const lineCount = layoutText(
+      target.node.props.value,
+      contentWidth,
+      "word",
+    ).lineCount;
+    return Math.max(0, lineCount - contentHeight);
+  }
+
+  const isVertical = target.node.type === "vstack";
+  const props = target.node.type !== "text" ? target.node.props : null;
+  const padX = (props as any)?.padding?.x ?? 0;
+  const padY = (props as any)?.padding?.y ?? 0;
+
+  if (isVertical) {
+    let contentHeight = 0;
+    for (const child of children) {
+      const childBottom = child.rect.y + child.rect.height - rect.y;
+      if (childBottom > contentHeight) contentHeight = childBottom;
+    }
+    return Math.max(0, contentHeight + padY - rect.height);
+  }
+
+  let contentWidth = 0;
+  for (const child of children) {
+    const childRight = child.rect.x + child.rect.width - rect.x;
+    if (childRight > contentWidth) contentWidth = childRight;
+  }
+  return Math.max(0, contentWidth + padX - rect.width);
+}