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

package/src/layout/index.ts

@@ -1,671 +1,671 @@
-import type { SectionRenderState } from '@twinfinity/geometry';
-import defaultTemplateJson from '../templates/default-template.json';
-import {
-    pointInPolygon,
-    filterItemsInPolygons,
-    filterEntriesByClip,
-    offsetPolygons,
-    projectPolygonsToLocal
-} from './clipUtils';
-import { uniquePositiveDenoms } from './utils';
-import { validateLayoutTemplate as validateLayoutTemplateExternal } from './validation';
-import { renderViewportElement } from './viewportRender';
-import { prepareViewports } from './viewportPrep';
-import { renderLabels, ViewportRenderInfo } from './labelsRender';
-import { renderQrElements } from './qrRender';
-import { applyLegendFilter, buildLegendGroup } from './legendRender';
-import { RenderLayoutOptions } from './options';
-import { resolvePresets } from './presets';
-import { pushWarning } from './warnings';
-import { escapeAttr, escapeText, interpolate, getPathValue } from './renderUtils';
-import { validateSectionState } from './sectionValidation';
-import {
-    ELEMENT_KIND_VIEWPORT,
-    ELEMENT_KIND_TEXT,
-    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,
-    ELEMENT_KIND_LEGEND,
-    ELEMENT_KIND_GROUP
-} from './elementKinds';
-import {
-    AssetSpec,
-    LayoutElement,
-    ViewportElement,
-    TextElement,
-    ImageElement,
-    LineElement,
-    RectElement,
-    CircleElement,
-    PolylineElement,
-    PolygonElement,
-    ScaleBarElement,
-    QrElement,
-    LabelsElement,
-    LegendElement,
-    GroupElement,
-    LayoutTemplate,
-    ModelContext,
-    LayoutData,
-    ValidationIssue,
-    ComputedViewportScale
-} from './types';
-
-export type LayoutDataValidationResult =
-    | { ok: true }
-    | {
-          ok: false;
-          errors: string[];
-      };
-
-export type PreflightResult =
-    | { ok: true }
-    | {
-          ok: false;
-          templateErrors?: ValidationIssue[];
-          dataErrors?: string[];
-          sectionErrors?: string[];
-      };
-
-import { isRecord, getProp } from './typeGuards';
-
-/**
- * Validate template, layout data, and section state in a single call.
- * Combines `validateLayoutTemplate`, `validateLayoutData`, and `validateSectionState`.
- */
-export const preflight = (
-    template: LayoutTemplate,
-    data: unknown,
-    expectedViewportIds: string[],
-    sectionState?: SectionRenderState
-): PreflightResult => {
-    const templateValidation = validateLayoutTemplate(template);
-    const dataValidation = validateLayoutData(data, expectedViewportIds);
-    const sectionValidation = sectionState ? validateSectionState(sectionState) : { ok: true as const };
-
-    const ok = templateValidation.ok && dataValidation.ok && sectionValidation.ok;
-    if (ok) return { ok: true };
-
-    return {
-        ok: false,
-        templateErrors: templateValidation.ok ? undefined : templateValidation.errors,
-        dataErrors: dataValidation.ok ? undefined : dataValidation.errors,
-        sectionErrors: sectionValidation.ok ? undefined : sectionValidation.errors
-    };
-};
-
-/**
- * Validate layout data before rendering to catch missing propertySets or items arrays.
- */
-export const validateLayoutData = (data: unknown, expectedViewportIds: string[]): LayoutDataValidationResult => {
-    const errors: string[] = [];
-    if (!isRecord(data)) {
-        return { ok: false, errors: ['layout data must be an object'] };
-    }
-    expectedViewportIds.forEach((vpId) => {
-        const viewports = getProp(data, 'viewports');
-        const viewport = isRecord(viewports) ? getProp(viewports, vpId) : undefined;
-        const items = getProp(viewport, 'items');
-        if (!Array.isArray(items)) {
-            errors.push(`viewports.${vpId}.items is required and must be an array.`);
-            return;
-        }
-        items.forEach((it: unknown, idx: number) => {
-            if (!isRecord(it)) {
-                errors.push(`viewports.${vpId}.items[${idx}] must be an object.`);
-                return;
-            }
-            const sets = getProp(it, 'propertySets');
-            if (!isRecord(sets)) {
-                errors.push(`viewports.${vpId}.items[${idx}] is missing propertySets.<Set>.<Prop>.value.`);
-                return;
-            }
-            Object.entries(sets).forEach(([setName, props]) => {
-                if (!isRecord(props)) {
-                    errors.push(`viewports.${vpId}.items[${idx}].propertySets.${setName} must be an object.`);
-                    return;
-                }
-                Object.entries(props).forEach(([propName, payload]) => {
-                    if (!isRecord(payload) || !('value' in payload)) {
-                        errors.push(
-                            `viewports.${vpId}.items[${idx}].propertySets.${setName}.${propName} must include a value (propertySets.<Set>.<Prop>.value).`
-                        );
-                    }
-                });
-            });
-        });
-    });
-    return errors.length ? { ok: false, errors } : { ok: true };
-};
-
-export type {
-    PageSpec,
-    TextStyle,
-    StyleMap,
-    AssetSpec,
-    LayoutElement,
-    BaseElement,
-    ViewportElement,
-    TextElement,
-    ImageElement,
-    LineElement,
-    RectElement,
-    CircleElement,
-    PolylineElement,
-    PolygonElement,
-    PointMm,
-    ScaleBarElement,
-    QrElement,
-    LabelsElement,
-    LegendElement,
-    GroupElement,
-    LayoutTemplate,
-    LegendAnchor,
-    LegendColumn,
-    SvgModelView,
-    ModelContext,
-    LayoutData,
-    LayoutDataViewports,
-    ViewportItemsMap,
-    PagePresetKey,
-    PageOrientation,
-    ValidationOptions,
-    ValidationIssue,
-    ValidationResult,
-    ComputedViewportScale,
-    NormalizedProductItem,
-    SectionStateValidationResult,
-    LabelStyle,
-    WhereCondition,
-    ClipConfig,
-    HighlightConfig,
-    ViewportLineStyle,
-    ViewportLineStyles,
-    SectionResult,
-    FillRule,
-    RenderDrawingInput,
-    RenderDrawingResult,
-    IncludeClassesFilter,
-    ResolvedIncludeFilter,
-    TemplateVariableDef,
-    TemplateVariableInfo
-} from './types';
-
-export type { RenderLayoutOptions } from './options';
-
-const validateLayoutTemplate = validateLayoutTemplateExternal;
-
-export { pointInPolygon, filterItemsInPolygons, filterEntriesByClip, offsetPolygons, projectPolygonsToLocal };
-/** Normalize IFC class names to lowercase for consistent matching. */
-export { normalizeClass } from './filters';
-/** Test whether an item matches a class + where filter (used by clip, highlight, labels, legend). */
-export { matchesV2Filter } from './filters';
-/** Metadata utilities: build lookup maps, resolve IFC class includes, and merge metadata sources. */
-export {
-    buildMetadataMap,
-    normalizePropertySets,
-    resolveIfcClassName,
-    resolveIfcClassId,
-    resolveIncludeClasses,
-    resolveAllowedClasses,
-    resolveMeta
-} from './metadata';
-/** Validate a layout template JSON structure. Returns `{ ok, errors }` or `{ ok, template }`. */
-export { validateLayoutTemplate as validateLayoutTemplateExternal } from './validation';
-/** Layout utility functions: scale denominators, label sizing, color parsing, and line style application. */
-export { uniquePositiveDenoms, computeLabelFontSize, colorFromString, applyLineStyleToPaths } from './utils';
-/** Property resolution: traverse nested objects with dot-path strings like `"BIP.spacename"`. */
-export { getPathValue, resolveProperty, resolvePath, matchesPropertyFilter } from './renderUtils';
-
-const SVG_NS = 'http://www.w3.org/2000/svg';
-
-/** Build legend table rows from product items with property formatting. */
-export { buildLegendRows, type LegendRow, type LegendRowOptions } from './legendRows';
-/** Product normalization, viewport item builders, and section-state-to-SVG-model conversion. */
-export type { ProductLike, BuildViewportItemsOptions } from './itemBuilders';
-export { normalizeProductEntry, buildViewportItems, sectionStateToModelView } from './itemBuilders';
-/**
- * High-level facade: renders a complete drawing from a template + section geometry.
- * Internalizes all data wiring (items, colors, labels, metadata) that `renderLayout` requires manually.
- */
-export {
-    renderDrawing,
-    resolveFillColor,
-    BUILTIN_LINE_DEFAULTS,
-    BUILTIN_HIDDEN_DEFAULTS,
-    BUILTIN_LABEL_DEFAULTS,
-    CATEGORY_BUILTIN_OVERRIDES,
-    setRenderLayoutBinding
-} from './renderDrawing';
-export type { ResolvedLineStyles } from './renderDrawing';
-
-export { EXAMPLE_BUILDING_CLASSES } from './presets';
-
-export { analyzeTemplate } from './analyzeTemplate';
-export type { TemplateRequirements } from './analyzeTemplate';
-
-/** Drawing export utilities: convert SVG markup to PDF or SVG files. */
-export { exportToPdf, exportToSvg } from './exportDrawing';
-export type { ExportPdfOptions, ExportSvgOptions } from './exportDrawing';
-
-/** Template variable utilities: extract, validate, and resolve template parameters. */
-export {
-    getTemplateVariables,
-    getTemplateDefaults,
-    resolveTemplateValues,
-    applyTemplateVariables
-} from './templateVariables';
-
-/** Result of {@link renderLayout}: the final SVG markup, per-viewport scale info, and any warnings. */
-export interface RenderLayoutResult {
-    /** Complete SVG markup string ready for embedding or PDF conversion. */
-    svg: string;
-    /** Per-viewport computed scale information (denominator, mm-per-model-unit, fit status). */
-    viewportScales: Record<string, ComputedViewportScale>;
-    /** Non-fatal issues encountered during rendering (missing assets, unresolved styles, etc.). */
-    warnings: string[];
-}
-
-/** Built-in default layout template (A3 landscape with a single viewport). */
-export const DEFAULT_LAYOUT_TEMPLATE = defaultTemplateJson as LayoutTemplate;
-
-const dashArray = (dashed?: boolean): string => (dashed ? ' stroke-dasharray="4 2"' : '');
-
-const formatNumber = (value: number): number => {
-    if (!Number.isFinite(value)) return 0;
-    return Number.parseFloat(value.toFixed(3));
-};
-
-/**
- * Render a layout template to SVG.
- *
- * This is the low-level rendering function. For most use cases, prefer {@link renderDrawing}
- * which handles all data wiring automatically.
- *
- * @param template - Validated layout template (page, elements, styles, presets).
- * @param data - Layout data with viewport items, template variables, and legend rows.
- * @param models - Per-viewport SVG model views (geometry + transforms).
- * @param options - Optional rendering settings (remote assets, scale overrides, metadata).
- * @returns SVG markup string, computed viewport scales, and any warnings.
- */
-export async function renderLayout(
-    template: LayoutTemplate,
-    data: LayoutData,
-    models: ModelContext,
-    options?: RenderLayoutOptions
-): Promise<RenderLayoutResult> {
-    const presets = resolvePresets(template?.presets);
-
-    const validation = validateLayoutTemplate(template, {
-        allowRemoteAssets: options?.allowRemoteAssets,
-        allowDataUrls: options?.allowDataUrls,
-        maxViewports: options?.maxViewports
-    });
-    if (!validation.ok) {
-        throw new Error(
-            `Template validation failed: ${validation.errors.map((e: ValidationIssue) => `${e.path}: ${e.message}`).join('; ')}`
-        );
-    }
-
-    const preferredScales = uniquePositiveDenoms(options?.scaleDenominators);
-    const page = template.page;
-    const warnings: string[] = [];
-
-    // Flatten all elements to collect viewports, qrs, labels, legends regardless of grouping
-    const allElements: LayoutElement[] = [];
-    const collectElements = (elements: LayoutElement[]): void => {
-        elements.forEach((el) => {
-            allElements.push(el);
-            if (el.kind === ELEMENT_KIND_GROUP) {
-                collectElements((el as GroupElement).children);
-            }
-        });
-    };
-    collectElements(template.elements);
-
-    const viewports = allElements.filter((el) => el.kind === ELEMENT_KIND_VIEWPORT) as ViewportElement[];
-
-    const dataValidation = validateLayoutData(
-        data,
-        viewports.map((v) => v.id)
-    );
-    if (!dataValidation.ok) {
-        throw new Error(`Layout data validation failed: ${dataValidation.errors.join('; ')}`);
-    }
-
-    const {
-        viewportScales,
-        viewportClipPolygonsLocal,
-        viewportClipPolygonsWorld,
-        viewportClipBounds,
-        viewportClipLabels,
-        viewportClipStyles,
-        // viewportClipWhere intentionally omitted — not needed for rendering
-        viewportHighlight,
-        filteredModelsByViewport
-    } = prepareViewports(viewports, models, data, preferredScales, presets, {
-        metadataById: options?.metadataById,
-        warnings
-    });
-
-    const viewportData: Record<
-        string,
-        {
-            scaleDenom: number;
-            scaleText: string;
-            mmPerModelUnit: number;
-            fits: boolean;
-        }
-    > = {};
-
-    Object.entries(viewportScales).forEach(([id, scale]) => {
-        viewportData[id] = {
-            scaleDenom: scale.denom,
-            scaleText: `1:${scale.denom}`,
-            mmPerModelUnit: scale.mmPerModelUnit,
-            fits: scale.fits
-        };
-    });
-
-    const dataWithViewport = { ...data, viewport: viewportData };
-
-    const sorted = [...template.elements].sort((a, b) => (a.zIndex ?? 0) - (b.zIndex ?? 0));
-
-    const parts: string[] = [];
-    parts.push(
-        `<svg xmlns="${SVG_NS}" width="${page.widthMm}mm" height="${page.heightMm}mm" viewBox="0 0 ${page.widthMm} ${page.heightMm}">`
-    );
-
-    if (page.backgroundColor) {
-        parts.push(
-            `<rect x="0" y="0" width="${page.widthMm}" height="${page.heightMm}" fill="${escapeAttr(page.backgroundColor)}"/>`
-        );
-    }
-
-    const assetMap = new Map<string, AssetSpec>();
-    (template.assets ?? []).forEach((asset) => assetMap.set(asset.id, asset));
-
-    const qrElements = allElements.filter((el) => el.kind === ELEMENT_KIND_QR) as QrElement[];
-    const labelElements = allElements.filter((el) => el.kind === ELEMENT_KIND_LABELS) as LabelsElement[];
-    const viewportRenderInfo: Record<string, ViewportRenderInfo> = {};
-
-    // Pre-process legends to collect color maps (needed before viewport rendering)
-    const legendColorMaps = new Map<string, Map<string, string>>(); // viewport ID -> color map
-    const legendElements = allElements.filter((el) => el.kind === ELEMENT_KIND_LEGEND) as LegendElement[];
-    legendElements.forEach((legend) => {
-        if (legend.assignColors?.enabled && legend.groupBy) {
-            const legendItems = getPathValue(data, `viewports.${legend.viewport}.items`);
-            const rawLegendItems = Array.isArray(legendItems) ? legendItems : [];
-            const legendDataFiltered = applyLegendFilter(
-                rawLegendItems,
-                legend,
-                viewports,
-                viewportClipPolygonsLocal,
-                viewportRenderInfo
-            );
-            if (legendDataFiltered && legendDataFiltered.length) {
-                const vpEl = viewports.find((v) => v.id === legend.viewport);
-                const fillOpacity = vpEl?.fills?.length ? (vpEl.fills[0].fillOpacity ?? 0.35) : undefined;
-                const result = buildLegendGroup(
-                    legend,
-                    template.styles,
-                    page,
-                    page.marginMm,
-                    legendDataFiltered,
-                    fillOpacity
-                );
-                if (result?.colorMap) {
-                    legendColorMaps.set(legend.viewport, result.colorMap);
-                    console.log(
-                        `[LEGEND PRE-PROCESS] Stored color map for viewport "${legend.viewport}": ${result.colorMap.size} colors`
-                    );
-                }
-            }
-        }
-    });
-
-    sorted.forEach((el) => {
-        if (el.kind === ELEMENT_KIND_RECT) {
-            const r = el as RectElement;
-            parts.push(
-                `<rect x="${r.xMm}" y="${r.yMm}" width="${r.widthMm}" height="${r.heightMm}"` +
-                    (r.stroke ? ` stroke="${escapeAttr(r.stroke)}"` : '') +
-                    (r.strokeWidthMm ? ` stroke-width="${r.strokeWidthMm}"` : '') +
-                    (r.fill ? ` fill="${escapeAttr(r.fill)}"` : ' fill="none"') +
-                    dashArray(r.dashed) +
-                    ` />`
-            );
-        } else if (el.kind === ELEMENT_KIND_LINE) {
-            const l = el as LineElement;
-            parts.push(
-                `<line x1="${l.x1Mm}" y1="${l.y1Mm}" x2="${l.x2Mm}" y2="${l.y2Mm}"` +
-                    (l.stroke ? ` stroke="${escapeAttr(l.stroke)}"` : '') +
-                    (l.strokeWidthMm ? ` stroke-width="${l.strokeWidthMm}"` : '') +
-                    dashArray(l.dashed) +
-                    ` />`
-            );
-        } else if (el.kind === ELEMENT_KIND_CIRCLE) {
-            const c = el as CircleElement;
-            parts.push(
-                `<circle cx="${c.cxMm}" cy="${c.cyMm}" r="${c.rMm}"` +
-                    (c.stroke ? ` stroke="${escapeAttr(c.stroke)}"` : '') +
-                    (c.strokeWidthMm ? ` stroke-width="${c.strokeWidthMm}"` : '') +
-                    (c.fill ? ` fill="${escapeAttr(c.fill)}"` : ' fill="none"') +
-                    dashArray(c.dashed) +
-                    ` />`
-            );
-        } else if (el.kind === ELEMENT_KIND_POLYLINE) {
-            const pl = el as PolylineElement;
-            const pointsStr = pl.points.map((p) => `${formatNumber(p.xMm)},${formatNumber(p.yMm)}`).join(' ');
-            parts.push(
-                `<polyline points="${pointsStr}" stroke="${escapeAttr(pl.stroke)}" stroke-width="${pl.strokeWidthMm}" fill="none"${dashArray(pl.dashed)} />`
-            );
-        } else if (el.kind === ELEMENT_KIND_POLYGON) {
-            const pg = el as PolygonElement;
-            const pointsStr = pg.points.map((p) => `${formatNumber(p.xMm)},${formatNumber(p.yMm)}`).join(' ');
-            parts.push(
-                `<polygon points="${pointsStr}"` +
-                    (pg.stroke ? ` stroke="${escapeAttr(pg.stroke)}"` : '') +
-                    (pg.strokeWidthMm ? ` stroke-width="${pg.strokeWidthMm}"` : '') +
-                    (pg.fill ? ` fill="${escapeAttr(pg.fill)}"` : ' fill="none"') +
-                    dashArray(pg.dashed) +
-                    ` />`
-            );
-        } else if (el.kind === ELEMENT_KIND_TEXT) {
-            const tEl = el as TextElement;
-            const styleName = tEl.textStyle;
-            const style = styleName ? template.styles?.[styleName] : undefined;
-            if (!style) {
-                pushWarning(warnings, `Missing text style '${styleName ?? '(none)'}' for element '${tEl.id}'.`);
-                return;
-            }
-            const text = interpolate(tEl.text, dataWithViewport, warnings);
-            const anchor = tEl.align === 'center' ? 'middle' : tEl.align === 'right' ? 'end' : 'start';
-            parts.push(
-                `<text x="${tEl.xMm}" y="${tEl.yMm}" font-family="${escapeAttr(style.fontFamily)}" font-size="${style.fontSizeMm}"` +
-                    (style.fontWeight ? ` font-weight="${escapeAttr(style.fontWeight)}"` : '') +
-                    (style.color ? ` fill="${escapeAttr(style.color)}"` : '') +
-                    (style.letterSpacingMm !== undefined ? ` letter-spacing="${style.letterSpacingMm}"` : '') +
-                    (style.lineHeightMm !== undefined ? ` line-height="${style.lineHeightMm}"` : '') +
-                    ` text-anchor="${anchor}">${escapeText(text)}</text>`
-            );
-        } else if (el.kind === ELEMENT_KIND_IMAGE) {
-            const img = el as ImageElement;
-            const asset = assetMap.get(img.assetId);
-            if (!asset) {
-                pushWarning(warnings, `Missing asset '${img.assetId}' for image '${img.id}'.`);
-                return;
-            }
-            if (asset.src) {
-                parts.push(
-                    `<image href="${escapeAttr(asset.src)}" x="${img.xMm}" y="${img.yMm}" width="${img.widthMm}" height="${img.heightMm}"` +
-                        (img.fit === 'cover'
-                            ? ' preserveAspectRatio="xMidYMid slice"'
-                            : img.fit === 'stretch'
-                              ? ' preserveAspectRatio="none"'
-                              : ' preserveAspectRatio="xMidYMid meet"') +
-                        ` />`
-                );
-            } else if (asset.content) {
-                parts.push(
-                    `<g transform="translate(${img.xMm} ${img.yMm}) scale(${img.widthMm} ${img.heightMm})">${asset.content}</g>`
-                );
-            }
-        } else if (el.kind === ELEMENT_KIND_SCALE_BAR) {
-            const sb = el as ScaleBarElement;
-            // Scale bar declares which viewport it binds to via `viewport`
-            const boundViewport = sb.viewport ?? viewports[0]?.id ?? null;
-            if (!boundViewport) {
-                pushWarning(warnings, `Scale bar '${sb.id}' is not bound to a viewport.`);
-                return;
-            }
-            const scaleInfo = viewportScales[boundViewport];
-            if (!scaleInfo) {
-                pushWarning(warnings, `Viewport '${boundViewport}' missing scale info for scale bar '${sb.id}'.`);
-                return;
-            }
-            const lengthMm = sb.maxLengthMm;
-            const segments = sb.segments ?? 10;
-            const segmentMm = lengthMm / segments;
-            const metersPerMm = 1 / scaleInfo.mmPerModelUnit;
-            const segmentMeters = segmentMm * metersPerMm;
-            const labelsEvery = Math.max(1, sb.labelEvery ?? 1);
-            const unitSuffix = sb.unit ? ` ${sb.unit}` : ' m';
-            const barParts: string[] = [];
-            const sbStroke = sb.stroke ?? '#000';
-            const sbStrokeWidth = sb.strokeWidthMm ?? 0.5;
-
-            for (let i = 0; i <= segments; i++) {
-                const x = sb.xMm + segmentMm * i;
-                const isLabel = i % labelsEvery === 0;
-                const height = isLabel ? 4 : 3;
-                barParts.push(
-                    `<line x1="${x}" y1="${sb.yMm}" x2="${x}" y2="${sb.yMm - height}" stroke="${escapeAttr(
-                        sbStroke
-                    )}" stroke-width="${sbStrokeWidth}" />`
-                );
-                if (isLabel && sb.textStyle) {
-                    const style = template.styles?.[sb.textStyle];
-                    if (style) {
-                        const labelValue = (segmentMeters * i).toFixed(2).replace(/\.?0+$/, '');
-                        barParts.push(
-                            `<text x="${x}" y="${sb.yMm + style.fontSizeMm + 1}" font-family="${escapeAttr(
-                                style.fontFamily
-                            )}" font-size="${style.fontSizeMm}" text-anchor="middle">${escapeText(labelValue + unitSuffix)}</text>`
-                        );
-                    }
-                }
-            }
-
-            barParts.push(
-                `<line x1="${sb.xMm}" y1="${sb.yMm}" x2="${sb.xMm + lengthMm}" y2="${sb.yMm}" stroke="${escapeAttr(
-                    sbStroke
-                )}" stroke-width="${sbStrokeWidth}" />`
-            );
-
-            parts.push(barParts.join(''));
-        } else if (el.kind === ELEMENT_KIND_VIEWPORT) {
-            const vp = el as ViewportElement;
-            const model = filteredModelsByViewport[vp.id] ?? models[vp.id] ?? null;
-            if (!model) {
-                pushWarning(warnings, `Viewport '${vp.id}' missing model.`);
-            }
-            const vpParts = renderViewportElement(
-                vp,
-                model,
-                dataWithViewport,
-                preferredScales,
-                presets.scales,
-                assetMap,
-                viewportScales,
-                viewportClipPolygonsLocal,
-                viewportClipBounds,
-                viewportClipLabels,
-                viewportClipStyles,
-                viewportHighlight,
-                viewportRenderInfo,
-                warnings,
-                legendColorMaps
-            );
-            parts.push(...vpParts);
-        } else if (el.kind === ELEMENT_KIND_LEGEND) {
-            const legend = el as LegendElement;
-            const legendItems = getPathValue(data, `viewports.${legend.viewport}.items`);
-            const rawLegendItems = Array.isArray(legendItems) ? legendItems : [];
-            const legendDataFiltered = applyLegendFilter(
-                rawLegendItems,
-                legend,
-                viewports,
-                viewportClipPolygonsLocal,
-                viewportRenderInfo
-            );
-            if (!legendDataFiltered || !legendDataFiltered.length) {
-                if (!rawLegendItems.length) {
-                    pushWarning(warnings, `Legend '${legend.id}' has no items from viewport '${legend.viewport}'.`);
-                } else {
-                    pushWarning(
-                        warnings,
-                        `Legend '${legend.id}' filter matched 0 of ${rawLegendItems.length} items (class=${JSON.stringify(legend.class)}, where=${JSON.stringify(legend.where)}).`
-                    );
-                }
-            }
-            const vpEl = viewports.find((v) => v.id === legend.viewport);
-            // Derive swatch opacity from viewport fill rules (first matching rule's opacity)
-            const fillOpacity = vpEl?.fills?.length ? (vpEl.fills[0].fillOpacity ?? 0.35) : undefined;
-            const legendResult = buildLegendGroup(
-                legend,
-                template.styles,
-                page,
-                page.marginMm,
-                legendDataFiltered || [],
-                fillOpacity
-            );
-            if (legendResult) {
-                parts.push(legendResult.svg);
-            }
-        }
-    });
-
-    if (labelElements.length) {
-        const labelParts = renderLabels(
-            labelElements,
-            data,
-            viewportRenderInfo,
-            viewportClipLabels,
-            viewportClipPolygonsLocal,
-            viewportClipPolygonsWorld,
-            template.styles ?? {},
-            dataWithViewport,
-            warnings
-        );
-        parts.push(...labelParts);
-    }
-
-    if (qrElements.length) {
-        const qrParts = await renderQrElements(
-            qrElements,
-            viewports,
-            viewportScales,
-            models,
-            { qrContext: options?.qrContext },
-            dataWithViewport,
-            warnings
-        );
-        parts.push(...qrParts);
-    }
-
-    parts.push('</svg>');
-
-    return { svg: parts.join(''), viewportScales, warnings };
-}
-
-// Register renderLayout with renderDrawing to break the circular dependency.
-// This runs at module evaluation time — safe because renderLayout is defined above.
-import { setRenderLayoutBinding as _setBinding } from './renderDrawing';
-_setBinding(renderLayout as any);
+import type { SectionRenderState } from '@twinfinity/geometry';
+import defaultTemplateJson from '../templates/default-template.json';
+import {
+    pointInPolygon,
+    filterItemsInPolygons,
+    filterEntriesByClip,
+    offsetPolygons,
+    projectPolygonsToLocal
+} from './clipUtils';
+import { uniquePositiveDenoms } from './utils';
+import { validateLayoutTemplate as validateLayoutTemplateExternal } from './validation';
+import { renderViewportElement } from './viewportRender';
+import { prepareViewports } from './viewportPrep';
+import { renderLabels, ViewportRenderInfo } from './labelsRender';
+import { renderQrElements } from './qrRender';
+import { applyLegendFilter, buildLegendGroup } from './legendRender';
+import { RenderLayoutOptions } from './options';
+import { resolvePresets } from './presets';
+import { pushWarning } from './warnings';
+import { escapeAttr, escapeText, interpolate, getPathValue } from './renderUtils';
+import { validateSectionState } from './sectionValidation';
+import {
+    ELEMENT_KIND_VIEWPORT,
+    ELEMENT_KIND_TEXT,
+    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,
+    ELEMENT_KIND_LEGEND,
+    ELEMENT_KIND_GROUP
+} from './elementKinds';
+import {
+    AssetSpec,
+    LayoutElement,
+    ViewportElement,
+    TextElement,
+    ImageElement,
+    LineElement,
+    RectElement,
+    CircleElement,
+    PolylineElement,
+    PolygonElement,
+    ScaleBarElement,
+    QrElement,
+    LabelsElement,
+    LegendElement,
+    GroupElement,
+    LayoutTemplate,
+    ModelContext,
+    LayoutData,
+    ValidationIssue,
+    ComputedViewportScale
+} from './types';
+
+export type LayoutDataValidationResult =
+    | { ok: true }
+    | {
+          ok: false;
+          errors: string[];
+      };
+
+export type PreflightResult =
+    | { ok: true }
+    | {
+          ok: false;
+          templateErrors?: ValidationIssue[];
+          dataErrors?: string[];
+          sectionErrors?: string[];
+      };
+
+import { isRecord, getProp } from './typeGuards';
+
+/**
+ * Validate template, layout data, and section state in a single call.
+ * Combines `validateLayoutTemplate`, `validateLayoutData`, and `validateSectionState`.
+ */
+export const preflight = (
+    template: LayoutTemplate,
+    data: unknown,
+    expectedViewportIds: string[],
+    sectionState?: SectionRenderState
+): PreflightResult => {
+    const templateValidation = validateLayoutTemplate(template);
+    const dataValidation = validateLayoutData(data, expectedViewportIds);
+    const sectionValidation = sectionState ? validateSectionState(sectionState) : { ok: true as const };
+
+    const ok = templateValidation.ok && dataValidation.ok && sectionValidation.ok;
+    if (ok) return { ok: true };
+
+    return {
+        ok: false,
+        templateErrors: templateValidation.ok ? undefined : templateValidation.errors,
+        dataErrors: dataValidation.ok ? undefined : dataValidation.errors,
+        sectionErrors: sectionValidation.ok ? undefined : sectionValidation.errors
+    };
+};
+
+/**
+ * Validate layout data before rendering to catch missing propertySets or items arrays.
+ */
+export const validateLayoutData = (data: unknown, expectedViewportIds: string[]): LayoutDataValidationResult => {
+    const errors: string[] = [];
+    if (!isRecord(data)) {
+        return { ok: false, errors: ['layout data must be an object'] };
+    }
+    expectedViewportIds.forEach((vpId) => {
+        const viewports = getProp(data, 'viewports');
+        const viewport = isRecord(viewports) ? getProp(viewports, vpId) : undefined;
+        const items = getProp(viewport, 'items');
+        if (!Array.isArray(items)) {
+            errors.push(`viewports.${vpId}.items is required and must be an array.`);
+            return;
+        }
+        items.forEach((it: unknown, idx: number) => {
+            if (!isRecord(it)) {
+                errors.push(`viewports.${vpId}.items[${idx}] must be an object.`);
+                return;
+            }
+            const sets = getProp(it, 'propertySets');
+            if (!isRecord(sets)) {
+                errors.push(`viewports.${vpId}.items[${idx}] is missing propertySets.<Set>.<Prop>.value.`);
+                return;
+            }
+            Object.entries(sets).forEach(([setName, props]) => {
+                if (!isRecord(props)) {
+                    errors.push(`viewports.${vpId}.items[${idx}].propertySets.${setName} must be an object.`);
+                    return;
+                }
+                Object.entries(props).forEach(([propName, payload]) => {
+                    if (!isRecord(payload) || !('value' in payload)) {
+                        errors.push(
+                            `viewports.${vpId}.items[${idx}].propertySets.${setName}.${propName} must include a value (propertySets.<Set>.<Prop>.value).`
+                        );
+                    }
+                });
+            });
+        });
+    });
+    return errors.length ? { ok: false, errors } : { ok: true };
+};
+
+export type {
+    PageSpec,
+    TextStyle,
+    StyleMap,
+    AssetSpec,
+    LayoutElement,
+    BaseElement,
+    ViewportElement,
+    TextElement,
+    ImageElement,
+    LineElement,
+    RectElement,
+    CircleElement,
+    PolylineElement,
+    PolygonElement,
+    PointMm,
+    ScaleBarElement,
+    QrElement,
+    LabelsElement,
+    LegendElement,
+    GroupElement,
+    LayoutTemplate,
+    LegendAnchor,
+    LegendColumn,
+    SvgModelView,
+    ModelContext,
+    LayoutData,
+    LayoutDataViewports,
+    ViewportItemsMap,
+    PagePresetKey,
+    PageOrientation,
+    ValidationOptions,
+    ValidationIssue,
+    ValidationResult,
+    ComputedViewportScale,
+    NormalizedProductItem,
+    SectionStateValidationResult,
+    LabelStyle,
+    WhereCondition,
+    ClipConfig,
+    HighlightConfig,
+    ViewportLineStyle,
+    ViewportLineStyles,
+    SectionResult,
+    FillRule,
+    RenderDrawingInput,
+    RenderDrawingResult,
+    IncludeClassesFilter,
+    ResolvedIncludeFilter,
+    TemplateVariableDef,
+    TemplateVariableInfo
+} from './types';
+
+export type { RenderLayoutOptions } from './options';
+
+const validateLayoutTemplate = validateLayoutTemplateExternal;
+
+export { pointInPolygon, filterItemsInPolygons, filterEntriesByClip, offsetPolygons, projectPolygonsToLocal };
+/** Normalize IFC class names to lowercase for consistent matching. */
+export { normalizeClass } from './filters';
+/** Test whether an item matches a class + where filter (used by clip, highlight, labels, legend). */
+export { matchesV2Filter } from './filters';
+/** Metadata utilities: build lookup maps, resolve IFC class includes, and merge metadata sources. */
+export {
+    buildMetadataMap,
+    normalizePropertySets,
+    resolveIfcClassName,
+    resolveIfcClassId,
+    resolveIncludeClasses,
+    resolveAllowedClasses,
+    resolveMeta
+} from './metadata';
+/** Validate a layout template JSON structure. Returns `{ ok, errors }` or `{ ok, template }`. */
+export { validateLayoutTemplate as validateLayoutTemplateExternal } from './validation';
+/** Layout utility functions: scale denominators, label sizing, color parsing, and line style application. */
+export { uniquePositiveDenoms, computeLabelFontSize, colorFromString, applyLineStyleToPaths } from './utils';
+/** Property resolution: traverse nested objects with dot-path strings like `"BIP.spacename"`. */
+export { getPathValue, resolveProperty, resolvePath, matchesPropertyFilter } from './renderUtils';
+
+const SVG_NS = 'http://www.w3.org/2000/svg';
+
+/** Build legend table rows from product items with property formatting. */
+export { buildLegendRows, type LegendRow, type LegendRowOptions } from './legendRows';
+/** Product normalization, viewport item builders, and section-state-to-SVG-model conversion. */
+export type { ProductLike, BuildViewportItemsOptions } from './itemBuilders';
+export { normalizeProductEntry, buildViewportItems, sectionStateToModelView } from './itemBuilders';
+/**
+ * High-level facade: renders a complete drawing from a template + section geometry.
+ * Internalizes all data wiring (items, colors, labels, metadata) that `renderLayout` requires manually.
+ */
+export {
+    renderDrawing,
+    resolveFillColor,
+    BUILTIN_LINE_DEFAULTS,
+    BUILTIN_HIDDEN_DEFAULTS,
+    BUILTIN_LABEL_DEFAULTS,
+    CATEGORY_BUILTIN_OVERRIDES,
+    setRenderLayoutBinding
+} from './renderDrawing';
+export type { ResolvedLineStyles } from './renderDrawing';
+
+export { EXAMPLE_BUILDING_CLASSES } from './presets';
+
+export { analyzeTemplate } from './analyzeTemplate';
+export type { TemplateRequirements } from './analyzeTemplate';
+
+/** Drawing export utilities: convert SVG markup to PDF or SVG files. */
+export { exportToPdf, exportToSvg } from './exportDrawing';
+export type { ExportPdfOptions, ExportSvgOptions } from './exportDrawing';
+
+/** Template variable utilities: extract, validate, and resolve template parameters. */
+export {
+    getTemplateVariables,
+    getTemplateDefaults,
+    resolveTemplateValues,
+    applyTemplateVariables
+} from './templateVariables';
+
+/** Result of {@link renderLayout}: the final SVG markup, per-viewport scale info, and any warnings. */
+export interface RenderLayoutResult {
+    /** Complete SVG markup string ready for embedding or PDF conversion. */
+    svg: string;
+    /** Per-viewport computed scale information (denominator, mm-per-model-unit, fit status). */
+    viewportScales: Record<string, ComputedViewportScale>;
+    /** Non-fatal issues encountered during rendering (missing assets, unresolved styles, etc.). */
+    warnings: string[];
+}
+
+/** Built-in default layout template (A3 landscape with a single viewport). */
+export const DEFAULT_LAYOUT_TEMPLATE = defaultTemplateJson as LayoutTemplate;
+
+const dashArray = (dashed?: boolean): string => (dashed ? ' stroke-dasharray="4 2"' : '');
+
+const formatNumber = (value: number): number => {
+    if (!Number.isFinite(value)) return 0;
+    return Number.parseFloat(value.toFixed(3));
+};
+
+/**
+ * Render a layout template to SVG.
+ *
+ * This is the low-level rendering function. For most use cases, prefer {@link renderDrawing}
+ * which handles all data wiring automatically.
+ *
+ * @param template - Validated layout template (page, elements, styles, presets).
+ * @param data - Layout data with viewport items, template variables, and legend rows.
+ * @param models - Per-viewport SVG model views (geometry + transforms).
+ * @param options - Optional rendering settings (remote assets, scale overrides, metadata).
+ * @returns SVG markup string, computed viewport scales, and any warnings.
+ */
+export async function renderLayout(
+    template: LayoutTemplate,
+    data: LayoutData,
+    models: ModelContext,
+    options?: RenderLayoutOptions
+): Promise<RenderLayoutResult> {
+    const presets = resolvePresets(template?.presets);
+
+    const validation = validateLayoutTemplate(template, {
+        allowRemoteAssets: options?.allowRemoteAssets,
+        allowDataUrls: options?.allowDataUrls,
+        maxViewports: options?.maxViewports
+    });
+    if (!validation.ok) {
+        throw new Error(
+            `Template validation failed: ${validation.errors.map((e: ValidationIssue) => `${e.path}: ${e.message}`).join('; ')}`
+        );
+    }
+
+    const preferredScales = uniquePositiveDenoms(options?.scaleDenominators);
+    const page = template.page;
+    const warnings: string[] = [];
+
+    // Flatten all elements to collect viewports, qrs, labels, legends regardless of grouping
+    const allElements: LayoutElement[] = [];
+    const collectElements = (elements: LayoutElement[]): void => {
+        elements.forEach((el) => {
+            allElements.push(el);
+            if (el.kind === ELEMENT_KIND_GROUP) {
+                collectElements((el as GroupElement).children);
+            }
+        });
+    };
+    collectElements(template.elements);
+
+    const viewports = allElements.filter((el) => el.kind === ELEMENT_KIND_VIEWPORT) as ViewportElement[];
+
+    const dataValidation = validateLayoutData(
+        data,
+        viewports.map((v) => v.id)
+    );
+    if (!dataValidation.ok) {
+        throw new Error(`Layout data validation failed: ${dataValidation.errors.join('; ')}`);
+    }
+
+    const {
+        viewportScales,
+        viewportClipPolygonsLocal,
+        viewportClipPolygonsWorld,
+        viewportClipBounds,
+        viewportClipLabels,
+        viewportClipStyles,
+        // viewportClipWhere intentionally omitted — not needed for rendering
+        viewportHighlight,
+        filteredModelsByViewport
+    } = prepareViewports(viewports, models, data, preferredScales, presets, {
+        metadataById: options?.metadataById,
+        warnings
+    });
+
+    const viewportData: Record<
+        string,
+        {
+            scaleDenom: number;
+            scaleText: string;
+            mmPerModelUnit: number;
+            fits: boolean;
+        }
+    > = {};
+
+    Object.entries(viewportScales).forEach(([id, scale]) => {
+        viewportData[id] = {
+            scaleDenom: scale.denom,
+            scaleText: `1:${scale.denom}`,
+            mmPerModelUnit: scale.mmPerModelUnit,
+            fits: scale.fits
+        };
+    });
+
+    const dataWithViewport = { ...data, viewport: viewportData };
+
+    const sorted = [...template.elements].sort((a, b) => (a.zIndex ?? 0) - (b.zIndex ?? 0));
+
+    const parts: string[] = [];
+    parts.push(
+        `<svg xmlns="${SVG_NS}" width="${page.widthMm}mm" height="${page.heightMm}mm" viewBox="0 0 ${page.widthMm} ${page.heightMm}">`
+    );
+
+    if (page.backgroundColor) {
+        parts.push(
+            `<rect x="0" y="0" width="${page.widthMm}" height="${page.heightMm}" fill="${escapeAttr(page.backgroundColor)}"/>`
+        );
+    }
+
+    const assetMap = new Map<string, AssetSpec>();
+    (template.assets ?? []).forEach((asset) => assetMap.set(asset.id, asset));
+
+    const qrElements = allElements.filter((el) => el.kind === ELEMENT_KIND_QR) as QrElement[];
+    const labelElements = allElements.filter((el) => el.kind === ELEMENT_KIND_LABELS) as LabelsElement[];
+    const viewportRenderInfo: Record<string, ViewportRenderInfo> = {};
+
+    // Pre-process legends to collect color maps (needed before viewport rendering)
+    const legendColorMaps = new Map<string, Map<string, string>>(); // viewport ID -> color map
+    const legendElements = allElements.filter((el) => el.kind === ELEMENT_KIND_LEGEND) as LegendElement[];
+    legendElements.forEach((legend) => {
+        if (legend.assignColors?.enabled && legend.groupBy) {
+            const legendItems = getPathValue(data, `viewports.${legend.viewport}.items`);
+            const rawLegendItems = Array.isArray(legendItems) ? legendItems : [];
+            const legendDataFiltered = applyLegendFilter(
+                rawLegendItems,
+                legend,
+                viewports,
+                viewportClipPolygonsLocal,
+                viewportRenderInfo
+            );
+            if (legendDataFiltered && legendDataFiltered.length) {
+                const vpEl = viewports.find((v) => v.id === legend.viewport);
+                const fillOpacity = vpEl?.fills?.length ? (vpEl.fills[0].fillOpacity ?? 0.35) : undefined;
+                const result = buildLegendGroup(
+                    legend,
+                    template.styles,
+                    page,
+                    page.marginMm,
+                    legendDataFiltered,
+                    fillOpacity
+                );
+                if (result?.colorMap) {
+                    legendColorMaps.set(legend.viewport, result.colorMap);
+                    console.log(
+                        `[LEGEND PRE-PROCESS] Stored color map for viewport "${legend.viewport}": ${result.colorMap.size} colors`
+                    );
+                }
+            }
+        }
+    });
+
+    sorted.forEach((el) => {
+        if (el.kind === ELEMENT_KIND_RECT) {
+            const r = el as RectElement;
+            parts.push(
+                `<rect x="${r.xMm}" y="${r.yMm}" width="${r.widthMm}" height="${r.heightMm}"` +
+                    (r.stroke ? ` stroke="${escapeAttr(r.stroke)}"` : '') +
+                    (r.strokeWidthMm ? ` stroke-width="${r.strokeWidthMm}"` : '') +
+                    (r.fill ? ` fill="${escapeAttr(r.fill)}"` : ' fill="none"') +
+                    dashArray(r.dashed) +
+                    ` />`
+            );
+        } else if (el.kind === ELEMENT_KIND_LINE) {
+            const l = el as LineElement;
+            parts.push(
+                `<line x1="${l.x1Mm}" y1="${l.y1Mm}" x2="${l.x2Mm}" y2="${l.y2Mm}"` +
+                    (l.stroke ? ` stroke="${escapeAttr(l.stroke)}"` : '') +
+                    (l.strokeWidthMm ? ` stroke-width="${l.strokeWidthMm}"` : '') +
+                    dashArray(l.dashed) +
+                    ` />`
+            );
+        } else if (el.kind === ELEMENT_KIND_CIRCLE) {
+            const c = el as CircleElement;
+            parts.push(
+                `<circle cx="${c.cxMm}" cy="${c.cyMm}" r="${c.rMm}"` +
+                    (c.stroke ? ` stroke="${escapeAttr(c.stroke)}"` : '') +
+                    (c.strokeWidthMm ? ` stroke-width="${c.strokeWidthMm}"` : '') +
+                    (c.fill ? ` fill="${escapeAttr(c.fill)}"` : ' fill="none"') +
+                    dashArray(c.dashed) +
+                    ` />`
+            );
+        } else if (el.kind === ELEMENT_KIND_POLYLINE) {
+            const pl = el as PolylineElement;
+            const pointsStr = pl.points.map((p) => `${formatNumber(p.xMm)},${formatNumber(p.yMm)}`).join(' ');
+            parts.push(
+                `<polyline points="${pointsStr}" stroke="${escapeAttr(pl.stroke)}" stroke-width="${pl.strokeWidthMm}" fill="none"${dashArray(pl.dashed)} />`
+            );
+        } else if (el.kind === ELEMENT_KIND_POLYGON) {
+            const pg = el as PolygonElement;
+            const pointsStr = pg.points.map((p) => `${formatNumber(p.xMm)},${formatNumber(p.yMm)}`).join(' ');
+            parts.push(
+                `<polygon points="${pointsStr}"` +
+                    (pg.stroke ? ` stroke="${escapeAttr(pg.stroke)}"` : '') +
+                    (pg.strokeWidthMm ? ` stroke-width="${pg.strokeWidthMm}"` : '') +
+                    (pg.fill ? ` fill="${escapeAttr(pg.fill)}"` : ' fill="none"') +
+                    dashArray(pg.dashed) +
+                    ` />`
+            );
+        } else if (el.kind === ELEMENT_KIND_TEXT) {
+            const tEl = el as TextElement;
+            const styleName = tEl.textStyle;
+            const style = styleName ? template.styles?.[styleName] : undefined;
+            if (!style) {
+                pushWarning(warnings, `Missing text style '${styleName ?? '(none)'}' for element '${tEl.id}'.`);
+                return;
+            }
+            const text = interpolate(tEl.text, dataWithViewport, warnings);
+            const anchor = tEl.align === 'center' ? 'middle' : tEl.align === 'right' ? 'end' : 'start';
+            parts.push(
+                `<text x="${tEl.xMm}" y="${tEl.yMm}" font-family="${escapeAttr(style.fontFamily)}" font-size="${style.fontSizeMm}"` +
+                    (style.fontWeight ? ` font-weight="${escapeAttr(style.fontWeight)}"` : '') +
+                    (style.color ? ` fill="${escapeAttr(style.color)}"` : '') +
+                    (style.letterSpacingMm !== undefined ? ` letter-spacing="${style.letterSpacingMm}"` : '') +
+                    (style.lineHeightMm !== undefined ? ` line-height="${style.lineHeightMm}"` : '') +
+                    ` text-anchor="${anchor}">${escapeText(text)}</text>`
+            );
+        } else if (el.kind === ELEMENT_KIND_IMAGE) {
+            const img = el as ImageElement;
+            const asset = assetMap.get(img.assetId);
+            if (!asset) {
+                pushWarning(warnings, `Missing asset '${img.assetId}' for image '${img.id}'.`);
+                return;
+            }
+            if (asset.src) {
+                parts.push(
+                    `<image href="${escapeAttr(asset.src)}" x="${img.xMm}" y="${img.yMm}" width="${img.widthMm}" height="${img.heightMm}"` +
+                        (img.fit === 'cover'
+                            ? ' preserveAspectRatio="xMidYMid slice"'
+                            : img.fit === 'stretch'
+                              ? ' preserveAspectRatio="none"'
+                              : ' preserveAspectRatio="xMidYMid meet"') +
+                        ` />`
+                );
+            } else if (asset.content) {
+                parts.push(
+                    `<g transform="translate(${img.xMm} ${img.yMm}) scale(${img.widthMm} ${img.heightMm})">${asset.content}</g>`
+                );
+            }
+        } else if (el.kind === ELEMENT_KIND_SCALE_BAR) {
+            const sb = el as ScaleBarElement;
+            // Scale bar declares which viewport it binds to via `viewport`
+            const boundViewport = sb.viewport ?? viewports[0]?.id ?? null;
+            if (!boundViewport) {
+                pushWarning(warnings, `Scale bar '${sb.id}' is not bound to a viewport.`);
+                return;
+            }
+            const scaleInfo = viewportScales[boundViewport];
+            if (!scaleInfo) {
+                pushWarning(warnings, `Viewport '${boundViewport}' missing scale info for scale bar '${sb.id}'.`);
+                return;
+            }
+            const lengthMm = sb.maxLengthMm;
+            const segments = sb.segments ?? 10;
+            const segmentMm = lengthMm / segments;
+            const metersPerMm = 1 / scaleInfo.mmPerModelUnit;
+            const segmentMeters = segmentMm * metersPerMm;
+            const labelsEvery = Math.max(1, sb.labelEvery ?? 1);
+            const unitSuffix = sb.unit ? ` ${sb.unit}` : ' m';
+            const barParts: string[] = [];
+            const sbStroke = sb.stroke ?? '#000';
+            const sbStrokeWidth = sb.strokeWidthMm ?? 0.5;
+
+            for (let i = 0; i <= segments; i++) {
+                const x = sb.xMm + segmentMm * i;
+                const isLabel = i % labelsEvery === 0;
+                const height = isLabel ? 4 : 3;
+                barParts.push(
+                    `<line x1="${x}" y1="${sb.yMm}" x2="${x}" y2="${sb.yMm - height}" stroke="${escapeAttr(
+                        sbStroke
+                    )}" stroke-width="${sbStrokeWidth}" />`
+                );
+                if (isLabel && sb.textStyle) {
+                    const style = template.styles?.[sb.textStyle];
+                    if (style) {
+                        const labelValue = (segmentMeters * i).toFixed(2).replace(/\.?0+$/, '');
+                        barParts.push(
+                            `<text x="${x}" y="${sb.yMm + style.fontSizeMm + 1}" font-family="${escapeAttr(
+                                style.fontFamily
+                            )}" font-size="${style.fontSizeMm}" text-anchor="middle">${escapeText(labelValue + unitSuffix)}</text>`
+                        );
+                    }
+                }
+            }
+
+            barParts.push(
+                `<line x1="${sb.xMm}" y1="${sb.yMm}" x2="${sb.xMm + lengthMm}" y2="${sb.yMm}" stroke="${escapeAttr(
+                    sbStroke
+                )}" stroke-width="${sbStrokeWidth}" />`
+            );
+
+            parts.push(barParts.join(''));
+        } else if (el.kind === ELEMENT_KIND_VIEWPORT) {
+            const vp = el as ViewportElement;
+            const model = filteredModelsByViewport[vp.id] ?? models[vp.id] ?? null;
+            if (!model) {
+                pushWarning(warnings, `Viewport '${vp.id}' missing model.`);
+            }
+            const vpParts = renderViewportElement(
+                vp,
+                model,
+                dataWithViewport,
+                preferredScales,
+                presets.scales,
+                assetMap,
+                viewportScales,
+                viewportClipPolygonsLocal,
+                viewportClipBounds,
+                viewportClipLabels,
+                viewportClipStyles,
+                viewportHighlight,
+                viewportRenderInfo,
+                warnings,
+                legendColorMaps
+            );
+            parts.push(...vpParts);
+        } else if (el.kind === ELEMENT_KIND_LEGEND) {
+            const legend = el as LegendElement;
+            const legendItems = getPathValue(data, `viewports.${legend.viewport}.items`);
+            const rawLegendItems = Array.isArray(legendItems) ? legendItems : [];
+            const legendDataFiltered = applyLegendFilter(
+                rawLegendItems,
+                legend,
+                viewports,
+                viewportClipPolygonsLocal,
+                viewportRenderInfo
+            );
+            if (!legendDataFiltered || !legendDataFiltered.length) {
+                if (!rawLegendItems.length) {
+                    pushWarning(warnings, `Legend '${legend.id}' has no items from viewport '${legend.viewport}'.`);
+                } else {
+                    pushWarning(
+                        warnings,
+                        `Legend '${legend.id}' filter matched 0 of ${rawLegendItems.length} items (class=${JSON.stringify(legend.class)}, where=${JSON.stringify(legend.where)}).`
+                    );
+                }
+            }
+            const vpEl = viewports.find((v) => v.id === legend.viewport);
+            // Derive swatch opacity from viewport fill rules (first matching rule's opacity)
+            const fillOpacity = vpEl?.fills?.length ? (vpEl.fills[0].fillOpacity ?? 0.35) : undefined;
+            const legendResult = buildLegendGroup(
+                legend,
+                template.styles,
+                page,
+                page.marginMm,
+                legendDataFiltered || [],
+                fillOpacity
+            );
+            if (legendResult) {
+                parts.push(legendResult.svg);
+            }
+        }
+    });
+
+    if (labelElements.length) {
+        const labelParts = renderLabels(
+            labelElements,
+            data,
+            viewportRenderInfo,
+            viewportClipLabels,
+            viewportClipPolygonsLocal,
+            viewportClipPolygonsWorld,
+            template.styles ?? {},
+            dataWithViewport,
+            warnings
+        );
+        parts.push(...labelParts);
+    }
+
+    if (qrElements.length) {
+        const qrParts = await renderQrElements(
+            qrElements,
+            viewports,
+            viewportScales,
+            models,
+            { qrContext: options?.qrContext },
+            dataWithViewport,
+            warnings
+        );
+        parts.push(...qrParts);
+    }
+
+    parts.push('</svg>');
+
+    return { svg: parts.join(''), viewportScales, warnings };
+}
+
+// Register renderLayout with renderDrawing to break the circular dependency.
+// This runs at module evaluation time — safe because renderLayout is defined above.
+import { setRenderLayoutBinding as _setBinding } from './renderDrawing';
+_setBinding(renderLayout as any);