Skip to content

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

Merge latest dev into fix/sequence-note-wrap

yarrbakr4b86332b3e98
diff --cc archify.zip
index 6e7bef64,5b65b36d..bdc02743
Binary files differ
diff --cc archify/renderers/sequence/render-sequence.mjs
index 0137f200,805768cc..9d11f695
--- a/archify/renderers/sequence/render-sequence.mjs
+++ b/archify/renderers/sequence/render-sequence.mjs
@@@ -46,156 -46,44 +46,164 @@@ function legendEntries()
// needs LEGEND_BLOCK_HEIGHT (title glyphs, row, and the 54px baseline inset).
const LEGEND_CONTENT_GAP = 12;
const LEGEND_BLOCK_HEIGHT = 86;
-const contentBottom = Math.max(
- 0,
- ...asArray(sequence.messages).map((message) => message.y + (message.note ? 22 : 6)),
- ...asArray(sequence.activations).map((activation) => activation.to),
- ...asArray(sequence.segments).map((segment) => segment.to),
-);
-function legendRequiredHeight(width) {
- const entries = legendEntries();
- if (!entries.length) return 0;
- return Math.ceil(contentBottom + LEGEND_CONTENT_GAP + LEGEND_BLOCK_HEIGHT
- + legendFootprint(entries, { width: width - 80 }).extraHeight);
-}
-// A renderer-sized canvas grows to keep the legend clear of late messages;
-// an authored viewBox is honored and validated below.
-const viewBox = sequence.meta?.viewBox || [920, Math.max(760, legendRequiredHeight(920))];
-// The timeline scales with viewBox height: a taller viewBox gains message room,
-// a shorter one shrinks the readable band (validated below) instead of clipping.
+
+// Column geometry depends only on the canvas width, which is known before the
+// automatic height is: notes wrap inside lane gaps, and their wrapped height
+// feeds that automatic height.
// `column_fit: "spread"` widens the lanes with the viewBox instead of keeping
// the fixed 108px gap, so a wide canvas gains column distance and label room
- // rather than dead space on the right. The default stays "fixed" so existing
- // diagrams keep their coordinates.
+ // rather than dead space on the right. Spread is the default on both automatic
+ // and authored canvases; explicit fixed retains historical coordinates.
+const canvasWidth = sequence.meta?.viewBox?.[0] ?? 920;
- const columnFit = sequence.meta?.column_fit === 'spread' ? 'spread' : 'fixed';
+ const columnFit = sequence.meta?.column_fit || 'spread';
const participantCount = Math.max(1, asArray(sequence.participants).length);
- const sideMargin = 62;
+ const preferredSideMargin = 62;
const participantW = columnFit === 'spread'
- ? Math.max(86, Math.min(190, Math.round((canvasWidth - sideMargin * 2) / participantCount) - 24))
- ? Math.max(86, Math.min(190, Math.round((viewBox[0] - preferredSideMargin * 2) / participantCount) - 24))
++ ? Math.max(86, Math.min(190, Math.round((canvasWidth - preferredSideMargin * 2) / participantCount) - 24))
: 86;
+ // Narrow feasible frames can reduce the left margin, while ordinary frames
+ // keep 62px. Compute card width first so this does not change its sizing rule.
+ const minimumParticipantSpan = participantCount * participantW + (participantCount - 1) * 16;
+ const sideMargin = columnFit === 'spread'
- ? Math.max(40, Math.min(preferredSideMargin, viewBox[0] - 40 - minimumParticipantSpan))
++ ? Math.max(40, Math.min(preferredSideMargin, canvasWidth - 40 - minimumParticipantSpan))
+ : preferredSideMargin;
+ // Fit the authored width when feasible, preserving a real 16px card gutter.
+ // Infeasible frames retain that minimum and fail the capacity check below.
const colGap = columnFit === 'spread' && participantCount > 1
- ? Math.max(108, (canvasWidth - 40 - sideMargin - participantW) / (participantCount - 1))
- ? Math.max(participantW + 16, (viewBox[0] - 40 - sideMargin - participantW) / (participantCount - 1))
++ ? Math.max(participantW + 16, (canvasWidth - 40 - sideMargin - participantW) / (participantCount - 1))
: 108;
+const leftX = columnFit === 'spread' ? sideMargin + participantW / 2 : sideMargin;
+const participantIndexById = new Map(asArray(sequence.participants).map((participant, index) => [participant.id, index]));
+
+function participantX(index) {
+ return leftX + index * colGap;
+}
+
+// A note wraps inside one gap between neighbouring lifelines, so it never
+// crosses an unrelated lifeline or activation bar (#676). Every character
+// stays visible, including in image exports: long unbroken text (a URL or
+// path) breaks after its punctuation, otherwise at any character.
+const NOTE_FONT_SIZE = 7;
+const NOTE_LINE_HEIGHT = NOTE_FONT_SIZE + 4;
+// The first line keeps its original position: 12px past the arrow start,
+// which sits 7px from the lifeline.
+const NOTE_ARROW_INSET = 7;
+const NOTE_TEXT_INSET = 12;
+// Activation bars reach 5px past a lifeline; keep 6px of air beyond them.
+const NOTE_LIFELINE_CLEARANCE = 11;
+// Spread columns share one computed gap, but subtracting floating-point column
+// centres can differ in the last digits; such gaps still count as equal.
+const NOTE_GAP_TOLERANCE = 0.5;
+const NOTE_BREAK_AFTER = new Set(['/', '.', '-', '?', '&', '=', '#', '_']);
+const noteSegmenter = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
+const noteLayouts = new Map();
+
+function noteTextWidth(text) {
+ return minimumNodeTextWidth(text, NOTE_FONT_SIZE);
+}
+
+// Index after the last punctuation break in `piece`, or its full length.
+function noteBreakIndex(piece) {
+ for (let index = piece.length - 1; index > 0; index -= 1) {
+ if (NOTE_BREAK_AFTER.has(piece[index - 1])) return index;
+ }
+ return piece.length;
+}
+
+function wrapNoteText(text, width) {
+ const lines = [];
+ let line = '';
+ const flush = () => {
+ const trimmed = line.trimEnd();
+ if (trimmed) lines.push(trimmed);
+ line = '';
+ };
+ for (const word of String(text).match(/\s+|\S+/gu) || []) {
+ if (/^\s+$/u.test(word)) {
+ if (line) line += ' ';
+ continue;
+ }
+ if (noteTextWidth(line + word) <= width) {
+ line += word;
+ continue;
+ }
+ flush();
+ let piece = '';
+ for (const { segment } of noteSegmenter.segment(word)) {
+ while (piece && noteTextWidth(piece + segment) > width) {
+ const cut = noteBreakIndex(piece);
+ lines.push(piece.slice(0, cut));
+ piece = piece.slice(cut);
+ }
+ piece += segment;
+ }
+ line = piece;
+ }
+ flush();
+ return lines;
+}
+
+// The widest gap the message spans; equal gaps resolve to the left-most one,
+// where a note has always started, so notes keep their original position.
+function noteGapIndex(fromIndex, toIndex) {
+ const low = Math.min(fromIndex, toIndex);
+ const high = Math.max(fromIndex, toIndex);
+ let best = null;
+ for (let gap = low; gap < high; gap += 1) {
+ const width = participantX(gap + 1) - participantX(gap);
+ if (!best || width > best.width + NOTE_GAP_TOLERANCE) best = { gap, width };
+ }
+ return best?.gap ?? null;
+}
+
+function noteRect(message) {
+ const note = noteLayout(message);
+ return note && { x: note.x, y: note.top, width: note.width, height: note.bottom - note.top };
+}
+
+function noteLayout(message) {
+ if (noteLayouts.has(message)) return noteLayouts.get(message);
+ let result = null;
+ const fromIndex = participantIndexById.get(message.from);
+ const toIndex = participantIndexById.get(message.to);
+ if (message.note && typeof message.y === 'number' && fromIndex !== undefined && toIndex !== undefined && fromIndex !== toIndex) {
+ const gap = noteGapIndex(fromIndex, toIndex);
+ const x = participantX(gap) + NOTE_ARROW_INSET + NOTE_TEXT_INSET;
+ const maxWidth = Math.max(1, participantX(gap + 1) - NOTE_LIFELINE_CLEARANCE - x);
+ const lines = noteTextWidth(message.note) <= maxWidth ? [message.note] : wrapNoteText(message.note, maxWidth);
+ const baseline = message.y + 18;
+ result = {
+ x,
+ baseline,
+ lines,
+ width: Math.max(...lines.map(noteTextWidth)),
+ top: baseline - NOTE_FONT_SIZE,
+ bottom: message.y + 22 + (lines.length - 1) * NOTE_LINE_HEIGHT,
+ };
+ }
+ noteLayouts.set(message, result);
+ return result;
+}
+
+const contentBottom = Math.max(
+ 0,
+ ...asArray(sequence.messages).map((message) => (message.note
+ ? noteLayout(message)?.bottom ?? message.y + 22
+ : message.y + 6)),
+ ...asArray(sequence.activations).map((activation) => activation.to),
+ ...asArray(sequence.segments).map((segment) => segment.to),
+);
+function legendRequiredHeight(width) {
+ const entries = legendEntries();
+ if (!entries.length) return 0;
+ return Math.ceil(contentBottom + LEGEND_CONTENT_GAP + LEGEND_BLOCK_HEIGHT
+ + legendFootprint(entries, { width: width - 80 }).extraHeight);
+}
+// A renderer-sized canvas grows to keep the legend clear of late messages;
+// an authored viewBox is honored and validated below.
+const viewBox = sequence.meta?.viewBox || [920, Math.max(760, legendRequiredHeight(920))];
+// The timeline scales with viewBox height: a taller viewBox gains message room,
+// a shorter one shrinks the readable band (validated below) instead of clipping.
// Showcase is the fast-authoring default; standard retains legacy label geometry.
const readableMessages = sequence.meta?.quality_profile === 'showcase';
diff --cc test/sequence-width-review.test.mjs
index 4461b6ec,e5b359bf..082fe72b
--- a/test/sequence-width-review.test.mjs
+++ b/test/sequence-width-review.test.mjs
@@@ -133,25 -165,17 +165,27 @@@ test('small conversations and a compac
assert.equal(check(render(t, compact).output).report.composition.sequenceColumnSpace.reviewSuggested, false);
});
-test('meaningful CJK message labels and notes occupy the right-hand region', t => {
- for (const field of ['label', 'note']) {
- const spec = sequence();
- spec.meta.column_fit = 'fixed';
- spec.messages = [{ from: 'p4', to: 'p5', y: 200, label: '结果', [field]: '这是需要保留的中文说明'.repeat(field === 'label' ? 4 : 3) }];
- const { report } = check(render(t, spec).output);
- const space = report.composition.sequenceColumnSpace;
- assert.equal(space.measured, true);
- assert.ok(space.occupiedRight > 810);
- assert.equal(space.reviewSuggested, false, `${field} reserves the apparent blank area`);
- }
+test('meaningful CJK message labels occupy the right-hand region', t => {
+ const spec = sequence();
++ spec.meta.column_fit = 'fixed';
+ spec.messages = [{ from: 'p4', to: 'p5', y: 200, label: '这是需要保留的中文说明'.repeat(4) }];
+ const { report } = check(render(t, spec).output);
+ const space = report.composition.sequenceColumnSpace;
+ assert.equal(space.measured, true);
+ assert.ok(space.occupiedRight > 810);
+ assert.equal(space.reviewSuggested, false, 'label reserves the apparent blank area');
+});
+
+test('a long CJK note wraps inside its lane gap, so the unused width stays measurable', t => {
+ const spec = sequence();
++ spec.meta.column_fit = 'fixed';
+ spec.messages = [{ from: 'p4', to: 'p5', y: 200, label: '结果', note: '这是需要保留的中文说明'.repeat(3) }];
+ const { output, html } = render(t, spec);
+ assert.match(html, /<tspan /, 'the note wraps onto several lines');
+ const space = check(output).report.composition.sequenceColumnSpace;
+ assert.equal(space.measured, true);
+ assert.ok(space.occupiedRight <= 645, `the note stays left of the last column (${space.occupiedRight})`);
+ assert.equal(space.reviewSuggested, true);
});
test('segment frames are structural but their text still reserves width', t => {