@opengeni/react 0.12.0 → 0.15.0

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

@@ -0,0 +1,233 @@
+import type {
+  GetWorkspaceCaptureResponse,
+  SessionEvent,
+  WorkspaceCaptureDegradedReason,
+  WorkspaceCaptureManifest,
+  WorkspaceRevisionCapturedPayload,
+  WorkspaceRevisionDegradedPayload,
+} from "@opengeni/sdk";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useOpenGeni, type ClientOverride } from "../provider";
+
+/** The announce event M1 emits at turn end (metadata only, never content). */
+const REVISION_CAPTURED = "workspace.revision.captured";
+const REVISION_DEGRADED = "workspace.revision.degraded";
+const MANIFEST_FETCH_TIMEOUT_MS = 15_000;
+
+export type UseWorkspaceCaptureOptions = ClientOverride & {
+  /** Live event log (usually `useSessionEvents().events`) — a
+   *  `workspace.revision.captured` for a NEWER revision refreshes the manifest. */
+  events?: SessionEvent[] | undefined;
+  /** Hold off the mount fetch (e.g. the workbench panel is collapsed). Default true. */
+  enabled?: boolean | undefined;
+};
+
+export type UseWorkspaceCaptureResult = {
+  /** The resolved manifest (tree index + per-repo diffs + file refs), or null when
+   *  no capture exists (falls back to the live/wake path — status quo). */
+  capture: WorkspaceCaptureManifest | null;
+  /** The loaded capture's monotonic revision, or null when unavailable. */
+  revision: number | null;
+  /** When the loaded capture was taken (ISO), for the "as of <time>" source badge. */
+  capturedAt: string | null;
+  /** Whether a capture is available at all (the `{available:false}` discriminator). */
+  available: boolean;
+  /** Why the newest durable revision is unavailable. null means no capture has
+   *  been attempted yet; a value means capture explicitly failed closed and
+   *  consumers must use the live box rather than trust an incomplete snapshot. */
+  degradedReason: WorkspaceCaptureDegradedReason | null;
+  /** The changed-file count from the capture's stats, resolved on the FIRST GET
+   *  (from the response's top-level `stats`, before any manifest-URL hop). null
+   *  until that first resolve; 0 when no capture exists. This is the pre-paint
+   *  "changes exist?" signal the dock uses to pick its default tab with no
+   *  embedder events-at-mount contract. */
+  fileCount: number | null;
+  /** A newer revision has been ANNOUNCED than the one currently loaded (a refresh
+   *  is in flight or pending). M5's source badge can show a subtle "updating…". */
+  isStale: boolean;
+  loading: boolean;
+  error: Error | null;
+  /** Force a re-fetch of the latest capture. */
+  refresh: () => Promise<void>;
+};
+
+/**
+ * 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
+ * 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
+ * newer than the one loaded triggers a background refresh (stale-while-revalidate).
+ * `{available:false}` is a value, never a crash — consumers fall back to the
+ * live/wake path exactly as before the capture feature existed.
+ */
+export function useWorkspaceCapture(
+  sessionId: string | null | undefined,
+  options: UseWorkspaceCaptureOptions = {},
+): UseWorkspaceCaptureResult {
+  const { client, workspaceId } = useOpenGeni(options);
+  const enabled = (options.enabled ?? true) && Boolean(sessionId);
+  const identityKey = `${workspaceId}\u0000${sessionId ?? ""}`;
+
+  const [capture, setCapture] = useState<WorkspaceCaptureManifest | null>(null);
+  const [available, setAvailable] = useState(false);
+  const [degradedReason, setDegradedReason] = useState<WorkspaceCaptureDegradedReason | null>(null);
+  // Resolved from the FIRST GET's top-level stats (before any manifest-URL hop),
+  // so the dock can pick its default tab as early as possible. null until then.
+  const [fileCount, setFileCount] = useState<number | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  // The highest revision ANNOUNCED on the event log — compared against the loaded
+  // manifest's revision to compute `isStale` and to gate refreshes.
+  const [announcedRevision, setAnnouncedRevision] = useState<number | null>(null);
+  // State updates are asynchronous, so the previous session's capture still
+  // exists during the first render after an identity switch. Tag it and hide it
+  // synchronously until the new identity's request owns the state.
+  const [stateIdentity, setStateIdentity] = useState(identityKey);
+
+  // 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);
+  // 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;
+    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),
+        });
+        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);
+        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,
+      );
+    } catch (cause) {
+      if (generationRef.current !== generation) return;
+      setError(cause instanceof Error ? cause : new Error(String(cause)));
+    } finally {
+      if (generationRef.current === generation) setLoading(false);
+    }
+  }, [client, workspaceId, sessionId, identityKey]);
+
+  // Mount fetch + reset on identity change.
+  useEffect(() => {
+    // Invalidate a request started for the previous identity before clearing its
+    // state. The cleanup also fences a response that arrives after unmount.
+    generationRef.current += 1;
+    lastSeqRef.current = 0;
+    setCapture(null);
+    setAvailable(false);
+    setDegradedReason(null);
+    setFileCount(null);
+    setAnnouncedRevision(null);
+    setError(null);
+    if (!enabled) {
+      setLoading(false);
+      return;
+    }
+    void refresh();
+    return () => {
+      generationRef.current += 1;
+    };
+  }, [enabled, refresh]);
+
+  // Fold `workspace.revision.captured` announcements. A revision NEWER than the one
+  // loaded bumps the announced high-water mark (→ isStale) and refreshes in the
+  // background. The event is announce-only (metadata) — we still re-fetch the
+  // manifest, since the payload carries no content.
+  const events = options.events;
+  useEffect(() => {
+    if (!enabled || !events) return;
+    let newest: number | null = null;
+    for (const event of events) {
+      if (event.sequence <= lastSeqRef.current) continue;
+      if (event.type === REVISION_CAPTURED) {
+        const payload = event.payload as WorkspaceRevisionCapturedPayload | null;
+        if (payload && typeof payload === "object" && typeof payload.revision === "number") {
+          newest = newest === null ? payload.revision : Math.max(newest, payload.revision);
+        }
+      } else if (event.type === REVISION_DEGRADED) {
+        const payload = event.payload as WorkspaceRevisionDegradedPayload | null;
+        if (payload && typeof payload === "object" && typeof payload.revision === "number") {
+          newest = newest === null ? payload.revision : Math.max(newest, payload.revision);
+        }
+      }
+    }
+    for (const event of events)
+      if (event.sequence > lastSeqRef.current) lastSeqRef.current = event.sequence;
+    if (newest === null) return;
+    setAnnouncedRevision((prev) => (prev === null || newest > prev ? newest : prev));
+  }, [enabled, events]);
+
+  // A newer announced revision than the loaded manifest → refresh in the background.
+  const identityMatches = enabled && stateIdentity === identityKey;
+  const visibleCapture = identityMatches ? capture : null;
+  const visibleAnnouncedRevision = identityMatches ? announcedRevision : null;
+  const loadedRevision = visibleCapture?.revision ?? null;
+  useEffect(() => {
+    if (!enabled) return;
+    if (visibleAnnouncedRevision === null) return;
+    if (loadedRevision !== null && visibleAnnouncedRevision <= loadedRevision) return;
+    // A newer capture exists than the one we hold (or we hold none) — pull it.
+    void refresh();
+  }, [enabled, visibleAnnouncedRevision, loadedRevision, refresh]);
+
+  const isStale =
+    loadedRevision !== null &&
+    visibleAnnouncedRevision !== null &&
+    visibleAnnouncedRevision > loadedRevision;
+
+  return {
+    capture: visibleCapture,
+    revision: loadedRevision,
+    capturedAt: visibleCapture?.capturedAt ?? null,
+    available: identityMatches && available,
+    degradedReason: identityMatches ? degradedReason : null,
+    fileCount: identityMatches ? fileCount : null,
+    isStale,
+    loading: identityMatches && loading,
+    error: identityMatches ? error : null,
+    refresh,
+  };
+}

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

@@ -0,0 +1,231 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useOpenGeni, type ClientOverride } from "../provider";
+
+/**
+ * The wake-on-edit state machine (dossier §3 #5 / §10.4 / §12-C). M3 OWNS this
+ * logic; M5 renders it. States are explicit and exhaustive:
+ *
+ *   viewing-cold      — cold snapshot open, no local edits (editable, cloud).
+ *   buffering         — local edits buffered; the box is not warm and no warm is
+ *                       yet in flight (the host has not attached).
+ *   warming           — edits buffered; the box is actively coming up (the host
+ *                       attached a viewer in response to `wantsWarm`).
+ *   flushing          — the box is warm; the guarded write is in flight.
+ *   flushed           — the buffer was written to the live box.
+ *   conflict          — the live file diverged from the captured base between
+ *                       capture and flush; NO write was issued (C2).
+ *   readonly-offline  — a self-hosted machine that is offline; read-only, no wake.
+ */
+export type WorkspaceEditState =
+  | "viewing-cold"
+  | "buffering"
+  | "warming"
+  | "flushing"
+  | "flushed"
+  | "conflict"
+  | "readonly-offline";
+
+export type WorkspaceEditConflict = {
+  path: string;
+  /** The capture-served content the edit was based on. */
+  base: string;
+  /** The live content found on the box at flush time (what would be overwritten). */
+  live: string;
+};
+
+export type UseWorkspaceEditOptions = ClientOverride & {
+  /** The file being edited (workspace-relative). null disables the machine. */
+  path?: string | null | undefined;
+  /** The capture-served content loaded into the editor — the flush base (C2). */
+  baseContent?: string | null | undefined;
+  /** `capabilities.liveness` — "warm" | "draining" | "cold". Drives the flush. */
+  liveness?: string | undefined;
+  /** True while the host is actively warming the box (attach in flight, not warm
+   *  yet) — lifts `buffering` → `warming`. The host sets this after acting on
+   *  `wantsWarm` (e.g. flipping `attachFiles` on `useSessionCapabilities`). */
+  warming?: boolean | undefined;
+  /** A self-hosted machine that is OFFLINE: read-only, no remote wake possible. */
+  offline?: boolean | undefined;
+  /** Called once when the first cold edit needs the box warmed — the host wires
+   *  this to its liveness primitive (flip `attachFiles`/`attachViewer`). */
+  onWarmRequested?: (() => void) | undefined;
+};
+
+export type UseWorkspaceEditResult = {
+  state: WorkspaceEditState;
+  /** The editor should be read-only (self-hosted offline). */
+  readOnly: boolean;
+  /** The current buffered content (null = no local edit yet). */
+  buffer: string | null;
+  /** The host should warm the box (flip its attach primitive). Latches true from
+   *  the first cold edit until the buffer flushes or is discarded. */
+  wantsWarm: boolean;
+  /** Record an edit from the editor (idempotent per identical content). */
+  edit: (content: string) => void;
+  /** The conflict detail when `state === "conflict"`. */
+  conflict: WorkspaceEditConflict | null;
+  /** Flush the buffer regardless of the base guard (the user chose "overwrite"
+   *  from the conflict bar). Writes last-writer-wins. */
+  overwrite: () => Promise<void>;
+  /** Drop the local buffer and return to viewing the snapshot. */
+  discard: () => void;
+  error: Error | null;
+};
+
+function isLive(liveness: string | undefined): boolean {
+  return liveness === "warm" || liveness === "draining";
+}
+
+/**
+ * Cold-editing without a spinner: the editor opens instantly from the capture,
+ * the first keystroke buffers locally AND signals the host to warm the box, and on
+ * warm the buffer flushes IF the live file still matches the captured base — else a
+ * non-blocking conflict is surfaced and nothing is overwritten (dossier §12-C2).
+ *
+ * The base guard compares the live content at flush time against `baseContent`
+ * (the exact bytes the editor loaded). This is equivalent to the sha256 compare
+ * the dossier describes — M1 leaves `baseHash` null, so the loaded content IS the
+ * authoritative base — and avoids async Web Crypto in the render path.
+ */
+export function useWorkspaceEdit(
+  sessionId: string | null | undefined,
+  options: UseWorkspaceEditOptions = {},
+): UseWorkspaceEditResult {
+  const { client, workspaceId } = useOpenGeni(options);
+  const path = options.path ?? null;
+  const baseContent = options.baseContent ?? null;
+  const live = isLive(options.liveness);
+  const offline = options.offline === true;
+
+  const [buffer, setBuffer] = useState<string | null>(null);
+  const [wantsWarm, setWantsWarm] = useState(false);
+  const [flush, setFlush] = useState<"idle" | "flushing" | "flushed" | "conflict">("idle");
+  const [conflict, setConflict] = useState<WorkspaceEditConflict | null>(null);
+  const [error, setError] = useState<Error | null>(null);
+
+  const onWarmRequested = options.onWarmRequested;
+  const bufferRef = useRef<string | null>(null);
+  bufferRef.current = buffer;
+  // Guards a single in-flight flush against re-entry (liveness can re-render).
+  const flushingRef = useRef(false);
+
+  // Reset the machine when the edited file (or session) changes.
+  useEffect(() => {
+    setBuffer(null);
+    setWantsWarm(false);
+    setFlush("idle");
+    setConflict(null);
+    setError(null);
+    flushingRef.current = false;
+  }, [sessionId, path]);
+
+  const edit = useCallback(
+    (content: string) => {
+      if (offline) return; // read-only — no buffering, no wake.
+      setBuffer((prev) => (prev === content ? prev : content));
+      // Any new edit invalidates a prior flushed/conflict resolution.
+      setFlush((prev) => (prev === "flushing" ? prev : "idle"));
+      setConflict(null);
+      if (!live) {
+        // First cold edit signals the host to warm the box (once).
+        setWantsWarm((prev) => {
+          if (!prev) onWarmRequested?.();
+          return true;
+        });
+      }
+    },
+    [offline, live, onWarmRequested],
+  );
+
+  const doFlush = useCallback(
+    async (force: boolean) => {
+      if (!sessionId || !path) return;
+      const content = bufferRef.current;
+      if (content === null) return;
+      if (flushingRef.current) return;
+      flushingRef.current = true;
+      setFlush("flushing");
+      setError(null);
+      try {
+        if (!force) {
+          // Base guard: re-read the live file and compare to the captured base. A
+          // divergence means the box changed under us — surface a conflict, write
+          // NOTHING (C2).
+          const liveRead = await client.fsRead(workspaceId, sessionId, { path });
+          const liveContent = liveRead.content;
+          if (baseContent !== null && liveContent !== baseContent) {
+            setConflict({ path, base: baseContent, live: liveContent });
+            setFlush("conflict");
+            return;
+          }
+        }
+        await client.fsWrite(workspaceId, sessionId, { path, content, overwrite: true });
+        setConflict(null);
+        setFlush("flushed");
+        setWantsWarm(false);
+      } catch (cause) {
+        setError(cause instanceof Error ? cause : new Error(String(cause)));
+        // Leave the buffer intact so the user can retry; fall back to buffering.
+        setFlush("idle");
+      } finally {
+        flushingRef.current = false;
+      }
+    },
+    [client, workspaceId, sessionId, path, baseContent],
+  );
+
+  // Auto-flush once the box is warm and a buffer is pending (the wake completed).
+  useEffect(() => {
+    if (offline) return;
+    if (!live) return;
+    if (buffer === null) return;
+    if (flush === "flushed" || flush === "conflict" || flush === "flushing") return;
+    void doFlush(false);
+  }, [offline, live, buffer, flush, doFlush]);
+
+  const overwrite = useCallback(async () => {
+    await doFlush(true);
+  }, [doFlush]);
+
+  const discard = useCallback(() => {
+    setBuffer(null);
+    setWantsWarm(false);
+    setFlush("idle");
+    setConflict(null);
+    setError(null);
+  }, []);
+
+  // Derive the exhaustive public state.
+  let state: WorkspaceEditState;
+  if (offline) {
+    state = "readonly-offline";
+  } else if (flush === "flushing") {
+    state = "flushing";
+  } else if (flush === "flushed") {
+    state = "flushed";
+  } else if (flush === "conflict") {
+    state = "conflict";
+  } else if (buffer === null) {
+    state = "viewing-cold";
+  } else if (live) {
+    // Warm with a pending buffer that hasn't entered flush yet — a transient tick
+    // before the auto-flush effect runs.
+    state = "flushing";
+  } else if (options.warming === true) {
+    state = "warming";
+  } else {
+    state = "buffering";
+  }
+
+  return {
+    state,
+    readOnly: offline,
+    buffer,
+    wantsWarm,
+    edit,
+    conflict,
+    overwrite,
+    discard,
+    error,
+  };
+}

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

@@ -5,26 +5,69 @@ import { usePolledValue } from "./internal";
 
 export type UseWorkspaceSessionsOptions = ClientOverride & {
   limit?: number | undefined;
+  parentSessionId?: string | null | undefined;
+  cursor?: string | undefined;
+  search?: string | undefined;
   /** Refresh interval (ms) for fleet/manager views. Off by default. */
   pollIntervalMs?: number | undefined;
   enabled?: boolean | undefined;
 };
 
 export type UseWorkspaceSessionsResult = {
+  /**
+   * All visible rows, with pins first. This preserves the pre-pinning hook
+   * contract for consumers that only read `sessions`.
+   */
   sessions: Session[];
+  /** The complete personal pinned section, also present in `sessions`. */
+  pinned: Session[];
+  nextCursor: string | null;
   loading: boolean;
   error: Error | null;
   refresh: () => Promise<void>;
 };
 
 /** List the workspace's sessions — the data behind fleet and manager views. */
-export function useWorkspaceSessions(options: UseWorkspaceSessionsOptions = {}): UseWorkspaceSessionsResult {
+export function useWorkspaceSessions(
+  options: UseWorkspaceSessionsOptions = {},
+): UseWorkspaceSessionsResult {
   const { client, workspaceId } = useOpenGeni(options);
   const limit = options.limit;
+  const parentSessionId = options.parentSessionId;
+  const cursor = options.cursor;
+  const search = options.search;
+  const queryKey = JSON.stringify({ workspaceId, limit, parentSessionId, cursor, search });
   const load = useCallback(
-    async () => await client.listSessions(workspaceId, limit !== undefined ? { limit } : {}),
-    [client, workspaceId, limit],
+    async () => ({
+      queryKey,
+      page: await client.listSessionPage(workspaceId, {
+        ...(limit !== undefined ? { limit } : {}),
+        ...(parentSessionId !== undefined ? { parentSessionId } : {}),
+        ...(cursor !== undefined ? { cursor } : {}),
+        ...(search !== undefined ? { search } : {}),
+      }),
+    }),
+    [client, workspaceId, limit, parentSessionId, cursor, search, queryKey],
   );
-  const state = usePolledValue(load, { pollIntervalMs: options.pollIntervalMs, enabled: options.enabled });
-  return { sessions: state.data ?? [], loading: state.loading, error: state.error, refresh: state.refresh };
+  const state = usePolledValue(load, {
+    pollIntervalMs: options.pollIntervalMs,
+    enabled: options.enabled,
+  });
+  // usePolledValue drops stale async completions, while the explicit query key
+  // also prevents the previous query's cached value from painting for the one
+  // render before its loader-change effect clears state.
+  const page = state.data?.queryKey === queryKey ? state.data.page : null;
+  const pinned = page?.pinned ?? [];
+  const ordinary = page?.sessions ?? [];
+  return {
+    // The old hook returned every visible session. Keep that public behavior
+    // while exposing `pinned` separately for the compact section. The API page
+    // itself continues to paginate only `ordinary` rows via nextCursor.
+    sessions: [...pinned, ...ordinary],
+    pinned,
+    nextCursor: page?.nextCursor ?? null,
+    loading: state.loading,
+    error: state.error,
+    refresh: state.refresh,
+  };
 }

package/src/hooks/use-workspaces.ts

@@ -27,40 +27,43 @@ export type UseWorkspacesResult = {
 export function useWorkspaces(options: UseWorkspacesOptions = {}): UseWorkspacesResult {
   const client = useOpenGeniClient(options);
   const load = useCallback(async () => await client.listWorkspaces(), [client]);
-  const state = usePolledValue(load, { pollIntervalMs: options.pollIntervalMs, enabled: options.enabled });
-  const mutation = useMutationRunner();
+  const { data, loading, error, refresh } = usePolledValue(load, {
+    pollIntervalMs: options.pollIntervalMs,
+    enabled: options.enabled,
+  });
+  const { run, mutating, mutationError, clearMutationError } = useMutationRunner();
 
   const create = useCallback(
     async (request: CreateWorkspaceRequest): Promise<Workspace | null> => {
-      const result = await mutation.run(() => client.createWorkspace(request));
+      const result = await run(() => client.createWorkspace(request));
       if (result) {
-        await state.refresh();
+        await refresh();
       }
       return result;
     },
-    [client, mutation.run, state.refresh],
+    [client, run, refresh],
   );
 
   const update = useCallback(
     async (workspaceId: string, request: UpdateWorkspaceRequest): Promise<Workspace | null> => {
-      const result = await mutation.run(() => client.updateWorkspace(workspaceId, request));
+      const result = await run(() => client.updateWorkspace(workspaceId, request));
       if (result) {
-        await state.refresh();
+        await refresh();
       }
       return result;
     },
-    [client, mutation.run, state.refresh],
+    [client, run, refresh],
   );
 
   return {
-    workspaces: state.data ?? [],
-    loading: state.loading,
-    error: state.error,
-    refresh: state.refresh,
+    workspaces: data ?? [],
+    loading,
+    error,
+    refresh,
     create,
     update,
-    mutating: mutation.mutating,
-    mutationError: mutation.mutationError,
-    clearMutationError: mutation.clearMutationError,
+    mutating,
+    mutationError,
+    clearMutationError,
   };
 }