pmx-canvas 0.1.21 → 0.1.23

package/CHANGELOG.md

@@ -3,6 +3,139 @@
 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
+`pmx-canvas diagram add` alias, declares kebab-case aliases for the
+HTML sidecar fields in the schema, advertises those flags in `node
+add --help --type html`, elides full file bodies from compact node
+responses, validates presentation theme names with a clear error,
+and improves keyboard focus inside present mode.
+
+### Added
+
+- **`pmx-canvas diagram add` CLI alias.** A thin wrapper that
+  delegates to `pmx-canvas external-app add --kind excalidraw` so
+  diagram creation has a discoverable top-level command. The `diagram`
+  subcommand is now registered in `AGENT_COMMANDS` and surfaces in
+  `pmx-canvas --help`. The help text for `diagram add` notes the
+  equivalence so agents can switch between the two without guessing.
+- **`node add --help --type html` advertises sidecar flags.** The
+  help output now includes a dedicated "HTML sidecar flags" section
+  listing `--summary`, `--agent-summary`, `--description`,
+  `--presentation true`, `--slide-title`, and `--embedded-node-id`,
+  matching the sidecars added in 0.1.21.
+- **Kebab-case aliases for HTML sidecar fields in
+  `canvas_describe_schema`.** The schema entries for `agentSummary`,
+  `embeddedNodeIds`, `embeddedUrls`, and `slideTitles` now declare
+  the corresponding kebab-case flag names so agents reading the
+  schema discover the CLI shape without trial and error.
+
+### Changed
+
+- **Compact node responses elide file content.**
+  `serializeCanvasNodeCompact` replaces a file node's full
+  `data.fileContent` with `{ omitted: 'file-content', bytes,
+  lineCount, sha256 }`. Agents that hit `canvas_get_node`,
+  `canvas_get_layout`, or batch-style responses without
+  `full: true` no longer re-receive the file body on every read;
+  the file `path` is still exposed as `content` so the node remains
+  fetchable.
+- **Presentation theme names are validated.** Passing an invalid
+  `theme` (or `theme.base`) to a `presentation` primitive now
+  fails fast with a clear "use canvas, midnight, paper, aurora, or
+  a custom theme object" message instead of silently falling
+  through to a default. The HTTP `POST /api/canvas/node?type=html-
+  primitive` endpoint wraps `buildHtmlPrimitive` in a try/catch and
+  returns a 400 with the message.
+- **Present-mode keyboard focus is tighter.** Tabbing inside the
+  presentation overlay now jumps to the Exit button instead of
+  escaping to the underlying canvas, Space and Enter on the Exit
+  button no longer trigger slide navigation, and the overlay
+  re-focuses itself when keyboard focus drifts outside. The deck
+  iframe loses its 18px corner radius in present mode for an
+  edge-to-edge fullscreen frame.
+
+### Internal
+
+- Regression coverage for: `node add` forwarding HTML sidecar flags
+  through to the underlying html node, `node add --help --type
+  html` advertising the new flags, `diagram add` always invoking
+  the Excalidraw external app alias, `diagram` routing through the
+  agent CLI (not the server-startup path), presentation primitives
+  rejecting unknown theme names, and batch `file` node add
+  responses returning compact `file-content` metadata instead of
+  the full body.
+
 ## [0.1.21] - 2026-05-09
 
 HTML communication maturity pass on top of 0.1.20. Adds a
@@ -981,6 +1114,8 @@ 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
 [0.1.19]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.19

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/canvas/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 ────────────────────── */