@plannotator/ui 0.28.0 → 0.29.0

package/hooks/usePinpoint.ts

@@ -1,66 +1,103 @@
-import { useEffect, useState, type RefObject } from 'react';
-import type Highlighter from '@plannotator/web-highlighter';
+import {
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  type RefObject,
+} from 'react';
 import type { InputMethod } from '../types';
-import { resolvePinpointTarget } from '../utils/blockTargeting';
-
+import {
+  buildSemanticTargetGraph,
+  createSemanticTargetRange,
+  resolveSemanticTargetAtPoint,
+  type SemanticTarget,
+} from '../utils/blockTargeting';
+
+/** Inputs for pointer Pinpoint targeting within one rendered document. */
 export interface UsePinpointOptions {
   containerRef: RefObject<HTMLElement | null>;
-  highlighterRef: RefObject<Highlighter | null>;
   inputMethod: InputMethod;
   /** Disable when toolbar/popover/diff is active */
   enabled: boolean;
+  /** Submit a text range through the shared annotation pipeline. */
+  onSelectRange: (range: Range) => void;
   /** Handle code block clicks (needs special annotation path) */
   onCodeBlockClick: (blockId: string, element: HTMLElement) => void;
 }
 
+/** Live pointer-owned state returned by `usePinpoint`. */
 export interface UsePinpointReturn {
-  hoverTarget: { element: HTMLElement; label: string } | null;
+  /** Live target from the canonical semantic graph under the pointer. */
+  hoverTarget: SemanticTarget | null;
+  /** Release pointer-owned feedback so keyboard navigation can take over. */
+  clearHover: () => void;
 }
 
+/**
+ * Resolve pointer hover and clicks through the canonical semantic target graph.
+ *
+ * The hook mutates only its transient hover marker and removes it when disabled
+ * or unmounted.
+ */
 export function usePinpoint({
   containerRef,
-  highlighterRef,
   inputMethod,
   enabled,
+  onSelectRange,
   onCodeBlockClick,
 }: UsePinpointOptions): UsePinpointReturn {
-  const [hoverTarget, setHoverTarget] = useState<{ element: HTMLElement; label: string } | null>(null);
+  const [hoverTarget, setHoverTarget] = useState<SemanticTarget | null>(null);
+  const hoverElementRef = useRef<HTMLElement | null>(null);
 
   const isActive = inputMethod === 'pinpoint' && enabled;
+  const clearHover = useCallback(() => {
+    hoverElementRef.current?.removeAttribute('data-pinpoint-hover');
+    hoverElementRef.current = null;
+    setHoverTarget(null);
+  }, []);
 
   // Clear hover when deactivated
   useEffect(() => {
     if (!isActive) {
-      setHoverTarget((prev) => {
-        if (prev) prev.element.removeAttribute('data-pinpoint-hover');
-        return null;
-      });
+      clearHover();
     }
-  }, [isActive]);
+  }, [clearHover, isActive]);
 
   // Mousemove / touchstart — resolve target and update hover state
   useEffect(() => {
     const container = containerRef.current;
     if (!isActive || !container) return;
 
-    let prevElement: HTMLElement | null = null;
+    let graph = buildSemanticTargetGraph(container);
+    let graphIsDirty = false;
+    const liveGraph = () => {
+      if (graphIsDirty) {
+        graph = buildSemanticTargetGraph(container);
+        graphIsDirty = false;
+      }
+      return graph;
+    };
+    const observer = new MutationObserver(() => {
+      graphIsDirty = true;
+    });
+    observer.observe(container, { childList: true, subtree: true });
 
     const updateHover = (clientX: number, clientY: number, target: HTMLElement) => {
-      const resolved = resolvePinpointTarget(target, container, { clientX, clientY });
+      const resolved = resolveSemanticTargetAtPoint(
+        liveGraph(),
+        target,
+        { clientX, clientY },
+      );
 
       if (resolved) {
-        if (resolved.element !== prevElement) {
-          prevElement?.removeAttribute('data-pinpoint-hover');
+        if (resolved.element !== hoverElementRef.current) {
+          hoverElementRef.current?.removeAttribute('data-pinpoint-hover');
           resolved.element.setAttribute('data-pinpoint-hover', '');
-          prevElement = resolved.element;
-          setHoverTarget({ element: resolved.element, label: resolved.label });
+          hoverElementRef.current = resolved.element;
+          setHoverTarget(resolved);
         }
       } else {
-        if (prevElement) {
-          prevElement.removeAttribute('data-pinpoint-hover');
-          prevElement = null;
-          setHoverTarget(null);
-        }
+        clearHover();
       }
     };
 
@@ -76,9 +113,7 @@ export function usePinpoint({
     };
 
     const handleMouseLeave = () => {
-      prevElement?.removeAttribute('data-pinpoint-hover');
-      prevElement = null;
-      setHoverTarget(null);
+      clearHover();
     };
 
     container.addEventListener('mousemove', handleMouseMove);
@@ -86,12 +121,14 @@ export function usePinpoint({
     container.addEventListener('touchstart', handleTouchStart, { passive: true });
 
     return () => {
-      prevElement?.removeAttribute('data-pinpoint-hover');
+      observer.disconnect();
+      hoverElementRef.current?.removeAttribute('data-pinpoint-hover');
+      hoverElementRef.current = null;
       container.removeEventListener('mousemove', handleMouseMove);
       container.removeEventListener('mouseleave', handleMouseLeave);
       container.removeEventListener('touchstart', handleTouchStart);
     };
-  }, [isActive, containerRef]);
+  }, [clearHover, isActive, containerRef]);
 
   // Click — create Range and trigger web-highlighter
   useEffect(() => {
@@ -99,15 +136,12 @@ export function usePinpoint({
     if (!isActive || !container) return;
 
     const handleClick = (e: MouseEvent) => {
-      // Read highlighter at click time, not effect setup time.
-      // On remount (e.g. after exiting plan diff), the highlighter init effect
-      // may not have run yet when this effect sets up, but it will be ready by
-      // the time the user clicks.
-      const highlighter = highlighterRef.current;
-      if (!highlighter) return;
-
       const target = e.target as HTMLElement;
-      const resolved = resolvePinpointTarget(target, container, { clientX: e.clientX, clientY: e.clientY });
+      const resolved = resolveSemanticTargetAtPoint(
+        buildSemanticTargetGraph(container),
+        target,
+        { clientX: e.clientX, clientY: e.clientY },
+      );
       if (!resolved) return;
 
       // Prevent link navigation in pinpoint mode
@@ -120,7 +154,7 @@ export function usePinpoint({
       resolved.element.removeAttribute('data-pinpoint-hover');
       setHoverTarget(null);
 
-      if (resolved.isCodeBlock) {
+      if (resolved.kind === 'code') {
         // Route to existing code block annotation path
         const codeBlockContainer = container.querySelector(`[data-block-id="${resolved.blockId}"]`) as HTMLElement;
         if (codeBlockContainer) {
@@ -131,19 +165,10 @@ export function usePinpoint({
 
       // Create a text-level Range spanning the target element's content.
       // web-highlighter needs ranges anchored to text nodes, not elements.
-      const range = createTextRange(resolved.element);
+      const range = createSemanticTargetRange(resolved);
       if (!range) return;
 
-      // Set browser selection so web-highlighter's mouseup handler picks it up
-      const sel = window.getSelection();
-      sel?.removeAllRanges();
-      sel?.addRange(range);
-
-      // Drive web-highlighter programmatically — fires CREATE event
-      highlighter.fromRange(range);
-
-      // Clean up browser selection
-      window.getSelection()?.removeAllRanges();
+      onSelectRange(range);
     };
 
     // Use capture phase so we get the click before links navigate
@@ -152,31 +177,7 @@ export function usePinpoint({
     return () => {
       container.removeEventListener('click', handleClick, true);
     };
-  }, [isActive, containerRef, highlighterRef, onCodeBlockClick]);
-
-  return { hoverTarget };
-}
-
-/**
- * Create a Range anchored to text nodes (not elements).
- * web-highlighter's painter expects text-node-level ranges.
- */
-function createTextRange(element: HTMLElement): Range | null {
-  const walker = document.createTreeWalker(element, NodeFilter.SHOW_TEXT, null);
-
-  let firstNode: Text | null = null;
-  let lastNode: Text | null = null;
-
-  let node: Text | null;
-  while ((node = walker.nextNode() as Text | null)) {
-    if (!firstNode) firstNode = node;
-    lastNode = node;
-  }
-
-  if (!firstNode || !lastNode) return null;
+  }, [isActive, containerRef, onCodeBlockClick, onSelectRange]);
 
-  const range = document.createRange();
-  range.setStart(firstNode, 0);
-  range.setEnd(lastNode, lastNode.length);
-  return range;
+  return { hoverTarget, clearHover };
 }

package/hooks/usePlanDiff.ts

@@ -5,7 +5,7 @@
  * Consumes the version history API endpoints.
  */
 
-import { useState, useMemo, useCallback, useEffect } from "react";
+import { useState, useMemo, useCallback, useEffect, useRef } from "react";
 import {
   computePlanDiff,
   type PlanDiffBlock,
@@ -89,7 +89,22 @@ export function usePlanDiff(
   currentPlan: string,
   initialPreviousPlan: string | null,
   versionInfo: VersionInfo | null,
-  fetchers?: PlanDiffFetchers
+  fetchers?: PlanDiffFetchers,
+  /**
+   * Identity of the document `initialPreviousPlan`/`versionInfo` belong to
+   * (e.g. a folder/linked document's filepath). When this changes between
+   * renders, the diff-base state below switches to that document's own
+   * remembered base selection (if this document was visited earlier in the
+   * session — see baseSelectionsByDocKeyRef below) or, the first time a
+   * document is seen, seeds from its `initialPreviousPlan`/`versionInfo` —
+   * either way, never keeping whatever the previously active document had
+   * selected, since that would silently keep diffing the new document's text
+   * against the old document's base plan. Omit (or keep it referentially
+   * stable, as the root document does for the life of a session) to preserve
+   * exactly today's one-time-hydration behavior via the two sync effects
+   * below.
+   */
+  docKey?: string | null
 ): UsePlanDiffReturn {
   const fetchVersionImpl = fetchers?.fetchVersion ?? defaultFetchVersion;
   const fetchVersionsImpl = fetchers?.fetchVersions ?? defaultFetchVersions;
@@ -118,6 +133,62 @@ export function usePlanDiff(
     }
   }, [versionInfo]);
 
+  // Remember each document's diff-base selection across navigation, keyed by
+  // docKey (including `null`/`undefined`) — so returning to a previously
+  // visited document (e.g. the root doc after a linked-doc detour) restores
+  // whatever base version the user had picked there instead of re-seeding
+  // defaults. A plain ref (not state) since writing it must never itself
+  // trigger a render — it's only read/written from inside the docKey-change
+  // effect below. Never shared across keys: each key's entry is only ever
+  // populated from that same key's own state at the moment it stops being
+  // active.
+  const baseSelectionsByDocKeyRef = useRef(
+    new Map<
+      string | null | undefined,
+      { diffBasePlan: string | null; diffBaseVersion: number | null }
+    >()
+  );
+
+  // Reset (or restore) diff-base state whenever the active document identity
+  // changes (e.g. folder/linked-doc navigation). docKey is undefined/stable
+  // for a session with no per-doc identity (the root document), so this
+  // never fires there and the sync effects above keep owning its one-time
+  // hydration — byte-identical to before this seam existed.
+  const prevDocKeyRef = useRef(docKey);
+  useEffect(() => {
+    if (prevDocKeyRef.current === docKey) return;
+
+    // Persist the outgoing document's current selection before switching, so
+    // coming back to it later (even after other documents were visited in
+    // between) restores it rather than re-seeding defaults.
+    baseSelectionsByDocKeyRef.current.set(prevDocKeyRef.current, {
+      diffBasePlan,
+      diffBaseVersion,
+    });
+    prevDocKeyRef.current = docKey;
+
+    const remembered = baseSelectionsByDocKeyRef.current.get(docKey);
+    if (remembered) {
+      setDiffBasePlan(remembered.diffBasePlan);
+      setDiffBaseVersion(remembered.diffBaseVersion);
+    } else {
+      setDiffBasePlan(initialPreviousPlan);
+      setDiffBaseVersion(
+        versionInfo && versionInfo.version > 1 ? versionInfo.version - 1 : null
+      );
+    }
+    setVersions([]);
+    setIsLoadingVersions(false);
+    setIsSelectingVersion(false);
+    setFetchingVersion(null);
+    // Only the identity change (docKey) should trigger this reset — the sync
+    // effects above already handle initialPreviousPlan/versionInfo arriving
+    // late for a stable identity, and re-running this on every value change
+    // would fight version selection (selectBaseVersion intentionally leaves
+    // docKey unchanged while it swaps diffBasePlan/diffBaseVersion).
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [docKey]);
+
   const hasPreviousVersion =
     versionInfo !== null && versionInfo.totalVersions > 1 && diffBasePlan !== null;
 

package/hooks/useSkillReferenceAutocomplete.ts

@@ -0,0 +1,239 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import type React from 'react';
+import {
+  extractSkillReferences,
+  filterSkillCatalog,
+  findSkillReferenceTokens,
+  findSkillTrigger,
+  insertSkillReference,
+  type SkillCatalogEntry,
+  type SkillReferenceToken,
+  type SkillTriggerContext,
+} from '../utils/skillReferences';
+import { fetchSkillCatalog, getCachedSkillCatalog } from '../utils/skillCatalog';
+
+export interface SkillReferenceMenuState {
+  items: SkillCatalogEntry[];
+  /** Explicitly activated row, or null — the menu opens with NOTHING active. */
+  activeIndex: number | null;
+  query: string;
+}
+
+export interface UseSkillReferenceAutocompleteResult {
+  /** Open menu state, or null. Render SkillReferenceMenu from this. */
+  menu: SkillReferenceMenuState | null;
+  /** Call FIRST in the textarea's onKeyDown; true means the event was consumed. */
+  onKeyDown: (e: React.KeyboardEvent<HTMLTextAreaElement>) => boolean;
+  /** Call from the textarea's onSelect (fires on every caret move + input). */
+  onSelect: () => void;
+  /** Insert the given menu item at the active trigger. */
+  select: (index: number) => void;
+  /** Human-only skills currently referenced in the text (drives the composer warning). */
+  humanOnlyReferences: SkillCatalogEntry[];
+  /** Positioned reference occurrences in the text (drives the composer highlight overlay). */
+  referenceTokens: SkillReferenceToken[];
+}
+
+/**
+ * Skill-reference autocomplete for a comment textarea. Typing `/` or `$` at
+ * the start of a word opens a menu of the user's global agent skills; the
+ * catalog is fetched lazily (memory-cached, never persisted). With no catalog
+ * (endpoint absent, discovery failed, no skills installed) every path here is
+ * inert and the textarea behaves exactly as before.
+ *
+ * NO-PRESELECTION INVARIANT (do not weaken — an adversarial review proved the
+ * failure): the menu opens with no row active, and while no row is active
+ * Enter, Tab, and every other typing key behave exactly as if the menu were
+ * not open — "This costs $" + Enter is a newline, "cd /" + Tab leaves the
+ * field. A row becomes active ONLY via explicit keyboard navigation
+ * (ArrowDown from none lands on the FIRST row, ArrowUp from none on the
+ * LAST) — and on a BARE trigger (zero query characters) even the arrows pass
+ * through to the textarea and dismiss the menu, because in a multi-line
+ * composer "cost: $" + ArrowUp means caret navigation, not menu navigation;
+ * arrows engage the menu only once a query character was typed. Only with an
+ * active row do Enter and Tab insert. Pointer hover never activates a
+ * row (a menu rendered over the composer sits exactly where the mouse rests
+ * while typing); a pointer CLICK inserts directly and never arms Enter.
+ * Continuing to type re-filters the list and DISARMS any active row, so an
+ * activation always refers to the exact list the user saw. Escape clears the
+ * active row and dismisses the menu when the user has engaged with it (a row
+ * is active or a query was typed); on a bare-trigger menu with no engagement
+ * it passes through, so Escape still closes the composer in one press.
+ */
+export function useSkillReferenceAutocomplete(options: {
+  text: string;
+  setText: (text: string) => void;
+  textareaRef: React.RefObject<HTMLTextAreaElement | null>;
+  enabled: boolean;
+}): UseSkillReferenceAutocompleteResult {
+  const { text, setText, textareaRef, enabled } = options;
+  // Seed from the memory cache only when the surface opted in — a disabled
+  // composer must stay inert even after another surface warmed the catalog.
+  const [catalog, setCatalog] = useState<SkillCatalogEntry[]>(() =>
+    enabled ? getCachedSkillCatalog() : [],
+  );
+  const [caret, setCaret] = useState<number | null>(null);
+  const [activeIndex, setActiveIndex] = useState<number | null>(null);
+  // Escape dismisses the menu for the trigger it was open on; the same trigger
+  // does not reopen until the user leaves it (new trigger start clears this).
+  const [dismissedStart, setDismissedStart] = useState<number | null>(null);
+
+  useEffect(() => {
+    if (!enabled) return;
+    let cancelled = false;
+    fetchSkillCatalog().then((skills) => {
+      if (!cancelled) setCatalog(skills);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [enabled]);
+
+  const trigger: SkillTriggerContext | null = useMemo(() => {
+    if (!enabled || catalog.length === 0 || caret === null) return null;
+    return findSkillTrigger(text, caret);
+  }, [enabled, catalog, text, caret]);
+
+  const items = useMemo(
+    () => (trigger ? filterSkillCatalog(catalog, trigger.query) : []),
+    [catalog, trigger],
+  );
+
+  const open = trigger !== null && items.length > 0 && trigger.start !== dismissedStart;
+
+  // A new trigger start clears the dismissal memory.
+  const lastTriggerStart = useRef<number | null>(null);
+  useEffect(() => {
+    const start = trigger?.start ?? null;
+    if (start !== lastTriggerStart.current) {
+      lastTriggerStart.current = start;
+      setDismissedStart(null);
+    }
+  }, [trigger]);
+
+  // Any trigger change — a new trigger OR more typing re-filtering the same
+  // one — disarms the active row. An activation must always refer to the
+  // exact list the user was looking at when they pressed the arrow key.
+  const triggerStart = trigger?.start ?? null;
+  const triggerQuery = trigger?.query ?? null;
+  useEffect(() => {
+    setActiveIndex(null);
+  }, [triggerStart, triggerQuery]);
+
+  // Never let a stale activation point past the list (catalog refreshes can
+  // shrink it without a query change). Out of range reads as "nothing active".
+  const boundedActive =
+    activeIndex !== null && activeIndex >= 0 && activeIndex < items.length ? activeIndex : null;
+
+  const readCaret = useCallback(() => {
+    const el = textareaRef.current;
+    setCaret(el ? el.selectionStart : null);
+  }, [textareaRef]);
+
+  const select = useCallback(
+    (index: number) => {
+      const el = textareaRef.current;
+      if (!trigger || !el) return;
+      const item = items[index];
+      if (!item) return;
+      const result = insertSkillReference(text, el.selectionStart, trigger, item);
+      setText(result.text);
+      setCaret(result.caret);
+      setActiveIndex(null);
+      // Close deterministically. The DOM caret only moves in the 0ms timer
+      // below, and React's select plugin can re-read the STALE caret before
+      // then (mousedown/keydown fire onSelect), which would transiently
+      // re-open the menu on the just-replaced query. Dismissing the trigger
+      // start makes the close ordering-safe; the dismissal clears itself as
+      // soon as the trigger changes (including to null when the caret lands).
+      setDismissedStart(trigger.start);
+      // Restore focus + caret after React commits the new value.
+      setTimeout(() => {
+        if (!el.isConnected) return;
+        el.focus();
+        el.setSelectionRange(result.caret, result.caret);
+      }, 0);
+    },
+    [items, setText, text, textareaRef, trigger],
+  );
+
+  const onKeyDown = useCallback(
+    (e: React.KeyboardEvent<HTMLTextAreaElement>): boolean => {
+      if (!open) return false;
+      // IME composition: for Pinyin, Telex, 2-set Korean and friends the
+      // composition buffer is ASCII, so the menu can be open exactly when
+      // Enter means "commit this candidate" and the arrows drive the
+      // candidate list. Never consume keys mid-composition. With bare
+      // triggers opening the menu, this guard is MORE load-bearing than
+      // before: the menu is open during more compositions.
+      if (e.nativeEvent.isComposing) return false;
+      if (e.metaKey || e.ctrlKey || e.altKey) return false;
+      switch (e.key) {
+        case 'ArrowDown':
+        case 'ArrowUp':
+          // BARE trigger, zero query, nothing active: the arrows were aimed
+          // at the textarea (proven regression: "first line\ncost: $" +
+          // ArrowUp must move the caret up, not arm the menu's last row so
+          // the next Enter inserts a skill). Dismiss the menu and pass the
+          // key through. Once the user has typed a query character — or
+          // engaged a row via a query — the arrows navigate the menu.
+          if (boundedActive === null && trigger.query.length === 0) {
+            setDismissedStart(trigger.start);
+            return false;
+          }
+          e.preventDefault();
+          if (e.key === 'ArrowDown') {
+            setActiveIndex(boundedActive === null ? 0 : (boundedActive + 1) % items.length);
+          } else {
+            setActiveIndex(
+              boundedActive === null
+                ? items.length - 1
+                : (boundedActive - 1 + items.length) % items.length,
+            );
+          }
+          return true;
+        case 'Enter':
+        case 'Tab':
+          // NO row active means these keys were NOT aimed at the menu:
+          // Enter stays a newline, Tab still leaves the field. This is the
+          // proven regression ("This costs $" + Enter); never consume here.
+          if (boundedActive === null) return false;
+          e.preventDefault();
+          select(boundedActive);
+          return true;
+        case 'Escape':
+          // Only consume Escape when the user engaged with the menu (typed a
+          // query or activated a row). A bare-trigger menu the user ignored
+          // must not cost an extra Escape on the way to closing the composer.
+          if (boundedActive === null && trigger.query.length === 0) return false;
+          e.preventDefault();
+          e.stopPropagation();
+          setActiveIndex(null);
+          setDismissedStart(trigger.start);
+          return true;
+        default:
+          return false;
+      }
+    },
+    [boundedActive, items.length, open, select, trigger],
+  );
+
+  const humanOnlyReferences = useMemo(
+    () => (enabled ? extractSkillReferences(text, catalog).filter((s) => s.humanOnly) : []),
+    [enabled, text, catalog],
+  );
+
+  const referenceTokens = useMemo(
+    () => (enabled ? findSkillReferenceTokens(text, catalog) : []),
+    [enabled, text, catalog],
+  );
+
+  return {
+    menu: open ? { items, activeIndex: boundedActive, query: trigger.query } : null,
+    onKeyDown,
+    onSelect: readCaret,
+    select,
+    humanOnlyReferences,
+    referenceTokens,
+  };
+}

package/hooks/useUpdateCheck.ts

@@ -114,8 +114,7 @@ export function useUpdateCheck(): UpdateInfo | null {
           releaseUrl: release.html_url,
           featureHighlight,
         });
-      } catch (e) {
-        console.debug('Update check failed:', e);
+      } catch {
       }
     };