@buoy-gg/images 7.0.29 → 7.0.30

package/src/capture/overrides.ts

@@ -1,332 +0,0 @@
-/**
- * Simulation overrides — the "we own the props" tier of actions.
- *
- * Because the RN decorator and the expo-image render patch control every
- * mounted image's props, anything the component accepts is a simulation:
- * forced errors (instant, offline-safe file:// source), forced loading
- * (blackhole-IP source that never resolves), URL swaps, blanking, style
- * merges (locate-flash border), and app-wide modes (offline images /
- * cold-start / blank images).
- *
- * Re-render plumbing: every mutation bumps a per-record or global version.
- * RN wrappers subscribe via useSyncExternalStore with a per-record snapshot
- * (only the touched image re-renders); expo class instances are re-rendered
- * directly via forceUpdate() from the per-record instance registry.
- */
-
-import { remoteImagesDispatch } from "../remote";
-import { imagesState } from "../state";
-import { getRecord, getSnapshot, updateRecord } from "../store/imageEventStore";
-import type { ImageLib } from "../types";
-
-// ---------------------------------------------------------------------------
-// Override model
-// ---------------------------------------------------------------------------
-
-export type OverrideSource =
-  | { type: "url"; uri: string }
-  /** Nonexistent file:// — native fires onError immediately, no network needed. */
-  | { type: "error" }
-  /** Blackhole IP — the request hangs, onLoad never fires (loading forever). */
-  | { type: "hang" }
-  /** No source at all (expo keeps showing its placeholder). */
-  | { type: "blank" };
-
-export interface ImageOverride {
-  source?: OverrideSource;
-  /** Merged over the app's style (size experiments etc.). */
-  style?: Record<string, unknown>;
-  /** Extra props merged last (expo contentFit, priority, cachePolicy…). */
-  extraProps?: Record<string, unknown>;
-  /** Shown as the record's override badge, e.g. "Forced error". */
-  label: string;
-}
-
-const FORCED_ERROR_URI = "file:///buoy-images-forced-error.png";
-const HANG_URI = "https://10.255.255.1/buoy-images-hang.png";
-/** Offline mode replaces network sources with this (fails immediately). */
-const OFFLINE_URI = "file:///buoy-images-offline-no-network.png";
-const FLASH_STYLE = { borderWidth: 3, borderColor: "#FF453A" } as const;
-/**
- * RN core has NO safe "empty source": undefined resolves to the app bundle
- * path and [] does too on RN 0.85 — both fire a bogus onError ("The file …
- * couldn't be opened", observed live). So RN images blank via opacity
- * instead (visual-only; the decoded image stays resident). expo-image
- * supports a true `source={null}` and keeps showing its placeholder.
- */
-const RN_BLANK_STYLE = { opacity: 0 } as const;
-
-export type NetworkMode = "normal" | "offline" | "cold";
-
-// ---------------------------------------------------------------------------
-// Version bus (re-render triggers)
-// ---------------------------------------------------------------------------
-
-function emit(): void {
-  for (const l of imagesState().actionListeners) l();
-}
-
-function forceUpdateExpo(recordId?: number): void {
-  const s = imagesState();
-  if (recordId != null) {
-    const instance = s.expoInstances.get(recordId) as
-      | { forceUpdate?: () => void }
-      | undefined;
-    instance?.forceUpdate?.();
-    return;
-  }
-  for (const instance of s.expoInstances.values()) {
-    (instance as { forceUpdate?: () => void })?.forceUpdate?.();
-  }
-}
-
-/** Bump one record's render version (re-renders just that image). */
-export function touchRecord(recordId: number): void {
-  const s = imagesState();
-  s.recordVersions.set(recordId, ++s.versionCounter);
-  emit();
-  forceUpdateExpo(recordId);
-}
-
-/** Bump the global render version (re-renders every wrapped image). */
-export function touchGlobal(): void {
-  const s = imagesState();
-  s.globalVersion = ++s.versionCounter;
-  emit();
-  forceUpdateExpo();
-}
-
-/** Snapshot for the RN wrapper's useSyncExternalStore. */
-export function getRenderVersion(recordId: number | null): number {
-  const s = imagesState();
-  const record = recordId != null ? (s.recordVersions.get(recordId) ?? 0) : 0;
-  return Math.max(record, s.globalVersion);
-}
-
-// ---------------------------------------------------------------------------
-// Per-record overrides
-// ---------------------------------------------------------------------------
-
-/** Remote param shape for the adapter's `setOverride` action. */
-function overrideParams(
-  recordId: number,
-  source: OverrideSource
-): Record<string, unknown> {
-  return source.type === "url"
-    ? { id: recordId, kind: "url", uri: source.uri }
-    : { id: recordId, kind: source.type };
-}
-
-/**
- * Local bookkeeping only (no remote forward) — mirrors keep this as an
- * optimistic UI update; the next device snapshot is the source of truth.
- */
-function setOverrideLocal(recordId: number, override: ImageOverride): void {
-  imagesState().overrides.set(recordId, override);
-  updateRecord(recordId, { overrideLabel: override.label });
-  touchRecord(recordId);
-}
-
-export function setOverride(recordId: number, override: ImageOverride): void {
-  if (override.source) {
-    void remoteImagesDispatch()?.(
-      "setOverride",
-      overrideParams(recordId, override.source)
-    );
-  }
-  setOverrideLocal(recordId, override);
-}
-
-function clearOverrideLocal(recordId: number): void {
-  imagesState().overrides.delete(recordId);
-  updateRecord(recordId, { overrideLabel: undefined });
-  touchRecord(recordId);
-}
-
-export function clearOverride(recordId: number): void {
-  void remoteImagesDispatch()?.("clearOverride", { id: recordId });
-  clearOverrideLocal(recordId);
-}
-
-export function getOverride(recordId: number | null): ImageOverride | undefined {
-  if (recordId == null) return undefined;
-  return imagesState().overrides.get(recordId) as ImageOverride | undefined;
-}
-
-// ---------------------------------------------------------------------------
-// Mass actions (every mounted image at once)
-// ---------------------------------------------------------------------------
-
-/** Adapter `massAction` kind for a mass override (per-record 'hang' is mass 'loading'). */
-function massKind(source: OverrideSource): string {
-  return source.type === "hang" ? "loading" : source.type;
-}
-
-/** Apply one override to every mounted record. Returns how many were hit. */
-export function setOverrideForAllMounted(source: OverrideSource, label: string): number {
-  // One mass action on the device, not N per-record forwards.
-  void remoteImagesDispatch()?.("massAction", { kind: massKind(source) });
-  let count = 0;
-  for (const record of getSnapshot()) {
-    if (!record.mounted) continue;
-    setOverrideLocal(record.id, { source, label });
-    count++;
-  }
-  return count;
-}
-
-/** Remove every active override. Returns how many were cleared. */
-export function clearAllOverrides(): number {
-  void remoteImagesDispatch()?.("massAction", { kind: "restore" });
-  // Mirrors track labels on records, not the overrides map — clear both.
-  const ids = new Set<number>(imagesState().overrides.keys());
-  for (const record of getSnapshot()) {
-    if (record.overrideLabel != null) ids.add(record.id);
-  }
-  for (const id of ids) clearOverrideLocal(id);
-  return ids.size;
-}
-
-/** Flash every mounted image (locate everything the tool tracks). */
-export function flashAllMounted(durationMs = 2500): number {
-  void remoteImagesDispatch()?.("massAction", { kind: "flash" });
-  let count = 0;
-  for (const record of getSnapshot()) {
-    if (!record.mounted) continue;
-    flashRecordLocal(record.id, durationMs);
-    count++;
-  }
-  return count;
-}
-
-function flashRecordLocal(recordId: number, durationMs = 2500): void {
-  const s = imagesState();
-  s.flashUntil.set(recordId, Date.now() + durationMs);
-  touchRecord(recordId);
-  setTimeout(() => {
-    imagesState().flashUntil.delete(recordId);
-    touchRecord(recordId);
-  }, durationMs + 50);
-}
-
-/** Flash a border on the on-screen image so it can be located visually. */
-export function flashRecord(recordId: number, durationMs = 2500): void {
-  void remoteImagesDispatch()?.("flash", { id: recordId });
-  flashRecordLocal(recordId, durationMs);
-}
-
-// ---------------------------------------------------------------------------
-// Global simulation modes
-// ---------------------------------------------------------------------------
-
-/**
- * offline — every NETWORK image load fails immediately (both libs, cache or
- *   not); bundled/local assets still load, like a real offline device showing
- *   shipped images. Blunt on purpose: toggle + reload = images visibly gone.
- *   (The subtler `only-if-cached` variant was correct-but-confusing, and its
- *   uncached requests HANG on iOS instead of erroring — bad for QA.)
- * cold — every image bypasses caches (RN `cache:'reload'`, expo
- *   `cachePolicy:'none'`): first-launch behavior without clearing anything.
- */
-export function setNetworkMode(mode: NetworkMode): void {
-  void remoteImagesDispatch()?.("setNetworkMode", { mode });
-  imagesState().globalModes.network = mode;
-  touchGlobal();
-}
-
-/** Chrome-style "disable images": render every image without a source. */
-export function setBlankImages(enabled: boolean): void {
-  void remoteImagesDispatch()?.("setBlankImages", { enabled });
-  imagesState().globalModes.blank = enabled;
-  touchGlobal();
-}
-
-export function getGlobalModes(): { network: NetworkMode; blank: boolean } {
-  return imagesState().globalModes;
-}
-
-// ---------------------------------------------------------------------------
-// Application (called from the RN wrapper + expo render patch)
-// ---------------------------------------------------------------------------
-
-/** Inject a `cache` policy into an RN source (object or array shape). */
-export function patchSourceCache(source: unknown, cache: string): unknown {
-  if (Array.isArray(source)) {
-    return source.map((entry) =>
-      entry && typeof entry === "object" && typeof (entry as { uri?: unknown }).uri === "string"
-        ? { ...(entry as object), cache }
-        : entry
-    );
-  }
-  if (source && typeof source === "object" && typeof (source as { uri?: unknown }).uri === "string") {
-    return { ...(source as object), cache };
-  }
-  return source; // numeric assets etc. — nothing to patch
-}
-
-function resolveOverrideSource(source: OverrideSource, lib: ImageLib): unknown {
-  switch (source.type) {
-    case "url":
-      return { uri: source.uri };
-    case "error":
-      return { uri: FORCED_ERROR_URI };
-    case "hang":
-      return { uri: HANG_URI };
-    case "blank":
-      // Only reached for expo — RN blanking is style-based (see RN_BLANK_STYLE).
-      return null;
-  }
-}
-
-/**
- * Merge global modes + per-record override + locate-flash into an
- * already-copied props object. Mutates and returns `out`.
- */
-export function applyOverrides(
-  out: Record<string, unknown>,
-  recordId: number | null,
-  lib: ImageLib
-): Record<string, unknown> {
-  const s = imagesState();
-  const modes = s.globalModes;
-
-  if (modes.network === "offline") {
-    // Hard offline: network sources fail outright (both libs); bundled/local
-    // assets keep loading like a real offline device.
-    const record = recordId != null ? getRecord(recordId) : undefined;
-    if (record?.sourceKind === "network") {
-      out.source = { uri: OFFLINE_URI };
-    }
-  } else if (modes.network === "cold") {
-    if (lib === "rn") {
-      out.source = patchSourceCache(out.source, "reload");
-    } else {
-      out.cachePolicy = "none";
-    }
-  }
-  if (modes.blank) {
-    if (lib === "expo") out.source = null;
-    else out.style = [out.style, RN_BLANK_STYLE];
-  }
-
-  const override = getOverride(recordId);
-  if (override) {
-    if (override.source) {
-      if (override.source.type === "blank" && lib === "rn") {
-        out.style = [out.style, RN_BLANK_STYLE];
-      } else {
-        out.source = resolveOverrideSource(override.source, lib);
-      }
-    }
-    if (override.extraProps) Object.assign(out, override.extraProps);
-    if (override.style) out.style = [out.style, override.style];
-  }
-
-  if (recordId != null) {
-    const until = s.flashUntil.get(recordId);
-    if (until != null && until > Date.now()) {
-      out.style = [out.style, FLASH_STYLE];
-    }
-  }
-  return out;
-}

package/src/capture/savings.ts

@@ -1,204 +0,0 @@
-/**
- * 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 { remoteImagesDispatch } from "../remote";
-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> {
-  // Mirror mode: the re-encode must happen ON DEVICE (that's the whole point —
-  // real bytes from the real encoder); forward and relay the result.
-  const remote = remoteImagesDispatch();
-  if (remote) {
-    try {
-      return (await remote("proveSavings", { id: record.id })) as SavingsResult;
-    } catch (error) {
-      return { ok: false, message: String((error as Error)?.message ?? error) };
-    }
-  }
-  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;
-}