@opengeni/react 1.0.1 → 1.0.2-canary.37191796234001

package/src/components/sandbox-files.tsx

@@ -2,6 +2,7 @@ import { FileCode2Icon, FileWarningIcon, LoaderCircleIcon } from "lucide-react";
 import { type ReactNode, useCallback, useEffect, useRef, useState } from "react";
 import { Group, Panel, Separator } from "react-resizable-panels";
 import { cn } from "../lib/cn";
+import { prefersReducedMotion } from "../lib/motion";
 import { useThemeType } from "../lib/use-theme-type";
 import {
   CapturedFileUnavailableError,
@@ -9,6 +10,7 @@ import {
   type UseSandboxFilesResult,
 } from "../hooks/use-sandbox-files";
 import type { UseSandboxGitResult } from "../hooks/use-sandbox-git";
+import { filePathVisibility, type FileNodeVisibilityPredicate } from "../file-node-visibility";
 import { CodeEditor } from "./code-editor";
 import { FileBrowser } from "./file-browser";
 import { PierreFile } from "./pierre-file";
@@ -32,8 +34,16 @@ 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. */
+  /** Restore the file last viewed in this task. Invalid/missing paths still
+   * surface the ordinary file-view error instead of changing files silently. */
+  initialSelectedPath?: string | null | undefined;
+  onSelectedPathChange?: ((path: string | null) => void) | undefined;
+  /** Presentation-only node filter shared with the tree and selected-file view. */
+  isNodeVisible?: FileNodeVisibilityPredicate | undefined;
+  /** A deliberate file-open path routed here by the parent workspace. */
   requestedPath?: string | undefined;
+  /** 1-based line to reveal after `requestedPath` opens. */
+  requestedLine?: number | null | 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. */
@@ -47,6 +57,8 @@ export type SandboxFilesProps = {
   workspaceWaking?: boolean | undefined;
   /** Whether live reads are currently authoritative. */
   liveWorkspaceReady?: boolean | undefined;
+  /** Failed live negotiation; never present a failure as an ongoing wake. */
+  workspaceError?: Error | null | undefined;
   /** Deliberately wake the machine to read content absent from the capture. */
   onWakeWorkspace?: (() => void) | undefined;
   themeType?: "dark" | "light" | undefined;
@@ -67,22 +79,33 @@ export function SandboxFiles({
   usePierre = true,
   editable = true,
   onEditIntent,
+  initialSelectedPath,
+  onSelectedPathChange,
+  isNodeVisible,
   requestedPath,
+  requestedLine,
   requestedPathRequestId,
   requestedPathReady = true,
   workspaceResting = false,
   workspaceWaking = false,
   liveWorkspaceReady = true,
+  workspaceError = null,
   onWakeWorkspace,
   themeType,
   className,
 }: SandboxFilesProps) {
-  const [selected, setSelected] = useState<string | null>(null);
+  const [selected, setSelected] = useState<string | null>(() => initialSelectedPath ?? null);
   // 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 [focusLine, setFocusLine] = useState<number | null>(null);
+  const [treeRevealRequest, setTreeRevealRequest] = useState<{
+    path: string;
+    requestId: string | number;
+  } | null>(null);
   const [liveRequestedPath, setLiveRequestedPath] = useState<string | null>(null);
   const [viewReloadRevision, setViewReloadRevision] = useState(0);
+  const viewerScrollRef = useRef<HTMLDivElement | null>(null);
   const pendingRequestRef = useRef<string | number | null>(null);
   const handledRequestRef = useRef<string | number | null>(null);
   const requestKey = requestedPath ? (requestedPathRequestId ?? requestedPath) : null;
@@ -91,6 +114,7 @@ export function SandboxFiles({
     if (!requestedPath || requestKey === null) {
       pendingRequestRef.current = null;
       handledRequestRef.current = null;
+      setTreeRevealRequest(null);
       return;
     }
     if (handledRequestRef.current === requestKey) {
@@ -98,13 +122,40 @@ export function SandboxFiles({
     }
     if (!requestedPathReady) {
       pendingRequestRef.current = requestKey;
+      setTreeRevealRequest(null);
+      return;
+    }
+    if (isNodeVisible && files.loading && files.tree.length === 0) return;
+    if (isNodeVisible && !files.loading && files.tree.length === 0) {
+      handledRequestRef.current = requestKey;
+      pendingRequestRef.current = null;
+      setTreeRevealRequest(null);
+      return;
+    }
+    if (filePathVisibility(files.tree, requestedPath, isNodeVisible) === "hidden") {
+      handledRequestRef.current = requestKey;
+      pendingRequestRef.current = null;
+      setTreeRevealRequest(null);
       return;
     }
     handledRequestRef.current = requestKey;
     pendingRequestRef.current = null;
     setSelected(requestedPath);
+    onSelectedPathChange?.(requestedPath);
     setEditMode(false);
-  }, [requestKey, requestedPath, requestedPathReady]);
+    setFocusLine(requestedLine != null && requestedLine > 0 ? requestedLine : null);
+    setTreeRevealRequest({ path: requestedPath, requestId: requestKey });
+    setViewReloadRevision((revision) => revision + 1);
+  }, [
+    files.loading,
+    files.tree,
+    isNodeVisible,
+    onSelectedPathChange,
+    requestKey,
+    requestedLine,
+    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
@@ -143,27 +194,52 @@ export function SandboxFiles({
   // The selected tree file opens in the viewer (read-only) or the editor (when
   // 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 selectedVisibility = selected
+    ? filePathVisibility(files.tree, selected, isNodeVisible)
+    : "unknown";
+  const visibilityPending = Boolean(isNodeVisible && files.loading && files.tree.length === 0);
+  const viewPath = selectedVisibility === "hidden" || visibilityPending ? null : selected;
+  useEffect(() => {
+    if (selected === null || selectedVisibility !== "hidden") return;
+    setSelected(null);
+    onSelectedPathChange?.(null);
+    setEditMode(false);
+    setFocusLine(null);
+    setTreeRevealRequest(null);
+    setLiveRequestedPath(null);
+  }, [onSelectedPathChange, selected, selectedVisibility]);
   const fileView = useFileView(
     viewPath,
     files.readFile,
-    (files.contentRevision ?? 0) + viewReloadRevision,
+    `${files.contentRevision ?? 0}:${viewReloadRevision}`,
   );
 
+  useEffect(() => {
+    if (focusLine === null && viewReloadRevision > 0 && viewerScrollRef.current) {
+      viewerScrollRef.current.scrollTop = 0;
+    }
+  }, [focusLine, viewReloadRevision]);
+
   // Selecting a (different) file always returns to View — never drop the user into
   // 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);
-  }, []);
+  const selectFile = useCallback(
+    (path: string) => {
+      if (pendingRequestRef.current !== null) {
+        handledRequestRef.current = pendingRequestRef.current;
+        pendingRequestRef.current = null;
+      }
+      setSelected(path);
+      onSelectedPathChange?.(path);
+      setEditMode(false);
+      setFocusLine(null);
+      setTreeRevealRequest(null);
+      setLiveRequestedPath(null);
+      setViewReloadRevision(0);
+    },
+    [onSelectedPathChange],
+  );
 
   // A tree file is editable only when it is a real, fully-loaded text file: not
   // binary (would corrupt on save) and not truncated (we only hold a PREFIX). The
@@ -181,10 +257,22 @@ export function SandboxFiles({
   const captureFileUnavailable =
     fileView.error instanceof CapturedFileUnavailableError ? fileView.error : null;
   const waitingForSelectedFile =
+    !workspaceError &&
     liveRequestedPath === viewPath &&
     (!liveWorkspaceReady || files.loading) &&
     captureFileUnavailable !== null;
 
+  if (workspaceError && !liveWorkspaceReady && files.source !== "capture") {
+    return (
+      <Notice className={className} title="Could not open live workspace" announce="alert">
+        <p>{workspaceError.message}</p>
+        {onWakeWorkspace ? (
+          <WakeButton onClick={onWakeWorkspace}>Retry live workspace</WakeButton>
+        ) : null}
+      </Notice>
+    );
+  }
+
   if (workspaceResting || workspaceWaking) {
     return (
       <div className={cn("h-full", className)} data-opengeni-workspace-resting>
@@ -263,7 +351,14 @@ export function SandboxFiles({
         >
           <FileBrowser
             result={files}
+            isNodeVisible={isNodeVisible}
             selectedPath={selected ?? undefined}
+            {...(treeRevealRequest
+              ? {
+                  revealPath: treeRevealRequest.path,
+                  revealPathRequestId: treeRevealRequest.requestId,
+                }
+              : {})}
             onSelectFile={selectFile}
             editable={editable}
             emptyState="This directory is empty"
@@ -295,7 +390,11 @@ export function SandboxFiles({
               data-opengeni-selected-file
               className="min-w-0 truncate font-og-mono text-og-xs text-og-fg-muted"
             >
-              {selected ?? "No file selected"}
+              {selected
+                ? focusLine !== null
+                  ? `${selected}:${focusLine}`
+                  : selected
+                : "No file selected"}
             </span>
             {/* View/Edit toggle — only for a real, fully-loaded text file the editor
                 can safely round-trip. Binary/truncated/read-only files never get an
@@ -311,7 +410,11 @@ export function SandboxFiles({
               />
             )}
           </div>
-          <div className="min-h-0 flex-1 overflow-auto">
+          <div
+            ref={viewerScrollRef}
+            className="min-h-0 flex-1 overflow-auto"
+            data-opengeni-file-viewer-scroll
+          >
             {viewPath ? (
               showEditor && fileView.content !== null ? (
                 <CodeEditor
@@ -327,6 +430,15 @@ export function SandboxFiles({
                   {...(onEditIntent ? { onEditIntent } : {})}
                   className="h-full"
                 />
+              ) : workspaceError &&
+                (liveRequestedPath === viewPath || requestedPath === viewPath) &&
+                !liveWorkspaceReady ? (
+                <Notice title="Could not open live file" announce="alert">
+                  <p>{workspaceError.message}</p>
+                  {onWakeWorkspace ? (
+                    <WakeButton onClick={onWakeWorkspace}>Retry live file</WakeButton>
+                  ) : null}
+                </Notice>
               ) : waitingForSelectedFile ? (
                 <Notice
                   icon={
@@ -367,6 +479,12 @@ export function SandboxFiles({
                 </Notice>
               ) : fileView.loading ? (
                 <Notice announce="status">Loading {viewPath}…</Notice>
+              ) : fileView.imageUrl ? (
+                <RasterFilePreview
+                  key={fileView.imageUrl}
+                  src={fileView.imageUrl}
+                  path={viewPath}
+                />
               ) : fileView.isBinary ? (
                 <Notice>
                   {viewPath} is a binary file ({fileView.sizeBytes ?? 0} bytes).
@@ -379,8 +497,9 @@ export function SandboxFiles({
                       loaded). Editing is disabled to avoid corrupting the file.
                     </div>
                   )}
-                  {usePierre ? (
+                  {usePierre && focusLine === null ? (
                     <PierreFile
+                      key={`${viewPath}:${viewReloadRevision}`}
                       path={viewPath}
                       contents={fileView.content}
                       themeType={resolvedTheme}
@@ -391,6 +510,12 @@ export function SandboxFiles({
                       }
                       className="p-1"
                     />
+                  ) : focusLine !== null ? (
+                    <LineNumberedFile
+                      path={viewPath}
+                      contents={fileView.content}
+                      focusLine={focusLine}
+                    />
                   ) : (
                     <pre className="overflow-auto whitespace-pre p-2 font-og-mono text-og-sm text-og-fg">
                       {fileView.content}
@@ -402,18 +527,27 @@ export function SandboxFiles({
               )
             ) : // 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>
+              workspaceError ? (
+                <Notice title="Could not open live file" announce="alert">
+                  <p>{workspaceError.message}</p>
+                  {onWakeWorkspace ? (
+                    <WakeButton onClick={onWakeWorkspace}>Retry live file</WakeButton>
+                  ) : null}
+                </Notice>
+              ) : (
+                <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>
+              )
             ) : (
               <Notice icon={<FileCode2Icon className="size-5" aria-hidden />} title="Choose a file">
                 Select a file in the tree to preview it.
@@ -431,13 +565,72 @@ function WakeButton({ children, onClick }: { children: ReactNode; onClick: () =>
     <button
       type="button"
       onClick={onClick}
-      className="mt-1 inline-flex min-h-11 items-center justify-center rounded-og-md bg-og-accent-deep px-3 py-2 text-og-sm font-medium text-og-accent-fg shadow-sm transition-opacity hover:opacity-90 focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-og-accent focus-visible:ring-offset-2 focus-visible:ring-offset-og-bg"
+      className="mt-1 inline-flex min-h-11 items-center justify-center rounded-og-md border border-og-primary-border bg-og-primary text-og-primary-fg px-3 py-2 text-og-sm font-medium transition-colors hover:bg-og-primary-hover focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-og-accent focus-visible:ring-offset-2 focus-visible:ring-offset-og-bg"
     >
       {children}
     </button>
   );
 }
 
+function LineNumberedFile({
+  path,
+  contents,
+  focusLine,
+}: {
+  path: string;
+  contents: string;
+  focusLine: number;
+}) {
+  const lines = contents.split("\n");
+  const inRange = focusLine >= 1 && focusLine <= lines.length;
+  const targetRef = useRef<HTMLDivElement | null>(null);
+
+  useEffect(() => {
+    targetRef.current?.scrollIntoView({
+      block: "center",
+      behavior: prefersReducedMotion() ? "auto" : "smooth",
+    });
+  }, [path, focusLine, contents]);
+
+  return (
+    <div
+      className="h-full min-h-0 overflow-auto font-og-mono text-og-sm text-og-fg"
+      role="region"
+      aria-label={inRange ? `${path} at line ${focusLine}` : path}
+    >
+      {!inRange ? (
+        <p
+          className="border-b border-og-border bg-og-surface-1 px-2 py-1 text-og-xs text-og-fg-muted"
+          role="status"
+        >
+          Line {focusLine} is past the end of this file.
+        </p>
+      ) : null}
+      <div>
+        {lines.map((text, index) => {
+          const lineNumber = index + 1;
+          const focused = inRange && lineNumber === focusLine;
+          return (
+            <div
+              key={lineNumber}
+              ref={focused ? targetRef : undefined}
+              data-opengeni-file-line={lineNumber}
+              {...(focused ? { "data-opengeni-focus-line": "" } : {})}
+              aria-current={focused ? "location" : undefined}
+              className={cn("flex gap-3 px-2 py-0.5 leading-6", focused && "bg-og-accent-soft")}
+            >
+              <span className="w-11 shrink-0 select-none text-right tabular-nums text-og-fg-subtle">
+                {lineNumber}
+              </span>
+              <pre className="min-w-0 flex-1 whitespace-pre-wrap break-words">{text || " "}</pre>
+            </div>
+          );
+        })}
+      </div>
+    </div>
+  );
+}
+
 function GitHeader({ git, loading }: { git: SandboxFilesGitSummary; loading: boolean }) {
   if (loading) {
     return (
@@ -474,8 +667,10 @@ function GitHeader({ git, loading }: { git: SandboxFilesGitSummary; loading: boo
       </span>
       {(git.ahead > 0 || git.behind > 0) && (
         <span className="flex shrink-0 items-center gap-1.5 text-og-xs text-og-fg-subtle">
-          {git.ahead > 0 && <span>↑{git.ahead}</span>}
-          {git.behind > 0 && <span>↓{git.behind}</span>}
+          {/* Small arrow glyphs can make axe's pixel overlap heuristic inconclusive.
+              Keep both counters in the same computed-contrast audit as the dirty count. */}
+          {git.ahead > 0 && <span data-contrast-audited>↑{git.ahead}</span>}
+          {git.behind > 0 && <span data-contrast-audited>↓{git.behind}</span>}
         </span>
       )}
       {dirty && (
@@ -523,6 +718,7 @@ function Segmented({
 
 type FileViewState = {
   content: string | null;
+  imageUrl?: string | null;
   isBinary: boolean;
   /** The backend truncated the read (size cap hit) — content is a PREFIX only.
    *  Editing+saving such a file would write the prefix back and corrupt it, so
@@ -542,7 +738,7 @@ type FileViewState = {
 function useFileView(
   path: string | null,
   readFile: UseSandboxFilesResult["readFile"],
-  reloadRevision = 0,
+  reloadRevision: string | number = 0,
 ): FileViewState {
   const previousPathRef = useRef<string | null>(null);
   const [state, setState] = useState<FileViewState>({
@@ -595,6 +791,8 @@ function useFileView(
             : res.content;
         setState({
           content,
+          imageUrl:
+            !res.truncated && res.encoding === "base64" ? rasterImageUrl(path, res.content) : null,
           isBinary: res.isBinary,
           truncated: res.truncated,
           sizeBytes: res.sizeBytes,
@@ -626,6 +824,38 @@ function useFileView(
   return state;
 }
 
+/** Only raster formats belong in this preview; never interpret SVG/HTML as a document. */
+function rasterImageUrl(path: string, content: string): string | null {
+  const extension = path.split(".").pop()?.toLowerCase();
+  const mime =
+    extension === "png"
+      ? "image/png"
+      : extension === "jpg" || extension === "jpeg"
+        ? "image/jpeg"
+        : extension === "gif"
+          ? "image/gif"
+          : extension === "webp"
+            ? "image/webp"
+            : null;
+  return mime ? `data:${mime};base64,${content}` : null;
+}
+
+function RasterFilePreview({ src, path }: { src: string; path: string }) {
+  const [failed, setFailed] = useState(false);
+  return failed ? (
+    <Notice title="Image preview unavailable" announce="alert">
+      Could not decode {path} as an image.
+    </Notice>
+  ) : (
+    <img
+      src={src}
+      alt={path}
+      onError={() => setFailed(true)}
+      className="max-w-full object-contain"
+    />
+  );
+}
+
 /** Decode a base64 payload to a UTF-8 string (browser `atob` + TextDecoder). */
 function decodeBase64Utf8(b64: string): string {
   try {
@@ -671,7 +901,9 @@ function Notice({
           </span>
         ) : null}
         {title ? <p className="font-medium text-og-fg">{title}</p> : null}
-        <div className="leading-5">{children}</div>
+        <div data-contrast-audited className="leading-5">
+          {children}
+        </div>
       </div>
     </div>
   );

package/src/components/sandbox-terminal.tsx

@@ -1,5 +1,12 @@
 import type { TerminalCapability } from "@opengeni/sdk";
-import { type ReactNode, useEffect, useLayoutEffect, useRef, useState } from "react";
+import {
+  type ReactNode,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+  useSyncExternalStore,
+} from "react";
 import { cn } from "../lib/cn";
 import { type TerminalStreamStatus, useTerminalStream } from "../hooks/use-terminal-stream";
 import type { UseSandboxTerminalResult } from "../hooks/use-sandbox-terminal";
@@ -7,6 +14,7 @@ import { resolveTerminalFont, xtermThemeFromTokens } from "../lib/xterm-theme";
 import { sandboxAcceptsLiveIo } from "../lib/sandbox-liveness";
 import { terminalCanAcquirePty } from "../lib/terminal-capability";
 import { attachRenderer, type RendererLoaders, type RendererTier } from "../lib/xterm-renderer";
+import { sandboxTerminalPeers } from "../lib/workbench-peers";
 
 /**
  * A COMPLETE xterm `ITheme` (subset by intent, but every field xterm colors a
@@ -114,6 +122,19 @@ type XtermLike = {
   };
 };
 type FitAddonLike = { fit: () => void };
+type TerminalPeerBundle = {
+  Terminal: new (options: Record<string, unknown>) => XtermLike;
+  FitAddon: new () => FitAddonLike;
+  WebLinksAddon: new (handler: (event: MouseEvent, uri: string) => void) => unknown;
+  loadWebgl?:
+    | (() => Promise<{
+        WebglAddon: new () => {
+          dispose: () => void;
+          onContextLoss?: (callback: () => void) => void;
+        };
+      }>)
+    | undefined;
+};
 
 export type TerminalSurfaceState =
   | "loading"
@@ -237,6 +258,12 @@ export function SandboxTerminal({
   const wroteFirehoseRef = useRef(false);
   const bootActiveRef = useRef(false);
   const [ready, setReady] = useState(false);
+  const [loadError, setLoadError] = useState<Error | null>(null);
+  const peerRevision = useSyncExternalStore(
+    sandboxTerminalPeers.subscribe,
+    sandboxTerminalPeers.revision,
+    sandboxTerminalPeers.revision,
+  );
   const [inputReady, setInputReady] = useState(false);
   const [activated, setActivated] = useState(false);
 
@@ -353,12 +380,10 @@ export function SandboxTerminal({
 
     ensureXtermBaseCss();
 
+    setLoadError(null);
     void (async () => {
-      const [{ Terminal }, { FitAddon }, { WebLinksAddon }] = await Promise.all([
-        import("@xterm/xterm"),
-        import("@xterm/addon-fit"),
-        import("@xterm/addon-web-links"),
-      ]);
+      const { Terminal, FitAddon, WebLinksAddon, loadWebgl } =
+        (await sandboxTerminalPeers.load()) as TerminalPeerBundle;
       if (disposed) return;
       await waitForSize(el);
       if (disposed) return;
@@ -397,13 +422,17 @@ export function SandboxTerminal({
       const failSet = forcedRendererFailures();
       const loaders: RendererLoaders = {
         webgl: async (onLoss) => {
+          if (disposed) throw new Error("Terminal was disposed");
           if (failSet.has("webgl")) throw new Error("forced webgl failure");
-          const { WebglAddon } = await import("@xterm/addon-webgl");
+          if (!loadWebgl) throw new Error("WebGL terminal renderer is not enabled");
+          const { WebglAddon } = await loadWebgl();
+          if (disposed) throw new Error("Terminal was disposed");
           const addon = new WebglAddon() as unknown as {
             dispose: () => void;
             onContextLoss?: (cb: () => void) => void;
           };
           addon.onContextLoss?.(() => {
+            if (disposed) return;
             try {
               addon.dispose();
             } catch {
@@ -416,6 +445,7 @@ export function SandboxTerminal({
         },
       };
       await attachRenderer("webgl", loaders, (tier) => {
+        if (disposed) return;
         rendererRef.current = tier;
         el.setAttribute("data-og-term-renderer", tier);
       });
@@ -448,7 +478,9 @@ export function SandboxTerminal({
         }
         setReady(true);
       });
-    })();
+    })().catch((cause: unknown) => {
+      if (!disposed) setLoadError(cause instanceof Error ? cause : new Error(String(cause)));
+    });
 
     return () => {
       disposed = true;
@@ -461,9 +493,9 @@ export function SandboxTerminal({
       bootActiveRef.current = false;
       setReady(false);
     };
-    // Mount ONCE — see the effects below for the runtime option syncs.
+    // Mount once per peer registration; runtime options sync without a remount.
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, []);
+  }, [peerRevision]);
 
   // Sync stdin/cursor at runtime (NOT a remount) when interactivity flips, so the
   // projection→PTY handoff keeps the single Terminal instance + its scrollback.
@@ -621,7 +653,12 @@ export function SandboxTerminal({
         onPointerDownCapture={handleActivate}
         onFocusCapture={handleActivate}
       >
-        {!ready && (placeholder ?? <TerminalPlaceholder />)}
+        {!ready &&
+          (loadError ? (
+            <p role="alert">{loadError.message}</p>
+          ) : (
+            (placeholder ?? <TerminalPlaceholder />)
+          ))}
         {/* Kept `visibility:hidden` until the first successful fit so the first
             VISIBLE frame is already correctly sized (no 80×24 flash — E4). */}
         <div