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(lifecycle): keep transition labels clear of band titles
tt-a1i58901040fd97
diff --git a/archify.zip b/archify.zipindex b8fa820c..3a1e3d91 100644Binary files a/archify.zip and b/archify.zip differdiff --git a/archify/renderers/lifecycle/render-lifecycle.mjs b/archify/renderers/lifecycle/render-lifecycle.mjsindex 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.jsonnew file mode 100644index 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.mjsnew file mode 100644index 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.mjsindex 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',