@symbiote-native/engine 1.2.0 → 1.3.1

package/build/tree-host.js

@@ -1,28 +1,12 @@
-// The TREE HOST seam — the one place JS asks about a tree it does not hold.
-//
-// `@symbiote-native/engine` keeps NO tree. Every adapter mutation appends an opcode to
-// `mutation-buffer.ts`, and turning that buffer into a tree is the HOST's job: native on device, and
-// headlessly the TypeScript applier in `@symbiote-native/test-utils`, installed by `installFabric()`.
-// That applier lives there for the same reason the fake `nativeFabricUIManager` does — it is a JS
-// stand-in for a native thing, and `core/test-utils` is a devDependency of the adapters rather than a
-// runtime one, so nothing an app loads contains a JS tree.
-//
-// Shaped after `fabric.ts`'s slot seam on purpose: a resolver plus a test-time installer.
-//
-// `undefined` / empty is an ORDINARY answer from every read here, not an error — the same contract
-// `committedRecordOf` already carried. A runtime with no host, a node the host has not seen, and a
-// genuinely absent value are indistinguishable to a caller, and all three degrade.
+// The tree host seam — the one place JS asks about a tree it does not hold. @symbiote-native/engine
+// keeps no tree: every adapter mutation appends an opcode (mutation-buffer.ts), and turning that
+// into a tree is the host's job — native on device, a TypeScript applier headlessly (test-utils).
 import { hasChangedSinceCommit, hasPendingOps, noteCommitDrained, recordCommit, takeBatch, } from './mutation-buffer.js';
 import { nativeEngine } from './native-engine.js';
 import { takePropStats } from './node.js';
-/**
- * The census of a tree nobody counted — what a host with no walk of its own answers, and what
- * `censusRetainedTree` answers when no host is installed at all.
- *
- * Not exported from the package barrel: it is a HOST-author constant, and an app reading a census
- * asserts against a mounted tree, where a zero from here cannot be mistaken for a zero from a real
- * empty tree.
- */
+// The census of a tree nobody counted — what a host with no walk answers, and what
+// censusRetainedTree answers with no host installed. Not exported from the package barrel: an app
+// reading a census asserts against a mounted tree, so a zero from here must not read as a real one.
 export const EMPTY_CENSUS = {
     nodes: 0,
     anchors: 0,
@@ -31,45 +15,25 @@ export const EMPTY_CENSUS = {
     flattenWidths: [],
 };
 let host;
-/**
- * Install the tree host. `installFabric()` (test-utils) calls this with the TypeScript applier; the
- * native module installs itself the same way once its bindings carry these reads.
- *
- * Passing `undefined` uninstalls, so a fixture can prove a path degrades rather than throws.
- */
+// Install the tree host. installFabric() (test-utils) calls this with the TypeScript applier; the
+// native module installs itself the same way. Passing undefined uninstalls, so a fixture can prove
+// a path degrades rather than throws.
 export function setTreeHost(next) {
     host = next;
 }
-/** The installed host, or `undefined` on a runtime that has none. */
+// The installed host, or undefined on a runtime that has none.
 export function treeHost() {
     return host;
 }
-/**
- * Push everything recorded since the last apply into the host.
- *
- * Every READ goes through here first. A reconciler navigates the tree it is mid-way through
- * BUILDING — Vue, Solid, Svelte and Angular all ask for a parent or a sibling between mutations and
- * long before the commit — so a host that only learned of ops at `completeRoot` would answer about a
- * tree several operations stale. The ops are structural, so applying them early costs nothing: only
- * `OP_COMMIT` reaches Fabric, and one is recorded solely by `commitSurfaceOps` below, immediately
- * before its own drain.
- */
-/**
- * Adapters that COALESCE writes, given the last moment to record what they are holding.
- *
- * An adapter cannot always publish a write the instant its framework hands it over. Angular's
- * styling engine has no whole-value call — `ɵɵstyleMap` delivers one key per `Renderer2.setStyle`
- * — so the renderer accumulates the run and writes RN's one `style` prop once. That accumulator has
- * to be emptied before anything can observe the tree, and the adapter cannot know when that is: a
- * read and a commit both arrive from elsewhere.
- *
- * Both of them come through `flushOps`, which is what makes this the right seam and a cheap one — it
- * is the single door in front of every drain, `commit` included.
- *
- * NOT A COMMIT HOOK. It fires before every read as well, so a listener must be idempotent and must
- * do nothing when it holds nothing. It runs BEFORE the `hasPendingOps` check on purpose: a listener
- * holding a write has ops that are not in the buffer yet, so an empty buffer is no reason to skip it.
- */
+// Push everything recorded since the last apply into the host. Every read goes through here first
+// — a reconciler navigates the tree mid-build (Vue/Solid/Svelte/Angular all ask for a parent or
+// sibling before commit), so a host only told at completeRoot would answer about a stale tree.
+// Adapters that coalesce writes, given the last moment to record what they're holding. Angular's
+// styling engine has no whole-value call (ɵɵstyleMap delivers one key per setStyle), so the
+// renderer accumulates a run and writes RN's one style prop only once — flushed from here.
+// Not a commit hook: fires before every read too, so a listener must be idempotent and must do
+// nothing when it holds nothing. Runs before the hasPendingOps check, since a listener holding a
+// write has ops not in the buffer yet.
 const beforeFlush = new Set();
 export function registerBeforeFlush(listener) {
     beforeFlush.add(listener);
@@ -79,13 +43,9 @@ export function registerBeforeFlush(listener) {
 // and ask the same listener for what it has already handed over. One flag rather than per-listener
 // bookkeeping: the whole set is being drained, and re-entering any of it is the same mistake.
 let settling = false;
-/**
- * Collect what the listeners are holding, WITHOUT draining.
- *
- * Separate from `flushOps` because a read may legitimately decide it needs no drain — `parentOf`
- * skips one for a node whose placement is not pending — and skipping the drain must not also skip
- * asking. A held write is still a write, and a reader that cannot see it is reading a stale tree.
- */
+// Collect what the listeners are holding, without draining. Separate from flushOps because a read
+// may legitimately decide it needs no drain (parentOf skips one for a node whose placement isn't
+// pending), but skipping the drain must not also skip asking a held write.
 export function settleBeforeFlush() {
     if (settling || beforeFlush.size === 0)
         return;
@@ -106,63 +66,38 @@ export function flushOps() {
 }
 // Commits this window, for readCommitProfile below.
 let commits = 0;
-// A surface to ask for this window's node counts. They live in C++ and this profile is id-less, so
-// the window has to keep a tag to ask WITH, and exactly one: `walkCost_` is file-scope in
-// `SymbioteTree.cpp`, shared by every surface and drained on read, so asking a second surface in the
+// A surface to ask for this window's node counts, exactly one: walkCost_ is file-scope in
+// SymbioteTree.cpp, shared by every surface and drained on read, so asking a second surface in the
 // same window reads zeroes and a sum would be wrong rather than merely redundant.
 let lastCommittedTag;
-/**
- * Record a surface's commit and drain the buffer into the host.
- *
- * A SURFACE IS AN ANCHOR: an anchor is a node whose children belong to its parent's list, and a
- * surface is a node whose children belong to the root child set. Same shape, which is why `OP_COMMIT`
- * names one node and the host needs no `rootTag -> map`.
- *
- * `others` is every OTHER live surface, and it exists because the buffer is GLOBAL while a commit
- * names ONE root. A framework can mutate a tree that belongs to a different surface than the one
- * whose renderer it is holding — a portal, a tunnel, any cross-surface move — and every adapter
- * then asks its OWN surface to commit. The ops reach the host either way, so the other surface is
- * left correctly updated in the tree and never handed to `completeRoot`: a stale Fabric root that
- * nothing will refresh until something unrelated dirties it. Naming every root here is what makes a
- * commit mean "flush what changed" rather than "flush the surface I happen to be bound to".
- *
- * A single-surface app — every example, and the overwhelming case — passes an empty list and the
- * behaviour is byte-identical to naming only itself.
- */
+// Record a surface's commit and drain the buffer into the host. A surface is an anchor: its
+// children belong to the root child set the same way an anchor's belong to its parent's list,
+// which is why OP_COMMIT names one node and the host needs no rootTag -> map.
+// `others` is every other live surface, needed because the buffer is global while a commit names
+// one root — a portal or cross-surface move can mutate a different surface than the one
+// committing, and naming every root here is what flushes what actually changed.
+// A single-surface app (the overwhelming case) passes an empty list, byte-identical to naming
+// only itself.
 export function commitSurfaceOps(rootTag, surface, others = []) {
     commits += 1;
-    // No host: the ops STAY PENDING. Draining them here would be silent data loss — a surface created
-    // before a host is installed would have its own `createElement` thrown away, and the next commit
-    // that DOES reach a host names a node that host never saw. Nothing is red until then, and the
-    // throw when it comes names the commit rather than the discard.
-    //
-    // The commit op is not recorded either, for the same reason: it would sit at the head of the next
-    // batch, ahead of the creates it depends on.
+    // No host: ops stay pending, not drained — a surface created before a host installs would have
+    // its own createElement thrown away, and the next commit that does reach a host would name a
+    // node that host never saw. The commit op itself is skipped too, for the same reason.
     if (host === undefined)
         return;
-    // NOTHING TO PUBLISH — return before the host is asked to do anything.
-    //
-    // The host already declines `completeRoot` when the root child set comes back identical, but it
-    // decides that AFTER rebuilding the set: every child of the committed surface is visited to
-    // rediscover that none of them moved. Measured on the reference applier, a commit with nothing
-    // pending cost 0.0145 ms over 500 rows and 0.0822 over 4 000 — linear in the width of the surface,
-    // for a commit that publishes nothing.
-    //
-    // Who pays it: any frame where a framework re-ran an effect and produced no change, which for a
-    // reactive adapter is most frames.
-    //
-    // The post-commit hooks are NOT affected. `notifyCommitted`, `runPostCommitHooks`,
-    // `runDeferredAttaches` and the `afterCommit` drain all run in `surface.ts` AFTER this call and
-    // are deliberately not gated on the commit having made native calls — a fold that strips a prop
-    // makes its own commit byte-identical, and the hook reacting to that flip must still fire.
+    // Nothing to publish — return before the host does anything. The host already declines
+    // completeRoot on an identical child set, but only after rebuilding it: every child is
+    // revisited to discover none moved, linear cost for a commit that publishes nothing.
+    // Post-commit hooks are NOT affected: notifyCommitted/runPostCommitHooks/runDeferredAttaches/
+    // afterCommit all run after this call in surface.ts, deliberately ungated on native calls — a
+    // fold that strips a prop makes its commit byte-identical, and the hook must still fire.
     if (!hasChangedSinceCommit())
         return;
     for (const [otherTag, otherSurface] of others) {
         recordCommit(otherTag, otherSurface);
     }
-    // `undefined` means this surface no longer OWNS its root — a re-mount on the same rootTag took
-    // it. Its ops still drain, because a teardown is what carries the removals; completing the root
-    // would hand Fabric the dead surface's emptied tree over the live one's.
+    // undefined means this surface no longer owns its root — a re-mount on the same rootTag took
+    // it. Its ops still drain, since a teardown is what carries the removals.
     if (rootTag !== undefined) {
         recordCommit(rootTag, surface);
         lastCommittedTag = rootTag;
@@ -170,20 +105,15 @@ export function commitSurfaceOps(rootTag, surface, others = []) {
     host.applyOps(takeBatch());
     noteCommitDrained();
 }
-/**
- * NOTE: reading this now DRAINS the surface telemetry too — `nodesCreated` is folded in from
- * `readSurfaceTelemetry`, which zeroes on read in C++. A sampler polling this on an interval
- * therefore empties what a later `readSurfaceTelemetry` call would have reported.
- */
+// Reading this now drains the surface telemetry too — nodesCreated is folded in from
+// readSurfaceTelemetry, which zeroes on read in C++, so a sampler polling this on an interval
+// empties what a later readSurfaceTelemetry call would have reported.
 export function readCommitProfile() {
-    // ONE read, not two: `readSurfaceTelemetry` zeroes the C++ accumulator, so asking it twice hands
-    // the second caller zeroes and the field would read as "the buffer never crossed".
-    //
-    // Gated on a commit having LANDED in this window, and not merely on a tag being known. Fabric's
-    // `TransactionTelemetry::getCommitStartTime` asserts that a commit has started, so asking a
-    // surface that has not committed since the last read aborts the process in a debug build and
-    // reads an undefined time point in a release one. The window's own `commits` is the only thing
-    // that answers "is there anything to ask about" without asking.
+    // One read, not two: readSurfaceTelemetry zeroes the C++ accumulator, so asking twice hands the
+    // second caller zeroes and the field would read as "the buffer never crossed".
+    // Gated on a commit having landed this window, not merely a tag being known: Fabric's telemetry
+    // asserts a commit has started, so asking an uncommitted surface aborts in debug and reads
+    // garbage in release. `commits` answers "anything to ask about" without asking.
     const telemetry = commits === 0 || lastCommittedTag === undefined
         ? undefined
         : readSurfaceTelemetry(lastCommittedTag);
@@ -198,44 +128,24 @@ export function readCommitProfile() {
     commits = 0;
     return snapshot;
 }
-/**
- * RN's own commit telemetry for a surface THIS HOST NEED NOT HAVE DRIVEN, or `undefined` when the
- * runtime cannot answer.
- *
- * It exists for one comparison and should not be reached for anything else: `readCommitProfile`
- * accumulates inside our own commit, so it can only ever describe a tree we built, and the standing
- * open question is whether a tree-wide text re-measure is something we cause or something a Fabric
- * commit costs whoever drives it. Point this at a surface React Native's OWN renderer committed and
- * the two numbers are directly comparable — same device, same RN, same tree.
- *
- * `undefined` rather than zeroes on a runtime without the binding, deliberately: zeroes would read
- * as "the other renderer measures no text", which is precisely the claim under test.
- */
+// RN's own commit telemetry for a surface this host need not have driven, or undefined when the
+// runtime cannot answer. Exists for one comparison: point this at a surface RN's own renderer
+// committed and the two numbers are directly comparable — same device, same RN, same tree.
+// undefined rather than zeroes on a runtime without the binding, deliberately: zeroes would read
+// as "the other renderer measures no text", which is precisely the claim under test.
 export function readSurfaceTelemetry(surfaceId) {
     return nativeEngine()?.readSurfaceTelemetry?.(surfaceId);
 }
-/**
- * Arm the C++ half's diagnostics (`SymbioteDebug.h`), which `installBindings` already did from
- * `DEBUG=1` / `globalThis.__SYMBIOTE_DEBUG__` at install.
- *
- * This is for the LATER toggle — the runtime escape hatch `debug.ts` documents for hosts where the
- * env is not reachable. Without it a `globalThis.__SYMBIOTE_DEBUG__ = true` typed into a running app
- * would flip the JS half and silently leave the engine's own half dark, which is the surprise worth
- * the six lines.
- */
+// Arm the C++ half's diagnostics (SymbioteDebug.h), already done by installBindings from DEBUG=1 /
+// globalThis.__SYMBIOTE_DEBUG__ at install. This is for the LATER toggle: without it, flipping the
+// runtime escape hatch would flip the JS half and silently leave the engine's half dark.
 export function setNativeDebug(enabled) {
     nativeEngine()?.setDebugEnabled?.(enabled);
 }
-/**
- * Drain what the C++ half has logged since the last call.
- *
- * The reason those lines are retained at all rather than only written to stderr: a diagnostic nobody
- * can assert on is one that rots. This is what lets a test say "the engine warned about that" —
- * see `core/engine/cpp/tests/js/native-debug-log.itest.ts`.
- *
- * An empty array on a runtime without the binding, not `undefined`: the question "what was logged"
- * has an honest empty answer, unlike the telemetry read above, where a zero would be a false claim.
- */
+// Drain what the C++ half has logged since the last call. Retained rather than only written to
+// stderr so a test can assert "the engine warned about that" (native-debug-log.itest.ts).
+// An empty array on a runtime without the binding, not undefined: "what was logged" has an honest
+// empty answer, unlike the telemetry read above, where a zero would be a false claim.
 export function takeNativeDebugLog() {
     return nativeEngine()?.takeDebugLog?.() ?? [];
 }

package/build/view-config.js

@@ -1,16 +1,9 @@
-// Per-native-component event declarations: symbiote's slimmed ViewConfigRegistry.
-// Mirrors React Native's ViewConfig: each Fabric component declares which event
-// names it can emit. This is native-component knowledge (a Switch fires `change`,
-// a ScrollView fires `scroll`), shared by every adapter, so it lives here, not in
-// any one framework adapter.
-//
-// Flat-bag adapters (React / Vue / Solid) hand props and handlers mixed together
-// and must split them. They consult this registry to tell an event handler
-// (`onChange` -> `change`, a declared event) from a native prop that merely looks
-// like one (`onTintColor` -> `tintColor`, NOT a declared event -> stays a prop and
-// reaches Fabric). Structural adapters (Svelte `addEventListener`, Angular
-// `Renderer2.listen`) deliver events pre-separated and call `setEventListener`
-// directly, bypassing this entirely.
+// Per-native-component event declarations: symbiote's slimmed ViewConfigRegistry. Mirrors RN's
+// ViewConfig — each Fabric component declares which event names it can emit — shared by every
+// adapter, so it lives here rather than in any one framework adapter.
+// Flat-bag adapters (React/Vue/Solid) hand props and handlers mixed together and must split them:
+// they consult this registry to tell an event handler (onChange -> change) from a native prop that
+// merely looks like one. Structural adapters (Svelte, Angular) deliver events pre-separated.
 import { isRegisteredEvent } from './registry.js';
 // Accessibility events from RN's base ViewConfig: every view can emit them.
 // accessibilityAction fires on iOS + Android; the other three are iOS-only and inert
@@ -21,20 +14,15 @@ const A11Y_EVENTS = [
     'magicTap',
     'accessibilityEscape',
 ];
-// Events every view can emit, from RN's base ViewConfig. `press`/`pressIn`/`pressOut`/
-// `longPress` are synthesized from the touch stream (see events.ts); `layout` is
-// universal; `focus`/`blur` are RN's bubbling focus events declared on the base View
-// (ViewPropTypes.js FocusEventProps), so any view can emit them; the accessibility
-// events are base too, so they reach every component.
+// Events every view can emit, from RN's base ViewConfig. press/pressIn/pressOut/longPress are
+// synthesized from the touch stream (events.ts); layout is universal; focus/blur are RN's bubbling
+// focus events on the base View, so any view can emit them; the accessibility events are base too.
 const BASE_EVENTS = [
     'press',
     'pressIn',
     'pressOut',
-    // Synthesized from the touch stream like its four siblings, and omitted here until 2026-09-02.
-    // A name the press machine OWNS but the engine does not route is dead: `routeProp` hands an `on*`
-    // prop to `setEventListener` (and thus to the behavior's stash) only for a registered event, so
-    // `onPressMove` landed in `node.props` where nothing reads it. The wrapper that used to pass the
-    // same callback to the machine directly hid this.
+    // Must be registered like its four siblings: routeProp hands an on* prop to setEventListener
+    // only for a registered event, so an unregistered onPressMove lands in node.props unread.
     'pressMove',
     'longPress',
     'layout',
@@ -42,15 +30,9 @@ const BASE_EVENTS = [
     'blur',
     ...A11Y_EVENTS,
 ];
-// An event set is platform-invariant: a text input emits `change` on iOS and Android
-// alike; only the native component NAME differs (iOS RCTSinglelineTextInputView vs
-// Android AndroidTextInput, iOS Switch vs Android AndroidSwitch). So each primitive's
-// events are declared ONCE and keyed under BOTH platform names below. The table is
-// consulted by the resolved native name (SymbioteNode.component), and only one
-// platform's names ever exist at runtime, so the other platform's keys are inert (no
-// Platform.OS branch), the names simply coexist. Missing the Android keys is what made
-// onValueChange (and Switch/Modal/RefreshControl events) silently dead on Android: the
-// onX prop failed isEventFor, fell to setProp, and no listener was ever registered.
+// An event set is platform-invariant: a text input emits `change` on iOS and Android alike, only
+// the native component name differs. Each primitive's events are declared once and keyed under
+// both platform names — consulted by the resolved name, so only one side is ever live at runtime.
 const TEXT_INPUT_EVENTS = [
     'change',
     'focus',
@@ -67,11 +49,9 @@ const MODAL_EVENTS = [
     'requestClose',
     'orientationChange',
 ];
-// A scroll view's events are the same on both axes and both platforms; only the native
-// NAME differs (iOS RCTScrollView for both; Android RCTScrollView vertical vs
-// AndroidHorizontalScrollView horizontal). Declared once, keyed under each name below. The
-// Android horizontal name was missing, so a horizontal FlatList's onScroll never fired and
-// its windowing stalled: same failure mode as the text-input keys.
+// A scroll view's events are the same on both axes and both platforms; only the native name
+// differs (Android RCTScrollView vertical vs AndroidHorizontalScrollView horizontal). Declared
+// once, keyed under each name below — same shape as the text-input keys above.
 const SCROLL_EVENTS = [
     'scroll',
     'scrollBeginDrag',