@layoutit/polycss-core 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,914 @@
+declare const DEFAULT_PROJECTION: "cubic";
+/**
+ * How polygon lighting is applied by DOM renderers.
+ * - "baked": multiply the light tint into the off-DOM canvas before the
+ *   polygon becomes an atlas sprite. Best fidelity (full RGB tint) but
+ *   the atlas re-rasterizes whenever the light changes.
+ * - "dynamic": lighting computed entirely in CSS via per-polygon normals
+ *   embedded in calc() and scene-root light vars (background-color +
+ *   background-blend-mode multiply, masked by the atlas alpha). Atlas
+ *   stays light-independent — sliding the light only writes a few CSS
+ *   variables, no JS work, no atlas re-rasterization.
+ */
+type PolyTextureLightingMode = "baked" | "dynamic";
+/**
+ * 3D point/vector, stored as a `[x, y, z]` tuple. Tuple (rather than
+ * `{x, y, z}`) for compact JSON: meshes serialize to thousands of vertices
+ * 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.
+ */
+type Vec3 = [number, number, number];
+/**
+ * 2D point/vector — `[u, v]`. Used for texture-atlas UV coordinates on
+ * polygons. Convention follows OBJ: u is horizontal (0=left, 1=right),
+ * v is vertical (0=bottom, 1=top). Renderers flip v when binding to raster
+ * image space whose Y-axis points down.
+ */
+type Vec2 = [number, number];
+interface TextureTriangle {
+    vertices: [Vec3, Vec3, Vec3];
+    uvs: [Vec2, Vec2, Vec2];
+}
+/**
+ * Directional light — simulates a single distant source (sun, key light).
+ * Contributes Lambert shading scaled by `intensity`. `direction` is in
+ * scene-local CSS-pixel coords and does not need to be pre-normalized.
+ * Mirrors three.js's `DirectionalLight`.
+ */
+interface PolyDirectionalLight {
+    /** Direction the light shines TOWARD (typical convention). */
+    direction: Vec3;
+    /** Light tint, hex string. White by default. */
+    color?: string;
+    /** Scalar multiplier on the directional contribution. Default 1. */
+    intensity?: number;
+}
+/**
+ * Ambient light — uniform fill that adds to every polygon regardless of
+ * orientation. Mirrors three.js's `AmbientLight`. Decoupled from the
+ * directional contribution: the two add independently rather than
+ * splitting a fixed energy budget.
+ */
+interface PolyAmbientLight {
+    /** Tint, hex string. White by default. */
+    color?: string;
+    /** Scalar multiplier on the ambient contribution. Default 0.4. */
+    intensity?: number;
+}
+/**
+ * Material — paint configuration shareable across many polygons.
+ *
+ * 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
+ * `background-image: url(material.texture)` directly — no per-polygon canvas
+ * rasterization, browser-cached texture, mounting / unmounting one polygon
+ * does not affect any other.
+ *
+ * Three.js parallel: combines THREE.Texture + a basic Material in one. CSS
+ * has no shader/sampler concerns, so the texture/material split from
+ * Three.js doesn't pay rent here.
+ */
+interface PolyMaterial {
+    /** Image source. Anything `background-image: url(...)` can use. */
+    texture: string;
+    /** 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;
+}
+/**
+ * The single polygon type for polycss. N coplanar vertices in 3D space,
+ * CCW winding from outside. No bbox field, no shape discriminator, no
+ * input/output distinction — one type, used by parsers, by the merge
+ * pass, and by the renderer.
+ */
+interface Polygon {
+    /** N coplanar vertices in 3D space, CCW winding from outside. */
+    vertices: Vec3[];
+    /**
+     * Solid base color. Falls back to "#cccccc" when neither color nor
+     * texture is set.
+     */
+    color?: string;
+    /**
+     * Texture URL. When set with `uvs`, UV-mapped via affine; without
+     * `uvs`, single-tile fill. If the load fails, renderer falls back to
+     * `color` (or default gray).
+     */
+    texture?: string;
+    /**
+     * 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-
+     * polygon canvas rasterization). Falls back to the atlas path otherwise.
+     */
+    material?: PolyMaterial;
+    /**
+     * Per-vertex UV coords (0..1, OBJ convention with v=0 at bottom).
+     * Length MUST equal vertices.length when set; mismatched UVs are
+     * stripped by `normalizePolygons`.
+     */
+    uvs?: Vec2[];
+    /**
+     * Renderer-internal source triangles for UV textures. Merge passes use this
+     * to reduce DOM planes while preserving per-triangle texture mapping in the
+     * generated atlas.
+     * @internal
+     */
+    textureTriangles?: TextureTriangle[];
+    /**
+     * User-controlled metadata. Reflected to DOM as `data-*` attributes via
+     * stringification by the framework wrappers. Only string|number|boolean
+     * values are kept; other shapes are dropped by `normalizePolygons`.
+     */
+    data?: Record<string, string | number | boolean>;
+}
+
+/**
+ * normalizePolygons — validates a polygon list, drops degenerate inputs,
+ * triangulates non-coplanar N-gons, strips bad UVs, sanitizes data, and
+ * returns the cleaned polygons + a list of human-readable warnings.
+ *
+ * Validation rules are encoded here and covered by the normalization tests.
+ *
+ * Pure: no DOM, no I/O, deterministic. Bbox is NOT computed here — that's
+ * derived on demand by `buildSceneContext` / consumers.
+ */
+
+interface NormalizeResult {
+    polygons: Polygon[];
+    warnings: string[];
+}
+declare function normalizePolygons(input: Polygon[]): NormalizeResult;
+
+/**
+ * Scene context — the top-level entry point that takes a polygon mesh
+ * (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.
+ */
+
+interface SceneBbox {
+    /** Minimum corner of the axis-aligned bounding box (inclusive). */
+    min: Vec3;
+    /** Maximum corner of the axis-aligned bounding box (inclusive). */
+    max: Vec3;
+}
+interface SceneContext {
+    /** Validated polygon list — the renderer iterates this. */
+    polygons: Polygon[];
+    /** Polygon-mesh bbox in world space. Used to size the scene container. */
+    sceneBbox: SceneBbox;
+    /** Warnings raised during normalization (already-applied fixes). */
+    warnings: string[];
+}
+interface SceneContextBuildArgs {
+    /**
+     * Polygon list. Pass parser output directly — `buildSceneContext` runs
+     * `normalizePolygons` for you.
+     */
+    polygons: Polygon[];
+    /**
+     * If true, skip the normalize pass (caller has already validated). Useful
+     * when chaining `mergePolygons` after a manual `normalizePolygons` call.
+     */
+    skipNormalize?: boolean;
+}
+interface SceneContextBuildResult {
+    context: SceneContext;
+    /**
+     * Mesh-bbox dimensions. Convenience copy of `context.sceneBbox` plus a
+     * `size` field (max - min) for callers that want a single number per axis.
+     */
+    dimensions: {
+        sceneBbox: SceneBbox;
+        size: Vec3;
+    };
+    /** Warnings raised during normalization. Mirrors `context.warnings`. */
+    warnings: string[];
+}
+/**
+ * Compute the axis-aligned bounding box across every vertex of every polygon.
+ * Returns a zero-extent bbox at origin for empty input — callers that care
+ * about that case should check `polygons.length` first.
+ */
+declare function computeSceneBbox(polygons: Polygon[]): SceneBbox;
+declare function buildSceneContext(args: SceneContextBuildArgs): SceneContextBuildResult;
+
+/**
+ * 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.
+ */
+
+interface PolygonFace {
+    /** Vertices in CCW-from-outside order. Same as Polygon.vertices. */
+    v: Vec3[];
+    /** Original polygon's color, if any (for lighting helpers). */
+    color?: string;
+}
+interface TexturePaintMetricsOptions {
+    /** CSS pixels per world X/Y unit. Matches renderer default. */
+    tileSize?: number;
+    /** CSS pixels per world Z unit. Defaults to tileSize. */
+    layerElevation?: number;
+    /** When true, skip untextured polygons. Defaults to true. */
+    texturedOnly?: boolean;
+}
+interface TexturePaintMetrics {
+    /** Input polygon count before filtering. */
+    totalPolygons: number;
+    /** Polygons included in the metric after filtering and degeneracy checks. */
+    measuredPolygons: number;
+    /** Included polygons with a texture URL. */
+    texturedPolygons: number;
+    /** Sum of rectangular element areas in CSS px^2. */
+    elementArea: number;
+    /** Sum of projected polygon areas in CSS px^2. */
+    polygonArea: number;
+    /** elementArea - polygonArea, clamped at 0. */
+    transparentArea: number;
+    /** transparentArea / elementArea. */
+    transparentRatio: number;
+    /** elementArea / polygonArea. */
+    overdrawRatio: number;
+    /** Highest per-polygon transparentRatio. */
+    worstTransparentRatio: number;
+}
+/**
+ * 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.
+ *
+ * Returns an empty array for degenerate polygons (< 3 vertices).
+ */
+declare function polygonFaces(p: Polygon): PolygonFace[];
+declare function computeTexturePaintMetrics(polygons: Polygon[], options?: TexturePaintMetricsOptions): TexturePaintMetrics;
+
+/**
+ * Apply CSS-style chained `rotateX(rx) rotateY(ry) rotateZ(rz)` rotation
+ * 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
+ * matrix `M = Rx · Ry · Rz`, applied to a point as `M · p` — so Rz acts
+ * first on the point, then Ry, then Rx. Compound rotations only commute
+ * when axes coincide; getting the order wrong silently corrupts results
+ * for any two-axis combination.
+ *
+ * Angles in degrees.
+ */
+declare function rotateVec3(v: Vec3, rxDeg: number, ryDeg: number, rzDeg: number): Vec3;
+/**
+ * Inverse of `rotateVec3` for the same rotation tuple — transforms a
+ * world-space vector into the mesh's local frame. Used by the baked
+ * atlas pipeline to inverse-rotate the directional light so the
+ * pre-multiplied Lambert shading stays correct after the mesh rotates,
+ * and by the dynamic-mode CSS-var override for the same reason.
+ *
+ * The inverse of `M = Rx · Ry · Rz` is `M⁻¹ = Rz⁻¹ · Ry⁻¹ · Rx⁻¹`, so
+ * Rx⁻¹ acts first on the vector, then Ry⁻¹, then Rz⁻¹.
+ *
+ * `rot` is `[rxDeg, ryDeg, rzDeg]` matching the mesh's CSS rotation prop.
+ */
+declare function inverseRotateVec3(v: Vec3, rot: Vec3): Vec3;
+
+/**
+ * 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.
+ */
+declare const BASE_TILE = 50;
+interface AutoRotateConfig {
+    axis?: "x" | "y";
+    speed?: number;
+    pauseOnInteraction?: boolean;
+}
+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).
+ *
+ * `pan`, `tilt`, and `depthOffset` are gone. Translations now live inside
+ * `target` so they happen BEFORE rotations — enabling correct world-space
+ * pan at any tilt angle.
+ *
+ * `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.
+ */
+interface CameraState {
+    target: Vec3;
+    rotX: number;
+    rotY: number;
+    zoom: number;
+    /** Camera pull-back from target in CSS pixels. Default 0. */
+    distance: number;
+}
+interface CameraStyleInput {
+    rows?: number;
+    cols?: number;
+}
+interface CameraHandle {
+    state: CameraState;
+    update(next: Partial<CameraState>): void;
+    getStyle(input?: CameraStyleInput): {
+        transform: string;
+        width: string;
+        height: string;
+    };
+}
+declare function normalizeInvertMultiplier(value: number | boolean | undefined): number | undefined;
+declare const DEFAULT_CAMERA_STATE: CameraState;
+declare function createIsometricCamera(initial?: Partial<CameraState>): CameraHandle;
+
+interface ParsedColor {
+    rgb: [number, number, number];
+    alpha: number;
+}
+declare function parseHexColor(value: string): ParsedColor | null;
+declare function parseRgbColor(value: string): ParsedColor | null;
+/** Parse hex or rgb/rgba color strings. Pure — no DOM. */
+declare function parsePureColor(input: string): ParsedColor | null;
+declare function clampChannel(value: number): number;
+declare function formatColor(color: ParsedColor): string;
+
+declare function parseColor(input: string): ParsedColor | null;
+/**
+ * Lighten/darken a color by a flat per-channel delta. Used by the framework
+ * wrappers for tinted-overlay debug renderers; per-polygon Lambert shading
+ * goes through `computeShapeLighting` instead.
+ */
+declare function shadeColor(base: string, delta: number): string;
+/**
+ * Per-polygon Lambert shading. Given a polygon's outward normal and the
+ * scene's lights, returns the shaded color as a CSS rgb string.
+ *
+ * Math (decoupled, three.js convention):
+ *   tint = ambient.color · ambient.intensity
+ *        + directional.color · directional.intensity · max(0, n · (−L))
+ *   final = baseColor × tint
+ *
+ * Pass `directional` and/or `ambient` undefined to fall back to defaults
+ * (top-down white directional with intensity 1, white ambient with
+ * intensity 0.4) — useful for static SSR/validator renders.
+ */
+declare function computeShapeLighting(normal: Vec3, baseColor: string, directional?: PolyDirectionalLight, ambient?: PolyAmbientLight): string;
+
+/**
+ * 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.
+ *
+ *   - Geodesic spheres: ~half the triangles came from quad subdivisions
+ *   - OBJ imports: many were quads/n-gons fan-triangulated by the importer
+ *   - Hand-built dodecahedra: 36 triangles → 12 pentagons
+ *
+ * Algorithm:
+ *   1. For each input polygon, compute its plane (unit normal + signed
+ *      distance from origin).
+ *   2. Build an undirected edge graph: every edge of every polygon indexes
+ *      the polygons it belongs to.
+ *   3. Repeatedly walk shared edges and merge the two polygons sharing that
+ *      edge if they pass the merge predicate (same color, near-coplanar,
+ *      result is convex, edge is interior). Each merge replaces two
+ *      polygons with one larger polygon and updates the edge index.
+ *   4. Iterate until no more merges fire — the fixed point grows triangles
+ *      → quads → pentagons → … as far as the geometry allows.
+ *
+ * Polygons with < 3 vertices are passed through unchanged (the caller is
+ * expected to have run `normalizePolygons` first; this is a defensive copy).
+ */
+
+declare function mergePolygons(input: Polygon[]): Polygon[];
+
+interface CoverPlanarPolygonsOptions {
+    /** Smallest connected coplanar group worth attempting. Default 4. */
+    minGroupPolygons?: number;
+    /** Maximum candidate 2D axes tested per group. Default 8. */
+    maxCandidateAxes?: number;
+    /** Plane normal/distance tolerance in scene units. Default 1e-3. */
+    planeEpsilon?: number;
+}
+/**
+ * Re-cover flat same-color mesh regions with generated convex polygons.
+ *
+ * `mergePolygons` preserves source topology: it can only combine existing
+ * neighboring faces. This pass is more aggressive for solid-color planar
+ * regions: it projects each connected coplanar patch into 2D, covers the
+ * patch from its outer boundary, then lets `mergePolygons` collapse the
+ * generated cover into large rects/quads where possible.
+ */
+declare function coverPlanarPolygons(input: Polygon[], options?: CoverPlanarPolygonsOptions): Polygon[];
+
+/**
+ * cullInteriorPolygons — remove polygons that are fully enclosed by other
+ * polygons of the same mesh and therefore never visible from any external
+ * camera direction.
+ *
+ * Algorithm: for each polygon p,
+ *   1. Sample K unit directions on the hemisphere above p's normal.
+ *   2. Cast a ray from a point just above p's centroid in each direction.
+ *   3. If at least one ray escapes without hitting any other polygon → p
+ *      is potentially visible from some external camera → keep it.
+ *   4. If every ray hits another polygon → p is fully surrounded → cull it.
+ *
+ * Acceleration: flat-array SAH-built binary BVH with slab-test AABB traversal.
+ * All BVH data is stored in typed Float64Array / Int32Array for cache efficiency.
+ * Ray traversal visits only the subtrees whose AABBs the ray intersects.
+ *
+ * Runs once at parse time inside `loadMesh`, before `mergePolygons`. Zero
+ * runtime cost. Conservative by design — false negatives (failing to cull
+ * a truly hidden poly) are safe; false positives would be a visual bug.
+ */
+
+interface CullInteriorOptions {
+    /** Hemisphere ray samples per polygon. Higher = fewer false positives, slower. Default 12. */
+    samples?: number;
+}
+declare function cullInteriorPolygons(polygons: Polygon[], options?: CullInteriorOptions): Polygon[];
+
+/**
+ * Geometry for the three.js-style debug axes gizmo: three thin colored
+ * 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
+ * (`+X right, +Y forward, +Z up`). Wrap with the framework's PolyMesh /
+ * PolyScene equivalent to render.
+ */
+
+interface AxesHelperOptions {
+    /** Length of each axis bar in world units. */
+    size?: number;
+    /** Bar cross-section width as a fraction of `size`. */
+    thickness?: number;
+    /** When true, also draws bars in the −X / −Y / −Z direction. */
+    negative?: boolean;
+    /** X-axis bar color. */
+    xColor?: string;
+    /** Y-axis bar color. */
+    yColor?: string;
+    /** Z-axis bar color. */
+    zColor?: string;
+}
+/**
+ * Build the polygons for an AxesHelper-style gizmo. Three thin cuboids,
+ * one per world axis. Defaults match `<PolyAxesHelper>` in the framework
+ * packages.
+ */
+declare function axesHelperPolygons(options?: AxesHelperOptions): Polygon[];
+
+/**
+ * Geometry for a single 3D arrow: a thin axis-aligned cuboid shaft
+ * stretching from the origin along one signed axis, capped with a
+ * 4-sided pyramid head pointing further in that direction. Used as the
+ * drag handle for `<TransformControls>` — same primitive recipe as
+ * `axesHelperPolygons`, plus an arrowhead.
+ *
+ * Returned polygons are in standard polycss world space and intended
+ * to be wrapped in the framework's PolyMesh equivalent for rendering.
+ */
+
+interface ArrowPolygonsOptions {
+    /** World axis the arrow extends along: 0=X, 1=Y, 2=Z. */
+    axis: 0 | 1 | 2;
+    /** Direction along the axis: +1 (positive) or -1 (negative). Default +1. */
+    sign?: 1 | -1;
+    /** Length of the rectangular shaft along the axis. */
+    shaftLength?: number;
+    /** Half cross-section of the shaft (perpendicular to the axis). */
+    shaftHalfThickness?: number;
+    /** Length of the pyramid head along the axis (extends past the shaft). */
+    headLength?: number;
+    /** Half-extent of the pyramid base. */
+    headHalfThickness?: number;
+    /** Fill color. */
+    color?: string;
+}
+/** Build the polygons for one signed-axis arrow. */
+declare function arrowPolygons(options: ArrowPolygonsOptions): Polygon[];
+
+/**
+ * Geometry for a flat ring (annulus) lying in the plane perpendicular
+ * to a chosen axis. Used as the rotation handle in
+ * `<TransformControls mode="rotate">` — three rings, one per axis,
+ * each draggable to rotate the target around that axis.
+ *
+ * The ring is a sequence of quad segments around a circle. We don't
+ * model a true torus (tube) — a flat annulus reads cleanly as a
+ * "rotation circle" and keeps the polygon count proportional to the
+ * `segments` knob.
+ *
+ * Returned polygons are in standard polycss world space and intended
+ * to be wrapped in the framework's PolyMesh equivalent for rendering.
+ */
+
+interface RingPolygonsOptions {
+    /** World axis the ring is perpendicular to: 0=X, 1=Y, 2=Z. The ring
+     *  itself lies in the plane spanned by the other two axes. */
+    axis: 0 | 1 | 2;
+    /** Mid-radius of the ring (distance from center to the middle of
+     *  the annulus band). */
+    radius: number;
+    /** Half-width of the annulus band — the ring spans `radius - half`
+     *  to `radius + half`. */
+    halfThickness?: number;
+    /** Number of quad segments around the circle. Higher = smoother. */
+    segments?: number;
+    /** Fill color. */
+    color?: string;
+}
+/** Build the polygons for a flat ring (annulus). */
+declare function ringPolygons(options: RingPolygonsOptions): Polygon[];
+
+/**
+ * Geometry for a small solid-color octahedron — the marker shape used by
+ * `PolyDirectionalLightHelper` to indicate where a directional light is
+ * shining from. Eight CCW-from-outside triangular faces, vertices at
+ * `center ± (size, 0, 0)` etc.
+ */
+
+interface OctahedronPolygonsOptions {
+    /** Center of the octahedron in world space. */
+    center: Vec3;
+    /** Half-extent (distance from center to each pole vertex). */
+    size: number;
+    /** Fill color applied to all eight faces. */
+    color?: string;
+}
+declare function octahedronPolygons(options: OctahedronPolygonsOptions): Polygon[];
+
+/**
+ * Unified parser return type. All polygon-emitting parsers (parseObj,
+ * parseGltf, 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 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[];
+    /**
+     * 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[];
+}
+interface ParseResult {
+    /** The mesh, as a flat polygon list. Already vertex-permuted to polycss space. */
+    polygons: Polygon[];
+    /** 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;
+    };
+}
+
+/**
+ * PolyAnimationMixer — three.js-shaped animation API for polycss.
+ *
+ * Mirrors three.js's AnimationMixer + AnimationAction surface closely enough
+ * that users familiar with drei's `useAnimations` can migrate without friction.
+ *
+ * Loop mode constants match three.js numeric values exactly:
+ *   LoopOnce = 2200, LoopRepeat = 2201, LoopPingPong = 2202
+ */
+
+declare const LoopOnce: 2200;
+declare const LoopRepeat: 2201;
+declare const LoopPingPong: 2202;
+type LoopMode = typeof LoopOnce | typeof LoopRepeat | typeof LoopPingPong;
+
+/**
+ * Minimal target interface the mixer requires. `PolyMeshHandle` from both
+ * the polycss vanilla API and the React/Vue frameworks satisfies this
+ * structurally — no import needed.
+ */
+interface PolyAnimationTarget {
+    setPolygons(polygons: Polygon[]): void;
+}
+/**
+ * Per-clip playback action. Mirrors three.js `AnimationAction` method surface.
+ * All mutating methods return `this` for chaining.
+ */
+interface PolyAnimationAction {
+    /** Start playing (sets weight=1, resets time if not already playing). */
+    play(): PolyAnimationAction;
+    /** Stop playing and reset time to 0. */
+    stop(): PolyAnimationAction;
+    /** Reset time to 0 without stopping. */
+    reset(): PolyAnimationAction;
+    /** Fade weight from 0 to 1 over `durationSeconds`. */
+    fadeIn(durationSeconds: number): PolyAnimationAction;
+    /** Fade weight from current to 0 over `durationSeconds`. */
+    fadeOut(durationSeconds: number): PolyAnimationAction;
+    /**
+     * Cross-fade from this action to `target` over `durationSeconds`.
+     * Fades this out and target in simultaneously.
+     */
+    crossFadeTo(target: PolyAnimationAction, durationSeconds: number): PolyAnimationAction;
+    /**
+     * Cross-fade from `from` into this action over `durationSeconds`.
+     * Sugar for `from.fadeOut(d); this.fadeIn(d)`.
+     */
+    crossFadeFrom(from: PolyAnimationAction, durationSeconds: number): PolyAnimationAction;
+    /** Set loop mode and repetition count. */
+    setLoop(mode: LoopMode, repetitions: number): PolyAnimationAction;
+    /** Override the effective time scale. */
+    setEffectiveTimeScale(scale: number): PolyAnimationAction;
+    /** Override the effective weight. */
+    setEffectiveWeight(weight: number): PolyAnimationAction;
+    /** When true, the action freezes on the last frame after finishing. */
+    clampWhenFinished: boolean;
+    /** Playback speed multiplier. Default 1. */
+    timeScale: number;
+    /** Blend weight [0, 1]. Default 1. */
+    weight: number;
+    /** Current playback position in seconds. */
+    time: number;
+    /**
+     * When false, the action contributes 0 weight to the blend even if
+     * `weight > 0`. Time still advances. Default true.
+     */
+    enabled: boolean;
+    /**
+     * When true, time does NOT advance on `mixer.update()` but the action
+     * remains active and contributes its current weight to the blend. Default false.
+     */
+    paused: boolean;
+    /** Whether the action is currently playing. */
+    readonly isRunning: boolean;
+}
+/**
+ * Drives one or more `PolyAnimationAction`s against a single mesh target.
+ * Mirrors the three.js `AnimationMixer` API.
+ */
+interface PolyAnimationMixer {
+    /**
+     * Return the action for a clip (by index or name). Creates the action if it
+     * doesn't exist yet (lazy instantiation, same as three.js).
+     */
+    clipAction(clip: number | string): PolyAnimationAction;
+    /**
+     * Return an existing action without creating one. Returns null if the
+     * action hasn't been instantiated yet.
+     */
+    existingAction(clip: number | string): PolyAnimationAction | null;
+    /**
+     * Advance all active actions by `deltaSeconds` and apply the resulting
+     * polygon frame to the root target. Call this once per animation frame.
+     */
+    update(deltaSeconds: number): void;
+    /** Stop all active actions. */
+    stopAllAction(): void;
+    /** Remove a cached action for `clip`. */
+    uncacheClip(clip: number | string): void;
+    /** Remove all cached actions for this mixer's root. */
+    uncacheRoot(): void;
+}
+declare function createPolyAnimationMixer(root: PolyAnimationTarget, controller: ParseAnimationController): PolyAnimationMixer;
+
+interface ObjParseOptions {
+    /**
+     * Largest mesh extent (in scene-space units). The mesh is uniformly
+     * scaled so its longest bbox dimension equals this. Default: 60.
+     */
+    targetSize?: number;
+    /**
+     * Padding added to the bbox of every emitted polygon so they don't land
+     * at coordinate "0". Default: 1.
+     */
+    gridShift?: number;
+    /**
+     * Color used for faces that have no `usemtl` in scope, or whose material
+     * name doesn't resolve via `materialColors`. Default: "#888888".
+     */
+    defaultColor?: string;
+    /**
+     * Override map: material name → CSS color string. Falls back to:
+     *  1. The material name interpreted as a 6-char hex (e.g. "FF9800" → "#FF9800"),
+     *  2. Otherwise a slot from `palette` indexed by first-seen material order,
+     *  3. Otherwise `defaultColor`.
+     */
+    materialColors?: Record<string, string>;
+    /**
+     * Optional map: material name → texture URL. When set, every triangle
+     * emitted under that material gets `texture` populated. The renderer
+     * stamps the image across the triangle's local 2D plane.
+     */
+    materialTextures?: Record<string, string>;
+    /**
+     * Palette used to assign colors to materials whose names aren't hex.
+     * Each new non-hex material name takes the next palette slot.
+     */
+    palette?: string[];
+    /**
+     * Names of `o <name>` objects to KEEP. When set, faces outside these
+     * objects are dropped.
+     */
+    includeObjects?: string[];
+    /**
+     * Names of `o <name>` objects to DROP. Applied after `includeObjects`.
+     * Faces with no enclosing `o` line are kept unless `includeObjects` is set.
+     */
+    excludeObjects?: string[];
+}
+declare function parseObj(text: string, options?: ObjParseOptions): ParseResult;
+
+/**
+ * Wavefront `.mtl` material file parser. Companion to parseObj — reads the
+ * material library that ships next to a `.obj` and returns per-material
+ * diffuse color (`Kd`) and optional diffuse texture map path (`map_Kd`).
+ *
+ * Usage:
+ *   const mtl = await fetch("/foo.mtl").then(r => r.text());
+ *   const { colors, textures } = parseMtl(mtl);
+ *   const obj = await fetch("/foo.obj").then(r => r.text());
+ *   const { polygons } = parseObj(obj, { materialColors: colors, materialTextures: textures });
+ *
+ * Texture paths are returned exactly as written in the .mtl — relative paths,
+ * Windows backslashes etc. are not normalized. Callers are expected to
+ * resolve them against the .mtl's base URL.
+ *
+ * NOTE: parseMtl intentionally returns its own `MtlParseResult` shape
+ * (NOT the unified `ParseResult`). It's an asymmetric helper — it emits
+ * materials, not polygons — and forcing it into ParseResult would mean
+ * an empty `polygons[]` and a misleading `dispose()`.
+ */
+interface MtlParseResult {
+    /** Material name → CSS hex color (from `Kd r g b`). */
+    colors: Record<string, string>;
+    /** Material name → texture path (from `map_Kd <path>`). Path is unresolved. */
+    textures: Record<string, string>;
+}
+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;
+    /**
+     * Override map: glTF material name → CSS color string. Falls back to the
+     * material's `pbrMetallicRoughness.baseColorFactor` if not in this map.
+     */
+    materialColors?: 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).
+     *  - "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";
+    /**
+     * For .gltf (non-binary) — resolve a glTF buffer URI to its bytes. The
+     * built-in parser handles GLB binary chunks natively; .gltf files with
+     * external .bin files need this.
+     */
+    resolveBuffer?: (uri: string) => Promise<Uint8Array> | Uint8Array;
+    /**
+     * Base URL the source file lives at. Used to resolve external image URIs
+     * (`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;
+
+interface SolidTextureSampleOptions {
+    /**
+     * Set false to keep every textured polygon texture-backed. Defaults to true
+     * when a browser-like Image + canvas environment is available.
+     */
+    enabled?: boolean;
+    /** Per-channel tolerance for declaring sampled texels uniform. Default 2. */
+    colorTolerance?: number;
+    /** Skip decoding very large textures for this optimization. Default 16 MP. */
+    maxTexturePixels?: number;
+}
+declare function bakeSolidTextureSampledPolygons(polygons: Polygon[], options?: SolidTextureSampleOptions): Promise<Polygon[]>;
+declare function bakeSolidTextureSamples(result: ParseResult, options?: SolidTextureSampleOptions): Promise<ParseResult>;
+
+interface VoxParseOptions {
+    /**
+     * Largest mesh extent (in scene-space units). The mesh is uniformly
+     * scaled so its longest bbox dimension equals this. Default: 60.
+     */
+    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.
+     */
+    gridShift?: number;
+}
+declare function parseVox(buffer: ArrayBuffer, options?: VoxParseOptions): ParseResult;
+
+/**
+ * loadMesh — high-level fetch+parse dispatcher. Picks the parser by file
+ * extension, fetches the URL, runs the parser, returns the unified
+ * `ParseResult`.
+ *
+ * Supported:
+ *   - `.obj`  → text fetch + `parseObj`
+ *   - `.glb`  → ArrayBuffer fetch + `parseGltf`
+ *   - `.gltf` → ArrayBuffer fetch + `parseGltf` (caller may pass `baseUrl`)
+ *   - `.vox`  → ArrayBuffer fetch + `parseVox`
+ *
+ * `.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.
+ */
+
+interface LoadMeshOptions {
+    /**
+     * Base URL for resolving relative texture/buffer URIs inside the mesh
+     * (passed through to `parseGltf` for embedded image extraction). When
+     * omitted, the URL passed to `loadMesh` is used as the base.
+     */
+    baseUrl?: string;
+    /**
+     * Companion `.mtl` URL for OBJ files. When set, loadMesh fetches the
+     * mtl, runs `parseMtl`, and threads `materialColors` + `materialTextures`
+     * into `parseObj` — so the OBJ renders with its authored materials.
+     * Texture paths inside the mtl are resolved against the mtl URL.
+     * Ignored for `.glb` / `.gltf` (they carry materials inline).
+     */
+    mtlUrl?: string;
+    /** Forwarded to `parseObj` (merged with materials derived from `mtlUrl`). */
+    objOptions?: ObjParseOptions;
+    /** Forwarded to `parseGltf`. */
+    gltfOptions?: GltfParseOptions;
+    /** Forwarded to `parseVox`. */
+    voxOptions?: VoxParseOptions;
+    /**
+     * Converts texture-backed faces whose UV samples are a uniform color into
+     * solid-color polygons before culling/merging. This avoids atlas sprites for
+     * low-poly models that use texture atlases as color swatches.
+     */
+    solidTextureSamples?: boolean | SolidTextureSampleOptions;
+}
+declare function loadMesh(url: string, options?: LoadMeshOptions): Promise<ParseResult>;
+
+export { type ArrowPolygonsOptions, type AutoRotateConfig, type AutoRotateOption, type AxesHelperOptions, BASE_TILE, type CameraHandle, type CameraState, type CameraStyleInput, type CoverPlanarPolygonsOptions, type CullInteriorOptions, DEFAULT_CAMERA_STATE, DEFAULT_PROJECTION, type GltfParseOptions, type LoadMeshOptions, type LoopMode, LoopOnce, LoopPingPong, LoopRepeat, type MtlParseResult, type NormalizeResult, type ObjParseOptions, type OctahedronPolygonsOptions, type ParseAnimationClip, type ParseAnimationController, type ParseResult, type ParsedColor, type PolyAmbientLight, type PolyAnimationAction, type ParseAnimationClip as PolyAnimationClip, type PolyAnimationMixer, type PolyAnimationTarget, type PolyDirectionalLight, type PolyMaterial, type PolyTextureLightingMode, type Polygon, type PolygonFace, type RingPolygonsOptions, type SceneBbox, type SceneContext, type SceneContextBuildArgs, type SceneContextBuildResult, type SolidTextureSampleOptions, type TexturePaintMetrics, type TexturePaintMetricsOptions, type TextureTriangle, type Vec2, type Vec3, type VoxParseOptions, arrowPolygons, axesHelperPolygons, bakeSolidTextureSampledPolygons, bakeSolidTextureSamples, buildSceneContext, clampChannel, computeSceneBbox, computeShapeLighting, computeTexturePaintMetrics, coverPlanarPolygons, createIsometricCamera, createPolyAnimationMixer, cullInteriorPolygons, formatColor, inverseRotateVec3, loadMesh, mergePolygons, normalizeInvertMultiplier, normalizePolygons, octahedronPolygons, parseColor, parseGltf, parseHexColor, parseMtl, parseObj, parsePureColor, parseRgbColor, parseVox, polygonFaces, ringPolygons, rotateVec3, shadeColor };