pmx-canvas 0.1.20 → 0.1.22

package/CHANGELOG.md

@@ -3,6 +3,154 @@
 All notable changes to `pmx-canvas` are documented here. This project follows
 [Semantic Versioning](https://semver.org/).
 
+## [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
+`presentation` primitive kind (PowerPoint-style decks with themes),
+turns every html node into a first-class agent context surface with
+semantic sidecars (summary, agent summary, description, slide
+titles, embedded refs), wires a real Present-mode overlay with
+iframe-focused keyboard navigation and a live theme bridge, and
+routes the `pmx-canvas html` subcommand correctly through the agent
+CLI.
+
+### Added
+
+- **New `presentation` HTML primitive kind.** `canvas_add_html_primitive
+  --kind presentation` generates a PowerPoint-style fullscreen deck
+  inside the standard sandboxed `html` node and persists the deck
+  metadata (`presentation: true`, `slideCount`, `slideTitles`,
+  optional `presentationTheme`). Themes: `canvas`, `midnight`,
+  `paper`, `aurora`, or a custom color object with `bg`, `panel`,
+  `surface`, `border`, `text`, `textSecondary`, `textMuted`,
+  `accent`, and `colorScheme`. The MCP canvas now exposes 19 HTML
+  primitives (was 18).
+- **HTML node semantic sidecars.** Every html node can now carry
+  agent-readable metadata that agents see without parsing the
+  iframe payload: `summary`, `agentSummary`, `description`,
+  `presentation`, `slideTitles`, `embeddedNodeIds`, `embeddedUrls`.
+  Same surface lands on CLI (`pmx-canvas node add --type html
+  --summary "..." --agent-summary "..." --description "..."
+  --presentation true --slide-title "..." --embedded-node-id ...`),
+  HTTP `POST /api/canvas/node`, MCP `canvas_add_html_node`, SDK
+  `PmxCanvas.addHtmlNode()`, and `canvas_describe_schema`.
+  `agent-context` and `canvas://pinned-context` now expose this
+  metadata for HTML nodes.
+- **Auto-derived `contentSummary` for html nodes.** When the agent
+  doesn't supply an explicit summary, PMX runs the rendered HTML
+  through a new `summarizeHtmlText()` (in
+  `src/server/html-node-summary.ts`) to extract a bounded plain-
+  text summary that drives search, pinned context, and spatial
+  context. `normalizeHtmlNodeSemanticData()` keeps existing
+  provenance and semantic fields stable across edits.
+- **Browser-side Present mode.** Presentation-marked html nodes
+  surface a Present button in `ExpandedNodeOverlay` that opens a
+  fullscreen overlay with the deck iframe focused. Arrow keys,
+  Page Up/Down, Space, Home, and End are forwarded into the iframe
+  via a token-scoped postMessage bridge, and pressing Escape inside
+  the iframe exits via the same bridge. A live theme bridge
+  re-injects the canvas theme tokens into the iframe whenever the
+  theme changes, so present mode reflects light/dark toggles
+  instantly.
+- **`html-primitives.md` skill reference.** New 132-line authoring
+  guide under `skills/pmx-canvas/references/` covers when to use
+  primitives versus `canvas_add_html_node` versus
+  `canvas_build_web_artifact`, the catalog, and shared design
+  language.
+
+### Changed
+
+- **`canvas_add_html_node` clarifies presentation is opt-in.** The
+  MCP tool description now states explicitly that presentation
+  mode is opt-in (pass `presentation: true` or use the
+  `presentation` primitive) — normal html nodes remain the default
+  for reports, widgets, and bespoke visualizations.
+- **Auto-fit no longer shrinks presentation html nodes.** Like
+  graph and json-render frames, presentation-marked html nodes
+  keep their explicit width and height so decks aren't squeezed
+  by the content-fit pass.
+- **`pmx-canvas html` subcommand routes through the agent CLI.**
+  Same fix as the earlier `fit` and `screenshot` routing issues —
+  `html` is now in the `AGENT_COMMANDS` set in `src/cli/index.ts`
+  so it doesn't get treated as a server-startup invocation.
+
+### Internal
+
+- Regression coverage for: HTML node semantic sidecars persisting
+  through CLI/HTTP/MCP, presentation primitives storing slide
+  metadata and theme metadata (named + custom), agent context
+  exposing html sidecars and presentation metadata, auto-fit
+  excluding presentation html frames, the `html` CLI routing,
+  client-side present-mode behavior (only explicit presentation
+  html nodes can present; theme bridge injected; srcdoc marker
+  distinguishes review vs present mode), live theme update on
+  present-mode iframe (e2e), and present mode focusing iframe
+  keyboard navigation while hiding review hints (e2e).
+
 ## [0.1.20] - 2026-05-06
 
 A bigger feature release. Adds 18 reusable HTML communication
@@ -897,6 +1045,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.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
 [0.1.18]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.18

package/dist/canvas/global.css

@@ -2438,6 +2438,18 @@ body,
   border-color: var(--c-muted);
 }
 
+.expanded-action-btn.expanded-action-primary {
+  background: var(--c-accent-12);
+  border-color: var(--c-accent-30);
+  color: var(--c-accent);
+}
+
+.expanded-action-btn.expanded-action-primary:hover {
+  background: var(--c-accent-25);
+  border-color: var(--c-accent);
+  color: var(--c-text);
+}
+
 .expanded-action-btn.expanded-action-active {
   background: var(--c-warn-12);
   border-color: var(--c-warn-30);
@@ -2455,6 +2467,65 @@ body,
   padding: 0 4px;
 }
 
+.html-presentation-overlay {
+  position: fixed;
+  inset: 0;
+  z-index: 10050;
+  display: flex;
+  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-exit {
+  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-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: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: 0;
+  background: var(--c-bg);
+  overflow: hidden;
+}
+
+.html-node-frame-presentation {
+  flex: 1;
+  min-height: 0;
+  border-radius: 0 !important;
+}
+
 /* ── Context pin button on node title bar ────────────────────── */
 .node-controls .ctx-pin-btn {
   color: var(--c-muted);