pmx-canvas 0.5.1 → 0.6.2

package/skills/pmx-canvas/references/installing-pmx-canvas.md

@@ -2,41 +2,101 @@
 
 Use this reference when the `pmx-canvas` skill is installed but the `pmx-canvas` command is not available yet.
 
-## From npm
+## Prerequisites and version
+
+The examples pin **PMX Canvas 0.6.1**, which requires **Bun >=1.4.2** even when
+installed through npm: the CLI runs through Bun, not Node. Check `bun --version`
+first. If missing or older, follow the [Bun installation instructions](https://bun.sh/docs/installation)
+with the user's authorization. Ensure Bun is on the MCP host's PATH as well as the
+interactive shell's; use an absolute `bun`/`bunx` executable path if needed.
+
+Install/configure only when requested. After an intentional runtime upgrade, sync the
+skill from that installed package and restart existing server/MCP processes as described
+in `SKILL.md`. Do not pair newer checkout guidance with an older runtime unknowingly.
+
+## Install from npm
 
 ```bash
-npm install -g pmx-canvas
-pmx-canvas serve --daemon --no-open --wait-ms=20000
-pmx-canvas open
+npm install -g pmx-canvas@0.6.1
+pmx-canvas --version
 ```
 
-## From a local checkout
+Without a global install, use `bunx pmx-canvas@0.6.1` in place of `pmx-canvas` in
+the commands below. Do not use unpinned `bunx pmx-canvas` for a version-specific check.
+
+## Choose the workspace and target
+
+Select an existing absolute root and a dedicated free port. These shell examples use
+POSIX syntax; supply equivalent environment variables on other platforms.
+
+```bash
+export PMX_CANVAS_WORKSPACE_ROOT=/absolute/path/to/project
+export PMX_CANVAS_PORT=14313 # Example only: choose a free port for this workspace.
+unset PMX_CANVAS_URL # A stale URL overrides the environment's CLI port target.
+```
+
+Use **both root and port**. Root pinning alone does not align the CLI, MCP, and browser
+if a server falls back to another port. Without an explicit root, MCP may attach to a
+different workspace on the preferred port. `PMX_CANVAS_ALLOW_WORKSPACE_SPLIT=1` opts
+out of that heuristic but is not a substitute for checking the actual target.
+
+For server startup, precedence is `--port`, then `PMX_WEB_CANVAS_PORT`, then
+`PMX_CANVAS_PORT` (then `PORT` in Amp orbs), then the default 4313. For CLI queries and
+mutations, explicit `--server-url`/`--port` override environment targeting; otherwise
+`PMX_CANVAS_URL` wins over `PMX_CANVAS_PORT`. URL targeting does not set the bind port.
+
+## Start the server
+
+On an ordinary local machine:
+
+```bash
+pmx-canvas serve --daemon --no-open --port="$PMX_CANVAS_PORT" --wait-ms=20000
+```
+
+In a managed environment, use the host's supervised-service mechanism with foreground
+`pmx-canvas serve --no-open --port=<chosen-port>`, passing the selected environment.
+Do not daemonize inside a supervisor or rely on `nohup`, background shell jobs, or tmux
+to survive an orb restart. In an Amp orb, prefer declared services with
+`amp orb services ensure`; otherwise use `amp orb service start` with the foreground
+command. Use the host's authenticated portal/preview for remote viewing, not a raw
+loopback URL. Verify health below before opening the workbench or making writes.
+
+CLI query/mutation commands do not auto-start a server; `serve` or `--mcp` does.
+
+## From a local checkout (development)
 
 ```bash
 git clone https://github.com/pskoett/pmx-canvas.git
 cd pmx-canvas
 bun install
 bun run build
-bun run src/cli/index.ts serve --daemon --no-open --wait-ms=20000
+bun run src/cli/index.ts --version
 ```
 
-For development, run commands through Bun from the checkout:
-
-```bash
-bun run src/cli/index.ts status
-bun run src/cli/index.ts node add --type markdown --title "Hello" --content "# PMX"
-```
+This uses the checked-out source, not necessarily the published 0.6.1 package. Follow
+that checkout's `package.json` Bun requirement and bundled skill. Set the same root/port
+environment above; substitute `bun run /absolute/path/to/pmx-canvas/src/cli/index.ts`
+for `pmx-canvas` in startup and verification commands. The target workspace can be
+different from the source checkout. Build the client before browser verification.
 
 ## MCP Config
 
-For agents that support MCP, configure PMX Canvas as a stdio MCP server:
+For agents that support MCP, configure the pinned package as a stdio server. Replace
+the root and port with your selections; ensure the port is dedicated to this workspace.
+The empty URL overrides a stale inherited value (empty is treated as unset). If the host
+discards empty env values, remove `PMX_CANVAS_URL` from its launch environment instead.
 
 ```json
 {
   "mcpServers": {
     "canvas": {
       "command": "bunx",
-      "args": ["pmx-canvas", "--mcp"]
+      "args": ["pmx-canvas@0.6.1", "--mcp"],
+      "env": {
+        "PMX_CANVAS_WORKSPACE_ROOT": "/absolute/path/to/project",
+        "PMX_CANVAS_PORT": "14313",
+        "PMX_CANVAS_URL": ""
+      }
     }
   }
 }
@@ -49,18 +109,66 @@ If you are using a local checkout instead of the published package, point the co
   "mcpServers": {
     "canvas": {
       "command": "bun",
-      "args": ["run", "/path/to/pmx-canvas/src/cli/index.ts", "--mcp"]
+      "args": ["run", "/absolute/path/to/pmx-canvas/src/cli/index.ts", "--mcp"],
+      "env": {
+        "PMX_CANVAS_WORKSPACE_ROOT": "/absolute/path/to/project",
+        "PMX_CANVAS_PORT": "14313",
+        "PMX_CANVAS_URL": ""
+      }
     }
   }
 }
 ```
 
-## Verify
+Restart the host's MCP process after changing configuration. Inspect startup output for
+fallback ports; do not assume the configured port is the one the MCP server bound.
+
+## Verify the actual target before writes
+
+For the local target selected above:
 
 ```bash
 pmx-canvas --version
-pmx-canvas serve status
+curl --fail --silent --show-error "http://localhost:${PMX_CANVAS_PORT}/health"
+pmx-canvas serve status --port="$PMX_CANVAS_PORT"
+```
+
+Require healthy `ok`, the expected running `version`, and a **`workspace`** matching the
+intended canonical absolute root (resolve symlinks on both paths). Inspect persistence
+health too. `serve status` checks a local port, not an arbitrary `PMX_CANVAS_URL`.
+When deliberately targeting a URL or a fallback port, fetch `/health` there instead,
+then align CLI, MCP, and browser to it. Never print a credential-bearing URL.
+On mismatch, stop: leave the other server alone, choose a free port, and repeat.
+
+Only after confirming the target:
+
+```bash
 pmx-canvas layout
+pmx-canvas open
+```
+
+Inside an orb, open the registered portal rather than asking the user to open localhost.
+
+## Disposable smoke verification
+
+`smoke` creates/searches/removes a temporary node and can leave history/activity records.
+It reports the workspace but does **not** compare it with your intended root. Do not run
+it on a valuable board as an identity check. Use a new disposable workspace and its own
+free port, start it with the appropriate startup method above, and verify `/health` first:
+
+```bash
+export PMX_CANVAS_WORKSPACE_ROOT="$(mktemp -d)"
+export PMX_CANVAS_PORT=14314 # Choose another free port.
+unset PMX_CANVAS_URL
+# Start this workspace's server, then verify its actual health workspace/version.
+# Only after that verification succeeds:
+pmx-canvas smoke
 ```
 
-The CLI defaults to `http://localhost:4313`. Override with `PMX_CANVAS_URL` or `PMX_CANVAS_PORT` if the server runs elsewhere.
+Inspect the JSON report and exit status: health, MCP initialize, node lifecycle, and
+validation should pass; failures exit 1. Version skew is reported in details and is not
+necessarily a failing check. Smoke proves neither `tools/list` discovery nor browser
+rendering: verify those separately when testing the complete onboarding experience.
+Stop only the test server (service-manager stop, or `serve stop --port=<test-port>` for
+your local daemon) before removing its disposable directory. Never clear a user's board
+or stop an unrelated listener to make a smoke test pass.

package/skills/pmx-canvas-testing/SKILL.md

@@ -9,7 +9,14 @@ description: >
 
 # PMX Canvas Testing
 
-Use this skill whenever you touch code in this repo and need a consistent verification path.
+Use this skill when changing the PMX Canvas product checkout and you need a consistent verification
+path. The commands and paths below refer to that source checkout, not to a workspace that merely
+has the published package and skills installed.
+
+For an isolated consumer workspace, do not expect the package to contain this checkout's
+`tests/`, source-only scripts, or Playwright configuration. Validate package transports and host
+integration through their public CLI, MCP, HTTP, and SDK surfaces; use the
+`published-consumer-e2e` skill when a packed-install outside-in check is required.
 
 ## When To Use
 
@@ -59,9 +66,11 @@ and check `$?`, then read the file.
 
 ## Current Project Test Surface
 
-- Bun tests live under `tests/unit/`
-- Playwright browser smoke lives under `tests/e2e/`
-- CI runs Bun coverage plus the browser smoke flow
+- In the product source checkout, Bun tests live under `tests/unit/`.
+- In the product source checkout, Playwright browser smoke lives under `tests/e2e/`.
+- Product CI runs those checkout suites: Bun coverage plus the browser smoke flow.
+- An isolated installed consumer instead tests the package's public transports and host behavior;
+  it does not run or depend on the product checkout's source suites.
 
 ## WebView Automation Caveat
 

package/skills/web-artifacts-builder/scripts/bundle-artifact.sh

@@ -56,14 +56,12 @@ function replay_filtered_stderr() {
 
 function run_with_filtered_stderr() {
   local stderr_file
+  local status
   stderr_file="$(mktemp)"
-  if "$@" 2>"$stderr_file"; then
-    replay_filtered_stderr "$stderr_file"
-    rm -f "$stderr_file"
-    return 0
-  fi
-
-  local status=$?
+  set +e
+  "$@" 2>"$stderr_file"
+  status=$?
+  set -e
   replay_filtered_stderr "$stderr_file"
   rm -f "$stderr_file"
   return "$status"
@@ -161,7 +159,19 @@ rm -rf dist bundle.html
 
 # Build with Parcel
 echo "🔨 Building with Parcel..."
-run_with_filtered_stderr run_local_binary parcel build index.html --dist-dir dist --no-source-maps --log-level error
+parcel_status=0
+run_with_filtered_stderr run_local_binary parcel build index.html --dist-dir dist --no-source-maps --log-level error || parcel_status=$?
+
+# Self-heal a wedged cache: these build projects are REUSED across artifact
+# builds, and a parcel killed mid-write (e.g. the canvas server torn down
+# during a build) leaves a corrupted .parcel-cache that makes every later
+# build die before emitting anything — permanently, until the cache goes.
+# Retry exactly once from a cold cache, then preserve a genuine build failure.
+if [ "$parcel_status" -ne 0 ] || [ ! -s "dist/index.html" ]; then
+  echo "🧹 Parcel build failed or produced no output — clearing .parcel-cache and retrying cold..."
+  rm -rf .parcel-cache dist
+  run_with_filtered_stderr run_local_binary parcel build index.html --dist-dir dist --no-source-maps --log-level error
+fi
 
 if [ ! -s "dist/index.html" ]; then
   echo "❌ Error: Parcel did not produce dist/index.html" >&2

package/src/client/canvas/CanvasNode.tsx

@@ -234,6 +234,7 @@ export function CanvasNode({ node, children, onContextMenu }: CanvasNodeProps) {
 
   const handleTitlePointerDown = useCallback(
     (e: PointerEvent) => {
+      if (e.button !== 0) return;
       if (renaming) return;
       if (canvasTool.value === 'connect') {
         startEdgeDrag(e);
@@ -267,6 +268,7 @@ export function CanvasNode({ node, children, onContextMenu }: CanvasNodeProps) {
 
   const handlePointerDown = useCallback(
     (e: PointerEvent) => {
+      if (e.button !== 0) return;
       e.stopPropagation();
       if (canvasTool.value === 'connect') {
         startEdgeDrag(e);
@@ -281,8 +283,10 @@ export function CanvasNode({ node, children, onContextMenu }: CanvasNodeProps) {
     [node.id, startEdgeDrag],
   );
 
-  const handleContextMenuEvent = useCallback(
+  const handleDblClick = useCallback(
     (e: MouseEvent) => {
+      const target = e.target instanceof Element ? e.target : null;
+      if (target?.closest('button, input, textarea, select, a, [contenteditable="true"]')) return;
       if (onContextMenu) onContextMenu(e, node.id);
     },
     [onContextMenu, node.id],
@@ -312,13 +316,6 @@ export function CanvasNode({ node, children, onContextMenu }: CanvasNodeProps) {
     [node],
   );
 
-  // ── Double-click rename ───────────────────────────────
-  const handleTitleDblClick = useCallback((e: MouseEvent) => {
-    e.stopPropagation();
-    setRenaming(true);
-    requestAnimationFrame(() => renameRef.current?.focus());
-  }, []);
-
   const title =
     (node.data.title as string) ||
     // Untitled file nodes (created before titles were synthesized server-side)
@@ -453,7 +450,7 @@ export function CanvasNode({ node, children, onContextMenu }: CanvasNodeProps) {
         data-node-type={node.type}
         style={{ ...nodeStyle, width: 'auto', height: 'auto' }}
         onPointerDown={handlePointerDown}
-        onContextMenu={handleContextMenuEvent}
+        onDblClick={handleDblClick}
         title="Expand group"
         data-testid="group-chip"
       >
@@ -499,7 +496,7 @@ export function CanvasNode({ node, children, onContextMenu }: CanvasNodeProps) {
       onMouseDown={(e) => {
         if (e.shiftKey) e.preventDefault();
       }}
-      onContextMenu={handleContextMenuEvent}
+      onDblClick={handleDblClick}
     >
       {isGroup && (
         <div class="node-titlebar group-edge-row" onPointerDown={handleTitlePointerDown}>
@@ -517,7 +514,7 @@ export function CanvasNode({ node, children, onContextMenu }: CanvasNodeProps) {
                 onClick={(e) => e.stopPropagation()}
               />
             ) : (
-              <span class="group-name" onDblClick={handleTitleDblClick} title={`${title} — double-click to rename`}>
+              <span class="group-name" title={title}>
                 {title}
               </span>
             )}
@@ -659,7 +656,7 @@ export function CanvasNode({ node, children, onContextMenu }: CanvasNodeProps) {
               onClick={(e) => e.stopPropagation()}
             />
           ) : (
-            <span class="node-title" onDblClick={handleTitleDblClick} title={`${title} — double-click to rename`}>
+            <span class="node-title" title={title}>
               {title}
             </span>
           )}

package/src/client/canvas/CanvasViewport.tsx

@@ -409,7 +409,7 @@ export function CanvasViewport({
       if (e.target !== container) return;
 
       // Pan tool / held Space: usePanZoom owns this drag.
-      if (isPanModeActive() || e.button === 1) {
+      if (isPanModeActive() || e.button === 1 || e.button === 2) {
         if (!e.shiftKey && !lassoRef.current) {
           activeNodeId.value = null;
           clearSelection();
@@ -659,50 +659,36 @@ export function CanvasViewport({
     };
   }, [containerRef]);
 
-  // ── Double-click on background → create new markdown node ──
+  // ── Double-click on background → open node creation menu ──
   const handleDblClick = useCallback(
     (e: MouseEvent) => {
       if (annotationMode) return;
       const container = containerRef.current;
-      if (!container || e.target !== container) return;
+      if (!container || e.target !== container || !onCanvasContextMenu) return;
       const rect = container.getBoundingClientRect();
       const v = viewport.value;
       const wx = (e.clientX - rect.left - v.x) / v.scale;
       const wy = (e.clientY - rect.top - v.y) / v.scale;
-      // Offset so node centers on click point
-      const nodeW = 520;
-      const nodeH = 360;
-      createNodeFromClient({
-        type: 'markdown',
-        title: 'New note',
-        x: wx - nodeW / 2,
-        y: wy - nodeH / 2,
-        width: nodeW,
-        height: nodeH,
-      });
+      onCanvasContextMenu(e, wx, wy);
     },
-    [annotationMode, containerRef],
+    [annotationMode, containerRef, onCanvasContextMenu],
   );
 
-  const handleContextMenu = useCallback(
-    (e: MouseEvent) => {
-      if (annotationMode) return;
-      if (!onCanvasContextMenu) return;
-
-      const container = containerRef.current;
-      if (!container) return;
-
-      const target = e.target instanceof Element ? e.target : null;
-      if (target?.closest('.canvas-node')) return;
+  const handleContextMenu = useCallback((e: MouseEvent) => {
+    // Right-click is a pan gesture, never a menu trigger. Suppress the
+    // browser menu whether it lands on the board or bubbles from a node.
+    e.preventDefault();
+  }, []);
 
-      const rect = container.getBoundingClientRect();
-      const v = viewport.value;
-      const canvasX = (e.clientX - rect.left - v.x) / v.scale;
-      const canvasY = (e.clientY - rect.top - v.y) / v.scale;
-      onCanvasContextMenu(e, canvasX, canvasY);
-    },
-    [annotationMode, containerRef, onCanvasContextMenu],
-  );
+  // Internal native drags (selected node text, links inside rendered
+  // markdown) re-enter this same container as drops and mint webpage nodes
+  // from card text (0.5.1 Amp finding D). Kill them at the source — external
+  // drags never fire a local dragstart, so file/URL import is untouched.
+  // Editable elements keep their native drag (text drag inside an editor).
+  const handleDragStart = useCallback((e: DragEvent) => {
+    if (isEditableElement(e.target instanceof Element ? e.target : null)) return;
+    e.preventDefault();
+  }, []);
 
   // ── Drag-and-drop files from filesystem ──
   const handleDragEnter = useCallback((e: DragEvent) => {
@@ -824,6 +810,7 @@ export function CanvasViewport({
       onPointerUp={handlePointerUp}
       onContextMenu={handleContextMenu}
       onDblClick={handleDblClick}
+      onDragStart={handleDragStart}
       onDragEnter={handleDragEnter}
       onDragOver={handleDragOver}
       onDragLeave={handleDragLeave}

package/src/client/canvas/ContextMenu.tsx

@@ -466,6 +466,19 @@ function buildNodeMenuItems(node: CanvasNodeState): MenuItem[] {
     action: () => focusNode(node.id),
   });
 
+  items.push({
+    label: 'Rename…',
+    action: () => {
+      void askText('Rename node', 'Node title', {
+        initial: typeof node.data.title === 'string' ? node.data.title : '',
+        confirm: 'Save',
+      }).then((title) => {
+        if (!title?.trim()) return;
+        void updateNodeFromClient(node.id, { title: title.trim() });
+      });
+    },
+  });
+
   // Expand into full-viewport overlay for focused work
   if (EXPANDABLE_TYPES.has(node.type)) {
     items.push({

package/src/client/canvas/EdgeLayer.tsx

@@ -166,7 +166,7 @@ function EdgePath({ edge, fromNode, toNode, focused, dimmed, selected, scale, on
     <g>
       {/* Invisible wide hitbox — the ONE interactive part of the edge layer
           (the svg itself is pointer-events:none): click selects the edge
-          (Delete then removes it), right-click opens the edge menu. */}
+          (Delete then removes it), double-click opens the edge menu. */}
       <path
         d={d}
         fill="none"
@@ -179,7 +179,7 @@ function EdgePath({ edge, fromNode, toNode, focused, dimmed, selected, scale, on
           e.stopPropagation();
           selectedEdgeId.value = edge.id;
         }}
-        onContextMenu={onContextMenu ? (e) => onContextMenu(e as unknown as MouseEvent, edge.id) : undefined}
+        onDblClick={onContextMenu ? (e) => onContextMenu(e as unknown as MouseEvent, edge.id) : undefined}
       />
 
       {/* Glow layer for focused or selected edges */}

package/src/client/canvas/SessionPanel.tsx

@@ -288,7 +288,10 @@ function TimelineRow({ entry }: { entry: TimelineEntry }) {
 }
 
 export function SessionPanel() {
-  const [collapsed, setCollapsed] = useState(false);
+  // A gate may temporarily expand the panel without turning that expansion
+  // into a user preference. Once the last gate settles, only an explicitly
+  // opened panel remains open.
+  const [manuallyOpened, setManuallyOpened] = useState(false);
   const session = activeSession.value;
   const items = sessionWorkItems.value;
   const gates = pendingGates.value;
@@ -307,12 +310,28 @@ export function SessionPanel() {
     void refreshTimeline();
   }, []);
 
-  if (collapsed) {
+  const expanded = manuallyOpened || gates.length > 0;
+  if (!expanded) {
     return (
       <aside class="session-panel is-collapsed" aria-label="Session (collapsed)">
-        <button type="button" class="session-collapse" onClick={() => setCollapsed(false)} title="Expand session panel">
+        <button
+          type="button"
+          class="session-collapse"
+          onClick={() => setManuallyOpened(true)}
+          title="Expand session panel"
+        >
           ‹
         </button>
+        {session && (
+          <span
+            class={`session-collapsed-live phase-${session.phase}`}
+            title={agentPhaseLabel(session)}
+            aria-label={`Session live: ${agentPhaseLabel(session)}`}
+          >
+            <span class="session-live-dot" aria-hidden="true" />
+            live
+          </span>
+        )}
         <span class="session-collapsed-label">Session</span>
       </aside>
     );
@@ -342,7 +361,7 @@ export function SessionPanel() {
         <button
           type="button"
           class="session-collapse"
-          onClick={() => setCollapsed(true)}
+          onClick={() => setManuallyOpened(false)}
           title="Collapse session panel"
         >
           ›

package/src/client/canvas/ShortcutOverlay.tsx

@@ -32,7 +32,7 @@ const GROUPS: ShortcutGroup[] = [
       { keys: 'I / W / H', desc: 'New image / webpage / HTML surface' },
       { keys: 'Shift+F', desc: 'New file node (workspace path)' },
       { keys: 'G / Shift+G', desc: 'Group the selection (new frame when empty) / ungroup' },
-      { keys: 'Double-click', desc: 'Create new markdown note on canvas' },
+      { keys: 'Double-click', desc: 'Open actions on a node or create menu on canvas' },
       { keys: 'Drag port \u2192 node', desc: 'Connect two nodes (hover to reveal ports)' },
     ],
   },
@@ -52,7 +52,7 @@ const GROUPS: ShortcutGroup[] = [
     shortcuts: [
       { keys: '?', desc: 'Toggle this shortcut overlay' },
       { keys: 'Minimap', desc: 'Click/drag to navigate (toggle in the rail)' },
-      { keys: 'Right-click', desc: 'Context menu — dock, focus, connect' },
+      { keys: 'Right-drag', desc: 'Pan the board from anywhere' },
     ],
   },
 ];