@octane-xplat/gif 0.10.0 → 0.11.1

package/README.md

@@ -24,6 +24,49 @@ import { AnimatedImage } from '@octane-xplat/gif'
 and the plugin accepts the same values natively. For Lottie JSON
 animations use [`@octane-xplat/lottie`](../lottie/README.md) instead.
 
+## Prefetch
+
+`prefetch` warms the image engine's disk cache for URLs you expect to show
+soon — bytes on disk now, decode still at display time:
+
+```tsx
+import { prefetch } from '@octane-xplat/gif'
+
+await prefetch(feed.map((post) => post.imageUrl)) // false if any URL fails
+
+await prefetch(urls, {
+	headers: { Authorization: 'Bearer …' }, // Android only — see below
+	concurrency: 5, // max parallel fetches (default)
+})
+```
+
+On Android that is Fresco's `prefetchToDiskCache`; on iOS, SDWebImage's
+prefetcher storing to disk. On web it loads each URL through a throwaway
+`<img>` so the browser HTTP cache is warm. It resolves `false` when any URL
+fails — and always `false` on macOS, where the AppKit host has no image
+pipeline yet. Same contract as `@octane-xplat/image`'s `prefetch`.
+
+Options: `headers` is forwarded to the engine — **honored on Android,
+dropped on iOS** (the plugin's prefetch path lacks the request-modifier
+branch its display path has; an upstream patch is needed) — and ignored on
+web. `concurrency` caps parallel fetches JS-side (default 5).
+
+## Platform props
+
+`ios`, `android`, and `web` escape bags apply after the shared props, the
+same convention as `@octane-xplat/ui`. Native bags assign onto the ui-image
+`Img` view, so engine props such as `noCache`, `decodeWidth`,
+`decodeHeight`, `placeholderImageUri`, and `progressiveRenderingEnabled`
+are reachable where the engine supports them:
+
+```tsx
+<AnimatedImage
+	src={photo.url}
+	ios={{ noCache: true }}
+	android={{ decodeWidth: 288, decodeHeight: 288 }}
+/>
+```
+
 Per-target limits are recorded in
 [known limits](../../docs/verify/known-limits.md). Exercised by
 [`AnimatedImageDemo`](../demos/src/AnimatedImageDemo.tsrx).

package/dist/native/AnimatedImage.tsrx.js

@@ -0,0 +1,39 @@
+import { applyEscapeProps } from "./escape-props.js";
+import { defineUniversalComponent, registerElement, universalPlan, universalValue } from "@nativescript-community/octane";
+import { Img } from "@nativescript-community/ui-image";
+//#region src/AnimatedImage.tsrx
+var __octaneUniversalPlan0 = universalPlan("nativescript", {
+	"kind": "host",
+	"type": "animatedimage",
+	"props": {
+		"animatedImageView": true,
+		"autoPlayAnimations": true
+	},
+	"bindings": [
+		["ref", 0],
+		["id", 1],
+		["className", 2],
+		["style", 3],
+		["src", 4],
+		["stretch", 5],
+		["width", 6],
+		["height", 7],
+		["accessibilityLabel", 8]
+	]
+});
+registerElement("animatedimage", Img);
+var AnimatedImage = defineUniversalComponent("nativescript", function AnimatedImage(props) {
+	return universalValue(__octaneUniversalPlan0, [
+		(v) => applyEscapeProps(v, props),
+		props.id,
+		props.className,
+		props.style,
+		props.src,
+		props.stretch ?? "aspectFit",
+		props.width,
+		props.height,
+		props.alt
+	]);
+}, { "module": "@nativescript-community/octane" });
+//#endregion
+export { AnimatedImage };

package/dist/native/escape-props.js

@@ -0,0 +1,12 @@
+import { isAndroid, isIOS } from "@nativescript/core";
+//#region src/escape-props.ts
+/** Apply only the active device's escape bag after the shared props — the
+*  same convention @octane-xplat/ui uses, kept local so this leaf does not
+*  depend on ui. */
+function applyEscapeProps(view, props) {
+	if (!view) return;
+	const bag = isIOS ? props.ios : isAndroid ? props.android : void 0;
+	if (bag) Object.assign(view, bag);
+}
+//#endregion
+export { applyEscapeProps };

package/dist/native/index.js

@@ -1,36 +1,3 @@
-import { defineUniversalComponent, registerElement, universalPlan, universalValue } from "@nativescript-community/octane";
-import { Img } from "@nativescript-community/ui-image";
-//#region src/AnimatedImage.tsrx
-var __octaneUniversalPlan0 = universalPlan("nativescript", {
-	"kind": "host",
-	"type": "animatedimage",
-	"props": {
-		"animatedImageView": true,
-		"autoPlayAnimations": true
-	},
-	"bindings": [
-		["id", 0],
-		["className", 1],
-		["style", 2],
-		["src", 3],
-		["stretch", 4],
-		["width", 5],
-		["height", 6],
-		["accessibilityLabel", 7]
-	]
-});
-registerElement("animatedimage", Img);
-var AnimatedImage = defineUniversalComponent("nativescript", function AnimatedImage(props) {
-	return universalValue(__octaneUniversalPlan0, [
-		props.id,
-		props.className,
-		props.style,
-		props.src,
-		props.stretch ?? "aspectFit",
-		props.width,
-		props.height,
-		props.alt
-	]);
-}, { "module": "@nativescript-community/octane" });
-//#endregion
-export { AnimatedImage };
+import { AnimatedImage } from "./AnimatedImage.tsrx.js";
+import { prefetch } from "./prefetch.js";
+export { AnimatedImage, prefetch };

package/dist/native/octane-client-build.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "buildId": "c6fedeaa-e421-4e30-9b60-ebee0157b035",
+  "buildId": "2aeebf52-3b47-473e-8519-9eb628f641fb",
   "mode": "production",
   "capabilities": {
     "independentHydration": false

package/dist/native/prefetch-batch.js

@@ -0,0 +1,27 @@
+function prefetchBatch(srcs, concurrency, warm) {
+	const urls = Array.isArray(srcs) ? srcs : [srcs];
+	if (urls.length === 0) return Promise.resolve(true);
+	const requested = Math.floor(concurrency ?? 5);
+	const limit = Number.isFinite(requested) && requested > 0 ? requested : 5;
+	return new Promise((resolve) => {
+		let next = 0;
+		let active = Math.min(limit, urls.length);
+		for (let i = 0; i < active; i++) (async () => {
+			while (next < urls.length) {
+				const url = urls[next++];
+				try {
+					if (!await warm(url)) {
+						resolve(false);
+						return;
+					}
+				} catch {
+					resolve(false);
+					return;
+				}
+			}
+			if (--active === 0) resolve(true);
+		})();
+	});
+}
+//#endregion
+export { prefetchBatch };

package/dist/native/prefetch.js

@@ -0,0 +1,26 @@
+import { prefetchBatch } from "./prefetch-batch.js";
+import { getImagePipeline, initialize } from "@nativescript-community/ui-image";
+import { isAndroid } from "@nativescript/core";
+//#region src/prefetch.ts
+/** prefetch — warm the image engine's disk cache for `srcs` without displaying
+*  anything. Android (Fresco): `prefetchToDiskCache` stores encoded bytes on
+*  disk and defers bitmap decode to display. iOS (SDWebImage): the prefetcher
+*  stores the downloaded image to the disk cache only. Either way a later
+*  `AnimatedImage` with the same src hits disk instead of the network.
+*  Resolves false when any URL fails; resolves false when the pipeline is not
+*  available yet (e.g. called before app launch).
+*  `options.concurrency` caps parallel fetches (default 5); `options.headers`
+*  is honored on Android and silently dropped on iOS (upstream gap — see
+*  PrefetchOptions). */
+function prefetch(srcs, options) {
+	try {
+		if (isAndroid) initialize();
+		const pipeline = getImagePipeline();
+		const { concurrency, ...engineOptions } = options ?? {};
+		return prefetchBatch(srcs, concurrency, (url) => pipeline.prefetchToDiskCache(url, engineOptions).then(() => true, () => false));
+	} catch {
+		return Promise.resolve(false);
+	}
+}
+//#endregion
+export { prefetch };

package/dist/web/AnimatedImage.web.tsrx.js

@@ -0,0 +1,49 @@
+import { applyEscapeProps } from "./escape-props.web.js";
+import { __s, bag7, clone, queueRefAttach, queueRefDetach, setStyle, template } from "octane";
+import { bindSignalAttribute, enableSignalBindings, replaceRef, setPlainAttribute, setURLAttribute } from "octane/internal/client";
+//#region src/AnimatedImage.web.tsrx
+enableSignalBindings(1, true);
+var _t$0 = /* @__PURE__ */ template("<img/>");
+var _rm$0 = [
+	"r",
+	"b",
+	"a"
+];
+var OBJECT_FIT = {
+	none: "none",
+	fill: "fill",
+	aspectFit: "contain",
+	aspectFill: "cover"
+};
+var AnimatedImage = /* @__PURE__ */ __s(function AnimatedImage(props, __s, __extra) {
+	let _b = __s.slots[0];
+	if (_b === void 0) {
+		let _m0, _m1;
+		const _root = clone(_t$0);
+		queueRefAttach(__s, _m1 = (e) => applyEscapeProps(e, props), _m0 = _root);
+		(__s.cleanups ??= []).push(() => _b && queueRefDetach(_b.b, _b.a));
+		_b = bag7(__s, _root, _m0, _m1, void 0, void 0, void 0, void 0, void 0);
+		__s.refFields = _rm$0;
+	} else {
+		const _r = (e) => applyEscapeProps(e, props);
+		if (_r !== _b.b) _b.b = replaceRef(__s, _b.b, _r, _b.a);
+	}
+	_b.c = bindSignalAttribute(__s, _b.c, _b.a, "id", props.id, "b:524dc1ba", setPlainAttribute);
+	_b.d = bindSignalAttribute(__s, _b.d, _b.a, "class", props.className, "b:0279b906", "class");
+	{
+		const _v = {
+			objectFit: OBJECT_FIT[props.stretch ?? "aspectFit"],
+			width: props.width,
+			height: props.height,
+			...props.style
+		};
+		if (_b.e !== _v) {
+			setStyle(_b.a, _v, _b.e);
+			_b.e = _v;
+		}
+	}
+	_b.f = bindSignalAttribute(__s, _b.f, _b.a, "src", props.src, "b:f8b000cf", setURLAttribute);
+	_b.g = bindSignalAttribute(__s, _b.g, _b.a, "alt", props.alt, "b:29df9938", setPlainAttribute);
+});
+//#endregion
+export { AnimatedImage };

package/dist/web/escape-props.web.js

@@ -0,0 +1,18 @@
+//#region src/escape-props.web.ts
+/** Apply DOM escape props after the primitive's own props. Dash-named keys
+*  are attributes; other keys use the DOM property where available. Mirrors
+*  @octane-xplat/ui's web escape-props so this leaf does not depend on ui. */
+function applyEscapeProps(element, props) {
+	if (!element || !props.web) return;
+	for (const [key, value] of Object.entries(props.web)) if (key.includes("-")) {
+		if (value == null || value === false) element.removeAttribute(key);
+		else element.setAttribute(key, value === true ? "" : String(value));
+	} else if (key in element) try {
+		element[key] = value;
+	} catch {
+		element.setAttribute(key, String(value));
+	}
+	else if (value != null) element.setAttribute(key, String(value));
+}
+//#endregion
+export { applyEscapeProps };

package/dist/web/index.js

@@ -1,38 +1,3 @@
-import { __s, bag6, clone, setStyle, template } from "octane";
-import { bindSignalAttribute, enableSignalBindings, setPlainAttribute, setURLAttribute } from "octane/internal/client";
-//#region src/AnimatedImage.web.tsrx
-enableSignalBindings(1, true);
-var _t$0 = /* @__PURE__ */ template("<img/>");
-var OBJECT_FIT = {
-	none: "none",
-	fill: "fill",
-	aspectFit: "contain",
-	aspectFill: "cover"
-};
-var AnimatedImage = /* @__PURE__ */ __s(function AnimatedImage(props, __s, __extra) {
-	let _b = __s.slots[0];
-	if (_b === void 0) {
-		let _m1;
-		const _root = clone(_t$0);
-		_m1 = _root;
-		_b = bag6(__s, _root, void 0, _m1, void 0, void 0, void 0, void 0);
-	}
-	_b.a = bindSignalAttribute(__s, _b.a, _b.b, "id", props.id, "b:42ec7ee7", setPlainAttribute);
-	_b.c = bindSignalAttribute(__s, _b.c, _b.b, "class", props.className, "b:1b1f2715", "class");
-	{
-		const _v = {
-			objectFit: OBJECT_FIT[props.stretch ?? "aspectFit"],
-			width: props.width,
-			height: props.height,
-			...props.style
-		};
-		if (_b.d !== _v) {
-			setStyle(_b.b, _v, _b.d);
-			_b.d = _v;
-		}
-	}
-	_b.e = bindSignalAttribute(__s, _b.e, _b.b, "src", props.src, "b:3d7475fa", setURLAttribute);
-	_b.f = bindSignalAttribute(__s, _b.f, _b.b, "alt", props.alt, "b:3f7e4d1f", setPlainAttribute);
-});
-//#endregion
-export { AnimatedImage };
+import { AnimatedImage } from "./AnimatedImage.web.tsrx.js";
+import { prefetch } from "./prefetch.web.js";
+export { AnimatedImage, prefetch };

package/dist/web/octane-client-build.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "buildId": "53761028-f4c2-4203-8188-4bb35aaf8f26",
+  "buildId": "0940d223-5435-4ff5-98b9-95158ea69208",
   "mode": "production",
   "capabilities": {
     "independentHydration": false

package/dist/web/prefetch-batch.js

@@ -0,0 +1,27 @@
+function prefetchBatch(srcs, concurrency, warm) {
+	const urls = Array.isArray(srcs) ? srcs : [srcs];
+	if (urls.length === 0) return Promise.resolve(true);
+	const requested = Math.floor(concurrency ?? 5);
+	const limit = Number.isFinite(requested) && requested > 0 ? requested : 5;
+	return new Promise((resolve) => {
+		let next = 0;
+		let active = Math.min(limit, urls.length);
+		for (let i = 0; i < active; i++) (async () => {
+			while (next < urls.length) {
+				const url = urls[next++];
+				try {
+					if (!await warm(url)) {
+						resolve(false);
+						return;
+					}
+				} catch {
+					resolve(false);
+					return;
+				}
+			}
+			if (--active === 0) resolve(true);
+		})();
+	});
+}
+//#endregion
+export { prefetchBatch };

package/dist/web/prefetch.web.js

@@ -0,0 +1,17 @@
+import { prefetchBatch } from "./prefetch-batch.js";
+//#region src/prefetch.web.ts
+/** prefetch — load each `src` through a throwaway <img> so the response lands
+*  in the browser HTTP cache; decode and render stay with the displaying
+*  element. `options.headers` is ignored — an <img> request cannot carry
+*  custom headers. `options.concurrency` caps parallel loads (default 5).
+*  Resolves false when any URL fails. */
+function prefetch(srcs, options) {
+	return prefetchBatch(srcs, options?.concurrency, (url) => new Promise((resolve) => {
+		const image = new Image();
+		image.onload = () => resolve(true);
+		image.onerror = () => resolve(false);
+		image.src = url;
+	}));
+}
+//#endregion
+export { prefetch };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octane-xplat/gif",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "description": "Animated images (GIF/animated webp) for Octane xplat — web <img> + @nativescript-community/ui-image",
   "keywords": [
     "android",

package/src/AnimatedImage.tsrx

@@ -2,6 +2,7 @@
 import { registerElement } from '@nativescript-community/octane';
 import { Img } from '@nativescript-community/ui-image';
 import type { AnimatedImageProps } from './props';
+import { applyEscapeProps } from './escape-props';
 
 // @nativescript-community/ui-image — Fresco DraweeView on Android,
 // SDAnimatedImageView on iOS when `animatedImageView` is set (plain UIImageView
@@ -14,6 +15,7 @@ registerElement('animatedimage', Img);
  *  the shared contract is always-playing. */
 export function AnimatedImage(props: AnimatedImageProps) @{
 	<animatedimage
+		ref={(v: any) => applyEscapeProps(v, props)}
 		id={props.id}
 		className={props.className}
 		style={props.style}

package/src/AnimatedImage.web.tsrx

@@ -1,4 +1,5 @@
 import type { AnimatedImageProps } from './props';
+import { applyEscapeProps } from './escape-props.web';
 
 const OBJECT_FIT = {
 	none: 'none',
@@ -11,6 +12,7 @@ const OBJECT_FIT = {
  *  `stretch` maps to object-fit. */
 export function AnimatedImage(props: AnimatedImageProps) @{
 	<img
+		ref={(e: any) => applyEscapeProps(e, props)}
 		id={props.id}
 		className={props.className}
 		style={{

package/src/escape-props.ts

@@ -0,0 +1,15 @@
+import { isAndroid, isIOS } from '@nativescript/core'
+
+/** Apply only the active device's escape bag after the shared props — the
+ *  same convention @octane-xplat/ui uses, kept local so this leaf does not
+ *  depend on ui. */
+export function applyEscapeProps(view: any, props: { ios?: any; android?: any }): void {
+	if (!view) {
+		return
+	}
+
+	const bag = isIOS ? props.ios : isAndroid ? props.android : undefined
+	if (bag) {
+		Object.assign(view, bag)
+	}
+}

package/src/escape-props.web.ts

@@ -0,0 +1,26 @@
+/** Apply DOM escape props after the primitive's own props. Dash-named keys
+ *  are attributes; other keys use the DOM property where available. Mirrors
+ *  @octane-xplat/ui's web escape-props so this leaf does not depend on ui. */
+export function applyEscapeProps(element: any, props: { web?: any }): void {
+	if (!element || !props.web) {
+		return
+	}
+
+	for (const [key, value] of Object.entries(props.web)) {
+		if (key.includes('-')) {
+			if (value == null || value === false) {
+				element.removeAttribute(key)
+			} else {
+				element.setAttribute(key, value === true ? '' : String(value))
+			}
+		} else if (key in element) {
+			try {
+				element[key] = value
+			} catch {
+				element.setAttribute(key, String(value))
+			}
+		} else if (value != null) {
+			element.setAttribute(key, String(value))
+		}
+	}
+}

package/src/index.macos.ts

@@ -1,2 +1,3 @@
 export { AnimatedImage } from './AnimatedImage.macos.tsrx'
-export type { AnimatedImageProps } from './props'
+export { prefetch } from './prefetch.macos'
+export type { AnimatedImageProps, PrefetchOptions } from './props'

package/src/index.ts

@@ -1,4 +1,5 @@
 // Platform barrels — explicit .tsrx leaf imports (moduleSuffixes don't
 // reach .tsrx; same convention as @octane-xplat/ui index.*.ts).
 export { AnimatedImage } from './AnimatedImage.tsrx'
-export type { AnimatedImageProps } from './props'
+export { prefetch } from './prefetch'
+export type { AnimatedImageProps, PrefetchOptions } from './props'

package/src/index.web.ts

@@ -1,4 +1,5 @@
 // Platform barrels — explicit .tsrx leaf imports (moduleSuffixes don't
 // reach .tsrx; same convention as @octane-xplat/ui index.*.ts).
 export { AnimatedImage } from './AnimatedImage.web.tsrx'
-export type { AnimatedImageProps } from './props'
+export { prefetch } from './prefetch.web'
+export type { AnimatedImageProps, PrefetchOptions } from './props'

package/src/prefetch-batch.ts

@@ -0,0 +1,50 @@
+/** VENDORED — identical copy in packages/gif/src/prefetch-batch.ts; keep in
+ *  sync.
+ *
+ *  Shared batch driver for the image-engine leaves' `prefetch` contract:
+ *  normalizes `string | string[]`, caps in-flight requests JS-side, and
+ *  resolves `true` only when every URL warms — `false` on the first failure
+ *  (in-flight requests settle on their own; the result is already decided). */
+
+/** Matches the `maxRequests = 5` ceiling NS core's ImageCache used. */
+export const DEFAULT_PREFETCH_CONCURRENCY = 5
+
+export function prefetchBatch(
+	srcs: string | string[],
+	concurrency: number | undefined,
+	warm: (url: string) => Promise<boolean>,
+): Promise<boolean> {
+	const urls = Array.isArray(srcs) ? srcs : [srcs]
+	if (urls.length === 0) {
+		return Promise.resolve(true)
+	}
+
+	const requested = Math.floor(concurrency ?? DEFAULT_PREFETCH_CONCURRENCY)
+	const limit =
+		Number.isFinite(requested) && requested > 0 ? requested : DEFAULT_PREFETCH_CONCURRENCY
+
+	return new Promise<boolean>((resolve) => {
+		let next = 0
+		let active = Math.min(limit, urls.length)
+		for (let i = 0; i < active; i++) {
+			void (async () => {
+				while (next < urls.length) {
+					const url = urls[next++]
+					try {
+						if (!(await warm(url))) {
+							resolve(false)
+							return
+						}
+					} catch {
+						resolve(false)
+						return
+					}
+				}
+
+				if (--active === 0) {
+					resolve(true)
+				}
+			})()
+		}
+	})
+}

package/src/prefetch.macos.ts

@@ -0,0 +1,8 @@
+import type { PrefetchOptions } from './props'
+
+/** prefetch — no-op on the AppKit host: it has no image pipeline yet
+ *  (AnimatedImage renders a placeholder there), so nothing is warmed.
+ *  Resolves false to report that honestly. */
+export function prefetch(_srcs: string | string[], _options?: PrefetchOptions): Promise<boolean> {
+	return Promise.resolve(false)
+}

package/src/prefetch.ts

@@ -0,0 +1,38 @@
+import { isAndroid } from '@nativescript/core'
+import { getImagePipeline, initialize } from '@nativescript-community/ui-image'
+import { prefetchBatch } from './prefetch-batch'
+import type { PrefetchOptions } from './props'
+
+/** prefetch — warm the image engine's disk cache for `srcs` without displaying
+ *  anything. Android (Fresco): `prefetchToDiskCache` stores encoded bytes on
+ *  disk and defers bitmap decode to display. iOS (SDWebImage): the prefetcher
+ *  stores the downloaded image to the disk cache only. Either way a later
+ *  `AnimatedImage` with the same src hits disk instead of the network.
+ *  Resolves false when any URL fails; resolves false when the pipeline is not
+ *  available yet (e.g. called before app launch).
+ *  `options.concurrency` caps parallel fetches (default 5); `options.headers`
+ *  is honored on Android and silently dropped on iOS (upstream gap — see
+ *  PrefetchOptions). */
+export function prefetch(srcs: string | string[], options?: PrefetchOptions): Promise<boolean> {
+	try {
+		// The plugin lazily initializes Fresco inside createNativeView; a prefetch
+		// that runs before any Img mounts has to do it first. initialize() is a
+		// no-op once the plugin (or the app) has initialized. iOS has no equivalent
+		// requirement and its initialize() is not guarded, so it stays Android-only.
+		if (isAndroid) {
+			initialize()
+		}
+
+		const pipeline = getImagePipeline()
+		const { concurrency, ...engineOptions } = options ?? {}
+
+		return prefetchBatch(srcs, concurrency, (url) =>
+			pipeline.prefetchToDiskCache(url, engineOptions).then(
+				() => true,
+				() => false,
+			),
+		)
+	} catch {
+		return Promise.resolve(false)
+	}
+}

package/src/prefetch.web.test.ts

@@ -0,0 +1,104 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { prefetch } from './prefetch.web'
+import { prefetchBatch } from './prefetch-batch'
+
+// Same web prefetch contract as @octane-xplat/image: throwaway <img> per URL,
+// awaited until load/error, false when any URL fails, JS-side concurrency cap.
+
+class MockImage {
+	static instances: MockImage[] = []
+	onload: (() => void) | null = null
+	onerror: (() => void) | null = null
+	set src(_url: string) {
+		MockImage.instances.push(this)
+	}
+	load() {
+		this.onload?.()
+	}
+	fail() {
+		this.onerror?.()
+	}
+}
+
+const flush = () => new Promise((resolve) => setTimeout(resolve, 0))
+
+async function drainPending(promise: Promise<boolean>) {
+	let result: boolean | undefined
+	void promise.then((value) => {
+		result = value
+	})
+
+	while (result === undefined) {
+		for (const image of MockImage.instances.splice(0)) {
+			image.load()
+		}
+
+		await flush()
+	}
+
+	return result
+}
+
+describe('prefetch (web)', () => {
+	afterEach(() => {
+		MockImage.instances = []
+		vi.unstubAllGlobals()
+	})
+
+	it('resolves true only after every <img> fires load', async () => {
+		vi.stubGlobal('Image', MockImage)
+		const promise = prefetch(['https://x/a.gif', 'https://x/b.gif'])
+		let settled = false
+		void promise.then(() => {
+			settled = true
+		})
+
+		await flush()
+		expect(settled).toBe(false)
+		expect(await drainPending(promise)).toBe(true)
+	})
+
+	it('resolves false when any URL fails', async () => {
+		vi.stubGlobal('Image', MockImage)
+		const promise = prefetch(['https://x/a.gif', 'https://x/b.gif'])
+		const [failed] = MockImage.instances.splice(0)
+		failed.fail()
+		expect(await promise).toBe(false)
+	})
+
+	it('accepts a single URL and resolves true for an empty batch', async () => {
+		vi.stubGlobal('Image', MockImage)
+		expect(await prefetch([])).toBe(true)
+		const promise = prefetch('https://x/a.gif')
+		expect(MockImage.instances).toHaveLength(1)
+		expect(await drainPending(promise)).toBe(true)
+	})
+
+	it('caps in-flight loads at options.concurrency', async () => {
+		vi.stubGlobal('Image', MockImage)
+		const promise = prefetch(
+			Array.from({ length: 7 }, (_, i) => `https://x/${i}.gif`),
+			{ concurrency: 2, headers: { Authorization: 'Bearer x' } },
+		)
+
+		expect(MockImage.instances).toHaveLength(2)
+		MockImage.instances.splice(0).forEach((image) => image.load())
+		await flush()
+		await flush()
+		expect(MockImage.instances.length).toBeLessThanOrEqual(2)
+		expect(await drainPending(promise)).toBe(true)
+	})
+
+	it('defaults to five parallel loads', async () => {
+		vi.stubGlobal('Image', MockImage)
+		const promise = prefetch(Array.from({ length: 9 }, (_, i) => `https://x/${i}.gif`))
+		expect(MockImage.instances).toHaveLength(5)
+		expect(await drainPending(promise)).toBe(true)
+	})
+})
+
+describe('prefetchBatch', () => {
+	it('reports false if the warm callback throws', async () => {
+		expect(await prefetchBatch(['a', 'b'], 5, () => Promise.reject(new Error('boom')))).toBe(false)
+	})
+})

package/src/prefetch.web.ts

@@ -0,0 +1,21 @@
+import { prefetchBatch } from './prefetch-batch'
+import type { PrefetchOptions } from './props'
+
+/** prefetch — load each `src` through a throwaway <img> so the response lands
+ *  in the browser HTTP cache; decode and render stay with the displaying
+ *  element. `options.headers` is ignored — an <img> request cannot carry
+ *  custom headers. `options.concurrency` caps parallel loads (default 5).
+ *  Resolves false when any URL fails. */
+export function prefetch(srcs: string | string[], options?: PrefetchOptions): Promise<boolean> {
+	return prefetchBatch(
+		srcs,
+		options?.concurrency,
+		(url) =>
+			new Promise<boolean>((resolve) => {
+				const image = new Image()
+				image.onload = () => resolve(true)
+				image.onerror = () => resolve(false)
+				image.src = url
+			}),
+	)
+}

package/src/props.ts

@@ -9,4 +9,26 @@ export interface AnimatedImageProps {
 	stretch?: 'none' | 'fill' | 'aspectFit' | 'aspectFill'
 	width?: string | number
 	height?: string | number
+	/** Platform-specific properties are applied after shared props. Native
+	 *  bags assign onto the ui-image `Img` view — `noCache`, `decodeWidth`,
+	 *  `decodeHeight`, `placeholderImageUri`, `progressiveRenderingEnabled`,
+	 *  `cacheKey`, and the rest of its prop surface are reachable this way;
+	 *  the shared props stay the parity contract. */
+	ios?: any
+	android?: any
+	web?: any
+}
+
+/** Options for `prefetch`. The same contract `@octane-xplat/image`'s
+ *  `prefetch` carries. */
+export interface PrefetchOptions {
+	/** Request headers for the prefetch fetch. Honored on Android (Fresco);
+	 *  **dropped on iOS** — the plugin's prefetch path builds its SDWebImage
+	 *  context without the download-request-modifier branch its `Img`
+	 *  display path has; an upstream patch is needed there. Ignored on web —
+	 *  a plain <img> cannot send custom headers. */
+	headers?: Record<string, string>
+	/** Max URLs fetched in parallel (JS-side cap). Default 5 — the same
+	 *  ceiling NS core's ImageCache used. */
+	concurrency?: number
 }

package/types/generated/.tsrx-typegen-manifest.json

@@ -3,8 +3,13 @@
   "files": [
     "AnimatedImage.d.ts",
     "AnimatedImage.web.d.ts",
+    "escape-props.d.ts",
+    "escape-props.web.d.ts",
     "index.d.ts",
     "index.web.d.ts",
+    "prefetch-batch.d.ts",
+    "prefetch.d.ts",
+    "prefetch.web.d.ts",
     "props.d.ts"
   ]
 }

package/types/generated/escape-props.d.ts

@@ -0,0 +1,7 @@
+/** Apply only the active device's escape bag after the shared props — the
+ *  same convention @octane-xplat/ui uses, kept local so this leaf does not
+ *  depend on ui. */
+export declare function applyEscapeProps(view: any, props: {
+    ios?: any;
+    android?: any;
+}): void;

package/types/generated/escape-props.web.d.ts

@@ -0,0 +1,6 @@
+/** Apply DOM escape props after the primitive's own props. Dash-named keys
+ *  are attributes; other keys use the DOM property where available. Mirrors
+ *  @octane-xplat/ui's web escape-props so this leaf does not depend on ui. */
+export declare function applyEscapeProps(element: any, props: {
+    web?: any;
+}): void;

package/types/generated/index.d.ts

@@ -1,2 +1,3 @@
 export { AnimatedImage } from './AnimatedImage.js';
-export type { AnimatedImageProps } from './props.js';
+export { prefetch } from './prefetch.js';
+export type { AnimatedImageProps, PrefetchOptions } from './props.js';

package/types/generated/index.web.d.ts

@@ -1,2 +1,3 @@
 export { AnimatedImage } from './AnimatedImage.web.js';
-export type { AnimatedImageProps } from './props.js';
+export { prefetch } from './prefetch.web.js';
+export type { AnimatedImageProps, PrefetchOptions } from './props.js';

package/types/generated/prefetch-batch.d.ts

@@ -0,0 +1,10 @@
+/** VENDORED — identical copy in packages/gif/src/prefetch-batch.ts; keep in
+ *  sync.
+ *
+ *  Shared batch driver for the image-engine leaves' `prefetch` contract:
+ *  normalizes `string | string[]`, caps in-flight requests JS-side, and
+ *  resolves `true` only when every URL warms — `false` on the first failure
+ *  (in-flight requests settle on their own; the result is already decided). */
+/** Matches the `maxRequests = 5` ceiling NS core's ImageCache used. */
+export declare const DEFAULT_PREFETCH_CONCURRENCY = 5;
+export declare function prefetchBatch(srcs: string | string[], concurrency: number | undefined, warm: (url: string) => Promise<boolean>): Promise<boolean>;

package/types/generated/prefetch.d.ts

@@ -0,0 +1,12 @@
+import type { PrefetchOptions } from './props.js';
+/** prefetch — warm the image engine's disk cache for `srcs` without displaying
+ *  anything. Android (Fresco): `prefetchToDiskCache` stores encoded bytes on
+ *  disk and defers bitmap decode to display. iOS (SDWebImage): the prefetcher
+ *  stores the downloaded image to the disk cache only. Either way a later
+ *  `AnimatedImage` with the same src hits disk instead of the network.
+ *  Resolves false when any URL fails; resolves false when the pipeline is not
+ *  available yet (e.g. called before app launch).
+ *  `options.concurrency` caps parallel fetches (default 5); `options.headers`
+ *  is honored on Android and silently dropped on iOS (upstream gap — see
+ *  PrefetchOptions). */
+export declare function prefetch(srcs: string | string[], options?: PrefetchOptions): Promise<boolean>;

package/types/generated/prefetch.web.d.ts

@@ -0,0 +1,7 @@
+import type { PrefetchOptions } from './props.js';
+/** prefetch — load each `src` through a throwaway <img> so the response lands
+ *  in the browser HTTP cache; decode and render stay with the displaying
+ *  element. `options.headers` is ignored — an <img> request cannot carry
+ *  custom headers. `options.concurrency` caps parallel loads (default 5).
+ *  Resolves false when any URL fails. */
+export declare function prefetch(srcs: string | string[], options?: PrefetchOptions): Promise<boolean>;

package/types/generated/props.d.ts

@@ -9,4 +9,25 @@ export interface AnimatedImageProps {
     stretch?: 'none' | 'fill' | 'aspectFit' | 'aspectFill';
     width?: string | number;
     height?: string | number;
+    /** Platform-specific properties are applied after shared props. Native
+     *  bags assign onto the ui-image `Img` view — `noCache`, `decodeWidth`,
+     *  `decodeHeight`, `placeholderImageUri`, `progressiveRenderingEnabled`,
+     *  `cacheKey`, and the rest of its prop surface are reachable this way;
+     *  the shared props stay the parity contract. */
+    ios?: any;
+    android?: any;
+    web?: any;
+}
+/** Options for `prefetch`. The same contract `@octane-xplat/image`'s
+ *  `prefetch` carries. */
+export interface PrefetchOptions {
+    /** Request headers for the prefetch fetch. Honored on Android (Fresco);
+     *  **dropped on iOS** — the plugin's prefetch path builds its SDWebImage
+     *  context without the download-request-modifier branch its `Img`
+     *  display path has; an upstream patch is needed there. Ignored on web —
+     *  a plain <img> cannot send custom headers. */
+    headers?: Record<string, string>;
+    /** Max URLs fetched in parallel (JS-side cap). Default 5 — the same
+     *  ceiling NS core's ImageCache used. */
+    concurrency?: number;
 }

package/types/index.macos.d.ts

@@ -1,4 +1,5 @@
-import type { AnimatedImageProps } from './generated/props.js'
+import type { AnimatedImageProps, PrefetchOptions } from './generated/props.js'
 
-export type { AnimatedImageProps } from './generated/props.js'
+export type { AnimatedImageProps, PrefetchOptions } from './generated/props.js'
 export declare function AnimatedImage(props: AnimatedImageProps): unknown
+export declare function prefetch(srcs: string | string[], options?: PrefetchOptions): Promise<boolean>