pmx-canvas 0.1.26 → 0.1.27

package/src/json-render/charts/tufte-definitions.ts

@@ -0,0 +1,128 @@
+/**
+ * Definitions for the Tufte primitive chart components in ./tufte-components.tsx.
+ *
+ * Kept separate from ./definitions.ts and ./extra-definitions.ts so the
+ * original chart catalogs stay untouched and the merge in ./catalog.ts is the
+ * only contact surface.
+ */
+
+import { z } from 'zod';
+
+export const tufteChartComponentDefinitions = {
+  Sparkline: {
+    props: z.object({
+      title: z.string().nullable(),
+      data: z.array(z.record(z.string(), z.unknown())),
+      valueKey: z.string(),
+      color: z.string().nullable(),
+      fill: z.boolean().nullable(),
+      showEndDot: z.boolean().nullable(),
+      showMinMax: z.boolean().nullable(),
+      showValue: z.boolean().nullable(),
+      height: z.number().nullable(),
+    }),
+    description:
+      'Word-sized sparkline: a single trend line with no axes, grid, or labels. Optional end dot, min/max markers, light area fill, and an inline last value. The canonical Tufte primitive for showing a trajectory in minimal space.',
+    example: {
+      title: 'Latency p95',
+      data: [{ t: 0, ms: 120 }, { t: 1, ms: 138 }, { t: 2, ms: 117 }, { t: 3, ms: 152 }, { t: 4, ms: 109 }],
+      valueKey: 'ms',
+      color: null,
+      fill: true,
+      showEndDot: true,
+      showMinMax: false,
+      showValue: true,
+      height: null,
+    },
+  },
+
+  DotPlot: {
+    props: z.object({
+      title: z.string().nullable(),
+      data: z.array(z.record(z.string(), z.unknown())),
+      labelKey: z.string(),
+      valueKey: z.string(),
+      color: z.string().nullable(),
+      sort: z.enum(['asc', 'desc', 'none']).nullable(),
+      height: z.number().nullable(),
+    }),
+    description:
+      'Cleveland dot plot: categorical labels down the Y axis, one dot per category positioned by value on X. Higher data-ink ratio than a bar chart for ranked comparison. Sorts descending by default.',
+    example: {
+      title: 'Build time by package',
+      data: [
+        { pkg: 'core', seconds: 42 },
+        { pkg: 'client', seconds: 31 },
+        { pkg: 'mcp', seconds: 18 },
+        { pkg: 'cli', seconds: 9 },
+      ],
+      labelKey: 'pkg',
+      valueKey: 'seconds',
+      color: null,
+      sort: 'desc',
+      height: null,
+    },
+  },
+
+  BulletChart: {
+    props: z.object({
+      title: z.string().nullable(),
+      data: z.array(z.record(z.string(), z.unknown())),
+      labelKey: z.string().nullable(),
+      valueKey: z.string(),
+      targetKey: z.string().nullable(),
+      rangesKey: z.string().nullable(),
+      color: z.string().nullable(),
+      height: z.number().nullable(),
+    }),
+    description:
+      "Stephen Few's bullet graph: a measure bar against grayscale qualitative bands with a target tick and per-row scale ticks. Compact KPI-vs-target display. Provide per-row `ranges` (ascending band thresholds) and `target`.",
+    example: {
+      title: 'Quarterly KPIs vs target',
+      data: [
+        { label: 'Revenue', value: 84, target: 90, ranges: [50, 75, 100] },
+        { label: 'NPS', value: 67, target: 60, ranges: [40, 60, 80] },
+        { label: 'Uptime', value: 99, target: 99.9, ranges: [95, 99, 100] },
+      ],
+      labelKey: 'label',
+      valueKey: 'value',
+      targetKey: 'target',
+      rangesKey: 'ranges',
+      color: null,
+      height: null,
+    },
+  },
+
+  Slopegraph: {
+    props: z.object({
+      title: z.string().nullable(),
+      data: z.array(z.record(z.string(), z.unknown())),
+      labelKey: z.string(),
+      beforeKey: z.string(),
+      afterKey: z.string(),
+      beforeLabel: z.string().nullable(),
+      afterLabel: z.string().nullable(),
+      color: z.string().nullable(),
+      colorByDirection: z.boolean().nullable(),
+      height: z.number().nullable(),
+    }),
+    description:
+      "Tufte slopegraph: two value columns (before/after) with a connecting line per category. Lines use one neutral ink by default; set colorByDirection to accent rising lines and mute falling ones. Ideal for paired change across many items.",
+    example: {
+      title: 'Coverage before/after refactor',
+      data: [
+        { module: 'auth', before: 62, after: 81 },
+        { module: 'canvas', before: 74, after: 78 },
+        { module: 'mcp', before: 55, after: 49 },
+      ],
+      labelKey: 'module',
+      beforeKey: 'before',
+      afterKey: 'after',
+      beforeLabel: 'Before',
+      afterLabel: 'After',
+      color: null,
+      colorByDirection: null,
+      height: null,
+    },
+  },
+} as const;

package/src/json-render/directives.ts

@@ -0,0 +1,29 @@
+/**
+ * Custom json-render directives available in PMX Canvas specs.
+ *
+ * Directives let agent specs declare formatting/derivation ($format, $math,
+ * $concat, $count, $truncate, $pluralize, $join) instead of pre-formatting
+ * strings. Registered into the iframe renderer via <JSONUIProvider directives>.
+ */
+import type { DirectiveDefinition } from '@json-render/core';
+import { standardDirectives } from '@json-render/directives';
+
+/**
+ * Directives enabled in the PMX Canvas viewer. `standardDirectives` covers the
+ * seven stateless directives. The $t i18n directive is intentionally omitted —
+ * it is a factory requiring locale config and PMX Canvas has no locale source.
+ */
+export const pmxCanvasDirectives: DirectiveDefinition[] = [...standardDirectives];
+
+/**
+ * True when a prop value is a render-time dynamic expression — a directive
+ * (`$format`/`$math`/…) or an existing binding (`$state`/`$item`/`$bindItem`/
+ * `$cond`/`$template`/`$computed`). These objects are resolved inside the
+ * renderer, so the server-side validators must leave them untouched instead of
+ * string-coercing them to `"[object Object]"` or rejecting them as the wrong
+ * primitive type.
+ */
+export function isDynamicPropValue(value: unknown): boolean {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  return Object.keys(value as Record<string, unknown>).some((key) => key.startsWith('$'));
+}

package/src/json-render/renderer/index.css

@@ -204,6 +204,65 @@ button {
   color: var(--destructive);
 }
 
+.pmx-button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.5rem;
+  height: 2.25rem;
+  padding: 0.5rem 1rem;
+  border: 1px solid transparent;
+  border-radius: var(--radius);
+  font-size: 0.875rem;
+  font-weight: 500;
+  line-height: 1.25rem;
+  white-space: nowrap;
+  cursor: pointer;
+  transition: background-color 0.15s ease, border-color 0.15s ease, opacity 0.15s ease;
+}
+
+.pmx-button:disabled {
+  pointer-events: none;
+  opacity: 0.5;
+}
+
+.pmx-button--primary {
+  background: var(--primary);
+  color: var(--primary-foreground);
+}
+
+.pmx-button--secondary {
+  background: var(--secondary);
+  color: var(--secondary-foreground);
+}
+
+.pmx-button--destructive,
+.pmx-button--danger {
+  background: var(--destructive);
+  color: var(--destructive-foreground);
+}
+
+.pmx-button--success {
+  background: var(--chart-2);
+  color: var(--primary-foreground);
+}
+
+.pmx-button--outline {
+  border-color: var(--border);
+  background: transparent;
+  color: var(--foreground);
+}
+
+.pmx-button--ghost {
+  background: transparent;
+  color: var(--foreground);
+}
+
+.pmx-button--ghost:hover,
+.pmx-button--outline:hover {
+  background: color-mix(in oklch, var(--foreground) 8%, transparent);
+}
+
 /* -- Chart components -- */
 
 .pmx-chart {
@@ -225,6 +284,48 @@ button {
   min-width: 360px;
 }
 
+.pmx-chart--dot-plot,
+.pmx-chart--bullet,
+.pmx-chart--slopegraph {
+  min-width: 320px;
+}
+
+.pmx-chart--sparkline {
+  min-width: 160px;
+  padding: 0.25rem 0;
+}
+
+.pmx-chart__sparkline-row {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.pmx-chart__sparkline-svg {
+  display: block;
+  width: 100%;
+  height: 36px;
+}
+
+.pmx-chart__sparkline-value {
+  font-size: 0.8125rem;
+  font-weight: 600;
+  font-variant-numeric: tabular-nums;
+  white-space: nowrap;
+}
+
+.pmx-chart__dot-plot-svg,
+.pmx-chart__bullet-svg,
+.pmx-chart__slopegraph-svg {
+  display: block;
+}
+
+.pmx-chart--dot-plot text,
+.pmx-chart--bullet text,
+.pmx-chart--slopegraph text {
+  font-variant-numeric: tabular-nums;
+}
+
 .pmx-chart__title {
   font-size: 0.875rem;
   font-weight: 600;

package/src/json-render/renderer/index.tsx

@@ -14,6 +14,9 @@ import { shadcnComponents } from '@json-render/shadcn';
 import { catalog } from '../catalog';
 import { chartComponents } from '../charts/components';
 import { extraChartComponents } from '../charts/extra-components';
+import { tufteChartComponents } from '../charts/tufte-components';
+import { pmxCanvasDirectives } from '../directives';
+import { JsonRenderDevtools } from '@json-render/devtools-react';
 
 type BadgeVariant = 'default' | 'secondary' | 'destructive' | 'outline' | 'success' | 'info' | 'warning' | 'error' | 'danger';
 type BadgeProps = {
@@ -36,12 +39,37 @@ function Badge({ props }: { props: BadgeProps }) {
   );
 }
 
+type ButtonVariant = 'primary' | 'secondary' | 'destructive' | 'danger' | 'outline' | 'ghost' | 'success';
+type ButtonProps = {
+  label: string;
+  variant?: ButtonVariant | null;
+  disabled?: boolean | null;
+};
+
+function Button({ props, emit }: { props: ButtonProps; emit: (event: string) => void }) {
+  const resolvedVariant = props.variant ?? 'primary';
+  return (
+    <button
+      type="button"
+      data-slot="button"
+      data-variant={resolvedVariant}
+      className={`pmx-button pmx-button--${resolvedVariant}`}
+      disabled={props.disabled ?? false}
+      onClick={() => emit('press')}
+    >
+      {props.label}
+    </button>
+  );
+}
+
 const { registry } = defineRegistry(catalog as never, {
   components: {
     ...shadcnComponents,
     Badge,
+    Button,
     ...chartComponents,
     ...extraChartComponents,
+    ...tufteChartComponents,
   } as never,
 });
 
@@ -50,6 +78,7 @@ declare global {
     __PMX_CANVAS_JSON_RENDER_SPEC__?: Spec & { state?: Record<string, unknown> };
     __PMX_CANVAS_JSON_RENDER_THEME__?: string;
     __PMX_CANVAS_JSON_RENDER_DISPLAY__?: string;
+    __PMX_CANVAS_JSON_RENDER_DEVTOOLS__?: boolean;
   }
 }
 
@@ -95,8 +124,12 @@ function App() {
       <JSONUIProvider
         registry={registry}
         initialState={spec.state ?? undefined}
+        directives={pmxCanvasDirectives}
       >
         <Renderer spec={spec} registry={registry} loading={false} />
+        {window.__PMX_CANVAS_JSON_RENDER_DEVTOOLS__ ? (
+          <JsonRenderDevtools position="right" />
+        ) : null}
       </JSONUIProvider>
     </div>
   );

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 { 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]);
     }
   }
@@ -502,6 +537,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 +682,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 +782,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 +899,7 @@ export async function buildJsonRenderViewerHtml(options: {
   spec: JsonRenderSpec;
   theme?: 'dark' | 'light' | 'high-contrast';
   display?: 'expanded';
+  devtools?: boolean;
 }): Promise<string> {
   try {
     await ensureJsonRenderBundle();
@@ -663,6 +914,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({