@bendyline/squisq 1.4.0 → 1.5.0

package/src/doc/templates/index.ts

@@ -20,12 +20,19 @@ import type {
   PersistentLayerConfig,
 } from '../../schemas/BlockTemplates.js';
 import type { Theme } from '../../schemas/Theme.js';
+import type { CustomTemplateDefinition } from '../../schemas/CustomTemplates.js';
 import { isTemplateBlock, createTemplateContext } from '../../schemas/BlockTemplates.js';
 import { DEFAULT_THEME as defaultTheme } from '../../schemas/themeLibrary.js';
-import { expandPersistentLayers } from './persistentLayers.js';
+import { expandPersistentLayers, wrapWithPersistentLayers } from './persistentLayers.js';
+import { applyRenderStyleToLayers } from '../utils/applyRenderStyle.js';
+import { resolveBlockTransition } from '../../schemas/Transitions.js';
+import { makeCustomTemplateFn } from './customTemplate.js';
 import type { ViewportConfig } from '../../schemas/Viewport.js';
 import { VIEWPORT_PRESETS } from '../../schemas/Viewport.js';
 
+export { TEMPLATE_METADATA } from './metadata.js';
+export type { TemplateMetadata } from './metadata.js';
+
 // Import all template functions
 import { titleBlock } from './titleBlock.js';
 import { sectionHeader } from './sectionHeader.js';
@@ -46,6 +53,9 @@ import { pullQuote } from './pullQuote.js';
 import { videoWithCaption } from './videoWithCaption.js';
 import { videoPullQuote } from './videoPullQuote.js';
 import { dataTable } from './dataTable.js';
+import { diagramBlock } from './diagramBlock.js';
+import { drawingBlock } from './drawingBlock.js';
+import { layoutBlock } from './layoutBlock.js';
 
 /**
  * Registry mapping template ids (the strings that appear in
@@ -82,6 +92,9 @@ export const templateRegistry: TemplateRegistry = {
   videoWithCaption,
   videoPullQuote,
   dataTable,
+  diagram: diagramBlock,
+  layout: layoutBlock,
+  drawing: drawingBlock,
 };
 
 /**
@@ -95,6 +108,8 @@ export const TEMPLATE_ALIASES: Readonly<Record<string, string>> = {
   quoteBlock: 'quote',
   mapBlock: 'map',
   listBlock: 'list',
+  diagramBlock: 'diagram',
+  diagramNode: 'diagram',
 };
 
 /**
@@ -105,14 +120,67 @@ export function resolveTemplateName(name: string): string {
   return TEMPLATE_ALIASES[name] ?? name;
 }
 
+/**
+ * Container templates render their parent block by consuming the block's
+ * child headings (via `context.children`) — `diagram` draws them as nodes,
+ * `drawing` as shapes, `layout` as absolutely-positioned layers. Those
+ * children are therefore NOT independently renderable slides/sections;
+ * render paths use {@link isContainerTemplate} to skip descending into
+ * them (see `flattenRenderableBlocks`).
+ */
+export const CONTAINER_TEMPLATES: ReadonlySet<string> = new Set(['diagram', 'drawing', 'layout']);
+
+/** True when `name` (or its alias) is a children-consuming container template. */
+export function isContainerTemplate(name: string | undefined): boolean {
+  if (!name) return false;
+  return CONTAINER_TEMPLATES.has(resolveTemplateName(name));
+}
+
+/**
+ * Merge user-defined custom templates onto the built-in registry.
+ * Built-in names take precedence on collision — a user can't shadow
+ * `title` or `diagram` from a custom definition. Returns a frozen view
+ * so callers don't accidentally mutate the global registry.
+ */
+export type RuntimeTemplateRegistry = Record<
+  string,
+  (input: TemplateBlock, ctx: TemplateContext) => Layer[]
+>;
+
+export function buildRegistry(
+  custom?: readonly CustomTemplateDefinition[],
+): RuntimeTemplateRegistry {
+  // The exported `templateRegistry` is a discriminated-union mapped type;
+  // we cast through `unknown` because each entry's `input` type is the
+  // template-specific variant, not the broad `TemplateBlock` union.
+  // The runtime contract — "given any TemplateBlock that resolves to a
+  // registered name, the function returns Layer[]" — holds because the
+  // expansion path looks up by `template` string before calling.
+  const merged: RuntimeTemplateRegistry = {
+    ...(templateRegistry as unknown as RuntimeTemplateRegistry),
+  };
+  if (custom) {
+    for (const def of custom) {
+      if (merged[def.name]) continue; // built-in wins
+      merged[def.name] = makeCustomTemplateFn(def) as unknown as RuntimeTemplateRegistry[string];
+    }
+  }
+  return merged;
+}
+
 /**
  * Expand a template block into a full Block with layers.
+ *
+ * `registry` lets callers swap in a registry that includes user-defined
+ * custom templates. Defaults to the built-in registry when omitted.
  */
-export function expandTemplateBlock(templateBlock: TemplateBlock, context: TemplateContext): Block {
+export function expandTemplateBlock(
+  templateBlock: TemplateBlock,
+  context: TemplateContext,
+  registry: RuntimeTemplateRegistry = templateRegistry as unknown as RuntimeTemplateRegistry,
+): Block {
   const resolved = resolveTemplateName(templateBlock.template);
-  const templateFn = (templateRegistry as Record<string, unknown>)[resolved] as
-    | ((input: TemplateBlock, ctx: TemplateContext) => Layer[])
-    | undefined;
+  const templateFn = registry[resolved];
 
   if (!templateFn) {
     console.warn(`Unknown template: ${templateBlock.template}`);
@@ -127,10 +195,19 @@ export function expandTemplateBlock(templateBlock: TemplateBlock, context: Templ
     };
   }
 
+  // Effective template input: the block's own fields, then structured
+  // body data (```json data fences / derived auto-template inputs), then
+  // `{[…]}` string overrides — the same merge order getLayers uses.
+  const { templateData, templateOverrides } = templateBlock as Block;
+  const input =
+    templateData || templateOverrides
+      ? ({ ...templateBlock, ...templateData, ...templateOverrides } as TemplateBlock)
+      : templateBlock;
+
   // Generate layers from template with error handling
   let layers: Layer[];
   try {
-    layers = templateFn(templateBlock, context);
+    layers = templateFn(input, context);
     if (!Array.isArray(layers)) {
       console.error(
         `Template ${templateBlock.template} did not return an array, got:`,
@@ -180,6 +257,12 @@ export interface ExpandDocBlocksOptions {
    * ensuring proper synchronization with audio playback.
    */
   audioSegments?: AudioSegmentTiming[];
+  /**
+   * User-defined custom templates to merge onto the built-in registry
+   * before expanding blocks. Typically passed straight from
+   * `Doc.customTemplates`. Built-in names take precedence on collision.
+   */
+  customTemplates?: readonly CustomTemplateDefinition[];
 }
 
 /**
@@ -193,38 +276,88 @@ export interface ExpandDocBlocksOptions {
  * @param blocks - Array of template or raw blocks
  * @param options - Expansion options including theme, viewport, and persistent layers
  */
+/**
+ * Finalize an expanded block in place: apply the theme's motion post-pass
+ * to template-generated layers, wrap with persistent bottom/top layers,
+ * and fill the theme's default transition (never on block 0, never over an
+ * authored transition). Shared by every expansion path in this module.
+ */
+function finalizeExpandedBlock(
+  expandedBlock: Block,
+  sourceBlock: DocBlock,
+  blockIndex: number,
+  theme: Theme,
+  bottomLayers: Layer[],
+  topLayers: Layer[],
+): void {
+  // Theme motion defaults apply only to template-generated layers —
+  // raw authored block.layers are never restyled.
+  if (isTemplateBlock(sourceBlock) && expandedBlock.layers && expandedBlock.layers.length > 0) {
+    expandedBlock.layers = applyRenderStyleToLayers(expandedBlock.layers, expandedBlock, theme);
+  }
+
+  if (bottomLayers.length > 0 || topLayers.length > 0) {
+    expandedBlock.layers = wrapWithPersistentLayers(
+      expandedBlock.layers ?? [],
+      sourceBlock as TemplateBlock,
+      bottomLayers,
+      topLayers,
+    );
+  }
+
+  const transition = resolveBlockTransition(expandedBlock, theme, blockIndex);
+  if (transition !== expandedBlock.transition) {
+    expandedBlock.transition = transition;
+  }
+}
+
 export function expandDocBlocks(blocks: DocBlock[], options: ExpandDocBlocksOptions = {}): Block[] {
   const opts: ExpandDocBlocksOptions = options;
 
   const theme = opts.theme ?? defaultTheme;
   const viewport = opts.viewport ?? VIEWPORT_PRESETS.landscape;
-  const { persistentLayers, audioSegments } = opts;
+  const { persistentLayers, audioSegments, customTemplates } = opts;
   const totalBlocks = blocks.length;
-
-  // Pre-expand persistent layers once
-  const bottomLayers = expandPersistentLayers(persistentLayers?.bottomLayers);
-  const topLayers = expandPersistentLayers(persistentLayers?.topLayers);
+  // Merge user-defined templates onto the built-in registry once per
+  // call; passed into every `expandTemplateBlock` invocation below.
+  const registry: RuntimeTemplateRegistry =
+    customTemplates && customTemplates.length > 0
+      ? buildRegistry(customTemplates)
+      : (templateRegistry as unknown as RuntimeTemplateRegistry);
+
+  // Pre-expand persistent layers once. Callers that pass no config inherit
+  // the theme's atmosphere (docs with their own layers pass them in and win
+  // wholesale — see resolvePersistentLayers).
+  const effectivePersistentLayers = persistentLayers ?? theme.persistentLayers;
+  const bottomLayers = expandPersistentLayers(effectivePersistentLayers?.bottomLayers, theme);
+  const topLayers = expandPersistentLayers(effectivePersistentLayers?.topLayers, theme);
 
   // If no audio segments provided, use simple cumulative timing
   if (!audioSegments || audioSegments.length === 0) {
     let currentTime = 0;
     return blocks.map((block, index) => {
       const context = createTemplateContext(theme, index, totalBlocks, viewport);
+      const maybeChildren = (block as Block).children;
+      if (maybeChildren && maybeChildren.length > 0) {
+        context.children = maybeChildren;
+      }
+      // Expose the source block so custom templates' token resolver can
+      // see the block's title / contents / children. Only set for
+      // custom-templated blocks — built-ins ignore context.block but
+      // exposing it changes object identity which we want to avoid for
+      // the perf-sensitive built-in path.
+      if (
+        isTemplateBlock(block) &&
+        customTemplates &&
+        customTemplates.some((c) => c.name === block.template)
+      ) {
+        context.block = block as Block;
+      }
       const expandedBlock = isTemplateBlock(block)
-        ? expandTemplateBlock(block, context)
+        ? expandTemplateBlock(block, context, registry)
         : (block as Block);
 
-      // Inject persistent layers
-      const templateBlock = block as TemplateBlock;
-      const useBottom = templateBlock.useBottomLayer !== false;
-      const useTop = templateBlock.useTopLayer !== false;
-      if (bottomLayers.length > 0 || topLayers.length > 0) {
-        expandedBlock.layers = [
-          ...(useBottom ? bottomLayers : []),
-          ...(expandedBlock.layers ?? []),
-          ...(useTop ? topLayers : []),
-        ];
-      }
+      finalizeExpandedBlock(expandedBlock, block, index, theme, bottomLayers, topLayers);
 
       expandedBlock.startTime = currentTime;
       currentTime += expandedBlock.duration;
@@ -252,20 +385,22 @@ export function expandDocBlocks(blocks: DocBlock[], options: ExpandDocBlocksOpti
       let offsetTime = 0;
       for (const { block, originalIndex } of segmentBlocks) {
         const context = createTemplateContext(theme, originalIndex, totalBlocks, viewport);
+        const maybeChildren = (block as Block).children;
+        if (maybeChildren && maybeChildren.length > 0) {
+          context.children = maybeChildren;
+        }
+        if (
+          isTemplateBlock(block) &&
+          customTemplates &&
+          customTemplates.some((c) => c.name === block.template)
+        ) {
+          context.block = block as Block;
+        }
         const expandedBlock = isTemplateBlock(block)
-          ? expandTemplateBlock(block, context)
+          ? expandTemplateBlock(block, context, registry)
           : (block as Block);
 
-        const templateBlock = block as TemplateBlock;
-        const useBottom = templateBlock.useBottomLayer !== false;
-        const useTop = templateBlock.useTopLayer !== false;
-        if (bottomLayers.length > 0 || topLayers.length > 0) {
-          expandedBlock.layers = [
-            ...(useBottom ? bottomLayers : []),
-            ...(expandedBlock.layers ?? []),
-            ...(useTop ? topLayers : []),
-          ];
-        }
+        finalizeExpandedBlock(expandedBlock, block, originalIndex, theme, bottomLayers, topLayers);
 
         expandedBlock.startTime = offsetTime;
         offsetTime += expandedBlock.duration;
@@ -318,21 +453,24 @@ export function expandDocBlocks(blocks: DocBlock[], options: ExpandDocBlocksOpti
 
     for (const { block, originalIndex } of segmentBlocks) {
       const context = createTemplateContext(theme, originalIndex, totalBlocks, viewport);
+      const maybeChildren = (block as Block).children;
+      if (maybeChildren && maybeChildren.length > 0) {
+        context.children = maybeChildren;
+      }
+      if (
+        isTemplateBlock(block) &&
+        customTemplates &&
+        customTemplates.some((c) => c.name === block.template)
+      ) {
+        context.block = block as Block;
+      }
       const expandedBlock = isTemplateBlock(block)
-        ? expandTemplateBlock(block, context)
+        ? expandTemplateBlock(block, context, registry)
         : (block as Block);
 
-      const templateBlock = block as TemplateBlock;
-      const useBottom = templateBlock.useBottomLayer !== false;
-      const useTop = templateBlock.useTopLayer !== false;
-      if (bottomLayers.length > 0 || topLayers.length > 0) {
-        expandedBlock.layers = [
-          ...(useBottom ? bottomLayers : []),
-          ...(expandedBlock.layers ?? []),
-          ...(useTop ? topLayers : []),
-        ];
-      }
+      finalizeExpandedBlock(expandedBlock, block, originalIndex, theme, bottomLayers, topLayers);
 
+      const templateBlock = block as TemplateBlock;
       expandedInfos.push({
         block: expandedBlock,
         originalIndex,
@@ -578,7 +716,13 @@ export type {
 } from '../../schemas/Viewport.js';
 export { getLayoutHints, getTwoColumnPositions } from '../../schemas/LayoutStrategy.js';
 export type { LayoutHints } from '../../schemas/LayoutStrategy.js';
-export { expandPersistentLayers, getDocStyleConfig } from './persistentLayers.js';
+export {
+  expandPersistentLayers,
+  getDocStyleConfig,
+  getPersistentLayersFromTheme,
+  resolvePersistentLayers,
+  wrapWithPersistentLayers,
+} from './persistentLayers.js';
 
 // Re-export individual templates for direct access
 export { titleBlock } from './titleBlock.js';
@@ -602,6 +746,31 @@ export { pullQuote } from './pullQuote.js';
 export { videoWithCaption } from './videoWithCaption.js';
 export { videoPullQuote } from './videoPullQuote.js';
 export { dataTable } from './dataTable.js';
+export { diagramBlock } from './diagramBlock.js';
+export { computeDiagramLayout } from './diagramLayout.js';
+export type {
+  DiagramLayout,
+  DiagramNodePosition,
+  DiagramEdge,
+  DiagramLayoutOptions,
+} from './diagramLayout.js';
+export { drawingBlock } from './drawingBlock.js';
+export {
+  computeDrawingLayout,
+  normalizeShapeKind,
+  isShapeName,
+  SHAPE_NAMES,
+} from './drawingLayout.js';
+export type {
+  DrawingLayout,
+  DrawingShape,
+  DrawingShapeKind,
+  DrawingConnector,
+  DrawingLayoutOptions,
+} from './drawingLayout.js';
+export { layoutBlock } from './layoutBlock.js';
+export { computeLayoutLayers } from './layoutLayout.js';
+export type { LayoutLayersResult, LayoutLayerDefaults } from './layoutLayout.js';
 
 // Re-export accent image utilities
 export { getAccentLayout, createAccentLayers, adjustY, DEFAULT_LAYOUT } from './accentImage.js';

package/src/doc/templates/layoutBlock.ts

@@ -0,0 +1,43 @@
+/**
+ * Layout block template.
+ *
+ * Renders the parent block's children as free-form, **absolutely
+ * positioned** layers on a canvas (text boxes, shapes, images). Unlike
+ * `drawingBlock`, coordinates are used as-is — there is no fit-to-viewport
+ * scaling — because a layout is a fixed-canvas composition.
+ *
+ * Each child is one layer: `### {#id} {[<type> x=.. y=.. …]}`. A text box's
+ * content lives in its child body as markdown (see `computeLayoutLayers`).
+ * Children render in document order (first child = back-most layer).
+ */
+
+import type { Layer, TextLayer } from '../../schemas/Doc.js';
+import type { TemplateBlock, TemplateContext } from '../../schemas/BlockTemplates.js';
+import { scaledFontSize } from '../../schemas/BlockTemplates.js';
+import { getThemeFont } from '../utils/themeUtils.js';
+import { computeLayoutLayers } from './layoutLayout.js';
+
+export function layoutBlock(input: TemplateBlock, context: TemplateContext): Layer[] {
+  const { theme, viewport, children = [] } = context;
+  // Theme ink for un-styled text and strokes — the fixed dark-slate
+  // default disappeared on dark themes.
+  const { layers } = computeLayoutLayers(children, viewport, { ink: theme.colors.text });
+  return layers.length > 0 ? layers : [emptyHint(input, context)];
+}
+
+function emptyHint(input: TemplateBlock, context: TemplateContext): TextLayer {
+  return {
+    type: 'text',
+    id: 'layout-empty',
+    content: {
+      text: (input as { title?: string }).title ?? 'Empty layout',
+      style: {
+        fontSize: scaledFontSize(36, context, true),
+        fontFamily: getThemeFont(context, 'title'),
+        color: context.theme.colors.textMuted,
+        textAlign: 'center',
+      },
+    },
+    position: { x: '50%', y: '50%', anchor: 'center' },
+  };
+}

package/src/doc/templates/layoutLayout.ts

@@ -0,0 +1,243 @@
+/**
+ * Layout layout — pure derivation of positioned layers from a `layout`
+ * block's child sub-blocks. The layout counterpart to `drawingLayout.ts`,
+ * with two deliberate differences:
+ *
+ *  - **Absolute** positioning. Each child's `x`/`y`/`width`/`height` are
+ *    used as-is in viewport units (no auto-grid, no fit-to-viewport
+ *    scaling). A layout is a free-form canvas; authors place things where
+ *    they want them.
+ *  - **Text content lives in the child body.** A `{[text …]}` child's
+ *    paragraphs/lists/marks under its heading become the text — readable
+ *    markdown rather than an encoded blob. (`content.html` is filled by the
+ *    editor for rich on-canvas rendering; SSR uses the plain `content.text`.)
+ *
+ * Each child heading is one layer: `### {#id} {[<type> x=.. y=.. …]}`.
+ * Children are emitted in document order, so the first child is the
+ * back-most layer (painters' order).
+ */
+
+import type { Layer, ShapeLayer, TextLayer, PathLayer, ImageLayer } from '../../schemas/Doc.js';
+import { extractPlainText } from '../../markdown/utils.js';
+import { normalizeShapeKind } from './drawingLayout.js';
+import { shapePath } from '../utils/shapeGeometry.js';
+
+export interface LayoutLayersResult {
+  layers: Layer[];
+  warnings: string[];
+}
+
+export interface LayoutLayerDefaults {
+  /**
+   * Default ink — text color and path/line stroke — used when the author
+   * omits `color=`/`stroke=`. `layoutBlock` passes the theme text color so
+   * un-styled text stays legible on dark themes; the editor's scene canvas
+   * omits it and gets the dark-slate default that suits its fixed light
+   * surface.
+   */
+  ink?: string;
+}
+
+/** Fallback ink for callers that don't supply defaults (editor scene canvas). */
+const DEFAULT_INK = '#1e293b';
+
+/** Minimal Block shape this derivation reads (subset of `Block`). */
+interface LayoutChildBlock {
+  id: string;
+  template?: string;
+  templateOverrides?: Record<string, string>;
+  title?: string;
+  contents?: import('../../markdown/types.js').MarkdownNode[];
+}
+
+const DEFAULT_TEXT = { w: 300, h: 80 };
+const DEFAULT_SHAPE = { w: 160, h: 90 };
+const DEFAULT_IMAGE = { w: 320, h: 240 };
+
+/**
+ * Map a layout block's children → positioned layers. Pure: same children
+ * always produce the same layers.
+ */
+export function computeLayoutLayers(
+  children: readonly LayoutChildBlock[],
+  _viewport: { width: number; height: number },
+  defaults: LayoutLayerDefaults = {},
+): LayoutLayersResult {
+  const ink = defaults.ink ?? DEFAULT_INK;
+  const layers: Layer[] = [];
+  const warnings: string[] = [];
+
+  for (const child of children) {
+    const params = child.templateOverrides ?? {};
+    const annotation = (child.template ?? '').toLowerCase();
+    const x = numParam(params, 'x') ?? 0;
+    const y = numParam(params, 'y') ?? 0;
+
+    if (annotation === 'image' || annotation === 'img') {
+      const src = strParam(params, 'src');
+      if (!src) {
+        warnings.push(`Layout image "${child.id}" has no src= and was skipped`);
+        continue;
+      }
+      const layer: ImageLayer = {
+        id: child.id,
+        type: 'image',
+        position: {
+          x,
+          y,
+          width: numParam(params, 'width') ?? DEFAULT_IMAGE.w,
+          height: numParam(params, 'height') ?? DEFAULT_IMAGE.h,
+        },
+        content: {
+          src,
+          alt: strParam(params, 'alt') ?? '',
+          ...(strParam(params, 'fit')
+            ? { fit: strParam(params, 'fit') as 'cover' | 'contain' | 'fill' }
+            : {}),
+        },
+      };
+      layers.push(layer);
+      continue;
+    }
+
+    const kind = normalizeShapeKind(child.template);
+    if (!kind) {
+      warnings.push(
+        `Layout child "${child.id}" is not a layer (annotation "${child.template ?? '—'}") and was skipped`,
+      );
+      continue;
+    }
+
+    if (kind === 'text') {
+      const text = bodyText(child) || child.title || '';
+      const layer: TextLayer = {
+        id: child.id,
+        type: 'text',
+        position: {
+          x,
+          y,
+          width: numParam(params, 'width') ?? DEFAULT_TEXT.w,
+          height: numParam(params, 'height') ?? DEFAULT_TEXT.h,
+        },
+        content: { text, style: textStyleFromParams(params, ink) },
+      };
+      layers.push(layer);
+      continue;
+    }
+
+    const width = numParam(params, 'width') ?? numParam(params, 'w') ?? DEFAULT_SHAPE.w;
+    const height = numParam(params, 'height') ?? numParam(params, 'h') ?? DEFAULT_SHAPE.h;
+
+    if (kind === 'rect' || kind === 'circle') {
+      const shape: ShapeLayer = {
+        id: child.id,
+        type: 'shape',
+        position: { x, y, width, height },
+        content: {
+          shape: kind,
+          ...(strParam(params, 'fill') ? { fill: strParam(params, 'fill') } : {}),
+          ...(strParam(params, 'stroke') ? { stroke: strParam(params, 'stroke') } : {}),
+          ...(numParam(params, 'strokeWidth') != null
+            ? { strokeWidth: numParam(params, 'strokeWidth') }
+            : {}),
+          ...(strParam(params, 'borderStyle')
+            ? { borderStyle: strParam(params, 'borderStyle') as 'solid' | 'dashed' | 'dotted' }
+            : {}),
+          ...(kind === 'rect' && numParam(params, 'borderRadius') != null
+            ? { borderRadius: numParam(params, 'borderRadius') }
+            : {}),
+        },
+      };
+      layers.push(shape);
+      continue;
+    }
+
+    // line / arrow / path / named polygon → PathLayer (absolute geometry).
+    const diagonal = `M ${round(x)} ${round(y)} L ${round(x + width)} ${round(y + height)}`;
+    let d = diagonal;
+    let pathFill = 'none';
+    let endMarker: 'none' | 'arrow' = 'none';
+    if (kind === 'path') {
+      d = strParam(params, 'd') ?? diagonal;
+      pathFill = strParam(params, 'fill') ?? 'none';
+    } else if (kind === 'arrow') {
+      endMarker = 'arrow';
+    } else if (kind !== 'line') {
+      d = shapePath(kind, x, y, width, height) ?? diagonal;
+      pathFill = strParam(params, 'fill') ?? 'none';
+    }
+    const path: PathLayer = {
+      id: child.id,
+      type: 'path',
+      position: { x: 0, y: 0, width: '100%', height: '100%' },
+      content: {
+        d,
+        stroke: strParam(params, 'stroke') ?? ink,
+        strokeWidth: numParam(params, 'strokeWidth') ?? 2,
+        fill: pathFill,
+        ...(strParam(params, 'dasharray') ? { dasharray: strParam(params, 'dasharray') } : {}),
+        ...(endMarker !== 'none' ? { endMarker } : {}),
+      },
+    };
+    layers.push(path);
+  }
+
+  return { layers, warnings };
+}
+
+/** Build a TextStyle from a text layer's annotation params. */
+function textStyleFromParams(
+  params: Record<string, string>,
+  ink: string,
+): TextLayer['content']['style'] {
+  const style: TextLayer['content']['style'] = {
+    fontSize: numParam(params, 'fontSize') ?? 32,
+    color: strParam(params, 'color') ?? ink,
+  };
+  const fontFamily = strParam(params, 'fontFamily');
+  if (fontFamily) style.fontFamily = fontFamily;
+  const fontWeight = strParam(params, 'fontWeight');
+  if (fontWeight === 'bold' || fontWeight === 'normal') style.fontWeight = fontWeight;
+  const fontStyle = strParam(params, 'fontStyle');
+  if (fontStyle === 'italic' || fontStyle === 'normal') style.fontStyle = fontStyle;
+  const align = strParam(params, 'align');
+  if (align === 'left' || align === 'center' || align === 'right') style.textAlign = align;
+  const valign = strParam(params, 'valign');
+  if (valign === 'top' || valign === 'middle' || valign === 'bottom') style.verticalAlign = valign;
+  const lineHeight = numParam(params, 'lineHeight');
+  if (lineHeight != null) style.lineHeight = lineHeight;
+  const padding = numParam(params, 'padding');
+  if (padding != null) style.padding = padding;
+  const background = strParam(params, 'background');
+  if (background) style.background = background;
+  return style;
+}
+
+/** Read a raw string param (trims a trailing comma — `x=21, y=25` tolerated). */
+function strParam(params: Record<string, string>, key: string): string | undefined {
+  const raw = params[key];
+  if (raw == null) return undefined;
+  const v = raw.replace(/,\s*$/, '').trim();
+  return v.length > 0 ? v : undefined;
+}
+
+/** Coerce a numeric param, tolerating a trailing comma. Undefined on failure. */
+function numParam(params: Record<string, string>, key: string): number | undefined {
+  const v = strParam(params, key);
+  if (v == null) return undefined;
+  const n = Number(v);
+  return Number.isFinite(n) ? n : undefined;
+}
+
+/** Plain text of a block's body content. */
+function bodyText(block: LayoutChildBlock): string {
+  if (!block.contents || block.contents.length === 0) return '';
+  return block.contents
+    .map((node) => extractPlainText(node))
+    .join('\n')
+    .trim();
+}
+
+function round(n: number): number {
+  return Math.round(n * 100) / 100;
+}