ink-framework 0.0.0-stage → 0.1.0-alpha.2

package/src/image.ts

@@ -0,0 +1,45 @@
+import type { IconAsset } from "./index";
+import { createElement, memo } from "./react";
+import type { Destination } from "./navigation";
+import { pressHandler, type PressProps } from "./press";
+
+export function Avatar({ src = "", unread = false, onPress, onLongPress }: {
+  src?: string;
+  unread?: boolean;
+  onPress?: () => void;
+  onLongPress?: () => void;
+}) {
+  return createElement("Avatar", { src, unread, onPress, onLongPress });
+}
+
+function RowComponent<const D extends Destination>({ image, title, titleMaxLines, titleIcon, subtitle, subtitleIcon, href, url, onPress, onLongPress }: PressProps<D> & {
+  image?: string;
+  title: string;
+  titleMaxLines?: number;
+  titleIcon?: IconAsset;
+  subtitle?: string;
+  subtitleIcon?: IconAsset;
+  onLongPress?: () => void;
+}) {
+  return createElement("RowContent", {
+    image, title, titleMaxLines, titleIcon, subtitle, subtitleIcon,
+    onPress: pressHandler({ href, url, onPress }) ?? (onLongPress ? () => {} : undefined),
+    onLongPress,
+  });
+}
+
+export const Row = /* @__PURE__ */ memo(RowComponent) as typeof RowComponent;
+
+export function Image(props: {
+  src: string;
+  width: number;
+  height: number;
+  fit?: "contain" | "cover";
+  bleed?: boolean;
+  /** Fill the available content width, using width and height as the aspect ratio. */
+  fillWidth?: boolean;
+  zoomable?: boolean;
+  loop?: boolean;
+}) {
+  return createElement("Image", props);
+}

package/src/index.ts

@@ -0,0 +1,137 @@
+/// <reference path="./assets.d.ts" />
+import type { IconAsset } from "./assets";
+import type { ReactElement, ReactNode } from "react";
+import type {} from "react/jsx-runtime";
+import type {} from "react/jsx-dev-runtime";
+import { createElement, useMemo, useState } from "./react";
+import { ScrollToEndContext } from "./scroll";
+import type { Destination } from "./navigation";
+import { pressHandler, type PressProps } from "./press";
+export { useSnapshot, type Snapshot, type SnapshotSource } from "./snapshot";
+export { resource, type ResourceSnapshot, type ResourceSource } from "./resource";
+export { useAction, type Action } from "./action";
+export { NativeError } from "./native";
+export { Tabs, Slot, navigate, replace, back, useRouteParams, type Destination } from "./navigation";
+
+export function Screen({ header, children, leftAction, rightAction, ...props }: {
+  children?: ReactNode;
+  header?: ReactNode;
+  title?: string;
+  background?: string;
+  centered?: boolean;
+  wide?: boolean;
+  bottomInset?: boolean;
+  waitForImages?: boolean;
+  leftAction?: { icon: IconAsset; onPress: () => void };
+  rightAction?: { icon: IconAsset; onPress: () => void };
+}) {
+  const [scrollToEnd, setScrollToEnd] = useState(0);
+  const requestEnd = useMemo(() => () => setScrollToEnd(value => value + 1), []);
+  return createElement(ScrollToEndContext.Provider, { value: requestEnd }, createElement("Screen", { ...props, scrollToEnd, pinnedHeader: header != null, leftIcon: leftAction?.icon, onLeftPress: leftAction?.onPress, rightIcon: rightAction?.icon, onRightPress: rightAction?.onPress },
+    header != null && createElement(Stack, { gap: 47 }, header),
+    children,
+  ));
+}
+
+export interface StackProps {
+  children?: ReactNode;
+  axis?: "vertical" | "horizontal";
+  gap?: number;
+  align?: "start" | "center" | "end" | "stretch";
+  justify?: "start" | "center" | "end" | "space-between";
+  onPress?: () => void;
+  haptic?: boolean;
+}
+
+export const Stack = "Stack";
+
+export type TextProps<D extends Destination = Destination> = PressProps<D> & {
+  width?: number;
+  children?: ReactNode;
+  size?: number;
+  align?: "start" | "center" | "end" | "justify";
+  maxLines?: number;
+  tabularNumbers?: boolean;
+}
+
+// Keep text as a host element while checking literal route parameters in JSX.
+export const Text = "Text" as "Text" & (<const D extends Destination>(props: TextProps<D>) => ReactElement);
+
+declare module "react" {
+  namespace JSX {
+    interface IntrinsicElements {
+      Text: TextProps;
+      Stack: StackProps;
+    }
+  }
+}
+
+// The automatic JSX runtime can resolve a different React type instance in linked apps.
+declare module "react/jsx-runtime" {
+  namespace JSX {
+    interface IntrinsicElements { Text: TextProps; Stack: StackProps; }
+  }
+}
+
+declare module "react/jsx-dev-runtime" {
+  namespace JSX {
+    interface IntrinsicElements { Text: TextProps; Stack: StackProps; }
+  }
+}
+
+export function Button<const D extends Destination>(props: PressProps<D> & {
+  children?: ReactNode;
+  onLongPress?: () => void;
+  disabled?: boolean;
+  selected?: boolean;
+  icon?: IconAsset;
+}) {
+  const { href, url, onPress, ...rest } = props;
+  return createElement("Button", { ...rest, onPress: pressHandler({ href, url, onPress }) });
+}
+
+export { Row, Image, Avatar } from "./image";
+export { Canvas, Rectangle, CanvasText, CanvasIcon } from "./canvas";
+
+export function Field<const D extends Destination>(props: PressProps<D> & {
+  label: string;
+  children?: ReactNode;
+}) {
+  const { href, url, onPress, ...rest } = props;
+  return createElement("Field", { ...rest, onPress: pressHandler({ href, url, onPress }) });
+}
+
+export function Toggle(props: {
+  label: string;
+  subtitle?: string;
+  value: boolean;
+  disabled?: boolean;
+  onChange: (value: boolean) => void;
+}) {
+  return createElement("Toggle", props);
+}
+
+export function Icon(props: {
+  name: IconAsset;
+  size?: number;
+  tone?: "primary" | "muted";
+}) {
+  return createElement("Icon", props);
+}
+
+export { TextInput } from "./input";
+
+export { List, type ListProps } from "./list";
+export { ReorderList, type ReorderListProps } from "./reorder";
+export { setColourScheme, useColourScheme, type ColourScheme } from "./appearance";
+export {
+  SettingsChoices, LoadingState, EmptyState, ErrorState, Confirmation,
+  type SettingsChoice, type SettingsChoicesProps, type EmptyStateProps,
+  type ErrorStateProps, type ConfirmationProps,
+} from "./patterns";
+
+export { findIcon, type IconAsset } from "./assets";
+export { PlayingScreen, type PlayingScreenProps, type Playback, type TransportControl } from "./playing";
+export { ConversationScreen, Message, type ConversationScreenProps, type ConversationMessage, type MessageProps, type MessageAction, type ReplyPreview } from "./conversation";
+export { openURL, share } from "./external";
+export { LinkPreview, type LinkPreviewData, type LinkPreviewProps } from "./link-preview";

package/src/input.ts

@@ -0,0 +1,24 @@
+import { createElement, useState } from "./react";
+
+export function TextInput(props: {
+  value: string;
+  onChange: (value: string) => void;
+  onSubmit?: (value: string) => void;
+  placeholder?: string;
+  autoFocus?: boolean;
+  action?: "return" | "search" | "done";
+  inputMode?: "text" | "numeric";
+  prefix?: string;
+  suffix?: string;
+}) {
+  const [eventCount, setEventCount] = useState(0);
+  const nativeProps = {
+    ...props,
+    eventCount,
+    onChange(value: string, count: number) {
+      setEventCount(count);
+      props.onChange(value);
+    },
+  };
+  return createElement("TextInput", nativeProps);
+}

package/src/link-preview.ts

@@ -0,0 +1,29 @@
+import { createElement } from "./react";
+import { Image, Stack, Text } from "./index";
+import { openLink } from "./external";
+
+export type LinkPreviewData = {
+  url: string;
+  title?: string;
+  image?: { src: string; width: number; height: number };
+  icon?: string;
+};
+
+export type LinkPreviewProps = LinkPreviewData & {
+  onPress?: () => void;
+  onLongPress?: () => void;
+};
+
+export function LinkPreview({ url, title, image, icon, onPress, onLongPress }: LinkPreviewProps) {
+  const domain = url.replace(/^https?:\/\/(?:www\.)?/, "").split(/[/?#]/, 1)[0];
+  return createElement("Pressable", { onPress: onPress ?? (() => openLink(url)), onLongPress },
+    createElement("LinkPreview", null,
+      image && createElement(Image, {
+        src: image.src, width: 220, height: 220 * image.height / image.width, fit: "cover",
+      }),
+      createElement(Stack, { gap: 4, align: "stretch" },
+        title && createElement(Text, { size: 16, maxLines: 2 }, title),
+        createElement(Stack, { axis: "horizontal", gap: 8, align: "center" },
+          icon && createElement(Image, { src: icon, width: 16, height: 16, fit: "contain" }),
+          createElement(Text, { size: 13, maxLines: 1 }, domain)))));
+}

package/src/links.ts

@@ -0,0 +1,13 @@
+import { LinkifyIt } from "linkify-it";
+
+let linkify: LinkifyIt | undefined;
+
+export function textLinks(text: string) {
+  linkify ??= new LinkifyIt({ fuzzyLink: true });
+  return (linkify.match(text) || []).map(match => ({
+    start: match.index,
+    end: match.lastIndex,
+    url: !match.schema
+      ? match.url.replace(/^http:/, "https:") : match.url,
+  }));
+}

package/src/list-patch.ts

@@ -0,0 +1,14 @@
+export type NativeListItem = { key: string; values: unknown; measurementKey: string | number | null };
+type Patch = { previous: NativeListItem[]; changes: NativeListItem[]; keys?: string[] };
+
+const patches = new WeakMap<NativeListItem[], Patch>();
+
+export function rememberListPatch(items: NativeListItem[], patch: Patch) {
+  patches.set(items, patch);
+}
+
+export function listPatch(previous: NativeListItem[], items: NativeListItem[]) {
+  const patch = patches.get(items);
+  patches.delete(items);
+  return patch?.previous === previous ? patch : undefined;
+}

package/src/list.ts

@@ -0,0 +1,134 @@
+import { createElement, Fragment, useContext, useEffect, useLayoutEffect, useRef, useState, type ReactNode } from "./react";
+
+import { useAction } from "./action";
+import { Button, Stack, Text } from "./index";
+import { CompiledList, nativeListPlan } from "./native-list";
+import { ScrollToEndContext } from "./scroll";
+
+const OLDER_PAGE_AHEAD_ITEMS = 8;
+
+export function ListLoadError({ message, onRetry }: { message: string; onRetry: () => void }) {
+  return createElement(Stack, { gap: 24 },
+    createElement(Text, { size: 18 }, message),
+    createElement(Button, { onPress: onRetry }, "Try again"),
+  );
+}
+
+export type ListProps<T> = {
+  items: readonly T[];
+  keyExtractor: (item: T, index: number) => string;
+  renderItem: (item: T, index: number) => ReactNode;
+  gap?: number;
+  followEnd?: boolean;
+  measurementKey?: string | number;
+  onLoadMore?: () => Promise<void>;
+  hasMore?: boolean;
+  onLoadOlder?: () => Promise<void>;
+  hasOlder?: boolean;
+  initialPosition?: "start" | "end";
+};
+
+export function List<T>(props: ListProps<T>) {
+  const requestEnd = useContext(ScrollToEndContext);
+  const initialised = useRef(false);
+  useLayoutEffect(() => {
+    if (initialised.current || props.initialPosition === "end" && !props.items.length) return;
+    initialised.current = true;
+    if (props.initialPosition === "end") requestEnd?.();
+  }, [props.initialPosition, props.items.length, requestEnd]);
+  const plan = nativeListPlan(props.renderItem);
+  return plan ? createElement(CompiledList<T>, { ...props, plan, key: plan.template }) : createElement(ReactList<T>, props);
+}
+
+export function ReactList<T>({ items, keyExtractor, renderItem, gap = 47, followEnd = false, measurementKey, onLoadMore, hasMore = false, onLoadOlder, hasOlder = false, initialPosition = "start" }: ListProps<T>) {
+  if (!Number.isFinite(gap) || gap < 0) {
+    throw new Error("List gap must be finite and non-negative");
+  }
+  const initialWindow = useRef(initialPosition === "end");
+  const previous = useRef<{
+    measurementKey?: string | number;
+    keyExtractor: ListProps<T>["keyExtractor"];
+    items: readonly T[]; keys: string[]; contentVersions: number[]; revision: number;
+    records: Map<string, { item: T; version: number }>;
+  } | null>(null);
+  const [window, setWindow] = useState({ start: initialPosition === "end" ? Math.max(0, items.length - 32) : 0, end: initialPosition === "end" ? items.length : 32, revision: 0, nearEnd: false });
+  const requested = useRef<string | null>(null);
+  const load = useAction(() => onLoadMore?.());
+  const olderRequested = useRef<string | null>(null);
+  const older = useAction(() => onLoadOlder?.());
+  let start = Math.min(window.start, items.length);
+  let end = Math.min(window.end, items.length);
+  if (initialWindow.current && items.length) {
+    start = Math.max(0, items.length - 32);
+    end = items.length;
+  }
+  let data = previous.current;
+  const old = data;
+  const keys = old && old.items === items && old.keyExtractor === keyExtractor ? old.keys : items.map(keyExtractor);
+  if (keys !== old?.keys && (keys.some(key => typeof key !== "string") || new Set(keys).size !== keys.length)) {
+    throw new Error("List keys must be unique strings");
+  }
+  const keysChanged = old && keys !== old.keys && (keys.length !== old.keys.length || keys.some((key, i) => key !== old.keys[i]));
+  if (!data || data.items !== items || data.measurementKey !== measurementKey || keysChanged) {
+    const revision = (old?.revision ?? 0) + 1;
+    const records = new Map(keys.map((key, index) => {
+      const oldRecord = old?.records.get(key);
+      return [key, { item: items[index], version: oldRecord && old?.measurementKey === measurementKey && Object.is(oldRecord.item, items[index]) ? oldRecord.version : revision }];
+    }));
+    const contentVersions = Array.from(records.values(), record => record.version);
+    if (new TextEncoder().encode(JSON.stringify({ keys, contentVersions })).length > 128 * 1024) {
+      throw new Error("List metadata exceeds 128 KiB; use shorter keys or a bounded data window");
+    }
+    if (initialWindow.current && items.length) {
+      if (start !== window.start || end !== window.end) setWindow({ start, end, revision, nearEnd: false });
+    } else if (old && window.revision !== revision && old.keys[window.start] !== undefined) {
+      const mapped = keys.indexOf(old.keys[window.start]);
+      start = mapped < 0 ? Math.min(window.start, Math.max(0, items.length - 1)) : mapped;
+      end = Math.min(start + window.end - window.start, items.length);
+      if (start !== window.start || end !== window.end) setWindow({ start, end, revision, nearEnd: false });
+    }
+    data = { items, keys, keyExtractor, contentVersions, revision, records, measurementKey };
+  }
+  if (data.keyExtractor !== keyExtractor) data = { ...data, keyExtractor };
+  useLayoutEffect(() => {
+    previous.current = data;
+    if (items.length) initialWindow.current = false;
+  });
+  const { revision, contentVersions } = data;
+  const boundary = JSON.stringify([keys.length, keys.at(-1)]);
+  useEffect(() => {
+    if (!onLoadMore || !hasMore || load.status === "pending" || load.status === "error"
+      || window.revision !== revision || !window.nearEnd || requested.current === boundary) return;
+    requested.current = boundary;
+    load.run();
+  }, [onLoadMore, hasMore, load.status, load.run, window, revision, boundary]);
+  const firstBoundary = JSON.stringify([keys.length, keys[0]]);
+  useEffect(() => {
+    if (!onLoadOlder || !hasOlder || older.status === "pending" || older.status === "error"
+      || window.revision !== revision || window.start > OLDER_PAGE_AHEAD_ITEMS || olderRequested.current === firstBoundary) return;
+    olderRequested.current = firstBoundary;
+    older.run();
+  }, [onLoadOlder, hasOlder, older.status, older.run, window, revision, firstBoundary]);
+  const children: ReactNode[] = [];
+  for (let index = start; index < end; index++) {
+    children.push(createElement("Stack", { key: keys[index], axis: "vertical", align: "stretch" }, renderItem(items[index], index)));
+  }
+  const props = {
+    keys: data.keys,
+    contentVersions,
+    revision,
+    gap,
+    followEnd,
+    start,
+    onWindow(start: number, end: number, eventRevision: number, nearEnd: boolean) {
+      if (eventRevision !== revision) return;
+      setWindow(previous => previous.start === start && previous.end === end && previous.revision === eventRevision && previous.nearEnd === nearEnd ? previous : { start, end, revision: eventRevision, nearEnd });
+    },
+  };
+  const list = createElement("List", props, children);
+  return createElement(Fragment, null,
+    older.status === "error" && createElement(ListLoadError, { message: older.error.message, onRetry: older.run }),
+    list,
+    load.status === "error" && createElement(ListLoadError, { message: load.error.message, onRetry: load.run }),
+  );
+}

package/src/native-list.ts

@@ -0,0 +1,248 @@
+import { createElement, Fragment, useLayoutEffect, useMemo, useRef, type ComponentProps, type ReactNode } from "./react";
+import { ListLoadError, ReactList, type ListProps } from "./list";
+import { useAction } from "./action";
+import type { Row } from "./image";
+import { pressHandler } from "./press";
+import { rememberListPatch, type NativeListItem } from "./list-patch";
+
+type Captured = { value: unknown; prototype?: object | null; fields?: [PropertyKey, boolean, Captured][] };
+type Scope = { identity: string; values: readonly Captured[] };
+type Capture = { identity: string; values: () => readonly unknown[]; usesIndex?: boolean };
+type Plan<T> = { project: (item: T, index: number) => unknown[]; template: string; scope?: Capture };
+const needsReact = /* @__PURE__ */ Symbol("list needs React");
+const plans = /* @__PURE__ */ new WeakMap<Function, Plan<unknown>>();
+const keys = /* @__PURE__ */ new WeakMap<Function, string>();
+const plainRecords = /* @__PURE__ */ new WeakSet<object>();
+declare const __inkIsProxy: (value: unknown) => boolean;
+const isProxy = typeof __inkIsProxy === "function" ? __inkIsProxy : undefined;
+
+function bareFunctionPrototype(value: unknown, owner: Function): value is object {
+  if (value === null || typeof value !== "object" || isProxy?.(value)) return false;
+  if (Object.getPrototypeOf(value) !== Object.prototype || Reflect.ownKeys(value).length !== 1) return false;
+  const constructor = Object.getOwnPropertyDescriptor(value, "constructor");
+  return !!constructor && "value" in constructor && constructor.value === owner;
+}
+
+function plainData(value: unknown, cache = plainRecords, visiting = new Set<object>()): boolean {
+  if (value === null || typeof value !== "object" && typeof value !== "function") return true;
+  if (cache.has(value)) return true;
+  if (isProxy?.(value)) return false;
+  if (visiting.has(value) || visiting.size >= 64) return false;
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== null && prototype !== Object.prototype && prototype !== Array.prototype
+    && !(typeof value === "function" && prototype === Function.prototype)) return false;
+  visiting.add(value);
+  const properties: Record<PropertyKey, PropertyDescriptor> = Object.getOwnPropertyDescriptors(value);
+  const plain = Reflect.ownKeys(properties).every(key => {
+    const property = properties[key];
+    if (!("value" in property)) return false;
+    if (["toString", "valueOf", Symbol.toPrimitive].includes(key) && typeof property.value === "function") return false;
+    if (key === "prototype" && typeof value === "function" && bareFunctionPrototype(property.value, value)) return true;
+    return plainData(property.value, cache, visiting);
+  });
+  visiting.delete(value);
+  if (plain && isProxy) cache.add(value);
+  return plain;
+}
+
+/** @internal A compiler-proven field extractor has no captured state. */
+export function nativeListKey<T>(extract: (item: T, index: number) => string, identity: string) {
+  keys.set(extract, identity);
+  return extract;
+}
+
+/** @internal Created by the Ink compiler; application List props stay unchanged. */
+export function nativeListRow<T>(render: (item: T, index: number) => ReactNode, project: Plan<T>["project"], template: string, scope?: Capture) {
+  plans.set(render, { project: project as Plan<unknown>["project"], template, scope });
+  return render;
+}
+
+/** @internal Match React's primitive text children without invoking components. */
+export function listText(parts: unknown[]): string {
+  return parts.map(value => {
+    if (value == null || typeof value === "boolean") return "";
+    if (Array.isArray(value)) return listText(value);
+    if (!["string", "number", "bigint"].includes(typeof value)) throw needsReact;
+    return String(value);
+  }).join("");
+}
+
+/** @internal The same presentation fields as Ink's stateless Row component. */
+export function listRowFields(props: ComponentProps<typeof Row>) {
+  return { image: props.image, title: props.title, titleMaxLines: props.titleMaxLines,
+    titleIcon: props.titleIcon, subtitle: props.subtitle, subtitleIcon: props.subtitleIcon,
+    onLongPress: props.onLongPress,
+    onPress: pressHandler(props) ?? (props.onLongPress ? () => {} : undefined) };
+}
+
+function nativeValue(value: unknown, previous?: unknown): unknown {
+  if (typeof value === "function") return true;
+  if (value == null) return null;
+  if (Array.isArray(value)) {
+    const before = Array.isArray(previous) ? previous : [];
+    const next = value.map((item, index) => nativeValue(item, before[index]));
+    return before.length === next.length && next.every((item, index) => Object.is(item, before[index])) ? before : next;
+  }
+  if (typeof value === "object") {
+    const before = previous !== null && typeof previous === "object" && !Array.isArray(previous)
+      ? previous as Record<string, unknown> : {};
+    const next: Record<string, unknown> = {};
+    let unchanged = true;
+    for (const key of Object.keys(value)) {
+      const item = nativeValue(Reflect.get(value, key), before[key]);
+      next[key] = item;
+      if (!Object.hasOwn(before, key) || !Object.is(item, before[key])) unchanged = false;
+    }
+    return unchanged && Object.keys(next).length === Object.keys(before).length ? before : next;
+  }
+  return value;
+}
+
+type NativeItem = NativeListItem;
+type RowRecord<T> = { item: T; index: number; native: NativeItem };
+type Records<T> = { data: NativeItem[]; rows: Map<string, RowRecord<T>>; template: string;
+  items: readonly T[]; key: string | Function; measurementKey?: string | number; scope?: Scope };
+
+function captureValue(value: unknown, cache: WeakMap<object, Captured>): Captured {
+  if (value === null || typeof value !== "object" && typeof value !== "function") return { value };
+  const previous = cache.get(value);
+  if (previous) return previous;
+  const properties: Record<PropertyKey, PropertyDescriptor> = Object.getOwnPropertyDescriptors(value);
+  const captured: Captured = { value, prototype: Object.getPrototypeOf(value), fields: Reflect.ownKeys(properties).map(key => {
+    const property = properties[key];
+    const field = key === "prototype" && typeof value === "function" && bareFunctionPrototype(property.value, value)
+      ? { value: property.value } : captureValue(property.value, cache);
+    return [key, !!property.enumerable, field];
+  }) };
+  cache.set(value, captured);
+  return captured;
+}
+
+function sameCapture(before: Captured, after: Captured, seen: WeakMap<Captured, Captured>): boolean {
+  // Other JS hosts cannot establish that an object has no Proxy traps.
+  if (before.value !== null && (typeof before.value === "object" || typeof before.value === "function") && !isProxy) return false;
+  if (!Object.is(before.value, after.value) || before.prototype !== after.prototype) return false;
+  const previous = before.fields, current = after.fields;
+  if (!previous || !current) return previous === current;
+  if (seen.get(before) === after) return true;
+  seen.set(before, after);
+  return previous.length === current.length && current.every(([key, enumerable, value], index) =>
+    key === previous[index][0] && enumerable === previous[index][1] && sameCapture(previous[index][2], value, seen));
+}
+
+function sameScopeValues(before: readonly Captured[], after: readonly Captured[]): boolean {
+  const seen = new WeakMap<Captured, Captured>();
+  return before.length === after.length && after.every((value, index) => sameCapture(before[index], value, seen));
+}
+
+export function nativeListPlan<T>(render: ListProps<T>["renderItem"]): Plan<T> | undefined {
+  return plans.get(render) as Plan<T> | undefined;
+}
+
+export function CompiledList<T>({ plan, ...props }: ListProps<T> & { plan: Plan<T> }) {
+  const { items, keyExtractor, gap = 47, followEnd, initialPosition, measurementKey, onLoadMore, onLoadOlder, hasMore = false, hasOlder = false } = props;
+  if (!Number.isFinite(gap) || gap < 0) throw new Error("List gap must be finite and non-negative");
+  const load = useAction(() => onLoadMore?.());
+  const older = useAction(() => onLoadOlder?.());
+  const committed = useRef<Records<T> | null>(null);
+  const records = useMemo(() => {
+    const previous = committed.current;
+    const keyIdentity = keys.get(keyExtractor) ?? keyExtractor;
+    const captured = plan.scope && (items.length ? plan.scope.values() : []);
+    if (captured && !captured.every(value => plainData(value, new WeakSet()))) return null;
+    const snapshots = new WeakMap<object, Captured>();
+    const scope = plan.scope && { identity: plan.scope.identity, values: captured?.map(value => captureValue(value, snapshots)) ?? [] };
+    const sameScope = scope && previous?.scope?.identity === scope.identity && sameScopeValues(previous.scope.values, scope.values);
+    if (previous && previous.items === items && previous.key === keyIdentity
+      && previous.template === plan.template && previous.measurementKey === measurementKey
+      && sameScope) return previous;
+    const rows = new Map<string, RowRecord<T>>();
+    let unchanged = items.length === previous?.data.length;
+    let reordered = !unchanged;
+    const changes: NativeItem[] = [];
+    let data;
+    try {
+      if (!items.every(item => plainData(item))) throw needsReact;
+      data = items.map((item, index) => {
+        const key = typeof keyIdentity === "string" && previous?.key === keyIdentity && previous.items[index] === item
+          ? previous.data[index].key : keyExtractor(item, index);
+        if (typeof key !== "string" || rows.has(key)) throw new Error("List keys must be unique strings");
+        const beforeRow = previous?.template === plan.template ? previous.rows.get(key) : undefined;
+        const before = beforeRow?.native;
+        const projected = beforeRow && sameScope && beforeRow.item === item
+          && (beforeRow.index === index || plan.scope?.usesIndex === false)
+          ? beforeRow.native.values : nativeValue(plan.project(item, index), before?.values);
+        const measurement = measurementKey ?? null;
+        const record = before && before.values === projected && before.measurementKey === measurement
+          ? before : { key, values: projected, measurementKey: measurement };
+        rows.set(key, { item, index, native: record });
+        if (record !== previous?.data[index]) {
+          unchanged = false;
+          if (record !== before) changes.push(record);
+          if (key !== previous?.data[index]?.key) reordered = true;
+        }
+        return record;
+      });
+    } catch (error) {
+      if (error !== needsReact) throw error;
+      return null;
+    }
+    if (unchanged && previous) data = previous.data;
+    else if (previous) rememberListPatch(data, { previous: previous.data, changes,
+      ...(reordered ? { keys: data.map(item => item.key) } : {}) });
+    return { data, rows, template: plan.template, items, key: keyIdentity, measurementKey, scope };
+  }, [items, keyExtractor, plan, measurementKey]);
+  useLayoutEffect(() => { committed.current = records; }, [records]);
+  const targets = useMemo(() => {
+    type Template = { id: number; props: Record<string, unknown>; children: Template[] };
+    const targets = new Map<number, Record<string, (string | number)[]>>();
+    const visit = (node: Template) => {
+      const events: Record<string, (string | number)[]> = {};
+      for (const [name, value] of Object.entries(node.props)) {
+        if (name.startsWith("on") && typeof value === "object" && value !== null && "path" in value) {
+          const path = value.path;
+          if (Array.isArray(path) && path.every(part => typeof part === "string" || typeof part === "number")) events[name] = path.slice(1);
+        }
+      }
+      targets.set(node.id, events);
+      node.children.forEach(visit);
+    };
+    visit(JSON.parse(plan.template) as Template);
+    return targets;
+  }, [plan.template]);
+  if (!records) return createElement(ReactList<T>, props);
+  const nativeProps = {
+    items: records.data, keyField: "key", template: plan.template, gap, followEnd, initialEnd: initialPosition === "end",
+    hasMore: hasMore && load.status !== "pending" && load.status !== "error",
+    hasOlder: hasOlder && older.status !== "pending" && older.status !== "error",
+    onEndReached: onLoadMore ? load.run : undefined,
+    onStartReached: onLoadOlder ? older.run : undefined,
+    onRowEvent(key: string, target: number, name: string, ...args: unknown[]) {
+      const path = targets.get(target)?.[name];
+      const row = records.rows.get(key);
+      let callback: unknown = row && path ? plan.project(row.item, row.index) : undefined;
+      for (const part of path ?? []) {
+        callback = callback != null && typeof callback === "object" ? Reflect.get(callback, part) : undefined;
+      }
+      if (path && typeof callback === "function") callback(...args);
+    },
+  };
+  return createElement(Fragment, null,
+    older.status === "error" && createElement(ListLoadError, { message: older.error.message, onRetry: older.run }),
+    createElement("NativeList", nativeProps),
+    load.status === "error" && createElement(ListLoadError, { message: load.error.message, onRetry: load.run }),
+  );
+}
+
+/** @internal Fixed native descriptions for Ink's own list components. */
+export function nativeListTemplate(build: (
+  node: (type: string, props: Record<string, unknown>, children?: NativeRowNode[]) => NativeRowNode,
+  field: (...path: (string | number)[]) => unknown,
+) => NativeRowNode): string {
+  let next = 1;
+  return JSON.stringify({ id: 0, type: "Stack", props: { gap: 0, align: "stretch" }, children: [build(
+    (type, props, children = []) => ({ id: next++, type, props, children }),
+    (...path) => ({ $value: 0, path: ["values", 0, ...path] }),
+  )] });
+}
+type NativeRowNode = { id: number; type: string; props: Record<string, unknown>; children: NativeRowNode[] };