@buoy-gg/assets 7.0.16

package/src/store/baseline.ts

@@ -0,0 +1,152 @@
+/**
+ * Baseline diff — the regression-prevention half of the tool.
+ *
+ * "Save baseline" persists a slim {hash, size} snapshot of the inventory via
+ * shared-ui's persistentStorage (FileSystem → AsyncStorage → memory), and
+ * every later scan diffs against it: new assets, removed assets, grown
+ * assets, net bytes. Run it before and after a branch and you get "this
+ * branch added 2.3 MB" without any CI tooling.
+ *
+ * On dashboard mirrors the actions forward to the device (the baseline
+ * belongs to the app being inspected, not the dashboard) and the computed
+ * diff arrives back inside the synced snapshot.
+ */
+
+import { persistentStorage } from "@buoy-gg/shared-ui";
+import { remoteAssetsDispatch } from "../remote";
+import { assetsState } from "../state";
+import { getSnapshot, invalidate } from "./assetStore";
+import type { AssetRecord, AssetsBaseline, AssetsDiff } from "../types";
+
+const STORAGE_KEY = "@react_buoy/assets/baseline";
+
+/** ≥1 KB counts as growth; below that is codec/metadata noise. */
+const GROWN_THRESHOLD_BYTES = 1024;
+
+/** Load the persisted baseline into state once; safe to call repeatedly. */
+export async function loadBaseline(): Promise<AssetsBaseline | null> {
+  const s = assetsState();
+  if (s.baselineLoaded) return s.baseline;
+  s.baselineLoaded = true;
+  try {
+    const raw = await persistentStorage.getItem(STORAGE_KEY);
+    if (raw) {
+      const parsed = JSON.parse(raw) as AssetsBaseline;
+      if (parsed && typeof parsed.savedAt === "number" && parsed.entries) {
+        s.baseline = parsed;
+        invalidate();
+      }
+    }
+  } catch {
+    // unreadable baseline = no baseline
+  }
+  return s.baseline;
+}
+
+export async function saveBaseline(): Promise<AssetsBaseline> {
+  const remote = remoteAssetsDispatch();
+  if (remote) {
+    await remote("saveBaseline");
+    return assetsState().baseline ?? { savedAt: Date.now(), entries: {} };
+  }
+  const s = assetsState();
+  const entries: AssetsBaseline["entries"] = {};
+  for (const r of getSnapshot()) {
+    entries[r.key] = {
+      hash: r.hash ?? null,
+      sizeBytes: r.sizeSource === "measured" ? (r.sizeBytes ?? null) : null,
+      name: r.name,
+      type: r.type,
+    };
+  }
+  const baseline: AssetsBaseline = { savedAt: Date.now(), entries };
+  s.baseline = baseline;
+  s.baselineLoaded = true;
+  invalidate();
+  try {
+    await persistentStorage.setItem(STORAGE_KEY, JSON.stringify(baseline));
+  } catch {
+    // in-memory baseline still works for this session
+  }
+  return baseline;
+}
+
+export async function clearBaseline(): Promise<void> {
+  const remote = remoteAssetsDispatch();
+  if (remote) {
+    await remote("clearBaseline");
+    return;
+  }
+  const s = assetsState();
+  s.baseline = null;
+  s.baselineLoaded = true;
+  invalidate();
+  try {
+    await persistentStorage.removeItem(STORAGE_KEY);
+  } catch {
+    // nothing to clean up
+  }
+}
+
+export function computeDiff(
+  records: AssetRecord[],
+  baseline: AssetsBaseline
+): AssetsDiff {
+  const added: number[] = [];
+  const grown: Array<{ id: number; deltaBytes: number }> = [];
+  const seen = new Set<string>();
+  let currentBytes = 0;
+  let baselineBytes = 0;
+  let comparable = false;
+
+  for (const r of records) {
+    seen.add(r.key);
+    const then = baseline.entries[r.key];
+    if (!then) {
+      added.push(r.id);
+      continue;
+    }
+    const now = r.sizeSource === "measured" ? (r.sizeBytes ?? null) : null;
+    if (now != null && then.sizeBytes != null) {
+      comparable = true;
+      currentBytes += now;
+      baselineBytes += then.sizeBytes;
+      if (now - then.sizeBytes >= GROWN_THRESHOLD_BYTES) {
+        grown.push({ id: r.id, deltaBytes: now - then.sizeBytes });
+      }
+    }
+  }
+
+  const removed: AssetsDiff["removed"] = [];
+  for (const [key, entry] of Object.entries(baseline.entries)) {
+    if (!seen.has(key)) {
+      removed.push({ key, name: entry.name, type: entry.type });
+      if (entry.sizeBytes != null) baselineBytes += entry.sizeBytes;
+    }
+  }
+  // Added assets' measured bytes count toward the net even without a
+  // baseline counterpart — that's exactly the growth being reported.
+  for (const id of added) {
+    const r = records.find((rec) => rec.id === id);
+    if (r?.sizeSource === "measured" && r.sizeBytes != null) {
+      comparable = true;
+      currentBytes += r.sizeBytes;
+    }
+  }
+
+  return {
+    baselineSavedAt: baseline.savedAt,
+    added,
+    removed,
+    grown: grown.sort((a, b) => b.deltaBytes - a.deltaBytes),
+    netBytes: comparable ? currentBytes - baselineBytes : null,
+  };
+}
+
+/** Current diff: the synced device's on mirrors, computed locally on device. */
+export function getDiff(): AssetsDiff | null {
+  const s = assetsState();
+  if (s.mirrorDiff) return s.mirrorDiff;
+  if (!s.baseline) return null;
+  return computeDiff(getSnapshot(), s.baseline);
+}

package/src/store/insights.ts

@@ -0,0 +1,145 @@
+/**
+ * Derived insights over the asset inventory — the Lighthouse/Emerge-style
+ * audit findings, each pointing at concrete record ids.
+ */
+
+import { assetsState } from "../state";
+import { estDecodedBytes } from "./assetStore";
+import type { AssetRecord, AssetsInsights, DuplicateInsight } from "../types";
+
+/** png/jpeg at or above this measured size are flagged as WebP candidates. */
+const WEBP_CANDIDATE_BYTES = 50 * 1024;
+/** GIFs at or above this measured size decode into serious frame memory. */
+const HEAVY_GIF_BYTES = 100 * 1024;
+/** Fonts at or above this are usually unsubset icon fonts. */
+const HEAVY_FONT_BYTES = 150 * 1024;
+/** Flag images decoding to more pixels than this many screenfuls. */
+const OVER_DECODE_SCREENS = 2;
+/** A higher scale variant this much smaller than a lower one = bad export. */
+const SCALE_ANOMALY_RATIO = 0.9;
+/**
+ * Anomaly checks only apply when the smaller variant is at least this big —
+ * for tiny icons PNG overhead dominates and byte ordering is pure noise.
+ */
+const SCALE_ANOMALY_MIN_BYTES = 4 * 1024;
+
+function effectivePixelRatio(): number {
+  const mirror = assetsState().mirrorPixelRatio;
+  if (mirror != null) return mirror;
+  try {
+    return require("react-native").PixelRatio.get();
+  } catch {
+    return 2;
+  }
+}
+
+/** Physical pixels of the entire screen (fallback ≈ a 6.1" phone). */
+function screenPixels(): number {
+  try {
+    const { Dimensions, PixelRatio } = require("react-native");
+    const screen = Dimensions.get("screen");
+    const ratio = PixelRatio.get();
+    return screen.width * ratio * screen.height * ratio;
+  } catch {
+    return 1170 * 2532;
+  }
+}
+
+/** True when the measured per-scale sizes contradict the scales (bad export). */
+function hasScaleAnomaly(record: AssetRecord): boolean {
+  const sizes = record.sizesByScale;
+  if (!sizes) return false;
+  const ordered = Object.entries(sizes)
+    .map(([scale, bytes]) => ({ scale: Number(scale), bytes }))
+    .filter((e) => Number.isFinite(e.scale) && e.bytes > 0)
+    .sort((a, b) => a.scale - b.scale);
+  for (let i = 1; i < ordered.length; i++) {
+    if (
+      ordered[i - 1]!.bytes >= SCALE_ANOMALY_MIN_BYTES &&
+      ordered[i]!.bytes < ordered[i - 1]!.bytes * SCALE_ANOMALY_RATIO
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export function computeInsights(list: AssetRecord[]): AssetsInsights {
+  const deviceScale = effectivePixelRatio();
+
+  const byHash = new Map<string, AssetRecord[]>();
+  for (const r of list) {
+    if (!r.hash) continue;
+    const group = byHash.get(r.hash);
+    if (group) group.push(r);
+    else byHash.set(r.hash, [r]);
+  }
+  const duplicates: DuplicateInsight[] = [];
+  for (const [hash, group] of byHash) {
+    if (group.length < 2) continue;
+    const measured = group.find((r) => r.sizeBytes != null);
+    duplicates.push({
+      hash,
+      ids: group.map((r) => r.id),
+      wastedBytes:
+        measured?.sizeBytes != null
+          ? measured.sizeBytes * (group.length - 1)
+          : null,
+    });
+  }
+
+  const screenPx = screenPixels();
+  const scaleGaps: number[] = [];
+  const webpCandidates: number[] = [];
+  const neverLoaded: number[] = [];
+  const overDecode: number[] = [];
+  const heavyGifs: number[] = [];
+  const heavyFonts: number[] = [];
+  const scaleAnomalies: number[] = [];
+  for (const r of list) {
+    if (!r.loaded) neverLoaded.push(r.id);
+    // Only multi-scale assets missing the device scale are flagged — the
+    // author clearly manages variants and missed one. Single-@1x images are
+    // the overwhelmingly common case and flagging them all is pure noise.
+    if (
+      r.kind === "image" &&
+      r.scales.length > 1 &&
+      !r.scales.some((s) => s >= deviceScale)
+    ) {
+      scaleGaps.push(r.id);
+    }
+    if (
+      (r.type === "png" || r.type === "jpg" || r.type === "jpeg") &&
+      r.sizeBytes != null &&
+      r.sizeBytes >= WEBP_CANDIDATE_BYTES
+    ) {
+      webpCandidates.push(r.id);
+    }
+    // estDecodedBytes = pixels × 4, so pixels = bytes / 4.
+    if (
+      r.kind === "image" &&
+      estDecodedBytes(r) / 4 > screenPx * OVER_DECODE_SCREENS
+    ) {
+      overDecode.push(r.id);
+    }
+    if (r.type === "gif" && (r.sizeBytes ?? 0) >= HEAVY_GIF_BYTES) {
+      heavyGifs.push(r.id);
+    }
+    if (r.kind === "font" && (r.sizeBytes ?? 0) >= HEAVY_FONT_BYTES) {
+      heavyFonts.push(r.id);
+    }
+    if (hasScaleAnomaly(r)) scaleAnomalies.push(r.id);
+  }
+
+  return {
+    duplicates,
+    scaleGaps,
+    webpCandidates,
+    neverLoaded,
+    overDecode,
+    heavyGifs,
+    heavyFonts,
+    scaleAnomalies,
+  };
+}
+

package/src/sync/assetsSyncAdapter.ts

@@ -0,0 +1,151 @@
+/**
+ * Sync adapter for the Assets 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 images).
+ * Exposes the asset inventory to the desktop dashboard and the MCP server.
+ */
+
+import { getScanStatus, rescan } from "../capture/install";
+import { measureSizes } from "../capture/measure";
+import {
+  clearRecords,
+  computeStats,
+  estDecodedBytes,
+  getRecord,
+  getSnapshot,
+  subscribe,
+} from "../store/assetStore";
+import { clearBaseline, getDiff, saveBaseline } from "../store/baseline";
+import { computeInsights } from "../store/insights";
+import type { AssetKind, AssetRecord, AssetRecordWire } from "../types";
+
+const KINDS: AssetKind[] = ["image", "font", "video", "audio", "data", "other"];
+
+function toWire(record: AssetRecord): AssetRecordWire {
+  return {
+    id: record.id,
+    key: record.key,
+    registryId: record.registryId ?? null,
+    name: record.name,
+    type: record.type,
+    kind: record.kind,
+    hash: record.hash ?? null,
+    location: record.httpServerLocation ?? null,
+    width: record.width ?? null,
+    height: record.height ?? null,
+    scales: record.scales,
+    uri: record.resolvedUri ?? null,
+    loaded: record.loaded,
+    sizeBytes:
+      record.sizeSource === "measured"
+        ? (record.sizeBytes ?? null)
+        : estDecodedBytes(record) || null,
+    sizeSource: record.sizeSource ?? null,
+  };
+}
+
+function requireRecord(params: unknown): AssetRecord {
+  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(
+      `Asset record ${id} not found — re-run the list action for current ids.`
+    );
+  }
+  return record;
+}
+
+/** Largest-first is the useful default for an inventory. */
+function bySizeDesc(a: AssetRecord, b: AssetRecord): number {
+  return (b.sizeBytes ?? estDecodedBytes(b)) - (a.sizeBytes ?? estDecodedBytes(a));
+}
+
+function overview() {
+  const snapshot = getSnapshot();
+  return {
+    stats: computeStats(snapshot),
+    scanStatus: getScanStatus(),
+    insights: computeInsights(snapshot),
+    diff: getDiff(),
+    records: [...snapshot].sort(bySizeDesc),
+  };
+}
+
+export const assetsSyncAdapter = {
+  version: 1,
+  getSnapshot: () => {
+    const { records, ...rest } = overview();
+    return { ...rest, records: records.slice(0, 200).map(toWire) };
+  },
+  subscribe: (onChange: () => void) => subscribe(onChange),
+  actions: {
+    /** List assets, largest first. Params: { limit?, kind?, loadedOnly? }. */
+    list: (params: unknown) => {
+      const p = (params ?? {}) as {
+        limit?: number;
+        kind?: string;
+        loadedOnly?: boolean;
+      };
+      const limit = Math.min(Math.max(p.limit ?? 50, 1), 500);
+      const { records, ...rest } = overview();
+      let filtered = records;
+      if (p.kind) {
+        if (!KINDS.includes(p.kind as AssetKind)) {
+          throw new Error(`kind must be one of: ${KINDS.join(", ")}`);
+        }
+        filtered = filtered.filter((r) => r.kind === p.kind);
+      }
+      if (p.loadedOnly) filtered = filtered.filter((r) => r.loaded);
+      return {
+        ...rest,
+        total: filtered.length,
+        records: filtered.slice(0, limit).map(toWire),
+      };
+    },
+    /** Full detail for one asset. Params: { id }. */
+    getDetail: (params: unknown) => {
+      const record = requireRecord(params);
+      return {
+        ...toWire(record),
+        origin: record.origin,
+        fileSystemLocation: record.fileSystemLocation ?? null,
+        files: record.files ?? null,
+        sizesByScale: record.sizesByScale ?? null,
+        estDecodedBytes: estDecodedBytes(record) || null,
+      };
+    },
+    /** Re-walk the registry, merge the Metro graph, refresh fonts, measure sizes. */
+    rescan: async () => {
+      const status = await rescan();
+      return { ok: true, scanStatus: status };
+    },
+    /** (Re-)measure byte sizes from the dev server. */
+    measureSizes: async () => {
+      const result = await measureSizes();
+      return { ok: result.measured > 0, ...result };
+    },
+    /** Persist the current inventory as the comparison baseline. */
+    saveBaseline: async () => {
+      const baseline = await saveBaseline();
+      return {
+        ok: true,
+        savedAt: baseline.savedAt,
+        assets: Object.keys(baseline.entries).length,
+      };
+    },
+    /** Drop the saved baseline. */
+    clearBaseline: async () => {
+      await clearBaseline();
+      return { ok: true, message: "Baseline cleared" };
+    },
+    /** Change vs the saved baseline (null when no baseline exists). */
+    getDiff: () => getDiff(),
+    /** Wipe the store (next rescan rebuilds it). */
+    clearRecords: () => {
+      clearRecords();
+      return { ok: true, message: "Inventory cleared — rescan to rebuild" };
+    },
+    getScanStatus: () => getScanStatus(),
+  },
+};

package/src/types.ts

@@ -0,0 +1,160 @@
+/**
+ * Types for the Assets tool.
+ *
+ * An AssetRecord is one bundled asset (all of its scale variants together —
+ * icon.png + icon@2x.png + icon@3x.png is ONE record, mirroring how Metro
+ * registers it). Records come from two places:
+ *
+ *  - "registry": the runtime @react-native/assets-registry — assets whose
+ *    module has actually been evaluated (`loaded: true`). Works in dev AND
+ *    release, bare RN AND Expo.
+ *  - "graph": the Metro dev server's `<entry>.assets` endpoint — every asset
+ *    in the dependency graph, including ones never required at runtime.
+ *    Dev-only. Graph-only records are the "shipped but never loaded" set.
+ */
+
+export type AssetKind = "image" | "font" | "video" | "audio" | "data" | "other";
+
+export type AssetOrigin = "registry" | "graph";
+
+export interface AssetRecord {
+  id: number;
+  /** Stable identity across sources: `${httpServerLocation}/${name}.${type}`. */
+  key: string;
+  /** Runtime asset id in @react-native/assets-registry (set once evaluated). */
+  registryId?: number;
+  name: string;
+  /** File extension without the dot (png, ttf, mp4, …). */
+  type: string;
+  kind: AssetKind;
+  /** Metro's md5 over ALL scale variants concatenated. */
+  hash?: string;
+  httpServerLocation?: string;
+  /** Logical (scale-divided) dimensions — images only. */
+  width?: number;
+  height?: number;
+  scales: number[];
+  /** resolveAssetSource().uri for this device/environment. */
+  resolvedUri?: string;
+  resolvedScale?: number;
+  /** True once the asset module was evaluated (present in the runtime registry). */
+  loaded: boolean;
+  origin: AssetOrigin;
+  /** Dev-only fields from the Metro graph (stripped from runtime records). */
+  fileSystemLocation?: string;
+  files?: string[];
+  /** Per-scale md5s (Expo graph) — the key into ExpoUpdates.localAssets. */
+  fileHashes?: string[];
+  /** Measured bytes per scale ("1", "2", …) — dev server or file system. */
+  sizesByScale?: Record<string, number>;
+  /** Total measured bytes across all scale variants. */
+  sizeBytes?: number;
+  sizeSource?: "measured" | "estimate";
+  firstSeenAt: number;
+}
+
+/** How the tool learned its inventory + what enrichment is available. */
+export interface AssetsScanStatus {
+  registryAvailable: boolean;
+  /** registerAsset wrapper installed (live updates). */
+  patched: boolean;
+  registryCount: number;
+  /** Metro dev server reachable (graph + size measurement possible). */
+  graphSupported: boolean;
+  /** Assets in the full Metro graph; null until fetched. */
+  graphCount: number | null;
+  graphError: string | null;
+  lastScanAt: number | null;
+  measuring: boolean;
+  measuredCount: number;
+  /** Loaded font families (expo-font native module; [] when unavailable). */
+  fontFamilies: string[];
+  /** Entries in ExpoUpdates.localAssets; null when not an updates env. */
+  localAssetCount: number | null;
+}
+
+export interface AssetsStats {
+  total: number;
+  loaded: number;
+  neverLoaded: number;
+  byKind: Record<AssetKind, { count: number; bytes: number }>;
+  /** Sum of measured bytes only (see measuredCount for coverage). */
+  totalBytes: number;
+  measuredCount: number;
+  fontFamilies: number;
+}
+
+export interface DuplicateInsight {
+  hash: string;
+  /** Record ids sharing the hash. */
+  ids: number[];
+  /** Bytes that could be saved by deduping (null until sizes measured). */
+  wastedBytes: number | null;
+}
+
+export interface AssetsInsights {
+  duplicates: DuplicateInsight[];
+  /** Image records whose scale variants can't serve this device's PixelRatio. */
+  scaleGaps: number[];
+  /** png/jpeg records over the size threshold — WebP conversion candidates. */
+  webpCandidates: number[];
+  /** Records in the bundle graph that no runtime code ever required. */
+  neverLoaded: number[];
+  /** Images that decode to more pixels than 2× this device's entire screen. */
+  overDecode: number[];
+  /** GIFs big enough to hurt (every frame decodes into memory). */
+  heavyGifs: number[];
+  /** Font files over the icon-font-bloat threshold. */
+  heavyFonts: number[];
+  /** Scale variants whose measured bytes contradict their scale (bad export). */
+  scaleAnomalies: number[];
+}
+
+/** Persisted snapshot of the inventory for before/after comparison. */
+export interface AssetsBaseline {
+  savedAt: number;
+  entries: Record<
+    string,
+    { hash: string | null; sizeBytes: number | null; name: string; type: string }
+  >;
+}
+
+export interface AssetsDiff {
+  baselineSavedAt: number;
+  /** Current record ids not present in the baseline. */
+  added: number[];
+  /** Baseline assets no longer in the inventory. */
+  removed: Array<{ key: string; name: string; type: string }>;
+  /** Current record ids whose measured size grew ≥1 KB vs the baseline. */
+  grown: Array<{ id: number; deltaBytes: number }>;
+  /** Sum of measured sizes now minus then; null when sizes are unmeasured. */
+  netBytes: number | null;
+}
+
+/** Slim wire form of a record (desktop dashboard + MCP). */
+export interface AssetRecordWire {
+  id: number;
+  key: string;
+  registryId: number | null;
+  name: string;
+  type: string;
+  kind: AssetKind;
+  hash: string | null;
+  location: string | null;
+  width: number | null;
+  height: number | null;
+  scales: number[];
+  uri: string | null;
+  loaded: boolean;
+  sizeBytes: number | null;
+  sizeSource: "measured" | "estimate" | null;
+}
+
+export interface AssetsSnapshotPayload {
+  stats: AssetsStats;
+  scanStatus: AssetsScanStatus;
+  insights: AssetsInsights;
+  /** Change vs the saved baseline; null when no baseline exists. */
+  diff: AssetsDiff | null;
+  records: AssetRecordWire[];
+}