@transitrix/diagrams 1.7.6 → 1.8.1

package/src/node-size-presets.ts

@@ -0,0 +1,157 @@
+/**
+ * Block/cell size presets for diagram renderers.
+ *
+ * Presets drive both layout geometry and shared text-layout char budgets.
+ * Smooth per-pixel sliders are intentionally deferred.
+ */
+
+export type NodeSizePreset = 'compact' | 'normal' | 'wide';
+
+export const NODE_SIZE_PRESET_VALUES: readonly NodeSizePreset[] = ['compact', 'normal', 'wide'] as const;
+
+export interface BoxDimensions {
+  width: number;
+  height: number;
+}
+
+export interface BlocksLeafDimensions extends BoxDimensions {}
+
+export interface ProcessBlueprintDimensions {
+  legendColumnWidth: number;
+  stageColumnWidth: number;
+  stageHeaderHeight: number;
+  goalRowHeight: number;
+  resultRowHeight: number;
+  aspectRowMinHeight: number;
+  pillHeight: number;
+  pillGap: number;
+  cellPadding: number;
+  textLineHeight: number;
+  textCharWidth: number;
+  cellTextPadX: number;
+  cellTextPadY: number;
+}
+
+export interface CapabilityMapDimensions {
+  nodeWidth: number;
+  nodeHeight: number;
+}
+
+type PresetTable<T> = Record<NodeSizePreset, T>;
+
+export const GOALS_NODE_SIZE: PresetTable<BoxDimensions> = {
+  compact: { width: 200, height: 72 },
+  normal: { width: 250, height: 72 },
+  wide: { width: 320, height: 72 },
+};
+
+export const DGCA_NODE_SIZE: PresetTable<BoxDimensions> = {
+  compact: { width: 200, height: 72 },
+  normal: { width: 220, height: 72 },
+  wide: { width: 280, height: 72 },
+};
+
+export const BLOCKS_LEAF_SIZE: PresetTable<BlocksLeafDimensions> = {
+  compact: { width: 140, height: 72 },
+  normal: { width: 160, height: 72 },
+  wide: { width: 200, height: 72 },
+};
+
+export const ACTION_NODE_SIZE: PresetTable<BoxDimensions> = {
+  compact: { width: 180, height: 72 },
+  normal: { width: 200, height: 80 },
+  wide: { width: 260, height: 80 },
+};
+
+export const PROCESS_BLUEPRINT_SIZE: PresetTable<ProcessBlueprintDimensions> = {
+  compact: {
+    legendColumnWidth: 120,
+    stageColumnWidth: 180,
+    stageHeaderHeight: 36,
+    goalRowHeight: 52,
+    resultRowHeight: 52,
+    aspectRowMinHeight: 56,
+    pillHeight: 36,
+    pillGap: 4,
+    cellPadding: 8,
+    textLineHeight: 16,
+    textCharWidth: 7.5,
+    cellTextPadX: 10,
+    cellTextPadY: 10,
+  },
+  normal: {
+    legendColumnWidth: 140,
+    stageColumnWidth: 220,
+    stageHeaderHeight: 40,
+    goalRowHeight: 56,
+    resultRowHeight: 56,
+    aspectRowMinHeight: 60,
+    pillHeight: 40,
+    pillGap: 4,
+    cellPadding: 8,
+    textLineHeight: 17,
+    textCharWidth: 7.5,
+    cellTextPadX: 10,
+    cellTextPadY: 10,
+  },
+  wide: {
+    legendColumnWidth: 160,
+    stageColumnWidth: 280,
+    stageHeaderHeight: 44,
+    goalRowHeight: 60,
+    resultRowHeight: 60,
+    aspectRowMinHeight: 64,
+    pillHeight: 44,
+    pillGap: 4,
+    cellPadding: 8,
+    textLineHeight: 18,
+    textCharWidth: 7.5,
+    cellTextPadX: 10,
+    cellTextPadY: 10,
+  },
+};
+
+export const CAPABILITY_MAP_NODE_SIZE: PresetTable<CapabilityMapDimensions> = {
+  compact: { nodeWidth: 200, nodeHeight: 56 },
+  normal: { nodeWidth: 240, nodeHeight: 60 },
+  wide: { nodeWidth: 300, nodeHeight: 64 },
+};
+
+export type NodeSizeNotation =
+  | 'goals'
+  | 'dgca'
+  | 'dga'
+  | 'blocks'
+  | 'action'
+  | 'processBlueprint'
+  | 'capabilityMap';
+
+/** Parse a VS Code setting value into a preset id (defaults to `normal`). */
+export function parseNodeSizePreset(value: string | undefined): NodeSizePreset {
+  if (value === 'compact' || value === 'wide') return value;
+  return 'normal';
+}
+
+export function resolveGoalsNodeSize(preset: NodeSizePreset): BoxDimensions {
+  return GOALS_NODE_SIZE[preset];
+}
+
+export function resolveDgcaNodeSize(preset: NodeSizePreset): BoxDimensions {
+  return DGCA_NODE_SIZE[preset];
+}
+
+export function resolveBlocksLeafSize(preset: NodeSizePreset): BlocksLeafDimensions {
+  return BLOCKS_LEAF_SIZE[preset];
+}
+
+export function resolveActionNodeSize(preset: NodeSizePreset): BoxDimensions {
+  return ACTION_NODE_SIZE[preset];
+}
+
+export function resolveProcessBlueprintSize(preset: NodeSizePreset): ProcessBlueprintDimensions {
+  return PROCESS_BLUEPRINT_SIZE[preset];
+}
+
+export function resolveCapabilityMapNodeSize(preset: NodeSizePreset): CapabilityMapDimensions {
+  return CAPABILITY_MAP_NODE_SIZE[preset];
+}

package/src/process-blueprint/layout.ts

@@ -18,6 +18,7 @@ import type {
   StageHeaderCell,
   StageTextCell,
 } from './types.js';
+import { wrapTextLines } from '../webview/entity-text-layout.js';
 
 const ASPECT_CATEGORIES: AspectCategory[] = ['systems', 'actors', 'equipment', 'information_entities'];
 
@@ -78,56 +79,11 @@ function resolveOptions(options: ProcessBlueprintLayoutOptions | undefined): Res
 }
 
 /**
- * Greedy word-wrap to a max characters-per-line budget. Words longer than the
- * budget are hard-split; if the result exceeds `maxLines`, the last kept line
- * is truncated with an ellipsis so a single pathological cell can't grow the
- * whole row unbounded.
+ * Greedy word-wrap to a max characters-per-line budget. Delegates to the shared
+ * shared text-layout module.
  */
 function wrapText(text: string, maxChars: number, maxLines: number): string[] {
-  const trimmed = (text ?? '').trim();
-  if (trimmed.length === 0) return [];
-  const budget = Math.max(1, maxChars);
-
-  const words = trimmed.split(/\s+/);
-  const lines: string[] = [];
-  let cur = '';
-  const flush = (): void => {
-    if (cur.length > 0) {
-      lines.push(cur);
-      cur = '';
-    }
-  };
-
-  for (const word of words) {
-    if (word.length > budget) {
-      // Token wider than the cell: hard-break it across lines.
-      flush();
-      let rest = word;
-      while (rest.length > budget) {
-        lines.push(rest.slice(0, budget));
-        rest = rest.slice(budget);
-      }
-      cur = rest;
-      continue;
-    }
-    const candidate = cur.length > 0 ? `${cur} ${word}` : word;
-    if (candidate.length > budget) {
-      flush();
-      cur = word;
-    } else {
-      cur = candidate;
-    }
-  }
-  flush();
-
-  if (lines.length > maxLines) {
-    const capped = lines.slice(0, maxLines);
-    const last = capped[maxLines - 1];
-    const clipped = last.length > budget - 1 ? last.slice(0, budget - 1) : last;
-    capped[maxLines - 1] = `${clipped.replace(/…$/, '')}…`;
-    return capped;
-  }
-  return lines;
+  return wrapTextLines(text, maxChars, maxLines);
 }
 
 function buildStageIndex(stages: Stage[]): Map<string, number> {

package/src/webview/__tests__/entity-text-layout.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest';
+import {
+  layoutCenteredEntityText,
+  maxCharsForInnerWidth,
+  wrapWords,
+  wrapTextLines,
+} from '../entity-text-layout.js';
+
+describe('entity-text-layout', () => {
+  it('wrapWords respects max lines and truncates with ellipsis', () => {
+    const long = 'one two three four five six seven eight nine ten eleven twelve';
+    const lines = wrapWords(long, 12, 2);
+    expect(lines.length).toBeLessThanOrEqual(2);
+    expect(lines[lines.length - 1]).toMatch(/…$/);
+  });
+
+  it('maxCharsForInnerWidth scales with inner width', () => {
+    expect(maxCharsForInnerWidth(160, 7)).toBeGreaterThan(maxCharsForInnerWidth(120, 7));
+  });
+
+  it('layoutCenteredEntityText emits more name capacity on wide boxes', () => {
+    const narrow = layoutCenteredEntityText({
+      boxX: 0,
+      boxY: 0,
+      boxWidth: 200,
+      boxHeight: 72,
+      name: 'Improve customer onboarding experience across regions',
+      id: 'GOAL-001',
+      nameMaxLines: 2,
+      idMaxLines: 1,
+    });
+    const wide = layoutCenteredEntityText({
+      boxX: 0,
+      boxY: 0,
+      boxWidth: 320,
+      boxHeight: 72,
+      name: 'Improve customer onboarding experience across regions',
+      id: 'GOAL-001',
+      nameMaxLines: 2,
+      idMaxLines: 1,
+    });
+    const narrowPrimary = narrow.filter((l) => l.cls === 'text-primary').map((l) => l.text).join(' ');
+    const widePrimary = wide.filter((l) => l.cls === 'text-primary').map((l) => l.text).join(' ');
+    expect(widePrimary.replace(/…/g, '').length).toBeGreaterThanOrEqual(narrowPrimary.replace(/…/g, '').length);
+  });
+
+  it('wrapTextLines hard-breaks oversized tokens (blueprint cells)', () => {
+    const lines = wrapTextLines('supercalifragilisticexpialidocious word', 10, 3);
+    expect(lines.length).toBeGreaterThan(1);
+    expect(lines.every((l) => l.length <= 10)).toBe(true);
+  });
+});

package/src/webview/__tests__/entry.test.ts

@@ -47,9 +47,9 @@ describe('webview/entry — Step 2 host API', () => {
 
   it('routes non-goals kinds to their validator after Step 4 (no NOTATION-NOT-WIRED)', () => {
     // Every supported kind is now wired to its validator + renderer. A
-    // malformed fgca document must surface a structured validation error from
-    // the fgca validator — never the Step-2/3 "not wired" placeholder.
-    const r = render('fgca', 'changes: []\n');
+    // malformed dgca document must surface a structured validation error from
+    // the dgca validator — never the Step-2/3 "not wired" placeholder.
+    const r = render('dgca', 'changes: []\n');
     expect(r.status).toBe('error');
     expect(r.errors.length).toBeGreaterThan(0);
     expect(r.errors.every((e) => e.code !== 'NOTATION-NOT-WIRED')).toBe(true);

package/src/webview/__tests__/render-blocks.test.ts

@@ -10,15 +10,7 @@ import { describe, expect, it } from 'vitest';
 
 import type { BlocksFile } from '../../blocks/types.js';
 import { renderBlocksSvg } from '../render-blocks.js';
-
-// Approximate character widths used by the renderer when sizing labels.
-// Kept in sync with `CHAR_W` / `CHAR_W_ID` in render-blocks.ts so the test
-// can compute the same overflow bounds the renderer uses.
-const CHAR_W = 7;
-const CHAR_W_ID = 6;
-
-// Same horizontal margin the renderer reserves so text never abuts the rect.
-const TEXT_MARGIN_X = 8;
+import { CHAR_W_PRIMARY as CHAR_W, CHAR_W_ID, TEXT_MARGIN_X } from '../entity-text-layout.js';
 
 function leafDoc(name: string, id: string): BlocksFile {
   return {

package/src/webview/entity-text-layout.ts

@@ -0,0 +1,355 @@
+/**
+ * Shared text-in-block layout for Transitrix diagram renderers.
+ *
+ * Consolidates wrapping, truncation, and vertical placement patterns previously
+ * duplicated across Blocks, Goals, DGCA/DGA, Activities, Process Blueprint, and
+ * Capability Map renderers.
+ */
+
+export const TEXT_MARGIN_X = 8;
+/** Approximate character width (px) at text-primary size (12px/600). */
+export const CHAR_W_PRIMARY = 7;
+/** Approximate character width (px) at text-id size (10px/600). */
+export const CHAR_W_ID = 6;
+/** Approximate character width (px) at text-secondary size. */
+export const CHAR_W_SECONDARY = 7;
+/** Vertical advance between name line centres (text-primary). */
+export const LINE_H_PRIMARY = 14;
+/** Vertical advance between secondary line centres. */
+export const LINE_H_SECONDARY = 14;
+/** Vertical advance between id line centres (text-id). */
+export const LINE_H_ID = 12;
+/** Gap between the name block and the id block in leaf-style layouts. */
+export const NAME_ID_GAP = 14;
+/** Gap between stacked row groups (name → type → id). */
+export const ROW_GROUP_GAP = 9;
+
+export function maxCharsForInnerWidth(innerWidth: number, charWidth: number): number {
+  return Math.max(4, Math.floor(Math.max(0, innerWidth) / charWidth));
+}
+
+/** Word-wrap `text` to at most `maxLines` lines of `maxChars` each. */
+export function wrapWords(text: string, maxChars: number, maxLines: number): string[] {
+  const safeMax = Math.max(2, maxChars);
+  const words = text.split(' ');
+  const lines: string[] = [];
+  let cur = '';
+  for (let i = 0; i < words.length; i++) {
+    const w = words[i];
+    const next = cur ? `${cur} ${w}` : w;
+    if (next.length <= safeMax) {
+      cur = next;
+    } else {
+      if (cur) lines.push(cur);
+      cur = '';
+      if (lines.length >= maxLines) break;
+      if (lines.length === maxLines - 1) {
+        const rest = words.slice(i).join(' ');
+        lines.push(rest.length <= safeMax ? rest : `${rest.slice(0, safeMax - 1)}…`);
+        return lines;
+      }
+      cur = w.length <= safeMax ? w : `${w.slice(0, safeMax - 1)}…`;
+    }
+  }
+  if (cur && lines.length < maxLines) lines.push(cur);
+  return lines.length ? lines : [`${text.slice(0, safeMax - 1)}…`];
+}
+
+/**
+ * Greedy word-wrap with hard-break for tokens wider than the budget. When the
+ * result exceeds `maxLines`, the last kept line is truncated with an ellipsis.
+ * Used by Process Blueprint goal/result cells and aspect pill names.
+ */
+export function wrapTextLines(text: string, maxChars: number, maxLines: number): string[] {
+  const trimmed = (text ?? '').trim();
+  if (trimmed.length === 0) return [];
+  const budget = Math.max(1, maxChars);
+
+  const words = trimmed.split(/\s+/);
+  const lines: string[] = [];
+  let cur = '';
+  const flush = (): void => {
+    if (cur.length > 0) {
+      lines.push(cur);
+      cur = '';
+    }
+  };
+
+  for (const word of words) {
+    if (word.length > budget) {
+      flush();
+      let rest = word;
+      while (rest.length > budget) {
+        lines.push(rest.slice(0, budget));
+        rest = rest.slice(budget);
+      }
+      cur = rest;
+      continue;
+    }
+    const candidate = cur.length > 0 ? `${cur} ${word}` : word;
+    if (candidate.length > budget) {
+      flush();
+      cur = word;
+    } else {
+      cur = candidate;
+    }
+  }
+  flush();
+
+  if (lines.length > maxLines) {
+    const capped = lines.slice(0, maxLines);
+    const last = capped[maxLines - 1];
+    const clipped = last.length > budget - 1 ? last.slice(0, budget - 1) : last;
+    capped[maxLines - 1] = `${clipped.replace(/…$/, '')}…`;
+    return capped;
+  }
+  return lines;
+}
+
+/** Split an ID (no spaces) across lines, breaking at `_` or `-`. */
+export function wrapId(id: string, maxChars: number, maxLines = 2): string[] {
+  if (maxLines <= 1) return [truncateId(id, maxChars)];
+  if (id.length <= maxChars) return [id];
+  const seg = id.slice(0, maxChars);
+  const sepIdx = Math.max(seg.lastIndexOf('_'), seg.lastIndexOf('-'));
+  const cut = sepIdx > Math.floor(maxChars / 3) ? sepIdx : maxChars - 1;
+  const isSep = id[cut] === '_' || id[cut] === '-';
+  const line1 = id.slice(0, cut);
+  const rest = id.slice(cut + (isSep ? 1 : 0));
+  return [line1, rest.length <= maxChars ? rest : `${rest.slice(0, maxChars - 1)}…`];
+}
+
+/** Truncate `text` to at most `maxChars` characters, at a word boundary when possible. */
+export function truncateLine(text: string, maxChars: number): string {
+  const safeMax = Math.max(2, maxChars);
+  if (text.length <= safeMax) return text;
+  const cut = text.slice(0, safeMax - 1);
+  const lastSpace = cut.lastIndexOf(' ');
+  return `${lastSpace > safeMax / 2 ? cut.slice(0, lastSpace) : cut}…`;
+}
+
+/** Single-line ID truncation that prefers `_`/`-` separators before a hard cut. */
+export function truncateId(id: string, maxChars: number): string {
+  const safeMax = Math.max(2, maxChars);
+  if (id.length <= safeMax) return id;
+  const cut = id.slice(0, safeMax - 1);
+  const sepIdx = Math.max(cut.lastIndexOf('_'), cut.lastIndexOf('-'));
+  return `${sepIdx > safeMax / 3 ? cut.slice(0, sepIdx) : cut}…`;
+}
+
+export interface TextLineSpec {
+  cls: string;
+  text: string;
+  y: number;
+  /** When set, use this x; otherwise callers supply a shared anchor (e.g. box centre). */
+  x?: number;
+}
+
+export interface LayoutCenteredEntityOptions {
+  boxX: number;
+  boxY: number;
+  boxWidth: number;
+  boxHeight: number;
+  name: string;
+  type?: string;
+  id: string;
+  nameMaxLines?: number;
+  idMaxLines?: number;
+  marginX?: number;
+}
+
+interface TextRowGroup {
+  cls: string;
+  lines: string[];
+  lineHeight: number;
+  gapAfter: number;
+}
+
+function totalVerticalSpan(groups: TextRowGroup[]): number {
+  let span = 0;
+  for (let i = 0; i < groups.length; i++) {
+    const g = groups[i];
+    if (g.lines.length > 1) span += (g.lines.length - 1) * g.lineHeight;
+    if (i < groups.length - 1) span += g.gapAfter;
+  }
+  return span;
+}
+
+/**
+ * Layout centred entity text (name → optional type → id) inside a fixed box.
+ * Returns absolute SVG y-positions (line centres) for each rendered row.
+ */
+export function layoutCenteredEntityText(opts: LayoutCenteredEntityOptions): TextLineSpec[] {
+  const marginX = opts.marginX ?? TEXT_MARGIN_X;
+  const innerW = Math.max(0, opts.boxWidth - marginX * 2);
+  const cx = opts.boxX + opts.boxWidth / 2;
+  const maxCharsName = maxCharsForInnerWidth(innerW, CHAR_W_PRIMARY);
+  const maxCharsType = maxCharsForInnerWidth(innerW, CHAR_W_SECONDARY);
+  const maxCharsId = maxCharsForInnerWidth(innerW, CHAR_W_ID);
+
+  const nameLines = wrapWords(opts.name, maxCharsName, opts.nameMaxLines ?? 2);
+  const typeLine = opts.type?.trim() ? truncateLine(opts.type, maxCharsType) : undefined;
+  const idMaxLines = opts.idMaxLines ?? 1;
+  const idLines = idMaxLines <= 1 ? [truncateId(opts.id, maxCharsId)] : wrapId(opts.id, maxCharsId, idMaxLines);
+
+  const groups: TextRowGroup[] = [
+    {
+      cls: 'text-primary',
+      lines: nameLines,
+      lineHeight: LINE_H_PRIMARY,
+      gapAfter: typeLine ? ROW_GROUP_GAP : NAME_ID_GAP,
+    },
+  ];
+  if (typeLine) {
+    groups.push({
+      cls: 'text-secondary',
+      lines: [typeLine],
+      lineHeight: LINE_H_SECONDARY,
+      gapAfter: NAME_ID_GAP,
+    });
+  }
+  groups.push({
+    cls: 'text-id',
+    lines: idLines,
+    lineHeight: LINE_H_ID,
+    gapAfter: 0,
+  });
+
+  const span = totalVerticalSpan(groups);
+  const firstY = Math.round(opts.boxY + (opts.boxHeight - span) / 2);
+  const out: TextLineSpec[] = [];
+  let y = firstY;
+  for (let gi = 0; gi < groups.length; gi++) {
+    const g = groups[gi];
+    for (let li = 0; li < g.lines.length; li++) {
+      out.push({ cls: g.cls, text: g.lines[li], y });
+      if (li < g.lines.length - 1) y += g.lineHeight;
+    }
+    if (gi < groups.length - 1) y += g.gapAfter;
+  }
+  return out;
+}
+
+/** Emit centred `<text>` elements from {@link layoutCenteredEntityText} specs. */
+export function emitCenteredTextSvg(
+  specs: TextLineSpec[],
+  centerX: number,
+  esc: (s: string) => string,
+): string {
+  return specs
+    .map((spec) => {
+      const x = spec.x ?? centerX;
+      const anchor = spec.x != null && spec.cls === 'text-pill' ? ' text-anchor="middle"' : ' text-anchor="middle"';
+      return `<text class="${spec.cls}" x="${x}" y="${spec.y}"${anchor} dominant-baseline="central">${esc(spec.text)}</text>`;
+    })
+    .join('\n');
+}
+
+export interface LayoutLeafBlockTextOptions {
+  boxX: number;
+  boxY: number;
+  boxWidth: number;
+  boxHeight: number;
+  name: string;
+  id: string;
+  nameMaxLines?: number;
+  marginX?: number;
+}
+
+/** Leaf nested-block layout: name (up to 3 lines) + id (up to 2 lines), centred. */
+export function layoutLeafBlockText(opts: LayoutLeafBlockTextOptions): TextLineSpec[] {
+  const marginX = opts.marginX ?? TEXT_MARGIN_X;
+  const innerW = Math.max(0, opts.boxWidth - marginX * 2);
+  const maxCharsName = maxCharsForInnerWidth(innerW, CHAR_W_PRIMARY);
+  const maxCharsId = maxCharsForInnerWidth(innerW, CHAR_W_ID);
+  const nameLines = wrapWords(opts.name, maxCharsName, opts.nameMaxLines ?? 3);
+  const idLines = wrapId(opts.id, maxCharsId, 2);
+
+  const nameSpan = (nameLines.length - 1) * LINE_H_PRIMARY;
+  const idSpan = (idLines.length - 1) * LINE_H_ID;
+  const totalSpan = nameSpan + NAME_ID_GAP + idSpan;
+  const firstY = Math.round(opts.boxY + (opts.boxHeight - totalSpan) / 2);
+
+  const out: TextLineSpec[] = [];
+  for (let i = 0; i < nameLines.length; i++) {
+    out.push({ cls: 'text-primary', text: nameLines[i], y: firstY + i * LINE_H_PRIMARY });
+  }
+  const idFirstY = firstY + nameSpan + NAME_ID_GAP;
+  for (let i = 0; i < idLines.length; i++) {
+    out.push({ cls: 'text-id', text: idLines[i], y: idFirstY + i * LINE_H_ID });
+  }
+  return out;
+}
+
+export interface LayoutHeaderBlockTextOptions {
+  boxX: number;
+  boxY: number;
+  boxWidth: number;
+  headerHeight: number;
+  name: string;
+  id: string;
+  marginX?: number;
+}
+
+/** Container header: single-line name + id stacked in the header strip. */
+export function layoutHeaderBlockText(opts: LayoutHeaderBlockTextOptions): TextLineSpec[] {
+  const marginX = opts.marginX ?? TEXT_MARGIN_X;
+  const innerW = Math.max(0, opts.boxWidth - marginX * 2);
+  const maxCharsName = maxCharsForInnerWidth(innerW, CHAR_W_PRIMARY);
+  const maxCharsId = maxCharsForInnerWidth(innerW, CHAR_W_ID);
+  const nameText = truncateLine(opts.name, maxCharsName);
+  const idText = truncateId(opts.id, maxCharsId);
+  const headerMid = opts.boxY + opts.headerHeight / 2;
+  const halfSpan = (LINE_H_PRIMARY + LINE_H_ID) / 4;
+  return [
+    { cls: 'text-primary', text: nameText, y: Math.round(headerMid - halfSpan) },
+    { cls: 'text-id', text: idText, y: Math.round(headerMid + halfSpan) },
+  ];
+}
+
+/**
+ * Left-anchored multi-line cell text, vertically centred (Process Blueprint cells).
+ * Returns one spec per line with absolute x baked into caller via anchorX.
+ */
+export function layoutLeftCellLines(
+  lines: string[],
+  anchorX: number,
+  cellTop: number,
+  cellHeight: number,
+  lineHeight: number,
+  cls: string,
+): TextLineSpec[] {
+  const ls = lines.length > 0 ? lines : [''];
+  const firstY = cellTop + cellHeight / 2 - ((ls.length - 1) / 2) * lineHeight;
+  return ls.map((text, i) => ({ cls, text, y: firstY + i * lineHeight, x: anchorX }));
+}
+
+/** Centred pill text: name lines + optional id line below. */
+export function layoutCenteredPillText(
+  pillX: number,
+  pillY: number,
+  pillWidth: number,
+  pillHeight: number,
+  nameLines: string[],
+  idLine: string | undefined,
+  nameLineHeight = 15,
+): TextLineSpec[] {
+  const cx = pillX + pillWidth / 2;
+  const lineCount = nameLines.length + (idLine ? 1 : 0);
+  const firstY = pillY + pillHeight / 2 - ((lineCount - 1) / 2) * nameLineHeight;
+  const out: TextLineSpec[] = nameLines.map((text, i) => ({
+    cls: 'text-pill',
+    text,
+    y: firstY + i * nameLineHeight,
+    x: cx,
+  }));
+  if (idLine) {
+    out.push({
+      cls: 'text-secondary',
+      text: idLine,
+      y: firstY + nameLines.length * nameLineHeight,
+      x: cx,
+    });
+  }
+  return out;
+}