@buoy-gg/images 7.0.3

package/src/capture/savings.ts

@@ -0,0 +1,193 @@
+/**
+ * Savings prover — Squoosh-style, on device.
+ *
+ * Instead of estimating what an oversized source wastes, PROVE it: re-encode
+ * the image at the displayed size (× pixel ratio) as WebP via
+ * expo-image-manipulator (verified: chainable resize → saveAsync WebP on BOTH
+ * platforms, available in Expo Go), stat the output file, and report real
+ * bytes vs the original. The optimized file:// URI can then be A/B'd in place
+ * through the existing swap-url override.
+ *
+ * Original size is resolved in tiers: observed download bytes (onProgress
+ * total) → expo disk-cache file size → HEAD Content-Length.
+ */
+
+import { neededPixels } from "../store/imageEventStore";
+import type { ImageRecord } from "../types";
+
+export interface SavingsResult {
+  ok: boolean;
+  message: string;
+  /** Real encoded bytes of the original (when determinable). */
+  originalBytes?: number;
+  originalBytesSource?: "download" | "cacheFile" | "head";
+  /** Real encoded bytes of the optimized WebP on disk. */
+  optimizedBytes?: number;
+  /** file:// URI of the optimized image (feed to swap-url to preview). */
+  optimizedUri?: string;
+  optimizedDims?: { width: number; height: number };
+  savedBytes?: number;
+  savedPct?: number;
+}
+
+interface LegacyFs {
+  getInfoAsync?: (uri: string, options?: { size?: boolean }) => Promise<{
+    exists: boolean;
+    size?: number;
+  }>;
+}
+
+function loadLegacyFs(): LegacyFs | null {
+  try {
+    const mod = require("expo-file-system/legacy");
+    const fs = mod?.default || mod;
+    if (fs?.getInfoAsync) return fs;
+  } catch {
+    // try main import
+  }
+  try {
+    const mod = require("expo-file-system");
+    const fs = mod?.default || mod;
+    if (fs?.getInfoAsync) return fs;
+  } catch {
+    // not installed
+  }
+  return null;
+}
+
+async function fileSize(uri: string): Promise<number | null> {
+  const fs = loadLegacyFs();
+  if (!fs?.getInfoAsync) return null;
+  try {
+    const normalized = uri.startsWith("file://") ? uri : `file://${uri}`;
+    const info = await fs.getInfoAsync(normalized, { size: true });
+    return info.exists && typeof info.size === "number" ? info.size : null;
+  } catch {
+    return null;
+  }
+}
+
+async function resolveOriginalBytes(
+  record: ImageRecord
+): Promise<{ bytes: number; source: SavingsResult["originalBytesSource"] } | null> {
+  if (record.bytesTotal && record.bytesTotal > 0) {
+    return { bytes: record.bytesTotal, source: "download" };
+  }
+  // expo disk cache file
+  if (record.lib === "expo") {
+    try {
+      const expo = require("expo-image");
+      const path: string | null = await expo.Image.getCachePathAsync(record.uri);
+      if (path) {
+        const size = await fileSize(path);
+        if (size != null) return { bytes: size, source: "cacheFile" };
+      }
+    } catch {
+      // fall through
+    }
+  }
+  // HEAD request (network sources only)
+  if (record.sourceKind === "network") {
+    try {
+      const response = await fetch(record.uri, { method: "HEAD" });
+      const length = Number(response.headers.get("content-length"));
+      if (Number.isFinite(length) && length > 0) return { bytes: length, source: "head" };
+    } catch {
+      // unknown original size is fine
+    }
+  }
+  return null;
+}
+
+/**
+ * Re-encode `record`'s source at its displayed size as WebP and measure it.
+ * Requires expo-image-manipulator (graceful message when absent).
+ */
+export async function proveSavings(record: ImageRecord): Promise<SavingsResult> {
+  if (!record.uri || (record.sourceKind !== "network" && record.sourceKind !== "asset" && record.sourceKind !== "file")) {
+    return { ok: false, message: "No loadable source URI on this record" };
+  }
+  const needed = neededPixels(record);
+  if (!needed) {
+    return { ok: false, message: "No layout yet — the image must render once to know its displayed size" };
+  }
+
+  let manipulator: {
+    ImageManipulator?: { manipulate: (source: string) => any };
+    manipulateAsync?: (
+      uri: string,
+      actions: unknown[],
+      options: Record<string, unknown>
+    ) => Promise<{ uri: string; width: number; height: number }>;
+    SaveFormat?: Record<string, string>;
+  };
+  try {
+    manipulator = require("expo-image-manipulator");
+  } catch {
+    return {
+      ok: false,
+      message: "expo-image-manipulator not installed — add it to enable real savings measurement",
+    };
+  }
+
+  const webp = manipulator.SaveFormat?.WEBP ?? "webp";
+  const targetWidth = Math.min(needed.width, record.intrinsic?.width ?? needed.width);
+
+  let original: Awaited<ReturnType<typeof resolveOriginalBytes>> = null;
+  let optimized: { uri: string; width: number; height: number } | null = null;
+  try {
+    [original, optimized] = await Promise.all([
+      resolveOriginalBytes(record),
+      (async (): Promise<{ uri: string; width: number; height: number } | null> => {
+        // Preferred: context API (current). Fallback: deprecated manipulateAsync.
+        if (manipulator.ImageManipulator?.manipulate) {
+          const context = manipulator.ImageManipulator.manipulate(record.uri);
+          try {
+            const ref = await context.resize({ width: targetWidth }).renderAsync();
+            try {
+              return await ref.saveAsync({ format: webp, compress: 0.8 });
+            } finally {
+              ref.release?.();
+            }
+          } finally {
+            context.release?.();
+          }
+        }
+        if (manipulator.manipulateAsync) {
+          return manipulator.manipulateAsync(record.uri, [{ resize: { width: targetWidth } }], {
+            compress: 0.8,
+            format: webp,
+          });
+        }
+        return null;
+      })(),
+    ]);
+  } catch (error) {
+    return { ok: false, message: `Re-encode failed: ${String((error as Error)?.message ?? error)}` };
+  }
+
+  if (!optimized?.uri) {
+    return { ok: false, message: "Re-encode produced no output (unsupported source?)" };
+  }
+
+  const optimizedBytes = await fileSize(optimized.uri);
+  const result: SavingsResult = {
+    ok: true,
+    message: "",
+    optimizedUri: optimized.uri,
+    optimizedBytes: optimizedBytes ?? undefined,
+    optimizedDims: { width: optimized.width, height: optimized.height },
+    originalBytes: original?.bytes,
+    originalBytesSource: original?.source,
+  };
+  if (original?.bytes != null && optimizedBytes != null) {
+    result.savedBytes = Math.max(0, original.bytes - optimizedBytes);
+    result.savedPct = original.bytes > 0 ? Math.round((result.savedBytes / original.bytes) * 100) : 0;
+    result.message = `Right-sized WebP is ${result.savedPct}% smaller (real bytes, encoded on device)`;
+  } else if (optimizedBytes != null) {
+    result.message = "Optimized variant encoded — original size unknown (no download bytes, cache entry, or Content-Length)";
+  } else {
+    result.message = "Optimized variant encoded — could not stat the output file";
+  }
+  return result;
+}

package/src/capture/shared.ts

@@ -0,0 +1,387 @@
+/**
+ * Capture core shared by the RN <Image> decorator and the expo-image patch.
+ *
+ * ImageInstanceTracker: one per live image component instance. It rolls a new
+ * ImageRecord whenever the instance's source URI changes, and exposes wrapped
+ * event handlers that feed the store while still calling through to whatever
+ * handlers the app passed.
+ */
+
+import type { CacheVerdict, ImageLib, SourceKind } from "../types";
+import { imagesState } from "../state";
+import { dropActionState, settleReloadRequest } from "./actions";
+import {
+  createRecord,
+  getRecord,
+  updateRecord,
+} from "../store/imageEventStore";
+
+/**
+ * Images rendered by Buoy's own UI (e.g. thumbnails inside the Images modal)
+ * carry this testID prefix and are excluded from capture, so the tool doesn't
+ * pollute its own registry.
+ */
+export const INTERNAL_TEST_ID_PREFIX = "buoy-internal";
+
+export function isInternalImage(testID: unknown): boolean {
+  return typeof testID === "string" && testID.startsWith(INTERNAL_TEST_ID_PREFIX);
+}
+
+/**
+ * React Native's own devtools UI loads images too (LogBox icons resolve to
+ * Metro asset URLs under Libraries/LogBox). They're noise in an app-focused
+ * registry — skip them.
+ */
+export function isNoiseUri(uri: string): boolean {
+  return (
+    uri.includes("Libraries%2FLogBox") ||
+    uri.includes("Libraries/LogBox") ||
+    uri.includes("LogBoxImages")
+  );
+}
+
+export function classifyUri(uri: string): SourceKind {
+  if (uri.startsWith("http://") || uri.startsWith("https://")) return "network";
+  if (uri.startsWith("file://") || uri.startsWith("asset://")) return "file";
+  if (uri.startsWith("data:")) return "data";
+  return "other";
+}
+
+/**
+ * Best-effort URI extraction from any source prop shape (RN or expo-image):
+ * string, number (Metro asset), {uri}, arrays of those, ImageRef.
+ */
+export function resolveSourceUri(source: unknown): {
+  uri: string;
+  kind: SourceKind;
+} {
+  if (source == null) return { uri: "", kind: "other" };
+  if (Array.isArray(source)) {
+    return resolveSourceUri(source.length > 0 ? source[0] : null);
+  }
+  if (typeof source === "string") {
+    return { uri: source, kind: classifyUri(source) };
+  }
+  if (typeof source === "number") {
+    // Metro asset id. Image is guaranteed evaluated by the time an instance
+    // renders, so requiring it lazily here can never latch the decorator late.
+    try {
+      const rn = require("react-native");
+      const resolved = rn.Image?.resolveAssetSource?.(source);
+      if (resolved?.uri) return { uri: resolved.uri, kind: "asset" };
+    } catch {
+      // fall through
+    }
+    return { uri: `asset:#${source}`, kind: "asset" };
+  }
+  if (typeof source === "object") {
+    const uri = (source as { uri?: unknown }).uri;
+    if (typeof uri === "string") {
+      const kind = classifyUri(uri);
+      // require()'d assets resolve to Metro dev-server URLs in dev — still
+      // report them as assets when they carry the packager marker.
+      if ((source as { __packager_asset?: boolean }).__packager_asset) {
+        return { uri, kind: "asset" };
+      }
+      return { uri, kind };
+    }
+    // expo-image ImageRef (native shared object) has width/height but no uri.
+    const width = (source as { width?: unknown }).width;
+    if (typeof width === "number") return { uri: "(ImageRef)", kind: "other" };
+  }
+  return { uri: "", kind: "other" };
+}
+
+/** The event-handler subset we intercept, normalized across both libraries. */
+export interface OriginalHandlers {
+  onLoadStart?: (event: unknown) => void;
+  onProgress?: (event: unknown) => void;
+  onLoad?: (event: unknown) => void;
+  onError?: (event: unknown) => void;
+  onLoadEnd?: (event: unknown) => void;
+  onDisplay?: (event: unknown) => void;
+  onLayout?: (event: unknown) => void;
+}
+
+export type WrappedHandlers = Required<
+  Pick<
+    OriginalHandlers,
+    "onLoadStart" | "onProgress" | "onLoad" | "onError" | "onLayout"
+  >
+> &
+  Pick<OriginalHandlers, "onLoadEnd" | "onDisplay">;
+
+/** RN events arrive as {nativeEvent}; expo-image passes the payload directly. */
+function payloadOf(event: unknown): Record<string, unknown> {
+  if (event && typeof event === "object") {
+    const native = (event as { nativeEvent?: unknown }).nativeEvent;
+    if (native && typeof native === "object") {
+      return native as Record<string, unknown>;
+    }
+    return event as Record<string, unknown>;
+  }
+  return {};
+}
+
+/**
+ * After an RN-core load, classify the cache via Image.queryCache.
+ *
+ * Delayed + retried: NSURLCache commits fresh downloads asynchronously, so a
+ * query at the instant of onLoad reports a miss for images that ARE being
+ * cached (observed live). First probe after 600ms, one re-probe at 3s to
+ * catch slow cache writes.
+ */
+function queryRnCache(recordId: number, uri: string): void {
+  const probe = () => {
+    try {
+      const rn = require("react-native");
+      const queryCache: undefined | ((uris: string[]) => Promise<Record<string, string>>) =
+        rn.Image?.queryCache;
+      if (typeof queryCache !== "function" || !uri) return;
+      queryCache([uri])
+        .then((result) => {
+          const verdict = result?.[uri] as CacheVerdict | undefined;
+          if (verdict) {
+            updateRecord(recordId, {
+              cacheVerdict: verdict,
+              cacheVerdictSource: "queryCache",
+            });
+          }
+        })
+        .catch(() => {});
+    } catch {
+      // queryCache unavailable (web) — leave verdict unknown.
+    }
+  };
+  setTimeout(probe, 600);
+  setTimeout(() => {
+    const record = getRecord(recordId);
+    if (record && record.cacheVerdictSource !== "queryCache") probe();
+  }, 3000);
+}
+
+export class ImageInstanceTracker {
+  private readonly lib: ImageLib;
+  private recordId: number | null = null;
+  private uri: string | null = null;
+  private handlerCache: { key: unknown[]; out: WrappedHandlers } | null = null;
+
+  constructor(lib: ImageLib) {
+    this.lib = lib;
+  }
+
+  getRecordId(): number | null {
+    return this.recordId;
+  }
+
+  /** Record accessibility presence (called per render; writes only on change). */
+  noteA11y(hasAltText: boolean): void {
+    if (this.recordId == null) return;
+    const record = getRecord(this.recordId);
+    if (record && record.hasAltText !== hasAltText) {
+      updateRecord(this.recordId, { hasAltText });
+    }
+  }
+
+  /** Call on every render with the current source prop. Rolls records on change. */
+  syncSource(source: unknown): void {
+    const { uri, kind } = resolveSourceUri(source);
+    if (uri === this.uri) return;
+    this.uri = uri;
+    this.handlerCache = null; // handlers close over recordId via getter, but roll anyway
+    if (this.recordId != null) dropActionState(this.recordId);
+    if (!uri || isNoiseUri(uri)) {
+      this.recordId = null;
+      return;
+    }
+    const record = createRecord({ lib: this.lib, uri, sourceKind: kind });
+    this.recordId = record.id;
+  }
+
+  unmount(): void {
+    if (this.recordId != null) {
+      updateRecord(this.recordId, { mounted: false });
+      dropActionState(this.recordId);
+    }
+  }
+
+  /**
+   * Wrapped handlers for the current originals. Cached by handler identity so
+   * re-renders with unchanged props reuse the same functions.
+   */
+  handlers(orig: OriginalHandlers): WrappedHandlers {
+    const key = [
+      orig.onLoadStart,
+      orig.onProgress,
+      orig.onLoad,
+      orig.onError,
+      orig.onLoadEnd,
+      orig.onDisplay,
+      orig.onLayout,
+      this.recordId,
+    ];
+    const cached = this.handlerCache;
+    if (cached && cached.key.length === key.length && cached.key.every((k, i) => k === key[i])) {
+      return cached.out;
+    }
+
+    const recordId = this.recordId;
+    const lib = this.lib;
+    const uri = this.uri ?? "";
+
+    const out: WrappedHandlers = {
+      onLoadStart: (event) => {
+        if (recordId != null) {
+          const record = getRecord(recordId);
+          const now = Date.now();
+          // Out-of-order defense (seen live on iOS remounts/cache hits AND
+          // instant file:// failures): the native onLoadStart of a burst can
+          // arrive AFTER its onLoad/onError. A "start" right after a settled
+          // outcome belongs to that same burst — don't regress the record.
+          const settledAt = Math.max(record?.loadedAt ?? 0, record?.erroredAt ?? 0);
+          const settledJustNow = settledAt > 0 && now - settledAt < 300;
+          updateRecord(recordId, {
+            ...(settledJustNow ? {} : { status: "loading", error: undefined, errorCode: undefined, errorHeaders: undefined }),
+            startedAt: now,
+            loadCount: (record?.loadCount ?? 0) + 1,
+          });
+        }
+        orig.onLoadStart?.(event);
+      },
+      onProgress: (event) => {
+        if (recordId != null) {
+          const p = payloadOf(event);
+          updateRecord(recordId, {
+            progressSeen: true,
+            bytesLoaded: typeof p.loaded === "number" ? p.loaded : undefined,
+            bytesTotal: typeof p.total === "number" ? p.total : undefined,
+          });
+        }
+        orig.onProgress?.(event);
+      },
+      onLoad: (event) => {
+        if (recordId != null) {
+          const p = payloadOf(event);
+          const source = (p.source ?? {}) as Record<string, unknown>;
+          const now = Date.now();
+          const record = getRecord(recordId);
+          // Duration only counts from a start belonging to THIS load cycle: a
+          // start newer than the previous completion. Without one (instant
+          // cache hit whose onLoadStart arrives late/never), report 0ms.
+          const start =
+            record?.startedAt != null &&
+            record.startedAt <= now &&
+            record.startedAt > (record.loadedAt ?? record.createdAt - 1)
+              ? record.startedAt
+              : record?.loadedAt == null
+                ? (record?.startedAt ?? record?.createdAt ?? now)
+                : now;
+          const width = typeof source.width === "number" ? source.width : 0;
+          const height = typeof source.height === "number" ? source.height : 0;
+          updateRecord(recordId, {
+            status: "loaded",
+            loadedAt: now,
+            durationMs: Math.max(0, now - start),
+            error: undefined,
+            errorCode: undefined,
+            errorHeaders: undefined,
+            intrinsic: width > 0 && height > 0 ? { width, height } : record?.intrinsic,
+            cacheVerdict:
+              typeof p.cacheType === "string"
+                ? (p.cacheType as CacheVerdict)
+                : record?.cacheVerdict,
+            cacheVerdictSource:
+              typeof p.cacheType === "string" ? "event" : record?.cacheVerdictSource,
+            mediaType:
+              typeof source.mediaType === "string" || source.mediaType === null
+                ? (source.mediaType as string | null)
+                : record?.mediaType,
+            isAnimated:
+              typeof source.isAnimated === "boolean"
+                ? source.isAnimated
+                : record?.isAnimated,
+          });
+          settleReloadRequest(recordId);
+          if (lib === "rn") queryRnCache(recordId, uri);
+        }
+        orig.onLoad?.(event);
+      },
+      onError: (event) => {
+        if (recordId != null) {
+          const p = payloadOf(event);
+          let message =
+            typeof p.error === "string"
+              ? p.error
+              : String((p.error as { message?: string })?.message ?? "unknown error");
+          // Simulation sources produce raw file-not-found noise — translate to
+          // an honest label (state-based, so it works for both libs' error
+          // texts), in our record AND in the event the app receives.
+          const record0 = getRecord(recordId);
+          const s = imagesState();
+          const activeOverride = s.overrides.get(recordId) as
+            | { source?: { type?: string } }
+            | undefined;
+          if (activeOverride?.source?.type === "error") {
+            message = "Forced error (Buoy Images simulation)";
+            if (typeof p.error === "string") p.error = message;
+          } else if (
+            s.globalModes.network === "offline" &&
+            record0?.sourceKind === "network"
+          ) {
+            message = "Offline simulation (Buoy Images): network image blocked";
+            if (typeof p.error === "string") p.error = message;
+          }
+          updateRecord(recordId, {
+            status: "error",
+            erroredAt: Date.now(),
+            error: message,
+            errorCode: typeof p.responseCode === "number" ? p.responseCode : undefined,
+            errorHeaders:
+              p.httpResponseHeaders && typeof p.httpResponseHeaders === "object"
+                ? (p.httpResponseHeaders as Record<string, string>)
+                : undefined,
+          });
+          settleReloadRequest(recordId);
+        }
+        orig.onError?.(event);
+      },
+      onLayout: (event) => {
+        if (recordId != null) {
+          const layout = (payloadOf(event).layout ?? {}) as Record<string, unknown>;
+          const width = typeof layout.width === "number" ? layout.width : 0;
+          const height = typeof layout.height === "number" ? layout.height : 0;
+          if (width > 0 && height > 0) {
+            const record = getRecord(recordId);
+            const prev = record?.layout;
+            // Size change AFTER the image loaded = layout-shift suspect (the
+            // image arriving resized its box — reserve explicit dimensions).
+            const shifted =
+              prev != null &&
+              record?.loadedAt != null &&
+              (Math.abs(prev.width - width) > 1 || Math.abs(prev.height - height) > 1);
+            updateRecord(recordId, {
+              layout: { width, height },
+              ...(shifted ? { layoutShifts: (record?.layoutShifts ?? 0) + 1 } : {}),
+            });
+          }
+        }
+        orig.onLayout?.(event);
+      },
+    };
+
+    // Only forward-wrap the optional ones so we don't attach handlers a
+    // library doesn't support (onDisplay is expo-only; onLoadEnd is RN-only).
+    out.onLoadEnd = orig.onLoadEnd
+      ? (event) => orig.onLoadEnd?.(event)
+      : undefined;
+    if (this.lib === "expo") {
+      out.onDisplay = (event) => {
+        if (recordId != null) updateRecord(recordId, { displayedAt: Date.now() });
+        orig.onDisplay?.(event);
+      };
+    }
+
+    this.handlerCache = { key, out };
+    return out;
+  }
+}