@plannotator/ui 0.39.0 → 0.40.0

package/hooks/useLinkedDoc.ts

@@ -7,6 +7,7 @@
  */
 
 import { useState, useCallback, useRef } from "react";
+import { normalizeBrowserPath } from "@plannotator/core/browser-paths";
 import type { Annotation, ImageAttachment } from "../types";
 import type { ViewerHandle } from "../components/Viewer";
 import type { SidebarTab } from "./useSidebar";
@@ -136,13 +137,19 @@ export interface UseLinkedDocReturn {
   error: string | null;
   /** Whether a fetch is in progress */
   isLoading: boolean;
-  /** Open a linked document by path (saves plan state, fetches doc, swaps) */
-  open: (docPath: string, buildUrl?: (path: string) => string, targetTab?: SidebarTab) => Promise<void>;
+  /** Open a linked document by path (saves plan state, fetches doc, swaps).
+   *  `revealSidebar: false` leaves the sidebar exactly as it was. */
+  open: (
+    docPath: string,
+    buildUrl?: (path: string) => string,
+    targetTab?: SidebarTab,
+    options?: { revealSidebar?: boolean },
+  ) => Promise<void>;
   /** Open an already-loaded linked document without refetching from disk */
   openLoaded: (
     doc: LinkedDocLoadData & { filepath: string },
     targetTab?: SidebarTab,
-    options?: { notifyDocumentLoaded?: boolean },
+    options?: { notifyDocumentLoaded?: boolean; revealSidebar?: boolean },
   ) => void;
   /** Return to the plan (caches doc annotations, restores plan state) */
   back: () => void;
@@ -150,6 +157,20 @@ export interface UseLinkedDocReturn {
   dismissError: () => void;
   /** All linked doc annotations including the active doc's live state (keyed by filepath) */
   getDocAnnotations: () => Map<string, CachedDocState>;
+  /**
+   * Replace the stored annotations of a document that is NOT the active one —
+   * a cached linked doc, or the stashed source document. This is what lets the
+   * panel's cross-file view edit and delete another file's comments without
+   * navigating to it; the active document's annotations are host state
+   * (`setAnnotations`) and are deliberately never touched here.
+   *
+   * Returns false when no stored document matches (including the active one),
+   * so a host can fall back to its own live-state path.
+   */
+  updateStoredAnnotations: (
+    filepath: string,
+    update: (annotations: Annotation[]) => Annotation[],
+  ) => boolean;
   /** Snapshot the root document plus linked-doc cache for cross-document session swaps */
   snapshotSession: () => LinkedDocSessionState;
   /** Restore a root document plus linked-doc cache, closing any active linked document */
@@ -203,6 +224,11 @@ export function useLinkedDoc(options: UseLinkedDocOptions): UseLinkedDocReturn {
   const [error, setError] = useState<string | null>(null);
   const [isLoading, setIsLoading] = useState(false);
   const [docAnnotationCount, setDocAnnotationCount] = useState(0);
+  // Bumped whenever a stored (non-active) document's annotations change in
+  // place. docCache is a ref, so without this the memos keyed on
+  // getDocAnnotations' identity — panel groups, counts, the export — would
+  // keep serving the pre-mutation cache.
+  const [storeRevision, setStoreRevision] = useState(0);
 
   // Stash plan state when navigating to a linked doc
   const savedPlanState = useRef<SavedPlanState | null>(null);
@@ -281,10 +307,19 @@ export function useLinkedDoc(options: UseLinkedDocOptions): UseLinkedDocReturn {
   const activateDocument = useCallback((
     data: LinkedDocLoadData & { filepath: string },
     targetTab?: SidebarTab,
-    options: { snapshotCurrent?: boolean; notifyDocumentLoaded?: boolean } = {},
+    options: {
+      snapshotCurrent?: boolean;
+      notifyDocumentLoaded?: boolean;
+      revealSidebar?: boolean;
+    } = {},
   ) => {
     const snapshotCurrent = options.snapshotCurrent ?? true;
     const notifyDocumentLoaded = options.notifyDocumentLoaded ?? true;
+    // Opening a document reveals the sidebar so its "Viewing / Back to …"
+    // header is in reach. A host whose surface has its own way back (the
+    // raw-HTML header's Back control) passes false, and the sidebar is left
+    // exactly as the user had it — closed stays closed, open stays put.
+    const revealSidebar = options.revealSidebar ?? true;
     if (snapshotCurrent) onBeforeNavigate?.();
 
     // Backlink detection: if a linked doc links back to the source file (e.g.,
@@ -368,7 +403,7 @@ export function useLinkedDoc(options: UseLinkedDocOptions): UseLinkedDocReturn {
       versionInfo: diffBaseline.versionInfo,
     });
     setError(null);
-    sidebar.open(targetTab ?? "toc");
+    if (revealSidebar) sidebar.open(targetTab ?? "toc");
     onDocumentActivated?.(data);
 
     // Re-apply cached annotations after DOM settles
@@ -407,16 +442,22 @@ export function useLinkedDoc(options: UseLinkedDocOptions): UseLinkedDocReturn {
   const openLoaded = useCallback((
     doc: LinkedDocLoadData & { filepath: string },
     targetTab?: SidebarTab,
-    options?: { notifyDocumentLoaded?: boolean },
+    options?: { notifyDocumentLoaded?: boolean; revealSidebar?: boolean },
   ) => {
     activateDocument(doc, targetTab, {
       snapshotCurrent: true,
       notifyDocumentLoaded: options?.notifyDocumentLoaded,
+      revealSidebar: options?.revealSidebar,
     });
   }, [activateDocument]);
 
   const open = useCallback(
-    async (docPath: string, buildUrl?: (path: string) => string, targetTab?: SidebarTab) => {
+    async (
+      docPath: string,
+      buildUrl?: (path: string) => string,
+      targetTab?: SidebarTab,
+      options?: { revealSidebar?: boolean },
+    ) => {
       onBeforeNavigate?.();
       setIsLoading(true);
       setError(null);
@@ -438,7 +479,10 @@ export function useLinkedDoc(options: UseLinkedDocOptions): UseLinkedDocReturn {
           setError("Failed to load document");
           return;
         }
-        activateDocument({ ...data, filepath: data.filepath }, targetTab, { snapshotCurrent: false });
+        activateDocument({ ...data, filepath: data.filepath }, targetTab, {
+          snapshotCurrent: false,
+          revealSidebar: options?.revealSidebar,
+        });
       } catch {
         setError("Failed to connect to server");
       } finally {
@@ -527,6 +571,50 @@ export function useLinkedDoc(options: UseLinkedDocOptions): UseLinkedDocReturn {
     viewerRef,
   ]);
 
+  const updateStoredAnnotations = useCallback((
+    filepath: string,
+    update: (annotations: Annotation[]) => Annotation[],
+  ): boolean => {
+    // Callers address documents by whatever spelling their list carries — the
+    // panel's groups are normalized (forward slashes, collapsed separators)
+    // while the cache is keyed by the raw server path. On Windows those differ
+    // (`C:/repo/a.md` vs `C:\repo\a.md`) and an unnormalized lookup missed
+    // every time, so a cross-file edit or delete silently did nothing.
+    const wanted = normalizeBrowserPath(filepath);
+
+    // The active document's annotations live in host state, not the cache — a
+    // write here would be silently overwritten the next time it is cached.
+    if (linkedDoc && wanted === normalizeBrowserPath(linkedDoc.filepath)) return false;
+
+    let cacheKey: string | undefined;
+    for (const key of docCache.current.keys()) {
+      if (normalizeBrowserPath(key) === wanted) { cacheKey = key; break; }
+    }
+    const cached = cacheKey === undefined ? undefined : docCache.current.get(cacheKey);
+    if (cached && cacheKey !== undefined) {
+      docCache.current.set(cacheKey, { ...cached, annotations: update([...cached.annotations]) });
+    } else if (savedPlanState.current && sourceFilePath && wanted === normalizeBrowserPath(sourceFilePath)) {
+      const saved = savedPlanState.current;
+      savedPlanState.current = { ...saved, annotations: update([...saved.annotations]) };
+    } else {
+      return false;
+    }
+
+    // Same accounting as activateDocument/back: everything except the document
+    // that is active right now.
+    let total = 0;
+    for (const [fp, entry] of docCache.current.entries()) {
+      if (linkedDoc && fp === linkedDoc.filepath) continue;
+      total += entry.annotations.length + entry.globalAttachments.length;
+    }
+    if (linkedDoc && savedPlanState.current) {
+      total += savedPlanState.current.annotations.length + savedPlanState.current.globalAttachments.length;
+    }
+    setDocAnnotationCount(total);
+    setStoreRevision((r) => r + 1);
+    return true;
+  }, [linkedDoc, sourceFilePath]);
+
   const getDocAnnotations = useCallback((): Map<string, CachedDocState> => {
     const result = new Map(docCache.current);
     // Include stashed original-file annotations when viewing a linked doc
@@ -547,7 +635,9 @@ export function useLinkedDoc(options: UseLinkedDocOptions): UseLinkedDocReturn {
       });
     }
     return result;
-  }, [linkedDoc, annotations, globalAttachments, sourceFilePath, sourceConverted, getDocumentMarkdown]);
+    // storeRevision: cross-file edits mutate docCache in place, so the
+    // identity of this callback is what tells memoized readers to recompute.
+  }, [linkedDoc, annotations, globalAttachments, sourceFilePath, sourceConverted, getDocumentMarkdown, storeRevision]);
 
   return {
     isActive: linkedDoc !== null,
@@ -559,6 +649,7 @@ export function useLinkedDoc(options: UseLinkedDocOptions): UseLinkedDocReturn {
     back,
     dismissError,
     getDocAnnotations,
+    updateStoredAnnotations,
     snapshotSession,
     restoreSession,
     docAnnotationCount,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plannotator/ui",
-  "version": "0.39.0",
+  "version": "0.40.0",
   "type": "module",
   "exports": {
     "./components/*": "./components/*.tsx",
@@ -74,7 +74,7 @@
     "@lezer/highlight": "^1.2.3",
     "@pierre/diffs": "1.3.6",
     "@plannotator/atomic-editor": "^0.8.0",
-    "@plannotator/core": "0.25.2",
+    "@plannotator/core": "0.25.3",
     "@plannotator/markdown-editor": "^0.4.0",
     "@plannotator/web-highlighter": "^0.8.1",
     "@tanstack/react-table": "^8.21.3",
@@ -86,7 +86,7 @@
     "katex": "^0.16.47",
     "lucide-react": "^1.38.0",
     "marked": "^17.0.6",
-    "mermaid": "^11.17.2",
+    "mermaid": "12.0.0",
     "motion": "^12.38.0",
     "perfect-freehand": "^1.2.2",
     "tailwind-merge": "^3.6.0",

package/shortcuts/plan-review/htmlAnnotate.shortcuts.ts

@@ -1,23 +1,37 @@
 import { defineShortcutScope } from '../core';
 import { createShortcutScopeHook } from '../runtime';
 
-// Interact/Annotate toggle for HTML and live-app annotate surfaces. The same
-// chord is mirrored inside the sandboxed iframe by the bridge (focus usually
-// lives in there on live apps) and forwarded to the parent, so it works
-// regardless of which document owns the keyboard. No bare-letter binding:
-// bare letters belong to type-to-comment and the page itself.
+// Chords for the HTML and live-app annotate surfaces. Both are mirrored inside
+// the sandboxed iframe by the bridge (focus usually lives in there on live
+// apps) and forwarded to the parent, so they work regardless of which document
+// owns the keyboard. No bare-letter binding: bare letters belong to
+// type-to-comment and the page itself.
+//
+// `Mod+Shift+X` for the tools rather than a mnemonic letter: every mnemonic
+// candidate is claimed by a browser (H = Chrome's Home / Firefox's history
+// library, E/I/J/K/C = devtools, B/O = bookmarks, V = paste-as-plain-text,
+// T = reopen tab), and a chord the browser eats is worse than an arbitrary
+// one. X is unassigned in Chrome, Firefox, Safari and Edge on every platform.
 export const htmlAnnotateShortcuts = defineShortcutScope({
   id: 'html-annotate',
   title: 'HTML Annotate',
   shortcuts: {
     toggleAnnotateMode: {
-      description: 'Toggle Interact / Annotate',
+      description: 'Toggle annotate mode',
       bindings: ['Mod+Shift+A'],
       section: 'Annotations',
-      hint: 'On HTML and live app surfaces: arm annotation capture, or hand clicks back to the page. Esc also exits Annotate.',
+      hint: 'On HTML and live app surfaces: arm annotation capture, or hand clicks back to the page. Esc also exits Annotate; this chord is the way back in.',
       preventDefault: true,
       displayOrder: 0,
     },
+    toggleTools: {
+      description: 'Show or hide tools',
+      bindings: ['Mod+Shift+X'],
+      section: 'Annotations',
+      hint: 'On HTML and live app surfaces: the header eye — shows or removes all floating chrome over the page. HTML surfaces open with the tools hidden.',
+      preventDefault: true,
+      displayOrder: 1,
+    },
   },
 });