@octane-xplat/image 0.0.1 → 0.11.0

package/types/generated/Image.d.ts

@@ -0,0 +1,16 @@
+import type { ImageProps } from './props.js';
+/**  Image — ui-image `Img` (Glide/SDWebImage). Mirrors the core contract:
+ *  `src` takes the Img grammar (remote URL, res://name, ~/bundle path, file
+ *  path, data: URI) plus a resolution-qualified `ImageSourceLike[]` (closest
+ *  pixel count wins once the view has a real layout — the srcset model).
+ *  `contentFit` maps to stretch for the centered contain/cover/fill cases;
+ *  'none'/'scale-down'/positioned content take the computed path — the host
+ *  box is measured, the content rect computed, and a fill-stretched `Img`
+ *  laid out inside a clipped absolutelayout (same structure core uses).
+ *  `src` never goes through JSX: the binding holds it until first layout,
+ *  writes decodeWidth/decodeHeight in device px, then assigns — an eager src
+ *  decodes at full source resolution. SVG is unsupported — keep core `Image`
+ *  for those. `alt` maps to accessibilityLabel. `decoding` accepts the shared
+ *  vocabulary but 'sync' degrades to async with a warning — the engines have
+ *  no synchronous decode mode (see props.ts). */
+export declare function Image(props: ImageProps): unknown;

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

@@ -0,0 +1,12 @@
+import type { ImageProps } from './props.js';
+/**  Image — a plain <img>, mirroring the core contract: a source array becomes
+ *  a real `srcset` (browser owns selection); `contentFit`/`contentPosition`
+ *  map 1:1 to object-fit/object-position with 'cover'/'50% 50%' defaults;
+ *  `placeholder` rides the same element — the img keeps its last decoded
+ *  image while a hidden prefetch warms the final src, so placeholder → final
+ *  swaps in one view without a blank frame. Engine-only props (cachePolicy,
+ *  failureImage, headers, decodeWidth/decodeHeight, progressive,
+ *  fadeDuration) have no <img> equivalent and are ignored. onLoad fires
+ *  without `source` — the browser does not report which cache satisfied the
+ *  request. */
+export declare function Image(props: ImageProps): import("octane/jsx-runtime").JSX.Element;

package/types/generated/cache.d.ts

@@ -0,0 +1,28 @@
+import type { ImageCacheConfig, ImageCacheQueryOptions, ImageCacheState, PrefetchOptions } from './props.js';
+/** 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. */
+export declare function initializeImageCache(config?: ImageCacheConfig): void;
+/** 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. */
+export declare function prefetch(srcs: string | string[], options?: PrefetchOptions): Promise<boolean>;
+/** Remove `src` from memory and disk caches. */
+export declare function evictImage(src: string): Promise<boolean>;
+/** Drop every cached image (memory + disk). */
+export declare function clearImageCaches(): Promise<void>;
+/** 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". */
+export declare function isImageCached(srcs: string | readonly string[], options?: ImageCacheQueryOptions): Promise<Record<string, ImageCacheState>>;

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

@@ -0,0 +1,16 @@
+import type { ImageCacheConfig, ImageCacheQueryOptions, ImageCacheState, PrefetchOptions } from './props.js';
+/** No-op — the browser owns its HTTP cache; there is no sizing API. */
+export declare function initializeImageCache(_config?: ImageCacheConfig): void;
+/** Warm the browser HTTP cache by loading each `src` through a throwaway
+ *  <img> — the response must land (`load`/`error` awaited) before the promise
+ *  resolves. Decode still happens at display, matching the native
+ *  disk-prefetch contract. `options.headers` is ignored — an <img> request
+ *  cannot carry custom headers. Resolves `false` when any URL fails. */
+export declare function prefetch(srcs: string | string[], options?: PrefetchOptions): Promise<boolean>;
+/** No-op — browsers expose no per-URL cache eviction for <img>. */
+export declare function evictImage(_src: string): Promise<boolean>;
+/** No-op — browsers expose no cache clearing for <img>. */
+export declare function clearImageCaches(): Promise<void>;
+/** Always 'none' — the browser cache is not queryable. Returns the same
+ *  `Record` shape as native, keyed by each requested URL. */
+export declare function isImageCached(srcs: string | readonly string[], _options?: ImageCacheQueryOptions): Promise<Record<string, ImageCacheState>>;

package/types/generated/hash-image.d.ts

@@ -0,0 +1,14 @@
+/** VENDORED from packages/ui/src/hash-image.ts — keep in sync.
+ *  Placeholder-hash decoders shared by the Image leaves: `blurhash:` and
+ *  `thumbhash:` URIs decode to a PNG in pure JS so a placeholder is a real
+ *  image on every platform — ImageSource.fromBase64Sync on native, a
+ *  data:image/png URL on web. Decode sizes stay small (~32px); the view's
+ *  own fit/stretch scales the result, same as the final image.
+ *
+ *  blurhash decode is a port of the Wolt reference decoder (MIT);
+ *  thumbHashToRGBA and rgbaToPng are ports of Evan Wallace's thumbhash.js
+ *  (MIT), with the data-URL/btoa tail replaced by byte output so this file
+ *  carries no DOM or platform APIs. */
+export declare function isHashPlaceholder(src: string): boolean;
+/** `blurhash:<hash>` / `thumbhash:<base64>` → PNG bytes as base64, or null. */
+export declare function hashToPngBase64(src: string): string | null;

package/types/generated/image-binding.d.ts

@@ -0,0 +1,40 @@
+import type { ImageContentFit, ImageContentPositionObject, ImageSourceLike } from './props.js';
+/** View-sized decode + srcset selection + content-rect layout for the
+ *  ui-image `Img` leaf. Mirrors the core Image binding semantics
+ *  (packages/ui/src/image-sizing.ts + image-content-binding.ts):
+ *
+ *  `src` never goes through JSX — the binding holds it until the view's
+ *  first real layout, writes decodeWidth/decodeHeight in device pixels,
+ *  then assigns it. Without that hold the engine decodes at full source
+ *  resolution (the 5 MB-cache jank this package exists to fix is half
+ *  cache size and half oversized decodes — study L1+L2). A later resize
+ *  re-issues at the new size, except 'fill'/'none' fits where the decode
+ *  can't improve. 'none' never downsamples — its contract is source pixels.
+ *
+ *  `update` must be idempotent: ref callbacks re-fire on every render, and
+ *  same view + same src + same size is a no-op. */
+export declare function createImageBinding(options: {
+    getFit: () => ImageContentFit;
+    getPosition: () => ImageContentPositionObject;
+    getSrc: () => {
+        source: any;
+        sources: ImageSourceLike[] | null;
+    };
+    /** Explicit decode bounds — the caller's decodeWidth/decodeHeight props;
+     *  when set they win over the measured view size. */
+    getDecodeBounds: () => {
+        width?: number;
+        height?: number;
+    };
+    /** Device-pixel scale (Screen.mainScreen.scale) — injected so this
+     *  module stays platform-free. */
+    screenScale: () => number;
+}): {
+    /** Called from the ref callbacks — image view first, then the computed
+     *  path's wrapper host. Refreshes the pending src from props and
+     *  evaluates; idempotent. */
+    update(imageView: any, hostView: any): void;
+    /** Engine set the final bitmap — record intrinsic size for the
+     *  content-rect path. */
+    setIntrinsic(widthPx: number, heightPx: number): void;
+};

package/types/generated/image-content.d.ts

@@ -0,0 +1,57 @@
+import type { ImageContentFit, ImageContentPosition, ImageContentPositionObject, ImageContentPositionValue, ImageSourceLike } from './props.js';
+/** VENDORED from packages/ui/src/image-content.ts — keep in sync.
+ *  Shared `contentFit`/`contentPosition` + multi-source math for `Image` —
+ *  pure functions used by every leaf (docs/notes/expo-image-study.md L7/L8).
+ *  Semantics mirror CSS `object-fit`/`object-position`, which is also
+ *  expo-image's contract: the leaves compute the drawn-content rect
+ *  themselves instead of delegating to platform scaleType/contentMode,
+ *  so all platforms get the same answer.
+ *
+ *  The default fit is 'cover' everywhere (the expo/RN default). Today's
+ *  platform defaults disagree — web <img> is 'fill' and NS stretch is
+ *  'aspectFit' — so an un-propped Image was silently divergent. */
+export declare const DEFAULT_CONTENT_FIT: ImageContentFit;
+export declare function resolveContentFit(fit?: ImageContentFit): ImageContentFit;
+export declare function resolveContentPosition(position?: ImageContentPosition): ImageContentPositionObject;
+/** Offset of the drawn content's start edge inside the view along one axis.
+ *  expo-image `calcTranslation`: percentages run over the free space
+ *  (view − content), absolute dips measure from the named edge, and the
+ *  reverse edge (right/bottom) counts back from the far side. */
+export declare function contentAxisOffset(viewSize: number, contentSize: number, start: ImageContentPositionValue | undefined, end: ImageContentPositionValue | undefined): number;
+export declare function isCenteredContentPosition(position: ImageContentPositionObject): boolean;
+/** The rect the bitmap occupies inside the view box, in the same units the
+ *  caller measures with (native: dips; web: CSS px via object-fit anyway —
+ *  only the native leaf calls this). Every length unit is dips except the
+ *  intrinsic size, which the leaf must supply in dips too. */
+export declare function contentRect(fit: ImageContentFit, position: ImageContentPositionObject, viewWidth: number, viewHeight: number, imageWidth: number, imageHeight: number): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/** True when no platform stretch/scaleType can express the request and the
+ *  leaf must measure + lay out the image itself: 'none' (iOS maps NS
+ *  stretch='none' to TopLeft, not CSS centered), 'scale-down' (needs the
+ *  intrinsic-vs-view compare), or any non-center position. 'fill' is
+ *  exempt — its rect is always the whole box, so position can't matter. */
+export declare function needsContentRect(fit: ImageContentFit, position: ImageContentPositionObject): boolean;
+/** NS `stretch` for the fast path — only reached for fits the platform
+ *  vocabulary expresses identically (contain/cover/fill centered). */
+export declare function contentFitToStretch(fit: ImageContentFit): 'aspectFit' | 'aspectFill' | 'fill';
+/** L8 — expo `getBestSource`: the source whose declared pixel count
+ *  (`width·height·scale²`, dips × density) is closest to the view's pixel
+ *  count. Needs a real measured size; one source or no size picks nothing
+ *  to decide. Unsized sources score worst and are skipped when any sized
+ *  candidate exists. */
+export declare function bestImageSource(sources: readonly ImageSourceLike[], viewWidth: number, viewHeight: number, screenScale: number): ImageSourceLike | null;
+/** Browser `object-position` for a resolved position — mirrors expo-image
+ *  web's `getObjectPositionFromContentPositionObject`. */
+export declare function objectPositionCSSValue(position: ImageContentPositionObject): string;
+/** Browser `srcset` candidates for a source array: `w` descriptors (real
+ *  file px = width·scale) when every source is sized, `x` descriptors when
+ *  every source only carries density. `src` falls back to the largest
+ *  declared pixel count — guaranteed coverage where srcset is ignored. */
+export declare function imageSrcSet(sources: readonly ImageSourceLike[]): {
+    src: string;
+    srcSet?: string;
+};

package/types/generated/index.d.ts

@@ -0,0 +1,3 @@
+export { Image } from './Image.js';
+export { clearImageCaches, evictImage, initializeImageCache, isImageCached, prefetch, } from './cache.js';
+export type { ImageCacheConfig, ImageCachePolicy, ImageCacheQueryOptions, ImageCacheState, ImageContentFit, ImageContentPosition, ImageContentPositionObject, ImageContentPositionString, ImageContentPositionValue, ImageDecoding, ImageErrorEvent, ImageLoadEvent, ImageProps, PrefetchOptions, ImageSourceLike, } from './props.js';

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

@@ -0,0 +1,3 @@
+export { Image } from './Image.web.js';
+export { clearImageCaches, evictImage, initializeImageCache, isImageCached, prefetch, } from './cache.web.js';
+export type { ImageCacheConfig, ImageCachePolicy, ImageCacheQueryOptions, ImageCacheState, ImageContentFit, ImageContentPosition, ImageContentPositionObject, ImageContentPositionString, ImageContentPositionValue, ImageDecoding, ImageErrorEvent, ImageLoadEvent, ImageProps, PrefetchOptions, ImageSourceLike, } 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/props.d.ts

@@ -0,0 +1,99 @@
+import type { ImageProps as CoreImageProps } from '@octane-xplat/ui';
+export type { ImageContentFit, ImageContentPosition, ImageContentPositionObject, ImageContentPositionString, ImageContentPositionValue, ImageDecoding, ImageSourceLike, } from '@octane-xplat/ui';
+/** How the engine's caches participate in a load. The plugin exposes a single
+ *  all-off switch (`noCache` → Glide `skipMemoryCache` + `DiskCacheStrategy.NONE`
+ *  on Android, `SDWebImageOptions.FromLoaderOnly` on iOS), so the only honest
+ *  non-default value is 'none'. 'memory'/'disk' splits are not representable
+ *  through the plugin's request options today. Ignored on web — browsers own
+ *  their HTTP cache. */
+export type ImageCachePolicy = 'memory-disk' | 'none';
+export interface ImageLoadEvent {
+    /** Decoded bitmap size in pixels. */
+    width: number;
+    height: number;
+    /** Where the engine served the image from. Absent on web — the browser
+     *  does not report which cache (if any) satisfied an <img>. */
+    source?: 'network' | 'memory' | 'disk' | 'local';
+}
+export interface ImageErrorEvent {
+    error: Error;
+}
+/** Cache sizing/eviction applied through `initializeImageCache`. Native only —
+ *  the web engine (browser HTTP cache) offers no equivalent knobs. */
+export interface ImageCacheConfig {
+    /** In-memory bitmap cache size in bytes (Android Glide). */
+    memoryCacheSize?: number;
+    /** Size the memory cache as N fullscreen bitmaps (Android Glide). */
+    memoryCacheScreens?: number;
+    /** Persist the cache-key registry across launches so evictions stay
+     *  consistent (Android SharedPreferences store). */
+    persistentCacheKeys?: boolean;
+    /** Bump to invalidate every cached entry — Glide `ObjectKey` signature. */
+    globalSignatureKey?: string;
+    /** iOS: track transformed cache keys for eviction. Needed when decodeWidth/
+     *  decodeHeight (or other transforms) are used alongside evictImage —
+     *  transformed images key differently than the raw URL. */
+    iosComplexCacheEviction?: boolean;
+}
+/** Result of `isImageCached`. 'none' also covers "unknown" — on web the
+ *  browser cache is not queryable, so web always reports 'none'. */
+export type ImageCacheState = 'memory' | 'disk' | 'none';
+/** Options for `prefetch` — the same contract `@octane-xplat/gif`'s
+ *  `prefetch` carries. */
+export interface PrefetchOptions {
+    /** Request headers forwarded on Android and iOS (the framework patch
+     *  restores iOS request modifiers). 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;
+}
+/** Display-load context for `isImageCached`. On iOS the engine folds the
+ *  transform a load used into the cache key — decode bounds are the common
+ *  one, and the leaf always decodes to a size (explicit props or the view's
+ *  measured size), so a bare probe misses entries a display load wrote.
+ *  Repeat the same decode bounds here to probe the key a display load hits.
+ *  Android keys probes on the URL alone and ignores these — but the plugin
+ *  cannot see Glide's active resources there, so a bitmap still on screen
+ *  may report 'none'. Web reports 'none' regardless. */
+export interface ImageCacheQueryOptions {
+    /** Device-pixel decode bounds — same meaning as the `Image` props. */
+    decodeWidth?: number;
+    decodeHeight?: number;
+}
+/** Image — drop-in alternative to `@octane-xplat/ui`'s Image backed by a real
+ *  image engine (Glide on Android, SDWebImage on iOS via
+ *  `@nativescript-community/ui-image`): sized in-memory bitmap cache, disk
+ *  cache, decode-to-view-size, placeholders and transitions. Web renders a
+ *  plain <img>. Every `@octane-xplat/ui` Image prop is accepted with the same
+ *  meaning — the members below are engine extensions with no core equivalent;
+ *  they are ignored on web. SVG `src` is the one behavioral gap — keep core
+ *  `Image` for those. One asymmetry: `decoding='sync'` is not honorably
+ *  supported — Glide/SDWebImage have no synchronous decode mode (the plugin's
+ *  `loadMode` prop is registered but never read), so 'sync' degrades to
+ *  async on native with a console warning rather than a fake. */
+export interface ImageProps extends CoreImageProps {
+    /** Native only — 'none' bypasses memory and disk caches for this image.
+     *  Default 'memory-disk' leaves both caches active. */
+    cachePolicy?: ImageCachePolicy;
+    /** Native only — image shown when `src` fails (`failureImageUri`). */
+    failureImage?: string;
+    /** Native only — extra HTTP headers for the request (authenticated URLs). */
+    headers?: Record<string, string>;
+    /** Native only — explicit decode bounds in device pixels. Default is the
+     *  view's laid-out size (the src is held until first layout so the engine
+     *  never decodes at full source resolution). */
+    decodeWidth?: number;
+    decodeHeight?: number;
+    /** Native only — progressive/interlaced rendering while bytes stream. */
+    progressive?: boolean;
+    /** Native only — crossfade duration in ms when the image lands (0
+     *  disables; engine default applies when unset). */
+    fadeDuration?: number;
+    /** Fired when the final image is set. `source` reports which cache level
+     *  served the bitmap — native only; web fires without `source`. */
+    onLoad?: (event: ImageLoadEvent) => void;
+    /** Fired when the load fails. */
+    onError?: (event: ImageErrorEvent) => void;
+}

package/types/index.macos.d.ts

@@ -0,0 +1,28 @@
+import type { ImageProps } from './generated/props.js'
+
+export type {
+	ImageCacheConfig,
+	ImageCachePolicy,
+	ImageCacheQueryOptions,
+	ImageCacheState,
+	ImageContentFit,
+	ImageContentPosition,
+	ImageContentPositionObject,
+	ImageContentPositionString,
+	ImageContentPositionValue,
+	ImageErrorEvent,
+	ImageLoadEvent,
+	ImageProps,
+	ImageSourceLike,
+	PrefetchOptions,
+} from './generated/props.js'
+
+export declare function Image(props: ImageProps): unknown
+export declare function initializeImageCache(config?: import('./generated/props.js').ImageCacheConfig): void
+export declare function prefetch(srcs: string | string[], options?: PrefetchOptions): Promise<boolean>
+export declare function evictImage(src: string): Promise<boolean>
+export declare function clearImageCaches(): Promise<void>
+export declare function isImageCached(
+	srcs: string | readonly string[],
+	options?: import('./generated/props.js').ImageCacheQueryOptions,
+): Promise<Record<string, import('./generated/props.js').ImageCacheState>>