@backmatter/studio 0.0.15 → 0.0.17

package/src/pages/CodeSessionPage.tsx

@@ -0,0 +1,1361 @@
+// packages/studio/src/pages/CodeSessionPage.tsx
+import { useCallback, useEffect, useRef, useState, type FormEvent } from "react";
+import type { RouteModel } from "@backmatter/core";
+import { useOutletContext } from "react-router";
+import * as stylex from "@stylexjs/stylex";
+import { Combobox } from "@base-ui/react/combobox";
+import {
+  IconArrowRotateClockwise,
+  IconArrowUpRight,
+  IconCheckmark1Small,
+  IconCrossSmall,
+  IconEyeOpen,
+  IconFiles,
+  IconGlobe,
+} from "@central-icons-react/round-outlined-radius-2-stroke-1.5";
+import { ChatPanel } from "../chat/ChatPanel";
+import { ChatProvider, ChatSessionScope, useChatBusy } from "../chat/ChatProvider";
+import { useReplicaState } from "../replica/useReplica";
+import { colors, radius, space, type } from "../styles/tokens.stylex";
+import { apiCredentials, apiHeaders, apiUrl } from "../studio-config";
+import { Text } from "../ui/Text";
+import { cx, popup, popupClassName } from "../ui/popup";
+import type { WorkspaceOutletContext } from "../workspace/types";
+import { bootSteps, hostPath, type BootStep, type HostPhase } from "./code-session-boot";
+import {
+  frameAddress,
+  framedLocation,
+  rememberPath,
+  rememberedPath,
+  previewUrl,
+  type HostPreview,
+} from "./code-session-frame";
+import { contentRoutes, matchingRoutes } from "./code-session-routes";
+import { CodeSessionFiles, type FilesView } from "./CodeSessionFiles";
+import { PreviewSizeSwitch, PreviewViewport } from "./PreviewSize";
+import { persistPreviewSize, readPreviewSize, type PreviewSize } from "./preview-size";
+import type { WorkspaceFile } from "./code-session-files";
+import { clearCodeSessionEdits, fetchCodeSessionEdits, updateCodeSessionBranch } from "../api";
+import { branchNoticeKind, type BranchNoticeKind } from "./branch-notice";
+import { usePublishCodeSession } from "./code-session-context";
+import { sessionDocument } from "./session-preview";
+import { useSessionPreview } from "./use-session-preview";
+
+type OpenState =
+  | { kind: "loading" }
+  | { kind: "forbidden" }
+  | { kind: "fail"; error: string }
+  | { kind: "ready"; sessionId: string };
+
+export type HostView = {
+  phase: HostPhase | null;
+  furthest: "installing" | "starting" | null;
+  log: string;
+  timedOut: boolean;
+};
+
+export type SessionTab = "preview" | "files";
+
+// A first install of a customer's dependencies takes minutes in a fresh container.
+const HOST_WAIT_MS = 10 * 60 * 1000;
+const STATUS_POLL_MS = 2000;
+
+export function CodeSessionScreen({
+  state,
+  host,
+  tab,
+  onTab,
+  preview,
+  path,
+  location,
+  onPath,
+  reloads,
+  live = false,
+  onReload,
+  onOpen,
+  routes = [],
+  routesPending = false,
+  onOpenRoutes,
+  previewSize = "desktop",
+  onPreviewSize = () => {},
+  models = [],
+  files,
+  chat,
+  notice = null,
+  noticeBusy = false,
+  onUpdateBranch = () => {},
+  onClearEdits = () => {},
+}: {
+  state: OpenState;
+  host: HostView;
+  tab: SessionTab;
+  onTab: (tab: SessionTab) => void;
+  files: FilesView;
+  /** The host's own origin and its ticketed entry, or null until the host is up. */
+  preview: HostPreview | null;
+  /** Where the frame was sent. */
+  path: string;
+  /** Where the frame's page says it is now, after its own navigation. */
+  location: string;
+  onPath: (path: string) => void;
+  reloads: number;
+  /** A file edit. The open page stays up until the next document has loaded. */
+  live?: boolean;
+  onReload: () => void;
+  onOpen: () => void;
+  /** Public routes of the content files in this checkout. */
+  routes?: readonly string[];
+  /** The checkout file list has not come back yet. */
+  routesPending?: boolean;
+  onOpenRoutes?: () => void;
+  previewSize?: PreviewSize;
+  onPreviewSize?: (size: PreviewSize) => void;
+  /** Models whose routes name the document under a pointed block. */
+  models?: readonly RouteModel[];
+  chat: React.ReactNode;
+  notice?: BranchNoticeKind | null;
+  /** Chat is writing, or the checkout is already being replaced. */
+  noticeBusy?: boolean;
+  onUpdateBranch?: () => void;
+  onClearEdits?: () => void;
+}) {
+  // The entry's ticket sets the host's cookie on first load; later loads ride that cookie.
+  // A reload uses the route the frame is on, which can differ from the last address typed.
+  const chatBusy = useChatBusy();
+  const actionBusy = noticeBusy || chatBusy;
+  const frameSrc = preview ? frameAddress(preview, reloads > 0 ? location : path, reloads) : null;
+  const frameRef = useRef<HTMLIFrameElement>(null);
+  const heldFrameRef = useRef<HTMLIFrameElement | null>(null);
+  const [pointFrame, setPointFrame] = useState<HTMLIFrameElement | null>(null);
+  const frameWatch = `${tab}:${reloads}:${frameSrc ?? ""}`;
+  const [frameSeen, setFrameSeen] = useState(frameWatch);
+  const [frameLoaded, setFrameLoaded] = useState<string | null>(null);
+  const [held, setHeld] = useState<{ reload: number; src: string } | null>(null);
+  if (frameWatch !== frameSeen) {
+    setFrameSeen(frameWatch);
+    setFrameLoaded(null);
+  }
+  // A live edit keeps the document that is already up. The next one loads behind it.
+  const holding = live && held !== null && frameSrc !== null && held.reload !== reloads;
+  const framePending = !holding && frameSrc !== null && tab === "preview" && frameLoaded !== frameWatch;
+  let pointOrigin: string | null = null;
+  if (preview) {
+    try {
+      pointOrigin = new URL(preview.origin).origin;
+    } catch {
+      pointOrigin = null;
+    }
+  }
+  useSessionPreview({
+    frame: tab === "preview" ? pointFrame : null,
+    origin: pointOrigin,
+    models,
+    enabled: state.kind === "ready",
+  });
+
+  useEffect(() => {
+    if (tab !== "preview") {
+      setPointFrame(null);
+      return;
+    }
+    setPointFrame(holding ? heldFrameRef.current : frameRef.current);
+  }, [tab, holding, reloads, frameSrc]);
+
+  function revealFrame() {
+    if (!frameSrc) return;
+    try {
+      const href = frameRef.current?.contentWindow?.location.href;
+      if (!href || href === "about:blank") return;
+    } catch {
+      // A cross-origin document means the host answered.
+    }
+    setFrameLoaded(frameWatch);
+    setHeld({ reload: reloads, src: frameSrc });
+  }
+
+  if (state.kind === "forbidden") return null;
+
+  return (
+    <div {...stylex.props(styles.shell)}>
+      <aside {...stylex.props(styles.chat)} aria-label="Code session chat">
+        {chat}
+      </aside>
+
+      <section {...stylex.props(styles.stage)} aria-label="Host">
+        <div {...stylex.props(styles.toolbar)}>
+          <div role="tablist" aria-label="View" {...stylex.props(styles.tabs)}>
+            <TabButton active={tab === "preview"} onClick={() => onTab("preview")}>
+              <IconEyeOpen size={14} ariaHidden />
+              Preview
+            </TabButton>
+            <TabButton active={tab === "files"} onClick={() => onTab("files")}>
+              <IconFiles size={14} ariaHidden />
+              Files
+            </TabButton>
+          </div>
+
+          <AddressBar
+            path={location}
+            enabled={frameSrc !== null && tab === "preview"}
+            routes={routes}
+            routesPending={routesPending}
+            onOpenRoutes={onOpenRoutes}
+            onPath={onPath}
+            onReload={onReload}
+            onOpen={onOpen}
+          />
+          <div {...stylex.props(styles.sizeSwitch)}>
+            <PreviewSizeSwitch
+              size={previewSize}
+              onSize={onPreviewSize}
+              disabled={frameSrc === null || tab !== "preview"}
+            />
+          </div>
+        </div>
+
+        {notice ? (
+          <div {...stylex.props(styles.notice)} role="status">
+            <span {...stylex.props(styles.noticeText)}>
+              {notice === "edits"
+                ? "This branch has new commits. Commit them, or clear the edit set, before updating."
+                : notice === "fold"
+                  ? "This branch has new commits. The last commit is still folding."
+                  : "This branch has new commits."}
+            </span>
+            {notice === "update" ? (
+              <button
+                type="button"
+                {...stylex.props(styles.noticeButton)}
+                disabled={actionBusy}
+                onClick={onUpdateBranch}
+              >
+                Update branch
+              </button>
+            ) : null}
+            {notice === "edits" ? (
+              <button
+                type="button"
+                {...stylex.props(styles.noticeButton)}
+                disabled={actionBusy}
+                onClick={onClearEdits}
+              >
+                Clear edit set
+              </button>
+            ) : null}
+          </div>
+        ) : null}
+
+        <div {...stylex.props(styles.canvas)}>
+          {tab === "files" ? (
+            <CodeSessionFiles {...files} />
+          ) : state.kind === "fail" ? (
+            <BootCard title="This branch cannot open a code session" error={state.error} />
+          ) : frameSrc ? (
+            <PreviewViewport size={previewSize}>
+              {holding && held ? (
+                <iframe
+                  ref={heldFrameRef}
+                  key={held.reload}
+                  title="Code session"
+                  src={held.src}
+                  sandbox="allow-scripts allow-same-origin allow-forms allow-popups allow-modals allow-downloads"
+                  {...stylex.props(styles.frame)}
+                />
+              ) : null}
+              <iframe
+                ref={frameRef}
+                key={reloads}
+                title={holding ? "" : "Code session"}
+                aria-hidden={holding || undefined}
+                src={frameSrc}
+                sandbox="allow-scripts allow-same-origin allow-forms allow-popups allow-modals allow-downloads"
+                onLoad={revealFrame}
+                {...stylex.props(styles.frame, holding && styles.frameIncoming)}
+              />
+              {framePending ? (
+                <div {...stylex.props(styles.pending)} role="status">
+                  <span {...stylex.props(styles.mark, styles.spinner)} />
+                  Loading the page
+                </div>
+              ) : null}
+            </PreviewViewport>
+          ) : (
+            <BootCard
+              title={
+                host.timedOut
+                  ? "The dev server has not opened its port yet"
+                  : host.phase === "failed" || host.phase === "stopped"
+                    ? "The host stopped while booting"
+                    : "Booting the host"
+              }
+              steps={bootSteps({
+                opening: state.kind === "loading",
+                phase: host.phase,
+                furthest: host.furthest,
+              })}
+              log={host.log}
+            />
+          )}
+        </div>
+      </section>
+    </div>
+  );
+}
+
+function TabButton({
+  active,
+  onClick,
+  children,
+}: {
+  active: boolean;
+  onClick: () => void;
+  children: React.ReactNode;
+}) {
+  return (
+    <button
+      type="button"
+      role="tab"
+      aria-selected={active}
+      onClick={onClick}
+      {...stylex.props(styles.tab, active && styles.tabActive)}
+    >
+      {children}
+    </button>
+  );
+}
+
+function AddressBar({
+  path,
+  enabled,
+  routes,
+  routesPending,
+  onOpenRoutes,
+  onPath,
+  onReload,
+  onOpen,
+}: {
+  path: string;
+  enabled: boolean;
+  routes: readonly string[];
+  routesPending: boolean;
+  onOpenRoutes?: () => void;
+  onPath: (path: string) => void;
+  onReload: () => void;
+  onOpen: () => void;
+}) {
+  const [query, setQuery] = useState<string | null>(null);
+  const [open, setOpen] = useState(false);
+  const picked = useRef(false);
+  const fieldRef = useRef<HTMLButtonElement>(null);
+  const inputRef = useRef<HTMLInputElement>(null);
+  const shown = query ? matchingRoutes(routes, query) : [...routes];
+
+  useEffect(() => {
+    if (!open) return;
+    const input = inputRef.current;
+    input?.focus();
+    input?.select();
+  }, [open]);
+
+  return (
+    <div {...stylex.props(styles.address)}>
+      <button
+        type="button"
+        aria-label="Reload preview"
+        disabled={!enabled}
+        onClick={onReload}
+        {...stylex.props(styles.iconButton)}
+      >
+        <IconArrowRotateClockwise size={14} ariaHidden />
+      </button>
+      <Combobox.Root
+        items={shown}
+        filteredItems={shown}
+        inputValue={query ?? ""}
+        disabled={!enabled}
+        open={open}
+        value={routes.includes(path) ? path : null}
+        onOpenChange={(next) => {
+          if (!enabled && next) return;
+          setOpen(next);
+          if (next) onOpenRoutes?.();
+          else setQuery(null);
+        }}
+        onInputValueChange={(value, details) => {
+          if (details.reason === "input-change" || details.reason === "input-clear") {
+            setQuery(value);
+          }
+        }}
+        onValueChange={(value) => {
+          if (typeof value !== "string") return;
+          picked.current = true;
+          setQuery(null);
+          onPath(hostPath(value));
+          queueMicrotask(() => {
+            picked.current = false;
+          });
+        }}
+      >
+        <Combobox.Trigger
+          ref={fieldRef}
+          aria-label="Preview path"
+          disabled={!enabled}
+          data-no-ring
+          className={cx(styles.addressTrigger)}
+        >
+          <IconGlobe size={13} ariaHidden />
+          <span {...stylex.props(styles.addressPath)}>{path}</span>
+        </Combobox.Trigger>
+        <Combobox.Portal>
+          <Combobox.Positioner
+            anchor={fieldRef}
+            side="bottom"
+            align="start"
+            sideOffset={6}
+            className={cx(popup.positioner)}
+          >
+            <Combobox.Popup
+              aria-label="Pages"
+              className={(state) => popupClassName(state, styles.routePopup)}
+            >
+              <form
+                onSubmit={(event: FormEvent<HTMLFormElement>) => {
+                  event.preventDefault();
+                  const fromList = picked.current;
+                  picked.current = false;
+                  if (fromList) return;
+                  const typed = event.currentTarget.querySelector("input")?.value;
+                  if (typed?.trim()) onPath(hostPath(typed));
+                  setOpen(false);
+                  setQuery(null);
+                }}
+              >
+                <Combobox.Input
+                  ref={inputRef}
+                  placeholder="Find a page"
+                  aria-label="Find a page"
+                  spellCheck={false}
+                  autoComplete="off"
+                  data-no-ring
+                  className={cx(popup.quietInput, styles.routeSearch)}
+                  onKeyDown={(event) => {
+                    if (event.key !== "Enter") return;
+                    // A highlighted row is chosen by the combobox. A bare Enter goes to the typed path.
+                    if (event.currentTarget.getAttribute("aria-activedescendant")) return;
+                    const typed = event.currentTarget.value.trim();
+                    if (!typed) return;
+                    picked.current = true;
+                    onPath(hostPath(typed));
+                  }}
+                />
+              </form>
+              <div {...stylex.props(popup.separator)} />
+              <Combobox.Empty className={cx(popup.empty)}>
+                {routesPending ? "Loading pages" : "No pages"}
+              </Combobox.Empty>
+              <Combobox.List className={cx(styles.routeList)}>
+                {(route: string) => (
+                  <Combobox.Item
+                    key={route}
+                    value={route}
+                    className={(state) =>
+                      cx(
+                        popup.item,
+                        styles.routeItem,
+                        state.highlighted && popup.itemHighlighted,
+                        state.selected && popup.itemSelected,
+                      )
+                    }
+                  >
+                    {route}
+                  </Combobox.Item>
+                )}
+              </Combobox.List>
+            </Combobox.Popup>
+          </Combobox.Positioner>
+        </Combobox.Portal>
+      </Combobox.Root>
+      <button
+        type="button"
+        aria-label="Open preview in a new tab"
+        disabled={!enabled}
+        onClick={onOpen}
+        {...stylex.props(styles.iconButton)}
+      >
+        <IconArrowUpRight size={14} ariaHidden />
+      </button>
+    </div>
+  );
+}
+
+function BootCard({
+  title,
+  steps,
+  log,
+  error,
+}: {
+  title: string;
+  steps?: BootStep[];
+  log?: string;
+  error?: string;
+}) {
+  const tail = (log ?? "").trimEnd().split("\n").slice(-12).join("\n");
+  return (
+    <div {...stylex.props(styles.bootWrap)}>
+      <div {...stylex.props(styles.bootCard)} role="status" aria-live="polite">
+        <Text size="md" weight="medium">
+          {title}
+        </Text>
+        {steps ? (
+          <ol {...stylex.props(styles.steps)}>
+            {steps.map((step) => (
+              <li key={step.label} {...stylex.props(styles.step)}>
+                <StepMark state={step.state} />
+                <span
+                  {...stylex.props(
+                    styles.stepLabel,
+                    step.state === "pending" && styles.stepPending,
+                    step.state === "failed" && styles.stepFailed,
+                  )}
+                >
+                  {step.label}
+                </span>
+              </li>
+            ))}
+          </ol>
+        ) : null}
+        {error ? <p {...stylex.props(styles.error)}>{error}</p> : null}
+        {tail ? <pre {...stylex.props(styles.log)}>{tail}</pre> : null}
+      </div>
+    </div>
+  );
+}
+
+function StepMark({ state }: { state: BootStep["state"] }) {
+  if (state === "done") {
+    return (
+      <span {...stylex.props(styles.mark, styles.markDone)}>
+        <IconCheckmark1Small size={14} ariaHidden />
+      </span>
+    );
+  }
+  if (state === "failed") {
+    return (
+      <span {...stylex.props(styles.mark, styles.markFailed)}>
+        <IconCrossSmall size={14} ariaHidden />
+      </span>
+    );
+  }
+  if (state === "active") {
+    return <span {...stylex.props(styles.mark, styles.spinner)} />;
+  }
+  return <span {...stylex.props(styles.mark, styles.markPending)} />;
+}
+
+function storedPreviewPath(workspaceId: string): string {
+  try {
+    return rememberedPath(window.sessionStorage, workspaceId);
+  } catch {
+    return "/";
+  }
+}
+
+async function requestPreview(workspaceId: string, sessionId: string): Promise<HostPreview | null> {
+  const res = await fetch(
+    apiUrl(`/workspaces/${workspaceId}/code-sessions/${sessionId}/preview`),
+    { method: "POST", credentials: apiCredentials(), headers: apiHeaders() },
+  ).catch(() => null);
+  if (!res?.ok) return null;
+  const body = (await res.json().catch(() => null)) as Partial<HostPreview> | null;
+  return typeof body?.origin === "string" && typeof body.entry === "string"
+    ? { origin: body.origin, entry: body.entry }
+    : null;
+}
+
+export default function CodeSessionPage() {
+  const { workspace, models } = useOutletContext<WorkspaceOutletContext>();
+  const git = useReplicaState().git(workspace.id);
+  const branch = git?.currentBranch ?? "main";
+  const [state, setState] = useState<OpenState>({ kind: "loading" });
+  const [host, setHost] = useState<HostView>({
+    phase: null,
+    furthest: null,
+    log: "",
+    timedOut: false,
+  });
+  const [tab, setTab] = useState<SessionTab>("preview");
+  const [preview, setPreview] = useState<HostPreview | null>(null);
+  const [path, setPath] = useState(() => storedPreviewPath(workspace.id));
+  const [location, setLocation] = useState(() => storedPreviewPath(workspace.id));
+  const [reloads, setReloads] = useState(0);
+  const [previewSize, setPreviewSize] = useState(readPreviewSize);
+  const [live, setLive] = useState(false);
+  const [dismissedRoute, setDismissedRoute] = useState<string | null>(null);
+  const [fileList, setFileList] = useState<string[] | null>(null);
+  const [routesPending, setRoutesPending] = useState(false);
+  const [filesError, setFilesError] = useState<string | null>(null);
+  const [selectedFile, setSelectedFile] = useState<string | null>(null);
+  const [openedFile, setOpenedFile] = useState<WorkspaceFile | "loading" | null>(null);
+  const latestFile = useRef<string | null>(null);
+
+  const sessionId = state.kind === "ready" ? state.sessionId : null;
+  const [editCount, setEditCount] = useState(0);
+  const [foldPending, setFoldPending] = useState(false);
+  const [baseSha, setBaseSha] = useState<string | null>(null);
+  const [updating, setUpdating] = useState(false);
+  const publishCodeSession = usePublishCodeSession();
+
+  const refreshEdits = useCallback(() => {
+    if (!sessionId) {
+      setEditCount(0);
+      setFoldPending(false);
+      return;
+    }
+    void fetchCodeSessionEdits(workspace.id, sessionId)
+      .then((list) => {
+        setEditCount(list.files.length);
+        setFoldPending(list.foldPending);
+      })
+      .catch(() => {
+        setEditCount(0);
+        setFoldPending(false);
+      });
+  }, [sessionId, workspace.id]);
+
+  // The host's dev server does not push a reload through the preview proxy.
+  // The write tool has already asked the server to compile this page. The open
+  // page stays up while that next document loads.
+  const reloadPreview = useCallback(() => {
+    setLive(true);
+    setReloads((n) => n + 1);
+  }, []);
+  const settleEdits = useCallback(() => {
+    refreshEdits();
+    window.setTimeout(() => refreshEdits(), 800);
+  }, [refreshEdits]);
+
+  useEffect(() => {
+    refreshEdits();
+    const timer = window.setInterval(refreshEdits, 8000);
+    return () => window.clearInterval(timer);
+  }, [refreshEdits]);
+
+  useEffect(() => {
+    if (!sessionId) {
+      publishCodeSession(null);
+      return;
+    }
+    publishCodeSession({ sessionId, editCount, refresh: refreshEdits, updating });
+    return () => publishCodeSession(null);
+  }, [sessionId, editCount, refreshEdits, publishCodeSession, updating]);
+
+  // The agent and the dev server change the checkout, so read it fresh when the list is opened.
+  const loadCheckout = useCallback(async () => {
+    if (!sessionId) return;
+    const res = await fetch(
+      apiUrl(`/workspaces/${workspace.id}/code-sessions/${sessionId}/files`),
+      { credentials: apiCredentials(), headers: apiHeaders() },
+    ).catch(() => null);
+    const body = res?.ok ? ((await res.json().catch(() => null)) as { files?: string[] } | null) : null;
+    if (body?.files) {
+      setFileList(body.files);
+      setFilesError(null);
+    } else {
+      setFilesError("The checkout could not be read. Is the host still running?");
+    }
+  }, [sessionId, workspace.id]);
+
+  useEffect(() => {
+    if (tab !== "files" || !sessionId) return;
+    setFilesError(null);
+    void loadCheckout();
+  }, [tab, sessionId, loadCheckout]);
+
+  function openRoutes() {
+    setRoutesPending(fileList === null);
+    void loadCheckout().finally(() => setRoutesPending(false));
+  }
+
+  useEffect(() => {
+    try {
+      rememberPath(window.sessionStorage, workspace.id, location);
+    } catch {
+      // A render without browser storage has nothing to restore on the next load.
+    }
+  }, [workspace.id, location]);
+
+  useEffect(() => {
+    if (!preview) return;
+    const onMessage = (event: MessageEvent) => {
+      const next = framedLocation(event, preview.origin);
+      if (next !== null) setLocation(next);
+    };
+    window.addEventListener("message", onMessage);
+    return () => window.removeEventListener("message", onMessage);
+  }, [preview]);
+
+  function navigate(next: string) {
+    setPath(next);
+    setLocation(next);
+    setLive(false);
+    // A fresh frame, so asking for the route it is already on still loads it.
+    setReloads((n) => n + 1);
+  }
+
+  async function selectFile(path: string) {
+    if (!sessionId) return;
+    latestFile.current = path;
+    setSelectedFile(path);
+    setOpenedFile("loading");
+    const res = await fetch(
+      apiUrl(
+        `/workspaces/${workspace.id}/code-sessions/${sessionId}/files/content?path=${encodeURIComponent(path)}`,
+      ),
+      { credentials: apiCredentials(), headers: apiHeaders() },
+    ).catch(() => null);
+    const body = res?.ok ? ((await res.json().catch(() => null)) as WorkspaceFile | null) : null;
+    if (latestFile.current === path) setOpenedFile(body);
+  }
+
+  useEffect(() => {
+    let cancelled = false;
+    setState({ kind: "loading" });
+    setBaseSha(null);
+    setHost({ phase: null, furthest: null, log: "", timedOut: false });
+    setPreview(null);
+    const stored = storedPreviewPath(workspace.id);
+    setPath(stored);
+    setLocation(stored);
+    setReloads(0);
+    setLive(false);
+    setDismissedRoute(null);
+    setFileList(null);
+    setRoutesPending(false);
+    setSelectedFile(null);
+    setOpenedFile(null);
+    latestFile.current = null;
+    void (async () => {
+      const res = await fetch(apiUrl(`/workspaces/${workspace.id}/code-sessions`), {
+        method: "POST",
+        credentials: apiCredentials(),
+        headers: {
+          "Content-Type": "application/json",
+          ...apiHeaders(),
+        },
+        body: JSON.stringify({ branch }),
+      });
+      if (cancelled) return;
+      if (res.status === 403) {
+        setState({ kind: "forbidden" });
+        return;
+      }
+      if (res.status === 422) {
+        const body = (await res.json().catch(() => ({}))) as { error?: string };
+        setState({
+          kind: "fail",
+          error: typeof body.error === "string" ? body.error : "unknown",
+        });
+        return;
+      }
+      if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        setState({ kind: "fail", error: text || `request failed: ${res.status}` });
+        return;
+      }
+      const body = (await res.json()) as { session?: { id?: string; baseSha?: string } };
+      const sessionId = body.session?.id;
+      setBaseSha(typeof body.session?.baseSha === "string" ? body.session.baseSha : null);
+      if (!sessionId) {
+        setState({ kind: "fail", error: "invalid response" });
+        return;
+      }
+      setState({ kind: "ready", sessionId });
+
+      const statusUrl = apiUrl(`/workspaces/${workspace.id}/code-sessions/${sessionId}/status`);
+      const deadline = Date.now() + HOST_WAIT_MS;
+      while (!cancelled && Date.now() < deadline) {
+        const polled = await fetch(statusUrl, {
+          credentials: apiCredentials(),
+          headers: apiHeaders(),
+        }).catch(() => null);
+        if (cancelled) return;
+        if (polled?.ok) {
+          const status = (await polled.json()) as { phase: HostPhase; log: string };
+          setHost((current) => ({
+            phase: status.phase,
+            furthest:
+              status.phase === "installing" || status.phase === "starting"
+                ? status.phase
+                : current.furthest,
+            log: status.log,
+            timedOut: false,
+          }));
+          if (status.phase === "ready") {
+            const entry = await requestPreview(workspace.id, sessionId);
+            if (cancelled) return;
+            if (entry) setPreview(entry);
+            else setState({ kind: "fail", error: "The preview could not be opened." });
+            return;
+          }
+          if (status.phase === "failed" || status.phase === "stopped") return;
+        }
+        await new Promise((resolve) => setTimeout(resolve, STATUS_POLL_MS));
+      }
+      if (!cancelled) setHost((current) => ({ ...current, timedOut: true }));
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [workspace.id, branch]);
+
+  async function bootAgain(id: string, openPath: string) {
+    setPath(openPath);
+    setLocation(openPath);
+    setReloads(0);
+    setPreview(null);
+    setHost({ phase: null, furthest: null, log: "", timedOut: false });
+    const statusUrl = apiUrl(`/workspaces/${workspace.id}/code-sessions/${id}/status`);
+    const deadline = Date.now() + HOST_WAIT_MS;
+    while (Date.now() < deadline) {
+      const polled = await fetch(statusUrl, {
+        credentials: apiCredentials(),
+        headers: apiHeaders(),
+      }).catch(() => null);
+      if (polled?.ok) {
+        const status = (await polled.json()) as { phase: HostPhase; log: string };
+        setHost((current) => ({
+          phase: status.phase,
+          furthest:
+            status.phase === "installing" || status.phase === "starting"
+              ? status.phase
+              : current.furthest,
+          log: status.log,
+          timedOut: false,
+        }));
+        if (status.phase === "ready") {
+          const entry = await requestPreview(workspace.id, id);
+          if (entry) setPreview(entry);
+          else setState({ kind: "fail", error: "The preview could not be opened." });
+          return;
+        }
+        if (status.phase === "failed" || status.phase === "stopped") return;
+      }
+      await new Promise((resolve) => setTimeout(resolve, STATUS_POLL_MS));
+    }
+    setHost((current) => ({ ...current, timedOut: true }));
+  }
+
+  async function onUpdateBranch() {
+    if (!sessionId || updating) return;
+    setUpdating(true);
+    try {
+      const result = await updateCodeSessionBranch(workspace.id, sessionId);
+      setBaseSha(result.baseSha);
+      await bootAgain(sessionId, location);
+    } catch {
+      // The checkout stayed on its commit, and the preview that is up stays up.
+    } finally {
+      setUpdating(false);
+      refreshEdits();
+    }
+  }
+
+  function onClearEdits() {
+    if (!sessionId || updating) return;
+    const confirmed = window.confirm(
+      "Clear the edit set? The files go back to this session's commit. The chat stays.",
+    );
+    if (!confirmed) return;
+    setUpdating(true);
+    void (async () => {
+      try {
+        await clearCodeSessionEdits(workspace.id, sessionId);
+        await bootAgain(sessionId, location);
+      } catch {
+        // The edit set is still there.
+      } finally {
+        setUpdating(false);
+        refreshEdits();
+      }
+    })();
+  }
+
+  async function openInNewTab() {
+    if (state.kind !== "ready") return;
+    // The iframe's cookie is partitioned under Studio, so a new tab needs its own ticket.
+    const tab = window.open("about:blank", "_blank");
+    const entry = await requestPreview(workspace.id, state.sessionId);
+    if (!tab) return;
+    if (!entry) {
+      tab.close();
+      return;
+    }
+    tab.opener = null;
+    tab.location.href = previewUrl(entry.entry, location);
+  }
+
+  const chatRoute = dismissedRoute === location ? null : location;
+  const viewed = chatRoute ? sessionDocument({ type: "route", slug: chatRoute }, models) : null;
+  const chatColumn =
+    state.kind === "ready" ? (
+      <div {...stylex.props(styles.chatHost)}>
+        <ChatSessionScope>
+          <ChatPanel fill />
+        </ChatSessionScope>
+      </div>
+    ) : null;
+
+  const screen = (
+    <CodeSessionScreen
+      models={models}
+      state={state}
+      host={host}
+      tab={tab}
+      onTab={setTab}
+      preview={preview}
+      path={path}
+      location={location}
+      onPath={navigate}
+      reloads={reloads}
+      live={live}
+      onReload={() => navigate(location)}
+      onOpen={() => void openInNewTab()}
+      routes={contentRoutes(models, fileList ?? [])}
+      routesPending={routesPending}
+      onOpenRoutes={openRoutes}
+      files={{
+        list: fileList,
+        error: filesError,
+        selected: selectedFile,
+        opened: openedFile,
+        onSelect: (path) => void selectFile(path),
+      }}
+      chat={chatColumn}
+      notice={
+        updating
+          ? null
+          : branchNoticeKind({
+              baseSha,
+              headSha: git?.head?.sha ?? null,
+              editCount,
+              foldPending,
+            })
+      }
+      noticeBusy={updating}
+      onUpdateBranch={() => void onUpdateBranch()}
+      onClearEdits={onClearEdits}
+      previewSize={previewSize}
+      onPreviewSize={(size) => {
+        setPreviewSize(size);
+        persistPreviewSize(size);
+      }}
+    />
+  );
+
+  if (state.kind !== "ready") return screen;
+  return (
+    <ChatProvider
+      workspaceId={workspace.id}
+      codeSessionId={state.sessionId}
+      route={chatRoute}
+      viewed={viewed}
+      onRouteDismiss={setDismissedRoute}
+      onCheckoutWrite={reloadPreview}
+      onTurnSettled={settleEdits}
+      startOpen
+    >
+      {screen}
+    </ChatProvider>
+  );
+}
+
+const hover = "@media (hover: hover)";
+
+const spin = stylex.keyframes({
+  from: { transform: "rotate(0deg)" },
+  to: { transform: "rotate(360deg)" },
+});
+
+const styles = stylex.create({
+  shell: {
+    display: "flex",
+    flex: 1,
+    minHeight: 0,
+    minWidth: 0,
+    backgroundColor: colors.bgApp,
+  },
+  chat: {
+    width: "360px",
+    flexShrink: 0,
+    display: "flex",
+    flexDirection: "column",
+    minHeight: 0,
+    borderRightWidth: 1,
+    borderRightStyle: "solid",
+    borderRightColor: colors.border,
+    backgroundColor: colors.bgSurface,
+    overflow: "hidden",
+  },
+  chatHost: {
+    display: "flex",
+    flex: 1,
+    flexDirection: "column",
+    minHeight: 0,
+  },
+  chatHeader: {
+    display: "flex",
+    alignItems: "center",
+    height: "44px",
+    boxSizing: "border-box",
+    paddingInline: space.lg,
+    borderBottomWidth: 1,
+    borderBottomStyle: "solid",
+    borderBottomColor: colors.border,
+  },
+  messages: {
+    flex: 1,
+    minHeight: 0,
+    overflow: "auto",
+    padding: space.lg,
+  },
+  lineList: {
+    display: "flex",
+    flexDirection: "column",
+    gap: space.sm,
+    margin: 0,
+    padding: 0,
+    listStyle: "none",
+  },
+  line: {
+    fontSize: type.sm,
+    lineHeight: 1.45,
+    color: colors.text,
+  },
+  userLine: {
+    alignSelf: "flex-end",
+    maxWidth: "85%",
+    paddingBlock: space.xs,
+    paddingInline: space.sm,
+    borderRadius: radius.md,
+    backgroundColor: colors.bgPanelInset,
+  },
+  composer: {
+    padding: space.md,
+  },
+  inputWrap: {
+    position: "relative",
+    borderWidth: 1,
+    borderStyle: "solid",
+    borderColor: colors.border,
+    borderRadius: radius.md,
+    backgroundColor: colors.bgInput,
+  },
+  input: {
+    display: "block",
+    width: "100%",
+    minHeight: "84px",
+    resize: "none",
+    boxSizing: "border-box",
+    font: "inherit",
+    fontSize: type.sm,
+    color: colors.text,
+    backgroundColor: "transparent",
+    borderWidth: 0,
+    outline: "none",
+    padding: space.sm,
+    paddingBottom: "36px",
+  },
+  send: {
+    position: "absolute",
+    right: space.sm,
+    bottom: space.sm,
+    display: "inline-flex",
+    alignItems: "center",
+    justifyContent: "center",
+    width: "26px",
+    height: "26px",
+    borderWidth: 0,
+    borderRadius: "999px",
+    cursor: { default: "pointer", ":disabled": "default" },
+    color: colors.textInverse,
+    backgroundColor: colors.text,
+    opacity: { default: 1, ":disabled": 0.3 },
+  },
+  notice: {
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "space-between",
+    gap: space.md,
+    paddingInline: space.md,
+    paddingBlock: space.sm,
+    borderBottomWidth: 1,
+    borderBottomStyle: "solid",
+    borderBottomColor: colors.border,
+    backgroundColor: colors.bgSurface,
+  },
+  noticeText: {
+    fontSize: type.sm,
+    color: colors.text,
+  },
+  noticeButton: {
+    flexShrink: 0,
+    font: "inherit",
+    fontSize: type.xs,
+    fontWeight: 500,
+    cursor: { default: "pointer", ":disabled": "default" },
+    paddingBlock: "4px",
+    paddingInline: space.sm,
+    borderWidth: 1,
+    borderStyle: "solid",
+    borderColor: colors.border,
+    borderRadius: radius.sm,
+    color: colors.text,
+    backgroundColor: colors.bgPanelInset,
+    opacity: { default: 1, ":disabled": 0.4 },
+  },
+  stage: {
+    display: "flex",
+    flex: 1,
+    flexDirection: "column",
+    minWidth: 0,
+    minHeight: 0,
+  },
+  toolbar: {
+    display: "grid",
+    gridTemplateColumns: "1fr minmax(0, 520px) 1fr",
+    alignItems: "center",
+    gap: space.md,
+    height: "44px",
+    boxSizing: "border-box",
+    paddingInline: space.md,
+    borderBottomWidth: 1,
+    borderBottomStyle: "solid",
+    borderBottomColor: colors.border,
+    backgroundColor: colors.bgSurface,
+  },
+  tabs: {
+    display: "inline-flex",
+    justifySelf: "start",
+    gap: "2px",
+    padding: "2px",
+    borderRadius: radius.md,
+    backgroundColor: colors.bgPanelInset,
+  },
+  tab: {
+    display: "inline-flex",
+    alignItems: "center",
+    gap: space.xs,
+    font: "inherit",
+    fontSize: type.xs,
+    fontWeight: 500,
+    cursor: "pointer",
+    paddingBlock: "4px",
+    paddingInline: space.sm,
+    borderWidth: 0,
+    borderRadius: radius.sm,
+    color: { default: colors.textMuted, [hover]: { default: null, ":hover": colors.text } },
+    backgroundColor: "transparent",
+  },
+  tabActive: {
+    color: colors.text,
+    backgroundColor: colors.bgSurface,
+    boxShadow: "0 1px 2px rgba(0, 0, 0, 0.08)",
+  },
+  address: {
+    display: "flex",
+    alignItems: "center",
+    gap: space.xs,
+    minWidth: 0,
+  },
+  sizeSwitch: {
+    justifySelf: "end",
+  },
+  addressTrigger: {
+    display: "flex",
+    flex: 1,
+    alignItems: "center",
+    gap: space.xs,
+    minWidth: 0,
+    height: "28px",
+    paddingInline: space.sm,
+    borderWidth: 0,
+    borderRadius: "999px",
+    font: "inherit",
+    textAlign: "left",
+    cursor: { default: "pointer", ":disabled": "default" },
+    color: { default: colors.textMuted, ":disabled": colors.textMuted },
+    backgroundColor: colors.bgPanelInset,
+  },
+  addressPath: {
+    flex: 1,
+    minWidth: 0,
+    overflow: "hidden",
+    textOverflow: "ellipsis",
+    whiteSpace: "nowrap",
+    fontFamily: type.mono,
+    fontSize: type.xs,
+    color: colors.text,
+  },
+  routeSearch: {
+    fontFamily: type.mono,
+    fontSize: type.xs,
+  },
+  routePopup: {
+    width: "var(--anchor-width)",
+    minWidth: "220px",
+    maxHeight: "min(320px, var(--available-height))",
+    display: "flex",
+    flexDirection: "column",
+    overflowY: "hidden",
+  },
+  routeList: {
+    minHeight: 0,
+    overflowY: "auto",
+  },
+  routeItem: {
+    fontFamily: type.mono,
+  },
+  iconButton: {
+    display: "inline-flex",
+    alignItems: "center",
+    justifyContent: "center",
+    flexShrink: 0,
+    width: "28px",
+    height: "28px",
+    borderWidth: 0,
+    borderRadius: radius.sm,
+    cursor: { default: "pointer", ":disabled": "default" },
+    color: { default: colors.textMuted, ":disabled": colors.border },
+    backgroundColor: {
+      default: "transparent",
+      [hover]: { default: null, ":hover:not(:disabled)": colors.bgHover },
+    },
+  },
+  canvas: {
+    position: "relative",
+    display: "flex",
+    flex: 1,
+    minWidth: 0,
+    minHeight: 0,
+    backgroundColor: colors.bgApp,
+  },
+  frame: {
+    flex: 1,
+    width: "100%",
+    minHeight: 0,
+    borderWidth: 0,
+    backgroundColor: "#fff",
+  },
+  frameIncoming: {
+    position: "absolute",
+    inset: 0,
+    opacity: 0,
+    pointerEvents: "none",
+  },
+  pending: {
+    position: "absolute",
+    inset: 0,
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "center",
+    gap: space.sm,
+    fontSize: type.sm,
+    color: colors.textMuted,
+    backgroundColor: colors.bgApp,
+  },
+  bootWrap: {
+    display: "flex",
+    flex: 1,
+    alignItems: "center",
+    justifyContent: "center",
+    padding: space.xl,
+  },
+  bootCard: {
+    display: "flex",
+    flexDirection: "column",
+    gap: space.md,
+    width: "100%",
+    maxWidth: "460px",
+    padding: space.xl,
+    borderWidth: 1,
+    borderStyle: "solid",
+    borderColor: colors.border,
+    borderRadius: radius.md,
+    backgroundColor: colors.bgSurface,
+  },
+  steps: {
+    display: "flex",
+    flexDirection: "column",
+    gap: space.sm,
+    margin: 0,
+    padding: 0,
+    listStyle: "none",
+  },
+  step: {
+    display: "flex",
+    alignItems: "center",
+    gap: space.sm,
+  },
+  stepLabel: {
+    fontSize: type.sm,
+    color: colors.text,
+  },
+  stepPending: {
+    color: colors.textMuted,
+  },
+  stepFailed: {
+    color: colors.danger,
+  },
+  mark: {
+    display: "inline-flex",
+    alignItems: "center",
+    justifyContent: "center",
+    flexShrink: 0,
+    width: "18px",
+    height: "18px",
+    boxSizing: "border-box",
+    borderRadius: "999px",
+  },
+  markDone: {
+    color: colors.textInverse,
+    backgroundColor: colors.success,
+  },
+  markFailed: {
+    color: colors.textInverse,
+    backgroundColor: colors.danger,
+  },
+  markPending: {
+    borderWidth: 1.5,
+    borderStyle: "solid",
+    borderColor: colors.border,
+  },
+  spinner: {
+    borderWidth: 2,
+    borderStyle: "solid",
+    borderColor: colors.border,
+    borderTopColor: colors.accent,
+    animationName: spin,
+    animationDuration: { default: "0.8s", "@media (prefers-reduced-motion: reduce)": "2.4s" },
+    animationTimingFunction: "linear",
+    animationIterationCount: "infinite",
+  },
+  log: {
+    margin: 0,
+    maxHeight: "200px",
+    overflow: "auto",
+    padding: space.sm,
+    borderRadius: radius.sm,
+    fontFamily: type.mono,
+    fontSize: "11px",
+    lineHeight: 1.5,
+    whiteSpace: "pre-wrap",
+    wordBreak: "break-word",
+    color: colors.textMuted,
+    backgroundColor: colors.bgPanelInset,
+  },
+  error: {
+    margin: 0,
+    color: colors.danger,
+    fontSize: type.sm,
+  },
+});