@farm.js/react 0.1.0-beta.7 → 0.1.0-beta.8

package/README.md

@@ -301,24 +301,61 @@ Native known-position updates can avoid a complete keyed scan too:
 
 ```tsx
 setItems((current) => current.toSpliced(selectedIndex, 0, nextItem));
+setItems((current) => current.toSpliced(selectedIndex, 0, nextA, nextB));
+setItems((current) => current.toSpliced(selectedIndex, 0, ...incomingItems));
 setItems((current) => current.toSpliced(selectedIndex, 1));
+setItems((current) => current.toSpliced(selectedIndex, 25));
+setItems((current) => current.toSpliced(selectedIndex, 1, replacement));
+setItems((current) => current.toSpliced(selectedIndex, 25, ...replacements));
 setItems((current) => current.with(selectedIndex, replacement));
+
+// Two same-key windows may be queued before one compiler flush.
+setItems((current) => current.toSpliced(firstIndex, 25, ...firstRefresh));
+setItems((current) => current.toSpliced(secondIndex, 25, ...secondRefresh));
 ```
 
 The compiler recognizes only a concise functional setter and either a safe-integer literal or a
 compiler-safe runtime position expression, such as an identifier, property read, arithmetic,
-conditional, or safe `Math` call. The update must insert one item with zero removals, remove one
-item, or directly replace one item. Farm preserves method lookup, evaluates the position and
-remaining arguments once in their original order, executes the ordinary native call, and records
-metadata only after validating the committed native source, result, and actual safe-integer
-position. The runtime creates one inserted row, removes one known row, or patches/replaces one row
-at that position without rereading every existing key, descriptor, and binding. Surviving rows keep
-their DOM identity. Index-aware or collection-reading rows, custom methods, position expressions
-with user calls or mutations, runtime positions that are not safe integers, other `toSpliced()`
-forms, block-bodied updaters, unsafe incoming expressions, queued uncommitted updates, reused keys,
-nested or React-owned rows, and failed checks use complete keyed reconciliation. Reports expose the
-site count as `keyedArrayPositionHints`; the capability is tree-shaken from modules that do not emit
-it.
+conditional, or safe `Math` call. The update must insert one or more compiler-safe items with zero
+removals, remove one item or a fixed positive safe-integer literal range, replace one item through
+either `toSpliced()` or `with()`, or replace a fixed positive safe-integer literal window with
+compiler-safe explicit items or a safe spread. Farm preserves method lookup,
+evaluates the position and remaining arguments once in their original order, executes the ordinary
+native call, and records metadata only after validating the committed native source, result, and
+actual safe-integer position and clamped removal count. A batch requires at least two evaluated
+items at runtime. Exact-window replacement supports a safe spread that evaluates to zero, one, or
+many items. A fresh-key window creates every incoming key, descriptor, binding snapshot, and
+detached row before changing the live DOM, rejects key collisions, and mounts the complete batch
+through one document fragment. It then removes only the replaced window. When the incoming window
+has the same length and the same keys in the same order, Farm prepares every binding read and
+changed DOM target across the complete window first, patches the existing rows in place, and
+updates the stored row objects used by later events. That path creates no descriptors or DOM rows,
+and preserves row identity, focus, and selection. A fixed-length window may instead reorder keys
+from inside its own removed interval and mix them with globally fresh keys. Farm prepares all
+reused binding updates, new descriptors, binding snapshots, and detached rows before the first DOM
+write. It removes only retired rows, preserves each reused row, batches adjacent new rows in a
+fragment, and applies LIS only to the reused part of that interval so it moves the fewest connected
+rows needed by the local permutation. Rows outside the interval are not rerendered or rebound.
+Multiple length-preserving same-key windows
+queued before one compiler flush compose into one atomic refresh. Fixed-length queued windows may
+mix same-key refreshes with globally new final keys, and both disjoint and overlapping windows are
+supported. An overlapping position uses the last queued value; intermediate identities are never
+mounted. Farm validates the complete chain and final key set, then prepares every touched key,
+binding value, DOM target, new descriptor, binding snapshot, and disconnected DOM row before the
+first write. It patches same-key positions and swaps only final fresh-key positions. Untouched rows
+keep their identity and are not recreated. The runtime otherwise creates one inserted row,
+removes only the known row or range, or patches/replaces one row at that position without rereading
+every existing key, descriptor, and binding. Surviving rows keep their DOM identity. Index-aware or
+collection-reading rows, custom methods, position expressions with user calls or mutations,
+runtime positions that are not safe integers, dynamic, zero, negative, or fractional removal
+counts, other `toSpliced()` forms, block-bodied updaters, unsafe incoming expressions, queued
+chains containing a structural window or unhinted intermediate update, existing keys moved from
+outside the removed interval, length-changing partially reused windows, duplicate final keys,
+nested or React-owned rows, and failed checks use complete keyed reconciliation before the fast
+path mutates the DOM.
+Reports expose the site count as `keyedArrayPositionHints`. Batch insertion and exact-window
+replacement use progressively separate optional runtime capabilities, so existing single-position
+and batch-only bundles do not retain window validation or replacement code.
 
 A direct native reverse can carry its complete permutation to a separate optional runtime:
 
@@ -657,8 +694,10 @@ reasons aggregated by count. Its summary and per-module `optimizations` also rep
 `keyedArrayAppendHints`, the number of compiler-proven direct keyed-array append sites; and
 `keyedArrayFilterHints`, the number of compiler-proven direct keyed-array filter sites; and
 `keyedArrayPrependHints`, the number of compiler-proven direct keyed-array prepend sites; and
-`keyedArrayPositionHints`, the number of compiler-proven native exact-position insertion, removal,
-or replacement sites, including guarded compiler-safe runtime positions; and
+`keyedArrayPositionHints`, the number of compiler-proven native exact-position insertion, single or
+contiguous-range removal, single-row replacement, or exact-window replacement sites, including
+guarded compiler-safe runtime positions;
+and
 `keyedArrayReorderHints`, the number of compiler-proven direct native keyed-array reverse sites; and
 `keyedArraySortHints`, the number of compiler-proven direct native keyed-array sort sites; and
 `keyedArrayRollingWindowHints`, the number of compiler-proven retained-tail plus incoming-suffix