@rightkit/document-workspace 0.0.0-stage → 0.1.1

package/dist/app/tabMountPolicy.js

@@ -0,0 +1,104 @@
+import { documentHasPinnedState, formatIsIntrinsicallyHeavy, heavyResourcesForDocument, } from "@rightkit/document-core/app/resourceCensus";
+/** Maximum number of ordinary document routers kept paint-warm (DocumentRouterTable's own limit). */
+export const ORDINARY_LIVE_PANE_LIMIT = 2;
+// Original policy (protected ∪ active ∪ previousActive) cold-remounted every tab on a A→B→C→A cycle,
+// which reads as a bug in ordinary use even though it was the deliberate stress-test-tuned plateau from
+// 553d6b55. An MRU window keeps recently-visited tabs mounted (not paint-warm — see DocumentRouterTable's
+// separate, still-tight isPaintWarm) so returning to a tab you left seconds ago doesn't cold-mount it.
+// 8 is generous headroom above the 2-pane paint-warm limit while still bounding a 50-tab stress session.
+//
+// The window is a resource BUDGET, not a slot count: a document currently holding a heavy runtime
+// (docx-editor, pdf-document, html-iframe, image-viewer, …) consumes more of it than a light or
+// medium one, so heavyweight background panes shell sooner than lightweight ones at the same MRU
+// rank. This makes the limit resource-aware without lowering it — VR-P0-4.
+//
+// Measured 2026-10-11 by `runTabLivenessWindow` (scripts/qa-resources-e2e.mjs, receipt
+// `memoryPerTab`; hidden Chrome, JS heap after a forced collection, plain-text tabs only): a live
+// text tab costs about 0.24 MB of heap and a shelled one about 0.03 MB, so 50 tabs with 8 live sit
+// at 11.1 MB against 8.0 MB for one tab. Heavy formats (PDF, DOCX, HTML frames) and native WebView
+// memory are not in that figure; they are why the budget is weighted rather than raised.
+export const LIVE_TAB_LIMIT = 8;
+/** Heavy documents consume more of the MRU budget than light/medium ones, so they age out sooner. */
+const HEAVY_CANDIDATE_WEIGHT = 2;
+const ORDINARY_CANDIDATE_WEIGHT = 1;
+/**
+ * A candidate's cost is the max of two independent signals:
+ *  - intrinsic: a static fact about the document's FORMAT (html/docx/pdf/image always allocate a
+ *    heavy resource while mounted), true whether or not the pane is currently mounted at all;
+ *  - resident: what the census currently has allocated for this path, which is a live-only signal
+ *    that goes to zero the moment a shelled pane releases its resources.
+ * Taking the max means resident information can only ever RAISE the cost above the format's floor
+ * (e.g. a doc holding more than one heavy resource kind at once), never lower a known-heavy format
+ * to ordinary weight just because it is not currently resident — see VR-P0-4 follow-up.
+ */
+function candidateWeight(path, format) {
+    const intrinsic = formatIsIntrinsicallyHeavy(format)
+        ? HEAVY_CANDIDATE_WEIGHT
+        : ORDINARY_CANDIDATE_WEIGHT;
+    const resident = heavyResourcesForDocument(path) > 0 ? HEAVY_CANDIDATE_WEIGHT : ORDINARY_CANDIDATE_WEIGHT;
+    return Math.max(intrinsic, resident);
+}
+/**
+ * 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 function dirtyPaneMayShell(format, hasExternalSourceOrDraftOwner) {
+    return (hasExternalSourceOrDraftOwner && (format === "txt" || format === "md" || format === "html"));
+}
+/**
+ * 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 function liveDocumentPaths({ activePath, previousActivePath, protectedPaths, recentPaths = [], formatByPath, }) {
+    const paths = new Set(protectedPaths);
+    let budget = LIVE_TAB_LIMIT;
+    const weightOf = (path) => candidateWeight(path, formatByPath?.get(path));
+    // Active and previous-active are unconditionally live, but they still spend from the same
+    // shared budget as everything else — otherwise the window would exceed LIVE_TAB_LIMIT whenever
+    // they also show up in recentPaths (which they normally do).
+    for (const path of [activePath, previousActivePath]) {
+        if (!path || paths.has(path))
+            continue;
+        paths.add(path);
+        budget = Math.max(0, budget - weightOf(path));
+    }
+    for (const path of recentPaths) {
+        if (paths.has(path))
+            continue;
+        if (documentHasPinnedState(path)) {
+            // Never evict a pane with pinned state. No heuristic, no limit, no exception.
+            paths.add(path);
+            continue;
+        }
+        const weight = weightOf(path);
+        if (weight > budget)
+            continue;
+        paths.add(path);
+        budget -= weight;
+    }
+    return paths;
+}
+/** Deterministic observability for stress tests & diagnostics; never reads wall-clock time. */
+export function tabMountCounters(documentPaths, livePaths, protectedPaths) {
+    let protectedLiveCount = 0;
+    for (const path of documentPaths)
+        if (livePaths.has(path) && protectedPaths.has(path))
+            protectedLiveCount++;
+    const liveCount = documentPaths.filter((path) => livePaths.has(path)).length;
+    return {
+        shellCount: documentPaths.length - liveCount,
+        liveCount,
+        protectedLiveCount,
+        ordinaryLiveLimit: ORDINARY_LIVE_PANE_LIMIT,
+    };
+}

package/dist/app/tabWarmOrder.d.ts

@@ -0,0 +1,7 @@
+export declare function loadTabWarmOrder(storage?: Pick<Storage, "getItem">): string[];
+export declare function saveTabWarmOrder(paths: readonly string[], storage?: Pick<Storage, "setItem">): void;
+/**
+ * Restored tabs warm in prior activation order. Tabs absent from that order use proximity to the
+ * active tab, alternating forward/backward, so first idle work benefits likely next clicks.
+ */
+export declare function restoredTabWarmOrder(openPaths: readonly string[], activePath: string | null, savedOrder: readonly string[]): string[];

package/dist/app/tabWarmOrder.js

@@ -0,0 +1,48 @@
+const TAB_WARM_ORDER_KEY = "vr.session.tab-warm-order";
+const MAX_SAVED_PATHS = 64;
+export function loadTabWarmOrder(storage = localStorage) {
+    try {
+        const parsed = JSON.parse(storage.getItem(TAB_WARM_ORDER_KEY) ?? "[]");
+        if (!Array.isArray(parsed))
+            return [];
+        return [...new Set(parsed.filter((value) => typeof value === "string"))].slice(0, MAX_SAVED_PATHS);
+    }
+    catch {
+        return [];
+    }
+}
+export function saveTabWarmOrder(paths, storage = localStorage) {
+    try {
+        storage.setItem(TAB_WARM_ORDER_KEY, JSON.stringify([...new Set(paths)].slice(0, MAX_SAVED_PATHS)));
+    }
+    catch {
+        // Storage can be unavailable in hardened webviews. Warm-order persistence is optional.
+    }
+}
+/**
+ * Restored tabs warm in prior activation order. Tabs absent from that order use proximity to the
+ * active tab, alternating forward/backward, so first idle work benefits likely next clicks.
+ */
+export function restoredTabWarmOrder(openPaths, activePath, savedOrder) {
+    const open = new Set(openPaths);
+    const result = [];
+    const add = (path) => {
+        if (!path || path === activePath || !open.has(path) || result.includes(path))
+            return;
+        result.push(path);
+    };
+    for (const path of savedOrder)
+        add(path);
+    const activeIndex = activePath ? openPaths.indexOf(activePath) : -1;
+    if (activeIndex >= 0) {
+        for (let distance = 1; distance < openPaths.length; distance++) {
+            add(openPaths[activeIndex + distance]);
+            add(openPaths[activeIndex - distance]);
+        }
+    }
+    else {
+        for (const path of openPaths)
+            add(path);
+    }
+    return result;
+}

package/dist/app/tabs/TabFuseCurves.d.ts

@@ -0,0 +1,3 @@
+export declare function TabFuseCurves({ size }: {
+    size?: number;
+}): import("react").JSX.Element;

package/dist/app/tabs/TabFuseCurves.js

@@ -0,0 +1,15 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Concave bottom-corner curves that fuse the ACTIVE titlebar tab into the reader
+ * surface — the horizontal-strip counterpart of @rightkit/react-shell FuseCurves
+ * (which bridges an active sidebar ROW's right edge). The strip fuses at both
+ * bottom corners instead: left piece = the same square-minus-quarter-disc path
+ * verbatim; right piece = the same path mirrored with scaleX(-1). Kept as SVG
+ * (not the mockup's radial-gradient pseudo-elements) because SVG antialiases the
+ * arc edge identically to the sidebar fuse and never depends on the tab's
+ * ::before/::after slots (the inactive-tab separator already uses ::before).
+ */
+const TAB_FUSE_PATH = "M12 0V12H0A12 12 0 0 0 12 0Z";
+export function TabFuseCurves({ size = 12 }) {
+    return (_jsxs(_Fragment, { children: [_jsx("svg", { "data-vr-tab-fuse-curve": "left", "aria-hidden": "true", focusable: "false", width: size, height: size, viewBox: "0 0 12 12", preserveAspectRatio: "none", className: "pointer-events-none absolute bottom-0", style: { left: -size, fill: "var(--reader-surface)" }, children: _jsx("path", { d: TAB_FUSE_PATH }) }), _jsx("svg", { "data-vr-tab-fuse-curve": "right", "aria-hidden": "true", focusable: "false", width: size, height: size, viewBox: "0 0 12 12", preserveAspectRatio: "none", className: "pointer-events-none absolute bottom-0", style: { right: -size, transform: "scaleX(-1)", fill: "var(--reader-surface)" }, children: _jsx("path", { d: TAB_FUSE_PATH }) })] }));
+}

package/dist/app/tabs/TabOverview.d.ts

@@ -0,0 +1,24 @@
+import { type RefObject } from "react";
+import type { LoadedDocument } from "@rightkit/document-core/documents/types";
+export interface TabOverviewProps {
+    docs: LoadedDocument[];
+    activePath: string | null;
+    titleFor: (doc: LoadedDocument) => string;
+    isDirty: (doc: LoadedDocument) => boolean;
+    dirtyPaths: ReadonlySet<string>;
+    subscribeDirty: (path: string, cb: () => void) => () => void;
+    subscribeEdits: (path: string, cb: () => void) => () => void;
+    getEditSnapshot: (path: string) => string | undefined;
+    computeTitle?: (doc: LoadedDocument) => string;
+    onActivate: (path: string) => void;
+    /** Bulk close for the footer action (integrator wires closeMany — dirty docs route
+     *  through the Save-All/Discard-All chooser upstream). */
+    onClosePaths: (paths: string[]) => void;
+    onClose: () => void;
+    /** Overview toggle button — Popover already restores focus to its opener, so this is a
+     *  fallback only (e.g. the button unmounted between open and close). */
+    returnFocusRef: RefObject<HTMLButtonElement | null>;
+}
+export declare const TabOverview: import("react").MemoExoticComponent<typeof TabOverviewImpl>;
+declare function TabOverviewImpl({ docs, activePath, titleFor, isDirty, dirtyPaths, subscribeDirty, subscribeEdits, getEditSnapshot, computeTitle, onActivate, onClosePaths, onClose, returnFocusRef, }: TabOverviewProps): import("react").JSX.Element;
+export {};

package/dist/app/tabs/TabOverview.js

@@ -0,0 +1,121 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Tab overview — the ⌘⇧A popover that drops out of the titlebar tab strip's right-edge
+// button (brief Part A item 8; visual spec docs/design/viewright-tabs-explorer.html `.pop`).
+// Built on the sidebar's shared Popover (glass panel, Escape + click-outside dismiss, and
+// focus restore to the element that opened it). Top→bottom: search field (focused on open),
+// type chips with counts, a scrollable list of matching tabs, and a footer with "N of M tabs"
+// plus a bulk Close that only appears while a filter or search is active.
+import { memo, useEffect, useRef, useState, } from "react";
+import { moveIndex } from "@rightkit/platform-ui/headless";
+import { isUntitled } from "@rightkit/document-core/documents/types";
+import { FileTypeIcon } from "../../documents/FileTypeIcon.js";
+import { LiveTitle } from "../LiveTitle.js";
+import { Popover } from "../sidebar/SidebarPrimitives.js";
+import { pathFolder } from "../sidebar/SidebarPathUtils.js";
+import { useTabDirty } from "./useTabDirty.js";
+const TYPE_GROUPS = [
+    { id: "all", label: "All", formats: null },
+    { id: "pdf", label: "PDF", formats: ["pdf"] },
+    { id: "md", label: "Markdown", formats: ["md", "mdx"] },
+    { id: "docx", label: "Word", formats: ["docx"] },
+    { id: "image", label: "Images", formats: ["image"] },
+    { id: "html", label: "HTML", formats: ["html"] },
+    { id: "txt", label: "Text", formats: ["txt"] },
+];
+/** [singular, plural] nouns for the bulk-close label — "Close 8 PDFs", "Close 3 Word
+ *  documents", "Close 5 tabs" when only a search is narrowing the set. */
+const TYPE_NOUNS = {
+    all: ["tab", "tabs"],
+    pdf: ["PDF", "PDFs"],
+    md: ["Markdown file", "Markdown files"],
+    docx: ["Word document", "Word documents"],
+    image: ["image", "images"],
+    html: ["HTML file", "HTML files"],
+    txt: ["text file", "text files"],
+};
+export const TabOverview = memo(TabOverviewImpl);
+function TabOverviewImpl({ docs, activePath, titleFor, isDirty, dirtyPaths, subscribeDirty, subscribeEdits, getEditSnapshot, computeTitle, onActivate, onClosePaths, onClose, returnFocusRef, }) {
+    const inputRef = useRef(null);
+    const listRef = useRef(null);
+    const [query, setQuery] = useState("");
+    const [typeGroup, setTypeGroup] = useState("all");
+    // Search field takes focus on open (Popover's auto-focus only targets [role=menuitem]s,
+    // which this list deliberately doesn't use — rows stay honest buttons).
+    useEffect(() => {
+        inputRef.current?.focus();
+    }, []);
+    // If the opener vanished while we were open, land on the overview button instead of <body>.
+    useEffect(() => () => {
+        if (document.activeElement === document.body)
+            returnFocusRef.current?.focus();
+    }, [returnFocusRef]);
+    const q = query.trim().toLowerCase();
+    const formats = TYPE_GROUPS.find((g) => g.id === typeGroup)?.formats ?? null;
+    const shown = docs.filter((doc) => {
+        if (formats && !formats.includes(doc.format))
+            return false;
+        if (!q)
+            return true;
+        return (titleFor(doc).toLowerCase().includes(q) || pathFolder(doc.path).toLowerCase().includes(q));
+    });
+    const rows = () => [
+        ...(listRef.current?.querySelectorAll("[data-vr-ov-row]") ?? []),
+    ];
+    // ↓/↑ roam between the search field and the row list (clamped, no wrap — first row's ↑
+    // returns to the field); Enter in the field opens the first match; Enter on a row is the
+    // button's native click (activate + close). Escape is Popover's.
+    const onKeyDown = (event) => {
+        const list = rows();
+        if (event.key === "ArrowDown") {
+            if (!list.length)
+                return;
+            event.preventDefault();
+            const at = list.indexOf(document.activeElement);
+            list[at < 0 ? 0 : moveIndex(at, list.length, "next", false)]?.focus();
+            return;
+        }
+        if (event.key === "ArrowUp") {
+            event.preventDefault();
+            const at = list.indexOf(document.activeElement);
+            if (at <= 0)
+                inputRef.current?.focus();
+            else
+                list[moveIndex(at, list.length, "prev", false)]?.focus();
+            return;
+        }
+        if (event.key === "Enter" && document.activeElement === inputRef.current && shown.length) {
+            event.preventDefault();
+            onActivate(shown[0].path);
+            onClose();
+        }
+    };
+    const activate = (path) => {
+        onActivate(path);
+        onClose();
+    };
+    const closeShown = () => {
+        onClosePaths(shown.map((d) => d.path));
+        onClose();
+    };
+    // Footer bulk action: only while a filter/search is active AND something matched —
+    // "Close 8 PDFs" / "Close 3 Word documents" / "Close 5 tabs" (search-only), with the
+    // dirty-count hint when the affected set includes unsaved tabs.
+    const filterActive = typeGroup !== "all" || q !== "";
+    const dirtyShown = shown.filter((d) => dirtyPaths.has(d.path) || isDirty(d)).length;
+    const noun = TYPE_NOUNS[typeGroup][shown.length === 1 ? 0 : 1];
+    return (_jsxs(Popover, { onClose: onClose, className: "vr-ov-pop", role: "dialog", ariaModal: false, ariaLabel: "Open tabs", children: [_jsx("input", { ref: inputRef, className: "vr-ov-q vr-focus", placeholder: "Search open tabs", "aria-label": "Search open tabs", value: query, onChange: (event) => setQuery(event.target.value), onKeyDown: onKeyDown }), _jsx("div", { className: "vr-ov-chips", role: "group", "aria-label": "Filter by type", children: TYPE_GROUPS.map((group) => {
+                    const n = group.formats
+                        ? docs.filter((d) => group.formats?.includes(d.format)).length
+                        : docs.length;
+                    if (group.id !== "all" && n === 0)
+                        return null; // hide zero-count chips
+                    return (_jsxs("button", { type: "button", className: "vr-ov-chip vr-press vr-focus", "aria-pressed": typeGroup === group.id, onClick: () => setTypeGroup(group.id), children: [group.label, " ", n] }, group.id));
+                }) }), _jsx("div", { ref: listRef, className: "vr-ov-list", onKeyDown: onKeyDown, children: shown.length === 0 ? (_jsx("div", { className: "vr-ov-empty", children: "No open tabs match" })) : (shown.map((doc) => (_jsx(OverviewRow, { doc: doc, title: titleFor(doc), titleNode: computeTitle && isUntitled(doc.path) ? (_jsx(LiveTitle, { doc: doc, compute: computeTitle, subscribeEdits: subscribeEdits, getEditSnapshot: getEditSnapshot })) : undefined, isDirty: isDirty, dirtyHint: dirtyPaths.has(doc.path), subscribeDirty: subscribeDirty, active: doc.path === activePath, onActivate: activate }, doc.tabKey ?? doc.path)))) }), _jsxs("div", { className: "vr-ov-foot", children: [_jsxs("span", { className: "vr-ov-sum", children: [shown.length, " of ", docs.length, " ", docs.length === 1 ? "tab" : "tabs"] }), filterActive && shown.length > 0 && (_jsxs("button", { type: "button", className: "vr-ov-close vr-press vr-focus", onClick: closeShown, children: ["Close ", shown.length, " ", noun, dirtyShown > 0 ? ` · ${dirtyShown} unsaved, will ask` : ""] }))] })] }));
+}
+const OverviewRow = memo(OverviewRowImpl);
+function OverviewRowImpl({ doc, title, titleNode, isDirty, dirtyHint, subscribeDirty, active, onActivate, }) {
+    const dirty = useTabDirty(doc, dirtyHint, isDirty, subscribeDirty);
+    const displayPath = doc.format === "web" ? (doc.web?.url ?? doc.path) : doc.path;
+    const folder = isUntitled(doc.path) ? "Unsaved buffer" : pathFolder(displayPath);
+    return (_jsxs("button", { type: "button", "data-vr-ov-row": true, className: `vr-ov-row${active ? " vr-ov-row-active" : ""}`, "data-active": active || undefined, title: displayPath, "aria-current": active || undefined, "aria-label": `${title}${dirty ? " — Unsaved edits" : ""}`, onClick: () => onActivate(doc.path), children: [_jsx("span", { className: "vr-ov-row-ficon", "aria-hidden": "true", children: _jsx(FileTypeIcon, { format: doc.format, path: doc.path, size: 20 }) }), _jsxs("span", { className: "vr-ov-row-text", children: [_jsx("span", { className: "vr-ov-row-name", children: titleNode ?? title }), _jsx("span", { className: "vr-ov-row-meta", children: folder })] }), dirty && _jsx("span", { className: "vr-ov-row-unsaved", children: "\u25CF Unsaved" })] }));
+}

package/dist/app/tabs/TabStrip.d.ts

@@ -0,0 +1,42 @@
+import type { LoadedDocument } from "@rightkit/document-core/documents/types";
+/**
+ * Everything the strip needs, supplied by the shell (App builds this once so the
+ * memoized strip skips per-keystroke re-renders the same way Sidebar/Toolbar do).
+ */
+export interface TabStripProps {
+    /** openDocs in order — single source of truth for tab order. */
+    docs: LoadedDocument[];
+    activePath: string | null;
+    sidebarCollapsed: boolean;
+    /** Dispatches "viewright:toggle-sidebar" (the sidebar owns the actual state). */
+    onToggleSidebar: () => void;
+    onActivate: (path: string) => void;
+    /** Goes through the existing dirty-confirm flow (requestClose). */
+    onRequestClose: (path: string) => void;
+    onCloseAll: () => void;
+    onCloseOthers: (path: string) => void;
+    onCloseRight: (path: string) => void;
+    onReorderTabs: (fromPath: string, toPath: string, position?: "before" | "after") => void;
+    /** New untitled txt buffer (Ctrl/Cmd+T). */
+    onNewDocument: () => void;
+    onTogglePin: (path: string) => void;
+    pinnedPaths: ReadonlySet<string>;
+    openLocalPaths: string[];
+    titleFor: (doc: LoadedDocument) => string;
+    isDirty: (doc: LoadedDocument) => boolean;
+    dirtyPaths: ReadonlySet<string>;
+    subscribeDirty: (path: string, cb: () => void) => () => void;
+    subscribeEdits: (path: string, cb: () => void) => () => void;
+    getEditSnapshot: (path: string) => string | undefined;
+    /** LiveTitle compute — keeps untitled tab names live while typing. */
+    computeTitle: (doc: LoadedDocument) => string;
+    overviewOpen: boolean;
+    onOverviewOpenChange: (open: boolean) => void;
+    /** Bulk-close an arbitrary subset (integrator wires closeMany — the overview's
+     *  "Close all" footer uses it; dirty docs still go through the unsaved-changes
+     *  chooser). */
+    onClosePaths: (paths: string[]) => void;
+}
+export declare const TabStrip: import("react").MemoExoticComponent<typeof TabStripImpl>;
+declare function TabStripImpl({ docs, activePath, sidebarCollapsed, onActivate, onRequestClose, onCloseAll, onCloseOthers, onCloseRight, onReorderTabs, onTogglePin, pinnedPaths, openLocalPaths, titleFor, isDirty, dirtyPaths, subscribeDirty, subscribeEdits, getEditSnapshot, computeTitle, overviewOpen, onOverviewOpenChange, onClosePaths, }: TabStripProps): import("react").JSX.Element;
+export {};