@rightkit/document-workspace 0.0.0-stage → 0.1.0

package/dist/app/useCommandPalette.js

@@ -0,0 +1,254 @@
+import { createElement, useMemo } from "react";
+import { File } from "@phosphor-icons/react/dist/icons/File";
+import { ClockCounterClockwise } from "@phosphor-icons/react/dist/icons/ClockCounterClockwise";
+import { FilePlus } from "@phosphor-icons/react/dist/icons/FilePlus";
+import { FolderOpen } from "@phosphor-icons/react/dist/icons/FolderOpen";
+import { GlobeSimple } from "@phosphor-icons/react/dist/icons/GlobeSimple";
+import { ArrowClockwise } from "@phosphor-icons/react/dist/icons/ArrowClockwise";
+import { Gear } from "@phosphor-icons/react/dist/icons/Gear";
+import { Keyboard } from "@phosphor-icons/react/dist/icons/Keyboard";
+import { CircleHalf } from "@phosphor-icons/react/dist/icons/CircleHalf";
+import { TextAlignLeft } from "@phosphor-icons/react/dist/icons/TextAlignLeft";
+import { Palette } from "@phosphor-icons/react/dist/icons/Palette";
+import { Copy } from "@phosphor-icons/react/dist/icons/Copy";
+import { ClipboardText } from "@phosphor-icons/react/dist/icons/ClipboardText";
+import { Export } from "@phosphor-icons/react/dist/icons/Export";
+import { FloppyDisk } from "@phosphor-icons/react/dist/icons/FloppyDisk";
+import { Printer } from "@phosphor-icons/react/dist/icons/Printer";
+import { Eye } from "@phosphor-icons/react/dist/icons/Eye";
+import { Code } from "@phosphor-icons/react/dist/icons/Code";
+import { capabilitiesFor } from "../documents/capabilities.js";
+import { displayTitle } from "@rightkit/document-core/documents/types";
+import { BASE_THEME_IDS, themeById } from "@rightkit/document-core/settings/themes";
+import { shortcutLabel } from "@rightkit/document-core/platform";
+// Decorative leading glyph for a palette row. Kept tiny + weight-regular to match the compact list.
+// biome-ignore lint/suspicious/noExplicitAny: Phosphor's icon props are structurally identical here.
+const ic = (I) => createElement(I, { size: 16, weight: "regular" });
+/**
+ * Command-palette entries: open tabs + recents + context-aware commands. Routes through the
+ * existing document handlers — the palette is just a uniform, cross-format way to reach them.
+ * Format-specific commands (save/print/view) gate on `capabilitiesFor`, not ad-hoc format checks.
+ */
+export function useCommandPalette(d) {
+    const { openDocs, recents, active, activeEditable, titleFor, activate, openRecent, newDocument, onOpenDialog, onOpenUrl, onSave, onSaveAs, onPrint, docxMenu, onChangeView, settings, update, openSettings, reopenClosed, showHelp, copyContents, exportMarkdown, copyRendered, copyAsMarkdown, duplicate, } = d;
+    return useMemo(() => {
+        const tabItems = openDocs.map((doc) => ({
+            id: `tab:${doc.path}`,
+            label: titleFor(doc),
+            hint: "open tab",
+            icon: ic(File),
+            run: () => void activate(doc.path),
+        }));
+        const recentItems = recents.map((r) => ({
+            id: `recent:${r.token}`,
+            label: displayTitle(r.displayName),
+            hint: "recent",
+            icon: ic(ClockCounterClockwise),
+            run: () => void openRecent(r),
+        }));
+        const cmds = [
+            {
+                id: "cmd:new",
+                label: "New text document",
+                hint: shortcutLabel("mod+n"),
+                icon: ic(FilePlus),
+                run: newDocument,
+            },
+            {
+                id: "cmd:open",
+                label: "Open file…",
+                hint: shortcutLabel("mod+o"),
+                icon: ic(FolderOpen),
+                run: () => void onOpenDialog(),
+            },
+            {
+                id: "cmd:open-url",
+                label: "Open URL…",
+                hint: "web",
+                icon: ic(GlobeSimple),
+                run: onOpenUrl,
+            },
+            {
+                id: "cmd:reopen",
+                label: "Reopen closed tab",
+                hint: shortcutLabel("mod+shift+t"),
+                icon: ic(ArrowClockwise),
+                run: reopenClosed,
+            },
+            { id: "cmd:settings", label: "Settings", icon: ic(Gear), run: openSettings },
+            {
+                id: "cmd:shortcuts",
+                label: "Keyboard shortcuts",
+                hint: "?",
+                icon: ic(Keyboard),
+                run: showHelp,
+            },
+            {
+                id: "cmd:contrast",
+                label: `Contrast: ${settings.contrast === "high" ? "Normal" : "High"}`,
+                hint: "typography",
+                icon: ic(CircleHalf),
+                run: () => update({ contrast: settings.contrast === "high" ? "normal" : "high" }),
+            },
+            {
+                id: "cmd:wrap",
+                label: `Word wrap: ${settings.wordWrap ? "Off" : "On"}`,
+                hint: "editor",
+                icon: ic(TextAlignLeft),
+                run: () => update({ wordWrap: !settings.wordWrap }),
+            },
+            ...BASE_THEME_IDS.map((id) => {
+                const theme = themeById(id);
+                return {
+                    id: `cmd:theme-${id}`,
+                    label: `Theme: ${theme.name}`,
+                    hint: "theme",
+                    icon: ic(Palette),
+                    run: () => update({ themeId: id }),
+                };
+            }),
+        ];
+        if (active) {
+            const c = capabilitiesFor(active.format);
+            if (copyContents)
+                cmds.push({
+                    id: "cmd:copy-contents",
+                    label: "Copy document contents",
+                    hint: "clipboard",
+                    icon: ic(Copy),
+                    run: copyContents,
+                });
+            if (copyRendered)
+                cmds.push({
+                    id: "cmd:copy-rendered",
+                    label: "Copy rendered Markdown (for sharing)",
+                    hint: "clipboard",
+                    icon: ic(ClipboardText),
+                    run: copyRendered,
+                });
+            if (copyAsMarkdown)
+                cmds.push({
+                    id: "cmd:copy-as-markdown",
+                    label: "Copy as Markdown",
+                    hint: "clipboard",
+                    icon: ic(ClipboardText),
+                    run: copyAsMarkdown,
+                });
+            if (duplicate)
+                cmds.push({
+                    id: "cmd:duplicate",
+                    label: "Duplicate as draft",
+                    hint: "new copy",
+                    icon: ic(Copy),
+                    run: duplicate,
+                });
+            if (exportMarkdown) {
+                cmds.push({
+                    id: "cmd:export-html",
+                    label: "Export as HTML…",
+                    hint: "markdown",
+                    icon: ic(Export),
+                    run: () => exportMarkdown("html"),
+                });
+                cmds.push({
+                    id: "cmd:export-txt",
+                    label: "Export as plain text…",
+                    hint: "markdown",
+                    icon: ic(Export),
+                    run: () => exportMarkdown("txt"),
+                });
+            }
+            if (activeEditable) {
+                cmds.push({
+                    id: "cmd:save",
+                    label: "Save",
+                    hint: shortcutLabel("mod+s"),
+                    icon: ic(FloppyDisk),
+                    run: () => (active.format === "docx" ? void docxMenu?.save() : void onSave(active)),
+                });
+            }
+            if (c.canSaveAs) {
+                cmds.push({
+                    id: "cmd:saveas",
+                    label: "Save As…",
+                    hint: shortcutLabel("mod+shift+s"),
+                    icon: ic(FloppyDisk),
+                    run: () => void onSaveAs(active),
+                });
+            }
+            if (c.canPrintInApp)
+                cmds.push({
+                    id: "cmd:print",
+                    label: "Print",
+                    hint: shortcutLabel("mod+p"),
+                    icon: ic(Printer),
+                    run: () => onPrint(active),
+                });
+            else if (active.format === "docx")
+                cmds.push({
+                    id: "cmd:print",
+                    label: "Print",
+                    hint: shortcutLabel("mod+p"),
+                    icon: ic(Printer),
+                    run: () => void docxMenu?.print(),
+                });
+            if (c.canSwitchView) {
+                if (active.format === "html") {
+                    cmds.push({
+                        id: "cmd:view-interactive",
+                        label: "View: Interactive",
+                        icon: ic(Eye),
+                        run: () => void onChangeView("interactive"),
+                    });
+                    cmds.push({
+                        id: "cmd:view-safe",
+                        label: "View: Safe",
+                        icon: ic(Eye),
+                        run: () => void onChangeView("preview"),
+                    });
+                }
+                else {
+                    cmds.push({
+                        id: "cmd:view-preview",
+                        label: "View: Preview",
+                        icon: ic(Eye),
+                        run: () => void onChangeView("preview"),
+                    });
+                    cmds.push({
+                        id: "cmd:view-source",
+                        label: "View: Source",
+                        icon: ic(Code),
+                        run: () => void onChangeView("source"),
+                    });
+                }
+            }
+        }
+        return [...tabItems, ...recentItems, ...cmds];
+    }, [
+        openDocs,
+        recents,
+        active,
+        activeEditable,
+        titleFor,
+        activate,
+        openRecent,
+        newDocument,
+        onOpenDialog,
+        onOpenUrl,
+        onSave,
+        onSaveAs,
+        onPrint,
+        docxMenu,
+        onChangeView,
+        settings,
+        update,
+        openSettings,
+        reopenClosed,
+        showHelp,
+        copyContents,
+        exportMarkdown,
+        duplicate,
+        copyRendered,
+        copyAsMarkdown,
+    ]);
+}

package/dist/app/useCrossDocSearch.d.ts

@@ -0,0 +1,7 @@
+import type { LoadedDocument, SearchProvider } from "@rightkit/document-core/documents/types";
+/**
+ * Build a synthetic SearchProvider that aggregates matches across multiple warm tabs.
+ * The provider fans out find() to all registered providers, builds a flat match list in
+ * tab order, and navigates between tabs on next/prev.
+ */
+export declare function buildCrossDocProvider(providers: Map<string, SearchProvider>, openDocs: LoadedDocument[], activate: (path: string) => Promise<void>): SearchProvider;

package/dist/app/useCrossDocSearch.js

@@ -0,0 +1,94 @@
+/**
+ * Build a synthetic SearchProvider that aggregates matches across multiple warm tabs.
+ * The provider fans out find() to all registered providers, builds a flat match list in
+ * tab order, and navigates between tabs on next/prev.
+ */
+export function buildCrossDocProvider(providers, openDocs, activate) {
+    let matches = [];
+    let globalActive = -1;
+    let lastQuery = "";
+    let lastOptions = { matchCase: false, wholeWord: false };
+    const orderedDocs = openDocs.filter((d) => providers.has(d.path));
+    const find = async (query, options) => {
+        matches = [];
+        globalActive = -1;
+        lastQuery = query;
+        lastOptions = options;
+        if (!query)
+            return { count: 0, activeIndex: -1 };
+        // Each provider.find() is an independent per-doc search (some cross a render/IPC boundary,
+        // e.g. docx) — fan them out concurrently, then stitch the results back together in the
+        // existing orderedDocs order so matches/globalIndex stay deterministic regardless of which
+        // provider actually finishes first.
+        const perDocResults = await Promise.all(orderedDocs.map(async (doc) => {
+            const provider = providers.get(doc.path);
+            if (!provider)
+                return null;
+            try {
+                return { doc, res: await provider.find(query, options) };
+            }
+            catch {
+                // Skip providers that fail (e.g. cold docx tabs).
+                return null;
+            }
+        }));
+        for (const entry of perDocResults) {
+            if (!entry)
+                continue;
+            for (let i = 0; i < entry.res.count; i++) {
+                matches.push({
+                    path: entry.doc.path,
+                    displayName: entry.doc.displayName,
+                    matchIndexWithinDoc: i,
+                    globalIndex: matches.length,
+                });
+            }
+        }
+        globalActive = matches.length > 0 ? 0 : -1;
+        if (globalActive >= 0) {
+            await navigateTo(globalActive);
+        }
+        return { count: matches.length, activeIndex: globalActive };
+    };
+    const navigateTo = async (idx) => {
+        if (idx < 0 || idx >= matches.length)
+            return;
+        const m = matches[idx];
+        await activate(m.path);
+        const provider = providers.get(m.path);
+        if (!provider)
+            return;
+        if (provider.seek) {
+            provider.seek(m.matchIndexWithinDoc);
+            return;
+        }
+        await provider.find(lastQuery, lastOptions);
+        for (let i = 0; i < m.matchIndexWithinDoc; i++) {
+            await provider.next();
+        }
+    };
+    const step = async (dir) => {
+        if (matches.length === 0)
+            return { count: 0, activeIndex: -1 };
+        globalActive = (((globalActive + dir) % matches.length) + matches.length) % matches.length;
+        await navigateTo(globalActive);
+        return { count: matches.length, activeIndex: globalActive };
+    };
+    return {
+        kind: "source",
+        canReplace: false,
+        supportsMatchCase: true,
+        supportsWholeWord: true,
+        find,
+        next: () => step(1),
+        prev: () => step(-1),
+        close: () => {
+            matches = [];
+            globalActive = -1;
+            // Close all sub-providers' find state.
+            for (const doc of orderedDocs) {
+                providers.get(doc.path)?.close();
+            }
+        },
+    };
+}

package/dist/app/useDistractionFree.d.ts

@@ -0,0 +1,21 @@
+import type { LoadedDocument } from "@rightkit/document-core/documents/types";
+import type { createBlockDraftRegistry } from "@rightkit/document-core/app/blockDrafts";
+type Registry = ReturnType<typeof createBlockDraftRegistry>;
+/** Distraction-free reading mode: the toggle (guarded by unresolved block drafts), the Esc-exit
+ * effect, and the confirm-dialog handlers. Extracted verbatim from App.tsx. */
+export declare function useDistractionFree({ active, blockDrafts, overlayOpen, }: {
+    active: LoadedDocument | null;
+    blockDrafts: Registry;
+    /** True while settings / palette / help / open-url own Esc. */
+    overlayOpen: boolean;
+}): {
+    distractionFree: boolean;
+    toggleDistractionFree: () => void;
+    fullscreenConfirm: {
+        onDone: () => Promise<void>;
+        onDiscard: () => Promise<void>;
+        onStay: () => void;
+        error: string | null;
+    } | null;
+};
+export {};

package/dist/app/useDistractionFree.js

@@ -0,0 +1,73 @@
+import { useRef, useState } from "react";
+import { toast, useDismiss } from "@rightkit/platform-ui/headless";
+import { shortcutLabel } from "@rightkit/document-core/platform";
+import { resolveDocumentDrafts } from "./draftResolution.js";
+/** Distraction-free reading mode: the toggle (guarded by unresolved block drafts), the Esc-exit
+ * effect, and the confirm-dialog handlers. Extracted verbatim from App.tsx. */
+export function useDistractionFree({ active, blockDrafts, overlayOpen, }) {
+    const [distractionFree, setDistractionFree] = useState(false);
+    const [pendingFullscreenDraft, setPendingFullscreenDraft] = useState(null);
+    const flipDistractionFree = () => setDistractionFree((on) => {
+        if (!on)
+            toast(`Distraction-free — press ${shortcutLabel("esc")} or ${shortcutLabel("mod+shift+f")} to exit`, "info");
+        return !on;
+    });
+    const toggleDistractionFree = () => {
+        const path = active?.path;
+        if (path && blockDrafts.snapshotModified(path).length > 0) {
+            setPendingFullscreenDraft({ drafts: blockDrafts.snapshotModified(path) });
+            return;
+        }
+        // Clean draft closes silently before entering fullscreen
+        if (path) {
+            const clean = blockDrafts.snapshotAll(path);
+            for (const d of clean)
+                blockDrafts.discard(d.identity);
+        }
+        flipDistractionFree();
+    };
+    // Esc leaves distraction-free reading (when nothing else owns Esc).
+    // Bubble phase on the window, like the handler it replaces, so an overlay or modal that takes
+    // Escape in the capture phase keeps its own Escape.
+    const windowTarget = useRef(typeof window === "undefined" ? null : window);
+    useDismiss(() => setDistractionFree(false), {
+        enabled: distractionFree && !overlayOpen,
+        escapeTarget: windowTarget,
+        outside: false,
+        preventDefault: true,
+        stopPropagation: false,
+        imeGuard: false,
+    });
+    const onDone = async () => {
+        const path = active?.path;
+        if (!path) {
+            setPendingFullscreenDraft(null);
+            return;
+        }
+        const outcome = await resolveDocumentDrafts(blockDrafts, path, "view-change", "done");
+        if (outcome !== "resolved") {
+            setPendingFullscreenDraft({ drafts: blockDrafts.snapshotModified(path) });
+            return;
+        }
+        setPendingFullscreenDraft(null);
+        flipDistractionFree();
+    };
+    const onDiscard = async () => {
+        const path = active?.path;
+        if (path)
+            await resolveDocumentDrafts(blockDrafts, path, "view-change", "discard");
+        setPendingFullscreenDraft(null);
+        flipDistractionFree();
+    };
+    const confirm = pendingFullscreenDraft
+        ? {
+            onDone,
+            onDiscard,
+            onStay: () => setPendingFullscreenDraft(null),
+            error: pendingFullscreenDraft.drafts.find((d) => d.error)?.error ??
+                pendingFullscreenDraft.drafts.find((d) => d.reason)?.reason ??
+                null,
+        }
+        : null;
+    return { distractionFree, toggleDistractionFree, fullscreenConfirm: confirm };
+}

package/dist/app/useDocumentCreation.d.ts

@@ -0,0 +1,18 @@
+import { type Dispatch, type MutableRefObject, type SetStateAction } from "react";
+import { type LoadedDocument, type ViewMode } from "@rightkit/document-core/documents/types";
+import type { DocumentTabs } from "./useDocumentTabs.js";
+/** New-untitled / duplicate-as-draft creation and the txt keystroke path (edits + draft persistence). */
+export declare function useDocumentCreation(deps: {
+    untitledSeq: MutableRefObject<number>;
+    withTabKey: <T extends LoadedDocument>(doc: T, existingKey?: string) => T;
+    setOpenDocs: DocumentTabs["setOpenDocs"];
+    setActivePath: DocumentTabs["setActivePath"];
+    setViews: Dispatch<SetStateAction<Record<string, ViewMode>>>;
+    writeEdits: DocumentTabs["writeEdits"];
+    writeEditsLive: DocumentTabs["writeEditsLive"];
+    queueAutoSave: (path: string) => void;
+}): {
+    newDocument: (format?: "txt" | "md" | "docx") => void;
+    duplicateAsDraft: (text: string, toastMsg?: string) => void;
+    onTxtChange: (path: string, content: string, text: string) => void;
+};

package/dist/app/useDocumentCreation.js

@@ -0,0 +1,63 @@
+import { useCallback } from "react";
+import { docTitle, isUntitled } from "@rightkit/document-core/documents/types";
+import { bufferToBase64, createBlankDocxBuffer } from "@rightkit/docx-editor/documents/docx/blankDocx";
+import { clearDraft, clearFileDraft, writeDraftDebounced, writeFileDraftDebounced, } from "./documentDrafts.js";
+import { toast } from "@rightkit/platform-ui/headless";
+/** New-untitled / duplicate-as-draft creation and the txt keystroke path (edits + draft persistence). */
+export function useDocumentCreation(deps) {
+    const { untitledSeq, withTabKey, setOpenDocs, setActivePath, setViews, writeEdits, writeEditsLive, queueAutoSave, } = deps;
+    const newDocument = useCallback((format = "txt") => {
+        const path = `untitled:${untitledSeq.current++}`;
+        const content = format === "docx" ? bufferToBase64(createBlankDocxBuffer()) : "";
+        const doc = withTabKey({
+            path,
+            displayName: docTitle(path),
+            format,
+            content,
+        });
+        setOpenDocs((prev) => [...prev, doc]);
+        if (format !== "docx")
+            writeEdits((e) => ({ ...e, [path]: "" }));
+        setViews((v) => ({ ...v, [path]: "preview" }));
+        setActivePath(path);
+    }, [untitledSeq, writeEdits, setOpenDocs, setViews, setActivePath, withTabKey]);
+    // Duplicate a document's text into a new, never-saved draft (Word-style "make a copy") — leaves the
+    // original untouched on disk; the copy is a scratch buffer the user can edit and Save As later.
+    const duplicateAsDraft = useCallback((text, toastMsg = "Duplicated as a draft") => {
+        const path = `untitled:${untitledSeq.current++}`;
+        const doc = withTabKey({
+            path,
+            displayName: docTitle(path),
+            format: "txt",
+            content: "",
+        });
+        setOpenDocs((prev) => [...prev, doc]);
+        writeEdits((e) => ({ ...e, [path]: text }));
+        setViews((v) => ({ ...v, [path]: "preview" }));
+        setActivePath(path);
+        toast(toastMsg, "success");
+    }, [untitledSeq, writeEdits, setOpenDocs, setViews, setActivePath, withTabKey]);
+    const onTxtChange = useCallback((path, content, text) => {
+        // Keystroke path: writeEditsLive mutates editsRef + notifies only this path's live subscribers
+        // (the bottom-bar word-count/dirty and this tab's title) — App does NOT re-render. The save/dirty
+        // path reads editsRef, so it always sees the latest text.
+        writeEditsLive(path, text);
+        queueAutoSave(path);
+        // Untitled buffers: persist to draftKey so they restore on next launch. The write is debounced
+        // (T2-1) — clearDraft cancels any pending debounced write so an equal-to-saved edit can't be
+        // resurrected by a stale write landing after the clear.
+        if (isUntitled(path)) {
+            if (text === content)
+                clearDraft(path);
+            else
+                writeDraftDebounced(path, text);
+            return;
+        }
+        // File-backed txt (Notepad-style): persist edit + the disk base so we can detect stale drafts.
+        if (text === content)
+            clearFileDraft(path);
+        else
+            writeFileDraftDebounced(path, { base: content, text });
+    }, [queueAutoSave, writeEditsLive]);
+    return { newDocument, duplicateAsDraft, onTxtChange };
+}

package/dist/app/useDocumentDirty.d.ts

@@ -0,0 +1,31 @@
+import { type MutableRefObject } from "react";
+import { type LoadedDocument } from "@rightkit/document-core/documents/types";
+import type { BlockDraftRegistry } from "@rightkit/document-core/app/blockDrafts";
+import type { DocumentTabs } from "./useDocumentTabs.js";
+/** Dirty/title/draft read helpers (pure reads over tab refs + the block-draft registry). */
+export declare function useDocumentDirty(deps: {
+    blockDrafts: BlockDraftRegistry;
+    pdfDirtyRef: DocumentTabs["pdfDirtyRef"];
+    docxDirtyRef: DocumentTabs["docxDirtyRef"];
+    imageDirtyRef: DocumentTabs["imageDirtyRef"];
+    editsRef: MutableRefObject<Record<string, string>>;
+    htmlPagesRef: DocumentTabs["htmlPagesRef"];
+}): {
+    hasModifiedDraft: (path: string) => boolean;
+    snapshotModified: (path?: string) => Readonly<{
+        identity: import("@rightkit/document-core/app/blockDrafts").BlockDraftIdentity;
+        blockKind: string;
+        originalRevision: string | number;
+        sourceRange?: import("@rightkit/document-core/app/blockDrafts").BlockDraftSourceRange;
+        sourceChecksum?: string;
+        originalText: string;
+        currentText: string;
+        targetTag?: string;
+        selectionBookmark?: import("@rightkit/document-core/app/blockDrafts").BlockDraftSelectionBookmark;
+        status: import("@rightkit/document-core/app/blockDrafts").BlockDraftStatus;
+        reason?: string;
+        error?: string;
+    }>[];
+    isDirty: (doc: LoadedDocument) => boolean;
+    titleFor: (doc: LoadedDocument) => string;
+};

package/dist/app/useDocumentDirty.js

@@ -0,0 +1,46 @@
+import { useCallback } from "react";
+import { displayTitle, isUntitled, untitledTitle, } from "@rightkit/document-core/documents/types";
+import { isWebDocument } from "@rightkit/document-core/documents/web/webUrl";
+/** Dirty/title/draft read helpers (pure reads over tab refs + the block-draft registry). */
+export function useDocumentDirty(deps) {
+    const { blockDrafts, docxDirtyRef, pdfDirtyRef, editsRef, imageDirtyRef, htmlPagesRef } = deps;
+    const hasModifiedDraft = useCallback((path) => blockDrafts.snapshotModified(path).length > 0, [blockDrafts]);
+    const snapshotModified = useCallback((path) => blockDrafts.snapshotModified(path), [blockDrafts]);
+    const isDirty = useCallback((doc) => {
+        if (isWebDocument(doc))
+            return false;
+        if (doc.format === "pdf")
+            return pdfDirtyRef.current.has(doc.path);
+        // An open block draft counts as unsaved work (close/quit must resolve it).
+        if (hasModifiedDraft(doc.path))
+            return true;
+        if (doc.format === "docx")
+            return docxDirtyRef.current.has(doc.path);
+        if (doc.format === "image")
+            return imageDirtyRef.current.has(doc.path);
+        // Read the synchronous mirrors so a save/close in the same tick as a keystroke sees the latest
+        // text. Reactivity is preserved because every edit also calls a setter, which re-renders.
+        const entryDirty = (editsRef.current[doc.path] ?? doc.content) !== doc.content;
+        if (doc.format === "html") {
+            if (entryDirty)
+                return true;
+            // An HTML tab is also dirty if any navigated sub-page in its session has unsaved edits.
+            const session = htmlPagesRef.current[doc.path];
+            if (session)
+                for (const p in session)
+                    if (session[p].edited !== session[p].original)
+                        return true;
+            return false;
+        }
+        return entryDirty;
+    }, [hasModifiedDraft, docxDirtyRef, pdfDirtyRef, editsRef, imageDirtyRef, htmlPagesRef]);
+    // Reads editsRef.current (a live ref). Keystrokes never re-render App; the expanded-sidebar rows +
+    // the titlebar get LIVE untitled titles by subscribing to this doc's edit slice (LiveTitle/useEditText),
+    // which re-renders just that label and re-invokes titleFor with the fresh ref value.
+    const titleFor = useCallback((doc) => isWebDocument(doc)
+        ? doc.displayName
+        : isUntitled(doc.path)
+            ? untitledTitle(editsRef.current[doc.path] ?? "")
+            : displayTitle(doc.path), [editsRef]);
+    return { hasModifiedDraft, snapshotModified, isDirty, titleFor };
+}

package/dist/app/useDocumentLoader.d.ts

@@ -0,0 +1,55 @@
+import { type Dispatch, type MutableRefObject, type SetStateAction } from "react";
+import { type LoadedDocument, type ViewMeta, type ViewMode } from "@rightkit/document-core/documents/types";
+import { type FileEntry } from "../state/library.js";
+import type { DocumentTabs } from "./useDocumentTabs.js";
+export interface OpenDocumentOptions {
+    /** Add the tab without activating it. */
+    background?: boolean;
+    /** Skip the per-open recents refresh; the caller refreshes once after a batch. */
+    deferLibraryRefresh?: boolean;
+    /** Leave the current error banner alone. Session-restore opens use this so they cannot clear an
+     *  error they didn't set (e.g. a launched file that failed to open). Their own failures still
+     *  report. */
+    keepError?: boolean;
+    /** Place the new tab within the open-tab list (applied in the same state update that adds it), so
+     *  a batch opener can insert tabs at their final position instead of re-ordering them later. */
+    arrange?: (docs: LoadedDocument[]) => LoadedDocument[];
+}
+interface DocumentLoaderDeps {
+    openDocs: LoadedDocument[];
+    setOpenDocs: DocumentTabs["setOpenDocs"];
+    setViews: Dispatch<SetStateAction<Record<string, ViewMode>>>;
+    viewsRef: MutableRefObject<Record<string, ViewMode>>;
+    viewMetaRef: MutableRefObject<Record<string, ViewMeta>>;
+    writeEdits: DocumentTabs["writeEdits"];
+    setError: Dispatch<SetStateAction<string | null>>;
+    setOpeningPath: Dispatch<SetStateAction<string | null>>;
+    setActivePath: DocumentTabs["setActivePath"];
+    fingerprints: MutableRefObject<Map<string, {
+        mtimeMs: number;
+        size: number;
+    }>>;
+    refreshLibrary: () => Promise<void>;
+    syncPinned: (path: string) => Promise<void>;
+    isDirty: (doc: LoadedDocument) => boolean;
+    clearImageDirty: (path: string) => void;
+    withTabKey: <T extends LoadedDocument>(doc: T, existingKey?: string) => T;
+}
+/**
+ * Open/read paths into tabs: file-picker open, live-URL "tabs", reopening a known-recent entry, the
+ * open-file dialog, and paging to a sibling image in place. Extracted verbatim from useDocuments —
+ * bodies, error handling, restore-draft logic, and view-default selection are unchanged. `activate`
+ * stays with the orchestrator (it's just an activePath setter, and requestClose/doClose/reload all
+ * need it too), so loader functions take it as a dependency instead of owning it.
+ */
+export declare function useDocumentLoader({ openDocs, setOpenDocs, setViews, viewsRef, viewMetaRef, writeEdits, setError, setOpeningPath, setActivePath, fingerprints, refreshLibrary, syncPinned, isDirty, clearImageDirty, withTabKey, }: DocumentLoaderDeps): {
+    activate: (path: string) => Promise<void>;
+    open: (path: string, opts?: OpenDocumentOptions) => Promise<void>;
+    openLiveUrl: (input: string, opts?: {
+        background?: boolean;
+    }) => Promise<void>;
+    openRecent: (entry: FileEntry) => Promise<void>;
+    onOpenDialog: () => Promise<void>;
+    openImageSibling: (currentPath: string, targetPath: string) => Promise<void>;
+};
+export {};