pmx-canvas 0.1.0

package/dist/types/server/spatial-analysis.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Spatial Semantics Layer for PMX Canvas
+ *
+ * Analyzes the spatial arrangement of nodes on the canvas to extract
+ * meaningful relationships: proximity clusters, reading order, and
+ * neighborhood context around pinned nodes.
+ *
+ * This makes the canvas promise — "spatial arrangement is communication" —
+ * actually real for agents. Instead of raw x/y coordinates, agents get
+ * semantic clusters, ordered context, and implicit human intent.
+ */
+import type { CanvasNodeState, CanvasEdge } from './canvas-state.js';
+export interface SpatialCluster {
+    /** Auto-generated cluster ID */
+    id: string;
+    /** Node IDs in this cluster */
+    nodeIds: string[];
+    /** Human-readable label derived from node titles/types */
+    label: string;
+    /** Centroid of the cluster */
+    centroid: {
+        x: number;
+        y: number;
+    };
+    /** Bounding box of all nodes in the cluster */
+    bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+export interface SpatialNeighbor {
+    id: string;
+    type: string;
+    title: string | null;
+    distance: number;
+}
+export interface NodeSpatialInfo {
+    id: string;
+    type: string;
+    title: string | null;
+    content: string | null;
+    clusterId: string | null;
+    /** Reading order index (top-left to bottom-right) */
+    readingOrder: number;
+}
+export interface SpatialContext {
+    /** Total nodes on canvas */
+    totalNodes: number;
+    /** Detected proximity clusters */
+    clusters: SpatialCluster[];
+    /** All nodes in spatial reading order (top-left to bottom-right) */
+    nodesInReadingOrder: NodeSpatialInfo[];
+    /** For each pinned node, nearby unpinned nodes (the implicit context) */
+    pinnedNeighborhoods: {
+        pinnedNodeId: string;
+        pinnedNodeTitle: string | null;
+        neighbors: SpatialNeighbor[];
+    }[];
+}
+/**
+ * Detect proximity clusters using single-linkage clustering.
+ * Two nodes are "close" if their edge-to-edge gap is within the threshold.
+ *
+ * Default threshold: 200px (roughly "visually grouped" on a typical canvas).
+ */
+export declare function detectClusters(nodes: CanvasNodeState[], proximityThreshold?: number): SpatialCluster[];
+/**
+ * Find the nearest unpinned nodes to each pinned node.
+ */
+export declare function findNeighborhoods(nodes: CanvasNodeState[], pinnedIds: Set<string>, maxNeighbors?: number, maxDistance?: number): SpatialContext['pinnedNeighborhoods'];
+/**
+ * Full-text search across node titles and content.
+ * Returns matching nodes with relevance score.
+ */
+export declare function searchNodes(nodes: CanvasNodeState[], query: string): {
+    id: string;
+    type: string;
+    title: string | null;
+    snippet: string;
+    score: number;
+}[];
+/**
+ * Build the complete spatial context for the canvas.
+ */
+export declare function buildSpatialContext(nodes: CanvasNodeState[], _edges: CanvasEdge[], pinnedIds: Set<string>): SpatialContext;

package/dist/types/server/trace-manager.d.ts

@@ -0,0 +1,48 @@
+/**
+ * TraceManager — creates trace nodes and flow edges on the canvas
+ * as the agent calls tools and spawns subagents.
+ *
+ * Server-side singleton consumed by chat-view event wiring.
+ */
+declare class TraceManager {
+    private _enabled;
+    private traceNodeIds;
+    private lastTraceNodeId;
+    private toolCallToNodeId;
+    private traceOrigin;
+    private chainIndex;
+    get enabled(): boolean;
+    setEnabled(value: boolean): void;
+    onToolStart(payload: {
+        name: string;
+        toolCallId?: string;
+        activity?: string;
+        mcpServerName?: string | null;
+        mcpToolName?: string | null;
+    }): void;
+    onToolComplete(payload: {
+        name: string;
+        toolCallId?: string;
+        success?: boolean;
+        activity?: string;
+        error?: string;
+    }): void;
+    onSubagentStarted(payload: {
+        agentName: string;
+        agentDisplayName?: string;
+    }): void;
+    onSubagentCompleted(payload: {
+        agentName: string;
+        agentDisplayName?: string;
+        durationMs?: number;
+        failed?: boolean;
+    }): void;
+    clearTrace(): void;
+    getTraceNodeCount(): number;
+    private getOrigin;
+    private nextPosition;
+    private evictIfNeeded;
+    private broadcastUpdate;
+}
+export declare const traceManager: TraceManager;
+export {};

package/dist/types/server/web-artifacts.d.ts

@@ -0,0 +1,50 @@
+export interface WebArtifactBuildInput {
+    title: string;
+    appTsx: string;
+    indexCss?: string;
+    mainTsx?: string;
+    indexHtml?: string;
+    files?: Record<string, string>;
+    projectPath?: string;
+    outputPath?: string;
+    initScriptPath?: string;
+    bundleScriptPath?: string;
+    timeoutMs?: number;
+}
+export interface WebArtifactBuildOutput {
+    filePath: string;
+    fileSize: number;
+    projectPath: string;
+    metadata: Record<string, unknown>;
+    logs?: {
+        stdout?: WebArtifactLogSummary;
+        stderr?: WebArtifactLogSummary;
+    };
+    stdout?: string;
+    stderr?: string;
+}
+export interface WebArtifactLogSummary {
+    lineCount: number;
+    excerpt: string[];
+    truncated: boolean;
+    suppressedNoiseCount: number;
+}
+export interface WebArtifactCanvasOpenResult {
+    nodeId: string;
+    url: string;
+}
+export interface WebArtifactCanvasBuildResult extends WebArtifactBuildOutput {
+    openedInCanvas: boolean;
+    nodeId?: string;
+    url?: string;
+}
+export declare function resolveWorkspacePath(pathLike: string, cwd?: string): string;
+export declare function resolveWebArtifactScriptPath(kind: 'init' | 'bundle'): string;
+export declare function executeWebArtifactBuild(input: WebArtifactBuildInput): Promise<WebArtifactBuildOutput>;
+export declare function openWebArtifactInCanvas(input: {
+    title: string;
+    filePath: string;
+}): WebArtifactCanvasOpenResult;
+export declare function buildWebArtifactOnCanvas(input: WebArtifactBuildInput & {
+    openInCanvas?: boolean;
+}): Promise<WebArtifactCanvasBuildResult>;

package/dist/types/server/webpage-node.d.ts

@@ -0,0 +1,25 @@
+export declare const WEBPAGE_NODE_DEFAULT_SIZE: {
+    readonly width: 520;
+    readonly height: 420;
+};
+export interface WebpageSnapshot {
+    url: string;
+    pageTitle: string | null;
+    description: string | null;
+    imageUrl: string | null;
+    content: string;
+    excerpt: string;
+    fetchedAt: string;
+    statusCode: number;
+    contentType: string | null;
+    frameBlocked: boolean;
+    frameBlockedReason: string | null;
+}
+export declare function normalizeWebpageUrl(rawUrl: string): string;
+export declare function summarizeWebpageContent(data: Record<string, unknown>, maxLength?: number): string;
+export declare function fetchWebpageSnapshot(inputUrl: string): Promise<WebpageSnapshot>;
+export declare function getWebpageFetchErrorDetails(error: unknown): {
+    message: string;
+    statusCode: number | null;
+    contentType: string | null;
+};

package/dist/types/shared/auto-arrange.d.ts

@@ -0,0 +1,29 @@
+export interface ArrangePosition {
+    x: number;
+    y: number;
+}
+export interface ArrangeSize {
+    width: number;
+    height: number;
+}
+export interface ArrangeNode {
+    id: string;
+    type: string;
+    position: ArrangePosition;
+    size: ArrangeSize;
+    pinned: boolean;
+    dockPosition: 'left' | 'right' | null;
+    data: Record<string, unknown>;
+}
+export interface ArrangeEdge {
+    id: string;
+    from: string;
+    to: string;
+}
+export interface AutoArrangeResult {
+    nodePositions: Map<string, ArrangePosition>;
+    groupBounds: Map<string, ArrangePosition & ArrangeSize>;
+}
+type ArrangeMode = 'grid' | 'graph';
+export declare function computeAutoArrange(allNodes: ArrangeNode[], allEdges: ArrangeEdge[], mode: ArrangeMode): AutoArrangeResult;
+export {};

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

@@ -0,0 +1,9 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+export interface NormalizeExtAppToolResultInput {
+    result: unknown;
+    success?: boolean;
+    error?: string;
+    content?: string;
+    detailedContent?: string;
+}
+export declare function normalizeExtAppToolResult(input: NormalizeExtAppToolResultInput): CallToolResult;

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

@@ -0,0 +1,26 @@
+export interface CanvasPlacementRect {
+    position: {
+        x: number;
+        y: number;
+    };
+    size: {
+        width: number;
+        height: number;
+    };
+}
+export declare function rectsOverlap(a: {
+    x: number;
+    y: number;
+}, aw: number, ah: number, b: CanvasPlacementRect, gap: number): boolean;
+export declare function overlapsAny(pos: {
+    x: number;
+    y: number;
+}, width: number, height: number, existing: CanvasPlacementRect[], gap: number): boolean;
+export declare function findBlocker(pos: {
+    x: number;
+    y: number;
+}, width: number, height: number, existing: CanvasPlacementRect[], gap: number): CanvasPlacementRect | undefined;
+export declare function findOpenCanvasPosition(existing: CanvasPlacementRect[], width: number, height: number, gap?: number): {
+    x: number;
+    y: number;
+};

package/dist/types/shared/semantic-attention.d.ts

@@ -0,0 +1,97 @@
+import type { CanvasEdge, CanvasLayout, CanvasNodeState } from '../client/types.js';
+import { type SpatialContext } from '../server/spatial-analysis.js';
+export type SemanticWatchEventType = 'context-pin' | 'connect' | 'remove' | 'group' | 'move-end';
+export declare const ALL_SEMANTIC_WATCH_EVENT_TYPES: SemanticWatchEventType[];
+export interface SemanticWatchNodeSummary {
+    id: string;
+    title: string | null;
+    nodeType: CanvasNodeState['type'];
+}
+export interface SemanticWatchEdgeSummary {
+    id: string;
+    edgeType: CanvasEdge['type'];
+    fromId: string;
+    toId: string;
+    fromTitle: string | null;
+    toTitle: string | null;
+}
+export interface ContextPinWatchEvent {
+    type: 'context-pin';
+    timestamp?: string;
+    sessionId?: string;
+    added: SemanticWatchNodeSummary[];
+    removed: SemanticWatchNodeSummary[];
+}
+export interface ConnectWatchEvent {
+    type: 'connect';
+    timestamp?: string;
+    sessionId?: string;
+    edges: SemanticWatchEdgeSummary[];
+}
+export interface RemoveWatchEvent {
+    type: 'remove';
+    timestamp?: string;
+    sessionId?: string;
+    nodes: SemanticWatchNodeSummary[];
+    edges: SemanticWatchEdgeSummary[];
+}
+export interface GroupCreatedSummary {
+    id: string;
+    title: string | null;
+    childCount: number;
+}
+export interface GroupUpdatedSummary {
+    id: string;
+    title: string | null;
+    addedChildIds: string[];
+    removedChildIds: string[];
+    childCount: number;
+}
+export interface GroupWatchEvent {
+    type: 'group';
+    timestamp?: string;
+    sessionId?: string;
+    created: GroupCreatedSummary[];
+    updated: GroupUpdatedSummary[];
+}
+export interface MoveEndNodeSummary extends SemanticWatchNodeSummary {
+    reasons: string[];
+}
+export interface MoveEndWatchEvent {
+    type: 'move-end';
+    timestamp?: string;
+    sessionId?: string;
+    nodes: MoveEndNodeSummary[];
+}
+export type SemanticWatchEvent = ContextPinWatchEvent | ConnectWatchEvent | RemoveWatchEvent | GroupWatchEvent | MoveEndWatchEvent;
+export interface SseMessage {
+    event: string;
+    data: unknown;
+    id?: string;
+}
+export interface SemanticAttentionRegion {
+    id: string;
+    primaryNodeId: string;
+    nodeIds: string[];
+}
+export interface SemanticAttentionSnapshot {
+    layout: CanvasLayout | null;
+    pinnedNodeIds: string[];
+    primaryFocusNodeIds: string[];
+    secondaryFocusNodeIds: string[];
+    regions: SemanticAttentionRegion[];
+    spatial: SpatialContext | null;
+}
+export declare function formatCompactWatchEvent(event: SemanticWatchEvent): string;
+export declare class SemanticWatchReducer {
+    private currentLayout;
+    private currentPins;
+    private previousSpatial;
+    setInitialPins(nodeIds: string[]): void;
+    getAttentionSnapshot(): SemanticAttentionSnapshot;
+    handleMessage(message: SseMessage): SemanticWatchEvent[];
+    private handleContextPinsChanged;
+    private handleLayoutUpdate;
+    private buildGroupEvent;
+    private buildMoveEndEvent;
+}

package/package.json

@@ -0,0 +1,109 @@
+{
+  "name": "pmx-canvas",
+  "version": "0.1.0",
+  "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",
+  "module": "./src/server/index.ts",
+  "types": "./dist/types/server/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/server/index.d.ts",
+      "default": "./src/server/index.ts"
+    }
+  },
+  "bin": {
+    "pmx-canvas": "src/cli/index.ts"
+  },
+  "files": [
+    "src/",
+    "skills/",
+    "dist/canvas/",
+    "dist/json-render/",
+    "dist/types/",
+    "Readme.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "bun run src/cli/index.ts",
+    "dev:demo": "bun run src/cli/index.ts --demo",
+    "dev:portless": "portless run --name pmx --app-port 4313 bun run src/cli/index.ts --no-open --port=4313",
+    "dev:portless:demo": "portless run --name pmx --app-port 4313 bun run src/cli/index.ts --no-open --port=4313 --demo",
+    "build:client": "bun build src/client/index.tsx --outdir dist/canvas --minify && cp src/client/theme/global.css dist/canvas/global.css",
+    "build:json-render": "bash scripts/build-json-render.sh",
+    "build:types": "tsc -p tsconfig.types.json",
+    "build": "bun run build:client && bun run build:json-render && bun run build:types",
+    "start": "bun run src/cli/index.ts --no-open",
+    "pack:dry-run": "bun pm pack --dry-run",
+    "release:check": "bun run build && bun run typecheck && bun run test:all",
+    "release:smoke": "bash scripts/release-smoke.sh",
+    "typecheck": "tsc --noEmit",
+    "test": "PMX_CANVAS_DISABLE_BROWSER_OPEN=1 bun test tests/unit",
+    "test:unit": "PMX_CANVAS_DISABLE_BROWSER_OPEN=1 bun test tests/unit",
+    "test:coverage": "bun test tests/unit --coverage --coverage-reporter=text --coverage-reporter=lcov --coverage-dir coverage",
+    "test:web-canvas": "PMX_CANVAS_DISABLE_BROWSER_OPEN=1 bun run build && PMX_CANVAS_DISABLE_BROWSER_OPEN=1 bun x playwright test",
+    "test:e2e": "bun run test:web-canvas",
+    "test:web-canvas:headed": "bun run build && bun x playwright test --headed",
+    "test:e2e:headed": "bun run test:web-canvas:headed",
+    "test:all": "bun run test && bun run test:web-canvas",
+    "test:install-browsers": "bun x playwright install chromium",
+    "validate:agent-skills": "bash scripts/validate-agent-skill-mirrors.sh",
+    "prepublishOnly": "bun run build && bun run typecheck"
+  },
+  "dependencies": {
+    "@joplin/turndown-plugin-gfm": "^1.0.64",
+    "@json-render/core": "^0.14.1",
+    "@json-render/mcp": "^0.14.1",
+    "@json-render/react": "^0.14.1",
+    "@json-render/shadcn": "^0.14.1",
+    "@modelcontextprotocol/ext-apps": "^1.3.1",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@preact/signals": "^2.0.0",
+    "@types/turndown": "^5.0.6",
+    "marked": "^15.0.0",
+    "preact": "^10.25.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "recharts": "^3.2.1",
+    "turndown": "^7.2.4",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.58.2",
+    "@tailwindcss/cli": "^4.1.18",
+    "@types/bun": "latest",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "tailwindcss": "^4.1.18",
+    "tw-animate-css": "^1.4.0",
+    "typescript": "^5.7.0"
+  },
+  "keywords": [
+    "canvas",
+    "agent",
+    "workbench",
+    "spatial",
+    "coding-agent",
+    "claude-code",
+    "codex",
+    "cursor",
+    "windsurf",
+    "mcp",
+    "model-context-protocol",
+    "ai-tools"
+  ],
+  "author": "pskoett",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pskoett/pmx-canvas"
+  },
+  "bugs": {
+    "url": "https://github.com/pskoett/pmx-canvas/issues"
+  },
+  "homepage": "https://github.com/pskoett/pmx-canvas#readme",
+  "engines": {
+    "bun": ">=1.3.12"
+  }
+}