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): keep a crowded segment title inside its own phase

tt-a1ida4165703088
diff --git a/archify/renderers/sequence/render-sequence.mjs b/archify/renderers/sequence/render-sequence.mjs
index 7feb167b..cb0cacfb 100644
--- a/archify/renderers/sequence/render-sequence.mjs
+++ b/archify/renderers/sequence/render-sequence.mjs
@@ -208,9 +208,30 @@ function segmentLabelBox(segment) {
if (!occupied.some((rect) => rectsOverlap(label, rect, 2))) break;
label.y -= 22;
}
+ if (!segmentLabelMisplaced(label, segment)) return label;
+ // Abutting segments can leave no room on the border: the badge climbed
+ // 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.
+ 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;
+ inside.y += 22;
+ }
return label;
}
+// A badge on its frame's top border is the intended title. It stops naming
+// that frame once it hides mostly behind the participant headers, or once
+// message labels pushed it up into another segment.
+function segmentLabelMisplaced(label, segment) {
+ const half = label.height / 2;
+ if (layout.topY + layout.participantH - label.y > half) return true;
+ if (label.y >= segment.from - 22) return false;
+ return asArray(sequence.segments).some((other) => other !== segment
+ && Math.min(label.y + label.height, other.to) - Math.max(label.y, other.from) > half);
+}
+
const compositionFrames = asArray(sequence.segments).map((segment, index) => ({
id: index,
label: segment.label,
diff --git a/test/fixtures/sequence-first-draft/scan-to-pay.sequence.json b/test/fixtures/sequence-first-draft/scan-to-pay.sequence.json
new file mode 100644
index 00000000..bf1a2afe
--- /dev/null
+++ b/test/fixtures/sequence-first-draft/scan-to-pay.sequence.json
@@ -0,0 +1,148 @@
+{
+ "schema_version": 1,
+ "diagram_type": "sequence",
+ "meta": {
+ "title": "扫码支付回调流程",
+ "locale": "zh-CN",
+ "quality_profile": "showcase",
+ "output": "scan-to-pay.html"
+ },
+ "participants": [
+ {
+ "id": "user",
+ "type": "external",
+ "label": "用户",
+ "sublabel": "手机微信"
+ },
+ {
+ "id": "pos",
+ "type": "frontend",
+ "label": "收银台",
+ "sublabel": "门店 POS"
+ },
+ {
+ "id": "svc",
+ "type": "backend",
+ "label": "支付服务",
+ "sublabel": "订单与对账"
+ },
+ {
+ "id": "wx",
+ "type": "external",
+ "label": "微信支付",
+ "sublabel": "统一下单"
+ },
+ {
+ "id": "mq",
+ "type": "messagebus",
+ "label": "消息队列",
+ "sublabel": "支付事件"
+ },
+ {
+ "id": "erp",
+ "type": "backend",
+ "label": "ERP",
+ "sublabel": "库存与财务"
+ }
+ ],
+ "messages": [
+ {
+ "id": "m1",
+ "from": "pos",
+ "to": "svc",
+ "y": 160,
+ "label": "创建支付单"
+ },
+ {
+ "id": "m2",
+ "from": "svc",
+ "to": "wx",
+ "y": 192,
+ "label": "统一下单 (NATIVE)",
+ "variant": "emphasis"
+ },
+ {
+ "id": "m3",
+ "from": "wx",
+ "to": "svc",
+ "y": 224,
+ "label": "返回 code_url",
+ "variant": "return"
+ },
+ {
+ "id": "m4",
+ "from": "svc",
+ "to": "pos",
+ "y": 256,
+ "label": "展示二维码",
+ "variant": "return"
+ },
+ {
+ "id": "m5",
+ "from": "user",
+ "to": "wx",
+ "y": 288,
+ "label": "扫码并确认支付"
+ },
+ {
+ "id": "m6",
+ "from": "wx",
+ "to": "svc",
+ "y": 320,
+ "label": "异步通知支付结果",
+ "variant": "dashed",
+ "note": "需验签,并按订单号幂等处理"
+ },
+ {
+ "id": "m7",
+ "from": "svc",
+ "to": "wx",
+ "y": 352,
+ "label": "返回 SUCCESS",
+ "variant": "return"
+ },
+ {
+ "id": "m8",
+ "from": "svc",
+ "to": "mq",
+ "y": 384,
+ "label": "发布 支付成功 事件",
+ "variant": "dashed"
+ },
+ {
+ "id": "m9",
+ "from": "mq",
+ "to": "erp",
+ "y": 416,
+ "label": "扣减库存 记账",
+ "variant": "dashed"
+ },
+ {
+ "id": "m10",
+ "from": "pos",
+ "to": "svc",
+ "y": 448,
+ "label": "轮询订单状态"
+ },
+ {
+ "id": "m11",
+ "from": "svc",
+ "to": "pos",
+ "y": 480,
+ "label": "已支付",
+ "variant": "return"
+ }
+ ],
+ "segments": [
+ {
+ "from": 140,
+ "to": 300,
+ "label": "下单"
+ },
+ {
+ "from": 300,
+ "to": 520,
+ "label": "支付与通知"
+ }
+ ]
+}
diff --git a/test/sequence-segment-labels.test.mjs b/test/sequence-segment-labels.test.mjs
new file mode 100644
index 00000000..76447395
--- /dev/null
+++ b/test/sequence-segment-labels.test.mjs
@@ -0,0 +1,57 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const renderer = path.resolve(__dirname, '..', 'archify', 'renderers', 'sequence', 'render-sequence.mjs');
+// An unedited first draft with two abutting segments (140-300, 300-520). On
+// dev the first label climbed behind the participant headers and the second
+// climbed into the first segment, where it named the wrong phase.
+const fixture = path.join(__dirname, 'fixtures', 'sequence-first-draft', 'scan-to-pay.sequence.json');
+const PARTICIPANT_BOTTOM = 72 + 60;
+
+function render(diagram) {
+ const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-sequence-segments-'));
+ const input = path.join(directory, 'candidate.json');
+ const output = path.join(directory, 'candidate.html');
+ fs.writeFileSync(input, JSON.stringify(diagram));
+ const result = spawnSync(process.execPath, [renderer, input, output], { cwd: directory, encoding: 'utf8' });
+ return { ...result, html: result.status === 0 ? fs.readFileSync(output, 'utf8') : '' };
+}
+
+const labels = (html) => [...html.matchAll(/data-segment-id="(\d+)">\s*<rect x="([\d.]+)" y="([\d.-]+)" width="([\d.]+)" height="([\d.]+)"/g)]
+ .map((match) => ({ index: +match[1], y: +match[3], height: +match[5] }));
+
+test('abutting segment labels stay in their own phase and clear of the participant headers', () => {
+ const diagram = JSON.parse(fs.readFileSync(fixture, 'utf8'));
+ const result = render(diagram);
+ assert.equal(result.status, 0, result.stdout + result.stderr);
+ const placed = labels(result.html);
+ assert.equal(placed.length, diagram.segments.length);
+ for (const label of placed) {
+ const own = diagram.segments[label.index];
+ assert.ok(label.y >= PARTICIPANT_BOTTOM, `segment ${label.index} label is behind the participant headers`);
+ for (const [index, other] of diagram.segments.entries()) {
+ if (index === label.index) continue;
+ const inside = Math.min(label.y + label.height, other.to) - Math.max(label.y, other.from);
+ assert.ok(inside <= label.height / 2, `segment ${label.index} label sits in segment ${index}`);
+ }
+ assert.ok(label.y + label.height > own.from - 24 && label.y < own.to, `segment ${label.index} label is detached from its frame`);
+ }
+});
+
+test('a label that fits above a spaced frame keeps its place above it', () => {
+ const diagram = JSON.parse(fs.readFileSync(fixture, 'utf8'));
+ diagram.segments = [{ from: 330, to: 520, label: 'pay' }];
+ for (const message of diagram.messages) message.y += message.y >= 300 ? 40 : 0;
+ diagram.segments[0].from = 340;
+ diagram.segments[0].to = 560;
+ const result = render(diagram);
+ assert.equal(result.status, 0, result.stdout + result.stderr);
+ const [label] = labels(result.html);
+ assert.ok(label.y + label.height <= 340, `label at ${label.y} should stay above the frame`);
+});