@buoy-gg/images 7.0.29 → 7.0.30

package/src/preset.tsx

@@ -1,35 +0,0 @@
-/**
- * Pre-configured Images tool for FloatingDevTools.
- *
- * @example
- * ```tsx
- * import { imagesToolPreset } from '@buoy-gg/images';
- *
- * <FloatingDevTools apps={[imagesToolPreset]} />
- * ```
- */
-
-import { ImagesIcon, IMAGES_ICON_COLOR } from "./components/ImagesIcon";
-import { ImagesModal } from "./components/ImagesModal";
-
-export const imagesToolPreset = {
-  id: "images",
-  name: "IMAGES",
-  description: "Image loads, caching, failures, and oversize checks",
-  slot: "both" as const,
-  icon: ({ size, color }: { size: number; color?: string }) => (
-    <ImagesIcon size={size} color={color || IMAGES_ICON_COLOR} />
-  ),
-  component: ImagesModal,
-};
-
-/** Create a custom Images tool configuration. */
-export function createImagesTool(
-  options: { name?: string; description?: string } = {}
-) {
-  return {
-    ...imagesToolPreset,
-    name: options.name ?? imagesToolPreset.name,
-    description: options.description ?? imagesToolPreset.description,
-  };
-}

package/src/register.ts

@@ -1,17 +0,0 @@
-/**
- * Side-effect entry: installs image capture on import.
- *
- * Import this FIRST in your app entry file so the RN-core <Image> decorator
- * lands before React Native's Image module is evaluated:
- *
- * ```ts
- * import "@buoy-gg/images/register";
- * ```
- *
- * This module intentionally imports nothing that touches react-native's Image
- * (directly or transitively) before installing.
- */
-
-import { installImageCapture } from "./capture/install";
-
-installImageCapture();

package/src/remote.ts

@@ -1,42 +0,0 @@
-/**
- * Remote-dispatch seam for dashboard mirrors (Buoy Desktop).
- *
- * On device this stays null and every action in capture/ runs locally. A
- * dashboard sets a handler that forwards the action name + params over the
- * external-sync protocol to the SAME adapter actions the MCP uses
- * (sync/imagesSyncAdapter.ts), so one action vocabulary serves phone UI,
- * desktop UI, and LLM automation.
- */
-
-import { imagesState } from "./state";
-import type { ActionResult } from "./capture/actions";
-
-export type ImagesRemoteDispatch = (
-  action: string,
-  params?: Record<string, unknown>
-) => Promise<unknown>;
-
-export function setRemoteImagesHandler(
-  handler: ImagesRemoteDispatch | null
-): void {
-  imagesState().remoteDispatch = handler;
-}
-
-export function remoteImagesDispatch(): ImagesRemoteDispatch | null {
-  return imagesState().remoteDispatch;
-}
-
-/** Coerce an adapter action's `{ ok, message }` reply into an ActionResult. */
-export async function remoteActionResult(
-  call: Promise<unknown>
-): Promise<ActionResult> {
-  try {
-    const result = (await call) as { ok?: unknown; message?: unknown } | null;
-    return {
-      ok: !!result?.ok,
-      message: String(result?.message ?? ""),
-    };
-  } catch (error) {
-    return { ok: false, message: String((error as Error)?.message ?? error) };
-  }
-}

package/src/state.ts

@@ -1,103 +0,0 @@
-/**
- * Global singleton state for the Images tool.
- *
- * The package can get evaluated twice as two separate module instances (e.g.
- * the `/register` entry shim resolving to one copy while the package root
- * import resolves to another — lib vs src). If capture state lived in module
- * scope, the early copy would install the RN decorator and collect records
- * while the UI copy read an empty store and a false "decorator never ran"
- * flag. Keying all mutable state on globalThis under a well-known symbol makes
- * every copy operate on the same data.
- */
-
-import type { CaptureStatus, ImageRecord } from "./types";
-
-export interface ImagesGlobalState {
-  // store
-  records: ImageRecord[];
-  byId: Map<number, ImageRecord>;
-  nextId: number;
-  listeners: Set<() => void>;
-  snapshot: ImageRecord[];
-  emitScheduled: boolean;
-  // install flags
-  captureInstalled: boolean;
-  rnInstalled: boolean;
-  expoInstalled: boolean;
-  // rn decorator status
-  decoratorRegistered: boolean;
-  decoratorInvoked: boolean;
-  attachSeen: number;
-  // expo patch status
-  expoAvailable: boolean;
-  expoPatched: boolean;
-  // actions
-  /** recordId → pending reload request for the RN wrapper to consume. */
-  reloadRequests: Map<number, { nonce: number; bust: boolean }>;
-  /** Notified when a reload request is issued (wrappers re-check their nonce). */
-  actionListeners: Set<() => void>;
-  /** recordId → live expo-image class instance (has reloadAsync etc.). */
-  expoInstances: Map<number, unknown>;
-  // simulation overrides
-  /** recordId → active override (source swap / forced error / style merge). */
-  overrides: Map<number, unknown>;
-  /** recordId → epoch-ms until which the locate-flash border is shown. */
-  flashUntil: Map<number, number>;
-  /** Per-record render version (bumped by any action touching that record). */
-  recordVersions: Map<number, number>;
-  /** Render version for global-mode changes (affects every image). */
-  globalVersion: number;
-  /** Monotonic counter feeding both version maps. */
-  versionCounter: number;
-  /** App-wide simulation modes. */
-  globalModes: { network: "normal" | "offline" | "cold"; blank: boolean };
-  // mirror mode (desktop dashboard)
-  /** True on dashboards: local capture must never install (mirror only). */
-  captureDisabled: boolean;
-  /** Forwards actions to the synced device instead of running them locally. */
-  remoteDispatch:
-    | ((action: string, params?: Record<string, unknown>) => Promise<unknown>)
-    | null;
-  /** Device PixelRatio derived from the synced snapshot (layout → neededPx). */
-  mirrorPixelRatio: number | null;
-  /** Device-reported capture status (overrides the local probe on mirrors). */
-  mirrorCaptureStatus: CaptureStatus | null;
-}
-
-const KEY = Symbol.for("buoy.images.globalState.v1");
-
-export function imagesState(): ImagesGlobalState {
-  const g = globalThis as Record<symbol, ImagesGlobalState | undefined>;
-  if (!g[KEY]) {
-    g[KEY] = {
-      records: [],
-      byId: new Map(),
-      nextId: 1,
-      listeners: new Set(),
-      snapshot: [],
-      emitScheduled: false,
-      captureInstalled: false,
-      rnInstalled: false,
-      expoInstalled: false,
-      decoratorRegistered: false,
-      decoratorInvoked: false,
-      attachSeen: 0,
-      expoAvailable: false,
-      expoPatched: false,
-      reloadRequests: new Map(),
-      actionListeners: new Set(),
-      expoInstances: new Map(),
-      overrides: new Map(),
-      flashUntil: new Map(),
-      recordVersions: new Map(),
-      globalVersion: 0,
-      versionCounter: 0,
-      globalModes: { network: "normal", blank: false },
-      captureDisabled: false,
-      remoteDispatch: null,
-      mirrorPixelRatio: null,
-      mirrorCaptureStatus: null,
-    };
-  }
-  return g[KEY];
-}

package/src/store/imageEventStore.ts

@@ -1,236 +0,0 @@
-/**
- * imageEventStore
- *
- * Bounded buffer of ImageRecords fed by the capture layer (installRnImage /
- * installExpoImage). Follows the console tool's store shape — Set of
- * listeners, frame-coalesced emit so bursty image grids don't turn every
- * event into its own React commit — but ALL mutable state lives on the
- * globalThis singleton (see ../state.ts) so a dual module instance of this
- * package still reads/writes one shared store.
- */
-
-import { PixelRatio } from "react-native";
-import { remoteImagesDispatch } from "../remote";
-import { imagesState } from "../state";
-import type { ImageRecord, ImageStats, ImagesSnapshotPayload } from "../types";
-
-/** Max records retained before the oldest are dropped. */
-const MAX_RECORDS = 500;
-
-function emit(): void {
-  const s = imagesState();
-  if (s.emitScheduled) return;
-  s.emitScheduled = true;
-  requestAnimationFrame(() => {
-    s.emitScheduled = false;
-    for (const listener of s.listeners) listener();
-  });
-}
-
-/** Snapshot identity only changes on emit, so useSyncExternalStore stays cheap. */
-function invalidate(): void {
-  const s = imagesState();
-  s.snapshot = [...s.records];
-  emit();
-}
-
-export function createRecord(
-  partial: Omit<ImageRecord, "id" | "createdAt" | "loadCount" | "mounted" | "status">
-): ImageRecord {
-  const s = imagesState();
-  const record: ImageRecord = {
-    ...partial,
-    id: s.nextId++,
-    createdAt: Date.now(),
-    status: "pending",
-    mounted: true,
-    loadCount: 0,
-  };
-  s.records.push(record);
-  s.byId.set(record.id, record);
-  if (s.records.length > MAX_RECORDS) {
-    const dropped = s.records.splice(0, s.records.length - MAX_RECORDS);
-    for (const d of dropped) s.byId.delete(d.id);
-  }
-  invalidate();
-  return record;
-}
-
-/** Mutate a record in place (records are owned by the store) and notify. */
-export function updateRecord(
-  id: number,
-  patch: Partial<ImageRecord>
-): ImageRecord | undefined {
-  const s = imagesState();
-  const record = s.byId.get(id);
-  if (!record) return undefined;
-  Object.assign(record, patch);
-  invalidate();
-  return record;
-}
-
-export function getRecord(id: number): ImageRecord | undefined {
-  return imagesState().byId.get(id);
-}
-
-export function getSnapshot(): ImageRecord[] {
-  return imagesState().snapshot;
-}
-
-export function subscribe(listener: () => void): () => void {
-  const s = imagesState();
-  s.listeners.add(listener);
-  return () => imagesState().listeners.delete(listener);
-}
-
-export function clearRecords(): void {
-  // Mirror mode: clear the device's registry too, or the next snapshot would
-  // refill this store straight away.
-  void remoteImagesDispatch()?.("clearRecords");
-  const s = imagesState();
-  // Keep records still actively loading so in-flight events don't orphan.
-  s.records = s.records.filter(
-    (r) => r.mounted && r.status !== "loaded" && r.status !== "error"
-  );
-  s.byId = new Map(s.records.map((r) => [r.id, r]));
-  invalidate();
-}
-
-// ---------------------------------------------------------------------------
-// Mirror mode (desktop dashboard)
-// ---------------------------------------------------------------------------
-
-/**
- * Dashboards never instrument their own images — the store is purely a mirror
- * of the synced device. Makes installImageCapture() a permanent no-op.
- */
-export function disableImagesCapture(): void {
-  imagesState().captureDisabled = true;
-}
-
-/**
- * Replace the whole store from a synced adapter snapshot (wire records are
- * newest-first; the store keeps oldest-first and useImageRecords reverses).
- * Also adopts the device's global modes / capture status and derives the
- * DEVICE's PixelRatio so oversize math doesn't use the dashboard display's.
- */
-export function replaceImagesFromSnapshot(payload: ImagesSnapshotPayload): void {
-  const s = imagesState();
-  const wire = payload.records ?? [];
-
-  // neededPx was computed on device as round(layout * PixelRatio.get()), so
-  // the widest record recovers the device scale with the least rounding error.
-  let bestWidth = 0;
-  for (const w of wire) {
-    if (w.layout && w.neededPx && w.layout.width > bestWidth) {
-      bestWidth = w.layout.width;
-      s.mirrorPixelRatio = w.neededPx.width / w.layout.width;
-    }
-  }
-
-  const now = Date.now();
-  s.records = [...wire].reverse().map((w) => ({
-    id: w.id,
-    lib: w.lib,
-    uri: w.uri,
-    sourceKind: w.kind,
-    status: w.status,
-    mounted: w.mounted,
-    createdAt: now - w.ageMs,
-    durationMs: w.ms ?? undefined,
-    intrinsic: w.intrinsic ?? undefined,
-    layout: w.layout ?? undefined,
-    cacheVerdict: w.cache ?? undefined,
-    cacheVerdictSource: w.cacheSource ?? undefined,
-    progressSeen: w.progressSeen,
-    // The wire carries only the total; a settled download loaded all of it.
-    bytesLoaded: w.status === "loaded" ? (w.bytesTotal ?? undefined) : undefined,
-    bytesTotal: w.bytesTotal ?? undefined,
-    error: w.error ?? undefined,
-    errorCode: w.errorCode ?? undefined,
-    loadCount: w.loadCount,
-    overrideLabel: w.overrideLabel ?? undefined,
-    hasAltText: w.hasAltText ?? undefined,
-    layoutShifts: w.layoutShifts,
-  }));
-  s.byId = new Map(s.records.map((r) => [r.id, r]));
-  if (payload.globalModes) s.globalModes = { ...payload.globalModes };
-  if (payload.captureStatus) s.mirrorCaptureStatus = payload.captureStatus;
-  invalidate();
-  // Mode toggles render through the actions bus, not the record store.
-  for (const l of s.actionListeners) l();
-}
-
-// ---------------------------------------------------------------------------
-// Derived math (shared by rows, detail view, and stats)
-// ---------------------------------------------------------------------------
-
-/** Device PixelRatio on device; the SYNCED device's ratio on a mirror. */
-export function effectivePixelRatio(): number {
-  return imagesState().mirrorPixelRatio ?? PixelRatio.get();
-}
-
-/** Physical pixels actually needed to fill the laid-out view 1:1. */
-export function neededPixels(record: ImageRecord): { width: number; height: number } | null {
-  if (!record.layout || record.layout.width <= 0 || record.layout.height <= 0) return null;
-  const scale = effectivePixelRatio();
-  return {
-    width: Math.round(record.layout.width * scale),
-    height: Math.round(record.layout.height * scale),
-  };
-}
-
-/**
- * Linear oversize factor: how many times larger (per axis, area-normalized)
- * the decoded bitmap is vs what the view needs. 1 = perfect, 2 = 4× the pixels.
- */
-export function oversizeFactor(record: ImageRecord): number | null {
-  const needed = neededPixels(record);
-  if (!needed || !record.intrinsic) return null;
-  const neededArea = needed.width * needed.height;
-  const intrinsicArea = record.intrinsic.width * record.intrinsic.height;
-  if (neededArea <= 0 || intrinsicArea <= 0) return null;
-  return Math.sqrt(intrinsicArea / neededArea);
-}
-
-/** Estimated decoded-bitmap memory for a loaded record (RGBA8888). */
-export function estDecodedBytes(record: ImageRecord): number {
-  if (!record.intrinsic) return 0;
-  return record.intrinsic.width * record.intrinsic.height * 4;
-}
-
-/** Decoded bytes beyond what the laid-out size needs (0 if not oversized). */
-export function estWastedBytes(record: ImageRecord): number {
-  const needed = neededPixels(record);
-  if (!needed || !record.intrinsic) return 0;
-  const wasted =
-    (record.intrinsic.width * record.intrinsic.height -
-      needed.width * needed.height) *
-    4;
-  return Math.max(0, wasted);
-}
-
-export function computeStats(list: ImageRecord[]): ImageStats {
-  const stats: ImageStats = {
-    total: list.length,
-    loading: 0,
-    loaded: 0,
-    errors: 0,
-    networkLoads: 0,
-    estDecodedBytes: 0,
-    estWastedBytes: 0,
-  };
-  for (const r of list) {
-    // Unmounted in-flight records are stale (the instance died mid-load) —
-    // they must not count as live in-flight work.
-    if ((r.status === "loading" || r.status === "pending") && r.mounted) stats.loading++;
-    if (r.status === "loaded") stats.loaded++;
-    if (r.status === "error") stats.errors++;
-    if (r.progressSeen || r.cacheVerdict === "none") stats.networkLoads++;
-    if (r.mounted && r.status === "loaded") {
-      stats.estDecodedBytes += estDecodedBytes(r);
-      stats.estWastedBytes += estWastedBytes(r);
-    }
-  }
-  return stats;
-}

package/src/store/insights.ts

@@ -1,66 +0,0 @@
-/**
- * Cross-record insights — findings computed purely from data the registry
- * already holds (no extra instrumentation): duplicate simultaneous loads,
- * retry storms, iOS image-queue saturation, missing alt text, and
- * layout-shifting images.
- */
-
-import type { ImageInsights, ImageRecord } from "../types";
-
-/** loadCount at/above this flags render-thrash reload storms. */
-const RETRY_STORM_THRESHOLD = 5;
-/** RCTImageLoader allows 4 concurrent loading tasks on iOS. */
-const IOS_CONCURRENT_LOAD_LIMIT = 4;
-
-export function computeInsights(records: ImageRecord[]): ImageInsights {
-  const byUri = new Map<string, number>();
-  const retryStorms: ImageInsights["retryStorms"] = [];
-  const layoutShifters: ImageInsights["layoutShifters"] = [];
-  let missingAlt = 0;
-  let rnLoading = 0;
-
-  for (const r of records) {
-    if (r.mounted && r.uri) {
-      byUri.set(r.uri, (byUri.get(r.uri) ?? 0) + 1);
-    }
-    if (r.loadCount >= RETRY_STORM_THRESHOLD) {
-      retryStorms.push({ id: r.id, uri: r.uri, loadCount: r.loadCount });
-    }
-    if ((r.layoutShifts ?? 0) > 0) {
-      layoutShifters.push({ id: r.id, uri: r.uri, shifts: r.layoutShifts ?? 0 });
-    }
-    if (r.mounted && r.hasAltText === false) missingAlt++;
-    if (r.lib === "rn" && r.mounted && r.status === "loading") rnLoading++;
-  }
-
-  const duplicates = [...byUri.entries()]
-    .filter(([, count]) => count > 1)
-    .map(([uri, count]) => ({ uri, count }))
-    .sort((a, b) => b.count - a.count);
-
-  return {
-    duplicates,
-    retryStorms: retryStorms.sort((a, b) => b.loadCount - a.loadCount),
-    queueSaturated: rnLoading > IOS_CONCURRENT_LOAD_LIMIT,
-    missingAlt,
-    layoutShifters,
-  };
-}
-
-/** Compact one-line chips for UI/MCP surfacing. Empty array = all clear. */
-export function insightChips(insights: ImageInsights): string[] {
-  const chips: string[] = [];
-  if (insights.duplicates.length > 0) {
-    const extra = insights.duplicates.reduce((n, d) => n + d.count - 1, 0);
-    chips.push(`${insights.duplicates.length} duplicate URL${insights.duplicates.length > 1 ? "s" : ""} (${extra} redundant loads)`);
-  }
-  if (insights.retryStorms.length > 0) {
-    chips.push(`${insights.retryStorms.length} retry storm${insights.retryStorms.length > 1 ? "s" : ""}`);
-  }
-  if (insights.queueSaturated) chips.push("iOS image queue saturated (>4 loading)");
-  if (insights.missingAlt > 0) chips.push(`${insights.missingAlt} missing alt text`);
-  if (insights.layoutShifters.length > 0) {
-    chips.push(`${insights.layoutShifters.length} layout-shifting image${insights.layoutShifters.length > 1 ? "s" : ""}`);
-  }
-  return chips;
-}

package/src/sync/__tests__/imagesSyncAdapter.test.ts

@@ -1,114 +0,0 @@
-import { afterEach, describe, expect, it } from "vitest";
-import { createRecord, updateRecord } from "../../store/imageEventStore";
-import { imagesState } from "../../state";
-import {
-  SNAPSHOT_URI_INLINE_LIMIT,
-  imagesSyncAdapter,
-  toWireUri,
-} from "../imagesSyncAdapter";
-
-// Node has no rAF; the store coalesces listener notifies onto one frame.
-globalThis.requestAnimationFrame = ((cb: (t: number) => void) => {
-  cb(0);
-  return 0;
-}) as typeof requestAnimationFrame;
-
-afterEach(() => {
-  const s = imagesState();
-  s.records = [];
-  s.byId = new Map();
-  s.snapshot = [];
-  s.nextId = 1;
-});
-
-describe("imagesSyncAdapter", () => {
-  it("exposes version 1 and the listed actions", () => {
-    expect(imagesSyncAdapter.version).toBe(1);
-    expect(Object.keys(imagesSyncAdapter.actions)).toEqual(
-      expect.arrayContaining([
-        "list",
-        "getDetail",
-        "clearRecords",
-        "setNetworkMode",
-      ]),
-    );
-  });
-
-  it("keeps http URIs inline and snapshots as JSON", () => {
-    createRecord({
-      lib: "rn",
-      uri: "https://cdn.example.com/hero.png",
-      sourceKind: "network",
-    });
-
-    const snapshot = imagesSyncAdapter.getSnapshot();
-    expect(snapshot.records).toHaveLength(1);
-    expect(snapshot.records[0]?.uri).toBe("https://cdn.example.com/hero.png");
-    expect(snapshot.records[0]?.kind).toBe("network");
-    expect(() => JSON.stringify(snapshot)).not.toThrow();
-  });
-
-  it("does not drop the images snapshot when a data URI is multi-MB", () => {
-    const huge = `data:image/png;base64,${"A".repeat(3 * 1024 * 1024)}`;
-    createRecord({ lib: "rn", uri: huge, sourceKind: "data" });
-
-    const snapshot = imagesSyncAdapter.getSnapshot();
-    expect(snapshot.records).toHaveLength(1);
-    const wired = snapshot.records[0];
-    expect(wired?.kind).toBe("data");
-    expect(wired?.uri).toBe(toWireUri(huge));
-    expect(wired?.uri.length).toBeLessThan(SNAPSHOT_URI_INLINE_LIMIT);
-    expect(wired?.uri.startsWith("data:image/png;base64,")).toBe(true);
-    expect(() => JSON.stringify(snapshot)).not.toThrow();
-    expect(JSON.stringify(snapshot).length).toBeLessThan(2 * 1024 * 1024);
-  });
-
-  it("stubs data URIs in insights as well as records", () => {
-    const huge = `data:image/png;base64,${"B".repeat(80 * 1024)}`;
-    createRecord({ lib: "rn", uri: huge, sourceKind: "data" });
-    createRecord({ lib: "rn", uri: huge, sourceKind: "data" });
-
-    const snapshot = imagesSyncAdapter.getSnapshot();
-    expect(snapshot.insights.duplicates).toHaveLength(1);
-    expect(snapshot.insights.duplicates[0]?.count).toBe(2);
-    expect(snapshot.insights.duplicates[0]?.uri).toBe(toWireUri(huge));
-    expect(snapshot.insights.duplicates[0]?.uri.length).toBeLessThan(
-      SNAPSHOT_URI_INLINE_LIMIT,
-    );
-    expect(JSON.stringify(snapshot).length).toBeLessThan(2 * 1024 * 1024);
-  });
-
-  it("caps native error messages that embed a data URI", () => {
-    const huge = `data:image/png;base64,${"C".repeat(3 * 1024 * 1024)}`;
-    const record = createRecord({
-      lib: "rn",
-      uri: "https://cdn.example.com/hero.png",
-      sourceKind: "network",
-    });
-    updateRecord(record.id, {
-      status: "error",
-      error: `Failed to load ${huge}`,
-    });
-
-    const snapshot = imagesSyncAdapter.getSnapshot();
-    const wired = snapshot.records[0];
-    expect(wired?.error).toBeTruthy();
-    expect(wired?.error?.length).toBeLessThan(SNAPSHOT_URI_INLINE_LIMIT + 80);
-    expect(wired?.error?.startsWith("Failed to load data:image/png;base64,")).toBe(
-      true,
-    );
-    expect(imagesState().byId.get(record.id)?.error?.length).toBeGreaterThan(
-      2 * 1024 * 1024,
-    );
-    expect(() => JSON.stringify(snapshot)).not.toThrow();
-    expect(JSON.stringify(snapshot).length).toBeLessThan(2 * 1024 * 1024);
-  });
-
-  it("does not hang on empty action params", () => {
-    expect(imagesSyncAdapter.actions.list()).toEqual(
-      expect.objectContaining({ total: 0, records: [] }),
-    );
-    expect(() => imagesSyncAdapter.actions.getDetail()).toThrow(/id/);
-    expect(() => imagesSyncAdapter.actions.getDetail({})).toThrow(/id/);
-  });
-});