pmx-canvas 0.1.20 → 0.1.22

package/src/client/canvas/ExpandedNodeOverlay.tsx

@@ -1,4 +1,4 @@
-import { useCallback, useState } from 'preact/hooks';
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'preact/hooks';
 import { ContextNode } from '../nodes/ContextNode';
 import { FileNode } from '../nodes/FileNode';
 import { LedgerNode } from '../nodes/LedgerNode';
@@ -7,7 +7,7 @@ import { McpAppNode } from '../nodes/McpAppNode';
 import { StatusNode } from '../nodes/StatusNode';
 import { ImageNode } from '../nodes/ImageNode';
 import { WebpageNode } from '../nodes/WebpageNode';
-import { HtmlNode } from '../nodes/HtmlNode';
+import { HtmlNode, shouldShowPresentationControls } from '../nodes/HtmlNode';
 import { PromptNode } from '../nodes/PromptNode';
 import { ResponseNode } from '../nodes/ResponseNode';
 import { TraceNode } from '../nodes/TraceNode';
@@ -81,15 +81,74 @@ function wordCount(text: string): number {
   return text.split(/\s+/).filter(Boolean).length;
 }
 
+function isPresentationExitMessage(value: unknown, token: string): boolean {
+  return value !== null &&
+    typeof value === 'object' &&
+    (value as { source?: unknown }).source === 'pmx-canvas-html-node' &&
+    (value as { type?: unknown }).type === 'presentation-exit' &&
+    (value as { token?: unknown }).token === token;
+}
+
+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;
   const [copied, setCopied] = useState(false);
+  const [presenting, setPresenting] = useState(false);
+  const [presentationExitToken, setPresentationExitToken] = useState('');
+  const presentationOverlayRef = useRef<HTMLDivElement>(null);
+  const presentationExitButtonRef = useRef<HTMLButtonElement>(null);
 
   const handleClose = useCallback(() => {
+    setPresenting(false);
     collapseExpandedNode();
   }, []);
 
+  const handlePresent = useCallback(() => {
+    setPresentationExitToken(`presentation-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`);
+    setPresenting(true);
+  }, []);
+
+  const postPresentationMessage = useCallback((message: Record<string, unknown>) => {
+    const frame = document.querySelector<HTMLIFrameElement>('.html-presentation-overlay iframe.html-node-frame-presentation');
+    frame?.contentWindow?.postMessage({
+      source: 'pmx-canvas-html-node',
+      token: presentationExitToken,
+      ...message,
+    }, '*');
+  }, [presentationExitToken]);
+
+  const handleExitPresentation = useCallback(() => {
+    setPresenting(false);
+  }, []);
+
+  const handlePresentationKeyDown = useCallback((event: KeyboardEvent) => {
+    if (event.key === 'Escape') {
+      event.preventDefault();
+      event.stopPropagation();
+      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();
+    postPresentationMessage({ type: 'presentation-key', key: event.key });
+  }, [postPresentationMessage]);
+
   const handleBackdropPointerDown = useCallback((e: PointerEvent) => {
     if ((e.target as HTMLElement).classList.contains('expanded-overlay-backdrop')) {
       collapseExpandedNode();
@@ -111,6 +170,31 @@ export function ExpandedNodeOverlay() {
     toggleContextPin(nodeId);
   }, [nodeId]);
 
+  useEffect(() => {
+    setPresenting(false);
+  }, [nodeId]);
+
+  useLayoutEffect(() => {
+    if (!presenting) return;
+    const focusPresentationOverlay = () => {
+      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) => {
+      if (!isPresentationExitMessage(event.data, presentationExitToken)) return;
+      setPresenting(false);
+    };
+    document.addEventListener('keydown', handlePresentationKeyDown, true);
+    window.addEventListener('message', handleMessage);
+    return () => {
+      focusTimers.forEach((timer) => window.clearTimeout(timer));
+      document.removeEventListener('keydown', handlePresentationKeyDown, true);
+      window.removeEventListener('message', handleMessage);
+    };
+  }, [handlePresentationKeyDown, presentationExitToken, presenting]);
+
   if (!node) return null;
 
   const title =
@@ -123,6 +207,7 @@ export function ExpandedNodeOverlay() {
   const hasText = textContent.length > 0;
   const pendingClose = pendingExpandedNodeCloseId.value === nodeId;
   const isEmbeddedViewer = node.type === 'mcp-app' || node.type === 'webpage' || node.type === 'json-render' || node.type === 'graph';
+  const canPresent = shouldShowPresentationControls(node);
 
   return (
     <div
@@ -218,6 +303,17 @@ export function ExpandedNodeOverlay() {
               </button>
             )}
 
+            {canPresent && (
+              <button
+                type="button"
+                class="expanded-action-btn expanded-action-primary"
+                onClick={handlePresent}
+                title="Present this HTML node fullscreen"
+              >
+                Present
+              </button>
+            )}
+
             {/* Word count */}
             {words > 0 && (
               <span class="expanded-meta">
@@ -270,6 +366,23 @@ export function ExpandedNodeOverlay() {
             </div>
           ) : renderContent(node, true)}
         </div>
+        {canPresent && presenting && (
+          <div ref={presentationOverlayRef} class="html-presentation-overlay" role="dialog" aria-modal="true" aria-label={`Present ${title}`} tabIndex={-1} onKeyDownCapture={handlePresentationKeyDown}>
+            <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>
+          </div>
+        )}
       </div>
     </div>
   );

package/src/client/canvas/auto-fit.ts

@@ -11,8 +11,12 @@ function hasExplicitStructuredFrame(node: CanvasNodeState): boolean {
   return node.type === 'graph' || node.type === 'json-render';
 }
 
+function isPresentationHtmlNode(node: CanvasNodeState): boolean {
+  return node.type === 'html' && node.data.presentation === true;
+}
+
 export function shouldAutoFitNode(node: CanvasNodeState): boolean {
-  return !node.collapsed && !node.dockPosition && node.data.strictSize !== true && node.type !== 'group' && !isExtAppNode(node) && !hasExplicitStructuredFrame(node);
+  return !node.collapsed && !node.dockPosition && node.data.strictSize !== true && node.type !== 'group' && !isExtAppNode(node) && !hasExplicitStructuredFrame(node) && !isPresentationHtmlNode(node);
 }
 
 export function computeAutoFitHeight(node: CanvasNodeState, contentHeight: number): number | null {

package/src/client/nodes/HtmlNode.tsx

@@ -1,4 +1,5 @@
-import { useMemo } from 'preact/hooks';
+import { useEffect, useMemo, useRef } from 'preact/hooks';
+import { canvasTheme } from '../state/canvas-store';
 import { getCanvasTokens } from '../theme/tokens';
 import type { CanvasNodeState } from '../types';
 
@@ -95,28 +96,135 @@ function buildThemeStyleBlock(): string {
  * a `<head>`, inject at the top of head; otherwise wrap the content in a full
  * document. Returns a complete HTML string suitable for `srcdoc`.
  */
-function buildSrcDoc(userHtml: string): string {
-  const styleBlock = `<style data-pmx-canvas-theme>${buildThemeStyleBlock()}</style>`;
+function buildPresentationEscapeBridge(exitToken?: string): string {
+  const token = JSON.stringify(exitToken ?? '');
+  return `<script data-pmx-canvas-presentation-bridge>
+const PMX_CANVAS_PRESENTATION_EXIT_TOKEN = ${token};
+document.addEventListener('keydown', (event) => {
+  if (event.key === 'Escape') {
+    window.parent.postMessage({ source: 'pmx-canvas-html-node', type: 'presentation-exit', token: PMX_CANVAS_PRESENTATION_EXIT_TOKEN }, '*');
+  }
+}, true);
+window.addEventListener('message', (event) => {
+  const message = event.data;
+  if (!message || message.source !== 'pmx-canvas-html-node' || message.type !== 'presentation-key' || message.token !== PMX_CANVAS_PRESENTATION_EXIT_TOKEN) return;
+  if (typeof message.key !== 'string') return;
+  if (typeof window.PMX_CANVAS_PRESENTATION_HANDLE_KEY === 'function') {
+    window.PMX_CANVAS_PRESENTATION_HANDLE_KEY(message.key);
+    return;
+  }
+  document.dispatchEvent(new CustomEvent('pmx-presentation-key', { detail: { key: message.key }, bubbles: true, cancelable: true }));
+  document.dispatchEvent(new KeyboardEvent('keydown', { key: message.key, bubbles: true, cancelable: true }));
+});
+</script>`;
+}
+
+function buildThemeBridge(themeToken: string): string {
+  const token = JSON.stringify(themeToken);
+  return `<script data-pmx-canvas-theme-bridge>
+const PMX_CANVAS_THEME_TOKEN = ${token};
+window.addEventListener('message', (event) => {
+  const message = event.data;
+  if (!message || message.source !== 'pmx-canvas-html-node' || message.type !== 'theme-update' || message.token !== PMX_CANVAS_THEME_TOKEN) return;
+  if (typeof message.css !== 'string' || typeof message.theme !== 'string') return;
+  let style = document.querySelector('style[data-pmx-canvas-theme]');
+  if (!style) {
+    style = document.createElement('style');
+    style.setAttribute('data-pmx-canvas-theme', '');
+    document.head.prepend(style);
+  }
+  style.textContent = message.css;
+  document.documentElement.setAttribute('data-pmx-canvas-theme', message.theme);
+  document.documentElement.setAttribute('data-theme', message.theme);
+});
+</script>`;
+}
+
+function injectIntoHead(html: string, content: string): string {
+  if (/<head[\s>]/i.test(html)) {
+    return html.replace(/<head([^>]*)>/i, `<head$1>${content}`);
+  }
+  if (/<html[\s>]/i.test(html)) {
+    return html.replace(/<html([^>]*)>/i, `<html$1><head>${content}</head>`);
+  }
+  return html;
+}
+
+function buildSrcDoc(userHtml: string, options: { presentation?: boolean; presentationExitToken?: string; themeToken: string; themeCss: string; theme: string }): string {
+  const styleBlock = `<style data-pmx-canvas-theme>${options.themeCss}</style>`;
+  const themeBridge = buildThemeBridge(options.themeToken);
+  const presentationBridge = options.presentation ? buildPresentationEscapeBridge(options.presentationExitToken) : '';
+  const injectedHeadContent = `${styleBlock}${themeBridge}${presentationBridge}`;
+  const presentationAttr = options.presentation ? ' data-pmx-presentation-mode="present"' : '';
   const trimmed = userHtml.trim();
   const isFullDoc = /<html[\s>]/i.test(trimmed);
   if (isFullDoc) {
-    if (/<head[\s>]/i.test(trimmed)) {
-      return trimmed.replace(/<head([^>]*)>/i, `<head$1>${styleBlock}`);
-    }
-    // Has <html> but no <head> — inject one.
-    return trimmed.replace(/<html([^>]*)>/i, `<html$1><head>${styleBlock}</head>`);
+    const withTheme = trimmed.replace(/<html([^>]*)>/i, `<html$1 data-pmx-canvas-theme="${options.theme}" data-theme="${options.theme}"${presentationAttr}>`);
+    return injectIntoHead(withTheme, injectedHeadContent);
   }
   // Fragment — wrap in full document.
-  return `<!doctype html><html><head><meta charset="utf-8">${styleBlock}</head><body>${userHtml}</body></html>`;
+  return `<!doctype html><html data-pmx-canvas-theme="${options.theme}" data-theme="${options.theme}"${presentationAttr}><head><meta charset="utf-8">${injectedHeadContent}</head><body>${userHtml}</body></html>`;
+}
+
+export function createHtmlNodeSrcDocForTest(userHtml: string, options: { theme: string; themeCss: string; themeToken?: string; presentation?: boolean; presentationExitToken?: string }): string {
+  return buildSrcDoc(userHtml, {
+    themeToken: options.themeToken ?? 'test-theme-token',
+    theme: options.theme,
+    themeCss: options.themeCss,
+    presentation: options.presentation,
+    presentationExitToken: options.presentationExitToken,
+  });
+}
+
+export function shouldShowPresentationControls(node: CanvasNodeState): boolean {
+  return node.type === 'html' && node.data.presentation === true;
 }
 
-export function HtmlNode({ node, expanded = false }: { node: CanvasNodeState; expanded?: boolean }) {
+export function HtmlNode({
+  node,
+  expanded = false,
+  presentation = false,
+  presentationExitToken,
+  autoFocus = false,
+}: { node: CanvasNodeState; expanded?: boolean; presentation?: boolean; presentationExitToken?: string; autoFocus?: boolean }) {
+  const iframeRef = useRef<HTMLIFrameElement>(null);
+  const theme = canvasTheme.value;
+  const themeToken = useMemo(() => `theme-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`, []);
+  const themeCss = useMemo(() => buildThemeStyleBlock(), [theme]);
   const html = typeof node.data.html === 'string'
     ? node.data.html
     : typeof node.data.content === 'string'
       ? node.data.content
       : '';
-  const srcDoc = useMemo(() => (html ? buildSrcDoc(html) : ''), [html]);
+  const srcDoc = useMemo(() => (html ? buildSrcDoc(html, { presentation, presentationExitToken, themeToken, themeCss, theme }) : ''), [html, presentation, presentationExitToken, themeToken]);
+
+  useEffect(() => {
+    iframeRef.current?.contentWindow?.postMessage({
+      source: 'pmx-canvas-html-node',
+      type: 'theme-update',
+      token: themeToken,
+      theme,
+      css: themeCss,
+    }, '*');
+    if (autoFocus) iframeRef.current?.focus();
+  }, [theme, themeCss, themeToken]);
+
+  useEffect(() => {
+    if (!autoFocus) return;
+    const id = window.setTimeout(() => iframeRef.current?.focus(), 0);
+    return () => window.clearTimeout(id);
+  }, [autoFocus, srcDoc]);
+
+  const handleFrameLoad = () => {
+    iframeRef.current?.contentWindow?.postMessage({
+      source: 'pmx-canvas-html-node',
+      type: 'theme-update',
+      token: themeToken,
+      theme,
+      css: themeCss,
+    }, '*');
+    if (autoFocus) iframeRef.current?.focus();
+  };
 
   if (!html) {
     return (
@@ -134,16 +242,20 @@ export function HtmlNode({ node, expanded = false }: { node: CanvasNodeState; ex
   // arbitrary author code runs inside this exact sandbox.
   return (
     <iframe
+      ref={iframeRef}
+      class={presentation ? 'html-node-frame html-node-frame-presentation' : 'html-node-frame'}
       title={typeof node.data.title === 'string' ? node.data.title : 'HTML node'}
       sandbox="allow-scripts"
       srcdoc={srcDoc}
+      tabIndex={autoFocus ? 0 : undefined}
+      onLoad={handleFrameLoad}
       style={{
         width: '100%',
         height: '100%',
-        minHeight: expanded ? '70vh' : '300px',
+        minHeight: presentation ? 0 : expanded ? '70vh' : '300px',
         border: 'none',
         background: 'var(--c-bg)',
-        borderRadius: '6px',
+        borderRadius: presentation ? 0 : '6px',
         display: 'block',
       }}
     />

package/src/client/state/sse-bridge.ts

@@ -291,9 +291,9 @@ function ensureLedgerNode(summary: Record<string, unknown>): void {
 function applyCanvasTheme(theme: string): void {
   const valid = theme === 'dark' || theme === 'light' || theme === 'high-contrast';
   if (!valid || canvasTheme.value === theme) return;
-  canvasTheme.value = theme;
   document.documentElement.setAttribute('data-theme', theme);
   invalidateTokenCache();
+  canvasTheme.value = theme;
 }
 
 function isCanvasNodeType(value: unknown): value is CanvasNodeState['type'] {

package/src/client/theme/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);

package/src/mcp/canvas-access.ts

@@ -442,7 +442,37 @@ class RemoteCanvasAccess implements CanvasAccess {
   }
 
   async addHtmlNode(input: AddHtmlNodeInput): Promise<string> {
-    return await this.requestNodeId('POST', '/api/canvas/node', { type: 'html', ...input });
+    const {
+      summary,
+      agentSummary,
+      description,
+      presentation,
+      slideTitles,
+      embeddedNodeIds,
+      embeddedUrls,
+      ...rest
+    } = input as AddHtmlNodeInput & {
+      summary?: string;
+      agentSummary?: string;
+      description?: string;
+      presentation?: boolean;
+      slideTitles?: string[];
+      embeddedNodeIds?: string[];
+      embeddedUrls?: string[];
+    };
+    return await this.requestNodeId('POST', '/api/canvas/node', {
+      type: 'html',
+      ...rest,
+      data: {
+        ...(typeof summary === 'string' ? { summary } : {}),
+        ...(typeof agentSummary === 'string' ? { agentSummary } : {}),
+        ...(typeof description === 'string' ? { description } : {}),
+        ...(presentation === true ? { presentation: true } : {}),
+        ...(Array.isArray(slideTitles) ? { slideTitles } : {}),
+        ...(Array.isArray(embeddedNodeIds) ? { embeddedNodeIds } : {}),
+        ...(Array.isArray(embeddedUrls) ? { embeddedUrls } : {}),
+      },
+    });
   }
 
   async addHtmlPrimitive(input: AddHtmlPrimitiveInput): Promise<AddHtmlPrimitiveResult> {

package/src/mcp/server.ts

@@ -403,10 +403,17 @@ export async function startMcpServer(): Promise<void> {
   // ── canvas_add_html_node ────────────────────────────────────────
   server.tool(
     'canvas_add_html_node',
-    'Add an html node: a self-contained HTML document (with optional inline <script> and CDN <script src="...">) rendered inside a sandboxed iframe (sandbox="allow-scripts"). Use this for moderate-complexity visualizations or interactive widgets that need real JS but do not warrant a full React/shadcn build. The iframe inherits canvas theme tokens via injected CSS custom properties (both --c-* and common --color-* aliases) so authored HTML using var(--color-text-secondary), var(--color-bg), etc. renders cohesively. No same-origin access; no top-navigation; no forms. For declarative-only views with zero JS, prefer canvas_add_json_render_node. For React + shadcn + routing or multi-component apps, use canvas_build_web_artifact.',
+    'Add a normal html node: a self-contained HTML document (with optional inline <script> and CDN <script src="...">) rendered inside a sandboxed iframe (sandbox="allow-scripts"). This is the default HTML surface for reports, widgets, and bespoke visualizations. Presentation mode is opt-in: only pass presentation:true when the user explicitly asks for a deck/fullscreen presentation, or use canvas_add_html_primitive with kind="presentation". The iframe inherits live canvas theme tokens via injected CSS custom properties (both --c-* and common --color-* aliases) so authored HTML using var(--color-text-secondary), var(--color-bg), etc. renders cohesively. No same-origin access; no top-navigation; no forms. For declarative-only views with zero JS, prefer canvas_add_json_render_node. For React + shadcn + routing or multi-component apps, use canvas_build_web_artifact.',
     {
       html: z.string().describe('HTML document or fragment. Full <html>...</html> documents are passed through with theme styles injected into <head>; bare fragments are wrapped in a minimal document. Inline <script> and remote CDN <script src="..."> are allowed.'),
       title: z.string().optional().describe('Node title shown in the canvas titlebar.'),
+      summary: z.string().optional().describe('Agent-readable semantic summary for this HTML node. If omitted, PMX derives one from visible HTML text.'),
+      agentSummary: z.string().optional().describe('Explicit agent-readable summary. Alias for summary with higher priority when both are provided.'),
+      description: z.string().optional().describe('Short description included in search and pinned/spatial context.'),
+      presentation: z.boolean().optional().describe('Marks this HTML surface as a fullscreen presentation/deck. Omit unless the user explicitly requested presentation mode.'),
+      slideTitles: z.array(z.string()).optional().describe('Agent-readable slide titles for presentation HTML.'),
+      embeddedNodeIds: z.array(z.string()).optional().describe('Canvas node IDs embedded or represented by this HTML surface.'),
+      embeddedUrls: z.array(z.string()).optional().describe('URLs embedded or represented by this HTML surface.'),
       x: z.number().optional().describe('X position (auto-placed if omitted).'),
       y: z.number().optional().describe('Y position (auto-placed if omitted).'),
       width: z.number().optional().describe('Width in pixels (default: 720).'),
@@ -420,6 +427,13 @@ export async function startMcpServer(): Promise<void> {
       const id = await c.addHtmlNode({
         html: input.html,
         ...(typeof input.title === 'string' ? { title: input.title } : {}),
+        ...(typeof input.summary === 'string' ? { summary: input.summary } : {}),
+        ...(typeof input.agentSummary === 'string' ? { agentSummary: input.agentSummary } : {}),
+        ...(typeof input.description === 'string' ? { description: input.description } : {}),
+        ...(input.presentation === true ? { presentation: true } : {}),
+        ...(Array.isArray(input.slideTitles) ? { slideTitles: input.slideTitles } : {}),
+        ...(Array.isArray(input.embeddedNodeIds) ? { embeddedNodeIds: input.embeddedNodeIds } : {}),
+        ...(Array.isArray(input.embeddedUrls) ? { embeddedUrls: input.embeddedUrls } : {}),
         ...(typeof input.x === 'number' ? { x: input.x } : {}),
         ...(typeof input.y === 'number' ? { y: input.y } : {}),
         ...(typeof input.width === 'number' ? { width: input.width } : {}),
@@ -434,11 +448,11 @@ export async function startMcpServer(): Promise<void> {
 
   server.tool(
     'canvas_add_html_primitive',
-    'Create a reusable HTML communication primitive as a normal sandboxed html node. Use this instead of long markdown for side-by-side choices, implementation plans, PR review sheets, module maps, design sheets, component galleries, flowcharts, slide decks, explainers, status reports, and throwaway editors with export/copy paths.',
+    'Create a reusable HTML communication primitive as a normal sandboxed html node. Use this instead of long markdown for side-by-side choices, implementation plans, PR review sheets, module maps, design sheets, component galleries, flowcharts, explainers, status reports, and throwaway editors with export/copy paths. Use kind="presentation" only when the user explicitly asks for a PowerPoint-like deck, pitch, briefing, workshop walkthrough, or fullscreen story.',
     {
       kind: htmlPrimitiveKindSchema.describe('Primitive kind. Call canvas_describe_schema and read htmlPrimitives for data shapes and examples.'),
       title: z.string().optional().describe('Node title shown in the canvas titlebar.'),
-      data: z.record(z.string(), z.unknown()).optional().describe('Primitive-specific data payload. See canvas_describe_schema.htmlPrimitives for each shape.'),
+      data: z.record(z.string(), z.unknown()).optional().describe('Primitive-specific data payload. For kind="presentation", data may include theme:"canvas"|"midnight"|"paper"|"aurora" or a custom color object. See canvas_describe_schema.htmlPrimitives for each shape.'),
       x: z.number().optional().describe('X position (auto-placed if omitted).'),
       y: z.number().optional().describe('Y position (auto-placed if omitted).'),
       width: z.number().optional().describe('Width in pixels (defaults per primitive).'),

package/src/server/agent-context.ts

@@ -192,6 +192,18 @@ function metadataForNode(node: CanvasNodeState): Record<string, unknown> | undef
       }
       return Object.keys(metadata).length > 0 ? metadata : undefined;
     }
+    case 'html': {
+      const metadata: Record<string, unknown> = {};
+      for (const key of ['summary', 'description', 'agentSummary', 'contentSummary', 'htmlPrimitive', 'presentation', 'slideCount', 'slideTitles', 'speakerNotes', 'embeddedNodeIds', 'embeddedUrls']) {
+        const value = node.data[key];
+        if (Array.isArray(value)) {
+          if (value.length > 0) metadata[key] = value;
+        } else if (value !== undefined && value !== null && value !== '') {
+          metadata[key] = value;
+        }
+      }
+      return Object.keys(metadata).length > 0 ? metadata : undefined;
+    }
     case 'mcp-app': {
       const metadata: Record<string, unknown> = {};
       for (const key of ['url', 'path', 'mode', 'hostMode', 'viewerType', 'serverName', 'toolName', 'resourceUri', 'sessionStatus', 'projectPath', 'artifactBytes', 'sourceFiles', 'sourceFileCount', 'deps']) {
@@ -245,10 +257,20 @@ export function summarizeNodeForAgentContext(
       return stringifyContextValue(node.data.spec ?? {}, defaultTextLength);
     }
     case 'html': {
+      if (typeof node.data.agentSummary === 'string') {
+        return truncateContextText(node.data.agentSummary, defaultTextLength);
+      }
       if (typeof node.data.htmlPrimitive === 'string') {
         return summarizeHtmlPrimitiveData(node.data, defaultTextLength);
       }
-      return stringifyContextValue({ title: node.data.title, description: node.data.description }, defaultTextLength);
+      return stringifyContextValue({
+        title: node.data.title,
+        description: node.data.description,
+        summary: node.data.summary,
+        contentSummary: node.data.contentSummary,
+        embeddedNodeIds: node.data.embeddedNodeIds,
+        embeddedUrls: node.data.embeddedUrls,
+      }, defaultTextLength);
     }
     case 'prompt':
     case 'response': {

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 } : {}),
@@ -1552,8 +1557,16 @@ export async function executeCanvasBatch(
             };
           } else {
             const data = isPlainRecord(args.data) ? args.data : {};
-            const htmlData = type === 'html' && typeof args.html === 'string'
-              ? { ...data, html: args.html }
+            const htmlData = type === 'html'
+              ? {
+                  ...data,
+                  ...(typeof args.html === 'string' ? { html: args.html } : {}),
+                  ...(typeof args.summary === 'string' ? { summary: args.summary } : {}),
+                  ...(typeof args.agentSummary === 'string' ? { agentSummary: args.agentSummary } : {}),
+                  ...(typeof args.description === 'string' ? { description: args.description } : {}),
+                  ...(Array.isArray(args.embeddedNodeIds) ? { embeddedNodeIds: args.embeddedNodeIds } : {}),
+                  ...(Array.isArray(args.embeddedUrls) ? { embeddedUrls: args.embeddedUrls } : {}),
+                }
               : data;
             const created = addCanvasNode({
               type: type as CanvasNodeState['type'],