@rightkit/document-workspace 0.0.0-stage → 0.1.0

package/dist/app/useDocumentTabs.js

@@ -0,0 +1,207 @@
+import { useCallback, useEffect, useReducer, useRef, useState } from "react";
+/**
+ * The shared open-document state: tabs (openDocs + activePath), per-path unsaved TXT buffers
+ * (edits, with a synchronous editsRef mirror so a save/close in the same tick as a keystroke reads
+ * the latest text), the DOCX dirty set, and the per-HTML-session sub-page buffers. Owned separately
+ * so useViewState/useLibrary can take activePath/openDocs while useDocuments takes the setters
+ * (breaks the otherwise-circular wiring).
+ */
+export function useDocumentTabs() {
+    const [openDocs, setOpenDocs] = useState([]);
+    const [activePath, setActivePath] = useState(null);
+    // editsRef + a per-path pub/sub ARE the unsaved-text store (the single source of truth — NOT React
+    // state). A keystroke mutates the ref and notifies ONLY that path's subscribers (the active editor's
+    // bottom-bar word-count/dirty and that tab's title), so App and the rest of the chrome never re-render
+    // on a keystroke. `bumpEdits` exists only to re-render App on the rare EXTERNAL write
+    // (reopen/conflict/restore/save) so the controlled editor's `text` prop re-reads the ref.
+    const editsRef = useRef({});
+    const [, bumpEdits] = useReducer((n) => n + 1, 0);
+    const editsSubsRef = useRef(new Map());
+    const liveNotifyTimersRef = useRef(new Map());
+    const notifyEdits = useCallback((path) => {
+        // Snapshot the Set before iterating: a subscriber that unsubscribes inside its own callback would
+        // otherwise make Set.forEach skip not-yet-visited callbacks in the same pass.
+        const cbs = editsSubsRef.current.get(path);
+        if (cbs)
+            for (const cb of [...cbs])
+                cb();
+    }, []);
+    const scheduleLiveNotify = useCallback((path) => {
+        const existing = liveNotifyTimersRef.current.get(path);
+        if (existing)
+            clearTimeout(existing);
+        liveNotifyTimersRef.current.set(path, setTimeout(() => {
+            liveNotifyTimersRef.current.delete(path);
+            notifyEdits(path);
+        }, 90));
+    }, [notifyEdits]);
+    const clearLiveNotify = useCallback((path) => {
+        const existing = liveNotifyTimersRef.current.get(path);
+        if (!existing)
+            return;
+        clearTimeout(existing);
+        liveNotifyTimersRef.current.delete(path);
+    }, []);
+    useEffect(() => () => {
+        for (const timer of liveNotifyTimersRef.current.values())
+            clearTimeout(timer);
+        liveNotifyTimersRef.current.clear();
+    }, []);
+    const subscribeEdits = useCallback((path, cb) => {
+        let set = editsSubsRef.current.get(path);
+        if (!set) {
+            set = new Set();
+            editsSubsRef.current.set(path, set);
+        }
+        set.add(cb);
+        return () => {
+            set.delete(cb);
+            if (set.size === 0)
+                editsSubsRef.current.delete(path);
+        };
+    }, []);
+    const getEditSnapshot = useCallback((path) => editsRef.current[path], []);
+    // Origin tag for external ingress: bumped ONLY by writeEdits (reopen/reload/restore/conflict/
+    // duplicate) when a path's value actually changes — never by writeEditsLive (core publishes).
+    // The Markdown core provider applies external text only when this advances past what it applied.
+    const externalSeqRef = useRef({});
+    const getExternalSeq = useCallback((path) => externalSeqRef.current[path] ?? 0, []);
+    // Keystroke path: mutate the ref synchronously + debounce this path's live chrome subscribers. No App
+    // re-render. Saves/closes read editsRef immediately, while title/word-count repaint once after a burst
+    // of typing instead of making a React commit for every key.
+    const writeEditsLive = useCallback((path, text) => {
+        editsRef.current[path] = text;
+        scheduleLiveNotify(path);
+    }, [scheduleLiveNotify]);
+    // External path (reopen/conflict/restore/save/duplicate): mutate the ref, notify any changed path's
+    // subscribers, and bump so App re-renders once and the controlled editor re-syncs from the ref.
+    const writeEdits = useCallback((updater) => {
+        const prev = editsRef.current;
+        editsRef.current = updater(prev);
+        for (const path of new Set([...Object.keys(prev), ...Object.keys(editsRef.current)])) {
+            if (editsRef.current[path] !== prev[path])
+                externalSeqRef.current[path] = (externalSeqRef.current[path] ?? 0) + 1;
+        }
+        for (const path of editsSubsRef.current.keys()) {
+            if (editsRef.current[path] !== prev[path]) {
+                clearLiveNotify(path);
+                notifyEdits(path);
+            }
+        }
+        bumpEdits();
+    }, [clearLiveNotify, notifyEdits]);
+    const [docxDirty, setDocxDirtyState] = useState(new Set());
+    const docxDirtyRef = useRef(new Set());
+    const setDocxDirty = useCallback((next) => {
+        const value = typeof next === "function"
+            ? next(docxDirtyRef.current)
+            : next;
+        docxDirtyRef.current = value;
+        setDocxDirtyState(value);
+    }, []);
+    const [pdfDirty, setPdfDirtyState] = useState(new Set());
+    const pdfDirtyRef = useRef(new Set());
+    const setPdfDirty = useCallback((next) => {
+        const value = typeof next === "function"
+            ? next(pdfDirtyRef.current)
+            : next;
+        pdfDirtyRef.current = value;
+        setPdfDirtyState(value);
+    }, []);
+    // Text/HTML keep their buffers here; binary editors contribute path markers to the same tab store.
+    const [imageDirty, setImageDirtyState] = useState(new Set());
+    const imageDirtyRef = useRef(new Set());
+    const setImageDirty = useCallback((next) => {
+        const value = typeof next === "function"
+            ? next(imageDirtyRef.current)
+            : next;
+        imageDirtyRef.current = value;
+        setImageDirtyState(value);
+    }, []);
+    // HTML site sessions. Sub-page buffers live here (App level), not inside HtmlDocument, because only
+    // the active document is mounted — component state would be lost on a tab switch and invisible to
+    // the window-quit guard. The synchronous htmlPagesRef mirror lets a save/close read the latest
+    // edits in the same tick as a keystroke (same pattern as editsRef).
+    const [htmlPages, setHtmlPages] = useState({});
+    const htmlPagesRef = useRef({});
+    // T2-3: the React-state publish below feeds App's per-path html props (htmlPropsFor), which cascade
+    // into a DocumentRouter re-render — debounce it for the per-keystroke edit path (typing in an HTML
+    // sub-page) so that doesn't storm the whole app. `htmlPagesRef` is updated SYNCHRONOUSLY on every
+    // call regardless of debounce, so save/dirty logic (which reads the ref, not this state) is never
+    // stale; `notifyEdits` also stays synchronous so the bottom-bar/tab dirty marker stays live. Every
+    // caller EXCEPT the live-typing path (useHtmlSession's setHtmlPageEdited) passes immediate=true
+    // (the default), which also FLUSHES any pending debounced publish — save/discard/reload always see
+    // the latest buffer, so the state is never stale when it actually matters.
+    const htmlPagesPublishTimerRef = useRef(null);
+    const writeHtmlPages = useCallback((updater, options = {}) => {
+        htmlPagesRef.current = updater(htmlPagesRef.current);
+        // Notify entry-path subscribers so the bottom bar's isDirty(htmlDoc) — which folds in sub-page
+        // dirtiness — re-evaluates live while editing a navigated sub-page (no tab switch needed).
+        for (const entryPath of Object.keys(htmlPagesRef.current))
+            notifyEdits(entryPath);
+        if (options.immediate === false) {
+            if (htmlPagesPublishTimerRef.current != null)
+                clearTimeout(htmlPagesPublishTimerRef.current);
+            htmlPagesPublishTimerRef.current = setTimeout(() => {
+                htmlPagesPublishTimerRef.current = null;
+                setHtmlPages(htmlPagesRef.current);
+            }, 300);
+            return;
+        }
+        if (htmlPagesPublishTimerRef.current != null) {
+            clearTimeout(htmlPagesPublishTimerRef.current);
+            htmlPagesPublishTimerRef.current = null;
+        }
+        setHtmlPages(htmlPagesRef.current);
+    }, [notifyEdits]);
+    useEffect(() => () => {
+        if (htmlPagesPublishTimerRef.current != null)
+            clearTimeout(htmlPagesPublishTimerRef.current);
+    }, []);
+    // entryPath → the in-site page currently shown in that HTML tab (roams as the user navigates).
+    // App needs it for Ctrl+S / Save targeting and the per-page dirty indicator.
+    const [htmlActivePage, setHtmlActivePage] = useState({});
+    // MDX component-import grants. Unlike HTML sub-pages, these have no editable buffer — the sandboxed
+    // iframe only reads them at compile time — so a plain ref (entryPath -> Set<grantedSubPath>) is
+    // enough bookkeeping. Tracked so the owning tab's close can revoke them (mirrors htmlPagesRef's
+    // shape one level down: Map<entryPath, Set<subPath>> instead of Map<entryPath, Map<subPath, buffer>>).
+    const mdxGrantsRef = useRef({});
+    const trackMdxGrant = useCallback((entryPath, grantedPath) => {
+        if (grantedPath === entryPath)
+            return;
+        let set = mdxGrantsRef.current[entryPath];
+        if (!set) {
+            set = new Set();
+            mdxGrantsRef.current[entryPath] = set;
+        }
+        set.add(grantedPath); // Set semantics: re-resolving the same import on HMR-style re-render is a no-op.
+    }, []);
+    return {
+        openDocs,
+        setOpenDocs,
+        activePath,
+        setActivePath,
+        editsRef,
+        writeEdits,
+        writeEditsLive,
+        subscribeEdits,
+        getEditSnapshot,
+        getExternalSeq,
+        docxDirty,
+        docxDirtyRef,
+        setDocxDirty,
+        pdfDirty,
+        pdfDirtyRef,
+        setPdfDirty,
+        imageDirty,
+        imageDirtyRef,
+        setImageDirty,
+        htmlPages,
+        htmlPagesRef,
+        writeHtmlPages,
+        htmlActivePage,
+        setHtmlActivePage,
+        mdxGrantsRef,
+        trackMdxGrant,
+    };
+}

package/dist/app/useDocumentWatcher.d.ts

@@ -0,0 +1,83 @@
+import { type Dispatch, type MutableRefObject, type SetStateAction } from "react";
+import { type LoadedDocument } from "@rightkit/document-core/documents/types";
+import type { DocumentTabs } from "./useDocumentTabs.js";
+import type { BlockDraftRegistry } from "@rightkit/document-core/app/blockDrafts";
+export declare function pickNextActive(closedPath: string, prevDocs: LoadedDocument[], remaining: LoadedDocument[], activationOrder: string[]): string | null;
+interface DocumentWatcherDeps {
+    openDocs: LoadedDocument[];
+    openDocsRef: MutableRefObject<LoadedDocument[]>;
+    activationOrderRef: MutableRefObject<string[]>;
+    setOpenDocs: DocumentTabs["setOpenDocs"];
+    setActivePath: DocumentTabs["setActivePath"];
+    activePath: string | null;
+    writeEdits: DocumentTabs["writeEdits"];
+    setDocxDirty: DocumentTabs["setDocxDirty"];
+    setPdfDirty: DocumentTabs["setPdfDirty"];
+    htmlPagesRef: DocumentTabs["htmlPagesRef"];
+    writeHtmlPages: DocumentTabs["writeHtmlPages"];
+    setHtmlActivePage: DocumentTabs["setHtmlActivePage"];
+    mdxGrantsRef: DocumentTabs["mdxGrantsRef"];
+    clearImageDirty: (path: string) => void;
+    isDirty: (doc: LoadedDocument) => boolean;
+    openLiveUrl: (input: string, opts?: {
+        background?: boolean;
+    }) => Promise<void>;
+    activate: (path: string) => Promise<void>;
+    open: (path: string) => Promise<void>;
+    fingerprints: MutableRefObject<Map<string, {
+        mtimeMs: number;
+        size: number;
+    }>>;
+    selfSaved: MutableRefObject<Set<string>>;
+    /** Save paths whose writes are still in flight; watcher events are replayed after completion. */
+    pendingSavePaths?: ReadonlySet<string>;
+    /** Synchronous saver mirror; covers the gap before pendingSavePaths state renders. */
+    synchronousPendingSavePathsRef?: MutableRefObject<ReadonlySet<string>>;
+    /** Synchronous mirrors for DOCX/HTML save wrappers. */
+    synchronousPendingSavePathsRefs?: ReadonlyArray<MutableRefObject<ReadonlySet<string>>>;
+    reloadHtmlSubpage: (path: string) => void;
+    setHtmlConfirm: Dispatch<SetStateAction<{
+        entryPath: string;
+        mode: "save" | "close";
+    } | null>>;
+    setConfirmClose: Dispatch<SetStateAction<string | null>>;
+    confirmClose: string | null;
+    setConflict: Dispatch<SetStateAction<string | null>>;
+    onSave: (doc: LoadedDocument) => Promise<string | null>;
+    onDocxSave: (path: string, buffer: ArrayBuffer) => Promise<void>;
+    docxSaver: MutableRefObject<(() => Promise<ArrayBuffer | null>) | null>;
+    docxSaversRef?: MutableRefObject<Map<string, () => Promise<ArrayBuffer | null>>>;
+    onDocxSaveAs: (doc: LoadedDocument, buffer?: ArrayBuffer) => Promise<string | null>;
+    withTabKey: <T extends LoadedDocument>(doc: T, existingKey?: string) => T;
+    /** Block-draft registry for draft-aware close/save/reload. Optional so this hook's signature stays
+     *  backward-compatible with callers that haven't threaded it through yet. */
+    blockDrafts?: BlockDraftRegistry;
+    /** useViewState's teardown (see useViewState.ts) — deletes a closed path's views/viewsRef/
+     *  viewMetaRef entries. Optional so this hook's signature stays backward-compatible with callers
+     *  that haven't threaded it through yet; when absent, view-state pruning on close is simply
+     *  skipped (same as before this dep existed). */
+    dropViewState?: (path: string) => void;
+}
+/**
+ * Tab lifecycle (close/teardown/reopen) and external-change detection (fingerprint-checked
+ * reload). Extracted verbatim from useDocuments — bodies, fingerprint suppression, and the reopen
+ * stack's bounded-eviction grant revocation are unchanged. Owns `closedTabs` (the Ctrl+Shift+T stack);
+ * `fingerprints` and `selfSaved` are owned by sibling hooks and threaded in so all three read/write the
+ * same single source of truth. `confirmClose`/`conflict` STATE stays with the orchestrator (it's part
+ * of the public return shape and `requestClose` needs to set it before this hook can read it back), so
+ * this hook only receives the current value + setter.
+ */
+export declare function useDocumentWatcher({ openDocs, openDocsRef, activationOrderRef, setOpenDocs, setActivePath, activePath, writeEdits, setDocxDirty, setPdfDirty, htmlPagesRef, writeHtmlPages, setHtmlActivePage, mdxGrantsRef, clearImageDirty, isDirty, openLiveUrl, activate, open, fingerprints, selfSaved, pendingSavePaths, synchronousPendingSavePathsRef, synchronousPendingSavePathsRefs, reloadHtmlSubpage, setHtmlConfirm, setConfirmClose, confirmClose, setConflict, onSave, onDocxSave, docxSaver, docxSaversRef, onDocxSaveAs, withTabKey, blockDrafts, dropViewState, }: DocumentWatcherDeps): {
+    teardownDoc: (path: string, closingDoc: LoadedDocument | undefined) => void;
+    doClose: (path: string) => void;
+    reopenLastClosed: () => void;
+    requestClose: (path: string) => void;
+    confirmSave: () => Promise<void>;
+    confirmDontSave: () => Promise<void>;
+    applyReload: (path: string) => void;
+    reload: (path: string, options?: {
+        force?: boolean;
+        replayDeferred?: boolean;
+    }) => void;
+};
+export {};