@buoy-gg/images 7.0.3

package/src/capture/installExpoImage.ts

@@ -0,0 +1,115 @@
+/**
+ * expo-image interception via class-prototype patch.
+ *
+ * expo-image's <Image> is a class component (React.PureComponent) whose
+ * render() reads `this.props`, so wrapping the prototype's render and swapping
+ * `this.props` for an instrumented copy for the duration of the original
+ * render is timing-immune (prototype methods are looked up dynamically — no
+ * import-order race like the RN core decorator). Props are restored in
+ * `finally`, so PureComponent's shouldComponentUpdate still compares the
+ * app's real props.
+ *
+ * Double-patch safety: install flags live on the globalThis singleton AND a
+ * marker is stamped on the prototype itself, so even two module instances of
+ * this package can't wrap render() twice.
+ *
+ * expo-image is an optional peer: if it isn't installed, this is a no-op.
+ */
+
+import { imagesState } from "../state";
+import { registerExpoInstance } from "./actions";
+import { applyOverrides } from "./overrides";
+import { ImageInstanceTracker, isInternalImage } from "./shared";
+import type { OriginalHandlers } from "./shared";
+
+interface ExpoImageInstance {
+  props: Record<string, unknown>;
+}
+
+const PATCH_MARKER = "__buoyImagesPatched";
+
+const trackers = new WeakMap<object, ImageInstanceTracker>();
+
+function trackerFor(instance: object): ImageInstanceTracker {
+  let tracker = trackers.get(instance);
+  if (!tracker) {
+    tracker = new ImageInstanceTracker("expo");
+    trackers.set(instance, tracker);
+  }
+  return tracker;
+}
+
+export function installExpoImageInterceptor(): void {
+  const s = imagesState();
+  if (s.expoInstalled) return;
+  s.expoInstalled = true;
+
+  let ImageClass:
+    | {
+        prototype: ExpoImageInstance & {
+          render: () => unknown;
+          componentWillUnmount?: () => void;
+          [PATCH_MARKER]?: boolean;
+        };
+      }
+    | undefined;
+  try {
+    ImageClass = require("expo-image").Image;
+  } catch {
+    s.expoAvailable = false;
+    return; // expo-image not installed in this app
+  }
+  if (!ImageClass?.prototype?.render) {
+    s.expoAvailable = false;
+    return;
+  }
+  s.expoAvailable = true;
+
+  const proto = ImageClass.prototype;
+  if (proto[PATCH_MARKER]) {
+    s.expoPatched = true;
+    return; // already patched by another module instance of this package
+  }
+  proto[PATCH_MARKER] = true;
+
+  const originalRender = proto.render;
+  const originalUnmount = proto.componentWillUnmount;
+
+  proto.render = function buoyImagesRender(this: ExpoImageInstance) {
+    const originalProps = this.props;
+    if (isInternalImage(originalProps?.testID)) {
+      return originalRender.call(this);
+    }
+    const tracker = trackerFor(this);
+    tracker.syncSource(originalProps?.source);
+    tracker.noteA11y(
+      Boolean(originalProps?.alt ?? originalProps?.accessibilityLabel)
+    );
+    // Keep the action layer pointed at the live instance (reloadAsync etc.).
+    registerExpoInstance(tracker.getRecordId(), this);
+    const wrapped = tracker.handlers(originalProps as OriginalHandlers);
+    try {
+      // Simulation layer: global modes + per-record override + locate-flash.
+      this.props = applyOverrides(
+        { ...originalProps, ...wrapped },
+        tracker.getRecordId(),
+        "expo"
+      );
+      return originalRender.call(this);
+    } finally {
+      this.props = originalProps;
+    }
+  };
+
+  proto.componentWillUnmount = function buoyImagesUnmount(this: ExpoImageInstance) {
+    trackers.get(this)?.unmount();
+    originalUnmount?.call(this);
+  };
+
+  s.expoPatched = true;
+}
+
+export function expoCaptureStatus(): { available: boolean; patched: boolean } {
+  const s = imagesState();
+  return { available: s.expoAvailable, patched: s.expoPatched };
+}

package/src/capture/installRnImage.tsx

@@ -0,0 +1,133 @@
+/**
+ * RN core <Image> interception via the official injection hook.
+ *
+ * `unstable_setImageComponentDecorator` wraps EVERY RN <Image> app-wide — but
+ * the decorator is latched ONCE, at Image module evaluation
+ * (`Image.ios.js` / `Image.android.js` read it at module scope). So install
+ * order matters: this must run before anything touches `Image` from
+ * 'react-native' — hence the `@buoy-gg/images/register` first-import.
+ *
+ * Detection strategy: the decorator sets `decoratorInvoked` when RN's Image
+ * module applies it. `unstable_registerImageAttachedCallback` is a live Set
+ * (never latched), so image mounts are always visible — if mounts happen but
+ * the decorator never ran, we were too late and CaptureStatus reports it.
+ *
+ * All flags live on the globalThis singleton (../state.ts) so a second module
+ * instance of this package neither re-installs nor reports a stale status.
+ */
+
+import * as React from "react";
+import { imagesState } from "../state";
+import {
+  getReloadNonce,
+  getReloadRequest,
+  subscribeActions,
+} from "./actions";
+import { applyOverrides, getRenderVersion, patchSourceCache } from "./overrides";
+import { ImageInstanceTracker, isInternalImage } from "./shared";
+import type { OriginalHandlers } from "./shared";
+
+/** Wraps one RN Image render with capture instrumentation + reload actions. */
+function useImageCapture(props: Record<string, unknown>): {
+  props: Record<string, unknown>;
+  reloadKey: number;
+} {
+  const trackerRef = React.useRef<ImageInstanceTracker | null>(null);
+  if (trackerRef.current == null) {
+    trackerRef.current = new ImageInstanceTracker("rn");
+  }
+  const tracker = trackerRef.current;
+
+  const internal = isInternalImage(props.testID);
+  if (!internal) {
+    tracker.syncSource(props.source);
+    tracker.noteA11y(
+      Boolean(props.alt ?? props.accessibilityLabel ?? props["aria-label"])
+    );
+  }
+
+  // Action/override bus: version bumps re-render just this instance (snapshot
+  // is per-record with a global floor, so unrelated actions don't invalidate
+  // other images but global-mode toggles reach everyone).
+  React.useSyncExternalStore(subscribeActions, () =>
+    getRenderVersion(internal ? null : tracker.getRecordId())
+  );
+
+  React.useEffect(() => {
+    if (internal) return undefined;
+    return () => tracker.unmount();
+  }, [tracker, internal]);
+
+  if (internal) return { props, reloadKey: 0 };
+
+  const recordId = tracker.getRecordId();
+  const wrapped = tracker.handlers(props as OriginalHandlers);
+  const out: Record<string, unknown> = { ...props, ...wrapped };
+
+  // While a bust request is pending (cleared when the load settles), refetch
+  // bypassing caches — VERIFIED both platforms honor source.cache: 'reload'.
+  const request = getReloadRequest(recordId);
+  if (request?.bust) {
+    out.source = patchSourceCache(out.source, "reload");
+  }
+  // Simulation layer: global modes + per-record override + locate-flash.
+  applyOverrides(out, recordId, "rn");
+  return { props: out, reloadKey: getReloadNonce(recordId) };
+}
+
+export function installRnImageInterceptor(): void {
+  const s = imagesState();
+  if (s.rnInstalled) return;
+  s.rnInstalled = true;
+
+  try {
+    // Deep import: evaluates ONLY the injection module, never Image itself.
+    const injection = require("react-native/Libraries/Image/ImageInjection");
+
+    const setDecorator: undefined | ((d: unknown) => void) =
+      injection.unstable_setImageComponentDecorator;
+    const registerAttached: undefined | ((cb: (node: unknown) => void) => void) =
+      injection.unstable_registerImageAttachedCallback;
+
+    if (typeof setDecorator === "function") {
+      setDecorator((BaseImage: React.ComponentType<Record<string, unknown>>) => {
+        imagesState().decoratorInvoked = true;
+        const CapturedImage = React.forwardRef<unknown, Record<string, unknown>>(
+          function BuoyCapturedImage(props, ref) {
+            const { props: instrumented, reloadKey } = useImageCapture(props);
+            // key bump forces a native remount → fresh load cycle (retry).
+            return <BaseImage key={`buoy-r${reloadKey}`} {...instrumented} ref={ref} />;
+          }
+        );
+        return CapturedImage;
+      });
+      s.decoratorRegistered = true;
+    }
+
+    // Live mount signal — works regardless of decorator timing. Used purely
+    // to detect the "decorator registered too late" condition.
+    if (typeof registerAttached === "function") {
+      registerAttached(() => {
+        imagesState().attachSeen++;
+      });
+    }
+  } catch {
+    // Internal RN path moved (version drift) or non-RN platform — expo-image
+    // capture still works; status will report the decorator as inactive.
+    s.decoratorRegistered = false;
+  }
+}
+
+export function rnCaptureStatus(): {
+  decoratorRegistered: boolean;
+  decoratorActive: boolean;
+  tooLate: boolean;
+} {
+  const s = imagesState();
+  return {
+    decoratorRegistered: s.decoratorRegistered,
+    decoratorActive: s.decoratorInvoked,
+    // Mounts observed but our wrapper never rendered → Image latched first.
+    tooLate: s.decoratorRegistered && !s.decoratorInvoked && s.attachSeen > 0,
+  };
+}

package/src/capture/overrides.ts

@@ -0,0 +1,282 @@
+/**
+ * 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 { 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
+// ---------------------------------------------------------------------------
+
+export function setOverride(recordId: number, override: ImageOverride): void {
+  imagesState().overrides.set(recordId, override);
+  updateRecord(recordId, { overrideLabel: override.label });
+  touchRecord(recordId);
+}
+
+export function clearOverride(recordId: number): void {
+  imagesState().overrides.delete(recordId);
+  updateRecord(recordId, { overrideLabel: undefined });
+  touchRecord(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)
+// ---------------------------------------------------------------------------
+
+/** Apply one override to every mounted record. Returns how many were hit. */
+export function setOverrideForAllMounted(source: OverrideSource, label: string): number {
+  let count = 0;
+  for (const record of getSnapshot()) {
+    if (!record.mounted) continue;
+    setOverride(record.id, { source, label });
+    count++;
+  }
+  return count;
+}
+
+/** Remove every active override. Returns how many were cleared. */
+export function clearAllOverrides(): number {
+  const ids = [...imagesState().overrides.keys()];
+  for (const id of ids) clearOverride(id);
+  return ids.length;
+}
+
+/** Flash every mounted image (locate everything the tool tracks). */
+export function flashAllMounted(durationMs = 2500): number {
+  let count = 0;
+  for (const record of getSnapshot()) {
+    if (!record.mounted) continue;
+    flashRecord(record.id, durationMs);
+    count++;
+  }
+  return count;
+}
+
+/** Flash a border on the on-screen image so it can be located visually. */
+export function flashRecord(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);
+}
+
+// ---------------------------------------------------------------------------
+// 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 {
+  imagesState().globalModes.network = mode;
+  touchGlobal();
+}
+
+/** Chrome-style "disable images": render every image without a source. */
+export function setBlankImages(enabled: boolean): void {
+  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;
+}