@layoutit/polycss-react 0.0.1 → 0.2.0

package/dist/index.d.cts

@@ -2,7 +2,7 @@ import * as react 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';
+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';
 
 interface PolyPerspectiveCameraProps {
     zoom?: number;
@@ -36,6 +36,13 @@ declare const PolyOrthographicCamera: react.MemoExoticComponent<typeof PolyOrtho
 
 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 {
@@ -95,7 +104,21 @@ interface PolyCameraContextValue {
 declare const PolyCameraContext: react.Context<PolyCameraContextValue | null>;
 declare function useCameraContext(): PolyCameraContextValue;
 
-type AtlasScale = number | "auto";
+interface ShadowOptions {
+    color?: string;
+    opacity?: number;
+    lift?: 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.
@@ -159,14 +182,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 +220,18 @@ 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;
+    /**
+     * 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,13 +242,19 @@ interface PolySceneProps extends TransformProps {
      * origin is at a corner / feet / arbitrary point.
      */
     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?: 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 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>;
 
 type UseMeshOptions = LoadMeshOptions;
@@ -288,6 +328,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,21 +422,46 @@ 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;
+    /** 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;
+    /**
+     * 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>>;
 
+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;
 }
@@ -435,9 +509,76 @@ 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 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>;
 
+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.ForwardRefExoticComponent<PolyFirstPersonControlsProps & react.RefAttributes<PolyFirstPersonControlsHandle>>;
+
 interface PolyControlsAnimateOptions {
     /** Degrees per 60Hz-equivalent frame. Default 0.3 (≈ 18 deg/sec). */
     speed?: number;
@@ -485,14 +626,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 {
@@ -666,4 +807,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, 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 };

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import * as react 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';
+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';
 
 interface PolyPerspectiveCameraProps {
     zoom?: number;
@@ -36,6 +36,13 @@ declare const PolyOrthographicCamera: react.MemoExoticComponent<typeof PolyOrtho
 
 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 {
@@ -95,7 +104,21 @@ interface PolyCameraContextValue {
 declare const PolyCameraContext: react.Context<PolyCameraContextValue | null>;
 declare function useCameraContext(): PolyCameraContextValue;
 
-type AtlasScale = number | "auto";
+interface ShadowOptions {
+    color?: string;
+    opacity?: number;
+    lift?: 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.
@@ -159,14 +182,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 +220,18 @@ 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;
+    /**
+     * 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,13 +242,19 @@ interface PolySceneProps extends TransformProps {
      * origin is at a corner / feet / arbitrary point.
      */
     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?: 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 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>;
 
 type UseMeshOptions = LoadMeshOptions;
@@ -288,6 +328,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,21 +422,46 @@ 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;
+    /** 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;
+    /**
+     * 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>>;
 
+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;
 }
@@ -435,9 +509,76 @@ 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 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>;
 
+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.ForwardRefExoticComponent<PolyFirstPersonControlsProps & react.RefAttributes<PolyFirstPersonControlsHandle>>;
+
 interface PolyControlsAnimateOptions {
     /** Degrees per 60Hz-equivalent frame. Default 0.3 (≈ 18 deg/sec). */
     speed?: number;
@@ -485,14 +626,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 {
@@ -666,4 +807,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, 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 };