pmx-canvas 0.8.2 → 0.9.0

package/src/client/canvas/use-memory-graph.ts

@@ -0,0 +1,58 @@
+import { useEffect, useRef, useState } from 'preact/hooks';
+import type { MemoryGraph } from '../../shared/memory-graph.js';
+import { boardList, catalogEpoch, memoryGraphRevision } from '../state/boards-store';
+import { requestJson } from '../state/intent-bridge';
+
+/** Coalesce live discovery and reject responses from an older library revision. */
+export function useMemoryGraph(projection: 'full' | 'boards') {
+  const boards = boardList.value;
+  const liveRevision = memoryGraphRevision.value;
+  const [graph, setGraph] = useState<MemoryGraph | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(false);
+  const refresh = useRef(() => {});
+  useEffect(() => {
+    let cancelled = false;
+    let running = false;
+    let dirty = false;
+    let timer: number | undefined;
+    const schedule = () => {
+      dirty = true;
+      if (!running && timer === undefined) timer = window.setTimeout(load, 120);
+    };
+    const load = async () => {
+      timer = undefined;
+      dirty = false;
+      running = true;
+      setLoading(true);
+      const epoch = catalogEpoch;
+      const revision = memoryGraphRevision.peek();
+      const catalog = boardList.peek();
+      const result = await requestJson<MemoryGraph | null>(
+        'memoryGraph',
+        `/api/canvas/memory-graph?projection=${projection}`,
+        null,
+      );
+      if (cancelled) return;
+      running = false;
+      if (epoch !== catalogEpoch || revision !== memoryGraphRevision.peek() || catalog !== boardList.peek()) {
+        schedule();
+        return;
+      }
+      if (result && Array.isArray(result.nodes) && Array.isArray(result.edges)) {
+        setGraph(result);
+        setError(false);
+      } else setError(true);
+      setLoading(false);
+      if (dirty) schedule();
+    };
+    refresh.current = schedule;
+    schedule();
+    return () => {
+      cancelled = true;
+      window.clearTimeout(timer);
+    };
+  }, [projection]);
+  useEffect(() => refresh.current(), [liveRevision, boards]);
+  return { graph, loading, error, retry: () => refresh.current() };
+}

package/src/client/canvas/use-node-drag.ts

@@ -47,6 +47,7 @@ export function useNodeDrag({ nodeId, viewport, onMove, onDragEnd, onClick }: No
       const onPointerMove = (ev: PointerEvent) => {
         if (!isDragging.current) return;
         if (!moved && Math.hypot(ev.clientX - e.clientX, ev.clientY - e.clientY) < 4) return;
+        if (!moved) document.documentElement.classList.add('is-node-moving');
         moved = true;
         pendingPointer = { x: ev.clientX, y: ev.clientY };
         if (frameId !== null) return;
@@ -59,7 +60,7 @@ export function useNodeDrag({ nodeId, viewport, onMove, onDragEnd, onClick }: No
           flushMove();
         }
         isDragging.current = false;
-        document.documentElement.classList.remove('is-node-dragging');
+        document.documentElement.classList.remove('is-node-dragging', 'is-node-moving');
         document.removeEventListener('pointermove', onPointerMove);
         document.removeEventListener('pointerup', finishDrag);
         document.removeEventListener('pointercancel', finishDrag);

package/src/client/canvas/use-pan-zoom.ts

@@ -6,6 +6,7 @@ import type { ViewportState } from '../types';
 const MIN_SCALE = 0.1;
 const MAX_SCALE = 4;
 const PAN_SPEED = 1;
+const RIGHT_DRAG_THRESHOLD = 5;
 
 function clampScale(scale: number): number {
   return Math.min(MAX_SCALE, Math.max(MIN_SCALE, scale));
@@ -15,6 +16,8 @@ interface PanZoomOptions {
   viewport: Signal<ViewportState>;
   onViewportChange: (v: ViewportState) => void;
   onViewportCommit: (v: ViewportState) => void;
+  onBackgroundContextMenu?: (e: MouseEvent, worldX: number, worldY: number) => void;
+  onEdgeContextMenu?: (e: MouseEvent, edgeId: string) => void;
   disabled?: boolean;
 }
 
@@ -23,13 +26,28 @@ interface PanZoomOptions {
  * - Wheel + Ctrl/Cmd: zoom centered on pointer
  * - Wheel without modifier: pan
  * - Right or middle pointer drag: pan from anywhere
+ * - Right-click on background: creation menu on release, unless dragged
  * - Pointer drag on background in pan mode: pan
  * - Pinch (touch): zoom
  */
-export function usePanZoom({ viewport, onViewportChange, onViewportCommit, disabled = false }: PanZoomOptions) {
+export function usePanZoom({
+  viewport,
+  onViewportChange,
+  onViewportCommit,
+  onBackgroundContextMenu,
+  onEdgeContextMenu,
+  disabled = false,
+}: PanZoomOptions) {
   const containerRef = useRef<HTMLDivElement>(null);
   const isPanning = useRef(false);
   const lastPointer = useRef({ x: 0, y: 0 });
+  const rightPress = useRef<{
+    x: number;
+    y: number;
+    background: boolean;
+    edgeId: string | null;
+    dragged: boolean;
+  } | null>(null);
   const lastPinchDist = useRef(0);
   const wheelCommitTimer = useRef<number | null>(null);
 
@@ -123,6 +141,16 @@ export function usePanZoom({ viewport, onViewportChange, onViewportCommit, disab
         // Select tool: background drag belongs to the lasso (CanvasViewport).
         return;
       }
+      rightPress.current =
+        e.button === 2
+          ? {
+              x: e.clientX,
+              y: e.clientY,
+              background: e.target === container,
+              edgeId: e.target instanceof Element ? e.target.getAttribute('data-edge-id') : null,
+              dragged: false,
+            }
+          : null;
       isPanning.current = true;
       document.documentElement.classList.add('is-canvas-panning');
       lastPointer.current = { x: e.clientX, y: e.clientY };
@@ -135,6 +163,11 @@ export function usePanZoom({ viewport, onViewportChange, onViewportCommit, disab
     (e: PointerEvent) => {
       if (!isPanning.current) return;
       if (disabled) return;
+      const press = rightPress.current;
+      if (press && !press.dragged) {
+        if (Math.hypot(e.clientX - press.x, e.clientY - press.y) <= RIGHT_DRAG_THRESHOLD) return;
+        press.dragged = true;
+      }
       const dx = e.clientX - lastPointer.current.x;
       const dy = e.clientY - lastPointer.current.y;
       lastPointer.current = { x: e.clientX, y: e.clientY };
@@ -145,13 +178,37 @@ export function usePanZoom({ viewport, onViewportChange, onViewportCommit, disab
     [disabled, viewport, onViewportChange],
   );
 
-  const handlePointerUp = useCallback(() => {
-    if (isPanning.current) {
+  const handlePointerUp = useCallback(
+    (e: PointerEvent) => {
+      if (!isPanning.current) return;
+      // Completing a middle pan must not paste the Linux primary selection.
+      e.preventDefault();
+      const press = rightPress.current;
+      rightPress.current = null;
+      isPanning.current = false;
+      document.documentElement.classList.remove('is-canvas-panning');
+      if (press && !press.dragged) {
+        // Native contextmenu may fire on press or release depending on the OS.
+        // Decide here instead, and never open on cancellation or lost capture.
+        if (!disabled && e.type === 'pointerup') {
+          if (press.edgeId) onEdgeContextMenu?.(e, press.edgeId);
+          else if (press.background) {
+            const rect = containerRef.current?.getBoundingClientRect();
+            if (!rect) return;
+            const v = viewport.value;
+            onBackgroundContextMenu?.(
+              e,
+              (e.clientX - rect.left - v.x) / v.scale,
+              (e.clientY - rect.top - v.y) / v.scale,
+            );
+          }
+        }
+        return;
+      }
       onViewportCommit(viewport.value);
-    }
-    isPanning.current = false;
-    document.documentElement.classList.remove('is-canvas-panning');
-  }, [onViewportCommit, viewport]);
+    },
+    [disabled, onBackgroundContextMenu, onEdgeContextMenu, onViewportCommit, viewport],
+  );
 
   // Touch pinch
   const handleTouchMove = useCallback(

package/src/client/icons.tsx

@@ -192,23 +192,6 @@ export function IconMinimap(p: IconProps): JSX.Element {
   );
 }
 
-/** Sun with rays */
-export function IconSun(p: IconProps): JSX.Element {
-  return (
-    <Icon {...p}>
-      <circle cx="8" cy="8" r="3" />
-      <line x1="8" y1="1" x2="8" y2="3" />
-      <line x1="8" y1="13" x2="8" y2="15" />
-      <line x1="1" y1="8" x2="3" y2="8" />
-      <line x1="13" y1="8" x2="15" y2="8" />
-      <line x1="3.05" y1="3.05" x2="4.46" y2="4.46" />
-      <line x1="11.54" y1="11.54" x2="12.95" y2="12.95" />
-      <line x1="3.05" y1="12.95" x2="4.46" y2="11.54" />
-      <line x1="11.54" y1="4.46" x2="12.95" y2="3.05" />
-    </Icon>
-  );
-}
-
 /** Crescent moon */
 export function IconMoon(p: IconProps): JSX.Element {
   return (
@@ -253,39 +236,6 @@ export function IconTextAnnotation(p: IconProps): JSX.Element {
   );
 }
 
-/** Camera — snapshots */
-export function IconSnapshot(p: IconProps): JSX.Element {
-  return (
-    <Icon {...p}>
-      <rect x="1" y="4" width="14" height="10" rx="1.5" />
-      <path d="M5.5 4 L6.5 2.5 H9.5 L10.5 4" />
-      <circle cx="8" cy="9" r="2.3" />
-    </Icon>
-  );
-}
-
-/** Bullseye — trace toggle */
-export function IconTrace(p: IconProps): JSX.Element {
-  return (
-    <Icon {...p}>
-      <circle cx="8" cy="8" r="6" />
-      <circle cx="8" cy="8" r="3" />
-      <circle cx="8" cy="8" r="0.8" fill="currentColor" stroke="none" />
-    </Icon>
-  );
-}
-
-/** X in circle — clear trace */
-export function IconClearTrace(p: IconProps): JSX.Element {
-  return (
-    <Icon {...p}>
-      <circle cx="8" cy="8" r="6" />
-      <line x1="5.5" y1="5.5" x2="10.5" y2="10.5" />
-      <line x1="10.5" y1="5.5" x2="5.5" y2="10.5" />
-    </Icon>
-  );
-}
-
 /** Magnifying glass — search */
 export function IconSearch(p: IconProps): JSX.Element {
   return (
@@ -296,19 +246,6 @@ export function IconSearch(p: IconProps): JSX.Element {
   );
 }
 
-/** Keyboard — shortcuts */
-export function IconShortcuts(p: IconProps): JSX.Element {
-  return (
-    <Icon {...p}>
-      <rect x="1" y="3" width="14" height="10" rx="1.5" />
-      <line x1="4" y1="6" x2="5" y2="6" />
-      <line x1="7.5" y1="6" x2="8.5" y2="6" />
-      <line x1="11" y1="6" x2="12" y2="6" />
-      <line x1="4" y1="10" x2="12" y2="10" />
-    </Icon>
-  );
-}
-
 /** Speech bubble — steer the agent (command bar composer). */
 export function IconSteer(p: IconProps): JSX.Element {
   return (

package/src/client/mcp-app/style.css

@@ -1,10 +1,4 @@
 .pmx-host-app { height: 100%; display: flex; flex-direction: column; }
 .pmx-host-app > .app-shell { flex: 1; min-height: 0; height: auto; }
-/* Keep context controls clear of the host's floating chat composer. */
-.pmx-host-app .context-pin-bar {
-  bottom: 16px;
-  left: 16px;
-  transform: none;
-}
 /* Guard refusals must remain readable while the full source editor is open. */
 .pmx-host-app .attention-toast.attention-tone-remove { z-index: 100100; }

package/src/client/nodes/AxStepControls.tsx

@@ -1,4 +1,5 @@
 import { useState } from 'preact/hooks';
+import { BarHint } from '../canvas/BarHint';
 import { readAxFlow, readAxStep, type AxFlowStamp } from '../../shared/ax-flow.js';
 import { nodes, updateNodeData } from '../state/canvas-store';
 import { updateNodeFromClient } from '../state/intent-bridge';
@@ -121,31 +122,43 @@ function FlowLoopControls({ node, flow }: { node: CanvasNodeState; flow: AxFlowS
         {running ? `Loop running · run ${run + 1}/${maxRuns}` : `Loop idle · ${run}/${maxRuns} runs`}
       </span>
       {running ? (
-        <button
-          type="button"
-          class="ax-node-action"
-          style={activeButtonStyle}
-          title="Stop the loop now. The stop is persisted on this node, so it survives a refresh and no further step is opened."
-          onClick={(e) => {
-            e.stopPropagation();
-            void persistLoop(node, flow, { ...flow.loop, running: false });
-          }}
+        <BarHint
+          label="Stop the loop now"
+          body="The stop is persisted on this node, so it survives a refresh and no further step is opened."
+          side="up"
+          fitWithin=".node-content, .expanded-overlay-panel"
         >
-          Stop
-        </button>
+          <button
+            type="button"
+            class="ax-node-action"
+            style={activeButtonStyle}
+            onClick={(e) => {
+              e.stopPropagation();
+              void persistLoop(node, flow, { ...flow.loop, running: false });
+            }}
+          >
+            Stop
+          </button>
+        </BarHint>
       ) : (
-        <button
-          type="button"
-          class="ax-node-action"
-          style={axNodeActionButtonStyle}
-          title="Run this flow as a loop: each completed step opens the next one, and the last step starts the next run — until the run cap is reached or you press Stop."
-          onClick={(e) => {
-            e.stopPropagation();
-            void handleRun();
-          }}
+        <BarHint
+          label="Run this flow as a loop"
+          body="Each completed step opens the next one, and the last step starts the next run — until the run cap is reached or you press Stop."
+          side="up"
+          fitWithin=".node-content, .expanded-overlay-panel"
         >
-          Run loop
-        </button>
+          <button
+            type="button"
+            class="ax-node-action"
+            style={axNodeActionButtonStyle}
+            onClick={(e) => {
+              e.stopPropagation();
+              void handleRun();
+            }}
+          >
+            Run loop
+          </button>
+        </BarHint>
       )}
       <input
         class="ax-flow-steer-input"
@@ -170,18 +183,24 @@ function FlowLoopControls({ node, flow }: { node: CanvasNodeState; flow: AxFlowS
           color: 'var(--c-text)',
         }}
       />
-      <button
-        type="button"
-        class="ax-node-action"
-        style={axNodeActionButtonStyle}
-        title="Send a steering message to the agent working this flow."
-        onClick={(e) => {
-          e.stopPropagation();
-          void handleSteer();
-        }}
+      <BarHint
+        label="Send a steering message to the agent working this flow"
+        side="up"
+        align="end"
+        fitWithin=".node-content, .expanded-overlay-panel"
       >
-        Steer
-      </button>
+        <button
+          type="button"
+          class="ax-node-action"
+          style={axNodeActionButtonStyle}
+          onClick={(e) => {
+            e.stopPropagation();
+            void handleSteer();
+          }}
+        >
+          Steer
+        </button>
+      </BarHint>
     </div>
   );
 }
@@ -199,25 +218,30 @@ export function AxStepControls({ node }: { node: CanvasNodeState }) {
           Step {step.index}/{step.total}
         </span>
         {STEP_ACTIONS.map((action) => (
-          <button
+          <BarHint
             key={action.status}
-            type="button"
-            class="ax-node-action"
-            aria-pressed={status === action.status}
-            style={status === action.status ? activeButtonStyle : axNodeActionButtonStyle}
-            title={`Set this step's work item to "${action.status}".`}
-            onClick={(e) => {
-              e.stopPropagation();
-              void runNodeAxInteraction(
-                node,
-                'ax.work.update',
-                { id: step.workItemId, status: action.status },
-                action.toast,
-              );
-            }}
+            label={`Set this step's work item to "${action.status}"`}
+            side="up"
+            fitWithin=".node-content, .expanded-overlay-panel"
           >
-            {action.label}
-          </button>
+            <button
+              type="button"
+              class="ax-node-action"
+              aria-pressed={status === action.status}
+              style={status === action.status ? activeButtonStyle : axNodeActionButtonStyle}
+              onClick={(e) => {
+                e.stopPropagation();
+                void runNodeAxInteraction(
+                  node,
+                  'ax.work.update',
+                  { id: step.workItemId, status: action.status },
+                  action.toast,
+                );
+              }}
+            >
+              {action.label}
+            </button>
+          </BarHint>
         ))}
       </div>
       {flow && <FlowLoopControls node={node} flow={flow} />}

package/src/client/nodes/BoardNode.tsx

@@ -11,7 +11,11 @@ export function BoardNode({ node }: { node: CanvasNodeState }) {
       <div class="board-node-content">
         <div class="board-node-label">Linked board</div>
         <strong class="board-node-title">{target?.name ?? 'Missing board'}</strong>
-        <div class="board-node-meta">{target ? `${target.nodeCount} nodes` : boardId || 'No target id'}</div>
+        <div class="board-node-meta">
+          {target
+            ? `${target.nodeCount} nodes${target.pin ? ' · pinned, so it travels with you' : ''}`
+            : boardId || 'No target id'}
+        </div>
         {target?.summary && <p class="board-node-summary">{target.summary}</p>}
         {!!target?.pinnedTitles?.length && (
           <p class="board-node-meta">Pinned: {target.pinnedTitles.map((pin) => pin.title).join(', ')}</p>

package/src/client/nodes/ContextNode.tsx

@@ -1,4 +1,5 @@
 import { openWorkbenchFile } from '../state/intent-bridge';
+import { BarHint } from '../canvas/BarHint';
 import { TYPE_LABELS, type CanvasNodeState } from '../types';
 import { axNodeActionButtonStyle, runNodeAxInteraction } from './ax-node-actions';
 
@@ -172,18 +173,24 @@ export function ContextNode({
     >
       {/* AX: focus the agent on this context node */}
       <div style={{ display: 'flex', justifyContent: 'flex-end' }}>
-        <button
-          type="button"
-          class="ax-node-action"
-          title="Point the agent at this node — sets it as the agent's current AX focus so the agent pulls it into context to work on next (a one-click alternative to manually pinning)."
-          style={axNodeActionButtonStyle}
-          onClick={(e) => {
-            e.stopPropagation();
-            void runNodeAxInteraction(node, 'ax.focus.set', undefined, 'Focus set');
-          }}
+        <BarHint
+          label="Point the agent at this node"
+          body="Sets it as the agent's current AX focus, so the agent pulls it into context to work on next — a one-click alternative to pinning."
+          align="end"
+          fitWithin=".node-content"
         >
-          Set focus
-        </button>
+          <button
+            type="button"
+            class="ax-node-action"
+            style={axNodeActionButtonStyle}
+            onClick={(e) => {
+              e.stopPropagation();
+              void runNodeAxInteraction(node, 'ax.focus.set', undefined, 'Focus set');
+            }}
+          >
+            Set focus
+          </button>
+        </BarHint>
       </div>
 
       {tokenLimit !== null && tokenLimit > 0 && (

package/src/client/nodes/ExtAppFrame.tsx

@@ -1576,7 +1576,6 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
               expandNode(nodeId);
             }}
             class="ext-app-preview-catcher"
-            title="Click to open"
             style={{
               position: 'absolute',
               top: 0,

package/src/client/nodes/FileNode.tsx

@@ -1,4 +1,5 @@
 import { useCallback, useEffect, useMemo, useState } from 'preact/hooks';
+import { BarHint } from '../canvas/BarHint';
 import { IconPlusCircle, IconRefresh } from '../icons';
 import { delimiterForPath, parseDelimitedText } from '../../shared/delimited-text';
 import { updateNodeData } from '../state/canvas-store';
@@ -243,7 +244,6 @@ function TextFileNode({ node, expanded = false }: { node: CanvasNodeState; expan
             whiteSpace: 'nowrap',
             flex: 1,
           }}
-          title={filePath}
         >
           {filePath}
         </span>
@@ -255,47 +255,51 @@ function TextFileNode({ node, expanded = false }: { node: CanvasNodeState; expan
             {new Date(updatedAt).toLocaleTimeString()}
           </span>
         )}
-        <button
-          type="button"
-          class="ax-node-action"
-          title="Mark this file as AX evidence"
-          onClick={(e) => {
-            e.stopPropagation();
-            void runNodeAxInteraction(
-              node,
-              'ax.evidence.add',
-              { kind: 'file', title: filePath.split('/').pop() || filePath, ref: filePath },
-              'Marked as evidence',
-            );
-          }}
-          style={{
-            background: 'none',
-            border: 'none',
-            color: 'var(--c-muted)',
-            cursor: 'pointer',
-            padding: '2px 4px',
-            fontSize: '12px',
-            flexShrink: 0,
-          }}
-        >
-          <IconPlusCircle size={14} />
-        </button>
-        <button
-          type="button"
-          onClick={handleReload}
-          title="Reload file"
-          style={{
-            background: 'none',
-            border: 'none',
-            color: 'var(--c-muted)',
-            cursor: 'pointer',
-            padding: '2px 4px',
-            fontSize: '12px',
-            flexShrink: 0,
-          }}
-        >
-          <IconRefresh size={14} />
-        </button>
+        <BarHint label="Mark this file as AX evidence" align="end" fitWithin=".node-content">
+          <button
+            type="button"
+            class="ax-node-action"
+            aria-label="Mark this file as AX evidence"
+            onClick={(e) => {
+              e.stopPropagation();
+              void runNodeAxInteraction(
+                node,
+                'ax.evidence.add',
+                { kind: 'file', title: filePath.split('/').pop() || filePath, ref: filePath },
+                'Marked as evidence',
+              );
+            }}
+            style={{
+              background: 'none',
+              border: 'none',
+              color: 'var(--c-muted)',
+              cursor: 'pointer',
+              padding: '2px 4px',
+              fontSize: '12px',
+              flexShrink: 0,
+            }}
+          >
+            <IconPlusCircle size={14} />
+          </button>
+        </BarHint>
+        <BarHint label="Reload file" align="end" fitWithin=".node-content">
+          <button
+            type="button"
+            onClick={handleReload}
+            aria-label="Reload file"
+            style={{
+              background: 'none',
+              border: 'none',
+              color: 'var(--c-muted)',
+              cursor: 'pointer',
+              padding: '2px 4px',
+              fontSize: '12px',
+              flexShrink: 0,
+            }}
+          >
+            <IconRefresh size={14} />
+          </button>
+        </BarHint>
       </div>
 
       {/* Content area */}

package/src/client/nodes/HtmlNode.tsx

@@ -121,6 +121,37 @@ export function HtmlNode({
     return () => window.clearTimeout(id);
   }, [autoFocus, surfaceSrc]);
 
+  const handleDocumentLoad = (frame: HTMLIFrameElement, signal: AbortSignal): Promise<boolean> => {
+    if (signal.aborted) return Promise.resolve(false);
+    return new Promise((resolve) => {
+      const finish = (ready: boolean) => {
+        clearTimeout(timer);
+        window.removeEventListener('message', receive);
+        signal.removeEventListener('abort', cancel);
+        resolve(ready);
+      };
+      const cancel = () => finish(false);
+      const receive = (event: MessageEvent) => {
+        if (
+          event.source !== frame.contentWindow ||
+          event.data?.source !== HTML_SURFACE_PUSH_SOURCE ||
+          event.data?.token !== themeToken
+        )
+          return;
+        // A healthy offscreen frame can wait for paint without a deadline.
+        if (event.data.type === 'mounted') clearTimeout(timer);
+        if (event.data.type === 'ready') finish(true);
+      };
+      const timer = setTimeout(cancel, 10_000);
+      window.addEventListener('message', receive);
+      signal.addEventListener('abort', cancel, { once: true });
+      frame.contentWindow?.postMessage(
+        { source: HTML_SURFACE_PUSH_SOURCE, type: 'check-ready', token: themeToken },
+        '*',
+      );
+    });
+  };
+
   const handleFrameLoad = () => {
     iframeRef.current?.contentWindow?.postMessage(
       {
@@ -174,6 +205,7 @@ export function HtmlNode({
       allow=""
       tabIndex={autoFocus ? 0 : undefined}
       onLoad={handleFrameLoad}
+      onDocumentLoad={handleDocumentLoad}
     />
   );
 }