@layoutit/polycss-react 0.2.0 → 0.2.1

package/dist/index.d.cts

@@ -1,8 +1,8 @@
-import * as react from 'react';
-import react__default, { ReactNode, CSSProperties, MouseEventHandler, PointerEventHandler, FocusEventHandler, KeyboardEventHandler, RefObject, MouseEvent as MouseEvent$1 } from 'react';
+import * as React$1 from 'react';
+import React__default, { ReactNode, CSSProperties, MouseEventHandler, PointerEventHandler, FocusEventHandler, KeyboardEventHandler, RefObject, MouseEvent as MouseEvent$1 } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { Vec3, CameraState, CameraHandle, Vec2, PolyMaterial, PolyDirectionalLight, PolyTextureLightingMode, Polygon, PolyAmbientLight, LoadMeshOptions, PolyAnimationTarget, PolyAnimationMixer, PolyAnimationClip, PolyAnimationAction, ParseAnimationController } from '@layoutit/polycss-core';
-export { ApproximateMergeOptions, ArrowPolygonsOptions, AutoRotateConfig, AutoRotateOption, AxesHelperOptions, BASE_TILE, BoxFace, BoxFaceOptions, BoxPolygonsOptions, CAMERA_BACKFACE_CULL_EPS, CameraCullNormalGroup, CameraCullRotation, CameraHandle, CameraState, CameraStyleInput, CoverPlanarPolygonsOptions, CullInteriorOptions, DEFAULT_CAMERA_STATE, DEFAULT_PROJECTION, GltfParseOptions, LoadMeshOptions, LoopMode, LoopOnce, LoopPingPong, LoopRepeat, MeshResolution, MtlParseResult, NormalizeResult, ObjParseOptions, OctahedronPolygonsOptions, OptimizeMeshPolygonsOptions, ParseAnimationClip, ParseAnimationController, ParseResult, ParsedColor, PolyAmbientLight, PolyAnimationAction, PolyAnimationClip, PolyAnimationMixer, PolyAnimationTarget, PolyDirectionalLight, PolyMaterial, PolyTextureLightingMode, Polygon, PolygonFace, RingPolygonsOptions, SceneBbox, SceneContext, SceneContextBuildArgs, SceneContextBuildResult, SolidTextureSampleOptions, TexturePaintMetrics, TexturePaintMetricsOptions, TextureTriangle, VOXEL_CAMERA_CULL_AXIS_EPS, VOXEL_CAMERA_CULL_NORMAL_LIMIT, Vec2, Vec3, VoxParseOptions, arrowPolygons, axesHelperPolygons, bakeSolidTextureSampledPolygons, bakeSolidTextureSamples, boxPolygons, buildSceneContext, cameraCullNormalGroups, cameraCullNormalGroupsFromPolygons, cameraCullNormalKey, cameraCullVisibleSignature, cameraFacingDepth, clampChannel, computeSceneBbox, computeShapeLighting, computeTexturePaintMetrics, coverPlanarPolygons, createIsometricCamera, createPolyAnimationMixer, cullInteriorPolygons, formatColor, inverseRotateVec3, isAxisAlignedSurfaceNormal, isVoxelCameraCullableNormalGroups, loadMesh, mergePolygons, normalFacesCamera, normalizeInvertMultiplier, normalizePolygons, octahedronPolygons, optimizeMeshPolygons, parseColor, parseGltf, parseHexColor, parseMtl, parseObj, parsePureColor, parseRgbColor, parseVox, polygonCssSurfaceNormal, polygonFaces, polygonFacesCamera, ringPolygons, rotateVec3, shadeColor } from '@layoutit/polycss-core';
+import { Vec3, CameraState, CameraHandle, Vec2, PolyMaterial, PolyDirectionalLight, PolyTextureLightingMode, TextureQuality, Polygon, PolyAmbientLight, PolySeamBleed, PolyRenderStrategiesOption, LoadMeshOptions, ParseResult, MeshResolution, BoxPolygonsOptions, ConePolygonsOptions, CylinderPolygonsOptions, DodecahedronPolygonsOptions, IcosahedronPolygonsOptions, OctahedronPolygonsOptions, PlanePolygonsOptions, RingPolygonsOptions, SpherePolygonsOptions, TetrahedronPolygonsOptions, TorusPolygonsOptions, PolyAnimationTarget, PolyAnimationMixer, PolyAnimationClip, PolyAnimationAction, ParseAnimationController } from '@layoutit/polycss-core';
+export { ArrowPolygonsOptions, AutoRotateConfig, AutoRotateOption, AxesHelperOptions, BASE_TILE, BoxFace, BoxFaceOptions, BoxPolygonsOptions, CAMERA_BACKFACE_CULL_EPS, CameraCullNormalGroup, CameraCullRotation, CameraHandle, CameraState, CameraStyleInput, ConePolygonsOptions, CoverPlanarPolygonsOptions, CullInteriorOptions, CylinderPolygonsOptions, DEFAULT_CAMERA_STATE, DEFAULT_PROJECTION, DEFAULT_SEAM_FACET_SPLIT_OPTIONS, DEFAULT_SEAM_OVERLAP_OPTIONS, DodecahedronPolygonsOptions, GltfParseOptions, IcosahedronPolygonsOptions, LoadMeshOptions, LoopMode, LoopOnce, LoopPingPong, LoopRepeat, MeshResolution, MtlParseResult, NormalizeResult, ObjParseOptions, OctahedronPolygonsOptions, OptimizeAnimatedMeshPolygonsOptions, OptimizeMeshPolygonsOptions, ParseAnimationClip, ParseAnimationController, ParseResult, ParsedColor, PlanePolygonsOptions, PolyAmbientLight, PolyAnimationAction, PolyAnimationClip, PolyAnimationMixer, PolyAnimationTarget, PolyDirectionalLight, PolyMaterial, PolyRenderStrategiesOption, PolyRenderStrategy, PolyTextureLightingMode, Polygon, PolygonFace, RingPolygonsOptions, SceneBbox, SceneContext, SceneContextBuildArgs, SceneContextBuildResult, SeamFacetSplitCandidate, SeamFacetSplitCandidateReason, SeamFacetSplitOptions, SeamFacetSplitReport, SeamOverlapCandidate, SeamOverlapCandidateKind, SeamOverlapDiagnostics, SeamOverlapOptions, SolidTextureSampleOptions, TetrahedronPolygonsOptions, TexturePaintMetrics, TexturePaintMetricsOptions, TextureTriangle, TorusPolygonsOptions, VOXEL_CAMERA_CULL_AXIS_EPS, VOXEL_CAMERA_CULL_NORMAL_LIMIT, Vec2, Vec3, VoxParseOptions, arrowPolygons, axesHelperPolygons, bakeSolidTextureSampledPolygons, bakeSolidTextureSamples, boxPolygons, buildSceneContext, cameraCullNormalGroups, cameraCullNormalGroupsFromPolygons, cameraCullNormalKey, cameraCullVisibleSignature, cameraFacingDepth, clampChannel, computeSceneBbox, computeShapeLighting, computeTexturePaintMetrics, conePolygons, coverPlanarPolygons, createIsometricCamera, createPolyAnimationMixer, cullInteriorPolygons, cylinderPolygons, dodecahedronPolygons, formatColor, icosahedronPolygons, inverseRotateVec3, isAxisAlignedSurfaceNormal, isVoxelCameraCullableNormalGroups, loadMesh, mergePolygons, normalFacesCamera, normalizeInvertMultiplier, normalizePolygons, octahedronPolygons, optimizeAnimatedMeshPolygons, optimizeMeshPolygons, parseColor, parseGltf, parseHexColor, parseMtl, parseObj, parsePureColor, parseRgbColor, parseVox, planePolygons, polygonCssSurfaceNormal, polygonFaces, polygonFacesCamera, repairMeshSeams, ringPolygons, rotateVec3, seamFacetSplitPolygons, seamFacetSplitReport, seamOverlapDiagnostics, seamOverlapPolygons, seamOverlapReport, shadeColor, tetrahedronPolygons, torusPolygons } from '@layoutit/polycss-core';
 
 interface PolyPerspectiveCameraProps {
     zoom?: number;
@@ -18,7 +18,7 @@ interface PolyPerspectiveCameraProps {
     style?: React.CSSProperties;
 }
 declare function PolyPerspectiveCameraInner({ zoom, target, rotX, rotY, distance, perspective, children, className, style, }: PolyPerspectiveCameraProps): react_jsx_runtime.JSX.Element;
-declare const PolyPerspectiveCamera: react.MemoExoticComponent<typeof PolyPerspectiveCameraInner>;
+declare const PolyPerspectiveCamera: React$1.MemoExoticComponent<typeof PolyPerspectiveCameraInner>;
 
 interface PolyOrthographicCameraProps {
     zoom?: number;
@@ -32,7 +32,7 @@ interface PolyOrthographicCameraProps {
     style?: React.CSSProperties;
 }
 declare function PolyOrthographicCameraInner({ zoom, target, rotX, rotY, distance, children, className, style, }: PolyOrthographicCameraProps): react_jsx_runtime.JSX.Element;
-declare const PolyOrthographicCamera: react.MemoExoticComponent<typeof PolyOrthographicCameraInner>;
+declare const PolyOrthographicCamera: React$1.MemoExoticComponent<typeof PolyOrthographicCameraInner>;
 
 interface SceneStoreState {
     cameraState: CameraState;
@@ -101,25 +101,22 @@ interface PolyCameraContextValue {
      */
     applyTransformDirect: () => void;
 }
-declare const PolyCameraContext: react.Context<PolyCameraContextValue | null>;
+declare const PolyCameraContext: React$1.Context<PolyCameraContextValue | null>;
 declare function useCameraContext(): PolyCameraContextValue;
 
 interface ShadowOptions {
     color?: string;
     opacity?: number;
     lift?: number;
+    /**
+     * Maximum CSS pixels the shadow may extend beyond the mesh's
+     * footprint. Caps the SVG backing store at low light elevations to
+     * prevent repaint flicker. Default: `2000`. Pass `Infinity` to
+     * disable the cap entirely.
+     */
+    maxExtend?: number;
 }
 
-/** A render strategy tag that can be selectively disabled. */
-type PolyRenderStrategy = "b" | "i" | "u";
-interface PolyRenderStrategiesOption {
-    /** Strategies to skip; polygons that would normally use them fall through
-     *  the chain (b → i → s, u → i → s, i → s). `<s>` is the universal
-     *  fallback and cannot be disabled — textured polys have no other path. */
-    disable?: readonly PolyRenderStrategy[];
-}
-type TextureQuality = number | "auto";
-
 /**
  * Three.js-style transform props accepted by every polycss component.
  * In Phase 3, position/scale/rotation are accepted but not yet applied —
@@ -225,6 +222,8 @@ interface PolySceneProps extends TransformProps {
      *  desktop/mobile sprite sizing. Numeric values 0.1..1 force an explicit
      *  raster scale and the 64px sprite. */
     textureQuality?: TextureQuality;
+    /** Solid seam overscan. `"auto"` computes a fitted per-edge amount from the polygon plan. */
+    seamBleed?: PolySeamBleed;
     /**
      * Render strategy overrides. Use `{ disable: ["u"] }` to force solid
      * triangles through the atlas path (`<s>`), or `{ disable: ["b", "i", "u"] }`
@@ -243,9 +242,11 @@ interface PolySceneProps extends TransformProps {
      */
     autoCenter?: boolean;
     /**
-     * Shadow appearance for meshes with `castShadow={true}`. Only applies in
-     * dynamic lighting mode — baked mode does not emit shadow leaves.
-     * Defaults: `{ color: "#000000", opacity: 0.25, lift: 0.05 }`.
+     * Shadow appearance for meshes with `castShadow={true}`. Works in both
+     * lighting modes — dynamic mode projects via CSS vars so shadows
+     * follow a moving light, baked mode CPU-bakes the projection into
+     * each leaf's inline `matrix3d` and drops back-facing polys from the
+     * DOM entirely. Defaults: `{ color: "#000000", opacity: 0.25, lift: 0.05, maxExtend: 2000 }`.
      */
     shadow?: ShadowOptions;
     className?: string;
@@ -254,12 +255,13 @@ interface PolySceneProps extends TransformProps {
     debugShowLabels?: boolean;
     debugShowBackfaces?: boolean;
 }
-declare function PolySceneInner({ polygons: polygonsProp, centerPolygons: centerPolygonsProp, perspective: _perspective, rotX: _rotX, rotY: _rotY, zoom: _zoom, directionalLight, ambientLight, textureLighting, textureQuality, strategies, autoCenter, shadow, className, style, children, position: _position, scale: _scale, rotation: _rotation, debugShowLabels: _debugShowLabels, debugShowBackfaces, }: PolySceneProps): react_jsx_runtime.JSX.Element;
-declare const PolyScene: react.MemoExoticComponent<typeof PolySceneInner>;
+declare function PolySceneInner({ polygons: polygonsProp, centerPolygons: centerPolygonsProp, perspective: _perspective, rotX: _rotX, rotY: _rotY, zoom: _zoom, directionalLight, ambientLight, textureLighting, textureQuality, seamBleed, strategies, autoCenter, shadow, className, style, children, position: _position, scale: _scale, rotation: _rotation, debugShowLabels: _debugShowLabels, debugShowBackfaces, }: PolySceneProps): react_jsx_runtime.JSX.Element;
+declare const PolyScene: React$1.MemoExoticComponent<typeof PolySceneInner>;
 
 type UseMeshOptions = LoadMeshOptions;
 interface UseMeshResult {
     polygons: Polygon[];
+    voxelSource: ParseResult["voxelSource"];
     loading: boolean;
     error: Error | null;
     warnings: string[];
@@ -271,7 +273,7 @@ declare function usePolyMesh(src: string, options?: UseMeshOptions): UseMeshResu
 /**
  * Pointer event API for <PolyMesh>. Mirrors @react-three/fiber's mesh
  * event surface (handler names + payload shape) so devs migrating from
- * three.js use the same mental model. polycss is DOM-native so we get
+ * three.js use the same mental model. PolyCSS is DOM-native so we get
  * native pointer events for free — no raycaster, no canvas event
  * synthesis.
  *
@@ -306,6 +308,12 @@ interface PolyMeshHandle {
     getScale(): number | Vec3 | undefined;
     /** Polygons currently being rendered (post-autoCenter). */
     getPolygons(): Polygon[];
+    /**
+     * Replace the mesh polygons imperatively. Animated solid-triangle meshes use
+     * a stable DOM update path that mutates mounted leaves directly; unsupported
+     * topology falls back to the normal framework render path.
+     */
+    setPolygons(polygons: Polygon[]): void;
     /**
      * Snapshot the current `rotation` prop as the new "baked rotation" and
      * trigger an atlas re-rasterization with the directional light
@@ -427,6 +435,8 @@ interface PolyMeshProps extends TransformProps, InteractionProps {
      *  desktop/mobile sprite sizing. Numeric values 0.1..1 force an explicit
      *  raster scale and the 64px sprite. */
     textureQuality?: TextureQuality;
+    /** Solid seam overscan. `"auto"` computes a fitted per-edge amount from the polygon plan. */
+    seamBleed?: PolySeamBleed;
     /** Per-polygon override render, or static children mounted inside the mesh wrapper. */
     children?: ((polygon: Polygon, index: number) => ReactNode) | ReactNode;
     /** Loading slot — rendered while `src` is being fetched/parsed. */
@@ -435,6 +445,10 @@ interface PolyMeshProps extends TransformProps, InteractionProps {
     errorFallback?: (error: Error) => ReactNode;
     /** Parser options forwarded to parseObj/parseGltf. */
     parseOptions?: UseMeshOptions;
+    /** Mesh optimization intent. Defaults to "lossy"; set "lossless" to keep
+     *  authored surface fidelity. Top-level prop wins over `parseOptions.meshResolution`
+     *  when both are present. */
+    meshResolution?: MeshResolution;
     /**
      * When `true` and the scene is in dynamic lighting mode, emits a flat
      * shadow leaf (`<q class="polycss-shadow">`) sibling for each polygon.
@@ -446,7 +460,7 @@ interface PolyMeshProps extends TransformProps, InteractionProps {
     className?: string;
     style?: CSSProperties;
 }
-declare const PolyMesh: react.ForwardRefExoticComponent<PolyMeshProps & react.RefAttributes<PolyMeshHandle>>;
+declare const PolyMesh: React$1.ForwardRefExoticComponent<PolyMeshProps & React$1.RefAttributes<PolyMeshHandle>>;
 
 interface PolyGroundProps {
     /** Side length of the ground quad in world units. Default `6`. */
@@ -473,7 +487,7 @@ interface UseSceneContextResult {
     };
 }
 /**
- * React hook that runs the polycss scene-context pipeline:
+ * React hook that runs the PolyCSS scene-context pipeline:
  *   normalizePolygons → mergePolygons by default → bbox compute.
  *
  * Returns the processed polygons + the scene-wide axis-aligned bbox. Memoized
@@ -510,7 +524,42 @@ declare function usePolyMaterial(options: {
  * typically created once at parse time and passed by reference.
  */
 declare function PolyInner({ vertices, color, texture, uvs, data, material, position, scale, rotation, className, style: styleProp, id, onClick, onDoubleClick, onMouseEnter, onMouseLeave, onMouseMove, onPointerDown, onPointerUp, onPointerEnter, onPointerLeave, onFocus, onBlur, onKeyDown, tabIndex, role, "aria-label": ariaLabel, "aria-hidden": ariaHidden, pointerEvents: pointerEventsProp, context, textureLighting: textureLightingProp, textureQuality: textureQualityProp, baseColor: baseColorProp, ...dataAttrs }: PolyProps): react_jsx_runtime.JSX.Element | null;
-declare const Poly: react__default.MemoExoticComponent<typeof PolyInner>;
+declare const Poly: React__default.MemoExoticComponent<typeof PolyInner>;
+
+type ShapeMeshProps = Omit<PolyMeshProps, "polygons" | "src" | "mtl">;
+interface PolyBoxProps extends ShapeMeshProps, BoxPolygonsOptions {
+}
+declare function PolyBox({ size, center, min, max, color, texture, material, uvs, data, faces, ...meshProps }: PolyBoxProps): react_jsx_runtime.JSX.Element;
+interface PolyPlaneProps extends ShapeMeshProps, PlanePolygonsOptions {
+}
+declare function PolyPlane({ axis, size, offset, along, color, ...meshProps }: PolyPlaneProps): react_jsx_runtime.JSX.Element;
+interface PolyRingProps extends ShapeMeshProps, RingPolygonsOptions {
+}
+declare function PolyRing({ axis, radius, halfThickness, segments, color, ...meshProps }: PolyRingProps): react_jsx_runtime.JSX.Element;
+interface PolyOctahedronProps extends ShapeMeshProps, OctahedronPolygonsOptions {
+}
+declare function PolyOctahedron({ center, size, color, ...meshProps }: PolyOctahedronProps): react_jsx_runtime.JSX.Element;
+interface PolyTetrahedronProps extends ShapeMeshProps, TetrahedronPolygonsOptions {
+}
+declare function PolyTetrahedron({ size, color, ...meshProps }: PolyTetrahedronProps): react_jsx_runtime.JSX.Element;
+interface PolyIcosahedronProps extends ShapeMeshProps, IcosahedronPolygonsOptions {
+}
+declare function PolyIcosahedron({ size, color, ...meshProps }: PolyIcosahedronProps): react_jsx_runtime.JSX.Element;
+interface PolyDodecahedronProps extends ShapeMeshProps, DodecahedronPolygonsOptions {
+}
+declare function PolyDodecahedron({ size, color, ...meshProps }: PolyDodecahedronProps): react_jsx_runtime.JSX.Element;
+interface PolySphereProps extends ShapeMeshProps, SpherePolygonsOptions {
+}
+declare function PolySphere({ radius, subdivisions, color, ...meshProps }: PolySphereProps): react_jsx_runtime.JSX.Element;
+interface PolyCylinderProps extends ShapeMeshProps, CylinderPolygonsOptions {
+}
+declare function PolyCylinder({ radius, radiusTop, height, radialSegments, color, ...meshProps }: PolyCylinderProps): react_jsx_runtime.JSX.Element;
+interface PolyConeProps extends ShapeMeshProps, ConePolygonsOptions {
+}
+declare function PolyCone({ radius, height, radialSegments, color, ...meshProps }: PolyConeProps): react_jsx_runtime.JSX.Element;
+interface PolyTorusProps extends ShapeMeshProps, TorusPolygonsOptions {
+}
+declare function PolyTorus({ radius, tube, radialSegments, tubularSegments, color, ...meshProps }: PolyTorusProps): react_jsx_runtime.JSX.Element;
 
 interface PolyFirstPersonControlsOptions {
     /** Master switch. When `false`, all sub-controls are inert. Default: `true`. */
@@ -577,7 +626,7 @@ interface PolyFirstPersonControlsProps extends PolyFirstPersonControlsOptions {
     /** Called when pointer-lock is released (interaction ends). */
     onInteractionEnd?: () => void;
 }
-declare const PolyFirstPersonControls: react.ForwardRefExoticComponent<PolyFirstPersonControlsProps & react.RefAttributes<PolyFirstPersonControlsHandle>>;
+declare const PolyFirstPersonControls: React$1.ForwardRefExoticComponent<PolyFirstPersonControlsProps & React$1.RefAttributes<PolyFirstPersonControlsHandle>>;
 
 interface PolyControlsAnimateOptions {
     /** Degrees per 60Hz-equivalent frame. Default 0.3 (≈ 18 deg/sec). */
@@ -789,6 +838,29 @@ declare function PolyDirectionalLightHelper({ light, target, distance, size, col
 
 declare function injectPolyBaseStyles(doc?: Document): void;
 
+interface PolyRenderSurfaceLeafCounts {
+    quad: number;
+    clippedSolid: number;
+    atlas: number;
+    stableTriangle: number;
+}
+interface PolyRenderStats {
+    polygonCount: number;
+    mountedPolygonLeafCount: number;
+    shadowLeafCount: number;
+    surfaceLeafCounts: PolyRenderSurfaceLeafCounts;
+    bucketCount: number;
+}
+interface PolyRenderStatsOptions {
+    polygonCount?: number;
+    /**
+     * Optional subtree selector for diagnostics that only want model leaves and
+     * not helpers/floors/gizmos sharing the same scene root.
+     */
+    scopeSelector?: string;
+}
+declare function collectPolyRenderStats(root: ParentNode | null | undefined, optionsOrPolygonCount?: number | PolyRenderStatsOptions): PolyRenderStats;
+
 interface UsePolyAnimationResult {
     /** Attach to a `PolyAnimationTarget`-compatible handle when not using `root`. */
     ref: RefObject<PolyAnimationTarget | null>;
@@ -807,4 +879,4 @@ interface UsePolyAnimationResult {
 }
 declare function usePolyAnimation(clips: PolyAnimationClip[] | undefined, controller: ParseAnimationController | undefined, root?: RefObject<PolyAnimationTarget | null> | PolyAnimationTarget | null): UsePolyAnimationResult;
 
-export { type DOMPassthroughProps, type InteractionProps, Poly, PolyAxesHelper, type PolyAxesHelperProps, PolyPerspectiveCamera as PolyCamera, PolyCameraContext, type PolyCameraContextValue, type PolyPerspectiveCameraProps as PolyCameraProps, type PolyControlsAnimateOptions, type PolyControlsCamera, PolyDirectionalLightHelper, type PolyDirectionalLightHelperProps, type PolyEventHandler, PolyFirstPersonControls, type PolyFirstPersonControlsHandle, type PolyFirstPersonControlsOptions, type PolyFirstPersonControlsProps, PolyGround, type PolyGroundProps, PolyMapControls, type PolyControlsCamera as PolyMapControlsCamera, type PolyMapControlsProps, PolyMesh, type PolyMeshHandle, type PolyMeshProps, type PolyMouseEvent, PolyOrbitControls, type PolyControlsCamera as PolyOrbitControlsCamera, type PolyOrbitControlsProps, PolyOrthographicCamera, type PolyOrthographicCameraProps, PolyPerspectiveCamera, type PolyPerspectiveCameraProps, type PolyPointerEvent, type PolyProps, type PolyRenderStrategiesOption, type PolyRenderStrategy, PolyScene, type PolySceneProps, PolySelect, type PolySelectProps, type PolySelectionApi, PolyTransformControls, type PolyTransformControlsObject, type PolyTransformControlsObjectChangeEvent, type PolyTransformControlsProps, type PolyWheelEvent, type SharedControlsProps, type TransformProps, type UseCameraOptions, type UseCameraResult, type UseMeshOptions, type UseMeshResult, type UsePolyAnimationResult, type UseSceneContextOptions, type UseSceneContextResult, findMeshUnderPoint, findPolyMeshHandle, injectPolyBaseStyles, pointInMeshElement, useCameraContext, usePolyAnimation, usePolyCamera, usePolyMaterial, usePolyMesh, usePolySceneContext, usePolySelect, usePolySelectionApi };
+export { type DOMPassthroughProps, type InteractionProps, Poly, PolyAxesHelper, type PolyAxesHelperProps, PolyBox, type PolyBoxProps, PolyOrthographicCamera as PolyCamera, PolyCameraContext, type PolyCameraContextValue, type PolyOrthographicCameraProps as PolyCameraProps, PolyCone, type PolyConeProps, type PolyControlsAnimateOptions, type PolyControlsCamera, PolyCylinder, type PolyCylinderProps, PolyDirectionalLightHelper, type PolyDirectionalLightHelperProps, PolyDodecahedron, type PolyDodecahedronProps, type PolyEventHandler, PolyFirstPersonControls, type PolyFirstPersonControlsHandle, type PolyFirstPersonControlsOptions, type PolyFirstPersonControlsProps, PolyGround, type PolyGroundProps, PolyIcosahedron, type PolyIcosahedronProps, PolyMapControls, type PolyControlsCamera as PolyMapControlsCamera, type PolyMapControlsProps, PolyMesh, type PolyMeshHandle, type PolyMeshProps, type PolyMouseEvent, PolyOctahedron, type PolyOctahedronProps, PolyOrbitControls, type PolyControlsCamera as PolyOrbitControlsCamera, type PolyOrbitControlsProps, PolyOrthographicCamera, type PolyOrthographicCameraProps, PolyPerspectiveCamera, type PolyPerspectiveCameraProps, PolyPlane, type PolyPlaneProps, type PolyPointerEvent, type PolyProps, type PolyRenderStats, type PolyRenderStatsOptions, type PolyRenderSurfaceLeafCounts, PolyRing, type PolyRingProps, PolyScene, type PolySceneProps, PolySelect, type PolySelectProps, type PolySelectionApi, PolySphere, type PolySphereProps, PolyTetrahedron, type PolyTetrahedronProps, PolyTorus, type PolyTorusProps, PolyTransformControls, type PolyTransformControlsObject, type PolyTransformControlsObjectChangeEvent, type PolyTransformControlsProps, type PolyWheelEvent, type SharedControlsProps, type TransformProps, type UseCameraOptions, type UseCameraResult, type UseMeshOptions, type UseMeshResult, type UsePolyAnimationResult, type UseSceneContextOptions, type UseSceneContextResult, collectPolyRenderStats, findMeshUnderPoint, findPolyMeshHandle, injectPolyBaseStyles, pointInMeshElement, useCameraContext, usePolyAnimation, usePolyCamera, usePolyMaterial, usePolyMesh, usePolySceneContext, usePolySelect, usePolySelectionApi };

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-import * as react from 'react';
-import react__default, { ReactNode, CSSProperties, MouseEventHandler, PointerEventHandler, FocusEventHandler, KeyboardEventHandler, RefObject, MouseEvent as MouseEvent$1 } from 'react';
+import * as React$1 from 'react';
+import React__default, { ReactNode, CSSProperties, MouseEventHandler, PointerEventHandler, FocusEventHandler, KeyboardEventHandler, RefObject, MouseEvent as MouseEvent$1 } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { Vec3, CameraState, CameraHandle, Vec2, PolyMaterial, PolyDirectionalLight, PolyTextureLightingMode, Polygon, PolyAmbientLight, LoadMeshOptions, PolyAnimationTarget, PolyAnimationMixer, PolyAnimationClip, PolyAnimationAction, ParseAnimationController } from '@layoutit/polycss-core';
-export { ApproximateMergeOptions, ArrowPolygonsOptions, AutoRotateConfig, AutoRotateOption, AxesHelperOptions, BASE_TILE, BoxFace, BoxFaceOptions, BoxPolygonsOptions, CAMERA_BACKFACE_CULL_EPS, CameraCullNormalGroup, CameraCullRotation, CameraHandle, CameraState, CameraStyleInput, CoverPlanarPolygonsOptions, CullInteriorOptions, DEFAULT_CAMERA_STATE, DEFAULT_PROJECTION, GltfParseOptions, LoadMeshOptions, LoopMode, LoopOnce, LoopPingPong, LoopRepeat, MeshResolution, MtlParseResult, NormalizeResult, ObjParseOptions, OctahedronPolygonsOptions, OptimizeMeshPolygonsOptions, ParseAnimationClip, ParseAnimationController, ParseResult, ParsedColor, PolyAmbientLight, PolyAnimationAction, PolyAnimationClip, PolyAnimationMixer, PolyAnimationTarget, PolyDirectionalLight, PolyMaterial, PolyTextureLightingMode, Polygon, PolygonFace, RingPolygonsOptions, SceneBbox, SceneContext, SceneContextBuildArgs, SceneContextBuildResult, SolidTextureSampleOptions, TexturePaintMetrics, TexturePaintMetricsOptions, TextureTriangle, VOXEL_CAMERA_CULL_AXIS_EPS, VOXEL_CAMERA_CULL_NORMAL_LIMIT, Vec2, Vec3, VoxParseOptions, arrowPolygons, axesHelperPolygons, bakeSolidTextureSampledPolygons, bakeSolidTextureSamples, boxPolygons, buildSceneContext, cameraCullNormalGroups, cameraCullNormalGroupsFromPolygons, cameraCullNormalKey, cameraCullVisibleSignature, cameraFacingDepth, clampChannel, computeSceneBbox, computeShapeLighting, computeTexturePaintMetrics, coverPlanarPolygons, createIsometricCamera, createPolyAnimationMixer, cullInteriorPolygons, formatColor, inverseRotateVec3, isAxisAlignedSurfaceNormal, isVoxelCameraCullableNormalGroups, loadMesh, mergePolygons, normalFacesCamera, normalizeInvertMultiplier, normalizePolygons, octahedronPolygons, optimizeMeshPolygons, parseColor, parseGltf, parseHexColor, parseMtl, parseObj, parsePureColor, parseRgbColor, parseVox, polygonCssSurfaceNormal, polygonFaces, polygonFacesCamera, ringPolygons, rotateVec3, shadeColor } from '@layoutit/polycss-core';
+import { Vec3, CameraState, CameraHandle, Vec2, PolyMaterial, PolyDirectionalLight, PolyTextureLightingMode, TextureQuality, Polygon, PolyAmbientLight, PolySeamBleed, PolyRenderStrategiesOption, LoadMeshOptions, ParseResult, MeshResolution, BoxPolygonsOptions, ConePolygonsOptions, CylinderPolygonsOptions, DodecahedronPolygonsOptions, IcosahedronPolygonsOptions, OctahedronPolygonsOptions, PlanePolygonsOptions, RingPolygonsOptions, SpherePolygonsOptions, TetrahedronPolygonsOptions, TorusPolygonsOptions, PolyAnimationTarget, PolyAnimationMixer, PolyAnimationClip, PolyAnimationAction, ParseAnimationController } from '@layoutit/polycss-core';
+export { ArrowPolygonsOptions, AutoRotateConfig, AutoRotateOption, AxesHelperOptions, BASE_TILE, BoxFace, BoxFaceOptions, BoxPolygonsOptions, CAMERA_BACKFACE_CULL_EPS, CameraCullNormalGroup, CameraCullRotation, CameraHandle, CameraState, CameraStyleInput, ConePolygonsOptions, CoverPlanarPolygonsOptions, CullInteriorOptions, CylinderPolygonsOptions, DEFAULT_CAMERA_STATE, DEFAULT_PROJECTION, DEFAULT_SEAM_FACET_SPLIT_OPTIONS, DEFAULT_SEAM_OVERLAP_OPTIONS, DodecahedronPolygonsOptions, GltfParseOptions, IcosahedronPolygonsOptions, LoadMeshOptions, LoopMode, LoopOnce, LoopPingPong, LoopRepeat, MeshResolution, MtlParseResult, NormalizeResult, ObjParseOptions, OctahedronPolygonsOptions, OptimizeAnimatedMeshPolygonsOptions, OptimizeMeshPolygonsOptions, ParseAnimationClip, ParseAnimationController, ParseResult, ParsedColor, PlanePolygonsOptions, PolyAmbientLight, PolyAnimationAction, PolyAnimationClip, PolyAnimationMixer, PolyAnimationTarget, PolyDirectionalLight, PolyMaterial, PolyRenderStrategiesOption, PolyRenderStrategy, PolyTextureLightingMode, Polygon, PolygonFace, RingPolygonsOptions, SceneBbox, SceneContext, SceneContextBuildArgs, SceneContextBuildResult, SeamFacetSplitCandidate, SeamFacetSplitCandidateReason, SeamFacetSplitOptions, SeamFacetSplitReport, SeamOverlapCandidate, SeamOverlapCandidateKind, SeamOverlapDiagnostics, SeamOverlapOptions, SolidTextureSampleOptions, TetrahedronPolygonsOptions, TexturePaintMetrics, TexturePaintMetricsOptions, TextureTriangle, TorusPolygonsOptions, VOXEL_CAMERA_CULL_AXIS_EPS, VOXEL_CAMERA_CULL_NORMAL_LIMIT, Vec2, Vec3, VoxParseOptions, arrowPolygons, axesHelperPolygons, bakeSolidTextureSampledPolygons, bakeSolidTextureSamples, boxPolygons, buildSceneContext, cameraCullNormalGroups, cameraCullNormalGroupsFromPolygons, cameraCullNormalKey, cameraCullVisibleSignature, cameraFacingDepth, clampChannel, computeSceneBbox, computeShapeLighting, computeTexturePaintMetrics, conePolygons, coverPlanarPolygons, createIsometricCamera, createPolyAnimationMixer, cullInteriorPolygons, cylinderPolygons, dodecahedronPolygons, formatColor, icosahedronPolygons, inverseRotateVec3, isAxisAlignedSurfaceNormal, isVoxelCameraCullableNormalGroups, loadMesh, mergePolygons, normalFacesCamera, normalizeInvertMultiplier, normalizePolygons, octahedronPolygons, optimizeAnimatedMeshPolygons, optimizeMeshPolygons, parseColor, parseGltf, parseHexColor, parseMtl, parseObj, parsePureColor, parseRgbColor, parseVox, planePolygons, polygonCssSurfaceNormal, polygonFaces, polygonFacesCamera, repairMeshSeams, ringPolygons, rotateVec3, seamFacetSplitPolygons, seamFacetSplitReport, seamOverlapDiagnostics, seamOverlapPolygons, seamOverlapReport, shadeColor, tetrahedronPolygons, torusPolygons } from '@layoutit/polycss-core';
 
 interface PolyPerspectiveCameraProps {
     zoom?: number;
@@ -18,7 +18,7 @@ interface PolyPerspectiveCameraProps {
     style?: React.CSSProperties;
 }
 declare function PolyPerspectiveCameraInner({ zoom, target, rotX, rotY, distance, perspective, children, className, style, }: PolyPerspectiveCameraProps): react_jsx_runtime.JSX.Element;
-declare const PolyPerspectiveCamera: react.MemoExoticComponent<typeof PolyPerspectiveCameraInner>;
+declare const PolyPerspectiveCamera: React$1.MemoExoticComponent<typeof PolyPerspectiveCameraInner>;
 
 interface PolyOrthographicCameraProps {
     zoom?: number;
@@ -32,7 +32,7 @@ interface PolyOrthographicCameraProps {
     style?: React.CSSProperties;
 }
 declare function PolyOrthographicCameraInner({ zoom, target, rotX, rotY, distance, children, className, style, }: PolyOrthographicCameraProps): react_jsx_runtime.JSX.Element;
-declare const PolyOrthographicCamera: react.MemoExoticComponent<typeof PolyOrthographicCameraInner>;
+declare const PolyOrthographicCamera: React$1.MemoExoticComponent<typeof PolyOrthographicCameraInner>;
 
 interface SceneStoreState {
     cameraState: CameraState;
@@ -101,25 +101,22 @@ interface PolyCameraContextValue {
      */
     applyTransformDirect: () => void;
 }
-declare const PolyCameraContext: react.Context<PolyCameraContextValue | null>;
+declare const PolyCameraContext: React$1.Context<PolyCameraContextValue | null>;
 declare function useCameraContext(): PolyCameraContextValue;
 
 interface ShadowOptions {
     color?: string;
     opacity?: number;
     lift?: number;
+    /**
+     * Maximum CSS pixels the shadow may extend beyond the mesh's
+     * footprint. Caps the SVG backing store at low light elevations to
+     * prevent repaint flicker. Default: `2000`. Pass `Infinity` to
+     * disable the cap entirely.
+     */
+    maxExtend?: number;
 }
 
-/** A render strategy tag that can be selectively disabled. */
-type PolyRenderStrategy = "b" | "i" | "u";
-interface PolyRenderStrategiesOption {
-    /** Strategies to skip; polygons that would normally use them fall through
-     *  the chain (b → i → s, u → i → s, i → s). `<s>` is the universal
-     *  fallback and cannot be disabled — textured polys have no other path. */
-    disable?: readonly PolyRenderStrategy[];
-}
-type TextureQuality = number | "auto";
-
 /**
  * Three.js-style transform props accepted by every polycss component.
  * In Phase 3, position/scale/rotation are accepted but not yet applied —
@@ -225,6 +222,8 @@ interface PolySceneProps extends TransformProps {
      *  desktop/mobile sprite sizing. Numeric values 0.1..1 force an explicit
      *  raster scale and the 64px sprite. */
     textureQuality?: TextureQuality;
+    /** Solid seam overscan. `"auto"` computes a fitted per-edge amount from the polygon plan. */
+    seamBleed?: PolySeamBleed;
     /**
      * Render strategy overrides. Use `{ disable: ["u"] }` to force solid
      * triangles through the atlas path (`<s>`), or `{ disable: ["b", "i", "u"] }`
@@ -243,9 +242,11 @@ interface PolySceneProps extends TransformProps {
      */
     autoCenter?: boolean;
     /**
-     * Shadow appearance for meshes with `castShadow={true}`. Only applies in
-     * dynamic lighting mode — baked mode does not emit shadow leaves.
-     * Defaults: `{ color: "#000000", opacity: 0.25, lift: 0.05 }`.
+     * Shadow appearance for meshes with `castShadow={true}`. Works in both
+     * lighting modes — dynamic mode projects via CSS vars so shadows
+     * follow a moving light, baked mode CPU-bakes the projection into
+     * each leaf's inline `matrix3d` and drops back-facing polys from the
+     * DOM entirely. Defaults: `{ color: "#000000", opacity: 0.25, lift: 0.05, maxExtend: 2000 }`.
      */
     shadow?: ShadowOptions;
     className?: string;
@@ -254,12 +255,13 @@ interface PolySceneProps extends TransformProps {
     debugShowLabels?: boolean;
     debugShowBackfaces?: boolean;
 }
-declare function PolySceneInner({ polygons: polygonsProp, centerPolygons: centerPolygonsProp, perspective: _perspective, rotX: _rotX, rotY: _rotY, zoom: _zoom, directionalLight, ambientLight, textureLighting, textureQuality, strategies, autoCenter, shadow, className, style, children, position: _position, scale: _scale, rotation: _rotation, debugShowLabels: _debugShowLabels, debugShowBackfaces, }: PolySceneProps): react_jsx_runtime.JSX.Element;
-declare const PolyScene: react.MemoExoticComponent<typeof PolySceneInner>;
+declare function PolySceneInner({ polygons: polygonsProp, centerPolygons: centerPolygonsProp, perspective: _perspective, rotX: _rotX, rotY: _rotY, zoom: _zoom, directionalLight, ambientLight, textureLighting, textureQuality, seamBleed, strategies, autoCenter, shadow, className, style, children, position: _position, scale: _scale, rotation: _rotation, debugShowLabels: _debugShowLabels, debugShowBackfaces, }: PolySceneProps): react_jsx_runtime.JSX.Element;
+declare const PolyScene: React$1.MemoExoticComponent<typeof PolySceneInner>;
 
 type UseMeshOptions = LoadMeshOptions;
 interface UseMeshResult {
     polygons: Polygon[];
+    voxelSource: ParseResult["voxelSource"];
     loading: boolean;
     error: Error | null;
     warnings: string[];
@@ -271,7 +273,7 @@ declare function usePolyMesh(src: string, options?: UseMeshOptions): UseMeshResu
 /**
  * Pointer event API for <PolyMesh>. Mirrors @react-three/fiber's mesh
  * event surface (handler names + payload shape) so devs migrating from
- * three.js use the same mental model. polycss is DOM-native so we get
+ * three.js use the same mental model. PolyCSS is DOM-native so we get
  * native pointer events for free — no raycaster, no canvas event
  * synthesis.
  *
@@ -306,6 +308,12 @@ interface PolyMeshHandle {
     getScale(): number | Vec3 | undefined;
     /** Polygons currently being rendered (post-autoCenter). */
     getPolygons(): Polygon[];
+    /**
+     * Replace the mesh polygons imperatively. Animated solid-triangle meshes use
+     * a stable DOM update path that mutates mounted leaves directly; unsupported
+     * topology falls back to the normal framework render path.
+     */
+    setPolygons(polygons: Polygon[]): void;
     /**
      * Snapshot the current `rotation` prop as the new "baked rotation" and
      * trigger an atlas re-rasterization with the directional light
@@ -427,6 +435,8 @@ interface PolyMeshProps extends TransformProps, InteractionProps {
      *  desktop/mobile sprite sizing. Numeric values 0.1..1 force an explicit
      *  raster scale and the 64px sprite. */
     textureQuality?: TextureQuality;
+    /** Solid seam overscan. `"auto"` computes a fitted per-edge amount from the polygon plan. */
+    seamBleed?: PolySeamBleed;
     /** Per-polygon override render, or static children mounted inside the mesh wrapper. */
     children?: ((polygon: Polygon, index: number) => ReactNode) | ReactNode;
     /** Loading slot — rendered while `src` is being fetched/parsed. */
@@ -435,6 +445,10 @@ interface PolyMeshProps extends TransformProps, InteractionProps {
     errorFallback?: (error: Error) => ReactNode;
     /** Parser options forwarded to parseObj/parseGltf. */
     parseOptions?: UseMeshOptions;
+    /** Mesh optimization intent. Defaults to "lossy"; set "lossless" to keep
+     *  authored surface fidelity. Top-level prop wins over `parseOptions.meshResolution`
+     *  when both are present. */
+    meshResolution?: MeshResolution;
     /**
      * When `true` and the scene is in dynamic lighting mode, emits a flat
      * shadow leaf (`<q class="polycss-shadow">`) sibling for each polygon.
@@ -446,7 +460,7 @@ interface PolyMeshProps extends TransformProps, InteractionProps {
     className?: string;
     style?: CSSProperties;
 }
-declare const PolyMesh: react.ForwardRefExoticComponent<PolyMeshProps & react.RefAttributes<PolyMeshHandle>>;
+declare const PolyMesh: React$1.ForwardRefExoticComponent<PolyMeshProps & React$1.RefAttributes<PolyMeshHandle>>;
 
 interface PolyGroundProps {
     /** Side length of the ground quad in world units. Default `6`. */
@@ -473,7 +487,7 @@ interface UseSceneContextResult {
     };
 }
 /**
- * React hook that runs the polycss scene-context pipeline:
+ * React hook that runs the PolyCSS scene-context pipeline:
  *   normalizePolygons → mergePolygons by default → bbox compute.
  *
  * Returns the processed polygons + the scene-wide axis-aligned bbox. Memoized
@@ -510,7 +524,42 @@ declare function usePolyMaterial(options: {
  * typically created once at parse time and passed by reference.
  */
 declare function PolyInner({ vertices, color, texture, uvs, data, material, position, scale, rotation, className, style: styleProp, id, onClick, onDoubleClick, onMouseEnter, onMouseLeave, onMouseMove, onPointerDown, onPointerUp, onPointerEnter, onPointerLeave, onFocus, onBlur, onKeyDown, tabIndex, role, "aria-label": ariaLabel, "aria-hidden": ariaHidden, pointerEvents: pointerEventsProp, context, textureLighting: textureLightingProp, textureQuality: textureQualityProp, baseColor: baseColorProp, ...dataAttrs }: PolyProps): react_jsx_runtime.JSX.Element | null;
-declare const Poly: react__default.MemoExoticComponent<typeof PolyInner>;
+declare const Poly: React__default.MemoExoticComponent<typeof PolyInner>;
+
+type ShapeMeshProps = Omit<PolyMeshProps, "polygons" | "src" | "mtl">;
+interface PolyBoxProps extends ShapeMeshProps, BoxPolygonsOptions {
+}
+declare function PolyBox({ size, center, min, max, color, texture, material, uvs, data, faces, ...meshProps }: PolyBoxProps): react_jsx_runtime.JSX.Element;
+interface PolyPlaneProps extends ShapeMeshProps, PlanePolygonsOptions {
+}
+declare function PolyPlane({ axis, size, offset, along, color, ...meshProps }: PolyPlaneProps): react_jsx_runtime.JSX.Element;
+interface PolyRingProps extends ShapeMeshProps, RingPolygonsOptions {
+}
+declare function PolyRing({ axis, radius, halfThickness, segments, color, ...meshProps }: PolyRingProps): react_jsx_runtime.JSX.Element;
+interface PolyOctahedronProps extends ShapeMeshProps, OctahedronPolygonsOptions {
+}
+declare function PolyOctahedron({ center, size, color, ...meshProps }: PolyOctahedronProps): react_jsx_runtime.JSX.Element;
+interface PolyTetrahedronProps extends ShapeMeshProps, TetrahedronPolygonsOptions {
+}
+declare function PolyTetrahedron({ size, color, ...meshProps }: PolyTetrahedronProps): react_jsx_runtime.JSX.Element;
+interface PolyIcosahedronProps extends ShapeMeshProps, IcosahedronPolygonsOptions {
+}
+declare function PolyIcosahedron({ size, color, ...meshProps }: PolyIcosahedronProps): react_jsx_runtime.JSX.Element;
+interface PolyDodecahedronProps extends ShapeMeshProps, DodecahedronPolygonsOptions {
+}
+declare function PolyDodecahedron({ size, color, ...meshProps }: PolyDodecahedronProps): react_jsx_runtime.JSX.Element;
+interface PolySphereProps extends ShapeMeshProps, SpherePolygonsOptions {
+}
+declare function PolySphere({ radius, subdivisions, color, ...meshProps }: PolySphereProps): react_jsx_runtime.JSX.Element;
+interface PolyCylinderProps extends ShapeMeshProps, CylinderPolygonsOptions {
+}
+declare function PolyCylinder({ radius, radiusTop, height, radialSegments, color, ...meshProps }: PolyCylinderProps): react_jsx_runtime.JSX.Element;
+interface PolyConeProps extends ShapeMeshProps, ConePolygonsOptions {
+}
+declare function PolyCone({ radius, height, radialSegments, color, ...meshProps }: PolyConeProps): react_jsx_runtime.JSX.Element;
+interface PolyTorusProps extends ShapeMeshProps, TorusPolygonsOptions {
+}
+declare function PolyTorus({ radius, tube, radialSegments, tubularSegments, color, ...meshProps }: PolyTorusProps): react_jsx_runtime.JSX.Element;
 
 interface PolyFirstPersonControlsOptions {
     /** Master switch. When `false`, all sub-controls are inert. Default: `true`. */
@@ -577,7 +626,7 @@ interface PolyFirstPersonControlsProps extends PolyFirstPersonControlsOptions {
     /** Called when pointer-lock is released (interaction ends). */
     onInteractionEnd?: () => void;
 }
-declare const PolyFirstPersonControls: react.ForwardRefExoticComponent<PolyFirstPersonControlsProps & react.RefAttributes<PolyFirstPersonControlsHandle>>;
+declare const PolyFirstPersonControls: React$1.ForwardRefExoticComponent<PolyFirstPersonControlsProps & React$1.RefAttributes<PolyFirstPersonControlsHandle>>;
 
 interface PolyControlsAnimateOptions {
     /** Degrees per 60Hz-equivalent frame. Default 0.3 (≈ 18 deg/sec). */
@@ -789,6 +838,29 @@ declare function PolyDirectionalLightHelper({ light, target, distance, size, col
 
 declare function injectPolyBaseStyles(doc?: Document): void;
 
+interface PolyRenderSurfaceLeafCounts {
+    quad: number;
+    clippedSolid: number;
+    atlas: number;
+    stableTriangle: number;
+}
+interface PolyRenderStats {
+    polygonCount: number;
+    mountedPolygonLeafCount: number;
+    shadowLeafCount: number;
+    surfaceLeafCounts: PolyRenderSurfaceLeafCounts;
+    bucketCount: number;
+}
+interface PolyRenderStatsOptions {
+    polygonCount?: number;
+    /**
+     * Optional subtree selector for diagnostics that only want model leaves and
+     * not helpers/floors/gizmos sharing the same scene root.
+     */
+    scopeSelector?: string;
+}
+declare function collectPolyRenderStats(root: ParentNode | null | undefined, optionsOrPolygonCount?: number | PolyRenderStatsOptions): PolyRenderStats;
+
 interface UsePolyAnimationResult {
     /** Attach to a `PolyAnimationTarget`-compatible handle when not using `root`. */
     ref: RefObject<PolyAnimationTarget | null>;
@@ -807,4 +879,4 @@ interface UsePolyAnimationResult {
 }
 declare function usePolyAnimation(clips: PolyAnimationClip[] | undefined, controller: ParseAnimationController | undefined, root?: RefObject<PolyAnimationTarget | null> | PolyAnimationTarget | null): UsePolyAnimationResult;
 
-export { type DOMPassthroughProps, type InteractionProps, Poly, PolyAxesHelper, type PolyAxesHelperProps, PolyPerspectiveCamera as PolyCamera, PolyCameraContext, type PolyCameraContextValue, type PolyPerspectiveCameraProps as PolyCameraProps, type PolyControlsAnimateOptions, type PolyControlsCamera, PolyDirectionalLightHelper, type PolyDirectionalLightHelperProps, type PolyEventHandler, PolyFirstPersonControls, type PolyFirstPersonControlsHandle, type PolyFirstPersonControlsOptions, type PolyFirstPersonControlsProps, PolyGround, type PolyGroundProps, PolyMapControls, type PolyControlsCamera as PolyMapControlsCamera, type PolyMapControlsProps, PolyMesh, type PolyMeshHandle, type PolyMeshProps, type PolyMouseEvent, PolyOrbitControls, type PolyControlsCamera as PolyOrbitControlsCamera, type PolyOrbitControlsProps, PolyOrthographicCamera, type PolyOrthographicCameraProps, PolyPerspectiveCamera, type PolyPerspectiveCameraProps, type PolyPointerEvent, type PolyProps, type PolyRenderStrategiesOption, type PolyRenderStrategy, PolyScene, type PolySceneProps, PolySelect, type PolySelectProps, type PolySelectionApi, PolyTransformControls, type PolyTransformControlsObject, type PolyTransformControlsObjectChangeEvent, type PolyTransformControlsProps, type PolyWheelEvent, type SharedControlsProps, type TransformProps, type UseCameraOptions, type UseCameraResult, type UseMeshOptions, type UseMeshResult, type UsePolyAnimationResult, type UseSceneContextOptions, type UseSceneContextResult, findMeshUnderPoint, findPolyMeshHandle, injectPolyBaseStyles, pointInMeshElement, useCameraContext, usePolyAnimation, usePolyCamera, usePolyMaterial, usePolyMesh, usePolySceneContext, usePolySelect, usePolySelectionApi };
+export { type DOMPassthroughProps, type InteractionProps, Poly, PolyAxesHelper, type PolyAxesHelperProps, PolyBox, type PolyBoxProps, PolyOrthographicCamera as PolyCamera, PolyCameraContext, type PolyCameraContextValue, type PolyOrthographicCameraProps as PolyCameraProps, PolyCone, type PolyConeProps, type PolyControlsAnimateOptions, type PolyControlsCamera, PolyCylinder, type PolyCylinderProps, PolyDirectionalLightHelper, type PolyDirectionalLightHelperProps, PolyDodecahedron, type PolyDodecahedronProps, type PolyEventHandler, PolyFirstPersonControls, type PolyFirstPersonControlsHandle, type PolyFirstPersonControlsOptions, type PolyFirstPersonControlsProps, PolyGround, type PolyGroundProps, PolyIcosahedron, type PolyIcosahedronProps, PolyMapControls, type PolyControlsCamera as PolyMapControlsCamera, type PolyMapControlsProps, PolyMesh, type PolyMeshHandle, type PolyMeshProps, type PolyMouseEvent, PolyOctahedron, type PolyOctahedronProps, PolyOrbitControls, type PolyControlsCamera as PolyOrbitControlsCamera, type PolyOrbitControlsProps, PolyOrthographicCamera, type PolyOrthographicCameraProps, PolyPerspectiveCamera, type PolyPerspectiveCameraProps, PolyPlane, type PolyPlaneProps, type PolyPointerEvent, type PolyProps, type PolyRenderStats, type PolyRenderStatsOptions, type PolyRenderSurfaceLeafCounts, PolyRing, type PolyRingProps, PolyScene, type PolySceneProps, PolySelect, type PolySelectProps, type PolySelectionApi, PolySphere, type PolySphereProps, PolyTetrahedron, type PolyTetrahedronProps, PolyTorus, type PolyTorusProps, PolyTransformControls, type PolyTransformControlsObject, type PolyTransformControlsObjectChangeEvent, type PolyTransformControlsProps, type PolyWheelEvent, type SharedControlsProps, type TransformProps, type UseCameraOptions, type UseCameraResult, type UseMeshOptions, type UseMeshResult, type UsePolyAnimationResult, type UseSceneContextOptions, type UseSceneContextResult, collectPolyRenderStats, findMeshUnderPoint, findPolyMeshHandle, injectPolyBaseStyles, pointInMeshElement, useCameraContext, usePolyAnimation, usePolyCamera, usePolyMaterial, usePolyMesh, usePolySceneContext, usePolySelect, usePolySelectionApi };