@symbiote-native/engine 1.2.0 → 1.3.1

package/build/image-loader.d.ts

@@ -6,8 +6,10 @@ export type IImageSize = {
 export type IImageCacheStatus = 'memory' | 'disk' | 'disk/memory';
 type ISizeSuccess = (width: number, height: number) => void;
 type ISizeFailure = (error: unknown) => void;
-declare function getSize(uri: string, success?: ISizeSuccess, failure?: ISizeFailure): Promise<IImageSize>;
-declare function getSizeWithHeaders(uri: string, headers: Record<string, string>, success?: ISizeSuccess, failure?: ISizeFailure): Promise<IImageSize>;
+declare function getSize(uri: string): Promise<IImageSize>;
+declare function getSize(uri: string, success: ISizeSuccess, failure?: ISizeFailure): undefined;
+declare function getSizeWithHeaders(uri: string, headers: Record<string, string>): Promise<IImageSize>;
+declare function getSizeWithHeaders(uri: string, headers: Record<string, string>, success: ISizeSuccess, failure?: ISizeFailure): undefined;
 declare function prefetch(uri: string, callback?: (requestId: number) => void): Promise<boolean>;
 declare function abortPrefetch(requestId: number): void;
 declare function queryCache(uris: string[]): Promise<Record<string, IImageCacheStatus>>;

package/build/image-loader.js

@@ -1,27 +1,16 @@
-// Image static methods (RN's Image.getSize / prefetch / queryCache / etc).
-//
-// These mirror RN's iOS Image statics (Libraries/Image/Image.ios.js), which delegate to the
-// `ImageLoader` native (Turbo)Module declared in NativeImageLoaderIOS.js. The Android spec
-// (NativeImageLoaderAndroid.js) registers under the SAME module name ('ImageLoader'), so this
-// stays a flat, non-platform-split module - only the Android prefetch call signature differs (a
-// second `requestId` arg), branched on Platform.OS below, not on module name. NOTE the asymmetry
-// in the iOS spec: `getSize` resolves a `[width, height]` ARRAY, while `getSizeWithHeaders`
-// resolves a `{width, height}` OBJECT, both are guarded below before reading. The native result
-// crosses the I/O boundary as `unknown`; we never cast it, we narrow its shape.
-//
-// This is a stateful, native-bridge-touching imperative module (module-level ImageLoader cache +
-// prefetch requestId counter) with no view of its own - it belongs in @symbiote-native/engine
-// alongside Alert/Share, not in a view/render-*.ts file (whose contract is zero state / zero
-// native bridge).
+// Image static methods (RN's Image.getSize/prefetch/queryCache/etc). Both iOS and Android specs
+// register under the same module name ('ImageLoader'), so this stays flat, non-platform-split —
+// only the Android prefetch call signature differs (a second requestId arg), branched below.
+// The native result crosses the I/O boundary as unknown; we never cast it, we narrow its shape.
+// This is a stateful, native-bridge-touching imperative module with no view of its own — it
+// belongs here alongside Alert/Share, not in a view/render-*.ts file.
 import { dlog } from './debug.js';
 import { resolveImageSource, } from './image-source-resolver.js';
 import { getNativeModule } from './native-modules/index.js';
 import { Platform } from './platform';
 import { isNumber } from './type-guards.js';
-// The iOS native module name RN registers this under (NativeImageLoaderIOS.js resolves
-// `TurboModuleRegistry.getEnforcing<Spec>('ImageLoader')`). A module name like this is only
-// provable on a real host - a headless fake answers to any name - so this iOS name is
-// device-verify-pending.
+// The native module name RN registers this under. A module name like this is only provable on a
+// real host — a headless fake answers to any name.
 const IMAGE_LOADER_MODULE = 'ImageLoader';
 let imageLoaderModule;
 function getImageLoader() {
@@ -54,40 +43,29 @@ function requireLoader(method) {
     }
     return loader;
 }
-// Resolve image dimensions, optionally via success/failure callbacks. Always returns the Promise
-// too (RN returns void when a callback is passed, but a promise-and-callback shape is friendlier
-// and a strict superset).
+// Image.ios.js / Image.android.js: the promise when no success callback is given; otherwise the
+// result goes to the callbacks and nothing is returned, a missing `failure` becoming a warning.
+function deliverSize(promise, uri, success, failure) {
+    if (typeof success !== 'function')
+        return promise;
+    promise
+        .then(size => success(size.width, size.height))
+        .catch(typeof failure === 'function'
+        ? failure
+        : () => console.warn('Failed to get size for image: ' + uri));
+    return undefined;
+}
 function getSize(uri, success, failure) {
     const promise = Promise.resolve()
         .then(() => requireLoader('getSize').getSize(uri))
         .then(toImageSize);
-    if (typeof success === 'function') {
-        promise
-            .then(size => success(size.width, size.height))
-            .catch((error) => {
-            if (typeof failure === 'function')
-                failure(error);
-            else
-                dlog(`Image.getSize failed for ${uri}: ${String(error)}`);
-        });
-    }
-    return promise;
+    return deliverSize(promise, uri, success, failure);
 }
 function getSizeWithHeaders(uri, headers, success, failure) {
     const promise = Promise.resolve()
         .then(() => requireLoader('getSizeWithHeaders').getSizeWithHeaders(uri, headers))
         .then(toImageSize);
-    if (typeof success === 'function') {
-        promise
-            .then(size => success(size.width, size.height))
-            .catch((error) => {
-            if (typeof failure === 'function')
-                failure(error);
-            else
-                dlog(`Image.getSizeWithHeaders failed for ${uri}: ${String(error)}`);
-        });
-    }
-    return promise;
+    return deliverSize(promise, uri, success, failure);
 }
 // Android keys an in-flight prefetch by a monotonic requestId (so abortRequest can cancel it);
 // RN's Image.android.js generates the same way. iOS ignores the arg.
@@ -159,10 +137,8 @@ async function queryCache(uris) {
         throw error;
     });
 }
-// PURE JS: run the currently-installed source resolver (the same machinery the Image component
-// uses via resolveImageSource). RN's resolveAssetSource turns a require() asset id into
-// {uri, scale, ...}; the app injects the real one with setImageSourceResolver, and this exposes
-// its output to callers directly.
+// Pure JS: run the currently-installed source resolver (the same machinery the Image component
+// uses via resolveImageSource). The app injects the real one with setImageSourceResolver.
 function resolveAssetSource(source) {
     return resolveImageSource(source);
 }

package/build/image-source-resolver.js

@@ -1,10 +1,6 @@
-// Image source resolution seam: require('./x.png') asset ids and {uri} sources are resolved by
-// RN's own resolveAssetSource before reaching the shared render fn. The actual resolution is
-// RN-platform-specific, so it is injected here rather than imported, mirroring platform-color.ts's
-// processColor seam - this keeps @symbiote-native/components free of a react-native dependency (and
-// the headless harness working). BOTH the pure renderImage view (@symbiote-native/components) and
-// this package's own image-loader statics (resolveAssetSource) call resolveImageSource; neither
-// reaches into the mutable resolver directly.
+// require('./x.png') asset ids and {uri} sources resolve via RN's own resolveAssetSource, which is
+// platform-specific and injected here rather than imported (mirrors platform-color.ts's
+// processColor seam) so @symbiote-native/components stays free of a react-native dependency.
 let sourceResolver = source => source;
 export function setImageSourceResolver(resolve) {
     sourceResolver = resolve;

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

@@ -1,16 +1,5 @@
 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 function resolveImageSourceProp(value: unknown, dropsSingleSourceHeaders?: boolean): 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

@@ -1,17 +1,7 @@
-// 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
+// Image sources, resolved on the way IN rather than in the C++ payload builder like the rest of
+// Image's rule: resolveImageSource asks Metro's asset registry, a JS-only, bundle-time table with
+// no C++ side. Same seam as structured-style.ts's write-time boxShadow/filter/transform fold.
+// The three names are Image's: `source` the real one, `defaultSource` the placeholder,
 // `loadingIndicatorSource` Android's spinner.
 import { resolveImageSource } from './image-source-resolver.js';
 export const IMAGE_SOURCE_PROPS = new Set([
@@ -19,34 +9,36 @@ export const IMAGE_SOURCE_PROPS = new Set([
     '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) {
+// Resolve a source prop and normalize it to the array shape native expects — always an array,
+// even for the single-object and asset-id cases, since a bare object reaching Fabric paints and
+// reports nothing at all.
+// A value this can't make sense of comes back untouched rather than wrapped: a tag with no image
+// behavior must keep its props verbatim (pinned by image-payload.itest.ts).
+export function resolveImageSourceProp(value, dropsSingleSourceHeaders = false) {
     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];
+    if (Array.isArray(resolved))
+        return resolved;
+    // Android `source` only: `Image.android.js` lifts headers to the native `headers` prop just for an
+    // ARRAY source, and ReactImageView ignores per-source headers, so RN sends none for a single
+    // object. Wrapping here erases that shape, so its headers go here too.
+    if (dropsSingleSourceHeaders &&
+        typeof resolved === 'object' &&
+        resolved !== null &&
+        'headers' in resolved) {
+        const { headers: _dropped, ...rest } = resolved;
+        return [rest];
+    }
+    return [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.
+// Android's ReactImageView.setShouldNotifyLoadEvents gates on this prop: none of these four ever
+// fire until Image.android.js sets it, because any one of them is authored; iOS has no such gate.
+// Real Fabric events (view-config.ts's COMPONENT_EVENTS.RCTImageView), so routeProp diverts them
+// through setEventListener/node.listeners, never writeProp — named in listener form (onLoad ->
+// load), what node.listeners keys on.
 export const IMAGE_LOAD_EVENT_NAMES = new Set([
     'loadStart',
     'load',

package/build/imperative.d.ts

@@ -2,47 +2,19 @@ import type { IMeasureInWindowOnSuccess, IMeasureLayoutOnSuccess, IMeasureOnSucc
 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;

package/build/imperative.js

@@ -1,29 +1,18 @@
-// The imperative half of what `commit.ts` used to export — everything an app or an adapter reaches
-// for OUTSIDE a render: measure, view commands, accessibility events, the Animated fast path.
-//
-// It survived the tree's removal unchanged in SHAPE, because every one of these was already written
-// against three fields — a Fabric handle, a tag, a root tag — and never against the walk. What
-// changed is where those come from: `committedOf(node)` read an `IMirror` on the node, and the tree
-// HOST answers now (`tree-host.ts`) — native on device, the TypeScript applier headlessly.
-//
-// `undefined` is the ORDINARY state here, not an error. An adapter that wires an imperative call at
-// lifecycle time runs before `completeRoot` under an async-batched commit (Vue and Svelte schedule
-// it on a microtask), so the node has no handle yet. Every function either defers (`whenCommitted`)
-// or logs and returns — never throws.
+// Everything an app or adapter reaches for outside a render: measure, view commands, accessibility
+// events, the Animated fast path. Each is written against a Fabric handle/tag/root tag answered by
+// the tree host (tree-host.ts): native on device, a TypeScript applier headlessly.
+// undefined is the ordinary state here, not an error. An adapter wiring an imperative call at
+// lifecycle time can run before completeRoot under an async-batched commit, so the node has no
+// handle yet. Every function either defers (whenCommitted) or logs and returns — never throws.
 import { dlog, isDebug } from './debug.js';
 import { clearPublishedStyle, writeProp } from './node.js';
 import { flattenStyle } from './style/index.js';
 import { flushOps, treeHost } from './tree-host.js';
-/**
- * What Fabric currently holds for `node`, or `undefined` before its first commit.
- *
- * Flushes first: an imperative call can land between a mutation and its commit, and the host cannot
- * answer about ops it has not been handed.
- *
- * `undefined` is the ORDINARY state, not an error — and it is also what a WRAPPED node gets. The host
- * keys on the handle OBJECT, so a Vue `reactive()` / deep-`ref()` Proxy around a host element misses
- * and every function below degrades to its log. Hold host nodes with `shallowRef`.
- */
+// What Fabric currently holds for `node`, or undefined before its first commit. Flushes first: an
+// imperative call can land between a mutation and its commit, and the host can't answer about ops
+// it hasn't been handed.
+// undefined is also what a wrapped node gets: the host keys on the handle object, so a Vue
+// reactive()/deep-ref() Proxy around a host element misses. Hold host nodes with shallowRef.
 function committedRecordOf(node) {
     flushOps();
     return treeHost()?.committedRecordOf(node);
@@ -48,16 +37,11 @@ export function flushNativeProps() {
     for (const rootTag of roots)
         commitSurface?.(rootTag);
 }
-/**
- * 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.
- */
+// 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, but a change
+// driven by a native event has no such follow-up (setNodePressed is the first such caller).
+// Queued rather than committed on the spot: several writes in one task publish together at the
+// microtask boundary, one commit per surface.
 export function requestCommitFor(node) {
     const record = committedRecordOf(node);
     if (record === undefined) {
@@ -66,14 +50,9 @@ export function requestCommitFor(node) {
     }
     requestCommitForRoot(record.rootTag);
 }
-/**
- * The same request, for a caller that already holds the node's record.
- *
- * `committedRecordOf` crosses the host boundary, and `setNativeProps` fetches the record two lines
- * before it calls this — so asking again was two crossings for one fact, on the path an
- * `AnimatedProps` leaf runs once per frame per animated node. Measured at 2 of the 3 crossings a
- * frame made (`__tests__/animated-frame-cost.test.ts`).
- */
+// The same request, for a caller that already holds the node's record. committedRecordOf crosses
+// the host boundary, and setNativeProps fetches the record two lines before it calls this — asking
+// again would be a second crossing for one fact, on a path an AnimatedProps leaf runs per frame.
 function requestCommitForRoot(rootTag) {
     pendingRoots.add(rootTag);
     if (!flushScheduled) {
@@ -92,20 +71,15 @@ export function disposeRoot(rootTag) {
 export function getNativeTag(node) {
     return committedRecordOf(node)?.tag;
 }
-/**
- * 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.
- */
+// The node's current native handle, in kind identical to React's stateNode.node. Opaque: under the
+// native host it's a ShadowNode, under a headless one whatever that host committed (see
+// ICommittedRecord.handle).
 export function getNativeNode(node) {
     return committedRecordOf(node)?.handle;
 }
-// Actions waiting for their node's first commit. An adapter that wires an imperative call at
-// lifecycle time can run BEFORE completeRoot under an async-batched commit, so the node has no
-// handle yet and the call would silently no-op. Each waiter retries after a commit and is dropped
-// once it runs. React commits synchronously, so its actions run inline and never land here.
+// Actions waiting for their node's first commit — an adapter wiring a call at lifecycle time can
+// run before completeRoot under an async-batched commit, so the node has no handle yet. Each
+// waiter retries after a commit and is dropped once it runs; React runs its actions inline.
 const pendingCommitWaiters = new Set();
 /** Called by the commit path once a batch has published. */
 export function notifyCommitted() {
@@ -114,10 +88,8 @@ export function notifyCommitted() {
             pendingCommitWaiters.delete(waiter);
     }
 }
-/**
- * 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).
- */
+// 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 to drop the retry (e.g. on unmount).
 export function whenCommitted(node, action) {
     const attempt = () => {
         if (committedRecordOf(node) === undefined)
@@ -175,13 +147,9 @@ export function measureLayout(node, relativeTo, onSuccess, onFail = () => { }) {
     }
     treeHost()?.measureLayout(node, relativeTo, onFail, onSuccess);
 }
-/**
- * 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.
- */
+// 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's own version unwraps only a ShadowNode it minted itself.
 export function setIsJSResponder(node, isResponder, blockNativeResponder) {
     if (committedRecordOf(node) === undefined) {
         dlog('setIsJSResponder skipped: node not committed');
@@ -194,22 +162,12 @@ export function propOf(node, key) {
     flushOps();
     return treeHost()?.propOf(node, key);
 }
-// Per-frame prop write for the JS-driven Animated path, and the one write that bypasses the
-// declarative style. RN flushes an animation frame with an in-place `instance.setNativeProps(...)`;
-// Fabric is persistent, so a frame is one scoped commit instead.
-//
-// IT NO LONGER BYPASSES ANYTHING, and the correction it used to owe the host is gone with the
-// bypass. This wrote to Fabric directly once, so the host had to be told what had been sent behind
-// its back or its next diff would be computed against a stale base. The write is an ordinary op now
-// — the commit that carries it updates that record itself. Telling the host EARLY was strictly
-// worse than not telling it: `noteNativePropsBypass` folded the values into `committedProps` before
-// the commit ran, so the diff found nothing to send and the write never reached Fabric at all.
-//
-// One correction survives, because it is about the ENGINE's own state rather than the host's:
-// `parts.published` is cleared, so `pushClassStyle`'s guard cannot turn away the re-push that
-// RESTORES the declarative style this frame just overwrote. The guard is exact, and an app handing
-// over a hoisted style constant (StyleSheet.create, a module-level object) would otherwise never
-// get it back.
+// Per-frame prop write for the JS-driven Animated path — RN flushes an animation frame with an
+// in-place instance.setNativeProps(...); Fabric is persistent, so a frame is one scoped commit
+// instead, an ordinary op the commit that carries it accounts for on its own.
+// One correction survives, about the engine's own state: parts.published is cleared, so
+// pushClassStyle's guard can't turn away the re-push that restores the declarative style this
+// frame just overwrote — otherwise a hoisted style constant would never come back.
 export function setNativeProps(node, partial) {
     const record = committedRecordOf(node);
     if (record === undefined) {
@@ -229,30 +187,22 @@ export function setNativeProps(node, partial) {
         }
         else {
             merged[key] = value;
-            // This path used to owe the aria gate that `setProp` carried, since it bypasses it. There is
-            // no gate to owe any more: the fold is the device's rule and it recomputes presence from the
-            // bag. See `node.ts`'s note at the old choke point.
         }
     }
     for (const [key, value] of Object.entries(merged)) {
-        // `writeProp`, not `recordSetProp`: this is the path with no `routeProp` in front of it, so a
-        // function reaches the wire from here and nowhere else. `AnimatedProps.__getValue()` copies
-        // every key its leaf holds, `panHandlers` included.
+        // writeProp, not recordSetProp: this is the path with no routeProp in front of it, so a
+        // function reaches the wire from here and nowhere else (AnimatedProps.__getValue() copies
+        // every key its leaf holds, panHandlers included).
         writeProp(node, key, value);
     }
     if (merged.style !== undefined)
         clearPublishedStyle(node);
-    // GATED, and this is the one place in the engine where "per frame" is the right unit to worry
-    // about. An `AnimatedProps` leaf calls this once per frame per animated node, so the template
-    // string and the `Object.keys` array it builds are 60 allocations a second per node — times the
-    // list, for a list that animates its rows. F-61 dismissed 347 ungated arguments because none of
-    // them was on a path that repeats; this one is, and F-61 had it in its own in-loop list and
-    // priced it as "runs once".
+    // Gated: an AnimatedProps leaf calls this once per frame per animated node, so the template
+    // string and Object.keys array below would otherwise allocate 60 times a second per node.
     if (isDebug()) {
         dlog(`setNativeProps root=${record.rootTag} tag=${record.tag} keys=${Object.keys(partial)}`);
     }
     // Queued, not committed: every write made in this task publishes together at the microtask
-    // boundary. With the record already in hand — asking for it again is a second crossing for a
-    // fact this function fetched four lines up.
+    // boundary. The record is already in hand, so this avoids a second crossing for the same fact.
     requestCommitForRoot(record.rootTag);
 }

package/build/index.d.ts

@@ -65,6 +65,7 @@ export { imageStatics } from './image-loader';
 export type { IImageStatics, IImageSize, IImageCacheStatus, } from './image-loader';
 export { setImageSourceResolver, resolveImageSource, } from './image-source-resolver';
 export type { IImageSource, IImageSourceProp } from './image-source-resolver';
+export { setAssetSourceResolver, resolveAssetSource, } from './asset-source-resolver';
 export { ActionSheetIOS } from './action-sheet-ios';
 export type { IActionSheetIOSOptions, IShareActionSheetIOSOptions, IShareActionSheetError, } from './action-sheet-ios';
 export { Linking } from './linking';
@@ -90,8 +91,8 @@ export type { IKeyboardEventName, IKeyboardEvent, IKeyboardMetrics, } from './ke
 export { currentlyFocusedInput, setInputFocused, setInputBlurred, blurTextInput, focusTextInput, } from './text-input-state';
 export { LayoutAnimation } from './layout-animation';
 export type { ILayoutAnimationType, ILayoutAnimationProperty, ILayoutAnimationConfig, ILayoutAnimationAnim, ILayoutAnimationTypes, ILayoutAnimationProperties, } from './layout-animation';
-export { BackHandler } from './back-handler';
-export type { IBackPressEventName, IBackPressHandler } from './back-handler';
+export { BackHandler, installBackHandler } from './back-handler';
+export type { IBackPressEventName, IBackPressHandler, IHardwareBackPressEvent, } from './back-handler';
 export { PermissionsAndroid, PERMISSIONS, RESULTS, } from './permissions-android';
 export type { IPermission, IPermissionStatus, IRationale, } from './permissions-android';
 export { AccessibilityInfo } from './accessibility-info';