pmx-canvas 0.1.29 → 0.1.31

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

@@ -1,11 +1,4 @@
 import type { CanvasNodeState } from '../types';
-export declare function createHtmlNodeSrcDocForTest(userHtml: string, options: {
-    theme: string;
-    themeCss: string;
-    themeToken?: string;
-    presentation?: boolean;
-    presentationExitToken?: string;
-}): string;
 export declare function shouldShowPresentationControls(node: CanvasNodeState): boolean;
 export declare function HtmlNode({ node, expanded, presentation, presentationExitToken, autoFocus, }: {
     node: CanvasNodeState;

package/dist/types/client/nodes/ax-node-actions.d.ts

@@ -0,0 +1,18 @@
+import type { CanvasNodeState } from '../types';
+/**
+ * Submit a native-node AX interaction (plan-004 Phase 2) and surface the outcome
+ * as a transient toast. Inline node controls call this; the server enforces the
+ * node's capabilities, so a denied interaction simply shows an error toast.
+ */
+export declare function runNodeAxInteraction(node: CanvasNodeState, type: string, payload: Record<string, unknown> | undefined, successTitle: string): Promise<void>;
+/** Shared style for the small inline AX action button on native nodes. */
+export declare const axNodeActionButtonStyle: {
+    readonly padding: "3px 8px";
+    readonly fontSize: "10px";
+    readonly background: "var(--c-accent-12)";
+    readonly border: "1px solid var(--c-accent-25)";
+    readonly borderRadius: "4px";
+    readonly color: "var(--c-text-soft)";
+    readonly cursor: "pointer";
+    readonly flexShrink: 0;
+};

package/dist/types/client/nodes/surface-url.d.ts

@@ -0,0 +1,22 @@
+import type { CanvasNodeState } from '../types';
+/**
+ * Stable content hash (djb2) used to cache-bust the surface iframe `src` when a
+ * node's HTML changes. The server always serves current state, but a same `src`
+ * string won't reload the iframe on its own — bumping `?v=` does.
+ */
+export declare function surfaceContentHash(input: string): string;
+export interface SurfaceUrlOptions {
+    theme?: string;
+    themeToken?: string;
+    present?: boolean;
+    presentToken?: string;
+    v?: string;
+    /** Nonce authorizing iframe → parent AX emits (html bridge). */
+    axToken?: string;
+}
+/** Build the stable per-node surface URL (/api/canvas/surface/:id) the iframe and "Open as site" both use. */
+export declare function nodeSurfaceUrl(nodeId: string, opts?: SurfaceUrlOptions): string;
+/** Whether a node can be opened as a standalone site (shared with the server). */
+export declare function canOpenAsSite(node: CanvasNodeState): boolean;
+/** Open the node's surface in a new browser tab. */
+export declare function openNodeAsSite(node: CanvasNodeState): void;

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

@@ -1,3 +1,6 @@
 import { type SseMessage } from '../../shared/semantic-attention.js';
+import { type AttentionTone } from './attention-store';
+/** Show a transient toast from arbitrary client code (e.g. AX action feedback). */
+export declare function showToast(tone: AttentionTone, title: string, detail?: string, nodeIds?: string[]): void;
 export declare function resetAttentionBridge(): void;
 export declare function syncAttentionFromSse(message: SseMessage): void;

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

@@ -111,6 +111,23 @@ export declare function removeNodeFromClient(id: string): Promise<{
     ok: boolean;
     removed?: string;
 }>;
+export interface AxInteractionRequest {
+    type: string;
+    sourceNodeId: string;
+    payload?: Record<string, unknown>;
+    sourceSurface?: 'native-node' | 'json-render' | 'html-node' | 'mcp-app' | 'adapter';
+}
+export interface AxInteractionResponse {
+    ok: boolean;
+    type?: string;
+    sourceNodeId?: string;
+    primitive?: unknown;
+    status?: number;
+    code?: string;
+    error?: string;
+}
+/** Submit a capability-gated AX interaction from a native node control. */
+export declare function submitAxInteractionFromClient(input: AxInteractionRequest): Promise<AxInteractionResponse>;
 /** Commit the current viewport to the authoritative server state. */
 export declare function updateViewportFromClient(viewport: {
     x: number;

package/dist/types/json-render/renderer/index.d.ts

@@ -14,5 +14,7 @@ declare global {
         __PMX_CANVAS_JSON_RENDER_THEME__?: string;
         __PMX_CANVAS_JSON_RENDER_DISPLAY__?: string;
         __PMX_CANVAS_JSON_RENDER_DEVTOOLS__?: boolean;
+        __PMX_CANVAS_JSON_RENDER_NODE_ID__?: string;
+        __PMX_CANVAS_AX_TOKEN__?: string;
     }
 }

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

@@ -6,6 +6,7 @@ export declare const schema: import("@json-render/core").Schema<{
             props: import("@json-render/core").SchemaType<"propsOf", string>;
             children: import("@json-render/core").SchemaType<"array", import("@json-render/core").SchemaType<"string", unknown>>;
             visible: import("@json-render/core").SchemaType<"any", unknown>;
+            on: import("@json-render/core").SchemaType<"any", unknown>;
         }>>;
     }>;
     catalog: import("@json-render/core").SchemaType<"object", {
@@ -29,6 +30,7 @@ export declare const elementTreeSchema: import("@json-render/core").Schema<{
             props: import("@json-render/core").SchemaType<"propsOf", string>;
             children: import("@json-render/core").SchemaType<"array", import("@json-render/core").SchemaType<"string", unknown>>;
             visible: import("@json-render/core").SchemaType<"any", unknown>;
+            on: import("@json-render/core").SchemaType<"any", unknown>;
         }>>;
     }>;
     catalog: import("@json-render/core").SchemaType<"object", {

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

@@ -90,4 +90,6 @@ export declare function buildJsonRenderViewerHtml(options: {
     theme?: 'dark' | 'light' | 'high-contrast';
     display?: 'expanded';
     devtools?: boolean;
+    nodeId?: string;
+    axToken?: string;
 }): Promise<string>;

package/dist/types/mcp/canvas-access.d.ts

@@ -29,6 +29,22 @@ type SetAxFocusResult = ReturnType<PmxCanvas['setAxFocus']>;
 type RecordAxEventInput = Parameters<PmxCanvas['recordAxEvent']>[0];
 type RecordAxEventResult = ReturnType<PmxCanvas['recordAxEvent']>;
 type SendSteeringResult = ReturnType<PmxCanvas['sendSteering']>;
+type SubmitAxInteractionInput = Parameters<PmxCanvas['submitAxInteraction']>[0];
+type SubmitAxInteractionResult = ReturnType<PmxCanvas['submitAxInteraction']>;
+type GetPendingSteeringResult = ReturnType<PmxCanvas['getPendingSteering']>;
+type ListElicitationsResult = ReturnType<PmxCanvas['listElicitations']>;
+type RequestElicitationInput = Parameters<PmxCanvas['requestElicitation']>[0];
+type RequestElicitationResult = ReturnType<PmxCanvas['requestElicitation']>;
+type RespondElicitationResult = ReturnType<PmxCanvas['respondElicitation']>;
+type ListModeRequestsResult = ReturnType<PmxCanvas['listModeRequests']>;
+type RequestModeInput = Parameters<PmxCanvas['requestMode']>[0];
+type RequestModeResult = ReturnType<PmxCanvas['requestMode']>;
+type ResolveModeRequestResult = ReturnType<PmxCanvas['resolveModeRequest']>;
+type GetCommandRegistryResult = ReturnType<PmxCanvas['getCommandRegistry']>;
+type InvokeCommandResult = ReturnType<PmxCanvas['invokeCommand']>;
+type GetPolicyResult = ReturnType<PmxCanvas['getPolicy']>;
+type SetPolicyInput = Parameters<PmxCanvas['setPolicy']>[0];
+type SetPolicyResult = ReturnType<PmxCanvas['setPolicy']>;
 type GetAxTimelineQuery = Parameters<PmxCanvas['getAxTimeline']>[0];
 type GetAxTimelineResult = ReturnType<PmxCanvas['getAxTimeline']>;
 type AddWorkItemInput = Parameters<PmxCanvas['addWorkItem']>[0];
@@ -139,6 +155,37 @@ export interface CanvasAccess {
     reportHostCapability(input: unknown, options?: {
         source?: PmxAxSource;
     }): Promise<ReportHostCapabilityResult>;
+    submitAxInteraction(input: SubmitAxInteractionInput, options?: {
+        source?: PmxAxSource;
+    }): Promise<SubmitAxInteractionResult>;
+    getPendingSteering(options?: {
+        consumer?: string;
+        limit?: number;
+    }): Promise<GetPendingSteeringResult>;
+    markSteeringDelivered(id: string): Promise<boolean>;
+    listElicitations(): Promise<ListElicitationsResult>;
+    requestElicitation(input: RequestElicitationInput, options?: {
+        source?: PmxAxSource;
+    }): Promise<RequestElicitationResult>;
+    respondElicitation(id: string, response: Record<string, unknown>, options?: {
+        source?: PmxAxSource;
+    }): Promise<RespondElicitationResult>;
+    listModeRequests(): Promise<ListModeRequestsResult>;
+    requestMode(input: RequestModeInput, options?: {
+        source?: PmxAxSource;
+    }): Promise<RequestModeResult>;
+    resolveModeRequest(id: string, decision: 'approved' | 'rejected', options?: {
+        resolution?: string;
+        source?: PmxAxSource;
+    }): Promise<ResolveModeRequestResult>;
+    getCommandRegistry(): Promise<GetCommandRegistryResult>;
+    invokeCommand(name: string, args?: Record<string, unknown> | null, options?: {
+        source?: PmxAxSource;
+    }): Promise<InvokeCommandResult>;
+    getPolicy(): Promise<GetPolicyResult>;
+    setPolicy(patch: SetPolicyInput, options?: {
+        source?: PmxAxSource;
+    }): Promise<SetPolicyResult>;
     clear(): Promise<void>;
     search(query: string): Promise<SearchResult>;
     undo(): Promise<UndoRedoResult>;

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

@@ -0,0 +1,210 @@
+/**
+ * PMX-AX node interaction core (plan-004 Phase 1).
+ *
+ * One normalized envelope + capability model for node-originated AX interactions.
+ * Eligible nodes emit a validated `PmxAxInteraction`; this module checks the
+ * node's capabilities and payload, then maps the interaction onto the EXISTING
+ * AX operations (work items, evidence, approvals, review, focus, steering,
+ * events). It is host-agnostic and transport-agnostic — the same envelope backs
+ * native node events, json-render actions, the sandboxed HTML bridge, MCP apps,
+ * and host adapters (later phases).
+ *
+ * Decoupling: this module never imports the canvas-state singleton at runtime.
+ * The dispatcher takes the manager via dependency injection (structural
+ * `AxInteractionManager`), so it stays pure and unit-testable and introduces no
+ * import cycle (canvas-state → canvas-provenance must not pull this in).
+ */
+import { z } from 'zod';
+import type { CanvasNodeState } from './canvas-state.js';
+import type { CanvasNodeType } from './canvas-provenance.js';
+import type { PmxAxApprovalGate, PmxAxElicitation, PmxAxEvent, PmxAxEventKind, PmxAxEvidence, PmxAxEvidenceKind, PmxAxFocusState, PmxAxMode, PmxAxModeRequest, PmxAxReviewAnchorType, PmxAxReviewAnnotation, PmxAxReviewKind, PmxAxReviewRegion, PmxAxReviewSeverity, PmxAxSource, PmxAxSteeringMessage, PmxAxWorkItem, PmxAxWorkItemStatus } from './ax-state.js';
+export declare const AX_INTERACTION_TYPES: readonly ["ax.event.record", "ax.steer", "ax.work.create", "ax.work.update", "ax.evidence.add", "ax.approval.request", "ax.approval.resolve", "ax.review.add", "ax.focus.set", "ax.command.invoke", "ax.elicitation.request", "ax.mode.request"];
+export type AxInteractionType = (typeof AX_INTERACTION_TYPES)[number];
+export type AxDeliveryMode = 'record-only' | 'notify-agent' | 'send-to-agent';
+export interface NodeAxCapabilities {
+    enabled: boolean;
+    /** Interaction types this node may emit. Also the per-node override ceiling. */
+    allowed: AxInteractionType[];
+    /** Subset of `allowed` that should route through an approval gate (later phases). */
+    requiresApproval: AxInteractionType[];
+    delivery: AxDeliveryMode;
+}
+/**
+ * Server-side default (and per-node ceiling) capabilities per node type, from the
+ * plan's node capability matrix. `html`/`html-primitive`, `mcp-app`, and the
+ * internal `prompt`/`response` types default to disabled (opt-in / later phases);
+ * a node can anchor AX state but only eligible types may EMIT interactions.
+ */
+export declare const DEFAULT_NODE_AX_CAPABILITIES: Record<CanvasNodeType, NodeAxCapabilities>;
+/** Validate caller-supplied per-node `data.axCapabilities` into a partial override. */
+export declare function normalizeNodeAxCapabilities(value: unknown): Partial<NodeAxCapabilities> | null;
+/**
+ * Effective capabilities for a node: the type default merged with the node's own
+ * `data.axCapabilities`. A per-node override can toggle `enabled` and NARROW
+ * `allowed`, but never grant a type beyond the type's ceiling (security: a
+ * pasted/generated node cannot escalate itself).
+ */
+export declare function resolveNodeAxCapabilities(node: CanvasNodeState): NodeAxCapabilities;
+declare const InteractionEnvelopeSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        "ax.event.record": "ax.event.record";
+        "ax.steer": "ax.steer";
+        "ax.work.create": "ax.work.create";
+        "ax.work.update": "ax.work.update";
+        "ax.evidence.add": "ax.evidence.add";
+        "ax.approval.request": "ax.approval.request";
+        "ax.approval.resolve": "ax.approval.resolve";
+        "ax.review.add": "ax.review.add";
+        "ax.focus.set": "ax.focus.set";
+        "ax.command.invoke": "ax.command.invoke";
+        "ax.elicitation.request": "ax.elicitation.request";
+        "ax.mode.request": "ax.mode.request";
+    }>;
+    sourceNodeId: z.ZodString;
+    sourceSurface: z.ZodOptional<z.ZodEnum<{
+        "mcp-app": "mcp-app";
+        "json-render": "json-render";
+        "native-node": "native-node";
+        "html-node": "html-node";
+        adapter: "adapter";
+    }>>;
+    actor: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodEnum<{
+            agent: "agent";
+            system: "system";
+            human: "human";
+        }>;
+        id: z.ZodOptional<z.ZodString>;
+        displayName: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    payload: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    correlationId: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type PmxAxInteraction = z.infer<typeof InteractionEnvelopeSchema>;
+/** Caller-facing interaction input (payload optional; validated on apply). */
+export interface AxInteractionInput {
+    type: AxInteractionType;
+    sourceNodeId: string;
+    sourceSurface?: PmxAxInteraction['sourceSurface'];
+    actor?: PmxAxInteraction['actor'];
+    payload?: Record<string, unknown>;
+    correlationId?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Structural subset of CanvasStateManager that interaction dispatch needs.
+ * Injected so this module stays free of a runtime canvas-state import.
+ */
+export interface AxInteractionManager {
+    getNode(id: string): CanvasNodeState | undefined;
+    recordAxEvent(input: {
+        kind: PmxAxEventKind;
+        summary: string;
+        detail?: string | null;
+        nodeIds?: string[];
+        data?: Record<string, unknown> | null;
+    }, options?: {
+        source?: PmxAxSource;
+    }): PmxAxEvent;
+    recordSteeringMessage(message: string, options?: {
+        source?: PmxAxSource;
+    }): PmxAxSteeringMessage;
+    addWorkItem(input: {
+        title: string;
+        status?: PmxAxWorkItemStatus;
+        detail?: string | null;
+        nodeIds?: string[];
+    }, options?: {
+        source?: PmxAxSource;
+    }): PmxAxWorkItem;
+    updateWorkItem(id: string, patch: {
+        title?: string;
+        status?: PmxAxWorkItemStatus;
+        detail?: string | null;
+        nodeIds?: string[];
+    }, options?: {
+        source?: PmxAxSource;
+    }): PmxAxWorkItem | null;
+    addEvidence(input: {
+        kind: PmxAxEvidenceKind;
+        title: string;
+        body?: string | null;
+        ref?: string | null;
+        nodeIds?: string[];
+        data?: Record<string, unknown> | null;
+    }, options?: {
+        source?: PmxAxSource;
+    }): PmxAxEvidence;
+    requestApproval(input: {
+        title: string;
+        detail?: string | null;
+        action?: string | null;
+        nodeIds?: string[];
+    }, options?: {
+        source?: PmxAxSource;
+    }): PmxAxApprovalGate;
+    resolveApproval(id: string, decision: 'approved' | 'rejected', options?: {
+        resolution?: string;
+        source?: PmxAxSource;
+    }): PmxAxApprovalGate | null;
+    addReviewAnnotation(input: {
+        body: string;
+        kind?: PmxAxReviewKind;
+        severity?: PmxAxReviewSeverity;
+        anchorType?: PmxAxReviewAnchorType;
+        nodeId?: string | null;
+        file?: string | null;
+        region?: PmxAxReviewRegion | null;
+        author?: string | null;
+    }, options?: {
+        source?: PmxAxSource;
+    }): PmxAxReviewAnnotation | null;
+    setAxFocus(nodeIds: string[], options?: {
+        source?: PmxAxSource;
+    }): PmxAxFocusState;
+    requestElicitation(input: {
+        prompt: string;
+        fields?: string[];
+        nodeIds?: string[];
+    }, options?: {
+        source?: PmxAxSource;
+    }): PmxAxElicitation;
+    requestMode(input: {
+        mode: PmxAxMode;
+        reason?: string | null;
+        nodeIds?: string[];
+    }, options?: {
+        source?: PmxAxSource;
+    }): PmxAxModeRequest;
+    invokeCommand(name: string, args?: Record<string, unknown> | null, options?: {
+        source?: PmxAxSource;
+    }): PmxAxEvent | null;
+}
+export interface AxInteractionEvent {
+    event: string;
+    payload: Record<string, unknown>;
+}
+export type AxInteractionPublicResult = {
+    ok: true;
+    type: AxInteractionType;
+    sourceNodeId: string;
+    primitive: unknown;
+} | {
+    ok: false;
+    status: number;
+    code: string;
+    error: string;
+};
+export interface AxInteractionResult {
+    result: AxInteractionPublicResult;
+    events: AxInteractionEvent[];
+}
+/**
+ * Validate + execute a node-originated AX interaction. Returns the public result
+ * plus the SSE events the caller should emit (accepted/rejected outcome + the
+ * underlying AX state event). Never throws on bad input — returns an `ok: false`
+ * result with an appropriate HTTP-ish status.
+ */
+export declare function applyAxInteraction(manager: AxInteractionManager, rawBody: unknown, source: PmxAxSource): AxInteractionResult;
+export {};

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

@@ -7,7 +7,7 @@ export interface PmxAxFocusState {
     updatedAt: string | null;
     source: PmxAxSource | null;
 }
-export type PmxAxEventKind = 'prompt' | 'assistant-message' | 'tool-start' | 'tool-result' | 'failure' | 'approval' | 'steering';
+export type PmxAxEventKind = 'prompt' | 'assistant-message' | 'tool-start' | 'tool-result' | 'failure' | 'approval' | 'steering' | 'command';
 export type PmxAxEvidenceKind = 'logs' | 'tool-result' | 'screenshot' | 'file' | 'diff' | 'test-output';
 export type PmxAxWorkItemStatus = 'todo' | 'in-progress' | 'blocked' | 'done' | 'cancelled';
 export type PmxAxApprovalStatus = 'pending' | 'approved' | 'rejected';
@@ -122,6 +122,9 @@ export interface PmxAxState {
     workItems: PmxAxWorkItem[];
     approvalGates: PmxAxApprovalGate[];
     reviewAnnotations: PmxAxReviewAnnotation[];
+    elicitations: PmxAxElicitation[];
+    modeRequests: PmxAxModeRequest[];
+    policy: PmxAxPolicy;
 }
 export interface PmxAxPinnedContext {
     preamble: string;
@@ -144,12 +147,72 @@ export interface PmxAxContext {
     workItems: PmxAxWorkItem[];
     approvalGates: PmxAxApprovalGate[];
     reviewAnnotations: PmxAxReviewAnnotation[];
+    elicitations: PmxAxElicitation[];
+    modeRequests: PmxAxModeRequest[];
+    policy: PmxAxPolicy;
     timeline: PmxAxTimelineSummary;
     host: PmxAxHostCapability | null;
 }
+export interface PmxAxCommandDescriptor {
+    name: string;
+    description: string;
+}
+export declare const AX_COMMAND_REGISTRY: Record<string, PmxAxCommandDescriptor>;
+export declare function isAxCommand(name: unknown): name is string;
+export declare function listAxCommands(): PmxAxCommandDescriptor[];
+export interface PmxAxPolicy {
+    tools: {
+        allowed: string[];
+        excluded: string[];
+        approvalRequired: string[];
+    };
+    prompt: {
+        systemAppend: string | null;
+        mode: string | null;
+    };
+}
+export declare function createEmptyAxPolicy(): PmxAxPolicy;
+export declare function normalizeAxPolicy(input: unknown): PmxAxPolicy;
 export declare function isAxEventKind(value: unknown): value is PmxAxEventKind;
 export declare function isAxEvidenceKind(value: unknown): value is PmxAxEvidenceKind;
 export declare function createEmptyAxFocusState(): PmxAxFocusState;
+export type PmxAxElicitationStatus = 'pending' | 'answered' | 'cancelled';
+export interface PmxAxElicitation {
+    id: string;
+    prompt: string;
+    fields: string[];
+    status: PmxAxElicitationStatus;
+    response: Record<string, unknown> | null;
+    nodeIds: string[];
+    createdAt: string;
+    resolvedAt: string | null;
+    source: PmxAxSource | null;
+}
+export declare function normalizeAxElicitation(input: unknown, validNodeIds?: Set<string>): PmxAxElicitation | null;
+export declare function createAxElicitation(input: {
+    prompt: string;
+    fields?: string[];
+    nodeIds?: string[];
+}, source: PmxAxSource | null, validNodeIds?: Set<string>): PmxAxElicitation;
+export type PmxAxMode = 'plan' | 'execute' | 'autonomous';
+export type PmxAxModeRequestStatus = 'pending' | 'approved' | 'rejected';
+export interface PmxAxModeRequest {
+    id: string;
+    mode: PmxAxMode;
+    reason: string | null;
+    status: PmxAxModeRequestStatus;
+    nodeIds: string[];
+    createdAt: string;
+    resolvedAt: string | null;
+    resolution: string | null;
+    source: PmxAxSource | null;
+}
+export declare function normalizeAxModeRequest(input: unknown, validNodeIds?: Set<string>): PmxAxModeRequest | null;
+export declare function createAxModeRequest(input: {
+    mode: PmxAxMode;
+    reason?: string | null;
+    nodeIds?: string[];
+}, source: PmxAxSource | null, validNodeIds?: Set<string>): PmxAxModeRequest;
 export declare function createEmptyAxState(): PmxAxState;
 export declare function createEmptyAxHostCapability(): PmxAxHostCapability;
 export declare function normalizeAxFocusState(input: unknown, validNodeIds?: Set<string>): PmxAxFocusState;
@@ -207,6 +270,9 @@ export declare function buildAxContext(input: {
     workItems: PmxAxWorkItem[];
     approvalGates: PmxAxApprovalGate[];
     reviewAnnotations: PmxAxReviewAnnotation[];
+    elicitations: PmxAxElicitation[];
+    modeRequests: PmxAxModeRequest[];
+    policy: PmxAxPolicy;
     timeline: PmxAxTimelineSummary;
     host: PmxAxHostCapability | null;
 }): PmxAxContext;

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

@@ -49,6 +49,10 @@ export declare function loadAxEvidenceFromDB(db: Database, q?: AxTimelineQuery):
 export declare function loadAxSteeringFromDB(db: Database, q?: AxTimelineQuery & {
     onlyPending?: boolean;
 }): PmxAxSteeringMessage[];
+export declare function loadPendingAxSteeringFromDB(db: Database, options?: {
+    consumer?: string;
+    limit?: number;
+}): PmxAxSteeringMessage[];
 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-serialization.d.ts

@@ -6,6 +6,7 @@ export interface SerializedCanvasNode extends CanvasNodeState {
     content: string | null;
     path: string | null;
     url: string | null;
+    surfaceUrl: string | null;
     provenance: CanvasNodeProvenance | null;
 }
 export interface SerializedCanvasLayout extends Omit<CanvasLayout, 'nodes'> {
@@ -33,6 +34,7 @@ export interface CanvasAnnotationContextSummary {
 export declare function getCanvasNodeKind(node: CanvasNodeState, data: Record<string, unknown>): string;
 export declare function getCanvasNodeTitle(node: CanvasNodeState): string | null;
 export declare function getCanvasNodeContent(node: CanvasNodeState): string | null;
+export declare function getCanvasNodeSurfaceUrl(node: CanvasNodeState, data: Record<string, unknown>): string | null;
 export declare function serializeCanvasNode(node: CanvasNodeState): SerializedCanvasNode;
 export declare function serializeCanvasNodeForAgent(node: CanvasNodeState): SerializedCanvasNode;
 export declare function serializeCanvasNodeCompact(node: CanvasNodeState): SerializedCanvasNode;

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

@@ -10,7 +10,7 @@
  * Legacy `.pmx-canvas/state.json` is auto-migrated on first boot.
  */
 import { type PersistedCanvasState, type CanvasTheme, type AxTimelineQuery } from './canvas-db.js';
-import { type PmxAxFocusState, type PmxAxSource, type PmxAxState, type PmxAxWorkItem, type PmxAxWorkItemStatus, type PmxAxApprovalGate, type PmxAxReviewAnnotation, type PmxAxReviewKind, type PmxAxReviewSeverity, type PmxAxReviewStatus, type PmxAxReviewAnchorType, type PmxAxReviewRegion, type PmxAxEvent, type PmxAxEventKind, type PmxAxEvidence, type PmxAxEvidenceKind, type PmxAxSteeringMessage, type PmxAxHostCapability, type PmxAxTimelineSummary } from './ax-state.js';
+import { type PmxAxElicitation, type PmxAxModeRequest, type PmxAxMode, type PmxAxCommandDescriptor, type PmxAxPolicy, type PmxAxFocusState, type PmxAxSource, type PmxAxState, type PmxAxWorkItem, type PmxAxWorkItemStatus, type PmxAxApprovalGate, type PmxAxReviewAnnotation, type PmxAxReviewKind, type PmxAxReviewSeverity, type PmxAxReviewStatus, type PmxAxReviewAnchorType, type PmxAxReviewRegion, type PmxAxEvent, type PmxAxEventKind, type PmxAxEvidence, type PmxAxEvidenceKind, type PmxAxSteeringMessage, type PmxAxHostCapability, type PmxAxTimelineSummary } from './ax-state.js';
 export declare const PMX_CANVAS_DIR = ".pmx-canvas";
 export interface PersistedBlobRef {
     __pmxCanvasBlob: 'v1';
@@ -122,7 +122,7 @@ export interface CanvasNodeUpdate {
 }
 export type CanvasChangeType = 'pins' | 'nodes' | 'ax' | 'ax-timeline';
 export interface MutationRecordInfo {
-    operationType: 'addNode' | 'updateNode' | 'removeNode' | 'addEdge' | 'removeEdge' | 'addAnnotation' | 'removeAnnotation' | 'clear' | 'restoreSnapshot' | 'setPins' | 'setAxFocus' | 'addWorkItem' | 'updateWorkItem' | 'requestApproval' | 'resolveApproval' | 'addReviewAnnotation' | 'updateReviewAnnotation' | 'arrange' | 'batch' | 'groupNodes' | 'ungroupNodes' | 'viewport';
+    operationType: 'addNode' | 'updateNode' | 'removeNode' | 'addEdge' | 'removeEdge' | 'addAnnotation' | 'removeAnnotation' | 'clear' | 'restoreSnapshot' | 'setPins' | 'setAxFocus' | 'addWorkItem' | 'updateWorkItem' | 'requestApproval' | 'resolveApproval' | 'addReviewAnnotation' | 'updateReviewAnnotation' | 'requestElicitation' | 'respondElicitation' | 'requestMode' | 'resolveModeRequest' | 'setPolicy' | 'arrange' | 'batch' | 'groupNodes' | 'ungroupNodes' | 'viewport';
     description: string;
     forward: () => void;
     inverse: () => void;
@@ -199,6 +199,13 @@ declare class CanvasStateManager {
     private emptyPersistedState;
     /** Load canvas state from SQLite (or legacy JSON fallback). Call once on server startup. */
     loadFromDisk(options?: LoadFromDiskOptions): boolean;
+    /**
+     * Whether this workspace's canvas DB already holds saved state. Used to gate
+     * brand-new-workspace seeding (e.g. the default docked status/context widgets)
+     * so we never add nodes to a canvas that already has content. Reflects the
+     * pre-run persisted flag until the next save.
+     */
+    hasPersistedState(): boolean;
     /** Debounced save — coalesces rapid mutations into a single write. */
     private scheduleSave;
     flushToDisk(): void;
@@ -316,6 +323,42 @@ declare class CanvasStateManager {
         source?: PmxAxSource;
     }): PmxAxReviewAnnotation | null;
     getHostCapability(): PmxAxHostCapability | null;
+    getElicitations(): PmxAxElicitation[];
+    requestElicitation(input: {
+        prompt: string;
+        fields?: string[];
+        nodeIds?: string[];
+    }, options?: {
+        source?: PmxAxSource;
+    }): PmxAxElicitation;
+    respondElicitation(id: string, response: Record<string, unknown>, options?: {
+        source?: PmxAxSource;
+    }): PmxAxElicitation | null;
+    getModeRequests(): PmxAxModeRequest[];
+    requestMode(input: {
+        mode: PmxAxMode;
+        reason?: string | null;
+        nodeIds?: string[];
+    }, options?: {
+        source?: PmxAxSource;
+    }): PmxAxModeRequest;
+    resolveModeRequest(id: string, decision: 'approved' | 'rejected', options?: {
+        resolution?: string;
+        source?: PmxAxSource;
+    }): PmxAxModeRequest | null;
+    getCommandRegistry(): PmxAxCommandDescriptor[];
+    /** Invoke a registry-gated PMX command intent — records a timeline event (no execution). */
+    invokeCommand(name: string, args?: Record<string, unknown> | null, options?: {
+        source?: PmxAxSource;
+    }): PmxAxEvent | null;
+    getPolicy(): PmxAxPolicy;
+    /** Merge a declarative tool/prompt policy patch (canvas-bound, snapshotted). */
+    setPolicy(patch: {
+        tools?: Partial<PmxAxPolicy['tools']>;
+        prompt?: Partial<PmxAxPolicy['prompt']>;
+    }, _options?: {
+        source?: PmxAxSource;
+    }): PmxAxPolicy;
     setHostCapability(input: unknown, _options?: {
         source?: PmxAxSource;
     }): PmxAxHostCapability;
@@ -347,6 +390,15 @@ declare class CanvasStateManager {
     getAxSteering(q?: AxTimelineQuery & {
         onlyPending?: boolean;
     }): PmxAxSteeringMessage[];
+    /**
+     * Undelivered steering for a consumer (Phase 4 delivery). Excludes messages
+     * whose source equals the consumer to prevent delivery loops (e.g. Copilot
+     * should not be handed back steering it originated).
+     */
+    getPendingSteering(options?: {
+        consumer?: string;
+        limit?: number;
+    }): PmxAxSteeringMessage[];
     getAxTimelineSummary(): PmxAxTimelineSummary;
     getAxTimeline(q?: AxTimelineQuery): {
         events: PmxAxEvent[];

package/dist/types/server/html-surface.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Server-side builder for an `html` node's standalone surface document.
+ *
+ * This is the canonical wrapper that used to live in the client (HtmlNode's
+ * `buildSrcDoc`). It now lives on the server so a single document definition
+ * backs BOTH the in-canvas iframe and the "Open as site" tab — the iframe and
+ * the standalone tab load the exact same URL (/api/canvas/surface/:nodeId), so
+ * there is one render path and no content fork.
+ *
+ * Theming: instead of inlining a token `<style>` block, the document links the
+ * same-origin `/canvas/surface-theme.css` stylesheet and selects a palette via
+ * the `<html data-theme="...">` attribute. A sandboxed (opaque-origin) document
+ * can still load this same-origin stylesheet, and live theme switching works by
+ * toggling the attribute (the theme bridge below) — no CSS payload over
+ * postMessage required.
+ */
+export type SurfaceTheme = 'dark' | 'light' | 'high-contrast';
+/** Path the surface document links for its theme tokens (served from dist/canvas). */
+export declare const SURFACE_THEME_STYLESHEET = "/canvas/surface-theme.css";
+/** CSP sandbox tokens for an `html`/`html-primitive` surface — scripts only, opaque origin. */
+export declare const HTML_SURFACE_SANDBOX = "allow-scripts";
+export declare function normalizeSurfaceTheme(value: string | null | undefined): SurfaceTheme;
+export interface HtmlSurfaceOptions {
+    theme: SurfaceTheme;
+    /**
+     * Tab/document title. Injected as `<title>` only when the author HTML does not
+     * already declare one, so a standalone "Open as site" tab shows the node title
+     * instead of falling back to the raw URL.
+     */
+    title?: string;
+    /** Client nonce that authorizes parent → iframe theme-update messages. */
+    themeToken?: string;
+    presentation?: boolean;
+    presentationExitToken?: string;
+    /** Inject window.PMX_AX.emit (only when the node's AX capabilities are enabled). */
+    axBridge?: boolean;
+    /** Nonce authorizing iframe → parent AX emits; embedded in the bridge. */
+    axToken?: string;
+    /** Node id stamped on emitted interactions. */
+    nodeId?: string;
+}
+/**
+ * Wrap author HTML into a complete, themed standalone document. Accepts either a
+ * full HTML document (injects into its `<head>`) or a fragment (wraps it).
+ */
+export declare function buildHtmlSurfaceDocument(userHtml: string, options: HtmlSurfaceOptions): string;