@1agh/maude 0.28.1 → 0.30.0

package/{plugins/design/dev-server → apps/studio}/api.ts

@@ -3,9 +3,16 @@
 
 import crypto from 'node:crypto';
 import type { Dirent } from 'node:fs';
-import { readdir, readFile, stat as statp } from 'node:fs/promises';
+import { mkdir, readdir, readFile, rename, stat as statp } from 'node:fs/promises';
 import path from 'node:path';
 
+import { renderBriefBoard, validateCanvasName } from './canvas-create.ts';
+import {
+  CanvasEditError,
+  editAttribute,
+  removeAttribute,
+  editText as runEditText,
+} from './canvas-edit.ts';
 import type { Context } from './context.ts';
 
 const SKIP_DIRS = new Set([
@@ -95,6 +102,9 @@ export interface Comment {
   id: string;
   file: string;
   selector: string;
+  /** Occurrence index among `querySelectorAll(selector)` — disambiguates a
+   * component repeated within one artboard. Absent on legacy comments. */
+  index?: number;
   dom_path: string[];
   tag: string;
   classes: string;
@@ -129,6 +139,19 @@ export interface ExportHistoryEntry {
   at: string;
 }
 
+export type CreateCanvasResult =
+  | { ok: true; file: string; rel: string; slug: string }
+  | { ok: false; status: number; error: string };
+
+export type DeleteCanvasResult =
+  | { ok: true; rel: string; slug: string; trashed: string[]; trashDir: string }
+  | { ok: false; status: number; error: string };
+
+/** Phase 12 — result of an in-canvas direct edit (`editCss` / `editText`). */
+export type EditOpResult =
+  | { ok: true; delta: number }
+  | { ok: false; status: number; error: string };
+
 export interface Api {
   // File tree
   fileSlug(file: string): string;
@@ -168,6 +191,35 @@ export interface Api {
   // Annotations sidecar (Phase 5 — .design/<slug>.annotations.svg)
   loadAnnotations(file: string): Promise<string | null>;
   saveAnnotations(file: string, svg: string): Promise<boolean>;
+  // Phase 23 — content-addressed binary image write (drag-drop / paste / picker)
+  saveAsset(bytes: Uint8Array): Promise<SaveAssetResult>;
+  // Create a blank brief board from the browser (Phase 22 — POST /_api/canvas)
+  createCanvas(input: {
+    name?: unknown;
+    kind?: unknown;
+    group?: unknown;
+  }): Promise<CreateCanvasResult>;
+  // Soft-delete a canvas from the browser (Phase 22 — DELETE /_api/canvas)
+  deleteCanvas(input: { file?: unknown }): Promise<DeleteCanvasResult>;
+  // Phase 12 (DDR-103) — single-property inline CSS edit (POST /_api/edit-css).
+  // Main-origin only: writes one key into the element's inline `style={{}}` object.
+  editCss(input: {
+    canvas?: unknown;
+    id?: unknown;
+    property?: unknown;
+    value?: unknown;
+  }): Promise<EditOpResult>;
+  // Phase 12 (DDR-103) — inline text-content edit (POST /_api/edit-text). Main-origin only.
+  editText(input: { canvas?: unknown; id?: unknown; text?: unknown }): Promise<EditOpResult>;
+  // Phase 12.2 (DDR-104) — custom HTML attribute edit (POST /_api/edit-attr). Main-origin
+  // only. The CSS panel's "custom HTML attribute" escape hatch (data-*, aria-*, role, …);
+  // writes a plain JSX attribute via editAttribute's non-`style.` path.
+  editAttr(input: {
+    canvas?: unknown;
+    id?: unknown;
+    attr?: unknown;
+    value?: unknown;
+  }): Promise<EditOpResult>;
   // Aggregate data
   buildIndexData(): Promise<unknown>;
   buildSystemData(dsName?: string | null): Promise<unknown>;
@@ -182,80 +234,92 @@ export interface ApiHooks {
   onAnnotationsChanged?: (file: string, svg: string) => void;
 }
 
+// FigJam v3 — the annotation sanitizer moved to annotations-model.ts (the
+// schema owner; the allowlist guards exactly that vocabulary, and the
+// headless `maude design annotate` write verb needs it without pulling the
+// server modules). Re-exported here so every existing `from './api.ts'`
+// import keeps working unchanged.
+export { ASSET_IMAGE_HREF_RE, sanitizeAnnotationSvg } from './annotations-model.ts';
+
+import { sanitizeAnnotationSvg } from './annotations-model.ts';
+
+/** Phase 23 — hard ceiling on a single uploaded asset (10 MB). */
+export const ASSET_MAX_BYTES = 10 * 1024 * 1024;
+
 /**
- * Elements the annotation tool legitimately emits (`strokesToSvg` in
- * annotations-layer.tsx). This is the WHOLE vocabulary — purely presentational.
+ * Phase 23 security review (DDR-088 follow-up) — aggregate per-server-instance
+ * write budget for `/_api/asset`. Content-addressing dedupes IDENTICAL bytes,
+ * but a one-byte mutation (a PNG `tEXt` chunk / a single pixel) yields a fresh
+ * sha8 each time, so dedup is NOT a disk-fill defense. This caps total bytes a
+ * single dev-server instance will ever write to `assets/` — generous for real
+ * reference material, but bounds a scripted loop from the untrusted canvas
+ * origin. Overridable via `MAUDE_ASSET_SESSION_BUDGET` (bytes) for power users.
  */
-const ANNOTATION_SVG_ELEMENTS = new Set([
-  'svg',
-  'g',
-  'path',
-  'rect',
-  'ellipse',
-  'line',
-  'polyline',
-  // Phase 24 — `polygon` (diamond / triangle shape primitives + closed arrowhead
-  // outlines + diamond heads) and `circle` (circle arrowhead). Inert shape
-  // elements with no script capability — same safety class as the rest.
-  'polygon',
-  'circle',
-  'text',
-]);
+export const ASSET_SESSION_BUDGET = (() => {
+  const env = Number(process.env.MAUDE_ASSET_SESSION_BUDGET);
+  return Number.isFinite(env) && env > 0 ? env : 256 * 1024 * 1024;
+})();
 
 /**
- * A3 (DDR-060 F1 re-audit) — sanitize an annotation SVG before it is persisted /
- * synced / mirrored into the collab Y.Map. ALLOWLIST, not denylist (the F1
- * confirming pass showed a denylist loses the race: `<svg:script>` via namespace,
- * `javascript&#58;` via HTML entity, `<style>@import url()>`, CSS `url(javascript:)`
- * all slipped a tag-name denylist). Two rules, both keyed to the fixed legit
- * vocabulary so they're zero-regression on real annotations:
- *
- *   1. Element allowlist — drop the markup of any tag whose LOCAL name (namespace
- *      stripped, so `svg:script` → `script`) isn't in ANNOTATION_SVG_ELEMENTS.
- *      Dropped-tag text content survives as inert text (not in a script/style
- *      context), which is harmless.
- *   2. Attribute denylist on survivors — the legit vocabulary uses none of
- *      `on*=`, `style=`, or any `href`, so stripping them closes inline handlers,
- *      CSS `url(javascript:)`, and entity-encoded `xlink:href` in one pass.
- *
- * The current consumer (`svgToStrokes` → DOMParser image/svg+xml → structured
- * strokes → React) never raw-renders this string, so the live XSS risk is already
- * nil; this keeps "inert" TRUE for any future raw-render consumer and for the
- * synced file a peer / Claude-context ingests (defense-in-depth, DDR-054 §3).
+ * Phase 23 — content-type sniff from the first bytes (magic numbers). The
+ * declared name / extension / Content-Type is NEVER trusted — the bytes decide
+ * the stored extension (a `.png` name carrying GIF bytes is stored as `.gif`).
+ * SVG (XML/text) matches nothing here → returns null → rejected, so a
+ * script-bearing vector can't ride in through the image route. See DDR (Task 9).
  */
-export function sanitizeAnnotationSvg(svg: string): string {
-  return (
-    svg
-      // 1. Remove the CONTENT of executable / instruction-bearing elements (not
-      //    just their tags) so an injected script body / `@import` / prompt-
-      //    injection string can't survive as inert text a future raw-renderer or
-      //    Claude-context read might act on. Namespace-tolerant (`svg:script`),
-      //    non-greedy to the first matching dangerous close tag.
-      .replace(
-        /<\s*(?:[\w-]+:)?(?:script|style|foreignObject|title|desc)\b[\s\S]*?<\s*\/\s*(?:[\w-]+:)?(?:script|style|foreignObject|title|desc)\s*>/gi,
-        ''
-      )
-      // 2. Element allowlist — drop the markup of any tag whose LOCAL name isn't
-      //    in the fixed annotation vocabulary. `[^>]*` stops at the first `>`;
-      //    annotation attrs never contain a literal `>`.
-      .replace(/<\/?\s*([a-zA-Z][\w:-]*)\b[^>]*>/g, (match, rawName: string) => {
-        const local = String(rawName).split(':').pop()?.toLowerCase() ?? '';
-        return ANNOTATION_SVG_ELEMENTS.has(local) ? match : '';
-      })
-      // 3. Attribute denylist on the surviving allowlisted elements — the legit
-      //    vocabulary uses no on*= / style= / *href=, so stripping them closes
-      //    inline handlers, CSS url(javascript:), and entity-encoded hrefs.
-      //    The leading boundary is a LOOKBEHIND on whitespace / quote / slash
-      //    (not a consumed `\s`) so a handler glued to the previous attribute's
-      //    closing quote — `<circle r="2"onload="…"/>`, which HTML/SVG parsers
-      //    accept as a distinct attribute — is also stripped (Phase 24 security
-      //    review, DDR-067). The non-consuming lookbehind leaves the preceding
-      //    quote intact so the legit attribute it belonged to survives.
-      .replace(
-        /(?<=[\s"'/])(?:on[a-z]+|style|(?:[\w-]+:)?href)\s*=\s*("[^"]*"|'[^']*'|[^\s>]+)/gi,
-        ''
-      )
-  );
+export function sniffImageType(bytes: Uint8Array): 'png' | 'jpg' | 'gif' | 'webp' | null {
+  const b = bytes;
+  // PNG — 89 50 4E 47 0D 0A 1A 0A
+  if (
+    b.length >= 8 &&
+    b[0] === 0x89 &&
+    b[1] === 0x50 &&
+    b[2] === 0x4e &&
+    b[3] === 0x47 &&
+    b[4] === 0x0d &&
+    b[5] === 0x0a &&
+    b[6] === 0x1a &&
+    b[7] === 0x0a
+  ) {
+    return 'png';
+  }
+  // JPEG — FF D8 FF
+  if (b.length >= 3 && b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff) return 'jpg';
+  // GIF — "GIF87a" / "GIF89a"
+  if (
+    b.length >= 6 &&
+    b[0] === 0x47 &&
+    b[1] === 0x49 &&
+    b[2] === 0x46 &&
+    b[3] === 0x38 &&
+    (b[4] === 0x37 || b[4] === 0x39) &&
+    b[5] === 0x61
+  ) {
+    return 'gif';
+  }
+  // WEBP — "RIFF"????"WEBP"
+  if (
+    b.length >= 12 &&
+    b[0] === 0x52 &&
+    b[1] === 0x49 &&
+    b[2] === 0x46 &&
+    b[3] === 0x46 &&
+    b[8] === 0x57 &&
+    b[9] === 0x45 &&
+    b[10] === 0x42 &&
+    b[11] === 0x50
+  ) {
+    return 'webp';
+  }
+  return null;
+}
+
+export interface SaveAssetResult {
+  ok: boolean;
+  status?: number;
+  error?: string;
+  /** Relative `assets/<sha8>.<ext>` path on success. */
+  path?: string;
 }
 
 export function createApi(ctx: Context, hooks: ApiHooks): Api {
@@ -471,6 +535,7 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
       id: newCommentId(),
       file: payload.file,
       selector: String(payload.selector || ''),
+      index: typeof payload.index === 'number' ? payload.index : undefined,
       dom_path: Array.isArray(payload.dom_path) ? payload.dom_path.slice(0, 16) : [],
       tag: String(payload.tag || ''),
       classes: String(payload.classes || ''),
@@ -712,6 +777,444 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     return true;
   }
 
+  // Phase 23 — content-addressed asset write. Reachable from the (potentially
+  // untrusted, DDR-054) canvas origin, so every cap is load-bearing, NOT
+  // optional (DDR Task 9):
+  //   • magic-byte sniff → true type ∈ {png,jpg,gif,webp}; a header lie or an
+  //     SVG (script-bearing vector) is rejected — bytes decide, name is ignored.
+  //   • ≤ 10 MB ceiling (assets get their OWN cap; never routed through the 1 MB
+  //     SVG-text gate in saveAnnotations).
+  //   • content-addressed name `assets/<sha8-of-bytes>.<ext>` → identical drops
+  //     dedupe → a malicious canvas can't fill the disk with N copies of one
+  //     image, and orphan-on-delete is safe (shared content survives).
+  //   • resolved-path containment assert (defense-in-depth; the name carries no
+  //     user input, but a poisoned designRoot must still not escape).
+  // Running total of bytes this server instance has actually written (post-dedupe).
+  let assetBytesWritten = 0;
+  async function saveAsset(bytes: Uint8Array): Promise<SaveAssetResult> {
+    if (!bytes || bytes.length === 0) return { ok: false, status: 400, error: 'empty body' };
+    if (bytes.length > ASSET_MAX_BYTES) {
+      return { ok: false, status: 413, error: 'asset exceeds the 10 MB cap' };
+    }
+    const kind = sniffImageType(bytes);
+    if (!kind) {
+      return {
+        ok: false,
+        status: 415,
+        error: 'unsupported image type — png/jpeg/gif/webp only (SVG rejected)',
+      };
+    }
+    const sha8 = crypto.createHash('sha256').update(bytes).digest('hex').slice(0, 8);
+    const name = `${sha8}.${kind}`;
+    const assetsDir = path.join(paths.designRoot, 'assets');
+    const fileAbs = path.join(assetsDir, name);
+    // Containment backstop — the name is content-addressed (sha8 hex + sniffed
+    // ext), so there is no user-controlled path segment, but assert anyway.
+    const resolved = path.resolve(fileAbs);
+    const assetsResolved = path.resolve(assetsDir);
+    if (resolved !== path.join(assetsResolved, name)) {
+      return { ok: false, status: 400, error: 'resolved asset path escapes assets dir' };
+    }
+    try {
+      // Dedupe — identical bytes hash to the same name; skip the write if present.
+      if (!(await Bun.file(fileAbs).exists())) {
+        // Aggregate write budget (DDR-088 follow-up) — bounds a scripted
+        // one-byte-mutation disk-fill loop from the untrusted canvas origin.
+        // Only a genuinely NEW file counts (a dedupe hit is free).
+        if (assetBytesWritten + bytes.length > ASSET_SESSION_BUDGET) {
+          return {
+            ok: false,
+            status: 429,
+            error: 'asset write budget exceeded for this server session',
+          };
+        }
+        await mkdir(assetsDir, { recursive: true });
+        await Bun.write(fileAbs, bytes);
+        assetBytesWritten += bytes.length;
+      }
+    } catch (err) {
+      return { ok: false, status: 500, error: err instanceof Error ? err.message : 'write failed' };
+    }
+    return { ok: true, path: `assets/${name}` };
+  }
+
+  // Phase 22 — create a blank brief board from the browser file tree. Wired ONLY
+  // on the main origin (server.ts startMainServer); the segregated canvas origin
+  // (DDR-054) never exposes this — an untrusted canvas iframe must not be able to
+  // write arbitrary `.tsx` files. The single user-controlled value (`name`) is
+  // gated by `validateCanvasName` (path + JSX + JSON injection boundary); `group`
+  // is allowlisted to the configured canvas groups; a `resolve()` containment
+  // assert is the defense-in-depth backstop.
+  async function createCanvas(input: {
+    name?: unknown;
+    kind?: unknown;
+    group?: unknown;
+  }): Promise<CreateCanvasResult> {
+    // v1 only stamps blank boards — generation stays with `/design:new` (Claude).
+    const kind = input.kind == null || input.kind === '' ? 'brief-board' : input.kind;
+    if (kind !== 'brief-board') {
+      return { ok: false, status: 400, error: 'only kind "brief-board" is supported' };
+    }
+    const v = validateCanvasName(input.name);
+    if (!v.ok || !v.name || !v.componentName) {
+      return { ok: false, status: 400, error: v.error ?? 'invalid name' };
+    }
+
+    // Group must be one of the configured canvas groups (+ the new-canvas dir).
+    const allowed = new Set<string>(cfg.canvasGroups.map((g) => g.path));
+    allowed.add(cfg.newCanvasDir || 'ui');
+    const group =
+      input.group == null || input.group === '' ? cfg.newCanvasDir || 'ui' : String(input.group);
+    if (!allowed.has(group)) {
+      return { ok: false, status: 400, error: `group must be one of: ${[...allowed].join(', ')}` };
+    }
+
+    const groupAbs = path.join(paths.designRoot, group);
+    const fileAbs = path.join(groupAbs, `${v.name}.tsx`);
+    // Containment backstop, two layers (Phase 22 security review F2). The name
+    // regex already forbids traversal, but `group` comes from config
+    // (canvasGroups[].path / newCanvasDir), which `normalizeConfig` does NOT
+    // validate for `..`. So assert (1) the GROUP resolves inside designRoot —
+    // a config-supplied `../../etc` must not relocate the write out of the
+    // project — and (2) the file resolves inside that group. Without (1) a
+    // poisoned config would be an arbitrary-directory `.tsx` write (latent today
+    // because config isn't sync-scoped; closed now so a future config-sync can't
+    // re-open it).
+    const resolvedDesignRoot = path.resolve(paths.designRoot);
+    const resolvedGroup = path.resolve(groupAbs);
+    if (
+      resolvedGroup !== resolvedDesignRoot &&
+      !resolvedGroup.startsWith(`${resolvedDesignRoot}${path.sep}`)
+    ) {
+      return { ok: false, status: 400, error: 'canvas group resolves outside the design root' };
+    }
+    if (
+      path.resolve(fileAbs) !== path.join(resolvedGroup, `${v.name}.tsx`) ||
+      !path.resolve(fileAbs).startsWith(`${resolvedGroup}${path.sep}`)
+    ) {
+      return { ok: false, status: 400, error: 'resolved path escapes the canvas group' };
+    }
+    if (await Bun.file(fileAbs).exists()) {
+      return {
+        ok: false,
+        status: 409,
+        error: `a canvas named "${v.name}" already exists in ${group}`,
+      };
+    }
+
+    const rel = path.posix.join(group, `${v.name}.tsx`);
+    const slug = fileSlug(rel);
+    const dsName = cfg.defaultDesignSystem || 'project';
+    const platform = 'desktop';
+    const tsx = renderBriefBoard({
+      name: v.name,
+      componentName: v.componentName,
+      dsName,
+      platform,
+      seedHint: 'Empty brief board — annotate me',
+      historyDir: path.posix.join(paths.designRel, '_history', slug),
+    });
+    const now = new Date().toISOString();
+    const meta = {
+      kind: 'brief-board',
+      title: v.name,
+      subtitle: 'brief board',
+      brief: v.name,
+      designSystem: dsName,
+      platform,
+      created: now,
+      last_modified: now,
+    };
+    await Bun.write(fileAbs, tsx);
+    await Bun.write(
+      path.join(groupAbs, `${v.name}.meta.json`),
+      `${JSON.stringify(meta, null, 2)}\n`
+    );
+    // designRel-prefixed path — matches the file-tree `file.path` shape so the
+    // client can open it directly after reloadTree().
+    return { ok: true, file: path.posix.join(paths.designRel, rel), rel, slug };
+  }
+
+  // Phase 22 — SOFT-delete a canvas (DELETE /_api/canvas). Same trust boundary as
+  // createCanvas: main-origin-only, never the untrusted canvas iframe origin
+  // (DDR-054). Destructive, so it MOVES the whole sidecar set to
+  // `<designRoot>/_trash/<stamp>__<slug>/` (recoverable locally) instead of a hard
+  // rm — pairs with the existing `_history/` + /design:rollback model. Hub
+  // propagation of the delete is deliberately out of scope (Phase 26 consent).
+  async function deleteCanvas(input: { file?: unknown }): Promise<DeleteCanvasResult> {
+    const raw = input?.file;
+    if (typeof raw !== 'string' || !raw.trim()) {
+      return { ok: false, status: 400, error: 'file is required' };
+    }
+    let rel = raw.trim();
+    try {
+      rel = decodeURIComponent(rel);
+    } catch {
+      /* leave as-is */
+    }
+    rel = rel.replace(/^\/+/, '');
+    const prefix = `${paths.designRel.replace(/^\/+|\/+$/g, '')}/`;
+    if (rel.startsWith(prefix)) rel = rel.slice(prefix.length);
+
+    // Only a real `.tsx` canvas, no traversal.
+    if (rel.includes('..')) return { ok: false, status: 400, error: 'invalid path' };
+    if (!/\.tsx$/i.test(rel)) {
+      return { ok: false, status: 400, error: 'only .tsx canvases can be deleted' };
+    }
+
+    const fileAbs = path.join(paths.designRoot, rel);
+    const resolvedDesignRoot = path.resolve(paths.designRoot);
+    const resolvedFile = path.resolve(fileAbs);
+    if (
+      resolvedFile !== resolvedDesignRoot &&
+      !resolvedFile.startsWith(`${resolvedDesignRoot}${path.sep}`)
+    ) {
+      return { ok: false, status: 400, error: 'path escapes the design root' };
+    }
+
+    // Must live under a NON-DS canvas group — never the design system (`system`),
+    // never a loose root file (config.json, README). Deleting DS sources is not a
+    // canvas operation.
+    const deletable = cfg.canvasGroups.filter(
+      (g) => g.label !== 'Design system' && !/^system(\/|$)/.test(g.path)
+    );
+    const inGroup = deletable.some((g) => {
+      const gAbs = path.resolve(path.join(paths.designRoot, g.path));
+      return resolvedFile.startsWith(`${gAbs}${path.sep}`);
+    });
+    if (!inGroup) {
+      return {
+        ok: false,
+        status: 400,
+        error: 'only canvases under a managed canvas group can be deleted',
+      };
+    }
+
+    if (!(await Bun.file(fileAbs).exists())) {
+      return { ok: false, status: 404, error: 'canvas not found' };
+    }
+
+    const slug = fileSlug(rel);
+    const base = path.basename(rel).replace(/\.tsx$/i, '');
+    const groupDir = path.dirname(fileAbs);
+    // Filesystem-safe wall-clock stamp (no `:`) so repeated deletes of the same
+    // canvas don't collide in _trash.
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const trashDir = path.join(paths.designRoot, '_trash', `${stamp}__${slug}`);
+    await mkdir(trashDir, { recursive: true });
+
+    const trashed: string[] = [];
+    const moveIfExists = async (src: string, destName: string) => {
+      try {
+        await statp(src); // throws if absent (works for files AND dirs)
+      } catch {
+        return;
+      }
+      try {
+        await rename(src, path.join(trashDir, destName));
+        trashed.push(path.relative(paths.designRoot, src));
+      } catch {
+        /* best-effort — a sidecar that can't move shouldn't abort the delete */
+      }
+    };
+
+    // Primary + the full sidecar set (annotations, meta, history, canvas-state,
+    // comments). Flattened names so the trash dir is a self-contained bundle.
+    await moveIfExists(fileAbs, `${base}.tsx`);
+    await moveIfExists(path.join(groupDir, `${base}.meta.json`), `${base}.meta.json`);
+    await moveIfExists(
+      path.join(paths.designRoot, `${slug}.annotations.svg`),
+      `${slug}.annotations.svg`
+    );
+    await moveIfExists(path.join(paths.designRoot, '_history', slug), `_history__${slug}`);
+    await moveIfExists(
+      path.join(paths.canvasStateDir, `${slug}.json`),
+      `_canvas-state__${slug}.json`
+    );
+    await moveIfExists(path.join(paths.commentsDir, `${slug}.json`), `_comments__${slug}.json`);
+
+    await Bun.write(
+      path.join(trashDir, '_trash-manifest.json'),
+      `${JSON.stringify({ canvas: rel, slug, deletedAt: new Date().toISOString(), trashed }, null, 2)}\n`
+    );
+
+    return {
+      ok: true,
+      rel,
+      slug,
+      trashed,
+      trashDir: path.relative(paths.repoRoot, trashDir),
+    };
+  }
+
+  // Phase 12 (DDR-103) — resolve a v2 canvas slug (`selected.canvas`: POSIX,
+  // extension-less, designRoot-relative — matches `_locator.json` keys + the
+  // `canvasSlug()` shape) to its absolute `.tsx` path, with a containment
+  // backstop. Same main-origin-only trust boundary as createCanvas: the
+  // untrusted canvas iframe origin never reaches a source-write endpoint.
+  function resolveCanvasAbs(
+    slugRaw: unknown
+  ): { ok: true; abs: string } | { ok: false; status: number; error: string } {
+    if (typeof slugRaw !== 'string' || !slugRaw.trim()) {
+      return { ok: false, status: 400, error: 'canvas (slug) required' };
+    }
+    let slug = slugRaw.replace(/^\/+|\/+$/g, '').replace(/\.(tsx|html)$/i, '');
+    // Accept either the bare slug (`ui/Foo`) or the designRel-prefixed file path
+    // the client `selected.file` carries (`.design/ui/Foo.tsx`) — strip a leading
+    // designRel so both shapes resolve to the same canvas (mirrors deriveCanvasSlug).
+    const dr = paths.designRel.replace(/^\.\//, '').replace(/^\/+|\/+$/g, '');
+    if (dr && slug.startsWith(`${dr}/`)) slug = slug.slice(dr.length + 1);
+    if (
+      !slug ||
+      path.isAbsolute(slug) ||
+      slug.split('/').some((seg) => seg === '..' || seg === '.' || seg === '')
+    ) {
+      return { ok: false, status: 400, error: 'invalid canvas slug' };
+    }
+    const abs = `${path.join(paths.designRoot, ...slug.split('/'))}.tsx`;
+    const resolvedRoot = path.resolve(paths.designRoot);
+    const resolved = path.resolve(abs);
+    if (!resolved.startsWith(`${resolvedRoot}${path.sep}`)) {
+      return { ok: false, status: 400, error: 'canvas resolves outside the design root' };
+    }
+    return { ok: true, abs };
+  }
+
+  // 8-hex lowercase, the shape `computeId` (canvas-edit.ts) stamps on data-cd-id.
+  const CD_ID_RE = /^[0-9a-f]{8}$/;
+
+  async function editCss(input: {
+    canvas?: unknown;
+    id?: unknown;
+    property?: unknown;
+    value?: unknown;
+    reset?: unknown;
+  }): Promise<EditOpResult> {
+    const r = resolveCanvasAbs(input.canvas);
+    if (!r.ok) return r;
+    const id = typeof input.id === 'string' ? input.id.trim() : '';
+    if (!CD_ID_RE.test(id)) return { ok: false, status: 400, error: 'invalid data-cd-id' };
+    const property = typeof input.property === 'string' ? input.property.trim() : '';
+    // CSS property names are ASCII letters + hyphens only (optionally a leading
+    // `-` for vendor prefixes) — reject anything that could smuggle a second key
+    // or an expression into the inline style object.
+    if (!property || !/^-?[a-z][a-z-]*$/.test(property)) {
+      return { ok: false, status: 400, error: 'invalid css property' };
+    }
+    // kebab → camelCase JSX style key.
+    const camel = property.replace(/-([a-z])/g, (_m, c: string) => c.toUpperCase());
+    // Phase 12.3 — `reset: true` REMOVES the inline property (back to class /
+    // inherited). No value needed; a missing key is a no-op (delta 0).
+    if (input.reset === true) {
+      try {
+        const res = await removeAttribute(r.abs, id, `style.${camel}`);
+        return { ok: true, delta: res.delta };
+      } catch (err) {
+        return {
+          ok: false,
+          status: 422,
+          error: err instanceof CanvasEditError ? err.message : 'reset failed',
+        };
+      }
+    }
+    const value = typeof input.value === 'string' ? input.value : '';
+    if (!value.trim()) return { ok: false, status: 400, error: 'value required' };
+    if (value.length > 256) return { ok: false, status: 413, error: 'value too long' };
+    // The value is always written as a JS STRING literal: JSON.stringify escapes
+    // quotes/backslashes/newlines so it can never break out of the string, and
+    // React accepts string values for every style prop — so `var(--accent)`,
+    // `#fff`, `8px`, `700`, `1.5` all ride verbatim.
+    try {
+      const res = await editAttribute(r.abs, id, `style.${camel}`, JSON.stringify(value));
+      return { ok: true, delta: res.delta };
+    } catch (err) {
+      return {
+        ok: false,
+        status: 422,
+        error: err instanceof CanvasEditError ? err.message : 'edit failed',
+      };
+    }
+  }
+
+  async function editText(input: {
+    canvas?: unknown;
+    id?: unknown;
+    text?: unknown;
+  }): Promise<EditOpResult> {
+    const r = resolveCanvasAbs(input.canvas);
+    if (!r.ok) return r;
+    const id = typeof input.id === 'string' ? input.id.trim() : '';
+    if (!CD_ID_RE.test(id)) return { ok: false, status: 400, error: 'invalid data-cd-id' };
+    if (typeof input.text !== 'string') return { ok: false, status: 400, error: 'text required' };
+    if (input.text.length > 5000) return { ok: false, status: 413, error: 'text too long' };
+    try {
+      const res = await runEditText(r.abs, id, input.text);
+      return { ok: true, delta: res.delta };
+    } catch (err) {
+      return {
+        ok: false,
+        status: 422,
+        error: err instanceof CanvasEditError ? err.message : 'edit failed',
+      };
+    }
+  }
+
+  async function editAttr(input: {
+    canvas?: unknown;
+    id?: unknown;
+    attr?: unknown;
+    value?: unknown;
+    reset?: unknown;
+  }): Promise<EditOpResult> {
+    const r = resolveCanvasAbs(input.canvas);
+    if (!r.ok) return r;
+    const id = typeof input.id === 'string' ? input.id.trim() : '';
+    if (!CD_ID_RE.test(id)) return { ok: false, status: 400, error: 'invalid data-cd-id' };
+    const attr = typeof input.attr === 'string' ? input.attr.trim() : '';
+    // Plain HTML attributes only — data-*, aria-*, role, title, id, lang, dir…
+    // Reject `style*` (that's /_api/edit-css), `data-cd-id` (pipeline-owned, also
+    // refused downstream by editAttribute), and anything that isn't a bare html
+    // attribute name. Digits allowed mid-name (e.g. data-2x).
+    if (
+      !attr ||
+      !/^[a-z][a-z0-9-]*$/.test(attr) ||
+      attr === 'data-cd-id' ||
+      attr.startsWith('style')
+    ) {
+      return { ok: false, status: 400, error: 'invalid attribute' };
+    }
+    // Phase 12.3 — `reset: true` REMOVES the custom attribute. No-op if absent.
+    if (input.reset === true) {
+      try {
+        const res = await removeAttribute(r.abs, id, attr);
+        return { ok: true, delta: res.delta };
+      } catch (err) {
+        return {
+          ok: false,
+          status: 422,
+          error: err instanceof CanvasEditError ? err.message : 'reset failed',
+        };
+      }
+    }
+    const value = typeof input.value === 'string' ? input.value : '';
+    if (!value.trim()) return { ok: false, status: 400, error: 'value required' };
+    if (value.length > 256) return { ok: false, status: 413, error: 'value too long' };
+    try {
+      // Non-`style.` attr name → editAttribute writes a plain quoted JSX attribute.
+      // Pass the value RAW: editStringAttr quotes/escapes it itself (JSON.stringify
+      // on replace, escapeAttr on insert) — pre-stringifying here double-encoded
+      // the value (`data-x="\"ok\""`; knob-smoke finding, 2026-06-12).
+      const res = await editAttribute(r.abs, id, attr, value);
+      return { ok: true, delta: res.delta };
+    } catch (err) {
+      return {
+        ok: false,
+        status: 422,
+        error: err instanceof CanvasEditError ? err.message : 'edit failed',
+      };
+    }
+  }
+
   async function saveCanvasState(file: string, state: Record<string, unknown>) {
     if (!state || typeof state !== 'object') return;
     const safe: Record<string, unknown> = {};
@@ -732,6 +1235,28 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
   async function buildIndexData() {
     const groups = [];
 
+    // DDR-093 — per-canvas design-system map (repo-relative canvas path → DS
+    // name) so the client's canvasUrl() injects each UI canvas's OWN tokens
+    // instead of unconditionally designSystems[0]. Populated from the canvas
+    // groups below; returned on the payload and folded into the client cfg.
+    const canvasDesignSystems: Record<string, string> = {};
+    const defaultDs = cfg.defaultDesignSystem || cfg.designSystems?.[0]?.name || 'project';
+    // A file under `system/<folder>/` belongs to the DS that owns that folder —
+    // path-authoritative, because specimens/ui_kits rarely carry a sidecar
+    // `designSystem`. Returns null for `ui/` canvases (resolved via sidecar).
+    const ownerDsName = (repoRelPath: string): string | null => {
+      let r = repoRelPath;
+      const prefix = `${paths.designRel}/`;
+      if (r.startsWith(prefix)) r = r.slice(prefix.length);
+      const m = r.match(/^system\/([^/]+)\//);
+      if (!m) return null;
+      const folder = m[1];
+      const owner = (cfg.designSystems ?? []).find(
+        (d) => d.path === `system/${folder}` || d.path.endsWith(`/${folder}`)
+      );
+      return owner?.name ?? null;
+    };
+
     // PROJECT — top-level .design/ files (README.md, INDEX.md, config.json, …).
     // These are non-HTML so they're listed but not openable in the iframe; the
     // sidebar can still display them as context (mirrors CV-08 mock).
@@ -777,6 +1302,20 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
       const filePaths = isDs
         ? await findFiles(groupAbs, groupRel, ['.tsx', '.html', '.md', '.css', '.json'])
         : await findFiles(groupAbs, groupRel, ['.tsx', '.html', '.css', '.json']);
+      // DDR-093 — record each `.tsx` canvas's design system. canvasUrl() only
+      // injects tokens for `.tsx`, so skip everything else. Path-owned DS wins
+      // (system/<ds>/…); otherwise the sidecar's `meta.designSystem`, defaulting
+      // to the project default when the canvas declares none.
+      for (const fp of filePaths) {
+        if (!fp.endsWith('.tsx')) continue;
+        let dsName = ownerDsName(fp);
+        if (!dsName) {
+          const meta = await loadCanvasMeta(fp);
+          const declared = meta?.designSystem;
+          dsName = typeof declared === 'string' && declared.trim() ? declared : defaultDs;
+        }
+        canvasDesignSystems[fp] = dsName;
+      }
       // Strip down to `g.path` so per-DS folders (`project`, `beta`, …) show
       // up as the top-level dirs inside the DS section. Single-DS configs get
       // a wrapper folder too — slightly more verbose, but consistent with
@@ -837,6 +1376,7 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
       projectLabel: ctx.projectLabel,
       designRoot: paths.designRel,
       groups,
+      canvasDesignSystems,
     };
   }
 
@@ -1078,6 +1618,12 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     patchCanvasMeta,
     loadAnnotations,
     saveAnnotations,
+    saveAsset,
+    createCanvas,
+    deleteCanvas,
+    editCss,
+    editText,
+    editAttr,
     buildIndexData,
     buildSystemData,
     loadExportHistory,