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 grid routes for compatible port pins

tt-a1ia4a52850ecc0
diff --git a/archify.zip b/archify.zip
index 7c9333ee..19ade230 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 6d54de09..8b8f4f8d 100644
--- a/archify/renderers/lifecycle/README.md
+++ b/archify/renderers/lifecycle/README.md
@@ -92,8 +92,9 @@ 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
+Explicit `fromSide` / `toSide` values remain authoritative. Pins that match the
+grid router's chosen sides keep its routes and adaptive row gaps. If an automatic
+transition pins a different side, the scene uses the shared side-aware obstacle
planner, retaining the v2 state grid and shared port spreading.
## Layout budget (v1)
diff --git a/archify/renderers/lifecycle/render-lifecycle.mjs b/archify/renderers/lifecycle/render-lifecycle.mjs
index 0d30e55d..91904ad3 100644
--- a/archify/renderers/lifecycle/render-lifecycle.mjs
+++ b/archify/renderers/lifecycle/render-lifecycle.mjs
@@ -72,13 +72,6 @@ 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,
@@ -245,21 +238,30 @@ function measureState(state) {
}
const states = new Map(asArray(lifecycle.states).map((state) => [state.id, measureState(state)]));
+const plannedTransitions = asArray(lifecycle.transitions).filter(plannerRouted);
const v2Rows = laneRowOrder();
const v2RowOf = (state) => (v2Rows.includes(state.lane) ? v2Rows.indexOf(state.lane) : undefined);
+let useGridRouter = isV2;
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 = useGridRouter ? createLifecycleGridRouter(states, asArray(lifecycle.transitions).filter(plannerRouted), {
+ const probe = createLifecycleGridRouter(states, plannedTransitions, {
rowOf: v2RowOf, columnXs: v2ColumnCenters,
- }) : null;
+ });
+ // Compatible pins keep the grid layout. A conflicting pin sends the whole
+ // scene to the side-aware planner so all edges still share port spreading
+ // and obstacle reservations.
+ useGridRouter = plannedTransitions.every(transition => {
+ const sides = probe.connectionSides(transition);
+ return ['fromSide', 'toSide'].every(key => !transition[key] || transition[key] === 'auto' || transition[key] === sides[key]);
+ });
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) || 0);
+ top += rowHeight + Math.max(layoutV2.rowPitch - layoutV2.stateH, useGridRouter ? probe.gapHeight(index) : 0);
});
for (const state of asArray(lifecycle.states)) states.set(state.id, measureState(state));
}
@@ -616,7 +618,6 @@ function plannerRouted(transition) {
&& transition.channelY === undefined;
}
-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 = useGridRouter ? createLifecycleGridRouter(states, plannedTransitions, {
diff --git a/archify/test/lifecycle-v2-layout.test.mjs b/archify/test/lifecycle-v2-layout.test.mjs
index d1e827f5..16588a20 100644
--- a/archify/test/lifecycle-v2-layout.test.mjs
+++ b/archify/test/lifecycle-v2-layout.test.mjs
@@ -181,6 +181,44 @@ 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, sides] of [
+ ['both', { fromSide: 'right', toSide: 'left' }],
+ ['source-only', { fromSide: 'right' }],
+ ['target-only', { toSide: 'left' }],
+]) {
+ test(`v2 compatible side pins preserve grid routes and parallel pairs: ${name}`, () => {
+ const doc = v2SessionDocument();
+ const automatic = render(`compatible-${name}-automatic`, doc);
+ assert.equal(automatic.code, 0, automatic.stderr);
+ Object.assign(doc.transitions.find(transition => transition.id === 'pause'), sides);
+ const pinned = render(`compatible-${name}-pinned`, doc);
+ assert.equal(pinned.code, 0, pinned.stderr);
+ const svg = svgOf(pinned.output);
+ const routes = Object.fromEntries([...svg.matchAll(/data-edge-id="([^"]+)"[^>]*data-composition-points="([^"]+)"/g)]
+ .map(match => [match[1], match[2].split(';').map(point => point.split(',').map(Number))]));
+ for (const id of ['pause', 'resume', 'drop', 'rejoin']) assert.equal(routes[id].length, 2, `${id} stays straight`);
+ assert.notEqual(routes.pause[0][1], routes.resume[0][1], 'horizontal reciprocal routes stay separate');
+ assert.notEqual(routes.drop[0][0], routes.rejoin[0][0], 'vertical reciprocal routes stay separate');
+ assert.equal(svg, svgOf(automatic.output), 'compatible pins preserve all routes, labels, and row gaps');
+ const result = validate(`compatible-${name}`, doc);
+ assert.equal(result.code, 0, result.stdout || result.stderr);
+ });
+}
+
+test('v2 deployment example keeps its grid layout with a compatible cross-row pin', () => {
+ const doc = JSON.parse(fs.readFileSync(path.join(skillRoot, 'examples/deployment-release.lifecycle.json'), 'utf8'));
+ const automatic = render('deployment-automatic', doc);
+ assert.equal(automatic.code, 0, automatic.stderr);
+ Object.assign(doc.transitions.find(transition => transition.from === 'ready' && transition.to === 'rollback'), {
+ fromSide: 'bottom', toSide: 'top',
+ });
+ const pinned = render('deployment-compatible', doc);
+ assert.equal(pinned.code, 0, pinned.stderr);
+ assert.equal(svgOf(pinned.output), svgOf(automatic.output), 'a redundant pin must not change the diagram');
+ const result = validate('deployment-compatible', doc);
+ assert.equal(result.code, 0, result.stdout || result.stderr);
+});
+
for (const [name, lane, sides] of [
['same-row-bottom', 'main', { fromSide: 'bottom', toSide: 'bottom' }],
['cross-row-right', 'wait', { fromSide: 'right', toSide: 'right' }],