@1agh/maude 0.42.0 → 0.44.0

package/apps/studio/canvas-edit.ts

@@ -375,7 +375,8 @@ export function applyRemove(
 export async function editText(
   canvasAbsPath: string,
   id: string,
-  text: string
+  text: string,
+  opts?: DynamicTextOpts
 ): Promise<EditResult> {
   return withLock(canvasAbsPath, async () => {
     const file = Bun.file(canvasAbsPath);
@@ -386,7 +387,16 @@ export async function editText(
       });
     }
     const source = await file.text();
-    const next = applyTextEdit(canvasAbsPath, source, id, text);
+    // Byte cap before the AST walk (ethical-hacker F-C) — a real canvas is well
+    // under this; a pathologically large attacker-authored file that would make
+    // the resolver's per-candidate walk expensive is refused up front.
+    if (source.length > 4_000_000) {
+      throw new CanvasEditError(`canvas too large to edit inline (${source.length} bytes)`, {
+        canvas: canvasAbsPath,
+        id,
+      });
+    }
+    const next = applyTextEdit(canvasAbsPath, source, id, text, opts);
     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);
@@ -455,17 +465,35 @@ export function applyEdit(
   return { source: out, delta: out.length - source.length };
 }
 
+/**
+ * Extra context for editing text that comes from a `{variable}` rather than a
+ * literal (unified-text-editing follow-up). `occurrence` = which rendered
+ * instance the user edited (index among DOM nodes carrying this same cd-id — a
+ * `.map()` renders one source element N×); `before` = the pre-edit rendered
+ * text, used both to pick the right `.map()` item when the index drifts (a
+ * `.filter().map()` etc.) and to refuse a rewrite we can't confidently target.
+ */
+export interface DynamicTextOpts {
+  occurrence?: number;
+  before?: string;
+}
+
 /**
  * Pure variant of `editText` — parse, locate the JSXText child, overwrite its
  * source span (preserving the original leading/trailing whitespace so JSX
- * indentation survives), escaping the new text. Throws `CanvasEditError` for a
- * missing id, no text content, or mixed/expression children.
+ * indentation survives), escaping the new text. A single `{'literal'}` child is
+ * rewritten in place (DDR-150 P1). A single `{variable}` / `{item.prop}` child
+ * is resolved back to its source string (a local `const` or a `.map()`ed array
+ * element) when `opts` carries enough to target it unambiguously — otherwise it
+ * throws `CanvasEditError` (genuinely dynamic → route to /design:edit), same as
+ * mixed content.
  */
 export function applyTextEdit(
   canvasAbsPath: string,
   source: string,
   id: string,
-  text: string
+  text: string,
+  opts?: DynamicTextOpts
 ): EditResult {
   const parsed = parseSync(canvasAbsPath, source, { sourceType: 'module' });
   if (parsed.errors && parsed.errors.length > 0) {
@@ -507,16 +535,24 @@ export function applyTextEdit(
   // dynamic: refuse and route to /design:edit rather than delete the binding.
   if (meaningful.length === 1 && only?.type === 'JSXExpressionContainer') {
     const expr = (only as AnyNode).expression;
-    if (
-      expr &&
-      (expr.type === 'Literal' || expr.type === 'StringLiteral') &&
-      typeof expr.value === 'string'
-    ) {
+    // A single `{'string literal'}` — rewrite the literal in place (DDR-150 P1).
+    if (isStringLit(expr)) {
       const s = new MagicString(source);
       s.overwrite(expr.start as number, expr.end as number, JSON.stringify(text));
       const out = s.toString();
       return { source: out, delta: out.length - source.length };
     }
+    // A single `{variable}` / `{item.prop}` — trace it back to its source string
+    // (a local const, or a `.map()`ed array element) and rewrite THERE. The
+    // literal that comes back is a JS string, so it round-trips through
+    // JSON.stringify like the `{'literal'}` case above (no JSX-entity surface).
+    const span = resolveDynamicTextSpan(parsed.program, hit.element, expr, id, opts);
+    if (span) {
+      const s = new MagicString(source);
+      s.overwrite(span.start as number, span.end as number, JSON.stringify(text));
+      const out = s.toString();
+      return { source: out, delta: out.length - source.length };
+    }
     throw new CanvasEditError(`element "${id}" has dynamic content — edit it via /design:edit`, {
       canvas: canvasAbsPath,
       id,
@@ -541,6 +577,287 @@ export function applyTextEdit(
   return { source: out, delta: out.length - source.length };
 }
 
+// ---------------------------------------------------------------------------
+// Dynamic-text resolution (unified-text-editing follow-up). A `{variable}` /
+// `{item.prop}` text child has no literal to rewrite at the element — the
+// string lives in a `const` or a `.map()`ed data array. These helpers trace it
+// back to that source StringLiteral so inline editing works there too, WITHOUT
+// ever risking the wrong rewrite: the occurrence index picks the `.map()` item,
+// and the pre-edit text (`before`) both verifies that pick and rescues it when
+// the index drifts (`.filter().map()`, reorders). Anything we can't target
+// unambiguously returns null → the caller throws → routes to /design:edit.
+
+function isStringLit(n: AnyNode): boolean {
+  return !!(
+    n &&
+    (n.type === 'Literal' || n.type === 'StringLiteral') &&
+    typeof n.value === 'string'
+  );
+}
+
+/** Depth-first visit every AST node (skips location metadata keys). */
+function walkAst(root: AnyNode, fn: (node: AnyNode) => void): void {
+  function visit(node: AnyNode): void {
+    if (!node || typeof node !== 'object') return;
+    if (Array.isArray(node)) {
+      for (const c of node) visit(c);
+      return;
+    }
+    if (typeof node.type !== 'string') return;
+    fn(node);
+    for (const k of Object.keys(node)) {
+      if (k === 'loc' || k === 'range' || k === 'start' || k === 'end' || k === 'type') continue;
+      visit(node[k]);
+    }
+  }
+  visit(root);
+}
+
+/** The innermost `xs.map((param) => …)` whose callback param is `paramName`
+ *  and whose body byte-range encloses `element`. Returns the mapped array
+ *  expression (an Identifier or an inline ArrayExpression), or null. */
+function findEnclosingMapArray(
+  program: AnyNode,
+  element: AnyNode,
+  paramName: string
+): AnyNode | null {
+  const es = element.start as number;
+  const ee = element.end as number;
+  let best: AnyNode | null = null;
+  let bestSize = Number.POSITIVE_INFINITY;
+  walkAst(program, (node) => {
+    if (node.type !== 'CallExpression') return;
+    const callee = node.callee;
+    if (callee?.type !== 'MemberExpression' || callee.computed) return;
+    if (callee.property?.name !== 'map') return;
+    const cb = node.arguments?.[0];
+    if (cb?.type !== 'ArrowFunctionExpression' && cb?.type !== 'FunctionExpression') return;
+    const p0 = cb.params?.[0];
+    if (p0?.type !== 'Identifier' || p0.name !== paramName) return;
+    const body = cb.body;
+    if (typeof body?.start !== 'number' || typeof body?.end !== 'number') return;
+    if (!(body.start <= es && ee <= body.end)) return;
+    const size = (body.end as number) - (body.start as number);
+    if (size < bestSize) {
+      bestSize = size;
+      best = callee.object;
+    }
+  });
+  return best;
+}
+
+/** Resolve an array expression (an inline `[…]` or an Identifier bound to a
+ *  `const xs = […]`) to its ArrayExpression node. */
+function resolveArrayExpr(program: AnyNode, arrayExpr: AnyNode): AnyNode | null {
+  if (arrayExpr?.type === 'ArrayExpression') return arrayExpr;
+  if (arrayExpr?.type === 'Identifier') {
+    let found: AnyNode | null = null;
+    walkAst(program, (node) => {
+      if (
+        node.type === 'VariableDeclarator' &&
+        node.id?.type === 'Identifier' &&
+        node.id.name === arrayExpr.name &&
+        node.init?.type === 'ArrayExpression'
+      ) {
+        found = node.init;
+      }
+    });
+    return found;
+  }
+  return null;
+}
+
+/** The value node of property `propName` on an ObjectExpression, or null. */
+function objPropValue(objExpr: AnyNode, propName: string): AnyNode | null {
+  if (objExpr?.type !== 'ObjectExpression') return null;
+  for (const p of objExpr.properties ?? []) {
+    if (p?.type !== 'Property' || p.computed) continue;
+    const keyOk =
+      (p.key?.type === 'Identifier' && p.key.name === propName) ||
+      (isStringLit(p.key) && p.key.value === propName);
+    if (keyOk) return p.value ?? null;
+  }
+  return null;
+}
+
+/**
+ * Bounded expression evaluator — resolve `expr` to a concrete value node
+ * (a StringLiteral, ObjectExpression, or ArrayExpression) by following const
+ * bindings, numeric array indices (`XS[0]`), and object-field access
+ * (`obj.field`). Returns null for anything genuinely computed (calls, template
+ * strings, arithmetic). Depth-capped so a cyclic const can't loop.
+ */
+function resolveValueNode(program: AnyNode, expr: AnyNode, depth = 0): AnyNode | null {
+  if (!expr || depth > 8) return null;
+  if (isStringLit(expr)) return expr;
+  if (expr.type === 'ObjectExpression' || expr.type === 'ArrayExpression') return expr;
+  if (expr.type === 'Identifier') {
+    let init: AnyNode | null = null;
+    walkAst(program, (n) => {
+      if (
+        n.type === 'VariableDeclarator' &&
+        n.id?.type === 'Identifier' &&
+        n.id.name === expr.name &&
+        n.init
+      ) {
+        init = n.init;
+      }
+    });
+    return init ? resolveValueNode(program, init, depth + 1) : null;
+  }
+  if (expr.type === 'MemberExpression') {
+    const obj = resolveValueNode(program, expr.object, depth + 1);
+    if (!obj) return null;
+    if (expr.computed) {
+      const idx = expr.property;
+      if (
+        (idx?.type === 'Literal' || idx?.type === 'NumericLiteral') &&
+        typeof idx.value === 'number' &&
+        obj.type === 'ArrayExpression'
+      ) {
+        return resolveValueNode(program, obj.elements?.[idx.value], depth + 1);
+      }
+      return null;
+    }
+    if (expr.property?.type === 'Identifier') {
+      return resolveValueNode(program, objPropValue(obj, expr.property.name), depth + 1);
+    }
+    return null;
+  }
+  return null;
+}
+
+/** Ordered value-expressions of a `<CompName propName={…}>` usage, one per
+ *  usage in source order (aligns with the DOM occurrence of the element the
+ *  prop feeds). null slot = a usage that omits the prop. */
+function componentUsageValues(
+  program: AnyNode,
+  componentName: string,
+  propName: string
+): Array<AnyNode | null> | null {
+  if (!componentName) return null;
+  const out: Array<AnyNode | null> = [];
+  walkAst(program, (node) => {
+    if (node.type !== 'JSXElement') return;
+    const name = node.openingElement?.name;
+    if (name?.type !== 'JSXIdentifier' || name.name !== componentName) return;
+    let val: AnyNode | null = null;
+    for (const a of node.openingElement?.attributes ?? []) {
+      if (
+        a?.type === 'JSXAttribute' &&
+        a.name?.type === 'JSXIdentifier' &&
+        a.name.name === propName
+      ) {
+        val =
+          a.value?.type === 'JSXExpressionContainer'
+            ? a.value.expression
+            : isStringLit(a.value)
+              ? a.value
+              : null;
+        break;
+      }
+    }
+    out.push(val);
+  });
+  return out.length ? out : null;
+}
+
+/**
+ * Trace a single `{base}` / `{base.field}` text expression back to the
+ * StringLiteral node that holds its text, or null when it can't be targeted
+ * confidently. `base` is resolved through three bindings — a `.map()` callback
+ * param (array items), a component PROP (each `<Comp prop={…}>` usage), or a
+ * local `const` — and each candidate is run through the bounded evaluator
+ * (`beat.caption` where `beat={BEATS[0]}` → `BEATS[0].caption`). The occurrence
+ * index picks the slot; `before` verifies it and rescues a drifted index; ties
+ * are never guessed. `occurrence`/`before` come from the edited DOM instance.
+ */
+function resolveDynamicTextSpan(
+  program: AnyNode,
+  element: AnyNode,
+  expr: AnyNode,
+  id: string,
+  opts?: DynamicTextOpts
+): AnyNode | null {
+  // Decompose into base Identifier + optional single field.
+  let baseName: string;
+  let field: string | null;
+  if (expr?.type === 'Identifier') {
+    baseName = expr.name;
+    field = null;
+  } else if (
+    expr?.type === 'MemberExpression' &&
+    !expr.computed &&
+    expr.object?.type === 'Identifier' &&
+    expr.property?.type === 'Identifier'
+  ) {
+    baseName = expr.object.name;
+    field = expr.property.name;
+  } else {
+    return null;
+  }
+
+  // Candidate value-expressions for `base`, one per rendered slot.
+  let candidates: Array<AnyNode | null> | null = null;
+  // (1) a `.map()` callback param → the array items.
+  const arrExpr = findEnclosingMapArray(program, element, baseName);
+  if (arrExpr) {
+    const arr = resolveArrayExpr(program, arrExpr);
+    candidates = arr ? (arr.elements ?? []) : null;
+  }
+  // (2) a component prop → each `<Comp base={…}>` usage's value.
+  if (!candidates) {
+    const componentName =
+      collectElementsFull(program).find((e) => e.id === id)?.componentName ?? '';
+    candidates = componentUsageValues(program, componentName, baseName);
+  }
+  // (3) a local const → a single candidate.
+  if (!candidates) {
+    let init: AnyNode | null = null;
+    walkAst(program, (n) => {
+      if (
+        n.type === 'VariableDeclarator' &&
+        n.id?.type === 'Identifier' &&
+        n.id.name === baseName
+      ) {
+        init = n.init ?? null;
+      }
+    });
+    candidates = init ? [init] : null;
+  }
+  if (!candidates) return null;
+  // Complexity cap (ethical-hacker F-C): each candidate runs a full-program
+  // walkAst per resolution step, so an attacker-authored canvas with a huge
+  // array of `{identifier}` items could make this O(N × program). A real
+  // `.map()`/usage list is tiny; anything past the cap is refused (a single
+  // edit couldn't confidently target one of thousands of slots anyway).
+  const MAX_CANDIDATES = 1000;
+  if (candidates.length > MAX_CANDIDATES) return null;
+
+  // Resolve each candidate to a StringLiteral (applying `.field` when present).
+  const lits: Array<AnyNode | null> = candidates.map((c) => {
+    const base = resolveValueNode(program, c);
+    if (!base) return null;
+    if (field) {
+      const v = resolveValueNode(program, objPropValue(base, field));
+      return isStringLit(v) ? v : null;
+    }
+    return isStringLit(base) ? base : null;
+  });
+
+  // Pick: occurrence index (verified by `before`), else the UNIQUE `before`
+  // match, else — only with no `before` to verify — the raw index. No guessing.
+  const beforeTrim = (opts?.before ?? '').trim();
+  const occ = typeof opts?.occurrence === 'number' && opts.occurrence >= 0 ? opts.occurrence : null;
+  const at = occ != null ? lits[occ] : null;
+  if (at && (!beforeTrim || String(at.value).trim() === beforeTrim)) return at;
+  if (beforeTrim) {
+    const hits = lits.filter((c): c is AnyNode => !!c && String(c.value).trim() === beforeTrim);
+    return hits.length === 1 ? (hits[0] ?? null) : null;
+  }
+  return at ?? null;
+}
+
 // ---------------------------------------------------------------------------
 // Node-move reorder (DDR-138, phase-12.1). Moving a whole JSXElement to a new
 // sibling/parent position — the one structural edit `editAttribute`/`editText`
@@ -2842,6 +3159,138 @@ export async function insertElement(
   });
 }
 
+/**
+ * Insert a synthesized element as a child of the `<DCArtboard id="…">` itself —
+ * the empty-artboard fallback for the tool-palette "+ Element" affordance
+ * (Stage I3 tail addendum). `applyInsertElement` needs a sibling `data-cd-id`
+ * to anchor on; a freshly-scaffolded or fully-cleared artboard has none, so
+ * this variant anchors on the DCArtboard JSX node itself (addressed by its
+ * `id` PROP, same convention as `applyResizeArtboard`/`applyDeleteArtboard` —
+ * an artboard's rendered `<article data-dc-screen>` carries no `data-cd-id`).
+ * Only `inside-start`/`inside-end` make sense here (no sibling to be
+ * before/after). Pure; reparse-gated like `applyInsertElement`.
+ */
+export function applyInsertElementIntoArtboard(
+  canvasAbsPath: string,
+  source: string,
+  artboardId: string,
+  position: 'inside-start' | 'inside-end',
+  kind: InsertKind,
+  opts?: { src?: string }
+): { source: string; newId: string | null } {
+  if (kind === 'image') {
+    if (!opts?.src?.trim()) {
+      throw new CanvasEditError('insert image requires a contained asset src (assets/…)', {
+        canvas: canvasAbsPath,
+        id: artboardId,
+      });
+    }
+    assertContainedAssetSrc(opts.src, canvasAbsPath);
+  }
+  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,
+    });
+  }
+  if (target.openingElement?.selfClosing || !target.closingElement) {
+    throw new CanvasEditError(
+      `<DCArtboard id="${artboardId}"> is self-closing — cannot nest an element inside it`,
+      { canvas: canvasAbsPath, id: artboardId }
+    );
+  }
+
+  const rStart = target.start as number;
+  const indentUnit = detectIndentUnit(source);
+  const newText = synthInsertElement(kind, opts?.src);
+  const targetIndent = lineStartInfo(source, rStart).indent + indentUnit;
+
+  let anchor: number;
+  let insertText: string;
+  if (position === 'inside-start') {
+    anchor = target.openingElement.end as number;
+    insertText = `\n${targetIndent}${newText}`;
+  } else {
+    const cStart = target.closingElement.start as number;
+    const cLine = lineStartInfo(source, cStart);
+    if (cLine.newlineBefore) {
+      anchor = cLine.indentStart - 1;
+      insertText = `\n${targetIndent}${newText}`;
+    } else {
+      anchor = cStart;
+      insertText = `${newText}`;
+    }
+  }
+
+  const s = new MagicString(source);
+  s.appendLeft(anchor, insertText);
+  const out = s.toString();
+  const check = parseSync(canvasAbsPath, out, { sourceType: 'module' });
+  if (check.errors && check.errors.length > 0) {
+    throw new CanvasEditError(
+      `insert would produce invalid source (${check.errors[0]?.message ?? 'parse error'}); aborted`,
+      { canvas: canvasAbsPath, id: artboardId }
+    );
+  }
+  // Same post-insert id recomputation as applyInsertElement — single append,
+  // no removes, so the new element's `<` lands at this exact offset in `out`.
+  const prefixLen = insertText.indexOf(newText);
+  const elemStart = anchor + prefixLen;
+  let newId: string | null = null;
+  let fallback: string | null = null;
+  for (const { id: eid, node } of collectElements(check.program)) {
+    if ((node.start as number) === elemStart) {
+      newId = eid;
+      break;
+    }
+    if (out.slice(node.start as number, node.end as number) === newText) fallback = eid;
+  }
+  return { source: out, newId: newId ?? fallback };
+}
+
+/** Insert an element into an artboard by artboardId (no ref sibling) on disk. */
+export async function insertElementIntoArtboard(
+  canvasAbsPath: string,
+  artboardId: string,
+  position: 'inside-start' | 'inside-end',
+  kind: InsertKind,
+  opts?: { src?: string }
+): Promise<{ source: string; newId: string | null }> {
+  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 = applyInsertElementIntoArtboard(
+      canvasAbsPath,
+      source,
+      artboardId,
+      position,
+      kind,
+      opts
+    );
+    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;
+  });
+}
+
 /**
  * Duplicate the element with `data-cd-id === id` — insert a verbatim copy of its
  * source as the next sibling (Cmd+D, Task L3). Since the SOURCE carries no
@@ -2957,8 +3406,14 @@ function collectJsxByTag(program: AnyNode, tagName: string): AnyNode[] {
  * `width="430"` and break the numeric prop. Overwrites an existing `{expr}` or
  * `"literal"`, or inserts the attribute after the tag name if missing.
  */
-function writeNumericAttr(s: MagicString, opening: AnyNode, name: string, value: number): void {
-  const num = Math.max(1, Math.round(value));
+function writeNumericAttr(
+  s: MagicString,
+  opening: AnyNode,
+  name: string,
+  value: number,
+  min = 1
+): void {
+  const num = Math.max(min, Math.round(value));
   const attr = findAttribute(opening, name);
   if (attr) {
     const v = attr.value;
@@ -3045,6 +3500,195 @@ export async function resizeArtboard(
   });
 }
 
+/**
+ * Write/clear a BARE JSX boolean attribute (`<DCArtboard fixed>`, not
+ * `fixed={true}` or a string). `value=false` reuses `removeStringAttr`'s
+ * generic span-plus-leading-whitespace removal (it doesn't care whether the
+ * attribute it's removing has a value) — only the `true` insert path is new.
+ */
+function writeBooleanAttr(
+  s: MagicString,
+  opening: AnyNode,
+  name: string,
+  value: boolean,
+  source: string
+): void {
+  if (!value) {
+    removeStringAttr(s, opening, name, source);
+    return;
+  }
+  if (findAttribute(opening, name)) return; // already present in some form
+  const insertAt: number | undefined = opening?.name?.end;
+  if (typeof insertAt !== 'number') throw new Error('Opening element has no resolvable name range');
+  s.appendLeft(insertAt, ` ${name}`);
+}
+
+/**
+ * Toggle an artboard's height sizing mode (Hug ⇄ Fixed CSS-panel control).
+ * `fixed=true` adds the bare `fixed` prop and, when `freezeHeight` is given
+ * (the board's current measured height), also writes it as the exact
+ * `height` — so pinning to Fixed doesn't snap the box back to whatever the
+ * JSX `height` floor happened to be. `fixed=false` removes the `fixed` prop;
+ * `height` is left as-is (it resumes being the hug floor). Same id-prop
+ * addressing as applyResizeArtboard (DDR-027 — an artboard frame carries no
+ * data-cd-id). Pure; reparse-gated.
+ */
+export function applySetArtboardHug(
+  canvasAbsPath: string,
+  source: string,
+  artboardId: string,
+  fixed: boolean,
+  freezeHeight?: number
+): { 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);
+  writeBooleanAttr(s, target.openingElement, 'fixed', fixed, source);
+  if (fixed && typeof freezeHeight === 'number') {
+    writeNumericAttr(s, target.openingElement, 'height', freezeHeight);
+  }
+  const out = s.toString();
+  const check = parseSync(canvasAbsPath, out, { sourceType: 'module' });
+  if (check.errors && check.errors.length > 0) {
+    throw new CanvasEditError(
+      `artboard hug-toggle produced invalid source (${check.errors[0]?.message ?? 'parse error'})`,
+      { canvas: canvasAbsPath, id: artboardId }
+    );
+  }
+  return { source: out };
+}
+
+/** Set an artboard's Hug/Fixed mode on disk (atomic write + cross-process lock). */
+export async function setArtboardHug(
+  canvasAbsPath: string,
+  artboardId: string,
+  fixed: boolean,
+  freezeHeight?: number
+): 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 = applySetArtboardHug(canvasAbsPath, source, artboardId, fixed, freezeHeight);
+    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;
+  });
+}
+
+/** Patch shape for {@link applySetArtboardStyle} — `null` resets/removes that
+ *  prop back to the engine default; `undefined`/absent leaves it untouched. */
+export interface ArtboardStylePatch {
+  background?: string | null;
+  padding?: number | null;
+  layout?: string | null;
+  gap?: number | null;
+}
+
+/**
+ * Write the artboard "more settings" props (background / padding / layout /
+ * gap) — applied to `.dc-artboard-body` by DCArtboard, not the frame chrome.
+ * String props (background/layout) reuse `editStringAttr`/`removeStringAttr`;
+ * numeric props (padding/gap) reuse `writeNumericAttr` with a 0 floor (unlike
+ * width/height, 0 padding/gap is a normal value, not a degenerate one). Same
+ * id-prop addressing + reparse-gate as applyResizeArtboard/applySetArtboardHug.
+ */
+export function applySetArtboardStyle(
+  canvasAbsPath: string,
+  source: string,
+  artboardId: string,
+  patch: ArtboardStylePatch
+): { 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 ('background' in patch) {
+    if (patch.background == null) removeStringAttr(s, opening, 'background', source);
+    else editStringAttr(s, opening, 'background', patch.background, canvasAbsPath, artboardId);
+  }
+  if ('layout' in patch) {
+    if (patch.layout == null) removeStringAttr(s, opening, 'layout', source);
+    else editStringAttr(s, opening, 'layout', patch.layout, canvasAbsPath, artboardId);
+  }
+  if ('padding' in patch) {
+    if (patch.padding == null) removeStringAttr(s, opening, 'padding', source);
+    else writeNumericAttr(s, opening, 'padding', patch.padding, 0);
+  }
+  if ('gap' in patch) {
+    if (patch.gap == null) removeStringAttr(s, opening, 'gap', source);
+    else writeNumericAttr(s, opening, 'gap', patch.gap, 0);
+  }
+  const out = s.toString();
+  const check = parseSync(canvasAbsPath, out, { sourceType: 'module' });
+  if (check.errors && check.errors.length > 0) {
+    throw new CanvasEditError(
+      `artboard style edit produced invalid source (${check.errors[0]?.message ?? 'parse error'})`,
+      { canvas: canvasAbsPath, id: artboardId }
+    );
+  }
+  return { source: out };
+}
+
+/** Set an artboard's style props on disk (atomic write + cross-process lock). */
+export async function setArtboardStyle(
+  canvasAbsPath: string,
+  artboardId: string,
+  patch: ArtboardStylePatch
+): 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 = applySetArtboardStyle(canvasAbsPath, source, artboardId, patch);
+    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;
+  });
+}
+
 /**
  * Delete the `<DCArtboard id="…">` whose `id` prop equals `artboardId` — the
  * artboard counterpart of applyDeleteElement (an artboard is addressed by its id