@opengeni/react 0.11.0 → 0.13.0

package/src/hooks/use-sandbox-files.ts

@@ -6,6 +6,7 @@ import type {
   GitChangedPayload,
   GitFileStatusCode,
   SessionEvent,
+  WorkspaceCaptureManifest,
 } from "@opengeni/sdk";
 import { useCallback, useEffect, useRef, useState } from "react";
 import { useOpenGeni, type ClientOverride } from "../provider";
@@ -22,6 +23,10 @@ export type FileTreeNode = {
   children?: FileTreeNode[] | undefined;
   size?: number | null | undefined;
   status?: FileTreeStatus | undefined;
+  /** A residue dir the capture COLLAPSED (node_modules, .git, dist, …): its
+   *  contents were never indexed. Cold, expanding it can't list children — the
+   *  UI shows an inline "contents on machine" row until the box is warm. */
+  truncated?: boolean | undefined;
 };
 
 export type UseSandboxFilesOptions = ClientOverride & {
@@ -38,6 +43,12 @@ export type UseSandboxFilesOptions = ClientOverride & {
    *  (with no `fs.changed` event) never re-lists. Passing liveness re-lists when
    *  the box first becomes warm, so the tree populates as soon as the box is up. */
   liveness?: string | undefined;
+  /** The latest turn-end workspace capture (from `useWorkspaceCapture`). When the
+   *  box is NOT warm, the tree paints INSTANTLY from this capture's tree index (the
+   *  <200ms cold first paint) instead of blocking on a Channel-A list. A warm box
+   *  always wins (live path unchanged). On the cold→warm transition the live list
+   *  is merged in place — no remount, no flash (dossier §10.4 / §12-A1/D1). */
+  capture?: WorkspaceCaptureManifest | null | undefined;
   /** Called when an OPTIMISTIC mutation is reverted because its background
    *  Channel-A op failed (e.g. a 409 rename collision). The host wires this to a
    *  toast — the tree silently rolls the node back, the user sees why. */
@@ -68,6 +79,11 @@ export type UseSandboxFilesResult = {
   moveEntry: (path: string, newPath: string, opts?: { overwrite?: boolean }) => Promise<void>;
   /** Re-list the whole tree from the root. */
   refresh: () => Promise<void>;
+  /** Which source the tree is currently served from: the live box, the turn-end
+   *  capture (cold/offline), or neither yet. M5's source badge reads this. */
+  source: "live" | "capture" | null;
+  /** When the served capture was taken (ISO), when `source === "capture"`. */
+  capturedAt: string | null;
   loading: boolean;
   error: Error | null;
 };
@@ -85,10 +101,6 @@ function leafOf(path: string): string {
 }
 
 /** Join a parent dir with a leaf name (handles the root "" parent). */
-function joinPath(parent: string, name: string): string {
-  return parent ? `${parent}/${name}` : name;
-}
-
 /** Stable sibling ordering: dirs before files, then case-insensitive by name —
  *  matches a typical depth-1 list so an optimistic insert lands where a real
  *  re-list would put it (no jump when the server reconciles). */
@@ -118,6 +130,9 @@ function fsNodeToTree(node: FsTreeNode): FileTreeNode {
     kind,
     size: node.sizeBytes,
     ...(kind === "dir" ? { children: mappedChildren } : {}),
+    // A collapsed residue dir from the capture index — carried through so the
+    // tree can show an inline "contents on machine" row cold instead of nothing.
+    ...(kind === "dir" && node.truncated ? { truncated: true } : {}),
   };
 }
 
@@ -132,7 +147,11 @@ const GIT_STATUS_TO_TREE: Partial<Record<GitFileStatusCode, FileTreeStatus>> = {
 };
 
 /** Replace the children of `targetPath` within the tree (immutably). */
-function replaceChildren(nodes: FileTreeNode[], targetPath: string, children: FileTreeNode[]): FileTreeNode[] {
+function replaceChildren(
+  nodes: FileTreeNode[],
+  targetPath: string,
+  children: FileTreeNode[],
+): FileTreeNode[] {
   return nodes.map((node) => {
     if (node.path === targetPath) {
       return { ...node, children };
@@ -223,14 +242,34 @@ function removeNode(nodes: FileTreeNode[], path: string): FileTreeNode[] {
  *  and entries the server no longer returns are dropped. This is the in-place
  *  merge a root ("") reconcile needs — a blind replace would collapse every
  *  expanded top-level dir back to the unexpanded marker (the reported bug). */
+/** Shallow node equality for identity preservation across a reconcile — same
+ *  path/kind/name/size/status (children handled separately by the caller). */
+function sameNodeShallow(a: FileTreeNode, b: FileTreeNode): boolean {
+  return (
+    a.path === b.path &&
+    a.kind === b.kind &&
+    a.name === b.name &&
+    (a.size ?? null) === (b.size ?? null) &&
+    (a.status ?? undefined) === (b.status ?? undefined) &&
+    (a.truncated ?? false) === (b.truncated ?? false)
+  );
+}
+
 function mergeChildren(current: FileTreeNode[], listed: FileTreeNode[]): FileTreeNode[] {
   const byPath = new Map(current.map((n) => [n.path, n] as const));
   const merged = listed.map((next) => {
     const existing = byPath.get(next.path);
+    if (!existing) return next; // brand-new entry
     // Keep an already-expanded dir's loaded children; otherwise take the listing's
     // marker (undefined = unexpanded). Carry forward size/status from the listing.
-    if (existing && existing.kind === "dir" && next.kind === "dir" && existing.children !== undefined) {
-      return { ...next, children: existing.children };
+    if (existing.kind === "dir" && next.kind === "dir" && existing.children !== undefined) {
+      const candidate: FileTreeNode = { ...next, children: existing.children };
+      // Preserve identity when nothing observable changed — no remount (§12-D1).
+      return sameNodeShallow(existing, candidate) ? existing : candidate;
+    }
+    // A file or an unexpanded dir: preserve identity when the node is unchanged.
+    if (existing.children === next.children && sameNodeShallow(existing, next)) {
+      return existing;
     }
     return next;
   });
@@ -276,7 +315,17 @@ export function useSandboxFiles(
   const [loading, setLoading] = useState(false);
   const [expandingPaths, setExpandingPaths] = useState<Set<string>>(new Set());
   const [error, setError] = useState<Error | null>(null);
+  // Which source the tree currently reflects — "capture" (cold paint) or "live".
+  const [source, setSource] = useState<"live" | "capture" | null>(null);
   const statusRef = useRef<Map<string, FileTreeStatus>>(new Map());
+  // Async reads, event cursors, and debounced work are scoped to the hook's
+  // workspace/session/root identity. These refs are reset/fenced at that boundary.
+  const refreshGenerationRef = useRef(0);
+  const identityGenerationRef = useRef(0);
+  const lastSeqRef = useRef(0);
+  const pendingParentsRef = useRef<Set<string>>(new Set());
+  const pendingGitRef = useRef(false);
+  const debounceRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
   // ── Self-emitted fs.changed de-dupe ───────────────────────────────────────
   // Every one of OUR mutations emits an `fs.changed` event back on the live log
@@ -292,22 +341,38 @@ export function useSandboxFiles(
   // Keep the ref mirror current for the optimistic snapshot path.
   treeRef.current = tree;
 
+  // Overlay the git-status tint onto the tree. IDENTITY-PRESERVING: a node whose
+  // tint and children are unchanged is returned by reference (not rebuilt), so a
+  // re-tint or a cold→warm reconcile does NOT remount unchanged rows — the
+  // no-flicker constraint (dossier §3 #6 / §12-D1). An empty overlay is still
+  // meaningful: it strips stale tints after the repository becomes clean.
   const applyStatus = useCallback((nodes: FileTreeNode[]): FileTreeNode[] => {
     const overlay = statusRef.current;
-    if (overlay.size === 0) return nodes;
-    const walk = (list: FileTreeNode[]): FileTreeNode[] =>
-      list.map((node) => {
-        const status = overlay.get(node.path);
-        const next = node.children ? { ...node, children: walk(node.children) } : { ...node };
-        if (status && node.kind === "file") next.status = status;
+    const walk = (list: FileTreeNode[]): FileTreeNode[] => {
+      let changed = false;
+      const out = list.map((node) => {
+        const nextChildren = node.children ? walk(node.children) : node.children;
+        const wantStatus = node.kind === "file" ? overlay.get(node.path) : undefined;
+        const childrenChanged = nextChildren !== node.children;
+        const statusChanged = (node.status ?? undefined) !== (wantStatus ?? undefined);
+        if (!childrenChanged && !statusChanged) return node;
+        changed = true;
+        const next: FileTreeNode = {
+          ...node,
+          ...(node.children ? { children: nextChildren } : {}),
+        };
+        if (wantStatus) next.status = wantStatus;
         else delete next.status;
         return next;
       });
+      return changed ? out : list;
+    };
     return walk(nodes);
   }, []);
 
   const refresh = useCallback(async () => {
     if (!sessionId) return;
+    const generation = (refreshGenerationRef.current += 1);
     setLoading(true);
     setError(null);
     try {
@@ -315,6 +380,7 @@ export function useSandboxFiles(
       // returns isRepo:false), then the tree, so the first paint is tinted.
       try {
         const status = await client.gitStatus(workspaceId, sessionId, { path: rootPath });
+        if (refreshGenerationRef.current !== generation) return;
         const overlay = new Map<string, FileTreeStatus>();
         for (const file of status.files) {
           const code = file.worktree ?? file.index;
@@ -323,24 +389,57 @@ export function useSandboxFiles(
         }
         statusRef.current = overlay;
       } catch {
+        if (refreshGenerationRef.current !== generation) return;
         statusRef.current = new Map();
       }
       const listed = await client.fsList(workspaceId, sessionId, { path: rootPath, depth: 1 });
+      if (refreshGenerationRef.current !== generation) return;
       const children = (listed.root.children ?? []).map(fsNodeToTree);
       // Merge rather than replace so an explicit refresh / cold→warm re-list folds
-      // in new entries WITHOUT collapsing the dirs the user already expanded. On a
-      // first (empty) load this is a plain set.
-      setTree((prev) => applyStatus(prev.length === 0 ? children : mergeRootChildren(prev, children)));
+      // in new entries WITHOUT collapsing the dirs the user already expanded (and,
+      // via the identity-preserving merge, WITHOUT remounting unchanged rows — the
+      // no-flicker cold→warm reconcile). On a first (empty) load this is a plain set.
+      setTree((prev) =>
+        applyStatus(prev.length === 0 ? children : mergeRootChildren(prev, children)),
+      );
+      // Live data is now serving — flip the source off the capture snapshot.
+      setSource("live");
     } catch (cause) {
+      if (refreshGenerationRef.current !== generation) return;
       setError(cause instanceof Error ? cause : new Error(String(cause)));
     } finally {
-      setLoading(false);
+      if (refreshGenerationRef.current === generation) setLoading(false);
     }
   }, [client, workspaceId, sessionId, rootPath, applyStatus]);
 
+  // Seed (or re-seed) the tree from a turn-end capture — the COLD/offline paint,
+  // zero Channel-A calls. The tree index is workspace-relative (`treeIndex`); the
+  // tint overlay comes from the capture's changed `files`. Uses the SAME merge as
+  // the live reconcile so a re-seed (a newer capture arriving cold) patches deltas
+  // in place instead of remounting the tree (§12-D1). Never runs while warm.
+  const seedFromCapture = useCallback(
+    (manifest: WorkspaceCaptureManifest) => {
+      const overlay = new Map<string, FileTreeStatus>();
+      for (const file of manifest.files) {
+        if (file.deleted) continue;
+        const mapped = GIT_STATUS_TO_TREE[file.status];
+        if (mapped) overlay.set(file.path, mapped);
+      }
+      statusRef.current = overlay;
+      const children = (manifest.treeIndex.children ?? []).map(fsNodeToTree);
+      setTree((prev) =>
+        applyStatus(prev.length === 0 ? children : mergeRootChildren(prev, children)),
+      );
+      setSource("capture");
+      setError(null);
+    },
+    [applyStatus],
+  );
+
   const expand = useCallback(
     async (path: string) => {
       if (!sessionId) return;
+      const identityGeneration = identityGenerationRef.current;
       // Mark this node as expanding so the FileBrowser can render a spinner while
       // the (often 2-3s) Channel-A fs/list is in flight — the tree never looks
       // frozen on a click.
@@ -351,17 +450,21 @@ export function useSandboxFiles(
       });
       try {
         const listed = await client.fsList(workspaceId, sessionId, { path, depth: 1 });
+        if (identityGenerationRef.current !== identityGeneration) return;
         const children = (listed.root.children ?? []).map(fsNodeToTree);
         setTree((prev) => applyStatus(replaceChildren(prev, path, children)));
       } catch (cause) {
+        if (identityGenerationRef.current !== identityGeneration) return;
         setError(cause instanceof Error ? cause : new Error(String(cause)));
       } finally {
-        setExpandingPaths((prev) => {
-          if (!prev.has(path)) return prev;
-          const next = new Set(prev);
-          next.delete(path);
-          return next;
-        });
+        if (identityGenerationRef.current === identityGeneration) {
+          setExpandingPaths((prev) => {
+            if (!prev.has(path)) return prev;
+            const next = new Set(prev);
+            next.delete(path);
+            return next;
+          });
+        }
       }
     },
     [client, workspaceId, sessionId, applyStatus],
@@ -385,17 +488,21 @@ export function useSandboxFiles(
   const reconcilePath = useCallback(
     async (path: string) => {
       if (!sessionId) return;
+      const identityGeneration = identityGenerationRef.current;
       // Skip parents that aren't currently loaded/expanded in the tree (nothing
       // visible to update; they re-list fresh on the next expand).
       if (!parentIsLoaded(treeRef.current, path)) return;
       try {
         const listed = await client.fsList(workspaceId, sessionId, { path, depth: 1 });
+        if (identityGenerationRef.current !== identityGeneration) return;
         const children = (listed.root.children ?? []).map(fsNodeToTree);
         if (path === "") setTree((prev) => applyStatus(mergeRootChildren(prev, children)));
         else
           setTree((prev) => {
             const existing = findNodeByPath(prev, path);
-            const merged = existing?.children ? mergeChildren(existing.children, children) : children;
+            const merged = existing?.children
+              ? mergeChildren(existing.children, children)
+              : children;
             return applyStatus(replaceChildren(prev, path, merged));
           });
       } catch {
@@ -414,17 +521,19 @@ export function useSandboxFiles(
   // refresh. The returned promise resolves/rejects with the op so callers (the
   // editor save, inline rename) can still await it.
   const runOptimistic = useCallback(
-    async <T,>(
+    async <T>(
       opName: string,
       apply: (nodes: FileTreeNode[]) => FileTreeNode[],
       op: () => Promise<T>,
       reconcileParents: string[],
     ): Promise<T> => {
+      const identityGeneration = identityGenerationRef.current;
       // Snapshot the pre-op tree from the ref (StrictMode-safe — see treeRef).
       const snapshot = treeRef.current;
       setTree(applyStatus(apply(snapshot)));
       try {
         const res = await op();
+        if (identityGenerationRef.current !== identityGeneration) return res;
         // Remember the revision WE caused so the matching fs.changed echo is
         // ignored by the event effect (no self-triggered refresh).
         if (res && typeof res === "object" && "revision" in res) {
@@ -433,10 +542,14 @@ export function useSandboxFiles(
         }
         // Reconcile loaded parents to fold the server's real metadata. Sequential
         // and best-effort — purely cosmetic over the already-correct optimistic UI.
-        for (const parent of reconcileParents) await reconcilePath(parent);
+        for (const parent of reconcileParents) {
+          if (identityGenerationRef.current !== identityGeneration) return res;
+          await reconcilePath(parent);
+        }
         return res;
       } catch (cause) {
         const err = cause instanceof Error ? cause : new Error(String(cause));
+        if (identityGenerationRef.current !== identityGeneration) throw err;
         // Revert the optimistic edit to the exact pre-op tree.
         setTree(applyStatus(snapshot));
         setError(err);
@@ -537,22 +650,71 @@ export function useSandboxFiles(
     [client, workspaceId, sessionId, runOptimistic],
   );
 
-  // Initial load + reset on identity change.
+  // Initial paint + reset on identity change. Source selection (dossier §10.4):
+  //   • warm/draining box → the LIVE list (unchanged behavior).
+  //   • cold/offline box WITH a capture → paint instantly from the capture index
+  //     (no Channel-A; the box warms in the background and the warm effect below
+  //     reconciles live in place).
+  //   • cold box with NO capture → best-effort live list (status quo — never worse).
+  const capture = options.capture ?? null;
+  const isLive = options.liveness === "warm" || options.liveness === "draining";
+  // Key the seed on the capture's REVISION (a primitive), not the manifest object
+  // — a consumer passing a fresh object each render (or a new revision) must not
+  // spin the effect. The latest manifest is read from a ref at run time.
+  const captureRef = useRef<WorkspaceCaptureManifest | null>(capture);
+  captureRef.current = capture;
+  const captureRevision = capture?.revision ?? null;
+  const identityKey = `${workspaceId}\u0000${sessionId ?? ""}\u0000${rootPath}`;
+  const previousIdentityRef = useRef(identityKey);
   useEffect(() => {
-    if (!enabled) {
+    // Any source-selection change supersedes an older root refresh. A true data
+    // identity change additionally fences all other async tree work and resets
+    // event/debounce state before the event-folding effect runs.
+    refreshGenerationRef.current += 1;
+    const identityChanged = previousIdentityRef.current !== identityKey;
+    previousIdentityRef.current = identityKey;
+    if (identityChanged || !enabled) {
+      identityGenerationRef.current += 1;
+      lastSeqRef.current = 0;
+      pendingParentsRef.current = new Set();
+      pendingGitRef.current = false;
+      if (debounceRef.current) {
+        clearTimeout(debounceRef.current);
+        debounceRef.current = null;
+      }
+      ownRevisionsRef.current = new Set();
+      statusRef.current = new Map();
+      treeRef.current = [];
       setTree([]);
+      setExpandingPaths(new Set());
+      setSource(null);
+      setLoading(false);
+      setError(null);
+    }
+    if (!enabled) {
       return;
     }
-    void refresh();
-  }, [enabled, refresh]);
+    if (isLive) {
+      void refresh();
+    } else if (captureRevision !== null && captureRef.current) {
+      seedFromCapture(captureRef.current);
+    } else {
+      void refresh();
+    }
+    return () => {
+      refreshGenerationRef.current += 1;
+    };
+  }, [enabled, isLive, captureRevision, identityKey, refresh, seedFromCapture]);
 
   // Re-pull JUST the git-status overlay and re-tint the existing tree in place —
   // no fs re-list, no collapse. This is all a `git.changed` (commit/stage/checkout)
   // needs: the tree SHAPE is unchanged, only the tints move.
   const refreshGitOverlay = useCallback(async () => {
     if (!sessionId) return;
+    const identityGeneration = identityGenerationRef.current;
     try {
       const status = await client.gitStatus(workspaceId, sessionId, { path: rootPath });
+      if (identityGenerationRef.current !== identityGeneration) return;
       const overlay = new Map<string, FileTreeStatus>();
       for (const file of status.files) {
         const code = file.worktree ?? file.index;
@@ -577,10 +739,6 @@ export function useSandboxFiles(
   //     preserved). Bursts are debounced into a single reconcile pass.
   //   • A git.changed just re-tints (refreshes the status overlay) — no fs re-list.
   const events = options.events;
-  const lastSeqRef = useRef(0);
-  const pendingParentsRef = useRef<Set<string>>(new Set());
-  const pendingGitRef = useRef(false);
-  const debounceRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
   useEffect(() => {
     if (!enabled || !events) return;
@@ -593,7 +751,8 @@ export function useSandboxFiles(
         if (!payload || typeof payload !== "object") continue;
         // Suppress our own writes: the optimistic tree already shows them.
         if (payload.source === "write") continue;
-        if (typeof payload.revision === "number" && ownRevisionsRef.current.has(payload.revision)) continue;
+        if (typeof payload.revision === "number" && ownRevisionsRef.current.has(payload.revision))
+          continue;
         for (const change of payload.changes ?? []) {
           pendingParentsRef.current.add(parentOf(change.path));
           if (change.oldPath) pendingParentsRef.current.add(parentOf(change.oldPath));
@@ -604,18 +763,26 @@ export function useSandboxFiles(
         // A git.changed our own write triggered (commit/stage from the agent is
         // external; a checkout we caused isn't — but we don't cause git ops here,
         // so any git.changed is external) → re-tint.
-        if (payload && typeof payload === "object" && typeof payload.revision === "number"
-          && ownRevisionsRef.current.has(payload.revision)) continue;
+        if (
+          payload &&
+          typeof payload === "object" &&
+          typeof payload.revision === "number" &&
+          ownRevisionsRef.current.has(payload.revision)
+        )
+          continue;
         pendingGitRef.current = true;
       }
     }
     // Advance the high-water mark past everything we've folded.
-    for (const event of events) if (event.sequence > lastSeqRef.current) lastSeqRef.current = event.sequence;
+    for (const event of events)
+      if (event.sequence > lastSeqRef.current) lastSeqRef.current = event.sequence;
     if (!sawNew) return;
 
     if (debounceRef.current) clearTimeout(debounceRef.current);
+    const identityGeneration = identityGenerationRef.current;
     debounceRef.current = setTimeout(() => {
       debounceRef.current = null;
+      if (identityGenerationRef.current !== identityGeneration) return;
       const parents = pendingParentsRef.current;
       pendingParentsRef.current = new Set();
       const wantGit = pendingGitRef.current;
@@ -624,13 +791,18 @@ export function useSandboxFiles(
       // so the freshly-listed nodes get the correct overlay.
       void (async () => {
         if (wantGit) await refreshGitOverlay();
-        for (const parent of parents) await reconcilePath(parent);
+        if (identityGenerationRef.current !== identityGeneration) return;
+        for (const parent of parents) {
+          if (identityGenerationRef.current !== identityGeneration) return;
+          await reconcilePath(parent);
+        }
       })();
     }, 150);
   }, [enabled, events, reconcilePath, refreshGitOverlay]);
 
   useEffect(
     () => () => {
+      identityGenerationRef.current += 1;
       if (debounceRef.current) clearTimeout(debounceRef.current);
     },
     [],
@@ -664,6 +836,8 @@ export function useSandboxFiles(
     deleteEntry,
     moveEntry,
     refresh,
+    source,
+    capturedAt: source === "capture" ? (capture?.capturedAt ?? null) : null,
     loading,
     error,
   };