@layoutit/polycss-react 0.2.5 → 0.2.7

package/dist/index.d.cts

@@ -2,8 +2,8 @@ import * as React$1 from 'react';
 import React__default, { ReactNode, CSSProperties, MouseEventHandler, PointerEventHandler, FocusEventHandler, KeyboardEventHandler, IframeHTMLAttributes, RefObject, MouseEvent as MouseEvent$1 } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as _layoutit_polycss_core 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, OptimizeMeshParseResultOptions, OptimizeMeshPolygonsOptions, ParseAnimationClip, ParseAnimationController, ParseResult, ParseStlColor, ParseStlSolid, ParseStlTopology, ParsedColor, PlanePolygonsOptions, PolyAmbientLight, PolyAnimationAction, PolyAnimationClip, PolyAnimationMixer, PolyAnimationTarget, PolyDirectionalLight, PolyMaterial, PolyMeshTransformInput, PolyRenderStrategiesOption, PolyRenderStrategy, PolySceneTransformInput, PolyTextureLightingMode, Polygon, PolygonFace, RingPolygonsOptions, SceneBbox, SceneContext, SceneContextBuildArgs, SceneContextBuildResult, SeamFacetSplitCandidate, SeamFacetSplitCandidateReason, SeamFacetSplitOptions, SeamFacetSplitReport, SeamOverlapCandidate, SeamOverlapCandidateKind, SeamOverlapDiagnostics, SeamOverlapOptions, SimplifyTriangleMeshPolygonsOptions, SolidTextureSampleOptions, StlParseOptions, TetrahedronPolygonsOptions, TexturePaintMetrics, TexturePaintMetricsOptions, TextureTriangle, TorusPolygonsOptions, VOXEL_CAMERA_CULL_AXIS_EPS, VOXEL_CAMERA_CULL_NORMAL_LIMIT, Vec2, Vec3, VoxParseOptions, arrowPolygons, axesHelperPolygons, bakeSolidTextureSampledPolygons, bakeSolidTextureSamples, boxPolygons, buildPolyMeshTransform, buildPolySceneTransform, 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, optimizeMeshParseResult, optimizeMeshPolygons, parseColor, parseGltf, parseHexColor, parseMtl, parseObj, parsePureColor, parseRgbColor, parseStl, parseVox, planePolygons, cssDistanceToWorld as polyCssDistanceToWorld, cssPositionToWorld as polyCssPositionToWorld, polygonCssSurfaceNormal, polygonFaces, polygonFacesCamera, repairMeshSeams, ringPolygons, rotateVec3, seamFacetSplitPolygons, seamFacetSplitReport, seamOverlapDiagnostics, seamOverlapPolygons, seamOverlapReport, shadeColor, simplifyTriangleMeshPolygons, tetrahedronPolygons, torusPolygons, worldDirectionToCss as worldDirectionToPolyCss, worldDirectionalLightToCss as worldDirectionalLightToPolyCss, worldDistanceToCss as worldDistanceToPolyCss, worldPositionToCss as worldPositionToPolyCss } from '@layoutit/polycss-core';
+import { Vec3, CameraState, CameraHandle, PolyCameraProjection, PolyTextureImageSource, PolyTexturePresentation, Vec2, PolyMaterial, PolyDirectionalLight, PolyTextureLightingMode, TextureQuality, PolyTextureLeafSizing, PolyTextureImageRendering, PolyTextureBackend, PolyTextureProjection, Polygon, PolyPointLight, 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, OptimizeMeshParseResultOptions, OptimizeMeshPolygonsOptions, ParseAnimationClip, ParseAnimationController, ParseResult, ParseStlColor, ParseStlSolid, ParseStlTopology, ParsedColor, PlanePolygonsOptions, PolyAmbientLight, PolyAnimationAction, PolyAnimationClip, PolyAnimationMixer, PolyAnimationTarget, PolyCameraProjection, PolyCameraSnapshot, PolyCameraSnapshotOptions, PolyCameraSnapshotSource, PolyDirectionalLight, PolyMaterial, PolyMeshTransformInput, PolyRenderStrategiesOption, PolyRenderStrategy, PolySceneTransformInput, PolyTextureBackend, PolyTextureImageLighting, PolyTextureImageRendering, PolyTextureImageSource, PolyTextureLeafSizing, PolyTextureLightingMode, PolyTexturePresentation, PolyTextureProjection, Polygon, PolygonFace, RingPolygonsOptions, SceneBbox, SceneContext, SceneContextBuildArgs, SceneContextBuildResult, SeamFacetSplitCandidate, SeamFacetSplitCandidateReason, SeamFacetSplitOptions, SeamFacetSplitReport, SeamOverlapCandidate, SeamOverlapCandidateKind, SeamOverlapDiagnostics, SeamOverlapOptions, SimplifyTriangleMeshPolygonsOptions, SolidTextureSampleOptions, StlParseOptions, TetrahedronPolygonsOptions, TexturePaintMetrics, TexturePaintMetricsOptions, TextureTriangle, TorusPolygonsOptions, VOXEL_CAMERA_CULL_AXIS_EPS, VOXEL_CAMERA_CULL_NORMAL_LIMIT, Vec2, Vec3, VoxParseOptions, arrowPolygons, axesHelperPolygons, bakeSolidTextureSampledPolygons, bakeSolidTextureSamples, boxPolygons, buildPolyCameraSceneTransform, buildPolyMeshTransform, buildPolySceneTransform, buildSceneContext, cameraCullNormalGroups, cameraCullNormalGroupsFromPolygons, cameraCullNormalKey, cameraCullVisibleSignature, cameraFacingDepth, capturePolyCameraSnapshot, clampChannel, computeSceneBbox, computeShapeLighting, computeTexturePaintMetrics, conePolygons, coverPlanarPolygons, createIsometricCamera, createPolyAnimationMixer, cssDistanceToWorld, cssPositionToWorld, cullInteriorPolygons, cylinderPolygons, dodecahedronPolygons, formatColor, icosahedronPolygons, inverseRotateVec3, isAxisAlignedSurfaceNormal, isVoxelCameraCullableNormalGroups, loadMesh, mergePolygons, normalFacesCamera, normalizeInvertMultiplier, normalizePolygons, octahedronPolygons, optimizeAnimatedMeshPolygons, optimizeMeshParseResult, optimizeMeshPolygons, parseColor, parseGltf, parseHexColor, parseMtl, parseObj, parsePureColor, parseRgbColor, parseStl, parseVox, planePolygons, polyCameraTargetToCss, polyCssDistanceToWorld, polyCssPositionToWorld, polygonCssSurfaceNormal, polygonFaces, polygonFacesCamera, repairMeshSeams, resolvePolyCameraAppliedPerspectiveStyle, ringPolygons, rotateVec3, seamFacetSplitPolygons, seamFacetSplitReport, seamOverlapDiagnostics, seamOverlapPolygons, seamOverlapReport, shadeColor, simplifyTriangleMeshPolygons, tetrahedronPolygons, torusPolygons, worldDirectionToCss, worldDirectionToPolyCss, worldDirectionalLightToCss, worldDirectionalLightToPolyCss, worldDistanceToCss, worldDistanceToPolyCss, worldPositionToCss, worldPositionToPolyCss } from '@layoutit/polycss-core';
 
 interface PolyPerspectiveCameraProps {
     zoom?: number;
@@ -63,6 +63,8 @@ interface UseCameraOptions {
     rotX?: number;
     rotY?: number;
     distance?: number;
+    projection?: PolyCameraProjection;
+    perspectiveStyle?: string;
 }
 interface UseCameraResult {
     store: SceneStore;
@@ -116,6 +118,32 @@ interface ShadowOptions {
      * disable the cap entirely.
      */
     maxExtend?: number;
+    /**
+     * Cast a low-resolution parametric silhouette per caster instead of its full
+     * geometry — lighter DOM + cheaper projection at the cost of an approximate
+     * outline. Casts onto every receiver through the normal pipeline. Default:
+     * `false`. (Directional + point lights; the exact path stays the default.)
+     */
+    parametric?: boolean;
+    /**
+     * Parametric-shadow detail (max silhouette points / pixel-grid resolution).
+     * Only used when `parametric` is true. Default: `16`. Override per mesh via
+     * `<PolyMesh shadowDefinition>`.
+     */
+    definition?: number;
+    /**
+     * Parametric render style: `"vector"` (smooth contour, default) or `"pixel"`
+     * (greedy-meshed voxel blocks; `definition` becomes the grid resolution).
+     */
+    style?: "vector" | "pixel";
+    /**
+     * Re-emit a caster's shadow while it animates (deforms) so the shadow follows
+     * the pose instead of freezing. Default `false`: a same-topology deform keeps
+     * the last shadow pose (re-emitting every frame is expensive). Best with
+     * `parametric` — a low-res silhouette is cheap to reproject. Topology changes
+     * (different polygon count) always re-emit regardless.
+     */
+    followAnimation?: boolean;
 }
 
 /** Three.js-style transform props accepted by every PolyCSS component. */
@@ -164,8 +192,11 @@ interface PolyProps extends TransformProps, DOMPassthroughProps {
     vertices: Vec3[];
     color?: string;
     texture?: string;
+    textureImageSource?: PolyTextureImageSource;
+    texturePresentation?: PolyTexturePresentation;
     uvs?: Vec2[];
     data?: Record<string, string | number | boolean>;
+    doubleSided?: boolean;
     /** Shared material. When set AND the polygon's UVs form an axis-aligned
      *  rectangle, renders via `background-image` directly — no per-polygon
      *  canvas rasterization. Falls back to the atlas path otherwise. */
@@ -176,6 +207,10 @@ interface PolyProps extends TransformProps, DOMPassthroughProps {
         directionalLight?: PolyDirectionalLight;
         textureLighting?: PolyTextureLightingMode;
         textureQuality?: TextureQuality;
+        textureLeafSizing?: PolyTextureLeafSizing;
+        textureImageRendering?: PolyTextureImageRendering;
+        textureBackend?: PolyTextureBackend;
+        textureProjection?: PolyTextureProjection;
         debugShowBackfaces?: boolean;
         [key: string]: unknown;
     };
@@ -184,6 +219,14 @@ interface PolyProps extends TransformProps, DOMPassthroughProps {
     /** Atlas bitmap budget and CSS sprite size. `"auto"` (default) uses a
      *  device-appropriate memory budget and desktop/mobile sprite sizing. */
     textureQuality?: TextureQuality;
+    /** Atlas leaf CSS primitive sizing. Defaults to scene context, then canonical. */
+    textureLeafSizing?: PolyTextureLeafSizing;
+    /** Default image filtering for atlas and direct image texture leaves. */
+    textureImageRendering?: PolyTextureImageRendering;
+    /** Default texture backend request. Defaults to scene context, then "auto". */
+    textureBackend?: PolyTextureBackend;
+    /** Default texture projection request. Defaults to scene context, then "affine". */
+    textureProjection?: PolyTextureProjection;
     /** Pre-computed shaded base color from the parent (optional override). */
     baseColor?: string;
 }
@@ -210,6 +253,9 @@ interface PolySceneProps extends TransformProps {
     rotY?: number;
     zoom?: number;
     directionalLight?: PolyDirectionalLight;
+    /** Point lights (world-space positions). Direction-only per-face Lambert,
+     *  baked-mode only. */
+    pointLights?: PolyPointLight[];
     ambientLight?: PolyAmbientLight;
     /** Textured polygon lighting mode. Defaults to "baked". */
     textureLighting?: PolyTextureLightingMode;
@@ -218,6 +264,14 @@ interface PolySceneProps extends TransformProps {
      *  desktop/mobile sprite sizing. Numeric values 0.1..1 force an explicit
      *  raster scale and the 64px sprite. */
     textureQuality?: TextureQuality;
+    /** Atlas leaf CSS primitive sizing. Defaults to canonical browser-fast sizing. */
+    textureLeafSizing?: PolyTextureLeafSizing;
+    /** Default image filtering for atlas and direct image texture leaves. */
+    textureImageRendering?: PolyTextureImageRendering;
+    /** Default texture backend request. Defaults to "auto". */
+    textureBackend?: PolyTextureBackend;
+    /** Default texture projection request. Defaults to "affine". */
+    textureProjection?: PolyTextureProjection;
     /** Solid seam overscan. `"auto"` computes a fitted per-edge amount from the polygon plan. */
     seamBleed?: PolySeamBleed;
     /**
@@ -250,7 +304,7 @@ 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, seamBleed, strategies, autoCenter, shadow, 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, pointLights, ambientLight, textureLighting, textureQuality, textureLeafSizing, textureImageRendering, textureBackend, textureProjection, 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;
@@ -331,6 +385,8 @@ interface PolyMeshHandle {
      * safe to call.
      */
     rebakeAtlas(): void;
+    /** Resolves when this mesh's current texture generation has usable backgrounds. */
+    whenTexturesReady(): Promise<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.
@@ -438,6 +494,14 @@ 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;
+    /** Atlas leaf CSS primitive sizing. Defaults to scene context, then canonical. */
+    textureLeafSizing?: PolyTextureLeafSizing;
+    /** Default image filtering for atlas and direct image texture leaves. */
+    textureImageRendering?: PolyTextureImageRendering;
+    /** Default texture backend request. Defaults to scene context, then "auto". */
+    textureBackend?: PolyTextureBackend;
+    /** Default texture projection request. Defaults to scene context, then "affine". */
+    textureProjection?: PolyTextureProjection;
     /** Solid seam overscan. `"auto"` computes a fitted per-edge amount from the polygon plan. */
     seamBleed?: PolySeamBleed;
     /**
@@ -476,6 +540,12 @@ interface PolyMeshProps extends TransformProps, InteractionProps {
      * for caster meshes — receivers handle shadow display. Defaults to `false`.
      */
     receiveShadow?: boolean;
+    /**
+     * Per-mesh parametric-shadow detail, overriding the scene's
+     * `shadow.definition` for this mesh's cast/self shadow. Only used when the
+     * scene's `shadow.parametric` is true. Unset → inherit the scene definition.
+     */
+    shadowDefinition?: number;
     /**
      * Apply mesh optimization (coplanar merge + interior cull) before
      * rendering. Defaults to `true` — matches vanilla `scene.add`'s default.
@@ -580,7 +650,7 @@ 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, textureQuality: textureQualityProp, baseColor: baseColorProp, ...dataAttrs }: PolyProps): react_jsx_runtime.JSX.Element | null;
+declare function PolyInner({ vertices, color, texture, textureImageSource, texturePresentation, uvs, data, doubleSided, 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, textureLeafSizing: textureLeafSizingProp, textureImageRendering: textureImageRenderingProp, textureBackend: textureBackendProp, textureProjection: textureProjectionProp, 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">;
@@ -902,11 +972,84 @@ interface PolyRenderSurfaceLeafCounts {
     atlas: number;
     stableTriangle: number;
 }
+type PolyRenderLeafStrategy = keyof PolyRenderSurfaceLeafCounts;
+interface PolyTextureReadiness {
+    ready: boolean;
+    textureLeafCount: number;
+    readyTextureLeafCount: number;
+    pendingTextureLeafCount: number;
+    atlasTextureLeafCount: number;
+    imageTextureLeafCount: number;
+}
+interface PolyTextureRenderStats {
+    ready: boolean;
+    leafCount: number;
+    atlasCount: number;
+    imageCount: number;
+    pendingCount: number;
+    sizingCounts: {
+        canonical: number;
+        local: number;
+        raster: number;
+        image: number;
+        unknown: number;
+    };
+    imageRenderingCounts: {
+        auto: number;
+        pixelated: number;
+        unknown: number;
+    };
+    projectionCounts: {
+        affine: number;
+        projective: number;
+        fallback: number;
+        unknown: number;
+    };
+    minLeafWidth: number;
+    maxLeafWidth: number;
+    minLeafHeight: number;
+    maxLeafHeight: number;
+    doubleSidedCount: number;
+}
+interface PolySnapshotRenderStats {
+    runtimeAtlasUrlCount: number;
+    snapshotAtlasCount: number;
+    snapshotBackgroundCount: number;
+    selfContained: boolean;
+}
+interface PolyCameraSnapshotStats {
+    rootFound: boolean;
+    projection: "orthographic" | "perspective" | "unknown";
+    perspectiveStyle: string;
+    appliedPerspectiveStyle: string;
+    zoom?: number;
+    distance?: number;
+    rotX?: number;
+    rotY?: number;
+    target?: [number, number, number];
+}
+interface PolyLeafInfo {
+    element: HTMLElement;
+    strategy: PolyRenderLeafStrategy;
+    polygonIndex?: number;
+    textureBackend?: string;
+    textureReady?: boolean;
+    textureLeafSizing?: string;
+    textureImageRendering?: string;
+    textureProjection?: string;
+    textureLeafWidth?: number;
+    textureLeafHeight?: number;
+    doubleSided?: boolean;
+}
 interface PolyRenderStats {
     polygonCount: number;
     mountedPolygonLeafCount: number;
     shadowLeafCount: number;
     surfaceLeafCounts: PolyRenderSurfaceLeafCounts;
+    textureReadiness: PolyTextureReadiness;
+    textureStats: PolyTextureRenderStats;
+    snapshotStats: PolySnapshotRenderStats;
+    cameraStats: PolyCameraSnapshotStats;
     bucketCount: number;
 }
 interface PolyRenderStatsOptions {
@@ -917,6 +1060,8 @@ interface PolyRenderStatsOptions {
      */
     scopeSelector?: string;
 }
+declare function queryPolyLeaves(root: ParentNode | null | undefined, optionsOrPolygonCount?: number | PolyRenderStatsOptions): PolyLeafInfo[];
+declare function collectPolyTextureReadiness(root: ParentNode | null | undefined, optionsOrPolygonCount?: number | PolyRenderStatsOptions): PolyTextureReadiness;
 declare function collectPolyRenderStats(root: ParentNode | null | undefined, optionsOrPolygonCount?: number | PolyRenderStatsOptions): PolyRenderStats;
 
 interface UsePolyAnimationResult {
@@ -937,4 +1082,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, 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, PolyIframe, type PolyIframeProps, 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 };
+export { type DOMPassthroughProps, type InteractionProps, Poly, PolyAxesHelper, type PolyAxesHelperProps, PolyBox, type PolyBoxProps, PolyOrthographicCamera as PolyCamera, PolyCameraContext, type PolyCameraContextValue, type PolyOrthographicCameraProps as PolyCameraProps, type PolyCameraSnapshotStats, 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, PolyIframe, type PolyIframeProps, type PolyLeafInfo, 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 PolyRenderLeafStrategy, type PolyRenderStats, type PolyRenderStatsOptions, type PolyRenderSurfaceLeafCounts, PolyRing, type PolyRingProps, PolyScene, type PolySceneProps, PolySelect, type PolySelectProps, type PolySelectionApi, type PolySnapshotRenderStats, PolySphere, type PolySphereProps, PolyTetrahedron, type PolyTetrahedronProps, type PolyTextureReadiness, type PolyTextureRenderStats, 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, collectPolyTextureReadiness, findMeshUnderPoint, findPolyMeshHandle, injectPolyBaseStyles, pointInMeshElement, queryPolyLeaves, useCameraContext, usePolyAnimation, usePolyCamera, usePolyMaterial, usePolyMesh, usePolySceneContext, usePolySelect, usePolySelectionApi };

package/dist/index.d.ts

@@ -2,8 +2,8 @@ import * as React$1 from 'react';
 import React__default, { ReactNode, CSSProperties, MouseEventHandler, PointerEventHandler, FocusEventHandler, KeyboardEventHandler, IframeHTMLAttributes, RefObject, MouseEvent as MouseEvent$1 } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as _layoutit_polycss_core 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, OptimizeMeshParseResultOptions, OptimizeMeshPolygonsOptions, ParseAnimationClip, ParseAnimationController, ParseResult, ParseStlColor, ParseStlSolid, ParseStlTopology, ParsedColor, PlanePolygonsOptions, PolyAmbientLight, PolyAnimationAction, PolyAnimationClip, PolyAnimationMixer, PolyAnimationTarget, PolyDirectionalLight, PolyMaterial, PolyMeshTransformInput, PolyRenderStrategiesOption, PolyRenderStrategy, PolySceneTransformInput, PolyTextureLightingMode, Polygon, PolygonFace, RingPolygonsOptions, SceneBbox, SceneContext, SceneContextBuildArgs, SceneContextBuildResult, SeamFacetSplitCandidate, SeamFacetSplitCandidateReason, SeamFacetSplitOptions, SeamFacetSplitReport, SeamOverlapCandidate, SeamOverlapCandidateKind, SeamOverlapDiagnostics, SeamOverlapOptions, SimplifyTriangleMeshPolygonsOptions, SolidTextureSampleOptions, StlParseOptions, TetrahedronPolygonsOptions, TexturePaintMetrics, TexturePaintMetricsOptions, TextureTriangle, TorusPolygonsOptions, VOXEL_CAMERA_CULL_AXIS_EPS, VOXEL_CAMERA_CULL_NORMAL_LIMIT, Vec2, Vec3, VoxParseOptions, arrowPolygons, axesHelperPolygons, bakeSolidTextureSampledPolygons, bakeSolidTextureSamples, boxPolygons, buildPolyMeshTransform, buildPolySceneTransform, 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, optimizeMeshParseResult, optimizeMeshPolygons, parseColor, parseGltf, parseHexColor, parseMtl, parseObj, parsePureColor, parseRgbColor, parseStl, parseVox, planePolygons, cssDistanceToWorld as polyCssDistanceToWorld, cssPositionToWorld as polyCssPositionToWorld, polygonCssSurfaceNormal, polygonFaces, polygonFacesCamera, repairMeshSeams, ringPolygons, rotateVec3, seamFacetSplitPolygons, seamFacetSplitReport, seamOverlapDiagnostics, seamOverlapPolygons, seamOverlapReport, shadeColor, simplifyTriangleMeshPolygons, tetrahedronPolygons, torusPolygons, worldDirectionToCss as worldDirectionToPolyCss, worldDirectionalLightToCss as worldDirectionalLightToPolyCss, worldDistanceToCss as worldDistanceToPolyCss, worldPositionToCss as worldPositionToPolyCss } from '@layoutit/polycss-core';
+import { Vec3, CameraState, CameraHandle, PolyCameraProjection, PolyTextureImageSource, PolyTexturePresentation, Vec2, PolyMaterial, PolyDirectionalLight, PolyTextureLightingMode, TextureQuality, PolyTextureLeafSizing, PolyTextureImageRendering, PolyTextureBackend, PolyTextureProjection, Polygon, PolyPointLight, 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, OptimizeMeshParseResultOptions, OptimizeMeshPolygonsOptions, ParseAnimationClip, ParseAnimationController, ParseResult, ParseStlColor, ParseStlSolid, ParseStlTopology, ParsedColor, PlanePolygonsOptions, PolyAmbientLight, PolyAnimationAction, PolyAnimationClip, PolyAnimationMixer, PolyAnimationTarget, PolyCameraProjection, PolyCameraSnapshot, PolyCameraSnapshotOptions, PolyCameraSnapshotSource, PolyDirectionalLight, PolyMaterial, PolyMeshTransformInput, PolyRenderStrategiesOption, PolyRenderStrategy, PolySceneTransformInput, PolyTextureBackend, PolyTextureImageLighting, PolyTextureImageRendering, PolyTextureImageSource, PolyTextureLeafSizing, PolyTextureLightingMode, PolyTexturePresentation, PolyTextureProjection, Polygon, PolygonFace, RingPolygonsOptions, SceneBbox, SceneContext, SceneContextBuildArgs, SceneContextBuildResult, SeamFacetSplitCandidate, SeamFacetSplitCandidateReason, SeamFacetSplitOptions, SeamFacetSplitReport, SeamOverlapCandidate, SeamOverlapCandidateKind, SeamOverlapDiagnostics, SeamOverlapOptions, SimplifyTriangleMeshPolygonsOptions, SolidTextureSampleOptions, StlParseOptions, TetrahedronPolygonsOptions, TexturePaintMetrics, TexturePaintMetricsOptions, TextureTriangle, TorusPolygonsOptions, VOXEL_CAMERA_CULL_AXIS_EPS, VOXEL_CAMERA_CULL_NORMAL_LIMIT, Vec2, Vec3, VoxParseOptions, arrowPolygons, axesHelperPolygons, bakeSolidTextureSampledPolygons, bakeSolidTextureSamples, boxPolygons, buildPolyCameraSceneTransform, buildPolyMeshTransform, buildPolySceneTransform, buildSceneContext, cameraCullNormalGroups, cameraCullNormalGroupsFromPolygons, cameraCullNormalKey, cameraCullVisibleSignature, cameraFacingDepth, capturePolyCameraSnapshot, clampChannel, computeSceneBbox, computeShapeLighting, computeTexturePaintMetrics, conePolygons, coverPlanarPolygons, createIsometricCamera, createPolyAnimationMixer, cssDistanceToWorld, cssPositionToWorld, cullInteriorPolygons, cylinderPolygons, dodecahedronPolygons, formatColor, icosahedronPolygons, inverseRotateVec3, isAxisAlignedSurfaceNormal, isVoxelCameraCullableNormalGroups, loadMesh, mergePolygons, normalFacesCamera, normalizeInvertMultiplier, normalizePolygons, octahedronPolygons, optimizeAnimatedMeshPolygons, optimizeMeshParseResult, optimizeMeshPolygons, parseColor, parseGltf, parseHexColor, parseMtl, parseObj, parsePureColor, parseRgbColor, parseStl, parseVox, planePolygons, polyCameraTargetToCss, polyCssDistanceToWorld, polyCssPositionToWorld, polygonCssSurfaceNormal, polygonFaces, polygonFacesCamera, repairMeshSeams, resolvePolyCameraAppliedPerspectiveStyle, ringPolygons, rotateVec3, seamFacetSplitPolygons, seamFacetSplitReport, seamOverlapDiagnostics, seamOverlapPolygons, seamOverlapReport, shadeColor, simplifyTriangleMeshPolygons, tetrahedronPolygons, torusPolygons, worldDirectionToCss, worldDirectionToPolyCss, worldDirectionalLightToCss, worldDirectionalLightToPolyCss, worldDistanceToCss, worldDistanceToPolyCss, worldPositionToCss, worldPositionToPolyCss } from '@layoutit/polycss-core';
 
 interface PolyPerspectiveCameraProps {
     zoom?: number;
@@ -63,6 +63,8 @@ interface UseCameraOptions {
     rotX?: number;
     rotY?: number;
     distance?: number;
+    projection?: PolyCameraProjection;
+    perspectiveStyle?: string;
 }
 interface UseCameraResult {
     store: SceneStore;
@@ -116,6 +118,32 @@ interface ShadowOptions {
      * disable the cap entirely.
      */
     maxExtend?: number;
+    /**
+     * Cast a low-resolution parametric silhouette per caster instead of its full
+     * geometry — lighter DOM + cheaper projection at the cost of an approximate
+     * outline. Casts onto every receiver through the normal pipeline. Default:
+     * `false`. (Directional + point lights; the exact path stays the default.)
+     */
+    parametric?: boolean;
+    /**
+     * Parametric-shadow detail (max silhouette points / pixel-grid resolution).
+     * Only used when `parametric` is true. Default: `16`. Override per mesh via
+     * `<PolyMesh shadowDefinition>`.
+     */
+    definition?: number;
+    /**
+     * Parametric render style: `"vector"` (smooth contour, default) or `"pixel"`
+     * (greedy-meshed voxel blocks; `definition` becomes the grid resolution).
+     */
+    style?: "vector" | "pixel";
+    /**
+     * Re-emit a caster's shadow while it animates (deforms) so the shadow follows
+     * the pose instead of freezing. Default `false`: a same-topology deform keeps
+     * the last shadow pose (re-emitting every frame is expensive). Best with
+     * `parametric` — a low-res silhouette is cheap to reproject. Topology changes
+     * (different polygon count) always re-emit regardless.
+     */
+    followAnimation?: boolean;
 }
 
 /** Three.js-style transform props accepted by every PolyCSS component. */
@@ -164,8 +192,11 @@ interface PolyProps extends TransformProps, DOMPassthroughProps {
     vertices: Vec3[];
     color?: string;
     texture?: string;
+    textureImageSource?: PolyTextureImageSource;
+    texturePresentation?: PolyTexturePresentation;
     uvs?: Vec2[];
     data?: Record<string, string | number | boolean>;
+    doubleSided?: boolean;
     /** Shared material. When set AND the polygon's UVs form an axis-aligned
      *  rectangle, renders via `background-image` directly — no per-polygon
      *  canvas rasterization. Falls back to the atlas path otherwise. */
@@ -176,6 +207,10 @@ interface PolyProps extends TransformProps, DOMPassthroughProps {
         directionalLight?: PolyDirectionalLight;
         textureLighting?: PolyTextureLightingMode;
         textureQuality?: TextureQuality;
+        textureLeafSizing?: PolyTextureLeafSizing;
+        textureImageRendering?: PolyTextureImageRendering;
+        textureBackend?: PolyTextureBackend;
+        textureProjection?: PolyTextureProjection;
         debugShowBackfaces?: boolean;
         [key: string]: unknown;
     };
@@ -184,6 +219,14 @@ interface PolyProps extends TransformProps, DOMPassthroughProps {
     /** Atlas bitmap budget and CSS sprite size. `"auto"` (default) uses a
      *  device-appropriate memory budget and desktop/mobile sprite sizing. */
     textureQuality?: TextureQuality;
+    /** Atlas leaf CSS primitive sizing. Defaults to scene context, then canonical. */
+    textureLeafSizing?: PolyTextureLeafSizing;
+    /** Default image filtering for atlas and direct image texture leaves. */
+    textureImageRendering?: PolyTextureImageRendering;
+    /** Default texture backend request. Defaults to scene context, then "auto". */
+    textureBackend?: PolyTextureBackend;
+    /** Default texture projection request. Defaults to scene context, then "affine". */
+    textureProjection?: PolyTextureProjection;
     /** Pre-computed shaded base color from the parent (optional override). */
     baseColor?: string;
 }
@@ -210,6 +253,9 @@ interface PolySceneProps extends TransformProps {
     rotY?: number;
     zoom?: number;
     directionalLight?: PolyDirectionalLight;
+    /** Point lights (world-space positions). Direction-only per-face Lambert,
+     *  baked-mode only. */
+    pointLights?: PolyPointLight[];
     ambientLight?: PolyAmbientLight;
     /** Textured polygon lighting mode. Defaults to "baked". */
     textureLighting?: PolyTextureLightingMode;
@@ -218,6 +264,14 @@ interface PolySceneProps extends TransformProps {
      *  desktop/mobile sprite sizing. Numeric values 0.1..1 force an explicit
      *  raster scale and the 64px sprite. */
     textureQuality?: TextureQuality;
+    /** Atlas leaf CSS primitive sizing. Defaults to canonical browser-fast sizing. */
+    textureLeafSizing?: PolyTextureLeafSizing;
+    /** Default image filtering for atlas and direct image texture leaves. */
+    textureImageRendering?: PolyTextureImageRendering;
+    /** Default texture backend request. Defaults to "auto". */
+    textureBackend?: PolyTextureBackend;
+    /** Default texture projection request. Defaults to "affine". */
+    textureProjection?: PolyTextureProjection;
     /** Solid seam overscan. `"auto"` computes a fitted per-edge amount from the polygon plan. */
     seamBleed?: PolySeamBleed;
     /**
@@ -250,7 +304,7 @@ 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, seamBleed, strategies, autoCenter, shadow, 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, pointLights, ambientLight, textureLighting, textureQuality, textureLeafSizing, textureImageRendering, textureBackend, textureProjection, 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;
@@ -331,6 +385,8 @@ interface PolyMeshHandle {
      * safe to call.
      */
     rebakeAtlas(): void;
+    /** Resolves when this mesh's current texture generation has usable backgrounds. */
+    whenTexturesReady(): Promise<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.
@@ -438,6 +494,14 @@ 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;
+    /** Atlas leaf CSS primitive sizing. Defaults to scene context, then canonical. */
+    textureLeafSizing?: PolyTextureLeafSizing;
+    /** Default image filtering for atlas and direct image texture leaves. */
+    textureImageRendering?: PolyTextureImageRendering;
+    /** Default texture backend request. Defaults to scene context, then "auto". */
+    textureBackend?: PolyTextureBackend;
+    /** Default texture projection request. Defaults to scene context, then "affine". */
+    textureProjection?: PolyTextureProjection;
     /** Solid seam overscan. `"auto"` computes a fitted per-edge amount from the polygon plan. */
     seamBleed?: PolySeamBleed;
     /**
@@ -476,6 +540,12 @@ interface PolyMeshProps extends TransformProps, InteractionProps {
      * for caster meshes — receivers handle shadow display. Defaults to `false`.
      */
     receiveShadow?: boolean;
+    /**
+     * Per-mesh parametric-shadow detail, overriding the scene's
+     * `shadow.definition` for this mesh's cast/self shadow. Only used when the
+     * scene's `shadow.parametric` is true. Unset → inherit the scene definition.
+     */
+    shadowDefinition?: number;
     /**
      * Apply mesh optimization (coplanar merge + interior cull) before
      * rendering. Defaults to `true` — matches vanilla `scene.add`'s default.
@@ -580,7 +650,7 @@ 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, textureQuality: textureQualityProp, baseColor: baseColorProp, ...dataAttrs }: PolyProps): react_jsx_runtime.JSX.Element | null;
+declare function PolyInner({ vertices, color, texture, textureImageSource, texturePresentation, uvs, data, doubleSided, 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, textureLeafSizing: textureLeafSizingProp, textureImageRendering: textureImageRenderingProp, textureBackend: textureBackendProp, textureProjection: textureProjectionProp, 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">;
@@ -902,11 +972,84 @@ interface PolyRenderSurfaceLeafCounts {
     atlas: number;
     stableTriangle: number;
 }
+type PolyRenderLeafStrategy = keyof PolyRenderSurfaceLeafCounts;
+interface PolyTextureReadiness {
+    ready: boolean;
+    textureLeafCount: number;
+    readyTextureLeafCount: number;
+    pendingTextureLeafCount: number;
+    atlasTextureLeafCount: number;
+    imageTextureLeafCount: number;
+}
+interface PolyTextureRenderStats {
+    ready: boolean;
+    leafCount: number;
+    atlasCount: number;
+    imageCount: number;
+    pendingCount: number;
+    sizingCounts: {
+        canonical: number;
+        local: number;
+        raster: number;
+        image: number;
+        unknown: number;
+    };
+    imageRenderingCounts: {
+        auto: number;
+        pixelated: number;
+        unknown: number;
+    };
+    projectionCounts: {
+        affine: number;
+        projective: number;
+        fallback: number;
+        unknown: number;
+    };
+    minLeafWidth: number;
+    maxLeafWidth: number;
+    minLeafHeight: number;
+    maxLeafHeight: number;
+    doubleSidedCount: number;
+}
+interface PolySnapshotRenderStats {
+    runtimeAtlasUrlCount: number;
+    snapshotAtlasCount: number;
+    snapshotBackgroundCount: number;
+    selfContained: boolean;
+}
+interface PolyCameraSnapshotStats {
+    rootFound: boolean;
+    projection: "orthographic" | "perspective" | "unknown";
+    perspectiveStyle: string;
+    appliedPerspectiveStyle: string;
+    zoom?: number;
+    distance?: number;
+    rotX?: number;
+    rotY?: number;
+    target?: [number, number, number];
+}
+interface PolyLeafInfo {
+    element: HTMLElement;
+    strategy: PolyRenderLeafStrategy;
+    polygonIndex?: number;
+    textureBackend?: string;
+    textureReady?: boolean;
+    textureLeafSizing?: string;
+    textureImageRendering?: string;
+    textureProjection?: string;
+    textureLeafWidth?: number;
+    textureLeafHeight?: number;
+    doubleSided?: boolean;
+}
 interface PolyRenderStats {
     polygonCount: number;
     mountedPolygonLeafCount: number;
     shadowLeafCount: number;
     surfaceLeafCounts: PolyRenderSurfaceLeafCounts;
+    textureReadiness: PolyTextureReadiness;
+    textureStats: PolyTextureRenderStats;
+    snapshotStats: PolySnapshotRenderStats;
+    cameraStats: PolyCameraSnapshotStats;
     bucketCount: number;
 }
 interface PolyRenderStatsOptions {
@@ -917,6 +1060,8 @@ interface PolyRenderStatsOptions {
      */
     scopeSelector?: string;
 }
+declare function queryPolyLeaves(root: ParentNode | null | undefined, optionsOrPolygonCount?: number | PolyRenderStatsOptions): PolyLeafInfo[];
+declare function collectPolyTextureReadiness(root: ParentNode | null | undefined, optionsOrPolygonCount?: number | PolyRenderStatsOptions): PolyTextureReadiness;
 declare function collectPolyRenderStats(root: ParentNode | null | undefined, optionsOrPolygonCount?: number | PolyRenderStatsOptions): PolyRenderStats;
 
 interface UsePolyAnimationResult {
@@ -937,4 +1082,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, 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, PolyIframe, type PolyIframeProps, 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 };
+export { type DOMPassthroughProps, type InteractionProps, Poly, PolyAxesHelper, type PolyAxesHelperProps, PolyBox, type PolyBoxProps, PolyOrthographicCamera as PolyCamera, PolyCameraContext, type PolyCameraContextValue, type PolyOrthographicCameraProps as PolyCameraProps, type PolyCameraSnapshotStats, 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, PolyIframe, type PolyIframeProps, type PolyLeafInfo, 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 PolyRenderLeafStrategy, type PolyRenderStats, type PolyRenderStatsOptions, type PolyRenderSurfaceLeafCounts, PolyRing, type PolyRingProps, PolyScene, type PolySceneProps, PolySelect, type PolySelectProps, type PolySelectionApi, type PolySnapshotRenderStats, PolySphere, type PolySphereProps, PolyTetrahedron, type PolyTetrahedronProps, type PolyTextureReadiness, type PolyTextureRenderStats, 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, collectPolyTextureReadiness, findMeshUnderPoint, findPolyMeshHandle, injectPolyBaseStyles, pointInMeshElement, queryPolyLeaves, useCameraContext, usePolyAnimation, usePolyCamera, usePolyMaterial, usePolyMesh, usePolySceneContext, usePolySelect, usePolySelectionApi };