@1agh/maude 0.15.0

package/plugins/design/dev-server/canvas-build.ts

@@ -0,0 +1,219 @@
+// Browser-loadable canvas bundle (DDR-019, Phase 3.6 Task 6).
+//
+// The pre-3.6 pipeline (canvas-pipeline.ts) parses the TSX, injects data-cd-id,
+// then lowers JSX via Bun.Transpiler. Output is JS but uses Bun-runtime-internal
+// `jsxDEV_<hash>` symbol names — not browser-loadable.
+//
+// This module wraps that pipeline with a second pass through Bun.build, which
+// resolves the JSX runtime against the canonical "react/jsx-dev-runtime" import
+// and externalises React + ReactDOM. Output is standard ES module text. The
+// browser loads it via the runtime importmap declared in _shell.html.
+//
+// The two-stage approach is deliberate:
+//
+//   1. canvas-pipeline.ts (oxc + magic-string) — owns identity. Pre-orders JSX
+//      elements, injects data-cd-id, writes _locator.json. Pure + fast.
+//   2. canvas-build.ts (Bun.build) — owns module shape. Feeds the post-pass-1
+//      source to Bun.build via a virtual-loader plugin, so the bundler
+//      processes our edited source (not the on-disk file). Externalises every
+//      runtime package the importmap covers.
+//
+// Caller (http.ts) reads the canvas source, calls buildCanvasModule(), then
+// serves the resulting JS at /<designRel>/ui/<slug>.tsx with Content-Type
+// `application/javascript`.
+
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+import { canvasLibPath, canvasLibResolver } from './canvas-lib-resolver.ts';
+import { transpileCanvasSource } from './canvas-pipeline.ts';
+import type { LocatorMap } from './locator.ts';
+import { RUNTIME_PACKAGES } from './runtime-bundle.ts';
+
+// Sanity-check the dev-server-bundled canvas-lib once per process boot. If the
+// install is corrupt (file missing), surface that before the first canvas build
+// — Bun.build's plugin throws collapse to a useless "Bundle failed" string.
+let canvasLibPresenceVerified = false;
+function verifyCanvasLibPresence(): void {
+  if (canvasLibPresenceVerified) return;
+  const target = canvasLibPath();
+  if (!existsSync(target)) {
+    throw new Error(
+      `[@maude/canvas-lib] canvas library missing at ${target} — dev-server install is corrupt; re-install @1agh/maude.`
+    );
+  }
+  canvasLibPresenceVerified = true;
+}
+
+// Per DDR-025, canvas-lib now ships with the dev-server. Downstream projects
+// with a legacy `<designRoot>/_lib/canvas-lib.tsx` from a pre-4.0.5 setup get a
+// single deprecation warning per dev-server process — the project file is
+// ignored, the dev-server-bundled lib is authoritative.
+const loggedLegacyForRoot = new Set<string>();
+function warnLegacyDesignLib(designRoot: string): void {
+  if (loggedLegacyForRoot.has(designRoot)) return;
+  loggedLegacyForRoot.add(designRoot);
+  const legacy = path.join(designRoot, '_lib', 'canvas-lib.tsx');
+  if (existsSync(legacy)) {
+    console.warn(
+      `[canvas-lib] Legacy ${legacy} detected. As of v0.15.0, canvas-lib ships with the dev-server install — the project file is ignored and can be deleted. See DDR-025 for the migration rationale.`
+    );
+  }
+}
+
+export interface CanvasBundleResult {
+  /** Browser-loadable ES module text. */
+  js: string;
+  /** data-cd-id → source location map (same as the pipeline emits). */
+  locator: LocatorMap;
+  /** Content-derived hash; suitable as HTTP ETag. */
+  etag: string;
+}
+
+export interface BuildCanvasOptions {
+  /**
+   * Absolute path to the design root. Per DDR-025 canvas-lib is dev-server
+   * bundled, so this value is no longer required to resolve `@maude/canvas-lib`
+   * — it's accepted for back-compat and used only to emit a one-shot
+   * deprecation warning when a legacy `<designRoot>/_lib/canvas-lib.tsx` is
+   * detected.
+   */
+  designRoot?: string;
+}
+
+/**
+ * Build a single canvas TSX file end-to-end. Identity pass is from
+ * canvas-pipeline.ts; the module pass is Bun.build with React externalised
+ * and `@maude/canvas-lib` resolved to the dev-server-bundled canvas-lib.
+ */
+export async function buildCanvasModule(
+  canvasAbsPath: string,
+  source: string,
+  options: BuildCanvasOptions = {}
+): Promise<CanvasBundleResult> {
+  // Pass 1: inject data-cd-id, capture the locator.
+  const pass1 = transpileCanvasSource(canvasAbsPath, source);
+
+  // Sanity-check the dev-server-bundled canvas-lib once per process — if the
+  // install is corrupt, fail loud before Bun.build collapses plugin throws.
+  if (/@maude\/canvas-lib/.test(source)) {
+    verifyCanvasLibPresence();
+  }
+
+  // Non-destructive deprecation warning for projects still carrying a legacy
+  // `<designRoot>/_lib/canvas-lib.tsx`. The dev-server-bundled lib is
+  // authoritative; this just nudges the project owner to clean up.
+  if (options.designRoot) {
+    warnLegacyDesignLib(options.designRoot);
+  }
+
+  // Pass 2: Bun.build with a virtual loader that resolves canvasAbsPath to the
+  // post-pass-1 TSX. Every other import (npm packages, relative imports of
+  // sibling canvas components) goes through Bun's default resolver. The four
+  // runtime packages are externalised so they resolve through the importmap.
+  // Phase 5.1 — `react-dom` is now its own runtime package (so createPortal is
+  // in the bundle). The flatMap legacy alias for `react-dom` is no longer
+  // needed; RUNTIME_PACKAGES already lists every specifier the importmap covers.
+  const externalSpecifiers = new Set<string>(RUNTIME_PACKAGES);
+
+  const built = await Bun.build({
+    entrypoints: [canvasAbsPath],
+    target: 'browser',
+    format: 'esm',
+    minify: false,
+    splitting: false,
+    define: {
+      // Match runtime-bundle.ts: production React. Without this the canvas's
+      // `import { jsxDEV } from "react/jsx-dev-runtime"` resolves against a
+      // bundle that fails to load due to a Bun.build naming collision in the
+      // dev variant. Both halves of the system MUST agree on the JSX runtime
+      // flavour.
+      'process.env.NODE_ENV': '"production"',
+    },
+    plugins: [
+      // Resolve `@maude/canvas-lib` BEFORE exact-externals — we want the bare
+      // specifier to map to the dev-server-bundled lib, not get marked external.
+      canvasLibResolver(),
+      {
+        name: 'canvas-virtual-source',
+        setup(builder) {
+          builder.onLoad({ filter: filterForExactPath(canvasAbsPath) }, () => ({
+            contents: pass1.withIds,
+            loader: 'tsx',
+          }));
+        },
+      },
+      {
+        name: 'exact-externals',
+        setup(builder) {
+          builder.onResolve({ filter: /.*/ }, (args) => {
+            if (externalSpecifiers.has(args.path)) {
+              return { path: args.path, external: true };
+            }
+            return null;
+          });
+        },
+      },
+    ],
+  });
+
+  if (!built.success) {
+    const msg = built.logs.map((l) => l.message).join('\n');
+    throw new Error(`Bun.build failed on ${canvasAbsPath}:\n${msg}`);
+  }
+  const entry = built.outputs.find((o) => o.kind === 'entry-point');
+  if (!entry) {
+    throw new Error(`Bun.build produced no entry-point output for ${canvasAbsPath}`);
+  }
+  let js = await entry.text();
+
+  // Gather any sibling CSS the bundler produced from `import "./<slug>.css"`
+  // statements in the canvas/specimen TSX. Bun.build extracts those into a
+  // separate `kind: "asset"` CSS file. Browser-loaded ESM doesn't process
+  // `import "*.css"` natively, so we inline the CSS via a `<style>` tag
+  // injection at module-init time — keeps each canvas self-contained without
+  // needing a parallel `<link>` request.
+  const cssAssets = built.outputs.filter((o) => o.kind === 'asset' && o.path.endsWith('.css'));
+  if (cssAssets.length > 0) {
+    let css = '';
+    for (const a of cssAssets) css += await a.text();
+    if (css.trim().length > 0) {
+      const slug = canvasAbsPath.split('/').pop() ?? 'canvas';
+      js = buildCssInjector(slug, css) + js;
+    }
+  }
+
+  const etag = Bun.hash(js).toString(16);
+  return { js, locator: pass1.locator, etag };
+}
+
+/**
+ * Synthesize a module-init prologue that creates a `<style data-canvas-css>`
+ * tag with the bundled CSS text. Idempotent per-slug — duplicate mounts of
+ * the same canvas don't re-inject. Run at top-level so it executes before
+ * the React component does its first render.
+ */
+function buildCssInjector(slug: string, css: string): string {
+  // JSON-encode the CSS text so we don't need to worry about backticks,
+  // backslashes, or embedded `</style>` (which would break a raw template).
+  const enc = JSON.stringify(css);
+  const id = `canvas-css-${slug.replace(/[^a-zA-Z0-9-]/g, '_')}`;
+  return `// canvas-build: inject bundled sibling CSS so the canvas is self-contained.\n(function(){if(typeof document==="undefined")return;if(document.getElementById(${JSON.stringify(id)}))return;var s=document.createElement("style");s.id=${JSON.stringify(id)};s.dataset.canvasCss="bundled";s.textContent=${enc};document.head.appendChild(s);})();\n`;
+}
+
+function filterForExactPath(absPath: string): RegExp {
+  // Bun.build hands onLoad the resolved on-disk path. On macOS /tmp is a
+  // symlink to /private/tmp, so an entrypoint of "/tmp/foo.tsx" arrives in
+  // onLoad as "/private/tmp/foo.tsx". Match on the *trailing* path
+  // segments — same filename + parent dir — which is enough to uniquely
+  // identify a canvas file path while tolerating prefix normalisations.
+  // We require the last two segments to match so a canvas with the same
+  // filename in a different directory doesn't collide.
+  const parts = absPath.split('/');
+  const tail = parts.slice(-2).join('/');
+  return new RegExp(`/${escapeRegex(tail)}$`);
+}
+
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/plugins/design/dev-server/canvas-edit.ts

@@ -0,0 +1,388 @@
+// AST-aware single-element edits for the `/design:edit` Step 3a fast path
+// (DDR-019, Phase 3.6 Task 5).
+//
+// Caller hands us (canvasAbsPath, dataCdId, attr, value); we parse the TSX,
+// re-walk it with the same component/jsxIndex bookkeeping as canvas-pipeline.ts,
+// find the JSX element whose ID matches, and rewrite a single attribute via
+// magic-string. The two-pass-transform contract (DDR-019) is the only thing
+// that keeps source-DOM identity stable across edits — so the editor lives
+// next to the transpiler and shares its toolchain (oxc-parser + magic-string).
+//
+// Supported `attr` syntaxes:
+//   - "className"         → swap the value of the `className` JSX attribute
+//                           (insert one if missing). Value form: bare string.
+//   - "style.<prop>"      → swap (or insert) a single CSS-property key inside
+//                           the inline `style={{ ... }}` object. Value form:
+//                           literal text inserted between `:` and `,` — pass a
+//                           JS expression (string with quotes for strings, raw
+//                           number for numbers).
+//   - "<any other name>"  → swap (or insert) the value of a plain string
+//                           attribute (aria-label, role, title, ...).
+//
+// All edits preserve every other attribute byte-for-byte. The `data-cd-id`
+// attribute is intentionally NOT writable through this path — the pipeline
+// owns those.
+//
+// Concurrent edits against the same canvas serialise behind a per-file mutex
+// (matches the locator.ts pattern). Two parallel edits against different
+// canvases run in parallel.
+
+import MagicString from 'magic-string';
+import { parseSync } from 'oxc-parser';
+
+export class CanvasEditError extends Error {
+  readonly canvas: string;
+  readonly id: string;
+  constructor(message: string, info: { canvas: string; id: string }) {
+    super(message);
+    this.name = 'CanvasEditError';
+    this.canvas = info.canvas;
+    this.id = info.id;
+  }
+}
+
+const PASCAL_CASE = /^[A-Z][A-Za-z0-9_]*$/;
+// biome-ignore lint/suspicious/noExplicitAny: oxc-parser AST nodes are heterogeneous.
+type AnyNode = any;
+
+function isPascalIdent(name: unknown): name is string {
+  return typeof name === 'string' && PASCAL_CASE.test(name);
+}
+
+function componentNameOf(node: AnyNode): string | null {
+  if (!node || typeof node !== 'object') return null;
+  if (node.type === 'FunctionDeclaration' && isPascalIdent(node.id?.name)) return node.id.name;
+  if (node.type === 'VariableDeclarator' && isPascalIdent(node.id?.name)) {
+    const init = node.init;
+    if (init && (init.type === 'ArrowFunctionExpression' || init.type === 'FunctionExpression')) {
+      return node.id.name;
+    }
+  }
+  if (node.type === 'FunctionExpression' && isPascalIdent(node.id?.name)) return node.id.name;
+  return null;
+}
+
+function computeId(componentName: string, idx: number): string {
+  return Bun.hash(`${componentName}:${idx}`).toString(16).padStart(16, '0').slice(0, 8);
+}
+
+interface OpeningHit {
+  opening: AnyNode;
+}
+
+/**
+ * Find the openingElement of the JSX element whose pipeline-computed ID matches
+ * `targetId`. Walks pre-order with the same component+jsxIndex bookkeeping the
+ * pipeline uses, so the ID arithmetic stays in lockstep. Returns null if no
+ * match.
+ */
+function findOpening(program: AnyNode, targetId: string): OpeningHit | null {
+  interface Frame {
+    componentName: string;
+    jsxIndex: number;
+  }
+  const stack: Frame[] = [{ componentName: '', jsxIndex: 0 }];
+  let hit: OpeningHit | null = null;
+
+  function visit(node: AnyNode): void {
+    if (hit || !node || typeof node !== 'object') return;
+    if (Array.isArray(node)) {
+      for (const c of node) {
+        if (hit) return;
+        visit(c);
+      }
+      return;
+    }
+    if (typeof node.type !== 'string') return;
+
+    const newComp = componentNameOf(node);
+    let pushed = false;
+    if (newComp !== null) {
+      stack.push({ componentName: newComp, jsxIndex: 0 });
+      pushed = true;
+    }
+
+    if (node.type === 'JSXElement') {
+      const frame = stack[stack.length - 1] as Frame;
+      const idx = frame.jsxIndex;
+      frame.jsxIndex += 1;
+      const id = computeId(frame.componentName, idx);
+      if (id === targetId) {
+        hit = { opening: node.openingElement };
+      }
+      if (!hit) {
+        if (node.openingElement) visit(node.openingElement.attributes);
+        visit(node.children);
+      }
+      if (pushed) stack.pop();
+      return;
+    }
+
+    for (const k of Object.keys(node)) {
+      if (k === 'loc' || k === 'range' || k === 'start' || k === 'end' || k === 'type') continue;
+      visit(node[k]);
+    }
+
+    if (pushed) stack.pop();
+  }
+
+  visit(program);
+  return hit;
+}
+
+function findAttribute(opening: AnyNode, name: string): AnyNode | null {
+  const attrs = opening?.attributes;
+  if (!Array.isArray(attrs)) return null;
+  for (const a of attrs) {
+    if (a?.type === 'JSXAttribute' && a.name?.type === 'JSXIdentifier' && a.name.name === name) {
+      return a;
+    }
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Per-canvas mutex. Mirrors locator.ts; two concurrent edits against the same
+// .tsx file serialise so they can't race read-modify-write.
+
+const locks = new Map<string, Promise<void>>();
+function withLock<T>(filePath: string, fn: () => Promise<T>): Promise<T> {
+  const prev = locks.get(filePath) ?? Promise.resolve();
+  let release!: () => void;
+  const gate = new Promise<void>((res) => {
+    release = res;
+  });
+  const next = prev.then(() => gate);
+  locks.set(filePath, next);
+  return prev.then(fn).finally(() => {
+    release();
+    if (locks.get(filePath) === next) locks.delete(filePath);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Public API.
+
+export interface EditResult {
+  /** The post-edit source (also written to disk by editAttribute()). */
+  source: string;
+  /** Number of bytes the edit changed (positive = grew, negative = shrunk). */
+  delta: number;
+}
+
+/**
+ * Apply a single-attribute edit to the JSX element with the given `data-cd-id`.
+ * Reads the canvas, rewrites in memory, writes atomically (via Bun.write to a
+ * tmp + rename) so a concurrent reader never sees a partial file.
+ */
+export async function editAttribute(
+  canvasAbsPath: string,
+  id: string,
+  attr: string,
+  value: string
+): Promise<EditResult> {
+  return withLock(canvasAbsPath, async () => {
+    const file = Bun.file(canvasAbsPath);
+    if (!(await file.exists())) {
+      throw new CanvasEditError(`Canvas not found: ${canvasAbsPath}`, {
+        canvas: canvasAbsPath,
+        id,
+      });
+    }
+    const source = await file.text();
+    const next = applyEdit(canvasAbsPath, source, id, attr, value);
+    if (next.source === source) return { source, delta: 0 };
+    const tmp = `${canvasAbsPath}.tmp.${Math.random().toString(36).slice(2, 10)}`;
+    await Bun.write(tmp, next.source);
+    const { rename } = await import('node:fs/promises');
+    await rename(tmp, canvasAbsPath);
+    return next;
+  });
+}
+
+/**
+ * Pure variant — exposed for tests + in-memory pipelines. Caller owns
+ * persistence. Throws CanvasEditError if the ID isn't found or the edit shape
+ * isn't representable.
+ */
+export function applyEdit(
+  canvasAbsPath: string,
+  source: string,
+  id: string,
+  attr: string,
+  value: string
+): EditResult {
+  const parsed = parseSync(canvasAbsPath, source, { sourceType: 'module' });
+  if (parsed.errors && parsed.errors.length > 0) {
+    const first = parsed.errors[0];
+    throw new CanvasEditError(
+      `oxc-parser failed on ${canvasAbsPath}: ${first?.message ?? 'unknown'}`,
+      { canvas: canvasAbsPath, id }
+    );
+  }
+
+  const hit = findOpening(parsed.program, id);
+  if (!hit) {
+    throw new CanvasEditError(`data-cd-id "${id}" not found in ${canvasAbsPath}`, {
+      canvas: canvasAbsPath,
+      id,
+    });
+  }
+
+  const s = new MagicString(source);
+  if (attr.startsWith('style.')) {
+    editStyleProp(s, hit.opening, attr.slice('style.'.length), value, canvasAbsPath, id);
+  } else if (attr === 'data-cd-id') {
+    throw new CanvasEditError('data-cd-id is owned by the pipeline; cannot be edited', {
+      canvas: canvasAbsPath,
+      id,
+    });
+  } else {
+    editStringAttr(s, hit.opening, attr, value);
+  }
+
+  const out = s.toString();
+  return { source: out, delta: out.length - source.length };
+}
+
+// ---------------------------------------------------------------------------
+// Edit shapes.
+
+function editStringAttr(s: MagicString, opening: AnyNode, name: string, value: string): void {
+  const attr = findAttribute(opening, name);
+  if (attr) {
+    // Replace existing value. JSX attribute value forms we handle:
+    //   - <Tag name="literal" />           → replace inside the quotes
+    //   - <Tag name={'literal'} />         → wrap quotes around new value
+    //   - <Tag name={expr} />              → replace the whole expression text
+    //   - <Tag name />                     → no value node; add `="..."`
+    const v = attr.value;
+    if (!v) {
+      // <Tag name /> → <Tag name="value" />
+      s.appendLeft(attr.end, `="${escapeAttr(value)}"`);
+      return;
+    }
+    if (v.type === 'Literal' || v.type === 'StringLiteral') {
+      // Replace just the value text, keeping surrounding quotes.
+      s.overwrite(v.start, v.end, JSON.stringify(value));
+      return;
+    }
+    if (v.type === 'JSXExpressionContainer') {
+      // Replace the whole `{...}` with a plain quoted literal — keeps the
+      // resulting JSX readable, no escaping gymnastics.
+      s.overwrite(v.start, v.end, JSON.stringify(value));
+      return;
+    }
+    // Unknown shape — refuse rather than corrupt.
+    throw new Error(`Unsupported JSX attribute value shape: ${v.type}`);
+  }
+  // Attribute missing — insert right after the tag name (mirrors pipeline's
+  // injection point so attribute order stays predictable).
+  const insertAt: number | undefined = opening?.name?.end;
+  if (typeof insertAt !== 'number') {
+    throw new Error('Opening element has no resolvable name range');
+  }
+  s.appendLeft(insertAt, ` ${name}="${escapeAttr(value)}"`);
+}
+
+function escapeAttr(value: string): string {
+  return value.replace(/"/g, '&quot;').replace(/[<>]/g, (c) => (c === '<' ? '&lt;' : '&gt;'));
+}
+
+function editStyleProp(
+  s: MagicString,
+  opening: AnyNode,
+  prop: string,
+  value: string,
+  canvasAbsPath: string,
+  id: string
+): void {
+  const attr = findAttribute(opening, 'style');
+  if (!attr) {
+    // No style prop yet — insert one with a single key.
+    const insertAt: number | undefined = opening?.name?.end;
+    if (typeof insertAt !== 'number') {
+      throw new Error('Opening element has no resolvable name range');
+    }
+    s.appendLeft(insertAt, ` style={{ ${jsKey(prop)}: ${value} }}`);
+    return;
+  }
+  const v = attr.value;
+  if (!v || v.type !== 'JSXExpressionContainer') {
+    throw new CanvasEditError(
+      `style attribute on ${id} is not a {{...}} expression — refusing to edit`,
+      { canvas: canvasAbsPath, id }
+    );
+  }
+  const obj = v.expression;
+  if (!obj || obj.type !== 'ObjectExpression') {
+    throw new CanvasEditError(
+      `style={...} on ${id} is not an inline ObjectExpression — refusing to edit`,
+      { canvas: canvasAbsPath, id }
+    );
+  }
+
+  // Search for an existing property with the same key. JSX styles permit
+  // camelCase identifiers (paddingTop) AND quoted strings ("padding-top").
+  // Compare both forms.
+  const propCamel = prop.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+  for (const p of obj.properties as AnyNode[]) {
+    if (p?.type !== 'Property' && p?.type !== 'ObjectProperty') continue;
+    const k = p.key;
+    if (!k) continue;
+    const kname = k.type === 'Identifier' ? k.name : k.type === 'Literal' ? String(k.value) : null;
+    if (kname === prop || kname === propCamel) {
+      s.overwrite(p.value.start, p.value.end, value);
+      return;
+    }
+  }
+
+  // Key missing — append before the closing `}`. ObjectExpression's last char
+  // is the `}`; magic-string appendLeft at end keeps the brace in place.
+  const props = obj.properties as AnyNode[];
+  const tail = props.length > 0 ? (props[props.length - 1].end as number) : obj.start + 1;
+  const sep = props.length > 0 ? ', ' : ' ';
+  // The object's textual end is `obj.end - 1` for `}` after the chars.
+  // appendLeft at obj.end -1 puts new text before the `}`.
+  s.appendLeft(obj.end - 1, `${sep}${jsKey(prop)}: ${value} `);
+  // Suppress unused-var lint without bypassing TS:
+  void tail;
+}
+
+/**
+ * Render a JS object key — bare identifier when the prop is camelCase + valid
+ * JS id, quoted otherwise. Mirrors how authors write JSX styles.
+ */
+function jsKey(prop: string): string {
+  if (/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(prop)) return prop;
+  return JSON.stringify(prop);
+}
+
+// ---------------------------------------------------------------------------
+// CLI entry. Invoked by bin/canvas-edit.sh — keeps Bun startup off the hot
+// path of /design:edit when the orchestrator shells out.
+//
+// Layout:  bun run canvas-edit.ts --invoke <canvas> <id> <attr> <value>
+
+if (import.meta.main) {
+  const argv = process.argv.slice(2);
+  if (argv[0] === '--invoke' && argv.length === 5) {
+    const [, canvas, id, attr, value] = argv;
+    if (!canvas || !id || !attr || value === undefined) {
+      console.error('canvas-edit: --invoke needs <canvas> <id> <attr> <value>');
+      process.exit(2);
+    }
+    try {
+      const r = await editAttribute(canvas, id, attr, value);
+      console.log(JSON.stringify({ canvas, id, delta: r.delta }));
+      process.exit(0);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error(`canvas-edit: ${msg}`);
+      process.exit(2);
+    }
+  } else {
+    console.error('Usage: bun run canvas-edit.ts --invoke <canvas> <id> <attr> <value>');
+    process.exit(2);
+  }
+}