@textui/core 0.3.0 → 0.5.0

package/dist/util/text.d.ts

@@ -1,4 +1,12 @@
 import type { TextWrap } from '../types/style.js';
+/**
+ * True for a string that is entirely printable ASCII.
+ *
+ * Worth asking, because the answer is yes for very nearly all of it: source
+ * code, file names, labels, key hints. Every character is then one grapheme
+ * one cell wide, and none of the Unicode machinery below has anything to do.
+ */
+export declare function isAscii(text: string): boolean;
 /**
  * Split into grapheme clusters. Falls back to code points without Intl.
  *
@@ -58,7 +66,16 @@ export declare function wrapModeOf(wrap: TextWrap | undefined): WrapMode;
 /** Break into lines of at most `width` cells. Honours existing newlines. */
 export declare function wrapText(text: string, width: number, mode?: WrapMode): string[];
 export declare function stripAnsi(text: string): string;
-/** Remove control characters that would corrupt the frame. Keeps newlines. */
+/**
+ * Remove control characters that would corrupt the frame. Keeps newlines.
+ *
+ * Two regular expressions over every string on screen, every frame, and for
+ * almost all of them the answer is the string it was given. `test` before
+ * `replace` is one scan that stops at the first match instead of two that
+ * always run to the end and allocate a copy each - and it returns the original
+ * string, so the callers that follow it get a cache hit on the width they
+ * already worked out rather than an equal-but-different string.
+ */
 export declare function sanitize(text: string): string;
 /** Repeat a grapheme to exactly `width` cells (wide chars land short). */
 export declare function repeatToWidth(char: string, width: number): string;

package/dist/util/text.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../../src/util/text.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AA8BlD;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAShD;AA8ED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAsBrD;AAED,2CAA2C;AAC3C,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQhD;AAED,+EAA+E;AAC/E,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAYhE;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAgC/E;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,MAAM,CAuB7D;AAED,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEtD,+DAA+D;AAC/D,wBAAgB,QAAQ,CACtB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,QAAQ,SAAM,EACd,IAAI,GAAE,YAAoB,GACzB,MAAM,CAkCR;AAED,2EAA2E;AAC3E,wBAAgB,KAAK,CACnB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,KAAK,GAAE,MAAM,GAAG,QAAQ,GAAG,OAAgB,EAC3C,IAAI,SAAM,GACT,MAAM,CAQR;AAED,kEAAkE;AAClE,wBAAgB,KAAK,CACnB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,KAAK,GAAE,MAAM,GAAG,QAAQ,GAAG,OAAgB,EAC3C,QAAQ,SAAM,GACb,MAAM,CAER;AAED,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAEhD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,GAAG,SAAS,GAAG,YAAY,GAAG,SAAS,CAOnF;AAED,iFAAiF;AACjF,wBAAgB,UAAU,CAAC,IAAI,EAAE,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAE/D;AAED,4EAA4E;AAC5E,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,QAAiB,GAAG,MAAM,EAAE,CAuDvF;AAOD,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED,8EAA8E;AAC9E,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAG7C;AAED,0EAA0E;AAC1E,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAIjE"}
+{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../../src/util/text.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAelD;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAM7C;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAShD;AA8ED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAsBrD;AAsBD,2CAA2C;AAC3C,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAgBhD;AAED,+EAA+E;AAC/E,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAYhE;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAgC/E;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,MAAM,CAuB7D;AAED,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEtD,+DAA+D;AAC/D,wBAAgB,QAAQ,CACtB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,QAAQ,SAAM,EACd,IAAI,GAAE,YAAoB,GACzB,MAAM,CAkCR;AAED,2EAA2E;AAC3E,wBAAgB,KAAK,CACnB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,KAAK,GAAE,MAAM,GAAG,QAAQ,GAAG,OAAgB,EAC3C,IAAI,SAAM,GACT,MAAM,CAQR;AAED,kEAAkE;AAClE,wBAAgB,KAAK,CACnB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,KAAK,GAAE,MAAM,GAAG,QAAQ,GAAG,OAAgB,EAC3C,QAAQ,SAAM,GACb,MAAM,CAER;AAED,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAEhD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,GAAG,SAAS,GAAG,YAAY,GAAG,SAAS,CAOnF;AAED,iFAAiF;AACjF,wBAAgB,UAAU,CAAC,IAAI,EAAE,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAE/D;AAED,4EAA4E;AAC5E,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,QAAiB,GAAG,MAAM,EAAE,CAuDvF;AAOD,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C;AAgBD;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAG7C;AAED,0EAA0E;AAC1E,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAIjE"}

package/dist/util/text.js

@@ -15,7 +15,7 @@ const segmenter = typeof Intl !== 'undefined' && 'Segmenter' in Intl
  * code, file names, labels, key hints. Every character is then one grapheme
  * one cell wide, and none of the Unicode machinery below has anything to do.
  */
-function isAscii(text) {
+export function isAscii(text) {
     for (let i = 0; i < text.length; i++) {
         const c = text.charCodeAt(i);
         if (c < 0x20 || c > 0x7e)
@@ -148,6 +148,25 @@ export function graphemeWidth(cluster) {
         return 2;
     return 1;
 }
+/**
+ * Widths already worked out, for strings that are not plain ASCII.
+ *
+ * The same strings are measured over and over. A frame measures the tree, lays
+ * it out and paints it - which is three walks over the same text - and then
+ * the next frame does all three again for content that has not changed. Nearly
+ * every row in a terminal application carries one glyph among its ASCII, a box
+ * rule or a bullet or an icon, and a single non-ASCII character sends the whole
+ * string down the slow path: an array of one-character strings, and a width
+ * classification for each of them. That was a quarter of the frame in a long
+ * transcript, spent proving the same sentences were the same width they were a
+ * thirtieth of a second ago.
+ *
+ * Only the slow path is remembered. ASCII is answered by `.length` before the
+ * map is even consulted, which is cheaper than the lookup would be, so the
+ * cache holds only what it saves anything on.
+ */
+const widths = new Map();
+const WIDTH_CACHE = 8192;
 /** Width of a string in terminal cells. */
 export function stringWidth(text) {
     if (text === '')
@@ -155,9 +174,18 @@ export function stringWidth(text) {
     // Fast path: pure ASCII printable.
     if (isAscii(text))
         return text.length;
+    const seen = widths.get(text);
+    if (seen !== undefined)
+        return seen;
     let w = 0;
     for (const g of graphemes(text))
         w += graphemeWidth(g);
+    // Emptied rather than evicted one at a time: a terminal's vocabulary of
+    // strings is small and slow-moving, so the cap is only ever reached by
+    // something streaming new text, and for that the whole map is stale.
+    if (widths.size >= WIDTH_CACHE)
+        widths.clear();
+    widths.set(text, w);
     return w;
 }
 /** Take at most `width` cells from the front. Never splits a wide grapheme. */
@@ -405,10 +433,33 @@ const ANSI_RE =
 export function stripAnsi(text) {
     return text.replace(ANSI_RE, '');
 }
-/** Remove control characters that would corrupt the frame. Keeps newlines. */
+/*
+ * Test copies, without the `g` flag.
+ *
+ * `test` on a global regular expression advances its `lastIndex` and starts
+ * the next call from there, so the same string tested twice answers yes then
+ * no. Asking is a different question from replacing and gets its own pattern.
+ */
+// eslint-disable-next-line no-control-regex
+const ANSI_TEST = /\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~]|\][^\x07\x1B]*(?:\x07|\x1B\\))/;
+// eslint-disable-next-line no-control-regex
+const CONTROL_TEST = /[\x00-\x08\x0B-\x1F\x7F]/;
+// eslint-disable-next-line no-control-regex
+const CONTROL_RE = /[\x00-\x08\x0B-\x1F\x7F]/g;
+/**
+ * Remove control characters that would corrupt the frame. Keeps newlines.
+ *
+ * Two regular expressions over every string on screen, every frame, and for
+ * almost all of them the answer is the string it was given. `test` before
+ * `replace` is one scan that stops at the first match instead of two that
+ * always run to the end and allocate a copy each - and it returns the original
+ * string, so the callers that follow it get a cache hit on the width they
+ * already worked out rather than an equal-but-different string.
+ */
 export function sanitize(text) {
-    // eslint-disable-next-line no-control-regex
-    return stripAnsi(text).replace(/[\x00-\x08\x0B-\x1F\x7F]/g, '');
+    if (ANSI_TEST.test(text))
+        return stripAnsi(text).replace(CONTROL_RE, '');
+    return CONTROL_TEST.test(text) ? text.replace(CONTROL_RE, '') : text;
 }
 /** Repeat a grapheme to exactly `width` cells (wide chars land short). */
 export function repeatToWidth(char, width) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@textui/core",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Graph-mounted terminal UI runtime - store, registries, renderer, host primitives",
   "keywords": [
     "terminal",

package/src/app/app.ts

@@ -7,6 +7,7 @@ import type { ResourceAdapter } from '../types/adapter.js';
 import type { Size, Rect } from '../types/geometry.js';
 import type { ResolvedTheme } from '../types/theme.js';
 import type { TerminalCapabilities, CapabilityOverrides } from '../types/capabilities.js';
+import type { TerminalSessionOptions } from '../types/terminal.js';
 import type { InputEvent, KeyEvent, MouseEvent } from '../types/input.js';
 import type { LayerEntry } from '../types/layer.js';
 import type { Instance } from '../runtime/instance.js';
@@ -93,6 +94,8 @@ export class App implements TextUIApp {
   private frameScheduled = false;
   private frameTimer: ReturnType<typeof setTimeout> | null = null;
   private running_ = false;
+  /** What `start` acquired, so `suspend` can put the same thing back. */
+  private session: TerminalSessionOptions | null = null;
   private disposed = false;
   private themeId: string;
   private shellId: string;
@@ -363,7 +366,10 @@ export class App implements TextUIApp {
     }
 
     const caps = this.terminal.capabilities();
-    await this.terminal.acquire({
+    // Kept, because `suspend` has to put back exactly what was taken: a
+    // session re-acquired from defaults would come back without the mouse, or
+    // with an alt screen the caller had asked not to have.
+    this.session = {
       managed: true,
       altScreen: true,
       hideCursor: true,
@@ -373,7 +379,8 @@ export class App implements TextUIApp {
       focusEvents: caps.focusEvents,
       enhancedKeys: caps.kittyKeyboard,
       ...this.options.session,
-    });
+    };
+    await this.terminal.acquire(this.session);
 
     // After `acquire`, never before: with no session there is nothing to put
     // the shape back, so an early call is dropped rather than leaked.
@@ -387,6 +394,36 @@ export class App implements TextUIApp {
     this.renderFrame();
   }
 
+  /**
+   * Hand the terminal to something else, and take it back.
+   *
+   * For a program that draws for itself - an editor, a pager, a shell. The
+   * session is released, so the alt screen is left, raw mode is off and the
+   * child inherits a terminal in the state it expects; then it is acquired
+   * again exactly as it was.
+   *
+   * The frame buffer is invalidated on the way back rather than merely
+   * redrawn. The renderer writes the difference between what it painted last
+   * and what it paints now, and after another program has been on the screen
+   * that difference is against something no longer there - so a plain redraw
+   * puts back only the cells this application happened to change.
+   *
+   * `run` rejecting still gives the terminal back.
+   */
+  async suspend<T>(run: () => Promise<T>): Promise<T> {
+    if (!this.running_ || !this.session) return run();
+    await this.terminal.release();
+    try {
+      return await run();
+    }
+    finally {
+      await this.terminal.acquire(this.session);
+      this.applyCursorShape();
+      this.buffer_.invalidate();
+      this.renderFrame();
+    }
+  }
+
   async stop(): Promise<void> {
     if (!this.running_) return;
     this.running_ = false;
@@ -816,7 +853,21 @@ export class App implements TextUIApp {
     walkInstances(this.root, (instance) => {
       if (position) return;
       const cursor = instance.props.cursor;
-      if (!cursor || !instance.box) return;
+      /*
+       * Absent, not falsy.
+       *
+       * `cursor` is a column, and column 0 is a real one - it is where the
+       * caret sits in an empty field, and where it sits at the start of any
+       * field. `!cursor` treated that as "no caret here", so a text input
+       * published no cursor position at all until its first character was
+       * typed: the terminal cursor stayed hidden, and the only thing marking
+       * the focused control was its border colour.
+       *
+       * `true` still means "here, at offset 0", which is what the `typeof`
+       * below is for - so this rejects the three ways of saying nothing and
+       * nothing else.
+       */
+      if (cursor === undefined || cursor === null || cursor === false || !instance.box) return;
       const id = typeof instance.props.id === 'string' ? instance.props.id : instance.id;
       if (id !== focused && `${instance.id}:focus` !== focused) return;
 
@@ -941,6 +992,33 @@ export class App implements TextUIApp {
     } catch (err) {
       this.handleError(err, `input:${event.type}`);
     }
+
+    /*
+     * Pointer motion and the wheel are streams, and only where they got to
+     * means anything.
+     *
+     * A terminal reports every cell the pointer crosses and every notch of the
+     * wheel, and one read can carry twenty of them - so rendering per event
+     * lays out and paints the whole tree twenty times to draw one gesture. The
+     * cost is the size of the tree, which is why it is invisible on a short
+     * screen and, on a long transcript, is the thing being dragged trailing
+     * seconds behind the pointer and a wheel that goes on scrolling after the
+     * hand has stopped. That second one is the tell: it is not momentum, it is
+     * a backlog of events still being drawn one frame each.
+     *
+     * Only the drawing is coalesced. Every event is still dispatched, so the
+     * notches still add up and the pointer still ends where it ended; what
+     * they share is the one frame `handleMouse` asked for, at the animation
+     * ceiling rather than at whatever rate the terminal felt like reporting.
+     *
+     * Keys are the opposite and stay synchronous: every one of them is a
+     * separate thing a person did, and a handler closes over the props from
+     * its last render, so typing "ab" without a frame in between makes the
+     * handler for "b" see the state from before "a".
+     */
+    if (event.type === 'mouse'
+      && (event.action === 'move' || event.action === 'drag' || event.action === 'wheel')) return;
+
     if (this.running_ && this.isDirty()) this.renderFrame();
   }
 

package/src/jsx/intrinsics.ts

@@ -1,4 +1,4 @@
-import type { Style, StyleInput } from '../types/style.js';
+import type { Style, StyleColor, StyleInput } from '../types/style.js';
 import type { SemanticRole } from '../types/component-registry.js';
 import type { KeyEvent, MouseEvent } from '../types/input.js';
 import type { PaintSurface, RenderContext } from '../types/render.js';
@@ -99,6 +99,19 @@ export interface TextProps extends BaseProps {
   /** Where to cut when the text does not fit. */
   truncate?: 'end' | 'start' | 'middle' | false;
   ellipsis?: string;
+  /**
+   * Text to pick out wherever it appears, case-insensitively.
+   *
+   * For search: the caller passes what it is looking for and the rows are
+   * coloured where they hold it. It is applied after wrapping and truncation,
+   * to the text as drawn - so nothing about how a paragraph is broken into
+   * lines has to change to mark a hit in it, and a match split across a wrap
+   * is simply not on either row to colour.
+   */
+  match?: string;
+  /** The match's colours. Accent on its own foreground by default. */
+  matchFg?: StyleColor;
+  matchBg?: StyleColor;
 }
 
 export interface CanvasProps extends BaseProps {

package/src/render/buffer.ts

@@ -2,6 +2,16 @@ import type { Rect } from '../types/geometry.js';
 import type { Cell, CellBuffer } from '../types/cells.js';
 import { COLOR_DEFAULT, packColor, type PackedColor } from './color.js';
 
+/**
+ * A character no cell can hold, for the previous frame when it must not match.
+ *
+ * `put` refuses the empty string and every real glyph is one the terminal can
+ * print, so NUL is a value that never arrives from a render and never leaves
+ * one: `diffFrame` reads `chars`, never `prevChars`, so this is only ever a
+ * comparison and is never written out.
+ */
+const NEVER = '\u0000';
+
 /** One cell as it is stored: colours packed, nothing allocated to read it. */
 export interface PackedCell {
   char: string;
@@ -238,7 +248,7 @@ export class Buffer implements CellBuffer {
 
     // A resize invalidates the previous frame entirely.
     const n = width * height;
-    this.prevChars = new Array<string>(n).fill(' ');
+    this.prevChars = new Array<string>(n).fill(NEVER);
     this.prevFg = new Int32Array(n).fill(COLOR_DEFAULT);
     this.prevBg = new Int32Array(n).fill(COLOR_DEFAULT);
     this.prevAttrs = new Uint16Array(n);
@@ -282,9 +292,25 @@ export class Buffer implements CellBuffer {
     this.committed = true;
   }
 
-  /** Force the next diff to repaint everything. After a resize or a redraw. */
+  /**
+   * Force the next diff to repaint everything. After a resize or a redraw.
+   *
+   * Both halves, and the second one is the one that was missing. Clearing
+   * `committed` makes `dirtyRows` return every row, but `diffFrame` still
+   * skips each cell that matches the previous frame - and a blank cell in the
+   * new frame matched the reset previous frame exactly, so it was never
+   * written. Under a theme with an opaque canvas nothing showed, because every
+   * cell carries a background colour and therefore differs anyway. Under a
+   * theme with a transparent one the blanks are default-on-default, and the
+   * terminal kept whatever the old layout had left in them: a resize scattered
+   * the previous frame across the new one and it never cleared.
+   *
+   * So the previous frame is filled with a character no cell can hold, which
+   * is a comparison that cannot come out equal.
+   */
   invalidate(): void {
     this.committed = false;
+    this.prevChars.fill(NEVER);
   }
 
   toText(rect?: Rect): string {

package/src/render/layout.ts

@@ -40,6 +40,19 @@ export interface LayoutBox {
   /** Content larger than `content`, when overflow is 'scroll'. */
   scrollSize?: Size;
 
+  /**
+   * Frame and gaps, worked out once for this box.
+   *
+   * Neither depends on the space being offered - they are the box's own
+   * margin, border, padding and gap - and the box is measured about four
+   * times a frame at different bounds, each of which was rebuilding both and
+   * allocating three objects to do it. Same lifetime as `measured` below, and
+   * for the same reason: a layout box is rebuilt from the instance tree every
+   * frame, so nothing here can go stale.
+   */
+  frame?: { margin: Edges; inset: Edges };
+  gaps?: { main: number; cross: number };
+
   /**
    * The last answer `measureBox` gave for this box, and what it was asked.
    *
@@ -145,11 +158,15 @@ function mainOverflow(box: LayoutBox): Overflow {
  * that sets both reads the same either way round.
  */
 function gapsOf(box: LayoutBox): { main: number; cross: number } {
+  const seen = box.gaps;
+  if (seen !== undefined) return seen;
   const vertical = box.style.rowGap ?? box.style.gap ?? 0;
   const horizontal = box.style.columnGap ?? box.style.gap ?? 0;
-  return isColumn(box)
+  const gaps = isColumn(box)
     ? { main: vertical, cross: horizontal }
     : { main: horizontal, cross: vertical };
+  box.gaps = gaps;
+  return gaps;
 }
 
 /**
@@ -181,10 +198,12 @@ function splitLines(mains: number[], gap: number, limit: number): [number, numbe
 
 /** Space this box consumes outside its content: margin, border, padding. */
 function frameOf(box: LayoutBox): { margin: Edges; inset: Edges } {
+  const seen = box.frame;
+  if (seen !== undefined) return seen;
   const margin = resolveEdges(box.style.margin);
   const padding = resolveEdges(box.style.padding);
   const b = box.borderEdges;
-  return {
+  const frame = {
     margin,
     inset: {
       top: b.top + padding.top,
@@ -193,6 +212,8 @@ function frameOf(box: LayoutBox): { margin: Edges; inset: Edges } {
       left: b.left + padding.left,
     },
   };
+  box.frame = frame;
+  return frame;
 }
 
 /**
@@ -247,7 +268,7 @@ export function measureBox(box: LayoutBox, availW: number, availH: number): Size
       if (isAbsolute(child) || isHidden(child)) continue;
       count++;
       const m = measureBox(child, innerAvailW, innerAvailH);
-      const cm = resolveEdges(child.style.margin);
+      const cm = frameOf(child).margin;
       mains.push(column ? m.height + edgeV(cm) : m.width + edgeH(cm));
       crosses.push(column ? m.width + edgeH(cm) : m.height + edgeV(cm));
     }
@@ -289,7 +310,7 @@ export function measureBox(box: LayoutBox, availW: number, availH: number): Size
           if (isAbsolute(child) || isHidden(child)) continue;
           const flex = Math.max(0, child.style.flex ?? 0);
           if (flex > 0) {
-            const cm = resolveEdges(child.style.margin);
+            const cm = frameOf(child).margin;
             const share = Math.max(0, Math.floor((room * flex) / totalFlex) - edgeH(cm));
             const m = measureBox(child, share, innerAvailH);
             crosses[index] = m.height + edgeV(cm);
@@ -519,7 +540,7 @@ function layoutWrapped(box: LayoutBox, flow: LayoutBox[]): void {
   const mains: number[] = [];
   const crosses: number[] = [];
   for (const child of flow) {
-    const margin = resolveEdges(child.style.margin);
+    const margin = frameOf(child).margin;
     const basis = child.style.basis ?? (column ? child.style.height : child.style.width);
     const fixed = resolveDimension(basis, mainAvail);
     const m = measureBox(
@@ -580,7 +601,7 @@ function layoutLine(
   const gapTotal = flow.length > 1 ? gap * (flow.length - 1) : 0;
 
   // 1. base sizes
-  const margins = flow.map((c) => resolveEdges(c.style.margin));
+  const margins = flow.map((c) => frameOf(c).margin);
   const bases: number[] = [];
   for (let i = 0; i < flow.length; i++) {
     const child = flow[i] as LayoutBox;

package/src/runtime/paint.ts

@@ -1,5 +1,5 @@
 import type { Rect } from '../types/geometry.js';
-import type { Style } from '../types/style.js';
+import type { Style, StyleColor, TextWrap } from '../types/style.js';
 import type { ResolvedTheme } from '../types/theme.js';
 import type { TerminalCapabilities } from '../types/capabilities.js';
 import type { Cell, Color } from '../types/cells.js';
@@ -12,7 +12,7 @@ import type { Buffer } from '../render/buffer.js';
 import { COLOR_DEFAULT, mix, packColor, type PackedColor } from '../render/color.js';
 import { rectIntersect } from '../types/geometry.js';
 import {
-  graphemes, graphemeWidth, sanitize, stringWidth, truncate,
+  graphemes, graphemeWidth, isAscii, sanitize, stringWidth, truncate,
   truncateSideOf, wrapModeOf, wrapText,
 } from '../util/text.js';
 import {
@@ -87,8 +87,23 @@ class Surface implements PaintSurface {
     const link = style?.link;
     const oy = this.rect.y + y;
 
+    const clean = sanitize(text);
+
+    // Plain ASCII is one cell per character and needs none of the clustering
+    // machinery - and it is nearly every string a terminal ever draws. The
+    // general path allocates an array of one-character strings for the whole
+    // run before writing any of it.
     let cx = x;
-    for (const g of graphemes(sanitize(text))) {
+    if (isAscii(clean)) {
+      for (let i = 0; i < clean.length; i++) {
+        const ax = this.rect.x + cx;
+        if (this.visible(ax, oy)) this.buffer.put(ax, oy, clean[i] as string, fg, bg, attrs, link);
+        cx += 1;
+      }
+      return cx - x;
+    }
+
+    for (const g of graphemes(clean)) {
       const w = graphemeWidth(g);
       if (w === 0) continue;
       const ax = this.rect.x + cx;
@@ -337,6 +352,17 @@ function oneLine(text: string): string {
   return text.includes('\n') ? text.split('\n').join(' ') : text;
 }
 
+/**
+ * Text measurements already taken.
+ *
+ * A measurement is a pure function of the string, how it wraps and the width
+ * it is offered - and a layout asks for the same three several times in a
+ * frame, then the next frame asks for all of them again. The text in a
+ * transcript does not change; only the one line somebody is typing does.
+ */
+const measurements = new Map<string, { width: number; height: number }>();
+const MEASURE_CACHE = 4096;
+
 function textMeasure(instance: Instance, style: Style): (w: number, h: number) => { width: number; height: number } {
   return (maxWidth: number) => {
     const text = sanitize(textContent(instance));
@@ -344,26 +370,41 @@ function textMeasure(instance: Instance, style: Style): (w: number, h: number) =
 
     const wrap = style.wrap ?? 'none';
 
+    const key = `${wrap}\u0000${String(maxWidth)}\u0000${text}`;
+    const seen = measurements.get(key);
+    if (seen !== undefined) return seen;
+
     // A truncating text is one row, always. It still asks for the width it
     // would like - a box sizing itself around it gets the whole string when
     // there is room, and only cuts when there is not.
-    if (truncateSideOf(wrap) !== undefined) {
-      return { width: stringWidth(oneLine(text)), height: 1 };
-    }
+    const size = measure(text, wrap, maxWidth);
+    if (measurements.size >= MEASURE_CACHE) measurements.clear();
+    measurements.set(key, size);
+    return size;
+  };
+}
 
-    if (wrap === 'none') {
-      const lines = text.split('\n');
-      return {
-        width: Math.max(...lines.map(stringWidth)),
-        height: lines.length,
-      };
-    }
-    const limit = Number.isFinite(maxWidth) && maxWidth > 0 ? maxWidth : stringWidth(text);
-    const lines = wrapText(text, limit, wrapModeOf(wrap));
+/** The measurement itself, with nothing remembered. */
+function measure(text: string, wrap: TextWrap, maxWidth: number): { width: number; height: number } {
+  // A truncating text is one row, always. It still asks for the width it
+  // would like - a box sizing itself around it gets the whole string when
+  // there is room, and only cuts when there is not.
+  if (truncateSideOf(wrap) !== undefined) {
+    return { width: stringWidth(oneLine(text)), height: 1 };
+  }
+
+  if (wrap === 'none') {
+    const lines = text.split('\n');
     return {
-      width: Math.min(limit, Math.max(0, ...lines.map(stringWidth))),
-      height: Math.max(1, lines.length),
+      width: Math.max(...lines.map(stringWidth)),
+      height: lines.length,
     };
+  }
+  const limit = Number.isFinite(maxWidth) && maxWidth > 0 ? maxWidth : stringWidth(text);
+  const lines = wrapText(text, limit, wrapModeOf(wrap));
+  return {
+    width: Math.min(limit, Math.max(0, ...lines.map(stringWidth))),
+    height: Math.max(1, lines.length),
   };
 }
 
@@ -672,6 +713,23 @@ function paintText(
     link: typeof instance.props.link === 'string' ? instance.props.link : undefined,
   };
 
+  /*
+   * Text to pick out of this one, and how to draw it where it appears.
+   *
+   * Search highlighting is a paint-time concern and not a content one: the
+   * caller passes the same string it is searching for and the wrapped rows
+   * are coloured where they hold it, so nothing about how the text is broken
+   * into lines has to change to mark a hit in it.
+   */
+  const match = typeof instance.props.match === 'string'
+    ? instance.props.match.toLowerCase()
+    : '';
+  const matchStyle: CellStyle = {
+    ...style,
+    fg: colorOf(packStyleColor((instance.props.matchFg as StyleColor | undefined) ?? 'onAccent', env.theme)),
+    bg: colorOf(packStyleColor((instance.props.matchBg as StyleColor | undefined) ?? 'accent', env.theme)),
+  };
+
   const wrap = visual.style.wrap ?? 'none';
   const align = visual.style.textAlign ?? 'left';
   // The ellipsis is a glyph like any other: on an ascii terminal it is '...'.
@@ -703,8 +761,42 @@ function paintText(
       align === 'center' ? Math.max(0, Math.floor((area.width - w) / 2))
         : align === 'right' ? Math.max(0, area.width - w)
           : 0;
-    surface.text(area.x + offset, area.y + i, line, style);
+    if (match === '') {
+      surface.text(area.x + offset, area.y + i, line, style);
+      continue;
+    }
+    for (const run of split(line, match)) {
+      surface.text(
+        area.x + offset + stringWidth(line.slice(0, run.at)),
+        area.y + i,
+        run.text,
+        run.hit ? matchStyle : style,
+      );
+    }
+  }
+}
+
+/**
+ * A line cut into the parts that match a needle and the parts that do not.
+ *
+ * Case-insensitive, and over the line as it will be drawn - so a match broken
+ * across a wrap is two lines with no match in either, which is the honest
+ * answer: there is nothing on one row to put a colour on.
+ */
+function split(line: string, needle: string): { at: number; text: string; hit: boolean }[] {
+  const runs: { at: number; text: string; hit: boolean }[] = [];
+  const haystack = line.toLowerCase();
+  let from = 0;
+  for (;;) {
+    const at = haystack.indexOf(needle, from);
+    if (at === -1) break;
+    if (at > from) runs.push({ at: from, text: line.slice(from, at), hit: false });
+    runs.push({ at, text: line.slice(at, at + needle.length), hit: true });
+    from = at + needle.length;
   }
+  if (runs.length === 0) return [{ at: 0, text: line, hit: false }];
+  if (from < line.length) runs.push({ at: from, text: line.slice(from), hit: false });
+  return runs;
 }
 
 /**

package/src/types/app.ts

@@ -67,6 +67,17 @@ export interface TextUIApp extends Disposable {
   start(): Promise<void>;
   /** Release exactly what was acquired, then stop. */
   stop(): Promise<void>;
+  /**
+   * Hand the terminal to something that draws for itself, and take it back.
+   *
+   * For an editor, a pager, a shell. The session is released so the child
+   * inherits a terminal in the state it expects - no alt screen, no raw mode -
+   * and is acquired again afterwards exactly as it was, with the frame
+   * repainted whole rather than diffed against what another program left.
+   *
+   * `run` rejecting still gives the terminal back.
+   */
+  suspend<T>(run: () => Promise<T>): Promise<T>;
   /** Force a frame now, outside the scheduler. Tests and screenshots use it. */
   flush(): void;
   /**