@buoy-gg/images 7.0.3

package/src/sync/imagesSyncAdapter.ts

@@ -0,0 +1,261 @@
+/**
+ * Sync adapter for the Images tool, consumed by @buoy-gg/external-sync's
+ * `useExternalSync` (structurally matches its ToolSyncAdapter interface so
+ * this package doesn't need a dependency on it — same pattern as js-top's
+ * adapter). Exposes the live image registry to the desktop dashboard and the
+ * MCP server, plus every action the on-device UI has: reload/retry,
+ * simulation overrides (force error/loading/blank/URL swap), locate-flash,
+ * global modes, and cache clears.
+ */
+
+import {
+  evictExpoDiskEntry,
+  hardReloadAllMounted,
+  hardReloadRecord,
+  retryRecord,
+} from "../capture/actions";
+import { getCaptureStatus } from "../capture/install";
+import {
+  clearAllOverrides,
+  clearOverride,
+  flashAllMounted,
+  flashRecord,
+  getGlobalModes,
+  setBlankImages,
+  setNetworkMode,
+  setOverride,
+  setOverrideForAllMounted,
+} from "../capture/overrides";
+import { proveSavings } from "../capture/savings";
+import { computeInsights } from "../store/insights";
+import type { NetworkMode, OverrideSource } from "../capture/overrides";
+import {
+  clearRecords,
+  computeStats,
+  estDecodedBytes,
+  estWastedBytes,
+  getRecord,
+  getSnapshot,
+  neededPixels,
+  oversizeFactor,
+  subscribe,
+} from "../store/imageEventStore";
+import type { ImageRecord } from "../types";
+
+/** Slim wire form of a record (heavy/derived fields precomputed + rounded). */
+function toWire(record: ImageRecord) {
+  const factor = oversizeFactor(record);
+  return {
+    id: record.id,
+    lib: record.lib,
+    uri: record.uri,
+    kind: record.sourceKind,
+    status: record.status,
+    mounted: record.mounted,
+    cache: record.cacheVerdict ?? null,
+    cacheSource: record.cacheVerdictSource ?? null,
+    ms: record.durationMs != null ? Math.round(record.durationMs) : null,
+    intrinsic: record.intrinsic ?? null,
+    layout: record.layout
+      ? {
+          width: Math.round(record.layout.width),
+          height: Math.round(record.layout.height),
+        }
+      : null,
+    neededPx: neededPixels(record),
+    oversizeFactor: factor != null ? Math.round(factor * 100) / 100 : null,
+    decodedKB: Math.round(estDecodedBytes(record) / 1024),
+    wastedKB: Math.round(estWastedBytes(record) / 1024),
+    progressSeen: record.progressSeen === true,
+    bytesTotal: record.bytesTotal ?? null,
+    error: record.error ?? null,
+    errorCode: record.errorCode ?? null,
+    loadCount: record.loadCount,
+    overrideLabel: record.overrideLabel ?? null,
+    hasAltText: record.hasAltText ?? null,
+    layoutShifts: record.layoutShifts ?? 0,
+    ageMs: Date.now() - record.createdAt,
+  };
+}
+
+function requireRecord(params: unknown): ImageRecord {
+  const id = (params as { id?: number })?.id;
+  if (typeof id !== "number") throw new Error("Missing numeric `id` param");
+  const record = getRecord(id);
+  if (!record) {
+    throw new Error(
+      `Image record ${id} not found (cleared or evicted) — re-run the list action for current ids.`
+    );
+  }
+  return record;
+}
+
+function overview() {
+  const snapshot = getSnapshot();
+  return {
+    stats: computeStats(snapshot),
+    captureStatus: getCaptureStatus(),
+    globalModes: getGlobalModes(),
+    insights: computeInsights(snapshot),
+    records: [...snapshot].reverse(), // newest first
+  };
+}
+
+export const imagesSyncAdapter = {
+  version: 1,
+  getSnapshot: () => {
+    const { records, ...rest } = overview();
+    return { ...rest, records: records.slice(0, 100).map(toWire) };
+  },
+  subscribe: (onChange: () => void) => subscribe(onChange),
+  actions: {
+    /** List records (newest first). Params: { limit?, status? }. */
+    list: (params: unknown) => {
+      const p = (params ?? {}) as { limit?: number; status?: string };
+      const limit = Math.min(Math.max(p.limit ?? 50, 1), 200);
+      const { records, ...rest } = overview();
+      const filtered = p.status
+        ? records.filter((r) => r.status === p.status)
+        : records;
+      return {
+        ...rest,
+        total: filtered.length,
+        records: filtered.slice(0, limit).map(toWire),
+      };
+    },
+    /** Full detail for one record. Params: { id }. */
+    getDetail: (params: unknown) => {
+      const record = requireRecord(params);
+      return { ...toWire(record), errorHeaders: record.errorHeaders ?? null };
+    },
+    /** Bypass-cache reload. Params: { id }. */
+    hardReload: (params: unknown) => hardReloadRecord(requireRecord(params)),
+    /** Re-encode at displayed size as WebP, return real byte savings. Params: { id }. */
+    proveSavings: (params: unknown) => proveSavings(requireRecord(params)),
+    /** Plain fresh load attempt. Params: { id }. */
+    retry: (params: unknown) => retryRecord(requireRecord(params)),
+    /** Evict the expo-image disk entry for this record. Params: { id }. */
+    evictDisk: async (params: unknown) => {
+      const record = requireRecord(params);
+      const evicted = await evictExpoDiskEntry(record);
+      return {
+        ok: evicted,
+        message: evicted
+          ? "Disk cache entry deleted"
+          : "No disk entry found (expo-image + expo-file-system required)",
+      };
+    },
+    /** Flash a red border on the on-screen image. Params: { id }. */
+    flash: (params: unknown) => {
+      flashRecord(requireRecord(params).id);
+      return { ok: true, message: "Flashing for 2.5s" };
+    },
+    /**
+     * Apply a simulation override. Params: { id, kind, uri? } where kind is
+     * 'error' | 'hang' | 'blank' | 'url' ('url' requires uri).
+     */
+    setOverride: (params: unknown) => {
+      const record = requireRecord(params);
+      const p = params as { kind?: string; uri?: string };
+      const kinds: Record<string, { source: OverrideSource; label: string }> = {
+        error: { source: { type: "error" }, label: "Forced error" },
+        hang: { source: { type: "hang" }, label: "Forced loading" },
+        blank: { source: { type: "blank" }, label: "Blanked" },
+      };
+      if (p.kind === "url") {
+        if (!p.uri) throw new Error("kind 'url' requires a `uri` param");
+        setOverride(record.id, {
+          source: { type: "url", uri: p.uri },
+          label: "URL swapped",
+        });
+        return { ok: true, message: `Source overridden to ${p.uri}` };
+      }
+      const entry = p.kind ? kinds[p.kind] : undefined;
+      if (!entry) throw new Error(`Unknown override kind: ${String(p.kind)}`);
+      if (!record.mounted) {
+        return { ok: false, message: "Instance unmounted — overrides need the image on screen" };
+      }
+      setOverride(record.id, entry);
+      return { ok: true, message: `${entry.label} applied` };
+    },
+    /** Remove a simulation override. Params: { id }. */
+    clearOverride: (params: unknown) => {
+      clearOverride(requireRecord(params).id);
+      return { ok: true, message: "Override removed — original source restored" };
+    },
+    /**
+     * Mass action on every mounted image. Params: { kind } where kind is
+     * 'error' | 'loading' | 'blank' | 'reload' | 'flash' | 'restore'.
+     */
+    massAction: async (params: unknown) => {
+      const kind = (params as { kind?: string })?.kind;
+      switch (kind) {
+        case "error": {
+          const n = setOverrideForAllMounted({ type: "error" }, "Forced error");
+          return { ok: n > 0, message: `Forced error on ${n} images` };
+        }
+        case "loading": {
+          const n = setOverrideForAllMounted({ type: "hang" }, "Forced loading");
+          return { ok: n > 0, message: `Forced loading on ${n} images` };
+        }
+        case "blank": {
+          const n = setOverrideForAllMounted({ type: "blank" }, "Blanked");
+          return { ok: n > 0, message: `Blanked ${n} images` };
+        }
+        case "reload":
+          return hardReloadAllMounted();
+        case "flash": {
+          const n = flashAllMounted();
+          return { ok: n > 0, message: `Flashing ${n} images` };
+        }
+        case "restore": {
+          const n = clearAllOverrides();
+          return { ok: true, message: `Restored ${n} images` };
+        }
+        default:
+          throw new Error(`Unknown mass kind: ${String(kind)}`);
+      }
+    },
+    /** Global network simulation. Params: { mode: 'normal'|'offline'|'cold' }. */
+    setNetworkMode: (params: unknown) => {
+      const mode = (params as { mode?: NetworkMode })?.mode;
+      if (mode !== "normal" && mode !== "offline" && mode !== "cold") {
+        throw new Error("mode must be 'normal' | 'offline' | 'cold'");
+      }
+      setNetworkMode(mode);
+      return { ok: true, modes: getGlobalModes() };
+    },
+    /** Chrome-style disable-images. Params: { enabled: boolean }. */
+    setBlankImages: (params: unknown) => {
+      setBlankImages((params as { enabled?: boolean })?.enabled === true);
+      return { ok: true, modes: getGlobalModes() };
+    },
+    /** Clear the captured registry (keeps in-flight loads). */
+    clearRecords: () => {
+      clearRecords();
+      return { ok: true, message: "Registry cleared" };
+    },
+    /** Clear expo-image caches. Params: { memory?, disk? } (default both). */
+    clearExpoCaches: async (params: unknown) => {
+      const p = (params ?? {}) as { memory?: boolean; disk?: boolean };
+      const doMemory = p.memory !== false;
+      const doDisk = p.disk !== false;
+      try {
+        const expo = require("expo-image");
+        const results: string[] = [];
+        if (doMemory) {
+          await expo.Image.clearMemoryCache();
+          results.push("memory");
+        }
+        if (doDisk) {
+          await expo.Image.clearDiskCache();
+          results.push("disk");
+        }
+        return { ok: true, message: `Cleared expo-image ${results.join(" + ")} cache` };
+      } catch {
+        return { ok: false, message: "expo-image not installed" };
+      }
+    },
+    getCaptureStatus: () => getCaptureStatus(),
+  },
+};

package/src/types.ts

@@ -0,0 +1,111 @@
+/**
+ * Shared types for the Images tool.
+ *
+ * One ImageRecord = one load lifecycle of one mounted image instance for one
+ * source URI. If the same component instance switches to a new URI, the old
+ * record is finalized and a new one starts.
+ */
+
+/** Which image library rendered the instance. */
+export type ImageLib = "rn" | "expo";
+
+/** Coarse classification of where the source points. */
+export type SourceKind = "network" | "asset" | "file" | "data" | "other";
+
+export type ImageStatus = "pending" | "loading" | "loaded" | "error";
+
+/**
+ * Where the decoded image came from.
+ * - expo-image reports this directly on onLoad (`cacheType`).
+ * - RN core is classified after load via `Image.queryCache` (iOS can report
+ *   'disk/memory'; misses come back as undefined, shown as unknown).
+ */
+export type CacheVerdict = "none" | "disk" | "memory" | "disk/memory";
+
+export interface ImageRecord {
+  id: number;
+  lib: ImageLib;
+  uri: string;
+  sourceKind: SourceKind;
+  status: ImageStatus;
+  /** False once the owning component instance unmounted. */
+  mounted: boolean;
+  /** ms epoch when the record was created (≈ render of the instance). */
+  createdAt: number;
+  /** ms epoch of onLoadStart (native began working on the source). */
+  startedAt?: number;
+  loadedAt?: number;
+  /** ms epoch of the last onError (used for out-of-order event defense). */
+  erroredAt?: number;
+  /** expo-image only: when pixels were actually presented (onDisplay). */
+  displayedAt?: number;
+  /** startedAt → loadedAt (falls back to createdAt → loadedAt). */
+  durationMs?: number;
+  /** Decoded bitmap size in physical pixels (from onLoad). */
+  intrinsic?: { width: number; height: number };
+  /** Laid-out view size in dp (from injected onLayout). */
+  layout?: { width: number; height: number };
+  cacheVerdict?: CacheVerdict;
+  cacheVerdictSource?: "event" | "queryCache";
+  /** True if byte progress events fired (a real network download happened). */
+  progressSeen?: boolean;
+  bytesLoaded?: number;
+  bytesTotal?: number;
+  /** expo-image iOS only (Android reports null). */
+  mediaType?: string | null;
+  isAnimated?: boolean;
+  error?: string;
+  /** iOS RN core only: HTTP status code from onError. */
+  errorCode?: number;
+  /** iOS RN core only: response headers from onError. */
+  errorHeaders?: Record<string, string>;
+  /** How many load cycles this record has seen (source retries/reloads). */
+  loadCount: number;
+  /** Set while a simulation override is active (e.g. "Forced error"). */
+  overrideLabel?: string;
+  /** Whether the component had alt/accessibilityLabel at last render. */
+  hasAltText?: boolean;
+  /** Times the laid-out size changed AFTER the image loaded (CLS signal). */
+  layoutShifts?: number;
+}
+
+/** Cross-record findings computed from the live registry. */
+export interface ImageInsights {
+  /** Same URI loaded by 2+ mounted instances (duplicate decodes). */
+  duplicates: { uri: string; count: number }[];
+  /** Records with suspiciously many load cycles (render-thrash reloads). */
+  retryStorms: { id: number; uri: string; loadCount: number }[];
+  /** >4 RN-core images loading at once (iOS caps concurrent loads at 4). */
+  queueSaturated: boolean;
+  /** Mounted images missing alt/accessibilityLabel. */
+  missingAlt: number;
+  /** Images whose layout changed after load (layout-shift suspects). */
+  layoutShifters: { id: number; uri: string; shifts: number }[];
+}
+
+/** Aggregate stats derived from the current buffer. */
+export interface ImageStats {
+  total: number;
+  loading: number;
+  loaded: number;
+  errors: number;
+  /** Records whose bytes came over the network this session. */
+  networkLoads: number;
+  /** Σ intrinsic w×h×4 across loaded, still-mounted records. */
+  estDecodedBytes: number;
+  /** Σ estimated wasted decoded bytes from oversized sources (mounted). */
+  estWastedBytes: number;
+}
+
+/** Capture capability report — what the interceptors managed to hook. */
+export interface CaptureStatus {
+  installed: boolean;
+  /** RN core decorator landed before Image module evaluation. */
+  rnDecoratorActive: boolean;
+  /** RN core Image module was already evaluated when we tried (too late). */
+  rnDecoratorTooLate: boolean;
+  /** expo-image found and prototype-patched. */
+  expoPatched: boolean;
+  /** expo-image not installed in this app. */
+  expoAvailable: boolean;
+}