@buoy-gg/images 7.0.3

package/lib/typescript/sync/imagesSyncAdapter.d.ts

@@ -0,0 +1,205 @@
+/**
+ * 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 type { NetworkMode } from "../capture/overrides";
+export declare const imagesSyncAdapter: {
+    version: number;
+    getSnapshot: () => {
+        records: {
+            id: number;
+            lib: import("..").ImageLib;
+            uri: string;
+            kind: import("..").SourceKind;
+            status: import("..").ImageStatus;
+            mounted: boolean;
+            cache: import("..").CacheVerdict | null;
+            cacheSource: "event" | "queryCache" | null;
+            ms: number | null;
+            intrinsic: {
+                width: number;
+                height: number;
+            } | null;
+            layout: {
+                width: number;
+                height: number;
+            } | null;
+            neededPx: {
+                width: number;
+                height: number;
+            } | null;
+            oversizeFactor: number | null;
+            decodedKB: number;
+            wastedKB: number;
+            progressSeen: boolean;
+            bytesTotal: number | null;
+            error: string | null;
+            errorCode: number | null;
+            loadCount: number;
+            overrideLabel: string | null;
+            hasAltText: boolean | null;
+            layoutShifts: number;
+            ageMs: number;
+        }[];
+        stats: import("..").ImageStats;
+        captureStatus: import("..").CaptureStatus;
+        globalModes: {
+            network: NetworkMode;
+            blank: boolean;
+        };
+        insights: import("..").ImageInsights;
+    };
+    subscribe: (onChange: () => void) => () => void;
+    actions: {
+        /** List records (newest first). Params: { limit?, status? }. */
+        list: (params: unknown) => {
+            total: number;
+            records: {
+                id: number;
+                lib: import("..").ImageLib;
+                uri: string;
+                kind: import("..").SourceKind;
+                status: import("..").ImageStatus;
+                mounted: boolean;
+                cache: import("..").CacheVerdict | null;
+                cacheSource: "event" | "queryCache" | null;
+                ms: number | null;
+                intrinsic: {
+                    width: number;
+                    height: number;
+                } | null;
+                layout: {
+                    width: number;
+                    height: number;
+                } | null;
+                neededPx: {
+                    width: number;
+                    height: number;
+                } | null;
+                oversizeFactor: number | null;
+                decodedKB: number;
+                wastedKB: number;
+                progressSeen: boolean;
+                bytesTotal: number | null;
+                error: string | null;
+                errorCode: number | null;
+                loadCount: number;
+                overrideLabel: string | null;
+                hasAltText: boolean | null;
+                layoutShifts: number;
+                ageMs: number;
+            }[];
+            stats: import("..").ImageStats;
+            captureStatus: import("..").CaptureStatus;
+            globalModes: {
+                network: NetworkMode;
+                blank: boolean;
+            };
+            insights: import("..").ImageInsights;
+        };
+        /** Full detail for one record. Params: { id }. */
+        getDetail: (params: unknown) => {
+            errorHeaders: Record<string, string> | null;
+            id: number;
+            lib: import("..").ImageLib;
+            uri: string;
+            kind: import("..").SourceKind;
+            status: import("..").ImageStatus;
+            mounted: boolean;
+            cache: import("..").CacheVerdict | null;
+            cacheSource: "event" | "queryCache" | null;
+            ms: number | null;
+            intrinsic: {
+                width: number;
+                height: number;
+            } | null;
+            layout: {
+                width: number;
+                height: number;
+            } | null;
+            neededPx: {
+                width: number;
+                height: number;
+            } | null;
+            oversizeFactor: number | null;
+            decodedKB: number;
+            wastedKB: number;
+            progressSeen: boolean;
+            bytesTotal: number | null;
+            error: string | null;
+            errorCode: number | null;
+            loadCount: number;
+            overrideLabel: string | null;
+            hasAltText: boolean | null;
+            layoutShifts: number;
+            ageMs: number;
+        };
+        /** Bypass-cache reload. Params: { id }. */
+        hardReload: (params: unknown) => Promise<import("..").ActionResult>;
+        /** Re-encode at displayed size as WebP, return real byte savings. Params: { id }. */
+        proveSavings: (params: unknown) => Promise<import("..").SavingsResult>;
+        /** Plain fresh load attempt. Params: { id }. */
+        retry: (params: unknown) => Promise<import("..").ActionResult>;
+        /** Evict the expo-image disk entry for this record. Params: { id }. */
+        evictDisk: (params: unknown) => Promise<{
+            ok: boolean;
+            message: string;
+        }>;
+        /** Flash a red border on the on-screen image. Params: { id }. */
+        flash: (params: unknown) => {
+            ok: boolean;
+            message: string;
+        };
+        /**
+         * Apply a simulation override. Params: { id, kind, uri? } where kind is
+         * 'error' | 'hang' | 'blank' | 'url' ('url' requires uri).
+         */
+        setOverride: (params: unknown) => {
+            ok: boolean;
+            message: string;
+        };
+        /** Remove a simulation override. Params: { id }. */
+        clearOverride: (params: unknown) => {
+            ok: boolean;
+            message: string;
+        };
+        /**
+         * Mass action on every mounted image. Params: { kind } where kind is
+         * 'error' | 'loading' | 'blank' | 'reload' | 'flash' | 'restore'.
+         */
+        massAction: (params: unknown) => Promise<import("..").ActionResult>;
+        /** Global network simulation. Params: { mode: 'normal'|'offline'|'cold' }. */
+        setNetworkMode: (params: unknown) => {
+            ok: boolean;
+            modes: {
+                network: NetworkMode;
+                blank: boolean;
+            };
+        };
+        /** Chrome-style disable-images. Params: { enabled: boolean }. */
+        setBlankImages: (params: unknown) => {
+            ok: boolean;
+            modes: {
+                network: NetworkMode;
+                blank: boolean;
+            };
+        };
+        /** Clear the captured registry (keeps in-flight loads). */
+        clearRecords: () => {
+            ok: boolean;
+            message: string;
+        };
+        /** Clear expo-image caches. Params: { memory?, disk? } (default both). */
+        clearExpoCaches: (params: unknown) => Promise<{
+            ok: boolean;
+            message: string;
+        }>;
+        getCaptureStatus: () => import("..").CaptureStatus;
+    };
+};
+//# sourceMappingURL=imagesSyncAdapter.d.ts.map

package/lib/typescript/sync/imagesSyncAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"imagesSyncAdapter.d.ts","sourceRoot":"","sources":["../../../src/sync/imagesSyncAdapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAsBH,OAAO,KAAK,EAAE,WAAW,EAAkB,MAAM,sBAAsB,CAAC;AAyExE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0BAMN,MAAM,IAAI;;QAE9B,gEAAgE;uBACjD,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAatB,kDAAkD;4BAC9B,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAI3B,2CAA2C;6BACtB,OAAO;QAC5B,qFAAqF;+BAC9D,OAAO;QAC9B,gDAAgD;wBAChC,OAAO;QACvB,uEAAuE;4BAC7C,OAAO;;;;QAUjC,iEAAiE;wBACjD,OAAO;;;;QAIvB;;;WAGG;8BACmB,OAAO;;;;QAwB7B,oDAAoD;gCAC5B,OAAO;;;;QAI/B;;;WAGG;6BACwB,OAAO;QA6BlC,8EAA8E;iCACrD,OAAO;;;;;;;QAQhC,iEAAiE;iCACxC,OAAO;;;;;;;QAIhC,2DAA2D;;;;;QAK3D,0EAA0E;kCAC1C,OAAO;;;;;;CAsB1C,CAAC"}

package/lib/typescript/types.d.ts

@@ -0,0 +1,121 @@
+/**
+ * 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;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/typescript/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@buoy-gg/images",
+  "version": "7.0.3",
+  "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",
+  "types": "lib/typescript/index.d.ts",
+  "react-native": "src/index.tsx",
+  "source": "src/index.tsx",
+  "files": [
+    "src",
+    "lib",
+    "register.js",
+    "register.d.ts"
+  ],
+  "sideEffects": [
+    "**/register.*",
+    "**/index.*"
+  ],
+  "dependencies": {
+    "@buoy-gg/shared-ui": "7.0.3"
+  },
+  "peerDependencies": {
+    "expo-image": "*",
+    "react": "*",
+    "react-native": "*"
+  },
+  "peerDependenciesMeta": {
+    "expo-image": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.1.0",
+    "@types/react-native": "^0.73.0",
+    "typescript": "~5.8.3"
+  },
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "targets": [
+      "commonjs",
+      "module",
+      "typescript"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/LovesWorking/react-native-buoy.git",
+    "directory": "packages/images"
+  },
+  "bugs": {
+    "url": "https://github.com/LovesWorking/react-native-buoy/issues"
+  },
+  "homepage": "https://github.com/LovesWorking/react-native-buoy/tree/main/packages/images#readme",
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  },
+  "scripts": {
+    "build": "bob build",
+    "typecheck": "tsc --noEmit",
+    "clean": "rimraf lib",
+    "test": "pnpm run typecheck",
+    "postinstall": "echo \"Run pnpm build to compile this package\""
+  }
+}

package/register.d.ts

@@ -0,0 +1 @@
+export {};

package/register.js

@@ -0,0 +1,15 @@
+/**
+ * Subpath shim: `import "@buoy-gg/images/register"`.
+ *
+ * Installs image capture on import. Must be the FIRST import of the app entry
+ * file so the RN-core <Image> decorator lands before React Native's Image
+ * module evaluates. Works with and without package `exports` resolution
+ * (e.g. Metro `unstable_enablePackageExports: false`).
+ *
+ * Resolves to src (Metro transpiles TS in node_modules) so it shares ONE
+ * module instance with the package root import, which also resolves to src
+ * via the "react-native" main field — a lib-pointing shim would create a
+ * second copy of the capture layer and split the decorator from the store.
+ * Capture state is additionally globalThis-keyed as a second line of defense.
+ */
+module.exports = require("./src/register");

package/src/capture/actions.ts

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

@@ -0,0 +1,36 @@
+/**
+ * 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();
+  if (s.captureInstalled) return;
+  s.captureInstalled = true;
+  installRnImageInterceptor();
+  installExpoImageInterceptor();
+}
+
+export function getCaptureStatus(): CaptureStatus {
+  const rn = rnCaptureStatus();
+  const expo = expoCaptureStatus();
+  return {
+    installed: imagesState().captureInstalled,
+    rnDecoratorActive: rn.decoratorActive,
+    rnDecoratorTooLate: rn.tooLate,
+    expoPatched: expo.patched,
+    expoAvailable: expo.available,
+  };
+}