pmx-canvas 0.1.26 → 0.1.28

package/src/json-render/server.ts

@@ -2,7 +2,9 @@ import { spawn } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { buildAppHtml } from '@json-render/mcp/build-app-html';
+import { applySpecPatch, parseSpecStreamLine, type Spec, type SpecStreamLine } from '@json-render/core';
 import { allComponentDefinitions, catalog, validateShadcnElementProps, type JsonRenderIssue } from './catalog.js';
+import { findUnknownDirectiveKey, isDynamicPropValue } from './directives.js';
 
 export interface JsonRenderSpec {
   root: string;
@@ -36,8 +38,23 @@ export interface GraphNodeInput {
   lineKey?: string;
   aggregate?: 'sum' | 'count' | 'avg';
   color?: string;
+  colorBy?: 'series' | 'category' | 'value' | 'none';
+  highlight?: number | 'max' | 'min' | null;
   barColor?: string;
   lineColor?: string;
+  labelKey?: string;
+  beforeKey?: string;
+  afterKey?: string;
+  beforeLabel?: string;
+  afterLabel?: string;
+  targetKey?: string;
+  rangesKey?: string;
+  sort?: 'asc' | 'desc' | 'none';
+  fill?: boolean;
+  showEndDot?: boolean;
+  showMinMax?: boolean;
+  showValue?: boolean;
+  colorByDirection?: boolean;
   height?: number;
   showLegend?: boolean;
   showLabels?: boolean;
@@ -59,7 +76,11 @@ export type GraphChartType =
   | 'ScatterChart'
   | 'RadarChart'
   | 'StackedBarChart'
-  | 'ComposedChart';
+  | 'ComposedChart'
+  | 'Sparkline'
+  | 'DotPlot'
+  | 'BulletChart'
+  | 'Slopegraph';
 
 const GRAPH_TYPE_ALIASES: Record<string, GraphChartType> = {
   line: 'LineChart',
@@ -84,6 +105,15 @@ const GRAPH_TYPE_ALIASES: Record<string, GraphChartType> = {
   composedchart: 'ComposedChart',
   combo: 'ComposedChart',
   combochart: 'ComposedChart',
+  sparkline: 'Sparkline',
+  spark: 'Sparkline',
+  dotplot: 'DotPlot',
+  dot: 'DotPlot',
+  cleveland: 'DotPlot',
+  bullet: 'BulletChart',
+  bulletchart: 'BulletChart',
+  slopegraph: 'Slopegraph',
+  slope: 'Slopegraph',
 };
 
 const COERCIBLE_STRING_PROPS = [
@@ -316,7 +346,12 @@ function normalizeElementProps(
   const props = (stripNullishDeep(rawProps) as Record<string, unknown> | undefined) ?? {};
 
   for (const key of COERCIBLE_STRING_PROPS) {
-    if (key in props && typeof props[key] !== 'string' && props[key] !== undefined) {
+    if (
+      key in props &&
+      typeof props[key] !== 'string' &&
+      props[key] !== undefined &&
+      !isDynamicPropValue(props[key])
+    ) {
       props[key] = String(props[key]);
     }
   }
@@ -477,6 +512,24 @@ export function normalizeAndValidateJsonRenderSpec(spec: unknown): JsonRenderSpe
     throw new Error('Missing root and elements in spec. Pass a complete {root, elements} document, or a single bare component object with a type field.');
   }
 
+  // Reject an unrecognized $-keyed expression object in any element prop BEFORE
+  // normalization can string-coerce it to "[object Object]" (the reported $path
+  // symptom). The error names the offending key and points at $state, the
+  // correct path-read binding.
+  const elementsRecord = asRecord(specRecord.elements) ?? {};
+  for (const [elementKey, rawElement] of Object.entries(elementsRecord)) {
+    const props = asRecord(asRecord(rawElement)?.props);
+    if (!props) continue;
+    for (const [propKey, propValue] of Object.entries(props)) {
+      const unknownKey = findUnknownDirectiveKey(propValue);
+      if (unknownKey) {
+        throw new Error(
+          `Unknown directive "${unknownKey}" on elements.${elementKey}.props.${propKey}. Valid directives are $format, $math, $concat, $count, $truncate, $pluralize, $join; to read a value from state by path use { "$state": "/path" } (there is no $path directive).`,
+        );
+      }
+    }
+  }
+
   const normalizedSpec = normalizeSpec(specRecord);
   const validation = catalog.validate(normalizedSpec);
   if (!validation.success || !validation.data) {
@@ -502,6 +555,86 @@ function inferKeysFromData(data: Array<Record<string, unknown>>, exclude: string
   return Object.keys(first).filter((key) => !exclude.includes(key));
 }
 
+function collectDataKeys(data: Array<Record<string, unknown>>): Set<string> {
+  const keys = new Set<string>();
+  for (const row of data) {
+    for (const key of Object.keys(row)) keys.add(key);
+  }
+  return keys;
+}
+
+function assertGraphDataKeys(
+  data: Array<Record<string, unknown>>,
+  chartType: GraphChartType,
+  chartProps: Record<string, unknown>,
+): void {
+  if (data.length === 0) return;
+  const available = collectDataKeys(data);
+  const required = new Set<string>();
+
+  const addString = (value: unknown): void => {
+    if (typeof value === 'string' && value.length > 0) required.add(value);
+  };
+  const addStringList = (value: unknown): void => {
+    if (!Array.isArray(value)) return;
+    for (const item of value) addString(item);
+  };
+
+  switch (chartType) {
+    case 'PieChart':
+      addString(chartProps.nameKey);
+      addString(chartProps.valueKey);
+      break;
+    case 'ScatterChart':
+      addString(chartProps.xKey);
+      addString(chartProps.yKey);
+      addString(chartProps.zKey);
+      break;
+    case 'RadarChart':
+      addString(chartProps.axisKey);
+      addStringList(chartProps.metrics);
+      break;
+    case 'StackedBarChart':
+      addString(chartProps.xKey);
+      addStringList(chartProps.series);
+      break;
+    case 'ComposedChart':
+      addString(chartProps.xKey);
+      addString(chartProps.barKey);
+      addString(chartProps.lineKey);
+      break;
+    case 'Sparkline':
+      addString(chartProps.valueKey);
+      break;
+    case 'DotPlot':
+      addString(chartProps.labelKey);
+      addString(chartProps.valueKey);
+      break;
+    case 'BulletChart':
+      addString(chartProps.labelKey);
+      addString(chartProps.valueKey);
+      addString(chartProps.targetKey);
+      addString(chartProps.rangesKey);
+      break;
+    case 'Slopegraph':
+      addString(chartProps.labelKey);
+      addString(chartProps.beforeKey);
+      addString(chartProps.afterKey);
+      break;
+    case 'AreaChart':
+    case 'BarChart':
+    case 'LineChart':
+      addString(chartProps.xKey);
+      addString(chartProps.yKey);
+      break;
+  }
+
+  const missing = [...required].filter((key) => !available.has(key));
+  if (missing.length === 0) return;
+  const availableList = [...available].sort().join(', ') || '(none)';
+  throw new Error(`Graph data key mismatch for ${chartType}: missing ${missing.join(', ')}. Available keys: ${availableList}.`);
+}
+
 export function buildGraphSpec(input: GraphNodeInput): JsonRenderSpec {
   const title = input.title?.trim() || 'Graph';
   const chartType = normalizeGraphType(input.graphType);
@@ -567,18 +700,66 @@ export function buildGraphSpec(input: GraphNodeInput): JsonRenderSpec {
       chartProps.showLegend = input.showLegend !== false;
       break;
     }
+    case 'BarChart': {
+      const xKey = input.xKey ?? inferKeysFromData(input.data)[0] ?? 'label';
+      const yKey = input.yKey ?? inferKeysFromData(input.data, [xKey])[0] ?? 'value';
+      chartProps.xKey = xKey;
+      chartProps.yKey = yKey;
+      chartProps.aggregate = input.aggregate ?? null;
+      chartProps.color = input.color ?? null;
+      chartProps.colorBy = input.colorBy ?? 'series';
+      chartProps.highlight = input.highlight === undefined ? 'max' : input.highlight;
+      break;
+    }
+    case 'Sparkline': {
+      chartProps.valueKey = input.valueKey ?? input.yKey ?? 'value';
+      chartProps.color = input.color ?? null;
+      chartProps.fill = input.fill ?? null;
+      chartProps.showEndDot = input.showEndDot ?? null;
+      chartProps.showMinMax = input.showMinMax ?? null;
+      chartProps.showValue = input.showValue ?? null;
+      break;
+    }
+    case 'DotPlot': {
+      chartProps.labelKey = input.labelKey ?? input.xKey ?? 'label';
+      chartProps.valueKey = input.valueKey ?? input.yKey ?? 'value';
+      chartProps.color = input.color ?? null;
+      chartProps.sort = input.sort ?? null;
+      break;
+    }
+    case 'BulletChart': {
+      chartProps.labelKey = input.labelKey ?? input.xKey ?? null;
+      chartProps.valueKey = input.valueKey ?? input.yKey ?? 'value';
+      chartProps.targetKey = input.targetKey ?? null;
+      chartProps.rangesKey = input.rangesKey ?? null;
+      chartProps.color = input.color ?? null;
+      break;
+    }
+    case 'Slopegraph': {
+      chartProps.labelKey = input.labelKey ?? 'label';
+      chartProps.beforeKey = input.beforeKey ?? 'before';
+      chartProps.afterKey = input.afterKey ?? 'after';
+      chartProps.beforeLabel = input.beforeLabel ?? null;
+      chartProps.afterLabel = input.afterLabel ?? null;
+      chartProps.color = input.color ?? null;
+      chartProps.colorByDirection = input.colorByDirection ?? null;
+      break;
+    }
     case 'AreaChart':
     case 'LineChart':
-    case 'BarChart':
     default: {
-      chartProps.xKey = input.xKey ?? 'label';
-      chartProps.yKey = input.yKey ?? 'value';
+      const xKey = input.xKey ?? inferKeysFromData(input.data)[0] ?? 'label';
+      const yKey = input.yKey ?? inferKeysFromData(input.data, [xKey])[0] ?? 'value';
+      chartProps.xKey = xKey;
+      chartProps.yKey = yKey;
       chartProps.aggregate = input.aggregate ?? null;
       chartProps.color = input.color ?? null;
       break;
     }
   }
 
+  assertGraphDataKeys(input.data, chartType, chartProps);
+
   return normalizeAndValidateJsonRenderSpec({
     root: 'card',
     elements: {
@@ -619,14 +800,101 @@ export function buildGraphConfig(input: GraphNodeInput): Record<string, unknown>
     ...(input.lineKey ? { lineKey: input.lineKey } : {}),
     ...(input.aggregate ? { aggregate: input.aggregate } : {}),
     ...(input.color ? { color: input.color } : {}),
+    ...(input.colorBy ? { colorBy: input.colorBy } : {}),
+    ...(input.highlight !== undefined ? { highlight: input.highlight } : {}),
     ...(input.barColor ? { barColor: input.barColor } : {}),
     ...(input.lineColor ? { lineColor: input.lineColor } : {}),
+    ...(input.labelKey ? { labelKey: input.labelKey } : {}),
+    ...(input.beforeKey ? { beforeKey: input.beforeKey } : {}),
+    ...(input.afterKey ? { afterKey: input.afterKey } : {}),
+    ...(input.beforeLabel ? { beforeLabel: input.beforeLabel } : {}),
+    ...(input.afterLabel ? { afterLabel: input.afterLabel } : {}),
+    ...(input.targetKey ? { targetKey: input.targetKey } : {}),
+    ...(input.rangesKey ? { rangesKey: input.rangesKey } : {}),
+    ...(input.sort ? { sort: input.sort } : {}),
+    ...(typeof input.fill === 'boolean' ? { fill: input.fill } : {}),
+    ...(typeof input.showEndDot === 'boolean' ? { showEndDot: input.showEndDot } : {}),
+    ...(typeof input.showMinMax === 'boolean' ? { showMinMax: input.showMinMax } : {}),
+    ...(typeof input.showValue === 'boolean' ? { showValue: input.showValue } : {}),
+    ...(typeof input.colorByDirection === 'boolean' ? { colorByDirection: input.colorByDirection } : {}),
     ...(typeof input.height === 'number' ? { height: input.height } : {}),
     ...(typeof input.showLegend === 'boolean' ? { showLegend: input.showLegend } : {}),
     ...(typeof input.showLabels === 'boolean' ? { showLabels: input.showLabels } : {}),
   };
 }
 
+/** The minimal spec a streaming json-render node starts from before any patches. */
+export function emptyStreamingSpec(): JsonRenderSpec {
+  return { root: '', elements: {} };
+}
+
+const UNSAFE_PATCH_SEGMENTS = new Set(['__proto__', 'constructor', 'prototype']);
+
+/**
+ * Reject JSON-Pointer paths that would let a streamed patch reach a prototype
+ * chain (`__proto__`/`constructor`/`prototype`). The upstream applySpecPatch
+ * walks the path with plain property assignment and has no such guard, so an
+ * agent-supplied patch like `{op:'add',path:'/__proto__/x',value:...}` would
+ * otherwise pollute Object.prototype server-side. Segments are JSON-Pointer
+ * escaped (`~1`->`/`, `~0`->`~`); decode before comparing.
+ */
+function isSafePatchPath(path: string): boolean {
+  for (const rawSegment of path.split('/')) {
+    const segment = rawSegment.replace(/~1/g, '/').replace(/~0/g, '~');
+    if (UNSAFE_PATCH_SEGMENTS.has(segment)) return false;
+  }
+  return true;
+}
+
+/** Accept a SpecStream item as either a raw JSONL line or a JSON-Patch object. */
+function coerceStreamPatch(item: unknown): SpecStreamLine | null {
+  const patch = (() => {
+    if (typeof item === 'string') return parseSpecStreamLine(item);
+    if (item && typeof item === 'object' && !Array.isArray(item)) {
+      const record = item as Record<string, unknown>;
+      if (typeof record.op === 'string' && typeof record.path === 'string') {
+        return item as SpecStreamLine;
+      }
+    }
+    return null;
+  })();
+  if (!patch || typeof patch.path !== 'string' || !isSafePatchPath(patch.path)) return null;
+  return patch;
+}
+
+/**
+ * Apply a batch of SpecStream patches to the current spec, accumulating the
+ * result. The canvas is the source of truth — patches are applied server-side
+ * and the browser only renders the current accumulated spec, so there is no
+ * client-side reconciliation. Tolerant by design: malformed or inapplicable
+ * patches are skipped and counted, never thrown, so a partial stream keeps
+ * building toward the final spec.
+ */
+export function applyJsonRenderStreamPatches(
+  currentSpec: JsonRenderSpec,
+  items: unknown[],
+): { spec: JsonRenderSpec; applied: number; skipped: number } {
+  let spec = currentSpec as Spec;
+  let applied = 0;
+  let skipped = 0;
+  for (const item of items) {
+    const patch = coerceStreamPatch(item);
+    if (!patch) {
+      skipped++;
+      continue;
+    }
+    try {
+      spec = applySpecPatch(spec, patch);
+      applied++;
+    } catch {
+      // Inapplicable patch (e.g. references a not-yet-added element); skip and
+      // keep streaming. A later patch may add the missing target.
+      skipped++;
+    }
+  }
+  return { spec: spec as JsonRenderSpec, applied, skipped };
+}
+
 export function createJsonRenderNodeData(
   nodeId: string,
   title: string,
@@ -649,6 +917,7 @@ export async function buildJsonRenderViewerHtml(options: {
   spec: JsonRenderSpec;
   theme?: 'dark' | 'light' | 'high-contrast';
   display?: 'expanded';
+  devtools?: boolean;
 }): Promise<string> {
   try {
     await ensureJsonRenderBundle();
@@ -663,6 +932,7 @@ export async function buildJsonRenderViewerHtml(options: {
       `window.__PMX_CANVAS_JSON_RENDER_SPEC__ = ${JSON.stringify(options.spec)};`,
       ...(options.theme ? [`window.__PMX_CANVAS_JSON_RENDER_THEME__ = ${JSON.stringify(options.theme)};`] : []),
       ...(options.display ? [`window.__PMX_CANVAS_JSON_RENDER_DISPLAY__ = ${JSON.stringify(options.display)};`] : []),
+      ...(options.devtools ? ['window.__PMX_CANVAS_JSON_RENDER_DEVTOOLS__ = true;'] : []),
       jsBundle,
     ].join('\n');
     return buildAppHtml({