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): 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.mjsindex 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.jsonnew file mode 100644index 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.mjsnew file mode 100644index 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`);+});