@bendyline/squisq 1.4.0 → 1.5.0

package/src/__tests__/customTemplateSample.test.ts

@@ -0,0 +1,83 @@
+/**
+ * End-to-end sanity check: the kind of doc a user might compose by
+ * hand (or via the upcoming TemplateDesigner) renders through the
+ * markdown → Doc → expanded layers pipeline with tokens substituted.
+ *
+ * Build-the-payload-here so the test doesn't depend on the site
+ * package — it's verifying the pure pipeline.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { markdownToDoc } from '../doc/markdownToDoc';
+import { expandDocBlocks } from '../doc/templates/index';
+import { parseMarkdown } from '../markdown/parse';
+import { writeCustomTemplatesToFrontmatter } from '../doc/customTemplatesFrontmatter';
+import type { CustomTemplateDefinition } from '../schemas/CustomTemplates.js';
+import type { TextLayer } from '../schemas/Doc.js';
+import { VIEWPORT_PRESETS } from '../schemas/Viewport.js';
+
+const heroDef: CustomTemplateDefinition = {
+  name: 'hero',
+  label: 'Hero Section',
+  viewport: { width: 1920, height: 1080 },
+  layers: [
+    {
+      id: 'hero-title',
+      type: 'text',
+      position: { x: '6%', y: '20%', width: '88%' },
+      content: {
+        text: '{title}',
+        style: { fontSize: 96, color: '#0f172a' },
+      },
+    },
+    {
+      id: 'hero-body',
+      type: 'text',
+      position: { x: '6%', y: '52%', width: '88%' },
+      content: {
+        text: '{content}',
+        style: { fontSize: 36, color: '#475569' },
+      },
+    },
+  ],
+};
+
+function buildSampleMarkdown(): string {
+  const payload = writeCustomTemplatesToFrontmatter([heroDef]);
+  return `---
+squisq-custom-templates: "${payload}"
+---
+
+# Welcome to Squisq {[hero]}
+
+A small editor for big ideas.
+`;
+}
+
+describe('Custom template pipeline (markdown → expanded layers)', () => {
+  it('substitutes {title} and {content} when a doc uses a frontmatter-defined template', () => {
+    const doc = markdownToDoc(parseMarkdown(buildSampleMarkdown()));
+    const blocks = expandDocBlocks(doc.blocks, {
+      customTemplates: doc.customTemplates,
+    });
+    expect(blocks).toHaveLength(1);
+    const layers = blocks[0].layers ?? [];
+    expect(layers).toHaveLength(2);
+
+    expect((layers[0] as TextLayer).content.text).toBe('Welcome to Squisq');
+    expect((layers[1] as TextLayer).content.text).toBe('A small editor for big ideas.');
+  });
+
+  it('renders the same template against a portrait viewport without re-authoring', () => {
+    const doc = markdownToDoc(parseMarkdown(buildSampleMarkdown()));
+    const blocks = expandDocBlocks(doc.blocks, {
+      customTemplates: doc.customTemplates,
+      viewport: VIEWPORT_PRESETS.portrait,
+    });
+    const layers = blocks[0].layers ?? [];
+    // %-based positions survive the viewport switch — the SSR
+    // renderer resolves them against the actual viewport at draw time.
+    expect(layers[0].position.x).toBe('6%');
+    expect(layers[0].position.width).toBe('88%');
+  });
+});

package/src/__tests__/customTemplatesFrontmatter.test.ts

@@ -0,0 +1,205 @@
+/**
+ * Custom templates round-trip through frontmatter.
+ *
+ * Verifies that a CustomTemplateDefinition stored in markdown
+ * frontmatter is faithfully reconstructed by `markdownToDoc` and
+ * serialized back by `docToMarkdown` without loss.
+ */
+
+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,
+} from '../doc/customTemplatesFrontmatter';
+import { parseMarkdown } from '../markdown/parse';
+import type { Layer } from '../schemas/Doc.js';
+import type { CustomTemplateDefinition } from '../schemas/CustomTemplates.js';
+
+const sampleLayers: Layer[] = [
+  {
+    id: 'title',
+    type: 'text',
+    position: { x: '5%', y: '10%', width: '90%' },
+    content: { text: '{title}', style: { fontSize: 72, color: '#000' } },
+  },
+  {
+    id: 'body',
+    type: 'text',
+    position: { x: '5%', y: '40%', width: '90%' },
+    content: { text: '{content}', style: { fontSize: 32, color: '#333' } },
+  },
+];
+
+const heroDef: CustomTemplateDefinition = {
+  name: 'hero',
+  label: 'Hero',
+  description: 'Large title with body below.',
+  viewport: { width: 1920, height: 1080 },
+  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]);
+    expect(typeof payload).toBe('string');
+    // Compact form: a readable JSON object keyed by name, short keys, no
+    // base64, and the default 1920×1080 viewport omitted.
+    expect(payload!.startsWith('{"hero":')).toBe(true);
+    expect(payload).toContain('"lb":"Hero"');
+    expect(payload).not.toContain('"viewport"');
+    const fm = { [FRONTMATTER_CUSTOM_TEMPLATES_KEY]: payload };
+    const out = readCustomTemplatesFromFrontmatter(fm);
+    expect(out).toHaveLength(1);
+    expect(out![0]).toEqual(heroDef);
+  });
+
+  it('is markedly smaller than the legacy base64 form', () => {
+    const compact = writeCustomTemplatesToFrontmatter([heroDef])!;
+    const legacyBase64 = btoa(unescape(encodeURIComponent(JSON.stringify([{ ...heroDef }]))));
+    expect(compact.length).toBeLessThan(legacyBase64.length);
+  });
+
+  it('still reads the legacy base64-JSON payload (back-compat)', () => {
+    // What older documents have on disk: base64 of the full-keyed array.
+    const legacy = btoa(unescape(encodeURIComponent(JSON.stringify([heroDef]))));
+    const out = readCustomTemplatesFromFrontmatter({
+      [FRONTMATTER_CUSTOM_TEMPLATES_KEY]: legacy,
+    });
+    expect(out).toHaveLength(1);
+    expect(out![0]).toEqual(heroDef);
+  });
+
+  it('round-trips layers carrying the full styling field set without loss', () => {
+    const rich: CustomTemplateDefinition = {
+      name: 'rich',
+      label: 'Rich',
+      viewport: { width: 1080, height: 1080 },
+      layers: [
+        {
+          id: 'p',
+          type: 'path',
+          position: { x: '1%', y: '2%', width: '3%', height: '4%', anchor: 'center' },
+          content: {
+            d: 'M0 0',
+            shapeKind: 'star',
+            fill: '#fff',
+            fillOpacity: 0.5,
+            gradient: { from: '#000', to: '#fff', angle: 90 },
+            stroke: '#111',
+            strokeWidth: 3,
+            borderStyle: 'dashed',
+            dasharray: '4 2',
+          },
+        } as Layer,
+      ],
+    };
+    const payload = writeCustomTemplatesToFrontmatter([rich])!;
+    const out = readCustomTemplatesFromFrontmatter({ [FRONTMATTER_CUSTOM_TEMPLATES_KEY]: payload });
+    expect(out![0]).toEqual(rich);
+  });
+
+  it('round-trips multiple definitions in declaration order', () => {
+    const second: CustomTemplateDefinition = { ...heroDef, name: 'second', label: 'Second' };
+    const payload = writeCustomTemplatesToFrontmatter([heroDef, second]);
+    const out = readCustomTemplatesFromFrontmatter({
+      [FRONTMATTER_CUSTOM_TEMPLATES_KEY]: payload,
+    });
+    expect(out!.map((d) => d.name)).toEqual(['hero', 'second']);
+  });
+
+  it('also accepts an already-decoded array shape (forward-compatible)', () => {
+    const out = readCustomTemplatesFromFrontmatter({
+      [FRONTMATTER_CUSTOM_TEMPLATES_KEY]: [
+        {
+          name: 'hero',
+          label: 'Hero',
+          viewport: { width: 1920, height: 1080 },
+          layers: sampleLayers,
+        },
+      ],
+    });
+    expect(out).toHaveLength(1);
+    expect(out![0].name).toBe('hero');
+  });
+
+  it('returns undefined when the key is absent', () => {
+    expect(readCustomTemplatesFromFrontmatter({})).toBeUndefined();
+    expect(readCustomTemplatesFromFrontmatter(undefined)).toBeUndefined();
+  });
+
+  it("returns undefined when the encoded string isn't a valid array", () => {
+    const fm = { [FRONTMATTER_CUSTOM_TEMPLATES_KEY]: 'not-base64-of-an-array' };
+    expect(readCustomTemplatesFromFrontmatter(fm)).toBeUndefined();
+  });
+});
+
+describe('Doc.customTemplates round-trip via markdownToDoc + docToMarkdown', () => {
+  it('survives a markdownToDoc → docToMarkdown cycle', () => {
+    const encoded = writeCustomTemplatesToFrontmatter([heroDef])!;
+    // Compact JSON is stored unquoted — it round-trips verbatim through
+    // the line-based frontmatter parser.
+    const sourceMd = `---
+title: My Doc
+squisq-custom-templates: ${encoded}
+---
+
+# Welcome {[hero]}
+
+A small editor for big ideas.
+`;
+    const doc = markdownToDoc(parseMarkdown(sourceMd));
+    expect(doc.customTemplates).toBeDefined();
+    expect(doc.customTemplates).toHaveLength(1);
+    expect(doc.customTemplates![0].name).toBe('hero');
+    expect(doc.customTemplates![0].layers).toEqual(sampleLayers);
+
+    // Round-trip back — docToMarkdown must restore the frontmatter
+    // entry with an equivalent encoded payload.
+    const mdOut = docToMarkdown(doc);
+    expect(mdOut.frontmatter).toBeDefined();
+    const payload = mdOut.frontmatter![FRONTMATTER_CUSTOM_TEMPLATES_KEY];
+    expect(typeof payload).toBe('string');
+    const reread = readCustomTemplatesFromFrontmatter({
+      [FRONTMATTER_CUSTOM_TEMPLATES_KEY]: payload,
+    });
+    expect(reread).toEqual(doc.customTemplates);
+  });
+
+  it('drops the frontmatter key when the doc has no custom templates anymore', () => {
+    void vi; // imported for parity; not used here
+    const doc = {
+      articleId: 'd',
+      duration: 0,
+      blocks: [],
+      audio: { segments: [] },
+      // Stale frontmatter from an earlier save when the doc DID have
+      // custom templates — but doc.customTemplates is now empty.
+      frontmatter: {
+        title: 'Doc',
+        [FRONTMATTER_CUSTOM_TEMPLATES_KEY]: 'stale-base64-blob',
+      },
+    };
+    const md = docToMarkdown(doc);
+    expect(md.frontmatter).toBeDefined();
+    expect(md.frontmatter).not.toHaveProperty(FRONTMATTER_CUSTOM_TEMPLATES_KEY);
+    expect(md.frontmatter!.title).toBe('Doc');
+  });
+});

package/src/__tests__/customThemesFrontmatter.test.ts

@@ -0,0 +1,118 @@
+/**
+ * Custom themes round-trip through frontmatter.
+ *
+ * The theme analog of customTemplatesFrontmatter.test.ts: verifies that a
+ * Theme stored in markdown frontmatter under `squisq-custom-themes` is
+ * faithfully reconstructed by `markdownToDoc` and serialized back by
+ * `docToMarkdown` without loss, and that the reader is tolerant of malformed
+ * entries.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { markdownToDoc } from '../doc/markdownToDoc';
+import { docToMarkdown } from '../doc/docToMarkdown';
+import {
+  readCustomThemesFromFrontmatter,
+  writeCustomThemesToFrontmatter,
+  FRONTMATTER_CUSTOM_THEMES_KEY,
+} from '../doc/customThemesFrontmatter';
+import { parseMarkdown } from '../markdown/parse';
+import { compileTheme } from '../schemas/themeCompile';
+import type { Doc } from '../schemas/Doc.js';
+import type { Theme } from '../schemas/Theme.js';
+
+const brand: Theme = compileTheme({
+  id: 'my-brand',
+  name: 'My Brand',
+  seedColors: { primary: '#3182ce', secondary: '#805ad5' },
+});
+
+describe('writeCustomThemesToFrontmatter → readCustomThemesFromFrontmatter', () => {
+  it('round-trips a single theme through the compact JSON wire format', () => {
+    const payload = writeCustomThemesToFrontmatter([brand]);
+    expect(typeof payload).toBe('string');
+    expect(payload!.startsWith('{"my-brand":')).toBe(true);
+    const out = readCustomThemesFromFrontmatter({ [FRONTMATTER_CUSTOM_THEMES_KEY]: payload });
+    expect(out).toHaveLength(1);
+    expect(out![0]).toEqual(brand);
+  });
+
+  it('round-trips multiple themes keyed by id', () => {
+    const second = compileTheme({
+      id: 'second',
+      name: 'Second',
+      seedColors: { primary: '#e53e3e' },
+    });
+    const payload = writeCustomThemesToFrontmatter([brand, second]);
+    const out = readCustomThemesFromFrontmatter({ [FRONTMATTER_CUSTOM_THEMES_KEY]: payload });
+    expect(out!.map((t) => t.id).sort()).toEqual(['my-brand', 'second']);
+  });
+
+  it('also accepts an already-decoded object map (forward-compatible)', () => {
+    const out = readCustomThemesFromFrontmatter({
+      [FRONTMATTER_CUSTOM_THEMES_KEY]: { 'my-brand': brand },
+    });
+    expect(out).toHaveLength(1);
+    expect(out![0].id).toBe('my-brand');
+  });
+
+  it('drops invalid themes rather than failing the whole load', () => {
+    const payload = JSON.stringify({ 'my-brand': brand, junk: { id: 'junk' } });
+    const out = readCustomThemesFromFrontmatter({ [FRONTMATTER_CUSTOM_THEMES_KEY]: payload });
+    expect(out).toHaveLength(1);
+    expect(out![0].id).toBe('my-brand');
+  });
+
+  it('returns undefined when the key is absent or unparseable', () => {
+    expect(readCustomThemesFromFrontmatter({})).toBeUndefined();
+    expect(readCustomThemesFromFrontmatter(undefined)).toBeUndefined();
+    expect(
+      readCustomThemesFromFrontmatter({ [FRONTMATTER_CUSTOM_THEMES_KEY]: 'not json' }),
+    ).toBeUndefined();
+  });
+});
+
+describe('Doc.customThemes round-trip via markdownToDoc + docToMarkdown', () => {
+  it('survives a markdownToDoc → docToMarkdown cycle and keeps the selection', () => {
+    const encoded = writeCustomThemesToFrontmatter([brand])!;
+    // Compact JSON is stored unquoted — it round-trips verbatim through the
+    // line-based frontmatter parser, exactly like custom templates.
+    const sourceMd = `---
+title: My Doc
+squisq-theme: my-brand
+squisq-custom-themes: ${encoded}
+---
+
+# Welcome
+
+A small editor for big ideas.
+`;
+    const doc = markdownToDoc(parseMarkdown(sourceMd));
+    expect(doc.customThemes).toHaveLength(1);
+    expect(doc.customThemes![0]).toEqual(brand);
+
+    const mdOut = docToMarkdown(doc);
+    const payload = mdOut.frontmatter![FRONTMATTER_CUSTOM_THEMES_KEY];
+    expect(typeof payload).toBe('string');
+    const reread = readCustomThemesFromFrontmatter({ [FRONTMATTER_CUSTOM_THEMES_KEY]: payload });
+    expect(reread).toEqual(doc.customThemes);
+    // The active selection is preserved untouched.
+    expect(mdOut.frontmatter!['squisq-theme']).toBe('my-brand');
+  });
+
+  it('drops the frontmatter key when the doc has no custom themes anymore', () => {
+    const doc: Doc = {
+      articleId: 'd',
+      duration: 0,
+      blocks: [],
+      audio: { segments: [] },
+      frontmatter: {
+        title: 'Doc',
+        [FRONTMATTER_CUSTOM_THEMES_KEY]: 'stale-blob',
+      },
+    };
+    const md = docToMarkdown(doc);
+    expect(md.frontmatter).not.toHaveProperty(FRONTMATTER_CUSTOM_THEMES_KEY);
+    expect(md.frontmatter!.title).toBe('Doc');
+  });
+});

package/src/__tests__/diagramBlock.test.ts

@@ -0,0 +1,122 @@
+import { describe, it, expect } from 'vitest';
+import { diagramBlock } from '../doc/templates/diagramBlock.js';
+import { createTemplateContext } from '../schemas/BlockTemplates.js';
+import { DEFAULT_THEME } from '../schemas/themeLibrary.js';
+import { VIEWPORT_PRESETS } from '../schemas/Viewport.js';
+import type { Block, Layer, ShapeLayer, PathLayer, TextLayer } from '../schemas/Doc.js';
+import type { DiagramBlockInput } from '../schemas/BlockTemplates.js';
+
+function makeBlock(overrides: Partial<Block> & { id: string }): Block {
+  return {
+    startTime: 0,
+    duration: 0,
+    audioSegment: 0,
+    ...overrides,
+  } as Block;
+}
+
+function makeInput(overrides: Partial<DiagramBlockInput> = {}): DiagramBlockInput {
+  return {
+    template: 'diagram',
+    id: 'family-tree',
+    duration: 0,
+    audioSegment: 0,
+    ...overrides,
+  };
+}
+
+describe('diagramBlock template', () => {
+  it('emits node card + label layers for each child', () => {
+    const ctx = createTemplateContext(DEFAULT_THEME, 0, 1, VIEWPORT_PRESETS.landscape);
+    ctx.children = [
+      makeBlock({ id: 'a', title: 'Alpha', x: 100, y: 100 }),
+      makeBlock({ id: 'b', title: 'Beta', x: 400, y: 100 }),
+    ];
+    const layers = diagramBlock(makeInput(), ctx);
+    const cards = layers.filter((l) => l.type === 'shape') as ShapeLayer[];
+    const texts = layers.filter((l) => l.type === 'text') as TextLayer[];
+    expect(cards.length).toBe(2);
+    expect(texts.length).toBe(2);
+    expect(texts[0].content.text).toBe('Alpha');
+    expect(texts[1].content.text).toBe('Beta');
+  });
+
+  it('emits a path layer with arrow for each connectsTo entry', () => {
+    const ctx = createTemplateContext(DEFAULT_THEME, 0, 1, VIEWPORT_PRESETS.landscape);
+    ctx.children = [
+      makeBlock({ id: 'a', x: 100, y: 100, connectsTo: [{ target: 'b' }] }),
+      makeBlock({ id: 'b', x: 400, y: 100 }),
+    ];
+    const layers = diagramBlock(makeInput(), ctx);
+    const paths = layers.filter((l) => l.type === 'path') as PathLayer[];
+    expect(paths.length).toBe(1);
+    expect(paths[0].content.endMarker).toBe('arrow');
+    expect(paths[0].content.d.startsWith('M ')).toBe(true);
+  });
+
+  it('emits a typed edge label when connection has a type', () => {
+    const ctx = createTemplateContext(DEFAULT_THEME, 0, 1, VIEWPORT_PRESETS.landscape);
+    ctx.children = [
+      makeBlock({ id: 'a', x: 100, y: 100, connectsTo: [{ target: 'b', type: 'requires' }] }),
+      makeBlock({ id: 'b', x: 400, y: 100 }),
+    ];
+    const layers = diagramBlock(makeInput(), ctx);
+    const labels = layers.filter(
+      (l): l is TextLayer => l.type === 'text' && l.id.startsWith('edge-label-'),
+    );
+    expect(labels.length).toBe(1);
+    expect(labels[0].content.text).toBe('requires');
+  });
+
+  it('returns a single hint text layer when there are no children', () => {
+    const ctx = createTemplateContext(DEFAULT_THEME, 0, 1, VIEWPORT_PRESETS.landscape);
+    ctx.children = [];
+    const layers = diagramBlock(makeInput({ title: 'Empty' }), ctx);
+    expect(layers.length).toBe(1);
+    expect(layers[0].type).toBe('text');
+  });
+
+  it('emits a title layer when input.title is set', () => {
+    const ctx = createTemplateContext(DEFAULT_THEME, 0, 1, VIEWPORT_PRESETS.landscape);
+    ctx.children = [makeBlock({ id: 'a', title: 'A', x: 100, y: 100 })];
+    const layers = diagramBlock(makeInput({ title: 'My Diagram' }), ctx);
+    const titleLayer = layers.find((l): l is TextLayer => l.id === 'diagram-title');
+    expect(titleLayer).toBeDefined();
+    expect(titleLayer?.content.text).toBe('My Diagram');
+  });
+
+  it('handles children without explicit positions via auto-layout', () => {
+    const ctx = createTemplateContext(DEFAULT_THEME, 0, 1, VIEWPORT_PRESETS.landscape);
+    ctx.children = [
+      makeBlock({ id: 'a', title: 'A' }),
+      makeBlock({ id: 'b', title: 'B' }),
+      makeBlock({ id: 'c', title: 'C' }),
+    ];
+    const layers = diagramBlock(makeInput(), ctx);
+    const cards = layers.filter((l) => l.type === 'shape');
+    expect(cards.length).toBe(3);
+  });
+});
+
+describe('diagramBlock integration with getLayers', () => {
+  it('renders through the full template registry', async () => {
+    const { getLayers } = await import('../doc/getLayers.js');
+    const parentBlock: Block = {
+      id: 'family',
+      startTime: 0,
+      duration: 0,
+      audioSegment: 0,
+      template: 'diagram',
+      title: 'Family Tree',
+      children: [
+        makeBlock({ id: 'a', title: 'A', x: 100, y: 100 }),
+        makeBlock({ id: 'b', title: 'B', x: 400, y: 100, connectsTo: [{ target: 'a' }] }),
+      ],
+    };
+    const layers = getLayers(parentBlock, {});
+    // 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);
+    expect(types.has('path')).toBe(true);
+  });
+});

package/src/__tests__/diagramLayout.test.ts

@@ -0,0 +1,134 @@
+import { describe, it, expect } from 'vitest';
+import { computeDiagramLayout } from '../doc/templates/diagramLayout.js';
+import type { Block } from '../schemas/Doc.js';
+
+function makeBlock(overrides: Partial<Block> & { id: string }): Block {
+  return {
+    startTime: 0,
+    duration: 0,
+    audioSegment: 0,
+    ...overrides,
+  } as Block;
+}
+
+describe('computeDiagramLayout', () => {
+  it('keeps explicit x/y positions intact', () => {
+    const layout = computeDiagramLayout([
+      makeBlock({ id: 'a', x: 100, y: 200 }),
+      makeBlock({ id: 'b', x: 400, y: 300 }),
+    ]);
+    expect(layout.nodes).toHaveLength(2);
+    expect(layout.nodes[0]).toMatchObject({ id: 'a', x: 100, y: 200, pinned: true });
+    expect(layout.nodes[1]).toMatchObject({ id: 'b', x: 400, y: 300, pinned: true });
+  });
+
+  it('auto-positions children missing x or y in a grid below pinned nodes', () => {
+    const layout = computeDiagramLayout([
+      makeBlock({ id: 'pinned', x: 200, y: 100 }),
+      makeBlock({ id: 'a' }),
+      makeBlock({ id: 'b' }),
+      makeBlock({ id: 'c' }),
+      makeBlock({ id: 'd' }),
+    ]);
+    expect(layout.nodes.find((n) => n.id === 'pinned')?.pinned).toBe(true);
+    const auto = layout.nodes.filter((n) => n.id !== 'pinned');
+    for (const node of auto) {
+      expect(node.pinned).toBe(false);
+      // Should sit below the pinned node's y.
+      expect(node.y).toBeGreaterThan(100);
+    }
+  });
+
+  it('places fully-unpositioned children starting at the default origin', () => {
+    const layout = computeDiagramLayout([
+      makeBlock({ id: 'a', title: 'A' }),
+      makeBlock({ id: 'b', title: 'B' }),
+    ]);
+    expect(layout.nodes[0].pinned).toBe(false);
+    expect(layout.nodes[1].pinned).toBe(false);
+    expect(layout.nodes[0].x).toBeGreaterThanOrEqual(0);
+    expect(layout.nodes[0].y).toBeGreaterThanOrEqual(0);
+  });
+
+  it('extracts edges from connectsTo, including connection types', () => {
+    const layout = computeDiagramLayout([
+      makeBlock({
+        id: 'a',
+        x: 0,
+        y: 0,
+        connectsTo: [{ target: 'b', type: 'flow' }, { target: 'c' }],
+      }),
+      makeBlock({ id: 'b', x: 100, y: 0 }),
+      makeBlock({ id: 'c', x: 200, y: 0 }),
+    ]);
+    expect(layout.edges).toHaveLength(2);
+    expect(layout.edges[0]).toMatchObject({ source: 'a', target: 'b', type: 'flow' });
+    expect(layout.edges[1]).toMatchObject({ source: 'a', target: 'c' });
+    expect(layout.edges[1].type).toBeUndefined();
+  });
+
+  it('drops edges with unknown targets and reports a warning', () => {
+    const layout = computeDiagramLayout([
+      makeBlock({
+        id: 'a',
+        x: 0,
+        y: 0,
+        connectsTo: [{ target: 'ghost' }, { target: 'b' }],
+      }),
+      makeBlock({ id: 'b', x: 100, y: 0 }),
+    ]);
+    expect(layout.edges).toHaveLength(1);
+    expect(layout.edges[0].target).toBe('b');
+    expect(layout.warnings.length).toBe(1);
+    expect(layout.warnings[0]).toContain('ghost');
+  });
+
+  it('dedupes edges with identical source/target/type', () => {
+    const layout = computeDiagramLayout([
+      makeBlock({
+        id: 'a',
+        x: 0,
+        y: 0,
+        connectsTo: [
+          { target: 'b', type: 'flow' },
+          { target: 'b', type: 'flow' },
+        ],
+      }),
+      makeBlock({ id: 'b', x: 100, y: 0 }),
+    ]);
+    expect(layout.edges).toHaveLength(1);
+  });
+
+  it('distinguishes edges with different types', () => {
+    const layout = computeDiagramLayout([
+      makeBlock({
+        id: 'a',
+        x: 0,
+        y: 0,
+        connectsTo: [
+          { target: 'b', type: 'flow' },
+          { target: 'b', type: 'requires' },
+        ],
+      }),
+      makeBlock({ id: 'b', x: 100, y: 0 }),
+    ]);
+    expect(layout.edges).toHaveLength(2);
+  });
+
+  it('returns an empty layout for no children', () => {
+    const layout = computeDiagramLayout([]);
+    expect(layout.nodes).toEqual([]);
+    expect(layout.edges).toEqual([]);
+    expect(layout.warnings).toEqual([]);
+  });
+
+  it('falls back to the block id for the node label when title is missing', () => {
+    const layout = computeDiagramLayout([makeBlock({ id: 'lonely', x: 0, y: 0 })]);
+    expect(layout.nodes[0].label).toBe('lonely');
+  });
+
+  it('uses block.title for the node label when present', () => {
+    const layout = computeDiagramLayout([makeBlock({ id: 'a', x: 0, y: 0, title: 'Alpha' })]);
+    expect(layout.nodes[0].label).toBe('Alpha');
+  });
+});