@rightkit/document-workspace 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,387 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// The explorer directory tree: lazy one-level listing per expanded dir (explorer_list_dir),
+// non-recursive watches while a dir is expanded (explorer_watch_dir / explorer_unwatch_dir +
+// "explorer:changed" re-lists just that dir), ARIA tree semantics with roving tabindex and
+// arrow-key navigation, and the shared row chrome (caret, folder/format icon, name, "…" button).
+import { memo, useCallback, useEffect, useMemo, useRef, useState, } from "react";
+import { CaretDown } from "@phosphor-icons/react/dist/icons/CaretDown";
+import { CaretRight } from "@phosphor-icons/react/dist/icons/CaretRight";
+import { Cloud } from "@phosphor-icons/react/dist/icons/Cloud";
+import { Desktop } from "@phosphor-icons/react/dist/icons/Desktop";
+import { DotsThree } from "@phosphor-icons/react/dist/icons/DotsThree";
+import { DownloadSimple } from "@phosphor-icons/react/dist/icons/DownloadSimple";
+import { File } from "@phosphor-icons/react/dist/icons/File";
+import { FileText } from "@phosphor-icons/react/dist/icons/FileText";
+import { Folder } from "@phosphor-icons/react/dist/icons/Folder";
+import { HardDrives } from "@phosphor-icons/react/dist/icons/HardDrives";
+import { House } from "@phosphor-icons/react/dist/icons/House";
+import { FileTypeIcon } from "../../../documents/FileTypeIcon.js";
+import { explorerListDir, explorerUnwatchDir, explorerWatchDir, onExplorerChanged, } from "../../../state/explorer.js";
+import { parseHostError } from "@rightkit/document-core/state/tauriBridge";
+import { childNameOnPath, pathInside, rowKindOf } from "./explorerState.js";
+import { hostAppName } from "../../../appName.js";
+function explorerErrorMessage(e) {
+    // Commands reject with the typed {code,message} envelope (e.g. "permission_denied") — show its
+    // message inline in the tree rather than toasting or crashing.
+    return parseHostError(e).message;
+}
+/** `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 function useExplorerTree(wantedPath = null) {
+    const [expanded, setExpanded] = useState(() => new Set());
+    const [dirs, setDirs] = useState(() => new Map());
+    const expandedRef = useRef(expanded);
+    expandedRef.current = expanded;
+    const dirsRef = useRef(dirs);
+    dirsRef.current = dirs;
+    const wantedRef = useRef(wantedPath);
+    wantedRef.current = wantedPath;
+    // Synchronous guards so a double-fired effect (StrictMode) or rapid toggle can't double-list or
+    // double-watch a dir before the state update lands.
+    const watchedRef = useRef(new Set());
+    const loadingRef = useRef(new Set());
+    const setDir = useCallback((path, next) => {
+        setDirs((prev) => {
+            const m = new Map(prev);
+            m.set(path, next);
+            return m;
+        });
+    }, []);
+    const fetchDir = useCallback((path) => {
+        if (loadingRef.current.has(path))
+            return;
+        loadingRef.current.add(path);
+        const cur = dirsRef.current.get(path);
+        setDir(path, {
+            status: "loading",
+            entries: cur?.entries ?? [],
+            truncated: cur?.truncated ?? false,
+        });
+        void explorerListDir(path, childNameOnPath(path, wantedRef.current)).then((listing) => {
+            loadingRef.current.delete(path);
+            setDir(path, {
+                status: "ready",
+                // A folder never lists itself: a child carrying its parent's path (a link that
+                // resolves back to the folder) would make an expanded folder render inside itself
+                // without end.
+                entries: keepUnchangedEntries(dirsRef.current.get(path)?.entries, listing.entries.filter((e) => e.path !== path)),
+                truncated: listing.truncated,
+            });
+        }, (e) => {
+            loadingRef.current.delete(path);
+            setDir(path, {
+                status: "error",
+                entries: cur?.entries ?? [],
+                truncated: false,
+                message: explorerErrorMessage(e),
+            });
+        });
+    }, [setDir]);
+    /** List a dir on first expand; a later manual relistDir forces a fetch. */
+    const loadDir = useCallback((path) => {
+        const cur = dirsRef.current.get(path);
+        if (cur && cur.status !== "error")
+            return;
+        fetchDir(path);
+    }, [fetchDir]);
+    const watch = useCallback((path) => {
+        if (watchedRef.current.has(path))
+            return;
+        watchedRef.current.add(path);
+        void explorerWatchDir(path);
+    }, []);
+    const unwatch = useCallback((path) => {
+        if (!watchedRef.current.delete(path))
+            return;
+        void explorerUnwatchDir(path);
+    }, []);
+    const expandDir = useCallback((path) => {
+        setExpanded((prev) => {
+            if (prev.has(path))
+                return prev;
+            const next = new Set(prev);
+            next.add(path);
+            return next;
+        });
+        watch(path);
+        loadDir(path);
+    }, [watch, loadDir]);
+    const collapseDir = useCallback((path) => {
+        setExpanded((prev) => {
+            if (!prev.has(path))
+                return prev;
+            const next = new Set(prev);
+            next.delete(path);
+            return next;
+        });
+        unwatch(path);
+    }, [unwatch]);
+    const toggleDir = useCallback((path) => {
+        if (expandedRef.current.has(path))
+            collapseDir(path);
+        else
+            expandDir(path);
+    }, [expandDir, collapseDir]);
+    const expandPaths = useCallback((paths) => {
+        for (const p of paths)
+            expandDir(p);
+    }, [expandDir]);
+    // One global "explorer:changed" subscription: re-list only the changed dir, and only while it's
+    // expanded (its listing is on screen). On unmount, drop the listener and every dir watch.
+    useEffect(() => {
+        let live = true;
+        let un;
+        void onExplorerChanged((dir) => {
+            if (!live || !expandedRef.current.has(dir))
+                return;
+            fetchDir(dir);
+        }).then((unsub) => {
+            if (live)
+                un = unsub;
+            else
+                unsub();
+        });
+        return () => {
+            live = false;
+            un?.();
+            for (const w of watchedRef.current)
+                void explorerUnwatchDir(w);
+            watchedRef.current.clear();
+        };
+    }, [fetchDir]);
+    return useMemo(() => ({
+        expanded,
+        dirs,
+        expandDir,
+        collapseDir,
+        toggleDir,
+        expandPaths,
+        relistDir: fetchDir,
+    }), [expanded, dirs, expandDir, collapseDir, toggleDir, expandPaths, fetchDir]);
+}
+/** A re-list returns fresh objects for every entry. Keep the previous object for each entry that
+ *  did not change, so memoised rows skip it: a watched folder that changes constantly (a temp or
+ *  build directory) otherwise re-rendered every one of its rows on every change. */
+function keepUnchangedEntries(previous, next) {
+    if (!previous || previous.length === 0)
+        return next;
+    const byPath = new Map(previous.map((e) => [e.path, e]));
+    return next.map((e) => {
+        const old = byPath.get(e.path);
+        return old &&
+            old.name === e.name &&
+            old.kind === e.kind &&
+            old.modified === e.modified &&
+            old.size === e.size
+            ? old
+            : e;
+    });
+}
+/** Rows of a folder mount in batches of this size, one batch per frame, so expanding a folder
+ *  with thousands of entries never blocks the page in a single render. */
+const ROW_MOUNT_BATCH = 200;
+function locationIcon(icon) {
+    const props = { size: 15, weight: "regular", "aria-hidden": true };
+    switch (icon) {
+        case "home":
+            return _jsx(House, { ...props });
+        case "desktop":
+            return _jsx(Desktop, { ...props });
+        case "documents":
+            return _jsx(FileText, { ...props });
+        case "downloads":
+            return _jsx(DownloadSimple, { ...props });
+        case "icloud":
+        case "onedrive":
+            return _jsx(Cloud, { ...props });
+        case "volume":
+        case "root":
+            return _jsx(HardDrives, { ...props });
+        default:
+            return _jsx(Folder, { ...props });
+    }
+}
+function nodeIcon(node) {
+    if (node.kind === "dir") {
+        if (node.icon !== undefined)
+            return locationIcon(node.icon);
+        return _jsx(Folder, { size: 15, weight: "fill", "aria-hidden": true });
+    }
+    if (node.kind === "file") {
+        return (_jsx(FileTypeIcon, { format: (node.format ?? "unknown"), path: node.path, size: 14 }));
+    }
+    return _jsx(File, { size: 15, weight: "regular", "aria-hidden": true });
+}
+const TreeRow = memo(function TreeRow({ node, depth, parentPath, expanded, selected, open, tabbed, actions, }) {
+    const expandable = node.kind === "dir";
+    const unsupported = node.kind === "other";
+    return (_jsxs("div", { role: "treeitem", "aria-label": node.name, "aria-description": open ? "Open in a tab" : undefined, "aria-expanded": expandable ? expanded : undefined, "aria-selected": selected, "aria-disabled": unsupported || undefined, "data-vr-tree-path": node.path, "data-vr-parent": parentPath, tabIndex: tabbed ? 0 : -1, title: unsupported ? `${node.path} — ${hostAppName()} can't open this file type` : node.path, className: `vr-x-row${unsupported ? " vr-x-dim" : ""}`, style: { paddingLeft: 8 + depth * 14 }, onClick: () => {
+            if (expandable)
+                actions.toggleDir(node.path);
+            else if (node.kind === "file")
+                actions.onActivateRow(node);
+        }, onFocus: () => actions.setFocusPath(node.path), onContextMenu: (e) => {
+            e.preventDefault();
+            actions.onOpenMenu(node, e.clientX, e.clientY);
+        }, children: [_jsx("span", { className: "vr-x-caret", "aria-hidden": true, children: expandable ? (expanded ? (_jsx(CaretDown, { size: 10, weight: "regular" })) : (_jsx(CaretRight, { size: 10, weight: "regular" }))) : null }), _jsx("span", { className: "vr-x-icn", "aria-hidden": true, children: nodeIcon(node) }), _jsx("span", { className: "vr-x-name", children: node.name }), open && _jsx("span", { className: "vr-x-open", title: "Open in a tab", "aria-hidden": true }), _jsx("button", { type: "button", tabIndex: -1, "aria-label": `Actions for ${node.name}`, className: "vr-x-dots vr-press vr-focus", onClick: (e) => {
+                    e.stopPropagation();
+                    const r = e.currentTarget.getBoundingClientRect();
+                    actions.onOpenMenu(node, r.right, r.bottom + 2);
+                }, onContextMenu: (e) => {
+                    e.preventDefault();
+                    e.stopPropagation();
+                    const r = e.currentTarget.getBoundingClientRect();
+                    actions.onOpenMenu(node, r.right, r.bottom + 2);
+                }, children: _jsx(DotsThree, { size: 14, weight: "bold", "aria-hidden": true }) })] }));
+});
+// One spec object per listing entry, so a memoised row sees the same `node` on every render.
+const specByEntry = new WeakMap();
+function entryToSpec(e) {
+    const cached = specByEntry.get(e);
+    if (cached)
+        return cached;
+    const kind = rowKindOf(e.kind);
+    const spec = {
+        path: e.path,
+        name: e.name,
+        kind,
+        format: kind === "file" ? e.kind : undefined,
+    };
+    specByEntry.set(e, spec);
+    return spec;
+}
+function ChildrenRows({ dir, depth, ctx }) {
+    const st = ctx.tree.dirs.get(dir);
+    const pad = { paddingLeft: 24 + depth * 14 };
+    const total = st?.entries.length ?? 0;
+    const [mounted, setMounted] = useState(ROW_MOUNT_BATCH);
+    useEffect(() => {
+        if (mounted >= total)
+            return;
+        const frame = requestAnimationFrame(() => setMounted((count) => Math.min(total, count + ROW_MOUNT_BATCH)));
+        return () => cancelAnimationFrame(frame);
+    }, [mounted, total]);
+    // The row on the way to the file being revealed (or the active file) must exist at once, so the
+    // reveal can scroll to it; rows mounted for it stay mounted once the reveal has finished.
+    const wanted = ctx.revealPath ?? ctx.activePath;
+    const wantedIndex = useMemo(() => {
+        if (!st || !wanted || total <= ROW_MOUNT_BATCH)
+            return -1;
+        return st.entries.findIndex((e) => e.path === wanted || pathInside(e.path, wanted));
+    }, [st, wanted, total]);
+    const limit = Math.min(total, Math.max(mounted, wantedIndex + 1));
+    useEffect(() => {
+        if (limit > mounted)
+            setMounted(limit);
+    }, [limit, mounted]);
+    if (!st || (st.status === "loading" && st.entries.length === 0)) {
+        return (_jsx("div", { className: "vr-x-empty", style: pad, children: "Loading\u2026" }));
+    }
+    if (st.status === "error") {
+        return (_jsx("div", { className: "vr-x-note", role: "note", style: pad, children: st.message ?? "Couldn't list this folder." }));
+    }
+    return (_jsxs(_Fragment, { children: [st.entries.length === 0 && (_jsx("div", { className: "vr-x-empty", style: pad, children: "Empty folder" })), (limit < total ? st.entries.slice(0, limit) : st.entries).map((e) => (_jsx(ExplorerNode, { node: entryToSpec(e), depth: depth, parentPath: dir, ctx: ctx }, e.path))), st.truncated && limit >= total && (_jsx("div", { className: "vr-x-empty", style: pad, children: "\u2026 (more)" }))] }));
+}
+function ExplorerNode({ node, depth, parentPath, ctx, }) {
+    const expanded = node.kind === "dir" && ctx.tree.expanded.has(node.path);
+    const selected = node.path === ctx.activePath;
+    const open = !selected && node.kind !== "dir" && ctx.openPaths.has(node.path);
+    const tabbed = ctx.focusPath === node.path || (ctx.focusPath == null && ctx.firstPath === node.path);
+    return (_jsxs(_Fragment, { children: [_jsx(TreeRow, { node: node, depth: depth, parentPath: parentPath, expanded: expanded, selected: selected, open: open, tabbed: tabbed, actions: ctx.actions }), expanded && (_jsx("div", { role: "group", children: _jsx(ChildrenRows, { dir: node.path, depth: depth + 1, ctx: ctx }) }))] }));
+}
+/** 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 function ExplorerTree({ ariaLabel, roots, tree, activePath, revealPath = null, openPaths, onActivateRow, onOpenMenu, }) {
+    const ref = useRef(null);
+    const [focusPath, setFocusPath] = useState(null);
+    // The latest callbacks behind one object whose identity never changes (see RowActions).
+    const latest = useRef({ toggleDir: tree.toggleDir, onActivateRow, onOpenMenu });
+    latest.current = { toggleDir: tree.toggleDir, onActivateRow, onOpenMenu };
+    const actions = useMemo(() => ({
+        toggleDir: (path) => latest.current.toggleDir(path),
+        setFocusPath,
+        onActivateRow: (node) => latest.current.onActivateRow(node),
+        onOpenMenu: (node, x, y) => latest.current.onOpenMenu(node, x, y),
+    }), []);
+    const ctx = useMemo(() => ({
+        tree,
+        focusPath,
+        firstPath: roots[0]?.path,
+        activePath,
+        revealPath,
+        openPaths,
+        actions,
+    }), [tree, focusPath, roots, activePath, revealPath, openPaths, actions]);
+    const onKeyDown = (e) => {
+        const container = ref.current;
+        if (!container)
+            return;
+        const items = Array.from(container.querySelectorAll('[role="treeitem"]'));
+        if (items.length === 0)
+            return;
+        const activeEl = document.activeElement;
+        let idx = items.indexOf(activeEl);
+        if (idx < 0)
+            idx = items.findIndex((el) => el.dataset.vrTreePath === focusPath);
+        if (idx < 0)
+            idx = 0;
+        const cur = items[idx];
+        const focusItem = (el) => {
+            if (!el)
+                return;
+            el.focus();
+            el.scrollIntoView?.({ block: "nearest" });
+        };
+        switch (e.key) {
+            case "ArrowDown":
+                e.preventDefault();
+                focusItem(items[Math.min(items.length - 1, idx + 1)]);
+                break;
+            case "ArrowUp":
+                e.preventDefault();
+                focusItem(items[Math.max(0, idx - 1)]);
+                break;
+            case "Home":
+                e.preventDefault();
+                focusItem(items[0]);
+                break;
+            case "End":
+                e.preventDefault();
+                focusItem(items[items.length - 1]);
+                break;
+            case "ArrowRight": {
+                e.preventDefault();
+                const state = cur.getAttribute("aria-expanded");
+                const path = cur.dataset.vrTreePath;
+                if (state === "false" && path)
+                    tree.expandDir(path);
+                else if (state === "true")
+                    focusItem(items[idx + 1]);
+                break;
+            }
+            case "ArrowLeft": {
+                e.preventDefault();
+                const state = cur.getAttribute("aria-expanded");
+                const path = cur.dataset.vrTreePath;
+                if (state === "true" && path) {
+                    tree.collapseDir(path);
+                    break;
+                }
+                const parent = cur.dataset.vrParent;
+                if (parent) {
+                    const parentEl = items.find((el) => el.dataset.vrTreePath === parent);
+                    if (parentEl)
+                        focusItem(parentEl);
+                }
+                break;
+            }
+            case "Enter":
+            case " ": {
+                e.preventDefault();
+                cur.click();
+                break;
+            }
+        }
+    };
+    return (_jsx("div", { role: "tree", "aria-label": ariaLabel, ref: ref, onKeyDown: onKeyDown, className: "vr-x-tree", children: roots.map((r, i) => (_jsx(ExplorerNode, { node: r, depth: 0, parentPath: undefined, ctx: ctx }, `${i}:${r.path}`))) }));
+}

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

@@ -0,0 +1,37 @@
+export declare const EXPLORER_SETTINGS_KEY = "vr.explorer.v1";
+export interface ExplorerSectionState {
+    pinned: boolean;
+    recent: boolean;
+    locations: boolean;
+}
+export interface ExplorerPersisted {
+    /** Dir paths currently expanded in the Locations tree / Pinned folders. */
+    expanded: string[];
+    sections: ExplorerSectionState;
+    /** Sidebar pixel width (also mirrored to localStorage "vr.sidebar.width"). */
+    width: number;
+    /** Explorer scroll offset (scrollTop of the nav container). */
+    scroll: number;
+}
+export declare function defaultExplorerPersisted(): ExplorerPersisted;
+/** Load the persisted explorer record once (SQLite mirror via settings_get); merges over defaults
+ *  and caches the result so the sidebar shell and the sections share one IPC read. */
+export declare function loadExplorerPersisted(): Promise<ExplorerPersisted>;
+/** Synchronous read of the last-loaded record (defaults before hydration resolves). */
+export declare function explorerPersistedSync(): ExplorerPersisted;
+/** Merge a patch into the record and schedule a debounced (~300ms) mirror write. */
+export declare function saveExplorerPersisted(patch: Partial<ExplorerPersisted>): void;
+/** Case-insensitive "is `child` strictly inside `dir`" on path segments. */
+export declare function pathInside(dir: string, child: string): boolean;
+/** The chain of ancestor directories of `filePath` from `rootDir` (inclusive) down to the file's
+ *  parent dir — used by "reveal the active file" to expand each level. Returns [] when the file is
+ *  not under rootDir. Ancestors are rebuilt from the file path's own segments so they keep the
+ *  backend's canonical casing (they must string-match the `path` keys of tree dir entries). */
+export declare function ancestorDirs(filePath: string, rootDir: string): string[];
+/** The name of the child of `dir` on the way to `target` (the target itself when it is a direct
+ *  child), or undefined when `dir` is not a strict ancestor of `target`. Separator-agnostic:
+ *  `C:\Temp` with `C:\Temp\abc\x.md` gives "abc". */
+export declare function childNameOnPath(dir: string, target: string | null): string | undefined;
+/** ExplorerEntry.kind → row kind. "dir" stays "dir", a supported format id becomes "file"
+ *  (openable, broker-granted path), anything else is "other" (real path, no grant — never open). */
+export declare function rowKindOf(kind: string): "dir" | "file" | "other";

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

@@ -0,0 +1,135 @@
+// Shared state for the explorer sidebar (Part C): the "vr.explorer.v1" settings-mirror record
+// (expanded dirs, section open/closed, sidebar width, scroll position) with a module-level cache +
+// debounced write, plus the small path helpers the lazy tree and the active-file reveal need.
+import { getSettingsMirror, setSettingsMirror } from "@rightkit/document-core/state/tauriBridge";
+import { splitPath } from "../SidebarPathUtils.js";
+export const EXPLORER_SETTINGS_KEY = "vr.explorer.v1";
+export function defaultExplorerPersisted() {
+    return {
+        expanded: [],
+        sections: { pinned: true, recent: true, locations: true },
+        width: 0,
+        scroll: 0,
+    };
+}
+let cache = null;
+/** Set once any save has landed — a late-resolving load must not stomp a fresher write. */
+let mutated = false;
+let writeTimer = null;
+function sanitize(raw) {
+    const fallback = defaultExplorerPersisted();
+    if (raw === null || typeof raw !== "object")
+        return fallback;
+    const o = raw;
+    const s = o.sections;
+    return {
+        expanded: Array.isArray(o.expanded)
+            ? o.expanded.filter((p) => typeof p === "string")
+            : [],
+        sections: {
+            pinned: typeof s?.pinned === "boolean" ? s.pinned : true,
+            recent: typeof s?.recent === "boolean" ? s.recent : true,
+            locations: typeof s?.locations === "boolean" ? s.locations : true,
+        },
+        width: typeof o.width === "number" && Number.isFinite(o.width) ? o.width : 0,
+        scroll: typeof o.scroll === "number" && Number.isFinite(o.scroll) ? o.scroll : 0,
+    };
+}
+/** Load the persisted explorer record once (SQLite mirror via settings_get); merges over defaults
+ *  and caches the result so the sidebar shell and the sections share one IPC read. */
+export async function loadExplorerPersisted() {
+    if (cache)
+        return cache;
+    const raw = await getSettingsMirror(EXPLORER_SETTINGS_KEY);
+    if (mutated && cache)
+        return cache;
+    let parsed = defaultExplorerPersisted();
+    if (raw != null) {
+        try {
+            parsed = sanitize(JSON.parse(raw));
+        }
+        catch {
+            /* corrupt mirror value — keep defaults */
+        }
+    }
+    if (!mutated)
+        cache = parsed;
+    return cache ?? parsed;
+}
+/** Synchronous read of the last-loaded record (defaults before hydration resolves). */
+export function explorerPersistedSync() {
+    return cache ?? defaultExplorerPersisted();
+}
+/** Merge a patch into the record and schedule a debounced (~300ms) mirror write. */
+export function saveExplorerPersisted(patch) {
+    mutated = true;
+    cache = { ...(cache ?? defaultExplorerPersisted()), ...patch };
+    if (writeTimer != null)
+        window.clearTimeout(writeTimer);
+    writeTimer = window.setTimeout(() => {
+        writeTimer = null;
+        if (cache)
+            void setSettingsMirror(EXPLORER_SETTINGS_KEY, JSON.stringify(cache));
+    }, 300);
+}
+// ── Path helpers (separator-agnostic; the tree sees both / and \ paths) ──────
+/** Case-insensitive "is `child` strictly inside `dir`" on path segments. */
+export function pathInside(dir, child) {
+    const d = splitPath(dir).join("/").toLowerCase();
+    const c = splitPath(child).join("/").toLowerCase();
+    return c.length > d.length && c.startsWith(d + "/");
+}
+/** The chain of ancestor directories of `filePath` from `rootDir` (inclusive) down to the file's
+ *  parent dir — used by "reveal the active file" to expand each level. Returns [] when the file is
+ *  not under rootDir. Ancestors are rebuilt from the file path's own segments so they keep the
+ *  backend's canonical casing (they must string-match the `path` keys of tree dir entries). */
+export function ancestorDirs(filePath, rootDir) {
+    if (!pathInside(rootDir, filePath))
+        return [];
+    const rootSegs = splitPath(rootDir);
+    const fileSegs = splitPath(filePath);
+    const sep = filePath.includes("\\") ? "\\" : "/";
+    const out = [];
+    for (let i = rootSegs.length; i < fileSegs.length; i++) {
+        if (i === rootSegs.length) {
+            out.push(rootDir);
+            continue;
+        }
+        const head = fileSegs[0] ?? "";
+        if (/^[A-Za-z]:$/.test(head)) {
+            out.push(head + sep + fileSegs.slice(1, i).join(sep));
+        }
+        else {
+            out.push((filePath.startsWith("/") ? "/" : "") + fileSegs.slice(0, i).join(sep));
+        }
+    }
+    return out;
+}
+/** The name of the child of `dir` on the way to `target` (the target itself when it is a direct
+ *  child), or undefined when `dir` is not a strict ancestor of `target`. Separator-agnostic:
+ *  `C:\Temp` with `C:\Temp\abc\x.md` gives "abc". */
+export function childNameOnPath(dir, target) {
+    if (!target || !pathInside(dir, target))
+        return undefined;
+    return splitPath(target)[splitPath(dir).length];
+}
+const KNOWN_FORMATS = new Set([
+    "md",
+    "mdx",
+    "txt",
+    "pdf",
+    "html",
+    "docx",
+    "image",
+    "web",
+    "unknown",
+]);
+/** ExplorerEntry.kind → row kind. "dir" stays "dir", a supported format id becomes "file"
+ *  (openable, broker-granted path), anything else is "other" (real path, no grant — never open). */
+export function rowKindOf(kind) {
+    if (kind === "dir")
+        return "dir";
+    if (kind === "other" || !KNOWN_FORMATS.has(kind))
+        return "other";
+    return "file";
+}

package/dist/app/tabMountPolicy.d.ts

@@ -0,0 +1,45 @@
+import { type DocumentFormat } from "@rightkit/document-core/app/resourceCensus";
+/** Maximum number of ordinary document routers kept paint-warm (DocumentRouterTable's own limit). */
+export declare const ORDINARY_LIVE_PANE_LIMIT = 2;
+export declare const LIVE_TAB_LIMIT = 8;
+export type TabMountPolicyInput = Readonly<{
+    activePath: string | null;
+    previousActivePath: string | null;
+    protectedPaths: ReadonlySet<string>;
+    /** Recently-active paths, most-recent-first. Only the first LIVE_TAB_LIMIT entries stay live. */
+    recentPaths?: readonly string[];
+    /**
+     * Document format per path, for the intrinsic-cost floor in `candidateWeight`. Optional and
+     * missing entries fall back to the census-only signal (matches prior behavior) so existing
+     * callers/tests that don't care about the eviction-cost-decay case keep working unchanged.
+     */
+    formatByPath?: ReadonlyMap<string, DocumentFormat>;
+}>;
+export type TabMountCounters = Readonly<{
+    shellCount: number;
+    liveCount: number;
+    protectedLiveCount: number;
+    ordinaryLiveLimit: number;
+}>;
+/**
+ * Dirty text sessions may leave the live set only after their authoritative source (or a
+ * structured draft snapshot) is owned above the router. Binary editors deliberately never get
+ * this escape hatch: their mounted runtime remains their only authoritative dirty state.
+ */
+export declare function dirtyPaneMayShell(format: string, hasExternalSourceOrDraftOwner: boolean): boolean;
+/**
+ * Active + previous-active + a resource-weighted MRU window of recently-active panes stay live.
+ * `protectedPaths` protection is deliberately additive and unbounded: a draft or pending save
+ * cannot be evicted merely because another tab became active or aged out of the MRU window.
+ *
+ * Beyond that, every candidate is checked against the resource census before it can age out:
+ * a document reporting pinned state (dirty with no external owner — `documentHasPinnedState`)
+ * is kept live no matter its MRU rank or weight, full stop — there is no limit or heuristic that
+ * overrides this. A document whose state is dirty-but-externalized, or simply clean, competes for
+ * the MRU budget like any other, weighted by `candidateWeight` so heavyweight panes shell out
+ * before lightweight ones at the same recency — and stay counted as heavyweight even once shelled,
+ * via `formatByPath`'s intrinsic-cost floor (see `candidateWeight`'s own doc comment).
+ */
+export declare function liveDocumentPaths({ activePath, previousActivePath, protectedPaths, recentPaths, formatByPath, }: TabMountPolicyInput): Set<string>;
+/** Deterministic observability for stress tests & diagnostics; never reads wall-clock time. */
+export declare function tabMountCounters(documentPaths: readonly string[], livePaths: ReadonlySet<string>, protectedPaths: ReadonlySet<string>): TabMountCounters;