@layoutit/polycss-react 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,669 @@
+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';
+
+interface PolyPerspectiveCameraProps {
+    zoom?: number;
+    target?: Vec3;
+    rotX?: number;
+    rotY?: number;
+    /** Camera pull-back in CSS pixels (dolly). Default 0. */
+    distance?: number;
+    /** CSS perspective distance in pixels. Defaults to 8000. */
+    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>;
+
+interface PolyOrthographicCameraProps {
+    zoom?: number;
+    target?: Vec3;
+    rotX?: number;
+    rotY?: number;
+    /** Camera pull-back in CSS pixels (dolly). Default 0. */
+    distance?: number;
+    children?: ReactNode;
+    className?: string;
+    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>;
+
+interface SceneStoreState {
+    cameraState: CameraState;
+}
+interface SceneStore {
+    getState(): SceneStoreState;
+    setState(partial: Partial<SceneStoreState>): void;
+    subscribe(listener: () => void): () => void;
+    /** Update camera state from the current imperative camera handle. */
+    updateCameraFromRef(handle: CameraHandle): boolean;
+    /** Force notify all subscribers (e.g. after prop-driven camera change). */
+    notifyAll(): void;
+}
+
+interface UseCameraOptions {
+    zoom?: number;
+    target?: Vec3;
+    rotX?: number;
+    rotY?: number;
+    distance?: number;
+}
+interface UseCameraResult {
+    store: SceneStore;
+    cameraRef: React.MutableRefObject<CameraHandle>;
+    sceneElRef: React.MutableRefObject<HTMLElement | null>;
+    /**
+     * Attach to the camera root element. Layered components like
+     * <PolyOrbitControls> need the underlying ref to wire non-passive wheel /
+     * pointer listeners (React's synthetic onWheel is passive in modern
+     * versions and can't preventDefault).
+     */
+    cameraElRef: React.MutableRefObject<HTMLDivElement | null>;
+    /**
+     * Apply the current camera state (from cameraRef.current.state) directly
+     * to sceneEl.style.transform — bypasses React. Exposed so layered
+     * components like <PolyOrbitControls> can call it after mutating state.
+     */
+    applyTransformDirect: () => void;
+}
+declare function usePolyCamera(options: UseCameraOptions): UseCameraResult;
+
+interface PolyCameraContextValue {
+    store: SceneStore;
+    cameraRef: React.MutableRefObject<CameraHandle>;
+    sceneElRef: React.MutableRefObject<HTMLElement | null>;
+    /**
+     * The host element the camera attaches to (parent of sceneEl). Exposed
+     * so layered components like <PolyControls> can attach their own
+     * pointer/wheel listeners.
+     */
+    cameraElRef: React.MutableRefObject<HTMLElement | null>;
+    /**
+     * Apply the current camera state (from cameraRef.current.state) directly
+     * to sceneEl.style.transform — bypasses React. Used by both useCamera's
+     * built-in handlers and any layered <PolyControls>. Calling it after
+     * cameraRef.current.update(...) makes the DOM reflect the new state.
+     */
+    applyTransformDirect: () => void;
+}
+declare const PolyCameraContext: react.Context<PolyCameraContextValue | null>;
+declare function useCameraContext(): PolyCameraContextValue;
+
+type AtlasScale = 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.
+ */
+interface TransformProps {
+    position?: Vec3;
+    scale?: number | Vec3;
+    rotation?: Vec3;
+}
+/**
+ * DOM event handlers, ARIA, and style props forwarded to the rendered
+ * element (atlas-backed <div>) 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.
+ */
+interface DOMPassthroughProps {
+    className?: string;
+    style?: CSSProperties;
+    id?: string;
+    onClick?: MouseEventHandler<HTMLElement>;
+    onDoubleClick?: MouseEventHandler<HTMLElement>;
+    onMouseEnter?: MouseEventHandler<HTMLElement>;
+    onMouseLeave?: MouseEventHandler<HTMLElement>;
+    onMouseMove?: MouseEventHandler<HTMLElement>;
+    onPointerDown?: PointerEventHandler<HTMLElement>;
+    onPointerUp?: PointerEventHandler<HTMLElement>;
+    onPointerEnter?: PointerEventHandler<HTMLElement>;
+    onPointerLeave?: PointerEventHandler<HTMLElement>;
+    onFocus?: FocusEventHandler<HTMLElement>;
+    onBlur?: FocusEventHandler<HTMLElement>;
+    onKeyDown?: KeyboardEventHandler<HTMLElement>;
+    tabIndex?: number;
+    role?: string;
+    "aria-label"?: string;
+    "aria-hidden"?: boolean;
+    pointerEvents?: "auto" | "none";
+    [dataAttr: `data-${string}`]: string | number | boolean | undefined;
+}
+/**
+ * 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.
+ */
+interface PolyProps extends TransformProps, DOMPassthroughProps {
+    vertices: Vec3[];
+    color?: string;
+    texture?: string;
+    uvs?: Vec2[];
+    data?: Record<string, string | number | 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. */
+    material?: PolyMaterial;
+    context?: {
+        tileSize?: number;
+        layerElevation?: number;
+        directionalLight?: PolyDirectionalLight;
+        textureLighting?: PolyTextureLightingMode;
+        atlasScale?: AtlasScale;
+        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;
+    /** Pre-computed shaded base color from the parent (optional override). */
+    baseColor?: string;
+}
+
+interface PolySceneProps extends TransformProps {
+    /** Polygons to render. Composes additively with `children`. */
+    polygons?: Polygon[];
+    /**
+     * Polygons used ONLY for the `autoCenter` bbox computation. When provided,
+     * the autoCenter translate is derived from this list instead of `polygons`.
+     *
+     * Use this when the scene's renderable polygons live inside a child
+     * `<PolyMesh>` (e.g. in selection mode) rather than in `polygons`. Passing
+     * the full mesh polygon list here ensures the autoCenter wrapper shifts
+     * all children — including helpers like `<PolyAxesHelper>` — by the same
+     * -bboxCenter amount as the vanilla renderer's `centerWrapper`. Without it,
+     * `autoCenter` computes its bbox from an empty `polygons=[]` and produces
+     * no shift, so helpers stay at world origin while the mesh is recentered by
+     * PolyMesh's own `autoCenter`.
+     */
+    centerPolygons?: Polygon[];
+    perspective?: number;
+    rotX?: number;
+    rotY?: number;
+    zoom?: number;
+    directionalLight?: PolyDirectionalLight;
+    ambientLight?: PolyAmbientLight;
+    /** Textured polygon lighting mode. Defaults to "baked". */
+    textureLighting?: PolyTextureLightingMode;
+    /** Raster scale for generated atlas pages. `"auto"` reduces large atlases. */
+    atlasScale?: AtlasScale;
+    /**
+     * 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
+     * `transform-origin` is moved to the bbox center in CSS. Equivalent to
+     * setting Three.js's `OrbitControls.target` to the mesh centroid. Off
+     * by default to match Three.js: meshes load at their authored origin
+     * unless the user opts in. Use this for loaded OBJ/GLB assets whose
+     * origin is at a corner / feet / arbitrary point.
+     */
+    autoCenter?: boolean;
+    className?: string;
+    style?: CSSProperties;
+    children?: ReactNode;
+    debugShowLabels?: boolean;
+    debugShowBackfaces?: boolean;
+}
+declare function PolySceneInner({ polygons: polygonsProp, centerPolygons: centerPolygonsProp, perspective: _perspective, rotX: _rotX, rotY: _rotY, zoom: _zoom, directionalLight, ambientLight, textureLighting, atlasScale, autoCenter, className, style, children, position: _position, scale: _scale, rotation: _rotation, debugShowLabels: _debugShowLabels, debugShowBackfaces, }: PolySceneProps): react_jsx_runtime.JSX.Element;
+declare const PolyScene: react.MemoExoticComponent<typeof PolySceneInner>;
+
+type UseMeshOptions = LoadMeshOptions;
+interface UseMeshResult {
+    polygons: Polygon[];
+    loading: boolean;
+    error: Error | null;
+    warnings: string[];
+    /** Manually trigger cleanup (also called on unmount automatically). */
+    dispose: () => void;
+}
+declare function usePolyMesh(src: string, options?: UseMeshOptions): UseMeshResult;
+
+/**
+ * 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
+ * native pointer events for free — no raycaster, no canvas event
+ * synthesis.
+ *
+ * Diverges from r3f in two intentional ways:
+ *   1. Bubbling matches DOM (pointer hits the front element only). r3f
+ *      replays events to occluded objects behind the front hit; doing
+ *      that here would require running our own raycaster, which defeats
+ *      the point of being DOM-native.
+ *   2. `face`, `uv`, `uv1`, `instanceId` are omitted — they're three.js
+ *      BufferGeometry / InstancedMesh concepts with no polycss analogue.
+ *      The polycss-native equivalent of `face` is the hit polygon's
+ *      index, exposed via `polygon` (set when the underlying DOM target
+ *      is an `<i>` polygon element).
+ */
+
+/**
+ * Imperative handle exposed by `<PolyMesh ref>`. Read-only view of the
+ * mesh's element + current transform + polygons. Mutation flows through
+ * controlled props (parent owns transform state) — matches three.js
+ * editor's pattern of keeping `selected` external to the object.
+ */
+interface PolyMeshHandle {
+    /** The `.polycss-mesh` wrapper div (null until mounted). */
+    readonly element: HTMLDivElement | null;
+    /** Identifier passed via the `id` prop, if any. */
+    readonly id?: string;
+    /** Current `position` prop value. */
+    getPosition(): Vec3 | undefined;
+    /** Current `rotation` prop value (Euler degrees). */
+    getRotation(): Vec3 | undefined;
+    /** Current `scale` prop value. */
+    getScale(): number | Vec3 | undefined;
+    /** Polygons currently being rendered (post-autoCenter). */
+    getPolygons(): Polygon[];
+    /**
+     * Snapshot the current `rotation` prop as the new "baked rotation" and
+     * trigger an atlas re-rasterization with the directional light
+     * inverse-rotated into the mesh's local frame.
+     *
+     * Call this after a rotate-mode drag ends (i.e. on pointer release) —
+     * **not** on every pointermove during the drag. The visual wrapper already
+     * follows the live `rotation` prop smoothly; the atlas only needs to
+     * update once per committed rotation so it doesn't re-bake every frame.
+     *
+     * Math rationale: baked atlas tiles encode `baseColor × Lambert(worldNormal,
+     * worldLight)`. When the mesh wrapper rotates via CSS the world-space normal
+     * changes but the baked color does not, causing stale shading. Calling
+     * `rebakeAtlas()` inverse-rotates the world light into the mesh-local frame
+     * before re-running the atlas baker, so `dot(localNormal, localLight) ===
+     * dot(worldNormal, worldLight)` and the shading is correct again.
+     *
+     * In dynamic (`textureLighting="dynamic"`) mode this call is a no-op for
+     * shading purposes (dynamic mode re-evaluates per frame), but it is still
+     * safe to call.
+     */
+    rebakeAtlas(): void;
+}
+/**
+ * Pointer event payload delivered to <PolyMesh> handlers. Mirrors r3f's
+ * shape, minus raycaster-specific fields. See module docstring for the
+ * intentional divergences.
+ */
+interface PolyPointerEvent<E extends Event = PointerEvent> {
+    /** The mesh originally under the pointer (deepest hit). */
+    object: PolyMeshHandle;
+    /** The mesh whose handler is being invoked. Equal to `object` until
+     *  ancestor bubbling is added (out of scope for v1). */
+    eventObject: PolyMeshHandle;
+    /** All meshes stacked under the pointer this moment, front-to-back.
+     *  Computed via `document.elementsFromPoint` then filtered to
+     *  registered `.polycss-mesh` ancestors. */
+    intersections: Array<{
+        object: PolyMeshHandle;
+    }>;
+    /** Pointer position in normalized device coords [-1, 1] relative to
+     *  the camera viewport. (0,0) = viewport center. Falls back to (0,0)
+     *  when the mesh is rendered outside a `<PolyCamera>`. */
+    pointer: {
+        x: number;
+        y: number;
+    };
+    /** Pixel distance from the most recent `pointerdown` to this event.
+     *  0 on pointerdown itself. Use to discriminate click-vs-drag. */
+    delta: number;
+    /** The underlying DOM event. */
+    nativeEvent: E;
+    /** Stops native bubbling. (Equivalent to `nativeEvent.stopPropagation()`
+     *  today; reserved for future r3f-style bubbling above the wrapper.) */
+    stopPropagation(): void;
+}
+type PolyMouseEvent = PolyPointerEvent<MouseEvent>;
+type PolyWheelEvent = PolyPointerEvent<WheelEvent>;
+type PolyEventHandler<E extends Event = PointerEvent> = (event: PolyPointerEvent<E>) => void;
+/**
+ * Pointer / mouse / wheel handlers accepted by `<PolyMesh>`. Names mirror
+ * r3f exactly. Provide any handler to opt the mesh into receiving events;
+ * absent handlers add zero overhead.
+ */
+interface InteractionProps {
+    onClick?: PolyEventHandler<MouseEvent>;
+    onContextMenu?: PolyEventHandler<MouseEvent>;
+    onDoubleClick?: PolyEventHandler<MouseEvent>;
+    onWheel?: PolyEventHandler<WheelEvent>;
+    onPointerDown?: PolyEventHandler<PointerEvent>;
+    onPointerUp?: PolyEventHandler<PointerEvent>;
+    onPointerMove?: PolyEventHandler<PointerEvent>;
+    onPointerOver?: PolyEventHandler<PointerEvent>;
+    onPointerOut?: PolyEventHandler<PointerEvent>;
+    onPointerEnter?: PolyEventHandler<PointerEvent>;
+    onPointerLeave?: PolyEventHandler<PointerEvent>;
+    onPointerCancel?: PolyEventHandler<PointerEvent>;
+}
+/** Walk up from `el` looking for the nearest registered mesh wrapper. */
+declare function findPolyMeshHandle(el: Element | null): PolyMeshHandle | null;
+/** Test whether `(clientX, clientY)` falls inside any polygon leaf
+ *  child of `meshEl`'s post-3D bounding rect. Skips zero-area rects
+ *  (happy-dom and pre-layout SSR return those). */
+declare function pointInMeshElement(meshEl: HTMLElement, clientX: number, clientY: number): boolean;
+/** Walk every registered `.polycss-mesh` in the document and return
+ *  the first whose polygon bounding-rects contain `(clientX, clientY)`.
+ *  An optional `filter` skips matched mesh elements (e.g. gizmos). */
+declare function findMeshUnderPoint(clientX: number, clientY: number, filter?: (meshEl: HTMLElement) => boolean): PolyMeshHandle | null;
+
+interface PolyMeshProps extends TransformProps, InteractionProps {
+    /** Stable identifier — exposed on the mesh handle and reflected as
+     *  `data-poly-mesh-id` on the wrapper div. Use for selection lookups. */
+    id?: string;
+    /** URL to .obj / .glb / .gltf. Mutually exclusive with `polygons`. */
+    src?: string;
+    /**
+     * Companion `.mtl` URL for OBJ models. When set, materials defined in
+     * the mtl (Kd colors, map_Kd textures) are applied to the loaded mesh.
+     * Ignored for GLB/GLTF (they carry materials inline).
+     */
+    mtl?: string;
+    /** Pre-parsed polygons. Mutually exclusive with `src`. */
+    polygons?: Polygon[];
+    /** Translate so mesh's bbox center is at local origin before applying `position`. */
+    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;
+    /** 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;
+    className?: string;
+    style?: CSSProperties;
+}
+declare const PolyMesh: react.ForwardRefExoticComponent<PolyMeshProps & react.RefAttributes<PolyMeshHandle>>;
+
+interface UseSceneContextOptions {
+    directionalLight?: PolyDirectionalLight;
+}
+interface UseSceneContextResult {
+    polygons: Polygon[];
+    sceneBbox: {
+        min: Vec3;
+        max: Vec3;
+    };
+}
+/**
+ * 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.
+ */
+declare function usePolySceneContext(polygons: Polygon[], options: UseSceneContextOptions): UseSceneContextResult;
+
+/**
+ * usePolyMaterial — memoizes a shared material handle so the same
+ * (texture, key) inputs always return a stable object reference.
+ *
+ * Stable references matter for <Poly memo> shallow-compare: if the material
+ * object identity is stable, tiles that share the same material won't
+ * re-render just because a parent re-rendered.
+ *
+ * Future: additional material props (color tint, opacity, blend, lighting
+ * overrides) will live here.
+ */
+declare function usePolyMaterial(options: {
+    texture: string;
+    key?: string;
+}): PolyMaterial;
+
+/**
+ * Poly — renders one polygon as an atlas-backed DOM sprite.
+ *
+ * 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.
+ *
+ * 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
+ * check is sound here because polygon data (vertices, color, texture) is
+ * typically created once at parse time and passed by reference.
+ */
+declare function PolyInner({ vertices, color, texture, uvs, data, material, position, scale, rotation, className, style: styleProp, id, onClick, onDoubleClick, onMouseEnter, onMouseLeave, onMouseMove, onPointerDown, onPointerUp, onPointerEnter, onPointerLeave, onFocus, onBlur, onKeyDown, tabIndex, role, "aria-label": ariaLabel, "aria-hidden": ariaHidden, pointerEvents: pointerEventsProp, context, textureLighting: textureLightingProp, atlasScale: atlasScaleProp, baseColor: baseColorProp, ...dataAttrs }: PolyProps): react_jsx_runtime.JSX.Element | null;
+declare const Poly: react__default.MemoExoticComponent<typeof PolyInner>;
+
+interface PolyControlsAnimateOptions {
+    /** Degrees per 60Hz-equivalent frame. Default 0.3 (≈ 18 deg/sec). */
+    speed?: number;
+    /** Rotation axis. Default "y". */
+    axis?: "x" | "y";
+    /** Pause animate while a pointer drag is in progress. Default true. */
+    pauseOnInteraction?: boolean;
+}
+interface PolyControlsCamera {
+    rotX: number;
+    rotY: number;
+    zoom: number;
+    target: Vec3;
+    distance: number;
+}
+interface SharedControlsProps {
+    /** Pointer-drag. Default true. */
+    drag?: boolean;
+    /** Wheel / pinch zoom. Default true. */
+    wheel?: boolean;
+    /**
+     * Dolly mode: wheel changes `distance` (camera pull-back in CSS pixels)
+     * instead of `zoom` (CSS scale). Mirrors three.js OrbitControls dolly.
+     * Default false (wheel changes zoom). When true, use `minDistance` /
+     * `maxDistance` to clamp the range.
+     */
+    dolly?: boolean;
+    /** Drag-direction inversion. Number = sensitivity multiplier. Default false. */
+    invert?: boolean | number;
+    /** Minimum zoom (CSS scale). Default 0.1. */
+    minZoom?: number;
+    /** Maximum zoom (CSS scale). Default 10. */
+    maxZoom?: number;
+    /** Minimum camera distance in CSS pixels when dolly is enabled. Default 0. */
+    minDistance?: number;
+    /** Maximum camera distance in CSS pixels when dolly is enabled. Default 5000. */
+    maxDistance?: number;
+    /** Auto-rotate. Pass false (or omit) to disable. */
+    animate?: false | PolyControlsAnimateOptions;
+    /**
+     * Fires whenever the controls mutate camera state.
+     */
+    onChange?: (camera: PolyControlsCamera) => void;
+    onInteractionStart?: (camera: PolyControlsCamera) => void;
+    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;
+
+/** Optional ref-or-direct binding to a target mesh. */
+type PolyTransformControlsObject = PolyMeshHandle | RefObject<PolyMeshHandle | null> | null;
+interface PolyTransformControlsObjectChangeEvent {
+    /** The mesh being transformed. */
+    object: PolyMeshHandle;
+    /** The new position. Only emitted when `mode` is "translate". */
+    position?: Vec3;
+    /** The new Euler rotation (degrees, X/Y/Z). Only emitted when
+     *  `mode` is "rotate". */
+    rotation?: Vec3;
+}
+interface PolyTransformControlsProps {
+    /** Mesh to attach to. Pass a ref returned from `useRef<PolyMeshHandle>()`
+     *  or a handle directly. `null` hides the gizmo. */
+    object: PolyTransformControlsObject;
+    /** Drag mode. "translate" → axial arrows, "rotate" → axial rings. */
+    mode?: "translate" | "rotate";
+    /** Axis basis. Only "world" is implemented in v1. */
+    space?: "world" | "local";
+    /** Multiplier on gizmo size (shaft length / ring radius). Default 1. */
+    size?: number;
+    /** Show / hide axis gizmo PAIRS. Default true. In translate mode this
+     *  hides both the +/- arrows for that axis; in rotate mode this hides
+     *  the corresponding ring. */
+    showX?: boolean;
+    showY?: boolean;
+    showZ?: boolean;
+    /** Snap step (CSS pixels) for translate-mode dragging. */
+    translationSnap?: number | null;
+    /** Snap step (degrees) for rotate-mode dragging. */
+    rotationSnap?: number | null;
+    /** Disable interaction without unmounting. Default true. */
+    enabled?: boolean;
+    /** Fires for any transform change. Argument-less, mirrors three.js. */
+    onChange?: () => void;
+    /** Fires with the new transform during drag. Use this to update
+     *  position state — controlled flow, parent owns state. */
+    onObjectChange?: (event: PolyTransformControlsObjectChangeEvent) => void;
+    /** Fires once on drag start. */
+    onMouseDown?: () => void;
+    /** Fires once on drag end. */
+    onMouseUp?: () => void;
+    /** Fires with `true` on drag start, `false` on drag end. Mirrors
+     *  three.js's `'dragging-changed'` event (kebab-case preserved here
+     *  via the boolean payload, since react prop naming is camelCase). */
+    onDraggingChanged?: (dragging: boolean) => void;
+}
+declare function PolyTransformControls({ object, mode, space, size, showX, showY, showZ, translationSnap, rotationSnap, enabled, onChange, onObjectChange, onMouseDown, onMouseUp, onDraggingChanged, }: PolyTransformControlsProps): react_jsx_runtime.JSX.Element | null;
+
+interface PolySelectionApi {
+    /** Current selection. Stable reference between renders unless changed. */
+    selected: PolyMeshHandle[];
+    /** Replace selection wholesale. */
+    set(next: PolyMeshHandle[]): void;
+    /** Add to selection (or replace, when `multiple` is false). */
+    add(handle: PolyMeshHandle): void;
+    /** Remove from selection. No-op if not present. */
+    remove(handle: PolyMeshHandle): void;
+    /** Toggle membership. With `multiple=false`, toggling a non-selected
+     *  mesh replaces selection; toggling the selected mesh clears. */
+    toggle(handle: PolyMeshHandle): void;
+    /** Clear selection. */
+    clear(): void;
+    /** Membership test. */
+    has(handle: PolyMeshHandle): boolean;
+}
+interface PolySelectProps {
+    /** Allow multiple meshes selected at once. Default false. */
+    multiple?: boolean;
+    /** Optional filter applied to every selection change. Returned array
+     *  becomes the new selection. */
+    filter?: (meshes: PolyMeshHandle[]) => PolyMeshHandle[];
+    /** Fires after every selection change with the new array. */
+    onChange?: (meshes: PolyMeshHandle[]) => void;
+    /** Fires when a click lands inside the Select wrapper but resolves to
+     *  no mesh ancestor (i.e. the background). Receives the click event. */
+    onPointerMissed?: (event: MouseEvent$1<HTMLDivElement>) => void;
+    /** When true (default), clicking the background clears selection. */
+    clearOnMiss?: boolean;
+    children?: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Selection wrapper. The host element uses `display: contents` by default
+ * so it doesn't affect CSS layout — its descendants render as if it
+ * weren't there, while pointer events still bubble through it.
+ */
+declare function PolySelect({ multiple, filter, onChange, onPointerMissed, clearOnMiss, children, className, style, }: PolySelectProps): react_jsx_runtime.JSX.Element;
+/**
+ * Read the current selection from the nearest enclosing `<Select>`.
+ * Returns an empty array when used outside a `<Select>` (matches drei).
+ */
+declare function usePolySelect(): PolyMeshHandle[];
+/**
+ * Read the imperative selection API. Throws when used outside `<PolySelect>`
+ * — fail loudly because callers expect to mutate.
+ */
+declare function usePolySelectionApi(): PolySelectionApi;
+
+interface PolyAxesHelperProps {
+    /** Length of each axis bar in world units. */
+    size?: number;
+    /** Bar cross-section width as a fraction of `size`. */
+    thickness?: number;
+    /** When true, also draws bars in the −X / −Y / −Z direction. */
+    negative?: boolean;
+    /** X-axis bar color. Mirrors three.js's red/green/blue convention. */
+    xColor?: string;
+    yColor?: string;
+    zColor?: string;
+}
+/**
+ * PolyAxesHelper — three colored bars from world origin along +X / +Y / +Z.
+ * Mirrors three.js's `AxesHelper`: red=X, green=Y, blue=Z.
+ *
+ * Renders inside the parent scene's transform, so it inherits camera
+ * rotation and zoom automatically.
+ */
+declare function PolyAxesHelper({ size, thickness, negative, xColor, yColor, zColor, }: PolyAxesHelperProps): react_jsx_runtime.JSX.Element;
+
+interface PolyDirectionalLightHelperProps {
+    /** Light to visualize. */
+    light: PolyDirectionalLight;
+    /**
+     * Point the marker orbits around, in world coords. Mirrors three.js's
+     * `DirectionalLight.target.position` — usually the mesh's bbox center.
+     * Defaults to the world origin.
+     */
+    target?: Vec3;
+    /** Distance from `target` to render the source marker, in world units. */
+    distance?: number;
+    /** Marker half-extent in world units. */
+    size?: number;
+    /** Marker color override. Defaults to `light.color`. */
+    color?: string;
+}
+/**
+ * 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.
+ *
+ * The octahedron is built at LOCAL origin once; the world position is
+ * applied via PolyMesh's `position` prop (a CSS transform on the wrapper).
+ * That keeps the polygons array reference-stable across light-direction
+ * changes — the atlas does not rebuild and the marker glides smoothly.
+ */
+declare function PolyDirectionalLightHelper({ light, target, distance, size, color, }: PolyDirectionalLightHelperProps): react_jsx_runtime.JSX.Element;
+
+declare function injectPolyBaseStyles(doc?: Document): void;
+
+interface UsePolyAnimationResult {
+    /** Attach to a `PolyAnimationTarget`-compatible handle when not using `root`. */
+    ref: RefObject<PolyAnimationTarget | null>;
+    /** The active mixer, or null if inputs are not ready yet. */
+    mixer: PolyAnimationMixer | null;
+    /** Resolved clip list (empty when `clips` is undefined). */
+    clips: PolyAnimationClip[];
+    /** Clip names in input order. */
+    names: string[];
+    /**
+     * Lazy action proxy keyed by clip name. Accessing `actions["walk"]`
+     * instantiates the action if it does not exist yet. Returns null when the
+     * mixer is not ready.
+     */
+    actions: Record<string, PolyAnimationAction | null>;
+}
+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 };