pmx-canvas 0.8.0 → 0.9.0

package/src/client/App.tsx

@@ -1,4 +1,5 @@
-import { useCallback, useEffect, useRef, useState } from 'preact/hooks';
+import { computed } from '@preact/signals';
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'preact/hooks';
 import { Presentation } from './canvas/Presentation';
 import { presenting } from './state/presentation';
 import { AttentionHistory } from './canvas/AttentionHistory';
@@ -6,26 +7,36 @@ import { AttentionToast } from './canvas/AttentionToast';
 import { registerCanvasArea, canvasArea } from './canvas/canvas-area';
 import { CanvasViewport } from './canvas/CanvasViewport';
 import { CommandBar } from './canvas/CommandBar';
+import { ContextPinBar } from './canvas/ContextChip';
 import { ConnectionBanner } from './canvas/ConnectionBanner';
 import { CommandPalette } from './canvas/CommandPalette';
 import { BoardLinkDialog } from './canvas/BoardLinkDialog';
+import { LifecyclePanel } from './canvas/LifecyclePanel';
+import { KnowledgeSync, LifecycleFilters } from './canvas/LifecycleChrome';
 import { ContextMenu, useContextMenu } from './canvas/ContextMenu';
-import { ContextPinBar } from './canvas/ContextPinBar';
 import { EmptyState } from './canvas/EmptyState';
 import { HomeView } from './canvas/HomeView';
 import { ExportDialog } from './canvas/ExportDialog';
-import { activeBoardId, boardsLoaded } from './state/boards-store';
+import { activeBoardId, boardsLoaded, browsingMemory, boardIncarnation } from './state/boards-store';
 import { createNodeInView } from './canvas/create-in-view';
-import { undoFromKeyboard } from './state/session-store';
+import {
+  activityLens,
+  heldGates,
+  pendingGates,
+  scopeFence,
+  sessionPanelOpened,
+  undoFromKeyboard,
+} from './state/session-store';
 import { ActivityFeed, WritersSheet } from './canvas/ExternalWriters';
 import { ExpandedNodeOverlay } from './canvas/ExpandedNodeOverlay';
 import { Minimap } from './canvas/Minimap';
 import { SelectionBar } from './canvas/SelectionBar';
-import { SessionPanel } from './canvas/SessionPanel';
+import { AgentControls, SessionPanel } from './canvas/SessionPanel';
 import { SessionReceipt } from './canvas/SessionReceipt';
 import { ShortcutOverlay } from './canvas/ShortcutOverlay';
 import { SnapshotPanel } from './canvas/SnapshotPanel';
 import { promptedCreate, ToolRail } from './canvas/ToolRail';
+import { EdgeHint, RelationLegend } from './canvas/EdgeLayer';
 import { TextPrompt } from './canvas/TextPrompt';
 import { TopBar } from './canvas/TopBar';
 import {
@@ -39,6 +50,7 @@ import {
   edges,
   expandedNodeId,
   fitAll,
+  focusNode,
   hasInitialServerLayout,
   nodes,
   pendingExpandedNodeCloseId,
@@ -53,7 +65,8 @@ import {
 } from './state/canvas-store';
 import { connectSSE } from './state/sse-bridge';
 import { intents } from './state/intent-store';
-import { sessionActive } from './state/presence-store';
+import { sessionActive, sessionChromeActive } from './state/presence-store';
+import { agentSessionsEnabled, knowledgeLifecycleEnabled } from './state/workspace-settings';
 import { isHostedWorkbench } from './state/workbench-transport';
 import {
   createGroupFromClient,
@@ -63,31 +76,73 @@ import {
   ungroupFromClient,
 } from './state/intent-bridge';
 import type { AnnotationTool } from './types';
+import { lifecycleFilter, lifecycleTarget } from './state/knowledge-store';
+import { relationFilter } from './state/relation-store';
+import { isSelectionEscape } from './utils/keyboard';
 
 function logAppError(action: string, error: unknown): void {
   console.error(`[app] ${action} failed`, error);
 }
 
+/**
+ * App needs only whether the board is empty. Reading the nodes map itself
+ * would re-render the whole shell (and re-measure the canvas) on every drag frame.
+ */
+const boardIsEmpty = computed(() => nodes.value.size === 0);
+const validReviewTarget = computed(() => {
+  const target = lifecycleTarget.value;
+  return (
+    !!target &&
+    !browsingMemory.value &&
+    activeBoardId.value === target.boardId &&
+    boardIncarnation === target.incarnation &&
+    nodes.value.has(target.nodeId)
+  );
+});
+const reviewIsOpen = computed(() => knowledgeLifecycleEnabled.value && validReviewTarget.value);
+
 export function App() {
-  const [minimapVisible, setMinimapVisible] = useState(true);
+  // Off by default in a narrow pane (Pane600.dc.html); the Settings menu turns it on.
+  const [minimapVisible, setMinimapVisible] = useState(() => window.innerWidth >= 700);
   const [snapshotOpen, setSnapshotOpen] = useState(false);
   const [paletteOpen, setPaletteOpen] = useState(false);
   const [boardLinkOpen, setBoardLinkOpen] = useState(false);
+  const [boardLinkSource, setBoardLinkSource] = useState<{ sourceNodeId?: string; wikiRef?: string }>({});
   const [shortcutsOpen, setShortcutsOpen] = useState(false);
   const [annotationTool, setAnnotationTool] = useState<AnnotationTool>(null);
   const snapshotBtnRef = useRef<HTMLButtonElement>(null);
+  const canvasRegionRef = useRef<HTMLDivElement>(null);
+  const [area, setArea] = useState(canvasArea);
   const { menu, openNodeMenu, openCanvasMenu, openEdgeMenu, closeMenu } = useContextMenu();
   const hasInitialLayout = hasInitialServerLayout.value;
-  const onHome = boardsLoaded.value && activeBoardId.value === null;
+  const onHome = boardsLoaded.value && (activeBoardId.value === null || browsingMemory.value);
   // rail-chrome-v2: the one selector every agent surface mounts on. Exposed
   // as a data attribute so styling and tests can key on it; the quiet board
   // (no attached session) must stay byte-clean of agent chrome.
-  const sessionIsActive = sessionActive.value;
+  const sessionIsActive = sessionChromeActive.value;
+  const sessionsEnabled = agentSessionsEnabled.value;
+  const hasAgentControls =
+    sessionActive.value || pendingGates.value.length > 0 || heldGates.value.length > 0 || !!scopeFence.value;
+  const reviewOpen = reviewIsOpen.value;
+
+  useLayoutEffect(() => {
+    if (!sessionsEnabled) {
+      activityLens.value = null;
+      sessionPanelOpened.value = false;
+      if (document.activeElement?.closest('.command-bar, .session-panel, .agent-popover')) {
+        snapshotBtnRef.current?.focus({ preventScroll: true });
+      }
+    }
+  }, [sessionsEnabled]);
 
   const handleToggleMinimap = useCallback(() => setMinimapVisible((v) => !v), []);
   const handleToggleSnapshot = useCallback(() => setSnapshotOpen((v) => !v), []);
   const handleCloseSnapshot = useCallback(() => setSnapshotOpen(false), []);
   const handleSetAnnotationTool = useCallback((tool: AnnotationTool) => setAnnotationTool(tool), []);
+  const handleCanvasRegion = useCallback((el: HTMLDivElement | null) => {
+    registerCanvasArea(el);
+    canvasRegionRef.current = el;
+  }, []);
 
   const handleMinimapNavigate = useCallback((x: number, y: number) => {
     animateViewport({ x, y, scale: viewport.value.scale }, 200);
@@ -98,7 +153,11 @@ export function App() {
   }, []);
 
   useEffect(() => {
-    const open = () => setBoardLinkOpen(true);
+    const open = (event: Event) => {
+      const detail = (event as CustomEvent<{ sourceNodeId?: string; wikiRef?: string }>).detail;
+      setBoardLinkSource(detail ?? {});
+      setBoardLinkOpen(true);
+    };
     window.addEventListener('pmx-open-board-link', open);
     return () => window.removeEventListener('pmx-open-board-link', open);
   }, []);
@@ -123,12 +182,24 @@ export function App() {
     };
   }, []);
 
-  useEffect(() => {
+  // Keyboard ownership must match the committed UI before another key can arrive.
+  useLayoutEffect(() => {
     const handleKeyDown = (e: KeyboardEvent) => {
       // AltGr on European Windows layouts reports Ctrl+Alt — never treat it
       // as the shortcut modifier, or AltGr+Z (ż, ź…) fires undo.
       const mod = (e.metaKey || e.ctrlKey) && !e.altKey;
 
+      // The shortcut reference is available on Home too.
+      if (shortcutsOpen && (e.key === 'Escape' || e.key === '?' || (e.key === '/' && e.shiftKey))) {
+        e.preventDefault();
+        setShortcutsOpen(false);
+        return;
+      }
+
+      // The library owns its keyboard. Never edit the agent's hidden active board.
+      if (browsingMemory.value || activeBoardId.value === null) return;
+      if (e.defaultPrevented) return;
+
       // Cmd/Ctrl+K toggles command palette (works from anywhere, including inputs)
       if (mod && e.key === 'k') {
         e.preventDefault();
@@ -143,7 +214,15 @@ export function App() {
         return;
       }
 
-      // Esc always collapses expanded node first (even from inside inputs)
+      // A companion review closes before expansion or the underlying selection.
+      if (e.key === 'Escape' && reviewIsOpen.value) {
+        if ((e.target as HTMLElement | null)?.closest('[role="menu"], [role="alertdialog"]')) return;
+        e.preventDefault();
+        lifecycleTarget.value = null;
+        return;
+      }
+
+      // Esc collapses expansion after its companion review.
       if (e.key === 'Escape' && expandedNodeId.value && !pendingExpandedNodeCloseId.value) {
         e.preventDefault();
         collapseExpandedNode();
@@ -157,13 +236,6 @@ export function App() {
         return;
       }
 
-      // Esc closes shortcut overlay
-      if (e.key === 'Escape' && shortcutsOpen) {
-        e.preventDefault();
-        setShortcutsOpen(false);
-        return;
-      }
-
       // Ignore other shortcuts when inside inputs or editable content — the
       // single-key rail shortcuts below would otherwise eat characters typed
       // into the inline markdown editor (contenteditable), which INPUT/TEXTAREA
@@ -171,9 +243,16 @@ export function App() {
       const target = e.target as HTMLElement | null;
       const tag = target?.tagName;
       if (tag === 'INPUT' || tag === 'TEXTAREA' || target?.isContentEditable) return;
+      // Menus own every shortcut; dialogs retain global undo, zoom and help.
+      if (target?.closest('[role="menu"]')) return;
+      const inDialog = target?.closest('[role="dialog"]');
+      // Chrome owns its arrow keys and Tab order, rather than board navigation.
+      if ((e.key === 'Tab' || e.key.startsWith('Arrow')) && target?.closest('.tool-rail, .top-bar')) {
+        return;
+      }
 
       // Held Space = temporary pan tool (released on keyup below).
-      if (e.key === ' ' && !e.repeat && !mod) {
+      if (e.key === ' ' && !e.repeat && !mod && !inDialog) {
         e.preventDefault();
         spacePanHeld.value = true;
         return;
@@ -207,11 +286,15 @@ export function App() {
       } else if (mod && e.key === '-') {
         e.preventDefault();
         zoomByFactor(1 / 1.25);
+      } else if (inDialog) {
+        // Dialog controls keep navigation and board-editing keys to themselves.
+        return;
       } else if (e.key === 'Escape') {
-        if (selectedNodeIds.value.size > 0 || selectedEdgeId.value !== null) {
-          clearSelection();
-          return;
-        }
+        if (!isSelectionEscape(e)) return;
+        e.preventDefault();
+        if (relationFilter.value?.boardId === activeBoardId.value) relationFilter.value = null;
+        lifecycleFilter.value = 'All';
+        clearSelection();
         activeNodeId.value = null;
         closeMenu();
       } else if (e.key === 'Tab') {
@@ -327,22 +410,32 @@ export function App() {
     return () => window.clearTimeout(timer);
   }, [sessionIsActive]);
 
+  useLayoutEffect(() => {
+    const region = canvasRegionRef.current;
+    if (!region) return;
+    const observer = new ResizeObserver(() => {
+      setArea(canvasArea());
+      void reportClientViewportSize();
+      const review = lifecycleTarget.value;
+      if (review && reviewIsOpen.value) focusNode(review.nodeId, { recordHistory: false });
+    });
+    observer.observe(region);
+    return () => observer.disconnect();
+  }, []);
+
   useEffect(() => {
     if (!hasInitialLayout) return;
     const ready = (window as Window & { __pmxCanvasBootstrapReady?: () => void }).__pmxCanvasBootstrapReady;
     if (typeof ready === 'function') ready();
   }, [hasInitialLayout]);
 
-  const allNodes = Array.from(nodes.value.values());
-
-  const area = canvasArea();
-
   return (
     <div
       class={`app-shell${presenting.value ? ' is-presenting' : ''}`}
       data-session-active={sessionIsActive ? 'true' : 'false'}
     >
       <Presentation />
+      <EdgeHint />
       <ToolRail
         minimapVisible={minimapVisible}
         onToggleMinimap={handleToggleMinimap}
@@ -357,52 +450,66 @@ export function App() {
       <div class="app-main">
         <TopBar />
         <ConnectionBanner />
-        <div class="canvas-region" ref={(el) => registerCanvasArea(el)}>
-          <CanvasViewport
-            onNodeContextMenu={openNodeMenu}
-            onCanvasContextMenu={openCanvasMenu}
-            onEdgeContextMenu={openEdgeMenu}
-            annotationMode={annotationTool !== null}
-            annotationTool={annotationTool}
-          />
-          <AttentionToast />
-          <AttentionHistory />
-          <ActivityFeed />
-          <WritersSheet />
-          {onHome ? (
-            <HomeView />
-          ) : (
-            hasInitialLayout &&
-            allNodes.length === 0 &&
-            intents.value.size === 0 && <EmptyState onOpenPalette={() => setPaletteOpen(true)} />
-          )}
-          {selectedNodeIds.value.size > 0 && <SelectionBar />}
-          {sessionIsActive && !isHostedWorkbench() ? (
-            <CommandBar />
-          ) : (
-            contextPinnedNodeIds.value.size > 0 && <ContextPinBar />
-          )}
-          <SessionReceipt onOpenSnapshots={() => setSnapshotOpen(true)} />
-          <TextPrompt />
-          <ExportDialog />
-          {expandedNodeId.value && <ExpandedNodeOverlay />}
-          <SnapshotPanel open={snapshotOpen} onClose={handleCloseSnapshot} anchorRef={snapshotBtnRef} />
-          {minimapVisible && !onHome && (
-            <Minimap
-              viewport={viewport}
-              nodes={nodes}
-              edges={edges}
-              onNavigate={handleMinimapNavigate}
-              containerWidth={area.width}
-              containerHeight={area.height}
+        <div class={`workspace${reviewOpen ? ' is-reviewing' : ''}`}>
+          <div class="canvas-region" ref={handleCanvasRegion}>
+            {!browsingMemory.value && (
+              <CanvasViewport
+                onNodeContextMenu={openNodeMenu}
+                onCanvasContextMenu={openCanvasMenu}
+                onEdgeContextMenu={openEdgeMenu}
+                annotationMode={annotationTool !== null}
+                annotationTool={annotationTool}
+              />
+            )}
+            <AttentionToast />
+            <KnowledgeSync />
+            {!onHome && <LifecycleFilters />}
+            {!onHome && <RelationLegend />}
+            <AttentionHistory />
+            <ActivityFeed />
+            <WritersSheet />
+            {onHome ? (
+              <HomeView />
+            ) : (
+              hasInitialLayout &&
+              boardIsEmpty.value &&
+              intents.value.size === 0 && <EmptyState onOpenPalette={() => setPaletteOpen(true)} />
+            )}
+            {!onHome && selectedNodeIds.value.size > 0 && <SelectionBar />}
+            {!onHome && !sessionsEnabled && <ContextPinBar />}
+            {!onHome && sessionActive.value && !isHostedWorkbench() && <CommandBar />}
+            {!onHome && <SessionReceipt onOpenSnapshots={() => setSnapshotOpen(true)} />}
+            <TextPrompt />
+            {!browsingMemory.value && <ExportDialog />}
+            {!onHome && expandedNodeId.value && <ExpandedNodeOverlay />}
+            <SnapshotPanel
+              open={snapshotOpen && !browsingMemory.value}
+              onClose={handleCloseSnapshot}
+              anchorRef={snapshotBtnRef}
             />
-          )}
+            {minimapVisible && !onHome && (
+              <Minimap
+                viewport={viewport}
+                nodes={nodes}
+                edges={edges}
+                onNavigate={handleMinimapNavigate}
+                containerWidth={area.width}
+                containerHeight={area.height}
+              />
+            )}
+          </div>
+          {validReviewTarget.value && <LifecyclePanel />}
         </div>
       </div>
       {sessionIsActive && <SessionPanel />}
-      {menu && <ContextMenu menu={menu} onClose={closeMenu} />}
-      {paletteOpen && <CommandPalette onClose={() => setPaletteOpen(false)} onToggleMinimap={handleToggleMinimap} />}
-      {boardLinkOpen && <BoardLinkDialog onClose={() => setBoardLinkOpen(false)} />}
+      {!sessionIsActive && hasAgentControls && <AgentControls />}
+      {!browsingMemory.value && menu && <ContextMenu menu={menu} onClose={closeMenu} />}
+      {!browsingMemory.value && paletteOpen && (
+        <CommandPalette onClose={() => setPaletteOpen(false)} onToggleMinimap={handleToggleMinimap} />
+      )}
+      {!browsingMemory.value && boardLinkOpen && (
+        <BoardLinkDialog {...boardLinkSource} onClose={() => setBoardLinkOpen(false)} />
+      )}
       {shortcutsOpen && <ShortcutOverlay onClose={() => setShortcutsOpen(false)} />}
     </div>
   );

package/src/client/canvas/AttentionHistory.tsx

@@ -31,7 +31,6 @@ export function AttentionHistory() {
         class="attention-history-tab"
         onClick={handleOpenUpdates}
         aria-label={unread > 0 ? `Recent updates — ${unread} new` : 'Recent updates'}
-        title={unread > 0 ? `${unread} new updates since last viewed` : 'Recent updates'}
       >
         <svg
           width="14"
@@ -72,7 +71,6 @@ export function AttentionHistory() {
           class="attention-history-close"
           onClick={closeAttentionHistory}
           aria-label="Collapse changes panel"
-          title="Collapse"
         >
           <IconClose />
         </button>

package/src/client/canvas/BarHint.tsx

@@ -1,4 +1,19 @@
-import type { ComponentChildren } from 'preact';
+import { render, type ComponentChildren, type VNode } from 'preact';
+import { useLayoutEffect, useMemo, useState } from 'preact/hooks';
+
+/** Escape a bar's filter/clip without installing React-compat event hooks. */
+export function BarPortal({ children }: { children: VNode }) {
+  const host = useMemo(() => document.createElement('div'), []);
+  useLayoutEffect(() => {
+    document.body.appendChild(host);
+    return () => {
+      render(null, host);
+      host.remove();
+    };
+  }, [host]);
+  useLayoutEffect(() => render(children, host), [children, host]);
+  return null;
+}
 
 /**
  * Styled hover/focus tooltip for bar controls — the replacement for native
@@ -11,6 +26,7 @@ export function BarHint({
   align = 'center',
   side = 'down',
   tapToOpen = false,
+  fitWithin,
   children,
 }: {
   label: string;
@@ -27,12 +43,34 @@ export function BarHint({
    * after the click, not linger on focus.
    */
   tapToOpen?: boolean;
+  /**
+   * The clipping box to stay inside (a CSS selector for an ancestor). As the
+   * tooltip opens it takes whichever of end/start alignment fits — a node
+   * header chip sits anywhere along a card that clips its contents.
+   */
+  fitWithin?: string;
   children: ComponentChildren;
 }) {
+  const [fitted, setFitted] = useState<'start' | 'end' | null>(null);
+  const fit = (event: Event) => {
+    if (!fitWithin) return;
+    const anchor = event.currentTarget as HTMLElement;
+    const box = anchor.closest(fitWithin)?.getBoundingClientRect();
+    const tip = anchor.querySelector('.toolbar-tooltip')?.getBoundingClientRect();
+    if (!box || !tip) return;
+    const self = anchor.getBoundingClientRect();
+    // Opening from the anchor's right edge leftwards (end) or its left edge rightwards (start).
+    const endFits = self.right - tip.width >= box.left;
+    const startFits = self.left + tip.width <= box.right;
+    setFitted(endFits || !startFits ? 'end' : 'start');
+  };
+  const placed = fitted ?? align;
   return (
     <span
-      class={`toolbar-tooltip-anchor toolbar-tooltip-anchor-${align}${side === 'up' ? ' toolbar-tooltip-anchor-up' : ''}${tapToOpen ? ' toolbar-tooltip-anchor-tap' : ''}`}
+      class={`toolbar-tooltip-anchor toolbar-tooltip-anchor-${placed}${side === 'up' ? ' toolbar-tooltip-anchor-up' : ''}${tapToOpen ? ' toolbar-tooltip-anchor-tap' : ''}`}
       tabIndex={tapToOpen ? -1 : undefined}
+      onPointerEnter={fitWithin ? fit : undefined}
+      onFocusIn={fitWithin ? fit : undefined}
     >
       {children}
       <span class="toolbar-tooltip" role="tooltip">

package/src/client/canvas/BoardCopyDialog.tsx

@@ -42,7 +42,7 @@ export function BoardCopyDialog({ board, onClose }: { board: BoardSummary; onClo
     const created = await createBoardFrom({
       sourceBoardId: board.id,
       name: name.trim(),
-      ...(board.category ? { category: board.category } : {}),
+      ...(board.folder ? { folder: board.folder } : {}),
       nodeIds: [...selected],
       includeReadme,
       includeStructure,

package/src/client/canvas/BoardFolderDialog.tsx

@@ -1,5 +1,5 @@
 import { useEffect, useRef, useState } from 'preact/hooks';
-import { normalizeBoardCategory } from '../../shared/boards.js';
+import { normalizeBoardFolder } from '../../shared/boards.js';
 import { boardList, updateBoard, type BoardSummary } from '../state/boards-store';
 import { useFocusTrap } from './use-focus-trap';
 
@@ -14,7 +14,7 @@ export function BoardFolderDialog({
   onClose: () => void;
 }) {
   const ref = useRef<HTMLDivElement>(null);
-  const [parent, setParent] = useState(board.category ?? '');
+  const [parent, setParent] = useState(board.folder ?? '');
   const [name, setName] = useState('');
   const [busy, setBusy] = useState(false);
   const [error, setError] = useState('');
@@ -32,18 +32,18 @@ export function BoardFolderDialog({
 
   const destination = name.trim() ? [parent, name.trim()].filter(Boolean).join('/') : parent;
   const move = async () => {
-    let category: string | null;
+    let folder: string | null;
     try {
       if (name.includes('/')) throw new Error('Use one folder name; choose its parent above.');
-      category = normalizeBoardCategory(destination);
+      folder = normalizeBoardFolder(destination);
     } catch (cause) {
       setError(cause instanceof Error ? cause.message : String(cause));
       return;
     }
     setBusy(true);
     setError('');
-    await updateBoard(board.id, { category });
-    if (boardList.value.find((entry) => entry.id === board.id)?.category === category) onClose();
+    await updateBoard(board.id, { folder });
+    if (boardList.value.find((entry) => entry.id === board.id)?.folder === folder) onClose();
     else setError('Could not move this board. Try again.');
     setBusy(false);
   };
@@ -108,7 +108,7 @@ export function BoardFolderDialog({
           <button
             type="button"
             class="text-prompt-confirm"
-            disabled={busy || destination === (board.category ?? '')}
+            disabled={busy || destination === (board.folder ?? '')}
             onClick={() => void move()}
           >
             {busy ? 'Moving…' : 'Move board'}