@octane-xplat/gif 0.0.0-nightly.g2e22171

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Alec Larson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,72 @@
+# `@octane-xplat/gif`
+
+```sh
+pnpm add @octane-xplat/gif
+```
+
+Animated images (GIF, animated WebP) for Octane xplat apps: a plain
+`<img>` on web and `@nativescript-community/ui-image`
+(Fresco on Android / SDWebImage on iOS) on native, with a macOS entry.
+
+```tsx
+import { AnimatedImage } from '@octane-xplat/gif'
+
+;<AnimatedImage
+	src="https://example.com/loader.gif"
+	alt="Loading"
+	stretch="aspectFit" // 'none' | 'fill' | 'aspectFit' | 'aspectFill'
+	width={96}
+	height={96}
+/>
+```
+
+`stretch` shares the core `Image` grammar — web maps it to `object-fit`
+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/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@octane-xplat/gif",
+  "version": "0.0.0-nightly.g2e22171",
+  "description": "Animated images (GIF/animated webp) for Octane xplat — web <img> + @nativescript-community/ui-image",
+  "keywords": [
+    "android",
+    "animated-image",
+    "animated-webp",
+    "cross-platform",
+    "gif",
+    "image",
+    "ios",
+    "nativescript",
+    "octane",
+    "web",
+    "xplat"
+  ],
+  "homepage": "https://github.com/octane-xplat/octane-xplat/tree/main/packages/gif",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/octane-xplat/octane-xplat",
+    "directory": "packages/gif"
+  },
+  "files": [
+    "types",
+    "src",
+    "!src/**/*.test.*",
+    "!src/**/*.spec.*"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "macos": {
+        "types": "./types/index.macos.d.ts",
+        "default": "./src/index.macos.ts"
+      },
+      "web": {
+        "types": "./types/generated/index.web.d.ts",
+        "default": "./src/index.web.ts"
+      },
+      "native": {
+        "types": "./types/generated/index.d.ts",
+        "default": "./src/index.ts"
+      },
+      "types": "./types/generated/index.d.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@nativescript-community/ui-image": "4.6.20"
+  },
+  "devDependencies": {
+    "@nativescript-community/octane": "0.2.5",
+    "@nativescript/core": "9.1.3",
+    "@octane-xplat/macos-renderer": "0.0.0-nightly.g2e22171",
+    "@octanejs/vite-plugin": "0.1.61",
+    "@tsrx/typescript-plugin": "0.4.11",
+    "octane": "0.11.0",
+    "tsrx-typegen": "0.3.0",
+    "typescript": "5.9.3",
+    "vite": "8.3.0"
+  },
+  "peerDependencies": {
+    "@nativescript-community/octane": ">=0.2.1 <1",
+    "@nativescript/core": ">=9.1.0 <10",
+    "octane": ">=0.6.3 <1"
+  },
+  "peerDependenciesMeta": {
+    "@nativescript-community/octane": {
+      "optional": true
+    },
+    "@nativescript/core": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "test:packed": "node tests/packed-consumer.mjs",
+    "typegen": "tsrx-typegen --target octane",
+    "pack:check": "tsrx-typegen --pack-check"
+  }
+}

package/src/AnimatedImage.macos.tsrx

@@ -0,0 +1,7 @@
+/** @jsxImportSource @octane-xplat/macos-renderer */
+import type { AnimatedImageProps } from './props'
+
+/** Show an explicit placeholder until the AppKit host has an animation view. */
+export function AnimatedImage(_props: AnimatedImageProps) @{
+	<label className="vx-unsupported">Animated images are unsupported by the AppKit host</label>
+}

package/src/AnimatedImage.tsrx

@@ -0,0 +1,30 @@
+/** @jsxImportSource @nativescript-community/octane */
+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
+// otherwise, which would still decode but not animate).
+registerElement('animatedimage', Img);
+
+/** AnimatedImage — GIF/animated-webp decode + autoplay via ui-image. `src`
+ *  takes the Img grammar: remote URL, res://name, ~/bundle path, file path.
+ *  There is intentionally no play/pause prop — <img> can't pause on web, so
+ *  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}
+		src={props.src}
+		stretch={props.stretch ?? 'aspectFit'}
+		width={props.width}
+		height={props.height}
+		animatedImageView={true}
+		autoPlayAnimations={true}
+		accessibilityLabel={props.alt}
+	/>
+}

package/src/AnimatedImage.web.tsrx

@@ -0,0 +1,27 @@
+import type { AnimatedImageProps } from './props';
+import { applyEscapeProps } from './escape-props.web';
+
+const OBJECT_FIT = {
+	none: 'none',
+	fill: 'fill',
+	aspectFit: 'contain',
+	aspectFill: 'cover',
+} as const;
+
+/** AnimatedImage — a plain <img>; browsers animate GIF/webp natively.
+ *  `stretch` maps to object-fit. */
+export function AnimatedImage(props: AnimatedImageProps) @{
+	<img
+		ref={(e: any) => applyEscapeProps(e, props)}
+		id={props.id}
+		className={props.className}
+		style={{
+			objectFit: OBJECT_FIT[props.stretch ?? 'aspectFit'],
+			width: props.width,
+			height: props.height,
+			...props.style,
+		}}
+		src={props.src}
+		alt={props.alt}
+	/>
+}

package/src/AnimatedImage.windows.tsrx

@@ -0,0 +1,8 @@
+/** @jsxImportSource @nativescript-community/octane */
+import type { AnimatedImageProps } from './props'
+
+/** Unsupported placeholder — the Windows host has no animated-image engine
+ *  (ui-image ships iOS/Android only). */
+export function AnimatedImage(_props: AnimatedImageProps) @{
+	<label className="vx-unsupported" text="Animated images are unsupported on the Windows host" />
+}

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

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

package/src/index.ts

@@ -0,0 +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 { prefetch } from './prefetch'
+export type { AnimatedImageProps, PrefetchOptions } from './props'

package/src/index.web.ts

@@ -0,0 +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 { prefetch } from './prefetch.web'
+export type { AnimatedImageProps, PrefetchOptions } from './props'

package/src/index.windows.ts

@@ -0,0 +1,5 @@
+// Windows barrel — explicit leaf imports keep @nativescript-community/
+// ui-image (iOS/Android only) out of the windows graph at the file boundary.
+export { AnimatedImage } from './AnimatedImage.windows.tsrx'
+export { prefetch } from './prefetch.windows'
+export type { AnimatedImageProps, PrefetchOptions } from './props'

package/src/native-elements.d.ts

@@ -0,0 +1,8 @@
+import { Img } from '@nativescript-community/ui-image'
+import type { Attributes } from '@nativescript-community/octane/intrinsics'
+
+declare module '@nativescript-community/octane/intrinsics' {
+	interface NativeScriptElements {
+		animatedimage: Attributes<typeof Img>
+	}
+}

package/src/prefetch-batch.ts

@@ -0,0 +1,55 @@
+/** VENDORED — identical copy in packages/image/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)
+		// Surviving workers stop dequeuing once a failure decides the result —
+		// only already-running warm() calls settle on their own.
+		let failed = false
+		for (let i = 0; i < active; i++) {
+			void (async () => {
+				while (!failed && next < urls.length) {
+					const url = urls[next++]
+					try {
+						if (!(await warm(url))) {
+							failed = true
+							resolve(false)
+							return
+						}
+					} catch {
+						failed = true
+						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.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/prefetch.windows.ts

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

package/src/props.ts

@@ -0,0 +1,34 @@
+export interface AnimatedImageProps {
+	className?: any
+	style?: any
+	id?: string
+	src: string
+	alt?: string
+	/** Content fit — same grammar as core Image. Web maps to object-fit;
+	 *  ui-image (Fresco/SDWebImage) accepts the same values. */
+	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

@@ -0,0 +1,16 @@
+{
+  "version": 1,
+  "files": [
+    "AnimatedImage.d.ts",
+    "AnimatedImage.web.d.ts",
+    "escape-props.d.ts",
+    "escape-props.web.d.ts",
+    "index.d.ts",
+    "index.web.d.ts",
+    "native-elements.d.ts",
+    "prefetch-batch.d.ts",
+    "prefetch.d.ts",
+    "prefetch.web.d.ts",
+    "props.d.ts"
+  ]
+}

package/types/generated/AnimatedImage.d.ts

@@ -0,0 +1,6 @@
+import type { AnimatedImageProps } from './props.js';
+/**  AnimatedImage — GIF/animated-webp decode + autoplay via ui-image. `src`
+ *  takes the Img grammar: remote URL, res://name, ~/bundle path, file path.
+ *  There is intentionally no play/pause prop — <img> can't pause on web, so
+ *  the shared contract is always-playing. */
+export declare function AnimatedImage(props: AnimatedImageProps): unknown;

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

@@ -0,0 +1,5 @@
+/** @jsxImportSource octane */
+import type { AnimatedImageProps } from './props.js';
+/**  AnimatedImage — a plain <img>; browsers animate GIF/webp natively.
+ *  `stretch` maps to object-fit. */
+export declare function AnimatedImage(props: AnimatedImageProps): import("octane/jsx-runtime").JSX.Element;

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

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

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

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

package/types/generated/native-elements.d.ts

@@ -0,0 +1,8 @@
+import { Img } from '@nativescript-community/ui-image'
+import type { Attributes } from '@nativescript-community/octane/intrinsics'
+
+declare module '@nativescript-community/octane/intrinsics' {
+	interface NativeScriptElements {
+		animatedimage: Attributes<typeof Img>
+	}
+}

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

@@ -0,0 +1,10 @@
+/** VENDORED — identical copy in packages/image/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

@@ -0,0 +1,33 @@
+export interface AnimatedImageProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    src: string;
+    alt?: string;
+    /** Content fit — same grammar as core Image. Web maps to object-fit;
+     *  ui-image (Fresco/SDWebImage) accepts the same values. */
+    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

@@ -0,0 +1,8 @@
+import type { AnimatedImageProps, PrefetchOptions } 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>