@valyrianjs/terminal 0.2.1 → 0.2.2

package/llms-full.txt

@@ -666,7 +666,7 @@ console.log(session.output());
 session.destroy();
 ```
 
-For large lists, add `virtualized` and place the list in a bounded region such as a filled pane or split. The virtualized workbench shows the normal uncontrolled API with `itemKey`, the `children` callback, event observation, and internal active, selected, and viewport state: [`examples/docs/virtualized-list-workbench.tsx`](../examples/docs/virtualized-list-workbench.tsx). Run it with `bun examples/docs/virtualized-list-workbench.tsx`, move active rows with `J/K` or `Up`/`Down`, jump with `PageUp`, `PageDown`, `Home`, or `End`, select with `Enter`, and quit with `Ctrl+C`.
+For large lists, add `virtualized` and place the list in a bounded region such as a filled pane or split. The virtualized workbench demonstrates the uncontrolled List API with `itemKey`, the `children` callback, event payloads, active row, selected row, and viewport values: [`examples/docs/virtualized-list-workbench.tsx`](../examples/docs/virtualized-list-workbench.tsx). Shift+Up and Shift+Down are available for custom app actions. The List does not reorder items by default. Run it with `bun examples/docs/virtualized-list-workbench.tsx`, move active rows with `J/K` or `Up`/`Down`, jump with `PageUp`, `PageDown`, `Home`, or `End`, select with `Enter`, and quit with `Ctrl+C`.
 
 ## Local state to Valyrian state module bridge
 
@@ -1144,12 +1144,12 @@ Use `Editor` for notes, descriptions, and longer messages.
 
 **What it is:** A multi-line editable field.
 **Use it for:** notes, descriptions, and longer messages.
-**Core props:** `id`, `value`, `placeholder`, `height`, `onchange`, `oninput`, `onsubmit`, `oncancel`.
+**Core props:** `id`, `value`, `placeholder`, `width`, `height`, `fill`, `onchange`, `oninput`, `onsubmit`, `oncancel`.
 
 **Minimal example:**
 
 ```tsx
-<Editor id="details" height={4} value={details} onchange={(event) => { details = event.value; }} />
+<Editor id="details" fill height={4} value={details} onchange={(event) => { details = event.value; }} />
 ```
 
 **Complete demo:** [`examples/docs/primitive-input-workbench.tsx`](../examples/docs/primitive-input-workbench.tsx). Run it with `bun examples/docs/primitive-input-workbench.tsx` and quit with `Ctrl+C`.
@@ -1196,7 +1196,7 @@ Use `List` for menus, choosers, command lists, and item browsers.
 
 **What it is:** A focusable collection control with selection and press events.
 **Use it for:** menus, choosers, command lists, and item browsers.
-**Core props:** `id`, `items`, `children` callback, `renderItem`, `itemKey`, `virtualized`, `showActive`, `onchange`, `onviewportchange`, `onpress`, `ondoublepress`, `oncontextpress`. `List` owns its active row, selected row, and viewport state internally; observe those values from event payloads.
+**Core props:** `id`, `items`, `children` callback, `renderItem`, `itemKey`, `virtualized`, `showActive`, `onchange`, `onviewportchange`, `onpress`, `ondoublepress`, `oncontextpress`. `List` manages its active row, selected row, and viewport state. Read those values from event payloads.
 
 **Minimal example:**
 
@@ -1208,7 +1208,7 @@ Use `List` for menus, choosers, command lists, and item browsers.
 
 **Complete demo:** [`examples/docs/primitive-data-explorer.tsx`](../examples/docs/primitive-data-explorer.tsx). Run it with `bun examples/docs/primitive-data-explorer.tsx` and quit with `Ctrl+C`.
 
-**Virtualized demo:** [`examples/docs/virtualized-list-workbench.tsx`](../examples/docs/virtualized-list-workbench.tsx). Run it with `bun examples/docs/virtualized-list-workbench.tsx`, move active rows with `J/K` or `Up`/`Down`, jump with `PageUp`, `PageDown`, `Home`, or `End`, select with `Enter`, and quit with `Ctrl+C`.
+**Virtualized demo:** [`examples/docs/virtualized-list-workbench.tsx`](../examples/docs/virtualized-list-workbench.tsx). Run it with `bun examples/docs/virtualized-list-workbench.tsx`, move active rows with `J/K` or `Up`/`Down`, jump with `PageUp`, `PageDown`, `Home`, or `End`, select with `Enter`, and quit with `Ctrl+C`. `Shift+Up` and `Shift+Down` are shown as app-defined commands, not built-in reorder behavior.
 
 ### `Table`
 
@@ -1359,7 +1359,7 @@ This guide explains how interactive primitives receive input and report events.
 
 ## Input events
 
-Keyboard dispatch uses normalized key names such as `ENTER`, `TAB`, `SHIFT_TAB`, `LEFT`, `RIGHT`, `CTRL_V`, and single-character strings. When a session is connected to `stdin`, terminal input is parsed and routed to the focused primitive.
+Keyboard dispatch uses normalized key names such as `ENTER`, `TAB`, `SHIFT_TAB`, `LEFT`, `RIGHT`, `SHIFT_UP`, `SHIFT_DOWN`, `CTRL_V`, and single-character strings. When a session is connected to `stdin`, terminal input is parsed and routed to the focused primitive.
 
 Pasted text is treated as text input for the focused primitive. Do not treat pasted strings or key sequences as terminal control instructions inside rendered content.
 
@@ -1399,7 +1399,7 @@ Main handlers:
 
 ### `Editor`
 
-`Editor` is a multiline editing primitive.
+`Editor` is a multiline editing primitive. Use `height` for a bounded multiline viewport, `width` for a fixed frame width, and `fill` when the editor should behave like a textarea surface that consumes available width and height. Explicit dimensions win over `fill`; without those props, existing content-sized rendering stays intact.
 
 Supported behavior includes:
 
@@ -1440,13 +1440,13 @@ A quick second primary mouse press keeps the normal activation behavior and also
 
 ### `List`
 
-`List` models active row movement, optional visible selection, viewport scroll, and activation. In virtualized mode the component receives the full `items` array and owns the viewport; wheel input moves the viewport, while keyboard list commands move the active row and emit `change`. A JSX `children` callback receives `(item, ctx)` with `ctx.active`, `ctx.selected`, `ctx.index`, `ctx.key`, and `ctx.viewportIndex`; it takes precedence over `renderItem`. Use `itemKey` when rows have stable identities across reorder or filtering.
+`List` models active row movement, optional visible selection, viewport scroll, and activation. In virtualized mode, pass the full `items` array; the list shows the visible viewport, wheel input scrolls it, and keyboard list commands move the active row and emit `change`. A JSX `children` callback receives `(item, ctx)` with `ctx.active`, `ctx.selected`, `ctx.index`, `ctx.key`, and `ctx.viewportIndex`; it takes precedence over `renderItem`. Use `itemKey` when rows have stable identities across reorder or filtering.
 
 Supported behavior includes:
 
 - `UP` and `DOWN` move the active row and emit `onchange`
 - `PageUp`, `PageDown`, `Home`, and `End` jump the active row and keep it visible
-- `LEFT` and `RIGHT` have no default list command, so applications can bind them
+- `LEFT`, `RIGHT`, `SHIFT_UP`, and `SHIFT_DOWN` have no default list command, so applications can bind them
 - `ENTER` selects and activates the active row
 - mouse click selects and activates the target row
 - mouse hover reports row details when mouse input is connected
@@ -1465,7 +1465,7 @@ Main handlers:
 - `oncapturestart`
 - `oncaptureend`
 
-`pointerCapture` lets a list keep drag interaction even when the pointer leaves the initial hitbox.
+`pointerCapture` lets a list keep drag interaction even when the pointer leaves the initial hitbox. If your app needs reordering, priority changes, or other modified-arrow behavior, bind `SHIFT_UP` or `SHIFT_DOWN` through `keymap.bindings` and handle the custom command in `keymap.onCommand`. The list will not mutate item order by default.
 
 ### `ScrollView`
 
@@ -5044,7 +5044,7 @@ Use `style`, `styles`, and `state` for normal component styling:
 - `styles` maps visual states to dot path recipes or inline style objects.
 - `state` declares app-owned states such as `loading`, `warning`, `success`, `muted`, `expanded`, or `dropTarget`.
 
-Renderer-owned states come from the runtime when the renderer has the fact itself. Focus, hover, selection, current rows, and pointer capture fall in this group when the primitive supports them. App-owned state should describe product state that the app already knows. Do not mark a ready button as `loading` or an editable field as `readonly`; that teaches a lie to the UI and then the UI repeats it with confidence.
+Renderer-owned states come from the runtime when the renderer has the fact itself. Focus, hover, selection, current rows, and pointer capture fall in this group when the primitive supports them. App-owned state should describe product state that the app already knows. Do not use app-owned states for conditions that are not true. For example, do not mark a ready button as `loading` or an editable field as `readonly`.
 
 Precedence: the renderer starts with the automatic `<element>.base` recipe when the primitive has one, applies the instance `style`, then applies `styles` entries for current states in stable visual-state order. Geometry fields such as supported padding and border come from the automatic base recipe plus the instance `style` so layout, hitboxes, and cursors stay stable across focus, hover, and pressed state changes. State styles affect the rendered spans after layout; later current states override earlier visual fields when they set the same property. Inline style objects and dot path recipes use the same merge path after resolution.
 
@@ -5053,6 +5053,7 @@ Renderer notes:
 - Raw ANSI escape control is not the normal public styling API. Use semantic styles and let `ansiOutput()` serialize frames.
 - Layout margin is not supported; use padding, `gap`, `Fixed`, `Split`, or explicit text spacing.
 - The renderer owns terminal frame spans, clipping, focus, and selection; the app owns business state and labels.
+- When a styled public primitive resolves a final frame, its background spans cover that final frame, including cells introduced by layout composition, clipping, or fill. Child backgrounds cover their cells and parent backgrounds resume after child spans close in ANSI output.
 
 Run `bun examples/docs/style-system.tsx`, try `Tab`, `Enter`, and `W`, and quit with `Ctrl+C`; or open [`examples/docs/style-system.tsx`](../examples/docs/style-system.tsx). Run `bun examples/docs/theme-colors.tsx`, press `Tab`, and quit with `Ctrl+C`; or open [`examples/docs/theme-colors.tsx`](../examples/docs/theme-colors.tsx).
 
@@ -5233,7 +5234,9 @@ Props:
 - `focusable?: boolean`
 - `value?: string`
 - `placeholder?: string`
+- `width?: number`
 - `height?: number`
+- `fill?: boolean`
 - shared visual props: `style`, `styles`, `state`
 - `onchange?(event)`
 - `oninput?(event)`
@@ -5246,7 +5249,7 @@ Payloads:
 - `TerminalEditorSubmitEventPayload` - `{ type: "submit", id, value }`
 - `TerminalEditorCancelEventPayload` - `{ type: "cancel", id, value }`
 
-Supports multiline editing, submit, cancel, cursor movement, paste, and deletion. Cursor columns use JavaScript string columns rather than a complete terminal-width model.
+Supports multiline editing, submit, cancel, cursor movement, paste, and deletion. Without `fill`, `width`, or `height`, `Editor` keeps content-sized rendering. `height` constrains the multiline viewport, `width` fixes the final frame width, and `fill` uses the available render context for both axes. Explicit `width` and `height` win over `fill`; for example, `fill` plus `height` fills only the width. Use `Editor` for textarea-like surfaces; `Input` remains the single-line primitive. Cursor columns use JavaScript string columns rather than a complete terminal-width model.
 
 ### `Button`
 
@@ -5303,7 +5306,7 @@ Payloads:
 - `TerminalListPointerEventPayload<T>` - `{ type: "hover" | "rowenter" | "rowleave", id, row, index, key?, value, x, y }`
 - `TerminalCaptureEventPayload` - `{ type: "capturestart" | "captureend", id, source, row, x, y }`
 
-Supports internal active row movement, internal selection, activation, double press on the same row, context press for the target row, hover payloads, optional wrapping, optional virtualization, viewport scroll, and pointer capture. `Up`/`Down`, `PageUp`, `PageDown`, `Home`, and `End` are built-in list navigation keys; `Left` and `Right` stay available for application bindings. Keyboard navigation moves the active row and emits `change`; `Enter` selects and activates the active row. Pointer click selects and activates the clicked row. A quick second primary click on the same row emits `doublepress` without a second `press`. The default renderer displays the active row as `list.current`; when the selected row differs from the active row, it displays the selected row as `list.selected`. A JSX `children` callback is the recommended item renderer and wins over `renderItem` when both are present. `children` receives `ctx.active` and `ctx.selected` separately. `renderItem` remains as a compatibility alias with the legacy `(item, index)` signature. `wrap` wraps long default-rendered item text to the list width. Virtualized lists receive the full `items` array and calculate the visible viewport internally; use `itemKey` for stable event identity when items can reorder. Observe the resulting active row, selected row, and viewport through the list event payloads. Run [`examples/docs/virtualized-list-workbench.tsx`](../examples/docs/virtualized-list-workbench.tsx) with `bun examples/docs/virtualized-list-workbench.tsx` to inspect those values from events in one bounded split layout.
+Supports active row movement, selection, activation, double press on the same row, context press for the target row, hover payloads, optional wrapping, optional virtualization, viewport scroll, and pointer capture. `Up`/`Down`, `PageUp`, `PageDown`, `Home`, and `End` are built-in list navigation keys; `Left`, `Right`, `Shift+Up`, and `Shift+Down` stay available for application bindings. The library never reorders or mutates list items from modified arrow keys by default; priority changes and reordering belong in app-defined commands. Keyboard navigation moves the active row and emits `change`; `Enter` selects and activates the active row. Pointer click selects and activates the clicked row. A quick second primary click on the same row emits `doublepress` without a second `press`. The default renderer displays the active row as `list.current`; when the selected row differs from the active row, it displays the selected row as `list.selected`. A JSX `children` callback is the recommended item renderer and wins over `renderItem` when both are present. `children` receives `ctx.active` and `ctx.selected` separately. `renderItem` remains as a compatibility alias with the legacy `(item, index)` signature. `wrap` wraps long default-rendered item text to the list width. Virtualized lists receive the full `items` array and render the visible viewport; use `itemKey` for stable event identity when items can reorder. Observe the resulting active row, selected row, and viewport through the list event payloads. Run [`examples/docs/virtualized-list-workbench.tsx`](../examples/docs/virtualized-list-workbench.tsx) with `bun examples/docs/virtualized-list-workbench.tsx` to inspect those values from events in one bounded split layout.
 
 ### `ScrollView`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valyrianjs/terminal",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Terminal adapter for valyrian.js",
   "license": "Apache-2.0",
   "private": false,
@@ -23,6 +23,7 @@
   "files": [
     "dist",
     "docs",
+    "examples",
     "src",
     "!docs/local-demo.md",
     "!docs/plans",
@@ -32,7 +33,7 @@
     "llms-full.txt"
   ],
   "scripts": {
-    "test": "bun test --max-concurrency=1",
+    "test": "bun run build && bun test --max-concurrency=1",
     "demo:dogfood": "bun examples/opencode-dogfood.tsx",
     "llms:full": "bun scripts/generate-llms-full.ts",
     "replay:ansi": "bun scripts/replay-ansi.ts",

package/src/ansi.ts

@@ -1,3 +1,4 @@
+import { terminalCellWidth, terminalGraphemes } from "./text.js";
 import { resolveTerminalStyle, resolveTerminalStyleToken } from "./theme.js";
 import type { CursorPosition, TerminalFrame, TerminalStyleSpan, TerminalTheme } from "./types.js";
 
@@ -100,19 +101,18 @@ function renderAnsiLine(line: string, spans: TerminalStyleSpan[], y: number, the
   const rowSpans = lineSpans(spans, y);
   let activeSpanIndex = 0;
 
-  for (let i = 0; i < line.length; i += 1) {
+  for (const grapheme of terminalGraphemes(line)) {
     while (rowSpans[activeSpanIndex]?.x1 === visibleColumn) {
       output += spanAnsiOpen(rowSpans[activeSpanIndex], theme);
       activeSpanIndex += 1;
     }
 
-    const char = line[i];
-    if (char === "|") {
+    if (grapheme === "|") {
       continue;
     }
 
-    output += char;
-    visibleColumn += 1;
+    output += grapheme;
+    visibleColumn += terminalCellWidth(grapheme);
 
     let closedSpan = false;
     for (const span of rowSpans) {
@@ -129,7 +129,7 @@ function renderAnsiLine(line: string, spans: TerminalStyleSpan[], y: number, the
         closedSpan = true;
       }
     }
-    if (closedSpan && visibleColumn <= line.length && line[visibleColumn - 1] === " ") {
+    if (closedSpan && visibleColumn <= terminalCellWidth(line)) {
       for (const span of rowSpans) {
         if (span.x1 < visibleColumn && span.x2 > visibleColumn) {
           output += spanAnsiOpen(span, theme);
@@ -174,22 +174,20 @@ function formatPlainLine(line: string, spans: TerminalStyleSpan[], y: number, th
       && !token?.plainSuffix
       && span.x1 === 1
       && y === firstFallbackFocusY
-      && span.x2 <= line.length + 1
       && !line.trimStart().startsWith(">")
       && !line.includes("|")
       && !line.includes("[>");
     return {
       ...span,
-      x2: fallbackFocusMarker ? Math.min(span.x2, line.trimEnd().length + 1) : span.x2,
+      x2: fallbackFocusMarker ? Math.min(span.x2, terminalCellWidth(line.trimEnd()) + 1) : span.x2,
       plainPrefix: token?.plainPrefix ?? span.style?.plainPrefix ?? (fallbackFocusMarker ? ">" : ""),
       plainSuffix: token?.plainSuffix ?? span.style?.plainSuffix ?? (fallbackFocusMarker ? "<" : "")
     };
   }).filter((span) => Boolean(span.plainPrefix || span.plainSuffix));
 
-  for (let i = 0; i < line.length; i += 1) {
-    const char = line[i];
-    if (char === "|") {
-      output += char;
+  for (const grapheme of terminalGraphemes(line)) {
+    if (grapheme === "|") {
+      output += grapheme;
       continue;
     }
 
@@ -199,8 +197,8 @@ function formatPlainLine(line: string, spans: TerminalStyleSpan[], y: number, th
       }
     }
 
-    output += char;
-    visibleColumn += 1;
+    output += grapheme;
+    visibleColumn += terminalCellWidth(grapheme);
 
     for (const span of rowSpans) {
       if (span.x2 === visibleColumn) {

package/src/events.ts

@@ -146,6 +146,8 @@ export function parseTerminalKey(chunk: string | Uint8Array) {
   if (value === "\u001b[B") return "DOWN";
   if (value === "\u001b[C") return "RIGHT";
   if (value === "\u001b[D") return "LEFT";
+  if (value === "\u001b[1;2A") return "SHIFT_UP";
+  if (value === "\u001b[1;2B") return "SHIFT_DOWN";
   if (value === "\u001b[1;2C") return "SHIFT_RIGHT";
   if (value === "\u001b[1;2D") return "SHIFT_LEFT";
   if (value === "\u001b[1;3C" || value === "\u001bf") return "ALT_RIGHT";

package/src/frame-style.ts

@@ -0,0 +1,36 @@
+import type { TerminalStyleSpan } from "./types.js";
+
+const FULL_FRAME_SPAN = Symbol("valyrian.terminal.fullFrameSpan");
+const FULL_ROW_SPAN = Symbol("valyrian.terminal.fullRowSpan");
+
+type InternalFullFrameSpan = TerminalStyleSpan & { [FULL_FRAME_SPAN]?: true };
+type InternalFullRowSpan = TerminalStyleSpan & { [FULL_ROW_SPAN]?: true };
+
+export function markFullFrameSpan(span: TerminalStyleSpan): TerminalStyleSpan {
+  Object.defineProperty(span, FULL_FRAME_SPAN, { value: true, enumerable: false, configurable: true });
+  return span;
+}
+
+export function isFullFrameSpan(span: TerminalStyleSpan) {
+  return (span as InternalFullFrameSpan)[FULL_FRAME_SPAN] === true;
+}
+
+export function markFullRowSpan(span: TerminalStyleSpan): TerminalStyleSpan {
+  Object.defineProperty(span, FULL_ROW_SPAN, { value: true, enumerable: false, configurable: true });
+  return span;
+}
+
+export function isFullRowSpan(span: TerminalStyleSpan) {
+  return (span as InternalFullRowSpan)[FULL_ROW_SPAN] === true;
+}
+
+export function cloneStyleSpan(span: TerminalStyleSpan, patch: Partial<TerminalStyleSpan>): TerminalStyleSpan {
+  const next = { ...span, ...patch };
+  if (isFullFrameSpan(span)) {
+    markFullFrameSpan(next);
+  }
+  if (isFullRowSpan(span)) {
+    markFullRowSpan(next);
+  }
+  return next;
+}

package/src/layout.ts

@@ -1,3 +1,5 @@
+import { cloneStyleSpan, isFullFrameSpan, isFullRowSpan } from "./frame-style.js";
+import { dropTerminalCells, padEndTerminalCells, sliceTerminalCells, terminalCellWidth } from "./text.js";
 import type { CursorPosition, TerminalFrame, TerminalHitbox, TerminalStyleSpan } from "./types.js";
 
 function repeat(char: string, count: number) {
@@ -9,7 +11,7 @@ export function createFrame(lines: string[], hitboxes: TerminalHitbox[] = [], cu
 }
 
 export function getFrameWidth(frame: TerminalFrame) {
-  return frame.lines.reduce((max, line) => Math.max(max, line.length), 0);
+  return frame.lines.reduce((max, line) => Math.max(max, terminalCellWidth(line)), 0);
 }
 
 export function getFrameHeight(frame: TerminalFrame) {
@@ -29,12 +31,12 @@ export function shiftFrame(frame: TerminalFrame, dx: number, dy: number): Termin
       contentY: typeof box.contentY === "number" ? box.contentY + dy : undefined
     })),
     cursor: frame.cursor ? { x: frame.cursor.x + dx, y: frame.cursor.y + dy } : null,
-    spans: frame.spans.map((span) => ({ ...span, x1: span.x1 + dx, x2: span.x2 + dx, y: span.y + dy }))
+    spans: frame.spans.map((span) => cloneStyleSpan(span, { x1: span.x1 + dx, x2: span.x2 + dx, y: span.y + dy }))
   };
 }
 
 function normalizeLines(frame: TerminalFrame, width: number, height: number) {
-  const lines = frame.lines.map((line) => line.padEnd(width, " "));
+  const lines = frame.lines.map((line) => padEndTerminalCells(line, width));
   while (lines.length < height) {
     lines.push(repeat(" ", width));
   }
@@ -57,15 +59,15 @@ export function mergeVertical(frames: TerminalFrame[], options: { gap?: number }
 
   for (let i = 0; i < filtered.length; i += 1) {
     const frame = filtered[i];
-    const normalized = normalizeLines(frame, width, getFrameHeight(frame));
-    lines.push(...normalized);
-    const shifted = shiftFrame(frame, 0, rowOffset);
+    const normalizedFrame = fitFrame(frame, width, getFrameHeight(frame), { expandFullFrameSpans: true });
+    lines.push(...normalizedFrame.lines);
+    const shifted = shiftFrame(normalizedFrame, 0, rowOffset);
     hitboxes.push(...shifted.hitboxes);
     spans.push(...shifted.spans);
     if (!cursor && frame.cursor) {
       cursor = { x: frame.cursor.x, y: frame.cursor.y + rowOffset };
     }
-    rowOffset += normalized.length;
+    rowOffset += normalizedFrame.lines.length;
     if (i < filtered.length - 1 && gap > 0) {
       for (let j = 0; j < gap; j += 1) {
         lines.push(repeat(" ", width));
@@ -87,9 +89,8 @@ export function mergeHorizontal(frames: TerminalFrame[], options: { gap?: number
   const widths = filtered.map(getFrameWidth);
   const height = filtered.reduce((max, frame) => Math.max(max, getFrameHeight(frame)), 0);
   const normalizedFrames = filtered.map((frame, index) => ({
-    frame,
-    width: widths[index],
-    lines: normalizeLines(frame, widths[index], height)
+    frame: fitFrame(frame, widths[index], height, { expandFullFrameSpans: true }),
+    width: widths[index]
   }));
   const gapText = repeat(" ", gap);
   const lines = new Array<string>(height).fill("");
@@ -101,7 +102,7 @@ export function mergeHorizontal(frames: TerminalFrame[], options: { gap?: number
   for (let index = 0; index < normalizedFrames.length; index += 1) {
     const part = normalizedFrames[index];
     for (let row = 0; row < height; row += 1) {
-      lines[row] += part.lines[row];
+      lines[row] += part.frame.lines[row];
       if (index < normalizedFrames.length - 1) {
         lines[row] += gapText;
       }
@@ -125,20 +126,20 @@ export function padFrame(frame: TerminalFrame, padding: number) {
   }
 
   const width = getFrameWidth(frame);
-  const middle = frame.lines.map((line) => `${repeat(" ", amount)}${line.padEnd(width, " ")}${repeat(" ", amount)}`);
+  const middle = frame.lines.map((line) => `${repeat(" ", amount)}${padEndTerminalCells(line, width)}${repeat(" ", amount)}`);
   const blank = repeat(" ", width + amount * 2);
   const lines = [...new Array<string>(amount).fill(blank), ...middle, ...new Array<string>(amount).fill(blank)];
   const shifted = shiftFrame(frame, amount, amount);
   return createFrame(lines, shifted.hitboxes, frame.cursor ? { x: frame.cursor.x + amount, y: frame.cursor.y + amount } : null, shifted.spans);
 }
 
-export function fitFrame(frame: TerminalFrame, width?: number, height?: number) {
+export function fitFrame(frame: TerminalFrame, width?: number, height?: number, options: { expandFullFrameSpans?: boolean } = {}) {
   const nextWidth = Math.max(getFrameWidth(frame), Number(width || 0));
   const nextHeight = Math.max(getFrameHeight(frame), Number(height || 0));
   if (nextWidth === getFrameWidth(frame) && nextHeight === getFrameHeight(frame)) {
     return frame;
   }
-  return createFrame(normalizeLines(frame, nextWidth, nextHeight), frame.hitboxes, frame.cursor, frame.spans);
+  return constrainFrame(frame, { width: nextWidth, height: nextHeight, expandFullFrameSpans: options.expandFullFrameSpans });
 }
 
 function constraintSize(value: number | undefined, fallback: number) {
@@ -160,13 +161,13 @@ function clamp(value: number, min: number, max: number) {
   return Math.min(max, Math.max(min, value));
 }
 
-export function constrainFrame(frame: TerminalFrame, options: { width?: number; height?: number } = {}): TerminalFrame {
+export function constrainFrame(frame: TerminalFrame, options: { width?: number; height?: number; expandFullFrameSpans?: boolean; expandFullRowSpans?: boolean } = {}): TerminalFrame {
   const width = constraintSize(options.width, getFrameWidth(frame));
   const height = constraintSize(options.height, getFrameHeight(frame));
   const lines: string[] = [];
 
   for (let row = 0; row < height; row += 1) {
-    lines.push((frame.lines[row] || "").slice(0, width).padEnd(width, " "));
+    lines.push(padEndTerminalCells(sliceTerminalCells(frame.lines[row] || "", width), width));
   }
 
   const hitboxes = frame.hitboxes
@@ -184,8 +185,26 @@ export function constrainFrame(frame: TerminalFrame, options: { width?: number;
     ? { x: frame.cursor.x, y: frame.cursor.y }
     : null;
 
+  const originalWidth = getFrameWidth(frame);
+  const originalHeight = getFrameHeight(frame);
   const spanRightEdge = width + 1;
   const spans = frame.spans.flatMap((span) => {
+    const coversCurrentFrame = options.expandFullFrameSpans === true && isFullFrameSpan(span) && span.x1 === 1 && span.x2 === originalWidth + 1;
+    if (coversCurrentFrame) {
+      if (width <= 0 || span.y < 1 || span.y > Math.min(originalHeight, height)) {
+        return [];
+      }
+      return [cloneStyleSpan(span, { x1: 1, x2: spanRightEdge })];
+    }
+
+    const coversCurrentRow = (options.expandFullFrameSpans === true || options.expandFullRowSpans === true) && isFullRowSpan(span) && span.x1 === 1 && span.x2 === originalWidth + 1;
+    if (coversCurrentRow) {
+      if (width <= 0 || span.y < 1 || span.y > Math.min(originalHeight, height)) {
+        return [];
+      }
+      return [cloneStyleSpan(span, { x1: 1, x2: spanRightEdge })];
+    }
+
     if (width <= 0 || span.y < 1 || span.y > height || span.x2 <= 1 || span.x1 >= spanRightEdge) {
       return [];
     }
@@ -196,9 +215,22 @@ export function constrainFrame(frame: TerminalFrame, options: { width?: number;
       return [];
     }
 
-    return [{ ...span, x1: clippedX1, x2: clippedX2 }];
+    return [cloneStyleSpan(span, { x1: clippedX1, x2: clippedX2 })];
   });
 
+  const fullFrameSpans = options.expandFullFrameSpans === true
+    ? frame.spans.filter((span) => isFullFrameSpan(span) && span.x1 === 1 && span.x2 === originalWidth + 1)
+    : [];
+  const firstFullFrameRow = fullFrameSpans.reduce<number | null>((first, span) => first === null ? span.y : Math.min(first, span.y), null);
+  if (firstFullFrameRow !== null) {
+    const templates = fullFrameSpans.filter((span) => span.y === firstFullFrameRow);
+    for (let y = originalHeight + 1; y <= height; y += 1) {
+      for (const template of templates) {
+        spans.push(cloneStyleSpan(template, { x1: 1, x2: spanRightEdge, y }));
+      }
+    }
+  }
+
   return createFrame(lines, hitboxes, cursor, spans);
 }
 
@@ -234,16 +266,20 @@ export function overlayFrame(base: TerminalFrame, overlay: TerminalFrame, option
 
     const baseLine = lines[baseRow];
     const start = x - 1;
-    if (start >= baseLine.length) {
+    if (start >= terminalCellWidth(baseLine)) {
       continue;
     }
 
-    const visibleWidth = Math.min(constrainedOverlay.lines[row].length, baseLine.length - start);
+    const visibleWidth = Math.min(terminalCellWidth(constrainedOverlay.lines[row]), terminalCellWidth(baseLine) - start);
     if (visibleWidth <= 0) {
       continue;
     }
 
-    lines[baseRow] = `${baseLine.slice(0, start)}${constrainedOverlay.lines[row].slice(0, visibleWidth)}${baseLine.slice(start + visibleWidth)}`;
+    const prefix = sliceTerminalCells(baseLine, start);
+    const suffix = dropTerminalCells(baseLine, start + visibleWidth);
+    const insert = sliceTerminalCells(constrainedOverlay.lines[row], visibleWidth);
+    const removedWidth = terminalCellWidth(baseLine) - terminalCellWidth(prefix) - terminalCellWidth(suffix);
+    lines[baseRow] = `${prefix}${padEndTerminalCells(insert, removedWidth)}${suffix}`;
   }
 
   const shiftedOverlay = shiftFrame(constrainedOverlay, x - 1, y - 1);
@@ -271,10 +307,7 @@ export function cropFrame(frame: TerminalFrame, offset: number, height: number)
     }));
   const spans = frame.spans
     .filter((span) => span.y > start && span.y <= start + size)
-    .map((span) => ({
-      ...span,
-      y: span.y - start
-    }));
+    .map((span) => cloneStyleSpan(span, { y: span.y - start }));
   const cursor = frame.cursor && frame.cursor.y > start && frame.cursor.y <= start + size
     ? { x: frame.cursor.x, y: frame.cursor.y - start }
     : null;

package/src/mouse.ts

@@ -79,6 +79,15 @@ export function cursorFromHitbox(hitbox: TerminalHitbox, x: number) {
   if (typeof hitbox.textStartX !== "number") {
     return 0;
   }
+
   const textLength = Number(hitbox.textLength || 0);
-  return Math.max(0, Math.min(textLength, x - hitbox.textStartX));
+  const cellOffset = Math.max(0, x - hitbox.textStartX);
+  if (Array.isArray(hitbox.textCellToStringIndex) && hitbox.textCellToStringIndex.length > 0) {
+    const index = hitbox.textCellToStringIndex[Math.min(cellOffset, hitbox.textCellToStringIndex.length - 1)];
+    if (typeof index === "number" && Number.isFinite(index)) {
+      return Math.max(0, Math.min(textLength, index));
+    }
+  }
+
+  return Math.max(0, Math.min(textLength, cellOffset));
 }