@opengeni/react 0.13.0 → 0.20.0

package/src/components/queue-surface-state.tsx

@@ -0,0 +1,94 @@
+import { Loader2Icon, RotateCwIcon } from "lucide-react";
+
+import type { UseTurnQueueResult } from "../hooks/use-turn-queue";
+
+type QueueStateProps = {
+  queue: UseTurnQueueResult;
+};
+
+export function EmptyQueueStateSurface({ queue }: QueueStateProps) {
+  const hasError = Boolean(queue.error || queue.mutationError);
+  return (
+    <div
+      className="mx-auto mb-2 w-full max-w-3xl shrink-0 px-4 sm:px-6"
+      data-testid="queue-surface"
+    >
+      <div className="overflow-hidden rounded-lg border border-border bg-surface/80 shadow-sm">
+        {queue.stoppingPreviousAttempt ? (
+          <QueueStoppingStatus queue={queue} dividerAfter={hasError} />
+        ) : null}
+        {hasError ? <QueueErrorAlert queue={queue} /> : null}
+      </div>
+    </div>
+  );
+}
+
+export function QueueStoppingStatus({
+  queue,
+  dividerAfter = false,
+}: QueueStateProps & { dividerAfter?: boolean }) {
+  return (
+    <div
+      role="status"
+      aria-live="polite"
+      className={`flex min-h-11 items-center gap-2.5 bg-status-waiting/[0.07] px-3 py-2 text-xs text-fg ${
+        dividerAfter ? "border-b border-status-waiting/20" : ""
+      }`}
+      data-testid="stopping-previous-attempt"
+    >
+      <Loader2Icon
+        aria-hidden="true"
+        className="size-3.5 shrink-0 animate-spin text-status-waiting motion-reduce:animate-none"
+      />
+      <span className="min-w-0">
+        <span className="font-medium">
+          {queue.effectiveControl?.state === "paused"
+            ? "Stopping current attempt…"
+            : "Stopping previous attempt…"}
+        </span>{" "}
+        <span className="text-fg-muted">
+          {queue.effectiveControl?.state === "paused"
+            ? "Queued work stays saved until you resume."
+            : "Queued work is saved and starts automatically."}
+        </span>
+      </span>
+    </div>
+  );
+}
+
+export function QueueErrorAlert({
+  queue,
+  dividerBefore = false,
+}: QueueStateProps & { dividerBefore?: boolean }) {
+  return (
+    <div className={`${dividerBefore ? "border-t border-border" : ""} p-2`}>
+      <div
+        role="alert"
+        className="flex min-w-0 max-w-full flex-wrap items-start gap-2 rounded-md bg-status-failed/10 px-2 py-1.5 text-xs text-status-failed"
+      >
+        <span
+          role="region"
+          aria-label="Queue error details"
+          tabIndex={0}
+          className="max-h-[min(5rem,20dvh)] min-w-0 max-w-full flex-[1_1_5rem] overflow-auto overscroll-contain whitespace-pre-wrap rounded-sm outline-none [overflow-wrap:anywhere] [unicode-bidi:plaintext] focus-visible:ring-2 focus-visible:ring-ring/40"
+          data-testid="queue-error-message"
+          dir="auto"
+        >
+          {(queue.mutationError ?? queue.error)?.message}
+        </span>
+        <button
+          type="button"
+          onClick={() => {
+            queue.clearMutationError();
+            void queue.refresh();
+          }}
+          aria-label="Dismiss queue error and retry"
+          title="Retry loading the queue"
+          className="ms-auto inline-flex size-7 shrink-0 items-center justify-center self-start rounded-md outline-none transition-colors hover:bg-surface-3 focus-visible:ring-2 focus-visible:ring-ring/40 motion-reduce:transition-none pointer-coarse:size-[44px]"
+        >
+          <RotateCwIcon className="size-3.5" />
+        </button>
+      </div>
+    </div>
+  );
+}

package/src/components/queue-surface.tsx

@@ -0,0 +1,60 @@
+import { Loader2Icon } from "lucide-react";
+import { lazy, Suspense, type ComponentType } from "react";
+
+import type { QueueSurfaceProps } from "./queue-surface-implementation";
+import { EmptyQueueStateSurface } from "./queue-surface-state";
+
+export type { QueueSurfaceProps } from "./queue-surface-implementation";
+
+const loadQueueSurface = () => import("./queue-surface-implementation");
+type QueueSurfaceModule = { QueueSurface: ComponentType<QueueSurfaceProps> };
+type QueueSurfaceLoader = () => Promise<QueueSurfaceModule>;
+
+/** The sole human prompt queue: compact above Goal, Agents, and composer. */
+export const QueueSurface = createQueueSurface(loadQueueSurface);
+
+/** @internal Deterministic Suspense seam for the QueueSurface regression suite. */
+export function createQueueSurfaceForTest(loadImplementation: QueueSurfaceLoader) {
+  return createQueueSurface(loadImplementation);
+}
+
+function createQueueSurface(loadImplementation: QueueSurfaceLoader) {
+  const LazyQueueSurface = lazy(async () => ({
+    default: (await loadImplementation()).QueueSurface,
+  }));
+
+  return function QueueSurfaceBoundary(props: QueueSurfaceProps) {
+    const { queue } = props;
+    if (queue.queue.length === 0) {
+      if (!queue.stoppingPreviousAttempt && !queue.error && !queue.mutationError) return null;
+      return <EmptyQueueStateSurface queue={queue} />;
+    }
+
+    return (
+      <Suspense fallback={<QueueSurfaceFallback count={queue.queue.length} />}>
+        <LazyQueueSurface {...props} />
+      </Suspense>
+    );
+  };
+}
+
+function QueueSurfaceFallback({ count }: { count: number }) {
+  return (
+    <div
+      aria-live="polite"
+      className="mx-auto mb-2 w-full max-w-3xl shrink-0 px-4 sm:px-6"
+      data-testid="queue-surface-loading"
+      role="status"
+    >
+      <div className="overflow-hidden rounded-lg border border-border bg-surface/80 shadow-sm">
+        <div className="flex items-center gap-2 px-3 py-2 text-xs text-fg-muted pointer-coarse:min-h-[44px]">
+          <Loader2Icon
+            aria-hidden="true"
+            className="size-3.5 shrink-0 animate-spin motion-reduce:animate-none"
+          />
+          Loading {count} queued prompt{count === 1 ? "" : "s"}…
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/components/sandbox-files.tsx

@@ -1,8 +1,11 @@
-import type { FsReadResponse } from "@opengeni/sdk";
+import { FileCode2Icon, FileWarningIcon, LoaderCircleIcon } from "lucide-react";
 import { type ReactNode, useCallback, useEffect, useRef, useState } from "react";
 import { cn } from "../lib/cn";
 import { useThemeType } from "../lib/use-theme-type";
-import type { UseSandboxFilesResult } from "../hooks/use-sandbox-files";
+import {
+  CapturedFileUnavailableError,
+  type UseSandboxFilesResult,
+} from "../hooks/use-sandbox-files";
 import type { UseSandboxGitResult } from "../hooks/use-sandbox-git";
 import { CodeEditor } from "./code-editor";
 import { FileBrowser } from "./file-browser";
@@ -27,6 +30,23 @@ export type SandboxFilesProps = {
    *  dock warms the box on this so the save lands fast; opening/reading never fires
    *  it. Browsing the tree/diff must not warm a box. */
   onEditIntent?: (() => void) | undefined;
+  /** A guarded diff path routed here by the parent workspace. */
+  requestedPath?: string | undefined;
+  /** Identity for one guarded-file request. Increment this when the same path is
+   *  deliberately requested again; it also lets a pending request be consumed
+   *  without overriding later manual tree navigation. Defaults to the path. */
+  requestedPathRequestId?: string | number | undefined;
+  /** False while the parent is waking a cold sandbox for `requestedPath`. */
+  requestedPathReady?: boolean | undefined;
+  /** The machine is cold and no durable capture exists yet. Render an explicit
+   *  wake gate instead of an empty-tree lie or an implicit Channel-A read. */
+  workspaceResting?: boolean | undefined;
+  /** A deliberate wake has started but the live file surface is not ready yet. */
+  workspaceWaking?: boolean | undefined;
+  /** Whether live reads are currently authoritative. */
+  liveWorkspaceReady?: boolean | undefined;
+  /** Deliberately wake the machine to read content absent from the capture. */
+  onWakeWorkspace?: (() => void) | undefined;
   themeType?: "dark" | "light" | undefined;
   className?: string | undefined;
 };
@@ -45,6 +65,13 @@ export function SandboxFiles({
   usePierre = true,
   editable = true,
   onEditIntent,
+  requestedPath,
+  requestedPathRequestId,
+  requestedPathReady = true,
+  workspaceResting = false,
+  workspaceWaking = false,
+  liveWorkspaceReady = true,
+  onWakeWorkspace,
   themeType,
   className,
 }: SandboxFilesProps) {
@@ -52,6 +79,30 @@ export function SandboxFiles({
   // View vs Edit for the selected file. Resets to View on every new selection so
   // opening a file never lands you in a stale dirty editor for a different path.
   const [editMode, setEditMode] = useState(false);
+  const [liveRequestedPath, setLiveRequestedPath] = useState<string | null>(null);
+  const [viewReloadRevision, setViewReloadRevision] = useState(0);
+  const pendingRequestRef = useRef<string | number | null>(null);
+  const handledRequestRef = useRef<string | number | null>(null);
+  const requestKey = requestedPath ? (requestedPathRequestId ?? requestedPath) : null;
+
+  useEffect(() => {
+    if (!requestedPath || requestKey === null) {
+      pendingRequestRef.current = null;
+      handledRequestRef.current = null;
+      return;
+    }
+    if (handledRequestRef.current === requestKey) {
+      return;
+    }
+    if (!requestedPathReady) {
+      pendingRequestRef.current = requestKey;
+      return;
+    }
+    handledRequestRef.current = requestKey;
+    pendingRequestRef.current = null;
+    setSelected(requestedPath);
+    setEditMode(false);
+  }, [requestKey, requestedPath, requestedPathReady]);
 
   // Side-by-side (tree left, viewer right) once the surface is wide enough;
   // stacked (tree over viewer) on a narrow dock. Tracked off the container so it
@@ -77,13 +128,21 @@ export function SandboxFiles({
   // writable). Nothing is auto-selected — the pane waits for a tree click, so the
   // Files tab opens as a calm browser, not a diff.
   const viewPath = selected;
-  const fileView = useFileView(viewPath, files.readFile);
+  const fileView = useFileView(viewPath, files.readFile, viewReloadRevision);
 
   // Selecting a (different) file always returns to View — never drop the user into
-  // an editor whose buffer belongs to the previously-selected path.
+  // an editor whose buffer belongs to the previously-selected path. Manual
+  // navigation also consumes a pending guarded-file request: a late cold→warm
+  // transition must never pull the user away from the file they chose meanwhile.
   const selectFile = useCallback((path: string) => {
+    if (pendingRequestRef.current !== null) {
+      handledRequestRef.current = pendingRequestRef.current;
+      pendingRequestRef.current = null;
+    }
     setSelected(path);
     setEditMode(false);
+    setLiveRequestedPath(null);
+    setViewReloadRevision(0);
   }, []);
 
   // A tree file is editable only when it is a real, fully-loaded text file: not
@@ -99,9 +158,54 @@ export function SandboxFiles({
     !fileView.truncated &&
     fileView.content !== null;
   const showEditor = canEdit && editMode;
+  const captureFileUnavailable =
+    fileView.error instanceof CapturedFileUnavailableError ? fileView.error : null;
+  const waitingForSelectedFile =
+    liveRequestedPath === viewPath &&
+    (!liveWorkspaceReady || files.loading) &&
+    captureFileUnavailable !== null;
 
   if (!fileSystemAvailable) {
-    return <Notice className={className}>This sandbox does not expose a file system.</Notice>;
+    return (
+      <Notice
+        className={className}
+        icon={<FileWarningIcon className="size-5" aria-hidden />}
+        title="Files unavailable"
+        announce="alert"
+      >
+        This sandbox does not expose a file system.
+      </Notice>
+    );
+  }
+
+  if (workspaceResting || workspaceWaking) {
+    return (
+      <div className={cn("h-full", className)} data-opengeni-workspace-resting>
+        <Notice
+          icon={
+            workspaceWaking ? (
+              <LoaderCircleIcon
+                className="size-5 animate-spin motion-reduce:animate-none"
+                aria-hidden
+              />
+            ) : (
+              <FileCode2Icon className="size-5" aria-hidden />
+            )
+          }
+          title={workspaceWaking ? "Waking workspace" : "Workspace is resting"}
+          announce="status"
+        >
+          <p>
+            {workspaceWaking
+              ? "Connecting to the live file system…"
+              : "No captured revision is available yet. Wake the sandbox to browse its current files."}
+          </p>
+          {!workspaceWaking && onWakeWorkspace ? (
+            <WakeButton onClick={onWakeWorkspace}>Open live workspace</WakeButton>
+          ) : null}
+        </Notice>
+      </div>
+    );
   }
 
   return (
@@ -138,7 +242,10 @@ export function SandboxFiles({
           )}
         >
           <div className="flex shrink-0 items-center justify-between gap-2 border-b border-og-border bg-og-surface-1 px-2 py-1">
-            <span className="min-w-0 truncate font-og-mono text-og-xs text-og-fg-muted">
+            <span
+              data-opengeni-selected-file
+              className="min-w-0 truncate font-og-mono text-og-xs text-og-fg-muted"
+            >
               {selected ?? "No file selected"}
             </span>
             {/* View/Edit toggle — only for a real, fully-loaded text file the editor
@@ -163,16 +270,54 @@ export function SandboxFiles({
                   path={viewPath}
                   initialContents={fileView.content}
                   themeType={resolvedTheme}
-                  onSave={(contents) => files.writeFile(viewPath, contents)}
+                  onSave={(contents) =>
+                    files.writeFile(viewPath, contents, { expectedContent: fileView.content! })
+                  }
+                  onOverwrite={(contents) => files.writeFile(viewPath, contents, { force: true })}
+                  onReload={() => setViewReloadRevision((revision) => revision + 1)}
                   {...(onEditIntent ? { onEditIntent } : {})}
                   className="h-full"
                 />
+              ) : waitingForSelectedFile ? (
+                <Notice
+                  icon={
+                    <LoaderCircleIcon
+                      className="size-5 animate-spin motion-reduce:animate-none"
+                      aria-hidden
+                    />
+                  }
+                  title="Waking workspace"
+                  announce="status"
+                >
+                  Opening {viewPath} when the live file system is ready…
+                </Notice>
+              ) : captureFileUnavailable ? (
+                <Notice icon={<FileCode2Icon className="size-5" aria-hidden />} title="On machine">
+                  <p>
+                    {captureFileUnavailable.reason === "too-large"
+                      ? "This file is larger than the captured preview limit."
+                      : captureFileUnavailable.reason === "content-missing"
+                        ? "The captured copy is no longer available."
+                        : "This file was indexed, but it was not changed in the captured turn."}
+                  </p>
+                  {onWakeWorkspace ? (
+                    <WakeButton
+                      onClick={() => {
+                        setLiveRequestedPath(viewPath);
+                        if (liveWorkspaceReady) void files.refresh();
+                        else onWakeWorkspace();
+                      }}
+                    >
+                      {liveWorkspaceReady ? "Retry live file" : "Open live file"}
+                    </WakeButton>
+                  ) : null}
+                </Notice>
               ) : fileView.error ? (
-                <Notice>
+                <Notice announce="alert">
                   Could not open {viewPath}: {fileView.error.message}
                 </Notice>
               ) : fileView.loading ? (
-                <Notice>Loading {viewPath}…</Notice>
+                <Notice announce="status">Loading {viewPath}…</Notice>
               ) : fileView.isBinary ? (
                 <Notice>
                   {viewPath} is a binary file ({fileView.sizeBytes ?? 0} bytes).
@@ -204,11 +349,26 @@ export function SandboxFiles({
                   )}
                 </>
               ) : (
-                <Notice>Loading {viewPath}…</Notice>
+                <Notice announce="status">Loading {viewPath}…</Notice>
               )
+            ) : // Nothing selected — the tree shows the whole workspace; pick a file.
+            requestedPath && !requestedPathReady ? (
+              <Notice
+                icon={
+                  <LoaderCircleIcon
+                    className="size-5 animate-spin motion-reduce:animate-none"
+                    aria-hidden
+                  />
+                }
+                title="Waking sandbox"
+                announce="status"
+              >
+                Opening {requestedPath} when the live workspace is ready…
+              </Notice>
             ) : (
-              // Nothing selected — the tree shows the whole workspace; pick a file.
-              <Notice>Select a file in the tree to view it.</Notice>
+              <Notice icon={<FileCode2Icon className="size-5" aria-hidden />} title="Choose a file">
+                Select a file in the tree to preview it.
+              </Notice>
             )}
           </div>
         </div>
@@ -217,19 +377,36 @@ export function SandboxFiles({
   );
 }
 
+function WakeButton({ children, onClick }: { children: ReactNode; onClick: () => void }) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      className="mt-1 inline-flex min-h-11 items-center justify-center rounded-og-md bg-og-accent px-3 py-2 text-og-sm font-medium text-og-on-accent shadow-sm transition-colors hover:bg-og-accent-hover focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-og-accent focus-visible:ring-offset-2 focus-visible:ring-offset-og-bg"
+    >
+      {children}
+    </button>
+  );
+}
+
 function GitHeader({ git, dirtyCount }: { git: UseSandboxGitResult; dirtyCount: number }) {
   const dirty = dirtyCount > 0;
   return (
     <div className="flex shrink-0 items-center gap-2 border-b border-og-border bg-og-surface-1 px-2 py-1 text-og-sm">
       <span
+        aria-hidden="true"
         className={cn(
           "size-2 shrink-0 rounded-full",
           dirty ? "bg-og-status-running" : "bg-og-status-idle",
         )}
-        title={dirty ? `${dirtyCount} changed` : "clean"}
       />
+      <span className="sr-only">
+        {dirty ? `Working tree has ${dirtyCount} changed files` : "Working tree clean"}
+      </span>
       <span className="truncate font-og-mono text-og-fg">
-        {git.branch ?? (git.isRepo ? "(detached)" : "no repo")}
+        {git.repoCount > 1
+          ? `${git.repoCount} repositories`
+          : (git.branch ?? (git.isRepo ? "(detached)" : "no repo"))}
       </span>
       {(git.ahead > 0 || git.behind > 0) && (
         <span className="flex shrink-0 items-center gap-1.5 text-og-xs text-og-fg-subtle">
@@ -238,7 +415,13 @@ function GitHeader({ git, dirtyCount }: { git: UseSandboxGitResult; dirtyCount:
         </span>
       )}
       {dirty && (
-        <span className="ml-auto shrink-0 text-og-xs text-og-fg-subtle">{dirtyCount} changed</span>
+        <span
+          aria-hidden="true"
+          data-contrast-audited
+          className="ml-auto shrink-0 text-og-xs text-og-fg-subtle"
+        >
+          {dirtyCount} changed
+        </span>
       )}
     </div>
   );
@@ -261,7 +444,7 @@ function Segmented({
           type="button"
           onClick={() => onChange(opt.value)}
           className={cn(
-            "min-h-7 rounded-og-xs px-1.5 py-0.5 text-og-xs max-[1023px]:min-h-11 pointer-coarse:min-h-11",
+            "min-h-7 rounded-og-xs px-1.5 py-0.5 text-og-xs focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-og-accent max-[1023px]:min-h-11 max-[1023px]:min-w-11 pointer-coarse:min-h-11 pointer-coarse:min-w-11",
             opt.value === value
               ? "bg-og-accent-soft text-og-fg"
               : "text-og-fg-subtle hover:text-og-fg",
@@ -294,7 +477,8 @@ type FileViewState = {
  */
 function useFileView(
   path: string | null,
-  readFile: (path: string) => Promise<FsReadResponse>,
+  readFile: UseSandboxFilesResult["readFile"],
+  reloadRevision = 0,
 ): FileViewState {
   const [state, setState] = useState<FileViewState>({
     content: null,
@@ -317,6 +501,7 @@ function useFileView(
       return;
     }
     let cancelled = false;
+    const abort = new AbortController();
     setState({
       content: null,
       isBinary: false,
@@ -325,7 +510,7 @@ function useFileView(
       loading: true,
       error: null,
     });
-    void readFile(path)
+    void readFile(path, { signal: abort.signal })
       .then((res) => {
         if (cancelled) return;
         const content = res.isBinary
@@ -355,8 +540,9 @@ function useFileView(
       });
     return () => {
       cancelled = true;
+      abort.abort();
     };
-  }, [path, readFile]);
+  }, [path, readFile, reloadRevision]);
   return state;
 }
 
@@ -375,15 +561,38 @@ function decodeBase64Utf8(b64: string): string {
   return b64;
 }
 
-function Notice({ children, className }: { children: ReactNode; className?: string | undefined }) {
+function Notice({
+  children,
+  className,
+  icon,
+  title,
+  announce,
+}: {
+  children: ReactNode;
+  className?: string | undefined;
+  icon?: ReactNode | undefined;
+  title?: string | undefined;
+  announce?: "status" | "alert" | undefined;
+}) {
   return (
     <div
+      role={announce}
+      aria-atomic={announce ? "true" : undefined}
+      aria-live={announce === "alert" ? "assertive" : announce === "status" ? "polite" : undefined}
       className={cn(
         "flex h-full items-center justify-center p-4 text-center text-og-sm text-og-fg-subtle",
         className,
       )}
     >
-      {children}
+      <div className="flex max-w-sm flex-col items-center gap-2.5">
+        {icon ? (
+          <span className="grid size-10 place-items-center rounded-og-lg border border-og-border bg-og-surface-1 text-og-fg-muted shadow-sm">
+            {icon}
+          </span>
+        ) : null}
+        {title ? <p className="font-medium text-og-fg">{title}</p> : null}
+        <div className="leading-5">{children}</div>
+      </div>
     </div>
   );
 }

package/src/components/sandbox-terminal.tsx

@@ -221,7 +221,13 @@ export function SandboxTerminal({
   // status lines INSIDE xterm instead of an overlay — but only when there is no
   // firehose transcript to show yet (otherwise the projected output is shown).
   const warm = liveness === "warm" || liveness === "draining";
-  const booting = activated && !ptyMode && !warm && liveness != null && result.chunks.length === 0;
+  const booting =
+    activated &&
+    !ptyMode &&
+    !warm &&
+    liveness !== null &&
+    liveness !== undefined &&
+    result.chunks.length === 0;
 
   function handleActivate() {
     if (!activated) setActivated(true);
@@ -502,7 +508,7 @@ export function SandboxTerminal({
                 writtenRef.current = new Set();
                 wroteFirehoseRef.current = false;
               }}
-              className="rounded-og-sm px-1.5 py-0.5 text-og-xs hover:text-og-fg pointer-coarse:min-h-10"
+              className="rounded-og-sm px-1.5 py-0.5 text-og-xs hover:text-og-fg pointer-coarse:min-h-11"
             >
               Clear
             </button>