pmx-canvas 0.1.0

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

@@ -0,0 +1,154 @@
+import { type CanvasEdge, type CanvasNodeState, type CanvasNodeUpdate, type CanvasSnapshot } from './canvas-state.js';
+import { type GraphNodeInput, type JsonRenderNodeInput, type JsonRenderSpec } from '../json-render/server.js';
+export type CanvasArrangeMode = 'grid' | 'column' | 'flow';
+export type CanvasPinMode = 'set' | 'add' | 'remove';
+interface CanvasAddNodeInput {
+    type: CanvasNodeState['type'];
+    title?: string;
+    content?: string;
+    data?: Record<string, unknown>;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    defaultWidth?: number;
+    defaultHeight?: number;
+    fileMode?: 'path' | 'inline' | 'auto';
+}
+interface CanvasCreateGroupInput {
+    title?: string;
+    childIds?: string[];
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    color?: string;
+    childLayout?: CanvasArrangeMode;
+}
+export interface CanvasBatchOperation {
+    op: string;
+    assign?: string;
+    args?: Record<string, unknown>;
+}
+interface CanvasNodeLookupInput {
+    id?: string;
+    search?: string;
+}
+export declare function primeCanvasRuntimeBackends(options?: {
+    forceRehydrateExtApps?: boolean;
+}): {
+    targetIds: string[];
+};
+export declare function syncCanvasRuntimeBackends(options?: {
+    forceRehydrateExtApps?: boolean;
+    alreadyPrimed?: boolean;
+}): Promise<{
+    rehydrated: number;
+    failed: number;
+}>;
+export declare function validateCanvasNodePatch(patch: {
+    position?: {
+        x: number;
+        y: number;
+    };
+    size?: {
+        width: number;
+        height: number;
+    };
+}): string | null;
+export declare function scheduleCodeGraphRecompute(onComplete?: () => void): void;
+export declare function addCanvasNode(input: CanvasAddNodeInput): {
+    id: string;
+    node: CanvasNodeState;
+    needsCodeGraphRecompute: boolean;
+};
+export declare function resolveCanvasNode(nodeRef: CanvasNodeLookupInput): {
+    ok: true;
+    node: CanvasNodeState;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function refreshCanvasWebpageNode(id: string, options?: {
+    url?: string;
+}): Promise<{
+    ok: boolean;
+    id: string;
+    error?: string;
+}>;
+export declare function removeCanvasNode(id: string): {
+    removed: boolean;
+    needsCodeGraphRecompute: boolean;
+};
+export declare function arrangeCanvasNodes(layout: CanvasArrangeMode): {
+    arranged: number;
+    layout: CanvasArrangeMode;
+};
+export declare function applyCanvasNodeUpdates(updates: CanvasNodeUpdate[]): {
+    applied: number;
+    skipped: number;
+};
+export declare function setCanvasContextPins(nodeIds: string[], mode?: CanvasPinMode): {
+    count: number;
+    nodeIds: string[];
+};
+export declare function listCanvasSnapshots(): CanvasSnapshot[];
+export declare function saveCanvasSnapshot(name: string): CanvasSnapshot | null;
+export declare function restoreCanvasSnapshot(idOrName: string): Promise<{
+    ok: boolean;
+}>;
+export declare function deleteCanvasSnapshot(id: string): {
+    ok: boolean;
+};
+export declare function addCanvasEdge(input: {
+    from?: string;
+    to?: string;
+    fromSearch?: string;
+    toSearch?: string;
+    type: CanvasEdge['type'];
+    label?: string;
+    style?: CanvasEdge['style'];
+    animated?: boolean;
+}): {
+    id: string;
+    from: string;
+    to: string;
+};
+export declare function removeCanvasEdge(id: string): {
+    removed: boolean;
+};
+export declare function createCanvasGroup(input: CanvasCreateGroupInput): {
+    id: string;
+    node: CanvasNodeState;
+};
+export declare function groupCanvasNodes(groupId: string, childIds: string[], options?: {
+    childLayout?: CanvasArrangeMode;
+}): {
+    ok: boolean;
+};
+export declare function ungroupCanvasNodes(groupId: string): {
+    ok: boolean;
+};
+export declare function clearCanvas(): {
+    ok: boolean;
+};
+export declare function createCanvasJsonRenderNode(input: JsonRenderNodeInput): {
+    id: string;
+    url: string;
+    spec: JsonRenderSpec;
+    node: CanvasNodeState;
+};
+export declare function createCanvasGraphNode(input: GraphNodeInput): {
+    id: string;
+    url: string;
+    spec: JsonRenderSpec;
+    node: CanvasNodeState;
+};
+export declare function executeCanvasBatch(operations: CanvasBatchOperation[]): Promise<{
+    ok: boolean;
+    results: Array<Record<string, unknown>>;
+    refs: Record<string, unknown>;
+    failedIndex?: number;
+    error?: string;
+}>;
+export {};

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

@@ -0,0 +1,13 @@
+export type CanvasNodeType = 'markdown' | 'mcp-app' | 'webpage' | 'json-render' | 'graph' | 'prompt' | 'response' | 'status' | 'context' | 'ledger' | 'trace' | 'file' | 'image' | 'group';
+export type CanvasNodeProvenanceSourceKind = 'workspace-file' | 'webpage-url' | 'mcp-tool' | 'artifact-file' | 'image-url';
+export type CanvasNodeRefreshStrategy = 'file-watch' | 'file-read-write' | 'image-reload' | 'webpage-refresh' | 'mcp-app-rehydrate' | 'artifact-reopen';
+export interface CanvasNodeProvenance {
+    sourceKind: CanvasNodeProvenanceSourceKind;
+    sourceUri: string;
+    refreshStrategy: CanvasNodeRefreshStrategy;
+    snapshotContent: boolean;
+    syncedAt?: string;
+    details?: Record<string, unknown>;
+}
+export declare function inferCanvasNodeProvenance(nodeType: CanvasNodeType, data: Record<string, unknown>): CanvasNodeProvenance | null;
+export declare function normalizeCanvasNodeData<T extends Record<string, unknown>>(nodeType: CanvasNodeType, data: T): T;

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

@@ -0,0 +1,49 @@
+import { type JsonRenderComponentDescriptor } from '../json-render/catalog.js';
+import { type GraphNodeInput, type JsonRenderSpec } from '../json-render/server.js';
+export interface CanvasCreateField {
+    name: string;
+    type: string;
+    required: boolean;
+    description: string;
+    aliases?: string[];
+}
+export interface CanvasCreateTypeSchema {
+    type: string;
+    kind: 'node' | 'virtual-node';
+    description: string;
+    endpoint: string;
+    fields: CanvasCreateField[];
+    example: Record<string, unknown>;
+    notes?: string[];
+}
+export interface StructuredValidationResult {
+    ok: true;
+    type: 'json-render' | 'graph';
+    normalizedSpec: JsonRenderSpec;
+    summary: Record<string, unknown>;
+}
+declare const CANONICAL_GRAPH_TYPES: readonly ["line", "bar", "pie", "area", "scatter", "radar", "stacked-bar", "composed"];
+type CanvasGraphType = typeof CANONICAL_GRAPH_TYPES[number];
+export declare function describeCanvasSchema(): {
+    ok: true;
+    source: 'running-server';
+    version: string | null;
+    nodeTypes: CanvasCreateTypeSchema[];
+    jsonRender: {
+        rootShape: Record<string, string>;
+        components: JsonRenderComponentDescriptor[];
+    };
+    graph: {
+        graphTypes: CanvasGraphType[];
+    };
+    mcp: {
+        tools: string[];
+        resources: string[];
+    };
+};
+export declare function validateStructuredCanvasPayload(input: {
+    type: 'json-render' | 'graph';
+    spec?: unknown;
+    graph?: GraphNodeInput;
+}): StructuredValidationResult;
+export {};

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

@@ -0,0 +1,25 @@
+import type { CanvasLayout, CanvasNodeState, ViewportState } from './canvas-state.js';
+import { type CanvasNodeProvenance } from './canvas-provenance.js';
+export interface SerializedCanvasNode extends CanvasNodeState {
+    title: string | null;
+    content: string | null;
+    path: string | null;
+    url: string | null;
+    provenance: CanvasNodeProvenance | null;
+}
+export interface SerializedCanvasLayout extends Omit<CanvasLayout, 'nodes'> {
+    nodes: SerializedCanvasNode[];
+}
+export declare function getCanvasNodeTitle(node: CanvasNodeState): string | null;
+export declare function getCanvasNodeContent(node: CanvasNodeState): string | null;
+export declare function serializeCanvasNode(node: CanvasNodeState): SerializedCanvasNode;
+export declare function serializeCanvasLayout(layout: CanvasLayout): SerializedCanvasLayout;
+export interface CanvasSummary {
+    totalNodes: number;
+    totalEdges: number;
+    nodesByType: Record<string, number>;
+    pinnedCount: number;
+    pinnedTitles: string[];
+    viewport: ViewportState;
+}
+export declare function buildCanvasSummary(): CanvasSummary;

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

@@ -0,0 +1,174 @@
+/**
+ * Server-side canvas state manager.
+ *
+ * Maintains the authoritative node layout so that:
+ * - Agent tools (Phase 3) can read/mutate canvas state
+ * - Client syncs bidirectionally (SSE for server→client, POST for client→server)
+ *
+ * Persistence: canvas state auto-saves to `.pmx-canvas/state.json` in the
+ * workspace root on every mutation (debounced). Auto-loads on `loadFromDisk()`.
+ */
+export declare const PMX_CANVAS_DIR = ".pmx-canvas";
+interface LoadFromDiskOptions {
+    clearExisting?: boolean;
+}
+export declare const IMAGE_MIME_MAP: Record<string, string>;
+export interface CanvasSnapshot {
+    id: string;
+    name: string;
+    createdAt: string;
+    nodeCount: number;
+    edgeCount: number;
+}
+export interface CanvasNodeState {
+    id: string;
+    type: 'markdown' | 'mcp-app' | 'webpage' | 'json-render' | 'graph' | 'prompt' | 'response' | 'status' | 'context' | 'ledger' | 'trace' | 'file' | 'image' | 'group';
+    position: {
+        x: number;
+        y: number;
+    };
+    size: {
+        width: number;
+        height: number;
+    };
+    zIndex: number;
+    collapsed: boolean;
+    pinned: boolean;
+    dockPosition: 'left' | 'right' | null;
+    data: Record<string, unknown>;
+}
+export interface ViewportState {
+    x: number;
+    y: number;
+    scale: number;
+}
+export interface CanvasEdge {
+    id: string;
+    from: string;
+    to: string;
+    type: 'relation' | 'depends-on' | 'flow' | 'references';
+    label?: string;
+    style?: 'solid' | 'dashed' | 'dotted';
+    animated?: boolean;
+}
+export interface CanvasLayout {
+    viewport: ViewportState;
+    nodes: CanvasNodeState[];
+    edges: CanvasEdge[];
+}
+export interface CanvasNodeUpdate {
+    id: string;
+    position?: {
+        x: number;
+        y: number;
+    };
+    size?: {
+        width: number;
+        height: number;
+    };
+    collapsed?: boolean;
+    dockPosition?: 'left' | 'right' | null;
+}
+export type CanvasChangeType = 'pins' | 'nodes';
+export interface MutationRecordInfo {
+    operationType: 'addNode' | 'updateNode' | 'removeNode' | 'addEdge' | 'removeEdge' | 'clear' | 'restoreSnapshot' | 'setPins' | 'arrange' | 'batch' | 'groupNodes' | 'ungroupNodes' | 'viewport';
+    description: string;
+    forward: () => void;
+    inverse: () => void;
+}
+interface GroupNodesOptions {
+    preservePositions?: boolean;
+    layout?: 'grid' | 'column' | 'flow';
+    keepGroupFrame?: boolean;
+}
+declare class CanvasStateManager {
+    private nodes;
+    private edges;
+    private _viewport;
+    private _contextPinnedNodeIds;
+    private _workspaceRoot;
+    private _changeListeners;
+    /** Register a listener for state changes. Used by MCP server to emit resource notifications. */
+    onChange(cb: (type: CanvasChangeType) => void): void;
+    private notifyChange;
+    private _mutationRecorder;
+    private _suppressRecording;
+    /** Register a mutation recorder. Used by mutation-history to capture undo/redo closures. */
+    onMutation(cb: (info: MutationRecordInfo) => void): void;
+    /** Run a function with mutation recording suppressed (for undo/redo replay and computed edges). */
+    withSuppressedRecording(fn: () => void): void;
+    /** Create a closure that runs with recording suppressed. */
+    private suppressed;
+    private recordMutation;
+    private applyResolvedGroupBounds;
+    private getGroupSnapshot;
+    private normalizeNode;
+    private reflowAllGroups;
+    private translateGroupChildren;
+    private recomputeParentGroupBounds;
+    private compactGroupChildren;
+    private _stateFilePath;
+    private _saveTimer;
+    /** Set the workspace root to enable auto-persistence. */
+    setWorkspaceRoot(workspaceRoot: string): void;
+    /**
+     * One-time migration: rename files from the pre-consolidation layout
+     * (`.pmx-canvas.json` + `.pmx-canvas-snapshots/`) into `.pmx-canvas/`.
+     * No-op when the new layout already exists.
+     */
+    private migrateLegacyLayout;
+    getWorkspaceRoot(): string;
+    private emptyPersistedState;
+    /** Load canvas state from disk. Call once on server startup. */
+    loadFromDisk(options?: LoadFromDiskOptions): boolean;
+    /** Debounced save — coalesces rapid mutations into a single disk write. */
+    private scheduleSave;
+    flushToDisk(): void;
+    /** Write current state to disk immediately. */
+    private saveToDisk;
+    private get snapshotsDir();
+    private applyPersistedState;
+    private readResolvedSnapshot;
+    /** Save current canvas state as a named snapshot. */
+    saveSnapshot(name: string): CanvasSnapshot | null;
+    /** List all saved snapshots. */
+    listSnapshots(): CanvasSnapshot[];
+    /** Restore canvas state from a snapshot. */
+    restoreSnapshot(idOrName: string): boolean;
+    /** Read a snapshot's data without restoring it (for diff). Resolves by ID or name. */
+    getSnapshotData(idOrName: string): {
+        name: string;
+        nodes: CanvasNodeState[];
+        edges: CanvasEdge[];
+    } | null;
+    /** Delete a snapshot. */
+    deleteSnapshot(id: string): boolean;
+    get viewport(): ViewportState;
+    addNode(node: CanvasNodeState): void;
+    addJsonRenderNode(node: CanvasNodeState): void;
+    addGraphNode(node: CanvasNodeState): void;
+    updateNode(id: string, patch: Partial<CanvasNodeState>): void;
+    removeNode(id: string): void;
+    getNode(id: string): CanvasNodeState | undefined;
+    addEdge(edge: CanvasEdge): boolean;
+    removeEdge(id: string): boolean;
+    getEdges(): CanvasEdge[];
+    getEdgesForNode(nodeId: string): CanvasEdge[];
+    private removeEdgesForNode;
+    getLayout(): CanvasLayout;
+    applyUpdates(updates: CanvasNodeUpdate[]): {
+        applied: number;
+        skipped: number;
+    };
+    setViewport(v: Partial<ViewportState>): void;
+    get contextPinnedNodeIds(): Set<string>;
+    setContextPins(nodeIds: string[]): void;
+    clearContextPins(): void;
+    /** Move child nodes into a group. Sets data.parentGroup on children and data.children on the group. */
+    groupNodes(groupId: string, childIds: string[], options?: GroupNodesOptions): boolean;
+    /** Remove all children from a group, clearing their parentGroup. */
+    ungroupNodes(groupId: string): boolean;
+    clear(): void;
+}
+export declare const canvasState: CanvasStateManager;
+export {};

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

@@ -0,0 +1,33 @@
+import type { CanvasLayout } from './canvas-state.js';
+export interface CanvasValidationPair {
+    aId: string;
+    aTitle: string | null;
+    bId: string;
+    bTitle: string | null;
+}
+export interface CanvasContainmentIssue {
+    groupId: string;
+    groupTitle: string | null;
+    childId: string;
+    childTitle: string | null;
+}
+export interface CanvasValidationResult {
+    ok: boolean;
+    collisions: CanvasValidationPair[];
+    containments: CanvasContainmentIssue[];
+    containmentViolations: CanvasContainmentIssue[];
+    missingEdgeEndpoints: Array<{
+        edgeId: string;
+        from: string;
+        to: string;
+    }>;
+    summary: {
+        nodes: number;
+        edges: number;
+        collisions: number;
+        containments: number;
+        containmentViolations: number;
+        missingEdgeEndpoints: number;
+    };
+}
+export declare function validateCanvasLayout(layout: CanvasLayout): CanvasValidationResult;

package/dist/types/server/chart-template.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Chart HTML template generator — produces self-contained ext-app HTML
+ * documents that render interactive Chart.js charts inside the canvas
+ * ExtAppFrame iframe.
+ *
+ * The generated HTML:
+ * 1. Renders immediately from inline data (no bridge needed)
+ * 2. Connects to host AppBridge via the embedded ext-app App SDK runtime
+ * 3. Accepts updated data via toolInput for re-rendering
+ */
+export interface ChartDataset {
+    label: string;
+    values: number[];
+    color?: string;
+}
+export interface ChartConfig {
+    title: string;
+    chartType: 'bar' | 'line' | 'pie' | 'scatter' | 'doughnut' | 'radar';
+    labels: string[];
+    datasets: ChartDataset[];
+    xAxisLabel?: string;
+    yAxisLabel?: string;
+    stacked?: boolean;
+}
+/**
+ * Generate a self-contained HTML document that renders a Chart.js chart
+ * and optionally connects to the host via the ext-app App SDK.
+ */
+export declare function generateChartHtml(config: ChartConfig): string;

package/dist/types/server/code-graph.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Code Graph — Auto-dependency detection between file nodes.
+ *
+ * Parses imports from file node content and auto-creates `depends-on` edges
+ * between file nodes that reference each other. Updates live when files change.
+ *
+ * Supported import patterns:
+ * - JS/TS: import ... from '...', import('...'), require('...')
+ * - Python: import ..., from ... import ...
+ * - Go: import "...", import ( "..." )
+ * - Rust: mod ..., use crate::...
+ *
+ * Auto-edges are tagged with `_autoCodeGraph: true` in their metadata so they
+ * can be distinguished from manually created edges and cleaned up properly.
+ */
+export interface CodeGraphEdge {
+    fromNodeId: string;
+    toNodeId: string;
+    fromPath: string;
+    toPath: string;
+    importSpecifier: string;
+}
+export interface CodeGraphSummary {
+    totalFileNodes: number;
+    totalAutoEdges: number;
+    nodes: {
+        id: string;
+        path: string;
+        title: string | null;
+        imports: string[];
+        importedBy: string[];
+        /** Number of files this node depends on */
+        outDegree: number;
+        /** Number of files that depend on this node */
+        inDegree: number;
+    }[];
+    /** Most-depended-on files (highest inDegree) */
+    centralFiles: {
+        path: string;
+        title: string | null;
+        inDegree: number;
+    }[];
+    /** Files with no dependencies in or out (isolated) */
+    isolatedFiles: {
+        path: string;
+        title: string | null;
+    }[];
+}
+/**
+ * Extract import specifiers from file content based on file extension.
+ */
+export declare function parseImports(content: string, filePath: string): string[];
+/**
+ * Recompute all auto-edges for the code graph.
+ * Called when file nodes are added/removed or file content changes.
+ *
+ * Returns the list of edges that were created/maintained.
+ */
+export declare function recomputeCodeGraph(): CodeGraphEdge[];
+/**
+ * Build a summary of the code graph for the MCP resource.
+ */
+export declare function buildCodeGraphSummary(): CodeGraphSummary;
+/**
+ * Format code graph summary as human-readable text for MCP.
+ */
+export declare function formatCodeGraph(summary: CodeGraphSummary): string;

package/dist/types/server/context-cards.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Context cards — standalone version.
+ *
+ * In the full PMX project this reads project memory and context doc definitions.
+ * In the standalone canvas, we expose the types and a simplified builder that
+ * returns an empty card list (the host application can populate cards via the API).
+ */
+export type WorkbenchContextCardCategory = 'profile' | 'planning' | 'tooling' | 'memory';
+export interface WorkbenchContextCard {
+    key: string;
+    label: string;
+    summary: string;
+    path: string;
+    exists: boolean;
+    required: boolean;
+    staleDays: number;
+    mtimeMs: number | null;
+    state: 'loaded' | 'missing' | 'stale' | 'invalid';
+    sourceKind: 'workspace' | 'global';
+    note: string | null;
+    injectMode: 'startup';
+    category: WorkbenchContextCardCategory;
+}
+export declare function buildWorkbenchContextCards(_workspaceRoot?: string): WorkbenchContextCard[];

package/dist/types/server/diagram-presets.d.ts

@@ -0,0 +1,28 @@
+import type { ExternalMcpTransportConfig } from './mcp-app-runtime.js';
+export declare const EXCALIDRAW_MCP_URL = "https://mcp.excalidraw.com/mcp";
+export declare const EXCALIDRAW_SERVER_NAME = "Excalidraw";
+export declare const EXCALIDRAW_CREATE_VIEW_TOOL = "create_view";
+export declare const EXCALIDRAW_MCP_TRANSPORT: ExternalMcpTransportConfig;
+export interface DiagramPresetOpenInput {
+    elements: unknown;
+    title?: string;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+}
+export interface ExcalidrawOpenMcpAppInput {
+    transport: ExternalMcpTransportConfig;
+    toolName: string;
+    serverName: string;
+    toolArguments: {
+        elements: string;
+    };
+    title?: string;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+}
+export declare function normalizeExcalidrawElements(elements: unknown): string;
+export declare function buildExcalidrawOpenMcpAppInput(input: DiagramPresetOpenInput): ExcalidrawOpenMcpAppInput;

package/dist/types/server/ext-app-call-registry.d.ts

@@ -0,0 +1,16 @@
+export interface ExtAppCallIdentity {
+    toolCallId?: string;
+    serverName?: string;
+    toolName?: string;
+}
+export declare function getExtAppCallKey(serverName?: string, toolName?: string): string | null;
+export declare class ExtAppCallRegistry {
+    private activeIds;
+    private keyById;
+    private idsByKey;
+    register(identity: ExtAppCallIdentity): string | null;
+    has(toolCallId?: string): boolean;
+    resolve(identity: ExtAppCallIdentity): string | null;
+    complete(identity: ExtAppCallIdentity): string | null;
+    clear(): void;
+}

package/dist/types/server/ext-app-tool-result.d.ts

@@ -0,0 +1 @@
+export { normalizeExtAppToolResult, type NormalizeExtAppToolResultInput, } from '../shared/ext-app-tool-result.js';

package/dist/types/server/file-watcher.d.ts

@@ -0,0 +1,16 @@
+/**
+ * File watcher for file-type canvas nodes.
+ *
+ * Monitors files on disk and pushes content updates to the canvas
+ * when they change. This enables real-time file viewing: the agent
+ * edits a file, the canvas node updates automatically.
+ */
+/** Register a callback for when a watched file changes. */
+export declare function onFileNodeChanged(cb: (nodeId: string) => void): void;
+/** Start watching a file for a given node. */
+export declare function watchFileForNode(nodeId: string, filePath: string): void;
+/** Stop watching a file for a given node. */
+export declare function unwatchFileForNode(nodeId: string, filePath?: string): void;
+/** Stop all watchers. */
+export declare function unwatchAll(): void;
+export declare function rewatchAllFileNodes(): void;