pmx-canvas 0.2.0 → 0.2.2

package/skills/pmx-canvas/references/github-copilot-app-adapter.md

@@ -52,20 +52,36 @@ panel.
 ### Agent behavior — steering is gated, not pushed
 
 `onUserPromptSubmitted` injects the whole `/api/canvas/ax/context` (pins, focus, work
-items, approval gates, and `timeline.pendingSteering`) as hidden context — but only
-when the **pin/focus gate is open** (`pinned.count > 0 || focus.nodeIds.length > 0`),
-and it is clipped to a char budget. Three consequences the adapter/agent must honor:
+items, approval gates, and the compact `delivery` lead block) as hidden context — but
+only when the **pin/focus gate is open** (`pinned.count > 0 || focus.nodeIds.length > 0`),
+and it is clipped to a char budget. Read steering from **`delivery.pendingSteering`**
+(the compact, count-bearing block — newest-first, capped at 10), not the full
+`timeline.pendingSteering`. Three consequences the adapter/agent must honor:
 
 1. A steering board must **stay pinned** (or its button must also emit `ax.focus.set`
    on the board node) to hold the gate open.
 2. A sandbox button click does **not** wake a turn — a human message does. The click
    only enqueues the steer.
-3. The agent must **act on injected `pendingSteering` / `pendingActivity` and then ack**
-   (`canvas_ax_delivery { action: "mark" }`), or it re-injects every gated turn.
+3. The agent must **act on injected `delivery.pendingSteering` / `pendingActivity` and
+   then ack** (`canvas_ax_delivery { action: "mark" }`), or it re-injects every gated turn.
 
-To be robust to the char clip, prefer injecting the compact loop-safe lead block from
+To be robust to the char clip, prefer injecting that compact loop-safe lead block from
 `GET /api/canvas/ax/context?consumer=copilot` (`delivery.pendingSteering` +
-`delivery.pendingActivity`) **above** the full dump.
+`delivery.totalPending` / `delivery.omittedPending` + `delivery.pendingActivity`)
+**above** the full dump. When `omittedPending > 0`, drain the full FIFO backlog from
+`canvas_ax_delivery { action: "claim", consumer: "copilot" }` (oldest-first).
+
+#### Waking the agent from a canvas steer (#59) — adapter-owned
+
+Recording a browser-origin `ax.steer` does **not** wake the active session by itself
+(report #59); PMX only queues it (the `ok:true` emit ack = "recorded", not "delivered").
+To make a canvas **Steer** button actually create a visible turn, the adapter must, on
+its own cadence (e.g. an SSE subscription or poll), **drain**
+`canvas_ax_delivery { action: "claim", consumer: "copilot" }`, call the host's native
+send (`copilotSession.send` / the working `send_instruction` path) with each steer, then
+`canvas_ax_delivery { action: "mark" }` it (loop-safe). This wake is intentionally
+host-owned — PMX never imports the host SDK. Until the adapter wires it, a steering
+button must be labeled "queued for the agent's next turn", not "steer now".
 
 ### Closing the loop (optional, recommended)
 

package/src/cli/index.ts

@@ -122,15 +122,30 @@ function removePidFile(path: string): void {
   }
 }
 
-async function isHealthy(url: string): Promise<boolean> {
+interface HealthStatus {
+  responsive: boolean;
+  workspace: string | null;
+}
+
+async function readHealthStatus(url: string): Promise<HealthStatus> {
   try {
     const response = await fetch(url);
-    return response.ok;
+    if (!response.ok) return { responsive: false, workspace: null };
+    const payload = await response.json().catch(() => null) as unknown;
+    const workspace = payload && typeof payload === 'object' && 'workspace' in payload
+      && typeof payload.workspace === 'string'
+      ? payload.workspace
+      : null;
+    return { responsive: true, workspace };
   } catch {
-    return false;
+    return { responsive: false, workspace: null };
   }
 }
 
+async function isHealthy(url: string): Promise<boolean> {
+  return (await readHealthStatus(url)).responsive;
+}
+
 function readLogTail(path: string, maxLines = 20): string | null {
   try {
     if (!existsSync(path)) return null;
@@ -254,7 +269,8 @@ async function showServeStatus(options: {
   const url = `http://localhost:${options.port}/workbench`;
   const pid = readPidFile(options.pidFile);
   const pidRunning = pid ? isProcessRunning(pid) : false;
-  const responsive = await isHealthy(healthUrl);
+  const health = await readHealthStatus(healthUrl);
+  const responsive = health.responsive;
   const running = responsive || pidRunning;
   if (!running && existsSync(options.pidFile) && !pidRunning) {
     removePidFile(options.pidFile);
@@ -265,6 +281,7 @@ async function showServeStatus(options: {
     daemon: true,
     running,
     responsive,
+    workspace: health.workspace,
     pid,
     pidRunning,
     url,

package/src/client/canvas/CanvasNode.tsx

@@ -324,19 +324,19 @@ export function CanvasNode({ node, children, onContextMenu }: CanvasNodeProps) {
           >
             {node.collapsed ? '▸' : '▾'}
           </button>
-          {node.type !== 'status' && (
-            <button
-              type="button"
-              onClick={(e) => {
-                e.stopPropagation();
-                removeNode(node.id);
-                void removeNodeFromClient(node.id);
-              }}
-              title="Close"
-            >
-              ×
-            </button>
-          )}
+          {/* Report #64: status nodes get the same remove control as every other
+              node type (backend removal + undo/history handle status uniformly). */}
+          <button
+            type="button"
+            onClick={(e) => {
+              e.stopPropagation();
+              removeNode(node.id);
+              void removeNodeFromClient(node.id);
+            }}
+            title="Close"
+          >
+            ×
+          </button>
         </div>
       </div>
       {!node.collapsed && (

package/src/client/canvas/CanvasViewport.tsx

@@ -31,6 +31,7 @@ import {
 import { createEdgeFromClient, createNodeFromClient } from '../state/intent-bridge';
 import type { CanvasAnnotation, CanvasNodeState } from '../types';
 import { FocusFieldLayer } from './FocusFieldLayer';
+import { IntentLayer } from './IntentLayer';
 import { CanvasNode } from './CanvasNode';
 import { EdgeLayer } from './EdgeLayer';
 import { AnnotationLayer } from './AnnotationLayer';
@@ -772,6 +773,7 @@ export function CanvasViewport({ onNodeContextMenu, onCanvasContextMenu, annotat
         }}
       >
         <FocusFieldLayer />
+        <IntentLayer />
         <EdgeLayer nodes={nodes} edges={edges} />
         <AnnotationLayer annotations={Array.from(annotations.value.values())} />
         {draftAnnotation && draftAnnotation.points.length >= 2 && <AnnotationLayer annotations={[draftAnnotation]} />}

package/src/client/canvas/ContextMenu.tsx

@@ -8,6 +8,7 @@ import {
   focusNode,
   nodes,
   pendingConnection,
+  persistLayout,
   removeNode,
   toggleCollapsed,
   toggleContextPin,
@@ -424,23 +425,29 @@ function buildNodeMenuItems(node: CanvasNodeState): MenuItem[] {
     action: () => toggleCollapsed(node.id),
   });
 
-  // Pin/Unpin
+  // Context pin — add/remove from the human-curated agent context (report #63).
+  // This is the PRIMARY "pin" in PMX's model ("pin nodes to curate context"); it
+  // matches the SelectionBar's "Pin as context" and updates the context count + the
+  // node's ctx-pin indicator. Listed first so the obvious "Pin" verb maps to context.
+  const isCtxPinned = contextPinnedNodeIds.value.has(node.id);
+  items.push({
+    label: isCtxPinned ? 'Unpin from context' : 'Pin as context',
+    action: () => toggleContextPin(node.id),
+  });
+
+  // Position lock — a distinct, secondary feature (exclude from auto-arrange). Renamed
+  // off the word "Pin" so it no longer collides with context pinning (report #63), and
+  // now persists like every other layout mutation.
   items.push({
-    label: node.pinned ? 'Unpin' : 'Pin (exclude from auto-arrange)',
+    label: node.pinned ? 'Unlock position' : 'Lock position (no auto-arrange)',
     action: () => {
       const pinned = !node.pinned;
       updateNode(node.id, { pinned });
       void updateNodeFromClient(node.id, { pinned });
+      persistLayout();
     },
   });
 
-  // Context pin — add/remove from persistent agent context
-  const isCtxPinned = contextPinnedNodeIds.value.has(node.id);
-  items.push({
-    label: isCtxPinned ? 'Remove from context' : 'Add to context',
-    action: () => toggleContextPin(node.id),
-  });
-
   // ── Edge connection ──
   const pending = pendingConnection.value;
   if (pending && pending.from !== node.id) {
@@ -586,16 +593,15 @@ function buildNodeMenuItems(node: CanvasNodeState): MenuItem[] {
     }
   }
 
-  if (node.type !== 'status') {
-    items.push({ separator: true });
-    items.push({
-      label: 'Close',
-      action: () => {
-        removeNode(node.id);
-        void removeNodeFromClient(node.id);
-      },
-    });
-  }
+  // Report #64: status nodes are removable like any other node type.
+  items.push({ separator: true });
+  items.push({
+    label: 'Close',
+    action: () => {
+      removeNode(node.id);
+      void removeNodeFromClient(node.id);
+    },
+  });
 
   return items;
 }

package/src/client/canvas/IntentLayer.tsx

@@ -0,0 +1,278 @@
+import { useEffect } from 'preact/hooks';
+import { nodes } from '../state/canvas-store';
+import {
+  hoveredIntentId,
+  intents,
+  type ClientIntent,
+} from '../state/intent-store';
+import { vetoGhostIntent } from '../state/intent-bridge';
+import { getNodeIcon } from '../icons';
+import { TYPE_LABELS } from '../types';
+import type { CanvasNodeState } from '../types';
+
+/**
+ * Ghost Cursor of Intent overlay. Renders the agent's pre-commit moves as faint
+ * placeholders in world space (it lives inside the canvas transform, like
+ * FocusFieldLayer, so positions are world coords). Five kinds:
+ *   create  → dashed ghost node with icon + type badge
+ *   move    → ghost at the destination + a dashed trail from the current node
+ *   connect → dashed bezier in the edge-type color
+ *   remove  → red crosshatch tombstone over the target
+ *   edit    → shimmer bar over the target
+ * Each ghost carries a label/confidence chip, its reason, a seq badge (staged
+ * batches), and a ✕ veto (also Esc while hovered).
+ */
+
+interface Rect {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+
+const DEFAULT_GHOST_SIZE = { width: 260, height: 150 };
+
+const GHOST_SIZE: Partial<Record<string, { width: number; height: number }>> = {
+  markdown: { width: 300, height: 170 },
+  status: { width: 280, height: 110 },
+  context: { width: 300, height: 200 },
+  trace: { width: 220, height: 64 },
+  file: { width: 300, height: 190 },
+  image: { width: 260, height: 200 },
+  webpage: { width: 320, height: 210 },
+  html: { width: 320, height: 210 },
+  group: { width: 340, height: 210 },
+  graph: { width: 320, height: 210 },
+  'json-render': { width: 320, height: 210 },
+  'mcp-app': { width: 340, height: 230 },
+};
+
+function isKnownNodeType(value: string | undefined): value is CanvasNodeState['type'] {
+  return !!value && value in TYPE_LABELS;
+}
+
+function getNodeRect(nodeId: string | undefined): Rect | null {
+  if (!nodeId) return null;
+  const node = nodes.value.get(nodeId);
+  if (!node || node.dockPosition !== null) return null;
+  return { left: node.position.x, top: node.position.y, width: node.size.width, height: node.size.height };
+}
+
+function center(rect: Rect): { x: number; y: number } {
+  return { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 };
+}
+
+function ghostOpacity(intent: ClientIntent): number {
+  if (typeof intent.confidence !== 'number') return 0.82;
+  return 0.4 + Math.max(0, Math.min(1, intent.confidence)) * 0.55;
+}
+
+function bezierPath(a: { x: number; y: number }, b: { x: number; y: number }): string {
+  const dx = Math.max(40, Math.abs(b.x - a.x) / 2);
+  return `M ${a.x} ${a.y} C ${a.x + dx} ${a.y}, ${b.x - dx} ${b.y}, ${b.x} ${b.y}`;
+}
+
+function GhostInfo({ intent }: { intent: ClientIntent }) {
+  const NodeIcon = isKnownNodeType(intent.nodeType) ? getNodeIcon(intent.nodeType) : null;
+  const label = intent.label || intent.kind;
+  const confidencePct =
+    typeof intent.confidence === 'number' ? `${Math.round(intent.confidence * 100)}%` : null;
+  return (
+    <div
+      class="intent-info"
+      onMouseEnter={() => (hoveredIntentId.value = intent.id)}
+      onMouseLeave={() => {
+        if (hoveredIntentId.value === intent.id) hoveredIntentId.value = null;
+      }}
+    >
+      <div class="intent-chip">
+        {typeof intent.seq === 'number' && <span class="intent-seq">{intent.seq}</span>}
+        {NodeIcon && (
+          <span class="intent-chip-icon" aria-hidden="true">
+            <NodeIcon size={12} />
+          </span>
+        )}
+        <span class="intent-chip-label">{label}</span>
+        {confidencePct && <span class="intent-confidence">{confidencePct}</span>}
+        {intent.phase === 'forming' && (
+          <button
+            type="button"
+            class="intent-veto"
+            title="Veto this move (Esc)"
+            aria-label="Veto this move"
+            onClick={(e) => {
+              e.stopPropagation();
+              void vetoGhostIntent(intent);
+            }}
+          >
+            ✕
+          </button>
+        )}
+      </div>
+      {intent.reason && <div class="intent-reason">{intent.reason}</div>}
+    </div>
+  );
+}
+
+function GhostBox({ intent, rect }: { intent: ClientIntent; rect: Rect }) {
+  const NodeIcon = isKnownNodeType(intent.nodeType) ? getNodeIcon(intent.nodeType) : null;
+  const typeLabel = isKnownNodeType(intent.nodeType) ? TYPE_LABELS[intent.nodeType] : 'Node';
+  return (
+    <div
+      class={`intent-ghost intent-ghost-box is-${intent.phase}`}
+      data-intent-id={intent.id}
+      style={{
+        left: `${rect.left}px`,
+        top: `${rect.top}px`,
+        width: `${rect.width}px`,
+        height: `${rect.height}px`,
+        opacity: ghostOpacity(intent),
+      }}
+    >
+      <div class="intent-ghost-titlebar">
+        <span class="intent-ghost-icon" aria-hidden="true">
+          {NodeIcon ? <NodeIcon size={13} /> : '◇'}
+        </span>
+        <span class="intent-ghost-badge">{typeLabel}</span>
+      </div>
+      <GhostInfo intent={intent} />
+    </div>
+  );
+}
+
+function GhostOverlay({ intent, rect, variant }: { intent: ClientIntent; rect: Rect; variant: 'remove' | 'edit' }) {
+  return (
+    <div
+      class={`intent-ghost intent-ghost-${variant} is-${intent.phase}`}
+      data-intent-id={intent.id}
+      style={{
+        left: `${rect.left}px`,
+        top: `${rect.top}px`,
+        width: `${rect.width}px`,
+        height: `${rect.height}px`,
+        opacity: ghostOpacity(intent),
+      }}
+    >
+      {variant === 'edit' && <div class="intent-edit-bar" />}
+      <GhostInfo intent={intent} />
+    </div>
+  );
+}
+
+function renderGhost(intent: ClientIntent) {
+  const settledRect = intent.phase === 'settling'
+    ? getNodeRect(intent.settledNodeId)
+    : null;
+  switch (intent.kind) {
+    case 'create': {
+      if (!intent.position) return null;
+      const size = (intent.nodeType && GHOST_SIZE[intent.nodeType]) || DEFAULT_GHOST_SIZE;
+      const rect: Rect = settledRect ?? { left: intent.position.x, top: intent.position.y, ...size };
+      return <GhostBox key={intent.id} intent={intent} rect={rect} />;
+    }
+    case 'move': {
+      if (!intent.position) return null;
+      const source = getNodeRect(intent.nodeId);
+      const size = source ?? DEFAULT_GHOST_SIZE;
+      const rect: Rect = settledRect ?? { left: intent.position.x, top: intent.position.y, width: size.width, height: size.height };
+      return <GhostBox key={intent.id} intent={intent} rect={rect} />;
+    }
+    case 'remove': {
+      const rect = settledRect ?? getNodeRect(intent.nodeId);
+      if (!rect) return null;
+      return <GhostOverlay key={intent.id} intent={intent} rect={rect} variant="remove" />;
+    }
+    case 'edit': {
+      const rect = settledRect ?? getNodeRect(intent.nodeId);
+      if (!rect) return null;
+      return <GhostOverlay key={intent.id} intent={intent} rect={rect} variant="edit" />;
+    }
+    case 'connect': {
+      if (!intent.edge) return null;
+      const from = getNodeRect(intent.edge.from);
+      const to = getNodeRect(intent.edge.to);
+      if (!from || !to) return null;
+      const mid = { x: (from.left + from.width / 2 + to.left + to.width / 2) / 2, y: (from.top + from.height / 2 + to.top + to.height / 2) / 2 };
+      const rect: Rect = { left: mid.x - 110, top: mid.y - 18, width: 220, height: 36 };
+      // The bezier itself is drawn in the shared SVG layer; here we anchor the info card.
+      return (
+        <div
+          key={intent.id}
+          class={`intent-ghost intent-ghost-connect is-${intent.phase}`}
+          data-intent-id={intent.id}
+          style={{ left: `${rect.left}px`, top: `${rect.top}px`, width: `${rect.width}px`, opacity: ghostOpacity(intent) }}
+        >
+          <GhostInfo intent={intent} />
+        </div>
+      );
+    }
+    default:
+      return null;
+  }
+}
+
+export function IntentLayer() {
+  const list = Array.from(intents.value.values());
+
+  // Esc vetoes the hovered ghost before App's hierarchical Esc handler runs.
+  useEffect(() => {
+    function onKeyDown(e: KeyboardEvent): void {
+      if (e.key !== 'Escape') return;
+      const id = hoveredIntentId.value;
+      if (!id) return;
+      const intent = intents.value.get(id);
+      if (!intent || intent.phase !== 'forming') return;
+      e.stopImmediatePropagation();
+      e.preventDefault();
+      void vetoGhostIntent(intent);
+    }
+    window.addEventListener('keydown', onKeyDown, true);
+    return () => window.removeEventListener('keydown', onKeyDown, true);
+  }, []);
+
+  if (list.length === 0) return null;
+
+  return (
+    <div class="intent-layer">
+      <svg class="intent-line-layer" style={{ position: 'absolute', top: 0, left: 0, width: '100%', height: '100%', overflow: 'visible', pointerEvents: 'none' }}>
+        <defs>
+          <marker id="intent-arrow" markerWidth="8" markerHeight="8" refX="6" refY="3" orient="auto">
+            <path d="M0,0 L6,3 L0,6 Z" class="intent-arrow-head" />
+          </marker>
+        </defs>
+        {list.map((intent) => {
+          if (intent.kind === 'connect' && intent.edge) {
+            const from = getNodeRect(intent.edge.from);
+            const to = getNodeRect(intent.edge.to);
+            if (!from || !to) return null;
+            return (
+              <path
+                key={`line-${intent.id}`}
+                d={bezierPath(center(from), center(to))}
+                class={`intent-edge type-${intent.edge.type}`}
+                style={{ opacity: ghostOpacity(intent) }}
+              />
+            );
+          }
+          if (intent.kind === 'move' && intent.position) {
+            const source = getNodeRect(intent.nodeId);
+            if (!source) return null;
+            const size = source;
+            const dest = { x: intent.position.x + size.width / 2, y: intent.position.y + size.height / 2 };
+            return (
+              <path
+                key={`line-${intent.id}`}
+                d={bezierPath(center(source), dest)}
+                class="intent-trail"
+                markerEnd="url(#intent-arrow)"
+                style={{ opacity: ghostOpacity(intent) }}
+              />
+            );
+          }
+          return null;
+        })}
+      </svg>
+      {list.map(renderGhost)}
+    </div>
+  );
+}

package/src/client/nodes/ExtAppFrame.tsx

@@ -643,29 +643,38 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
     if (iframeRef.current) {
       iframeRef.current.style.height = '100%';
     }
-    if (!bridge || !bridgeReadyRef.current) return;
-    bridge.setHostContext?.({
-      theme: toMcpTheme(canvasTheme.value),
-      platform: 'web',
-      containerDimensions: resolveExtAppContainerDimensions(iframeRef.current, {
-        width: node.size.width,
-        height: maxHeight,
-      }),
-      displayMode: isExpanded ? 'fullscreen' : 'inline',
-      locale: navigator.language,
-      timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
-    });
-    void bridge.sendHostContextChange?.({
-      theme: toMcpTheme(canvasTheme.value),
-      platform: 'web',
-      containerDimensions: resolveExtAppContainerDimensions(iframeRef.current, {
-        width: node.size.width,
-        height: maxHeight,
-      }),
-      displayMode: isExpanded ? 'fullscreen' : 'inline',
-      locale: navigator.language,
-      timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+    if (!bridge || !bridgeReadyRef.current) return undefined;
+    // Measure + send AFTER the expand/collapse overlay has laid out (double rAF).
+    // Measuring synchronously here reads the iframe at its OLD inline size, so an app
+    // like Excalidraw reflows bound text against stale dimensions and clips the start
+    // of labels in expanded mode (report #62). A double rAF lands after layout+paint so
+    // resolveExtAppContainerDimensions reads the real expanded frame.
+    let raf1: number | null = null;
+    let raf2: number | null = null;
+    raf1 = requestAnimationFrame(() => {
+      raf1 = null;
+      raf2 = requestAnimationFrame(() => {
+        raf2 = null;
+        if (!bridgeReadyRef.current) return;
+        const hostContext = {
+          theme: toMcpTheme(canvasTheme.value),
+          platform: 'web' as const,
+          containerDimensions: resolveExtAppContainerDimensions(iframeRef.current, {
+            width: node.size.width,
+            height: maxHeight,
+          }),
+          displayMode: isExpanded ? ('fullscreen' as const) : ('inline' as const),
+          locale: navigator.language,
+          timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+        };
+        bridge.setHostContext?.(hostContext);
+        void bridge.sendHostContextChange?.(hostContext);
+      });
     });
+    return () => {
+      if (raf1 !== null) cancelAnimationFrame(raf1);
+      if (raf2 !== null) cancelAnimationFrame(raf2);
+    };
   }, [isExpanded, maxHeight]);
 
   // Loading state — HTML not yet fetched

package/src/client/state/intent-bridge.ts

@@ -55,6 +55,37 @@ export async function sendIntent(
   });
 }
 
+/**
+ * Veto a forming ghost intent at the mutation gate, then queue steering for the
+ * active agent session only when the server accepted the veto.
+ */
+export async function vetoGhostIntent(intent: {
+  id: string;
+  kind: string;
+  label?: string;
+  reason?: string;
+}): Promise<boolean> {
+  const what = intent.label?.trim() || `${intent.kind} intent`;
+  const message = `Veto: do not ${what}${intent.reason ? ` — ${intent.reason}` : ''}.`;
+  const cleared = await requestJson<{ ok?: boolean; cleared?: boolean }>(
+    'vetoGhostIntent',
+    `/api/canvas/ax/intent/${encodeURIComponent(intent.id)}`,
+    { ok: false, cleared: false },
+    {
+      method: 'DELETE',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ vetoed: true }),
+    },
+  );
+  if (cleared.cleared !== true) return false;
+  await requestBestEffort('vetoGhostSteering', '/api/canvas/ax/steer', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ message, source: 'browser' }),
+  });
+  return true;
+}
+
 /** Fetch rendered markdown HTML from the server. */
 export async function renderMarkdown(markdown: string): Promise<string> {
   const data = await requestJson<{ html?: string }>('renderMarkdown', '/api/render', {}, {