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

package/README.md

@@ -23,7 +23,27 @@ export default defineConfig({
 ```
 
 `compiler: true` uses inference: every application TSX/JSX component is considered, eligible
-components are compiled, and everything else keeps the normal React path.
+components are compiled with hybrid reactivity, and everything else keeps the normal React path.
+
+Hybrid reactivity starts from the compiler's proven state-to-binding dependency lists, then marks
+only multi-state short-circuit bindings for runtime read tracking. For
+`enabled ? activeValue : inactiveValue`, an update to the inactive value does not schedule the
+binding. The runtime uses direct subscription indexes rather than proxies or a component-wide
+scan. Use `compiler: { reactivity: "static" }` to retain only the complete build-time dependency
+lists for comparison or diagnosis.
+
+Compiler output also selects its runtime capabilities at build time. A direct counter imports only
+the cell scheduler and direct-binding core; conditionals, keyed rows and LIS, nested host ranges,
+and component islands are retained only when a compiled component in that module needs them. Plain
+keyed rows omit the larger recursive-host and row-conditional extensions. This selection is
+automatic and does not add a configuration option or asynchronous runtime loading. The legacy
+`createCompiledComponent` export remains a complete compatibility entry for hand-authored
+definitions, while generated code uses the tree-shakable feature entry.
+
+The persisted production-size fixtures and regression gate live in
+[`RUNTIME_SIZE_RESULTS.md`](./RUNTIME_SIZE_RESULTS.md). The recorded direct-only runtime premium is
+73.6% smaller than the complete compatibility runtime premium; the feature-heavy keyed benchmark
+application removes 6,185 gzip bytes from its previous compiler-on build.
 
 For selective adoption, use annotation mode:
 
@@ -34,6 +54,7 @@ renderer: react({
       mode: "annotation",
       directive: "use compiler",
       onUnsupported: "warn",
+      reactivity: "hybrid",
     },
   },
 }),
@@ -56,6 +77,7 @@ The current compiler handles components that it can prove have:
 - one host-element root and a statically known host-element tree around supported conditional,
   keyed-list, and React component-island boundaries;
 - an identifier props parameter or flat object destructuring with aliases and defaults;
+- build-time dependency cells for referenced flat primitive props, with runtime identity guards;
 - top-level `useState` declarations;
 - optional compiler-safe derived `const` values declared after state and in source order;
 - whitelisted `Boolean`, `Number`, `String`, and deterministic `Math` calculations;
@@ -67,19 +89,25 @@ The current compiler handles components that it can prove have:
 - item-keyed `collection.map(...)` children and explicit `List` boundaries at statically known
   container locations, including supported non-mutating collection pipelines;
 - inline synchronous events inside otherwise eligible host-only keyed rows;
-- row-local logical and ternary host branches inside stable keyed-row containers;
+- multiple and recursively nested logical or ternary host branches inside non-interactive keyed
+  rows, including branches beside static host siblings;
 - stable module-level child components with compiler-safe props;
 - React-managed event handlers; and
 - no refs, effects, or unsupported dynamic child structures.
 
-The generated component preserves React ownership of initial placement, props, events, SSR, and
-hydration. Local state cells batch updates into a microtask and patch only compiler-known DOM
-targets. Proven host containers can transfer child ownership after mount for host-only conditional
-branches and ranges, plus non-interactive host-only keyed rows. An interactive row or a row with
-local conditional slots uses a hybrid boundary instead: React retains its events, conditional
-Fibers, and structural reconciliation, while Farm patches same-key bindings and refreshes only
-changed row-local branches. React still creates or hydrates all initial DOM. Anything outside those
-narrow contracts uses a small React-owned boundary or the complete original component.
+The generated component preserves React ownership of initial placement, parent update commits,
+identity-bearing props, events, SSR, and hydration. Local state cells batch updates into a
+microtask; eligible flat destructured primitive props join the same dependency index after React
+commits their parent update. The runtime skips unchanged binding output and patches only
+compiler-known DOM targets. Objects, arrays, functions, symbols, React elements, `children`, and
+identifier props retain the normal React prop-render path. Proven host containers
+can transfer child ownership after mount for host-only conditional
+branches and ranges, plus non-interactive host-only keyed rows and their recursively nested host
+conditions. An interactive row uses a hybrid boundary instead: React retains its events,
+conditional Fibers, and structural reconciliation, while Farm patches same-key bindings and
+refreshes only changed React-owned row-local branches. React still creates or hydrates all initial
+DOM. Anything outside those narrow contracts uses a small React-owned boundary or the complete
+original component.
 
 For a common dedicated conditional, no new component or annotation is required:
 
@@ -155,7 +183,7 @@ insert, removal, or reorder asks React to reconcile the rows, adopts the committ
 reapplies current bindings, and then resumes direct same-key patches. This avoids creating eventful
 DOM outside React's Fiber tree.
 
-A keyed row may also contain dedicated conditional slots:
+A non-interactive keyed row may also transfer its safe host conditions to the same keyed instance:
 
 ```tsx
 <ul>
@@ -163,7 +191,16 @@ A keyed row may also contain dedicated conditional slots:
     <li key={item.id}>
       <span>{item.label}</span>
       <div className="status-slot">
-        {item.done ? <strong>{item.label} complete</strong> : <span>In progress</span>}
+        <i>State</i>
+        {item.done ? (
+          <article>
+            <strong>{item.label} complete</strong>
+            <div>{item.details && <small>{item.description}</small>}</div>
+          </article>
+        ) : (
+          <span>In progress</span>
+        )}
+        <b>Prepared</b>
       </div>
       <section className="details-slot">{item.expanded && <p>{item.description}</p>}</section>
     </li>
@@ -171,13 +208,53 @@ A keyed row may also contain dedicated conditional slots:
 </ul>
 ```
 
-Each conditional must be the only meaningful child of its persistent lowercase host container.
-The compiler records its test and branch bindings per row key. A same-key collection update compares
-those prepared snapshots and asks React to render only the conditional boundaries whose selected
-branch or branch values changed. Other conditional rows and the outer map stay untouched. Inserts,
-removals, and reorders remain React structural commits for these rows, after which Farm re-adopts
-the host skeleton and resumes row-local updates. This keeps empty branches, SSR, hydration,
-recoverable hydration errors, error boundaries, and Fast Refresh inside React's ownership.
+The compiler prepares the row descriptor, static sibling positions, branch factories, and
+text/attribute/style bindings at build time. React creates or hydrates the initial list. After
+mount, a same-key update patches the active branch in place or mounts, replaces, or removes only the
+changed branch. Multiple and deeper host-only conditions share that row scope. Insertions and
+removals create or clean one row scope, while reorders use the normal LIS pass. The component body
+and map callback do not rerun, and no wrapper or hydration marker is added.
+
+This compiler-owned tier requires a lowercase non-interactive host row. Hooks, custom components,
+branch events, refs, SVG, fragments, spreads, dangerous HTML, controlled inputs inside a condition,
+and unproven expressions stay on React. An otherwise eligible row with inline events continues to
+use the hybrid boundary: React owns its conditional Fibers and structural commits, while Farm
+compares per-key snapshots and refreshes only changed slots. Duplicate runtime keys or invalid
+adopted DOM switch the complete list to React.
+
+An eligible outer keyed row may also own nested keyed ranges:
+
+```tsx
+<div>
+  {projects.map((project) => (
+    <section key={project.id}>
+      <h2>{project.name}</h2>
+      <ul>
+        <li>Tasks</li>
+        {project.tasks.map((task) => (
+          <li key={task.id}>{task.title}</li>
+        ))}
+        <li>End</li>
+      </ul>
+    </section>
+  ))}
+</div>
+```
+
+Every outer key receives an isolated inner key table and LIS pass. Moving a project preserves its
+task scope; reordering one task list touches only that project. Surviving project, task, and static
+sibling elements keep their DOM identity, and removing an outer row cleans its inner scope. The
+initial contract accepts non-interactive lowercase inner rows from `.map(...)` or inline `List`,
+including multiple ranges separated by static host siblings. Inner events or forms, Hooks, custom
+components, fragments, refs, SVG, spreads, dangerous HTML, and index keys keep the complete outer
+row on React's fallback. Additional keyed levels that satisfy the same host-only contract are
+analyzed recursively instead of using a fixed nesting limit.
+
+For example, `boards → columns → cards → tags` becomes a tree of keyed scopes. Each stable parent
+key owns its child key table and LIS pass. Moving a board carries its column, card, and tag scopes;
+reordering cards reconciles only the selected column. Block IDs stay globally unique while runtime
+instances are isolated by their complete parent-key path. Removing any parent cleans every
+descendant subscription before its DOM leaves the document.
 
 A keyed collection may use derived locals or an inline chain of `filter`, `slice`, `toSorted`, and
 `toReversed`:
@@ -211,10 +288,9 @@ the TypeScript `lib` with ES2023 and target a runtime that supports them when us
 
 React remains the fallback and compatibility boundary. An interactive map beside static children,
 a non-host sibling between ranges, a row with a non-inline or async handler, a file input or dynamic
-form control shape, a fragment, a ref, a custom component, or a conditional mixed directly beside
-other children in the same host slot uses the existing React-owned keyed boundary. The outer
-compiled component can still be skipped, but React reconciles that list's rows and owns their
-events, lifecycle, and state.
+form control shape, a fragment, a ref, a custom component, or any unsupported nested dynamic
+structure uses the existing React-owned keyed boundary. The outer compiled component can still be
+skipped, but React reconciles that list's rows and owns their events, lifecycle, and state.
 
 Non-interactive host maps can share a nested or component-root container with static host siblings:
 
@@ -315,21 +391,37 @@ Conditional blocks have three safe ownership levels. One or more proven host-onl
 may become compiler-owned ranges among static host siblings, including at the exact component root.
 A dedicated container with exactly one conditional child uses the smaller compiler-owned branch
 boundary. The more general React-owned conditional path accepts supported events, nested host
-conditionals, keyed lists, and component islands. Keys, custom components, fragments, refs, SVG,
-attribute spreads, `dangerouslySetInnerHTML`, nested dynamic blocks, and branch events keep React
-ownership. An empty ternary branch may be `null` or `false`. The inactive branch is described at
-build time but is never pre-mounted or cached. If a logical `&&` evaluates to a number such as `0`,
+conditionals, keyed lists, and component islands. A compiler-owned host branch may now recursively
+contain eligible host-only conditional ranges and non-interactive keyed ranges in nested host
+containers. Each nested range receives its own dependency entry and updates without rerunning or
+replacing the outer branch. When conditionals and keyed maps/`List` ranges are direct siblings in
+one safe host container, the compiler emits one ordered mixed-range controller. It mounts or removes
+conditional branches, applies independent LIS reconciliation to each keyed range, and preserves
+static siblings in place. Stateful leaf text, attributes, `className`, and individual inline style
+properties on those siblings are compiled into stable segment/sibling/path bindings. Their address
+does not shift when a nearby condition mounts or a keyed range inserts, removes, or reorders rows,
+so the same controller patches them from the current state snapshot without replacing the sibling
+or rerunning the owner. The same mixed layout may recurse inside safe branches and keyed rows.
+Keys on branches, custom components, fragments, refs, SVG, attribute spreads,
+`dangerouslySetInnerHTML`, branch events, interactive rows, and unsupported mixed children keep
+React ownership. An empty ternary branch may be `null` or `false`. The
+inactive branch is described at build time but is never pre-mounted or cached. If a logical `&&`
+evaluates to a number such as `0`,
 or adopted DOM no longer matches its descriptor, the affected container remounts through React so
 JavaScript, hydration, and React rendering semantics remain exact.
 
 All component-level boundary types share one block graph and one ID sequence. A nested
 binding records its nearest conditional parent. If one state flush affects both an outer
 conditional and its descendants, the runtime refreshes the mounted outer boundary once and skips
-the redundant descendant refreshes. React unmounts inner boundaries normally, their subscriptions
-are removed, and a later remount reads the latest compiler-cell values. Host-only keyed rows have
-separate runtime instances per key. Row-local conditional IDs are scoped to that instance and
-paired with its stable key, so two rows can use the same build-time slot ID without sharing data or
-subscriptions. Unsupported row subtrees stay complete React-owned keyed boundaries.
+the redundant descendant refreshes. React-owned inner boundaries unmount normally. Compiler-owned
+host scopes explicitly remove every nested subscription before their outer DOM is removed, and a
+later mount reads the latest compiler-cell values. Surviving keyed rows move with the existing LIS
+algorithm. Duplicate runtime keys, invalid adoption, or an unsafe logical value transfer the outer
+container back to React; descendant dependencies remain subscribed so that fallback stays live.
+Host-only keyed rows have separate runtime instances per key. Row-local conditional and keyed-range
+IDs are scoped to that instance and paired with its stable key, so two rows can use the same
+build-time slot ID without sharing data or subscriptions. Unsupported row subtrees stay complete
+React-owned keyed boundaries.
 
 Unsupported components fall back to React by default. Use `onUnsupported: "warn"` for diagnostics
 or `onUnsupported: "error"` while tightening an annotated migration.
@@ -357,8 +449,12 @@ Application and prototype calls, dynamic style objects, handlers outside JSX eve
 computed, and rest props patterns, async handlers, unkeyed or index-keyed lists, chained maps,
 unsupported conditional roots, effects, and more advanced hook support intentionally stay on React
 in this release. Compiler-owned keyed rows support either one dedicated host-only map/`List` or
-one or more non-interactive ranges in a nested or component-root host container. Inline synchronous
-events and dedicated row-local host conditional slots can use the single-list hybrid path, but
-branch events, interactive ranges beside siblings, nested dynamic blocks, conditionals mixed with
-siblings in one slot, non-inline or async row handlers, unsupported form shapes, custom components,
-fragments, refs, SVG, and duplicate runtime keys keep or switch to React ownership.
+one or more non-interactive ranges in a nested or component-root host container. A dedicated
+non-interactive row may also contain multiple recursive logical or ternary host branches beside
+stateful static host siblings, plus recursively nested non-interactive keyed ranges scoped by every
+stable parent key. Static sibling bindings support safe leaf text, attributes, `className`, and
+individual style properties; lifecycle-sensitive shapes continue to fall back. Inline synchronous
+row events continue to use the hybrid React-owned row path. Branch
+or nested-row events, interactive ranges beside siblings, non-inline or async row handlers,
+unsupported form shapes, custom components, fragments, refs, SVG, and duplicate runtime keys keep
+or switch to React ownership.