@layoutit/polycss-core 0.2.0 → 0.2.2

package/dist/index.d.ts

@@ -25,7 +25,7 @@ type MeshResolution = "lossless" | "lossy";
  * and the difference adds up. Destructure with `const [x, y, z] = v` when
  * you need named axes.
  *
- * Polycss world space convention: +X right, +Y forward, +Z up.
+ * PolyCSS world space convention: +X right, +Y forward, +Z up.
  */
 type Vec3 = [number, number, number];
 /**
@@ -39,6 +39,12 @@ interface TextureTriangle {
     vertices: [Vec3, Vec3, Vec3];
     uvs: [Vec2, Vec2, Vec2];
 }
+type PolyTextureWrapMode = "repeat" | "clamp-to-edge" | "mirrored-repeat";
+interface PolyTextureWrap {
+    s: PolyTextureWrapMode;
+    t: PolyTextureWrapMode;
+}
+type PolyTextureAlphaMode = "opaque" | "mask" | "blend";
 /**
  * Directional light — simulates a single distant source (sun, key light).
  * Contributes Lambert shading scaled by `intensity`. `direction` is in
@@ -70,7 +76,7 @@ interface PolyAmbientLight {
  *
  * In CSS terms, a material bundles the `background-image` source plus paint
  * config. When a polygon references a material AND its UVs form an
- * axis-aligned rectangle, polycss renders the polygon as an <i> with
+ * axis-aligned rectangle, PolyCSS renders the polygon as an <i> with
  * `background-image: url(material.texture)` directly — no per-polygon canvas
  * rasterization, browser-cached texture, mounting / unmounting one polygon
  * does not affect any other.
@@ -82,7 +88,7 @@ interface PolyAmbientLight {
 interface PolyMaterial {
     /** Image source. Anything `background-image: url(...)` can use. */
     texture: string;
-    /** Optional unique key (used by polycss to dedupe / cache). Caller can
+    /** Optional unique key (used by PolyCSS to dedupe / cache). Caller can
      *  pass a stable string; if omitted, the material's identity is its object
      *  reference. */
     key?: string;
@@ -107,10 +113,24 @@ interface Polygon {
      * `color` (or default gray).
      */
     texture?: string;
+    /**
+     * Texture sampler wrap mode for UVs outside [0, 1]. glTF imports preserve
+     * sampler.wrapS / wrapT here so the atlas rasterizer can tile repeated UVs.
+     * When unset, renderers keep the historical single-image behavior.
+     * @internal
+     */
+    textureWrap?: PolyTextureWrap;
+    /**
+     * Texture alpha interpretation imported from glTF `material.alphaMode`.
+     * Opaque textures can use transparent PNG padding without cutting holes in
+     * the rendered polygon.
+     * @internal
+     */
+    textureAlphaMode?: PolyTextureAlphaMode;
     /**
      * Shared material. When set, `material.texture` takes precedence over the
      * inline `texture` field. If the polygon's UVs form an axis-aligned
-     * rectangle, polycss uses the direct CSS background-image path (no per-
+     * rectangle, PolyCSS uses the direct CSS background-image path (no per-
      * polygon canvas rasterization). Falls back to the atlas path otherwise.
      */
     material?: PolyMaterial;
@@ -127,6 +147,26 @@ interface Polygon {
      * @internal
      */
     textureTriangles?: TextureTriangle[];
+    /**
+     * Import-time simplifier seam keys retained after solid texture baking.
+     * Renderers ignore this; mesh optimization uses it to avoid welding vertices
+     * that shared a position but came from different texture/attribute seams.
+     * @internal
+     */
+    simplifyVertexKeys?: string[];
+    /**
+     * Stricter import-time simplifier keys that preserve source vertex identity.
+     * Renderers ignore this; candidate simplification uses it only for fallback
+     * passes where relaxed seam welding loses after render-cost optimization.
+     * @internal
+     */
+    simplifySourceVertexKeys?: string[];
+    /**
+     * Source material requested two-sided rendering. Importers use this so
+     * optimization passes do not collapse intentional reverse-wound faces.
+     * @internal
+     */
+    doubleSided?: boolean;
     /**
      * User-controlled metadata. Reflected to DOM as `data-*` attributes via
      * stringification by the framework wrappers. Only string|number|boolean
@@ -157,8 +197,8 @@ declare function normalizePolygons(input: Polygon[]): NormalizeResult;
  * (already normalized) and returns the data the framework wrappers need
  * to render.
  *
- * No cube grid, no per-Z layer bucketing, no wall mask, no neighbor-based
- * occlusion. Just a polygon list and a scene bbox.
+ * The renderer consumes a flat polygon list plus a scene bbox; higher-level
+ * culling or mesh optimization happens before this context is built.
  */
 
 interface SceneBbox {
@@ -210,10 +250,8 @@ declare function buildSceneContext(args: SceneContextBuildArgs): SceneContextBui
 
 /**
  * Polygon geometry helpers — pure math operating on Polygon vertices.
- *
- * After cube removal in Phase 2, this module carries small polygon-level
- * helpers for downstream consumers (lighting, debug metrics, etc.). The
- * cube / ramp / wedge / spike face emitters lived here in voxcss; they're gone.
+ * These helpers feed lighting, diagnostics, and renderer metrics without
+ * depending on browser APIs.
  */
 
 interface PolygonFace {
@@ -252,8 +290,7 @@ interface TexturePaintMetrics {
 }
 /**
  * Surface a polygon as a single face. The returned array always has length 1;
- * the indirection exists so callers that historically iterated faces (e.g.
- * the manifold check, the canvas validator) can keep their loop shape.
+ * the indirection lets face-oriented consumers keep a common loop shape.
  *
  * Returns an empty array for degenerate polygons (< 3 vertices).
  */
@@ -262,7 +299,7 @@ declare function computeTexturePaintMetrics(polygons: Polygon[], options?: Textu
 
 /**
  * Apply CSS-style chained `rotateX(rx) rotateY(ry) rotateZ(rz)` rotation
- * to a 3D vector. Matches the matrix composition used by polycss mesh
+ * to a 3D vector. Matches the matrix composition used by PolyCSS mesh
  * wrapper transforms (see `buildTransform` in each PolyMesh implementation).
  *
  * CSS composes `transform: rotateX(rx) rotateY(ry) rotateZ(rz)` as the
@@ -287,6 +324,20 @@ declare function rotateVec3(v: Vec3, rxDeg: number, ryDeg: number, rzDeg: number
  * `rot` is `[rxDeg, ryDeg, rzDeg]` matching the mesh's CSS rotation prop.
  */
 declare function inverseRotateVec3(v: Vec3, rot: Vec3): Vec3;
+/**
+ * Apply the wrapper's actual CSS rotation matrix to a CSS-frame vector,
+ * given the user-supplied world rotation tuple `[rx_w, ry_w, rz_w]`.
+ *
+ * The wrapper emits `rotateY(-rx_w) rotateX(-ry_w) rotateZ(-rz_w)` (the
+ * world↔CSS reflection conjugation of three.js XYZ Euler). That matrix
+ * is `Ry(-rx_w) · Rx(-ry_w) · Rz(-rz_w) · v` applied to a vector. Use
+ * this anywhere downstream code needs to transform a CSS-frame normal or
+ * point through the same rotation the wrapper applies — e.g. back-face
+ * culling, voxel item ordering. NOT for inverse-rotating a world light
+ * direction into mesh-local frame — that still uses `inverseRotateVec3`
+ * with the user's world rotation, since it operates in world frame.
+ */
+declare function rotateVec3InWrapperCssFrame(v: Vec3, worldRot: Vec3): Vec3;
 
 /**
  * Minimal quaternion helpers for composing rotations.
@@ -334,7 +385,7 @@ declare function quatFromEulerXYZ(eulerDeg: Vec3): Quat;
 declare function eulerXYZFromQuat(q: Quat): Vec3;
 
 /**
- * Base tile size in CSS pixels. One polycss world unit = BASE_TILE CSS
+ * Base tile size in CSS pixels. One PolyCSS world unit = BASE_TILE CSS
  * pixels (pre-scale). Used to convert world-coordinate target values to
  * CSS translations in the transform string.
  */
@@ -349,7 +400,7 @@ type AutoRotateOption = boolean | number | AutoRotateConfig;
  * World-coordinate camera state (Three.js-style).
  *
  * `target` is the world point that should appear at the viewport centre.
- * Polycss world axes: [0]=X (rows/south), [1]=Y (cols/east), [2]=Z (up).
+ * PolyCSS world axes: [0]=X (rows/south), [1]=Y (cols/east), [2]=Z (up).
  *
  * `pan`, `tilt`, and `depthOffset` are gone. Translations now live inside
  * `target` so they happen BEFORE rotations — enabling correct world-space
@@ -358,7 +409,7 @@ type AutoRotateOption = boolean | number | AutoRotateConfig;
  * `distance` is the camera's pull-back from the target in CSS pixels.
  * Increasing distance moves the camera farther from the target along the
  * view axis (dolly out) — analogous to three.js's spherical radius.
- * Default 0 keeps the legacy behaviour unchanged.
+ * Default 0 keeps orthographic/isometric scenes flat.
  */
 interface CameraState {
     target: Vec3;
@@ -385,6 +436,66 @@ declare function normalizeInvertMultiplier(value: number | boolean | undefined):
 declare const DEFAULT_CAMERA_STATE: CameraState;
 declare function createIsometricCamera(initial?: Partial<CameraState>): CameraHandle;
 
+/**
+ * Screen → world inverse projection helpers.
+ *
+ * The camera transform a CameraHandle emits is:
+ *
+ *   `translateZ(-distance) scale(zoom/tile) rotateX(rotX) rotate(rotY) translate3d(-cssX, -cssY, -cssZ)`
+ *
+ * (right-to-left for point transforms). For an orthographic camera the
+ * depth component drops out at projection time, so a screen position
+ * (mx, my) unprojects to a 3D RAY in world space — every depth value
+ * along that ray maps to the same screen position. Callers pick a
+ * specific 3D point by intersecting the ray with a surface they care
+ * about (here: a sphere).
+ *
+ * `screenToWorldOnSphere` is the common case: given a mouse position,
+ * find where on a fixed sphere (e.g. the draggable light marker's
+ * sphere of constant radius) the cursor is pointing. Returns null
+ * when the ray misses the sphere.
+ */
+
+interface ScreenToWorldOptions {
+    /** Camera state — rotX/rotY/zoom/target, same shape `CameraHandle.state` exposes. */
+    camera: CameraState;
+    /** World-units → CSS-px factor. Pass `DEFAULT_TILE` from the renderer. */
+    tileSize: number;
+    /** Viewport center in CSS pixels (screen coordinates). The mouse position
+     *  is interpreted relative to this point. */
+    viewportCenterX: number;
+    viewportCenterY: number;
+    /** Mouse screen position (CSS pixels). */
+    mouseX: number;
+    mouseY: number;
+}
+/**
+ * Unproject the cursor to a ray in world coordinates.
+ *
+ *   `ray(t) = origin + t · direction`
+ *
+ * `origin` is the world point that screen-coincides with the mouse at
+ * depth t=0; `direction` is the camera-forward axis in world frame.
+ * For orthographic cameras the ray is parallel — every point along it
+ * projects to the same screen position.
+ */
+declare function screenToWorldRay(opts: ScreenToWorldOptions): {
+    origin: Vec3;
+    direction: Vec3;
+};
+/**
+ * Unproject the cursor and intersect with a sphere in world coords.
+ * Returns the FRONT intersection (the one closer to the camera) when
+ * the ray hits the sphere. When the ray misses (cursor outside the
+ * projected silhouette), returns the point on the sphere's silhouette
+ * closest to the cursor — that way callers like draggable helpers keep
+ * tracking the cursor along the rim instead of freezing in place.
+ */
+declare function screenToWorldOnSphere(opts: ScreenToWorldOptions & {
+    sphereCenter: Vec3;
+    sphereRadius: number;
+}): Vec3 | null;
+
 interface ParsedColor {
     rgb: [number, number, number];
     alpha: number;
@@ -421,9 +532,8 @@ declare function computeShapeLighting(normal: Vec3, baseColor: string, direction
 /**
  * Merge coplanar same-color adjacent triangles into N-vertex polygons.
  *
- * Each polygon is rendered as one atlas-backed DOM element — so a mesh whose
- * triangles came from quads or pentagons collapses back into its original
- * face count.
+ * Each visible polygon renders as one DOM leaf — so a mesh whose triangles
+ * came from quads or pentagons collapses back into its original face count.
  *
  *   - Geodesic spheres: ~half the triangles came from quad subdivisions
  *   - OBJ imports: many were quads/n-gons fan-triangulated by the importer
@@ -454,10 +564,9 @@ declare function mergePolygons(input: Polygon[]): Polygon[];
  * Why this exists: modelers (and importers) often emit redundant geometry
  * for the same visible surface — a doubled face on a wall, an inner shell
  * coincident with an outer shell, or two N-gons that fan-triangulate the
- * same region. Each duplicate is a real `<i>` element at render time:
- * it costs DOM, Lambert math, atlas budget, AND it produces stacked
- * shadow leaves that visibly multiply on the receiver (overlapping dark
- * patches on the ground).
+ * same region. Each duplicate is a real render leaf at render time:
+ * it costs DOM, Lambert math, atlas budget, and redundant shadow projection
+ * work.
  *
  * This is a separate concern from `cullInteriorPolygons` (which removes
  * polygons fully *enclosed* by other geometry, conservative against
@@ -509,6 +618,10 @@ interface DedupeOverlappingPolygonsOptions {
      *  containment ratios) for a pair to count as a duplicate.
      *  Default 0.7. Lower (~0.4) is liberal; higher (~0.9) is strict. */
     overlapFraction?: number;
+    /** Preserve reverse-wound faces from authored double-sided materials.
+     *  Geometry dedupe keeps these by default; shadow dedupe can disable it
+     *  because coincident front/back casters produce stacked shadows. */
+    preserveDoubleSidedBackfaces?: boolean;
 }
 /** Identify polygons that are duplicates within tolerance. Returns the
  *  set of indices into the input array that should be dropped (the
@@ -517,9 +630,8 @@ interface DedupeOverlappingPolygonsOptions {
  *  larger area as a tiebreaker.
  *
  *  Exposed for callers that want to act on the index set directly —
- *  e.g. shadow casting can use a looser tolerance to skip shadow leaves
- *  for redundant casters without removing them from the renderable
- *  polygon set. */
+ *  e.g. shadow casting can use a looser tolerance to skip redundant caster
+ *  projections without removing them from the renderable polygon set. */
 declare function findOverlappingPolygonDuplicates(input: Polygon[], options?: DedupeOverlappingPolygonsOptions): Set<number>;
 declare function dedupeOverlappingPolygons(input: Polygon[], options?: DedupeOverlappingPolygonsOptions): Polygon[];
 
@@ -542,29 +654,271 @@ interface CoverPlanarPolygonsOptions {
  */
 declare function coverPlanarPolygons(input: Polygon[], options?: CoverPlanarPolygonsOptions): Polygon[];
 
-interface ApproximateMergeOptions {
-    maxAngleDeg?: number;
-    maxPlaneDisplacement?: number;
-    maxBoundaryDisplacement?: number;
-    isolatedPairs?: boolean;
+interface SimplifyTriangleMeshPolygonsOptions {
+    /** Target triangle ratio per eligible connected material group. Default 0.7. */
+    ratio?: number;
+    /** Maximum accepted local plane displacement in scene units. Default 0.18. */
+    maxError?: number;
+    /** Reject collapses that rotate any affected face beyond this angle. Default 65. */
+    maxNormalAngleDeg?: number;
+    /** Only collapse vertices onto existing endpoint positions. Default true. */
+    preserveVertices?: boolean;
+    /** Use stricter importer source-vertex keys instead of relaxed seam keys. Default "relaxed". */
+    vertexKeyMode?: "relaxed" | "source";
+    /** Keep topological/material boundary vertices fixed. Default true. */
+    lockBoundary?: boolean;
+    /** Skip small groups where decimation is unlikely to repay the mutation cost. Default 80. */
+    minGroupTriangles?: number;
+    /** Hard cap for rebuild passes. Default 12. */
+    maxPasses?: number;
 }
+/**
+ * Import-time triangle decimation for already-solid meshes.
+ *
+ * This is deliberately conservative: textured polygons and material/color
+ * boundaries are kept out of the collapse graph, endpoint-preserving collapses
+ * mirror meshoptimizer's index-buffer simplification shape by default, and
+ * callers can cheaply compare the returned candidate against their normal
+ * render-cost optimizer before accepting it.
+ */
+declare function simplifyTriangleMeshPolygons(polygons: Polygon[], options?: SimplifyTriangleMeshPolygonsOptions): Polygon[];
+
 interface OptimizeMeshPolygonsOptions {
     /** Public quality/resolution intent. Defaults to "lossy". */
     meshResolution?: MeshResolution;
+    /**
+     * Return as soon as the optimizer finds a result with at most this many
+     * polygons. Useful for candidate comparisons where the caller already knows
+     * the maximum DOM leaf count it can accept.
+     */
+    stopAtPolygonCount?: number;
     /**
      * Run the planar cover pass as an exact candidate for untextured coplanar
      * regions. Defaults to true.
      */
     rectCover?: boolean | CoverPlanarPolygonsOptions;
+}
+declare function optimizeMeshPolygons(polygons: Polygon[], options?: OptimizeMeshPolygonsOptions): Polygon[];
+
+/**
+ * Unified parser return type. All polygon-emitting parsers (parseObj,
+ * parseGltf, parseVox, parseStl, the loadMesh dispatcher) return this exact shape.
+ *
+ * The asymmetric helper `parseMtl` returns its own `MtlParseResult` (it
+ * emits materials, not polygons) — see parseMtl.ts for the rationale.
+ *
+ * Lifecycle contract: callers MUST call `dispose()` when the result is no
+ * longer needed. Idempotent — safe to call on unmount even if `objectUrls`
+ * is empty (e.g. `parseObj`, where it's a no-op).
+ */
+
+interface PolyVoxelCell {
+    x: number;
+    y: number;
+    z: number;
+    color: string;
+}
+interface PolyVoxelSource {
+    kind: "magica-vox";
+    cells: PolyVoxelCell[];
+    rows: number;
+    cols: number;
+    depth: number;
+    scale: number;
+    sourceBytes: number;
+}
+interface ParseStlTopology {
+    componentCount: number;
+    repairedTriangleCount: number;
+    outwardComponentCount: number;
+    suppliedNormalComponentCount: number;
+    inconsistentSharedEdgeCount: number;
+    nonManifoldSharedEdgeCount: number;
+}
+interface ParseStlColor {
+    format: "magics";
+    defaultColor: string;
+    alpha: number;
+    coloredTriangleCount: number;
+    defaultColorTriangleCount: number;
+}
+interface ParseStlSolid {
+    name: string;
+    start: number;
+    count: number;
+}
+interface ParseAnimationClip {
+    /** Stable numeric index in the source file's animation array. */
+    index: number;
+    /** Human-readable clip name. Falls back to `animation_N` when omitted. */
+    name: string;
+    /** Clip duration in seconds, derived from its sampler input accessors. */
+    duration: number;
+    /** Number of glTF animation channels in the clip. */
+    channelCount: number;
+}
+interface ParseAnimationController {
+    /** Animation clips exposed by the parsed mesh. Empty when none are usable. */
+    clips: ParseAnimationClip[];
     /**
-     * Lossy approximate merge settings. Ignored for lossless resolution.
-     * When omitted, lossy evaluates isolated-pair and small plane-group
-     * strategies, then chooses the lowest render-cost result with a near-cost
-     * preference for candidates that reduce detected internal gaps.
+     * Sample a clip at `timeSeconds` and return a fresh polygon list.
+     * `clip` accepts either the clip index or its name. Time wraps by duration.
      */
-    approximateMerge?: boolean | ApproximateMergeOptions;
+    sample: (clip: number | string, timeSeconds: number) => Polygon[];
 }
-declare function optimizeMeshPolygons(polygons: Polygon[], options?: OptimizeMeshPolygonsOptions): Polygon[];
+interface ParseResult {
+    /** The mesh, as a flat polygon list. Already vertex-permuted to polycss space. */
+    polygons: Polygon[];
+    /** Optional raw voxel source for `.vox` fast paths; polygon fallback remains authoritative. */
+    voxelSource?: PolyVoxelSource;
+    /** Optional animation sampler for formats that carry timeline data. */
+    animation?: ParseAnimationController;
+    /**
+     * Blob/object URLs minted during parse (e.g. embedded GLB images). Pass-by-
+     * reference — the same array is exposed on the result for visibility, and
+     * `dispose()` revokes each one. Do NOT mutate this array externally.
+     */
+    objectUrls: string[];
+    /**
+     * Idempotent — revokes object URLs. Safe to call on unmount, safe to call
+     * twice. Parsers without minted URLs (parseObj, parseMtl) supply a no-op.
+     */
+    dispose: () => void;
+    /**
+     * Non-fatal warnings raised during parse. Empty for parsers that don't
+     * have a warning channel; populated when downstream `normalizePolygons`
+     * is invoked through the high-level pipeline.
+     */
+    warnings: string[];
+    /** Optional format-specific metadata. */
+    metadata?: {
+        /** Triangle count after fan-triangulation (parseObj) or post-triangulation (parseGltf). */
+        triangleCount?: number;
+        /** Mesh names from the file (for glTF, from doc.meshes[].name). */
+        meshes?: string[];
+        /** Material names (in first-seen order). */
+        materials?: string[];
+        /** Animation clips from the file, mirrored from `animation.clips`. */
+        animations?: ParseAnimationClip[];
+        /** Source file size in bytes (for diagnostics). */
+        sourceBytes?: number;
+        /** Voxel count for `.vox` sources. */
+        voxelCount?: number;
+        /** Printable binary STL header, trimmed. */
+        stlHeader?: string;
+        /** Binary STL color metadata when a supported color extension is present. */
+        stlColor?: ParseStlColor;
+        /** Consecutive ASCII `solid` groups after parse/filtering. */
+        stlSolids?: ParseStlSolid[];
+        /** STL winding/connectivity diagnostics. */
+        stlTopology?: ParseStlTopology;
+    };
+}
+
+interface OptimizeMeshParseResultOptions {
+    /** Render-cost optimization intent. Defaults to "lossy". */
+    meshResolution?: MeshResolution;
+    /** Parse result before solid texture baking, used to identify baked swatch faces. */
+    source?: ParseResult;
+    /** Merge near-identical baked swatch colors in lossy mode. Default 36. */
+    bakedTextureColorMergeDistance?: number;
+    /** Try static triangle simplification before final polygon optimization. Default true. */
+    simplifyTriangleMeshes?: boolean;
+    /** Options for the static triangle simplifier. */
+    simplifyTriangleMeshOptions?: SimplifyTriangleMeshPolygonsOptions;
+    /** Candidate optimizer early-stop drop target. Default 0.15. */
+    simplifyEarlyStopDropRatio?: number;
+}
+declare function optimizeMeshParseResult(result: ParseResult, options?: OptimizeMeshParseResultOptions): ParseResult;
+
+type SeamOverlapCandidateKind = "true-gap" | "connected-facet" | "material-boundary";
+interface SeamOverlapCandidate {
+    kind: SeamOverlapCandidateKind;
+    aPolygon: number;
+    aEdge: number;
+    bPolygon: number;
+    bEdge: number;
+    aColor?: string;
+    bColor?: string;
+    aMaterialKey: string;
+    bMaterialKey: string;
+    gapPx: number;
+    spanPx: number;
+    aStartPx: number;
+    aEndPx: number;
+    bStartPx: number;
+    bEndPx: number;
+    targetClosurePx: number;
+    appliedClosurePx: number;
+    residualGapPx: number;
+    residualTargetPx: number;
+}
+interface SeamOverlapDiagnostics {
+    exactPairs: number;
+    nearPairs: number;
+    patchedPolygons: number;
+    patchedEdges: number;
+    maxMeasuredGapPx: number;
+    maxAppliedAmountPx: number;
+    unclosedPairs: number;
+    maxResidualGapPx: number;
+}
+interface SeamOverlapOptions {
+    overlapPx?: number;
+    maxGapPx?: number;
+    capacityScale?: number;
+}
+interface SeamFacetSplitOptions {
+    rotX?: number;
+    rotY?: number;
+    viewAware?: boolean;
+    passes?: number;
+    budget?: number;
+}
+type SeamFacetSplitCandidateReason = "component-anchor" | "global-outlier" | "local-follow-up" | "shared-polygon" | "below-threshold";
+interface SeamFacetSplitCandidate {
+    key: string;
+    aPolygon: number;
+    aEdge: number;
+    bPolygon: number;
+    bEdge: number;
+    color?: string;
+    materialKey: string;
+    lengthPx: number;
+    projectedLengthPx: number;
+    score: number;
+    normalRisk: number;
+    shapeRisk: number;
+    viewRisk: number;
+    component: number;
+    marginalCost: number;
+    selected: boolean;
+    reason: SeamFacetSplitCandidateReason;
+}
+interface SeamFacetSplitReport {
+    candidates: SeamFacetSplitCandidate[];
+    selectedPolygons: number;
+    selectedEdges: number;
+    addedPolygons: number;
+}
+
+declare const DEFAULT_SEAM_OVERLAP_OPTIONS: {
+    readonly overlapPx: 1.25;
+    readonly maxGapPx: 14;
+    readonly capacityScale: 1;
+};
+declare const DEFAULT_SEAM_FACET_SPLIT_OPTIONS: {
+    readonly budget: 40;
+};
+declare function seamFacetSplitPolygons(polygons: Polygon[], seamOptions?: number | SeamOverlapOptions, splitOptions?: SeamFacetSplitOptions): Polygon[];
+declare function seamFacetSplitReport(polygons: Polygon[], seamOptions?: number | SeamOverlapOptions, splitOptions?: SeamFacetSplitOptions): SeamFacetSplitReport;
+declare function seamOverlapPolygons(polygons: Polygon[], options?: number | SeamOverlapOptions): Polygon[];
+declare function repairMeshSeams(polygons: Polygon[], seamOptions?: number | SeamOverlapOptions, splitOptions?: SeamFacetSplitOptions): Polygon[];
+declare function seamOverlapDiagnostics(polygons: Polygon[], options?: number | SeamOverlapOptions): SeamOverlapDiagnostics;
+declare function seamOverlapReport(polygons: Polygon[], options?: number | SeamOverlapOptions): {
+    diagnostics: SeamOverlapDiagnostics;
+    candidates: SeamOverlapCandidate[];
+};
 
 /**
  * cullInteriorPolygons — remove polygons that are fully enclosed by other
@@ -588,11 +942,58 @@ declare function optimizeMeshPolygons(polygons: Polygon[], options?: OptimizeMes
  */
 
 interface CullInteriorOptions {
-    /** Hemisphere ray samples per polygon. Higher = fewer false positives, slower. Default 12. */
+    /** Hemisphere ray samples per polygon. Higher = fewer false positives, slower. Default 8. */
     samples?: number;
+    /** Bypass the "large open topology" safety bail-out. By default a mesh
+     *  with >20% boundary edges is treated as open (terrain, partial geometry)
+     *  and culling is skipped to avoid false-positive removals on exposed faces.
+     *  Buildings imported from OBJ commonly have windows/doors that push the
+     *  boundary ratio above the threshold while STILL having clearly enclosed
+     *  interior walls that should be culled — set this when the caller has
+     *  another signal (e.g. mesh is known to be a building / room) that
+     *  interior culling is desired. Default false. */
+    force?: boolean;
+    /** Fraction of sample directions that must find at least one escaping
+     *  origin for the polygon to count as visible. Default `1 / samples`
+     *  (the original "any escape keeps" behaviour). Raise to ~0.5 to
+     *  classify polygons as interior when MOST hemisphere directions are
+     *  blocked — catches interior panels of building meshes (the cottage's
+     *  porch trim, back-of-wall door frames) that have a sliver of clear
+     *  sky through windows/openings but are otherwise enclosed. */
+    minEscapeRatio?: number;
 }
 declare function cullInteriorPolygons(polygons: Polygon[], options?: CullInteriorOptions): Polygon[];
 
+/**
+ * computeLightVisibility — for each polygon of a mesh, determines whether
+ * direct light from a given direction physically reaches it (ray from the
+ * polygon's centroid toward the light source is unblocked) or is occluded
+ * by other geometry of the same mesh.
+ *
+ * This is the CPU equivalent of one shadow-map sample per polygon from the
+ * light's POV. Used by the baked atlas pipeline so polygons in shadow get
+ * lit with ambient-only color, matching Three.js's depth-pass occlusion.
+ *
+ * Algorithm: Möller-Trumbore ray-triangle intersection per candidate, with
+ * a flat-array BVH for any-hit traversal. Cost: O(F log F) per mesh per
+ * light direction. Cottage at ~240 polys: ~5-10 ms. Caller should cache by
+ * (mesh geometry version, lightDir hash) and only recompute on change.
+ */
+
+/**
+ * Returns a Set of polygon indices that are OCCLUDED from the light
+ * (a ray from the polygon's centroid in the +lightDir direction hits
+ * another polygon of the same mesh before escaping to infinity).
+ *
+ * `lightDir` is the direction TO the light source (matching the
+ * convention used by `shadePolygon`'s caller — points from the
+ * surface toward the light).
+ *
+ * Caller should cache by mesh-geometry version + lightDir hash;
+ * recompute only when either changes.
+ */
+declare function computeLightVisibility(polygons: readonly Polygon[], lightDir: Vec3, skipIndices?: ReadonlySet<number>): Set<number>;
+
 declare const CAMERA_BACKFACE_CULL_EPS = 0.00001;
 declare const VOXEL_CAMERA_CULL_AXIS_EPS = 0.001;
 declare const VOXEL_CAMERA_CULL_NORMAL_LIMIT = 6;
@@ -621,7 +1022,7 @@ declare function cameraCullVisibleSignature(groups: readonly CameraCullNormalGro
  * cuboids stretching along world-X, world-Y and world-Z. Mirrors the
  * convention `red=X, green=Y, blue=Z`.
  *
- * Returned polygons are in the standard polycss world-space convention
+ * Returned polygons are in the standard PolyCSS world-space convention
  * (`+X right, +Y forward, +Z up`). Wrap with the framework's PolyMesh /
  * PolyScene equivalent to render.
  */
@@ -650,7 +1051,7 @@ declare function axesHelperPolygons(options?: AxesHelperOptions): Polygon[];
 /**
  * Axis-aligned box/cuboid geometry as six quad polygons.
  *
- * Returned polygons are in standard polycss world space:
+ * Returned polygons are in standard PolyCSS world space:
  * +X = right, +Y = front/forward, +Z = top/up.
  */
 
@@ -678,7 +1079,7 @@ declare function boxPolygons(options?: BoxPolygonsOptions): Polygon[];
  * drag handle for `<TransformControls>` — same primitive recipe as
  * `axesHelperPolygons`, plus an arrowhead.
  *
- * Returned polygons are in standard polycss world space and intended
+ * Returned polygons are in standard PolyCSS world space and intended
  * to be wrapped in the framework's PolyMesh equivalent for rendering.
  */
 
@@ -717,7 +1118,7 @@ declare function arrowPolygons(options: ArrowPolygonsOptions): Polygon[];
  * "rotation circle" and keeps the polygon count proportional to the
  * `segments` knob.
  *
- * Returned polygons are in standard polycss world space and intended
+ * Returned polygons are in standard PolyCSS world space and intended
  * to be wrapped in the framework's PolyMesh equivalent for rendering.
  */
 
@@ -775,7 +1176,7 @@ declare function ringQuadPolygons(options: RingQuadPolygonsOptions): Polygon[];
  * attached mesh along two axes simultaneously (XY, XZ, or YZ), instead of
  * the single-axis motion the arrow shafts provide.
  *
- * The polygon lives in standard polycss world space; wrap it in the
+ * The polygon lives in standard PolyCSS world space; wrap it in the
  * framework's PolyMesh equivalent for rendering.
  */
 
@@ -817,92 +1218,569 @@ interface OctahedronPolygonsOptions {
 declare function octahedronPolygons(options: OctahedronPolygonsOptions): Polygon[];
 
 /**
- * Unified parser return type. All polygon-emitting parsers (parseObj,
- * parseGltf, the loadMesh dispatcher) return this exact shape.
+ * Icosphere (subdivided icosahedron) geometry — approximates a sphere with
+ * triangular faces. Each subdivision step quadruples the face count:
+ *   subdivisions 0 → 20, 1 → 80, 2 → 320, 3 → 1280 (capped).
  *
- * The asymmetric helper `parseMtl` returns its own `MtlParseResult` (it
- * emits materials, not polygons) — see parseMtl.ts for the rationale.
+ * Vertex coordinates use PolyCSS world space: +X right, +Y forward, +Z up.
+ * The sphere is centered at the origin; all vertices sit at distance `radius`.
+ * Faces wind CCW from the outside (outward normal = away from origin).
+ */
+
+interface SpherePolygonsOptions {
+    /** Radius of the sphere. Default 50. */
+    radius?: number;
+    /** Subdivision level (0 = bare icosahedron, 20 triangles; each +1 quadruples count). Default 1 → 80 triangles. Cap at 3 (1280 triangles). */
+    subdivisions?: number;
+    /** Fill color applied to all faces. */
+    color?: string;
+}
+declare function spherePolygons(options?: SpherePolygonsOptions): Polygon[];
+
+/**
+ * Regular tetrahedron geometry — four equilateral triangular faces.
  *
- * Lifecycle contract: callers MUST call `dispose()` when the result is no
- * longer needed. Idempotent — safe to call on unmount even if `objectUrls`
- * is empty (e.g. `parseObj`, where it's a no-op).
+ * Vertices are placed so the tetrahedron is centered at the origin.
+ * Faces wind CCW from the outside.
+ *
+ * PolyCSS world space: +X right, +Y forward, +Z up.
  */
 
-interface PolyVoxelCell {
-    x: number;
-    y: number;
-    z: number;
-    color: string;
+interface TetrahedronPolygonsOptions {
+    /** Circumradius: distance from center to each vertex. Default 100. */
+    size?: number;
+    /** Fill color applied to all four faces. */
+    color?: string;
 }
-interface PolyVoxelSource {
-    kind: "magica-vox";
-    cells: PolyVoxelCell[];
-    rows: number;
-    cols: number;
-    depth: number;
-    scale: number;
-    gridShift: number;
-    sourceBytes: number;
+declare function tetrahedronPolygons(options?: TetrahedronPolygonsOptions): Polygon[];
+
+/**
+ * Regular icosahedron geometry — 20 equilateral triangular faces.
+ *
+ * Vertices are placed on a sphere of radius `size` centered at the origin.
+ * Faces wind CCW from the outside.
+ *
+ * PolyCSS world space: +X right, +Y forward, +Z up.
+ */
+
+interface IcosahedronPolygonsOptions {
+    /** Circumradius: distance from center to each vertex. Default 100. */
+    size?: number;
+    /** Fill color applied to all 20 faces. */
+    color?: string;
 }
-interface ParseAnimationClip {
-    /** Stable numeric index in the source file's animation array. */
-    index: number;
-    /** Human-readable clip name. Falls back to `animation_N` when omitted. */
-    name: string;
-    /** Clip duration in seconds, derived from its sampler input accessors. */
-    duration: number;
-    /** Number of glTF animation channels in the clip. */
-    channelCount: number;
+declare function icosahedronPolygons(options?: IcosahedronPolygonsOptions): Polygon[];
+
+/**
+ * Regular dodecahedron geometry — 12 regular pentagonal faces.
+ *
+ * Vertices are placed on a sphere of radius `size` centered at the origin.
+ * Each face is a pentagon (5 vertices) wound CCW from the outside.
+ *
+ * All 12 pentagonal faces of a regular dodecahedron are truly planar — each
+ * lies on a single tangent plane. No triangulation is needed. The renderer
+ * uses <i> (border-shape) on Chromium and <s> elsewhere for non-quad polygons.
+ *
+ * PolyCSS world space: +X right, +Y forward, +Z up.
+ */
+
+interface DodecahedronPolygonsOptions {
+    /** Circumradius: distance from center to each vertex. Default 100. */
+    size?: number;
+    /** Fill color applied to all 12 faces. */
+    color?: string;
 }
-interface ParseAnimationController {
-    /** Animation clips exposed by the parsed mesh. Empty when none are usable. */
-    clips: ParseAnimationClip[];
-    /**
-     * Sample a clip at `timeSeconds` and return a fresh polygon list.
-     * `clip` accepts either the clip index or its name. Time wraps by duration.
-     */
-    sample: (clip: number | string, timeSeconds: number) => Polygon[];
+declare function dodecahedronPolygons(options?: DodecahedronPolygonsOptions): Polygon[];
+
+/**
+ * Z-axis cylinder geometry with optional radius taper.
+ *
+ * Geometry:
+ *   - `radialSegments` side faces (quads for cylinders/frustums, triangles
+ *     when one radius collapses to a cone tip).
+ *   - `radialSegments` bottom-cap triangles (fan from center).
+ *   - `radialSegments` top-cap triangles (fan from center), omitted when
+ *     radiusTop ≈ 0 (i.e. cone tip).
+ *
+ * The cylinder sits centered at the origin, spanning Z = −height/2 to
+ * Z = +height/2. Side quads are axis-aligned in the cylinder's own local
+ * frame, which maximises the chance of hitting the <b> quad fast-path.
+ *
+ * PolyCSS world space: +X right, +Y forward, +Z up. The cylinder axis is
+ * the Z axis so a typical upright pillar stands without any extra rotation.
+ */
+
+interface CylinderPolygonsOptions {
+    /** Bottom-cap radius. Default 50. */
+    radius?: number;
+    /** Top-cap radius. Defaults to `radius` (straight cylinder).
+     *  Set to 0 (or near 0) for a cone. */
+    radiusTop?: number;
+    /** Height along the Z axis. Default 100. */
+    height?: number;
+    /** Number of radial segments. Default 12. */
+    radialSegments?: number;
+    /** Fill color applied to all polygons. */
+    color?: string;
 }
-interface ParseResult {
-    /** The mesh, as a flat polygon list. Already vertex-permuted to polycss space. */
-    polygons: Polygon[];
-    /** Optional raw voxel source for `.vox` fast paths; polygon fallback remains authoritative. */
-    voxelSource?: PolyVoxelSource;
-    /** Optional animation sampler for formats that carry timeline data. */
-    animation?: ParseAnimationController;
-    /**
-     * Blob/object URLs minted during parse (e.g. embedded GLB images). Pass-by-
-     * reference — the same array is exposed on the result for visibility, and
-     * `dispose()` revokes each one. Do NOT mutate this array externally.
-     */
-    objectUrls: string[];
-    /**
-     * Idempotent — revokes object URLs. Safe to call on unmount, safe to call
-     * twice. Parsers without minted URLs (parseObj, parseMtl) supply a no-op.
-     */
-    dispose: () => void;
-    /**
-     * Non-fatal warnings raised during parse. Empty for parsers that don't
-     * have a warning channel; populated when downstream `normalizePolygons`
-     * is invoked through the high-level pipeline.
-     */
-    warnings: string[];
-    /** Optional format-specific metadata. */
-    metadata?: {
-        /** Triangle count after fan-triangulation (parseObj) or post-triangulation (parseGltf). */
-        triangleCount?: number;
-        /** Mesh names from the file (for glTF, from doc.meshes[].name). */
-        meshes?: string[];
-        /** Material names (in first-seen order). */
-        materials?: string[];
-        /** Animation clips from the file, mirrored from `animation.clips`. */
-        animations?: ParseAnimationClip[];
-        /** Source file size in bytes (for diagnostics). */
-        sourceBytes?: number;
-        /** Voxel count for `.vox` sources. */
-        voxelCount?: number;
+declare function cylinderPolygons(options?: CylinderPolygonsOptions): Polygon[];
+
+/**
+ * Z-axis cone geometry — a cylinder with `radiusTop: 0`.
+ *
+ * This is a thin wrapper around `cylinderPolygons` with `radiusTop` forced
+ * to zero. The top cap is omitted (no area at the tip), and side faces are
+ * emitted as triangles.
+ *
+ * PolyCSS world space: +X right, +Y forward, +Z up. Cone axis is Z; the apex
+ * is at Z = +height/2 and the base at Z = -height/2.
+ */
+
+interface ConePolygonsOptions {
+    /** Base radius. Default 50. */
+    radius?: number;
+    /** Height along the Z axis. Default 100. */
+    height?: number;
+    /** Number of radial segments. Default 12. */
+    radialSegments?: number;
+    /** Fill color applied to all polygons. */
+    color?: string;
+}
+declare function conePolygons(options?: ConePolygonsOptions): Polygon[];
+
+/**
+ * Torus geometry — Z-axis ring plane.
+ *
+ * The torus is centered at the origin. The ring lies in the XY plane (the
+ * ground plane in PolyCSS world space, where Z is up). The donut hole points
+ * along the Z axis.
+ *
+ * Geometry: `radialSegments × tubularSegments` quads on the surface.
+ *
+ * DOM cost note: at default settings (12 × 16 = 192 quads) this is the
+ * heaviest of the built-in primitives. Reduce radialSegments / tubularSegments
+ * if render budget is tight.
+ *
+ * PolyCSS world space: +X right, +Y forward, +Z up.
+ */
+
+interface TorusPolygonsOptions {
+    /** Distance from center of tube to center of torus. Default 50. */
+    radius?: number;
+    /** Radius of the tube. Default 15. */
+    tube?: number;
+    /** Number of segments around the main ring. Default 12. */
+    radialSegments?: number;
+    /** Number of segments around the tube cross-section. Default 16. */
+    tubularSegments?: number;
+    /** Fill color applied to all polygons. */
+    color?: string;
+}
+declare function torusPolygons(options?: TorusPolygonsOptions): Polygon[];
+
+/** Tiny non-zero scale collapsed into the projection's Z column to keep
+ *  the matrix invertible. Chromium skips elements whose composed
+ *  transform is singular (m22 = 0 would make this a true projection
+ *  matrix, but Chromium would refuse to paint it), so we crush Z to 1%
+ *  of its input instead of exactly zero. The result still looks flat
+ *  to the eye — sub-pixel drift on any realistic scene size. */
+declare const BAKED_SHADOW_Z_SQUASH = 0.01;
+/** Minimum absolute value of the up-axis light component before the
+ *  projection blows up (we divide by it). Matches the --clz clamp in
+ *  the dynamic-mode applyDynamicLightVars helper so baked + dynamic
+ *  behave identically when the light is near-horizontal. */
+declare const BAKED_SHADOW_MIN_UP = 0.01;
+/**
+ * Build the CSS-space shadow projection matrix for a fixed light + ground
+ * plane. The 16-element output mirrors the retained `--shadow-proj` CSS
+ * custom property, but with literal numbers — ready to be formatted into a
+ * single `matrix3d(...)`.
+ *
+ * `lightDir` is the direction the light TRAVELS (e.g. `[0, 0, -1]` is
+ * straight down). PolyCSS world Z is up, and the world→CSS axis swap
+ * leaves Z alone — see styles.ts for the full convention.
+ *
+ * `groundCssZ` is the receiver plane in CSS-Z (= world-Z) coordinates,
+ * already in unit-less form (matrix3d entries must be dimensionless).
+ */
+declare function buildBakedShadowProjectionMatrix(lightDir: Vec3, groundCssZ: number): number[];
+/**
+ * Decides whether a polygon should cast a shadow given its outward
+ * normal and the light's travel direction.
+ *
+ * True for polygons whose normals point in the same direction as the
+ * light travels — i.e., on the far/dark side of the mesh from the
+ * light's POV. Those define the silhouette of the cast shadow.
+ *
+ * False for front-facing polygons whose projection would land inside
+ * the silhouette and only add overdraw. Dynamic mode hides these with
+ * a Lambert opacity gate; baked mode skips the DOM emission entirely.
+ */
+declare function isBakedShadowCaster(normal: Vec3, lightDir: Vec3): boolean;
+/**
+ * 2D convex hull (Andrew's monotone chain, O(n log n)). Returns the
+ * hull vertices in CCW order. Used to compute a receiver mesh's XY
+ * footprint when subtracting it from the global ground shadow.
+ */
+declare function convexHull2D(points: ReadonlyArray<readonly [number, number]>): Array<[number, number]>;
+/**
+ * Signed area of a 2D polygon (positive for CCW vertex order, negative
+ * for CW). Used by `ensureCcw2D` to normalize winding before concatenating
+ * polygons into a compound SVG path under `fill-rule="nonzero"`: mixed
+ * CCW/CW subpaths would cancel each other's winding in the overlap
+ * region and paint an unintended hole.
+ */
+declare function polygonSignedArea2D(vertices: ReadonlyArray<readonly [number, number]>): number;
+/**
+ * Returns the polygon's vertices in CCW order, reversing if necessary.
+ * Operates on a copy — input is left unmodified.
+ */
+declare function ensureCcw2D(vertices: ReadonlyArray<readonly [number, number]>): Array<[number, number]>;
+/**
+ * Projects a single CSS-3D vertex onto the shadow ground plane, returning
+ * the resulting 2D point in CSS coordinates. Mirrors the retained
+ * `--shadow-proj` matrix, but evaluated on the CPU for a fixed light + ground
+ * so many projected vertices can be merged into one SVG shadow path.
+ *
+ * `cssVertex` is a 3D point that has already been through the world→CSS
+ * axis swap and unit scale (so its components are dimensionless CSS-space
+ * coordinates). `lightDir` follows the same `--clx/--cly/--clz` convention
+ * as `buildBakedShadowProjectionMatrix`.
+ */
+declare function projectCssVertexToGround(cssVertex: Vec3, lightDir: Vec3, groundCssZ: number): [number, number];
+
+type Pt = readonly [number, number];
+/**
+ * Clips `subject` against the convex polygon `clip`. Both polygons are
+ * 2D, given in CCW vertex order. Returns the clipped polygon as a new
+ * array of points; an empty array means `subject` lies entirely outside.
+ */
+declare function clipPolygonToConvex2D(subject: ReadonlyArray<Pt>, clip: ReadonlyArray<Pt>): Array<[number, number]>;
+
+/**
+ * One coplanar group of receiver polygons projected into a 2D (u, v) basis on
+ * the shared plane. Sutherland-Hodgman clips caster-projected shadows to this
+ * group's outline; the per-member polygons let the renderer post-filter sub-
+ * shadows that fall outside the actual surface union (concave-bridging air
+ * gaps inside the convex hull).
+ */
+type ReceiverPlaneGroup = {
+    O: Vec3;
+    n: Vec3;
+    u: Vec3;
+    v: Vec3;
+    outlineUv: Array<[number, number]>;
+    memberPolysUv: Array<Array<[number, number]>>;
+    memberPolyIndices: number[];
+};
+/** World→CSS axis swap. World is `+X right, +Y forward, +Z up`; the renderer's
+ *  internal frame swaps X↔Y and scales by BASE_TILE (one world unit =
+ *  BASE_TILE CSS px). Same conversion every renderer applies at the boundary
+ *  for mesh positions, polygon vertices, and light directions. */
+declare function worldPositionToCss(p: Vec3): Vec3;
+/** World→CSS axis swap for directions (no scale; directions stay unit). The
+ *  polygon basis stores normals in the swapped CSS frame, so light vectors
+ *  must match before any dot product. */
+declare function worldDirectionToCss(d: Vec3): Vec3;
+/** Apply {@link worldDirectionToCss} to a directional-light object,
+ *  preserving the other fields. Used by atlas plan + buildBasisHints +
+ *  receiver-shadow callers so the light vector is in the same CSS-axis
+ *  frame as the polygon normals. Mirror of vanilla's
+ *  `worldDirectionalLightToCss` in `packages/polycss/src/api/scene/transforms.ts`. */
+declare function worldDirectionalLightToCss<T extends {
+    direction?: Vec3;
+} | undefined>(light: T): T;
+/** Normalize a mesh `scale` value into a Vec3 (undefined → [1,1,1], number →
+ *  uniform, Vec3 → as-is with `?? 1` per axis). */
+declare function meshScaleVec3(scale: number | Vec3 | undefined | null): Vec3;
+/**
+ * Build a `vert → CSS-frame world position` function for a mesh with the
+ * given scale + position. Pivots scale from the mesh ORIGIN. Rotation is
+ * intentionally not applied here — shadow geometry is computed once per
+ * mesh-transform change and already lives in world coords after this
+ * per-vertex transform; rotation lives on the wrapper.
+ */
+declare function worldCssForMesh(scale: number | Vec3 | undefined | null): (vert: Vec3, pos: Vec3) => Vec3;
+/**
+ * Minkowski expansion of a convex CCW polygon outward by `expand` units. Each
+ * vertex moves along the bisector of its two adjacent edge outward-
+ * perpendiculars, scaled so the edge offset distance equals `expand` (true
+ * Minkowski sum with a disk of radius `expand`, evaluated at the vertex). For
+ * convex inputs the result is a larger convex polygon with every edge offset
+ * outward by exactly `expand`.
+ */
+declare function expandConvexHullOutward(hullCcw: Array<[number, number]>, expand: number): Array<[number, number]>;
+/** Outward extension applied to each receiver face's convex outline (CSS px).
+ *  Adjacent receiver faces sharing an edge each expand by this amount, so the
+ *  two shadows overlap by ~2×EXPAND at the corner — eliminating the sub-pixel
+ *  light strip that used to appear where two wall faces meet. 0.5 CSS px stays
+ *  sub-pixel at typical zoom. */
+declare const RECEIVER_OUTLINE_EXPAND = 0.5;
+/** Plane-grouping tolerances. dot-product > 0.999 (~2.5° angular) catches
+ *  tessellation artifacts on flat surfaces without merging adjacent faces of
+ *  a low-poly curved mesh. Plane-offset tolerance is 0.5 CSS px — sub-pixel
+ *  coplanarity drift in glTF imports doesn't separate what should be a single
+ *  surface. */
+declare const RECEIVER_NORMAL_TOL = 0.001;
+declare const RECEIVER_OFFSET_TOL = 0.5;
+/**
+ * Groups a receiver's polygons into shadow-receiving surfaces. Two passes:
+ *
+ *   1. Plane bucket — group by matching normal + plane offset within tolerance
+ *      (catches tessellated flat regions).
+ *   2. Connected component — within each plane bucket, union-find on shared-
+ *      edge adjacency (faces sharing >= 2 vertices). Catches disjoint coplanar
+ *      walls where a convex hull of everything would bridge an air gap.
+ *
+ * Per group, output a convex hull in the group's (u, v) coords (Minkowski-
+ * expanded by `RECEIVER_OUTLINE_EXPAND`).
+ *
+ * `worldCss(vert, pos)` is the per-vertex world→CSS conversion (built via
+ * `worldCssForMesh` for the receiver's scale + position). `dedupDrop` is the
+ * set of receiver polygon indices to skip.
+ */
+declare function groupReceiverFaceGroups(polygons: readonly Polygon[], rpos: Vec3, worldCss: (vert: Vec3, pos: Vec3) => Vec3, dedupDrop: ReadonlySet<number>): ReceiverPlaneGroup[];
+
+/**
+ * Caster-mesh silhouette extraction for the receiver-shadow path.
+ *
+ * Given a closed (or near-closed) caster mesh and a directional light,
+ * computes the silhouette LOOPS — the closed cycles of edges where
+ * adjacent polygons disagree on whether they face the light. For a
+ * closed manifold convex mesh that's one loop; for concave or
+ * higher-genus meshes it may be several.
+ *
+ * The receiver-shadow algorithm normally projects every caster
+ * polygon's outline independently, which collapses to a silhouette at
+ * paint time via SVG fill-rule:nonzero. That makes the browser do the
+ * union work AFTER we've already paid the DOM cost for hundreds or
+ * thousands of triangle sub-paths. Extracting the silhouette here lets
+ * us emit ONE outline per mesh per receiver, dropping path-d size by
+ * 100× on heavy meshes like the teapot. See H9 in
+ * `bench/notes/SHADOW_PERF_LOG.md` and `bench/notes/H9_SILHOUETTE_DESIGN.md`.
+ *
+ * Pure data; no DOM access. Used by `computeReceiverShadowFaces` once
+ * H9 lands.
+ */
+
+/** Per-edge ownership record. `polyB === null` for boundary edges (open
+ *  meshes). Vertex coords are the canonical "from" vertices of the edge —
+ *  silhouette walking uses them to reconstruct loop geometry. */
+interface EdgeOwners {
+    polyA: number;
+    polyB: number | null;
+    vertA: Vec3;
+    vertB: Vec3;
+}
+/**
+ * Build a map from canonical edge key → owning polygon(s). Mirrors the
+ * vertex-quantization used by `buildSharedEdgeMap` so we agree on what
+ * "same edge" means.
+ *
+ * Edge keys are orientation-independent (vertex-pair sorted by string),
+ * so two polygons sharing an edge will report the same key. Polygons
+ * are listed in encounter order; for manifold meshes each edge has
+ * exactly 2 owners. Non-manifold edges (3+ owners) get truncated to
+ * `polyB = null` so the caller treats them as boundaries — safer than
+ * picking an arbitrary "second" polygon.
+ */
+declare function buildEdgeOwners(polygons: readonly Polygon[]): Map<string, EdgeOwners>;
+/** Classify each polygon as facing the light. Convention: `n · L < 0`
+ *  means the polygon's outward face is toward the light source (light
+ *  TRAVELS in direction L, polygons are CCW-from-outside). Matches the
+ *  light-backface cull's sign convention. */
+declare function classifyFacing(planeNormals: Array<Vec3 | null>, lightDir: Vec3): boolean[];
+/**
+ * Walk silhouette edges into closed loops. An edge is silhouette iff
+ * its two adjacent polygons disagree on `facing`. Boundary edges
+ * (polyB === null) are silhouette iff their owner is front-facing —
+ * the boundary is where the lit side ends.
+ *
+ * Returns one closed loop per connected silhouette cycle, each as a
+ * Vec3[] sequence (last vertex equals first vertex implicitly; not
+ * duplicated). For non-manifold or open meshes some edges may not form
+ * a clean cycle; those edges are dropped and the remaining cycles are
+ * returned best-effort.
+ */
+declare function extractSilhouetteLoops(edgeOwners: ReadonlyMap<string, EdgeOwners>, facing: boolean[]): Vec3[][];
+
+/**
+ * Per-receiver cached face geometry. One record per coplanar face group:
+ * plane (O, n, u, v), outline polygon (Sutherland-Hodgman clip), bbox in
+ * (u, v) for SVG sizing, and the pre-stringified matrix3d transform that
+ * places an SVG on that face plane.
+ *
+ * All of this is invariant under light/caster changes. Per light tick the
+ * caller just re-runs the per-tri SH and builds the path `d` — never
+ * recompute groups or basis. Cache invalidated when the receiver's polygon
+ * count or position changes.
+ */
+interface ReceiverFacePlane {
+    O: Vec3;
+    n: Vec3;
+    u: Vec3;
+    v: Vec3;
+    outlineUv: Array<[number, number]>;
+    memberPolysUv: Array<Array<[number, number]>>;
+    memberPolyIndices: number[];
+    minU: number;
+    minV: number;
+    width: number;
+    height: number;
+    matrixCss: string;
+    faceIndex: number;
+    /** World-frame lift (already × BASE_TILE) along +n. Re-applied per-frame
+     *  when building a tight shadow SVG matrix so the SVG hovers over the face. */
+    lift: number;
+}
+/**
+ * Per-caster cached per-polygon data: world-space vertices + 3D AABB
+ * corners + caster-polygon plane normal/offset. Invariant under light
+ * direction; depends only on the caster mesh's geometry and position.
+ */
+interface CasterPolyItem {
+    wv: Vec3[];
+    bboxCorners: Vec3[];
+    planeN: Vec3 | null;
+    planeOffset: number;
+    polygonIndex: number;
+}
+/** A caster mesh's prepared items paired with a stable identifier the caller
+ *  can use for per-path attribution. */
+interface ReceiverCasterInput<T = unknown> {
+    /** Caller-defined identifier (e.g. mesh ref, mesh shadow id). Echoed back
+     *  on each emitted path so the renderer can map a subpath to its source
+     *  caster mesh. */
+    id: T;
+    items: CasterPolyItem[];
+    /** Self-shadow edge adjacency. When this caster is the same mesh as the
+     *  receiver, the renderer pre-computes a map polygonIndex →
+     *  set-of-other-polygonIndex that share at least one edge (within
+     *  EDGE_MATCH_EPS). The shadow algorithm skips projecting `polygonIndex`
+     *  onto any receiver face whose member set intersects the shared-edge
+     *  set — those projections are sliver shadows along seams (smooth-shaded
+     *  GLB meshes, subdivided spheres) that the user never wants to see. */
+    selfShadowEdgeMap?: ReadonlyMap<number, ReadonlySet<number>>;
+    /** Per-mesh edge ownership map for silhouette extraction. Cached by the
+     *  caller (WeakMap<Mesh, …>) and shared across receivers within a frame.
+     *  When present AND the caster is NOT the receiver AND items.length ≥
+     *  SILHOUETTE_MIN_POLYS, the shadow algorithm projects per-mesh
+     *  silhouette loops instead of every front-facing triangle — collapses
+     *  the N-triangle path to 1 outline per caster per receiver. See H9 in
+     *  `bench/notes/SHADOW_PERF_LOG.md`. */
+    edgeOwners?: ReadonlyMap<string, EdgeOwners>;
+    /** Total polygon count on the source caster mesh (NOT the filtered
+     *  `items` count). Needed by silhouette extraction so the `facing`
+     *  array is sized correctly even when atlas-plan / dedup filters drop
+     *  some polygons from `items`. */
+    casterPolygonCount?: number;
+}
+/**
+ * Build a polygon-adjacency map: polygonIndex → set of polygonIndex that
+ * share at least one edge (vertex pair, orientation-independent). Used by
+ * the receiver-shadow algorithm to cull sliver shadows along mesh seams.
+ *
+ * Edge match tolerance is small enough to dedupe vertex coordinates that
+ * went through `optimizeMeshPolygons` snap-to-plane but not so loose it
+ * connects geometrically distinct polygons.
+ */
+declare function buildSharedEdgeMap(polygons: readonly Polygon[]): Map<number, Set<number>>;
+/** One contributing caster's shadow subpath on a single receiver face. */
+interface ReceiverShadowPath<T = unknown> {
+    /** Caster id echoed from the input. */
+    casterId: T;
+    /** Path data string: `M…L…Z` subpaths in face-local (u, v) coordinates
+     *  pre-translated so the SVG's `viewBox` is `0 0 width height`. */
+    d: string;
+    /** Source polygon indices on the caster mesh in subpath order (one per
+     *  M…L…Z block). Used for DevTools attribution. */
+    casterPolygonIndices: number[];
+}
+/** Per-receiver-face shadow spec. Renderer mounts one SVG per spec. */
+interface ReceiverShadowFaceSpec<T = unknown> {
+    /** Index into the prepared `ReceiverFacePlane[]` list. Stable across
+     *  frames; used as the `data-poly-shadow-receiver-face` attr. */
+    faceIndex: number;
+    /** Receiver polygon indices that make up this coplanar group. */
+    memberPolyIndices: number[];
+    /** matrix3d(...) transform that places the SVG on the face plane. */
+    matrixCss: string;
+    width: number;
+    height: number;
+    /** Fill (and stroke) color resolved per-face: textured receivers get the
+     *  user's `shadow.color`; solid receivers get their own ambient-only
+     *  shadePolygon for byte-exact Three.js parity. */
+    fill: string;
+    /** Per-face opacity (already accounts for textured-darken Lambert ratio
+     *  if applicable). */
+    opacity: number;
+    paths: Array<ReceiverShadowPath<T>>;
+}
+/**
+ * Build silhouette `edgeOwners` for a caster mesh in world-CSS frame.
+ * Used by the silhouette path inside `computeReceiverShadowFaces` (H9).
+ * Polygons are transformed through the same world-CSS pipeline as
+ * `prepareCasterPolyItems` (worldCssForMesh + optional rotation around
+ * the CSS-pivot) so the silhouette loop vertices land in the same world
+ * frame as the receiver face plane and the light direction.
+ *
+ * Caller caches by (mesh, polygon-list-identity + position + scale +
+ * rotation) — invalidates only when the caster's geometry or transform
+ * actually changes. Light direction is NOT a bust key (silhouette
+ * adjacency is per-mesh, facing is per-frame).
+ */
+declare function prepareCasterEdgeOwners(polygons: readonly Polygon[], position: Vec3, scale: number | Vec3 | undefined | null, rotation?: Vec3 | null): ReadonlyMap<string, EdgeOwners>;
+/**
+ * Build CasterPolyItem[] for a caster mesh. Pure: same inputs → same output.
+ * The caller memoizes by mesh ref + bust key. `includePolygonIndex(idx)`
+ * decides which polygons participate (e.g. dedup drop + atlas-plan filter
+ * in vanilla; just dedup drop in React/Vue without an atlas-plan concept).
+ */
+declare function prepareCasterPolyItems(polygons: readonly Polygon[], position: Vec3, scale: number | Vec3 | undefined | null, includePolygonIndex: (polygonIndex: number) => boolean, rotation?: Vec3 | null): CasterPolyItem[];
+/**
+ * Build ReceiverFacePlane[] for a receiver mesh. Pure: groups coplanar
+ * polygons, computes (u,v) basis + outline, applies interior occlusion cull
+ * (drops face planes hidden behind a parallel face plane within wall-
+ * thickness range).
+ *
+ * `shadowLift` is the world-unit lift applied along each face normal so the
+ * shadow SVG composites above the surface without z-fighting (matches the
+ * ground-shadow `shadow.lift` option).
+ */
+declare function prepareReceiverFacePlanes(polygons: readonly Polygon[], position: Vec3, scale: number | Vec3 | undefined | null, dedupDrop: ReadonlySet<number>, shadowLift: number, rotation?: Vec3 | null): ReceiverFacePlane[];
+/** Input for `computeReceiverShadowFaces`. */
+interface ComputeReceiverShadowFacesInput<T = unknown> {
+    /** Precomputed face planes from `prepareReceiverFacePlanes`. */
+    receiverPlanes: ReceiverFacePlane[];
+    /** Receiver's polygon list, used to look up per-face fill color. */
+    receiverPolygons: readonly Polygon[];
+    /** Whether the receiver mesh has any textured polygons. Drives the
+     *  textured-darken opacity calc vs solid-replace fill color. */
+    receiverHasTexture: boolean;
+    /** Per-caster items + caller id, in caller-defined order. */
+    casters: ReceiverCasterInput<T>[];
+    /** Directional light vector in CSS frame. */
+    lightDir: Vec3;
+    /** Camera cull rotation (rotX/rotY + receiver mesh rotation) so back-
+     *  facing receiver faces can be skipped. */
+    cameraRot: CameraCullRotation;
+    /** Ambient light (used for solid-receiver shadow tint via shadePolygon). */
+    ambientLight?: PolyAmbientLight;
+    /** Directional light (used for textured-darken opacity calc). */
+    directionalLight?: PolyDirectionalLight;
+    /** Scene shadow options. */
+    shadow?: {
+        color?: string;
+        opacity?: number;
+        maxExtend?: number;
     };
 }
+/**
+ * The pure per-frame algorithm. Returns one ReceiverShadowFaceSpec for each
+ * visible receiver face that catches at least one caster's shadow. Skips
+ * back-facing faces. Caller mounts SVGs per spec.
+ */
+declare function computeReceiverShadowFaces<T = unknown>(input: ComputeReceiverShadowFacesInput<T>): ReceiverShadowFaceSpec<T>[];
 
 /**
  * PolyAnimationMixer — three.js-shaped animation API for polycss.
@@ -1008,6 +1886,12 @@ interface PolyAnimationMixer {
 }
 declare function createPolyAnimationMixer(root: PolyAnimationTarget, controller: ParseAnimationController): PolyAnimationMixer;
 
+interface OptimizeAnimatedMeshPolygonsOptions {
+    /** Public quality/resolution intent. Defaults to "lossy". */
+    meshResolution?: MeshResolution;
+}
+declare function optimizeAnimatedMeshPolygons(result: ParseResult, options?: OptimizeAnimatedMeshPolygonsOptions): ParseResult;
+
 interface ObjParseOptions {
     /**
      * Largest mesh extent (in scene-space units). The mesh is uniformly
@@ -1015,10 +1899,20 @@ interface ObjParseOptions {
      */
     targetSize?: number;
     /**
-     * Padding added to the bbox of every emitted polygon so they don't land
-     * at coordinate "0". Default: 1.
+     * Where to place the mesh-local origin relative to the parsed geometry.
+     *
+     * - `"min"` (default): bbox-min sits at local (0,0,0); geometry lives in
+     *   the +X+Y+Z quadrant. This is PolyCSS's historical behavior.
+     * - `true` (or `"center"`): bbox-center sits at local (0,0,0); geometry
+     *   is centered around the origin. Pair with `scene.add(parse, {position,
+     *   rotation:[...]})` to get three.js-style rotate-in-place around the
+     *   centroid.
+     *
+     * Three.js's `GLTFLoader`/`OBJLoader` don't reposition vertices at all;
+     * for byte-parity loading set this to a separate explicit `false` once
+     * the no-offset option lands.
      */
-    gridShift?: number;
+    center?: boolean | "min" | "center";
     /**
      * Color used for faces that have no `usemtl` in scope, or whose material
      * name doesn't resolve via `materialColors`. Default: "#888888".
@@ -1086,8 +1980,6 @@ declare function parseMtl(text: string): MtlParseResult;
 interface GltfParseOptions {
     /** Largest mesh extent (units). Mesh is uniformly scaled to fit. Default 60. */
     targetSize?: number;
-    /** Padding offset (avoids coordinate "0"). Default 1. */
-    gridShift?: number;
     /** Color used when a primitive has no material or no baseColorFactor. */
     defaultColor?: string;
     /**
@@ -1095,15 +1987,32 @@ interface GltfParseOptions {
      * material's `pbrMetallicRoughness.baseColorFactor` if not in this map.
      */
     materialColors?: Record<string, string>;
+    /**
+     * Override map: glTF material name → texture image URL. Takes priority over
+     * `pbrMetallicRoughness.baseColorTexture`; useful for GLB/GLTF exports that
+     * preserved UVs but dropped external image references.
+     */
+    materialTextures?: Record<string, string>;
     /**
      * Which axis is "up" in the source mesh.
      *  - "y" (default, glTF spec): cyclic permutation (x,y,z) → (z,x,y) so
-     *    +Y ends up on polycss's +Z (elevation).
+     *    +Y ends up on PolyCSS's +Z (elevation).
      *  - "z" (Blender-style, FBX2glTF often emits this): identity, no swap.
      * Pick "z" if the model lands on its side / lies down instead of
      * standing.
      */
     upAxis?: "y" | "z";
+    /**
+     * Where to place the mesh-local origin relative to the parsed geometry.
+     *
+     * - `"min"` (default): bbox-min sits at local (0,0,0); geometry lives in
+     *   the +X+Y+Z quadrant. This is PolyCSS's historical behavior.
+     * - `true` (or `"center"`): bbox-center sits at local (0,0,0); geometry
+     *   is centered around the origin. Pair with `scene.add(parse, {position,
+     *   rotation:[...]})` to get three.js-style rotate-in-place around the
+     *   centroid.
+     */
+    center?: boolean | "min" | "center";
     /**
      * For .gltf (non-binary) — resolve a glTF buffer URI to its bytes. The
      * built-in parser handles GLB binary chunks natively; .gltf files with
@@ -1115,7 +2024,7 @@ interface GltfParseOptions {
      * (`doc.images[i].uri = "Textures/foo.png"`) against the GLB/glTF's
      * location. Without this, relative URIs would resolve against the page,
      * which 404s. Pass the same URL you fetched the file from.
-     */
+    */
     baseUrl?: string;
 }
 declare function parseGltf(input: ArrayBuffer | Uint8Array, options?: GltfParseOptions): ParseResult;
@@ -1142,58 +2051,36 @@ interface VoxParseOptions {
      */
     targetSize?: number;
     /**
-     * Per-coordinate offset added after scaling. Keeps coordinates away from
-     * zero (matching OBJ/glTF parsers). Default: 0 — vox already starts at
-     * non-negative integers so zero makes sensible default.
+     * Optional lossy palette simplification. When > 0, opaque, hue-compatible
+     * palette colors within this RGB distance are folded into the most-used
+     * nearby color before greedy voxel meshing. Default: disabled.
      */
-    gridShift?: number;
+    paletteMergeDistance?: number;
+    /**
+     * Optional lossy local cleanup. When > 0, small face-plane color islands
+     * and thin streaks are recolored to a neighboring dominant hue-compatible
+     * color within this RGB distance before greedy voxel meshing. Default:
+     * disabled.
+     */
+    colorRegionMergeDistance?: number;
 }
 declare function parseVox(buffer: ArrayBuffer, options?: VoxParseOptions): ParseResult;
 
-type PlaneAxis = "x" | "y" | "z";
-type PolyVoxelFace = "t" | "b" | "bl" | "br" | "fr" | "fl";
-interface PolyVoxelWallsMask {
-    t: boolean;
-    b: boolean;
-    bl: boolean;
-    br: boolean;
-    fl: boolean;
-    fr: boolean;
-}
-interface FaceKey {
-    axis: PlaneAxis;
-    plane: number;
-    face: PolyVoxelFace;
-}
-interface FaceBuffer {
-    width: number;
-    height: number;
-    minRow: number;
-    minCol: number;
-    ids: Uint32Array;
-    mask: Uint8Array;
-    filledCount: number;
-    palette: string[];
-}
-interface FaceData {
-    key: FaceKey;
-    buffer: FaceBuffer;
-}
-type Brush = {
-    r0: number;
-    c0: number;
-    r1: number;
-    c1: number;
-    baseColor: string;
-};
-type SlicePlan = {
-    key: FaceKey;
-    buffer: FaceBuffer;
-    brushes: Brush[];
-};
-declare const NEXT_LAYER_STEP: Record<PolyVoxelFace, number>;
-declare const buildSlicePlan: (faceData: FaceData, nextLayer: FaceBuffer | null) => SlicePlan;
-declare const buildFaceDataFromVoxelSource: (source: PolyVoxelSource) => FaceData[];
+interface StlParseOptions {
+    /** Largest mesh extent (units). Mesh is uniformly scaled to fit. Default: 60. */
+    targetSize?: number;
+    /** Padding offset added after scaling. Default: 1. */
+    gridShift?: number;
+    /** Solid color assigned to every STL triangle. Default: "#888888". */
+    defaultColor?: string;
+    /**
+     * Which axis is "up" in the source mesh.
+     *  - "z" (default): identity axes, matching common CAD/3D-print STL exports.
+     *  - "y": cyclic permutation (x,y,z) → (z,x,y), matching OBJ/glTF's +Y-up path.
+     */
+    upAxis?: "z" | "y";
+}
+declare function parseStl(source: ArrayBuffer | Uint8Array | string, options?: StlParseOptions): ParseResult;
 
 /**
  * loadMesh — high-level fetch+parse dispatcher. Picks the parser by file
@@ -1205,11 +2092,12 @@ declare const buildFaceDataFromVoxelSource: (source: PolyVoxelSource) => FaceDat
  *   - `.glb`  → ArrayBuffer fetch + `parseGltf`
  *   - `.gltf` → ArrayBuffer fetch + `parseGltf` (caller may pass `baseUrl`)
  *   - `.vox`  → ArrayBuffer fetch + `parseVox`
+ *   - `.stl`  → ArrayBuffer fetch + `parseStl`
  *
  * `.mtl` is rejected — it's a material file, not a mesh. Use `parseMtl`
  * directly if you want to read materials.
  *
- * Other extensions throw. Future formats (STL, PLY) plug in here.
+ * Other extensions throw. Future formats (PLY, 3MF) plug in here.
  */
 
 interface LoadMeshOptions {
@@ -1233,6 +2121,8 @@ interface LoadMeshOptions {
     gltfOptions?: GltfParseOptions;
     /** Forwarded to `parseVox`. */
     voxOptions?: VoxParseOptions;
+    /** Forwarded to `parseStl`. */
+    stlOptions?: StlParseOptions;
     /**
      * Converts texture-backed faces whose UV samples are a uniform color into
      * solid-color polygons before culling/merging. This avoids atlas sprites for
@@ -1241,10 +2131,578 @@ interface LoadMeshOptions {
     solidTextureSamples?: boolean | SolidTextureSampleOptions;
     /**
      * Mesh optimization intent. Defaults to "lossy"; set "lossless" to keep
-     * exact planar candidates only.
+     * exact planar candidates only. STL imports use the conservative lossless
+     * optimizer path in both modes.
      */
     meshResolution?: MeshResolution;
 }
 declare function loadMesh(url: string, options?: LoadMeshOptions): Promise<ParseResult>;
 
-export { type ApproximateMergeOptions, type ArrowPolygonsOptions, type AutoRotateConfig, type AutoRotateOption, type AxesHelperOptions, BASE_TILE, type BoxFace, type BoxFaceOptions, type BoxPolygonsOptions, CAMERA_BACKFACE_CULL_EPS, type CameraCullNormalGroup, type CameraCullRotation, type CameraHandle, type CameraState, type CameraStyleInput, type CoverPlanarPolygonsOptions, type CullInteriorOptions, DEFAULT_CAMERA_STATE, DEFAULT_PROJECTION, type DedupeOverlappingPolygonsOptions, type GltfParseOptions, type LoadMeshOptions, type LoopMode, LoopOnce, LoopPingPong, LoopRepeat, type MeshResolution, type MtlParseResult, type NormalizeResult, type ObjParseOptions, type OctahedronPolygonsOptions, type OptimizeMeshPolygonsOptions, NEXT_LAYER_STEP as POLY_VOXEL_NEXT_LAYER_STEP, type ParseAnimationClip, type ParseAnimationController, type ParseResult, type ParsedColor, type PlanePolygonsOptions, type PolyAmbientLight, type PolyAnimationAction, type ParseAnimationClip as PolyAnimationClip, type PolyAnimationMixer, type PolyAnimationTarget, type PolyDirectionalLight, type PolyMaterial, type PolyTextureLightingMode, type Brush as PolyVoxelBrush, type PolyVoxelCell, type PolyVoxelFace, type FaceBuffer as PolyVoxelFaceBuffer, type FaceData as PolyVoxelFaceData, type FaceKey as PolyVoxelFaceKey, type PlaneAxis as PolyVoxelPlaneAxis, type SlicePlan as PolyVoxelSlicePlan, type PolyVoxelSource, type PolyVoxelWallsMask, type Polygon, type PolygonFace, QUAT_IDENTITY, type Quat, type RingPolygonsOptions, type RingQuadPolygonsOptions, type SceneBbox, type SceneContext, type SceneContextBuildArgs, type SceneContextBuildResult, type SolidTextureSampleOptions, type TexturePaintMetrics, type TexturePaintMetricsOptions, type TextureTriangle, VOXEL_CAMERA_CULL_AXIS_EPS, VOXEL_CAMERA_CULL_NORMAL_LIMIT, type Vec2, type Vec3, type VoxParseOptions, arrowPolygons, axesHelperPolygons, bakeSolidTextureSampledPolygons, bakeSolidTextureSamples, boxPolygons, buildFaceDataFromVoxelSource as buildPolyVoxelFaceData, buildSlicePlan as buildPolyVoxelSlicePlan, buildSceneContext, cameraCullNormalGroups, cameraCullNormalGroupsFromPolygons, cameraCullNormalKey, cameraCullVisibleSignature, cameraFacingDepth, clampChannel, computeSceneBbox, computeShapeLighting, computeTexturePaintMetrics, coverPlanarPolygons, createIsometricCamera, createPolyAnimationMixer, cullInteriorPolygons, dedupeOverlappingPolygons, eulerXYZFromQuat, findOverlappingPolygonDuplicates, formatColor, inverseRotateVec3, isAxisAlignedSurfaceNormal, isVoxelCameraCullableNormalGroups, loadMesh, mergePolygons, normalFacesCamera, normalizeInvertMultiplier, normalizePolygons, octahedronPolygons, optimizeMeshPolygons, parseColor, parseGltf, parseHexColor, parseMtl, parseObj, parsePureColor, parseRgbColor, parseVox, planePolygons, polygonCssSurfaceNormal, polygonFaces, polygonFacesCamera, quatFromAxisAngle, quatFromEulerXYZ, quatMultiply, ringPolygons, ringQuadPolygons, rotateVec3, shadeColor };
+declare const DEFAULT_TILE = 50;
+declare const DEFAULT_LIGHT_DIR: Vec3;
+declare const DEFAULT_LIGHT_COLOR = "#ffffff";
+declare const DEFAULT_LIGHT_INTENSITY = 1;
+declare const DEFAULT_AMBIENT_COLOR = "#ffffff";
+declare const DEFAULT_AMBIENT_INTENSITY = 0.4;
+declare const ATLAS_MAX_SIZE = 4096;
+declare const ATLAS_PADDING = 1;
+declare const MIN_ATLAS_SCALE = 0.1;
+declare const MAX_ATLAS_SCALE = 1;
+declare const AUTO_ATLAS_LOW_AREA: number;
+declare const AUTO_ATLAS_MEDIUM_AREA: number;
+declare const AUTO_ATLAS_MAX_BITMAP_SIDE = 2048;
+declare const AUTO_ATLAS_MAX_DECODED_BYTES_MOBILE: number;
+declare const AUTO_ATLAS_MAX_DECODED_BYTES_DESKTOP: number;
+declare const AUTO_ATLAS_SCALE_GUARD = 0.995;
+declare const COLOR_PARSE_CACHE_MAX = 512;
+declare const ASYNC_RENDER_BUDGET_MS = 12;
+declare const RECT_EPS = 0.001;
+declare const BASIS_EPS = 1e-9;
+declare const SURFACE_NORMAL_EPS = 0.0001;
+declare const SURFACE_DISTANCE_EPS = 0.1;
+declare const SEAM_LIGHT_EPS = 0.01;
+declare const TEXTURE_TRIANGLE_BLEED = 0.75;
+declare const TEXTURE_EDGE_REPAIR_ALPHA_MIN = 1;
+declare const TEXTURE_EDGE_REPAIR_SOURCE_ALPHA_MIN = 250;
+declare const TEXTURE_EDGE_REPAIR_RADIUS = 1.5;
+declare const SOLID_TRIANGLE_BLEED = 0.75;
+declare const DEFAULT_MATRIX_DECIMALS = 3;
+declare const DEFAULT_BORDER_SHAPE_DECIMALS = 2;
+declare const DEFAULT_ATLAS_CSS_DECIMALS = 4;
+declare const DECIMAL_SCALES: number[];
+declare const SOLID_QUAD_CANONICAL_SIZE = 64;
+declare const SOLID_TRIANGLE_CANONICAL_SIZE = 32;
+declare const SOLID_TRIANGLE_LARGE_BORDER_CANONICAL_SIZE = 96;
+declare const ATLAS_CANONICAL_SIZE_EXPLICIT = 64;
+declare const ATLAS_CANONICAL_SIZE_AUTO_DESKTOP = 128;
+declare const BORDER_SHAPE_CENTER_PERCENT = 50;
+declare const BORDER_SHAPE_POINT_EPS = 1e-7;
+declare const BORDER_SHAPE_CANONICAL_SIZE = 16;
+declare const BORDER_SHAPE_BLEED = 0.9;
+declare const CORNER_SHAPE_POINT_EPS = 0.75;
+declare const CORNER_SHAPE_DUPLICATE_EPS = 0.2;
+declare const PROJECTIVE_QUAD_DENOM_EPS = 0.05;
+declare const PROJECTIVE_QUAD_MAX_WEIGHT_RATIO = 256;
+declare const PROJECTIVE_QUAD_BLEED = 0.6;
+declare const DEFAULT_SEAM_BLEED = 1.5;
+/** Clamp the `seamBleed` ratio. `undefined` → 1 (full default), 0 → no
+ *  bleed, values outside [0,1] are clamped. Single source of truth for
+ *  how the public ratio maps to per-strategy bleed multipliers. */
+declare function resolveBleedRatio(seamBleed: number | "auto" | undefined): number;
+
+interface RGB {
+    r: number;
+    g: number;
+    b: number;
+}
+interface RGBFactors {
+    r: number;
+    g: number;
+    b: number;
+}
+interface UvAffine {
+    a: number;
+    b: number;
+    c: number;
+    d: number;
+    e: number;
+    f: number;
+}
+interface UvSampleRect {
+    minU: number;
+    minV: number;
+    maxU: number;
+    maxV: number;
+}
+interface TextureTrianglePlan {
+    screenPts: number[];
+    uvAffine: UvAffine | null;
+    uvSampleRect: UvSampleRect | null;
+}
+interface TextureAtlasPlan {
+    index: number;
+    polygon: Polygon;
+    texture?: string;
+    tileSize: number;
+    layerElevation: number;
+    matrix: string;
+    canonicalMatrix: string;
+    atlasMatrix: string;
+    atlasCanonicalSize?: number;
+    projectiveMatrix: string | null;
+    canvasW: number;
+    canvasH: number;
+    screenPts: number[];
+    uvAffine: UvAffine | null;
+    uvSampleRect: UvSampleRect | null;
+    textureTriangles: TextureTrianglePlan[] | null;
+    textureEdgeRepairEdges: Set<number> | null;
+    textureEdgeRepair: boolean;
+    seamBleed?: number;
+    seamBleedEdges?: Set<number>;
+    seamBleedEdgeAmounts?: Map<number, number>;
+    seamBleedInsets?: SeamBleedInsets;
+    /** Resolved per-strategy bleed multiplier (0..1, default 1). Populated
+     *  at plan construction from `options.seamBleed` via `resolveBleedRatio`.
+     *  Downstream emitters (borderShapeGeometryForPlan, projective-quad
+     *  rasteriser, etc.) read this and multiply their hardcoded per-strategy
+     *  bleed constants by it. Single knob for "scale down all my bleeds". */
+    bleedRatio?: number;
+    /** World-space surface normal — stable across light changes, used by dynamic mode. */
+    normal: Vec3;
+    textureTint: RGBFactors;
+    shadedColor: string;
+}
+interface BorderShapeBounds {
+    minX: number;
+    minY: number;
+    width: number;
+    height: number;
+}
+interface BorderShapeGeometry {
+    bounds: BorderShapeBounds;
+    points: Array<[number, number]>;
+}
+type CornerShapeCorner = "topLeft" | "topRight" | "bottomRight" | "bottomLeft";
+type CornerShapeSide = "left" | "right" | "top" | "bottom";
+interface CornerShapeRadius {
+    x: number;
+    y: number;
+}
+interface CornerShapeGeometry {
+    bounds: BorderShapeBounds;
+    radii: Partial<Record<CornerShapeCorner, CornerShapeRadius>>;
+}
+type TextureQuality = number | "auto";
+type PolySeamBleed = number | "auto";
+type PolySeamBleedEdgeValue = ReadonlySet<number> | ReadonlyMap<number, number>;
+type PolySeamBleedEdges = ReadonlyMap<number, PolySeamBleedEdgeValue> | readonly (PolySeamBleedEdgeValue | undefined)[];
+type PolyRenderStrategy = "b" | "i" | "u";
+type SolidTrianglePrimitive = "border" | "border-large" | "corner-bevel";
+interface PolyRenderStrategiesOption {
+    /** Strategies to skip; polygons that would normally use them fall through
+     *  the chain (b → i → s, u → i → s, i → s). `<s>` is the universal
+     *  fallback and cannot be disabled — textured polys have no other path. */
+    disable?: readonly PolyRenderStrategy[];
+}
+interface SeamBleedInsets {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+}
+interface PackedTextureAtlasEntry extends TextureAtlasPlan {
+    pageIndex: number;
+    x: number;
+    y: number;
+}
+interface PackedPage {
+    width: number;
+    height: number;
+    entries: PackedTextureAtlasEntry[];
+}
+interface PackingShelf {
+    x: number;
+    y: number;
+    height: number;
+}
+interface PackingPage extends PackedPage {
+    shelves: PackingShelf[];
+    sealed?: boolean;
+}
+interface PackedAtlas {
+    entries: Array<PackedTextureAtlasEntry | null>;
+    pages: PackedPage[];
+}
+interface SolidTriangleBasis {
+    a: number;
+    b: number;
+    c: number;
+}
+interface SolidTriangleColorPlan {
+    index: number;
+    polygon: Polygon;
+    colorComputed: boolean;
+    bakedColor?: string;
+    bakedRgb?: RGB;
+    bakedAlpha?: number;
+    dynamicVars?: string;
+}
+interface SolidTrianglePlan extends SolidTriangleColorPlan {
+    styleText: string;
+    transformText: string;
+    basis: SolidTriangleBasis;
+    primitive: SolidTrianglePrimitive;
+}
+interface SolidTriangleComputeOptions {
+    basis?: SolidTriangleBasis;
+    includeColor?: boolean;
+    matrixDecimals?: number;
+    color?: string;
+    primitive?: SolidTrianglePrimitive;
+    /** Pre-resolved primitive used when `primitive` is not set — replaces the
+     *  browser-global resolution that formerly happened inside the function. */
+    resolvedPrimitive?: SolidTrianglePrimitive | null;
+}
+interface StableTriangleColorState {
+    updatesDisabled: boolean;
+    freezeFrames: number;
+    colorFrame: number;
+    maxStep: number;
+}
+interface SolidTriangleFrame {
+    polygonCount: number;
+    vertices: ArrayLike<number>;
+    colors?: readonly (string | undefined)[];
+}
+interface SolidPaintDefaults {
+    paintColor?: string;
+    dynamicColor?: {
+        r: number;
+        g: number;
+        b: number;
+    };
+    dynamicColorKey?: string;
+}
+interface TextureAtlasPage {
+    width: number;
+    height: number;
+    url: string | null;
+}
+interface RectBrush {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+interface LocalBasis {
+    xAxis: Vec3;
+    yAxis: Vec3;
+    local2D: Vec2[];
+    shiftX: number;
+    shiftY: number;
+    canvasW: number;
+    canvasH: number;
+    pixelArea: number;
+    rawArea: number;
+}
+interface BasisOptions {
+    optimize: boolean;
+    fixedXAxis?: Vec3;
+    boundsOrigin?: Vec3;
+    snapBounds?: boolean;
+    seamEdges?: Set<number>;
+}
+interface BasisHint {
+    xAxis?: Vec3;
+    boundsOrigin?: Vec3;
+    seamEdges: Set<number>;
+    textureEdgeRepairEdges?: Set<number>;
+}
+interface PolygonBasisInfo {
+    pts: Vec3[];
+    normal: Vec3;
+    planeD: number;
+    optimizable: boolean;
+}
+interface ProjectiveQuadGuardSettings {
+    denomEps: number;
+    maxWeightRatio: number;
+    bleed: number;
+    disableGuards: boolean;
+}
+interface ProjectiveQuadGuardOverrides {
+    denomEps?: number;
+    maxWeightRatio?: number;
+    bleed?: number;
+    disableGuards?: boolean;
+}
+interface ProjectiveQuadGuardGlobal {
+    __polycssProjectiveQuadGuards?: ProjectiveQuadGuardOverrides;
+}
+interface ProjectiveQuadCoefficients {
+    g: number;
+    h: number;
+    w1: number;
+    w3: number;
+}
+interface StablePlanBasis {
+    normal: Vec3;
+    xAxis: Vec3;
+    yAxis: Vec3;
+    tx: number;
+    ty: number;
+    tz: number;
+}
+/** Options for solidTrianglePlan computation — the pure-math subset of
+ *  RenderTextureAtlasOptions with no DOM reference. */
+interface SolidTrianglePlanOptions {
+    tileSize?: number;
+    layerElevation?: number;
+    directionalLight?: PolyDirectionalLight;
+    ambientLight?: PolyAmbientLight;
+    textureLighting?: PolyTextureLightingMode;
+    solidPaintDefaults?: SolidPaintDefaults;
+    strategies?: PolyRenderStrategiesOption;
+    seamBleed?: PolySeamBleed;
+    seamEdges?: Set<number>;
+    /** Per-strategy bleed multiplier (0..1, default 1). Scales the
+     *  hardcoded SOLID_TRIANGLE_BLEED used as the seamBleed fallback when
+     *  no shared-edge bleed is present. Populated upstream from
+     *  `resolveBleedRatio(publicOptions.seamBleed)`. */
+    bleedRatio?: number;
+    /**
+     * Indices (into the polygon array being planned) of polygons that the
+     * directional light cannot physically reach because another polygon of
+     * the same mesh is between them and the light source. Per-polygon
+     * directScale is forced to 0 for indices in this set, so they receive
+     * ambient lighting only — matching what a shadow-map-equivalent pass
+     * would produce.
+     */
+    lightOccludedPolyIndices?: ReadonlySet<number>;
+}
+/** Internal solid-triangle plan options (extends SolidTrianglePlanOptions). */
+interface InternalSolidTrianglePlanOptions extends SolidTrianglePlanOptions {
+    optimizeStableTriangleStyle?: boolean;
+    stableTriangleColorSteps?: number;
+    stableTriangleMatrixDecimals?: number;
+}
+/** Options accepted by the public {@link computeTextureAtlasPlanPublic} wrapper. */
+interface ComputeTextureAtlasPlanOptions {
+    tileSize?: number;
+    layerElevation?: number;
+    directionalLight?: PolyDirectionalLight;
+    ambientLight?: PolyAmbientLight;
+    /** Shared-edge set returned by {@link buildTextureEdgeRepairSets}. */
+    textureEdgeRepairEdges?: Set<number>;
+    seamBleed?: PolySeamBleed;
+    seamEdges?: Set<number>;
+    /** Indices of polygons that the directional light cannot reach because
+     *  another polygon of the same mesh occludes them (precomputed via
+     *  {@link import("../cull/lightVisibility").computeLightVisibility}). When
+     *  `index ∈ lightOccludedPolyIndices`, the polygon's direct lighting term
+     *  is forced to zero and only ambient remains. Matches the vanilla
+     *  renderer's self-shadow path. */
+    lightOccludedPolyIndices?: ReadonlySet<number>;
+}
+
+declare function roundDecimal(value: number, decimals: number): string;
+declare function formatCssLength(value: number, decimals?: number): string;
+declare function formatMatrix3dValues(values: readonly number[], decimals?: number): string;
+declare function formatAffineMatrix3dColumns(xCol: Vec3, yCol: Vec3, zCol: Vec3, txCol: Vec3, decimals?: number): string;
+declare function formatAffineMatrix3dScalars(x0: number, x1: number, x2: number, y0: number, y1: number, y2: number, z0: number, z1: number, z2: number, tx0: number, tx1: number, tx2: number, decimals?: number): string;
+declare function formatAffineMatrix3dTransformScalars(x0: number, x1: number, x2: number, y0: number, y1: number, y2: number, z0: number, z1: number, z2: number, tx0: number, tx1: number, tx2: number, decimals?: number): string;
+declare function formatScaledMatrixFromPlan(entry: TextureAtlasPlan, scaleX: number, scaleY: number, offsetX?: number, offsetY?: number): string;
+declare function formatBorderShapeMatrix(entry: TextureAtlasPlan, bounds: BorderShapeBounds): string;
+declare function formatSolidQuadMatrix(entry: TextureAtlasPlan): string;
+declare function formatAtlasMatrix(entry: TextureAtlasPlan, atlasCanonicalSize: number): string;
+declare function formatPercent(value: number, decimals?: number): string;
+/** Format a raw comma-separated matrix3d value string with rounded decimals. */
+declare function formatMatrix3d(matrix: string, decimals?: number): string;
+/** Format a pixel CSS length value. */
+declare function formatCssLengthPx(value: number, decimals?: number): string;
+/**
+ * Produce the CSS matrix3d transform for a solid-quad (`<b>`) leaf, including
+ * the canonical primitive scale.
+ */
+declare function formatSolidQuadEntryMatrix(entry: TextureAtlasPlan): string;
+
+declare function buildTextureEdgeRepairSets(polygons: Polygon[]): Array<Set<number> | undefined>;
+declare function resolveSeamBleed(value: unknown, fallback: number): number;
+declare function normalizedSeamBleed(value: unknown): number | undefined;
+declare function safePlanSeamBleedAmount(screenPts: number[], edgeIndex: number, requested: number): number;
+declare function computePlanSeamBleedEdgeAmounts(screenPts: number[], seamEdges: ReadonlySet<number> | undefined, seamBleed: number | undefined): Map<number, number> | undefined;
+declare function seamBleedAmountArray(vertexCount: number, edgeAmounts: ReadonlyMap<number, number> | undefined): number[] | null;
+declare function computeSeamBleedInsets(screenPts: number[], edgeAmounts: ReadonlyMap<number, number> | undefined): SeamBleedInsets | undefined;
+interface SeamBleedDetectionOptions {
+    tileSize?: number;
+    layerElevation?: number;
+    directionalLight?: unknown;
+    ambientLight?: unknown;
+}
+declare function buildSeamBleedPolygonSet(polygons: Polygon[], options?: SeamBleedDetectionOptions): Set<number>;
+declare function buildSeamBleedPolygonEdges(polygons: Polygon[], options?: SeamBleedDetectionOptions): Map<number, Set<number>>;
+
+type PureColorParseResult = ReturnType<typeof parsePureColor>;
+declare function cachedParsePureColor(input: string): PureColorParseResult;
+declare function parseHex(hex: string): RGB;
+declare function rgbKey({ r, g, b }: RGB): string;
+/** Returns the parsed alpha for a color string (1.0 default). */
+declare function parseAlpha(input: string): number;
+declare function rgbToHex({ r, g, b }: RGB): string;
+/**
+ * Tint factors for a textured polygon, in LINEAR light space.
+ *
+ * Returns the per-channel multiplier that the rasterizer should apply to the
+ * texture pixels' LINEAR values — matching Three.js MeshLambertMaterial:
+ *   lit_linear = albedo_linear × tint
+ *   tint = (lightColor × lambert × I + ambientColor × I_amb) / π
+ *
+ * Light + ambient colors are interpreted as sRGB and converted to linear.
+ * The rasterizer is responsible for decoding the texture sample from sRGB
+ * to linear before multiplying by these factors, then re-encoding for paint
+ * (see applyTextureTint in the renderer). `directScale` is already
+ * `intensity × max(n·L, 0)` (computed by the caller).
+ */
+declare function textureTintFactors(directScale: number, lightColor: string, ambientColor: string, ambientIntensity: number): RGBFactors;
+declare function tintToCss({ r, g, b }: RGBFactors): string;
+declare function shadePolygon(baseColor: string, directScale: number, lightColor: string, ambientColor: string, ambientIntensity: number): string;
+declare function quantizeCssColor(input: string, steps: number): string;
+declare function rgbEqual(a: RGB | undefined, b: RGB | undefined): boolean;
+declare function stepRgbToward(current: RGB, target: RGB, maxStep: number): RGB;
+declare function rgbToCss(rgb: RGB, alpha?: number): string;
+declare function colorErrorScore(current: string | undefined, next: string): number;
+
+declare function fullRectBounds(entry: TextureAtlasPlan): {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+} | null;
+declare function isFullRectSolid(entry: TextureAtlasPlan): boolean;
+declare function isSolidTrianglePlan(entry: TextureAtlasPlan): boolean;
+declare function isProjectiveQuadPlan(entry: TextureAtlasPlan): entry is TextureAtlasPlan & {
+    projectiveMatrix: string;
+};
+declare function safariCssProjectiveUnsupported(userAgent: string): boolean;
+declare function incrementCount(map: Map<string, number>, key: string): void;
+declare function dominantCountKey(map: Map<string, number>): string | undefined;
+interface FilterAtlasPlansEnv {
+    solidTriangleSupported: boolean;
+    projectiveQuadSupported: boolean;
+    borderShapeSupported: boolean;
+    /** When true, non-triangle non-rect non-projective polys whose plan has
+     *  cornerShapeGeometryForPlan != null are excluded from the atlas (they
+     *  render as <u> via corner-*-shape: bevel CSS — matches vanilla's
+     *  createCornerShapeSolidElement path). Falsy / undefined preserves the
+     *  earlier core behaviour (those polys stay in atlas as <s> fallback). */
+    cornerShapeSupported?: boolean;
+}
+/**
+ * Filter a plan array to the subset that needs atlas packing, given the active
+ * render strategies and texture-lighting mode. Plans excluded from the atlas
+ * will be rendered via `<b>`, `<i>`, or `<u>` by the framework components.
+ */
+declare function filterAtlasPlans(plans: Array<TextureAtlasPlan | null>, textureLighting: PolyTextureLightingMode, disabled: ReadonlySet<PolyRenderStrategy>, env: FilterAtlasPlansEnv): Array<TextureAtlasPlan | null>;
+interface GetSolidPaintDefaultsEnv {
+    solidTriangleSupported: boolean;
+    projectiveQuadSupported: boolean;
+    cornerShapeSupported: boolean;
+    borderShapeSupported: boolean;
+}
+declare function getSolidPaintDefaultsForPlansCore(plans: Array<TextureAtlasPlan | null>, textureLighting: PolyTextureLightingMode, disabled: ReadonlySet<PolyRenderStrategy>, env: GetSolidPaintDefaultsEnv, parseHexFn: (color: string) => RGB, rgbKeyFn: (rgb: RGB) => string, cornerShapeGeometryForPlanFn?: (plan: TextureAtlasPlan) => unknown): {
+    paintColor?: string;
+    dynamicColorKey?: string;
+    dynamicColor?: RGB;
+};
+
+declare function cssPoints(vertices: Vec3[], tile: number, elev: number): Vec3[];
+declare function computeSurfaceNormal(pts: Vec3[]): Vec3 | null;
+declare function isConvexPolygonPoints(points: Array<[number, number]>): boolean;
+declare function signedArea2D(points: Array<[number, number]>): number;
+declare function intersect2DLines(a0: [number, number], a1: [number, number], b0: [number, number], b1: [number, number]): [number, number] | null;
+declare function intersect2DLinesRaw(a0x: number, a0y: number, a1x: number, a1y: number, b0x: number, b0y: number, b1x: number, b1y: number): Vec2 | null;
+declare function expandClipPoints(points: number[], amount: number): number[];
+declare function offsetConvexPolygonPoints(points: number[], amount: number): number[];
+declare function offsetConvexPolygonPointsByEdgeAmounts(points: number[], amounts: readonly number[]): number[];
+declare function offsetTrianglePoints(x0: number, y0: number, x1: number, y1: number, x2: number, y2: number, amount: number): number[];
+declare function offsetStableTrianglePoints(left: number, right: number, height: number, amount: number): number[];
+declare function stableBasisFromPlan(source: TextureAtlasPlan, polygon: Polygon): StablePlanBasis | null;
+declare function stableTriangleMatrixDecimals(matrixDecimals: number | undefined): number;
+
+declare function polygonContainsPoint(points: Array<[number, number]>, px?: number, py?: number): boolean;
+declare function borderShapeBoundsFromPoints(points: number[], fallbackWidth: number, fallbackHeight: number): BorderShapeBounds;
+/** Reads `entry.bleedRatio` (defaulted to 1) and scales BORDER_SHAPE_BLEED
+ *  accordingly. Plans are tagged with the ratio at construction time
+ *  (see computeTextureAtlasPlan) so every consumer gets the same value. */
+declare function borderShapeGeometryForPlan(entry: TextureAtlasPlan): BorderShapeGeometry;
+declare function simplifyCornerShapePoints(points: Array<[number, number]>): Array<[number, number]>;
+declare function cornerShapePointSides([x, y]: [number, number]): Set<CornerShapeSide> | null;
+declare function sharedCornerShapeSide(a: Set<CornerShapeSide>, b: Set<CornerShapeSide>): boolean;
+declare function cornerShapeDiagonal(aPoint: [number, number], aSides: Set<CornerShapeSide>, bPoint: [number, number], bSides: Set<CornerShapeSide>): [CornerShapeCorner, CornerShapeRadius] | null;
+declare function cornerShapeGeometryForPlan(entry: TextureAtlasPlan): CornerShapeGeometry | null;
+declare function cssBorderShapeForGeometry(points: Array<[number, number]>): string;
+declare function cssBorderShapeForPlan(entry: TextureAtlasPlan): string;
+declare function formatBorderShapeEntryMatrix(entry: TextureAtlasPlan): string;
+declare function formatBorderShapeElementStyle(entry: TextureAtlasPlan): string;
+declare function formatCornerShapeElementStyle(entry: TextureAtlasPlan, geometry: CornerShapeGeometry): string;
+
+declare function computeSolidTriangleColorPlanFromNormal(polygon: Polygon, index: number, nx: number, ny: number, nz: number, options: SolidTrianglePlanOptions, includeColor: boolean, colorOverride?: string): SolidTriangleColorPlan;
+declare function computeSolidTriangleColorPlan(polygon: Polygon, index: number, options: SolidTrianglePlanOptions): SolidTriangleColorPlan | null;
+declare function computeSolidTrianglePlan(polygon: Polygon, index: number, options: SolidTrianglePlanOptions, computeOptions?: SolidTriangleComputeOptions): SolidTrianglePlan | null;
+declare function computeSolidTrianglePlanFromCssPoints(polygon: Polygon, index: number, options: SolidTrianglePlanOptions, computeOptions: SolidTriangleComputeOptions, p0x: number, p0y: number, p0z: number, p1x: number, p1y: number, p1z: number, p2x: number, p2y: number, p2z: number): SolidTrianglePlan | null;
+
+declare function resolveProjectiveQuadGuards(overrides: ProjectiveQuadGuardOverrides | undefined): ProjectiveQuadGuardSettings;
+declare function computeProjectiveQuadCoefficients(q: Array<[number, number]>, guards: ProjectiveQuadGuardSettings): ProjectiveQuadCoefficients | null;
+declare function computeProjectiveQuadMatrix(screenPts: number[], xAxis: Vec3, yAxis: Vec3, normal: Vec3, tx: number, ty: number, tz: number, guards: ProjectiveQuadGuardSettings, seamBleedEdgeAmounts?: ReadonlyMap<number, number>): string | null;
+declare function dotVec(a: Vec3, b: Vec3): number;
+declare function crossVec(a: Vec3, b: Vec3): Vec3;
+declare function isBasisOptimizable(polygon: Polygon): boolean;
+declare function getPolygonBasisInfo(polygon: Polygon, tile: number, elev: number): PolygonBasisInfo | null;
+declare function compatibleSurface(a: PolygonBasisInfo | null, b: PolygonBasisInfo | null): boolean;
+declare function compatibleBleedSurface(a: PolygonBasisInfo | null, b: PolygonBasisInfo | null): boolean;
+declare function seamLightBrightness(info: PolygonBasisInfo | null, options: SolidTrianglePlanOptions): number | null;
+declare function basisAxisKey(axis: Vec3): string;
+declare function makeLocalBasis(pts: Vec3[], origin: Vec3, normal: Vec3, rawXAxis: Vec3, options?: {
+    boundsOrigin?: Vec3;
+    snapBounds?: boolean;
+}): LocalBasis | null;
+declare function evaluateIslandAxis(component: number[], infos: Array<PolygonBasisInfo | null>, axis: Vec3, boundsOrigin: Vec3): {
+    pixelArea: number;
+    rawArea: number;
+} | null;
+declare function chooseIslandXAxis(component: number[], infos: Array<PolygonBasisInfo | null>): BasisHint | null;
+declare function buildBasisHints(polygons: Polygon[], options: SolidTrianglePlanOptions): Array<BasisHint | undefined>;
+declare function chooseLocalBasis(pts: Vec3[], origin: Vec3, normal: Vec3, options: BasisOptions): LocalBasis | null;
+declare function isFullRectBasis(basis: LocalBasis): boolean;
+declare function computeUvAffine(points: Vec2[], uvs: Vec2[]): UvAffine | null;
+declare function computeUvSampleRect(uvs: Vec2[]): UvSampleRect | null;
+declare function projectTextureTriangle(triangle: TextureTriangle, tile: number, elev: number, origin: Vec3, xAxis: Vec3, yAxis: Vec3, shiftX: number, shiftY: number): TextureTrianglePlan | null;
+declare function computeTextureAtlasPlan(polygon: Polygon, index: number, options: SolidTrianglePlanOptions, projectiveQuadGuards: ProjectiveQuadGuardSettings, basisHint?: BasisHint): TextureAtlasPlan | null;
+/**
+ * Compute the per-polygon layout plan for one polygon in isolation.
+ *
+ * This is the public single-polygon variant used by React and Vue components.
+ * It does not run the cross-polygon basis-optimisation or seam-detection that
+ * the full `renderPolygonsWithTextureAtlas` pipeline performs, but the
+ * strategy selection (projective-quad, rect, etc.) is identical to the
+ * canonical renderer.
+ *
+ * The `projectiveQuadOverrides` parameter is the pre-resolved override bag
+ * formerly obtained from `doc.defaultView.__polycssProjectiveQuadGuards`.
+ * Callers that have a Document should extract it before calling; callers in
+ * browser-free environments can pass `undefined` for the default guards.
+ */
+declare function computeTextureAtlasPlanPublic(polygon: Polygon, index: number, options?: ComputeTextureAtlasPlanOptions, projectiveQuadOverrides?: ProjectiveQuadGuardOverrides, 
+/** Cross-polygon basis hint pre-computed via {@link buildBasisHints} on
+ *  the full polygon array. When supplied, it overrides the per-polygon
+ *  textureEdgeRepairEdges fallback below. Vanilla's renderer always passes
+ *  this from {@link buildBasisHints}; React/Vue mirror that path. */
+basisHintOverride?: BasisHint): TextureAtlasPlan | null;
+
+declare function normalizeAtlasScale(scale: number | string | undefined): number;
+declare function atlasArea(pages: PackedPage[]): number;
+declare function autoAtlasScaleCap(pages: PackedPage[], maxDecodedBytes: number): number;
+declare function autoAtlasScale(pages: PackedPage[], maxDecodedBytes: number): number;
+declare function atlasBitmapMaxSide(pages: PackedPage[], atlasScale: number): number;
+declare function atlasDecodedBytes(pages: PackedPage[], atlasScale: number): number;
+declare function autoAtlasBudgetFactor(pages: PackedPage[], atlasScale: number, maxDecodedBytes: number): number;
+/** Returns the max decoded-bytes budget for the given device class. */
+declare function autoAtlasMaxDecodedBytes(isMobile: boolean): number;
+/** Returns the atlas canonical size for the given texture quality and device class. */
+declare function atlasCanonicalSizeForTextureQuality(textureQualityInput: TextureQuality | undefined, isMobile: boolean): number;
+declare function applyPackedAtlasCanonicalSize(packed: PackedAtlas, atlasCanonicalSize: number): PackedAtlas;
+declare function atlasCanonicalSizeForEntry(entry: TextureAtlasPlan): number;
+declare function atlasPadding(atlasScale: number): number;
+declare function packTextureAtlasPlans(plans: Array<TextureAtlasPlan | null>, atlasScale?: number): PackedAtlas;
+/**
+ * Pack atlas plans and resolve atlas scale, accepting a pre-resolved isMobile
+ * boolean instead of a Document reference.
+ */
+declare function packTextureAtlasPlansWithScaleCore(plans: Array<TextureAtlasPlan | null>, textureQualityInput: TextureQuality | undefined, isMobile: boolean): {
+    packed: PackedAtlas;
+    atlasScale: number;
+    atlasCanonicalSize: number;
+};
+
+export { ASYNC_RENDER_BUDGET_MS, ATLAS_CANONICAL_SIZE_AUTO_DESKTOP, ATLAS_CANONICAL_SIZE_EXPLICIT, ATLAS_MAX_SIZE, ATLAS_PADDING, AUTO_ATLAS_LOW_AREA, AUTO_ATLAS_MAX_BITMAP_SIDE, AUTO_ATLAS_MAX_DECODED_BYTES_DESKTOP, AUTO_ATLAS_MAX_DECODED_BYTES_MOBILE, AUTO_ATLAS_MEDIUM_AREA, AUTO_ATLAS_SCALE_GUARD, type ArrowPolygonsOptions, type AutoRotateConfig, type AutoRotateOption, type AxesHelperOptions, BAKED_SHADOW_MIN_UP, BAKED_SHADOW_Z_SQUASH, BASE_TILE, BASIS_EPS, BORDER_SHAPE_BLEED, BORDER_SHAPE_CANONICAL_SIZE, BORDER_SHAPE_CENTER_PERCENT, BORDER_SHAPE_POINT_EPS, type BasisHint, type BasisOptions, type BorderShapeBounds, type BorderShapeGeometry, type BoxFace, type BoxFaceOptions, type BoxPolygonsOptions, CAMERA_BACKFACE_CULL_EPS, COLOR_PARSE_CACHE_MAX, CORNER_SHAPE_DUPLICATE_EPS, CORNER_SHAPE_POINT_EPS, type CameraCullNormalGroup, type CameraCullRotation, type CameraHandle, type CameraState, type CameraStyleInput, type CasterPolyItem, type ComputeReceiverShadowFacesInput, type ComputeTextureAtlasPlanOptions, type ConePolygonsOptions, type CornerShapeCorner, type CornerShapeGeometry, type CornerShapeRadius, type CornerShapeSide, type CoverPlanarPolygonsOptions, type CullInteriorOptions, type CylinderPolygonsOptions, DECIMAL_SCALES, DEFAULT_AMBIENT_COLOR, DEFAULT_AMBIENT_INTENSITY, DEFAULT_ATLAS_CSS_DECIMALS, DEFAULT_BORDER_SHAPE_DECIMALS, DEFAULT_CAMERA_STATE, DEFAULT_LIGHT_COLOR, DEFAULT_LIGHT_DIR, DEFAULT_LIGHT_INTENSITY, DEFAULT_MATRIX_DECIMALS, DEFAULT_PROJECTION, DEFAULT_SEAM_BLEED, DEFAULT_SEAM_FACET_SPLIT_OPTIONS, DEFAULT_SEAM_OVERLAP_OPTIONS, DEFAULT_TILE, type DedupeOverlappingPolygonsOptions, type DodecahedronPolygonsOptions, type EdgeOwners, type FilterAtlasPlansEnv, type GetSolidPaintDefaultsEnv, type GltfParseOptions, type IcosahedronPolygonsOptions, type InternalSolidTrianglePlanOptions, type LoadMeshOptions, type LocalBasis, type LoopMode, LoopOnce, LoopPingPong, LoopRepeat, MAX_ATLAS_SCALE, MIN_ATLAS_SCALE, type MeshResolution, type MtlParseResult, type NormalizeResult, type ObjParseOptions, type OctahedronPolygonsOptions, type OptimizeAnimatedMeshPolygonsOptions, type OptimizeMeshParseResultOptions, type OptimizeMeshPolygonsOptions, PROJECTIVE_QUAD_BLEED, PROJECTIVE_QUAD_DENOM_EPS, PROJECTIVE_QUAD_MAX_WEIGHT_RATIO, type PackedAtlas, type PackedPage, type PackedTextureAtlasEntry, type PackingPage, type PackingShelf, type ParseAnimationClip, type ParseAnimationController, type ParseResult, type ParseStlColor, type ParseStlSolid, type ParseStlTopology, type ParsedColor, type PlanePolygonsOptions, type PolyAmbientLight, type PolyAnimationAction, type ParseAnimationClip as PolyAnimationClip, type PolyAnimationMixer, type PolyAnimationTarget, type PolyDirectionalLight, type PolyMaterial, type PolyRenderStrategiesOption, type PolyRenderStrategy, type PolySeamBleed, type PolySeamBleedEdgeValue, type PolySeamBleedEdges, type PolyTextureAlphaMode, type PolyTextureLightingMode, type PolyTextureWrap, type PolyTextureWrapMode, type PolyVoxelCell, type PolyVoxelSource, type Polygon, type PolygonBasisInfo, type PolygonFace, type ProjectiveQuadCoefficients, type ProjectiveQuadGuardGlobal, type ProjectiveQuadGuardOverrides, type ProjectiveQuadGuardSettings, QUAT_IDENTITY, type Quat, RECEIVER_NORMAL_TOL, RECEIVER_OFFSET_TOL, RECEIVER_OUTLINE_EXPAND, RECT_EPS, type RGB, type RGBFactors, type ReceiverCasterInput, type ReceiverFacePlane, type ReceiverPlaneGroup, type ReceiverShadowFaceSpec, type ReceiverShadowPath, type RectBrush, type RingPolygonsOptions, type RingQuadPolygonsOptions, SEAM_LIGHT_EPS, SOLID_QUAD_CANONICAL_SIZE, SOLID_TRIANGLE_BLEED, SOLID_TRIANGLE_CANONICAL_SIZE, SOLID_TRIANGLE_LARGE_BORDER_CANONICAL_SIZE, SURFACE_DISTANCE_EPS, SURFACE_NORMAL_EPS, type SceneBbox, type SceneContext, type SceneContextBuildArgs, type SceneContextBuildResult, type ScreenToWorldOptions, type SeamBleedInsets, type SeamFacetSplitCandidate, type SeamFacetSplitCandidateReason, type SeamFacetSplitOptions, type SeamFacetSplitReport, type SeamOverlapCandidate, type SeamOverlapCandidateKind, type SeamOverlapDiagnostics, type SeamOverlapOptions, type SimplifyTriangleMeshPolygonsOptions, type SolidPaintDefaults, type SolidTextureSampleOptions, type SolidTriangleBasis, type SolidTriangleColorPlan, type SolidTriangleComputeOptions, type SolidTriangleFrame, type SolidTrianglePlan, type SolidTrianglePlanOptions, type SolidTrianglePrimitive, type SpherePolygonsOptions, type StablePlanBasis, type StableTriangleColorState, type StlParseOptions, TEXTURE_EDGE_REPAIR_ALPHA_MIN, TEXTURE_EDGE_REPAIR_RADIUS, TEXTURE_EDGE_REPAIR_SOURCE_ALPHA_MIN, TEXTURE_TRIANGLE_BLEED, type TetrahedronPolygonsOptions, type TextureAtlasPage, type TextureAtlasPlan, type TexturePaintMetrics, type TexturePaintMetricsOptions, type TextureQuality, type TextureTriangle, type TextureTrianglePlan, type TorusPolygonsOptions, type UvAffine, type UvSampleRect, VOXEL_CAMERA_CULL_AXIS_EPS, VOXEL_CAMERA_CULL_NORMAL_LIMIT, type Vec2, type Vec3, type VoxParseOptions, applyPackedAtlasCanonicalSize, arrowPolygons, atlasArea, atlasBitmapMaxSide, atlasCanonicalSizeForEntry, atlasCanonicalSizeForTextureQuality, atlasDecodedBytes, atlasPadding, autoAtlasBudgetFactor, autoAtlasMaxDecodedBytes, autoAtlasScale, autoAtlasScaleCap, axesHelperPolygons, bakeSolidTextureSampledPolygons, bakeSolidTextureSamples, basisAxisKey, borderShapeBoundsFromPoints, borderShapeGeometryForPlan, boxPolygons, buildBakedShadowProjectionMatrix, buildBasisHints, buildEdgeOwners, buildSceneContext, buildSeamBleedPolygonEdges, buildSeamBleedPolygonSet, buildSharedEdgeMap, buildTextureEdgeRepairSets, cachedParsePureColor, cameraCullNormalGroups, cameraCullNormalGroupsFromPolygons, cameraCullNormalKey, cameraCullVisibleSignature, cameraFacingDepth, chooseIslandXAxis, chooseLocalBasis, clampChannel, classifyFacing, clipPolygonToConvex2D, colorErrorScore, compatibleBleedSurface, compatibleSurface, computeLightVisibility, computePlanSeamBleedEdgeAmounts, computeProjectiveQuadCoefficients, computeProjectiveQuadMatrix, computeReceiverShadowFaces, computeSceneBbox, computeSeamBleedInsets, computeShapeLighting, computeSolidTriangleColorPlan, computeSolidTriangleColorPlanFromNormal, computeSolidTrianglePlan, computeSolidTrianglePlanFromCssPoints, computeSurfaceNormal, computeTextureAtlasPlan, computeTextureAtlasPlanPublic, computeTexturePaintMetrics, computeUvAffine, computeUvSampleRect, conePolygons, convexHull2D, cornerShapeDiagonal, cornerShapeGeometryForPlan, cornerShapePointSides, coverPlanarPolygons, createIsometricCamera, createPolyAnimationMixer, crossVec, cssBorderShapeForGeometry, cssBorderShapeForPlan, cssPoints, cullInteriorPolygons, cylinderPolygons, dedupeOverlappingPolygons, dodecahedronPolygons, dominantCountKey, dotVec, ensureCcw2D, eulerXYZFromQuat, evaluateIslandAxis, expandClipPoints, expandConvexHullOutward, extractSilhouetteLoops, filterAtlasPlans, findOverlappingPolygonDuplicates, formatAffineMatrix3dColumns, formatAffineMatrix3dScalars, formatAffineMatrix3dTransformScalars, formatAtlasMatrix, formatBorderShapeElementStyle, formatBorderShapeEntryMatrix, formatBorderShapeMatrix, formatColor, formatCornerShapeElementStyle, formatCssLength, formatCssLengthPx, formatMatrix3d, formatMatrix3dValues, formatPercent, formatScaledMatrixFromPlan, formatSolidQuadEntryMatrix, formatSolidQuadMatrix, fullRectBounds, getPolygonBasisInfo, getSolidPaintDefaultsForPlansCore, groupReceiverFaceGroups, icosahedronPolygons, incrementCount, intersect2DLines, intersect2DLinesRaw, inverseRotateVec3, isAxisAlignedSurfaceNormal, isBakedShadowCaster, isBasisOptimizable, isConvexPolygonPoints, isFullRectBasis, isFullRectSolid, isProjectiveQuadPlan, isSolidTrianglePlan, isVoxelCameraCullableNormalGroups, loadMesh, makeLocalBasis, mergePolygons, meshScaleVec3, normalFacesCamera, normalizeAtlasScale, normalizeInvertMultiplier, normalizePolygons, normalizedSeamBleed, octahedronPolygons, offsetConvexPolygonPoints, offsetConvexPolygonPointsByEdgeAmounts, offsetStableTrianglePoints, offsetTrianglePoints, optimizeAnimatedMeshPolygons, optimizeMeshParseResult, optimizeMeshPolygons, packTextureAtlasPlans, packTextureAtlasPlansWithScaleCore, parseAlpha, parseColor, parseGltf, parseHex, parseHexColor, parseMtl, parseObj, parsePureColor, parseRgbColor, parseStl, parseVox, planePolygons, polygonContainsPoint, polygonCssSurfaceNormal, polygonFaces, polygonFacesCamera, polygonSignedArea2D, prepareCasterEdgeOwners, prepareCasterPolyItems, prepareReceiverFacePlanes, projectCssVertexToGround, projectTextureTriangle, quantizeCssColor, quatFromAxisAngle, quatFromEulerXYZ, quatMultiply, repairMeshSeams, resolveBleedRatio, resolveProjectiveQuadGuards, resolveSeamBleed, rgbEqual, rgbKey, rgbToCss, rgbToHex, ringPolygons, ringQuadPolygons, rotateVec3, rotateVec3InWrapperCssFrame, roundDecimal, safariCssProjectiveUnsupported, safePlanSeamBleedAmount, screenToWorldOnSphere, screenToWorldRay, seamBleedAmountArray, seamFacetSplitPolygons, seamFacetSplitReport, seamLightBrightness, seamOverlapDiagnostics, seamOverlapPolygons, seamOverlapReport, shadeColor, shadePolygon, sharedCornerShapeSide, signedArea2D, simplifyCornerShapePoints, simplifyTriangleMeshPolygons, spherePolygons, stableBasisFromPlan, stableTriangleMatrixDecimals, stepRgbToward, tetrahedronPolygons, textureTintFactors, tintToCss, torusPolygons, worldCssForMesh, worldDirectionToCss, worldDirectionalLightToCss, worldPositionToCss };