pmx-canvas 0.1.21 → 0.1.22

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "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",

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

package/src/server/canvas-operations.ts

@@ -19,7 +19,7 @@ import {
 import { mutationHistory } from './mutation-history.js';
 import { computeGroupBounds, findOpenCanvasPosition } from './placement.js';
 import { searchNodes } from './spatial-analysis.js';
-import { getCanvasNodeTitle, serializeCanvasNode, type SerializedCanvasNode } from './canvas-serialization.js';
+import { getCanvasNodeTitle, serializeCanvasNodeCompact, type SerializedCanvasNode } from './canvas-serialization.js';
 import { computeAutoArrange } from '../shared/auto-arrange.js';
 import {
   buildGraphSpec,
@@ -1490,7 +1490,7 @@ function resolveBatchRefs(value: unknown, refs: Record<string, unknown>): unknow
 }
 
 function serializeCreatedNode(node: CanvasNodeState): SerializedCanvasNode {
-  return serializeCanvasNode(node);
+  return serializeCanvasNodeCompact(node);
 }
 
 export async function executeCanvasBatch(
@@ -1527,10 +1527,15 @@ export async function executeCanvasBatch(
             throw new Error('Batch html-primitive creation is not supported yet. Use node.add with type "html" and generated html, or create the primitive through MCP/HTTP/CLI first.');
           }
           if (type === 'webpage') {
+            const content = typeof args.url === 'string' && args.url.trim().length > 0
+              ? args.url
+              : typeof args.content === 'string'
+                ? args.content
+                : undefined;
             const created = addCanvasNode({
               type: 'webpage',
               ...(typeof args.title === 'string' ? { title: args.title } : {}),
-              ...(typeof args.content === 'string' ? { content: args.content } : {}),
+              ...(content ? { content } : {}),
               ...(isPlainRecord(args.data) ? { data: args.data } : {}),
               ...(typeof args.x === 'number' ? { x: args.x } : {}),
               ...(typeof args.y === 'number' ? { y: args.y } : {}),

package/src/server/canvas-schema.ts

@@ -244,11 +244,11 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     fields: [
       { name: 'html', type: 'string', required: false, description: 'HTML document or fragment rendered in the sandboxed iframe.', aliases: ['content', 'stdin'] },
       { name: 'summary', type: 'string', required: false, description: 'Explicit agent-readable summary. If omitted, PMX derives one from visible HTML text.' },
-      { name: 'agentSummary', type: 'string', required: false, description: 'Explicit semantic sidecar used by search, pinned context, and spatial context.' },
-      { name: 'embeddedNodeIds', type: 'string[]', required: false, description: 'Canvas node IDs represented or iframe-embedded by this HTML surface.' },
-      { name: 'embeddedUrls', type: 'string[]', required: false, description: 'URLs represented or iframe-embedded by this HTML surface.' },
+      { name: 'agentSummary', type: 'string', required: false, description: 'Explicit semantic sidecar used by search, pinned context, and spatial context.', aliases: ['agent-summary'] },
+      { name: 'embeddedNodeIds', type: 'string[]', required: false, description: 'Canvas node IDs represented or iframe-embedded by this HTML surface.', aliases: ['embedded-node-id'] },
+      { name: 'embeddedUrls', type: 'string[]', required: false, description: 'URLs represented or iframe-embedded by this HTML surface.', aliases: ['embedded-url'] },
       { name: 'presentation', type: 'boolean', required: false, description: 'Marks this HTML surface as a fullscreen presentation/deck.' },
-      { name: 'slideTitles', type: 'string[]', required: false, description: 'Agent-readable slide titles for presentation HTML.' },
+      { name: 'slideTitles', type: 'string[]', required: false, description: 'Agent-readable slide titles for presentation HTML.', aliases: ['slide-title'] },
       { name: 'primitive', type: 'HtmlPrimitiveKind', required: false, description: 'Generate HTML from a built-in communication primitive instead of passing raw HTML.', aliases: ['kind'] },
       { name: 'data', type: 'record<string, unknown>', required: false, description: 'Primitive data when --primitive is used, or arbitrary node metadata.' },
       { name: 'title', type: 'string', required: false, description: 'Optional node title.' },

package/src/server/canvas-serialization.ts

@@ -56,6 +56,13 @@ interface ExternalMcpAppHtmlSummary {
   sha256: string;
 }
 
+interface FileContentSummary {
+  omitted: 'file-content';
+  bytes: number;
+  lineCount: number;
+  sha256: string;
+}
+
 function pickString(value: unknown): string | null {
   return typeof value === 'string' && value.length > 0 ? value : null;
 }
@@ -142,6 +149,25 @@ export function serializeCanvasNodeForAgent(node: CanvasNodeState): SerializedCa
   };
 }
 
+export function serializeCanvasNodeCompact(node: CanvasNodeState): SerializedCanvasNode {
+  const serialized = serializeCanvasNode(node);
+  if (serialized.type !== 'file' || typeof serialized.data.fileContent !== 'string') return serialized;
+  const fileContent = serialized.data.fileContent;
+  return {
+    ...serialized,
+    content: serialized.path,
+    data: {
+      ...serialized.data,
+      fileContent: {
+        omitted: 'file-content',
+        bytes: Buffer.byteLength(fileContent, 'utf-8'),
+        lineCount: fileContent.split('\n').length,
+        sha256: createHash('sha256').update(fileContent).digest('hex'),
+      } satisfies FileContentSummary,
+    },
+  };
+}
+
 function summarizeBlobValue(value: unknown): unknown {
   if (!canvasState.isBlobReference(value)) return value;
   return {

package/src/server/html-primitives.ts

@@ -511,14 +511,23 @@ const PRESENTATION_THEMES: Record<PresentationThemeName, PresentationThemeTokens
   },
 };
 
+function isPresentationThemeName(value: string): value is PresentationThemeName {
+  return value === 'canvas' || value === 'midnight' || value === 'paper' || value === 'aurora';
+}
+
+function parsePresentationThemeName(value: string, field = 'theme'): PresentationThemeName {
+  if (isPresentationThemeName(value)) return value;
+  throw new Error(`Invalid presentation ${field} "${value}". Use canvas, midnight, paper, aurora, or a custom theme object.`);
+}
+
 function presentationTheme(data: Record<string, unknown>): PresentationThemeTokens {
   const raw = data.theme ?? data.presentationTheme;
   if (typeof raw === 'string') {
-    return PRESENTATION_THEMES[raw as PresentationThemeName] ?? PRESENTATION_THEMES.canvas;
+    return PRESENTATION_THEMES[parsePresentationThemeName(raw)];
   }
   if (!isRecord(raw)) return PRESENTATION_THEMES.canvas;
-  const baseName = typeof raw.base === 'string' && raw.base in PRESENTATION_THEMES
-    ? raw.base as PresentationThemeName
+  const baseName = typeof raw.base === 'string'
+    ? parsePresentationThemeName(raw.base, 'theme base')
     : 'canvas';
   const base = PRESENTATION_THEMES[baseName];
   const readColor = (key: string, fallback: string): string => {
@@ -544,8 +553,9 @@ function presentationTheme(data: Record<string, unknown>): PresentationThemeToke
 
 function presentationThemeMetadata(data: Record<string, unknown>): string | Record<string, string> | undefined {
   const raw = data.theme ?? data.presentationTheme;
-  if (typeof raw === 'string') return raw;
+  if (typeof raw === 'string') return parsePresentationThemeName(raw);
   if (!isRecord(raw)) return undefined;
+  if (typeof raw.base === 'string') parsePresentationThemeName(raw.base, 'theme base');
   const result: Record<string, string> = {};
   for (const [key, value] of Object.entries(raw)) {
     if (typeof value === 'string') result[key] = value;

package/src/server/server.ts

@@ -1541,11 +1541,16 @@ function createCanvasHtmlPrimitiveNode(body: Record<string, unknown>): Response
     return responseJson({ ok: false, error: `Unknown HTML primitive: ${String(rawKind)}.` }, 400);
   }
   const data = isRecord(body.data) ? body.data : {};
-  const built = buildHtmlPrimitive({
-    kind: rawKind,
-    ...(typeof body.title === 'string' ? { title: body.title } : {}),
-    data,
-  });
+  let built: ReturnType<typeof buildHtmlPrimitive>;
+  try {
+    built = buildHtmlPrimitive({
+      kind: rawKind,
+      ...(typeof body.title === 'string' ? { title: body.title } : {}),
+      data,
+    });
+  } catch (error) {
+    return responseJson({ ok: false, error: error instanceof Error ? error.message : String(error) }, 400);
+  }
   const geometry = resolveCreateGeometry(body);
   const { node } = addCanvasNode({
     type: 'html',