@schlessera/brain-ui-react 0.35.0 → 0.37.0

package/src/components/files/file-panel.tsx

@@ -1,12 +1,29 @@
 import { Suspense, lazy, useEffect } from "react";
+import { Button, Label, Receipt, ScreenHeader } from "@schlessera/brain-ui-kit";
+import type { ReceiptRow } from "@schlessera/brain-ui-kit";
 import { ChevronDown, ChevronRight, X } from "lucide-react";
 import { useFileStore } from "../../stores/file-store.js";
+import { singleKey } from "../../lib/single-key.js";
+import { useUIStore } from "../../stores/ui-store.js";
 import { useDeferredUnmount } from "../../hooks/use-deferred-unmount.js";
+import { useMediaQuery } from "../../hooks/use-media-query.js";
+import { splitFrontmatter } from "../../lib/frontmatter.js";
 import { cn } from "../../lib/utils.js";
+import { formatSize } from "./file-viewer-frame.js";
+import { DisabledToggleRow } from "../graph/graph-form.js";
+import { STALE_AFTER_DAYS, ageInDays, formatAge } from "./staleness.js";
 
 /** Matches the `duration-300` slide-out below. */
 const SLIDE_OUT_MS = 300;
 
+/**
+ * The `laptop:` breakpoint from `theme.css`. From here up the rail is
+ * expanded and the design's D3 draws Files as panes beside it; below, the
+ * drawer. Read as a media query rather than a class pair so only one of the
+ * two shapes is mounted — two would mean two file trees on the store.
+ */
+const PANES_QUERY = "(min-width: 900px)";
+
 /**
  * The tree and the viewers load the first time the panel is opened. Together
  * they carry the markdown, HTML, image and PDF viewers, none of which the chat
@@ -20,6 +37,7 @@ export function FilePanel({ open, onClose }: { open: boolean; onClose: () => voi
   const treeExpanded = useFileStore((s) => s.treeExpanded);
   const setTreeExpanded = useFileStore((s) => s.setTreeExpanded);
   const closeFile = useFileStore((s) => s.closeFile);
+  const panes = useMediaQuery(PANES_QUERY);
 
   useEffect(() => {
     if (!open) return;
@@ -55,6 +73,10 @@ export function FilePanel({ open, onClose }: { open: boolean; onClose: () => voi
   const showContent = useDeferredUnmount(open, SLIDE_OUT_MS);
   const showTree = showContent && (!currentPath || treeExpanded);
 
+  if (panes) {
+    return open ? <FilePanes onClose={onClose} /> : null;
+  }
+
   return (
     <>
       {open && (
@@ -131,3 +153,149 @@ export function FilePanel({ open, onClose }: { open: boolean; onClose: () => voi
     </>
   );
 }
+
+/**
+ * D3 (the fifth design drop): from `laptop:` up Files is
+ * not a drawer but a layer of panes over the content area, beside the rail —
+ * a 300px tree, the reading pane at a 720px measure, and from `wide:` a
+ * 320px evidence rail. No backdrop: the rail stays reachable, and the layer
+ * is the app's own surface, not a sheet over it. The host still composes
+ * views, so this remains the same `FilePanel` the drawer is; only the shape
+ * changes with the width.
+ *
+ * The tree's title carries no document count: the file store has no total,
+ * and the design's `4,812 docs` is not something to make up.
+ *
+ * The footer prints the keys that fire. `j` / `k` are single-key letters
+ * and go with the Settings off switch (D37 — a key that does not fire is
+ * not advertised); `← →` and `⏎` are not letters, the switch does not
+ * cover them, and the kit `FileRow` binds them regardless — so they print
+ * regardless. `FileRow` already moves focus with ↑↓ and Home/End on its
+ * own, so nothing here binds movement a second time.
+ *
+ * The evidence rail (sixth pass §3a): each block is independent and simply
+ * absent when its data does not exist, but the COLUMN stays — "a pane count
+ * that changes as you click through files is a worse defect than a sparse
+ * rail." So the rail mounts with the panes, empty until a file is open, and
+ * a file with no frontmatter shows only the blocks it has.
+ */
+function FilePanes({ onClose }: { onClose: () => void }) {
+  const currentPath = useFileStore((s) => s.currentPath);
+  const content = useFileStore((s) => s.currentContent);
+  const singleKeyShortcuts = useUIStore((s) => s.singleKeyShortcuts);
+  const loaded = content !== null && content.path === currentPath ? content : null;
+
+  const frontmatter: ReceiptRow[] =
+    loaded?.kind === "markdown"
+      ? splitFrontmatter(loaded.content ?? "").fields.map((f) => ({
+          k: f.key,
+          v: f.list ? f.list.join(", ") : f.value || "—",
+        }))
+      : [];
+
+  // Stale (sixth pass §3b): `mtime` is on every file the server serves, in
+  // milliseconds; the threshold is `STALE_AFTER_DAYS`. Past it the block
+  // turns gold — the same tone the tree's dot wears.
+  const modified = loaded ? ageInDays(loaded.mtime) : null;
+  const stale = modified !== null && modified >= STALE_AFTER_DAYS;
+
+  return (
+    <div
+      role="dialog"
+      aria-label="Files"
+      className="fixed bottom-0 right-0 top-0 z-40 flex bg-surface tablet:left-[60px] laptop:left-[208px]"
+    >
+      {/* Tree */}
+      <aside className="flex w-[300px] shrink-0 flex-col border-r border-border">
+        <div className="shrink-0 px-4 pb-2 pt-4">
+          <h2 className="font-[family-name:var(--font-display)] text-[22px] leading-tight text-foreground">Files</h2>
+        </div>
+        {/* Untrusted only (sixth pass §3b): needs the provenance record —
+            origin, who, when — which no file carries yet. Drawn, disabled,
+            with its reason, never dropped: it is one of the two facts that
+            decide whether an answer may cite a file. */}
+        <div className="shrink-0 border-b border-border">
+          <DisabledToggleRow label="Untrusted only" reason="needs provenance" tone="purple" last />
+        </div>
+        {/* `j` / `k` move between tree items while one holds focus (D36:
+            focus-scoped, printed where they apply); the kit `FileRow` owns
+            ↑↓, Home, End and the ← → fold. */}
+        <div
+          className="min-h-0 flex-1 overflow-y-auto"
+          onKeyDown={(e) => {
+            if (!singleKeyShortcuts) return;
+            const key = singleKey(e);
+            if (key !== "j" && key !== "k") return;
+            const items = [...e.currentTarget.querySelectorAll<HTMLElement>('[role="treeitem"]')];
+            const here = items.indexOf(e.target as HTMLElement);
+            if (here === -1) return;
+            e.preventDefault();
+            items[(here + (key === "j" ? 1 : -1) + items.length) % items.length]?.focus();
+          }}
+        >
+          <Suspense fallback={null}>
+            <FileTree />
+          </Suspense>
+        </div>
+        <div className="shrink-0 border-t border-border px-4 py-2 font-[family-name:var(--font-mono)] text-[10px] text-muted-foreground">
+          {singleKeyShortcuts ? "j / k move · " : ""}← → fold · ⏎ open
+        </div>
+      </aside>
+
+      {/* Reading pane */}
+      <section className="flex min-w-0 flex-1 flex-col" aria-label={currentPath ?? "No file open"}>
+        <div className="flex shrink-0 items-start border-b border-border pr-3">
+          <div className="min-w-0 flex-1">
+            <ScreenHeader
+              variant="nav"
+              title={currentPath ?? "Files"}
+              subtitle={loaded ? formatSize(loaded.size) : undefined}
+              back={false}
+              divider={false}
+            />
+          </div>
+          <div className="shrink-0 pt-2">
+            <Button label="Close" icon="dismiss" tone="ghost" size="sm" block={false} onClick={onClose} />
+          </div>
+        </div>
+        <div className="min-h-0 flex-1 overflow-hidden">
+          <div className="mx-auto h-full w-full max-w-[720px]">
+            <Suspense fallback={null}>
+              <FileViewer />
+            </Suspense>
+          </div>
+        </div>
+      </section>
+
+      {/* Evidence rail, from `wide:` only (the four-pane rule, D37 §2).
+          Always in the tree once the panes are: the column never collapses. */}
+      <aside
+        aria-label="Evidence"
+        className="hidden w-[320px] shrink-0 flex-col gap-4 overflow-y-auto border-l border-border bg-background px-4 py-4 wide:flex"
+      >
+        {frontmatter.length > 0 && (
+          <div className="flex flex-col gap-2" data-rail-block="frontmatter">
+            <Label text="Frontmatter" icon="scope" meta={`${frontmatter.length} ${frontmatter.length === 1 ? "key" : "keys"}`} />
+            <Receipt rows={frontmatter} keyWidth={72} />
+          </div>
+        )}
+        {modified !== null && (
+          <div className="flex flex-col gap-2" data-rail-block="modified" data-stale={stale ? "" : undefined}>
+            <Label text="Modified" icon="history" tone={stale ? "gold" : undefined} meta={stale ? "stale" : undefined} />
+            <div
+              className={cn(
+                "font-[family-name:var(--font-mono)] text-[10px]",
+                stale ? "text-[var(--bk-gold-ink)]" : "text-muted-foreground"
+              )}
+            >
+              modified {formatAge(modified)} · {stale ? "stale past" : "stale after"} {STALE_AFTER_DAYS}
+            </div>
+          </div>
+        )}
+        {/* The design also draws "Linked from" (backlinks) and "Provenance"
+            (git hash, host, date) here. The app has no API for either yet,
+            so neither is drawn: an evidence rail shows what is known. */}
+      </aside>
+    </div>
+  );
+}

package/src/components/files/file-tree-view.tsx

@@ -0,0 +1,127 @@
+import { FileRow, Placeholder } from "@schlessera/brain-ui-kit";
+import type { FileKind } from "@schlessera/brain-ui-kit";
+import { useEffect, useRef, type ReactNode } from "react";
+import { cn } from "../../lib/utils.js";
+
+/**
+ * The file tree's rows, rendered from props (S7, the `files` directory). The
+ * design's `1e` screen draws the tree out of the kit's `FileRow` — folder,
+ * open folder, file, image — so that is what a row is here. `FileTree` is
+ * the container: it subscribes each node to the file store and decides
+ * expansion, loading, errors and the active path; these views decide how
+ * that looks.
+ *
+ * `TreeRow` is ONE row. The container renders it recursively so each node
+ * keeps its own store subscription (a change deep in one folder re-renders
+ * that row, not the tree); the children arrive as `children` already
+ * rendered. A highlighted row (the tree was asked to reveal this folder)
+ * scrolls itself into view and reports when the flash has run, so the
+ * container can clear the request.
+ */
+const IMAGE_EXT = new Set([".png", ".jpg", ".jpeg", ".gif", ".webp", ".svg", ".avif", ".bmp", ".ico"]);
+
+export function fileKind(name: string, isDir: boolean, expanded: boolean): FileKind {
+  if (isDir) return expanded ? "open" : "folder";
+  const i = name.lastIndexOf(".");
+  const ext = i >= 0 ? name.slice(i).toLowerCase() : "";
+  return IMAGE_EXT.has(ext) ? "image" : "file";
+}
+
+export interface TreeRowProps {
+  name: string;
+  kind: FileKind;
+  depth: number;
+  /** The row the viewer is on. */
+  active: boolean;
+  /** A folder whose listing is in flight. */
+  loading: boolean;
+  /** The tree was asked to reveal this folder: flash it, scroll it into view. */
+  highlighted: boolean;
+  /** A folder's listing failed; shown under the row with a retry. */
+  error?: string;
+  /**
+   * Days since the file was modified, given only when past the staleness
+   * threshold (`staleness.ts`). D3 draws it as the gold left-edge dot and
+   * the mono `stale 38d` meta, the same two marks the design's `1e` screen
+   * uses; the container decides from `mtime`, the row only prints.
+   */
+  staleDays?: number;
+  children?: ReactNode;
+  onClick: () => void;
+  onRetry?: () => void;
+  onHighlightShown?: () => void;
+  /**
+   * The kit `FileRow` binds → on a closed folder to `onFold(true)` and ← on
+   * an open one to `onFold(false)` (sixth pass §8: the ARIA tree pattern
+   * requires them, and the footer prints them). Folders only.
+   */
+  onFold?: (open: boolean) => void;
+}
+
+/** How long the reveal flash runs before the request is cleared. */
+export const HIGHLIGHT_MS = 1800;
+
+export function TreeRow(p: TreeRowProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const { highlighted, onHighlightShown } = p;
+  useEffect(() => {
+    if (!highlighted || !ref.current) return;
+    ref.current.scrollIntoView({ behavior: "smooth", block: "center" });
+    const t = setTimeout(() => onHighlightShown?.(), HIGHLIGHT_MS);
+    return () => clearTimeout(t);
+  }, [highlighted, onHighlightShown]);
+
+  return (
+    <li>
+      <div ref={ref} className={cn(highlighted && "brain-tree-highlight")}>
+        <FileRow
+          label={p.name}
+          kind={p.kind}
+          depth={p.depth}
+          active={p.active}
+          meta={p.loading ? "loading…" : p.staleDays !== undefined ? `stale ${p.staleDays}d` : undefined}
+          metaTone={!p.loading && p.staleDays !== undefined ? "gold" : undefined}
+          flag={p.staleDays !== undefined ? "gold" : undefined}
+          onClick={p.onClick}
+          onFold={p.onFold}
+        />
+      </div>
+      {p.error ? (
+        <div style={{ paddingLeft: 8 + (p.depth + 1) * 22 }} className="py-1 pr-2">
+          <FileRow view="error" stateMessage="Folder unreadable" stateDetail={p.error} stateAction="Retry" onStateAction={p.onRetry} />
+        </div>
+      ) : null}
+      {p.children ? <ul>{p.children}</ul> : null}
+    </li>
+  );
+}
+
+export interface FileTreeViewProps {
+  /** The root listing: `loading` before it arrives, `error` when it failed, `ready` with rows. */
+  state: "loading" | "error" | "ready";
+  error?: string;
+  children?: ReactNode;
+  onRetry?: () => void;
+}
+
+export function FileTreeView(p: FileTreeViewProps) {
+  if (p.state === "error") {
+    return (
+      <div className="px-3 py-2">
+        <Placeholder variant="error" message="Files unreadable" detail={p.error} actionLabel="Retry" onAction={p.onRetry} />
+      </div>
+    );
+  }
+  if (p.state === "loading") {
+    return (
+      <div className="px-3 py-2" aria-label="Loading files">
+        <Placeholder variant="loading" lines={4} bordered={false} pad={4} />
+      </div>
+    );
+  }
+  return (
+    <ul className="py-1 text-sm" role="tree">
+      {p.children}
+    </ul>
+  );
+}

package/src/components/files/file-tree.tsx

@@ -1,21 +1,15 @@
-import { useEffect, useRef } from "react";
-import { ChevronRight, Folder, FolderOpen, FileText, FileCode, FileImage, File as FileIcon, Loader2, AlertCircle } from "lucide-react";
+import { useCallback, useEffect } from "react";
 import { useFileStore } from "../../stores/file-store.js";
 import type { FileEntry } from "@schlessera/brain-ui-sdk/protocol";
-import { cn } from "../../lib/utils.js";
-
-const IMAGE_EXT = new Set([".png", ".jpg", ".jpeg", ".gif", ".webp", ".svg", ".avif", ".bmp", ".ico"]);
-const CODE_EXT = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".py", ".rb", ".go", ".rs", ".java", ".sh", ".bash", ".css", ".html", ".json", ".yaml", ".yml", ".toml", ".sql"]);
-
-function iconForFile(name: string) {
-  const i = name.lastIndexOf(".");
-  const ext = i >= 0 ? name.slice(i).toLowerCase() : "";
-  if (ext === ".md" || ext === ".markdown" || ext === ".txt") return FileText;
-  if (IMAGE_EXT.has(ext)) return FileImage;
-  if (CODE_EXT.has(ext)) return FileCode;
-  return FileIcon;
-}
+import { FileTreeView, TreeRow, fileKind } from "./file-tree-view.js";
+import { ageInDays, isStale } from "./staleness.js";
 
+/**
+ * The container (S7): every node subscribes to the file store for its own
+ * expansion, loading, error, active and highlight state, and renders a
+ * `TreeRow` with its children rendered the same way. The store owns the
+ * directory cache and the requests; the rows own nothing.
+ */
 export function FileTree() {
   const loadDir = useFileStore((s) => s.loadDir);
   const dirCache = useFileStore((s) => s.dirCache);
@@ -29,115 +23,67 @@ export function FileTree() {
 
   const rootEntries = dirCache[""];
   const rootError = dirErrors[""];
-
-  if (rootError) {
-    return (
-      <div className="flex items-start gap-2 px-4 py-3 text-xs text-destructive">
-        <AlertCircle className="h-4 w-4 shrink-0" />
-        <span>{rootError}</span>
-      </div>
-    );
-  }
-
-  if (!rootEntries) {
-    return (
-      <div className="flex items-center gap-2 px-4 py-3 text-xs text-muted-foreground">
-        <Loader2 className="h-3.5 w-3.5 animate-spin" />
-        Loading files...
-      </div>
-    );
-  }
+  const retryRoot = useCallback(() => void loadDir(""), [loadDir]);
 
   return (
-    <ul className="py-1 text-sm">
-      {rootEntries.map((entry) => (
+    <FileTreeView state={rootError ? "error" : rootEntries ? "ready" : "loading"} error={rootError} onRetry={retryRoot}>
+      {rootEntries?.map((entry) => (
         <TreeNode key={entry.path} entry={entry} depth={0} />
       ))}
-    </ul>
+    </FileTreeView>
   );
 }
 
 function TreeNode({ entry, depth }: { entry: FileEntry; depth: number }) {
-  const expanded = useFileStore((s) => s.expandedDirs.has(entry.path));
-  const loading = useFileStore((s) => s.loadingDirs.has(entry.path));
-  const childEntries = useFileStore((s) => (entry.type === "dir" ? s.dirCache[entry.path] : undefined));
-  const childError = useFileStore((s) => (entry.type === "dir" ? s.dirErrors[entry.path] : undefined));
+  const isDir = entry.type === "dir";
+  const expanded = useFileStore((s) => isDir && s.expandedDirs.has(entry.path));
+  const loading = useFileStore((s) => isDir && s.loadingDirs.has(entry.path));
+  const childEntries = useFileStore((s) => (isDir ? s.dirCache[entry.path] : undefined));
+  const childError = useFileStore((s) => (isDir ? s.dirErrors[entry.path] : undefined));
   const toggleDir = useFileStore((s) => s.toggleDir);
+  const loadDir = useFileStore((s) => s.loadDir);
   const openFile = useFileStore((s) => s.openFile);
   const isActive = useFileStore((s) => s.currentPath === entry.path);
-  const highlighted = useFileStore(
-    (s) => entry.type === "dir" && s.highlightedDir === entry.path
-  );
+  const highlighted = useFileStore((s) => isDir && s.highlightedDir === entry.path);
   const setHighlightedDir = useFileStore((s) => s.setHighlightedDir);
-  const dirBtnRef = useRef<HTMLButtonElement>(null);
-
-  useEffect(() => {
-    if (!highlighted || !dirBtnRef.current) return;
-    dirBtnRef.current.scrollIntoView({ behavior: "smooth", block: "center" });
-    const t = setTimeout(() => setHighlightedDir(null), 1800);
-    return () => clearTimeout(t);
-  }, [highlighted, setHighlightedDir]);
+  const clearHighlight = useCallback(() => setHighlightedDir(null), [setHighlightedDir]);
 
-  const indent = { paddingLeft: depth * 14 + 8 };
+  // Staleness is a fact about a FILE's content. A directory's mtime moves
+  // when an entry is added or removed, not when a note inside it changes,
+  // so a folder gets no dot: the design's gold folder (`context · stale
+  // 38d`) needs the newest child's mtime, which the tree only knows once
+  // that folder has been opened. The server sends `mtime` per entry; an
+  // older one without it draws nothing rather than guessing.
+  const staleDays =
+    !isDir && entry.mtime !== undefined && isStale(entry.mtime) ? ageInDays(entry.mtime) : undefined;
 
-  if (entry.type === "dir") {
-    return (
-      <li>
-        <button
-          ref={dirBtnRef}
-          onClick={() => void toggleDir(entry.path)}
-          className={cn(
-            "flex w-full items-center gap-1.5 rounded px-2 py-1 text-left text-foreground transition-colors hover:bg-surface-raised",
-            highlighted && "brain-tree-highlight"
-          )}
-          style={indent}
-          aria-expanded={expanded}
-        >
-          <ChevronRight
-            className={cn(
-              "h-3 w-3 shrink-0 text-muted-foreground transition-transform",
-              expanded && "rotate-90"
-            )}
-          />
-          {expanded ? (
-            <FolderOpen className="h-4 w-4 shrink-0 text-primary/80" />
-          ) : (
-            <Folder className="h-4 w-4 shrink-0 text-muted-foreground" />
-          )}
-          <span className="truncate">{entry.name}</span>
-          {loading && <Loader2 className="ml-auto h-3 w-3 animate-spin text-muted-foreground" />}
-        </button>
-        {expanded && (
-          <ul>
-            {childError && (
-              <li className="flex items-center gap-1.5 px-2 py-1 text-xs text-destructive" style={{ paddingLeft: (depth + 1) * 14 + 8 }}>
-                <AlertCircle className="h-3 w-3" /> {childError}
-              </li>
-            )}
-            {childEntries?.map((child) => (
-              <TreeNode key={child.path} entry={child} depth={depth + 1} />
-            ))}
-          </ul>
-        )}
-      </li>
-    );
-  }
+  // ← / → fold (sixth pass §8). The kit only calls `onFold(true)` on a closed
+  // folder and `onFold(false)` on an open one, but the guard keeps the store
+  // honest if a stale `kind` and the key disagree for a frame.
+  const fold = isDir
+    ? (open: boolean) => {
+        if (open !== expanded) void toggleDir(entry.path);
+      }
+    : undefined;
 
-  const Icon = iconForFile(entry.name);
   return (
-    <li>
-      <button
-        onClick={() => void openFile(entry.path)}
-        className={cn(
-          "flex w-full items-center gap-1.5 rounded px-2 py-1 text-left transition-colors hover:bg-surface-raised",
-          isActive ? "bg-surface-raised text-primary" : "text-foreground/90"
-        )}
-        style={indent}
-      >
-        <span className="h-3 w-3 shrink-0" />
-        <Icon className="h-3.5 w-3.5 shrink-0 text-muted-foreground" />
-        <span className="truncate">{entry.name}</span>
-      </button>
-    </li>
+    <TreeRow
+      name={entry.name}
+      kind={fileKind(entry.name, isDir, expanded)}
+      depth={depth}
+      active={isActive}
+      loading={loading}
+      highlighted={highlighted}
+      error={expanded ? childError : undefined}
+      staleDays={staleDays}
+      onClick={() => void (isDir ? toggleDir(entry.path) : openFile(entry.path))}
+      onRetry={() => void loadDir(entry.path)}
+      onHighlightShown={clearHighlight}
+      onFold={fold}
+    >
+      {expanded && childEntries?.length
+        ? childEntries.map((child) => <TreeNode key={child.path} entry={child} depth={depth + 1} />)
+        : undefined}
+    </TreeRow>
   );
 }

package/src/components/files/file-viewer-binary.tsx

@@ -1,11 +1,12 @@
 import { FileWarning, Download } from "lucide-react";
 import type { FileContentResponse } from "@schlessera/brain-ui-sdk/protocol";
-import { apiBase } from "../../lib/backend.js";
+import { useBrainUiRoot } from "../../root-context.js";
 import { ZoomableImage } from "../images/zoomable-image.js";
 
 export function FileViewerBinary({ content }: { content: FileContentResponse }) {
+  const root = useBrainUiRoot();
   const isImage = content.mime?.startsWith("image/");
-  const rawUrl = `${apiBase()}/files/content?path=${encodeURIComponent(content.path)}&raw=1`;
+  const rawUrl = `${root.apiBase()}/files/content?path=${encodeURIComponent(content.path)}&raw=1`;
 
   if (isImage) {
     const filename = content.path.split("/").pop() ?? content.path;

package/src/components/files/file-viewer-frame.tsx

@@ -0,0 +1,113 @@
+import { Callout, EmptyState, FilterRow, Placeholder } from "@schlessera/brain-ui-kit";
+import { Check, Copy, FolderOpen } from "lucide-react";
+import type { ReactNode } from "react";
+
+/**
+ * The viewer's chrome, rendered from props (S7): the toolbar over the file,
+ * and the three states the body can be in before there is a file to draw.
+ * `FileViewer` is the container — it reads the store, builds the share
+ * options (which need the root) and chooses the body renderer; this owns
+ * how the frame looks.
+ *
+ * The Preview / Raw switch is the kit's `FilterRow`: two pills, one
+ * selected, activation following focus, which is what a mode switch is.
+ * The reveal and copy controls stay native icon buttons (titled; the kit
+ * has no icon-only button) and the share menu arrives rendered.
+ */
+export type ViewMode = "preview" | "raw";
+
+export interface ViewerToolbarProps {
+  fileName: string;
+  fullPath: string;
+  size?: number;
+  mode: ViewMode;
+  /** Only markdown, HTML and standalone diagrams have a preview to switch to. */
+  previewAvailable: boolean;
+  copied: boolean;
+  /** The share menu, already built by the container; null when nothing shares. */
+  share: ReactNode;
+  onMode: (mode: ViewMode) => void;
+  onCopyPath: () => void;
+  onReveal: () => void;
+}
+
+export function ViewerToolbar(p: ViewerToolbarProps) {
+  return (
+    <div className="flex items-center gap-2 border-b border-border bg-surface px-4 py-2">
+      <button
+        type="button"
+        onClick={p.onReveal}
+        title="Reveal in tree"
+        className="rounded p-1 text-muted-foreground transition-colors hover:bg-surface-raised hover:text-foreground"
+      >
+        <FolderOpen className="h-3.5 w-3.5" />
+      </button>
+      <div className="min-w-0 flex-1">
+        <div className="truncate text-sm font-medium text-foreground" title={p.fullPath}>
+          {p.fileName}
+        </div>
+        <div className="truncate text-[10px] text-muted-foreground" title={p.fullPath}>
+          {p.fullPath}
+          {p.size !== undefined && <span className="ml-2">· {formatSize(p.size)}</span>}
+        </div>
+      </div>
+      <button
+        type="button"
+        onClick={p.onCopyPath}
+        title="Copy path"
+        className="rounded p-1.5 text-muted-foreground transition-colors hover:bg-surface-raised hover:text-foreground"
+      >
+        {p.copied ? <Check className="h-3.5 w-3.5" /> : <Copy className="h-3.5 w-3.5" />}
+      </button>
+      {p.share}
+      {p.previewAvailable && (
+        <div className="w-auto shrink-0">
+          <FilterRow
+            items={[
+              { label: "Preview", onClick: () => p.onMode("preview") },
+              { label: "Raw", onClick: () => p.onMode("raw") },
+            ]}
+            active={p.mode === "preview" ? 0 : 1}
+            mono={false}
+          />
+        </div>
+      )}
+    </div>
+  );
+}
+
+export function ViewerLoading() {
+  return (
+    <div className="px-6 py-6" aria-label="Loading file">
+      <Placeholder variant="loading" lines={5} bordered={false} pad={0} />
+    </div>
+  );
+}
+
+export function ViewerError({ message }: { message: string }) {
+  return (
+    <div className="m-4" role="alert">
+      <Callout tone="red" variant="banner" icon="failed" mono text={message} />
+    </div>
+  );
+}
+
+export function ViewerEmpty() {
+  return (
+    <EmptyState
+      variant="no-results"
+      icon="folder"
+      tone="neutral"
+      title="No file open"
+      body="Select a file from the tree to view it."
+      meta=""
+      minHeight={240}
+    />
+  );
+}
+
+export function formatSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / 1024 / 1024).toFixed(2)} MB`;
+}