@farm.js/react 0.1.0-beta.3 → 0.1.0-beta.30

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -3,7 +3,7 @@
3
3
  React renderer integration for FARMJS, including the experimental AOT compiler.
4
4
 
5
5
  React remains the default renderer and needs no package or configuration. Install this package only
6
- when opting into the compiler experiment:
6
+ when opting into the compiler:
7
7
 
8
8
  ```bash
9
9
  pnpm add @farm.js/react
@@ -15,26 +15,66 @@ import { react } from "@farm.js/react";
15
15
 
16
16
  export default defineConfig({
17
17
  renderer: react({
18
- experimental: {
19
- compiler: true,
20
- },
18
+ compiler: true,
21
19
  }),
22
20
  });
23
21
  ```
24
22
 
25
23
  `compiler: true` uses inference: every application TSX/JSX component is considered, eligible
26
- components are compiled, and everything else keeps the normal React path.
24
+ components are compiled with hybrid reactivity, and everything else keeps the normal React path.
25
+
26
+ The compiler is experimental and stays off when this option is omitted or `false`. The former
27
+ `react({ experimental: { compiler } })` spelling remains a deprecated alias with the same options
28
+ and a one-time warning. Do not configure both spellings, even when one is `false`.
29
+
30
+ ### Compatibility and upgrades
31
+
32
+ `react({ compiler })`, `ReactCompilerOptions`, and `List` from `@farm.js/react/list` are the
33
+ application-facing API. Both inference and annotation mode, static and hybrid reactivity, fallback
34
+ diagnostics, and coverage reporting remain supported. Annotation and static mode are advanced
35
+ options, not separate experimental APIs. The package is independently versioned; a prerelease
36
+ version remains a beta until its stable release is published.
37
+
38
+ The compiler and `@farm.js/react/compiler-runtime` ship together. Generated definitions must use
39
+ the runtime from the same installed package version; they are not a cross-version interchange
40
+ format. Upgrade the package and rebuild the complete app, including SSR and browser output,
41
+ together. Do not copy generated compiler output between package versions or deploy a new server
42
+ with an old browser build. Existing runtime exports remain available, but prefer ordinary React
43
+ source over hand-authored compiler definitions.
44
+
45
+ Hybrid reactivity starts from the compiler's proven state-to-binding dependency lists, then marks
46
+ only multi-state short-circuit bindings for runtime read tracking. For
47
+ `enabled ? activeValue : inactiveValue`, an update to the inactive value does not schedule the
48
+ binding. The runtime uses direct subscription indexes rather than proxies or a component-wide
49
+ scan. Use `compiler: { reactivity: "static" }` to retain only the complete build-time dependency
50
+ lists for comparison or diagnosis.
51
+
52
+ Compiler output also selects its runtime capabilities at build time. A direct counter imports only
53
+ the cell scheduler and direct-binding core; conditionals, keyed rows and LIS, nested host ranges,
54
+ and component islands are retained only when a compiled component in that module needs them. Plain
55
+ keyed rows omit the larger recursive-host and row-conditional extensions. This selection is
56
+ automatic and does not add a configuration option or asynchronous runtime loading. The legacy
57
+ `createCompiledComponent` export remains a complete compatibility entry for hand-authored
58
+ definitions, while generated code uses the tree-shakable feature entry.
59
+
60
+ Plain keyed lists with filter hints and only identity-based selection also use the single-kind
61
+ target runtime. Filtering keeps its existing native-method checks and fallback; mixed Set/Map
62
+ targets, conditional rows, and nested host blocks keep their existing runtime capabilities.
63
+
64
+ The persisted production-size fixtures and regression gate live in
65
+ [`RUNTIME_SIZE_RESULTS.md`](./RUNTIME_SIZE_RESULTS.md). The recorded compiler-selected core runtime
66
+ premium is 85.4% smaller than the complete compatibility runtime premium; the feature-heavy keyed
67
+ benchmark application removes 6,185 gzip bytes from its previous compiler-on build.
27
68
 
28
69
  For selective adoption, use annotation mode:
29
70
 
30
71
  ```ts
31
72
  renderer: react({
32
- experimental: {
33
- compiler: {
34
- mode: "annotation",
35
- directive: "use compiler",
36
- onUnsupported: "warn",
37
- },
73
+ compiler: {
74
+ mode: "annotation",
75
+ directive: "use compiler",
76
+ onUnsupported: "warn",
77
+ reactivity: "hybrid",
38
78
  },
39
79
  }),
40
80
  ```
@@ -56,6 +96,7 @@ The current compiler handles components that it can prove have:
56
96
  - one host-element root and a statically known host-element tree around supported conditional,
57
97
  keyed-list, and React component-island boundaries;
58
98
  - an identifier props parameter or flat object destructuring with aliases and defaults;
99
+ - build-time dependency cells for referenced flat primitive props, with runtime identity guards;
59
100
  - top-level `useState` declarations;
60
101
  - optional compiler-safe derived `const` values declared after state and in source order;
61
102
  - whitelisted `Boolean`, `Number`, `String`, and deterministic `Math` calculations;
@@ -67,19 +108,25 @@ The current compiler handles components that it can prove have:
67
108
  - item-keyed `collection.map(...)` children and explicit `List` boundaries at statically known
68
109
  container locations, including supported non-mutating collection pipelines;
69
110
  - inline synchronous events inside otherwise eligible host-only keyed rows;
70
- - row-local logical and ternary host branches inside stable keyed-row containers;
111
+ - multiple and recursively nested logical or ternary host branches inside non-interactive keyed
112
+ rows, including branches beside static host siblings;
71
113
  - stable module-level child components with compiler-safe props;
72
114
  - React-managed event handlers; and
73
115
  - no refs, effects, or unsupported dynamic child structures.
74
116
 
75
- The generated component preserves React ownership of initial placement, props, events, SSR, and
76
- hydration. Local state cells batch updates into a microtask and patch only compiler-known DOM
77
- targets. Proven host containers can transfer child ownership after mount for host-only conditional
78
- branches and ranges, plus non-interactive host-only keyed rows. An interactive row or a row with
79
- local conditional slots uses a hybrid boundary instead: React retains its events, conditional
80
- Fibers, and structural reconciliation, while Farm patches same-key bindings and refreshes only
81
- changed row-local branches. React still creates or hydrates all initial DOM. Anything outside those
82
- narrow contracts uses a small React-owned boundary or the complete original component.
117
+ The generated component preserves React ownership of initial placement, parent update commits,
118
+ identity-bearing props, events, SSR, and hydration. Local state cells batch updates into a
119
+ microtask; eligible flat destructured primitive props join the same dependency index after React
120
+ commits their parent update. The runtime skips unchanged binding output and patches only
121
+ compiler-known DOM targets. Objects, arrays, functions, symbols, React elements, `children`, and
122
+ identifier props retain the normal React prop-render path. Proven host containers
123
+ can transfer child ownership after mount for host-only conditional
124
+ branches and ranges, plus non-interactive host-only keyed rows and their recursively nested host
125
+ conditions. An interactive row uses a hybrid boundary instead: React retains its events,
126
+ conditional Fibers, and structural reconciliation, while Farm patches same-key bindings and
127
+ refreshes only changed React-owned row-local branches. React still creates or hydrates all initial
128
+ DOM. Anything outside those narrow contracts uses a small React-owned boundary or the complete
129
+ original component.
83
130
 
84
131
  For a common dedicated conditional, no new component or annotation is required:
85
132
 
@@ -134,6 +181,696 @@ Later list updates patch surviving rows by key, create or remove only the change
134
181
  longest increasing subsequence (LIS) to minimize DOM moves during a reorder. The outer user
135
182
  component and the list callback do not rerun for those compiler-cell updates.
136
183
 
184
+ When a separate state cell or primitive prop is compared with the exact row-key expression using
185
+ `===` or `!==`, the compiler emits a key-directed binding proof. A selection change such as
186
+ `item.id === selectedId` then looks up only the previously selected and newly selected row
187
+ instances. Class, attribute, style, and leaf-text bindings on those rows update without evaluating
188
+ the other keyed instances. The proof requires one reactive target used only in strict comparisons;
189
+ mixed structural dependencies, ambiguous expressions, non-primitive runtime targets, React-owned
190
+ rows, and unsupported shapes keep the complete scan or React fallback. No option is required, and
191
+ the compiler report exposes the emitted binding count as `keyedIdentityTargets`.
192
+
193
+ For multi-selection, an exact local-state expression such as `markedIds.has(item.id)` receives a
194
+ separate Set-membership proof. The runtime compares the previous and next native `Set` snapshots and
195
+ patches only row keys in their symmetric difference. It accepts ordinary native sets containing
196
+ primitive keys. Different fields, extra reactive dependencies, Set subclasses or proxies, object
197
+ members, customized `has` behavior, React-owned rows, nested blocks, and structural dependencies
198
+ stay on the existing complete or React-owned paths. The compiler report exposes this count as
199
+ `keyedMembershipTargets`.
200
+
201
+ For per-row data, an exact local-state expression such as `statusById.get(item.id)` receives a
202
+ separate Map-lookup proof. The runtime compares the previous and next native `Map` snapshots and
203
+ patches only row keys whose mapped primitive value changed. It accepts ordinary native maps with
204
+ primitive keys and primitive or nullish values. Different fields, extra dependencies, Map
205
+ subclasses or proxies, object values, customized `get` behavior, React-owned rows, nested blocks,
206
+ and structural dependencies keep the existing complete or React-owned paths. The compiler report
207
+ exposes this count as `keyedMapLookupTargets`.
208
+
209
+ When a targeted Set or Map is compiler-owned, Farm can also carry the exact mutated keys from a
210
+ proven immutable functional update:
211
+
212
+ ```tsx
213
+ setMarkedIds((current) => {
214
+ const next = new Set(current);
215
+ if (next.has(id)) next.delete(id);
216
+ else next.add(id);
217
+ return next;
218
+ });
219
+
220
+ setStatusById((current) => new Map(current).set(id, "ready"));
221
+ ```
222
+
223
+ The application still creates its normal immutable collection. The generated update records only
224
+ the native `add`, `delete`, or `set` calls that execute, and the runtime validates those keys
225
+ against the previous committed collection. It can then update the relevant keyed rows without
226
+ iterating every old and new Set member or Map entry first. Queued functional updates compose, and
227
+ the runtime periodically compacts its persistent snapshot so a long update chain stays bounded.
228
+
229
+ This proof is deliberately conservative. The state must start from a compiler-owned native
230
+ `Set`/`Map`; every setter use must be a fresh same-kind replacement or a recognized immutable
231
+ updater; and the collection, updater parameter, and cloned draft must not escape or be mutated
232
+ through unknown code. Shadowed constructors, custom collections, object keys, object Map values,
233
+ direct state mutation, aliased drafts, or a failed runtime check use the existing snapshot or
234
+ React-owned path before compiled bindings run. No option or syntax is added. The compiler report
235
+ counts emitted native mutation sites as `keyedCollectionUpdateHints`.
236
+
237
+ For a direct keyed `useState` collection, the compiler also recognizes conservative same-order
238
+ updates such as:
239
+
240
+ ```tsx
241
+ setItems((current) =>
242
+ current
243
+ .map((item) => (item.id === targetId ? { ...item, label: nextLabel } : item))
244
+ .map((item) => (item.id === targetId ? { ...item, selected: !item.selected } : item)),
245
+ );
246
+ ```
247
+
248
+ Farm executes every generated native `map()` and then compares the committed and final item
249
+ identities once. It validates final length, keys, and positions and patches each final changed row
250
+ once; intermediate arrays never receive DOM work. Every user `map()` remains O(n); this removes the
251
+ keyed runtime's second full key-and-binding scan. Queued hints compose. The source method lookup,
252
+ native result, callback order, and thrown errors are preserved.
253
+
254
+ The setter may be concise or use a block containing exactly one value-returning `return`. Extra
255
+ updater statements, conditional returns, and missing returns keep complete keyed reconciliation.
256
+ Each stage requires an inline synchronous conditional mapper that returns the original item on at
257
+ least one path and an object-spread replacement on another. The callback may be a concise expression
258
+ or a structured block containing fully returning `if` or `switch` branches and proven local `const`
259
+ aliases. Each alias needs a simple identifier and compiler-safe initializer. A `switch` needs one
260
+ `default`, a complete return from every case, safe discriminant and case expressions, and no trailing
261
+ statements. Consecutive empty labels may share the next fully returning body; partially executed
262
+ fallthrough and dangling labels are rejected. An unsupported mapper anywhere in the chain disables
263
+ the complete setter hint. Custom methods still execute but record no metadata. Key changes, structural
264
+ edits, sparse or subclassed arrays, relevant mixed dependencies, and failed runtime checks use the
265
+ existing complete reconciliation and LIS path. Non-functional setters, derived collections,
266
+ referenced callbacks, mutable or destructured declarations, effectful initializers, other
267
+ intermediate statements, partial or dangling fallthrough, mutating mappers, and other unproven forms
268
+ are simply not hinted. No new option is required. A compiler report counts prepared map calls as
269
+ `keyedMapUpdateHints`. The separate hint runtime capability is imported only when that count is
270
+ nonzero, so direct-only and ordinary keyed builds do not retain it.
271
+
272
+ The same optional runtime recognizes conservative immutable appends on a direct keyed array:
273
+
274
+ ```tsx
275
+ setItems((current) => [...current, nextItem]);
276
+ setItems((current) => [...current, ...nextItems]);
277
+ setItems((current) => {
278
+ return [...current, ...nextItems];
279
+ });
280
+ ```
281
+
282
+ Because every existing item keeps its key and index, Farm validates the committed source and the
283
+ queued append chain, reads keys and descriptors only for the appended suffix, and mounts that
284
+ suffix in one fragment. Existing row DOM is left untouched. The setter may be concise or use a
285
+ block containing exactly one direct value-returning `return`. Extra statements, conditional
286
+ returns, and missing returns keep complete keyed reconciliation. Native arrays are required;
287
+ middle insertion, removal, direct replacement, duplicate keys, rows that read the collection
288
+ itself, and failed runtime checks use complete keyed reconciliation. A key that reads the
289
+ collection prevents hint emission entirely. The compiler report exposes the emitted-site count as
290
+ `keyedArrayAppendHints`.
291
+
292
+ When all keyed-row plans in a component are plain, target-free rows and the only emitted update
293
+ hints are appends, the compiler selects a smaller append-only runtime. This omits unused map-update
294
+ and keyed-target fast paths, not support for other state changes: opaque updates and rejected hints
295
+ still use complete keyed reconciliation. Mixed hints, targeted bindings, conditional rows, and host
296
+ blocks keep their existing runtime. No additional option is required.
297
+
298
+ The same component-wide proof selects a smaller removal-only runtime when the only emitted
299
+ update hints are `filter()` and/or `slice()`. It omits unused append, map-update, and keyed-target
300
+ fast paths while retaining complete keyed reconciliation for opaque updates or rejected hints.
301
+ A sibling list requiring broader hints, targeted bindings, conditional rows, or host blocks keeps
302
+ the existing combined runtime. This changes bundle selection, not native array or React semantics.
303
+
304
+ Adjacent removal and append setters can share the same committed-row proof:
305
+
306
+ ```tsx
307
+ setItems((current) => current.filter((item) => item.id !== expiredId));
308
+ setItems((current) => [...current, incoming]);
309
+
310
+ setItems((current) => current.slice(start, end));
311
+ setItems((current) => [...current, ...incoming]);
312
+
313
+ setItems((current) => current.slice(start, end));
314
+ setItems((current) => [...current, incoming]);
315
+ setItems((current) =>
316
+ current.map((item) => (item.id === targetId ? { ...item, label: nextLabel } : item)),
317
+ );
318
+
319
+ setItems((current) => current.filter((item) => item.id !== expiredId));
320
+ setItems((current) =>
321
+ current.map((item) => (item.id === targetId ? { ...item, label: nextLabel } : item)),
322
+ );
323
+ setItems((current) => [...current, incoming]);
324
+ ```
325
+
326
+ The setters still execute in order and still create their normal native arrays. Before changing the
327
+ DOM, Farm validates the original committed token, every filter or slice survivor, the complete final
328
+ length, and every incoming key. It prepares all incoming keys, descriptors, bindings, and detached
329
+ host rows first; only then does it remove rejected rows, update survivor indexes, and append the new
330
+ suffix in one fragment. Existing survivors are neither rebound nor recreated, and additional
331
+ adjacent append setters are collapsed into the same final suffix. This keeps the unavoidable native
332
+ filter or slice work while removing the keyed runtime's second full scan.
333
+
334
+ One or more immediately adjacent safe same-key `map()` setters may run between the filter or slice
335
+ and the append, after the append, or in both positions. A safe map may also precede the structural
336
+ removal. Farm carries the original survivor indices or retained interval through those native maps
337
+ and records each replacement against its committed row. Before touching the DOM it validates the
338
+ complete dense result, every survivor identity, every changed key and binding, and every incoming
339
+ row. It then removes only rejected rows, patches only changed survivors, and creates the suffix from
340
+ its final values. The owner stays mounted, survivor DOM identity is preserved, and the suffix is
341
+ appended once.
342
+
343
+ Only concise updater results and blocks with one direct value-returning `return` that form one
344
+ direct chain for the same state array are linked. The row and key must be compiler-owned and
345
+ index-independent. A reorder in the structural-append chain, an
346
+ unsupported or non-adjacent map, an unhinted update to that state, another dirty row dependency,
347
+ collection-reading binding, custom, sparse, or subclassed array, nested or React-owned row,
348
+ duplicate final key, or reuse of any committed key in the appended suffix keeps complete React
349
+ reconciliation before a DOM write. A mapped survivor whose key changes also falls back before
350
+ mutation. No API or configuration is added. Compiler reports use the existing
351
+ `keyedArrayFilterHints`, `keyedArraySliceHints`, and `keyedArrayAppendHints` counts, and modules
352
+ without both accepted operations omit the composed runtime.
353
+
354
+ The mirror-image prepend form is supported when the keyed row and key do not read the row index:
355
+
356
+ ```tsx
357
+ setItems((current) => [nextItem, ...current]);
358
+ setItems((current) => [...nextItems, ...current]);
359
+ setItems((current) => {
360
+ return [...nextItems, ...current];
361
+ });
362
+
363
+ setItems((current) => current.filter((item) => item.id !== expiredId));
364
+ setItems((current) => [nextItem, ...current]);
365
+
366
+ setItems((current) => current.slice(start, end));
367
+ setItems((current) => [...nextItems, ...current]);
368
+
369
+ setItems((current) => current.filter((item) => item.id !== expiredId));
370
+ setItems((current) => [nextItem, ...current]);
371
+ setItems((current) =>
372
+ current.map((item) => (item.id === targetId ? { ...item, label: nextLabel } : item)),
373
+ );
374
+
375
+ setItems((current) => current.slice(start, end));
376
+ setItems((current) =>
377
+ current.map((item) => (item.id === targetId ? { ...item, label: nextLabel } : item)),
378
+ );
379
+ setItems((current) => [nextItem, ...current]);
380
+ ```
381
+
382
+ Farm validates the committed source and queued prepend chain, creates only the new prefix, inserts
383
+ it before the first existing row, and shifts the stored indexes used by delegated row events.
384
+ When an adjacent filter or bounded slice runs first, the compiler also carries the exact survivor
385
+ positions into the prepend. The runtime removes only rejected rows, preserves every surviving DOM
386
+ node, and creates only the final prefix instead of rescanning and rebinding the whole result.
387
+ Multiple adjacent prepends share the same proof.
388
+
389
+ When every keyed list in a component is plain and has no targeted bindings, and prepend is
390
+ the only emitted update hint, Farm selects a smaller prepend-only runtime. It omits unused
391
+ target and map/append fast paths, but keeps the same prepend validation and complete keyed
392
+ reconciliation for opaque or rejected updates. Mixed hints, conditional/host rows, and targeted
393
+ bindings on any sibling list keep their existing runtime. This changes bundle size, not the
394
+ supported update semantics or the prepend algorithm.
395
+
396
+ The setter may be concise or use a block containing exactly one direct value-returning `return`.
397
+ Extra statements, conditional returns, and missing returns keep complete keyed reconciliation.
398
+
399
+ One or more immediately adjacent safe same-key `map()` setters may run after the prepend or between
400
+ the removal and prepend. A safe map may also run immediately before the removal. Farm carries every
401
+ survivor back to its committed row, validates the complete dense result and every final key, then
402
+ patches only changed survivors and creates the prefix from its final mapped values. A surviving DOM
403
+ node keeps its identity even when its item object changes.
404
+
405
+ Index-aware rows, collection-reading bindings or keys, React-owned or nested row structures,
406
+ middle insertion, direct replacement, a reordered structural chain, an unsupported or non-adjacent
407
+ map, duplicate final keys, reuse of any committed key in the new prefix, custom or sparse arrays,
408
+ and failed validation use complete keyed reconciliation before any DOM mutation. A mapped survivor
409
+ whose key changes also falls back before mutation. The compiler report exposes the emitted-site
410
+ count as `keyedArrayPrependHints`; no option or component API is added, and modules without the
411
+ accepted removal, prepend, and map chain omit its mapped runtime.
412
+
413
+ Native slices with compiler-safe bounds can carry their exact retained interval into the same
414
+ removal runtime:
415
+
416
+ ```tsx
417
+ setItems((current) => current.slice(1_000));
418
+ setItems((current) => current.slice(0, -1_000));
419
+ setItems((current) => current.slice(2, 8));
420
+ setItems((current) => current.slice(trimCount));
421
+ setItems((current) => current.slice(visible.start, visible.end));
422
+ setItems((current) => {
423
+ return current.slice(visible.start, visible.end);
424
+ });
425
+ ```
426
+
427
+ For compiler-owned host rows whose render and key do not read the row index, Farm validates the
428
+ committed source and queued slice chain, preserves every surviving DOM row, and removes only rows
429
+ outside the retained interval. A slice-only chain does not reread surviving keys, descriptors, or
430
+ bindings. One or two safe-integer literals or compiler-safe runtime expressions are required.
431
+ Identifiers, property reads, side-effect-free arithmetic and conditionals, and safe `Math` calls
432
+ are supported. The setter may be concise or use a block containing exactly one direct
433
+ value-returning `return`. Farm preserves native method lookup, argument evaluation, coercion,
434
+ results, and errors, then records metadata only when the evaluated bounds are already safe integers.
435
+ Calls, assignments, updates, unsafe evaluated bounds, updater blocks with extra statements,
436
+ directives, conditional returns, or no value-returning `return`, chained updates, custom slice
437
+ methods, sparse or subclassed arrays, index-aware or collection-reading rows, React-owned structures,
438
+ and failed validation keep complete keyed reconciliation. No option or component is added. The
439
+ compiler report exposes the emitted-site count as `keyedArraySliceHints`.
440
+
441
+ A fixed-size feed can combine that retained tail with a new keyed suffix:
442
+
443
+ ```tsx
444
+ setItems((current) => [...current.slice(1), nextItem]);
445
+ setItems((current) => [...current.slice(1_000), ...nextItems]);
446
+
447
+ const trimCount = pageSize * pagesToExpire;
448
+ setItems((current) => [...current.slice(trimCount), ...nextItems]);
449
+ setItems((current) => {
450
+ return [...current.slice(trimCount), ...nextItems];
451
+ });
452
+ ```
453
+
454
+ Farm executes the ordinary native slice and array construction, then validates the complete hint
455
+ chain back to the committed source, retained item identities, and final incoming keys. Multiple
456
+ rolling setters queued before one compiler flush collapse into one cumulative prefix removal; rows
457
+ introduced by an earlier setter are created only if they remain in the final suffix. Farm removes
458
+ only the expired committed prefix, leaves the retained DOM rows in place, and creates only that
459
+ final incoming suffix. The setter may be concise or use a block containing exactly one direct
460
+ value-returning `return`. This form supports one safe-integer literal or compiler-safe runtime slice
461
+ bound and compiler-owned, index-independent host rows. Identifiers, property reads,
462
+ side-effect-free arithmetic and conditionals, and safe `Math` calls are supported while preserving
463
+ native lookup, evaluation, results, and errors.
464
+
465
+ Immediately adjacent safe same-key maps may run before, after, or between one or more rolling
466
+ setters in the same synchronous setter segment:
467
+
468
+ ```tsx
469
+ setItems((current) =>
470
+ current.map((item) => (item.id === editedId ? { ...item, label: nextLabel } : item)),
471
+ );
472
+ setItems((current) => [...current.slice(trimCount), ...nextItems]);
473
+ setItems((current) =>
474
+ current.map((item) => (item.id === selectedId ? { ...item, selected: true } : item)),
475
+ );
476
+ setItems((current) => [...current.slice(secondTrimCount), ...laterItems]);
477
+ setItems((current) =>
478
+ current.map((item) => (item.id === editedId ? { ...item, status: "ready" } : item)),
479
+ );
480
+ ```
481
+
482
+ Each map may use a compiler-safe nested conditional to update several retained rows.
483
+ The compiler carries mapped survivor identity through the retained tail, creates incoming rows
484
+ from their final mapped values, and patches only changed committed survivors. A single rolling
485
+ setter uses the optional structural append/map runtime. Multiple rolling setters keep their
486
+ cumulative retained-window metadata and mapped provenance through an optional runtime dedicated to
487
+ mapped rolling chains. No new public helper, option, or always-loaded browser code is added.
488
+
489
+ Effectful expressions, reused keys, updater blocks with extra statements, directives, conditional
490
+ returns, or no value-returning `return`, custom slice behavior, collection-reading or index-aware
491
+ rows, nested or React-owned rows, mixed or unhinted queued chains, a statement or unsupported setter
492
+ inside the segment, changed mapped keys, unsafe or no-op evaluated bounds, and failed checks use
493
+ complete keyed reconciliation. Unmapped rolling modules retain the smaller optional all-hint
494
+ runtime. Reports expose each emitted rolling site as `keyedArrayRollingWindowHints`, each rolling
495
+ step retained across a multi-window mapped chain as `keyedArrayMappedRollingWindowChainHints`, and
496
+ each safe map as `keyedMapUpdateHints`.
497
+
498
+ Native known-position updates can avoid a complete keyed scan too:
499
+
500
+ ```tsx
501
+ setItems((current) => current.toSpliced(selectedIndex, 0, nextItem));
502
+ setItems((current) => current.toSpliced(selectedIndex, 0, nextA, nextB));
503
+ setItems((current) => current.toSpliced(selectedIndex, 0, ...incomingItems));
504
+ setItems((current) => current.toSpliced(selectedIndex, 1));
505
+ setItems((current) => current.toSpliced(selectedIndex, 25));
506
+ setItems((current) => current.toSpliced(selectedIndex, 1, replacement));
507
+ setItems((current) => current.toSpliced(selectedIndex, 25, ...replacements));
508
+ setItems((current) => current.with(selectedIndex, replacement));
509
+ setItems((current) => {
510
+ return current.toSpliced(selectedIndex, 0, nextItem);
511
+ });
512
+ setItems((current) => {
513
+ return current.with(selectedIndex, replacement);
514
+ });
515
+
516
+ // Two same-key windows may be queued before one compiler flush.
517
+ setItems((current) => current.toSpliced(firstIndex, 25, ...firstRefresh));
518
+ setItems((current) => current.toSpliced(secondIndex, 25, ...secondRefresh));
519
+ ```
520
+
521
+ The compiler recognizes a concise functional setter or a setter block containing exactly one direct
522
+ `return`. Its position must be either a safe-integer literal or a compiler-safe runtime expression,
523
+ such as an identifier, property read, arithmetic, conditional, or safe `Math` call. The update must insert
524
+ one or more compiler-safe items with zero removals, remove one item or a fixed positive safe-integer
525
+ literal range, replace one item through either `toSpliced()` or `with()`, or replace a fixed positive
526
+ safe-integer literal window with compiler-safe explicit items or a safe spread. Farm preserves method lookup,
527
+ evaluates the position and remaining arguments once in their original order, executes the ordinary
528
+ native call, and records metadata only after validating the committed native source, result, and
529
+ actual safe-integer position and clamped removal count. A batch requires at least two evaluated
530
+ items at runtime. Exact-window replacement supports a safe spread that evaluates to zero, one, or
531
+ many items. A fresh-key window creates every incoming key, descriptor, binding snapshot, and
532
+ detached row before changing the live DOM, rejects key collisions, and mounts the complete batch
533
+ through one document fragment. It then removes only the replaced window. When the incoming window
534
+ has the same length and the same keys in the same order, Farm prepares every binding read and
535
+ changed DOM target across the complete window first, patches the existing rows in place, and
536
+ updates the stored row objects used by later events. That path creates no descriptors or DOM rows,
537
+ and preserves row identity, focus, and selection. Validated same-key row and window refreshes also
538
+ keep the existing row map and element lookup, and skip redundant cache cleanup instead of
539
+ rebuilding whole-list bookkeeping. Source and key validation still run, and each flush commits the
540
+ new collection token for subsequent updates. Structural changes retain index rebuilding and cache
541
+ cleanup. A window may instead grow or shrink while it
542
+ reorders keys from inside its own removed interval and mixes them with globally fresh keys. Farm
543
+ prepares all reused binding updates, new descriptors, binding snapshots, and detached rows before
544
+ the first DOM write. It removes only retired rows, preserves each reused row, batches adjacent new
545
+ rows in a fragment, updates shifted suffix indexes, and applies LIS only to the reused part of that
546
+ interval so it moves the fewest connected rows needed by the local permutation. Rows outside the
547
+ interval are not rerendered or rebound.
548
+ Multiple length-preserving same-key windows
549
+ queued before one compiler flush compose into one atomic refresh. Fixed-length queued windows may
550
+ mix same-key refreshes with globally new final keys, and both disjoint and overlapping windows are
551
+ supported. An overlapping position uses the last queued value; intermediate identities are never
552
+ mounted. Farm validates the complete chain and final key set, then prepares every touched key,
553
+ binding value, DOM target, new descriptor, binding snapshot, and disconnected DOM row before the
554
+ first write. It patches same-key positions and swaps only final fresh-key positions. Untouched rows
555
+ keep their identity and are not recreated. The runtime otherwise creates one inserted row,
556
+ removes only the known row or range, or patches/replaces one row at that position without rereading
557
+ every existing key, descriptor, and binding. Surviving rows keep their DOM identity. Index-aware or
558
+ collection-reading rows, custom methods, position expressions with user calls or mutations,
559
+ runtime positions that are not safe integers, dynamic, zero, negative, or fractional removal
560
+ counts, other `toSpliced()` forms, updater blocks with extra statements, directives, conditional
561
+ returns, or no value-returning `return`, unsafe incoming expressions, queued chains containing a
562
+ structural window or unhinted intermediate update, existing keys moved from outside the removed
563
+ interval, duplicate final keys, nested or React-owned rows, and failed checks use complete keyed
564
+ reconciliation before the fast path mutates the DOM.
565
+ Reports expose the site count as `keyedArrayPositionHints`. Batch insertion and exact-window
566
+ replacement use progressively separate optional runtime capabilities, so existing single-position
567
+ and batch-only bundles do not retain window validation or replacement code.
568
+
569
+ A direct native reverse can carry its complete permutation to a separate optional runtime:
570
+
571
+ ```tsx
572
+ setItems((current) => current.toReversed());
573
+ setItems((current) => {
574
+ return current.toReversed();
575
+ });
576
+ ```
577
+
578
+ Farm recognizes the concise form and a block containing exactly one direct `return`. It preserves
579
+ the method lookup, call result, and errors, then records metadata only for the native method on an
580
+ ordinary array whose chain starts at the committed collection. One direct reverse
581
+ verifies equal lengths and every reversed item identity before moving the existing keyed elements
582
+ with the minimum `n - 1` connected DOM moves. It does not reread row keys, descriptors, or bindings
583
+ and does not run the generic LIS calculation. Consecutive concise native `toReversed()` and
584
+ `toSorted()` setters queued before one flush compose into one final validated permutation. The
585
+ runtime skips intermediate DOM states. When the proven chain contains only reversals, Farm tracks
586
+ their parity relative to the committed rows: an even count validates exact identity and performs
587
+ no DOM moves, source-item map construction, or LIS; an odd count validates exact reverse and uses
588
+ the same minimum `n - 1` moves as one reverse. A chain containing a sort keeps the general final
589
+ permutation and uses LIS once. A concise updater or a block containing exactly one direct
590
+ value-returning `return` may also chain two or more native reorder operations:
591
+
592
+ ```tsx
593
+ setItems((current) => current.toSorted((left, right) => left.rank - right.rank).toReversed());
594
+ setItems((current) => {
595
+ return current.toSorted((left, right) => left.rank - right.rank).toReversed();
596
+ });
597
+ ```
598
+
599
+ Farm evaluates every lookup and call in JavaScript order, carries the same committed token through
600
+ the pipeline, and reconciles only its final result. Index-aware or collection-reading rows,
601
+ arguments to `toReversed()`, referenced comparators, computed methods, updater blocks with extra
602
+ statements, directives, conditional returns, or no returned value, custom methods, sparse or
603
+ subclassed behavior, structural calls after reordering, an unhinted intermediate update, nested or
604
+ React-owned rows, and failed checks keep complete keyed reconciliation.
605
+
606
+ A compiler-safe `filter()` or bounded `slice()` prefix may precede the native reorder suffix in a
607
+ concise updater or exact one-return block. A filter predicate may be concise or contain exactly one
608
+ direct value-returning `return`:
609
+
610
+ ```tsx
611
+ setItems((current) =>
612
+ current
613
+ .filter((item) => {
614
+ return item.visible;
615
+ })
616
+ .toSorted((left, right) => left.rank - right.rank)
617
+ .toReversed(),
618
+ );
619
+ ```
620
+
621
+ Farm validates the complete survivor set and final order before the first DOM write, removes only
622
+ rejected rows, and applies LIS once to the survivors. Concise or exact one-return filter/slice and
623
+ reorder setters also compose when queued in that order before one flush. Unsupported calls or a
624
+ structural call after a reorder fall back. Reports count each compiled step in the existing filter,
625
+ slice, sort, or reverse counter, and modules without those operations omit their optional runtimes.
626
+ Farm does not polyfill `Array.prototype.toReversed`.
627
+
628
+ A compiler-safe same-key map may also appear before or after native reorder steps:
629
+
630
+ ```tsx
631
+ setItems((current) =>
632
+ current
633
+ .map((item) => (item.id === editedId ? { ...item, label: nextLabel } : item))
634
+ .map((item) => (item.id === editedId ? { ...item, rank: nextRank } : item))
635
+ .toSorted((left, right) => left.rank - right.rank),
636
+ );
637
+ ```
638
+
639
+ One callback may select several rows through nested expressions, structured early returns, or a
640
+ fully returning `switch`:
641
+
642
+ ```tsx
643
+ setItems((current) =>
644
+ current.map((item) => {
645
+ const matchesReviewed = item.id === reviewedId;
646
+ if (matchesReviewed) return { ...item, status: "reviewed" };
647
+ const matchesEscalated = item.id === escalatedId;
648
+ if (matchesEscalated) {
649
+ return { ...item, status: "escalated", priority: 1 };
650
+ }
651
+ return item;
652
+ }),
653
+ );
654
+ ```
655
+
656
+ Every condition must be compiler-safe, and every leaf must return the original item or a safe
657
+ object spread of it, with at least one unchanged and one replacement path. Concise expressions and
658
+ blocks made from fully returning `if` or `switch` branches plus local `const` aliases are accepted.
659
+ Each alias must have a simple identifier and compiler-safe initializer. A switch requires one
660
+ `default` and complete returning cases. Consecutive empty labels may share the next body, while
661
+ partial or dangling fallthrough is rejected. Mutable or destructured declarations, effectful
662
+ initializers, other intermediate statements, and ambiguous leaves use complete keyed
663
+ reconciliation. A runtime key change also falls back before any DOM write.
664
+
665
+ The functional setter may be concise or a block containing exactly one direct value-returning
666
+ `return`. Farm executes every native map and reorder call normally. For consecutive accepted maps,
667
+ it checks each native call but compares only the input and final result of that map segment, avoiding
668
+ a full lineage scan for every intermediate array. It verifies the committed token, dense-array
669
+ shape, a one-to-one source-item match, and every final replacement key before touching the DOM, then runs one
670
+ LIS and patches each changed row once. Unchanged rows need no second key or binding read. Queued
671
+ supported map-and-reorder setters compose against the same committed rows. Every accepted map
672
+ requires an inline synchronous conditional mapper whose leaves return either the original item or
673
+ an object-spread replacement, plus index-independent compiler-owned host rows. Concise expressions
674
+ and structured blocks with proven local `const` aliases plus fully returning `if` or `switch`
675
+ branches are supported.
676
+ Changed keys, referenced callbacks, mutable, destructured, or effectful declarations, other
677
+ intermediate statements or partial/dangling fallthrough, unconditional replacements, `thisArg`,
678
+ structural calls in the same chain, computed or custom methods, sparse or subclassed arrays,
679
+ collection-reading bindings, nested or React-owned rows, and failed checks use complete keyed
680
+ reconciliation. Reports use the existing map, sort, and reorder hint counters, and unrelated modules
681
+ do not retain this optional runtime.
682
+
683
+ The maps may also finish the concise pipeline:
684
+
685
+ ```tsx
686
+ setItems((current) =>
687
+ current
688
+ .toReversed()
689
+ .map((item) => (item.id === editedId ? { ...item, label: nextLabel } : item))
690
+ .map((item) => (item.id === editedId ? { ...item, rank: nextRank } : item)),
691
+ );
692
+ ```
693
+
694
+ Farm retains the preceding reorder instead of treating the mapped result as an unhinted snapshot.
695
+ An exact reverse uses the minimum-move reverse path without a general source-item lookup or LIS. A
696
+ sort remains an ambiguous permutation, so Farm performs one validated source lookup and LIS pass.
697
+ Safe maps on both sides of a reorder flatten their replacements back to the same committed rows.
698
+
699
+ Safe maps may also run before, between, or after index-independent `filter` or `slice` steps in one
700
+ concise functional setter or one block with a single direct `return`. A final native reorder is optional:
701
+
702
+ ```tsx
703
+ setItems((current) =>
704
+ current
705
+ .filter((item) => item.visible)
706
+ .map((item) => (item.id === editedId ? { ...item, label: nextLabel } : item))
707
+ .slice(0, limit)
708
+ .toSorted((left, right) => left.rank - right.rank),
709
+ );
710
+
711
+ setItems((current) =>
712
+ current
713
+ .map((item) => (item.id === editedId ? { ...item, label: nextLabel } : item))
714
+ .filter((item) => item.visible)
715
+ .slice(0, limit),
716
+ );
717
+ ```
718
+
719
+ The structural helpers retain both the committed survivor indices and mapped-item sources across
720
+ each accepted step. The final commit removes rejected rows, performs LIS moves only when a reorder
721
+ needs them, and patches bindings only for changed survivors. Every native callback and method still
722
+ runs in JavaScript order.
723
+
724
+ The structural and map steps may also be split across immediately adjacent setter calls in either
725
+ order:
726
+
727
+ ```tsx
728
+ // Map, then structural work.
729
+ setItems((current) =>
730
+ current.map((item) => (item.id === editedId ? { ...item, label: nextLabel } : item)),
731
+ );
732
+ setItems((current) => current.filter((item) => item.visible));
733
+ setItems((current) => current.slice(0, limit));
734
+
735
+ // Structural work, then maps.
736
+ setItems((current) => current.filter((item) => item.visible));
737
+ setItems((current) => current.slice(0, limit));
738
+ setItems((current) =>
739
+ current.map((item) => (item.id === editedId ? { ...item, label: nextLabel } : item)),
740
+ );
741
+ setItems((current) =>
742
+ current.map((item) => (item.id === editedId ? { ...item, rank: nextRank } : item)),
743
+ );
744
+ ```
745
+
746
+ Farm links only consecutive calls to the same setter. A leading map retains its first committed
747
+ source through later structural work; a terminal map consumes the saved survivor lineage from the
748
+ preceding filter or slice. Multiple safe steps in either segment may share the proof, and mixed
749
+ map/structural/map sequences compose. Every result and key is validated before the queued commit
750
+ touches the DOM. An intervening statement, another setter, an unsafe callback, a changed key, or
751
+ failed runtime validation keeps complete keyed reconciliation.
752
+
753
+ The survivor proof may continue through adjacent native reorder setters:
754
+
755
+ ```tsx
756
+ setItems((current) => current.filter((item) => item.visible));
757
+ setItems((current) =>
758
+ current.map((item) => (item.id === editedId ? { ...item, rank: nextRank } : item)),
759
+ );
760
+ setItems((current) => current.toSorted((left, right) => left.rank - right.rank));
761
+ setItems((current) => current.toReversed());
762
+ ```
763
+
764
+ Farm retains the committed survivor positions and same-key replacements until the final queued
765
+ value. The commit removes rejected rows, patches changed survivors, and applies the final order in
766
+ one validated DOM transaction. Exact reverses use the minimum-move reverse path; an arbitrary sort
767
+ uses one source lookup and LIS. Non-adjacent calls, another setter, unsupported syntax, or a failed
768
+ shape/key check keep complete reconciliation.
769
+
770
+ The reorder and safe maps may also be adjacent setter calls in the same synchronous block:
771
+
772
+ ```tsx
773
+ setItems((current) => current.toReversed());
774
+ setItems((current) =>
775
+ current.map((item) => (item.id === editedId ? { ...item, label: nextLabel } : item)),
776
+ );
777
+ setItems((current) =>
778
+ current.map((item) => (item.id === editedId ? { ...item, rank: nextRank } : item)),
779
+ );
780
+ ```
781
+
782
+ The compiler links only consecutive calls to the same setter. It keeps the reorder token through
783
+ each accepted native map, then validates row keys before applying the same exact-reverse or
784
+ sort-permutation path at commit. Adjacent compiler-safe filter or slice work switches to the
785
+ structural proof above. An intervening statement, another setter, an unsupported map, or a changed
786
+ key keeps the ordinary complete fallback. Standalone map-only components do not retain the
787
+ map-and-reorder runtime.
788
+
789
+ The mirror order is supported as well: two or more adjacent concise same-key map setters may be
790
+ followed by a concise native reverse or sort setter. Farm records their replacement lineage from
791
+ the committed collection and carries it into the final reorder. Only adjacent calls to the same
792
+ setter are linked; intervening work and unsupported updates retain complete reconciliation.
793
+
794
+ Mapped lineage also continues through multiple adjacent native reorder setters. For example,
795
+ `map -> reverse -> sort -> reverse` keeps the same committed-row proof until the final value, then
796
+ performs one validated keyed reconciliation. A concise `map().toReversed()` pipeline may start the
797
+ same chain. Adjacent compiler-safe filter or slice work changes it into a structural chain while
798
+ retaining the committed source. Every updater and native method still executes in order; another
799
+ setter, intervening work, or an unsupported method ends the chain and preserves the complete
800
+ fallback.
801
+
802
+ A reverse before the safe map pipeline may be queued in a separate setter:
803
+
804
+ ```tsx
805
+ setItems((current) => current.toReversed());
806
+ setItems((current) =>
807
+ current.map((item) => (item.id === editedId ? { ...item, label: nextLabel } : item)).toReversed(),
808
+ );
809
+ ```
810
+
811
+ A direct `toReversed()` suffix is more specific than an arbitrary permutation. When all preceding
812
+ maps retain committed row order, Farm validates the mirrored source-to-result relation and every
813
+ changed binding before touching the DOM, then performs the minimum-move reverse without building a
814
+ second item lookup map or running LIS. Additional exact reversals toggle that proof between reverse
815
+ and identity. Therefore two reversals after safe maps patch changed rows in committed order without
816
+ moving DOM nodes or creating the generic source map; three use the exact reverse path. Exact reverse
817
+ metadata also composes across queued setters: a queued reverse followed by safe maps and another
818
+ reverse retains exact identity, so only changed row bindings are patched. A preceding sort or any
819
+ ambiguous order keeps the general permutation path.
820
+
821
+ A direct native immutable sort can use the same optional reorder runtime:
822
+
823
+ ```tsx
824
+ setItems((current) => current.toSorted((left, right) => left.rank - right.rank));
825
+ setLabels((current) => current.toSorted());
826
+ setItems((current) => {
827
+ return current.toSorted((left, right) => left.rank - right.rank);
828
+ });
829
+ ```
830
+
831
+ Farm recognizes a concise functional setter or a block containing exactly one direct `return`,
832
+ with no comparator or an inline synchronous comparator from the compiler-safe expression subset.
833
+ It preserves the original method lookup, comparator, stable native result, and errors. After the
834
+ native sort runs, the runtime validates an ordinary dense array whose reorder chain starts at the
835
+ committed collection, equal lengths, and a unique one-to-one item-identity permutation. It then
836
+ uses LIS to move only `n - LIS` keyed DOM nodes without rereading row keys, descriptors, or
837
+ bindings. Multiple concise native sorts and reverses queued in one flush, or chained in one concise
838
+ updater, share the original committed token and reconcile only their final permutation. The native
839
+ sorting work itself is unchanged.
840
+
841
+ Index-aware or collection-reading rows, referenced comparators, updater blocks with extra
842
+ statements, directives, conditional returns, or no returned value, computed or unsupported chained
843
+ calls, custom methods, sparse or subclassed arrays, duplicate item identities, unhinted intermediate
844
+ updates, structural calls after reordering, nested or React-owned rows, and failed checks keep
845
+ complete keyed reconciliation. A compiler-safe filter/slice prefix is supported. Reports count each
846
+ compiled sort step as a `keyedArraySortHints` entry; sort shares the optional reorder runtime, and
847
+ Farm does not polyfill `Array.prototype.toSorted`.
848
+
849
+ Concise or single-return block-bodied immutable filters on a direct keyed array can carry removal
850
+ positions into the same optional runtime:
851
+
852
+ ```tsx
853
+ setItems((current) => current.filter((item) => item.id !== removedId));
854
+ setItems((current) => {
855
+ return current.filter((item) => item.id !== removedId);
856
+ });
857
+ setItems((current) =>
858
+ current.filter((item) => {
859
+ return item.id !== removedId;
860
+ }),
861
+ );
862
+ ```
863
+
864
+ For compiler-owned host rows whose render and key do not observe the row index, Farm validates the
865
+ native filter chain, every surviving item identity, and every surviving key before removing only
866
+ the rejected DOM rows. It does not recreate descriptors or reread bindings for unchanged rows,
867
+ and queued filters compose before one compiler flush. Index-aware rows or predicates, updater blocks
868
+ with extra statements, directives, conditional returns, or no value-returning `return`, predicate
869
+ blocks with those unsupported shapes, custom filter methods, sparse or subclassed arrays,
870
+ collection-reading bindings or keys, React-owned row structures, mixed dirty dependencies, and
871
+ failed validation use complete keyed reconciliation. No option or new component is required. The
872
+ compiler report exposes the emitted-site count as `keyedArrayFilterHints`.
873
+
137
874
  An otherwise eligible host row may also contain an inline synchronous React event:
138
875
 
139
876
  ```tsx
@@ -155,7 +892,7 @@ insert, removal, or reorder asks React to reconcile the rows, adopts the committ
155
892
  reapplies current bindings, and then resumes direct same-key patches. This avoids creating eventful
156
893
  DOM outside React's Fiber tree.
157
894
 
158
- A keyed row may also contain dedicated conditional slots:
895
+ A non-interactive keyed row may also transfer its safe host conditions to the same keyed instance:
159
896
 
160
897
  ```tsx
161
898
  <ul>
@@ -163,7 +900,16 @@ A keyed row may also contain dedicated conditional slots:
163
900
  <li key={item.id}>
164
901
  <span>{item.label}</span>
165
902
  <div className="status-slot">
166
- {item.done ? <strong>{item.label} complete</strong> : <span>In progress</span>}
903
+ <i>State</i>
904
+ {item.done ? (
905
+ <article>
906
+ <strong>{item.label} complete</strong>
907
+ <div>{item.details && <small>{item.description}</small>}</div>
908
+ </article>
909
+ ) : (
910
+ <span>In progress</span>
911
+ )}
912
+ <b>Prepared</b>
167
913
  </div>
168
914
  <section className="details-slot">{item.expanded && <p>{item.description}</p>}</section>
169
915
  </li>
@@ -171,13 +917,59 @@ A keyed row may also contain dedicated conditional slots:
171
917
  </ul>
172
918
  ```
173
919
 
174
- Each conditional must be the only meaningful child of its persistent lowercase host container.
175
- The compiler records its test and branch bindings per row key. A same-key collection update compares
176
- those prepared snapshots and asks React to render only the conditional boundaries whose selected
177
- branch or branch values changed. Other conditional rows and the outer map stay untouched. Inserts,
178
- removals, and reorders remain React structural commits for these rows, after which Farm re-adopts
179
- the host skeleton and resumes row-local updates. This keeps empty branches, SSR, hydration,
180
- recoverable hydration errors, error boundaries, and Fast Refresh inside React's ownership.
920
+ The compiler prepares the row descriptor, static sibling positions, branch factories, and
921
+ text/attribute/style bindings at build time. React creates or hydrates the initial list. After
922
+ mount, a same-key update patches the active branch in place or mounts, replaces, or removes only the
923
+ changed branch. Multiple and deeper host-only conditions share that row scope. Insertions and
924
+ removals create or clean one row scope, while reorders use the normal LIS pass. The component body
925
+ and map callback do not rerun, and no wrapper or hydration marker is added.
926
+
927
+ This compiler-owned tier requires a lowercase non-interactive host row. Hooks, custom components,
928
+ branch events, refs, SVG, fragments, spreads, dangerous HTML, controlled inputs inside a condition,
929
+ and unproven expressions stay on React. An otherwise eligible row with inline events continues to
930
+ use the hybrid boundary: React owns its conditional Fibers and structural commits, while Farm
931
+ compares per-key snapshots and refreshes only changed slots. Duplicate runtime keys or invalid
932
+ adopted DOM switch the complete list to React.
933
+
934
+ An eligible outer keyed row may also own nested keyed ranges:
935
+
936
+ ```tsx
937
+ <div>
938
+ {projects.map((project) => (
939
+ <section key={project.id}>
940
+ <h2>{project.name}</h2>
941
+ <ul>
942
+ <li>Tasks</li>
943
+ {project.tasks.map((task) => (
944
+ <li key={task.id}>{task.title}</li>
945
+ ))}
946
+ <li>End</li>
947
+ </ul>
948
+ </section>
949
+ ))}
950
+ </div>
951
+ ```
952
+
953
+ Every outer key receives an isolated inner key table and LIS pass. Moving a project preserves its
954
+ task scope; reordering one task list touches only that project. Surviving project, task, and static
955
+ sibling elements keep their DOM identity, and removing an outer row cleans its inner scope. The
956
+ initial contract accepts non-interactive lowercase inner rows from `.map(...)` or inline `List`,
957
+ including multiple ranges separated by static host siblings. Inner events or forms, Hooks, custom
958
+ components, fragments, refs, SVG, spreads, dangerous HTML, and index keys keep the complete outer
959
+ row on React's fallback. Additional keyed levels that satisfy the same host-only contract are
960
+ analyzed recursively instead of using a fixed nesting limit.
961
+
962
+ When every inner key stays in the same order, the nested scope reuses its row table and skips
963
+ position-map construction and LIS planning. It still validates all keys and updates every child
964
+ scope and binding. Insertions, removals, and reorders keep the existing structural reconciliation;
965
+ duplicate keys or an invalid child scope keep the existing React fallback. This also applies to
966
+ keyed ranges next to host-only conditions inside a nested mixed range.
967
+
968
+ For example, `boards → columns → cards → tags` becomes a tree of keyed scopes. Each stable parent
969
+ key owns its child key table and LIS pass. Moving a board carries its column, card, and tag scopes;
970
+ reordering cards reconciles only the selected column. Block IDs stay globally unique while runtime
971
+ instances are isolated by their complete parent-key path. Removing any parent cleans every
972
+ descendant subscription before its DOM leaves the document.
181
973
 
182
974
  A keyed collection may use derived locals or an inline chain of `filter`, `slice`, `toSorted`, and
183
975
  `toReversed`:
@@ -211,10 +1003,9 @@ the TypeScript `lib` with ES2023 and target a runtime that supports them when us
211
1003
 
212
1004
  React remains the fallback and compatibility boundary. An interactive map beside static children,
213
1005
  a non-host sibling between ranges, a row with a non-inline or async handler, a file input or dynamic
214
- form control shape, a fragment, a ref, a custom component, or a conditional mixed directly beside
215
- other children in the same host slot uses the existing React-owned keyed boundary. The outer
216
- compiled component can still be skipped, but React reconciles that list's rows and owns their
217
- events, lifecycle, and state.
1006
+ form control shape, a fragment, a ref, a custom component, or any unsupported nested dynamic
1007
+ structure uses the existing React-owned keyed boundary. The outer compiled component can still be
1008
+ skipped, but React reconciles that list's rows and owns their events, lifecycle, and state.
218
1009
 
219
1010
  Non-interactive host maps can share a nested or component-root container with static host siblings:
220
1011
 
@@ -315,21 +1106,37 @@ Conditional blocks have three safe ownership levels. One or more proven host-onl
315
1106
  may become compiler-owned ranges among static host siblings, including at the exact component root.
316
1107
  A dedicated container with exactly one conditional child uses the smaller compiler-owned branch
317
1108
  boundary. The more general React-owned conditional path accepts supported events, nested host
318
- conditionals, keyed lists, and component islands. Keys, custom components, fragments, refs, SVG,
319
- attribute spreads, `dangerouslySetInnerHTML`, nested dynamic blocks, and branch events keep React
320
- ownership. An empty ternary branch may be `null` or `false`. The inactive branch is described at
321
- build time but is never pre-mounted or cached. If a logical `&&` evaluates to a number such as `0`,
1109
+ conditionals, keyed lists, and component islands. A compiler-owned host branch may now recursively
1110
+ contain eligible host-only conditional ranges and non-interactive keyed ranges in nested host
1111
+ containers. Each nested range receives its own dependency entry and updates without rerunning or
1112
+ replacing the outer branch. When conditionals and keyed maps/`List` ranges are direct siblings in
1113
+ one safe host container, the compiler emits one ordered mixed-range controller. It mounts or removes
1114
+ conditional branches, applies independent LIS reconciliation to each keyed range, and preserves
1115
+ static siblings in place. Stateful leaf text, attributes, `className`, and individual inline style
1116
+ properties on those siblings are compiled into stable segment/sibling/path bindings. Their address
1117
+ does not shift when a nearby condition mounts or a keyed range inserts, removes, or reorders rows,
1118
+ so the same controller patches them from the current state snapshot without replacing the sibling
1119
+ or rerunning the owner. The same mixed layout may recurse inside safe branches and keyed rows.
1120
+ Keys on branches, custom components, fragments, refs, SVG, attribute spreads,
1121
+ `dangerouslySetInnerHTML`, branch events, interactive rows, and unsupported mixed children keep
1122
+ React ownership. An empty ternary branch may be `null` or `false`. The
1123
+ inactive branch is described at build time but is never pre-mounted or cached. If a logical `&&`
1124
+ evaluates to a number such as `0`,
322
1125
  or adopted DOM no longer matches its descriptor, the affected container remounts through React so
323
1126
  JavaScript, hydration, and React rendering semantics remain exact.
324
1127
 
325
1128
  All component-level boundary types share one block graph and one ID sequence. A nested
326
1129
  binding records its nearest conditional parent. If one state flush affects both an outer
327
1130
  conditional and its descendants, the runtime refreshes the mounted outer boundary once and skips
328
- the redundant descendant refreshes. React unmounts inner boundaries normally, their subscriptions
329
- are removed, and a later remount reads the latest compiler-cell values. Host-only keyed rows have
330
- separate runtime instances per key. Row-local conditional IDs are scoped to that instance and
331
- paired with its stable key, so two rows can use the same build-time slot ID without sharing data or
332
- subscriptions. Unsupported row subtrees stay complete React-owned keyed boundaries.
1131
+ the redundant descendant refreshes. React-owned inner boundaries unmount normally. Compiler-owned
1132
+ host scopes explicitly remove every nested subscription before their outer DOM is removed, and a
1133
+ later mount reads the latest compiler-cell values. Surviving keyed rows move with the existing LIS
1134
+ algorithm. Duplicate runtime keys, invalid adoption, or an unsafe logical value transfer the outer
1135
+ container back to React; descendant dependencies remain subscribed so that fallback stays live.
1136
+ Host-only keyed rows have separate runtime instances per key. Row-local conditional and keyed-range
1137
+ IDs are scoped to that instance and paired with its stable key, so two rows can use the same
1138
+ build-time slot ID without sharing data or subscriptions. Unsupported row subtrees stay complete
1139
+ React-owned keyed boundaries.
333
1140
 
334
1141
  Unsupported components fall back to React by default. Use `onUnsupported: "warn"` for diagnostics
335
1142
  or `onUnsupported: "error"` while tightening an annotated migration.
@@ -346,7 +1153,29 @@ compiler: {
346
1153
 
347
1154
  The default path is `.farm/react-compiler.json`. The report covers the production browser graph and
348
1155
  contains project-relative module paths, compiled component names, fallback details, and fallback
349
- reasons aggregated by count. A custom project-relative `reportFile` also enables reporting.
1156
+ reasons aggregated by count. Its summary and per-module `optimizations` also report
1157
+ `keyedIdentityTargets`, the number of scalar key-directed row bindings;
1158
+ `keyedMapLookupTargets`, the number of native-Map keyed lookup bindings;
1159
+ `keyedMembershipTargets`, the number of native-Set membership bindings;
1160
+ `keyedCollectionUpdateHints`, the number of compiler-proven native Set/Map mutation sites; and
1161
+ `keyedMapUpdateHints`, the number of compiler-proven keyed `map()` update calls; and
1162
+ `keyedArrayAppendHints`, the number of compiler-proven direct keyed-array append sites; and
1163
+ `keyedArrayFilterHints`, the number of compiler-proven keyed-array filter sites, including supported
1164
+ structural reorder pipelines; and
1165
+ `keyedArrayPrependHints`, the number of compiler-proven direct keyed-array prepend sites; and
1166
+ `keyedArrayPositionHints`, the number of compiler-proven native exact-position insertion, single or
1167
+ contiguous-range removal, single-row replacement, or exact-window replacement sites, including
1168
+ guarded compiler-safe runtime positions;
1169
+ and
1170
+ `keyedArrayReorderHints`, the number of compiler-proven native keyed-array reverse steps; and
1171
+ `keyedArraySortHints`, the number of compiler-proven native keyed-array sort steps; and
1172
+ `keyedArrayMappedRollingWindowChainHints`, the number of compiler-proven rolling steps retained
1173
+ across multi-window same-key map chains; and
1174
+ `keyedArrayRollingWindowHints`, the number of compiler-proven retained-tail plus incoming-suffix
1175
+ sites; and
1176
+ `keyedArraySliceHints`, the number of compiler-proven keyed-array slice sites with literal or guarded
1177
+ compiler-safe runtime bounds, including supported structural reorder pipelines. A custom
1178
+ project-relative `reportFile` also enables reporting.
350
1179
 
351
1180
  The runtime test compares the same counter interaction on both paths: ordinary React performs a
352
1181
  second component render and commit, while the compiled component remains at one render and one
@@ -354,11 +1183,15 @@ commit and updates its two bindings directly. This is a deterministic structural
354
1183
  assertion; it is not presented as a cross-machine timing benchmark.
355
1184
 
356
1185
  Application and prototype calls, dynamic style objects, handlers outside JSX events, nested,
357
- computed, and rest props patterns, async handlers, unkeyed or index-keyed lists, chained maps,
358
- unsupported conditional roots, effects, and more advanced hook support intentionally stay on React
359
- in this release. Compiler-owned keyed rows support either one dedicated host-only map/`List` or
360
- one or more non-interactive ranges in a nested or component-root host container. Inline synchronous
361
- events and dedicated row-local host conditional slots can use the single-list hybrid path, but
362
- branch events, interactive ranges beside siblings, nested dynamic blocks, conditionals mixed with
363
- siblings in one slot, non-inline or async row handlers, unsupported form shapes, custom components,
364
- fragments, refs, SVG, and duplicate runtime keys keep or switch to React ownership.
1186
+ computed, and rest props patterns, async handlers, unkeyed or index-keyed lists, unsupported map
1187
+ chains, unsupported conditional roots, effects, and more advanced hook support intentionally stay
1188
+ on React in this release. Compiler-owned keyed rows support either one dedicated host-only map/`List` or
1189
+ one or more non-interactive ranges in a nested or component-root host container. A dedicated
1190
+ non-interactive row may also contain multiple recursive logical or ternary host branches beside
1191
+ stateful static host siblings, plus recursively nested non-interactive keyed ranges scoped by every
1192
+ stable parent key. Static sibling bindings support safe leaf text, attributes, `className`, and
1193
+ individual style properties; lifecycle-sensitive shapes continue to fall back. Inline synchronous
1194
+ row events continue to use the hybrid React-owned row path. Branch
1195
+ or nested-row events, interactive ranges beside siblings, non-inline or async row handlers,
1196
+ unsupported form shapes, custom components, fragments, refs, SVG, and duplicate runtime keys keep
1197
+ or switch to React ownership.