@bendyline/squisq 1.5.2 → 2.0.0

package/src/__tests__/asciiTimelineRender.test.ts

@@ -0,0 +1,376 @@
+import { describe, expect, it } from 'vitest';
+import {
+  asciiTimelineToTemplateData,
+  detectAsciiTimeline,
+  parseAsciiTimeline,
+  renderAsciiTimeline,
+  type AsciiTimeline,
+} from '../doc/asciiTimeline/index.js';
+import {
+  TICK_INTERPOLATION_TIMELINE,
+  WRAPPED_CLIENT_KERNEL_TIMELINE,
+} from './fixtures/asciiTimelines.js';
+
+function renderFixpoint(timeline: AsciiTimeline, style?: 'unicode' | 'ascii'): string {
+  const first = renderAsciiTimeline(timeline, style ? { style } : {});
+  const second = renderAsciiTimeline(parseAsciiTimeline(first));
+  const third = renderAsciiTimeline(parseAsciiTimeline(second));
+  expect(second).toBe(first);
+  expect(third).toBe(first);
+  return first;
+}
+
+describe('renderAsciiTimeline', () => {
+  const timeline: AsciiTimeline = {
+    tracks: [
+      {
+        id: 'kernel',
+        label: 'kernel ticks (30 Hz)',
+        row: 4,
+        startColumn: 20,
+        endColumn: 65,
+        events: [
+          {
+            id: 'tick-28',
+            label: 'T28',
+            description: 'delta-28',
+            column: 22,
+            side: 'above',
+            marker: 'filled',
+          },
+          {
+            id: 'tick-29',
+            label: 'T29',
+            column: 38,
+            side: 'below',
+            marker: 'hollow',
+          },
+        ],
+      },
+      {
+        id: 'branch',
+        label: 'client frames',
+        row: 9,
+        startColumn: 30,
+        endColumn: 55,
+        events: [
+          {
+            id: 'render-point',
+            label: 'render position',
+            description: 'interpolate T28 to T29',
+            column: 42,
+            marker: 'diamond',
+          },
+        ],
+      },
+    ],
+    links: [{ source: 'tick-28', target: 'render-point', label: 'feeds renderer' }],
+    width: 80,
+    height: 12,
+    style: 'unicode',
+    warnings: [],
+  };
+
+  it('emits a continuous rail with pointer callouts and branch declarations', () => {
+    const output = renderFixpoint(timeline);
+    const lines = output.split('\n');
+    const kernelRail = lines.find((line) => line.includes('kernel ticks (30 Hz)'));
+
+    expect(kernelRail).toMatch(/kernel ticks \(30 Hz\) \{#kernel start=20 end=65\}: ─*●─*○─*►/u);
+    expect(output).toContain('▲ T28 :: delta-28 {#tick-28 column=22}');
+    expect(output).toContain('▼ T29 {#tick-29 column=38}');
+    expect(lines[lines.length - 1]).toBe('branch: tick-28 → render-point : feeds renderer');
+  });
+
+  it('uses parser-recognizable ASCII markers and rails', () => {
+    const output = renderFixpoint(timeline, 'ascii');
+
+    expect(output).toMatch(/^kernel ticks \(30 Hz\) \{#kernel start=20 end=65\}: -*\*-*o-*>/m);
+    expect(output).toContain('^ T28 :: delta-28 {#tick-28 column=22}');
+    expect(output).toContain('v T29 {#tick-29 column=38}');
+    expect(output).toContain('branch: tick-28 -> render-point : feeds renderer');
+    expect(output).not.toMatch(/[─●○◆►→]/u);
+  });
+
+  it('sorts tracks/events and drops unresolved links before the first render', () => {
+    const shuffled: AsciiTimeline = {
+      ...timeline,
+      tracks: [...timeline.tracks].reverse().map((track) => ({
+        ...track,
+        events: [...track.events].reverse(),
+      })),
+      links: [...timeline.links, { source: 'missing', target: 'tick-28' }],
+    };
+    const output = renderFixpoint(shuffled);
+
+    expect(output.indexOf('kernel ticks')).toBeLessThan(output.indexOf('client frames'));
+    expect(output.indexOf('T28')).toBeLessThan(output.indexOf('T29'));
+    expect(output).not.toContain('missing');
+  });
+
+  it('normalizes colliding ids and prose-heavy Unicode without fixpoint churn', () => {
+    const adversarial: AsciiTimeline = {
+      tracks: [
+        {
+          id: 'one',
+          row: 0,
+          startColumn: 0,
+          endColumn: 20,
+          events: [
+            { id: 'same', label: 'oooooooooooo', column: 0 },
+            { id: 'same', label: 'second', column: 10 },
+            { id: 'same_2', label: 'third', column: 20 },
+          ],
+        },
+      ],
+      links: [],
+      width: 21,
+      height: 1,
+      style: 'unicode',
+      warnings: [],
+    };
+    const output = renderFixpoint(adversarial);
+
+    expect(output).toContain('{#same column=0}');
+    expect(output).toContain('{#same_2 column=10}');
+    expect(output).toContain('{#same_2_2 column=20}');
+    expect(parseAsciiTimeline(output).style).toBe('unicode');
+  });
+
+  it('preserves shared geometry when track labels have different lengths', () => {
+    const geometry: AsciiTimeline = {
+      tracks: [
+        {
+          id: 'short',
+          label: 'A',
+          row: 0,
+          startColumn: 10,
+          endColumn: 110,
+          events: [
+            { id: 'a20', label: '20', column: 20 },
+            { id: 'a90', label: '90', column: 90 },
+          ],
+        },
+        {
+          id: 'long',
+          label: 'A much longer parallel track label',
+          row: 3,
+          startColumn: 10,
+          endColumn: 110,
+          events: [
+            { id: 'b20', label: '20', column: 20 },
+            { id: 'b90', label: '90', column: 90 },
+          ],
+        },
+      ],
+      links: [],
+      width: 111,
+      height: 4,
+      style: 'unicode',
+      warnings: [],
+    };
+    const before = asciiTimelineToTemplateData(geometry).tracks.map((track) =>
+      track.events.map((event) => event.position),
+    );
+    const rendered = renderFixpoint(geometry);
+    const parsed = parseAsciiTimeline(rendered);
+    const after = asciiTimelineToTemplateData(parsed).tracks.map((track) =>
+      track.events.map((event) => event.position),
+    );
+
+    expect(parsed.tracks.map((track) => [track.startColumn, track.endColumn])).toEqual([
+      [10, 110],
+      [10, 110],
+    ]);
+    expect(after).toEqual(before);
+  });
+
+  it('preserves internal arrows and double hyphens in event prose', () => {
+    const prose: AsciiTimeline = {
+      tracks: [
+        {
+          id: 'flow',
+          label: 'Flow',
+          row: 0,
+          startColumn: 0,
+          endColumn: 20,
+          events: [
+            {
+              id: 'compare',
+              label: 'Compare',
+              description: 'A > B; release--candidate',
+              column: 10,
+            },
+          ],
+        },
+      ],
+      links: [],
+      width: 21,
+      height: 1,
+      style: 'unicode',
+      warnings: [],
+    };
+    const parsed = parseAsciiTimeline(renderFixpoint(prose));
+
+    expect(parsed.tracks[0].events[0].description).toBe('A > B; release--candidate');
+  });
+
+  it('canonicalizes the exact sample without losing its cadence or callout semantics', () => {
+    const parsed = parseAsciiTimeline(TICK_INTERPOLATION_TIMELINE);
+    const before = asciiTimelineToTemplateData(parsed).tracks.map((track) =>
+      track.events.map((event) => event.position),
+    );
+    const output = renderFixpoint(parsed);
+    expect(detectAsciiTimeline(output).isTimeline).toBe(true);
+    expect(detectAsciiTimeline(output, { explicit: true }).isTimeline).toBe(true);
+    const reparsed = parseAsciiTimeline(output);
+    const [kernel, client] = reparsed.tracks;
+
+    expect(reparsed.tracks).toHaveLength(2);
+    expect(kernel.endLabel).toBe('sim time');
+    expect(kernel.events[0]).toMatchObject({
+      label: 'T28',
+      description: 'deltas sent: Δ28',
+      side: 'above',
+      descriptionSide: 'below',
+    });
+    expect(client.events.filter((event) => event.callout === false)).toHaveLength(16);
+    expect(client.events.map((event) => event.label)).toEqual(
+      expect.arrayContaining(['estimated kernel clock', 'render position']),
+    );
+    expect(
+      asciiTimelineToTemplateData(reparsed).tracks.map((track) =>
+        track.events.map((event) => event.position),
+      ),
+    ).toEqual(before);
+  });
+
+  it('canonicalizes wrapped flow art into a byte-stable point timeline', () => {
+    const wrapped = parseAsciiTimeline(WRAPPED_CLIENT_KERNEL_TIMELINE);
+    const output = renderFixpoint(wrapped);
+    const reparsed = parseAsciiTimeline(output);
+
+    expect(output).toContain('CLIENT (main thread)');
+    expect(output).toContain('KERNEL (Web Worker / Node)');
+    expect(output).toContain('branch: command-rejected-event → error-surfaced-to-user-agent');
+    expect(reparsed.tracks.map((track) => track.events.map((event) => event.id))).toEqual(
+      wrapped.tracks.map((track) => track.events.map((event) => event.id)),
+    );
+    expect(reparsed.links).toEqual(wrapped.links);
+  });
+
+  it('round-trips a hyphenated label ending in an ASCII-marker letter', () => {
+    const hyphenated: AsciiTimeline = {
+      tracks: [
+        {
+          id: 'flow',
+          row: 0,
+          startColumn: 0,
+          endColumn: 20,
+          events: [
+            { id: 'go', label: 'Go-live', column: 0 },
+            { id: 'done', label: 'Done', column: 20 },
+          ],
+        },
+      ],
+      links: [],
+      width: 21,
+      height: 1,
+      style: 'unicode',
+      warnings: [],
+    };
+
+    const parsed = parseAsciiTimeline(renderFixpoint(hyphenated));
+    expect(parsed.tracks[0].events.map((event) => [event.id, event.label])).toEqual([
+      ['go', 'Go-live'],
+      ['done', 'Done'],
+    ]);
+  });
+
+  it('does not treat marker letters beside double hyphens as ASCII events', () => {
+    const doubleHyphen: AsciiTimeline = {
+      tracks: [
+        {
+          id: 'ascii-flow',
+          row: 0,
+          startColumn: 0,
+          endColumn: 10,
+          events: [{ id: 'foo', label: 'foo--bar', column: 5 }],
+        },
+      ],
+      links: [],
+      width: 11,
+      height: 1,
+      style: 'ascii',
+      warnings: [],
+    };
+
+    const parsed = parseAsciiTimeline(renderFixpoint(doubleHyphen, 'ascii'));
+    expect(parsed.tracks[0].events).toMatchObject([{ id: 'foo', label: 'foo--bar' }]);
+  });
+
+  it('round-trips brace-delimited prose in a track end label', () => {
+    const braceSuffix: AsciiTimeline = {
+      tracks: [
+        {
+          id: 'release',
+          row: 0,
+          startColumn: 0,
+          endColumn: 10,
+          endLabel: 'status {beta}',
+          events: [
+            { id: 'a', label: 'A', column: 0 },
+            { id: 'b', label: 'B', column: 10 },
+          ],
+        },
+      ],
+      links: [],
+      width: 11,
+      height: 1,
+      style: 'unicode',
+      warnings: [],
+    };
+
+    const parsed = parseAsciiTimeline(renderFixpoint(braceSuffix));
+    expect(parsed.tracks[0].endLabel).toBe('status {beta}');
+    expect(parsed.tracks[0].events.map((event) => [event.id, event.label])).toEqual([
+      ['a', 'A'],
+      ['b', 'B'],
+    ]);
+  });
+
+  it.each(['unicode', 'ascii'] as const)(
+    'normalizes leading rail prose without %s fixpoint churn',
+    (style) => {
+      const leadingRails: AsciiTimeline = {
+        tracks: [
+          {
+            id: 'flags',
+            endLabel: '─-done',
+            row: 0,
+            startColumn: 0,
+            endColumn: 20,
+            events: [
+              { id: 'watch', label: '--watch', column: 0 },
+              { id: 'negative', label: '-1.5', column: 10 },
+              { id: 'phase', label: '─phase', column: 20 },
+            ],
+          },
+        ],
+        links: [],
+        width: 21,
+        height: 1,
+        style,
+        warnings: [],
+      };
+      const parsed = parseAsciiTimeline(renderFixpoint(leadingRails, style));
+
+      expect(parsed.tracks[0].events.map((event) => event.label)).toEqual([
+        '−−watch',
+        '−1.5',
+        '–phase',
+      ]);
+      expect(parsed.tracks[0].endLabel).toBe('–−done');
+    },
+  );
+});

package/src/__tests__/attrTokens.test.ts

@@ -120,6 +120,11 @@ describe('needsQuoting / quoteAttrValue', () => {
 });
 
 describe('matchTrailingTemplateAnnotation', () => {
+  it('matches an empty trailing annotation', () => {
+    const m = matchTrailingTemplateAnnotation('Heading {[]}');
+    expect(m?.inner).toBe('');
+  });
+
   it('matches a simple trailing annotation', () => {
     const m = matchTrailingTemplateAnnotation('Getting Started {[comparisonBar]}');
     expect(m?.inner).toBe('comparisonBar');

package/src/__tests__/contentContainer.test.ts

@@ -34,6 +34,38 @@ describe('MemoryContentContainer', () => {
     expect(new Uint8Array(result!)).toEqual(new Uint8Array([1, 2, 3, 4]));
   });
 
+  it('accepts ArrayBuffers created in another browser realm', async () => {
+    const iframe = document.createElement('iframe');
+    document.body.appendChild(iframe);
+    try {
+      const foreignWindow = iframe.contentWindow as unknown as {
+        ArrayBuffer: ArrayBufferConstructor;
+        Uint8Array: Uint8ArrayConstructor;
+      };
+      const data = new foreignWindow.ArrayBuffer(3);
+      new foreignWindow.Uint8Array(data).set([7, 8, 9]);
+      await container.writeFile('foreign.bin', data);
+      expect(new Uint8Array((await container.readFile('foreign.bin'))!)).toEqual(
+        new Uint8Array([7, 8, 9]),
+      );
+    } finally {
+      iframe.remove();
+    }
+  });
+
+  it('owns copies on both write and read', async () => {
+    const input = new ArrayBuffer(2);
+    new Uint8Array(input).set([1, 2]);
+    await container.writeFile('owned.bin', input);
+
+    new Uint8Array(input)[0] = 9;
+    const firstRead = (await container.readFile('owned.bin'))!;
+    expect(Array.from(new Uint8Array(firstRead))).toEqual([1, 2]);
+
+    new Uint8Array(firstRead)[1] = 9;
+    expect(Array.from(new Uint8Array((await container.readFile('owned.bin'))!))).toEqual([1, 2]);
+  });
+
   it('writeFile overwrites existing file', async () => {
     await container.writeFile('f.txt', new TextEncoder().encode('first'));
     await container.writeFile('f.txt', new TextEncoder().encode('second'));
@@ -120,6 +152,12 @@ describe('getDocumentPath', () => {
     expect(await container.getDocumentPath()).toBe('index.md');
   });
 
+  it('preserves the actual case of a priority filename', async () => {
+    await container.writeFile('Index.MD', new TextEncoder().encode('# Hello'));
+    expect(await container.getDocumentPath()).toBe('Index.MD');
+    expect(await container.readDocument()).toBe('# Hello');
+  });
+
   it('prefers index.md over doc.md', async () => {
     await container.writeFile('doc.md', new TextEncoder().encode('doc'));
     await container.writeFile('index.md', new TextEncoder().encode('index'));
@@ -196,6 +234,11 @@ describe('findDocumentPath', () => {
     expect(findDocumentPath(entries)).toBe('index.md');
   });
 
+  it('returns the matched entry path rather than a lower-cased synthetic path', () => {
+    const entries: ContentEntry[] = [{ path: 'INDEX.md', mimeType: 'text/markdown', size: 50 }];
+    expect(findDocumentPath(entries)).toBe('INDEX.md');
+  });
+
   it('skips subdirectory .md files', () => {
     const entries: ContentEntry[] = [
       { path: 'docs/guide.md', mimeType: 'text/markdown', size: 50 },

package/src/__tests__/customTemplatesFrontmatter.test.ts

@@ -10,8 +10,6 @@ import { describe, it, expect, vi } from 'vitest';
 import { markdownToDoc } from '../doc/markdownToDoc';
 import { docToMarkdown } from '../doc/docToMarkdown';
 import {
-  encodeLayersForFrontmatter,
-  decodeLayersFromFrontmatter,
   readCustomTemplatesFromFrontmatter,
   writeCustomTemplatesToFrontmatter,
   FRONTMATTER_CUSTOM_TEMPLATES_KEY,
@@ -43,19 +41,6 @@ const heroDef: CustomTemplateDefinition = {
   layers: sampleLayers,
 };
 
-describe('encodeLayersForFrontmatter ↔ decodeLayersFromFrontmatter', () => {
-  it('round-trips a single Layer array verbatim', () => {
-    const encoded = encodeLayersForFrontmatter(sampleLayers);
-    const decoded = decodeLayersFromFrontmatter(encoded);
-    expect(decoded).toEqual(sampleLayers);
-  });
-
-  it("returns [] when the base64 isn't valid JSON", () => {
-    const garbage = encodeLayersForFrontmatter(sampleLayers).slice(0, 4);
-    expect(decodeLayersFromFrontmatter(garbage)).toEqual([]);
-  });
-});
-
 describe('writeCustomTemplatesToFrontmatter → readCustomTemplatesFromFrontmatter', () => {
   it('round-trips a single definition through the compact JSON wire format', () => {
     const payload = writeCustomTemplatesToFrontmatter([heroDef]);

package/src/__tests__/dataTable.test.ts

@@ -1,5 +1,6 @@
 import { describe, it, expect } from 'vitest';
-import { getLayers, RenderContext } from '../doc/getLayers.js';
+import type { MaterializeBlockLayersOptions } from '../doc/materializeBlockLayers.js';
+import { materializeLayers } from './materializeTestUtils.js';
 import { DEFAULT_THEME } from '../schemas/themeLibrary.js';
 import { VIEWPORT_PRESETS } from '../schemas/Viewport.js';
 import type { TemplateBlock } from '../schemas/BlockTemplates.js';
@@ -24,7 +25,7 @@ function makeDataTableBlock(overrides: Record<string, unknown> = {}): TemplateBl
   } as TemplateBlock;
 }
 
-const defaultContext: RenderContext = {
+const defaultContext: MaterializeBlockLayersOptions = {
   theme: DEFAULT_THEME,
   viewport: VIEWPORT_PRESETS.landscape,
   blockIndex: 0,
@@ -37,7 +38,7 @@ const defaultContext: RenderContext = {
 
 describe('dataTable template', () => {
   it('produces layers including a table layer', () => {
-    const layers = getLayers(makeDataTableBlock(), defaultContext);
+    const layers = materializeLayers(makeDataTableBlock(), defaultContext);
     expect(layers.length).toBeGreaterThan(0);
 
     const tableLayer = layers.find((l) => l.type === 'table');
@@ -45,14 +46,14 @@ describe('dataTable template', () => {
   });
 
   it('table layer contains the correct headers', () => {
-    const layers = getLayers(makeDataTableBlock(), defaultContext);
+    const layers = materializeLayers(makeDataTableBlock(), defaultContext);
     const tableLayer = layers.find((l) => l.type === 'table') as TableLayer;
 
     expect(tableLayer.content.headers).toEqual(['Name', 'Value']);
   });
 
   it('table layer contains the correct rows', () => {
-    const layers = getLayers(makeDataTableBlock(), defaultContext);
+    const layers = materializeLayers(makeDataTableBlock(), defaultContext);
     const tableLayer = layers.find((l) => l.type === 'table') as TableLayer;
 
     expect(tableLayer.content.rows).toEqual([
@@ -62,7 +63,7 @@ describe('dataTable template', () => {
   });
 
   it('includes a title text layer when title is provided', () => {
-    const layers = getLayers(makeDataTableBlock({ title: 'My Table' }), defaultContext);
+    const layers = materializeLayers(makeDataTableBlock({ title: 'My Table' }), defaultContext);
     const textLayers = layers.filter((l) => l.type === 'text');
 
     expect(textLayers.length).toBeGreaterThanOrEqual(1);
@@ -71,7 +72,7 @@ describe('dataTable template', () => {
   });
 
   it('omits title layer when no title is given', () => {
-    const layers = getLayers(makeDataTableBlock({ title: undefined }), defaultContext);
+    const layers = materializeLayers(makeDataTableBlock({ title: undefined }), defaultContext);
     const textLayers = layers.filter((l) => l.type === 'text');
 
     // Should have no text layers (only bg + table)
@@ -79,20 +80,23 @@ describe('dataTable template', () => {
   });
 
   it('includes a background layer', () => {
-    const layers = getLayers(makeDataTableBlock(), defaultContext);
+    const layers = materializeLayers(makeDataTableBlock(), defaultContext);
     // Background is the first layer (shape with gradient fill)
     expect(['shape', 'image']).toContain(layers[0].type);
   });
 
   it('passes column alignment to the table layer', () => {
-    const layers = getLayers(makeDataTableBlock({ align: ['left', 'right'] }), defaultContext);
+    const layers = materializeLayers(
+      makeDataTableBlock({ align: ['left', 'right'] }),
+      defaultContext,
+    );
     const tableLayer = layers.find((l) => l.type === 'table') as TableLayer;
 
     expect(tableLayer.content.align).toEqual(['left', 'right']);
   });
 
   it('applies theme colors to table styling', () => {
-    const layers = getLayers(makeDataTableBlock(), defaultContext);
+    const layers = materializeLayers(makeDataTableBlock(), defaultContext);
     const tableLayer = layers.find((l) => l.type === 'table') as TableLayer;
     const style = tableLayer.content.style;
 
@@ -106,8 +110,11 @@ describe('dataTable template', () => {
   });
 
   it('adjusts table position when title is present vs absent', () => {
-    const withTitle = getLayers(makeDataTableBlock({ title: 'Title' }), defaultContext);
-    const withoutTitle = getLayers(makeDataTableBlock({ title: undefined }), defaultContext);
+    const withTitle = materializeLayers(makeDataTableBlock({ title: 'Title' }), defaultContext);
+    const withoutTitle = materializeLayers(
+      makeDataTableBlock({ title: undefined }),
+      defaultContext,
+    );
 
     const tableWithTitle = withTitle.find((l) => l.type === 'table') as TableLayer;
     const tableWithoutTitle = withoutTitle.find((l) => l.type === 'table') as TableLayer;
@@ -117,18 +124,21 @@ describe('dataTable template', () => {
   });
 
   it('works with portrait viewport', () => {
-    const portraitContext: RenderContext = {
+    const portraitContext: MaterializeBlockLayersOptions = {
       ...defaultContext,
       viewport: VIEWPORT_PRESETS.portrait,
     };
-    const layers = getLayers(makeDataTableBlock(), portraitContext);
+    const layers = materializeLayers(makeDataTableBlock(), portraitContext);
     expect(layers.length).toBeGreaterThan(0);
     const tableLayer = layers.find((l) => l.type === 'table');
     expect(tableLayer).toBeDefined();
   });
 
   it('handles empty rows gracefully', () => {
-    const layers = getLayers(makeDataTableBlock({ headers: ['A', 'B'], rows: [] }), defaultContext);
+    const layers = materializeLayers(
+      makeDataTableBlock({ headers: ['A', 'B'], rows: [] }),
+      defaultContext,
+    );
     const tableLayer = layers.find((l) => l.type === 'table') as TableLayer;
     expect(tableLayer.content.rows).toEqual([]);
   });

package/src/__tests__/diagramBlock.test.ts

@@ -98,9 +98,9 @@ describe('diagramBlock template', () => {
   });
 });
 
-describe('diagramBlock integration with getLayers', () => {
+describe('diagramBlock integration with materializeBlockLayers', () => {
   it('renders through the full template registry', async () => {
-    const { getLayers } = await import('../doc/getLayers.js');
+    const { materializeBlockLayers } = await import('../doc/materializeBlockLayers.js');
     const parentBlock: Block = {
       id: 'family',
       startTime: 0,
@@ -113,7 +113,7 @@ describe('diagramBlock integration with getLayers', () => {
         makeBlock({ id: 'b', title: 'B', x: 400, y: 100, connectsTo: [{ target: 'a' }] }),
       ],
     };
-    const layers = getLayers(parentBlock, {});
+    const layers = materializeBlockLayers(parentBlock, { persistentLayers: false }).layers;
     // Should contain at least one shape (node card) and one path (edge).
     const types = new Set(layers.map((l: Layer) => l.type));
     expect(types.has('shape')).toBe(true);

package/src/__tests__/diagramText.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+import { DIAGRAM_LABEL_LINE_HEIGHT, fitDiagramLabel } from '../doc/utils/diagramText';
+
+describe('fitDiagramLabel', () => {
+  it('keeps a short single-line label at its preferred size', () => {
+    expect(fitDiagramLabel('Web1', 180, 64, 22)).toMatchObject({
+      fontSize: 22,
+      lineCount: 1,
+      firstLineOffset: 0,
+    });
+  });
+
+  it('shrinks and centers a dense multi-line package label inside its card', () => {
+    const fit = fitDiagramLabel(
+      '@bendyline/molen-kernel\nheadless sim — no DOM, no thread\nWorker + Node',
+      252,
+      112,
+      38,
+    );
+
+    expect(fit.fontSize).toBeLessThan(38);
+    expect(fit.lineCount).toBeGreaterThanOrEqual(3);
+    expect(fit.lineCount * fit.fontSize * DIAGRAM_LABEL_LINE_HEIGHT).toBeLessThanOrEqual(96);
+    expect(fit.firstLineOffset).toBeLessThan(0);
+  });
+});