@octane-xplat/image 0.0.1 → 0.11.0

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,124 @@
+# `@octane-xplat/image`
+
+```sh
+pnpm add @octane-xplat/image
+```
+
+Cached remote/local images for Octane xplat apps: a plain `<img>` on web and
+[`@nativescript-community/ui-image`](https://github.com/nativescript-community/ui-image)
+v5 on native — **Glide + okhttp3 on Android** (sized LRU memory cache, bitmap
+pool, disk cache, decode-to-view-size) and **SDWebImage on iOS**. This is the
+fix for the core `image`'s 5 MB `LruCache`, which evicts visible images
+mid-scroll and re-decodes them.
+
+**Recommended image path for apps with native targets.** `Image` is a drop-in
+for `@octane-xplat/ui`'s `Image` — the same name and the same prop contract
+(`src` incl. `ImageSourceLike[]` multi-source, `alt`, `placeholder`,
+`recyclingKey`, `contentFit`, `contentPosition`, layout-child props,
+`ios`/`android`/`web` bags). Switching engines is an import-path change:
+
+```tsx
+import { Image } from '@octane-xplat/image' // was '@octane-xplat/ui'
+```
+
+plus the engine's own knobs on top:
+
+```tsx
+import { Image, initializeImageCache, prefetch } from '@octane-xplat/image'
+
+// Optional, app entry: size the memory cache before the first render.
+initializeImageCache({ memoryCacheScreens: 2 })
+
+;<Image
+	src="https://example.com/photo.jpg"
+	alt="Trailhead"
+	contentFit="cover" // 'cover' | 'contain' | 'fill' | 'none' | 'scale-down'
+	placeholder="blurhash:LEHV6nWB2yk8pyo0adR*.7kCMdnj" // or res://, ~/, file, data:
+	cachePolicy="memory-disk" // or 'none' to bypass both caches (native)
+	failureImage="~/failed.png" // shown on load failure (native)
+	headers={{ Authorization: 'Bearer …' }} // extra request headers (native)
+	decodeWidth={600} // explicit decode bounds in device px; default = view size (native)
+	onLoad={(e) => console.log(e.width, e.height, e.source)} // 'network'|'memory'|'disk'|'local' (native)
+	onError={(e) => console.warn(e.error)}
+/>
+
+// Warm the disk cache ahead of a feed scroll (bytes only — decode at
+// display). One URL or a batch; resolves false if any URL fails.
+await prefetch('https://example.com/next.jpg')
+await prefetch(feed.map((post) => post.imageUrl), {
+	headers: { Authorization: 'Bearer …' }, // Android only — see below
+	concurrency: 5, // max parallel fetches (default)
+})
+```
+
+`onLoad`'s `source` field reports which cache level served the image
+(`'memory'` / `'disk'` / `'network'` / `'local'`) — the cheapest way to prove
+the cache is doing its job.
+
+Cache functions: `prefetch`, `evictImage`, `clearImageCaches`,
+`isImageCached`, `initializeImageCache` — the same contract
+`@octane-xplat/gif`'s `prefetch` carries. On web they degrade honestly:
+`prefetch` warms the browser HTTP cache through a throwaway `<img>` per URL,
+awaited until the response lands (resolves `false` if any URL fails); the
+rest are documented no-ops, and macOS `prefetch` resolves `false` since the
+AppKit host has no image pipeline.
+
+`prefetch` options: `headers` forwards request headers to the engine —
+honored on Android and iOS with the framework patch —
+and ignored on web, where a plain `<img>` cannot send custom headers.
+`concurrency` caps parallel fetches JS-side (default 5).
+
+iOS parity note: `ui-image` 5.x dropped the 4.x wiring that let prefetch honor
+its cache level and forward request `headers`. The framework patch set
+(`@nativescript-community__ui-image@5.0.17.patch`, applied automatically via
+`xplat patches apply` / `@octane-xplat/patches`) restores both — a disk prefetch
+writes encoded bytes to disk without decoding or warming memory (matching
+Android's Glide `downloadOnly`), a memory prefetch stays off disk, and a
+prefetch carrying `headers` sends them on iOS the same as Android.
+
+`isImageCached` takes one URL or a list and always resolves a `Record` keyed by URL — the RN `queryCache`
+shape:
+
+```ts
+const states = await isImageCached([
+	'https://example.com/a.jpg',
+	'https://example.com/b.jpg',
+])
+// states['https://example.com/a.jpg'] === 'memory' | 'disk' | 'none'
+```
+
+On iOS the cache key includes the decode bounds a display load used, so
+probe with the same `decodeWidth`/`decodeHeight` to match it:
+
+```ts
+await isImageCached(url, { decodeWidth: 600, decodeHeight: 400 })
+```
+
+Android caveat: the plugin's probe can't see Glide's active resources, so a
+bitmap still on screen may report `'none'` — treat `'none'` as "not provably
+cached", not "absent".
+
+## Divergences from core `Image`
+
+- **No SVG sources** — Glide/SDWebImage don't decode SVG. Keep core `Image`
+  for `svg` markup/data URIs/`.svg` URLs.
+- **`cachePolicy` has only two honest values.** The plugin exposes a single
+  all-off switch (`noCache` → Glide `skipMemoryCache` +
+  `DiskCacheStrategy.NONE`, SDWebImage `FromLoaderOnly`), so
+  `'memory'`/`'disk'` splits are not representable — only `'memory-disk'`
+  (default) and `'none'`.
+- **`decoding='sync'` is not honorably supported.** Glide/SDWebImage have no
+  synchronous decode mode — the ui-image plugin's `loadMode` prop is
+  registered but never read — so 'sync' degrades to the async default with
+  a console warning. If synchronous decode is a hard requirement, use core
+  `Image` (NS `loadMode` honors it for file/resource/data srcs). On web the
+  prop maps 1:1 to the HTML `decoding` attribute, as it does on core.
+- Engine extras (`failureImage`, `headers`, `decodeWidth`, `decodeHeight`,
+  `progressive`, `fadeDuration`, `cachePolicy`) are native-only and ignored on
+  web.
+- macOS renders through the same AppKit `<image>` path as core `Image` — no
+  engine there; cache helpers resolve as no-ops.
+
+Per-target limits are recorded in
+[known limits](../../docs/verify/known-limits.md). Exercised by
+[`CachedImageDemo`](../demos/src/CachedImageDemo.tsrx).

package/dist/native/Image.tsrx.js

@@ -0,0 +1,264 @@
+import { hashToPngBase64 } from "./hash-image.js";
+import { contentFitToStretch, needsContentRect, resolveContentFit, resolveContentPosition } from "./image-content.js";
+import { createImageBinding } from "./image-binding.js";
+import { defineUniversalComponent, hookSlots, registerElement, universalIf, universalPlan, universalProps, universalValue, useMemo, useRef } from "@nativescript-community/octane";
+import { ImageSource, Screen, isAndroid, isIOS } from "@nativescript/core";
+import { Img, initialize } from "@nativescript-community/ui-image";
+//#region src/Image.tsrx
+var _hs$ = /* @__PURE__ */ hookSlots(5);
+var _h$0 = /* @__PURE__ */ Symbol(_hs$);
+var _h$1 = /* @__PURE__ */ Symbol(_hs$ + 1);
+var _h$2 = /* @__PURE__ */ Symbol(_hs$ + 2);
+var _h$3 = /* @__PURE__ */ Symbol(_hs$ + 3);
+var _h$4 = /* @__PURE__ */ Symbol(_hs$ + 4);
+var __octaneUniversalPlan0 = universalPlan("nativescript", {
+	"kind": "host",
+	"type": "absolutelayout",
+	"propsSlot": 0,
+	"children": [{
+		"kind": "host",
+		"type": "cachedimage",
+		"props": { "stretch": "fill" },
+		"bindings": [
+			["ref", 1],
+			["failureImageUri", 2],
+			["headers", 3],
+			["noCache", 4],
+			["progressiveRenderingEnabled", 5],
+			["fadeDuration", 6],
+			["accessibilityLabel", 7]
+		]
+	}]
+});
+var __octaneUniversalPlan1 = universalPlan("nativescript", {
+	"kind": "host",
+	"type": "cachedimage",
+	"propsSlot": 0
+});
+var __octaneUniversalPlan2 = universalPlan("nativescript", {
+	"kind": "slot",
+	"slot": 0
+});
+registerElement("cachedimage", Img);
+var syncDecodeWarned = false;
+var engineStarted = false;
+function ensureEngine() {
+	if (!engineStarted) {
+		initialize();
+		engineStarted = true;
+	}
+}
+var LAYOUT_KEYS = [
+	"row",
+	"col",
+	"rowSpan",
+	"colSpan",
+	"dock",
+	"left",
+	"top",
+	"flexGrow",
+	"flexShrink",
+	"alignSelf",
+	"order"
+];
+function layoutChildAttrs(props) {
+	const result = {};
+	for (const key of LAYOUT_KEYS) if (props[key] !== void 0) result[key] = props[key];
+	return result;
+}
+function applyEscapeProps(view, props) {
+	const bag = isIOS ? props.ios : isAndroid ? props.android : void 0;
+	if (bag) Object.assign(view, bag);
+}
+function resolveSrc(src) {
+	const comma = src.indexOf(",");
+	if (src.startsWith("data:") && comma > 0 && src.slice(0, comma).endsWith(";base64")) return ImageSource.fromBase64Sync(src.slice(comma + 1));
+	return src;
+}
+function placeholderValue(placeholder) {
+	const png = hashToPngBase64(placeholder);
+	if (png) return ImageSource.fromBase64Sync(png);
+	if (/^https?:\/\//.test(placeholder)) return null;
+	return resolveSrc(placeholder);
+}
+var Image = defineUniversalComponent("nativescript", function Image(props) {
+	ensureEngine();
+	if (props.decoding === "sync" && !syncDecodeWarned) {
+		syncDecodeWarned = true;
+		console.warn("[octane-xplat] Image: decoding='sync' is not supported by the Glide/SDWebImage engine — decode stays async.");
+	}
+	const latest = useRef(props, _h$0);
+	latest.current = props;
+	const fit = resolveContentFit(props.contentFit);
+	const position = resolveContentPosition(props.contentPosition);
+	const computed = needsContentRect(fit, position);
+	const imageRef = useRef(null, _h$1);
+	const hostRef = useRef(null, _h$2);
+	const binding = useMemo(() => createImageBinding({
+		getFit: () => resolveContentFit(latest.current.contentFit),
+		getPosition: () => resolveContentPosition(latest.current.contentPosition),
+		getSrc: () => {
+			const src = latest.current.src;
+			return Array.isArray(src) ? {
+				source: null,
+				sources: src
+			} : {
+				source: resolveSrc(src),
+				sources: null
+			};
+		},
+		getDecodeBounds: () => ({
+			width: latest.current.decodeWidth,
+			height: latest.current.decodeHeight
+		}),
+		screenScale: () => Screen.mainScreen?.scale ?? 1
+	}), [], _h$3);
+	const boundRef = useRef({
+		key: props.recyclingKey,
+		src: props.src
+	}, _h$4);
+	const bound = boundRef.current;
+	boundRef.current = {
+		key: props.recyclingKey,
+		src: props.src
+	};
+	if (bound.key != null && props.recyclingKey != null && bound.key !== props.recyclingKey && bound.src !== props.src && imageRef.current) {
+		const nativeView = imageRef.current.nativeViewProtected;
+		if (nativeView) {
+			if (isIOS) nativeView.image = null;
+			else nativeView.setImageDrawable?.(null);
+		}
+	}
+	const attach = (view) => {
+		if (!view) return;
+		imageRef.current = view;
+		applyEscapeProps(view, props);
+		const ph = latest.current.placeholder;
+		if (ph) {
+			const resolved = placeholderValue(ph);
+			if (resolved != null) view.placeholderImageUri = resolved;
+		}
+		if (!view.__xplatImageWired) {
+			view.__xplatImageWired = true;
+			view.on(Img.finalImageSetEvent, (e) => {
+				const info = e.imageInfo;
+				const w = info?.getWidth?.() ?? info?.width ?? 0;
+				const h = info?.getHeight?.() ?? info?.height ?? 0;
+				binding.setIntrinsic(w, h);
+				latest.current.onLoad?.({
+					width: w,
+					height: h,
+					source: e.source
+				});
+			});
+			view.on(Img.failureEvent, (e) => {
+				latest.current.onError?.({ error: e.error });
+			});
+		}
+	};
+	return universalValue(__octaneUniversalPlan2, [universalIf(computed, () => {
+		return universalValue(__octaneUniversalPlan0, [
+			universalProps([
+				[
+					"set",
+					"ref",
+					(v) => {
+						hostRef.current = v;
+						if (v && isIOS && v.ios) v.ios.clipsToBounds = true;
+						if (v) binding.update(imageRef.current, v);
+					}
+				],
+				[
+					"set",
+					"id",
+					props.id
+				],
+				[
+					"set",
+					"className",
+					props.className
+				],
+				[
+					"set",
+					"style",
+					props.style
+				],
+				["spread", layoutChildAttrs(props)]
+			]),
+			(v) => {
+				attach(v);
+				if (v) binding.update(v, hostRef.current);
+			},
+			props.failureImage,
+			props.headers,
+			props.cachePolicy === "none",
+			props.progressive,
+			props.fadeDuration,
+			props.alt
+		]);
+	}, () => {
+		return universalValue(__octaneUniversalPlan1, [universalProps([
+			[
+				"set",
+				"ref",
+				(v) => {
+					attach(v);
+					if (v) binding.update(v, null);
+				}
+			],
+			[
+				"set",
+				"id",
+				props.id
+			],
+			[
+				"set",
+				"className",
+				props.className
+			],
+			[
+				"set",
+				"style",
+				props.style
+			],
+			["spread", layoutChildAttrs(props)],
+			[
+				"set",
+				"stretch",
+				contentFitToStretch(fit)
+			],
+			[
+				"set",
+				"failureImageUri",
+				props.failureImage
+			],
+			[
+				"set",
+				"headers",
+				props.headers
+			],
+			[
+				"set",
+				"noCache",
+				props.cachePolicy === "none"
+			],
+			[
+				"set",
+				"progressiveRenderingEnabled",
+				props.progressive
+			],
+			[
+				"set",
+				"fadeDuration",
+				props.fadeDuration
+			],
+			[
+				"set",
+				"accessibilityLabel",
+				props.alt
+			]
+		])]);
+	})]);
+}, { "module": "@nativescript-community/octane" });
+//#endregion
+export { Image };

package/dist/native/cache.js

@@ -0,0 +1,64 @@
+import { prefetchBatch } from "./prefetch-batch.js";
+import { ImagePipeline, getImagePipeline, initialize } from "@nativescript-community/ui-image";
+//#region src/cache.ts
+/** Apply engine-level cache configuration. Call from the app entry before the
+*  first <Image> renders — the plugin initializes Glide lazily, so sizing must
+*  arrive before the first view creates the engine. A later call is a no-op
+*  (the plugin guards on its own `initialized` flag). Native only. */
+function initializeImageCache(config) {
+	initialize({
+		memoryCacheSize: config?.memoryCacheSize,
+		memoryCacheScreens: config?.memoryCacheScreens,
+		usePersistentCacheKeyStore: config?.persistentCacheKeys,
+		globalSignatureKey: config?.globalSignatureKey
+	});
+	if (config?.iosComplexCacheEviction !== void 0) ImagePipeline.iosComplexCacheEviction = config.iosComplexCacheEviction;
+}
+/** Warm the disk cache without decoding — bytes are fetched and stored, decode
+*  cost stays at display time. One URL or an array; resolves `true` when all
+*  warmed, `false` if any URL fails or the pipeline is not up yet (e.g. called
+*  before app launch). Same contract as `@octane-xplat/gif`'s `prefetch`.
+*
+*  `options.headers` is forwarded on Android and iOS (via the framework
+*  patch). `options.concurrency` caps parallel fetches. */
+function prefetch(srcs, options) {
+	try {
+		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);
+	}
+}
+/** Remove `src` from memory and disk caches. */
+function evictImage(src) {
+	initialize();
+	return getImagePipeline().evictFromCache(src);
+}
+/** Drop every cached image (memory + disk). */
+function clearImageCaches() {
+	initialize();
+	return getImagePipeline().clearCaches();
+}
+/** Report which cache level currently holds each `src` — 'memory', 'disk',
+*  or 'none' (not cached / unknown). Accepts a single URL or a list; the
+*  result is always a `Record` keyed by URL (the RN `queryCache` shape).
+*  `options` repeats the display load's decode bounds: on iOS the cache key
+*  includes the transform context, so an image displayed with
+*  decodeWidth/decodeHeight only reports its level when the probe passes
+*  the same values. Android caveat: the plugin's probe cannot see Glide's
+*  active resources, so a bitmap still on screen may report 'none' —
+*  treat 'none' as "not provably cached", not "absent". */
+async function isImageCached(srcs, options) {
+	initialize();
+	const pipeline = getImagePipeline();
+	const list = typeof srcs === "string" ? [srcs] : srcs;
+	const states = {};
+	await Promise.all(list.map(async (src) => {
+		states[src] = pipeline.isInBitmapMemoryCache(src, options) ? "memory" : await pipeline.isInDiskCache(src, options) ? "disk" : "none";
+	}));
+	return states;
+}
+//#endregion
+export { clearImageCaches, evictImage, initializeImageCache, isImageCached, prefetch };