@ccheever/exact-renderer 0.1.0

package/src/image-source.native.ts

@@ -0,0 +1,703 @@
+import { isAssetRef } from '@exact/core/assets-fonts-state';
+
+import type {
+  ColorSchemeImageSource,
+  ImageColorScheme,
+  ImageCandidate,
+  ImageLoading,
+  ImagePlaceholder,
+  ImageSource,
+} from './types.js';
+
+export interface ImageWarningInput {
+  readonly alt?: string;
+  readonly decorative?: boolean;
+  readonly source?: ImageSource;
+  readonly testID?: string;
+}
+
+const warnedMissingAlt = new Set<string>();
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object';
+}
+
+function hasNonEmptyStringProperty<Key extends string>(
+  value: unknown,
+  key: Key,
+): value is Record<Key, string> & Record<string, unknown> {
+  return isRecord(value) && typeof value[key] === 'string' && value[key].length > 0;
+}
+
+function getDevicePixelRatio(): number {
+  const value = (globalThis as typeof globalThis & { devicePixelRatio?: unknown }).devicePixelRatio;
+  if (typeof value === 'number' && isFinite(value) && value > 0) {
+    return value;
+  }
+
+  const exact = (globalThis as { exact?: { screenScale?: unknown } }).exact;
+  return typeof exact?.screenScale === 'number' && isFinite(exact.screenScale) && exact.screenScale > 0
+    ? exact.screenScale
+    : 1;
+}
+
+function isImageCandidate(value: unknown): value is ImageCandidate {
+  return isRecord(value) && typeof value.uri === 'string' && value.uri.length > 0;
+}
+
+function isImageCandidateArray(source: unknown): source is readonly ImageCandidate[] {
+  return Array.isArray(source) && source.length > 0 && source.every(isImageCandidate);
+}
+
+function isThumbhashSource(source: unknown): source is { thumbhash: string } {
+  return hasNonEmptyStringProperty(source, 'thumbhash');
+}
+
+function isUriSource(
+  source: unknown,
+): source is { uri: string; headers?: Record<string, string>; cacheKey?: string } {
+  return hasNonEmptyStringProperty(source, 'uri');
+}
+
+export function isColorSchemeImageSource(source: unknown): source is ColorSchemeImageSource {
+  if (!isRecord(source) || isUriSource(source) || isThumbhashSource(source)) {
+    return false;
+  }
+
+  return (
+    'light' in source ||
+    'dark' in source ||
+    'fallback' in source
+  );
+}
+
+function describeImageSource(source: ImageSource | undefined): string {
+  if (source == null) {
+    return 'unknown';
+  }
+
+  if (typeof source === 'string') {
+    return source;
+  }
+
+  if (typeof source === 'number') {
+    return `numeric:${source}`;
+  }
+
+  if (isAssetRef(source)) {
+    return source.url;
+  }
+
+  if (isImageCandidateArray(source)) {
+    return source.map((candidate) => candidate.uri).join('|');
+  }
+
+  if (isColorSchemeImageSource(source)) {
+    return [
+      source.light ? `light:${describeImageSource(source.light)}` : '',
+      source.dark ? `dark:${describeImageSource(source.dark)}` : '',
+      source.fallback ? `fallback:${describeImageSource(source.fallback)}` : '',
+    ].filter(Boolean).join('|') || 'color-scheme';
+  }
+
+  if (isThumbhashSource(source)) {
+    return 'thumbhash';
+  }
+
+  if (isUriSource(source)) {
+    return source.uri;
+  }
+
+  return 'unknown';
+}
+
+function formatPreferenceScore(type: string | undefined): number {
+  switch ((type ?? '').toLowerCase()) {
+    case 'image/avif':
+      return 0;
+    case 'image/webp':
+      return 1;
+    case 'image/png':
+      return 2;
+    case 'image/jpeg':
+    case 'image/jpg':
+      return 3;
+    default:
+      return 4;
+  }
+}
+
+function isWidthBucketCandidateList(candidates: readonly ImageCandidate[]): boolean {
+  if (candidates.length === 0) {
+    return false;
+  }
+
+  for (const candidate of candidates) {
+    if (typeof candidate.pixelDensity === 'number' && isFinite(candidate.pixelDensity)) {
+      return false;
+    }
+
+    if (!(typeof candidate.width === 'number' && isFinite(candidate.width) && candidate.width > 0)) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+function estimateViewportContentWidthPoints(): number {
+  const exact = (globalThis as { exact?: { screenWidth?: number } }).exact;
+  if (typeof exact?.screenWidth === 'number' && isFinite(exact.screenWidth) && exact.screenWidth > 0) {
+    return Math.max(120, exact.screenWidth - 96);
+  }
+
+  return 390;
+}
+
+function pickBestWidthBucketCandidate(
+  candidates: readonly ImageCandidate[],
+  targetPixelWidth: number,
+): ImageCandidate {
+  const sorted = [...candidates].sort((a, b) => (a.width ?? 0) - (b.width ?? 0));
+  for (const candidate of sorted) {
+    const width = candidate.width ?? 0;
+    if (width >= targetPixelWidth) {
+      return candidate;
+    }
+  }
+
+  return sorted[sorted.length - 1] ?? candidates[0];
+}
+
+function pickBestImageCandidate(
+  candidates: readonly ImageCandidate[],
+  pixelRatio: number = getDevicePixelRatio(),
+): ImageCandidate {
+  if (isWidthBucketCandidateList(candidates)) {
+    const targetPixels = Math.ceil(estimateViewportContentWidthPoints() * pixelRatio);
+    return pickBestWidthBucketCandidate(candidates, targetPixels);
+  }
+
+  let best = candidates[0];
+  let bestScore = Number.POSITIVE_INFINITY;
+
+  for (const candidate of candidates) {
+    const density = typeof candidate.pixelDensity === 'number' && isFinite(candidate.pixelDensity)
+      ? candidate.pixelDensity
+      : 1;
+    const densityScore = Math.abs(density - pixelRatio);
+    const typeScore = formatPreferenceScore(candidate.type);
+    const widthScore =
+      typeof candidate.width === 'number' && isFinite(candidate.width)
+        ? -candidate.width / 100000
+        : 0;
+    const score = densityScore * 10 + typeScore + widthScore;
+
+    if (score < bestScore) {
+      best = candidate;
+      bestScore = score;
+    }
+  }
+
+  return best;
+}
+
+function decodeThumbHashBase64ToBytes(encoded: string): Uint8Array {
+  const normalized = encoded.trim();
+  if (normalized.length === 0) {
+    throw new Error('empty thumbhash');
+  }
+
+  if (typeof Buffer !== 'undefined') {
+    return Uint8Array.from(Buffer.from(normalized, 'base64'));
+  }
+
+  const binary = atob(normalized);
+  const out = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index++) {
+    out[index] = binary.charCodeAt(index);
+  }
+  return out;
+}
+
+export function thumbhashStringToDataUrl(hash: string): string | undefined {
+  try {
+    return thumbHashBytesToDataUrl(decodeThumbHashBase64ToBytes(hash));
+  } catch {
+    return undefined;
+  }
+}
+
+// Adapted from thumbhash 0.1.1's MIT-licensed decoder so native startup does
+// not need the full package module, which also includes the encoder.
+function thumbHashBytesToDataUrl(hash: Uint8Array): string {
+  const image = thumbHashToRgba(hash);
+  return rgbaToDataUrl(image.width, image.height, image.rgba);
+}
+
+function thumbHashToRgba(hash: Uint8Array): {
+  readonly height: number;
+  readonly rgba: Uint8Array;
+  readonly width: number;
+} {
+  const { PI, min, max, cos, round } = Math;
+  const header24 = hash[0] | (hash[1] << 8) | (hash[2] << 16);
+  const header16 = hash[3] | (hash[4] << 8);
+  const lDc = (header24 & 63) / 63;
+  const pDc = ((header24 >> 6) & 63) / 31.5 - 1;
+  const qDc = ((header24 >> 12) & 63) / 31.5 - 1;
+  const lScale = ((header24 >> 18) & 31) / 31;
+  const hasAlpha = header24 >> 23;
+  const pScale = ((header16 >> 3) & 63) / 63;
+  const qScale = ((header16 >> 9) & 63) / 63;
+  const isLandscape = header16 >> 15;
+  const lx = max(3, isLandscape ? hasAlpha ? 5 : 7 : header16 & 7);
+  const ly = max(3, isLandscape ? header16 & 7 : hasAlpha ? 5 : 7);
+  const aDc = hasAlpha ? (hash[5] & 15) / 15 : 1;
+  const aScale = (hash[5] >> 4) / 15;
+  const acStart = hasAlpha ? 6 : 5;
+  let acIndex = 0;
+
+  const decodeChannel = (nx: number, ny: number, scale: number): number[] => {
+    const ac: number[] = [];
+    for (let cy = 0; cy < ny; cy++) {
+      for (let cx = cy ? 0 : 1; cx * ny < nx * (ny - cy); cx++) {
+        const nibble = (hash[acStart + (acIndex >> 1)] >> ((acIndex++ & 1) << 2)) & 15;
+        ac.push((nibble / 7.5 - 1) * scale);
+      }
+    }
+    return ac;
+  };
+
+  const lAc = decodeChannel(lx, ly, lScale);
+  const pAc = decodeChannel(3, 3, pScale * 1.25);
+  const qAc = decodeChannel(3, 3, qScale * 1.25);
+  const aAc = hasAlpha ? decodeChannel(5, 5, aScale) : [];
+  const ratio = thumbHashApproximateAspectRatio(hash);
+  const width = round(ratio > 1 ? 32 : 32 * ratio);
+  const height = round(ratio > 1 ? 32 / ratio : 32);
+  const rgba = new Uint8Array(width * height * 4);
+  const fx: number[] = [];
+  const fy: number[] = [];
+
+  for (let y = 0, i = 0; y < height; y++) {
+    for (let x = 0; x < width; x++, i += 4) {
+      let l = lDc;
+      let p = pDc;
+      let q = qDc;
+      let a = aDc;
+
+      for (let cx = 0, count = max(lx, hasAlpha ? 5 : 3); cx < count; cx++) {
+        fx[cx] = cos(PI / width * (x + 0.5) * cx);
+      }
+      for (let cy = 0, count = max(ly, hasAlpha ? 5 : 3); cy < count; cy++) {
+        fy[cy] = cos(PI / height * (y + 0.5) * cy);
+      }
+
+      for (let cy = 0, j = 0; cy < ly; cy++) {
+        for (let cx = cy ? 0 : 1, fy2 = fy[cy] * 2; cx * ly < lx * (ly - cy); cx++, j++) {
+          l += lAc[j] * fx[cx] * fy2;
+        }
+      }
+
+      for (let cy = 0, j = 0; cy < 3; cy++) {
+        for (let cx = cy ? 0 : 1, fy2 = fy[cy] * 2; cx < 3 - cy; cx++, j++) {
+          const f = fx[cx] * fy2;
+          p += pAc[j] * f;
+          q += qAc[j] * f;
+        }
+      }
+
+      if (hasAlpha) {
+        for (let cy = 0, j = 0; cy < 5; cy++) {
+          for (let cx = cy ? 0 : 1, fy2 = fy[cy] * 2; cx < 5 - cy; cx++, j++) {
+            a += aAc[j] * fx[cx] * fy2;
+          }
+        }
+      }
+
+      const b = l - 2 / 3 * p;
+      const r = (3 * l - b + q) / 2;
+      const g = r - q;
+      rgba[i] = max(0, 255 * min(1, r));
+      rgba[i + 1] = max(0, 255 * min(1, g));
+      rgba[i + 2] = max(0, 255 * min(1, b));
+      rgba[i + 3] = max(0, 255 * min(1, a));
+    }
+  }
+
+  return { width, height, rgba };
+}
+
+function thumbHashApproximateAspectRatio(hash: Uint8Array): number {
+  const header = hash[3];
+  const hasAlpha = hash[2] & 0x80;
+  const isLandscape = hash[4] & 0x80;
+  const lx = isLandscape ? hasAlpha ? 5 : 7 : header & 7;
+  const ly = isLandscape ? header & 7 : hasAlpha ? 5 : 7;
+  return lx / ly;
+}
+
+function rgbaToDataUrl(width: number, height: number, rgba: Uint8Array): string {
+  const row = width * 4 + 1;
+  const idat = 6 + height * (5 + row);
+  const bytes = [
+    137, 80, 78, 71, 13, 10, 26, 10, 0, 0, 0, 13, 73, 72, 68, 82, 0, 0,
+    width >> 8, width & 255, 0, 0, height >> 8, height & 255, 8, 6, 0, 0, 0, 0, 0, 0, 0,
+    idat >>> 24, (idat >> 16) & 255, (idat >> 8) & 255, idat & 255,
+    73, 68, 65, 84, 120, 1,
+  ];
+  const crcTable = [
+    0, 498536548, 997073096, 651767980, 1994146192, 1802195444, 1303535960,
+    1342533948, -306674912, -267414716, -690576408, -882789492, -1687895376,
+    -2032938284, -1609899400, -1111625188,
+  ];
+  let a = 1;
+  let b = 0;
+
+  for (let y = 0, i = 0, end = row - 1; y < height; y++, end += row - 1) {
+    bytes.push(y + 1 < height ? 0 : 1, row & 255, row >> 8, ~row & 255, (row >> 8) ^ 255, 0);
+    for (b = (b + a) % 65521; i < end; i++) {
+      const value = rgba[i] & 255;
+      bytes.push(value);
+      a = (a + value) % 65521;
+      b = (b + a) % 65521;
+    }
+  }
+
+  bytes.push(
+    b >> 8, b & 255, a >> 8, a & 255, 0, 0, 0, 0,
+    0, 0, 0, 0, 73, 69, 78, 68, 174, 66, 96, 130,
+  );
+
+  for (const [start, end] of [[12, 29], [37, 41 + idat]]) {
+    let crc = ~0;
+    for (let i = start; i < end; i++) {
+      crc ^= bytes[i];
+      crc = (crc >>> 4) ^ crcTable[crc & 15];
+      crc = (crc >>> 4) ^ crcTable[crc & 15];
+    }
+    crc = ~crc;
+    let outputIndex = end;
+    bytes[outputIndex++] = crc >>> 24;
+    bytes[outputIndex++] = (crc >> 16) & 255;
+    bytes[outputIndex++] = (crc >> 8) & 255;
+    bytes[outputIndex] = crc & 255;
+  }
+
+  return `data:image/png;base64,${encodeBase64Bytes(bytes)}`;
+}
+
+function encodeBase64Bytes(bytes: readonly number[]): string {
+  if (typeof Buffer !== 'undefined') {
+    return Buffer.from(bytes).toString('base64');
+  }
+
+  if (typeof btoa === 'function') {
+    let binary = '';
+    for (const byte of bytes) {
+      binary += String.fromCharCode(byte & 255);
+    }
+    return btoa(binary);
+  }
+
+  const alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+  let output = '';
+  for (let index = 0; index < bytes.length; index += 3) {
+    const first = bytes[index] & 255;
+    const hasSecond = index + 1 < bytes.length;
+    const hasThird = index + 2 < bytes.length;
+    const second = hasSecond ? bytes[index + 1] & 255 : 0;
+    const third = hasThird ? bytes[index + 2] & 255 : 0;
+    const triplet = (first << 16) | (second << 8) | third;
+    output += alphabet[(triplet >> 18) & 63];
+    output += alphabet[(triplet >> 12) & 63];
+    output += hasSecond ? alphabet[(triplet >> 6) & 63] : '=';
+    output += hasThird ? alphabet[triplet & 63] : '=';
+  }
+  return output;
+}
+
+function resolveUrlLikeImageSource(source: ImageSource): string | undefined {
+  if (typeof source === 'string' && source.length > 0) {
+    return source;
+  }
+
+  if (isAssetRef(source)) {
+    return source.url;
+  }
+
+  if (isUriSource(source)) {
+    return source.uri;
+  }
+
+  return undefined;
+}
+
+export function getRuntimeImageColorScheme(): ImageColorScheme {
+  const state = (globalThis as {
+    __exactExperienceRegistryState?: {
+      theme?: {
+        scheme?: unknown;
+      } | null;
+    };
+  }).__exactExperienceRegistryState;
+  const scheme = state?.theme?.scheme;
+  return scheme === 'light' || scheme === 'dark' ? scheme : 'light';
+}
+
+export function resolveThemeAwareImageSource(
+  source: ImageSource | undefined,
+  scheme: ImageColorScheme = getRuntimeImageColorScheme(),
+): ImageSource | undefined {
+  if (!isColorSchemeImageSource(source)) {
+    return source;
+  }
+
+  const selected = source[scheme] ?? source.fallback ?? source.light ?? source.dark;
+  return resolveThemeAwareImageSource(selected, scheme);
+}
+
+export function resolveImageSourceForNative(
+  source: ImageSource | undefined,
+  scheme: ImageColorScheme = getRuntimeImageColorScheme(),
+): string | undefined {
+  if (source == null) {
+    return undefined;
+  }
+
+  if (isColorSchemeImageSource(source)) {
+    return resolveImageSourceForNative(resolveThemeAwareImageSource(source, scheme), scheme);
+  }
+
+  if (typeof source === 'number') {
+    if (process.env.NODE_ENV !== 'production' && process.env.NODE_ENV !== 'test') {
+      console.warn('[Exact] Numeric image sources are not supported. Use asset(...) instead.');
+    }
+    return undefined;
+  }
+
+  if (isImageCandidateArray(source)) {
+    return resolveImageSourceForNative(pickBestImageCandidate(source), scheme);
+  }
+
+  if (isThumbhashSource(source)) {
+    return thumbhashStringToDataUrl(source.thumbhash);
+  }
+
+  return resolveUrlLikeImageSource(source);
+}
+
+export function resolveImagePlaceholderForNative(
+  placeholder: ImagePlaceholder | undefined,
+): string | undefined {
+  if (placeholder == null) {
+    return undefined;
+  }
+
+  if (hasNonEmptyStringProperty(placeholder, 'color')) {
+    return `color:${placeholder.color}`;
+  }
+
+  return resolveImageSourceForNative(placeholder as ImageSource);
+}
+
+export function warnIfImageMissingAlt({
+  alt,
+  decorative,
+  source,
+  testID,
+}: ImageWarningInput): void {
+  if (
+    process.env.NODE_ENV === 'production' ||
+    process.env.NODE_ENV === 'test' ||
+    decorative ||
+    alt !== undefined
+  ) {
+    return;
+  }
+
+  const signature = `${testID ?? 'no-testid'}:${describeImageSource(source)}`;
+  if (warnedMissingAlt.has(signature)) {
+    return;
+  }
+
+  warnedMissingAlt.add(signature);
+  console.warn('[Exact] <Image> is missing alt text. Provide alt="..." or set decorative.');
+}
+
+// LLP 0154 P2: web-primitives.ts is shared runtime code (it branches on the
+// render environment at runtime), so every platform variant of this module
+// must export the same public surface. The DOM resolvers below mirror
+// image-source.ts using this file's own helpers; the DOM render branch is
+// unreachable on native, but the implementations stay faithful so the
+// contract holds if that ever changes.
+
+const DEFAULT_PLACEHOLDER_COLOR = '#e5e7eb';
+
+export interface DOMResolvedImageSource {
+  readonly pictureSources: ReadonlyArray<{
+    readonly srcSet: string;
+    readonly type?: string;
+  }>;
+  readonly src?: string;
+  readonly srcSet?: string;
+  readonly themeSources?: {
+    readonly light?: string;
+    readonly dark?: string;
+    readonly fallback?: string;
+  };
+}
+
+export interface DOMResolvedImagePlaceholder {
+  readonly backgroundColor?: string;
+  readonly backgroundImage?: string;
+}
+
+function formatSrcSetDescriptor(candidate: ImageCandidate): string {
+  if (typeof candidate.width === 'number' && isFinite(candidate.width) && candidate.width > 0) {
+    return `${candidate.width}w`;
+  }
+
+  if (
+    typeof candidate.pixelDensity === 'number' &&
+    isFinite(candidate.pixelDensity) &&
+    candidate.pixelDensity > 0
+  ) {
+    return `${candidate.pixelDensity}x`;
+  }
+
+  return '';
+}
+
+function buildSrcSet(candidates: readonly ImageCandidate[]): string {
+  return candidates
+    .map((candidate) => {
+      const descriptor = formatSrcSetDescriptor(candidate);
+      return descriptor.length > 0 ? `${candidate.uri} ${descriptor}` : candidate.uri;
+    })
+    .join(', ');
+}
+
+export function resolveImageSourceForDOM(
+  source: ImageSource | undefined,
+  scheme: ImageColorScheme = getRuntimeImageColorScheme(),
+): DOMResolvedImageSource | undefined {
+  if (source == null || typeof source === 'number') {
+    return undefined;
+  }
+
+  if (isColorSchemeImageSource(source)) {
+    const selected = resolveThemeAwareImageSource(source, scheme);
+    const resolved = resolveImageSourceForDOM(selected, scheme);
+    const light = source.light ? resolveImageSourceForNative(source.light, 'light') : undefined;
+    const dark = source.dark ? resolveImageSourceForNative(source.dark, 'dark') : undefined;
+    const fallback = source.fallback ? resolveImageSourceForNative(source.fallback, scheme) : undefined;
+    if (!resolved) {
+      return undefined;
+    }
+    return {
+      ...resolved,
+      themeSources: {
+        ...(light ? { light } : {}),
+        ...(dark ? { dark } : {}),
+        ...(fallback ? { fallback } : {}),
+      },
+    };
+  }
+
+  if (isThumbhashSource(source)) {
+    const dataUrl = thumbhashStringToDataUrl(source.thumbhash);
+    if (dataUrl == null || dataUrl.length === 0) {
+      return undefined;
+    }
+
+    return {
+      pictureSources: [],
+      src: dataUrl,
+    };
+  }
+
+  if (isImageCandidateArray(source)) {
+    const groupedByType = new Map<string, ImageCandidate[]>();
+    const fallbackCandidates: ImageCandidate[] = [];
+
+    for (const candidate of source) {
+      if (typeof candidate.type === 'string' && candidate.type.length > 0) {
+        const existing = groupedByType.get(candidate.type) ?? [];
+        existing.push(candidate);
+        groupedByType.set(candidate.type, existing);
+      } else {
+        fallbackCandidates.push(candidate);
+      }
+    }
+
+    const pictureSources = Array.from(groupedByType.entries())
+      .sort(([typeA], [typeB]) => formatPreferenceScore(typeA) - formatPreferenceScore(typeB))
+      .map(([type, candidates]) => ({
+        type,
+        srcSet: buildSrcSet(candidates),
+      }));
+    const fallback = fallbackCandidates.length > 0 ? fallbackCandidates : source;
+
+    return {
+      pictureSources,
+      src: pickBestImageCandidate(source).uri,
+      srcSet: fallback.length > 1 ? buildSrcSet(fallback) : undefined,
+    };
+  }
+
+  const src = resolveUrlLikeImageSource(source);
+  if (!src) {
+    return undefined;
+  }
+
+  return {
+    pictureSources: [],
+    src,
+  };
+}
+
+export function resolveImagePlaceholderForDOM(
+  placeholder: ImagePlaceholder | undefined,
+): DOMResolvedImagePlaceholder | undefined {
+  if (placeholder == null) {
+    return undefined;
+  }
+
+  if (hasNonEmptyStringProperty(placeholder, 'color')) {
+    return {
+      backgroundColor: placeholder.color,
+    };
+  }
+
+  if (isThumbhashSource(placeholder)) {
+    const dataUrl = thumbhashStringToDataUrl(placeholder.thumbhash);
+    if (dataUrl != null && dataUrl.length > 0) {
+      return {
+        backgroundImage: `url("${dataUrl.replace(/"/g, '\\"')}")`,
+      };
+    }
+
+    return {
+      backgroundColor: DEFAULT_PLACEHOLDER_COLOR,
+    };
+  }
+
+  const resolved = resolveImageSourceForDOM(placeholder as ImageSource);
+  if (!resolved?.src) {
+    return undefined;
+  }
+
+  return {
+    backgroundImage: `url("${resolved.src.replace(/"/g, '\\"')}")`,
+  };
+}
+
+export function normalizeImageLoading(loading: ImageLoading | undefined): 'eager' | 'lazy' | undefined {
+  if (loading === 'eager' || loading === 'lazy') {
+    return loading;
+  }
+
+  return undefined;
+}