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

package/README.md

@@ -300,19 +300,62 @@ expose the site count as `keyedArrayRollingWindowHints`.
 Native known-position updates can avoid a complete keyed scan too:
 
 ```tsx
-setItems((current) => current.toSpliced(500, 0, nextItem));
-setItems((current) => current.with(500, replacement));
+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, a build-time safe-integer position, one
-inserted item with zero removals, or one direct replacement. Farm preserves the ordinary native
-method call and records metadata only after validating the committed native source and result. The
-runtime creates one inserted row or patches/replaces one row at the known position without
-rereading every existing key, descriptor, and binding. Index-aware or collection-reading rows,
-custom methods, 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.
+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 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:
 
@@ -330,6 +373,26 @@ React-owned rows, and failed checks keep complete keyed reconciliation. Reports
 count as `keyedArrayReorderHints`, and modules without one omit the reorder runtime. Farm does not
 polyfill `Array.prototype.toReversed`.
 
+A direct native immutable sort can use the same optional reorder runtime:
+
+```tsx
+setItems((current) => current.toSorted((left, right) => left.rank - right.rank));
+setLabels((current) => current.toSorted());
+```
+
+Farm recognizes a concise functional setter with no comparator or an inline synchronous comparator
+from the compiler-safe expression subset. It preserves the original method lookup, comparator,
+stable native result, and errors. After the native sort runs, the runtime validates a committed
+ordinary dense array, equal lengths, and a unique one-to-one item-identity permutation. It then
+uses LIS to move only `n - LIS` keyed DOM nodes without rereading row keys, descriptors, or
+bindings. The native sorting work itself is unchanged.
+
+Index-aware or collection-reading rows, referenced comparators, block-bodied updaters, computed or
+chained calls, custom methods, sparse or subclassed arrays, duplicate item identities, queued
+uncommitted sorts, nested or React-owned rows, and failed checks keep complete keyed
+reconciliation. Reports expose the site count as `keyedArraySortHints`; sort shares the optional
+reorder runtime, and Farm does not polyfill `Array.prototype.toSorted`.
+
 Concise immutable filters on a direct keyed array can carry removal positions into the same
 optional runtime:
 
@@ -631,9 +694,12 @@ 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 known-position insertion or
-replacement sites; 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
 sites; and
 `keyedArraySliceHints`, the number of compiler-proven direct keyed-array slice sites. A custom