@twinfinity/printing 5.0.3-ci.28538-beta

package/src/layout/analyzeTemplate.ts

@@ -0,0 +1,218 @@
+import { normalizeClass } from './filters';
+import type {
+    LayoutTemplate,
+    LayoutElement,
+    ViewportElement,
+    TextElement,
+    ImageElement,
+    QrElement,
+    LabelsElement,
+    LegendElement,
+    GroupElement,
+    ScaleBarElement,
+    WhereCondition
+} from './types';
+
+/**
+ * Describes the input requirements inferred from a layout template.
+ * Use `analyzeTemplate()` to scan a template and discover what data it needs.
+ */
+export interface TemplateRequirements {
+    /** Viewport IDs the template declares. */
+    viewportIds: string[];
+
+    /** Property paths referenced by legends, where-filters, and labels.
+     *  Short-path format: "SetName.propName" (e.g. "BIP.spacename"). */
+    propertyPaths: string[];
+
+    /** Class filters referenced (e.g. "space", "walls"). Already lowercase. */
+    classFilters: string[];
+
+    /** Asset IDs referenced by image/northArrow elements. */
+    assetIds: string[];
+
+    /** Text interpolation variables (e.g. "viewport.main.scaleText"). */
+    interpolationVars: string[];
+
+    /** Whether the template references remote (http/https) asset URLs. */
+    usesRemoteAssets: boolean;
+}
+
+const INTERPOLATION_RE = /\{\{\s*([^}]+?)\s*\}\}/g;
+
+/** Extract `{{path}}` tokens from a template string. */
+function extractInterpolationVars(text: string): string[] {
+    const vars: string[] = [];
+    let m: RegExpExecArray | null;
+    INTERPOLATION_RE.lastIndex = 0;
+    while ((m = INTERPOLATION_RE.exec(text)) !== null) {
+        vars.push(m[1]);
+    }
+    return vars;
+}
+
+/** Collect keys from a WhereCondition (each key is a property short-path). */
+function collectWherePaths(where: WhereCondition | undefined, out: Set<string>): void {
+    if (!where || typeof where !== 'object') return;
+    for (const key of Object.keys(where)) {
+        out.add(key);
+    }
+}
+
+/** Collect class filter values, normalizing to lowercase. */
+function collectClassFilter(classFilter: string | string[] | undefined, out: Set<string>): void {
+    if (!classFilter) return;
+    const classes = Array.isArray(classFilter) ? classFilter : [classFilter];
+    for (const c of classes) {
+        const normalized = normalizeClass(c);
+        if (normalized) out.add(normalized);
+    }
+}
+
+/**
+ * Scan a layout template and return its input requirements.
+ *
+ * This is a pure, read-only analysis — it does not modify the template or
+ * perform any rendering. Use the result to validate inputs before calling
+ * `renderDrawing()` or `renderLayout()`.
+ */
+export function analyzeTemplate(template: LayoutTemplate): TemplateRequirements {
+    const viewportIds = new Set<string>();
+    const propertyPaths = new Set<string>();
+    const classFilters = new Set<string>();
+    const assetIds = new Set<string>();
+    const interpolationVars = new Set<string>();
+    let usesRemoteAssets = false;
+
+    // Check assets for remote URLs
+    if (template.assets) {
+        for (const asset of template.assets) {
+            if (asset.src && /^https?:\/\//i.test(asset.src)) {
+                usesRemoteAssets = true;
+            }
+        }
+    }
+
+    // Walk all elements (recursing into groups)
+    const walk = (elements: LayoutElement[]): void => {
+        for (const el of elements) {
+            switch (el.kind) {
+                case 'viewport': {
+                    const vp = el as ViewportElement;
+                    viewportIds.add(vp.id);
+
+                    // Clip filter
+                    if (vp.clip) {
+                        collectClassFilter(vp.clip.class, classFilters);
+                        collectWherePaths(vp.clip.where, propertyPaths);
+                    }
+
+                    // Highlight filter
+                    if (vp.highlight) {
+                        collectClassFilter(vp.highlight.class, classFilters);
+                        collectWherePaths(vp.highlight.where, propertyPaths);
+                    }
+
+                    // includeClasses
+                    if (vp.includeClasses) {
+                        if (Array.isArray(vp.includeClasses)) {
+                            for (const c of vp.includeClasses) {
+                                const normalized = normalizeClass(c);
+                                if (normalized) classFilters.add(normalized);
+                            }
+                        }
+                        // Preset references are resolved at render time, nothing to collect
+                    }
+
+                    // North arrow asset
+                    if (vp.northArrow?.assetId) {
+                        assetIds.add(vp.northArrow.assetId);
+                    }
+                    break;
+                }
+
+                case 'text': {
+                    const txt = el as TextElement;
+                    if (txt.text) {
+                        for (const v of extractInterpolationVars(txt.text)) {
+                            interpolationVars.add(v);
+                        }
+                    }
+                    break;
+                }
+
+                case 'image': {
+                    const img = el as ImageElement;
+                    if (img.assetId) assetIds.add(img.assetId);
+                    break;
+                }
+
+                case 'qr': {
+                    const qr = el as QrElement;
+                    if (qr.dataTemplate) {
+                        for (const v of extractInterpolationVars(qr.dataTemplate)) {
+                            interpolationVars.add(v);
+                        }
+                    }
+                    break;
+                }
+
+                case 'labels': {
+                    const sl = el as LabelsElement;
+                    collectClassFilter(sl.class, classFilters);
+                    collectWherePaths(sl.where, propertyPaths);
+
+                    // Extract property paths from text interpolation (skip viewport.* which are computed)
+                    if (sl.text) {
+                        for (const v of extractInterpolationVars(sl.text)) {
+                            if (!v.startsWith('viewport.')) {
+                                propertyPaths.add(v);
+                            } else {
+                                interpolationVars.add(v);
+                            }
+                        }
+                    }
+                    break;
+                }
+
+                case 'legend': {
+                    const leg = el as LegendElement;
+                    collectClassFilter(leg.class, classFilters);
+                    collectWherePaths(leg.where, propertyPaths);
+
+                    // Column property paths
+                    if (leg.columns) {
+                        for (const col of leg.columns) {
+                            if (col.property) propertyPaths.add(col.property);
+                        }
+                    }
+                    break;
+                }
+
+                case 'scaleBar': {
+                    // scaleBar references a viewport by ID (informational)
+                    const sb = el as ScaleBarElement;
+                    if (sb.viewport) viewportIds.add(sb.viewport);
+                    break;
+                }
+
+                case 'group': {
+                    const grp = el as GroupElement;
+                    if (grp.children) walk(grp.children);
+                    break;
+                }
+            }
+        }
+    };
+
+    walk(template.elements);
+
+    return {
+        viewportIds: [...viewportIds],
+        propertyPaths: [...propertyPaths],
+        classFilters: [...classFilters],
+        assetIds: [...assetIds],
+        interpolationVars: [...interpolationVars],
+        usesRemoteAssets
+    };
+}

package/src/layout/clipUtils.ts

@@ -0,0 +1,193 @@
+import type { SvgModelView } from './types';
+import { EPSILON_DIVISION_SAFETY, CENTER_FRACTION } from './geometryConstants';
+
+export type Point = { x: number; y: number };
+export type Polygon = Point[];
+
+import { isRecord, getProp } from './typeGuards';
+
+export const pointInPolygon = (polygon: Polygon, x: number, y: number): boolean => {
+    let inside = false;
+    for (let i = 0, j = polygon.length - 1; i < polygon.length; j = i++) {
+        const xi = polygon[i].x,
+            yi = polygon[i].y;
+        const xj = polygon[j].x,
+            yj = polygon[j].y;
+        const intersect = yi > y !== yj > y && x < ((xj - xi) * (y - yi)) / (yj - yi) + xi;
+        if (intersect) inside = !inside;
+    }
+    return inside;
+};
+
+export const filterItemsInPolygons = (
+    items: unknown[],
+    polygons: Polygon[],
+    xField = 'x',
+    yField = 'z',
+    getPathValue: (obj: unknown, path: string) => unknown
+): unknown[] => {
+    if (!Array.isArray(items) || !Array.isArray(polygons) || polygons.length === 0) return items ?? [];
+    return items.filter((item) => {
+        const xVal = getPathValue(item, xField);
+        const yVal = getPathValue(item, yField);
+        if (!Number.isFinite(xVal) || !Number.isFinite(yVal)) return false;
+        const x = Number(xVal);
+        const y = Number(yVal);
+        return polygons.some((poly) => pointInPolygon(poly, x, y));
+    });
+};
+
+export const filterEntriesByClip = (
+    entries: unknown[],
+    polygons: Array<Array<{ x: number; z: number }>>
+): unknown[] => {
+    if (!Array.isArray(entries) || !Array.isArray(polygons) || polygons.length === 0) return entries ?? [];
+
+    const getCenter = (entry: unknown): { x: number | null; z: number | null } => {
+        const product = getProp(entry, 'product') ?? entry;
+        try {
+            const boundingInfoFn = getProp(product, 'boundingInfo');
+            const boundingInfo = typeof boundingInfoFn === 'function' ? boundingInfoFn() : null;
+            const bbox = isRecord(boundingInfo) ? getProp(boundingInfo, 'boundingBox') : null;
+            const min = isRecord(bbox) ? (getProp(bbox, 'minimumWorld') ?? getProp(bbox, 'minimum')) : null;
+            const max = isRecord(bbox) ? (getProp(bbox, 'maximumWorld') ?? getProp(bbox, 'maximum')) : null;
+            const minX = isRecord(min) ? getProp(min, 'x') : null;
+            const maxX = isRecord(max) ? getProp(max, 'x') : null;
+            const minZ = isRecord(min) ? getProp(min, 'z') : null;
+            const maxZ = isRecord(max) ? getProp(max, 'z') : null;
+            if (Number.isFinite(minX) && Number.isFinite(maxX) && Number.isFinite(minZ) && Number.isFinite(maxZ)) {
+                return {
+                    x: (Number(minX) + Number(maxX)) * CENTER_FRACTION,
+                    z: (Number(minZ) + Number(maxZ)) * CENTER_FRACTION
+                };
+            }
+        } catch {
+            // Bounding info access may fail for products without geometry or with malformed data structures.
+            // This is expected behavior - we fall back to entry.x/z properties below.
+        }
+        const x = getProp(entry, 'x');
+        const z = getProp(entry, 'z');
+        return { x: typeof x === 'number' ? x : null, z: typeof z === 'number' ? z : null };
+    };
+
+    return entries.filter((entry) => {
+        const center = getCenter(entry);
+        if (!Number.isFinite(center.x) || !Number.isFinite(center.z)) return false;
+        const x = Number(center.x);
+        const z = Number(center.z);
+        return polygons.some((poly) =>
+            pointInPolygon(
+                poly.map((p) => ({ x: p.x, y: p.z })),
+                x,
+                z
+            )
+        );
+    });
+};
+
+export const offsetPolygons = (polys: Polygon[], delta: number): Polygon[] => {
+    if (!Array.isArray(polys) || !polys.length || !Number.isFinite(delta) || delta === 0) return polys ?? [];
+    const intersectLines = (p: Point, r: Point, q: Point, s: Point): Point | null => {
+        const rxs = r.x * s.y - r.y * s.x;
+        if (Math.abs(rxs) < EPSILON_DIVISION_SAFETY) return null; // parallel
+        const t = ((q.x - p.x) * s.y - (q.y - p.y) * s.x) / rxs;
+        return { x: p.x + t * r.x, y: p.y + t * r.y };
+    };
+    const offsetPoly = (poly: Polygon): Polygon => {
+        const n = poly.length;
+        if (n < 3) return poly;
+        const area = poly.reduce((sum, p, i) => {
+            const q = poly[(i + 1) % n];
+            return sum + p.x * q.y - q.x * p.y;
+        }, 0);
+        const orient = area >= 0 ? 1 : -1; // ccw => outward is right normal
+        const out: Polygon = [];
+        for (let i = 0; i < n; i++) {
+            const p0 = poly[(i + n - 1) % n];
+            const p1 = poly[i];
+            const p2 = poly[(i + 1) % n];
+            const e1x = p1.x - p0.x;
+            const e1y = p1.y - p0.y;
+            const e2x = p2.x - p1.x;
+            const e2y = p2.y - p1.y;
+            const len1 = Math.hypot(e1x, e1y) || EPSILON_DIVISION_SAFETY;
+            const len2 = Math.hypot(e2x, e2y) || EPSILON_DIVISION_SAFETY;
+            const n1x = (orient * e1y) / len1;
+            const n1y = (orient * -e1x) / len1;
+            const n2x = (orient * e2y) / len2;
+            const n2y = (orient * -e2x) / len2;
+            const line1Point = { x: p1.x + n1x * delta, y: p1.y + n1y * delta };
+            const line2Point = { x: p1.x + n2x * delta, y: p1.y + n2y * delta };
+            const inter = intersectLines(line1Point, { x: e1x, y: e1y }, line2Point, { x: e2x, y: e2y });
+            out.push(inter ?? line2Point);
+        }
+        return out;
+    };
+    return polys.map(offsetPoly);
+};
+
+export const projectPolygonsToLocal = (
+    polygonsSource: unknown,
+    xField: string,
+    yField: string,
+    model: SvgModelView,
+    rotationDeg: number,
+    contentOffsetX: number,
+    contentOffsetY: number,
+    mmPerModel: number
+): { local: Polygon[]; page: Polygon[] } => {
+    const cosA = Math.cos((rotationDeg * Math.PI) / 180);
+    const sinA = Math.sin((rotationDeg * Math.PI) / 180);
+    const toLocal = (px: number, py: number): Point => {
+        const viewX = px - model.transform!.viewMinX;
+        const viewY = model.transform!.viewMaxZ - py;
+        const x0 = viewX - model.widthModel / 2;
+        const y0 = viewY - model.heightModel / 2;
+        const x1 = x0 * cosA - y0 * sinA;
+        const y1 = x0 * sinA + y0 * cosA;
+        return { x: x1, y: y1 };
+    };
+    const toPage = (px: number, py: number): Point => {
+        const viewX = px - model.transform!.viewMinX;
+        const viewY = model.transform!.viewMaxZ - py;
+        const x0 = viewX - model.widthModel / 2;
+        const y0 = viewY - model.heightModel / 2;
+        const x1 = x0 * cosA - y0 * sinA;
+        const y1 = x0 * sinA + y0 * cosA;
+        return { x: contentOffsetX + x1 * mmPerModel, y: contentOffsetY + y1 * mmPerModel };
+    };
+    const projectPolyLocal = (poly: unknown[]): Polygon =>
+        poly
+            .map((pt: unknown) => {
+                const px = Number(getProp(pt, xField));
+                const py = Number(getProp(pt, yField));
+                if (!Number.isFinite(px) || !Number.isFinite(py)) return null;
+                return toLocal(px, py);
+            })
+            .filter(Boolean) as Polygon;
+    const projectPoly = (poly: unknown[]): Polygon =>
+        poly
+            .map((pt: unknown) => {
+                const px = Number(getProp(pt, xField));
+                const py = Number(getProp(pt, yField));
+                if (!Number.isFinite(px) || !Number.isFinite(py)) return null;
+                return toPage(px, py);
+            })
+            .filter(Boolean) as Polygon;
+
+    const local: Polygon[] = [];
+    const page: Polygon[] = [];
+    if (Array.isArray(polygonsSource)) {
+        polygonsSource.forEach((poly: unknown) => {
+            const points = getProp(poly, 'points');
+            const pl = Array.isArray(points) ? points : Array.isArray(poly) ? poly : null;
+            if (!pl || pl.length < 3) return;
+            const projectedLocal = projectPolyLocal(pl);
+            if (projectedLocal.length >= 3) {
+                local.push(projectedLocal);
+                page.push(projectPoly(pl));
+            }
+        });
+    }
+    return { local, page };
+};

package/src/layout/colorConstants.ts

@@ -0,0 +1,16 @@
+/**
+ * Color computation constants
+ */
+
+// RGB color value limits
+export const RGB_MAX = 255; // Maximum value for RGB color components (0-255)
+export const RGB_MIN = 0; // Minimum value for RGB color components
+
+// Bit shift offsets for color packing/unpacking
+export const RED_SHIFT = 16; // Shift for red component in 24-bit color
+export const GREEN_SHIFT = 8; // Shift for green component in 24-bit color
+
+// Color modulo for hash-based color generation
+export const HASH_COLOR_MODULO = 255; // Modulo for generating colors from hash values
+export const HASH_GREEN_SHIFT = 4; // Bit shift for green in hash-based colors
+export const HASH_BLUE_SHIFT = 8; // Bit shift for blue in hash-based colors

package/src/layout/elementKinds.ts

@@ -0,0 +1,35 @@
+/**
+ * Constants for layout element kinds
+ */
+
+export const ELEMENT_KIND_VIEWPORT = 'viewport';
+export const ELEMENT_KIND_TEXT = 'text';
+export const ELEMENT_KIND_IMAGE = 'image';
+export const ELEMENT_KIND_LINE = 'line';
+export const ELEMENT_KIND_RECT = 'rect';
+export const ELEMENT_KIND_CIRCLE = 'circle';
+export const ELEMENT_KIND_POLYLINE = 'polyline';
+export const ELEMENT_KIND_POLYGON = 'polygon';
+export const ELEMENT_KIND_SCALE_BAR = 'scaleBar';
+export const ELEMENT_KIND_QR = 'qr';
+export const ELEMENT_KIND_LABELS = 'labels';
+export const ELEMENT_KIND_LEGEND = 'legend';
+export const ELEMENT_KIND_GROUP = 'group';
+
+/**
+ * Union type of all valid element kinds
+ */
+export type ElementKind =
+    | typeof ELEMENT_KIND_VIEWPORT
+    | typeof ELEMENT_KIND_TEXT
+    | typeof ELEMENT_KIND_IMAGE
+    | typeof ELEMENT_KIND_LINE
+    | typeof ELEMENT_KIND_RECT
+    | typeof ELEMENT_KIND_CIRCLE
+    | typeof ELEMENT_KIND_POLYLINE
+    | typeof ELEMENT_KIND_POLYGON
+    | typeof ELEMENT_KIND_SCALE_BAR
+    | typeof ELEMENT_KIND_QR
+    | typeof ELEMENT_KIND_LABELS
+    | typeof ELEMENT_KIND_LEGEND
+    | typeof ELEMENT_KIND_GROUP;

package/src/layout/exportDrawing.ts

@@ -0,0 +1,206 @@
+/**
+ * Drawing export utilities for converting SVG markup to various formats.
+ *
+ * This module provides functions for exporting drawings to PDF and SVG files.
+ * These are pure functions that take SVG markup and export options, with no
+ * dependencies on BIM viewer APIs or application state.
+ *
+ * @module exportDrawing
+ */
+
+import { exportSectionToPdf, exportSectionToSvg } from '../printToPdf';
+
+/**
+ * Extracts page dimensions from SVG markup.
+ * Parses the width/height attributes from the root <svg> element.
+ *
+ * @param svg - SVG markup string
+ * @returns Page dimensions in millimeters
+ * @throws {Error} If SVG dimensions cannot be parsed
+ */
+function extractPageSizeFromSvg(svg: string): { widthMm: number; heightMm: number } {
+    // Match width and height attributes (supports both "420mm" and "420" formats)
+    const widthMatch = svg.match(/width="([0-9.]+)(?:mm)?"/);
+    const heightMatch = svg.match(/height="([0-9.]+)(?:mm)?"/);
+
+    if (!widthMatch || !heightMatch) {
+        throw new Error(
+            'Cannot extract page size from SVG. SVG must have width and height attributes. ' +
+                'Provide pageSize option explicitly or ensure SVG contains width/height attributes.'
+        );
+    }
+
+    const widthMm = parseFloat(widthMatch[1]);
+    const heightMm = parseFloat(heightMatch[1]);
+
+    if (!Number.isFinite(widthMm) || !Number.isFinite(heightMm) || widthMm <= 0 || heightMm <= 0) {
+        throw new Error(
+            `Invalid page dimensions extracted from SVG: ${widthMm}mm × ${heightMm}mm. ` +
+                'Provide pageSize option explicitly.'
+        );
+    }
+
+    return { widthMm, heightMm };
+}
+
+/**
+ * Options for exporting a drawing to PDF format.
+ */
+export interface ExportPdfOptions {
+    /**
+     * Output filename (with or without .pdf extension).
+     * Default: "drawing.pdf"
+     */
+    filename?: string;
+
+    /**
+     * Optional page dimensions in millimeters.
+     * If not provided, automatically extracted from SVG width/height attributes.
+     * Only needed if you want to override the SVG's embedded page size.
+     */
+    pageSize?: {
+        widthMm: number;
+        heightMm: number;
+    };
+
+    /**
+     * If true, opens PDF in a new browser tab.
+     * If false, downloads the PDF file.
+     * Default: false (download)
+     */
+    openInNewTab?: boolean;
+}
+
+/**
+ * Options for exporting a drawing to SVG format.
+ */
+export interface ExportSvgOptions {
+    /**
+     * Output filename (with or without .svg extension).
+     * Default: "drawing.svg"
+     */
+    filename?: string;
+
+    /**
+     * If true, opens SVG in a new browser tab.
+     * If false, downloads the SVG file.
+     * Default: false (download)
+     */
+    openInNewTab?: boolean;
+}
+
+/**
+ * Exports an SVG drawing to PDF format.
+ *
+ * Converts the SVG markup to a vector PDF using jsPDF and svg2pdf.js.
+ * The PDF maintains full vector quality with no rasterization.
+ *
+ * **Page size is automatically extracted from the SVG** (width/height attributes),
+ * so you don't need to specify it manually. The template's page dimensions are
+ * embedded in the SVG markup by renderDrawing() or renderLayout().
+ *
+ * **Features:**
+ * - ✅ Vector PDF output (scalable, searchable text)
+ * - ✅ Preserves colors, strokes, fills, fonts
+ * - ✅ No quality loss (unlike raster export)
+ * - ✅ Small file size (vector graphics)
+ * - ✅ Automatic page size detection from SVG
+ *
+ * **Use cases:**
+ * - Print-ready construction documents
+ * - Archival drawings
+ * - Sharing with clients/contractors
+ * - CAD import (vector format)
+ *
+ * @param svg - SVG markup string (from renderDrawing() or renderLayout())
+ * @param options - Export options (filename, optional page size override, open vs download)
+ * @returns Promise that resolves when export completes
+ *
+ * @example
+ * ```typescript
+ * // Basic usage - page size is automatically extracted from SVG
+ * const { svg } = await renderDrawing({ template, models });
+ * await exportToPdf(svg, {
+ *   filename: "floor-plan.pdf",
+ *   openInNewTab: true
+ * });
+ *
+ * // With custom filename
+ * await exportToPdf(svg, {
+ *   filename: `${template.id}-${new Date().toISOString().slice(0,10)}.pdf`
+ * });
+ *
+ * // Override page size if needed (rare)
+ * await exportToPdf(svg, {
+ *   filename: "custom.pdf",
+ *   pageSize: { widthMm: 420, heightMm: 297 },  // A3 landscape override
+ *   openInNewTab: false
+ * });
+ * ```
+ *
+ * @throws {Error} If PDF generation fails or SVG page size cannot be extracted
+ */
+export async function exportToPdf(svg: string, options: ExportPdfOptions = {}): Promise<void> {
+    const filename = options.filename ?? 'drawing.pdf';
+    const filenameWithExt = filename.endsWith('.pdf') ? filename : `${filename}.pdf`;
+
+    // Extract page size from SVG if not provided
+    const pageSize = options.pageSize ?? extractPageSizeFromSvg(svg);
+
+    await exportSectionToPdf({
+        svgMarkup: svg,
+        fileName: filenameWithExt,
+        pageSizeMm: pageSize as any,
+        openInNewTab: options.openInNewTab ?? false
+    });
+}
+
+/**
+ * Exports an SVG drawing to SVG file format.
+ *
+ * Saves or displays the SVG markup as a standalone .svg file.
+ * The SVG can be opened in browsers, vector editors (Inkscape, Illustrator),
+ * or imported into CAD software.
+ *
+ * **Features:**
+ * - ✅ Native vector format (editable in SVG editors)
+ * - ✅ Smallest file size (XML text)
+ * - ✅ Web-friendly (can embed in HTML)
+ * - ✅ Full styling preserved
+ *
+ * **Use cases:**
+ * - Web display (embed in HTML)
+ * - Vector editing (Inkscape, Illustrator)
+ * - Further processing (scripting, automation)
+ * - Archival (open standard format)
+ *
+ * @param svg - SVG markup string (from renderDrawing())
+ * @param options - Export options (filename, open vs download)
+ * @returns Promise that resolves when export completes
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const { svg } = await renderDrawing({ template, models });
+ * await exportToSvg(svg, {
+ *   filename: "floor-plan.svg",
+ *   openInNewTab: true
+ * });
+ *
+ * // Download with custom name
+ * await exportToSvg(svg, {
+ *   filename: `${template.id}-${Date.now()}.svg`,
+ *   openInNewTab: false
+ * });
+ * ```
+ */
+export function exportToSvg(svg: string, options: ExportSvgOptions = {}): void {
+    const filename = options.filename ?? 'drawing.svg';
+    const filenameWithExt = filename.endsWith('.svg') ? filename : `${filename}.svg`;
+
+    exportSectionToSvg({
+        svgMarkup: svg,
+        fileName: filenameWithExt,
+        openInNewTab: options.openInNewTab ?? false
+    });
+}