chalkbridge 1.1.0 → 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, iconNeedsAPlace, DataUrl, Index, ROUNDNESS, STALE_SELECTION_MS, noScenes, ClientMessage, assertNever, PROTOCOL_VERSION, ApiError, EXCALIDRAW_FILE_VERSION, EXCALIDRAW_FILE_TYPE, point, FLAG_GLYPH, measureLine, wrapLines, KIND_ABBREVIATION, catalogUnavailable, FrameId, IconItem, ExcalidrawFile } from './chunk-XDK5UUTO.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';
@@ -2128,6 +2128,151 @@ function overlapWarning(elements) {
   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);
@@ -2245,6 +2390,12 @@ function observeScene(input) {
     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
   };
 }
@@ -3319,8 +3470,108 @@ function labelledSize(label, fontSize = HOUSE.fontSize) {
   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);
@@ -3335,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: {
@@ -3397,52 +3654,6 @@ function focusElements(deps) {
   };
 }
 
-// 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/frames.ts
 function boundsAround(children) {
   const pad2 = HOUSE.sizes.framePad;
@@ -3532,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,
@@ -3574,6 +3955,38 @@ function edgePoint(from, to, gap) {
   const t = scale + push;
   return [cx + dx * t, cy + dy * t];
 }
+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);
@@ -3589,18 +4002,53 @@ function redrawOne(current, labels, arrow, lane) {
     ...edgePoint(boxOf(from), boxOf(to), startGap),
     ...edgePoint(boxOf(to), boxOf(from), endGap)
   ];
-  const points = elbowed ? elbowRoute(ex - sx, ey - sy) : [point(0, 0), point(ex - sx, ey - sy)];
-  const spans = points.reduce(
-    (box, [px2, py]) => ({
-      w: Math.max(box.w, Math.abs(px2)),
-      h: Math.max(box.h, Math.abs(py))
-    }),
-    { w: 0, h: 0 }
-  );
+  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,
+    // 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,
@@ -3608,7 +4056,7 @@ function redrawOne(current, labels, arrow, lane) {
   };
   const label = labels.get(arrow.id);
   if (label === void 0) return [redrawn];
-  const mid = routeMidpoint({ x: sx, y: sy, points });
+  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 }];
 }
@@ -3621,6 +4069,7 @@ function faceBetween(from, to) {
   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) => {
@@ -3656,7 +4105,8 @@ function laneOffsets(arrows, current) {
     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 spread = Math.min(LANE_SPREAD, span / (slots.length + 1));
+    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 };
@@ -3745,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;
@@ -3768,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];
     }
@@ -3832,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));
@@ -3863,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 = [];
@@ -3876,13 +4370,18 @@ function layoutLayered(scene, targets, spacing) {
   }
   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();
   for (const node of nodes) incoming.set(node.id, []);
-  for (const edge of edges) incoming.get(edge.to)?.push(edge.from);
+  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) {
@@ -3923,26 +4422,87 @@ function layoutLayered(scene, targets, spacing) {
       previous = key;
     }
   }
-  const position = /* @__PURE__ */ new Map();
   const rankNumbers = [...slots.keys()].sort((a, b) => a - b);
+  const childrenOf2 = /* @__PURE__ */ new Map();
   for (const r of rankNumbers) {
-    const bucket = slots.get(r) ?? [];
-    const scored = bucket.map((slot) => {
-      const parents = slot.parents.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 { slot, barycentre };
-    });
-    scored.sort(
-      (a, b) => a.barycentre - b.barycentre || (a.slot.key < b.slot.key ? -1 : a.slot.key > b.slot.key ? 1 : 0)
-    );
-    scored.forEach(({ slot }, i) => {
-      position.set(slot.key, i);
-    });
-    slots.set(
-      r,
-      scored.map((entry) => entry.slot)
-    );
+    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 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) => {
@@ -3990,6 +4550,202 @@ function layoutLayered(scene, targets, spacing) {
   });
   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) {
@@ -4165,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 = (element) => labelledSize(element.label, element.fontSize ?? HOUSE.fontSize);
-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(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/create-elements.ts
 function createElements(deps) {
   return async (input) => {
@@ -4742,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) => {
@@ -4811,11 +5509,14 @@ function updateElements(deps) {
         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));
@@ -4944,7 +5645,7 @@ function readEnv(source) {
 }
 
 // src/composition/container.ts
-var PACKAGE_VERSION = "1.1.0";
+var PACKAGE_VERSION = "1.1.1";
 function readRuntime() {
   return {
     env: process.env,
@@ -5552,9 +6253,13 @@ 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;
@@ -5958,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. How the line runs, what each end looks like, and whether it is dashed all carry meaning here and are all settable \u2014 read chalk_read_me('arrows') before drawing a diagram's worth of them, or every edge comes out an identical straight solid line.",
+  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
@@ -5984,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 },