@1agh/maude 0.46.0 → 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.
  *
@@ -3963,12 +4029,21 @@ function objectExpressionToPlain(node: AnyNode, depth = 0): Record<string, unkno
  * 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, `print` isn't a `{{...}}` object-expression,
- * or `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).
+ * 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,
@@ -3984,8 +4059,10 @@ export function readArtboardPrintProp(
   const attr = findAttribute(target.openingElement, 'print');
   if (attr?.value?.type !== 'JSXExpressionContainer') return null;
   const expr = attr.value.expression as AnyNode | undefined;
-  if (expr?.type !== 'ObjectExpression') return null;
-  return objectExpressionToPlain(expr);
+  if (!expr) return null;
+  const resolved = resolveValueNode(parsed.program, expr);
+  if (resolved?.type !== 'ObjectExpression') return null;
+  return objectExpressionToPlain(resolved);
 }
 
 /**
@@ -4148,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;
@@ -4415,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