Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.
HTML agent-skillsai-agentsarchitecture-diagramclaude-codeclaude-skillscodexcoding-agentsdeepseek-harnessdeveloper-toolsdiagramsdiagrams-as-codedsh-pluginflowchartllmmermaidopencodesequence-diagramsoftware-architecturesystem-designvisualization
fix(sequence): report a segment edge along a message arrow and keep a packed segment title off the next one
tt-a1i3b7f0e0fc6de
diff --git a/archify/references/authoring-contract.md b/archify/references/authoring-contract.mdindex 7fc5c22f..e29c9f66 100644--- a/archify/references/authoring-contract.md+++ b/archify/references/authoring-contract.md@@ -316,7 +316,7 @@ not settle viewport fit. These are repair directions, not guaranteed coordinates### Sequence-Participants are ordered by conversation role. Messages own their vertical order. Use return/async/security variants for meaning, not decoration; sequence does not use Automatic Port Spread.+Participants are ordered by conversation role. Messages own their vertical order. Use return/async/security variants for meaning, not decoration; sequence does not use Automatic Port Spread. A segment's `from`/`to` edges must stay at least 4px off every message arrow (`message.y`): an edge along an arrow leaves the reader unable to tell which phase the message belongs to, and the renderer reports it.### Dataflowdiff --git a/archify/renderers/sequence/README.md b/archify/renderers/sequence/README.mdindex dcd98f65..81005538 100644--- a/archify/renderers/sequence/README.md+++ b/archify/renderers/sequence/README.md@@ -118,7 +118,7 @@ for the bounded authoring repair and explicit-fixed preservation rules.- Use `security` for auth, consent, permission, and policy calls.- Use `return` for quiet response messages.- Use `dashed` for async trace, event, logging, and non-blocking work.-- Use segments as light background guides; keep segment labels short.+- Use segments as light background guides; keep segment labels short and keep each frame edge at least 4px off every message arrow.- Keep labels concise, but try `meta.column_fit: "spread"` before shortening ameaningful participant label just to fit the fixed boxes.diff --git a/archify/renderers/sequence/render-sequence.mjs b/archify/renderers/sequence/render-sequence.mjsindex cb0cacfb..10c197fa 100644--- a/archify/renderers/sequence/render-sequence.mjs+++ b/archify/renderers/sequence/render-sequence.mjs@@ -213,9 +213,13 @@ function segmentLabelBox(segment) {// behind the participant headers or into the previous segment, where it// names the wrong phase. Its own frame's top-left corner, clear of messages,// names the right one.+ // Another segment's title normally sits on that segment's own top border,+ // so its strip is taken too.+ const otherTitles = asArray(sequence.segments).filter((other) => other !== segment)+ .map((other) => ({ x: 56, y: other.from - 22, width: Math.max(42, textUnits(other.label) * 5.2 + 14), height: 18 }));const inside = { x: 56, y: segment.from + 4, width: labelW, height: 18 };for (let attempt = 0; attempt < 4 && inside.y + inside.height <= segment.to - 2; attempt += 1) {- if (!occupied.some((rect) => rectsOverlap(inside, rect, 2))) return inside;+ if (![...occupied, ...otherTitles].some((rect) => rectsOverlap(inside, rect, 2))) return inside;inside.y += 22;}return label;@@ -468,7 +472,26 @@ function validateSequence() {if (segment.from < layout.topY || segment.to > layout.lifelineBottom + 20) {problems.push(`Segment "${segment.label}" extends outside the canvas — keep its y range between ${layout.topY} and ${layout.lifelineBottom + 20}.`);}+ // A frame edge may pass behind a masked message label, but an edge that+ // runs along the arrow itself leaves the reader unable to tell which phase+ // the message belongs to.+ if (sequence.meta?.quality_profile) {+ for (const edge of ['from', 'to']) {+ const border = segment[edge];+ const cut = asArray(sequence.messages).filter((message) => typeof message.y === 'number'+ && Math.abs(border - message.y) < 4);+ for (const message of cut) {+ problems.push(`Segment "${segment.label}" ${edge === 'from' ? 'top' : 'bottom'} edge at y ${border} runs along message "${message.label}" (arrow at y ${message.y}) — move the edge to at least ${message.y + 4} to leave the message above it, or to at most ${message.y - 4} to leave it below.`);+ }+ }+ }const labelBox = segmentLabelBox(segment);+ for (const other of asArray(sequence.segments)) {+ if (other === segment || asArray(sequence.segments).indexOf(other) < asArray(sequence.segments).indexOf(segment)) continue;+ if (rectsOverlap(labelBox, segmentLabelBox(other), 0)) {+ problems.push(`Segment labels "${segment.label}" and "${other.label}" overlap — leave more room between the segments' messages near their shared border, or shorten a label.`);+ }+ }const availableWidth = Math.max(0, viewBox[0] - 48 - labelBox.x);if (labelBox.x + labelBox.width > viewBox[0] - 48) {const requiredWidth = Math.ceil(labelBox.x + labelBox.width + 48);diff --git a/test/fixtures/sequence-first-draft/resumable-upload.sequence.json b/test/fixtures/sequence-first-draft/resumable-upload.sequence.jsonnew file mode 100644index 00000000..819b870e--- /dev/null+++ b/test/fixtures/sequence-first-draft/resumable-upload.sequence.json@@ -0,0 +1,151 @@+{+ "schema_version": 1,+ "diagram_type": "sequence",+ "meta": {+ "title": "Resumable file upload",+ "locale": "en",+ "quality_profile": "showcase",+ "output": "resumable-upload.html"+ },+ "participants": [+ {+ "id": "client",+ "type": "frontend",+ "label": "Client",+ "sublabel": "web uploader"+ },+ {+ "id": "api",+ "type": "backend",+ "label": "Upload API",+ "sublabel": "tus server"+ },+ {+ "id": "s3",+ "type": "cloud",+ "label": "Object store",+ "sublabel": "S3 multipart"+ },+ {+ "id": "scan",+ "type": "backend",+ "label": "Virus scan",+ "sublabel": "ClamAV"+ },+ {+ "id": "db",+ "type": "database",+ "label": "Metadata DB",+ "sublabel": "Postgres"+ }+ ],+ "messages": [+ {+ "id": "m1",+ "from": "client",+ "to": "api",+ "y": 160,+ "label": "POST /uploads (size, name)"+ },+ {+ "id": "m2",+ "from": "api",+ "to": "s3",+ "y": 192,+ "label": "CreateMultipartUpload"+ },+ {+ "id": "m3",+ "from": "s3",+ "to": "api",+ "y": 224,+ "label": "uploadId",+ "variant": "return"+ },+ {+ "id": "m4",+ "from": "api",+ "to": "client",+ "y": 256,+ "label": "201 Location",+ "variant": "return"+ },+ {+ "id": "m5",+ "from": "client",+ "to": "api",+ "y": 300,+ "label": "PATCH chunk 1..n"+ },+ {+ "id": "m6",+ "from": "api",+ "to": "s3",+ "y": 328,+ "label": "UploadPart",+ "variant": "dashed"+ },+ {+ "id": "m7",+ "from": "client",+ "to": "api",+ "y": 356,+ "label": "HEAD (resume offset)"+ },+ {+ "id": "m8",+ "from": "api",+ "to": "s3",+ "y": 392,+ "label": "CompleteMultipartUpload"+ },+ {+ "id": "m9",+ "from": "api",+ "to": "scan",+ "y": 420,+ "label": "scan object",+ "variant": "dashed"+ },+ {+ "id": "m10",+ "from": "scan",+ "to": "api",+ "y": 448,+ "label": "clean",+ "variant": "return"+ },+ {+ "id": "m11",+ "from": "api",+ "to": "db",+ "y": 476,+ "label": "insert file row"+ },+ {+ "id": "m12",+ "from": "api",+ "to": "client",+ "y": 504,+ "label": "204 done",+ "variant": "return"+ }+ ],+ "segments": [+ {+ "from": 140,+ "to": 280,+ "label": "Create"+ },+ {+ "from": 286,+ "to": 370,+ "label": "Transfer + resume"+ },+ {+ "from": 376,+ "to": 530,+ "label": "Finalize"+ }+ ]+}\ No newline at end of filediff --git a/test/sequence-segment-labels.test.mjs b/test/sequence-segment-labels.test.mjsindex 76447395..ca28622a 100644--- a/test/sequence-segment-labels.test.mjs+++ b/test/sequence-segment-labels.test.mjs@@ -55,3 +55,37 @@ test('a label that fits above a spaced frame keeps its place above it', () => {const [label] = labels(result.html);assert.ok(label.y + label.height <= 340, `label at ${label.y} should stay above the frame`);});++// A three-phase upload whose middle phase is packed with messages: its title+// cannot sit on its own top border, and the next phase's title owns the strip+// above that phase's border.+const upload = path.join(__dirname, 'fixtures', 'sequence-first-draft', 'resumable-upload.sequence.json');++test('a title pushed inside its packed frame keeps clear of the next segment title', () => {+ const diagram = JSON.parse(fs.readFileSync(upload, 'utf8'));+ // The first draft's spacing, where the middle title used to land on "Finalize".+ const ys = { PATCH: 300, UploadPart: 320, HEAD: 332, Complete: 364, scan: 404, clean: 436, insert: 468, 204: 500 };+ for (const message of diagram.messages) {+ const key = Object.keys(ys).find((prefix) => message.label.startsWith(prefix));+ if (key) message.y = ys[key];+ }+ diagram.segments = [{ from: 140, to: 280, label: 'Create' }, { from: 286, to: 384, label: 'Transfer + resume' }, { from: 390, to: 540, label: 'Finalize' }];+ const result = render(diagram);+ assert.equal(result.status, 0, result.stdout + result.stderr);+ const placed = labels(result.html);+ for (let i = 0; i < placed.length; i += 1) {+ for (let j = i + 1; j < placed.length; j += 1) {+ const overlap = Math.min(placed[i].y + placed[i].height, placed[j].y + placed[j].height) - Math.max(placed[i].y, placed[j].y);+ assert.ok(overlap <= 0, `segment titles ${placed[i].index} and ${placed[j].index} overlap by ${overlap}px`);+ }+ }+});++test('a segment edge running along a message arrow is reported with the move that clears it', () => {+ const diagram = JSON.parse(fs.readFileSync(upload, 'utf8'));+ diagram.segments[0].to = 298;+ diagram.segments[1].from = 302;+ const result = render(diagram);+ assert.notEqual(result.status, 0);+ assert.match(result.stderr + result.stdout, /Segment "Create" bottom edge at y 298 runs along message "PATCH chunk 1\.\.n" \(arrow at y 300\) — move the edge to at least 304/);+});