@twinfinity/printing 6.1.0-beta → 6.1.2-ci.30738-beta

package/src/layout/validation.ts

@@ -6,6 +6,9 @@ import {
     ELEMENT_KIND_IMAGE,
     ELEMENT_KIND_LINE,
     ELEMENT_KIND_RECT,
+    ELEMENT_KIND_CIRCLE,
+    ELEMENT_KIND_POLYLINE,
+    ELEMENT_KIND_POLYGON,
     ELEMENT_KIND_SCALE_BAR,
     ELEMENT_KIND_QR,
     ELEMENT_KIND_LABELS,
@@ -20,9 +23,9 @@ 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 maxViewports = options?.maxViewports ?? 8;
+    const strictResourceRefs = options?.strictResourceRefs ?? false;
     const errors: ValidationIssue[] = [];
 
     if (!isRecord(template)) {
@@ -30,6 +33,10 @@ export function validateLayoutTemplate(template: unknown, options?: ValidationOp
     }
 
     const t = template;
+    // Remote resources are opt-in (matches the schema default and the
+    // renderer's warnings): explicit option wins, else the template's own
+    // root flag, else disallowed.
+    const allowRemoteResources = options?.allowRemoteResources ?? getProp(t, 'allowRemoteResources') === true;
 
     const page = getProp(t, 'page');
     if (!isRecord(page)) {
@@ -45,39 +52,45 @@ export function validateLayoutTemplate(template: unknown, options?: ValidationOp
         }
     }
 
-    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.' });
+    const resourceIds = new Set<string>();
+    const resources = getProp(t, 'resources');
+    if (Array.isArray(resources)) {
+        resources.forEach((resource: unknown, index: number) => {
+            if (!isRecord(resource)) {
+                errors.push({ path: `resources[${index}]`, message: 'Resource must be an object.' });
                 return;
             }
-            const id = getProp(asset, 'id');
+            const id = getProp(resource, '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.' });
+                errors.push({ path: `resources[${index}].id`, message: 'Resource id is required.' });
+            } else if (resourceIds.has(id as string)) {
+                errors.push({ path: `resources[${index}].id`, message: 'Duplicate resource id.' });
             } else {
-                assetIds.add(id as string);
+                resourceIds.add(id as string);
             }
 
-            const src = getProp(asset, 'src');
-            const content = getProp(asset, 'content');
+            const src = getProp(resource, 'src');
+            const content = getProp(resource, 'content');
             if (!isNonEmptyString(src) && !isNonEmptyString(content)) {
-                errors.push({ path: `assets[${index}]`, message: 'Asset must have either src or content.' });
+                errors.push({ path: `resources[${index}]`, message: 'Resource 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.' });
+                if (isRemoteUrl(src as string) && !allowRemoteResources) {
+                    errors.push({
+                        path: `resources[${index}].src`,
+                        message: 'Remote URLs are not allowed for resources.'
+                    });
                 } else if (isDataUrl(src as string) && !allowDataUrls) {
-                    errors.push({ path: `assets[${index}].src`, message: 'Data URLs are not allowed for assets.' });
+                    errors.push({
+                        path: `resources[${index}].src`,
+                        message: 'Data URLs are not allowed for resources.'
+                    });
                 }
             }
         });
-    } else if (assets !== undefined) {
-        errors.push({ path: 'assets', message: 'Assets must be an array when provided.' });
+    } else if (resources !== undefined) {
+        errors.push({ path: 'resources', message: 'Resources must be an array when provided.' });
     }
 
     const styleNames = new Set<string>();
@@ -130,8 +143,8 @@ export function validateLayoutTemplate(template: unknown, options?: ValidationOp
             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.');
+            ensure(typeof xMm === 'number' && Number.isFinite(xMm), `${path}.xMm`, 'xMm is required.');
+            ensure(typeof yMm === 'number' && Number.isFinite(yMm), `${path}.yMm`, 'yMm is required.');
             const border = getProp(el, 'border');
             if (border) {
                 // border.stroke and border.strokeWidthMm are optional in v2
@@ -159,8 +172,8 @@ export function validateLayoutTemplate(template: unknown, options?: ValidationOp
         } 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.');
+            ensure(typeof xMm === 'number' && Number.isFinite(xMm), `${path}.xMm`, 'xMm is required.');
+            ensure(typeof yMm === 'number' && Number.isFinite(yMm), `${path}.yMm`, 'yMm is required.');
             const textStyle = getProp(el, 'textStyle');
             if (textStyle !== undefined) {
                 if (typeof textStyle === 'string' && styleNames.size > 0 && !styleNames.has(textStyle)) {
@@ -174,12 +187,47 @@ export function validateLayoutTemplate(template: unknown, options?: ValidationOp
         } 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.');
+            const resourceId = getProp(el, 'resourceId');
+            ensure(isNonEmptyString(resourceId), `${path}.resourceId`, 'resourceId is required.');
+            // Opt-in only. `renderLayout` throws on any validation error, so treating a dangling
+            // reference as one turns a template that used to print without a single logo into a
+            // template that does not print at all — the renderer already warns and skips that
+            // element, which is the better outcome mid-print. Authoring tools that want the typo
+            // caught up front can ask for it.
+            if (strictResourceRefs && isNonEmptyString(resourceId) && !resourceIds.has(resourceId)) {
+                ensure(false, `${path}.resourceId`, `No resource is declared with id '${resourceId}'.`);
+            }
         } 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_CIRCLE) {
+            ensure(isPositiveNumber(getProp(el, 'rMm')), `${path}.rMm`, 'rMm must be > 0.');
+            const cxMm = getProp(el, 'cxMm');
+            const cyMm = getProp(el, 'cyMm');
+            ensure(typeof cxMm === 'number' && Number.isFinite(cxMm), `${path}.cxMm`, 'cxMm is required.');
+            ensure(typeof cyMm === 'number' && Number.isFinite(cyMm), `${path}.cyMm`, 'cyMm is required.');
+        } else if (kind === ELEMENT_KIND_POLYLINE) {
+            const points = getProp(el, 'points');
+            ensure(
+                Array.isArray(points) && points.length >= 2,
+                `${path}.points`,
+                'points is required (at least 2 points).'
+            );
+            ensure(isNonEmptyString(getProp(el, 'stroke')), `${path}.stroke`, 'stroke is required.');
+            ensure(
+                isPositiveNumber(getProp(el, 'strokeWidthMm')),
+                `${path}.strokeWidthMm`,
+                'strokeWidthMm must be > 0.'
+            );
+        } else if (kind === ELEMENT_KIND_POLYGON) {
+            const points = getProp(el, 'points');
+            ensure(
+                Array.isArray(points) && points.length >= 3,
+                `${path}.points`,
+                'points is required (at least 3 points).'
+            );
         } else if (kind === ELEMENT_KIND_SCALE_BAR) {
             ensure(isPositiveNumber(getProp(el, 'maxLengthMm')), `${path}.maxLengthMm`, 'maxLengthMm must be > 0.');
             const textStyle = getProp(el, 'textStyle');
@@ -195,8 +243,8 @@ export function validateLayoutTemplate(template: unknown, options?: ValidationOp
             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.');
+            ensure(typeof xMm === 'number' && Number.isFinite(xMm), `${path}.xMm`, 'xMm is required.');
+            ensure(typeof yMm === 'number' && Number.isFinite(yMm), `${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.');
@@ -288,8 +336,16 @@ export function validateLayoutTemplate(template: unknown, options?: ValidationOp
                 );
                 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.');
+                ensure(
+                    typeof clipXMm === 'number' && Number.isFinite(clipXMm),
+                    `${path}.clip.xMm`,
+                    'clip.xMm is required.'
+                );
+                ensure(
+                    typeof clipYMm === 'number' && Number.isFinite(clipYMm),
+                    `${path}.clip.yMm`,
+                    'clip.yMm is required.'
+                );
             }
             const children = getProp(el, 'children');
             if (Array.isArray(children)) {
@@ -305,8 +361,8 @@ export function validateLayoutTemplate(template: unknown, options?: ValidationOp
     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.' });
+    } else {
+        errors.push({ path: 'elements', message: 'elements is required and must be an array.' });
     }
 
     // Validate template variables (if present)
@@ -319,6 +375,16 @@ export function validateLayoutTemplate(template: unknown, options?: ValidationOp
             for (const [varName, varDef] of Object.entries(variables)) {
                 const varPath = `variables.${varName}`;
 
+                // Names are referenced as {{vars.<name>}} — non-identifier
+                // names (dashes, dots, spaces) collide with the placeholder
+                // syntax and are silently never substituted.
+                if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(varName)) {
+                    errors.push({
+                        path: varPath,
+                        message: 'Variable names must be simple identifiers ([A-Za-z_][A-Za-z0-9_]*).'
+                    });
+                }
+
                 if (!isRecord(varDef)) {
                     errors.push({ path: varPath, message: 'Variable definition must be an object.' });
                     continue;

package/src/layout/viewportPrep.ts

@@ -5,8 +5,8 @@ import { pushWarning } from './warnings';
 import { pickScale } from './viewportUtils';
 import type { ResolvedPresets } from './presets';
 import { getPathValue } from './renderUtils';
-import { pointInPolygon, offsetPolygons, Polygon } from './clipUtils';
-import { matchesV2Filter, normalizeClass } from './filters';
+import { pointInPolygon, offsetPolygons, unionPolygons, Polygon } from './clipUtils';
+import { matchesFilter, normalizeClass } from './filters';
 import { EPSILON_MIN_DIMENSION } from './geometryConstants';
 
 export interface ViewportPrepResult {
@@ -20,7 +20,7 @@ export interface ViewportPrepResult {
     viewportClipLabels: Record<string, boolean>;
     viewportClipStyles: Record<
         string,
-        { stroke?: string; strokeWidthMm?: number; strokeOpacity?: number; fill?: string; fillOpacity?: number }
+        { color?: string; widthMm?: number; opacity?: number; dash?: string; fill?: string; fillOpacity?: number }
     >;
     viewportClipWhere: Record<string, WhereCondition | undefined>;
     viewportHighlight: Record<
@@ -28,9 +28,10 @@ export interface ViewportPrepResult {
         {
             gids: Set<string> | null;
             styles: {
-                stroke?: string;
-                strokeWidthMm?: number;
-                strokeOpacity?: number;
+                color?: string;
+                widthMm?: number;
+                opacity?: number;
+                dash?: string;
                 fill?: string;
                 fillOpacity?: number;
             };
@@ -60,7 +61,7 @@ export const prepareViewports = (
     const viewportClipLabels: Record<string, boolean> = {};
     const viewportClipStyles: Record<
         string,
-        { stroke?: string; strokeWidthMm?: number; strokeOpacity?: number; fill?: string; fillOpacity?: number }
+        { color?: string; widthMm?: number; opacity?: number; dash?: string; fill?: string; fillOpacity?: number }
     > = {};
     const viewportClipWhere: Record<string, WhereCondition | undefined> = {};
     const viewportHighlight: ViewportPrepResult['viewportHighlight'] = {};
@@ -77,7 +78,7 @@ export const prepareViewports = (
         if (hlCfg && hlCfg.where) {
             const sourceItems = getPathValue(data, `viewports.${vp.id}.items`);
             if (Array.isArray(sourceItems) && sourceItems.length) {
-                const matching = sourceItems.filter((it) => matchesV2Filter(it, hlCfg.class, hlCfg.where));
+                const matching = sourceItems.filter((it) => matchesFilter(it, hlCfg.class, hlCfg.where));
                 if (matching.length) {
                     highlightGids = new Set(
                         matching
@@ -130,7 +131,7 @@ export const prepareViewports = (
             viewportClipWhere[vp.id] = clipCfg.where;
             const sourceItems = getPathValue(data, `viewports.${vp.id}.items`);
             if (Array.isArray(sourceItems) && sourceItems.length) {
-                const matchingItems = sourceItems.filter((it) => matchesV2Filter(it, clipCfg.class, clipCfg.where));
+                const matchingItems = sourceItems.filter((it) => matchesFilter(it, clipCfg.class, clipCfg.where));
                 if (!matchingItems.length) {
                     pushWarning(
                         options.warnings,
@@ -167,13 +168,17 @@ export const prepareViewports = (
                         }
                         if (mapped.length >= 3) projectedLocal.push(mapped);
                     }
-                    const expandByM =
-                        typeof clipCfg.expandByM === 'number' &&
-                        Number.isFinite(clipCfg.expandByM) &&
-                        clipCfg.expandByM > 0
-                            ? clipCfg.expandByM
+                    const expandBy =
+                        typeof clipCfg.expandBy === 'number' &&
+                        Number.isFinite(clipCfg.expandBy) &&
+                        clipCfg.expandBy > 0
+                            ? clipCfg.expandBy
                             : 0;
-                    const buffered = expandByM > 0 ? offsetPolygons(projectedLocal, expandByM) : projectedLocal;
+                    const expanded = expandBy > 0 ? offsetPolygons(projectedLocal, expandBy) : projectedLocal;
+                    // Merge overlapping polygons into single outlines (the
+                    // result rings can include holes — everything downstream
+                    // renders them with even-odd rules).
+                    const buffered = unionPolygons(expanded);
 
                     if (buffered.length) {
                         // Calculate bounds from EXPANDED polygon for viewport sizing (so everything fits)
@@ -196,9 +201,10 @@ export const prepareViewports = (
                         viewportClipPolygonsLocal[vp.id] = buffered;
                         viewportClipLabels[vp.id] = !!clipCfg.clipLabels;
                         viewportClipStyles[vp.id] = {
-                            stroke: clipCfg.stroke ?? '#000000',
-                            strokeWidthMm: clipCfg.strokeWidthMm ?? 0.5,
-                            strokeOpacity: clipCfg.strokeOpacity ?? 1,
+                            color: clipCfg.color ?? '#000000',
+                            widthMm: clipCfg.widthMm ?? 0.5,
+                            opacity: clipCfg.opacity ?? 1,
+                            dash: clipCfg.dash,
                             fill: clipCfg.fill ?? 'none',
                             fillOpacity: clipCfg.fillOpacity ?? 0
                         };
@@ -219,6 +225,8 @@ export const prepareViewports = (
                         if (worldPolygons.length) {
                             viewportClipPolygonsWorld[vp.id] = worldPolygons;
                             clipAllowedGids = new Set<string>();
+                            // pointInPolygon expects y — map polys ONCE, not per item.
+                            const worldPolygons2D = worldPolygons.map((poly) => poly.map((p) => ({ x: p.x, y: p.z })));
                             for (const item of sourceItems) {
                                 // Use item's direct x/z properties (same approach as labels)
                                 const ix = getProp(item, 'x');
@@ -227,11 +235,9 @@ export const prepareViewports = (
                                 if (!Number.isFinite(ix) || !Number.isFinite(iz)) {
                                     continue;
                                 }
-                                // Convert polygon {x,z} to {x,y} for pointInPolygon (same as labels do)
-                                const inside = worldPolygons.some((poly) => {
-                                    const polyWith2D = poly.map((p) => ({ x: p.x, y: p.z }));
-                                    return pointInPolygon(polyWith2D, ix as number, iz as number);
-                                });
+                                const inside = worldPolygons2D.some((poly) =>
+                                    pointInPolygon(poly, ix as number, iz as number)
+                                );
                                 if (inside) {
                                     const gid = getProp(item, 'gid') ?? getProp(item, 'id');
                                     if (gid !== null && gid !== undefined) {
@@ -264,16 +270,18 @@ export const prepareViewports = (
 
         const hlStyles = hlCfg
             ? {
-                  stroke: typeof hlCfg.stroke === 'string' ? hlCfg.stroke : '#ff0000',
-                  strokeWidthMm: typeof hlCfg.strokeWidthMm === 'number' ? hlCfg.strokeWidthMm : 0.5,
-                  strokeOpacity: typeof hlCfg.strokeOpacity === 'number' ? hlCfg.strokeOpacity : 1,
+                  color: typeof hlCfg.color === 'string' ? hlCfg.color : '#ff0000',
+                  widthMm: typeof hlCfg.widthMm === 'number' ? hlCfg.widthMm : 0.5,
+                  opacity: typeof hlCfg.opacity === 'number' ? hlCfg.opacity : 1,
+                  dash: typeof hlCfg.dash === 'string' ? hlCfg.dash : undefined,
                   fill: typeof hlCfg.fill === 'string' ? hlCfg.fill : '#ffff00',
                   fillOpacity: typeof hlCfg.fillOpacity === 'number' ? hlCfg.fillOpacity : 0.5
               }
             : {
-                  stroke: undefined,
-                  strokeWidthMm: undefined,
-                  strokeOpacity: undefined,
+                  color: undefined,
+                  widthMm: undefined,
+                  opacity: undefined,
+                  dash: undefined,
                   fill: undefined,
                   fillOpacity: undefined
               };
@@ -291,6 +299,16 @@ export const prepareViewports = (
         addFilterClasses(hlCfg?.class);
         addFilterClasses(clipCfg?.class);
 
+        // gid-based features (highlight, clip include/exclude, includeClasses)
+        // require rawPaths with per-product meta — filterModelForViewport
+        // returns the model UNTOUCHED without them, so warn instead of
+        // silently rendering as if the config didn't exist.
+        if (baseModel && !baseModel.rawPaths?.length && (vp.highlight || vp.clip || vp.includeClasses)) {
+            pushWarning(
+                options.warnings,
+                `Viewport '${vp.id}' declares highlight/clip/includeClasses but its model has no rawPaths with per-product metadata — these settings will have no effect.`
+            );
+        }
         const model = baseModel
             ? filterModelForViewport(
                   baseModel,