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

package/src/layout/renderTemplateSheet.ts

@@ -0,0 +1,435 @@
+import { buildPlaneBasis, planeFromPointAndNormal, type PlaneBasis, type Vec3 } from '@twinfinity/geometry';
+import {
+    computePlaneSectionsForProducts,
+    SlabSection,
+    type ProductLike,
+    type SlabSectionResult
+} from '@twinfinity/product-geometry';
+import { buildSectionStateForEntries } from '../sections';
+import { renderDrawing } from './renderDrawing';
+import { sectionStateToModelView } from './itemBuilders';
+import { slabSectionToModelView, slabPerProductToEntries } from './slabModelView';
+import { resolveViewportSection, sectionDefKey, type ResolvedSectionDef, type SectionDefaults } from './sectionDefs';
+import {
+    computeViewportClassClosure,
+    filterProductsByClosure,
+    collectClassBehavior,
+    type ClassBehaviorRule
+} from './classClosure';
+import { buildMetadataMap } from './metadata';
+
+/**
+ * Plain world AABB from a viewer product's duck-typed `boundingInfo()` (BimIfcObject
+ * exposes Babylon BoundingInfo; plain ProductLike adapters usually have none → null).
+ */
+function productAabb(product: ProductLike): { min: [number, number, number]; max: [number, number, number] } | null {
+    const withBi = product as ProductLike & { boundingInfo?: () => Record<string, unknown> };
+    if (typeof withBi.boundingInfo !== 'function') return null;
+    const bi = withBi.boundingInfo();
+    if (!bi) return null;
+    const bb = bi.boundingBox as Record<string, unknown> | undefined;
+    const bMin = (bb?.minimumWorld ?? bi.minimum) as (number[] & Record<string, number>) | undefined;
+    const bMax = (bb?.maximumWorld ?? bi.maximum) as (number[] & Record<string, number>) | undefined;
+    if (!bMin || !bMax) return null;
+    return {
+        min: [bMin[0] ?? bMin.x ?? 0, bMin[1] ?? bMin.y ?? 0, bMin[2] ?? bMin.z ?? 0],
+        max: [bMax[0] ?? bMax.x ?? 0, bMax[1] ?? bMax.y ?? 0, bMax[2] ?? bMax.z ?? 0]
+    };
+}
+import type {
+    LayoutTemplate,
+    SvgModelView,
+    ViewportLineStyles,
+    ViewportStairArrowOptions,
+    ProductPolylineEntry
+} from './types';
+
+// Products + template → rendered sheet, in one call. This is the consumer
+// contract for the template's self-describing sections: every viewport's
+// cutHeight/planeNormal/planePosition/depth is resolved (sectionDefs),
+// computed (SlabSection for plans, plane sections for elevations/sections),
+// adapted to SvgModelViews and fed to renderDrawing — so the workbench, the
+// viewer print dialog and any future consumer render a template identically
+// instead of re-implementing this pipeline.
+//
+// Invariants encoded here (learned the hard way — do not "optimize" away):
+// - Sections are computed UNFILTERED: the renderer applies each viewport's
+//   includeClasses at render time via rawPaths + metadata, and highlight/clip
+//   need the highlight-class geometry present even when includeClasses
+//   excludes it from drawing (e.g. highlighting a space in a walls-only view).
+// - The plan's lateral section origin stays at world zero so the projected
+//   space equals world x/z — labels/legend items are placed in world x/z, and
+//   a shifted origin would displace them.
+// - The plan projection plane sits `above` metres over the cut (matches
+//   ExportDrawingPdf/printToSvg), with a (0,0,1) up hint for north-up plans.
+
+type SectionEntries = Parameters<typeof buildSectionStateForEntries>[0];
+type SectionStateOptions = Parameters<typeof buildSectionStateForEntries>[1];
+
+/**
+ * The expensive template-independent half of one viewport's render: only the
+ * geometry is cached — the SvgModelView is built per viewport at render time,
+ * so template-driven styling (lineStyles incl. dash, fills) applies without
+ * re-sectioning.
+ */
+export type ComputedSection =
+    | {
+          kind: 'plan';
+          geometry: SlabSectionResult<ProductLike>;
+          basis: PlaneBasis;
+          segmentCount: number;
+          /** Per-product cut polylines (world x/z) — feeds labels/legend items. */
+          entries: ProductPolylineEntry[];
+      }
+    | {
+          kind: 'elevation';
+          perProduct: SectionEntries;
+          normal: Vec3;
+          segmentCount: number;
+          entries: ProductPolylineEntry[];
+      };
+
+/**
+ * Section-geometry cache, one entry per distinct section definition. Owned by
+ * the caller (its lifetime = one loaded model; clear it when the model
+ * changes); renderTemplateSheet evicts entries no viewport references any
+ * more, keeping it bounded while sharing repeated definitions.
+ */
+export class SectionCache {
+    private readonly _map = new Map<string, ComputedSection>();
+
+    get(key: string): ComputedSection | undefined {
+        return this._map.get(key);
+    }
+
+    set(key: string, value: ComputedSection): void {
+        this._map.set(key, value);
+    }
+
+    evictExcept(used: ReadonlySet<string>): void {
+        for (const key of this._map.keys()) {
+            if (!used.has(key)) this._map.delete(key);
+        }
+    }
+
+    clear(): void {
+        this._map.clear();
+    }
+}
+
+export interface RenderTemplateSheetInput {
+    template: LayoutTemplate;
+    /** Products with geometry — pass ALL of them (unfiltered; see above). */
+    products: ProductLike[];
+    /**
+     * Fallback plan position (world) for viewports without a section
+     * definition — typically the model AABB centre. Without it such
+     * viewports are skipped with a warning.
+     */
+    modelCenter?: [number, number, number];
+    /** Section defaults applied where viewports omit cutHeight/depth. */
+    defaults?: SectionDefaults;
+    /** Reuse section geometry across renders (strongly recommended). */
+    cache?: SectionCache;
+    /** Context for role:'main'/'anchor' QR elements. */
+    qrContext?: {
+        host?: string | null;
+        containerName?: string | null;
+        floorName?: string | null;
+        planeHeight?: number | null;
+    };
+    /** Values for the template's declared variables ({{vars.*}}). */
+    variables?: Record<string, unknown>;
+    /**
+     * Host-side authorisation for fetching `https://` resources, matching the option `renderDrawing`
+     * already takes. Without it a caller rendering a sheet had no say at all — only the template
+     * could enable remote loading — so a host that wanted to permit it for its own templates could
+     * not, and one that wanted to observe the setting had nowhere to look.
+     */
+    allowRemoteResources?: boolean;
+    /**
+     * Progress callback: overall fraction 0–1 plus a human-readable phase.
+     * Section phases stream from SlabSection per viewport (cached sections
+     * skip ahead); the final render step reports as its own phase. Wire this
+     * to a busy indicator — large models can take tens of seconds, and
+     * without feedback a long compute is indistinguishable from a hang.
+     */
+    onProgress?: (progress: number, phase: string) => void;
+}
+
+export interface RenderedTemplateSheet {
+    svg: string;
+    warnings: string[];
+    /** Sum over viewports — 0 means no cut produced drawable geometry. */
+    segmentCount: number;
+}
+
+/**
+ * Read a viewport's `stairArrows` geometry options into a canonical object:
+ * known fields only, fixed order, invalid values dropped — so equal options
+ * always serialize to the same cache-key fragment and unknown junk from a
+ * hand-written template can't reach the geometry pass.
+ */
+export function readViewportStairArrowOptions(vp: Record<string, unknown>): ViewportStairArrowOptions | undefined {
+    const raw = vp.stairArrows;
+    if (!raw || typeof raw !== 'object') return undefined;
+    const r = raw as Record<string, unknown>;
+    const out: ViewportStairArrowOptions = {};
+    if (r.startMarker === 'filled' || r.startMarker === 'open' || r.startMarker === 'none') {
+        out.startMarker = r.startMarker;
+    }
+    if (r.arrowhead === 'filled' || r.arrowhead === 'outline' || r.arrowhead === 'open') {
+        out.arrowhead = r.arrowhead;
+    }
+    for (const k of ['lengthScale', 'minLength', 'maxLength', 'landingExtension'] as const) {
+        const v = r[k];
+        if (typeof v === 'number' && Number.isFinite(v) && v >= 0) out[k] = v;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+
+async function computeSectionForDef(
+    products: ProductLike[],
+    def: ResolvedSectionDef,
+    onPhase?: (pct: number, phase: string) => void,
+    classBehavior?: ClassBehaviorRule[],
+    stairArrows?: ViewportStairArrowOptions
+): Promise<ComputedSection> {
+    if (!def.plan) {
+        // Elevations/sections: a thin plane section projected by the section-
+        // state builder — its planeNormal projection is the canonical
+        // orientation (a hand-rolled basis renders elevations mirrored).
+        onPhase?.(0, 'Computing plane sections');
+        const n = def.normal;
+        // AABB gate: a product whose bounds do not straddle the section plane
+        // cannot contribute plane sections — skip it before any mesh access.
+        const straddling = products.filter((p) => {
+            const bi = productAabb(p);
+            if (!bi) return true;
+            const c0 = (bi.min[0] + bi.max[0]) * 0.5 * n[0];
+            const c1 = (bi.min[1] + bi.max[1]) * 0.5 * n[1];
+            const c2 = (bi.min[2] + bi.max[2]) * 0.5 * n[2];
+            const e =
+                ((bi.max[0] - bi.min[0]) / 2) * Math.abs(n[0]) +
+                ((bi.max[1] - bi.min[1]) / 2) * Math.abs(n[1]) +
+                ((bi.max[2] - bi.min[2]) / 2) * Math.abs(n[2]);
+            const center = c0 + c1 + c2;
+            return center - e <= def.position && center + e >= def.position;
+        });
+        const origin: Vec3 = [n[0] * def.position, n[1] * def.position, n[2] * def.position];
+        const plane = planeFromPointAndNormal(origin, n as unknown as Vec3);
+        const section = await computePlaneSectionsForProducts(straddling, plane);
+        onPhase?.(100, 'Plane sections complete');
+        return {
+            kind: 'elevation',
+            perProduct: section.perProduct as unknown as SectionEntries,
+            normal: n as unknown as Vec3,
+            segmentCount: section.segments.length,
+            entries: []
+        };
+    }
+
+    // Plans go through SlabSection (cut/visible/hidden lines with occlusion).
+    const viewDir: [number, number, number] = [0, -1, 0];
+    const above = Math.max(0, def.depth.above);
+    const below = Math.max(0, def.depth.below);
+    const slab = new SlabSection<ProductLike>({
+        cutHeight: def.position,
+        viewDir,
+        cutOrigin: [0, def.position, 0],
+        depth: { above, below },
+        // stairArrows: generated only for stair-category products (className fallback in
+        // the gather), so enabling it unconditionally costs nothing on stairless slabs —
+        // and the stairArrows lineStyles category has been in the template schema all
+        // along, styling output this pipeline never produced.
+        lines: { cut: true, visible: true, hidden: true, stairArrows: true },
+        // Template-driven marker shapes / run sizing; SlabSection merges the
+        // partial object with its own defaults.
+        ...(stairArrows ? { stairArrows } : {}),
+        // Per-product attribution feeds labels/legend items.
+        trackProducts: true,
+        onProgress: onPhase,
+        // Forward-compatible pass-through: the published product-geometry ignores unknown
+        // options; the classBehavior contract activates with TWINS-3784's SlabSection.
+        ...(classBehavior?.length ? { classBehavior } : {})
+    });
+    const geometry = await slab.compute(products);
+    const segmentCount = geometry.cutLines.length + geometry.visibleLines.length + geometry.hiddenLines.length;
+    const entries = slabPerProductToEntries(geometry.perProduct ?? []);
+    const basis = buildPlaneBasis([0, def.position + above, 0], viewDir, [0, 0, 1]);
+    return { kind: 'plan', geometry, basis, segmentCount, entries };
+}
+
+/** Build a viewport's model view from cached geometry + its own lineStyles. */
+function buildViewForViewport(computed: ComputedSection, vp: Record<string, unknown>): SvgModelView | null {
+    const lineStyles = vp.lineStyles as ViewportLineStyles | undefined;
+    if (computed.kind === 'plan') {
+        return slabSectionToModelView(computed.geometry, computed.basis, lineStyles);
+    }
+    const state = buildSectionStateForEntries(computed.perProduct, {
+        strokeWidth: lineStyles?.default?.widthMm ?? 0.25,
+        includeMeta: true,
+        includeLabels: false,
+        fills: vp.fills as SectionStateOptions['fills'],
+        planeNormal: computed.normal
+    });
+    return state ? sectionStateToModelView(state) : null;
+}
+
+/**
+ * Render a template against a product set: resolve each viewport's section
+ * definition, compute (or reuse from `cache`) the section per distinct
+ * definition, and feed renderDrawing one model per viewport id.
+ */
+export async function renderTemplateSheet(input: RenderTemplateSheetInput): Promise<RenderedTemplateSheet> {
+    const warnings: string[] = [];
+    const cache = input.cache ?? new SectionCache();
+
+    // Resolve template variables BEFORE section resolution — variables can
+    // drive section placement ("cutHeight": "{{vars.cutHeight}}", typed
+    // whole-value substitution), and the geometry cache must key on the
+    // resolved values. The resolved template carries no {{vars.*}} left, so
+    // renderDrawing gets no variables input.
+    let template = input.template;
+    if (template.variables) {
+        const { resolveTemplateValues, applyTemplateVariables } = await import('./templateVariables');
+        const { values, warnings: varWarnings } = resolveTemplateValues(template, input.variables);
+        varWarnings.forEach((w) => warnings.push(`[Variables] ${w}`));
+        template = applyTemplateVariables(template, values, warnings);
+    }
+
+    const viewports = ((template.elements ?? []) as unknown as Array<Record<string, unknown>>).filter(
+        (e): e is Record<string, unknown> & { id: string } => e.kind === 'viewport' && typeof e.id === 'string'
+    );
+
+    if (viewports.length === 0) {
+        warnings.push('Template has no viewport elements — nothing to section.');
+    }
+
+    // Per-viewport compute-class closure (classClosure.ts): only the viewport's include
+    // classes take part in its drawing generation, hidden lines included — geometry
+    // outside the closure neither draws nor OCCLUDES there, and pays no compute cost
+    // (the dominant lever on MEP-heavy models). The closure contains the viewport's
+    // highlight/clip/fill/label/legend classes too, so the "sections computed unfiltered"
+    // invariant above still holds WITHIN it. The closure is part of the section cache
+    // key: viewports sharing (sectionDef, closure) share geometry, and editing
+    // includeClasses re-sections.
+    const productsByClosureKey = new Map<string, ProductLike[]>();
+    const productsForClosure = (closure: Set<string> | null): { products: ProductLike[]; closureKey: string } => {
+        const closureKey = closure ? [...closure].sort().join(',') : 'all';
+        let products = productsByClosureKey.get(closureKey);
+        if (!products) {
+            products = closure ? filterProductsByClosure(input.products, closure) : input.products;
+            productsByClosureKey.set(closureKey, products);
+        }
+        return { products, closureKey };
+    };
+
+    const models: Record<string, SvgModelView> = {};
+    const usedKeys = new Set<string>();
+    let segmentCount = 0;
+    // Labels/legend items are placed in world x/z (floor-plane convention) and must see ALL products
+    // regardless of viewport class filters — so they come from each viewport's unfiltered section.
+    //
+    // Keyed by viewport id rather than collapsed into one list: a legend declares which viewport it
+    // describes (`legend.viewport`, required) and renderLayout reads that viewport's items, so a
+    // sheet may carry several legends describing several plans. Passing one flat list handed every
+    // legend the first plan's contents no matter what it was bound to.
+    // No fallback to another viewport's entries: a legend describing a viewport that yielded nothing
+    // renders empty and renderLayout warns by name ("Legend 'x' has no items from viewport 'y'"),
+    // which is more use than quietly showing another viewport's contents under its heading.
+    const entriesByViewport: Record<string, ProductPolylineEntry[]> = {};
+    // gid → class/property metadata for EVERY product in every section. The entries
+    // arrays only cover cut-bearing products, but render-time includeClasses filtering
+    // must classify products whose geometry never crosses the cut (furniture below a
+    // plan cut) — without this map their visible/hidden lines vanish from the drawing.
+    const fullMetadata: ReturnType<typeof buildMetadataMap> = {};
+
+    for (const vp of viewports) {
+        let def = resolveViewportSection(vp as never, input.defaults);
+        if (!def) {
+            if (!input.modelCenter) {
+                warnings.push(`Viewport '${vp.id}' has no section definition and no modelCenter fallback — skipped.`);
+                continue;
+            }
+            def = {
+                plan: true,
+                normal: [0, 1, 0],
+                position: input.modelCenter[1],
+                depth: { above: 0.5, below: 1.5 }
+            };
+            warnings.push(
+                `Viewport '${vp.id}' has no section definition — using a default plan at ${def.position.toFixed(1)} m.`
+            );
+        }
+        const { products, closureKey } = productsForClosure(computeViewportClassClosure(vp, template));
+        const classBehavior = collectClassBehavior(vp, template);
+        // Behavior is part of the cache key: same def+closure with different behavior
+        // flags must not share geometry.
+        const behaviorKey = classBehavior.length ? JSON.stringify(classBehavior) : '';
+        // Stair-arrow geometry options are part of the cache key too: the arrows are
+        // baked into the section geometry, so viewports with different marker styles
+        // must not share it. readViewportStairArrowOptions canonicalizes field order.
+        const stairArrows = readViewportStairArrowOptions(vp);
+        const stairKey = stairArrows ? JSON.stringify(stairArrows) : '';
+        const key = `${sectionDefKey(def)}|${closureKey}|${behaviorKey}|${stairKey}`;
+        usedKeys.add(key);
+        let computed = cache.get(key);
+        if (!computed) {
+            // Section compute dominates total time; reserve the last 10% for the
+            // render step below. Cached viewports jump ahead without reporting.
+            const vpIndex = viewports.indexOf(vp);
+            computed = await computeSectionForDef(
+                products,
+                def,
+                (pct, phase) =>
+                    input.onProgress?.(
+                        ((vpIndex + pct / 100) / viewports.length) * 0.9,
+                        `Viewport '${vp.id}': ${phase}`
+                    ),
+                classBehavior,
+                stairArrows
+            );
+            cache.set(key, computed);
+        }
+        segmentCount += computed.segmentCount;
+        if (computed.kind === 'plan') {
+            Object.assign(fullMetadata, buildMetadataMap((computed.geometry.perProduct ?? []) as unknown[]));
+        } else {
+            Object.assign(fullMetadata, buildMetadataMap(computed.perProduct as unknown[]));
+        }
+        if (computed.entries?.length) entriesByViewport[vp.id] = computed.entries;
+        const view = buildViewForViewport(computed, vp);
+        if (!view) {
+            warnings.push(`Viewport '${vp.id}': section produced no drawable geometry at this cut.`);
+            continue;
+        }
+        models[vp.id] = view;
+    }
+
+    cache.evictExcept(usedKeys);
+
+    if (Object.keys(models).length === 0) {
+        return { svg: '', warnings, segmentCount };
+    }
+
+    input.onProgress?.(0.9, 'Rendering sheet');
+    const { svg, warnings: renderWarnings } = await renderDrawing({
+        // Already variable-resolved above — pass no variables down.
+        template,
+        models,
+        options: {
+            allowRemoteResources:
+                (template as { allowRemoteResources?: boolean }).allowRemoteResources ?? input.allowRemoteResources,
+            qrContext: input.qrContext,
+            metadataById: fullMetadata,
+            // Feeds labels/legend items, keyed by viewport so each legend describes the viewport it
+            // declares — a sheet may carry several legends over several plans. This used to be one
+            // flat list taken from the first plan viewport, which handed every legend that plan's
+            // contents no matter what it was bound to.
+            productEntries: Object.keys(entriesByViewport).length ? entriesByViewport : undefined
+        }
+    });
+    input.onProgress?.(1, 'Complete');
+    return { svg, warnings: [...warnings, ...renderWarnings], segmentCount };
+}

package/src/layout/renderUtils.ts

@@ -1,5 +1,10 @@
 import { isRecord } from './typeGuards';
 
+/** Round a coordinate for SVG output (3 decimals ≈ 1 µm at mm scale) —
+ *  emitting raw doubles bloats the SVG with 17-digit numbers. */
+export const formatNumber = (value: number): number =>
+    Number.isFinite(value) ? Number.parseFloat(value.toFixed(3)) : 0;
+
 export const escapeAttr = (value: unknown): string =>
     String(value).replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
 
@@ -21,8 +26,51 @@ export const getPathValue = (source: unknown, path: string): unknown => {
     return current;
 };
 
+/**
+ * Split a placeholder expression into its value path and optional format
+ * filter: "area | round:1" → { path: 'area', filter: 'round:1' }.
+ */
+export const splitPlaceholder = (expr: string): { path: string; filter: string | null } => {
+    const pipe = expr.indexOf('|');
+    if (pipe < 0) return { path: expr.trim(), filter: null };
+    return { path: expr.slice(0, pipe).trim(), filter: expr.slice(pipe + 1).trim() };
+};
+
+/**
+ * Apply a placeholder format filter to a resolved value:
+ * - `round` / `round:N` — round to N decimals (default 0), trailing zeros trimmed
+ * - `fixed` / `fixed:N` — exactly N decimals (default 0), for aligned output
+ * Non-numeric values pass through unchanged; unknown filters warn and pass
+ * through so a typo degrades to the unformatted value, not an empty label.
+ */
+export const applyPlaceholderFilter = (
+    value: unknown,
+    filter: string | null,
+    warnings?: string[],
+    context?: string
+): unknown => {
+    if (!filter) return value;
+    const m = /^(round|fixed)(?:\s*:\s*(\d+))?$/.exec(filter);
+    if (!m) {
+        warnings?.push(`Unknown placeholder filter '${filter}'${context ? ` in "${context}"` : ''}.`);
+        return value;
+    }
+    const num = typeof value === 'number' ? value : Number(value);
+    if (typeof value === 'boolean' || value === '' || !Number.isFinite(num)) return value;
+    const digits = m[2] ? Number(m[2]) : 0;
+    // toFixed throws RangeError outside 0..100, and the digit count comes from the template — a
+    // stray `{{ x | fixed:200 }}` would take the whole render down rather than warning about itself.
+    if (!Number.isInteger(digits) || digits < 0 || digits > 100) {
+        warnings?.push(`Filter '${filter}' needs 0-100 decimals${context ? ` in "${context}"` : ''}.`);
+        return value;
+    }
+    const fixed = num.toFixed(digits);
+    return m[1] === 'fixed' ? fixed : String(Number(fixed));
+};
+
 export const interpolate = (template: string, data: any, warnings?: string[]): string =>
-    template.replace(/\{\{\s*([^}]+?)\s*\}\}/g, (match, path) => {
+    template.replace(/\{\{\s*([^}]+?)\s*\}\}/g, (match, expr) => {
+        const { path, filter } = splitPlaceholder(expr);
         const value = getPathValue(data, path);
         if (value === undefined || value === null) {
             if (warnings) {
@@ -38,15 +86,16 @@ export const interpolate = (template: string, data: any, warnings?: string[]): s
             }
             return '';
         }
-        return String(value);
+        return String(applyPlaceholderFilter(value, filter, warnings, template));
     });
 
 export const interpolateWithSources = (template: string, sources: any[]): string =>
-    template.replace(/\{\{\s*([^}]+?)\s*\}\}/g, (_match, path) => {
+    template.replace(/\{\{\s*([^}]+?)\s*\}\}/g, (_match, expr) => {
+        const { path, filter } = splitPlaceholder(expr);
         for (const source of sources) {
             const value = getPathValue(source, path);
             if (value !== undefined && value !== null && typeof value !== 'object') {
-                return String(value);
+                return String(applyPlaceholderFilter(value, filter));
             }
         }
         return '';

package/src/layout/sectionDefs.ts

@@ -0,0 +1,131 @@
+import type { ViewportElement } from './types';
+
+/**
+ * The template's per-viewport section contract, resolved to one canonical
+ * shape. Templates declare either `cutHeight` (+ `depth`) for horizontal
+ * plans or `planeNormal` + `planePosition` for elevations/sections; this
+ * module is the single reader/writer of those fields so every consumer
+ * (workbench, viewer print dialog, …) interprets them identically.
+ *
+ * Canonical form: plans always have `normal = [0, 1, 0]` and `position` =
+ * world Y (a `planeNormal: [0,-1,0]` declaration is folded into that), so
+ * `position` can be used directly as the cut height.
+ */
+export interface ResolvedSectionDef {
+    /** True when the cut is a horizontal plan (normal along Y). */
+    plan: boolean;
+    /** Normalized cut-plane normal (world). `[0, 1, 0]` for plans. */
+    normal: [number, number, number];
+    /** Position along the normal in world metres — world Y for plans. */
+    position: number;
+    /** Slab thickness in front of / behind the plane (metres). */
+    depth: { above: number; below: number };
+}
+
+export const DEFAULT_SECTION_DEPTH = { above: 0.5, below: 1.5 } as const;
+
+export interface SectionDefaults {
+    cutHeight?: number;
+    depth?: { above?: number; below?: number };
+}
+
+const AXIS_EPSILON = 1e-6;
+
+/**
+ * True when a section field carries a whole-value variable binding
+ * (`"{{vars.cutHeight}}"`). Bound fields resolve to numbers only after
+ * `applyTemplateVariables` — resolveViewportSection treats them as
+ * unresolvable rather than guessing.
+ */
+export function isVariableBinding(v: unknown): boolean {
+    return typeof v === 'string' && /^\{\{\s*vars\.\w+\s*\}\}$/.test(v);
+}
+
+/** True when any of the viewport's section fields is variable-bound. */
+export function sectionUsesVariables(vp: Pick<ViewportElement, 'cutHeight' | 'planePosition'>): boolean {
+    return isVariableBinding(vp.cutHeight) || isVariableBinding(vp.planePosition);
+}
+
+/**
+ * Read a viewport element's section definition. `planeNormal` +
+ * `planePosition` takes precedence over `cutHeight` (matching the field
+ * docs); returns null when the viewport declares nothing (and no default
+ * `cutHeight` is provided) or when a section field is still variable-bound
+ * (resolve the template's variables first).
+ */
+export function resolveViewportSection(
+    vp: Pick<ViewportElement, 'cutHeight' | 'planeNormal' | 'planePosition' | 'depth'>,
+    defaults?: SectionDefaults
+): ResolvedSectionDef | null {
+    // Unresolved bindings: never guess a position — callers must apply
+    // template variables before resolving sections.
+    if (sectionUsesVariables(vp)) return null;
+
+    const above =
+        typeof vp.depth?.above === 'number' ? vp.depth.above : (defaults?.depth?.above ?? DEFAULT_SECTION_DEPTH.above);
+    const below =
+        typeof vp.depth?.below === 'number' ? vp.depth.below : (defaults?.depth?.below ?? DEFAULT_SECTION_DEPTH.below);
+    const depth = { above: Math.max(0, above), below: Math.max(0, below) };
+
+    const n = vp.planeNormal;
+    if (Array.isArray(n) && n.length === 3 && n.every((v) => typeof v === 'number')) {
+        const len = Math.hypot(n[0], n[1], n[2]);
+        if (len > AXIS_EPSILON) {
+            let normal: [number, number, number] = [n[0] / len, n[1] / len, n[2] / len];
+            let position = typeof vp.planePosition === 'number' ? vp.planePosition : 0;
+            const plan = Math.abs(normal[0]) < AXIS_EPSILON && Math.abs(normal[2]) < AXIS_EPSILON;
+            if (plan && normal[1] < 0) {
+                // Canonicalize plans to +Y so position === world Y.
+                normal = [0, 1, 0];
+                position = -position;
+            } else if (plan) {
+                normal = [0, 1, 0];
+            }
+            return { plan, normal, position, depth };
+        }
+    }
+
+    if (typeof vp.cutHeight === 'number') {
+        return { plan: true, normal: [0, 1, 0], position: vp.cutHeight, depth };
+    }
+    if (typeof defaults?.cutHeight === 'number') {
+        return { plan: true, normal: [0, 1, 0], position: defaults.cutHeight, depth };
+    }
+    return null;
+}
+
+/**
+ * Write a section definition back onto a viewport element in canonical form:
+ * plans use the `cutHeight` shorthand (and drop `planeNormal`/`planePosition`),
+ * everything else uses `planeNormal` + `planePosition` (and drops
+ * `cutHeight`). Keeping reader and writer together prevents the two
+ * shorthands from coexisting on one element, where reader precedence would
+ * silently decide.
+ */
+export function writeViewportSection(
+    vp: Partial<Pick<ViewportElement, 'cutHeight' | 'planeNormal' | 'planePosition' | 'depth'>>,
+    def: ResolvedSectionDef
+): void {
+    vp.depth = { above: def.depth.above, below: def.depth.below };
+    if (def.plan) {
+        vp.cutHeight = def.normal[1] >= 0 ? def.position : -def.position;
+        delete vp.planeNormal;
+        delete vp.planePosition;
+    } else {
+        vp.planeNormal = [def.normal[0], def.normal[1], def.normal[2]];
+        vp.planePosition = def.position;
+        delete vp.cutHeight;
+    }
+}
+
+const fmtNum = (v: number): string => String(Math.round(v * 1e6) / 1e6);
+
+/** Stable cache key for a resolved section definition (same cut ⇒ same key). */
+export function sectionDefKey(def: ResolvedSectionDef): string {
+    return [
+        def.plan ? 'plan' : 'section',
+        def.normal.map(fmtNum).join(','),
+        fmtNum(def.position),
+        `${fmtNum(def.depth.above)}/${fmtNum(def.depth.below)}`
+    ].join('|');
+}