pmx-canvas 0.3.1 → 0.3.3

package/dist/types/cli/agent.d.ts

@@ -10,4 +10,12 @@
  * - Idempotent operations where possible
  * - --yes for destructive actions, --dry-run for preview
  */
-export declare function runAgentCli(args: string[]): Promise<void>;
+/**
+ * Extract the global `--port <n>` / `--server-url <url>` flags (any position,
+ * `=` or space-separated value) and set the invocation's target override.
+ * Returns the remaining args for command dispatch. Invalid values are a loud
+ * `die` — never a silent fallback to the default port. `--server-url` wins
+ * over `--port` when both are given.
+ */
+export declare function extractGlobalTargetFlags(args: string[]): string[];
+export declare function runAgentCli(rawArgs: string[]): Promise<void>;

package/dist/types/cli/daemon.d.ts

@@ -17,6 +17,8 @@ export declare function removePidFile(path: string): void;
 export interface HealthStatus {
     responsive: boolean;
     workspace: string | null;
+    /** The serving process's own pid, self-reported by /health (0.3.3+ servers). */
+    pid: number | null;
 }
 export declare function readHealthStatus(url: string): Promise<HealthStatus>;
 export declare function isHealthy(url: string): Promise<boolean>;
@@ -65,6 +67,21 @@ export declare function startDaemonMode(options: DaemonPaths & {
     waitMs: number;
     entry: string;
 }): Promise<void>;
+/**
+ * Resolve the pid story `serve status` reports. The AUTHORITATIVE pid is the
+ * serving process's self-reported /health pid: the pid file can go stale when
+ * something other than `serve --daemon` (re)spawned the server on this port —
+ * e.g. a host adapter respawn (0.3.2 report Finding P). Reporting the dead
+ * file pid as `pid` while `running` was true made agents read a contradiction
+ * (`running: true, pidRunning: false`); report the real listener instead and
+ * mark the file explicitly stale. Pre-0.3.3 servers don't self-report a pid —
+ * for those, fall back to the pid-file view unchanged.
+ */
+export declare function resolveDaemonPidView(pidFilePid: number | null, pidFilePidRunning: boolean, health: HealthStatus): {
+    pid: number | null;
+    pidRunning: boolean;
+    pidFileStale: boolean;
+};
 export declare function showServeStatus(options: DaemonPaths & {
     entry: string;
 }): Promise<void>;

package/dist/types/client/nodes/ExtAppFrame.d.ts

@@ -19,7 +19,15 @@ interface ExtAppHostDimensionsTarget {
  * everywhere we can test (Chrome / Codex / Playwright).
  */
 export declare function isWebKitOnlyHost(userAgent: string): boolean;
-export declare function nextWebkitRepaintSlot(): number;
+export declare const WEBKIT_REMOUNT_SETTLE_MS = 1000;
+export interface WebkitRemountTask {
+    /** Perform the remount. Return false if the node no longer needs it (skips the boot wait). */
+    remount: () => boolean;
+    /** Resolves when the remounted app genuinely boots AND finishes its bootstrap replay, or after a bounded timeout. */
+    awaitBoot: () => Promise<void>;
+}
+export declare function extAppRecoveryLog(nodeId: string, event: string): void;
+export declare function enqueueWebkitRemount(task: WebkitRemountTask): void;
 export declare function shouldScheduleWebKitRepaint(status: ExtAppFrameStatus, hasReplayToolResult: boolean): boolean;
 export declare function getExtAppBridgeInitKey(node: CanvasNodeState, retryKey: number): string;
 export declare function resolveExtAppDisplayModeRequest(requestedMode: DisplayMode, isExpanded: boolean): {
@@ -30,6 +38,19 @@ export declare function resolveExtAppDisplayModeRequest(requestedMode: DisplayMo
 export declare function sendExtAppBootstrapState(bridge: ExtAppBridgeNotifications, toolInput: Record<string, unknown>, toolResult: CallToolResult | undefined): Promise<void>;
 export declare function resolveExtAppSandbox(value: unknown): string;
 export declare function buildExtAppAxBridgeScript(axToken: string, nodeId: string): string;
+/**
+ * Boot beacon injected into EVERY ext-app document (not gated on AX): posts one
+ * parent message the moment the iframe's scripts execute. This is the liveness
+ * signal the WebKit never-booted watchdog keys on — it distinguishes an app
+ * that is alive but boots via the 1200ms bootstrap fallback (e.g. a non-SDK
+ * widget that never sends ui/notifications/initialized) from a dead window
+ * whose scripts never ran. Without it, the watchdog treated every
+ * fallback-booted app as never-booted and remounted it up to the attempt cap —
+ * a reboot/flicker loop for exactly the apps the fallback exists to support
+ * (0.3.2 pre-release review). The token scopes the message to this component;
+ * the host also checks event.source against the live iframe.
+ */
+export declare function buildExtAppBootBeaconScript(frameToken: string, nodeId: string): string;
 export declare function injectExtAppAxBridgeScript(html: string, axBridgeScript: string): string;
 export declare function resolveExtAppContainerDimensions(target: ExtAppHostDimensionsTarget | null | undefined, fallback: {
     width: number;

package/dist/types/server/server.d.ts

@@ -81,6 +81,14 @@ export declare function setPrimaryWorkbenchAutoOpenEnabled(enabled: boolean): vo
 export declare function isPrimaryWorkbenchAutoOpenEnabled(): boolean;
 export declare function hasWorkbenchSubscribers(): boolean;
 export declare function setPrimaryWorkbenchCanvasPromptHandler(handler: PrimaryWorkbenchCanvasPromptHandler | null): void;
+/**
+ * Containment check for bundle-asset serving. Separator-agnostic: on Windows,
+ * `resolve()` returns backslash paths, so comparing against a `${dir}/` template
+ * rejected every asset — /canvas/index.js 404'd and the SPA never booted (the
+ * 0.3.1 Windows report). Normalizing both sides keeps the check exact on POSIX
+ * and correct on win32, and testable with win32-shaped fixtures on any host.
+ */
+export declare function isCanvasBundlePath(distPath: string, bundleDir: string): boolean;
 export declare function buildMacBrowserOpenScript(appName: string, url: string): string;
 export declare function openUrlInExternalBrowser(url: string): boolean;
 /**

package/docs/RELEASE.md

@@ -124,6 +124,17 @@ If this is the first release from your machine, run `bunx npm login`
 once so Bun can reuse your npm credentials. CI does not need this —
 it uses `NPM_TOKEN` directly.
 
+## Sync consumer skill mirrors
+
+Every release since 0.3.0 has been retested against **stale** skill mirrors:
+consumer workspaces (e.g. `personalclaude`) carry copies of the pmx-canvas
+skill under `.github/`, `.codex/`, `.claude/`, and `.agents/`, and testers
+repeatedly had to sync them mid-cycle before results were trustworthy. After
+publishing, update the installed package in the consumer workspace and re-sync
+its four mirrors from
+`<global npm root>/pmx-canvas/skills/pmx-canvas/` so the first test pass runs
+against the released skill, not the previous version's guidance.
+
 ## GitHub release
 
 After `npm publish` succeeds:

package/docs/cli.md

@@ -2,7 +2,16 @@
 
 The CLI is the shell-native way to run and control PMX Canvas. It targets
 `http://localhost:4313` by default — override with `PMX_CANVAS_URL` or
-`PMX_CANVAS_PORT` when the server runs elsewhere.
+`PMX_CANVAS_PORT` when the server runs elsewhere, or per invocation with the
+global `--port <n>` / `--server-url <url>` flags (any position; `--server-url`
+wins over `--port`, and both win over the environment variables). An invalid
+value for either flag is a hard error — the CLI never falls back silently to
+the default port.
+
+```bash
+pmx-canvas node list --port 4750                      # target a non-default daemon
+pmx-canvas --server-url http://127.0.0.1:4750 status  # same, by URL
+```
 
 ## Server lifecycle
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Spatial canvas workbench for coding agents — infinite 2D canvas with agent-native CLI, MCP integration, nodes, edges, file watching, and snapshots",
   "type": "module",
   "main": "./src/server/index.ts",

package/skills/pmx-canvas/SKILL.md

@@ -24,7 +24,8 @@ Humans curate agent context by pinning nodes; agents read that curation through
    `workspace` must equal the intended absolute workspace root. A healthy listener on port 4313
    may belong to another project.
 3. **Read before write.** Search with `canvas_query { action: "search", query }` before creating
-   nodes. Read the full layout only when necessary.
+   nodes. Read the full layout only when necessary. The MCP parameter is `query` — passing the
+   HTTP API's `q` is silently ignored and returns zero results.
 4. **Snapshot before destructive changes.** Use `canvas_snapshot` (deprecated standalone; folds into
    the `canvas_snapshot` composite's `save` action in v0.4) before clear, restore, or a major
    reorganization.
@@ -33,7 +34,8 @@ Humans curate agent context by pinning nodes; agents read that curation through
    or edit, then pass the returned `intent.id` as `intentId` on the mutation so the ghost settles
    into the result. Use it as much as possible to make your next move and your work visible: the
    human watches intent form and can veto mid-thought. Skip it only for trivial in-place tweaks or
-   high-frequency batch churn.
+   high-frequency batch churn. The default TTL (~8s) expires between agent turns: signal with
+   `ttlMs: 30000` and settle by passing `intentId` on the mutation in the same or next call.
 6. **Mutate through current composites.** Prefer the 15 composite MCP tools below.
 7. **Arrange and validate.** After batch changes, use `canvas_view { action: "arrange" }` when
    appropriate and always finish with `canvas_query { action: "validate" }`.
@@ -215,13 +217,17 @@ Prefer `canvas_query { action: "search" }` over parsing the full layout.
   loads (e.g. the GitHub Copilot app's embedded WKWebView) can render as a black tile — a host
   compositor paint race on the nested iframe, **not** a broken node (the session is healthy and
   `sessionStatus` is `ready`; it renders fine in Chrome, the Codex browser, and for nodes created
-  live after the panel hydrates). The canvas forces a one-time post-boot repaint remount under
-  WebKit, which reliably repaints a **single** present-at-load
-  ext-app — but a board with **several** ext-apps present at WebKit panel-load can still black out
-  (the simultaneous cold-hydration burst overwhelms the WebKit compositor). Recovery is
-  deterministic: **expand-then-close** any black tile (forces a fresh mount in the fullscreen
-  overlay, which always paints), or open the workbench in a normal browser (Chrome). Do not
-  diagnose a healthy app session as a broken node; the durable fix is upstream in the host panel.
+  live after the panel hydrates). Under WebKit the canvas ATTEMPTS auto-recovery: after boot,
+  each present-at-load ext-app is remounted through a serialized, boot-aware queue (one app at a
+  time), with a watchdog retry for iframes that never boot and a re-arm when a panel that loaded
+  hidden becomes visible. Treat the auto-recovery as best-effort, NOT guaranteed — the 0.3.2
+  Copilot-host report shows tiles can still come up black in real WKWebView panels (compositing
+  success is not observable from page JS, so retries are bounded). Keep the cautionary behavior:
+  recovery is deterministic via **expand-then-close** of the black tile (forces a fresh mount in
+  the fullscreen overlay, which always paints), or open the workbench in a normal browser
+  (Chrome). Do not diagnose a healthy app session as a broken node. When reporting a black tile,
+  fetch `GET /api/canvas/debug/ext-app-recovery` from the daemon and attach the trace — it shows
+  what the recovery queue actually did in that panel.
 - Graph and json-render standalone surfaces use `display=site` and fill the browser viewport, and
   reflow on a live window resize in a normal browser. Some single-tab host browsers (e.g. the
   Codex in-app browser) don't deliver live-resize events, so a resized standalone chart can look

package/skills/pmx-canvas/references/full-reference.md

@@ -510,6 +510,13 @@ surfaces): `canvas_batch`, `canvas_pin_nodes`, `canvas_screenshot`, `canvas_ax_i
 `canvas_diff` — deprecated pending a `canvas_snapshot` composite in v0.4; the name collides with
 the current save-snapshot tool, so the composite cannot land additively).
 
+`canvas_batch` supports exactly these ops: `node.add`, `node.update`, `node.remove`, `graph.add`,
+`edge.add`, `edge.remove`, `group.create`, `group.add`, `group.remove`, `pin.set`/`pin.add`/
+`pin.remove`, `snapshot.save`, and `arrange`. Anything else fails with "Unsupported canvas_batch
+operation" — batch is non-atomic, so earlier ops stay applied and the response carries
+`failedIndex`. `canvas_screenshot` requires an active automation WebView: call
+`canvas_webview { action: "start" }` first.
+
 > **Removed in v0.3.0 → use the composite instead**: `canvas_open_mcp_app` / `canvas_add_diagram` /
 > `canvas_build_web_artifact` → **`canvas_app`**; `canvas_webview_start` / `canvas_webview_status` /
 > `canvas_webview_stop` / `canvas_resize` / `canvas_evaluate` → **`canvas_webview`**;

package/src/cli/agent.ts

@@ -89,13 +89,77 @@ interface CanvasSchemaResponse {
   };
 }
 
+// Per-invocation target override from the global --server-url / --port flags.
+// Before these existed, `--port 4750` on any agent command was SILENTLY ignored
+// and the command hit the default 4313 daemon — which once pointed a test
+// automation WebView at a live production board.
+let cliTargetOverride: string | null = null;
+
 function getBaseUrl(): string {
+  if (cliTargetOverride) return cliTargetOverride;
   const envUrl = process.env.PMX_CANVAS_URL;
   if (envUrl) return envUrl.replace(/\/$/, '');
   const port = process.env.PMX_CANVAS_PORT || DEFAULT_PORT;
   return `http://localhost:${port}`;
 }
 
+/**
+ * Extract the global `--port <n>` / `--server-url <url>` flags (any position,
+ * `=` or space-separated value) and set the invocation's target override.
+ * Returns the remaining args for command dispatch. Invalid values are a loud
+ * `die` — never a silent fallback to the default port. `--server-url` wins
+ * over `--port` when both are given.
+ */
+export function extractGlobalTargetFlags(args: string[]): string[] {
+  cliTargetOverride = null;
+  let portOverride: number | null = null;
+  let urlOverride: string | null = null;
+  const rest: string[] = [];
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    let name: 'port' | 'server-url' | null = null;
+    let value: string | undefined;
+    if (arg === '--port' || arg === '--server-url') {
+      name = arg.slice(2) as 'port' | 'server-url';
+      value = args[i + 1];
+      i += 1;
+    } else if (arg.startsWith('--port=')) {
+      name = 'port';
+      value = arg.slice('--port='.length);
+    } else if (arg.startsWith('--server-url=')) {
+      name = 'server-url';
+      value = arg.slice('--server-url='.length);
+    } else {
+      rest.push(arg);
+      continue;
+    }
+
+    if (name === 'port') {
+      const port = Number(value);
+      if (!value || !Number.isInteger(port) || port <= 0 || port > 65535) {
+        die(
+          `--port requires a port number, got ${value === undefined ? 'no value' : JSON.stringify(value)}.`,
+          'Example: --port 4313. Without the flag, PMX_CANVAS_PORT / PMX_CANVAS_URL pick the target.',
+        );
+      }
+      portOverride = port;
+    } else {
+      if (!value || !/^https?:\/\//.test(value)) {
+        die(
+          `--server-url requires an http(s) URL, got ${value === undefined ? 'no value' : JSON.stringify(value)}.`,
+          'Example: --server-url http://localhost:4313. Without the flag, PMX_CANVAS_URL picks the target.',
+        );
+      }
+      urlOverride = value.replace(/\/$/, '');
+    }
+  }
+
+  if (urlOverride) cliTargetOverride = urlOverride;
+  else if (portOverride) cliTargetOverride = `http://localhost:${portOverride}`;
+  return rest;
+}
+
 function die(message: string, hint?: string): never {
   const out: Record<string, string> = { error: message };
   if (hint) out.hint = hint;
@@ -3535,6 +3599,8 @@ Analysis:
 
 Global flags:
   --help, -h                          Show help for any command
+  --port <n>                          Target daemon port for this invocation (overrides PMX_CANVAS_PORT)
+  --server-url <url>                  Target server URL for this invocation (overrides PMX_CANVAS_URL; wins over --port)
 
 Environment:
   PMX_CANVAS_URL    Server URL (default: http://localhost:4313)
@@ -3592,7 +3658,8 @@ async function readStdin(): Promise<string> {
 
 // ── Router ───────────────────────────────────────────────────
 
-export async function runAgentCli(args: string[]): Promise<void> {
+export async function runAgentCli(rawArgs: string[]): Promise<void> {
+  const args = extractGlobalTargetFlags(rawArgs);
   if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
     showTopLevelHelp();
     return;

package/src/cli/daemon.ts

@@ -88,20 +88,26 @@ export function removePidFile(path: string): void {
 export interface HealthStatus {
   responsive: boolean;
   workspace: string | null;
+  /** The serving process's own pid, self-reported by /health (0.3.3+ servers). */
+  pid: number | null;
 }
 
 export async function readHealthStatus(url: string): Promise<HealthStatus> {
   try {
     const response = await fetch(url);
-    if (!response.ok) return { responsive: false, workspace: null };
+    if (!response.ok) return { responsive: false, workspace: null, pid: 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 };
+    const pid =
+      payload && typeof payload === 'object' && 'pid' in payload && typeof payload.pid === 'number'
+        ? payload.pid
+        : null;
+    return { responsive: true, workspace, pid };
   } catch {
-    return { responsive: false, workspace: null };
+    return { responsive: false, workspace: null, pid: null };
   }
 }
 
@@ -335,17 +341,41 @@ export async function startDaemonMode(
   process.exit(0);
 }
 
+/**
+ * Resolve the pid story `serve status` reports. The AUTHORITATIVE pid is the
+ * serving process's self-reported /health pid: the pid file can go stale when
+ * something other than `serve --daemon` (re)spawned the server on this port —
+ * e.g. a host adapter respawn (0.3.2 report Finding P). Reporting the dead
+ * file pid as `pid` while `running` was true made agents read a contradiction
+ * (`running: true, pidRunning: false`); report the real listener instead and
+ * mark the file explicitly stale. Pre-0.3.3 servers don't self-report a pid —
+ * for those, fall back to the pid-file view unchanged.
+ */
+export function resolveDaemonPidView(
+  pidFilePid: number | null,
+  pidFilePidRunning: boolean,
+  health: HealthStatus,
+): { pid: number | null; pidRunning: boolean; pidFileStale: boolean } {
+  const authoritative = health.responsive && health.pid !== null;
+  return {
+    pid: authoritative ? health.pid : pidFilePid,
+    pidRunning: authoritative ? true : pidFilePidRunning,
+    pidFileStale: pidFilePid !== null && !pidFilePidRunning && (!health.responsive || health.pid !== pidFilePid),
+  };
+}
+
 export async function showServeStatus(options: DaemonPaths & { entry: string }): Promise<void> {
   const healthUrl = `http://localhost:${options.port}/health`;
   const url = `http://localhost:${options.port}/workbench`;
-  const pid = readPidFile(options.pidFile);
-  const pidRunning = pid ? isOwnDaemonProcess(pid, options.entry) : false;
+  const pidFilePid = readPidFile(options.pidFile);
+  const pidFilePidRunning = pidFilePid ? isOwnDaemonProcess(pidFilePid, options.entry) : false;
   const health = await readHealthStatus(healthUrl);
   const responsive = health.responsive;
-  const running = responsive || pidRunning;
+  const running = responsive || pidFilePidRunning;
+  const { pid, pidRunning, pidFileStale } = resolveDaemonPidView(pidFilePid, pidFilePidRunning, health);
   // Clean up a stale pid file, but never a concurrent starter's fresh empty
   // spawn lock (that would let a racing `serve --daemon` double-spawn).
-  if (!running && existsSync(options.pidFile) && !pidRunning && !isFreshEmptyLock(options.pidFile)) {
+  if (!running && existsSync(options.pidFile) && !pidFilePidRunning && !isFreshEmptyLock(options.pidFile)) {
     removePidFile(options.pidFile);
   }
 
@@ -357,6 +387,8 @@ export async function showServeStatus(options: DaemonPaths & { entry: string }):
     workspace: health.workspace,
     pid,
     pidRunning,
+    pidFilePid,
+    pidFileStale,
     url,
     healthUrl,
     logFile: options.logFile,

package/src/cli/index.ts

@@ -120,6 +120,25 @@ function stripOption(argv: string[], name: string): string[] {
   return stripped;
 }
 
+// Global target flags (--port / --server-url) may precede the subcommand, e.g.
+// `pmx-canvas --port 4750 node list`. Skip them (and their values) when picking
+// the subcommand to dispatch, so the agent CLI — which strips these flags via
+// extractGlobalTargetFlags and validates them loudly — is reached instead of the
+// server-startup fallback. Only these two flags are skipped; other leading flags
+// (--mcp, --demo, …) still route exactly as before.
+function commandAfterGlobalTargetFlags(argv: string[]): string {
+  for (let index = 0; index < argv.length; index++) {
+    const arg = argv[index];
+    if (arg === '--port' || arg === '--server-url') {
+      if (index + 1 < argv.length && !argv[index + 1].startsWith('-')) index++;
+      continue;
+    }
+    if (arg.startsWith('--port=') || arg.startsWith('--server-url=')) continue;
+    return arg;
+  }
+  return '';
+}
+
 function runMcpServerProcess(): Promise<void> {
   return new Promise((resolvePromise, rejectPromise) => {
     const child = spawn(process.execPath, ['run', mcpServerEntry], {
@@ -181,7 +200,8 @@ if (firstArg === 'serve') {
   args.shift();
 }
 
-if (AGENT_COMMANDS.has(firstArg) && firstArg !== 'serve') {
+const routedCommand = commandAfterGlobalTargetFlags(args);
+if (AGENT_COMMANDS.has(routedCommand) && routedCommand !== 'serve') {
   await runAgentCli(args);
 } else if (args.includes('--mcp')) {
   // MCP server mode: stdio transport, auto-starts canvas on first tool call