@glyphcss/core 0.0.1

package/dist/index.d.cts

@@ -0,0 +1,1181 @@
+declare const DEFAULT_PROJECTION: "cubic";
+/**
+ * Mesh post-processing intent.
+ * - "lossless": preserve the authored surface while applying exact
+ *   reductions such as interior culling and coplanar merge.
+ * - "lossy": allow bounded geometric approximation when it reduces the
+ *   rendered polygon/DOM count.
+ */
+type MeshResolution = "lossless" | "lossy";
+/**
+ * 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];
+    /** Hex color string (`#rrggbb`) propagated from source model material. */
+    color?: string;
+}
+/**
+ * Directional light — simulates a single distant source (sun, key light).
+ * Contributes Lambert shading scaled by `intensity`. `direction` is in
+ * scene-local coords and does not need to be pre-normalized.
+ * Mirrors three.js's `DirectionalLight`.
+ */
+interface GlyphcssDirectionalLight {
+    /** 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 GlyphcssAmbientLight {
+    /** 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>;
+}
+/** Rendering mode for `rasterize`. See README for tradeoffs. */
+type RenderMode = "wireframe" | "solid" | "voxel";
+/**
+ * Character ramp used by `solid` mode to map shaded intensity to a glyph.
+ * Index 0 = darkest (transparent / unset), last index = brightest.
+ */
+type CharRamp = string[];
+/**
+ * Wireframe edge weight. Maps to glyph density in the rasterizer:
+ *   1 — thin (spokes, inner cage)
+ *   2 — normal (main cage edges)
+ *   3 — core (focal accents)
+ */
+type EdgeWeight = 1 | 2 | 3;
+/** A single drawable edge in wireframe mode. */
+interface WireframeEdge {
+    from: Vec3;
+    to: Vec3;
+    weight?: EdgeWeight;
+    /** Hex color string (`#rrggbb`) propagated from the adjacent triangle's material. */
+    color?: string;
+}
+/** Grid dimensions in character cells. */
+interface GridSize {
+    cols: number;
+    rows: number;
+    /** Character cell aspect ratio (height / width). Typically ~2.0 for monospace. */
+    cellAspect: number;
+}
+/**
+ * A 3D anchor that should produce a 2D hitbox in the consumer's DOM.
+ * Consumers absolute-position a `<div>` at the projected cell, sized by
+ * `size` (in character cells). Pure-math: this module just projects.
+ */
+interface Hotspot {
+    id: string;
+    at: Vec3;
+    /** Hitbox size in cells. Default `[1, 1]`. */
+    size?: [number, number];
+}
+/** Result of projecting a single hotspot through the camera. */
+interface HotspotCell {
+    id: string;
+    col: number;
+    row: number;
+    /** Camera-space Z. Useful for `z-index` / occlusion checks. */
+    depth: number;
+    /** False if behind the camera or off-grid. */
+    visible: 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;
+}
+/**
+ * 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[];
+
+/**
+ * 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;
+
+/**
+ * Minimal quaternion helpers for composing rotations.
+ *
+ * Why we need quaternions: the public PolyMesh API exposes rotation as a
+ * Euler triple `[rx, ry, rz]` in degrees (drives CSS `rotateX rotateY
+ * rotateZ`, applied right-to-left). Euler triples don't compose by
+ * component addition — rotating Y after X must happen around the mesh's
+ * NEW local-Y axis, not world-Y. The transform-controls ring drag handler
+ * uses these helpers to compose around the mesh's local axis correctly:
+ *
+ *   q_start = quatFromEulerXYZ(currentRotationDeg)
+ *   q_delta = quatFromAxisAngle(localAxis, deltaRadians)
+ *   q_new   = quatMultiply(q_start, q_delta)        // RIGHT-multiply = local frame
+ *   next    = eulerXYZFromQuat(q_new)
+ *
+ * Convention: "XYZ" Euler means the composed rotation matrix is
+ * `Rx(rx) · Ry(ry) · Rz(rz)`, which matches CSS `rotateX rotateY rotateZ`
+ * (right-to-left application to a point ⇒ Z first, then Y, then X).
+ *
+ * Quaternion format: `[w, x, y, z]` (real-first, like three.js's internal
+ * `_x/_y/_z/_w` reordered). Stored as plain tuples — no constructor or
+ * runtime allocations per drag.
+ */
+
+/** Quaternion `[w, x, y, z]`, real component first. Unit-length is not
+ *  enforced by the type — callers normalize when needed. */
+type Quat = [number, number, number, number];
+/** Identity quaternion. */
+declare const QUAT_IDENTITY: Quat;
+/** Hamilton product `q1 * q2`. Apply to a vector as `q v q⁻¹`. Right-
+ *  multiplication composes the second rotation in the LOCAL frame of the
+ *  first — that's the property the gizmo relies on for local-axis drag. */
+declare function quatMultiply(q1: Quat, q2: Quat): Quat;
+/** Quaternion from axis-angle. `axis` must be unit length (caller's
+ *  responsibility — typically a CSS basis vector). `angleRad` in radians. */
+declare function quatFromAxisAngle(axis: Vec3, angleRad: number): Quat;
+/** Quaternion from Euler XYZ degrees — the order CSS `rotateX rotateY
+ *  rotateZ` applies. Matches the composed matrix `Rx(rx)·Ry(ry)·Rz(rz)`. */
+declare function quatFromEulerXYZ(eulerDeg: Vec3): Quat;
+/** Euler XYZ degrees from a quaternion — inverse of `quatFromEulerXYZ`.
+ *  Handles gimbal lock (|ry| → 90°) by collapsing rz onto rx. The output
+ *  matches the convention used by CSS `rotateX rotateY rotateZ` so it can
+ *  be written straight back into a PolyMesh rotation prop. */
+declare function eulerXYZFromQuat(q: Quat): 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?: GlyphcssDirectionalLight, ambient?: GlyphcssAmbientLight): 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[];
+
+/**
+ * dedupeOverlappingPolygons — drop polygons whose 3D footprint coincides
+ * with another polygon's, within an epsilon tolerance.
+ *
+ * Why this exists: modelers (and importers) often emit redundant geometry
+ * for the same visible surface — a doubled face on a wall, an inner shell
+ * coincident with an outer shell, or two N-gons that fan-triangulate the
+ * same region. Each duplicate is a real `<i>` element at render time:
+ * it costs DOM, Lambert math, atlas budget, AND it produces stacked
+ * shadow leaves that visibly multiply on the receiver (overlapping dark
+ * patches on the ground).
+ *
+ * This is a separate concern from `cullInteriorPolygons` (which removes
+ * polygons fully *enclosed* by other geometry, conservative against
+ * false positives) and from `mergePolygons` (which joins same-color
+ * coplanar polygons that share an edge). A polygon's exact twin
+ * doesn't share an edge with itself and isn't enclosed by anything —
+ * it slips through both passes.
+ *
+ * Algorithm:
+ *   1. Compute each polygon's plane (normal + signed offset along
+ *      normal) and centroid.
+ *   2. Bucket polygons by quantized plane key (rounded normal direction
+ *      with sign-folding so anti-parallel faces share a bucket, and
+ *      rounded distance from origin along the unsigned normal axis).
+ *      Polygons in different buckets cannot overlap.
+ *   3. Within each bucket, do an O(K²) pairwise check on at most K
+ *      polygons. Two polygons overlap if their 2D projections onto
+ *      the shared plane share a significant area fraction.
+ *   4. When a pair overlaps, drop one: prefer keeping the one whose
+ *      normal points *away* from the mesh centroid (the "outward"
+ *      face). For ties (truly identical orientation), keep the one
+ *      with greater 2D area.
+ *
+ * Runs once at parse time in the same pipeline as mergePolygons. Zero
+ * cost at runtime — once it returns the polygon array is final and the
+ * dedup logic never executes again.
+ */
+
+/** Tunable thresholds. Default values are conservative — only catch
+ *  duplicates that are visually identical surfaces (exact twins,
+ *  back-to-back winding flips, nested polys on the same plane).
+ *  Looser values are appropriate for shadow-casting purposes, where
+ *  any polygons whose projections land in the same place can share a
+ *  shadow without affecting the rendered model. */
+interface DedupeOverlappingPolygonsOptions {
+    /** Maximum 1 - |dot(n_a, n_b)| for normals to count as "parallel".
+     *  Default 1e-3 (strict — must be near-identical orientation).
+     *  Looser values (~5e-2 ≈ 18° off) treat near-parallel normals as
+     *  duplicates, useful for shadow dedup where small orientation
+     *  differences project to nearly the same shadow shape. */
+    normalTolerance?: number;
+    /** Maximum signed-distance difference between two polygons' plane
+     *  offsets (along their shared normal) to count as coplanar.
+     *  Default 0.05 (world units). Looser values treat distinct
+     *  parallel shells (e.g. an inner cavity wall behind an outer
+     *  wall) as shadow-duplicates. */
+    distanceTolerance?: number;
+    /** Minimum overlap fraction (max of A-in-B and B-in-A vertex
+     *  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;
+}
+/** Identify polygons that are duplicates within tolerance. Returns the
+ *  set of indices into the input array that should be dropped (the
+ *  losers of duplicate pairs). The "winner" of a pair is the polygon
+ *  whose normal faces away from the mesh centroid (outward), with
+ *  larger area as a tiebreaker.
+ *
+ *  Exposed for callers that want to act on the index set directly —
+ *  e.g. shadow casting can use a looser tolerance to skip shadow leaves
+ *  for redundant casters without removing them from the renderable
+ *  polygon set. */
+declare function findOverlappingPolygonDuplicates(input: Polygon[], options?: DedupeOverlappingPolygonsOptions): Set<number>;
+declare function dedupeOverlappingPolygons(input: Polygon[], options?: DedupeOverlappingPolygonsOptions): 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[];
+
+interface ApproximateMergeOptions {
+    maxAngleDeg?: number;
+    maxPlaneDisplacement?: number;
+    maxBoundaryDisplacement?: number;
+    isolatedPairs?: boolean;
+}
+interface OptimizeMeshPolygonsOptions {
+    /** Public quality/resolution intent. Defaults to "lossy". */
+    meshResolution?: MeshResolution;
+    /**
+     * Run the planar cover pass as an exact candidate for untextured coplanar
+     * 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[];
+
+/**
+ * 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[];
+
+declare const CAMERA_BACKFACE_CULL_EPS = 0.00001;
+declare const VOXEL_CAMERA_CULL_AXIS_EPS = 0.001;
+declare const VOXEL_CAMERA_CULL_NORMAL_LIMIT = 6;
+interface CameraCullRotation {
+    rotX: number;
+    rotY: number;
+    meshRotation?: Vec3;
+}
+interface CameraCullNormalGroup {
+    key: string;
+    normal: Vec3;
+}
+declare function polygonCssSurfaceNormal(polygon: Polygon): Vec3 | null;
+declare function cameraFacingDepth(normal: Vec3, rotation: CameraCullRotation): number;
+declare function normalFacesCamera(normal: Vec3, rotation: CameraCullRotation, depthThreshold?: number): boolean;
+declare function polygonFacesCamera(polygon: Polygon, rotation: CameraCullRotation, depthThreshold?: number): boolean;
+declare function cameraCullNormalKey(normal: Vec3): string;
+declare function cameraCullNormalGroups(normals: Iterable<Vec3 | null | undefined>): CameraCullNormalGroup[];
+declare function cameraCullNormalGroupsFromPolygons(polygons: readonly Polygon[]): CameraCullNormalGroup[];
+declare function isAxisAlignedSurfaceNormal(normal: Vec3, axisEpsilon?: number): boolean;
+declare function isVoxelCameraCullableNormalGroups(groups: readonly CameraCullNormalGroup[]): boolean;
+declare function cameraCullVisibleSignature(groups: readonly CameraCullNormalGroup[], rotation: CameraCullRotation, depthThreshold?: number): string;
+
+/**
+ * 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;
+    /** Emit the rectangular shaft polygons. Default `true`. Set `false` to
+     *  render just the pyramid head — used by transform-control gizmos to
+     *  declutter back-facing axes (only the head still identifies direction
+     *  while the shaft would visually overlap the front-facing arrow). */
+    shaft?: boolean;
+}
+/** 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[];
+
+/**
+ * One square quad covering the bounding box of a ring (annulus) in the
+ * plane perpendicular to a chosen axis. Used by `<PolyTransformControls
+ * mode="rotate">` together with a CSS `mask: radial-gradient(...)` to
+ * render the visible donut, replacing the segmented quad-strip approach
+ * of `ringPolygons` with a single DOM element per ring.
+ *
+ * The caller is responsible for applying the mask CSS and using a donut-
+ * shaped hit-test (the quad's bounding rect alone would over-hit the
+ * inner hole). The recommended setup is to set the CSS custom property
+ * `--ring-inner-ratio` on the mesh element so the mask scales with the
+ * caller's chosen thickness ratio.
+ */
+
+interface RingQuadPolygonsOptions {
+    /** World axis the ring is perpendicular to: 0=X, 1=Y, 2=Z. The quad
+     *  lies in the plane spanned by the other two axes. */
+    axis: 0 | 1 | 2;
+    /** Outer radius of the ring. The quad spans ±outerRadius in both
+     *  in-plane axes. */
+    outerRadius: number;
+    /** Fill color. */
+    color?: string;
+}
+/** Build a single 4-vertex polygon (a square) bounding the ring's outer
+ *  circle. CSS `mask` is expected to clip this to the donut shape at
+ *  render time. */
+declare function ringQuadPolygons(options: RingQuadPolygonsOptions): Polygon[];
+
+/**
+ * A flat quad on one of the three axis-aligned planes, offset diagonally
+ * along the two in-plane axes. Used as a planar drag handle in
+ * `<PolyTransformControls>` — clicking and dragging this handle moves the
+ * 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
+ * framework's PolyMesh equivalent for rendering.
+ */
+
+interface PlanePolygonsOptions {
+    /** Axis perpendicular to the plane: 0 = YZ plane, 1 = XZ plane,
+     *  2 = XY plane. The quad lies on the OTHER two axes. */
+    axis: 0 | 1 | 2;
+    /** Half-extent of the quad along each in-plane axis. Default `0.4`. */
+    size?: number;
+    /** Center of the quad along the two in-plane axes. Pass a single number
+     *  to use the same offset on both (positive places the handle in the
+     *  +A/+B corner). Pass `[offsetA, offsetB]` to control each
+     *  independently — sign flips move the handle to a different octant.
+     *  `A = (axis+1)%3`, `B = (axis+2)%3`. Default `size * 2`. */
+    offset?: number | [number, number];
+    /** Position along the perpendicular axis. Default `0` (on the plane). */
+    along?: number;
+    /** Fill color. */
+    color?: string;
+}
+/** Build the polygons for one axis-aligned planar drag handle. */
+declare function planePolygons(options: PlanePolygonsOptions): Polygon[];
+
+/**
+ * Geometry for a small solid-color octahedron — the marker shape used by
+ * `GlyphcssDirectionalLightHelper` 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;
+    };
+}
+
+/**
+ * GlyphcssAnimationMixer — three.js-shaped animation API for glyphcss.
+ *
+ * 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. `GlyphcssMeshHandle` from both
+ * the glyphcss vanilla API and the React/Vue frameworks satisfies this
+ * structurally — no import needed.
+ */
+interface GlyphcssAnimationTarget {
+    setPolygons(polygons: Polygon[]): void;
+}
+/**
+ * Per-clip playback action. Mirrors three.js `AnimationAction` method surface.
+ * All mutating methods return `this` for chaining.
+ */
+interface GlyphcssAnimationAction {
+    /** Start playing (sets weight=1, resets time if not already playing). */
+    play(): GlyphcssAnimationAction;
+    /** Stop playing and reset time to 0. */
+    stop(): GlyphcssAnimationAction;
+    /** Reset time to 0 without stopping. */
+    reset(): GlyphcssAnimationAction;
+    /** Fade weight from 0 to 1 over `durationSeconds`. */
+    fadeIn(durationSeconds: number): GlyphcssAnimationAction;
+    /** Fade weight from current to 0 over `durationSeconds`. */
+    fadeOut(durationSeconds: number): GlyphcssAnimationAction;
+    /**
+     * Cross-fade from this action to `target` over `durationSeconds`.
+     * Fades this out and target in simultaneously.
+     */
+    crossFadeTo(target: GlyphcssAnimationAction, durationSeconds: number): GlyphcssAnimationAction;
+    /**
+     * Cross-fade from `from` into this action over `durationSeconds`.
+     * Sugar for `from.fadeOut(d); this.fadeIn(d)`.
+     */
+    crossFadeFrom(from: GlyphcssAnimationAction, durationSeconds: number): GlyphcssAnimationAction;
+    /** Set loop mode and repetition count. */
+    setLoop(mode: LoopMode, repetitions: number): GlyphcssAnimationAction;
+    /** Override the effective time scale. */
+    setEffectiveTimeScale(scale: number): GlyphcssAnimationAction;
+    /** Override the effective weight. */
+    setEffectiveWeight(weight: number): GlyphcssAnimationAction;
+    /** 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 `GlyphcssAnimationAction`s against a single mesh target.
+ * Mirrors the three.js `AnimationMixer` API.
+ */
+interface GlyphcssAnimationMixer {
+    /**
+     * 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): GlyphcssAnimationAction;
+    /**
+     * Return an existing action without creating one. Returns null if the
+     * action hasn't been instantiated yet.
+     */
+    existingAction(clip: number | string): GlyphcssAnimationAction | 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 createGlyphcssAnimationMixer(root: GlyphcssAnimationTarget, controller: ParseAnimationController): GlyphcssAnimationMixer;
+
+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;
+    /**
+     * Mesh optimization intent. Defaults to "lossy"; set "lossless" to keep
+     * exact planar candidates only.
+     */
+    meshResolution?: MeshResolution;
+}
+declare function loadMesh(url: string, options?: LoadMeshOptions): Promise<ParseResult>;
+
+/**
+ * Perspective projection identical to RadiantHero's: `persp = 4 / (z + 3)`.
+ * Returns `[col, row, depth]` in grid space. `cellAspect` corrects for the
+ * non-square character cell (height / width).
+ */
+declare function project(v: Vec3, cols: number, rows: number, cellAspect: number, cx?: number, cy?: number, scale?: number): [number, number, number];
+
+/** Public: derive feature edges from a triangle list. `featureAngleDeg = 0` = all edges. */
+declare function trianglesToFeatureEdges(triangles: TextureTriangle[], featureAngleDeg?: number): WireframeEdge[];
+
+export { type ApproximateMergeOptions, type ArrowPolygonsOptions, type AutoRotateConfig, type AutoRotateOption, type AxesHelperOptions, BASE_TILE, CAMERA_BACKFACE_CULL_EPS, type CameraCullNormalGroup, type CameraCullRotation, type CameraHandle, type CameraState, type CameraStyleInput, type CharRamp, type CoverPlanarPolygonsOptions, type CullInteriorOptions, DEFAULT_CAMERA_STATE, DEFAULT_PROJECTION, type DedupeOverlappingPolygonsOptions, type EdgeWeight, type GltfParseOptions, type GlyphcssAmbientLight, type GlyphcssAnimationAction, type ParseAnimationClip as GlyphcssAnimationClip, type GlyphcssAnimationMixer, type GlyphcssAnimationTarget, type GlyphcssDirectionalLight, type GridSize, type Hotspot, type HotspotCell, type LoadMeshOptions, type LoopMode, LoopOnce, LoopPingPong, LoopRepeat, type MeshResolution, type MtlParseResult, type NormalizeResult, type ObjParseOptions, type OctahedronPolygonsOptions, type OptimizeMeshPolygonsOptions, type ParseAnimationClip, type ParseAnimationController, type ParseResult, type ParsedColor, type PlanePolygonsOptions, type Polygon, type PolygonFace, QUAT_IDENTITY, type Quat, type RenderMode, type RingPolygonsOptions, type RingQuadPolygonsOptions, type SceneBbox, type SceneContext, type SceneContextBuildArgs, type SceneContextBuildResult, type SolidTextureSampleOptions, type TextureTriangle, VOXEL_CAMERA_CULL_AXIS_EPS, VOXEL_CAMERA_CULL_NORMAL_LIMIT, type Vec2, type Vec3, type VoxParseOptions, type WireframeEdge, arrowPolygons, axesHelperPolygons, bakeSolidTextureSampledPolygons, bakeSolidTextureSamples, buildSceneContext, cameraCullNormalGroups, cameraCullNormalGroupsFromPolygons, cameraCullNormalKey, cameraCullVisibleSignature, cameraFacingDepth, clampChannel, computeSceneBbox, computeShapeLighting, coverPlanarPolygons, createGlyphcssAnimationMixer, createIsometricCamera, 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, project, quatFromAxisAngle, quatFromEulerXYZ, quatMultiply, ringPolygons, ringQuadPolygons, rotateVec3, shadeColor, trianglesToFeatureEdges };