Skip to content

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

fix(lifecycle): keep transition labels clear of band titles

tt-a1i58901040fd97
diff --git a/archify.zip b/archify.zip
index b8fa820c..3a1e3d91 100644
Binary files a/archify.zip and b/archify.zip differ
diff --git a/archify/renderers/lifecycle/render-lifecycle.mjs b/archify/renderers/lifecycle/render-lifecycle.mjs
index 6d0ca363..760730ff 100644
--- a/archify/renderers/lifecycle/render-lifecycle.mjs
+++ b/archify/renderers/lifecycle/render-lifecycle.mjs
@@ -2,7 +2,7 @@ import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { esc, renderDefinitions, renderSemanticSigil, textUnits } from '../shared/utils.mjs';
import { animateAttr, focusEdgeAttrs, focusNodeAttrs, focusNodeTitle, loadDiagramWithBrandMarks, writeDiagram, svgAccessibleText, svgRootAttrs } from '../shared/cli.mjs';
-import { throwDiagnosticProblems } from '../shared/diagnostics.mjs';
+import { recordDiagnostic, throwDiagnosticProblems } from '../shared/diagnostics.mjs';
import { createRouter } from '../architecture/routing.mjs';
import { placeAutomaticLabels, reservedLabelRect } from '../architecture/labels.mjs';
import { resolveLegend, renderLegend as renderResolvedLegend } from '../shared/legend.mjs';
@@ -293,6 +293,21 @@ function validateLifecycle() {
}));
const labelRects = transitionLabelRects();
+ if (lifecycle.meta?.quality_profile === 'showcase') {
+ for (const rect of labelRects) {
+ for (const title of bandGeometry()) {
+ if (!rectsOverlap(rect, title)) continue;
+ const message = `Transition label "${rect.label}" overlaps lifecycle band title "${title.label}" — move the label with labelAt/labelDx/labelDy/labelSegment or provide more space.`;
+ recordDiagnostic({
+ code: 'composition/label-band-title-overlap', severity: 'error', message,
+ subject: { diagramType: 'lifecycle', collection: 'transitions', index: rect.relationIndex, from: rect.relation.from, to: rect.relation.to },
+ evidence: { labelRect: { x: rect.x, y: rect.y, width: rect.width, height: rect.height }, bandTitle: title },
+ supportedFixes: ['move the transition label with labelAt/labelDx/labelDy/labelSegment while preserving its text'],
+ });
+ problems.push(message);
+ }
+ }
+ }
for (const rect of labelRects) {
for (const state of states.values()) {
if (rectsOverlap(rect, state, -2)) {
@@ -478,7 +493,7 @@ if (lifecycle.meta?.quality_profile === 'showcase') {
? [{ relationIndex, points: pathFor(transition).points }] : []
)),
components: [...states.values()],
- titles: [],
+ titles: bandGeometry(),
viewBox,
placementBottom: lifecycleAreaBottom(),
});
@@ -497,15 +512,18 @@ function bandTitles() {
];
}
+function bandGeometry() {
+ return bandTitles().map((title, index) => {
+ const baseline = [100, 252, 424][index];
+ const label = `${String(index + 1).padStart(2, '0')} / ${title}`;
+ return { index, label, x: 72, y: baseline - 11, width: textUnits(label) * 6.2, height: 14, baseline };
+ });
+}
+
function renderBands() {
const right = viewBox[0] - 72;
- const titles = bandTitles();
- return ` <path d="M 72 112 L ${right} 112" class="a-default" stroke-width="0.8" stroke-dasharray="3,8"/>
- <text x="72" y="100" class="t-dim" font-size="10" font-weight="600">01 / ${esc(titles[0])}</text>
- <path d="M 72 264 L ${right} 264" class="a-default" stroke-width="0.8" stroke-dasharray="3,8"/>
- <text x="72" y="252" class="t-dim" font-size="10" font-weight="600">02 / ${esc(titles[1])}</text>
- <path d="M 72 436 L ${right} 436" class="a-default" stroke-width="0.8" stroke-dasharray="3,8"/>
- <text x="72" y="424" class="t-dim" font-size="10" font-weight="600">03 / ${esc(titles[2])}</text>`;
+ return bandGeometry().map((band) => ` <path d="M 72 ${band.baseline + 12} L ${right} ${band.baseline + 12}" class="a-default" stroke-width="0.8" stroke-dasharray="3,8"/>
+ <text x="${band.x}" y="${band.baseline}" class="t-dim" font-size="10" font-weight="600">${esc(band.label)}</text>`).join('\n');
}
function renderState(state) {
diff --git a/archify/test/fixtures/lifecycle-planner/band-title-overlap.lifecycle.json b/archify/test/fixtures/lifecycle-planner/band-title-overlap.lifecycle.json
new file mode 100644
index 00000000..d0b24162
--- /dev/null
+++ b/archify/test/fixtures/lifecycle-planner/band-title-overlap.lifecycle.json
@@ -0,0 +1,48 @@
+{
+ "schema_version": 1,
+ "diagram_type": "lifecycle",
+ "meta": {
+ "title": "线上书店订单生命周期",
+ "locale": "zh-CN",
+ "output": "diagram.html",
+ "animation": "none",
+ "quality_profile": "showcase"
+ },
+ "lanes": [
+ { "id": "main", "label": "下单与履约" },
+ { "id": "refund", "label": "退款申请" },
+ { "id": "retry", "label": "可恢复失败" },
+ { "id": "terminal", "label": "终态" }
+ ],
+ "states": [
+ { "id": "created", "type": "start", "label": "已创建", "sublabel": "订单生成", "lane": "main", "col": 0, "step": "01" },
+ { "id": "pending_payment", "type": "waiting", "label": "待支付", "sublabel": "等待付款事件", "lane": "main", "col": 1, "step": "02" },
+ { "id": "paid", "type": "active", "label": "已支付", "sublabel": "付款成功", "lane": "main", "col": 2, "step": "03" },
+ { "id": "preparing", "type": "active", "label": "备货中", "sublabel": "准备商品", "lane": "main", "col": 3, "step": "04" },
+ { "id": "shipped", "type": "waiting", "label": "已发货", "sublabel": "等待确认收货", "lane": "main", "col": 4, "step": "05" },
+ { "id": "refunding", "type": "active", "label": "退款处理中", "sublabel": "已申请退款", "lane": "refund", "col": 1 },
+ { "id": "refund_failed", "type": "failure", "label": "退款失败", "sublabel": "保留失败状态·可重试", "lane": "retry", "col": 0, "yOffset": 85 },
+ { "id": "cancelled", "type": "failure", "label": "已取消", "sublabel": "支付超时·释放库存", "lane": "terminal", "col": 0, "tag": "终态" },
+ { "id": "refunded", "type": "success", "label": "已退款", "sublabel": "退款成功", "lane": "terminal", "col": 1, "tag": "终态" },
+ { "id": "completed", "type": "success", "label": "已完成", "sublabel": "用户确认收货", "lane": "terminal", "col": 2, "tag": "终态" }
+ ],
+ "transitions": [
+ { "from": "created", "to": "pending_payment", "label": "订单创建", "variant": "emphasis" },
+ { "from": "pending_payment", "to": "paid", "label": "付款成功事件", "variant": "emphasis" },
+ { "from": "pending_payment", "to": "pending_payment", "label": "付款失败·重试支付", "variant": "dashed" },
+ { "from": "pending_payment", "to": "cancelled", "label": "超过付款期限·释放库存", "variant": "security" },
+ { "from": "paid", "to": "preparing", "label": "开始备货" },
+ { "from": "preparing", "to": "shipped", "label": "完成备货·发货", "variant": "emphasis" },
+ { "from": "shipped", "to": "completed", "label": "用户确认收货", "variant": "emphasis" },
+ { "from": "paid", "to": "refunding", "label": "申请退款" },
+ { "from": "preparing", "to": "refunding", "label": "申请退款" },
+ { "from": "refunding", "to": "refunded", "label": "退款成功" },
+ { "from": "refunding", "to": "refund_failed", "label": "退款失败" },
+ { "from": "refund_failed", "to": "refunding", "label": "重试退款", "variant": "dashed" }
+ ],
+ "cards": [
+ { "dot": "cyan", "title": "主流程", "items": ["付款成功触发已支付;随后备货、发货", "用户确认收货后,订单进入已完成"] },
+ { "dot": "amber", "title": "可恢复失败", "items": ["待支付时付款失败,可重试支付", "退款失败保留失败状态,可重试退款"] },
+ { "dot": "rose", "title": "终态与限制", "items": ["待支付超时才取消,并释放库存", "已取消、已退款、已完成是终态", "已发货不能直接取消"] }
+ ]
+}
diff --git a/archify/test/lifecycle-band-title.test.mjs b/archify/test/lifecycle-band-title.test.mjs
new file mode 100644
index 00000000..85284b29
--- /dev/null
+++ b/archify/test/lifecycle-band-title.test.mjs
@@ -0,0 +1,70 @@
+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, pathToFileURL } from 'node:url';
+import { ChromeVisualBrowser, findChrome } from '../bin/visual-check.mjs';
+const root = fileURLToPath(new URL('../', import.meta.url));
+const fixture = JSON.parse(fs.readFileSync(path.join(root, 'test/fixtures/lifecycle-planner/band-title-overlap.lifecycle.json')));
+function run(t, doc, command = 'validate') {
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-band-title-'));
+ t.after(() => fs.rmSync(dir, { recursive: true, force: true }));
+ const input = path.join(dir, 'input.json'), output = path.join(dir, 'output.html');
+ fs.writeFileSync(input, JSON.stringify(doc));
+ const args = command === 'render' ? [output] : ['--quality', doc.meta.quality_profile, '--json'];
+ const result = spawnSync(process.execPath, [path.join(root, 'bin/archify.mjs'), command, 'lifecycle', input, ...args], { encoding: 'utf8' });
+ return { ...result, output };
+}
+test('automatic lifecycle labels avoid band headings on the reported fixture', t => {
+ const result = run(t, fixture);
+ assert.equal(result.status, 0, result.stdout + result.stderr);
+});
+for (const [index, y] of [100, 252, 424].entries()) {
+ test(`explicit collision with band ${index + 1} is diagnosed without changing authored coordinates`, t => {
+ const doc = structuredClone(fixture);
+ doc.transitions[0].labelAt = [100, y - 5];
+ const result = run(t, doc);
+ assert.equal(result.status, 1, result.stdout);
+ const diagnostic = JSON.parse(result.stdout).diagnostics.find(d => d.code === 'composition/label-band-title-overlap');
+ assert.ok(diagnostic, result.stdout);
+ assert.equal(diagnostic.evidence.bandTitle.index, index);
+ assert.equal(diagnostic.subject.index, 0);
+ const box = diagnostic.evidence.labelRect;
+ assert.equal(box.x + box.width / 2, 100);
+ assert.equal(box.y + 11, y - 5);
+ });
+}
+test('standard preserves authored label placement', t => {
+ const doc = structuredClone(fixture);
+ doc.meta.quality_profile = 'standard';
+ doc.states = doc.states.slice(0, 2);
+ doc.transitions = doc.transitions.slice(0, 1);
+ doc.transitions[0].labelAt = [100, 95];
+ const result = run(t, doc, 'render');
+ assert.equal(result.status, 0, result.stdout + result.stderr);
+ assert.match(fs.readFileSync(result.output, 'utf8'), /<text x="100" y="95"/);
+});
+test('real browser keeps all band titles clear in both themes, including long Chinese headings', { skip: !process.env.ARCHIFY_CHROME }, async t => {
+ const browser = new ChromeVisualBrowser(findChrome());
+ try {
+ const session = await browser.sessionPromise;
+ await browser.cdp.send('Emulation.setDeviceMetricsOverride', { width: 1440, height: 900, deviceScaleFactor: 1, mobile: false }, session);
+ for (const long of [false, true]) {
+ const doc = structuredClone(fixture);
+ if (long) doc.lanes[0].label = '下单与履约流程及付款状态';
+ const result = run(t, doc, 'render');
+ assert.equal(result.status, 0, result.stdout + result.stderr);
+ for (const theme of ['light', 'dark']) {
+ const loaded = browser.cdp.waitFor('Page.loadEventFired', session);
+ await browser.cdp.send('Page.navigate', { url: `${pathToFileURL(result.output).href}?theme=${theme}` }, session);
+ await loaded;
+ const response = await browser.cdp.send('Runtime.evaluate', { awaitPromise: true, returnByValue: true, expression: `(async()=>{await document.fonts.ready;const titles=[...document.querySelectorAll('svg text')].filter(t=>/^0[123] \\/ /.test(t.textContent));const masks=[...document.querySelectorAll('g[data-edge-from] > rect.c-mask')];const hits=[];for(const title of titles){const a=title.getBBox();for(const mask of masks){const b=mask.getBBox();if(a.x<b.x+b.width&&a.x+a.width>b.x&&a.y<b.y+b.height&&a.y+a.height>b.y)hits.push(title.textContent);}}return {count:titles.length,hits};})()` }, session);
+ assert.equal(response.exceptionDetails, undefined);
+ assert.equal(response.result.value.count, 3);
+ assert.deepEqual(response.result.value.hits, [], `${theme}, long=${long}`);
+ }
+ }
+ } finally { await browser.close(); }
+});
diff --git a/scripts/run-browser-tests.mjs b/scripts/run-browser-tests.mjs
index a8698d6b..6bf76990 100644
--- a/scripts/run-browser-tests.mjs
+++ b/scripts/run-browser-tests.mjs
@@ -18,6 +18,7 @@ const testFiles = [
'compact-header-clearance.test.mjs',
'architecture-reading-size-browser.test.mjs',
'lifecycle-rail-browser.test.mjs',
+ 'lifecycle-band-title.test.mjs',
'export-cleanup-browser.test.mjs',
'offline-font-browser.test.mjs',
'i18n.test.mjs',