@1agh/maude 0.45.2 → 0.46.0

package/apps/studio/acp/bridge.ts

@@ -202,6 +202,40 @@ function withTimeout<T>(p: Promise<T>, ms: number): Promise<T | typeof TIMED_OUT
  * `LoadSessionRequest` (schema/types.gen.d.ts) — `sessionFor`'s resume path
  * spreads this same object and adds `sessionId` rather than duplicating it.
  */
+// The curated tool allow-list every Maude bridge session auto-approves, so the
+// design workflow (edit a canvas, then shell out to the `maude` CLI + its design
+// helpers) runs without a permission prompt on EVERY step — the out-of-box
+// "Manual mode blocks every edit" complaint this closes (DDR-184). Deliberately
+// NARROW, and a complement to (not a reversal of) DDR-179's "mode picker stays
+// honest": the session mode is left untouched at its default, so anything NOT on
+// this list still routes through the real approve/deny gate (requestPermission →
+// PermissionPrompt) — arbitrary `Bash(curl …)`/`rm`, WebFetch, unknown MCP tools.
+//
+//  • File tools (Read/Edit/Write/Glob/Grep/NotebookEdit) — the canvas-editing
+//    surface. Auto-approving Edit/Write is the accepted residual: edits land in
+//    the served project (already the edit target) and are reversible via the
+//    `_history/` snapshot stack.
+//  • `Bash(maude:*)` — the SINGLE rule that covers the entire design-helper
+//    surface, because DDR-062 routes every helper through `maude design <verb>`
+//    (screenshot / draw-* / canvas-rects / probe-footage / …) and their own deps
+//    (agent-browser, playwright, svgo) run as CHILDREN of that one bash call, so
+//    they need no separate entry. Bash NOT starting with `maude` still prompts.
+//
+// SOURCE-OF-TRUTH GUARD: this list is asserted against the `maude design` verb
+// dispatch (`cli/commands/design.mjs`) + `plugins/design/dependencies.json` by
+// acp-session-allowed-tools.test.ts — a future helper that is NOT reached via
+// `maude design` (a brand-new top-level tool, not a new verb) fails that test
+// loudly instead of silently prompting the user mid-workflow.
+export const MAUDE_DEFAULT_ALLOWED_TOOLS: readonly string[] = [
+  'Read',
+  'Edit',
+  'Write',
+  'Glob',
+  'Grep',
+  'NotebookEdit',
+  'Bash(maude:*)',
+];
+
 export function newSessionParams(
   repoRoot: string,
   studioBrief?: string,
@@ -219,7 +253,15 @@ export function newSessionParams(
   // deputy chain (the DDR-143 guard #6 follow-up). The project's CLAUDE.md is read
   // via a separate path and is unaffected. Always injected — every Maude bridge
   // session is auto-approving. `...plugins` (DDR-143) rides the same options object.
-  const options: Record<string, unknown> = { settingSources: ['user'] };
+  const options: Record<string, unknown> = {
+    settingSources: ['user'],
+    // DDR-184 — auto-approve Maude's own first-party tool surface so the design
+    // workflow never stalls on a per-edit / per-`maude` permission prompt. Rides
+    // the same `_meta.claudeCode.options` spread as `plugins`/`settings` below
+    // (`...userProvidedOptions`, acp-agent.js:2333→2455) into the SDK's
+    // `allowedTools` (sdk.d.ts:1331). Everything off this list still prompts.
+    allowedTools: [...MAUDE_DEFAULT_ALLOWED_TOOLS],
+  };
   if (plugins && plugins.length > 0) {
     options.plugins = plugins;
     // DDR-168 — the bundled `design` plugin is now injected UNCONDITIONALLY

package/apps/studio/annotations-snap.ts

@@ -30,6 +30,20 @@ export interface SnapResult {
   guides: SnapGuide[];
 }
 
+/**
+ * T7 (feature-1-artboard-kinds-foundation) — a generic-layout-guide line
+ * (T5), in WORLD coordinates, offered to `computeSnap` the same way a
+ * stroke/artboard bbox candidate is. `at`/`from`/`to` mirror `SnapGuide`'s own
+ * shape (this IS the line, not a box to derive one from) — the caller
+ * (annotations-layer.tsx) resolves an artboard's `guides` prop into these.
+ */
+export interface GuideLineCandidate {
+  axis: 'x' | 'y';
+  at: number;
+  from: number;
+  to: number;
+}
+
 /** Snap threshold in world px at zoom 1 (callers scale by 1/zoom). */
 export const SNAP_THRESHOLD_PX = 6;
 
@@ -61,17 +75,26 @@ function gridDelta(pos: number, pitch: number, threshold: number): number | null
  * leading edge falls back to the canvas dot grid — weaker than smart guides
  * (geometry alignment wins over the lattice) and silent (no guide line, the
  * dots themselves are the visual). ⌘ suppresses both via the caller.
+ *
+ * T7 — `opts.guideLines` (generic layout guides, T5) feed the SAME candidate
+ * pool as stroke/artboard bboxes: each line is tested against all three
+ * moving lines (leading edge, center, trailing edge), exactly like a
+ * sibling/artboard edge, and competes on equal footing (nearest within
+ * threshold wins — a closer stroke edge still beats a farther guide line).
  */
 export function computeSnap(
   moving: SnapBox,
   candidates: readonly SnapBox[],
   threshold: number,
-  opts?: { grid?: number }
+  opts?: { grid?: number; guideLines?: readonly GuideLineCandidate[] }
 ): SnapResult {
   const grid = opts?.grid ?? 0;
-  if (threshold <= 0 || (candidates.length === 0 && grid <= 0)) return NO_SNAP;
-  let bestX: { d: number; at: number; cand: SnapBox } | null = null;
-  let bestY: { d: number; at: number; cand: SnapBox } | null = null;
+  const guideLines = opts?.guideLines ?? [];
+  if (threshold <= 0 || (candidates.length === 0 && guideLines.length === 0 && grid <= 0)) {
+    return NO_SNAP;
+  }
+  let bestX: { d: number; at: number; from: number; to: number } | null = null;
+  let bestY: { d: number; at: number; from: number; to: number } | null = null;
   const mx = lines(moving, 'x');
   const my = lines(moving, 'y');
   for (const c of candidates) {
@@ -81,7 +104,7 @@ export function computeSnap(
       for (const v of cx) {
         const d = v - m;
         if (Math.abs(d) <= threshold && (!bestX || Math.abs(d) < Math.abs(bestX.d))) {
-          bestX = { d, at: v, cand: c };
+          bestX = { d, at: v, from: c.y, to: c.y + c.h };
         }
       }
     }
@@ -89,7 +112,24 @@ export function computeSnap(
       for (const v of cy) {
         const d = v - m;
         if (Math.abs(d) <= threshold && (!bestY || Math.abs(d) < Math.abs(bestY.d))) {
-          bestY = { d, at: v, cand: c };
+          bestY = { d, at: v, from: c.x, to: c.x + c.w };
+        }
+      }
+    }
+  }
+  for (const g of guideLines) {
+    if (g.axis === 'x') {
+      for (const m of mx) {
+        const d = g.at - m;
+        if (Math.abs(d) <= threshold && (!bestX || Math.abs(d) < Math.abs(bestX.d))) {
+          bestX = { d, at: g.at, from: g.from, to: g.to };
+        }
+      }
+    } else {
+      for (const m of my) {
+        const d = g.at - m;
+        if (Math.abs(d) <= threshold && (!bestY || Math.abs(d) < Math.abs(bestY.d))) {
+          bestY = { d, at: g.at, from: g.from, to: g.to };
         }
       }
     }
@@ -109,16 +149,16 @@ export function computeSnap(
     guides.push({
       axis: 'x',
       at: bestX.at,
-      from: Math.min(moving.y + dy, bestX.cand.y),
-      to: Math.max(moving.y + moving.h + dy, bestX.cand.y + bestX.cand.h),
+      from: Math.min(moving.y + dy, bestX.from),
+      to: Math.max(moving.y + moving.h + dy, bestX.to),
     });
   }
   if (bestY) {
     guides.push({
       axis: 'y',
       at: bestY.at,
-      from: Math.min(moving.x + dx, bestY.cand.x),
-      to: Math.max(moving.x + moving.w + dx, bestY.cand.x + bestY.cand.w),
+      from: Math.min(moving.x + dx, bestY.from),
+      to: Math.max(moving.x + moving.w + dx, bestY.to),
     });
   }
   return { dx, dy, guides };

package/apps/studio/api.ts

@@ -34,7 +34,10 @@ import {
   retimeSequence,
   retimeSequenceByClip,
   editText as runEditText,
+  setArtboardGuides,
   setArtboardHug,
+  setArtboardKind,
+  setArtboardPrint,
   setArtboardStyle,
   toggleClipHidden,
 } from './canvas-edit.ts';
@@ -47,6 +50,7 @@ import {
 } from './generation/audio-library.ts';
 import { createHistory } from './history.ts';
 import { STICKERS_DIR } from './paths.ts';
+import { getPaperPreset, MAX_PRINT_MM } from './print/units.ts';
 
 // Directories that never hold user-facing canvases. Exported so the
 // external-canvas watcher (`canvas-list-watch.ts`) shares one source instead of
@@ -488,6 +492,24 @@ export interface Api {
     layout?: unknown;
     gap?: unknown;
   }): Promise<{ ok: true; seq?: number } | { ok: false; status: number; error: string }>;
+  /** Kind-switch surfaces (T8) — context menu + Inspector picker. */
+  setArtboardKindOp(input: {
+    canvas?: unknown;
+    artboardId?: unknown;
+    kind?: unknown;
+  }): Promise<{ ok: true; seq?: number } | { ok: false; status: number; error: string }>;
+  /** Generic layout guides (T5) — replace-whole-prop write. */
+  setArtboardGuidesOp(input: {
+    canvas?: unknown;
+    artboardId?: unknown;
+    guides?: unknown;
+  }): Promise<{ ok: true; seq?: number } | { ok: false; status: number; error: string }>;
+  /** feature-2-print-artboards T2 — paper/orientation/bleed/margins, replace-whole-prop write. */
+  setArtboardPrintOp(input: {
+    canvas?: unknown;
+    artboardId?: unknown;
+    print?: unknown;
+  }): Promise<{ ok: true; seq?: number } | { ok: false; status: number; error: string }>;
   /** Duplicate an element (Cmd+D) — a copy as the next sibling, whole-file undo. */
   duplicateElementOp(input: {
     canvas?: unknown;
@@ -1214,16 +1236,66 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     return path.join(paths.canvasStateDir, `${fileSlug(file)}.view.json`);
   }
 
-  async function loadCanvasView(
-    file: string
-  ): Promise<{ viewport?: { x: number; y: number; zoom: number } } | null> {
+  const MAX_OVERLAY_KEYS = 32;
+  const MAX_OVERLAY_KEY_LEN = 64;
+
+  /**
+   * Validate a candidate overlay-visibility bag — feature-1-artboard-kinds-
+   * foundation T6. A flat string→boolean map (`{ guides: true }`); downstream
+   * plans (print bleed, web breakpoints) add their own keys without a schema
+   * change here. Reachable from the untrusted canvas origin (DDR-054) via the
+   * same `/_api/canvas-meta` PATCH the viewport lane already uses, so it's
+   * capped the same way `set-artboard-style` caps its patch shape — bounded
+   * key COUNT and key LENGTH, not just type. Empty object is valid (an
+   * explicit "nothing on" state); malformed input is null (silent no-op).
+   */
+  function normalizeOverlays(v: unknown): Record<string, boolean> | null {
+    if (!v || typeof v !== 'object' || Array.isArray(v)) return null;
+    const entries = Object.entries(v as Record<string, unknown>);
+    if (entries.length > MAX_OVERLAY_KEYS) return null;
+    const out: Record<string, boolean> = {};
+    for (const [k, val] of entries) {
+      if (k.length === 0 || k.length > MAX_OVERLAY_KEY_LEN) return null;
+      if (typeof val !== 'boolean') return null;
+      out[k] = val;
+    }
+    return out;
+  }
+
+  /** Raw view-file contents, tolerant of a missing/corrupt file (→ `{}`) — the
+   *  read half of the read-modify-write both `saveCanvasView` and
+   *  `saveCanvasOverlays` need so writing one lane never clobbers the other. */
+  async function readCanvasViewRaw(file: string): Promise<Record<string, unknown>> {
+    const viewAbs = canvasViewPath(file);
+    if (!viewAbs) return {};
+    try {
+      const obj = JSON.parse(await Bun.file(viewAbs).text());
+      return obj && typeof obj === 'object' && !Array.isArray(obj)
+        ? (obj as Record<string, unknown>)
+        : {};
+    } catch {
+      return {};
+    }
+  }
+
+  async function loadCanvasView(file: string): Promise<{
+    viewport?: { x: number; y: number; zoom: number };
+    overlays?: Record<string, boolean>;
+  } | null> {
     const viewAbs = canvasViewPath(file);
     if (!viewAbs) return null;
     try {
       const obj = JSON.parse(await Bun.file(viewAbs).text());
       if (obj && typeof obj === 'object' && !Array.isArray(obj)) {
         const vp = normalizeViewport((obj as { viewport?: unknown }).viewport);
-        return vp ? { viewport: vp } : {};
+        const ov = normalizeOverlays((obj as { overlays?: unknown }).overlays);
+        const result: {
+          viewport?: { x: number; y: number; zoom: number };
+          overlays?: Record<string, boolean>;
+        } = {};
+        if (vp) result.viewport = vp;
+        if (ov && Object.keys(ov).length > 0) result.overlays = ov;
+        return result;
       }
       return null;
     } catch {
@@ -1233,7 +1305,8 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
 
   /** Persist the per-user camera. Validates + clamps; best-effort (mkdir the
    *  bucket if absent). Returns the normalized viewport on write, null when the
-   *  path is rejected or the viewport is invalid (no write). */
+   *  path is rejected or the viewport is invalid (no write). Read-modify-write
+   *  so an existing `overlays` key in the same view file survives. */
   async function saveCanvasView(
     file: string,
     viewport: unknown
@@ -1244,13 +1317,44 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     if (!vp) return null;
     try {
       await mkdir(paths.canvasStateDir, { recursive: true });
-      await Bun.write(viewAbs, `${JSON.stringify({ viewport: vp }, null, 2)}\n`);
+      const current = await readCanvasViewRaw(file);
+      await Bun.write(viewAbs, `${JSON.stringify({ ...current, viewport: vp }, null, 2)}\n`);
       return vp;
     } catch {
       return null;
     }
   }
 
+  /**
+   * Persist the per-user overlay-visibility bag (T6). Shallow-merges into
+   * whatever `overlays` the view file already has — a `{ guides: true }` patch
+   * doesn't erase a `bleed` key a downstream print-plan toggle already set.
+   * Never touches the versioned `.meta.json`. Read-modify-write so an existing
+   * `viewport` key survives.
+   */
+  async function saveCanvasOverlays(
+    file: string,
+    overlays: unknown
+  ): Promise<Record<string, boolean> | null> {
+    const viewAbs = canvasViewPath(file);
+    if (!viewAbs) return null;
+    const ov = normalizeOverlays(overlays);
+    if (ov === null) return null;
+    try {
+      await mkdir(paths.canvasStateDir, { recursive: true });
+      const current = await readCanvasViewRaw(file);
+      const prevOverlays =
+        current.overlays && typeof current.overlays === 'object' && !Array.isArray(current.overlays)
+          ? (current.overlays as Record<string, unknown>)
+          : {};
+      const merged = normalizeOverlays({ ...prevOverlays, ...ov }) ?? ov;
+      await Bun.write(viewAbs, `${JSON.stringify({ ...current, overlays: merged }, null, 2)}\n`);
+      return merged;
+    } catch {
+      return null;
+    }
+  }
+
   async function loadCanvasMeta(file: string): Promise<Record<string, unknown> | null> {
     const metaAbs = canvasMetaPath(file);
     if (!metaAbs) return null;
@@ -1274,11 +1378,17 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     // codebase convention + biome's noDelete.)
     obj.viewport = undefined;
     obj.last_modified = undefined;
+    // T6 — `overlays` (per-user guide/mark visibility) is runtime state same as
+    // `viewport`; a versioned `.meta.json` should never carry one (sanitizer),
+    // but strip defensively before overlaying the real per-user value below.
+    obj.overlays = undefined;
     const view = await loadCanvasView(file);
     if (view?.viewport) obj.viewport = view.viewport;
-    // Preserve the historic contract: no meta AND no camera → null (GET → {},
-    // PATCH-on-rejected-path → 404). A view-only canvas still returns its camera.
-    if (!hadMeta && !view?.viewport) return null;
+    if (view?.overlays) obj.overlays = view.overlays;
+    // Preserve the historic contract: no meta AND no camera/overlays → null
+    // (GET → {}, PATCH-on-rejected-path → 404). A view-only canvas still
+    // returns its camera/overlays.
+    if (!hadMeta && !view?.viewport && !view?.overlays) return null;
     return obj;
   }
 
@@ -1331,6 +1441,27 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
       }
     }
 
+    // --- Per-user overlay-visibility lane (T6): overlays → view file, never
+    // the versioned meta. Same shape as the viewport lane above — `null`
+    // clears, an invalid bag is a silent no-op (normalizeOverlays → null).
+    if (patch.overlays !== undefined) {
+      if (patch.overlays === null) {
+        const viewAbs = canvasViewPath(file);
+        if (viewAbs) {
+          try {
+            const current = await readCanvasViewRaw(file);
+            const { overlays: _drop, ...rest } = current;
+            await mkdir(paths.canvasStateDir, { recursive: true });
+            await Bun.write(viewAbs, `${JSON.stringify(rest, null, 2)}\n`);
+          } catch {
+            /* best-effort clear */
+          }
+        }
+      } else {
+        await saveCanvasOverlays(file, patch.overlays);
+      }
+    }
+
     // --- Shared document lane: layout → versioned meta, stamps last_modified. ---
     if (patch.layout !== undefined) {
       let current: Record<string, unknown> = {};
@@ -2952,6 +3083,193 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     }
   }
 
+  const ARTBOARD_KIND_VALUES = new Set(['digital', 'print', 'web', 'video']);
+
+  /** Kind-switch surfaces (T8): context menu + Inspector picker. */
+  async function setArtboardKindOp(input: {
+    canvas?: unknown;
+    artboardId?: unknown;
+    kind?: unknown;
+  }): Promise<{ ok: true; seq?: number } | { ok: false; status: number; error: string }> {
+    const r = resolveCanvasAbs(input.canvas);
+    if (!r.ok) return r;
+    if (!takeStructuralToken()) return RATE_LIMITED;
+    const artboardId = typeof input.artboardId === 'string' ? input.artboardId.trim() : '';
+    if (!/^[A-Za-z][\w-]{0,63}$/.test(artboardId)) {
+      return { ok: false, status: 400, error: 'invalid artboard id' };
+    }
+    let kind: string | null;
+    if (input.kind === null) {
+      kind = null;
+    } else if (typeof input.kind === 'string' && ARTBOARD_KIND_VALUES.has(input.kind)) {
+      kind = input.kind;
+    } else {
+      return { ok: false, status: 400, error: 'invalid kind' };
+    }
+    const rel = path.relative(paths.designRoot, r.abs);
+    ctx.bus.emit('activity:suppress', rel);
+    try {
+      const before = await Bun.file(r.abs).text();
+      await setArtboardKind(r.abs, artboardId, kind);
+      const after = await Bun.file(r.abs).text();
+      if (after === before) {
+        ctx.bus.emit('activity:unsuppress', rel);
+        return { ok: true };
+      }
+      try {
+        await history.writeSnapshot(rel, before, 'pre-set-artboard-kind');
+      } catch {
+        /* snapshot best-effort */
+      }
+      return { ok: true, seq: logUndo(r.abs, before, after) };
+    } catch (err) {
+      ctx.bus.emit('activity:unsuppress', rel);
+      return {
+        ok: false,
+        status: err instanceof CanvasEditError ? 422 : 500,
+        error: err instanceof Error ? err.message : 'set-artboard-kind failed',
+      };
+    }
+  }
+
+  const MAX_GUIDES_JSON_BYTES = 4096;
+
+  /** Generic layout guides (T5) — Inspector/skill writer. Replace-whole-prop,
+   *  never a deep merge (see applySetArtboardGuides's own doc comment). */
+  async function setArtboardGuidesOp(input: {
+    canvas?: unknown;
+    artboardId?: unknown;
+    guides?: unknown;
+  }): Promise<{ ok: true; seq?: number } | { ok: false; status: number; error: string }> {
+    const r = resolveCanvasAbs(input.canvas);
+    if (!r.ok) return r;
+    if (!takeStructuralToken()) return RATE_LIMITED;
+    const artboardId = typeof input.artboardId === 'string' ? input.artboardId.trim() : '';
+    if (!/^[A-Za-z][\w-]{0,63}$/.test(artboardId)) {
+      return { ok: false, status: 400, error: 'invalid artboard id' };
+    }
+    let guides: Record<string, unknown> | null;
+    if (input.guides === null) {
+      guides = null;
+    } else if (
+      input.guides &&
+      typeof input.guides === 'object' &&
+      !Array.isArray(input.guides) &&
+      JSON.stringify(input.guides).length <= MAX_GUIDES_JSON_BYTES
+    ) {
+      guides = input.guides as Record<string, unknown>;
+    } else {
+      return { ok: false, status: 400, error: 'invalid guides' };
+    }
+    const rel = path.relative(paths.designRoot, r.abs);
+    ctx.bus.emit('activity:suppress', rel);
+    try {
+      const before = await Bun.file(r.abs).text();
+      await setArtboardGuides(r.abs, artboardId, guides);
+      const after = await Bun.file(r.abs).text();
+      if (after === before) {
+        ctx.bus.emit('activity:unsuppress', rel);
+        return { ok: true };
+      }
+      try {
+        await history.writeSnapshot(rel, before, 'pre-set-artboard-guides');
+      } catch {
+        /* snapshot best-effort */
+      }
+      return { ok: true, seq: logUndo(r.abs, before, after) };
+    } catch (err) {
+      ctx.bus.emit('activity:unsuppress', rel);
+      return {
+        ok: false,
+        status: err instanceof CanvasEditError ? 422 : 500,
+        error: err instanceof Error ? err.message : 'set-artboard-guides failed',
+      };
+    }
+  }
+
+  const PRINT_ORIENTATION_VALUES = new Set(['portrait', 'landscape']);
+
+  function isFiniteMmOrUndefined(v: unknown): v is number | undefined {
+    return (
+      v === undefined ||
+      (typeof v === 'number' && Number.isFinite(v) && v >= 0 && v <= MAX_PRINT_MM)
+    );
+  }
+
+  /**
+   * feature-2-print-artboards T2 — paper/orientation/bleed/margins. Replace-
+   * whole-prop (see applySetArtboardPrint's own doc comment) — the caller
+   * sends the full merged object, not a delta. `print: null` clears the
+   * prop. Shape validation lives HERE (canvas-edit.ts stays generic
+   * Record<string, unknown> AST surgery, same split as setArtboardGuidesOp).
+   */
+  async function setArtboardPrintOp(input: {
+    canvas?: unknown;
+    artboardId?: unknown;
+    print?: unknown;
+  }): Promise<{ ok: true; seq?: number } | { ok: false; status: number; error: string }> {
+    const r = resolveCanvasAbs(input.canvas);
+    if (!r.ok) return r;
+    if (!takeStructuralToken()) return RATE_LIMITED;
+    const artboardId = typeof input.artboardId === 'string' ? input.artboardId.trim() : '';
+    if (!/^[A-Za-z][\w-]{0,63}$/.test(artboardId)) {
+      return { ok: false, status: 400, error: 'invalid artboard id' };
+    }
+    let print: Record<string, unknown> | null;
+    if (input.print === null) {
+      print = null;
+    } else if (input.print && typeof input.print === 'object' && !Array.isArray(input.print)) {
+      const p = input.print as Record<string, unknown>;
+      if (typeof p.paper !== 'string' || !getPaperPreset(p.paper)) {
+        return { ok: false, status: 400, error: 'invalid or unknown paper preset' };
+      }
+      if (p.orientation !== undefined && !PRINT_ORIENTATION_VALUES.has(p.orientation as string)) {
+        return { ok: false, status: 400, error: 'invalid orientation' };
+      }
+      if (!isFiniteMmOrUndefined(p.bleedMm)) {
+        return { ok: false, status: 400, error: 'invalid bleedMm' };
+      }
+      if (p.marginsMm !== undefined) {
+        if (typeof p.marginsMm !== 'object' || p.marginsMm === null || Array.isArray(p.marginsMm)) {
+          return { ok: false, status: 400, error: 'invalid marginsMm' };
+        }
+        const m = p.marginsMm as Record<string, unknown>;
+        for (const side of ['top', 'right', 'bottom', 'left']) {
+          if (!isFiniteMmOrUndefined(m[side])) {
+            return { ok: false, status: 400, error: `invalid marginsMm.${side}` };
+          }
+        }
+      }
+      print = p;
+    } else {
+      return { ok: false, status: 400, error: 'invalid print' };
+    }
+    const rel = path.relative(paths.designRoot, r.abs);
+    ctx.bus.emit('activity:suppress', rel);
+    try {
+      const before = await Bun.file(r.abs).text();
+      await setArtboardPrint(r.abs, artboardId, print);
+      const after = await Bun.file(r.abs).text();
+      if (after === before) {
+        ctx.bus.emit('activity:unsuppress', rel);
+        return { ok: true };
+      }
+      try {
+        await history.writeSnapshot(rel, before, 'pre-set-artboard-print');
+      } catch {
+        /* snapshot best-effort */
+      }
+      return { ok: true, seq: logUndo(r.abs, before, after) };
+    } catch (err) {
+      ctx.bus.emit('activity:unsuppress', rel);
+      return {
+        ok: false,
+        status: err instanceof CanvasEditError ? 422 : 500,
+        error: err instanceof Error ? err.message : 'set-artboard-print failed',
+      };
+    }
+  }
+
   const ARTBOARD_LAYOUT_VALUES = new Set(['block', 'flex-col', 'flex-row', 'grid']);
 
   /** Set artboard "more settings" — background / padding / layout / gap. */
@@ -2972,9 +3290,9 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     }
     const patch: {
       background?: string | null;
-      padding?: number | null;
+      padding?: number | string | null;
       layout?: string | null;
-      gap?: number | null;
+      gap?: number | string | null;
     } = {};
     if ('background' in input) {
       if (input.background === null) patch.background = null;
@@ -2992,19 +3310,28 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
         return { ok: false, status: 400, error: 'invalid layout' };
       }
     }
-    const clampBoxDim = (v: unknown): number | null | undefined => {
+    // Dogfood (artboard panel ↔ shared inspector controls) — padding/gap
+    // accept a design-token binding alongside raw px. STRICT single-var shape
+    // (not a free-form CSS string like `background`): the value lands in a
+    // JSX prop AND in `.dc-artboard-body`'s inline style, so anything beyond
+    // one `var(--…)` reference is rejected rather than round-tripped.
+    const BOX_TOKEN_RE = /^var\(--[a-zA-Z0-9_-]{1,64}\)$/;
+    const clampBoxDim = (v: unknown): number | string | null | undefined => {
       if (v === null) return null;
       if (v === undefined) return undefined;
+      if (typeof v === 'string' && BOX_TOKEN_RE.test(v)) return v;
       return Number.isFinite(Number(v)) ? Math.max(0, Math.min(512, Math.round(Number(v)))) : NaN;
     };
     if ('padding' in input) {
       const p = clampBoxDim(input.padding);
-      if (Number.isNaN(p)) return { ok: false, status: 400, error: 'invalid padding' };
+      if (typeof p === 'number' && Number.isNaN(p))
+        return { ok: false, status: 400, error: 'invalid padding' };
       patch.padding = p;
     }
     if ('gap' in input) {
       const g = clampBoxDim(input.gap);
-      if (Number.isNaN(g)) return { ok: false, status: 400, error: 'invalid gap' };
+      if (typeof g === 'number' && Number.isNaN(g))
+        return { ok: false, status: 400, error: 'invalid gap' };
       patch.gap = g;
     }
     if (Object.keys(patch).length === 0) {
@@ -3772,6 +4099,9 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     resizeArtboardOp,
     setArtboardHugOp,
     setArtboardStyleOp,
+    setArtboardKindOp,
+    setArtboardGuidesOp,
+    setArtboardPrintOp,
     deleteArtboardOp,
     duplicateElementOp,
     editScopeOp,