---
title: "React Renderer"
description: "Use FARMJS with the default React renderer, including client hooks, streaming SSR, and the experimental AOT compiler."
canonical_url: "https://mcp.farmjs.dev/docs/renderers/react"
markdown_url: "https://mcp.farmjs.dev/docs/renderers/react.md"
last_updated: "2026-10-20"
x_farming_labs_generated_preamble: true
---
# React Renderer
URL: /docs/renderers/react
LLM index: /llms.txt
Description: Use FARMJS with the default React renderer, including client hooks, streaming SSR, and the experimental AOT compiler.
# React Renderer
React is the default FARMJS renderer and has the broadest client-feature support. Existing projects
do not need a renderer option or an additional adapter package.
## Create an app
```bash
pnpm create @farm.js/app my-app --template basic --typescript
```
Omitting `renderer` keeps React active:
```ts
import { defineConfig } from "@farm.js/core";
export default defineConfig({});
```
## Route components
React routes use `.tsx` or `.jsx` files:
```text
src/app/layout.tsx
src/app/page.tsx
src/app/products/[id]/page.tsx
```
```tsx
import type { LayoutProps, Metadata } from "@farm.js/core";
import "./globals.css";
export const metadata: Metadata = {
title: "My FARMJS app",
};
export default function RootLayout({ children }: LayoutProps) {
return {children};
}
```
Add `"use client"` to an interactive component. FARMJS keeps ordinary server-rendered routes out of
the browser bundle and hydrates the client boundaries imported by the route.
```tsx
"use client";
import { useState } from "react";
export function Counter() {
const [count, setCount] = useState(0);
return ;
}
```
## Shared client state
`createStore` from `@farm.js/core/client` provides an in-memory React store with typed field
selectors. String, numeric, and symbol state keys work with `use`, `get`, `set`, `subscribe`,
and direct field accessors:
```tsx
"use client";
import { useState } from "react";
import { createStore } from "@farm.js/core/client";
const selected = Symbol("selected");
export function Selection() {
const [store] = useState(() => createStore({ 0: "First item", [selected]: false }));
const label = store.use(0);
const active = store[selected]();
return (
);
}
```
Use `store.use([0, selected])` to select multiple fields. Subscriptions only notify for changed
selected values, including updates through patches, `replace`, or `reset`. Numeric keys follow
normal object semantics (`0` names the same property as `"0"`); symbols retain their identity,
even when their descriptions match. State contains own enumerable properties, including symbols.
String names used by the store API, such as `use` and `set`, remain reserved.
The example creates one store per mounted component; share that instance through context when
needed. Do not put request-specific server data in a process-global store. This store does not
persist data or serialize symbol keys across server/client boundaries.
## AOT compiler
Farm's experimental React compiler moves a narrow class of local state-update work from React's
runtime render-and-reconcile path into build-time binding metadata. It is opt-in, disabled by
default, and only affects the React renderer that enables it. Preact, Solid, Vue, Svelte, and
custom renderers do not receive this transform.
> The compiler is experimental. `@farm.js/react` is still a beta, and eligibility, generated
> output, and options can change between releases. Unsupported components always stay on React.
The compiler is intentionally conservative. It only transforms a component when it can prove that
the component has one stable host-element tree and that each supported state value maps to known
text or attribute targets. If that proof fails, the original component stays on React.
### Why this compiler exists
An ordinary local `useState` update asks React to run the component again, produce another element
tree, reconcile it with the previous tree, and commit the changed DOM. That general model is needed
for dynamic React applications, but it repeats work when a component's structure is fixed and only
a few text or attribute values can change.
For that safe subset, Farm prepares three things ahead of time:
1. local state cells plus read-only cells for eligible primitive props;
2. the DOM path of every state-driven text or attribute binding; and
3. the state-cell dependencies for each binding.
After mount, an eligible local update flushes the changed cells and patches only the affected
bindings. A parent update still enters through React, but flat destructured `string`, `number`,
`boolean`, `bigint`, `null`, or `undefined` props can reuse the mounted compiled render plan and
patch the same dependency graph after commit. React still owns initial rendering, component
placement, the parent update, events, SSR, hydration, and unmounting. Identity-bearing props and
unsupported prop shapes keep the full React render path.
### Enable the compiler
Start from the focused compiler starter when you want the compiler option, shared dark starter
UI, a live AOT-versus-React comparison, and a reproducible browser check already wired together:
```bash
pnpm create @farm.js/app compiler-app --template react-compiler --typescript
```
You can also clone the standalone
[React Compiler Starter](https://github.com/farming-labs/farmjs-react-compiler-starter).
Install `@farm.js/react` to select the React renderer with compiler options:
```bash
pnpm add @farm.js/react
```
```ts
import { defineConfig } from "@farm.js/core";
import { react } from "@farm.js/react";
export default defineConfig({
renderer: react({
compiler: true,
}),
});
```
`compiler: true` is the recommended starting point. It means automatic
inference with safe React fallback:
```ts
compiler: {
mode: "infer",
onUnsupported: "fallback",
reactivity: "hybrid",
}
```
Omitting `compiler` or setting it to `false` disables the transform.
### Experimental AOT compiler
Upgrading from an earlier beta? The option used to live at
`react({ experimental: { compiler } })`. That form still works as a
deprecated alias: it logs a one-time deprecation warning and behaves exactly like the top-level
option. Setting both keys is an error. This heading preserves existing links to the compiler
guide; use the [AOT compiler](#aot-compiler) section for new links.
### Compatibility and release status
`@farm.js/react` is versioned independently from core. A `-beta.N` package version is still a beta;
moving the configuration option does not by itself publish a stable package, and the compiler stays
experimental until that happens. The first stable release covers `react({ compiler })`, the
documented compiler options, and the public `List` component. Inference and annotation mode, hybrid
and static reactivity, diagnostics, and reporting all remain supported; the advanced options do not
require an experimental flag.
The compiler and `@farm.js/react/compiler-runtime` must come from the same installed package
version. Generated definitions are an implementation protocol, not a cross-version format.
Rebuild and deploy the complete server and browser output together after upgrading. Do not mix
cached compiled modules from different package versions. Existing runtime exports remain available;
applications should normally write React components rather than hand-author generated definitions.
Eligibility and the set of compiled components can evolve between releases. React fallback,
documented options, and observable application behavior are the compatibility contract, not an
exact render count, generated helper name, or benchmark score. Unsupported components continue on
React unless `onUnsupported: "error"` deliberately makes them a build error.
### Combine the compiler with isolated hydration
The compiler and [isolated client hydration](/docs/configuration#isolated-client-hydration) optimize
different parts of the same client component. Isolated hydration keeps the server-owned layout out
of the browser graph and gives an eligible client leaf its own root. The compiler keeps React in
charge of that root's SSR, hydration, events, and unmounting, then patches compiler-proven state
bindings directly after mount.
```ts
import { defineConfig } from "@farm.js/core";
import { react } from "@farm.js/react";
export default defineConfig({
renderer: react({
compiler: true,
}),
experimental: {
isolatedClientHydration: "enabled",
},
});
```
Farm's maintained [isolated hydration benchmark](https://github.com/farming-labs/farm.js/blob/main/benchmarks/isolated-hydration/results/latest.md)
builds the same route-wide and isolated fixtures with the compiler off and on. Compiler builds must
prove that every measured component compiled. The cost guard checks initial transfer, hydration,
heap, and repeated state updates separately so a steady-state compiler win cannot hide an isolated
root startup regression.
### Configuration API
```ts
type ReactCompilerMode = "infer" | "annotation";
type ReactCompilerReactivity = "static" | "hybrid";
type UnsupportedCompilerBehavior = "fallback" | "warn" | "error";
interface ReactCompilerOptions {
mode?: ReactCompilerMode;
directive?: string;
onUnsupported?: UnsupportedCompilerBehavior;
reactivity?: ReactCompilerReactivity;
report?: boolean;
reportFile?: string;
}
```
| Option | Values | Default | Purpose |
| --------------- | ------------------------------------- | --------------------------- | ------------------------------------------------------------------------ |
| `compiler` | `false`, `true`, or an options object | `false` | Disables, enables with defaults, or configures the React-only transform. |
| `mode` | `"infer"`, `"annotation"` | `"infer"` | Selects components automatically or only through an explicit directive. |
| `directive` | non-empty string | `"use compiler"` | Names the module/function directive used by annotation mode. |
| `onUnsupported` | `"fallback"`, `"warn"`, `"error"` | `"fallback"` | Controls what happens outside the current supported subset. |
| `reactivity` | `"static"`, `"hybrid"` | `"hybrid"` | Selects complete static dependencies or runtime-narrowed subscriptions. |
| `report` | boolean | `false` | Writes a compiler coverage report after a successful production build. |
| `reportFile` | project-relative path | `.farm/react-compiler.json` | Changes the report path and enables reporting when provided. |
`directive` is valid only when `mode` is `"annotation"`. Invalid compiler, reactivity, or
unsupported-component modes and directives configured in inference mode throw a configuration
error instead of silently changing behavior.
### Static and hybrid reactivity
Both modes keep the compiler's complete state dependency list as the correctness boundary. They
also build a reverse dependency index once, so a state update goes directly to its candidate
bindings instead of scanning every binding in the component.
`"hybrid"` additionally marks compiler-proven, multi-state short-circuit expressions and observes
the `CompilerCell.get()` calls made by those direct text, attribute, and style readers after mount.
Ordinary bindings stay entirely on the static index. A reader such as
`enabled ? activeValue : inactiveValue` subscribes to `enabled` and only the selected value. When
`enabled` changes, the reader runs and replaces its subscriptions. The generated binding carries
the internal `tracking: "dynamic"` marker; application code never manages it. Structural block
dependencies remain compiler-defined, and unsupported expressions still fall back to React; this
option does not add a Proxy or make arbitrary JavaScript compiler-safe.
`"static"` uses the full dependency list for every update. It is useful as a deterministic
comparison and diagnostic mode. `"hybrid"` is the default because it can avoid inactive work while
preserving the compiler's safe fallback and React ownership boundaries. Both modes cache the last
committed direct-binding value and skip an identical DOM write.
When Suspense (or React 19's Activity) temporarily hides a compiled component, Farm retains
its pending local state and React-owned text-node snapshots. On reappearance, it synchronizes
the current committed props before rebuilding binding dependencies and drains queued updates
in order. Hiding is not treated as permanent disposal: host refs and refresh subscriptions
are detached, while component-owned state remains available for React to resume.
During a production build, identical compiler inputs can reuse results across route discovery,
SSR, and client compilation. This build-local cache retains at most 128 entries and 16 MiB of
source-key/result payloads (excluding JavaScript object overhead and active compilation work).
Results are isolated from each consumer, and the cache is discarded after the build, including
failures. Diagnostics and compiler reports still run for every transform. Ordinary development
keeps Vite's existing caching behavior; there is no persistent source cache, configuration flag,
or added browser runtime payload.
### Component selection
#### Automatic inference
`compiler: true` and `mode: "infer"` inspect top-level, capitalized function components in
application `.tsx` and `.jsx` modules under the project root. Dependencies in `node_modules` are not
transformed. Every eligible component is compiled; every unsupported component remains unchanged.
Use the built-in function directive to keep a specific component entirely on React:
```tsx
export function ReactOwnedEditor() {
"use no compiler";
// React always owns this component.
}
```
The opt-out is intentionally local. It documents a known ownership boundary without disabling the
compiler for the rest of the module.
#### Annotation mode
Annotation mode is useful for a staged rollout or a strict, reviewed set of components:
```ts
renderer: react({
compiler: {
mode: "annotation",
directive: "use compiler",
onUnsupported: "warn",
},
}),
```
Place the configured directive inside one component to select only that component:
```tsx
export function Counter() {
"use compiler";
const [count, setCount] = useState(0);
return ;
}
```
Or place it at the top of a module to select every eligible component in that module:
```tsx
"use compiler";
import { useState } from "react";
export function Counter() {
const [count, setCount] = useState(0);
return ;
}
```
The directive name is configurable:
```ts
compiler: {
mode: "annotation",
directive: "use optimize",
}
```
An explicitly selected component that cannot be compiled produces a warning even when
`onUnsupported` is `"fallback"`. Explicit selection should not fail silently.
### Unsupported-component behavior
| Value | Behavior | Good fit |
| ------------ | ---------------------------------------------------------------------------------------- | ---------------------------------------------- |
| `"fallback"` | Keep the original React component. Inferred unsupported candidates are quiet. | Broad automatic experimentation. |
| `"warn"` | Keep the React component and emit a diagnostic containing the component name and reason. | Finding missed optimization opportunities. |
| `"error"` | Stop the transform/build when a considered component cannot be compiled. | Enforcing a reviewed annotation-mode contract. |
For example, an unsupported keyed list can report:
```text
[react-compiler] KeyedList: dynamic child structures require React reconciliation; using React.
```
Use `"warn"` while exploring the compiler. Use annotation mode with `"error"` when CI should prove
that every explicitly selected component still satisfies the supported contract.
### Compiler coverage report
Console warnings are useful while editing, but a report makes compiler coverage visible across the
production browser graph where compiled DOM updates run. Enable it without changing selection or
fallback behavior:
```ts
renderer: react({
compiler: {
report: true,
},
}),
```
After a successful build, Farm writes `.farm/react-compiler.json`:
```json
{
"version": 1,
"summary": {
"modules": 2,
"componentsConsidered": 4,
"compiled": 2,
"fallback": 2,
"keyedArrayAppendHints": 1,
"keyedArrayFilterHints": 1,
"keyedArrayPrependHints": 1,
"keyedArrayPositionHints": 1,
"keyedArrayReorderHints": 1,
"keyedArraySortHints": 1,
"keyedArrayMappedRollingWindowChainHints": 0,
"keyedArrayRollingWindowHints": 1,
"keyedArraySliceHints": 1,
"keyedCollectionUpdateHints": 3,
"keyedIdentityTargets": 2,
"keyedMapLookupTargets": 1,
"keyedMembershipTargets": 1,
"keyedMapUpdateHints": 1
},
"fallbackReasons": [
{
"count": 2,
"reason": "dynamic child structures require React reconciliation"
}
],
"modules": [
{
"id": "src/Products.tsx",
"compiled": ["ProductRow"],
"optimizations": {
"keyedArrayAppendHints": 1,
"keyedArrayFilterHints": 1,
"keyedArrayPrependHints": 1,
"keyedArrayPositionHints": 1,
"keyedArrayReorderHints": 1,
"keyedArraySortHints": 1,
"keyedArrayMappedRollingWindowChainHints": 0,
"keyedArrayRollingWindowHints": 1,
"keyedArraySliceHints": 1,
"keyedCollectionUpdateHints": 3,
"keyedIdentityTargets": 2,
"keyedMapLookupTargets": 1,
"keyedMembershipTargets": 1,
"keyedMapUpdateHints": 1
},
"fallbacks": [
{
"module": "src/Products.tsx",
"component": "ProductList",
"reason": "dynamic child structures require React reconciliation",
"selected": false
}
]
}
]
}
```
`componentsConsidered` counts candidates selected by the active mode. `compiled` counts components
using the AOT runtime, and `fallback` counts candidates left on React. `keyedIdentityTargets` counts
row bindings that can update by looking up the previous and next key directly.
`keyedMapLookupTargets` counts row bindings that can update from changed primitive values in a
local native `Map`.
`keyedMembershipTargets` counts row bindings that can update from the changed members of a local
native `Set`.
`keyedCollectionUpdateHints` counts proven native Set/Map mutation sites that can carry their
executed keys to the runtime.
`keyedMapUpdateHints` counts map calls where the compiler proved that a direct keyed collection can
report its changed row indexes while one or more consecutive immutable `map()` stages run. The same
counts appear per module.
`keyedArrayAppendHints` counts setter sites where the compiler proved a direct keyed array append
and can hand the appended suffix to the runtime. `keyedArrayFilterHints` counts concise or
single-return block-bodied keyed-array filter sites that can report removed positions.
`keyedArrayPrependHints` counts setter sites where the compiler proved a direct keyed array prepend
and can hand the new prefix to the runtime.
`keyedArraySliceHints` counts direct keyed-array slices whose compiler-safe bounds identify one
exact retained interval after runtime validation.
`keyedArrayPositionHints` counts compiler-proven native keyed-array insertions, single or
contiguous-range removals, single-row replacements, and exact-window replacements with a guarded
position.
`keyedArrayReorderHints` counts native keyed-array reverse steps whose complete permutation can be
validated, including steps after a supported filter/slice prefix.
`keyedArraySortHints` counts native keyed-array sort steps whose resulting permutation can be
validated without rebuilding keyed rows, including steps after a supported filter/slice prefix.
`keyedArrayMappedRollingWindowChainHints` counts rolling steps retained across compiler-proven
multi-window same-key map chains.
`keyedArrayRollingWindowHints` counts direct keyed-array updates that retain a proven sliced tail
and append an incoming suffix.
`selected` is `true` when an annotation explicitly requested compilation. Module paths are relative
to the project root, and the output is sorted and contains no timestamp, so CI can compare reports
without machine-specific noise.
Use a different project-relative output path when CI collects artifacts elsewhere:
```ts
compiler: {
reportFile: "artifacts/react-compiler.json",
}
```
Report paths cannot be absolute or escape the project root. Reporting is observability only: it
does not make unsupported components fail. Use `onUnsupported: "error"` when failure is the desired
policy.
### Current supported contract
The current compiler deliberately supports a smaller subset than general React. A component must
satisfy all of these rules:
| Area | Current supported shape |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Component discovery | A top-level, capitalized function declaration, function expression, or arrow component in application `.tsx` or `.jsx`. |
| Function shape | Synchronous, non-generator, non-generic block body with zero parameters, one props identifier, or object props destructuring without computed keys. |
| Props | Object destructuring supports shorthand names, aliases, defaults, nested object and array patterns, and rest. Referenced primitive values join the dependency graph after mount. |
| Body | Top-level `useState` declarations, compiler-safe derived values and named handlers in any order (a derived value cannot read a later state), then one unconditional JSX return. |
| State | `const [value, setValue] = useState(initial)`, including lazy initializers, multiple cells, and queued functional updates. |
| Root | Exactly one lowercase host JSX element such as `button`, `section`, `input`, or `div`. |
| Tree | A statically known host tree around eligible conditional, keyed-list, compiled keyed-row, and component-island boundaries. |
| Text bindings | State-driven text in a leaf host element. |
| Attribute bindings | Basic attributes, controlled form properties, and individual properties in one inline `style` object. |
| Events | Inline handlers and `const` or function-declaration handlers, including async ones, plus inline synchronous events in eligible host-only keyed rows. |
| Conditional blocks | Logical/ternary host branches in dedicated containers or direct ranges among static host siblings, including the component root. |
| Keyed lists | Item-keyed maps and imported `List`, including safe collection pipelines; eligible rows use direct bindings and recursive host-only conditions. |
| Range siblings | Stable host siblings beside ranges may patch leaf text, attributes, `className`, and individual inline style properties. |
| Component islands | Stable imported or module-level component identifiers with explicit compiler-safe props and no JSX children, spread, `ref`, or `key`. |
This component is eligible:
```tsx
"use client";
import { useState } from "react";
interface StatusButtonProps {
initial?: number;
label: string;
}
export function StatusButton({ initial = 0, label: title }: StatusButtonProps) {
const [count, setCount] = useState(initial);
const [active, setActive] = useState(false);
const visibleCount = Math.max(0, count);
const statusClass = active ? "active" : "idle";
const visibleLabel = `${title}: ${String(visibleCount)}`;
function update() {
setCount((value) => value + 1);
setActive((value) => !value);
}
return (
);
}
```
The compiler records separate dependencies for `count` and `active`. Changing `count` does not
reevaluate bindings that depend only on `active`, and vice versa.
Derived values are expanded into the generated bindings, so they do not create a runtime scope or
force a component rerender. They may use literals, props, state, operators, optional/member access,
conditionals, templates, earlier derived values, and a small call whitelist. The whitelist contains
`Boolean`, `Number`, `String`, and `Math.abs`, `ceil`, `floor`, `max`, `min`, `round`, `sign`, and
`trunc`. Safe keyed collections additionally accept the non-mutating pipeline described below. A
name is not treated as built-in when the component shadows it. Outside that pipeline, application
helpers, prototype methods, `Math.random`, optional calls, assignments, identity-bearing object or
array literals, functions, JSX, constructors, and other unproven expressions still fall back to
React.
For destructured props, the original component wrapper still performs JavaScript destructuring on
every parent render. Defaults therefore apply only to `undefined`, aliases keep their normal local
names, and the resolved values are passed to the compiled definition. A named handler can be a
`const` function or function declaration, synchronous or async. It is expanded when passed directly to a JSX
event or called from that event's inline function, including arguments such as
`onClick={() => select(productId)}`. Calling it while producing the event prop, exposing it as a
child, using it outside an event, or making it a generator or generic still falls back to React.
A handler that can run code later, because it awaits or contains a nested function such as a
`setTimeout` callback, reads each state value and prop it uses once, when it starts. Code after an
`await` therefore sees the values from the render that created the handler, as it does in React.
#### Primitive prop cells
Flat destructured props referenced by the compiled render are assigned read-only cells after the
component's local state cells. The compiler includes those cell indexes in ordinary text,
attribute, style, conditional, keyed-range, and component-island dependencies. For example:
```tsx
export function Total({ label, price, quantity, enabled }: TotalProps) {
const [discount, setDiscount] = useState(0);
const total = price * quantity - discount;
return (
{label}: {total}
{enabled && Ready}
);
}
```
When `label`, `price`, `quantity`, or `enabled` changes to another primitive, React commits the
parent update, the compiled wrapper returns its already-mounted element, and the runtime commits
the new prop cells. Only dependent targets or blocks refresh. `discount` and a prop change in the
same turn share one coherent flush, so `total` observes both newest values.
The optimization is deliberately runtime-guarded. If any tracked value is an object, array,
function, symbol, React element, or `children`, the definition runs through normal React rendering
and reconciliation for that update. Components using an identifier props parameter also retain
the existing React prop path; flat destructuring is the current proof boundary. Props used only as
`useState` initializers keep React's normal initialize-once semantics and are not turned into live
state replacements. No extra option or annotation is required.
Stateful styles use one inline object literal. The compiler creates a separate binding for each
state-dependent camelCase property or CSS custom property, so changing `opacity` does not rewrite
an unrelated `width`. Style spreads, methods, computed names, and conditional whole objects remain
on React because their final property set or precedence can change.
### Conditional DOM blocks
This optimization is automatic for components selected by the compiler
configuration. It does not require a conditional component, a new annotation, or another option.
The compiler can isolate logical and ternary child structures when their positions are known at
build time:
```tsx
export function StatusPanel() {
const [loading, setLoading] = useState(false);
const [enabled, setEnabled] = useState(true);
const [updates, setUpdates] = useState(0);
return (
Status
{loading &&
Loading update {updates}…
}
Stable content · update {updates}
{enabled ? Enabled at {updates} : Disabled at {updates}}
);
}
```
At build time, Farm records each condition's state cells and prepares a descriptor plus exact
text/attribute/style bindings for every host branch. It also counts the static host elements before
each range and after the final range. React still creates the complete initial tree during client
rendering, SSR, or hydration. After mount, Farm adopts the original container, its static siblings,
and any active branches. It does not add a wrapper, comment marker, or hydration attribute.
When a state update keeps the same branch, Farm patches only that branch's changed bindings and
preserves its DOM identity. When the condition changes, Farm inserts, removes, or replaces only that
range. Multiple ranges are evaluated from one state snapshot and committed from right to left, so
adjacent empty ranges and simultaneous changes keep their original order. Root attributes and
ordinary bindings such as `data-update` above continue to patch the same physical root. The user
component and unchanged static siblings do not execute or remount.
The compiler-owned path is deliberately narrow:
- A nested or component-root lowercase host container may contain one or more eligible direct
conditionals separated by statically known host siblings. A nested container needs at least two
meaningful children; the existing dedicated one-child optimization handles the smaller shape.
- Every other direct child is a lowercase host subtree. Its text and ordinary attributes may use
supported bindings, and its event handlers remain React events. Fragments, custom components, or
another dynamic structure beside a range keep that container on the React-owned path.
- Every non-empty branch has one lowercase HTML root and a statically known host-only descendant
tree. Text, attributes, and individual inline style properties may use supported expressions.
- Branch events, `key`, custom components, fragments, refs, SVG, `dangerouslySetInnerHTML`, JSX
spreads, interactive keyed rows, unsupported direct-child structures, and dynamic text mixed
beside nested elements require React ownership.
- A ternary may use `null` or `false` for an empty branch. For logical `&&`, a numeric falsy value
such as `0` can be visible React output, so the runtime remounts that container through React
instead of incorrectly treating it as empty.
- The test and every prepared binding must use the same deterministic expression subset as other
compiler bindings.
A dedicated host container whose conditional is its only meaningful child uses the same branch
descriptor and update behavior. It remains useful when a branch needs one fixed mounting location:
```tsx
{loading &&
Loading…
}
```
### Recursive compiler-owned host blocks
An eligible compiler-owned branch may contain more eligible host-only blocks:
```tsx
{open ? (
Inbox
{loading &&
Loading…
}
Fixed row
{messages.map((message) => (
{message.title}
))}
) : (
)}
```
The outer `open` condition, nested `loading` range, and keyed `messages` range receive globally
unique block IDs and separate dependency lists. Updating `loading` touches only its host range.
Updating `messages` reuses matching rows, patches their prepared bindings, and applies LIS moves.
Neither update reruns the component or replaces the outer `section`.
If an outer condition and a descendant change in the same microtask, the scheduler commits the
outer block first and suppresses the now-redundant child refresh. Removing an outer branch cleans
every descendant subscription before removing its DOM. Reopening it creates the selected host tree
from current compiler cells, so updates made while closed cannot become stale work.
This recursive path is intentionally host-only. Nested conditional ranges may recurse again, and a
nested container may own one or more non-interactive keyed ranges separated by static host
siblings. Hooks, custom components, branch events, refs, SVG, fragments, dangerous HTML,
interactive rows, or unsupported structure inside an inner keyed row keep React ownership. React still renders the initial
client/SSR tree, hydrates it, reports recoverable mismatches, and handles every fallback. Duplicate
runtime keys or invalid adopted DOM remount the affected outer container through React; descendant
dependencies remain live after that handoff.
### Mixed conditional and keyed ranges
A safe host container may interleave both range kinds in their original order:
```tsx
Inventory
{loading &&
Loading…
}
Rows
{items.map((item) => (
{item.label}
))}
{error ? Error : Ready}
```
The compiler emits one mixed-range descriptor rather than competing conditional and list
controllers. Each slot records its kind and the number of static host siblings before it. On an
update, every condition and collection is read from one compiler-cell snapshot. Conditional slots
mount, replace, or remove one host branch; keyed slots reuse their per-key instances and run LIS
independently. Reconciliation proceeds from right to left, preserving the exact order when adjacent
ranges become empty, grow, or change together. Static header, divider, and footer nodes are never
used as synthetic markers and retain their DOM identity.
Those structurally stable siblings may still contain stateful values:
```tsx
{title}
{loading &&
Loading…
}
Rows: {items.length}
{items.map((item) => (
{item.label}
))}
```
The build records each sibling binding by static segment, sibling position inside that segment,
and nested host path. Unlike a live `children[index]` address, that coordinate does not shift when
an earlier condition mounts or when an earlier keyed range inserts, removes, or reorders rows. One
compiler flush can therefore patch the header, divider, and footer while also reconciling every
dynamic range, without rerunning the owner or replacing those siblings. Supported bindings are
safe leaf text, ordinary attributes, `className`, and individual properties in one inline style
object.
Safe host-only conditionals and keyed ranges may recurse inside a mixed branch or row. Every syntax
site still receives one globally unique block ID and a parent link, so an affected outer mixed block
suppresses redundant descendant refreshes. Removing a branch or keyed row cleans its nested mixed
subscriptions before removing DOM. Recreating it reads current state, preventing hidden or removed
work from becoming stale. Stateful static-sibling bindings use the same mechanism inside recursively
compiled branches and keyed rows; row-local bindings close over the current row descriptor and are
rebound when a surviving keyed row receives a new item value.
This path requires at least one conditional and one keyed `.map(...)` or `List` range in the same
lowercase host container. Every dynamic branch and row must have a statically known host tree and a
stable item-derived key. Hooks, custom components, events inside branches or rows, controlled forms,
refs, SVG, fragments, spreads, dangerous HTML, duplicate runtime keys, numeric logical output, or an
invalid hydration/adoption shape keep or transfer that complete container to React. Parent prop and
Fast Refresh changes also remount the container through React so the compiler never retains stale
closures or static markup. Static siblings remain plain lowercase host trees; lifecycle-sensitive
components, Hooks, refs, controlled forms, events requiring compiler DOM ownership, or unproven
expressions retain the existing React fallback.
The existing React-owned conditional boundary remains the fallback for supported complex shapes.
It can contain event handlers, nested host conditionals, keyed lists, and component islands while
still skipping the surrounding compiled component. Unsupported roots or unprovable behavior keep
the complete original React component. A parent-prop update, Fast Refresh, invalid adopted DOM, or
numeric logical output remounts the affected range container through React before direct updates
resume. In every tier, React remains responsible for delegated events, error boundaries, Strict
Mode, SSR, and hydration semantics.
### Compiled keyed rows and React list boundaries
The compiler automatically recognizes a direct keyed map in a safe, statically known container:
```tsx
export function Inventory() {
const [items, setItems] = useState(initialItems);
return (
{items.map((item) => (
{item.label}
))}
);
}
```
This dedicated `ul` has one meaningful child and each row is a host-only tree. Farm can therefore
prepare the row's host descriptor, key reader, and exact text, attribute, and style bindings at
build time. React still creates the initial elements during client render or hydration. After the
component mounts, Farm adopts those elements as keyed row instances.
Updating `items` then does not execute `Inventory` or its JSX row-render callback. Surviving rows
are found by key and their prepared bindings are patched directly. Missing keys remove only their
row, and new keys create only their prepared host tree. During a reorder, Farm calculates the
longest increasing subsequence (LIS) of the old row positions. Rows in that subsequence stay in
place; only the other surviving rows move. LIS is a runtime move planner over compiler-prepared
rows, not a claim that the future contents of an array are known at build time.
When an update keeps every row and changes only a few positions, such as swapping two rows, Farm
compares the new keys with the committed order position by position, confirms that the changed
positions only trade rows among themselves, and plans moves over those positions alone. A swap moves
two rows without building a set of every key. Every row's bindings are still reread, as React would
rerender them.
#### Key-directed selection updates
A separate state or primitive prop often identifies one active row while the collection itself
does not change:
```tsx
const [selectedId, setSelectedId] = useState(null);
{rows.map((row) => (
{row.label}
))}
;
```
For an exact `===` or `!==` comparison against the same expression used by `key`, the compiler
records which state or primitive-prop cell supplies the target. After mount, changing `selectedId`
looks up the previously selected key and the next selected key in the existing row-instance map.
Only those rows evaluate the affected class, attribute, style, or leaf-text binding. A 20,000-row
selection therefore performs at most two row-binding evaluations instead of scanning all 20,000
rows. The component and its `map()` callback still do not rerun.
This proof is intentionally narrow. The target must be read only as an operand of strict key
comparisons, the binding must have no second reactive dependency, and the target must not also
change the collection or its key projection. The runtime accepts only string, number, bigint, or
nullish targets. Object, array, boolean, ambiguous, mixed structural, React-owned, nested-block, and
unsupported expressions use the existing complete evaluation or React fallback. Missing keys are
safe and simply patch no next row. No option or component primitive is required. The compiler
report exposes the number of emitted row-binding proofs as `keyedIdentityTargets`.
For plain keyed rows using only one target kind, the compiler includes only that kind's target
runtime: identity, Set membership, or Map lookup. Identity-only selection does not retain the
Set/Map snapshot machinery. These paths keep two target snapshot maps instead of six. Rows
combining target kinds, row conditionals, nested host blocks, or structural update hints continue
using the complete runtime. This changes bundle and bookkeeping costs, not eligibility, update
semantics, or the normal React fallback; there is no new option to enable.
#### Key-directed Set membership updates
Multi-selection usually keeps several row keys in local state:
```tsx
const [markedIds, setMarkedIds] = useState(() => new Set());
{rows.map((row) => (
{row.label}
))}
;
```
For an exact `localSet.has(rowKey)` binding, the compiler records the local state cell and the row
key expression. The runtime snapshots the previous and next members and computes their symmetric
difference. Only rows whose membership changed evaluate that binding. Replacing two marked keys in
a 20,000-row table therefore touches at most four matching row instances instead of scanning every
row. The component and its `map()` callback do not rerun.
The proof accepts only a direct `has()` call on one local `useState` value with the exact expression
used by `key`. At runtime, targeting requires an ordinary native `Set` containing only string,
number, bigint, or nullish members. Set subclasses, proxies, own `has` overrides, object members,
different row fields, extra reactive dependencies, React-owned rows, nested blocks, and structural
key dependencies do not use this path. If a runtime value fails the native-Set guard, that keyed
boundary returns to React before compiled bindings are evaluated. This keeps custom collection
semantics and error handling under React ownership. No option or component primitive is required.
The report exposes the emitted binding count as `keyedMembershipTargets`.
#### Key-directed Map lookup updates
Per-row status and metadata often live in a local Map rather than on the row objects:
```tsx
const [statusById, setStatusById] = useState(() => new Map());
{rows.map((row) => (
{row.label}
))}
;
```
For an exact `localMap.get(rowKey)` binding, the compiler records the local state cell and row-key
expression. The runtime snapshots the previous and next entries and compares mapped values with
`Object.is`. Only keys whose visible lookup result changed evaluate the row binding. Status text,
validation messages, progress attributes, classes, and styles can therefore update without
evaluating the same lookup for every row. The component and its `map()` callback do not rerun.
Snapshot comparison still visits Map entries; this optimization removes the full row-binding and
DOM-target scan, not the application's Map construction or the runtime's entry comparison.
The proof accepts one local `useState` dependency and a direct `get()` call with the exact
expression used by `key`. At runtime, targeting requires an ordinary native `Map` with string,
number, bigint, or nullish keys and string, number, bigint, boolean, or nullish values. Map
subclasses, proxies, own `get` overrides, object values, different row fields, extra reactive
dependencies, React-owned rows, nested blocks, and structural key dependencies do not use this
path. A failed runtime guard returns that keyed boundary to React before compiled bindings run.
No option or component primitive is required. The report exposes the emitted binding count as
`keyedMapLookupTargets`.
When a key-directed identity, Set-membership, or Map-lookup refresh selects multiple binding
updates, the runtime prepares every selected value and resolves every selected DOM target before
committing the batch. A reader failure in a later selected row therefore leaves earlier rows
untouched, while an invalid target uses the complete React fallback. Preparation retains the same
changed-key set; it does not scan unaffected rows. Single-binding refreshes retain the direct path.
#### Producer-side Set and Map deltas
The Set-membership and Map-lookup paths above normally compare complete previous and next
snapshots to discover which keys changed. Farm can remove that second collection scan when it can
prove a compiler-owned immutable functional update:
```tsx
setMarkedIds((current) => {
const next = new Set(current);
if (next.has(id)) next.delete(id);
else next.add(id);
return next;
});
setStatusById((current) => new Map(current).set(id, "ready"));
```
The JavaScript written by the application still creates and mutates its fresh collection, so
`new Set(current)` and `new Map(current)` retain their normal cost and semantics. At build time,
the compiler wraps only proven native `Set.add`, `Set.delete`, `Map.set`, and `Map.delete` calls.
The generated metadata contains the keys whose mutations actually executed. At commit, the
runtime validates those keys against the previous collection and updates only matching keyed-row
bindings instead of walking every old and new entry to rediscover the delta.
Concise `new Set(current).add(key)` and `new Map(current).set(key, value)` updaters are supported.
A block updater may clone `current` once into a `const`, read `has`, `get`, or `size`, perform native
mutations, and return `current`, that clone, or a fresh same-kind collection. Queued functional
updates compose. Runtime snapshots use persistent change overlays and compact after a bounded
chain, so repeated updates do not build an unlimited lookup history.
The proof requires a native collection created by the same local `useState` declaration. Every
setter use for that state must be either a fresh same-kind replacement or a proven updater. Direct
state mutation, unknown setter results, state or draft escape, draft aliases, shadowed
constructors, collection subclasses/proxies, object keys, and object Map values disable the delta
path. A failed proof keeps the existing full snapshot comparison; a failed runtime safety check
returns the boundary to React before compiled binding reads. This is an internal optimization and
adds no component, directive, or configuration. Reports expose the number of wrapped native
mutation sites as `keyedCollectionUpdateHints`.
#### Mutation-aware same-order updates
The compiler can remove the runtime's second full-row scan for a common immutable update:
```tsx
setItems((current) =>
current
.map((item) => (item.id === targetId ? { ...item, label: nextLabel } : item))
.map((item) => (item.id === targetId ? { ...item, selected: !item.selected } : item)),
);
```
This needs no option or component primitive. At build time, Farm recognizes a functional setter on
the direct `useState` collection used by a compiled keyed map or `List`. The setter may be concise or
use a block containing exactly one value-returning `return`, and that returned expression may contain
one or more consecutive `map()` calls. Extra updater statements, conditional returns, or a missing
return keep complete keyed reconciliation. Every mapper must be an inline arrow whose returning
paths are conditional: at least one path returns the original item and another returns a new object
that spreads that item. This may be a concise expression or a structured block made from fully
returning `if` or `switch` branches plus immutable local `const` aliases. Each alias needs a simple
identifier and a compiler-safe initializer. A `switch` needs one `default`, a complete return from
every case, and no trailing statements. Consecutive empty case labels may share the next fully
returning body; a case that executes anything before falling through, or a final label with no body,
is rejected. Its discriminant, case tests, conditions, and replacement values must use the same safe
expression subset. The hint runtime is retained only in modules where at least one such call is
emitted; direct-only and ordinary keyed builds do not import that capability.
```tsx
setItems((current) =>
current.map((item) => {
switch (item.status) {
case "draft":
case "queued":
return { ...item, label: draftLabel };
case "published":
return { ...item, label: publishedLabel };
default:
return item;
}
}),
);
```
Every native `map()` still runs and is still O(n). After the complete chain succeeds, Farm compares
the committed and final item identities once, validates the final key and position for every
changed row, and patches each final row once. Intermediate arrays never receive DOM work. The
optimization removes the runtime's second full key-and-binding scan rather than removing the
application's map work. Multiple hinted functional updates queued in one compiler flush are
combined.
Farm preserves each source property lookup and call. It records metadata only after an exact native
`Array.prototype.map` succeeds on ordinary dense arrays. A custom method, sparse or subclassed
array, unsupported mapper anywhere in the chain, changed key, insert, removal, reorder, relevant
second dependency, or failed runtime check uses the existing complete keyed reconciliation and LIS
path. Native results and thrown mapper or method errors are preserved. Derived collections,
non-functional setters, referenced callbacks, mutable or destructured local declarations,
effectful initializers, other intermediate statements, partial or dangling fallthrough, mutating
replacements, and other unproven shapes also keep that existing path. This is an optimization hint, not a new
correctness contract or a way to bypass React fallback behavior. The compiler report exposes the
number of prepared map calls as `keyedMapUpdateHints`.
#### Keyed array append hints
A direct keyed `useState` array can also avoid rescanning all existing rows for common immutable
appends:
```tsx
setItems((current) => [...current, nextItem]);
setItems((current) => [...current, ...nextItems]);
setItems((current) => {
return [...current, ...nextItems];
});
```
At build time, Farm recognizes a concise functional setter or a setter block containing exactly one
direct value-returning `return`. Its returned array literal must start with exactly `...current` and
have at least one trailing item or spread. The application still creates its normal immutable array.
Generated metadata connects that result to the last committed array and records where its appended
suffix begins. Queued functional appends form one validated chain.
At update time, existing keyed rows already have the same item, key, and index. Farm therefore
reads keys, descriptors, and bindings only for the appended suffix, creates only those host rows,
and inserts them together with a document fragment. It does not rerun the owner component or touch
the existing row DOM.
The proof is intentionally narrow. Both values must be native arrays. Middle insertion, removal,
direct replacement, a copy with no appended entries, updater blocks with extra statements,
conditional returns, or no value-returning `return`, duplicate keys, React-owned or nested
host-block rows, row conditionals, and rows whose bindings read the collection itself keep complete
keyed reconciliation. Keys that read the collection also prevent the compiler from emitting the
hint. A preceding unhinted update, an unrelated dirty dependency, or any failed source/length check
also discards the hint. These fallbacks preserve normal React behavior; the syntax does not opt the
component into a different correctness model.
The compiler report exposes emitted sites as `keyedArrayAppendHints`, and the hinted runtime is
retained only when a module emits at least one append or same-order map hint.
Adjacent removal and append setters can share the same committed-row proof:
```tsx
setItems((current) => current.filter((item) => item.id !== expiredId));
setItems((current) => [...current, incoming]);
setItems((current) => current.slice(start, end));
setItems((current) => [...current, ...incoming]);
setItems((current) => current.slice(start, end));
setItems((current) => [...current, incoming]);
setItems((current) =>
current.map((item) => (item.id === targetId ? { ...item, label: nextLabel } : item)),
);
setItems((current) => current.filter((item) => item.id !== expiredId));
setItems((current) =>
current.map((item) => (item.id === targetId ? { ...item, label: nextLabel } : item)),
);
setItems((current) => [...current, incoming]);
```
The setters still execute in order and still create their normal native arrays. Before changing the
DOM, Farm validates the original committed token, every filter or slice survivor, the complete final
length, and every incoming key. It prepares all incoming keys, descriptors, bindings, and detached
host rows first; only then does it remove rejected rows, update survivor indexes, and append the new
suffix in one fragment. Existing survivors are neither rebound nor recreated, and additional
adjacent append setters are collapsed into the same final suffix. This keeps the unavoidable native
filter or slice work while removing the keyed runtime's second full scan.
One or more immediately adjacent safe same-key `map()` setters may run between the filter or slice
and the append, after the append, or in both positions. A safe map may also precede the structural
removal. Farm carries the original survivor indices or retained interval through those native maps
and records each replacement against its committed row. Before touching the DOM it validates the
complete dense result, every survivor identity, every changed key and binding, and every incoming
row. It then removes only rejected rows, patches only changed survivors, and creates the suffix from
its final values. The owner stays mounted, survivor DOM identity is preserved, and the suffix is
appended once.
Only concise updater results and blocks with one direct value-returning `return` that form one
direct chain for the same state array are linked. The row and key must be compiler-owned and
index-independent. A reorder in the structural-append chain, an
unsupported or non-adjacent map, an unhinted update to that state, another dirty row dependency,
collection-reading binding, custom, sparse, or subclassed array, nested or React-owned row,
duplicate final key, or reuse of any committed key in the appended suffix keeps complete React
reconciliation before a DOM write. A mapped survivor whose key changes also falls back before
mutation. No API or configuration is added. Compiler reports use the existing
`keyedArrayFilterHints`, `keyedArraySliceHints`, and `keyedArrayAppendHints` counts, and modules
without both accepted operations omit the composed runtime.
#### Keyed array prepend hints
A direct keyed `useState` array can avoid rescanning every existing row when new items are inserted
at the beginning:
```tsx
setItems((current) => [nextItem, ...current]);
setItems((current) => [...nextItems, ...current]);
setItems((current) => {
return [...nextItems, ...current];
});
setItems((current) => current.filter((item) => item.id !== expiredId));
setItems((current) => [nextItem, ...current]);
setItems((current) => current.slice(start, end));
setItems((current) => [...nextItems, ...current]);
setItems((current) => current.filter((item) => item.id !== expiredId));
setItems((current) => [nextItem, ...current]);
setItems((current) =>
current.map((item) => (item.id === targetId ? { ...item, label: nextLabel } : item)),
);
setItems((current) => current.slice(start, end));
setItems((current) =>
current.map((item) => (item.id === targetId ? { ...item, label: nextLabel } : item)),
);
setItems((current) => [nextItem, ...current]);
```
At build time, Farm recognizes a concise functional setter or a setter block containing exactly one
direct value-returning `return`. Its returned array literal must end with exactly `...current` and
have at least one leading item or spread. The application still creates its normal immutable array.
Generated metadata connects the result to the last committed array and records the prefix length.
Multiple hinted prepends queued before one compiler flush form one validated chain.
At update time, Farm verifies native arrays, source identity, lengths, and every existing suffix
item before changing the DOM. It reads keys, descriptors, and bindings only for the new prefix,
creates only those host rows, inserts them before the first existing row, and shifts the stored
indexes used by delegated row events. Existing row DOM is neither recreated nor rebound.
An immediately adjacent compiler-proven `filter()` or bounded `slice()` may feed one or more of
these prepends. Farm carries the original survivor positions or retained interval through the
queued setters. Before mutation it validates the committed token, the complete dense final array,
every survivor identity, and every prefix key, descriptor, and binding. It then removes rejected
rows, inserts the prepared prefix once, and updates survivor event indexes. Surviving rows keep
their exact DOM nodes and do not rerun their bindings.
One or more immediately adjacent safe same-key `map()` setters may run after the prepend or between
the removal and prepend. A safe map may also run immediately before the removal. Farm carries every
survivor back to its committed row, validates the complete dense result and all final keys and
bindings before mutation, then patches only changed survivors and creates the prefix from its final
mapped values. The component owner stays mounted and surviving DOM identity is preserved.
This proof requires compiler-owned host rows whose render callback and key do not read the row
index. Index-aware rows, collection-derived keys, collection-reading bindings, React-owned or
nested host-block rows, row conditionals, middle insertion, direct replacement, updater blocks with
extra statements, conditional returns, or no value-returning `return`, a reordered structural chain,
an unsupported or non-adjacent map, duplicate final keys,
reuse of any committed key in the prefix, custom, sparse, or subclassed arrays, an unrelated dirty
dependency, or any failed runtime check keeps complete keyed reconciliation before a DOM write. A
mapped survivor whose key changes and a prepend queued after an unhinted update also fall back.
Reports expose emitted sites as `keyedArrayPrependHints`; no option or component API is added, and
modules without the accepted removal, prepend, and map chain omit its mapped runtime.
#### Keyed array slice hints
A direct keyed `useState` array can retain a known window without rescanning all surviving rows:
```tsx
setItems((current) => current.slice(1_000));
setItems((current) => current.slice(0, -1_000));
setItems((current) => current.slice(2, 8));
setItems((current) => current.slice(-5));
const trimCount = pageSize * pagesToDiscard;
setItems((current) => current.slice(trimCount));
setItems((current) => current.slice(visible.start, visible.end));
setItems((current) => {
return current.slice(visible.start, visible.end);
});
```
At build time, Farm recognizes a concise functional setter or a setter block containing exactly one
direct value-returning `return`. The returned expression must directly call native `slice()` with
one or two safe-integer literals or compiler-safe runtime expressions. Identifiers, property reads,
side-effect-free arithmetic and conditionals, and safe `Math` calls are supported. User-defined
calls, assignments, update expressions, and other effectful forms are not transformed. Farm
preserves the original method lookup and argument evaluation order, evaluates each bound once, and
preserves the native call, coercion, return value, and thrown errors. Generated metadata records the
normalized retained interval only when every evaluated bound is already a safe integer, and links
multiple slice or filter updates queued before one compiler flush.
At update time, Farm validates the native arrays, committed source, queued lengths, interval, and
surviving item identities before changing the DOM. It removes only rows outside the interval,
updates stored indexes used by delegated row events, and preserves every surviving element. A
slice-only chain does not reread surviving keys, descriptors, or bindings, and the owner component
does not rerun.
The proof requires compiler-owned host rows whose render callback and key do not observe the row
index. Effectful bound expressions, evaluated bounds that are fractional, non-numeric, or otherwise
not safe integers, `slice()` without a bound, a literal no-op `slice(0)`, updater blocks with extra
statements, directives, conditional returns, or no value-returning `return`, chained updaters, custom
slice methods, sparse or subclassed arrays, collection-derived keys,
collection-reading bindings, React-owned row structures, nested host blocks, row conditionals,
unrelated dirty dependencies, and failed runtime validation keep complete keyed reconciliation.
A runtime bound that evaluates to a no-op still preserves the native result and uses complete
reconciliation. These checks make the metadata an optional optimization rather than a new behavior
contract. No configuration or component primitive is added. Reports expose emitted sites as
`keyedArraySliceHints`; slice reuses the existing removal-hint runtime so it does not add another
structural runtime combination.
#### Keyed array rolling-window hints
Queues, logs, charts, and fixed-size feeds often expire a prefix while adding new rows:
```tsx
setItems((current) => [...current.slice(1), nextItem]);
setItems((current) => [...current.slice(1_000), ...nextItems]);
const trimCount = pageSize * pagesToExpire;
setItems((current) => [...current.slice(trimCount), ...nextItems]);
setItems((current) => {
return [...current.slice(trimCount), ...nextItems];
});
```
At build time, Farm recognizes a concise functional setter or a setter block containing exactly one
direct value-returning `return`. The first array entry must spread a direct native
`current.slice(bound)`, and the remaining entries must be compiler-safe incoming values. The single
bound may be a safe-integer literal or a compiler-safe runtime expression: identifiers, property
reads, side-effect-free arithmetic and conditionals, and safe `Math` calls are supported. The
application still performs the same slice and array construction. Farm preserves method lookup and
argument evaluation order, evaluates the bound once, and records only metadata that connects the
final array to its committed source and retained interval.
At update time, Farm validates native arrays, the complete metadata chain back to the committed
source token, the exact retained tail, every retained item identity, and every final incoming key
before changing the DOM. Multiple rolling setters queued before one compiler flush collapse into
one cumulative prefix removal. Rows introduced by an earlier setter are created only if they remain
in the final suffix. Farm removes the expired committed prefix, updates stored event indexes,
preserves every retained element, and creates only that final incoming suffix. Incoming keys are
checked against the complete committed window; reusing an expired key takes full keyed
reconciliation so React key identity is preserved.
Safe same-key maps may be immediately adjacent before, after, or between one or more rolling
setters in the same synchronous setter segment:
```tsx
setItems((current) =>
current.map((item) => (item.id === editedId ? { ...item, label: nextLabel } : item)),
);
setItems((current) => [...current.slice(trimCount), ...nextItems]);
setItems((current) =>
current.map((item) => (item.id === selectedId ? { ...item, selected: true } : item)),
);
setItems((current) => [...current.slice(secondTrimCount), ...laterItems]);
setItems((current) =>
current.map((item) => (item.id === editedId ? { ...item, status: "ready" } : item)),
);
```
Each map may use a compiler-safe nested conditional to update several retained rows.
Farm links mapped retained items back to their committed rows, creates the incoming suffix from its
final mapped values, and prepares every changed binding and incoming row before the first live DOM
write. Unchanged survivors keep their elements, focus, selection, scopes, and delegated-event
indexes. One rolling setter lowers through the existing structural append/map runtime. A segment
with multiple rolling setters retains cumulative rolling-window metadata plus mapped provenance
through an optional runtime dedicated to mapped rolling chains. This adds no public helper,
configuration, or always-loaded browser feature.
The proof remains intentionally narrow: one compiler-safe slice bound, compiler-owned host rows,
and index-independent render and key callbacks. A second slice bound, literal zero, effectful bound
expressions, updater blocks with extra statements, directives, conditional returns, or no
value-returning `return`, custom slice behavior, sparse or subclassed arrays, queued chains
containing a mixed or unhinted intermediate update, collection-reading bindings, index-aware rows,
React-owned rows, nested host blocks, row conditionals, a statement or unsupported setter inside
the segment, unrelated dirty dependencies, changed mapped keys, and failed runtime validation all
keep complete keyed reconciliation. Runtime bounds that evaluate to a fractional, non-numeric,
unsafe, or no-op value preserve native results and use that fallback. No new component or option is
required. Reports expose each emitted rolling site as
`keyedArrayRollingWindowHints`, each rolling step retained across a multi-window mapped chain as
`keyedArrayMappedRollingWindowChainHints`, and each safe map as `keyedMapUpdateHints`; unmapped
rolling modules retain the smaller optional all-hint runtime.
#### Keyed array known-position hints
Native immutable array methods can state an exact insertion, removal, or replacement position:
```tsx
setItems((current) => current.toSpliced(selectedIndex, 0, nextItem));
setItems((current) => current.toSpliced(selectedIndex, 0, nextA, nextB));
setItems((current) => current.toSpliced(selectedIndex, 0, ...incomingItems));
setItems((current) => current.toSpliced(selectedIndex, 1));
setItems((current) => current.toSpliced(selectedIndex, 25));
setItems((current) => current.toSpliced(selectedIndex, 1, replacement));
setItems((current) => current.toSpliced(selectedIndex, 25, ...replacements));
setItems((current) => current.with(selectedIndex, replacement));
setItems((current) => {
return current.toSpliced(selectedIndex, 0, nextItem);
});
setItems((current) => {
return current.with(selectedIndex, replacement);
});
const deleteCount = visibleRows.length;
setItems((current) => current.toSpliced(selectedIndex, deleteCount, ...replacements));
// Two same-key windows may be queued before one compiler flush.
setItems((current) => current.toSpliced(firstIndex, 25, ...firstRefresh));
setItems((current) => current.toSpliced(secondIndex, 25, ...secondRefresh));
```
At build time, Farm recognizes concise functional setters or setter blocks containing exactly one
direct `return`. The position—and, for `toSpliced()`, delete count—must be a safe-integer literal or
compiler-safe runtime expression.
Identifiers, property reads,
side-effect-free arithmetic and conditionals, and safe `Math` calls are supported. User-defined
calls, assignments, update expressions, and other effectful forms are not transformed.
`toSpliced()` may insert compiler-safe items with a literal zero delete count, remove one item or a
contiguous range, replace exactly one item, or replace a positive window with compiler-safe
explicit items or a safe spread; `with()` must replace exactly one item. A literal zero delete count
with an explicit pair or a safe spread such as `...incomingItems` selects the batch insertion path
when at least two items are produced at runtime. A literal delete count above one with any incoming
item, a positive literal count with multiple items or a spread, or any compiler-safe runtime delete
count selects exact-window replacement; the spread may evaluate to zero, one, or many items. Farm
preserves the original method lookup,
evaluates every argument once in its original order, and preserves the native call, return value,
coercion, and thrown errors. The runtime records metadata only after the native call proves that the
evaluated position is already a safe integer and the evaluated delete count is already a positive
safe integer. A custom method or a count that is zero, negative, fractional, non-numeric, or
otherwise unsafe still runs normally but takes complete keyed reconciliation.
At update time, Farm validates the committed native source, result length, source token, normalized
position, clamped removal count, and any incoming key before changing the DOM. For a batch, Farm
checks existing-key collisions against the committed row map and keeps a temporary set of only
the incoming batch's keys. It does not copy every existing key into that set. Complete source-row
validation still runs, and Farm computes every incoming key, descriptor, binding snapshot, and
detached host row before mutating the live tree. Duplicate incoming keys or collisions with
existing keys therefore take complete reconciliation without a partial insertion. Valid rows
are mounted in one document fragment;
surrounding elements remain connected and only stored suffix indexes shift. Exact-window
replacement with fresh keys removes only the proven old interval after every incoming row is
prepared. If the incoming interval has the same length and exactly the same keys in the same order,
Farm first evaluates all keys and binding snapshots and resolves every changed target across the
complete interval. It then patches only changed bindings in place and updates each stored row
object, so later delegated or cached handlers observe the latest data. No descriptor or DOM row is
created, and every row keeps its identity, focus, and text selection. Validated same-key row and
window refreshes also keep the existing row map and element lookup, and skip redundant cache
cleanup after the bindings are patched. Source and key validation still run, and each flush commits
the new collection token so subsequent updates use current state.
Structural changes retain index rebuilding and cache cleanup. A window may instead grow or
shrink while it reorders keys from inside its own removed interval and mixes them with globally
fresh keys. Farm prepares all reused binding updates, new descriptors, binding snapshots, and
detached rows before the first DOM write. It removes only retired rows, preserves each reused row,
batches adjacent new rows in a fragment, updates shifted suffix indexes, and applies LIS only to
the reused part of that interval so it moves the fewest connected rows needed by the local
permutation. Rows outside the interval are not rerendered or rebound. Multiple length-preserving
same-key windows queued before one compiler flush compose into one atomic refresh. Fixed-length
queued windows may mix same-key rows with globally new final keys, and both disjoint and
overlapping windows are supported. An overlapping position uses the last queued value;
intermediate identities are never mounted. Farm validates the complete chain and final key set,
using the committed row map directly for key collisions instead of copying every existing key
into a temporary set. For length-preserving queued windows, it sorts the window ranges and walks
them alongside the rows, without building a set of touched positions or sorting those positions.
Overlapping and contained ranges prepare each final position once, in row order. This removes
bookkeeping, not the full-chain or untouched-row checks: every row is still validated before
preparation. It then prepares every touched key, binding value, DOM target, new descriptor, binding
snapshot, and disconnected DOM row before the first write. It patches same-key positions and swaps only final
fresh-key positions. Untouched rows retain their identity. Duplicate final keys and keys reused
from outside a single removed interval take complete reconciliation before fast-path mutation. A
queued chain may also contain disjoint grow or shrink windows. Farm maps every immediate-source
position through earlier length changes, proves that the source and final intervals remain
disjoint, and prepares all local key reuse, fresh rows, binding updates, cleanup, and per-window LIS
moves before changing the DOM. Adjacent windows and empty incoming intervals remain eligible. An
overlapping structural window or a key transferred between windows keeps complete reconciliation.
A single insertion
creates one row at that position. A removal cleans up and removes only the known row or contiguous
range while preserving every
surviving element. A same-key replacement patches that row in place; a new-key replacement creates
and swaps one host row. The owner component does not rerun, and surviving row keys, descriptors,
and bindings are not reread.
The proof requires compiler-owned host rows whose render and key do not observe the row index.
Effectful position or delete-count expressions, runtime positions that are fractional or otherwise
not safe integers, runtime delete counts that are zero, negative, fractional, non-numeric, or
otherwise not positive safe integers, other `toSpliced()` shapes, updater blocks with extra
statements, directives, conditional returns, or no value-returning `return`, unsafe incoming
expressions, custom methods, overlapping queued structural windows,
unhinted intermediate updates, an existing key moved from outside its local removed interval or
between queued windows, duplicate final keys, collection-reading bindings, React-owned rows,
nested host blocks, row conditionals, unrelated dirty dependencies, and failed runtime checks keep
complete keyed reconciliation.
Negative safe-integer positions and counts larger than the remaining suffix use the native
method's normal clamping rules. No new option or component is required. Reports expose emitted
sites as `keyedArrayPositionHints`. Batch insertion and exact-window replacement select
progressively separate optional runtime capabilities, so modules with only single-row operations
or batch insertion retain no window-replacement runtime.
#### Keyed array reorder hints
A direct native reverse states the complete next order without changing keyed row identity:
```tsx
setItems((current) => current.toReversed());
setItems((current) => {
return current.toReversed();
});
```
Farm recognizes the concise functional-setter form and a setter block containing exactly one direct
`return`. It preserves the original method lookup, native call, returned array, and thrown errors.
Metadata is recorded only when the result is an ordinary native array, the executed method is the
native `toReversed()` method, and the reorder chain starts at the committed collection. A custom or
unavailable method therefore keeps its normal behavior and never enters the fast path.
At update time, Farm verifies the committed source token, equal lengths, every source row identity,
and the exact reversed result before moving the DOM. The runtime leaves one row in place and moves
the other rows through connected `insertBefore()` operations, the minimum `n - 1` moves for a
reverse. It does not call row keys, recreate descriptors, reread bindings, or run the generic LIS
calculation. Existing elements, handlers, form state, and focus stay attached to their keys.
Multiple concise native reorder setters may run before the same compiler flush:
```tsx
setItems((current) => current.toSorted((left, right) => left.rank - right.rank));
setItems((current) => current.toReversed());
```
Each setter still executes in order with normal JavaScript semantics. Farm carries the original
committed token through consecutive native `toSorted()` and `toReversed()` results, validates the
final array as the exact same set of unique item identities, and reconciles that final order once.
Intermediate orders never reach the DOM. For a chain made only of reversals, Farm tracks whether
the final order is exactly the committed order or its reverse. An even count validates identity and
does not build the generic item map, run LIS, or move a DOM node. An odd count validates reverse and
uses the specialized minimum `n - 1` move path. Any sort makes the final order a general
permutation, so that path still uses LIS.
The same proof also works when two or more native reorder operations are chained inside one concise
functional setter or a setter block containing exactly one direct value-returning `return`:
```tsx
setItems((current) => current.toSorted((left, right) => left.rank - right.rank).toReversed());
setItems((current) => {
return current.toSorted((left, right) => left.rank - right.rank).toReversed();
});
```
Farm prepares this pipeline at build time and evaluates each property lookup, inline comparator,
and native call in its original JavaScript order. The intermediate arrays do not reach the DOM.
The runtime validates only the final order against the committed collection. A cancelling
`current.toReversed().toReversed()` pipeline uses the exact-identity path described above; mixed
sort/reverse pipelines apply one LIS-based reconciliation.
A compiler-safe `filter()` or bounded `slice()` prefix may run before one or more native reorder
steps in the same concise setter or exact one-return block. The filter predicate may itself be a
concise expression or an exact one-return block:
```tsx
setItems((current) =>
current
.filter((item) => {
return item.visible;
})
.toSorted((left, right) => left.rank - right.rank)
.toReversed(),
);
```
Farm executes every native method normally, carries the structural survivor proof into the final
reorder result, and validates the complete operation before touching the DOM. It removes only
rejected rows, uses LIS once for the surviving final order, and preserves every surviving element,
handler, and form control without recreating descriptors or rereading bindings. Concise or exact
one-return filter/slice and reorder setters in the same batch use the same proof.
The first proof requires compiler-owned host rows whose render and key do not observe the index.
Arguments to `toReversed()`, referenced comparators, computed methods, chains containing a method
outside the supported `filter()`/`slice()` prefix and `toSorted()`/`toReversed()` suffix,
updater blocks with extra statements, directives, conditional returns, or no returned value,
subclassed or sparse behavior, collection-reading bindings, custom methods, structural calls after
reordering, an unhinted intermediate update, React-owned rows, nested host blocks, row conditionals,
unrelated dirty dependencies, and any identity mismatch use complete keyed reconciliation. No
option or component is added. Reports count every compiled structural and reorder step in its
existing hint counter; modules without those steps do not retain their optional runtimes. The
application runtime must provide `Array.prototype.toReversed`; Farm does not polyfill it.
#### Same-key map and reorder pipelines
A common data-table update changes one row and immediately restores a sorted order:
```tsx
setItems((current) =>
current
.map((item) => (item.id === editedId ? { ...item, label: nextLabel } : item))
.map((item) => (item.id === editedId ? { ...item, rank: nextRank } : item))
.toSorted((left, right) => left.rank - right.rank),
);
```
For a concise functional setter or a setter block containing exactly one direct `return`, Farm can
prepare one or more consecutive safe same-key `map()` calls before or after native `toSorted()` or
`toReversed()` calls as one update pipeline.
JavaScript still performs every map and reorder normally. For two or more accepted maps, the
compiler runtime checks each native call as it completes but records replacement lineage only once,
by comparing the input and final result of each consecutive map segment. The intermediate arrays
need no separate full scan, and the final replacements still point directly to their committed
source rows. The complete pipeline then needs one final keyed reconciliation rather than a growing
chain of intermediate snapshots.
One callback may select several rows with nested expressions, structured early returns, or a fully
returning `switch`:
```tsx
setItems((current) =>
current.map((item) => {
const matchesReviewed = item.id === reviewedId;
if (matchesReviewed) return { ...item, status: "reviewed" };
const matchesEscalated = item.id === escalatedId;
if (matchesEscalated) {
return { ...item, status: "escalated", priority: 1 };
}
return item;
}),
);
```
The compiler recursively proves every condition and leaf. Each leaf must return the original item
or a compiler-safe object spread of that item, with at least one unchanged and one replacement
path. Block bodies may also introduce local `const` aliases with simple identifier bindings and
compiler-safe initializers. Mutable or destructured declarations, object/array/function literals,
unknown calls, loops, mutation, partial or dangling fallthrough, and any other effectful or ambiguous
control flow keep complete keyed reconciliation. Runtime key validation remains atomic, so a
replacement that changes its key falls back before the first DOM write.
Before changing the DOM, the runtime verifies ordinary dense arrays, exact native methods, the
committed collection token, equal lengths, a unique one-to-one source-item match, and the key of
every replacement item. It prepares all changed binding values and DOM targets first, runs one LIS
reconciliation for the final order, and patches bindings only for rows whose item identity changed.
Unchanged rows need no second key or binding read. Existing row elements, delegated handlers,
controlled inputs, focus, and text selection stay attached to their keys. Multiple supported
map-and-reorder setters queued before one compiler flush compose against the same committed
collection and expose only the final state.
Safe maps can also appear before, between, or after index-independent filter and slice steps. A
final native reorder is optional:
```tsx
setItems((current) =>
current
.filter((item) => item.visible)
.map((item) => (item.id === editedId ? { ...item, label: nextLabel } : item))
.slice(0, limit)
.toSorted((left, right) => left.rank - right.rank),
);
setItems((current) =>
current
.map((item) => (item.id === editedId ? { ...item, label: nextLabel } : item))
.filter((item) => item.visible)
.slice(0, limit),
);
```
Each callback still evaluates in normal JavaScript order. Farm carries both proofs across the
pipeline: which committed rows survived and which surviving items replaced their source items. It
validates every survivor and key before the first DOM write, removes rejected rows, performs LIS
moves only when a reorder needs them, and patches bindings only for changed survivors. A changed
item that a later structural step removes needs no row patch.
Structural and map work may also be split across adjacent setter calls in either order:
```tsx
// Map, then structural work.
setItems((current) =>
current.map((item) => (item.id === editedId ? { ...item, label: nextLabel } : item)),
);
setItems((current) => current.filter((item) => item.visible));
setItems((current) => current.slice(0, limit));
// Structural work, then maps.
setItems((current) => current.filter((item) => item.visible));
setItems((current) => current.slice(0, limit));
setItems((current) =>
current.map((item) => (item.id === editedId ? { ...item, label: nextLabel } : item)),
);
setItems((current) =>
current.map((item) => (item.id === editedId ? { ...item, rank: nextRank } : item)),
);
```
Farm links only consecutive calls to the same setter. A leading map retains its first committed
source through later structural work; a terminal map consumes the saved survivor lineage from the
preceding filter or slice. Multiple safe steps in either segment may share the proof, and mixed
map/structural/map sequences compose. Every result and key is validated before the queued commit
touches the DOM. An intervening statement, another setter, an unsupported callback, a changed key,
or any failed runtime proof keeps complete reconciliation.
That survivor proof may continue through adjacent native reorder setters too:
```tsx
setItems((current) => current.filter((item) => item.visible));
setItems((current) =>
current.map((item) => (item.id === editedId ? { ...item, rank: nextRank } : item)),
);
setItems((current) => current.toSorted((left, right) => left.rank - right.rank));
setItems((current) => current.toReversed());
```
Farm keeps the retained-row positions and same-key replacements attached to the same committed
collection. The final update removes rejected rows, patches changed survivors, and applies the
resulting order in one validated DOM transaction. Exact reverse chains use the minimum-move reverse
path; an arbitrary sort uses one source lookup and LIS. The native setters still run in order. If
the calls are not adjacent, target another state value, use an unsupported callback or method, or
fail a runtime shape/key check, Farm discards the proof and performs complete reconciliation.
A safe map may also be the final pipeline step:
```tsx
setItems((current) =>
current
.toReversed()
.map((item) => (item.id === editedId ? { ...item, label: nextLabel } : item))
.map((item) => (item.id === editedId ? { ...item, rank: nextRank } : item)),
);
```
Here the maps retain the preceding reorder lineage instead of turning the final value into an
unhinted snapshot. An exact reverse uses the direct minimum-move reverse path and patches only
changed rows. An earlier sort retains its general permutation proof, so Farm creates one
source-item lookup, runs LIS once, and still skips key and binding reads for unchanged rows. Map
segments on both sides of a reorder flatten replacements back to the same committed source rows.
The same proof can cross adjacent setter calls in one synchronous block:
```tsx
setItems((current) => current.toReversed());
setItems((current) =>
current.map((item) => (item.id === editedId ? { ...item, label: nextLabel } : item)),
);
setItems((current) =>
current.map((item) => (item.id === editedId ? { ...item, rank: nextRank } : item)),
);
```
Farm links only consecutive concise calls to the same setter. Each accepted standalone map keeps
the earlier reorder token, so an exact reverse still takes the direct minimum-move path and a sort
still performs one validated lookup and LIS. Adjacent compiler-safe filter or slice work switches
the chain to the structural proof described above. An intervening statement, a different setter,
an unsupported map, or host-backed/nested row structure ends the specialized chain and preserves
the existing complete fallback. Map-only components do not retain the optional map-and-reorder
runtime.
The maps may come first as separate queued setters too:
```tsx
setItems((current) =>
current.map((item) => (item.id === editedId ? { ...item, label: nextLabel } : item)),
);
setItems((current) =>
current.map((item) => (item.id === editedId ? { ...item, rank: nextRank } : item)),
);
setItems((current) => current.toReversed());
```
Farm records safe replacement lineage from the committed collection, then carries it into the
following native reverse or sort. This produces the same final result as React's queued functional
setters while reconciling the keyed block once. Only adjacent concise calls to the same setter are
linked; any statement or unsupported update between them keeps the existing fallback.
The mapped lineage can continue through more than one adjacent native reorder setter:
```tsx
setItems((current) =>
current.map((item) => (item.id === editedId ? { ...item, rank: nextRank } : item)),
);
setItems((current) => current.toReversed());
setItems((current) => current.toSorted((left, right) => left.rank - right.rank));
setItems((current) => current.toReversed());
```
Farm still executes every updater and native method in order. Each accepted reverse or sort carries
the same committed-row proof forward, so the final value needs one validated keyed reconciliation
rather than losing map lineage after the first reorder. A `map().toReversed()` pipeline can start
the same adjacent chain. Adjacent compiler-safe filter or slice work changes this into a structural
chain while retaining the committed source. An intervening statement, another setter, or an
unsupported method ends the chain before later setters are considered.
Exact reverse proof can also cross a setter boundary in the same batch:
```tsx
setItems((current) => current.toReversed());
setItems((current) =>
current.map((item) => (item.id === editedId ? { ...item, label: nextLabel } : item)).toReversed(),
);
```
When the maps are followed directly by `toReversed()`, their same-order lineage proves the exact
final permutation. Farm validates each mirrored source item and every changed replacement before
the first DOM write, then uses the minimum-move reverse operation directly. It does not allocate a
second source-item lookup map or run LIS for that case. Further exact reversals toggle the proof:
two reversals patch changed rows in committed order with zero DOM moves, while three use the exact
reverse path. The runtime now retains that exact identity-or-reverse proof across separate queued
setters too. For example, a queued reverse followed by a safe map and another reverse patches the
changed row in committed order without moving DOM rows or constructing the generic source map. A
sort or any other order ambiguity keeps the general permutation path.
The setter may be concise or a block with exactly one direct value-returning `return`. The proof
requires every map callback to be inline, synchronous, compiler-safe, and to return the
original item on one conditional path and an object-spread replacement on another. Concise
expressions and structured blocks containing proven local `const` aliases plus fully returning `if`
or `switch` branches are accepted. It requires compiler-owned host rows whose render and key do not observe the index.
Referenced callbacks, mutable, destructured, or effectful declarations, other intermediate
statements, partial or dangling fallthrough, unconditional replacements, changed or duplicate keys,
`thisArg`, maps after structural steps, computed or custom methods, sparse or subclassed arrays,
collection-reading bindings, React-owned rows, nested host blocks, row conditionals, unrelated dirty
dependencies, or failed runtime validation use complete keyed reconciliation before any fast-path
DOM write.
No API or option is added. Reports count the prepared map and reorder calls through the existing
`keyedMapUpdateHints`, `keyedArraySortHints`, and `keyedArrayReorderHints` fields. Modules that do
not contain a supported map-and-reorder pipeline do not retain its optional runtime. Farm does not
polyfill `Array.prototype.toSorted` or `Array.prototype.toReversed`.
#### Keyed array sort hints
A direct native immutable sort can reuse every keyed row while changing only its DOM position:
```tsx
setItems((current) => current.toSorted((left, right) => left.rank - right.rank));
setLabels((current) => current.toSorted());
setItems((current) => {
return current.toSorted((left, right) => left.rank - right.rank);
});
```
Farm recognizes a concise functional setter or a setter block containing exactly one direct
`return`, with either no comparator or an inline synchronous comparator from the compiler's safe
expression subset. It preserves the original method lookup, comparator execution, native result,
stable-sort behavior, and thrown errors. The native sort still does the comparison work; this
optimization removes repeated keyed-row work after the result is known.
At commit time, Farm verifies an ordinary dense array whose reorder chain starts at the committed
collection, the native `toSorted()` method, equal lengths, and a one-to-one identity match between
the committed and final items. It then computes the longest increasing subsequence of the resulting
permutation and moves only the rows outside that subsequence. Consecutive concise native sorts and
reverses queued before one flush, or chained in one concise updater, share this final
reconciliation. Keys, descriptors, and bindings are not reread, the owner component does not rerun,
and existing elements, handlers, form state, focus, and text selection remain attached to their
rows.
This proof requires compiler-owned host rows whose render and key do not observe the row index.
Referenced comparators, updater blocks with extra statements, directives, conditional returns, or
no returned value, computed methods, custom methods, sparse or subclassed arrays, duplicate item
identities, collection-reading bindings, an unhinted intermediate update, structural calls after
reordering, React-owned rows, nested host blocks, row conditionals, unrelated dirty dependencies,
and failed validation keep complete keyed reconciliation. Native sort/reverse chains may start with
compiler-safe `filter()` and bounded `slice()` calls; other chained calls fall back. Reports count
each compiled sort step as a `keyedArraySortHints` entry. Sort shares the optional reorder runtime,
and Farm does not polyfill `Array.prototype.toSorted`.
#### Keyed array filter hints
A concise or single-return block-bodied immutable filter on a direct keyed `useState` array can
remove rows without rebuilding every surviving row:
```tsx
setItems((current) => current.filter((item) => item.id !== removedId));
setItems((current) => {
return current.filter((item) => item.id !== removedId);
});
setItems((current) =>
current.filter((item) => {
return item.id !== removedId;
}),
);
```
At build time, Farm recognizes a concise functional setter or a setter block containing exactly one
direct value-returning `return`. The returned expression must directly call native `filter()` with
a synchronous, one-parameter predicate from the compiler's safe expression subset. The predicate
may be a concise expression or a block containing exactly one direct value-returning `return`. The
native `filter()` still runs normally. Its generated wrapper records rejected positions and links
queued filters to the last committed array.
At update time, Farm validates the native-array chain, result lengths, surviving item identities,
and surviving keys before changing the DOM. It then removes only rejected row elements, updates
the stored positions used by delegated row events, and keeps all surviving elements in place. Row
descriptors and bindings are not recreated or reread, and the owner component does not rerun.
The proof applies only to compiler-owned host rows whose render callback and key do not observe the
row index. An index-aware row or predicate, collection-derived key, updater or predicate block with
extra statements, directives, conditional returns, or no value-returning `return`, custom filter
method, sparse or subclassed array, binding that reads the collection, React-owned row structure,
nested host block, row conditional, unrelated dirty dependency, or failed runtime validation keeps
complete keyed reconciliation. A filter queued after an unhinted update also falls back. These
checks make the hint an internal optimization rather than a new behavior contract.
Reports expose emitted sites as `keyedArrayFilterHints`; the optional hinted runtime is retained only
when a module emits a supported update hint.
#### Interactive host rows
An otherwise eligible host-only row may contain inline synchronous React events:
```tsx
export function Inventory() {
const [items, setItems] = useState(initialItems);
return (
{items.map((item, index) => (
{item.label}
))}
);
}
```
This uses a hybrid ownership model. React creates or hydrates every row, installs the event props,
and performs every structural insert, removal, or reorder. Farm does not call `addEventListener`
and does not create an eventful row outside React's Fiber tree. At build time, the compiler replaces
each eligible row event prop with a stable keyed proxy and prepares the row's ordinary bindings.
When React dispatches the event, the proxy resolves that key's current row instance and passes the
latest item and index to the original handler. Replacing `{ id: "a", label: "Alpha" }` with a new
object for key `"a"`, or moving it to a new index, therefore cannot leave the handler with the item
or index captured by an older map execution.
If an update keeps the exact key sequence, Farm patches changed text, attributes, and styles without
executing the owner component or map callback. If keys are inserted, removed, or reordered, the
internal boundary renders once and lets React reconcile. After that commit, Farm validates and
re-adopts the host rows, reapplies every current binding, and resumes direct same-key updates. The
reapply step is important because React compares its next props with its previous virtual props,
which may predate a direct DOM patch.
The initial event contract is deliberately conservative: the row and descendants must still be a
statically known HTML host tree; the handler must be inline, synchronous, and free of Hooks,
`this`, `super`, and `arguments`. Non-inline or async handlers, custom row components, fragments,
refs, SVG, spreads, and other unproven shapes use the React-owned keyed boundary. The same hybrid
path is available to an eligible inline host row rendered through `List`.
#### Controlled fields in keyed rows
An eligible host row can contain ordinary controlled form fields:
```tsx
```
React still creates or hydrates the controls, dispatches `change`, `input`, selection, and
composition events, and reconciles any key insertion, removal, or reorder. Farm prepares the
`value` and `checked` property bindings at build time. A same-key edit flushes the collection cell,
looks up that row instance, and writes only the affected form properties and dependent row output;
the owner component and map do not execute again.
This is property-based rather than attribute-only. Text inputs and textareas update `.value`,
checkboxes and radios update `.checked`, and controlled single or multiple selects update their
selected options. The runtime avoids assigning an equal value, captures the focused text control's
selection before the compiler microtask, and restores the range after its keyed boundary commits.
Composition handlers remain React event props, so IME event order is unchanged.
React exposes `event.currentTarget` only while an event handler is running. If a functional
compiler-state updater refers to one of its properties, the transform snapshots that property read
before queuing the updater. This preserves the common keyed update shown above without retaining or
replaying the SyntheticEvent, and it prevents React's controlled-field restoration from changing a
deferred `.value` or `.checked` read.
The initial optimized contract requires a static input `type` and static `