pmx-canvas 0.1.18 → 0.1.20

package/dist/types/client/canvas/CanvasViewport.d.ts

@@ -1,5 +1,5 @@
 import type { CanvasNodeState } from '../types';
-type AnnotationTool = 'pen' | 'eraser' | null;
+type AnnotationTool = 'pen' | 'eraser' | 'text' | null;
 interface CanvasViewportProps {
     onNodeContextMenu?: (e: MouseEvent, nodeId: string) => void;
     onCanvasContextMenu?: (e: MouseEvent, canvasX: number, canvasY: number) => void;

package/dist/types/client/icons.d.ts

@@ -23,6 +23,8 @@ export declare function IconMoon(p: IconProps): JSX.Element;
 export declare function IconPen(p: IconProps): JSX.Element;
 /** Eraser — remove canvas annotations */
 export declare function IconEraser(p: IconProps): JSX.Element;
+/** Text cursor — canvas text annotation mode */
+export declare function IconTextAnnotation(p: IconProps): JSX.Element;
 /** Camera — snapshots */
 export declare function IconSnapshot(p: IconProps): JSX.Element;
 /** Bullseye — trace toggle */

package/dist/types/client/state/canvas-store.d.ts

@@ -45,9 +45,11 @@ export declare function removeEdgesForNode(nodeId: string): void;
 export declare function addAnnotation(annotation: CanvasAnnotation): void;
 export declare function removeAnnotation(id: string): void;
 export declare function createAnnotationFromClient(input: {
+    type?: CanvasAnnotation['type'];
     points: CanvasAnnotation['points'];
     color: string;
     width: number;
+    text?: string;
     label?: string;
 }): Promise<{
     ok: boolean;

package/dist/types/client/types.d.ts

@@ -35,7 +35,7 @@ export interface CanvasAnnotationPoint {
 }
 export interface CanvasAnnotation {
     id: string;
-    type: 'freehand';
+    type: 'freehand' | 'text';
     points: CanvasAnnotationPoint[];
     bounds: {
         x: number;
@@ -45,6 +45,7 @@ export interface CanvasAnnotation {
     };
     color: string;
     width: number;
+    text?: string;
     label?: string;
     createdAt: string;
 }

package/dist/types/json-render/charts/components.d.ts

@@ -6,7 +6,7 @@
  * chat example. Each component receives BaseComponentProps<T> and renders
  * a responsive chart inside a styled container.
  */
-import type { ReactNode } from 'react';
+import { type ReactNode } from 'react';
 import type { BaseComponentProps } from '@json-render/react';
 export declare const CHART_COLORS: string[];
 export type AggregateMode = 'sum' | 'count' | 'avg';
@@ -56,6 +56,10 @@ export declare const axisTickMargin = 8;
 export declare const legendMargin: {
     top: number;
 };
+export declare function useChartFrameHeight(explicitHeight: number | null | undefined, fallbackHeight?: number): {
+    frameRef: import("react").RefObject<HTMLDivElement | null>;
+    height: number;
+};
 /** Shared wrapper for cartesian charts (Line + Bar). */
 export declare function CartesianChart({ props, children, className, }: {
     props: CartesianChartProps;

package/dist/types/json-render/renderer/index.d.ts

@@ -12,5 +12,6 @@ declare global {
             state?: Record<string, unknown>;
         };
         __PMX_CANVAS_JSON_RENDER_THEME__?: string;
+        __PMX_CANVAS_JSON_RENDER_DISPLAY__?: string;
     }
 }

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

@@ -58,4 +58,5 @@ export declare function buildJsonRenderViewerHtml(options: {
     title: string;
     spec: JsonRenderSpec;
     theme?: 'dark' | 'light' | 'high-contrast';
+    display?: 'expanded';
 }): Promise<string>;

package/dist/types/mcp/canvas-access.d.ts

@@ -8,6 +8,8 @@ type AddDiagramInput = Parameters<PmxCanvas['addDiagram']>[0];
 type AddJsonRenderNodeInput = Parameters<PmxCanvas['addJsonRenderNode']>[0];
 type AddJsonRenderNodeResult = ReturnType<PmxCanvas['addJsonRenderNode']>;
 type AddHtmlNodeInput = Parameters<PmxCanvas['addHtmlNode']>[0];
+type AddHtmlPrimitiveInput = Parameters<PmxCanvas['addHtmlPrimitive']>[0];
+type AddHtmlPrimitiveResult = ReturnType<PmxCanvas['addHtmlPrimitive']>;
 type AddGraphNodeInput = Parameters<PmxCanvas['addGraphNode']>[0];
 type AddGraphNodeResult = ReturnType<PmxCanvas['addGraphNode']>;
 type UpdateNodePatch = Parameters<PmxCanvas['updateNode']>[1];
@@ -50,6 +52,7 @@ export interface CanvasAccess {
     addDiagram(input: AddDiagramInput): Promise<OpenMcpAppResult>;
     addJsonRenderNode(input: AddJsonRenderNodeInput): Promise<AddJsonRenderNodeResult>;
     addHtmlNode(input: AddHtmlNodeInput): Promise<string>;
+    addHtmlPrimitive(input: AddHtmlPrimitiveInput): Promise<AddHtmlPrimitiveResult>;
     addGraphNode(input: AddGraphNodeInput): Promise<AddGraphNodeResult>;
     buildWebArtifact(input: WebArtifactInput): Promise<WebArtifactResult>;
     updateNode(id: string, patch: UpdateNodePatch): Promise<void>;

package/dist/types/server/canvas-operations.d.ts

@@ -56,6 +56,10 @@ interface CanvasAddNodeInput {
     fileMode?: 'path' | 'inline' | 'auto';
     strictSize?: boolean;
 }
+export declare const MARKDOWN_NODE_DEFAULT_SIZE: {
+    width: number;
+    height: number;
+};
 interface CanvasCreateGroupInput {
     title?: string;
     childIds?: string[];

package/dist/types/server/canvas-schema.d.ts

@@ -1,5 +1,6 @@
 import { type JsonRenderComponentDescriptor } from '../json-render/catalog.js';
 import { type GraphNodeInput, type JsonRenderSpec } from '../json-render/server.js';
+import { type HtmlPrimitiveDescriptor } from './html-primitives.js';
 export interface CanvasCreateField {
     name: string;
     type: string;
@@ -19,8 +20,17 @@ export interface CanvasCreateTypeSchema {
 }
 export interface StructuredValidationResult {
     ok: true;
-    type: 'json-render' | 'graph';
-    normalizedSpec: JsonRenderSpec;
+    type: 'json-render' | 'graph' | 'html-primitive';
+    normalizedSpec?: JsonRenderSpec;
+    normalizedPrimitive?: {
+        kind: string;
+        title: string;
+        htmlBytes: number;
+        defaultSize: {
+            width: number;
+            height: number;
+        };
+    };
     summary: Record<string, unknown>;
 }
 declare const CANONICAL_GRAPH_TYPES: readonly ["line", "bar", "pie", "area", "scatter", "radar", "stacked-bar", "composed"];
@@ -37,6 +47,7 @@ export declare function describeCanvasSchema(): {
     graph: {
         graphTypes: CanvasGraphType[];
     };
+    htmlPrimitives: HtmlPrimitiveDescriptor[];
     mcp: {
         tools: string[];
         resources: string[];
@@ -44,8 +55,13 @@ export declare function describeCanvasSchema(): {
     };
 };
 export declare function validateStructuredCanvasPayload(input: {
-    type: 'json-render' | 'graph';
+    type: 'json-render' | 'graph' | 'html-primitive';
     spec?: unknown;
     graph?: GraphNodeInput;
+    primitive?: {
+        kind: string;
+        title?: string;
+        data?: Record<string, unknown>;
+    };
 }): StructuredValidationResult;
 export {};

package/dist/types/server/canvas-serialization.d.ts

@@ -18,6 +18,7 @@ export interface CanvasAnnotationSummary {
     color: string;
     width: number;
     pointCount: number;
+    text: string | null;
     label: string | null;
     createdAt: string;
 }

package/dist/types/server/canvas-state.d.ts

@@ -39,6 +39,8 @@ export interface CanvasSnapshot {
 export interface CanvasSnapshotListOptions {
     limit?: number;
     query?: string;
+    before?: string;
+    after?: string;
     all?: boolean;
 }
 export interface CanvasSnapshotGcOptions {
@@ -88,7 +90,7 @@ export interface CanvasAnnotationPoint {
 }
 export interface CanvasAnnotation {
     id: string;
-    type: 'freehand';
+    type: 'freehand' | 'text';
     points: CanvasAnnotationPoint[];
     bounds: {
         x: number;
@@ -98,6 +100,7 @@ export interface CanvasAnnotation {
     };
     color: string;
     width: number;
+    text?: string;
     label?: string;
     createdAt: string;
 }
@@ -132,6 +135,9 @@ interface GroupNodesOptions {
     layout?: 'grid' | 'column' | 'flow';
     keepGroupFrame?: boolean;
 }
+interface ApplyUpdatesOptions {
+    skipGroupChildTranslation?: boolean;
+}
 declare class CanvasStateManager {
     private nodes;
     private edges;
@@ -229,7 +235,7 @@ declare class CanvasStateManager {
     private removeEdgesForNode;
     getLayout(): CanvasLayout;
     getLayoutForPersistence(): CanvasLayout;
-    applyUpdates(updates: CanvasNodeUpdate[]): {
+    applyUpdates(updates: CanvasNodeUpdate[], options?: ApplyUpdatesOptions): {
         applied: number;
         skipped: number;
     };

package/dist/types/server/html-primitives.d.ts

@@ -0,0 +1,34 @@
+export declare const HTML_PRIMITIVE_KINDS: readonly ["choice-grid", "plan-timeline", "review-sheet", "pr-writeup", "system-map", "code-walkthrough", "design-sheet", "component-gallery", "interaction-prototype", "flowchart", "deck", "illustration-set", "explainer", "status-report", "incident-report", "triage-board", "config-editor", "prompt-tuner"];
+export type HtmlPrimitiveKind = typeof HTML_PRIMITIVE_KINDS[number];
+export interface HtmlPrimitiveDescriptor {
+    kind: HtmlPrimitiveKind;
+    title: string;
+    description: string;
+    useWhen: string;
+    defaultSize: {
+        width: number;
+        height: number;
+    };
+    dataShape: string;
+    example: Record<string, unknown>;
+}
+export interface HtmlPrimitiveInput {
+    kind: HtmlPrimitiveKind;
+    title?: string;
+    data?: Record<string, unknown>;
+}
+export interface HtmlPrimitiveBuildResult {
+    kind: HtmlPrimitiveKind;
+    title: string;
+    html: string;
+    summary: string;
+    defaultSize: {
+        width: number;
+        height: number;
+    };
+    data: Record<string, unknown>;
+}
+export declare function isHtmlPrimitiveKind(value: string): value is HtmlPrimitiveKind;
+export declare function getHtmlPrimitiveDescriptor(kind: HtmlPrimitiveKind): HtmlPrimitiveDescriptor;
+export declare function listHtmlPrimitiveDescriptors(): HtmlPrimitiveDescriptor[];
+export declare function buildHtmlPrimitive(input: HtmlPrimitiveInput): HtmlPrimitiveBuildResult;

package/dist/types/server/index.d.ts

@@ -3,6 +3,7 @@ import type { CanvasAnnotation, CanvasNodeState, CanvasEdge, CanvasLayout } from
 import { searchNodes } from './spatial-analysis.js';
 import { diffLayouts } from './mutation-history.js';
 import { fitCanvasView, gcCanvasSnapshots, listCanvasSnapshots } from './canvas-operations.js';
+import type { HtmlPrimitiveKind } from './html-primitives.js';
 import { type WebArtifactBuildInput, type WebArtifactCanvasBuildResult } from './web-artifacts.js';
 import { type ExternalMcpTransportConfig } from './mcp-app-runtime.js';
 import { type DiagramPresetOpenInput } from './diagram-presets.js';
@@ -181,6 +182,7 @@ export declare class PmxCanvas extends EventEmitter {
         graph: {
             graphTypes: ("line" | "bar" | "pie" | "area" | "scatter" | "radar" | "composed" | "stacked-bar")[];
         };
+        htmlPrimitives: import("./html-primitives.js").HtmlPrimitiveDescriptor[];
         mcp: {
             tools: string[];
             resources: string[];
@@ -248,6 +250,21 @@ export declare class PmxCanvas extends EventEmitter {
         height?: number;
         strictSize?: boolean;
     }): string;
+    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;
+    };
     addGraphNode(input: GraphNodeInput): {
         id: string;
         url: string;
@@ -275,10 +292,12 @@ 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, openWebArtifactInCanvas, resolveWebArtifactScriptPath, resolveWorkspacePath, } from './web-artifacts.js';
 export { buildGraphSpec, buildJsonRenderViewerHtml, createJsonRenderNodeData, GRAPH_NODE_SIZE, JSON_RENDER_NODE_SIZE, normalizeAndValidateJsonRenderSpec, } from '../json-render/server.js';
 export type { CodeGraphSummary, CodeGraphEdge } from './code-graph.js';
 export type { MutationEntry, MutationSummary, SnapshotDiffResult } from './mutation-history.js';
 export type { WebArtifactBuildInput, WebArtifactBuildOutput, WebArtifactCanvasBuildResult, 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/docs/RELEASE.md

@@ -0,0 +1,153 @@
+# Release process
+
+Internal recipe for cutting a new `pmx-canvas` release. Lives in `docs/`
+rather than the README so end-user agents and humans driving the canvas
+aren't distracted by maintainer-only flow. Agents working **on** this
+repo (improving the canvas itself) should treat this file as the
+single source of truth for the release dance — see also
+[`AGENTS.md`](../AGENTS.md) and [`CLAUDE.md`](../CLAUDE.md).
+
+## TL;DR
+
+1. Land all the changes you want in the release on `main` with green CI.
+2. Bump `package.json` `version`.
+3. Add a `## [X.Y.Z]` block to `CHANGELOG.md`.
+4. Commit, push, wait for `test.yml` green.
+5. `git tag -a vX.Y.Z -m "..." && git push origin vX.Y.Z` →
+   `publish.yml` runs `npm publish --access public --provenance`.
+6. `gh release create vX.Y.Z --notes-file <notes.md>`.
+7. Smoke-test the published tarball: `bunx pmx-canvas@X.Y.Z --no-open`.
+
+## Pre-flight gates
+
+Run these locally before tagging. They mirror what `publish.yml`
+re-runs in CI; a failure here means the publish workflow will also fail.
+
+```bash
+bun install --frozen-lockfile
+bun run typecheck
+bun run build
+bun test tests/unit         # 200+ tests, all green
+bun run test:web-canvas     # Playwright E2E, all green
+bun run test:e2e-cli        # fresh-workspace CLI eval
+bun run release:check       # bundles + lints
+bun run release:smoke       # packs + boots from a clean dir
+bun run pack:dry-run        # confirms the tarball shape
+```
+
+`bun run test:e2e-cli` starts a local server in a fresh temp workspace
+and exercises the CLI flows from
+[`docs/evals/e2e-cli-coverage.md`](evals/e2e-cli-coverage.md).
+
+## Versioning
+
+Semantic versioning. While we are still in `0.1.x`:
+
+- Patch (`0.1.x → 0.1.x+1`): bug fixes, hardening, internal cleanups,
+  additive CLI flags / MCP fields with backwards-compat fallbacks.
+- Minor (`0.1.x → 0.2.0`): documented breaking changes (e.g. dropping
+  the `hostMode + path` fallback in `getCanvasNodeKind`, removing legacy
+  `ext-app-ext-app-…` ID handling, JSON-shape changes that aren't
+  additive).
+- Major (`0.x → 1.0`): production-stability commitment.
+
+CLAUDE.md rule #5 (CanvasStateManager / PmxCanvas SDK / HTTP / MCP
+four-layer parity) is the strongest hard rule for what counts as
+non-breaking — a CLI/HTTP-only addition without MCP parity has
+historically required a follow-up patch release to restore parity.
+
+## CHANGELOG
+
+`CHANGELOG.md` follows [Keep a Changelog](https://keepachangelog.com/).
+Each release section uses these subheadings:
+
+- **Added** — new public surface (HTTP endpoint, MCP tool/resource, CLI
+  command/flag, SDK export, JSON shape).
+- **Changed** — behavior changes that aren't strictly bug fixes
+  (response shape additions, schema cleanups, stricter validation).
+- **Fixed** — bug fixes.
+- **Internal** — refactors, test additions, docs that don't affect
+  the public surface.
+
+Don't ship a release without a CHANGELOG entry. The GitHub release
+notes file (`/tmp/pmx-canvas-vX.Y.Z-release-notes.md` by convention)
+expands on the CHANGELOG with examples and migration notes.
+
+## Tag → publish
+
+The publish workflow ([`/.github/workflows/publish.yml`](../.github/workflows/publish.yml))
+triggers on tags matching `v*`:
+
+```bash
+git tag -a v0.1.6 -m "v0.1.6 — short summary"
+git push origin v0.1.6
+```
+
+It will:
+
+1. Verify the tag matches `package.json` version.
+2. Re-run typecheck / build / unit / E2E / pack.
+3. `npm publish --access public --provenance` using the `NPM_TOKEN`
+   secret. Provenance attestations are signed via sigstore and visible
+   on the npm package page.
+
+Watch it complete:
+
+```bash
+gh run watch
+```
+
+If publish fails after npm has accepted the tarball, you cannot reuse
+the same version number. Bump the patch and re-tag.
+
+If this is the first release from your machine, run `bunx npm login`
+once so Bun can reuse your npm credentials. CI does not need this —
+it uses `NPM_TOKEN` directly.
+
+## GitHub release
+
+After `npm publish` succeeds:
+
+```bash
+gh release create v0.1.6 \
+  --title "pmx-canvas 0.1.6 — short theme" \
+  --notes-file /tmp/pmx-canvas-v0.1.6-release-notes.md \
+  --verify-tag
+```
+
+`--verify-tag` makes the command fail if the local tag drifted from
+the remote — a small but useful guard.
+
+## Smoke test from npm
+
+```bash
+cd /tmp && rm -rf smoke && mkdir smoke && cd smoke
+bunx --bun pmx-canvas@<version> --no-open --port=4926 > smoke.log &
+SP=$!
+for i in 1 2 3 4 5 6 7 8 9 10; do
+  curl -sf http://localhost:4926/health >/dev/null 2>&1 && break
+  sleep 1
+done
+curl -s http://localhost:4926/health      # → {"ok":true,"workspace":"…"}
+bunx pmx-canvas@<version> --version       # → <version>
+kill $SP
+```
+
+If `bunx pmx-canvas@<version>` resolves and the health endpoint replies
+with `ok: true`, the published tarball is intact end-to-end.
+
+## Common gotchas
+
+- **`/.pmx-canvas/artifacts/.web-artifacts/sdlc-control-room/.parcel-cache/`**
+  files always show as modified after running an artifact build. They
+  are workspace-local cache and must not be committed; they're gitignored
+  but still appear in `git status`. Use `git restore --staged` if they
+  sneak into a `git add -A`.
+- **`docs/screenshot.png`** updates whenever the showcase E2E runs.
+  Don't bake those updates into a release commit unless the screenshot
+  in `Readme.md` actually needs the refresh.
+- **CHANGELOG dates**: use the actual publish date in the
+  `## [version] - YYYY-MM-DD` header, not the day you wrote the entry.
+- **Node 24 deprecation timeline**: GitHub Actions is migrating
+  `actions/checkout`, `setup-node`, `upload-artifact` to Node 24 by
+  June 2, 2026. The publish workflow already pins `@v5` of all three.