@oh-my-pi/pi-tui 18.4.3 → 18.4.4

package/src/components/form.ts

@@ -1,6 +1,10 @@
 import { getKeybindings } from "../keybindings";
 import { matchesKey } from "../keys";
 import type { MouseRoutable, SgrMouseEvent } from "../mouse";
+import { col, node, span } from "../native/describe";
+import { plainText } from "../native/spans";
+import type { DescribeContext, NativeChild, NativeNode, NativeUiEvent } from "../native/node";
+import { type SelectPickerOptions, SelectListSheet } from "../native/picker";
 import { Container, type Component, type Focusable } from "../tui";
 import { replaceTabs, truncateToWidth } from "../utils";
 import { Input } from "./input";
@@ -48,10 +52,13 @@ function hasMouseRouter(component: FormControl): component is FormControl & Mous
 class StyledText implements Component {
 	readonly #text: Text;
 	#value: string;
+	#native: NativeNode | undefined;
 
 	constructor(
 		value: string,
 		private readonly style: (text: string) => string,
+		/** Span token standing in for `style` on a TSP terminal. */
+		private readonly token?: string,
 	) {
 		this.#value = value;
 		this.#text = new Text(this.style(value), 0, 0);
@@ -60,9 +67,15 @@ class StyledText implements Component {
 	setText(value: string): void {
 		if (value === this.#value) return;
 		this.#value = value;
+		this.#native = undefined;
 		this.#text.setText(this.style(value));
 	}
 
+	describe(_cx: DescribeContext): NativeNode {
+		this.#native ??= node("text", { spans: [span(plainText(this.#value), this.token)] });
+		return this.#native;
+	}
+
 	render(width: number): readonly string[] {
 		return this.#text.render(width);
 	}
@@ -77,9 +90,14 @@ class OptionalText implements Component {
 	readonly #text: StyledText;
 	#value = "";
 	readonly #empty: readonly string[] = [];
+	readonly #hidden = node("text", { text: "", hidden: true });
 
-	constructor(style: (text: string) => string) {
-		this.#text = new StyledText("", style);
+	constructor(style: (text: string) => string, token?: string) {
+		this.#text = new StyledText("", style, token);
+	}
+
+	describe(cx: DescribeContext): NativeNode {
+		return this.#value ? this.#text.describe(cx) : this.#hidden;
 	}
 
 	setText(value: string): void {
@@ -114,37 +132,67 @@ export class FormField implements Component, Focusable, MouseRoutable {
 	#memoControl: readonly string[] | undefined;
 	#memoAfter: readonly string[] | undefined;
 	#memoLines: readonly string[] = [];
+	/** Fixed described structure: every child is a component or a static node, so it never changes. */
+	readonly #native: NativeNode;
 
 	constructor(control: FormControl, options: FormFieldOptions) {
 		this.control = control;
-		this.#error = new OptionalText(options.theme.error);
+		this.#error = new OptionalText(options.theme.error, "error");
+		// Spacing is the terminal's (`gap`); only content becomes native children.
+		const native: NativeChild[] = [];
 
 		if (options.leadingSpace) this.#beforeControl.addChild(new Spacer(1));
 		if (options.label) {
-			this.#beforeControl.addChild(new StyledText(options.label, options.theme.label));
+			const label = new StyledText(options.label, options.theme.label, "strong");
+			this.#beforeControl.addChild(label);
+			native.push(label);
 		}
 		if (options.description) {
 			if (options.label) this.#beforeControl.addChild(new Spacer(1));
-			this.#beforeControl.addChild(new StyledText(options.description, options.theme.description));
+			const description = new StyledText(options.description, options.theme.description, "muted");
+			this.#beforeControl.addChild(description);
+			native.push(description);
+		}
+		for (const detail of options.details ?? []) {
+			this.#beforeControl.addChild(detail);
+			native.push(detail);
 		}
-		for (const detail of options.details ?? []) this.#beforeControl.addChild(detail);
 		if (options.preview) {
 			this.#beforeControl.addChild(new Spacer(1));
 			if (options.previewLabel) {
-				this.#beforeControl.addChild(new StyledText(options.previewLabel, options.theme.description));
+				const previewLabel = new StyledText(options.previewLabel, options.theme.description, "muted");
+				this.#beforeControl.addChild(previewLabel);
+				native.push(previewLabel);
 			}
 			this.#beforeControl.addChild(options.preview);
+			native.push(options.preview);
 		}
 		if (options.spaceBeforeControl !== false) this.#beforeControl.addChild(new Spacer(1));
+		native.push(control);
 
 		if (options.spaceAfterControl !== false) this.#afterControl.addChild(new Spacer(1));
 		this.#afterControl.addChild(this.#error);
-		for (const summary of options.summary ?? []) this.#afterControl.addChild(summary);
-		if (options.hint) this.#afterControl.addChild(new StyledText(options.hint, options.theme.hint));
+		native.push(this.#error);
+		for (const summary of options.summary ?? []) {
+			this.#afterControl.addChild(summary);
+			native.push(summary);
+		}
+		if (options.hint) {
+			const hint = new StyledText(options.hint, options.theme.hint, "muted");
+			this.#afterControl.addChild(hint);
+			native.push(hint);
+		}
 		if (options.footer) {
 			this.#afterControl.addChild(new Spacer(1));
 			this.#afterControl.addChild(options.footer);
+			native.push(options.footer);
 		}
+		this.#native = col(native, { gap: "sm", role: "omp.form.field" });
+	}
+
+	/** Label, description, details, preview, the control, error, summary, hint and footer as one column. */
+	describe(_cx: DescribeContext): NativeNode {
+		return this.#native;
 	}
 
 	get focused(): boolean {
@@ -346,14 +394,22 @@ export interface SelectFormFieldOptions extends Omit<FormFieldOptions, "preview"
 	onCancel(): void;
 	/** Schedule a frame after an asynchronous preview update settles. */
 	requestRender?: () => void;
+	/** The picker sheet a long choice (> {@link PICKER_MIN_ITEMS} items) describes as; defaults to the label. */
+	picker?: SelectPickerOptions;
 }
 
+/** Choices longer than this describe as a `picker md` sheet where the terminal draws one (spec §5 controls). */
+const PICKER_MIN_ITEMS = 12;
+
 /** SelectList field that centralizes selection, cancellation, preview refresh, and mouse routing. */
 export class SelectFormField extends FormField {
 	readonly selectList: SelectList;
 	readonly #previewText: StyledText | undefined;
 	readonly #getPreview: (() => string) | undefined;
 	readonly #requestRender: (() => void) | undefined;
+	readonly #sheet: SelectListSheet;
+	/** Number of choices (before filtering). */
+	readonly itemCount: number;
 	#previewRequestId = 0;
 
 	constructor(options: SelectFormFieldOptions) {
@@ -375,6 +431,16 @@ export class SelectFormField extends FormField {
 		this.#previewText = previewText;
 		this.#getPreview = options.getPreview;
 		this.#requestRender = options.requestRender;
+		this.itemCount = options.items.length;
+		this.#sheet = new SelectListSheet(
+			selectList,
+			options.picker ?? {
+				title: options.label ?? "Select",
+				...(options.description ? { subtitle: options.description } : {}),
+				searchable: true,
+			},
+			{ docked: false },
+		);
 
 		selectList.onSelect = item => {
 			try {
@@ -420,9 +486,20 @@ export class SelectFormField extends FormField {
 
 	override invalidate(): void {
 		this.#updatePreview();
+		this.#sheet.invalidate();
 		super.invalidate();
 	}
 
+	/** Long choices describe as a picker sheet where supported; the host places it (layer or prefs editor). */
+	override describe(cx: DescribeContext): NativeNode {
+		return this.itemCount > PICKER_MIN_ITEMS && cx.supports("picker") ? this.#sheet.describe() : super.describe(cx);
+	}
+
+	/** Picker pointer events drive the list as its keys do (preview, pick, cancel). */
+	handleNativeEvent(event: NativeUiEvent): void {
+		this.#sheet.handle(event);
+	}
+
 	#finishPreview(requestId: number): void {
 		if (requestId !== this.#previewRequestId) return;
 		this.setError(undefined);
@@ -467,13 +544,20 @@ export class Form implements Component, Focusable, MouseRoutable {
 	#memoWidth = -1;
 	#memoFieldLines: (readonly string[])[] = [];
 	#memoLines: readonly string[] = [];
+	readonly #native: NativeNode;
 
 	constructor(options: FormOptions) {
 		this.#options = options;
 		this.#fields = options.fields;
+		this.#native = col(this.#fields, { gap: "md", role: "omp.form" });
 		this.#syncFocus();
 	}
 
+	/** The fields as one column; focus traversal stays keyboard-driven. */
+	describe(_cx: DescribeContext): NativeNode {
+		return this.#native;
+	}
+
 	get focused(): boolean {
 		return this.#focused;
 	}

package/src/components/image.ts

@@ -8,6 +8,9 @@ import {
 	renderImage,
 	TERMINAL,
 } from "../terminal-capabilities";
+import { registerNativeBlob } from "../native/blobs";
+import { node } from "../native/describe";
+import type { DescribeContext, NativeNode } from "../native/node";
 import type { Component } from "../tui";
 
 export interface ImageTheme {
@@ -731,6 +734,7 @@ export class Image implements Component {
 	// pads itself to this height so a budget demotion never shrinks the block
 	// (its rows may already be committed to native scrollback).
 	#renderedGraphicRows = 0;
+	#native?: NativeNode;
 
 	constructor(
 		base64Data: string,
@@ -764,6 +768,32 @@ export class Image implements Component {
 		this.#cachedWidth = undefined;
 	}
 
+	/**
+	 * A native `image` backed by a content-addressed blob; the terminal fits
+	 * it. Cell caps become `ch`/`lines` bounds. The inline-image budget and
+	 * graphics protocols do not apply.
+	 */
+	describe(_cx: DescribeContext): NativeNode {
+		if (this.#native) return this.#native;
+		const blob = registerNativeBlob(Buffer.from(this.#base64Data, "base64"), this.#mimeType);
+		const maxW = this.#options.maxWidthCells;
+		const maxH = this.#options.maxHeightCells;
+		this.#native = node("image", {
+			blob,
+			alt: imageFallback(this.#mimeType, this.#dimensions, this.#options.filename),
+			w: this.#dimensions.widthPx,
+			h: this.#dimensions.heightPx,
+			max:
+				(maxW ?? 0) > 0 || (maxH ?? 0) > 0
+					? {
+							w: maxW && maxW > 0 ? `${maxW}ch` : undefined,
+							h: maxH && maxH > 0 ? `${maxH}lines` : undefined,
+						}
+					: undefined,
+		});
+		return this.#native;
+	}
+
 	render(width: number): readonly string[] {
 		const imageProtocol = TERMINAL.imageProtocol;
 		const hasProtocol = imageProtocol != null;

package/src/components/input.ts

@@ -2,6 +2,11 @@ import { BracketedPasteHandler, decodeReencodedPasteControls } from "../brackete
 import { getKeybindings } from "../keybindings";
 import { extractPrintableText, matchesKey } from "../keys";
 import { KillRing } from "../kill-ring";
+import type { TspInputProps } from "@oh-my-pi/pi-wire";
+import { node } from "../native/describe";
+import { sameProps } from "../native/memo";
+import { plainText } from "../native/spans";
+import type { DescribeContext, NativeNode } from "../native/node";
 import { SpaceHoldGesture } from "../space-hold";
 import { type Component, CURSOR_MARKER, type Focusable } from "../tui";
 import { cursorColumnWindow } from "./scroll-viewport";
@@ -58,6 +63,8 @@ export class Input implements Component, Focusable {
 	prompt = "> ";
 	/** Render the editable value as bullets while retaining the real value internally. */
 	mask = false;
+	/** Dim hint a native terminal shows while the value is empty. */
+	placeholder: string | undefined;
 	onSubmit?: (value: string) => void;
 	onEscape?: () => void;
 	/** Space-bar push-to-talk; set its `handler` to enable it. */
@@ -81,9 +88,17 @@ export class Input implements Component, Focusable {
 	/** Code units of the current volatile speech-to-text preview (see {@link setVolatileText}). */
 	#volatileTextLen = 0;
 
+	#native?: { props: TspInputProps; node: NativeNode };
+
 	getValue(): string {
 		return this.#value;
 	}
+
+	/** The caret as a UTF-16 offset into {@link getValue}. */
+	getCursor(): number {
+		return this.#cursor;
+	}
+
 	/** Return bounded input content and cursor state for debug inspection. */
 	debugState(): Record<string, unknown> {
 		return {
@@ -112,7 +127,14 @@ export class Input implements Component, Focusable {
 		return this.#useTerminalCursor;
 	}
 
-	handleInput(data: string): void {
+	/**
+	 * Apply one key: the editor's text bindings (motion, deletion, kill ring,
+	 * undo), pastes and printable text. Returns whether the key was the
+	 * field's: false for keys it has no binding for, and for cancel/submit
+	 * without an `onEscape`/`onSubmit`, so a host (a list's search field) can
+	 * route everything else on.
+	 */
+	handleInput(data: string): boolean {
 		// Handle bracketed paste mode
 		const paste = this.#pasteHandler.process(data);
 		if (paste.handled) {
@@ -122,77 +144,79 @@ export class Input implements Component, Focusable {
 					this.handleInput(paste.remaining);
 				}
 			}
-			return;
+			return true;
 		}
 
 		// Space-hold push-to-talk: a sustained space bar starts/stops STT instead of typing spaces.
 		switch (this.spaceHold.process(matchesKey(data, "space"))) {
 			case "type":
 				this.#insertCharacter(" ");
-				return;
+				return true;
 			case "swallow":
-				return;
+				return true;
 		}
 
 		const kb = getKeybindings();
 
 		// Escape/Cancel
 		if (kb.matches(data, "tui.select.cancel")) {
-			if (this.onEscape) this.onEscape();
-			return;
+			if (!this.onEscape) return false;
+			this.onEscape();
+			return true;
 		}
 
 		// Undo
 		if (kb.matches(data, "tui.editor.undo")) {
 			this.#undo();
-			return;
+			return true;
 		}
 
 		// Submit
 		if (kb.matches(data, "tui.input.submit") || data === "\n") {
-			if (this.onSubmit) this.onSubmit(this.#value);
-			return;
+			if (!this.onSubmit) return false;
+			this.onSubmit(this.#value);
+			return true;
 		}
 
 		// Deletion
 		if (kb.matches(data, "tui.editor.deleteCharBackward")) {
 			this.#handleBackspace();
-			return;
+			return true;
 		}
 
 		if (kb.matches(data, "tui.editor.deleteCharForward")) {
 			this.#handleForwardDelete();
-			return;
+			return true;
 		}
 
 		if (kb.matches(data, "tui.editor.deleteWordBackward")) {
 			this.#deleteWordBackwards();
-			return;
+			return true;
 		}
 
 		if (kb.matches(data, "tui.editor.deleteWordForward")) {
 			this.#deleteWordForward();
-			return;
+			return true;
 		}
 
 		if (kb.matches(data, "tui.editor.deleteToLineStart")) {
 			this.#deleteToLineStart();
-			return;
+			return true;
 		}
 
 		if (kb.matches(data, "tui.editor.deleteToLineEnd")) {
 			this.#deleteToLineEnd();
-			return;
+			return true;
 		}
 
 		// Kill ring actions
 		if (kb.matches(data, "tui.editor.yank")) {
 			this.#yank();
-			return;
+			return true;
 		}
 		if (kb.matches(data, "tui.editor.yankPop")) {
 			this.#yankPop();
-			return;
+			return true;
 		}
 
 		// Cursor movement
@@ -204,7 +228,7 @@ export class Input implements Component, Focusable {
 				const lastGrapheme = graphemes[graphemes.length - 1];
 				this.#cursor -= lastGrapheme ? lastGrapheme.segment.length : 1;
 			}
-			return;
+			return true;
 		}
 
 		if (kb.matches(data, "tui.editor.cursorRight")) {
@@ -215,36 +239,36 @@ export class Input implements Component, Focusable {
 				const firstGrapheme = graphemes[0];
 				this.#cursor += firstGrapheme ? firstGrapheme.segment.length : 1;
 			}
-			return;
+			return true;
 		}
 
 		if (kb.matches(data, "tui.editor.cursorLineStart")) {
 			this.#lastAction = null;
 			this.#cursor = 0;
-			return;
+			return true;
 		}
 
 		if (kb.matches(data, "tui.editor.cursorLineEnd")) {
 			this.#lastAction = null;
 			this.#cursor = this.#value.length;
-			return;
+			return true;
 		}
 
 		if (kb.matches(data, "tui.editor.cursorWordLeft")) {
 			this.#moveWordBackwards();
-			return;
+			return true;
 		}
 
 		if (kb.matches(data, "tui.editor.cursorWordRight")) {
 			this.#moveWordForwards();
-			return;
+			return true;
 		}
 
 		// Regular character input, including Kitty CSI-u text-producing sequences.
 		const printableText = extractPrintableText(data);
-		if (printableText) {
-			this.#insertCharacter(printableText);
-		}
+		if (!printableText) return false;
+		this.#insertCharacter(printableText);
+		return true;
 	}
 
 	/** Apply terminal paste semantics to text from non-bracketed paste transports
@@ -484,6 +508,33 @@ export class Input implements Component, Focusable {
 		// No cached state to invalidate currently
 	}
 
+	/**
+	 * An `input` with the value, the caret as a UTF-16 offset and the prompt;
+	 * the terminal draws the caret, scrolls horizontally and places the IME.
+	 * A masked input sends one bullet per grapheme, with the caret mapped onto
+	 * them, so the secret never leaves the process.
+	 */
+	describe(_cx: DescribeContext): NativeNode {
+		let value = this.#value;
+		let cursor = this.#cursor;
+		if (this.mask) {
+			const graphemes = [...segmenter.segment(this.#value)];
+			value = "•".repeat(graphemes.length);
+			cursor = graphemes.filter(grapheme => grapheme.index < this.#cursor).length;
+		}
+		const prompt = plainText(this.prompt);
+		const props: TspInputProps = {
+			text: value,
+			cursor,
+			prompt: prompt || undefined,
+			placeholder: this.placeholder,
+		};
+		if (this.#native && sameProps(this.#native.props, props)) return this.#native.node;
+		const described = node("input", props);
+		this.#native = { props, node: described };
+		return described;
+	}
+
 	render(width: number): readonly string[] {
 		width = Number.isFinite(width) ? Math.max(0, Math.trunc(width)) : 0;
 		// Calculate visible window

package/src/components/key-value-list.ts

@@ -1,3 +1,6 @@
+import { compactText, styleSpans } from "../native/spans";
+import { node } from "../native/describe";
+import type { DescribeContext, NativeNode } from "../native/node";
 import type { Component } from "../tui";
 import { Ellipsis, getWidthConfigEpoch, replaceTabs, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "../utils";
 
@@ -31,6 +34,7 @@ export class KeyValueList implements Component {
 	#rows: readonly KeyValueRow[];
 	readonly #options: KeyValueListOptions;
 	#cache: { width: number; epoch: number; lines: readonly string[] } | undefined;
+	#native: NativeNode | undefined;
 
 	constructor(rows: readonly KeyValueRow[], options: KeyValueListOptions) {
 		this.#rows = rows;
@@ -41,11 +45,25 @@ export class KeyValueList implements Component {
 		if (this.#rows === rows) return false;
 		this.#rows = rows;
 		this.#cache = undefined;
+		this.#native = undefined;
 		return true;
 	}
 
 	invalidate(): void {
 		this.#cache = undefined;
+		this.#native = undefined;
+	}
+
+	/** An aligned `kv` grid; label width and value wrapping are the terminal's. */
+	describe(_cx: DescribeContext): NativeNode {
+		this.#native ??= node("kv", {
+			layout: "grid",
+			items: this.#rows.map(row => ({
+				k: compactText(styleSpans(singleLine(row.label), row.labelStyle)),
+				v: compactText(styleSpans(singleLine(row.value), row.valueStyle)),
+			})),
+		});
+		return this.#native;
 	}
 
 	render(width: number): readonly string[] {

package/src/components/layout/geometry.ts

@@ -1,3 +1,4 @@
+import type { TspProps, TspSpace } from "@oh-my-pi/pi-wire";
 import type { MouseRoutable } from "../../mouse";
 import type { Component } from "../../tui";
 import { padding, truncateToWidth, visibleWidth } from "../../utils";
@@ -51,6 +52,49 @@ export interface LayoutAllocation {
 	max?: number;
 }
 
+const kNativeAdapter = Symbol("layout.nativeAdapter");
+type AdaptedRenderer = LayoutRenderer & { [kNativeAdapter]?: Component };
+
+/**
+ * Describe child for layout content: components describe themselves; a lazy
+ * row renderer becomes a stable adapter component the native engine renders
+ * as a `rows` fallback (it can only produce width-bound rows).
+ */
+export function nativeLayoutChild(content: LayoutContent): Component {
+	if (typeof content !== "function") return content;
+	const adapted = content as AdaptedRenderer;
+	adapted[kNativeAdapter] ??= { render: width => content(width, undefined) };
+	return adapted[kNativeAdapter];
+}
+
+/** Spacing step standing in for a textual gap decoration (the terminal draws no divider glyphs). */
+export function nativeLayoutGap(decoration: LayoutDecoration | undefined): TspSpace | undefined {
+	const length = layoutDecorationText(decoration).length;
+	if (length === 0) return undefined;
+	if (length === 1) return "xs";
+	if (length === 2) return "sm";
+	return "md";
+}
+
+/** Flex props for one layout slot along `axis` (`w` for rows, `h` for stacks). */
+export function nativeSlotProps(
+	axis: "w" | "h",
+	slot: { fixed?: number; grow?: number; min?: number; max?: number },
+): TspProps<"col"> {
+	const bound = (cells: number): { w: `${number}ch` } | { h: `${number}lines` } =>
+		axis === "w" ? { w: `${cells}ch` } : { h: `${cells}lines` };
+	const fixed = optionalLayoutSize(slot.fixed);
+	if (fixed !== undefined) return { grow: 0, shrink: 0, min: bound(fixed), max: bound(fixed) };
+	const min = optionalLayoutSize(slot.min);
+	const max = optionalLayoutSize(slot.max);
+	return {
+		grow: slot.grow === undefined ? undefined : layoutSize(slot.grow),
+		basis: "content",
+		min: min === undefined || min === 0 ? undefined : bound(min),
+		max: max === undefined ? undefined : bound(max),
+	};
+}
+
 /** Clamp an external size to a finite, non-negative integer cell count. */
 export function layoutSize(value: number | undefined, fallback = 0): number {
 	const resolved = value === undefined || !Number.isFinite(value) ? fallback : value;

package/src/components/layout/row.ts

@@ -1,4 +1,6 @@
 import type { MouseRoutable, SgrMouseEvent } from "../../mouse";
+import { col, row } from "../../native/describe";
+import type { DescribeContext, NativeNode } from "../../native/node";
 import type { Component } from "../../tui";
 import { padding, visibleWidth } from "../../utils";
 import {
@@ -15,6 +17,9 @@ import {
 	type LayoutInsets,
 	type LayoutRect,
 	layoutSize,
+	nativeLayoutChild,
+	nativeLayoutGap,
+	nativeSlotProps,
 	optionalLayoutSize,
 	renderLayoutContent,
 	uniqueLayoutComponents,
@@ -87,6 +92,7 @@ export class Row implements Component, MouseRoutable {
 	#frames: LayoutRect[] = [];
 	#memo: RowMemo | undefined;
 	#ignoreTight = false;
+	#native: { children: RowChild[]; gap: LayoutDecoration | undefined; node: NativeNode } | undefined;
 
 	constructor(options: RowOptions) {
 		this.#children = options.children.map(child => ({ ...child, padding: { ...child.padding } }));
@@ -168,6 +174,30 @@ export class Row implements Component, MouseRoutable {
 		}
 	}
 
+	/**
+	 * A flex `row`: each child sits in a slot carrying its width bounds
+	 * (fixed → min = max `ch`, else grow/min/max). Decorations become gap
+	 * spacing; clipping and the exact row budget are the terminal's.
+	 */
+	describe(_cx: DescribeContext): NativeNode {
+		const cached = this.#native;
+		if (cached?.children === this.#children && cached.gap === this.#gap) return cached.node;
+		const slots = this.#children.map(child =>
+			col(
+				[nativeLayoutChild(child.content)],
+				nativeSlotProps("w", {
+					fixed: child.width,
+					grow: child.width === undefined ? layoutSize(child.grow, 1) : undefined,
+					min: child.minWidth,
+					max: child.maxWidth,
+				}),
+			),
+		);
+		const described = row(slots, { gap: nativeLayoutGap(this.#gap), align: this.#align });
+		this.#native = { children: this.#children, gap: this.#gap, node: described };
+		return described;
+	}
+
 	/** Translate a row-local point into a child's local coordinates. */
 	locate(line: number, col: number): RowHit | undefined {
 		for (let index = 0; index < this.#frames.length; index++) {