diff --git a/skill-flavors/studioweb/uipath-maestro-flow/references/brownfield.md b/skill-flavors/studioweb/uipath-maestro-flow/references/brownfield.md index 732accba39..42400fa08e 100644 --- a/skill-flavors/studioweb/uipath-maestro-flow/references/brownfield.md +++ b/skill-flavors/studioweb/uipath-maestro-flow/references/brownfield.md @@ -113,3 +113,7 @@ In Studio Web the target `.flow` is the source: use the round trip in or tell the user this needs `@uipath/maestro-builder-sdk` 6.114.0 or later, since Studio Web owns the SDK copy). + + +tell the user this needs `@uipath/maestro-builder-sdk` 6.115.0 or later, since Studio Web owns the SDK copy and the merged `.flow` is never edited by hand. + diff --git a/skills/uipath-maestro-flow/references/brownfield.md b/skills/uipath-maestro-flow/references/brownfield.md index 0875f0f221..e48799e2e4 100644 --- a/skills/uipath-maestro-flow/references/brownfield.md +++ b/skills/uipath-maestro-flow/references/brownfield.md @@ -616,17 +616,21 @@ Do not run `uip maestro flow format` on the merged file; it discards the author' Decompiled source carries that layout as a `.layout({ nodes })` block, one long-hand entry per node. Keep it. -Only an added step's entry lands: a step the edit adds has none, so compile places it on its placeholder row and `merge` moves it next to its neighbours; to choose the spot yourself, add `: at(x, y)` beside the neighbouring entries (`import { at } from '@uipath/maestro-builder-sdk'`); `merge` keeps a step you placed and moves only the ones compile left unplaced (`@uipath/maestro-builder-sdk` 6.114.0 or later; an older SDK also moves an `at()` where (x − 256) is a multiple of 288 on y = 144 or 304, so avoid those spots, +A step the edit adds has no entry, so compile places it on its placeholder row and `merge` moves it next to its neighbours; to choose the spot yourself, add `: at(x, y)` beside the neighbouring entries (`import { at } from '@uipath/maestro-builder-sdk'`); `merge` keeps a step you placed and moves only the ones compile left unplaced (`@uipath/maestro-builder-sdk` 6.114.0 or later; an older SDK also moves an `at()` where (x − 256) is a multiple of 288 on y = 144 or 304, so avoid those spots, or upgrade with `npm install -g @uipath/maestro-builder-sdk@latest`). A container the edit grows can still push that spot aside, so keep where it lands. -At the root, an existing node's position and size come from the original whatever the source says, except that `merge` shifts later nodes and grows a container to fit added steps; moving or resizing one in the source does nothing, so for any other change set `layout.nodes..position` or `.size` in the merged `.flow` instead, and only when the file has no `layout.nodes` map, the node's `ui`. -Inside a subflow the source's entries land only when the edit changed that subflow: `merge` then takes the subflow from the edited compile whole, and otherwise keeps the original subflow as it was (6.44.4 or later; an older SDK takes every subflow from the edited compile, +To move or resize an existing node, change or add its entry in the source (decompile writes none while every node of that flow or subflow is still where compile put it) and merge again: `merge` applies an entry whose position, size or collapsed state differs from the baseline to the original node, at the root and in subflows, and every other node keeps the original's geometry. For example, `review: at(640, 144)` changed to `at(640, 304)` moves only `review`. No hand edit of the merged `.flow` is needed. +This needs `@uipath/maestro-builder-sdk` 6.115.0 or later. An older SDK keeps the original's position and size whatever the source says; + +with it, set `layout.nodes..position` or `.size` in the merged `.flow` instead (the node's `ui` only when the file has no `layout.nodes` map), or upgrade with `npm install -g @uipath/maestro-builder-sdk@latest`. + +`merge` still shifts later nodes and grows a container to fit added steps. A subflow the edit changed is taken from the edited compile whole; any other subflow keeps the original, plus the entries you changed (6.44.4 or later; an older SDK takes every subflow from the edited compile, so upgrade with `npm install -g @uipath/maestro-builder-sdk@latest`). -A step the edit removes must lose its entry, or compile fails on the unknown key. +Remove the entry of a step the edit removes. A leftover key does not fail compile: compile drops it and warns `LAYOUT_UNKNOWN_KEY`, and `check` reports the same warning (`@uipath/maestro-builder-sdk` 6.115.0 or later; an older SDK fails compile on it). Grid and rules: [`operate.md`](operate.md#lay-out-from-source-instead-layout-at-dim). ## A path without an End stays open diff --git a/skills/uipath-maestro-flow/references/diagnose.md b/skills/uipath-maestro-flow/references/diagnose.md index 9898f76d57..c61fd5753b 100644 --- a/skills/uipath-maestro-flow/references/diagnose.md +++ b/skills/uipath-maestro-flow/references/diagnose.md @@ -132,7 +132,7 @@ canvas. When the source sets `.layout()`, the misshapen node is the one with no entry, an entry at the wrong coordinates, or a container whose `dim()` no longer holds a body that grew. In a greenfield source: add or move its `at(x, y)`, resize with `dim(width, height)`, and recompile rather than running `format`, which would discard every other entry too. -In a merged brownfield file only an added node's entry lands; fix an existing node's position or size in the merged `.flow`'s `layout.nodes` ([`operate.md`](operate.md#lay-out-from-source-instead-layout-at-dim), [`brownfield.md`](brownfield.md#designer-shapes-decompile-keeps)). +In a brownfield edit, fix it the same way in the decompiled source and merge again; `merge` applies a changed entry to the original node ([`operate.md`](operate.md#lay-out-from-source-instead-layout-at-dim)). This needs `@uipath/maestro-builder-sdk` 6.115.0 or later; the older-SDK fallback is in [`brownfield.md`](brownfield.md#designer-shapes-decompile-keeps). **Green `validate`, faulted `debug`.** Structural correctness and runtime correctness are different claims. `validate` proves the emitted `.flow` is well diff --git a/skills/uipath-maestro-flow/references/operate.md b/skills/uipath-maestro-flow/references/operate.md index af12fdb4fe..10b599302f 100644 --- a/skills/uipath-maestro-flow/references/operate.md +++ b/skills/uipath-maestro-flow/references/operate.md @@ -78,7 +78,7 @@ Rules: Compile gives a node without `dim()` its canvas-shape size: an agent node (`inlineAgent`, `conversationalAgent`, `voiceAgent`) is 288 × 96, so the next column starts 384 px to its right; a container is 560 × 320 unless its `dim()` makes it larger (rule 2), and the row below it starts one row gap (64 px) under its bottom edge, not at the next 160 px row. 2. **A child's position is relative to its container.** A loop or do-while body starts at `at(144, 96)` inside the container's padding. The container's 560 × 320 holds a small body; give it a `dim()` only when the body needs more: the right edge of its rightmost child plus 144, by the bottom edge of its lowest child plus 96. For one row of 96 px nodes that is `dim(192 × bodyNodes + 192, 320)` from two body nodes on (two nodes: `dim(576, 320)`, as `eachInvoice` above); a body with an inline agent, a second row or a nested container is measured from its own entries, not from the node count. -3. **Name every node, or none.** A missing entry falls back to compile's one-row placeholder, which lands on top of your layout; an unknown key fails `compile`. +3. **Name every node, or none.** A missing entry falls back to compile's one-row placeholder, which lands on top of your layout. A key that names no node is dropped with a `LAYOUT_UNKNOWN_KEY` warning (an SDK older than 6.115.0 fails `compile` on it); remove it. 4. **Never `format` a file whose source sets `.layout()`.** `format` re-lays out every node and discards the source's positions, exactly as it does to a merged brownfield file. 5. **`at` and `dim` need `@uipath/maestro-builder-sdk` 6.36.0 or later** — check that `dist/api-index.md` of the SDK copy in use lists them. If not, upgrade that copy: `npm install @uipath/maestro-builder-sdk@latest` in a workspace that has its own `node_modules` copy (it is used before the global one), else `npm install -g @uipath/maestro-builder-sdk@latest`; or write the entry long-hand, `{ position: { x, y } }` with an optional `size: { width, height }`.