@layoutit/polycss-react 0.2.0 → 0.2.2

package/dist/index.d.ts

@@ -1,8 +1,9 @@
-import * as react from 'react';
-import react__default, { ReactNode, CSSProperties, MouseEventHandler, PointerEventHandler, FocusEventHandler, KeyboardEventHandler, RefObject, MouseEvent as MouseEvent$1 } from 'react';
+import * as React$1 from 'react';
+import React__default, { ReactNode, CSSProperties, MouseEventHandler, PointerEventHandler, FocusEventHandler, KeyboardEventHandler, IframeHTMLAttributes, RefObject, MouseEvent as MouseEvent$1 } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { Vec3, CameraState, CameraHandle, Vec2, PolyMaterial, PolyDirectionalLight, PolyTextureLightingMode, Polygon, PolyAmbientLight, LoadMeshOptions, PolyAnimationTarget, PolyAnimationMixer, PolyAnimationClip, PolyAnimationAction, ParseAnimationController } from '@layoutit/polycss-core';
-export { ApproximateMergeOptions, ArrowPolygonsOptions, AutoRotateConfig, AutoRotateOption, AxesHelperOptions, BASE_TILE, BoxFace, BoxFaceOptions, BoxPolygonsOptions, CAMERA_BACKFACE_CULL_EPS, CameraCullNormalGroup, CameraCullRotation, CameraHandle, CameraState, CameraStyleInput, CoverPlanarPolygonsOptions, CullInteriorOptions, DEFAULT_CAMERA_STATE, DEFAULT_PROJECTION, GltfParseOptions, LoadMeshOptions, LoopMode, LoopOnce, LoopPingPong, LoopRepeat, MeshResolution, MtlParseResult, NormalizeResult, ObjParseOptions, OctahedronPolygonsOptions, OptimizeMeshPolygonsOptions, ParseAnimationClip, ParseAnimationController, ParseResult, ParsedColor, PolyAmbientLight, PolyAnimationAction, PolyAnimationClip, PolyAnimationMixer, PolyAnimationTarget, PolyDirectionalLight, PolyMaterial, PolyTextureLightingMode, Polygon, PolygonFace, RingPolygonsOptions, SceneBbox, SceneContext, SceneContextBuildArgs, SceneContextBuildResult, SolidTextureSampleOptions, TexturePaintMetrics, TexturePaintMetricsOptions, TextureTriangle, VOXEL_CAMERA_CULL_AXIS_EPS, VOXEL_CAMERA_CULL_NORMAL_LIMIT, Vec2, Vec3, VoxParseOptions, arrowPolygons, axesHelperPolygons, bakeSolidTextureSampledPolygons, bakeSolidTextureSamples, boxPolygons, buildSceneContext, cameraCullNormalGroups, cameraCullNormalGroupsFromPolygons, cameraCullNormalKey, cameraCullVisibleSignature, cameraFacingDepth, clampChannel, computeSceneBbox, computeShapeLighting, computeTexturePaintMetrics, coverPlanarPolygons, createIsometricCamera, createPolyAnimationMixer, cullInteriorPolygons, formatColor, inverseRotateVec3, isAxisAlignedSurfaceNormal, isVoxelCameraCullableNormalGroups, loadMesh, mergePolygons, normalFacesCamera, normalizeInvertMultiplier, normalizePolygons, octahedronPolygons, optimizeMeshPolygons, parseColor, parseGltf, parseHexColor, parseMtl, parseObj, parsePureColor, parseRgbColor, parseVox, polygonCssSurfaceNormal, polygonFaces, polygonFacesCamera, ringPolygons, rotateVec3, shadeColor } from '@layoutit/polycss-core';
+import * 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, PolyRenderStrategiesOption, PolyRenderStrategy, 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, 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, polygonCssSurfaceNormal, polygonFaces, polygonFacesCamera, repairMeshSeams, ringPolygons, rotateVec3, seamFacetSplitPolygons, seamFacetSplitReport, seamOverlapDiagnostics, seamOverlapPolygons, seamOverlapReport, shadeColor, simplifyTriangleMeshPolygons, tetrahedronPolygons, torusPolygons } from '@layoutit/polycss-core';
 
 interface PolyPerspectiveCameraProps {
     zoom?: number;
@@ -11,14 +12,14 @@ interface PolyPerspectiveCameraProps {
     rotY?: number;
     /** Camera pull-back in CSS pixels (dolly). Default 0. */
     distance?: number;
-    /** CSS perspective distance in pixels. Defaults to 8000. */
+    /** CSS perspective distance in pixels. Defaults to 32000. */
     perspective?: number;
     children?: ReactNode;
     className?: string;
     style?: React.CSSProperties;
 }
 declare function PolyPerspectiveCameraInner({ zoom, target, rotX, rotY, distance, perspective, children, className, style, }: PolyPerspectiveCameraProps): react_jsx_runtime.JSX.Element;
-declare const PolyPerspectiveCamera: react.MemoExoticComponent<typeof PolyPerspectiveCameraInner>;
+declare const PolyPerspectiveCamera: React$1.MemoExoticComponent<typeof PolyPerspectiveCameraInner>;
 
 interface PolyOrthographicCameraProps {
     zoom?: number;
@@ -32,7 +33,7 @@ interface PolyOrthographicCameraProps {
     style?: React.CSSProperties;
 }
 declare function PolyOrthographicCameraInner({ zoom, target, rotX, rotY, distance, children, className, style, }: PolyOrthographicCameraProps): react_jsx_runtime.JSX.Element;
-declare const PolyOrthographicCamera: react.MemoExoticComponent<typeof PolyOrthographicCameraInner>;
+declare const PolyOrthographicCamera: React$1.MemoExoticComponent<typeof PolyOrthographicCameraInner>;
 
 interface SceneStoreState {
     cameraState: CameraState;
@@ -101,31 +102,23 @@ interface PolyCameraContextValue {
      */
     applyTransformDirect: () => void;
 }
-declare const PolyCameraContext: react.Context<PolyCameraContextValue | null>;
+declare const PolyCameraContext: React$1.Context<PolyCameraContextValue | null>;
 declare function useCameraContext(): PolyCameraContextValue;
 
 interface ShadowOptions {
     color?: string;
     opacity?: number;
     lift?: number;
+    /**
+     * Maximum CSS pixels the shadow may extend beyond the mesh's
+     * footprint. Caps the SVG backing store at low light elevations to
+     * prevent repaint flicker. Default: `2000`. Pass `Infinity` to
+     * disable the cap entirely.
+     */
+    maxExtend?: number;
 }
 
-/** A render strategy tag that can be selectively disabled. */
-type PolyRenderStrategy = "b" | "i" | "u";
-interface PolyRenderStrategiesOption {
-    /** Strategies to skip; polygons that would normally use them fall through
-     *  the chain (b → i → s, u → i → s, i → s). `<s>` is the universal
-     *  fallback and cannot be disabled — textured polys have no other path. */
-    disable?: readonly PolyRenderStrategy[];
-}
-type TextureQuality = number | "auto";
-
-/**
- * Three.js-style transform props accepted by every polycss component.
- * In Phase 3, position/scale/rotation are accepted but not yet applied —
- * the rendered transform comes from vertices in scene-root space.
- * Phase 4 wires these into the matrix3d composition with parent PolyMesh.
- */
+/** Three.js-style transform props accepted by every PolyCSS component. */
 interface TransformProps {
     position?: Vec3;
     scale?: number | Vec3;
@@ -133,7 +126,7 @@ interface TransformProps {
 }
 /**
  * DOM event handlers, ARIA, and style props forwarded to the rendered
- * element (atlas-backed <div>) by every Poly component.
+ * element by every Poly component.
  *
  * This is the DOM-native pitch: polygons are real DOM nodes you can
  * target with CSS, attach event handlers to, and inspect in DevTools.
@@ -165,7 +158,7 @@ interface DOMPassthroughProps {
  * Props for the `<Poly>` component — the atomic polygon primitive.
  *
  * Extends TransformProps + DOMPassthroughProps with the polygon's own fields.
- * This is the canonical polycss v0.1.0 Poly component API per §API freeze.
+ * This is the canonical Poly component API.
  */
 interface PolyProps extends TransformProps, DOMPassthroughProps {
     vertices: Vec3[];
@@ -225,6 +218,8 @@ interface PolySceneProps extends TransformProps {
      *  desktop/mobile sprite sizing. Numeric values 0.1..1 force an explicit
      *  raster scale and the 64px sprite. */
     textureQuality?: TextureQuality;
+    /** Solid seam overscan. `"auto"` computes a fitted per-edge amount from the polygon plan. */
+    seamBleed?: PolySeamBleed;
     /**
      * Render strategy overrides. Use `{ disable: ["u"] }` to force solid
      * triangles through the atlas path (`<s>`), or `{ disable: ["b", "i", "u"] }`
@@ -243,9 +238,10 @@ interface PolySceneProps extends TransformProps {
      */
     autoCenter?: boolean;
     /**
-     * Shadow appearance for meshes with `castShadow={true}`. Only applies in
-     * dynamic lighting mode — baked mode does not emit shadow leaves.
-     * Defaults: `{ color: "#000000", opacity: 0.25, lift: 0.05 }`.
+     * Shadow appearance for meshes with `castShadow={true}`. Works in both
+     * lighting modes. Shadows emit as SVG paths and reproject when light,
+     * ground, or mesh geometry changes. Defaults:
+     * `{ color: "#000000", opacity: 0.25, lift: 0.05, maxExtend: 2000 }`.
      */
     shadow?: ShadowOptions;
     className?: string;
@@ -254,12 +250,13 @@ interface PolySceneProps extends TransformProps {
     debugShowLabels?: boolean;
     debugShowBackfaces?: boolean;
 }
-declare function PolySceneInner({ polygons: polygonsProp, centerPolygons: centerPolygonsProp, perspective: _perspective, rotX: _rotX, rotY: _rotY, zoom: _zoom, directionalLight, ambientLight, textureLighting, textureQuality, strategies, autoCenter, shadow, className, style, children, position: _position, scale: _scale, rotation: _rotation, debugShowLabels: _debugShowLabels, debugShowBackfaces, }: PolySceneProps): react_jsx_runtime.JSX.Element;
-declare const PolyScene: react.MemoExoticComponent<typeof PolySceneInner>;
+declare function PolySceneInner({ polygons: polygonsProp, centerPolygons: centerPolygonsProp, perspective: _perspective, rotX: _rotX, rotY: _rotY, zoom: _zoom, directionalLight, ambientLight, textureLighting, textureQuality, seamBleed, strategies, autoCenter, shadow, className, style, children, position: _position, scale: _scale, rotation: _rotation, debugShowLabels: _debugShowLabels, debugShowBackfaces, }: PolySceneProps): react_jsx_runtime.JSX.Element;
+declare const PolyScene: React$1.MemoExoticComponent<typeof PolySceneInner>;
 
 type UseMeshOptions = LoadMeshOptions;
 interface UseMeshResult {
     polygons: Polygon[];
+    voxelSource: ParseResult["voxelSource"];
     loading: boolean;
     error: Error | null;
     warnings: string[];
@@ -271,7 +268,7 @@ declare function usePolyMesh(src: string, options?: UseMeshOptions): UseMeshResu
 /**
  * Pointer event API for <PolyMesh>. Mirrors @react-three/fiber's mesh
  * event surface (handler names + payload shape) so devs migrating from
- * three.js use the same mental model. polycss is DOM-native so we get
+ * three.js use the same mental model. PolyCSS is DOM-native so we get
  * native pointer events for free — no raycaster, no canvas event
  * synthesis.
  *
@@ -306,6 +303,12 @@ interface PolyMeshHandle {
     getScale(): number | Vec3 | undefined;
     /** Polygons currently being rendered (post-autoCenter). */
     getPolygons(): Polygon[];
+    /**
+     * Replace the mesh polygons imperatively. Animated solid-triangle meshes use
+     * a stable DOM update path that mutates mounted leaves directly; unsupported
+     * topology falls back to the normal framework render path.
+     */
+    setPolygons(polygons: Polygon[]): void;
     /**
      * Snapshot the current `rotation` prop as the new "baked rotation" and
      * trigger an atlas re-rasterization with the directional light
@@ -418,6 +421,14 @@ interface PolyMeshProps extends TransformProps, InteractionProps {
     mtl?: string;
     /** Pre-parsed polygons. Mutually exclusive with `src`. */
     polygons?: Polygon[];
+    /** Optional `parseResult.voxelSource` companion for `.vox` meshes. When
+     *  set alongside `polygons`, the direct voxel renderer fast path activates
+     *  — emitting one `<b>` per visible voxel quad inside `.polycss-voxel-face`
+     *  wrappers (matches vanilla's `scene.add(parseResult)` behaviour).
+     *  Callers fetching via core's `loadMesh()` pass `parseResult.voxelSource`
+     *  here so the fast path engages; callers fetching via PolyMesh's `src`
+     *  prop get the same data wired through `useMesh` automatically. */
+    voxelSource?: _layoutit_polycss_core.ParseResult["voxelSource"];
     /** Translate so mesh's bbox center is at local origin before applying `position`. */
     autoCenter?: boolean;
     /** Textured polygon lighting mode. Defaults to "baked". */
@@ -427,6 +438,17 @@ interface PolyMeshProps extends TransformProps, InteractionProps {
      *  desktop/mobile sprite sizing. Numeric values 0.1..1 force an explicit
      *  raster scale and the 64px sprite. */
     textureQuality?: TextureQuality;
+    /** Solid seam overscan. `"auto"` computes a fitted per-edge amount from the polygon plan. */
+    seamBleed?: PolySeamBleed;
+    /**
+     * Hold the whole previous frame (geometry + texture) until the next atlas is
+     * decoded, then swap atomically — so a geometry edit never shows geometry
+     * before its texture. Best when edits arrive as discrete commits (no
+     * continuous drag). Defaults to false (bitmap streams in over live geometry).
+     */
+    atomicAtlas?: boolean;
+    /** Fires when the displayed atlas frame swaps to a ready one (atomic mode). */
+    onFrameReady?: () => void;
     /** Per-polygon override render, or static children mounted inside the mesh wrapper. */
     children?: ((polygon: Polygon, index: number) => ReactNode) | ReactNode;
     /** Loading slot — rendered while `src` is being fetched/parsed. */
@@ -435,18 +457,66 @@ interface PolyMeshProps extends TransformProps, InteractionProps {
     errorFallback?: (error: Error) => ReactNode;
     /** Parser options forwarded to parseObj/parseGltf. */
     parseOptions?: UseMeshOptions;
+    /** Mesh optimization intent. Defaults to "lossy"; set "lossless" to keep
+     *  authored surface fidelity. Top-level prop wins over `parseOptions.meshResolution`
+     *  when both are present. */
+    meshResolution?: MeshResolution;
     /**
-     * When `true` and the scene is in dynamic lighting mode, emits a flat
-     * shadow leaf (`<q class="polycss-shadow">`) sibling for each polygon.
-     * 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`.
+     * When `true`, emits a per-mesh SVG shadow path in both lighting modes.
+     * Each casting polygon projects onto the scene ground plane along the
+     * directional light; overlapping outlines are merged into one silhouette.
+     * Defaults to `false`.
      */
     castShadow?: boolean;
+    /**
+     * When `true`, this mesh acts as a shadow receiver. The scene's caster
+     * meshes (those with `castShadow=true`) project per-coplanar-face SVG
+     * shadows onto each visible surface of this mesh, matching Three.js's
+     * `mesh.receiveShadow` semantics. Disables the ground-shadow fallback
+     * for caster meshes — receivers handle shadow display. Defaults to `false`.
+     */
+    receiveShadow?: boolean;
+    /**
+     * Apply mesh optimization (coplanar merge + interior cull) before
+     * rendering. Defaults to `true` — matches vanilla `scene.add`'s default.
+     * Set `false` for helper meshes (axes, light markers) whose geometry
+     * shouldn't be merged, or when the imperative `updatePolygon` API needs
+     * polygon refs to survive across updates.
+     */
+    merge?: boolean;
+    className?: string;
+    style?: CSSProperties;
+}
+declare const PolyMesh: React$1.ForwardRefExoticComponent<PolyMeshProps & React$1.RefAttributes<PolyMeshHandle>>;
+
+interface PolyIframeProps {
+    /** Iframe URL — forwarded to the underlying <iframe>'s `src` attribute. */
+    src: string;
+    /** Width in world units (multiplied by BASE_TILE for CSS px). */
+    width: number;
+    /** Height in world units (multiplied by BASE_TILE for CSS px). */
+    height: number;
+    /** World-units position (+X right, +Y forward, +Z up). */
+    position?: Vec3;
+    /** World Euler XYZ in degrees. */
+    rotation?: Vec3;
+    /** Uniform scale (number) or per-axis Vec3. */
+    scale?: number | Vec3;
+    /** Forwarded to the underlying <iframe>'s `allow`. */
+    allow?: string;
+    /** Forwarded to the underlying <iframe>'s `sandbox`. */
+    sandbox?: string;
+    /** Forwarded to the underlying <iframe>'s `loading`. */
+    loading?: IframeHTMLAttributes<HTMLIFrameElement>["loading"];
+    /** Forwarded to the underlying <iframe>'s `referrerpolicy`. */
+    referrerPolicy?: IframeHTMLAttributes<HTMLIFrameElement>["referrerPolicy"];
+    /** Forwarded to the underlying <iframe>'s `title` (a11y label). */
+    title?: string;
     className?: string;
+    /** Style overrides on the wrapper div (NOT on the iframe). */
     style?: CSSProperties;
 }
-declare const PolyMesh: react.ForwardRefExoticComponent<PolyMeshProps & react.RefAttributes<PolyMeshHandle>>;
+declare function PolyIframe({ src, width, height, position, rotation, scale, allow, sandbox, loading, referrerPolicy, title, className, style, }: PolyIframeProps): react_jsx_runtime.JSX.Element;
 
 interface PolyGroundProps {
     /** Side length of the ground quad in world units. Default `6`. */
@@ -455,8 +525,8 @@ interface PolyGroundProps {
     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. */
+    /** Fill color. Default `#7d848e` — medium gray, chosen so the default
+     *  25% black SVG shadow has visible contrast against it. */
     color?: string;
     className?: string;
 }
@@ -473,11 +543,11 @@ interface UseSceneContextResult {
     };
 }
 /**
- * React hook that runs the polycss scene-context pipeline:
+ * React hook that runs the PolyCSS scene-context pipeline:
  *   normalizePolygons → mergePolygons by default → bbox compute.
  *
  * Returns the processed polygons + the scene-wide axis-aligned bbox. Memoized
- * on input identity + the few options that affect output. Per §Design.6.
+ * on input identity + the few options that affect output.
  */
 declare function usePolySceneContext(polygons: Polygon[], options: UseSceneContextOptions): UseSceneContextResult;
 
@@ -498,11 +568,12 @@ declare function usePolyMaterial(options: {
 }): PolyMaterial;
 
 /**
- * Poly — renders one polygon as an atlas-backed DOM sprite.
+ * Poly — renders one polygon as a render-strategy DOM leaf.
  *
  * Public API: `{ vertices, color?, texture?, uvs?, data? }` plus DOM
- * passthrough props. The atlas renderer handles both textured and solid-color
- * faces, so `<Poly>` never emits SVG in the normal render path.
+ * passthrough props. Solid faces use the cheapest supported solid strategy;
+ * textured faces use the atlas path. `<Poly>` never emits SVG in the normal
+ * render path.
  *
  * Wrapped in React.memo so parent re-renders (e.g. camera rotation updating
  * rotY state) do not re-render stable polygon children. The shallow-equality
@@ -510,7 +581,42 @@ declare function usePolyMaterial(options: {
  * typically created once at parse time and passed by reference.
  */
 declare function PolyInner({ vertices, color, texture, uvs, data, material, position, scale, rotation, className, style: styleProp, id, onClick, onDoubleClick, onMouseEnter, onMouseLeave, onMouseMove, onPointerDown, onPointerUp, onPointerEnter, onPointerLeave, onFocus, onBlur, onKeyDown, tabIndex, role, "aria-label": ariaLabel, "aria-hidden": ariaHidden, pointerEvents: pointerEventsProp, context, textureLighting: textureLightingProp, textureQuality: textureQualityProp, baseColor: baseColorProp, ...dataAttrs }: PolyProps): react_jsx_runtime.JSX.Element | null;
-declare const Poly: react__default.MemoExoticComponent<typeof PolyInner>;
+declare const Poly: React__default.MemoExoticComponent<typeof PolyInner>;
+
+type ShapeMeshProps = Omit<PolyMeshProps, "polygons" | "src" | "mtl">;
+interface PolyBoxProps extends ShapeMeshProps, BoxPolygonsOptions {
+}
+declare function PolyBox({ size, center, min, max, color, texture, material, uvs, data, faces, ...meshProps }: PolyBoxProps): react_jsx_runtime.JSX.Element;
+interface PolyPlaneProps extends ShapeMeshProps, PlanePolygonsOptions {
+}
+declare function PolyPlane({ axis, size, offset, along, color, ...meshProps }: PolyPlaneProps): react_jsx_runtime.JSX.Element;
+interface PolyRingProps extends ShapeMeshProps, RingPolygonsOptions {
+}
+declare function PolyRing({ axis, radius, halfThickness, segments, color, ...meshProps }: PolyRingProps): react_jsx_runtime.JSX.Element;
+interface PolyOctahedronProps extends ShapeMeshProps, OctahedronPolygonsOptions {
+}
+declare function PolyOctahedron({ center, size, color, ...meshProps }: PolyOctahedronProps): react_jsx_runtime.JSX.Element;
+interface PolyTetrahedronProps extends ShapeMeshProps, TetrahedronPolygonsOptions {
+}
+declare function PolyTetrahedron({ size, color, ...meshProps }: PolyTetrahedronProps): react_jsx_runtime.JSX.Element;
+interface PolyIcosahedronProps extends ShapeMeshProps, IcosahedronPolygonsOptions {
+}
+declare function PolyIcosahedron({ size, color, ...meshProps }: PolyIcosahedronProps): react_jsx_runtime.JSX.Element;
+interface PolyDodecahedronProps extends ShapeMeshProps, DodecahedronPolygonsOptions {
+}
+declare function PolyDodecahedron({ size, color, ...meshProps }: PolyDodecahedronProps): react_jsx_runtime.JSX.Element;
+interface PolySphereProps extends ShapeMeshProps, SpherePolygonsOptions {
+}
+declare function PolySphere({ radius, subdivisions, color, ...meshProps }: PolySphereProps): react_jsx_runtime.JSX.Element;
+interface PolyCylinderProps extends ShapeMeshProps, CylinderPolygonsOptions {
+}
+declare function PolyCylinder({ radius, radiusTop, height, radialSegments, color, ...meshProps }: PolyCylinderProps): react_jsx_runtime.JSX.Element;
+interface PolyConeProps extends ShapeMeshProps, ConePolygonsOptions {
+}
+declare function PolyCone({ radius, height, radialSegments, color, ...meshProps }: PolyConeProps): react_jsx_runtime.JSX.Element;
+interface PolyTorusProps extends ShapeMeshProps, TorusPolygonsOptions {
+}
+declare function PolyTorus({ radius, tube, radialSegments, tubularSegments, color, ...meshProps }: PolyTorusProps): react_jsx_runtime.JSX.Element;
 
 interface PolyFirstPersonControlsOptions {
     /** Master switch. When `false`, all sub-controls are inert. Default: `true`. */
@@ -577,7 +683,7 @@ interface PolyFirstPersonControlsProps extends PolyFirstPersonControlsOptions {
     /** Called when pointer-lock is released (interaction ends). */
     onInteractionEnd?: () => void;
 }
-declare const PolyFirstPersonControls: react.ForwardRefExoticComponent<PolyFirstPersonControlsProps & react.RefAttributes<PolyFirstPersonControlsHandle>>;
+declare const PolyFirstPersonControls: React$1.ForwardRefExoticComponent<PolyFirstPersonControlsProps & React$1.RefAttributes<PolyFirstPersonControlsHandle>>;
 
 interface PolyControlsAnimateOptions {
     /** Degrees per 60Hz-equivalent frame. Default 0.3 (≈ 18 deg/sec). */
@@ -775,10 +881,11 @@ interface PolyDirectionalLightHelperProps {
  * PolyDirectionalLightHelper — small octahedron placed along the light's
  * direction vector. Mirrors three.js's `DirectionalLightHelper`.
  *
- * `light.direction` is in CSS-pixel space (axis convention used by the
- * shader). Polygon vertices are in world space, which the renderer remaps
- * via `[v[1], v[0], v[2]]`. The helper reverses that swap so the marker
- * lands where the light visibly comes from on screen.
+ * Post-parity: both `light.direction` and `target` are in WORLD coords
+ * (`+X right, +Y forward, +Z up`), and `<PolyMesh>`'s `position` prop is
+ * also world units (the renderer applies the world→CSS axis swap +
+ * ×BASE_TILE internally). The helper just adds `dir × distance` to
+ * `target` and passes the result through.
  *
  * The octahedron is built at LOCAL origin once; the world position is
  * applied via PolyMesh's `position` prop (a CSS transform on the wrapper).
@@ -789,6 +896,29 @@ declare function PolyDirectionalLightHelper({ light, target, distance, size, col
 
 declare function injectPolyBaseStyles(doc?: Document): void;
 
+interface PolyRenderSurfaceLeafCounts {
+    quad: number;
+    clippedSolid: number;
+    atlas: number;
+    stableTriangle: number;
+}
+interface PolyRenderStats {
+    polygonCount: number;
+    mountedPolygonLeafCount: number;
+    shadowLeafCount: number;
+    surfaceLeafCounts: PolyRenderSurfaceLeafCounts;
+    bucketCount: number;
+}
+interface PolyRenderStatsOptions {
+    polygonCount?: number;
+    /**
+     * Optional subtree selector for diagnostics that only want model leaves and
+     * not helpers/floors/gizmos sharing the same scene root.
+     */
+    scopeSelector?: string;
+}
+declare function collectPolyRenderStats(root: ParentNode | null | undefined, optionsOrPolygonCount?: number | PolyRenderStatsOptions): PolyRenderStats;
+
 interface UsePolyAnimationResult {
     /** Attach to a `PolyAnimationTarget`-compatible handle when not using `root`. */
     ref: RefObject<PolyAnimationTarget | null>;
@@ -807,4 +937,4 @@ interface UsePolyAnimationResult {
 }
 declare function usePolyAnimation(clips: PolyAnimationClip[] | undefined, controller: ParseAnimationController | undefined, root?: RefObject<PolyAnimationTarget | null> | PolyAnimationTarget | null): UsePolyAnimationResult;
 
-export { type DOMPassthroughProps, type InteractionProps, Poly, PolyAxesHelper, type PolyAxesHelperProps, PolyPerspectiveCamera as PolyCamera, PolyCameraContext, type PolyCameraContextValue, type PolyPerspectiveCameraProps as PolyCameraProps, type PolyControlsAnimateOptions, type PolyControlsCamera, PolyDirectionalLightHelper, type PolyDirectionalLightHelperProps, type PolyEventHandler, PolyFirstPersonControls, type PolyFirstPersonControlsHandle, type PolyFirstPersonControlsOptions, type PolyFirstPersonControlsProps, PolyGround, type PolyGroundProps, PolyMapControls, type PolyControlsCamera as PolyMapControlsCamera, type PolyMapControlsProps, PolyMesh, type PolyMeshHandle, type PolyMeshProps, type PolyMouseEvent, PolyOrbitControls, type PolyControlsCamera as PolyOrbitControlsCamera, type PolyOrbitControlsProps, PolyOrthographicCamera, type PolyOrthographicCameraProps, PolyPerspectiveCamera, type PolyPerspectiveCameraProps, type PolyPointerEvent, type PolyProps, type PolyRenderStrategiesOption, type PolyRenderStrategy, PolyScene, type PolySceneProps, PolySelect, type PolySelectProps, type PolySelectionApi, PolyTransformControls, type PolyTransformControlsObject, type PolyTransformControlsObjectChangeEvent, type PolyTransformControlsProps, type PolyWheelEvent, type SharedControlsProps, type TransformProps, type UseCameraOptions, type UseCameraResult, type UseMeshOptions, type UseMeshResult, type UsePolyAnimationResult, type UseSceneContextOptions, type UseSceneContextResult, findMeshUnderPoint, findPolyMeshHandle, injectPolyBaseStyles, pointInMeshElement, useCameraContext, usePolyAnimation, usePolyCamera, usePolyMaterial, usePolyMesh, usePolySceneContext, usePolySelect, usePolySelectionApi };
+export { type DOMPassthroughProps, type InteractionProps, Poly, PolyAxesHelper, type PolyAxesHelperProps, PolyBox, type PolyBoxProps, PolyOrthographicCamera as PolyCamera, PolyCameraContext, type PolyCameraContextValue, type PolyOrthographicCameraProps as PolyCameraProps, PolyCone, type PolyConeProps, type PolyControlsAnimateOptions, type PolyControlsCamera, PolyCylinder, type PolyCylinderProps, PolyDirectionalLightHelper, type PolyDirectionalLightHelperProps, PolyDodecahedron, type PolyDodecahedronProps, type PolyEventHandler, PolyFirstPersonControls, type PolyFirstPersonControlsHandle, type PolyFirstPersonControlsOptions, type PolyFirstPersonControlsProps, PolyGround, type PolyGroundProps, PolyIcosahedron, type PolyIcosahedronProps, 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 };