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): preserve transitions with notes only

To3akaRin485f4d2cb6b6
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 84968796..d7e559dc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -19,6 +19,7 @@ All notable changes are documented here. Format loosely follows [Keep a Changelo
- **Japanese entry point under the same maintenance contract.** `README_JA.md` joins the language switcher and every README parity check: brand mark and demo-section placement, the animated proof and demo deep links, share-card and real-repository proofs, the update-awareness disclosure, the Hermes Agent and DSH installation rows, the self-hosted Star History ending, and release-identity validation of the version badge, the Japanese development marker, and the Raven manual-ZIP boundary. The switcher check is now driven by one per-language table, so a future language is added in one place.
### Fixed
+- **Lifecycle transition notes (#549).** Notes render when the transition label is omitted or empty, with matching route-space reservations and collision checks; existing label-only and label-plus-note layouts retain their behavior.
- **Brand content-encoding negotiation (#514).** Capture and pinned re-fetches request identity encoding and reject unexpected encoded response bodies before parsing or hashing, with the coding error preserved if favicon fallback also fails.
- **Escaped brand icon URLs (#454).** Favicon discovery decodes basic named and numeric HTML character references once before URL resolution, preserving percent escapes and the existing network and digest checks.
- **Brand HTML head boundaries.** Favicon capture ignores apparent head endings inside comments, raw text and quoted attributes while retaining bounded, streaming head reads.
diff --git a/archify.zip b/archify.zip
index 471b4ed1..6034cbe9 100644
Binary files a/archify.zip and b/archify.zip differ
diff --git a/archify/renderers/lifecycle/README.md b/archify/renderers/lifecycle/README.md
index 2b6ef27c..fe566e02 100644
--- a/archify/renderers/lifecycle/README.md
+++ b/archify/renderers/lifecycle/README.md
@@ -82,6 +82,14 @@ furthest occupied phase column. Route presets for transitions: `straight`,
`via` points, or the default `auto`. Multi-segment transitions get rounded
corners; tune them with `cornerRadius` (default 10, `0` for sharp bends).
+Transition `label` and `note` are independently optional. A non-empty `note`
+renders even when `label` is omitted or empty, using its existing secondary
+text style on a single row and retaining the note's fine-detail visibility.
+With both fields present, the note stays below the label. Notes participate in
+automatic label placement, route-space reservation, and label collision checks;
+the existing `labelAt`, `labelDx`, `labelDy`, and
+`labelSegment` controls also position a note-only text block.
+
## Design Rules
- Treat lifecycle diagrams as a phase map, not a dense state-transition graph.
diff --git a/archify/renderers/lifecycle/render-lifecycle.mjs b/archify/renderers/lifecycle/render-lifecycle.mjs
index 3418bd98..6d0ca363 100644
--- a/archify/renderers/lifecycle/render-lifecycle.mjs
+++ b/archify/renderers/lifecycle/render-lifecycle.mjs
@@ -389,8 +389,8 @@ function plannerRouted(transition) {
const plannedTransitions = asArray(lifecycle.transitions).filter(plannerRouted);
const planner = createRouter(states, plannedTransitions, {
- labelRectFor: (transition, points, { routes, labels }) => (transition.label ? reservedLabelRect({
- label: { relation: transition, label: transition.label, ...transitionLabelBoxAt(transition, labelPoint(transition, points)) },
+ labelRectFor: (transition, points, { routes, labels }) => ((transition.label || transition.note) ? reservedLabelRect({
+ label: { relation: transition, label: transition.label || transition.note, ...transitionLabelBoxAt(transition, labelPoint(transition, points)) },
points,
routes: routes.map((route, index) => ({ relationIndex: index, points: route })),
labels,
@@ -455,15 +455,15 @@ function transitionLabelBox(transition) {
function transitionLabelBoxAt(transition, [lx, ly]) {
const longestLine = Math.max(textUnits(transition.label), textUnits(transition.note || ''));
const width = Math.max(32, longestLine * 4.9 + 12);
- const height = transition.note ? 27 : 16;
+ const height = transition.label && transition.note ? 27 : 16;
return { x: lx - width / 2, y: ly - 11, width, height, lx, ly };
}
function transitionLabelRects() {
const rects = [];
for (const [relationIndex, transition] of asArray(lifecycle.transitions).entries()) {
- if (!transition.label || !states.has(transition.from) || !states.has(transition.to)) continue;
- rects.push({ relation: transition, relationIndex, label: transition.label, ...transitionLabelBox(transition) });
+ if (!(transition.label || transition.note) || !states.has(transition.from) || !states.has(transition.to)) continue;
+ rects.push({ relation: transition, relationIndex, label: transition.label || transition.note, ...transitionLabelBox(transition) });
}
return rects;
}
@@ -553,7 +553,7 @@ function renderTransitionPath(transition, index) {
const strokeWidth = transition.width || (transition.variant === 'emphasis' ? 2 : 1.1);
const automaticRoute = plannerRouted(transition);
const crossover = automaticRoute ? ' data-composition-crossover="halo"' : '';
- const edge = ` <path ${focusEdgeAttrs(transition.from, transition.to, transition.label, index, transition.id)} data-composition-points="${routePointsValue(routed.points)}"${crossover}${authoredStraightRouteAttrs(transition, routed.points)} d="${routed.d}" class="${cls}"${animateAttr(lifecycle.meta, 'edge', index)} stroke-width="${strokeWidth}" marker-end="url(#${marker})"/>`;
+ const edge = ` <path ${focusEdgeAttrs(transition.from, transition.to, transition.label || transition.note, index, transition.id)} data-composition-points="${routePointsValue(routed.points)}"${crossover}${authoredStraightRouteAttrs(transition, routed.points)} d="${routed.d}" class="${cls}"${animateAttr(lifecycle.meta, 'edge', index)} stroke-width="${strokeWidth}" marker-end="url(#${marker})"/>`;
if (!automaticRoute) return edge;
// Same presentation-only wrapper as architecture: the mask underlay lets two
// planner routes cross legibly while the viewer still sees one semantic edge.
@@ -562,14 +562,16 @@ function renderTransitionPath(transition, index) {
}
function renderTransitionLabel(transition, index) {
- if (!transition.label) return '';
+ if (!(transition.label || transition.note)) return '';
const { lx, ly, width: labelW, height: labelH } = transitionLabelBox(transition);
+ const label = transition.label
+ ? `\n <text x="${lx}" y="${ly}" class="${edgeLabelAccent(transition.variant)}" font-size="8" text-anchor="middle">${esc(transition.label)}</text>`
+ : '';
const note = transition.note
- ? `\n <text data-detail="fine" x="${lx}" y="${ly + 11}" class="t-dim" font-size="7" text-anchor="middle">${esc(transition.note)}</text>`
+ ? `\n <text data-detail="fine" x="${lx}" y="${ly + (transition.label ? 11 : 0)}" class="t-dim" font-size="7" text-anchor="middle">${esc(transition.note)}</text>`
: '';
- return ` <g data-detail="context" ${focusEdgeAttrs(transition.from, transition.to, transition.label, index, transition.id)}>
- <rect x="${lx - labelW / 2}" y="${ly - 11}" width="${labelW}" height="${labelH}" rx="4" class="c-mask"/>
- <text x="${lx}" y="${ly}" class="${edgeLabelAccent(transition.variant)}" font-size="8" text-anchor="middle">${esc(transition.label)}</text>${note}
+ return ` <g data-detail="${transition.label ? 'context' : 'fine'}" ${focusEdgeAttrs(transition.from, transition.to, transition.label || transition.note, index, transition.id)}>
+ <rect x="${lx - labelW / 2}" y="${ly - 11}" width="${labelW}" height="${labelH}" rx="4" class="c-mask"/>${label}${note}
</g>`;
}
diff --git a/archify/test/lifecycle-note-only.test.mjs b/archify/test/lifecycle-note-only.test.mjs
new file mode 100644
index 00000000..0069e41d
--- /dev/null
+++ b/archify/test/lifecycle-note-only.test.mjs
@@ -0,0 +1,201 @@
+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';
+import { parse } from 'parse5';
+
+const skillRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const cli = path.join(skillRoot, 'bin/archify.mjs');
+const attr = (node, name) => node.attrs?.find((item) => item.name === name)?.value;
+const walk = (node) => [node, ...(node.childNodes || []).flatMap(walk)];
+const text = (node) => node.nodeName === '#text' ? node.value : (node.childNodes || []).map(text).join('');
+
+function document(transition) {
+ return {
+ schema_version: 1, diagram_type: 'lifecycle',
+ meta: { title: 'Approval lifecycle', output: 'review.html', legend: { mode: 'hidden' } },
+ lanes: [{ id: 'main', label: 'Work' }],
+ states: [
+ { id: 'review', type: 'active', label: 'Review', lane: 'main', col: 0 },
+ { id: 'approved', type: 'success', label: 'Approved', lane: 'main', col: 2 },
+ ],
+ transitions: [{ id: 'approval', from: 'review', to: 'approved', ...transition }],
+ };
+}
+
+function fixture(t) {
+ const root = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-lifecycle-note-'));
+ t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+ return { input: path.join(root, 'input.json'), output: path.join(root, 'review.html') };
+}
+
+function run(data, command, value) {
+ fs.writeFileSync(data.input, JSON.stringify(value));
+ const result = spawnSync(process.execPath, [
+ cli, command, 'lifecycle', data.input,
+ ...(command === 'deliver' ? [data.output] : []), '--json',
+ ], { cwd: skillRoot, encoding: 'utf8', timeout: 30000 });
+ assert.ifError(result.error);
+ return { ...result, receipt: JSON.parse(result.stdout) };
+}
+
+function svg(data) {
+ const root = walk(parse(fs.readFileSync(data.output, 'utf8'))).find((node) => node.tagName === 'svg');
+ assert.ok(root, 'delivery must contain an SVG');
+ return root;
+}
+
+function edgeGeometry(root, id = 'approval') {
+ const node = walk(root).find((item) => item.tagName === 'path' && attr(item, 'data-edge-id') === id);
+ assert.ok(node, 'semantic transition path must exist');
+ return { d: attr(node, 'd'), points: attr(node, 'data-composition-points') };
+}
+
+function edgeTexts(root, id = 'approval') {
+ const group = walk(root).find((node) => node.tagName === 'g' && attr(node, 'data-edge-id') === id);
+ return group ? walk(group).filter((node) => node.tagName === 'text').map(text) : [];
+}
+
+for (const [name, transition] of [
+ ['omitted label with automatic routing', { note: 'manager sign-off' }],
+ ['empty label with automatic routing', { label: '', note: 'manager sign-off' }],
+ ['explicit straight route', { route: 'straight', note: 'manager sign-off' }],
+ ['explicit pinned label', { route: 'straight', labelAt: [300, 220], note: 'manager sign-off' }],
+ ['escaped CJK and special characters', { note: '审批 <通过> & "复核"' }],
+]) {
+ test(`lifecycle preserves note-only text: ${name}`, { timeout: 60000 }, (t) => {
+ const data = fixture(t);
+ const value = document(transition);
+ let explicitGeometry;
+ if (transition.route) {
+ const control = structuredClone(value);
+ delete control.transitions[0].note;
+ const initial = run(data, 'deliver', control);
+ assert.equal(initial.status, 0, initial.stdout);
+ explicitGeometry = edgeGeometry(svg(data));
+ }
+ const validation = run(data, 'validate', value);
+ assert.equal(validation.status, 0, validation.stdout);
+ const delivery = run(data, 'deliver', value);
+ assert.equal(delivery.status, 0, delivery.stdout);
+ assert.equal(delivery.receipt.ok, true);
+ // Inspect SVG text nodes, not embedded authored JSON or metadata.
+ assert.deepEqual(edgeTexts(svg(data)), [transition.note]);
+ const group = walk(svg(data)).find((node) => node.tagName === 'g' && attr(node, 'data-edge-id') === 'approval');
+ const note = walk(group).find((node) => node.tagName === 'text');
+ const mask = walk(group).find((node) => node.tagName === 'rect');
+ assert.equal(attr(group, 'data-detail'), 'fine');
+ assert.equal(attr(group, 'data-edge-label'), transition.note);
+ assert.equal(attr(note, 'data-detail'), 'fine');
+ assert.equal(attr(note, 'class'), 't-dim');
+ assert.equal(attr(note, 'font-size'), '7');
+ assert.equal(attr(mask, 'height'), '16');
+ if (transition.labelAt) assert.equal(Number(attr(note, 'y')), transition.labelAt[1]);
+ if (explicitGeometry) assert.deepEqual(edgeGeometry(svg(data)), explicitGeometry, 'preserve authored route geometry');
+ const paths = walk(svg(data)).filter((node) => node.tagName === 'path' && attr(node, 'data-edge-id') === 'approval');
+ assert.equal(paths.length, 1, 'keep exactly one semantic transition');
+ assert.equal(attr(paths[0], 'data-edge-label'), transition.note);
+ assert.equal(attr(paths[0], 'data-edge-from'), 'review');
+ assert.equal(attr(paths[0], 'data-edge-to'), 'approved');
+ });
+}
+
+for (const [name, transition, expected] of [
+ ['label and note', { label: 'approve', note: 'manager sign-off' }, ['approve', 'manager sign-off']],
+ ['label only', { label: 'approve' }, ['approve']],
+ ['no text', {}, []],
+ ['empty note', { note: '' }, []],
+]) {
+ test(`lifecycle preserves existing ${name} behavior`, { timeout: 60000 }, (t) => {
+ const data = fixture(t);
+ const result = run(data, 'deliver', document({ route: 'straight', ...transition }));
+ assert.equal(result.status, 0, result.stdout);
+ assert.deepEqual(edgeTexts(svg(data)), expected);
+ if (expected.length === 2) {
+ const group = walk(svg(data)).find((node) => node.tagName === 'g' && attr(node, 'data-edge-id') === 'approval');
+ const rows = walk(group).filter((node) => node.tagName === 'text');
+ assert.equal(attr(group, 'data-detail'), 'context');
+ assert.equal(attr(walk(group).find((node) => node.tagName === 'rect'), 'height'), '27');
+ assert.equal(Number(attr(rows[1], 'y')) - Number(attr(rows[0], 'y')), 11);
+ }
+ });
+}
+
+test('note-only text pinned inside a state is rejected without replacing the old artifact', { timeout: 60000 }, (t) => {
+ const data = fixture(t);
+ const initial = run(data, 'deliver', document({ route: 'straight' }));
+ assert.equal(initial.status, 0, initial.stdout);
+ const previous = fs.readFileSync(data.output);
+ const state = walk(svg(data)).find((node) => node.tagName === 'g' && attr(node, 'data-node-id') === 'review');
+ const rect = walk(state).find((node) => node.tagName === 'rect');
+ const pin = [Number(attr(rect, 'x')) + Number(attr(rect, 'width')) / 2,
+ Number(attr(rect, 'y')) + Number(attr(rect, 'height')) / 2];
+ const value = document({ route: 'straight', note: 'manager sign-off', labelAt: pin });
+ for (const command of ['validate', 'deliver']) {
+ const result = run(data, command, value);
+ assert.notEqual(result.status, 0, 'note-only geometry must participate in state collision checks');
+ assert.match(result.receipt.error, /overlaps state "review"/);
+ assert.deepEqual(fs.readFileSync(data.output), previous);
+ }
+});
+
+test('note-only text participates in collisions with another transition label', { timeout: 60000 }, (t) => {
+ const data = fixture(t);
+ const value = document({ route: 'straight', note: 'manager sign-off', labelAt: [300, 220] });
+ value.lanes.push({ id: 'terminal', label: 'Terminal' });
+ value.states.push(
+ { id: 'cancelled', type: 'failure', label: 'Cancelled', lane: 'terminal', col: 0 },
+ { id: 'archived', type: 'neutral', label: 'Archived', lane: 'terminal', col: 2 },
+ );
+ value.transitions.push({ id: 'archive', from: 'cancelled', to: 'archived', route: 'straight', label: 'archive', labelAt: [300, 220] });
+ // The same authored routes and ordinary label are valid without the note.
+ const control = structuredClone(value);
+ delete control.transitions[0].note;
+ const initial = run(data, 'deliver', control);
+ assert.equal(initial.status, 0, initial.stdout);
+ const previous = fs.readFileSync(data.output);
+ for (const command of ['validate', 'deliver']) {
+ const result = run(data, command, value);
+ assert.notEqual(result.status, 0, 'note-only text must be included in label collision checks');
+ assert.match(result.receipt.error, /Labels .*manager sign-off.*archive.* overlap/);
+ assert.deepEqual(fs.readFileSync(data.output), previous);
+ }
+});
+
+
+test('showcase planner reserves and places note-only text like equivalent ordinary labels', { timeout: 60000 }, (t) => {
+ const data = fixture(t);
+ const original = JSON.parse(fs.readFileSync(path.join(skillRoot,
+ 'test/fixtures/lifecycle-planner/approval.lifecycle.json'), 'utf8'));
+ assert.equal(original.meta.quality_profile, 'showcase');
+ const snapshots = {};
+ for (const mode of ['labels', 'notes', 'no-text']) {
+ const value = structuredClone(original);
+ for (const edge of value.transitions) {
+ if (mode === 'notes') edge.note = edge.label;
+ if (mode !== 'labels') delete edge.label;
+ }
+ const result = run(data, 'deliver', value);
+ assert.equal(result.status, 0, result.stdout);
+ const root = svg(data);
+ snapshots[mode] = {
+ routes: value.transitions.map(({ id }) => edgeGeometry(root, id)),
+ positions: value.transitions.map(({ id }) => {
+ const group = walk(root).find((node) => node.tagName === 'g' && attr(node, 'data-edge-id') === id);
+ return group ? walk(group).filter((node) => node.tagName === 'text')
+ .map((node) => [attr(node, 'x'), attr(node, 'y')]) : [];
+ }),
+ };
+ if (mode === 'notes') for (const edge of original.transitions) {
+ assert.deepEqual(edgeTexts(root, edge.id), [edge.label]);
+ }
+ }
+ // This dense real fixture needs label-aware routes. Merely drawing notes
+ // after planning would use the different, unreserved no-text routes.
+ assert.notDeepEqual(snapshots.notes.routes, snapshots['no-text'].routes);
+ assert.deepEqual(snapshots.notes.routes, snapshots.labels.routes);
+ assert.deepEqual(snapshots.notes.positions, snapshots.labels.positions);
+});