Skip to content

Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.

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.md
index 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.
### Dataflow
diff --git a/archify/renderers/sequence/README.md b/archify/renderers/sequence/README.md
index 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 a
meaningful participant label just to fit the fixed boxes.
diff --git a/archify/renderers/sequence/render-sequence.mjs b/archify/renderers/sequence/render-sequence.mjs
index 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.json
new file mode 100644
index 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 file
diff --git a/test/sequence-segment-labels.test.mjs b/test/sequence-segment-labels.test.mjs
index 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/);
+});