@transitrix/diagrams 1.8.2 → 1.8.3

package/dist/blocks/layout.js

@@ -3,7 +3,7 @@ const DEFAULTS = {
     leafWidth: ENTITY_NODE_SIZE.normal.width,
     leafHeight: ENTITY_NODE_SIZE.normal.height,
     padding: 12,
-    headerHeight: 28,
+    headerHeight: 32,
     childGap: 12,
     topLevelGap: 24,
 };

package/dist/webview/__tests__/entity-text-layout.test.js

@@ -1,5 +1,6 @@
 import { describe, expect, it } from 'vitest';
-import { layoutCenteredEntityText, LINE_H_PRIMARY, LINE_H_SECONDARY, maxCharsForInnerWidth, ROW_GROUP_GAP, wrapWords, wrapTextLines, } from '../entity-text-layout.js';
+import { layoutCenteredEntityText, layoutLeafBlockText, layoutHeaderBlockText, LINE_H_PRIMARY, LINE_H_SECONDARY, TEXT_MARGIN_Y, maxCharsForInnerWidth, ROW_GROUP_GAP, wrapWords, wrapTextLines, } from '../entity-text-layout.js';
+import { ENTITY_NODE_SIZE } from '../../node-size-presets.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';
@@ -58,3 +59,97 @@ describe('entity-text-layout', () => {
         expect(lines.every((l) => l.length <= 10)).toBe(true);
     });
 });
+// Approximate half-extent (px) of each text class's glyphs around its centre
+// y — font-size / 2, the same heuristic the render-blocks overlap regression
+// test (#419) uses. Used below to assert text never visually crosses the box
+// border, not just that the *nominal* line-height budget fits.
+const HALF_EXTENT = {
+    'text-primary': 6, // 12px font
+    'text-secondary': 6, // 11px font, rounded up
+    'text-id': 5, // 10px font
+};
+describe('entity text layout — never overflows the box, always keeps padding', () => {
+    const PRESETS = Object.entries(ENTITY_NODE_SIZE); // compact/normal/wide
+    const NAMES = [
+        'Short',
+        'Achieve full GDPR & NIS2 compliance',
+        'A name so long it would need three or more lines to render in full without any height limit at all',
+    ];
+    function assertNoOverflowAndPadded(specs, boxTop, boxBottom) {
+        for (const s of specs) {
+            const half = HALF_EXTENT[s.cls] ?? 6;
+            expect(s.y - half).toBeGreaterThanOrEqual(boxTop);
+            expect(s.y + half).toBeLessThanOrEqual(boxBottom);
+        }
+    }
+    for (const [presetName, size] of PRESETS) {
+        for (const withType of [false, true]) {
+            for (const name of NAMES) {
+                it(`layoutCenteredEntityText: ${presetName} preset, type=${withType}, name="${name.slice(0, 20)}…" stays inside the box`, () => {
+                    const boxY = 0;
+                    const specs = layoutCenteredEntityText({
+                        boxX: 0,
+                        boxY,
+                        boxWidth: size.width,
+                        boxHeight: size.height,
+                        name,
+                        type: withType ? 'Strategic Goal' : undefined,
+                        id: 'GOAL-EU-COMPLIANCE-1',
+                        nameMaxLines: 2,
+                        idMaxLines: 1,
+                    });
+                    assertNoOverflowAndPadded(specs, boxY, boxY + size.height);
+                });
+            }
+        }
+    }
+    it('reproduces the reported case (wide preset, 2-line name + type + long id) with real padding on all sides', () => {
+        const size = ENTITY_NODE_SIZE.normal;
+        const boxY = 100;
+        const specs = layoutCenteredEntityText({
+            boxX: 0,
+            boxY,
+            boxWidth: size.width,
+            boxHeight: size.height,
+            name: 'Achieve full GDPR & NIS2 compliance',
+            type: 'Project Goal',
+            id: 'GOAL-EU-COMPLIANCE-1',
+            nameMaxLines: 2,
+            idMaxLines: 1,
+        });
+        const nameLines = specs.filter((s) => s.cls === 'text-primary');
+        expect(nameLines.length).toBe(2); // normal preset is tall enough to keep both lines
+        assertNoOverflowAndPadded(specs, boxY, boxY + size.height);
+        // Explicit padding, not just "doesn't cross the border".
+        const firstTop = Math.min(...specs.map((s) => s.y - (HALF_EXTENT[s.cls] ?? 6)));
+        const lastBottom = Math.max(...specs.map((s) => s.y + (HALF_EXTENT[s.cls] ?? 6)));
+        expect(firstTop - boxY).toBeGreaterThanOrEqual(TEXT_MARGIN_Y);
+        expect(boxY + size.height - lastBottom).toBeGreaterThanOrEqual(TEXT_MARGIN_Y);
+    });
+    it('layoutLeafBlockText stays inside the box for compact preset with a long name and id', () => {
+        const size = ENTITY_NODE_SIZE.compact;
+        const boxY = 0;
+        const specs = layoutLeafBlockText({
+            boxX: 0,
+            boxY,
+            boxWidth: size.width,
+            boxHeight: size.height,
+            name: 'Personal data records that linger after consent withdrawal across many systems and archives',
+            id: 'VERY_LONG_BLOCK_IDENTIFIER_WITH_MANY_SEGMENTS_AND_MORE',
+        });
+        assertNoOverflowAndPadded(specs, boxY, boxY + size.height);
+    });
+    it('layoutHeaderBlockText stays inside a short header strip', () => {
+        const boxY = 0;
+        const headerHeight = 28;
+        const specs = layoutHeaderBlockText({
+            boxX: 0,
+            boxY,
+            boxWidth: 250,
+            headerHeight,
+            name: 'A fairly long container name here',
+            id: 'VERY_LONG_CONTAINER_IDENTIFIER',
+        });
+        assertNoOverflowAndPadded(specs, boxY, boxY + headerHeight);
+    });
+});

package/dist/webview/entity-text-layout.d.ts

@@ -6,6 +6,14 @@
  * Capability Map renderers.
  */
 export declare const TEXT_MARGIN_X = 8;
+/**
+ * Minimum reserved vertical padding (px) between the box's top/bottom edge and
+ * the nearest line's outer extent. Always enforced — see
+ * {@link layoutCenteredEntityText}'s adaptive line-count reduction, which
+ * trades name-line count for this padding rather than letting text touch or
+ * cross the box border.
+ */
+export declare const TEXT_MARGIN_Y = 4;
 /** Approximate character width (px) at text-primary size (12px/600). */
 export declare const CHAR_W_PRIMARY = 7;
 /** Approximate character width (px) at text-id size (10px/600). */
@@ -18,10 +26,15 @@ export declare const LINE_H_PRIMARY = 14;
 export declare const LINE_H_SECONDARY = 14;
 /** Vertical advance between id line centres (text-id). */
 export declare const LINE_H_ID = 12;
-/** Gap between the name block and the id block in leaf-style layouts. */
+/**
+ * Gap between the name block and the id block in leaf-style layouts — used as
+ * a direct centre-to-centre distance there, so keep it >= ~11px (half of
+ * text-primary's 12px font + half of text-id's 10px font) to avoid the
+ * overlap regressed in #419. Do not tighten without re-checking that test.
+ */
 export declare const NAME_ID_GAP = 14;
 /** Gap between stacked row groups (name → type → id). */
-export declare const ROW_GROUP_GAP = 9;
+export declare const ROW_GROUP_GAP = 4;
 export declare function maxCharsForInnerWidth(innerWidth: number, charWidth: number): number;
 /** Word-wrap `text` to at most `maxLines` lines of `maxChars` each. */
 export declare function wrapWords(text: string, maxChars: number, maxLines: number): string[];
@@ -55,10 +68,20 @@ export interface LayoutCenteredEntityOptions {
     nameMaxLines?: number;
     idMaxLines?: number;
     marginX?: number;
+    marginY?: number;
 }
 /**
  * Layout centred entity text (name → optional type → id) inside a fixed box.
  * Returns absolute SVG y-positions (line centres) for each rendered row.
+ *
+ * Guarantees, in order of priority:
+ *   1. Content never crosses the box's top/bottom edge.
+ *   2. At least `marginY` (default {@link TEXT_MARGIN_Y}) of padding is kept
+ *      above the first line's glyphs and below the last line's glyphs.
+ *   3. The name gets as many lines as `nameMaxLines` allows (2 by default)
+ *      when the box is tall enough; on short/compact boxes (e.g. with a type
+ *      row present) it degrades to fewer name lines — trading line count,
+ *      not padding — rather than letting text overflow.
  */
 export declare function layoutCenteredEntityText(opts: LayoutCenteredEntityOptions): TextLineSpec[];
 /** Emit centred `<text>` elements from {@link layoutCenteredEntityText} specs. */
@@ -73,7 +96,12 @@ export interface LayoutLeafBlockTextOptions {
     nameMaxLines?: number;
     marginX?: number;
 }
-/** Leaf nested-block layout: name (up to 3 lines) + id (up to 2 lines), centred. */
+/**
+ * Leaf nested-block layout: name (up to 3 lines) + id (up to 2 lines), centred.
+ * Degrades name line count (never below 1) when the box is too short to hold
+ * the requested max plus {@link TEXT_MARGIN_Y} padding on both edges, so text
+ * never crosses the box border.
+ */
 export declare function layoutLeafBlockText(opts: LayoutLeafBlockTextOptions): TextLineSpec[];
 export interface LayoutHeaderBlockTextOptions {
     boxX: number;

package/dist/webview/entity-text-layout.js

@@ -6,6 +6,14 @@
  * Capability Map renderers.
  */
 export const TEXT_MARGIN_X = 8;
+/**
+ * Minimum reserved vertical padding (px) between the box's top/bottom edge and
+ * the nearest line's outer extent. Always enforced — see
+ * {@link layoutCenteredEntityText}'s adaptive line-count reduction, which
+ * trades name-line count for this padding rather than letting text touch or
+ * cross the box border.
+ */
+export const TEXT_MARGIN_Y = 4;
 /** 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). */
@@ -18,10 +26,15 @@ export const LINE_H_PRIMARY = 14;
 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. */
+/**
+ * Gap between the name block and the id block in leaf-style layouts — used as
+ * a direct centre-to-centre distance there, so keep it >= ~11px (half of
+ * text-primary's 12px font + half of text-id's 10px font) to avoid the
+ * overlap regressed in #419. Do not tighten without re-checking that test.
+ */
 export const NAME_ID_GAP = 14;
 /** Gap between stacked row groups (name → type → id). */
-export const ROW_GROUP_GAP = 9;
+export const ROW_GROUP_GAP = 4;
 export function maxCharsForInnerWidth(innerWidth, charWidth) {
     return Math.max(4, Math.floor(Math.max(0, innerWidth) / charWidth));
 }
@@ -136,67 +149,100 @@ export function truncateId(id, maxChars) {
     const sepIdx = Math.max(cut.lastIndexOf('_'), cut.lastIndexOf('-'));
     return `${sepIdx > safeMax / 3 ? cut.slice(0, sepIdx) : cut}…`;
 }
-function totalVerticalSpan(groups) {
-    let span = 0;
-    for (let i = 0; i < groups.length; i++) {
-        const g = groups[i];
-        span += g.lines.length * g.lineHeight;
-        if (i < groups.length - 1)
-            span += g.gapAfter;
+/**
+ * Half-extent (px) of rendered glyphs around their centre y — approximately
+ * font-size / 2, the same heuristic the #419 non-overlap regression test
+ * uses. Used only to keep the *outermost* line's visual extent (not just its
+ * centre) inside the box when computing edge padding; inter-line spacing
+ * between adjacent rows is governed separately by the LINE_H_ constants,
+ * NAME_ID_GAP and ROW_GROUP_GAP, which already keep centres far enough apart
+ * to avoid overlap.
+ */
+const HALF_EXTENT_PRIMARY = 6; // text-primary, 12px font
+const HALF_EXTENT_ID = 5; // text-id, 10px font
+/** Place `groups`' lines starting at `startY`, advancing by each line's own height and gap. */
+function placeLines(groups, startY) {
+    const out = [];
+    let y = startY;
+    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 });
+            y += g.lineHeight;
+        }
+        if (gi < groups.length - 1)
+            y += g.gapAfter;
     }
-    return span;
+    return out;
+}
+/** Centre-to-centre distance from the first to the last placed line. */
+function centerSpan(groups) {
+    const ys = placeLines(groups, 0).map((s) => s.y);
+    return ys[ys.length - 1] - ys[0];
 }
 /**
  * Layout centred entity text (name → optional type → id) inside a fixed box.
  * Returns absolute SVG y-positions (line centres) for each rendered row.
+ *
+ * Guarantees, in order of priority:
+ *   1. Content never crosses the box's top/bottom edge.
+ *   2. At least `marginY` (default {@link TEXT_MARGIN_Y}) of padding is kept
+ *      above the first line's glyphs and below the last line's glyphs.
+ *   3. The name gets as many lines as `nameMaxLines` allows (2 by default)
+ *      when the box is tall enough; on short/compact boxes (e.g. with a type
+ *      row present) it degrades to fewer name lines — trading line count,
+ *      not padding — rather than letting text overflow.
  */
 export function layoutCenteredEntityText(opts) {
     const marginX = opts.marginX ?? TEXT_MARGIN_X;
+    const marginY = opts.marginY ?? TEXT_MARGIN_Y;
     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 = [
-        {
-            cls: 'text-primary',
-            lines: nameLines,
-            lineHeight: LINE_H_PRIMARY,
-            gapAfter: typeLine ? ROW_GROUP_GAP : NAME_ID_GAP,
-        },
-    ];
-    if (typeLine) {
+    function buildGroups(nameLines) {
+        const groups = [
+            {
+                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-secondary',
-            lines: [typeLine],
-            lineHeight: LINE_H_SECONDARY,
-            gapAfter: NAME_ID_GAP,
+            cls: 'text-id',
+            lines: idLines,
+            lineHeight: LINE_H_ID,
+            gapAfter: 0,
         });
+        return groups;
     }
-    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 = [];
-    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 });
-            y += g.lineHeight;
-        }
-        if (gi < groups.length - 1)
-            y += g.gapAfter;
+    // groups[0] is always the name (text-primary) and the last group is always
+    // the id (text-id), so the edge-padding half-extents below are fixed.
+    const requestedNameMaxLines = Math.max(1, opts.nameMaxLines ?? 2);
+    const availableHeight = Math.max(0, opts.boxHeight - marginY * 2);
+    let nameLines = wrapWords(opts.name, maxCharsName, requestedNameMaxLines);
+    let groups = buildGroups(nameLines);
+    let contentSpan = centerSpan(groups) + HALF_EXTENT_PRIMARY + HALF_EXTENT_ID;
+    for (let cap = requestedNameMaxLines - 1; cap >= 1 && contentSpan > availableHeight; cap--) {
+        nameLines = wrapWords(opts.name, maxCharsName, cap);
+        groups = buildGroups(nameLines);
+        contentSpan = centerSpan(groups) + HALF_EXTENT_PRIMARY + HALF_EXTENT_ID;
     }
-    return out;
+    const margin = Math.max(0, (opts.boxHeight - contentSpan) / 2);
+    const firstY = Math.round(opts.boxY + margin + HALF_EXTENT_PRIMARY);
+    return placeLines(groups, firstY);
 }
 /** Emit centred `<text>` elements from {@link layoutCenteredEntityText} specs. */
 export function emitCenteredTextSvg(specs, centerX, esc) {
@@ -208,28 +254,48 @@ export function emitCenteredTextSvg(specs, centerX, esc) {
     })
         .join('\n');
 }
-/** Leaf nested-block layout: name (up to 3 lines) + id (up to 2 lines), centred. */
+/**
+ * Leaf nested-block layout: name (up to 3 lines) + id (up to 2 lines), centred.
+ * Degrades name line count (never below 1) when the box is too short to hold
+ * the requested max plus {@link TEXT_MARGIN_Y} padding on both edges, so text
+ * never crosses the box border.
+ */
 export function layoutLeafBlockText(opts) {
     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 idCenterSpan = (idLines.length - 1) * LINE_H_ID;
+    const requestedNameMaxLines = Math.max(1, opts.nameMaxLines ?? 3);
+    const availableHeight = Math.max(0, opts.boxHeight - TEXT_MARGIN_Y * 2);
+    let nameLines = wrapWords(opts.name, maxCharsName, requestedNameMaxLines);
+    let nameCenterSpan = (nameLines.length - 1) * LINE_H_PRIMARY;
+    let contentSpan = nameCenterSpan + NAME_ID_GAP + idCenterSpan + HALF_EXTENT_PRIMARY + HALF_EXTENT_ID;
+    for (let cap = requestedNameMaxLines - 1; cap >= 1 && contentSpan > availableHeight; cap--) {
+        nameLines = wrapWords(opts.name, maxCharsName, cap);
+        nameCenterSpan = (nameLines.length - 1) * LINE_H_PRIMARY;
+        contentSpan = nameCenterSpan + NAME_ID_GAP + idCenterSpan + HALF_EXTENT_PRIMARY + HALF_EXTENT_ID;
+    }
+    const margin = Math.max(0, (opts.boxHeight - contentSpan) / 2);
+    const firstY = Math.round(opts.boxY + margin + HALF_EXTENT_PRIMARY);
     const out = [];
     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;
+    const idFirstY = firstY + nameCenterSpan + 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;
 }
+/**
+ * Direct centre-to-centre gap between the header's name and id lines.
+ * Safely above the ~11px non-overlap floor (half of text-primary's 12px font
+ * + half of text-id's 10px font, per the #419 regression) but tighter than
+ * {@link NAME_ID_GAP} to fit the compact header strip.
+ */
+const HEADER_NAME_ID_GAP = 12;
 /** Container header: single-line name + id stacked in the header strip. */
 export function layoutHeaderBlockText(opts) {
     const marginX = opts.marginX ?? TEXT_MARGIN_X;
@@ -238,11 +304,13 @@ export function layoutHeaderBlockText(opts) {
     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;
+    const contentSpan = HEADER_NAME_ID_GAP + HALF_EXTENT_PRIMARY + HALF_EXTENT_ID;
+    const margin = Math.max(0, (opts.headerHeight - contentSpan) / 2);
+    const nameY = Math.round(opts.boxY + margin + HALF_EXTENT_PRIMARY);
+    const idY = nameY + HEADER_NAME_ID_GAP;
     return [
-        { cls: 'text-primary', text: nameText, y: Math.round(headerMid - halfSpan) },
-        { cls: 'text-id', text: idText, y: Math.round(headerMid + halfSpan) },
+        { cls: 'text-primary', text: nameText, y: nameY },
+        { cls: 'text-id', text: idText, y: idY },
     ];
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@transitrix/diagrams",
-  "version": "1.8.2",
+  "version": "1.8.3",
   "type": "module",
   "description": "Shared rendering, validation, and pure mutations for Transitrix custom diagram formats.",
   "license": "MIT",

package/src/blocks/layout.ts

@@ -11,7 +11,7 @@ const DEFAULTS: Required<BlocksLayoutOptions> = {
   leafWidth: ENTITY_NODE_SIZE.normal.width,
   leafHeight: ENTITY_NODE_SIZE.normal.height,
   padding: 12,
-  headerHeight: 28,
+  headerHeight: 32,
   childGap: 12,
   topLevelGap: 24,
 };

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

@@ -1,13 +1,17 @@
 import { describe, expect, it } from 'vitest';
 import {
   layoutCenteredEntityText,
+  layoutLeafBlockText,
+  layoutHeaderBlockText,
   LINE_H_PRIMARY,
   LINE_H_SECONDARY,
+  TEXT_MARGIN_Y,
   maxCharsForInnerWidth,
   ROW_GROUP_GAP,
   wrapWords,
   wrapTextLines,
 } from '../entity-text-layout.js';
+import { ENTITY_NODE_SIZE } from '../../node-size-presets.js';
 
 describe('entity-text-layout', () => {
   it('wrapWords respects max lines and truncates with ellipsis', () => {
@@ -71,3 +75,108 @@ describe('entity-text-layout', () => {
     expect(lines.every((l) => l.length <= 10)).toBe(true);
   });
 });
+
+// Approximate half-extent (px) of each text class's glyphs around its centre
+// y — font-size / 2, the same heuristic the render-blocks overlap regression
+// test (#419) uses. Used below to assert text never visually crosses the box
+// border, not just that the *nominal* line-height budget fits.
+const HALF_EXTENT: Record<string, number> = {
+  'text-primary': 6, // 12px font
+  'text-secondary': 6, // 11px font, rounded up
+  'text-id': 5, // 10px font
+};
+
+describe('entity text layout — never overflows the box, always keeps padding', () => {
+  const PRESETS = Object.entries(ENTITY_NODE_SIZE); // compact/normal/wide
+  const NAMES = [
+    'Short',
+    'Achieve full GDPR & NIS2 compliance',
+    'A name so long it would need three or more lines to render in full without any height limit at all',
+  ];
+
+  function assertNoOverflowAndPadded(
+    specs: { cls: string; y: number }[],
+    boxTop: number,
+    boxBottom: number,
+  ): void {
+    for (const s of specs) {
+      const half = HALF_EXTENT[s.cls] ?? 6;
+      expect(s.y - half).toBeGreaterThanOrEqual(boxTop);
+      expect(s.y + half).toBeLessThanOrEqual(boxBottom);
+    }
+  }
+
+  for (const [presetName, size] of PRESETS) {
+    for (const withType of [false, true]) {
+      for (const name of NAMES) {
+        it(`layoutCenteredEntityText: ${presetName} preset, type=${withType}, name="${name.slice(0, 20)}…" stays inside the box`, () => {
+          const boxY = 0;
+          const specs = layoutCenteredEntityText({
+            boxX: 0,
+            boxY,
+            boxWidth: size.width,
+            boxHeight: size.height,
+            name,
+            type: withType ? 'Strategic Goal' : undefined,
+            id: 'GOAL-EU-COMPLIANCE-1',
+            nameMaxLines: 2,
+            idMaxLines: 1,
+          });
+          assertNoOverflowAndPadded(specs, boxY, boxY + size.height);
+        });
+      }
+    }
+  }
+
+  it('reproduces the reported case (wide preset, 2-line name + type + long id) with real padding on all sides', () => {
+    const size = ENTITY_NODE_SIZE.normal;
+    const boxY = 100;
+    const specs = layoutCenteredEntityText({
+      boxX: 0,
+      boxY,
+      boxWidth: size.width,
+      boxHeight: size.height,
+      name: 'Achieve full GDPR & NIS2 compliance',
+      type: 'Project Goal',
+      id: 'GOAL-EU-COMPLIANCE-1',
+      nameMaxLines: 2,
+      idMaxLines: 1,
+    });
+    const nameLines = specs.filter((s) => s.cls === 'text-primary');
+    expect(nameLines.length).toBe(2); // normal preset is tall enough to keep both lines
+    assertNoOverflowAndPadded(specs, boxY, boxY + size.height);
+    // Explicit padding, not just "doesn't cross the border".
+    const firstTop = Math.min(...specs.map((s) => s.y - (HALF_EXTENT[s.cls] ?? 6)));
+    const lastBottom = Math.max(...specs.map((s) => s.y + (HALF_EXTENT[s.cls] ?? 6)));
+    expect(firstTop - boxY).toBeGreaterThanOrEqual(TEXT_MARGIN_Y);
+    expect(boxY + size.height - lastBottom).toBeGreaterThanOrEqual(TEXT_MARGIN_Y);
+  });
+
+  it('layoutLeafBlockText stays inside the box for compact preset with a long name and id', () => {
+    const size = ENTITY_NODE_SIZE.compact;
+    const boxY = 0;
+    const specs = layoutLeafBlockText({
+      boxX: 0,
+      boxY,
+      boxWidth: size.width,
+      boxHeight: size.height,
+      name: 'Personal data records that linger after consent withdrawal across many systems and archives',
+      id: 'VERY_LONG_BLOCK_IDENTIFIER_WITH_MANY_SEGMENTS_AND_MORE',
+    });
+    assertNoOverflowAndPadded(specs, boxY, boxY + size.height);
+  });
+
+  it('layoutHeaderBlockText stays inside a short header strip', () => {
+    const boxY = 0;
+    const headerHeight = 28;
+    const specs = layoutHeaderBlockText({
+      boxX: 0,
+      boxY,
+      boxWidth: 250,
+      headerHeight,
+      name: 'A fairly long container name here',
+      id: 'VERY_LONG_CONTAINER_IDENTIFIER',
+    });
+    assertNoOverflowAndPadded(specs, boxY, boxY + headerHeight);
+  });
+});

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

@@ -7,6 +7,14 @@
  */
 
 export const TEXT_MARGIN_X = 8;
+/**
+ * Minimum reserved vertical padding (px) between the box's top/bottom edge and
+ * the nearest line's outer extent. Always enforced — see
+ * {@link layoutCenteredEntityText}'s adaptive line-count reduction, which
+ * trades name-line count for this padding rather than letting text touch or
+ * cross the box border.
+ */
+export const TEXT_MARGIN_Y = 4;
 /** 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). */
@@ -19,10 +27,15 @@ export const LINE_H_PRIMARY = 14;
 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. */
+/**
+ * Gap between the name block and the id block in leaf-style layouts — used as
+ * a direct centre-to-centre distance there, so keep it >= ~11px (half of
+ * text-primary's 12px font + half of text-id's 10px font) to avoid the
+ * overlap regressed in #419. Do not tighten without re-checking that test.
+ */
 export const NAME_ID_GAP = 14;
 /** Gap between stacked row groups (name → type → id). */
-export const ROW_GROUP_GAP = 9;
+export const ROW_GROUP_GAP = 4;
 
 export function maxCharsForInnerWidth(innerWidth: number, charWidth: number): number {
   return Math.max(4, Math.floor(Math.max(0, innerWidth) / charWidth));
@@ -156,6 +169,7 @@ export interface LayoutCenteredEntityOptions {
   nameMaxLines?: number;
   idMaxLines?: number;
   marginX?: number;
+  marginY?: number;
 }
 
 interface TextRowGroup {
@@ -165,69 +179,111 @@ interface TextRowGroup {
   gapAfter: number;
 }
 
-function totalVerticalSpan(groups: TextRowGroup[]): number {
-  let span = 0;
-  for (let i = 0; i < groups.length; i++) {
-    const g = groups[i];
-    span += g.lines.length * g.lineHeight;
-    if (i < groups.length - 1) span += g.gapAfter;
+/**
+ * Half-extent (px) of rendered glyphs around their centre y — approximately
+ * font-size / 2, the same heuristic the #419 non-overlap regression test
+ * uses. Used only to keep the *outermost* line's visual extent (not just its
+ * centre) inside the box when computing edge padding; inter-line spacing
+ * between adjacent rows is governed separately by the LINE_H_ constants,
+ * NAME_ID_GAP and ROW_GROUP_GAP, which already keep centres far enough apart
+ * to avoid overlap.
+ */
+const HALF_EXTENT_PRIMARY = 6; // text-primary, 12px font
+const HALF_EXTENT_ID = 5; // text-id, 10px font
+
+/** Place `groups`' lines starting at `startY`, advancing by each line's own height and gap. */
+function placeLines(groups: TextRowGroup[], startY: number): TextLineSpec[] {
+  const out: TextLineSpec[] = [];
+  let y = startY;
+  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 });
+      y += g.lineHeight;
+    }
+    if (gi < groups.length - 1) y += g.gapAfter;
   }
-  return span;
+  return out;
+}
+
+/** Centre-to-centre distance from the first to the last placed line. */
+function centerSpan(groups: TextRowGroup[]): number {
+  const ys = placeLines(groups, 0).map((s) => s.y);
+  return ys[ys.length - 1] - ys[0];
 }
 
 /**
  * Layout centred entity text (name → optional type → id) inside a fixed box.
  * Returns absolute SVG y-positions (line centres) for each rendered row.
+ *
+ * Guarantees, in order of priority:
+ *   1. Content never crosses the box's top/bottom edge.
+ *   2. At least `marginY` (default {@link TEXT_MARGIN_Y}) of padding is kept
+ *      above the first line's glyphs and below the last line's glyphs.
+ *   3. The name gets as many lines as `nameMaxLines` allows (2 by default)
+ *      when the box is tall enough; on short/compact boxes (e.g. with a type
+ *      row present) it degrades to fewer name lines — trading line count,
+ *      not padding — rather than letting text overflow.
  */
 export function layoutCenteredEntityText(opts: LayoutCenteredEntityOptions): TextLineSpec[] {
   const marginX = opts.marginX ?? TEXT_MARGIN_X;
+  const marginY = opts.marginY ?? TEXT_MARGIN_Y;
   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) {
+  function buildGroups(nameLines: string[]): TextRowGroup[] {
+    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-secondary',
-      lines: [typeLine],
-      lineHeight: LINE_H_SECONDARY,
-      gapAfter: NAME_ID_GAP,
+      cls: 'text-id',
+      lines: idLines,
+      lineHeight: LINE_H_ID,
+      gapAfter: 0,
     });
+    return groups;
   }
-  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 });
-      y += g.lineHeight;
-    }
-    if (gi < groups.length - 1) y += g.gapAfter;
+
+  // groups[0] is always the name (text-primary) and the last group is always
+  // the id (text-id), so the edge-padding half-extents below are fixed.
+  const requestedNameMaxLines = Math.max(1, opts.nameMaxLines ?? 2);
+  const availableHeight = Math.max(0, opts.boxHeight - marginY * 2);
+
+  let nameLines = wrapWords(opts.name, maxCharsName, requestedNameMaxLines);
+  let groups = buildGroups(nameLines);
+  let contentSpan = centerSpan(groups) + HALF_EXTENT_PRIMARY + HALF_EXTENT_ID;
+  for (
+    let cap = requestedNameMaxLines - 1;
+    cap >= 1 && contentSpan > availableHeight;
+    cap--
+  ) {
+    nameLines = wrapWords(opts.name, maxCharsName, cap);
+    groups = buildGroups(nameLines);
+    contentSpan = centerSpan(groups) + HALF_EXTENT_PRIMARY + HALF_EXTENT_ID;
   }
-  return out;
+
+  const margin = Math.max(0, (opts.boxHeight - contentSpan) / 2);
+  const firstY = Math.round(opts.boxY + margin + HALF_EXTENT_PRIMARY);
+  return placeLines(groups, firstY);
 }
 
 /** Emit centred `<text>` elements from {@link layoutCenteredEntityText} specs. */
@@ -256,25 +312,44 @@ export interface LayoutLeafBlockTextOptions {
   marginX?: number;
 }
 
-/** Leaf nested-block layout: name (up to 3 lines) + id (up to 2 lines), centred. */
+/**
+ * Leaf nested-block layout: name (up to 3 lines) + id (up to 2 lines), centred.
+ * Degrades name line count (never below 1) when the box is too short to hold
+ * the requested max plus {@link TEXT_MARGIN_Y} padding on both edges, so text
+ * never crosses the box border.
+ */
 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 idCenterSpan = (idLines.length - 1) * LINE_H_ID;
+
+  const requestedNameMaxLines = Math.max(1, opts.nameMaxLines ?? 3);
+  const availableHeight = Math.max(0, opts.boxHeight - TEXT_MARGIN_Y * 2);
+
+  let nameLines = wrapWords(opts.name, maxCharsName, requestedNameMaxLines);
+  let nameCenterSpan = (nameLines.length - 1) * LINE_H_PRIMARY;
+  let contentSpan = nameCenterSpan + NAME_ID_GAP + idCenterSpan + HALF_EXTENT_PRIMARY + HALF_EXTENT_ID;
+  for (
+    let cap = requestedNameMaxLines - 1;
+    cap >= 1 && contentSpan > availableHeight;
+    cap--
+  ) {
+    nameLines = wrapWords(opts.name, maxCharsName, cap);
+    nameCenterSpan = (nameLines.length - 1) * LINE_H_PRIMARY;
+    contentSpan = nameCenterSpan + NAME_ID_GAP + idCenterSpan + HALF_EXTENT_PRIMARY + HALF_EXTENT_ID;
+  }
 
-  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 margin = Math.max(0, (opts.boxHeight - contentSpan) / 2);
+  const firstY = Math.round(opts.boxY + margin + HALF_EXTENT_PRIMARY);
 
   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;
+  const idFirstY = firstY + nameCenterSpan + 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 });
   }
@@ -291,6 +366,14 @@ export interface LayoutHeaderBlockTextOptions {
   marginX?: number;
 }
 
+/**
+ * Direct centre-to-centre gap between the header's name and id lines.
+ * Safely above the ~11px non-overlap floor (half of text-primary's 12px font
+ * + half of text-id's 10px font, per the #419 regression) but tighter than
+ * {@link NAME_ID_GAP} to fit the compact header strip.
+ */
+const HEADER_NAME_ID_GAP = 12;
+
 /** Container header: single-line name + id stacked in the header strip. */
 export function layoutHeaderBlockText(opts: LayoutHeaderBlockTextOptions): TextLineSpec[] {
   const marginX = opts.marginX ?? TEXT_MARGIN_X;
@@ -299,11 +382,14 @@ export function layoutHeaderBlockText(opts: LayoutHeaderBlockTextOptions): TextL
   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;
+
+  const contentSpan = HEADER_NAME_ID_GAP + HALF_EXTENT_PRIMARY + HALF_EXTENT_ID;
+  const margin = Math.max(0, (opts.headerHeight - contentSpan) / 2);
+  const nameY = Math.round(opts.boxY + margin + HALF_EXTENT_PRIMARY);
+  const idY = nameY + HEADER_NAME_ID_GAP;
   return [
-    { cls: 'text-primary', text: nameText, y: Math.round(headerMid - halfSpan) },
-    { cls: 'text-id', text: idText, y: Math.round(headerMid + halfSpan) },
+    { cls: 'text-primary', text: nameText, y: nameY },
+    { cls: 'text-id', text: idText, y: idY },
   ];
 }