chalkbridge 1.0.4 → 1.1.1

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { SceneElement, PackName, PackKind, IconId, SceneId, Scene, SnapshotId, SERVER_MANAGED_FIELDS, BINDING_FIELDS, GUIDE_TOPICS, DetailLevel, createNodeSkeletonExpander, ok, fail, bridgeSpawnFailed, bridgeVersionMismatch, bridgeUnreachable, GuideTopic, storeUnavailable, describeThrown, unreadableSceneFile, pathOutsideRepo, packInstallFailed, sceneFileMissing, notAPack, PackRecipe, portUnavailable, DescribeSceneOutput, DescribeSceneInput, GetSelectionOutput, GetSelectionInput, GetElementsOutput, GetElementsInput, ListScenesOutput, ListScenesInput, SceneSettingsOutput, SceneSettingsInput, SearchIconsOutput, SearchIconsInput, ScreenshotOutput, ScreenshotInput, ReadMeOutput, ReadMeInput, PlaceIconOutput, PlaceIconInput, SnapshotOutput, SnapshotInput, RestoreSnapshotOutput, RestoreSnapshotInput, ExportSceneOutput, ExportSceneInput, ImportSceneOutput, ImportSceneInput, ExportImageOutput, ExportImageInput, InstallPackOutput, InstallPackInput, notARepo, ScreenshotResponse, RemovePackOutput, ListPacksOutput, RawElementsOutput, FocusOutput, EmbedOutput, AnnotateOutput, FrameOutput, UngroupOutput, GroupOutput, ArrangeOutput, DeleteElementsOutput, UpdateElementsOutput, ConnectOutput, CreateElementsOutput, HealthResponse, iconIdOf, unknownScene, unknownSnapshot, exportFailed, unknownIcon, HOUSE, FileId, ElementId, diskConflict, refusedFieldMessage, idCollision, expansionFailed, emptySelection, unknownElement, frameIdOf, GroupId, staleVersion, noBoundLabel, deepEqual, exportTimedOut, noBrowser, DebugElementRequest, CreateElementsInput, ConnectToolInput, UpdateElementsInput, DeleteElementsInput, ArrangeToolInput, GroupInput, UngroupInput, FrameInput, AnnotateInput, EmbedInput, FocusInput, RawElementsInput, ListPacksInput, RemovePackInput, DataUrl, Index, ROUNDNESS, STALE_SELECTION_MS, noScenes, ClientMessage, assertNever, PROTOCOL_VERSION, ApiError, EXCALIDRAW_FILE_VERSION, EXCALIDRAW_FILE_TYPE, point, FLAG_GLYPH, KIND_ABBREVIATION, catalogUnavailable, FrameId, IconItem, ExcalidrawFile } from './chunk-U2ZMSGNS.js';
+import { SceneElement, PackName, PackKind, IconId, SceneId, Scene, SnapshotId, SERVER_MANAGED_FIELDS, BINDING_FIELDS, GUIDE_TOPICS, DetailLevel, createNodeSkeletonExpander, ok, fail, bridgeSpawnFailed, bridgeVersionMismatch, bridgeUnreachable, GuideTopic, storeUnavailable, describeThrown, unreadableSceneFile, pathOutsideRepo, packInstallFailed, sceneFileMissing, notAPack, PackRecipe, portUnavailable, DescribeSceneOutput, DescribeSceneInput, GetSelectionOutput, GetSelectionInput, GetElementsOutput, GetElementsInput, ListScenesOutput, ListScenesInput, SceneSettingsOutput, SceneSettingsInput, SearchIconsOutput, SearchIconsInput, ScreenshotOutput, ScreenshotInput, ReadMeOutput, ReadMeInput, PlaceIconOutput, PlaceIconInput, SnapshotOutput, SnapshotInput, RestoreSnapshotOutput, RestoreSnapshotInput, ExportSceneOutput, ExportSceneInput, ImportSceneOutput, ImportSceneInput, ExportImageOutput, ExportImageInput, InstallPackOutput, InstallPackInput, notARepo, ScreenshotResponse, RemovePackOutput, ListPacksOutput, RawElementsOutput, FocusOutput, EmbedOutput, AnnotateOutput, FrameOutput, UngroupOutput, GroupOutput, ArrangeOutput, DeleteElementsOutput, UpdateElementsOutput, ConnectOutput, CreateElementsOutput, HealthResponse, iconIdOf, unknownScene, unknownSnapshot, exportFailed, unknownIcon, HOUSE, FileId, ElementId, diskConflict, refusedFieldMessage, idCollision, expansionFailed, emptySelection, unknownElement, measureLine, frameIdOf, GroupId, staleVersion, noBoundLabel, deepEqual, exportTimedOut, noBrowser, DebugElementRequest, CreateElementsInput, ConnectToolInput, UpdateElementsInput, DeleteElementsInput, ArrangeToolInput, GroupInput, UngroupInput, FrameInput, AnnotateInput, EmbedInput, FocusInput, RawElementsInput, ListPacksInput, RemovePackInput, iconNeedsAPlace, DataUrl, Index, wrapLines, ROUNDNESS, STALE_SELECTION_MS, noScenes, ClientMessage, assertNever, PROTOCOL_VERSION, ApiError, EXCALIDRAW_FILE_VERSION, EXCALIDRAW_FILE_TYPE, point, FLAG_GLYPH, KIND_ABBREVIATION, catalogUnavailable, FrameId, IconItem, ExcalidrawFile } from './chunk-XFH76JS6.js';
 import './chunk-7D4SUZUM.js';
 import { appendFileSync, existsSync, mkdirSync } from 'node:fs';
 import { homedir } from 'node:os';
@@ -2025,6 +2025,254 @@ function createExportBroker(options, deps) {
   };
 }
 
+// src/domain/scene/overlaps.ts
+var MIN_OVERLAP_PX = 2;
+var MAX_REPORTED_OVERLAPS = 12;
+function routeMidpoint(arrow) {
+  const points = arrow.points;
+  const lengths = points.slice(1).map((p, i) => {
+    const prev = points[i];
+    const [px2, py] = p;
+    if (prev === void 0 || px2 === void 0 || py === void 0) return 0;
+    const [qx, qy] = prev;
+    if (qx === void 0 || qy === void 0) return 0;
+    return Math.hypot(px2 - qx, py - qy);
+  });
+  let want = lengths.reduce((sum, l) => sum + l, 0) / 2;
+  for (let i = 0; i < lengths.length; i++) {
+    const from = points[i];
+    const to = points[i + 1];
+    const length = lengths[i];
+    if (from === void 0 || to === void 0 || length === void 0) continue;
+    const [fx, fy] = from;
+    const [tx, ty] = to;
+    if (fx === void 0 || fy === void 0 || tx === void 0 || ty === void 0) continue;
+    if (want > length && i < lengths.length - 1) {
+      want -= length;
+      continue;
+    }
+    const k = length === 0 ? 0 : want / length;
+    return { x: arrow.x + fx + (tx - fx) * k, y: arrow.y + fy + (ty - fy) * k };
+  }
+  return { x: arrow.x, y: arrow.y };
+}
+function renderedRect(element, byId) {
+  if (element.type !== "text" || element.containerId === null) return element;
+  const container = byId.get(element.containerId);
+  if (container === void 0 || container.type !== "arrow") return element;
+  const mid = routeMidpoint(container);
+  return {
+    x: mid.x - element.width / 2,
+    y: mid.y - element.height / 2,
+    width: element.width,
+    height: element.height
+  };
+}
+var intersection = (a, b) => ({
+  width: Math.min(a.x + a.width, b.x + b.width) - Math.max(a.x, b.x),
+  height: Math.min(a.y + a.height, b.y + b.height) - Math.max(a.y, b.y)
+});
+function rectsOverlap(a, b) {
+  const { width, height } = intersection(a, b);
+  return width >= MIN_OVERLAP_PX && height >= MIN_OVERLAP_PX;
+}
+function frameOf(element, byId) {
+  if (element.frameId !== null) return element.frameId;
+  if (element.type !== "text" || element.containerId === null) return null;
+  return byId.get(element.containerId)?.frameId ?? null;
+}
+function nested(a, b, byId) {
+  if (a.type === "frame" && frameOf(b, byId) === frameIdOf(a.id)) return true;
+  if (b.type === "frame" && frameOf(a, byId) === frameIdOf(b.id)) return true;
+  if (a.type === "text" && a.containerId === b.id && b.type !== "arrow") return true;
+  if (b.type === "text" && b.containerId === a.id && a.type !== "arrow") return true;
+  return false;
+}
+var participates = (element) => !element.isDeleted && element.type !== "arrow" && element.type !== "line" && // Frames are regions, not shapes. One is 600 px across, so nearly everything near it
+// intersects its area — and unlike a box it does not obscure what it covers, because a
+// frame only clips its *own* children. Reporting non-children put a warning on every
+// framed diagram, which is the noise this file exists to avoid. The case that genuinely
+// hides content — a child outside the frame holding it — is prevented rather than
+// reported: `frames.refitFrames` grows the frame on every path that can move a child.
+element.type !== "frame" && element.width > 0 && element.height > 0;
+function wouldCollide(candidate, elements, ignore = /* @__PURE__ */ new Set()) {
+  const byId = new Map(elements.map((element) => [element.id, element]));
+  return elements.filter(participates).filter((element) => !ignore.has(element.id)).some((element) => rectsOverlap(candidate, renderedRect(element, byId)));
+}
+function findOverlaps(elements) {
+  const byId = new Map(elements.map((element) => [element.id, element]));
+  const live = elements.filter(participates);
+  const found = [];
+  for (let i = 0; i < live.length; i++) {
+    const a = live[i];
+    if (a === void 0) continue;
+    for (let j = i + 1; j < live.length; j++) {
+      const b = live[j];
+      if (b === void 0) continue;
+      if (nested(a, b, byId)) continue;
+      const { width, height } = intersection(renderedRect(a, byId), renderedRect(b, byId));
+      if (width < MIN_OVERLAP_PX || height < MIN_OVERLAP_PX) continue;
+      found.push({ a: a.id, b: b.id, width: Math.round(width), height: Math.round(height) });
+    }
+  }
+  return found.sort(
+    (p, q) => q.width * q.height - p.width * p.height || (p.a < q.a ? -1 : p.a > q.a ? 1 : 0) || (p.b < q.b ? -1 : p.b > q.b ? 1 : 0)
+  );
+}
+function overlapWarning(elements) {
+  const found = findOverlaps(elements);
+  const worst = found[0];
+  if (worst === void 0) return null;
+  const size = `${Math.round(worst.width)}x${Math.round(worst.height)}`;
+  const count2 = found.length === 1 ? "1 overlap" : `${found.length} overlaps`;
+  return `${count2} on the canvas \u2014 worst ${worst.a} \xD7 ${worst.b} (${size}). chalk_describe_scene lists them; chalk_arrange moves them apart`;
+}
+
+// src/domain/scene/anchors.ts
+var ANCHOR_GAP = 12;
+var anchorsOf = (element) => element.customData?.chalk?.anchorIds ?? [];
+var isAnchored = (element) => anchorsOf(element).length > 0;
+function anchoredPosition(anchor, size, placement) {
+  const midX = anchor.x + anchor.width / 2 - size.width / 2;
+  const midY = anchor.y + anchor.height / 2 - size.height / 2;
+  switch (placement) {
+    case "above":
+      return { x: midX, y: anchor.y - size.height - ANCHOR_GAP };
+    case "below":
+      return { x: midX, y: anchor.y + anchor.height + ANCHOR_GAP };
+    case "left":
+      return { x: anchor.x - size.width - ANCHOR_GAP, y: midY };
+    case "right":
+      return { x: anchor.x + anchor.width + ANCHOR_GAP, y: midY };
+    case "badge":
+      return { x: anchor.x + anchor.width - size.width / 2, y: anchor.y - size.height / 2 };
+    case "inside":
+      return { x: midX, y: midY };
+  }
+}
+var captionBelow = (position, size) => ({
+  x: position.x,
+  y: position.y + size.height + 8
+});
+function withAnchoredElements(scene, deltas) {
+  const attached = scene.filter((element) => !element.isDeleted && isAnchored(element));
+  if (attached.length === 0) return deltas;
+  const widened = new Map(deltas);
+  const present2 = new Set(scene.filter((element) => !element.isDeleted).map((e) => e.id));
+  for (const element of attached) {
+    if (widened.has(element.id)) continue;
+    const live = anchorsOf(element).filter((id) => present2.has(id));
+    if (live.length === 0) continue;
+    const moves = live.map((id) => deltas.get(id));
+    const [first] = moves;
+    if (first === void 0) continue;
+    if (!moves.every((move) => move !== void 0 && move[0] === first[0] && move[1] === first[1])) {
+      continue;
+    }
+    widened.set(element.id, first);
+  }
+  return widened;
+}
+
+// src/domain/scene/recommend.ts
+var ENOUGH_TO_MATTER = 5;
+var HUB_SHARE = 0.5;
+var HUB_MIN_DEGREE = 4;
+var RING_LABEL_WIDTH = 200;
+function recommendLayout(scene, targetIds) {
+  const wanted = new Set(targetIds);
+  const nodes = scene.filter(
+    (element) => wanted.has(element.id) && !isLinear(element) && !isAnchored(element) && !element.isDeleted
+  );
+  if (nodes.length < ENOUGH_TO_MATTER) return null;
+  const ids = new Set(nodes.map((node) => node.id));
+  const degree = new Map(nodes.map((node) => [node.id, 0]));
+  const out = new Map(nodes.map((node) => [node.id, []]));
+  let edges = 0;
+  for (const element of scene) {
+    if (element.type !== "arrow" || element.isDeleted) continue;
+    const from = startOf(element);
+    const to = endOf(element);
+    if (from === null || to === null || from === to) continue;
+    if (!ids.has(from) || !ids.has(to)) continue;
+    edges += 1;
+    degree.set(from, (degree.get(from) ?? 0) + 1);
+    degree.set(to, (degree.get(to) ?? 0) + 1);
+    out.get(from)?.push(to);
+  }
+  if (edges === 0) {
+    return {
+      op: "grid",
+      why: `${nodes.length} elements with no arrows between them \u2014 chalk_arrange(op: "grid") is the layout for a set rather than a graph`
+    };
+  }
+  const busiest = Math.max(...degree.values());
+  const hubShare = busiest / (nodes.length - 1);
+  const depth = longestChain(nodes, out);
+  const widestLabel = Math.max(...nodes.map((node) => node.width));
+  if (hubShare >= HUB_SHARE && busiest >= HUB_MIN_DEGREE) {
+    const hub = nodes.find((node) => (degree.get(node.id) ?? 0) === busiest);
+    const name = hub === void 0 ? "one element" : shortLabel(scene, hub);
+    return widestLabel > RING_LABEL_WIDTH ? {
+      op: "layout-tree",
+      why: `${name} touches ${busiest} of ${nodes.length - 1} others and the labels are wide \u2014 chalk_arrange(op: "layout-tree") puts it on the left and fans the rest out; a ring this wide crosses its own middle`
+    } : {
+      op: "layout-radial",
+      why: `${name} touches ${busiest} of ${nodes.length - 1} others \u2014 chalk_arrange(op: "layout-radial") puts it at the centre, which ranks cannot show`
+    };
+  }
+  return {
+    op: "layout-layered",
+    why: `${nodes.length} elements, ${edges} arrows, longest chain ${depth} \u2014 chalk_arrange(op: "layout-layered") ranks them by the direction of the arrows`
+  };
+}
+function longestChain(nodes, out) {
+  const ON_STACK = 1;
+  const DONE = 2;
+  const state = /* @__PURE__ */ new Map();
+  const depth = /* @__PURE__ */ new Map();
+  const visit = (start) => {
+    const stack = [{ node: start, cursor: 0 }];
+    state.set(start, ON_STACK);
+    while (stack.length > 0) {
+      const frame = stack[stack.length - 1];
+      if (frame === void 0) break;
+      const kids = out.get(frame.node) ?? [];
+      if (frame.cursor >= kids.length) {
+        let best = 1;
+        for (const kid2 of kids) {
+          if (state.get(kid2) === DONE) best = Math.max(best, 1 + (depth.get(kid2) ?? 0));
+        }
+        depth.set(frame.node, best);
+        state.set(frame.node, DONE);
+        stack.pop();
+        continue;
+      }
+      const kid = kids[frame.cursor];
+      frame.cursor += 1;
+      if (kid === void 0 || state.has(kid)) continue;
+      state.set(kid, ON_STACK);
+      stack.push({ node: kid, cursor: 0 });
+    }
+    return depth.get(start) ?? 1;
+  };
+  let longest = 0;
+  for (const node of [...nodes].sort((a, b) => a.id < b.id ? -1 : 1)) {
+    if (!state.has(node.id)) visit(node.id);
+    longest = Math.max(longest, depth.get(node.id) ?? 1);
+  }
+  return longest;
+}
+function shortLabel(scene, element) {
+  const bound = (element.boundElements ?? []).find((b) => b.type === "text")?.id;
+  const caption = bound === void 0 ? void 0 : scene.find((e) => e.id === bound);
+  if (caption !== void 0 && caption.type === "text") {
+    const text = (caption.originalText || caption.text).replace(/\n/g, " ").trim();
+    if (text !== "") return `"${text}"`;
+  }
+  return String(element.id).slice(0, 4);
+}
+
 // src/domain/scene/observe.ts
 var SHORT_ID_LENGTH = 4;
 var shortId2 = (id) => id.slice(0, SHORT_ID_LENGTH);
@@ -2131,6 +2379,7 @@ function observeScene(input) {
   const selected = new Set(input.selectedIds ?? []);
   const context = { labels, frames, selected, detail: input.detail };
   const rows = rowElements(scene.elements).filter((element) => element.type !== "frame");
+  const overlaps = findOverlaps(scene.elements);
   return {
     sceneId: scene.id,
     name: scene.name,
@@ -2139,6 +2388,14 @@ function observeScene(input) {
     updatedAgoMs: Math.max(0, input.now - scene.updatedAt),
     frames: [...frames.values()],
     elements: rows.map((element) => describeElement(element, context)),
+    overlaps: overlaps.slice(0, MAX_REPORTED_OVERLAPS),
+    overlapCount: overlaps.length,
+    // Over the rows, not the raw elements: a caption is part of the box it names, and
+    // counting one as a node would halve every degree the advice is computed from.
+    layoutAdvice: recommendLayout(
+      scene.elements,
+      rows.map((element) => element.id)
+    )?.why ?? null,
     detail: input.detail
   };
 }
@@ -3171,6 +3428,10 @@ function restoreSnapshot(deps) {
       sceneId: scene.id,
       sceneVersion: updated.sceneVersion,
       broadcastTo,
+      // A restore puts back exactly what was saved, so any collision in it is the one the
+      // snapshot was taken with. Worth saying: the reader is often restoring *because* a
+      // layout went wrong, and silence here would read as "the old one was clean".
+      overlapWarning: overlapWarning(snapshot.elements),
       snapshotId: snapshot.summary.id,
       label: snapshot.summary.label,
       restored: snapshot.elements.filter((element) => !element.isDeleted).length
@@ -3195,9 +3456,122 @@ function serviceSize() {
   const [width, height] = HOUSE.sizes.service;
   return { width, height };
 }
+var LINE_HEIGHT = 1.25;
+var quantise = (value) => Math.ceil(value / HOUSE.grid) * HOUSE.grid;
+function labelledSize(label, fontSize = HOUSE.fontSize) {
+  const floor = serviceSize();
+  if (label === void 0 || label === "") return floor;
+  const padX = HOUSE.sizes.labelPadX * 2;
+  const padY = HOUSE.sizes.labelPadY * 2;
+  const oneLine = measureLine(label, fontSize) + padX;
+  const width = Math.max(floor.width, quantise(Math.min(oneLine, HOUSE.sizes.maxBox)));
+  const lines = wrapLines(label, fontSize, width - padX);
+  const height = Math.max(floor.height, quantise(lines.length * fontSize * LINE_HEIGHT + padY));
+  return { width, height };
+}
+
+// src/domain/scene/skeleton.ts
+var isContainer = (type) => type === "rectangle" || type === "diamond" || type === "ellipse";
+function explicit(input) {
+  const kept = {};
+  for (const [key, value] of Object.entries(input)) {
+    if (value === void 0) continue;
+    if (key === "type" || key === "id" || key === "role" || key === "label") continue;
+    kept[key] = value;
+  }
+  return kept;
+}
+var defaultSize = (element) => labelledSize(element.label, element.fontSize ?? HOUSE.fontSize);
+function noteWrap(text, fontSize, requested) {
+  const column = requested ?? HOUSE.sizes.note;
+  if (text === "") return { text };
+  if (requested === void 0 && measureLine(text, fontSize) <= column) return { text };
+  const lines = wrapLines(text, fontSize, column);
+  return { text: lines.join("\n"), width: column, autoResize: false };
+}
+function normalizeElements(input) {
+  return input.elements.map((element, i) => {
+    const fallback = input.ids[i];
+    if (fallback === void 0) {
+      throw new Error(`normalizeElements needs one id per element: none at position ${i}`);
+    }
+    const id = element.id ?? fallback;
+    const role = styleForRole(element.role ?? "compute");
+    const set = explicit(element);
+    if (element.type === "text") {
+      const text = element.text ?? element.label ?? "";
+      const skeleton2 = {
+        type: "text",
+        id,
+        x: element.x,
+        y: element.y,
+        fontSize: HOUSE.fontSize,
+        fontFamily: HOUSE.fontFamily,
+        // A free-standing note is not a service box: it takes the role's ink but never
+        // its fill, because a filled rectangle behind a caption reads as a shape.
+        strokeColor: role.strokeColor,
+        ...set,
+        // Last, because it owns `text`: `explicit` copies the caller's unwrapped string
+        // across and this is what replaces it.
+        ...noteWrap(text, element.fontSize ?? HOUSE.fontSize, element.width)
+      };
+      return skeleton2;
+    }
+    if (element.type === "line") {
+      const skeleton2 = {
+        type: "line",
+        id,
+        x: element.x,
+        y: element.y,
+        strokeColor: role.strokeColor,
+        strokeWidth: HOUSE.strokeWidth,
+        roughness: HOUSE.roughness,
+        ...set,
+        ...element.label === void 0 ? {} : { label: houseLabel(element.label) }
+      };
+      return skeleton2;
+    }
+    if (!isContainer(element.type)) {
+      throw new Error(`normalizeElements cannot build a ${element.type}`);
+    }
+    const skeleton = {
+      type: element.type,
+      id,
+      x: element.x,
+      y: element.y,
+      ...defaultSize(element),
+      ...role,
+      ...set,
+      ...element.label === void 0 ? {} : { label: houseLabel(element.label) }
+    };
+    return skeleton;
+  });
+}
+var LAYOUT_HINT_THRESHOLD = 4;
+function layoutHint(elements) {
+  if (elements.length < LAYOUT_HINT_THRESHOLD) return null;
+  const positions = new Set(elements.map((element) => `${element.x},${element.y}`));
+  if (positions.size > 2) return null;
+  return `${elements.length} elements with no explicit layout \u2014 chalk_arrange(op: "layout-layered") will place them`;
+}
 
 // src/app/usecases/write/annotate-elements.ts
 var NOTE_GAP = 24;
+var NOTE_FONT_SIZE = 16;
+var NOTE_SEARCH_STEP = 40;
+var NOTE_SEARCH_LIMIT = 24;
+function clearSpotBelow(scene, preferred, size) {
+  for (let i = 0; i <= NOTE_SEARCH_LIMIT; i++) {
+    const candidate = {
+      x: preferred.x,
+      y: preferred.y + i * NOTE_SEARCH_STEP,
+      width: size.width,
+      height: size.height
+    };
+    if (!wouldCollide(candidate, scene)) return { x: candidate.x, y: candidate.y };
+  }
+  return preferred;
+}
 function annotateElements(deps) {
   return async (input) => {
     const scene = deps.write.resolve(input.sceneId);
@@ -3212,14 +3586,20 @@ function annotateElements(deps) {
     if (anchors.length === 0) return fail(emptySelection("chalk_annotate"));
     const left = Math.min(...anchors.map((element) => element.x));
     const bottom = Math.max(...anchors.map((element) => element.y + element.height));
+    const wrapped = noteWrap(input.text, NOTE_FONT_SIZE, void 0);
+    const size = {
+      width: wrapped.width ?? measureLine(wrapped.text, NOTE_FONT_SIZE),
+      height: wrapped.text.split("\n").length * NOTE_FONT_SIZE * LINE_HEIGHT
+    };
+    const spot = clearSpotBelow(scene.value.elements, { x: left, y: bottom + NOTE_GAP }, size);
     const skeleton = {
       type: "text",
       id: deps.idGen.elementId(),
-      x: left,
-      y: bottom + NOTE_GAP,
-      text: input.text,
+      x: spot.x,
+      y: spot.y,
+      ...wrapped,
       // A size below the labels, so a note reads as commentary rather than as content.
-      fontSize: 16,
+      fontSize: NOTE_FONT_SIZE,
       fontFamily: HOUSE.fontFamily,
       strokeColor: styleForRole("external").strokeColor,
       customData: {
@@ -3273,6 +3653,74 @@ function focusElements(deps) {
     return ok({ sceneId: scene.value.id, focused, broadcastTo });
   };
 }
+
+// src/domain/scene/frames.ts
+function boundsAround(children) {
+  const pad2 = HOUSE.sizes.framePad;
+  const left = Math.min(...children.map((c) => c.x));
+  const top = Math.min(...children.map((c) => c.y));
+  const right = Math.max(...children.map((c) => c.x + c.width));
+  const bottom = Math.max(...children.map((c) => c.y + c.height));
+  return {
+    x: left - pad2,
+    y: top - pad2,
+    width: right - left + pad2 * 2,
+    // Room at the top for the frame's own name, which renders above its border.
+    height: bottom - top + pad2 * 2
+  };
+}
+function childrenOf(scene, frame) {
+  const id = frameIdOf(frame.id);
+  return scene.filter(
+    (element) => !element.isDeleted && element.id !== frame.id && element.frameId === id
+  );
+}
+function releaseCrossingArrows(scene, frame) {
+  const id = frameIdOf(frame.id);
+  const inside = new Set(childrenOf(scene, frame).map((element) => element.id));
+  const byId = new Map(scene.map((element) => [element.id, element]));
+  return childrenOf(scene, frame).filter((element) => element.type === "arrow" || element.type === "line").filter((arrow) => {
+    if (arrow.type !== "arrow") return true;
+    const from = arrow.startBinding?.elementId;
+    const to = arrow.endBinding?.elementId;
+    if (from === void 0 || to === void 0) return true;
+    return !(inside.has(from) && inside.has(to));
+  }).filter((arrow) => byId.get(arrow.id)?.frameId === id).map((arrow) => ({ ...arrow, frameId: null }));
+}
+function withFrameChildren(scene, deltas) {
+  const frames = scene.filter(
+    (element) => element.type === "frame" && !element.isDeleted && deltas.has(element.id)
+  );
+  if (frames.length === 0) return deltas;
+  const widened = new Map(deltas);
+  for (const frame of frames) {
+    const delta = deltas.get(frame.id);
+    if (delta === void 0) continue;
+    for (const child of childrenOf(scene, frame)) {
+      if (widened.has(child.id)) continue;
+      widened.set(child.id, delta);
+    }
+  }
+  return widened;
+}
+function refitFrames(scene, moved) {
+  if (moved.size === 0) return [];
+  const current = scene.map((element) => moved.get(element.id) ?? element);
+  const refitted = [];
+  for (const element of current) {
+    if (element.type !== "frame" || element.isDeleted) continue;
+    const crossing = new Set(releaseCrossingArrows(current, element).map((a) => a.id));
+    const children = childrenOf(current, element).filter((c) => !crossing.has(c.id));
+    if (children.length === 0) continue;
+    if (!children.some((child) => moved.has(child.id))) continue;
+    const box = boundsAround(children);
+    if (element.x === box.x && element.y === box.y && element.width === box.width && element.height === box.height) {
+      continue;
+    }
+    refitted.push({ ...element, ...box });
+  }
+  return refitted;
+}
 function highestIndex(elements) {
   let highest = null;
   for (const element of elements) {
@@ -3295,6 +3743,176 @@ function betweenIndices(lower, upper, count2) {
   return generateNKeysBetween(lower, upper, count2).map((key) => Index.parse(key));
 }
 
+// src/domain/scene/route.ts
+var ROUTE_CLEARANCE = 30;
+var TURN_PENALTY = 60;
+var MAX_GRID = 64;
+var EPSILON = 1e-3;
+function segmentHitsRect(a, b, rect) {
+  let t0 = 0;
+  let t1 = 1;
+  const dx = b[0] - a[0];
+  const dy = b[1] - a[1];
+  const left = rect.x + EPSILON;
+  const right = rect.x + rect.width - EPSILON;
+  const top = rect.y + EPSILON;
+  const bottom = rect.y + rect.height - EPSILON;
+  const edges = [
+    [-dx, a[0] - left],
+    [dx, right - a[0]],
+    [-dy, a[1] - top],
+    [dy, bottom - a[1]]
+  ];
+  for (const edge of edges) {
+    const den = edge[0];
+    const num = edge[1];
+    if (den === 0) {
+      if (num < 0) return false;
+      continue;
+    }
+    const t = num / den;
+    if (den < 0) {
+      if (t > t1) return false;
+      if (t > t0) t0 = t;
+    } else {
+      if (t < t0) return false;
+      if (t < t1) t1 = t;
+    }
+  }
+  return t1 - t0 > EPSILON;
+}
+function routeHitsAny(points, obstacles) {
+  for (let i = 1; i < points.length; i++) {
+    const a = points[i - 1];
+    const b = points[i];
+    if (a === void 0 || b === void 0) continue;
+    for (const rect of obstacles) if (segmentHitsRect(a, b, rect)) return true;
+  }
+  return false;
+}
+function axis(ends, sides, clearance) {
+  const values = new Set(ends);
+  for (const [low, high] of sides) {
+    values.add(low - clearance);
+    values.add(high + clearance);
+  }
+  const sorted = [...values].sort((a, b) => a - b);
+  if (sorted.length <= MAX_GRID) return sorted;
+  const step = sorted.length / MAX_GRID;
+  const kept = new Set(ends);
+  for (let i = 0; i < MAX_GRID; i++) {
+    const value = sorted[Math.floor(i * step)];
+    if (value !== void 0) kept.add(value);
+  }
+  return [...kept].sort((a, b) => a - b);
+}
+function routeAround(start, end, obstacles, clearance = ROUTE_CLEARANCE) {
+  if (obstacles.length === 0) return null;
+  const xs = axis(
+    [start[0], end[0]],
+    obstacles.map((r) => [r.x, r.x + r.width]),
+    clearance
+  );
+  const ys = axis(
+    [start[1], end[1]],
+    obstacles.map((r) => [r.y, r.y + r.height]),
+    clearance
+  );
+  const xi = xs.indexOf(start[0]);
+  const yi = ys.indexOf(start[1]);
+  const xg = xs.indexOf(end[0]);
+  const yg = ys.indexOf(end[1]);
+  if (xi < 0 || yi < 0 || xg < 0 || yg < 0) return null;
+  const width = xs.length;
+  const index = (cx, cy) => cy * width + cx;
+  const goal = index(xg, yg);
+  const at = (cx, cy) => {
+    const x = xs[cx];
+    const y = ys[cy];
+    return [x ?? 0, y ?? 0];
+  };
+  const passable = (a, b) => {
+    for (const rect of obstacles) if (segmentHitsRect(a, b, rect)) return false;
+    return true;
+  };
+  const total = width * ys.length;
+  const best = new Float64Array(total).fill(Number.POSITIVE_INFINITY);
+  const cameFrom = new Int32Array(total).fill(-1);
+  const arrived = new Uint8Array(total);
+  const done = new Uint8Array(total);
+  const startAt = index(xi, yi);
+  best[startAt] = 0;
+  const heuristic = (cx, cy) => Math.abs((xs[cx] ?? 0) - end[0]) + Math.abs((ys[cy] ?? 0) - end[1]);
+  for (; ; ) {
+    let node = -1;
+    let cheapest = Number.POSITIVE_INFINITY;
+    for (let i = 0; i < total; i++) {
+      if (done[i] === 1) continue;
+      const score = best[i];
+      if (score === void 0 || !Number.isFinite(score)) continue;
+      const estimate = score + heuristic(i % width, Math.floor(i / width));
+      if (estimate < cheapest) {
+        cheapest = estimate;
+        node = i;
+      }
+    }
+    if (node < 0) return null;
+    if (node === goal) break;
+    done[node] = 1;
+    const cx = node % width;
+    const cy = Math.floor(node / width);
+    const here = at(cx, cy);
+    const cost = best[node] ?? 0;
+    const steps = [
+      [cx - 1, cy, 1],
+      [cx + 1, cy, 1],
+      [cx, cy - 1, 2],
+      [cx, cy + 1, 2]
+    ];
+    for (const [nx, ny, axisOf] of steps) {
+      if (nx < 0 || ny < 0 || nx >= width || ny >= ys.length) continue;
+      const next = index(nx, ny);
+      if (done[next] === 1) continue;
+      const there = at(nx, ny);
+      if (!passable(here, there)) continue;
+      const length = Math.abs(there[0] - here[0]) + Math.abs(there[1] - here[1]);
+      const turn = arrived[node] !== 0 && arrived[node] !== axisOf ? TURN_PENALTY : 0;
+      const candidate = cost + length + turn;
+      const known = best[next];
+      if (known === void 0 || candidate < known) {
+        best[next] = candidate;
+        cameFrom[next] = node;
+        arrived[next] = axisOf;
+      }
+    }
+  }
+  const path = [];
+  for (let node = goal; node >= 0; node = cameFrom[node] ?? -1) {
+    path.push(at(node % width, Math.floor(node / width)));
+    if (node === startAt) break;
+  }
+  path.reverse();
+  return simplify(path);
+}
+function simplify(points) {
+  if (points.length < 3) return points;
+  const out = [];
+  for (let i = 0; i < points.length; i++) {
+    const previous = out[out.length - 1];
+    const current = points[i];
+    const next = points[i + 1];
+    if (current === void 0) continue;
+    if (previous === void 0 || next === void 0) {
+      out.push(current);
+      continue;
+    }
+    const straightX = previous[0] === current[0] && current[0] === next[0];
+    const straightY = previous[1] === current[1] && current[1] === next[1];
+    if (!straightX && !straightY) out.push(current);
+  }
+  return out;
+}
+
 // src/domain/scene/arrange.ts
 var boxOf = (element) => ({
   x: element.x,
@@ -3337,7 +3955,39 @@ function edgePoint(from, to, gap) {
   const t = scale + push;
   return [cx + dx * t, cy + dy * t];
 }
-function redrawOne(current, labels, arrow) {
+var ROUTABLE_OBSTACLE = /* @__PURE__ */ new Set(["rectangle", "diamond", "ellipse", "image", "embeddable"]);
+function obstaclesFor(current, fromId, toId) {
+  const out = [];
+  for (const element of current.values()) {
+    if (element.id === fromId || element.id === toId) continue;
+    if (element.isDeleted || !ROUTABLE_OBSTACLE.has(element.type)) continue;
+    out.push(boxOf(element));
+  }
+  return out;
+}
+var NO_FAN = { start: 0, end: 0 };
+function stubFrom(box, at) {
+  const [cx, cy] = centre(box);
+  const horizontal = at[0] <= box.x || at[0] >= box.x + box.width;
+  if (horizontal) return [at[0] + (at[0] < cx ? -ROUTE_CLEARANCE : ROUTE_CLEARANCE), at[1]];
+  return [at[0], at[1] + (at[1] < cy ? -ROUTE_CLEARANCE : ROUTE_CLEARANCE)];
+}
+function anchorOn(box, adjacent, gap) {
+  const [cx, cy] = centre(box);
+  const dx = adjacent[0] - cx;
+  const dy = adjacent[1] - cy;
+  if (dx === 0 && dy === 0) return [cx, cy];
+  const toSide = Math.min(
+    dx === 0 ? Number.POSITIVE_INFINITY : box.width / 2 / Math.abs(dx),
+    dy === 0 ? Number.POSITIVE_INFINITY : box.height / 2 / Math.abs(dy)
+  );
+  const bx = cx + dx * toSide;
+  const by = cy + dy * toSide;
+  const reach = Math.hypot(dx * toSide, dy * toSide);
+  if (reach === 0) return [bx, by];
+  return [bx + dx * toSide * gap / reach, by + dy * toSide * gap / reach];
+}
+function redrawOne(current, labels, arrow, lane) {
   if (arrow.type !== "arrow") return [];
   const fromId = startOf(arrow);
   const toId = endOf(arrow);
@@ -3347,40 +3997,163 @@ function redrawOne(current, labels, arrow) {
   if (from === void 0 || to === void 0) return [];
   const startGap = arrow.startBinding?.gap ?? 4;
   const endGap = arrow.endBinding?.gap ?? 4;
-  const [sx, sy] = edgePoint(boxOf(from), boxOf(to), startGap);
-  const [ex, ey] = edgePoint(boxOf(to), boxOf(from), endGap);
-  const points = [point(0, 0), point(ex - sx, ey - sy)];
+  const elbowed = arrow.elbowed === true;
+  const [sx, sy, ex, ey] = elbowed ? facePoints(boxOf(from), boxOf(to), startGap, endGap, lane) : [
+    ...edgePoint(boxOf(from), boxOf(to), startGap),
+    ...edgePoint(boxOf(to), boxOf(from), endGap)
+  ];
+  const direct = elbowed ? elbowRoute(ex - sx, ey - sy) : [point(0, 0), point(ex - sx, ey - sy)];
+  const obstacles = obstaclesFor(current, fromId, toId);
+  const absolute = direct.map(([px2, py]) => [sx + px2, sy + py]);
+  const detoured = routeHitsAny(absolute, obstacles);
+  const [fsx, fsy, fex, fey] = detoured ? facePoints(boxOf(from), boxOf(to), startGap, endGap, NO_FAN) : [sx, sy, ex, ey];
+  const stubStart = stubFrom(boxOf(from), [fsx, fsy]);
+  const stubEnd = stubFrom(boxOf(to), [fex, fey]);
+  const found = detoured ? routeAround(stubStart, stubEnd, obstacles) : null;
+  const route = found === null ? null : simplify([[fsx, fsy], ...found, [fex, fey]]);
+  const drawn = route ?? direct.map(([px2, py]) => [sx + px2, sy + py]);
+  const settled = [...drawn];
+  const secondFromStart = settled[1];
+  const secondFromEnd = settled[settled.length - 2];
+  if (secondFromStart !== void 0) {
+    settled[0] = anchorOn(boxOf(from), secondFromStart, startGap);
+  }
+  if (secondFromEnd !== void 0) {
+    settled[settled.length - 1] = anchorOn(boxOf(to), secondFromEnd, endGap);
+  }
+  const first = settled[0] ?? [sx, sy];
+  const origin = [first[0], first[1]];
+  const points = settled.map(([ax, ay]) => point(ax - origin[0], ay - origin[1]));
+  const pxs = points.map(([px2]) => px2);
+  const pys = points.map(([, py]) => py);
+  const spans = {
+    w: Math.max(...pxs) - Math.min(...pxs),
+    h: Math.max(...pys) - Math.min(...pys)
+  };
   const redrawn = {
     ...arrow,
-    x: sx,
-    y: sy,
-    width: Math.abs(ex - sx),
-    height: Math.abs(ey - sy),
+    // A detour is an orthogonal route, so it is drawn as one.
+    //
+    // This is not cosmetic. Excalidraw owns the endpoints of a *bound* arrow at paint
+    // time: with `focus: 0` it re-derives where the line meets each box from the segment
+    // adjacent to it, and a detour changes exactly that segment. The stored endpoints are
+    // right — all twenty-nine measured on the boundary of the box they name — and the
+    // canvas still drew several of them leaving from nowhere, because the renderer had
+    // recomputed them from a first segment that now pointed the wrong way. An elbow arrow
+    // is anchored differently and keeps the route it was given.
+    //
+    // The second reason is what it looks like. A right-angled detour rendered with
+    // `roundness` comes out as a long S sweeping across the diagram — which is what the
+    // bend at the bottom of the sample was. Square corners are what an orthogonal route
+    // actually means.
+    ...route === null ? {} : { elbowed: true, roundness: null },
+    x: origin[0],
+    y: origin[1],
+    width: spans.w,
+    height: spans.h,
     points,
     lastCommittedPoint: null
   };
   const label = labels.get(arrow.id);
   if (label === void 0) return [redrawn];
-  return [
-    redrawn,
-    {
-      ...label,
-      x: (sx + ex) / 2 - label.width / 2,
-      y: (sy + ey) / 2 - label.height / 2
-    }
-  ];
+  const mid = routeMidpoint({ x: origin[0], y: origin[1], points });
+  const at = { x: mid.x - label.width / 2, y: mid.y - label.height / 2 };
+  return [redrawn, { ...label, ...at }];
+}
+function faceBetween(from, to) {
+  const [fx, fy] = centre(from);
+  const [tx, ty] = centre(to);
+  const dx = tx - fx;
+  const dy = ty - fy;
+  if (Math.abs(dx) >= Math.abs(dy)) return dx >= 0 ? "right" : "left";
+  return dy >= 0 ? "bottom" : "top";
+}
+var LANE_SPREAD = 44;
+var LANE_INSET = 10;
+function laneOffsets(arrows, current) {
+  const groups = /* @__PURE__ */ new Map();
+  const add = (nodeId, face, node, slot) => {
+    const key = `${nodeId}|${face}`;
+    const bucket = groups.get(key);
+    if (bucket === void 0) groups.set(key, { face, node, slots: [slot] });
+    else bucket.slots.push(slot);
+  };
+  const across = (face, box) => face === "right" || face === "left" ? centre(box)[1] : centre(box)[0];
+  for (const arrow of arrows) {
+    if (arrow.type !== "arrow" || arrow.elbowed !== true) continue;
+    const fromId = startOf(arrow);
+    const toId = endOf(arrow);
+    if (fromId === null || toId === null) continue;
+    const from = current.get(fromId);
+    const to = current.get(toId);
+    if (from === void 0 || to === void 0) continue;
+    const outFace = faceBetween(boxOf(from), boxOf(to));
+    const inFace = faceBetween(boxOf(to), boxOf(from));
+    add(fromId, outFace, boxOf(from), {
+      arrow: arrow.id,
+      end: "start",
+      along: across(outFace, boxOf(to))
+    });
+    add(toId, inFace, boxOf(to), {
+      arrow: arrow.id,
+      end: "end",
+      along: across(inFace, boxOf(from))
+    });
+  }
+  const offsets = /* @__PURE__ */ new Map();
+  for (const { face, node, slots } of groups.values()) {
+    if (slots.length < 2) continue;
+    slots.sort((a, b) => a.along - b.along || (a.arrow < b.arrow ? -1 : 1));
+    const span = face === "right" || face === "left" ? node.height : node.width;
+    const usable = Math.max(0, span - LANE_INSET * 2);
+    const spread = Math.min(LANE_SPREAD, usable / Math.max(1, slots.length - 1));
+    slots.forEach((slot, i) => {
+      const shift = (i - (slots.length - 1) / 2) * spread;
+      const so_far = offsets.get(slot.arrow) ?? { start: 0, end: 0 };
+      offsets.set(slot.arrow, { ...so_far, [slot.end]: shift });
+    });
+  }
+  return offsets;
+}
+function facePoints(from, to, startGap, endGap, lane) {
+  const [fx, fy] = centre(from);
+  const [tx, ty] = centre(to);
+  const dx = tx - fx;
+  const dy = ty - fy;
+  if (Math.abs(dx) >= Math.abs(dy)) {
+    const sx = dx >= 0 ? from.x + from.width + startGap : from.x - startGap;
+    const ex = dx >= 0 ? to.x - endGap : to.x + to.width + endGap;
+    return [sx, fy + lane.start, ex, ty + lane.end];
+  }
+  const sy = dy >= 0 ? from.y + from.height + startGap : from.y - startGap;
+  const ey = dy >= 0 ? to.y - endGap : to.y + to.height + endGap;
+  return [fx + lane.start, sy, tx + lane.end, ey];
+}
+function elbowRoute(dx, dy) {
+  const ALIGNED = 1;
+  if (Math.abs(dy) <= ALIGNED || Math.abs(dx) <= ALIGNED) {
+    return [point(0, 0), point(dx, dy)];
+  }
+  if (Math.abs(dx) >= Math.abs(dy)) {
+    const mid2 = dx / 2;
+    return [point(0, 0), point(mid2, 0), point(mid2, dy), point(dx, dy)];
+  }
+  const mid = dy / 2;
+  return [point(0, 0), point(0, mid), point(dx, mid), point(dx, dy)];
 }
 function redrawArrowsTouching(scene, moved) {
   const current = new Map(scene.map((element) => [element.id, moved.get(element.id) ?? element]));
   const labels = labelsByContainer([...current.values()]);
   const redrawn = [];
+  const lanes = laneOffsets([...current.values()], current);
+  const NO_LANE = { start: 0, end: 0 };
   for (const element of current.values()) {
     if (element.type !== "arrow") continue;
     const fromId = startOf(element);
     const toId = endOf(element);
     if (fromId === null || toId === null) continue;
     if (!moved.has(fromId) && !moved.has(toId)) continue;
-    redrawn.push(...redrawOne(current, labels, element));
+    redrawn.push(...redrawOne(current, labels, element, lanes.get(element.id) ?? NO_LANE));
   }
   return redrawn;
 }
@@ -3388,13 +4161,16 @@ function redrawArrows(scene, ids) {
   const current = new Map(scene.map((element) => [element.id, element]));
   const labels = labelsByContainer(scene);
   const wanted = new Set(ids);
-  return [...current.values()].filter((element) => wanted.has(element.id)).flatMap((element) => redrawOne(current, labels, element));
+  const lanes = laneOffsets([...current.values()], current);
+  const NO_LANE = { start: 0, end: 0 };
+  return [...current.values()].filter((element) => wanted.has(element.id)).flatMap((element) => redrawOne(current, labels, element, lanes.get(element.id) ?? NO_LANE));
 }
 function translate(scene, deltas) {
+  const widened = withAnchoredElements(scene, withFrameChildren(scene, deltas));
   const labels = labelsByContainer(scene);
   const moved = /* @__PURE__ */ new Map();
   for (const element of scene) {
-    const delta = deltas.get(element.id);
+    const delta = widened.get(element.id);
     if (delta === void 0) continue;
     const [dx, dy] = delta;
     if (dx === 0 && dy === 0) continue;
@@ -3404,7 +4180,10 @@ function translate(scene, deltas) {
       moved.set(label.id, { ...label, x: label.x + dx, y: label.y + dy });
     }
   }
-  return [...moved.values(), ...redrawArrowsTouching(scene, moved)];
+  const changed = new Map(moved);
+  for (const element of redrawArrowsTouching(scene, moved)) changed.set(element.id, element);
+  for (const element of refitFrames(scene, moved)) changed.set(element.id, element);
+  return [...changed.values()];
 }
 var alignments = {
   "align-left": (box, bounds) => [bounds.x - box.x, 0],
@@ -3416,14 +4195,14 @@ var alignments = {
   "align-center-h": (box, bounds) => [0, bounds.y + bounds.height / 2 - (box.y + box.height / 2)],
   "align-center-v": (box, bounds) => [bounds.x + bounds.width / 2 - (box.x + box.width / 2), 0]
 };
-function distribute(boxes, spacing, axis) {
-  const size = axis === "x" ? "width" : "height";
-  const order = boxes.map((box, i) => ({ box, i })).sort((a, b) => a.box[axis] - b.box[axis]);
+function distribute(boxes, spacing, axis2) {
+  const size = axis2 === "x" ? "width" : "height";
+  const order = boxes.map((box, i) => ({ box, i })).sort((a, b) => a.box[axis2] - b.box[axis2]);
   const deltas = boxes.map(() => [0, 0]);
-  let cursor = order[0]?.box[axis] ?? 0;
+  let cursor = order[0]?.box[axis2] ?? 0;
   for (const { box, i } of order) {
-    const delta = cursor - box[axis];
-    deltas[i] = axis === "x" ? [delta, 0] : [0, delta];
+    const delta = cursor - box[axis2];
+    deltas[i] = axis2 === "x" ? [delta, 0] : [0, delta];
     cursor += box[size] + spacing;
   }
   return deltas;
@@ -3439,10 +4218,10 @@ function grid(boxes, options) {
     return [anchor.x + column * cellW - box.x, anchor.y + rowIndex * cellH - box.y];
   });
 }
-function flip(boxes, axis) {
+function flip(boxes, axis2) {
   const bounds = boundsOfAll(boxes);
   return boxes.map((box) => {
-    if (axis === "x") {
+    if (axis2 === "x") {
       const mirrored2 = bounds.x + bounds.width - (box.x - bounds.x) - box.width;
       return [mirrored2 - box.x, 0];
     }
@@ -3503,6 +4282,12 @@ function arrangeGeometry(input) {
   if (input.op === "layout-layered") {
     return ok({ moved: layoutLayered(input.scene, targets, input.spacing) });
   }
+  if (input.op === "layout-radial") {
+    return ok({ moved: layoutRadial(input.scene, targets, input.spacing) });
+  }
+  if (input.op === "layout-tree") {
+    return ok({ moved: layoutTree(input.scene, targets, input.spacing) });
+  }
   const boxes = targets.map(boxOf);
   const spacing = input.spacing ?? HOUSE.spacing.h;
   const columns = input.columns ?? Math.ceil(Math.sqrt(targets.length));
@@ -3534,6 +4319,44 @@ function arrangeGeometry(input) {
   });
   return ok({ moved: translate(input.scene, byDelta) });
 }
+function backEdgeIndices(nodeIds, edges) {
+  const outgoing = /* @__PURE__ */ new Map();
+  for (const id of nodeIds) outgoing.set(id, []);
+  edges.forEach((edge, index) => {
+    outgoing.get(edge.from)?.push(index);
+  });
+  const ON_STACK = 1;
+  const DONE = 2;
+  const state = /* @__PURE__ */ new Map();
+  const back = /* @__PURE__ */ new Set();
+  for (const root of [...nodeIds].sort()) {
+    if (state.has(root)) continue;
+    state.set(root, ON_STACK);
+    const stack = [{ node: root, cursor: 0 }];
+    while (stack.length > 0) {
+      const frame = stack[stack.length - 1];
+      if (frame === void 0) break;
+      const fanOut = outgoing.get(frame.node) ?? [];
+      if (frame.cursor >= fanOut.length) {
+        state.set(frame.node, DONE);
+        stack.pop();
+        continue;
+      }
+      const index = fanOut[frame.cursor];
+      frame.cursor += 1;
+      if (index === void 0) continue;
+      const head = edges[index]?.to;
+      if (head === void 0) continue;
+      const seen = state.get(head);
+      if (seen === ON_STACK) back.add(index);
+      else if (seen === void 0) {
+        state.set(head, ON_STACK);
+        stack.push({ node: head, cursor: 0 });
+      }
+    }
+  }
+  return back;
+}
 function layoutLayered(scene, targets, spacing) {
   const inSet = new Set(targets.map((element) => element.id));
   const edges = [];
@@ -3545,22 +4368,20 @@ function layoutLayered(scene, targets, spacing) {
     if (!inSet.has(from) || !inSet.has(to) || from === to) continue;
     edges.push({ from, to });
   }
-  const nodes = targets.filter((element) => !isLinear(element));
+  const nodes = targets.filter((element) => !isLinear(element) && !isAnchored(element));
   if (nodes.length === 0) return [];
+  const back = backEdgeIndices(
+    nodes.map((node) => node.id),
+    edges
+  );
+  const forward = edges.filter((_, index) => !back.has(index));
   const incoming = /* @__PURE__ */ new Map();
-  const outgoing = /* @__PURE__ */ new Map();
-  for (const node of nodes) {
-    incoming.set(node.id, []);
-    outgoing.set(node.id, []);
-  }
-  for (const edge of edges) {
-    incoming.get(edge.to)?.push(edge.from);
-    outgoing.get(edge.from)?.push(edge.to);
-  }
+  for (const node of nodes) incoming.set(node.id, []);
+  for (const edge of forward) incoming.get(edge.to)?.push(edge.from);
   const rank = new Map(nodes.map((node) => [node.id, 0]));
   for (let pass = 0; pass < nodes.length; pass++) {
     let settled = true;
-    for (const edge of edges) {
+    for (const edge of forward) {
       const from = rank.get(edge.from) ?? 0;
       const to = rank.get(edge.to) ?? 0;
       if (to < from + 1) {
@@ -3570,60 +4391,361 @@ function layoutLayered(scene, targets, spacing) {
     }
     if (settled) break;
   }
-  const ranks = /* @__PURE__ */ new Map();
+  const LANE_WIDTH = 0;
+  const LANE_HEIGHT = 48;
+  const slots = /* @__PURE__ */ new Map();
+  const push = (r, slot) => {
+    const bucket = slots.get(r);
+    if (bucket === void 0) slots.set(r, [slot]);
+    else bucket.push(slot);
+  };
   for (const node of nodes) {
-    const r = rank.get(node.id) ?? 0;
-    const bucket = ranks.get(r);
-    if (bucket === void 0) ranks.set(r, [node]);
-    else bucket.push(node);
+    push(rank.get(node.id) ?? 0, {
+      key: node.id,
+      box: boxOf(node),
+      parents: incoming.get(node.id) ?? [],
+      node
+    });
   }
-  const position = /* @__PURE__ */ new Map();
-  const rankNumbers = [...ranks.keys()].sort((a, b) => a - b);
+  for (const edge of edges) {
+    const from = rank.get(edge.from);
+    const to = rank.get(edge.to);
+    if (from === void 0 || to === void 0) continue;
+    let previous = edge.from;
+    for (let r = Math.min(from, to) + 1; r < Math.max(from, to); r++) {
+      const key = `lane:${edge.from}>${edge.to}@${r}`;
+      push(r, {
+        key,
+        box: { x: 0, y: 0, width: LANE_WIDTH, height: LANE_HEIGHT },
+        parents: [previous]
+      });
+      previous = key;
+    }
+  }
+  const rankNumbers = [...slots.keys()].sort((a, b) => a - b);
+  const childrenOf2 = /* @__PURE__ */ new Map();
   for (const r of rankNumbers) {
-    const bucket = ranks.get(r) ?? [];
-    const scored = bucket.map((node) => {
-      const parents = (incoming.get(node.id) ?? []).map((id) => position.get(id)).filter((p) => p !== void 0);
-      const barycentre = parents.length === 0 ? Number.POSITIVE_INFINITY : parents.reduce((sum, p) => sum + p, 0) / parents.length;
-      return { node, barycentre };
-    });
-    scored.sort(
-      (a, b) => a.barycentre - b.barycentre || (a.node.id < b.node.id ? -1 : a.node.id > b.node.id ? 1 : 0)
-    );
-    scored.forEach(({ node }, i) => {
-      position.set(node.id, i);
-    });
-    ranks.set(
-      r,
-      scored.map((entry) => entry.node)
-    );
+    for (const slot of slots.get(r) ?? []) {
+      for (const parent of slot.parents) {
+        const kids = childrenOf2.get(parent);
+        if (kids === void 0) childrenOf2.set(parent, [slot.key]);
+        else kids.push(slot.key);
+      }
+    }
   }
-  const gapH = spacing ?? HOUSE.spacing.h;
+  const indicesOf = (ordering) => {
+    const at = /* @__PURE__ */ new Map();
+    for (const bucket of ordering.values()) {
+      bucket.forEach((slot, i) => {
+        at.set(slot.key, i);
+      });
+    }
+    return at;
+  };
+  const crossings = (ordering) => {
+    const at = indicesOf(ordering);
+    let total = 0;
+    for (const r of rankNumbers) {
+      const pairs = [];
+      for (const slot of ordering.get(r) ?? []) {
+        const below = at.get(slot.key);
+        if (below === void 0) continue;
+        for (const parent of slot.parents) {
+          const above = at.get(parent);
+          if (above !== void 0) pairs.push([above, below]);
+        }
+      }
+      for (let i = 0; i < pairs.length; i++) {
+        for (let j = i + 1; j < pairs.length; j++) {
+          const a = pairs[i];
+          const b = pairs[j];
+          if (a === void 0 || b === void 0) continue;
+          if ((a[0] - b[0]) * (a[1] - b[1]) < 0) total += 1;
+        }
+      }
+    }
+    return total;
+  };
+  const sweep = (ordering, direction) => {
+    const at = indicesOf(ordering);
+    const next = /* @__PURE__ */ new Map();
+    const order = direction === "down" ? rankNumbers : [...rankNumbers].reverse();
+    for (const r of order) {
+      const scored = (ordering.get(r) ?? []).map((slot) => {
+        const adjacent = direction === "down" ? slot.parents : childrenOf2.get(slot.key) ?? [];
+        const known = adjacent.map((key) => at.get(key)).filter((index) => index !== void 0);
+        return {
+          slot,
+          barycentre: known.length === 0 ? Number.POSITIVE_INFINITY : known.reduce((sum, index) => sum + index, 0) / known.length
+        };
+      });
+      scored.sort(
+        (a, b) => a.barycentre - b.barycentre || (a.slot.key < b.slot.key ? -1 : a.slot.key > b.slot.key ? 1 : 0)
+      );
+      const settled = scored.map((entry) => entry.slot);
+      settled.forEach((slot, i) => {
+        at.set(slot.key, i);
+      });
+      next.set(r, settled);
+    }
+    return next;
+  };
+  const SWEEPS = 4;
+  let current = new Map(rankNumbers.map((r) => [r, [...slots.get(r) ?? []]]));
+  let best = current;
+  let fewest = Number.POSITIVE_INFINITY;
+  for (let round = 0; round < SWEEPS; round++) {
+    current = sweep(current, round % 2 === 0 ? "down" : "up");
+    const score = crossings(current);
+    if (score < fewest) {
+      fewest = score;
+      best = current;
+    }
+  }
+  for (const r of rankNumbers) slots.set(r, [...best.get(r) ?? []]);
   const gapV = HOUSE.spacing.v;
+  const labelWidths = labelsByContainer(scene);
+  const captionRoom = (column) => {
+    const floor = spacing ?? HOUSE.spacing.h;
+    let widest = 0;
+    for (const edge of edges) {
+      const from = rank.get(edge.from);
+      const to = rank.get(edge.to);
+      if (from === void 0 || to === void 0) continue;
+      const low = Math.min(from, to);
+      const high = Math.max(from, to);
+      if (column < low || column >= high) continue;
+      const arrow = scene.find(
+        (element) => element.type === "arrow" && startOf(element) === edge.from && endOf(element) === edge.to
+      );
+      const caption = arrow === void 0 ? void 0 : labelWidths.get(arrow.id);
+      if (caption !== void 0) widest = Math.max(widest, caption.width);
+    }
+    return Math.max(floor, widest + HOUSE.sizes.labelPadX * 2);
+  };
   const anchor = boundsOfAll(nodes.map(boxOf));
   const columnWidths = rankNumbers.map(
-    (r) => Math.max(...(ranks.get(r) ?? []).map((node) => node.width))
+    (r) => Math.max(...(slots.get(r) ?? []).map((slot) => slot.box.width))
   );
   const tallest = Math.max(
     ...rankNumbers.map(
-      (r) => (ranks.get(r) ?? []).reduce((sum, node) => sum + node.height + gapV, -gapV)
+      (r) => (slots.get(r) ?? []).reduce((sum, slot) => sum + slot.box.height + gapV, -gapV)
     )
   );
   const deltas = /* @__PURE__ */ new Map();
   let cursorX = anchor.x;
   rankNumbers.forEach((r, column) => {
-    const bucket = ranks.get(r) ?? [];
-    const columnHeight = bucket.reduce((sum, node) => sum + node.height + gapV, -gapV);
+    const bucket = slots.get(r) ?? [];
+    const columnHeight = bucket.reduce((sum, slot) => sum + slot.box.height + gapV, -gapV);
     let cursorY = anchor.y + (tallest - columnHeight) / 2;
     const width = columnWidths[column] ?? 0;
-    for (const node of bucket) {
-      const x = cursorX + (width - node.width) / 2;
-      deltas.set(node.id, [x - node.x, cursorY - node.y]);
-      cursorY += node.height + gapV;
+    for (const slot of bucket) {
+      if (slot.node !== void 0) {
+        const x = cursorX + (width - slot.box.width) / 2;
+        deltas.set(slot.node.id, [x - slot.box.x, cursorY - slot.box.y]);
+      }
+      cursorY += slot.box.height + gapV;
     }
-    cursorX += width + gapH;
+    cursorX += width + captionRoom(r);
   });
   return translate(scene, deltas);
 }
+var TAU = Math.PI * 2;
+var normalizeAngle = (radians) => (radians % TAU + TAU) % TAU;
+function meanAngle(angles) {
+  let x = 0;
+  let y = 0;
+  for (const angle of angles) {
+    x += Math.cos(angle);
+    y += Math.sin(angle);
+  }
+  return Math.atan2(y, x);
+}
+var ringExtent = (element) => Math.max(element.width, element.height);
+function adjacency(scene, nodes) {
+  const inSet = new Set(nodes.map((node) => node.id));
+  const neighbours = /* @__PURE__ */ new Map();
+  for (const node of nodes) neighbours.set(node.id, /* @__PURE__ */ new Set());
+  for (const element of scene) {
+    if (element.type !== "arrow") continue;
+    const from = startOf(element);
+    const to = endOf(element);
+    if (from === null || to === null || from === to) continue;
+    if (!inSet.has(from) || !inSet.has(to)) continue;
+    neighbours.get(from)?.add(to);
+    neighbours.get(to)?.add(from);
+  }
+  return neighbours;
+}
+function pickHub(neighbours, ordered) {
+  const first = ordered[0];
+  if (first === void 0) return void 0;
+  const degree = (element) => neighbours.get(element.id)?.size ?? 0;
+  let hub = first;
+  for (const node of ordered) if (degree(node) > degree(hub)) hub = node;
+  return hub;
+}
+function layoutRadial(scene, targets, spacing) {
+  const nodes = targets.filter((element) => !isLinear(element) && !isAnchored(element));
+  const ordered = [...nodes].sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+  const neighbours = adjacency(scene, nodes);
+  const hub = pickHub(neighbours, ordered);
+  if (hub === void 0) return [];
+  const byId = new Map(nodes.map((node) => [node.id, node]));
+  const gap = spacing ?? HOUSE.spacing.h;
+  const ringOf = /* @__PURE__ */ new Map([[hub.id, 0]]);
+  const parentsOf = /* @__PURE__ */ new Map();
+  let frontier = [hub.id];
+  let depth = 0;
+  while (frontier.length > 0) {
+    depth += 1;
+    const discovered = /* @__PURE__ */ new Map();
+    for (const id of frontier) {
+      for (const other of [...neighbours.get(id) ?? []].sort()) {
+        if (ringOf.has(other)) continue;
+        const found = discovered.get(other);
+        if (found === void 0) discovered.set(other, [id]);
+        else found.push(id);
+      }
+    }
+    for (const [child, parents] of discovered) {
+      ringOf.set(child, depth);
+      parentsOf.set(child, parents);
+    }
+    frontier = [...discovered.keys()];
+  }
+  for (const node of ordered) {
+    if (!ringOf.has(node.id)) ringOf.set(node.id, depth + 1);
+  }
+  const rings = /* @__PURE__ */ new Map();
+  for (const node of ordered) {
+    const ring = ringOf.get(node.id) ?? 0;
+    const bucket = rings.get(ring);
+    if (bucket === void 0) rings.set(ring, [node.id]);
+    else bucket.push(node.id);
+  }
+  const [cx, cy] = centre(boundsOfAll(nodes.map(boxOf)));
+  const deltas = /* @__PURE__ */ new Map();
+  deltas.set(hub.id, [cx - (hub.x + hub.width / 2), cy - (hub.y + hub.height / 2)]);
+  const angleOf = /* @__PURE__ */ new Map([[hub.id, 0]]);
+  let cleared = ringExtent(hub) / 2;
+  for (const ring of [...rings.keys()].filter((r) => r > 0).sort((a, b) => a - b)) {
+    const members = rings.get(ring) ?? [];
+    if (members.length === 0) continue;
+    const scored = members.map((id) => {
+      const known = (parentsOf.get(id) ?? []).map((parent) => angleOf.get(parent)).filter((angle) => angle !== void 0);
+      return {
+        id,
+        at: known.length === 0 ? Number.POSITIVE_INFINITY : normalizeAngle(meanAngle(known))
+      };
+    });
+    scored.sort((a, b) => a.at - b.at || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    const extents = members.map((id) => {
+      const node = byId.get(id);
+      return node === void 0 ? 0 : ringExtent(node);
+    });
+    const widest = Math.max(...extents);
+    const seating = extents.reduce((sum, extent) => sum + extent + gap, 0) / TAU;
+    const radius = Math.max(seating, cleared + widest / 2 + gap);
+    scored.forEach(({ id }, i) => {
+      const theta = -Math.PI / 2 + TAU * i / members.length;
+      angleOf.set(id, normalizeAngle(theta));
+      const node = byId.get(id);
+      if (node === void 0) return;
+      deltas.set(id, [
+        cx + radius * Math.cos(theta) - node.width / 2 - node.x,
+        cy + radius * Math.sin(theta) - node.height / 2 - node.y
+      ]);
+    });
+    cleared = radius + widest / 2;
+  }
+  return translate(scene, deltas);
+}
+function layoutTree(scene, targets, spacing) {
+  const nodes = targets.filter((element) => !isLinear(element) && !isAnchored(element));
+  const ordered = [...nodes].sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+  const neighbours = adjacency(scene, nodes);
+  const root = pickHub(neighbours, ordered);
+  if (root === void 0) return [];
+  const byId = new Map(nodes.map((node) => [node.id, node]));
+  const gapH = spacing ?? HOUSE.spacing.h;
+  const gapV = HOUSE.spacing.v;
+  const depthOf = /* @__PURE__ */ new Map([[root.id, 0]]);
+  const childrenOf2 = /* @__PURE__ */ new Map();
+  const order = [];
+  const stack = [root.id];
+  const seen = /* @__PURE__ */ new Set([root.id]);
+  while (stack.length > 0) {
+    const id = stack.pop();
+    if (id === void 0) continue;
+    order.push(id);
+    const kids = [];
+    const adjacent = [...neighbours.get(id) ?? []].sort();
+    for (const other of adjacent) {
+      if (seen.has(other)) continue;
+      seen.add(other);
+      depthOf.set(other, (depthOf.get(id) ?? 0) + 1);
+      kids.push(other);
+    }
+    childrenOf2.set(id, kids);
+    for (let i = kids.length - 1; i >= 0; i--) {
+      const kid = kids[i];
+      if (kid !== void 0) stack.push(kid);
+    }
+  }
+  for (const node of ordered) {
+    if (seen.has(node.id)) continue;
+    seen.add(node.id);
+    depthOf.set(node.id, 1);
+    order.push(node.id);
+  }
+  const columns = /* @__PURE__ */ new Map();
+  for (const id of order) {
+    const d = depthOf.get(id) ?? 0;
+    const bucket = columns.get(d);
+    if (bucket === void 0) columns.set(d, [id]);
+    else bucket.push(id);
+  }
+  const captions = labelsByContainer(scene);
+  const crossing = /* @__PURE__ */ new Map();
+  for (const element of scene) {
+    if (element.type !== "arrow") continue;
+    const from = startOf(element);
+    const to = endOf(element);
+    if (from === null || to === null) continue;
+    const a = depthOf.get(from);
+    const b = depthOf.get(to);
+    if (a === void 0 || b === void 0 || a === b) continue;
+    const caption = captions.get(element.id);
+    if (caption === void 0) continue;
+    const gap = Math.min(a, b);
+    crossing.set(gap, Math.max(crossing.get(gap) ?? 0, caption.width));
+  }
+  const anchor = boundsOfAll(nodes.map(boxOf));
+  const depths = [...columns.keys()].sort((a, b) => a - b);
+  const columnX = /* @__PURE__ */ new Map();
+  let cursorX = anchor.x;
+  for (const d of depths) {
+    columnX.set(d, cursorX);
+    const widest = Math.max(...(columns.get(d) ?? []).map((id) => byId.get(id)?.width ?? 0));
+    const caption = crossing.get(d) ?? 0;
+    cursorX += widest + Math.max(gapH, caption === 0 ? 0 : caption + HOUSE.sizes.labelPadX * 2);
+  }
+  const columnHeight = (d) => (columns.get(d) ?? []).reduce((sum, id) => sum + (byId.get(id)?.height ?? 0) + gapV, -gapV);
+  const tallest = Math.max(...depths.map(columnHeight));
+  const deltas = /* @__PURE__ */ new Map();
+  for (const d of depths) {
+    let cursorY = anchor.y + (tallest - columnHeight(d)) / 2;
+    for (const id of columns.get(d) ?? []) {
+      const node = byId.get(id);
+      if (node === void 0) continue;
+      const x = columnX.get(d) ?? anchor.x;
+      deltas.set(id, [x - node.x, cursorY - node.y]);
+      cursorY += node.height + gapV;
+    }
+  }
+  return translate(scene, deltas);
+}
 
 // src/app/usecases/write/arrange-elements.ts
 function arrangeElements(deps) {
@@ -3644,6 +4766,7 @@ function arrangeElements(deps) {
       sceneId: applied.value.sceneId,
       sceneVersion: applied.value.sceneVersion,
       broadcastTo: applied.value.broadcastTo,
+      overlapWarning: applied.value.overlapWarning,
       moved: [...applied.value.applied]
     });
   };
@@ -3798,82 +4921,6 @@ function createDebugElement(deps) {
   };
 }
 
-// src/domain/scene/skeleton.ts
-var isContainer = (type) => type === "rectangle" || type === "diamond" || type === "ellipse";
-function explicit(input) {
-  const kept = {};
-  for (const [key, value] of Object.entries(input)) {
-    if (value === void 0) continue;
-    if (key === "type" || key === "id" || key === "role" || key === "label") continue;
-    kept[key] = value;
-  }
-  return kept;
-}
-var defaultSize = () => serviceSize();
-function normalizeElements(input) {
-  return input.elements.map((element, i) => {
-    const fallback = input.ids[i];
-    if (fallback === void 0) {
-      throw new Error(`normalizeElements needs one id per element: none at position ${i}`);
-    }
-    const id = element.id ?? fallback;
-    const role = styleForRole(element.role ?? "compute");
-    const set = explicit(element);
-    if (element.type === "text") {
-      const text = element.text ?? element.label ?? "";
-      const skeleton2 = {
-        type: "text",
-        id,
-        x: element.x,
-        y: element.y,
-        fontSize: HOUSE.fontSize,
-        fontFamily: HOUSE.fontFamily,
-        // A free-standing note is not a service box: it takes the role's ink but never
-        // its fill, because a filled rectangle behind a caption reads as a shape.
-        strokeColor: role.strokeColor,
-        ...set,
-        text
-      };
-      return skeleton2;
-    }
-    if (element.type === "line") {
-      const skeleton2 = {
-        type: "line",
-        id,
-        x: element.x,
-        y: element.y,
-        strokeColor: role.strokeColor,
-        strokeWidth: HOUSE.strokeWidth,
-        roughness: HOUSE.roughness,
-        ...set,
-        ...element.label === void 0 ? {} : { label: houseLabel(element.label) }
-      };
-      return skeleton2;
-    }
-    if (!isContainer(element.type)) {
-      throw new Error(`normalizeElements cannot build a ${element.type}`);
-    }
-    const skeleton = {
-      type: element.type,
-      id,
-      x: element.x,
-      y: element.y,
-      ...defaultSize(),
-      ...role,
-      ...set,
-      ...element.label === void 0 ? {} : { label: houseLabel(element.label) }
-    };
-    return skeleton;
-  });
-}
-var LAYOUT_HINT_THRESHOLD = 4;
-function layoutHint(elements) {
-  if (elements.length < LAYOUT_HINT_THRESHOLD) return null;
-  const positions = new Set(elements.map((element) => `${element.x},${element.y}`));
-  if (positions.size > 2) return null;
-  return `${elements.length} elements with no explicit layout \u2014 chalk_arrange(op: "layout-layered") will place them`;
-}
-
 // src/app/usecases/write/create-elements.ts
 function createElements(deps) {
   return async (input) => {
@@ -3901,20 +4948,6 @@ function createElements(deps) {
 }
 
 // src/app/usecases/write/frame-elements.ts
-function boundsAround(children) {
-  const pad2 = HOUSE.sizes.framePad;
-  const left = Math.min(...children.map((c) => c.x));
-  const top = Math.min(...children.map((c) => c.y));
-  const right = Math.max(...children.map((c) => c.x + c.width));
-  const bottom = Math.max(...children.map((c) => c.y + c.height));
-  return {
-    x: left - pad2,
-    y: top - pad2,
-    width: right - left + pad2 * 2,
-    // Room at the top for the frame's own name, which renders above its border.
-    height: bottom - top + pad2 * 2
-  };
-}
 function frameElements(deps) {
   return async (input) => {
     const scene = deps.write.resolve(input.sceneId);
@@ -3943,6 +4976,18 @@ function frameElements(deps) {
       if (!created.ok) return created;
       const committed = deps.write.append(scene.value, created.value);
       if (!committed.ok) return committed;
+      const after = deps.write.resolve(input.sceneId);
+      if (after.ok) {
+        const built = after.value.elements.find((element) => element.id === elementId);
+        if (built !== void 0) {
+          const released = releaseCrossingArrows(after.value.elements, built);
+          if (released.length > 0) {
+            const freed = deps.write.apply(after.value, released);
+            if (!freed.ok) return freed;
+            return ok({ ...freed.value, frameId, children: named2.map((e) => e.id) });
+          }
+        }
+      }
       return ok({ ...committed.value, frameId, children: named2.map((e) => e.id) });
     }
     if (input.frameId === void 0) {
@@ -3960,12 +5005,14 @@ function frameElements(deps) {
     if (members.length > 0) {
       changed.push({ ...frame, ...boundsAround(members) });
     }
+    changed.push(...releaseCrossingArrows([...scene.value.elements, ...changed], frame));
     const applied = deps.write.apply(scene.value, changed);
     if (!applied.ok) return applied;
     return ok({
       sceneId: applied.value.sceneId,
       sceneVersion: applied.value.sceneVersion,
       broadcastTo: applied.value.broadcastTo,
+      overlapWarning: applied.value.overlapWarning,
       frameId: input.frameId,
       children: members.map((element) => element.id)
     });
@@ -3991,6 +5038,7 @@ function groupElements(deps) {
       sceneId: applied.value.sceneId,
       sceneVersion: applied.value.sceneVersion,
       broadcastTo: applied.value.broadcastTo,
+      overlapWarning: applied.value.overlapWarning,
       groupId,
       grouped: applied.value.applied
     });
@@ -4011,6 +5059,7 @@ function ungroupElements(deps) {
       sceneId: applied.value.sceneId,
       sceneVersion: applied.value.sceneVersion,
       broadcastTo: applied.value.broadcastTo,
+      overlapWarning: applied.value.overlapWarning,
       ungrouped: applied.value.applied
     });
   };
@@ -4026,6 +5075,29 @@ var iconBox = (art, size) => {
   };
 };
 var svgDataUrl = (svg) => DataUrl.parse(`data:image/svg+xml;base64,${Buffer.from(svg, "utf8").toString("base64")}`);
+function placementOf(elements, input, box) {
+  if (input.attachTo !== void 0) {
+    const anchor = elements.find((element) => element.id === input.attachTo && !element.isDeleted);
+    if (anchor === void 0) return fail(unknownElement(input.attachTo));
+    const sides = input.placement !== void 0 ? [input.placement] : ["above", "below", "right", "left"];
+    const ignore = /* @__PURE__ */ new Set([anchor.id]);
+    for (const side of sides) {
+      const at = anchoredPosition(anchor, box, side);
+      const candidate = { ...at, width: box.width, height: box.height };
+      if (sides.length === 1 || !wouldCollide(candidate, elements, ignore)) {
+        return ok({ ...at, anchorIds: [anchor.id] });
+      }
+    }
+    return ok({
+      ...anchoredPosition(anchor, box, "above"),
+      anchorIds: [anchor.id]
+    });
+  }
+  if (input.x === void 0 || input.y === void 0) {
+    return fail(iconNeedsAPlace(input.iconId));
+  }
+  return ok({ x: input.x, y: input.y, anchorIds: null });
+}
 function placeIcon(deps) {
   return async (input) => {
     const opened = await deps.icons();
@@ -4044,12 +5116,21 @@ function placeIcon(deps) {
     if (!resolved.ok) return resolved;
     const scene = resolved.value;
     const size = input.size ?? HOUSE.sizes.icon;
-    const chalk = { author: "claude", kind: "icon", iconId: icon.id };
+    const box = icon.art.kind === "elements" ? { width: size, height: size } : iconBox(icon.art, size);
+    const spot = placementOf(scene.elements, input, box);
+    if (!spot.ok) return spot;
+    const { x, y, anchorIds } = spot.value;
+    const chalk = {
+      author: "claude",
+      kind: "icon",
+      iconId: icon.id,
+      ...anchorIds === null ? {} : { anchorIds }
+    };
     if (icon.art.kind === "elements") {
       const ids = deps.idGen.elementIds(icon.art.elements.length);
       const placed = deps.placer.place({
         elements: icon.art.elements,
-        at: { x: input.x, y: input.y },
+        at: { x, y },
         ids
       });
       const stamped = placed.map(
@@ -4066,7 +5147,6 @@ function placeIcon(deps) {
         iconId: icon.id
       });
     }
-    const box = iconBox(icon.art, size);
     const fileId = FileId.parse(deps.idGen.token());
     const file = {
       id: fileId,
@@ -4079,8 +5159,8 @@ function placeIcon(deps) {
       {
         type: "image",
         id: elementId,
-        x: input.x,
-        y: input.y,
+        x,
+        y,
         width: box.width,
         height: box.height,
         fileId,
@@ -4092,14 +5172,22 @@ function placeIcon(deps) {
       skeletons.push({
         type: "text",
         id: labelId,
-        x: input.x,
-        y: input.y + box.height + 8,
+        ...captionBelow({ x, y }, box),
         text: input.label,
         width: box.width,
         fontSize: HOUSE.fontSize,
         fontFamily: HOUSE.fontFamily,
         textAlign: "center",
-        customData: { chalk: { author: "claude", kind: "note", iconId: icon.id } }
+        // The caption carries the anchor too, or the glyph travels with its box and the
+        // word it is captioned with stays behind.
+        customData: {
+          chalk: {
+            author: "claude",
+            kind: "note",
+            iconId: icon.id,
+            ...anchorIds === null ? {} : { anchorIds }
+          }
+        }
       });
     }
     const expanded = await deps.write.create(scene, skeletons);
@@ -4185,7 +5273,10 @@ function writeContext(deps) {
       return ok({
         sceneId: scene.id,
         sceneVersion: updated.sceneVersion,
-        broadcastTo: broadcast(scene, updated.sceneVersion, pushed, patch?.files)
+        broadcastTo: broadcast(scene, updated.sceneVersion, pushed, patch?.files),
+        // The scene as it now stands, not the batch: a new box buries whatever was
+        // already underneath it, and the batch alone cannot see that.
+        overlapWarning: overlapWarning([...kept, ...expansion.created])
       });
     },
     apply(scene, changed, options) {
@@ -4195,7 +5286,10 @@ function writeContext(deps) {
           sceneVersion: scene.sceneVersion,
           broadcastTo: 0,
           applied: [],
-          rejected: []
+          rejected: [],
+          // Nothing was written, so nothing was made worse. Staying quiet here keeps the
+          // warning meaning "your write did this".
+          overlapWarning: null
         });
       }
       deps.markPresence("writing");
@@ -4224,7 +5318,8 @@ function writeContext(deps) {
           sceneVersion: scene.sceneVersion,
           broadcastTo: 0,
           applied: [...merged.applied],
-          rejected
+          rejected,
+          overlapWarning: null
         });
       }
       const updated = deps.commit(scene.id, merged.elements);
@@ -4236,7 +5331,8 @@ function writeContext(deps) {
         sceneVersion: updated.sceneVersion,
         broadcastTo: broadcast(scene, updated.sceneVersion, pushed),
         applied: [...merged.applied],
-        rejected
+        rejected,
+        overlapWarning: overlapWarning(merged.elements)
       });
     }
   };
@@ -4326,6 +5422,24 @@ function rawElements(deps) {
   };
 }
 
+// src/domain/scene/captions.ts
+function fitCaption(container, caption) {
+  if (caption.type !== "text") return caption;
+  const source = caption.originalText === "" ? caption.text : caption.originalText;
+  const inner = Math.max(1, container.width - HOUSE.sizes.labelPadX * 2);
+  const lines = wrapLines(source, caption.fontSize, inner);
+  const width = Math.max(...lines.map((line) => measureLine(line, caption.fontSize)));
+  const height = lines.length * caption.fontSize * caption.lineHeight;
+  return {
+    ...caption,
+    text: lines.join("\n"),
+    width,
+    height,
+    x: container.x + (container.width - width) / 2,
+    y: container.y + (container.height - height) / 2
+  };
+}
+
 // src/app/usecases/write/update-elements.ts
 var missing = (id) => toRejection(id, unknownElement(id));
 var onlyRequested = (landed, requested) => {
@@ -4378,17 +5492,37 @@ function updateElements(deps) {
       }
     }
     if (moved.size > 0) {
+      const deltas = /* @__PURE__ */ new Map();
+      for (const [id, next] of moved) {
+        const before = byId.get(id);
+        if (before !== void 0) deltas.set(id, [next.x - before.x, next.y - before.y]);
+      }
+      for (const [id, [dx, dy]] of withAnchoredElements(scene.value.elements, deltas)) {
+        if (deltas.has(id) || dx === 0 && dy === 0) continue;
+        const element = byId.get(id);
+        if (element === void 0) continue;
+        const followed = { ...element, x: element.x + dx, y: element.y + dy };
+        moved.set(id, followed);
+        knockOn.push(followed);
+      }
       for (const [id, next] of moved) {
         const before = byId.get(id);
         const caption = captionOf(scene.value.elements, id);
         if (before === void 0 || caption === void 0) continue;
-        knockOn.push({
-          ...caption,
-          x: caption.x + (next.x - before.x),
-          y: caption.y + (next.y - before.y)
-        });
+        const resized = next.width !== before.width || next.height !== before.height;
+        knockOn.push(
+          resized ? fitCaption(next, caption) : {
+            ...caption,
+            x: caption.x + (next.x - before.x),
+            y: caption.y + (next.y - before.y)
+          }
+        );
       }
       knockOn.push(...redrawArrowsTouching(scene.value.elements, moved));
+      const patched = new Set(changed.map((element) => element.id));
+      knockOn.push(
+        ...refitFrames(scene.value.elements, moved).filter((frame) => !patched.has(frame.id))
+      );
     }
     for (const element of knockOn) {
       const before = byId.get(element.id);
@@ -4402,6 +5536,7 @@ function updateElements(deps) {
       sceneId: applied.value.sceneId,
       sceneVersion: applied.value.sceneVersion,
       broadcastTo: applied.value.broadcastTo,
+      overlapWarning: applied.value.overlapWarning,
       // What the caller asked for, not everything that moved. A caption that followed its
       // box and an arrow that was redrawn are consequences; listing them would turn this
       // into "every element that changed" and leave the caller working out which of them
@@ -4455,6 +5590,7 @@ function deleteElements(deps) {
       sceneId: applied.value.sceneId,
       sceneVersion: applied.value.sceneVersion,
       broadcastTo: applied.value.broadcastTo,
+      overlapWarning: applied.value.overlapWarning,
       deleted: onlyRequested(
         applied.value.applied,
         input.deletions.map((deletion) => deletion.id)
@@ -4509,7 +5645,7 @@ function readEnv(source) {
 }
 
 // src/composition/container.ts
-var PACKAGE_VERSION = "1.0.4";
+var PACKAGE_VERSION = "1.1.1";
 function readRuntime() {
   return {
     env: process.env,
@@ -5117,8 +6253,26 @@ function renderScene(description) {
   }
   lines.push("elements:");
   for (const element of description.elements) lines.push(row(element, true));
+  lines.push(...adviceLines(description));
+  lines.push(...overlapLines(description));
   return lines.join("\n");
 }
+function adviceLines(description) {
+  return description.layoutAdvice === null ? [] : [`layout: ${description.layoutAdvice}`];
+}
+function overlapLines(description) {
+  if (description.overlapCount === 0) return [];
+  const shown = description.overlaps.length;
+  const header = shown === description.overlapCount ? `overlaps: ${description.overlapCount}` : `overlaps: ${description.overlapCount} (worst ${shown} shown)`;
+  return [
+    header,
+    ...description.overlaps.map(
+      (overlap) => `! ${shortId2(overlap.a)} \xD7 ${shortId2(overlap.b)}  ${px(overlap.width)}x${px(
+        overlap.height
+      )}`
+    )
+  ];
+}
 var arrowGlyph = (label) => label === null ? "->" : `-"${label}"->`;
 var insideLine = (edge) => `  ${shortId2(edge.from)} ${arrowGlyph(edge.label)} ${shortId2(edge.to)}`;
 var named = (id, label) => label === null ? shortId2(id) : `${shortId2(id)} "${label}"`;
@@ -5235,7 +6389,7 @@ var searchIconsTool = {
 };
 var placeIconTool = {
   name: "chalk_place_icon",
-  description: "Put an icon from the catalog on the canvas, at an id from chalk_search_icons. Give it a `label` \u2014 an unlabelled icon says a thing was here and not which thing. The icon id is recorded on the element, so chalk_describe_scene reports it as [icon:aws/lambda] rather than [image] and you can reason about it later without looking at pixels. Position it roughly and let chalk_arrange tidy up, as with everything else.",
+  description: "Put an icon from the catalog on the canvas, at an id from chalk_search_icons. **Prefer `attachTo`** \u2014 the element the icon belongs to \u2014 over x/y: an attached icon travels with that element through every layout, while one at bare coordinates is near its box by coincidence and gets stranded the first time chalk_arrange runs. `placement` picks the side (above by default, or below/left/right/badge/inside). Give it a `label` unless it is attached to something already named \u2014 an unlabelled loose icon says a thing was here and not which thing. The icon id is recorded on the element, so chalk_describe_scene reports it as [icon:aws/lambda] rather than [image] and you can reason about it later without looking at pixels.",
   annotations: {
     title: "Place an icon",
     readOnlyHint: false,
@@ -5353,7 +6507,7 @@ var sceneSettingsTool = {
 // src/interfaces/mcp/tools/session.ts
 var screenshotTool = {
   name: "chalk_screenshot",
-  description: "Look at the canvas as an image. Use it when geometry matters and the description does not settle it \u2014 does this overlap, is that arrow crossing three boxes, does the layout read. Rendering happens in the user's browser, so the canvas has to be open; if no tab is connected the error says so. Prefer chalk_describe_scene for anything you can answer from structure: it is far smaller and it gives you ids you can act on.",
+  description: "Look at the canvas as an image. Use it for questions only a picture answers \u2014 does the diagram read, does it look deliberate, is the visual weight right. Do NOT use it to find collisions: chalk_describe_scene reports every overlap with ids and sizes, and every write tool warns when it buried something. Rendering happens in the user's browser, so the canvas has to be open; if no tab is connected the error says so. Prefer chalk_describe_scene for anything answerable from structure \u2014 it is far smaller and it gives you ids you can act on.",
   annotations: {
     title: "Screenshot the canvas",
     readOnlyHint: true,
@@ -5509,7 +6663,7 @@ var createElementsTool = proxyTool({
 var connectTool = proxyTool({
   name: "chalk_connect",
   title: "Connect two elements",
-  description: "Draw an arrow between two elements. This is the ONLY way to make one: it binds both ends, so the arrow follows its boxes when the user drags them \u2014 an arrow made from coordinates comes loose the first time anybody tidies the diagram. Label it with what actually moves ('embeddings', 'POST /ingest', 'nightly'); an unlabelled arrow only says 'related', which the reader already assumed.",
+  description: "Draw an arrow between two elements. This is the ONLY way to make one: it binds both ends, so the arrow follows its boxes when the user drags them \u2014 an arrow made from coordinates comes loose the first time anybody tidies the diagram. Label it with what actually moves ('embeddings', 'POST /ingest', 'nightly'); an unlabelled arrow only says 'related', which the reader already assumed. `arrowType` is the one option worth knowing by name: it defaults to `round`, and `elbow` gives right-angled routing that suits an architecture diagram far better \u2014 pick one and keep it consistent across the canvas. Ends and `strokeStyle` carry meaning too (`dashed` for async is the modifier a reader most often wants) \u2014 read chalk_read_me('arrows') before drawing a diagram\u2019s worth of them, or every edge comes out an identical straight solid line.",
   input: ConnectToolInput,
   output: ConnectOutput,
   call: (bridge) => bridge.connect
@@ -5535,7 +6689,7 @@ var deleteElementsTool = proxyTool({
 var arrangeTool = proxyTool({
   name: "chalk_arrange",
   title: "Arrange elements",
-  description: "Lay elements out. `layout-layered` is the one to reach for after drawing a graph: it ranks the boxes from the direction of the arrows between them and places them, which is far better than choosing twenty pairs of coordinates one at a time. The rest are tidying \u2014 align\xD76, distribute-h/v, grid, flip\xD72, and four z-order ops. Arrange only what you added; running a layout over a diagram the user has arranged will move their work.",
+  description: "Lay elements out. Three of these read the arrows as well as the boxes and they answer different questions \u2014 picking the wrong one destroys the structure the right one would show. `layout-layered` ranks by arrow direction: reach for it when the diagram is a flow. `layout-radial` puts the most-connected box at the centre with the rest ringed around it. `layout-tree` puts it on the LEFT and fans the rest out rightwards, which reads better than a ring whenever the labels are wide \u2014 a ring has to be big enough to seat its members, and a big ring crosses its own middle. **chalk_describe_scene ends with a `layout:` line naming which of the three this graph wants and why** \u2014 read it rather than guessing. The rest are tidying: align\xD76, distribute-h/v, grid, flip\xD72, and four z-order ops. Arrange only what you added; running a layout over a diagram the user has arranged will move their work.",
   input: ArrangeToolInput,
   output: ArrangeOutput,
   annotations: { idempotentHint: true },
@@ -5853,6 +7007,9 @@ var STATUS = {
   // Phase 5.
   CATALOG_UNAVAILABLE: 500,
   UNKNOWN_ICON: 404,
+  // 400: the icon exists and the request is malformed — it says nothing about where to
+  // put the thing.
+  ICON_NEEDS_A_PLACE: 400,
   UNKNOWN_PACK: 404,
   // 502, not 500: the failure is somebody else registry or somebody else archive, and
   // the distinction is what tells a user to check their network rather than file a bug.