@buoy-gg/assets 7.0.16

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@buoy-gg/assets",
+  "version": "7.0.16",
+  "description": "See every asset shipped in your React Native app — bundled images, fonts, video and audio with dimensions, scale variants, byte sizes, duplicate detection and WebP-savings audit. 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"
+  ],
+  "sideEffects": [
+    "**/index.*"
+  ],
+  "dependencies": {
+    "@buoy-gg/shared-ui": "^7.0.16"
+  },
+  "peerDependencies": {
+    "expo-asset": "*",
+    "react": "*",
+    "react-native": "*"
+  },
+  "peerDependenciesMeta": {
+    "expo-asset": {
+      "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/assets"
+  },
+  "bugs": {
+    "url": "https://github.com/LovesWorking/react-native-buoy/issues"
+  },
+  "homepage": "https://github.com/LovesWorking/react-native-buoy/tree/main/packages/assets#readme",
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  },
+  "keywords": [
+    "react-native",
+    "expo",
+    "devtools",
+    "debugging",
+    "react-native-devtools",
+    "flipper-alternative",
+    "assets",
+    "bundle-size",
+    "images",
+    "fonts",
+    "app-size"
+  ],
+  "scripts": {
+    "build": "bob build",
+    "typecheck": "tsc --noEmit",
+    "clean": "rimraf lib",
+    "test": "pnpm run typecheck",
+    "postinstall": "echo \"Run pnpm build to compile this package\""
+  }
+}

package/src/capture/expo.ts

@@ -0,0 +1,45 @@
+/**
+ * Expo enrichment — all optional, all read through globalThis.expo guards so
+ * bare RN apps (no expo-modules) silently get none of it and no imports are
+ * added for anyone.
+ */
+
+interface ExpoGlobal {
+  modules?: {
+    ExpoFontLoader?: { getLoadedFonts?: () => string[] };
+    ExpoUpdates?: { localAssets?: Record<string, string> };
+  };
+}
+
+function expoModules(): ExpoGlobal["modules"] {
+  return (globalThis as { expo?: ExpoGlobal }).expo?.modules;
+}
+
+/**
+ * Every loaded font family — build-time embedded (config plugin / UIAppFonts /
+ * android assets/fonts) AND runtime Font.loadAsync, straight from the native
+ * module Expo documents as a stable global. [] when unavailable (bare RN).
+ */
+export function getLoadedFontFamilies(): string[] {
+  try {
+    const fonts = expoModules()?.ExpoFontLoader?.getLoadedFonts?.();
+    return Array.isArray(fonts) ? [...fonts].sort() : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * expo-updates' per-file-hash → local URI map: the COMPLETE shipped asset set
+ * in Expo Go / OTA environments, independent of what JS has evaluated.
+ * null when not running in an updates-managed environment.
+ */
+export function getLocalAssets(): Record<string, string> | null {
+  try {
+    const map = expoModules()?.ExpoUpdates?.localAssets;
+    if (map && typeof map === "object" && Object.keys(map).length > 0) return map;
+    return null;
+  } catch {
+    return null;
+  }
+}

package/src/capture/install.ts

@@ -0,0 +1,73 @@
+/**
+ * Capture install + scan orchestration.
+ *
+ * installAssetCapture() is cheap and synchronous (registry walk + patch) and
+ * runs at package import. The expensive passes — Metro graph fetch and byte
+ * measurement — run in rescan(), triggered when the modal opens or via the
+ * `rescan` sync action, so merely installing Buoy never hits the network.
+ */
+
+import { assetsState } from "../state";
+import { invalidate } from "../store/assetStore";
+import { getLoadedFontFamilies, getLocalAssets } from "./expo";
+import { measureSizes } from "./measure";
+import { fetchAssetGraph, getDevServerOrigin } from "./metroGraph";
+import { getRegistryModule, patchRegisterAsset, walkRegistry } from "./registry";
+import type { AssetsScanStatus } from "../types";
+
+export function installAssetCapture(): void {
+  const s = assetsState();
+  if (s.captureDisabled || s.installed) return;
+  s.installed = true;
+  s.registryAvailable = getRegistryModule() != null;
+  s.patched = patchRegisterAsset();
+  walkRegistry();
+  refreshEnrichment();
+  s.lastScanAt = Date.now();
+  invalidate();
+}
+
+function refreshEnrichment(): void {
+  const s = assetsState();
+  s.fontFamilies = getLoadedFontFamilies();
+  const localAssets = getLocalAssets();
+  s.localAssetCount = localAssets ? Object.keys(localAssets).length : null;
+}
+
+/**
+ * Full scan: registry re-walk (catches anything the patch missed), Metro
+ * graph merge (dev), Expo enrichment refresh, then size measurement.
+ */
+export async function rescan(): Promise<AssetsScanStatus> {
+  const s = assetsState();
+  if (s.captureDisabled) return getScanStatus();
+  installAssetCapture();
+  walkRegistry();
+  refreshEnrichment();
+  await fetchAssetGraph();
+  s.lastScanAt = Date.now();
+  invalidate();
+  void measureSizes();
+  return getScanStatus();
+}
+
+export function getScanStatus(): AssetsScanStatus {
+  const s = assetsState();
+  // Mirrors report the synced DEVICE's status, not the dashboard's.
+  if (s.mirrorScanStatus) return s.mirrorScanStatus;
+  let registryCount = 0;
+  for (const record of s.records) if (record.registryId != null) registryCount++;
+  return {
+    registryAvailable: s.registryAvailable,
+    patched: s.patched,
+    registryCount,
+    graphSupported: s.graphSupported || getDevServerOrigin() != null,
+    graphCount: s.graphCount,
+    graphError: s.graphError,
+    lastScanAt: s.lastScanAt,
+    measuring: s.measuring,
+    measuredCount: s.measuredCount,
+    fontFamilies: s.fontFamilies,
+    localAssetCount: s.localAssetCount,
+  };
+}

package/src/capture/measure.ts

@@ -0,0 +1,167 @@
+/**
+ * Byte-size measurement.
+ *
+ * Dev only in practice: each scale variant is fetched from the Metro dev
+ * server (HEAD first for Content-Length, GET-blob fallback since Metro
+ * doesn't reliably answer HEAD) and the per-variant sizes are summed onto
+ * the record. Android release resource ids and iOS file:// URIs are not
+ * measurable from JS — those records keep `estDecodedBytes` as their only
+ * size signal and the UI marks them as estimates.
+ */
+
+import { assetsState } from "../state";
+import { getSnapshot, invalidate, updateRecord } from "../store/assetStore";
+import { getDevServerOrigin } from "./metroGraph";
+import type { AssetRecord } from "../types";
+
+const CONCURRENCY = 4;
+
+/**
+ * Best displayable URL for a record: the resolved runtime URI, or (dev) the
+ * same dev-server URL the measurement pass uses — this is what gives graph-
+ * only (never-loaded) images real thumbnails.
+ */
+export function previewURL(record: AssetRecord): string | null {
+  if (record.resolvedUri) return record.resolvedUri;
+  const variants = variantURLs(record);
+  return variants.length ? variants[0]!.url : null;
+}
+
+/**
+ * Image source for thumbnails/previews. On device the NUMERIC registry id is
+ * preferred (resolves natively — works for Android release resource ids too).
+ * On dashboard mirrors that id belongs to the DEVICE's registry and rn-web
+ * throws "asset with ID N could not be found" — use the device's http(s)
+ * URL instead (the Metro dev server is reachable from the desktop).
+ */
+export function displaySource(
+  record: AssetRecord
+): number | { uri: string } | null {
+  const mirror = assetsState().captureDisabled;
+  if (!mirror && record.registryId != null) return record.registryId;
+  const uri = previewURL(record);
+  if (!uri) return null;
+  if (mirror && !/^https?:\/\//.test(uri)) return null;
+  return { uri };
+}
+
+/** All scale-variant URLs for a record, derived without re-encoding pitfalls. */
+export function variantURLs(record: AssetRecord): Array<{ scale: number; url: string }> {
+  const scales = record.scales.length ? record.scales : [1];
+
+  // Preferred: string surgery on the URL resolveAssetSource already proved
+  // works (handles Expo's ?unstable_path= form and monorepo rewrites).
+  const resolved = record.resolvedUri;
+  if (resolved && /^https?:\/\//.test(resolved) && record.resolvedScale != null) {
+    const pickedSuffix = record.resolvedScale === 1 ? "" : `@${record.resolvedScale}x`;
+    const marker = `${pickedSuffix}.${record.type}`;
+    if (resolved.includes(marker) || pickedSuffix === "") {
+      return scales.map((scale) => {
+        const suffix = scale === 1 ? "" : `@${scale}x`;
+        const url = (
+          pickedSuffix === ""
+            ? resolved.replace(`.${record.type}`, `${suffix}.${record.type}`)
+            : resolved.replace(marker, `${suffix}.${record.type}`)
+        ).replace(/ /g, "%20"); // RN's asset path builder doesn't encode spaces
+        return { scale, url };
+      });
+    }
+  }
+
+  // Graph-only records: rebuild the dev-server URL the way Metro's
+  // AssetSourceResolver does (plain concatenation), encoding only spaces —
+  // full encodeURI would double-encode Expo's pre-escaped unstable_path.
+  const origin = getDevServerOrigin();
+  if (!origin || !record.httpServerLocation) return [];
+  return scales.map((scale) => {
+    const suffix = scale === 1 ? "" : `@${scale}x`;
+    const path = `${record.httpServerLocation}/${record.name}${suffix}.${record.type}`;
+    const sep = path.includes("?") ? "&" : "?";
+    const url = `${origin}${path}${sep}platform=${platformName()}${
+      record.hash ? `&hash=${record.hash}` : ""
+    }`.replace(/ /g, "%20");
+    return { scale, url };
+  });
+}
+
+function platformName(): string {
+  try {
+    return require("react-native").Platform.OS;
+  } catch {
+    return "ios";
+  }
+}
+
+async function fetchSize(url: string): Promise<number | null> {
+  try {
+    const head = await fetch(url, { method: "HEAD" });
+    if (head.ok) {
+      const length = Number(head.headers.get("content-length"));
+      if (Number.isFinite(length) && length > 0) return length;
+    }
+  } catch {
+    // fall through to GET
+  }
+  try {
+    const response = await fetch(url);
+    if (!response.ok) return null;
+    const blob = await response.blob();
+    return blob.size > 0 ? blob.size : null;
+  } catch {
+    return null;
+  }
+}
+
+async function measureRecord(record: AssetRecord): Promise<void> {
+  const variants = variantURLs(record);
+  if (!variants.length) {
+    updateRecord(record.id, { sizeSource: "estimate" });
+    return;
+  }
+  const sizesByScale: Record<string, number> = {};
+  let total = 0;
+  for (const { scale, url } of variants) {
+    const size = await fetchSize(url);
+    if (size != null) {
+      sizesByScale[String(scale)] = size;
+      total += size;
+    }
+  }
+  if (total > 0) {
+    updateRecord(record.id, { sizesByScale, sizeBytes: total, sizeSource: "measured" });
+  } else {
+    updateRecord(record.id, { sizeSource: "estimate" });
+  }
+}
+
+/** Measure every unmeasured record; safe to re-run (skips measured ones). */
+export async function measureSizes(): Promise<{ measured: number; total: number }> {
+  const s = assetsState();
+  if (s.measuring) return { measured: s.measuredCount, total: getSnapshot().length };
+  const pending = getSnapshot().filter((r) => r.sizeSource !== "measured");
+  s.measuring = true;
+  invalidate();
+  try {
+    let index = 0;
+    const worker = async () => {
+      for (;;) {
+        const next = pending[index++];
+        if (!next) return;
+        await measureRecord(next);
+        s.measuredCount = getSnapshot().filter(
+          (r) => r.sizeSource === "measured"
+        ).length;
+      }
+    };
+    await Promise.all(
+      Array.from({ length: Math.min(CONCURRENCY, pending.length) }, worker)
+    );
+  } finally {
+    s.measuring = false;
+    invalidate();
+  }
+  return {
+    measured: s.measuredCount,
+    total: getSnapshot().length,
+  };
+}

package/src/capture/metroGraph.ts

@@ -0,0 +1,146 @@
+/**
+ * Metro dev-server graph fetch.
+ *
+ * The dev server serves `<entry>.assets` next to `<entry>.bundle` — the full
+ * dependency graph's AssetData[], INCLUDING assets never required at runtime
+ * and the `fileSystemLocation`/`files` fields Metro strips from runtime
+ * records. Deriving the URL by swapping `.bundle` → `.assets` on the running
+ * bundle's scriptURL keeps the entry path and platform/dev query params
+ * intact for both RN CLI (index.bundle) and Expo (…/entry.bundle) layouts.
+ *
+ * Graph-only records (in the graph, not the registry) are exactly the
+ * "shipped but never loaded" set. Dev-only: no server, no graph.
+ */
+
+import { assetsState } from "../state";
+import { assetKey, invalidate, upsertRecord } from "../store/assetStore";
+
+interface GraphAssetData {
+  __packager_asset?: boolean;
+  fileSystemLocation?: string;
+  httpServerLocation: string;
+  width?: number | null;
+  height?: number | null;
+  scales: number[];
+  files?: string[];
+  fileHashes?: string[];
+  hash: string;
+  name: string;
+  type: string;
+}
+
+export function getScriptURL(): string | null {
+  try {
+    const { NativeModules } = require("react-native");
+    const sourceCode = NativeModules?.SourceCode;
+    const url: unknown =
+      sourceCode?.getConstants?.().scriptURL ?? sourceCode?.scriptURL;
+    return typeof url === "string" ? url : null;
+  } catch {
+    return null;
+  }
+}
+
+/** http(s) origin of the Metro dev server, or null when running embedded. */
+export function getDevServerOrigin(): string | null {
+  const scriptURL = getScriptURL();
+  const match = scriptURL?.match(/^https?:\/\/[^/]+/);
+  return match ? match[0] : null;
+}
+
+/**
+ * Candidate graph URLs, most-likely first. The straight `.bundle`→`.assets`
+ * swap works for RN CLI, but Expo dev builds serve a VIRTUAL entry
+ * (.expo/.virtual-metro-entry.bundle) that only exists for .bundle requests —
+ * its .assets twin 404s — so the real entry modules are tried next, keeping
+ * the original query string (platform/dev/etc.) intact.
+ */
+export function getGraphURLCandidates(): string[] {
+  const scriptURL = getScriptURL();
+  if (!scriptURL || !/^https?:\/\//.test(scriptURL)) return [];
+  const origin = getDevServerOrigin();
+  const queryIndex = scriptURL.indexOf("?");
+  const query = queryIndex >= 0 ? scriptURL.slice(queryIndex) : "?platform=ios&dev=true";
+  const candidates: string[] = [];
+  if (scriptURL.includes(".bundle")) {
+    candidates.push(scriptURL.replace(".bundle", ".assets"));
+  }
+  if (origin) {
+    candidates.push(
+      `${origin}/node_modules/expo-router/entry.assets${query}`,
+      `${origin}/node_modules/expo/AppEntry.assets${query}`,
+      `${origin}/index.assets${query}`
+    );
+  }
+  return candidates;
+}
+
+/** Fetch the full asset graph from the dev server and merge it into the store. */
+export async function fetchAssetGraph(): Promise<
+  { ok: true; count: number } | { ok: false; message: string }
+> {
+  const s = assetsState();
+  const candidates = getGraphURLCandidates();
+  if (!candidates.length) {
+    s.graphSupported = false;
+    s.graphError = "No Metro dev server (embedded bundle)";
+    invalidate();
+    return { ok: false, message: s.graphError };
+  }
+  if (s.graphFetchInFlight) return { ok: false, message: "Graph fetch already running" };
+  s.graphFetchInFlight = true;
+  try {
+    let data: unknown = null;
+    let lastError = "";
+    for (const url of candidates) {
+      try {
+        const response = await fetch(url);
+        if (!response.ok) {
+          lastError = `Metro responded ${response.status} for ${url}`;
+          continue;
+        }
+        const parsed: unknown = await response.json();
+        if (Array.isArray(parsed)) {
+          data = parsed;
+          break;
+        }
+        lastError = "Unexpected .assets payload shape";
+      } catch (error) {
+        lastError = String((error as Error)?.message ?? error);
+      }
+    }
+    if (!Array.isArray(data)) throw new Error(lastError || "No graph endpoint answered");
+    const graph = data as GraphAssetData[];
+    for (const asset of graph) {
+      if (!asset || typeof asset.name !== "string" || typeof asset.type !== "string") {
+        continue;
+      }
+      upsertRecord({
+        key: assetKey(asset.httpServerLocation, asset.name, asset.type),
+        name: asset.name,
+        type: asset.type,
+        origin: "graph",
+        hash: asset.hash,
+        httpServerLocation: asset.httpServerLocation,
+        width: asset.width ?? undefined,
+        height: asset.height ?? undefined,
+        scales: asset.scales,
+        fileSystemLocation: asset.fileSystemLocation,
+        files: asset.files,
+        fileHashes: asset.fileHashes,
+      });
+    }
+    s.graphSupported = true;
+    s.graphCount = graph.length;
+    s.graphError = null;
+    invalidate();
+    return { ok: true, count: graph.length };
+  } catch (error) {
+    s.graphSupported = getDevServerOrigin() != null;
+    s.graphError = String((error as Error)?.message ?? error);
+    invalidate();
+    return { ok: false, message: s.graphError };
+  } finally {
+    s.graphFetchInFlight = false;
+  }
+}

package/src/capture/registry.ts

@@ -0,0 +1,134 @@
+/**
+ * Runtime access to @react-native/assets-registry.
+ *
+ * Asset ids are contiguous 1..N (`assets.push` return value), so a plain
+ * getAssetByID walk enumerates every asset registered so far — including
+ * everything registered BEFORE this tool was evaluated. That's why, unlike
+ * the images tool, there is no "must be the first import" requirement here:
+ * the walk backfills whatever the patch missed.
+ *
+ * registerAsset is patched (plain non-frozen CommonJS export, looked up at
+ * call time by Metro's generated asset modules) purely for LIVE updates as
+ * lazily-required assets register later.
+ */
+
+import { upsertRecord, assetKey } from "../store/assetStore";
+import type { AssetRecord } from "../types";
+
+/** Runtime shape of a registry entry (fileSystemLocation/files are stripped by Metro). */
+export interface PackagerAsset {
+  __packager_asset: boolean;
+  httpServerLocation: string;
+  width?: number | null;
+  height?: number | null;
+  scales: number[];
+  hash: string;
+  name: string;
+  type: string;
+}
+
+interface RegistryModule {
+  registerAsset: (asset: PackagerAsset) => number;
+  getAssetByID: (assetId: number) => PackagerAsset | undefined;
+}
+
+let cachedRegistry: RegistryModule | null | undefined;
+
+export function getRegistryModule(): RegistryModule | null {
+  if (cachedRegistry !== undefined) return cachedRegistry;
+  let mod: RegistryModule | null = null;
+  try {
+    mod = require("@react-native/assets-registry/registry");
+  } catch {
+    try {
+      // Older RN layouts re-export from here; same module instance when both exist.
+      mod = require("react-native/Libraries/Image/AssetRegistry");
+    } catch {
+      mod = null;
+    }
+  }
+  cachedRegistry =
+    mod && typeof mod.getAssetByID === "function" ? mod : null;
+  return cachedRegistry;
+}
+
+/** resolveAssetSource(id) → this environment's URI (dev URL / file:// / res id). */
+export function resolveRegistryAsset(
+  registryId: number
+): { uri: string; scale: number } | null {
+  try {
+    const { Image } = require("react-native");
+    const resolved = Image.resolveAssetSource(registryId);
+    if (resolved && typeof resolved.uri === "string") {
+      return { uri: resolved.uri, scale: resolved.scale ?? 1 };
+    }
+  } catch {
+    // resolution is enrichment — never let it break the walk
+  }
+  return null;
+}
+
+export function upsertFromPackagerAsset(
+  registryId: number,
+  asset: PackagerAsset
+): AssetRecord {
+  const resolved = resolveRegistryAsset(registryId);
+  return upsertRecord({
+    key: assetKey(asset.httpServerLocation, asset.name, asset.type),
+    name: asset.name,
+    type: asset.type,
+    origin: "registry",
+    registryId,
+    hash: asset.hash,
+    httpServerLocation: asset.httpServerLocation,
+    width: asset.width ?? undefined,
+    height: asset.height ?? undefined,
+    scales: asset.scales,
+    resolvedUri: resolved?.uri,
+    resolvedScale: resolved?.scale,
+    loaded: true,
+  });
+}
+
+/** Enumerate every asset registered so far. Returns the highest id seen. */
+export function walkRegistry(): number {
+  const registry = getRegistryModule();
+  if (!registry) return 0;
+  let id = 0;
+  for (;;) {
+    const asset = registry.getAssetByID(id + 1);
+    if (!asset) break;
+    id++;
+    upsertFromPackagerAsset(id, asset);
+  }
+  return id;
+}
+
+const PATCH_MARKER = "__buoyAssetsPatched";
+
+/**
+ * Wrap registerAsset so future registrations stream in live. Safe to call
+ * more than once (marker guard); the walk covers anything registered before.
+ */
+export function patchRegisterAsset(): boolean {
+  const registry = getRegistryModule();
+  if (!registry) return false;
+  const original = registry.registerAsset;
+  if ((original as unknown as Record<string, unknown>)[PATCH_MARKER]) return true;
+  const wrapped = (asset: PackagerAsset): number => {
+    const id = original.call(registry, asset);
+    try {
+      upsertFromPackagerAsset(id, asset);
+    } catch {
+      // never break app asset registration
+    }
+    return id;
+  };
+  (wrapped as unknown as Record<string, unknown>)[PATCH_MARKER] = true;
+  try {
+    registry.registerAsset = wrapped;
+  } catch {
+    return false;
+  }
+  return true;
+}