@symbiote-native/engine 0.4.0 → 1.0.0

package/build/host-behavior.js

@@ -26,6 +26,8 @@
 //
 // `registerHostBehavior` emits a `dlog` precisely so `DEBUG=1` answers "did my registration run at
 // all" before anyone starts debugging the behavior itself.
+import { parentsOf, subtreesOf } from './host-access.js';
+import { recordSetTag } from './mutation-buffer.js';
 import { dlog } from './debug.js';
 const behaviors = new Map();
 // Nodes that `removeChild` unlinked and that may or may not be coming back. See
@@ -39,7 +41,7 @@ const tornDown = new WeakSet();
 //
 // THE REGISTRY IS KEYED BY INTRINSIC TAG AND THE NODE IS NOT. `node.component` is the FABRIC view
 // name: every adapter resolves the tag through `descriptorFor` before calling `createElement`, so
-// `symbiote-view` arrives as `RCTView`. Keying the registry by Fabric name instead is not an
+// `view` arrives as `RCTView`. Keying the registry by Fabric name instead is not an
 // option — a pressable resolves to `RCTView` like any other view, so the press machine would
 // attach to every plain `View` in the app. So the tag alphabet is used EXACTLY ONCE, at
 // `attachHostBehavior`, where the caller still holds it; every later lookup reads this map.
@@ -53,6 +55,9 @@ const attached = new WeakMap();
 // ~1 000 calls on one benchmark row set), so neither may pay a Set insert for a feature no app
 // uses yet. While this is false both paths cost one boolean read, the same discipline as `isDebug`.
 let hasBehaviors = false;
+// See `hasAttachedBehaviors`. A behavior TYPE existing and a behavior being ON a node are different
+// questions, and the teardown sweep was asking the first one.
+let hasAttached = false;
 export function registerHostBehavior(component, behavior) {
     dlog(`registerHostBehavior: ${component}`);
     behaviors.set(component, behavior);
@@ -70,6 +75,107 @@ export function hostBehaviorFor(tag) {
 export function hasHostBehaviors() {
     return hasBehaviors;
 }
+/**
+ * Has a behavior ever ATTACHED to a node, as opposed to a behavior TYPE having been registered?
+ *
+ * `hasBehaviors` answers the second, and it is on from module load in every app: registering
+ * `Pressable` arms it whether or not one is ever mounted. It gates `createElement`'s attach probe
+ * correctly — a node has to be offered to the registry to find out. It gates the TEARDOWN SWEEP
+ * wrongly, and that is expensive: the sweep crosses every removed node into JS, which on a
+ * 1 000-row clear is ten thousand handles. Measured on `build-release`
+ * (`teardown-sweep-cost.itest.ts`): 1.8 ms with the sweep off against 6.3 ms with it on, i.e. 3.2x,
+ * all of it inside the commit. `Clear` is the one row where stock React Native beats every adapter.
+ *
+ * Nothing the sweep does can matter before the first attach, and the four collections say so:
+ * `attached` is written only by `attachHostBehavior`; `awaitingCommit` and `committedEachTime` are
+ * written only inside a `behavior.` branch; `parked` only by `detachAnimatedProps`, which has its
+ * own gate. The one remaining effect is marking `tornDown`, which exists so a later re-insert knows
+ * to re-arm — and there is nothing to re-arm.
+ *
+ * MONOTONE, deliberately: it turns on and never off, so it needs no accounting on a `WeakMap` that
+ * has no size and no destructor. Being late is the only way it can be wrong, and it cannot be late.
+ */
+export function hasAttachedBehaviors() {
+    return hasAttached;
+}
+// What an owner prop is called on the slot, or undefined when it belongs to the owner after all.
+//
+// Called from `routeProp` only for a node that HAS a slot (`node.childHost !== undefined`), which
+// is what keeps a WeakMap probe off the hot path: every other node is turned away by one field
+// read, the same gate `payloadFold` uses one layer down.
+export function slotPropNameFor(node, key) {
+    const behavior = attached.get(node);
+    if (behavior === undefined)
+        return undefined;
+    const named = behavior.slotProps?.[key];
+    if (named !== undefined)
+        return named;
+    const except = behavior.slotPropsExcept;
+    if (except !== undefined && !except.includes(key))
+        return key;
+    return undefined;
+}
+// Does this owner's slot host the app's children, or is it a built sibling they land beside? See
+// `slotTakesNoChildren`. Same `node.childHost` gate as every other probe here: the two callers ask
+// only after the field said there is a slot at all.
+export function slotTakesChildren(node) {
+    return attached.get(node)?.slotTakesNoChildren !== true;
+}
+// Nodes a behavior built that are NOT the slot, and whose payloads derive from the owner's props.
+//
+// `slotDerived` marks `node.childHost` and nothing else, which is one hop — enough for ScrollView,
+// whose only derived node IS the slot, and not enough for a primitive whose `buildStructure` builds
+// a chain. Button builds view > text > raw text and folds two of them from the same three owner
+// props; without this the deeper nodes freeze at their mount values, and the workaround is to write
+// them from inside a fold whose contract says it MUST be pure.
+//
+// A WeakMap rather than a field, for the reason `stashed` is one: this exists only for the handful
+// of nodes a composed behavior built, and a field costs a shape transition on every node in every
+// app. It is read only inside the `slotDerived` branch, which has already paid a WeakMap probe.
+const derived = new WeakMap();
+// Called from `buildStructure` for each node past the slot. Not idempotent-checked: structure is
+// built exactly once (`attachHostBehavior`, never `reattachSubtree`), so a second call would be a
+// bug worth seeing rather than one worth absorbing.
+export function addDerivedNode(owner, node) {
+    const existing = derived.get(owner);
+    if (existing === undefined)
+        derived.set(owner, [node]);
+    else
+        existing.push(node);
+}
+export function derivedNodesOf(owner) {
+    return derived.get(owner);
+}
+// Called from `setEventListener` on a PRESENCE flip of an owned name, and only there — the caller
+// has already established that this node owns the name, so the WeakMap probe is one it just paid.
+export function notifyOwnedListenerChange(node, name, wired) {
+    attached.get(node)?.onOwnedListenerChange?.(node, name, wired);
+}
+// Called from the two inserts once the child is in place. See `onChildInserted`.
+export function notifyChildInserted(node, child) {
+    attached.get(node)?.onChildInserted?.(node, child);
+}
+// What this owner does with a child of that Fabric component, or undefined when it does not claim
+// it at all. See `claimedChildren`.
+export function claimModeFor(node, component) {
+    return attached.get(node)?.claimedChildren?.[component];
+}
+/**
+ * Every owner key feeds the slot. The spelling for a `cloneElement` primitive, whose slot is not
+ * derived from a named set at all — see `IHostBehavior.slotDerived`.
+ *
+ * A sentinel in the SAME array rather than a second field, so `slotDerivesFrom` stays one lookup and
+ * a behavior that wants both spellings cannot express a contradiction.
+ */
+export const SLOT_DERIVED_ALL = '*';
+// Does this owner key feed the slot's payload? See `slotDerived`. Same `node.childHost` gate as
+// above keeps the WeakMap probe off every node that has no slot.
+export function slotDerivesFrom(node, key) {
+    const names = attached.get(node)?.slotDerived;
+    if (names === undefined)
+        return false;
+    return names.includes(SLOT_DERIVED_ALL) || names.includes(key);
+}
 // The app's listeners for names a behavior owns, per node. Not on the node: this exists only for
 // nodes carrying a behavior, and adding a field for it would pay a shape transition on every node
 // in every app for a feature almost none of them use.
@@ -104,14 +210,39 @@ export function attachHostBehavior(node, tag) {
     if (behavior === undefined)
         return;
     attached.set(node, behavior);
+    hasAttached = true;
+    // The tag itself, over the wire, so the host can resolve this tag's PLATFORM props without a trip
+    // back into JS. Here rather than in `createElement` because here is where a tag is known to name
+    // something: an app's own `<div>`-equivalent would otherwise pay an intern and an op to tell the
+    // host a name it has no rule for.
+    recordSetTag(node, tag);
+    // BEFORE `attach` and before any prop is routed, which is the whole point: it changes how a
+    // WRITE is stored, so a source written to this node must never arrive ahead of it.
+    if (behavior.resolvesImageSources === true)
+        node.resolvesImageSources = true;
+    if (behavior.nativeIdWinsOverId === true)
+        node.nativeIdWinsOverId = true;
     // A field rather than a lookup at payload-build time: `fabricProps` runs per node per commit and
     // must not pay a Map probe to discover that almost nothing has a fold.
     node.payloadFold = behavior.foldPayload;
+    // Shape before runtime: `attach` may want to read `node.childHost`, and nothing in `attach`'s
+    // contract depends on the node being childless. Deliberately NOT repeated in `reattachSubtree` —
+    // see `buildStructure`.
+    if (behavior.buildStructure !== undefined) {
+        node.childHost = behavior.buildStructure(node);
+    }
     behavior.attach(node);
     if (behavior.attachAfterCommit !== undefined)
         awaitingCommit.add(node);
-    if (behavior.afterCommit !== undefined)
+    if (behavior.afterCommit !== undefined) {
         committedEachTime.add(node);
+        node.hasCommitHook = true;
+        // Armed from the start, so the commit that first lands this node gives it a beat. A freshly
+        // created node has had no prop written through `setProp` yet — `createRawText`'s text is an OP,
+        // not a field — so nothing else would arm it, and its behavior would wait for a write that a
+        // purely declarative mount never makes.
+        noteCommitHookNodeChanged(node);
+    }
 }
 // Nodes whose behavior declared `afterCommit`. Separate from `awaitingCommit` because the two have
 // opposite lifetimes: one empties as its nodes commit, this one holds until teardown.
@@ -132,26 +263,112 @@ const awaitingCommit = new Set();
  * for the commit that lands it, and `detachSubtree` drops it if that commit never comes.
  */
 export function runDeferredAttaches(isCommitted) {
-    // The gate: an app registering no behavior pays two Set-size reads per commit, matching the
+    // The gate: an app registering no behavior pays one Set-size read per commit, matching the
     // discipline `hasBehaviors` sets for `createElement`.
-    if (awaitingCommit.size === 0 && committedEachTime.size === 0)
+    if (awaitingCommit.size === 0)
         return;
-    // SETUP BEFORE THE RECURRING BEAT, and the order is load-bearing on the FIRST commit, where a
-    // node carrying both hooks is drained by both. `attachAfterCommit` is where a behavior seeds the
-    // mirrors that `afterCommit` then compares against; run them the other way round and the first
-    // beat compares against nothing and commands a redundant write down to native.
     for (const node of awaitingCommit) {
         if (!isCommitted(node))
             continue;
         awaitingCommit.delete(node);
+        // The answer is worth recording, not just acting on. `runCommittedHooks` runs immediately after
+        // this and asks the SAME question about the SAME node, and `isCommitted` crosses the host
+        // boundary — so a node carrying both hooks paid two crossings for one fact on the commit that
+        // landed it. Two per `<text-input>` on a 1 000-row create, measured at the call site.
+        everCommitted.add(node);
         attached.get(node)?.attachAfterCommit?.(node);
     }
-    for (const node of committedEachTime) {
-        if (!isCommitted(node))
+}
+/**
+ * The recurring beat. Split from `runDeferredAttaches` because the two answer different questions:
+ * `attachAfterCommit` needs a FRESH FABRIC TAG, so it belongs below `completeRoot` and must not run
+ * on a commit that made no native call; `afterCommit` needs only "props were published", which a
+ * no-op commit satisfies just as well.
+ *
+ * Keeping them together made `afterCommit` unreachable for exactly the props a behavior owns: a fold
+ * that STRIPS a prop makes its own commit byte-identical, `commitContainer` returns above the drain,
+ * and the hook never sees the flip. TouchableOpacity's re-settle on `disabled` is the case
+ * (`disabled` is a MACHINE_ONLY key), Button's `title`/`color` the other.
+ *
+ * SETUP STILL RUNS BEFORE THE BEAT on the first commit, and the order is load-bearing: a node
+ * carrying both hooks has `attachAfterCommit` seed the mirrors `afterCommit` compares against. The
+ * caller preserves it by calling this AFTER `runDeferredAttaches` on the changed path — the no-op
+ * path has no setup to run, since a node with no Fabric tag has not committed at all.
+ */
+/**
+ * Nodes with a recurring hook whose props were written since the last beat.
+ *
+ * THE POPULATION THE BEAT RUNS OVER, and narrowing it to this is the second half of F-66. The
+ * first half stopped the loop CROSSING to decide whether to run a hook; this stops it running the
+ * hook at all for a node that cannot have anything to do — and the hook BODY is where the rest of
+ * the cost was. TextInput's asks the host for its `value` to compare against its native mirror,
+ * which the work ledger measures at `propOf` × 1 000 per commit, in all four adapters.
+ *
+ * Sound because both behaviors that document why they need the beat need it for the same event, a
+ * prop written on their own node. `switch.ts` says so outright — "a check scheduled only from
+ * `onChange` never re-runs for a prop change with no preceding native event … `afterCommit` costs
+ * nothing extra (it fires only on a commit that already changed something)" — and TextInput's
+ * controlled handshake has two sources, the app moving `value` and the user typing, the second of
+ * which writes `mostRecentEventCount`. A fold that STRIPS a prop is covered too: the write
+ * happened, and it is the PAYLOAD that comes out byte-identical, which is the case this hook was
+ * split from `attachAfterCommit` for.
+ */
+const commitHookNodesChanged = new Set();
+/**
+ * Arm a node's recurring hook for the next commit.
+ *
+ * Called from `setProp` — gated there on `node.hasCommitHook`, a boolean field beside
+ * `hasAriaAlias` on the same hidden class, so a node without a recurring hook pays one load and
+ * one branch per write and never reaches this.
+ */
+export function noteCommitHookNodeChanged(node) {
+    commitHookNodesChanged.add(node);
+}
+export function runCommittedHooks(isCommitted) {
+    if (commitHookNodesChanged.size === 0)
+        return;
+    const changed = [...commitHookNodesChanged];
+    commitHookNodesChanged.clear();
+    for (const node of changed) {
+        // Still in the set, i.e. still mounted with its behavior attached: `detachOne` removes a node
+        // from `committedEachTime`, and a write that armed it before it was torn down must not reach a
+        // hook whose `detach` has already run.
+        if (!committedEachTime.has(node))
             continue;
+        if (!everCommitted.has(node)) {
+            // ARMED BUT NOT YET COMMITTED — put it back. A node is armed when its behavior attaches,
+            // which is at `createElement`, before it is in anyone's tree; dropping it here would mean the
+            // commit that finally lands it never gives it a beat. This is the one place the narrowed
+            // population can lose a node, and it is why the set is cleared by REMOVAL of what ran rather
+            // than wholesale.
+            if (!isCommitted(node)) {
+                commitHookNodesChanged.add(node);
+                continue;
+            }
+            everCommitted.add(node);
+        }
         attached.get(node)?.afterCommit?.(node);
     }
 }
+// Nodes of `committedEachTime` that have reached Fabric at least once.
+//
+// ASKED ONCE PER NODE, not once per node per commit. `isCommitted` is `getNativeTag`, which is
+// `committedRecordOf` — a `flushOps()` and a CROSSING TO THE HOST. Before this, the loop above ran
+// over every mounted node whose behavior declared `afterCommit`, on every commit of ANY surface, so
+// a thousand-row list with a `<text-input>` per row paid a thousand crossings to select one row,
+// and paid them again on a commit that changed nothing at all. Measured at 550 for a 550-node set
+// (`__tests__/post-commit-hooks-are-not-the-tree.test.ts`).
+//
+// The cached answer is sound because within `committedEachTime` it is monotone: a node enters when
+// its behavior attaches, leaves in `detachOne` when it is torn down, and a live node that has been
+// committed keeps a Fabric record — a clone keeps the family. So the bit only ever goes TRUE for a
+// node still in the set, which is F-18's `mayHaveChildren` shape: a stale FALSE costs one more
+// crossing next commit, and a stale TRUE is impossible because leaving the set is what losing the
+// record means.
+//
+// A WeakSet rather than a node field: nothing outside this module has any business reading it, and
+// a node that leaves the tree takes its entry with it.
+const everCommitted = new WeakSet();
 // `removeChild` is NOT the destroy signal, and reading it as one is the bug this indirection
 // exists to avoid. Engine-side it looks like one — a reorder goes through `detach` inside
 // appendChild/insertBefore and never lands in removeChild — but a FRAMEWORK can spell a move as
@@ -182,26 +399,81 @@ export function markDetachCandidate(node) {
 //
 // The subtree walk lives here rather than at removal, and is cheaper for it: only the nodes that
 // actually left are walked.
-export function sweepDetachedBehaviors(topLevel) {
+//
+// `onDetached` runs for EVERY node of a genuinely-removed subtree, whether or not it carries a
+// behavior — it is how the engine's other per-node lifetime state (an Animated subscription, see
+// `animated/host-binding.ts`) gets the same "did it really leave" answer this sweep exists to
+// compute. Passed in for the no-cycle reason `runDeferredAttaches`' predicate is: this module must
+// keep pointing one way, and Metro's `inlineRequires` makes that a live hazard rather than taste.
+/**
+ * Whether the sweep has anything to do — asked BEFORE its arguments are built.
+ *
+ * The sweep's own first line already returns on an empty candidate set, and that was not enough:
+ * its caller passes `surface.children`, which is a GETTER that crosses to the host, allocates the
+ * whole top-level list and filters it into a second array. On a surface holding four thousand rows
+ * that ran on every commit, including the ones with nothing to sweep, because an argument is
+ * evaluated before the guard inside the callee can decline. Same shape as the `dlog` arguments that
+ * cost Angular 5-10% while emitting nothing.
+ */
+export function hasDetachCandidates() {
+    return detachCandidates.size > 0;
+}
+export function sweepDetachedBehaviors(topLevel, onDetached) {
     if (detachCandidates.size === 0)
         return;
+    // TWO crossings for the whole sweep, whatever it is sweeping — one for the parents, one for the
+    // subtrees. Asked per node instead, a Clear of a thousand rows spent eleven thousand
+    // (`ITreeHost.parentsOf` carries the measurement).
+    const candidates = [...detachCandidates];
+    const parents = parentsOf(candidates);
     // A surface's top-level nodes carry `parent === undefined` by design (surface.ts), and
     // `commitChildren` re-lists them without going through appendChild — so for those the parent
     // check alone would report a live node as gone.
-    const seen = new Set();
-    for (const node of detachCandidates) {
-        if (node.parent !== undefined || topLevel.includes(node))
-            continue;
-        detachSubtree(node, seen);
-    }
+    const left = candidates.filter((node, at) => parents[at] === undefined && !topLevel.includes(node));
+    for (const node of subtreesOf(left))
+        detachOne(node, onDetached);
     detachCandidates.clear();
 }
-// `seen` guards the one overlap the candidate set can contain: a removed parent and a removed
-// descendant of it are both nominated, and without it the descendant is detached twice.
-function detachSubtree(node, seen) {
-    if (seen.has(node))
+// Tear a subtree down unconditionally — the SURFACE teardown path, where there is nothing to
+// decide: `disposeRoot` drops the root container, so every node under it has left for good whatever
+// any framework intended.
+//
+// It exists because the sweep above cannot answer this. The sweep only sees nodes a `removeChild`
+// NOMINATED, and an unmount removes nothing — the adapter drops the whole surface. So before this,
+// `disposeRoot` touched no node at all: `committedOf` reads `node.committed`, a field on the node,
+// so every node of a dead surface still answered `isCommitted` and stayed in `committedEachTime`,
+// drained on every later commit anywhere in the process, with its timers still armed.
+export function teardownSubtree(node, onDetached) {
+    for (const each of subtreesOf([node]))
+        detachOne(each, onDetached);
+}
+// `tornDown` guards BOTH overlaps, and it used to be helped by a per-call `seen` Set that guarded
+// only the first of them:
+//
+//   within one call    a removed parent and a removed descendant are both nominated, so the
+//                      descendant arrives twice
+//   across calls       a node the sweep released and that `disposeRoot` then walks again, the
+//                      ordinary shape of an unmount after the framework emptied the tree
+//
+// `seen` was redundant for the first: `tornDown.add(node)` runs unconditionally two lines below the
+// guard, in the same call, so a second arrival takes the same early return. The only behaviour it
+// changed was after a THROWING `onDetached`, where the node would be retried — and a sweep that
+// threw half way has already left the tree in a state no retry repairs.
+//
+// It cost a Set allocation and two hash operations per node, against a teardown that visits every
+// removed node: 10 000 of them on a 1 000-row clear. Removing it is a simplification and NOT a
+// speed-up — measured on `build-release`, the sweep stayed at 4.4-4.6 ms either way
+// (`teardown-sweep-cost.itest.ts`). Whatever holds that time is not the bookkeeping per node.
+//
+// The subtree arrives FLAT, in one host read, instead of a `childrenOf` recursion. The recursion
+// stopped descending at an already-torn-down node where this skips it and carries on; the two agree
+// because both marks are whole-subtree — the sweep adds every descendant and `reattachSubtree`
+// removes every descendant — so a node in `tornDown` has its own descendants in it, and each of them
+// takes the same early return below.
+function detachOne(node, onDetached) {
+    if (tornDown.has(node))
         return;
-    seen.add(node);
+    onDetached(node);
     // Marked whether or not THIS node carries a behavior: the mark is what tells a later insert to
     // walk, and the node re-inserted is usually a plain container whose DESCENDANT holds the
     // machine. Gating the mark on `behaviors.has` made the row wrapper unmarked and the whole walk
@@ -217,14 +489,9 @@ function detachSubtree(node, seen) {
     // The recurring hook stops with the node, and unlike the deferral above this one has a visible
     // consequence if forgotten: a torn-down node would keep being asked to reconcile props against a
     // subtree that has left the tree, on every commit, forever.
-    // The recurring hook stops with the node, and unlike the deferral above this one has a visible
-    // consequence if forgotten: a torn-down node would keep being asked to reconcile props against a
-    // subtree that has left the tree, on every commit, forever.
     committedEachTime.delete(node);
     // The map, not the registry: by here only the Fabric name is left on the node.
     attached.get(node)?.detach(node);
-    for (const child of node.children)
-        detachSubtree(child, seen);
 }
 // Re-arms a node the sweep tore down but that the framework put back. Called from appendChild and
 // insertBefore, and it is a WeakSet miss — no walk at all — for every node in a freshly built
@@ -234,7 +501,13 @@ export function reattachHostBehaviors(node) {
         return;
     reattachSubtree(node);
 }
-function reattachSubtree(node) {
+// Flat for the same reason the detach walk is, and with nothing to reconcile: this one always
+// descended into every child, whatever the node's own mark said.
+function reattachSubtree(root) {
+    for (const node of subtreesOf([root]))
+        reattachOne(node);
+}
+function reattachOne(node) {
     if (tornDown.has(node)) {
         tornDown.delete(node);
         const behavior = attached.get(node);
@@ -245,11 +518,15 @@ function reattachSubtree(node) {
         // half-initialised, which is the failure this seam exists to prevent.
         if (behavior?.attachAfterCommit !== undefined)
             awaitingCommit.add(node);
-        if (behavior?.afterCommit !== undefined)
+        if (behavior?.afterCommit !== undefined) {
             committedEachTime.add(node);
+            node.hasCommitHook = true;
+            // A node coming back out of the park has not necessarily had a prop written since, and its
+            // mirror may have moved while it was away. Arm it once so the next commit gives it a beat —
+            // the narrowed population must not turn a RETURNING node into a silently skipped one.
+            noteCommitHookNodeChanged(node);
+        }
     }
-    for (const child of node.children)
-        reattachSubtree(child);
 }
 // Test-only. A registry is module state, so a suite that registers a behavior leaks it into every
 // later test in the same file unless it is cleared.
@@ -259,4 +536,5 @@ export function clearHostBehaviors() {
     awaitingCommit.clear();
     committedEachTime.clear();
     hasBehaviors = false;
+    hasAttached = false;
 }

package/build/image-source-write.d.ts

@@ -0,0 +1,16 @@
+export declare const IMAGE_SOURCE_PROPS: ReadonlySet<string>;
+/**
+ * Resolve a source prop and normalise it to the ARRAY shape native expects.
+ *
+ * Always an array, including for the single-object and asset-id cases: a bare object reaching
+ * Fabric paints nothing and reports nothing, which is worse than an image that is simply absent.
+ * The rule downstream then has one shape to reason about instead of three.
+ *
+ * A value this cannot make sense of comes back UNTOUCHED rather than wrapped. `routeProp` writes
+ * whatever it is handed, and a tag with no image behavior must keep its props verbatim — the
+ * control case in `image-payload.itest.ts` is what holds that line.
+ */
+export declare function resolveImageSourceProp(value: unknown): unknown;
+export declare const IMAGE_LOAD_EVENT_NAMES: ReadonlySet<string>;
+/** Whether at least one of the four still has a listener installed on the node. */
+export declare function anyImageLoadEventListenerWired(listeners: ReadonlyMap<string, unknown> | undefined): boolean;

package/build/image-source-write.js

@@ -0,0 +1,65 @@
+// Image sources, resolved on the way IN rather than on the way out.
+//
+// WHY IT IS HERE AND NOT IN THE PAYLOAD BUILDER, which is where every other part of Image's rule
+// now lives. `resolveImageSource` asks METRO'S ASSET REGISTRY — the table `require('./logo.png')`
+// indexes into, populated at bundle time, in JavaScript. There is no such table in C++ and there
+// should not be: it is the bundler's, not the platform's.
+//
+// This is the same seam and the same argument as `structured-style.ts`, which resolves
+// `boxShadow`/`filter`/`transform` at write time for the identical reason — a value resolved at
+// PAYLOAD-BUILD time is resolved HEADLESS ONLY, because the C++ builder has no JS to call, and the
+// device then commits the raw input and Fabric drops it in silence. Moving the lookup one step
+// earlier costs nothing and leaves the rest of the rule pure, which is what let it move at all.
+//
+// The three names are Image's: `source` is the real one, `defaultSource` the placeholder, and
+// `loadingIndicatorSource` Android's spinner.
+import { resolveImageSource } from './image-source-resolver.js';
+export const IMAGE_SOURCE_PROPS = new Set([
+    'source',
+    'defaultSource',
+    'loadingIndicatorSource',
+]);
+/**
+ * Resolve a source prop and normalise it to the ARRAY shape native expects.
+ *
+ * Always an array, including for the single-object and asset-id cases: a bare object reaching
+ * Fabric paints nothing and reports nothing, which is worse than an image that is simply absent.
+ * The rule downstream then has one shape to reason about instead of three.
+ *
+ * A value this cannot make sense of comes back UNTOUCHED rather than wrapped. `routeProp` writes
+ * whatever it is handed, and a tag with no image behavior must keep its props verbatim — the
+ * control case in `image-payload.itest.ts` is what holds that line.
+ */
+export function resolveImageSourceProp(value) {
+    if (value === undefined || value === null)
+        return value;
+    if (typeof value !== 'number' && typeof value !== 'object')
+        return value;
+    const resolved = resolveImageSource(value);
+    return Array.isArray(resolved) ? resolved : [resolved];
+}
+// `ReactImageView.setShouldNotifyLoadEvents` (Android) — `downloadListener` stays `null`, and
+// none of these four ever fires, until this prop is `true`. `Image.android.js` sets it whenever
+// ANY one of them is authored; iOS's native side has no such gate and never sets it.
+//
+// These four are real Fabric events (`view-config.ts`'s `COMPONENT_EVENTS.RCTImageView`), so
+// `routeProp` diverts them through `setEventListener`/`node.listeners`, never through `writeProp`
+// — unlike an ordinary function prop, they never reach the `functionProps` stash. Named here in
+// LISTENER form (post `listenerName()`: `onLoad` -> `load`), which is what `node.listeners` keys
+// on. Same shape `GATED_EVENT_PROPS` uses for `onLayout`, applied to a name no host behavior owns.
+export const IMAGE_LOAD_EVENT_NAMES = new Set([
+    'loadStart',
+    'load',
+    'loadEnd',
+    'error',
+]);
+/** Whether at least one of the four still has a listener installed on the node. */
+export function anyImageLoadEventListenerWired(listeners) {
+    if (listeners === undefined)
+        return false;
+    for (const name of IMAGE_LOAD_EVENT_NAMES) {
+        if (listeners.has(name))
+            return true;
+    }
+    return false;
+}

package/build/imperative.d.ts

@@ -0,0 +1,49 @@
+import type { IMeasureInWindowOnSuccess, IMeasureLayoutOnSuccess, IMeasureOnSuccess, IRootTag } from './fabric';
+import { type ISymbioteNode } from './node';
+export declare function registerSurfaceCommit(commit: (rootTag: IRootTag) => void, forget: (rootTag: IRootTag) => void): void;
+export declare function flushNativeProps(): void;
+/**
+ * Publish a node whose props changed OUTSIDE any renderer mutation.
+ *
+ * Recording is not publishing. Every other write reaches Fabric because the framework's own commit
+ * follows it; a change driven by a NATIVE EVENT has no such follow-up — the press path's
+ * `setNodePressed` is the first caller that is not `setNativeProps`.
+ *
+ * Queued rather than committed on the spot: several writes in one task publish together at the
+ * microtask boundary, one commit per surface.
+ */
+export declare function requestCommitFor(node: ISymbioteNode): void;
+export declare function disposeRoot(rootTag: IRootTag): void;
+/** The committed reactTag, stable across clone-on-write — what the native Animated driver binds. */
+export declare function getNativeTag(node: ISymbioteNode): number | undefined;
+/**
+ * The node's current native handle, in kind identical to React's `stateNode.node`.
+ *
+ * OPAQUE. Under the native host it is a `ShadowNode`, under a headless one whatever that host
+ * committed — see `ICommittedRecord.handle`. It used to be typed `IFabricNode`, a brand with no
+ * members, so a caller can do exactly as much with it as before.
+ */
+export declare function getNativeNode(node: ISymbioteNode): object | undefined;
+/** Called by the commit path once a batch has published. */
+export declare function notifyCommitted(): void;
+/**
+ * Run `action` once `node` has a committed Fabric handle — immediately if it already does, else
+ * after the commit that assigns one. Returns a cancel fn (drop the retry, e.g. on unmount).
+ */
+export declare function whenCommitted(node: ISymbioteNode, action: () => void): () => void;
+export declare function dispatchViewCommand(node: ISymbioteNode, commandName: string, args: readonly unknown[]): void;
+export declare function sendAccessibilityEvent(node: ISymbioteNode, eventType: string): void;
+export declare function measure(node: ISymbioteNode, callback: IMeasureOnSuccess): void;
+export declare function measureInWindow(node: ISymbioteNode, callback: IMeasureInWindowOnSuccess): void;
+export declare function measureLayout(node: ISymbioteNode, relativeTo: ISymbioteNode, onSuccess: IMeasureLayoutOnSuccess, onFail?: () => void): void;
+/**
+ * Tell native that JS has taken the gesture, or given it up.
+ *
+ * Through the HOST like the five above it, never through the Fabric slot: under the native tree
+ * host the committed handle is our placeholder, and `nativeFabricUIManager.setIsJSResponder` unwraps
+ * only a `ShadowNode` reference it minted itself.
+ */
+export declare function setIsJSResponder(node: ISymbioteNode, isResponder: boolean, blockNativeResponder: boolean): void;
+/** The node's CURRENT prop value, as the host holds it. The behaviors' one read. */
+export declare function propOf(node: ISymbioteNode, key: string): unknown;
+export declare function setNativeProps(node: ISymbioteNode, partial: Record<string, unknown>): void;