pmx-canvas 0.1.20 → 0.1.22

package/src/server/canvas-provenance.ts

@@ -1,4 +1,5 @@
 import { pathToFileURL } from 'node:url';
+import { normalizeHtmlNodeSemanticData } from './html-node-summary.js';
 
 export type CanvasNodeType =
   | 'markdown'
@@ -228,17 +229,18 @@ export function normalizeCanvasNodeData<T extends Record<string, unknown>>(
   nodeType: CanvasNodeType,
   data: T,
 ): T {
-  const existing = normalizeExistingProvenance(data.provenance);
-  const inferred = inferCanvasNodeProvenance(nodeType, data);
+  const semanticData = nodeType === 'html' ? normalizeHtmlNodeSemanticData(data) : data;
+  const existing = normalizeExistingProvenance(semanticData.provenance);
+  const inferred = inferCanvasNodeProvenance(nodeType, semanticData);
   const provenance = mergeProvenance(existing, inferred);
 
   if (provenance) {
-    return { ...data, provenance } as T;
+    return { ...semanticData, provenance } as T;
   }
-  if ('provenance' in data) {
-    const nextData = { ...data };
+  if ('provenance' in semanticData) {
+    const nextData = { ...semanticData };
     delete nextData.provenance;
     return nextData as T;
   }
-  return data;
+  return semanticData;
 }

package/src/server/canvas-schema.ts

@@ -243,6 +243,12 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     mcpTool: 'canvas_add_html_node',
     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.', 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.', 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.' },
@@ -259,6 +265,9 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     },
     notes: [
       'The CLI accepts --content as an alias and stores it as data.html so the renderer can load it.',
+      'Normal html nodes are the default. Presentation mode is opt-in via presentation:true or the presentation primitive.',
+      'HTML nodes persist data.contentSummary and data.agentSummary so agents can understand rich visual HTML without parsing the full iframe payload.',
+      'Only presentation-marked HTML nodes expose a browser Present button for fullscreen review; use the presentation primitive for PowerPoint-like decks.',
       'Use `primitive` / `kind` with `data` to create reusable agent communication artifacts such as choice grids, plans, review sheets, explainers, and editors.',
       'HTML runs in a sandboxed iframe without same-origin access to the canvas host.',
     ],
@@ -291,6 +300,8 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     },
     notes: [
       'HTTP callers may POST { type: "html-primitive", kind, data } or { type: "html", primitive: kind, data }; both create a normal html node with primitive metadata.',
+      'Use kind "presentation" only when a PowerPoint-like deck is requested; created nodes persist presentation, slideCount, slideTitles, and optional presentationTheme metadata for agents.',
+      'Presentation primitive data supports theme: "canvas" | "midnight" | "paper" | "aurora" or a custom color object with bg, panel, surface, border, text, textSecondary, textMuted, accent, and colorScheme.',
       'Interactive editor primitives include copy/export controls so the human can send edited state back to the agent.',
     ],
   },

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;
 }
@@ -76,10 +83,14 @@ export function getCanvasNodeTitle(node: CanvasNodeState): string | null {
 }
 
 export function getCanvasNodeContent(node: CanvasNodeState): string | null {
-  if (node.type === 'html' && typeof node.data.htmlPrimitive === 'string') {
-    const primitive = node.data.htmlPrimitive;
+  if (node.type === 'html') {
+    const primitive = typeof node.data.htmlPrimitive === 'string' ? node.data.htmlPrimitive : null;
     const description = pickString(node.data.description);
-    return description ? `${primitive}: ${description}` : primitive;
+    return pickString(node.data.agentSummary)
+      ?? pickString(node.data.contentSummary)
+      ?? (primitive
+        ? (description ? `${primitive}: ${description}` : primitive)
+        : null);
   }
   return pickString(node.data.content)
     ?? pickString(node.data.fileContent)
@@ -92,12 +103,13 @@ export function getCanvasNodeContent(node: CanvasNodeState): string | null {
 
 export function serializeCanvasNode(node: CanvasNodeState): SerializedCanvasNode {
   const data = normalizeCanvasNodeData(node.type, node.data);
+  const normalizedNode = { ...node, data };
   return {
     ...node,
     data,
     kind: getCanvasNodeKind(node, data),
-    title: getCanvasNodeTitle(node),
-    content: getCanvasNodeContent(node),
+    title: getCanvasNodeTitle(normalizedNode),
+    content: getCanvasNodeContent(normalizedNode),
     path: pickString(data.path),
     url: pickString(data.url),
     provenance: pickProvenance(data.provenance),
@@ -137,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-node-summary.ts

@@ -0,0 +1,141 @@
+const HTML_CONTENT_SUMMARY_MAX_LENGTH = 900;
+const HTML_AGENT_SUMMARY_MAX_LENGTH = 1200;
+const HTML_REFERENCE_LIMIT = 12;
+
+function pickString(value: unknown): string | null {
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
+}
+
+function strings(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.filter((item): item is string => typeof item === 'string' && item.trim().length > 0)
+    : [];
+}
+
+function truncateText(value: string, maxLength: number): string {
+  if (value.length <= maxLength) return value;
+  return `${value.slice(0, Math.max(0, maxLength - 3)).trimEnd()}...`;
+}
+
+function normalizeWhitespace(value: string): string {
+  return value.replace(/\s+/g, ' ').trim();
+}
+
+function decodeHtmlEntities(value: string): string {
+  const named: Record<string, string> = {
+    amp: '&',
+    gt: '>',
+    lt: '<',
+    nbsp: ' ',
+    quot: '"',
+    apos: "'",
+  };
+  return value.replace(/&(#x?[0-9a-f]+|[a-z]+);/gi, (match, entity) => {
+    const lower = entity.toLowerCase();
+    if (lower.startsWith('#x')) {
+      const codePoint = Number.parseInt(lower.slice(2), 16);
+      return Number.isInteger(codePoint) && codePoint >= 0 && codePoint <= 0x10ffff ? String.fromCodePoint(codePoint) : match;
+    }
+    if (lower.startsWith('#')) {
+      const codePoint = Number.parseInt(lower.slice(1), 10);
+      return Number.isInteger(codePoint) && codePoint >= 0 && codePoint <= 0x10ffff ? String.fromCodePoint(codePoint) : match;
+    }
+    return named[lower] ?? match;
+  });
+}
+
+export function summarizeHtmlText(html: string): string | null {
+  const withoutNoise = html
+    .replace(/<!--[\s\S]*?-->/g, ' ')
+    .replace(/<script\b[\s\S]*?<\/script>/gi, ' ')
+    .replace(/<style\b[\s\S]*?<\/style>/gi, ' ')
+    .replace(/<noscript\b[\s\S]*?<\/noscript>/gi, ' ');
+  const text = withoutNoise
+    .replace(/<(?:h[1-6]|p|li|br|div|section|article|header|footer|main|aside|summary|figcaption|blockquote|tr|td|th)\b[^>]*>/gi, '\n')
+    .replace(/<[^>]+>/g, ' ');
+  const normalized = normalizeWhitespace(decodeHtmlEntities(text));
+  return normalized.length > 0 ? truncateText(normalized, HTML_CONTENT_SUMMARY_MAX_LENGTH) : null;
+}
+
+function uniqueLimited(values: string[]): string[] {
+  const seen = new Set<string>();
+  const unique: string[] = [];
+  for (const value of values) {
+    const trimmed = value.trim();
+    if (!trimmed || seen.has(trimmed)) continue;
+    seen.add(trimmed);
+    unique.push(trimmed);
+    if (unique.length >= HTML_REFERENCE_LIMIT) break;
+  }
+  return unique;
+}
+
+function extractHtmlNodeIds(html: string): string[] {
+  const ids: string[] = [];
+  for (const match of html.matchAll(/\b(?:node|graph|json-render|web-artifact|mcp-app|group)-[a-z0-9-]+\b/gi)) {
+    ids.push(match[0]);
+  }
+  return uniqueLimited(ids);
+}
+
+function extractHtmlUrls(html: string): string[] {
+  const urls: string[] = [];
+  for (const match of html.matchAll(/\b(?:src|href)\s*=\s*["']([^"']+)["']/gi)) {
+    const url = match[1]?.trim();
+    if (!url) continue;
+    if (/^(?:https?:)?\/\//i.test(url) || url.startsWith('/') || url.startsWith('ui://')) {
+      urls.push(url);
+    }
+  }
+  return uniqueLimited(urls);
+}
+
+function joinSummaryParts(parts: string[]): string | null {
+  const summary = parts
+    .map((part) => part.trim())
+    .filter(Boolean)
+    .filter((part, index, all) => all.findIndex((candidate) => candidate === part) === index)
+    .join('\n');
+  return summary ? truncateText(summary, HTML_AGENT_SUMMARY_MAX_LENGTH) : null;
+}
+
+export function normalizeHtmlNodeSemanticData<T extends Record<string, unknown>>(data: T): T {
+  const {
+    agentSummary: _agentSummary,
+    contentSummary: _contentSummary,
+    embeddedNodeIds: _embeddedNodeIds,
+    embeddedUrls: _embeddedUrls,
+    embeddedNodeId: _embeddedNodeId,
+    embeddedGraphId: _embeddedGraphId,
+    sourceNodeId: _sourceNodeId,
+    ...base
+  } = data;
+
+  const html = pickString(base.html);
+  const explicitSummary = pickString(base.summary) ?? pickString(base.description);
+  const primitive = pickString(base.htmlPrimitive);
+  const contentSummary = html ? summarizeHtmlText(html) : null;
+  const explicitNodeIds = [
+    ...strings(data.embeddedNodeIds),
+    pickString(data.embeddedNodeId),
+    pickString(data.embeddedGraphId),
+    pickString(data.sourceNodeId),
+  ].filter((value): value is string => value !== null);
+  const embeddedNodeIds = uniqueLimited([...explicitNodeIds, ...(html ? extractHtmlNodeIds(html) : [])]);
+  const embeddedUrls = uniqueLimited([...strings(data.embeddedUrls), ...(html ? extractHtmlUrls(html) : [])]);
+  const agentSummary = pickString(data.agentSummary) ?? joinSummaryParts([
+    primitive ? `HTML primitive: ${primitive}` : '',
+    explicitSummary ?? '',
+    contentSummary ?? '',
+    embeddedNodeIds.length > 0 ? `Embedded canvas nodes: ${embeddedNodeIds.join(', ')}` : '',
+    embeddedUrls.length > 0 ? `Embedded URLs: ${embeddedUrls.join(', ')}` : '',
+  ]);
+
+  return {
+    ...base,
+    ...(contentSummary ? { contentSummary } : {}),
+    ...(agentSummary ? { agentSummary } : {}),
+    ...(embeddedNodeIds.length > 0 ? { embeddedNodeIds } : {}),
+    ...(embeddedUrls.length > 0 ? { embeddedUrls } : {}),
+  } as T;
+}