Skip to content

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

fix(sequence): pack few-participant automatic spread below 920px

tt-a1i71541a54180e
diff --git a/archify/references/authoring-contract.md b/archify/references/authoring-contract.md
index 5e16be16..865b0c04 100644
--- a/archify/references/authoring-contract.md
+++ b/archify/references/authoring-contract.md
@@ -319,7 +319,7 @@ not settle viewport fit. These are repair directions, not guaranteed coordinates
Participants are ordered by conversation role. Messages own their vertical order. Use return/async/security variants for meaning, not decoration; sequence does not use Automatic Port Spread. A segment's `from`/`to` edges must stay at least 4px off every message arrow (`message.y`): an edge along an arrow leaves the reader unable to tell which phase the message belongs to, and the renderer reports it.
-First-draft shape: every message needs an `id`, `from`, `to`, `label`, and integer `y` at least 160. `from` and `to` must be different participants — self-messages are unsupported (`sequence/self-message-unsupported`). Optional phase bands are `segments[]` with only `from`, `to`, and `label` (no segment `id`). Inventing `pos`/`size` on participants fails schema validation — order alone places them. Omit `meta.viewBox` so automatic height fits the timeline + legend (minimum 327px readable band) instead of a fixed 760px floor.
+First-draft shape: every message needs an `id`, `from`, `to`, `label`, and integer `y` at least 160. `from` and `to` must be different participants — self-messages are unsupported (`sequence/self-message-unsupported`). Optional phase bands are `segments[]` with only `from`, `to`, and `label` (no segment `id`). Inventing `pos`/`size` on participants fails schema validation — order alone places them. Omit `meta.viewBox` so automatic height fits the timeline + legend (minimum 327px readable band) instead of a fixed 760px floor, and so 2–3 participant spreads pack below the 920px default when labels fit (4+ stay at 920px; long labels still widen).
### Dataflow
diff --git a/archify/renderers/sequence/README.md b/archify/renderers/sequence/README.md
index 2f1ea990..a032ae18 100644
--- a/archify/renderers/sequence/README.md
+++ b/archify/renderers/sequence/README.md
@@ -66,7 +66,7 @@ muted text color.
| Constant | Value |
|----------|-------|
-| viewBox | automatic height fits content + legend (minimum 327px readable band); taller when late content needs more room; width defaults to 920 (wider for crowded spread). Schema minimum `[480, 480]` |
+| viewBox | automatic height fits content + legend (minimum 327px readable band); taller when late content needs more room; automatic width packs to 560–800px for 2–3 short-label participants (4+ default 920; long labels still widen). Schema minimum `[480, 480]` |
| Participant boxes | `spread` (default): viewBox-relative width from 86px up to 190px; `fixed`: 86px wide; both 60px tall at y 72 |
| Participant columns | `fixed`: centers at x = 62 + index×108; `spread`: columns distribute across the available viewBox width with at least a 16px card gutter |
| Participant count | the last box must end at or before width − 40; layouts that cannot fit fail closed |
diff --git a/archify/renderers/sequence/render-sequence.mjs b/archify/renderers/sequence/render-sequence.mjs
index ab3bc04b..a45595c4 100644
--- a/archify/renderers/sequence/render-sequence.mjs
+++ b/archify/renderers/sequence/render-sequence.mjs
@@ -70,12 +70,26 @@ function automaticCanvasWidth() {
textUnits(participant.label) * 6.8 <= width + 6
&& (!participant.sublabel || minimumNodeTextWidth(participant.sublabel, participantTextFit.sublabelMinimum) <= availableNodeTextWidth(width))
));
- if ((sequence.meta?.column_fit || 'spread') !== 'spread' || participantsFit(spreadParticipantWidth(920))) return 920;
+ const count = Math.max(1, asArray(sequence.participants).length);
+ const columnFitMode = sequence.meta?.column_fit || 'spread';
+ if (columnFitMode !== 'spread') return 920;
+ if (participantsFit(spreadParticipantWidth(920))) {
+ // Few-participant automatic canvases: keep readable box sizes but drop the
+ // empty gutters a 920px spread leaves beside 2–3 lifelines. Authored
+ // viewBoxes and the widen-for-labels path below are unchanged.
+ if (count <= 3) {
+ for (const candidate of [560, 640, 720, 800, 920]) {
+ const box = spreadParticipantWidth(candidate);
+ const span = count * box + (count - 1) * 16;
+ if (box >= 86 && participantsFit(box) && candidate - 80 >= span) return candidate;
+ }
+ }
+ return 920;
+ }
const needed = Math.max(...asArray(sequence.participants).map((participant) => Math.max(
textUnits(participant.label) * 6.8 - 6,
participant.sublabel ? minimumNodeTextWidth(participant.sublabel, participantTextFit.sublabelPreferred) + 86 - availableNodeTextWidth(86) : 0,
)));
- const count = Math.max(1, asArray(sequence.participants).length);
return Math.min(readableCanvasWidth, Math.max(920, Math.ceil((Math.min(190, needed) + 25) * count + 124)));
}
// A renderer-sized canvas grows to keep the legend clear of late messages and
diff --git a/test/sequence-column-fit.test.mjs b/test/sequence-column-fit.test.mjs
index 31f62294..8f94450a 100644
--- a/test/sequence-column-fit.test.mjs
+++ b/test/sequence-column-fit.test.mjs
@@ -229,6 +229,34 @@ test('narrow authored canvases reduce only the spread left margin to retain feas
});
+test('few-participant automatic spread packs below 920px when labels fit', () => {
+ for (const count of [2, 3]) {
+ const doc = {
+ schema_version: 1, diagram_type: 'sequence',
+ meta: { title: `${count} participants`, quality_profile: 'showcase' },
+ participants: Array.from({ length: count }, (_, index) => ({
+ id: `p${index}`, type: 'backend', label: `P${index}`,
+ })),
+ messages: [{ id: 'm0', from: 'p0', to: `p${count - 1}`, y: 200, label: 'ping' }],
+ };
+ const html = render(doc, true);
+ const width = Number(html.match(/<svg viewBox="0 0 (\d+) /)[1]);
+ assert.equal(width, 560, `${count}p should pack to 560, got ${width}`);
+ assert.match(html, /data-sequence-column-fit="spread"/);
+ }
+ // Four participants retain the established 920px spread contract.
+ const four = {
+ schema_version: 1, diagram_type: 'sequence',
+ meta: { title: 'Four participants', quality_profile: 'showcase' },
+ participants: Array.from({ length: 4 }, (_, index) => ({
+ id: `p${index}`, type: 'backend', label: `P${index}`,
+ })),
+ messages: [{ id: 'm0', from: 'p0', to: 'p3', y: 200, label: 'ping' }],
+ };
+ const fourHtml = render(four, true);
+ assert.match(fourHtml, /viewBox="0 0 920 /);
+});
+
test('eight participants fit the automatic 920px canvas with default and explicit spread', () => {
const doc = {
schema_version: 1, diagram_type: 'sequence', meta: { title: 'Eight participants' },