@valyrianjs/terminal 0.2.0 → 0.2.2

package/src/render.ts

@@ -1,12 +1,13 @@
 import { constrainFrame, createFrame, cropFrame, fitFrame, getFrameHeight, getFrameWidth, mergeHorizontal, mergeVertical, overlayFrame, shiftFrame } from "./layout.js";
 import { getSelectionRange, normalizeInputState } from "./events.js";
+import { markFullFrameSpan, markFullRowSpan } from "./frame-style.js";
 import { createEditorState } from "./editor-state.js";
 import { isFocusable, textContent } from "./tree.js";
 import { renderValyrianTerminal } from "./runtime.js";
-import { plainText } from "./text.js";
+import { cursorCellOffset, padEndTerminalCells, plainText, sliceTerminalCells, terminalCellToStringIndex, terminalCellWidth, terminalGraphemes } from "./text.js";
 import { resolveTerminalStyle } from "./theme.js";
 
-import type { InputInteractionState, TerminalElementNode, TerminalFocusNode, TerminalFrame, TerminalNode, TerminalSpacing, TerminalSplitBreakpoint, TerminalSplitSize, TerminalStyleDefinition, TerminalStyleSpan, TerminalTheme, TerminalVisualState } from "./types.js";
+import type { InputInteractionState, TerminalElementNode, TerminalFocusNode, TerminalFrame, TerminalHitbox, TerminalNode, TerminalSpacing, TerminalSplitBreakpoint, TerminalSplitSize, TerminalStyleDefinition, TerminalStyleSpan, TerminalTheme, TerminalVisualState } from "./types.js";
 
 export interface TerminalRenderContext {
   cols: number;
@@ -173,7 +174,7 @@ function fullFrameSpans(kinds: string[], width: number, height: number): Termina
   const spans: TerminalStyleSpan[] = [];
   for (const kind of kinds) {
     for (let y = 1; y <= height; y += 1) {
-      spans.push({ kind, x1: 1, x2: width + 1, y });
+      spans.push(markFullFrameSpan({ kind, x1: 1, x2: width + 1, y }));
     }
   }
   return spans;
@@ -209,7 +210,7 @@ function padFrameSides(frame: TerminalFrame, padding: SpacingSides) {
   const bottomLines = new Array<string>(padding.bottom).fill(" ".repeat(contentWidth));
   const lines = [
     ...topLines,
-    ...frame.lines.map((line) => `${" ".repeat(padding.left)}${line.padEnd(width, " ")}${" ".repeat(padding.right)}`),
+    ...frame.lines.map((line) => `${" ".repeat(padding.left)}${padEndTerminalCells(line, width)}${" ".repeat(padding.right)}`),
     ...bottomLines
   ];
   return shiftFrame(createFrame(lines, frame.hitboxes, frame.cursor, frame.spans), padding.left, padding.top);
@@ -227,7 +228,7 @@ function addBorder(frame: TerminalFrame, border: BorderSides) {
     lines.push(`${border.left ? chars.topLeft : chars.horizontal}${chars.horizontal.repeat(Math.max(0, width - left - right))}${border.right ? chars.topRight : chars.horizontal}`.slice(0, width));
   }
   for (const line of frame.lines) {
-    lines.push(`${border.left ? chars.vertical : ""}${line.padEnd(innerWidth, " ")}${border.right ? chars.vertical : ""}`);
+    lines.push(`${border.left ? chars.vertical : ""}${padEndTerminalCells(line, innerWidth)}${border.right ? chars.vertical : ""}`);
   }
   if (border.bottom) {
     lines.push(`${border.left ? chars.bottomLeft : chars.horizontal}${chars.horizontal.repeat(Math.max(0, width - left - right))}${border.right ? chars.bottomRight : chars.horizontal}`.slice(0, width));
@@ -252,15 +253,28 @@ function addFullFrameSpans(frame: TerminalFrame, kinds: ResolvedStyleSpan[]) {
   const spans = frame.spans.slice();
   for (const span of kinds) {
     for (let y = 1; y <= height; y += 1) {
-      spans.push({ ...span, x1: 1, x2: width + 1, y });
+      spans.push(markFullFrameSpan({ ...span, x1: 1, x2: width + 1, y }));
     }
   }
   return createFrame(frame.lines, frame.hitboxes, frame.cursor, spans);
 }
 
-function listVirtualRange(node: TerminalElementNode, itemCount: number, selectedIndex: number, context?: TerminalRenderContext) {
+function listViewportRows(node: TerminalElementNode, itemCount: number, context?: TerminalRenderContext) {
+  const explicitHeight = positiveDimension(node.props.height, "height");
+  const viewportSourceRows = explicitHeight ?? context?.rows ?? (itemCount || 1);
+  return Math.max(1, Math.min(itemCount || 1, positiveInteger(viewportSourceRows, "List viewport height")));
+}
+
+function clampListIndex(index: number, itemCount: number) {
+  if (itemCount <= 0) {
+    return 0;
+  }
+  return Math.max(0, Math.min(itemCount - 1, index));
+}
+
+function listVirtualRange(node: TerminalElementNode, itemCount: number, context?: TerminalRenderContext) {
   if (!node.props.virtualized) {
-    return { start: 0, end: itemCount };
+    return { start: 0, end: itemCount, visibleStart: 0, viewportRows: itemCount || 1 };
   }
 
   if (typeof node.props.itemHeight !== "undefined" && node.props.itemHeight !== 1) {
@@ -268,14 +282,102 @@ function listVirtualRange(node: TerminalElementNode, itemCount: number, selected
   }
 
   const overscan = nonNegativeInteger(node.props.overscan, "List overscan");
-  const viewportSourceRows = context?.rows ?? (itemCount || 1);
-  const viewportRows = Math.max(1, Math.min(itemCount || 1, positiveInteger(viewportSourceRows, "List viewport height")));
-  const selected = Math.max(0, Math.min(itemCount - 1, selectedIndex));
-  const visibleStart = Math.max(0, Math.min(selected, selected - viewportRows + 1));
+  const viewportRows = listViewportRows(node, itemCount, context);
+  const maxOffset = Math.max(0, itemCount - viewportRows);
+  let visibleStart = Math.max(0, Math.min(maxOffset, nonNegativeInteger(node.props.__scrollOffset, "List viewport offset")));
   const start = Math.max(0, visibleStart - overscan);
   const end = Math.min(itemCount, visibleStart + viewportRows + overscan);
 
-  return { start, end };
+  return { start, end, visibleStart, viewportRows };
+}
+
+function listItemKey(node: TerminalElementNode, item: unknown, index: number) {
+  if (typeof node.props.itemKey === "function") {
+    const key = node.props.itemKey(item, index);
+    if (typeof key !== "string" && typeof key !== "number") {
+      throw new RangeError("List itemKey must return a string or number");
+    }
+    return String(key);
+  }
+  return String(index);
+}
+
+function listItemRenderer(node: TerminalElementNode) {
+  if (typeof node.props.__childrenRenderer === "function") {
+    return { type: "children" as const, render: node.props.__childrenRenderer };
+  }
+  if (typeof node.props.renderItem === "function") {
+    return { type: "renderItem" as const, render: node.props.renderItem };
+  }
+  return undefined;
+}
+
+function wrapPlainText(value: string, width: number) {
+  if (!Number.isFinite(width) || !Number.isInteger(width) || width <= 0) {
+    return [""];
+  }
+
+  const rows: string[] = [];
+  const sourceRows = value.split("\n");
+  for (const sourceRow of sourceRows) {
+    if (sourceRow.length === 0) {
+      rows.push("");
+      continue;
+    }
+
+    let remaining = sourceRow;
+    while (terminalCellWidth(remaining) > width) {
+      const slice = sliceTerminalCells(remaining, width);
+      if (slice.length === 0) {
+        const [firstGrapheme = ""] = terminalGraphemes(remaining);
+        rows.push(firstGrapheme);
+        remaining = remaining.slice(firstGrapheme.length);
+        continue;
+      }
+
+      const breakAt = slice.lastIndexOf(" ");
+      if (breakAt > 0 && breakAt >= Math.floor(width * 0.6)) {
+        rows.push(remaining.slice(0, breakAt));
+        remaining = remaining.slice(breakAt + 1);
+      } else {
+        rows.push(slice);
+        remaining = remaining.slice(slice.length);
+      }
+    }
+    rows.push(remaining);
+  }
+
+  return rows.length ? rows : [""];
+}
+
+function renderListItemFrame(node: TerminalElementNode, item: unknown, index: number, viewportIndex: number, activeIndex: number, selectedIndex: number | null, wrapWidth: number, context?: TerminalRenderContext) {
+  const key = listItemKey(node, item, index);
+  const renderer = listItemRenderer(node);
+  if (!renderer) {
+    const label = plainText(item);
+    return createFrame(node.props.wrap === true ? wrapPlainText(label, wrapWidth) : label.split("\n"));
+  }
+
+  const ctx = {
+    index,
+    key,
+    active: index === activeIndex,
+    selected: selectedIndex !== null && index === selectedIndex,
+    viewportIndex,
+    item
+  };
+  const rendered = renderer.type === "children" ? renderer.render(item, ctx) : renderer.render(item, index);
+
+  if (typeof rendered === "string" || typeof rendered === "number") {
+    const label = plainText(rendered);
+    return createFrame(node.props.wrap === true ? wrapPlainText(label, wrapWidth) : label.split("\n"));
+  }
+
+  const frame = mergeVertical(renderValyrianTerminal(rendered).map((child) => renderTerminalFrame(child, context)));
+  if (node.props.wrap === true && frame.hitboxes.length === 0) {
+    return createFrame(frame.lines.flatMap((line) => wrapPlainText(line, wrapWidth)));
+  }
+  return frame;
 }
 
 function fixedPosition(value: unknown) {
@@ -371,7 +473,8 @@ function decorateContainerFrame(frame: TerminalFrame, node: TerminalElementNode,
     if ((typeof width === "number" && width > 0) || (typeof height === "number" && height > 0)) {
       next = constrainFrame(next, {
         width: typeof width === "number" && width > 0 ? width : undefined,
-        height: typeof height === "number" && height > 0 ? height : undefined
+        height: typeof height === "number" && height > 0 ? height : undefined,
+        expandFullFrameSpans: true
       });
     }
   }
@@ -380,7 +483,8 @@ function decorateContainerFrame(frame: TerminalFrame, node: TerminalElementNode,
   if (options.constrain) {
     next = constrainFrame(next, {
       width: typeof options.width === "undefined" ? positiveDimension(node.props.width, "width") : options.width,
-      height: typeof options.height === "undefined" ? positiveDimension(node.props.height, "height") : options.height
+      height: typeof options.height === "undefined" ? positiveDimension(node.props.height, "height") : options.height,
+      expandFullFrameSpans: true
     });
   }
   next = addContainerStyleSpans(next, node, resolved);
@@ -444,6 +548,19 @@ function resolveContainerChildContext(node: TerminalElementNode, dimensions: { w
   };
 }
 
+function interactiveTextMetadata(value: string) {
+  const textLength = value.length;
+  const textCellToStringIndex = terminalCellToStringIndex(value);
+  const usesLinearIndexes = textCellToStringIndex.length === textLength + 1
+    && textCellToStringIndex.every((index, cellOffset) => index === cellOffset);
+
+  if (usesLinearIndexes) {
+    return { textLength };
+  }
+
+  return { textLength, textCellToStringIndex };
+}
+
 function renderInputLine(value: string, inputState: InputInteractionState, padding: SpacingSides = { top: 0, right: 0, bottom: 0, left: 0 }) {
   const state = normalizeInputState(inputState, value.length);
   const { start, end } = getSelectionRange(state);
@@ -452,12 +569,29 @@ function renderInputLine(value: string, inputState: InputInteractionState, paddi
   const textStart = padding.left + 1;
   return {
     line: paddedLine,
-    cursor: { x: textStart + state.cursor, y: 1 },
-    spans: start === end ? [] : [{ kind: "input.selection", x1: textStart + start, x2: textStart + end, y: 1 }]
+    cursor: { x: textStart + cursorCellOffset(value, state.cursor), y: 1 },
+    spans: start === end ? [] : [{ kind: "input.selection", x1: textStart + cursorCellOffset(value, start), x2: textStart + cursorCellOffset(value, end), y: 1 }]
+  };
+}
+
+function resolveEditorDimensions(node: TerminalElementNode, context?: TerminalRenderContext) {
+  const explicitWidth = positiveDimension(node.props.width, "width");
+  const explicitHeight = positiveDimension(node.props.height, "height");
+  return {
+    width: typeof explicitWidth !== "undefined"
+      ? explicitWidth
+      : node.props.fill === true
+        ? fillContextDimension(context, "width", "Editor")
+        : undefined,
+    height: typeof explicitHeight !== "undefined"
+      ? explicitHeight
+      : node.props.fill === true
+        ? fillContextDimension(context, "height", "Editor")
+        : undefined
   };
 }
 
-function renderEditorFrame(node: TerminalElementNode) {
+function renderEditorFrame(node: TerminalElementNode, context?: TerminalRenderContext) {
   const value = typeof node.props.value !== "undefined" ? plainText(node.props.value) : "";
   const placeholder = typeof node.props.placeholder !== "undefined" ? plainText(node.props.placeholder) : "";
   const displayValue = value.length === 0 && !node.props.__focused && placeholder ? placeholder : value;
@@ -472,23 +606,28 @@ function renderEditorFrame(node: TerminalElementNode) {
 
     return `> ${line.slice(0, focusedColumn)}|${line.slice(focusedColumn)}`;
   });
-  const width = lines.reduce((max, line) => Math.max(max, line.length), 0);
-  const cursor = node.props.__focused ? { x: 3 + focusedColumn, y: focusedLine + 1 } : null;
-  const spans: TerminalStyleSpan[] = node.props.__focused ? [{ kind: "focus", x1: 1, x2: Math.max(2, lines[focusedLine].length + 1), y: focusedLine + 1 }] : [];
-  const height = typeof node.props.height === "undefined" ? undefined : positiveDimension(node.props.height, "height");
+  const width = lines.reduce((max, line) => Math.max(max, terminalCellWidth(line)), 0);
+  const cursor = node.props.__focused ? { x: 3 + cursorCellOffset(focusedState.lines[focusedLine], focusedColumn), y: focusedLine + 1 } : null;
+  const spans: TerminalStyleSpan[] = node.props.__focused ? [{ kind: "focus", x1: 1, x2: Math.max(2, terminalCellWidth(lines[focusedLine]) + 1), y: focusedLine + 1 }] : [];
+  const dimensions = resolveEditorDimensions(node, context);
   const frame = createFrame(lines, [], cursor, spans);
-  const scrollOffset = node.props.__focused && typeof height !== "undefined"
-    ? Math.min(Math.max(0, focusedLine - height + 1), Math.max(0, lines.length - height))
+  const scrollOffset = node.props.__focused && typeof dimensions.height !== "undefined"
+    ? Math.min(Math.max(0, focusedLine - dimensions.height + 1), Math.max(0, lines.length - dimensions.height))
     : 0;
-  const constrainedFrame = typeof height === "undefined"
+  const croppedFrame = typeof dimensions.height === "undefined"
     ? frame
-    : constrainFrame(scrollOffset > 0 ? cropFrame(frame, scrollOffset, height) : frame, { height });
+    : scrollOffset > 0
+      ? cropFrame(frame, scrollOffset, dimensions.height)
+      : frame;
+  const constrainedFrame = typeof dimensions.width === "undefined" && typeof dimensions.height === "undefined"
+    ? croppedFrame
+    : constrainFrame(croppedFrame, { ...dimensions, expandFullFrameSpans: true });
 
   if (!node.props.id) {
     return constrainedFrame;
   }
 
-  return createFrame(constrainedFrame.lines, [{ id: node.props.id, tag: node.tag, x1: 1, x2: Math.max(1, getFrameWidth(constrainedFrame), width), y1: 1, y2: getFrameHeight(constrainedFrame), textStartX: 3, textLength: value.length }], constrainedFrame.cursor, constrainedFrame.spans);
+  return createFrame(constrainedFrame.lines, [{ id: node.props.id, tag: node.tag, x1: 1, x2: Math.max(1, getFrameWidth(constrainedFrame)), y1: 1, y2: getFrameHeight(constrainedFrame), textStartX: 3, ...interactiveTextMetadata(value) }], constrainedFrame.cursor, constrainedFrame.spans);
 }
 
 function notifyLayoutContextProbe(node: TerminalElementNode, context?: TerminalRenderContext) {
@@ -524,13 +663,12 @@ function renderTableFrame(node: TerminalElementNode, context?: TerminalRenderCon
     const cells = new Array<TerminalFrame>(columnCount).fill(createFrame([""])).map((cell, index) => row[index] || cell);
     const rowHeight = cells.reduce((max, cell) => Math.max(max, getFrameHeight(cell)), 0);
     const normalized = cells.map((cell, index) => ({
-      frame: cell,
-      width: columnWidths[index],
-      lines: [...cell.lines.map((line) => line.padEnd(columnWidths[index], " ")), ...new Array<string>(Math.max(0, rowHeight - getFrameHeight(cell))).fill(" ".repeat(columnWidths[index]))]
+      frame: fitFrame(cell, columnWidths[index], rowHeight, { expandFullFrameSpans: true }),
+      width: columnWidths[index]
     }));
 
     for (let rowIndex = 0; rowIndex < rowHeight; rowIndex += 1) {
-      lines.push(normalized.map((cell) => cell.lines[rowIndex]).join(" | "));
+      lines.push(normalized.map((cell) => cell.frame.lines[rowIndex]).join(" | "));
     }
 
     let xOffset = 0;
@@ -681,7 +819,7 @@ function renderSplitFrame(node: TerminalElementNode, context?: TerminalRenderCon
     if (cellWidth <= 0 || cellHeight <= 0) {
       continue;
     }
-    frames.push(constrainFrame(renderSplitChildFrame(node.children[index], cellWidth, cellHeight, context), { width: cellWidth, height: cellHeight }));
+    frames.push(constrainFrame(renderSplitChildFrame(node.children[index], cellWidth, cellHeight, context), { width: cellWidth, height: cellHeight, expandFullFrameSpans: true }));
   }
 
   const frame = frames.length
@@ -722,7 +860,7 @@ function renderBodyFrame(children: TerminalNode[], props: TerminalElementNode["p
 }
 
 function renderFixedChildFrame(node: TerminalElementNode, width: number, height: number) {
-  return constrainFrame(renderBodyFrame(node.children, {}, { cols: width, rows: height }), { width, height });
+  return constrainFrame(renderBodyFrame(node.children, {}, { cols: width, rows: height }), { width, height, expandFullFrameSpans: true });
 }
 
 function renderFixedCompositionFrame(node: TerminalElementNode, width: number, height: number): TerminalFrame {
@@ -765,14 +903,14 @@ function renderFixedCompositionFrame(node: TerminalElementNode, width: number, h
     const leftFrames = fixedNodes.left.map((fixed) => renderFixedChildFrame(fixed, positiveInteger(fixed.props.size, "Fixed size"), middleHeight));
     const rightFrames = fixedNodes.right.map((fixed) => renderFixedChildFrame(fixed, positiveInteger(fixed.props.size, "Fixed size"), middleHeight));
     const bodyFrames = bodyWidth > 0
-      ? [constrainFrame(renderBodyFrame(bodyChildren, node.props, { cols: bodyWidth, rows: middleHeight }), { width: bodyWidth, height: middleHeight })]
+      ? [constrainFrame(renderBodyFrame(bodyChildren, node.props, { cols: bodyWidth, rows: middleHeight }), { width: bodyWidth, height: middleHeight, expandFullRowSpans: true })]
       : [];
 
-    middleFrames.push(constrainFrame(mergeHorizontal([...leftFrames, ...bodyFrames, ...rightFrames]), { width, height: middleHeight }));
+    middleFrames.push(constrainFrame(mergeHorizontal([...leftFrames, ...bodyFrames, ...rightFrames]), { width, height: middleHeight, expandFullRowSpans: true }));
   }
 
   const frame = mergeVertical([...topFrames, ...middleFrames, ...bottomFrames]);
-  return constrainFrame(frame, { width, height });
+  return constrainFrame(frame, { width, height, expandFullFrameSpans: true });
 }
 
 function renderStandaloneFixedFrame(node: TerminalElementNode, context?: TerminalRenderContext) {
@@ -846,7 +984,7 @@ function overlayGeometry(node: TerminalElementNode, width: number, height: numbe
 
 function renderOverlayChildFrame(node: TerminalElementNode, width: number, height: number, context?: TerminalRenderContext) {
   const geometry = overlayGeometry(node, width, height);
-  let frame = constrainFrame(renderBodyFrame(node.children, {}, { cols: geometry.width, rows: geometry.height, theme: context?.theme }), { width: geometry.width, height: geometry.height });
+  let frame = constrainFrame(renderBodyFrame(node.children, {}, { cols: geometry.width, rows: geometry.height, theme: context?.theme }), { width: geometry.width, height: geometry.height, expandFullRowSpans: true });
   frame = addContainerStyleSpans(frame, node, resolveNodeStyle(node, context));
   if (node.props.id && isFocusable(node)) {
     frame = addFocusableHitbox(frame, node as TerminalFocusNode);
@@ -854,11 +992,15 @@ function renderOverlayChildFrame(node: TerminalElementNode, width: number, heigh
   return { frame, geometry };
 }
 
+function orderedDirectOverlays(overlays: TerminalElementNode[]) {
+  return overlays.map((overlay, sourceOrder) => ({ overlay, sourceOrder })).sort((a, b) => a.sourceOrder - b.sourceOrder).map(({ overlay }) => overlay);
+}
+
 function applyDirectOverlays(base: TerminalFrame, overlays: TerminalElementNode[], context?: TerminalRenderContext) {
   let frame = base;
   const width = Math.max(1, getFrameWidth(base));
   const height = Math.max(1, getFrameHeight(base));
-  for (const overlay of overlays) {
+  for (const overlay of orderedDirectOverlays(overlays)) {
     const rendered = renderOverlayChildFrame(overlay, width, height, context);
     frame = overlayFrame(frame, rendered.frame, rendered.geometry);
   }
@@ -895,7 +1037,7 @@ function renderScreenFrame(node: TerminalElementNode, context?: TerminalRenderCo
     }
     base = mergeVertical(parts);
     if (context && overlays.length) {
-      base = constrainFrame(base, { width: context.cols, height: context.rows });
+      base = constrainFrame(base, { width: context.cols, height: context.rows, expandFullRowSpans: true });
     }
   }
 
@@ -968,13 +1110,13 @@ function renderLogViewFrame(node: TerminalElementNode, context?: TerminalRenderC
       }
     }
     if (typeof innerWidth !== "undefined") {
-      frame = constrainFrame(frame, { width: innerWidth, height: innerHeight });
+      frame = constrainFrame(frame, { width: innerWidth, height: innerHeight, expandFullFrameSpans: true });
     }
   }
   frame = padFrameSides(frame, padding);
   frame = addBorder(frame, border);
   if (typeof dimensions.width !== "undefined") {
-    frame = constrainFrame(frame, { width: dimensions.width, height: dimensions.height });
+    frame = constrainFrame(frame, { width: dimensions.width, height: dimensions.height, expandFullFrameSpans: true });
   } else if (typeof dimensions.height !== "undefined") {
     frame = cropFrame(frame, 0, dimensions.height);
     while (typeof dimensions.height !== "undefined" && getFrameHeight(frame) < dimensions.height) {
@@ -1005,18 +1147,18 @@ function renderSeparatedRowFrame(frames: TerminalFrame[], separator = " | ") {
     const frame = frames[index];
     const width = widths[index];
     for (let row = 0; row < height; row += 1) {
-      lines[row] += (frame.lines[row] || "").padEnd(width, " ");
+      lines[row] += padEndTerminalCells(frame.lines[row] || "", width);
       if (index < frames.length - 1) {
         lines[row] += separator;
       }
     }
-    const shifted = shiftFrame(frame, xOffset, 0);
+    const shifted = shiftFrame(fitFrame(frame, width, height, { expandFullFrameSpans: true }), xOffset, 0);
     hitboxes.push(...shifted.hitboxes);
     spans.push(...shifted.spans);
     if (!cursor && frame.cursor) {
       cursor = { x: frame.cursor.x + xOffset, y: frame.cursor.y };
     }
-    xOffset += width + (index < frames.length - 1 ? separator.length : 0);
+    xOffset += width + (index < frames.length - 1 ? terminalCellWidth(separator) : 0);
   }
 
   return createFrame(lines, hitboxes, cursor, spans);
@@ -1052,7 +1194,7 @@ function renderElementFrame(node: TerminalElementNode, context?: TerminalRenderC
       if (node.tag === "terminal-scroll") {
         const offset = numeric(node.props.__scrollOffset, 0);
         if (typeof dimensions.width !== "undefined") {
-          frame = constrainFrame(frame, { width: dimensions.width });
+          frame = constrainFrame(frame, { width: dimensions.width, expandFullFrameSpans: true });
         }
         const height = numeric(dimensions.height ?? node.props.height, getFrameHeight(frame));
         frame = cropFrame(frame, offset, height || getFrameHeight(frame));
@@ -1061,7 +1203,7 @@ function renderElementFrame(node: TerminalElementNode, context?: TerminalRenderC
         const spans = frame.spans.slice();
         for (let index = 0; index < frame.lines.length; index += 1) {
           const row = index + 1;
-          const width = frame.lines[index].length + 1;
+          const width = terminalCellWidth(frame.lines[index]) + 1;
           if (highlightRows.includes(row)) {
             spans.push({ kind: "highlight", x1: 1, x2: width, y: row });
           }
@@ -1084,41 +1226,114 @@ function renderElementFrame(node: TerminalElementNode, context?: TerminalRenderC
       return renderLogViewFrame(node, context);
     case "terminal-list": {
       const items = Array.isArray(node.props.items) ? node.props.items : [];
-      const selectedIndex = numeric(node.props.__selectedIndex, 0);
+      const activeIndex = clampListIndex(numeric(node.props.__activeIndex ?? node.props.__selectedIndex, 0), items.length);
+      const selectedIndex = typeof node.props.__selectedIndex === "number" ? clampListIndex(Number(node.props.__selectedIndex), items.length) : null;
       const hoveredIndex = typeof node.props.__hoveredIndex === "number" ? Number(node.props.__hoveredIndex) : -1;
-      const range = listVirtualRange(node, items.length, selectedIndex, context);
-      const lines: string[] = [];
-      for (let index = range.start; index < range.end; index += 1) {
-        const item = items[index];
-        const label = typeof node.props.renderItem === "function" ? plainText(node.props.renderItem(item, index)) : plainText(item);
-        lines.push(label);
-      }
-      const visibleLines = lines.length ? lines : [""];
+      const range = listVirtualRange(node, items.length, context);
       const layoutStyle = resolveLayoutStyle("list.base", node, context);
       const padding = normalizeSpacing(layoutStyle.padding, "List padding");
       const border = normalizeBorder(layoutStyle.border);
-      const decorated = addBorder(padFrameSides(createFrame(visibleLines), padding), border);
+      const horizontalDecoration = padding.left + padding.right + (border.left ? 1 : 0) + (border.right ? 1 : 0);
+      const wrapWidth = typeof context?.cols === "number" ? Math.max(1, context.cols - horizontalDecoration) : 1;
+      const visibleLines: string[] = [];
+      const itemIndexes: number[] = [];
+      const childHitboxes: TerminalHitbox[] = [];
+      for (let index = range.start; index < range.end; index += 1) {
+        const item = items[index];
+        const itemFrame = renderListItemFrame(node, item, index, index - range.visibleStart, activeIndex, selectedIndex, wrapWidth, context);
+        const rowOffset = visibleLines.length;
+        visibleLines.push(...itemFrame.lines);
+        for (let row = 0; row < itemFrame.lines.length; row += 1) {
+          itemIndexes.push(index);
+        }
+        childHitboxes.push(...shiftFrame(itemFrame, 0, rowOffset).hitboxes);
+      }
+      if (!visibleLines.length) {
+        visibleLines.push("");
+        itemIndexes.push(0);
+      }
+
+      const frameHeight = node.props.virtualized && node.props.wrap === true
+        ? positiveDimension(node.props.height, "height") ?? (typeof context?.rows === "number" ? Math.max(1, context.rows) : undefined)
+        : undefined;
+      const contentHeight = typeof frameHeight === "number"
+        ? Math.max(1, frameHeight - padding.top - padding.bottom - (border.top ? 1 : 0) - (border.bottom ? 1 : 0))
+        : visibleLines.length;
+      let visibleLineStart = 0;
+      if (node.props.virtualized && node.props.wrap === true && visibleLines.length > contentHeight) {
+        const activeLineIndex = itemIndexes.findIndex((sourceIndex) => sourceIndex === activeIndex);
+        if (activeLineIndex >= contentHeight) {
+          visibleLineStart = activeLineIndex - contentHeight + 1;
+        }
+      }
+      const frameLines = visibleLines.slice(visibleLineStart, visibleLineStart + contentHeight);
+      const frameItemIndexes = itemIndexes.slice(visibleLineStart, visibleLineStart + contentHeight);
+      const frameChildHitboxes = childHitboxes
+        .filter((box) => box.y2 > visibleLineStart && box.y1 <= visibleLineStart + contentHeight)
+        .map((box) => ({
+          ...box,
+          y1: Math.max(1, box.y1 - visibleLineStart),
+          y2: Math.min(contentHeight, box.y2 - visibleLineStart),
+          contentY: typeof box.contentY === "number" ? Math.max(1, box.contentY - visibleLineStart) : undefined
+        }));
+
+      const decorated = addBorder(padFrameSides(createFrame(frameLines, frameChildHitboxes), padding), border);
       const width = Math.max(1, getFrameWidth(decorated));
       const height = Math.max(1, getFrameHeight(decorated));
       const itemY = 1 + (border.top ? 1 : 0) + padding.top;
       const spans: TerminalStyleSpan[] = [];
-      for (let index = 0; index < visibleLines.length; index += 1) {
-        const sourceIndex = range.start + index;
+      for (let index = 0; index < frameLines.length; index += 1) {
+        const sourceIndex = frameItemIndexes[index];
         const y = itemY + index;
-        spans.push({ kind: "list.base", x1: 1, x2: width + 1, y });
-        if (sourceIndex === selectedIndex) {
-          spans.push({ kind: "list.current", x1: 1, x2: width + 1, y });
+        spans.push(markFullRowSpan({ kind: "list.base", x1: 1, x2: width + 1, y }));
+        if (selectedIndex !== null && selectedIndex !== activeIndex && sourceIndex === selectedIndex) {
+          spans.push(markFullRowSpan({ kind: "list.selected", x1: 1, x2: width + 1, y }));
+        }
+        if (sourceIndex === activeIndex) {
+          spans.push(markFullRowSpan({ kind: "list.current", x1: 1, x2: width + 1, y }));
         }
         if (sourceIndex === hoveredIndex) {
-          spans.push({ kind: "list.hover", x1: 1, x2: width + 1, y });
+          spans.push(markFullRowSpan({ kind: "list.hover", x1: 1, x2: width + 1, y }));
         }
       }
-      const frame = createFrame(decorated.lines, [], decorated.cursor, spans);
-      const styled = addFullFrameSpans(frame, resolveNodeStyle(node, context, { includeBase: false }).spanKinds);
-      if (!node.props.id) {
-        return styled;
+      const listHitboxes: TerminalHitbox[] = [];
+      const itemHitboxes: TerminalHitbox[] = [];
+      if (node.props.id) {
+        listHitboxes.push({
+          id: node.props.id,
+          tag: node.tag,
+          x1: 1,
+          x2: width,
+          y1: 1,
+          y2: Math.min(height, typeof frameHeight === "number" ? frameHeight : height),
+          itemOffset: range.start,
+          itemIndexes: frameItemIndexes,
+          contentY: itemY
+        });
+        let itemStart = 0;
+        while (itemStart < frameItemIndexes.length) {
+          const sourceIndex = frameItemIndexes[itemStart];
+          let itemEnd = itemStart;
+          while (itemEnd + 1 < frameItemIndexes.length && frameItemIndexes[itemEnd + 1] === sourceIndex) {
+            itemEnd += 1;
+          }
+          itemHitboxes.push({
+            id: node.props.id,
+            tag: node.tag,
+            x1: 1,
+            x2: width,
+            y1: itemY + itemStart,
+            y2: itemY + itemEnd,
+            itemOffset: range.start,
+            __listItemIndex: sourceIndex,
+            itemIndexes: new Array(itemEnd - itemStart + 1).fill(sourceIndex)
+          });
+          itemStart = itemEnd + 1;
+        }
       }
-      return createFrame(styled.lines, [{ id: node.props.id, tag: node.tag, x1: 1, x2: width, y1: 1, y2: height, itemOffset: range.start }], styled.cursor, styled.spans);
+      const frame = createFrame(decorated.lines, [...listHitboxes, ...itemHitboxes, ...decorated.hitboxes], decorated.cursor, spans);
+      const styled = addFullFrameSpans(frame, resolveNodeStyle(node, context, { includeBase: false }).spanKinds);
+      return typeof frameHeight === "number" ? constrainFrame(styled, { height: frameHeight, expandFullFrameSpans: true }) : styled;
     }
     case "terminal-table":
       return renderTableFrame(node, context);
@@ -1152,7 +1367,7 @@ function renderElementFrame(node: TerminalElementNode, context?: TerminalRenderC
         const decorated = addBorder(createFrame([line]), inputBorder);
         const width = Math.max(1, getFrameWidth(decorated));
         const height = Math.max(1, getFrameHeight(decorated));
-        const hitboxes = node.props.id ? [{ id: node.props.id, tag: node.tag, x1: 1, x2: width, y1: 1, y2: height, textStartX, textLength: stringValue.length }] : [];
+        const hitboxes = node.props.id ? [{ id: node.props.id, tag: node.tag, x1: 1, x2: width, y1: 1, y2: height, textStartX, ...interactiveTextMetadata(stringValue) }] : [];
         const spans = fullFrameSpans(["input.base"], width, height);
         return addFullFrameSpans(createFrame(decorated.lines, hitboxes, decorated.cursor, spans), resolveNodeStyle(node, context, { includeBase: false }).spanKinds);
       }
@@ -1161,19 +1376,19 @@ function renderElementFrame(node: TerminalElementNode, context?: TerminalRenderC
       const decorated = addBorder(createFrame([rendered.line], [], rendered.cursor, rendered.spans), inputBorder);
       const width = Math.max(1, getFrameWidth(decorated));
       const height = Math.max(1, getFrameHeight(decorated));
-      const hitboxes = node.props.id ? [{ id: node.props.id, tag: node.tag, x1: 1, x2: width, y1: 1, y2: height, textStartX, textLength: stringValue.length }] : [];
+      const hitboxes = node.props.id ? [{ id: node.props.id, tag: node.tag, x1: 1, x2: width, y1: 1, y2: height, textStartX, ...interactiveTextMetadata(stringValue) }] : [];
       const spans = [...fullFrameSpans(["input.base", "input.focus"], width, height), ...decorated.spans];
       return addFullFrameSpans(createFrame(decorated.lines, hitboxes, decorated.cursor, spans), resolveNodeStyle(node, context, { includeBase: false }).spanKinds);
     }
     case "terminal-editor":
-      return addFullFrameSpans(renderEditorFrame(node), resolveNodeStyle(node, context).spanKinds);
+      return addFullFrameSpans(renderEditorFrame(node, context), resolveNodeStyle(node, context).spanKinds);
     case "terminal-button": {
       const label = typeof node.props.label !== "undefined" ? plainText(node.props.label) : plainText(node.children.map(textContent).join(""));
       const layoutStyle = resolveLayoutStyle("button.base", node, context);
       const decorated = decoratedControlFrame([String(label)], layoutStyle);
       const width = Math.max(1, getFrameWidth(decorated));
       const height = Math.max(1, getFrameHeight(decorated));
-      const hitboxes = node.props.id ? [{ id: node.props.id, tag: node.tag, x1: 1, x2: width, y1: 1, y2: height }] : [];
+      const hitboxes = node.props.id ? [{ id: node.props.id, tag: node.tag, x1: 1, x2: width, y1: 1, y2: height, __pressHandler: typeof node.props.onpress === "function" ? node.props.onpress : undefined }] : [];
       const kinds = ["button.base", ...nodeStates(node).map((state) => `button.${state}`)];
       const spans = fullFrameSpans(kinds, width, height);
       return addFullFrameSpans(createFrame(decorated.lines, hitboxes, decorated.cursor, spans), resolveNodeStyle(node, context, { includeBase: false }).spanKinds);

package/src/runtime.ts

@@ -144,15 +144,23 @@ function normalizeValyrianInput(input: any): any {
   }
 
   const props = { ...((input.props && input.props.__terminalProps) || input.props || {}) };
-  const children = Array.isArray(input.children)
-    ? input.children.map((child) => {
+  const rawChildren = Array.isArray(input.children) ? input.children : [];
+  const isListComponentWithRenderChild = typeof input.tag === "function" && input.tag.name === "TerminalList" && rawChildren.length === 1 && typeof rawChildren[0] === "function";
+  if (isListComponentWithRenderChild) {
+    props.__childrenRenderer = rawChildren[0];
+  }
+  const tag = typeof input.tag === "string" ? input.tag : wrapComponent(input.tag);
+  const children = isListComponentWithRenderChild || (tag === "terminal-list" && rawChildren.length === 1 && typeof rawChildren[0] === "function")
+    ? []
+    : rawChildren.map((child) => {
       if (props["v-for"] && typeof child === "function") {
         return (...args: any[]) => normalizeValyrianInput(child(...args));
       }
       return normalizeValyrianInput(child);
-    })
-    : [];
-  const tag = typeof input.tag === "string" ? input.tag : wrapComponent(input.tag);
+    });
+  if (tag === "terminal-list" && rawChildren.length === 1 && typeof rawChildren[0] === "function") {
+    props.__childrenRenderer = rawChildren[0];
+  }
   if (typeof tag === "string" && isTerminalTag(tag)) {
     const terminalProps = { ...props };
     if (typeof props.style === "object") {