@rightkit/document-workspace 0.0.0-stage → 0.1.1

package/dist/app/useOpenFromClipboard.js

@@ -0,0 +1,44 @@
+import { useCallback } from "react";
+import { toast } from "@rightkit/platform-ui/headless";
+import { normalizeLivePreviewUrl } from "@rightkit/document-core/documents/web/webUrl";
+import { addRecentUrl } from "@rightkit/document-core/state/recentUrls";
+import { readClipboardContent, openLinkedDocument } from "@rightkit/document-core/state/tauriBridge";
+import { errorMessage } from "@rightkit/document-core/state/errors";
+import { localPathFromClipboardText } from "./clipboardPaths.js";
+/** Open from clipboard: copied files (CF_HDROP) open like a drag-drop; nothing → a toast. */
+export function useOpenFromClipboard({ open, openLiveUrl, duplicateAsDraft, setError, }) {
+    return useCallback(async () => {
+        const clip = await readClipboardContent();
+        switch (clip.kind) {
+            case "files":
+                for (const p of clip.paths)
+                    void open(p);
+                return;
+            case "image":
+                void open(clip.path);
+                return;
+            case "text":
+                if (normalizeLivePreviewUrl(clip.text)) {
+                    addRecentUrl(clip.text.trim());
+                    void openLiveUrl(clip.text);
+                    return;
+                }
+                {
+                    const localPath = localPathFromClipboardText(clip.text);
+                    if (localPath) {
+                        const granted = await openLinkedDocument(localPath).catch((e) => {
+                            setError(errorMessage(e));
+                            return null;
+                        });
+                        if (granted)
+                            void open(granted);
+                        return;
+                    }
+                }
+                duplicateAsDraft(clip.text, "Pasted from clipboard");
+                return;
+            default:
+                toast("Nothing on the clipboard to open", "info");
+        }
+    }, [open, openLiveUrl, duplicateAsDraft, setError]);
+}

package/dist/app/usePaneLiveness.d.ts

@@ -0,0 +1,29 @@
+import type { LoadedDocument } from "@rightkit/document-core/documents/types";
+import type { BlockDraftRegistry } from "@rightkit/document-core/app/blockDrafts";
+interface PaneLivenessDeps {
+    openDocs: LoadedDocument[];
+    activePath: string | null;
+    isDirty: (doc: LoadedDocument) => boolean;
+    /** In-flight saves (useDocuments' pendingSavePaths) — a saving tab's router stays live. */
+    pendingSavePaths: ReadonlySet<string>;
+    /** True while the launch restore is in flight; gates the post-restore warm-up walk. */
+    restoringSession: boolean;
+    /** Block draft registry: a tab with any open block draft is never shelled (editor-owned state). */
+    blockDrafts?: BlockDraftRegistry;
+}
+/**
+ * Warm-MRU pane liveness: which open tabs keep a live router vs a lightweight shell. Every open
+ * tab keeps a shell; only active + most-recent ordinary panes stay live, and writes or dirty state
+ * without an app-owned source/draft snapshot protect a path until safe to evict. Owns the MRU
+ * history (`recentPaths`), the previous-active tracker, the warm-order persistence + post-restore
+ * warm-up walk, `protectedPaths`/`formatByPath`/`desiredLivePaths`, and the deferred rendered/live
+ * reconciliation. `pruneClosedPaths` is called by App's shared closed-tab eviction effect so
+ * rendered/live/recent markers die with their tab. Pure policy lives in tabMountPolicy.ts /
+ * tabWarmOrder.ts. Extracted verbatim from App.tsx; bodies are unchanged.
+ */
+export declare function usePaneLiveness({ openDocs, activePath, isDirty, pendingSavePaths, restoringSession, blockDrafts, }: PaneLivenessDeps): {
+    livePaths: Set<string>;
+    renderedPaths: Set<string>;
+    pruneClosedPaths: (closedPaths: string[]) => void;
+};
+export {};

package/dist/app/usePaneLiveness.js

@@ -0,0 +1,199 @@
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { documentHasPinnedState } from "@rightkit/document-core/app/resourceCensus";
+import { dirtyPaneMayShell, liveDocumentPaths } from "./tabMountPolicy.js";
+import { loadTabWarmOrder, restoredTabWarmOrder, saveTabWarmOrder } from "./tabWarmOrder.js";
+import { nativeAutomationOwnsSession } from "./useDocumentRuntimeEffects.js";
+import { scheduleAfterPaintOrDelay } from "@rightkit/document-core/app/deferredMount";
+/**
+ * Warm-MRU pane liveness: which open tabs keep a live router vs a lightweight shell. Every open
+ * tab keeps a shell; only active + most-recent ordinary panes stay live, and writes or dirty state
+ * without an app-owned source/draft snapshot protect a path until safe to evict. Owns the MRU
+ * history (`recentPaths`), the previous-active tracker, the warm-order persistence + post-restore
+ * warm-up walk, `protectedPaths`/`formatByPath`/`desiredLivePaths`, and the deferred rendered/live
+ * reconciliation. `pruneClosedPaths` is called by App's shared closed-tab eviction effect so
+ * rendered/live/recent markers die with their tab. Pure policy lives in tabMountPolicy.ts /
+ * tabWarmOrder.ts. Extracted verbatim from App.tsx; bodies are unchanged.
+ */
+export function usePaneLiveness({ openDocs, activePath, isDirty, pendingSavePaths, restoringSession, blockDrafts, }) {
+    const previousActiveRef = useRef(activePath);
+    const [previousActivePath, setPreviousActivePath] = useState(null);
+    useLayoutEffect(() => {
+        if (previousActiveRef.current === activePath)
+            return;
+        setPreviousActivePath(previousActiveRef.current);
+        previousActiveRef.current = activePath;
+    }, [activePath]);
+    // Presence-only subscription: re-derive protection when a document gains or loses a block draft
+    // (open / commit / discard). Typing inside a draft does not fire it.
+    const [draftPresenceTick, setDraftPresenceTick] = useState(0);
+    useEffect(() => {
+        if (!blockDrafts)
+            return;
+        setDraftPresenceTick((tick) => tick + 1);
+        return blockDrafts.subscribePresence(() => setDraftPresenceTick((tick) => tick + 1));
+    }, [blockDrafts]);
+    // Every open tab keeps a lightweight shell. Only active + most-recent ordinary panes stay live;
+    // writes or dirty state without an app-owned source/draft snapshot add a path until safe to evict.
+    // biome-ignore lint/correctness/useExhaustiveDependencies: draftPresenceTick re-derives the set when a block draft opens or closes
+    const protectedPaths = useMemo(() => new Set(openDocs
+        .filter((doc) => {
+        // Switching tabs is the re-render boundary for ref-backed text edits. Read the just-
+        // departed active document here before after-paint reconciliation can evict its router.
+        const dirty = isDirty(doc);
+        if (doc.path === activePath && dirty)
+            return true;
+        // An open block draft (clean or modified) lives in its mounted editor, not in editsRef;
+        // shelling would orphan it. Protection ends when the draft is committed or discarded.
+        if (blockDrafts?.hasDraft(doc.path))
+            return true;
+        // TXT/Markdown sources are synchronously authoritative in editsRef; HTML entry and
+        // sub-page sources are synchronously authoritative in htmlPagesRef. Modified rich
+        // blocks use the app-owned registry. Those formats may therefore shell while dirty,
+        // but only through this narrow, explicit allow-list. DOCX/PDF fail closed; image
+        // remains governed by its recipe census.
+        const hasExternalSourceOrDraftOwner = doc.format === "txt" || doc.format === "md" || doc.format === "html";
+        const dirtyProtection = doc.format === "image"
+            ? documentHasPinnedState(doc.path)
+            : dirty && !dirtyPaneMayShell(doc.format, hasExternalSourceOrDraftOwner);
+        return dirtyProtection || pendingSavePaths.has(doc.path);
+    })
+        .map((doc) => doc.path)), [activePath, blockDrafts, draftPresenceTick, isDirty, openDocs, pendingSavePaths]);
+    // Background tabs keep lightweight shells. Active mounts synchronously in DocumentRouterTable;
+    // these sets only record visited paths & reconcile active/MRU/protected ownership after paint.
+    const [renderedPaths, setRenderedPaths] = useState(() => new Set());
+    const [livePaths, setLivePaths] = useState(() => new Set());
+    // Most-recently-active paths, newest first. Held as state (not a ref) because `desiredLivePaths`
+    // memoizes on it: a ref would mutate without re-running the memo, so a revisited tab would never
+    // re-enter the live set. Updated only when the active tab actually changes, so its identity is
+    // stable across unrelated renders and the after-paint reconciliation below cannot loop.
+    const automationOwnsSession = nativeAutomationOwnsSession();
+    const savedWarmOrder = useRef(automationOwnsSession ? [] : loadTabWarmOrder());
+    const restoreStarted = useRef(false);
+    const [warmOrderReady, setWarmOrderReady] = useState(false);
+    const [recentPaths, setRecentPaths] = useState(() => []);
+    useEffect(() => {
+        if (!activePath)
+            return;
+        setRecentPaths((prev) => {
+            if (prev[0] === activePath)
+                return prev;
+            return [activePath, ...prev.filter((path) => path !== activePath)];
+        });
+    }, [activePath]);
+    // Session restore loads file bytes & chunks in the background, but a restored router still used
+    // to cold-mount on first click because its in-memory MRU vanished at quit. Rebuild that bounded
+    // warm set after restore, one pane per quiet interval: prior activation order first, then tabs
+    // nearest the active one. User activity cancels remaining speculative work.
+    useEffect(() => {
+        if (restoringSession) {
+            restoreStarted.current = true;
+            return;
+        }
+        if (!restoreStarted.current)
+            return;
+        restoreStarted.current = false;
+        if (automationOwnsSession)
+            return;
+        setWarmOrderReady(true);
+        const queue = restoredTabWarmOrder(openDocs.map((doc) => doc.path), activePath, savedWarmOrder.current);
+        let index = 0;
+        let timer = 0;
+        const warmNext = () => {
+            const path = queue[index++];
+            if (!path)
+                return;
+            setRecentPaths((prev) => (prev.includes(path) ? prev : [...prev, path]));
+            timer = window.setTimeout(warmNext, 250);
+        };
+        timer = window.setTimeout(warmNext, 250);
+        return () => window.clearTimeout(timer);
+    }, [activePath, automationOwnsSession, openDocs, restoringSession]);
+    useEffect(() => {
+        if (!warmOrderReady || automationOwnsSession)
+            return;
+        saveTabWarmOrder(recentPaths);
+    }, [automationOwnsSession, recentPaths, warmOrderReady]);
+    useEffect(() => {
+        const openPaths = new Set(openDocs.map((doc) => doc.path));
+        setRecentPaths((prev) => {
+            const next = prev.filter((path) => openPaths.has(path));
+            return next.length === prev.length ? prev : next;
+        });
+    }, [openDocs]);
+    // Format per open path, so a SHELLED heavyweight document's mount-policy cost doesn't decay to
+    // ordinary weight merely because its census resources were released on eviction — see
+    // `candidateWeight` in tabMountPolicy.ts.
+    const formatByPath = useMemo(() => {
+        const map = new Map();
+        for (const doc of openDocs) {
+            if (doc.format === "txt" ||
+                doc.format === "md" ||
+                doc.format === "mdx" ||
+                doc.format === "html" ||
+                doc.format === "web" ||
+                doc.format === "docx" ||
+                doc.format === "pdf" ||
+                doc.format === "image")
+                map.set(doc.path, doc.format);
+        }
+        return map;
+    }, [openDocs]);
+    const desiredLivePaths = useMemo(() => liveDocumentPaths({
+        activePath,
+        previousActivePath,
+        protectedPaths,
+        recentPaths: recentPaths.filter((path) => formatByPath.has(path)),
+        formatByPath,
+    }), [activePath, previousActivePath, protectedPaths, recentPaths, formatByPath]);
+    // Active routers bypass this deferred state below, so a tab click mounts its viewer in the same
+    // commit and never paints an empty shell. Reconciliation remains deferred so eviction/cleanup
+    // cannot compete with activation work on the click frame.
+    useEffect(() => {
+        const target = desiredLivePaths;
+        return scheduleAfterPaintOrDelay(() => {
+            setRenderedPaths((prev) => {
+                const next = new Set(prev);
+                for (const path of target)
+                    next.add(path);
+                if (next.size === prev.size && [...next].every((path) => prev.has(path)))
+                    return prev;
+                return next;
+            });
+            setLivePaths((prev) => {
+                if (prev.size === target.size && [...prev].every((path) => target.has(path)))
+                    return prev;
+                return new Set(target);
+            });
+        });
+    }, [desiredLivePaths]);
+    // T5-2: drop closed tabs' keep-alive markers — otherwise renderedPaths grows for the life of the
+    // app instead of tracking only the currently-open tabs, and without the recentPaths prune the MRU
+    // window fills with closed paths (which both starves live slots from the tabs actually open and
+    // lets a reopened path inherit stale recency it did not earn). Called by App's shared closed-tab
+    // eviction effect once it has diffed openDocs, so all per-path cache/liveness cleanup still runs
+    // in the same pass.
+    const pruneClosedPaths = useCallback((closedPaths) => {
+        setRenderedPaths((prevRendered) => {
+            if (!closedPaths.some((p) => prevRendered.has(p)))
+                return prevRendered;
+            const next = new Set(prevRendered);
+            for (const p of closedPaths)
+                next.delete(p);
+            return next;
+        });
+        setLivePaths((prevLive) => {
+            if (!closedPaths.some((p) => prevLive.has(p)))
+                return prevLive;
+            const next = new Set(prevLive);
+            for (const p of closedPaths)
+                next.delete(p);
+            return next;
+        });
+        setRecentPaths((prevRecent) => {
+            if (!closedPaths.some((p) => prevRecent.includes(p)))
+                return prevRecent;
+            return prevRecent.filter((p) => !closedPaths.includes(p));
+        });
+    }, []);
+    return { livePaths, renderedPaths, pruneClosedPaths };
+}

package/dist/app/usePendingSavePaths.d.ts

@@ -0,0 +1,19 @@
+interface PendingSavePathsDeps {
+    /** The raw DOCX persist (useFormatDirtyState's onDocxSave) — wrapped here with pending tracking. */
+    persistDocx: (path: string, buffer: ArrayBuffer) => Promise<void>;
+    /** useDocumentSaver's own pending set (text/image saves in flight). */
+    saverPendingSavePaths: ReadonlySet<string>;
+}
+/**
+ * The union of all in-flight save paths across the three save surfaces — the saver's own pending
+ * set (text/image writes), tracked DOCX binary writes, and per-page HTML session writes — exposed
+ * as `pendingSavePaths` so the shell keeps a tab's router pinned while a save is in flight.
+ * Extracted verbatim from useDocuments; bodies are unchanged.
+ */
+export declare function usePendingSavePaths({ persistDocx, saverPendingSavePaths }: PendingSavePathsDeps): {
+    onDocxSave: (path: string, buffer: ArrayBuffer) => Promise<void>;
+    onHtmlSaveActivity: (entryPath: string, delta: 1 | -1) => void;
+    pendingSavePaths: Set<string>;
+    pendingSavePathsRef: import("react").RefObject<ReadonlySet<string>>;
+};
+export {};

package/dist/app/usePendingSavePaths.js

@@ -0,0 +1,67 @@
+import { useCallback, useMemo, useRef, useState } from "react";
+/**
+ * The union of all in-flight save paths across the three save surfaces — the saver's own pending
+ * set (text/image writes), tracked DOCX binary writes, and per-page HTML session writes — exposed
+ * as `pendingSavePaths` so the shell keeps a tab's router pinned while a save is in flight.
+ * Extracted verbatim from useDocuments; bodies are unchanged.
+ */
+export function usePendingSavePaths({ persistDocx, saverPendingSavePaths }) {
+    const pendingDocxSaveCounts = useRef(new Map());
+    const [pendingDocxSavePaths, setPendingDocxSavePaths] = useState(() => new Set());
+    const pendingHtmlSaveCounts = useRef(new Map());
+    const [pendingHtmlSavePaths, setPendingHtmlSavePaths] = useState(() => new Set());
+    const pendingSavePathsRef = useRef(new Set());
+    const onHtmlSaveActivity = useCallback((entryPath, delta) => {
+        const nextCount = Math.max(0, (pendingHtmlSaveCounts.current.get(entryPath) ?? 0) + delta);
+        if (nextCount > 0)
+            pendingHtmlSaveCounts.current.set(entryPath, nextCount);
+        else
+            pendingHtmlSaveCounts.current.delete(entryPath);
+        const pendingNow = new Set(pendingSavePathsRef.current);
+        if (nextCount > 0)
+            pendingNow.add(entryPath);
+        else
+            pendingNow.delete(entryPath);
+        pendingSavePathsRef.current = pendingNow;
+        setPendingHtmlSavePaths((prev) => {
+            if (nextCount > 0 === prev.has(entryPath))
+                return prev;
+            const next = new Set(prev);
+            if (nextCount > 0)
+                next.add(entryPath);
+            else
+                next.delete(entryPath);
+            return next;
+        });
+    }, []);
+    const onDocxSave = useCallback(async (path, buffer) => {
+        pendingDocxSaveCounts.current.set(path, (pendingDocxSaveCounts.current.get(path) ?? 0) + 1);
+        const pendingNow = new Set(pendingSavePathsRef.current);
+        pendingNow.add(path);
+        pendingSavePathsRef.current = pendingNow;
+        setPendingDocxSavePaths((prev) => (prev.has(path) ? prev : new Set(prev).add(path)));
+        try {
+            await persistDocx(path, buffer);
+        }
+        finally {
+            const remaining = (pendingDocxSaveCounts.current.get(path) ?? 1) - 1;
+            if (remaining > 0)
+                pendingDocxSaveCounts.current.set(path, remaining);
+            else {
+                pendingDocxSaveCounts.current.delete(path);
+                const pendingNow = new Set(pendingSavePathsRef.current);
+                pendingNow.delete(path);
+                pendingSavePathsRef.current = pendingNow;
+                setPendingDocxSavePaths((prev) => {
+                    if (!prev.has(path))
+                        return prev;
+                    const next = new Set(prev);
+                    next.delete(path);
+                    return next;
+                });
+            }
+        }
+    }, [persistDocx]);
+    const pendingSavePaths = useMemo(() => new Set([...saverPendingSavePaths, ...pendingDocxSavePaths, ...pendingHtmlSavePaths]), [saverPendingSavePaths, pendingDocxSavePaths, pendingHtmlSavePaths]);
+    return { onDocxSave, onHtmlSaveActivity, pendingSavePaths, pendingSavePathsRef };
+}

package/dist/app/useReadyShow.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The window launches hidden (tauri.conf.json `"visible": false`) and is revealed the instant React
+ * commits its first frame. We use useLayoutEffect: it runs synchronously right after the DOM is
+ * committed and — unlike requestAnimationFrame — fires even while the window is hidden. A hidden
+ * macOS WKWebView never schedules rAF (no compositing off-screen), so the old rAF-gated reveal always
+ * fell through to the safety timeout and cost ~4s on every macOS launch. Committing-then-showing is
+ * deterministic and instant on both macOS and Windows; the native surface is pre-painted to the theme
+ * color in showWindow() so the reveal never flashes white. Idempotent (shows once) so StrictMode's
+ * double-invoke in dev is harmless.
+ *
+ */
+export declare function useReadyShow(beforeShow?: () => void | Promise<void>): void;

package/dist/app/useReadyShow.js

@@ -0,0 +1,142 @@
+import { useLayoutEffect } from "react";
+import { getCurrentWindow } from "@tauri-apps/api/window";
+import { logError, logPerf } from "@rightkit/document-core/state/diagnostics";
+// Captured at module load (early in the import graph) so app:shown measures from near-boot.
+const bootStartedAt = performance.now();
+let shown = false;
+// WebView2 can briefly reveal the native surface while maximizing. Match it to the selected reading
+// pane so exposed resize pixels blend into the document instead of flashing white.
+function nativeColor(value) {
+    const channels = value.match(/^rgba?\(\s*([\d.]+)[,\s]+([\d.]+)[,\s]+([\d.]+)(?:\s*[,/]\s*([\d.]+%?))?\s*\)$/i);
+    if (!channels)
+        return value;
+    const byte = (channel) => Math.round(Math.max(0, Math.min(255, Number(channel))));
+    const alpha = channels[4]
+        ? Math.round(Math.max(0, Math.min(1, channels[4].endsWith("%")
+            ? Number(channels[4].slice(0, -1)) / 100
+            : Number(channels[4]))) * 255)
+        : 255;
+    return [byte(channels[1]), byte(channels[2]), byte(channels[3]), alpha];
+}
+function currentReaderBackground() {
+    try {
+        const htmlSurface = document
+            .querySelector('[data-vr-pane-state="active"] iframe[data-vr-html-surface]')
+            ?.dataset.vrHtmlSurface?.trim();
+        if (htmlSurface)
+            return nativeColor(htmlSurface);
+        const v = getComputedStyle(document.documentElement)
+            .getPropertyValue("--reader-surface")
+            .trim();
+        return v || "#F7F3EC";
+    }
+    catch {
+        return "#F7F3EC";
+    }
+}
+async function setNativeBackground() {
+    await getCurrentWindow().setBackgroundColor(currentReaderBackground());
+}
+function showWindow(beforeShow) {
+    if (shown)
+        return;
+    shown = true;
+    void Promise.resolve()
+        .then(async () => {
+        const win = getCurrentWindow();
+        // Set the native surface to the theme color FIRST, then reveal — so even the single composite
+        // between show() and the webview's first paint is themed, never white.
+        try {
+            await win.setBackgroundColor(currentReaderBackground());
+        }
+        catch {
+            if ("__TAURI_INTERNALS__" in window) {
+                logError("window:background-color-failed");
+            }
+        }
+        let resizeStartedAt;
+        let resizeTimer;
+        void win
+            .onResized(() => {
+            resizeStartedAt ??= performance.now();
+            window.clearTimeout(resizeTimer);
+            resizeTimer = window.setTimeout(() => {
+                const startedAt = resizeStartedAt;
+                if (startedAt === undefined)
+                    return;
+                logPerf("window:resize", startedAt);
+                resizeStartedAt = undefined;
+            }, 150);
+        })
+            .then((unlisten) => window.addEventListener("beforeunload", unlisten, { once: true }))
+            .catch(() => {
+            if ("__TAURI_INTERNALS__" in window) {
+                logError("window:resize-listener-failed");
+            }
+        });
+        // Caller-supplied pre-reveal step (e.g. the legal gate resizing/centering the window to its
+        // own 960x560 before it becomes visible) so the FIRST thing the user ever sees is already the
+        // right size — never a flash of the full app window followed by a shrink.
+        if (beforeShow) {
+            try {
+                await beforeShow();
+            }
+            catch {
+                // Best-effort — a failed resize must never block the reveal itself.
+            }
+        }
+        await win.show();
+    })
+        .then(() => logPerf("app:shown", bootStartedAt))
+        .catch(() => {
+        // Browser QA has no Tauri window; the app remains visible in that environment.
+    });
+}
+/**
+ * The window launches hidden (tauri.conf.json `"visible": false`) and is revealed the instant React
+ * commits its first frame. We use useLayoutEffect: it runs synchronously right after the DOM is
+ * committed and — unlike requestAnimationFrame — fires even while the window is hidden. A hidden
+ * macOS WKWebView never schedules rAF (no compositing off-screen), so the old rAF-gated reveal always
+ * fell through to the safety timeout and cost ~4s on every macOS launch. Committing-then-showing is
+ * deterministic and instant on both macOS and Windows; the native surface is pre-painted to the theme
+ * color in showWindow() so the reveal never flashes white. Idempotent (shows once) so StrictMode's
+ * double-invoke in dev is harmless.
+ *
+ */
+export function useReadyShow(beforeShow) {
+    useLayoutEffect(() => {
+        showWindow(beforeShow);
+        const isTauri = "__TAURI_INTERNALS__" in window;
+        let color = JSON.stringify(currentReaderBackground());
+        const refreshBackground = () => {
+            const next = currentReaderBackground();
+            const serialized = JSON.stringify(next);
+            if (serialized === color)
+                return;
+            color = serialized;
+            void setNativeBackground().catch(() => {
+                if (isTauri)
+                    logError("window:background-color-failed");
+            });
+        };
+        const rootObserver = new MutationObserver(refreshBackground);
+        rootObserver.observe(document.documentElement, {
+            attributes: true,
+            attributeFilter: ["style"],
+        });
+        const paneObserver = new MutationObserver(refreshBackground);
+        paneObserver.observe(document.documentElement, {
+            attributes: true,
+            subtree: true,
+            attributeFilter: ["data-vr-pane-state", "data-vr-html-surface"],
+        });
+        // beforeShow is intentionally a dependency: re-running this effect after the window has already
+        // shown is a harmless no-op (`showWindow`'s module-level `shown` guard short-circuits it), so callers
+        // that pass a beforeShow whose identity changes (e.g. AppRoot's resize callback, stable via
+        // useCallback but re-created when the legal-gate/app decision flips) never risk a stale closure.
+        return () => {
+            rootObserver.disconnect();
+            paneObserver.disconnect();
+        };
+    }, [beforeShow]);
+}

package/dist/app/useSearchController.d.ts

@@ -0,0 +1,22 @@
+import type { LoadedDocument, SearchProvider } from "@rightkit/document-core/documents/types";
+export type SearchScope = "current" | "all";
+/**
+ * Shared find/replace controller. With keep-alive, several viewers can be mounted at once, so search
+ * providers are registered PATH-SCOPED (each viewer registers its own path's provider on mount /
+ * null on unmount); the LIVE provider that Find uses is the active tab's, re-selected on tab switch
+ * (NOT on remount). Also owns find-bar open/replace state and the single toolbar FindBar element.
+ */
+export declare function useSearchController(activePath: string | null, active: LoadedDocument | null, openDocs?: LoadedDocument[], activate?: (path: string) => Promise<void>): {
+    searchProvider: SearchProvider | null;
+    registerSearchProvider: (path: string, provider: SearchProvider | null) => void;
+    openFind: (replace: boolean) => void;
+    closeFind: () => void;
+    toggleFind: (replace: boolean) => void;
+    openFindAll: () => void;
+    findBarEl: import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | null;
+    canOpenFind: boolean;
+    findOpen: boolean;
+    findMode: "find" | "replace" | undefined;
+    scope: SearchScope;
+    setScope: import("react").Dispatch<import("react").SetStateAction<SearchScope>>;
+};

package/dist/app/useSearchController.js

@@ -0,0 +1,114 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { FindBar } from "./FindBar.js";
+import { buildCrossDocProvider } from "./useCrossDocSearch.js";
+/** Formats whose find surface registers asynchronously, so Find may open before its provider exists. */
+const EARLY_FIND_FORMATS = new Set(["html", "docx", "md", "mdx"]);
+/**
+ * Shared find/replace controller. With keep-alive, several viewers can be mounted at once, so search
+ * providers are registered PATH-SCOPED (each viewer registers its own path's provider on mount /
+ * null on unmount); the LIVE provider that Find uses is the active tab's, re-selected on tab switch
+ * (NOT on remount). Also owns find-bar open/replace state and the single toolbar FindBar element.
+ */
+export function useSearchController(activePath, active, openDocs, activate) {
+    const [searchProvider, setSearchProvider] = useState(null);
+    const [findState, setFindState] = useState({ open: false, replace: false });
+    const [scope, setScope] = useState("current");
+    const providers = useRef(new Map());
+    const activePathRef = useRef(activePath);
+    activePathRef.current = activePath;
+    const crossDocRef = useRef(null);
+    // Latest state mirrors for callbacks that must keep a stable identity across a find session.
+    const searchProviderRef = useRef(null);
+    searchProviderRef.current = searchProvider;
+    const findStateRef = useRef(findState);
+    findStateRef.current = findState;
+    // A viewer registers (provider) / unregisters (null) its OWN path. If it's the active tab, it also
+    // becomes the live provider immediately.
+    const registerSearchProvider = useCallback((path, provider) => {
+        if (provider)
+            providers.current.set(path, provider);
+        else
+            providers.current.delete(path);
+        if (path === activePathRef.current)
+            setSearchProvider(provider);
+    }, []);
+    // On tab switch, swap to that tab's already-registered provider (warm panes don't remount).
+    // In "all" scope, build a cross-doc provider aggregating all warm tabs. It is rebuilt only when
+    // the set of open tabs changes: stepping to a match in another tab activates that tab, and
+    // rebuilding then would reset the match position to the first tab.
+    const openDocsRef = useRef(openDocs);
+    openDocsRef.current = openDocs;
+    const activateRef = useRef(activate);
+    activateRef.current = activate;
+    const crossDocScope = scope === "all" && !!openDocs && !!activate;
+    const openPathsKey = openDocs?.map((doc) => doc.path).join("\0") ?? "";
+    const followedPath = crossDocScope ? null : activePath;
+    useEffect(() => {
+        const docs = openDocsRef.current;
+        if (crossDocScope && docs && openPathsKey && providers.current.size >= 2) {
+            // Tear down previous cross-doc provider.
+            crossDocRef.current?.close();
+            const crossDoc = buildCrossDocProvider(providers.current, docs, (path) => activateRef.current ? activateRef.current(path) : Promise.resolve());
+            crossDocRef.current = crossDoc;
+            setSearchProvider(crossDoc);
+        }
+        else {
+            crossDocRef.current?.close();
+            crossDocRef.current = null;
+            setSearchProvider(providers.current.get(followedPath ?? activePathRef.current ?? "") ?? null);
+        }
+    }, [crossDocScope, openPathsKey, followedPath]);
+    const openFind = useCallback((replace) => {
+        setFindState({ open: true, replace });
+    }, []);
+    const openFindAll = useCallback(() => {
+        setScope("all");
+        setFindState({ open: true, replace: false });
+    }, []);
+    // Open even if the provider is still racing into place (HTML Safe render registers on iframe load;
+    // Interactive registers a postMessage-driven preview provider; DOCX registers when its editor view
+    // is ready; Markdown/MDX register once the ProseMirror view mounts). When the HTML source drawer is
+    // open it registers a "source" provider instead.
+    //
+    // Every format that owns a find surface must be listed in EARLY_FIND_FORMATS. Markdown was
+    // missing, so Cmd/Ctrl+F was a silent no-op on a .md tab until its editor happened to win the
+    // race — the failure mode is invisible (no error, nothing opens), which is why it went unnoticed.
+    const canOpenFind = !!searchProvider || (!!active?.format && EARLY_FIND_FORMATS.has(active.format));
+    const canCrossDoc = !!openDocs && openDocs.length >= 2;
+    // closeFind/toggleFind read live state through refs, so their identities stay stable for the
+    // whole find session instead of changing on every provider or open/replace transition.
+    const closeFind = useCallback(() => {
+        setFindState((current) => ({ ...current, open: false }));
+        crossDocRef.current?.close();
+        crossDocRef.current = null;
+        searchProviderRef.current?.close();
+    }, []);
+    const toggleFind = useCallback((replace) => {
+        const current = findStateRef.current;
+        if (current.open && current.replace === replace) {
+            closeFind();
+            return;
+        }
+        setFindState({ open: true, replace });
+    }, [closeFind]);
+    const findBarEl = active && findState.open && searchProvider ? (_jsx(FindBar, { provider: searchProvider, placement: active.format === "txt" ? "floating" : "toolbar", initialReplaceMode: findState.replace, scope: scope, onScopeChange: setScope, canCrossDoc: canCrossDoc, onClose: closeFind })) : null;
+    return {
+        searchProvider,
+        registerSearchProvider,
+        openFind,
+        closeFind,
+        toggleFind,
+        openFindAll,
+        findBarEl,
+        canOpenFind,
+        findOpen: findState.open,
+        findMode: findState.open
+            ? findState.replace
+                ? "replace"
+                : "find"
+            : undefined,
+        scope,
+        setScope,
+    };
+}