@buoy-gg/images 7.0.41 → 7.0.43

package/README.md

@@ -1,14 +1,16 @@
+<div align="center">
+
 # @buoy-gg/images
 
-[![npm version](https://img.shields.io/npm/v/@buoy-gg/images?style=flat-square&labelColor=1c1c1c&color=10B981)](https://www.npmjs.com/package/@buoy-gg/images) [![npm downloads](https://img.shields.io/npm/dm/@buoy-gg/images?style=flat-square&labelColor=1c1c1c&color=10B981)](https://www.npmjs.com/package/@buoy-gg/images)
+Inspect image loads observed by Buoy's supported image hooks, including timing, dimensions and estimated decoded memory.
 
-Inspect image loads observed by Buoy’s supported image hooks, including timing, dimensions, and estimated decoded memory.
+<a href="https://buoy.gg/buoy/latest/docs/tools/images"><b>Images guide</b></a> &nbsp;·&nbsp; <a href="https://buoy.gg">buoy.gg</a> &nbsp;·&nbsp; <a href="https://github.com/Buoy-gg/buoy">All tools</a>
 
-Part of [Buoy](https://github.com/Buoy-gg/buoy). Install the package, complete account setup, and follow the integration steps below.
+[![npm version](https://img.shields.io/npm/v/@buoy-gg/images?style=flat-square&labelColor=10302a&color=2a9d78)](https://www.npmjs.com/package/@buoy-gg/images) [![npm downloads](https://img.shields.io/npm/dm/@buoy-gg/images?style=flat-square&labelColor=10302a&color=2a9d78&label=downloads%2Fmonth)](https://www.npmjs.com/package/@buoy-gg/images)
 
-Buoy's own icons, backgrounds and tool previews are excluded from image capture. App images remain visible, including app views that load the same URL as a tool preview.
+<a href="https://buoy.gg/buoy/latest/docs/tools/images"><img src="https://raw.githubusercontent.com/Buoy-gg/buoy/main/.github/readme/tools/images.png" alt="Watch the Images film on buoy.gg" width="640" /></a>
 
-Native image loading can bypass JavaScript network capture. This package instruments supported React Native `Image` and `expo-image` paths to provide image-specific details.
+</div>
 
 ## Install
 
@@ -16,71 +18,10 @@ Native image loading can bypass JavaScript network capture. This package instrum
 npm install @buoy-gg/core @buoy-gg/images
 ```
 
-Then add the register import as the **first line** of your app entry file (`index.js` / `index.ts`):
-
-```ts
-import "@buoy-gg/images/register";
-```
-
-> Why first? RN core's `<Image>` instrumentation uses React Native's official component-decorator hook, which must be installed before the Image module first evaluates. expo-image capture has no such constraint — it works no matter when the tool loads. If you skip the import, the tool tells you what it's missing instead of sitting silently empty.
-
-## Before you start
-
-Use a development build with `@buoy-gg/core` and a Free or Pro Buoy account key. From your app’s directory, sign in:
-
-```bash
-npx --package=@buoy-gg/core buoy login
-```
-
-For Expo, initialize Buoy before rendering the menu:
-
-```tsx
-import { Buoy } from "@buoy-gg/core";
-
-Buoy.init({ licenseKey: process.env.EXPO_PUBLIC_BUOY_KEY });
-```
-
-The login command writes the Expo key to `.env.local`. For React Native CLI, pass the key from your app’s environment configuration; React Native does not load `.env.local` automatically. Mount `FloatingDevTools` inside the same providers as your screens and restart the development server after installation. The [Quick Start](https://buoy.gg/buoy/latest/docs/quick-start) shows the complete root component setup.
-
-## Quick start
-
-```tsx
-import { FloatingDevTools } from "@buoy-gg/core";
-
-export default function App() {
-  return (
-    <>
-      <YourApp />
-      <FloatingDevTools />
-    </>
-  );
-}
-```
-
-The IMAGES tool appears in the menu. Open it and browse image loads observed during the session.
-
-## Check the integration
-
-Load a supported image after the capture hook is installed and inspect the entry. Treat cache results according to the image library’s available signals and decoded memory as an estimate. Native image paths outside those hooks may not appear.
-
-## What you get
-
-- **Live image registry** — observed RN `<Image>` and expo-image loads: thumbnail, source, status, load time, decoded dimensions
-- **Cache verdicts** — memory / disk / network per load (expo-image reports it directly; RN core is classified via `Image.queryCache`)
-- **Oversize auditing** — decoded size vs displayed size × device pixel ratio, Lighthouse-style: green within 10%, red beyond 50%, with estimated wasted decoded memory and the exact size you should serve
-- **Memory accounting** — estimated decoded-bitmap bytes per image and totals across the session (catch ballooning before the OOM)
-- **Failure log** — captured `onError` events with the message, and on iOS the HTTP status code + response headers
-- **Cache actions** — clear expo-image memory/disk caches from the detail view
-- **Upscale detection** — tiny sources stretched into big boxes (blurry images) get flagged too
-
-## Desktop & AI
-
-To connect a React Native app to [Buoy Desktop](https://github.com/Buoy-gg/Buoy-Desktop) or MCP, install `@buoy-gg/external-sync` and follow the [Desktop connection guide](https://buoy.gg/buoy/latest/docs/desktop). Sign in to Desktop separately. [MCP setup](https://buoy.gg/buoy/latest/docs/mcp) also requires a process account and Pro access. Available remote actions depend on the tool and app integration.
-
-## Account and plan requirements
+Images appears in the menu once installed. Open it to browse the image loads seen during the session.
 
-Use a Free or Pro Buoy account. History limits and paid features vary by tool; see [pricing](https://buoy.gg/pricing). Production access requires Pro where supported. Development-only hooks and actions remain unavailable in release builds.
+The [Images guide](https://buoy.gg/buoy/latest/docs/tools/images) covers setup, what it captures and its limits. New to Buoy? Start with the [Quick start](https://buoy.gg/buoy/latest/docs/quick-start).
 
-## Web support (unreleased)
+---
 
-Browser capture observes DOM images and supports shared overrides and size analysis. Savings previews use Canvas; cross-origin reads require permission from the image server. The browser build is available in this checkout and has not been published yet. See the [web setup guide](https://buoy.gg/buoy/latest/docs/web-preview) for registration, dependencies, and browser boundaries.
+<sub>Part of <a href="https://buoy.gg">Buoy</a>, developer tools that live inside your app. Proprietary software. © Buoy LLC. <a href="https://buoy.gg/terms">Terms</a></sub>

package/lib/commonjs/autoCapture.js

@@ -1,4 +1 @@
-"use strict";
-
-require("./register");
-//# sourceMappingURL=autoCapture.js.map
+"use strict";require("./register");

package/lib/commonjs/autoCapture.web.js

@@ -1,6 +1 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-//# sourceMappingURL=autoCapture.web.js.map
+"use strict";Object.defineProperty(exports,"__esModule",{value:true});

package/lib/commonjs/capture/actions.js

@@ -1,243 +1 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.dropActionState = dropActionState;
-exports.evictExpoDiskEntry = evictExpoDiskEntry;
-exports.getReloadNonce = getReloadNonce;
-exports.getReloadRequest = getReloadRequest;
-exports.hardReloadAllMounted = hardReloadAllMounted;
-exports.hardReloadRecord = hardReloadRecord;
-exports.registerExpoInstance = registerExpoInstance;
-exports.retryRecord = retryRecord;
-exports.settleReloadRequest = settleReloadRequest;
-exports.subscribeActions = subscribeActions;
-var _nativeImageModules = require("./nativeImageModules");
-var _remote = require("../remote");
-var _state = require("../state");
-var _overrides = require("./overrides");
-/**
- * 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.
- */
-
-// ---------------------------------------------------------------------------
-// RN reload-request bus (consumed by the decorator wrapper)
-// ---------------------------------------------------------------------------
-
-function subscribeActions(listener) {
-  const s = (0, _state.imagesState)();
-  s.actionListeners.add(listener);
-  return () => (0, _state.imagesState)().actionListeners.delete(listener);
-}
-function getReloadRequest(recordId) {
-  if (recordId == null) return undefined;
-  return (0, _state.imagesState)().reloadRequests.get(recordId);
-}
-
-/** Reload nonce for a record (0 = never requested). Snapshot for the wrapper. */
-function getReloadNonce(recordId) {
-  return getReloadRequest(recordId)?.nonce ?? 0;
-}
-function requestRnReload(recordId, bust) {
-  const s = (0, _state.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.
-  (0, _overrides.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.
- */
-function settleReloadRequest(recordId) {
-  const s = (0, _state.imagesState)();
-  const req = s.reloadRequests.get(recordId);
-  if (req?.bust) {
-    s.reloadRequests.set(recordId, {
-      nonce: req.nonce,
-      bust: false
-    });
-  }
-}
-function dropActionState(recordId) {
-  const s = (0, _state.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)
-// ---------------------------------------------------------------------------
-
-function registerExpoInstance(recordId, instance) {
-  if (recordId == null) return;
-  (0, _state.imagesState)().expoInstances.set(recordId, instance);
-}
-function expoImageStatics() {
-  try {
-    return (0, _nativeImageModules.loadExpoImage)().Image ?? null;
-  } catch {
-    return null;
-  }
-}
-/**
- * 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() {
-  try {
-    const mod = (0, _nativeImageModules.loadLegacyFileSystem)();
-    const fs = mod?.default || mod;
-    if (fs?.deleteAsync) return fs;
-  } catch {
-    // try main import
-  }
-  try {
-    const mod = (0, _nativeImageModules.loadFileSystemModule)();
-    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.
- */
-async function evictExpoDiskEntry(record) {
-  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)
-// ---------------------------------------------------------------------------
-
-/** Fresh load attempt for a mounted image (no cache bypass). */
-async function retryRecord(record) {
-  const remote = (0, _remote.remoteImagesDispatch)();
-  if (remote) return (0, _remote.remoteActionResult)(remote("retry", {
-    id: record.id
-  }));
-  if (!record.mounted) {
-    return {
-      ok: false,
-      message: "Instance unmounted — cannot reload"
-    };
-  }
-  if (record.lib === "expo") {
-    const instance = (0, _state.imagesState)().expoInstances.get(record.id);
-    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. */
-async function hardReloadAllMounted() {
-  const remote = (0, _remote.remoteImagesDispatch)();
-  if (remote) {
-    return (0, _remote.remoteActionResult)(remote("massAction", {
-      kind: "reload"
-    }));
-  }
-  const {
-    getSnapshot
-  } = require("../store/imageEventStore");
-  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. */
-async function hardReloadRecord(record) {
-  const remote = (0, _remote.remoteImagesDispatch)();
-  if (remote) return (0, _remote.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"
-  };
-}
-//# sourceMappingURL=actions.js.map
+"use strict";Object.defineProperty(exports,"__esModule",{value:true});exports.dropActionState=dropActionState;exports.evictExpoDiskEntry=evictExpoDiskEntry;exports.getReloadNonce=getReloadNonce;exports.getReloadRequest=getReloadRequest;exports.hardReloadAllMounted=hardReloadAllMounted;exports.hardReloadRecord=hardReloadRecord;exports.registerExpoInstance=registerExpoInstance;exports.retryRecord=retryRecord;exports.settleReloadRequest=settleReloadRequest;exports.subscribeActions=subscribeActions;var _nativeImageModules=require("./nativeImageModules");var _remote=require("../remote");var _state=require("../state");var _overrides=require("./overrides");function subscribeActions(e){const t=(0,_state.imagesState)();t.actionListeners.add(e);return()=>(0,_state.imagesState)().actionListeners.delete(e)}function getReloadRequest(e){if(e==null)return void 0;return(0,_state.imagesState)().reloadRequests.get(e)}function getReloadNonce(e){return getReloadRequest(e)?.nonce??0}function requestRnReload(e,t){const s=(0,_state.imagesState)();const n=s.reloadRequests.get(e);s.reloadRequests.set(e,{nonce:(n?.nonce??0)+1,bust:t});(0,_overrides.touchRecord)(e)}function settleReloadRequest(e){const t=(0,_state.imagesState)();const s=t.reloadRequests.get(e);if(s?.bust){t.reloadRequests.set(e,{nonce:s.nonce,bust:false})}}function dropActionState(e){const t=(0,_state.imagesState)();t.reloadRequests.delete(e);t.expoInstances.delete(e);t.overrides.delete(e);t.flashUntil.delete(e);t.recordVersions.delete(e)}function registerExpoInstance(e,t){if(e==null)return;(0,_state.imagesState)().expoInstances.set(e,t)}function expoImageStatics(){try{return(0,_nativeImageModules.loadExpoImage)().Image??null}catch{return null}}function loadFileSystem(){try{const e=(0,_nativeImageModules.loadLegacyFileSystem)();const t=e?.default||e;if(t?.deleteAsync)return t}catch{}try{const e=(0,_nativeImageModules.loadFileSystemModule)();const t=e?.default||e;if(t?.deleteAsync)return t}catch{}return null}async function evictExpoDiskEntry(e){const t=expoImageStatics();const s=loadFileSystem();if(!t?.getCachePathAsync||!s?.deleteAsync||!e.uri)return false;try{const n=await t.getCachePathAsync(e.uri);if(!n)return false;const a=n.startsWith("file://")?n:`file://${n}`;await s.deleteAsync(a,{idempotent:true});return true}catch{return false}}async function retryRecord(e){const t=(0,_remote.remoteImagesDispatch)();if(t)return(0,_remote.remoteActionResult)(t("retry",{id:e.id}));if(!e.mounted){return{ok:false,message:"Instance unmounted \u2014 cannot reload"}}if(e.lib==="expo"){const s=(0,_state.imagesState)().expoInstances.get(e.id);if(!s?.reloadAsync){return{ok:false,message:"Live instance not reachable"}}await s.reloadAsync();return{ok:true,message:"Reload requested"}}requestRnReload(e.id,false);return{ok:true,message:"Remounting image"}}async function hardReloadAllMounted(){const e=(0,_remote.remoteImagesDispatch)();if(e){return(0,_remote.remoteActionResult)(e("massAction",{kind:"reload"}))}const{getSnapshot:t}=require("../store/imageEventStore");let s=0;for(const n of t()){if(!n.mounted)continue;const a=await hardReloadRecord(n);if(a.ok)s++}return{ok:s>0,message:`Hard-reloading ${s} mounted image${s===1?"":"s"}`}}async function hardReloadRecord(e){const t=(0,_remote.remoteImagesDispatch)();if(t)return(0,_remote.remoteActionResult)(t("hardReload",{id:e.id}));if(!e.mounted){return{ok:false,message:"Instance unmounted \u2014 cannot reload"}}if(e.sourceKind!=="network"){return retryRecord(e)}if(e.lib==="expo"){const s=await evictExpoDiskEntry(e);const n=expoImageStatics();await n?.clearMemoryCache?.().catch?.(()=>false);const a=await retryRecord(e);if(!a.ok)return a;return{ok:true,message:s?"Disk entry evicted, memory cache cleared, refetching":"Memory cache cleared, refetching (no disk entry found)"}}requestRnReload(e.id,true);return{ok:true,message:"Refetching with cache bypassed"}}

package/lib/commonjs/capture/install.js

@@ -1,45 +1 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.getCaptureStatus = getCaptureStatus;
-exports.installImageCapture = installImageCapture;
-var _state = require("../state");
-var _installExpoImage = require("./installExpoImage");
-var _installRnImage = require("./installRnImage");
-/**
- * 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.
- */
-
-function installImageCapture() {
-  const s = (0, _state.imagesState)();
-  // Mirror mode (desktop dashboard): never instrument the dashboard's own UI.
-  if (s.captureDisabled || s.captureInstalled) return;
-  s.captureInstalled = true;
-  (0, _installRnImage.installRnImageInterceptor)();
-  (0, _installExpoImage.installExpoImageInterceptor)();
-}
-function getCaptureStatus() {
-  // Mirror mode: report the synced DEVICE's capture status, not the local probe.
-  const mirrored = (0, _state.imagesState)().mirrorCaptureStatus;
-  if (mirrored) return mirrored;
-  const rn = (0, _installRnImage.rnCaptureStatus)();
-  const expo = (0, _installExpoImage.expoCaptureStatus)();
-  return {
-    installed: (0, _state.imagesState)().captureInstalled,
-    rnDecoratorActive: rn.decoratorActive,
-    rnDecoratorTooLate: rn.tooLate,
-    expoPatched: expo.patched,
-    expoAvailable: expo.available
-  };
-}
-//# sourceMappingURL=install.js.map
+"use strict";Object.defineProperty(exports,"__esModule",{value:true});exports.getCaptureStatus=getCaptureStatus;exports.installImageCapture=installImageCapture;var _state=require("../state");var _installExpoImage=require("./installExpoImage");var _installRnImage=require("./installRnImage");function installImageCapture(){const t=(0,_state.imagesState)();if(t.captureDisabled||t.captureInstalled)return;t.captureInstalled=true;(0,_installRnImage.installRnImageInterceptor)();(0,_installExpoImage.installExpoImageInterceptor)()}function getCaptureStatus(){const t=(0,_state.imagesState)().mirrorCaptureStatus;if(t)return t;const e=(0,_installRnImage.rnCaptureStatus)();const a=(0,_installExpoImage.expoCaptureStatus)();return{installed:(0,_state.imagesState)().captureInstalled,rnDecoratorActive:e.decoratorActive,rnDecoratorTooLate:e.tooLate,expoPatched:a.patched,expoAvailable:a.available}}