Skip to content
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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.tsx
index 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">