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

package/DESIGN.md

@@ -0,0 +1,168 @@
+# Design apps with Ink
+
+Build Light Phone III apps from Ink's screens and components. Ink already supplies typography, spacing, padding, colours, navigation, scrolling and keyboard behaviour. Your job is to choose the right page for each task and the right component for each piece of content.
+
+Follow the steps in order. Do not write screen code until you have a page map.
+
+## 1. Write a page map
+
+List every page before you build. Give each one a route, a single page type from [Page types](#2-choose-a-page-type) and the page it is reached from.
+
+```text
+/                     Main task      Tuner reading. Header: settings icon → /settings
+/settings             Settings       Toggles, Reference pitch field → /reference
+/reference            Choice         Reference pitch options. Saves and goes back
+```
+
+Shape the map with these rules:
+
+- `/` opens on the app's main task. Do not make it a menu of buttons that lead to the real content. Add setup or welcome pages only when the app cannot work without them, and leave them once setup is complete.
+- Use tabs only for two to four peer sections that users switch between often, such as Today, Locations and Settings. Put tab pages in `app/(tabs)/`.
+- Reach Settings from a header icon or a tab. Reach per-item actions from a `moreHoriz` header icon or a long press, which opens an options page.
+- Keep the tree shallow: section → item → options or choice. If a page needs a fourth level, group the settings differently.
+- When a page has two jobs, it is two pages. Split it.
+
+## 2. Choose a page type
+
+Every page is exactly one of these types. Use the listed components and nothing else at the top level of the page.
+
+| Page type | Use it for | Build with |
+| --- | --- | --- |
+| Main task | The app's primary reading or tool | `Screen` with the one thing users came for. Use `centered` for short content. Header icons for Settings and secondary pages |
+| Collection | Items users browse or open | `List` of `Row`. `EmptyState` when there are no items. `add` header icon to create |
+| Detail | One item | `Screen` titled with the item name. Content first, `moreHoriz` header icon for actions |
+| Settings | Preferences | `Toggle`, `Field` and `Button` as direct children of `Screen` |
+| Choice | Pick one value for a setting | `SettingsChoices` only. Save, then `back()` |
+| Input | Enter or edit one value | One `TextInput` with `autoFocus`. Its keyboard action submits. Hints or errors underneath only |
+| Options | Actions for one item | `Button`s only, one per action |
+| Confirmation | Destructive or irreversible action | `Confirmation` as the whole page |
+| Media or chat | Playback or messages | `PlayingScreen` or `ConversationScreen` |
+| Custom visual | Diagrams, boards, gauges | `Canvas` primitives inside `Screen`, with Ink components for any controls |
+
+Loading, empty and error states are not separate pages. Place `LoadingState`, `EmptyState` or `ErrorState` directly inside `Screen` in place of its content.
+
+## 3. Choose components
+
+Pick the component that matches what the element means, not how you want it to look.
+
+| To show | Use | Not |
+| --- | --- | --- |
+| A setting that is on or off | `Toggle label="…"` | A button whose label changes |
+| A setting with a current value | `Field label="…" href="/choice"` showing the value | A button labelled with the value |
+| A group of related settings | `Button href="/settings/group"` labelled with the group name | `Field` with an empty value |
+| An action | `Button` labelled with a verb | `Text` with `onPress` |
+| An item that opens | `Row` with `title`, and `subtitle` or `image` when useful | A `Stack` of `Text` with `onPress` |
+| A scrolling collection | `List` | `.map()` over many items inside `Stack` |
+| A user-ordered collection | `ReorderList` on its own page, reached from a `swapVert` header icon | Up and down buttons |
+| A one-of-many choice | `SettingsChoices` on a choice page | Toggles that turn each other off, or `+` and `−` buttons |
+| Content that stays above scrolling | `Screen header` | A custom pinned view |
+| Up to three persistent bottom actions | `Screen actionBar` | Buttons placed against the screen edge |
+| A secondary navigation action | `leftAction` or `rightAction` with an icon from `ink/icons` | A button in the content |
+| Supporting text | `Text size={18}` below what it explains | A paragraph above the controls |
+| A large primary reading | One `Text` with a large `size` and `tabularNumbers` | Several large sizes on one page |
+
+Common header icons: `settings` opens Settings, `add` creates an item, `moreHoriz` opens options, `swapVert` reorders, `sort` changes order, `check` saves an edit, and `graphicEq` opens the playing screen.
+
+## 4. Lay out the page
+
+- Put components directly inside `Screen`. `Screen` already spaces its children 47 pixels apart and supplies side padding and scrolling. Do not wrap the whole page in a `Stack`.
+- Use `Stack` only for elements that belong together and need tighter spacing than the page, such as a reading above its unit, or a horizontal row of labels. Use a gap of 16 or less inside a group.
+- Use `Stack justify="space-between"` as the only child of `Screen` to pin a footer to the bottom.
+- Order a page by importance: primary content, then the controls that act on it, then supporting text.
+- Order a Settings page as values first (toggles and fields), then links to groups, then destructive actions.
+- Use default text size for content and labels and `size={18}` for supporting text. Add at most one larger size per page, for its primary reading.
+- Centre short content with `Screen centered`. Align feeds, lists and forms to the top.
+
+## 5. Keep it small
+
+Ink apps are deliberately plain. Remove anything that does not help the user complete the task.
+
+- Do not create wrapper components that restyle or rearrange Ink components, such as cards, sections, headers, tiles or custom list items. A local component is fine when it composes Ink components for reuse across pages without changing their appearance.
+- Do not add borders, backgrounds, dividers, badges, status pills or decorative icons.
+- Do not set colours outside `Canvas`. Inside `Canvas`, derive colours from `useColourScheme()`.
+- Do not use props that are not in Ink's type definitions. If TypeScript rejects a prop, change the design, not the types.
+- Do not add explanatory paragraphs to a page. One short sentence is acceptable when the purpose or limits of a control are not obvious.
+- Do not add success messages for actions whose result is visible. Navigate back, or show the changed value.
+- Do not add a toggle subtitle that repeats its label. Add one only when the label alone cannot be understood.
+- Do not show the same information twice, such as a status in both a label and a sentence.
+
+## 6. Handle state and input
+
+- Inputs live on their own page. Use the right keyboard; its action submits or saves. Do not add a Save or Cancel button. The header Back button cancels.
+- Search submits to a separate results page. Multiline inputs keep Return for new lines and use a `check` header action to save.
+- Keep existing content visible during refreshes and when returning to a page. Show `LoadingState` only when there is no content yet.
+- Keep a control's label and appearance while its action is pending. `useAction` already ignores repeated calls, so do not set `disabled` or change the label to “Loading…”. Reserve `disabled` for controls that are unavailable.
+- Show one error at a time. Use `ErrorState` with a retry action when the page cannot show its content. Otherwise, place one `Text` beside the affected control.
+- Request a permission when the user opens the feature that needs it. Do not add a separate permission button.
+- Preserve scroll position, drafts and selections when navigating.
+- Use `tabularNumbers` for changing numbers. Reserve space for images whose size is known.
+
+## Example: a setup page
+
+This keyboard setup page mixes statuses, actions, instructions and several error messages:
+
+```tsx
+<Screen title="Set up keyboard">
+  <Stack gap={24}>
+    <Button onPress={enable.run}>{ready?.enabled ? "Atlas is enabled" : "Enable Atlas"}</Button>
+    <Button onPress={choose.run}>{ready?.selected ? "Atlas is selected" : "Choose Atlas"}</Button>
+    <Button onPress={scroll.run}>Open Scroll assistant</Button>
+    <Text size={18}>Select Sliding Mode 1 for each app where you want to scroll and swipe type. Atlas reads the keyboard while a text field is active, and scrolling works everywhere else.</Text>
+    {(enable.status === "error" || choose.status === "error") && <Text>Could not open keyboard settings.</Text>}
+    {scroll.status === "error" && <Text>Scroll assistant is only available on the Titan 2.</Text>}
+    {/* Retry button with disabled and pending label, two more error messages */}
+  </Stack>
+</Screen>
+```
+
+Problems:
+
+- Button labels change between an action and a status.
+- The whole page is wrapped in a `Stack` with its own gap.
+- A two-sentence paragraph sits between controls.
+- Each action adds its own error line at the bottom of the page.
+
+The same page as a Settings page type:
+
+```tsx
+<Screen title="Set up keyboard">
+  {loaded.status === "error" ? <ErrorState message="Could not read keyboard settings." onRetry={reload} /> : <>
+    <Field label="Enabled" onPress={enable.run}>{ready.enabled ? "Yes" : "No"}</Field>
+    <Field label="Selected" onPress={choose.run}>{ready.selected ? "Yes" : "No"}</Field>
+    <Field label="Scroll assistant" onPress={scroll.run}>Sliding Mode 1</Field>
+    {error && <Text size={18}>{error}</Text>}
+  </>}
+</Screen>
+```
+
+Each row shows one status and opens the place to change it. Spacing comes from `Screen`, and there is one error line.
+
+## Before you finish
+
+Check each page against this list and fix every failure before reporting the work as done:
+
+- [ ] The page appears in the page map with one page type.
+- [ ] `/` opens on the main task.
+- [ ] Top-level children of `Screen` are the components listed for its page type.
+- [ ] No wrapper `Stack`, custom gaps between page sections, borders, colours or decorative elements.
+- [ ] No component restyles or reimplements an Ink component.
+- [ ] Labels name actions or settings; values and statuses are in `Field` values or `Toggle` states.
+- [ ] No paragraphs, repeated information or success messages.
+- [ ] One error at a time, beside the control or as `ErrorState`.
+- [ ] `ink check` passes. Its `ink-design` rules catch some of these mistakes; fix the design rather than disabling a rule.
+- [ ] Each page is checked in the emulator with the keyboard open, long content, missing data, light and dark modes, and after navigating back from another page. Use the phone for hardware features.
+
+Use plain British English and sentence case. Name buttons with direct verbs, such as “Export words”.
+
+## Reference apps
+
+These apps show the intended structure. Read the matching page in one before building a new page type.
+
+| App | Shows |
+| --- | --- |
+| [Tuner](https://github.com/No-Scrolling/tuner) | Main task opening on a reading, Settings with a choice page |
+| [Weather](https://github.com/No-Scrolling/weather) | Tabs, grouped Settings, unit choice pages, search input and results |
+| [Podcasts](https://github.com/No-Scrolling/podcasts) | Collection, detail, options page, Player settings, `PlayingScreen` |
+| [Passes](https://github.com/No-Scrolling/passes) | Collection with reorder, options page, rename input, delete confirmation |
+
+See the [Ink documentation](https://ink.noscroll.ing/screens) for each component's props and examples. Ink's type definitions in `node_modules/ink/src` list every supported prop.

package/package.json

@@ -1,23 +1,27 @@
 {
   "name": "ink-framework",
-  "version": "0.1.0-alpha.10",
+  "version": "0.1.0-alpha.13",
   "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",
+    "./internal/controller": "./src/controller-react.ts",
     "./native": "./src/native.ts",
     "./native/controller": "./src/controller.ts",
     "./assets": "./src/assets.ts",
     "./icons": "./src/icons.ts",
     "./file-router": "./src/file-router.tsx",
     "./runtime-types": "./runtime.d.ts",
-    "./tsconfig": "./tsconfig.app.json"
+    "./tsconfig": "./tsconfig.app.json",
+    "./internal/react": "./src/react.ts",
+    "./resource": "./src/resource.ts"
   },
   "dependencies": {
     "linkify-it": "^6.1.0",
-    "react-reconciler": "0.33.0"
+    "preact": "10.29.3"
   },
   "peerDependencies": {
     "react": "19.2.8"
@@ -34,6 +38,7 @@
   "files": [
     "src",
     "*.json",
-    "*.ts"
+    "*.ts",
+    "*.md"
   ]
 }

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/compiler-runtime.ts

@@ -0,0 +1,6 @@
+import { useMemo } from "preact/hooks";
+
+/** React Compiler's per-component memo slots, retained across Preact renders. */
+export function c(size: number): unknown[] {
+  return useMemo(() => Array(size).fill(Symbol.for("react.memo_cache_sentinel")), []);
+}

package/src/controller-react.ts

@@ -0,0 +1,33 @@
+import { useMemo } from "./react";
+import { attachNativeController } from "./controller";
+
+type Attachment = ReturnType<typeof attachNativeController>;
+type ControllerAttachment = {
+  current: Attachment | null;
+  attach(recipe: unknown, observe: (value: unknown) => void, fail: (error: Error) => void,
+    ready?: (id: number) => void): () => void;
+};
+
+/** @internal Attach from an effect and return its cleanup, including for hidden Activities. */
+export function useNativeController(module: string, description = module): ControllerAttachment {
+  return useMemo(() => {
+    const controller: ControllerAttachment = {
+      current: null,
+      attach(recipe, observe, fail, ready) {
+        const attachment = attachNativeController(module, recipe, observe);
+        controller.current = attachment;
+        // Disposal removes event observers; promise continuations need their own lifetime check.
+        void attachment.ready.then(() => {
+          if (controller.current === attachment) ready?.(attachment.id);
+        }, error => {
+          if (controller.current === attachment) fail(error);
+        });
+        return () => {
+          controller.current = null;
+          void attachment.dispose().catch(error => console.error(`Could not release ${description}`, error));
+        };
+      },
+    };
+    return controller;
+  }, [module, description]);
+}

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/file-router.tsx

@@ -1,4 +1,4 @@
-import { Activity, createElement, useMemo, type ComponentType, type ReactNode } from "react";
+import { Activity, createElement, useMemo, type ComponentType, type ReactNode } from "./react";
 import { back, LayoutContext, NavigationStack, RouteContext, type Destination, type Entry } from "./navigation";
 
 export type FileRoute = { name: string; path: string; component: ComponentType };

package/src/fixed-list-row.ts

@@ -0,0 +1,65 @@
+import { createElement, type ComponentProps, type ReactElement } from "./react";
+import { Button, type StackProps, type TextProps } from "./index";
+import type { IconAsset } from "./assets";
+import { listText, nativeListRow, nativeListTemplate } from "./native-list";
+
+type SharedProps = { key?: string | number; hidden?: boolean };
+type RowProps = {
+  Stack: SharedProps & Omit<StackProps, "children">;
+  Text: SharedProps & Omit<TextProps, "children" | "href" | "url"> & { text: string };
+  Button: SharedProps & Pick<ComponentProps<typeof Button>, "icon" | "disabled" | "selected" | "onPress" | "onLongPress">;
+  MediaGridRow: SharedProps;
+  MediaCell: SharedProps & {
+    src: string; selected?: boolean; dimmed?: boolean; video?: boolean;
+    checkIcon?: IconAsset; videoIcon?: IconAsset;
+    onPress?: () => void; onLongPress?: () => void;
+  };
+};
+type RowValue = string | number | boolean | undefined | (() => void);
+type RowField<Fields, Value extends RowValue> = { readonly read: (fields: Fields) => Value };
+type BoundProps<Fields, Props> = { [Name in keyof Props]: (Props[Name] & RowValue) | RowField<Fields, Props[Name] & RowValue> };
+type RowNode<Fields> = {
+  type: keyof RowProps;
+  props: Record<string, RowValue | RowField<Fields, RowValue>>;
+  children: RowNode<Fields>[];
+};
+
+/** @internal A fixed built-in presentation with React and native list adapters. */
+export function fixedListRow<Fields>(build: (
+  node: <Kind extends keyof RowProps>(type: Kind, props: BoundProps<Fields, RowProps[NoInfer<Kind>]>, children?: RowNode<Fields>[]) => RowNode<Fields>,
+  field: <Value extends RowValue>(read: (fields: Fields) => Value) => RowField<Fields, Value>,
+) => RowNode<Fields>) {
+  class Field<Value extends RowValue> {
+    constructor(readonly read: (fields: Fields) => Value) {}
+  }
+  const root = build((type, props, children = []) => ({ type, props, children }), read => new Field(read));
+  const readers: ((fields: Fields) => RowValue)[] = [];
+  const template = nativeListTemplate((node, field) => {
+    const visit = (row: RowNode<Fields>): ReturnType<typeof node> => node(row.type,
+      Object.fromEntries(Object.entries(row.props).flatMap(([name, value]) => {
+        if (name === "key") return [];
+        if (value instanceof Field || name.startsWith("on")) {
+          const read = value instanceof Field ? value.read : () => value;
+          return [[name, field(readers.push(read) - 1)]];
+        }
+        return [[name, value]];
+      })), row.children.map(visit));
+    return visit(root);
+  });
+  function render(row: RowNode<Fields>, fields: Fields): ReactElement | null {
+    const props = Object.fromEntries(Object.entries(row.props).map(([name, value]) =>
+      [name, value instanceof Field ? value.read(fields) : value]));
+    if (props.hidden === true) return null;
+    if (row.type === "Text") {
+      const { text, ...rest } = props;
+      return createElement("Text", rest, listText([text]));
+    }
+    return createElement(row.type === "Button" ? Button : row.type, props, ...row.children.map(child => render(child, fields)));
+  }
+  return function<T>(project: (item: T, index: number) => Fields) {
+    return nativeListRow((item: T, index: number) => render(root, project(item, index)), (item, index) => {
+      const fields = project(item, index);
+      return [readers.map(read => read(fields))];
+    }, template);
+  };
+}