@uipath/maestro-builder-sdk 6.66.4 → 6.66.6

package/dist/merge.d.ts

@@ -18,7 +18,8 @@
  *     what a faithful round-trip of the original produces. When a node in
  *     `edited` is byte-equal to its `baseline` counterpart, the user did NOT
  *     touch it, so the merge keeps the ORIGINAL node verbatim (its real type,
- *     inputs, layout — even for a placeholder). Only nodes the user actually
+ *     inputs, layout — even for a placeholder; its position moves only to make
+ *     room for an added node, see node-placement.ts). Only nodes the user actually
  *     changed (or added) are taken from `edited`, and a changed node takes only
  *     the fields that differ from the baseline (see withEdits).
  *   - Without a `baseline`, the merge is two-way: it takes `edited`'s graph and
@@ -27,7 +28,8 @@
  *
  * Layout, `metadata`, `solutionId`, `projectId`, `runtime` and `layout` are
  * preserved from the original, apart from the `layout.nodes` entries of
- * removed nodes (dropped) and added nodes (node-placement.ts); `subflows` and
+ * removed nodes (dropped) and added nodes, and the positions and container
+ * sizes placement moves to make room for them (node-placement.ts); `subflows` and
  * edges (with their ids) come from `edited`; root `variables` merge as a
  * delta per entry, like nodes (merge-variables.ts); `definitions` and
  * `bindings` are unioned

package/dist/merge.js

@@ -18,7 +18,8 @@
  *     what a faithful round-trip of the original produces. When a node in
  *     `edited` is byte-equal to its `baseline` counterpart, the user did NOT
  *     touch it, so the merge keeps the ORIGINAL node verbatim (its real type,
- *     inputs, layout — even for a placeholder). Only nodes the user actually
+ *     inputs, layout — even for a placeholder; its position moves only to make
+ *     room for an added node, see node-placement.ts). Only nodes the user actually
  *     changed (or added) are taken from `edited`, and a changed node takes only
  *     the fields that differ from the baseline (see withEdits).
  *   - Without a `baseline`, the merge is two-way: it takes `edited`'s graph and
@@ -27,7 +28,8 @@
  *
  * Layout, `metadata`, `solutionId`, `projectId`, `runtime` and `layout` are
  * preserved from the original, apart from the `layout.nodes` entries of
- * removed nodes (dropped) and added nodes (node-placement.ts); `subflows` and
+ * removed nodes (dropped) and added nodes, and the positions and container
+ * sizes placement moves to make room for them (node-placement.ts); `subflows` and
  * edges (with their ids) come from `edited`; root `variables` merge as a
  * delta per entry, like nodes (merge-variables.ts); `definitions` and
  * `bindings` are unioned
@@ -432,8 +434,9 @@ function mergeFlowFindings(original, edited, options) {
     // ── Placement: a node the edit ADDED has no original position. Unless the
     //    author set one, it has compile's placeholder, an emission-index slot
     //    that can land on an original node. Put it next to its predecessor,
-    //    collision-free, and store every added node's position where the
-    //    original stores positions — see node-placement.ts. Root scope only: a
+    //    moving the nodes downstream of it and growing its containers to make
+    //    room, and store every added node's position where the original stores
+    //    positions — see node-placement.ts. Root scope only: a
     //    subflow is taken from `edited` whole, layout included. ──
     placeAddedNodes(finalNodes, result.edges, positionStoreOf(original) && layoutNodesOf(result), (id) => !origNodes.has(id));
     // ── Definitions: the (type, version) pairs used by EVERY node in the file —
@@ -458,7 +461,7 @@ function mergeFlowFindings(original, edited, options) {
     // metadata / solutionId / projectId / layout / runtime were carried by the
     // initial clone of `original` and are intentionally left untouched, apart
     // from the `layout.nodes` entries of removed nodes (dropped above) and added
-    // nodes (placement).
+    // nodes, and the positions and container sizes placement moves to make room.
     //
     // The declared file-format `version` follows the same delta rule the nodes
     // do. The original's wins by default, because a compile of an edited source

package/dist/node-placement.d.ts

@@ -6,15 +6,34 @@
  * `x = 256 + 288 × index, y = 144` (`+160` inside a container). Merge replaces
  * that placeholder on each node the edit added:
  *
- * - next to a positioned predecessor in the same container: one slot right;
+ * - right of its rightmost positioned predecessor in the same container, past
+ *   its width, on that predecessor's row; when the node leads into another
+ *   lane (its first successor's row does not meet the predecessor's) and that
+ *   successor is no join another lane already feeds, on that lane's row; when
+ *   its direct successor is tucked under the predecessor (a context index
+ *   under its agent), in that successor's spot, pushing it a slot;
  * - else, when the incoming edge comes from the node's own container (the first
  *   node of a loop body): at the body origin, inside the container's padding;
- * - else, one slot left of a positioned successor in the same container;
- * - then the nearest free spot around that candidate.
+ * - else, one slot left of a positioned successor in the same container, or in
+ *   its place when that is taken.
+ *
+ * A new branch whose spot holds another new branch out of the same
+ * predecessor takes the next row down instead of pushing it. A sticky note
+ * moves with the node it covers most (by id on a tie); one over no node stays.
+ *
+ * Added nodes are placed in waves by id, each node once every predecessor it
+ * has in its container is placed, so the result does not depend on the order
+ * of the node or edge arrays, and a join lands right of all its branches.
+ *
+ * When the spot is taken, or a successor would sit left of the new node, the
+ * nodes downstream of the new one, the ones it lands on, and whatever they
+ * would land on move right to make room; when one of them has to stay, the
+ * new node takes the nearest free spot instead. Each container that gained or
+ * moved a child then grows to fit it, and pushes what is past its old edges.
  *
  * Example: the edit inserts `auditLog` between `extractInvoice (448,144)` and
- * `routeInvoice (640,144)`. The candidate `(640,144)` is taken, so `auditLog`
- * goes to the first free spot, `(640,264)`.
+ * `routeInvoice (640,144)`. `auditLog` takes `(640,144)`; `routeInvoice` and
+ * `end` move 192 right.
  *
  * A child's position is relative to its container, as on the canvas.
  *
@@ -66,21 +85,32 @@ interface PlacedNode {
     [k: string]: unknown;
 }
 /**
- * Give each node the edit added a position next to its predecessor, in place.
+ * Give each node the edit added a position next to its predecessor, in place,
+ * making room for it.
  *
  * A node is placed when it is not in the original and its position is a
- * compile placeholder (an author `.layout()` position is kept). Its candidate,
- * in order: one slot right of the first predecessor in the same container that
- * already has a position (an original node, or an added node placed before it);
- * the body origin, when an edge enters it from its own container; one slot left
- * of a positioned successor in the same container. With none, the node keeps
- * its placeholder, and placed nodes avoid it.
+ * compile placeholder; the module header lists where it goes. When the spot is
+ * taken, or one of its first positioned successors would sit left of its
+ * right edge, the nodes past the insertion point that it lands on, and every
+ * node downstream of the new one, move right by the room it needs; so does
+ * whatever a moved node would then land on, and its downstream. Downstream
+ * reaches through added nodes not placed yet. When that would move a node that
+ * has to stay (an author position, an added node that can never be anchored),
+ * nothing moves and the node takes the nearest free spot. Then each container
+ * that gained or moved a child grows as far as those children need, keeping
+ * its padding, and pushes the siblings past its old right or bottom edge the
+ * same way, up to the root, keeping at least the row gap to its new edge.
+ *
+ * An author `.layout()` position is kept when a node is placed, but a growing
+ * container moves one in its way or downstream of it past its old edge (it
+ * was chosen against the old size), so growth never covers a node.
  *
  * Where the result is written follows the file: when the original stores
  * positions in `layout.nodes` (every canvas-saved file does), every added
  * node's `node.ui`, placed or not, sticky notes included, replaces its
  * `layout.nodes` entry, so the node has one position; otherwise
- * `node.ui.position` is updated.
+ * `node.ui.position` is updated. A moved or grown node keeps each field
+ * where it already is.
  *
  * @param nodes - The merged root nodes (mutated).
  * @param edges - The merged root edges.

package/dist/node-placement.js

@@ -6,15 +6,34 @@
  * `x = 256 + 288 × index, y = 144` (`+160` inside a container). Merge replaces
  * that placeholder on each node the edit added:
  *
- * - next to a positioned predecessor in the same container: one slot right;
+ * - right of its rightmost positioned predecessor in the same container, past
+ *   its width, on that predecessor's row; when the node leads into another
+ *   lane (its first successor's row does not meet the predecessor's) and that
+ *   successor is no join another lane already feeds, on that lane's row; when
+ *   its direct successor is tucked under the predecessor (a context index
+ *   under its agent), in that successor's spot, pushing it a slot;
  * - else, when the incoming edge comes from the node's own container (the first
  *   node of a loop body): at the body origin, inside the container's padding;
- * - else, one slot left of a positioned successor in the same container;
- * - then the nearest free spot around that candidate.
+ * - else, one slot left of a positioned successor in the same container, or in
+ *   its place when that is taken.
+ *
+ * A new branch whose spot holds another new branch out of the same
+ * predecessor takes the next row down instead of pushing it. A sticky note
+ * moves with the node it covers most (by id on a tie); one over no node stays.
+ *
+ * Added nodes are placed in waves by id, each node once every predecessor it
+ * has in its container is placed, so the result does not depend on the order
+ * of the node or edge arrays, and a join lands right of all its branches.
+ *
+ * When the spot is taken, or a successor would sit left of the new node, the
+ * nodes downstream of the new one, the ones it lands on, and whatever they
+ * would land on move right to make room; when one of them has to stay, the
+ * new node takes the nearest free spot instead. Each container that gained or
+ * moved a child then grows to fit it, and pushes what is past its old edges.
  *
  * Example: the edit inserts `auditLog` between `extractInvoice (448,144)` and
- * `routeInvoice (640,144)`. The candidate `(640,144)` is taken, so `auditLog`
- * goes to the first free spot, `(640,264)`.
+ * `routeInvoice (640,144)`. `auditLog` takes `(640,144)`; `routeInvoice` and
+ * `end` move 192 right.
  *
  * A child's position is relative to its container, as on the canvas.
  *
@@ -37,6 +56,10 @@ const PLACEHOLDER = { x0: 256, dx: 288, y0: 144, nestedDy: 160 };
 const DEFAULT_SIZE = 96;
 /** One slot to the right of a node: its width plus an equal gap, the spacing of a canvas row. */
 const SLOT_DX = 192;
+/** The space between two nodes in a canvas row. */
+const GAP = SLOT_DX - DEFAULT_SIZE;
+/** The box a container with no size gets (flow-core's container default). */
+const CONTAINER_SIZE = { width: 560, height: 320 };
 /** flow-core `findFreePosition` defaults. */
 const PADDING = 24;
 const STEP = 40;
@@ -69,6 +92,8 @@ export function isPlaceholderPosition(p) {
 }
 const overlaps = (a, b) => !(a.x + a.width + PADDING <= b.x || b.x + b.width + PADDING <= a.x
     || a.y + a.height + PADDING <= b.y || b.y + b.height + PADDING <= a.y);
+/** Whether two boxes share a row: their vertical extents meet, padding included. */
+const rowsMeet = (a, b) => a.y < b.y + b.height + PADDING && b.y < a.y + a.height + PADDING;
 /** flow-core `findFreePosition`: the candidate, else the first free spot on rings around it. */
 function findFreePosition(candidate, size, others) {
     const free = (p) => !others.some((o) => overlaps({ ...p, ...size }, o));
@@ -98,22 +123,41 @@ function moveAddedUi(nodes, layoutNodes, isAdded) {
         delete n.ui;
     }
 }
+/** What a push does when a moved node would land on one it may not move. */
+var Blocked;
+(function (Blocked) {
+    /** The push is called off: nothing moves. */
+    Blocked[Blocked["Refuse"] = 0] = "Refuse";
+    /** That node moves too. */
+    Blocked[Blocked["Push"] = 1] = "Push";
+})(Blocked || (Blocked = {}));
 /**
- * Give each node the edit added a position next to its predecessor, in place.
+ * Give each node the edit added a position next to its predecessor, in place,
+ * making room for it.
  *
  * A node is placed when it is not in the original and its position is a
- * compile placeholder (an author `.layout()` position is kept). Its candidate,
- * in order: one slot right of the first predecessor in the same container that
- * already has a position (an original node, or an added node placed before it);
- * the body origin, when an edge enters it from its own container; one slot left
- * of a positioned successor in the same container. With none, the node keeps
- * its placeholder, and placed nodes avoid it.
+ * compile placeholder; the module header lists where it goes. When the spot is
+ * taken, or one of its first positioned successors would sit left of its
+ * right edge, the nodes past the insertion point that it lands on, and every
+ * node downstream of the new one, move right by the room it needs; so does
+ * whatever a moved node would then land on, and its downstream. Downstream
+ * reaches through added nodes not placed yet. When that would move a node that
+ * has to stay (an author position, an added node that can never be anchored),
+ * nothing moves and the node takes the nearest free spot. Then each container
+ * that gained or moved a child grows as far as those children need, keeping
+ * its padding, and pushes the siblings past its old right or bottom edge the
+ * same way, up to the root, keeping at least the row gap to its new edge.
+ *
+ * An author `.layout()` position is kept when a node is placed, but a growing
+ * container moves one in its way or downstream of it past its old edge (it
+ * was chosen against the old size), so growth never covers a node.
  *
  * Where the result is written follows the file: when the original stores
  * positions in `layout.nodes` (every canvas-saved file does), every added
  * node's `node.ui`, placed or not, sticky notes included, replaces its
  * `layout.nodes` entry, so the node has one position; otherwise
- * `node.ui.position` is updated.
+ * `node.ui.position` is updated. A moved or grown node keeps each field
+ * where it already is.
  *
  * @param nodes - The merged root nodes (mutated).
  * @param edges - The merged root edges.
@@ -123,56 +167,441 @@ function moveAddedUi(nodes, layoutNodes, isAdded) {
 export function placeAddedNodes(nodes, edges, layoutNodes, isAdded) {
     if (layoutNodes)
         moveAddedUi(nodes, layoutNodes, isAdded);
+    const s = sceneOf(nodes, edges, layoutNodes, isAdded);
+    const before = new Map([...s.containers].map((id) => [id, bodyExtent(s, id, (o) => !isAdded(o.id))]));
+    placeInWaves(s);
+    fitContainers(s, before);
+}
+function sceneOf(nodes, edges, layoutNodes, isAdded) {
     const byId = new Map(nodes.map((n) => [n.id, n]));
-    const uiOf = (n) => {
-        const entry = layoutNodes?.[n.id];
+    const outOf = new Map();
+    const inOf = new Map();
+    for (const e of edges) {
+        if (!outOf.has(e.sourceNodeId))
+            outOf.set(e.sourceNodeId, []);
+        if (!inOf.has(e.targetNodeId))
+            inOf.set(e.targetNodeId, []);
+        outOf.get(e.sourceNodeId).push(e.targetNodeId);
+        inOf.get(e.targetNodeId).push(e.sourceNodeId);
+    }
+    const s = {
+        nodes,
+        byId,
+        layoutNodes,
+        isAdded,
+        containers: new Set(nodes.flatMap((n) => (n.parentId !== undefined && byId.has(n.parentId) ? [n.parentId] : []))),
+        outOf,
+        inOf,
+        pending: new Set(),
+        placed: new Set(),
+        anchored: new Set(),
+        toFit: new Set(),
+        notesOf: new Map(),
+    };
+    for (const n of nodes) {
+        if (isAdded(n.id) && n.type !== STICKY_NOTE_TYPE && isPlaceholderPosition(uiOf(s, n)?.position))
+            s.pending.add(n.id);
+    }
+    // A pending node no edge path links to a positioned one in its container
+    // (or to the container's entry) is never placed: it keeps its placeholder,
+    // and nothing may land on it.
+    const reach = [...nodes.filter((n) => isPositioned(s, n.id)).map((n) => n.id),
+        ...[...s.pending].filter((id) => enteredFromContainer(s, id))];
+    for (const id of reach)
+        s.anchored.add(id);
+    for (let i = 0; i < reach.length; i++) {
+        const scope = byId.get(reach[i])?.parentId;
+        for (const t of [...(outOf.get(reach[i]) ?? []), ...(inOf.get(reach[i]) ?? [])]) {
+            if (s.anchored.has(t) || !s.pending.has(t) || byId.get(t)?.parentId !== scope)
+                continue;
+            s.anchored.add(t);
+            reach.push(t);
+        }
+    }
+    assignNotes(s);
+    return s;
+}
+/**
+ * Give each sticky note to the positioned node in its container it covers
+ * most, by id on a tie, so the note moves with it; a note over no node stays.
+ */
+function assignNotes(s) {
+    const area = (a, b) => Math.max(0, Math.min(a.x + a.width, b.x + b.width) - Math.max(a.x, b.x)) * Math.max(0, Math.min(a.y + a.height, b.y + b.height) - Math.max(a.y, b.y));
+    for (const note of s.nodes) {
+        if (note.type !== STICKY_NOTE_TYPE || !hasPosition(s, note))
+            continue;
+        const r = rectOf(s, note);
+        const [owner] = positionedIn(s, note.parentId)
+            .map((o) => ({ id: o.id, covered: area(r, rectOf(s, o)) }))
+            .filter(({ covered }) => covered > 0)
+            .sort((a, b) => b.covered - a.covered || a.id.localeCompare(b.id));
+        if (!owner)
+            continue;
+        if (!s.notesOf.has(owner.id))
+            s.notesOf.set(owner.id, []);
+        s.notesOf.get(owner.id).push(note.id);
+    }
+}
+// ── Reading and writing positions ──
+function uiOf(s, n) {
+    const entry = s.layoutNodes?.[n.id];
+    const own = n.ui;
+    return entry ? { ...own, ...entry } : own;
+}
+function sizeOf(s, n) {
+    const fallback = s.containers.has(n.id) ? CONTAINER_SIZE : { width: DEFAULT_SIZE, height: DEFAULT_SIZE };
+    return { width: uiOf(s, n)?.size?.width ?? fallback.width, height: uiOf(s, n)?.size?.height ?? fallback.height };
+}
+const rectOf = (s, n) => ({ ...uiOf(s, n).position, ...sizeOf(s, n) });
+/** Write each field where it already lives; a new one goes where the file stores positions. */
+function write(s, n, patch) {
+    for (const [key, value] of Object.entries(patch)) {
         const own = n.ui;
-        return entry ? { ...own, ...entry } : own;
+        const entry = s.layoutNodes?.[n.id];
+        if (s.layoutNodes && (entry?.[key] !== undefined || own?.[key] === undefined))
+            s.layoutNodes[n.id] = { ...entry, [key]: value };
+        else
+            n.ui = { ...own, [key]: value };
+    }
+}
+/** Move `ids`, and the sticky notes they carry, by `by`. */
+function shift(s, ids, by) {
+    for (const id of [...ids, ...[...ids].flatMap((i) => s.notesOf.get(i) ?? [])]) {
+        const o = s.byId.get(id);
+        const p = uiOf(s, o).position;
+        write(s, o, { position: { x: p.x + by.x, y: p.y + by.y } });
+    }
+}
+// ── What may move ──
+const hasPosition = (s, o) => uiOf(s, o)?.position !== undefined;
+function isPositioned(s, id) {
+    const n = s.byId.get(id);
+    return n !== undefined && !s.pending.has(id) && hasPosition(s, n);
+}
+/** Positioned, and not an author `.layout()` position: those stay where the author put them. */
+const isMovable = (s, n) => isPositioned(s, n.id) && (!s.isAdded(n.id) || s.placed.has(n.id));
+/** Whether an edge enters `id` from its own container, which is in the scope: the first node of a body. */
+function enteredFromContainer(s, id) {
+    const parent = s.byId.get(id)?.parentId;
+    return parent !== undefined && s.byId.has(parent) && (s.inOf.get(id) ?? []).includes(parent);
+}
+/** A pending node that will never be placed: it keeps its placeholder. */
+const isFloating = (s, o) => s.pending.has(o.id) && !s.anchored.has(o.id);
+/** The nodes in `scope` a node may not overlap: positioned ones and floating placeholders. Pending ones are placed later, around them. */
+const obstaclesIn = (s, scope, except) => s.nodes.filter((o) => o.id !== except && o.parentId === scope && o.type !== STICKY_NOTE_TYPE && hasPosition(s, o)
+    && (!s.pending.has(o.id) || isFloating(s, o)));
+const positionedIn = (s, scope) => obstaclesIn(s, scope, '').filter((o) => isPositioned(s, o.id));
+/** Every node an edge path from `from` reaches inside its container, through pending ones. */
+function downstreamOf(s, from) {
+    const scope = s.byId.get(from)?.parentId;
+    const seen = new Set();
+    const queue = [from];
+    for (let i = 0; i < queue.length; i++) {
+        for (const t of s.outOf.get(queue[i]) ?? []) {
+            if (t === from || seen.has(t) || !s.byId.has(t) || s.byId.get(t).parentId !== scope)
+                continue;
+            seen.add(t);
+            queue.push(t);
+        }
+    }
+    return seen;
+}
+/**
+ * The first positioned nodes `from` reaches in its container, through pending
+ * ones, each with how many pending ones lie on the way.
+ */
+function frontierOf(s, from) {
+    const scope = s.byId.get(from)?.parentId;
+    const found = new Map();
+    const hops = new Map([[from, 0]]);
+    const queue = [from];
+    for (let i = 0; i < queue.length; i++) {
+        for (const t of s.outOf.get(queue[i]) ?? []) {
+            if (t === from || hops.has(t) || !s.byId.has(t) || s.byId.get(t).parentId !== scope)
+                continue;
+            const h = hops.get(queue[i]) + (queue[i] === from ? 0 : 1);
+            hops.set(t, h);
+            if (s.pending.has(t))
+                queue.push(t);
+            else if (isPositioned(s, t))
+                found.set(t, h);
+        }
+    }
+    return found;
+}
+// ── Pushing ──
+/** The cell span of the x-grid that indexes boxes for collision checks. */
+const GRID = 1024;
+/** A box spanning more cells than this is checked against every moved box instead of indexed. */
+const MAX_CELLS = 64;
+/** Boxes indexed by the x-grid cells they span, so a lookup only checks boxes near it. */
+function gridOf(s, boxes) {
+    const cells = new Map();
+    const wide = [];
+    const cell = (x) => Math.floor(x / GRID);
+    for (const o of boxes) {
+        const r = rectOf(s, o);
+        const first = cell(r.x - PADDING);
+        const last = cell(r.x + r.width + PADDING);
+        if (last - first >= MAX_CELLS) {
+            wide.push(o);
+            continue;
+        }
+        for (let c = first; c <= last; c++) {
+            if (!cells.has(c))
+                cells.set(c, []);
+            cells.get(c).push(o);
+        }
+    }
+    return (r) => {
+        const near = new Set(wide);
+        for (let c = cell(r.x - PADDING); c <= cell(r.x + r.width + PADDING); c++)
+            for (const o of cells.get(c) ?? [])
+                near.add(o);
+        return [...near];
     };
-    const sizeOf = (n) => ({
-        width: uiOf(n)?.size?.width ?? DEFAULT_SIZE,
-        height: uiOf(n)?.size?.height ?? DEFAULT_SIZE,
-    });
-    const pending = new Set(nodes.filter((n) => isAdded(n.id) && n.type !== STICKY_NOTE_TYPE && isPlaceholderPosition(uiOf(n)?.position)).map((n) => n.id));
-    const positioned = (id) => {
-        const n = byId.get(id);
-        return n !== undefined && !pending.has(id) && uiOf(n)?.position !== undefined;
+}
+/**
+ * What `opts.seed` carries along: the seed, the nodes downstream of a moved
+ * one that `opts.mayMove` allows (through pending ones, which do not move),
+ * and whatever a moved node would land on, with its downstream. Undefined when
+ * a moved node lands on one it may not move and `opts.blocked` refuses.
+ */
+function spread(s, opts) {
+    if (opts.seed.length === 0)
+        return new Set();
+    const scope = opts.seed[0].parentId;
+    const nearby = gridOf(s, obstaclesIn(s, scope, opts.origin));
+    const moved = new Set();
+    const seen = new Set([opts.origin]);
+    const queue = [];
+    const visit = (id, moves) => {
+        if (seen.has(id))
+            return;
+        seen.add(id);
+        if (moves)
+            moved.add(id);
+        queue.push(id);
     };
-    // Place in waves, so a run of added nodes chains off the first one placed.
-    for (let progress = true; progress && pending.size > 0;) {
-        progress = false;
-        for (const id of [...pending]) {
-            const n = byId.get(id);
-            const sameScope = (other) => byId.get(other)?.parentId === n.parentId;
-            const pred = edges.find((e) => e.targetNodeId === id && sameScope(e.sourceNodeId) && positioned(e.sourceNodeId));
-            const entersBody = !pred && n.parentId !== undefined && byId.has(n.parentId)
-                && edges.some((e) => e.targetNodeId === id && e.sourceNodeId === n.parentId);
-            const succ = pred || entersBody ? undefined
-                : edges.find((e) => e.sourceNodeId === id && sameScope(e.targetNodeId) && positioned(e.targetNodeId));
-            let candidate;
-            if (pred || succ) {
-                const anchor = uiOf(byId.get(pred?.sourceNodeId ?? succ.targetNodeId)).position;
-                candidate = { x: anchor.x + (pred ? SLOT_DX : -SLOT_DX), y: anchor.y };
-            }
-            else if (entersBody) {
-                candidate = { ...BODY_ORIGIN };
-            }
-            else {
+    for (const o of opts.seed)
+        visit(o.id, true);
+    for (let i = 0; i < queue.length; i++) {
+        const id = queue[i];
+        for (const t of s.outOf.get(id) ?? []) {
+            const d = s.byId.get(t);
+            if (!d || d.parentId !== scope || seen.has(t))
+                continue;
+            if (s.pending.has(t))
+                visit(t, false);
+            else if (isPositioned(s, t) && opts.mayMove(d))
+                visit(t, true);
+        }
+        if (!moved.has(id))
+            continue;
+        const r = rectOf(s, s.byId.get(id));
+        const box = { ...r, x: r.x + opts.by.x, y: r.y + opts.by.y };
+        if (opts.blocked === Blocked.Refuse && opts.keepClear && overlaps(box, opts.keepClear))
+            return undefined;
+        for (const other of nearby(box)) {
+            if (moved.has(other.id) || !overlaps(box, rectOf(s, other)))
                 continue;
-            }
-            // Still-pending nodes count at their placeholder: one that never finds an
-            // anchor stays there, and nothing may land on it.
-            const others = nodes
-                .filter((o) => o.id !== id && o.parentId === n.parentId && o.type !== STICKY_NOTE_TYPE && uiOf(o)?.position !== undefined)
-                .map((o) => ({ ...uiOf(o).position, ...sizeOf(o) }));
-            const position = findFreePosition(candidate, sizeOf(n), others);
-            const ui = { ...uiOf(n), position };
-            if (layoutNodes)
-                layoutNodes[id] = ui;
-            else
-                n.ui = ui;
-            pending.delete(id);
-            progress = true;
+            if (opts.blocked === Blocked.Refuse && !opts.mayMove(other))
+                return undefined;
+            visit(other.id, true);
+        }
+    }
+    return moved;
+}
+// ── Placing ──
+/** Place in waves, by id, until no pending node has an anchor left. */
+function placeInWaves(s) {
+    for (let wave = nextWave(s); wave.length > 0; wave = nextWave(s)) {
+        for (const id of wave)
+            placeNode(s, id);
+    }
+}
+/**
+ * The pending nodes to place next: those with a positioned predecessor (or
+ * their container's entry) and no predecessor in their container still to be
+ * placed; when the rest are in a cycle, those with a positioned predecessor;
+ * else those with a positioned successor.
+ */
+function nextWave(s) {
+    const pending = [...s.pending].sort();
+    const scopeOfId = (id) => s.byId.get(id).parentId;
+    const positionedNear = (id, other) => s.byId.get(other)?.parentId === scopeOfId(id) && isPositioned(s, other);
+    const fromBehind = (id) => enteredFromContainer(s, id) || (s.inOf.get(id) ?? []).some((p) => positionedNear(id, p));
+    const predsPlaced = (id) => (s.inOf.get(id) ?? []).every((p) => p === id || !s.anchored.has(p) || !s.pending.has(p) || s.byId.get(p)?.parentId !== scopeOfId(id));
+    const behind = pending.filter(fromBehind);
+    const settled = behind.filter(predsPlaced);
+    if (settled.length > 0)
+        return settled;
+    if (behind.length > 0)
+        return behind;
+    return pending.filter((id) => (s.outOf.get(id) ?? []).some((t) => positionedNear(id, t)));
+}
+/** Where a node goes before making room, and which nodes count as past it. */
+function candidateOf(s, n) {
+    const inScope = (other) => s.byId.get(other)?.parentId === n.parentId && isPositioned(s, other);
+    const rightEdge = (id) => rectOf(s, s.byId.get(id)).x + rectOf(s, s.byId.get(id)).width;
+    const [pred] = (s.inOf.get(n.id) ?? []).filter(inScope).sort((a, b) => rightEdge(b) - rightEdge(a) || a.localeCompare(b));
+    if (pred !== undefined) {
+        const anchor = rectOf(s, s.byId.get(pred));
+        const [lead] = [...frontierOf(s, n.id)].filter(([t]) => t !== pred)
+            .map(([t, hops]) => ({ t, hops, r: rectOf(s, s.byId.get(t)) }))
+            .sort((a, b) => a.hops - b.hops || a.r.x - b.r.x || a.t.localeCompare(b.t));
+        // A successor tucked under its predecessor (a context index under its agent): take its spot and push it a slot.
+        if (lead && lead.hops === 0 && lead.r.x >= anchor.x && lead.r.x < anchor.x + anchor.width) {
+            return { at: { x: lead.r.x, y: lead.r.y }, past: (o) => o.id !== pred && rectOf(s, o).x >= lead.r.x, pred };
+        }
+        // A join another lane already feeds keeps the node in its predecessor's lane.
+        const joins = lead !== undefined && (s.inOf.get(lead.t) ?? [])
+            .some((p) => p !== pred && s.byId.get(p)?.parentId === n.parentId && isPositioned(s, p));
+        const y = lead && !joins && !rowsMeet(anchor, lead.r) ? lead.r.y : anchor.y;
+        // At the predecessor's x counts as past (a context index under its agent); the predecessor does not.
+        return { at: { x: anchor.x + anchor.width + GAP, y }, past: (o) => o.id !== pred && rectOf(s, o).x >= anchor.x, pred };
+    }
+    if (enteredFromContainer(s, n.id))
+        return { at: { ...BODY_ORIGIN }, past: () => true };
+    const [succ] = (s.outOf.get(n.id) ?? []).filter(inScope)
+        .sort((a, b) => rectOf(s, s.byId.get(a)).x - rectOf(s, s.byId.get(b)).x || a.localeCompare(b));
+    const at = rectOf(s, s.byId.get(succ));
+    const left = { x: at.x - SLOT_DX, y: at.y };
+    if (!obstaclesIn(s, n.parentId, n.id).some((o) => overlaps({ ...left, ...sizeOf(s, n) }, rectOf(s, o))))
+        return { at: left };
+    return { at: { x: at.x, y: at.y }, past: (o) => rectOf(s, o).x >= at.x };
+}
+/** The new branches already placed out of `pred`, other than the node's own downstream. */
+function siblingsOf(s, pred, downstream) {
+    if (pred === undefined)
+        return new Set();
+    return new Set((s.outOf.get(pred) ?? []).filter((t) => s.placed.has(t) && !downstream.has(t)));
+}
+/**
+ * Move `at` down, row by row, while everything a box of `size` there would
+ * overlap is a sibling, in one sweep: only obstacles in its column can be
+ * hit, and the rows only go down.
+ */
+function stackBelowSiblings(s, at, size, obstacles, siblings) {
+    if (siblings.size === 0)
+        return;
+    const column = obstacles.map((o) => ({ id: o.id, r: rectOf(s, o) }))
+        .filter(({ r }) => r.x < at.x + size.width + PADDING && at.x < r.x + r.width + PADDING)
+        .sort((a, b) => a.r.y - b.r.y);
+    let row = [];
+    for (let next = 0;;) {
+        while (next < column.length && column[next].r.y < at.y + size.height + PADDING)
+            row.push(column[next++]);
+        row = row.filter(({ r }) => r.y + r.height + PADDING > at.y);
+        if (row.length === 0 || !row.every(({ id }) => siblings.has(id)))
+            return;
+        at.y = Math.max(...row.map(({ r }) => r.y + r.height)) + GAP;
+    }
+}
+function placeNode(s, id) {
+    const n = s.byId.get(id);
+    const { at, past, pred } = candidateOf(s, n);
+    const obstacles = obstaclesIn(s, n.parentId, id);
+    // An added sibling (another new branch out of the same predecessor) on the spot: take the next row down instead of pushing it.
+    const downstream = downstreamOf(s, id);
+    stackBelowSiblings(s, at, sizeOf(s, n), obstacles, siblingsOf(s, pred, downstream));
+    const box = { ...at, ...sizeOf(s, n) };
+    const hits = obstacles.filter((o) => overlaps(box, rectOf(s, o)));
+    const freeSpot = () => findFreePosition(at, sizeOf(s, n), obstacles.map((o) => rectOf(s, o)));
+    let position = at;
+    if (past) {
+        const pushable = (o) => isMovable(s, o) && past(o);
+        const roomFor = (o) => box.x + box.width + GAP - rectOf(s, o).x;
+        const after = [...downstream].map((d) => s.byId.get(d)).filter((o) => isPositioned(s, o.id) && pushable(o));
+        const rowNeed = [...hits, ...after].filter((o) => pushable(o) && rowsMeet(box, rectOf(s, o))).map(roomFor);
+        const successorNeed = [...frontierOf(s, id).keys()].map((t) => s.byId.get(t)).filter(pushable).map(roomFor);
+        const by = { x: Math.max(0, ...rowNeed, ...successorNeed), y: 0 };
+        const moved = hits.every(pushable)
+            ? spread(s, { origin: id, seed: [...hits, ...after], by, mayMove: pushable, blocked: Blocked.Refuse, keepClear: box })
+            : undefined;
+        if (moved)
+            shift(s, moved, by);
+        else if (hits.length > 0)
+            position = freeSpot();
+    }
+    else if (hits.length > 0) {
+        position = freeSpot();
+    }
+    write(s, n, { position });
+    s.pending.delete(id);
+    s.placed.add(id);
+    if (n.parentId !== undefined && s.byId.has(n.parentId))
+        s.toFit.add(n.parentId);
+}
+// ── Growing containers ──
+/** The right and bottom edge of a container's body, over the children `which` keeps. */
+function bodyExtent(s, id, which) {
+    const body = positionedIn(s, id).filter(which).map((o) => rectOf(s, o));
+    if (body.length === 0)
+        return undefined;
+    return { right: Math.max(...body.map((r) => r.x + r.width)), bottom: Math.max(...body.map((r) => r.y + r.height)) };
+}
+/**
+ * Grow each container that gained or moved a child, innermost first (by id on
+ * a tie), by as much as its body grew past the padding it had (the body
+ * origin's, for a body that was empty). A grown container pushes every
+ * sibling in its way or downstream of it past its old edges, an author
+ * position or placeholder included (it was chosen against the old size), and
+ * keeps at least the row gap to its new right edge. Its own container is
+ * fitted next.
+ */
+function fitContainers(s, before) {
+    const fitted = new Set();
+    for (let id = deepest(s.toFit, s.byId); id !== undefined; id = deepest(s.toFit, s.byId)) {
+        s.toFit.delete(id);
+        fitted.add(id);
+        const c = s.byId.get(id);
+        const now = bodyExtent(s, id, () => true);
+        if (!now)
+            continue;
+        const old = sizeOf(s, c);
+        const was = before.get(id);
+        const padRight = was ? Math.min(BODY_ORIGIN.x, old.width - was.right) : BODY_ORIGIN.x;
+        const padBottom = was ? Math.min(BODY_ORIGIN.y, old.height - was.bottom) : BODY_ORIGIN.y;
+        const width = Math.max(old.width, now.right + padRight);
+        const height = Math.max(old.height, now.bottom + padBottom);
+        if (width === old.width && height === old.height)
+            continue;
+        write(s, c, { size: { ...uiOf(s, c)?.size, width, height } });
+        if (c.parentId !== undefined && s.byId.has(c.parentId) && !fitted.has(c.parentId))
+            s.toFit.add(c.parentId);
+        if (!hasPosition(s, c))
+            continue;
+        const at = rectOf(s, c);
+        const grown = { ...at, width, height };
+        const siblings = obstaclesIn(s, c.parentId, id);
+        const downstream = downstreamOf(s, id);
+        if (width > old.width) {
+            const right = siblings.filter((o) => rectOf(s, o).x >= at.x + old.width && (downstream.has(o.id) || overlaps(grown, rectOf(s, o))));
+            const gapNeed = right.filter((o) => rowsMeet(grown, rectOf(s, o))).map((o) => at.x + width + GAP - rectOf(s, o).x);
+            const by = { x: Math.max(width - old.width, ...gapNeed), y: 0 };
+            const pastRight = (o) => hasPosition(s, o) && rectOf(s, o).x >= at.x + old.width;
+            const moved = spread(s, { origin: id, seed: right, by, mayMove: pastRight, blocked: Blocked.Push });
+            if (moved)
+                shift(s, moved, by);
+        }
+        if (height > old.height) {
+            const under = siblings.filter((o) => rectOf(s, o).y >= at.y + old.height && overlaps(grown, rectOf(s, o)));
+            const by = { x: 0, y: height - old.height };
+            const pastBottom = (o) => hasPosition(s, o) && rectOf(s, o).y >= at.y + old.height;
+            const moved = spread(s, { origin: id, seed: under, by, mayMove: pastBottom, blocked: Blocked.Push });
+            if (moved)
+                shift(s, moved, by);
         }
     }
 }
+/** The id in `ids` nested in the most containers, by id on a tie; a parent cycle stops counting at the node count. */
+function deepest(ids, byId) {
+    const depthOf = (id) => {
+        let depth = 0;
+        for (let p = byId.get(id)?.parentId; p !== undefined && byId.has(p) && depth < byId.size; p = byId.get(p)?.parentId)
+            depth += 1;
+        return depth;
+    };
+    return [...ids].sort((a, b) => depthOf(b) - depthOf(a) || a.localeCompare(b))[0];
+}

package/dist/nodes/agent/flow/node-type.js

@@ -114,7 +114,7 @@ function serializeVoiceAgent(s, ctx) {
     const json = voiceAgentJson({
         systemPrompt: s.systemPrompt, plan, voice: s.voice, maxIterations: s.maxIterations, source, name: ctx.step,
     });
-    ctx.sidecar({ path: `${source}/agent.json`, json });
+    ctx.sidecar({ path: `${source}/agent.json`, json }, s.source !== undefined ? `voice agent step "${ctx.step}"` : undefined);
     if (plan.refs.length > 0)
         ctx.typeAgentInputs(json.inputSchema, plan.refs);
     // The resource model lives on the definition (its `model.source: true` is
@@ -169,7 +169,7 @@ function serializeConversationalAgent(s, ctx) {
             maxTokenPerResponse: s.maxTokenPerResponse, maxIterations: s.maxIterations,
             guardrails: s.guardrails, source, name: ctx.step,
         }),
-    });
+    }, s.source !== undefined ? `conversational agent step "${ctx.step}"` : undefined);
     // A SHELL node, like the inline agent's (#927): exactly the keys
     // `toAgentShellInputs` keeps. The system prompt, the model and the run
     // settings live only in the sidecar (`metadata.isConversational` there is the

package/dist/serialize.js

@@ -292,6 +292,13 @@ export function serializeWithSidecars(built, opts = {}) {
     const flow = serialize(built, { ...opts, sidecars });
     return { flow, sidecars };
 }
+/**
+ * A sidecar path as the file system sees it on macOS (default APFS) and
+ * Windows, which ignore case: two paths with one key are one file there.
+ */
+function sidecarKey(path) {
+    return path.toLowerCase();
+}
 /**
  * `variables.nodes` — one entry per node OUTPUT, derived from the nodes we just
  * emitted.
@@ -1815,7 +1822,7 @@ function serializeFlow(built, opts) {
      * gets them and one that does not is unaffected.
      */
     const sidecars = opts.sidecars ?? [];
-    /** The sidecar paths an explicit `source` chose → who chose it (see `addSidecar`). */
+    /** The sidecar paths an explicit `source` chose (by {@link sidecarKey}) → who chose it (see `addSidecar`). */
     const explicitSidecars = new Map();
     /**
      * Add one sidecar file. An agent or a resource whose explicit `source` names
@@ -1825,19 +1832,26 @@ function serializeFlow(built, opts) {
      * naming both; `owner` is the one whose `source` is explicit, as the refusal
      * names it (`inline agent step "answer"'s context index "SOP"`). The same file
      * twice (a subflow body emitted for two callers) is not a clash.
+     *
+     * Paths are compared by {@link sidecarKey}, ignoring case: on macOS (default
+     * APFS) and Windows, `D84E2C17-…/agent.json` and `d84e2c17-…/agent.json` are
+     * one file (#1278).
      */
     const addSidecar = (file, owner) => {
-        const earlier = sidecars.find((f) => f.path === file.path);
-        const earlierOwner = explicitSidecars.get(file.path);
+        const key = sidecarKey(file.path);
+        const earlier = sidecars.find((f) => sidecarKey(f.path) === key);
+        const earlierOwner = explicitSidecars.get(key);
         if (earlier !== undefined && JSON.stringify(earlier.json) !== JSON.stringify(file.json)
             && (owner !== undefined || earlierOwner !== undefined)) {
             const names = [earlierOwner ?? 'another agent or resource', owner ?? 'another agent or resource'];
-            throw new CompileRefusal('INLINE_AGENT_RESOURCE_SOURCE_DUP', `${names[0].charAt(0).toUpperCase()}${names[0].slice(1)} and ${names[1]} would both write "${file.path}" with `
+            const where = earlier.path === file.path ? `"${file.path}"`
+                : `"${earlier.path}" and "${file.path}" (one file on macOS and Windows, which ignore case)`;
+            throw new CompileRefusal('INLINE_AGENT_RESOURCE_SOURCE_DUP', `${names[0].charAt(0).toUpperCase()}${names[0].slice(1)} and ${names[1]} would both write ${where} with `
                 + 'different content, so the second file would replace the first. Give each its own `source`, or omit '
                 + '`source` to derive one.');
         }
         if (owner !== undefined && earlierOwner === undefined)
-            explicitSidecars.set(file.path, owner);
+            explicitSidecars.set(key, owner);
         sidecars.push(file);
     };
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.66.4",
+  "version": "6.66.6",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -100,5 +100,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "af11f232febf9ed683dec9f44b4ae7fe3c2426fe"
+  "gitref": "108478742e5fc426dc26ba07020d85a3fdbcaa66"
 }