pmx-canvas 0.2.1 → 0.2.2

package/dist/types/client/canvas/IntentLayer.d.ts

@@ -0,0 +1 @@
+export declare function IntentLayer(): import("preact/src").JSX.Element | null;

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

@@ -2,6 +2,16 @@
 export declare function sendIntent(type: string, payload?: Record<string, unknown>): Promise<{
     ok: boolean;
 }>;
+/**
+ * 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 declare function vetoGhostIntent(intent: {
+    id: string;
+    kind: string;
+    label?: string;
+    reason?: string;
+}): Promise<boolean>;
 /** Fetch rendered markdown HTML from the server. */
 export declare function renderMarkdown(markdown: string): Promise<string>;
 /** Fetch file content from the server. */

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

@@ -0,0 +1,25 @@
+import type { PmxAxIntent } from '../../shared/ax-intent.js';
+/**
+ * Client-side store for the Ghost Cursor of Intent. Ghosts are ephemeral
+ * presence pushed over SSE (`ax-intent` / `ax-intent-clear`); this store mirrors
+ * them into a signal the IntentLayer renders, tracks a short exit phase so
+ * settle/dissolve can animate, and prunes anything the server's TTL frame did
+ * not reach (SSE backstop). Nothing here is ever persisted.
+ */
+export type IntentPhase = 'forming' | 'settling' | 'dissolving';
+export interface ClientIntent extends PmxAxIntent {
+    phase: IntentPhase;
+    /** The real node a settled intent became — seeds the settle morph. */
+    settledNodeId?: string;
+}
+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>;
+/** 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;
+/** Resolve a ghost into a real node — the settle morph, then removal. */
+export declare function settleIntent(id: string, settledNodeId?: string): void;
+/** Dissolve a ghost (expired / vetoed / evicted / abandoned), then remove it. */
+export declare function dissolveIntent(id: string): void;
+export declare function resetIntents(): void;

package/dist/types/json-render/server.d.ts

@@ -88,7 +88,7 @@ export declare function buildJsonRenderViewerHtml(options: {
     title: string;
     spec: JsonRenderSpec;
     theme?: 'dark' | 'light' | 'high-contrast';
-    display?: 'expanded';
+    display?: 'expanded' | 'site';
     devtools?: boolean;
     nodeId?: string;
     axToken?: string;

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

@@ -2,6 +2,7 @@ import { EventEmitter } from 'node:events';
 import { canvasState } from './canvas-state.js';
 import type { CanvasAnnotation, CanvasNodeState, CanvasEdge, CanvasLayout } from './canvas-state.js';
 import { type AxInteractionInput, type AxInteractionPublicResult } from './ax-interaction.js';
+import type { PmxAxIntent } from '../shared/ax-intent.js';
 import type { PmxAxActivityKind, PmxAxApprovalGate, PmxAxCommandDescriptor, PmxAxContext, PmxAxElicitation, PmxAxEvent, PmxAxEvidence, PmxAxEvidenceKind, PmxAxFocusState, PmxAxHostCapability, PmxAxMode, PmxAxModeRequest, PmxAxPolicy, PmxAxReviewAnchorType, PmxAxReviewAnnotation, PmxAxReviewKind, PmxAxReviewRegion, PmxAxReviewSeverity, PmxAxReviewStatus, PmxAxSource, PmxAxState, PmxAxSteeringMessage, PmxAxWorkItem, PmxAxWorkItemStatus } from './ax-state.js';
 import type { AxTimelineQuery } from './canvas-db.js';
 import { searchNodes } from './spatial-analysis.js';
@@ -30,6 +31,7 @@ export declare class PmxCanvas extends EventEmitter {
     constructor(options?: {
         port?: number;
     });
+    private runIntentCommit;
     start(options?: {
         open?: boolean;
         automationWebView?: boolean | CanvasAutomationWebViewOptions;
@@ -47,6 +49,7 @@ export declare class PmxCanvas extends EventEmitter {
      * or keep the whole node — both work. (Previously returned a bare id string.)
      */
     addNode(input: {
+        intentId?: string;
         type: CanvasNodeState['type'];
         title?: string;
         content?: string;
@@ -67,6 +70,7 @@ export declare class PmxCanvas extends EventEmitter {
         strictSize?: boolean;
     }): SdkCanvasNode;
     addWebpageNode(input: {
+        intentId?: string;
         title?: string;
         url: string;
         x?: number;
@@ -90,8 +94,11 @@ export declare class PmxCanvas extends EventEmitter {
     }>;
     updateNode(id: string, patch: Partial<CanvasNodeState> & Record<string, unknown>): void;
     /** Remove a node. Missing id throws (plan-005 unifies this across surfaces). */
-    removeNode(id: string): void;
+    removeNode(id: string, options?: {
+        intentId?: string;
+    }): void;
     addEdge(input: {
+        intentId?: string;
         from?: string;
         to?: string;
         fromSearch?: string;
@@ -112,6 +119,7 @@ export declare class PmxCanvas extends EventEmitter {
      * If childIds are provided, the group auto-sizes to contain them with padding.
      */
     createGroup(input: {
+        intentId?: string;
         title?: string;
         childIds?: string[];
         x?: number;
@@ -124,9 +132,12 @@ export declare class PmxCanvas extends EventEmitter {
     /** Add nodes to an existing group. */
     groupNodes(groupId: string, childIds: string[], options?: {
         childLayout?: 'grid' | 'column' | 'flow';
+        intentId?: string;
     }): boolean;
     /** Remove all children from a group (the group node remains). */
-    ungroupNodes(groupId: string): boolean;
+    ungroupNodes(groupId: string, options?: {
+        intentId?: string;
+    }): boolean;
     clear(): void;
     arrange(layout?: 'grid' | 'column' | 'flow'): void;
     focusNode(id: string, options?: {
@@ -155,6 +166,18 @@ export declare class PmxCanvas extends EventEmitter {
         source?: PmxAxSource;
     }): PmxAxSteeringMessage;
     markSteeringDelivered(id: string): boolean;
+    /**
+     * Ghost Cursor of Intent — announce a spatial move before making it. The ghost
+     * is ephemeral presence (auto-expiring, never snapshotted); the registry emits
+     * the `ax-intent` SSE frame so the browser paints a pre-commit placeholder.
+     */
+    signalIntent(input: Record<string, unknown>): PmxAxIntent;
+    updateIntent(id: string, patch: Record<string, unknown>): PmxAxIntent;
+    /** Dissolve a ghost; pass `settledNodeId` once the real node has landed. */
+    clearIntent(id: string, options?: {
+        settledNodeId?: string;
+        vetoed?: boolean;
+    }): boolean;
     /** Undelivered steering for a consumer (loop-safe; excludes consumer-originated). */
     getPendingSteering(options?: {
         consumer?: string;
@@ -440,7 +463,9 @@ export declare class PmxCanvas extends EventEmitter {
         timeoutMs?: number;
     }): Promise<OpenMcpAppCoreResult>;
     addDiagram(input: DiagramPresetOpenInput): Promise<OpenMcpAppCoreResult>;
-    addJsonRenderNode(input: JsonRenderNodeInput): {
+    addJsonRenderNode(input: JsonRenderNodeInput & {
+        intentId?: string;
+    }): {
         id: string;
         url: string;
         spec: JsonRenderSpec;
@@ -452,6 +477,7 @@ export declare class PmxCanvas extends EventEmitter {
      * reloads the viewer as the specVersion bumps.
      */
     streamJsonRenderNode(input: {
+        intentId?: string;
         nodeId?: string;
         title?: string;
         patches?: unknown[];
@@ -471,6 +497,7 @@ export declare class PmxCanvas extends EventEmitter {
         streamStatus: 'open' | 'closed';
     };
     addHtmlNode(input: {
+        intentId?: string;
         html: string;
         title?: string;
         summary?: string;
@@ -493,6 +520,7 @@ export declare class PmxCanvas extends EventEmitter {
         };
     }): SdkCanvasNode;
     addHtmlPrimitive(input: {
+        intentId?: string;
         kind: HtmlPrimitiveKind;
         title?: string;
         data?: Record<string, unknown>;
@@ -507,7 +535,9 @@ export declare class PmxCanvas extends EventEmitter {
         title: string;
         htmlBytes: number;
     };
-    addGraphNode(input: GraphNodeInput): {
+    addGraphNode(input: GraphNodeInput & {
+        intentId?: string;
+    }): {
         id: string;
         url: string;
         spec: JsonRenderSpec;

package/dist/types/server/intent-registry.d.ts

@@ -0,0 +1,45 @@
+import { type PmxAxIntent, type PmxAxIntentKind } from '../shared/ax-intent.js';
+type IntentEmitter = (event: string, payload: Record<string, unknown>) => void;
+export declare class IntentRegistry {
+    private readonly intents;
+    private readonly vetoedIntentIds;
+    private readonly committingIntentIds;
+    private emit;
+    private sweepTimer;
+    /** Inject the workbench SSE emitter (server.ts wires this at module load). */
+    setEmitter(emitter: IntentEmitter | null): void;
+    list(): PmxAxIntent[];
+    /** Signal a new (or replace an existing) intent. Returns the stored envelope. */
+    signal(raw: unknown): PmxAxIntent;
+    /** Patch a live intent (position/label/reason/confidence/seq) and bump its TTL. */
+    update(id: string, raw: unknown): PmxAxIntent;
+    /**
+     * Clear an intent. `settledNodeId` resolves it INTO a real node (the settle
+     * morph); `vetoed` marks a human pre-emptive veto. Either way the ghost
+     * dissolves. Returns true when an intent was actually removed.
+     */
+    clear(id: string, opts?: {
+        settledNodeId?: string;
+        vetoed?: boolean;
+    }): boolean;
+    /**
+     * Gate one real mutation behind a live, non-vetoed intent. The claim is
+     * synchronous: once this method has accepted the intent, a later veto cannot
+     * race in between the check and the mutation.
+     */
+    beginCommit(id: string, allowedKinds: readonly PmxAxIntentKind[]): PmxAxIntent;
+    completeCommit(id: string, settledNodeId?: string): void;
+    abortCommit(id: string): void;
+    runCommit<T>(id: string, allowedKinds: readonly PmxAxIntentKind[], mutate: () => T | Promise<T>, settledNodeId: (result: T, intent: PmxAxIntent) => string | undefined): Promise<T>;
+    /** Drop every live intent without per-id SSE (used on hard resets). */
+    reset(): void;
+    private rememberVeto;
+    private pruneVetoTombstones;
+    private evictOverflow;
+    private sweep;
+    private ensureSweeper;
+    private maybeStopSweeper;
+}
+/** Process-wide singleton, shared across HTTP handlers, MCP ops, and the SDK. */
+export declare const intentRegistry: IntentRegistry;
+export {};

package/dist/types/server/operations/ops/intent.d.ts

@@ -0,0 +1,2 @@
+import { type Operation } from '../types.js';
+export declare const intentOperations: Operation[];

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

@@ -0,0 +1,58 @@
+/**
+ * Ghost Cursor of Intent — the shared pre-commit "intent" envelope.
+ *
+ * An intent is EPHEMERAL PRESENCE, not canvas state: it describes a move the
+ * agent is ABOUT to make (create / move / connect / remove / edit) so the canvas
+ * can paint a faint placeholder before the real mutation lands. Like a
+ * multiplayer cursor, it auto-expires, is count-capped, and never enters
+ * `canvas_get_layout`, `state.json`, or snapshots.
+ *
+ * This module is import-shared by the server (IntentRegistry + the intent ops)
+ * and the client (intent-store + IntentLayer); it must stay free of any
+ * server-only or client-only imports.
+ */
+export type PmxAxIntentKind = 'create' | 'move' | 'connect' | 'remove' | 'edit';
+export type PmxAxIntentEdgeType = 'relation' | 'depends-on' | 'flow' | 'references';
+export interface PmxAxIntentEdge {
+    from: string;
+    to: string;
+    type: PmxAxIntentEdgeType;
+}
+export interface PmxAxIntent {
+    /** Stable id → update / clear / veto. Auto-generated when a signal omits it. */
+    id: string;
+    kind: PmxAxIntentKind;
+    /** create: where the new node forms. move: the destination. */
+    position?: {
+        x: number;
+        y: number;
+    };
+    /** move / edit / remove: the existing node the intent targets. */
+    nodeId?: string;
+    /** connect: the edge about to be drawn. */
+    edge?: PmxAxIntentEdge;
+    /** Node type the ghost renders (icon + type badge). Defaults to a neutral box. */
+    nodeType?: string;
+    /** Short action label shown on the ghost chip ("Add evidence"). */
+    label?: string;
+    /** WHY — shown beneath the ghost. The legibility payoff. */
+    reason?: string;
+    /** 0..1 → ghost opacity/solidity. */
+    confidence?: number;
+    /** Ordering hint for staged-batch ghosts (the numbered previsualization rail). */
+    seq?: number;
+    /** Source label of the surface that signalled the intent (mcp/api/sdk/...). */
+    source?: string;
+    /** Epoch ms when the intent was first signalled. */
+    createdAt: number;
+    /** Epoch ms when the intent auto-dissolves if not settled/cleared first. */
+    expiresAt: number;
+}
+export declare const INTENT_KINDS: PmxAxIntentKind[];
+export declare const INTENT_EDGE_TYPES: PmxAxIntentEdgeType[];
+/** Default lifetime of an unsettled ghost. */
+export declare const DEFAULT_INTENT_TTL_MS = 8000;
+/** Hard ceiling on TTL so a stuck ghost can never linger. */
+export declare const MAX_INTENT_TTL_MS = 60000;
+/** Live-intent cap — oldest is evicted past this (presence, not a queue). */
+export declare const MAX_LIVE_INTENTS = 12;

package/docs/mcp.md

@@ -1,11 +1,11 @@
 # MCP reference
 
-PMX Canvas ships an MCP stdio server with **83 tools** + **14 core resources**,
+PMX Canvas ships an MCP stdio server with **84 tools** + **14 core resources**,
 plus per-skill resources at `canvas://skills/<name>`. The server emits
 `notifications/resources/updated` when canvas state changes — humans pin
 nodes in the browser, agents are notified immediately.
 
-> **Consolidation in progress (plan-006/008).** The 83 tools are 14 action-discriminated
+> **Consolidation in progress (plan-006/008).** The 84 tools are 15 action-discriminated
 > **composites** (recommended — see below) plus 69 legacy single-purpose tools.
 > The composites fold the legacy tools behind an `action` (and, for `canvas_ax_gate`,
 > a `kind`) enum; each action dispatches to the same operation, so behavior is
@@ -51,6 +51,25 @@ its `action` to the same operation the legacy tool used, so results are identica
 | `canvas_ax_gate` | `request` · `resolve` · `await` × kind `approval` \| `elicitation` \| `mode` | `canvas_request_approval`, `canvas_resolve_approval`, `canvas_await_approval`, `canvas_request_elicitation`, `canvas_respond_elicitation`, `canvas_await_elicitation`, `canvas_request_mode`, `canvas_resolve_mode`, `canvas_await_mode` (9 → 1) |
 | `canvas_ax_timeline` | `read` · `record-event` · `add-evidence` · `send-steering` | `canvas_get_ax_timeline`, `canvas_record_ax_event`, `canvas_add_evidence`, `canvas_send_steering` |
 | `canvas_ax_delivery` | `claim` · `mark` | `canvas_claim_ax_delivery`, `canvas_mark_ax_delivery` |
+| `canvas_intent` | `signal` · `update` · `clear` | _(new — Ghost Cursor of Intent; no legacy standalone tool)_ |
+
+### `canvas_intent` — Ghost Cursor of Intent
+
+Announce the spatial move you are **about** to make so the canvas paints a faint
+pre-commit placeholder (a "ghost"). The human sees the next move forming — and can
+veto it — before the mutation lands.
+
+- `signal` — register an intent: `kind` (`create` \| `move` \| `connect` \| `remove` \| `edit`) plus the anchor it renders against (`position` for create/move, `nodeId` for move/edit/remove, `edge` for connect). Optional `label`, `reason`, `confidence` (0..1 → ghost opacity), `seq` (staged-batch ordering), `ttlMs` (default ~8s), and a stable `id` to update/clear later.
+- `update` — patch a live intent by `id` (position/label/reason/confidence/ttlMs).
+- `clear` — abandon/dissolve it explicitly. Normal linked mutations settle automatically.
+
+Intents are **ephemeral presence**: never persisted, never snapshotted, never in
+`canvas_get_layout`, and auto-expiring. They ride their own SSE channel
+(`ax-intent` / `ax-intent-clear`) and replay to reconnecting browsers while still
+live. Best practice — narrate your next move: `signal` → mutate with the returned
+`intent.id` as `intentId`. A vetoed or expired linked mutation is rejected, and a
+successful mutation settles the ghost automatically. Also reachable over HTTP:
+`POST/PATCH/DELETE /api/canvas/ax/intent[/:id]`.
 
 Field names match the underlying operation (e.g. `canvas_view { action: "focus", id }`,
 `canvas_group { action: "create", childIds }`). `canvas_ax_gate` has two discriminators:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "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",