@rightkit/document-workspace 0.0.0-stage → 0.1.0

package/dist/app/sidebar/SidebarPathUtils.js

@@ -0,0 +1,55 @@
+import { toast } from "@rightkit/platform-ui/headless";
+import { writeClipboardText } from "@rightkit/document-core/state/tauriBridge";
+export function isLocalFileDoc(doc) {
+    return doc.format !== "web" && !doc.path.startsWith("untitled:");
+}
+export function pathFolder(path) {
+    const lastSlash = Math.max(path.lastIndexOf("\\"), path.lastIndexOf("/"));
+    return lastSlash <= 0 ? "" : path.slice(0, lastSlash);
+}
+export function pathBase(path) {
+    const lastSlash = Math.max(path.lastIndexOf("\\"), path.lastIndexOf("/"));
+    return lastSlash < 0 ? path : path.slice(lastSlash + 1);
+}
+export function pathSeparator(path) {
+    return path.includes("\\") ? "\\" : "/";
+}
+export function splitPath(path) {
+    return path.split(/[\\/]+/).filter(Boolean);
+}
+export function commonFolder(paths) {
+    if (paths.length < 2)
+        return pathFolder(paths[0] ?? "");
+    const sep = pathSeparator(paths[0]);
+    const dirs = paths.map((path) => splitPath(pathFolder(path)));
+    const first = dirs[0] ?? [];
+    const common = [];
+    for (let i = 0; i < first.length; i++) {
+        const part = first[i];
+        if (dirs.every((dir) => dir[i]?.toLowerCase() === part.toLowerCase()))
+            common.push(part);
+        else
+            break;
+    }
+    return common.join(sep);
+}
+export function relativePath(path, openLocalPaths) {
+    const base = commonFolder(openLocalPaths);
+    if (!base)
+        return pathBase(path);
+    const next = path.slice(base.length).replace(/^[\\/]+/, "");
+    return next || pathBase(path);
+}
+export function breadcrumbPath(path) {
+    return splitPath(path).join(" > ");
+}
+export async function copyText(text) {
+    try {
+        await writeClipboardText(text);
+        toast("Copied to clipboard", "success");
+    }
+    catch {
+        // Clipboard can reject (permissions / no focus) — don't leak an unhandled rejection.
+        toast("Couldn't copy to clipboard", "error");
+    }
+}

package/dist/app/sidebar/SidebarPrimitives.d.ts

@@ -0,0 +1,12 @@
+export declare const menuItemClass = "vr-press vr-focus flex w-full items-center px-3 py-1.5 text-left font-sans text-sm text-paper/85 hover:bg-ink/50 hover:text-paper focus-visible:bg-ink/50 focus-visible:text-paper";
+export declare const compactMenuItemClass = "vr-press vr-focus flex w-full items-center px-2.5 py-1 text-left font-sans text-xs text-paper/85 hover:bg-ink/50 hover:text-paper focus-visible:bg-ink/50 focus-visible:text-paper";
+/** Classes every shell-menu panel in the sidebar shares (the glass panel; position comes from the shell). */
+export declare const menuPanelClass = "vr-pop no-print vr-glass-panel overflow-hidden rounded-lg";
+export declare function Popover({ onClose, className, children, role, ariaModal, ariaLabel, }: {
+    onClose: () => void;
+    className: string;
+    children: React.ReactNode;
+    role?: "menu" | "dialog";
+    ariaModal?: boolean;
+    ariaLabel?: string;
+}): import("react").JSX.Element;

package/dist/app/sidebar/SidebarPrimitives.js

@@ -0,0 +1,45 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Shared small presentational pieces reused by the sidebar's popovers (the tab overview) and by the collapsed rail / expanded header icon buttons.
+// Extracted verbatim from Sidebar.tsx as part of the 2026-07-02 decomposition plan (V-K).
+import { useDismiss, useExitTransition, useFocusTrap, useListNavigation } from "@rightkit/platform-ui/headless";
+import { useEffect, useLayoutEffect, useRef, useState } from "react";
+const menuItems = (root) => [
+    ...(root?.querySelectorAll('[role="menuitem"]:not([disabled])') ?? []),
+];
+export const menuItemClass = "vr-press vr-focus flex w-full items-center px-3 py-1.5 text-left font-sans text-sm text-paper/85 hover:bg-ink/50 hover:text-paper focus-visible:bg-ink/50 focus-visible:text-paper";
+export const compactMenuItemClass = "vr-press vr-focus flex w-full items-center px-2.5 py-1 text-left font-sans text-xs text-paper/85 hover:bg-ink/50 hover:text-paper focus-visible:bg-ink/50 focus-visible:text-paper";
+/** Classes every shell-menu panel in the sidebar shares (the glass panel; position comes from the shell). */
+export const menuPanelClass = "vr-pop no-print vr-glass-panel overflow-hidden rounded-lg";
+export function Popover({ onClose, className, children, role = "menu", ariaModal, ariaLabel, }) {
+    const panelRef = useRef(null);
+    const backdropRef = useRef(null);
+    const exit = useExitTransition({ exitMs: 80, onClosed: onClose });
+    const close = () => void exit.close();
+    // Escape and backdrop press dismiss; focus lands on the first item and returns to the opener.
+    useDismiss(close, { outside: "click-target", backdrop: backdropRef });
+    useFocusTrap(panelRef, true, { autoFocus: false, trap: false });
+    const [count, setCount] = useState(0);
+    useLayoutEffect(() => {
+        const n = menuItems(panelRef.current).length;
+        if (n !== count)
+            setCount(n);
+    });
+    const nav = useListNavigation({
+        count,
+        role: "menu",
+        focusOwner: "list",
+        homeEnd: false,
+        activateKeys: [],
+        keepIndexOnItemsChange: true,
+    });
+    // biome-ignore lint/correctness/useExhaustiveDependencies: re-run once the items are counted so the first item takes focus on open
+    useEffect(() => {
+        menuItems(panelRef.current)[nav.activeIndex]?.focus();
+    }, [nav.activeIndex, count]);
+    const { onKeyDown } = nav.getListProps();
+    return (_jsxs(_Fragment, { children: [_jsx("div", { ref: backdropRef, className: "no-print fixed inset-0 z-30", "aria-hidden": "true" }), _jsx("div", { ref: panelRef, onKeyDown: onKeyDown, onFocus: (event) => {
+                    const at = menuItems(panelRef.current).indexOf(event.target);
+                    if (at >= 0)
+                        nav.setActiveIndex(at);
+                }, role: role, ...(role === "dialog" ? { "aria-modal": ariaModal, "aria-label": ariaLabel } : {}), className: `vr-pop vr-pop-menu-tr${exit.closing ? " vr-pop-exit" : ""} no-print vr-glass-panel absolute z-40 overflow-hidden rounded-lg py-1 ${className}`, children: children })] }));
+}

package/dist/app/sidebar/SidebarRail.d.ts

@@ -0,0 +1,5 @@
+import { type ReactNode } from "react";
+import type { SidebarProps } from "../Sidebar.js";
+export declare function SidebarRail({ activePath, recents, pinnedEntries, onActivate, onOpenRecent, onOpenPath, onClearRecents, onOpenDialog, onOpenUrl, onOpenClipboard, onNew, onOpenSettings, openPaths, setOpen, }: SidebarProps & {
+    setOpen: (open: boolean) => void;
+}): ReactNode;

package/dist/app/sidebar/SidebarRail.js

@@ -0,0 +1,37 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// The collapsed sidebar: a thin always-visible rail fused with the titlebar, so the everyday
+// actions never move into the tab strip. Top: expand, New (format/open menu), Recent. Middle:
+// pinned files (one tap opens). Bottom: Settings. Open documents stay in the titlebar tabs.
+import { useRef, useState } from "react";
+import { IconButton } from "@rightkit/react-shell/react";
+import { Gear } from "@phosphor-icons/react/dist/icons/Gear";
+import { FolderSimple } from "@phosphor-icons/react/dist/icons/FolderSimple";
+import { FileTypeIcon } from "../../documents/FileTypeIcon.js";
+import { shortcutLabel } from "@rightkit/document-core/platform";
+import { ClockIcon, PanelIcon, PlusIcon } from "./SidebarIcons.js";
+import { NewOpenMenu, RecentsMenu } from "./SidebarMenus.js";
+const RAIL_WIDTH = 52;
+export function SidebarRail({ activePath, recents, pinnedEntries, onActivate, onOpenRecent, onOpenPath, onClearRecents, onOpenDialog, onOpenUrl, onOpenClipboard, onNew, onOpenSettings, openPaths, setOpen, }) {
+    const [menu, setMenu] = useState(null);
+    const anchorRef = useRef(null);
+    const toggle = (which, button) => {
+        anchorRef.current = button;
+        setMenu((m) => (m === which ? null : which));
+    };
+    return (_jsxs("aside", { "data-vr-sidebar": "rail", "aria-label": "Sidebar", className: "no-print vr-chrome vr-sidebar-shell relative flex shrink-0 flex-col items-center bg-panel", style: { width: RAIL_WIDTH }, children: [_jsx("div", { "data-tauri-drag-region": true, className: "h-[52px] w-full shrink-0" }), _jsxs("div", { className: "flex flex-col items-center gap-1", children: [_jsx(RailButton, { label: `Show sidebar (${shortcutLabel("mod+\\")})`, onClick: () => setOpen(true), children: _jsx(PanelIcon, {}) }), _jsx(RailButton, { label: "New document", expanded: menu === "new", onClick: (button) => toggle("new", button), children: _jsx(PlusIcon, {}) }), _jsx(RailButton, { label: "Recent files", expanded: menu === "recents", onClick: (button) => toggle("recents", button), children: _jsx(ClockIcon, {}) })] }), pinnedEntries.length > 0 && (_jsxs(_Fragment, { children: [_jsx("span", { "aria-hidden": "true", className: "my-2 h-px w-6 shrink-0 bg-line" }), _jsx("nav", { "aria-label": "Pinned", className: "flex min-h-0 flex-1 flex-col items-center gap-1 overflow-y-auto overflow-x-hidden [direction:rtl] [&>*]:[direction:ltr]", children: pinnedEntries.map((pin) => {
+                            const isDir = pin.kind === "dir";
+                            const open = openPaths.has(pin.path);
+                            return (_jsx(RailButton, { label: pin.displayName, current: pin.path === activePath, onClick: () => {
+                                    // A pinned folder needs the explorer to browse it; a file opens directly.
+                                    if (isDir)
+                                        setOpen(true);
+                                    else if (open)
+                                        onActivate(pin.path);
+                                    else
+                                        onOpenPath(pin.path);
+                                }, children: isDir ? (_jsx(FolderSimple, { size: 16, weight: "regular", "aria-hidden": true })) : (_jsx(FileTypeIcon, { format: pin.format, path: pin.path, size: 16 })) }, pin.path));
+                        }) })] })), _jsx("span", { className: "flex-1" }), _jsx("div", { className: "mb-2 flex shrink-0 flex-col items-center", children: _jsx(RailButton, { label: "Settings", onClick: onOpenSettings, children: _jsx(Gear, { size: 15, weight: "regular" }) }) }), menu === "new" && (_jsx(NewOpenMenu, { anchor: anchorRef.current ?? undefined, onClose: () => setMenu(null), onNew: onNew, onOpenDialog: onOpenDialog, onOpenUrl: onOpenUrl, onOpenClipboard: onOpenClipboard })), menu === "recents" && (_jsx(RecentsMenu, { anchor: anchorRef.current ?? undefined, onClose: () => setMenu(null), recents: recents, onOpenRecent: (entry) => void onOpenRecent(entry), onClearRecents: onClearRecents }))] }));
+}
+function RailButton({ label, onClick, expanded, current, children, }) {
+    return (_jsx(IconButton, { label: label, onClick: (event) => onClick(event.currentTarget), "aria-expanded": expanded, "aria-current": current ? "page" : undefined, "data-vr-tooltip": label, "data-vr-tooltip-side": "right", className: `vr-icon-tooltip vr-press vr-focus flex h-9 w-9 shrink-0 items-center justify-center rounded-lg text-muted hover:bg-ink/40 hover:text-paper${expanded || current ? " bg-ink/40 text-paper" : ""}`, children: children }));
+}

package/dist/app/sidebar/explorer/ExplorerRowMenu.d.ts

@@ -0,0 +1,21 @@
+export interface ExplorerRowMenuState {
+    x: number;
+    y: number;
+    name: string;
+    path: string;
+    isDir: boolean;
+    /** Row kind ("dir" | format id | "other") — drives which items are offered. */
+    kind: string;
+    pinned: boolean;
+    /** Show Pin/Unpin. Hidden for "other" files: their paths carry no broker grant, so the backend
+     *  toggle_pin would refuse them anyway. */
+    canPin: boolean;
+    /** "Open" handler — expand for dirs, open/activate for files. Absent for "other" rows. */
+    onOpen?: () => void;
+}
+export declare function ExplorerRowMenu({ menu, onClose, onTogglePin, onTogglePinDir, }: {
+    menu: ExplorerRowMenuState;
+    onClose: () => void;
+    onTogglePin: (path: string) => void;
+    onTogglePinDir: (path: string, label: string) => void;
+}): import("react").JSX.Element;

package/dist/app/sidebar/explorer/ExplorerRowMenu.js

@@ -0,0 +1,37 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// Right-click / "…" context menu for explorer tree rows (locations, listing entries, pinned rows)
+// and recent rows: Open, Reveal in Finder/File Explorer, Pin/Unpin, Copy Path.
+// Same chrome as the document tab menu (SidebarDocumentMenu): the shell's ContextMenu with the
+// glass panel and compact rows.
+import { useMemo, useRef } from "react";
+import { ContextMenu } from "@rightkit/react-shell/react";
+import { explorerReveal } from "../../../state/explorer.js";
+import { isMac } from "@rightkit/document-core/platform";
+import { compactMenuItemClass, menuPanelClass } from "../SidebarPrimitives.js";
+import { copyText } from "../SidebarPathUtils.js";
+export function ExplorerRowMenu({ menu, onClose, onTogglePin, onTogglePinDir, }) {
+    // Callbacks (and menu.onOpen) change identity per render; items must not (exitMs treats a new
+    // items identity as a re-open), so run() reads the latest through a ref.
+    const cb = useRef({ onOpen: menu.onOpen, onTogglePin, onTogglePinDir });
+    cb.current = { onOpen: menu.onOpen, onTogglePin, onTogglePinDir };
+    const { path, name, isDir, pinned, canPin } = menu;
+    const hasOpen = !!menu.onOpen;
+    const items = useMemo(() => [
+        ...(hasOpen ? [{ id: "open", label: "Open", run: () => cb.current.onOpen?.() }] : []),
+        { id: "reveal", label: isMac() ? "Reveal in Finder" : "Reveal in File Explorer", run: () => explorerReveal(path) },
+        ...(canPin
+            ? [
+                {
+                    id: "pin",
+                    label: pinned ? "Unpin" : "Pin",
+                    run: () => (isDir ? cb.current.onTogglePinDir(path, name) : cb.current.onTogglePin(path)),
+                },
+            ]
+            : []),
+        { id: "copy-path", label: "Copy Path", separatorBefore: true, run: () => copyText(path) },
+    ], [hasOpen, path, name, isDir, pinned, canPin]);
+    return (_jsx(ContextMenu, { x: menu.x, y: menu.y, items: items, onClose: onClose, label: `${menu.name} options`, width: 224, itemAs: "button", showLead: false, renderItem: (item) => item.label, className: `${menuPanelClass} overflow-y-auto py-0.5`, scrimClassName: "no-print", exitMs: 80, exitClassName: "vr-pop-exit", slots: {
+            item: `${compactMenuItemClass} [&.is-active]:bg-ink/50 [&.is-active]:text-paper`,
+            separator: "my-1 h-px bg-line",
+        } }));
+}

package/dist/app/sidebar/explorer/ExplorerSections.d.ts

@@ -0,0 +1,16 @@
+import type { FileEntry, PinEntry } from "../../../state/library.js";
+export interface ExplorerSectionsProps {
+    searchQuery?: string;
+    activePath: string | null;
+    openPaths: ReadonlySet<string>;
+    recents: FileEntry[];
+    pinnedPaths: ReadonlySet<string>;
+    pinnedEntries: PinEntry[];
+    onActivate: (path: string) => void;
+    onOpenRecent: (entry: FileEntry) => Promise<unknown> | undefined;
+    onOpenPath: (path: string) => void;
+    onTogglePin: (path: string) => void;
+    onTogglePinDir: (path: string, label: string) => void;
+    onClearRecents: () => void;
+}
+export declare function ExplorerSections({ searchQuery, activePath, openPaths, recents, pinnedPaths, pinnedEntries, onActivate, onOpenRecent, onOpenPath, onTogglePin, onTogglePinDir, onClearRecents, }: ExplorerSectionsProps): import("react").JSX.Element;

package/dist/app/sidebar/explorer/ExplorerSections.js

@@ -0,0 +1,259 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// The explorer sidebar body: three collapsible sections — Pinned (dirs first, then files;
+// pinned dirs expand like tree nodes), Recent (first 5 + "Show more…"), and Locations (the lazy
+// directory tree) — inside the sidebar's outer-left-scrollbar nav. Owns section open/closed state,
+// the persisted explorer record, active-file reveal, and the row context menu.
+import { useCallback, useEffect, useMemo, useRef, useState, } from "react";
+import { CaretDown } from "@phosphor-icons/react/dist/icons/CaretDown";
+import { FileTypeIcon } from "../../../documents/FileTypeIcon.js";
+import { baseName, formatFromPath } from "@rightkit/document-core/documents/types";
+import { explorerLocations } from "../../../state/explorer.js";
+import { ancestorDirs, explorerPersistedSync, loadExplorerPersisted, pathInside, saveExplorerPersisted, } from "./explorerState.js";
+import { ExplorerTree, useExplorerTree } from "./ExplorerTree.js";
+import { ExplorerRowMenu } from "./ExplorerRowMenu.js";
+const RECENT_LIMIT = 5;
+function Section({ id, label, count, open, onToggle, children, }) {
+    const bodyId = `vr-x-sec-${id}`;
+    return (_jsxs("div", { className: `vr-x-sec${open ? "" : " closed"}`, children: [_jsxs("button", { type: "button", className: "vr-x-sec-h vr-press", "aria-expanded": open, "aria-controls": bodyId, onClick: () => onToggle(id), children: [_jsx(CaretDown, { size: 10, weight: "regular", className: "vr-x-sec-caret", "aria-hidden": true }), _jsx("span", { className: "vr-x-sec-label", children: label }), count != null && count > 0 && _jsx("span", { className: "vr-x-sec-count", children: count })] }), _jsx("div", { id: bodyId, className: "vr-x-sec-b", children: children })] }));
+}
+export function ExplorerSections({ searchQuery = "", activePath, openPaths, recents, pinnedPaths, pinnedEntries, onActivate, onOpenRecent, onOpenPath, onTogglePin, onTogglePinDir, onClearRecents, }) {
+    const tree = useExplorerTree(activePath);
+    const [locations, setLocations] = useState([]);
+    const [sections, setSections] = useState({
+        pinned: true,
+        recent: true,
+        locations: true,
+    });
+    const [hydrated, setHydrated] = useState(false);
+    const [showAllRecent, setShowAllRecent] = useState(false);
+    const [menu, setMenu] = useState(null);
+    const [revealPath, setRevealPath] = useState(null);
+    const scrollRef = useRef(null);
+    const scrollRestored = useRef(false);
+    const hydratedRef = useRef(false);
+    const revealAttempts = useRef(0);
+    // Initial load: location roots + the persisted explorer record (sections + expanded dirs).
+    useEffect(() => {
+        let live = true;
+        void Promise.all([explorerLocations(), loadExplorerPersisted()]).then(([locs, persisted]) => {
+            if (!live)
+                return;
+            setLocations(locs);
+            setSections(persisted.sections);
+            tree.expandPaths(persisted.expanded);
+            hydratedRef.current = true;
+            setHydrated(true);
+        });
+        return () => {
+            live = false;
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [tree.expandPaths]);
+    // Persist section + expansion changes (debounced inside saveExplorerPersisted); never write
+    // before hydration or the defaults would stomp the stored record.
+    useEffect(() => {
+        if (!hydratedRef.current)
+            return;
+        saveExplorerPersisted({ sections });
+    }, [sections]);
+    useEffect(() => {
+        if (!hydratedRef.current)
+            return;
+        saveExplorerPersisted({ expanded: [...tree.expanded] });
+    }, [tree.expanded]);
+    // Restore scroll position once, after hydration.
+    useEffect(() => {
+        if (!hydrated || scrollRestored.current)
+            return;
+        scrollRestored.current = true;
+        const el = scrollRef.current;
+        const persisted = explorerPersistedSync();
+        if (el && persisted.scroll > 0)
+            el.scrollTop = persisted.scroll;
+    }, [hydrated]);
+    const onScroll = useCallback((e) => {
+        if (searchQuery.trim())
+            return;
+        saveExplorerPersisted({ scroll: Math.round(e.currentTarget.scrollTop) });
+    }, [searchQuery]);
+    const toggleSection = useCallback((id) => {
+        setSections((prev) => ({ ...prev, [id]: !prev[id] }));
+    }, []);
+    // Supported files: focus the tab when already open, else open through the broker-granted path.
+    const activateFile = useCallback((path) => {
+        if (openPaths.has(path))
+            onActivate(path);
+        else
+            onOpenPath(path);
+    }, [openPaths, onActivate, onOpenPath]);
+    const activateNode = useCallback((node) => activateFile(node.path), [activateFile]);
+    const openMenu = useCallback((node, x, y) => {
+        const isDir = node.kind === "dir";
+        setMenu({
+            x,
+            y,
+            name: node.name,
+            path: node.path,
+            isDir,
+            kind: node.kind === "file" ? (node.format ?? "file") : node.kind,
+            pinned: pinnedPaths.has(node.path),
+            canPin: node.kind !== "other",
+            onOpen: isDir
+                ? () => tree.expandDir(node.path)
+                : node.kind === "file"
+                    ? () => activateFile(node.path)
+                    : undefined,
+        });
+    }, [pinnedPaths, tree, activateFile]);
+    const openRecentMenu = useCallback((entry, x, y) => {
+        setMenu({
+            x,
+            y,
+            name: entry.displayName,
+            path: entry.token,
+            isDir: false,
+            kind: entry.format,
+            pinned: pinnedPaths.has(entry.token),
+            canPin: true,
+            onOpen: () => void onOpenRecent(entry),
+        });
+    }, [pinnedPaths, onOpenRecent]);
+    // Root specs.
+    const locationRoots = useMemo(() => locations.map((l) => ({
+        path: l.dir,
+        name: l.label,
+        kind: "dir",
+        icon: l.kind,
+    })), [locations]);
+    const pinnedRoots = useMemo(() => pinnedEntries.map((p) => p.kind === "dir"
+        ? { path: p.path, name: p.displayName, kind: "dir" }
+        : { path: p.path, name: p.displayName, kind: "file", format: p.format }), [pinnedEntries]);
+    const expandPaths = tree.expandPaths;
+    // Active-file reveal: expand the ancestor chain under whichever location contains the file,
+    // then scroll the row into view once it exists. Expansion is keyed on dir paths, so the chain
+    // can be expanded before any level has finished listing.
+    useEffect(() => {
+        if (!activePath || locations.length === 0) {
+            setRevealPath(null);
+            return;
+        }
+        const root = locations.find((l) => pathInside(l.dir, activePath));
+        if (!root) {
+            setRevealPath(null);
+            return;
+        }
+        expandPaths(ancestorDirs(activePath, root.dir));
+        revealAttempts.current = 0;
+        setRevealPath(activePath);
+        // Keyed on the active file only: depending on the whole tree object re-ran this on every
+        // expand/collapse and re-opened the active file's folders the moment the user closed them.
+    }, [activePath, locations, expandPaths]);
+    // Whenever the tree changes (children listed, dirs expanded), try to land the reveal scroll.
+    // biome-ignore lint/correctness/useExhaustiveDependencies: tree.dirs/tree.expanded are deliberate triggers — the reveal retries scrollIntoView as lazy listings land
+    useEffect(() => {
+        if (!revealPath)
+            return;
+        const el = scrollRef.current;
+        if (!el)
+            return;
+        const rows = el.querySelectorAll("[data-vr-tree-path]");
+        for (const row of rows) {
+            if (row.dataset.vrTreePath === revealPath) {
+                row.scrollIntoView?.({ block: "nearest" });
+                setRevealPath(null);
+                return;
+            }
+        }
+        // The row may appear only after several lazy listings; don't retry forever.
+        revealAttempts.current += 1;
+        if (revealAttempts.current > 12)
+            setRevealPath(null);
+    }, [revealPath, tree.dirs, tree.expanded]);
+    // A pinned file never appears in Recent again — one row per file, Pinned wins.
+    const recentFiles = useMemo(() => recents.filter((r) => !pinnedPaths.has(r.token)), [recents, pinnedPaths]);
+    const visibleRecents = showAllRecent ? recentFiles : recentFiles.slice(0, RECENT_LIMIT);
+    // Filename search reuses known broker entries; it never reads document contents.
+    const searchResults = useMemo(() => {
+        const files = new Map();
+        for (const pin of pinnedEntries) {
+            if (pin.kind !== "file")
+                continue;
+            files.set(pin.path, {
+                path: pin.path,
+                name: pin.displayName,
+                format: pin.format,
+                open: () => activateFile(pin.path),
+            });
+        }
+        for (const entry of recents) {
+            const path = entry.displayPath ?? entry.token;
+            if (files.has(path))
+                continue;
+            files.set(path, {
+                path,
+                name: entry.displayName,
+                format: entry.format,
+                open: () => (openPaths.has(path) ? onActivate(path) : void onOpenRecent(entry)),
+            });
+        }
+        for (const listing of tree.dirs.values()) {
+            for (const entry of listing.entries) {
+                if (entry.kind === "dir" || entry.kind === "other" || files.has(entry.path))
+                    continue;
+                files.set(entry.path, {
+                    path: entry.path,
+                    name: entry.name,
+                    format: entry.kind,
+                    open: () => activateFile(entry.path),
+                });
+            }
+        }
+        for (const path of openPaths) {
+            if (files.has(path) || path.startsWith("untitled:") || path.startsWith("web:"))
+                continue;
+            files.set(path, {
+                path,
+                name: baseName(path),
+                format: formatFromPath(path),
+                open: () => onActivate(path),
+            });
+        }
+        const query = searchQuery.trim().toLocaleLowerCase();
+        return [...files.values()].filter((file) => file.name.toLocaleLowerCase().includes(query));
+    }, [
+        searchQuery,
+        pinnedEntries,
+        recents,
+        tree.dirs,
+        openPaths,
+        activateFile,
+        onActivate,
+        onOpenRecent,
+    ]);
+    // The active file gets exactly ONE highlighted row: the first section that contains it
+    // (Pinned → Recent → Locations). Later occurrences fall back to the plain "open in a
+    // tab" dot the rows already render for openPaths.
+    const activeInPinned = !!activePath &&
+        pinnedEntries.some((p) => p.path === activePath || (p.kind === "dir" && pathInside(p.path, activePath)));
+    const activeInRecent = !!activePath && recentFiles.some((r) => r.token === activePath);
+    const pinnedActivePath = activeInPinned ? activePath : null;
+    const recentActivePath = !activeInPinned && activeInRecent ? activePath : null;
+    const locationsActivePath = !activeInPinned && !activeInRecent ? activePath : null;
+    const onRecentKey = (entry) => (e) => {
+        if (e.key !== "Enter" && e.key !== " ")
+            return;
+        e.preventDefault();
+        void onOpenRecent(entry);
+    };
+    return (_jsxs("nav", { ref: scrollRef, "aria-label": "Files", "data-vr-sidebar-explorer": true, onScroll: onScroll, className: "vr-explorer min-h-0 flex-1 overflow-x-hidden overflow-y-auto font-sans text-paper [direction:rtl] [&>*]:[direction:ltr]", children: [searchQuery.trim() ? (_jsxs("div", { "data-vr-document-search-results": true, children: [_jsx("p", { className: "vr-x-empty", role: "status", children: searchResults.length
+                            ? `${searchResults.length} ${searchResults.length === 1 ? "document" : "documents"}`
+                            : "No matching documents" }), searchResults.map((file) => (_jsxs("button", { type: "button", title: file.path, "data-vr-document-search-path": file.path, "aria-current": file.path === activePath || undefined, className: `vr-x-row vr-x-lrow w-full text-left${file.path === activePath ? " vr-x-sel" : ""}`, onClick: file.open, children: [_jsx("span", { className: "vr-x-caret", "aria-hidden": true }), _jsx("span", { className: "vr-x-icn", "aria-hidden": true, children: _jsx(FileTypeIcon, { format: file.format, path: file.path, size: 14 }) }), _jsx("span", { className: "vr-x-name", children: file.name })] }, file.path)))] })) : (_jsxs(_Fragment, { children: [pinnedRoots.length > 0 && (_jsx(Section, { id: "pinned", label: "Pinned", count: pinnedEntries.length, open: sections.pinned, onToggle: toggleSection, children: _jsx(ExplorerTree, { ariaLabel: "Pinned", roots: pinnedRoots, tree: tree, activePath: pinnedActivePath, openPaths: openPaths, onActivateRow: activateNode, onOpenMenu: openMenu }) })), _jsx(Section, { id: "recent", label: "Recent", count: recentFiles.length, open: sections.recent, onToggle: toggleSection, children: recentFiles.length === 0 ? (_jsx("div", { className: "vr-x-empty", children: "No recent files" })) : (_jsxs(_Fragment, { children: [visibleRecents.map((r) => {
+                                    const open = r.token !== recentActivePath && openPaths.has(r.token);
+                                    return (_jsxs("div", { role: "button", tabIndex: 0, title: r.token, "aria-label": r.displayName, "aria-description": open ? `${r.token} (open in a tab)` : r.token, "data-vr-recent-path": r.token, "aria-current": r.token === recentActivePath || undefined, className: `vr-x-row vr-x-lrow${r.token === recentActivePath ? " vr-x-sel" : ""}`, onClick: () => void onOpenRecent(r), onKeyDown: onRecentKey(r), onContextMenu: (e) => {
+                                            e.preventDefault();
+                                            openRecentMenu(r, e.clientX, e.clientY);
+                                        }, children: [_jsx("span", { className: "vr-x-caret", "aria-hidden": true }), _jsx("span", { className: "vr-x-icn", "aria-hidden": true, children: _jsx(FileTypeIcon, { format: r.format, path: r.token, size: 14 }) }), _jsx("span", { className: "vr-x-name", children: r.displayName }), open && _jsx("span", { className: "vr-x-open", title: "Open in a tab", "aria-hidden": true })] }, r.token));
+                                }), recentFiles.length > RECENT_LIMIT && (_jsx("button", { type: "button", className: "vr-x-more vr-press vr-focus", onClick: () => setShowAllRecent((v) => !v), children: showAllRecent
+                                        ? "Show less"
+                                        : `Show ${recentFiles.length - RECENT_LIMIT} more…` })), _jsx("button", { type: "button", className: "vr-x-more vr-press vr-focus", onClick: onClearRecents, children: "Clear recent files" })] })) }), _jsx(Section, { id: "locations", label: "Locations", open: sections.locations, onToggle: toggleSection, children: locationRoots.length === 0 ? (_jsx("div", { className: "vr-x-empty", children: "No locations" })) : (_jsx(ExplorerTree, { ariaLabel: "Locations", roots: locationRoots, tree: tree, activePath: locationsActivePath, revealPath: revealPath, openPaths: openPaths, onActivateRow: activateNode, onOpenMenu: openMenu })) })] })), menu && (_jsx(ExplorerRowMenu, { menu: menu, onClose: () => setMenu(null), onTogglePin: onTogglePin, onTogglePinDir: onTogglePinDir }))] }));
+}

package/dist/app/sidebar/explorer/ExplorerTree.d.ts

@@ -0,0 +1,46 @@
+import { type ExplorerEntry } from "../../../state/explorer.js";
+/** A node the tree can render: a root (location / pinned dir / pinned file) or a listing entry. */
+export interface ExplorerNodeSpec {
+    path: string;
+    name: string;
+    kind: "dir" | "file" | "other";
+    /** Format id for file rows (FileTypeIcon); undefined for dirs/others. */
+    format?: string;
+    /** Location kind ("home", "desktop", …) driving the root icon; undefined for plain dirs. */
+    icon?: string;
+}
+export interface ExplorerDirListing {
+    status: "loading" | "ready" | "error";
+    entries: ExplorerEntry[];
+    truncated: boolean;
+    message?: string;
+}
+export interface ExplorerTreeApi {
+    /** Dir paths currently expanded (persisted under vr.explorer.v1). */
+    expanded: ReadonlySet<string>;
+    /** dir path → latest listing state. */
+    dirs: ReadonlyMap<string, ExplorerDirListing>;
+    expandDir: (path: string) => void;
+    collapseDir: (path: string) => void;
+    toggleDir: (path: string) => void;
+    expandPaths: (paths: Iterable<string>) => void;
+    /** Force a re-list of a dir (watcher events; also retries after an error). */
+    relistDir: (path: string) => void;
+}
+/** `wantedPath` is the active file; a folder on its way is listed with the next segment's name so
+ *  the backend keeps that row even past its entry cap (otherwise the reveal stops at that folder). */
+export declare function useExplorerTree(wantedPath?: string | null): ExplorerTreeApi;
+/** One ARIA tree (roving tabindex, arrow keys) over a set of root nodes. Used for the Locations
+ *  section (roots = explorer_locations) and for the Pinned section (roots = pinned dirs+files). */
+export declare function ExplorerTree({ ariaLabel, roots, tree, activePath, revealPath, openPaths, onActivateRow, onOpenMenu, }: {
+    ariaLabel: string;
+    roots: ExplorerNodeSpec[];
+    tree: ExplorerTreeApi;
+    activePath: string | null;
+    /** File the sidebar is currently scrolling to (see ExplorerSections' active-file reveal). */
+    revealPath?: string | null;
+    openPaths: ReadonlySet<string>;
+    /** Leaf activation — supported file rows only (dirs toggle internally). */
+    onActivateRow: (node: ExplorerNodeSpec) => void;
+    onOpenMenu: (node: ExplorerNodeSpec, x: number, y: number) => void;
+}): import("react").JSX.Element;