@buoy-gg/images 7.0.3

package/src/index.tsx

@@ -0,0 +1,108 @@
+/**
+ * @buoy-gg/images
+ *
+ * Image debugger for React Native: a live registry of every image the app
+ * loads — RN core <Image> (via the official component-decorator hook) and
+ * expo-image (via a timing-immune class patch) — with cache verdicts
+ * (memory/disk/network), load timings, decoded-vs-displayed oversize checks,
+ * estimated decoded/wasted memory, and a failure log with HTTP details where
+ * the platform provides them.
+ *
+ * Image HTTP traffic never touches the JS network stack, so network devtools
+ * cannot see it — this tool is the visibility layer for images.
+ */
+
+// Side-effect: install capture as early as this package is imported. For full
+// RN-core coverage, import "@buoy-gg/images/register" FIRST in your entry file
+// (the RN decorator must beat React Native's Image module evaluation).
+import "./register";
+
+// =============================================================================
+// PRESET (Primary entry point — pass to <FloatingDevTools apps={[...]} />)
+// =============================================================================
+export { imagesToolPreset, createImagesTool } from "./preset";
+
+// =============================================================================
+// ROOT (optional; capture also auto-installs on package import)
+// =============================================================================
+export { ImagesRoot } from "./components/ImagesRoot";
+
+// =============================================================================
+// COMPONENTS
+// =============================================================================
+export { ImagesModal } from "./components/ImagesModal";
+export { ImagesIcon, IMAGES_ICON_COLOR } from "./components/ImagesIcon";
+
+// =============================================================================
+// CAPTURE
+// =============================================================================
+export { installImageCapture, getCaptureStatus } from "./capture/install";
+
+// =============================================================================
+// ACTIONS
+// =============================================================================
+export {
+  hardReloadRecord,
+  retryRecord,
+  evictExpoDiskEntry,
+} from "./capture/actions";
+export type { ActionResult } from "./capture/actions";
+
+// =============================================================================
+// SIMULATION OVERRIDES
+// =============================================================================
+export {
+  setOverride,
+  clearOverride,
+  getOverride,
+  flashRecord,
+  setNetworkMode,
+  setBlankImages,
+  getGlobalModes,
+  setOverrideForAllMounted,
+  clearAllOverrides,
+  flashAllMounted,
+} from "./capture/overrides";
+export { hardReloadAllMounted } from "./capture/actions";
+export type { ImageOverride, OverrideSource, NetworkMode } from "./capture/overrides";
+
+// =============================================================================
+// SAVINGS PROVER + INSIGHTS
+// =============================================================================
+export { proveSavings } from "./capture/savings";
+export type { SavingsResult } from "./capture/savings";
+export { computeInsights, insightChips } from "./store/insights";
+export { formatRecordMarkdown, formatRegistryMarkdown } from "./export";
+
+// =============================================================================
+// EXTERNAL SYNC (device → desktop dashboard / MCP)
+// =============================================================================
+export { imagesSyncAdapter } from "./sync/imagesSyncAdapter";
+
+// =============================================================================
+// STORE + HOOKS
+// =============================================================================
+export { useImageRecords } from "./hooks/useImageRecords";
+export {
+  clearRecords,
+  getSnapshot as getImageRecords,
+  subscribe as subscribeImageRecords,
+  computeStats,
+  oversizeFactor,
+  estDecodedBytes,
+  estWastedBytes,
+} from "./store/imageEventStore";
+
+// =============================================================================
+// TYPES
+// =============================================================================
+export type {
+  ImageRecord,
+  ImageStats,
+  ImageInsights,
+  ImageLib,
+  ImageStatus,
+  CacheVerdict,
+  SourceKind,
+  CaptureStatus,
+} from "./types";

package/src/preset.tsx

@@ -0,0 +1,35 @@
+/**
+ * Pre-configured Images tool for FloatingDevTools.
+ *
+ * @example
+ * ```tsx
+ * import { imagesToolPreset } from '@buoy-gg/images';
+ *
+ * <FloatingDevTools apps={[imagesToolPreset]} />
+ * ```
+ */
+
+import { ImagesIcon, IMAGES_ICON_COLOR } from "./components/ImagesIcon";
+import { ImagesModal } from "./components/ImagesModal";
+
+export const imagesToolPreset = {
+  id: "images",
+  name: "IMAGES",
+  description: "Image loads, caching, failures, and oversize checks",
+  slot: "both" as const,
+  icon: ({ size, color }: { size: number; color?: string }) => (
+    <ImagesIcon size={size} color={color || IMAGES_ICON_COLOR} />
+  ),
+  component: ImagesModal,
+};
+
+/** Create a custom Images tool configuration. */
+export function createImagesTool(
+  options: { name?: string; description?: string } = {}
+) {
+  return {
+    ...imagesToolPreset,
+    name: options.name ?? imagesToolPreset.name,
+    description: options.description ?? imagesToolPreset.description,
+  };
+}

package/src/register.ts

@@ -0,0 +1,17 @@
+/**
+ * Side-effect entry: installs image capture on import.
+ *
+ * Import this FIRST in your app entry file so the RN-core <Image> decorator
+ * lands before React Native's Image module is evaluated:
+ *
+ * ```ts
+ * import "@buoy-gg/images/register";
+ * ```
+ *
+ * This module intentionally imports nothing that touches react-native's Image
+ * (directly or transitively) before installing.
+ */
+
+import { installImageCapture } from "./capture/install";
+
+installImageCapture();

package/src/state.ts

@@ -0,0 +1,88 @@
+/**
+ * Global singleton state for the Images tool.
+ *
+ * The package can get evaluated twice as two separate module instances (e.g.
+ * the `/register` entry shim resolving to one copy while the package root
+ * import resolves to another — lib vs src). If capture state lived in module
+ * scope, the early copy would install the RN decorator and collect records
+ * while the UI copy read an empty store and a false "decorator never ran"
+ * flag. Keying all mutable state on globalThis under a well-known symbol makes
+ * every copy operate on the same data.
+ */
+
+import type { ImageRecord } from "./types";
+
+export interface ImagesGlobalState {
+  // store
+  records: ImageRecord[];
+  byId: Map<number, ImageRecord>;
+  nextId: number;
+  listeners: Set<() => void>;
+  snapshot: ImageRecord[];
+  emitScheduled: boolean;
+  // install flags
+  captureInstalled: boolean;
+  rnInstalled: boolean;
+  expoInstalled: boolean;
+  // rn decorator status
+  decoratorRegistered: boolean;
+  decoratorInvoked: boolean;
+  attachSeen: number;
+  // expo patch status
+  expoAvailable: boolean;
+  expoPatched: boolean;
+  // actions
+  /** recordId → pending reload request for the RN wrapper to consume. */
+  reloadRequests: Map<number, { nonce: number; bust: boolean }>;
+  /** Notified when a reload request is issued (wrappers re-check their nonce). */
+  actionListeners: Set<() => void>;
+  /** recordId → live expo-image class instance (has reloadAsync etc.). */
+  expoInstances: Map<number, unknown>;
+  // simulation overrides
+  /** recordId → active override (source swap / forced error / style merge). */
+  overrides: Map<number, unknown>;
+  /** recordId → epoch-ms until which the locate-flash border is shown. */
+  flashUntil: Map<number, number>;
+  /** Per-record render version (bumped by any action touching that record). */
+  recordVersions: Map<number, number>;
+  /** Render version for global-mode changes (affects every image). */
+  globalVersion: number;
+  /** Monotonic counter feeding both version maps. */
+  versionCounter: number;
+  /** App-wide simulation modes. */
+  globalModes: { network: "normal" | "offline" | "cold"; blank: boolean };
+}
+
+const KEY = Symbol.for("buoy.images.globalState.v1");
+
+export function imagesState(): ImagesGlobalState {
+  const g = globalThis as Record<symbol, ImagesGlobalState | undefined>;
+  if (!g[KEY]) {
+    g[KEY] = {
+      records: [],
+      byId: new Map(),
+      nextId: 1,
+      listeners: new Set(),
+      snapshot: [],
+      emitScheduled: false,
+      captureInstalled: false,
+      rnInstalled: false,
+      expoInstalled: false,
+      decoratorRegistered: false,
+      decoratorInvoked: false,
+      attachSeen: 0,
+      expoAvailable: false,
+      expoPatched: false,
+      reloadRequests: new Map(),
+      actionListeners: new Set(),
+      expoInstances: new Map(),
+      overrides: new Map(),
+      flashUntil: new Map(),
+      recordVersions: new Map(),
+      globalVersion: 0,
+      versionCounter: 0,
+      globalModes: { network: "normal", blank: false },
+    };
+  }
+  return g[KEY];
+}

package/src/store/imageEventStore.ts

@@ -0,0 +1,162 @@
+/**
+ * imageEventStore
+ *
+ * Bounded buffer of ImageRecords fed by the capture layer (installRnImage /
+ * installExpoImage). Follows the console tool's store shape — Set of
+ * listeners, frame-coalesced emit so bursty image grids don't turn every
+ * event into its own React commit — but ALL mutable state lives on the
+ * globalThis singleton (see ../state.ts) so a dual module instance of this
+ * package still reads/writes one shared store.
+ */
+
+import { PixelRatio } from "react-native";
+import { imagesState } from "../state";
+import type { ImageRecord, ImageStats } from "../types";
+
+/** Max records retained before the oldest are dropped. */
+const MAX_RECORDS = 500;
+
+function emit(): void {
+  const s = imagesState();
+  if (s.emitScheduled) return;
+  s.emitScheduled = true;
+  requestAnimationFrame(() => {
+    s.emitScheduled = false;
+    for (const listener of s.listeners) listener();
+  });
+}
+
+/** Snapshot identity only changes on emit, so useSyncExternalStore stays cheap. */
+function invalidate(): void {
+  const s = imagesState();
+  s.snapshot = [...s.records];
+  emit();
+}
+
+export function createRecord(
+  partial: Omit<ImageRecord, "id" | "createdAt" | "loadCount" | "mounted" | "status">
+): ImageRecord {
+  const s = imagesState();
+  const record: ImageRecord = {
+    ...partial,
+    id: s.nextId++,
+    createdAt: Date.now(),
+    status: "pending",
+    mounted: true,
+    loadCount: 0,
+  };
+  s.records.push(record);
+  s.byId.set(record.id, record);
+  if (s.records.length > MAX_RECORDS) {
+    const dropped = s.records.splice(0, s.records.length - MAX_RECORDS);
+    for (const d of dropped) s.byId.delete(d.id);
+  }
+  invalidate();
+  return record;
+}
+
+/** Mutate a record in place (records are owned by the store) and notify. */
+export function updateRecord(
+  id: number,
+  patch: Partial<ImageRecord>
+): ImageRecord | undefined {
+  const s = imagesState();
+  const record = s.byId.get(id);
+  if (!record) return undefined;
+  Object.assign(record, patch);
+  invalidate();
+  return record;
+}
+
+export function getRecord(id: number): ImageRecord | undefined {
+  return imagesState().byId.get(id);
+}
+
+export function getSnapshot(): ImageRecord[] {
+  return imagesState().snapshot;
+}
+
+export function subscribe(listener: () => void): () => void {
+  const s = imagesState();
+  s.listeners.add(listener);
+  return () => imagesState().listeners.delete(listener);
+}
+
+export function clearRecords(): void {
+  const s = imagesState();
+  // Keep records still actively loading so in-flight events don't orphan.
+  s.records = s.records.filter(
+    (r) => r.mounted && r.status !== "loaded" && r.status !== "error"
+  );
+  s.byId = new Map(s.records.map((r) => [r.id, r]));
+  invalidate();
+}
+
+// ---------------------------------------------------------------------------
+// Derived math (shared by rows, detail view, and stats)
+// ---------------------------------------------------------------------------
+
+/** Physical pixels actually needed to fill the laid-out view 1:1. */
+export function neededPixels(record: ImageRecord): { width: number; height: number } | null {
+  if (!record.layout || record.layout.width <= 0 || record.layout.height <= 0) return null;
+  const scale = PixelRatio.get();
+  return {
+    width: Math.round(record.layout.width * scale),
+    height: Math.round(record.layout.height * scale),
+  };
+}
+
+/**
+ * Linear oversize factor: how many times larger (per axis, area-normalized)
+ * the decoded bitmap is vs what the view needs. 1 = perfect, 2 = 4× the pixels.
+ */
+export function oversizeFactor(record: ImageRecord): number | null {
+  const needed = neededPixels(record);
+  if (!needed || !record.intrinsic) return null;
+  const neededArea = needed.width * needed.height;
+  const intrinsicArea = record.intrinsic.width * record.intrinsic.height;
+  if (neededArea <= 0 || intrinsicArea <= 0) return null;
+  return Math.sqrt(intrinsicArea / neededArea);
+}
+
+/** Estimated decoded-bitmap memory for a loaded record (RGBA8888). */
+export function estDecodedBytes(record: ImageRecord): number {
+  if (!record.intrinsic) return 0;
+  return record.intrinsic.width * record.intrinsic.height * 4;
+}
+
+/** Decoded bytes beyond what the laid-out size needs (0 if not oversized). */
+export function estWastedBytes(record: ImageRecord): number {
+  const needed = neededPixels(record);
+  if (!needed || !record.intrinsic) return 0;
+  const wasted =
+    (record.intrinsic.width * record.intrinsic.height -
+      needed.width * needed.height) *
+    4;
+  return Math.max(0, wasted);
+}
+
+export function computeStats(list: ImageRecord[]): ImageStats {
+  const stats: ImageStats = {
+    total: list.length,
+    loading: 0,
+    loaded: 0,
+    errors: 0,
+    networkLoads: 0,
+    estDecodedBytes: 0,
+    estWastedBytes: 0,
+  };
+  for (const r of list) {
+    // Unmounted in-flight records are stale (the instance died mid-load) —
+    // they must not count as live in-flight work.
+    if ((r.status === "loading" || r.status === "pending") && r.mounted) stats.loading++;
+    if (r.status === "loaded") stats.loaded++;
+    if (r.status === "error") stats.errors++;
+    if (r.progressSeen || r.cacheVerdict === "none") stats.networkLoads++;
+    if (r.mounted && r.status === "loaded") {
+      stats.estDecodedBytes += estDecodedBytes(r);
+      stats.estWastedBytes += estWastedBytes(r);
+    }
+  }
+  return stats;
+}

package/src/store/insights.ts

@@ -0,0 +1,66 @@
+/**
+ * Cross-record insights — findings computed purely from data the registry
+ * already holds (no extra instrumentation): duplicate simultaneous loads,
+ * retry storms, iOS image-queue saturation, missing alt text, and
+ * layout-shifting images.
+ */
+
+import type { ImageInsights, ImageRecord } from "../types";
+
+/** loadCount at/above this flags render-thrash reload storms. */
+const RETRY_STORM_THRESHOLD = 5;
+/** RCTImageLoader allows 4 concurrent loading tasks on iOS. */
+const IOS_CONCURRENT_LOAD_LIMIT = 4;
+
+export function computeInsights(records: ImageRecord[]): ImageInsights {
+  const byUri = new Map<string, number>();
+  const retryStorms: ImageInsights["retryStorms"] = [];
+  const layoutShifters: ImageInsights["layoutShifters"] = [];
+  let missingAlt = 0;
+  let rnLoading = 0;
+
+  for (const r of records) {
+    if (r.mounted && r.uri) {
+      byUri.set(r.uri, (byUri.get(r.uri) ?? 0) + 1);
+    }
+    if (r.loadCount >= RETRY_STORM_THRESHOLD) {
+      retryStorms.push({ id: r.id, uri: r.uri, loadCount: r.loadCount });
+    }
+    if ((r.layoutShifts ?? 0) > 0) {
+      layoutShifters.push({ id: r.id, uri: r.uri, shifts: r.layoutShifts ?? 0 });
+    }
+    if (r.mounted && r.hasAltText === false) missingAlt++;
+    if (r.lib === "rn" && r.mounted && r.status === "loading") rnLoading++;
+  }
+
+  const duplicates = [...byUri.entries()]
+    .filter(([, count]) => count > 1)
+    .map(([uri, count]) => ({ uri, count }))
+    .sort((a, b) => b.count - a.count);
+
+  return {
+    duplicates,
+    retryStorms: retryStorms.sort((a, b) => b.loadCount - a.loadCount),
+    queueSaturated: rnLoading > IOS_CONCURRENT_LOAD_LIMIT,
+    missingAlt,
+    layoutShifters,
+  };
+}
+
+/** Compact one-line chips for UI/MCP surfacing. Empty array = all clear. */
+export function insightChips(insights: ImageInsights): string[] {
+  const chips: string[] = [];
+  if (insights.duplicates.length > 0) {
+    const extra = insights.duplicates.reduce((n, d) => n + d.count - 1, 0);
+    chips.push(`${insights.duplicates.length} duplicate URL${insights.duplicates.length > 1 ? "s" : ""} (${extra} redundant loads)`);
+  }
+  if (insights.retryStorms.length > 0) {
+    chips.push(`${insights.retryStorms.length} retry storm${insights.retryStorms.length > 1 ? "s" : ""}`);
+  }
+  if (insights.queueSaturated) chips.push("iOS image queue saturated (>4 loading)");
+  if (insights.missingAlt > 0) chips.push(`${insights.missingAlt} missing alt text`);
+  if (insights.layoutShifters.length > 0) {
+    chips.push(`${insights.layoutShifters.length} layout-shifting image${insights.layoutShifters.length > 1 ? "s" : ""}`);
+  }
+  return chips;
+}