@symbiote-native/engine 0.5.0 → 1.1.0

package/build/host-behavior.js

@@ -26,16 +26,25 @@
 //
 // `registerHostBehavior` emits a `dlog` precisely so `DEBUG=1` answers "did my registration run at
 // all" before anyone starts debugging the behavior itself.
+import { parentsOf, teardownSubtreesOf } 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
 // `sweepDetachedBehaviors` for why the answer is not known until commit.
 const detachCandidates = new Set();
-// Nodes the sweep has torn down. A torn-down node can still be re-inserted — see
-// `reattachHostBehaviors` — and this is what tells an insert whether it must walk at all, so the
+// A node the sweep has torn down carries `node.isTornDown`. It can still be re-inserted — see
+// `reattachHostBehaviors` — and the bit is what tells an insert whether it must walk at all, so the
 // common case (building a fresh tree) never walks anything.
-const tornDown = new WeakSet();
-// The behavior a node actually got, remembered from its one and only registry lookup.
+//
+// A FIELD rather than the `WeakSet` it was, for the reason `slotBatch` is one: both of its readers
+// are per-node paths at list scale — the sweep touches every node of a removed subtree, and every
+// insert asks the question once.
+// The behavior a node actually got lives on the NODE, as `node.hostBehavior`, remembered from its
+// one and only registry lookup. A field rather than the `WeakMap` it was, for the reason
+// `node.payloadFold` — written on the next line of `attachHostBehavior` — already is one: every
+// reader here is a per-node path at list scale, and a `WeakMap` probe is the dearest way to ask a
+// question whose answer is almost always "none".
 //
 // 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
@@ -48,11 +57,13 @@ const tornDown = new WeakSet();
 // subject with `createElement(PRESSABLE_TAG)`, which passes the tag AS the Fabric name and makes
 // the key match by accident. No adapter constructs a node that way, so the registration could
 // never have fired in an app while all six break-tests kept failing correctly on their own axes.
-const attached = new WeakMap();
 // The gate. `createElement` and `removeChild` are the two hottest paths in the engine (9 002 and
 // ~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,13 +81,36 @@ 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:
+ * `node.hostBehavior` 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 `isTornDown`, 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);
+    const behavior = node.hostBehavior;
     if (behavior === undefined)
         return undefined;
     const named = behavior.slotProps?.[key];
@@ -91,7 +125,7 @@ export function slotPropNameFor(node, key) {
 // `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;
+    return node.hostBehavior?.slotTakesNoChildren !== true;
 }
 // Nodes a behavior built that are NOT the slot, and whose payloads derive from the owner's props.
 //
@@ -121,26 +155,32 @@ export function derivedNodesOf(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);
+    node.hostBehavior?.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);
-}
-// Called from the two structural entry points when a wrap claim lands or leaves. See
-// `onWrapChange`.
-export function notifyWrapChange(owner, wrapper) {
-    attached.get(owner)?.onWrapChange?.(owner, wrapper);
+    node.hostBehavior?.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];
+    return node.hostBehavior?.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) {
-    return attached.get(node)?.slotDerived?.includes(key) === true;
+    const names = node.hostBehavior?.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
@@ -149,7 +189,7 @@ const stashed = new WeakMap();
 // Takes the NODE, not a component string: the caller (`setEventListener`) has only the Fabric name
 // by then, which is not the registry's alphabet. Reads the same map `attachHostBehavior` wrote.
 export function ownsListener(node, name) {
-    return attached.get(node)?.ownedListeners?.includes(name) === true;
+    return node.hostBehavior?.ownedListeners?.includes(name) === true;
 }
 export function stashAppListener(node, name, listener) {
     let bag = stashed.get(node);
@@ -175,7 +215,19 @@ export function attachHostBehavior(node, tag) {
     const behavior = behaviors.get(tag);
     if (behavior === undefined)
         return;
-    attached.set(node, behavior);
+    node.hostBehavior = 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;
@@ -188,8 +240,15 @@ export function attachHostBehavior(node, tag) {
     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.
@@ -218,7 +277,12 @@ export function runDeferredAttaches(isCommitted) {
         if (!isCommitted(node))
             continue;
         awaitingCommit.delete(node);
-        attached.get(node)?.attachAfterCommit?.(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);
+        node.hostBehavior?.attachAfterCommit?.(node);
     }
 }
 /**
@@ -237,15 +301,80 @@ export function runDeferredAttaches(isCommitted) {
  * 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 (committedEachTime.size === 0)
+    if (commitHookNodesChanged.size === 0)
         return;
-    for (const node of committedEachTime) {
-        if (!isCommitted(node))
+    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;
-        attached.get(node)?.afterCommit?.(node);
+        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);
+        }
+        node.hostBehavior?.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
@@ -282,18 +411,36 @@ export function markDetachCandidate(node) {
 // `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, onDetached);
-    }
+    const left = candidates.filter((node, at) => parents[at] === undefined && !topLevel.includes(node));
+    // NARROWED, and it is the sweep's whole cost: what crosses is a handle per node, and on the
+    // benchmark row eight of every ten are plain views the sweep would mark and do nothing else
+    // with. See `ITreeHost.teardownSubtreesOf` for which nodes come back and why an ancestor must.
+    for (const node of teardownSubtreesOf(left))
+        detachOne(node, onDetached);
     detachCandidates.clear();
 }
 // Tear a subtree down unconditionally — the SURFACE teardown path, where there is nothing to
@@ -306,22 +453,50 @@ export function sweepDetachedBehaviors(topLevel, onDetached) {
 // 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) {
-    detachSubtree(node, new Set(), onDetached);
+    // Narrowed for the same reason the sweep is, and with more to gain: this path tears down a whole
+    // SURFACE, so the subtree is the screen.
+    for (const each of teardownSubtreesOf([node]))
+        detachOne(each, onDetached);
 }
-// `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. `tornDown`
-// guards the same overlap ACROSS calls — a node the sweep already released and that `disposeRoot`
-// then walks again, which is the ordinary shape of an unmount after the framework emptied the tree.
-function detachSubtree(node, seen, onDetached) {
-    if (seen.has(node) || tornDown.has(node))
+// `isTornDown` 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: the mark is raised 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 marked node has its descendants marked too, and each of them
+// takes the same early return below.
+function detachOne(node, onDetached) {
+    if (node.isTornDown)
         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
     // skip — the first version of the parked-node test caught exactly that.
-    tornDown.add(node);
+    node.isTornDown = true;
+    // AND THE REST OF THE BODY IS THE BEHAVIOUR'S, so a node without one leaves here. Nine of every
+    // ten nodes in a removed subtree are plain views: the mark above is the whole of what they owe,
+    // and the three collection probes below were being paid for them anyway. All three are written
+    // only inside `attachHostBehavior`, so an absent behavior means an absent entry in each.
+    const behavior = node.hostBehavior;
+    if (behavior === undefined)
+        return;
     // Drop a deferral the node never got to run. NO TEST CAN SEE THIS, and it is kept anyway —
     // stated rather than left as apparent coverage. The `isCommitted` predicate in the drain already
     // stops such a node from firing, so removing this line changes no observable behaviour; what it
@@ -333,23 +508,28 @@ function detachSubtree(node, seen, onDetached) {
     // 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, onDetached);
+    behavior.detach(node);
 }
 // 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
 // tree, which is the path that runs ~9 000 times per benchmark create.
 export function reattachHostBehaviors(node) {
-    if (!tornDown.has(node))
+    if (!node.isTornDown)
         return;
     reattachSubtree(node);
 }
-function reattachSubtree(node) {
-    if (tornDown.has(node)) {
-        tornDown.delete(node);
-        const behavior = attached.get(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) {
+    // Narrowed like the teardown that marked them: `reattachOne` acts only on a node the sweep
+    // marked, and the sweep marked exactly what this walk returns.
+    for (const node of teardownSubtreesOf([root]))
+        reattachOne(node);
+}
+function reattachOne(node) {
+    if (node.isTornDown) {
+        node.isTornDown = false;
+        const behavior = node.hostBehavior;
         behavior?.attach(node);
         // Re-arm the deferred half too. A parked node usually returns with its tag intact, so this
         // fires on the next drain — but re-arming is what keeps `attach` and `attachAfterCommit` a
@@ -357,11 +537,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.
@@ -371,4 +555,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;