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

package/src/layout/types.ts

@@ -1,835 +1,835 @@
-import type { SectionPath, SectionLabel } from '@twinfinity/geometry';
-
-export type PagePresetKey = 'a1' | 'a3' | 'a4';
-export type PageOrientation = 'portrait' | 'landscape';
-
-export interface PageSpec {
-    widthMm: number;
-    heightMm: number;
-    marginMm?: number;
-    backgroundColor?: string;
-}
-
-export interface TextStyle {
-    fontFamily: string;
-    fontSizeMm: number;
-    fontWeight?: 'normal' | 'bold' | 'lighter' | 'bolder' | string;
-    color?: string;
-    letterSpacingMm?: number;
-    lineHeightMm?: number;
-}
-
-export interface StyleMap {
-    [styleName: string]: TextStyle;
-}
-
-export interface AssetSpec {
-    id: string;
-    src?: string;
-    content?: string;
-}
-
-export type WhereCondition = Record<string, string | number | boolean | Array<string | number>>;
-
-export interface ClipConfig {
-    class?: string | string[];
-    where: WhereCondition;
-    expandByM?: number;
-    clipLabels?: boolean;
-    stroke?: string;
-    strokeWidthMm?: number;
-    strokeOpacity?: number;
-    fill?: string;
-    fillOpacity?: number;
-}
-
-/**
- * Template-driven fill rule for a viewport.
- *
- * Fill rules control which products get filled polygons in the drawing.
- * When no `fills` array is present on a viewport, no fills are rendered.
- *
- * Example:
- * ```json
- * { "class": "space", "fill": "sample", "fillOpacity": 0.35 }
- * { "class": "walls", "fill": "#cccccc", "fillOpacity": 0.5 }
- * ```
- */
-export interface FillRule {
-    /** IFC class filter (e.g. "space", "walls"). Matches ifcClass or ifcClassId. */
-    class?: string | string[];
-    /** Property-based filter (same as highlight/clip `where`). */
-    where?: WhereCondition;
-    /** Fill color: CSS hex (e.g. "#80c8b4"), "sample" to read from 3D model material, or "legend" to use colors assigned by legend. */
-    fill: string;
-    /** Fill opacity (0–1). Default: 0.35. */
-    fillOpacity?: number;
-    /** When true, only apply fill to items whose centroid is spatially inside the clip polygon.
-     *  Useful when expandByM reveals adjacent spaces that shouldn't be filled.
-     *  @default false */
-    matchClipFilter?: boolean;
-}
-
-export interface HighlightConfig {
-    class?: string | string[];
-    where: WhereCondition;
-    /** Only highlight items that also appear in the referenced viewport (i.e., intersect both planes). */
-    intersectsViewport?: string;
-    stroke?: string;
-    strokeWidthMm?: number;
-    strokeOpacity?: number;
-    fill?: string;
-    fillOpacity?: number;
-}
-
-export type LayoutElement =
-    | ViewportElement
-    | TextElement
-    | ImageElement
-    | LineElement
-    | RectElement
-    | CircleElement
-    | PolylineElement
-    | PolygonElement
-    | ScaleBarElement
-    | QrElement
-    | LabelsElement
-    | LegendElement
-    | GroupElement;
-
-export interface BaseElement {
-    kind: LayoutElement['kind'];
-    id: string;
-    zIndex?: number;
-}
-
-/** Style for a single line category in a viewport. */
-export interface ViewportLineStyle {
-    /** Line width in mm. */
-    widthMm?: number;
-    /** Line color (CSS color string). */
-    color?: string;
-    /** SVG dash array (e.g. "4 2"). */
-    dash?: string;
-    /** Whether this category is rendered. Default: true. */
-    enabled?: boolean;
-}
-
-/**
- * Per-category line styles for a viewport.
- *
- * Resolution order: category-specific → `default` → built-in defaults.
- *
- * Example:
- * ```json
- * {
- *   "default":     { "widthMm": 0.01, "color": "#1f2937" },
- *   "cutLines":    { "widthMm": 0.02, "color": "#000000" },
- *   "hiddenLines": { "widthMm": 0.005, "color": "#9ca3af", "dash": "4 2" }
- * }
- * ```
- */
-export interface ViewportLineStyles {
-    /** Fallback style for any category not explicitly listed. */
-    default?: ViewportLineStyle;
-    cutLines?: ViewportLineStyle;
-    visibleLines?: ViewportLineStyle;
-    hiddenLines?: ViewportLineStyle;
-    silhouettes?: ViewportLineStyle;
-    featureEdges?: ViewportLineStyle;
-    stairArrows?: ViewportLineStyle;
-    outlineVisible?: ViewportLineStyle;
-    outlineHidden?: ViewportLineStyle;
-}
-
-/**
- * Include filter for viewport geometry.
- *
- * Can be:
- * - String or string array: class names only
- * - Object with class + where: property-based filtering
- * - Preset reference: { preset: "presetName" }
- *
- * Examples:
- * ```json
- * "includeClasses": ["space", "walls"]
- * "includeClasses": [{ "class": "space", "where": { "BIP.spacetype": "ROOM" } }]
- * "includeClasses": { "preset": "defaultBuilding" }
- * ```
- */
-export type IncludeClassesFilter =
-    | string
-    | string[]
-    | { class?: string | string[]; where?: WhereCondition }
-    | { preset: string };
-
-/**
- * Resolved include filter (after preset expansion).
- * Either a simple class name or a class+where filter.
- */
-export type ResolvedIncludeFilter = string | { class?: string | string[]; where: WhereCondition };
-
-export interface ViewportElement extends BaseElement {
-    kind: 'viewport';
-    xMm: number;
-    yMm: number;
-    widthMm: number;
-    heightMm: number;
-    scaleMode?: 'fit' | 'fitAndRound' | 'fixed';
-    fixedScaleDenom?: number;
-    preferredScales?: number[];
-    scalePreset?: string;
-    align?: 'center' | 'topLeft';
-    rotationDeg?: number;
-    includeClasses?: IncludeClassesFilter | IncludeClassesFilter[];
-    /**
-     * Per-category line styles. When set, overrides `lineWidthMm`/`lineColor`.
-     * Use `lineStyles.default` for a single style across all categories,
-     * or specify individual categories (cutLines, hiddenLines, etc.).
-     */
-    lineStyles?: ViewportLineStyles;
-    /** Simple shorthand: default line width for all categories. Overridden by `lineStyles`. */
-    lineWidthMm?: number;
-    /** Simple shorthand: default line color for all categories. Overridden by `lineStyles`. */
-    lineColor?: string;
-    /**
-     * Fill rules controlling which products get filled polygons.
-     * When absent, no fills are rendered (default: no fill).
-     */
-    fills?: FillRule[];
-    northArrow?: { assetId: string; sizeMm?: number; offsetXMm?: number; offsetYMm?: number; rotationDeg?: number };
-    border?: { stroke?: string; strokeWidthMm?: number; dashed?: boolean };
-    clip?: ClipConfig;
-    highlight?: HighlightConfig;
-
-    // Section configuration (overrides app defaults if specified)
-    /**
-     * Override cutting plane height for horizontal plans (Y coordinate).
-     * If omitted, uses app default. Shorthand for planeNormal=[0,1,0], planePosition=cutHeight.
-     */
-    cutHeight?: number;
-    /**
-     * Override depth above/below cutting plane. If omitted, uses app default.
-     * Only applicable for SLAB mode (PLANE mode doesn't use depth).
-     */
-    depth?: { above?: number; below?: number };
-    /**
-     * Plane normal vector [x, y, z]. Automatically normalized.
-     * Takes precedence over cutHeight if both are specified.
-     * Examples:
-     * - [1, 0, 0] = vertical section perpendicular to X axis
-     * - [0, 1, 0] = horizontal plan (same as using cutHeight)
-     * - [0, 0, 1] = vertical section perpendicular to Z axis
-     * - [1, 0, 1] = diagonal section (will be normalized)
-     */
-    planeNormal?: [number, number, number];
-    /**
-     * Distance from origin along the (normalized) plane normal.
-     * Used with planeNormal to define the cutting plane.
-     * The plane passes through the point: normalize(planeNormal) * planePosition.
-     */
-    planePosition?: number;
-    /**
-     * Section computation mode: 'slab' or 'plane'.
-     * - 'slab': Optimized for horizontal floor plans. Uses depth above/below to include geometry.
-     * - 'plane': Arbitrary plane cuts (vertical sections, diagonal sections). Computes exact intersection.
-     *
-     * If omitted, mode is auto-detected from plane orientation:
-     * - Horizontal planes (planeNormal ≈ Y-axis) → 'slab'
-     * - Vertical or diagonal planes → 'plane'
-     */
-    mode?: 'slab' | 'plane';
-}
-
-export interface TextElement extends BaseElement {
-    kind: 'text';
-    xMm: number;
-    yMm: number;
-    textStyle?: string;
-    text: string;
-    maxWidthMm?: number;
-    align?: 'left' | 'center' | 'right';
-}
-
-export interface ImageElement extends BaseElement {
-    kind: 'image';
-    xMm: number;
-    yMm: number;
-    widthMm: number;
-    heightMm: number;
-    assetId: string;
-    fit?: 'contain' | 'cover' | 'stretch';
-}
-
-export interface LineElement extends BaseElement {
-    kind: 'line';
-    x1Mm: number;
-    y1Mm: number;
-    x2Mm: number;
-    y2Mm: number;
-    stroke?: string;
-    strokeWidthMm?: number;
-    dashed?: boolean;
-}
-
-export interface RectElement extends BaseElement {
-    kind: 'rect';
-    xMm: number;
-    yMm: number;
-    widthMm: number;
-    heightMm: number;
-    stroke?: string;
-    strokeWidthMm?: number;
-    fill?: string;
-    dashed?: boolean;
-}
-
-export interface CircleElement extends BaseElement {
-    kind: 'circle';
-    cxMm: number;
-    cyMm: number;
-    rMm: number;
-    stroke?: string;
-    strokeWidthMm?: number;
-    fill?: string;
-    dashed?: boolean;
-}
-
-export interface PointMm {
-    xMm: number;
-    yMm: number;
-}
-
-export interface PolylineElement extends BaseElement {
-    kind: 'polyline';
-    points: PointMm[];
-    stroke: string;
-    strokeWidthMm: number;
-    dashed?: boolean;
-}
-
-export interface PolygonElement extends BaseElement {
-    kind: 'polygon';
-    points: PointMm[];
-    stroke?: string;
-    strokeWidthMm?: number;
-    fill?: string;
-    dashed?: boolean;
-}
-
-export interface ScaleBarElement extends BaseElement {
-    kind: 'scaleBar';
-    xMm: number;
-    yMm: number;
-    maxLengthMm: number;
-    unit?: string;
-    segments?: number;
-    labelEvery?: number;
-    stroke?: string;
-    strokeWidthMm?: number;
-    textStyle?: string;
-    viewport?: string;
-}
-
-export interface QrElement extends BaseElement {
-    kind: 'qr';
-    xMm: number;
-    yMm: number;
-    sizeMm: number;
-    role?: 'main' | 'anchor' | 'custom';
-    anchorCorner?: 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right';
-    viewport?: string;
-    dataTemplate?: string;
-}
-
-export interface LabelsElement extends BaseElement {
-    kind: 'labels';
-    viewport: string;
-    class?: string | string[];
-    where?: WhereCondition;
-    text: string;
-    textStyle?: string;
-    align?: 'left' | 'center' | 'right';
-    maxWidthMm?: number;
-    /** When true, only show labels for items whose position is spatially inside the clip polygon.
-     *  @default false */
-    matchClipFilter?: boolean;
-}
-
-export type LegendAnchor = 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left';
-
-export interface LegendColumn {
-    id: string;
-    label: string;
-    property: string;
-    format?: { digits?: number; prefix?: string; suffix?: string };
-    align?: 'left' | 'center' | 'right';
-    minWidthMm?: number;
-    maxWidthMm?: number;
-    /**
-     * Enable summary (total) calculation for this column.
-     * When true, the summary row will show the sum of all values in this column.
-     * Only works for numerical columns.
-     * @default false
-     */
-    summary?: boolean;
-}
-
-export interface LegendElement extends BaseElement {
-    kind: 'legend';
-    viewport: string;
-    class?: string | string[];
-    where?: WhereCondition;
-    clipToViewport?: boolean;
-    anchor?: LegendAnchor;
-    anchorPositionMm?: { xMm: number; yMm: number };
-    marginMm?: number;
-    textStyle?: string;
-    showColorColumn?: boolean;
-    colorColumnWidthMm?: number;
-    cellPaddingMm?: number;
-    borderStrokeWidthMm?: number;
-    borderStrokeColor?: string;
-    gridStrokeWidthMm?: number;
-    gridStrokeColor?: string;
-    headerStrokeWidthMm?: number;
-    headerStrokeColor?: string;
-    columns: LegendColumn[];
-    /**
-     * Summary row configuration.
-     * Displays a totals row at the bottom of the legend.
-     * Columns with `summary: true` will show their sum in the summary row.
-     *
-     * @example
-     * ```json
-     * {
-     *   "summary": {
-     *     "enabled": true,
-     *     "label": "Total"
-     *   },
-     *   "columns": [
-     *     { "id": "name", "label": "Room", "property": "BIP.spacename" },
-     *     { "id": "area", "label": "Area", "property": "BIP.area", "summary": true }
-     *   ]
-     * }
-     * ```
-     */
-    summary?: {
-        /** Enable summary row. */
-        enabled: boolean;
-        /** Label for first column in summary row. Defaults to "Total". */
-        label?: string;
-    };
-    /**
-     * Group legend rows by a specific column property.
-     * When enabled, rows with identical values in the groupBy column are consolidated into a single row.
-     * Numerical columns are summed across grouped rows; non-numerical columns take the first value.
-     *
-     * @example
-     * ```json
-     * {
-     *   "groupBy": "BIP.spacename",
-     *   "columns": [
-     *     { "id": "name", "label": "Room", "property": "BIP.spacename" },
-     *     { "id": "area", "label": "Area", "property": "BIP.area", "format": { "digits": 2 } }
-     *   ]
-     * }
-     * ```
-     * This groups all rooms with the same name and sums their areas.
-     */
-    groupBy?: string;
-    /**
-     * Assign colors to legend rows and apply them to the referenced viewport.
-     * When enabled, generates colors for each legend row (or group if groupBy is used).
-     * The viewport can use these colors by setting fill: "legend" in its fill rules.
-     *
-     * @example
-     * ```json
-     * {
-     *   "assignColors": {
-     *     "enabled": true,
-     *     "palette": "auto"
-     *   },
-     *   "groupBy": "BIP.spacename"
-     * }
-     * ```
-     * Generates distinct colors for each room type, applied to matching spaces in viewport.
-     */
-    assignColors?: {
-        /** Enable color assignment to viewport items. */
-        enabled: boolean;
-        /** Color palette: "auto" for auto-generated colors, or array of hex colors. */
-        palette?: 'auto' | string[];
-    };
-}
-
-export interface GroupTransform {
-    translateXMm?: number;
-    translateYMm?: number;
-    rotateDeg?: number;
-    scaleX?: number;
-    scaleY?: number;
-}
-
-export interface GroupClipRect {
-    type: 'rect';
-    xMm: number;
-    yMm: number;
-    widthMm: number;
-    heightMm: number;
-}
-
-export interface GroupElement extends BaseElement {
-    kind: 'group';
-    opacity?: number;
-    transform?: GroupTransform;
-    clip?: GroupClipRect;
-    children: LayoutElement[];
-}
-
-/**
- * Template variable definition.
- *
- * Variables allow templates to be parameterized and reused with different values.
- * All variables MUST have a default value to ensure templates work without user input.
- *
- * Variables are referenced in templates using {{vars.variableName}} syntax.
- *
- * Example:
- * ```json
- * {
- *   "variables": {
- *     "hyresobjektsnummer": {
- *       "type": "string",
- *       "default": "2022-F2008",
- *       "label": "Hyresobjekt Number",
- *       "description": "The rental object identifier"
- *     }
- *   },
- *   "elements": [
- *     {
- *       "kind": "text",
- *       "text": "Hyresobjekt: {{vars.hyresobjektsnummer}}"
- *     }
- *   ]
- * }
- * ```
- */
-export interface TemplateVariableDef {
-    /** Variable type. Determines validation and UI control type. */
-    type: 'string' | 'number' | 'boolean' | 'array';
-
-    /**
-     * Default value for this variable.
-     * REQUIRED - ensures template always works even without user input.
-     * Must match the specified type.
-     */
-    default: any;
-
-    /** Human-readable label for UI generation. Defaults to variable name. */
-    label?: string;
-
-    /** Description/help text for UI generation. */
-    description?: string;
-
-    /**
-     * Semantic format hint for UI generation.
-     * Provides additional context for rendering appropriate controls.
-     *
-     * - `color`: Renders color picker (for type: 'string')
-     * - `email`: Renders email input with validation (for type: 'string')
-     * - `url`: Renders URL input with validation (for type: 'string')
-     * - `date`: Renders date picker (for type: 'string')
-     *
-     * @example
-     * ```json
-     * {
-     *   "lineColor": {
-     *     "type": "string",
-     *     "format": "color",
-     *     "default": "#1f2937"
-     *   }
-     * }
-     * ```
-     */
-    format?: 'color' | 'email' | 'url' | 'date';
-
-    // String validation
-    /** Minimum string length (for type: 'string'). */
-    minLength?: number;
-    /** Maximum string length (for type: 'string'). */
-    maxLength?: number;
-    /** Regex pattern for validation (for type: 'string'). */
-    pattern?: string;
-    /** Allowed values (dropdown options). */
-    enum?: string[];
-
-    // Number validation
-    /** Minimum value (for type: 'number'). */
-    min?: number;
-    /** Maximum value (for type: 'number'). */
-    max?: number;
-    /** Step size for UI controls (for type: 'number'). */
-    step?: number;
-
-    // Array validation
-    /** Array item specification (for type: 'array'). */
-    items?: {
-        type: 'string' | 'number';
-        enum?: any[];
-    };
-}
-
-/**
- * Variable information extracted from template for UI generation.
- */
-export interface TemplateVariableInfo {
-    name: string;
-    type: 'string' | 'number' | 'boolean' | 'array';
-    default: any;
-    label: string;
-    description?: string;
-    format?: 'color' | 'email' | 'url' | 'date';
-    min?: number;
-    max?: number;
-    step?: number;
-    minLength?: number;
-    maxLength?: number;
-    pattern?: string;
-    enum?: any[];
-    items?: {
-        type: 'string' | 'number';
-        enum?: any[];
-    };
-}
-
-export interface LayoutTemplate {
-    /** JSON Schema reference for editor autocompletion. Ignored at runtime. */
-    $schema?: string;
-    id?: string;
-
-    /**
-     * Template variables for parameterization.
-     *
-     * Variables allow templates to be reused with different values.
-     * All variables MUST have defaults - templates work without user input.
-     * Reference variables in template using {{vars.variableName}} syntax.
-     *
-     * Optional - templates without variables work as before (backward compatible).
-     */
-    variables?: Record<string, TemplateVariableDef>;
-
-    page: PageSpec;
-    styles?: StyleMap;
-    assets?: AssetSpec[];
-    elements: LayoutElement[];
-    presets?: {
-        includeClasses?: Record<string, string[]>;
-        scales?: Record<string, { preferredScales?: number[] }>;
-    };
-    /** Allow fetching remote assets (images, fonts). Default: false. */
-    allowRemoteAssets?: boolean;
-}
-
-export interface ModelMetadataEntry {
-    productId?: string;
-    ifcClass?: string;
-    properties?: any;
-    [key: string]: any;
-}
-
-export type ModelMetadata = Record<string, ModelMetadataEntry>;
-
-export interface ProductFieldPaths {
-    idPath?: string;
-    namePath?: string;
-    areaPath?: string;
-    classPath?: string;
-}
-
-export interface NormalizedProductItem {
-    gid?: string;
-    /** IfcClassType category (e.g. "space", "walls"). Used for template class filters. */
-    ifcClass?: string | null;
-    /** PredefinedIfcClassId (e.g. "IfcSpace", "IfcWall"). Used as fallback for class matching. */
-    ifcClassId?: string | null;
-    propertySets: Record<string, Record<string, { value: any; unit?: string; type?: string }>>;
-    productId: string;
-    productName: string;
-    area: number | null;
-    x?: number | null;
-    z?: number | null;
-    polylines?: Array<{ points?: Array<{ x: number; z: number }> }>;
-    [key: string]: any;
-}
-
-export type SectionStateValidationResult =
-    | { ok: true }
-    | {
-          ok: false;
-          errors: string[];
-      };
-
-export interface LabelStyle {
-    /** Text fill color. Default: "#374151" */
-    fill?: string;
-    /** Font family. Default: '"Segoe UI", "Helvetica Neue", Arial, sans-serif' */
-    fontFamily?: string;
-    /** Font weight. Default: "300" */
-    fontWeight?: string;
-}
-
-export interface SvgModelView {
-    groupSvg: string;
-    widthModel: number;
-    heightModel: number;
-    geometryTransform?: string;
-    transform?: {
-        viewMinX: number;
-        viewMaxX: number;
-        viewMinZ: number;
-        viewMaxZ: number;
-        viewWidth: number;
-        viewHeight: number;
-    };
-    rawPaths?: SectionPath[];
-    rawLabels?: SectionLabel[];
-    labelStyle?: LabelStyle;
-}
-
-export type ModelContext = Record<string, SvgModelView>;
-export type LayoutData = Record<string, any>;
-export type ViewportItemsMap = Record<string, { items: NormalizedProductItem[] }>;
-export type LayoutDataViewports = { viewports: ViewportItemsMap } & Record<string, any>;
-
-export interface ValidationOptions {
-    allowRemoteAssets?: boolean;
-    allowDataUrls?: boolean;
-    maxViewports?: number;
-}
-
-export interface ValidationIssue {
-    path: string;
-    message: string;
-}
-
-export type ValidationResult = { ok: true; template: any } | { ok: false; errors: ValidationIssue[] };
-
-export interface ComputedViewportScale {
-    denom: number;
-    mmPerModelUnit: number;
-    fits: boolean;
-}
-
-export interface SectionResult {
-    perProduct: Array<{
-        product: any;
-        segments: Array<[any, any]>;
-        polylines: Array<{ points: any[]; closed: boolean }>;
-    }>;
-}
-
-export interface RenderDrawingInput {
-    template: LayoutTemplate;
-    /**
-     * Section geometry to render.
-     *
-     * - Pass a single `SectionResult` to use the same geometry for every viewport.
-     * - Pass a `Record<string, SectionResult>` keyed by viewport ID for per-viewport control.
-     *
-     * Either `sections` or `models` must be provided. When `models` is provided,
-     * `sections` is ignored and the pre-built SvgModelViews are used directly.
-     */
-    sections?: SectionResult | Record<string, SectionResult>;
-    /**
-     * Pre-built model views keyed by viewport ID.
-     *
-     * Use this when geometry comes from a source other than `computePlaneSection`
-     * (e.g. SlabSection). The caller is responsible for producing `SvgModelView`
-     * objects; `renderDrawing` will pass them straight to `renderLayout`.
-     */
-    models?: ModelContext;
-    options?: {
-        allowRemoteAssets?: boolean;
-        qrContext?: {
-            host?: string | null;
-            containerName?: string | null;
-            floorName?: string | null;
-            planeHeight?: number | null;
-        };
-        /**
-         * Embed room labels directly in the section SVG.
-         *
-         * Only use this when the template does NOT have its own `labels` elements,
-         * otherwise you will get duplicate labels. When omitted, renderDrawing
-         * auto-detects template `labels` elements and skips embedding.
-         */
-        roomLabels?: {
-            /** Dot-separated path to the label text under product.properties.data. */
-            labelPath: string;
-            /** IFC class name filter (e.g. "space"). If omitted, all entries are included. */
-            classFilter?: string;
-        };
-        /**
-         * Raw per-product entries for automatic item building when using `models`.
-         *
-         * Each entry needs a `product` (BIM object with gid, name, class, properties)
-         * and `polylines` (for centroid computation and fill polygon rendering).
-         *
-         * When provided, renderDrawing builds NormalizedProductItems per viewport,
-         * resolving fill colors from each viewport's fill rules. This replaces
-         * manual item construction in consumer code.
-         *
-         * Ignored when `viewportItems` is also provided (explicit items take priority).
-         */
-        productEntries?: Array<{
-            product: unknown;
-            polylines: Array<{ points: Array<{ x: number; z: number }> }>;
-        }>;
-        /**
-         * Pre-built product items when `models` is provided directly.
-         * Keyed by viewport ID, each containing an array of NormalizedProductItems.
-         * Used for legends, labels, and other template elements that need item data.
-         *
-         * Takes priority over `productEntries` when both are provided.
-         */
-        viewportItems?: Record<string, { items: NormalizedProductItem[] }>;
-        /**
-         * App default section settings. Used as fallback when viewports don't specify
-         * their own cutHeight/depth configuration.
-         */
-        sectionDefaults?: {
-            cutHeight?: number;
-            depth?: { above?: number; below?: number };
-        };
-        /**
-         * Template variable values.
-         *
-         * When template defines `variables`, provide values here to customize the output.
-         * Missing values automatically use defaults from template (fail-safe).
-         * Invalid values fall back to defaults with warnings.
-         *
-         * Optional - if not provided, all template defaults are used.
-         *
-         * @example
-         * ```typescript
-         * await renderDrawing({
-         *   template,
-         *   models,
-         *   options: {
-         *     variables: {
-         *       hyresobjektsnummer: '2022-F2009',
-         *       showLegend: true
-         *     }
-         *   }
-         * });
-         * ```
-         */
-        variables?: Record<string, any>;
-    };
-}
-
-export interface RenderDrawingResult {
-    svg: string;
-    warnings: string[];
-}
+import type { SectionPath, SectionLabel } from '@twinfinity/geometry';
+
+export type PagePresetKey = 'a1' | 'a3' | 'a4';
+export type PageOrientation = 'portrait' | 'landscape';
+
+export interface PageSpec {
+    widthMm: number;
+    heightMm: number;
+    marginMm?: number;
+    backgroundColor?: string;
+}
+
+export interface TextStyle {
+    fontFamily: string;
+    fontSizeMm: number;
+    fontWeight?: 'normal' | 'bold' | 'lighter' | 'bolder' | string;
+    color?: string;
+    letterSpacingMm?: number;
+    lineHeightMm?: number;
+}
+
+export interface StyleMap {
+    [styleName: string]: TextStyle;
+}
+
+export interface AssetSpec {
+    id: string;
+    src?: string;
+    content?: string;
+}
+
+export type WhereCondition = Record<string, string | number | boolean | Array<string | number>>;
+
+export interface ClipConfig {
+    class?: string | string[];
+    where: WhereCondition;
+    expandByM?: number;
+    clipLabels?: boolean;
+    stroke?: string;
+    strokeWidthMm?: number;
+    strokeOpacity?: number;
+    fill?: string;
+    fillOpacity?: number;
+}
+
+/**
+ * Template-driven fill rule for a viewport.
+ *
+ * Fill rules control which products get filled polygons in the drawing.
+ * When no `fills` array is present on a viewport, no fills are rendered.
+ *
+ * Example:
+ * ```json
+ * { "class": "space", "fill": "sample", "fillOpacity": 0.35 }
+ * { "class": "walls", "fill": "#cccccc", "fillOpacity": 0.5 }
+ * ```
+ */
+export interface FillRule {
+    /** IFC class filter (e.g. "space", "walls"). Matches ifcClass or ifcClassId. */
+    class?: string | string[];
+    /** Property-based filter (same as highlight/clip `where`). */
+    where?: WhereCondition;
+    /** Fill color: CSS hex (e.g. "#80c8b4"), "sample" to read from 3D model material, or "legend" to use colors assigned by legend. */
+    fill: string;
+    /** Fill opacity (0–1). Default: 0.35. */
+    fillOpacity?: number;
+    /** When true, only apply fill to items whose centroid is spatially inside the clip polygon.
+     *  Useful when expandByM reveals adjacent spaces that shouldn't be filled.
+     *  @default false */
+    matchClipFilter?: boolean;
+}
+
+export interface HighlightConfig {
+    class?: string | string[];
+    where: WhereCondition;
+    /** Only highlight items that also appear in the referenced viewport (i.e., intersect both planes). */
+    intersectsViewport?: string;
+    stroke?: string;
+    strokeWidthMm?: number;
+    strokeOpacity?: number;
+    fill?: string;
+    fillOpacity?: number;
+}
+
+export type LayoutElement =
+    | ViewportElement
+    | TextElement
+    | ImageElement
+    | LineElement
+    | RectElement
+    | CircleElement
+    | PolylineElement
+    | PolygonElement
+    | ScaleBarElement
+    | QrElement
+    | LabelsElement
+    | LegendElement
+    | GroupElement;
+
+export interface BaseElement {
+    kind: LayoutElement['kind'];
+    id: string;
+    zIndex?: number;
+}
+
+/** Style for a single line category in a viewport. */
+export interface ViewportLineStyle {
+    /** Line width in mm. */
+    widthMm?: number;
+    /** Line color (CSS color string). */
+    color?: string;
+    /** SVG dash array (e.g. "4 2"). */
+    dash?: string;
+    /** Whether this category is rendered. Default: true. */
+    enabled?: boolean;
+}
+
+/**
+ * Per-category line styles for a viewport.
+ *
+ * Resolution order: category-specific → `default` → built-in defaults.
+ *
+ * Example:
+ * ```json
+ * {
+ *   "default":     { "widthMm": 0.01, "color": "#1f2937" },
+ *   "cutLines":    { "widthMm": 0.02, "color": "#000000" },
+ *   "hiddenLines": { "widthMm": 0.005, "color": "#9ca3af", "dash": "4 2" }
+ * }
+ * ```
+ */
+export interface ViewportLineStyles {
+    /** Fallback style for any category not explicitly listed. */
+    default?: ViewportLineStyle;
+    cutLines?: ViewportLineStyle;
+    visibleLines?: ViewportLineStyle;
+    hiddenLines?: ViewportLineStyle;
+    silhouettes?: ViewportLineStyle;
+    featureEdges?: ViewportLineStyle;
+    stairArrows?: ViewportLineStyle;
+    outlineVisible?: ViewportLineStyle;
+    outlineHidden?: ViewportLineStyle;
+}
+
+/**
+ * Include filter for viewport geometry.
+ *
+ * Can be:
+ * - String or string array: class names only
+ * - Object with class + where: property-based filtering
+ * - Preset reference: { preset: "presetName" }
+ *
+ * Examples:
+ * ```json
+ * "includeClasses": ["space", "walls"]
+ * "includeClasses": [{ "class": "space", "where": { "BIP.spacetype": "ROOM" } }]
+ * "includeClasses": { "preset": "defaultBuilding" }
+ * ```
+ */
+export type IncludeClassesFilter =
+    | string
+    | string[]
+    | { class?: string | string[]; where?: WhereCondition }
+    | { preset: string };
+
+/**
+ * Resolved include filter (after preset expansion).
+ * Either a simple class name or a class+where filter.
+ */
+export type ResolvedIncludeFilter = string | { class?: string | string[]; where: WhereCondition };
+
+export interface ViewportElement extends BaseElement {
+    kind: 'viewport';
+    xMm: number;
+    yMm: number;
+    widthMm: number;
+    heightMm: number;
+    scaleMode?: 'fit' | 'fitAndRound' | 'fixed';
+    fixedScaleDenom?: number;
+    preferredScales?: number[];
+    scalePreset?: string;
+    align?: 'center' | 'topLeft';
+    rotationDeg?: number;
+    includeClasses?: IncludeClassesFilter | IncludeClassesFilter[];
+    /**
+     * Per-category line styles. When set, overrides `lineWidthMm`/`lineColor`.
+     * Use `lineStyles.default` for a single style across all categories,
+     * or specify individual categories (cutLines, hiddenLines, etc.).
+     */
+    lineStyles?: ViewportLineStyles;
+    /** Simple shorthand: default line width for all categories. Overridden by `lineStyles`. */
+    lineWidthMm?: number;
+    /** Simple shorthand: default line color for all categories. Overridden by `lineStyles`. */
+    lineColor?: string;
+    /**
+     * Fill rules controlling which products get filled polygons.
+     * When absent, no fills are rendered (default: no fill).
+     */
+    fills?: FillRule[];
+    northArrow?: { assetId: string; sizeMm?: number; offsetXMm?: number; offsetYMm?: number; rotationDeg?: number };
+    border?: { stroke?: string; strokeWidthMm?: number; dashed?: boolean };
+    clip?: ClipConfig;
+    highlight?: HighlightConfig;
+
+    // Section configuration (overrides app defaults if specified)
+    /**
+     * Override cutting plane height for horizontal plans (Y coordinate).
+     * If omitted, uses app default. Shorthand for planeNormal=[0,1,0], planePosition=cutHeight.
+     */
+    cutHeight?: number;
+    /**
+     * Override depth above/below cutting plane. If omitted, uses app default.
+     * Only applicable for SLAB mode (PLANE mode doesn't use depth).
+     */
+    depth?: { above?: number; below?: number };
+    /**
+     * Plane normal vector [x, y, z]. Automatically normalized.
+     * Takes precedence over cutHeight if both are specified.
+     * Examples:
+     * - [1, 0, 0] = vertical section perpendicular to X axis
+     * - [0, 1, 0] = horizontal plan (same as using cutHeight)
+     * - [0, 0, 1] = vertical section perpendicular to Z axis
+     * - [1, 0, 1] = diagonal section (will be normalized)
+     */
+    planeNormal?: [number, number, number];
+    /**
+     * Distance from origin along the (normalized) plane normal.
+     * Used with planeNormal to define the cutting plane.
+     * The plane passes through the point: normalize(planeNormal) * planePosition.
+     */
+    planePosition?: number;
+    /**
+     * Section computation mode: 'slab' or 'plane'.
+     * - 'slab': Optimized for horizontal floor plans. Uses depth above/below to include geometry.
+     * - 'plane': Arbitrary plane cuts (vertical sections, diagonal sections). Computes exact intersection.
+     *
+     * If omitted, mode is auto-detected from plane orientation:
+     * - Horizontal planes (planeNormal ≈ Y-axis) → 'slab'
+     * - Vertical or diagonal planes → 'plane'
+     */
+    mode?: 'slab' | 'plane';
+}
+
+export interface TextElement extends BaseElement {
+    kind: 'text';
+    xMm: number;
+    yMm: number;
+    textStyle?: string;
+    text: string;
+    maxWidthMm?: number;
+    align?: 'left' | 'center' | 'right';
+}
+
+export interface ImageElement extends BaseElement {
+    kind: 'image';
+    xMm: number;
+    yMm: number;
+    widthMm: number;
+    heightMm: number;
+    assetId: string;
+    fit?: 'contain' | 'cover' | 'stretch';
+}
+
+export interface LineElement extends BaseElement {
+    kind: 'line';
+    x1Mm: number;
+    y1Mm: number;
+    x2Mm: number;
+    y2Mm: number;
+    stroke?: string;
+    strokeWidthMm?: number;
+    dashed?: boolean;
+}
+
+export interface RectElement extends BaseElement {
+    kind: 'rect';
+    xMm: number;
+    yMm: number;
+    widthMm: number;
+    heightMm: number;
+    stroke?: string;
+    strokeWidthMm?: number;
+    fill?: string;
+    dashed?: boolean;
+}
+
+export interface CircleElement extends BaseElement {
+    kind: 'circle';
+    cxMm: number;
+    cyMm: number;
+    rMm: number;
+    stroke?: string;
+    strokeWidthMm?: number;
+    fill?: string;
+    dashed?: boolean;
+}
+
+export interface PointMm {
+    xMm: number;
+    yMm: number;
+}
+
+export interface PolylineElement extends BaseElement {
+    kind: 'polyline';
+    points: PointMm[];
+    stroke: string;
+    strokeWidthMm: number;
+    dashed?: boolean;
+}
+
+export interface PolygonElement extends BaseElement {
+    kind: 'polygon';
+    points: PointMm[];
+    stroke?: string;
+    strokeWidthMm?: number;
+    fill?: string;
+    dashed?: boolean;
+}
+
+export interface ScaleBarElement extends BaseElement {
+    kind: 'scaleBar';
+    xMm: number;
+    yMm: number;
+    maxLengthMm: number;
+    unit?: string;
+    segments?: number;
+    labelEvery?: number;
+    stroke?: string;
+    strokeWidthMm?: number;
+    textStyle?: string;
+    viewport?: string;
+}
+
+export interface QrElement extends BaseElement {
+    kind: 'qr';
+    xMm: number;
+    yMm: number;
+    sizeMm: number;
+    role?: 'main' | 'anchor' | 'custom';
+    anchorCorner?: 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right';
+    viewport?: string;
+    dataTemplate?: string;
+}
+
+export interface LabelsElement extends BaseElement {
+    kind: 'labels';
+    viewport: string;
+    class?: string | string[];
+    where?: WhereCondition;
+    text: string;
+    textStyle?: string;
+    align?: 'left' | 'center' | 'right';
+    maxWidthMm?: number;
+    /** When true, only show labels for items whose position is spatially inside the clip polygon.
+     *  @default false */
+    matchClipFilter?: boolean;
+}
+
+export type LegendAnchor = 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left';
+
+export interface LegendColumn {
+    id: string;
+    label: string;
+    property: string;
+    format?: { digits?: number; prefix?: string; suffix?: string };
+    align?: 'left' | 'center' | 'right';
+    minWidthMm?: number;
+    maxWidthMm?: number;
+    /**
+     * Enable summary (total) calculation for this column.
+     * When true, the summary row will show the sum of all values in this column.
+     * Only works for numerical columns.
+     * @default false
+     */
+    summary?: boolean;
+}
+
+export interface LegendElement extends BaseElement {
+    kind: 'legend';
+    viewport: string;
+    class?: string | string[];
+    where?: WhereCondition;
+    clipToViewport?: boolean;
+    anchor?: LegendAnchor;
+    anchorPositionMm?: { xMm: number; yMm: number };
+    marginMm?: number;
+    textStyle?: string;
+    showColorColumn?: boolean;
+    colorColumnWidthMm?: number;
+    cellPaddingMm?: number;
+    borderStrokeWidthMm?: number;
+    borderStrokeColor?: string;
+    gridStrokeWidthMm?: number;
+    gridStrokeColor?: string;
+    headerStrokeWidthMm?: number;
+    headerStrokeColor?: string;
+    columns: LegendColumn[];
+    /**
+     * Summary row configuration.
+     * Displays a totals row at the bottom of the legend.
+     * Columns with `summary: true` will show their sum in the summary row.
+     *
+     * @example
+     * ```json
+     * {
+     *   "summary": {
+     *     "enabled": true,
+     *     "label": "Total"
+     *   },
+     *   "columns": [
+     *     { "id": "name", "label": "Room", "property": "BIP.spacename" },
+     *     { "id": "area", "label": "Area", "property": "BIP.area", "summary": true }
+     *   ]
+     * }
+     * ```
+     */
+    summary?: {
+        /** Enable summary row. */
+        enabled: boolean;
+        /** Label for first column in summary row. Defaults to "Total". */
+        label?: string;
+    };
+    /**
+     * Group legend rows by a specific column property.
+     * When enabled, rows with identical values in the groupBy column are consolidated into a single row.
+     * Numerical columns are summed across grouped rows; non-numerical columns take the first value.
+     *
+     * @example
+     * ```json
+     * {
+     *   "groupBy": "BIP.spacename",
+     *   "columns": [
+     *     { "id": "name", "label": "Room", "property": "BIP.spacename" },
+     *     { "id": "area", "label": "Area", "property": "BIP.area", "format": { "digits": 2 } }
+     *   ]
+     * }
+     * ```
+     * This groups all rooms with the same name and sums their areas.
+     */
+    groupBy?: string;
+    /**
+     * Assign colors to legend rows and apply them to the referenced viewport.
+     * When enabled, generates colors for each legend row (or group if groupBy is used).
+     * The viewport can use these colors by setting fill: "legend" in its fill rules.
+     *
+     * @example
+     * ```json
+     * {
+     *   "assignColors": {
+     *     "enabled": true,
+     *     "palette": "auto"
+     *   },
+     *   "groupBy": "BIP.spacename"
+     * }
+     * ```
+     * Generates distinct colors for each room type, applied to matching spaces in viewport.
+     */
+    assignColors?: {
+        /** Enable color assignment to viewport items. */
+        enabled: boolean;
+        /** Color palette: "auto" for auto-generated colors, or array of hex colors. */
+        palette?: 'auto' | string[];
+    };
+}
+
+export interface GroupTransform {
+    translateXMm?: number;
+    translateYMm?: number;
+    rotateDeg?: number;
+    scaleX?: number;
+    scaleY?: number;
+}
+
+export interface GroupClipRect {
+    type: 'rect';
+    xMm: number;
+    yMm: number;
+    widthMm: number;
+    heightMm: number;
+}
+
+export interface GroupElement extends BaseElement {
+    kind: 'group';
+    opacity?: number;
+    transform?: GroupTransform;
+    clip?: GroupClipRect;
+    children: LayoutElement[];
+}
+
+/**
+ * Template variable definition.
+ *
+ * Variables allow templates to be parameterized and reused with different values.
+ * All variables MUST have a default value to ensure templates work without user input.
+ *
+ * Variables are referenced in templates using {{vars.variableName}} syntax.
+ *
+ * Example:
+ * ```json
+ * {
+ *   "variables": {
+ *     "hyresobjektsnummer": {
+ *       "type": "string",
+ *       "default": "2022-F2008",
+ *       "label": "Hyresobjekt Number",
+ *       "description": "The rental object identifier"
+ *     }
+ *   },
+ *   "elements": [
+ *     {
+ *       "kind": "text",
+ *       "text": "Hyresobjekt: {{vars.hyresobjektsnummer}}"
+ *     }
+ *   ]
+ * }
+ * ```
+ */
+export interface TemplateVariableDef {
+    /** Variable type. Determines validation and UI control type. */
+    type: 'string' | 'number' | 'boolean' | 'array';
+
+    /**
+     * Default value for this variable.
+     * REQUIRED - ensures template always works even without user input.
+     * Must match the specified type.
+     */
+    default: any;
+
+    /** Human-readable label for UI generation. Defaults to variable name. */
+    label?: string;
+
+    /** Description/help text for UI generation. */
+    description?: string;
+
+    /**
+     * Semantic format hint for UI generation.
+     * Provides additional context for rendering appropriate controls.
+     *
+     * - `color`: Renders color picker (for type: 'string')
+     * - `email`: Renders email input with validation (for type: 'string')
+     * - `url`: Renders URL input with validation (for type: 'string')
+     * - `date`: Renders date picker (for type: 'string')
+     *
+     * @example
+     * ```json
+     * {
+     *   "lineColor": {
+     *     "type": "string",
+     *     "format": "color",
+     *     "default": "#1f2937"
+     *   }
+     * }
+     * ```
+     */
+    format?: 'color' | 'email' | 'url' | 'date';
+
+    // String validation
+    /** Minimum string length (for type: 'string'). */
+    minLength?: number;
+    /** Maximum string length (for type: 'string'). */
+    maxLength?: number;
+    /** Regex pattern for validation (for type: 'string'). */
+    pattern?: string;
+    /** Allowed values (dropdown options). */
+    enum?: string[];
+
+    // Number validation
+    /** Minimum value (for type: 'number'). */
+    min?: number;
+    /** Maximum value (for type: 'number'). */
+    max?: number;
+    /** Step size for UI controls (for type: 'number'). */
+    step?: number;
+
+    // Array validation
+    /** Array item specification (for type: 'array'). */
+    items?: {
+        type: 'string' | 'number';
+        enum?: any[];
+    };
+}
+
+/**
+ * Variable information extracted from template for UI generation.
+ */
+export interface TemplateVariableInfo {
+    name: string;
+    type: 'string' | 'number' | 'boolean' | 'array';
+    default: any;
+    label: string;
+    description?: string;
+    format?: 'color' | 'email' | 'url' | 'date';
+    min?: number;
+    max?: number;
+    step?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    enum?: any[];
+    items?: {
+        type: 'string' | 'number';
+        enum?: any[];
+    };
+}
+
+export interface LayoutTemplate {
+    /** JSON Schema reference for editor autocompletion. Ignored at runtime. */
+    $schema?: string;
+    id?: string;
+
+    /**
+     * Template variables for parameterization.
+     *
+     * Variables allow templates to be reused with different values.
+     * All variables MUST have defaults - templates work without user input.
+     * Reference variables in template using {{vars.variableName}} syntax.
+     *
+     * Optional - templates without variables work as before (backward compatible).
+     */
+    variables?: Record<string, TemplateVariableDef>;
+
+    page: PageSpec;
+    styles?: StyleMap;
+    assets?: AssetSpec[];
+    elements: LayoutElement[];
+    presets?: {
+        includeClasses?: Record<string, string[]>;
+        scales?: Record<string, { preferredScales?: number[] }>;
+    };
+    /** Allow fetching remote assets (images, fonts). Default: false. */
+    allowRemoteAssets?: boolean;
+}
+
+export interface ModelMetadataEntry {
+    productId?: string;
+    ifcClass?: string;
+    properties?: any;
+    [key: string]: any;
+}
+
+export type ModelMetadata = Record<string, ModelMetadataEntry>;
+
+export interface ProductFieldPaths {
+    idPath?: string;
+    namePath?: string;
+    areaPath?: string;
+    classPath?: string;
+}
+
+export interface NormalizedProductItem {
+    gid?: string;
+    /** IfcClassType category (e.g. "space", "walls"). Used for template class filters. */
+    ifcClass?: string | null;
+    /** PredefinedIfcClassId (e.g. "IfcSpace", "IfcWall"). Used as fallback for class matching. */
+    ifcClassId?: string | null;
+    propertySets: Record<string, Record<string, { value: any; unit?: string; type?: string }>>;
+    productId: string;
+    productName: string;
+    area: number | null;
+    x?: number | null;
+    z?: number | null;
+    polylines?: Array<{ points?: Array<{ x: number; z: number }> }>;
+    [key: string]: any;
+}
+
+export type SectionStateValidationResult =
+    | { ok: true }
+    | {
+          ok: false;
+          errors: string[];
+      };
+
+export interface LabelStyle {
+    /** Text fill color. Default: "#374151" */
+    fill?: string;
+    /** Font family. Default: '"Segoe UI", "Helvetica Neue", Arial, sans-serif' */
+    fontFamily?: string;
+    /** Font weight. Default: "300" */
+    fontWeight?: string;
+}
+
+export interface SvgModelView {
+    groupSvg: string;
+    widthModel: number;
+    heightModel: number;
+    geometryTransform?: string;
+    transform?: {
+        viewMinX: number;
+        viewMaxX: number;
+        viewMinZ: number;
+        viewMaxZ: number;
+        viewWidth: number;
+        viewHeight: number;
+    };
+    rawPaths?: SectionPath[];
+    rawLabels?: SectionLabel[];
+    labelStyle?: LabelStyle;
+}
+
+export type ModelContext = Record<string, SvgModelView>;
+export type LayoutData = Record<string, any>;
+export type ViewportItemsMap = Record<string, { items: NormalizedProductItem[] }>;
+export type LayoutDataViewports = { viewports: ViewportItemsMap } & Record<string, any>;
+
+export interface ValidationOptions {
+    allowRemoteAssets?: boolean;
+    allowDataUrls?: boolean;
+    maxViewports?: number;
+}
+
+export interface ValidationIssue {
+    path: string;
+    message: string;
+}
+
+export type ValidationResult = { ok: true; template: any } | { ok: false; errors: ValidationIssue[] };
+
+export interface ComputedViewportScale {
+    denom: number;
+    mmPerModelUnit: number;
+    fits: boolean;
+}
+
+export interface SectionResult {
+    perProduct: Array<{
+        product: any;
+        segments: Array<[any, any]>;
+        polylines: Array<{ points: any[]; closed: boolean }>;
+    }>;
+}
+
+export interface RenderDrawingInput {
+    template: LayoutTemplate;
+    /**
+     * Section geometry to render.
+     *
+     * - Pass a single `SectionResult` to use the same geometry for every viewport.
+     * - Pass a `Record<string, SectionResult>` keyed by viewport ID for per-viewport control.
+     *
+     * Either `sections` or `models` must be provided. When `models` is provided,
+     * `sections` is ignored and the pre-built SvgModelViews are used directly.
+     */
+    sections?: SectionResult | Record<string, SectionResult>;
+    /**
+     * Pre-built model views keyed by viewport ID.
+     *
+     * Use this when geometry comes from a source other than `computePlaneSection`
+     * (e.g. SlabSection). The caller is responsible for producing `SvgModelView`
+     * objects; `renderDrawing` will pass them straight to `renderLayout`.
+     */
+    models?: ModelContext;
+    options?: {
+        allowRemoteAssets?: boolean;
+        qrContext?: {
+            host?: string | null;
+            containerName?: string | null;
+            floorName?: string | null;
+            planeHeight?: number | null;
+        };
+        /**
+         * Embed room labels directly in the section SVG.
+         *
+         * Only use this when the template does NOT have its own `labels` elements,
+         * otherwise you will get duplicate labels. When omitted, renderDrawing
+         * auto-detects template `labels` elements and skips embedding.
+         */
+        roomLabels?: {
+            /** Dot-separated path to the label text under product.properties.data. */
+            labelPath: string;
+            /** IFC class name filter (e.g. "space"). If omitted, all entries are included. */
+            classFilter?: string;
+        };
+        /**
+         * Raw per-product entries for automatic item building when using `models`.
+         *
+         * Each entry needs a `product` (BIM object with gid, name, class, properties)
+         * and `polylines` (for centroid computation and fill polygon rendering).
+         *
+         * When provided, renderDrawing builds NormalizedProductItems per viewport,
+         * resolving fill colors from each viewport's fill rules. This replaces
+         * manual item construction in consumer code.
+         *
+         * Ignored when `viewportItems` is also provided (explicit items take priority).
+         */
+        productEntries?: Array<{
+            product: unknown;
+            polylines: Array<{ points: Array<{ x: number; z: number }> }>;
+        }>;
+        /**
+         * Pre-built product items when `models` is provided directly.
+         * Keyed by viewport ID, each containing an array of NormalizedProductItems.
+         * Used for legends, labels, and other template elements that need item data.
+         *
+         * Takes priority over `productEntries` when both are provided.
+         */
+        viewportItems?: Record<string, { items: NormalizedProductItem[] }>;
+        /**
+         * App default section settings. Used as fallback when viewports don't specify
+         * their own cutHeight/depth configuration.
+         */
+        sectionDefaults?: {
+            cutHeight?: number;
+            depth?: { above?: number; below?: number };
+        };
+        /**
+         * Template variable values.
+         *
+         * When template defines `variables`, provide values here to customize the output.
+         * Missing values automatically use defaults from template (fail-safe).
+         * Invalid values fall back to defaults with warnings.
+         *
+         * Optional - if not provided, all template defaults are used.
+         *
+         * @example
+         * ```typescript
+         * await renderDrawing({
+         *   template,
+         *   models,
+         *   options: {
+         *     variables: {
+         *       hyresobjektsnummer: '2022-F2009',
+         *       showLegend: true
+         *     }
+         *   }
+         * });
+         * ```
+         */
+        variables?: Record<string, any>;
+    };
+}
+
+export interface RenderDrawingResult {
+    svg: string;
+    warnings: string[];
+}