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

package/README.md

@@ -23,7 +23,14 @@ 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.
 
 For selective adoption, use annotation mode:
 
@@ -34,6 +41,7 @@ renderer: react({
       mode: "annotation",
       directive: "use compiler",
       onUnsupported: "warn",
+      reactivity: "hybrid",
     },
   },
 }),
@@ -56,29 +64,37 @@ 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;
 - optional synchronous `const` or function-declaration handlers used by JSX events;
 - state-driven text, attributes, per-property inline styles, and controlled form properties;
 - host-rooted `condition && <element>` and `condition ? <element> : <element>` child blocks at
-  statically known locations, including supported nested boundaries;
+  statically known locations, including direct ranges among static siblings and at the component
+  root;
 - 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, dedicated host containers can transfer child ownership after mount for host-only
-conditional branches and 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:
 
@@ -96,6 +112,26 @@ or hydration, a same-branch update patches those bindings without replacing the
 change creates, removes, or replaces only the selected branch. No marker node is added to SSR output.
 More complex conditional shapes keep the existing React-owned conditional boundary.
 
+Eligible direct conditionals can also share a host container with static host siblings:
+
+```tsx
+<article data-update={updates}>
+  <header>Status</header>
+  {loading && <p>Loading {updates}</p>}
+  <section>Stable content</section>
+  {enabled ? <strong>Enabled</strong> : <span>Disabled</span>}
+  <footer>Actions</footer>
+</article>
+```
+
+That `article` may be the component's exact returned root. Farm adopts the original container and
+counts its direct static elements as anchors for the conditional ranges. Same-branch bindings patch
+in place; branch changes insert, remove, or replace only their range. Multiple changed ranges use
+one state snapshot and reconcile from right to left, including when adjacent ranges are empty. The
+root and every unchanged static sibling keep their DOM identity, and no wrapper or marker is added.
+Branch events, components, fragments, refs, SVG, spreads, nested dynamic blocks, or another
+unsupported direct child keep the container on the React-owned path.
+
 For a common keyed map, no new API is required:
 
 ```tsx
@@ -134,7 +170,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>
@@ -142,7 +178,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>
@@ -150,13 +195,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`:
@@ -190,10 +275,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:
 
@@ -290,23 +374,41 @@ Generated callback refs give directly patched host elements stable private targe
 React-owned component may therefore return `null`, a fragment, or multiple host nodes without
 shifting an unrelated compiler binding. These refs do not add attributes to SSR output.
 
-Conditional blocks have two safe ownership levels. A dedicated container with exactly one proven
-host-only conditional child can use compiler-owned branch instances. Events, keys, custom
-components, fragments, refs, SVG, attribute spreads, `dangerouslySetInnerHTML`, nested dynamic
-blocks, and static siblings in that container keep React ownership. The more general React-owned
-conditional path still accepts supported nested conditionals, keyed lists, and component islands.
-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`, the runtime also
-falls back to React so JavaScript and React rendering semantics remain exact.
+Conditional blocks have three safe ownership levels. One or more proven host-only direct branches
+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. 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.
@@ -334,8 +436,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.