@buoy-gg/images 7.0.14 → 7.0.16

package/src/components/ImagesModal.tsx

@@ -5,7 +5,7 @@
  * instead of silently empty.
  */
 
-import { useState } from "react";
+import { useEffect, useState } from "react";
 import { FlatList, StyleSheet, Text, View } from "react-native";
 import { JsModal, macOSColors } from "@buoy-gg/shared-ui";
 import type { ModalState } from "@buoy-gg/shared-ui";
@@ -13,7 +13,8 @@ import { getCaptureStatus, installImageCapture } from "../capture/install";
 import { getGlobalModes } from "../capture/overrides";
 import { formatRecordMarkdown, formatRegistryMarkdown } from "../export";
 import { useImageRecords } from "../hooks/useImageRecords";
-import { clearRecords, getRecord } from "../store/imageEventStore";
+import { remoteImagesDispatch } from "../remote";
+import { clearRecords, getRecord, updateRecord } from "../store/imageEventStore";
 import { ImageDetail } from "./ImageDetail";
 import { ImageDetailFooter } from "./ImageDetailFooter";
 import { ImageRow } from "./ImageRow";
@@ -29,6 +30,8 @@ interface ImagesModalProps {
   onBack?: () => void;
   onMinimize?: (modalState: ModalState) => void;
   persistenceKey?: string;
+  /** Render as a plain header-bar + body stack instead of a JsModal (desktop). */
+  inline?: boolean;
 }
 
 function CaptureNotice() {
@@ -72,6 +75,7 @@ export function ImagesModal({
   onBack,
   onMinimize,
   persistenceKey,
+  inline = false,
 }: ImagesModalProps) {
   // Safety net: ensures capture is live even without the early register
   // import (expo-image capture is timing-immune, so this still gets most data).
@@ -81,6 +85,30 @@ export function ImagesModal({
   const [selectedId, setSelectedId] = useState<number | null>(null);
   const selected = selectedId != null ? getRecord(selectedId) : undefined;
 
+  // Mirror mode: the synced wire records omit errorHeaders (detail-only data)
+  // — pull them from the device the first time a failed record is opened.
+  const wantHeadersFor =
+    selected?.status === "error" && selected.errorHeaders == null
+      ? selected.id
+      : null;
+  useEffect(() => {
+    const remote = remoteImagesDispatch();
+    if (wantHeadersFor == null || !remote) return;
+    let cancelled = false;
+    remote("getDetail", { id: wantHeadersFor })
+      .then((detail) => {
+        if (cancelled) return;
+        const headers = (detail as { errorHeaders?: Record<string, string> | null })
+          ?.errorHeaders;
+        // `{}` (not undefined) so a headerless error doesn't refetch forever.
+        updateRecord(wantHeadersFor, { errorHeaders: headers ?? {} });
+      })
+      .catch(() => {});
+    return () => {
+      cancelled = true;
+    };
+  }, [wantHeadersFor]);
+
   // Stepping is relative to the live list (newest first): previous = newer.
   const selectedIndex = selected
     ? records.findIndex((r) => r.id === selected.id)
@@ -104,6 +132,58 @@ export function ImagesModal({
           getGlobalModes()
         );
 
+  const headerContent = (
+    <ImagesHeader
+      stats={stats}
+      detailOpen={selected != null}
+      detailIndex={selectedIndex}
+      detailTotal={records.length}
+      onCloseDetail={() => setSelectedId(null)}
+      onClear={clearRecords}
+      getReport={getReport}
+      onBack={onBack}
+    />
+  );
+
+  const body = selected ? (
+    <View style={styles.detailContainer}>
+      <ImageDetail record={selected} />
+      <ImageDetailFooter
+        key={selected.id}
+        record={selected}
+        hasPrevious={selectedIndex > 0}
+        hasNext={selectedIndex >= 0 && selectedIndex < records.length - 1}
+        onPrevious={() => stepTo(selectedIndex - 1)}
+        onNext={() => stepTo(selectedIndex + 1)}
+      />
+    </View>
+  ) : (
+    <View style={styles.listContainer}>
+      <InsightsBar insights={computeInsights(records)} />
+      <CaptureNotice />
+      <FlatList
+        data={records}
+        keyExtractor={(item: ImageRecord) => String(item.id)}
+        renderItem={({ item }) => <ImageRow record={item} onPress={setSelectedId} />}
+        ListEmptyComponent={<EmptyState />}
+      />
+      <ImagesListFooter />
+    </View>
+  );
+
+  // The ONLY difference between the phone and the desktop dashboard is which
+  // shell the header and body go in. Everything above this is shared.
+  if (inline) {
+    return (
+      <View style={styles.inlineRoot}>
+        {/* Flex-less wrapper — `ModalHeader` is `flex: 1` for JsModal's
+            ROW-direction header slot and would grow vertically here. */}
+        <View style={styles.inlineHeader}>{headerContent}</View>
+        {body}
+      </View>
+    );
+  }
+
   return (
     <JsModal
       visible={visible}
@@ -112,53 +192,41 @@ export function ImagesModal({
       persistenceKey={persistenceKey}
       header={{
         showToggleButton: true,
-        customContent: (
-          <ImagesHeader
-            stats={stats}
-            detailOpen={selected != null}
-            detailIndex={selectedIndex}
-            detailTotal={records.length}
-            onCloseDetail={() => setSelectedId(null)}
-            onClear={clearRecords}
-            getReport={getReport}
-            onBack={onBack}
-          />
-        ),
+        customContent: headerContent,
       }}
       enablePersistence
       initialMode="bottomSheet"
       disableScrollWrapper
     >
-      {selected ? (
-        <View style={styles.detailContainer}>
-          <ImageDetail record={selected} />
-          <ImageDetailFooter
-            key={selected.id}
-            record={selected}
-            hasPrevious={selectedIndex > 0}
-            hasNext={selectedIndex >= 0 && selectedIndex < records.length - 1}
-            onPrevious={() => stepTo(selectedIndex - 1)}
-            onNext={() => stepTo(selectedIndex + 1)}
-          />
-        </View>
-      ) : (
-        <View style={styles.listContainer}>
-          <InsightsBar insights={computeInsights(records)} />
-          <CaptureNotice />
-          <FlatList
-            data={records}
-            keyExtractor={(item: ImageRecord) => String(item.id)}
-            renderItem={({ item }) => <ImageRow record={item} onPress={setSelectedId} />}
-            ListEmptyComponent={<EmptyState />}
-          />
-          <ImagesListFooter />
-        </View>
-      )}
+      {body}
     </JsModal>
   );
 }
 
+/**
+ * The same Images tool as `ImagesModal`, rendered INLINE for hosts that place
+ * tools in a panel rather than a modal (the desktop dashboard). Exists so
+ * there is exactly one implementation of the tool's header, list and detail.
+ */
+export function ImagesToolView(
+  props: Omit<ImagesModalProps, "visible" | "onClose" | "inline"> = {}
+) {
+  return <ImagesModal {...props} inline visible onClose={() => {}} />;
+}
+
 const styles = StyleSheet.create({
+  inlineRoot: {
+    flex: 1,
+    minHeight: 0,
+    backgroundColor: macOSColors.background.base,
+  },
+  inlineHeader: {
+    paddingHorizontal: 12,
+    paddingVertical: 8,
+    borderBottomWidth: 1,
+    borderBottomColor: macOSColors.border.default,
+    backgroundColor: macOSColors.background.card,
+  },
   listContainer: {
     flex: 1,
   },

package/src/index.tsx

@@ -79,6 +79,18 @@ export { formatRecordMarkdown, formatRegistryMarkdown } from "./export";
 // =============================================================================
 export { imagesSyncAdapter } from "./sync/imagesSyncAdapter";
 
+// =============================================================================
+// DASHBOARD MIRROR (Buoy Desktop renders ImagesToolView fed by these)
+// =============================================================================
+export { ImagesToolView } from "./components/ImagesModal";
+export {
+  disableImagesCapture,
+  replaceImagesFromSnapshot,
+} from "./store/imageEventStore";
+export { setRemoteImagesHandler } from "./remote";
+export type { ImagesRemoteDispatch } from "./remote";
+export type { ImageRecordWire, ImagesSnapshotPayload } from "./types";
+
 // =============================================================================
 // STORE + HOOKS
 // =============================================================================

package/src/remote.ts

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

@@ -10,7 +10,7 @@
  * every copy operate on the same data.
  */
 
-import type { ImageRecord } from "./types";
+import type { CaptureStatus, ImageRecord } from "./types";
 
 export interface ImagesGlobalState {
   // store
@@ -51,6 +51,17 @@ export interface ImagesGlobalState {
   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");
@@ -82,6 +93,10 @@ export function imagesState(): ImagesGlobalState {
       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

@@ -10,8 +10,9 @@
  */
 
 import { PixelRatio } from "react-native";
+import { remoteImagesDispatch } from "../remote";
 import { imagesState } from "../state";
-import type { ImageRecord, ImageStats } from "../types";
+import type { ImageRecord, ImageStats, ImagesSnapshotPayload } from "../types";
 
 /** Max records retained before the oldest are dropped. */
 const MAX_RECORDS = 500;
@@ -83,6 +84,9 @@ export function subscribe(listener: () => void): () => void {
 }
 
 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(
@@ -92,14 +96,84 @@ export function clearRecords(): void {
   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 = PixelRatio.get();
+  const scale = effectivePixelRatio();
   return {
     width: Math.round(record.layout.width * scale),
     height: Math.round(record.layout.height * scale),

package/src/sync/imagesSyncAdapter.ts

@@ -40,10 +40,10 @@ import {
   oversizeFactor,
   subscribe,
 } from "../store/imageEventStore";
-import type { ImageRecord } from "../types";
+import type { ImageRecord, ImageRecordWire } from "../types";
 
 /** Slim wire form of a record (heavy/derived fields precomputed + rounded). */
-function toWire(record: ImageRecord) {
+function toWire(record: ImageRecord): ImageRecordWire {
   const factor = oversizeFactor(record);
   return {
     id: record.id,

package/src/types.ts

@@ -97,6 +97,49 @@ export interface ImageStats {
   estWastedBytes: number;
 }
 
+/**
+ * Slim wire form of a record as pushed by the external-sync adapter (heavy
+ * derived math precomputed on device). This is what dashboards receive and
+ * what `replaceFromSnapshot` reconstructs ImageRecords from — keep it in
+ * lockstep with `toWire` in sync/imagesSyncAdapter.ts (and the Flutter port).
+ */
+export interface ImageRecordWire {
+  id: number;
+  lib: ImageLib;
+  uri: string;
+  kind: SourceKind;
+  status: ImageStatus;
+  mounted: boolean;
+  cache: 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;
+}
+
+/** Full snapshot payload the adapter pushes to watching dashboards. */
+export interface ImagesSnapshotPayload {
+  stats?: ImageStats;
+  captureStatus?: CaptureStatus;
+  globalModes?: { network: "normal" | "offline" | "cold"; blank: boolean };
+  insights?: ImageInsights;
+  /** Newest first, capped at 100. */
+  records?: ImageRecordWire[];
+}
+
 /** Capture capability report — what the interceptors managed to hook. */
 export interface CaptureStatus {
   installed: boolean;