Python
Files explorer over session roots (UX-037)
Rohit C Prasad440606862916
diff --git a/surfaces/gui/e2e/files-explorer.spec.ts b/surfaces/gui/e2e/files-explorer.spec.tsnew file mode 100644index 00000000..f234ab8c--- /dev/null+++ b/surfaces/gui/e2e/files-explorer.spec.ts@@ -0,0 +1,28 @@+// UX-037: Files — an explorer over the session's roots behind the More fold. Each root+// opens in the artifact viewer (breadcrumb "Files"), whose folder listings click through+// to subfolders and files. Artifacts stays the curated scratch-only surface beside it.+import { expect } from "@playwright/test";+import { test } from "./fixtures";++test("Files lists the session roots and browses into a file", async ({ page }) => {+ await page.goto("/");+ await page.getByPlaceholder(/Ask the coworker/).fill("hello");+ await page.getByRole("button", { name: "Send" }).click();+ await expect(page.getByText(/Echo: hello/)).toBeVisible();++ // Behind More, collapsed by default like every section.+ await page.getByTestId("rail-more-toggle").click();+ await page.getByTestId("rail-toggle-files").click();+ const row = page.getByTestId("files-root-row").first();+ await expect(row).toContainText("scratch");+ await expect(row).toContainText("read-write");++ // Root → folder listing in the viewer, breadcrumb says Files.+ await row.click();+ await expect(page.getByTestId("artifact-folder")).toBeVisible();+ await expect(page.locator(".artifact-title")).toContainText("Files");++ // Drill into a file: the same viewer renders it.+ await page.getByRole("button", { name: /notes\.md/ }).click();+ await expect(page.locator(".artifact-md")).toContainText("hello from the explorer");+});diff --git a/surfaces/gui/e2e/fixtures.ts b/surfaces/gui/e2e/fixtures.tsindex 94c3e69f..7017c4c2 100644--- a/surfaces/gui/e2e/fixtures.ts+++ b/surfaces/gui/e2e/fixtures.ts@@ -1054,6 +1054,31 @@ export async function mockApi(page: import("@playwright/test").Page) {// an inline script that renders proof-of-execution, a parent-window escape attempt,// and an external subresource that must be CSP-blocked.if (/\/v1\/sessions\/[^/]+\/artifacts\/read$/.test(p)) {+ const reqPath = new URL(req.url()).searchParams.get("path") || "";+ // UX-037 Files: a session root (or subfolder) reads as a folder listing.+ const rootHit = roots.find((r) => reqPath === r.path);+ if (rootHit) {+ return json({+ ok: true,+ path: reqPath,+ kind: "folder",+ entries: [+ { name: "reports", dir: true, size: 0 },+ { name: "notes.md", dir: false, size: 128 },+ ],+ });+ }+ if (reqPath.endsWith("/reports")) {+ return json({+ ok: true,+ path: reqPath,+ kind: "folder",+ entries: [{ name: "security-review.html", dir: false, size: 2048 }],+ });+ }+ if (reqPath.endsWith("notes.md")) {+ return json({ ok: true, path: reqPath, kind: "markdown", content: "# Notes\n\nhello from the explorer" });+ }return json({ok: true,path: "reports/security-review.html",diff --git a/surfaces/gui/src/api.ts b/surfaces/gui/src/api.tsindex 6fa11f09..1384e6d2 100644--- a/surfaces/gui/src/api.ts+++ b/surfaces/gui/src/api.ts@@ -366,6 +366,9 @@ export interface ArtifactInfo {kind: "markdown" | "html" | "image" | "code" | "text" | string;size: number;modified_at: number;+ // Which rail surface opened it — drives the viewer's breadcrumb ("Artifacts" vs+ // "Files"). Absent = artifacts (UX-037).+ origin?: "artifacts" | "files";}export interface ArtifactContent {diff --git a/surfaces/gui/src/components/RightRail.tsx b/surfaces/gui/src/components/RightRail.tsxindex 0f1c1dd0..e8d354f9 100644--- a/surfaces/gui/src/components/RightRail.tsx+++ b/surfaces/gui/src/components/RightRail.tsx@@ -4,12 +4,14 @@ import pdfWorkerUrl from "pdfjs-dist/build/pdf.worker.min.mjs?url";import {getArtifacts,getJournalCases,+ getRoots,readArtifact,revealArtifact,type ArtifactContent,type ArtifactInfo,type Board,type JournalCase,+ type RootInfo,} from "../api";import type { SessionInfo, TodoItem } from "../types";import { AccessSection } from "./AccessSection";@@ -17,7 +19,7 @@ import { BoardSection } from "./BoardPanel";import { Icon } from "./Icon";import { Markdown, OPEN_ARTIFACT_EVENT } from "./Markdown";-type Panel = "progress" | "artifacts" | "board" | "journal" | "team";+type Panel = "progress" | "artifacts" | "board" | "journal" | "team" | "files";// Quiet file-type icons for the artifact list (the colored kind pills read as noisy).function kindIcon(kind: string): "file" | "fileCode" | "image" | "table" {@@ -115,6 +117,7 @@ export function RightRail({board: false,journal: false,team: false,+ files: false,});// Journal + Access sit behind a quiet "More" row (three primary sections max).const [moreOpen, setMoreOpen] = useState(false);@@ -140,6 +143,9 @@ export function RightRail({setMoreOpen(true);}, [openAccessKey]);const [artifacts, setArtifacts] = useState<ArtifactInfo[]>([]);+ // UX-037 Files: the session's roots (workspace/scratch/grants) — the entry points of+ // the file explorer. Fetched lazily when the More fold opens.+ const [rootDirs, setRootDirs] = useState<RootInfo[]>([]);const [journal, setJournal] = useState<JournalCase[]>([]);const [selected, setSelected] = useState<ArtifactInfo | null>(null);const [content, setContent] = useState<ArtifactContent | null>(null);@@ -151,6 +157,11 @@ export function RightRail({if (showArtifacts) refreshArtifacts();}, [active, sessionId, refreshKey, showArtifacts]);+ useEffect(() => {+ if (!active || !moreOpen) return;+ getRoots(sessionId).then(setRootDirs).catch(() => setRootDirs([]));+ }, [active, moreOpen, sessionId, refreshKey]);+// Journal cases surface only when a board exists — same visibility rule as the// Board section, so plain sessions carry zero team chrome.useEffect(() => {@@ -239,6 +250,7 @@ export function RightRail({kind: kindFromPath(path),size: 0,modified_at: 0,+ origin: selected?.origin,})}/>@@ -388,6 +400,52 @@ export function RightRail({</div></RailSection>)}+ {/* UX-037: Files — an explorer over the session's roots. Each root opens in+ the artifact viewer, whose folder listings already click through; the+ Artifacts section stays the curated scratch-only surface. */}+ {moreOpen && rootDirs.length > 0 && (+ <RailSection+ title="Files"+ count={String(rootDirs.length)}+ open={open.files}+ onToggle={() => setOpen({ ...open, files: !open.files })}+ >+ <div className="artifact-list" data-testid="files-roots">+ {rootDirs.map((r) => (+ <button+ className="artifact-row"+ key={r.path}+ data-testid="files-root-row"+ onClick={() =>+ setSelected({+ path: r.path,+ abs_path: r.path,+ name: r.label || r.path.split("/").pop() || r.path,+ kind: "folder",+ size: 0,+ modified_at: 0,+ origin: "files",+ })+ }+ title={r.path}+ >+ <span className="artifact-ico">+ <Icon name="folder" size={17} />+ </span>+ <span className="artifact-name">+ {r.label || r.path.split("/").pop() || r.path}+ <span className="artifact-row-meta">+ {r.writable ? "read-write" : "read-only"}+ {!r.exists ? " · missing" : ""}+ </span>+ </span>+ <span className="artifact-open">Browse</span>+ </button>+ ))}+ </div>+ </RailSection>+ )}+{/* §32: Access — the former Session-settings drawer, one section among peers.key: its data ownership resets with the conversation, like the old row did.Stays MOUNTED behind the More fold (hidden, not unmounted) so its openKey@@ -540,7 +598,7 @@ function ArtifactViewer({<Icon name="arrowLeft" size={16} /></button><div className="artifact-heading">- <div className="artifact-title"><span>Artifacts</span><span className="artifact-sep">/</span><span>{artifact.name}</span></div>+ <div className="artifact-title"><span>{artifact.origin === "files" ? "Files" : "Artifacts"}</span><span className="artifact-sep">/</span><span>{artifact.name}</span></div><div className="artifact-path">{artifact.path}</div></div><div className="rail-actions">