@cel-tui/core 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cel-tui/core",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Core framework engine for cel-tui — primitives, layout, rendering, input",
   "type": "module",
   "module": "src/index.ts",
@@ -34,7 +34,7 @@
     "layout"
   ],
   "dependencies": {
-    "@cel-tui/types": "0.3.0",
+    "@cel-tui/types": "0.4.0",
     "get-east-asian-width": "^1.5.0"
   },
   "peerDependencies": {

package/src/cel.ts

@@ -26,10 +26,18 @@ import {
   type EditState,
 } from "./text-edit.js";
 import type { Terminal } from "./terminal.js";
-import { visibleWidth } from "./width.js";
+import { getMaxScrollOffset, getScrollStep } from "./scroll.js";
 
 type RenderFn = () => Node | Node[];
 
+type TerminalCursorState =
+  | { visible: false }
+  | {
+      visible: true;
+      x: number;
+      y: number;
+    };
+
 let terminal: Terminal | null = null;
 let activeTheme: Theme = defaultTheme;
 let renderFn: RenderFn | null = null;
@@ -60,6 +68,9 @@ const uncontrolledScrollOffsets = new Map<string, number>();
 /** Nodes whose props were stamped with scrollOffset during the last paint. */
 let stampedScrollNodes: { node: Node; key: string }[] = [];
 
+/** The cursor state currently expected on the terminal. */
+let lastTerminalCursor: TerminalCursorState | null = { visible: false };
+
 function doRender(): void {
   renderScheduled = false;
   if (!renderFn || !terminal) return;
@@ -105,43 +116,38 @@ function doRender(): void {
   unstampUncontrolledFocus();
   unstampUncontrolledScroll();
 
+  const nextCursor = getDesiredTerminalCursor();
+
   // Emit to terminal — differential when possible
   if (prevBuffer) {
-    const output = emitDiff(prevBuffer, currentBuffer, activeTheme);
+    const output = emitDiff(prevBuffer, currentBuffer, activeTheme, {
+      cursor: nextCursor,
+      previousCursor: lastTerminalCursor,
+    });
     if (output.length > 0) terminal.write(output);
   } else {
-    const output = emitBuffer(currentBuffer, activeTheme);
+    const output = emitBuffer(currentBuffer, activeTheme, {
+      cursor: nextCursor,
+      previousCursor: lastTerminalCursor,
+    });
     terminal.write(output);
   }
 
-  // Position the native terminal cursor at the focused TextInput's cursor.
-  // This gives us a blinking cursor for free (terminal-managed blink).
-  positionTerminalCursor();
+  lastTerminalCursor = nextCursor;
 }
 
 /**
- * After each render, show the native terminal cursor at the focused
- * TextInput's cursor position (gives blinking for free). When no
- * TextInput is focused, hide the cursor.
+ * Resolve the final terminal cursor state for the current frame.
+ * The cursor is shown only for a focused TextInput whose cursor is visible
+ * within the clipped viewport.
  */
-function positionTerminalCursor(): void {
-  if (!terminal) return;
-
-  // Find focused TextInput in the layout tree (check stamped state during
-  // render — we need to check controlled focus in the current layouts)
+function getDesiredTerminalCursor(): TerminalCursorState {
   const focusedTI = findFocusedTextInputLayout();
-  if (focusedTI) {
-    const props = focusedTI.node
-      .props as import("@cel-tui/types").TextInputProps;
-    const pos = getTextInputCursorScreenPos(props, focusedTI.rect);
-    if (pos) {
-      // CUP: move cursor to (row, col) — 1-indexed
-      terminal.write(`\x1b[${pos.y + 1};${pos.x + 1}H`);
-      terminal.showCursor();
-      return;
-    }
-  }
-  terminal.hideCursor();
+  if (!focusedTI) return { visible: false };
+
+  const props = focusedTI.node.props as import("@cel-tui/types").TextInputProps;
+  const pos = getTextInputCursorScreenPos(props, focusedTI.rect);
+  return pos ? { visible: true, x: pos.x, y: pos.y } : { visible: false };
 }
 
 /**
@@ -453,49 +459,6 @@ function changeFocus(target: LayoutNode | null): void {
   }
 }
 
-/**
- * Compute the maximum scroll offset for a scrollable container or TextInput.
- * Returns 0 if content fits within the viewport.
- */
-function getMaxScrollOffset(target: LayoutNode): number {
-  const { rect, children } = target;
-
-  // TextInput: compute content height from wrapped text value
-  if (target.node.type === "textinput") {
-    const w = rect.width;
-    const value = target.node.props.value;
-    let lineCount = 0;
-    for (const rawLine of value.split("\n")) {
-      const lw = visibleWidth(rawLine);
-      lineCount += w > 0 && lw > w ? Math.ceil(lw / w) : 1;
-    }
-    return Math.max(0, lineCount - rect.height);
-  }
-
-  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;
-    }
-    // Viewport is the inner height (minus bottom padding)
-    // Content starts at padY, so contentHeight includes top padding offset
-    return Math.max(0, contentHeight + padY - rect.height);
-  } else {
-    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);
-  }
-}
-
 /**
  * Resolve the current scroll offset for a layout node.
  * Checks controlled (props.scrollOffset), then uncontrolled (path-based map).
@@ -539,7 +502,8 @@ function handleMouseEvent(event: MouseEvent): void {
     if (event.type === "scroll-up" || event.type === "scroll-down") {
       const target = findScrollTarget(path);
       if (target) {
-        const delta = event.type === "scroll-up" ? -1 : 1;
+        const step = getScrollStep(target);
+        const delta = event.type === "scroll-up" ? -step : step;
         const maxOffset = getMaxScrollOffset(target);
 
         if (target.node.type === "textinput") {
@@ -890,6 +854,7 @@ export const cel = {
   init(term: Terminal, options?: { theme?: Theme }): void {
     terminal = term;
     activeTheme = options?.theme ?? defaultTheme;
+    lastTerminalCursor = { visible: false };
     terminal.start(handleInput, () => cel.render());
   },
 
@@ -935,6 +900,7 @@ export const cel = {
     stampedNode = null;
     uncontrolledScrollOffsets.clear();
     stampedScrollNodes = [];
+    lastTerminalCursor = { visible: false };
     activeTheme = defaultTheme;
   },
 

package/src/emitter.ts

@@ -100,8 +100,61 @@ function hasStyle(cell: Cell): boolean {
 const SYNC_START = "\x1b[?2026h";
 const SYNC_END = "\x1b[?2026l";
 const CURSOR_HOME = "\x1b[H";
+const HIDE_CURSOR = "\x1b[?25l";
+const SHOW_CURSOR = "\x1b[?25h";
+const SAVE_CURSOR = "\x1b7";
+const RESTORE_CURSOR = "\x1b8";
 const RESET = "\x1b[0m";
 
+type CursorState =
+  | { visible: false }
+  | {
+      visible: true;
+      x: number;
+      y: number;
+    };
+
+interface EmitOptions {
+  cursor?: CursorState;
+  previousCursor?: CursorState | null;
+}
+
+function sameVisibleCursor(
+  a: CursorState | null | undefined,
+  b: CursorState | null | undefined,
+): boolean {
+  return (
+    a?.visible === true && b?.visible === true && a.x === b.x && a.y === b.y
+  );
+}
+
+function getCursorControls(
+  options: EmitOptions | undefined,
+  hasPaintOutput: boolean,
+): { prefix: string; suffix: string } {
+  const cursor = options?.cursor ?? { visible: false };
+  const previous = options?.previousCursor ?? null;
+
+  if (sameVisibleCursor(cursor, previous)) {
+    return hasPaintOutput
+      ? { prefix: SAVE_CURSOR, suffix: RESTORE_CURSOR }
+      : { prefix: "", suffix: "" };
+  }
+
+  if (cursor.visible) {
+    return {
+      prefix: "",
+      suffix:
+        `\x1b[${cursor.y + 1};${cursor.x + 1}H` +
+        (previous?.visible === true ? "" : SHOW_CURSOR),
+    };
+  }
+
+  return previous?.visible === true
+    ? { prefix: "", suffix: HIDE_CURSOR }
+    : { prefix: "", suffix: "" };
+}
+
 /**
  * Emit a full cell buffer as an ANSI string for terminal output.
  *
@@ -114,13 +167,16 @@ const RESET = "\x1b[0m";
  *
  * @param buf - The cell buffer to render.
  * @param theme - Color theme mapping. Defaults to the ANSI 16 theme.
+ * @param options - Optional terminal cursor state to apply before the synchronized output ends.
  * @returns A complete ANSI string ready to write to the terminal.
  */
 export function emitBuffer(
   buf: CellBuffer,
   theme: Theme = defaultTheme,
+  options?: EmitOptions,
 ): string {
-  let out = SYNC_START + CURSOR_HOME;
+  const cursorControls = getCursorControls(options, true);
+  let out = SYNC_START + cursorControls.prefix + CURSOR_HOME;
 
   let lastStyle: Cell | null = null;
 
@@ -153,7 +209,7 @@ export function emitBuffer(
     out += RESET;
   }
 
-  out += SYNC_END;
+  out += cursorControls.suffix + SYNC_END;
   return out;
 }
 
@@ -167,18 +223,21 @@ export function emitBuffer(
  * @param prev - The previous buffer.
  * @param next - The new buffer.
  * @param theme - Color theme mapping. Defaults to the ANSI 16 theme.
+ * @param options - Optional terminal cursor state to apply before the synchronized output ends.
  * @returns An ANSI string with only the changed cells.
  */
 export function emitDiff(
   prev: CellBuffer,
   next: CellBuffer,
   theme: Theme = defaultTheme,
+  options?: EmitOptions,
 ): string {
-  let out = SYNC_START;
-
   const changes = prev.diff(next);
+  const cursorControls = getCursorControls(options, changes.length > 0);
+  let out = SYNC_START + cursorControls.prefix;
+
   if (changes.length === 0) {
-    return out + SYNC_END;
+    return out + cursorControls.suffix + SYNC_END;
   }
 
   let lastStyle: Cell | null = null;
@@ -222,6 +281,6 @@ export function emitDiff(
     out += RESET;
   }
 
-  out += SYNC_END;
+  out += cursorControls.suffix + SYNC_END;
   return out;
 }

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/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);
+}

package/src/text-layout.ts

@@ -0,0 +1,250 @@
+import { visibleWidth } from "./width.js";
+
+const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+
+export interface VisualLine {
+  text: string;
+  startOffset: number;
+  endOffset: number;
+  width: number;
+}
+
+export interface VisualPosition {
+  line: number;
+  col: number;
+}
+
+export interface TextLayoutResult {
+  lines: VisualLine[];
+  lineCount: number;
+  offsetToPosition(offset: number): VisualPosition;
+}
+
+interface GraphemeInfo {
+  text: string;
+  startOffset: number;
+  endOffset: number;
+  width: number;
+  isWhitespace: boolean;
+}
+
+interface VisualLineData {
+  line: VisualLine;
+  graphemes: GraphemeInfo[];
+}
+
+interface Range {
+  start: number;
+  end: number;
+}
+
+export function layoutText(
+  value: string,
+  width: number,
+  wrap: "none" | "word",
+): TextLayoutResult {
+  const hardLines = splitHardLines(value);
+  const lines: VisualLineData[] = [];
+
+  for (const hardLine of hardLines) {
+    const graphemes = segmentLine(value, hardLine.start, hardLine.end);
+    if (wrap === "word") {
+      lines.push(
+        ...wrapGraphemes(value, graphemes, Math.max(1, width), hardLine),
+      );
+    } else {
+      lines.push(
+        ...buildVisualLines(
+          value,
+          graphemes,
+          [[0, graphemes.length]],
+          hardLine,
+        ),
+      );
+    }
+  }
+
+  if (lines.length === 0) {
+    const empty: VisualLineData = {
+      line: { text: "", startOffset: 0, endOffset: 0, width: 0 },
+      graphemes: [],
+    };
+    lines.push(empty);
+  }
+
+  return {
+    lines: lines.map((entry) => entry.line),
+    lineCount: lines.length,
+    offsetToPosition(offset: number): VisualPosition {
+      return offsetToPosition(lines, clamp(offset, 0, value.length));
+    },
+  };
+}
+
+function splitHardLines(value: string): Range[] {
+  const lines: Range[] = [];
+  let start = 0;
+  for (let i = 0; i < value.length; i++) {
+    if (value[i] === "\n") {
+      lines.push({ start, end: i });
+      start = i + 1;
+    }
+  }
+  lines.push({ start, end: value.length });
+  return lines;
+}
+
+function segmentLine(
+  value: string,
+  start: number,
+  end: number,
+): GraphemeInfo[] {
+  const graphemes: GraphemeInfo[] = [];
+  const text = value.slice(start, end);
+  let offset = start;
+
+  for (const { segment } of segmenter.segment(text)) {
+    graphemes.push({
+      text: segment,
+      startOffset: offset,
+      endOffset: offset + segment.length,
+      width: visibleWidth(segment),
+      isWhitespace: /^\s+$/u.test(segment),
+    });
+    offset += segment.length;
+  }
+
+  return graphemes;
+}
+
+function wrapGraphemes(
+  value: string,
+  graphemes: GraphemeInfo[],
+  width: number,
+  hardLine: Range,
+): VisualLineData[] {
+  if (graphemes.length === 0) {
+    return [makeVisualLine(value, graphemes, 0, 0, hardLine.start)];
+  }
+
+  const prefixWidths = [0];
+  for (const grapheme of graphemes) {
+    prefixWidths.push(prefixWidths[prefixWidths.length - 1]! + grapheme.width);
+  }
+
+  const ranges: Array<[number, number]> = [];
+  let lineStart = 0;
+
+  while (lineStart < graphemes.length) {
+    let lineEnd = lineStart;
+    let lastBreak = -1;
+
+    while (lineEnd < graphemes.length) {
+      const nextWidth = prefixWidths[lineEnd + 1]! - prefixWidths[lineStart]!;
+      if (nextWidth > width) break;
+      lineEnd++;
+      if (graphemes[lineEnd - 1]!.isWhitespace) {
+        lastBreak = lineEnd;
+      }
+    }
+
+    if (lineEnd >= graphemes.length) {
+      ranges.push([lineStart, graphemes.length]);
+      break;
+    }
+
+    if (lineEnd === lineStart) {
+      ranges.push([lineStart, lineStart + 1]);
+      lineStart++;
+      continue;
+    }
+
+    if (lastBreak > lineStart) {
+      ranges.push([lineStart, lastBreak]);
+      lineStart = lastBreak;
+      continue;
+    }
+
+    ranges.push([lineStart, lineEnd]);
+    lineStart = lineEnd;
+  }
+
+  return buildVisualLines(value, graphemes, ranges, hardLine);
+}
+
+function buildVisualLines(
+  value: string,
+  graphemes: GraphemeInfo[],
+  ranges: Array<[number, number]>,
+  hardLine: Range,
+): VisualLineData[] {
+  return ranges.map(([startIndex, endIndex]) =>
+    makeVisualLine(value, graphemes, startIndex, endIndex, hardLine.start),
+  );
+}
+
+function makeVisualLine(
+  value: string,
+  graphemes: GraphemeInfo[],
+  startIndex: number,
+  endIndex: number,
+  hardLineStart: number,
+): VisualLineData {
+  if (startIndex === endIndex) {
+    return {
+      line: {
+        text: "",
+        startOffset: hardLineStart,
+        endOffset: hardLineStart,
+        width: 0,
+      },
+      graphemes: [],
+    };
+  }
+
+  const lineGraphemes = graphemes.slice(startIndex, endIndex);
+  const startOffset = lineGraphemes[0]!.startOffset;
+  const endOffset = lineGraphemes[lineGraphemes.length - 1]!.endOffset;
+
+  return {
+    line: {
+      text: value.slice(startOffset, endOffset),
+      startOffset,
+      endOffset,
+      width: lineGraphemes.reduce((sum, grapheme) => sum + grapheme.width, 0),
+    },
+    graphemes: lineGraphemes,
+  };
+}
+
+function offsetToPosition(
+  lines: VisualLineData[],
+  offset: number,
+): VisualPosition {
+  for (let i = 1; i < lines.length; i++) {
+    if (offset === lines[i]!.line.startOffset) {
+      return { line: i, col: 0 };
+    }
+  }
+
+  for (let i = 0; i < lines.length; i++) {
+    const entry = lines[i]!;
+    const { line, graphemes } = entry;
+    if (offset < line.startOffset || offset > line.endOffset) continue;
+
+    let col = 0;
+    for (const grapheme of graphemes) {
+      if (offset <= grapheme.startOffset) break;
+      if (offset < grapheme.endOffset) break;
+      col += grapheme.width;
+    }
+    return { line: i, col };
+  }
+
+  const last = lines[lines.length - 1]!;
+  return { line: lines.length - 1, col: last.line.width };
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, value));
+}