@metamesh/modeling 0.0.0-bootstrap.0 → 0.6.0

package/dist/geometry/svg-import.js

@@ -0,0 +1,662 @@
+import { SaxesParser } from "saxes";
+import { GeometryError } from "./errors.js";
+import { regionArea, signedAreaLoop2 } from "./regions.js";
+import { resolveCircularSegments, resolveGeometryResolution, } from "./resolution.js";
+import { resolveGeometrySamplingLimits } from "./sampling-limits.js";
+import { strokePathMultiPolygon } from "./stroke-path.js";
+import { createBoundedSvgClipping } from "./svg/fill.js";
+import { flattenSvgSubpaths, SvgVertexBudget } from "./svg/path.js";
+const MAX_SVG_BYTES = 256 * 1024;
+const MAX_SVG_ELEMENTS = 500;
+const MAX_SVG_NESTING_DEPTH = 64;
+const MAX_SVG_NODES = 2_000;
+const SHORT_EDGE_LENGTH_MM = 0.01;
+const TINY_ISLAND_AREA_MM2 = 0.01;
+const SUPPORTED_TAGS = new Set([
+    "svg",
+    "g",
+    "rect",
+    "circle",
+    "ellipse",
+    "line",
+    "polyline",
+    "polygon",
+    "path",
+    "metadata",
+]);
+const SVG_NAMESPACE = "http://www.w3.org/2000/svg";
+const NUMBER_PATTERN = /^[-+]?(?:\d*\.\d+|\d+\.?)(?:e[-+]?\d+)?$/i;
+const SAFE_COLOR_PATTERN = /^(?:none|#[0-9a-f]{3,8}|(?:rgb|hsl)a?\([\d\s.,%+-]+\)|[a-z]+)$/i;
+const PRESENTATION_ATTRIBUTES = [
+    "fill",
+    "fill-opacity",
+    "fill-rule",
+    "stroke",
+    "stroke-linecap",
+    "stroke-linejoin",
+    "stroke-opacity",
+    "stroke-width",
+    "style",
+];
+const COMMON_ATTRIBUTES = new Set(["id", "name", "transform", ...PRESENTATION_ATTRIBUTES]);
+const ATTRIBUTES_BY_TAG = {
+    svg: new Set([
+        ...COMMON_ATTRIBUTES,
+        "height",
+        "preserveAspectRatio",
+        "version",
+        "viewBox",
+        "width",
+        "xmlns",
+    ]),
+    g: COMMON_ATTRIBUTES,
+    rect: new Set([...COMMON_ATTRIBUTES, "height", "rx", "ry", "width", "x", "y"]),
+    circle: new Set([...COMMON_ATTRIBUTES, "cx", "cy", "r"]),
+    ellipse: new Set([...COMMON_ATTRIBUTES, "cx", "cy", "rx", "ry"]),
+    line: new Set([...COMMON_ATTRIBUTES, "x1", "x2", "y1", "y2"]),
+    polyline: new Set([...COMMON_ATTRIBUTES, "points"]),
+    polygon: new Set([...COMMON_ATTRIBUTES, "points"]),
+    path: new Set([...COMMON_ATTRIBUTES, "d", "data-metamesh-text-id"]),
+    metadata: new Set(["id"]),
+};
+const DEFAULT_PAINT = {
+    fill: "black",
+    fillOpacity: 1,
+    fillRule: "nonzero",
+    stroke: "none",
+    strokeLinecap: "butt",
+    strokeLinejoin: "miter",
+    strokeOpacity: 1,
+    strokeWidth: 1,
+};
+function fail(message) {
+    throw new GeometryError("INVALID_ARGUMENT", message, { operation: "preflightSvgRegion" });
+}
+function complexityFail(message, details) {
+    throw new GeometryError("COMPLEXITY_LIMIT", message, {
+        operation: "preflightSvgRegion",
+        details,
+    });
+}
+function finite(value, fallback) {
+    if (value === undefined || value.trim() === "") {
+        if (fallback !== undefined)
+            return fallback;
+        return fail("A required SVG number is missing.");
+    }
+    if (!NUMBER_PATTERN.test(value.trim()))
+        return fail(`Invalid SVG number “${value}”.`);
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : fail(`Invalid SVG number “${value}”.`);
+}
+function multiply(left, right) {
+    return [
+        left[0] * right[0] + left[2] * right[1],
+        left[1] * right[0] + left[3] * right[1],
+        left[0] * right[2] + left[2] * right[3],
+        left[1] * right[2] + left[3] * right[3],
+        left[0] * right[4] + left[2] * right[5] + left[4],
+        left[1] * right[4] + left[3] * right[5] + left[5],
+    ];
+}
+function transformPoint(matrix, point) {
+    return [
+        matrix[0] * point[0] + matrix[2] * point[1] + matrix[4],
+        matrix[1] * point[0] + matrix[3] * point[1] + matrix[5],
+    ];
+}
+function parseTransform(value) {
+    if (value === undefined || value.trim() === "")
+        return [1, 0, 0, 1, 0, 0];
+    const pattern = /([a-zA-Z]+)\s*\(([^)]*)\)/g;
+    let result = [1, 0, 0, 1, 0, 0];
+    let matched = "";
+    let match;
+    while ((match = pattern.exec(value)) !== null) {
+        matched += match[0];
+        const name = match[1]?.toLowerCase();
+        const values = (match[2]?.match(/[-+]?(?:\d*\.\d+|\d+\.?)(?:e[-+]?\d+)?/gi) ?? []).map(Number);
+        let next;
+        if (name === "matrix" && values.length === 6) {
+            next = values;
+        }
+        else if (name === "translate" && values.length >= 1 && values.length <= 2) {
+            next = [1, 0, 0, 1, values[0] ?? 0, values[1] ?? 0];
+        }
+        else if (name === "scale" && values.length >= 1 && values.length <= 2) {
+            next = [values[0] ?? 1, 0, 0, values[1] ?? values[0] ?? 1, 0, 0];
+        }
+        else if (name === "rotate" && (values.length === 1 || values.length === 3)) {
+            const angle = ((values[0] ?? 0) * Math.PI) / 180;
+            const x = values[1] ?? 0;
+            const y = values[2] ?? 0;
+            const rotation = [
+                Math.cos(angle),
+                Math.sin(angle),
+                -Math.sin(angle),
+                Math.cos(angle),
+                0,
+                0,
+            ];
+            next = multiply([1, 0, 0, 1, x, y], multiply(rotation, [1, 0, 0, 1, -x, -y]));
+        }
+        else if (name === "skewx" && values.length === 1) {
+            next = [1, 0, Math.tan(((values[0] ?? 0) * Math.PI) / 180), 1, 0, 0];
+        }
+        else if (name === "skewy" && values.length === 1) {
+            next = [1, Math.tan(((values[0] ?? 0) * Math.PI) / 180), 0, 1, 0, 0];
+        }
+        else {
+            return fail(`Unsupported SVG transform “${name ?? ""}”.`);
+        }
+        result = multiply(result, next);
+    }
+    if (matched.replace(/[\s,]/g, "") !== value.replace(/[\s,]/g, "")) {
+        return fail("Invalid SVG transform syntax.");
+    }
+    return result;
+}
+function attributes(tag) {
+    const output = {};
+    for (const attribute of Object.values(tag.attributes)) {
+        const { name, value } = attribute;
+        if (name.toLowerCase().startsWith("on") || attribute.prefix !== "") {
+            return fail("Event handlers and custom namespaces are not supported in SVG geometry.");
+        }
+        if (/url\s*\(|javascript:/i.test(value))
+            return fail("External SVG references are not supported.");
+        output[name] = value;
+    }
+    return output;
+}
+function inlineStyle(value) {
+    if (value === undefined || value.trim() === "")
+        return {};
+    const output = {};
+    const allowed = new Set([
+        "fill",
+        "fill-opacity",
+        "fill-rule",
+        "stroke",
+        "stroke-linecap",
+        "stroke-linejoin",
+        "stroke-opacity",
+        "stroke-width",
+    ]);
+    for (const declaration of value.split(";")) {
+        if (declaration.trim() === "")
+            continue;
+        const separator = declaration.indexOf(":");
+        const key = declaration.slice(0, separator).trim().toLowerCase();
+        if (separator <= 0 || !allowed.has(key))
+            return fail(`Unsupported SVG style “${key}”.`);
+        output[key] = declaration.slice(separator + 1).trim();
+    }
+    return output;
+}
+function validateAttributes(tag, values) {
+    const allowed = ATTRIBUTES_BY_TAG[tag];
+    if (allowed === undefined)
+        return fail(`Unsupported SVG element <${tag}>.`);
+    for (const name of Object.keys(values)) {
+        if (!allowed.has(name))
+            return fail(`Unsupported SVG attribute “${name}” on <${tag}>.`);
+    }
+}
+function parsePaint(values, inherited) {
+    const style = inlineStyle(values.style);
+    // Inline declarations have CSS precedence over presentation attributes on the same element.
+    const value = (name) => style[name] ?? values[name];
+    const fillRule = value("fill-rule") ?? inherited.fillRule;
+    const strokeLinecap = value("stroke-linecap") ?? inherited.strokeLinecap;
+    const strokeLinejoin = value("stroke-linejoin") ?? inherited.strokeLinejoin;
+    if (fillRule !== "evenodd" && fillRule !== "nonzero")
+        return fail("Unsupported SVG fill rule.");
+    if (strokeLinecap !== "butt" && strokeLinecap !== "round" && strokeLinecap !== "square")
+        return fail("Unsupported SVG stroke cap.");
+    if (strokeLinejoin !== "bevel" && strokeLinejoin !== "miter" && strokeLinejoin !== "round")
+        return fail("Unsupported SVG stroke join.");
+    const fill = (value("fill") ?? inherited.fill).toLowerCase();
+    const stroke = (value("stroke") ?? inherited.stroke).toLowerCase();
+    if (!SAFE_COLOR_PATTERN.test(fill) || !SAFE_COLOR_PATTERN.test(stroke)) {
+        return fail("Unsupported SVG fill or stroke color.");
+    }
+    return {
+        fill,
+        fillOpacity: Math.min(1, Math.max(0, finite(value("fill-opacity"), inherited.fillOpacity))),
+        fillRule,
+        stroke,
+        strokeLinecap,
+        strokeLinejoin,
+        strokeOpacity: Math.min(1, Math.max(0, finite(value("stroke-opacity"), inherited.strokeOpacity))),
+        strokeWidth: Math.max(0, finite(value("stroke-width"), inherited.strokeWidth)),
+    };
+}
+function lengthMm(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    const match = /^([-+]?(?:\d*\.\d+|\d+\.?)(?:e[-+]?\d+)?)\s*(mm|cm|in|pt|pc|px)?$/i.exec(value.trim());
+    if (match === null)
+        return fail(`Unsupported SVG length “${value}”.`);
+    const factors = {
+        mm: 1,
+        cm: 10,
+        in: 25.4,
+        pt: 25.4 / 72,
+        pc: 25.4 / 6,
+        px: 25.4 / 96,
+    };
+    const factor = match[2] === undefined ? 1 : factors[match[2].toLowerCase()];
+    const number = Number(match[1]);
+    return factor !== undefined && Number.isFinite(number) && number > 0
+        ? number * factor
+        : fail("SVG dimensions must be positive.");
+}
+function viewBox(values) {
+    const parsed = values.viewBox?.split(/[\s,]+/).map(Number);
+    if (parsed === undefined)
+        return [0, 0, finite(values.width, 100), finite(values.height, 100)];
+    if (parsed.length !== 4 ||
+        parsed.some((entry) => !Number.isFinite(entry)) ||
+        (parsed[2] ?? 0) <= 0 ||
+        (parsed[3] ?? 0) <= 0) {
+        return fail("SVG viewBox must contain four finite values and positive dimensions.");
+    }
+    return parsed;
+}
+function canvasTransform(values, width, height, box, origin) {
+    const [x, y, viewWidth, viewHeight] = box;
+    const preserveAspectRatio = values.preserveAspectRatio?.trim() ?? "xMidYMid meet";
+    if (preserveAspectRatio !== "none" && preserveAspectRatio !== "xMidYMid meet") {
+        return fail('Only preserveAspectRatio="none" and "xMidYMid meet" are supported.');
+    }
+    const scaleX = width / viewWidth;
+    const scaleY = height / viewHeight;
+    const scale = preserveAspectRatio === "none" ? undefined : Math.min(scaleX, scaleY);
+    const appliedX = scale ?? scaleX;
+    const appliedY = scale ?? scaleY;
+    const offsetX = origin === "center" ? -(x + viewWidth / 2) * appliedX : -x * appliedX;
+    const offsetY = origin === "center" ? (y + viewHeight / 2) * appliedY : (y + viewHeight) * appliedY;
+    return [appliedX, 0, 0, -appliedY, offsetX, offsetY];
+}
+function isPainted(color, opacity) {
+    return color !== "none" && color !== "transparent" && opacity > 0;
+}
+function ellipsePoints(cx, cy, rx, ry, segments, budget) {
+    if (rx <= 0 || ry <= 0)
+        return fail("SVG ellipse radii must be positive.");
+    return Array.from({ length: segments }, (_, index) => {
+        budget.add("preflightSvgRegion");
+        const angle = (index * Math.PI * 2) / segments;
+        return [cx + Math.cos(angle) * rx, cy + Math.sin(angle) * ry];
+    });
+}
+function parsePoints(value) {
+    if (value === undefined)
+        return fail("SVG points are required.");
+    const numbers = value
+        .trim()
+        .split(/[\s,]+/)
+        .filter(Boolean)
+        .map(Number);
+    if (numbers.length < 4 ||
+        numbers.length % 2 !== 0 ||
+        numbers.some((entry) => !Number.isFinite(entry))) {
+        return fail("SVG points must contain finite X/Y pairs.");
+    }
+    const points = [];
+    for (let index = 0; index < numbers.length; index += 2)
+        points.push([numbers[index] ?? 0, numbers[index + 1] ?? 0]);
+    return points;
+}
+function inverseMatrix(matrix) {
+    const determinant = matrix[0] * matrix[3] - matrix[1] * matrix[2];
+    if (!Number.isFinite(determinant) || Math.abs(determinant) <= 1e-15) {
+        return fail("SVG geometry transforms must be non-singular.");
+    }
+    return [
+        matrix[3] / determinant,
+        -matrix[1] / determinant,
+        -matrix[2] / determinant,
+        matrix[0] / determinant,
+        (matrix[2] * matrix[5] - matrix[3] * matrix[4]) / determinant,
+        (matrix[1] * matrix[4] - matrix[0] * matrix[5]) / determinant,
+    ];
+}
+function maximumLinearScale(matrix) {
+    const trace = matrix[0] * matrix[0] + matrix[1] * matrix[1] + matrix[2] * matrix[2] + matrix[3] * matrix[3];
+    const determinant = matrix[0] * matrix[3] - matrix[1] * matrix[2];
+    return Math.sqrt(Math.max(0, (trace + Math.sqrt(Math.max(0, trace * trace - 4 * determinant * determinant))) / 2));
+}
+function adaptivePathSubpaths(d, transform, resolution, budget) {
+    if (d.trim() === "")
+        return fail("SVG path data is required.");
+    const inverse = inverseMatrix(transform);
+    try {
+        return flattenSvgSubpaths(d, transform, resolution, budget, "preflightSvgRegion").map(({ closed, points }) => ({
+            closed,
+            points: points.map((point) => transformPoint(inverse, point)),
+        }));
+    }
+    catch (error) {
+        if (error instanceof GeometryError)
+            throw error;
+        return fail(error instanceof Error ? `Invalid SVG path: ${error.message}` : "Invalid SVG path data.");
+    }
+}
+function elementSubpaths(tag, values, transform, resolution, budget) {
+    switch (tag) {
+        case "rect": {
+            const x = finite(values.x, 0);
+            const y = finite(values.y, 0);
+            const width = finite(values.width);
+            const height = finite(values.height);
+            if (width <= 0 || height <= 0)
+                return fail("SVG rectangle dimensions must be positive.");
+            const rx = values.rx === undefined ? finite(values.ry, 0) : finite(values.rx, 0);
+            const ry = values.ry === undefined ? rx : finite(values.ry, 0);
+            if (rx === 0 || ry === 0) {
+                return adaptivePathSubpaths(`M${x} ${y}H${x + width}V${y + height}H${x}Z`, transform, resolution, budget);
+            }
+            const radiusX = Math.min(Math.max(0, rx), width / 2);
+            const radiusY = Math.min(Math.max(0, ry), height / 2);
+            return adaptivePathSubpaths(`M${x + radiusX} ${y}H${x + width - radiusX}A${radiusX} ${radiusY} 0 0 1 ${x + width} ${y + radiusY}V${y + height - radiusY}A${radiusX} ${radiusY} 0 0 1 ${x + width - radiusX} ${y + height}H${x + radiusX}A${radiusX} ${radiusY} 0 0 1 ${x} ${y + height - radiusY}V${y + radiusY}A${radiusX} ${radiusY} 0 0 1 ${x + radiusX} ${y}Z`, transform, resolution, budget);
+        }
+        case "circle": {
+            const radius = finite(values.r);
+            const segments = resolveCircularSegments(radius * maximumLinearScale(transform), resolution, budget.limits);
+            return [
+                {
+                    closed: true,
+                    points: ellipsePoints(finite(values.cx, 0), finite(values.cy, 0), radius, radius, segments, budget),
+                },
+            ];
+        }
+        case "ellipse": {
+            const radiusX = finite(values.rx);
+            const radiusY = finite(values.ry);
+            const segments = resolveCircularSegments(Math.max(radiusX, radiusY) * maximumLinearScale(transform), resolution, budget.limits);
+            return [
+                {
+                    closed: true,
+                    points: ellipsePoints(finite(values.cx, 0), finite(values.cy, 0), radiusX, radiusY, segments, budget),
+                },
+            ];
+        }
+        case "line":
+            return adaptivePathSubpaths(`M${finite(values.x1, 0)} ${finite(values.y1, 0)}L${finite(values.x2, 0)} ${finite(values.y2, 0)}`, transform, resolution, budget);
+        case "polyline": {
+            const points = parsePoints(values.points);
+            return adaptivePathSubpaths(points.map(([x, y], index) => `${index === 0 ? "M" : "L"}${x} ${y}`).join(""), transform, resolution, budget);
+        }
+        case "polygon": {
+            const points = parsePoints(values.points);
+            return adaptivePathSubpaths(`${points.map(([x, y], index) => `${index === 0 ? "M" : "L"}${x} ${y}`).join("")}Z`, transform, resolution, budget);
+        }
+        case "path":
+            return adaptivePathSubpaths(values.d ?? "", transform, resolution, budget);
+        default:
+            return [];
+    }
+}
+function strokeConstructionVertexCount(subpath, paint, circularSegments) {
+    const minimumPoints = subpath.closed ? 3 : 2;
+    if (subpath.points.length < minimumPoints)
+        return 0;
+    const segments = subpath.closed ? subpath.points.length : subpath.points.length - 1;
+    const joins = subpath.closed ? subpath.points.length : Math.max(0, subpath.points.length - 2);
+    return (segments * 4 +
+        joins *
+            (paint.strokeLinejoin === "round"
+                ? circularSegments
+                : paint.strokeLinejoin === "miter"
+                    ? 4
+                    : 3) +
+        (!subpath.closed && paint.strokeLinecap === "round" ? 2 * circularSegments : 0));
+}
+function transformMultiPolygon(value, matrix) {
+    return value.map((polygon) => polygon.map((path) => path.map((point) => {
+        const transformed = transformPoint(matrix, point);
+        return [transformed[0], transformed[1]];
+    })));
+}
+function polygonArea(polygon) {
+    return (Math.abs(signedAreaLoop2(polygon.outer)) -
+        polygon.holes.reduce((total, hole) => total + Math.abs(signedAreaLoop2(hole)), 0));
+}
+function loopEdgeLengths(loop) {
+    return loop.map((point, index) => {
+        const next = loop[(index + 1) % loop.length];
+        return Math.hypot(next[0] - point[0], next[1] - point[1]);
+    });
+}
+function measureSvgRegion(region) {
+    const holes = region.reduce((total, polygon) => total + polygon.holes.length, 0);
+    let maxX = Number.NEGATIVE_INFINITY;
+    let maxY = Number.NEGATIVE_INFINITY;
+    let minEdgeLength = Number.POSITIVE_INFINITY;
+    let minX = Number.POSITIVE_INFINITY;
+    let minY = Number.POSITIVE_INFINITY;
+    let shortEdges = 0;
+    let vertices = 0;
+    for (const polygon of region) {
+        for (const loop of [polygon.outer, ...polygon.holes]) {
+            vertices += loop.length;
+            for (const point of loop) {
+                minX = Math.min(minX, point[0]);
+                minY = Math.min(minY, point[1]);
+                maxX = Math.max(maxX, point[0]);
+                maxY = Math.max(maxY, point[1]);
+            }
+            for (const length of loopEdgeLengths(loop)) {
+                minEdgeLength = Math.min(minEdgeLength, length);
+                if (length < SHORT_EDGE_LENGTH_MM)
+                    shortEdges += 1;
+            }
+        }
+    }
+    const bounds = region.length === 0
+        ? null
+        : Object.freeze({
+            max: Object.freeze([maxX, maxY]),
+            min: Object.freeze([minX, minY]),
+        });
+    return Object.freeze({
+        area: regionArea(region),
+        bounds,
+        components: region.length,
+        contours: region.length + holes,
+        holes,
+        minEdgeLength: Number.isFinite(minEdgeLength) ? minEdgeLength : null,
+        shortEdges,
+        tinyIslands: region.filter((polygon) => polygonArea(polygon) < TINY_ISLAND_AREA_MM2).length,
+        vertices,
+    });
+}
+/**
+ * Parses the bounded SVG subset into a robust millimetre region and an import-review report.
+ *
+ * Presentation colors are ignored, but every visible fill and positive-width stroke contributes
+ * geometry. Open filled subpaths use SVG's implicit closure while open strokes remain open.
+ * Transforms and declared physical units are flattened, viewport placement is explicit, and
+ * metadata is ignored. Tiny-island and short-edge counts are conservative physical indicators,
+ * not proof of raster provenance or process-specific manufacturability.
+ *
+ * @param svg - Complete SVG XML source, limited to 256 KiB of UTF-8.
+ * @param options - Physical flattening and viewport-origin controls.
+ * @returns The exact normalized region used for import plus bounded review metrics and repairs.
+ * @throws {@link GeometryError} When XML, supported-feature, geometry, or complexity checks fail.
+ */
+function createSvgRegionPreflight(svg, options = {}) {
+    const bytes = new TextEncoder().encode(svg).byteLength;
+    if (bytes > MAX_SVG_BYTES)
+        return fail("SVG geometry must be 256 KiB or smaller.");
+    const origin = options.origin ?? "center";
+    if (origin !== "center" && origin !== "document") {
+        return fail('SVG origin must be either "center" or "document".');
+    }
+    const limits = resolveGeometrySamplingLimits(options.limits);
+    const resolution = resolveGeometryResolution({
+        ...options.resolution,
+        ...(options.circularSegments === undefined
+            ? {}
+            : { circularSegments: options.circularSegments }),
+    }, limits);
+    const { assertExpandedVertexCount, boundedMultiPolygon, fillGeometry, multiPolygonVertexCount, regionFromMultiPolygon, unionAll, } = createBoundedSvgClipping(limits.maxProfilePoints);
+    const stack = [];
+    const geometry = [];
+    let elementCount = 0;
+    let emptyElements = 0;
+    let expandedGeometryVertices = 0;
+    let implicitFilledClosures = 0;
+    let invisibleElements = 0;
+    let nodeCount = 0;
+    let rootSeen = false;
+    let strokeConstructionVertices = 0;
+    const budget = new SvgVertexBudget(limits);
+    const appendGeometry = (target, value, stage) => {
+        const bounded = boundedMultiPolygon(value, stage);
+        expandedGeometryVertices += multiPolygonVertexCount(bounded);
+        assertExpandedVertexCount(expandedGeometryVertices, "accumulated geometry");
+        target.push(bounded);
+    };
+    // XML syntax and entity decoding belong to saxes; the bounded geometry policy stays here.
+    const parser = new SaxesParser({ xmlns: true });
+    parser.on("error", () => fail("SVG XML is malformed."));
+    parser.on("doctype", () => fail("DOCTYPE and entity declarations are not supported."));
+    parser.on("processinginstruction", () => fail("SVG processing instructions are not supported."));
+    parser.on("cdata", () => fail("SVG CDATA sections are not supported."));
+    parser.on("text", (text) => {
+        if (stack.at(-1)?.tag !== "metadata" && text.trim() !== "") {
+            return fail("Unexpected SVG text content.");
+        }
+    });
+    parser.on("opentag", (node) => {
+        if (node.prefix !== "" || (node.uri !== "" && node.uri !== SVG_NAMESPACE)) {
+            return fail("Custom XML namespaces are not supported.");
+        }
+        const tag = node.local;
+        if (tag === "image") {
+            return fail("This SVG contains an <image> element. MetaMesh requires real vector paths; embedded bitmap images are not supported. Re-export the original artwork as paths. Changing a PNG file extension or embedding it in an SVG will not work.");
+        }
+        if (!SUPPORTED_TAGS.has(tag))
+            return fail(`Unsupported SVG element <${tag}>.`);
+        nodeCount += 1;
+        if (nodeCount > MAX_SVG_NODES) {
+            complexityFail(`SVG may contain at most ${MAX_SVG_NODES} XML elements.`, {
+                maxNodes: MAX_SVG_NODES,
+                nodes: nodeCount,
+            });
+        }
+        if (!node.isSelfClosing && stack.length >= MAX_SVG_NESTING_DEPTH) {
+            complexityFail(`SVG nesting may be at most ${MAX_SVG_NESTING_DEPTH} elements deep.`, {
+                depth: stack.length + 1,
+                maxDepth: MAX_SVG_NESTING_DEPTH,
+            });
+        }
+        const values = attributes(node);
+        validateAttributes(tag, values);
+        const parent = stack.at(-1);
+        if (parent !== undefined && parent.tag !== "svg" && parent.tag !== "g") {
+            return fail(`Nested content in <${parent.tag}> is not supported.`);
+        }
+        if (tag === "svg" && parent !== undefined)
+            return fail("Nested SVG roots are not supported.");
+        let transform = multiply(parent?.transform ?? [1, 0, 0, 1, 0, 0], parseTransform(values.transform));
+        const paint = parsePaint(values, parent?.paint ?? DEFAULT_PAINT);
+        if (tag === "svg") {
+            if (rootSeen)
+                return fail("SVG must contain exactly one root element.");
+            rootSeen = true;
+            const box = viewBox(values);
+            const [, , viewWidth, viewHeight] = box;
+            const width = lengthMm(values.width, viewWidth);
+            const height = lengthMm(values.height, viewHeight);
+            transform = multiply(canvasTransform(values, width, height, box, origin), parseTransform(values.transform));
+        }
+        else if (parent === undefined) {
+            return fail("The SVG root element is missing.");
+        }
+        if (tag !== "metadata" && tag !== "svg" && tag !== "g") {
+            elementCount += 1;
+            if (elementCount > MAX_SVG_ELEMENTS)
+                return fail(`SVG geometry may contain at most ${MAX_SVG_ELEMENTS} elements.`);
+            const localSubpaths = elementSubpaths(tag, values, transform, resolution, budget);
+            const subpaths = localSubpaths.map((subpath) => ({
+                ...subpath,
+                points: subpath.points.map((point) => transformPoint(transform, point)),
+            }));
+            const paintedFill = isPainted(paint.fill, paint.fillOpacity);
+            const paintedStroke = isPainted(paint.stroke, paint.strokeOpacity) && paint.strokeWidth > 0;
+            const elementGeometry = [];
+            if (!paintedFill && !paintedStroke)
+                invisibleElements += 1;
+            if (paintedFill) {
+                implicitFilledClosures += subpaths.filter((subpath) => !subpath.closed && subpath.points.length >= 3).length;
+                appendGeometry(elementGeometry, fillGeometry(subpaths, paint.fillRule), "element fill output");
+            }
+            if (paintedStroke) {
+                const roundSegments = paint.strokeLinecap === "round" || paint.strokeLinejoin === "round"
+                    ? resolveCircularSegments((paint.strokeWidth / 2) * maximumLinearScale(transform), resolution, limits)
+                    : 3;
+                // Constructing the stroke before applying the affine matrix preserves SVG's
+                // exact non-uniform scale and skew behavior without a scalar-width approximation.
+                for (const subpath of localSubpaths) {
+                    strokeConstructionVertices += strokeConstructionVertexCount(subpath, paint, roundSegments);
+                    assertExpandedVertexCount(strokeConstructionVertices, "stroke construction");
+                    appendGeometry(elementGeometry, transformMultiPolygon(strokePathMultiPolygon(subpath.points, {
+                        cap: paint.strokeLinecap,
+                        closed: subpath.closed,
+                        join: paint.strokeLinejoin,
+                        width: paint.strokeWidth,
+                        limits,
+                    }, roundSegments), transform), "element stroke output");
+                }
+            }
+            if ((paintedFill || paintedStroke) && elementGeometry.every((value) => value.length === 0)) {
+                emptyElements += 1;
+            }
+            geometry.push(...elementGeometry);
+        }
+        stack.push({ tag, transform, paint });
+    });
+    parser.on("closetag", () => {
+        stack.pop();
+    });
+    parser.write(svg).close();
+    if (stack.length !== 0)
+        return fail("SVG contains unclosed elements.");
+    if (!rootSeen)
+        return fail("The SVG root element is missing.");
+    const region = regionFromMultiPolygon(unionAll(geometry));
+    assertExpandedVertexCount(region.reduce((total, polygon) => total +
+        polygon.outer.length +
+        polygon.holes.reduce((holeTotal, hole) => holeTotal + hole.length, 0), 0), "normalized region");
+    return Object.freeze({
+        geometry: measureSvgRegion(region),
+        region,
+        repairs: Object.freeze({
+            emptyElements,
+            implicitFilledClosures,
+            invisibleElements,
+            removedDuplicateVertices: budget.removedDuplicateCount,
+            removedSeamVertices: budget.removedSeamCount,
+        }),
+        source: Object.freeze({
+            bytes,
+            elements: elementCount,
+            emittedVertices: budget.emittedCount,
+            parsedVertices: budget.parsedCount,
+        }),
+    });
+}
+/**
+ * Preflights bounded SVG geometry without browser or Manifold dependencies.
+ *
+ * @param svg - Complete SVG XML source, limited to 256 KiB of UTF-8.
+ * @param options - Physical flattening and viewport-origin controls.
+ * @returns The canonical normalized region plus bounded source, topology, and safe-repair facts.
+ */
+export function preflightSvgRegion(svg, options = {}) {
+    return createSvgRegionPreflight(svg, options);
+}

package/dist/geometry/sweeps/options.js

@@ -0,0 +1,28 @@
+import { GeometryError } from "../errors.js";
+/** @internal Validates local scales before any manufacturing buffer allocation. */
+export function resolveSweepScales(scale, stationCount) {
+    const fail = () => {
+        throw new GeometryError("INVALID_ARGUMENT", "Sweep scales must be positive finite XY pairs, with one pair per station when varying.", { operation: "sweep" });
+    };
+    const pair = (value) => {
+        if (typeof value === "number") {
+            if (!(value > 0) || !Number.isFinite(value))
+                fail();
+            return [value, value];
+        }
+        if (!Array.isArray(value) ||
+            value.length !== 2 ||
+            !value.every((n) => typeof n === "number" && Number.isFinite(n) && n > 0))
+            fail();
+        return value;
+    };
+    if (scale === undefined ||
+        typeof scale === "number" ||
+        (Array.isArray(scale) && typeof scale[0] === "number")) {
+        const value = pair(scale ?? 1);
+        return Array.from({ length: stationCount }, () => value);
+    }
+    if (!Array.isArray(scale) || scale.length !== stationCount)
+        fail();
+    return scale.map(pair);
+}