@1agh/maude 0.45.2 → 0.47.0

package/apps/studio/canvas-edit.ts

@@ -82,6 +82,23 @@ interface OpeningHit {
  * pipeline uses, so the ID arithmetic stays in lockstep. Returns null if no
  * match.
  */
+/**
+ * Hand-authored `data-cd-id` literal on an opening element, when present. The
+ * pipeline PRESERVES an authored id (it skips injection — canvas-pipeline.ts
+ * `hasJsxAttr` gate), so the DOM carries the AUTHORED value while the
+ * positional `computeId` for that element never exists anywhere. Every walker
+ * that maps ids therefore has to prefer the authored literal — without this,
+ * authored-id elements were unreachable by the whole edit engine (dogfood
+ * 2026-07-20: "Convert failed: invalid container data-cd-id" on
+ * `data-cd-id="wal-hero-nav"`).
+ */
+function authoredCdId(opening: AnyNode): string | null {
+  const attr = findAttribute(opening, 'data-cd-id');
+  const v = attr?.value;
+  if (v?.type === 'Literal' && typeof v.value === 'string' && v.value) return v.value;
+  return null;
+}
+
 function findOpening(program: AnyNode, targetId: string): OpeningHit | null {
   interface Frame {
     componentName: string;
@@ -112,7 +129,7 @@ function findOpening(program: AnyNode, targetId: string): OpeningHit | null {
       const frame = stack[stack.length - 1] as Frame;
       const idx = frame.jsxIndex;
       frame.jsxIndex += 1;
-      const id = computeId(frame.componentName, idx);
+      const id = authoredCdId(node.openingElement) ?? computeId(frame.componentName, idx);
       if (id === targetId) {
         hit = { opening: node.openingElement, element: node };
       }
@@ -689,6 +706,14 @@ function objPropValue(objExpr: AnyNode, propName: string): AnyNode | null {
  */
 function resolveValueNode(program: AnyNode, expr: AnyNode, depth = 0): AnyNode | null {
   if (!expr || depth > 8) return null;
+  // Unwrap `x as T` / `x satisfies T` type-cast wrappers (e.g. a shared
+  // `print={A1_PRINT as any}` prop, or a `const X = {...} as const`
+  // declaration) — the cast carries no runtime value, so the wrapped
+  // expression is what every branch below actually needs to match against.
+  while (expr && (expr.type === 'TSAsExpression' || expr.type === 'TSSatisfiesExpression')) {
+    expr = expr.expression;
+  }
+  if (!expr) return null;
   if (isStringLit(expr)) return expr;
   if (expr.type === 'ObjectExpression' || expr.type === 'ArrayExpression') return expr;
   if (expr.type === 'Identifier') {
@@ -974,7 +999,10 @@ function collectElements(program: AnyNode): Array<{ id: string; node: AnyNode }>
       const frame = stack[stack.length - 1] as Frame;
       const idx = frame.jsxIndex;
       frame.jsxIndex += 1;
-      out.push({ id: computeId(frame.componentName, idx), node });
+      out.push({
+        id: authoredCdId(node.openingElement) ?? computeId(frame.componentName, idx),
+        node,
+      });
       if (node.openingElement) visit(node.openingElement.attributes);
       visit(node.children);
       if (pushed) stack.pop();
@@ -1034,7 +1062,7 @@ function collectElementsFull(
       const idx = frame.jsxIndex;
       frame.jsxIndex += 1;
       out.push({
-        id: computeId(frame.componentName, idx),
+        id: authoredCdId(node.openingElement) ?? computeId(frame.componentName, idx),
         componentName: frame.componentName,
         isFrameRoot: idx === 0,
         tag: tagOf(node),
@@ -1054,6 +1082,44 @@ function collectElementsFull(
   return out;
 }
 
+/**
+ * feature-4 T7a (layers purple instances, DDR-187 scope note) — the component
+ * map the shell's Layers panel renders instance rows from. For every element id
+ * whose ENCLOSING component is actually instantiated as a JSX element in this
+ * file (`<Card/>` — i.e. a reusable component, not the top-level canvas
+ * component, which is exported/mounted but never referenced as JSX here),
+ * report `{ component, root, usages }`. `root` marks the component's own frame
+ * root (the "instance" row in Figma terms — ◆-adjacent); inner members get the
+ * same purple treatment at lower prominence. Elements of never-instantiated
+ * components (the canvas root) are omitted — keeps the payload proportional to
+ * actual instances.
+ */
+export function componentMapForCanvas(
+  canvasAbsPath: string,
+  source: string
+): Record<string, { component: string; root: boolean; usages: number }> {
+  const parsed = parseSync(canvasAbsPath, source, { sourceType: 'module' });
+  if (parsed.errors && parsed.errors.length > 0) return {};
+  const all = collectElementsFull(parsed.program);
+  // Usage count per component name = JSX elements whose TAG is that name.
+  const usages = new Map<string, number>();
+  for (const e of all) {
+    if (e.tag && /^[A-Z]/.test(e.tag)) {
+      usages.set(e.tag, (usages.get(e.tag) ?? 0) + 1);
+    }
+  }
+  const out: Record<string, { component: string; root: boolean; usages: number }> = {};
+  for (const e of all) {
+    if (!e.componentName) continue;
+    const n = usages.get(e.componentName) ?? 0;
+    if (n < 1) continue; // top-level canvas component — not an instance
+    // First writer wins — repeated ids (a `.map`) share one source element; the
+    // map is keyed by source id, which is exactly what the Layers rows carry.
+    if (!out[e.id]) out[e.id] = { component: e.componentName, root: e.isFrameRoot, usages: n };
+  }
+  return out;
+}
+
 /**
  * Resolve a reused-component INSTANCE id to the parent's `<Component>` USAGE id.
  *
@@ -3598,12 +3664,16 @@ export async function setArtboardHug(
 }
 
 /** Patch shape for {@link applySetArtboardStyle} — `null` resets/removes that
- *  prop back to the engine default; `undefined`/absent leaves it untouched. */
+ *  prop back to the engine default; `undefined`/absent leaves it untouched.
+ *  padding/gap accept a `var(--token)` STRING alongside raw px numbers
+ *  (dogfood: the Inspector's artboard panel binds space tokens the same way
+ *  the CSS panel's ValueTokenField does) — validation of the string shape
+ *  lives at the api.ts layer, same split as every other artboard writer. */
 export interface ArtboardStylePatch {
   background?: string | null;
-  padding?: number | null;
+  padding?: number | string | null;
   layout?: string | null;
-  gap?: number | null;
+  gap?: number | string | null;
 }
 
 /**
@@ -3647,10 +3717,14 @@ export function applySetArtboardStyle(
   }
   if ('padding' in patch) {
     if (patch.padding == null) removeStringAttr(s, opening, 'padding', source);
+    else if (typeof patch.padding === 'string')
+      editStringAttr(s, opening, 'padding', patch.padding, canvasAbsPath, artboardId);
     else writeNumericAttr(s, opening, 'padding', patch.padding, 0);
   }
   if ('gap' in patch) {
     if (patch.gap == null) removeStringAttr(s, opening, 'gap', source);
+    else if (typeof patch.gap === 'string')
+      editStringAttr(s, opening, 'gap', patch.gap, canvasAbsPath, artboardId);
     else writeNumericAttr(s, opening, 'gap', patch.gap, 0);
   }
   const out = s.toString();
@@ -3689,6 +3763,308 @@ export async function setArtboardStyle(
   });
 }
 
+const ARTBOARD_KIND_VALUES = new Set(['digital', 'print', 'web', 'video']);
+
+/**
+ * Write/clear the DCArtboard `kind` prop (feature-1-artboard-kinds-foundation
+ * T5/T8) — kind-switch surfaces (context menu, Inspector) route here. Plain
+ * string prop, so this reuses the same `editStringAttr`/`removeStringAttr`
+ * toolkit + id-prop addressing as `applySetArtboardStyle`. `kind: null` clears
+ * back to the implicit default (`digital`, or the `subtreeHasVideoComp`
+ * fallback). Pure; reparse-gated.
+ */
+export function applySetArtboardKind(
+  canvasAbsPath: string,
+  source: string,
+  artboardId: string,
+  kind: string | null
+): { source: string } {
+  if (kind !== null && !ARTBOARD_KIND_VALUES.has(kind)) {
+    throw new CanvasEditError(`invalid artboard kind "${kind}"`, {
+      canvas: canvasAbsPath,
+      id: artboardId,
+    });
+  }
+  const parsed = parseSync(canvasAbsPath, source, { sourceType: 'module' });
+  if (parsed.errors && parsed.errors.length > 0) {
+    throw new CanvasEditError(
+      `oxc-parser failed on ${canvasAbsPath}: ${parsed.errors[0]?.message ?? 'unknown'}`,
+      { canvas: canvasAbsPath, id: artboardId }
+    );
+  }
+  const artboards = collectJsxByTag(parsed.program, 'DCArtboard');
+  const target = artboards.find((a) => getStringAttr(a.openingElement, 'id') === artboardId);
+  if (!target) {
+    throw new CanvasEditError(`<DCArtboard id="${artboardId}"> not found in ${canvasAbsPath}`, {
+      canvas: canvasAbsPath,
+      id: artboardId,
+    });
+  }
+  const s = new MagicString(source);
+  const opening = target.openingElement;
+  if (kind === null) removeStringAttr(s, opening, 'kind', source);
+  else editStringAttr(s, opening, 'kind', kind, canvasAbsPath, artboardId);
+  const out = s.toString();
+  const check = parseSync(canvasAbsPath, out, { sourceType: 'module' });
+  if (check.errors && check.errors.length > 0) {
+    throw new CanvasEditError(
+      `artboard kind edit produced invalid source (${check.errors[0]?.message ?? 'parse error'})`,
+      { canvas: canvasAbsPath, id: artboardId }
+    );
+  }
+  return { source: out };
+}
+
+/** Set an artboard's `kind` on disk (atomic write + cross-process lock). */
+export async function setArtboardKind(
+  canvasAbsPath: string,
+  artboardId: string,
+  kind: string | null
+): Promise<{ source: string }> {
+  return withLock(canvasAbsPath, async () => {
+    const file = Bun.file(canvasAbsPath);
+    if (!(await file.exists())) {
+      throw new CanvasEditError(`Canvas not found: ${canvasAbsPath}`, {
+        canvas: canvasAbsPath,
+        id: artboardId,
+      });
+    }
+    const source = await file.text();
+    const next = applySetArtboardKind(canvasAbsPath, source, artboardId, kind);
+    if (next.source === source) return next;
+    const tmp = `${canvasAbsPath}.tmp.${Math.random().toString(36).slice(2, 10)}`;
+    await Bun.write(tmp, next.source);
+    const { rename } = await import('node:fs/promises');
+    await rename(tmp, canvasAbsPath);
+    return next;
+  });
+}
+
+/**
+ * Write/clear an object-VALUED DCArtboard prop (`guides={{ columns: {...} }}`,
+ * `print={{ paper: 'a4' }}`), unlike every other artboard writer above.
+ * Per the plan's own gotcha, object-prop editing via AST is the hard part;
+ * this scopes to REPLACE-WHOLE-PROP (stringify the given object and overwrite
+ * the entire `{{...}}` span), not a deep merge — a caller that wants to keep
+ * one key while adding another must read the current value back (Inspector
+ * pre-fill reads `data-dc-*`-style attrs same as every other artboard knob)
+ * and send the full merged object. `value: null` removes the prop entirely.
+ * `JSON.stringify` output is valid as a JS object-literal expression (quoted
+ * keys are legal JS, not just JSON), so no separate JS-literal serializer is
+ * needed. Shape validation lives at the api.ts layer; this is pure AST
+ * surgery. Pure; reparse-gated. Shared by `applySetArtboardGuides` and
+ * `applySetArtboardPrint` (feature-2-print-artboards T2) below.
+ */
+function applySetArtboardObjectProp(
+  canvasAbsPath: string,
+  source: string,
+  artboardId: string,
+  propName: string,
+  value: Record<string, unknown> | null
+): { source: string } {
+  const parsed = parseSync(canvasAbsPath, source, { sourceType: 'module' });
+  if (parsed.errors && parsed.errors.length > 0) {
+    throw new CanvasEditError(
+      `oxc-parser failed on ${canvasAbsPath}: ${parsed.errors[0]?.message ?? 'unknown'}`,
+      { canvas: canvasAbsPath, id: artboardId }
+    );
+  }
+  const artboards = collectJsxByTag(parsed.program, 'DCArtboard');
+  const target = artboards.find((a) => getStringAttr(a.openingElement, 'id') === artboardId);
+  if (!target) {
+    throw new CanvasEditError(`<DCArtboard id="${artboardId}"> not found in ${canvasAbsPath}`, {
+      canvas: canvasAbsPath,
+      id: artboardId,
+    });
+  }
+  const s = new MagicString(source);
+  const opening = target.openingElement;
+  if (value === null) {
+    removeStringAttr(s, opening, propName, source);
+  } else {
+    const literal = JSON.stringify(value);
+    const attr = findAttribute(opening, propName);
+    if (!attr) {
+      const insertAt: number | undefined = opening?.name?.end;
+      if (typeof insertAt !== 'number') {
+        throw new Error('Opening element has no resolvable name range');
+      }
+      s.appendLeft(insertAt, ` ${propName}={${literal}}`);
+    } else if (attr.value?.type === 'JSXExpressionContainer') {
+      s.overwrite(attr.value.start, attr.value.end, `{${literal}}`);
+    } else {
+      throw new CanvasEditError(
+        `${propName} attribute is not a {{...}} expression — refusing to edit`,
+        {
+          canvas: canvasAbsPath,
+          id: artboardId,
+        }
+      );
+    }
+  }
+  const out = s.toString();
+  const check = parseSync(canvasAbsPath, out, { sourceType: 'module' });
+  if (check.errors && check.errors.length > 0) {
+    throw new CanvasEditError(
+      `artboard ${propName} edit produced invalid source (${check.errors[0]?.message ?? 'parse error'})`,
+      { canvas: canvasAbsPath, id: artboardId }
+    );
+  }
+  return { source: out };
+}
+
+/** Set an artboard's object-valued prop on disk (atomic write + cross-process lock). */
+async function setArtboardObjectProp(
+  canvasAbsPath: string,
+  artboardId: string,
+  propName: string,
+  value: Record<string, unknown> | null
+): Promise<{ source: string }> {
+  return withLock(canvasAbsPath, async () => {
+    const file = Bun.file(canvasAbsPath);
+    if (!(await file.exists())) {
+      throw new CanvasEditError(`Canvas not found: ${canvasAbsPath}`, {
+        canvas: canvasAbsPath,
+        id: artboardId,
+      });
+    }
+    const source = await file.text();
+    const next = applySetArtboardObjectProp(canvasAbsPath, source, artboardId, propName, value);
+    if (next.source === source) return next;
+    const tmp = `${canvasAbsPath}.tmp.${Math.random().toString(36).slice(2, 10)}`;
+    await Bun.write(tmp, next.source);
+    const { rename } = await import('node:fs/promises');
+    await rename(tmp, canvasAbsPath);
+    return next;
+  });
+}
+
+export function applySetArtboardGuides(
+  canvasAbsPath: string,
+  source: string,
+  artboardId: string,
+  guides: Record<string, unknown> | null
+): { source: string } {
+  return applySetArtboardObjectProp(canvasAbsPath, source, artboardId, 'guides', guides);
+}
+
+/** Set an artboard's `guides` on disk (atomic write + cross-process lock). */
+export function setArtboardGuides(
+  canvasAbsPath: string,
+  artboardId: string,
+  guides: Record<string, unknown> | null
+): Promise<{ source: string }> {
+  return setArtboardObjectProp(canvasAbsPath, artboardId, 'guides', guides);
+}
+
+/**
+ * Write/clear the DCArtboard `print` prop (feature-2-print-artboards T2) —
+ * see `applySetArtboardObjectProp`'s doc comment for the shared shape.
+ * `print: null` removes the prop entirely (e.g. reverting an artboard to a
+ * non-print kind).
+ */
+export function applySetArtboardPrint(
+  canvasAbsPath: string,
+  source: string,
+  artboardId: string,
+  print: Record<string, unknown> | null
+): { source: string } {
+  return applySetArtboardObjectProp(canvasAbsPath, source, artboardId, 'print', print);
+}
+
+/** Set an artboard's `print` on disk (atomic write + cross-process lock). */
+export function setArtboardPrint(
+  canvasAbsPath: string,
+  artboardId: string,
+  print: Record<string, unknown> | null
+): Promise<{ source: string }> {
+  return setArtboardObjectProp(canvasAbsPath, artboardId, 'print', print);
+}
+
+/**
+ * Read a JS object-literal AST node into a plain object WITHOUT eval —
+ * `print` (like every other canvas-authored JSX prop) is part of the
+ * DDR-054 untrusted-canvas surface, so evaluating its source text
+ * (`Function('return ' + src)()`) would be a code-injection hole. Handles
+ * string/numeric/boolean/null literals and nested object literals; any other
+ * value shape (identifiers, calls, template strings, arrays) is silently
+ * skipped — conservative by design, since a print-geometry reader should
+ * degrade to "field absent" rather than guess. Depth-capped defensively,
+ * though `print`'s own shape never nests past marginsMm (depth 2).
+ */
+function objectExpressionToPlain(node: AnyNode, depth = 0): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  if (depth > 6 || node?.type !== 'ObjectExpression') return out;
+  for (const p of node.properties ?? []) {
+    if ((p?.type !== 'Property' && p?.type !== 'ObjectProperty') || p.computed) continue;
+    const key =
+      p.key?.type === 'Identifier'
+        ? (p.key.name as string)
+        : isStringLit(p.key)
+          ? String(p.key.value)
+          : null;
+    if (key === null) continue;
+    const v = p.value;
+    if (!v) continue;
+    if (v.type === 'ObjectExpression') {
+      out[key] = objectExpressionToPlain(v, depth + 1);
+    } else if (
+      (v.type === 'Literal' ||
+        v.type === 'StringLiteral' ||
+        v.type === 'NumericLiteral' ||
+        v.type === 'BooleanLiteral') &&
+      (typeof v.value === 'string' ||
+        typeof v.value === 'number' ||
+        typeof v.value === 'boolean' ||
+        v.value === null)
+    ) {
+      out[key] = v.value;
+    }
+    // else: unsupported value shape — key silently omitted.
+  }
+  return out;
+}
+
+/**
+ * Read an artboard's `print` JSX prop as a plain object — used by the PDF
+ * exporter (T5) to resolve bleed/paper geometry for the artboard being
+ * exported. Read-only (no lock, no write). Returns null when the canvas/
+ * artboard/prop doesn't exist, `kind` isn't the literal string `"print"` — a
+ * `print` prop left over from a prior kind switch (or hand-authored on a
+ * non-print artboard) must NOT leak bleed/marks into an export; `kind="print"`
+ * is the sole gate (unlike `video`, print has no implicit structural-fallback
+ * resolution, so checking the explicit attr is sufficient — see
+ * DDR-181/canvas-lib.tsx) — or `print` doesn't resolve to a `{{...}}`
+ * object-expression.
+ *
+ * The prop is accepted either as an inline literal (`print={{ paper: 'a4' }}`)
+ * or as a reference to a top-level `const` sharing one spec across several
+ * artboards (`print={A1_PRINT}` / `print={A1_PRINT as any}`) — resolved via
+ * `resolveValueNode`'s same no-eval identifier lookup used elsewhere in this
+ * file. Anything else genuinely computed (an import, a function call, a
+ * spread) still returns null rather than guessing (RCA
+ * issue-pdf-print-export-marks-missing).
+ */
+export function readArtboardPrintProp(
+  canvasAbsPath: string,
+  source: string,
+  artboardId: string
+): Record<string, unknown> | null {
+  const parsed = parseSync(canvasAbsPath, source, { sourceType: 'module' });
+  if (parsed.errors && parsed.errors.length > 0) return null;
+  const artboards = collectJsxByTag(parsed.program, 'DCArtboard');
+  const target = artboards.find((a) => getStringAttr(a.openingElement, 'id') === artboardId);
+  if (!target) return null;
+  if (getStringAttr(target.openingElement, 'kind') !== 'print') return null;
+  const attr = findAttribute(target.openingElement, 'print');
+  if (attr?.value?.type !== 'JSXExpressionContainer') return null;
+  const expr = attr.value.expression as AnyNode | undefined;
+  if (!expr) return null;
+  const resolved = resolveValueNode(parsed.program, expr);
+  if (resolved?.type !== 'ObjectExpression') return null;
+  return objectExpressionToPlain(resolved);
+}
+
 /**
  * Delete the `<DCArtboard id="…">` whose `id` prop equals `artboardId` — the
  * artboard counterpart of applyDeleteElement (an artboard is addressed by its id
@@ -3849,6 +4225,148 @@ export async function insertArtboard(
   });
 }
 
+/**
+ * Duplicate the `<DCArtboard id="…">` whose `id` prop equals `artboardId` at
+ * a NEW width — feature-3-web-artboards T3 "Duplicate at width…". Clones the
+ * artboard's full source span (opening tag through children through closing
+ * tag) as the NEXT sibling in source order, then patches the clone's `id`
+ * (suffixed with the new width, de-duped against every existing artboard id),
+ * `label` (suffixed `" (WIDTHpx)"`), and `width` attributes. Every other prop
+ * (`kind`, `guides`, `print`, `background`, `layout`, `gap`, `fixed`, and the
+ * children themselves) carries over verbatim — this is a structural copy, not
+ * a linked variant (Design Decision 3): the agent or the clone's own
+ * `@container` rules adapt the content afterward.
+ *
+ * Unlike `applyDuplicateElement` (whose target has no explicit source `id` —
+ * data-cd-id is transpile-time positional, so a byte-verbatim clone never
+ * collides), an artboard's `id`/`label`/`width` ARE explicit JSX attributes
+ * that WOULD collide verbatim — they're rewritten in the clone text via a
+ * small isolated MagicString pass keyed off the original attribute nodes'
+ * offsets translated into clone-relative coordinates (offset - elStart),
+ * rather than re-parsing the extracted substring.
+ *
+ * Splicing the clone right after the SOURCE (not appended at the end of the
+ * file, unlike applyInsertArtboard) is what gives it a "beside the source"
+ * position for free: an artboard with no explicit `layout.artboards[]` entry
+ * places via the runtime's index-ordered default-grid (DDR-027,
+ * canvas-lib.tsx VP_GRID) — the very next index after the source is the next
+ * default-grid cell, so the clone lands beside the original with no extra
+ * position-writing plumbing. An artboard that DOES carry an explicit
+ * `layout.artboards[]` entry is unaffected by its index (position is keyed by
+ * id, not order).
+ *
+ * Reparse-gated. Whole-file-snapshot undo, like the other structural ops.
+ */
+export function applyDuplicateArtboard(
+  canvasAbsPath: string,
+  source: string,
+  artboardId: string,
+  newWidth: number
+): { source: string; artboardId: string } {
+  const parsed = parseSync(canvasAbsPath, source, { sourceType: 'module' });
+  if (parsed.errors && parsed.errors.length > 0) {
+    throw new CanvasEditError(
+      `oxc-parser failed on ${canvasAbsPath}: ${parsed.errors[0]?.message ?? 'unknown'}`,
+      { canvas: canvasAbsPath, id: artboardId }
+    );
+  }
+  const artboards = collectJsxByTag(parsed.program, 'DCArtboard');
+  const target = artboards.find((a) => getStringAttr(a.openingElement, 'id') === artboardId);
+  if (!target) {
+    throw new CanvasEditError(`<DCArtboard id="${artboardId}"> not found in ${canvasAbsPath}`, {
+      canvas: canvasAbsPath,
+      id: artboardId,
+    });
+  }
+  const width = Math.max(1, Math.round(newWidth));
+
+  const existingIds = new Set(
+    artboards
+      .map((a) => getStringAttr(a.openingElement, 'id'))
+      .filter((x): x is string => typeof x === 'string')
+  );
+  let newId = `${artboardId}-${width}`;
+  let suffix = 2;
+  while (existingIds.has(newId)) {
+    newId = `${artboardId}-${width}-${suffix}`;
+    suffix += 1;
+  }
+
+  const sourceLabel = getStringAttr(target.openingElement, 'label') ?? artboardId;
+  const newLabel = `${sourceLabel} (${width}px)`;
+
+  const elStart = target.start as number;
+  const elEnd = target.end as number;
+  const cloneText = source.slice(elStart, elEnd);
+
+  const idAttr = findAttribute(target.openingElement, 'id');
+  if (!idAttr || typeof idAttr.start !== 'number' || typeof idAttr.end !== 'number') {
+    throw new CanvasEditError(`<DCArtboard id="${artboardId}"> has no readable id attribute`, {
+      canvas: canvasAbsPath,
+      id: artboardId,
+    });
+  }
+  const labelAttr = findAttribute(target.openingElement, 'label');
+  const widthAttr = findAttribute(target.openingElement, 'width');
+
+  const cs = new MagicString(cloneText);
+  cs.overwrite(idAttr.start - elStart, idAttr.end - elStart, `id="${escapeAttr(newId)}"`);
+  if (labelAttr && typeof labelAttr.start === 'number' && typeof labelAttr.end === 'number') {
+    cs.overwrite(
+      labelAttr.start - elStart,
+      labelAttr.end - elStart,
+      `label="${escapeAttr(newLabel)}"`
+    );
+  } else {
+    cs.appendLeft(idAttr.end - elStart, ` label="${escapeAttr(newLabel)}"`);
+  }
+  if (widthAttr && typeof widthAttr.start === 'number' && typeof widthAttr.end === 'number') {
+    cs.overwrite(widthAttr.start - elStart, widthAttr.end - elStart, `width={${width}}`);
+  } else {
+    cs.appendLeft(idAttr.end - elStart, ` width={${width}}`);
+  }
+  const patchedClone = cs.toString();
+
+  const targetIndent = lineStartInfo(source, elStart).indent;
+  const insertText = `\n${targetIndent}${patchedClone}`;
+  const s = new MagicString(source);
+  s.appendLeft(elEnd, insertText);
+  const out = s.toString();
+  const check = parseSync(canvasAbsPath, out, { sourceType: 'module' });
+  if (check.errors && check.errors.length > 0) {
+    throw new CanvasEditError(
+      `duplicate-artboard produced invalid source (${check.errors[0]?.message ?? 'parse error'})`,
+      { canvas: canvasAbsPath, id: artboardId }
+    );
+  }
+  return { source: out, artboardId: newId };
+}
+
+/** Duplicate an artboard on disk (atomic write + cross-process lock). */
+export async function duplicateArtboard(
+  canvasAbsPath: string,
+  artboardId: string,
+  newWidth: number
+): Promise<{ source: string; artboardId: string }> {
+  return withLock(canvasAbsPath, async () => {
+    const file = Bun.file(canvasAbsPath);
+    if (!(await file.exists())) {
+      throw new CanvasEditError(`Canvas not found: ${canvasAbsPath}`, {
+        canvas: canvasAbsPath,
+        id: artboardId,
+      });
+    }
+    const source = await file.text();
+    const next = applyDuplicateArtboard(canvasAbsPath, source, artboardId, newWidth);
+    if (next.source === source) return next;
+    const tmp = `${canvasAbsPath}.tmp.${Math.random().toString(36).slice(2, 10)}`;
+    await Bun.write(tmp, next.source);
+    const { rename } = await import('node:fs/promises');
+    await rename(tmp, canvasAbsPath);
+    return next;
+  });
+}
+
 /** A clip in an assemble request — a dropped reference chip's src + kind. */
 export interface AssembleClip {
   src: string;
@@ -4116,6 +4634,454 @@ function editStyleProp(
   s.appendLeft((obj.end as number) - 1, `${sep}${jsKey(prop)}: ${value} `);
 }
 
+/**
+ * feature-4 T8 (convert-to-absolute, DDR-188) — set SEVERAL inline-style props on
+ * ONE opening element in ONE MagicString pass. `editStyleProp` can't be called
+ * N× per element on a fresh (style-less) element: it re-reads the ORIGINAL AST
+ * each call (which still shows no `style` attr) and would emit N duplicate
+ * `style={{…}}` attributes. So the no-style case is handled here with a single
+ * combined insert; the existing-style case safely delegates per-prop to
+ * `editStyleProp` (distinct keys → non-overlapping overwrites; new-key appends
+ * stack correctly before the closing brace). `entries` values are ALREADY
+ * source-ready (e.g. `'"absolute"'`, `JSON.stringify("12px")`).
+ */
+function setMultipleStyleProps(
+  s: MagicString,
+  opening: AnyNode,
+  entries: Array<[string, string]>,
+  canvasAbsPath: string,
+  id: string
+): void {
+  if (entries.length === 0) return;
+  const attr = findAttribute(opening, 'style');
+  if (!attr) {
+    const insertAt: number | undefined = opening?.name?.end;
+    if (typeof insertAt !== 'number') {
+      throw new Error('Opening element has no resolvable name range');
+    }
+    const body = entries.map(([k, v]) => `${jsKey(k)}: ${v}`).join(', ');
+    s.appendLeft(insertAt, ` style={{ ${body} }}`);
+    return;
+  }
+  for (const [k, v] of entries) {
+    editStyleProp(s, opening, k, v, canvasAbsPath, id);
+  }
+}
+
+/**
+ * feature-4 T8 (convert-to-absolute, DDR-188) — the "Remove auto layout" analogue.
+ * Pure AST batch write: rewrite each stamped CHILD to `position:absolute` with the
+ * frozen `left/top/width/height` the client measured (border-box, world units),
+ * and set the CONTAINER to `position:relative` when it's currently static — all in
+ * ONE MagicString pass so a single whole-file snapshot reverts the whole operation.
+ *
+ * Guards (all-or-nothing, throws `CanvasEditError` — the shell surfaces the reason
+ * and writes nothing):
+ *   - Every child id must be a plain, UNIQUE, in-source element. If any child's
+ *     `idIndex` resolves to a different `<Component/>` usage (a shared instance),
+ *     we refuse — converting one usage's props doesn't generalize, and doing it
+ *     silently would move every instance (the DDR-188 shared-instance abort; the
+ *     "affects N instances" confirm path is a deferred follow-up).
+ *   - The caller (canvas iframe) already refuses unstamped or duplicate-cd-id
+ *     (`.map`ed) direct children before it ever posts — this is the server-side
+ *     backstop for the component-usage case it can't see.
+ */
+export interface ConvertChildBox {
+  id: string;
+  idIndex?: number;
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+
+export interface ConvertContainerSpec {
+  /** Absent for the artboard-body ROOT level — `.dc-artboard-body` is already
+   *  `position:relative` engine chrome with no `data-cd-id`, so its children
+   *  get absolute boxes with no container write. */
+  containerId?: string;
+  containerIdIndex?: number;
+  containerSetRelative: boolean;
+  /** feature-4 (dogfood round 4) — freeze the container's OWN border-box size.
+   *  Needed for the element-level subtree ROOT: it keeps its flow position but
+   *  its auto height would collapse once every child goes absolute. */
+  freezeSize?: { width: number; height: number };
+  children: ConvertChildBox[];
+}
+
+export function applyConvertToAbsolute(
+  canvasAbsPath: string,
+  source: string,
+  spec: {
+    containerId?: string;
+    containerIdIndex?: number;
+    containerSetRelative?: boolean;
+    /** feature-4 T8b — user CONFIRMED converting component-instance children:
+     *  each child's `idIndex` routes the write to that occurrence's own
+     *  `<Component/>` USAGE (the Stage-H3 local-instance model — the usage
+     *  element carries the frozen box; the component must forward `style` for
+     *  it to paint, same assumption as instance drag-reposition). Without the
+     *  flag a shared child still throws (the pre-confirm abort). */
+    allowShared?: boolean;
+    children?: ConvertChildBox[];
+    /** feature-4 artboard-level convert (2026-07-19) — MULTI-container batch:
+     *  the whole artboard's layout flattened to absolute in ONE pass / ONE
+     *  undo seq. When present, the legacy single-container fields above are
+     *  ignored. */
+    containers?: ConvertContainerSpec[];
+    /** feature-4 TRUE FLATTEN (user steer 2026-07-20) — ids of UNSTYLED layout
+     *  wrappers to DISSOLVE: their opening+closing tags are removed from the
+     *  JSX (children hoist textually into the parent), so the tree genuinely
+     *  flattens. The client only nominates visually-inert wrappers (no
+     *  background/border/shadow/radius/clip) whose id is unique in the
+     *  artboard; their children's boxes are measured against the nearest
+     *  SURVIVING ancestor. */
+    dissolve?: string[];
+  }
+): EditResult {
+  const parsed = parseSync(canvasAbsPath, source, { sourceType: 'module' });
+  if (parsed.errors && parsed.errors.length > 0) {
+    const first = parsed.errors[0];
+    throw new CanvasEditError(
+      `oxc-parser failed on ${canvasAbsPath}: ${first?.message ?? 'unknown'}`,
+      {
+        canvas: canvasAbsPath,
+        id: spec.containerId ?? 'artboard',
+      }
+    );
+  }
+  const containers: ConvertContainerSpec[] = Array.isArray(spec.containers)
+    ? spec.containers
+    : [
+        {
+          containerId: spec.containerId,
+          containerIdIndex: spec.containerIdIndex,
+          containerSetRelative: spec.containerSetRelative === true,
+          children: spec.children ?? [],
+        },
+      ];
+  const totalChildren = containers.reduce((n, c) => n + c.children.length, 0);
+  if (totalChildren === 0) {
+    throw new CanvasEditError('convert-to-absolute: no children to convert', {
+      canvas: canvasAbsPath,
+      id: spec.containerId ?? 'artboard',
+    });
+  }
+  const s = new MagicString(source);
+  // Shared across ALL containers — a `.map()`ed child (two DOM children
+  // resolving to the SAME source element) can never convert: N rendered copies
+  // of ONE source element can't hold N absolute positions.
+  const writtenTargets = new Set<string>();
+  // A container may legitimately receive BOTH a `position:relative` write and
+  // (as a child of ITS parent container) an absolute box — track containers we
+  // already touched so the batch never double-writes `position` on one element.
+  const relativeWritten = new Set<string>();
+
+  for (const c of containers) {
+    // Container → position:relative (only when the client says it's currently
+    // static; already-positioned containers are left as-is; the artboard-body
+    // root level has no container to write).
+    if (c.containerId && (c.containerSetRelative || c.freezeSize)) {
+      const cid =
+        typeof c.containerIdIndex === 'number' && Number.isFinite(c.containerIdIndex)
+          ? resolveUsageId(parsed.program, c.containerId, c.containerIdIndex)
+          : c.containerId;
+      if (!relativeWritten.has(cid) && !writtenTargets.has(cid)) {
+        relativeWritten.add(cid);
+        const chit = findOpening(parsed.program, cid);
+        if (!chit) {
+          throw new CanvasEditError(`container "${c.containerId}" not found in ${canvasAbsPath}`, {
+            canvas: canvasAbsPath,
+            id: c.containerId,
+          });
+        }
+        const entries: Array<[string, string]> = [];
+        if (c.containerSetRelative) entries.push(['position', '"relative"']);
+        if (c.freezeSize) {
+          entries.push(
+            ['width', JSON.stringify(`${c.freezeSize.width}px`)],
+            ['height', JSON.stringify(`${c.freezeSize.height}px`)],
+            ['box-sizing', '"border-box"']
+          );
+        }
+        setMultipleStyleProps(s, chit.opening, entries, canvasAbsPath, cid);
+      }
+    }
+
+    // Each child → absolute + frozen box. A shared-component usage either
+    // routes to its own `<Component/>` usage (allowShared — the user
+    // confirmed) or throws (the pre-confirm abort).
+    for (const child of c.children) {
+      let cid = child.id;
+      if (typeof child.idIndex === 'number' && Number.isFinite(child.idIndex)) {
+        cid = resolveUsageId(parsed.program, child.id, child.idIndex);
+        if (cid !== child.id && !spec.allowShared) {
+          throw new CanvasEditError(
+            `convert-to-absolute: "${child.id}" is a shared component instance — confirm required`,
+            { canvas: canvasAbsPath, id: child.id }
+          );
+        }
+      }
+      if (writtenTargets.has(cid)) {
+        throw new CanvasEditError(
+          `convert-to-absolute: "${child.id}" renders from a repeated (.map) source element — cannot convert`,
+          { canvas: canvasAbsPath, id: child.id }
+        );
+      }
+      writtenTargets.add(cid);
+      const hit = findOpening(parsed.program, cid);
+      if (!hit) {
+        throw new CanvasEditError(`child "${child.id}" not found in ${canvasAbsPath}`, {
+          canvas: canvasAbsPath,
+          id: child.id,
+        });
+      }
+      // A COMPONENT-INSTANCE child (cid routed to a `<Component/>` usage):
+      // writing `style` on the usage tag only works when the component
+      // forwards it — most don't (live-dogfood 2026-07-20: the frozen Cards
+      // piled at the artboard's top-left). WRAP the usage in a positioned div
+      // instead — correct for ANY component, no forwarding assumption. The
+      // wrapper gets its own data-cd-id on the next transpile.
+      if (cid !== child.id) {
+        const elStart = hit.element?.start as number;
+        const elEnd = hit.element?.end as number;
+        // appendRight for the OPEN + appendLeft for the CLOSE: at a shared
+        // boundary between two ADJACENT usages (`<Card /><Card />`), MagicString
+        // renders the appendLeft bucket before the appendRight bucket, so the
+        // previous usage's close always lands before the next usage's open.
+        s.appendRight(
+          elStart,
+          `<div style={{ position: "absolute", left: ${JSON.stringify(`${child.left}px`)}, top: ${JSON.stringify(`${child.top}px`)}, width: ${JSON.stringify(`${child.width}px`)}, height: ${JSON.stringify(`${child.height}px`)} }}>`
+        );
+        s.appendLeft(elEnd, '</div>');
+        continue;
+      }
+      const entries: Array<[string, string]> = [
+        ['position', '"absolute"'],
+        ['left', JSON.stringify(`${child.left}px`)],
+        ['top', JSON.stringify(`${child.top}px`)],
+        ['width', JSON.stringify(`${child.width}px`)],
+        ['height', JSON.stringify(`${child.height}px`)],
+        ['box-sizing', '"border-box"'],
+      ];
+      // If this element was already made `relative` as a container in this
+      // batch, drop the child-role `position:absolute` write for it — one
+      // element gets ONE position key. (Deeper-level nesting keeps the
+      // relative context; children of an absolute element also resolve fine —
+      // absolute IS a positioning context — but never write both.)
+      if (relativeWritten.has(cid)) entries.shift();
+      setMultipleStyleProps(s, hit.opening, entries, canvasAbsPath, cid);
+    }
+  }
+
+  // feature-4 TRUE FLATTEN — dissolve nominated layout wrappers: strip the
+  // opening + closing tags, leaving the children's JSX in place (they hoist
+  // into the wrapper's parent). Style writes above never target a dissolved
+  // id (the client keeps the sets disjoint; enforced here as a hard error so
+  // a drifted client can't half-write a removed element).
+  if (Array.isArray(spec.dissolve) && spec.dissolve.length > 0) {
+    for (const did of spec.dissolve) {
+      if (writtenTargets.has(did) || relativeWritten.has(did)) {
+        throw new CanvasEditError(
+          `convert-to-absolute: "${did}" is both a style target and a dissolve target`,
+          { canvas: canvasAbsPath, id: did }
+        );
+      }
+      const hit = findOpening(parsed.program, did);
+      if (!hit) {
+        throw new CanvasEditError(`dissolve target "${did}" not found in ${canvasAbsPath}`, {
+          canvas: canvasAbsPath,
+          id: did,
+        });
+      }
+      const opening = hit.opening;
+      const closing = hit.element?.closingElement;
+      if (!closing || typeof closing.start !== 'number' || typeof closing.end !== 'number') {
+        throw new CanvasEditError(`dissolve target "${did}" is self-closing — nothing to hoist`, {
+          canvas: canvasAbsPath,
+          id: did,
+        });
+      }
+      s.remove(opening.start as number, opening.end as number);
+      s.remove(closing.start as number, closing.end as number);
+    }
+  }
+
+  const out = s.toString();
+  return { source: out, delta: out.length - source.length };
+}
+
+/**
+ * Async wrapper for {@link applyConvertToAbsolute} — read, apply, atomic write,
+ * per-file lock (same shape as `editAttribute`). Returns the changed source.
+ */
+export async function convertToAbsolute(
+  canvasAbsPath: string,
+  spec: Parameters<typeof applyConvertToAbsolute>[2]
+): Promise<EditResult> {
+  return withLock(canvasAbsPath, async () => {
+    const file = Bun.file(canvasAbsPath);
+    if (!(await file.exists())) {
+      throw new CanvasEditError(`Canvas not found: ${canvasAbsPath}`, {
+        canvas: canvasAbsPath,
+        id: spec.containerId ?? 'artboard',
+      });
+    }
+    const source = await file.text();
+    const next = applyConvertToAbsolute(canvasAbsPath, source, spec);
+    if (next.source === source) return { source, delta: 0, changed: false };
+    const tmp = `${canvasAbsPath}.tmp.${Math.random().toString(36).slice(2, 10)}`;
+    await Bun.write(tmp, next.source);
+    const { rename } = await import('node:fs/promises');
+    await rename(tmp, canvasAbsPath);
+    return { ...next, changed: true };
+  });
+}
+
+/**
+ * feature-4 detach-component (user steer 2026-07-19) — make ONE component
+ * instance independently editable without inlining its JSX. Strategy: CLONE the
+ * component's definition under a fresh name (`<C>Detached`, `<C>Detached2`, …)
+ * and repoint THIS usage's tags at the clone. 100% behavior-preserving for ANY
+ * component (props/children/expressions flow unchanged — no substitution
+ * heuristics), and every subsequent edit lands on the clone's single-usage
+ * definition, so `resolveEditScope` reports it LOCAL. This is the answer to
+ * "moving an absolute child inside a shared component moved it in every
+ * artboard" — detach first, then edit freely.
+ */
+export function applyDetachComponent(
+  canvasAbsPath: string,
+  source: string,
+  id: string,
+  occurrence?: number
+): { source: string; delta: number; detachedName: string } {
+  const parsed = parseSync(canvasAbsPath, source, { sourceType: 'module' });
+  if (parsed.errors && parsed.errors.length > 0) {
+    const first = parsed.errors[0];
+    throw new CanvasEditError(
+      `oxc-parser failed on ${canvasAbsPath}: ${first?.message ?? 'unknown'}`,
+      { canvas: canvasAbsPath, id }
+    );
+  }
+  const usageId = resolveUsageId(parsed.program, id, occurrence ?? 0);
+  if (usageId === id) {
+    throw new CanvasEditError('detach: this element is not part of a reused component instance', {
+      canvas: canvasAbsPath,
+      id,
+    });
+  }
+  const hit = findOpening(parsed.program, usageId);
+  if (!hit) {
+    throw new CanvasEditError(`detach: usage "${usageId}" not found`, {
+      canvas: canvasAbsPath,
+      id,
+    });
+  }
+  const nameNode = hit.opening?.name;
+  if (nameNode?.type !== 'JSXIdentifier' || typeof nameNode.name !== 'string') {
+    throw new CanvasEditError('detach: usage tag is not a plain component identifier', {
+      canvas: canvasAbsPath,
+      id,
+    });
+  }
+  const componentName: string = nameNode.name;
+
+  // Locate the component's top-level definition (function declaration or a
+  // const initialized with a function/arrow), unwrapping an export wrapper.
+  let defStart: number | null = null;
+  let defEnd: number | null = null;
+  let nameStart: number | null = null;
+  let nameEnd: number | null = null;
+  const body: AnyNode[] = Array.isArray(parsed.program?.body) ? parsed.program.body : [];
+  for (const stmtRaw of body) {
+    const stmt =
+      stmtRaw?.type === 'ExportNamedDeclaration' || stmtRaw?.type === 'ExportDefaultDeclaration'
+        ? (stmtRaw.declaration ?? stmtRaw)
+        : stmtRaw;
+    if (!stmt || typeof stmt !== 'object') continue;
+    if (stmt.type === 'FunctionDeclaration' && stmt.id?.name === componentName) {
+      defStart = stmt.start as number;
+      defEnd = stmt.end as number;
+      nameStart = stmt.id.start as number;
+      nameEnd = stmt.id.end as number;
+      break;
+    }
+    if (stmt.type === 'VariableDeclaration' && Array.isArray(stmt.declarations)) {
+      const d = stmt.declarations.find(
+        (dd: AnyNode) => dd?.id?.type === 'Identifier' && dd.id.name === componentName
+      );
+      if (
+        d &&
+        (d.init?.type === 'ArrowFunctionExpression' || d.init?.type === 'FunctionExpression')
+      ) {
+        defStart = stmt.start as number;
+        defEnd = stmt.end as number;
+        nameStart = d.id.start as number;
+        nameEnd = d.id.end as number;
+        break;
+      }
+    }
+  }
+  if (defStart === null || defEnd === null || nameStart === null || nameEnd === null) {
+    throw new CanvasEditError(
+      `detach: definition of <${componentName}> not found in this canvas (imported components can't be detached here)`,
+      { canvas: canvasAbsPath, id }
+    );
+  }
+
+  // Fresh, collision-free clone name. A plain substring check is sufficient —
+  // false positives only bump the counter.
+  let detachedName = `${componentName}Detached`;
+  let n = 2;
+  while (source.includes(detachedName)) {
+    detachedName = `${componentName}Detached${n}`;
+    n += 1;
+  }
+
+  const defText = source.slice(defStart, defEnd);
+  const cloned =
+    defText.slice(0, nameStart - defStart) + detachedName + defText.slice(nameEnd - defStart);
+
+  const s = new MagicString(source);
+  s.appendRight(defEnd, `\n\n${cloned}`);
+  // Repoint the usage's opening (and closing, when present) tag name.
+  s.overwrite(nameNode.start as number, nameNode.end as number, detachedName);
+  const closingName = hit.element?.closingElement?.name;
+  if (closingName?.type === 'JSXIdentifier') {
+    s.overwrite(closingName.start as number, closingName.end as number, detachedName);
+  }
+  const out = s.toString();
+  return { source: out, delta: out.length - source.length, detachedName };
+}
+
+/** Async wrapper for {@link applyDetachComponent} — read, apply, atomic write,
+ *  per-file lock (same shape as `editAttribute`). */
+export async function detachComponent(
+  canvasAbsPath: string,
+  id: string,
+  occurrence?: number
+): Promise<{ source: string; delta: number; changed: boolean; detachedName: string }> {
+  return withLock(canvasAbsPath, async () => {
+    const file = Bun.file(canvasAbsPath);
+    if (!(await file.exists())) {
+      throw new CanvasEditError(`Canvas not found: ${canvasAbsPath}`, {
+        canvas: canvasAbsPath,
+        id,
+      });
+    }
+    const source = await file.text();
+    const next = applyDetachComponent(canvasAbsPath, source, id, occurrence);
+    if (next.source === source) {
+      return { source, delta: 0, changed: false, detachedName: next.detachedName };
+    }
+    const tmp = `${canvasAbsPath}.tmp.${Math.random().toString(36).slice(2, 10)}`;
+    await Bun.write(tmp, next.source);
+    const { rename } = await import('node:fs/promises');
+    await rename(tmp, canvasAbsPath);
+    return { ...next, changed: true };
+  });
+}
+
 /**
  * Remove a single inline-style property (the "reset to original" path — DDR-104
  * Phase 12.3). No-op when the style attribute or the key is absent. When the key