pmx-canvas 0.4.3 → 0.4.5

package/dist/canvas/surface-theme.css

@@ -281,6 +281,38 @@
   --color-danger: #E57373;
 }
 
+:root[data-theme="volt"] {
+  /* ── Core palette (volt · green-tinted charcoal + coral) ── */
+  --c-bg: #0B0D0B;
+  --c-panel: #171A17;
+  --c-panel-soft: #111311;
+  --c-line: #272A27;
+  --c-text: #F6FFF5;
+  --c-text-soft: #CBD3CA;
+  --c-muted: #9CA49C;
+  --c-dim: #626962;
+  --c-accent: #DFDFC1;
+  --c-ok: #52C880;
+  --c-warn: #E4C465;
+  --c-warn-alt: #FFB300;
+  --c-danger: #D67670;
+  --c-purple: #BC8FB4;
+
+  --color-bg: #0B0D0B;
+  --color-panel: #171A17;
+  --color-surface: #111311;
+  --color-border: #272A27;
+  --color-text: #F6FFF5;
+  --color-text-primary: #F6FFF5;
+  --color-text-secondary: #CBD3CA;
+  --color-text-muted: #9CA49C;
+  --color-text-dim: #626962;
+  --color-accent: #DFDFC1;
+  --color-success: #52C880;
+  --color-warning: #E4C465;
+  --color-danger: #D67670;
+}
+
 html,
 body {
   margin: 0;

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

@@ -22,5 +22,6 @@ import './commands/ax.js';
 import './commands/webview.js';
 import './commands/apps.js';
 import './commands/copilot.js';
+import './commands/skills.js';
 export { extractGlobalTargetFlags };
 export declare function runAgentCli(rawArgs: string[]): Promise<void>;

package/dist/types/cli/commands/skills.d.ts

@@ -0,0 +1,41 @@
+export declare const BUNDLED_SKILLS: readonly ["pmx-canvas", "pmx-canvas-testing", "pmx-canvas-orchestration"];
+export interface SkillTreeComparison {
+    inSync: boolean;
+    /** Files present in the package tree but missing or different in the mirror. */
+    missingOrDifferent: string[];
+    /** Files present in the mirror but not in the package tree. */
+    extra: string[];
+}
+export declare function compareSkillTrees(sourceRoot: string, targetRoot: string): SkillTreeComparison;
+export interface InstalledSkillMirror {
+    /** The directory that owns the skills/ folder (e.g. ".codex", ".github", or any agent dir). */
+    host: string;
+    skill: string;
+    dir: string;
+}
+/**
+ * Find the bundled skills' installed copies in this workspace: any immediate
+ * child directory holding `skills/<skill>/SKILL.md`, regardless of which agent
+ * that directory belongs to. The package's own skills source is excluded so
+ * running inside the pmx-canvas checkout never compares a tree to itself.
+ */
+export declare function discoverInstalledSkillMirrors(workspaceRoot: string, packageSkillsRoot: string): InstalledSkillMirror[];
+export interface SkillMirrorResult {
+    host: string;
+    skill: string;
+    dir: string;
+    status: 'in-sync' | 'synced' | 'drifted' | 'skipped-not-a-package-copy';
+    missingOrDifferent?: string[];
+    extra?: string[];
+}
+/**
+ * A mirror is only replaceable when its SKILL.md frontmatter `name:` matches
+ * the bundled skill it sits under. A user's own skill living in a same-named
+ * directory (different frontmatter identity) must never be deleted — these
+ * trees are typically gitignored, so a wrong replace is unrecoverable.
+ */
+export declare function mirrorIdentityMatches(mirrorDir: string, skill: string): boolean;
+/** Sync (or, with check=true, only compare) every INSTALLED mirror against the package trees. */
+export declare function syncInstalledSkillMirrors(packageSkillsRoot: string, workspaceRoot: string, opts: {
+    check: boolean;
+}): SkillMirrorResult[];

package/dist/types/client/state/intent-store.d.ts

@@ -15,6 +15,12 @@ export interface ClientIntent extends PmxAxIntent {
 export declare const intents: import("@preact/signals-core").Signal<Map<string, ClientIntent>>;
 /** The ghost currently hovered — drives Esc-to-veto. */
 export declare const hoveredIntentId: import("@preact/signals-core").Signal<string | null>;
+/**
+ * Minimum time a ghost stays in its forming state before a settle/dissolve
+ * plays. Fast agents (and every server auto-ghost) signal and settle within
+ * milliseconds — without this floor, correct ghost usage is imperceptible.
+ */
+export declare const MIN_FORMING_MS = 650;
 /** A live `ax-intent` frame: (re)place the ghost in its forming state. */
 export declare function upsertIntent(intent: PmxAxIntent): void;
 export declare function removeIntent(id: string): void;

package/dist/types/client/state/sse-bridge.d.ts

@@ -1,3 +1,4 @@
+export declare function forcedTransport(): 'poll' | 'sse' | null;
 /** @internal — exported for testing */
 export declare function hashPath(path: string): string;
 /** @internal — exported for testing */

package/dist/types/server/ax-state-manager.d.ts

@@ -77,6 +77,7 @@ export declare class AxStateManager {
         status?: PmxAxWorkItemStatus;
         detail?: string | null;
         nodeIds?: string[];
+        agentId?: string | null;
     }, options?: {
         source?: PmxAxSource;
     }): PmxAxWorkItem;
@@ -85,6 +86,7 @@ export declare class AxStateManager {
         status?: PmxAxWorkItemStatus;
         detail?: string | null;
         nodeIds?: string[];
+        agentId?: string | null;
     }, options?: {
         source?: PmxAxSource;
     }): PmxAxWorkItem | null;
@@ -173,6 +175,7 @@ export declare class AxStateManager {
         data?: Record<string, unknown> | null;
     }, options?: {
         source?: PmxAxSource;
+        agentId?: string | null;
     }): PmxAxEvent;
     addEvidence(input: {
         kind: PmxAxEvidenceKind;
@@ -186,6 +189,8 @@ export declare class AxStateManager {
     }): PmxAxEvidence;
     recordSteeringMessage(message: string, options?: {
         source?: PmxAxSource;
+        agentId?: string | null;
+        target?: string | null;
     }): PmxAxSteeringMessage;
     markSteeringDelivered(id: string): boolean;
     /**

package/dist/types/server/ax-state.d.ts

@@ -1,6 +1,6 @@
 import type { CanvasLayout, CanvasNodeState } from './canvas-state.js';
 import type { AgentContextNode } from './agent-context.js';
-export type PmxAxSource = 'agent' | 'api' | 'browser' | 'cli' | 'codex' | 'copilot' | 'mcp' | 'sdk' | 'system';
+export type PmxAxSource = 'agent' | 'amp' | 'api' | 'browser' | 'cli' | 'codex' | 'copilot' | 'mcp' | 'sdk' | 'system';
 export interface PmxAxFocusState {
     nodeIds: string[];
     primaryNodeId: string | null;
@@ -24,6 +24,7 @@ export interface PmxAxWorkItem {
     createdAt: string;
     updatedAt: string;
     source: PmxAxSource | null;
+    agentId: string | null;
 }
 export interface PmxAxApprovalGate {
     id: string;
@@ -67,6 +68,7 @@ export interface PmxAxEvent {
     data: Record<string, unknown> | null;
     createdAt: string;
     source: PmxAxSource | null;
+    agentId: string | null;
 }
 export interface PmxAxEvidence {
     id: string;
@@ -87,6 +89,9 @@ export interface PmxAxSteeringMessage {
     delivered: boolean;
     createdAt: string;
     source: PmxAxSource | null;
+    agentId: string | null;
+    /** The agentId/consumer this steer is addressed to; null = broadcast to all consumers. */
+    target: string | null;
 }
 export interface PmxAxHostCapability {
     host: string | null;
@@ -257,6 +262,7 @@ export declare function createAxWorkItem(input: {
     status?: PmxAxWorkItemStatus;
     detail?: string | null;
     nodeIds?: string[];
+    agentId?: string | null;
 }, source: PmxAxSource | null, validNodeIds?: Set<string>): PmxAxWorkItem;
 export declare function createAxApprovalGate(input: {
     title: string;
@@ -280,7 +286,7 @@ export declare function createAxEvent(input: {
     detail?: string | null;
     nodeIds?: string[];
     data?: Record<string, unknown> | null;
-}, source: PmxAxSource | null): Omit<PmxAxEvent, 'seq'>;
+}, source: PmxAxSource | null, agentId?: string | null): Omit<PmxAxEvent, 'seq'>;
 export declare function createAxEvidence(input: {
     kind: PmxAxEvidenceKind;
     title: string;
@@ -289,7 +295,7 @@ export declare function createAxEvidence(input: {
     nodeIds?: string[];
     data?: Record<string, unknown> | null;
 }, source: PmxAxSource | null): Omit<PmxAxEvidence, 'seq'>;
-export declare function createAxSteeringMessage(message: string, source: PmxAxSource | null): Omit<PmxAxSteeringMessage, 'seq'>;
+export declare function createAxSteeringMessage(message: string, source: PmxAxSource | null, agentId?: string | null, target?: string | null): Omit<PmxAxSteeringMessage, 'seq'>;
 export declare function normalizeAxState(input: unknown, validNodeIds?: Set<string>): PmxAxState;
 export declare function buildAxContext(input: {
     layout: CanvasLayout;

package/dist/types/server/canvas-db.d.ts

@@ -56,7 +56,8 @@ export declare function loadPendingAxSteeringFromDB(db: Database, options?: {
 /**
  * NEWEST undelivered steering first (report #57) for the compact AX context lead
  * block — so a fresh steer is visible even behind a long backlog. Loop-safe: excludes
- * the consumer's own steering in SQL so the LIMIT applies after loop-prevention.
+ * the consumer's own steering and steering targeted at a different consumer in SQL
+ * so the LIMIT applies after both filters.
  * Distinct from loadPendingAxSteeringFromDB (FIFO oldest-first) which the claim/ack
  * delivery queue uses for ordered processing.
  */
@@ -64,7 +65,7 @@ export declare function loadNewestPendingAxSteeringFromDB(db: Database, options?
     consumer?: string;
     limit?: number;
 }): PmxAxSteeringMessage[];
-/** Total undelivered steering for a consumer (loop-safe — excludes the consumer's own). */
+/** Total undelivered steering for a consumer (loop-safe — excludes the consumer's own; target-scoped). */
 export declare function countPendingAxSteeringFromDB(db: Database, consumer?: string): number;
 export declare function loadAxTimelineSummaryFromDB(db: Database): PmxAxTimelineSummary;
 export declare function upsertAxHostCapabilityToDB(db: Database, cap: PmxAxHostCapability): void;

package/dist/types/server/canvas-state.d.ts

@@ -280,6 +280,7 @@ declare class CanvasStateManager {
         status?: PmxAxWorkItemStatus;
         detail?: string | null;
         nodeIds?: string[];
+        agentId?: string | null;
     }, options?: {
         source?: PmxAxSource;
     }): PmxAxWorkItem;
@@ -288,9 +289,17 @@ declare class CanvasStateManager {
         status?: PmxAxWorkItemStatus;
         detail?: string | null;
         nodeIds?: string[];
+        agentId?: string | null;
     }, options?: {
         source?: PmxAxSource;
     }): PmxAxWorkItem | null;
+    /**
+     * Mirror a work item's status onto every linked canvas node's `data.axWorkStatus`,
+     * through the standard node-update path (persistence + undo/redo, same as any other
+     * node data change). Nodes unlinked by an updateWorkItem nodeIds change have the
+     * mirrored status cleared.
+     */
+    private mirrorAxWorkStatusToNodes;
     getApprovalGates(): PmxAxApprovalGate[];
     requestApproval(input: {
         title: string;
@@ -376,6 +385,7 @@ declare class CanvasStateManager {
         data?: Record<string, unknown> | null;
     }, options?: {
         source?: PmxAxSource;
+        agentId?: string | null;
     }): PmxAxEvent;
     addEvidence(input: {
         kind: PmxAxEvidenceKind;
@@ -389,6 +399,8 @@ declare class CanvasStateManager {
     }): PmxAxEvidence;
     recordSteeringMessage(message: string, options?: {
         source?: PmxAxSource;
+        agentId?: string | null;
+        target?: string | null;
     }): PmxAxSteeringMessage;
     markSteeringDelivered(id: string): boolean;
     ingestActivity(input: {

package/dist/types/server/operations/ops/ax-shared.d.ts

@@ -11,9 +11,10 @@
 import { z } from 'zod';
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 import type { PmxAxSource } from '../../ax-state.js';
-export declare const AX_SOURCES: readonly ["agent", "api", "browser", "cli", "codex", "copilot", "mcp", "sdk", "system"];
+export declare const AX_SOURCES: readonly ["agent", "amp", "api", "browser", "cli", "codex", "copilot", "mcp", "sdk", "system"];
 /** Zod schema for the optional `source` field shared by AX MCP tool shapes. */
 export declare const AX_SOURCE_SHAPE: z.ZodOptional<z.ZodEnum<{
+    amp: "amp";
     agent: "agent";
     api: "api";
     browser: "browser";
@@ -24,6 +25,8 @@ export declare const AX_SOURCE_SHAPE: z.ZodOptional<z.ZodEnum<{
     sdk: "sdk";
     system: "system";
 }>>;
+/** Zod schema for the optional `agentId` field shared by AX MCP tool shapes. */
+export declare const AX_AGENT_ID_SHAPE: z.ZodOptional<z.ZodString>;
 /** An absent or unrecognized source falls back to the per-surface default. */
 export declare function normalizeAxSource(value: unknown, fallback: PmxAxSource): PmxAxSource;
 export declare function normalizeAxNodeIds(value: unknown): string[];

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

@@ -11,5 +11,13 @@ export declare function setOperationEventEmitter(emitter: OperationEventEmitter
 export declare function isEmitSuppressed(): boolean;
 /** Run `fn` with all operation SSE emits suppressed; restores depth on finally. */
 export declare function runWithSuppressedEmits<T>(fn: () => Promise<T>): Promise<T>;
-export declare function executeOperation(name: string, rawInput: unknown): Promise<unknown>;
+export interface ExecuteOperationMeta {
+    /**
+     * Skip the synthesized auto-ghost: set by the workbench's own HTTP calls
+     * (a human dragging a node is not agent activity) and by canvas.batch for
+     * its inner dispatches (batch churn is exempt, matching the skill contract).
+     */
+    suppressAutoGhost?: boolean;
+}
+export declare function executeOperation(name: string, rawInput: unknown, meta?: ExecuteOperationMeta): Promise<unknown>;
 export {};

package/dist/types/shared/ax-intent.d.ts

@@ -43,6 +43,12 @@ export interface PmxAxIntent {
     seq?: number;
     /** Source label of the surface that signalled the intent (mcp/api/sdk/...). */
     source?: string;
+    /**
+     * Server-synthesized ghost for an agent mutation that arrived WITHOUT an
+     * explicit canvas_intent signal (auto-ghost). Rendered visually lighter than
+     * a deliberate signal, and not vetoable — it settles immediately.
+     */
+    auto?: boolean;
     /** Epoch ms when the intent was first signalled. */
     createdAt: number;
     /** Epoch ms when the intent auto-dissolves if not settled/cleared first. */

package/dist/types/shared/themes.d.ts

@@ -9,7 +9,7 @@
  * theme picker, server validation, and surface documents pick it up from this
  * list.
  */
-export declare const CANVAS_THEMES: readonly ["dark", "light", "high-contrast", "midnight", "sepia", "arctic", "ember", "forest"];
+export declare const CANVAS_THEMES: readonly ["dark", "light", "high-contrast", "midnight", "sepia", "arctic", "ember", "forest", "volt"];
 export type CanvasThemeName = (typeof CANVAS_THEMES)[number];
 export declare function isCanvasTheme(value: unknown): value is CanvasThemeName;
 export declare function normalizeCanvasThemeName(value: unknown, fallback?: CanvasThemeName): CanvasThemeName;

package/docs/RELEASE.md

@@ -134,12 +134,20 @@ publishing, update the installed package in the consumer workspace and re-sync
 its four mirrors from `<global npm root>/pmx-canvas/skills/` so the first test
 pass runs against the released skills, not the previous version's guidance.
 
-Sync the **complete tree of every bundled skill** — `pmx-canvas` AND
-`pmx-canvas-testing`, including `references/`, `evals/`, and fixtures — and
-verify by diffing whole directories, not by comparing the `SKILL.md` hash
-alone. The 0.3.4 and 0.4.0 cycles both hit drift where `SKILL.md` matched but
-references/evals were stale, or a newly bundled skill was missing from the
-mirrors entirely.
+This is now one command in the consumer workspace (added post-0.4.3):
+
+```bash
+pmx-canvas skills sync --yes     # refreshes every INSTALLED skill copy from the package
+pmx-canvas skills sync --check   # drift detection only (exit 1 when stale)
+```
+
+It discovers the skill copies already installed in the workspace (whatever
+agent layout owns them — no host list is assumed) and compares/replaces
+**whole trees** — `references/`, `evals/`, fixtures — not `SKILL.md` hashes
+alone (the 0.3.x–0.4.x cycles repeatedly hit drift where the hash matched but
+supporting files were stale). Also re-run
+`pmx-canvas copilot install-extension --yes` in repos that use the Copilot
+adapter so the panel picks up new open-URL behavior.
 
 ## GitHub release
 

package/docs/bun-webview-integration.md

@@ -12,7 +12,7 @@ This document tracks:
 
 **Implemented** for Phase 1.
 
-The repo now targets Bun `>=1.3.12`, and PMX Canvas ships an opt-in, server-owned WebView automation session that can:
+The repo now targets Bun `>=1.3.14`, and PMX Canvas ships an opt-in, server-owned WebView automation session that can:
 
 - start a headless browser session for `/workbench`
 - report WebView runtime status
@@ -192,7 +192,7 @@ If `chromePath` or `chromeArgv` is provided, PMX Canvas forces a Chrome-backed s
 
 The repo now requires:
 
-- Bun `>=1.3.12`
+- Bun `>=1.3.14`
 
 That change is reflected in:
 

package/docs/cli.md

@@ -20,7 +20,7 @@ pmx-canvas                            # Start canvas, open browser
 pmx-canvas --demo                     # Start with the saved dashboard demo board
 pmx-canvas --port=8080                # Custom port
 pmx-canvas --no-open                  # Headless (for agents/CI)
-pmx-canvas --theme=light              # dark | light | high-contrast | midnight | sepia | arctic | ember | forest
+pmx-canvas --theme=light              # dark | light | high-contrast | midnight | sepia | arctic | ember | forest | volt
 pmx-canvas --mcp                      # Run as MCP server (stdio)
 pmx-canvas --webview-automation       # Start headless Bun.WebView session
 pmx-canvas open                       # Open the current workbench in a browser
@@ -211,6 +211,29 @@ pmx-canvas copilot install-extension --dry-run   # Preview target, writes nothin
 pmx-canvas copilot install-extension --yes        # Install/overwrite into .github/extensions/pmx-canvas/
 ```
 
+## Skill sync
+
+Refresh the pmx-canvas skill copies **already installed** in this workspace.
+The command discovers them (any `<agent-dir>/skills/pmx-canvas[-testing]`,
+whichever agent layout the workspace uses) and compares/replaces whole trees —
+references, evals, and fixtures included — so a copy can no longer drift while
+its `SKILL.md` hash matches. It never creates a copy where none is installed
+and makes no assumptions about which agents you use.
+
+```bash
+pmx-canvas skills sync --yes     # Refresh every installed copy from the package
+pmx-canvas skills sync --check   # Report drift only (exit 1 when stale), change nothing
+```
+
+Replacing a tree is destructive, so the sync requires `--yes`; without it the
+command only reports drift (like `--check`) and hints at the flag. A directory
+whose `SKILL.md` identity doesn't match the bundled skill is skipped, never
+replaced.
+
+Run `skills sync --yes` (and `copilot install-extension --yes` if the repo uses the
+Copilot adapter) after every `pmx-canvas` upgrade so agents operate on the
+released guidance.
+
 ## WebView automation
 
 Drive a headless Bun.WebView (Chromium or WebKit) pointed at the workbench:

package/docs/environment.md

@@ -25,8 +25,9 @@ optional; defaults are listed.
 
 | Variable | Read by | Effect |
 |---|---|---|
-| `PMX_CANVAS_THEME` | server | Startup theme: `dark` (default), `light`, `high-contrast`, `midnight`, `sepia`, `arctic`, `ember`, `forest`. |
-| `AMP_ORB` | server | Set by Amp orb services. When present, the served canvas page tells the browser it is running in an orb, which skips the iframe embed probe and forces `srcdoc` surface rendering when embedded (the orb portal blocks `src`-URL child iframes and the probe is unreliable there). |
+| `PMX_CANVAS_THEME` | server | Startup theme: `dark` (default), `light`, `high-contrast`, `midnight`, `sepia`, `arctic`, `ember`, `forest`, `volt`. |
+| `AMP_ORB` | server | Set by Amp orb services. When present, the served canvas page tells the browser it is running in an orb, which skips the iframe embed probe, forces `srcdoc` surface rendering when embedded (the orb portal blocks `src`-URL child iframes and the probe is unreliable there), and defaults the event transport to polling instead of SSE (the portal proxy buffers streams; `?transport=sse` overrides for diagnosis). |
+| `PORT` | server | Portal-assigned service port, honored ONLY when `AMP_ORB` is also set (Amp orbs) — after `--port`, `PMX_WEB_CANVAS_PORT`, and `PMX_CANVAS_PORT`, before the 4313 default. A stray `PORT` in normal shells never changes the port. |
 | `PMX_CANVAS_DISABLE_BROWSER_OPEN` | server | `1` suppresses auto-opening the browser (used by tests/CI). |
 | `PMX_CANVAS_DIST` | server | Explicit client bundle directory to serve instead of the packaged `dist/canvas`. |
 | `PMX_CANVAS_WEBVIEW_TIMEOUT_MS` | server | Startup timeout for the Bun.WebView automation session. |

package/docs/http-api.md

@@ -341,9 +341,12 @@ Responses are `{ ok, transport: "poll", snapshot, seq, events }` — poll again
 with `since=<seq>` every couple of seconds. A `since` from a previous server
 run or one that fell off the bounded event ring recovers with a fresh
 snapshot. The browser client uses this automatically: if the SSE stream
-produces no event within 3 seconds of connecting, it switches to polling.
-Force a transport with `/workbench?transport=poll` (or `transport=sse` to
-disable the fallback).
+produces no event within 3 seconds of connecting, it switches to polling (and
+tells the boot screen to wait for the fallback instead of alarming). Pages
+served by an Amp orb (`AMP_ORB` set — the same stamp that drives srcdoc mode)
+skip SSE entirely and default straight to polling. Force a transport with
+`/workbench?transport=poll` (or `transport=sse` to disable the fallback /
+override the orb default).
 
 ## Session theme override (host-default theming)
 

package/docs/plans/plan-009-tech-debt-backlog.md

@@ -66,7 +66,7 @@ The remaining items were re-analyzed with pros/cons and tiered; the maintainer a
 |---|---|
 | Windows web-artifacts | The artifact build pipeline is bash-script-backed (POSIX-only); `tests/unit/web-artifacts.test.ts` self-skips on win32 and docs now state the boundary. Decide: port the build scripts to a cross-platform runner, or keep the documented "build on POSIX, render anywhere" stance. |
 | Composite parity no longer machine-checked | Since v0.3.0 removed the legacy standalones, the byte-identical composite-vs-legacy guarantee has no head-to-head test — regressions in `buildInput`/`formatResult` reuse surface only via output-shape assertions. Accepted at review; revisit if a composite drifts. |
-| Portal-layer ext-app mount (contingency) | If the maintainer sets the WebKit UX bar at "never any visible gap", inline ext-app iframes must render outside the world transform — an architectural change that reopens the parked M3. 0.4.1 shipped the cheaper mimic (post-settle WebKit repaint nudge, `repaint-nudge` trail event) and the 0.4.1 Copilot report confirms the nudge RUNS but residual black tiles still appear (Diamond on first-load settle, Ellipse after restart settle) — the contingency's trigger condition is now met. This portal-layer mount is the designated next Finding N step; scope it as its own project (drag/zoom sync, z-order, clipping, minimap interplay), not a patch-release bolt-on. |
+| Portal-layer ext-app mount (contingency) | If the maintainer sets the WebKit UX bar at "never any visible gap", inline ext-app iframes must render outside the world transform — an architectural change that reopens the parked M3. 0.4.1 shipped the cheaper mimic (post-settle WebKit repaint nudge, `repaint-nudge` trail event) and the 0.4.1 Copilot report confirms the nudge RUNS but residual black tiles still appear (Diamond on first-load settle, Ellipse after restart settle) — the contingency's trigger condition is now met. 0.4.3 Codex hardens the evidence: three ready tiles blank in WebKit with **byte-identical** early/late screenshots while the recovery trail reported initialized/settled — DOM-level recovery completion does not prove compositor paint, so no DOM-side nudge can close this. This portal-layer mount is the designated next Finding N step; scope it as its own project (drag/zoom sync, z-order, clipping, minimap interplay), not a patch-release bolt-on. |
 
 ## Added post-0.4.0 (2026-08-04 report cycle)
 
@@ -75,6 +75,7 @@ The remaining items were re-analyzed with pros/cons and tiered; the maintainer a
 | Finding S — frame documents vs server restart | **Done + field-confirmed (0.4.1 reports, both hosts):** the browser revalidates minted frame-document URLs on every reconnect epoch (`workbenchConnectionEpoch`, HEAD probe) and re-mints against the new process when the store is gone; `/api/canvas/frame-documents/:id` answers HEAD. Copilot: IDs fully rotated, all post-restart 200, no frame-not-found tiles. Codex: re-mint without workbench reload. Server-side persistence deliberately NOT done — frames are client-derived and re-mintable. |
 | Amp portal nested-iframe embedding | **Done (2026-08-04):** boot-time embed probe (`/api/canvas/iframe-probe`) + fetch()+srcdoc fallback for all same-origin surfaces (`useSurfaceFrame`, `useIframeDocument` srcdoc short-circuit), `?iframe-mode` override, e2e-forced-mode coverage. External (cross-origin) app URLs cannot be inlined — documented limitation. |
 | Copilot adapter `canvas_snapshot list` descriptor lag | Host-side cached tool schema still requires `name`; fresh `--mcp` is correct. Adapter/packaging issue, not a daemon defect — nothing to change in core; 0.4.2 cycle saw the legacy tools gone from the host list after refresh. |
-| Finding T — theme/More menu mis-anchored | **Done (2026-08-05):** menus moved inside `.toolbar-menu-anchor` wrappers around their triggers (the group-level `position:relative` + `right:0` anchored them ~212px right of the button, both hosts). Anchor-geometry e2e regression tests added. |
-| Finding U — sticky `-32001` session-error banner over rendering content | **Mitigated (2026-08-05), root cause open:** when an ext-app session errors but the cached document still renders, the banner is now a soft degraded-interactivity notice instead of a red alarm. The underlying stressed-reconnect MCP timeout (long-lived tiles through theme churn + daemon respawn) is not clean-reproducible — investigate session re-establishment retry/backoff if the next cycle still hits it. |
+| Finding T — theme/More menu mis-anchored | **Done + field-confirmed (0.4.3 reports, both hosts):** menus moved inside `.toolbar-menu-anchor` wrappers around their triggers. Copilot measured button/menu right edges equal; Codex measured delta 0. Anchor-geometry e2e regression tests in place. |
+| Finding U — sticky `-32001` session-error banner over rendering content | **Presentation fix field-confirmed (0.4.3 reports, both hosts); root cause open:** forced error state renders the soft saved-content notice. The underlying stressed-reconnect MCP timeout is still not clean-reproducible — investigate session re-establishment retry/backoff if a future cycle reproduces it. |
+| Skill-mirror drift automation | **Done (2026-08-05):** `pmx-canvas skills sync` (+ `--check`, exit 1 on drift) discovers the skill copies already installed in the workspace — no assumed host layout, per maintainer direction — and whole-tree-replaces them from the package. Closes the recurring every-cycle hand-sync complaint in the audit addenda. Remaining audit ask: a true model-vs-baseline benchmark of the 17 eval prompts (a test-harness task, not a repo artifact). |
 | Registry-migration dead-code sweep | **Done (2026-08-03):** removed the orphaned `describeOp`/`describeGateOp` (composites.ts, dead since the v0.3.0 registration filter) and the `compactNodePayload`/`compactLayoutPayload`/`wantsFullPayload` duplicates in `mcp/server.ts` (live copies are in `ops/nodes.ts`). |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "Spatial canvas workbench for coding agents \u2014 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

@@ -18,6 +18,14 @@ Humans curate agent context by pinning nodes; agents read that curation through
 
 ## Required Operating Sequence
 
+0. **After a `pmx-canvas` upgrade, refresh this skill first.** Run
+   `pmx-canvas skills sync --yes` (`--check` to detect drift; exit 1 when stale) — it finds the skill
+   copies already installed in the workspace (whatever layout your agent uses) and replaces the
+   complete trees from the package, references/evals/fixtures included. Sync ONLY from the
+   installed package, never from a source checkout: this skill documents the runtime it ships
+   with, and a newer repo skill paired with an older installed runtime advertises commands and
+   themes the binary does not have (0.4.3 report skew finding). Also restart the HTTP daemon and
+   any `--mcp` processes; Bun does not hot-reload a running process.
 1. **Open or focus the workbench before mutating.** Reuse one visible canvas surface for the
    session.
 2. **Verify workspace identity.** Read `GET /health` or `pmx-canvas serve status`; the returned
@@ -36,6 +44,11 @@ Humans curate agent context by pinning nodes; agents read that curation through
    human watches intent form and can veto mid-thought. Skip it only for trivial in-place tweaks or
    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.
+   Since 0.4.5, an agent mutation WITHOUT a signal still shows a server-synthesized **auto-ghost**
+   (rendered lighter — dimmer, dotted, no veto — and settled instantly). That is a visibility
+   floor, not a replacement: only an explicit signal gives the human a real pre-mutation veto
+   window, your reasoning (`reason`), and staged multi-step previews. Batch and browser-human
+   actions never auto-ghost.
 6. **Mutate through current composites.** Prefer the 16 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" }`.
@@ -175,8 +188,8 @@ Use the visible workbench when the human is actively curating layout:
 - Drop files or URLs to create matching nodes.
 - Double-click markdown to edit inline.
 - Use toolbar snapshots before experiments and restore only after confirmation.
-- The toolbar carries view controls (fit, reset, zoom), arrange, minimap, a theme picker (eight
-  themes: dark, light, high-contrast, midnight, sepia, arctic, ember, forest), snapshots, trace,
+- The toolbar carries view controls (fit, reset, zoom), arrange, minimap, a theme picker (nine
+  themes: dark, light, high-contrast, midnight, sepia, arctic, ember, forest, volt), snapshots, trace,
   the annotation tools, search (Cmd+K), and shortcuts. On narrow viewports (≤900px — most
   embedded host panes and mobile) the secondary controls collapse into a single "⋯" More menu at
   the end of the bar; every action is still there as a labeled row, including the theme list. If
@@ -228,6 +241,10 @@ Prefer `canvas_query { action: "search" }` over parsing the full layout.
 - Hosted MCP-app/ext-app nodes such as Excalidraw require the in-canvas host bridge and are not
   standalone **Open as site** targets. URL-backed viewers and bundled web artifacts remain
   openable.
+- A standalone html surface (`/api/canvas/surface/:id` opened as a site) is a VISUAL view: it
+  renders the same content and theme, but `window.PMX_AX` is not injected without the canvas
+  iframe's per-mount nonce, so AX buttons only work inside the in-canvas node (0.4.4 Codex note).
+  Do not tell a user a standalone tab's controls will steer the agent.
 - A hosted ext-app (Excalidraw) node that is already on the board when a **WebKit** host panel
   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
@@ -264,9 +281,12 @@ Prefer `canvas_query { action: "search" }` over parsing the full layout.
   iframe) can block child iframes from loading ANY `src` URL, breaking every iframe-backed node
   with a gray placeholder. The canvas probes this at boot and auto-falls back to fetching
   same-origin surfaces and rendering them inline via `srcdoc` (HTML, graph, json-render, frame
-  documents). In Amp orbs specifically, the server sees `AMP_ORB` in its environment and stamps
-  the page so the embedded client skips the (there-unreliable) probe and goes straight to
-  `srcdoc`; HTML surfaces also inline their theme stylesheet so they render styled. External app
+  documents). In Amp orbs specifically, the server sees `AMP_ORB` in its environment and adapts
+  end to end: it binds the portal-assigned `$PORT` automatically (no port flag in the service
+  command), stamps the page so the embedded client skips the (there-unreliable) probe, goes
+  straight to `srcdoc`, AND defaults to the polling transport (the portal proxy buffers SSE —
+  waiting out the watchdog could trip the boot modal); HTML surfaces also inline their theme
+  stylesheet so they render styled. External app
   URLs cannot be inlined (cross-origin) and may stay blocked in such hosts. Force a mode with
   `/workbench?iframe-mode=srcdoc` (or `iframe-mode=src`) when diagnosing.
 - Graph and json-render standalone surfaces use `display=site` and fill the browser viewport, and

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

@@ -132,7 +132,7 @@ pmx-canvas --theme=light       # Light theme
 pmx-canvas --version           # Print installed version and exit
 ```
 
-`--theme` accepts `dark` (default), `light`, `high-contrast`, `midnight`, `sepia`, `arctic`, `ember`, or `forest` (0.4.x; the browser toolbar has a matching theme picker). Same value can be set via
+`--theme` accepts `dark` (default), `light`, `high-contrast`, `midnight`, `sepia`, `arctic`, `ember`, `forest`, or `volt` (0.4.x; the browser toolbar has a matching theme picker). Same value can be set via
 the `PMX_CANVAS_THEME` environment variable, or toggled live in the browser toolbar.
 
 Start the canvas once per session, then reuse it. Use `--no-open` when running as an agent — the