ink-framework 0.1.0-alpha.10 → 0.1.0-alpha.12

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "ink-framework",
-  "version": "0.1.0-alpha.10",
+  "version": "0.1.0-alpha.12",
   "types": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
     "./renderer": "./src/renderer.ts",
     "./internal/list": "./src/native-list.ts",
+    "./internal/data": "./src/data-views.ts",
     "./internal/playback": "./src/playback-binding.ts",
     "./native": "./src/native.ts",
     "./native/controller": "./src/controller.ts",

package/src/canvas.ts

@@ -15,10 +15,69 @@ export function Rectangle(props: Bounds & {
   onPress?: () => void;
   onLongPress?: () => void;
   onDragEnter?: () => void;
+  onDragStart?: () => void;
+  onDragEnd?: () => void;
+  haptic?: boolean;
 }) {
   return createElement("CanvasRectangle", props);
 }
 
+/** Native-owned horizontal selection. Remount to reset its initial position. */
+export function CanvasRange({
+  total, span, initialStart, step = 1, snapPoints = [], snapDistance = 6, tapSnapDistance = 10, hitSlop = 10,
+  minDragWidth = 0, inset = 4, innerFill = "#666666", dragOnly = false, snapOnTap = false, progress = 0,
+  progressDurationMs = 0, progressPlaying = false, progressLoop = false, progressFill = "#FFFFFF", ...props
+}: Bounds & {
+  total: number;
+  span: number;
+  initialStart: number;
+  step?: number;
+  snapPoints?: readonly number[];
+  /** Distances and inset use Canvas logical units. Drag release distance is 1.5× entry. */
+  snapDistance?: number;
+  tapSnapDistance?: number;
+  hitSlop?: number;
+  /** Minimum selection drag target width; does not change drawing or tap-to-seek. */
+  minDragWidth?: number;
+  inset?: number;
+  fill?: string;
+  innerFill?: string;
+  /** Move only by dragging the selection; taps inside emit a relative seek. */
+  dragOnly?: boolean;
+  /** In drag-only mode, marker taps move the selection before considering a seek. */
+  snapOnTap?: boolean;
+  /** Playback fraction inside the selection, from zero to one. */
+  progress?: number;
+  /** Enables native playback interpolation; zero keeps progress static. */
+  progressDurationMs?: number;
+  /** Actual playback advancement, false while paused or buffering. */
+  progressPlaying?: boolean;
+  progressLoop?: boolean;
+  progressFill?: string;
+  onRangeSeek?: (position: number) => void;
+  onRangeStart?: () => void;
+  onRangeCommit?: (start: number) => void;
+  /** FIFO snapshot before another press or Back; never emitted for movement. */
+  onRangeSnapshot?: (start: number) => void;
+}) {
+  return createElement("CanvasRectangle", {
+    ...props,
+    range: {
+      total, span, initialStart, step, snapPoints, snapDistance, tapSnapDistance, hitSlop, minDragWidth, inset,
+      innerFill, dragOnly, snapOnTap, progress, progressDurationMs, progressPlaying, progressLoop, progressFill,
+    },
+  });
+}
+
+/** A line through points in canvas units, with round ends and joins. Paths draw above the canvas's rectangles and text. */
+export function CanvasPath({ points, ...props }: {
+  points: readonly (readonly [x: number, y: number])[];
+  stroke?: string;
+  strokeWidth?: number;
+}) {
+  return createElement("CanvasPath", { ...props, points: points.flat() });
+}
+
 export function CanvasText({ children, ...props }: Bounds & {
   children: string | number;
   size?: number;

package/src/data-views.ts

@@ -0,0 +1,249 @@
+type IntrinsicCalls = {
+  filter<T>(items: readonly T[], predicate: (item: T, index: number) => boolean): T[];
+  sort<T>(items: T[], compare: (a: T, b: T) => number): T[];
+  map<T, U>(items: readonly T[], transform: (item: T, index: number) => U): U[];
+  lower(text: string): string;
+  includes(text: string, query: string): boolean;
+  localeCompare(a: string, b: string): number;
+  dateParse(value: unknown): number;
+  jsonParse(source: string, reviver: (this: object, key: string, value: unknown) => unknown): unknown;
+  weakMapGet<T>(map: WeakMap<object, T>, key: object): T | undefined;
+  weakMapSet<T>(map: WeakMap<object, T>, key: object, value: T): unknown;
+  mapGet<K, V>(map: Map<K, V>, key: K): V | undefined;
+  mapSet<K, V>(map: Map<K, V>, key: K, value: V): unknown;
+};
+
+type Intrinsics = {
+  WeakMap: WeakMapConstructor;
+  Map: MapConstructor;
+  calls?: IntrinsicCalls;
+  setTimeout?: (callback: () => void, delay: number) => number;
+  clearTimeout?: (timer: number) => void;
+};
+
+declare const __inkDataIntrinsics: Intrinsics | undefined;
+declare const __inkDataFields: ((items: unknown, fields: readonly string[], previous: readonly unknown[] | undefined,
+  mode: "search" | "sort") => readonly unknown[] | undefined) | undefined;
+declare const __inkDataSearch: ((items: unknown, fields: readonly string[], previousSnapshot: readonly unknown[] | undefined,
+  previousText: readonly string[] | undefined, separator: string | null, query?: () => unknown,
+  queryLower?: boolean) => (SearchCache & { items?: unknown[]; needle?: string }) | undefined) | undefined;
+declare const __inkPrepareDataSearch: ((items: unknown, fields: readonly string[], separator: string | null,
+  cursor: SearchCursor | undefined, limit: number) => SearchCursor | null | undefined) | undefined;
+
+const intrinsics = typeof __inkDataIntrinsics === "undefined" ? undefined : __inkDataIntrinsics;
+const calls = intrinsics?.calls;
+const snapshotFields = typeof __inkDataFields === "function" ? __inkDataFields : undefined;
+const prepareSearch = typeof __inkDataSearch === "function" ? __inkDataSearch : undefined;
+const warmSearch = typeof __inkPrepareDataSearch === "function" ? __inkPrepareDataSearch : undefined;
+const schedule = intrinsics?.setTimeout;
+const unschedule = intrinsics?.clearTimeout;
+
+type RawPlan = { fields: unknown; separator: unknown; queryLower: unknown; date: unknown; direction: unknown; tie: unknown };
+type SearchCache = { snapshot: readonly unknown[]; text: readonly string[] };
+interface CachedSearch extends SearchCache { changes: number }
+type SearchCursor = SearchCache & { offset: number; complete: boolean };
+type SearchJob = { items: object | undefined; cursor: SearchCursor | undefined; timer: number | undefined };
+type SearchPlan = {
+  fields: readonly string[];
+  separator: string | null;
+  queryLower: boolean;
+  cache: WeakMap<object, CachedSearch | undefined>;
+  seen: WeakMap<object, boolean>;
+  job: SearchJob | undefined;
+  retained: boolean;
+  next: SearchPlan | undefined;
+};
+type SortPlan = { fields: readonly string[]; direction: 1 | -1; tie: boolean };
+type SortEntry<T> = { item: T; date: number; tie: string };
+
+// Plans are compiler literals. Bound retained plans as well as keeping source arrays weak.
+const maximumPlans = 64;
+let searches: Map<string, SearchPlan> | undefined;
+let searchCount = 0;
+let searchHead: SearchPlan | undefined;
+let sorts: Map<string, SortPlan> | undefined;
+let sortCount = 0;
+
+function parsePlan(source: string): RawPlan | undefined {
+  const i = intrinsics!;
+  const records = new i.WeakMap<object, RawPlan>();
+  try {
+    // Collect only JSON's own members, including when Object.prototype has acquired getters.
+    const parsed = calls!.jsonParse(source, function(this: object, key: string, value: unknown) {
+      if (key === "fields" || key === "separator" || key === "queryLower" || key === "date" || key === "direction" || key === "tie") {
+        let record = calls!.weakMapGet(records, this);
+        if (!record) {
+          record = { fields: undefined, separator: undefined, queryLower: undefined, date: undefined, direction: undefined, tie: undefined };
+          calls!.weakMapSet(records, this, record);
+        }
+        record[key] = value;
+      }
+      return value;
+    });
+    return parsed !== null && typeof parsed === "object"
+      ? calls!.weakMapGet(records, parsed) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function searchPlan(source: string): SearchPlan | undefined {
+  const i = intrinsics!;
+  const known = searches && calls!.mapGet(searches, source);
+  if (known) return known;
+  const raw = parsePlan(source);
+  if (!raw || raw.separator !== null && typeof raw.separator !== "string"
+    || raw.queryLower !== undefined && typeof raw.queryLower !== "boolean") return undefined;
+  // The native guard validates the fields array without invoking getters or Proxy traps.
+  const plan: SearchPlan = { fields: raw.fields as readonly string[], separator: raw.separator,
+    queryLower: raw.queryLower === true, cache: new i.WeakMap<object, CachedSearch | undefined>(),
+    seen: new i.WeakMap<object, boolean>(), job: undefined, retained: true, next: undefined };
+  if (!searches || searchCount === maximumPlans) {
+    while (searchHead) {
+      const evicted = searchHead;
+      searchHead = evicted.next;
+      evicted.next = undefined;
+      evicted.retained = false;
+      cancelSearch(evicted);
+    }
+    searches = new i.Map<string, SearchPlan>();
+    searchCount = 0;
+  }
+  calls!.mapSet(searches, source, plan);
+  plan.next = searchHead;
+  searchHead = plan;
+  searchCount++;
+  return plan;
+}
+
+function cancelSearch(plan: SearchPlan): void {
+  const job = plan.job;
+  if (!job) return;
+  plan.job = undefined;
+  const timer = job.timer;
+  job.items = undefined;
+  job.cursor = undefined;
+  job.timer = undefined;
+  if (timer !== undefined) {
+    try { unschedule!(timer); } catch { /* Cancellation has already invalidated the job. */ }
+  }
+}
+
+function disableSearch(plan: SearchPlan, items: object): void {
+  calls!.weakMapSet(plan.cache, items, undefined);
+  calls!.weakMapSet(plan.seen, items, false);
+}
+
+function warmLater(plan: SearchPlan, items: object): void {
+  if (!plan.retained || plan.job?.items === items) return;
+  cancelSearch(plan);
+  const job: SearchJob = { items, cursor: undefined, timer: undefined };
+  plan.job = job;
+  const step = () => {
+    if (plan.job !== job) return;
+    job.timer = undefined;
+    try {
+      const source = job.items!;
+      const cursor = warmSearch!(source, plan.fields, plan.separator, job.cursor, 128);
+      if (plan.job !== job) return;
+      if (!cursor) {
+        // Unsupported shapes stay on the original path. A shrinking source (null)
+        // and thrown background errors remain eligible for a later attempt.
+        if (cursor === undefined) calls!.weakMapSet(plan.seen, source, false);
+        cancelSearch(plan);
+      } else if (cursor.complete) {
+        calls!.weakMapSet(plan.cache, source, { snapshot: cursor.snapshot, text: cursor.text, changes: 0 });
+        cancelSearch(plan);
+      } else {
+        job.cursor = cursor;
+        job.timer = schedule!(step, 0);
+      }
+    } catch {
+      // Background work must never turn a successful original search into an error.
+      if (plan.job === job) cancelSearch(plan);
+    }
+  };
+  try { job.timer = schedule!(step, 0); } catch { cancelSearch(plan); }
+}
+
+function sortPlan(source: string): SortPlan | undefined {
+  const i = intrinsics!;
+  const known = sorts && calls!.mapGet(sorts, source);
+  if (known) return known;
+  const raw = parsePlan(source);
+  if (!raw || typeof raw.date !== "string" || raw.direction !== 1 && raw.direction !== -1
+    || raw.tie !== undefined && typeof raw.tie !== "string") return undefined;
+  const plan: SortPlan = { fields: typeof raw.tie === "string" ? [raw.date, raw.tie] : [raw.date],
+    direction: raw.direction, tie: typeof raw.tie === "string" };
+  if (!sorts || sortCount === maximumPlans) {
+    sorts = new i.Map<string, SortPlan>();
+    sortCount = 0;
+  }
+  calls!.mapSet(sorts, source, plan);
+  sortCount++;
+  return plan;
+}
+
+/** @internal The compiler supplies the original filter expression as the fallback. */
+export function compiledSearch<T>(items: readonly T[], source: string, query: () => unknown, fallback: (items: readonly T[]) => T[]): T[] {
+  if (!intrinsics || !calls || !prepareSearch || !warmSearch || !schedule || !unschedule) return fallback(items);
+  let plan: SearchPlan | undefined;
+  try { plan = searchPlan(source); } catch { return fallback(items); }
+  if (!plan) return fallback(items);
+  if (plan.job && plan.job.items !== items) cancelSearch(plan);
+  const before = calls.weakMapGet(plan.cache, items);
+  if (!before) {
+    const result = fallback(items);
+    if (items !== null && (typeof items === "object" || typeof items === "function")) {
+      try {
+        const seen = calls.weakMapGet(plan.seen, items);
+        if (seen === true) warmLater(plan, items);
+        else if (seen === undefined) calls.weakMapSet(plan.seen, items, true);
+      } catch { /* Retaining a warming candidate is optional. */ }
+    }
+    return result;
+  }
+  const prepared = prepareSearch(items, plan.fields, before.snapshot, before.text, plan.separator, query, plan.queryLower);
+  if (!prepared) {
+    disableSearch(plan, items);
+    return fallback(items);
+  }
+  // The native guard leaves queries unevaluated for rejected or empty sources.
+  let result: T[];
+  // The guard returns current own row values without converting them.
+  if (prepared.items) result = prepared.items as T[];
+  else if (typeof prepared.needle === "string") {
+    // A query can change descriptors or species after preparation. Use the
+    // original filter operation with the already evaluated query in that case.
+    const needle = prepared.needle;
+    result = calls.filter(items, (_item: T, index: number) => calls.includes(prepared.text[index], needle));
+  } else return fallback(items);
+  const changes = prepared.snapshot === before.snapshot ? 0 : before.changes + 1;
+  if (changes >= 2) disableSearch(plan, items);
+  else calls.weakMapSet(plan.cache, items, { snapshot: prepared.snapshot, text: prepared.text, changes });
+  return result;
+}
+
+/** @internal Sort date keys once per invocation while retaining Array.sort's source identity. */
+export function compiledSort<T>(items: T[], source: string, fallback: (items: T[]) => T[]): T[] {
+  if (!intrinsics || !calls || !snapshotFields) return fallback(items);
+  const plan = sortPlan(source);
+  if (!plan) return fallback(items);
+  const snapshot = snapshotFields(items, plan.fields, undefined, "sort");
+  if (!snapshot || items.length < 2) return fallback(items);
+  const width = plan.fields.length;
+  for (let offset = 0; offset < snapshot.length; offset += width) {
+    const date = snapshot[offset];
+    if (date !== null && typeof date === "object" || typeof date === "function" || typeof date === "symbol"
+      || plan.tie && typeof snapshot[offset + 1] !== "string") return fallback(items);
+  }
+  const entries = calls.map(items, (item: T, index: number): SortEntry<T> => ({ item,
+    date: calls.dateParse(snapshot[index * width] ?? "") || 0,
+    tie: plan.tie ? snapshot[index * width + 1] as string : "" }));
+  calls.sort(entries, (a: SortEntry<T>, b: SortEntry<T>) => {
+    const order = plan.direction * (a.date - b.date);
+    return order || (plan.tie ? calls.localeCompare(a.tie, b.tie) : 0);
+  });
+  for (let index = 0; index < entries.length; index++) items[index] = entries[index].item;
+  return items;
+}

package/src/image.ts

@@ -30,11 +30,25 @@ function RowComponent<const D extends Destination>({ image, title, titleMaxLines
 
 export const Row = /* @__PURE__ */ memo(RowComponent) as typeof RowComponent;
 
+export type ImageCrop = { zoom: number; x: number; y: number };
+export type ImageOverlay = { src: string; x: number; y: number; width: number; height: number };
+
 export function Image(props: {
   src: string;
   width: number;
   height: number;
   fit?: "contain" | "cover";
+  /** Clockwise quarter turns. Reuses one decoded texture across rotation and fit changes. */
+  rotation?: 0 | 90 | 180 | 270;
+  background?: string;
+  /** Normalised centre in the rotated source, with zoom relative to cover (1–4). */
+  crop?: ImageCrop;
+  /** Native gesture updates, delivered before subsequent press callbacks. */
+  onCropChange?: (crop: ImageCrop) => void;
+  /** Dashed horizontal guides at normalised frame positions (0–1), independent of crop. */
+  horizontalGuides?: readonly number[];
+  /** Transparent image in normalised frame coordinates, independent of crop and rotation. */
+  overlay?: ImageOverlay;
   bleed?: boolean;
   /** Fill the available content width, using width and height as the aspect ratio. */
   fillWidth?: boolean;

package/src/index.ts

@@ -21,7 +21,6 @@ export function Screen({ header, children, leftAction, rightAction, ...props }:
   centered?: boolean;
   wide?: boolean;
   bottomInset?: boolean;
-  waitForImages?: boolean;
   leftAction?: { icon: IconAsset; onPress: () => void };
   rightAction?: { icon: IconAsset; onPress: () => void };
 }) {
@@ -91,10 +90,11 @@ export function Button<const D extends Destination>(props: PressProps<D> & {
 }
 
 export { Row, Image, Avatar } from "./image";
-export { Canvas, Rectangle, CanvasText, CanvasIcon } from "./canvas";
+export { Canvas, Rectangle, CanvasPath, CanvasRange, CanvasText, CanvasIcon } from "./canvas";
 
 export function Field<const D extends Destination>(props: PressProps<D> & {
   label: string;
+  disabled?: boolean;
   children?: ReactNode;
 }) {
   const { href, url, onPress, ...rest } = props;

package/src/native-list.ts

@@ -1,4 +1,4 @@
-import { createElement, Fragment, useLayoutEffect, useMemo, useRef, type ComponentProps, type ReactNode } from "./react";
+import { createElement, Fragment, useLayoutEffect, useMemo, useRef, useState, type ComponentProps, type ReactNode } from "./react";
 import { ListLoadError, ReactList, type ListProps } from "./list";
 import { useAction } from "./action";
 import type { Row } from "./image";
@@ -15,6 +15,8 @@ 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;
+declare const __inkIsDenseArray: (value: unknown) => boolean;
+const isDenseArray = typeof __inkIsDenseArray === "function" ? __inkIsDenseArray : undefined;
 
 function bareFunctionPrototype(value: unknown, owner: Function): value is object {
   if (value === null || typeof value !== "object" || isProxy?.(value)) return false;
@@ -99,21 +101,73 @@ function nativeValue(value: unknown, previous?: unknown): unknown {
 }
 
 type NativeItem = NativeListItem;
-type RowRecord<T> = { item: T; index: number; native: NativeItem };
-type Records<T> = { data: NativeItem[]; rows: Map<string, RowRecord<T>>; template: string;
+type Records<T> = { data: NativeItem[]; positions: Map<string, number>; template: string;
   items: readonly T[]; key: string | Function; measurementKey?: string | number; scope?: Scope };
+const cooperativeListSize = 512;
+const preparationBudget = 4;
+const minimumPreparationRows = 32;
+const maximumPreparationRows = 128;
+type Preparation<T> = { steps: Generator<void, Records<T> | null>; result?: { value: Records<T> | null }; error?: { value: unknown } };
+type Request<T> = { items: readonly T[]; key: string | Function; plan: Plan<T>;
+  measurementKey?: string | number; scope?: Scope; preparation: Preparation<T>; synchronous?: { value: Records<T> | null };
+  eventPositions: Map<string, number | undefined> };
+type Prepared<T> = { request: Request<T>; generation: number } &
+  ({ status: "ready"; value: Records<T> | null } | { status: "error"; error: unknown });
 
-function captureValue(value: unknown, cache: WeakMap<object, Captured>): Captured {
+function listItem<T>(items: readonly T[], index: number): T {
+  const property = Object.getOwnPropertyDescriptor(items, index);
+  if (!property || !("value" in property)) throw needsReact;
+  return property.value;
+}
+
+/**
+ * Reproject only the items replaced in place, when every key stays at its position.
+ * Returns undefined when keys move, so the caller rebuilds the whole list.
+ */
+function* replaceInPlace<T>(previous: Records<T>, items: readonly T[], plan: Plan<T>,
+  keyExtractor: ListProps<T>["keyExtractor"], dense: boolean): Generator<void, Records<T> | undefined> {
+  let data: NativeItem[] | undefined;
+  const changes: NativeItem[] = [];
+  const length = items.length;
+  for (let index = 0; index < length; index++) {
+    const item = dense ? items[index] : listItem(items, index);
+    if (item === previous.items[index]) continue;
+    const before = previous.data[index];
+    if (!plainData(item)) throw needsReact;
+    if (keyExtractor(item, index) !== before.key) return undefined;
+    const projected = nativeValue(plan.project(item, index), before.values);
+    if (projected !== before.values) {
+      const record = { key: before.key, values: projected, measurementKey: before.measurementKey };
+      (data ??= previous.data.slice())[index] = record;
+      changes.push(record);
+    }
+    yield;
+  }
+  if (data) rememberListPatch(data, { previous: previous.data, changes });
+  return { ...previous, data: data ?? previous.data, items };
+}
+
+function captureValue(value: unknown, cache: WeakMap<object, Captured>, visiting = new Set<object>()): Captured {
   if (value === null || typeof value !== "object" && typeof value !== "function") return { value };
   const previous = cache.get(value);
-  if (previous) return previous;
+  if (previous && isProxy) return previous;
+  if (isProxy?.(value) || visiting.has(value) || visiting.size >= 64) throw needsReact;
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== null && prototype !== Object.prototype && prototype !== Array.prototype
+    && !(typeof value === "function" && prototype === Function.prototype)) throw needsReact;
+  visiting.add(value);
   const properties: Record<PropertyKey, PropertyDescriptor> = Object.getOwnPropertyDescriptors(value);
-  const captured: Captured = { value, prototype: Object.getPrototypeOf(value), fields: Reflect.ownKeys(properties).map(key => {
+  const fields: NonNullable<Captured["fields"]> = [];
+  for (const key of Reflect.ownKeys(properties)) {
     const property = properties[key];
+    if (!("value" in property)) throw needsReact;
+    if (["toString", "valueOf", Symbol.toPrimitive].includes(key) && typeof property.value === "function") throw needsReact;
     const field = key === "prototype" && typeof value === "function" && bareFunctionPrototype(property.value, value)
-      ? { value: property.value } : captureValue(property.value, cache);
-    return [key, !!property.enumerable, field];
-  }) };
+      ? { value: property.value } : captureValue(property.value, cache, visiting);
+    fields.push([key, !!property.enumerable, field]);
+  }
+  visiting.delete(value);
+  const captured: Captured = { value, prototype, fields };
   cache.set(value, captured);
   return captured;
 }
@@ -135,6 +189,99 @@ function sameScopeValues(before: readonly Captured[], after: readonly Captured[]
   return before.length === after.length && after.every((value, index) => sameCapture(before[index], value, seen));
 }
 
+function captureScope<T>(plan: Plan<T>, items: readonly T[]): Scope | undefined {
+  if (!plan.scope) return;
+  const captured = items.length ? plan.scope.values() : [];
+  // Captures can mutate between slices; validate each fresh snapshot without the row cache.
+  return { identity: plan.scope.identity, values: captured.map(value => captureValue(value, new WeakMap())) };
+}
+
+function sameScope(before?: Scope, after?: Scope): boolean {
+  return !!before && !!after && before.identity === after.identity && sameScopeValues(before.values, after.values);
+}
+
+function capturesMatch<T>(request: Request<T>, latestPlan: Plan<T> | null): boolean {
+  return !!latestPlan && sameScope(request.scope, captureScope(request.plan, request.items))
+    && (latestPlan === request.plan || sameScope(request.scope, captureScope(latestPlan, request.items)));
+}
+
+function* prepareRecords<T>(previous: Records<T> | null, items: readonly T[], plan: Plan<T>,
+  keyExtractor: ListProps<T>["keyExtractor"], keyIdentity: string | Function,
+  measurementKey: string | number | undefined, scope: Scope | undefined, dense: boolean): Generator<void, Records<T> | null> {
+  try {
+    if (isProxy?.(items) || Object.getPrototypeOf(items) !== Array.prototype) throw needsReact;
+    const length = items.length;
+    const unchangedScope = sameScope(previous?.scope, scope);
+    if (previous && previous.items === items && previous.key === keyIdentity
+      && previous.template === plan.template && previous.measurementKey === measurementKey
+      && unchangedScope) return previous;
+    if (previous && unchangedScope && typeof keyIdentity === "string" && previous.key === keyIdentity
+      && previous.template === plan.template && previous.measurementKey === measurementKey
+      && previous.items.length === length) {
+      const patched = yield* replaceInPlace(previous, items, plan, keyExtractor, dense);
+      if (patched !== undefined) return { ...patched, scope };
+    }
+    const positions = new Map<string, number>();
+    let unchanged = length === previous?.data.length;
+    let reordered = !unchanged;
+    const changes: NativeItem[] = [];
+    let data: NativeItem[] = [];
+    const itemKeys: string[] = [];
+    for (let index = 0; index < length; index++) {
+      const item = dense ? items[index] : listItem(items, index);
+      if (!plainData(item)) throw needsReact;
+      const key = typeof keyIdentity === "string" && previous?.key === keyIdentity && previous.items[index] === item
+        ? previous.data[index].key : keyExtractor(item, index);
+      if (typeof key !== "string" || positions.has(key)) throw new Error("List keys must be unique strings");
+      const beforeIndex = previous?.template === plan.template ? previous.positions.get(key) : undefined;
+      const before = previous && beforeIndex !== undefined ? previous.data[beforeIndex] : undefined;
+      const projected = previous && beforeIndex !== undefined && unchangedScope && previous.items[beforeIndex] === item
+        && (beforeIndex === index || plan.scope?.usesIndex === false)
+        ? previous.data[beforeIndex].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 };
+      positions.set(key, index);
+      itemKeys.push(key);
+      if (record !== previous?.data[index]) {
+        unchanged = false;
+        if (record !== before) changes.push(record);
+        if (key !== previous?.data[index]?.key) reordered = true;
+      }
+      data.push(record);
+      yield;
+    }
+    if (unchanged && previous) data = previous.data;
+    else if (previous) rememberListPatch(data, { previous: previous.data, changes,
+      ...(reordered ? { keys: itemKeys } : {}) });
+    return { data, positions, template: plan.template, items, key: keyIdentity, measurementKey, scope };
+  } catch (error) {
+    if (error !== needsReact) throw error;
+    return null;
+  }
+}
+
+function advancePreparation<T>(preparation: Preparation<T>, cooperative: boolean) {
+  if (preparation.result) return preparation.result;
+  if (preparation.error) throw preparation.error.value;
+  const started = cooperative ? performance.now() : 0;
+  let rows = 0;
+  while (true) {
+    let step;
+    try {
+      step = preparation.steps.next();
+    } catch (error) {
+      preparation.error = { value: error };
+      throw error;
+    }
+    if (step.done) return preparation.result = { value: step.value };
+    rows++;
+    // Identity-only sparse scans do not yield: a single replaced row stays synchronous.
+    if (cooperative && (rows >= maximumPreparationRows
+      || rows >= minimumPreparationRows && performance.now() - started >= preparationBudget)) return;
+  }
+}
+
 export function nativeListPlan<T>(render: ListProps<T>["renderItem"]): Plan<T> | undefined {
   return plans.get(render) as Plan<T> | undefined;
 }
@@ -145,54 +292,45 @@ export function CompiledList<T>({ plan, ...props }: ListProps<T> & { plan: Plan<
   const load = useAction(() => onLoadMore?.());
   const older = useAction(() => onLoadOlder?.());
   const committed = useRef<Records<T> | null>(null);
-  const records = useMemo(() => {
-    const previous = committed.current;
+  const committedRequest = useRef<Request<T> | null>(null);
+  const committedPlan = useRef<Plan<T> | null>(null);
+  const generation = useRef(0);
+  const [prepared, setPrepared] = useState<Prepared<T> | null>(null);
+  const request = useMemo<Request<T>>(() => {
     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;
+    let scope: Scope | undefined;
     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;
-      });
+      scope = captureScope(plan, items);
     } catch (error) {
       if (error !== needsReact) throw error;
-      return null;
+      const preparation: Preparation<T> = { steps: (function* () { return null; })(), result: { value: null } };
+      return { items, key: keyIdentity, plan, measurementKey, preparation, synchronous: preparation.result, eventPositions: new Map() };
     }
-    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 };
+    const pending = committedRequest.current;
+    if (pending && pending.items === items && pending.key === keyIdentity
+      && pending.plan.template === plan.template && pending.measurementKey === measurementKey
+      && sameScope(pending.scope, scope)) return pending;
+    const previous = committed.current;
+    const dense = isDenseArray?.(items) ?? false;
+    const preparation: Preparation<T> = { steps: prepareRecords(previous, items, plan, keyExtractor, keyIdentity, measurementKey, scope, dense) };
+    // First population must exist when List's one-shot initialPosition effect scrolls its Screen.
+    const cooperative = !!isProxy && !!scope && typeof keyIdentity === "string"
+      && !!previous?.items.length && previous.template === plan.template && items.length >= cooperativeListSize;
+    const synchronous = advancePreparation(preparation, cooperative);
+    return { items, key: keyIdentity, plan, measurementKey, scope, preparation, synchronous, eventPositions: new Map() };
   }, [items, keyExtractor, plan, measurementKey]);
-  useLayoutEffect(() => { committed.current = records; }, [records]);
+  const outcome = prepared?.request === request && prepared.generation === generation.current ? prepared : undefined;
+  let records = outcome?.status === "ready" ? outcome.value
+    : request.synchronous ? request.synchronous.value : committed.current;
+  if (outcome?.status === "ready" && !request.synchronous) {
+    try {
+      if (!capturesMatch(request, committedPlan.current)) records = null;
+    } catch (error) {
+      if (error !== needsReact) throw error;
+      records = null;
+    }
+  }
+  const preparing = !request.synchronous && outcome?.status !== "ready";
   const targets = useMemo(() => {
     type Template = { id: number; props: Record<string, unknown>; children: Template[] };
     const targets = new Map<number, Record<string, (string | number)[]>>();
@@ -210,21 +348,88 @@ export function CompiledList<T>({ plan, ...props }: ListProps<T> & { plan: Plan<
     visit(JSON.parse(plan.template) as Template);
     return targets;
   }, [plan.template]);
+  const events = useRef<{
+    items: readonly T[]; keyExtractor: ListProps<T>["keyExtractor"]; plan: Plan<T>;
+    targets: typeof targets; positions: Map<string, number | undefined>;
+  } | null>(null);
+  useLayoutEffect(() => {
+    committed.current = records;
+    committedRequest.current = request;
+    committedPlan.current = plan;
+    events.current = { items, keyExtractor, plan, targets, positions: request.eventPositions };
+    return () => {
+      events.current = null;
+      committedRequest.current = null;
+      committedPlan.current = null;
+    };
+  });
+  useLayoutEffect(() => {
+    const currentGeneration = ++generation.current;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const current = () => generation.current === currentGeneration && committedRequest.current === request;
+    const run = () => {
+      if (!current()) return;
+      try {
+        const result = capturesMatch(request, committedPlan.current)
+          ? advancePreparation(request.preparation, true) : { value: null };
+        if (!current()) return;
+        if (result) setPrepared({ request, generation: currentGeneration, status: "ready", value: result.value });
+        else timer = setTimeout(run, 0);
+      } catch (error) {
+        if (!current()) return;
+        setPrepared(error === needsReact
+          ? { request, generation: currentGeneration, status: "ready", value: null }
+          : { request, generation: currentGeneration, status: "error", error });
+      }
+    };
+    if (!request.synchronous) timer = setTimeout(run, 0);
+    return () => {
+      generation.current++;
+      if (timer !== undefined) clearTimeout(timer);
+    };
+  }, [request]);
+  if (outcome?.status === "error") throw outcome.error;
   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,
+    items: records.data, keyField: "key", template: records.template, gap, followEnd, initialEnd: initialPosition === "end",
+    hasMore: !preparing && hasMore && load.status !== "pending" && load.status !== "error",
+    hasOlder: !preparing && hasOlder && older.status !== "pending" && older.status !== "error",
+    onEndReached: !preparing && onLoadMore ? load.run : undefined,
+    onStartReached: !preparing && 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 ?? []) {
+      const latest = events.current;
+      const path = latest?.targets.get(target)?.[name];
+      if (!latest || !path || isProxy?.(latest.items)) return;
+      const matches = (index: number) => {
+        const property = Object.getOwnPropertyDescriptor(latest.items, index);
+        return !!property && "value" in property && plainData(property.value)
+          && latest.keyExtractor(property.value, index) === key;
+      };
+      let index = latest.items === records.items ? records.positions.get(key) : latest.positions.get(key);
+      if (latest.items !== records.items && !latest.positions.has(key)) {
+        const beforeIndex = records.positions.get(key);
+        if (beforeIndex !== undefined && matches(beforeIndex)) index = beforeIndex;
+        else {
+          for (let candidate = 0; candidate < latest.items.length; candidate++) {
+            if (matches(candidate)) { index = candidate; break; }
+          }
+        }
+        latest.positions.set(key, index);
+      }
+      if (index === undefined) return;
+      let callback: unknown;
+      try {
+        const item = listItem(latest.items, index);
+        if (!plainData(item)) return;
+        callback = latest.plan.project(item, index);
+      } catch (error) {
+        if (error === needsReact) return;
+        throw error;
+      }
+      for (const part of path) {
         callback = callback != null && typeof callback === "object" ? Reflect.get(callback, part) : undefined;
       }
-      if (path && typeof callback === "function") callback(...args);
+      if (typeof callback === "function") callback(...args);
     },
   };
   return createElement(Fragment, null,

package/src/renderer.ts

@@ -11,7 +11,7 @@ declare const __inkCommit: (operations: Operation[]) => void;
 declare const __inkPost: (message: string) => void;
 
 type Props = Record<string, unknown>;
-type Instance = { id: number; type: string; props: Props; children: Instance[]; hidden?: boolean };
+type Instance = { id: number; type: string; props: Props; children: Instance[]; parent: Container | undefined; hidden?: boolean };
 type Container = { id: number; children: Instance[] };
 type Operation =
   | { op: "create"; id: number; type: string; props: Props }
@@ -86,16 +86,18 @@ function publish(instance: Instance) {
 }
 
 function insert(parent: Container, child: Instance, before?: Instance) {
-  const previous = parent.children.indexOf(child);
-  if (previous !== -1) parent.children.splice(previous, 1);
-  const index = before ? parent.children.indexOf(before) : parent.children.length;
-  parent.children.splice(index, 0, child);
+  // Only a moved child needs searching for; appends stay constant-time.
+  if (child.parent === parent) parent.children.splice(parent.children.indexOf(child), 1);
+  child.parent = parent;
+  if (before) parent.children.splice(parent.children.indexOf(before), 0, child);
+  else parent.children.push(child);
   publish(child);
   queue({ op: "insert", id: child.id, parent: parent.id, before: before?.id ?? null });
 }
 
 function forget(instance: Instance) {
   mounted.delete(instance.id);
+  instance.parent = undefined;
   for (const child of instance.children) forget(child);
 }
 
@@ -226,9 +228,10 @@ const reconciler = Reconciler<string, Props, Container, Instance, Instance, neve
   supportsHydration: false,
   isPrimaryRenderer: true,
   supportsMicrotasks: true,
-  createInstance: (type, props) => ({ id: allocateHostId(), type, props: hostProps(type, props), children: [] }),
-  createTextInstance: text => ({ id: allocateHostId(), type: "#text", props: { text }, children: [] }),
-  appendInitialChild: (parent, child) => { parent.children.push(child); },
+  // Declare `parent` up front so every instance keeps one object shape.
+  createInstance: (type, props) => ({ id: allocateHostId(), type, props: hostProps(type, props), children: [], parent: undefined }),
+  createTextInstance: text => ({ id: allocateHostId(), type: "#text", props: { text }, children: [], parent: undefined }),
+  appendInitialChild: (parent, child) => { parent.children.push(child); child.parent = parent; },
   finalizeInitialChildren: () => false,
   shouldSetTextContent: (type, props) => {
     if (type !== "Text") return false;

package/src/snapshot.ts

@@ -13,6 +13,6 @@ export interface SnapshotSource<T> {
 
 export function useSnapshot<T>(source: ResourceSource<T>): ResourceSnapshot<T>;
 export function useSnapshot<T>(source: SnapshotSource<T>): Snapshot<T>;
-export function useSnapshot<T>(source: SnapshotSource<T>): Snapshot<T> {
+export function useSnapshot(source: { subscribe(listener: () => void): () => void; getSnapshot(): unknown }): unknown {
   return useSyncExternalStore(source.subscribe, source.getSnapshot, source.getSnapshot);
 }