@buoy-gg/images 7.0.29 → 7.0.30

package/package.json

@@ -1,14 +1,13 @@
 {
   "name": "@buoy-gg/images",
-  "version": "7.0.29",
+  "version": "7.0.30",
   "description": "Debug every image in your React Native app — live load registry, cache verdicts (memory/disk/network), timings, oversize + wasted-memory checks, and failure diagnosis for RN <Image> and expo-image. Part of Buoy devtools.",
-  "main": "lib/commonjs/index",
-  "module": "lib/module/index",
+  "main": "lib/commonjs/index.js",
+  "module": "lib/module/index.js",
   "types": "lib/typescript/index.d.ts",
-  "react-native": "src/index.tsx",
+  "react-native": "lib/module/index.js",
   "source": "src/index.tsx",
   "files": [
-    "src",
     "lib",
     "register.js",
     "register.d.ts"
@@ -18,7 +17,7 @@
     "**/index.*"
   ],
   "dependencies": {
-    "@buoy-gg/shared-ui": "^7.0.29"
+    "@buoy-gg/shared-ui": "^7.0.30"
   },
   "peerDependencies": {
     "expo-image": "*",

package/src/capture/actions.ts

@@ -1,215 +0,0 @@
-/**
- * Per-image actions: hard reload (bypass cache) and retry.
- *
- * RN core path: the decorator wrapper owns every mounted <Image>'s props, so a
- * reload request re-renders the wrapper with a bumped `key` (native remount →
- * fresh load cycle) and, for cache-busting, `source.cache: 'reload'` injected
- * — VERIFIED supported on BOTH platforms (iOS NSURLRequest policy;
- * Android ReactImageView.kt reads source."cache" → Fresco full-fetch). The
- * override stays applied until the load settles, then reverts lazily on the
- * app's next natural re-render (avoids an extra cache round-trip).
- *
- * expo-image path: the patched class instance exposes the public
- * `reloadAsync()`. Cache-busting first evicts the disk entry (cache path +
- * expo-file-system delete) and clears expo's memory cache (global — no
- * per-entry memory eviction exists), so the reload is a true refetch that
- * rewrites both cache tiers.
- */
-
-import { remoteActionResult, remoteImagesDispatch } from "../remote";
-import { imagesState } from "../state";
-import { touchRecord } from "./overrides";
-import type { ImageRecord } from "../types";
-
-// ---------------------------------------------------------------------------
-// RN reload-request bus (consumed by the decorator wrapper)
-// ---------------------------------------------------------------------------
-
-export function subscribeActions(listener: () => void): () => void {
-  const s = imagesState();
-  s.actionListeners.add(listener);
-  return () => imagesState().actionListeners.delete(listener);
-}
-
-export function getReloadRequest(
-  recordId: number | null
-): { nonce: number; bust: boolean } | undefined {
-  if (recordId == null) return undefined;
-  return imagesState().reloadRequests.get(recordId);
-}
-
-/** Reload nonce for a record (0 = never requested). Snapshot for the wrapper. */
-export function getReloadNonce(recordId: number | null): number {
-  return getReloadRequest(recordId)?.nonce ?? 0;
-}
-
-function requestRnReload(recordId: number, bust: boolean): void {
-  const s = imagesState();
-  const prev = s.reloadRequests.get(recordId);
-  s.reloadRequests.set(recordId, { nonce: (prev?.nonce ?? 0) + 1, bust });
-  // touchRecord bumps the render version (the wrapper's snapshot) and emits.
-  touchRecord(recordId);
-}
-
-/**
- * Mark a request consumed once its load settles (called from the tracker on
- * load/error). Silent — the wrapper reverts the prop override on the app's
- * next natural re-render instead of forcing an immediate one.
- */
-export function settleReloadRequest(recordId: number): void {
-  const s = imagesState();
-  const req = s.reloadRequests.get(recordId);
-  if (req?.bust) {
-    s.reloadRequests.set(recordId, { nonce: req.nonce, bust: false });
-  }
-}
-
-export function dropActionState(recordId: number): void {
-  const s = imagesState();
-  s.reloadRequests.delete(recordId);
-  s.expoInstances.delete(recordId);
-  s.overrides.delete(recordId);
-  s.flashUntil.delete(recordId);
-  s.recordVersions.delete(recordId);
-}
-
-// ---------------------------------------------------------------------------
-// expo instance registry (populated by the render patch)
-// ---------------------------------------------------------------------------
-
-export function registerExpoInstance(recordId: number | null, instance: unknown): void {
-  if (recordId == null) return;
-  imagesState().expoInstances.set(recordId, instance);
-}
-
-interface ExpoImageStatics {
-  getCachePathAsync?: (cacheKey: string) => Promise<string | null>;
-  clearMemoryCache?: () => Promise<boolean>;
-}
-
-function expoImageStatics(): ExpoImageStatics | null {
-  try {
-    return require("expo-image").Image ?? null;
-  } catch {
-    return null;
-  }
-}
-
-interface FileSystemModule {
-  deleteAsync?: (uri: string, options?: { idempotent?: boolean }) => Promise<void>;
-}
-
-/**
- * expo-file-system, legacy path first (v19+/SDK 54+ moved the function API
- * there) then the main import — same pattern as shared-ui's persistentStorage.
- */
-function loadFileSystem(): FileSystemModule | null {
-  try {
-    const mod = require("expo-file-system/legacy");
-    const fs = mod?.default || mod;
-    if (fs?.deleteAsync) return fs;
-  } catch {
-    // try main import
-  }
-  try {
-    const mod = require("expo-file-system");
-    const fs = mod?.default || mod;
-    if (fs?.deleteAsync) return fs;
-  } catch {
-    // not installed
-  }
-  return null;
-}
-
-/**
- * Delete an expo-image disk-cache entry (JS-only: cache path + file delete).
- * Returns true if an entry existed and was deleted.
- */
-export async function evictExpoDiskEntry(record: ImageRecord): Promise<boolean> {
-  const statics = expoImageStatics();
-  const fileSystem = loadFileSystem();
-  if (!statics?.getCachePathAsync || !fileSystem?.deleteAsync || !record.uri) return false;
-  try {
-    const path = await statics.getCachePathAsync(record.uri);
-    if (!path) return false;
-    const uri = path.startsWith("file://") ? path : `file://${path}`;
-    await fileSystem.deleteAsync(uri, { idempotent: true });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-// ---------------------------------------------------------------------------
-// High-level dispatchers (used by the detail view)
-// ---------------------------------------------------------------------------
-
-export type ActionResult = { ok: boolean; message: string };
-
-/** Fresh load attempt for a mounted image (no cache bypass). */
-export async function retryRecord(record: ImageRecord): Promise<ActionResult> {
-  const remote = remoteImagesDispatch();
-  if (remote) return remoteActionResult(remote("retry", { id: record.id }));
-  if (!record.mounted) {
-    return { ok: false, message: "Instance unmounted — cannot reload" };
-  }
-  if (record.lib === "expo") {
-    const instance = imagesState().expoInstances.get(record.id) as
-      | { reloadAsync?: () => Promise<void> }
-      | undefined;
-    if (!instance?.reloadAsync) {
-      return { ok: false, message: "Live instance not reachable" };
-    }
-    await instance.reloadAsync();
-    return { ok: true, message: "Reload requested" };
-  }
-  requestRnReload(record.id, false);
-  return { ok: true, message: "Remounting image" };
-}
-
-/** Hard-reload every mounted image (mass cache-bust). Returns count started. */
-export async function hardReloadAllMounted(): Promise<ActionResult> {
-  const remote = remoteImagesDispatch();
-  if (remote) {
-    return remoteActionResult(remote("massAction", { kind: "reload" }));
-  }
-  const { getSnapshot } = require("../store/imageEventStore") as {
-    getSnapshot: () => ImageRecord[];
-  };
-  let count = 0;
-  for (const record of getSnapshot()) {
-    if (!record.mounted) continue;
-    const result = await hardReloadRecord(record);
-    if (result.ok) count++;
-  }
-  return { ok: count > 0, message: `Hard-reloading ${count} mounted image${count === 1 ? "" : "s"}` };
-}
-
-/** Bypass-cache reload: refetches from network and rewrites the caches. */
-export async function hardReloadRecord(record: ImageRecord): Promise<ActionResult> {
-  const remote = remoteImagesDispatch();
-  if (remote) return remoteActionResult(remote("hardReload", { id: record.id }));
-  if (!record.mounted) {
-    return { ok: false, message: "Instance unmounted — cannot reload" };
-  }
-  if (record.sourceKind !== "network") {
-    // Local/asset sources have no HTTP cache to bust — plain remount instead.
-    return retryRecord(record);
-  }
-  if (record.lib === "expo") {
-    const evicted = await evictExpoDiskEntry(record);
-    const statics = expoImageStatics();
-    // No per-entry memory eviction exists — global clear is the honest option.
-    await statics?.clearMemoryCache?.().catch?.(() => false);
-    const result = await retryRecord(record);
-    if (!result.ok) return result;
-    return {
-      ok: true,
-      message: evicted
-        ? "Disk entry evicted, memory cache cleared, refetching"
-        : "Memory cache cleared, refetching (no disk entry found)",
-    };
-  }
-  requestRnReload(record.id, true);
-  return { ok: true, message: "Refetching with cache bypassed" };
-}

package/src/capture/install.ts

@@ -1,40 +0,0 @@
-/**
- * installImageCapture — idempotent entry point for the capture layer.
- *
- * IMPORTANT (timing): the RN-core decorator only takes effect if this runs
- * before anything evaluates the `Image` module from 'react-native'. The
- * recommended integration is `import "@buoy-gg/images/register"` as the FIRST
- * import of the app entry file. The expo-image patch has no such constraint.
- *
- * Idempotency is keyed on the globalThis singleton, so even if this package
- * gets evaluated as two module instances, capture installs exactly once.
- */
-
-import { imagesState } from "../state";
-import { installExpoImageInterceptor, expoCaptureStatus } from "./installExpoImage";
-import { installRnImageInterceptor, rnCaptureStatus } from "./installRnImage";
-import type { CaptureStatus } from "../types";
-
-export function installImageCapture(): void {
-  const s = imagesState();
-  // Mirror mode (desktop dashboard): never instrument the dashboard's own UI.
-  if (s.captureDisabled || s.captureInstalled) return;
-  s.captureInstalled = true;
-  installRnImageInterceptor();
-  installExpoImageInterceptor();
-}
-
-export function getCaptureStatus(): CaptureStatus {
-  // Mirror mode: report the synced DEVICE's capture status, not the local probe.
-  const mirrored = imagesState().mirrorCaptureStatus;
-  if (mirrored) return mirrored;
-  const rn = rnCaptureStatus();
-  const expo = expoCaptureStatus();
-  return {
-    installed: imagesState().captureInstalled,
-    rnDecoratorActive: rn.decoratorActive,
-    rnDecoratorTooLate: rn.tooLate,
-    expoPatched: expo.patched,
-    expoAvailable: expo.available,
-  };
-}

package/src/capture/installExpoImage.ts

@@ -1,115 +0,0 @@
-/**
- * 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

@@ -1,133 +0,0 @@
-/**
- * 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,
-  };
-}