@bendyline/squisq 1.4.1 → 1.5.1

package/src/doc/templates/dataTable.ts

@@ -11,24 +11,35 @@
 
 import type { Layer } from '../../schemas/Doc.js';
 import type { DataTableInput, TemplateContext } from '../../schemas/BlockTemplates.js';
-import { scaledFontSize } from '../../schemas/BlockTemplates.js';
-import { getThemeFont, resolveColorScheme } from '../utils/themeUtils.js';
+import {
+  getThemeFont,
+  resolveColorScheme,
+  shouldUseShadow,
+  themedFontSize,
+  themedSurfaceGradient,
+} from '../utils/themeUtils.js';
+import { pickContrastingText, withAlpha } from '../../schemas/colorUtils.js';
 import { createBackgroundLayer } from './captionUtils.js';
 
 export function dataTable(input: DataTableInput, context: TemplateContext): Layer[] {
   const { title, headers, rows, align, colorScheme } = input;
-  const { theme } = context;
+  const { theme, viewport } = context;
 
   const colors = resolveColorScheme(context, colorScheme);
-  const titleFontSize = scaledFontSize(48, context, true);
-  const tableFontSize = scaledFontSize(28, context, false);
+  const titleFontSize = themedFontSize(48, context, true);
+  const tableFontSize = themedFontSize(28, context, false);
 
-  const layers: Layer[] = [
-    createBackgroundLayer(
-      'bg',
-      `linear-gradient(170deg, ${theme.colors.background} 0%, #0f1520 100%)`,
-    ),
-  ];
+  const layers: Layer[] = [createBackgroundLayer('bg', themedSurfaceGradient(context, 170))];
+
+  // Size the table band from its natural content height (header + rows at
+  // ~2.4× line height for cell padding) and center the title+table as one
+  // group — a full-height band left a ~200px orphan gap under the title.
+  // `rows` is required by the schema but may be missing on partially-
+  // authored blocks in live preview; treat it as empty rather than throwing.
+  const rowCount = (Array.isArray(rows) ? rows.length : 0) + 1;
+  const naturalTableHPct = Math.min(74, ((rowCount * tableFontSize * 2.4) / viewport.height) * 100);
+  const titleBandPct = title ? (titleFontSize * 2.2 * 100) / viewport.height : 0;
+  const groupTopPct = Math.max(8, (100 - titleBandPct - naturalTableHPct) / 2);
 
   // Optional title above the table
   if (title) {
@@ -43,15 +54,22 @@ export function dataTable(input: DataTableInput, context: TemplateContext): Laye
           fontWeight: 'bold',
           color: theme.colors.text,
           textAlign: 'center',
-          shadow: true,
+          shadow: shouldUseShadow(context),
         },
       },
-      position: { x: '50%', y: '10%', width: '80%', anchor: 'center' },
+      position: {
+        x: '50%',
+        y: `${groupTopPct + titleBandPct / 2}%`,
+        width: '80%',
+        anchor: 'center',
+      },
       animation: { type: 'fadeIn', duration: 0.8 },
     });
   }
 
-  // Table layer
+  // Table layer. Header text color is picked for contrast against the
+  // header fill — pairing two mid-tones from the same scheme made the
+  // header row read as a smudge in most themes.
   layers.push({
     type: 'table',
     id: 'table',
@@ -61,10 +79,10 @@ export function dataTable(input: DataTableInput, context: TemplateContext): Laye
       align,
       style: {
         headerBackground: colors.accent,
-        headerColor: colors.text,
-        cellBackground: 'rgba(255,255,255,0.05)',
+        headerColor: pickContrastingText(colors.accent),
+        cellBackground: withAlpha(theme.colors.text, 0.04),
         cellColor: theme.colors.text,
-        borderColor: 'rgba(255,255,255,0.12)',
+        borderColor: withAlpha(theme.colors.text, 0.15),
         fontSize: tableFontSize,
         fontFamily: getThemeFont(context, 'body'),
         headerFontFamily: getThemeFont(context, 'title'),
@@ -73,9 +91,9 @@ export function dataTable(input: DataTableInput, context: TemplateContext): Laye
     },
     position: {
       x: '10%',
-      y: title ? '18%' : '8%',
+      y: `${groupTopPct + titleBandPct}%`,
       width: '80%',
-      height: title ? '74%' : '84%',
+      height: `${naturalTableHPct}%`,
     },
     animation: { type: 'fadeIn', duration: 1, delay: title ? 0.4 : 0 },
   });

package/src/doc/templates/dateEvent.ts

@@ -12,37 +12,52 @@
 
 import type { Layer } from '../../schemas/Doc.js';
 import type { DateEventInput, TemplateContext } from '../../schemas/BlockTemplates.js';
-import { scaledFontSize } from '../../schemas/BlockTemplates.js';
-import { getThemeFont } from '../utils/themeUtils.js';
+import {
+  getThemeFont,
+  shouldUseShadow,
+  themedFontSize,
+  themedSurfaceGradient,
+  themedImageTreatment,
+} from '../utils/themeUtils.js';
+import { oklchDarken, relativeLuminance } from '../../schemas/colorUtils.js';
 import { createAccentLayers, getAccentLayout, adjustY, DEFAULT_LAYOUT } from './accentImage.js';
 
-const MOOD_COLORS = {
-  neutral: { bg: '#1a202c', date: '#63b3ed', text: '#ffffff' },
-  somber: { bg: '#1a1a2e', date: '#e53e3e', text: '#a0aec0' },
-  celebratory: { bg: '#1a365d', date: '#68d391', text: '#ffffff' },
+/**
+ * Mood accents tint the hero date, not the surface — the surface always
+ * comes from the theme. (Hard-coded dark mood panels used to turn light
+ * and warm themes into a cold navy slide.)
+ */
+const MOOD_ACCENTS = {
+  neutral: '#63b3ed',
+  somber: '#e53e3e',
+  celebratory: '#68d391',
 };
 
 export function dateEvent(input: DateEventInput, context: TemplateContext): Layer[] {
   const { date, description, footer, mood = 'neutral', accentImage } = input;
   const { theme } = context;
-  const colors = MOOD_COLORS[mood];
+  // Deepen the mood accent on light surfaces so the hero date keeps contrast.
+  const moodAccent = MOOD_ACCENTS[mood];
+  const dateColor =
+    relativeLuminance(theme.colors.background) > 0.5 ? oklchDarken(moodAccent, 0.25) : moodAccent;
 
   // Get layout adjustments if accent image is present
   const accentLayout = accentImage ? getAccentLayout(accentImage.position) : DEFAULT_LAYOUT;
 
   // Scale font sizes — date is the hero element
-  const dateFontSize = scaledFontSize(96, context, true);
-  const descFontSize = scaledFontSize(30, context, false);
-  const footerFontSize = scaledFontSize(26, context, false);
+  const dateFontSize = themedFontSize(96, context, true);
+  const descFontSize = themedFontSize(30, context, false);
+  const footerFontSize = themedFontSize(26, context, false);
 
   const layers: Layer[] = [
-    // Background — unique diagonal gradient to differentiate from other dark templates
+    // Background — theme surface gradient (diagonal to differentiate
+    // from other text templates)
     {
       type: 'shape',
       id: 'bg',
       content: {
         shape: 'rect',
-        fill: `linear-gradient(135deg, ${colors.bg} 0%, #0d1117 100%)`,
+        fill: themedSurfaceGradient(context, 135),
       },
       position: { x: 0, y: 0, width: '100%', height: '100%' },
     },
@@ -50,7 +65,13 @@ export function dateEvent(input: DateEventInput, context: TemplateContext): Laye
 
   // Add accent image layers (behind text, after background)
   if (accentImage) {
-    layers.push(...createAccentLayers(accentImage, input.id));
+    layers.push(
+      ...createAccentLayers(
+        accentImage,
+        input.id,
+        themedImageTreatment(context, input.imageTreatment),
+      ),
+    );
   }
 
   // Date — hero element, much larger
@@ -63,8 +84,8 @@ export function dateEvent(input: DateEventInput, context: TemplateContext): Laye
         fontSize: dateFontSize,
         fontFamily: getThemeFont(context, 'title'),
         fontWeight: 'bold',
-        color: colors.date,
-        shadow: !!accentImage,
+        color: dateColor,
+        shadow: shouldUseShadow(context),
       },
     },
     position: {
@@ -84,10 +105,10 @@ export function dateEvent(input: DateEventInput, context: TemplateContext): Laye
       style: {
         fontSize: descFontSize,
         fontFamily: getThemeFont(context, 'body'),
-        color: colors.text,
+        color: theme.colors.text,
         textAlign: 'center',
-        lineHeight: 1.8,
-        shadow: !!accentImage,
+        lineHeight: 1.6,
+        shadow: shouldUseShadow(context),
       },
     },
     position: {
@@ -110,12 +131,12 @@ export function dateEvent(input: DateEventInput, context: TemplateContext): Laye
           fontSize: footerFontSize,
           fontFamily: getThemeFont(context, 'body'),
           color: theme.colors.textMuted,
-          shadow: !!accentImage,
+          shadow: shouldUseShadow(context),
         },
       },
       position: {
         x: accentLayout.textCenterX,
-        y: adjustY('82%', accentLayout),
+        y: adjustY('72%', accentLayout),
         anchor: 'center',
       },
       animation: { type: 'fadeIn', duration: 1, delay: 3 },

package/src/doc/templates/definitionCard.ts

@@ -10,8 +10,15 @@
 
 import type { Layer } from '../../schemas/Doc.js';
 import type { DefinitionCardInput, TemplateContext } from '../../schemas/BlockTemplates.js';
-import { scaledFontSize } from '../../schemas/BlockTemplates.js';
-import { resolveColorScheme, getThemeFont } from '../utils/themeUtils.js';
+import {
+  resolveColorScheme,
+  getThemeFont,
+  shouldUseShadow,
+  themedEntrance,
+  themedFontSize,
+  themedSurfaceGradient,
+  themedImageTreatment,
+} from '../utils/themeUtils.js';
 import { createAccentLayers, getAccentLayout, adjustY, DEFAULT_LAYOUT } from './accentImage.js';
 import { createBackgroundLayer } from './captionUtils.js';
 
@@ -23,20 +30,21 @@ export function definitionCard(input: DefinitionCardInput, context: TemplateCont
   // Get layout adjustments if accent image is present
   const accentLayout = accentImage ? getAccentLayout(accentImage.position) : DEFAULT_LAYOUT;
 
-  const termFontSize = scaledFontSize(72, context, true);
-  const defFontSize = scaledFontSize(32, context, false);
-  const originFontSize = scaledFontSize(22, context, false);
+  const termFontSize = themedFontSize(72, context, true);
+  const defFontSize = themedFontSize(32, context, false);
+  const originFontSize = themedFontSize(22, context, false);
 
-  const layers: Layer[] = [
-    createBackgroundLayer(
-      'bg',
-      `linear-gradient(145deg, #1e2030 0%, ${theme.colors.background} 100%)`,
-    ),
-  ];
+  const layers: Layer[] = [createBackgroundLayer('bg', themedSurfaceGradient(context, 145))];
 
   // Add accent image layers
   if (accentImage) {
-    layers.push(...createAccentLayers(accentImage, input.id));
+    layers.push(
+      ...createAccentLayers(
+        accentImage,
+        input.id,
+        themedImageTreatment(context, input.imageTreatment),
+      ),
+    );
   }
 
   // Term — large, accent-colored
@@ -51,7 +59,7 @@ export function definitionCard(input: DefinitionCardInput, context: TemplateCont
         fontWeight: 'bold',
         color: colors.text,
         textAlign: 'center',
-        shadow: !!accentImage,
+        shadow: shouldUseShadow(context),
       },
     },
     position: {
@@ -59,7 +67,7 @@ export function definitionCard(input: DefinitionCardInput, context: TemplateCont
       y: adjustY('30%', accentLayout),
       anchor: 'center',
     },
-    animation: { type: 'fadeIn', duration: 1.5 },
+    animation: themedEntrance(context, 'text', { type: 'fadeIn', duration: 1.5 }),
   });
 
   // Horizontal separator line
@@ -92,7 +100,7 @@ export function definitionCard(input: DefinitionCardInput, context: TemplateCont
         textAlign: 'center',
         lineHeight: 1.6,
         maxLines: 4,
-        shadow: !!accentImage,
+        shadow: shouldUseShadow(context),
       },
     },
     position: {
@@ -101,7 +109,7 @@ export function definitionCard(input: DefinitionCardInput, context: TemplateCont
       width: accentLayout.textWidth,
       anchor: 'center',
     },
-    animation: { type: 'fadeIn', duration: 1, delay: 0.8 },
+    animation: themedEntrance(context, 'text', { type: 'fadeIn', duration: 1, delay: 0.8 }),
   });
 
   // Origin if provided
@@ -116,12 +124,12 @@ export function definitionCard(input: DefinitionCardInput, context: TemplateCont
           fontFamily: getThemeFont(context, 'body'),
           color: theme.colors.textMuted,
           textAlign: 'center',
-          shadow: !!accentImage,
+          shadow: shouldUseShadow(context),
         },
       },
       position: {
         x: accentLayout.textCenterX,
-        y: adjustY('78%', accentLayout),
+        y: adjustY('70%', accentLayout),
         anchor: 'center',
       },
       animation: { type: 'fadeIn', duration: 0.8, delay: 1.5 },

package/src/doc/templates/diagramBlock.ts

@@ -0,0 +1,204 @@
+/**
+ * Diagram block template.
+ *
+ * Renders the parent block's children as a node-and-edge diagram:
+ * - Each child becomes a rounded-rect node card with its title as label.
+ * - Each `child.connectsTo` entry becomes a path edge (cubic-bezier curve
+ *   with an arrowhead at the target end).
+ * - Children with `x`/`y` set are placed at those coordinates; the rest
+ *   are auto-laid out below in a square-ish grid (see `diagramLayout.ts`).
+ *
+ * Layout coordinates from `x=`/`y=` are author-defined units. The
+ * template computes a bounding box of all nodes and scales it to fit
+ * the block's viewport with padding, so users don't have to think about
+ * absolute pixel ranges.
+ */
+
+import type { Layer, ShapeLayer, TextLayer, PathLayer, MarkerStyle } from '../../schemas/Doc.js';
+import type { DiagramBlockInput, TemplateContext } from '../../schemas/BlockTemplates.js';
+import { resolveColorScheme, getThemeFont, themedFontSize } from '../utils/themeUtils.js';
+import { clipEndpoints, connectorPath, lineStyleDasharray } from '../utils/shapeGeometry.js';
+import { computeDiagramLayout, type DiagramNodePosition } from './diagramLayout.js';
+
+const NODE_WIDTH = 180;
+const NODE_HEIGHT = 64;
+const PADDING = 80;
+
+export function diagramBlock(input: DiagramBlockInput, context: TemplateContext): Layer[] {
+  const { theme, viewport, children = [] } = context;
+  const colors = resolveColorScheme(context, input.colorScheme ?? 'blue');
+
+  const layout = computeDiagramLayout(children);
+  if (layout.nodes.length === 0) {
+    // Empty diagram — render a single hint label so the block has visible content.
+    return [
+      {
+        type: 'text',
+        id: 'diagram-empty',
+        content: {
+          text: input.title ?? 'Empty diagram',
+          style: {
+            fontSize: themedFontSize(36, context, true),
+            fontFamily: getThemeFont(context, 'title'),
+            color: theme.colors.textMuted,
+            textAlign: 'center',
+          },
+        },
+        position: { x: '50%', y: '50%', anchor: 'center' },
+      },
+    ];
+  }
+
+  // Compute the bounding box of all nodes in author coordinates.
+  const minX = Math.min(...layout.nodes.map((n) => n.x));
+  const maxX = Math.max(...layout.nodes.map((n) => n.x + NODE_WIDTH));
+  const minY = Math.min(...layout.nodes.map((n) => n.y));
+  const maxY = Math.max(...layout.nodes.map((n) => n.y + NODE_HEIGHT));
+
+  // Available area in viewport pixels (after reserving space for the title, if any).
+  const titleHeight = input.title ? 120 : 0;
+  const availW = Math.max(1, viewport.width - PADDING * 2);
+  const availH = Math.max(1, viewport.height - PADDING * 2 - titleHeight);
+  const contentW = Math.max(1, maxX - minX);
+  const contentH = Math.max(1, maxY - minY);
+
+  // Uniform scale so the diagram fits both dimensions. Small diagrams are
+  // allowed to grow (everything here is vector) up to 1.8× so a three-node
+  // flow doesn't render as a tiny cluster in an empty canvas; label fonts
+  // and strokes scale with the nodes, clamped so text never balloons.
+  const scale = Math.min(availW / contentW, availH / contentH, 1.8);
+  const fontAdj = Math.min(Math.max(scale, 1), 1.5);
+  const strokeW = Math.round(2 * fontAdj);
+
+  // Compute viewport-pixel coordinates of each node's top-left corner.
+  // The title and the scaled diagram are centered together as one group —
+  // a top-pinned title over a center-floated diagram split the block into
+  // two stranded pieces.
+  const scaledW = contentW * scale;
+  const scaledH = contentH * scale;
+  const groupTop = Math.max(PADDING / 2, (viewport.height - titleHeight - scaledH) / 2);
+  const offsetX = PADDING + (availW - scaledW) / 2;
+  const offsetY = groupTop + titleHeight;
+  const transform = (n: DiagramNodePosition): { x: number; y: number; w: number; h: number } => ({
+    x: offsetX + (n.x - minX) * scale,
+    y: offsetY + (n.y - minY) * scale,
+    w: NODE_WIDTH * scale,
+    h: NODE_HEIGHT * scale,
+  });
+
+  const layers: Layer[] = [];
+
+  // Optional title above the diagram.
+  if (input.title) {
+    layers.push({
+      type: 'text',
+      id: 'diagram-title',
+      content: {
+        text: input.title,
+        style: {
+          fontSize: themedFontSize(40, context, true),
+          fontFamily: getThemeFont(context, 'title'),
+          fontWeight: 'bold',
+          color: theme.colors.text,
+          textAlign: 'center',
+        },
+      },
+      position: { x: '50%', y: groupTop + titleHeight / 2 - 16, anchor: 'center' },
+    });
+  }
+
+  // Position lookup by id for edge routing.
+  const positions = new Map<string, { cx: number; cy: number; rx: number; ry: number }>();
+  for (const node of layout.nodes) {
+    const t = transform(node);
+    positions.set(node.id, { cx: t.x + t.w / 2, cy: t.y + t.h / 2, rx: t.w / 2, ry: t.h / 2 });
+  }
+
+  // Edge styling (applies to all edges; per-edge styling lives on the nodes).
+  const startMarker: MarkerStyle = input.startStyle ?? 'none';
+  const endMarker: MarkerStyle = input.endStyle ?? 'arrow';
+  const edgeDash = lineStyleDasharray(input.lineStyle);
+
+  // Edges first so they sit behind nodes.
+  for (const edge of layout.edges) {
+    const a = positions.get(edge.source);
+    const b = positions.get(edge.target);
+    if (!a || !b) continue;
+    const { start, end } = clipEndpoints(a, b);
+    const pathLayer: PathLayer = {
+      type: 'path',
+      id: `edge-${edge.id}`,
+      content: {
+        d: connectorPath(input.edgeStyle ?? 'curved', start, end),
+        stroke: colors.text ?? theme.colors.primary,
+        strokeWidth: strokeW,
+        fill: 'none',
+        ...(edgeDash ? { dasharray: edgeDash } : {}),
+        ...(startMarker !== 'none' ? { startMarker } : {}),
+        ...(endMarker !== 'none' ? { endMarker } : {}),
+      },
+      position: { x: 0, y: 0, width: '100%', height: '100%' },
+    };
+    layers.push(pathLayer);
+
+    if (edge.type) {
+      // Connection-type label, floated just above the edge midpoint so the
+      // line never strikes through the text.
+      const mx = (a.cx + b.cx) / 2;
+      const my = (a.cy + b.cy) / 2;
+      const labelFontSize = themedFontSize(Math.round(18 * fontAdj), context, false);
+      const labelLayer: TextLayer = {
+        type: 'text',
+        id: `edge-label-${edge.id}`,
+        content: {
+          text: edge.type,
+          style: {
+            fontSize: labelFontSize,
+            fontFamily: getThemeFont(context, 'body'),
+            color: theme.colors.textMuted,
+            textAlign: 'center',
+          },
+        },
+        position: { x: mx, y: my - labelFontSize * 0.9, anchor: 'center' },
+      };
+      layers.push(labelLayer);
+    }
+  }
+
+  // Nodes (card + label) on top of edges.
+  for (const node of layout.nodes) {
+    const t = transform(node);
+    const card: ShapeLayer = {
+      type: 'shape',
+      id: `node-card-${node.id}`,
+      content: {
+        shape: 'rect',
+        fill: colors.bg ?? theme.colors.backgroundLight,
+        stroke: colors.text ?? theme.colors.primary,
+        strokeWidth: strokeW,
+        borderRadius: input.nodeShape === 'pill' ? t.h / 2 : 10,
+      },
+      position: { x: t.x, y: t.y, width: t.w, height: t.h },
+    };
+    layers.push(card);
+
+    const label: TextLayer = {
+      type: 'text',
+      id: `node-label-${node.id}`,
+      content: {
+        text: node.label,
+        style: {
+          fontSize: themedFontSize(Math.round(22 * fontAdj), context, false),
+          fontFamily: getThemeFont(context, 'body'),
+          fontWeight: 'bold',
+          color: colors.text ?? theme.colors.text,
+          textAlign: 'center',
+        },
+      },
+      position: { x: t.x + t.w / 2, y: t.y + t.h / 2, anchor: 'center', width: t.w },
+    };
+    layers.push(label);
+  }
+
+  return layers;
+}

package/src/doc/templates/diagramLayout.ts

@@ -0,0 +1,159 @@
+/**
+ * Diagram layout — shared between the read-only SVG render path
+ * (`diagramBlock` template) and the interactive editor (React Flow in
+ * `@bendyline/squisq-editor-react`). Same children + same options always
+ * produce the same node positions and edge list, so previews and the
+ * editor stay visually consistent.
+ *
+ * Layout rules:
+ * 1. Children with both `x` and `y` set keep their authored coordinates.
+ * 2. Children missing either coordinate are auto-placed in a square-ish
+ *    grid in declaration order, offset below the bounding box of the
+ *    explicitly-positioned children.
+ * 3. Edges come from each child's `connectsTo`. Targets that don't match
+ *    any sibling id are dropped (and counted in `warnings`).
+ */
+
+import type { Block, BlockConnection } from '../../schemas/Doc.js';
+
+export interface DiagramNodePosition {
+  /** Block id (matches `Block.id`). */
+  id: string;
+  /** Display label (block title or fallback to id). */
+  label: string;
+  /** Pixel x coordinate (canvas-relative). */
+  x: number;
+  /** Pixel y coordinate (canvas-relative). */
+  y: number;
+  /** True when the position came from `x=`/`y=` attributes; false when auto-laid out. */
+  pinned: boolean;
+  /** Optional `.class` tokens carried over from the heading. */
+  classes?: string[];
+}
+
+export interface DiagramEdge {
+  /** Synthetic stable edge id. */
+  id: string;
+  /** Source node id. */
+  source: string;
+  /** Target node id. */
+  target: string;
+  /** Connection type from `connectsTo=target:type` (used as edge label). */
+  type?: string;
+}
+
+export interface DiagramLayout {
+  nodes: DiagramNodePosition[];
+  edges: DiagramEdge[];
+  warnings: string[];
+}
+
+export interface DiagramLayoutOptions {
+  /** Horizontal grid pitch between auto-laid-out nodes. Default: 260 (node width 180 + 80 air). */
+  gapX?: number;
+  /** Vertical grid pitch between auto-laid-out nodes. Default: 140. */
+  gapY?: number;
+  /** Padding around the explicit-positions bounding box before the grid starts. Default: 80. */
+  gridPad?: number;
+  /** Origin x for the grid when no explicit nodes anchor it. Default: 80. */
+  gridOriginX?: number;
+  /** Origin y for the grid when no explicit nodes anchor it. Default: 80. */
+  gridOriginY?: number;
+}
+
+const DEFAULT_OPTS: Required<DiagramLayoutOptions> = {
+  gapX: 260,
+  gapY: 140,
+  gridPad: 80,
+  gridOriginX: 80,
+  gridOriginY: 80,
+};
+
+/**
+ * Compute node positions and edges for a diagram from a parent block's
+ * children. Pure function — same inputs always produce the same output.
+ */
+export function computeDiagramLayout(
+  children: readonly Block[],
+  options: DiagramLayoutOptions = {},
+): DiagramLayout {
+  const opts = { ...DEFAULT_OPTS, ...options };
+  const warnings: string[] = [];
+
+  // First pass: extract explicit positions, record which children still need a grid slot.
+  type Entry = { child: Block; pinned: boolean; x: number; y: number };
+  const entries: Entry[] = [];
+  const unpositionedIdx: number[] = [];
+
+  for (let i = 0; i < children.length; i++) {
+    const c = children[i];
+    const hasX = typeof c.x === 'number';
+    const hasY = typeof c.y === 'number';
+    if (hasX && hasY) {
+      entries.push({ child: c, pinned: true, x: c.x as number, y: c.y as number });
+    } else {
+      entries.push({ child: c, pinned: false, x: 0, y: 0 });
+      unpositionedIdx.push(i);
+    }
+  }
+
+  // Second pass: lay out unpositioned children in a square-ish grid.
+  if (unpositionedIdx.length > 0) {
+    const cols = Math.max(1, Math.ceil(Math.sqrt(unpositionedIdx.length)));
+    // Find the bottom-right of the pinned bounding box so the grid sits below it.
+    let baseX = opts.gridOriginX;
+    let baseY = opts.gridOriginY;
+    const pinned = entries.filter((e) => e.pinned);
+    if (pinned.length > 0) {
+      const minX = Math.min(...pinned.map((e) => e.x));
+      const maxY = Math.max(...pinned.map((e) => e.y));
+      baseX = minX;
+      baseY = maxY + opts.gridPad + opts.gapY;
+    }
+    unpositionedIdx.forEach((entryIdx, k) => {
+      const col = k % cols;
+      const row = Math.floor(k / cols);
+      entries[entryIdx].x = baseX + col * opts.gapX;
+      entries[entryIdx].y = baseY + row * opts.gapY;
+    });
+  }
+
+  // Third pass: emit nodes + the id-set used to validate edge targets.
+  const nodes: DiagramNodePosition[] = entries.map((e) => ({
+    id: e.child.id,
+    label: e.child.title ?? e.child.id,
+    x: e.x,
+    y: e.y,
+    pinned: e.pinned,
+    ...(e.child.classes && e.child.classes.length > 0 ? { classes: e.child.classes } : {}),
+  }));
+  const nodeIds = new Set(nodes.map((n) => n.id));
+
+  // Fourth pass: emit edges from each child's connectsTo, dropping ghosts.
+  const edges: DiagramEdge[] = [];
+  const seenEdgeIds = new Set<string>();
+  for (const child of children) {
+    if (!child.connectsTo) continue;
+    for (const conn of child.connectsTo) {
+      if (!nodeIds.has(conn.target)) {
+        warnings.push(`Edge from "${child.id}" to "${conn.target}" dropped: no such sibling node`);
+        continue;
+      }
+      const edgeId = makeEdgeId(child.id, conn);
+      if (seenEdgeIds.has(edgeId)) continue;
+      seenEdgeIds.add(edgeId);
+      edges.push({
+        id: edgeId,
+        source: child.id,
+        target: conn.target,
+        ...(conn.type ? { type: conn.type } : {}),
+      });
+    }
+  }
+
+  return { nodes, edges, warnings };
+}
+
+function makeEdgeId(source: string, conn: BlockConnection): string {
+  return conn.type ? `${source}->${conn.target}:${conn.type}` : `${source}->${conn.target}`;
+}