@opengeni/react 0.15.0 → 0.20.0

package/src/hooks/use-turn-queue.ts

@@ -6,8 +6,8 @@ import type {
   SessionQueueSnapshot,
   SessionTurn,
 } from "@opengeni/sdk";
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { useOpenGeni, type ClientOverride } from "../provider";
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { useEmbeddedSession, type EmbeddedSessionClientOverride } from "../session-context";
 import {
   useDebouncedCallback,
   useSessionEventTrigger,
@@ -24,9 +24,21 @@ export function isTurnQueueEvent(event: Pick<SessionEvent, "type">): boolean {
   );
 }
 
+function queueSnapshotCovers(
+  candidate: SessionQueueSnapshot | null,
+  observed: SessionQueueSnapshot,
+): boolean {
+  return Boolean(
+    candidate &&
+    candidate.version >= observed.version &&
+    candidate.effectiveControl.controlVersion >= observed.effectiveControl.controlVersion,
+  );
+}
+
 export type QueueMutationKind = "move" | "edit" | "steer" | "delete";
+const EMPTY_PENDING_BY_TURN: Readonly<Record<string, QueueMutationKind>> = {};
 
-export type UseTurnQueueOptions = ClientOverride &
+export type UseTurnQueueOptions = EmbeddedSessionClientOverride &
   SessionEventFeedOptions & {
     pollIntervalMs?: number | undefined;
   };
@@ -36,6 +48,8 @@ export type UseTurnQueueResult = {
   /** Human/API prompts exactly in server execution order. Never client-sorted. */
   queue: SessionTurn[];
   effectiveControl: EffectiveSessionControl | null;
+  /** The latest interrupted attempt has not yet durably proved physical quiescence. */
+  stoppingPreviousAttempt: boolean;
   loading: boolean;
   error: Error | null;
   refresh: () => Promise<void>;
@@ -65,62 +79,92 @@ export function useTurnQueue(
   options: UseTurnQueueOptions = {},
 ): UseTurnQueueResult {
   const { client, workspaceId, workspaceControlEvent, registerSessionReconciler } =
-    useOpenGeni(options);
+    useEmbeddedSession(options);
   const enabled = (options.enabled ?? true) && Boolean(sessionId);
+  const targetKey = `${workspaceId}\u0000${sessionId ?? ""}`;
   const [snapshot, setSnapshot] = useState<SessionQueueSnapshot | null>(null);
+  const [stateTargetKey, setStateTargetKey] = useState(targetKey);
   const [loading, setLoading] = useState(enabled);
   const [error, setError] = useState<Error | null>(null);
   const [mutationError, setMutationError] = useState<Error | null>(null);
   const [pendingByTurn, setPendingByTurn] = useState<Record<string, QueueMutationKind>>({});
   const pendingRef = useRef<Record<string, QueueMutationKind>>({});
   const readGeneration = useRef(0);
-  const targetKeyRef = useRef<string | null>(null);
+  const targetKeyRef = useRef(targetKey);
   const snapshotRef = useRef<SessionQueueSnapshot | null>(null);
 
-  const acceptSnapshot = useCallback((next: SessionQueueSnapshot | null): boolean => {
-    const current = snapshotRef.current;
-    if (
-      next &&
-      current &&
-      (next.version < current.version ||
-        next.effectiveControl.controlVersion < current.effectiveControl.controlVersion)
-    ) {
-      return false;
-    }
-    snapshotRef.current = next;
-    setSnapshot(next);
-    return true;
-  }, []);
+  // Revoke the old target only when the new one commits. A concurrent render
+  // may suspend while the previous target remains visible and interactive.
+  useLayoutEffect(() => {
+    if (targetKeyRef.current === targetKey) return;
+    targetKeyRef.current = targetKey;
+    readGeneration.current += 1;
+    snapshotRef.current = null;
+    pendingRef.current = {};
+    setStateTargetKey(targetKey);
+    setSnapshot(null);
+    setLoading(enabled);
+    setError(null);
+    setMutationError(null);
+    setPendingByTurn({});
+  }, [enabled, targetKey]);
 
-  const load = useCallback(async (): Promise<void> => {
-    if (!sessionId) return;
-    const ticket = ++readGeneration.current;
-    try {
-      const fetched = await client.getQueue(workspaceId, sessionId);
-      if (ticket === readGeneration.current) {
-        acceptSnapshot(fetched);
-        setError(null);
-        setLoading(false);
+  const acceptSnapshot = useCallback(
+    (ownedTargetKey: string, next: SessionQueueSnapshot | null): boolean => {
+      if (targetKeyRef.current !== ownedTargetKey) return false;
+      const current = snapshotRef.current;
+      if (
+        next &&
+        current &&
+        (next.version < current.version ||
+          next.effectiveControl.controlVersion < current.effectiveControl.controlVersion)
+      ) {
+        return false;
       }
-    } catch (cause) {
-      if (ticket === readGeneration.current) {
-        setError(asError(cause));
-        setLoading(false);
+      snapshotRef.current = next;
+      setStateTargetKey(ownedTargetKey);
+      setSnapshot(next);
+      return true;
+    },
+    [],
+  );
+
+  const load = useCallback(
+    async (rejectOnFailure = false): Promise<void> => {
+      if (!sessionId) return;
+      const ownedTargetKey = `${workspaceId}\u0000${sessionId}`;
+      const ticket = ++readGeneration.current;
+      try {
+        const fetched = await client.getQueue(workspaceId, sessionId);
+        if (targetKeyRef.current !== ownedTargetKey) return;
+        const ownsLatestRead = ticket === readGeneration.current;
+        if (rejectOnFailure) {
+          const committed = acceptSnapshot(ownedTargetKey, fetched);
+          if (!committed && !queueSnapshotCovers(snapshotRef.current, fetched)) {
+            throw new TypeError("Queue reconciliation did not commit authoritative state");
+          }
+          setError(null);
+          if (ownsLatestRead) setLoading(false);
+        } else if (ownsLatestRead) {
+          acceptSnapshot(ownedTargetKey, fetched);
+          setError(null);
+          setLoading(false);
+        }
+      } catch (cause) {
+        if (
+          targetKeyRef.current === ownedTargetKey &&
+          (ticket === readGeneration.current || rejectOnFailure)
+        ) {
+          setError(asError(cause));
+          if (ticket === readGeneration.current) setLoading(false);
+        }
+        if (rejectOnFailure) throw cause;
       }
-    }
-  }, [client, workspaceId, sessionId, acceptSnapshot]);
+    },
+    [client, workspaceId, sessionId, acceptSnapshot],
+  );
 
   useEffect(() => {
-    const targetKey = `${workspaceId}\u0000${sessionId ?? ""}`;
-    if (targetKeyRef.current !== targetKey) {
-      targetKeyRef.current = targetKey;
-      readGeneration.current += 1;
-      acceptSnapshot(null);
-      setError(null);
-      setMutationError(null);
-      setPendingByTurn({});
-      pendingRef.current = {};
-    }
     if (!enabled) {
       setLoading(false);
       return;
@@ -138,7 +182,7 @@ export function useTurnQueue(
       clearInterval(timer);
       readGeneration.current += 1;
     };
-  }, [load, enabled, workspaceId, sessionId, options.pollIntervalMs, acceptSnapshot]);
+  }, [load, enabled, options.pollIntervalMs]);
 
   useEffect(() => {
     if (enabled && workspaceControlEvent) void load();
@@ -149,10 +193,18 @@ export function useTurnQueue(
   }, [enabled, load, registerSessionReconciler, sessionId]);
 
   const scheduleRefresh = useDebouncedCallback(() => void load());
-  useSessionEventTrigger(client, workspaceId, sessionId, isTurnQueueEvent, scheduleRefresh, {
-    enabled,
-    ...(options.events !== undefined ? { events: options.events } : {}),
-  });
+  useSessionEventTrigger(
+    client,
+    workspaceId,
+    sessionId,
+    isTurnQueueEvent,
+    scheduleRefresh,
+    {
+      enabled,
+      ...(options.events !== undefined ? { events: options.events } : {}),
+    },
+    async () => await load(true),
+  );
 
   const mutate = useCallback(
     async (
@@ -163,23 +215,30 @@ export function useTurnQueue(
         turn: SessionTurn,
       ) => Promise<SessionQueueMutationResponse>,
     ): Promise<SessionQueueMutationResponse | null> => {
-      if (!sessionId || pendingRef.current[turnId]) return null;
+      const ownedTargetKey = targetKey;
+      if (!sessionId || targetKeyRef.current !== ownedTargetKey || pendingRef.current[turnId]) {
+        return null;
+      }
       const current = snapshotRef.current;
       const turn = current?.items.find((candidate) => candidate.id === turnId);
       if (!current || !turn) return null;
       pendingRef.current = { ...pendingRef.current, [turnId]: kind };
+      setStateTargetKey(ownedTargetKey);
       setPendingByTurn(pendingRef.current);
       setMutationError(null);
       try {
         const result = await command(current, turn);
-        acceptSnapshot(result.snapshot);
+        if (targetKeyRef.current !== ownedTargetKey) return null;
+        acceptSnapshot(ownedTargetKey, result.snapshot);
         return result;
       } catch (cause) {
-        setMutationError(asError(cause));
-        await load();
+        if (targetKeyRef.current === ownedTargetKey) {
+          setMutationError(asError(cause));
+          await load();
+        }
         return null;
       } finally {
-        if (turnId in pendingRef.current) {
+        if (targetKeyRef.current === ownedTargetKey && turnId in pendingRef.current) {
           const next = { ...pendingRef.current };
           delete next[turnId];
           pendingRef.current = next;
@@ -187,7 +246,7 @@ export function useTurnQueue(
         }
       }
     },
-    [acceptSnapshot, load, sessionId],
+    [acceptSnapshot, load, sessionId, targetKey],
   );
 
   const moveTurn = useCallback(
@@ -250,28 +309,37 @@ export function useTurnQueue(
     [client, mutate, sessionId, workspaceId],
   );
 
+  const identityMatches = stateTargetKey === targetKey;
+  const visibleSnapshot = identityMatches ? snapshot : null;
+  const visiblePendingByTurn = identityMatches ? pendingByTurn : EMPTY_PENDING_BY_TURN;
+  const mutating = useMemo(
+    () => Object.keys(visiblePendingByTurn).length > 0,
+    [visiblePendingByTurn],
+  );
   const mutationFor = useCallback(
-    (turnId: string): QueueMutationKind | null => pendingByTurn[turnId] ?? null,
-    [pendingByTurn],
+    (turnId: string): QueueMutationKind | null => visiblePendingByTurn[turnId] ?? null,
+    [visiblePendingByTurn],
   );
-  const mutating = useMemo(() => Object.keys(pendingByTurn).length > 0, [pendingByTurn]);
 
   return {
-    snapshot,
-    queue: snapshot?.items ?? [],
-    effectiveControl: snapshot?.effectiveControl ?? null,
-    loading,
-    error,
+    snapshot: visibleSnapshot,
+    queue: visibleSnapshot?.items ?? [],
+    effectiveControl: visibleSnapshot?.effectiveControl ?? null,
+    stoppingPreviousAttempt: visibleSnapshot?.stoppingPreviousAttempt ?? false,
+    loading: identityMatches ? loading : enabled,
+    error: identityMatches ? error : null,
     refresh: load,
     moveTurn,
     editTurn,
     steerTurn,
     removeTurn,
-    pendingByTurn,
+    pendingByTurn: visiblePendingByTurn,
     mutationFor,
     mutating,
-    mutationError,
-    clearMutationError: useCallback(() => setMutationError(null), []),
+    mutationError: identityMatches ? mutationError : null,
+    clearMutationError: useCallback(() => {
+      if (targetKeyRef.current === targetKey) setMutationError(null);
+    }, [targetKey]),
   };
 }
 

package/src/hooks/use-windowed-sections.ts

@@ -6,12 +6,12 @@ import { useCallback, useEffect, useMemo, useRef, useState } from "react";
    The Changes tab stacks N file diffs in one scroll pane. Mounting N Shiki
    highlighters (Pierre's `PatchDiff`) at once is the exact wart this replaces,
    so we mount only the sections inside the visible window ± overscan and reserve
-   the rest as empty space (dossier §10.7, D2).
+   the rest as empty space (D2).
 
    Why NOT `virtua` here (unlike the file tree/rail): Pierre renders each diff in
    a shadow DOM with its own internal overflow/virtualization, so an outer
    measuring virtualizer can read a collapsed or fixed height and lay sections
-   out wrong (dossier risk #6). This hook windows by mounting/unmounting whole
+   out wrong (known layout risk). This hook windows by mounting/unmounting whole
    file sections off a scroll offset and a per-section height ESTIMATE (refined
    by measurement when a real browser provides it), which never depends on
    Pierre reporting its own height — and the math is pure + deterministic, so

package/src/hooks/use-workspace-capture.ts

@@ -14,6 +14,79 @@ const REVISION_CAPTURED = "workspace.revision.captured";
 const REVISION_DEGRADED = "workspace.revision.degraded";
 const MANIFEST_FETCH_TIMEOUT_MS = 15_000;
 
+type AvailableCaptureResponse = Extract<GetWorkspaceCaptureResponse, { available: true }>;
+
+const CAPTURE_STATS_NUMBER_FIELDS = [
+  "repoCount",
+  "fileCount",
+  "additions",
+  "deletions",
+  "totalBytes",
+  "tooLargeCount",
+  "binaryCount",
+  "treeEntryCount",
+  "durationMs",
+] as const;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Signed manifests bypass the authenticated JSON client's wire decoder. Treat
+ * the blob as untrusted until its outer schema and exact revision identity match
+ * the metadata response that minted the URL. The API performs the full contract
+ * parse; this client-side boundary prevents a corrupt/mis-keyed response from
+ * being presented as a different authoritative capture.
+ */
+function captureManifestForResponse(
+  value: unknown,
+  response: AvailableCaptureResponse,
+): WorkspaceCaptureManifest {
+  if (
+    !isRecord(value) ||
+    value.version !== 1 ||
+    !Number.isSafeInteger(value.revision) ||
+    typeof value.capturedAt !== "string" ||
+    !(value.turnId === null || typeof value.turnId === "string") ||
+    !Number.isSafeInteger(value.leaseEpoch) ||
+    !isRecord(value.treeIndex) ||
+    typeof value.treeTruncated !== "boolean" ||
+    !Array.isArray(value.repos) ||
+    !Array.isArray(value.files) ||
+    !isRecord(value.stats)
+  ) {
+    throw new Error("Workspace capture manifest failed validation.");
+  }
+
+  if (
+    value.revision !== response.revision ||
+    value.capturedAt !== response.capturedAt ||
+    value.turnId !== response.turnId ||
+    value.leaseEpoch !== response.leaseEpoch
+  ) {
+    throw new Error("Workspace capture manifest identity did not match its response.");
+  }
+
+  for (const field of CAPTURE_STATS_NUMBER_FIELDS) {
+    if (!Number.isSafeInteger(value.stats[field]) || value.stats[field] !== response.stats[field]) {
+      throw new Error("Workspace capture manifest statistics did not match its response.");
+    }
+  }
+  if (
+    typeof value.stats.treeTruncated !== "boolean" ||
+    value.stats.treeTruncated !== response.stats.treeTruncated ||
+    (value.stats.fingerprint ?? null) !== (response.stats.fingerprint ?? null) ||
+    value.repos.length !== response.stats.repoCount ||
+    value.files.length !== response.stats.fileCount ||
+    value.treeTruncated !== response.stats.treeTruncated
+  ) {
+    throw new Error("Workspace capture manifest statistics did not match its response.");
+  }
+
+  return value as WorkspaceCaptureManifest;
+}
+
 export type UseWorkspaceCaptureOptions = ClientOverride & {
   /** Live event log (usually `useSessionEvents().events`) — a
    *  `workspace.revision.captured` for a NEWER revision refreshes the manifest. */
@@ -54,7 +127,7 @@ export type UseWorkspaceCaptureResult = {
 /**
  * The cold-paint data source: fetch the latest turn-end workspace capture with a
  * SINGLE api round-trip on mount (no machine, no Channel-A — this is the <200ms
- * first paint, dossier §10.4/§12-A1). The manifest is served inline in the common
+ * first paint). The manifest is served inline in the common
  * case; a rare >2MB manifest comes back as a short-TTL signed URL we follow.
  *
  * Subscribes to the live event log: a `workspace.revision.captured` for a revision
@@ -89,64 +162,93 @@ export function useWorkspaceCapture(
   // A generation counter fences a slow in-flight fetch against a newer one (or an
   // identity change) so a stale response can never overwrite fresher state.
   const generationRef = useRef(0);
+  const requestAbortRef = useRef<AbortController | null>(null);
   // Event sequence numbers are scoped to a session. Keeping this cursor across an
   // identity switch would discard the new session's low-numbered announcements.
   const lastSeqRef = useRef(0);
 
   const refresh = useCallback(async () => {
     if (!sessionId) return;
+    requestAbortRef.current?.abort();
+    const requestAbort = new AbortController();
+    requestAbortRef.current = requestAbort;
     const generation = (generationRef.current += 1);
     setStateIdentity(identityKey);
     setLoading(true);
     setError(null);
     try {
-      const res: GetWorkspaceCaptureResponse = await client.getWorkspaceCapture(
-        workspaceId,
-        sessionId,
-      );
-      if (generationRef.current !== generation) return;
-      if (!res.available) {
-        setCapture(null);
-        setAvailable(false);
-        setFileCount(0);
-        setDegradedReason(res.degradedReason ?? null);
-        return;
-      }
-      setDegradedReason(null);
-      // Resolve the changed-file count immediately from the response's stats — the
-      // default-tab signal must not wait on a >2MB manifest-URL hop.
-      setFileCount(res.stats.fileCount);
-      // Exactly one of manifest / manifestUrl is non-null (M2 contract). The inline
-      // manifest is the <200ms common case; a >2MB manifest is a signed URL hop.
-      let manifest = res.manifest;
-      if (!manifest && res.manifestUrl) {
-        const response = await fetch(res.manifestUrl.url, {
-          signal: AbortSignal.timeout(MANIFEST_FETCH_TIMEOUT_MS),
-        });
+      // A signed URL can expire between mint and GET. Re-enter the authenticated
+      // endpoint once to mint a fresh URL; never replay or log the old credential.
+      for (let attempt = 0; attempt < 2; attempt += 1) {
+        const res: GetWorkspaceCaptureResponse = await client.getWorkspaceCapture(
+          workspaceId,
+          sessionId,
+          { signal: requestAbort.signal },
+        );
         if (generationRef.current !== generation) return;
-        if (!response.ok)
-          throw new Error(`workspace capture manifest fetch failed: ${response.status}`);
-        manifest = (await response.json()) as WorkspaceCaptureManifest;
-        if (generationRef.current !== generation) return;
-      }
-      if (!manifest) {
-        // available:true but neither manifest nor a working URL — degrade, never crash.
-        setCapture(null);
-        setAvailable(false);
+        if (!res.available) {
+          setCapture(null);
+          setAvailable(false);
+          setFileCount(0);
+          setDegradedReason(res.degradedReason ?? null);
+          return;
+        }
+        setDegradedReason(null);
+        // Resolve the changed-file count immediately from the response's stats — the
+        // default-tab signal must not wait on a >2MB manifest-URL hop.
+        setFileCount(res.stats.fileCount);
+        // Exactly one of manifest / manifestUrl is non-null (M2 contract). The inline
+        // manifest is the <200ms common case; a >2MB manifest is a signed URL hop.
+        let manifestValue: unknown = res.manifest;
+        if (!manifestValue && res.manifestUrl) {
+          const response = await fetch(res.manifestUrl.url, {
+            signal: AbortSignal.any([
+              requestAbort.signal,
+              AbortSignal.timeout(MANIFEST_FETCH_TIMEOUT_MS),
+            ]),
+            credentials: "omit",
+            cache: "no-store",
+            referrerPolicy: "no-referrer",
+          }).catch(() => null);
+          if (generationRef.current !== generation) return;
+          if (!response?.ok) {
+            if (
+              attempt === 0 &&
+              (response === null || response.status === 401 || response.status === 403)
+            ) {
+              continue;
+            }
+            throw new Error(
+              `Workspace capture manifest download failed${response ? ` (${response.status})` : ""}.`,
+            );
+          }
+          try {
+            manifestValue = await response.json();
+          } catch {
+            throw new Error("Workspace capture manifest was not valid JSON.");
+          }
+          if (generationRef.current !== generation) return;
+        }
+        if (!manifestValue) {
+          throw new Error("Workspace capture response did not include a manifest.");
+        }
+        const manifest = captureManifestForResponse(manifestValue, res);
+        setCapture(manifest);
+        setAvailable(true);
+        // Fold the served revision into the announced high-water mark so a capture we
+        // JUST loaded is never reported stale against an older announce.
+        setAnnouncedRevision((prev) =>
+          prev === null || manifest.revision > prev ? manifest.revision : prev,
+        );
         return;
       }
-      setCapture(manifest);
-      setAvailable(true);
-      // Fold the served revision into the announced high-water mark so a capture we
-      // JUST loaded is never reported stale against an older announce.
-      setAnnouncedRevision((prev) =>
-        prev === null || manifest.revision > prev ? manifest.revision : prev,
-      );
+      throw new Error("Workspace capture manifest download failed after refreshing its URL.");
     } catch (cause) {
       if (generationRef.current !== generation) return;
       setError(cause instanceof Error ? cause : new Error(String(cause)));
     } finally {
       if (generationRef.current === generation) setLoading(false);
+      if (requestAbortRef.current === requestAbort) requestAbortRef.current = null;
     }
   }, [client, workspaceId, sessionId, identityKey]);
 
@@ -154,6 +256,8 @@ export function useWorkspaceCapture(
   useEffect(() => {
     // Invalidate a request started for the previous identity before clearing its
     // state. The cleanup also fences a response that arrives after unmount.
+    requestAbortRef.current?.abort();
+    requestAbortRef.current = null;
     generationRef.current += 1;
     lastSeqRef.current = 0;
     setCapture(null);
@@ -168,6 +272,8 @@ export function useWorkspaceCapture(
     }
     void refresh();
     return () => {
+      requestAbortRef.current?.abort();
+      requestAbortRef.current = null;
       generationRef.current += 1;
     };
   }, [enabled, refresh]);