pmx-canvas 0.2.0 → 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/ax-state-manager.d.ts

@@ -245,6 +245,17 @@ export declare class AxStateManager {
         consumer?: string;
         limit?: number;
     }): PmxAxSteeringMessage[];
+    /**
+     * NEWEST undelivered steering first, for the compact AX context lead block (report
+     * #57) — so a fresh steer is visible even behind a long backlog. Loop-safe like
+     * getPendingSteering, but ordered DESC instead of the FIFO ASC delivery queue.
+     */
+    getPendingSteeringForContext(options?: {
+        consumer?: string;
+        limit?: number;
+    }): PmxAxSteeringMessage[];
+    /** Total undelivered steering for a consumer (loop-safe), for the context backlog counts. */
+    getPendingSteeringCount(consumer?: string): number;
     getAxTimelineSummary(): PmxAxTimelineSummary;
     getAxTimeline(q?: AxTimelineQuery): {
         events: PmxAxEvent[];

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

@@ -145,6 +145,8 @@ export interface PendingAxActivityItem {
 }
 export interface PmxAxDeliveryContext {
     pendingSteering: PmxAxSteeringMessage[];
+    totalPending: number;
+    omittedPending: number;
     pendingActivity: PendingAxActivityItem[];
 }
 export interface PmxAxContext {

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

@@ -53,6 +53,19 @@ export declare function loadPendingAxSteeringFromDB(db: Database, options?: {
     consumer?: string;
     limit?: number;
 }): PmxAxSteeringMessage[];
+/**
+ * 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.
+ * Distinct from loadPendingAxSteeringFromDB (FIFO oldest-first) which the claim/ack
+ * delivery queue uses for ordered processing.
+ */
+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). */
+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;
 export declare function loadAxHostCapabilityFromDB(db: Database): PmxAxHostCapability | null;

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

@@ -431,6 +431,11 @@ declare class CanvasStateManager {
         consumer?: string;
         limit?: number;
     }): PmxAxSteeringMessage[];
+    getPendingSteeringForContext(options?: {
+        consumer?: string;
+        limit?: number;
+    }): PmxAxSteeringMessage[];
+    getPendingSteeringCount(consumer?: string): number;
     getAxTimelineSummary(): PmxAxTimelineSummary;
     getAxTimeline(q?: AxTimelineQuery): {
         events: PmxAxEvent[];

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/ax-host-adapter-contract.md

@@ -42,7 +42,25 @@ message; it does **not** wake the agent. It reaches the next turn only when:
 
 The `delivery` lead block (`GET /api/canvas/ax/context?consumer=<id>`) is the
 robustness hedge: it's compact and sits above the full dump, so an adapter can inject
-it un-truncated even on a busy board where the full context is clipped.
+it un-truncated even on a busy board where the full context is clipped. Its
+`pendingSteering` is **newest-first** (most recent at index 0), capped at 10, so a
+*fresh* steer is always visible even behind a long backlog of old unacked steers
+(report #57); `delivery.totalPending` / `delivery.omittedPending` tell the agent how
+many more are queued so it can drain the FIFO `…/delivery/pending` endpoint when the
+count is non-zero. **Adapters should read `delivery.pendingSteering`** (this compact,
+count-bearing block), not `timeline.pendingSteering`.
+
+### Canvas-origin steering does not wake the agent by itself (#59)
+
+Recording a browser-origin `ax.steer` (and the `ok:true` ack a surface button gets —
+report #55) means the steer is **queued on the timeline**, not delivered into a live
+agent turn. PMX deliberately does not import a host SDK, so the *wake* — turning a
+queued steer into a visible turn — is **adapter-owned**: a cooperating host adapter
+must drain `…/delivery/pending?consumer=<id>` and call its native send (e.g.
+`copilotSession.send`), then `…/delivery/<id>/mark` it. Until an adapter wires that,
+canvas-origin steering is delivered on the next human turn, not pushed. A steering
+surface should therefore label its button honestly ("queued for the agent's next
+turn"), never imply it interrupts the agent now.
 
 ## The two primitives that close the loop
 

package/docs/http-api.md

@@ -246,6 +246,10 @@ curl "http://localhost:4313/api/canvas/ax/mode/<id>?waitMs=30000"
 
 # Context — optional ?consumer= filters the compact, loop-safe `delivery` lead block
 # (undelivered steering + open work/approvals it can act on) for per-turn injection.
+# `delivery.pendingSteering` is NEWEST-first (most recent first), capped at 10, so a
+# fresh steer is visible even behind a backlog; `delivery.totalPending` /
+# `delivery.omittedPending` report how many more are queued. Drain the full FIFO
+# (oldest-first) backlog via /api/canvas/ax/delivery/pending when omittedPending > 0.
 curl "http://localhost:4313/api/canvas/ax/context?consumer=copilot"
 
 # Commands — list the registry, invoke a command (records a `command` agent-event)

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:
@@ -157,7 +176,7 @@ Individual bundled skills are also readable at `canvas://skills/<name>`.
 |----------|-------------|
 | `canvas://pinned-context` | Content of pinned nodes + nearby unpinned neighbors |
 | `canvas://ax` | PMX AX state: focus, work items, approval gates, review annotations |
-| `canvas://ax-context` | Agent-readable pinned and focused AX context, plus timeline summary and host capability |
+| `canvas://ax-context` | Agent-readable pinned and focused AX context, plus a compact `delivery` lead block (`pendingSteering` newest-first + `totalPending`/`omittedPending` counts), timeline summary, and host capability |
 | `canvas://ax-work` | Canvas-bound AX work: work items, approval gates, review annotations, elicitations, mode requests, and tool/prompt policy |
 | `canvas://ax-timeline` | Bounded AX timeline: recent agent-events, evidence, and steering messages |
 | `canvas://ax-pending-steering` | Undelivered steering an adapterless MCP client can claim, act on, and mark delivered |

package/package.json

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