@1agh/maude 0.45.2 → 0.47.0

package/apps/studio/api.ts

@@ -12,8 +12,14 @@ import {
   assembleCompSource,
   CanvasEditError,
   type ClipInfo,
+  type ConvertChildBox,
+  type ConvertContainerSpec,
+  componentMapForCanvas,
+  convertToAbsolute,
   deleteArtboard,
   deleteElement,
+  detachComponent,
+  duplicateArtboard,
   duplicateElement,
   type EditScope,
   editArrayElementString,
@@ -34,7 +40,10 @@ import {
   retimeSequence,
   retimeSequenceByClip,
   editText as runEditText,
+  setArtboardGuides,
   setArtboardHug,
+  setArtboardKind,
+  setArtboardPrint,
   setArtboardStyle,
   toggleClipHidden,
 } from './canvas-edit.ts';
@@ -47,6 +56,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
@@ -438,6 +448,21 @@ export interface Api {
   }): Promise<
     { ok: true; deletedId: string; seq?: number } | { ok: false; status: number; error: string }
   >;
+  /**
+   * feature-4 T8 (convert-to-absolute, DDR-188) — rewrite a container's stamped
+   * children to `position:absolute` with frozen boxes (+ container relative), in
+   * ONE whole-file write with ONE undo `seq`.
+   */
+  convertChildrenToAbsoluteOp(input: {
+    canvas?: unknown;
+    containerId?: unknown;
+    containerIdIndex?: unknown;
+    containerSetRelative?: unknown;
+    allowShared?: unknown;
+    children?: unknown;
+    containers?: unknown;
+    dissolve?: unknown;
+  }): Promise<{ ok: true; seq?: number } | { ok: false; status: number; error: string }>;
   /**
    * Insert a synthesized div/text/image relative to a reference element, OR —
    * when the artboard has no element to anchor on yet — as a direct child of
@@ -465,6 +490,14 @@ export interface Api {
   }): Promise<
     { ok: true; artboardId: string; seq?: number } | { ok: false; status: number; error: string }
   >;
+  /** Duplicate an artboard at a new width (feature-3-web-artboards T3). */
+  duplicateArtboardOp(input: {
+    canvas?: unknown;
+    artboardId?: unknown;
+    width?: unknown;
+  }): Promise<
+    { ok: true; artboardId: string; seq?: number } | { ok: false; status: number; error: string }
+  >;
   /** Free-hand artboard resize — write width/height numeric props (DDR-027, D4). */
   resizeArtboardOp(input: {
     canvas?: unknown;
@@ -488,6 +521,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;
@@ -507,6 +558,21 @@ export interface Api {
     id?: unknown;
     rendered?: unknown;
   }): Promise<({ ok: true } & EditScope) | { ok: false; status: number; error: string }>;
+  /** feature-4 T7a — Layers-panel component map (purple instance rows). */
+  componentMapOp(input: {
+    canvas?: unknown;
+  }): Promise<
+    | { ok: true; map: Record<string, { component: string; root: boolean; usages: number }> }
+    | { ok: false; status: number; error: string }
+  >;
+  /** feature-4 detach-component — clone the definition + repoint ONE usage. */
+  detachComponentOp(input: {
+    canvas?: unknown;
+    id?: unknown;
+    idIndex?: unknown;
+  }): Promise<
+    { ok: true; detachedName: string; seq?: number } | { ok: false; status: number; error: string }
+  >;
   // Undo/redo a prior reorder by seq (Cmd+Z from the canvas undo stack). Whole-
   // file content swap from the in-memory revert log — immune to the positional
   // data-cd-id churn a reorder causes (inverse-descriptor undo would go stale).
@@ -1214,16 +1280,87 @@ 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;
+  }
+
+  // feature-4 T7b — per-user LOCKED layer keys (`"<cdId>:<occurrenceIndex>"`).
+  // Runtime state per DDR-115 (like the camera + overlays): view.json, never the
+  // versioned `.meta.json`. Reachable from the untrusted canvas origin via the
+  // same PATCH lane, so shape + count are bounded.
+  const MAX_LOCKED_KEYS = 500;
+  const LOCKED_KEY_RE = /^[\w-]{1,64}:\d{1,4}$/;
+
+  function normalizeLocked(v: unknown): string[] | null {
+    if (!Array.isArray(v) || v.length > MAX_LOCKED_KEYS) return null;
+    const out: string[] = [];
+    for (const k of v) {
+      if (typeof k !== 'string' || !LOCKED_KEY_RE.test(k)) return null;
+      out.push(k);
+    }
+    return [...new Set(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>;
+    locked?: string[];
+  } | 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 lk = normalizeLocked((obj as { locked?: unknown }).locked);
+        const result: {
+          viewport?: { x: number; y: number; zoom: number };
+          overlays?: Record<string, boolean>;
+          locked?: string[];
+        } = {};
+        if (vp) result.viewport = vp;
+        if (ov && Object.keys(ov).length > 0) result.overlays = ov;
+        if (lk && lk.length > 0) result.locked = lk;
+        return result;
       }
       return null;
     } catch {
@@ -1233,7 +1370,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 +1382,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 +1443,20 @@ 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;
+    // feature-4 T7b — `locked` (per-user locked layer keys) is the same class.
+    obj.locked = 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;
+    if (view?.locked) obj.locked = view.locked;
+    // 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 && !view?.locked) return null;
     return obj;
   }
 
@@ -1331,6 +1509,53 @@ 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);
+      }
+    }
+
+    // --- Per-user locked-layers lane (feature-4 T7b): locked → view file,
+    // never the versioned meta. REPLACE semantics (the client sends the full
+    // set — merge semantics would make unlocking impossible); `null` clears; an
+    // invalid array is a silent no-op (normalizeLocked → null).
+    if (patch.locked !== undefined) {
+      const viewAbs = canvasViewPath(file);
+      if (viewAbs) {
+        try {
+          const current = await readCanvasViewRaw(file);
+          if (patch.locked === null) {
+            const { locked: _drop, ...rest } = current;
+            await mkdir(paths.canvasStateDir, { recursive: true });
+            await Bun.write(viewAbs, `${JSON.stringify(rest, null, 2)}\n`);
+          } else {
+            const lk = normalizeLocked(patch.locked);
+            if (lk !== null) {
+              await mkdir(paths.canvasStateDir, { recursive: true });
+              await Bun.write(viewAbs, `${JSON.stringify({ ...current, locked: lk }, null, 2)}\n`);
+            }
+          }
+        } catch {
+          /* best-effort */
+        }
+      }
+    }
+
     // --- Shared document lane: layout → versioned meta, stamps last_modified. ---
     if (patch.layout !== undefined) {
       let current: Record<string, unknown> = {};
@@ -2263,7 +2488,12 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
   }
 
   // 8-hex lowercase, the shape `computeId` (canvas-edit.ts) stamps on data-cd-id.
-  const CD_ID_RE = /^[0-9a-f]{8}$/;
+  // Pipeline-injected ids are 8-hex, but hand-AUTHORED `data-cd-id` attrs are
+  // preserved verbatim by the transpile (canvas-pipeline.ts) and are equally
+  // valid targets (dogfood 2026-07-20: `data-cd-id="wal-hero-nav"`). Accept
+  // both — word chars + dashes, bounded; the AST walkers do exact matching, so
+  // this is only a shape gate.
+  const CD_ID_RE = /^[\w-]{1,64}$/;
 
   // RC1 (rca/issue-canvas-hmr-optimistic-update-consistency) — every inline
   // edit is USER-originated (inspector CSS knobs, inline text, attr panel, and
@@ -2803,6 +3033,229 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     }
   }
 
+  /**
+   * feature-4 T8 (convert-to-absolute, DDR-188) — the "Remove auto layout"
+   * analogue. Rewrite every stamped child of a container to `position:absolute`
+   * with the frozen box the canvas measured, and set the container
+   * `position:relative` when static — ONE whole-file write, ONE undo `seq`. The
+   * canvas iframe pre-filters to plain, globally-unique children (no unstamped /
+   * repeated / component instances); the AST writer's `resolveUsageId` guard is
+   * the server-side backstop for a shared-component usage.
+   */
+  async function convertChildrenToAbsoluteOp(input: {
+    canvas?: unknown;
+    containerId?: unknown;
+    containerIdIndex?: unknown;
+    containerSetRelative?: unknown;
+    allowShared?: unknown;
+    children?: unknown;
+    containers?: unknown;
+    dissolve?: 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 num = (v: unknown): number | null =>
+      typeof v === 'number' && Number.isFinite(v) && Math.abs(v) <= 1_000_000
+        ? Math.round(v)
+        : null;
+    // Simplifier fix (review fan-out, 2026-07-21) — reuse canvas-edit.ts's own
+    // exported spec types instead of a locally re-declared shape, which had
+    // drifted (missing `freezeSize?`, populated a few lines below via a spread
+    // that silently bypassed excess-property checking).
+    const parseChildren = (raw: unknown): ConvertChildBox[] | string => {
+      if (!Array.isArray(raw) || raw.length === 0) return 'children required';
+      const out: ConvertChildBox[] = [];
+      for (const c of raw as Array<Record<string, unknown>>) {
+        const id = typeof c?.id === 'string' ? c.id.trim() : '';
+        if (!CD_ID_RE.test(id)) return 'invalid child data-cd-id';
+        const left = num(c.left);
+        const top = num(c.top);
+        const width = num(c.width);
+        const height = num(c.height);
+        if (left === null || top === null || width === null || height === null) {
+          return 'invalid child box (left/top/width/height)';
+        }
+        const idIndex = Number.isInteger(c.idIndex) ? (c.idIndex as number) : undefined;
+        out.push({ id, idIndex, left, top, width, height });
+      }
+      return out;
+    };
+
+    // feature-4 artboard-level convert (2026-07-19) — MULTI-container batch.
+    // Each container: optional containerId (absent = the artboard-body root
+    // level), a setRelative flag, and its children boxes. Total child count is
+    // capped across the batch.
+    let containersSpec: ConvertContainerSpec[] | undefined;
+    if (input.containers !== undefined) {
+      if (!Array.isArray(input.containers) || input.containers.length === 0) {
+        return { ok: false, status: 400, error: 'invalid containers' };
+      }
+      if (input.containers.length > 200) {
+        return { ok: false, status: 400, error: 'too many containers' };
+      }
+      containersSpec = [];
+      let total = 0;
+      for (const c of input.containers as Array<Record<string, unknown>>) {
+        let containerId: string | undefined;
+        if (c?.containerId !== undefined && c.containerId !== null) {
+          const cid = typeof c.containerId === 'string' ? c.containerId.trim() : '';
+          if (!CD_ID_RE.test(cid)) {
+            return {
+              ok: false,
+              status: 400,
+              error: `invalid container data-cd-id (${String(c.containerId).slice(0, 64)})`,
+            };
+          }
+          containerId = cid;
+        }
+        const kids = parseChildren(c?.children);
+        if (typeof kids === 'string') return { ok: false, status: 400, error: kids };
+        total += kids.length;
+        if (total > 500) return { ok: false, status: 400, error: 'too many children' };
+        let freezeSize: { width: number; height: number } | undefined;
+        if (c?.freezeSize && typeof c.freezeSize === 'object') {
+          const fw = num((c.freezeSize as Record<string, unknown>).width);
+          const fh = num((c.freezeSize as Record<string, unknown>).height);
+          if (fw !== null && fh !== null) freezeSize = { width: fw, height: fh };
+        }
+        containersSpec.push({
+          containerId,
+          containerIdIndex: Number.isInteger(c?.containerIdIndex)
+            ? (c.containerIdIndex as number)
+            : undefined,
+          containerSetRelative: c?.containerSetRelative === true,
+          ...(freezeSize ? { freezeSize } : {}),
+          children: kids,
+        });
+      }
+    }
+
+    // Legacy single-container shape (the element context-menu action).
+    let containerId = '';
+    let containerIdIndex: number | undefined;
+    let containerSetRelative = false;
+    let children: ConvertChildBox[] = [];
+    if (!containersSpec) {
+      containerId = typeof input.containerId === 'string' ? input.containerId.trim() : '';
+      if (!CD_ID_RE.test(containerId)) {
+        return { ok: false, status: 400, error: 'invalid container data-cd-id' };
+      }
+      containerIdIndex = Number.isInteger(input.containerIdIndex)
+        ? (input.containerIdIndex as number)
+        : undefined;
+      containerSetRelative = input.containerSetRelative === true;
+      if (Array.isArray(input.children) && input.children.length > 500) {
+        return { ok: false, status: 400, error: 'too many children' };
+      }
+      const kids = parseChildren(input.children);
+      if (typeof kids === 'string') return { ok: false, status: 400, error: kids };
+      children = kids;
+    }
+    const rel = path.relative(paths.designRoot, r.abs);
+    ctx.bus.emit('activity:suppress', rel);
+    try {
+      const before = await Bun.file(r.abs).text();
+      if (before.length > MAX_CANVAS_SOURCE) {
+        ctx.bus.emit('activity:unsuppress', rel);
+        return { ok: false, status: 413, error: 'canvas source too large' };
+      }
+      // feature-4 TRUE FLATTEN — validated dissolve list (batch shape only).
+      let dissolve: string[] | undefined;
+      if (input.dissolve !== undefined) {
+        if (!Array.isArray(input.dissolve) || input.dissolve.length > 200) {
+          return { ok: false, status: 400, error: 'invalid dissolve list' };
+        }
+        dissolve = [];
+        for (const d of input.dissolve) {
+          const id = typeof d === 'string' ? d.trim() : '';
+          if (!CD_ID_RE.test(id)) {
+            return { ok: false, status: 400, error: 'invalid dissolve data-cd-id' };
+          }
+          dissolve.push(id);
+        }
+      }
+      const res = await convertToAbsolute(
+        r.abs,
+        containersSpec
+          ? { allowShared: input.allowShared === true, containers: containersSpec, dissolve }
+          : {
+              containerId,
+              containerIdIndex,
+              containerSetRelative,
+              allowShared: input.allowShared === true,
+              children,
+            }
+      );
+      const after = res.source;
+      if (!res.changed || after === before) {
+        ctx.bus.emit('activity:unsuppress', rel);
+        return { ok: true };
+      }
+      try {
+        await history.writeSnapshot(rel, before, 'pre-convert-absolute');
+      } 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 : 'convert-to-absolute failed',
+      };
+    }
+  }
+
+  /**
+   * feature-4 detach-component (2026-07-19) — clone the component definition
+   * under a fresh name + repoint THIS usage at the clone, so subsequent edits
+   * stay local to this instance. Whole-file undo seq (Stage-I lane).
+   */
+  async function detachComponentOp(input: {
+    canvas?: unknown;
+    id?: unknown;
+    idIndex?: unknown;
+  }): Promise<
+    { ok: true; detachedName: string; seq?: number } | { ok: false; status: number; error: string }
+  > {
+    const r = resolveCanvasAbs(input.canvas);
+    if (!r.ok) return r;
+    if (!takeStructuralToken()) return RATE_LIMITED;
+    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 idIndex = Number.isInteger(input.idIndex) ? (input.idIndex as number) : undefined;
+    const rel = path.relative(paths.designRoot, r.abs);
+    ctx.bus.emit('activity:suppress', rel);
+    try {
+      const before = await Bun.file(r.abs).text();
+      if (before.length > MAX_CANVAS_SOURCE) {
+        ctx.bus.emit('activity:unsuppress', rel);
+        return { ok: false, status: 413, error: 'canvas source too large to grow' };
+      }
+      const res = await detachComponent(r.abs, id, idIndex);
+      const after = res.source;
+      if (!res.changed || after === before) {
+        ctx.bus.emit('activity:unsuppress', rel);
+        return { ok: true, detachedName: res.detachedName };
+      }
+      try {
+        await history.writeSnapshot(rel, before, 'pre-detach-component');
+      } catch {
+        /* snapshot best-effort */
+      }
+      return { ok: true, detachedName: res.detachedName, 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 : 'detach failed',
+      };
+    }
+  }
+
   /** Insert a new empty artboard (id/label/width/height) after the last one. */
   async function insertArtboardOp(input: {
     canvas?: unknown;
@@ -2858,6 +3311,59 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     }
   }
 
+  /**
+   * Duplicate an artboard at a new width (feature-3-web-artboards T3,
+   * "Duplicate at width…") — clones id/label/width, everything else
+   * (kind/guides/print/style/children) carries over verbatim.
+   */
+  async function duplicateArtboardOp(input: {
+    canvas?: unknown;
+    artboardId?: unknown;
+    width?: unknown;
+  }): Promise<
+    { ok: true; artboardId: string; 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 artboardId' };
+    }
+    const width = Number.isFinite(Number(input.width))
+      ? Math.max(64, Math.min(8192, Math.round(Number(input.width))))
+      : 0;
+    if (!width) return { ok: false, status: 400, error: 'width required' };
+    const rel = path.relative(paths.designRoot, r.abs);
+    ctx.bus.emit('activity:suppress', rel);
+    try {
+      const before = await Bun.file(r.abs).text();
+      if (before.length > MAX_CANVAS_SOURCE) {
+        ctx.bus.emit('activity:unsuppress', rel);
+        return { ok: false, status: 413, error: 'canvas source too large to grow' };
+      }
+      const res = await duplicateArtboard(r.abs, artboardId, width);
+      const after = await Bun.file(r.abs).text();
+      if (after === before) {
+        ctx.bus.emit('activity:unsuppress', rel);
+        return { ok: true, artboardId: res.artboardId };
+      }
+      try {
+        await history.writeSnapshot(rel, before, 'pre-duplicate-artboard');
+      } catch {
+        /* snapshot best-effort */
+      }
+      return { ok: true, artboardId: res.artboardId, 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 : 'duplicate-artboard failed',
+      };
+    }
+  }
+
   /** Free-hand artboard resize (D4) — write width/height NUMERIC props (DDR-027). */
   async function resizeArtboardOp(input: {
     canvas?: unknown;
@@ -2952,6 +3458,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 +3665,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 +3685,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) {
@@ -3146,6 +3848,42 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     }
   }
 
+  /**
+   * feature-4 T7a (layers purple instances) — the component map for the shell's
+   * Layers panel: `{ [cdId]: { component, root, usages } }` for every element
+   * that renders through an instantiated component. READ-only parse (same
+   * posture as editScopeOp).
+   */
+  async function componentMapOp(input: {
+    canvas?: unknown;
+  }): Promise<
+    | { ok: true; map: Record<string, { component: string; root: boolean; usages: number }> }
+    | { ok: false; status: number; error: string }
+  > {
+    const r = resolveCanvasAbs(input.canvas);
+    if (!r.ok) return r;
+    try {
+      const file = Bun.file(r.abs);
+      // Security fix (review fan-out, 2026-07-21) — this route is AUTO-fetched
+      // by the shell on every canvas/artboard switch (no user action), unlike
+      // the sibling edit-scope route it mirrors. Per this repo's hub-push
+      // threat model (DDR-060), a peer could otherwise cost a collaborator
+      // CPU/memory the moment they merely open a pathologically large synced
+      // canvas — cap it the same way the structural-write ops cap `before`.
+      if (file.size > MAX_CANVAS_SOURCE) {
+        return { ok: false, status: 413, error: 'canvas source too large' };
+      }
+      const source = await file.text();
+      return { ok: true, map: componentMapForCanvas(r.abs, source) };
+    } catch (err) {
+      return {
+        ok: false,
+        status: 500,
+        error: err instanceof Error ? err.message : 'component map failed',
+      };
+    }
+  }
+
   async function toggleHideOp(input: {
     canvas?: unknown;
     stableId?: unknown;
@@ -3766,15 +4504,22 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     compClips,
     reorder,
     retimeSequenceOp,
+    convertChildrenToAbsoluteOp,
+    detachComponentOp,
     deleteElementOp,
     insertElementOp,
     insertArtboardOp,
     resizeArtboardOp,
     setArtboardHugOp,
     setArtboardStyleOp,
+    setArtboardKindOp,
+    setArtboardGuidesOp,
+    setArtboardPrintOp,
     deleteArtboardOp,
+    duplicateArtboardOp,
     duplicateElementOp,
     editScopeOp,
+    componentMapOp,
     reorderRevert,
     buildIndexData,
     buildSystemData,