@layoutit/polycss-core 0.2.0 → 0.2.1

package/dist/index.d.cts

@@ -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,12 @@ interface Polygon {
      * @internal
      */
     textureTriangles?: TextureTriangle[];
+    /**
+     * 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
@@ -262,7 +288,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
@@ -334,7 +360,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 +375,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
@@ -509,6 +535,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
@@ -542,12 +572,6 @@ interface CoverPlanarPolygonsOptions {
  */
 declare function coverPlanarPolygons(input: Polygon[], options?: CoverPlanarPolygonsOptions): Polygon[];
 
-interface ApproximateMergeOptions {
-    maxAngleDeg?: number;
-    maxPlaneDisplacement?: number;
-    maxBoundaryDisplacement?: number;
-    isolatedPairs?: boolean;
-}
 interface OptimizeMeshPolygonsOptions {
     /** Public quality/resolution intent. Defaults to "lossy". */
     meshResolution?: MeshResolution;
@@ -556,16 +580,98 @@ interface OptimizeMeshPolygonsOptions {
      * regions. Defaults to true.
      */
     rectCover?: boolean | CoverPlanarPolygonsOptions;
-    /**
-     * 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.
-     */
-    approximateMerge?: boolean | ApproximateMergeOptions;
 }
 declare function optimizeMeshPolygons(polygons: Polygon[], options?: OptimizeMeshPolygonsOptions): Polygon[];
 
+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
  * polygons of the same mesh and therefore never visible from any external
@@ -588,7 +694,7 @@ 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;
 }
 declare function cullInteriorPolygons(polygons: Polygon[], options?: CullInteriorOptions): Polygon[];
@@ -621,7 +727,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 +756,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 +784,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 +823,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 +881,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.
  */
 
@@ -816,6 +922,249 @@ interface OctahedronPolygonsOptions {
 }
 declare function octahedronPolygons(options: OctahedronPolygonsOptions): Polygon[];
 
+/**
+ * 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).
+ *
+ * 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.
+ *
+ * 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 TetrahedronPolygonsOptions {
+    /** Circumradius: distance from center to each vertex. Default 100. */
+    size?: number;
+    /** Fill color applied to all four faces. */
+    color?: string;
+}
+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;
+}
+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;
+}
+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;
+}
+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 matrix3d expression in the
+ * dynamic-mode `--shadow-proj` CSS custom property, but with literal
+ * numbers — ready to be formatted into a single `matrix3d(...)` per
+ * shadow leaf.
+ *
+ * `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 per-element
+ * matrix3d that the dynamic-mode `--shadow-proj` builds, but evaluated on
+ * the CPU for a fixed light + ground — handy when many projected vertices
+ * are needed at once (e.g. rendering shadow outlines into a single SVG
+ * per mesh instead of one DOM leaf per casting polygon).
+ *
+ * `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]>;
+
 /**
  * Unified parser return type. All polygon-emitting parsers (parseObj,
  * parseGltf, the loadMesh dispatcher) return this exact shape.
@@ -1008,6 +1357,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
@@ -1095,10 +1450,16 @@ 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.
@@ -1147,54 +1508,22 @@ interface VoxParseOptions {
      * non-negative integers so zero makes sensible default.
      */
     gridShift?: number;
+    /**
+     * 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.
+     */
+    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[];
-
 /**
  * loadMesh — high-level fetch+parse dispatcher. Picks the parser by file
  * extension, fetches the URL, runs the parser, returns the unified
@@ -1247,4 +1576,513 @@ interface LoadMeshOptions {
 }
 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 SOLID_TRIANGLE_CORNER_CLASS = "polycss-corner-triangle";
+declare const SOLID_TRIANGLE_LARGE_BORDER_CLASS = "polycss-large-border-triangle";
+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;
+
+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;
+    /** 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>;
+}
+/** 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>;
+}
+
+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 64px 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;
+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;
+    borderShapeSupported: 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;
+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): 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 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 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 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 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, RECT_EPS, type RGB, type RGBFactors, type RectBrush, type RingPolygonsOptions, type RingQuadPolygonsOptions, SEAM_LIGHT_EPS, SOLID_QUAD_CANONICAL_SIZE, SOLID_TRIANGLE_BLEED, SOLID_TRIANGLE_CANONICAL_SIZE, SOLID_TRIANGLE_CORNER_CLASS, SOLID_TRIANGLE_LARGE_BORDER_CANONICAL_SIZE, SOLID_TRIANGLE_LARGE_BORDER_CLASS, SURFACE_DISTANCE_EPS, SURFACE_NORMAL_EPS, type SceneBbox, type SceneContext, type SceneContextBuildArgs, type SceneContextBuildResult, type SeamBleedInsets, type SeamFacetSplitCandidate, type SeamFacetSplitCandidateReason, type SeamFacetSplitOptions, type SeamFacetSplitReport, type SeamOverlapCandidate, type SeamOverlapCandidateKind, type SeamOverlapDiagnostics, type SeamOverlapOptions, type SolidPaintDefaults, type SolidTextureSampleOptions, type SolidTriangleBasis, type SolidTriangleColorPlan, type SolidTriangleComputeOptions, type SolidTriangleFrame, type SolidTrianglePlan, type SolidTrianglePlanOptions, type SolidTrianglePrimitive, type SpherePolygonsOptions, type StablePlanBasis, type StableTriangleColorState, 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, buildSceneContext, buildSeamBleedPolygonEdges, buildSeamBleedPolygonSet, buildTextureEdgeRepairSets, cachedParsePureColor, cameraCullNormalGroups, cameraCullNormalGroupsFromPolygons, cameraCullNormalKey, cameraCullVisibleSignature, cameraFacingDepth, chooseIslandXAxis, chooseLocalBasis, clampChannel, clipPolygonToConvex2D, colorErrorScore, compatibleBleedSurface, compatibleSurface, computePlanSeamBleedEdgeAmounts, computeProjectiveQuadCoefficients, computeProjectiveQuadMatrix, 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, filterAtlasPlans, findOverlappingPolygonDuplicates, formatAffineMatrix3dColumns, formatAffineMatrix3dScalars, formatAffineMatrix3dTransformScalars, formatAtlasMatrix, formatBorderShapeElementStyle, formatBorderShapeEntryMatrix, formatBorderShapeMatrix, formatColor, formatCornerShapeElementStyle, formatCssLength, formatCssLengthPx, formatMatrix3d, formatMatrix3dValues, formatPercent, formatScaledMatrixFromPlan, formatSolidQuadEntryMatrix, formatSolidQuadMatrix, fullRectBounds, getPolygonBasisInfo, getSolidPaintDefaultsForPlansCore, icosahedronPolygons, incrementCount, intersect2DLines, intersect2DLinesRaw, inverseRotateVec3, isAxisAlignedSurfaceNormal, isBakedShadowCaster, isBasisOptimizable, isConvexPolygonPoints, isFullRectBasis, isFullRectSolid, isProjectiveQuadPlan, isSolidTrianglePlan, isVoxelCameraCullableNormalGroups, loadMesh, makeLocalBasis, mergePolygons, normalFacesCamera, normalizeAtlasScale, normalizeInvertMultiplier, normalizePolygons, normalizedSeamBleed, octahedronPolygons, offsetConvexPolygonPoints, offsetConvexPolygonPointsByEdgeAmounts, offsetStableTrianglePoints, offsetTrianglePoints, optimizeAnimatedMeshPolygons, optimizeMeshPolygons, packTextureAtlasPlans, packTextureAtlasPlansWithScaleCore, parseAlpha, parseColor, parseGltf, parseHex, parseHexColor, parseMtl, parseObj, parsePureColor, parseRgbColor, parseVox, planePolygons, polygonContainsPoint, polygonCssSurfaceNormal, polygonFaces, polygonFacesCamera, polygonSignedArea2D, projectCssVertexToGround, projectTextureTriangle, quantizeCssColor, quatFromAxisAngle, quatFromEulerXYZ, quatMultiply, repairMeshSeams, resolveProjectiveQuadGuards, resolveSeamBleed, rgbEqual, rgbKey, rgbToCss, rgbToHex, ringPolygons, ringQuadPolygons, rotateVec3, roundDecimal, safariCssProjectiveUnsupported, safePlanSeamBleedAmount, seamBleedAmountArray, seamFacetSplitPolygons, seamFacetSplitReport, seamLightBrightness, seamOverlapDiagnostics, seamOverlapPolygons, seamOverlapReport, shadeColor, shadePolygon, sharedCornerShapeSide, signedArea2D, simplifyCornerShapePoints, spherePolygons, stableBasisFromPlan, stableTriangleMatrixDecimals, stepRgbToward, tetrahedronPolygons, textureTintFactors, tintToCss, torusPolygons };