@layoutit/polycss-react 0.0.1 → 0.2.1

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 { ArrowPolygonsOptions, AutoRotateConfig, AutoRotateOption, AxesHelperOptions, BASE_TILE, CameraHandle, CameraState, CameraStyleInput, CoverPlanarPolygonsOptions, CullInteriorOptions, DEFAULT_CAMERA_STATE, DEFAULT_PROJECTION, GltfParseOptions, LoadMeshOptions, LoopMode, LoopOnce, LoopPingPong, LoopRepeat, MtlParseResult, NormalizeResult, ObjParseOptions, OctahedronPolygonsOptions, ParseAnimationClip, ParseAnimationController, ParseResult, ParsedColor, PolyAmbientLight, PolyAnimationAction, PolyAnimationClip, PolyAnimationMixer, PolyAnimationTarget, PolyDirectionalLight, PolyMaterial, PolyTextureLightingMode, Polygon, PolygonFace, RingPolygonsOptions, SceneBbox, SceneContext, SceneContextBuildArgs, SceneContextBuildResult, SolidTextureSampleOptions, TexturePaintMetrics, TexturePaintMetricsOptions, TextureTriangle, Vec2, Vec3, VoxParseOptions, arrowPolygons, axesHelperPolygons, bakeSolidTextureSampledPolygons, bakeSolidTextureSamples, buildSceneContext, clampChannel, computeSceneBbox, computeShapeLighting, computeTexturePaintMetrics, coverPlanarPolygons, createIsometricCamera, createPolyAnimationMixer, cullInteriorPolygons, formatColor, inverseRotateVec3, loadMesh, mergePolygons, normalizeInvertMultiplier, normalizePolygons, octahedronPolygons, parseColor, parseGltf, parseHexColor, parseMtl, parseObj, parsePureColor, parseRgbColor, parseVox, polygonFaces, ringPolygons, rotateVec3, shadeColor } 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,10 +32,17 @@ 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;
+    /**
+     * Bbox-center of all auto-centerable meshes in world coords. Kept separate
+     * from `target` so user pan (written to `target` by controls) survives mesh
+     * add/remove without fighting the auto-managed centering offset.
+     * [0, 0, 0] when autoCenter is off or there are no centerable meshes.
+     */
+    autoCenterOffset: Vec3;
 }
 interface SceneStore {
     getState(): SceneStoreState;
@@ -45,6 +52,8 @@ interface SceneStore {
     updateCameraFromRef(handle: CameraHandle): boolean;
     /** Force notify all subscribers (e.g. after prop-driven camera change). */
     notifyAll(): void;
+    /** Update the autoCenterOffset (world coords bbox center). */
+    setAutoCenterOffset(offset: Vec3): void;
 }
 
 interface UseCameraOptions {
@@ -92,10 +101,21 @@ interface PolyCameraContextValue {
      */
     applyTransformDirect: () => void;
 }
-declare const PolyCameraContext: react.Context<PolyCameraContextValue | null>;
+declare const PolyCameraContext: React$1.Context<PolyCameraContextValue | null>;
 declare function useCameraContext(): PolyCameraContextValue;
 
-type AtlasScale = number | "auto";
+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;
+}
 
 /**
  * Three.js-style transform props accepted by every polycss component.
@@ -159,14 +179,15 @@ interface PolyProps extends TransformProps, DOMPassthroughProps {
         layerElevation?: number;
         directionalLight?: PolyDirectionalLight;
         textureLighting?: PolyTextureLightingMode;
-        atlasScale?: AtlasScale;
+        textureQuality?: TextureQuality;
         debugShowBackfaces?: boolean;
         [key: string]: unknown;
     };
     /** Textured polygon lighting mode. Defaults to scene context, then "baked". */
     textureLighting?: PolyTextureLightingMode;
-    /** Raster scale for generated atlas pages. `"auto"` reduces large atlases. */
-    atlasScale?: AtlasScale;
+    /** Atlas bitmap budget and CSS sprite size. `"auto"` (default) uses a
+     *  device-appropriate memory budget and desktop/mobile sprite sizing. */
+    textureQuality?: TextureQuality;
     /** Pre-computed shaded base color from the parent (optional override). */
     baseColor?: string;
 }
@@ -196,8 +217,20 @@ interface PolySceneProps extends TransformProps {
     ambientLight?: PolyAmbientLight;
     /** Textured polygon lighting mode. Defaults to "baked". */
     textureLighting?: PolyTextureLightingMode;
-    /** Raster scale for generated atlas pages. `"auto"` reduces large atlases. */
-    atlasScale?: AtlasScale;
+    /** Atlas bitmap budget and CSS sprite size. `"auto"` (default) uses a
+     *  device-appropriate memory budget (~4 MB mobile / ~16 MB desktop) and
+     *  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"] }`
+     * to force every polygon through the atlas. Mirrors the same option on
+     * `renderPolygonsWithTextureAtlas` in `@layoutit/polycss`.
+     */
+    strategies?: PolyRenderStrategiesOption;
     /**
      * When `true`, rotation pivots around the mesh's bbox center instead of
      * world (0,0,0). Polygon data is not mutated — the scene element's
@@ -208,18 +241,27 @@ interface PolySceneProps extends TransformProps {
      * origin is at a corner / feet / arbitrary point.
      */
     autoCenter?: boolean;
+    /**
+     * 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;
     style?: CSSProperties;
     children?: ReactNode;
     debugShowLabels?: boolean;
     debugShowBackfaces?: boolean;
 }
-declare function PolySceneInner({ polygons: polygonsProp, centerPolygons: centerPolygonsProp, perspective: _perspective, rotX: _rotX, rotY: _rotY, zoom: _zoom, directionalLight, ambientLight, textureLighting, atlasScale, autoCenter, 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[];
@@ -231,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.
  *
@@ -266,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
@@ -288,6 +336,15 @@ interface PolyMeshHandle {
      * safe to call.
      */
     rebakeAtlas(): void;
+    /**
+     * Mutate a single polygon in place and re-render the mesh. `target` is
+     * either a polygon reference (as returned by `getPolygons()`) or its index.
+     * `partial` fields are merged onto the polygon via `Object.assign`. Skips
+     * the merge pass — cheaper than a full prop change for targeted edits like
+     * color picker updates from an inspector UI. Silently no-ops when `target`
+     * is not found or the index is out of range.
+     */
+    updatePolygon(target: Polygon | number, partial: Partial<Polygon>): void;
 }
 /**
  * Pointer event payload delivered to <PolyMesh> handlers. Mirrors r3f's
@@ -373,20 +430,51 @@ interface PolyMeshProps extends TransformProps, InteractionProps {
     autoCenter?: boolean;
     /** Textured polygon lighting mode. Defaults to "baked". */
     textureLighting?: PolyTextureLightingMode;
-    /** Raster scale for generated atlas pages. `"auto"` reduces large atlases. */
-    atlasScale?: AtlasScale;
-    /** Per-polygon override render. Receives the polygon + its index. */
-    children?: (polygon: Polygon, index: number) => ReactNode;
+    /** Atlas bitmap budget and CSS sprite size. `"auto"` (default) uses a
+     *  device-appropriate memory budget (~4 MB mobile / ~16 MB desktop) and
+     *  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. */
     fallback?: ReactNode;
     /** Error slot — rendered if parse fails. Receives the Error. */
     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.
+     * The shadow is projected onto the ground plane along the CSS-space light
+     * direction via `--shadow-proj` (a CSS var on the scene root). Zero JS in
+     * the render loop — projection is pure `calc()`. Defaults to `false`.
+     */
+    castShadow?: boolean;
     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`. */
+    size?: number;
+    /** World-space Z (floor height). Default `0`. */
+    z?: number;
+    /** World-space XY center. Default `[0, 0]`. */
+    center?: [number, number];
+    /** Fill color. Default `#7d848e` — medium gray, chosen so the 25% black
+     *  `<q>` shadow leaves on top have visible contrast against it. */
+    color?: string;
+    className?: string;
+}
+declare function PolyGround({ size, z, center, color, className, }: PolyGroundProps): react_jsx_runtime.JSX.Element;
 
 interface UseSceneContextOptions {
     directionalLight?: PolyDirectionalLight;
@@ -399,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
@@ -435,8 +523,110 @@ declare function usePolyMaterial(options: {
  * check is sound here because polygon data (vertices, color, texture) is
  * 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, atlasScale: atlasScaleProp, baseColor: baseColorProp, ...dataAttrs }: PolyProps): react_jsx_runtime.JSX.Element | null;
-declare const Poly: react__default.MemoExoticComponent<typeof PolyInner>;
+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>;
+
+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`. */
+    enabled?: boolean;
+    /** Pointer-lock mouselook (rotX = pitch, rotY = yaw). Default: `true`. */
+    lookEnabled?: boolean;
+    /** WASD / arrow-key planar movement on world XY. Default: `true`. */
+    moveEnabled?: boolean;
+    /** Space-bar parametric jump arc on world Z. Default: `true`. */
+    jumpEnabled?: boolean;
+    /** Ctrl crouch (lowers eye height while held). Default: `true`. */
+    crouchEnabled?: boolean;
+    /** Mouselook sensitivity in degrees per pixel. Default: `0.15`. */
+    lookSensitivity?: number;
+    /** Invert vertical mouselook. Default: `false`. */
+    invertY?: boolean;
+    /** Movement speed in world units per second. Default: `5`. */
+    moveSpeed?: number;
+    /** Initial vertical velocity for a jump, world units per second. Default: `7`. */
+    jumpVelocity?: number;
+    /** Gravity acceleration in world units per second squared. Default: `18`. */
+    gravity?: number;
+    /** Standing eye height above the ground plane. Default: `1.7`. */
+    eyeHeight?: number;
+    /** Eye height while crouching. Default: `1`. */
+    crouchHeight?: number;
+    /** World Z of the ground plane the player walks on. Default: `0`. */
+    groundZ?: number;
+    /** Min pitch (rotX) angle in degrees. Default: `5`. */
+    minPitch?: number;
+    /** Max pitch (rotX) angle in degrees. Default: `175`. */
+    maxPitch?: number;
+}
+interface PolyFirstPersonControlsHandle {
+    update(partial: PolyFirstPersonControlsOptions): void;
+    resume(): void;
+    pause(): void;
+    destroy(): void;
+    /** Request pointer-lock now. Call from a user gesture (click). */
+    lock(): void;
+    /** Release pointer-lock. */
+    unlock(): void;
+    /** Whether pointer-lock is currently held. */
+    isLocked(): boolean;
+    /**
+     * The camera's WORLD position (the eye). Snapshot — mutate via WASD /
+     * jump / crouch, or by calling `setOrigin`.
+     */
+    getOrigin(): [number, number, number];
+    /**
+     * Move the camera origin to a specific world position. Re-derives the
+     * scene's target so the perspective viewer follows.
+     */
+    setOrigin(origin: [number, number, number]): void;
+    addEventListener(type: "change" | "start" | "end", listener: () => void): void;
+    removeEventListener(type: "change" | "start" | "end", listener: () => void): void;
+    hasEventListener(type: "change" | "start" | "end", listener: () => void): boolean;
+}
+interface PolyFirstPersonControlsProps extends PolyFirstPersonControlsOptions {
+    /** Called on every camera state change (mouselook, WASD, jump, crouch). */
+    onChange?: () => void;
+    /** Called when pointer-lock is acquired (interaction starts). */
+    onInteractionStart?: () => void;
+    /** Called when pointer-lock is released (interaction ends). */
+    onInteractionEnd?: () => void;
+}
+declare const PolyFirstPersonControls: React$1.ForwardRefExoticComponent<PolyFirstPersonControlsProps & React$1.RefAttributes<PolyFirstPersonControlsHandle>>;
 
 interface PolyControlsAnimateOptions {
     /** Degrees per 60Hz-equivalent frame. Default 0.3 (≈ 18 deg/sec). */
@@ -485,14 +675,14 @@ interface SharedControlsProps {
     onInteractionEnd?: (camera: PolyControlsCamera) => void;
 }
 
-interface PolyOrbitControlsProps extends SharedControlsProps {
-}
-declare function PolyOrbitControls({ drag, wheel, dolly, invert, minZoom, maxZoom, minDistance, maxDistance, animate, onChange, onInteractionStart, onInteractionEnd, }: PolyOrbitControlsProps): null;
-
 interface PolyMapControlsProps extends SharedControlsProps {
 }
 declare function PolyMapControls({ drag, wheel, dolly, invert, minZoom, maxZoom, minDistance, maxDistance, animate, onChange, onInteractionStart, onInteractionEnd, }: PolyMapControlsProps): null;
 
+interface PolyOrbitControlsProps extends SharedControlsProps {
+}
+declare function PolyOrbitControls({ drag, wheel, dolly, invert, minZoom, maxZoom, minDistance, maxDistance, animate, onChange, onInteractionStart, onInteractionEnd, }: PolyOrbitControlsProps): null;
+
 /** Optional ref-or-direct binding to a target mesh. */
 type PolyTransformControlsObject = PolyMeshHandle | RefObject<PolyMeshHandle | null> | null;
 interface PolyTransformControlsObjectChangeEvent {
@@ -648,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>;
@@ -666,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, 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, 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 };