@farm.js/react 0.1.0-beta.4 → 0.1.0-beta.41

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,9 +15,7 @@ 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
  ```
@@ -25,6 +23,25 @@ export default defineConfig({
25
23
  `compiler: true` uses inference: every application TSX/JSX component is considered, eligible
26
24
  components are compiled with hybrid reactivity, and everything else keeps the normal React path.
27
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
+
28
45
  Hybrid reactivity starts from the compiler's proven state-to-binding dependency lists, then marks
29
46
  only multi-state short-circuit bindings for runtime read tracking. For
30
47
  `enabled ? activeValue : inactiveValue`, an update to the inactive value does not schedule the
@@ -32,17 +49,37 @@ binding. The runtime uses direct subscription indexes rather than proxies or a c
32
49
  scan. Use `compiler: { reactivity: "static" }` to retain only the complete build-time dependency
33
50
  lists for comparison or diagnosis.
34
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
+ Generated code also selects refresh support through `import.meta.hot`. Production bundles can
61
+ remove the development refresh registry and compatibility checks; development retains
62
+ state-preserving refresh. Both entries share the same component runtime, including SSR, hydration,
63
+ DOM ownership, and fallback behavior. Existing hand-authored runtime entries retain refresh support.
64
+
65
+ Plain keyed lists with filter hints and only identity-based selection also use the single-kind
66
+ target runtime. Filtering keeps its existing native-method checks and fallback; mixed Set/Map
67
+ targets, conditional rows, and nested host blocks keep their existing runtime capabilities.
68
+
69
+ The persisted production-size fixtures and regression gate live in
70
+ [`RUNTIME_SIZE_RESULTS.md`](./RUNTIME_SIZE_RESULTS.md). The recorded compiler-selected core runtime
71
+ premium is 85.4% smaller than the complete compatibility runtime premium; the feature-heavy keyed
72
+ benchmark application removes 6,185 gzip bytes from its previous compiler-on build.
73
+
35
74
  For selective adoption, use annotation mode:
36
75
 
37
76
  ```ts
38
77
  renderer: react({
39
- experimental: {
40
- compiler: {
41
- mode: "annotation",
42
- directive: "use compiler",
43
- onUnsupported: "warn",
44
- reactivity: "hybrid",
45
- },
78
+ compiler: {
79
+ mode: "annotation",
80
+ directive: "use compiler",
81
+ onUnsupported: "warn",
82
+ reactivity: "hybrid",
46
83
  },
47
84
  }),
48
85
  ```
@@ -82,6 +119,11 @@ The current compiler handles components that it can prove have:
82
119
  - React-managed event handlers; and
83
120
  - no refs, effects, or unsupported dynamic child structures.
84
121
 
122
+ State-dependent event handler selection, such as `onClick={active ? save : cancel}`, keeps the
123
+ component on React's normal rendering path so replacing, adding, or removing a callback updates
124
+ React's event props. Direct inline handlers that read state when invoked, such as
125
+ `onClick={() => save(active)}`, retain the existing compiled path when otherwise eligible.
126
+
85
127
  The generated component preserves React ownership of initial placement, parent update commits,
86
128
  identity-bearing props, events, SSR, and hydration. Local state cells batch updates into a
87
129
  microtask; eligible flat destructured primitive props join the same dependency index after React
@@ -96,6 +138,10 @@ refreshes only changed React-owned row-local branches. React still creates or hy
96
138
  DOM. Anything outside those narrow contracts uses a small React-owned boundary or the complete
97
139
  original component.
98
140
 
141
+ Compiler-owned structural updates stay disabled inside SVG and MathML, including shared
142
+ HTML/SVG tag names such as `a` and `title`. React retains namespace-sensitive element creation
143
+ when rows are appended or conditional branches change; ordinary HTML rows remain eligible.
144
+
99
145
  For a common dedicated conditional, no new component or annotation is required:
100
146
 
101
147
  ```tsx
@@ -149,6 +195,703 @@ Later list updates patch surviving rows by key, create or remove only the change
149
195
  longest increasing subsequence (LIS) to minimize DOM moves during a reorder. The outer user
150
196
  component and the list callback do not rerun for those compiler-cell updates.
151
197
 
198
+ When a separate state cell or primitive prop is compared with the exact row-key expression using
199
+ `===` or `!==`, the compiler emits a key-directed binding proof. A selection change such as
200
+ `item.id === selectedId` then looks up only the previously selected and newly selected row
201
+ instances. Class, attribute, style, and leaf-text bindings on those rows update without evaluating
202
+ the other keyed instances. The proof requires one reactive target used only in strict comparisons;
203
+ mixed structural dependencies, ambiguous expressions, non-primitive runtime targets, React-owned
204
+ rows, and unsupported shapes keep the complete scan or React fallback. No option is required, and
205
+ the compiler report exposes the emitted binding count as `keyedIdentityTargets`.
206
+
207
+ For multi-selection, an exact local-state expression such as `markedIds.has(item.id)` receives a
208
+ separate Set-membership proof. The runtime compares the previous and next native `Set` snapshots and
209
+ patches only row keys in their symmetric difference. It accepts ordinary native sets containing
210
+ primitive keys. Different fields, extra reactive dependencies, Set subclasses or proxies, object
211
+ members, customized `has` behavior, React-owned rows, nested blocks, and structural dependencies
212
+ stay on the existing complete or React-owned paths. The compiler report exposes this count as
213
+ `keyedMembershipTargets`.
214
+
215
+ For per-row data, an exact local-state expression such as `statusById.get(item.id)` receives a
216
+ separate Map-lookup proof. The runtime compares the previous and next native `Map` snapshots and
217
+ patches only row keys whose mapped primitive value changed. It accepts ordinary native maps with
218
+ primitive keys and primitive or nullish values. Different fields, extra dependencies, Map
219
+ subclasses or proxies, object values, customized `get` behavior, React-owned rows, nested blocks,
220
+ and structural dependencies keep the existing complete or React-owned paths. The compiler report
221
+ exposes this count as `keyedMapLookupTargets`.
222
+
223
+ When a targeted Set or Map is compiler-owned, Farm can also carry the exact mutated keys from a
224
+ proven immutable functional update:
225
+
226
+ ```tsx
227
+ setMarkedIds((current) => {
228
+ const next = new Set(current);
229
+ if (next.has(id)) next.delete(id);
230
+ else next.add(id);
231
+ return next;
232
+ });
233
+
234
+ setStatusById((current) => new Map(current).set(id, "ready"));
235
+ ```
236
+
237
+ The application still creates its normal immutable collection. The generated update records only
238
+ the native `add`, `delete`, or `set` calls that execute, and the runtime validates those keys
239
+ against the previous committed collection. It can then update the relevant keyed rows without
240
+ iterating every old and new Set member or Map entry first. Queued functional updates compose, and
241
+ the runtime periodically compacts its persistent snapshot so a long update chain stays bounded.
242
+
243
+ This proof is deliberately conservative. The state must start from a compiler-owned native
244
+ `Set`/`Map`; every setter use must be a fresh same-kind replacement or a recognized immutable
245
+ updater; and the collection, updater parameter, and cloned draft must not escape or be mutated
246
+ through unknown code. Shadowed constructors, custom collections, object keys, object Map values,
247
+ direct state mutation, aliased drafts, or a failed runtime check use the existing snapshot or
248
+ React-owned path before compiled bindings run. No option or syntax is added. The compiler report
249
+ counts emitted native mutation sites as `keyedCollectionUpdateHints`.
250
+
251
+ For a direct keyed `useState` collection, the compiler also recognizes conservative same-order
252
+ updates such as:
253
+
254
+ ```tsx
255
+ setItems((current) =>
256
+ current
257
+ .map((item) => (item.id === targetId ? { ...item, label: nextLabel } : item))
258
+ .map((item) => (item.id === targetId ? { ...item, selected: !item.selected } : item)),
259
+ );
260
+ ```
261
+
262
+ Farm executes every generated native `map()` and then compares the committed and final item
263
+ identities once. It validates final length, keys, and positions and patches each final changed row
264
+ once; intermediate arrays never receive DOM work. Every user `map()` remains O(n); this removes the
265
+ keyed runtime's second full key-and-binding scan. Queued hints compose. The source method lookup,
266
+ native result, callback order, and thrown errors are preserved.
267
+
268
+ The setter may be concise or use a block containing exactly one value-returning `return`. Extra
269
+ updater statements, conditional returns, and missing returns keep complete keyed reconciliation.
270
+ Each stage requires an inline synchronous conditional mapper that returns the original item on at
271
+ least one path and an object-spread replacement on another. The callback may be a concise expression
272
+ or a structured block containing fully returning `if` or `switch` branches and proven local `const`
273
+ aliases. Each alias needs a simple identifier and compiler-safe initializer. A `switch` needs one
274
+ `default`, a complete return from every case, safe discriminant and case expressions, and no trailing
275
+ statements. Consecutive empty labels may share the next fully returning body; partially executed
276
+ fallthrough and dangling labels are rejected. An unsupported mapper anywhere in the chain disables
277
+ the complete setter hint. Custom methods still execute but record no metadata. Key changes, structural
278
+ edits, sparse or subclassed arrays, relevant mixed dependencies, and failed runtime checks use the
279
+ existing complete reconciliation and LIS path. Non-functional setters, derived collections,
280
+ referenced callbacks, mutable or destructured declarations, effectful initializers, other
281
+ intermediate statements, partial or dangling fallthrough, mutating mappers, and other unproven forms
282
+ are simply not hinted. No new option is required. A compiler report counts prepared map calls as
283
+ `keyedMapUpdateHints`. The separate hint runtime capability is imported only when that count is
284
+ nonzero, so direct-only and ordinary keyed builds do not retain it.
285
+
286
+ The same optional runtime recognizes conservative immutable appends on a direct keyed array:
287
+
288
+ ```tsx
289
+ setItems((current) => [...current, nextItem]);
290
+ setItems((current) => [...current, ...nextItems]);
291
+ setItems((current) => {
292
+ return [...current, ...nextItems];
293
+ });
294
+ ```
295
+
296
+ Because every existing item keeps its key and index, Farm validates the committed source and the
297
+ queued append chain, reads keys and descriptors only for the appended suffix, and mounts that
298
+ suffix in one fragment. Existing row DOM is left untouched. The setter may be concise or use a
299
+ block containing exactly one direct value-returning `return`. Extra statements, conditional
300
+ returns, and missing returns keep complete keyed reconciliation. Native arrays are required;
301
+ middle insertion, removal, direct replacement, duplicate keys, rows that read the collection
302
+ itself, and failed runtime checks use complete keyed reconciliation. A key that reads the
303
+ collection prevents hint emission entirely. The compiler report exposes the emitted-site count as
304
+ `keyedArrayAppendHints`.
305
+
306
+ When all keyed-row plans in a component are plain, target-free rows and the only emitted update
307
+ hints are appends, the compiler selects a smaller append-only runtime. This omits unused map-update
308
+ and keyed-target fast paths, not support for other state changes: opaque updates and rejected hints
309
+ still use complete keyed reconciliation. Mixed hints, targeted bindings, conditional rows, and host
310
+ blocks keep their existing runtime. No additional option is required.
311
+
312
+ The same component-wide proof selects a smaller removal-only runtime when the only emitted
313
+ update hints are `filter()` and/or `slice()`. It omits unused append, map-update, and keyed-target
314
+ fast paths while retaining complete keyed reconciliation for opaque updates or rejected hints.
315
+ A sibling list requiring broader hints, targeted bindings, conditional rows, or host blocks keeps
316
+ the existing combined runtime. This changes bundle selection, not native array or React semantics.
317
+
318
+ Adjacent removal and append setters can share the same committed-row proof:
319
+
320
+ ```tsx
321
+ setItems((current) => current.filter((item) => item.id !== expiredId));
322
+ setItems((current) => [...current, incoming]);
323
+
324
+ setItems((current) => current.slice(start, end));
325
+ setItems((current) => [...current, ...incoming]);
326
+
327
+ setItems((current) => current.slice(start, end));
328
+ setItems((current) => [...current, incoming]);
329
+ setItems((current) =>
330
+ current.map((item) => (item.id === targetId ? { ...item, label: nextLabel } : item)),
331
+ );
332
+
333
+ setItems((current) => current.filter((item) => item.id !== expiredId));
334
+ setItems((current) =>
335
+ current.map((item) => (item.id === targetId ? { ...item, label: nextLabel } : item)),
336
+ );
337
+ setItems((current) => [...current, incoming]);
338
+ ```
339
+
340
+ The setters still execute in order and still create their normal native arrays. Before changing the
341
+ DOM, Farm validates the original committed token, every filter or slice survivor, the complete final
342
+ length, and every incoming key. It prepares all incoming keys, descriptors, bindings, and detached
343
+ host rows first; only then does it remove rejected rows, update survivor indexes, and append the new
344
+ suffix in one fragment. Existing survivors are neither rebound nor recreated, and additional
345
+ adjacent append setters are collapsed into the same final suffix. This keeps the unavoidable native
346
+ filter or slice work while removing the keyed runtime's second full scan.
347
+
348
+ One or more immediately adjacent safe same-key `map()` setters may run between the filter or slice
349
+ and the append, after the append, or in both positions. A safe map may also precede the structural
350
+ removal. Farm carries the original survivor indices or retained interval through those native maps
351
+ and records each replacement against its committed row. Before touching the DOM it validates the
352
+ complete dense result, every survivor identity, every changed key and binding, and every incoming
353
+ row. It then removes only rejected rows, patches only changed survivors, and creates the suffix from
354
+ its final values. The owner stays mounted, survivor DOM identity is preserved, and the suffix is
355
+ appended once.
356
+
357
+ Only concise updater results and blocks with one direct value-returning `return` that form one
358
+ direct chain for the same state array are linked. The row and key must be compiler-owned and
359
+ index-independent. A reorder in the structural-append chain, an
360
+ unsupported or non-adjacent map, an unhinted update to that state, another dirty row dependency,
361
+ collection-reading binding, custom, sparse, or subclassed array, nested or React-owned row,
362
+ duplicate final key, or reuse of any committed key in the appended suffix keeps complete React
363
+ reconciliation before a DOM write. A mapped survivor whose key changes also falls back before
364
+ mutation. No API or configuration is added. Compiler reports use the existing
365
+ `keyedArrayFilterHints`, `keyedArraySliceHints`, and `keyedArrayAppendHints` counts, and modules
366
+ without both accepted operations omit the composed runtime.
367
+
368
+ The mirror-image prepend form is supported when the keyed row and key do not read the row index:
369
+
370
+ ```tsx
371
+ setItems((current) => [nextItem, ...current]);
372
+ setItems((current) => [...nextItems, ...current]);
373
+ setItems((current) => {
374
+ return [...nextItems, ...current];
375
+ });
376
+
377
+ setItems((current) => current.filter((item) => item.id !== expiredId));
378
+ setItems((current) => [nextItem, ...current]);
379
+
380
+ setItems((current) => current.slice(start, end));
381
+ setItems((current) => [...nextItems, ...current]);
382
+
383
+ setItems((current) => current.filter((item) => item.id !== expiredId));
384
+ setItems((current) => [nextItem, ...current]);
385
+ setItems((current) =>
386
+ current.map((item) => (item.id === targetId ? { ...item, label: nextLabel } : item)),
387
+ );
388
+
389
+ setItems((current) => current.slice(start, end));
390
+ setItems((current) =>
391
+ current.map((item) => (item.id === targetId ? { ...item, label: nextLabel } : item)),
392
+ );
393
+ setItems((current) => [nextItem, ...current]);
394
+ ```
395
+
396
+ Farm validates the committed source and queued prepend chain, creates only the new prefix, inserts
397
+ it before the first existing row, and shifts the stored indexes used by delegated row events.
398
+ When an adjacent filter or bounded slice runs first, the compiler also carries the exact survivor
399
+ positions into the prepend. The runtime removes only rejected rows, preserves every surviving DOM
400
+ node, and creates only the final prefix instead of rescanning and rebinding the whole result.
401
+ Multiple adjacent prepends share the same proof.
402
+
403
+ When every keyed list in a component is plain and has no targeted bindings, and prepend is
404
+ the only emitted update hint, Farm selects a smaller prepend-only runtime. It omits unused
405
+ target and map/append fast paths, but keeps the same prepend validation and complete keyed
406
+ reconciliation for opaque or rejected updates. Mixed hints, conditional/host rows, and targeted
407
+ bindings on any sibling list keep their existing runtime. This changes bundle size, not the
408
+ supported update semantics or the prepend algorithm.
409
+
410
+ The setter may be concise or use a block containing exactly one direct value-returning `return`.
411
+ Extra statements, conditional returns, and missing returns keep complete keyed reconciliation.
412
+
413
+ One or more immediately adjacent safe same-key `map()` setters may run after the prepend or between
414
+ the removal and prepend. A safe map may also run immediately before the removal. Farm carries every
415
+ survivor back to its committed row, validates the complete dense result and every final key, then
416
+ patches only changed survivors and creates the prefix from its final mapped values. A surviving DOM
417
+ node keeps its identity even when its item object changes.
418
+
419
+ Index-aware rows, collection-reading bindings or keys, React-owned or nested row structures,
420
+ middle insertion, direct replacement, a reordered structural chain, an unsupported or non-adjacent
421
+ map, duplicate final keys, reuse of any committed key in the new prefix, custom or sparse arrays,
422
+ and failed validation use complete keyed reconciliation before any DOM mutation. A mapped survivor
423
+ whose key changes also falls back before mutation. The compiler report exposes the emitted-site
424
+ count as `keyedArrayPrependHints`; no option or component API is added, and modules without the
425
+ accepted removal, prepend, and map chain omit its mapped runtime.
426
+
427
+ Native slices with compiler-safe bounds can carry their exact retained interval into the same
428
+ removal runtime:
429
+
430
+ ```tsx
431
+ setItems((current) => current.slice(1_000));
432
+ setItems((current) => current.slice(0, -1_000));
433
+ setItems((current) => current.slice(2, 8));
434
+ setItems((current) => current.slice(trimCount));
435
+ setItems((current) => current.slice(visible.start, visible.end));
436
+ setItems((current) => {
437
+ return current.slice(visible.start, visible.end);
438
+ });
439
+ ```
440
+
441
+ For compiler-owned host rows whose render and key do not read the row index, Farm validates the
442
+ committed source and queued slice chain, preserves every surviving DOM row, and removes only rows
443
+ outside the retained interval. A slice-only chain does not reread surviving keys, descriptors, or
444
+ bindings. One or two safe-integer literals or compiler-safe runtime expressions are required.
445
+ Identifiers, property reads, side-effect-free arithmetic and conditionals, and safe `Math` calls
446
+ are supported. The setter may be concise or use a block containing exactly one direct
447
+ value-returning `return`. Farm preserves native method lookup, argument evaluation, coercion,
448
+ results, and errors, then records metadata only when the evaluated bounds are already safe integers.
449
+ Calls, assignments, updates, unsafe evaluated bounds, updater blocks with extra statements,
450
+ directives, conditional returns, or no value-returning `return`, chained updates, custom slice
451
+ methods, sparse or subclassed arrays, index-aware or collection-reading rows, React-owned structures,
452
+ and failed validation keep complete keyed reconciliation. No option or component is added. The
453
+ compiler report exposes the emitted-site count as `keyedArraySliceHints`.
454
+
455
+ A fixed-size feed can combine that retained tail with a new keyed suffix:
456
+
457
+ ```tsx
458
+ setItems((current) => [...current.slice(1), nextItem]);
459
+ setItems((current) => [...current.slice(1_000), ...nextItems]);
460
+
461
+ const trimCount = pageSize * pagesToExpire;
462
+ setItems((current) => [...current.slice(trimCount), ...nextItems]);
463
+ setItems((current) => {
464
+ return [...current.slice(trimCount), ...nextItems];
465
+ });
466
+ ```
467
+
468
+ Farm executes the ordinary native slice and array construction, then validates the complete hint
469
+ chain back to the committed source, retained item identities, and final incoming keys. Multiple
470
+ rolling setters queued before one compiler flush collapse into one cumulative prefix removal; rows
471
+ introduced by an earlier setter are created only if they remain in the final suffix. Farm removes
472
+ only the expired committed prefix, leaves the retained DOM rows in place, and creates only that
473
+ final incoming suffix. The setter may be concise or use a block containing exactly one direct
474
+ value-returning `return`. This form supports one safe-integer literal or compiler-safe runtime slice
475
+ bound and compiler-owned, index-independent host rows. Identifiers, property reads,
476
+ side-effect-free arithmetic and conditionals, and safe `Math` calls are supported while preserving
477
+ native lookup, evaluation, results, and errors.
478
+
479
+ Immediately adjacent safe same-key maps may run before, after, or between one or more rolling
480
+ setters in the same synchronous setter segment:
481
+
482
+ ```tsx
483
+ setItems((current) =>
484
+ current.map((item) => (item.id === editedId ? { ...item, label: nextLabel } : item)),
485
+ );
486
+ setItems((current) => [...current.slice(trimCount), ...nextItems]);
487
+ setItems((current) =>
488
+ current.map((item) => (item.id === selectedId ? { ...item, selected: true } : item)),
489
+ );
490
+ setItems((current) => [...current.slice(secondTrimCount), ...laterItems]);
491
+ setItems((current) =>
492
+ current.map((item) => (item.id === editedId ? { ...item, status: "ready" } : item)),
493
+ );
494
+ ```
495
+
496
+ Each map may use a compiler-safe nested conditional to update several retained rows.
497
+ The compiler carries mapped survivor identity through the retained tail, creates incoming rows
498
+ from their final mapped values, and patches only changed committed survivors. A single rolling
499
+ setter uses the optional structural append/map runtime. Multiple rolling setters keep their
500
+ cumulative retained-window metadata and mapped provenance through an optional runtime dedicated to
501
+ mapped rolling chains. No new public helper, option, or always-loaded browser code is added.
502
+
503
+ Effectful expressions, reused keys, updater blocks with extra statements, directives, conditional
504
+ returns, or no value-returning `return`, custom slice behavior, collection-reading or index-aware
505
+ rows, nested or React-owned rows, mixed or unhinted queued chains, a statement or unsupported setter
506
+ inside the segment, changed mapped keys, unsafe or no-op evaluated bounds, and failed checks use
507
+ complete keyed reconciliation. Unmapped rolling modules retain the smaller optional all-hint
508
+ runtime. Reports expose each emitted rolling site as `keyedArrayRollingWindowHints`, each rolling
509
+ step retained across a multi-window mapped chain as `keyedArrayMappedRollingWindowChainHints`, and
510
+ each safe map as `keyedMapUpdateHints`.
511
+
512
+ Native known-position updates can avoid a complete keyed scan too:
513
+
514
+ ```tsx
515
+ setItems((current) => current.toSpliced(selectedIndex, 0, nextItem));
516
+ setItems((current) => current.toSpliced(selectedIndex, 0, nextA, nextB));
517
+ setItems((current) => current.toSpliced(selectedIndex, 0, ...incomingItems));
518
+ setItems((current) => current.toSpliced(selectedIndex, 1));
519
+ setItems((current) => current.toSpliced(selectedIndex, 25));
520
+ setItems((current) => current.toSpliced(selectedIndex, 1, replacement));
521
+ setItems((current) => current.toSpliced(selectedIndex, 25, ...replacements));
522
+ setItems((current) => current.with(selectedIndex, replacement));
523
+ setItems((current) => {
524
+ return current.toSpliced(selectedIndex, 0, nextItem);
525
+ });
526
+ setItems((current) => {
527
+ return current.with(selectedIndex, replacement);
528
+ });
529
+
530
+ // Two same-key windows may be queued before one compiler flush.
531
+ setItems((current) => current.toSpliced(firstIndex, 25, ...firstRefresh));
532
+ setItems((current) => current.toSpliced(secondIndex, 25, ...secondRefresh));
533
+ ```
534
+
535
+ When every keyed list in a component is plain and has no identity, `Set` membership, or `Map`
536
+ lookup targets, single-item position hints (including range removal) select a smaller runtime
537
+ without target tracking. Ordinary map and append updates and complete reconciliation remain
538
+ available. Any sibling with targets, conditional content, host scopes, or broader structural hints
539
+ retains the corresponding full-capability runtime. Batch insertion and window replacement keep
540
+ their existing runtimes. This changes payload size, not array-method or React behavior.
541
+
542
+ The compiler recognizes a concise functional setter or a setter block containing exactly one direct
543
+ `return`. Its position must be either a safe-integer literal or a compiler-safe runtime expression,
544
+ such as an identifier, property read, arithmetic, conditional, or safe `Math` call. The update must insert
545
+ one or more compiler-safe items with zero removals, remove one item or a fixed positive safe-integer
546
+ literal range, replace one item through either `toSpliced()` or `with()`, or replace a fixed positive
547
+ safe-integer literal window with compiler-safe explicit items or a safe spread. Farm preserves method lookup,
548
+ evaluates the position and remaining arguments once in their original order, executes the ordinary
549
+ native call, and records metadata only after validating the committed native source, result, and
550
+ actual safe-integer position and clamped removal count. A batch requires at least two evaluated
551
+ items at runtime. Exact-window replacement supports a safe spread that evaluates to zero, one, or
552
+ many items. A fresh-key window creates every incoming key, descriptor, binding snapshot, and
553
+ detached row before changing the live DOM, rejects key collisions, and mounts the complete batch
554
+ through one document fragment. It then removes only the replaced window. When the incoming window
555
+ has the same length and the same keys in the same order, Farm prepares every binding read and
556
+ changed DOM target across the complete window first, patches the existing rows in place, and
557
+ updates the stored row objects used by later events. That path creates no descriptors or DOM rows,
558
+ and preserves row identity, focus, and selection. Validated same-key row and window refreshes also
559
+ keep the existing row map and element lookup, and skip redundant cache cleanup instead of
560
+ rebuilding whole-list bookkeeping. Source and key validation still run, and each flush commits the
561
+ new collection token for subsequent updates. Structural changes retain index rebuilding and cache
562
+ cleanup. A window may instead grow or shrink while it
563
+ reorders keys from inside its own removed interval and mixes them with globally fresh keys. Farm
564
+ prepares all reused binding updates, new descriptors, binding snapshots, and detached rows before
565
+ the first DOM write. It removes only retired rows, preserves each reused row, batches adjacent new
566
+ rows in a fragment, updates shifted suffix indexes, and applies LIS only to the reused part of that
567
+ interval so it moves the fewest connected rows needed by the local permutation. Rows outside the
568
+ interval are not rerendered or rebound.
569
+ Multiple length-preserving same-key windows
570
+ queued before one compiler flush compose into one atomic refresh. Fixed-length queued windows may
571
+ mix same-key refreshes with globally new final keys, and both disjoint and overlapping windows are
572
+ supported. An overlapping position uses the last queued value; intermediate identities are never
573
+ mounted. Farm validates the complete chain and final key set, then prepares every touched key,
574
+ binding value, DOM target, new descriptor, binding snapshot, and disconnected DOM row before the
575
+ first write. It patches same-key positions and swaps only final fresh-key positions. Untouched rows
576
+ keep their identity and are not recreated. The runtime otherwise creates one inserted row,
577
+ removes only the known row or range, or patches/replaces one row at that position without rereading
578
+ every existing key, descriptor, and binding. Surviving rows keep their DOM identity. Index-aware or
579
+ collection-reading rows, custom methods, position expressions with user calls or mutations,
580
+ runtime positions that are not safe integers, dynamic, zero, negative, or fractional removal
581
+ counts, other `toSpliced()` forms, updater blocks with extra statements, directives, conditional
582
+ returns, or no value-returning `return`, unsafe incoming expressions, queued chains containing a
583
+ structural window or unhinted intermediate update, existing keys moved from outside the removed
584
+ interval, duplicate final keys, nested or React-owned rows, and failed checks use complete keyed
585
+ reconciliation before the fast path mutates the DOM.
586
+ Reports expose the site count as `keyedArrayPositionHints`. Batch insertion and exact-window
587
+ replacement use progressively separate optional runtime capabilities, so existing single-position
588
+ and batch-only bundles do not retain window validation or replacement code.
589
+
590
+ A direct native reverse can carry its complete permutation to a separate optional runtime:
591
+
592
+ ```tsx
593
+ setItems((current) => current.toReversed());
594
+ setItems((current) => {
595
+ return current.toReversed();
596
+ });
597
+ ```
598
+
599
+ Farm recognizes the concise form and a block containing exactly one direct `return`. It preserves
600
+ the method lookup, call result, and errors, then records metadata only for the native method on an
601
+ ordinary array whose chain starts at the committed collection. One direct reverse
602
+ verifies equal lengths and every reversed item identity before moving the existing keyed elements
603
+ with the minimum `n - 1` connected DOM moves. It does not reread row keys, descriptors, or bindings
604
+ and does not run the generic LIS calculation. Consecutive concise native `toReversed()` and
605
+ `toSorted()` setters queued before one flush compose into one final validated permutation. The
606
+ runtime skips intermediate DOM states. When the proven chain contains only reversals, Farm tracks
607
+ their parity relative to the committed rows: an even count validates exact identity and performs
608
+ no DOM moves, source-item map construction, or LIS; an odd count validates exact reverse and uses
609
+ the same minimum `n - 1` moves as one reverse. A chain containing a sort keeps the general final
610
+ permutation and uses LIS once. A concise updater or a block containing exactly one direct
611
+ value-returning `return` may also chain two or more native reorder operations:
612
+
613
+ ```tsx
614
+ setItems((current) => current.toSorted((left, right) => left.rank - right.rank).toReversed());
615
+ setItems((current) => {
616
+ return current.toSorted((left, right) => left.rank - right.rank).toReversed();
617
+ });
618
+ ```
619
+
620
+ Farm evaluates every lookup and call in JavaScript order, carries the same committed token through
621
+ the pipeline, and reconciles only its final result. Index-aware or collection-reading rows,
622
+ arguments to `toReversed()`, referenced comparators, computed methods, updater blocks with extra
623
+ statements, directives, conditional returns, or no returned value, custom methods, sparse or
624
+ subclassed behavior, structural calls after reordering, an unhinted intermediate update, nested or
625
+ React-owned rows, and failed checks keep complete keyed reconciliation.
626
+
627
+ A compiler-safe `filter()` or bounded `slice()` prefix may precede the native reorder suffix in a
628
+ concise updater or exact one-return block. A filter predicate may be concise or contain exactly one
629
+ direct value-returning `return`:
630
+
631
+ ```tsx
632
+ setItems((current) =>
633
+ current
634
+ .filter((item) => {
635
+ return item.visible;
636
+ })
637
+ .toSorted((left, right) => left.rank - right.rank)
638
+ .toReversed(),
639
+ );
640
+ ```
641
+
642
+ Farm validates the complete survivor set and final order before the first DOM write, removes only
643
+ rejected rows, and applies LIS once to the survivors. Concise or exact one-return filter/slice and
644
+ reorder setters also compose when queued in that order before one flush. Unsupported calls or a
645
+ structural call after a reorder fall back. Reports count each compiled step in the existing filter,
646
+ slice, sort, or reverse counter, and modules without those operations omit their optional runtimes.
647
+ Farm does not polyfill `Array.prototype.toReversed`.
648
+
649
+ A compiler-safe same-key map may also appear before or after native reorder steps:
650
+
651
+ ```tsx
652
+ setItems((current) =>
653
+ current
654
+ .map((item) => (item.id === editedId ? { ...item, label: nextLabel } : item))
655
+ .map((item) => (item.id === editedId ? { ...item, rank: nextRank } : item))
656
+ .toSorted((left, right) => left.rank - right.rank),
657
+ );
658
+ ```
659
+
660
+ One callback may select several rows through nested expressions, structured early returns, or a
661
+ fully returning `switch`:
662
+
663
+ ```tsx
664
+ setItems((current) =>
665
+ current.map((item) => {
666
+ const matchesReviewed = item.id === reviewedId;
667
+ if (matchesReviewed) return { ...item, status: "reviewed" };
668
+ const matchesEscalated = item.id === escalatedId;
669
+ if (matchesEscalated) {
670
+ return { ...item, status: "escalated", priority: 1 };
671
+ }
672
+ return item;
673
+ }),
674
+ );
675
+ ```
676
+
677
+ Every condition must be compiler-safe, and every leaf must return the original item or a safe
678
+ object spread of it, with at least one unchanged and one replacement path. Concise expressions and
679
+ blocks made from fully returning `if` or `switch` branches plus local `const` aliases are accepted.
680
+ Each alias must have a simple identifier and compiler-safe initializer. A switch requires one
681
+ `default` and complete returning cases. Consecutive empty labels may share the next body, while
682
+ partial or dangling fallthrough is rejected. Mutable or destructured declarations, effectful
683
+ initializers, other intermediate statements, and ambiguous leaves use complete keyed
684
+ reconciliation. A runtime key change also falls back before any DOM write.
685
+
686
+ The functional setter may be concise or a block containing exactly one direct value-returning
687
+ `return`. Farm executes every native map and reorder call normally. For consecutive accepted maps,
688
+ it checks each native call but compares only the input and final result of that map segment, avoiding
689
+ a full lineage scan for every intermediate array. It verifies the committed token, dense-array
690
+ shape, a one-to-one source-item match, and every final replacement key before touching the DOM, then runs one
691
+ LIS and patches each changed row once. Unchanged rows need no second key or binding read. Queued
692
+ supported map-and-reorder setters compose against the same committed rows. Every accepted map
693
+ requires an inline synchronous conditional mapper whose leaves return either the original item or
694
+ an object-spread replacement, plus index-independent compiler-owned host rows. Concise expressions
695
+ and structured blocks with proven local `const` aliases plus fully returning `if` or `switch`
696
+ branches are supported.
697
+ Changed keys, referenced callbacks, mutable, destructured, or effectful declarations, other
698
+ intermediate statements or partial/dangling fallthrough, unconditional replacements, `thisArg`,
699
+ structural calls in the same chain, computed or custom methods, sparse or subclassed arrays,
700
+ collection-reading bindings, nested or React-owned rows, and failed checks use complete keyed
701
+ reconciliation. Reports use the existing map, sort, and reorder hint counters, and unrelated modules
702
+ do not retain this optional runtime.
703
+
704
+ The maps may also finish the concise pipeline:
705
+
706
+ ```tsx
707
+ setItems((current) =>
708
+ current
709
+ .toReversed()
710
+ .map((item) => (item.id === editedId ? { ...item, label: nextLabel } : item))
711
+ .map((item) => (item.id === editedId ? { ...item, rank: nextRank } : item)),
712
+ );
713
+ ```
714
+
715
+ Farm retains the preceding reorder instead of treating the mapped result as an unhinted snapshot.
716
+ An exact reverse uses the minimum-move reverse path without a general source-item lookup or LIS. A
717
+ sort remains an ambiguous permutation, so Farm performs one validated source lookup and LIS pass.
718
+ Safe maps on both sides of a reorder flatten their replacements back to the same committed rows.
719
+
720
+ Safe maps may also run before, between, or after index-independent `filter` or `slice` steps in one
721
+ concise functional setter or one block with a single direct `return`. A final native reorder is optional:
722
+
723
+ ```tsx
724
+ setItems((current) =>
725
+ current
726
+ .filter((item) => item.visible)
727
+ .map((item) => (item.id === editedId ? { ...item, label: nextLabel } : item))
728
+ .slice(0, limit)
729
+ .toSorted((left, right) => left.rank - right.rank),
730
+ );
731
+
732
+ setItems((current) =>
733
+ current
734
+ .map((item) => (item.id === editedId ? { ...item, label: nextLabel } : item))
735
+ .filter((item) => item.visible)
736
+ .slice(0, limit),
737
+ );
738
+ ```
739
+
740
+ The structural helpers retain both the committed survivor indices and mapped-item sources across
741
+ each accepted step. The final commit removes rejected rows, performs LIS moves only when a reorder
742
+ needs them, and patches bindings only for changed survivors. Every native callback and method still
743
+ runs in JavaScript order.
744
+
745
+ The structural and map steps may also be split across immediately adjacent setter calls in either
746
+ order:
747
+
748
+ ```tsx
749
+ // Map, then structural work.
750
+ setItems((current) =>
751
+ current.map((item) => (item.id === editedId ? { ...item, label: nextLabel } : item)),
752
+ );
753
+ setItems((current) => current.filter((item) => item.visible));
754
+ setItems((current) => current.slice(0, limit));
755
+
756
+ // Structural work, then maps.
757
+ setItems((current) => current.filter((item) => item.visible));
758
+ setItems((current) => current.slice(0, limit));
759
+ setItems((current) =>
760
+ current.map((item) => (item.id === editedId ? { ...item, label: nextLabel } : item)),
761
+ );
762
+ setItems((current) =>
763
+ current.map((item) => (item.id === editedId ? { ...item, rank: nextRank } : item)),
764
+ );
765
+ ```
766
+
767
+ Farm links only consecutive calls to the same setter. A leading map retains its first committed
768
+ source through later structural work; a terminal map consumes the saved survivor lineage from the
769
+ preceding filter or slice. Multiple safe steps in either segment may share the proof, and mixed
770
+ map/structural/map sequences compose. Every result and key is validated before the queued commit
771
+ touches the DOM. An intervening statement, another setter, an unsafe callback, a changed key, or
772
+ failed runtime validation keeps complete keyed reconciliation.
773
+
774
+ The survivor proof may continue through adjacent native reorder setters:
775
+
776
+ ```tsx
777
+ setItems((current) => current.filter((item) => item.visible));
778
+ setItems((current) =>
779
+ current.map((item) => (item.id === editedId ? { ...item, rank: nextRank } : item)),
780
+ );
781
+ setItems((current) => current.toSorted((left, right) => left.rank - right.rank));
782
+ setItems((current) => current.toReversed());
783
+ ```
784
+
785
+ Farm retains the committed survivor positions and same-key replacements until the final queued
786
+ value. The commit removes rejected rows, patches changed survivors, and applies the final order in
787
+ one validated DOM transaction. Exact reverses use the minimum-move reverse path; an arbitrary sort
788
+ uses one source lookup and LIS. Non-adjacent calls, another setter, unsupported syntax, or a failed
789
+ shape/key check keep complete reconciliation.
790
+
791
+ The reorder and safe maps may also be adjacent setter calls in the same synchronous block:
792
+
793
+ ```tsx
794
+ setItems((current) => current.toReversed());
795
+ setItems((current) =>
796
+ current.map((item) => (item.id === editedId ? { ...item, label: nextLabel } : item)),
797
+ );
798
+ setItems((current) =>
799
+ current.map((item) => (item.id === editedId ? { ...item, rank: nextRank } : item)),
800
+ );
801
+ ```
802
+
803
+ The compiler links only consecutive calls to the same setter. It keeps the reorder token through
804
+ each accepted native map, then validates row keys before applying the same exact-reverse or
805
+ sort-permutation path at commit. Adjacent compiler-safe filter or slice work switches to the
806
+ structural proof above. An intervening statement, another setter, an unsupported map, or a changed
807
+ key keeps the ordinary complete fallback. Standalone map-only components do not retain the
808
+ map-and-reorder runtime.
809
+
810
+ The mirror order is supported as well: two or more adjacent concise same-key map setters may be
811
+ followed by a concise native reverse or sort setter. Farm records their replacement lineage from
812
+ the committed collection and carries it into the final reorder. Only adjacent calls to the same
813
+ setter are linked; intervening work and unsupported updates retain complete reconciliation.
814
+
815
+ Mapped lineage also continues through multiple adjacent native reorder setters. For example,
816
+ `map -> reverse -> sort -> reverse` keeps the same committed-row proof until the final value, then
817
+ performs one validated keyed reconciliation. A concise `map().toReversed()` pipeline may start the
818
+ same chain. Adjacent compiler-safe filter or slice work changes it into a structural chain while
819
+ retaining the committed source. Every updater and native method still executes in order; another
820
+ setter, intervening work, or an unsupported method ends the chain and preserves the complete
821
+ fallback.
822
+
823
+ A reverse before the safe map pipeline may be queued in a separate setter:
824
+
825
+ ```tsx
826
+ setItems((current) => current.toReversed());
827
+ setItems((current) =>
828
+ current.map((item) => (item.id === editedId ? { ...item, label: nextLabel } : item)).toReversed(),
829
+ );
830
+ ```
831
+
832
+ A direct `toReversed()` suffix is more specific than an arbitrary permutation. When all preceding
833
+ maps retain committed row order, Farm validates the mirrored source-to-result relation and every
834
+ changed binding before touching the DOM, then performs the minimum-move reverse without building a
835
+ second item lookup map or running LIS. Additional exact reversals toggle that proof between reverse
836
+ and identity. Therefore two reversals after safe maps patch changed rows in committed order without
837
+ moving DOM nodes or creating the generic source map; three use the exact reverse path. Exact reverse
838
+ metadata also composes across queued setters: a queued reverse followed by safe maps and another
839
+ reverse retains exact identity, so only changed row bindings are patched. A preceding sort or any
840
+ ambiguous order keeps the general permutation path.
841
+
842
+ A direct native immutable sort can use the same optional reorder runtime:
843
+
844
+ ```tsx
845
+ setItems((current) => current.toSorted((left, right) => left.rank - right.rank));
846
+ setLabels((current) => current.toSorted());
847
+ setItems((current) => {
848
+ return current.toSorted((left, right) => left.rank - right.rank);
849
+ });
850
+ ```
851
+
852
+ Farm recognizes a concise functional setter or a block containing exactly one direct `return`,
853
+ with no comparator or an inline synchronous comparator from the compiler-safe expression subset.
854
+ It preserves the original method lookup, comparator, stable native result, and errors. After the
855
+ native sort runs, the runtime validates an ordinary dense array whose reorder chain starts at the
856
+ committed collection, equal lengths, and a unique one-to-one item-identity permutation. It then
857
+ uses LIS to move only `n - LIS` keyed DOM nodes without rereading row keys, descriptors, or
858
+ bindings. Multiple concise native sorts and reverses queued in one flush, or chained in one concise
859
+ updater, share the original committed token and reconcile only their final permutation. The native
860
+ sorting work itself is unchanged.
861
+
862
+ Index-aware or collection-reading rows, referenced comparators, updater blocks with extra
863
+ statements, directives, conditional returns, or no returned value, computed or unsupported chained
864
+ calls, custom methods, sparse or subclassed arrays, duplicate item identities, unhinted intermediate
865
+ updates, structural calls after reordering, nested or React-owned rows, and failed checks keep
866
+ complete keyed reconciliation. A compiler-safe filter/slice prefix is supported. Reports count each
867
+ compiled sort step as a `keyedArraySortHints` entry; sort shares the optional reorder runtime, and
868
+ Farm does not polyfill `Array.prototype.toSorted`.
869
+
870
+ Concise or single-return block-bodied immutable filters on a direct keyed array can carry removal
871
+ positions into the same optional runtime:
872
+
873
+ ```tsx
874
+ setItems((current) => current.filter((item) => item.id !== removedId));
875
+ setItems((current) => {
876
+ return current.filter((item) => item.id !== removedId);
877
+ });
878
+ setItems((current) =>
879
+ current.filter((item) => {
880
+ return item.id !== removedId;
881
+ }),
882
+ );
883
+ ```
884
+
885
+ For compiler-owned host rows whose render and key do not observe the row index, Farm validates the
886
+ native filter chain, every surviving item identity, and every surviving key before removing only
887
+ the rejected DOM rows. It does not recreate descriptors or reread bindings for unchanged rows,
888
+ and queued filters compose before one compiler flush. Index-aware rows or predicates, updater blocks
889
+ with extra statements, directives, conditional returns, or no value-returning `return`, predicate
890
+ blocks with those unsupported shapes, custom filter methods, sparse or subclassed arrays,
891
+ collection-reading bindings or keys, React-owned row structures, mixed dirty dependencies, and
892
+ failed validation use complete keyed reconciliation. No option or new component is required. The
893
+ compiler report exposes the emitted-site count as `keyedArrayFilterHints`.
894
+
152
895
  An otherwise eligible host row may also contain an inline synchronous React event:
153
896
 
154
897
  ```tsx
@@ -237,6 +980,12 @@ components, fragments, refs, SVG, spreads, dangerous HTML, and index keys keep t
237
980
  row on React's fallback. Additional keyed levels that satisfy the same host-only contract are
238
981
  analyzed recursively instead of using a fixed nesting limit.
239
982
 
983
+ When every inner key stays in the same order, the nested scope reuses its row table and skips
984
+ position-map construction and LIS planning. It still validates all keys and updates every child
985
+ scope and binding. Insertions, removals, and reorders keep the existing structural reconciliation;
986
+ duplicate keys or an invalid child scope keep the existing React fallback. This also applies to
987
+ keyed ranges next to host-only conditions inside a nested mixed range.
988
+
240
989
  For example, `boards → columns → cards → tags` becomes a tree of keyed scopes. Each stable parent
241
990
  key owns its child key table and LIS pass. Moving a board carries its column, card, and tag scopes;
242
991
  reordering cards reconciles only the selected column. Block IDs stay globally unique while runtime
@@ -374,8 +1123,27 @@ Generated callback refs give directly patched host elements stable private targe
374
1123
  React-owned component may therefore return `null`, a fragment, or multiple host nodes without
375
1124
  shifting an unrelated compiler binding. These refs do not add attributes to SSR output.
376
1125
 
1126
+ Custom element tags and customized built-ins using `is` remain React-owned rather than receiving
1127
+ compiler attribute writes or host descriptors. React controls property setters, attributes, events,
1128
+ and element creation according to the installed React version, including during hydration.
1129
+
1130
+ State-dependent `contentEditable` bindings and non-literal `contentEditable` values in host
1131
+ descriptors remain React-owned. This preserves the difference between explicit `false` (not editable)
1132
+ and an absent value (inherit from the parent). Literal strings on ordinary direct hosts remain
1133
+ eligible for compilation.
1134
+
1135
+ `title` and `meta` elements inside conditional, keyed, or recursive host descriptors remain
1136
+ React-owned. React decides their document placement and cleanup, including React 19 head placement
1137
+ and the `itemProp` exception. The compiler does not implement a separate metadata manager.
1138
+
377
1139
  Conditional blocks have three safe ownership levels. One or more proven host-only direct branches
378
1140
  may become compiler-owned ranges among static host siblings, including at the exact component root.
1141
+ Script elements in conditional branches or keyed rows remain React-owned, including nested and
1142
+ non-executable scripts. React retains responsibility for inert script creation on insertion and
1143
+ reinsertion; the compiler does not create these elements through its host descriptors.
1144
+ The production browser control is
1145
+ `NODE_ENV=production node packages/farm-react/scripts/test-script-ownership-browser.mjs` from the
1146
+ workspace root. Set `CHROME_PATH` to use an installed Chrome instead of Playwright's browser.
379
1147
  A dedicated container with exactly one conditional child uses the smaller compiler-owned branch
380
1148
  boundary. The more general React-owned conditional path accepts supported events, nested host
381
1149
  conditionals, keyed lists, and component islands. A compiler-owned host branch may now recursively
@@ -425,17 +1193,59 @@ compiler: {
425
1193
 
426
1194
  The default path is `.farm/react-compiler.json`. The report covers the production browser graph and
427
1195
  contains project-relative module paths, compiled component names, fallback details, and fallback
428
- reasons aggregated by count. A custom project-relative `reportFile` also enables reporting.
1196
+ reasons aggregated by count. Its summary and per-module `optimizations` also report
1197
+ `keyedIdentityTargets`, the number of scalar key-directed row bindings;
1198
+ `keyedMapLookupTargets`, the number of native-Map keyed lookup bindings;
1199
+ `keyedMembershipTargets`, the number of native-Set membership bindings;
1200
+ `keyedCollectionUpdateHints`, the number of compiler-proven native Set/Map mutation sites; and
1201
+ `keyedMapUpdateHints`, the number of compiler-proven keyed `map()` update calls; and
1202
+ `keyedArrayAppendHints`, the number of compiler-proven direct keyed-array append sites; and
1203
+ `keyedArrayFilterHints`, the number of compiler-proven keyed-array filter sites, including supported
1204
+ structural reorder pipelines; and
1205
+ `keyedArrayPrependHints`, the number of compiler-proven direct keyed-array prepend sites; and
1206
+ `keyedArrayPositionHints`, the number of compiler-proven native exact-position insertion, single or
1207
+ contiguous-range removal, single-row replacement, or exact-window replacement sites, including
1208
+ guarded compiler-safe runtime positions;
1209
+ and
1210
+ `keyedArrayReorderHints`, the number of compiler-proven native keyed-array reverse steps; and
1211
+ `keyedArraySortHints`, the number of compiler-proven native keyed-array sort steps; and
1212
+ `keyedArrayMappedRollingWindowChainHints`, the number of compiler-proven rolling steps retained
1213
+ across multi-window same-key map chains; and
1214
+ `keyedArrayRollingWindowHints`, the number of compiler-proven retained-tail plus incoming-suffix
1215
+ sites; and
1216
+ `keyedArraySliceHints`, the number of compiler-proven keyed-array slice sites with literal or guarded
1217
+ compiler-safe runtime bounds, including supported structural reorder pipelines. A custom
1218
+ project-relative `reportFile` also enables reporting.
429
1219
 
430
1220
  The runtime test compares the same counter interaction on both paths: ordinary React performs a
431
1221
  second component render and commit, while the compiled component remains at one render and one
432
1222
  commit and updates its two bindings directly. This is a deterministic structural performance
433
1223
  assertion; it is not presented as a cross-machine timing benchmark.
434
1224
 
1225
+ `pnpm --filter @farm.js/react test:runtime-size` checks both gzip and Brotli compiler premiums
1226
+ against `RUNTIME_SIZE_RESULTS.json`, including plain keyed lists and the isolated core runtime.
1227
+ Missing or non-finite budget inputs and fixtures without an explicit budget policy fail the check.
1228
+ When intentionally adding or changing a baseline, generate it with
1229
+ `pnpm --filter @farm.js/react benchmark:runtime-size` and review the byte changes before committing;
1230
+ do not regenerate baselines just to hide a regression. These checks do not change application output.
1231
+
1232
+ Both runtime-size and keyed-target measurements compress each emitted JavaScript file independently,
1233
+ then sum the bytes. Multi-chunk builds also report per-file bytes and the union of entry chunks plus
1234
+ their static imports (`initial`), reachable dynamic imports and their dependencies (`deferred`), and
1235
+ any remaining emitted chunks (`unreferenced`). Shared chunks count once; deferred totals include all
1236
+ reachable lazy chunks, not a claim that every navigation downloads them. CSS, other assets, external
1237
+ dependencies and HTTP overhead are outside these JavaScript-only measurements. Existing single-chunk
1238
+ measurements are unchanged; concatenated code is used only for structural-marker checks.
1239
+
1240
+ Plain keyed-row features also omit conditional-boundary subscriptions, render adapters, and
1241
+ snapshot-update loops. Conditional features retain their per-block ownership and React fallback.
1242
+ The size suite checks a combined create/append/update/select/swap/remove/clear table as well as
1243
+ isolated operations, so an isolated fixture cannot hide retained conditional machinery.
1244
+
435
1245
  Application and prototype calls, dynamic style objects, handlers outside JSX events, nested,
436
- computed, and rest props patterns, async handlers, unkeyed or index-keyed lists, chained maps,
437
- unsupported conditional roots, effects, and more advanced hook support intentionally stay on React
438
- in this release. Compiler-owned keyed rows support either one dedicated host-only map/`List` or
1246
+ computed, and rest props patterns, async handlers, unkeyed or index-keyed lists, unsupported map
1247
+ chains, unsupported conditional roots, effects, and more advanced hook support intentionally stay
1248
+ on React in this release. Compiler-owned keyed rows support either one dedicated host-only map/`List` or
439
1249
  one or more non-interactive ranges in a nested or component-root host container. A dedicated
440
1250
  non-interactive row may also contain multiple recursive logical or ternary host branches beside
441
1251
  stateful static host siblings, plus recursively nested non-interactive keyed ranges scoped by every