@twinfinity/printing 6.0.1-ci.28952-beta → 6.0.2-beta

package/src/layout/validation.ts

@@ -1,392 +1,392 @@
-import { isNonEmptyString, isPositiveNumber, isRemoteUrl, isDataUrl } from './validationUtils';
-import { isRecord, getProp } from './validationHelpers';
-import {
-    ELEMENT_KIND_VIEWPORT,
-    ELEMENT_KIND_TEXT,
-    ELEMENT_KIND_IMAGE,
-    ELEMENT_KIND_LINE,
-    ELEMENT_KIND_RECT,
-    ELEMENT_KIND_SCALE_BAR,
-    ELEMENT_KIND_QR,
-    ELEMENT_KIND_LABELS,
-    ELEMENT_KIND_LEGEND,
-    ELEMENT_KIND_GROUP
-} from './elementKinds';
-
-import type { ValidationOptions, ValidationIssue, ValidationResult } from './types';
-export type { ValidationOptions, ValidationIssue, ValidationResult };
-
-/**
- * Lightweight template validation (structure only) for v2 schema.
- */
-export function validateLayoutTemplate(template: unknown, options?: ValidationOptions): ValidationResult {
-    const allowRemoteAssets = options?.allowRemoteAssets ?? true;
-    const allowDataUrls = options?.allowDataUrls ?? true;
-    const maxViewports = options?.maxViewports ?? 3;
-    const errors: ValidationIssue[] = [];
-
-    if (!isRecord(template)) {
-        return { ok: false, errors: [{ path: '', message: 'Template must be an object.' }] };
-    }
-
-    const t = template;
-
-    const page = getProp(t, 'page');
-    if (!isRecord(page)) {
-        errors.push({ path: 'page', message: 'Page definition is required.' });
-    } else {
-        if (!isPositiveNumber(getProp(page, 'widthMm')))
-            errors.push({ path: 'page.widthMm', message: 'widthMm must be > 0.' });
-        if (!isPositiveNumber(getProp(page, 'heightMm')))
-            errors.push({ path: 'page.heightMm', message: 'heightMm must be > 0.' });
-        const marginMm = getProp(page, 'marginMm');
-        if (marginMm !== undefined && typeof marginMm !== 'number') {
-            errors.push({ path: 'page.marginMm', message: 'marginMm must be a number when provided.' });
-        }
-    }
-
-    const assetIds = new Set<string>();
-    const assets = getProp(t, 'assets');
-    if (Array.isArray(assets)) {
-        assets.forEach((asset: unknown, index: number) => {
-            if (!isRecord(asset)) {
-                errors.push({ path: `assets[${index}]`, message: 'Asset must be an object.' });
-                return;
-            }
-            const id = getProp(asset, 'id');
-            if (!isNonEmptyString(id)) {
-                errors.push({ path: `assets[${index}].id`, message: 'Asset id is required.' });
-            } else if (assetIds.has(id as string)) {
-                errors.push({ path: `assets[${index}].id`, message: 'Duplicate asset id.' });
-            } else {
-                assetIds.add(id as string);
-            }
-
-            const src = getProp(asset, 'src');
-            const content = getProp(asset, 'content');
-            if (!isNonEmptyString(src) && !isNonEmptyString(content)) {
-                errors.push({ path: `assets[${index}]`, message: 'Asset must have either src or content.' });
-            }
-
-            if (isNonEmptyString(src)) {
-                if (isRemoteUrl(src as string) && !allowRemoteAssets) {
-                    errors.push({ path: `assets[${index}].src`, message: 'Remote URLs are not allowed for assets.' });
-                } else if (isDataUrl(src as string) && !allowDataUrls) {
-                    errors.push({ path: `assets[${index}].src`, message: 'Data URLs are not allowed for assets.' });
-                }
-            }
-        });
-    } else if (assets !== undefined) {
-        errors.push({ path: 'assets', message: 'Assets must be an array when provided.' });
-    }
-
-    const styleNames = new Set<string>();
-    const styles = getProp(t, 'styles');
-    if (styles !== undefined) {
-        if (!isRecord(styles)) {
-            errors.push({ path: 'styles', message: 'Styles must be an object map.' });
-        } else {
-            Object.entries(styles).forEach(([name, style]) => {
-                styleNames.add(name);
-                if (!isRecord(style)) {
-                    errors.push({ path: `styles.${name}`, message: 'Style must be an object.' });
-                    return;
-                }
-                if (!isNonEmptyString(getProp(style, 'fontFamily'))) {
-                    errors.push({ path: `styles.${name}.fontFamily`, message: 'fontFamily is required.' });
-                }
-                if (!isPositiveNumber(getProp(style, 'fontSizeMm'))) {
-                    errors.push({ path: `styles.${name}.fontSizeMm`, message: 'fontSizeMm must be > 0.' });
-                }
-            });
-        }
-    }
-
-    let viewportCount = 0;
-
-    const validateElement = (el: unknown, path: string): void => {
-        if (!isRecord(el)) {
-            errors.push({ path, message: 'Element must be an object.' });
-            return;
-        }
-        const kind = getProp(el, 'kind');
-        if (!kind || typeof kind !== 'string') {
-            errors.push({ path: `${path}.kind`, message: 'Element kind is required.' });
-            return;
-        }
-
-        const ensure = (condition: boolean, subPath: string, message: string): void => {
-            if (!condition) errors.push({ path: subPath, message });
-        };
-
-        ensure(isNonEmptyString(getProp(el, 'id')), `${path}.id`, 'Element id is required.');
-
-        if (kind === ELEMENT_KIND_VIEWPORT) {
-            viewportCount++;
-            if (viewportCount > maxViewports) {
-                errors.push({ path, message: 'Too many viewports.' });
-            }
-            ensure(isPositiveNumber(getProp(el, 'widthMm')), `${path}.widthMm`, 'widthMm must be > 0.');
-            ensure(isPositiveNumber(getProp(el, 'heightMm')), `${path}.heightMm`, 'heightMm must be > 0.');
-            const xMm = getProp(el, 'xMm');
-            const yMm = getProp(el, 'yMm');
-            ensure(isPositiveNumber(xMm) || xMm === 0, `${path}.xMm`, 'xMm is required.');
-            ensure(isPositiveNumber(yMm) || yMm === 0, `${path}.yMm`, 'yMm is required.');
-            const border = getProp(el, 'border');
-            if (border) {
-                // border.stroke and border.strokeWidthMm are optional in v2
-            }
-            const clip = getProp(el, 'clip');
-            if (clip && isRecord(clip)) {
-                const where = getProp(clip, 'where');
-                if (!isRecord(where)) {
-                    errors.push({
-                        path: `${path}.clip.where`,
-                        message: 'clip.where is required and must be an object.'
-                    });
-                }
-            }
-            const highlight = getProp(el, 'highlight');
-            if (highlight && isRecord(highlight)) {
-                const where = getProp(highlight, 'where');
-                if (!isRecord(where)) {
-                    errors.push({
-                        path: `${path}.highlight.where`,
-                        message: 'highlight.where is required and must be an object.'
-                    });
-                }
-            }
-        } else if (kind === ELEMENT_KIND_TEXT) {
-            const xMm = getProp(el, 'xMm');
-            const yMm = getProp(el, 'yMm');
-            ensure(isPositiveNumber(xMm) || xMm === 0, `${path}.xMm`, 'xMm is required.');
-            ensure(isPositiveNumber(yMm) || yMm === 0, `${path}.yMm`, 'yMm is required.');
-            const textStyle = getProp(el, 'textStyle');
-            if (textStyle !== undefined) {
-                if (typeof textStyle === 'string' && styleNames.size > 0 && !styleNames.has(textStyle)) {
-                    errors.push({
-                        path: `${path}.textStyle`,
-                        message: `Style '${textStyle}' is not defined in styles.`
-                    });
-                }
-            }
-            ensure(isNonEmptyString(getProp(el, 'text')), `${path}.text`, 'text is required.');
-        } else if (kind === ELEMENT_KIND_IMAGE) {
-            ensure(isPositiveNumber(getProp(el, 'widthMm')), `${path}.widthMm`, 'widthMm must be > 0.');
-            ensure(isPositiveNumber(getProp(el, 'heightMm')), `${path}.heightMm`, 'heightMm must be > 0.');
-            ensure(isNonEmptyString(getProp(el, 'assetId')), `${path}.assetId`, 'assetId is required.');
-        } else if (kind === ELEMENT_KIND_LINE) {
-            // stroke and strokeWidthMm optional in v2
-        } else if (kind === ELEMENT_KIND_RECT) {
-            ensure(isPositiveNumber(getProp(el, 'widthMm')), `${path}.widthMm`, 'widthMm must be > 0.');
-            ensure(isPositiveNumber(getProp(el, 'heightMm')), `${path}.heightMm`, 'heightMm must be > 0.');
-        } else if (kind === ELEMENT_KIND_SCALE_BAR) {
-            ensure(isPositiveNumber(getProp(el, 'maxLengthMm')), `${path}.maxLengthMm`, 'maxLengthMm must be > 0.');
-            const textStyle = getProp(el, 'textStyle');
-            if (textStyle !== undefined) {
-                if (typeof textStyle === 'string' && styleNames.size > 0 && !styleNames.has(textStyle)) {
-                    errors.push({
-                        path: `${path}.textStyle`,
-                        message: `Style '${textStyle}' is not defined in styles.`
-                    });
-                }
-            }
-        } else if (kind === ELEMENT_KIND_QR) {
-            ensure(isPositiveNumber(getProp(el, 'sizeMm')), `${path}.sizeMm`, 'sizeMm must be > 0.');
-            const xMm = getProp(el, 'xMm');
-            const yMm = getProp(el, 'yMm');
-            ensure(isPositiveNumber(xMm) || xMm === 0, `${path}.xMm`, 'xMm is required.');
-            ensure(isPositiveNumber(yMm) || yMm === 0, `${path}.yMm`, 'yMm is required.');
-        } else if (kind === ELEMENT_KIND_LABELS) {
-            ensure(isNonEmptyString(getProp(el, 'viewport')), `${path}.viewport`, 'viewport is required.');
-            ensure(isNonEmptyString(getProp(el, 'text')), `${path}.text`, 'text is required.');
-            const textStyle = getProp(el, 'textStyle');
-            if (textStyle !== undefined) {
-                if (typeof textStyle === 'string' && styleNames.size > 0 && !styleNames.has(textStyle)) {
-                    errors.push({
-                        path: `${path}.textStyle`,
-                        message: `Style '${textStyle}' is not defined in styles.`
-                    });
-                }
-            }
-        } else if (kind === ELEMENT_KIND_LEGEND) {
-            ensure(isNonEmptyString(getProp(el, 'viewport')), `${path}.viewport`, 'viewport is required.');
-            const columns = getProp(el, 'columns');
-            if (!Array.isArray(columns) || !columns.length) {
-                errors.push({ path: `${path}.columns`, message: 'columns is required and must be a non-empty array.' });
-            } else {
-                columns.forEach((col: unknown, idx: number) => {
-                    if (!isRecord(col)) {
-                        errors.push({ path: `${path}.columns[${idx}]`, message: 'Column must be an object.' });
-                        return;
-                    }
-                    ensure(
-                        isNonEmptyString(getProp(col, 'id')),
-                        `${path}.columns[${idx}].id`,
-                        'Column id is required.'
-                    );
-                    ensure(
-                        isNonEmptyString(getProp(col, 'label')),
-                        `${path}.columns[${idx}].label`,
-                        'Column label is required.'
-                    );
-                    ensure(
-                        isNonEmptyString(getProp(col, 'property')),
-                        `${path}.columns[${idx}].property`,
-                        'Column property is required.'
-                    );
-                });
-            }
-            const textStyle = getProp(el, 'textStyle');
-            if (textStyle !== undefined) {
-                if (typeof textStyle === 'string' && styleNames.size > 0 && !styleNames.has(textStyle)) {
-                    errors.push({
-                        path: `${path}.textStyle`,
-                        message: `Style '${textStyle}' is not defined in styles.`
-                    });
-                }
-            }
-            const clipToViewport = getProp(el, 'clipToViewport');
-            if (clipToViewport !== undefined && typeof clipToViewport !== 'boolean') {
-                errors.push({
-                    path: `${path}.clipToViewport`,
-                    message: 'clipToViewport must be a boolean when provided.'
-                });
-            }
-        } else if (kind === ELEMENT_KIND_GROUP) {
-            const opacity = getProp(el, 'opacity');
-            if (opacity !== undefined) {
-                ensure(
-                    typeof opacity === 'number' && opacity >= 0 && opacity <= 1,
-                    `${path}.opacity`,
-                    'opacity must be between 0 and 1.'
-                );
-            }
-            const transform = getProp(el, 'transform');
-            if (transform) {
-                const scaleX = getProp(transform, 'scaleX');
-                const scaleY = getProp(transform, 'scaleY');
-                ensure(
-                    scaleX === undefined || typeof scaleX === 'number',
-                    `${path}.transform.scaleX`,
-                    'scaleX must be a number'
-                );
-                ensure(
-                    scaleY === undefined || typeof scaleY === 'number',
-                    `${path}.transform.scaleY`,
-                    'scaleY must be a number'
-                );
-            }
-            const clip = getProp(el, 'clip');
-            if (clip) {
-                ensure(getProp(clip, 'type') === 'rect', `${path}.clip.type`, "clip.type must be 'rect'.");
-                ensure(isPositiveNumber(getProp(clip, 'widthMm')), `${path}.clip.widthMm`, 'clip.widthMm must be > 0.');
-                ensure(
-                    isPositiveNumber(getProp(clip, 'heightMm')),
-                    `${path}.clip.heightMm`,
-                    'clip.heightMm must be > 0.'
-                );
-                const clipXMm = getProp(clip, 'xMm');
-                const clipYMm = getProp(clip, 'yMm');
-                ensure(isPositiveNumber(clipXMm) || clipXMm === 0, `${path}.clip.xMm`, 'clip.xMm is required.');
-                ensure(isPositiveNumber(clipYMm) || clipYMm === 0, `${path}.clip.yMm`, 'clip.yMm is required.');
-            }
-            const children = getProp(el, 'children');
-            if (Array.isArray(children)) {
-                children.forEach((child: unknown, childIdx: number) =>
-                    validateElement(child, `${path}.children[${childIdx}]`)
-                );
-            }
-        } else {
-            errors.push({ path, message: `Unknown element kind '${kind}'.` });
-        }
-    };
-
-    const elements = getProp(t, 'elements');
-    if (Array.isArray(elements)) {
-        elements.forEach((el: unknown, index: number) => validateElement(el, `elements[${index}]`));
-    } else if (elements !== undefined) {
-        errors.push({ path: 'elements', message: 'Elements must be an array.' });
-    }
-
-    // Validate template variables (if present)
-    const variables = getProp(t, 'variables');
-    if (variables !== undefined) {
-        if (!isRecord(variables)) {
-            errors.push({ path: 'variables', message: 'Variables must be an object.' });
-        } else {
-            // Validate each variable definition
-            for (const [varName, varDef] of Object.entries(variables)) {
-                const varPath = `variables.${varName}`;
-
-                if (!isRecord(varDef)) {
-                    errors.push({ path: varPath, message: 'Variable definition must be an object.' });
-                    continue;
-                }
-
-                // Validate type
-                const varType = getProp(varDef, 'type');
-                if (!['string', 'number', 'boolean', 'array'].includes(varType as string)) {
-                    errors.push({
-                        path: `${varPath}.type`,
-                        message: `Type must be 'string', 'number', 'boolean', or 'array' (got '${varType}').`
-                    });
-                }
-
-                // Enforce default value (CRITICAL for fail-safe operation)
-                const defaultValue = getProp(varDef, 'default');
-                if (defaultValue === undefined || defaultValue === null) {
-                    errors.push({
-                        path: `${varPath}.default`,
-                        message: 'Variable must have a default value (required for fail-safe operation).'
-                    });
-                } else {
-                    // Validate default value matches declared type
-                    const actualType = Array.isArray(defaultValue) ? 'array' : typeof defaultValue;
-                    if (varType === 'number' && actualType !== 'number') {
-                        errors.push({
-                            path: `${varPath}.default`,
-                            message: `Default value must be a number (got ${actualType}).`
-                        });
-                    } else if (varType === 'string' && actualType !== 'string') {
-                        errors.push({
-                            path: `${varPath}.default`,
-                            message: `Default value must be a string (got ${actualType}).`
-                        });
-                    } else if (varType === 'boolean' && actualType !== 'boolean') {
-                        errors.push({
-                            path: `${varPath}.default`,
-                            message: `Default value must be a boolean (got ${actualType}).`
-                        });
-                    } else if (varType === 'array' && actualType !== 'array') {
-                        errors.push({
-                            path: `${varPath}.default`,
-                            message: `Default value must be an array (got ${actualType}).`
-                        });
-                    }
-                }
-
-                // Validate numeric constraints (if present)
-                if (varType === 'number') {
-                    const min = getProp(varDef, 'min');
-                    const max = getProp(varDef, 'max');
-                    if (min !== undefined && typeof min !== 'number') {
-                        errors.push({ path: `${varPath}.min`, message: 'min must be a number.' });
-                    }
-                    if (max !== undefined && typeof max !== 'number') {
-                        errors.push({ path: `${varPath}.max`, message: 'max must be a number.' });
-                    }
-                    if (typeof min === 'number' && typeof max === 'number' && min > max) {
-                        errors.push({ path: `${varPath}`, message: 'min cannot be greater than max.' });
-                    }
-                }
-            }
-        }
-    }
-
-    if (errors.length) {
-        return { ok: false, errors };
-    }
-
-    return { ok: true, template };
-}
+import { isNonEmptyString, isPositiveNumber, isRemoteUrl, isDataUrl } from './validationUtils';
+import { isRecord, getProp } from './validationHelpers';
+import {
+    ELEMENT_KIND_VIEWPORT,
+    ELEMENT_KIND_TEXT,
+    ELEMENT_KIND_IMAGE,
+    ELEMENT_KIND_LINE,
+    ELEMENT_KIND_RECT,
+    ELEMENT_KIND_SCALE_BAR,
+    ELEMENT_KIND_QR,
+    ELEMENT_KIND_LABELS,
+    ELEMENT_KIND_LEGEND,
+    ELEMENT_KIND_GROUP
+} from './elementKinds';
+
+import type { ValidationOptions, ValidationIssue, ValidationResult } from './types';
+export type { ValidationOptions, ValidationIssue, ValidationResult };
+
+/**
+ * Lightweight template validation (structure only) for v2 schema.
+ */
+export function validateLayoutTemplate(template: unknown, options?: ValidationOptions): ValidationResult {
+    const allowRemoteAssets = options?.allowRemoteAssets ?? true;
+    const allowDataUrls = options?.allowDataUrls ?? true;
+    const maxViewports = options?.maxViewports ?? 3;
+    const errors: ValidationIssue[] = [];
+
+    if (!isRecord(template)) {
+        return { ok: false, errors: [{ path: '', message: 'Template must be an object.' }] };
+    }
+
+    const t = template;
+
+    const page = getProp(t, 'page');
+    if (!isRecord(page)) {
+        errors.push({ path: 'page', message: 'Page definition is required.' });
+    } else {
+        if (!isPositiveNumber(getProp(page, 'widthMm')))
+            errors.push({ path: 'page.widthMm', message: 'widthMm must be > 0.' });
+        if (!isPositiveNumber(getProp(page, 'heightMm')))
+            errors.push({ path: 'page.heightMm', message: 'heightMm must be > 0.' });
+        const marginMm = getProp(page, 'marginMm');
+        if (marginMm !== undefined && typeof marginMm !== 'number') {
+            errors.push({ path: 'page.marginMm', message: 'marginMm must be a number when provided.' });
+        }
+    }
+
+    const assetIds = new Set<string>();
+    const assets = getProp(t, 'assets');
+    if (Array.isArray(assets)) {
+        assets.forEach((asset: unknown, index: number) => {
+            if (!isRecord(asset)) {
+                errors.push({ path: `assets[${index}]`, message: 'Asset must be an object.' });
+                return;
+            }
+            const id = getProp(asset, 'id');
+            if (!isNonEmptyString(id)) {
+                errors.push({ path: `assets[${index}].id`, message: 'Asset id is required.' });
+            } else if (assetIds.has(id as string)) {
+                errors.push({ path: `assets[${index}].id`, message: 'Duplicate asset id.' });
+            } else {
+                assetIds.add(id as string);
+            }
+
+            const src = getProp(asset, 'src');
+            const content = getProp(asset, 'content');
+            if (!isNonEmptyString(src) && !isNonEmptyString(content)) {
+                errors.push({ path: `assets[${index}]`, message: 'Asset must have either src or content.' });
+            }
+
+            if (isNonEmptyString(src)) {
+                if (isRemoteUrl(src as string) && !allowRemoteAssets) {
+                    errors.push({ path: `assets[${index}].src`, message: 'Remote URLs are not allowed for assets.' });
+                } else if (isDataUrl(src as string) && !allowDataUrls) {
+                    errors.push({ path: `assets[${index}].src`, message: 'Data URLs are not allowed for assets.' });
+                }
+            }
+        });
+    } else if (assets !== undefined) {
+        errors.push({ path: 'assets', message: 'Assets must be an array when provided.' });
+    }
+
+    const styleNames = new Set<string>();
+    const styles = getProp(t, 'styles');
+    if (styles !== undefined) {
+        if (!isRecord(styles)) {
+            errors.push({ path: 'styles', message: 'Styles must be an object map.' });
+        } else {
+            Object.entries(styles).forEach(([name, style]) => {
+                styleNames.add(name);
+                if (!isRecord(style)) {
+                    errors.push({ path: `styles.${name}`, message: 'Style must be an object.' });
+                    return;
+                }
+                if (!isNonEmptyString(getProp(style, 'fontFamily'))) {
+                    errors.push({ path: `styles.${name}.fontFamily`, message: 'fontFamily is required.' });
+                }
+                if (!isPositiveNumber(getProp(style, 'fontSizeMm'))) {
+                    errors.push({ path: `styles.${name}.fontSizeMm`, message: 'fontSizeMm must be > 0.' });
+                }
+            });
+        }
+    }
+
+    let viewportCount = 0;
+
+    const validateElement = (el: unknown, path: string): void => {
+        if (!isRecord(el)) {
+            errors.push({ path, message: 'Element must be an object.' });
+            return;
+        }
+        const kind = getProp(el, 'kind');
+        if (!kind || typeof kind !== 'string') {
+            errors.push({ path: `${path}.kind`, message: 'Element kind is required.' });
+            return;
+        }
+
+        const ensure = (condition: boolean, subPath: string, message: string): void => {
+            if (!condition) errors.push({ path: subPath, message });
+        };
+
+        ensure(isNonEmptyString(getProp(el, 'id')), `${path}.id`, 'Element id is required.');
+
+        if (kind === ELEMENT_KIND_VIEWPORT) {
+            viewportCount++;
+            if (viewportCount > maxViewports) {
+                errors.push({ path, message: 'Too many viewports.' });
+            }
+            ensure(isPositiveNumber(getProp(el, 'widthMm')), `${path}.widthMm`, 'widthMm must be > 0.');
+            ensure(isPositiveNumber(getProp(el, 'heightMm')), `${path}.heightMm`, 'heightMm must be > 0.');
+            const xMm = getProp(el, 'xMm');
+            const yMm = getProp(el, 'yMm');
+            ensure(isPositiveNumber(xMm) || xMm === 0, `${path}.xMm`, 'xMm is required.');
+            ensure(isPositiveNumber(yMm) || yMm === 0, `${path}.yMm`, 'yMm is required.');
+            const border = getProp(el, 'border');
+            if (border) {
+                // border.stroke and border.strokeWidthMm are optional in v2
+            }
+            const clip = getProp(el, 'clip');
+            if (clip && isRecord(clip)) {
+                const where = getProp(clip, 'where');
+                if (!isRecord(where)) {
+                    errors.push({
+                        path: `${path}.clip.where`,
+                        message: 'clip.where is required and must be an object.'
+                    });
+                }
+            }
+            const highlight = getProp(el, 'highlight');
+            if (highlight && isRecord(highlight)) {
+                const where = getProp(highlight, 'where');
+                if (!isRecord(where)) {
+                    errors.push({
+                        path: `${path}.highlight.where`,
+                        message: 'highlight.where is required and must be an object.'
+                    });
+                }
+            }
+        } else if (kind === ELEMENT_KIND_TEXT) {
+            const xMm = getProp(el, 'xMm');
+            const yMm = getProp(el, 'yMm');
+            ensure(isPositiveNumber(xMm) || xMm === 0, `${path}.xMm`, 'xMm is required.');
+            ensure(isPositiveNumber(yMm) || yMm === 0, `${path}.yMm`, 'yMm is required.');
+            const textStyle = getProp(el, 'textStyle');
+            if (textStyle !== undefined) {
+                if (typeof textStyle === 'string' && styleNames.size > 0 && !styleNames.has(textStyle)) {
+                    errors.push({
+                        path: `${path}.textStyle`,
+                        message: `Style '${textStyle}' is not defined in styles.`
+                    });
+                }
+            }
+            ensure(isNonEmptyString(getProp(el, 'text')), `${path}.text`, 'text is required.');
+        } else if (kind === ELEMENT_KIND_IMAGE) {
+            ensure(isPositiveNumber(getProp(el, 'widthMm')), `${path}.widthMm`, 'widthMm must be > 0.');
+            ensure(isPositiveNumber(getProp(el, 'heightMm')), `${path}.heightMm`, 'heightMm must be > 0.');
+            ensure(isNonEmptyString(getProp(el, 'assetId')), `${path}.assetId`, 'assetId is required.');
+        } else if (kind === ELEMENT_KIND_LINE) {
+            // stroke and strokeWidthMm optional in v2
+        } else if (kind === ELEMENT_KIND_RECT) {
+            ensure(isPositiveNumber(getProp(el, 'widthMm')), `${path}.widthMm`, 'widthMm must be > 0.');
+            ensure(isPositiveNumber(getProp(el, 'heightMm')), `${path}.heightMm`, 'heightMm must be > 0.');
+        } else if (kind === ELEMENT_KIND_SCALE_BAR) {
+            ensure(isPositiveNumber(getProp(el, 'maxLengthMm')), `${path}.maxLengthMm`, 'maxLengthMm must be > 0.');
+            const textStyle = getProp(el, 'textStyle');
+            if (textStyle !== undefined) {
+                if (typeof textStyle === 'string' && styleNames.size > 0 && !styleNames.has(textStyle)) {
+                    errors.push({
+                        path: `${path}.textStyle`,
+                        message: `Style '${textStyle}' is not defined in styles.`
+                    });
+                }
+            }
+        } else if (kind === ELEMENT_KIND_QR) {
+            ensure(isPositiveNumber(getProp(el, 'sizeMm')), `${path}.sizeMm`, 'sizeMm must be > 0.');
+            const xMm = getProp(el, 'xMm');
+            const yMm = getProp(el, 'yMm');
+            ensure(isPositiveNumber(xMm) || xMm === 0, `${path}.xMm`, 'xMm is required.');
+            ensure(isPositiveNumber(yMm) || yMm === 0, `${path}.yMm`, 'yMm is required.');
+        } else if (kind === ELEMENT_KIND_LABELS) {
+            ensure(isNonEmptyString(getProp(el, 'viewport')), `${path}.viewport`, 'viewport is required.');
+            ensure(isNonEmptyString(getProp(el, 'text')), `${path}.text`, 'text is required.');
+            const textStyle = getProp(el, 'textStyle');
+            if (textStyle !== undefined) {
+                if (typeof textStyle === 'string' && styleNames.size > 0 && !styleNames.has(textStyle)) {
+                    errors.push({
+                        path: `${path}.textStyle`,
+                        message: `Style '${textStyle}' is not defined in styles.`
+                    });
+                }
+            }
+        } else if (kind === ELEMENT_KIND_LEGEND) {
+            ensure(isNonEmptyString(getProp(el, 'viewport')), `${path}.viewport`, 'viewport is required.');
+            const columns = getProp(el, 'columns');
+            if (!Array.isArray(columns) || !columns.length) {
+                errors.push({ path: `${path}.columns`, message: 'columns is required and must be a non-empty array.' });
+            } else {
+                columns.forEach((col: unknown, idx: number) => {
+                    if (!isRecord(col)) {
+                        errors.push({ path: `${path}.columns[${idx}]`, message: 'Column must be an object.' });
+                        return;
+                    }
+                    ensure(
+                        isNonEmptyString(getProp(col, 'id')),
+                        `${path}.columns[${idx}].id`,
+                        'Column id is required.'
+                    );
+                    ensure(
+                        isNonEmptyString(getProp(col, 'label')),
+                        `${path}.columns[${idx}].label`,
+                        'Column label is required.'
+                    );
+                    ensure(
+                        isNonEmptyString(getProp(col, 'property')),
+                        `${path}.columns[${idx}].property`,
+                        'Column property is required.'
+                    );
+                });
+            }
+            const textStyle = getProp(el, 'textStyle');
+            if (textStyle !== undefined) {
+                if (typeof textStyle === 'string' && styleNames.size > 0 && !styleNames.has(textStyle)) {
+                    errors.push({
+                        path: `${path}.textStyle`,
+                        message: `Style '${textStyle}' is not defined in styles.`
+                    });
+                }
+            }
+            const clipToViewport = getProp(el, 'clipToViewport');
+            if (clipToViewport !== undefined && typeof clipToViewport !== 'boolean') {
+                errors.push({
+                    path: `${path}.clipToViewport`,
+                    message: 'clipToViewport must be a boolean when provided.'
+                });
+            }
+        } else if (kind === ELEMENT_KIND_GROUP) {
+            const opacity = getProp(el, 'opacity');
+            if (opacity !== undefined) {
+                ensure(
+                    typeof opacity === 'number' && opacity >= 0 && opacity <= 1,
+                    `${path}.opacity`,
+                    'opacity must be between 0 and 1.'
+                );
+            }
+            const transform = getProp(el, 'transform');
+            if (transform) {
+                const scaleX = getProp(transform, 'scaleX');
+                const scaleY = getProp(transform, 'scaleY');
+                ensure(
+                    scaleX === undefined || typeof scaleX === 'number',
+                    `${path}.transform.scaleX`,
+                    'scaleX must be a number'
+                );
+                ensure(
+                    scaleY === undefined || typeof scaleY === 'number',
+                    `${path}.transform.scaleY`,
+                    'scaleY must be a number'
+                );
+            }
+            const clip = getProp(el, 'clip');
+            if (clip) {
+                ensure(getProp(clip, 'type') === 'rect', `${path}.clip.type`, "clip.type must be 'rect'.");
+                ensure(isPositiveNumber(getProp(clip, 'widthMm')), `${path}.clip.widthMm`, 'clip.widthMm must be > 0.');
+                ensure(
+                    isPositiveNumber(getProp(clip, 'heightMm')),
+                    `${path}.clip.heightMm`,
+                    'clip.heightMm must be > 0.'
+                );
+                const clipXMm = getProp(clip, 'xMm');
+                const clipYMm = getProp(clip, 'yMm');
+                ensure(isPositiveNumber(clipXMm) || clipXMm === 0, `${path}.clip.xMm`, 'clip.xMm is required.');
+                ensure(isPositiveNumber(clipYMm) || clipYMm === 0, `${path}.clip.yMm`, 'clip.yMm is required.');
+            }
+            const children = getProp(el, 'children');
+            if (Array.isArray(children)) {
+                children.forEach((child: unknown, childIdx: number) =>
+                    validateElement(child, `${path}.children[${childIdx}]`)
+                );
+            }
+        } else {
+            errors.push({ path, message: `Unknown element kind '${kind}'.` });
+        }
+    };
+
+    const elements = getProp(t, 'elements');
+    if (Array.isArray(elements)) {
+        elements.forEach((el: unknown, index: number) => validateElement(el, `elements[${index}]`));
+    } else if (elements !== undefined) {
+        errors.push({ path: 'elements', message: 'Elements must be an array.' });
+    }
+
+    // Validate template variables (if present)
+    const variables = getProp(t, 'variables');
+    if (variables !== undefined) {
+        if (!isRecord(variables)) {
+            errors.push({ path: 'variables', message: 'Variables must be an object.' });
+        } else {
+            // Validate each variable definition
+            for (const [varName, varDef] of Object.entries(variables)) {
+                const varPath = `variables.${varName}`;
+
+                if (!isRecord(varDef)) {
+                    errors.push({ path: varPath, message: 'Variable definition must be an object.' });
+                    continue;
+                }
+
+                // Validate type
+                const varType = getProp(varDef, 'type');
+                if (!['string', 'number', 'boolean', 'array'].includes(varType as string)) {
+                    errors.push({
+                        path: `${varPath}.type`,
+                        message: `Type must be 'string', 'number', 'boolean', or 'array' (got '${varType}').`
+                    });
+                }
+
+                // Enforce default value (CRITICAL for fail-safe operation)
+                const defaultValue = getProp(varDef, 'default');
+                if (defaultValue === undefined || defaultValue === null) {
+                    errors.push({
+                        path: `${varPath}.default`,
+                        message: 'Variable must have a default value (required for fail-safe operation).'
+                    });
+                } else {
+                    // Validate default value matches declared type
+                    const actualType = Array.isArray(defaultValue) ? 'array' : typeof defaultValue;
+                    if (varType === 'number' && actualType !== 'number') {
+                        errors.push({
+                            path: `${varPath}.default`,
+                            message: `Default value must be a number (got ${actualType}).`
+                        });
+                    } else if (varType === 'string' && actualType !== 'string') {
+                        errors.push({
+                            path: `${varPath}.default`,
+                            message: `Default value must be a string (got ${actualType}).`
+                        });
+                    } else if (varType === 'boolean' && actualType !== 'boolean') {
+                        errors.push({
+                            path: `${varPath}.default`,
+                            message: `Default value must be a boolean (got ${actualType}).`
+                        });
+                    } else if (varType === 'array' && actualType !== 'array') {
+                        errors.push({
+                            path: `${varPath}.default`,
+                            message: `Default value must be an array (got ${actualType}).`
+                        });
+                    }
+                }
+
+                // Validate numeric constraints (if present)
+                if (varType === 'number') {
+                    const min = getProp(varDef, 'min');
+                    const max = getProp(varDef, 'max');
+                    if (min !== undefined && typeof min !== 'number') {
+                        errors.push({ path: `${varPath}.min`, message: 'min must be a number.' });
+                    }
+                    if (max !== undefined && typeof max !== 'number') {
+                        errors.push({ path: `${varPath}.max`, message: 'max must be a number.' });
+                    }
+                    if (typeof min === 'number' && typeof max === 'number' && min > max) {
+                        errors.push({ path: `${varPath}`, message: 'min cannot be greater than max.' });
+                    }
+                }
+            }
+        }
+    }
+
+    if (errors.length) {
+        return { ok: false, errors };
+    }
+
+    return { ok: true, template };
+}