pmx-canvas 0.1.22 → 0.1.23

package/CHANGELOG.md

@@ -3,6 +3,75 @@
 All notable changes to `pmx-canvas` are documented here. This project follows
 [Semantic Versioning](https://semver.org/).
 
+## [0.1.23] - 2026-05-12
+
+Persistence overhaul. Canvas state, snapshots, context pins, and the
+large-payload blob store all move from filesystem JSON files into a
+single SQLite database at `.pmx-canvas/canvas.db` (WAL mode). The
+old `state.json`, `snapshots/`, and per-blob files are auto-imported
+on first boot and renamed to `.bak`. Adds dock-aware validation and
+arrange behavior, accepts the documented `?type=` query string on
+node creation, and grows the schema-metadata kebab-case aliases to
+include both singular and plural variants.
+
+### Added
+
+- **SQLite persistence (`src/server/canvas-db.ts`, 710 lines).**
+  Canvas state, snapshots, context pins, and the blob sidecar
+  store now live in `.pmx-canvas/canvas.db` (Bun SQLite in WAL
+  mode). Shape preserved across the migration: nodes, edges,
+  annotations, viewport, context pins, history, snapshots, and
+  blob payloads with checksum validation.
+  - Override DB path: `PMX_CANVAS_DB_PATH` env var.
+  - Backward-compatible legacy path: `PMX_CANVAS_STATE_FILE` (if
+    you set a `.db` path there, it's used as the DB; if not, it's
+    treated as a legacy JSON path for migration).
+  - `stopCanvasServer()` now calls `canvasState.close()` which
+    checkpoints WAL data into the DB file — stop the server (or
+    flush/close the SDK) before committing `canvas.db`.
+  - SQLite WAL/SHM files (`*.db-wal`, `*.db-shm`) are gitignored;
+    `canvas.db` itself is git-committable.
+- **Legacy migration on first boot.** Existing
+  `.pmx-canvas/state.json`, root `.pmx-canvas.json`,
+  `.pmx-canvas/snapshots/`, `.pmx-canvas-snapshots/`, and blob
+  files are imported into the SQLite database and renamed to
+  `.bak` on first start. The migration is idempotent and only
+  runs when the DB is empty.
+- **HTTP node create accepts `?type=` query string.** `POST
+  /api/canvas/node?type=html-primitive` with the body's `data`
+  fields is accepted as an alternative to passing `type` in the
+  body — handy for `curl` and shell-based agents. The body form
+  still wins when both are present.
+
+### Changed
+
+- **Docked nodes are excluded from layout collision validation.**
+  `validateCanvasLayout` no longer flags `dockPosition !== null`
+  nodes as overlap or containment violations. Docked HUD-style
+  nodes intentionally sit on top of canvas content; the validator
+  now models that.
+- **Docked nodes are treated as arrange-locked.** `arrange()`
+  now skips translating nodes with `dockPosition !== null` along
+  with pinned and explicitly arrange-locked nodes. Dock geometry
+  is anchored to the HUD layer, not the world grid.
+- **Schema kebab-case aliases include plural forms.** `--embedded-
+  node-ids`, `--embedded-urls`, and `--slide-titles` are now
+  documented aliases for the array-shaped HTML sidecar fields,
+  alongside the existing singular `--embedded-node-id`,
+  `--embedded-url`, and `--slide-title`.
+- **Bun engine bumped to `>=1.3.14`.** `package.json#engines.bun`
+  raised from `>=1.3.12` to `>=1.3.14` to pick up the
+  `bun:sqlite` improvements the new persistence layer depends on.
+
+### Internal
+
+- Regression coverage for: `validateCanvasLayout` ignoring docked
+  nodes as collision candidates, html primitive node creation
+  accepting the documented query-string `?type=` form, and the
+  existing canvas-state and operations suites continuing to pass
+  against the SQLite-backed persistence (including snapshot
+  save/restore, blob round-trip, and undo/redo history).
+
 ## [0.1.22] - 2026-05-12
 
 CLI ergonomics and response-size polish on top of 0.1.21. Adds a
@@ -1045,6 +1114,7 @@ otherwise have to discover by trial and error.
 - Regression coverage for snapshot flat-`id` aliases on both MCP and
   HTTP surfaces, plus async / top-level-`await` WebView script bodies.
 
+[0.1.23]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.23
 [0.1.22]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.22
 [0.1.21]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.21
 [0.1.20]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.20

package/Readme.md

@@ -57,11 +57,12 @@ picks up immediately.
 
 ### 05 / Save
 
-Spatial state auto-saves to `.pmx-canvas/state.json` (debounced ~500 ms) —
+Spatial state auto-saves to `.pmx-canvas/canvas.db` (debounced ~500 ms) —
 git-committable, shareable across machines, and survives both browser
 refresh and server restart. Named [snapshots](docs/mcp.md#tools), full
 undo/redo, and an auto-detected code graph (JS/TS, Python, Go, Rust) make
-the canvas durable rather than throwaway.
+the canvas durable rather than throwaway. Stop the server before committing
+the DB so SQLite WAL data is checkpointed into the file.
 
 ### 06 / Any agent
 
@@ -168,7 +169,7 @@ the agent can read `canvas://skills` and pull in companion skills
   one machine. No built-in multi-user auth or presence — collaboration means
   human ↔ agent on the same machine, plus any other browser tab/agent
   pointed at the same `localhost:4313`. To share across machines, commit
-  `.pmx-canvas/state.json`.
+  `.pmx-canvas/canvas.db`.
 - **What leaves your machine.** The core canvas runs entirely on
   `localhost`. Network egress only happens for explicit, opt-in flows:
   `webpage` nodes fetch the URL you give them; `mcp-app` /

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-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.22",
+  "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