@symbiote-native/image 0.0.0-stage → 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 A. Prokopenko
+
+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

@@ -1,3 +1,46 @@
-# Temporary Holding Version
+# @symbiote-native/image
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[`expo-image`](https://docs.expo.dev/versions/latest/sdk/image/) for **every**
+[SymbioteNative](../../README.md) adapter: React, Vue, Svelte, Solid and Angular. An image view
+with caching, placeholders, transitions and SF Symbols, plus the cache and hash functions.
+
+## Install
+
+```bash
+npx @symbiote-native/cli new my-app --image   # new app
+npx @symbiote-native/cli add --image          # existing app
+```
+
+Manual: `npm install @symbiote-native/image`, then wire `expo-modules-autolinking` once per app.
+Never install `expo-image` or the `expo` meta-package yourself.
+
+## Usage
+
+```tsx
+import { Image, useImage } from '@symbiote-native/image/react';
+
+<Image
+  source="https://picsum.photos/400"
+  placeholder="blurhash:/L6PZfSi_.AyE_3t7t7R**0o#DgR4"
+  contentFit="cover"
+  transition={200}
+  style={{ width: 200, height: 200 }}
+/>;
+```
+
+The view takes the props of upstream's `Image`. The handle has `startAnimating`, `stopAnimating`,
+`lockResourceAsync`, `unlockResourceAsync` and `reloadAsync`, reached by a `ref` in React and Solid
+(`ref={fn}`), a template ref in Vue, `bind:this` in Svelte and a `@ViewChild` in Angular.
+
+`ImageBackground` is a view with an image filling it. `useImage` (`injectImage` in Angular) loads
+a native `ImageRef` and releases it with its owner. The static functions of upstream's `Image` are
+plain functions: `prefetchImages`, `clearMemoryCache`, `clearDiskCache`, `getCachePathAsync`,
+`writeToCacheAsync`, `readFromCacheAsync`, `configureCache`, `generateBlurhashAsync`,
+`generateThumbhashAsync`, `loadImageAsync`.
+
+Angular selectors are `ExpoImage` and `ExpoImageBackground`, `Image` and `ImageBackground` are
+tags of the adapter.
+
+## Not ported
+
+The web build, upstream's RSC snapshot tests and the `expo-observe` integration.

package/build/angular/image/index.d.ts

@@ -0,0 +1,20 @@
+import { NativeViewBase } from '@symbiote-native/angular';
+import type { IDescriptor } from '@symbiote-native/components';
+import type { IStyleProp } from '@symbiote-native/engine';
+import type { IImageStyle, IImageViewProps } from '../../core';
+declare const IMAGE_INPUTS: readonly ["source", "placeholder", "contentFit", "placeholderContentFit", "contentPosition", "transition", "blurRadius", "tintColor", "priority", "loading", "cachePolicy", "responsivePolicy", "recyclingKey", "autoplay", "sfEffect", "onLoadStart", "onLoad", "onProgress", "onError", "onLoadEnd", "onDisplay", "defaultSource", "loadingIndicatorSource", "resizeMode", "fadeDuration", "alt", "enableLiveTextInteraction", "allowDownscaling", "decodeFormat", "useAppleWebpCodec", "enforceEarlyResizing", "preferHighDynamicRange", "draggable"];
+export interface ExpoImage extends Partial<Pick<IImageViewProps, (typeof IMAGE_INPUTS)[number]>> {
+}
+/** Angular twin of `expo-image`'s `Image`, `Image` itself is a primitive tag of the adapter */
+export declare class ExpoImage extends NativeViewBase {
+    style?: IStyleProp<IImageStyle>;
+    private readonly view;
+    readonly startAnimating: () => Promise<void>;
+    readonly stopAnimating: () => Promise<void>;
+    readonly lockResourceAsync: () => Promise<void>;
+    readonly unlockResourceAsync: () => Promise<void>;
+    readonly reloadAsync: () => Promise<void>;
+    protected readonly propNames: readonly ["source", "placeholder", "contentFit", "placeholderContentFit", "contentPosition", "transition", "blurRadius", "tintColor", "priority", "loading", "cachePolicy", "responsivePolicy", "recyclingKey", "autoplay", "sfEffect", "onLoadStart", "onLoad", "onProgress", "onError", "onLoadEnd", "onDisplay", "defaultSource", "loadingIndicatorSource", "resizeMode", "fadeDuration", "alt", "enableLiveTextInteraction", "allowDownscaling", "decodeFormat", "useAppleWebpCodec", "enforceEarlyResizing", "preferHighDynamicRange", "draggable"];
+    protected renderView(props: object): IDescriptor | null;
+}
+export {};

package/build/angular/image/index.js

@@ -0,0 +1,113 @@
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { DescriptorOutlet, NativeViewBase } from '@symbiote-native/angular';
+import { createImageView } from '../../core/index.js';
+// One list is the inputs of the component and the props it hands to the native view
+const IMAGE_INPUTS = [
+    'source',
+    'placeholder',
+    'contentFit',
+    'placeholderContentFit',
+    'contentPosition',
+    'transition',
+    'blurRadius',
+    'tintColor',
+    'priority',
+    'loading',
+    'cachePolicy',
+    'responsivePolicy',
+    'recyclingKey',
+    'autoplay',
+    'sfEffect',
+    'onLoadStart',
+    'onLoad',
+    'onProgress',
+    'onError',
+    'onLoadEnd',
+    'onDisplay',
+    'defaultSource',
+    'loadingIndicatorSource',
+    'resizeMode',
+    'fadeDuration',
+    'alt',
+    'enableLiveTextInteraction',
+    'allowDownscaling',
+    'decodeFormat',
+    'useAppleWebpCodec',
+    'enforceEarlyResizing',
+    'preferHighDynamicRange',
+    'draggable',
+];
+/** Angular twin of `expo-image`'s `Image`, `Image` itself is a primitive tag of the adapter */
+let ExpoImage = (() => {
+    let _classDecorators = [Component({
+            selector: 'ExpoImage',
+            standalone: true,
+            imports: [DescriptorOutlet],
+            inputs: [...IMAGE_INPUTS],
+            changeDetection: ChangeDetectionStrategy.OnPush,
+            template: `@if (descriptor; as node) {
+    <symbiote-descriptor-outlet [node]="node" />
+  }`,
+        })];
+    let _classDescriptor;
+    let _classExtraInitializers = [];
+    let _classThis;
+    let _classSuper = NativeViewBase;
+    var ExpoImage = class extends _classSuper {
+        static { _classThis = this; }
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+            __esDecorate(null, _classDescriptor = { value: _classThis }, _classDecorators, { kind: "class", name: _classThis.name, metadata: _metadata }, null, _classExtraInitializers);
+            ExpoImage = _classThis = _classDescriptor.value;
+            if (_metadata) Object.defineProperty(_classThis, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+            __runInitializers(_classThis, _classExtraInitializers);
+        }
+        view = createImageView(() => this.hostNode());
+        // The functions of the view are members of the component, a `@ViewChild` reaches them
+        startAnimating = this.view.handle.startAnimating;
+        stopAnimating = this.view.handle.stopAnimating;
+        lockResourceAsync = this.view.handle.lockResourceAsync;
+        unlockResourceAsync = this.view.handle.unlockResourceAsync;
+        reloadAsync = this.view.handle.reloadAsync;
+        propNames = IMAGE_INPUTS;
+        renderView(props) {
+            return this.view.render(props);
+        }
+    };
+    return ExpoImage = _classThis;
+})();
+export { ExpoImage };

package/build/angular/image-background/index.d.ts

@@ -0,0 +1,14 @@
+import { NativeViewBase } from '@symbiote-native/angular';
+import type { IDescriptor } from '@symbiote-native/components';
+import type { IStyleProp } from '@symbiote-native/engine';
+import type { IImageBackgroundProps, IImageStyle } from '../../core';
+declare const IMAGE_BACKGROUND_INPUTS: readonly ["source", "placeholder", "contentFit", "placeholderContentFit", "contentPosition", "transition", "blurRadius", "tintColor", "priority", "loading", "cachePolicy", "responsivePolicy", "recyclingKey", "autoplay", "sfEffect", "onLoadStart", "onLoad", "onProgress", "onError", "onLoadEnd", "onDisplay", "defaultSource", "loadingIndicatorSource", "resizeMode", "fadeDuration", "alt", "enableLiveTextInteraction", "allowDownscaling", "decodeFormat", "useAppleWebpCodec", "enforceEarlyResizing", "preferHighDynamicRange", "draggable", "imageStyle"];
+export interface ExpoImageBackground extends Partial<Pick<IImageBackgroundProps, (typeof IMAGE_BACKGROUND_INPUTS)[number]>> {
+}
+/** Angular twin of `expo-image`'s `ImageBackground`, the content paints over the image */
+export declare class ExpoImageBackground extends NativeViewBase {
+    style?: IStyleProp<IImageStyle>;
+    protected readonly propNames: readonly ["source", "placeholder", "contentFit", "placeholderContentFit", "contentPosition", "transition", "blurRadius", "tintColor", "priority", "loading", "cachePolicy", "responsivePolicy", "recyclingKey", "autoplay", "sfEffect", "onLoadStart", "onLoad", "onProgress", "onError", "onLoadEnd", "onDisplay", "defaultSource", "loadingIndicatorSource", "resizeMode", "fadeDuration", "alt", "enableLiveTextInteraction", "allowDownscaling", "decodeFormat", "useAppleWebpCodec", "enforceEarlyResizing", "preferHighDynamicRange", "draggable", "imageStyle"];
+    protected renderView(props: object): IDescriptor;
+}
+export {};

package/build/angular/image-background/index.js

@@ -0,0 +1,107 @@
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { DescriptorHost, NativeViewBase } from '@symbiote-native/angular';
+import { renderImageBackground } from '../../core/index.js';
+// One list is the inputs of the component and the props it hands to the image
+const IMAGE_BACKGROUND_INPUTS = [
+    'source',
+    'placeholder',
+    'contentFit',
+    'placeholderContentFit',
+    'contentPosition',
+    'transition',
+    'blurRadius',
+    'tintColor',
+    'priority',
+    'loading',
+    'cachePolicy',
+    'responsivePolicy',
+    'recyclingKey',
+    'autoplay',
+    'sfEffect',
+    'onLoadStart',
+    'onLoad',
+    'onProgress',
+    'onError',
+    'onLoadEnd',
+    'onDisplay',
+    'defaultSource',
+    'loadingIndicatorSource',
+    'resizeMode',
+    'fadeDuration',
+    'alt',
+    'enableLiveTextInteraction',
+    'allowDownscaling',
+    'decodeFormat',
+    'useAppleWebpCodec',
+    'enforceEarlyResizing',
+    'preferHighDynamicRange',
+    'draggable',
+    'imageStyle',
+];
+/** Angular twin of `expo-image`'s `ImageBackground`, the content paints over the image */
+let ExpoImageBackground = (() => {
+    let _classDecorators = [Component({
+            selector: 'ExpoImageBackground',
+            standalone: true,
+            imports: [DescriptorHost],
+            inputs: [...IMAGE_BACKGROUND_INPUTS],
+            changeDetection: ChangeDetectionStrategy.OnPush,
+            template: `@if (descriptor; as node) {
+    <symbiote-descriptor-host [node]="node"><ng-content /></symbiote-descriptor-host>
+  }`,
+        })];
+    let _classDescriptor;
+    let _classExtraInitializers = [];
+    let _classThis;
+    let _classSuper = NativeViewBase;
+    var ExpoImageBackground = class extends _classSuper {
+        static { _classThis = this; }
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+            __esDecorate(null, _classDescriptor = { value: _classThis }, _classDecorators, { kind: "class", name: _classThis.name, metadata: _metadata }, null, _classExtraInitializers);
+            ExpoImageBackground = _classThis = _classDescriptor.value;
+            if (_metadata) Object.defineProperty(_classThis, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+            __runInitializers(_classThis, _classExtraInitializers);
+        }
+        propNames = IMAGE_BACKGROUND_INPUTS;
+        renderView(props) {
+            return renderImageBackground(props);
+        }
+    };
+    return ExpoImageBackground = _classThis;
+})();
+export { ExpoImageBackground };

package/build/angular/index.d.ts

@@ -0,0 +1,4 @@
+export { ExpoImage } from './image';
+export { ExpoImageBackground } from './image-background';
+export { injectImage } from './inject-image';
+export * from '../core';

package/build/angular/index.js

@@ -0,0 +1,6 @@
+// @symbiote-native/image/angular: the image view, its cache and hash functions on a shared core
+// The selectors are `ExpoImage*`, `Image` and `ImageBackground` are tags of the adapter
+export { ExpoImage } from './image/index.js';
+export { ExpoImageBackground } from './image-background/index.js';
+export { injectImage } from './inject-image.js';
+export * from '../core/index.js';

package/build/angular/inject-image.d.ts

@@ -0,0 +1,8 @@
+import type { Signal } from '@angular/core';
+import type { IImageLoadOptions, IImageSource, ImageRef } from '../core';
+/**
+ * Angular twin of `useImage`, `null` until the first image has loaded
+ *
+ * It loads again when the uri of the source or a signal read by `dependencies` changes
+ */
+export declare function injectImage(source: () => IImageSource | string | number, options?: () => IImageLoadOptions, dependencies?: () => unknown[]): Signal<ImageRef | null>;

package/build/angular/inject-image.js

@@ -0,0 +1,20 @@
+import { computed, effect, signal, untracked } from '@angular/core';
+import { createImageRefLoader, resolveSource } from '../core/index.js';
+/**
+ * Angular twin of `useImage`, `null` until the first image has loaded
+ *
+ * It loads again when the uri of the source or a signal read by `dependencies` changes
+ */
+export function injectImage(source, options = () => ({}), dependencies = () => []) {
+    const image = signal(null);
+    const key = computed(() => resolveSource(source())?.uri);
+    effect(onCleanup => {
+        // Read so the effect tracks them, the source itself is not a trigger
+        key();
+        dependencies();
+        const loader = createImageRefLoader(loaded => image.set(loaded), options);
+        untracked(() => loader.load(source()));
+        onCleanup(loader.cancel);
+    });
+    return image.asReadonly();
+}

package/build/core/constants.d.ts

@@ -0,0 +1,3 @@
+export declare const IMAGE_MODULE_NAME = "ExpoImage";
+/** `sf:name` in a source string, the native side reads `sf:/name` */
+export declare const SF_SYMBOL_PREFIX = "sf:";

package/build/core/constants.js

@@ -0,0 +1,4 @@
+// Apart from `native-module`, which resolves the module on import: the view needs the name too
+export const IMAGE_MODULE_NAME = 'ExpoImage';
+/** `sf:name` in a source string, the native side reads `sf:/name` */
+export const SF_SYMBOL_PREFIX = 'sf:';

package/build/core/hash-strings.d.ts

@@ -0,0 +1,5 @@
+import type { IImageSource } from './types';
+/** `blurhash:/<hash>/<width>/<height>` or `<hash>/<width>/<height>` */
+export declare function resolveBlurhashString(str: string): IImageSource;
+/** `thumbhash:/<hash>` or `<hash>` */
+export declare function resolveThumbhashString(str: string): IImageSource;

package/build/core/hash-strings.js

@@ -0,0 +1,20 @@
+const DEFAULT_HASH_SIZE = 16;
+function hashToUri(type, hash) {
+    const encoded = encodeURI(hash).replace(/#/g, '%23').replace(/\?/g, '%3F');
+    return `${type}:/${encoded}`;
+}
+/** `blurhash:/<hash>/<width>/<height>` or `<hash>/<width>/<height>` */
+export function resolveBlurhashString(str) {
+    const [hash = '', width = '', height = ''] = str.replace(/^blurhash:\//, '').split('/');
+    return {
+        uri: hashToUri('blurhash', hash),
+        width: parseInt(width, 10) || DEFAULT_HASH_SIZE,
+        height: parseInt(height, 10) || DEFAULT_HASH_SIZE,
+    };
+}
+/** `thumbhash:/<hash>` or `<hash>` */
+export function resolveThumbhashString(str) {
+    // A slash at the start of the hash would break the uri path
+    const hash = str.replace(/^thumbhash:\//, '').replace(/\//g, '\\');
+    return { uri: hashToUri('thumbhash', hash) };
+}

package/build/core/image-api.d.ts

@@ -0,0 +1,18 @@
+import type { IImageCacheConfig, IImageLoadOptions, IImagePrefetchOptions, IImageSource, ImageRef } from './types';
+type IPrefetchOptions = IImagePrefetchOptions['cachePolicy'] | IImagePrefetchOptions;
+/** The caching policy as a string, or with request headers as an object */
+export declare function prefetchImages(urls: string | string[], options?: IPrefetchOptions): Promise<boolean>;
+export declare const clearMemoryCache: () => Promise<boolean>;
+export declare const clearDiskCache: () => Promise<boolean>;
+export declare const getCachePathAsync: (cacheKey: string) => Promise<string | null>;
+export declare const writeToCacheAsync: (source: string | ImageRef, cacheKey: string) => Promise<void>;
+export declare const readFromCacheAsync: (cacheKey: string) => Promise<ImageRef | null>;
+export declare const configureCache: (config: IImageCacheConfig) => void;
+export declare const generateBlurhashAsync: (source: string | ImageRef, numberOfComponents: [number, number] | {
+    width: number;
+    height: number;
+}) => Promise<string | null>;
+export declare const generateThumbhashAsync: (source: string | ImageRef) => Promise<string>;
+/** Loads the image into a native `ImageRef`, the caller releases it */
+export declare function loadImageAsync(source: IImageSource | string | number, options?: IImageLoadOptions): Promise<ImageRef>;
+export {};

package/build/core/image-api.js

@@ -0,0 +1,30 @@
+import { toNativeColor } from './native-style.js';
+import { expoImage } from './native-module.js';
+import { resolveSource } from './sources.js';
+const DEFAULT_CACHE_POLICY = 'memory-disk';
+/** The caching policy as a string, or with request headers as an object */
+export function prefetchImages(urls, options) {
+    const { cachePolicy = DEFAULT_CACHE_POLICY, headers } = typeof options === 'string' ? { cachePolicy: options } : (options ?? {});
+    return expoImage.prefetch(Array.isArray(urls) ? urls : [urls], cachePolicy, headers);
+}
+export const clearMemoryCache = () => expoImage.clearMemoryCache();
+export const clearDiskCache = () => expoImage.clearDiskCache();
+export const getCachePathAsync = (cacheKey) => expoImage.getCachePathAsync(cacheKey);
+export const writeToCacheAsync = (source, cacheKey) => expoImage.writeToCacheAsync(source, cacheKey);
+export const readFromCacheAsync = (cacheKey) => expoImage.readFromCacheAsync(cacheKey);
+export const configureCache = (config) => expoImage.configureCache(config);
+export const generateBlurhashAsync = (source, numberOfComponents) => expoImage.generateBlurhashAsync(source, numberOfComponents);
+export const generateThumbhashAsync = (source) => expoImage.generateThumbhashAsync(source);
+/** Loads the image into a native `ImageRef`, the caller releases it */
+export async function loadImageAsync(source, options = {}) {
+    const resolved = resolveSource(source);
+    if (!resolved) {
+        throw new Error('[expo-image]: the image source could not be resolved');
+    }
+    const { maxWidth, maxHeight, tintColor } = options;
+    return expoImage.loadAsync(resolved, {
+        maxWidth,
+        maxHeight,
+        tintColor: toNativeColor(tintColor),
+    });
+}

package/build/core/image-background.d.ts

@@ -0,0 +1,11 @@
+import type { IDescriptor } from '@symbiote-native/components';
+import type { IStyleProp } from '@symbiote-native/engine';
+import type { IImageStyle, IImageViewProps } from './types';
+export type IImageBackgroundProps = IImageViewProps & {
+    /** Style of the image itself, `style` goes to the wrapping view */
+    imageStyle?: IStyleProp<IImageStyle>;
+    /** Goes to the wrapping view, as `style` does */
+    className?: string;
+};
+/** A view with an image filling it, the children of the app go after this descriptor */
+export declare function renderImageBackground(props: IImageBackgroundProps): IDescriptor;

package/build/core/image-background.js

@@ -0,0 +1,26 @@
+import { el } from '@symbiote-native/components';
+import { createImageView } from './image-view.js';
+const CLASS_KEYS = new Set(['className', 'class']);
+function isClassEntry([key]) {
+    return CLASS_KEYS.has(key);
+}
+const ABSOLUTE_FILL = {
+    position: 'absolute',
+    left: 0,
+    right: 0,
+    top: 0,
+    bottom: 0,
+};
+// The background image has no handle, so nobody asks it for a host node
+const backgroundImage = createImageView(() => null);
+/** A view with an image filling it, the children of the app go after this descriptor */
+export function renderImageBackground(props) {
+    const { style, imageStyle, ...rest } = props;
+    const entries = Object.entries(rest);
+    const image = backgroundImage.render({
+        ...Object.fromEntries(entries.filter(entry => !isClassEntry(entry))),
+        style: [ABSOLUTE_FILL, imageStyle],
+    });
+    const viewClass = Object.fromEntries(entries.filter(isClassEntry));
+    return el('view', { style, ...viewClass }, image ? [image] : []);
+}

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

@@ -0,0 +1,20 @@
+import type { IImageLoadOptions, IImageSource } from './types';
+export type IImageLoaderConfig<TImage extends {
+    release(): void;
+}> = {
+    load(source: IImageSource | string | number, options: IImageLoadOptions): Promise<TImage>;
+    /** Called with each image that finished loading */
+    onImage(image: TImage): void;
+    /** Read at the time of a failure, so the latest callback wins */
+    getOptions(): IImageLoadOptions;
+};
+export type IImageLoader = {
+    /** Starts a load and drops the result of the one before */
+    load(source: IImageSource | string | number): void;
+    /** Drops a load in flight and releases the image loaded last */
+    cancel(): void;
+};
+/** What a `useImage` hook drives with its own lifecycle */
+export declare function createImageLoader<TImage extends {
+    release(): void;
+}>(config: IImageLoaderConfig<TImage>): IImageLoader;

package/build/core/image-loader.js

@@ -0,0 +1,42 @@
+/** What a `useImage` hook drives with its own lifecycle */
+export function createImageLoader(config) {
+    let token = 0;
+    let loaded = null;
+    function release() {
+        loaded?.release();
+        loaded = null;
+    }
+    function fail(source, error, retry) {
+        const { onError } = config.getOptions();
+        if (onError) {
+            onError(error instanceof Error ? error : new Error(String(error)), retry);
+            return;
+        }
+        console.error(`Loading an image from '${JSON.stringify(source)}' failed, use 'onError' to handle errors`);
+        console.error(error);
+    }
+    function load(source) {
+        release();
+        token += 1;
+        const mine = token;
+        config
+            .load(source, config.getOptions())
+            .then(image => {
+            if (mine !== token)
+                return;
+            loaded = image;
+            config.onImage(image);
+        })
+            .catch((error) => {
+            if (mine === token)
+                fail(source, error, () => load(source));
+        });
+    }
+    return {
+        load,
+        cancel: () => {
+            token += 1;
+            release();
+        },
+    };
+}

package/build/core/image-ref-loader.d.ts

@@ -0,0 +1,4 @@
+import type { IImageLoader } from './image-loader';
+import type { IImageLoadOptions, ImageRef } from './types';
+/** The loader every `useImage` hook drives, `getOptions` is read at each load and failure */
+export declare function createImageRefLoader(onImage: (image: ImageRef) => void, getOptions: () => IImageLoadOptions): IImageLoader;

package/build/core/image-ref-loader.js

@@ -0,0 +1,10 @@
+import { loadImageAsync } from './image-api.js';
+import { createImageLoader } from './image-loader.js';
+/** The loader every `useImage` hook drives, `getOptions` is read at each load and failure */
+export function createImageRefLoader(onImage, getOptions) {
+    return createImageLoader({
+        load: loadImageAsync,
+        onImage,
+        getOptions,
+    });
+}

package/build/core/image-view-events.d.ts

@@ -0,0 +1,9 @@
+import type { ISymbioteEvent } from '@symbiote-native/engine';
+import type { IImageViewProps } from './types';
+/** The native payload sits in `nativeEvent`, callbacks get it as the event itself */
+export declare function toImageEvents(props: IImageViewProps): {
+    onLoadStart: () => void | undefined;
+    onLoad: (event: ISymbioteEvent) => void;
+    onProgress: (event: ISymbioteEvent) => void;
+    onError: (event: ISymbioteEvent) => void;
+};

package/build/core/image-view-events.js

@@ -0,0 +1,32 @@
+function field(value, key) {
+    return Reflect.get(Object(value), key);
+}
+function isLoad(value) {
+    return typeof field(value, 'cacheType') === 'string' && typeof field(value, 'source') === 'object';
+}
+function isProgress(value) {
+    return typeof field(value, 'loaded') === 'number' && typeof field(value, 'total') === 'number';
+}
+function isError(value) {
+    return typeof field(value, 'error') === 'string';
+}
+/** The native payload sits in `nativeEvent`, callbacks get it as the event itself */
+export function toImageEvents(props) {
+    return {
+        onLoadStart: () => props.onLoadStart?.(),
+        onLoad: (event) => {
+            if (isLoad(event.nativeEvent))
+                props.onLoad?.(event.nativeEvent);
+            props.onLoadEnd?.();
+        },
+        onProgress: (event) => {
+            if (isProgress(event.nativeEvent))
+                props.onProgress?.(event.nativeEvent);
+        },
+        onError: (event) => {
+            if (isError(event.nativeEvent))
+                props.onError?.(event.nativeEvent);
+            props.onLoadEnd?.();
+        },
+    };
+}

package/build/core/image-view.d.ts

@@ -0,0 +1,14 @@
+import type { IDescriptor } from '@symbiote-native/components';
+import type { ISymbioteNode } from '@symbiote-native/engine';
+import type { IImageViewHandle, IImageViewProps } from './types';
+export declare const imageViewName: () => string;
+export declare const ensureImageViewRegistered: () => boolean;
+export type IImageView = {
+    handle: IImageViewHandle;
+    /** `null` means the view cannot register and the caller renders nothing */
+    render(props: IImageViewProps): IDescriptor | null;
+};
+type IGetNode = () => ISymbioteNode | null | undefined;
+/** One per mounted view, `getNode` answers the host node once it exists */
+export declare function createImageView(getNode: IGetNode): IImageView;
+export {};