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

package/src/layout/renderDrawing.ts

@@ -1,710 +1,710 @@
-import type { SectionRenderState, SectionPath, SectionLabel } from '@twinfinity/geometry';
-import { sectionStateToModelView, computePolylinesCenter } from './itemBuilders';
-import { buildMetadataMap, normalizePropertySets, resolveIfcClassName, resolveIfcClassId } from './metadata';
-import { applyLineStyleToPaths } from './utils';
-import { analyzeTemplate } from './analyzeTemplate';
-import { matchesV2Filter } from './filters';
-import type {
-    LayoutTemplate,
-    ViewportElement,
-    ViewportLineStyle,
-    FillRule,
-    SvgModelView,
-    SectionResult,
-    RenderDrawingInput,
-    RenderDrawingResult,
-    NormalizedProductItem,
-    LabelStyle
-} from './types';
-import { getProp } from './typeGuards';
-
-// ---------------------------------------------------------------------------
-// Local type declarations for optional peer-dependency APIs.
-// Declared inline to avoid pulling @babylonjs/core and @twinfinity/core into
-// print-layout's compile-time dependency graph.
-// ---------------------------------------------------------------------------
-
-interface SampledColor {
-    color: { r: number; g: number; b: number };
-    alpha: number;
-}
-
-interface ExternalSections {
-    buildSectionStateForEntries: (
-        perProduct: unknown[],
-        options: {
-            viewport?: { viewMinX: number; viewMaxX: number; viewMinZ: number; viewMaxZ: number };
-            strokeWidth?: number;
-            labelFontSize?: number;
-            fills?: Array<{ class?: string | string[]; fillOpacity?: number; matchClipFilter?: boolean }>;
-            includeMeta?: boolean;
-            includeLabels?: boolean;
-            buildLabels?: (products: unknown[], fontSize: number) => unknown[];
-            clipPolygon?: Array<Array<{ x: number; z: number }>>;
-            planeNormal?: unknown;
-        }
-    ) => (SectionRenderState & { rawPaths?: SectionPath[]; rawLabels?: SectionLabel[] }) | null;
-}
-
-interface ExternalGeometry {
-    sampleProductColorRgba: (product: unknown) => SampledColor | undefined;
-    buildRoomLabels: (
-        entries: unknown[],
-        fontSize: number,
-        options: { labelPath: string; classFilter?: string }
-    ) => SectionLabel[];
-}
-
-// These were previously lazy-loaded via require() from @measurement-tools/* packages.
-// Now they are part of @twinfinity/printing (this package) and @twinfinity/geometry.
-import { buildSectionStateForEntries, resolveProductProperty } from '../sections';
-
-// Wrap into the ExternalSections shape for backward compat with the rest of this file.
-const _sections: ExternalSections = {
-    buildSectionStateForEntries: (perProduct, options) => {
-        type Entries = Parameters<typeof buildSectionStateForEntries>[0];
-        type Opts = Parameters<typeof buildSectionStateForEntries>[1];
-        return buildSectionStateForEntries(perProduct as Entries, {
-            ...options,
-            fills: options.fills as Opts['fills'],
-            buildLabels: options.buildLabels as Opts['buildLabels'],
-            planeNormal: options.planeNormal as Opts['planeNormal']
-        });
-    }
-};
-function getSections(): ExternalSections {
-    return _sections;
-}
-
-// sampleProductColorRgba: duck-type access to product mesh style color.
-// buildRoomLabels: requires product-geometry which this package can't depend on.
-// Consumers must provide buildRoomLabels via options if room labels are needed.
-const _geometry: ExternalGeometry = {
-    sampleProductColorRgba: (product: unknown): SampledColor | undefined => {
-        /** Duck-typed mesh with optional color-access methods. */
-        interface DuckMesh {
-            copyColorTo?: (out: Uint8Array, offset: number) => void;
-            getColorComponent?: (index: number) => number;
-            style?: { surfaceColor?: readonly number[]; color?: readonly number[] };
-        }
-        const p = product as Record<string, unknown>;
-        const meshes = (p?.meshes ?? p?.productMeshes) as DuckMesh[] | undefined;
-        if (!meshes?.length) return undefined;
-
-        const rgba = new Uint8Array(4);
-        for (const mesh of meshes) {
-            try {
-                if (typeof mesh.copyColorTo === 'function') {
-                    mesh.copyColorTo(rgba, 0);
-                } else if (typeof mesh.getColorComponent === 'function') {
-                    rgba[0] = mesh.getColorComponent(0);
-                    rgba[1] = mesh.getColorComponent(1);
-                    rgba[2] = mesh.getColorComponent(2);
-                    rgba[3] = mesh.getColorComponent(3);
-                } else {
-                    const style = mesh.style;
-                    const c = style?.surfaceColor ?? style?.color;
-                    if (c) {
-                        // surfaceColor values may be 0–1 or 0–255; normalize to 0–1
-                        const maxVal = Math.max(c[0], c[1], c[2]);
-                        const scale = maxVal > 1 ? 1 / 255 : 1;
-                        return {
-                            color: { r: c[0] * scale, g: c[1] * scale, b: c[2] * scale },
-                            alpha: (c[3] ?? (maxVal > 1 ? 255 : 1)) * scale
-                        };
-                    }
-                    continue;
-                }
-            } catch {
-                continue;
-            }
-            const [r, g, b, a] = rgba;
-            if (a === 0 && r === 0 && g === 0 && b === 0) continue;
-            return { color: { r: r / 255, g: g / 255, b: b / 255 }, alpha: a / 255 };
-        }
-        return undefined;
-    },
-    buildRoomLabels: () => [] // Requires product-geometry — consumer provides via options
-};
-function getGeometry(): ExternalGeometry {
-    return _geometry;
-}
-function getSampleColor(): (product: unknown) => SampledColor | undefined {
-    return _geometry.sampleProductColorRgba;
-}
-
-// Late-binding for renderLayout to break circular dependency.
-// renderDrawing is imported by index.ts which defines renderLayout.
-// The binding is set by index.ts after definition via setRenderLayoutBinding().
-let _renderLayout:
-    | ((
-          template: LayoutTemplate,
-          data: any,
-          models: Record<string, SvgModelView>,
-          options?: any
-      ) => Promise<{ svg: string; viewportScales: any; warnings: string[] }>)
-    | null = null;
-
-/** Called by index.ts to register renderLayout without a circular import. */
-export function setRenderLayoutBinding(fn: NonNullable<typeof _renderLayout>): void {
-    _renderLayout = fn;
-}
-
-function getRenderLayout(): NonNullable<typeof _renderLayout> {
-    if (!_renderLayout) {
-        throw new Error(
-            'renderLayout not initialized. Ensure @twinfinity/printing index is imported before calling renderDrawing.'
-        );
-    }
-    return _renderLayout;
-}
-
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-
-/**
- * High-level entry point that converts raw plane-section results and a layout
- * template into a ready-to-print SVG string.
- *
- * Internalizes all data wiring (section → SVG, item extraction, color sampling,
- * metadata building, legend/label data) that previously required ~350 lines of
- * app-side boilerplate.
- *
- * ```ts
- * const section = computePlaneSectionsForProducts(products, plane, { includeInvisible: true });
- * const { svg, warnings } = await renderDrawing({
- *   template,
- *   sections: { main: section },
- *   options: {
- *     allowRemoteAssets: true,
- *     qrContext: { host, containerName, planeHeight },
- *     productFields: { idPath: "propertySets.BIP.spacenumber.value", ... },
- *     roomLabels: { labelPath: "BIP.spacename", classFilter: "space" },
- *   },
- * });
- * ```
- */
-export async function renderDrawing(input: RenderDrawingInput): Promise<RenderDrawingResult> {
-    const { options } = input;
-    const warnings: string[] = [];
-
-    // ---- Resolve template variables (if present) ----
-    // This happens FIRST to ensure all {{vars.*}} references are resolved before validation/rendering
-    let template = input.template;
-    if (template.variables) {
-        const { resolveTemplateValues, applyTemplateVariables } = await import('./templateVariables');
-        const { values, warnings: varWarnings } = resolveTemplateValues(template, options?.variables);
-
-        // Add variable resolution warnings to output
-        varWarnings.forEach((w) => warnings.push(`[Variables] ${w}`));
-
-        // Apply variables to template (substitute {{vars.*}} references)
-        template = applyTemplateVariables(template, values);
-    }
-
-    const renderLayout = getRenderLayout();
-
-    // ---- Collect viewport elements from template ----
-    const viewports = template.elements.filter((el) => el.kind === 'viewport') as ViewportElement[];
-    if (!viewports.length) {
-        return { svg: '', warnings: ['No viewport elements in template.'] };
-    }
-
-    // ---- Fast path: pre-built models provided directly ----
-    if (input.models) {
-        // Build items: explicit viewportItems take priority, then auto-build from productEntries
-        let viewportsData: Record<string, { items: NormalizedProductItem[] }>;
-
-        if (options?.viewportItems) {
-            const emptyDefaults = Object.fromEntries(
-                viewports.map((vp) => [vp.id, { items: [] as NormalizedProductItem[] }])
-            );
-            viewportsData = { ...emptyDefaults, ...options.viewportItems };
-        } else if (options?.productEntries?.length) {
-            // Auto-build items per viewport from raw product entries
-            const sampleColor = getSampleColor();
-            viewportsData = {};
-            for (const vp of viewports) {
-                viewportsData[vp.id] = {
-                    items: buildItemsFromEntries(options.productEntries, vp.fills, sampleColor)
-                };
-            }
-        } else {
-            viewportsData = Object.fromEntries(
-                viewports.map((vp) => [vp.id, { items: [] as NormalizedProductItem[] }])
-            );
-        }
-
-        const layoutData = { viewports: viewportsData };
-
-        // Early input analysis: warn about mismatches between template and provided data
-        const reqs = analyzeTemplate(template);
-
-        for (const vpId of reqs.viewportIds) {
-            if (!input.models[vpId]) {
-                warnings.push(`Template viewport '${vpId}' has no model — it will render empty.`);
-            }
-        }
-
-        const allItems = Object.values(viewportsData).flatMap((v) => v.items);
-        if (allItems.length > 0) {
-            for (const path of reqs.propertyPaths) {
-                const parts = path.split('.');
-                if (parts.length < 2) continue;
-                const [setName, propName] = parts;
-                const hasIt = allItems.some((item) => item.propertySets?.[setName]?.[propName]?.value !== undefined);
-                if (!hasIt) {
-                    warnings.push(`Template references property '${path}' but no items provide it.`);
-                }
-            }
-        }
-
-        if (reqs.usesRemoteAssets && !template.allowRemoteAssets && !options?.allowRemoteAssets) {
-            warnings.push('Template uses remote assets but allowRemoteAssets is not enabled.');
-        }
-
-        // Build metadata from product entries (same as standard path)
-        const metadataEntries = options?.productEntries ?? [];
-        const metadataById = buildMetadataMap(metadataEntries);
-
-        const result = await renderLayout(template, layoutData, input.models, {
-            allowRemoteAssets: template.allowRemoteAssets ?? options?.allowRemoteAssets,
-            qrContext: options?.qrContext,
-            metadataById
-        });
-
-        return {
-            svg: result.svg,
-            warnings: [...warnings, ...result.warnings]
-        };
-    }
-
-    // ---- Standard path: build models from section results ----
-    if (!input.sections) {
-        return { svg: '', warnings: ['Either sections or models must be provided.'] };
-    }
-
-    const { buildSectionStateForEntries } = getSections();
-    const { sampleProductColorRgba, buildRoomLabels } = getGeometry();
-
-    // Normalize sections: single SectionResult → map to all viewports
-    const isSingle = !!(input.sections as SectionResult).perProduct;
-    const sections: Record<string, SectionResult> = isSingle
-        ? Object.fromEntries(viewports.map((vp) => [vp.id, input.sections as SectionResult]))
-        : (input.sections as Record<string, SectionResult>);
-
-    // Auto-detect whether the template has its own labels elements.
-    // If so, do NOT embed labels in the section SVG (would cause duplicates).
-    const hasTemplateLabelElements = template.elements.some((el) => el.kind === 'labels');
-    const roomLabelCfg = hasTemplateLabelElements ? undefined : options?.roomLabels;
-
-    // ---- Build section state + model view per viewport ----
-    const models: Record<string, SvgModelView> = {};
-    const entriesByViewport: Record<string, SectionResult['perProduct']> = {};
-    const sectionStateCache = new Map<string, SectionRenderState | null>();
-
-    for (const vp of viewports) {
-        const sectionResult = sections[vp.id];
-        if (!sectionResult?.perProduct?.length) {
-            warnings.push(`No section data for viewport '${vp.id}'.`);
-            continue;
-        }
-
-        entriesByViewport[vp.id] = sectionResult.perProduct;
-
-        // Dedup: skip if already built for this viewport key
-        if (sectionStateCache.has(vp.id)) {
-            const cached = sectionStateCache.get(vp.id);
-            if (cached) {
-                models[vp.id] = sectionStateToModelView(cached);
-            }
-            continue;
-        }
-
-        const resolved = resolveLineStyles(vp);
-
-        // Estimate label font size from template style and section bounds
-        const labelFontSize = estimateLabelFontSize(template, vp, sectionResult.perProduct);
-
-        // Extract clip polygon from section results if clip config is present
-        let clipPolygon: Array<Array<{ x: number; z: number }>> | undefined;
-        if (vp.clip?.where && vp.clip.class) {
-            const clipClass = Array.isArray(vp.clip.class) ? vp.clip.class : [vp.clip.class];
-            const clipEntries = sectionResult.perProduct.filter((entry: any) => {
-                const product = entry.product;
-                const matchesClass = clipClass.some((c: string) => product.class?.is?.(c));
-                if (!matchesClass) return false;
-                // Match where condition using T8-aware property resolution
-                for (const [path, expected] of Object.entries(vp.clip!.where!)) {
-                    const actualValue = resolveProductProperty(product, path);
-                    if (actualValue === undefined) return false;
-                    if (actualValue !== expected) return false;
-                }
-                return true;
-            });
-            if (clipEntries.length) {
-                clipPolygon = clipEntries.flatMap((entry: any) =>
-                    (entry.polylines || []).map((pl: any) => (pl.points || []).map((p: any) => ({ x: p.x, z: p.z })))
-                );
-            }
-        }
-
-        // Convert planeNormal array to object with x, y, z if present
-        let planeNormal: unknown = undefined;
-        if (vp.planeNormal && Array.isArray(vp.planeNormal) && vp.planeNormal.length === 3) {
-            planeNormal = { x: vp.planeNormal[0], y: vp.planeNormal[1], z: vp.planeNormal[2] };
-        }
-
-        type SectionStateWithRaw = SectionRenderState & { rawPaths?: SectionPath[]; rawLabels?: SectionLabel[] };
-        const state: SectionStateWithRaw | null = buildSectionStateForEntries(sectionResult.perProduct, {
-            strokeWidth: resolved.default.widthMm,
-            labelFontSize,
-            fills: vp.fills,
-            includeMeta: true,
-            includeLabels: !!roomLabelCfg,
-            buildLabels: roomLabelCfg
-                ? (products, fontSize) =>
-                      buildRoomLabels(products, fontSize, {
-                          labelPath: roomLabelCfg.labelPath,
-                          classFilter: roomLabelCfg.classFilter
-                      })
-                : undefined,
-            clipPolygon,
-            planeNormal
-        });
-
-        sectionStateCache.set(vp.id, state);
-
-        if (!state) {
-            warnings.push(`No geometry for viewport '${vp.id}'.`);
-            continue;
-        }
-
-        // Apply line style overrides from viewport config
-        let finalState: SectionStateWithRaw = state;
-        const defaultStyle = resolved.default;
-        if (defaultStyle.color || defaultStyle.widthMm) {
-            const style: { stroke?: string; strokeWidth?: number } = {};
-            if (defaultStyle.color) style.stroke = defaultStyle.color;
-            if (defaultStyle.widthMm) style.strokeWidth = defaultStyle.widthMm;
-            finalState = {
-                ...state,
-                paths: applyLineStyleToPaths(state.paths, style)
-            };
-            if (state.rawPaths) {
-                finalState.rawPaths = applyLineStyleToPaths(state.rawPaths, style);
-            }
-        }
-
-        const labelStyle: LabelStyle | undefined = template.styles?.body
-            ? {
-                  fill: template.styles.body.color ?? BUILTIN_LABEL_DEFAULTS.fill,
-                  fontFamily: template.styles.body.fontFamily ?? BUILTIN_LABEL_DEFAULTS.fontFamily,
-                  fontWeight: template.styles.body.fontWeight ?? BUILTIN_LABEL_DEFAULTS.fontWeight
-              }
-            : undefined;
-
-        models[vp.id] = sectionStateToModelView(finalState, labelStyle);
-    }
-
-    // ---- Build items per viewport ----
-    const viewportsData: Record<string, { items: NormalizedProductItem[] }> = {};
-
-    for (const vp of viewports) {
-        const entries = entriesByViewport[vp.id];
-        if (!entries) {
-            viewportsData[vp.id] = { items: [] };
-            continue;
-        }
-
-        viewportsData[vp.id] = { items: buildItemsFromEntries(entries, vp.fills, sampleProductColorRgba) };
-    }
-
-    // ---- Build metadata from all section entries ----
-    const allEntries = Object.values(entriesByViewport).flat();
-    const metadataById = buildMetadataMap(allEntries);
-
-    // ---- Assemble layout data ----
-    const layoutData = {
-        viewports: viewportsData
-    };
-
-    // ---- Render ----
-    const result = await renderLayout(template, layoutData, models, {
-        allowRemoteAssets: template.allowRemoteAssets ?? options?.allowRemoteAssets,
-        qrContext: options?.qrContext,
-        metadataById
-    });
-
-    return {
-        svg: result.svg,
-        warnings: [...warnings, ...result.warnings]
-    };
-}
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Build NormalizedProductItems from per-product entries.
- *
- * Shared between the standard path (plane sections) and the models path
- * (slab sections / pre-built models with productEntries).
- */
-function buildItemsFromEntries(
-    entries: Array<{ product: unknown; polylines: unknown }>,
-    fills: FillRule[] | undefined,
-    sampleColor: ((product: unknown) => SampledColor | undefined) | undefined
-): NormalizedProductItem[] {
-    return entries.map((entry) => {
-        const product = entry.product;
-        const propertySets = normalizePropertySets(product);
-        const gid = getProp(product, 'gid') ?? getProp(product, 'id');
-        const center = computePolylinesCenter(entry);
-        const name = getProp(product, 'name') as string | undefined;
-        const displayName = typeof name === 'string' && name.trim().length ? name.trim() : gid ? String(gid) : '-';
-        const item: NormalizedProductItem = {
-            gid: gid ? String(gid) : undefined,
-            ifcClass: resolveIfcClassName(product),
-            ifcClassId: resolveIfcClassId(product),
-            propertySets,
-            productId: gid ? String(gid) : '-',
-            productName: displayName,
-            area: null,
-            x: center.x,
-            z: center.z,
-            text: displayName,
-            polylines: entry.polylines as Array<{ points?: Array<{ x: number; z: number }> }>
-        };
-
-        if (fills?.length && sampleColor) {
-            const color = resolveFillColor(item, product, fills, sampleColor);
-            if (color) {
-                item.color = color;
-            }
-        }
-
-        return item;
-    });
-}
-
-/**
- * Estimate label font size in model units from the template body style and the
- * approximate viewport-to-world scale ratio.
- */
-function estimateLabelFontSize(
-    template: LayoutTemplate,
-    vp: ViewportElement,
-    perProduct: SectionResult['perProduct']
-): number {
-    const templateFontSizeMm = template.styles?.body?.fontSizeMm ?? 3.5;
-
-    // Quick world-bounds scan
-    let minX = Infinity;
-    let maxX = -Infinity;
-    let minZ = Infinity;
-    let maxZ = -Infinity;
-    for (const entry of perProduct) {
-        if (!entry.polylines) continue;
-        for (const polyline of entry.polylines) {
-            if (!polyline.points) continue;
-            for (const pt of polyline.points) {
-                const px = getProp(pt, 'x');
-                const pz = getProp(pt, 'z');
-                if (Number.isFinite(px) && Number.isFinite(pz)) {
-                    if ((px as number) < minX) minX = px as number;
-                    if ((px as number) > maxX) maxX = px as number;
-                    if ((pz as number) < minZ) minZ = pz as number;
-                    if ((pz as number) > maxZ) maxZ = pz as number;
-                }
-            }
-        }
-    }
-
-    const worldWidth = maxX - minX;
-    const worldHeight = maxZ - minZ;
-    if (!Number.isFinite(worldWidth) || worldWidth <= 0 || !Number.isFinite(worldHeight) || worldHeight <= 0) {
-        return templateFontSizeMm; // Fallback: 1:1 estimate
-    }
-
-    // Approximate mm-per-model-unit from the viewport dimensions
-    const scaleX = vp.widthMm / worldWidth;
-    const scaleY = vp.heightMm / worldHeight;
-    const mmPerModelUnit = Math.min(scaleX, scaleY);
-
-    if (!Number.isFinite(mmPerModelUnit) || mmPerModelUnit <= 0) {
-        return templateFontSizeMm;
-    }
-
-    return templateFontSizeMm / mmPerModelUnit;
-}
-
-// ---------------------------------------------------------------------------
-// Label style defaults
-// ---------------------------------------------------------------------------
-
-/** Built-in label style defaults when template body styles are partially set. */
-export const BUILTIN_LABEL_DEFAULTS = {
-    fill: '#374151',
-    fontFamily: '"Segoe UI", "Helvetica Neue", Arial, sans-serif',
-    fontWeight: '300'
-} as const;
-
-// ---------------------------------------------------------------------------
-// Line style defaults & resolution
-// ---------------------------------------------------------------------------
-
-/** Built-in defaults when neither lineStyles nor lineWidthMm/lineColor are set. */
-export const BUILTIN_LINE_DEFAULTS: Required<ViewportLineStyle> = {
-    widthMm: 0.35, // Reasonable default: 0.35mm line width (was 0.01mm - too thin!)
-    color: '#1f2937',
-    dash: '',
-    enabled: true
-};
-
-export const BUILTIN_HIDDEN_DEFAULTS: Required<ViewportLineStyle> = {
-    widthMm: 0.005,
-    color: '#9ca3af',
-    dash: '4 2',
-    enabled: true
-};
-
-type LineCategory =
-    | 'cutLines'
-    | 'visibleLines'
-    | 'hiddenLines'
-    | 'silhouettes'
-    | 'featureEdges'
-    | 'stairArrows'
-    | 'outlineVisible'
-    | 'outlineHidden';
-
-/** Category-specific built-in defaults (merged over the global default). */
-export const CATEGORY_BUILTIN_OVERRIDES: Partial<Record<LineCategory, Partial<ViewportLineStyle>>> = {
-    cutLines: { widthMm: 0.02 },
-    hiddenLines: BUILTIN_HIDDEN_DEFAULTS,
-    outlineHidden: BUILTIN_HIDDEN_DEFAULTS
-};
-
-export interface ResolvedLineStyles {
-    default: Required<ViewportLineStyle>;
-    byCategory: Record<LineCategory, Required<ViewportLineStyle>>;
-}
-
-/**
- * Resolve the effective line style for every category.
- *
- * Priority: category entry in `lineStyles` → `lineStyles.default`
- *         → `lineWidthMm`/`lineColor` shorthand → built-in defaults.
- */
-function resolveLineStyles(vp: ViewportElement): ResolvedLineStyles {
-    const ls = vp.lineStyles;
-
-    // Base default: lineStyles.default → shorthand → built-in
-    const base: Required<ViewportLineStyle> = {
-        ...BUILTIN_LINE_DEFAULTS,
-        ...(vp.lineWidthMm !== undefined ? { widthMm: vp.lineWidthMm } : {}),
-        ...(vp.lineColor !== undefined ? { color: vp.lineColor } : {}),
-        ...(ls?.default ?? {})
-    } as Required<ViewportLineStyle>;
-
-    const categories: LineCategory[] = [
-        'cutLines',
-        'visibleLines',
-        'hiddenLines',
-        'silhouettes',
-        'featureEdges',
-        'stairArrows',
-        'outlineVisible',
-        'outlineHidden'
-    ];
-
-    // Category group mapping: individual categories inherit from their group style
-    const categoryGroups: Record<LineCategory, LineCategory> = {
-        cutLines: 'visibleLines',
-        visibleLines: 'visibleLines',
-        silhouettes: 'visibleLines',
-        featureEdges: 'visibleLines',
-        outlineVisible: 'visibleLines',
-        hiddenLines: 'hiddenLines',
-        outlineHidden: 'hiddenLines',
-        stairArrows: 'stairArrows'
-    };
-
-    const byCategory = {} as Record<LineCategory, Required<ViewportLineStyle>>;
-    for (const cat of categories) {
-        const builtinOverride = CATEGORY_BUILTIN_OVERRIDES[cat];
-        const groupName = categoryGroups[cat];
-        const groupStyle = ls?.[groupName]; // Group style (visibleLines, hiddenLines, stairArrows)
-        const categoryOverride = ls?.[cat]; // Individual category settings (enable/disable)
-
-        byCategory[cat] = {
-            ...base,
-            ...(builtinOverride ?? {}),
-            ...(groupStyle ?? {}), // Apply group style first
-            ...(categoryOverride ?? {}) // Then individual overrides (enable/disable)
-        } as Required<ViewportLineStyle>;
-    }
-
-    return { default: base, byCategory };
-}
-
-// ---------------------------------------------------------------------------
-// Fill rule helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Resolve fill color for an item based on viewport fill rules.
- * Returns an RGBA tuple [r, g, b, a] (0–255) or undefined if no rule matches.
- */
-export function resolveFillColor(
-    item: NormalizedProductItem,
-    product: unknown,
-    fills: FillRule[] | undefined,
-    sampleColor: (product: unknown) => SampledColor | undefined
-): [number, number, number, number] | undefined {
-    if (!fills?.length) return undefined;
-    for (const rule of fills) {
-        if (!matchesV2Filter(item, rule.class, rule.where)) continue;
-        if (rule.fill === 'sample') {
-            const sampled = sampleColor(product);
-            if (sampled) {
-                return [
-                    Math.round(sampled.color.r * 255),
-                    Math.round(sampled.color.g * 255),
-                    Math.round(sampled.color.b * 255),
-                    Math.round(sampled.alpha * 255)
-                ];
-            }
-        } else {
-            return parseHexToRgba(rule.fill);
-        }
-        break; // first matching rule wins
-    }
-    return undefined;
-}
-
-/**
- * Parse a CSS hex color string to an RGBA tuple (0–255).
- */
-function parseHexToRgba(hex: string): [number, number, number, number] {
-    const h = hex.replace(/^#/, '');
-    if (h.length === 3) {
-        return [parseInt(h[0] + h[0], 16), parseInt(h[1] + h[1], 16), parseInt(h[2] + h[2], 16), 255];
-    }
-    if (h.length === 6) {
-        return [parseInt(h.substring(0, 2), 16), parseInt(h.substring(2, 4), 16), parseInt(h.substring(4, 6), 16), 255];
-    }
-    if (h.length === 8) {
-        return [
-            parseInt(h.substring(0, 2), 16),
-            parseInt(h.substring(2, 4), 16),
-            parseInt(h.substring(4, 6), 16),
-            parseInt(h.substring(6, 8), 16)
-        ];
-    }
-    // Fallback: opaque black
-    return [0, 0, 0, 255];
-}
+import type { SectionRenderState, SectionPath, SectionLabel } from '@twinfinity/geometry';
+import { sectionStateToModelView, computePolylinesCenter } from './itemBuilders';
+import { buildMetadataMap, normalizePropertySets, resolveIfcClassName, resolveIfcClassId } from './metadata';
+import { applyLineStyleToPaths } from './utils';
+import { analyzeTemplate } from './analyzeTemplate';
+import { matchesV2Filter } from './filters';
+import type {
+    LayoutTemplate,
+    ViewportElement,
+    ViewportLineStyle,
+    FillRule,
+    SvgModelView,
+    SectionResult,
+    RenderDrawingInput,
+    RenderDrawingResult,
+    NormalizedProductItem,
+    LabelStyle
+} from './types';
+import { getProp } from './typeGuards';
+
+// ---------------------------------------------------------------------------
+// Local type declarations for optional peer-dependency APIs.
+// Declared inline to avoid pulling @babylonjs/core and @twinfinity/core into
+// print-layout's compile-time dependency graph.
+// ---------------------------------------------------------------------------
+
+interface SampledColor {
+    color: { r: number; g: number; b: number };
+    alpha: number;
+}
+
+interface ExternalSections {
+    buildSectionStateForEntries: (
+        perProduct: unknown[],
+        options: {
+            viewport?: { viewMinX: number; viewMaxX: number; viewMinZ: number; viewMaxZ: number };
+            strokeWidth?: number;
+            labelFontSize?: number;
+            fills?: Array<{ class?: string | string[]; fillOpacity?: number; matchClipFilter?: boolean }>;
+            includeMeta?: boolean;
+            includeLabels?: boolean;
+            buildLabels?: (products: unknown[], fontSize: number) => unknown[];
+            clipPolygon?: Array<Array<{ x: number; z: number }>>;
+            planeNormal?: unknown;
+        }
+    ) => (SectionRenderState & { rawPaths?: SectionPath[]; rawLabels?: SectionLabel[] }) | null;
+}
+
+interface ExternalGeometry {
+    sampleProductColorRgba: (product: unknown) => SampledColor | undefined;
+    buildRoomLabels: (
+        entries: unknown[],
+        fontSize: number,
+        options: { labelPath: string; classFilter?: string }
+    ) => SectionLabel[];
+}
+
+// These were previously lazy-loaded via require() from @measurement-tools/* packages.
+// Now they are part of @twinfinity/printing (this package) and @twinfinity/geometry.
+import { buildSectionStateForEntries, resolveProductProperty } from '../sections';
+
+// Wrap into the ExternalSections shape for backward compat with the rest of this file.
+const _sections: ExternalSections = {
+    buildSectionStateForEntries: (perProduct, options) => {
+        type Entries = Parameters<typeof buildSectionStateForEntries>[0];
+        type Opts = Parameters<typeof buildSectionStateForEntries>[1];
+        return buildSectionStateForEntries(perProduct as Entries, {
+            ...options,
+            fills: options.fills as Opts['fills'],
+            buildLabels: options.buildLabels as Opts['buildLabels'],
+            planeNormal: options.planeNormal as Opts['planeNormal']
+        });
+    }
+};
+function getSections(): ExternalSections {
+    return _sections;
+}
+
+// sampleProductColorRgba: duck-type access to product mesh style color.
+// buildRoomLabels: requires product-geometry which this package can't depend on.
+// Consumers must provide buildRoomLabels via options if room labels are needed.
+const _geometry: ExternalGeometry = {
+    sampleProductColorRgba: (product: unknown): SampledColor | undefined => {
+        /** Duck-typed mesh with optional color-access methods. */
+        interface DuckMesh {
+            copyColorTo?: (out: Uint8Array, offset: number) => void;
+            getColorComponent?: (index: number) => number;
+            style?: { surfaceColor?: readonly number[]; color?: readonly number[] };
+        }
+        const p = product as Record<string, unknown>;
+        const meshes = (p?.meshes ?? p?.productMeshes) as DuckMesh[] | undefined;
+        if (!meshes?.length) return undefined;
+
+        const rgba = new Uint8Array(4);
+        for (const mesh of meshes) {
+            try {
+                if (typeof mesh.copyColorTo === 'function') {
+                    mesh.copyColorTo(rgba, 0);
+                } else if (typeof mesh.getColorComponent === 'function') {
+                    rgba[0] = mesh.getColorComponent(0);
+                    rgba[1] = mesh.getColorComponent(1);
+                    rgba[2] = mesh.getColorComponent(2);
+                    rgba[3] = mesh.getColorComponent(3);
+                } else {
+                    const style = mesh.style;
+                    const c = style?.surfaceColor ?? style?.color;
+                    if (c) {
+                        // surfaceColor values may be 0–1 or 0–255; normalize to 0–1
+                        const maxVal = Math.max(c[0], c[1], c[2]);
+                        const scale = maxVal > 1 ? 1 / 255 : 1;
+                        return {
+                            color: { r: c[0] * scale, g: c[1] * scale, b: c[2] * scale },
+                            alpha: (c[3] ?? (maxVal > 1 ? 255 : 1)) * scale
+                        };
+                    }
+                    continue;
+                }
+            } catch {
+                continue;
+            }
+            const [r, g, b, a] = rgba;
+            if (a === 0 && r === 0 && g === 0 && b === 0) continue;
+            return { color: { r: r / 255, g: g / 255, b: b / 255 }, alpha: a / 255 };
+        }
+        return undefined;
+    },
+    buildRoomLabels: () => [] // Requires product-geometry — consumer provides via options
+};
+function getGeometry(): ExternalGeometry {
+    return _geometry;
+}
+function getSampleColor(): (product: unknown) => SampledColor | undefined {
+    return _geometry.sampleProductColorRgba;
+}
+
+// Late-binding for renderLayout to break circular dependency.
+// renderDrawing is imported by index.ts which defines renderLayout.
+// The binding is set by index.ts after definition via setRenderLayoutBinding().
+let _renderLayout:
+    | ((
+          template: LayoutTemplate,
+          data: any,
+          models: Record<string, SvgModelView>,
+          options?: any
+      ) => Promise<{ svg: string; viewportScales: any; warnings: string[] }>)
+    | null = null;
+
+/** Called by index.ts to register renderLayout without a circular import. */
+export function setRenderLayoutBinding(fn: NonNullable<typeof _renderLayout>): void {
+    _renderLayout = fn;
+}
+
+function getRenderLayout(): NonNullable<typeof _renderLayout> {
+    if (!_renderLayout) {
+        throw new Error(
+            'renderLayout not initialized. Ensure @twinfinity/printing index is imported before calling renderDrawing.'
+        );
+    }
+    return _renderLayout;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * High-level entry point that converts raw plane-section results and a layout
+ * template into a ready-to-print SVG string.
+ *
+ * Internalizes all data wiring (section → SVG, item extraction, color sampling,
+ * metadata building, legend/label data) that previously required ~350 lines of
+ * app-side boilerplate.
+ *
+ * ```ts
+ * const section = computePlaneSectionsForProducts(products, plane, { includeInvisible: true });
+ * const { svg, warnings } = await renderDrawing({
+ *   template,
+ *   sections: { main: section },
+ *   options: {
+ *     allowRemoteAssets: true,
+ *     qrContext: { host, containerName, planeHeight },
+ *     productFields: { idPath: "propertySets.BIP.spacenumber.value", ... },
+ *     roomLabels: { labelPath: "BIP.spacename", classFilter: "space" },
+ *   },
+ * });
+ * ```
+ */
+export async function renderDrawing(input: RenderDrawingInput): Promise<RenderDrawingResult> {
+    const { options } = input;
+    const warnings: string[] = [];
+
+    // ---- Resolve template variables (if present) ----
+    // This happens FIRST to ensure all {{vars.*}} references are resolved before validation/rendering
+    let template = input.template;
+    if (template.variables) {
+        const { resolveTemplateValues, applyTemplateVariables } = await import('./templateVariables');
+        const { values, warnings: varWarnings } = resolveTemplateValues(template, options?.variables);
+
+        // Add variable resolution warnings to output
+        varWarnings.forEach((w) => warnings.push(`[Variables] ${w}`));
+
+        // Apply variables to template (substitute {{vars.*}} references)
+        template = applyTemplateVariables(template, values);
+    }
+
+    const renderLayout = getRenderLayout();
+
+    // ---- Collect viewport elements from template ----
+    const viewports = template.elements.filter((el) => el.kind === 'viewport') as ViewportElement[];
+    if (!viewports.length) {
+        return { svg: '', warnings: ['No viewport elements in template.'] };
+    }
+
+    // ---- Fast path: pre-built models provided directly ----
+    if (input.models) {
+        // Build items: explicit viewportItems take priority, then auto-build from productEntries
+        let viewportsData: Record<string, { items: NormalizedProductItem[] }>;
+
+        if (options?.viewportItems) {
+            const emptyDefaults = Object.fromEntries(
+                viewports.map((vp) => [vp.id, { items: [] as NormalizedProductItem[] }])
+            );
+            viewportsData = { ...emptyDefaults, ...options.viewportItems };
+        } else if (options?.productEntries?.length) {
+            // Auto-build items per viewport from raw product entries
+            const sampleColor = getSampleColor();
+            viewportsData = {};
+            for (const vp of viewports) {
+                viewportsData[vp.id] = {
+                    items: buildItemsFromEntries(options.productEntries, vp.fills, sampleColor)
+                };
+            }
+        } else {
+            viewportsData = Object.fromEntries(
+                viewports.map((vp) => [vp.id, { items: [] as NormalizedProductItem[] }])
+            );
+        }
+
+        const layoutData = { viewports: viewportsData };
+
+        // Early input analysis: warn about mismatches between template and provided data
+        const reqs = analyzeTemplate(template);
+
+        for (const vpId of reqs.viewportIds) {
+            if (!input.models[vpId]) {
+                warnings.push(`Template viewport '${vpId}' has no model — it will render empty.`);
+            }
+        }
+
+        const allItems = Object.values(viewportsData).flatMap((v) => v.items);
+        if (allItems.length > 0) {
+            for (const path of reqs.propertyPaths) {
+                const parts = path.split('.');
+                if (parts.length < 2) continue;
+                const [setName, propName] = parts;
+                const hasIt = allItems.some((item) => item.propertySets?.[setName]?.[propName]?.value !== undefined);
+                if (!hasIt) {
+                    warnings.push(`Template references property '${path}' but no items provide it.`);
+                }
+            }
+        }
+
+        if (reqs.usesRemoteAssets && !template.allowRemoteAssets && !options?.allowRemoteAssets) {
+            warnings.push('Template uses remote assets but allowRemoteAssets is not enabled.');
+        }
+
+        // Build metadata from product entries (same as standard path)
+        const metadataEntries = options?.productEntries ?? [];
+        const metadataById = buildMetadataMap(metadataEntries);
+
+        const result = await renderLayout(template, layoutData, input.models, {
+            allowRemoteAssets: template.allowRemoteAssets ?? options?.allowRemoteAssets,
+            qrContext: options?.qrContext,
+            metadataById
+        });
+
+        return {
+            svg: result.svg,
+            warnings: [...warnings, ...result.warnings]
+        };
+    }
+
+    // ---- Standard path: build models from section results ----
+    if (!input.sections) {
+        return { svg: '', warnings: ['Either sections or models must be provided.'] };
+    }
+
+    const { buildSectionStateForEntries } = getSections();
+    const { sampleProductColorRgba, buildRoomLabels } = getGeometry();
+
+    // Normalize sections: single SectionResult → map to all viewports
+    const isSingle = !!(input.sections as SectionResult).perProduct;
+    const sections: Record<string, SectionResult> = isSingle
+        ? Object.fromEntries(viewports.map((vp) => [vp.id, input.sections as SectionResult]))
+        : (input.sections as Record<string, SectionResult>);
+
+    // Auto-detect whether the template has its own labels elements.
+    // If so, do NOT embed labels in the section SVG (would cause duplicates).
+    const hasTemplateLabelElements = template.elements.some((el) => el.kind === 'labels');
+    const roomLabelCfg = hasTemplateLabelElements ? undefined : options?.roomLabels;
+
+    // ---- Build section state + model view per viewport ----
+    const models: Record<string, SvgModelView> = {};
+    const entriesByViewport: Record<string, SectionResult['perProduct']> = {};
+    const sectionStateCache = new Map<string, SectionRenderState | null>();
+
+    for (const vp of viewports) {
+        const sectionResult = sections[vp.id];
+        if (!sectionResult?.perProduct?.length) {
+            warnings.push(`No section data for viewport '${vp.id}'.`);
+            continue;
+        }
+
+        entriesByViewport[vp.id] = sectionResult.perProduct;
+
+        // Dedup: skip if already built for this viewport key
+        if (sectionStateCache.has(vp.id)) {
+            const cached = sectionStateCache.get(vp.id);
+            if (cached) {
+                models[vp.id] = sectionStateToModelView(cached);
+            }
+            continue;
+        }
+
+        const resolved = resolveLineStyles(vp);
+
+        // Estimate label font size from template style and section bounds
+        const labelFontSize = estimateLabelFontSize(template, vp, sectionResult.perProduct);
+
+        // Extract clip polygon from section results if clip config is present
+        let clipPolygon: Array<Array<{ x: number; z: number }>> | undefined;
+        if (vp.clip?.where && vp.clip.class) {
+            const clipClass = Array.isArray(vp.clip.class) ? vp.clip.class : [vp.clip.class];
+            const clipEntries = sectionResult.perProduct.filter((entry: any) => {
+                const product = entry.product;
+                const matchesClass = clipClass.some((c: string) => product.class?.is?.(c));
+                if (!matchesClass) return false;
+                // Match where condition using T8-aware property resolution
+                for (const [path, expected] of Object.entries(vp.clip!.where!)) {
+                    const actualValue = resolveProductProperty(product, path);
+                    if (actualValue === undefined) return false;
+                    if (actualValue !== expected) return false;
+                }
+                return true;
+            });
+            if (clipEntries.length) {
+                clipPolygon = clipEntries.flatMap((entry: any) =>
+                    (entry.polylines || []).map((pl: any) => (pl.points || []).map((p: any) => ({ x: p.x, z: p.z })))
+                );
+            }
+        }
+
+        // Convert planeNormal array to object with x, y, z if present
+        let planeNormal: unknown = undefined;
+        if (vp.planeNormal && Array.isArray(vp.planeNormal) && vp.planeNormal.length === 3) {
+            planeNormal = { x: vp.planeNormal[0], y: vp.planeNormal[1], z: vp.planeNormal[2] };
+        }
+
+        type SectionStateWithRaw = SectionRenderState & { rawPaths?: SectionPath[]; rawLabels?: SectionLabel[] };
+        const state: SectionStateWithRaw | null = buildSectionStateForEntries(sectionResult.perProduct, {
+            strokeWidth: resolved.default.widthMm,
+            labelFontSize,
+            fills: vp.fills,
+            includeMeta: true,
+            includeLabels: !!roomLabelCfg,
+            buildLabels: roomLabelCfg
+                ? (products, fontSize) =>
+                      buildRoomLabels(products, fontSize, {
+                          labelPath: roomLabelCfg.labelPath,
+                          classFilter: roomLabelCfg.classFilter
+                      })
+                : undefined,
+            clipPolygon,
+            planeNormal
+        });
+
+        sectionStateCache.set(vp.id, state);
+
+        if (!state) {
+            warnings.push(`No geometry for viewport '${vp.id}'.`);
+            continue;
+        }
+
+        // Apply line style overrides from viewport config
+        let finalState: SectionStateWithRaw = state;
+        const defaultStyle = resolved.default;
+        if (defaultStyle.color || defaultStyle.widthMm) {
+            const style: { stroke?: string; strokeWidth?: number } = {};
+            if (defaultStyle.color) style.stroke = defaultStyle.color;
+            if (defaultStyle.widthMm) style.strokeWidth = defaultStyle.widthMm;
+            finalState = {
+                ...state,
+                paths: applyLineStyleToPaths(state.paths, style)
+            };
+            if (state.rawPaths) {
+                finalState.rawPaths = applyLineStyleToPaths(state.rawPaths, style);
+            }
+        }
+
+        const labelStyle: LabelStyle | undefined = template.styles?.body
+            ? {
+                  fill: template.styles.body.color ?? BUILTIN_LABEL_DEFAULTS.fill,
+                  fontFamily: template.styles.body.fontFamily ?? BUILTIN_LABEL_DEFAULTS.fontFamily,
+                  fontWeight: template.styles.body.fontWeight ?? BUILTIN_LABEL_DEFAULTS.fontWeight
+              }
+            : undefined;
+
+        models[vp.id] = sectionStateToModelView(finalState, labelStyle);
+    }
+
+    // ---- Build items per viewport ----
+    const viewportsData: Record<string, { items: NormalizedProductItem[] }> = {};
+
+    for (const vp of viewports) {
+        const entries = entriesByViewport[vp.id];
+        if (!entries) {
+            viewportsData[vp.id] = { items: [] };
+            continue;
+        }
+
+        viewportsData[vp.id] = { items: buildItemsFromEntries(entries, vp.fills, sampleProductColorRgba) };
+    }
+
+    // ---- Build metadata from all section entries ----
+    const allEntries = Object.values(entriesByViewport).flat();
+    const metadataById = buildMetadataMap(allEntries);
+
+    // ---- Assemble layout data ----
+    const layoutData = {
+        viewports: viewportsData
+    };
+
+    // ---- Render ----
+    const result = await renderLayout(template, layoutData, models, {
+        allowRemoteAssets: template.allowRemoteAssets ?? options?.allowRemoteAssets,
+        qrContext: options?.qrContext,
+        metadataById
+    });
+
+    return {
+        svg: result.svg,
+        warnings: [...warnings, ...result.warnings]
+    };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Build NormalizedProductItems from per-product entries.
+ *
+ * Shared between the standard path (plane sections) and the models path
+ * (slab sections / pre-built models with productEntries).
+ */
+function buildItemsFromEntries(
+    entries: Array<{ product: unknown; polylines: unknown }>,
+    fills: FillRule[] | undefined,
+    sampleColor: ((product: unknown) => SampledColor | undefined) | undefined
+): NormalizedProductItem[] {
+    return entries.map((entry) => {
+        const product = entry.product;
+        const propertySets = normalizePropertySets(product);
+        const gid = getProp(product, 'gid') ?? getProp(product, 'id');
+        const center = computePolylinesCenter(entry);
+        const name = getProp(product, 'name') as string | undefined;
+        const displayName = typeof name === 'string' && name.trim().length ? name.trim() : gid ? String(gid) : '-';
+        const item: NormalizedProductItem = {
+            gid: gid ? String(gid) : undefined,
+            ifcClass: resolveIfcClassName(product),
+            ifcClassId: resolveIfcClassId(product),
+            propertySets,
+            productId: gid ? String(gid) : '-',
+            productName: displayName,
+            area: null,
+            x: center.x,
+            z: center.z,
+            text: displayName,
+            polylines: entry.polylines as Array<{ points?: Array<{ x: number; z: number }> }>
+        };
+
+        if (fills?.length && sampleColor) {
+            const color = resolveFillColor(item, product, fills, sampleColor);
+            if (color) {
+                item.color = color;
+            }
+        }
+
+        return item;
+    });
+}
+
+/**
+ * Estimate label font size in model units from the template body style and the
+ * approximate viewport-to-world scale ratio.
+ */
+function estimateLabelFontSize(
+    template: LayoutTemplate,
+    vp: ViewportElement,
+    perProduct: SectionResult['perProduct']
+): number {
+    const templateFontSizeMm = template.styles?.body?.fontSizeMm ?? 3.5;
+
+    // Quick world-bounds scan
+    let minX = Infinity;
+    let maxX = -Infinity;
+    let minZ = Infinity;
+    let maxZ = -Infinity;
+    for (const entry of perProduct) {
+        if (!entry.polylines) continue;
+        for (const polyline of entry.polylines) {
+            if (!polyline.points) continue;
+            for (const pt of polyline.points) {
+                const px = getProp(pt, 'x');
+                const pz = getProp(pt, 'z');
+                if (Number.isFinite(px) && Number.isFinite(pz)) {
+                    if ((px as number) < minX) minX = px as number;
+                    if ((px as number) > maxX) maxX = px as number;
+                    if ((pz as number) < minZ) minZ = pz as number;
+                    if ((pz as number) > maxZ) maxZ = pz as number;
+                }
+            }
+        }
+    }
+
+    const worldWidth = maxX - minX;
+    const worldHeight = maxZ - minZ;
+    if (!Number.isFinite(worldWidth) || worldWidth <= 0 || !Number.isFinite(worldHeight) || worldHeight <= 0) {
+        return templateFontSizeMm; // Fallback: 1:1 estimate
+    }
+
+    // Approximate mm-per-model-unit from the viewport dimensions
+    const scaleX = vp.widthMm / worldWidth;
+    const scaleY = vp.heightMm / worldHeight;
+    const mmPerModelUnit = Math.min(scaleX, scaleY);
+
+    if (!Number.isFinite(mmPerModelUnit) || mmPerModelUnit <= 0) {
+        return templateFontSizeMm;
+    }
+
+    return templateFontSizeMm / mmPerModelUnit;
+}
+
+// ---------------------------------------------------------------------------
+// Label style defaults
+// ---------------------------------------------------------------------------
+
+/** Built-in label style defaults when template body styles are partially set. */
+export const BUILTIN_LABEL_DEFAULTS = {
+    fill: '#374151',
+    fontFamily: '"Segoe UI", "Helvetica Neue", Arial, sans-serif',
+    fontWeight: '300'
+} as const;
+
+// ---------------------------------------------------------------------------
+// Line style defaults & resolution
+// ---------------------------------------------------------------------------
+
+/** Built-in defaults when neither lineStyles nor lineWidthMm/lineColor are set. */
+export const BUILTIN_LINE_DEFAULTS: Required<ViewportLineStyle> = {
+    widthMm: 0.35, // Reasonable default: 0.35mm line width (was 0.01mm - too thin!)
+    color: '#1f2937',
+    dash: '',
+    enabled: true
+};
+
+export const BUILTIN_HIDDEN_DEFAULTS: Required<ViewportLineStyle> = {
+    widthMm: 0.005,
+    color: '#9ca3af',
+    dash: '4 2',
+    enabled: true
+};
+
+type LineCategory =
+    | 'cutLines'
+    | 'visibleLines'
+    | 'hiddenLines'
+    | 'silhouettes'
+    | 'featureEdges'
+    | 'stairArrows'
+    | 'outlineVisible'
+    | 'outlineHidden';
+
+/** Category-specific built-in defaults (merged over the global default). */
+export const CATEGORY_BUILTIN_OVERRIDES: Partial<Record<LineCategory, Partial<ViewportLineStyle>>> = {
+    cutLines: { widthMm: 0.02 },
+    hiddenLines: BUILTIN_HIDDEN_DEFAULTS,
+    outlineHidden: BUILTIN_HIDDEN_DEFAULTS
+};
+
+export interface ResolvedLineStyles {
+    default: Required<ViewportLineStyle>;
+    byCategory: Record<LineCategory, Required<ViewportLineStyle>>;
+}
+
+/**
+ * Resolve the effective line style for every category.
+ *
+ * Priority: category entry in `lineStyles` → `lineStyles.default`
+ *         → `lineWidthMm`/`lineColor` shorthand → built-in defaults.
+ */
+function resolveLineStyles(vp: ViewportElement): ResolvedLineStyles {
+    const ls = vp.lineStyles;
+
+    // Base default: lineStyles.default → shorthand → built-in
+    const base: Required<ViewportLineStyle> = {
+        ...BUILTIN_LINE_DEFAULTS,
+        ...(vp.lineWidthMm !== undefined ? { widthMm: vp.lineWidthMm } : {}),
+        ...(vp.lineColor !== undefined ? { color: vp.lineColor } : {}),
+        ...(ls?.default ?? {})
+    } as Required<ViewportLineStyle>;
+
+    const categories: LineCategory[] = [
+        'cutLines',
+        'visibleLines',
+        'hiddenLines',
+        'silhouettes',
+        'featureEdges',
+        'stairArrows',
+        'outlineVisible',
+        'outlineHidden'
+    ];
+
+    // Category group mapping: individual categories inherit from their group style
+    const categoryGroups: Record<LineCategory, LineCategory> = {
+        cutLines: 'visibleLines',
+        visibleLines: 'visibleLines',
+        silhouettes: 'visibleLines',
+        featureEdges: 'visibleLines',
+        outlineVisible: 'visibleLines',
+        hiddenLines: 'hiddenLines',
+        outlineHidden: 'hiddenLines',
+        stairArrows: 'stairArrows'
+    };
+
+    const byCategory = {} as Record<LineCategory, Required<ViewportLineStyle>>;
+    for (const cat of categories) {
+        const builtinOverride = CATEGORY_BUILTIN_OVERRIDES[cat];
+        const groupName = categoryGroups[cat];
+        const groupStyle = ls?.[groupName]; // Group style (visibleLines, hiddenLines, stairArrows)
+        const categoryOverride = ls?.[cat]; // Individual category settings (enable/disable)
+
+        byCategory[cat] = {
+            ...base,
+            ...(builtinOverride ?? {}),
+            ...(groupStyle ?? {}), // Apply group style first
+            ...(categoryOverride ?? {}) // Then individual overrides (enable/disable)
+        } as Required<ViewportLineStyle>;
+    }
+
+    return { default: base, byCategory };
+}
+
+// ---------------------------------------------------------------------------
+// Fill rule helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve fill color for an item based on viewport fill rules.
+ * Returns an RGBA tuple [r, g, b, a] (0–255) or undefined if no rule matches.
+ */
+export function resolveFillColor(
+    item: NormalizedProductItem,
+    product: unknown,
+    fills: FillRule[] | undefined,
+    sampleColor: (product: unknown) => SampledColor | undefined
+): [number, number, number, number] | undefined {
+    if (!fills?.length) return undefined;
+    for (const rule of fills) {
+        if (!matchesV2Filter(item, rule.class, rule.where)) continue;
+        if (rule.fill === 'sample') {
+            const sampled = sampleColor(product);
+            if (sampled) {
+                return [
+                    Math.round(sampled.color.r * 255),
+                    Math.round(sampled.color.g * 255),
+                    Math.round(sampled.color.b * 255),
+                    Math.round(sampled.alpha * 255)
+                ];
+            }
+        } else {
+            return parseHexToRgba(rule.fill);
+        }
+        break; // first matching rule wins
+    }
+    return undefined;
+}
+
+/**
+ * Parse a CSS hex color string to an RGBA tuple (0–255).
+ */
+function parseHexToRgba(hex: string): [number, number, number, number] {
+    const h = hex.replace(/^#/, '');
+    if (h.length === 3) {
+        return [parseInt(h[0] + h[0], 16), parseInt(h[1] + h[1], 16), parseInt(h[2] + h[2], 16), 255];
+    }
+    if (h.length === 6) {
+        return [parseInt(h.substring(0, 2), 16), parseInt(h.substring(2, 4), 16), parseInt(h.substring(4, 6), 16), 255];
+    }
+    if (h.length === 8) {
+        return [
+            parseInt(h.substring(0, 2), 16),
+            parseInt(h.substring(2, 4), 16),
+            parseInt(h.substring(4, 6), 16),
+            parseInt(h.substring(6, 8), 16)
+        ];
+    }
+    // Fallback: opaque black
+    return [0, 0, 0, 255];
+}