@layoutit/polycss 0.2.1 → 0.2.3

package/README.md

@@ -1,6 +1,6 @@
 # PolyCSS
 
-A CSS polygon mesh library. A 3D engine for the DOM. Renders OBJ/MTL, GLB and VOX as real HTML elements transformed with CSS `matrix3d(...)`. Supports colors, textures, lighting, shadows, shapes and animations. Works with React, Vue or plain JavaScript.
+A CSS polygon mesh library. A 3D engine for the DOM. Renders OBJ/MTL, STL, glTF/GLB, and VOX as real HTML elements transformed with CSS `matrix3d(...)`. Supports colors, textures, lighting, shadows, shapes and animations. Works with React, Vue or plain JavaScript.
 
 Visit [polycss.com](https://polycss.com) for docs and model examples.
 
@@ -72,7 +72,6 @@ export default function App() {
 - `directionalLight` and `ambientLight` control scene lighting.
 - `textureLighting` chooses `"baked"` or `"dynamic"`.
 - `textureQuality` controls atlas raster budget.
-- Solid seam bleed is automatic on detected shared solid edges.
 - `strategies` can disable selected render strategies for diagnostics.
 - `autoCenter` rotates around the rendered mesh bounds instead of world origin.
 
@@ -83,8 +82,9 @@ export default function App() {
 - `polygons` accepts pre-parsed geometry.
 - `position`, `scale`, and `rotation` transform the mesh wrapper.
 - `autoCenter` shifts the mesh bbox center to local origin.
-- `meshResolution` chooses `"lossy"` (default) or `"lossless"` optimization.
+- `meshResolution` chooses `"lossy"` (default) or `"lossless"` optimization. STL imports use the conservative lossless path in both modes.
 - `castShadow` emits CSS-projected shadows in dynamic lighting mode.
+- Tooling can reuse `buildPolyMeshTransform`, `worldPositionToPolyCss`, and `worldDirectionToPolyCss` for renderer-compatible transforms.
 
 ### Controls
 
@@ -93,6 +93,18 @@ export default function App() {
 - `<PolyFirstPersonControls>` provides keyboard and pointer-look navigation.
 - `<PolyTransformControls>` adds translate/rotate gizmos for selected mesh handles.
 
+### Snapshot Export
+
+The vanilla package exports `exportPolySceneSnapshot(target)`. It clones the current rendered `.polycss-camera` / `.polycss-scene` DOM, injects only the PolyCSS CSS needed by that snapshot, inlines CSS `url(...)` image assets as `data:image/...;base64,...`, strips scripts and inline event handlers, and returns a standalone HTML document string with no PolyCSS runtime import. It works with rendered React/Vue scenes too; import it from `@layoutit/polycss` and pass the rendered camera or scene element.
+
+```ts
+import { exportPolySceneSnapshot } from "@layoutit/polycss";
+
+const html = await exportPolySceneSnapshot(scene.host);
+```
+
+If any referenced asset cannot be inlined, the function throws `PolySceneSnapshotError` with `code: "ASSET_INLINE_FAILED"`.
+
 ### Polygon Data Model
 
 Each polygon describes one renderable face:
@@ -149,22 +161,14 @@ scene.add(mesh);
 Supported formats:
 
 - OBJ + MTL, including `map_Kd` textures and UV coordinates.
+- STL triangle meshes, including binary Magics face colors. STL has no standard units, textures, UVs, or hierarchy, so imports skip lossy simplification and ray-based interior culling.
 - glTF / GLB, including embedded images and `TEXCOORD_0`.
 - MagicaVoxel `.vox`, with direct voxel fast paths when eligible.
 - Generated primitives: box, plane, ring, sphere, torus, cylinder, cone, and Platonic solids.
 
 ## Performance
 
-PolyCSS renders in the DOM, so performance is mostly determined by how many polygons are mounted and how much texture atlas area they consume. The renderer uses several CSS strategies so simple surfaces stay cheap and textured or irregular surfaces fall back to atlas slices.
-
-- One visible polygon becomes one leaf DOM element.
-- Flat rectangles and stable quads use solid CSS leaves.
-- Textured polygons are packed into generated texture atlases.
-- Dynamic lighting runs through CSS custom properties instead of per-frame JavaScript.
-- Voxel-shaped meshes mount only camera-facing leaves when the mesh is eligible.
-- `meshResolution: "lossy"` merges compatible polygons, then may spend a small split budget to repair high-risk seams.
-
-Renderer internals:
+PolyCSS renders through the DOM, so performance is mostly shaped by two things: the number of mounted leaves, and the amount of texture atlas area the browser has to paint. The renderer tries to keep the common cases cheap. Simple surfaces stay as solid CSS elements, while textured, irregular, or high-detail geometry falls back to atlas-backed slices only when needed.
 
 Each visible polygon is emitted as one leaf element; the renderer chooses the least expensive CSS primitive that can represent the polygon, then uses `matrix3d(...)` to place that primitive in 3D space.
 

package/dist/{PolyShapeElements-prI_DBZX.d.cts → PolyShapeElements-CoKhApyN.d.cts}

@@ -9,7 +9,7 @@ interface PolyCameraOptions {
     distance?: number;
 }
 interface PolyPerspectiveCameraOptions extends PolyCameraOptions {
-    /** CSS perspective distance in pixels. Default 8000. */
+    /** CSS perspective distance in pixels. Default 32000. */
     perspective?: number;
 }
 interface PolyOrthographicCameraOptions extends PolyCameraOptions {
@@ -28,7 +28,7 @@ interface PolyOrthographicCameraHandle extends CameraHandle {
 /**
  * Creates a perspective camera handle. The `perspectiveStyle` property
  * returns the CSS value to apply to the camera container's `perspective`
- * property (default `"8000px"`).
+ * property (default `"32000px"`).
  */
 declare function createPolyPerspectiveCamera(options?: PolyPerspectiveCameraOptions): PolyPerspectiveCameraHandle;
 /**
@@ -47,25 +47,10 @@ declare function createPolyOrthographicCamera(options?: PolyOrthographicCameraOp
 declare const createPolyCamera: typeof createPolyOrthographicCamera;
 
 /**
- * createPolyScene — imperative scene API. The vanilla counterpart to
- * `<PolyScene>` in React / Vue.
- *
- * Per §API freeze: takes a host element + scene options, returns a
- * `PolySceneHandle` whose `add(parseResult, transform?)` mounts a mesh under
- * the scene root and returns a removable `PolyMeshHandle`.
- *
- * Implementation:
- *   - Inserts a `<div class="polycss-scene">` into the host.
- *   - Each `add(...)` creates a `<div class="polycss-mesh">` with the
- *     mesh transform; mounts every valid polygon as an atlas-backed
- *     background sprite.
- *   - `destroy()` removes the scene element and disposes every mesh
- *     (which in turn disposes generated atlas blob URLs).
- *
- * The scene element is a 0×0 anchor at world (0,0,0) — pinned via
- * top:50%/left:50% so it sits at the visible center of the host. This
- * matches React/Vue's PolyScene anchor pattern. Polygons render around
- * the anchor via their own matrix3d translations.
+ * Public + internal types for the scene module, extracted from
+ * createPolyScene.ts so other scene/* helpers can import them without
+ * pulling in the whole factory body. createPolyScene.ts re-exports the
+ * public ones so the polycss package public surface is unchanged.
  */
 
 interface PolySceneOptions {
@@ -131,6 +116,15 @@ interface PolySceneOptions {
          */
         maxExtend?: number;
     };
+    /**
+     * When `true`, emit `data-poly-shadow-*` attribution attributes on every
+     * shadow SVG and path (type, receiver mesh id, receiver face index,
+     * member poly indices, caster ids, caster poly indices). Useful for
+     * DevTools inspection and per-poly attribution in debug benches. When
+     * `false` (default), these attributes are suppressed entirely — production
+     * scenes ship a cleaner DOM and avoid serializing per-frame JSON.
+     */
+    debugShadowAttrs?: boolean;
 }
 interface PolyMeshTransform {
     /** Stable identifier — exposed on the handle and reflected on the
@@ -193,8 +187,7 @@ interface PolyMeshHandle {
      *  the wrapper as `data-poly-mesh-id`. */
     readonly id?: string;
     /** Current transform snapshot (position / rotation / scale). Returned
-     *  by reference — treat as read-only and use `setTransform` to
-     *  mutate. */
+     *  by reference — treat as read-only and use `setTransform` to mutate. */
     readonly transform: PolyMeshTransform;
     /** Remove the mesh from the scene. */
     remove(): void;
@@ -265,6 +258,11 @@ interface PolySceneHandle {
      * FPV controls toggle `.polycss-fpv-host` on this element.
      */
     readonly cameraEl: HTMLElement;
+    /**
+     * The `.polycss-scene` root element inside `cameraEl`. Mesh wrappers, shadow
+     * roots, and helper DOM are mounted under this element.
+     */
+    readonly sceneElement: HTMLElement;
     /**
      * The camera handle this scene is bound to. Controls update camera state
      * via `scene.camera.update({...})` then call `scene.applyCamera()` to
@@ -290,10 +288,101 @@ interface PolySceneHandle {
      *  the element doesn't belong to this scene. */
     findMeshByElement(element: Element | null): PolyMeshHandle | null;
 }
-declare function createPolyScene(host: HTMLElement, options: PolySceneOptions): PolySceneHandle;
 
-declare const ELEMENT_BASE$a: typeof HTMLElement;
-declare class PolySceneElement extends ELEMENT_BASE$a {
+/**
+ * Shared types, constants, and utilities for orbit/map controls factories.
+ * Not part of the public API surface — use createPolyOrbitControls or
+ * createPolyMapControls.
+ */
+
+interface PolyControlsAnimateOptions {
+    /**
+     * Rotation rate in degrees per 60 Hz-equivalent frame. The tick is
+     * dt-clamped so 0.3 deg/frame ≈ 18 deg/sec on every refresh rate.
+     * Default: 0.3.
+     */
+    speed?: number;
+    /** Rotation axis. Default: "y" (yaw, rotates around vertical world Z). */
+    axis?: "x" | "y";
+    /** Halt the loop while a pointer drag is in progress. Default: true. */
+    pauseOnInteraction?: boolean;
+}
+interface PolyControlsBaseOptions {
+    /** Pointer-drag. Default: true. */
+    drag?: boolean;
+    /** Wheel / pinch zoom. Default: true. */
+    wheel?: boolean;
+    /**
+     * When `true`, wheel events change `distance` (camera pull-back in CSS px)
+     * instead of `zoom`. Mirrors Three.js OrbitControls dolly behaviour.
+     * Default: false (zoom mode).
+     */
+    dolly?: boolean;
+    /**
+     * Drag-direction inversion. `false` = natural, `true` = invert (×-1),
+     * a number multiplies sensitivity (negative inverts). Default: false.
+     */
+    invert?: boolean | number;
+    /** Minimum CSS zoom. Default: 0.1. */
+    minZoom?: number;
+    /** Maximum CSS zoom. Default: 10. */
+    maxZoom?: number;
+    /** Minimum dolly distance in CSS pixels. Default: 0. Only used when `dolly: true`. */
+    minDistance?: number;
+    /** Maximum dolly distance in CSS pixels. Default: Infinity. Only used when `dolly: true`. */
+    maxDistance?: number;
+    /** Auto-rotate. Pass false (or omit) to disable. */
+    animate?: false | PolyControlsAnimateOptions;
+}
+interface PolyControlsCamera {
+    rotX: number;
+    rotY: number;
+    zoom: number;
+    target: Vec3;
+    distance: number;
+}
+interface PolyControlsChangeEvent {
+    type: "change";
+    camera: PolyControlsCamera;
+}
+interface PolyControlsInteractionEvent {
+    type: "start" | "end";
+    camera: PolyControlsCamera;
+}
+type PolyControlsEvent = PolyControlsChangeEvent | PolyControlsInteractionEvent;
+type PolyControlsListener<E extends PolyControlsEvent = PolyControlsEvent> = (event: E) => void;
+interface PolyControlsHandle {
+    update(partial: PolyControlsBaseOptions): void;
+    resume(): void;
+    pause(): void;
+    destroy(): void;
+    addEventListener<T extends PolyControlsEvent["type"]>(type: T, listener: PolyControlsListener<Extract<PolyControlsEvent, {
+        type: T;
+    }>>): void;
+    removeEventListener<T extends PolyControlsEvent["type"]>(type: T, listener: PolyControlsListener<Extract<PolyControlsEvent, {
+        type: T;
+    }>>): void;
+    hasEventListener<T extends PolyControlsEvent["type"]>(type: T, listener: PolyControlsListener<Extract<PolyControlsEvent, {
+        type: T;
+    }>>): boolean;
+}
+
+/**
+ * createPolyOrbitControls — orbit-mode camera input for a PolyScene.
+ *
+ * Left-drag rotates rotX / rotY around the target (orbit). Wheel zooms or
+ * dollies. Mirrors Three.js OrbitControls semantics.
+ *
+ * For map/pan semantics (left-drag pans, right-drag orbits) use
+ * `createPolyMapControls` instead.
+ */
+
+type PolyOrbitControlsOptions = PolyControlsBaseOptions;
+type PolyOrbitControlsHandle = PolyControlsHandle;
+declare function createPolyOrbitControls(scene: PolySceneHandle, options?: PolyOrbitControlsOptions): PolyOrbitControlsHandle;
+
+declare const ELEMENT_BASE$b: typeof HTMLElement;
+declare class PolySceneElement extends ELEMENT_BASE$b {
     static get observedAttributes(): string[];
     private _scene;
     private _implicitCamera;
@@ -312,8 +401,8 @@ declare class PolySceneElement extends ELEMENT_BASE$a {
     attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
 }
 
-declare const ELEMENT_BASE$9: typeof HTMLElement;
-declare class PolyMeshElement extends ELEMENT_BASE$9 {
+declare const ELEMENT_BASE$a: typeof HTMLElement;
+declare class PolyMeshElement extends ELEMENT_BASE$a {
     static get observedAttributes(): string[];
     private _handle;
     private _parseResult;
@@ -327,6 +416,21 @@ declare class PolyMeshElement extends ELEMENT_BASE$9 {
     private _maybeLoad;
 }
 
+declare const ELEMENT_BASE$9: typeof HTMLElement;
+declare class PolyIframeElement extends ELEMENT_BASE$9 {
+    static get observedAttributes(): string[];
+    private _wrapper;
+    private _iframe;
+    /** The iframe element this <poly-iframe> mounted, or null when detached. */
+    getIframeElement(): HTMLIFrameElement | null;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+    private _mount;
+    private _applyGeometry;
+    private _teardown;
+}
+
 declare const ELEMENT_BASE$8: typeof HTMLElement;
 declare class PolyPolygonElement extends ELEMENT_BASE$8 {
     static get observedAttributes(): string[];
@@ -342,6 +446,11 @@ declare const ELEMENT_BASE$7: typeof HTMLElement;
 declare class PolyOrbitControlsElement extends ELEMENT_BASE$7 {
     static get observedAttributes(): string[];
     private _controls;
+    /** Returns the wrapped PolyOrbitControlsHandle once the element has
+     *  connected to its `<poly-scene>` ancestor. Lets external callers attach
+     *  `change` listeners (or call `update()` / `pause()`) the same way they
+     *  would on a vanilla `createPolyOrbitControls(scene, ...)` handle. */
+    getControls(): PolyOrbitControlsHandle | null;
     private _readAnimate;
     private _readOptions;
     private _findScene;
@@ -385,7 +494,7 @@ declare class PolyFirstPersonControlsElement extends ELEMENT_BASE$5 {
  * CSS `perspective` property set.
  *
  * Attributes (all optional):
- *   perspective   — number, CSS perspective in pixels (default 8000)
+ *   perspective   — number, CSS perspective in pixels (default 32000)
  *   zoom          — number
  *   rot-x         — number, degrees (default 65)
  *   rot-y         — number, degrees (default 45)
@@ -405,7 +514,7 @@ declare class PolyPerspectiveCameraElement extends ELEMENT_BASE$4 {
     private _teardown;
     connectedCallback(): void;
     disconnectedCallback(): void;
-    attributeChangedCallback(_name: string, oldValue: string | null, newValue: string | null): void;
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
 }
 
 /**
@@ -498,6 +607,7 @@ declare abstract class PolyShapeElement extends ELEMENT_BASE {
     abstract buildPolygons(): Polygon[];
     connectedCallback(): void;
     disconnectedCallback(): void;
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
     private _tearDown;
     private _mount;
 }
@@ -546,4 +656,4 @@ declare class PolyTorusElement extends PolyShapeElement {
     buildPolygons(): Polygon[];
 }
 
-export { PolySphereElement as A, PolyTetrahedronElement as B, PolyTorusElement as C, PolyTransformControlsElement as D, createPolyCamera as E, createPolyOrthographicCamera as F, createPolyPerspectiveCamera as G, createPolyScene as H, type PolySceneHandle as P, type PolyMeshHandle as a, PolyBoxElement as b, PolyCameraElement as c, type PolyCameraOptions as d, PolyConeElement as e, PolyCylinderElement as f, PolyDodecahedronElement as g, PolyFirstPersonControlsElement as h, PolyIcosahedronElement as i, PolyMapControlsElement as j, PolyMeshElement as k, type PolyMeshTransform as l, PolyOctahedronElement as m, PolyOrbitControlsElement as n, PolyOrthographicCameraElement as o, type PolyOrthographicCameraHandle as p, type PolyOrthographicCameraOptions as q, PolyPerspectiveCameraElement as r, type PolyPerspectiveCameraHandle as s, type PolyPerspectiveCameraOptions as t, PolyPlaneElement as u, PolyPolygonElement as v, PolyRingElement as w, PolySceneElement as x, type PolySceneOptions as y, PolySelectElement as z };
+export { PolyOrthographicCameraElement as A, type PolyOrthographicCameraHandle as B, type PolyOrthographicCameraOptions as C, PolyPerspectiveCameraElement as D, type PolyPerspectiveCameraHandle as E, type PolyPerspectiveCameraOptions as F, PolyPlaneElement as G, PolyPolygonElement as H, PolyRingElement as I, PolySceneElement as J, PolySelectElement as K, PolySphereElement as L, PolyTetrahedronElement as M, PolyTorusElement as N, PolyTransformControlsElement as O, type PolySceneOptions as P, createPolyCamera as Q, createPolyOrbitControls as R, createPolyOrthographicCamera as S, createPolyPerspectiveCamera as T, type PolySceneHandle as a, type PolyControlsHandle as b, type PolyControlsBaseOptions as c, type PolyControlsEvent as d, type PolyControlsListener as e, type PolyMeshHandle as f, PolyBoxElement as g, PolyCameraElement as h, type PolyCameraOptions as i, PolyConeElement as j, type PolyControlsAnimateOptions as k, type PolyControlsCamera as l, type PolyControlsChangeEvent as m, type PolyControlsInteractionEvent as n, PolyCylinderElement as o, PolyDodecahedronElement as p, PolyFirstPersonControlsElement as q, PolyIcosahedronElement as r, PolyIframeElement as s, PolyMapControlsElement as t, PolyMeshElement as u, type PolyMeshTransform as v, PolyOctahedronElement as w, PolyOrbitControlsElement as x, type PolyOrbitControlsHandle as y, type PolyOrbitControlsOptions as z };

package/dist/{PolyShapeElements-prI_DBZX.d.ts → PolyShapeElements-CoKhApyN.d.ts}

@@ -9,7 +9,7 @@ interface PolyCameraOptions {
     distance?: number;
 }
 interface PolyPerspectiveCameraOptions extends PolyCameraOptions {
-    /** CSS perspective distance in pixels. Default 8000. */
+    /** CSS perspective distance in pixels. Default 32000. */
     perspective?: number;
 }
 interface PolyOrthographicCameraOptions extends PolyCameraOptions {
@@ -28,7 +28,7 @@ interface PolyOrthographicCameraHandle extends CameraHandle {
 /**
  * Creates a perspective camera handle. The `perspectiveStyle` property
  * returns the CSS value to apply to the camera container's `perspective`
- * property (default `"8000px"`).
+ * property (default `"32000px"`).
  */
 declare function createPolyPerspectiveCamera(options?: PolyPerspectiveCameraOptions): PolyPerspectiveCameraHandle;
 /**
@@ -47,25 +47,10 @@ declare function createPolyOrthographicCamera(options?: PolyOrthographicCameraOp
 declare const createPolyCamera: typeof createPolyOrthographicCamera;
 
 /**
- * createPolyScene — imperative scene API. The vanilla counterpart to
- * `<PolyScene>` in React / Vue.
- *
- * Per §API freeze: takes a host element + scene options, returns a
- * `PolySceneHandle` whose `add(parseResult, transform?)` mounts a mesh under
- * the scene root and returns a removable `PolyMeshHandle`.
- *
- * Implementation:
- *   - Inserts a `<div class="polycss-scene">` into the host.
- *   - Each `add(...)` creates a `<div class="polycss-mesh">` with the
- *     mesh transform; mounts every valid polygon as an atlas-backed
- *     background sprite.
- *   - `destroy()` removes the scene element and disposes every mesh
- *     (which in turn disposes generated atlas blob URLs).
- *
- * The scene element is a 0×0 anchor at world (0,0,0) — pinned via
- * top:50%/left:50% so it sits at the visible center of the host. This
- * matches React/Vue's PolyScene anchor pattern. Polygons render around
- * the anchor via their own matrix3d translations.
+ * Public + internal types for the scene module, extracted from
+ * createPolyScene.ts so other scene/* helpers can import them without
+ * pulling in the whole factory body. createPolyScene.ts re-exports the
+ * public ones so the polycss package public surface is unchanged.
  */
 
 interface PolySceneOptions {
@@ -131,6 +116,15 @@ interface PolySceneOptions {
          */
         maxExtend?: number;
     };
+    /**
+     * When `true`, emit `data-poly-shadow-*` attribution attributes on every
+     * shadow SVG and path (type, receiver mesh id, receiver face index,
+     * member poly indices, caster ids, caster poly indices). Useful for
+     * DevTools inspection and per-poly attribution in debug benches. When
+     * `false` (default), these attributes are suppressed entirely — production
+     * scenes ship a cleaner DOM and avoid serializing per-frame JSON.
+     */
+    debugShadowAttrs?: boolean;
 }
 interface PolyMeshTransform {
     /** Stable identifier — exposed on the handle and reflected on the
@@ -193,8 +187,7 @@ interface PolyMeshHandle {
      *  the wrapper as `data-poly-mesh-id`. */
     readonly id?: string;
     /** Current transform snapshot (position / rotation / scale). Returned
-     *  by reference — treat as read-only and use `setTransform` to
-     *  mutate. */
+     *  by reference — treat as read-only and use `setTransform` to mutate. */
     readonly transform: PolyMeshTransform;
     /** Remove the mesh from the scene. */
     remove(): void;
@@ -265,6 +258,11 @@ interface PolySceneHandle {
      * FPV controls toggle `.polycss-fpv-host` on this element.
      */
     readonly cameraEl: HTMLElement;
+    /**
+     * The `.polycss-scene` root element inside `cameraEl`. Mesh wrappers, shadow
+     * roots, and helper DOM are mounted under this element.
+     */
+    readonly sceneElement: HTMLElement;
     /**
      * The camera handle this scene is bound to. Controls update camera state
      * via `scene.camera.update({...})` then call `scene.applyCamera()` to
@@ -290,10 +288,101 @@ interface PolySceneHandle {
      *  the element doesn't belong to this scene. */
     findMeshByElement(element: Element | null): PolyMeshHandle | null;
 }
-declare function createPolyScene(host: HTMLElement, options: PolySceneOptions): PolySceneHandle;
 
-declare const ELEMENT_BASE$a: typeof HTMLElement;
-declare class PolySceneElement extends ELEMENT_BASE$a {
+/**
+ * Shared types, constants, and utilities for orbit/map controls factories.
+ * Not part of the public API surface — use createPolyOrbitControls or
+ * createPolyMapControls.
+ */
+
+interface PolyControlsAnimateOptions {
+    /**
+     * Rotation rate in degrees per 60 Hz-equivalent frame. The tick is
+     * dt-clamped so 0.3 deg/frame ≈ 18 deg/sec on every refresh rate.
+     * Default: 0.3.
+     */
+    speed?: number;
+    /** Rotation axis. Default: "y" (yaw, rotates around vertical world Z). */
+    axis?: "x" | "y";
+    /** Halt the loop while a pointer drag is in progress. Default: true. */
+    pauseOnInteraction?: boolean;
+}
+interface PolyControlsBaseOptions {
+    /** Pointer-drag. Default: true. */
+    drag?: boolean;
+    /** Wheel / pinch zoom. Default: true. */
+    wheel?: boolean;
+    /**
+     * When `true`, wheel events change `distance` (camera pull-back in CSS px)
+     * instead of `zoom`. Mirrors Three.js OrbitControls dolly behaviour.
+     * Default: false (zoom mode).
+     */
+    dolly?: boolean;
+    /**
+     * Drag-direction inversion. `false` = natural, `true` = invert (×-1),
+     * a number multiplies sensitivity (negative inverts). Default: false.
+     */
+    invert?: boolean | number;
+    /** Minimum CSS zoom. Default: 0.1. */
+    minZoom?: number;
+    /** Maximum CSS zoom. Default: 10. */
+    maxZoom?: number;
+    /** Minimum dolly distance in CSS pixels. Default: 0. Only used when `dolly: true`. */
+    minDistance?: number;
+    /** Maximum dolly distance in CSS pixels. Default: Infinity. Only used when `dolly: true`. */
+    maxDistance?: number;
+    /** Auto-rotate. Pass false (or omit) to disable. */
+    animate?: false | PolyControlsAnimateOptions;
+}
+interface PolyControlsCamera {
+    rotX: number;
+    rotY: number;
+    zoom: number;
+    target: Vec3;
+    distance: number;
+}
+interface PolyControlsChangeEvent {
+    type: "change";
+    camera: PolyControlsCamera;
+}
+interface PolyControlsInteractionEvent {
+    type: "start" | "end";
+    camera: PolyControlsCamera;
+}
+type PolyControlsEvent = PolyControlsChangeEvent | PolyControlsInteractionEvent;
+type PolyControlsListener<E extends PolyControlsEvent = PolyControlsEvent> = (event: E) => void;
+interface PolyControlsHandle {
+    update(partial: PolyControlsBaseOptions): void;
+    resume(): void;
+    pause(): void;
+    destroy(): void;
+    addEventListener<T extends PolyControlsEvent["type"]>(type: T, listener: PolyControlsListener<Extract<PolyControlsEvent, {
+        type: T;
+    }>>): void;
+    removeEventListener<T extends PolyControlsEvent["type"]>(type: T, listener: PolyControlsListener<Extract<PolyControlsEvent, {
+        type: T;
+    }>>): void;
+    hasEventListener<T extends PolyControlsEvent["type"]>(type: T, listener: PolyControlsListener<Extract<PolyControlsEvent, {
+        type: T;
+    }>>): boolean;
+}
+
+/**
+ * createPolyOrbitControls — orbit-mode camera input for a PolyScene.
+ *
+ * Left-drag rotates rotX / rotY around the target (orbit). Wheel zooms or
+ * dollies. Mirrors Three.js OrbitControls semantics.
+ *
+ * For map/pan semantics (left-drag pans, right-drag orbits) use
+ * `createPolyMapControls` instead.
+ */
+
+type PolyOrbitControlsOptions = PolyControlsBaseOptions;
+type PolyOrbitControlsHandle = PolyControlsHandle;
+declare function createPolyOrbitControls(scene: PolySceneHandle, options?: PolyOrbitControlsOptions): PolyOrbitControlsHandle;
+
+declare const ELEMENT_BASE$b: typeof HTMLElement;
+declare class PolySceneElement extends ELEMENT_BASE$b {
     static get observedAttributes(): string[];
     private _scene;
     private _implicitCamera;
@@ -312,8 +401,8 @@ declare class PolySceneElement extends ELEMENT_BASE$a {
     attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
 }
 
-declare const ELEMENT_BASE$9: typeof HTMLElement;
-declare class PolyMeshElement extends ELEMENT_BASE$9 {
+declare const ELEMENT_BASE$a: typeof HTMLElement;
+declare class PolyMeshElement extends ELEMENT_BASE$a {
     static get observedAttributes(): string[];
     private _handle;
     private _parseResult;
@@ -327,6 +416,21 @@ declare class PolyMeshElement extends ELEMENT_BASE$9 {
     private _maybeLoad;
 }
 
+declare const ELEMENT_BASE$9: typeof HTMLElement;
+declare class PolyIframeElement extends ELEMENT_BASE$9 {
+    static get observedAttributes(): string[];
+    private _wrapper;
+    private _iframe;
+    /** The iframe element this <poly-iframe> mounted, or null when detached. */
+    getIframeElement(): HTMLIFrameElement | null;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+    private _mount;
+    private _applyGeometry;
+    private _teardown;
+}
+
 declare const ELEMENT_BASE$8: typeof HTMLElement;
 declare class PolyPolygonElement extends ELEMENT_BASE$8 {
     static get observedAttributes(): string[];
@@ -342,6 +446,11 @@ declare const ELEMENT_BASE$7: typeof HTMLElement;
 declare class PolyOrbitControlsElement extends ELEMENT_BASE$7 {
     static get observedAttributes(): string[];
     private _controls;
+    /** Returns the wrapped PolyOrbitControlsHandle once the element has
+     *  connected to its `<poly-scene>` ancestor. Lets external callers attach
+     *  `change` listeners (or call `update()` / `pause()`) the same way they
+     *  would on a vanilla `createPolyOrbitControls(scene, ...)` handle. */
+    getControls(): PolyOrbitControlsHandle | null;
     private _readAnimate;
     private _readOptions;
     private _findScene;
@@ -385,7 +494,7 @@ declare class PolyFirstPersonControlsElement extends ELEMENT_BASE$5 {
  * CSS `perspective` property set.
  *
  * Attributes (all optional):
- *   perspective   — number, CSS perspective in pixels (default 8000)
+ *   perspective   — number, CSS perspective in pixels (default 32000)
  *   zoom          — number
  *   rot-x         — number, degrees (default 65)
  *   rot-y         — number, degrees (default 45)
@@ -405,7 +514,7 @@ declare class PolyPerspectiveCameraElement extends ELEMENT_BASE$4 {
     private _teardown;
     connectedCallback(): void;
     disconnectedCallback(): void;
-    attributeChangedCallback(_name: string, oldValue: string | null, newValue: string | null): void;
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
 }
 
 /**
@@ -498,6 +607,7 @@ declare abstract class PolyShapeElement extends ELEMENT_BASE {
     abstract buildPolygons(): Polygon[];
     connectedCallback(): void;
     disconnectedCallback(): void;
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
     private _tearDown;
     private _mount;
 }
@@ -546,4 +656,4 @@ declare class PolyTorusElement extends PolyShapeElement {
     buildPolygons(): Polygon[];
 }
 
-export { PolySphereElement as A, PolyTetrahedronElement as B, PolyTorusElement as C, PolyTransformControlsElement as D, createPolyCamera as E, createPolyOrthographicCamera as F, createPolyPerspectiveCamera as G, createPolyScene as H, type PolySceneHandle as P, type PolyMeshHandle as a, PolyBoxElement as b, PolyCameraElement as c, type PolyCameraOptions as d, PolyConeElement as e, PolyCylinderElement as f, PolyDodecahedronElement as g, PolyFirstPersonControlsElement as h, PolyIcosahedronElement as i, PolyMapControlsElement as j, PolyMeshElement as k, type PolyMeshTransform as l, PolyOctahedronElement as m, PolyOrbitControlsElement as n, PolyOrthographicCameraElement as o, type PolyOrthographicCameraHandle as p, type PolyOrthographicCameraOptions as q, PolyPerspectiveCameraElement as r, type PolyPerspectiveCameraHandle as s, type PolyPerspectiveCameraOptions as t, PolyPlaneElement as u, PolyPolygonElement as v, PolyRingElement as w, PolySceneElement as x, type PolySceneOptions as y, PolySelectElement as z };
+export { PolyOrthographicCameraElement as A, type PolyOrthographicCameraHandle as B, type PolyOrthographicCameraOptions as C, PolyPerspectiveCameraElement as D, type PolyPerspectiveCameraHandle as E, type PolyPerspectiveCameraOptions as F, PolyPlaneElement as G, PolyPolygonElement as H, PolyRingElement as I, PolySceneElement as J, PolySelectElement as K, PolySphereElement as L, PolyTetrahedronElement as M, PolyTorusElement as N, PolyTransformControlsElement as O, type PolySceneOptions as P, createPolyCamera as Q, createPolyOrbitControls as R, createPolyOrthographicCamera as S, createPolyPerspectiveCamera as T, type PolySceneHandle as a, type PolyControlsHandle as b, type PolyControlsBaseOptions as c, type PolyControlsEvent as d, type PolyControlsListener as e, type PolyMeshHandle as f, PolyBoxElement as g, PolyCameraElement as h, type PolyCameraOptions as i, PolyConeElement as j, type PolyControlsAnimateOptions as k, type PolyControlsCamera as l, type PolyControlsChangeEvent as m, type PolyControlsInteractionEvent as n, PolyCylinderElement as o, PolyDodecahedronElement as p, PolyFirstPersonControlsElement as q, PolyIcosahedronElement as r, PolyIframeElement as s, PolyMapControlsElement as t, PolyMeshElement as u, type PolyMeshTransform as v, PolyOctahedronElement as w, PolyOrbitControlsElement as x, type PolyOrbitControlsHandle as y, type PolyOrbitControlsOptions as z };