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): honor pinned ports and keep source badges clear

tt-a1icc8e44c41f46
diff --git a/archify.zip b/archify.zip
index 9caf3574..e6dcf741 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 3ed78205..6d54de09 100644
--- a/archify/renderers/lifecycle/README.md
+++ b/archify/renderers/lifecycle/README.md
@@ -92,6 +92,10 @@ transition between two `main` states without a `variant` renders as the
emphasized primary path. Showcase labels are ranked beside their line, then on
it, then outward past neighbouring parallels.
+Explicit `fromSide` / `toSide` values remain authoritative. If an automatic
+transition pins either side, the scene uses the shared side-aware obstacle
+planner, retaining the v2 state grid and shared port spreading.
+
## Layout budget (v1)
| Band | Lane id | Top y | Column centers | Default state |
diff --git a/archify/renderers/lifecycle/render-lifecycle.mjs b/archify/renderers/lifecycle/render-lifecycle.mjs
index 51e32db4..0d30e55d 100644
--- a/archify/renderers/lifecycle/render-lifecycle.mjs
+++ b/archify/renderers/lifecycle/render-lifecycle.mjs
@@ -72,6 +72,13 @@ const stateTextFit = lifecycle.schema_version === 2 ? {
// is shared between versions.
const isV2 = lifecycle.schema_version === 2;
const authoredViewBox = lifecycle.meta?.viewBox;
+// The grid planner chooses facing sides. Once any automatic edge pins a
+// side, route that scene with the shared side-aware planner so pinned and
+// unpinned edges still share port spreading and obstacle reservations.
+const useGridRouter = isV2 && !asArray(lifecycle.transitions).some(transition => (
+ plannerRouted(transition)
+ && [transition.fromSide, transition.toSide].some(side => side && side !== 'auto')
+));
const layout = {
phaseY: 126,
@@ -243,16 +250,16 @@ const v2RowOf = (state) => (v2Rows.includes(state.lane) ? v2Rows.indexOf(state.l
if (isV2) {
// Route once to learn how many horizontal tracks each row gap carries,
// then open every gap to fit them before the final routing pass.
- const probe = createLifecycleGridRouter(states, asArray(lifecycle.transitions).filter(plannerRouted), {
+ const probe = useGridRouter ? createLifecycleGridRouter(states, asArray(lifecycle.transitions).filter(plannerRouted), {
rowOf: v2RowOf, columnXs: v2ColumnCenters,
- });
+ }) : null;
let top = layoutV2.firstRowTop;
v2Rows.forEach((laneId, index) => {
const rowHeight = Math.max(layoutV2.stateH, ...[...states.values()]
.filter((state) => state.lane === laneId)
.map((state) => state.y + state.height - v2RowTop.get(laneId)));
v2RowTop.set(laneId, top);
- top += rowHeight + Math.max(layoutV2.rowPitch - layoutV2.stateH, probe.gapHeight(index));
+ top += rowHeight + Math.max(layoutV2.rowPitch - layoutV2.stateH, probe?.gapHeight(index) || 0);
});
for (const state of asArray(lifecycle.states)) states.set(state.id, measureState(state));
}
@@ -612,7 +619,7 @@ function plannerRouted(transition) {
const plannedTransitions = asArray(lifecycle.transitions).filter(plannerRouted);
// v2 states sit on a fixed row/column grid, so automatic transitions use the
// dedicated orthogonal grid router; v1 keeps the shared obstacle planner.
-const planner = isV2 ? createLifecycleGridRouter(states, plannedTransitions, {
+const planner = useGridRouter ? createLifecycleGridRouter(states, plannedTransitions, {
rowOf: v2RowOf,
columnXs: v2ColumnCenters,
}) : createRouter(states, plannedTransitions, {
@@ -647,7 +654,7 @@ function pathFor(transition) {
if (pathCache.has(transition)) return pathCache.get(transition);
if (plannerRouted(transition)) {
let routed = planner.pathFor(transition);
- if (isV2) routed = { d: roundedPath(routed, transition.cornerRadius ?? 10), points: routed };
+ if (useGridRouter) routed = { d: roundedPath(routed, transition.cornerRadius ?? 10), points: routed };
pathCache.set(transition, routed);
return routed;
}
diff --git a/archify/renderers/shared/text-fit.mjs b/archify/renderers/shared/text-fit.mjs
index 79211f58..76e6719c 100644
--- a/archify/renderers/shared/text-fit.mjs
+++ b/archify/renderers/shared/text-fit.mjs
@@ -77,6 +77,23 @@ export function nodeLabelLayout({ width, height, rows, side = 'left', brand = fa
result.ys = ys;
return result;
}
+ if (source) {
+ // A source badge adds a second decoration on the right. On short boxes,
+ // restoring the original rows would put the title back under that badge.
+ // Try compact leading before giving up the dedicated text rail. Retain
+ // every font size and the authored box; only this crowded fallback packs
+ // the rows, with a full em above each baseline and 0.3 em below it.
+ let compactBottom = Math.max(brand ? 22 : SEMANTIC_SIGIL_FOOTPRINT, 19) + 1;
+ const compactYs = rows.map(row => {
+ const y = Math.ceil((compactBottom + 1 + row.font) * 10) / 10;
+ compactBottom = y + row.font * 0.3;
+ return y;
+ });
+ if (compactBottom <= height - 2) {
+ result.ys = compactYs;
+ return result;
+ }
+ }
// A deliberately short fixed box may have no spare row. Preserve its text
// and geometry, and fit only the decorative sigil in the space above it.
result.sigilY = 1;
diff --git a/archify/test/lifecycle-v2-layout.test.mjs b/archify/test/lifecycle-v2-layout.test.mjs
index 7f10e65e..d1e827f5 100644
--- a/archify/test/lifecycle-v2-layout.test.mjs
+++ b/archify/test/lifecycle-v2-layout.test.mjs
@@ -181,6 +181,48 @@ test('v2 grid routes are orthogonal and reciprocal pairs run as parallel lines',
assert.notEqual(routes.drop[0][0], routes.rejoin[0][0]);
});
+for (const [name, lane, sides] of [
+ ['same-row-bottom', 'main', { fromSide: 'bottom', toSide: 'bottom' }],
+ ['cross-row-right', 'wait', { fromSide: 'right', toSide: 'right' }],
+ ['source-only', 'main', { fromSide: 'bottom' }],
+ ['target-only', 'wait', { toSide: 'left' }],
+]) {
+ test(`v2 automatic routes honor authored sides: ${name}`, () => {
+ const doc = v2SessionDocument({ doc: {
+ states: [
+ { id: 'a', type: 'active', label: 'A', lane: 'main', col: 0 },
+ { id: 'b', type: 'success', label: 'B', lane, col: 1 },
+ { id: 'c', type: 'waiting', label: 'C', lane: 'wait', col: 0 },
+ ],
+ transitions: [
+ { id: 'pinned', from: 'a', to: 'b', ...sides },
+ { from: 'a', to: 'c' },
+ ],
+ } });
+ const result = validate(name, doc);
+ assert.equal(result.code, 0, result.stdout || result.stderr);
+ const rendered = render(name, doc);
+ assert.equal(rendered.code, 0, rendered.stderr);
+ const svg = svgOf(rendered.output);
+ const rects = stateRects(svg);
+ const points = svg.match(/data-edge-id="pinned"[^>]*data-composition-points="([^"]+)"/)[1]
+ .split(';').map(point => point.split(',').map(Number));
+ for (const [field, node, point, next] of [
+ ['fromSide', rects.a, points[0], points[1]],
+ ['toSide', rects.b, points.at(-1), points.at(-2)],
+ ]) {
+ const side = sides[field];
+ if (!side) continue;
+ const vertical = side === 'top' || side === 'bottom';
+ const axis = vertical ? 1 : 0;
+ const positive = side === 'bottom' || side === 'right';
+ assert.equal(point[axis], vertical ? node.y + (positive ? node.height : 0) : node.x + (positive ? node.width : 0));
+ assert.equal(point[1 - axis], next[1 - axis], `${field}: perpendicular segment`);
+ assert.ok(positive ? next[axis] > point[axis] : next[axis] < point[axis], `${field}: outward segment`);
+ }
+ });
+}
+
test('v2 start states get an initial marker and final states a double border', () => {
const doc = v2SessionDocument({ name: 'session-markers' });
doc.states = doc.states.map((s) => (s.lane === 'main' ? { ...s, col: s.col + 1 } : s));
diff --git a/archify/test/repository-evidence-types-browser.test.mjs b/archify/test/repository-evidence-types-browser.test.mjs
index 1c4bcef6..5329d452 100644
--- a/archify/test/repository-evidence-types-browser.test.mjs
+++ b/archify/test/repository-evidence-types-browser.test.mjs
@@ -33,6 +33,16 @@ test('non-architecture sources reach real Viewer beacons, Focus and Finder', {
['dataflow', 'nodes', 'product-analytics.dataflow.json', true, 'light'],
['lifecycle', 'states', 'agent-run.lifecycle.json', true, 'dark'],
['lifecycle', 'states', 'deployment-release.lifecycle.json', false, 'light', { brand: 'github' }],
+ ['lifecycle', 'states', 'agent-run.lifecycle.json', false, 'light', {
+ label: 'API', sublabel: 'source data', tag: undefined, step: undefined,
+ width: 92, height: 52, brand: 'github',
+ }],
+ ['lifecycle', 'states', 'deployment-release.lifecycle.json', false, 'dark', {
+ label: 'Offline mode', sublabel: 'source data', tag: 'waiting', step: undefined, brand: 'github',
+ }],
+ ['lifecycle', 'states', 'deployment-release.lifecycle.json', false, 'light', {
+ label: '等待人工审批确认', sublabel: '来源已核验', tag: '等待中', step: '02',
+ }],
];
for (const [type, collection, example, local, theme, extra = {}] of cases) {
const url = local ? 'http://git.internal/Team/repo' : 'https://github.com/example/evidence-repo';
@@ -57,13 +67,31 @@ test('non-architecture sources reach real Viewer beacons, Focus and Finder', {
return other && beaconBox && beaconBox.left < other.right && other.left < beaconBox.right
&& beaconBox.top < other.bottom && other.top < beaconBox.bottom;
}).map(([name]) => name);
+ const texts = [...node.querySelectorAll('text:not(.source-evidence-beacon text)')];
+ // Fine-detail tags/steps must also fit when zoom reveals them.
+ texts.forEach(text => {
+ text.style.setProperty('display', 'inline', 'important');
+ text.style.setProperty('opacity', '1', 'important');
+ });
+ const textCollisions = texts.flatMap((text, index) => texts.slice(index + 1).flatMap(other => {
+ const a = box(text), b = box(other);
+ return a.width && b.width && a.left < b.right && b.left < a.right && a.top < b.bottom && b.top < a.bottom
+ ? [[text.textContent, other.textContent]] : [];
+ }));
+ const shape = box(node.querySelector('rect'));
+ const overflowingText = texts.filter(text => {
+ const b = box(text);
+ return b.width && (b.top < shape.top || b.bottom > shape.bottom || b.left < shape.left || b.right > shape.right);
+ }).map(text => text.textContent);
node.dispatchEvent(new MouseEvent('click', {bubbles:true}));
const panel = document.getElementById('focus-evidence');
const rows = [...panel.querySelectorAll('.semantic-passport-source')];
const finder = document.getElementById('node-finder-input');
finder.value = 'source.js';
finder.dispatchEvent(new Event('input', {bubbles:true}));
- return { visible: !panel.hidden, beacon: !!node.querySelector('[data-source-evidence-beacon]'), collisions,
+ return { visible: !panel.hidden, beacon: !!node.querySelector('[data-source-evidence-beacon]'), collisions, textCollisions, overflowingText,
+ nodeSize: ['width', 'height'].map(key => Number(node.querySelector('rect').getAttribute(key))),
+ labelFont: Number(node.querySelector('text[data-node-label]').getAttribute('font-size')),
hasBrand: !!node.querySelector('.brand-mark'),
paths: rows.map(r => r.querySelector('small').textContent),
links: rows.filter(r => r.tagName === 'A').map(r => r.getAttribute('href')),
@@ -75,6 +103,12 @@ test('non-architecture sources reach real Viewer beacons, Focus and Finder', {
assert.equal(result.visible, true, type);
assert.equal(result.beacon, true, type);
assert.deepEqual(result.collisions, [], `${type} ${example}: the source badge must not cover the node's sigil, brand, or label`);
+ if (Object.keys(extra).length > 1) {
+ assert.deepEqual(result.textCollisions, [], `${type} ${node.label}: compact rows must remain separate`);
+ assert.deepEqual(result.overflowingText, [], `${type} ${node.label}: compact rows must remain inside the authored box`);
+ assert.deepEqual(result.nodeSize, [extra.width || 140, extra.height || 64], 'retain authored/default box dimensions');
+ assert.equal(result.labelFont, diagram.schema_version === 2 ? 11 : 10, 'retain the label font size');
+ }
assert.equal(result.hasBrand, Boolean(extra.brand), `${type} ${example}: brand fixture`);
assert.deepEqual(result.paths, ['source.js'], type);
assert.deepEqual(result.links, local ? [] : [`${url}/blob/${revision}/source.js#L1-L3`], type);