@1agh/maude 0.42.0 → 0.43.0

package/apps/studio/bin/read-annotations.mjs

@@ -105,8 +105,15 @@ Args:
   --json              No-op (JSON is the only output form).
 
 FigJam v3 additive fields per annotation: z (render order), groupIds (deepest →
-shallowest), author ("ai" for annotate-verb strokes), and from/to host ids on
-bound arrows.
+shallowest), author ("ai" for annotate-verb strokes), authorName/authorId
+(human-drawn stickies), and from/to host ids on bound arrows.
+
+Section annotations additionally carry members: an array of every OTHER
+annotation whose center falls inside the section's rect, in SPATIAL reading
+order (top-to-bottom, left-to-right — not paint order), each as
+{ id, tool, order, x, y, w, h, href? }. Answers "what's in this section, and
+in what order" for prompts like "make a video / Instagram carousel from
+this section" without hand-computing containment.
 
 Emits JSON to stdout. A missing annotation file emits [] (exit 0).`;
 
@@ -395,6 +402,31 @@ function readUnknown(tool, attrs, inner) {
 // provenance, render order (z = document position). Applied uniformly after
 // the per-tool extraction; arrows additionally surface bound endpoints as
 // `from`/`to` host ids so a bound diagram reads back as a GRAPH.
+const AUTHOR_NAME_MAX_LEN = 64;
+
+// Phase 3 (whiteboard-improvements) — mirrors annotations-model.ts's
+// sanitizeAuthorName (same code-point ranges: control chars, bidi
+// overrides/isolates, zero-width chars, BOM) so a peer-synced
+// `.annotations.svg`'s authorName/authorId reads identically through
+// either surface. Every string this CLI returns is already treated as DATA
+// by the whiteboard skill's trust model — this additionally strips the
+// characters that could visually spoof an author name.
+function sanitizeAuthorName(raw) {
+  let cleaned = '';
+  for (const ch of raw) {
+    const cp = ch.codePointAt(0) ?? 0;
+    const unsafe =
+      cp <= 0x1f ||
+      (cp >= 0x7f && cp <= 0x9f) ||
+      (cp >= 0x200b && cp <= 0x200f) ||
+      (cp >= 0x202a && cp <= 0x202e) ||
+      (cp >= 0x2066 && cp <= 0x2069) ||
+      cp === 0xfeff;
+    if (!unsafe) cleaned += ch;
+  }
+  return cleaned.trim().slice(0, AUTHOR_NAME_MAX_LEN);
+}
+
 function withShared(o, attrs, z) {
   o.z = z;
   const g = attr(attrs, 'data-group-ids');
@@ -403,6 +435,16 @@ function withShared(o, attrs, z) {
     if (ids.length) o.groupIds = ids;
   }
   if (attr(attrs, 'data-author') === 'ai') o.author = 'ai';
+  const authorName = attr(attrs, 'data-author-name');
+  if (authorName) {
+    const cleaned = sanitizeAuthorName(decodeEntities(authorName));
+    if (cleaned) o.authorName = cleaned;
+  }
+  const authorId = attr(attrs, 'data-author-id');
+  if (authorId) {
+    const cleanedId = sanitizeAuthorName(decodeEntities(authorId));
+    if (cleanedId) o.authorId = cleanedId;
+  }
   if (o.tool === 'arrow') {
     const sb = parseBind(attr(attrs, 'data-start-bind'));
     if (sb) o.from = sb.hostId;
@@ -615,6 +657,85 @@ function anchorToElement(ann, elements) {
   };
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Section membership + reading order (Phase 5, feature-whiteboard-
+// annotation-improvements). A common flow: the user drops several media/
+// stickies INTO a section, then asks "make a video from this" / "turn this
+// into an Instagram carousel" — the agent needs to know exactly which
+// annotations live in a given section, and in what visual order, without
+// hand-computing containment or guessing from raw x/y. Mirrors
+// `findElement`'s smallest-containing-rect convention (annotation CENTER
+// inside a rect), applied against SECTION rects instead of DOM element
+// rects.
+
+/**
+ * Spatial reading order — top-to-bottom, then left-to-right — NOT `z`
+ * (paint/document order): a user can drop stickies in any order they like,
+ * and assembling a carousel/video in PAINT order would visibly scramble it.
+ * Rows are bucketed by a Y-tolerance band (half the smallest member's
+ * height, floored at 16 units) so items a few units off from each other
+ * still read as "the same row"; `z` only breaks a true tie (same band, same
+ * x) between two members.
+ */
+function attachSectionMembers(annotations) {
+  const sections = annotations.filter((a) => a.tool === 'section' && a.id);
+  if (!sections.length) return annotations;
+
+  const centerOf = (a) => {
+    if (a.x == null || a.y == null) return null;
+    return { cx: a.x + (a.w || 0) / 2, cy: a.y + (a.h || 0) / 2 };
+  };
+
+  const membersBySection = new Map();
+  for (const section of sections) {
+    const sx1 = section.x;
+    const sy1 = section.y;
+    const sx2 = section.x + (section.w || 0);
+    const sy2 = section.y + (section.h || 0);
+    const candidates = [];
+    for (const a of annotations) {
+      if (a.tool === 'section' || !a.id) continue;
+      const c = centerOf(a);
+      if (!c) continue;
+      if (c.cx < sx1 || c.cx > sx2 || c.cy < sy1 || c.cy > sy2) continue;
+      candidates.push({ ann: a, c });
+    }
+    if (!candidates.length) {
+      membersBySection.set(section.id, []);
+      continue;
+    }
+    const heights = candidates.map((m) => m.ann.h || 0).filter((h) => h > 0);
+    const minHeight = heights.length ? Math.min(...heights) : 40;
+    const band = Math.max(16, minHeight / 2);
+    candidates.sort((m1, m2) => {
+      const dy = m1.c.cy - m2.c.cy;
+      if (Math.abs(dy) > band) return dy;
+      const dx = m1.c.cx - m2.c.cx;
+      if (dx !== 0) return dx;
+      return (m1.ann.z ?? 0) - (m2.ann.z ?? 0);
+    });
+    membersBySection.set(
+      section.id,
+      candidates.map((m, i) => ({
+        id: m.ann.id,
+        tool: m.ann.tool,
+        order: i,
+        x: m.ann.x,
+        y: m.ann.y,
+        w: m.ann.w,
+        h: m.ann.h,
+        ...(m.ann.href ? { href: m.ann.href } : null),
+      }))
+    );
+  }
+
+  return annotations.map((a) =>
+    a.tool === 'section' && membersBySection.has(a.id)
+      ? { ...a, members: membersBySection.get(a.id) }
+      : a
+  );
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Main
 
@@ -674,6 +795,7 @@ function main() {
   if (artboards.length) {
     annotations = annotations.map((a) => anchorToArtboard(a, artboards));
   }
+  annotations = attachSectionMembers(annotations);
 
   if (args.graph) {
     process.stdout.write(`${JSON.stringify({ annotations, graph: buildGraph(annotations) })}\n`);
@@ -689,6 +811,7 @@ function main() {
 // canvas-rects manifest without a second implementation.
 export {
   anchorToElement,
+  attachSectionMembers,
   buildGraph,
   fileSlug,
   findElement,

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