chalkbridge 1.0.4 → 1.1.0

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, 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 './chunk-7D4SUZUM.js';
 import { appendFileSync, existsSync, mkdirSync } from 'node:fs';
 import { homedir } from 'node:os';
@@ -2025,6 +2025,109 @@ 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/observe.ts
 var SHORT_ID_LENGTH = 4;
 var shortId2 = (id) => id.slice(0, SHORT_ID_LENGTH);
@@ -2131,6 +2234,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 +2243,8 @@ 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,
     detail: input.detail
   };
 }
@@ -3171,6 +3277,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,6 +3305,19 @@ 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/app/usecases/write/annotate-elements.ts
 var NOTE_GAP = 24;
@@ -3273,6 +3396,120 @@ function focusElements(deps) {
     return ok({ sceneId: scene.value.id, focused, broadcastTo });
   };
 }
+
+// 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;
+  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) {
@@ -3337,7 +3574,7 @@ function edgePoint(from, to, gap) {
   const t = scale + push;
   return [cx + dx * t, cy + dy * t];
 }
-function redrawOne(current, labels, arrow) {
+function redrawOne(current, labels, arrow, lane) {
   if (arrow.type !== "arrow") return [];
   const fromId = startOf(arrow);
   const toId = endOf(arrow);
@@ -3347,40 +3584,126 @@ 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 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 redrawn = {
     ...arrow,
     x: sx,
     y: sy,
-    width: Math.abs(ex - sx),
-    height: Math.abs(ey - sy),
+    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: sx, y: sy, 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;
+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 spread = Math.min(LANE_SPREAD, span / (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 +3711,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 +3730,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],
@@ -3545,18 +3874,11 @@ 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 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 edges) 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;
@@ -3570,57 +3892,101 @@ 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
+    });
+  }
+  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 position = /* @__PURE__ */ new Map();
-  const rankNumbers = [...ranks.keys()].sort((a, b) => a - b);
+  const rankNumbers = [...slots.keys()].sort((a, b) => a - b);
   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 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 { node, barycentre };
+      return { slot, barycentre };
     });
     scored.sort(
-      (a, b) => a.barycentre - b.barycentre || (a.node.id < b.node.id ? -1 : a.node.id > b.node.id ? 1 : 0)
+      (a, b) => a.barycentre - b.barycentre || (a.slot.key < b.slot.key ? -1 : a.slot.key > b.slot.key ? 1 : 0)
     );
-    scored.forEach(({ node }, i) => {
-      position.set(node.id, i);
+    scored.forEach(({ slot }, i) => {
+      position.set(slot.key, i);
     });
-    ranks.set(
+    slots.set(
       r,
-      scored.map((entry) => entry.node)
+      scored.map((entry) => entry.slot)
     );
   }
-  const gapH = spacing ?? HOUSE.spacing.h;
   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);
 }
@@ -3644,6 +4010,7 @@ function arrangeElements(deps) {
       sceneId: applied.value.sceneId,
       sceneVersion: applied.value.sceneVersion,
       broadcastTo: applied.value.broadcastTo,
+      overlapWarning: applied.value.overlapWarning,
       moved: [...applied.value.applied]
     });
   };
@@ -3809,7 +4176,7 @@ function explicit(input) {
   }
   return kept;
 }
-var defaultSize = () => serviceSize();
+var defaultSize = (element) => labelledSize(element.label, element.fontSize ?? HOUSE.fontSize);
 function normalizeElements(input) {
   return input.elements.map((element, i) => {
     const fallback = input.ids[i];
@@ -3858,7 +4225,7 @@ function normalizeElements(input) {
       id,
       x: element.x,
       y: element.y,
-      ...defaultSize(),
+      ...defaultSize(element),
       ...role,
       ...set,
       ...element.label === void 0 ? {} : { label: houseLabel(element.label) }
@@ -3901,20 +4268,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 +4296,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 +4325,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 +4358,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 +4379,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 +4395,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 +4436,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 +4467,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 +4479,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 +4492,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 +4593,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 +4606,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 +4638,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 +4651,8 @@ function writeContext(deps) {
         sceneVersion: updated.sceneVersion,
         broadcastTo: broadcast(scene, updated.sceneVersion, pushed),
         applied: [...merged.applied],
-        rejected
+        rejected,
+        overlapWarning: overlapWarning(merged.elements)
       });
     }
   };
@@ -4378,6 +4794,19 @@ 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);
@@ -4389,6 +4818,10 @@ function updateElements(deps) {
         });
       }
       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 +4835,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 +4889,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 +4944,7 @@ function readEnv(source) {
 }
 
 // src/composition/container.ts
-var PACKAGE_VERSION = "1.0.4";
+var PACKAGE_VERSION = "1.1.0";
 function readRuntime() {
   return {
     env: process.env,
@@ -5117,8 +5552,22 @@ function renderScene(description) {
   }
   lines.push("elements:");
   for (const element of description.elements) lines.push(row(element, true));
+  lines.push(...overlapLines(description));
   return lines.join("\n");
 }
+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 +5684,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 +5802,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 +5958,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. 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.",
   input: ConnectToolInput,
   output: ConnectOutput,
   call: (bridge) => bridge.connect
@@ -5853,6 +6302,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.