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,workflow): fit node text at its readable size

tt-a1i60342f60b63a
diff --git a/archify/renderers/sequence/render-sequence.mjs b/archify/renderers/sequence/render-sequence.mjs
index fdab7197..3ac24aec 100644
--- a/archify/renderers/sequence/render-sequence.mjs
+++ b/archify/renderers/sequence/render-sequence.mjs
@@ -8,7 +8,7 @@ import { componentFill, arrowClassMap, rectsOverlap, cleanFlowProblems, cleanCro
import { availableNodeTextWidth, fittedNodeFontSize, minimumNodeTextWidth } from '../shared/text-fit.mjs';
import { brandLabelFitWidth, brandMetadataFor, brandTopRailProblem, renderBrandMark } from '../shared/brand-marks.mjs';
import { translateMessage as i18nText } from '../shared/i18n.mjs';
-import { DESKTOP_READER_DIAGRAM_WIDTH, MIN_PROJECTED_NODE_TEXT_PX } from '../shared/desktop-readability.mjs';
+import { DESKTOP_READER_DIAGRAM_WIDTH, MIN_PROJECTED_NODE_TEXT_PX, minimumReadableSourceTextPx } from '../shared/desktop-readability.mjs';
const participantTextFit = {
sublabelPreferred: 7,
@@ -124,6 +124,12 @@ const layout = {
labelH: readableMessages ? 18 : 16
};
+// Shrink-to-fit must stop where the text still reads on the desktop at this
+// canvas width; a smaller fit only defers the failure to the browser gate.
+const readableSublabelMinimum = Math.max(participantTextFit.sublabelMinimum,
+ Math.ceil(minimumReadableSourceTextPx(viewBox[0]) * 10) / 10);
+const readableSublabelPreferred = Math.max(participantTextFit.sublabelPreferred, readableSublabelMinimum);
+
const participantBoxWidthNote = automaticWidth
? `participant boxes are ${participantW}px: the automatic ${viewBox[0]}px canvas cannot widen further without its 7px sublabels falling below the desktop reading minimum, so keep meta.viewBox omitted`
: columnFit === 'spread'
@@ -243,9 +249,9 @@ function validateSequence() {
// ordinary case, this rejects what it cannot rescue.
if (participant.sublabel) {
const availableTextW = availableNodeTextWidth(layout.participantW);
- const minimumW = minimumNodeTextWidth(participant.sublabel, participantTextFit.sublabelMinimum);
+ const minimumW = minimumNodeTextWidth(participant.sublabel, readableSublabelMinimum);
if (minimumW > availableTextW) {
- problems.push(`Sublabel "${participant.sublabel}" needs ~${Math.ceil(minimumW)}px at the ${participantTextFit.sublabelMinimum}px legible minimum, but participant "${participant.id}" provides ${availableTextW}px — shorten the sublabel (${participantBoxWidthNote}).`);
+ problems.push(`Sublabel "${participant.sublabel}" needs ~${Math.ceil(minimumW)}px at the ${readableSublabelMinimum}px minimum that stays readable on this ${viewBox[0]}px canvas, but participant "${participant.id}" provides ${availableTextW}px — shorten the sublabel (${participantBoxWidthNote}).`);
}
}
}
@@ -460,7 +466,7 @@ function renderParticipant(participant) {
const fill = componentFill[participant.type] || 'c-external';
const hasSub = participant.sublabel != null && participant.sublabel !== '';
const sub = hasSub
- ? `\n <text data-detail="context" x="${participant.cx}" y="${layout.topY + layout.participantSublabelY}" class="t-muted" font-size="${fittedNodeFontSize(participant.sublabel, layout.participantW, participantTextFit.sublabelPreferred, participantTextFit.sublabelMinimum)}" text-anchor="middle">${esc(participant.sublabel)}</text>`
+ ? `\n <text data-detail="context" x="${participant.cx}" y="${layout.topY + layout.participantSublabelY}" class="t-muted" font-size="${fittedNodeFontSize(participant.sublabel, layout.participantW, readableSublabelPreferred, readableSublabelMinimum)}" text-anchor="middle">${esc(participant.sublabel)}</text>`
: '';
const brand = renderBrandMark(participant, { x: participant.x + layout.participantW - 22, y: layout.topY + 6 });
const labelFontSize = fittedNodeFontSize(participant.label, brandLabelFitWidth(participant, layout.participantW), 11, 8);
diff --git a/archify/renderers/workflow/workflow-compiler.mjs b/archify/renderers/workflow/workflow-compiler.mjs
index 1d283030..889ee377 100644
--- a/archify/renderers/workflow/workflow-compiler.mjs
+++ b/archify/renderers/workflow/workflow-compiler.mjs
@@ -25,7 +25,7 @@ import {
import { availableNodeTextWidth, fittedNodeFontSize, minimumNodeTextWidth, nodeLabelLayout } from '../shared/text-fit.mjs';
import { brandLabelFitWidth, brandMarkFor, brandMetadataFor, brandTopRailProblem, renderBrandMark } from '../shared/brand-marks.mjs';
import { translateMessage as i18nText } from '../shared/i18n.mjs';
-import { predictedFixedWidthOverflow } from '../shared/desktop-readability.mjs';
+import { minimumReadableSourceTextPx, predictedFixedWidthOverflow } from '../shared/desktop-readability.mjs';
import {
createMappedWorkflowCandidate,
intrinsicWorkflow,
@@ -4841,13 +4841,38 @@ function renderGroup(group, index) {
<text x="${span.x + 10}" y="${labelY}" class="${textClass}" font-size="7" font-weight="600">${esc(group.label)}</text>`;
}
+// Shrink-to-fit stops where node text still reads on the desktop at the final
+// canvas width, so an overflow is reported here rather than by the browser gate.
+function readableTextMinimum(minimum) {
+ if (workflow.schema_version !== 2) return minimum;
+ return Math.max(minimum, Math.ceil(minimumReadableSourceTextPx(viewBox[0]) * 10) / 10);
+}
+
+function validateReadableNodeText() {
+ const problems = [];
+ for (const node of nodes.values()) {
+ for (const [field, value, minimum] of [
+ ['Sublabel', node.sublabel, readableTextMinimum(nodeTextFit.sublabelMinimum)],
+ ['Tag', node.tag, readableTextMinimum(nodeTextFit.tagMinimum)],
+ ]) {
+ const minimumW = value ? minimumNodeTextWidth(value, minimum) : 0;
+ if (minimumW > availableNodeTextWidth(node.width)) {
+ problems.push(`${field} "${value}" needs ~${Math.ceil(minimumW)}px at the ${minimum}px minimum that stays readable on this ${viewBox[0]}px canvas, but node "${node.id}" provides ${availableNodeTextWidth(node.width)}px — shorten the ${field.toLowerCase()}; a wider node or canvas lowers every projected font.`);
+ }
+ }
+ }
+ if (problems.length) throwDiagnosticProblems('Workflow layout validation failed', problems, { subject: { diagramType: 'workflow' } });
+}
+
function renderNode(node) {
const fill = componentFill[node.type] || 'c-external';
const accent = componentText[node.type] || 't-muted';
const hasSub = node.sublabel != null && node.sublabel !== '';
const labelFontSize = fittedNodeFontSize(node.label, brandLabelFitWidth(node, node.width), nodeTextFit.labelPreferred, nodeTextFit.labelMinimum);
- const sublabelFontSize = fittedNodeFontSize(node.sublabel, node.width, nodeTextFit.sublabelPreferred, nodeTextFit.sublabelMinimum);
- const tagFontSize = fittedNodeFontSize(node.tag, node.width, nodeTextFit.tagPreferred, nodeTextFit.tagMinimum);
+ const sublabelMinimum = readableTextMinimum(nodeTextFit.sublabelMinimum);
+ const tagMinimum = readableTextMinimum(nodeTextFit.tagMinimum);
+ const sublabelFontSize = fittedNodeFontSize(node.sublabel, node.width, Math.max(nodeTextFit.sublabelPreferred, sublabelMinimum), sublabelMinimum);
+ const tagFontSize = fittedNodeFontSize(node.tag, node.width, Math.max(nodeTextFit.tagPreferred, tagMinimum), tagMinimum);
const textRows = [{ text: node.label, font: labelFontSize, y: 21 }];
if (hasSub) textRows.push({ text: node.sublabel, font: sublabelFontSize, y: 38 });
if (node.tag) textRows.push({ text: node.tag, font: tagFontSize, y: node.height - 12 });
@@ -4951,6 +4976,7 @@ ${renderLegend()}
validateReadablePinnedGeometry();
validateWorkflow();
finalizeReadableViewBox();
+ validateReadableNodeText();
const svg = renderSvg();
const receipt = {
contract: layout.contract,
diff --git a/test/sequence-column-fit.test.mjs b/test/sequence-column-fit.test.mjs
index 6f4711fa..3fe6f97d 100644
--- a/test/sequence-column-fit.test.mjs
+++ b/test/sequence-column-fit.test.mjs
@@ -283,3 +283,20 @@ test('automatic spread canvas widens for participant labels up to the readable w
assert.notEqual(crowded.code, 0);
assert.match(crowded.stderr, /shorten it to at most \d+ text units[^]*keep meta\.viewBox omitted/);
});
+
+test('a widened automatic canvas reports sublabels at the size that stays readable there', () => {
+ const participant = (id, label, sublabel) => ({ id, type: 'backend', label, ...(sublabel ? { sublabel } : {}) });
+ const doc = {
+ schema_version: 1,
+ diagram_type: 'sequence',
+ meta: { title: 'Readable sublabel', quality_profile: 'showcase' },
+ participants: [
+ participant('a', 'Web UI'), participant('b', 'Orchestrator'), participant('c', 'team CLI'), participant('d', 'Runtime'),
+ participant('e', 'Team operations'), participant('f', 'SQLite'), participant('g', 'Stdin queue', 'tmp 或 reports/review'), participant('h', 'Worker'),
+ ],
+ messages: [{ from: 'a', to: 'h', label: 'send', y: 180 }],
+ };
+ const outcome = renderOutcome(doc);
+ assert.notEqual(outcome.code, 0);
+ assert.match(outcome.stderr, /Sublabel "tmp 或 reports\/review" needs ~\d+px at the [\d.]+px minimum that stays readable on this \d+px canvas/);
+});
diff --git a/test/workflow-compiler.test.mjs b/test/workflow-compiler.test.mjs
index bbd2e3e9..59b16259 100644
--- a/test/workflow-compiler.test.mjs
+++ b/test/workflow-compiler.test.mjs
@@ -357,7 +357,7 @@ test('readable-v2 separates approval branches in the checked-in workflow example
// approval-denied and approved-tool previously shared a mixed-style trunk.
// Node geometry, labels, all other paths and v1 baselines are unchanged.
sha256(result.svg.replace(/ data-(?:composition-routing|edge-role|layout-contract)="[^"]*"/g, '')),
- 'ee6a341d43479ac4b79deaef11513b4fac00cd984a376bf93b7ccd3a13b7e9a9',
+ 'cf98dc4bf3104e98dee7b69e1875206cc78cd9e322142e8432219c1784dae886',
);
});
@@ -500,6 +500,18 @@ test('a readable-v2 node without an authored width grows to fit its label', () =
assert.equal(width, 104);
});
+test('readable-v2 sublabels must fit at the size that stays readable on the final canvas', () => {
+ const workflow = adjacentWorkflow({ widths: [132, 200] });
+ workflow.nodes[1].col = 5;
+ workflow.nodes[0].sublabel = 'chain / debate / synthesis 调度';
+ for (const col of [0, 2, 3, 4]) {
+ workflow.nodes.push({ id: `wide-${col}`, lane: 'main', col, type: 'backend', label: `Step ${col}`, width: 200 });
+ }
+ const result = compileWorkflow({ workflow });
+ assert.equal(result.ok, false, 'expected a readable-size failure on a canvas wider than the reader');
+ assert.match(JSON.stringify(result.diagnostics), /minimum that stays readable on this \d+px canvas/);
+});
+
test('an automatic readable-v2 canvas too tall for the desktop page reads at page width', () => {
const workflow = adjacentWorkflow();
workflow.lanes = Array.from({ length: 6 }, (_, index) => ({ id: `lane-${index}`, label: `Lane ${index}` }));