pmx-canvas 0.1.21 → 0.1.23

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

@@ -0,0 +1,33 @@
+/**
+ * SQLite persistence layer for canvas state.
+ *
+ * Uses Bun's built-in `bun:sqlite` for zero-dependency, synchronous,
+ * WAL-mode persistence. Replaces the previous JSON file-based approach.
+ */
+import { Database } from 'bun:sqlite';
+import type { CanvasAnnotation, CanvasEdge, CanvasNodeState, CanvasSnapshot, CanvasSnapshotListOptions, ViewportState } from './canvas-state.js';
+export interface PersistedCanvasState {
+    version: number;
+    viewport: ViewportState;
+    nodes: CanvasNodeState[];
+    edges: CanvasEdge[];
+    annotations?: CanvasAnnotation[];
+    contextPins: string[];
+}
+export declare function openCanvasDb(dbPath: string): Database;
+export declare function checkpointCanvasDb(db: Database): void;
+export declare function finalizeCanvasDbForClose(db: Database): void;
+export declare function saveStateToDB(db: Database, state: PersistedCanvasState): void;
+/** Check if the DB has been populated with canvas state at least once. */
+export declare function isDbPopulated(db: Database): boolean;
+export declare function loadStateFromDB(db: Database): PersistedCanvasState | null;
+export declare function saveSnapshotToDB(db: Database, snapshot: CanvasSnapshot, state: PersistedCanvasState): void;
+export declare function loadSnapshotFromDB(db: Database, idOrName: string): {
+    snapshot: CanvasSnapshot;
+    state: PersistedCanvasState;
+} | null;
+export declare function listSnapshotsFromDB(db: Database, options?: CanvasSnapshotListOptions): CanvasSnapshot[];
+export declare function deleteSnapshotFromDB(db: Database, id: string): boolean;
+export declare function writeBlobToDB(db: Database, sha256: string, jsonValue: string): number;
+export declare function readBlobFromDB(db: Database, sha256: string): string | null;
+export declare function hasBlobInDB(db: Database, sha256: string): boolean;

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

@@ -35,6 +35,7 @@ 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 serializeCanvasNodeForAgent(node: CanvasNodeState): SerializedCanvasNode;
+export declare function serializeCanvasNodeCompact(node: CanvasNodeState): SerializedCanvasNode;
 export declare function serializeCanvasNodeWithBlobSummaries(node: CanvasNodeState): SerializedCanvasNode;
 export declare function serializeCanvasLayout(layout: CanvasLayout): SerializedCanvasLayout;
 export declare function serializeCanvasLayoutForAgent(layout: CanvasLayout): SerializedCanvasLayout;

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

@@ -5,9 +5,11 @@
  * - 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()`.
+ * Persistence: canvas state auto-saves to `.pmx-canvas/canvas.db` (SQLite WAL mode)
+ * in the workspace root on every mutation (debounced). Auto-loads on `loadFromDisk()`.
+ * Legacy `.pmx-canvas/state.json` is auto-migrated on first boot.
  */
+import { type PersistedCanvasState } from './canvas-db.js';
 export declare const PMX_CANVAS_DIR = ".pmx-canvas";
 export interface PersistedBlobRef {
     __pmxCanvasBlob: 'v1';
@@ -17,14 +19,7 @@ export interface PersistedBlobRef {
     bytes: number;
     jsonBytes: number;
 }
-interface PersistedCanvasState {
-    version: number;
-    viewport: ViewportState;
-    nodes: CanvasNodeState[];
-    edges: CanvasEdge[];
-    annotations?: CanvasAnnotation[];
-    contextPins: string[];
-}
+export type { PersistedCanvasState } from './canvas-db.js';
 interface LoadFromDiskOptions {
     clearExisting?: boolean;
 }
@@ -166,6 +161,7 @@ declare class CanvasStateManager {
     private recomputeParentGroupBounds;
     private compactGroupChildren;
     private _stateFilePath;
+    private _db;
     private _saveTimer;
     /** Set the workspace root to enable auto-persistence. */
     setWorkspaceRoot(workspaceRoot: string): void;
@@ -185,15 +181,22 @@ declare class CanvasStateManager {
      * No-op when the new layout already exists.
      */
     private migrateLegacyLayout;
+    /**
+     * One-time migration: import state.json + snapshot JSON files + blob files
+     * into the SQLite database. Renames originals to `.bak`.
+     */
+    private migrateJsonToSqlite;
     getWorkspaceRoot(): string;
     private emptyPersistedState;
-    /** Load canvas state from disk. Call once on server startup. */
+    /** Load canvas state from SQLite (or legacy JSON fallback). Call once on server startup. */
     loadFromDisk(options?: LoadFromDiskOptions): boolean;
-    /** Debounced save — coalesces rapid mutations into a single disk write. */
+    /** Debounced save — coalesces rapid mutations into a single write. */
     private scheduleSave;
     flushToDisk(): void;
-    /** Write current state to disk immediately. */
+    /** Write current state to SQLite immediately. */
     private saveToDisk;
+    /** Close the SQLite database cleanly. Call on server shutdown. */
+    close(): void;
     private get snapshotsDir();
     private applyPersistedState;
     private readResolvedSnapshot;
@@ -217,6 +220,8 @@ declare class CanvasStateManager {
     } | null;
     /** Delete a snapshot. */
     deleteSnapshot(id: string): boolean;
+    /** Remove all snapshots from the DB. Used by test teardown. */
+    clearAllSnapshots(): void;
     get viewport(): ViewportState;
     addNode(node: CanvasNodeState): void;
     addJsonRenderNode(node: CanvasNodeState): void;
@@ -250,4 +255,3 @@ declare class CanvasStateManager {
     clear(): void;
 }
 export declare const canvasState: CanvasStateManager;
-export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "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",
@@ -106,6 +106,6 @@
   },
   "homepage": "https://github.com/pskoett/pmx-canvas#readme",
   "engines": {
-    "bun": ">=1.3.12"
+    "bun": ">=1.3.14"
   }
 }

package/skills/pmx-canvas/SKILL.md

@@ -960,12 +960,16 @@ When the human wants to explore a different approach without losing current work
 
 ## Persistence
 
-Canvas state auto-saves to `.pmx-canvas/state.json` on every mutation (debounced 500ms). State
-loads automatically on server start. The file is git-committable — spatial knowledge
+Canvas state auto-saves to `.pmx-canvas/canvas.db` on every mutation (debounced 500ms). State
+loads automatically on server start. The SQLite DB is git-committable — spatial knowledge
 persists across sessions.
 
-Snapshots save to `.pmx-canvas/snapshots/`. Web artifacts land in `.pmx-canvas/artifacts/`.
-Legacy `.pmx-canvas.json` and `.pmx-canvas-snapshots/` are auto-migrated on first boot.
+Snapshots, context pins, and large node blobs are stored in the same DB. Web artifacts land in
+`.pmx-canvas/artifacts/`. Legacy JSON state, snapshot, and blob files are auto-imported into
+SQLite and renamed to `.bak` on first boot.
+
+Stop the server or flush/close the SDK before committing `canvas.db`; shutdown checkpoints SQLite
+WAL data into the DB file.
 
 ## Real-Time Collaboration
 

package/src/cli/agent.ts

@@ -164,7 +164,7 @@ function parseFlags(args: string[]): { positional: string[]; flags: Record<strin
   // Boolean-only flags (never take a value argument)
   const BOOL_FLAGS = new Set([
     'help', 'h', 'ids', 'stdin', 'yes', 'list', 'clear', 'set', 'animated', 'dry-run', 'all',
-    'no-open-in-canvas', 'lock-arrange', 'unlock-arrange', 'json', 'compact', 'summary',
+    'no-open-in-canvas', 'lock-arrange', 'unlock-arrange', 'json', 'compact',
     'verbose', 'include-logs', 'no-pan', 'schema', 'example', 'examples', 'strict-size', 'scroll-overflow',
   ]);
   for (let i = 0; i < args.length; i++) {
@@ -1723,6 +1723,16 @@ cmd('external-app add', 'Create a hosted external app node', [
     : result);
 });
 
+cmd('diagram add', 'Create an Excalidraw diagram node', [
+  'pmx-canvas diagram add --title "Architecture"',
+  'pmx-canvas diagram add --title "Architecture" --elements \'[{"type":"rectangle","id":"r1","x":0,"y":0,"width":120,"height":80}]\'',
+], async (args) => {
+  const { flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('diagram add');
+  const externalAppAdd = COMMANDS['external-app add'];
+  await externalAppAdd.run([...args, '--kind', 'excalidraw']);
+});
+
 // ── pin ──────────────────────────────────────────────────────
 cmd('pin', 'Manage context pins', [
   'pmx-canvas pin node1 node2 node3',
@@ -2431,11 +2441,19 @@ function showCommandHelp(name: string): void {
   if (name === 'node add') {
     console.log('\nSchema help:');
     console.log('  pmx-canvas node add --help --type webpage');
+    console.log('  pmx-canvas node add --help --type html');
     console.log('  pmx-canvas node add --help --type json-render --component Table');
     console.log('  pmx-canvas node add --help --type graph');
     console.log('  pmx-canvas html primitive schema --summary');
     console.log('  pmx-canvas node add --help --type webpage --json');
     console.log('  Use --strict-size to keep explicit width/height fixed and scroll overflowing content.');
+    console.log('\nHTML sidecar flags:');
+    console.log('  --summary <text>           Explicit human/agent-readable summary');
+    console.log('  --agent-summary <text>     Semantic summary for search, pinned context, and spatial context');
+    console.log('  --description <text>       Optional longer semantic description');
+    console.log('  --presentation true        Mark raw HTML as an explicit presentation deck');
+    console.log('  --slide-title <text>       Add a presentation slide title sidecar');
+    console.log('  --embedded-node-id <id>    Link represented/embedded canvas node ID');
   }
   if (name === 'html primitive add' || name === 'html primitive schema') {
     console.log('\nPrimitive flags:');
@@ -2534,6 +2552,10 @@ function showCommandHelp(name: string): void {
     console.log('  --initial-file <path>      Alias for --elements-file');
     console.log('  --timeout-ms <number>      Optional downstream MCP timeout for cold starts');
   }
+  if (name === 'diagram add') {
+    console.log('\nAlias:');
+    console.log('  Equivalent to: pmx-canvas external-app add --kind excalidraw ...');
+  }
   console.log('');
 }
 
@@ -2561,6 +2583,7 @@ Node commands:
   pmx-canvas graph add [options]      Add a graph node
   pmx-canvas html primitive add        Add an HTML communication primitive
   pmx-canvas html primitive schema     List HTML primitive kinds and shapes
+  pmx-canvas diagram add               Add an Excalidraw diagram node
 
 Edge commands:
   pmx-canvas edge add [options]       Add an edge between nodes
@@ -2636,6 +2659,7 @@ Examples:
   pmx-canvas graph add --graph-type bar --data-file ./metrics.json --x-key label --y-key value
   pmx-canvas html primitive add --kind choice-grid --data-file ./options.json --title "Options"
   pmx-canvas html primitive schema --summary
+  pmx-canvas diagram add --title "Architecture"
   pmx-canvas node add --help --type webpage
   pmx-canvas node schema --type json-render
   pmx-canvas node schema --type json-render --component Table --summary

package/src/cli/index.ts

@@ -32,7 +32,7 @@ if (args.includes('--version') || args.includes('-v')) {
 const AGENT_COMMANDS = new Set([
   'node', 'edge', 'json-render', 'search', 'layout', 'status', 'arrange', 'focus',
   'fit', 'screenshot', 'pin', 'undo', 'redo', 'history', 'snapshot', 'diff', 'group', 'webview', 'open',
-  'clear', 'code-graph', 'spatial', 'watch', 'web-artifact', 'external-app', 'graph', 'html', 'batch', 'validate', 'serve',
+  'clear', 'code-graph', 'spatial', 'watch', 'web-artifact', 'external-app', 'diagram', 'graph', 'html', 'batch', 'validate', 'serve',
 ]);
 
 const firstArg = args[0] ?? '';
@@ -506,6 +506,7 @@ Agent CLI (works against running server):
   watch [--json] [--events ...]       Watch low-token semantic canvas changes
   focus <node-id>                     Pan to node
   external-app add                    Add hosted external apps like Excalidraw
+  diagram add                         Add an Excalidraw diagram node
   pin <ids...> | --list | --clear     Manage context pins
   undo / redo / history               Time travel
   snapshot save|list|restore|diff|delete
@@ -550,6 +551,7 @@ Examples:
   pmx-canvas node schema --type json-render                   Show running-server schema info
   pmx-canvas web-artifact build --title "Dashboard" --app-file ./App.tsx
   pmx-canvas external-app add --kind excalidraw --title "Diagram"
+  pmx-canvas diagram add --title "Diagram"
   pmx-canvas validate spec --type graph --graph-type bar --data-file ./metrics.json --x-key label --y-key value
   pmx-canvas open                                             Open the workbench in a browser
   pmx-canvas webview status                                   Show WebView automation status

package/src/client/canvas/ExpandedNodeOverlay.tsx

@@ -93,6 +93,10 @@ function isPresentationNavigationKey(key: string): boolean {
   return key === 'ArrowRight' || key === 'PageDown' || key === ' ' || key === 'ArrowLeft' || key === 'PageUp' || key === 'Home' || key === 'End';
 }
 
+function isPresentationExitButtonTarget(target: EventTarget | null): boolean {
+  return target instanceof HTMLElement && Boolean(target.closest('.html-presentation-exit'));
+}
+
 export function ExpandedNodeOverlay() {
   const nodeId = expandedNodeId.value;
   const node = nodeId ? nodes.value.get(nodeId) : undefined;
@@ -100,6 +104,7 @@ export function ExpandedNodeOverlay() {
   const [presenting, setPresenting] = useState(false);
   const [presentationExitToken, setPresentationExitToken] = useState('');
   const presentationOverlayRef = useRef<HTMLDivElement>(null);
+  const presentationExitButtonRef = useRef<HTMLButtonElement>(null);
 
   const handleClose = useCallback(() => {
     setPresenting(false);
@@ -131,6 +136,13 @@ export function ExpandedNodeOverlay() {
       setPresenting(false);
       return;
     }
+    if (event.key === 'Tab' && !isPresentationExitButtonTarget(event.target)) {
+      event.preventDefault();
+      event.stopPropagation();
+      presentationExitButtonRef.current?.focus();
+      return;
+    }
+    if ((event.key === ' ' || event.key === 'Enter') && isPresentationExitButtonTarget(event.target)) return;
     if (!isPresentationNavigationKey(event.key)) return;
     event.preventDefault();
     event.stopPropagation();
@@ -165,7 +177,9 @@ export function ExpandedNodeOverlay() {
   useLayoutEffect(() => {
     if (!presenting) return;
     const focusPresentationOverlay = () => {
-      presentationOverlayRef.current?.focus();
+      const overlay = presentationOverlayRef.current;
+      if (!overlay || overlay.contains(document.activeElement)) return;
+      overlay.focus();
     };
     const focusTimers = [0, 50, 150].map((delay) => window.setTimeout(focusPresentationOverlay, delay));
     const handleMessage = (event: MessageEvent) => {
@@ -354,20 +368,16 @@ export function ExpandedNodeOverlay() {
         </div>
         {canPresent && presenting && (
           <div ref={presentationOverlayRef} class="html-presentation-overlay" role="dialog" aria-modal="true" aria-label={`Present ${title}`} tabIndex={-1} onKeyDownCapture={handlePresentationKeyDown}>
-            <div class="html-presentation-toolbar">
-              <div>
-                <div class="html-presentation-kicker">HTML presentation</div>
-                <div class="html-presentation-title">{title}</div>
-              </div>
-              <button
-                type="button"
-                class="html-presentation-exit"
-                onClick={handleExitPresentation}
-                title="Exit presentation (Esc)"
-              >
-                Exit presentation
-              </button>
-            </div>
+            <button
+              ref={presentationExitButtonRef}
+              type="button"
+              class="html-presentation-exit"
+              onClick={handleExitPresentation}
+              title="Exit presentation (Esc)"
+              aria-label="Exit presentation"
+            >
+              Exit presentation
+            </button>
             <div class="html-presentation-stage">
               <HtmlNode node={node} expanded presentation presentationExitToken={presentationExitToken} />
             </div>

package/src/client/nodes/HtmlNode.tsx

@@ -255,7 +255,7 @@ export function HtmlNode({
         minHeight: presentation ? 0 : expanded ? '70vh' : '300px',
         border: 'none',
         background: 'var(--c-bg)',
-        borderRadius: presentation ? '18px' : '6px',
+        borderRadius: presentation ? 0 : '6px',
         display: 'block',
       }}
     />

package/src/client/theme/global.css

@@ -2472,75 +2472,58 @@ body,
   inset: 0;
   z-index: 10050;
   display: flex;
-  flex-direction: column;
-  gap: 14px;
-  padding: clamp(12px, 2vw, 28px);
+  padding: 0;
   background:
     radial-gradient(circle at top left, var(--c-accent-25), transparent 36rem),
     rgba(3, 7, 18, 0.96);
   color: var(--c-text);
 }
 
-.html-presentation-toolbar {
-  display: flex;
-  align-items: center;
-  justify-content: space-between;
-  gap: 16px;
-  flex-shrink: 0;
-  padding: 10px 12px;
-  border: 1px solid var(--c-line);
-  border-radius: 16px;
-  background: var(--c-panel-glass);
-  box-shadow: 0 18px 50px var(--c-shadow-heavy);
-}
-
-.html-presentation-kicker {
-  color: var(--c-accent);
-  font-size: 10px;
-  font-weight: 800;
-  letter-spacing: 0.14em;
-  text-transform: uppercase;
-}
-
-.html-presentation-title {
-  max-width: min(72vw, 900px);
-  overflow: hidden;
-  color: var(--c-text);
-  font-size: 14px;
-  font-weight: 700;
-  text-overflow: ellipsis;
-  white-space: nowrap;
-}
-
 .html-presentation-exit {
-  flex-shrink: 0;
-  padding: 8px 12px;
+  position: fixed;
+  top: 12px;
+  right: 12px;
+  z-index: 1;
+  padding: 10px 14px;
   border: 1px solid var(--c-line);
   border-radius: 999px;
-  background: var(--c-panel-soft);
+  background: var(--c-panel-glass);
+  box-shadow: 0 18px 50px var(--c-shadow-heavy);
   color: var(--c-text-soft);
   cursor: pointer;
   font: 600 12px/1 var(--font);
+  opacity: 0;
+  pointer-events: none;
+  transform: translateY(-6px);
+  transition: opacity 0.15s ease, transform 0.15s ease, border-color 0.15s ease, color 0.15s ease;
 }
 
-.html-presentation-exit:hover {
+.html-presentation-exit:hover,
+.html-presentation-exit:focus-visible {
   border-color: var(--c-accent);
   color: var(--c-text);
 }
 
+.html-presentation-exit:focus,
+.html-presentation-exit:focus-visible {
+  opacity: 1;
+  pointer-events: auto;
+  transform: translateY(0);
+}
+
 .html-presentation-stage {
   flex: 1;
   min-height: 0;
   display: flex;
-  border-radius: 22px;
+  border-radius: 0;
   background: var(--c-bg);
-  box-shadow: 0 24px 90px rgba(0, 0, 0, 0.55);
   overflow: hidden;
 }
 
 .html-node-frame-presentation {
   flex: 1;
   min-height: 0;
+  border-radius: 0 !important;
 }
 
 /* ── Context pin button on node title bar ────────────────────── */