pmx-canvas 0.1.7 → 0.1.8

package/CHANGELOG.md

@@ -3,6 +3,56 @@
 All notable changes to `pmx-canvas` are documented here. This project follows
 [Semantic Versioning](https://semver.org/).
 
+## [0.1.8] - 2026-04-25
+
+Retest-driven follow-up to 0.1.7. This next release restores compatibility
+for image and json-render node creation, fixes the counter MCP fixture's
+accidental iframe overflow, and syncs packaged testing guidance with the
+canonical repo skill.
+
+### Fixed
+
+- **Image `path` is accepted as a compatibility alias for `content`.**
+  `pmx-canvas node add --type image --path <file>`, HTTP
+  `/api/canvas/node` payloads with `{ type: "image", path }`, and MCP
+  `canvas_add_node({ type: "image", path })` now all validate the file
+  and populate `data.src` instead of creating an empty/broken image node.
+- **json-render creation keeps 0.1.7 compatibility.**
+  `canvas_add_json_render_node`, `POST /api/canvas/json-render`, and
+  CLI `node add --type json-render` accept omitted titles and infer a
+  node title from the root element. Bare legacy component specs like
+  `{ type: "Badge", props: {...} }` are wrapped into a one-element
+  document before validation, while complete `{ root, elements }` specs
+  remain the canonical shape.
+- **Counter MCP fixture no longer creates a scrollable iframe by
+  accident.** The fixture now uses border-box sizing and hides root
+  overflow so `100vh` layouts with padding do not become `100vh +
+  padding`. This removes the observed repeated downward scroll in the
+  counter app and adds browser coverage for zero iframe body overflow.
+
+### Changed
+
+- **Packaged PMX Canvas testing skill is back in sync with canonical
+  guidance.** It now documents that `test:coverage` covers only the Bun
+  unit suite, names the coverage artifact, and calls out the WebView
+  automation timeout caveat used to distinguish environment limits from
+  product regressions.
+- **Schema metadata for the `path` alias and relaxed json-render contract
+  is version-stable.** `canvas_describe_schema` and `canvas://schema`
+  surface the image `path` alias and `title.required: false` on
+  json-render so agents discover the new shapes without reading the
+  CHANGELOG.
+- **Agent-facing `skills/pmx-canvas/SKILL.md` documents the same
+  contract.** The skill now describes the `path` alias for image nodes
+  and the relaxed json-render contract (omitted titles, bare component
+  specs) so agents do not need to retry across shapes.
+
+### Internal
+
+- Regression coverage for image `path` alias handling across CLI/HTTP/MCP,
+  json-render compatibility for omitted titles plus bare component specs,
+  and hosted counter MCP app iframe overflow.
+
 ## [0.1.7] - 2026-04-26
 
 Small retest-driven follow-up to 0.1.6. Three agent-facing ergonomics:
@@ -50,6 +100,7 @@ otherwise have to discover by trial and error.
 - Regression coverage for snapshot flat-`id` aliases on both MCP and
   HTTP surfaces, plus async / top-level-`await` WebView script bodies.
 
+[0.1.8]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.8
 [0.1.7]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.7
 
 ## [0.1.6] - 2026-04-26

package/dist/types/json-render/server.d.ts

@@ -4,7 +4,7 @@ export interface JsonRenderSpec {
     state?: Record<string, unknown>;
 }
 export interface JsonRenderNodeInput {
-    title: string;
+    title?: string;
     spec: unknown;
     x?: number;
     y?: number;
@@ -44,6 +44,7 @@ export declare const GRAPH_NODE_SIZE: {
     height: number;
 };
 export type GraphChartType = 'LineChart' | 'BarChart' | 'PieChart' | 'AreaChart' | 'ScatterChart' | 'RadarChart' | 'StackedBarChart' | 'ComposedChart';
+export declare function inferJsonRenderNodeTitle(spec: JsonRenderSpec, fallback?: string): string;
 export declare function normalizeAndValidateJsonRenderSpec(spec: unknown): JsonRenderSpec;
 export declare function normalizeGraphType(value: string): GraphChartType;
 export declare function buildGraphSpec(input: GraphNodeInput): JsonRenderSpec;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Spatial canvas workbench for coding agents — infinite 2D canvas with agent-native CLI, MCP integration, nodes, edges, file watching, and snapshots",
   "type": "module",
   "main": "./src/server/index.ts",

package/skills/pmx-canvas/SKILL.md

@@ -270,6 +270,7 @@ If a node type is rejected by `canvas_add_node`, call `canvas_describe_schema` a
 - `content`: for most types, this is markdown text. For `file` type, pass the **file path**
   (e.g., `"src/auth/login.ts"`) — the server auto-loads the file content and watches for changes.
   For `image` type, pass a file path, URL, or data URI.
+- `path`: compatibility alias for image paths only; prefer `content` for new image calls
 - `x`, `y`: position (auto-placed if omitted — prefer omitting for auto-layout)
 - `width`, `height`: dimensions (sensible defaults provided)
 - `color`: semantic color
@@ -306,8 +307,9 @@ If a node type is rejected by `canvas_add_node`, call `canvas_describe_schema` a
   ```
 
 **`canvas_add_json_render_node`** — Add a native json-render node
-- Required: `title`, `spec`
-- The `spec` must be a complete json-render object with `root`, `elements`, and optional `state`
+- Required: `spec`; `title` is optional and inferred from the root element when omitted
+- Prefer a complete json-render object with `root`, `elements`, and optional `state`
+- Legacy bare component specs like `{ type: "Badge", props: {...} }` are accepted and wrapped into a one-element document for compatibility
 - Use this when you want a structured UI panel rendered directly inside PMX Canvas
 - For shadcn `Badge`, prefer `props.text` with variants `default`, `secondary`, `destructive`, or
   `outline`. Legacy `props.label` and status variants (`success`, `info`, `warning`, `error`,

package/skills/pmx-canvas-testing/SKILL.md

@@ -40,11 +40,25 @@ bun run test:all            # Bun suite + browser smoke
   Manual browser validation also requires a fresh client bundle. `bun run test:web-canvas`
   already does this for you.
 
+## Coverage Notes
+
+- `bun run test:coverage` covers the Bun unit suite under `tests/unit/`
+- Coverage output is written to `coverage/lcov.info` and also printed as a text summary
+- CI currently uses that same unit-test coverage command, then runs browser smoke separately
+- Do not describe `test:coverage` as full-stack coverage; Playwright coverage is not wired in here
+
 ## Current Project Test Surface
 
 - Bun tests live under `tests/unit/`
 - Playwright browser smoke lives under `tests/e2e/`
-- CI runs coverage plus the browser smoke flow
+- CI runs Bun coverage plus the browser smoke flow
+
+## WebView Automation Caveat
+
+- Some Linux/CI environments expose `Bun.WebView` but still cannot start a usable automation
+  session within the timeout window
+- When testing WebView automation, treat a cleanly reported unsupported/timeout runtime boundary
+  as distinct from a product regression
 
 Prefer extending the existing suites before inventing a one-off script.
 

package/src/cli/agent.ts

@@ -522,11 +522,8 @@ async function buildJsonRenderRequestBody(
   flags: Record<string, string | true>,
 ): Promise<Record<string, unknown>> {
   const hint =
-    'Use: pmx-canvas node add --type json-render --title "Ops Dashboard" --spec-file ./dashboard.json';
+    'Use: pmx-canvas node add --type json-render --spec-file ./dashboard.json --title "Ops Dashboard"';
   const title = typeof flags.title === 'string' ? flags.title.trim() : '';
-  if (!title) {
-    die('json-render nodes require --title.', hint);
-  }
 
   const rawSpec = await readTextInput(flags, {
     fileFlags: ['spec-file'],
@@ -538,7 +535,7 @@ async function buildJsonRenderRequestBody(
   });
 
   const spec = parseJsonValue(rawSpec, 'JSON spec', hint);
-  const body: Record<string, unknown> = { title, spec };
+  const body: Record<string, unknown> = { ...(title ? { title } : {}), spec };
   applyCommonGeometryFlags(body, flags, {
     x: 'Use a finite number, e.g. --x 500',
     y: 'Use a finite number, e.g. --y 300',
@@ -985,8 +982,11 @@ cmd('node add', 'Add a node to the canvas', [
   const body: Record<string, unknown> = { type };
   if (flags.title) body.title = flags.title;
   const webpageUrl = getStringFlag(flags, 'url');
+  const imagePath = getStringFlag(flags, 'path');
   if (type === 'webpage' && webpageUrl) {
     body.url = webpageUrl;
+  } else if (type === 'image' && imagePath && !flags.content) {
+    body.content = imagePath;
   } else if (flags.content) {
     body.content = flags.content;
   }

package/src/json-render/server.ts

@@ -11,7 +11,7 @@ export interface JsonRenderSpec {
 }
 
 export interface JsonRenderNodeInput {
-  title: string;
+  title?: string;
   spec: unknown;
   x?: number;
   y?: number;
@@ -447,10 +447,38 @@ function normalizeSpec(spec: Record<string, unknown>): Record<string, unknown> {
   return changed ? { ...spec, elements: normalizedElements } : spec;
 }
 
-export function normalizeAndValidateJsonRenderSpec(spec: unknown): JsonRenderSpec {
+function isBareJsonRenderElement(spec: Record<string, unknown>): boolean {
+  return typeof spec.type === 'string' && !('root' in spec) && !('elements' in spec);
+}
+
+function normalizeJsonRenderInput(spec: unknown): unknown {
   const specRecord = asRecord(spec);
+  if (!specRecord || !isBareJsonRenderElement(specRecord)) return spec;
+
+  return {
+    root: 'root',
+    elements: {
+      root: {
+        ...specRecord,
+        children: Array.isArray(specRecord.children)
+          ? specRecord.children.filter((child: unknown) => typeof child === 'string')
+          : [],
+      },
+    },
+  };
+}
+
+export function inferJsonRenderNodeTitle(spec: JsonRenderSpec, fallback = 'json-render'): string {
+  const rootElement = asRecord(spec.elements[spec.root]);
+  const rootProps = asRecord(rootElement?.props);
+  const title = rootProps?.title ?? rootProps?.text ?? rootElement?.type;
+  return typeof title === 'string' && title.trim().length > 0 ? title.trim() : fallback;
+}
+
+export function normalizeAndValidateJsonRenderSpec(spec: unknown): JsonRenderSpec {
+  const specRecord = asRecord(normalizeJsonRenderInput(spec));
   if (!specRecord || typeof specRecord.root !== 'string' || !asRecord(specRecord.elements)) {
-    throw new Error('Missing root and elements in spec.');
+    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.');
   }
 
   const normalizedSpec = normalizeSpec(specRecord);

package/src/mcp/server.ts

@@ -41,11 +41,18 @@ import { listBundledSkills, readBundledSkill } from '../server/bundled-skills.js
 
 let canvas: PmxCanvas | null = null;
 
-const jsonRenderSpecSchema = z.object({
-  root: z.string(),
-  elements: z.record(z.string(), z.unknown()),
-  state: z.record(z.string(), z.unknown()).optional(),
-}).passthrough();
+const jsonRenderSpecSchema = z.union([
+  z.object({
+    root: z.string(),
+    elements: z.record(z.string(), z.unknown()),
+    state: z.record(z.string(), z.unknown()).optional(),
+  }).passthrough(),
+  z.object({
+    type: z.string(),
+    props: z.record(z.string(), z.unknown()).optional(),
+    children: z.array(z.string()).optional(),
+  }).passthrough(),
+]);
 
 function structuredSchemaDescription(): string {
   const routing = describeCanvasSchema().mcp.nodeTypeRouting;
@@ -140,6 +147,7 @@ export async function startMcpServer(): Promise<void> {
         .describe('Node type (prefer canvas_create_group for groups)'),
       title: z.string().optional().describe('Node title'),
       content: z.string().optional().describe('Node content (markdown for markdown nodes, file path for file nodes, image path/URL/data-URI for image nodes, URL for webpage nodes)'),
+      path: z.string().optional().describe('Compatibility alias for image node content. Prefer content for image paths.'),
       url: z.string().optional().describe('Canonical webpage URL field for webpage nodes. Overrides content when both are provided.'),
       x: z.number().optional().describe('X position (auto-placed if omitted)'),
       y: z.number().optional().describe('Y position (auto-placed if omitted)'),
@@ -169,7 +177,10 @@ export async function startMcpServer(): Promise<void> {
           ...(result.ok ? {} : { isError: true }),
         };
       }
-      const id = c.addNode(input);
+      const nodeInput = input.type === 'image' && input.path && !input.content
+        ? { ...input, content: input.path }
+        : input;
+      const id = c.addNode(nodeInput);
       return {
         content: [{ type: 'text', text: JSON.stringify(createdNodePayload(c, id), null, 2) }],
       };
@@ -442,8 +453,8 @@ export async function startMcpServer(): Promise<void> {
     'canvas_add_json_render_node',
     'Create a native json-render canvas node from a complete spec. Use this for structured dashboards, forms, tables, and other interactive UI panels that should render directly inside PMX Canvas.',
     {
-      title: z.string().describe('Node title'),
-      spec: jsonRenderSpecSchema.describe('Complete json-render spec with root, elements, and optional state'),
+      title: z.string().optional().describe('Optional node title. If omitted, PMX Canvas infers one from the root element.'),
+      spec: z.unknown().describe('json-render spec. Prefer a complete {root, elements, state?} document; a single bare component object is accepted for legacy callers.'),
       x: z.number().optional().describe('Optional X position'),
       y: z.number().optional().describe('Optional Y position'),
       width: z.number().optional().describe('Optional node width'),
@@ -453,7 +464,7 @@ export async function startMcpServer(): Promise<void> {
       const c = await ensureCanvas();
       try {
         const result = c.addJsonRenderNode({
-          title: input.title,
+          ...(typeof input.title === 'string' ? { title: input.title } : {}),
           spec: input.spec,
           ...(typeof input.x === 'number' ? { x: input.x } : {}),
           ...(typeof input.y === 'number' ? { y: input.y } : {}),

package/src/server/canvas-operations.ts

@@ -24,6 +24,7 @@ import {
   buildGraphSpec,
   createJsonRenderNodeData,
   GRAPH_NODE_SIZE,
+  inferJsonRenderNodeTitle,
   JSON_RENDER_NODE_SIZE,
   normalizeAndValidateJsonRenderSpec,
   type GraphNodeInput,
@@ -1000,7 +1001,7 @@ export function createCanvasJsonRenderNode(
     collapsed: false,
     pinned: false,
     dockPosition: null,
-    data: createJsonRenderNodeData(id, input.title, spec, {
+    data: createJsonRenderNodeData(id, input.title?.trim() || inferJsonRenderNodeTitle(spec), spec, {
       viewerType: 'json-render',
     }),
   };

package/src/server/canvas-schema.ts

@@ -171,7 +171,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     endpoint: '/api/canvas/node',
     mcpTool: 'canvas_add_node',
     fields: [
-      { name: 'content', type: 'string', required: true, description: 'Image path, URL, or data URI.' },
+      { name: 'content', type: 'string', required: true, description: 'Image path, URL, or data URI.', aliases: ['path'] },
       { name: 'title', type: 'string', required: false, description: 'Optional title override.' },
       { name: 'data.warning', type: 'string | { title?: string; detail: string }', required: false, description: 'Optional agent-supplied warning shown above the image.' },
       { name: 'data.warnings', type: 'Array<string | { title?: string; detail: string }>', required: false, description: 'Optional list of agent-supplied image warnings.' },
@@ -280,8 +280,8 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     endpoint: '/api/canvas/json-render',
     mcpTool: 'canvas_add_json_render_node',
     fields: [
-      { name: 'title', type: 'string', required: true, description: 'Rendered node title.' },
-      { name: 'spec', type: 'JsonRenderSpec', required: true, description: 'Complete json-render spec.' },
+      { name: 'title', type: 'string', required: false, description: 'Optional rendered node title; inferred from the root element when omitted.' },
+      { name: 'spec', type: 'JsonRenderSpec | JsonRenderElement', required: true, description: 'Complete {root, elements} json-render spec, or a legacy single bare component object with a type field.' },
       { name: 'x', type: 'number', required: false, description: 'Optional X position.' },
       { name: 'y', type: 'number', required: false, description: 'Optional Y position.' },
       { name: 'width', type: 'number', required: false, description: 'Optional node width.' },

package/src/server/server.ts

@@ -1210,12 +1210,15 @@ async function handleCanvasAddNode(req: Request): Promise<Response> {
   const extraData = body.data && typeof body.data === 'object' && !Array.isArray(body.data)
     ? body.data as Record<string, unknown>
     : undefined;
+  const content = type === 'image' && typeof body.path === 'string' && typeof body.content !== 'string'
+    ? body.path
+    : body.content;
   let added: ReturnType<typeof addCanvasNode>;
   try {
     added = addCanvasNode({
       type: type as CanvasNodeState['type'],
       ...(typeof body.title === 'string' ? { title: body.title } : {}),
-      ...(typeof body.content === 'string' ? { content: body.content } : {}),
+      ...(typeof content === 'string' ? { content } : {}),
       ...(extraData ? { data: extraData } : {}),
       ...(typeof body.x === 'number' ? { x: body.x } : {}),
       ...(typeof body.y === 'number' ? { y: body.y } : {}),
@@ -1603,13 +1606,10 @@ async function handleCanvasAddJsonRender(req: Request): Promise<Response> {
   const title = typeof body.title === 'string' ? body.title.trim() : '';
   const rawSpec =
     body.spec && typeof body.spec === 'object' && !Array.isArray(body.spec) ? body.spec : body;
-  if (!title) {
-    return responseJson({ ok: false, error: 'Missing required field: title.' }, 400);
-  }
 
   try {
     const result = createCanvasJsonRenderNode({
-      title,
+      ...(title ? { title } : {}),
       spec: rawSpec,
       ...(typeof body.x === 'number' ? { x: body.x } : {}),
       ...(typeof body.y === 'number' ? { y: body.y } : {}),