@tutti-os/workbench-surface 0.0.263 → 0.0.265

package/dist/index.js

@@ -4326,6 +4326,139 @@ function createWorkbenchGenieNodeVisibilityStore() {
   };
 }
 
+// src/preview/workbenchNodePreviewRuntime.ts
+var defaultMaxEntries = 96;
+function createWorkbenchNodePreviewRuntime(input = {}) {
+  const maxEntries = input.maxEntries ?? defaultMaxEntries;
+  const previewByIdentity = /* @__PURE__ */ new Map();
+  const latestPreviewByNodeId = /* @__PURE__ */ new Map();
+  const pendingByIdentity = /* @__PURE__ */ new Map();
+  const activeIdentityByNodeId = /* @__PURE__ */ new Map();
+  const writeIdentity = (identity, previewImageUrl) => {
+    previewByIdentity.delete(identity);
+    previewByIdentity.set(identity, previewImageUrl);
+    trimOldest(previewByIdentity, maxEntries);
+  };
+  const writeLatest = (nodeId, identity, previewImageUrl) => {
+    latestPreviewByNodeId.delete(nodeId);
+    latestPreviewByNodeId.set(nodeId, { identity, previewImageUrl });
+    trimOldest(latestPreviewByNodeId, maxEntries);
+  };
+  return {
+    async ensure(request) {
+      activeIdentityByNodeId.set(request.nodeId, request.identity);
+      const cached = previewByIdentity.get(request.identity);
+      if (cached) {
+        writeLatest(request.nodeId, request.identity, cached);
+        return cached;
+      }
+      const pending = pendingByIdentity.get(request.identity);
+      if (pending) {
+        return pending;
+      }
+      const operation = (async () => {
+        const persistedPreview = await invokePreviewAdapter(
+          request.readPersisted
+        );
+        if (persistedPreview) {
+          writeIdentity(request.identity, persistedPreview);
+          if (activeIdentityByNodeId.get(request.nodeId) === request.identity) {
+            writeLatest(request.nodeId, request.identity, persistedPreview);
+          }
+          return persistedPreview;
+        }
+        const capturedPreview = await invokePreviewAdapter(request.capture);
+        if (!capturedPreview) {
+          return null;
+        }
+        writeIdentity(request.identity, capturedPreview);
+        const isCurrentGeneration = activeIdentityByNodeId.get(request.nodeId) === request.identity;
+        if (isCurrentGeneration) {
+          writeLatest(request.nodeId, request.identity, capturedPreview);
+        }
+        if (isCurrentGeneration && request.writePersisted) {
+          invokePreviewPersistence(request.writePersisted, capturedPreview);
+        }
+        return capturedPreview;
+      })();
+      pendingByIdentity.set(request.identity, operation);
+      try {
+        return await operation;
+      } finally {
+        if (pendingByIdentity.get(request.identity) === operation) {
+          pendingByIdentity.delete(request.identity);
+        }
+      }
+    },
+    read(identity) {
+      const previewImageUrl = previewByIdentity.get(identity) ?? null;
+      if (previewImageUrl) {
+        previewByIdentity.delete(identity);
+        previewByIdentity.set(identity, previewImageUrl);
+      }
+      return previewImageUrl;
+    },
+    readLatest(nodeId) {
+      const latest = latestPreviewByNodeId.get(nodeId) ?? null;
+      if (latest) {
+        latestPreviewByNodeId.delete(nodeId);
+        latestPreviewByNodeId.set(nodeId, latest);
+      }
+      return latest?.previewImageUrl ?? null;
+    },
+    write({ identity, nodeId, previewImageUrl }) {
+      if (!previewImageUrl) {
+        return;
+      }
+      activeIdentityByNodeId.set(nodeId, identity);
+      writeIdentity(identity, previewImageUrl);
+      writeLatest(nodeId, identity, previewImageUrl);
+    }
+  };
+}
+async function invokePreviewAdapter(adapter) {
+  if (!adapter) {
+    return null;
+  }
+  try {
+    return await adapter();
+  } catch {
+    return null;
+  }
+}
+function invokePreviewPersistence(persist, previewImageUrl) {
+  try {
+    void Promise.resolve(persist(previewImageUrl)).catch(() => void 0);
+  } catch {
+  }
+}
+function trimOldest(entries, maxEntries) {
+  while (entries.size > maxEntries) {
+    const oldestKey = entries.keys().next().value;
+    if (oldestKey === void 0) {
+      return;
+    }
+    entries.delete(oldestKey);
+  }
+}
+var workbenchNodePreviewRuntime = createWorkbenchNodePreviewRuntime();
+function workbenchNodePreviewIdentity(nodeId) {
+  return `node:${nodeId}`;
+}
+function workbenchDockPreviewIdentity(key) {
+  return JSON.stringify([
+    key.workspaceId,
+    key.typeId,
+    key.instanceId,
+    key.instanceKey ?? null,
+    key.nodeId,
+    key.revision ?? null
+  ]);
+}
+function workbenchMinimizedDockPreviewIdentity(key, minimizedAtUnixMs) {
+  return `${workbenchDockPreviewIdentity(key)}:${minimizedAtUnixMs ?? "unknown"}`;
+}
+
 // src/react/workbenchGenieScheduling.ts
 function startCachedWorkbenchGenieRestore({
   launch,
@@ -4452,14 +4585,12 @@ var minimizedDockSlotEnterAnimationMs = 720;
 var dockAnchorResolveMaxAnimationFrames = 3;
 var dockPreviewMaxWidth = 260;
 var dockPreviewMaxHeight = 170;
-var dockPreviewImageCacheMaxEntries = 96;
 var minimizedGenieTextureCacheMaxBytes = 64 * 1024 * 1024;
 var minimizedGenieTextureCacheMaxEntries = 8;
 var inlineImageResourceCacheMaxEntries = 160;
 var inlineImageResizeTargetCacheMaxEntries = 4;
 var dockAnchorFallbackSizePx = 43.2;
 var genieInlineImageMaxDevicePixelRatio = 2;
-var dockPreviewImageByNodeID = /* @__PURE__ */ new Map();
 var inlineImageResourceByUrl = /* @__PURE__ */ new Map();
 var resizedInlineImageResourceByUrl = /* @__PURE__ */ new Map();
 function resolveWorkbenchCaptureElement(windowElement) {
@@ -4813,42 +4944,11 @@ function resolveDockAnchorViewportRect(element) {
   };
 }
 function writeCachedWorkbenchNodePreviewImage(nodeID, previewImageUrl) {
-  if (previewImageUrl) {
-    dockPreviewImageByNodeID.delete(nodeID);
-    dockPreviewImageByNodeID.set(nodeID, previewImageUrl);
-    while (dockPreviewImageByNodeID.size > dockPreviewImageCacheMaxEntries) {
-      const oldestNodeID = dockPreviewImageByNodeID.keys().next().value;
-      if (typeof oldestNodeID !== "string") {
-        break;
-      }
-      dockPreviewImageByNodeID.delete(oldestNodeID);
-    }
-  }
-}
-function readCachedWorkbenchNodePreviewImage(nodeID) {
-  return dockPreviewImageByNodeID.get(nodeID) ?? null;
-}
-async function captureWorkbenchNodePreviewImage(nodeID, options = {}) {
-  if (!options.bypassCache) {
-    const cachedPreviewImageUrl = readCachedWorkbenchNodePreviewImage(nodeID);
-    if (cachedPreviewImageUrl) {
-      return cachedPreviewImageUrl;
-    }
-  }
-  const windowElement = Array.from(
-    document.querySelectorAll("[data-workbench-window-id]")
-  ).find((candidate) => candidate.dataset.workbenchWindowId === nodeID) ?? null;
-  const captureTarget = windowElement ? resolveWorkbenchCaptureElement(windowElement) : null;
-  if (!captureTarget) {
-    return null;
-  }
-  const texture = await captureElementTexture(captureTarget, {
-    maxHeight: dockPreviewMaxHeight,
-    maxWidth: dockPreviewMaxWidth
-  }).catch(() => null);
-  const previewImageUrl = texture ? createDockPreviewDataUrl(texture.canvas) : null;
-  writeCachedWorkbenchNodePreviewImage(nodeID, previewImageUrl);
-  return previewImageUrl;
+  workbenchNodePreviewRuntime.write({
+    identity: workbenchNodePreviewIdentity(nodeID),
+    nodeId: nodeID,
+    previewImageUrl
+  });
 }
 async function captureProvidedWorkbenchNodePreviewImageForNode(node, input = {}) {
   const previewImageUrl = await Promise.resolve(
@@ -9008,11 +9108,11 @@ import { Component, memo as memo3, useCallback as useCallback14, useMemo as useM
 // src/host/WorkbenchHostDock.tsx
 import {
   useCallback as useCallback13,
-  useEffect as useEffect12,
+  useEffect as useEffect13,
   useLayoutEffect as useLayoutEffect7,
   useMemo as useMemo10,
   useRef as useRef11,
-  useState as useState10
+  useState as useState11
 } from "react";
 import {
   ArrowLeftIcon,
@@ -9022,6 +9122,141 @@ import {
   ChevronUpIcon
 } from "@tutti-os/ui-system";
 
+// src/host/useWorkbenchMinimizedDockPreview.ts
+import { useEffect as useEffect7, useState as useState6 } from "react";
+function useWorkbenchMinimizedDockPreview({
+  capturePreview,
+  deferPreview,
+  dockPreviewCache,
+  node,
+  providePreview,
+  workspaceId
+}) {
+  const [componentPreview, setComponentPreview] = useState6(void 0);
+  const [previewImageUrl, setPreviewImageUrl] = useState6(
+    () => deferPreview ? null : workbenchNodePreviewRuntime.readLatest(node.id)
+  );
+  useEffect7(() => {
+    if (deferPreview || !providePreview || componentPreview !== void 0 || previewImageUrl) {
+      return void 0;
+    }
+    return scheduleDeferredPreview(() => {
+      setComponentPreview(providePreview(node) ?? null);
+    });
+  }, [
+    componentPreview,
+    deferPreview,
+    node.data.instanceId,
+    node.data.instanceKey,
+    node.data.typeId,
+    node.id,
+    node.minimizedAtUnixMs,
+    previewImageUrl,
+    providePreview
+  ]);
+  useEffect7(() => {
+    if (deferPreview) {
+      return void 0;
+    }
+    let active = true;
+    const cachedPreview = readWorkbenchMinimizedDockPreviewImage(node.id);
+    setPreviewImageUrl(cachedPreview);
+    void resolveWorkbenchMinimizedDockPreviewImage({
+      capturePreview: capturePreview ? () => Promise.resolve(capturePreview(node)) : void 0,
+      dockPreviewCache,
+      node,
+      workspaceId
+    }).then((nextPreview) => {
+      if (active && nextPreview) {
+        setPreviewImageUrl(nextPreview);
+      }
+    });
+    return () => {
+      active = false;
+    };
+  }, [
+    capturePreview,
+    deferPreview,
+    dockPreviewCache,
+    node.data.instanceId,
+    node.data.instanceKey,
+    node.data.typeId,
+    node.id,
+    node.minimizedAtUnixMs,
+    workspaceId
+  ]);
+  return { componentPreview, previewImageUrl };
+}
+function readWorkbenchMinimizedDockPreviewImage(nodeId) {
+  return workbenchNodePreviewRuntime.readLatest(nodeId);
+}
+function resolveWorkbenchMinimizedDockPreviewRevision(node) {
+  return String(node.minimizedAtUnixMs);
+}
+function resolveWorkbenchMinimizedDockPreviewImage({
+  capturePreview,
+  dockPreviewCache,
+  node,
+  workspaceId
+}) {
+  const cacheKey = {
+    instanceId: node.data.instanceId,
+    instanceKey: node.data.instanceKey ?? null,
+    nodeId: node.id,
+    revision: resolveWorkbenchMinimizedDockPreviewRevision(node),
+    typeId: node.data.typeId,
+    workspaceId
+  };
+  const genieCacheKey = {
+    ...cacheKey,
+    revision: void 0
+  };
+  return workbenchNodePreviewRuntime.ensure({
+    capture: capturePreview,
+    identity: workbenchMinimizedDockPreviewIdentity(
+      cacheKey,
+      node.minimizedAtUnixMs
+    ),
+    nodeId: node.id,
+    readPersisted: dockPreviewCache ? async () => await dockPreviewCache.read(cacheKey) ?? dockPreviewCache.read(genieCacheKey) : void 0,
+    writePersisted: dockPreviewCache ? (previewImageUrl) => dockPreviewCache.write({ key: cacheKey, previewImageUrl }) : void 0
+  });
+}
+function scheduleDeferredPreview(run) {
+  let cancelled = false;
+  let frameId = null;
+  let idleId = null;
+  let timeoutId = null;
+  const invoke = () => {
+    if (!cancelled) {
+      run();
+    }
+  };
+  const scheduler = globalThis;
+  if (typeof scheduler.requestIdleCallback === "function") {
+    idleId = scheduler.requestIdleCallback(invoke, { timeout: 250 });
+  } else if (typeof scheduler.requestAnimationFrame === "function") {
+    frameId = scheduler.requestAnimationFrame(() => {
+      frameId = null;
+      timeoutId = globalThis.setTimeout(invoke, 0);
+    });
+  } else {
+    timeoutId = globalThis.setTimeout(invoke, 0);
+  }
+  return () => {
+    cancelled = true;
+    if (idleId !== null && typeof scheduler.cancelIdleCallback === "function") {
+      scheduler.cancelIdleCallback(idleId);
+    }
+    if (frameId !== null && typeof scheduler.cancelAnimationFrame === "function") {
+      scheduler.cancelAnimationFrame(frameId);
+    }
+    if (timeoutId !== null) {
+      globalThis.clearTimeout(timeoutId);
+    }
+  };
+}
+
 // src/host/dockEntries.ts
 function matchWorkbenchDockEntryNode(entry, node) {
   if (typeof node.data.dockEntryId === "string") {
@@ -9149,7 +9384,7 @@ function isWorkbenchDockEntryBlocked(entry) {
 }
 
 // src/host/dockMagnification.ts
-import { useCallback as useCallback10, useEffect as useEffect7, useRef as useRef6 } from "react";
+import { useCallback as useCallback10, useEffect as useEffect8, useRef as useRef6 } from "react";
 
 // src/host/dockMagnificationBounds.ts
 var DOCK_MAGNIFICATION_CROSS_AXIS_PADDING = 8;
@@ -9832,7 +10067,7 @@ function useDockMagnification({
   );
   handleGlobalPointerMoveRef.current = handlePointerMove;
   handleGlobalPointerCancelRef.current = handleGlobalPointerCancel;
-  useEffect7(() => {
+  useEffect8(() => {
     if (typeof document === "undefined") {
       return;
     }
@@ -9962,7 +10197,7 @@ function useDockMagnification({
     entryRampStartedAtRef.current = null;
     setMagnifyActive(false);
   }, [setMagnifyActive, slotRefs, stopAnimation, stopGlobalPointerTracking]);
-  useEffect7(
+  useEffect8(
     () => () => {
       resetMagnification();
     },
@@ -10158,7 +10393,7 @@ function orderWorkbenchMinimizedDockNodes(input) {
 }
 
 // src/host/minimizedDockStackPromotion.ts
-import { useEffect as useEffect8, useRef as useRef7, useState as useState6 } from "react";
+import { useEffect as useEffect9, useRef as useRef7, useState as useState7 } from "react";
 var minimizedDockStackPromotionDurationMs = 520;
 function detectMinimizedDockStackPromotion(previous, next) {
   const previousVisibleNodeIds = new Set(
@@ -10180,9 +10415,9 @@ function detectMinimizedDockStackPromotion(previous, next) {
 function useMinimizedDockStackPromotion(slots) {
   const previousSlotsRef = useRef7(slots);
   const promotionTimerRef = useRef7(null);
-  const [promotedNodeId, setPromotedNodeId] = useState6(null);
-  const [stackDispatching, setStackDispatching] = useState6(false);
-  useEffect8(() => {
+  const [promotedNodeId, setPromotedNodeId] = useState7(null);
+  const [stackDispatching, setStackDispatching] = useState7(false);
+  useEffect9(() => {
     const promotedNodeId2 = detectMinimizedDockStackPromotion(
       previousSlotsRef.current,
       slots
@@ -10248,10 +10483,10 @@ function resolveWorkbenchMinimizedDockRestoreIntent(input) {
 // src/host/WorkbenchHostDockPopup.tsx
 import {
   useCallback as useCallback12,
-  useEffect as useEffect11,
+  useEffect as useEffect12,
   useLayoutEffect as useLayoutEffect6,
   useRef as useRef10,
-  useState as useState9
+  useState as useState10
 } from "react";
 import { createPortal as createPortal3 } from "react-dom";
 import { FileCreateIcon as FileCreateIcon2, cn as cn2 } from "@tutti-os/ui-system";
@@ -10405,9 +10640,9 @@ function resolveDockPopupVerticalClampOffsetPx(input) {
 import {
   forwardRef,
   useCallback as useCallback11,
-  useEffect as useEffect9,
+  useEffect as useEffect10,
   useRef as useRef8,
-  useState as useState7
+  useState as useState8
 } from "react";
 import {
   Button as Button2,
@@ -10638,9 +10873,9 @@ var WorkbenchHostDockPopupCard = forwardRef(function WorkbenchHostDockPopupCard2
 }, ref) {
   const title = item.title?.trim() || item.node.title;
   const isMinimizedStack = variant === "minimized-stack";
-  const [isLaunching, setIsLaunching] = useState7(false);
+  const [isLaunching, setIsLaunching] = useState8(false);
   const launchTimerRef = useRef8(null);
-  useEffect9(
+  useEffect10(
     () => () => {
       if (launchTimerRef.current !== null) {
         clearTimeout(launchTimerRef.current);
@@ -10812,7 +11047,7 @@ function WorkbenchHostDockPopupCardLabel({ title }) {
 }
 
 // src/host/useWorkbenchHostDockPopupPreviewCapture.ts
-import { useEffect as useEffect10, useLayoutEffect as useLayoutEffect5, useRef as useRef9, useState as useState8 } from "react";
+import { useEffect as useEffect11, useLayoutEffect as useLayoutEffect5, useRef as useRef9, useState as useState9 } from "react";
 var dockPopupPreviewCacheMaxEntries = 64;
 var dockPopupPreviewByMemoryKey = /* @__PURE__ */ new Map();
 var pendingDockPopupPreviewCaptureKeys = /* @__PURE__ */ new Set();
@@ -10826,7 +11061,7 @@ function useWorkbenchHostDockPopupPreviewCapture(input) {
     resolveDockPreviewCacheKey: resolveDockPreviewCacheKey2
   } = input;
   const hasCapturePreview = Boolean(capturePreview);
-  const [capturedPreviewByMemoryKey, setCapturedPreviewByMemoryKey] = useState8({});
+  const [capturedPreviewByMemoryKey, setCapturedPreviewByMemoryKey] = useState9({});
   const capturedPreviewByMemoryKeyRef = useRef9(capturedPreviewByMemoryKey);
   const capturePreviewRef = useRef9(capturePreview);
   const debugDiagnosticsRef = useRef9(debugDiagnostics);
@@ -10855,13 +11090,13 @@ function useWorkbenchHostDockPopupPreviewCapture(input) {
       previewCaptureItemStateKeys
     );
   });
-  useEffect10(() => {
+  useEffect11(() => {
     isMountedRef.current = true;
     return () => {
       isMountedRef.current = false;
     };
   }, []);
-  useEffect10(() => {
+  useEffect11(() => {
     if (!capturePreviewRef.current || isContextMenu) {
       return;
     }
@@ -11280,9 +11515,9 @@ function WorkbenchHostDockPopup({
   );
   const popupRootRef = useRef10(null);
   const minimizedStackViewportRef = useRef10(null);
-  const [pointer, setPointer] = useState9(null);
-  const [minimizedStackScrollOffset, setMinimizedStackScrollOffset] = useState9(0);
-  const [verticalClampOffsetPx, setVerticalClampOffsetPx] = useState9(0);
+  const [pointer, setPointer] = useState10(null);
+  const [minimizedStackScrollOffset, setMinimizedStackScrollOffset] = useState10(0);
+  const [verticalClampOffsetPx, setVerticalClampOffsetPx] = useState10(0);
   const { previewStateFor } = useWorkbenchHostDockPopupPreviewCapture({
     capturePreview,
     debugDiagnostics,
@@ -11360,7 +11595,7 @@ function WorkbenchHostDockPopup({
     } : {}
   };
   const popupDiagnosticKey = items.map((item) => item.node.id).join("|");
-  useEffect11(() => {
+  useEffect12(() => {
     logWorkbenchDockPopupDebug("dock.popup.rendered", debugDiagnostics, {
       hasCapturePreview: Boolean(capturePreview),
       itemCount: popupDiagnosticKey ? popupDiagnosticKey.split("|").length : 0,
@@ -11442,7 +11677,7 @@ function WorkbenchHostDockPopup({
     cardRefCallbacksRef.current.set(nodeId, callback);
     return callback;
   }, []);
-  useEffect11(() => {
+  useEffect12(() => {
     if (!isLeftMinimizedStack) {
       return;
     }
@@ -11454,7 +11689,7 @@ function WorkbenchHostDockPopup({
       document.body.removeAttribute("data-desktop-dock-minimized-stack-open");
     };
   }, [isLeftMinimizedStack]);
-  useEffect11(() => {
+  useEffect12(() => {
     const handlePointerDown = (event) => {
       if (!(event.target instanceof Element)) {
         onClose();
@@ -11479,13 +11714,13 @@ function WorkbenchHostDockPopup({
       window.removeEventListener("keydown", handleKeyDown);
     };
   }, [onClose]);
-  useEffect11(() => {
+  useEffect12(() => {
     if (!isMinimizedStack) {
       return;
     }
     setMinimizedStackScrollOffset(initialMinimizedStackScrollOffset);
   }, [initialMinimizedStackScrollOffset, isMinimizedStack, items.length]);
-  useEffect11(() => {
+  useEffect12(() => {
     if (!isMinimizedStack) {
       return;
     }
@@ -11756,27 +11991,27 @@ function WorkbenchHostDock({
   const attentionTimeouts = useRef11(
     /* @__PURE__ */ new Map()
   );
-  const [activeAttentionEntryIds, setActiveAttentionEntryIds] = useState10(/* @__PURE__ */ new Set());
-  const [activePopup, setActivePopup] = useState10(null);
-  const [activeHoverPanel, setActiveHoverPanel] = useState10(null);
-  const [activeLabelTooltip, setActiveLabelTooltip] = useState10(null);
-  const [activeMinimizedStackPopup, setActiveMinimizedStackPopup] = useState10(null);
-  const [pendingActionKeys, setPendingActionKeys] = useState10(
+  const [activeAttentionEntryIds, setActiveAttentionEntryIds] = useState11(/* @__PURE__ */ new Set());
+  const [activePopup, setActivePopup] = useState11(null);
+  const [activeHoverPanel, setActiveHoverPanel] = useState11(null);
+  const [activeLabelTooltip, setActiveLabelTooltip] = useState11(null);
+  const [activeMinimizedStackPopup, setActiveMinimizedStackPopup] = useState11(null);
+  const [pendingActionKeys, setPendingActionKeys] = useState11(
     () => /* @__PURE__ */ new Set()
   );
-  const [dockFrameSize, setDockFrameSize] = useState10(null);
+  const [dockFrameSize, setDockFrameSize] = useState11(null);
   const { triggerDockBounce } = useDockBounce(slotRefs);
-  const [dockScrollState, setDockScrollState] = useState10(() => ({
+  const [dockScrollState, setDockScrollState] = useState11(() => ({
     canScrollBackward: false,
     canScrollForward: false,
     hasOverflow: false
   }));
-  const [dockStateRevision, setDockStateRevision] = useState10(0);
-  const [externalStateRevision, setExternalStateRevision] = useState10(0);
+  const [dockStateRevision, setDockStateRevision] = useState11(0);
+  const [externalStateRevision, setExternalStateRevision] = useState11(0);
   const [
     collapsingMinimizedLaunchAnchorKeys,
     setCollapsingMinimizedLaunchAnchorKeys
-  ] = useState10(() => /* @__PURE__ */ new Set());
+  ] = useState11(() => /* @__PURE__ */ new Set());
   const collapsingMinimizedLaunchTimerRef = useRef11(
     /* @__PURE__ */ new Map()
   );
@@ -11803,7 +12038,7 @@ function WorkbenchHostDock({
     labelTooltipOpenTimerRef.current = null;
     labelTooltipScheduledPointRef.current = null;
   }, []);
-  useEffect12(
+  useEffect13(
     () => () => {
       clearHoverPanelCloseTimer();
       clearHoverPanelOpenTimer();
@@ -11897,7 +12132,7 @@ function WorkbenchHostDock({
     pendingDockStateRefreshRef.current = false;
     setDockStateRevision((revision) => revision + 1);
   }, []);
-  useEffect12(() => {
+  useEffect13(() => {
     if (!dockStateSource) {
       return void 0;
     }
@@ -12003,10 +12238,10 @@ function WorkbenchHostDock({
     }
     dockMeasureRef.current?.removeAttribute("data-dock-hover-panel-open");
   }, []);
-  useEffect12(() => {
+  useEffect13(() => {
     activeHoverPanelRef.current = activeHoverPanel;
   }, [activeHoverPanel]);
-  useEffect12(() => {
+  useEffect13(() => {
     activeLabelTooltipRef.current = activeLabelTooltip;
   }, [activeLabelTooltip]);
   const closeLabelTooltipImmediate = useCallback13(
@@ -12478,7 +12713,7 @@ function WorkbenchHostDock({
       })()
     )
   );
-  useEffect12(() => {
+  useEffect13(() => {
     const shouldSubscribe = activePopup !== null || hasMinimizedPreviewCapture;
     if (!shouldSubscribe || !externalStateSource?.subscribeNodeState) {
       return void 0;
@@ -12503,7 +12738,7 @@ function WorkbenchHostDock({
     hasMinimizedPreviewCapture,
     workspaceId
   ]);
-  useEffect12(() => {
+  useEffect13(() => {
     const nextAttentionIds = /* @__PURE__ */ new Set();
     for (const entry of renderedDockEntries) {
       const nextToken = entry.attentionToken ?? null;
@@ -12544,7 +12779,7 @@ function WorkbenchHostDock({
       );
     }
   }, [renderedDockEntries]);
-  useEffect12(
+  useEffect13(
     () => () => {
       for (const timeout of attentionTimeouts.current.values()) {
         globalThis.clearTimeout(timeout);
@@ -13613,7 +13848,12 @@ function WorkbenchHostDock({
             placement: dockPlacement,
             debugDiagnostics,
             capturePreview: async (item) => {
-              const src = await captureMinimizedNodePreview(item.node);
+              const src = await resolveWorkbenchMinimizedDockPreviewImage({
+                capturePreview: () => captureMinimizedNodePreview(item.node),
+                dockPreviewCache,
+                node: item.node,
+                workspaceId
+              });
               return src ? { kind: "image", src } : null;
             },
             dockPreviewCache,
@@ -13632,10 +13872,10 @@ function WorkbenchHostDock({
                 isMinimized: true,
                 node,
                 preview: minimizedDock?.kind === "component" ? provideMinimizedNodePreview(node) ?? null : minimizedDock?.kind === "snapshot" && minimizedDock.capturePreview ? null : (() => {
-                  const previewImageUrl = readCachedWorkbenchNodePreviewImage(node.id);
+                  const previewImageUrl = readWorkbenchMinimizedDockPreviewImage(node.id);
                   return previewImageUrl ? { kind: "image", src: previewImageUrl } : null;
                 })(),
-                previewRevision: null,
+                previewRevision: resolveWorkbenchMinimizedDockPreviewRevision(node),
                 subtitle: node.data.instanceKey ?? node.data.instanceId,
                 title: node.title
               };
@@ -13706,115 +13946,14 @@ function WorkbenchHostDockMinimizedNodePreview({
   providePreview,
   workspaceId
 }) {
-  const [componentPreview, setComponentPreview] = useState10(void 0);
-  const [previewImageUrl, setPreviewImageUrl] = useState10(
-    () => deferPreview ? null : readCachedWorkbenchNodePreviewImage(node.id)
-  );
-  useEffect12(() => {
-    if (deferPreview || !providePreview || componentPreview !== void 0 || previewImageUrl) {
-      return void 0;
-    }
-    let cancelled = false;
-    let frameId = null;
-    let idleId = null;
-    let timeoutId = null;
-    const setDeferredComponentPreview = () => {
-      if (cancelled) {
-        return;
-      }
-      setComponentPreview(providePreview(node) ?? null);
-    };
-    const scheduler = globalThis;
-    if (typeof scheduler.requestIdleCallback === "function") {
-      idleId = scheduler.requestIdleCallback(setDeferredComponentPreview, {
-        timeout: 250
-      });
-    } else if (typeof scheduler.requestAnimationFrame === "function") {
-      frameId = scheduler.requestAnimationFrame(() => {
-        frameId = null;
-        timeoutId = globalThis.setTimeout(setDeferredComponentPreview, 0);
-      });
-    } else {
-      timeoutId = globalThis.setTimeout(setDeferredComponentPreview, 0);
-    }
-    return () => {
-      cancelled = true;
-      if (idleId !== null && typeof scheduler.cancelIdleCallback === "function") {
-        scheduler.cancelIdleCallback(idleId);
-      }
-      if (frameId !== null && typeof scheduler.cancelAnimationFrame === "function") {
-        scheduler.cancelAnimationFrame(frameId);
-      }
-      if (timeoutId !== null) {
-        globalThis.clearTimeout(timeoutId);
-      }
-    };
-  }, [
-    componentPreview,
-    deferPreview,
-    node.data.instanceId,
-    node.data.instanceKey,
-    node.data.typeId,
-    node.id,
-    node.minimizedAtUnixMs,
-    previewImageUrl,
-    providePreview
-  ]);
-  useEffect12(() => {
-    if (deferPreview) {
-      return void 0;
-    }
-    let cancelled = false;
-    const cachedPreviewImageUrl = readCachedWorkbenchNodePreviewImage(node.id);
-    setPreviewImageUrl(cachedPreviewImageUrl);
-    const cacheKey = resolveDockPreviewCacheKey(workspaceId, node);
-    if (!cachedPreviewImageUrl && dockPreviewCache) {
-      void dockPreviewCache.read(cacheKey).catch(() => null).then((persistedPreview) => {
-        if (cancelled || !persistedPreview) {
-          return;
-        }
-        writeCachedWorkbenchNodePreviewImage(node.id, persistedPreview);
-        setPreviewImageUrl(persistedPreview);
-      });
-    }
-    if (capturePreview) {
-      void Promise.resolve(capturePreview(node)).catch(() => null).then((nextPreview) => {
-        if (cancelled || !nextPreview) {
-          return;
-        }
-        writeCachedWorkbenchNodePreviewImage(node.id, nextPreview);
-        dockPreviewCache?.write({
-          key: cacheKey,
-          previewImageUrl: nextPreview
-        });
-        setPreviewImageUrl(nextPreview);
-      });
-    }
-    if (cachedPreviewImageUrl || node.isMinimized || capturePreview) {
-      return () => {
-        cancelled = true;
-      };
-    }
-    void captureWorkbenchNodePreviewImage(node.id).then((nextPreview) => {
-      if (!cancelled) {
-        setPreviewImageUrl(nextPreview);
-      }
-    });
-    return () => {
-      cancelled = true;
-    };
-  }, [
+  const { componentPreview, previewImageUrl } = useWorkbenchMinimizedDockPreview({
     capturePreview,
     deferPreview,
     dockPreviewCache,
-    node.data.instanceId,
-    node.data.instanceKey,
-    node.data.typeId,
-    node.id,
-    node.minimizedAtUnixMs,
+    node,
     providePreview,
     workspaceId
-  ]);
+  });
   if (deferPreview) {
     return renderMinimizedDockPreviewPlaceholder(className);
   }
@@ -13895,7 +14034,7 @@ function WorkbenchHostDockFrozenComponentPreview({
   preview
 }) {
   const sourceRef = useRef11(null);
-  const [frozenMarkup, setFrozenMarkup] = useState10(null);
+  const [frozenMarkup, setFrozenMarkup] = useState11(null);
   useLayoutEffect7(() => {
     if (frozenMarkup !== null) {
       return;
@@ -14295,7 +14434,7 @@ function useDockPresenceItems(items, shouldAnimateMinimizedDockEnter) {
   latestItemsByKey.current = new Map(items.map((item) => [item.key, item]));
   shouldAnimateMinimizedDockEnterRef.current = shouldAnimateMinimizedDockEnter;
   const itemKeys = items.map((item) => item.key).join("\0");
-  const [presentItems, setPresentItems] = useState10(
+  const [presentItems, setPresentItems] = useState11(
     () => items.map((item) => ({
       item,
       key: item.key,
@@ -14303,7 +14442,7 @@ function useDockPresenceItems(items, shouldAnimateMinimizedDockEnter) {
     }))
   );
   const initialized = useRef11(false);
-  useEffect12(() => {
+  useEffect13(() => {
     let nextSettleMs = dockPresenceAnimationMs;
     setPresentItems((current) => {
       const filteredItems = resolveDockPresenceItems({
@@ -14341,7 +14480,7 @@ function useDockWallpaperTones({
   elementRefs,
   itemKeys
 }) {
-  const [tones, setTones] = useState10(
+  const [tones, setTones] = useState11(
     () => /* @__PURE__ */ new Map()
   );
   useLayoutEffect7(() => {
@@ -14546,7 +14685,7 @@ function useDockBounce(slotRefs) {
     },
     [slotRefs]
   );
-  useEffect12(
+  useEffect13(
     () => () => {
       for (const anchorKey of timeoutsRef.current.keys()) {
         clearDockBounce(anchorKey);
@@ -15624,6 +15763,186 @@ function WorkbenchHost({
 // src/host/activations.ts
 var workbenchFocusInputActivationType = "focus-input";
 
+// src/preview/createWorkbenchNodePreviewCaptureAdapter.ts
+var defaultCaptureTimeoutMs = 2500;
+function createWorkbenchNodePreviewCaptureAdapter(options) {
+  const {
+    captureRect,
+    diagnostics,
+    maxHeight,
+    maxWidth,
+    resolveDiagnosticContext,
+    timeoutMs = defaultCaptureTimeoutMs
+  } = options;
+  return async (node) => {
+    const diagnosticContext = resolveDiagnosticContext?.(node) ?? {};
+    const emit = (diagnostic) => {
+      emitDiagnostic(diagnostics, {
+        ...diagnostic,
+        details: { ...diagnosticContext, ...diagnostic.details }
+      });
+    };
+    emit({
+      details: {
+        documentVisibilityState: document.visibilityState,
+        isMinimized: node.isMinimized,
+        nodeId: node.id
+      },
+      event: "capture_requested",
+      level: "debug"
+    });
+    const skip = resolveCaptureTarget(node);
+    if (skip.status === "skipped") {
+      emit({
+        details: {
+          ...skip.details,
+          nodeId: node.id,
+          reason: skip.reason
+        },
+        event: "capture_skipped",
+        level: skip.level
+      });
+      return null;
+    }
+    const rect = skip.target.getBoundingClientRect();
+    if (!isUsableCaptureRect(rect)) {
+      emit({
+        details: {
+          nodeId: node.id,
+          reason: "capture_rect_invalid",
+          rect: captureRectDetails(rect),
+          viewport: { height: window.innerHeight, width: window.innerWidth }
+        },
+        event: "capture_skipped",
+        level: "warn"
+      });
+      return null;
+    }
+    const input = {
+      maxHeight,
+      maxWidth,
+      nodeId: node.id,
+      rect: captureRectDetails(rect)
+    };
+    emit({
+      details: { ...input, timeoutMs },
+      event: "capture_started",
+      level: "info"
+    });
+    const startedAt = performance.now();
+    const capturePromise = Promise.resolve().then(() => captureRect(input));
+    const outcome = await resolveCaptureOutcome(capturePromise, timeoutMs);
+    if (outcome.status === "timed_out") {
+      emit({
+        details: {
+          durationMs: Math.round(performance.now() - startedAt),
+          nodeId: node.id,
+          timeoutMs
+        },
+        event: "capture_timed_out",
+        level: "warn"
+      });
+      return null;
+    }
+    if (outcome.status === "failed") {
+      emit({
+        details: {
+          durationMs: Math.round(performance.now() - startedAt),
+          error: serializeError(outcome.error),
+          nodeId: node.id
+        },
+        event: "capture_failed",
+        level: "warn"
+      });
+      return null;
+    }
+    emit({
+      details: {
+        dockPreviewImageUrlLength: outcome.previewImages?.dockPreviewImageUrl?.length ?? 0,
+        durationMs: Math.round(performance.now() - startedAt),
+        genieImageUrlLength: outcome.previewImages?.genieImageUrl?.length ?? 0,
+        hasResult: outcome.previewImages !== null,
+        nodeId: node.id
+      },
+      event: "capture_resolved",
+      level: outcome.previewImages ? "info" : "warn"
+    });
+    return outcome.previewImages;
+  };
+}
+function resolveCaptureTarget(node) {
+  if (node.isMinimized) {
+    return { level: "debug", reason: "node_minimized", status: "skipped" };
+  }
+  if (document.visibilityState !== "visible") {
+    return {
+      details: { documentVisibilityState: document.visibilityState },
+      level: "debug",
+      reason: "document_not_visible",
+      status: "skipped"
+    };
+  }
+  const windowElement = Array.from(
+    document.querySelectorAll("[data-workbench-window-id]")
+  ).find((candidate) => candidate.dataset.workbenchWindowId === node.id) ?? null;
+  if (!windowElement) {
+    return {
+      level: "warn",
+      reason: "window_element_missing",
+      status: "skipped"
+    };
+  }
+  if (windowElement.dataset.focused !== "true") {
+    return {
+      details: { focused: windowElement.dataset.focused ?? null },
+      level: "debug",
+      reason: "window_not_focused",
+      status: "skipped"
+    };
+  }
+  return {
+    status: "ready",
+    target: windowElement.querySelector(
+      '[data-workbench-window-capture="true"]'
+    ) ?? windowElement.querySelector(".workbench-window") ?? windowElement
+  };
+}
+function isUsableCaptureRect(rect) {
+  return Number.isFinite(rect.left) && Number.isFinite(rect.top) && Number.isFinite(rect.width) && Number.isFinite(rect.height) && rect.width > 0 && rect.height > 0 && rect.left >= 0 && rect.top >= 0 && rect.left + rect.width <= window.innerWidth && rect.top + rect.height <= window.innerHeight;
+}
+function captureRectDetails(rect) {
+  return {
+    height: rect.height,
+    width: rect.width,
+    x: rect.left,
+    y: rect.top
+  };
+}
+async function resolveCaptureOutcome(capturePromise, timeoutMs) {
+  let timeout;
+  const settledCapture = capturePromise.then(
+    (previewImages) => ({ previewImages, status: "resolved" }),
+    (error) => ({ error, status: "failed" })
+  );
+  const timeoutOutcome = new Promise((resolve) => {
+    timeout = setTimeout(() => resolve({ status: "timed_out" }), timeoutMs);
+  });
+  return Promise.race([settledCapture, timeoutOutcome]).finally(() => {
+    if (timeout) {
+      clearTimeout(timeout);
+    }
+  });
+}
+function emitDiagnostic(diagnostics, diagnostic) {
+  try {
+    diagnostics?.(diagnostic);
+  } catch {
+  }
+}
+function serializeError(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
 // src/react/WorkbenchDockComponentPreviewFrame.tsx
 import { jsx as jsx17 } from "react/jsx-runtime";
 function WorkbenchDockComponentPreviewFrame({
@@ -15849,6 +16168,7 @@ export {
   createWorkbenchHostProjectedNodeId,
   createWorkbenchNode,
   createWorkbenchNodeFromSnapshot,
+  createWorkbenchNodePreviewCaptureAdapter,
   createWorkbenchSnapshotFromState,
   createWorkbenchSnapshotLayoutBasis,
   createWorkbenchStateFromSnapshot,