@layoutit/polycss 0.2.0 → 0.2.1

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

@@ -1,13 +1,50 @@
-import { Polygon, Vec3, ParseResult, PolyDirectionalLight, PolyAmbientLight, PolyTextureLightingMode, CameraHandle } from '@layoutit/polycss-core';
+import { CameraHandle, Vec3, Polygon, MeshResolution, ParseResult, PolyDirectionalLight, PolyAmbientLight, PolyTextureLightingMode, TextureQuality, PolySeamBleed, PolyRenderStrategiesOption } from '@layoutit/polycss-core';
 
-type TextureQuality = number | "auto";
-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[];
+interface PolyCameraOptions {
+    zoom?: number;
+    target?: Vec3;
+    rotX?: number;
+    rotY?: number;
+    /** Camera pull-back in CSS pixels (dolly). Default 0. */
+    distance?: number;
+}
+interface PolyPerspectiveCameraOptions extends PolyCameraOptions {
+    /** CSS perspective distance in pixels. Default 8000. */
+    perspective?: number;
 }
+interface PolyOrthographicCameraOptions extends PolyCameraOptions {
+}
+/** Extends CameraHandle with projection info for the container element. */
+interface PolyPerspectiveCameraHandle extends CameraHandle {
+    readonly type: "perspective";
+    /** CSS `perspective` value to set on the camera container element. */
+    readonly perspectiveStyle: string;
+}
+interface PolyOrthographicCameraHandle extends CameraHandle {
+    readonly type: "orthographic";
+    /** CSS `perspective` value to set on the camera container element ("none"). */
+    readonly perspectiveStyle: "none";
+}
+/**
+ * Creates a perspective camera handle. The `perspectiveStyle` property
+ * returns the CSS value to apply to the camera container's `perspective`
+ * property (default `"8000px"`).
+ */
+declare function createPolyPerspectiveCamera(options?: PolyPerspectiveCameraOptions): PolyPerspectiveCameraHandle;
+/**
+ * Creates an orthographic camera handle. The `perspectiveStyle` property
+ * returns `"none"` — pass it to the container element's CSS `perspective`
+ * to disable perspective projection.
+ */
+declare function createPolyOrthographicCamera(options?: PolyOrthographicCameraOptions): PolyOrthographicCameraHandle;
+/**
+ * Ergonomic alias for `createPolyOrthographicCamera`. The default camera in
+ * PolyCSS is orthographic because the engine's structural advantages
+ * (integer-pixel atlas slicing, DOM-as-render-tree) are most visible in
+ * iso/voxel/diagrammatic scenes. Use `createPolyPerspectiveCamera` explicitly
+ * when depth foreshortening is needed.
+ */
+declare const createPolyCamera: typeof createPolyOrthographicCamera;
 
 /**
  * createPolyScene — imperative scene API. The vanilla counterpart to
@@ -32,27 +69,12 @@ interface PolyRenderStrategiesOption {
  */
 
 interface PolySceneOptions {
-    perspective?: number | false;
-    rotX?: number;
-    rotY?: number;
-    zoom?: number;
     /**
-     * Camera pull-back distance in CSS pixels. Increasing distance moves the
-     * camera farther from the target (scene appears smaller), applied as an
-     * outermost `translateZ(-distance)` in the scene transform. Matches the
-     * `distance` field in core's `CameraState`. Default: 0 (no dolly offset).
+     * Camera handle created by `createPolyCamera`, `createPolyOrthographicCamera`,
+     * or `createPolyPerspectiveCamera`. Required — `createPolyScene` will throw if
+     * this field is missing.
      */
-    distance?: number;
-    /**
-     * World-coordinate camera target — the world point that appears at the
-     * viewport centre. Matches React's `CameraState.target`. Defaults to
-     * `[0, 0, 0]` so existing scenes that don't set it keep working.
-     *
-     * Internally encoded as the innermost translate in the scene transform:
-     * `scale(zoom) rotateX(rotX) rotate(rotY) translate3d(-ty*tile, -tx*tile, -tz*tile)`
-     * (world→CSS axis swap: world-X→CSS-Y, world-Y→CSS-X, world-Z→CSS-Z).
-     */
-    target?: Vec3;
+    camera: PolyPerspectiveCameraHandle | PolyOrthographicCameraHandle;
     directionalLight?: PolyDirectionalLight;
     ambientLight?: PolyAmbientLight;
     /** Textured polygon lighting mode. Defaults to "baked". */
@@ -62,6 +84,8 @@ interface PolySceneOptions {
      *  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;
     /**
      * Skip specific render-strategy tags. Polygons that would normally use a
      * disabled tag fall through the chain (b → i → s, u → i → s, i → s).
@@ -76,9 +100,11 @@ interface PolySceneOptions {
      */
     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 — dynamic mode projects via CSS vars so shadows
+     * follow a moving light, baked mode CPU-bakes the projection into
+     * each leaf's inline `matrix3d` and drops back-facing polys from the
+     * DOM entirely. Defaults: `{ color: "#000000", opacity: 0.25, lift: 0.05, maxExtend: 2000 }`.
      */
     shadow?: {
         /** Shadow color as a CSS hex string. Default: `"#000000"`. */
@@ -92,6 +118,18 @@ interface PolySceneOptions {
          * shadow. In world units. Default: `0.05`.
          */
         lift?: number;
+        /**
+         * Maximum CSS pixels the shadow may extend beyond the mesh's
+         * footprint (the no-shear silhouette directly under the mesh). The
+         * footprint area is always preserved; only the sheared tail at low
+         * light elevations is truncated. Default: `2000`.
+         *
+         * **Trade-off:** larger values give longer shadows but the SVG
+         * backing store grows quadratically with this value, which can
+         * cause repaint flicker at extreme low-elevation angles. Pass a
+         * very large number (e.g. `Infinity`) to disable the cap entirely.
+         */
+        maxExtend?: number;
     };
 }
 interface PolyMeshTransform {
@@ -108,6 +146,12 @@ interface PolyMeshTransform {
      * triangle topology must remain stable from frame to frame.
      */
     merge?: boolean;
+    /**
+     * Mesh optimization intent. Defaults to `"lossy"` (bounded geometric
+     * approximation when it reduces polygon count). Set `"lossless"` to preserve
+     * the authored surface — only exact coplanar merges are applied.
+     */
+    meshResolution?: MeshResolution;
     /**
      * Keep polygon leaf DOM nodes stable across setPolygons() calls when the
      * mesh topology is unchanged. Intended for animated/deforming meshes.
@@ -120,14 +164,22 @@ interface PolyMeshTransform {
      */
     excludeFromAutoCenter?: boolean;
     /**
-     * When `true` and the scene is in dynamic lighting mode, the renderer emits
-     * a flat shadow leaf sibling for each non-textured polygon. The shadow is
-     * projected onto the ground plane (min world-Y of all casting meshes) along
-     * the CSS-space light direction (driven by `--clx/--cly/--clz` vars). Zero
-     * JS in the render loop — the projection matrix is a CSS var that recomputes
-     * via `calc()` when the light vars change. Defaults to `false`.
+     * When `true`, this mesh casts a shadow onto the scene's shadow ground
+     * plane (and onto any meshes marked `receiveShadow: true`). The shadow
+     * emits as one per-mesh `<svg>` whose path is the union of every
+     * casting polygon's projection. Works in both lighting modes.
+     * Defaults to `false`.
      */
     castShadow?: boolean;
+    /**
+     * **(experimental)** When `true`, this mesh acts as a shadow receiver:
+     * each of its polygon faces becomes a target plane that casting meshes'
+     * shadows project onto and get clipped to. Useful for "shadow on table"
+     * scenarios. Currently only convex face outlines clip cleanly. When no
+     * receivers are present the global ground plane is used as today.
+     * Defaults to `false`.
+     */
+    receiveShadow?: boolean;
 }
 interface PolyMeshHandle {
     /** The polygons that were loaded after normalization and automatic merge. */
@@ -196,8 +248,8 @@ interface PolyMeshHandle {
 interface PolySceneHandle {
     /** Add a mesh to the scene. Returns a handle for later removal. */
     add(mesh: ParseResult, opts?: PolyMeshTransform): PolyMeshHandle;
-    /** Update scene-level config (rotation, lighting, etc.). */
-    setOptions(partial: Partial<PolySceneOptions>): void;
+    /** Update scene-level config (lighting, autoCenter, strategies, etc.). Camera state is on `scene.camera`. */
+    setOptions(partial: Partial<Omit<PolySceneOptions, "camera">>): void;
     /** Tear down the scene; revokes all blob URLs of registered meshes. */
     destroy(): void;
     /**
@@ -207,13 +259,30 @@ interface PolySceneHandle {
      */
     readonly host: HTMLElement;
     /**
-     * Snapshot of the current options (camera, lighting, merge, autoCenter,
-     * textureLighting, textureQuality, and perspective). Returned by reference,
-     * so callers must treat it as read-only —
-     * mutations won't propagate. Used by helpers that need to read the current
-     * camera state without duplicating it.
+     * The `.polycss-camera` wrapper element created by `createPolyScene` between
+     * the host and the `.polycss-scene` element. Carries the CSS `perspective`
+     * that matches React/Vue's `<div class="polycss-camera">` wrapper shape.
+     * FPV controls toggle `.polycss-fpv-host` on this element.
+     */
+    readonly cameraEl: HTMLElement;
+    /**
+     * The camera handle this scene is bound to. Controls update camera state
+     * via `scene.camera.update({...})` then call `scene.applyCamera()` to
+     * re-apply the transform.
      */
-    getOptions(): Readonly<PolySceneOptions>;
+    readonly camera: PolyPerspectiveCameraHandle | PolyOrthographicCameraHandle;
+    /**
+     * Re-applies the scene transform from the current camera state. Call this
+     * after mutating `scene.camera.update({...})` to make the change visible.
+     * Controls call this once per interaction event after updating camera state.
+     */
+    applyCamera(): void;
+    /**
+     * Snapshot of the current non-camera scene options (lighting, autoCenter,
+     * textureQuality, strategies, shadow). Returned by reference — treat as
+     * read-only; use `setOptions` to update.
+     */
+    getOptions(): Readonly<Omit<PolySceneOptions, "camera">>;
     /** Snapshot of mesh handles currently in the scene (insertion order).
      *  Used by selection helpers to enumerate hit-test candidates. */
     meshes(): readonly PolyMeshHandle[];
@@ -221,65 +290,30 @@ interface PolySceneHandle {
      *  the element doesn't belong to this scene. */
     findMeshByElement(element: Element | null): PolyMeshHandle | null;
 }
-declare function createPolyScene(host: HTMLElement, options?: PolySceneOptions): PolySceneHandle;
-
-interface PolyCameraOptions {
-    zoom?: number;
-    target?: Vec3;
-    rotX?: number;
-    rotY?: number;
-    /** Camera pull-back in CSS pixels (dolly). Default 0. */
-    distance?: number;
-}
-interface PolyPerspectiveCameraOptions extends PolyCameraOptions {
-    /** CSS perspective distance in pixels. Default 8000. */
-    perspective?: number;
-}
-interface PolyOrthographicCameraOptions extends PolyCameraOptions {
-}
-/** Extends CameraHandle with projection info for the container element. */
-interface PolyPerspectiveCameraHandle extends CameraHandle {
-    readonly type: "perspective";
-    /** CSS `perspective` value to set on the camera container element. */
-    readonly perspectiveStyle: string;
-}
-interface PolyOrthographicCameraHandle extends CameraHandle {
-    readonly type: "orthographic";
-    /** CSS `perspective` value to set on the camera container element ("none"). */
-    readonly perspectiveStyle: "none";
-}
-/**
- * Creates a perspective camera handle. The `perspectiveStyle` property
- * returns the CSS value to apply to the camera container's `perspective`
- * property (default `"8000px"`).
- */
-declare function createPolyPerspectiveCamera(options?: PolyPerspectiveCameraOptions): PolyPerspectiveCameraHandle;
-/**
- * Creates an orthographic camera handle. The `perspectiveStyle` property
- * returns `"none"` — pass it to the container element's CSS `perspective`
- * to disable perspective projection.
- */
-declare function createPolyOrthographicCamera(options?: PolyOrthographicCameraOptions): PolyOrthographicCameraHandle;
+declare function createPolyScene(host: HTMLElement, options: PolySceneOptions): PolySceneHandle;
 
-declare const ELEMENT_BASE$8: typeof HTMLElement;
-declare class PolySceneElement extends ELEMENT_BASE$8 {
+declare const ELEMENT_BASE$a: typeof HTMLElement;
+declare class PolySceneElement extends ELEMENT_BASE$a {
     static get observedAttributes(): string[];
     private _scene;
+    private _implicitCamera;
     /**
      * Returns the underlying PolySceneHandle. Children call this during their own
      * connectedCallback to register meshes.
      */
     getScene(): PolySceneHandle | null;
-    private _readOptions;
+    private _findAncestorCamera;
+    private _buildImplicitCamera;
+    private _readNonCameraOptions;
     private _readDirectionalLight;
     private _readAmbientLight;
     connectedCallback(): void;
     disconnectedCallback(): void;
-    attributeChangedCallback(_name: string, oldValue: string | null, newValue: string | null): void;
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
 }
 
-declare const ELEMENT_BASE$7: typeof HTMLElement;
-declare class PolyMeshElement extends ELEMENT_BASE$7 {
+declare const ELEMENT_BASE$9: typeof HTMLElement;
+declare class PolyMeshElement extends ELEMENT_BASE$9 {
     static get observedAttributes(): string[];
     private _handle;
     private _parseResult;
@@ -293,8 +327,8 @@ declare class PolyMeshElement extends ELEMENT_BASE$7 {
     private _maybeLoad;
 }
 
-declare const ELEMENT_BASE$6: typeof HTMLElement;
-declare class PolyPolygonElement extends ELEMENT_BASE$6 {
+declare const ELEMENT_BASE$8: typeof HTMLElement;
+declare class PolyPolygonElement extends ELEMENT_BASE$8 {
     static get observedAttributes(): string[];
     private _handle;
     connectedCallback(): void;
@@ -304,8 +338,8 @@ declare class PolyPolygonElement extends ELEMENT_BASE$6 {
     private _mount;
 }
 
-declare const ELEMENT_BASE$5: typeof HTMLElement;
-declare class PolyOrbitControlsElement extends ELEMENT_BASE$5 {
+declare const ELEMENT_BASE$7: typeof HTMLElement;
+declare class PolyOrbitControlsElement extends ELEMENT_BASE$7 {
     static get observedAttributes(): string[];
     private _controls;
     private _readAnimate;
@@ -317,8 +351,8 @@ declare class PolyOrbitControlsElement extends ELEMENT_BASE$5 {
     attributeChangedCallback(_name: string, oldValue: string | null, newValue: string | null): void;
 }
 
-declare const ELEMENT_BASE$4: typeof HTMLElement;
-declare class PolyMapControlsElement extends ELEMENT_BASE$4 {
+declare const ELEMENT_BASE$6: typeof HTMLElement;
+declare class PolyMapControlsElement extends ELEMENT_BASE$6 {
     static get observedAttributes(): string[];
     private _controls;
     private _readAnimate;
@@ -330,6 +364,18 @@ declare class PolyMapControlsElement extends ELEMENT_BASE$4 {
     attributeChangedCallback(_name: string, oldValue: string | null, newValue: string | null): void;
 }
 
+declare const ELEMENT_BASE$5: typeof HTMLElement;
+declare class PolyFirstPersonControlsElement extends ELEMENT_BASE$5 {
+    static get observedAttributes(): string[];
+    private _controls;
+    private _readOptions;
+    private _findScene;
+    private _attach;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(_name: string, oldValue: string | null, newValue: string | null): void;
+}
+
 /**
  * <poly-perspective-camera> — standalone perspective camera element.
  *
@@ -347,8 +393,8 @@ declare class PolyMapControlsElement extends ELEMENT_BASE$4 {
  *   distance      — number, camera pull-back in CSS pixels
  */
 
-declare const ELEMENT_BASE$3: typeof HTMLElement;
-declare class PolyPerspectiveCameraElement extends ELEMENT_BASE$3 {
+declare const ELEMENT_BASE$4: typeof HTMLElement;
+declare class PolyPerspectiveCameraElement extends ELEMENT_BASE$4 {
     static get observedAttributes(): string[];
     private _camera;
     private _wrapper;
@@ -376,8 +422,8 @@ declare class PolyPerspectiveCameraElement extends ELEMENT_BASE$3 {
  *   distance      — number, camera pull-back in CSS pixels
  */
 
-declare const ELEMENT_BASE$2: typeof HTMLElement;
-declare class PolyOrthographicCameraElement extends ELEMENT_BASE$2 {
+declare const ELEMENT_BASE$3: typeof HTMLElement;
+declare class PolyOrthographicCameraElement extends ELEMENT_BASE$3 {
     static get observedAttributes(): string[];
     private _camera;
     private _wrapper;
@@ -391,8 +437,21 @@ declare class PolyOrthographicCameraElement extends ELEMENT_BASE$2 {
     attributeChangedCallback(_name: string, oldValue: string | null, newValue: string | null): void;
 }
 
-declare const ELEMENT_BASE$1: typeof HTMLElement;
-declare class PolyTransformControlsElement extends ELEMENT_BASE$1 {
+/**
+ * <poly-camera> — ergonomic alias for <poly-orthographic-camera>.
+ *
+ * The default camera in PolyCSS is orthographic. `<poly-camera>` maps to
+ * `PolyOrthographicCameraElement` so the canonical tree shape works without
+ * spelling out "orthographic" when it isn't relevant to the scene being built.
+ *
+ * Use <poly-perspective-camera> when depth foreshortening is needed.
+ */
+
+declare class PolyCameraElement extends PolyOrthographicCameraElement {
+}
+
+declare const ELEMENT_BASE$2: typeof HTMLElement;
+declare class PolyTransformControlsElement extends ELEMENT_BASE$2 {
     static get observedAttributes(): string[];
     private _tc;
     private _findScene;
@@ -404,8 +463,8 @@ declare class PolyTransformControlsElement extends ELEMENT_BASE$1 {
     attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
 }
 
-declare const ELEMENT_BASE: typeof HTMLElement;
-declare class PolySelectElement extends ELEMENT_BASE {
+declare const ELEMENT_BASE$1: typeof HTMLElement;
+declare class PolySelectElement extends ELEMENT_BASE$1 {
     static get observedAttributes(): string[];
     private _selection;
     private _findScene;
@@ -416,4 +475,75 @@ declare class PolySelectElement extends ELEMENT_BASE {
     attributeChangedCallback(_name: string, oldValue: string | null, newValue: string | null): void;
 }
 
-export { type PolySceneHandle as P, type TextureQuality as T, type PolyMeshHandle as a, type PolyCameraOptions as b, PolyMapControlsElement as c, PolyMeshElement as d, type PolyMeshTransform as e, PolyOrbitControlsElement as f, PolyOrthographicCameraElement as g, type PolyOrthographicCameraHandle as h, type PolyOrthographicCameraOptions as i, PolyPerspectiveCameraElement as j, type PolyPerspectiveCameraHandle as k, type PolyPerspectiveCameraOptions as l, PolyPolygonElement as m, type PolyRenderStrategiesOption as n, type PolyRenderStrategy as o, PolySceneElement as p, type PolySceneOptions as q, PolySelectElement as r, PolyTransformControlsElement as s, createPolyOrthographicCamera as t, createPolyPerspectiveCamera as u, createPolyScene as v };
+/**
+ * Primitive shape custom elements — <poly-box>, <poly-plane>, <poly-ring>,
+ * <poly-octahedron>, <poly-tetrahedron>, <poly-icosahedron>, <poly-dodecahedron>,
+ * <poly-cylinder>, <poly-cone>, <poly-torus>.
+ *
+ * Each element reads shape-specific attributes, calls the matching polygon
+ * generator from @layoutit/polycss-core, then registers the result with the
+ * nearest <poly-scene> ancestor using the same mechanism as <poly-mesh>.
+ *
+ * Attribute naming follows kebab-case conventions: `radial-segments`,
+ * `tubular-segments`, `radius-top`, `half-thickness`, etc.
+ */
+
+declare const ELEMENT_BASE: typeof HTMLElement;
+/**
+ * Base class for all primitive shape elements. Subclasses implement
+ * `buildPolygons()` which returns a Polygon[] from this element's attributes.
+ */
+declare abstract class PolyShapeElement extends ELEMENT_BASE {
+    private _handle;
+    abstract buildPolygons(): Polygon[];
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private _tearDown;
+    private _mount;
+}
+declare class PolyBoxElement extends PolyShapeElement {
+    static get observedAttributes(): string[];
+    buildPolygons(): Polygon[];
+}
+declare class PolyPlaneElement extends PolyShapeElement {
+    static get observedAttributes(): string[];
+    buildPolygons(): Polygon[];
+}
+declare class PolyRingElement extends PolyShapeElement {
+    static get observedAttributes(): string[];
+    buildPolygons(): Polygon[];
+}
+declare class PolyOctahedronElement extends PolyShapeElement {
+    static get observedAttributes(): string[];
+    buildPolygons(): Polygon[];
+}
+declare class PolyTetrahedronElement extends PolyShapeElement {
+    static get observedAttributes(): string[];
+    buildPolygons(): Polygon[];
+}
+declare class PolyIcosahedronElement extends PolyShapeElement {
+    static get observedAttributes(): string[];
+    buildPolygons(): Polygon[];
+}
+declare class PolyDodecahedronElement extends PolyShapeElement {
+    static get observedAttributes(): string[];
+    buildPolygons(): Polygon[];
+}
+declare class PolySphereElement extends PolyShapeElement {
+    static get observedAttributes(): string[];
+    buildPolygons(): Polygon[];
+}
+declare class PolyCylinderElement extends PolyShapeElement {
+    static get observedAttributes(): string[];
+    buildPolygons(): Polygon[];
+}
+declare class PolyConeElement extends PolyShapeElement {
+    static get observedAttributes(): string[];
+    buildPolygons(): Polygon[];
+}
+declare class PolyTorusElement extends PolyShapeElement {
+    static get observedAttributes(): string[];
+    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 };