@symbiote-native/engine 0.1.4 → 0.1.6

package/build/fabric-props.js

@@ -0,0 +1,186 @@
+// Fabric-prop translation: turn a retained node's logical props into the flat payload
+// Fabric's C++ props expect. Split out of commit.ts (which owns the reconciler/mirror walk
+// + the imperative instance API, neither of which this half touches) so the two
+// responsibilities stop sharing one 300+ line file. Color processing itself lives in
+// ./platform-color (the stable leaf every color-touching module imports from); this file only
+// decides WHICH props are color props and wires the structured CSS-style processors.
+import { RAW_TEXT_COMPONENT } from './node.js';
+import { flattenStyle } from './style/index.js';
+import { registeredProcessor } from './registry.js';
+import { isProcessableColor, processColor } from './platform-color/index.js';
+import { processBoxShadow } from './process-box-shadow/index.js';
+import { processFilter } from './process-filter.js';
+import { processTransformOrigin } from './process-transform-origin/index.js';
+import { processTransform } from './process-transform/index.js';
+import { processAspectRatio } from './process-aspect-ratio.js';
+import { processFontVariant } from './process-font-variant.js';
+import { processBackgroundImage } from './process-background-image/index.js';
+import { isRecord, isString } from './type-guards.js';
+// Color props must reach Fabric as platform ints, not CSS strings. Fabric's C++
+// color parser silently drops strings. The actual conversion (processColor) is
+// RN-platform-specific, so it is injected in platform-color.ts rather than imported,
+// keeping shared free of a react-native dependency (and the headless harness working).
+const COLOR_PROPS = new Set([
+    'backgroundColor',
+    'color',
+    'borderColor',
+    'borderTopColor',
+    'borderRightColor',
+    'borderBottomColor',
+    'borderLeftColor',
+    // Logical (writing-direction-relative) border colors + the block axis, all wired to
+    // processColor in RN's ReactNativeStyleAttributes. borderStartColor/borderEndColor are
+    // even publicly typed ColorValue, so they silently dropped on iOS / threw on Android.
+    'borderStartColor',
+    'borderEndColor',
+    'borderBlockColor',
+    'borderBlockStartColor',
+    'borderBlockEndColor',
+    'shadowColor',
+    // Text shadow + the W3C `outline`/image `overlay` colors, also processColor in RN.
+    'textShadowColor',
+    'overlayColor',
+    'outlineColor',
+    'tintColor',
+    // TextInput color props. iOS's native input accepts a CSS string, but Android's
+    // AndroidTextInput is strict ("ColorValue: the value must be a number or Object"),
+    // so these must be processColor'd here too, same as any other color reaching Fabric.
+    'placeholderTextColor',
+    'selectionColor',
+    'cursorColor',
+    'underlineColorAndroid',
+    // Text decoration color (underline/strike): same Fabric strictness as any color.
+    'textDecorationColor',
+    'selectionHandleColor',
+    // Switch track/thumb colors. RN processColors each via the Switch ViewConfig
+    // (SwitchNativeComponent / AndroidSwitchNativeComponent validAttributes). iOS takes
+    // onTintColor (ON) / tintColor (OFF); Android takes trackColorForTrue/False +
+    // trackTintColor, and Android's ColorPropConverter is strict ("the value must be a
+    // number or Object"), so a raw CSS string crashes. thumbTintColor reaches both.
+    'onTintColor',
+    'thumbTintColor',
+    'trackColorForTrue',
+    'trackColorForFalse',
+    'trackTintColor',
+]);
+// Structured CSS-style keys RN parses in JS before native (boxShadow/filter register
+// with enableNativeCSSParsing(), which DEFAULTS TO FALSE, so native CSS parsing is off
+// and the raw string is dropped). Each runs on the hoisted top-level style key, turning
+// a CSS string or structured array into the processed array Fabric's C++ expects.
+const STYLE_PROCESSORS = new Map([
+    ['boxShadow', value => processBoxShadow(asBoxShadowInput(value))],
+    ['filter', value => processFilter(asFilterInput(value))],
+    ['transformOrigin', value => processTransformOrigin(asTransformOriginInput(value))],
+    ['transform', processTransformValue],
+    ['aspectRatio', value => processAspectRatio(asAspectRatioInput(value))],
+    ['fontVariant', value => processFontVariant(asFontVariantInput(value))],
+    ['experimental_backgroundImage', value => processBackgroundImage(asBackgroundImageInput(value))],
+]);
+// boxShadow accepts a CSS string or an array of shadow objects; anything else is
+// undefined to processBoxShadow (which returns []). Narrowing avoids an `as` cast.
+function asBoxShadowInput(value) {
+    if (typeof value === 'string')
+        return value;
+    if (Array.isArray(value))
+        return value.filter(isRecord);
+    return undefined;
+}
+// filter accepts a CSS string or an array of single-key filter objects; same narrowing.
+function asFilterInput(value) {
+    if (typeof value === 'string')
+        return value;
+    if (Array.isArray(value))
+        return value.filter(isRecord);
+    return undefined;
+}
+// experimental_backgroundImage accepts a CSS string (gradient functions) or an array of
+// structured gradient objects; same narrowing as boxShadow/filter.
+function asBackgroundImageInput(value) {
+    if (typeof value === 'string')
+        return value;
+    if (Array.isArray(value))
+        return value.filter(isRecord);
+    return undefined;
+}
+// transformOrigin accepts a CSS string or a [x, y, z] array of strings/numbers; anything
+// else is undefined to processTransformOrigin (which defaults to center/center/0).
+function asTransformOriginInput(value) {
+    if (typeof value === 'string')
+        return value;
+    if (Array.isArray(value))
+        return value.filter(isStringOrNumber);
+    return undefined;
+}
+// aspectRatio accepts a number (the common, working form) or a ratio string; otherwise
+// undefined, which processAspectRatio drops.
+function asAspectRatioInput(value) {
+    if (typeof value === 'number' || typeof value === 'string')
+        return value;
+    return undefined;
+}
+// fontVariant accepts an array of variant strings (the common, working form) or a
+// space-separated string; anything else becomes an empty string, which yields [].
+function asFontVariantInput(value) {
+    if (typeof value === 'string')
+        return value;
+    if (Array.isArray(value))
+        return value.filter(isString);
+    return '';
+}
+// transform accepts a CSS string (processTransform parses it) or an array of single-key
+// transform records (the hot animated / sticky-header path, passed through unchanged).
+// A non-string non-array value is NOT dropped: it may already be processed, so it passes
+// through verbatim rather than being coerced to [] (which would erase a valid transform).
+function processTransformValue(value) {
+    if (typeof value === 'string')
+        return processTransform(value);
+    if (Array.isArray(value))
+        return processTransform(value.filter(isRecord));
+    return value;
+}
+function isStringOrNumber(value) {
+    return typeof value === 'string' || typeof value === 'number';
+}
+// Convert a prop to the shape Fabric's C++ expects. A third-party view contributes
+// its own processors, auto-derived from its ViewConfig (validAttributes[*].process,
+// e.g. processColor for a slider's track tints); those run first. Then the structured
+// CSS-style processors (boxShadow/filter). Built-ins are never in the registry, so they
+// fall through to the global color path, where any CSS-string color is run through the
+// injected platform processor (Fabric's C++ color parser silently drops strings).
+function processValue(component, key, value) {
+    const processor = registeredProcessor(component, key);
+    if (processor !== undefined)
+        return processor(value);
+    const styleProcessor = STYLE_PROCESSORS.get(key);
+    if (styleProcessor !== undefined)
+        return styleProcessor(value);
+    if (COLOR_PROPS.has(key) && isProcessableColor(value))
+        return processColor(value);
+    return value;
+}
+// Translate the retained node's logical props into the flat payload Fabric's C++
+// props expect: `style` keys are hoisted to the top level, event handlers and
+// undefined values are dropped.
+export function fabricProps(node) {
+    if (node.component === RAW_TEXT_COMPONENT) {
+        return { text: node.props.text };
+    }
+    const out = {};
+    for (const [key, value] of Object.entries(node.props)) {
+        if (key === 'style')
+            continue;
+        if (typeof value === 'function')
+            continue;
+        if (value === undefined)
+            continue;
+        out[key] = processValue(node.component, key, value);
+    }
+    // Collapse style (object | array | nested arrays) into one flat payload before
+    // hoisting: `style={[base, override]}` is RN's idiom and Fabric wants it flat.
+    const style = flattenStyle(node.props.style);
+    for (const [key, value] of Object.entries(style)) {
+        if (value !== undefined)
+            out[key] = processValue(node.component, key, value);
+    }
+    return out;
+}

package/build/i18n-manager/index.js

@@ -14,9 +14,10 @@
 //   swapLeftAndRightInRTL(flipStyles: boolean)
 import { dlog } from '../debug.js';
 import { getNativeModule } from '../native-modules.js';
+import { isBoolean } from '../type-guards.js';
 // The iOS native module name RN registers this under (the same name on both
-// platforms). A module name is only provable on a real host — a headless fake
-// answers to any name — so this name is still pending verification on device.
+// platforms). A module name is only provable on a real host (a headless fake
+// answers to any name), so this name is still pending verification on device.
 const I18N_MANAGER_MODULE = 'I18nManager';
 // RN's fallback constants when no native module is linked (headless / not yet on
 // device): not RTL, and the iOS default of swapping in RTL.
@@ -24,9 +25,6 @@ const DEFAULT_CONSTANTS = {
     isRTL: false,
     doLeftAndRightSwapInRTL: true,
 };
-function isBoolean(value) {
-    return typeof value === 'boolean';
-}
 function isOptionalString(value) {
     return value === undefined || typeof value === 'string';
 }

package/build/image-loader/index.d.ts

@@ -0,0 +1,24 @@
+import { type IImageSourceProp } from '../image-source-resolver';
+export type IImageSize = {
+    width: number;
+    height: number;
+};
+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 prefetch(uri: string, callback?: (requestId: number) => void): Promise<boolean>;
+declare function abortPrefetch(requestId: number): void;
+declare function queryCache(uris: string[]): Promise<Record<string, IImageCacheStatus>>;
+declare function resolveAssetSource(source: IImageSourceProp): unknown;
+export type IImageStatics = {
+    getSize: typeof getSize;
+    getSizeWithHeaders: typeof getSizeWithHeaders;
+    prefetch: typeof prefetch;
+    abortPrefetch: typeof abortPrefetch;
+    queryCache: typeof queryCache;
+    resolveAssetSource: typeof resolveAssetSource;
+};
+export declare const imageStatics: IImageStatics;
+export {};

package/build/image-loader/index.js

@@ -0,0 +1,175 @@
+// 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).
+import { dlog } from '../debug.js';
+import { resolveImageSource } from '../image-source-resolver.js';
+import { getNativeModule } from '../native-modules.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.
+const IMAGE_LOADER_MODULE = 'ImageLoader';
+let imageLoaderModule;
+function getImageLoader() {
+    if (imageLoaderModule === undefined) {
+        imageLoaderModule = getNativeModule(IMAGE_LOADER_MODULE);
+        dlog(`Image: ImageLoader module ${imageLoaderModule ? 'resolved' : 'NOT resolved (null)'}`);
+    }
+    return imageLoaderModule;
+}
+// Narrow native's getSize result. The spec resolves a `[width, height]` array, but tolerate a
+// `{width, height}` object too (getSizeWithHeaders uses that shape).
+function toImageSize(result) {
+    if (Array.isArray(result) && isNumber(result[0]) && isNumber(result[1])) {
+        return { width: result[0], height: result[1] };
+    }
+    if (typeof result === 'object' && result !== null) {
+        const width = Reflect.get(result, 'width');
+        const height = Reflect.get(result, 'height');
+        if (isNumber(width) && isNumber(height))
+            return { width, height };
+    }
+    throw new Error(`Image: unexpected size result from native: ${JSON.stringify(result)}`);
+}
+function requireLoader(method) {
+    const loader = getImageLoader();
+    if (loader === null) {
+        throw new Error(`Image.${method}: ImageLoader native module is not available ` +
+            '(running headless or not linked on this host).');
+    }
+    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).
+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;
+}
+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;
+}
+// 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.
+let prefetchRequestId = 0;
+// Download a remote image into the disk cache. Resolves to whether it succeeded. `callback`
+// receives the requestId (RN's Image.android.js shape) so the caller can later pass it to
+// abortPrefetch.
+async function prefetch(uri, callback) {
+    prefetchRequestId += 1;
+    const requestId = prefetchRequestId;
+    if (typeof callback === 'function')
+        callback(requestId);
+    const loader = requireLoader('prefetch');
+    return (Promise.resolve()
+        // Android's prefetchImage keys an abortable request on requestId; iOS takes ONLY the uri and
+        // throws on an extra arg (bridgeless TurboModule arg-count check). Match RN's per-platform call.
+        .then(() => Platform.OS === 'android'
+        ? loader.prefetchImage(uri, requestId)
+        : loader.prefetchImage(uri))
+        .then(result => result === true)
+        .catch((error) => {
+        dlog(`Image.prefetch failed for ${uri}: ${String(error)}`);
+        throw error;
+    }));
+}
+// Cancel an in-flight prefetch by the requestId prefetch handed back. Android only (mirrors
+// Image.android.js -> NativeImageLoaderAndroid.abortRequest); a missing abortRequest (iOS,
+// headless) is a no-op rather than a throw.
+function abortPrefetch(requestId) {
+    const loader = getImageLoader();
+    if (loader === null || typeof loader.abortRequest !== 'function') {
+        dlog(`Image.abortPrefetch(${requestId}): no abortRequest on this host, ignoring`);
+        return;
+    }
+    loader.abortRequest(requestId);
+}
+// Narrow native's queryCache result: an object mapping each known uri to its cache status.
+// Unknown statuses are dropped rather than trusted blindly.
+const CACHE_STATUS = {
+    memory: 'memory',
+    disk: 'disk',
+    'disk/memory': 'disk/memory',
+};
+function toCacheRecord(result) {
+    const record = {};
+    if (typeof result !== 'object' || result === null)
+        return record;
+    for (const key of Object.keys(result)) {
+        const value = Reflect.get(result, key);
+        if (typeof value === 'string' && Object.hasOwn(CACHE_STATUS, value)) {
+            record[key] = CACHE_STATUS[value];
+        }
+    }
+    return record;
+}
+async function queryCache(uris) {
+    return Promise.resolve()
+        .then(() => {
+        const loader = requireLoader('queryCache');
+        // The native queryCache never rejects (RCTImageLoader resolves getImageCacheStatus), so a
+        // rejection here is a JS/native boundary fault: log whether the method is even callable and
+        // the arg shape, to tell "not a function" (interop gap) from a marshalling reject.
+        dlog(`Image.queryCache: typeof loader.queryCache=${typeof loader.queryCache} uris=${uris.length}`);
+        return loader.queryCache(uris);
+    })
+        .then(toCacheRecord)
+        .catch((error) => {
+        dlog(`Image.queryCache failed: ${String(error)}`);
+        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.
+function resolveAssetSource(source) {
+    return resolveImageSource(source);
+}
+export const imageStatics = {
+    getSize,
+    getSizeWithHeaders,
+    prefetch,
+    abortPrefetch,
+    queryCache,
+    resolveAssetSource,
+};

package/build/image-loader.d.ts

@@ -0,0 +1,24 @@
+import { type IImageSourceProp } from './image-source-resolver';
+export type IImageSize = {
+    width: number;
+    height: number;
+};
+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 prefetch(uri: string, callback?: (requestId: number) => void): Promise<boolean>;
+declare function abortPrefetch(requestId: number): void;
+declare function queryCache(uris: string[]): Promise<Record<string, IImageCacheStatus>>;
+declare function resolveAssetSource(source: IImageSourceProp): unknown;
+export type IImageStatics = {
+    getSize: typeof getSize;
+    getSizeWithHeaders: typeof getSizeWithHeaders;
+    prefetch: typeof prefetch;
+    abortPrefetch: typeof abortPrefetch;
+    queryCache: typeof queryCache;
+    resolveAssetSource: typeof resolveAssetSource;
+};
+export declare const imageStatics: IImageStatics;
+export {};

package/build/image-loader.js

@@ -0,0 +1,175 @@
+// 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).
+import { dlog } from './debug.js';
+import { resolveImageSource } from './image-source-resolver.js';
+import { getNativeModule } from './native-modules.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.
+const IMAGE_LOADER_MODULE = 'ImageLoader';
+let imageLoaderModule;
+function getImageLoader() {
+    if (imageLoaderModule === undefined) {
+        imageLoaderModule = getNativeModule(IMAGE_LOADER_MODULE);
+        dlog(`Image: ImageLoader module ${imageLoaderModule ? 'resolved' : 'NOT resolved (null)'}`);
+    }
+    return imageLoaderModule;
+}
+// Narrow native's getSize result. The spec resolves a `[width, height]` array, but tolerate a
+// `{width, height}` object too (getSizeWithHeaders uses that shape).
+function toImageSize(result) {
+    if (Array.isArray(result) && isNumber(result[0]) && isNumber(result[1])) {
+        return { width: result[0], height: result[1] };
+    }
+    if (typeof result === 'object' && result !== null) {
+        const width = Reflect.get(result, 'width');
+        const height = Reflect.get(result, 'height');
+        if (isNumber(width) && isNumber(height))
+            return { width, height };
+    }
+    throw new Error(`Image: unexpected size result from native: ${JSON.stringify(result)}`);
+}
+function requireLoader(method) {
+    const loader = getImageLoader();
+    if (loader === null) {
+        throw new Error(`Image.${method}: ImageLoader native module is not available ` +
+            '(running headless or not linked on this host).');
+    }
+    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).
+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;
+}
+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;
+}
+// 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.
+let prefetchRequestId = 0;
+// Download a remote image into the disk cache. Resolves to whether it succeeded. `callback`
+// receives the requestId (RN's Image.android.js shape) so the caller can later pass it to
+// abortPrefetch.
+async function prefetch(uri, callback) {
+    prefetchRequestId += 1;
+    const requestId = prefetchRequestId;
+    if (typeof callback === 'function')
+        callback(requestId);
+    const loader = requireLoader('prefetch');
+    return (Promise.resolve()
+        // Android's prefetchImage keys an abortable request on requestId; iOS takes ONLY the uri and
+        // throws on an extra arg (bridgeless TurboModule arg-count check). Match RN's per-platform call.
+        .then(() => Platform.OS === 'android'
+        ? loader.prefetchImage(uri, requestId)
+        : loader.prefetchImage(uri))
+        .then(result => result === true)
+        .catch((error) => {
+        dlog(`Image.prefetch failed for ${uri}: ${String(error)}`);
+        throw error;
+    }));
+}
+// Cancel an in-flight prefetch by the requestId prefetch handed back. Android only (mirrors
+// Image.android.js -> NativeImageLoaderAndroid.abortRequest); a missing abortRequest (iOS,
+// headless) is a no-op rather than a throw.
+function abortPrefetch(requestId) {
+    const loader = getImageLoader();
+    if (loader === null || typeof loader.abortRequest !== 'function') {
+        dlog(`Image.abortPrefetch(${requestId}): no abortRequest on this host, ignoring`);
+        return;
+    }
+    loader.abortRequest(requestId);
+}
+// Narrow native's queryCache result: an object mapping each known uri to its cache status.
+// Unknown statuses are dropped rather than trusted blindly.
+const CACHE_STATUS = {
+    memory: 'memory',
+    disk: 'disk',
+    'disk/memory': 'disk/memory',
+};
+function toCacheRecord(result) {
+    const record = {};
+    if (typeof result !== 'object' || result === null)
+        return record;
+    for (const key of Object.keys(result)) {
+        const value = Reflect.get(result, key);
+        if (typeof value === 'string' && Object.hasOwn(CACHE_STATUS, value)) {
+            record[key] = CACHE_STATUS[value];
+        }
+    }
+    return record;
+}
+async function queryCache(uris) {
+    return Promise.resolve()
+        .then(() => {
+        const loader = requireLoader('queryCache');
+        // The native queryCache never rejects (RCTImageLoader resolves getImageCacheStatus), so a
+        // rejection here is a JS/native boundary fault: log whether the method is even callable and
+        // the arg shape, to tell "not a function" (interop gap) from a marshalling reject.
+        dlog(`Image.queryCache: typeof loader.queryCache=${typeof loader.queryCache} uris=${uris.length}`);
+        return loader.queryCache(uris);
+    })
+        .then(toCacheRecord)
+        .catch((error) => {
+        dlog(`Image.queryCache failed: ${String(error)}`);
+        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.
+function resolveAssetSource(source) {
+    return resolveImageSource(source);
+}
+export const imageStatics = {
+    getSize,
+    getSizeWithHeaders,
+    prefetch,
+    abortPrefetch,
+    queryCache,
+    resolveAssetSource,
+};

package/build/image-source-resolver/index.d.ts

@@ -0,0 +1,9 @@
+export declare function setImageSourceResolver(resolve: (source: unknown) => unknown): void;
+export declare function resolveImageSource(source: unknown): unknown;
+export type IImageSource = {
+    uri?: string;
+    scale?: number;
+    width?: number;
+    height?: number;
+};
+export type IImageSourceProp = IImageSource | IImageSource[] | number;

package/build/image-source-resolver/index.js

@@ -0,0 +1,16 @@
+// 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.
+let sourceResolver = source => source;
+export function setImageSourceResolver(resolve) {
+    sourceResolver = resolve;
+}
+// Public mirror of RN's Image.resolveAssetSource: run a source through the injected resolver.
+// Headless (no resolver wired) it is the identity, so smokes see the input unchanged.
+export function resolveImageSource(source) {
+    return sourceResolver(source);
+}

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

@@ -0,0 +1,9 @@
+export declare function setImageSourceResolver(resolve: (source: unknown) => unknown): void;
+export declare function resolveImageSource(source: unknown): unknown;
+export type IImageSource = {
+    uri?: string;
+    scale?: number;
+    width?: number;
+    height?: number;
+};
+export type IImageSourceProp = IImageSource | IImageSource[] | number;

package/build/image-source-resolver.js

@@ -0,0 +1,16 @@
+// 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.
+let sourceResolver = source => source;
+export function setImageSourceResolver(resolve) {
+    sourceResolver = resolve;
+}
+// Public mirror of RN's Image.resolveAssetSource: run a source through the injected resolver.
+// Headless (no resolver wired) it is the identity, so smokes see the input unchanged.
+export function resolveImageSource(source) {
+    return sourceResolver(source);
+}