@glyphcss/core 0.0.3 → 0.0.5

package/dist/index.d.cts

@@ -28,6 +28,8 @@ interface TextureTriangle {
     uvs: [Vec2, Vec2, Vec2];
     /** Hex color string (`#rrggbb`) propagated from source model material. */
     color?: string;
+    /** Texture URL carried for renderers that sample textures per cell (UV-mapped). */
+    texture?: string;
 }
 /**
  * Directional light — simulates a single distant source (sun, key light).
@@ -77,6 +79,13 @@ interface PolyMaterial {
      *  reference. */
     key?: string;
 }
+/** Texture sampler wrap mode for one axis (glTF sampler convention). */
+type PolyTextureWrapMode = "repeat" | "clamp-to-edge" | "mirrored-repeat";
+/** Per-axis texture wrap modes (see {@link Polygon.textureWrap}). */
+interface PolyTextureWrap {
+    s: PolyTextureWrapMode;
+    t: PolyTextureWrapMode;
+}
 /**
  * The single polygon type for glyphcss. N coplanar vertices in 3D space,
  * CCW winding from outside. No bbox field, no shape discriminator, no
@@ -104,6 +113,14 @@ interface Polygon {
      * polygon canvas rasterization). Falls back to the atlas path otherwise.
      */
     material?: PolyMaterial;
+    /**
+     * Texture sampler wrap mode for UVs outside [0, 1]. glTF imports and the
+     * fonts extruder preserve sampler.wrapS / wrapT here so a renderer that
+     * tiles textures can repeat the UVs. The ASCII renderer bakes textures to a
+     * flat per-face color and ignores this; unset keeps single-image behavior.
+     * @internal
+     */
+    textureWrap?: PolyTextureWrap;
     /**
      * Per-vertex UV coords (0..1, OBJ convention with v=0 at bottom).
      * Length MUST equal vertices.length when set; mismatched UVs are
@@ -1755,7 +1772,7 @@ declare function resolveGeometry(name: GlyphGeometryName, opts?: GlyphGeometryOp
 
 /**
  * Unified parser return type. All polygon-emitting parsers (parseObj,
- * parseGltf, the loadMesh dispatcher) return this exact shape.
+ * parseGltf, parseVox, parseStl, the loadMesh dispatcher) return this exact shape.
  *
  * The asymmetric helper `parseMtl` returns its own `MtlParseResult` (it
  * emits materials, not polygons) — see parseMtl.ts for the rationale.
@@ -1765,6 +1782,26 @@ declare function resolveGeometry(name: GlyphGeometryName, opts?: GlyphGeometryOp
  * is empty (e.g. `parseObj`, where it's a no-op).
  */
 
+interface ParseStlTopology {
+    componentCount: number;
+    repairedTriangleCount: number;
+    outwardComponentCount: number;
+    suppliedNormalComponentCount: number;
+    inconsistentSharedEdgeCount: number;
+    nonManifoldSharedEdgeCount: number;
+}
+interface ParseStlColor {
+    format: "magics";
+    defaultColor: string;
+    alpha: number;
+    coloredTriangleCount: number;
+    defaultColorTriangleCount: number;
+}
+interface ParseStlSolid {
+    name: string;
+    start: number;
+    count: number;
+}
 interface ParseAnimationClip {
     /** Stable numeric index in the source file's animation array. */
     index: number;
@@ -1818,6 +1855,16 @@ interface ParseResult {
         animations?: ParseAnimationClip[];
         /** Source file size in bytes (for diagnostics). */
         sourceBytes?: number;
+        /** Voxel count for `.vox` sources. */
+        voxelCount?: number;
+        /** Printable binary STL header, trimmed. */
+        stlHeader?: string;
+        /** Binary STL color metadata when a supported color extension is present. */
+        stlColor?: ParseStlColor;
+        /** Consecutive ASCII `solid` groups after parse/filtering. */
+        stlSolids?: ParseStlSolid[];
+        /** STL winding/connectivity diagnostics. */
+        stlTopology?: ParseStlTopology;
     };
 }
 
@@ -2048,8 +2095,33 @@ interface SolidTextureSampleOptions {
     /** Skip decoding very large textures for this optimization. Default 16 MP. */
     maxTexturePixels?: number;
 }
+interface SampledColor {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+interface TextureSampler {
+    width: number;
+    height: number;
+    data: ArrayLike<number>;
+    lowDetail: boolean;
+}
 declare function bakeSolidTextureSampledPolygons(polygons: Polygon[], options?: SolidTextureSampleOptions): Promise<Polygon[]>;
 declare function bakeSolidTextureSamples(result: ParseResult, options?: SolidTextureSampleOptions): Promise<ParseResult>;
+/**
+ * Decode every distinct texture referenced by `polygons` into a pixel sampler,
+ * for renderers that sample textures at draw time (per-cell UV mapping) instead
+ * of baking each face to one flat color. Keyed by texture URL. Empty map when no
+ * browser image/canvas env is available (SSR / tests).
+ */
+declare function buildTextureSamplers(polygons: Polygon[], options?: {
+    maxTexturePixels?: number;
+}): Promise<Map<string, TextureSampler>>;
+/** Sample a decoded texture at UV (0..1, OBJ convention with v=0 at bottom). */
+declare function sampleTexel(sampler: TextureSampler, u: number, v: number): SampledColor | null;
+/** The texture URL a polygon renders with (`material.texture` takes precedence). */
+declare function polygonTexture(polygon: Polygon): string | undefined;
 
 interface VoxParseOptions {
     /**
@@ -2066,6 +2138,22 @@ interface VoxParseOptions {
 }
 declare function parseVox(buffer: ArrayBuffer, options?: VoxParseOptions): ParseResult;
 
+interface StlParseOptions {
+    /** Largest mesh extent (units). Mesh is uniformly scaled to fit. Default: 60. */
+    targetSize?: number;
+    /** Padding offset added after scaling. Default: 1. */
+    gridShift?: number;
+    /** Solid color assigned to every STL triangle. Default: "#888888". */
+    defaultColor?: string;
+    /**
+     * Which axis is "up" in the source mesh.
+     *  - "z" (default): identity axes, matching common CAD/3D-print STL exports.
+     *  - "y": cyclic permutation (x,y,z) → (z,x,y), matching OBJ/glTF's +Y-up path.
+     */
+    upAxis?: "z" | "y";
+}
+declare function parseStl(source: ArrayBuffer | Uint8Array | string, options?: StlParseOptions): ParseResult;
+
 /**
  * loadMesh — high-level fetch+parse dispatcher. Picks the parser by file
  * extension, fetches the URL, runs the parser, returns the unified
@@ -2076,11 +2164,12 @@ declare function parseVox(buffer: ArrayBuffer, options?: VoxParseOptions): Parse
  *   - `.glb`  → ArrayBuffer fetch + `parseGltf`
  *   - `.gltf` → ArrayBuffer fetch + `parseGltf` (caller may pass `baseUrl`)
  *   - `.vox`  → ArrayBuffer fetch + `parseVox`
+ *   - `.stl`  → ArrayBuffer fetch + `parseStl`
  *
  * `.mtl` is rejected — it's a material file, not a mesh. Use `parseMtl`
  * directly if you want to read materials.
  *
- * Other extensions throw. Future formats (STL, PLY) plug in here.
+ * Other extensions throw. Future formats (PLY, 3MF) plug in here.
  */
 
 interface LoadMeshOptions {
@@ -2104,6 +2193,8 @@ interface LoadMeshOptions {
     gltfOptions?: GltfParseOptions;
     /** Forwarded to `parseVox`. */
     voxOptions?: VoxParseOptions;
+    /** Forwarded to `parseStl`. */
+    stlOptions?: StlParseOptions;
     /**
      * Converts texture-backed faces whose UV samples are a uniform color into
      * solid-color polygons before culling/merging. This avoids atlas sprites for
@@ -2128,4 +2219,4 @@ declare function project(v: Vec3, cols: number, rows: number, cellAspect: number
 /** Public: derive feature edges from a triangle list. `featureAngleDeg = 0` = all edges. */
 declare function trianglesToFeatureEdges(triangles: TextureTriangle[], featureAngleDeg?: number): WireframeEdge[];
 
-export { type AntiprismPolygonsOptions, type ApproximateMergeOptions, type ArrowPolygonsOptions, type AutoRotateConfig, type AutoRotateOption, type AxesHelperOptions, BASE_TILE, type BipyramidPolygonsOptions, CAMERA_BACKFACE_CULL_EPS, type CameraCullNormalGroup, type CameraCullRotation, type CameraHandle, type CameraState, type CameraStyleInput, type CharRamp, type ConePolygonsOptions, type CoverPlanarPolygonsOptions, type CubePolygonsOptions, type CuboctahedronPolygonsOptions, type CullInteriorOptions, type CylinderPolygonsOptions, DEFAULT_CAMERA_STATE, DEFAULT_PROJECTION, type DedupeOverlappingPolygonsOptions, type DeltoidalHexecontahedronPolygonsOptions, type DeltoidalIcositetrahedronPolygonsOptions, type DisdyakisDodecahedronPolygonsOptions, type DisdyakisTriacontahedronPolygonsOptions, type DodecahedronPolygonsOptions, type EdgeWeight, type GltfParseOptions, type GlyphAmbientLight, type GlyphAnimationAction, type ParseAnimationClip as GlyphAnimationClip, type GlyphAnimationMixer, type GlyphAnimationTarget, type GlyphDirectionalLight, type GlyphGeometryName, type GlyphGeometryOptions, type GreatDodecahedronPolygonsOptions, type GreatIcosahedronPolygonsOptions, type GreatStellatedDodecahedronPolygonsOptions, type GridSize, type Hotspot, type HotspotCell, type IcosahedronPolygonsOptions, type IcosidodecahedronPolygonsOptions, 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 PentagonalHexecontahedronPolygonsOptions, type PentagonalIcositetrahedronPolygonsOptions, type PentakisDodecahedronPolygonsOptions, type PlanePolygonsOptions, type Polygon, type PolygonFace, type PrismPolygonsOptions, type PyramidPolygonsOptions, QUAT_IDENTITY, type Quat, type RenderMode, type RhombicDodecahedronPolygonsOptions, type RhombicTriacontahedronPolygonsOptions, type RhombicosidodecahedronPolygonsOptions, type RhombicuboctahedronPolygonsOptions, type RingPolygonsOptions, type RingQuadPolygonsOptions, type SceneBbox, type SceneContext, type SceneContextBuildArgs, type SceneContextBuildResult, type SmallStellatedDodecahedronPolygonsOptions, type SnubCubePolygonsOptions, type SnubDodecahedronPolygonsOptions, type SolidTextureSampleOptions, type SpherePolygonsOptions, type TetrahedronPolygonsOptions, type TetrakisHexahedronPolygonsOptions, type TextureTriangle, type TorusPolygonsOptions, type TrapezohedronPolygonsOptions, type TriakisIcosahedronPolygonsOptions, type TriakisOctahedronPolygonsOptions, type TriakisTetrahedronPolygonsOptions, type TruncatedCubePolygonsOptions, type TruncatedCuboctahedronPolygonsOptions, type TruncatedDodecahedronPolygonsOptions, type TruncatedIcosahedronPolygonsOptions, type TruncatedIcosidodecahedronPolygonsOptions, type TruncatedOctahedronPolygonsOptions, type TruncatedTetrahedronPolygonsOptions, VOXEL_CAMERA_CULL_AXIS_EPS, VOXEL_CAMERA_CULL_NORMAL_LIMIT, type Vec2, type Vec3, type VoxParseOptions, type WireframeEdge, antiprismPolygons, arrowPolygons, axesHelperPolygons, bakeSolidTextureSampledPolygons, bakeSolidTextureSamples, bipyramidPolygons, buildSceneContext, cameraCullNormalGroups, cameraCullNormalGroupsFromPolygons, cameraCullNormalKey, cameraCullVisibleSignature, cameraFacingDepth, clampChannel, computeSceneBbox, computeShapeLighting, conePolygons, coverPlanarPolygons, createGlyphAnimationMixer, createIsometricCamera, cubePolygons, cuboctahedronPolygons, cullInteriorPolygons, cylinderPolygons, dedupeOverlappingPolygons, deltoidalHexecontahedronPolygons, deltoidalIcositetrahedronPolygons, disdyakisDodecahedronPolygons, disdyakisTriacontahedronPolygons, dodecahedronPolygons, eulerXYZFromQuat, findOverlappingPolygonDuplicates, formatColor, greatDodecahedronPolygons, greatIcosahedronPolygons, greatStellatedDodecahedronPolygons, icosahedronPolygons, icosidodecahedronPolygons, inverseRotateVec3, isAxisAlignedSurfaceNormal, isVoxelCameraCullableNormalGroups, loadMesh, mergePolygons, normalFacesCamera, normalizeInvertMultiplier, normalizePolygons, octahedronPolygons, optimizeMeshPolygons, parseColor, parseGltf, parseHexColor, parseMtl, parseObj, parsePureColor, parseRgbColor, parseVox, pentagonalHexecontahedronPolygons, pentagonalIcositetrahedronPolygons, pentakisDodecahedronPolygons, planePolygons, polygonCssSurfaceNormal, polygonFaces, polygonFacesCamera, prismPolygons, project, pyramidPolygons, quatFromAxisAngle, quatFromEulerXYZ, quatMultiply, resolveGeometry, rhombicDodecahedronPolygons, rhombicTriacontahedronPolygons, rhombicosidodecahedronPolygons, rhombicuboctahedronPolygons, ringPolygons, ringQuadPolygons, rotateVec3, shadeColor, smallStellatedDodecahedronPolygons, snubCubePolygons, snubDodecahedronPolygons, spherePolygons, tetrahedronPolygons, tetrakisHexahedronPolygons, torusPolygons, trapezohedronPolygons, triakisIcosahedronPolygons, triakisOctahedronPolygons, triakisTetrahedronPolygons, trianglesToFeatureEdges, truncatedCubePolygons, truncatedCuboctahedronPolygons, truncatedDodecahedronPolygons, truncatedIcosahedronPolygons, truncatedIcosidodecahedronPolygons, truncatedOctahedronPolygons, truncatedTetrahedronPolygons };
+export { type AntiprismPolygonsOptions, type ApproximateMergeOptions, type ArrowPolygonsOptions, type AutoRotateConfig, type AutoRotateOption, type AxesHelperOptions, BASE_TILE, type BipyramidPolygonsOptions, CAMERA_BACKFACE_CULL_EPS, type CameraCullNormalGroup, type CameraCullRotation, type CameraHandle, type CameraState, type CameraStyleInput, type CharRamp, type ConePolygonsOptions, type CoverPlanarPolygonsOptions, type CubePolygonsOptions, type CuboctahedronPolygonsOptions, type CullInteriorOptions, type CylinderPolygonsOptions, DEFAULT_CAMERA_STATE, DEFAULT_PROJECTION, type DedupeOverlappingPolygonsOptions, type DeltoidalHexecontahedronPolygonsOptions, type DeltoidalIcositetrahedronPolygonsOptions, type DisdyakisDodecahedronPolygonsOptions, type DisdyakisTriacontahedronPolygonsOptions, type DodecahedronPolygonsOptions, type EdgeWeight, type GltfParseOptions, type GlyphAmbientLight, type GlyphAnimationAction, type ParseAnimationClip as GlyphAnimationClip, type GlyphAnimationMixer, type GlyphAnimationTarget, type GlyphDirectionalLight, type GlyphGeometryName, type GlyphGeometryOptions, type GreatDodecahedronPolygonsOptions, type GreatIcosahedronPolygonsOptions, type GreatStellatedDodecahedronPolygonsOptions, type GridSize, type Hotspot, type HotspotCell, type IcosahedronPolygonsOptions, type IcosidodecahedronPolygonsOptions, 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 ParseStlColor, type ParseStlSolid, type ParseStlTopology, type ParsedColor, type PentagonalHexecontahedronPolygonsOptions, type PentagonalIcositetrahedronPolygonsOptions, type PentakisDodecahedronPolygonsOptions, type PlanePolygonsOptions, type PolyTextureWrap, type PolyTextureWrapMode, type Polygon, type PolygonFace, type PrismPolygonsOptions, type PyramidPolygonsOptions, QUAT_IDENTITY, type Quat, type RenderMode, type RhombicDodecahedronPolygonsOptions, type RhombicTriacontahedronPolygonsOptions, type RhombicosidodecahedronPolygonsOptions, type RhombicuboctahedronPolygonsOptions, type RingPolygonsOptions, type RingQuadPolygonsOptions, type SampledColor, type SceneBbox, type SceneContext, type SceneContextBuildArgs, type SceneContextBuildResult, type SmallStellatedDodecahedronPolygonsOptions, type SnubCubePolygonsOptions, type SnubDodecahedronPolygonsOptions, type SolidTextureSampleOptions, type SpherePolygonsOptions, type StlParseOptions, type TetrahedronPolygonsOptions, type TetrakisHexahedronPolygonsOptions, type TextureSampler, type TextureTriangle, type TorusPolygonsOptions, type TrapezohedronPolygonsOptions, type TriakisIcosahedronPolygonsOptions, type TriakisOctahedronPolygonsOptions, type TriakisTetrahedronPolygonsOptions, type TruncatedCubePolygonsOptions, type TruncatedCuboctahedronPolygonsOptions, type TruncatedDodecahedronPolygonsOptions, type TruncatedIcosahedronPolygonsOptions, type TruncatedIcosidodecahedronPolygonsOptions, type TruncatedOctahedronPolygonsOptions, type TruncatedTetrahedronPolygonsOptions, VOXEL_CAMERA_CULL_AXIS_EPS, VOXEL_CAMERA_CULL_NORMAL_LIMIT, type Vec2, type Vec3, type VoxParseOptions, type WireframeEdge, antiprismPolygons, arrowPolygons, axesHelperPolygons, bakeSolidTextureSampledPolygons, bakeSolidTextureSamples, bipyramidPolygons, buildSceneContext, buildTextureSamplers, cameraCullNormalGroups, cameraCullNormalGroupsFromPolygons, cameraCullNormalKey, cameraCullVisibleSignature, cameraFacingDepth, clampChannel, computeSceneBbox, computeShapeLighting, conePolygons, coverPlanarPolygons, createGlyphAnimationMixer, createIsometricCamera, cubePolygons, cuboctahedronPolygons, cullInteriorPolygons, cylinderPolygons, dedupeOverlappingPolygons, deltoidalHexecontahedronPolygons, deltoidalIcositetrahedronPolygons, disdyakisDodecahedronPolygons, disdyakisTriacontahedronPolygons, dodecahedronPolygons, eulerXYZFromQuat, findOverlappingPolygonDuplicates, formatColor, greatDodecahedronPolygons, greatIcosahedronPolygons, greatStellatedDodecahedronPolygons, icosahedronPolygons, icosidodecahedronPolygons, inverseRotateVec3, isAxisAlignedSurfaceNormal, isVoxelCameraCullableNormalGroups, loadMesh, mergePolygons, normalFacesCamera, normalizeInvertMultiplier, normalizePolygons, octahedronPolygons, optimizeMeshPolygons, parseColor, parseGltf, parseHexColor, parseMtl, parseObj, parsePureColor, parseRgbColor, parseStl, parseVox, pentagonalHexecontahedronPolygons, pentagonalIcositetrahedronPolygons, pentakisDodecahedronPolygons, planePolygons, polygonCssSurfaceNormal, polygonFaces, polygonFacesCamera, polygonTexture, prismPolygons, project, pyramidPolygons, quatFromAxisAngle, quatFromEulerXYZ, quatMultiply, resolveGeometry, rhombicDodecahedronPolygons, rhombicTriacontahedronPolygons, rhombicosidodecahedronPolygons, rhombicuboctahedronPolygons, ringPolygons, ringQuadPolygons, rotateVec3, sampleTexel, shadeColor, smallStellatedDodecahedronPolygons, snubCubePolygons, snubDodecahedronPolygons, spherePolygons, tetrahedronPolygons, tetrakisHexahedronPolygons, torusPolygons, trapezohedronPolygons, triakisIcosahedronPolygons, triakisOctahedronPolygons, triakisTetrahedronPolygons, trianglesToFeatureEdges, truncatedCubePolygons, truncatedCuboctahedronPolygons, truncatedDodecahedronPolygons, truncatedIcosahedronPolygons, truncatedIcosidodecahedronPolygons, truncatedOctahedronPolygons, truncatedTetrahedronPolygons };

package/dist/index.d.ts

@@ -28,6 +28,8 @@ interface TextureTriangle {
     uvs: [Vec2, Vec2, Vec2];
     /** Hex color string (`#rrggbb`) propagated from source model material. */
     color?: string;
+    /** Texture URL carried for renderers that sample textures per cell (UV-mapped). */
+    texture?: string;
 }
 /**
  * Directional light — simulates a single distant source (sun, key light).
@@ -77,6 +79,13 @@ interface PolyMaterial {
      *  reference. */
     key?: string;
 }
+/** Texture sampler wrap mode for one axis (glTF sampler convention). */
+type PolyTextureWrapMode = "repeat" | "clamp-to-edge" | "mirrored-repeat";
+/** Per-axis texture wrap modes (see {@link Polygon.textureWrap}). */
+interface PolyTextureWrap {
+    s: PolyTextureWrapMode;
+    t: PolyTextureWrapMode;
+}
 /**
  * The single polygon type for glyphcss. N coplanar vertices in 3D space,
  * CCW winding from outside. No bbox field, no shape discriminator, no
@@ -104,6 +113,14 @@ interface Polygon {
      * polygon canvas rasterization). Falls back to the atlas path otherwise.
      */
     material?: PolyMaterial;
+    /**
+     * Texture sampler wrap mode for UVs outside [0, 1]. glTF imports and the
+     * fonts extruder preserve sampler.wrapS / wrapT here so a renderer that
+     * tiles textures can repeat the UVs. The ASCII renderer bakes textures to a
+     * flat per-face color and ignores this; unset keeps single-image behavior.
+     * @internal
+     */
+    textureWrap?: PolyTextureWrap;
     /**
      * Per-vertex UV coords (0..1, OBJ convention with v=0 at bottom).
      * Length MUST equal vertices.length when set; mismatched UVs are
@@ -1755,7 +1772,7 @@ declare function resolveGeometry(name: GlyphGeometryName, opts?: GlyphGeometryOp
 
 /**
  * Unified parser return type. All polygon-emitting parsers (parseObj,
- * parseGltf, the loadMesh dispatcher) return this exact shape.
+ * parseGltf, parseVox, parseStl, the loadMesh dispatcher) return this exact shape.
  *
  * The asymmetric helper `parseMtl` returns its own `MtlParseResult` (it
  * emits materials, not polygons) — see parseMtl.ts for the rationale.
@@ -1765,6 +1782,26 @@ declare function resolveGeometry(name: GlyphGeometryName, opts?: GlyphGeometryOp
  * is empty (e.g. `parseObj`, where it's a no-op).
  */
 
+interface ParseStlTopology {
+    componentCount: number;
+    repairedTriangleCount: number;
+    outwardComponentCount: number;
+    suppliedNormalComponentCount: number;
+    inconsistentSharedEdgeCount: number;
+    nonManifoldSharedEdgeCount: number;
+}
+interface ParseStlColor {
+    format: "magics";
+    defaultColor: string;
+    alpha: number;
+    coloredTriangleCount: number;
+    defaultColorTriangleCount: number;
+}
+interface ParseStlSolid {
+    name: string;
+    start: number;
+    count: number;
+}
 interface ParseAnimationClip {
     /** Stable numeric index in the source file's animation array. */
     index: number;
@@ -1818,6 +1855,16 @@ interface ParseResult {
         animations?: ParseAnimationClip[];
         /** Source file size in bytes (for diagnostics). */
         sourceBytes?: number;
+        /** Voxel count for `.vox` sources. */
+        voxelCount?: number;
+        /** Printable binary STL header, trimmed. */
+        stlHeader?: string;
+        /** Binary STL color metadata when a supported color extension is present. */
+        stlColor?: ParseStlColor;
+        /** Consecutive ASCII `solid` groups after parse/filtering. */
+        stlSolids?: ParseStlSolid[];
+        /** STL winding/connectivity diagnostics. */
+        stlTopology?: ParseStlTopology;
     };
 }
 
@@ -2048,8 +2095,33 @@ interface SolidTextureSampleOptions {
     /** Skip decoding very large textures for this optimization. Default 16 MP. */
     maxTexturePixels?: number;
 }
+interface SampledColor {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+interface TextureSampler {
+    width: number;
+    height: number;
+    data: ArrayLike<number>;
+    lowDetail: boolean;
+}
 declare function bakeSolidTextureSampledPolygons(polygons: Polygon[], options?: SolidTextureSampleOptions): Promise<Polygon[]>;
 declare function bakeSolidTextureSamples(result: ParseResult, options?: SolidTextureSampleOptions): Promise<ParseResult>;
+/**
+ * Decode every distinct texture referenced by `polygons` into a pixel sampler,
+ * for renderers that sample textures at draw time (per-cell UV mapping) instead
+ * of baking each face to one flat color. Keyed by texture URL. Empty map when no
+ * browser image/canvas env is available (SSR / tests).
+ */
+declare function buildTextureSamplers(polygons: Polygon[], options?: {
+    maxTexturePixels?: number;
+}): Promise<Map<string, TextureSampler>>;
+/** Sample a decoded texture at UV (0..1, OBJ convention with v=0 at bottom). */
+declare function sampleTexel(sampler: TextureSampler, u: number, v: number): SampledColor | null;
+/** The texture URL a polygon renders with (`material.texture` takes precedence). */
+declare function polygonTexture(polygon: Polygon): string | undefined;
 
 interface VoxParseOptions {
     /**
@@ -2066,6 +2138,22 @@ interface VoxParseOptions {
 }
 declare function parseVox(buffer: ArrayBuffer, options?: VoxParseOptions): ParseResult;
 
+interface StlParseOptions {
+    /** Largest mesh extent (units). Mesh is uniformly scaled to fit. Default: 60. */
+    targetSize?: number;
+    /** Padding offset added after scaling. Default: 1. */
+    gridShift?: number;
+    /** Solid color assigned to every STL triangle. Default: "#888888". */
+    defaultColor?: string;
+    /**
+     * Which axis is "up" in the source mesh.
+     *  - "z" (default): identity axes, matching common CAD/3D-print STL exports.
+     *  - "y": cyclic permutation (x,y,z) → (z,x,y), matching OBJ/glTF's +Y-up path.
+     */
+    upAxis?: "z" | "y";
+}
+declare function parseStl(source: ArrayBuffer | Uint8Array | string, options?: StlParseOptions): ParseResult;
+
 /**
  * loadMesh — high-level fetch+parse dispatcher. Picks the parser by file
  * extension, fetches the URL, runs the parser, returns the unified
@@ -2076,11 +2164,12 @@ declare function parseVox(buffer: ArrayBuffer, options?: VoxParseOptions): Parse
  *   - `.glb`  → ArrayBuffer fetch + `parseGltf`
  *   - `.gltf` → ArrayBuffer fetch + `parseGltf` (caller may pass `baseUrl`)
  *   - `.vox`  → ArrayBuffer fetch + `parseVox`
+ *   - `.stl`  → ArrayBuffer fetch + `parseStl`
  *
  * `.mtl` is rejected — it's a material file, not a mesh. Use `parseMtl`
  * directly if you want to read materials.
  *
- * Other extensions throw. Future formats (STL, PLY) plug in here.
+ * Other extensions throw. Future formats (PLY, 3MF) plug in here.
  */
 
 interface LoadMeshOptions {
@@ -2104,6 +2193,8 @@ interface LoadMeshOptions {
     gltfOptions?: GltfParseOptions;
     /** Forwarded to `parseVox`. */
     voxOptions?: VoxParseOptions;
+    /** Forwarded to `parseStl`. */
+    stlOptions?: StlParseOptions;
     /**
      * Converts texture-backed faces whose UV samples are a uniform color into
      * solid-color polygons before culling/merging. This avoids atlas sprites for
@@ -2128,4 +2219,4 @@ declare function project(v: Vec3, cols: number, rows: number, cellAspect: number
 /** Public: derive feature edges from a triangle list. `featureAngleDeg = 0` = all edges. */
 declare function trianglesToFeatureEdges(triangles: TextureTriangle[], featureAngleDeg?: number): WireframeEdge[];
 
-export { type AntiprismPolygonsOptions, type ApproximateMergeOptions, type ArrowPolygonsOptions, type AutoRotateConfig, type AutoRotateOption, type AxesHelperOptions, BASE_TILE, type BipyramidPolygonsOptions, CAMERA_BACKFACE_CULL_EPS, type CameraCullNormalGroup, type CameraCullRotation, type CameraHandle, type CameraState, type CameraStyleInput, type CharRamp, type ConePolygonsOptions, type CoverPlanarPolygonsOptions, type CubePolygonsOptions, type CuboctahedronPolygonsOptions, type CullInteriorOptions, type CylinderPolygonsOptions, DEFAULT_CAMERA_STATE, DEFAULT_PROJECTION, type DedupeOverlappingPolygonsOptions, type DeltoidalHexecontahedronPolygonsOptions, type DeltoidalIcositetrahedronPolygonsOptions, type DisdyakisDodecahedronPolygonsOptions, type DisdyakisTriacontahedronPolygonsOptions, type DodecahedronPolygonsOptions, type EdgeWeight, type GltfParseOptions, type GlyphAmbientLight, type GlyphAnimationAction, type ParseAnimationClip as GlyphAnimationClip, type GlyphAnimationMixer, type GlyphAnimationTarget, type GlyphDirectionalLight, type GlyphGeometryName, type GlyphGeometryOptions, type GreatDodecahedronPolygonsOptions, type GreatIcosahedronPolygonsOptions, type GreatStellatedDodecahedronPolygonsOptions, type GridSize, type Hotspot, type HotspotCell, type IcosahedronPolygonsOptions, type IcosidodecahedronPolygonsOptions, 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 PentagonalHexecontahedronPolygonsOptions, type PentagonalIcositetrahedronPolygonsOptions, type PentakisDodecahedronPolygonsOptions, type PlanePolygonsOptions, type Polygon, type PolygonFace, type PrismPolygonsOptions, type PyramidPolygonsOptions, QUAT_IDENTITY, type Quat, type RenderMode, type RhombicDodecahedronPolygonsOptions, type RhombicTriacontahedronPolygonsOptions, type RhombicosidodecahedronPolygonsOptions, type RhombicuboctahedronPolygonsOptions, type RingPolygonsOptions, type RingQuadPolygonsOptions, type SceneBbox, type SceneContext, type SceneContextBuildArgs, type SceneContextBuildResult, type SmallStellatedDodecahedronPolygonsOptions, type SnubCubePolygonsOptions, type SnubDodecahedronPolygonsOptions, type SolidTextureSampleOptions, type SpherePolygonsOptions, type TetrahedronPolygonsOptions, type TetrakisHexahedronPolygonsOptions, type TextureTriangle, type TorusPolygonsOptions, type TrapezohedronPolygonsOptions, type TriakisIcosahedronPolygonsOptions, type TriakisOctahedronPolygonsOptions, type TriakisTetrahedronPolygonsOptions, type TruncatedCubePolygonsOptions, type TruncatedCuboctahedronPolygonsOptions, type TruncatedDodecahedronPolygonsOptions, type TruncatedIcosahedronPolygonsOptions, type TruncatedIcosidodecahedronPolygonsOptions, type TruncatedOctahedronPolygonsOptions, type TruncatedTetrahedronPolygonsOptions, VOXEL_CAMERA_CULL_AXIS_EPS, VOXEL_CAMERA_CULL_NORMAL_LIMIT, type Vec2, type Vec3, type VoxParseOptions, type WireframeEdge, antiprismPolygons, arrowPolygons, axesHelperPolygons, bakeSolidTextureSampledPolygons, bakeSolidTextureSamples, bipyramidPolygons, buildSceneContext, cameraCullNormalGroups, cameraCullNormalGroupsFromPolygons, cameraCullNormalKey, cameraCullVisibleSignature, cameraFacingDepth, clampChannel, computeSceneBbox, computeShapeLighting, conePolygons, coverPlanarPolygons, createGlyphAnimationMixer, createIsometricCamera, cubePolygons, cuboctahedronPolygons, cullInteriorPolygons, cylinderPolygons, dedupeOverlappingPolygons, deltoidalHexecontahedronPolygons, deltoidalIcositetrahedronPolygons, disdyakisDodecahedronPolygons, disdyakisTriacontahedronPolygons, dodecahedronPolygons, eulerXYZFromQuat, findOverlappingPolygonDuplicates, formatColor, greatDodecahedronPolygons, greatIcosahedronPolygons, greatStellatedDodecahedronPolygons, icosahedronPolygons, icosidodecahedronPolygons, inverseRotateVec3, isAxisAlignedSurfaceNormal, isVoxelCameraCullableNormalGroups, loadMesh, mergePolygons, normalFacesCamera, normalizeInvertMultiplier, normalizePolygons, octahedronPolygons, optimizeMeshPolygons, parseColor, parseGltf, parseHexColor, parseMtl, parseObj, parsePureColor, parseRgbColor, parseVox, pentagonalHexecontahedronPolygons, pentagonalIcositetrahedronPolygons, pentakisDodecahedronPolygons, planePolygons, polygonCssSurfaceNormal, polygonFaces, polygonFacesCamera, prismPolygons, project, pyramidPolygons, quatFromAxisAngle, quatFromEulerXYZ, quatMultiply, resolveGeometry, rhombicDodecahedronPolygons, rhombicTriacontahedronPolygons, rhombicosidodecahedronPolygons, rhombicuboctahedronPolygons, ringPolygons, ringQuadPolygons, rotateVec3, shadeColor, smallStellatedDodecahedronPolygons, snubCubePolygons, snubDodecahedronPolygons, spherePolygons, tetrahedronPolygons, tetrakisHexahedronPolygons, torusPolygons, trapezohedronPolygons, triakisIcosahedronPolygons, triakisOctahedronPolygons, triakisTetrahedronPolygons, trianglesToFeatureEdges, truncatedCubePolygons, truncatedCuboctahedronPolygons, truncatedDodecahedronPolygons, truncatedIcosahedronPolygons, truncatedIcosidodecahedronPolygons, truncatedOctahedronPolygons, truncatedTetrahedronPolygons };
+export { type AntiprismPolygonsOptions, type ApproximateMergeOptions, type ArrowPolygonsOptions, type AutoRotateConfig, type AutoRotateOption, type AxesHelperOptions, BASE_TILE, type BipyramidPolygonsOptions, CAMERA_BACKFACE_CULL_EPS, type CameraCullNormalGroup, type CameraCullRotation, type CameraHandle, type CameraState, type CameraStyleInput, type CharRamp, type ConePolygonsOptions, type CoverPlanarPolygonsOptions, type CubePolygonsOptions, type CuboctahedronPolygonsOptions, type CullInteriorOptions, type CylinderPolygonsOptions, DEFAULT_CAMERA_STATE, DEFAULT_PROJECTION, type DedupeOverlappingPolygonsOptions, type DeltoidalHexecontahedronPolygonsOptions, type DeltoidalIcositetrahedronPolygonsOptions, type DisdyakisDodecahedronPolygonsOptions, type DisdyakisTriacontahedronPolygonsOptions, type DodecahedronPolygonsOptions, type EdgeWeight, type GltfParseOptions, type GlyphAmbientLight, type GlyphAnimationAction, type ParseAnimationClip as GlyphAnimationClip, type GlyphAnimationMixer, type GlyphAnimationTarget, type GlyphDirectionalLight, type GlyphGeometryName, type GlyphGeometryOptions, type GreatDodecahedronPolygonsOptions, type GreatIcosahedronPolygonsOptions, type GreatStellatedDodecahedronPolygonsOptions, type GridSize, type Hotspot, type HotspotCell, type IcosahedronPolygonsOptions, type IcosidodecahedronPolygonsOptions, 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 ParseStlColor, type ParseStlSolid, type ParseStlTopology, type ParsedColor, type PentagonalHexecontahedronPolygonsOptions, type PentagonalIcositetrahedronPolygonsOptions, type PentakisDodecahedronPolygonsOptions, type PlanePolygonsOptions, type PolyTextureWrap, type PolyTextureWrapMode, type Polygon, type PolygonFace, type PrismPolygonsOptions, type PyramidPolygonsOptions, QUAT_IDENTITY, type Quat, type RenderMode, type RhombicDodecahedronPolygonsOptions, type RhombicTriacontahedronPolygonsOptions, type RhombicosidodecahedronPolygonsOptions, type RhombicuboctahedronPolygonsOptions, type RingPolygonsOptions, type RingQuadPolygonsOptions, type SampledColor, type SceneBbox, type SceneContext, type SceneContextBuildArgs, type SceneContextBuildResult, type SmallStellatedDodecahedronPolygonsOptions, type SnubCubePolygonsOptions, type SnubDodecahedronPolygonsOptions, type SolidTextureSampleOptions, type SpherePolygonsOptions, type StlParseOptions, type TetrahedronPolygonsOptions, type TetrakisHexahedronPolygonsOptions, type TextureSampler, type TextureTriangle, type TorusPolygonsOptions, type TrapezohedronPolygonsOptions, type TriakisIcosahedronPolygonsOptions, type TriakisOctahedronPolygonsOptions, type TriakisTetrahedronPolygonsOptions, type TruncatedCubePolygonsOptions, type TruncatedCuboctahedronPolygonsOptions, type TruncatedDodecahedronPolygonsOptions, type TruncatedIcosahedronPolygonsOptions, type TruncatedIcosidodecahedronPolygonsOptions, type TruncatedOctahedronPolygonsOptions, type TruncatedTetrahedronPolygonsOptions, VOXEL_CAMERA_CULL_AXIS_EPS, VOXEL_CAMERA_CULL_NORMAL_LIMIT, type Vec2, type Vec3, type VoxParseOptions, type WireframeEdge, antiprismPolygons, arrowPolygons, axesHelperPolygons, bakeSolidTextureSampledPolygons, bakeSolidTextureSamples, bipyramidPolygons, buildSceneContext, buildTextureSamplers, cameraCullNormalGroups, cameraCullNormalGroupsFromPolygons, cameraCullNormalKey, cameraCullVisibleSignature, cameraFacingDepth, clampChannel, computeSceneBbox, computeShapeLighting, conePolygons, coverPlanarPolygons, createGlyphAnimationMixer, createIsometricCamera, cubePolygons, cuboctahedronPolygons, cullInteriorPolygons, cylinderPolygons, dedupeOverlappingPolygons, deltoidalHexecontahedronPolygons, deltoidalIcositetrahedronPolygons, disdyakisDodecahedronPolygons, disdyakisTriacontahedronPolygons, dodecahedronPolygons, eulerXYZFromQuat, findOverlappingPolygonDuplicates, formatColor, greatDodecahedronPolygons, greatIcosahedronPolygons, greatStellatedDodecahedronPolygons, icosahedronPolygons, icosidodecahedronPolygons, inverseRotateVec3, isAxisAlignedSurfaceNormal, isVoxelCameraCullableNormalGroups, loadMesh, mergePolygons, normalFacesCamera, normalizeInvertMultiplier, normalizePolygons, octahedronPolygons, optimizeMeshPolygons, parseColor, parseGltf, parseHexColor, parseMtl, parseObj, parsePureColor, parseRgbColor, parseStl, parseVox, pentagonalHexecontahedronPolygons, pentagonalIcositetrahedronPolygons, pentakisDodecahedronPolygons, planePolygons, polygonCssSurfaceNormal, polygonFaces, polygonFacesCamera, polygonTexture, prismPolygons, project, pyramidPolygons, quatFromAxisAngle, quatFromEulerXYZ, quatMultiply, resolveGeometry, rhombicDodecahedronPolygons, rhombicTriacontahedronPolygons, rhombicosidodecahedronPolygons, rhombicuboctahedronPolygons, ringPolygons, ringQuadPolygons, rotateVec3, sampleTexel, shadeColor, smallStellatedDodecahedronPolygons, snubCubePolygons, snubDodecahedronPolygons, spherePolygons, tetrahedronPolygons, tetrakisHexahedronPolygons, torusPolygons, trapezohedronPolygons, triakisIcosahedronPolygons, triakisOctahedronPolygons, triakisTetrahedronPolygons, trianglesToFeatureEdges, truncatedCubePolygons, truncatedCuboctahedronPolygons, truncatedDodecahedronPolygons, truncatedIcosahedronPolygons, truncatedIcosidodecahedronPolygons, truncatedOctahedronPolygons, truncatedTetrahedronPolygons };