@r0kshan/cairn 1.0.0-RC17 → 1.0.0-RC18

package/README.md

@@ -34,7 +34,7 @@ Furthermore, complexe software architecture with many flows and component genera
 | **Typed diagrams with validation.** | Each view defines its element kinds and rules; `cairn validate` reports syntax, schema, and completeness issues as source-located, coded diagnostics, with a JSON mode for CI. |
 | **Flow matrix.** | `cairn matrix` exports the flow matrix as CSV, Markdown, or SVG — from any view, with the columns that view can fill. In infrastructure it splits protocol from port and annotates endpoints that sit in a network zone; headers localise via `style { lang: fr }`. The same table is available to embedders through `compile(source, { matrix: true })`. |
 | **Author-controlled positioning.** | Layout is automatic, with three opt-in overrides for when it gets a diagram wrong: `order: 2` sequences a top-level element along the disposition's own reading direction (left to right in `wide`, top to bottom in `tall`) and sorts siblings inside a container, `A.right -> B.left` pins which side of an element a flow leaves and arrives on, and the arrow glyph carries the line style (`->` solid, `-->` dashed, `..>` dotted). |
-| **Playground drag-to-adjust.** | When the automatic layout needs a correction, the [playground](https://cairn-psi-five.vercel.app/) lets you drag elements, flow labels, a single route segment, or a flow's endpoint onto another side. Every drag is written back into the source as the matching hint — `offset:`, `label-offset:`, `segment-offset:`, `ID.side` — so the adjustment stays versionable text and re-renders identically from the CLI. |
+| **Playground drag-to-adjust.** | When the automatic layout needs a correction, the [playground](https://cairn-psi-five.vercel.app/) lets you drag elements, flow labels, a single route segment, or a flow's endpoint onto another side. Every drag is written back into the source as the matching hint — `offset:`, `label-offset:`, `segment-offset:`, `ID.side` — so the adjustment stays versionable text and re-renders identically from the CLI. A hovered flow label also offers a wrap button, which writes that flow's own `flow-label-wrap:`. |
 | **Enterprise-view extras.** | Business objects on flows, an auto-generated legend, and a numbered-flow table via `flow-text: numbered`. |
 | **French or English output.** | `style { lang: fr }` localizes band titles, legend, and matrix headers while keeping keywords English for portable sources (open to adding other languages if you find this usefull) |
 | **In-built themes and customizable colours** | Whether using the default or a chosen in-built theme, element colours can be overriden  for all elements of a given kind in the `style` block |

package/bin/cairn.mjs

@@ -92386,7 +92386,8 @@ var init_ast = __esm({
       E0216: "Network zones belong to a site (or nest inside a larger zone): DMZ and LAN only mean something relative to a perimeter.",
       E0217: "A cluster groups the nodes that stand in for one another, so it needs a network location like any of them: put it in a `network-zone` or a `site`. Its members may be servers, deployed applications or databases \u2014 a Kubernetes cluster of worker nodes, or a database cluster of primary and standby.",
       W0540: 'C4 container-diagram practice: inter-process relationships should be labelled with their technology/protocol ("the how, not just the what"). Human/actor interactions are exempt. Add `(API_REST, JSON)` after the label, or ignore if the diagram is intentionally functional-only.',
-      E0223: "Unknown endpoint suffix. A flow endpoint may name the side it attaches to \u2014 `APP.right -> DB.left` \u2014 using the diagram as it is read: `left`, `right`, `top`, `bottom`. It may instead name its role towards a queue at the other end: `producer` or `consumer`. A declared side is a hint, not a guarantee: one the layout cannot reach is dropped with a W0570 warning rather than forced.",
+      E0223: "Unknown endpoint suffix. A flow endpoint may name the side it attaches to \u2014 `APP.right -> DB.left` \u2014 using the diagram as it is read: `left`, `right`, `top`, `bottom`. It may instead name its role towards a queue at the other end: `producer` or `consumer`. It may name one of each, in either order (`CAPTURE.producer.top`). A declared side is a hint, not a guarantee: one the layout cannot reach is dropped with a W0570 warning rather than forced.",
+      E0227: "One endpoint names two attachment sides, or two roles, and only one of each can hold: `A.top.bottom` asks for two sides of the same element, `A.producer.consumer` for two caps of the same queue. The first one written stands. A side and a *role* are a different matter \u2014 they answer different questions, so `CAPTURE.producer.top -> EVENTS` is read as both: the flow leaves CAPTURE's top and meets the queue's producer cap.",
       E0224: "An endpoint role says what this element does with the *queue* at the other end of the flow (`CAPTURE.producer -> EVENTS`), so the other end has to be one. Point the flow at a queue, or drop the role \u2014 between two ordinary elements the arrow already says everything a role would.",
       E0225: "A flow's queue endpoint carries both a declared side and a role at the other end, and they are two answers to one question: `producer` already means the queue's left cap and `consumer` its right. Keep the role and drop the side, or keep the side and drop the role.",
       E0240: "The infrastructure view requires every flow to carry its protocol (and port if relevant): the flow matrix is the primary output of this view. Add `(HTTPS/443)` after the label.",
@@ -92397,6 +92398,9 @@ var init_ast = __esm({
       E0109: "`offset:` takes two whole numbers \u2014 `offset: <dx>, <dy>` \u2014 the pixels to move this element by, right and down, from where the layout engine placed it. Either may be negative. It is a nudge, not a seat: elk still decides where the element belongs, so the diagram keeps re-flowing around it. Pair it with `order:` when the element is in the wrong place entirely \u2014 an offset large enough to change reading order is a sign the band is wrong, not the pixels.",
       W0572: "An `offset:` (or `label-offset:`) moved something onto something else. The hint is still honored \u2014 an author's positioning request is not negotiated \u2014 but the drawing now has an overlap the layout would never have produced on its own, so it is reported rather than left to be discovered in a review. Reduce the offset, or move the element with `order:` instead.",
       W0573: "An `offset:` was cut short so the element stays inside the container that holds it. Nesting is what a diagram *means* \u2014 a block drawn outside its system reads as a broken drawing, not a nudged one \u2014 so containment wins over the nudge here, and this is the one place a positioning hint is negotiated rather than honored outright. Nudge the container instead if the whole group belongs elsewhere, or use a smaller offset.",
+      E0110: "`size:` takes two whole numbers \u2014 `size: <dw>, <dh>` \u2014 the pixels of room to add to this container, rightward and downward, on top of what the layout gave it. Either may be negative. A delta rather than a box, for the same reason `offset:` is one: elk still sizes a container from what it holds, so a hint naming an absolute width would go stale the moment a child is added.",
+      E0226: "`size:` is a container's knob, and a container is something *drawn* as one. A leaf box is sized by the label in it \u2014 the uniform node width, or the tighter fit `label-padding:` asks for \u2014 so a delta there would argue with the one thing that decides it. A container kind holding nothing is the same case: with no children there is no frame, the layout gives it a plain box sized by its own label, and there is no room around anything to give. Put the elements it contains inside it, use `label-padding:` in `style` to change how tightly every box hugs its text, or `offset:` to move this one.",
+      W0575: "A `size:` ran out of room. A container is sized to hug what it holds, so its border has no slack of its own \u2014 shrinking closes the empty bands *between* its children instead, and stops once those are down to the minimum gap. Growing has no limit at all: a container enlarged past the one that holds it makes that one grow too. Everything else is honored as written, so a container grown onto a neighbour is drawn as asked and reported as W0572. To make this box smaller still, move or resize what is inside it.",
       W0571: "An endpoint reads `ID.side`, but `ID.side` is itself a declared element, and a declared id always wins \u2014 so the flow attaches to that element and no side is pinned. Rename the element if you meant the side."
     };
   }
@@ -93222,57 +93226,93 @@ function parseElement(p, sourceToken, parent) {
   (parent ? parent.children : model.elements).push(element);
 }
 function splitEndpoint(token, flow, end) {
-  const dot = token.text.lastIndexOf(".");
-  if (dot <= 0 || dot === token.text.length - 1) return null;
-  const base = token.text.slice(0, dot);
-  const suffix = token.text.slice(dot + 1);
-  return {
-    flow,
-    end,
-    raw: token.text,
-    rawSpan: token.span,
-    base,
-    baseSpan: { line: token.span.line, col: token.span.col, len: base.length },
-    suffix,
-    suffixSpan: { line: token.span.line, col: token.span.col + dot + 1, len: suffix.length }
-  };
+  const texts = token.text.split(".");
+  if (texts.length < 2 || texts.some((text) => !text)) return null;
+  let col = token.span.col;
+  const parts = texts.map((text) => {
+    const span = { line: token.span.line, col, len: text.length };
+    col += text.length + 1;
+    return { text, span };
+  });
+  return { flow, end, raw: token.text, rawSpan: token.span, parts };
 }
 function resolveEndpointSuffixes(splits, model, diagnostics) {
+  const sideOf2 = (text) => ATTACH_SIDES.includes(text);
+  const roleOf = (text) => ATTACH_ROLES.includes(text);
   for (const split of splits) {
-    const isSide = ATTACH_SIDES.includes(split.suffix);
-    const isRole = ATTACH_ROLES.includes(split.suffix);
     if (model.index.has(split.raw)) {
-      if (isSide || isRole)
+      let head = split.parts.length;
+      while (head > 1 && (sideOf2(split.parts[head - 1].text) || roleOf(split.parts[head - 1].text)))
+        head--;
+      const shadowed = split.parts.slice(head).map((part) => part.text);
+      if (shadowed.length) {
+        const base = split.parts.slice(0, head).map((part) => part.text).join(".");
+        const reading = [
+          shadowed.some((text) => roleOf(text)) ? "a role" : "",
+          shadowed.some((text) => sideOf2(text)) ? "an attachment side" : ""
+        ].filter(Boolean);
         diagnostics.push({
           code: "W0571",
           severity: "warning",
-          message: `\`${split.raw}\` is a declared element, so \`.${split.suffix}\` is not read as ${isSide ? "an attachment side" : "a role"}`,
+          message: `\`${split.raw}\` is a declared element, so \`.${shadowed.join(".")}\` is not read as ${reading.join(" and ")}`,
           span: split.rawSpan,
           note: "a declared id always wins over the `ID.side` reading",
-          help: isSide ? `rename the element if you meant to attach the flow to the ${split.suffix} side of \`${split.base}\`` : `rename the element if you meant \`${split.base}\` to be the ${split.suffix} of the queue at the other end`
+          help: `rename the element if you meant \`.${shadowed.join(".")}\` on \`${base}\``
         });
+      }
       continue;
     }
-    if (!model.index.has(split.base)) continue;
-    if (!isSide && !isRole)
-      diagnostics.push({
-        code: "E0223",
-        severity: "error",
-        message: `unknown endpoint suffix \`${split.suffix}\``,
-        span: split.suffixSpan,
-        note: "an endpoint names either the side it attaches to, as the diagram is read, or its role towards a queue",
-        help: "use `left`, `right`, `top` or `bottom` \u2014 `APP.right -> DB.left` \u2014 or `producer` / `consumer`, e.g. `CAPTURE.producer -> EVENTS`"
-      });
-    const side = isSide ? { value: split.suffix, span: split.suffixSpan } : void 0;
-    const role = isRole ? { value: split.suffix, span: split.suffixSpan } : void 0;
+    let cut = 0;
+    for (let take = split.parts.length - 1; take >= 1; take--) {
+      const base = split.parts.slice(0, take).map((part) => part.text).join(".");
+      if (model.index.has(base)) {
+        cut = take;
+        break;
+      }
+    }
+    if (!cut) continue;
+    let side;
+    let role;
+    for (const part of split.parts.slice(cut)) {
+      const partIsSide = sideOf2(part.text);
+      const partIsRole = roleOf(part.text);
+      if (!partIsSide && !partIsRole) {
+        diagnostics.push({
+          code: "E0223",
+          severity: "error",
+          message: `unknown endpoint suffix \`${part.text}\``,
+          span: part.span,
+          note: "an endpoint names either the side it attaches to, as the diagram is read, or its role towards a queue",
+          help: "use `left`, `right`, `top` or `bottom` \u2014 `APP.right -> DB.left` \u2014 or `producer` / `consumer`, e.g. `CAPTURE.producer -> EVENTS`, or one of each: `CAPTURE.producer.top -> EVENTS`"
+        });
+        continue;
+      }
+      const held = partIsSide ? side : role;
+      if (held) {
+        diagnostics.push({
+          code: "E0227",
+          severity: "error",
+          message: `this endpoint already names ${partIsSide ? `the \`${held.value}\` side` : `the \`${held.value}\` role`}`,
+          span: part.span,
+          note: `\`${split.raw}\` names two ${partIsSide ? "attachment sides" : "roles"}, and only one can hold`,
+          help: partIsSide ? "keep one side \u2014 a side and a *role* do accumulate, e.g. `CAPTURE.producer.top`" : "keep one role \u2014 a role and a *side* do accumulate, e.g. `CAPTURE.producer.top`"
+        });
+        continue;
+      }
+      if (partIsSide) side = { value: part.text, span: part.span };
+      else role = { value: part.text, span: part.span };
+    }
+    const baseParts = split.parts.slice(0, cut);
+    const baseText = baseParts.map((part) => part.text).join(".");
+    const baseSpan = { line: split.rawSpan.line, col: split.rawSpan.col, len: baseText.length };
     if (split.end === "from") {
-      split.flow.from = split.base;
-      split.flow.fromSpan = split.baseSpan;
+      split.flow.from = baseText;
+      split.flow.fromSpan = baseSpan;
       split.flow.fromSide = side;
       split.flow.fromRole = role;
     } else {
-      split.flow.to = split.base;
-      split.flow.toSpan = split.baseSpan;
+      split.flow.to = baseText;
+      split.flow.toSpan = baseSpan;
       split.flow.toSide = side;
       split.flow.toRole = role;
     }
@@ -93322,9 +93362,9 @@ function readOffsetPair(p) {
     span: { line: dx.span.line, col: dx.span.col, len: dy.span.col + dy.span.len - dx.span.col }
   };
 }
-function tryOffsetEntry(p, parent) {
+function tryPairEntry(p, parent, entry, put) {
   const { matchToken, advance, reportCoded, save, restore, syncToNextLine } = p;
-  if (!parent || !matchToken("id", "offset")) return false;
+  if (!parent || !matchToken("id", entry.key)) return false;
   const mark = save();
   const keyToken = advance();
   if (!matchToken("colon")) {
@@ -93334,16 +93374,11 @@ function tryOffsetEntry(p, parent) {
   advance();
   const pair2 = readOffsetPair(p);
   if (!pair2) {
-    reportCoded(
-      "E0109",
-      "`offset` expects two whole numbers \u2014 `offset: <dx>, <dy>`",
-      keyToken.span,
-      "e.g. `offset: 40, -20` \u2014 40px right and 20px up from where the layout put it"
-    );
+    reportCoded(entry.code, entry.message, keyToken.span, entry.help);
     syncToNextLine();
     return true;
   }
-  parent.offset = pair2;
+  put(parent, pair2);
   return true;
 }
 function tryLogoEntry(p, parent) {
@@ -93589,7 +93624,7 @@ function parse(src) {
     }
     if (tryStyleBlock(parent)) return;
     if (tryOrderEntry(parser, parent)) return;
-    if (tryOffsetEntry(parser, parent)) return;
+    if (tryOffsetEntry(parser, parent) || trySizeEntry(parser, parent)) return;
     if (tryLogoEntry(parser, parent)) return;
     if (!parent && tryLegendBlock(parser)) return;
     if (!parent && tryBusinessObject(parser)) return;
@@ -93784,7 +93819,7 @@ function applyStyleEntry(entry) {
       });
   }
 }
-var LINE_STYLES, LABEL_POSITIONS, DISPOSITIONS, NUMERIC_STYLE_ENTRIES, UNIFORM_STYLE_ENTRIES;
+var tryOffsetEntry, trySizeEntry, LINE_STYLES, LABEL_POSITIONS, DISPOSITIONS, NUMERIC_STYLE_ENTRIES, UNIFORM_STYLE_ENTRIES;
 var init_parser = __esm({
   "src/parser.ts"() {
     "use strict";
@@ -93793,6 +93828,32 @@ var init_parser = __esm({
     init_themes();
     init_element_tree();
     init_text_metrics();
+    tryOffsetEntry = (p, parent) => tryPairEntry(
+      p,
+      parent,
+      {
+        key: "offset",
+        code: "E0109",
+        message: "`offset` expects two whole numbers \u2014 `offset: <dx>, <dy>`",
+        help: "e.g. `offset: 40, -20` \u2014 40px right and 20px up from where the layout put it"
+      },
+      (element, pair2) => {
+        element.offset = pair2;
+      }
+    );
+    trySizeEntry = (p, parent) => tryPairEntry(
+      p,
+      parent,
+      {
+        key: "size",
+        code: "E0110",
+        message: "`size` expects two whole numbers \u2014 `size: <dw>, <dh>`",
+        help: "e.g. `size: 120, 40` \u2014 120px wider and 40px taller than the layout made it"
+      },
+      (element, pair2) => {
+        element.size = { dw: pair2.dx, dh: pair2.dy, span: pair2.span };
+      }
+    );
     LINE_STYLES = /* @__PURE__ */ new Set(["solid", "dashed", "dotted"]);
     LABEL_POSITIONS = /* @__PURE__ */ new Set(["on-line", "above", "below"]);
     DISPOSITIONS = /* @__PURE__ */ new Set(["wide", "tall", "slide", "page"]);
@@ -94764,6 +94825,7 @@ function validate(model) {
     ...checkNesting(elements, view),
     ...checkFlows(model, view),
     ...checkEndpointRoles(model, view),
+    ...checkSizes(elements, view),
     ...checkLogos(elements, view),
     ...checkBusinessObjects(model, view),
     ...checkMinimumCounts(elements, model, view),
@@ -94806,6 +94868,31 @@ function checkUnknownKinds(elements, view) {
   }
   return diagnostics;
 }
+function checkSizes(elements, view) {
+  const diagnostics = [];
+  for (const element of elements) {
+    if (!element.size) continue;
+    if (!view.containerKinds.includes(element.kind))
+      diagnostics.push({
+        code: "E0226",
+        severity: "error",
+        message: `\`${element.kind}\` is not a container, so it has no \`size\` to give`,
+        span: element.size.span,
+        note: `the \`${view.name}\` view accepts \`size\` on: ${view.containerKinds.join(", ")}`,
+        help: "a leaf box is sized by its own label \u2014 set `label-padding:` in `style` to change how tightly, or nudge this one with `offset:`"
+      });
+    else if (!element.children.length)
+      diagnostics.push({
+        code: "E0226",
+        severity: "error",
+        message: `\`${element.id}\` holds nothing, so it is drawn as a plain box rather than a container`,
+        span: element.size.span,
+        note: "a container's size is the room around what it holds \u2014 with no children there is no room to give",
+        help: "put the elements it contains inside it, or drop the `size:` and nudge this one with `offset:`"
+      });
+  }
+  return diagnostics;
+}
 function checkLogos(elements, view) {
   const diagnostics = [];
   const logoKinds = view.logoKinds ?? [];
@@ -98288,6 +98375,58 @@ function applySwap(scene, pair2, swap, leaves) {
     return true;
   }
 }
+function straightenCarriedRuns(scene, titleBoxes, only) {
+  if (!only.size) return;
+  const leaves = scene.nodes.filter((node) => !node.container);
+  if (!leaves.length) return;
+  const ctx = createTidyContext(scene, leaves, titleBoxes, false);
+  const strikesTitle = (at, from, to, horizontal) => {
+    const lo = Math.min(from, to);
+    const hi = Math.max(from, to);
+    return titleBoxes.some(
+      (band) => horizontal ? at > band.y && at < band.y + band.height && lo < band.x + band.width && hi > band.x : at > band.x && at < band.x + band.width && lo < band.y + band.height && hi > band.y
+    );
+  };
+  const taken = (seat, mine) => scene.edges.some(
+    (other) => other !== mine && other.pts.length >= 2 && [other.pts[0], other.pts[other.pts.length - 1]].some(
+      (end) => Math.abs(end.x - seat.x) < MIN_ATTACH_GAP && Math.abs(end.y - seat.y) < MIN_ATTACH_GAP
+    )
+  );
+  for (const edge of scene.edges) {
+    if (!only.has(edge.id) || edge.pts.length < 3) continue;
+    if (edge.pinned?.start || edge.pinned?.end) continue;
+    const src = sideOf(edge.pts[0], leaves);
+    const dst = sideOf(edge.pts[edge.pts.length - 1], leaves);
+    if (!src || !dst || src.node === dst.node) continue;
+    const alongY = src.side === "east" || src.side === "west";
+    const rightwards = dst.node.x > src.node.x;
+    const downwards = dst.node.y > src.node.y;
+    const srcSide = alongY ? rightwards ? "east" : "west" : downwards ? "south" : "north";
+    const dstSide = alongY ? rightwards ? "west" : "east" : downwards ? "north" : "south";
+    const span = (node) => alongY ? [node.y + MIN_SIDE_INSET, node.y + node.height - MIN_SIDE_INSET] : [node.x + MIN_SIDE_INSET, node.x + node.width - MIN_SIDE_INSET];
+    const [srcLo, srcHi] = span(src.node);
+    const [dstLo, dstHi] = span(dst.node);
+    const low = Math.max(srcLo, dstLo);
+    const high = Math.min(srcHi, dstHi);
+    if (low > high) continue;
+    const at = Math.round((low + high) / 2);
+    const seatOnFace = (node, side) => side === "north" ? { x: at, y: node.y } : side === "south" ? { x: at, y: node.y + node.height } : side === "west" ? { x: node.x, y: at } : { x: node.x + node.width, y: at };
+    const from = seatOnFace(src.node, srcSide);
+    const to = seatOnFace(dst.node, dstSide);
+    const travel = alongY ? to.x - from.x : to.y - from.y;
+    const outward = (side) => side === "east" || side === "south" ? 1 : -1;
+    if (travel === 0 || Math.sign(travel) !== outward(srcSide)) continue;
+    const lane = alongY ? [from.x, to.x] : [from.y, to.y];
+    const runFrom = Math.min(lane[0], lane[1]);
+    const runTo = Math.max(lane[0], lane[1]);
+    if (ctx.runHitsNode(!alongY, at, runFrom, runTo)) continue;
+    if (strikesTitle(at, runFrom, runTo, alongY)) continue;
+    const others = ctx.runsExcept(edge.id);
+    if (!ctx.runIsClear(alongY ? others.horizontal : others.vertical, at, runFrom, runTo)) continue;
+    if (taken(from, edge) || taken(to, edge)) continue;
+    edge.pts = [from, to];
+  }
+}
 function swapCrossingSiblingSeats(scene) {
   const leaves = scene.nodes.filter((node) => !node.container);
   const endsOf = (edge) => [
@@ -100954,6 +101093,155 @@ function stampLabelOffsets(edges, model) {
     for (const label of edge.labels) label.offset = { dx: declared.dx, dy: declared.dy };
   }
 }
+function freeBands(box, axis) {
+  const { node, pad } = box;
+  const { min, size } = AXIS[axis];
+  const spans = kidsOf(box).map((kid) => ({ start: kid[min], end: kid[min] + kid[size] })).sort((a, b) => a.start - b.start || a.end - b.end);
+  const merged = [];
+  for (const span of spans) {
+    const last = merged[merged.length - 1];
+    if (last && span.start <= last.end) last.end = Math.max(last.end, span.end);
+    else merged.push({ ...span });
+  }
+  if (!merged.length) return [];
+  const bands = [];
+  const add = (start, end, keep) => {
+    if (end - start > keep) bands.push({ end, spare: end - start - keep });
+  };
+  add(node[min], merged[0].start, pad);
+  for (let i = 0; i + 1 < merged.length; i++)
+    add(merged[i].end, merged[i + 1].start, MIN_SIBLING_GAP);
+  add(merged[merged.length - 1].end, node[min] + node[size], pad);
+  return bands;
+}
+function holdsChildren(box) {
+  const { node, pad } = box;
+  const kids = kidsOf(box);
+  if (!kids.length) return { minWidth: pad * 2, minHeight: pad * 2 };
+  return {
+    minWidth: Math.max(...kids.map((kid) => kid.x + kid.width)) + pad - node.x,
+    minHeight: Math.max(...kids.map((kid) => kid.y + kid.height)) + pad - node.y
+  };
+}
+function contentFloor(box) {
+  const spare = (axis) => freeBands(box, axis).reduce((total, band) => total + band.spare, 0);
+  return { minWidth: box.node.width - spare("x"), minHeight: box.node.height - spare("y") };
+}
+function squeezeInside(box, axis, target) {
+  const { min, size } = AXIS[axis];
+  const need = box.node[size] - target;
+  if (need <= 0) return;
+  const bands = freeBands(box, axis);
+  const spare = bands.reduce((total, band) => total + band.spare, 0);
+  if (spare <= 0) return;
+  const share = Math.min(1, need / spare);
+  const shiftAt = (at) => bands.reduce((total, band) => at >= band.end ? total + band.spare * share : total, 0);
+  for (const child of box.element.children) {
+    const kid = box.nodeById.get(child.id);
+    if (!kid) continue;
+    const shift = shiftAt(kid[min]);
+    if (!shift) continue;
+    for (const id of subtreeIds(child)) {
+      const inside = box.nodeById.get(id);
+      if (inside) inside[min] -= shift;
+    }
+  }
+}
+function applyContainerSizes(scene, model) {
+  const carried = /* @__PURE__ */ new Set();
+  const wanted = /* @__PURE__ */ new Map();
+  const walk = (elements) => {
+    for (const element of elements) {
+      walk(element.children);
+      if (element.size) wanted.set(element.id, element.size);
+    }
+  };
+  walk(model.elements);
+  if (!wanted.size) return carried;
+  const nodeById = new Map(scene.nodes.map((node) => [node.id, node]));
+  const pad = containerPad(model);
+  const clampedSpans = /* @__PURE__ */ new Set();
+  const applied = /* @__PURE__ */ new Map();
+  const before = new Map(
+    scene.nodes.map((node) => [
+      node.id,
+      { x: node.x, y: node.y, width: node.width, height: node.height }
+    ])
+  );
+  for (const [id, spec] of wanted) {
+    const node = nodeById.get(id);
+    const element = model.index.get(id);
+    if (!node || !element) continue;
+    const box = { node, element, nodeById, pad };
+    const floor = contentFloor(box);
+    const width = Math.max(node.width + spec.dw, floor.minWidth);
+    const height = Math.max(node.height + spec.dh, floor.minHeight);
+    if (width !== node.width + spec.dw || height !== node.height + spec.dh)
+      clampedSpans.add(spec.span);
+    squeezeInside(box, "x", width);
+    squeezeInside(box, "y", height);
+    node.width = width;
+    node.height = height;
+  }
+  const containWithin = (elements) => {
+    for (const element of elements) {
+      containWithin(element.children);
+      const node = nodeById.get(element.id);
+      if (!node?.container) continue;
+      const holds = holdsChildren({ node, element, nodeById, pad });
+      node.width = Math.max(node.width, holds.minWidth);
+      node.height = Math.max(node.height, holds.minHeight);
+    }
+  };
+  containWithin(model.elements);
+  for (const id of wanted.keys()) {
+    const node = nodeById.get(id);
+    const was = before.get(id);
+    if (node && was)
+      applied.set(id, { dw: node.width - was.width, dh: node.height - was.height });
+  }
+  if (clampedSpans.size) scene.clampedSizes = clampedSpans;
+  scene.appliedSizes = applied;
+  const seats = [];
+  for (const node of scene.nodes) {
+    const was = before.get(node.id);
+    if (!was) continue;
+    const moved = {
+      dx: node.x - was.x,
+      dy: node.y - was.y,
+      dw: node.width - was.width,
+      dh: node.height - was.height
+    };
+    if (!moved.dx && !moved.dy && !moved.dw && !moved.dh) continue;
+    seats.push({ box: was, ...moved });
+  }
+  seats.sort((a, b) => a.box.width * a.box.height - b.box.width * b.box.height);
+  if (!seats.length) return carried;
+  for (const edge of scene.edges) {
+    if (edge.pts.length < 2) continue;
+    for (const which of ["first", "last"]) {
+      const terminal = edge.pts[which === "first" ? 0 : edge.pts.length - 1];
+      const seat = seats.find((candidate) => pointOn(terminal, candidate.box));
+      if (!seat) continue;
+      const onRight = terminal.x >= seat.box.x + seat.box.width - ON_BORDER;
+      const onBottom = terminal.y >= seat.box.y + seat.box.height - ON_BORDER;
+      const delta = {
+        dx: seat.dx + (onRight ? seat.dw : 0),
+        dy: seat.dy + (onBottom ? seat.dh : 0)
+      };
+      if (!delta.dx && !delta.dy) continue;
+      carried.add(edge.id);
+      carryTerminal(edge, which, delta, {
+        x: seat.box.x + seat.dx,
+        y: seat.box.y + seat.dy,
+        width: seat.box.width + seat.dw,
+        height: seat.box.height + seat.dh
+      });
+    }
+  }
+  for (const edge of scene.edges) if (carried.has(edge.id)) dropRedundantPoints(edge.pts);
+  return carried;
+}
 function applyNodeOffsets(scene, offsetOf) {
   const carried = /* @__PURE__ */ new Set();
   if (!offsetOf.size) return carried;
@@ -101018,19 +101306,36 @@ function applyNodeOffsets(scene, offsetOf) {
       const seat = seats.find((candidate) => pointOn(terminal, candidate.box));
       if (!seat || !seat.delta.dx && !seat.delta.dy) continue;
       carried.add(edge.id);
-      const neighbourIndex = end === 0 ? 1 : edge.pts.length - 2;
-      const neighbour = edge.pts[neighbourIndex];
-      const wasHorizontal = Math.abs(terminal.y - neighbour.y) < 0.5;
-      terminal.x += seat.delta.dx;
-      terminal.y += seat.delta.dy;
-      const elbow = wasHorizontal ? { x: neighbour.x, y: terminal.y } : { x: terminal.x, y: neighbour.y };
-      const degenerate = Math.abs(elbow.x - terminal.x) < 0.5 && Math.abs(elbow.y - terminal.y) < 0.5 || Math.abs(elbow.x - neighbour.x) < 0.5 && Math.abs(elbow.y - neighbour.y) < 0.5;
-      if (!degenerate) edge.pts.splice(end === 0 ? 1 : edge.pts.length - 1, 0, elbow);
+      carryTerminal(edge, end === 0 ? "first" : "last", seat.delta, {
+        x: seat.box.x + seat.delta.dx,
+        y: seat.box.y + seat.delta.dy,
+        width: seat.box.width,
+        height: seat.box.height
+      });
     }
   }
   for (const edge of scene.edges) if (carried.has(edge.id)) dropRedundantPoints(edge.pts);
   return carried;
 }
+function carryTerminal(edge, which, delta, face) {
+  const end = which === "first" ? 0 : edge.pts.length - 1;
+  const terminal = edge.pts[end];
+  const neighbour = edge.pts[which === "first" ? 1 : edge.pts.length - 2];
+  const wasHorizontal = Math.abs(terminal.y - neighbour.y) < SEGMENT_EPSILON;
+  terminal.x += delta.dx;
+  terminal.y += delta.dy;
+  const slide = wasHorizontal ? { along: "y", low: face.y, high: face.y + face.height } : { along: "x", low: face.x, high: face.x + face.width };
+  const residual = neighbour[slide.along] - terminal[slide.along];
+  const seat = Math.min(
+    Math.max(neighbour[slide.along], slide.low + SEAT_INSET),
+    Math.max(slide.high - SEAT_INSET, slide.low + SEAT_INSET)
+  );
+  if (Math.abs(residual) < ARROW_ROOM2 && Math.abs(seat - neighbour[slide.along]) < SEGMENT_EPSILON)
+    terminal[slide.along] = seat;
+  const elbow = wasHorizontal ? { x: neighbour.x, y: terminal.y } : { x: terminal.x, y: neighbour.y };
+  const degenerate = Math.abs(elbow.x - terminal.x) < SEGMENT_EPSILON && Math.abs(elbow.y - terminal.y) < SEGMENT_EPSILON || Math.abs(elbow.x - neighbour.x) < SEGMENT_EPSILON && Math.abs(elbow.y - neighbour.y) < SEGMENT_EPSILON;
+  if (!degenerate) edge.pts.splice(which === "first" ? 1 : edge.pts.length - 1, 0, elbow);
+}
 function dropRedundantPoints(pts) {
   const inLine = (a, b, c) => Math.abs(a.x - b.x) < SEGMENT_EPSILON && Math.abs(b.x - c.x) < SEGMENT_EPSILON || Math.abs(a.y - b.y) < SEGMENT_EPSILON && Math.abs(b.y - c.y) < SEGMENT_EPSILON;
   for (let i = pts.length - 2; i >= 1; i--)
@@ -101156,6 +101461,37 @@ function shiftIntoCanvas(scene) {
   scene.width += shiftX;
   scene.height += shiftY;
 }
+function sizeOverlaps(scene, model, overlap) {
+  const sized = /* @__PURE__ */ new Map();
+  for (const element of model.index.values())
+    if (element.size) sized.set(element.id, element.size.span);
+  if (!sized.size) return [];
+  const family = /* @__PURE__ */ new Map();
+  const walk = (elements, ancestors) => {
+    for (const element of elements) {
+      if (sized.has(element.id))
+        family.set(element.id, /* @__PURE__ */ new Set([...ancestors, ...subtreeIds(element)]));
+      walk(element.children, [...ancestors, element.id]);
+    }
+  };
+  walk(model.elements, []);
+  const diagnostics = [];
+  for (const node of scene.nodes) {
+    const span = sized.get(node.id);
+    if (!span) continue;
+    const kin = family.get(node.id);
+    const struck = scene.nodes.find((other) => !kin.has(other.id) && overlap(node, other));
+    if (!struck) continue;
+    diagnostics.push({
+      code: "W0572",
+      severity: "warning",
+      message: `\`size\` on \`${node.id}\` overlaps \`${struck.id}\``,
+      span,
+      help: "the resize is applied as written \u2014 make it smaller, or give the drawing room with `order:`"
+    });
+  }
+  return diagnostics;
+}
 function offsetDiagnostics(scene, model) {
   const hints = [];
   for (const span of scene.segmentHints?.stale ?? [])
@@ -101174,6 +101510,14 @@ function offsetDiagnostics(scene, model) {
       span,
       help: "the run carries a terminal, so it can only slide as far as the side that terminal sits on \u2014 pin the side with `ID.side`, or move the element instead"
     });
+  for (const span of scene.clampedSizes ?? [])
+    hints.push({
+      code: "W0575",
+      severity: "warning",
+      message: "`size` was limited to keep this container around its own children",
+      span,
+      help: "a container is drawn around what it holds, which is not negotiable \u2014 resize or move the children first if the box has to be smaller"
+    });
   const spans = /* @__PURE__ */ new Map();
   const walk = (elements, inherited) => {
     for (const element of elements) {
@@ -101184,8 +101528,9 @@ function offsetDiagnostics(scene, model) {
   };
   walk(model.elements);
   for (const flow of model.flows) if (flow.labelOffset) spans.set(flow.id, flow.labelOffset.span);
-  if (!spans.size) return hints;
   const overlap = (a, b) => a.x < b.x + b.width && b.x < a.x + a.width && a.y < b.y + b.height && b.y < a.y + a.height;
+  hints.push(...sizeOverlaps(scene, model, overlap));
+  if (!spans.size) return hints;
   const leaves = scene.nodes.filter((node) => !node.container);
   const labels = scene.edges.flatMap((edge) => edge.labels);
   const diagnostics = [...hints];
@@ -101644,9 +101989,11 @@ function refuseScenicRepairs(scene, before) {
   }
 }
 function applyAuthorPositioning(scene, model) {
+  const runsBefore = new Map(scene.edges.map((edge) => [edge.id, straightRuns(edge.pts).length]));
+  const resized = applyContainerSizes(scene, model);
   const offsets = offsetAssignment(model);
-  if (offsets.size) {
-    const carried = applyNodeOffsets(scene, offsets);
+  if (offsets.size || resized.size) {
+    const carried = /* @__PURE__ */ new Set([...resized, ...applyNodeOffsets(scene, offsets)]);
     for (const edge of scene.edges) if (carried.has(edge.id)) edge.repairedFrom = void 0;
     const titles = titleBoxesOf(scene, model);
     reaimAfterOffsets(scene, titles, carried);
@@ -101662,6 +102009,12 @@ function applyAuthorPositioning(scene, model) {
       refuseScenicRepairs(scene, before);
       decoincideAfterOffsets(scene, titles, repairable);
     }
+    const bent = new Set(
+      scene.edges.filter(
+        (edge) => carried.has(edge.id) && straightRuns(edge.pts).length > (runsBefore.get(edge.id) ?? 0)
+      ).map((edge) => edge.id)
+    );
+    straightenCarriedRuns(scene, titles, bent);
   }
   const nudgedRuns = applySegmentOffsets(scene, model);
   if (nudgedRuns) {
@@ -101670,7 +102023,7 @@ function applyAuthorPositioning(scene, model) {
         edge.repairedFrom = void 0;
   }
   const nudgedLabels = scene.edges.some((edge) => edge.labels.some((label) => label.offset));
-  if (!offsets.size && !nudgedRuns && !nudgedLabels) return;
+  if (!offsets.size && !resized.size && !nudgedRuns && !nudgedLabels) return;
   anchorFlowLabels(scene, titleBoxesOf(scene, model));
   fitCanvas(scene);
 }
@@ -101821,7 +102174,7 @@ async function chooseLayout(model, view) {
   }
   return best?.scene ?? base;
 }
-var orderOption, semiInteractiveOption, ACTOR_MIN_WIDTH, PORT_PASS_ROUNDS, centerOf, isElkSource, elkPortId, DENSE_ENOUGH, DENSITY_GAIN, INGRESS_PARTITION, DEFAULT_INGRESS_KINDS, EGRESS_PARTITION, SLOT_SCALE, SIDE_TO_ELK, sideRequest, pointOn, SEGMENT_EPSILON, SLIDE_UNBOUNDED, SEAT_INSET, LEFT_MARGIN, RECLAIM_GAP, MIN_RECLAIM, MIN_RECLAIM_KEPT, RECLAIM_SHARE, RECLAIM_UNBUYABLE_TIER, RECLAIM_TRADE_SHARE, RECLAIM_TRADE_MIN, RECLAIM_LIFT_SHARE, BORDER_AIR, ARROW_ROOM2, RUN_CLEAR, ASPECT_TARGETS, pathLength2;
+var orderOption, semiInteractiveOption, ACTOR_MIN_WIDTH, PORT_PASS_ROUNDS, centerOf, isElkSource, elkPortId, DENSE_ENOUGH, DENSITY_GAIN, INGRESS_PARTITION, DEFAULT_INGRESS_KINDS, EGRESS_PARTITION, SLOT_SCALE, SIDE_TO_ELK, sideRequest, ON_BORDER, pointOn, containerPad, MIN_SIBLING_GAP, kidsOf, AXIS, SEGMENT_EPSILON, SLIDE_UNBOUNDED, SEAT_INSET, LEFT_MARGIN, RECLAIM_GAP, MIN_RECLAIM, MIN_RECLAIM_KEPT, RECLAIM_SHARE, RECLAIM_UNBUYABLE_TIER, RECLAIM_TRADE_SHARE, RECLAIM_TRADE_MIN, RECLAIM_LIFT_SHARE, BORDER_AIR, ARROW_ROOM2, RUN_CLEAR, ASPECT_TARGETS, pathLength2;
 var init_scene_layout = __esm({
   "src/scene-layout.ts"() {
     "use strict";
@@ -101855,7 +102208,15 @@ var init_scene_layout = __esm({
       bottom: "SOUTH"
     };
     sideRequest = (side) => side ? { value: side } : void 0;
+    ON_BORDER = 1;
     pointOn = (point, box) => point.x >= box.x - 1 && point.x <= box.x + box.width + 1 && point.y >= box.y - 1 && point.y <= box.y + box.height + 1;
+    containerPad = (model) => model.style.containerPadding ?? (model.style.compact ? 7 : 9);
+    MIN_SIBLING_GAP = 20;
+    kidsOf = (box) => box.element.children.map((child) => box.nodeById.get(child.id)).filter((child) => !!child);
+    AXIS = {
+      x: { min: "x", size: "width" },
+      y: { min: "y", size: "height" }
+    };
     SEGMENT_EPSILON = 0.5;
     SLIDE_UNBOUNDED = 1e4;
     SEAT_INSET = 4;
@@ -103908,7 +104269,7 @@ CORE_I   -> PARTNER "Nightly export" (SFTP/22)
     };
     args = process.argv.slice(2);
     command = args[0];
-    version = true ? "1.0.0-RC17" : pkg.version;
+    version = true ? "1.0.0-RC18" : pkg.version;
     VALUE_FLAGS = /* @__PURE__ */ new Set(["-o", "--format", "--theme"]);
     positionalFile = () => {
       for (let index = 0; index < args.length; index++) {

package/dist/cairn.mjs

@@ -93129,57 +93129,93 @@ function parseElement(p, sourceToken, parent) {
   (parent ? parent.children : model.elements).push(element);
 }
 function splitEndpoint(token, flow, end) {
-  const dot = token.text.lastIndexOf(".");
-  if (dot <= 0 || dot === token.text.length - 1) return null;
-  const base = token.text.slice(0, dot);
-  const suffix = token.text.slice(dot + 1);
-  return {
-    flow,
-    end,
-    raw: token.text,
-    rawSpan: token.span,
-    base,
-    baseSpan: { line: token.span.line, col: token.span.col, len: base.length },
-    suffix,
-    suffixSpan: { line: token.span.line, col: token.span.col + dot + 1, len: suffix.length }
-  };
+  const texts = token.text.split(".");
+  if (texts.length < 2 || texts.some((text) => !text)) return null;
+  let col = token.span.col;
+  const parts = texts.map((text) => {
+    const span = { line: token.span.line, col, len: text.length };
+    col += text.length + 1;
+    return { text, span };
+  });
+  return { flow, end, raw: token.text, rawSpan: token.span, parts };
 }
 function resolveEndpointSuffixes(splits, model, diagnostics) {
+  const sideOf2 = (text) => ATTACH_SIDES.includes(text);
+  const roleOf = (text) => ATTACH_ROLES.includes(text);
   for (const split of splits) {
-    const isSide = ATTACH_SIDES.includes(split.suffix);
-    const isRole = ATTACH_ROLES.includes(split.suffix);
     if (model.index.has(split.raw)) {
-      if (isSide || isRole)
+      let head = split.parts.length;
+      while (head > 1 && (sideOf2(split.parts[head - 1].text) || roleOf(split.parts[head - 1].text)))
+        head--;
+      const shadowed = split.parts.slice(head).map((part) => part.text);
+      if (shadowed.length) {
+        const base = split.parts.slice(0, head).map((part) => part.text).join(".");
+        const reading = [
+          shadowed.some((text) => roleOf(text)) ? "a role" : "",
+          shadowed.some((text) => sideOf2(text)) ? "an attachment side" : ""
+        ].filter(Boolean);
         diagnostics.push({
           code: "W0571",
           severity: "warning",
-          message: `\`${split.raw}\` is a declared element, so \`.${split.suffix}\` is not read as ${isSide ? "an attachment side" : "a role"}`,
+          message: `\`${split.raw}\` is a declared element, so \`.${shadowed.join(".")}\` is not read as ${reading.join(" and ")}`,
           span: split.rawSpan,
           note: "a declared id always wins over the `ID.side` reading",
-          help: isSide ? `rename the element if you meant to attach the flow to the ${split.suffix} side of \`${split.base}\`` : `rename the element if you meant \`${split.base}\` to be the ${split.suffix} of the queue at the other end`
+          help: `rename the element if you meant \`.${shadowed.join(".")}\` on \`${base}\``
         });
+      }
       continue;
     }
-    if (!model.index.has(split.base)) continue;
-    if (!isSide && !isRole)
-      diagnostics.push({
-        code: "E0223",
-        severity: "error",
-        message: `unknown endpoint suffix \`${split.suffix}\``,
-        span: split.suffixSpan,
-        note: "an endpoint names either the side it attaches to, as the diagram is read, or its role towards a queue",
-        help: "use `left`, `right`, `top` or `bottom` \u2014 `APP.right -> DB.left` \u2014 or `producer` / `consumer`, e.g. `CAPTURE.producer -> EVENTS`"
-      });
-    const side = isSide ? { value: split.suffix, span: split.suffixSpan } : void 0;
-    const role = isRole ? { value: split.suffix, span: split.suffixSpan } : void 0;
+    let cut = 0;
+    for (let take = split.parts.length - 1; take >= 1; take--) {
+      const base = split.parts.slice(0, take).map((part) => part.text).join(".");
+      if (model.index.has(base)) {
+        cut = take;
+        break;
+      }
+    }
+    if (!cut) continue;
+    let side;
+    let role;
+    for (const part of split.parts.slice(cut)) {
+      const partIsSide = sideOf2(part.text);
+      const partIsRole = roleOf(part.text);
+      if (!partIsSide && !partIsRole) {
+        diagnostics.push({
+          code: "E0223",
+          severity: "error",
+          message: `unknown endpoint suffix \`${part.text}\``,
+          span: part.span,
+          note: "an endpoint names either the side it attaches to, as the diagram is read, or its role towards a queue",
+          help: "use `left`, `right`, `top` or `bottom` \u2014 `APP.right -> DB.left` \u2014 or `producer` / `consumer`, e.g. `CAPTURE.producer -> EVENTS`, or one of each: `CAPTURE.producer.top -> EVENTS`"
+        });
+        continue;
+      }
+      const held = partIsSide ? side : role;
+      if (held) {
+        diagnostics.push({
+          code: "E0227",
+          severity: "error",
+          message: `this endpoint already names ${partIsSide ? `the \`${held.value}\` side` : `the \`${held.value}\` role`}`,
+          span: part.span,
+          note: `\`${split.raw}\` names two ${partIsSide ? "attachment sides" : "roles"}, and only one can hold`,
+          help: partIsSide ? "keep one side \u2014 a side and a *role* do accumulate, e.g. `CAPTURE.producer.top`" : "keep one role \u2014 a role and a *side* do accumulate, e.g. `CAPTURE.producer.top`"
+        });
+        continue;
+      }
+      if (partIsSide) side = { value: part.text, span: part.span };
+      else role = { value: part.text, span: part.span };
+    }
+    const baseParts = split.parts.slice(0, cut);
+    const baseText = baseParts.map((part) => part.text).join(".");
+    const baseSpan = { line: split.rawSpan.line, col: split.rawSpan.col, len: baseText.length };
     if (split.end === "from") {
-      split.flow.from = split.base;
-      split.flow.fromSpan = split.baseSpan;
+      split.flow.from = baseText;
+      split.flow.fromSpan = baseSpan;
       split.flow.fromSide = side;
       split.flow.fromRole = role;
     } else {
-      split.flow.to = split.base;
-      split.flow.toSpan = split.baseSpan;
+      split.flow.to = baseText;
+      split.flow.toSpan = baseSpan;
       split.flow.toSide = side;
       split.flow.toRole = role;
     }
@@ -93229,9 +93265,9 @@ function readOffsetPair(p) {
     span: { line: dx.span.line, col: dx.span.col, len: dy.span.col + dy.span.len - dx.span.col }
   };
 }
-function tryOffsetEntry(p, parent) {
+function tryPairEntry(p, parent, entry, put) {
   const { matchToken, advance, reportCoded, save, restore, syncToNextLine } = p;
-  if (!parent || !matchToken("id", "offset")) return false;
+  if (!parent || !matchToken("id", entry.key)) return false;
   const mark = save();
   const keyToken = advance();
   if (!matchToken("colon")) {
@@ -93241,18 +93277,39 @@ function tryOffsetEntry(p, parent) {
   advance();
   const pair2 = readOffsetPair(p);
   if (!pair2) {
-    reportCoded(
-      "E0109",
-      "`offset` expects two whole numbers \u2014 `offset: <dx>, <dy>`",
-      keyToken.span,
-      "e.g. `offset: 40, -20` \u2014 40px right and 20px up from where the layout put it"
-    );
+    reportCoded(entry.code, entry.message, keyToken.span, entry.help);
     syncToNextLine();
     return true;
   }
-  parent.offset = pair2;
+  put(parent, pair2);
   return true;
 }
+var tryOffsetEntry = (p, parent) => tryPairEntry(
+  p,
+  parent,
+  {
+    key: "offset",
+    code: "E0109",
+    message: "`offset` expects two whole numbers \u2014 `offset: <dx>, <dy>`",
+    help: "e.g. `offset: 40, -20` \u2014 40px right and 20px up from where the layout put it"
+  },
+  (element, pair2) => {
+    element.offset = pair2;
+  }
+);
+var trySizeEntry = (p, parent) => tryPairEntry(
+  p,
+  parent,
+  {
+    key: "size",
+    code: "E0110",
+    message: "`size` expects two whole numbers \u2014 `size: <dw>, <dh>`",
+    help: "e.g. `size: 120, 40` \u2014 120px wider and 40px taller than the layout made it"
+  },
+  (element, pair2) => {
+    element.size = { dw: pair2.dx, dh: pair2.dy, span: pair2.span };
+  }
+);
 function tryLogoEntry(p, parent) {
   const { matchToken, advance, reportCoded, save, restore, syncToNextLine } = p;
   if (!parent || !matchToken("id", "logo")) return false;
@@ -93496,7 +93553,7 @@ function parse(src) {
     }
     if (tryStyleBlock(parent)) return;
     if (tryOrderEntry(parser, parent)) return;
-    if (tryOffsetEntry(parser, parent)) return;
+    if (tryOffsetEntry(parser, parent) || trySizeEntry(parser, parent)) return;
     if (tryLogoEntry(parser, parent)) return;
     if (!parent && tryLegendBlock(parser)) return;
     if (!parent && tryBusinessObject(parser)) return;
@@ -94648,6 +94705,7 @@ function validate(model) {
     ...checkNesting(elements, view),
     ...checkFlows(model, view),
     ...checkEndpointRoles(model, view),
+    ...checkSizes(elements, view),
     ...checkLogos(elements, view),
     ...checkBusinessObjects(model, view),
     ...checkMinimumCounts(elements, model, view),
@@ -94690,6 +94748,31 @@ function checkUnknownKinds(elements, view) {
   }
   return diagnostics;
 }
+function checkSizes(elements, view) {
+  const diagnostics = [];
+  for (const element of elements) {
+    if (!element.size) continue;
+    if (!view.containerKinds.includes(element.kind))
+      diagnostics.push({
+        code: "E0226",
+        severity: "error",
+        message: `\`${element.kind}\` is not a container, so it has no \`size\` to give`,
+        span: element.size.span,
+        note: `the \`${view.name}\` view accepts \`size\` on: ${view.containerKinds.join(", ")}`,
+        help: "a leaf box is sized by its own label \u2014 set `label-padding:` in `style` to change how tightly, or nudge this one with `offset:`"
+      });
+    else if (!element.children.length)
+      diagnostics.push({
+        code: "E0226",
+        severity: "error",
+        message: `\`${element.id}\` holds nothing, so it is drawn as a plain box rather than a container`,
+        span: element.size.span,
+        note: "a container's size is the room around what it holds \u2014 with no children there is no room to give",
+        help: "put the elements it contains inside it, or drop the `size:` and nudge this one with `offset:`"
+      });
+  }
+  return diagnostics;
+}
 function checkLogos(elements, view) {
   const diagnostics = [];
   const logoKinds = view.logoKinds ?? [];
@@ -98089,6 +98172,58 @@ function applySwap(scene, pair2, swap, leaves) {
     return true;
   }
 }
+function straightenCarriedRuns(scene, titleBoxes, only) {
+  if (!only.size) return;
+  const leaves = scene.nodes.filter((node) => !node.container);
+  if (!leaves.length) return;
+  const ctx = createTidyContext(scene, leaves, titleBoxes, false);
+  const strikesTitle = (at, from, to, horizontal) => {
+    const lo = Math.min(from, to);
+    const hi = Math.max(from, to);
+    return titleBoxes.some(
+      (band) => horizontal ? at > band.y && at < band.y + band.height && lo < band.x + band.width && hi > band.x : at > band.x && at < band.x + band.width && lo < band.y + band.height && hi > band.y
+    );
+  };
+  const taken = (seat, mine) => scene.edges.some(
+    (other) => other !== mine && other.pts.length >= 2 && [other.pts[0], other.pts[other.pts.length - 1]].some(
+      (end) => Math.abs(end.x - seat.x) < MIN_ATTACH_GAP && Math.abs(end.y - seat.y) < MIN_ATTACH_GAP
+    )
+  );
+  for (const edge of scene.edges) {
+    if (!only.has(edge.id) || edge.pts.length < 3) continue;
+    if (edge.pinned?.start || edge.pinned?.end) continue;
+    const src = sideOf(edge.pts[0], leaves);
+    const dst = sideOf(edge.pts[edge.pts.length - 1], leaves);
+    if (!src || !dst || src.node === dst.node) continue;
+    const alongY = src.side === "east" || src.side === "west";
+    const rightwards = dst.node.x > src.node.x;
+    const downwards = dst.node.y > src.node.y;
+    const srcSide = alongY ? rightwards ? "east" : "west" : downwards ? "south" : "north";
+    const dstSide = alongY ? rightwards ? "west" : "east" : downwards ? "north" : "south";
+    const span = (node) => alongY ? [node.y + MIN_SIDE_INSET, node.y + node.height - MIN_SIDE_INSET] : [node.x + MIN_SIDE_INSET, node.x + node.width - MIN_SIDE_INSET];
+    const [srcLo, srcHi] = span(src.node);
+    const [dstLo, dstHi] = span(dst.node);
+    const low = Math.max(srcLo, dstLo);
+    const high = Math.min(srcHi, dstHi);
+    if (low > high) continue;
+    const at = Math.round((low + high) / 2);
+    const seatOnFace = (node, side) => side === "north" ? { x: at, y: node.y } : side === "south" ? { x: at, y: node.y + node.height } : side === "west" ? { x: node.x, y: at } : { x: node.x + node.width, y: at };
+    const from = seatOnFace(src.node, srcSide);
+    const to = seatOnFace(dst.node, dstSide);
+    const travel = alongY ? to.x - from.x : to.y - from.y;
+    const outward = (side) => side === "east" || side === "south" ? 1 : -1;
+    if (travel === 0 || Math.sign(travel) !== outward(srcSide)) continue;
+    const lane = alongY ? [from.x, to.x] : [from.y, to.y];
+    const runFrom = Math.min(lane[0], lane[1]);
+    const runTo = Math.max(lane[0], lane[1]);
+    if (ctx.runHitsNode(!alongY, at, runFrom, runTo)) continue;
+    if (strikesTitle(at, runFrom, runTo, alongY)) continue;
+    const others = ctx.runsExcept(edge.id);
+    if (!ctx.runIsClear(alongY ? others.horizontal : others.vertical, at, runFrom, runTo)) continue;
+    if (taken(from, edge) || taken(to, edge)) continue;
+    edge.pts = [from, to];
+  }
+}
 function swapCrossingSiblingSeats(scene) {
   const leaves = scene.nodes.filter((node) => !node.container);
   const endsOf = (edge) => [
@@ -100712,7 +100847,178 @@ function stampLabelOffsets(edges, model) {
     for (const label of edge.labels) label.offset = { dx: declared.dx, dy: declared.dy };
   }
 }
+var ON_BORDER = 1;
 var pointOn = (point, box) => point.x >= box.x - 1 && point.x <= box.x + box.width + 1 && point.y >= box.y - 1 && point.y <= box.y + box.height + 1;
+function containerSizeBounds(scene, model) {
+  const nodeById = new Map(scene.nodes.map((node) => [node.id, node]));
+  const pad = containerPad(model);
+  const bounds = /* @__PURE__ */ new Map();
+  const walk = (elements) => {
+    for (const element of elements) {
+      walk(element.children);
+      const node = nodeById.get(element.id);
+      if (node?.container) bounds.set(element.id, contentFloor({ node, element, nodeById, pad }));
+    }
+  };
+  walk(model.elements);
+  return bounds;
+}
+var containerPad = (model) => model.style.containerPadding ?? (model.style.compact ? 7 : 9);
+var MIN_SIBLING_GAP = 20;
+var kidsOf = (box) => box.element.children.map((child) => box.nodeById.get(child.id)).filter((child) => !!child);
+function freeBands(box, axis) {
+  const { node, pad } = box;
+  const { min, size } = AXIS[axis];
+  const spans = kidsOf(box).map((kid) => ({ start: kid[min], end: kid[min] + kid[size] })).sort((a, b) => a.start - b.start || a.end - b.end);
+  const merged = [];
+  for (const span of spans) {
+    const last = merged[merged.length - 1];
+    if (last && span.start <= last.end) last.end = Math.max(last.end, span.end);
+    else merged.push({ ...span });
+  }
+  if (!merged.length) return [];
+  const bands = [];
+  const add = (start, end, keep) => {
+    if (end - start > keep) bands.push({ end, spare: end - start - keep });
+  };
+  add(node[min], merged[0].start, pad);
+  for (let i = 0; i + 1 < merged.length; i++)
+    add(merged[i].end, merged[i + 1].start, MIN_SIBLING_GAP);
+  add(merged[merged.length - 1].end, node[min] + node[size], pad);
+  return bands;
+}
+var AXIS = {
+  x: { min: "x", size: "width" },
+  y: { min: "y", size: "height" }
+};
+function holdsChildren(box) {
+  const { node, pad } = box;
+  const kids = kidsOf(box);
+  if (!kids.length) return { minWidth: pad * 2, minHeight: pad * 2 };
+  return {
+    minWidth: Math.max(...kids.map((kid) => kid.x + kid.width)) + pad - node.x,
+    minHeight: Math.max(...kids.map((kid) => kid.y + kid.height)) + pad - node.y
+  };
+}
+function contentFloor(box) {
+  const spare = (axis) => freeBands(box, axis).reduce((total, band) => total + band.spare, 0);
+  return { minWidth: box.node.width - spare("x"), minHeight: box.node.height - spare("y") };
+}
+function squeezeInside(box, axis, target) {
+  const { min, size } = AXIS[axis];
+  const need = box.node[size] - target;
+  if (need <= 0) return;
+  const bands = freeBands(box, axis);
+  const spare = bands.reduce((total, band) => total + band.spare, 0);
+  if (spare <= 0) return;
+  const share = Math.min(1, need / spare);
+  const shiftAt = (at) => bands.reduce((total, band) => at >= band.end ? total + band.spare * share : total, 0);
+  for (const child of box.element.children) {
+    const kid = box.nodeById.get(child.id);
+    if (!kid) continue;
+    const shift = shiftAt(kid[min]);
+    if (!shift) continue;
+    for (const id of subtreeIds(child)) {
+      const inside = box.nodeById.get(id);
+      if (inside) inside[min] -= shift;
+    }
+  }
+}
+function applyContainerSizes(scene, model) {
+  const carried = /* @__PURE__ */ new Set();
+  const wanted = /* @__PURE__ */ new Map();
+  const walk = (elements) => {
+    for (const element of elements) {
+      walk(element.children);
+      if (element.size) wanted.set(element.id, element.size);
+    }
+  };
+  walk(model.elements);
+  if (!wanted.size) return carried;
+  const nodeById = new Map(scene.nodes.map((node) => [node.id, node]));
+  const pad = containerPad(model);
+  const clampedSpans = /* @__PURE__ */ new Set();
+  const applied = /* @__PURE__ */ new Map();
+  const before = new Map(
+    scene.nodes.map((node) => [
+      node.id,
+      { x: node.x, y: node.y, width: node.width, height: node.height }
+    ])
+  );
+  for (const [id, spec] of wanted) {
+    const node = nodeById.get(id);
+    const element = model.index.get(id);
+    if (!node || !element) continue;
+    const box = { node, element, nodeById, pad };
+    const floor = contentFloor(box);
+    const width = Math.max(node.width + spec.dw, floor.minWidth);
+    const height = Math.max(node.height + spec.dh, floor.minHeight);
+    if (width !== node.width + spec.dw || height !== node.height + spec.dh)
+      clampedSpans.add(spec.span);
+    squeezeInside(box, "x", width);
+    squeezeInside(box, "y", height);
+    node.width = width;
+    node.height = height;
+  }
+  const containWithin = (elements) => {
+    for (const element of elements) {
+      containWithin(element.children);
+      const node = nodeById.get(element.id);
+      if (!node?.container) continue;
+      const holds = holdsChildren({ node, element, nodeById, pad });
+      node.width = Math.max(node.width, holds.minWidth);
+      node.height = Math.max(node.height, holds.minHeight);
+    }
+  };
+  containWithin(model.elements);
+  for (const id of wanted.keys()) {
+    const node = nodeById.get(id);
+    const was = before.get(id);
+    if (node && was)
+      applied.set(id, { dw: node.width - was.width, dh: node.height - was.height });
+  }
+  if (clampedSpans.size) scene.clampedSizes = clampedSpans;
+  scene.appliedSizes = applied;
+  const seats = [];
+  for (const node of scene.nodes) {
+    const was = before.get(node.id);
+    if (!was) continue;
+    const moved = {
+      dx: node.x - was.x,
+      dy: node.y - was.y,
+      dw: node.width - was.width,
+      dh: node.height - was.height
+    };
+    if (!moved.dx && !moved.dy && !moved.dw && !moved.dh) continue;
+    seats.push({ box: was, ...moved });
+  }
+  seats.sort((a, b) => a.box.width * a.box.height - b.box.width * b.box.height);
+  if (!seats.length) return carried;
+  for (const edge of scene.edges) {
+    if (edge.pts.length < 2) continue;
+    for (const which of ["first", "last"]) {
+      const terminal = edge.pts[which === "first" ? 0 : edge.pts.length - 1];
+      const seat = seats.find((candidate) => pointOn(terminal, candidate.box));
+      if (!seat) continue;
+      const onRight = terminal.x >= seat.box.x + seat.box.width - ON_BORDER;
+      const onBottom = terminal.y >= seat.box.y + seat.box.height - ON_BORDER;
+      const delta = {
+        dx: seat.dx + (onRight ? seat.dw : 0),
+        dy: seat.dy + (onBottom ? seat.dh : 0)
+      };
+      if (!delta.dx && !delta.dy) continue;
+      carried.add(edge.id);
+      carryTerminal(edge, which, delta, {
+        x: seat.box.x + seat.dx,
+        y: seat.box.y + seat.dy,
+        width: seat.box.width + seat.dw,
+        height: seat.box.height + seat.dh
+      });
+    }
+  }
+  for (const edge of scene.edges) if (carried.has(edge.id)) dropRedundantPoints(edge.pts);
+  return carried;
+}
 function applyNodeOffsets(scene, offsetOf) {
   const carried = /* @__PURE__ */ new Set();
   if (!offsetOf.size) return carried;
@@ -100777,19 +101083,36 @@ function applyNodeOffsets(scene, offsetOf) {
       const seat = seats.find((candidate) => pointOn(terminal, candidate.box));
       if (!seat || !seat.delta.dx && !seat.delta.dy) continue;
       carried.add(edge.id);
-      const neighbourIndex = end === 0 ? 1 : edge.pts.length - 2;
-      const neighbour = edge.pts[neighbourIndex];
-      const wasHorizontal = Math.abs(terminal.y - neighbour.y) < 0.5;
-      terminal.x += seat.delta.dx;
-      terminal.y += seat.delta.dy;
-      const elbow = wasHorizontal ? { x: neighbour.x, y: terminal.y } : { x: terminal.x, y: neighbour.y };
-      const degenerate = Math.abs(elbow.x - terminal.x) < 0.5 && Math.abs(elbow.y - terminal.y) < 0.5 || Math.abs(elbow.x - neighbour.x) < 0.5 && Math.abs(elbow.y - neighbour.y) < 0.5;
-      if (!degenerate) edge.pts.splice(end === 0 ? 1 : edge.pts.length - 1, 0, elbow);
+      carryTerminal(edge, end === 0 ? "first" : "last", seat.delta, {
+        x: seat.box.x + seat.delta.dx,
+        y: seat.box.y + seat.delta.dy,
+        width: seat.box.width,
+        height: seat.box.height
+      });
     }
   }
   for (const edge of scene.edges) if (carried.has(edge.id)) dropRedundantPoints(edge.pts);
   return carried;
 }
+function carryTerminal(edge, which, delta, face) {
+  const end = which === "first" ? 0 : edge.pts.length - 1;
+  const terminal = edge.pts[end];
+  const neighbour = edge.pts[which === "first" ? 1 : edge.pts.length - 2];
+  const wasHorizontal = Math.abs(terminal.y - neighbour.y) < SEGMENT_EPSILON;
+  terminal.x += delta.dx;
+  terminal.y += delta.dy;
+  const slide = wasHorizontal ? { along: "y", low: face.y, high: face.y + face.height } : { along: "x", low: face.x, high: face.x + face.width };
+  const residual = neighbour[slide.along] - terminal[slide.along];
+  const seat = Math.min(
+    Math.max(neighbour[slide.along], slide.low + SEAT_INSET),
+    Math.max(slide.high - SEAT_INSET, slide.low + SEAT_INSET)
+  );
+  if (Math.abs(residual) < ARROW_ROOM2 && Math.abs(seat - neighbour[slide.along]) < SEGMENT_EPSILON)
+    terminal[slide.along] = seat;
+  const elbow = wasHorizontal ? { x: neighbour.x, y: terminal.y } : { x: terminal.x, y: neighbour.y };
+  const degenerate = Math.abs(elbow.x - terminal.x) < SEGMENT_EPSILON && Math.abs(elbow.y - terminal.y) < SEGMENT_EPSILON || Math.abs(elbow.x - neighbour.x) < SEGMENT_EPSILON && Math.abs(elbow.y - neighbour.y) < SEGMENT_EPSILON;
+  if (!degenerate) edge.pts.splice(which === "first" ? 1 : edge.pts.length - 1, 0, elbow);
+}
 function dropRedundantPoints(pts) {
   const inLine = (a, b, c) => Math.abs(a.x - b.x) < SEGMENT_EPSILON && Math.abs(b.x - c.x) < SEGMENT_EPSILON || Math.abs(a.y - b.y) < SEGMENT_EPSILON && Math.abs(b.y - c.y) < SEGMENT_EPSILON;
   for (let i = pts.length - 2; i >= 1; i--)
@@ -100919,6 +101242,37 @@ function shiftIntoCanvas(scene) {
   scene.width += shiftX;
   scene.height += shiftY;
 }
+function sizeOverlaps(scene, model, overlap) {
+  const sized = /* @__PURE__ */ new Map();
+  for (const element of model.index.values())
+    if (element.size) sized.set(element.id, element.size.span);
+  if (!sized.size) return [];
+  const family = /* @__PURE__ */ new Map();
+  const walk = (elements, ancestors) => {
+    for (const element of elements) {
+      if (sized.has(element.id))
+        family.set(element.id, /* @__PURE__ */ new Set([...ancestors, ...subtreeIds(element)]));
+      walk(element.children, [...ancestors, element.id]);
+    }
+  };
+  walk(model.elements, []);
+  const diagnostics = [];
+  for (const node of scene.nodes) {
+    const span = sized.get(node.id);
+    if (!span) continue;
+    const kin = family.get(node.id);
+    const struck = scene.nodes.find((other) => !kin.has(other.id) && overlap(node, other));
+    if (!struck) continue;
+    diagnostics.push({
+      code: "W0572",
+      severity: "warning",
+      message: `\`size\` on \`${node.id}\` overlaps \`${struck.id}\``,
+      span,
+      help: "the resize is applied as written \u2014 make it smaller, or give the drawing room with `order:`"
+    });
+  }
+  return diagnostics;
+}
 function offsetDiagnostics(scene, model) {
   const hints = [];
   for (const span of scene.segmentHints?.stale ?? [])
@@ -100937,6 +101291,14 @@ function offsetDiagnostics(scene, model) {
       span,
       help: "the run carries a terminal, so it can only slide as far as the side that terminal sits on \u2014 pin the side with `ID.side`, or move the element instead"
     });
+  for (const span of scene.clampedSizes ?? [])
+    hints.push({
+      code: "W0575",
+      severity: "warning",
+      message: "`size` was limited to keep this container around its own children",
+      span,
+      help: "a container is drawn around what it holds, which is not negotiable \u2014 resize or move the children first if the box has to be smaller"
+    });
   const spans = /* @__PURE__ */ new Map();
   const walk = (elements, inherited) => {
     for (const element of elements) {
@@ -100947,8 +101309,9 @@ function offsetDiagnostics(scene, model) {
   };
   walk(model.elements);
   for (const flow of model.flows) if (flow.labelOffset) spans.set(flow.id, flow.labelOffset.span);
-  if (!spans.size) return hints;
   const overlap = (a, b) => a.x < b.x + b.width && b.x < a.x + a.width && a.y < b.y + b.height && b.y < a.y + a.height;
+  hints.push(...sizeOverlaps(scene, model, overlap));
+  if (!spans.size) return hints;
   const leaves = scene.nodes.filter((node) => !node.container);
   const labels = scene.edges.flatMap((edge) => edge.labels);
   const diagnostics = [...hints];
@@ -101426,9 +101789,11 @@ function refuseScenicRepairs(scene, before) {
   }
 }
 function applyAuthorPositioning(scene, model) {
+  const runsBefore = new Map(scene.edges.map((edge) => [edge.id, straightRuns(edge.pts).length]));
+  const resized = applyContainerSizes(scene, model);
   const offsets = offsetAssignment(model);
-  if (offsets.size) {
-    const carried = applyNodeOffsets(scene, offsets);
+  if (offsets.size || resized.size) {
+    const carried = /* @__PURE__ */ new Set([...resized, ...applyNodeOffsets(scene, offsets)]);
     for (const edge of scene.edges) if (carried.has(edge.id)) edge.repairedFrom = void 0;
     const titles = titleBoxesOf(scene, model);
     reaimAfterOffsets(scene, titles, carried);
@@ -101444,6 +101809,12 @@ function applyAuthorPositioning(scene, model) {
       refuseScenicRepairs(scene, before);
       decoincideAfterOffsets(scene, titles, repairable);
     }
+    const bent = new Set(
+      scene.edges.filter(
+        (edge) => carried.has(edge.id) && straightRuns(edge.pts).length > (runsBefore.get(edge.id) ?? 0)
+      ).map((edge) => edge.id)
+    );
+    straightenCarriedRuns(scene, titles, bent);
   }
   const nudgedRuns = applySegmentOffsets(scene, model);
   if (nudgedRuns) {
@@ -101452,7 +101823,7 @@ function applyAuthorPositioning(scene, model) {
         edge.repairedFrom = void 0;
   }
   const nudgedLabels = scene.edges.some((edge) => edge.labels.some((label) => label.offset));
-  if (!offsets.size && !nudgedRuns && !nudgedLabels) return;
+  if (!offsets.size && !resized.size && !nudgedRuns && !nudgedLabels) return;
   anchorFlowLabels(scene, titleBoxesOf(scene, model));
   fitCanvas(scene);
 }
@@ -103076,6 +103447,7 @@ function layoutBoxes(model, scene) {
       declarations.set(element.id, {
         line: element.kindSpan.line,
         offsetSpan: element.offset?.span,
+        sizeSpan: element.size?.span,
         parent
       });
       walk(element.children, element.id);
@@ -103083,6 +103455,7 @@ function layoutBoxes(model, scene) {
   };
   walk(model.elements);
   const flowById = new Map(model.flows.map((flow) => [flow.id, flow]));
+  const sizeBounds = containerSizeBounds(scene, model);
   const boxes = [];
   const leaves = scene.nodes.filter((node) => !node.container);
   for (const node of scene.nodes) {
@@ -103096,6 +103469,8 @@ function layoutBoxes(model, scene) {
       width: node.width,
       height: node.height,
       container: node.container,
+      resize: sizeBounds.get(node.id),
+      sizeApplied: scene.appliedSizes?.get(node.id),
       ...declaration
     });
   }
@@ -103161,7 +103536,7 @@ function layoutBoxes(model, scene) {
 }
 
 // src/api.ts
-var version = true ? "1.0.0-RC17" : pkg.version;
+var version = true ? "1.0.0-RC18" : pkg.version;
 
 // src/playground.ts
 var ElkClass = import_elk_bundled.default;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@r0kshan/cairn",
-  "version": "1.0.0-RC17",
+  "version": "1.0.0-RC18",
   "description": "Architecture diagrams as code — typed views, semantic layout, no label overlap",
   "license": "Apache-2.0",
   "homepage": "https://github.com/R0kshan/cairn#readme",