pmx-canvas 0.1.18 → 0.1.20

package/src/server/index.ts

@@ -10,6 +10,7 @@ import { recomputeCodeGraph, buildCodeGraphSummary, formatCodeGraph } from './co
 import {
   addCanvasNode,
   addCanvasEdge,
+  MARKDOWN_NODE_DEFAULT_SIZE,
   applyCanvasNodeUpdates,
   arrangeCanvasNodes,
   clearCanvas,
@@ -39,6 +40,8 @@ import {
 } from './canvas-operations.js';
 import { validateCanvasLayout } from './canvas-validation.js';
 import { describeCanvasSchema, validateStructuredCanvasPayload } from './canvas-schema.js';
+import { buildHtmlPrimitive, isHtmlPrimitiveKind, listHtmlPrimitiveDescriptors } from './html-primitives.js';
+import type { HtmlPrimitiveKind } from './html-primitives.js';
 import {
   buildWebArtifactOnCanvas,
   type WebArtifactBuildInput,
@@ -178,8 +181,8 @@ export class PmxCanvas extends EventEmitter {
     }
     const { id, needsCodeGraphRecompute } = addCanvasNode({
       ...input,
-      defaultWidth: 360,
-      defaultHeight: 200,
+      defaultWidth: input.type === 'markdown' ? MARKDOWN_NODE_DEFAULT_SIZE.width : 360,
+      defaultHeight: input.type === 'markdown' ? MARKDOWN_NODE_DEFAULT_SIZE.height : 200,
       fileMode: 'path',
       ...(input.strictSize ? { strictSize: true } : {}),
     });
@@ -666,6 +669,42 @@ export class PmxCanvas extends EventEmitter {
     return id;
   }
 
+  addHtmlPrimitive(input: {
+    kind: HtmlPrimitiveKind;
+    title?: string;
+    data?: Record<string, unknown>;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    strictSize?: boolean;
+  }): { id: string; kind: HtmlPrimitiveKind; title: string; htmlBytes: number } {
+    const built = buildHtmlPrimitive({
+      kind: input.kind,
+      ...(typeof input.title === 'string' ? { title: input.title } : {}),
+      ...(input.data ? { data: input.data } : {}),
+    });
+    const { id } = addCanvasNode({
+      type: 'html',
+      title: built.title,
+      data: {
+        html: built.html,
+        htmlPrimitive: built.kind,
+        primitiveData: built.data,
+        description: built.summary,
+      },
+      ...(typeof input.x === 'number' ? { x: input.x } : {}),
+      ...(typeof input.y === 'number' ? { y: input.y } : {}),
+      ...(typeof input.width === 'number' ? { width: input.width } : {}),
+      ...(typeof input.height === 'number' ? { height: input.height } : {}),
+      ...(input.strictSize ? { strictSize: true } : {}),
+      defaultWidth: built.defaultSize.width,
+      defaultHeight: built.defaultSize.height,
+    });
+    emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
+    return { id, kind: built.kind, title: built.title, htmlBytes: Buffer.byteLength(built.html, 'utf-8') };
+  }
+
   addGraphNode(input: GraphNodeInput): { id: string; url: string; spec: JsonRenderSpec } {
     const result = createCanvasGraphNode(input);
     emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
@@ -747,6 +786,7 @@ export type { SpatialCluster, SpatialContext, SpatialNeighbor, NodeSpatialInfo }
 export { mutationHistory, diffLayouts, formatDiff } from './mutation-history.js';
 export { recomputeCodeGraph, buildCodeGraphSummary, formatCodeGraph } from './code-graph.js';
 export { describeCanvasSchema, validateStructuredCanvasPayload } from './canvas-schema.js';
+export { buildHtmlPrimitive, isHtmlPrimitiveKind, listHtmlPrimitiveDescriptors } from './html-primitives.js';
 export {
   buildWebArtifactOnCanvas,
   executeWebArtifactBuild,
@@ -771,4 +811,5 @@ export type {
   WebArtifactCanvasOpenResult,
 } from './web-artifacts.js';
 export type { GraphNodeInput, JsonRenderNodeInput, JsonRenderSpec } from '../json-render/server.js';
+export type { HtmlPrimitiveKind, HtmlPrimitiveDescriptor, HtmlPrimitiveInput, HtmlPrimitiveBuildResult } from './html-primitives.js';
 export { traceManager } from './trace-manager.js';

package/src/server/server.ts

@@ -79,6 +79,7 @@ import { validateLocalImageFile } from './image-source.js';
 import {
   addCanvasNode,
   addCanvasEdge,
+  MARKDOWN_NODE_DEFAULT_SIZE,
   applyCanvasNodeUpdates,
   buildStructuredNodeUpdate,
   arrangeCanvasNodes,
@@ -110,6 +111,7 @@ import {
 } from './canvas-operations.js';
 import { validateCanvasLayout } from './canvas-validation.js';
 import { describeCanvasSchema, validateStructuredCanvasPayload } from './canvas-schema.js';
+import { buildHtmlPrimitive, isHtmlPrimitiveKind } from './html-primitives.js';
 import {
   EXCALIDRAW_READ_CHECKPOINT_TOOL,
   EXCALIDRAW_SAVE_CHECKPOINT_TOOL,
@@ -129,6 +131,7 @@ import {
   WEBPAGE_NODE_DEFAULT_SIZE,
   normalizeWebpageUrl,
 } from './webpage-node.js';
+import type { JsonRenderSpec } from '../json-render/server.js';
 
 const DEFAULT_HOST = '127.0.0.1';
 const DEFAULT_PORT = 4313;
@@ -147,6 +150,40 @@ const canvasThemeSetting = (['dark', 'light', 'high-contrast'].includes(process.
   : 'dark');
 let lastWorkbenchContextCardsEnvelope: Record<string, unknown> | null = null;
 
+function normalizeGraphViewerSpec(
+  node: { type: string; data: Record<string, unknown> },
+  spec: JsonRenderSpec,
+  display: string | null,
+): JsonRenderSpec {
+  if (node.type !== 'graph') return spec;
+  const graphConfig = node.data.graphConfig;
+  if (
+    display !== 'expanded' &&
+    graphConfig &&
+    typeof graphConfig === 'object' &&
+    typeof (graphConfig as Record<string, unknown>).height === 'number'
+  ) {
+    return spec;
+  }
+  const chart = spec.elements.chart;
+  if (!chart || typeof chart !== 'object') return spec;
+  const chartRecord = chart as Record<string, unknown>;
+  const props = chartRecord.props;
+  if (!props || typeof props !== 'object' || typeof (props as Record<string, unknown>).height !== 'number') return spec;
+  const nextProps = { ...(props as Record<string, unknown>) };
+  delete nextProps.height;
+  return {
+    ...spec,
+    elements: {
+      ...spec.elements,
+      chart: {
+        ...chartRecord,
+        props: nextProps,
+      },
+    },
+  };
+}
+
 export interface PrimaryWorkbenchEventPayload {
   [key: string]: unknown;
 }
@@ -1238,6 +1275,15 @@ function annotationBounds(points: CanvasAnnotation['points']): CanvasAnnotation[
   return { x: minX, y: minY, width: maxX - minX, height: maxY - minY };
 }
 
+function textAnnotationBounds(point: CanvasAnnotation['points'][number], text: string, width: number): CanvasAnnotation['bounds'] {
+  return {
+    x: point.x,
+    y: point.y - width,
+    width: Math.max(width, text.length * width * 0.62),
+    height: width * 1.2,
+  };
+}
+
 function parseAnnotationPoints(value: unknown): CanvasAnnotation['points'] {
   if (!Array.isArray(value)) return [];
   return value
@@ -1253,31 +1299,41 @@ function parseAnnotationPoints(value: unknown): CanvasAnnotation['points'] {
 
 async function handleCanvasAddAnnotation(req: Request): Promise<Response> {
   const body = await readJson(req);
+  const type = body.type === 'text' ? 'text' : 'freehand';
   const points = parseAnnotationPoints(body.points);
-  if (points.length < 2) {
-    return responseJson({ ok: false, error: 'Annotation requires at least two valid points.' }, 400);
+  if (points.length < (type === 'text' ? 1 : 2)) {
+    return responseJson({ ok: false, error: type === 'text' ? 'Text annotation requires a valid point.' : 'Annotation requires at least two valid points.' }, 400);
   }
 
+  const defaultWidth = type === 'text' ? 24 : 4;
+  const maxWidth = type === 'text' ? 96 : 24;
   const width = typeof body.width === 'number' && Number.isFinite(body.width)
-    ? Math.min(24, Math.max(1, body.width))
-    : 4;
+    ? Math.min(maxWidth, Math.max(1, body.width))
+    : defaultWidth;
   const color = typeof body.color === 'string' && (body.color === 'currentColor' || /^#[0-9a-fA-F]{6}$/.test(body.color))
     ? body.color
     : 'currentColor';
   const label = typeof body.label === 'string' && body.label.trim().length > 0
     ? body.label.trim().slice(0, 160)
     : undefined;
+  const text = type === 'text' && typeof body.text === 'string' && body.text.trim().length > 0
+    ? body.text.trim().slice(0, 240)
+    : undefined;
+  if (type === 'text' && !text) {
+    return responseJson({ ok: false, error: 'Text annotation requires text.' }, 400);
+  }
   const id = typeof body.id === 'string' && body.id.trim().length > 0
     ? body.id.trim().slice(0, 120)
     : `ann-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
   const annotation: CanvasAnnotation = {
     id,
-    type: 'freehand',
+    type,
     points,
-    bounds: annotationBounds(points),
+    bounds: type === 'text' ? textAnnotationBounds(points[0]!, text!, width) : annotationBounds(points),
     color,
     width,
-    ...(label ? { label } : {}),
+    ...(text ? { text } : {}),
+    ...(label ?? text ? { label: label ?? text } : {}),
     createdAt: new Date().toISOString(),
   };
 
@@ -1401,6 +1457,9 @@ async function handleCanvasAddNode(req: Request): Promise<Response> {
         error: 'Node type "web-artifact" is created via POST /api/canvas/web-artifact with appTsx + title.',
       }, 400);
     }
+    if (type === 'html-primitive') {
+      return createCanvasHtmlPrimitiveNode(body);
+    }
     return responseJson({ ok: false, error: `Invalid node type: "${type}".` }, 400);
   }
 
@@ -1408,6 +1467,10 @@ async function handleCanvasAddNode(req: Request): Promise<Response> {
     return createCanvasWebpageNode(body);
   }
 
+  if (type === 'html' && (typeof body.primitive === 'string' || typeof body.kind === 'string')) {
+    return createCanvasHtmlPrimitiveNode(body);
+  }
+
   const extraData = body.data && typeof body.data === 'object' && !Array.isArray(body.data)
     ? body.data as Record<string, unknown>
     : undefined;
@@ -1443,8 +1506,8 @@ async function handleCanvasAddNode(req: Request): Promise<Response> {
       ...(type === 'trace' && typeof body.error === 'string' ? { error: body.error } : {}),
       ...(body.strictSize === true ? { strictSize: true } : {}),
       ...geometry,
-      defaultWidth: type === 'html' ? 720 : 360,
-      defaultHeight: type === 'html' ? 640 : 200,
+      defaultWidth: type === 'html' ? 720 : type === 'markdown' ? MARKDOWN_NODE_DEFAULT_SIZE.width : 360,
+      defaultHeight: type === 'html' ? 640 : type === 'markdown' ? MARKDOWN_NODE_DEFAULT_SIZE.height : 200,
       fileMode: 'auto',
     });
   } catch (error) {
@@ -1462,6 +1525,44 @@ async function handleCanvasAddNode(req: Request): Promise<Response> {
   return responseJson(buildNodeResponse(node));
 }
 
+function createCanvasHtmlPrimitiveNode(body: Record<string, unknown>): Response {
+  const rawKind = typeof body.primitive === 'string' ? body.primitive : body.kind;
+  if (typeof rawKind !== 'string' || !isHtmlPrimitiveKind(rawKind)) {
+    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,
+  });
+  const geometry = resolveCreateGeometry(body);
+  const { node } = addCanvasNode({
+    type: 'html',
+    title: built.title,
+    data: {
+      html: built.html,
+      htmlPrimitive: built.kind,
+      primitiveData: built.data,
+      description: built.summary,
+    },
+    ...(body.strictSize === true ? { strictSize: true } : {}),
+    ...geometry,
+    defaultWidth: built.defaultSize.width,
+    defaultHeight: built.defaultSize.height,
+  });
+  emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
+  return responseJson({
+    ...buildNodeResponse(node),
+    primitive: {
+      kind: built.kind,
+      title: built.title,
+      htmlBytes: Buffer.byteLength(built.html, 'utf-8'),
+      defaultSize: built.defaultSize,
+    },
+  });
+}
+
 // ── Group operations ─────────────────────────────────────────
 async function handleCanvasCreateGroup(req: Request): Promise<Response> {
   const body = await readJson(req);
@@ -1799,8 +1900,8 @@ function handleCanvasDescribeSchema(): Response {
 async function handleCanvasValidateSpec(req: Request): Promise<Response> {
   const body = await readJson(req);
   const rawType = typeof body.type === 'string' ? body.type.trim() : '';
-  if (rawType !== 'json-render' && rawType !== 'graph') {
-    return responseJson({ ok: false, error: 'Validation type must be "json-render" or "graph".' }, 400);
+  if (rawType !== 'json-render' && rawType !== 'graph' && rawType !== 'html-primitive') {
+    return responseJson({ ok: false, error: 'Validation type must be "json-render", "graph", or "html-primitive".' }, 400);
   }
 
   try {
@@ -1815,6 +1916,23 @@ async function handleCanvasValidateSpec(req: Request): Promise<Response> {
       }));
     }
 
+    if (rawType === 'html-primitive') {
+      const kind = typeof body.kind === 'string'
+        ? body.kind
+        : typeof body.primitive === 'string'
+          ? body.primitive
+          : '';
+      const data = isRecord(body.data) ? body.data : {};
+      return responseJson(validateStructuredCanvasPayload({
+        type: 'html-primitive',
+        primitive: {
+          kind,
+          ...(typeof body.title === 'string' ? { title: body.title } : {}),
+          data,
+        },
+      }));
+    }
+
     const data = parseGraphPayloadData(body.data);
     if (!data) {
       return responseJson({ ok: false, error: 'Graph validation requires a data array.' }, 400);
@@ -1976,10 +2094,15 @@ async function handleJsonRenderView(url: URL): Promise<Response> {
     return responseText('json-render node not found', 404);
   }
 
-  const spec = node.data.spec;
-  if (!spec || typeof spec !== 'object') {
+  const rawSpec = node.data.spec;
+  if (!rawSpec || typeof rawSpec !== 'object') {
     return responseText('json-render spec missing', 404);
   }
+  const spec = normalizeGraphViewerSpec(
+    { type: node.type, data: node.data },
+    rawSpec as { root: string; elements: Record<string, unknown>; state?: Record<string, unknown> },
+    url.searchParams.get('display'),
+  );
 
   const themeValue = url.searchParams.get('theme');
   const theme =
@@ -1989,8 +2112,9 @@ async function handleJsonRenderView(url: URL): Promise<Response> {
   const title = (node.data.title as string) || node.id;
   const html = await buildJsonRenderViewerHtml({
     title,
-    spec: spec as { root: string; elements: Record<string, unknown>; state?: Record<string, unknown> },
+    spec,
     ...(theme ? { theme } : {}),
+    ...(url.searchParams.get('display') === 'expanded' ? { display: 'expanded' as const } : {}),
   });
   return new Response(html, {
     headers: {
@@ -4145,6 +4269,8 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
             return responseJson(listCanvasSnapshots({
               limit: parsePositiveIntegerParam(url.searchParams.get('limit')),
               query: url.searchParams.get('q') ?? url.searchParams.get('query') ?? undefined,
+              before: url.searchParams.get('before') ?? undefined,
+              after: url.searchParams.get('after') ?? undefined,
               all: url.searchParams.get('all') === 'true',
             }));
           }

package/src/server/spatial-analysis.ts

@@ -160,7 +160,7 @@ function summarizeAnnotationForSpatialContext(
   );
   return {
     id: annotation.id,
-    label: annotation.label ?? null,
+    label: annotation.label ?? annotation.text ?? null,
     bounds: annotation.bounds,
     targetNodeIds: targetNodes.map((node) => node.id),
     targetNodeTitles,
@@ -312,7 +312,7 @@ export function searchNodes(
 
   for (const node of nodes) {
     const title = ((node.data.title as string) ?? '').toLowerCase();
-    const content = ((node.data.content as string) ?? (node.data.fileContent as string) ?? '').toLowerCase();
+    const content = ((node.data.content as string) ?? (node.data.description as string) ?? (node.data.fileContent as string) ?? '').toLowerCase();
     const path = ((node.data.path as string) ?? '').toLowerCase();
     const description = ((node.data.description as string) ?? '').toLowerCase();
     const url = ((node.data.url as string) ?? '').toLowerCase();
@@ -331,7 +331,7 @@ export function searchNodes(
 
     // Extract a snippet around the first match in content
     let snippet = '';
-    const fullContent = (node.data.content as string) ?? (node.data.fileContent as string) ?? '';
+    const fullContent = (node.data.content as string) ?? (node.data.description as string) ?? (node.data.fileContent as string) ?? '';
     const matchIdx = fullContent.toLowerCase().indexOf(terms[0]);
     if (matchIdx >= 0) {
       const start = Math.max(0, matchIdx - 40);