@layoutit/polycss 0.0.1 → 0.2.0

package/README.md

@@ -95,7 +95,7 @@ poly-polygon.hover { filter: brightness(1.5); }
 | `ambient-intensity` | Ambient light intensity |
 | `ambient-color` | Ambient light color hex |
 | `texture-lighting` | `"baked"` or `"dynamic"` |
-| `atlas-scale` | Raster scale for generated atlas pages; lower values reduce memory/detail |
+| `atlas-scale` | Atlas bitmap budget and compositor sprite size; lower numeric values reduce memory/detail |
 
 For pointer drag, wheel zoom, and autorotate, drop a `<poly-orbit-controls>` child inside the scene (or wire `createPolyOrbitControls(scene, ...)` against the imperative API). For pan-first map-style input use `<poly-map-controls>` / `createPolyMapControls` instead. Mirrors Three.js's split between camera state (`<poly-scene>`) and camera input.
 
@@ -161,7 +161,7 @@ mesh.dispose();
 | `directionalLight` | `PolyDirectionalLight` | Directional light config |
 | `ambientLight` | `PolyAmbientLight` | Ambient light config |
 | `textureLighting` | `"baked" \| "dynamic"` | Texture lighting mode |
-| `atlasScale` | `number \| "auto"` | Raster scale for generated atlas pages |
+| `textureQuality` | `number \| "auto"` | Atlas bitmap budget and compositor sprite size |
 | `autoCenter` | `boolean` | Rotate around the union bbox center of added meshes |
 
 Returns a `PolySceneHandle`:
@@ -177,6 +177,7 @@ interface PolySceneHandle {
 **`loadMesh(url, options?)`**
 
 Fetches and parses a mesh by URL (dispatches by extension: `.obj`, `.glb`, `.gltf`, `.vox`). Returns `Promise<ParseResult>`.
+Mesh optimization defaults to `meshResolution: "lossy"`; pass `"lossless"` for exact planar candidates only.
 
 ## Subpath imports
 

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

@@ -1,6 +1,13 @@
 import { Polygon, Vec3, ParseResult, PolyDirectionalLight, PolyAmbientLight, PolyTextureLightingMode, CameraHandle } from '@layoutit/polycss-core';
 
-type AtlasScale = number | "auto";
+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[];
+}
 
 /**
  * createPolyScene — imperative scene API. The vanilla counterpart to
@@ -50,8 +57,17 @@ interface PolySceneOptions {
     ambientLight?: PolyAmbientLight;
     /** Textured polygon lighting mode. Defaults to "baked". */
     textureLighting?: PolyTextureLightingMode;
-    /** Raster scale for generated atlas pages. `"auto"` reduces large atlases. */
-    atlasScale?: AtlasScale;
+    /** Atlas bitmap budget and CSS sprite size. `"auto"` uses a
+     *  device-appropriate memory budget (~4 MB mobile / ~16 MB desktop) and
+     *  desktop/mobile sprite sizing. Numeric values 0.1..1 force an explicit
+     *  raster scale and the 64px sprite. */
+    textureQuality?: TextureQuality;
+    /**
+     * 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).
+     * `<s>` is the universal fallback and cannot be disabled.
+     */
+    strategies?: PolyRenderStrategiesOption;
     /**
      * When `true`, rotation pivots around the union bbox of all added meshes
      * instead of world (0,0,0). The scene wraps polygons in an inner div
@@ -59,6 +75,24 @@ interface PolySceneOptions {
      * or `setOptions` is called. Mirrors React's `<PolyScene autoCenter>`.
      */
     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?: {
+        /** Shadow color as a CSS hex string. Default: `"#000000"`. */
+        color?: string;
+        /** Shadow opacity 0..1. Default: `0.25`. */
+        opacity?: number;
+        /**
+         * Raises the shadow plane slightly above the model bbox floor along
+         * +Z (Z up) so it sits on top of a receiver mesh placed at the bbox
+         * bottom, rather than below it where the receiver would occlude the
+         * shadow. In world units. Default: `0.05`.
+         */
+        lift?: number;
+    };
 }
 interface PolyMeshTransform {
     /** Stable identifier — exposed on the handle and reflected on the
@@ -85,6 +119,15 @@ interface PolyMeshTransform {
      * shift the camera target when toggled. Defaults to `false`.
      */
     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`.
+     */
+    castShadow?: boolean;
 }
 interface PolyMeshHandle {
     /** The polygons that were loaded after normalization and automatic merge. */
@@ -109,6 +152,15 @@ interface PolyMeshHandle {
         stableDom?: boolean;
         recomputeAutoCenter?: boolean;
     }): void;
+    /**
+     * Update a single polygon in place. `target` is either a polygon
+     * reference (as returned by `getPolygons()`) or its index. `partial`
+     * fields are merged onto the polygon; the mesh is then re-rendered.
+     * Skips the merge pass, so this is cheaper than `setPolygons` for
+     * targeted edits like color picker updates from an inspector UI.
+     * Silently no-ops if `target` isn't found.
+     */
+    updatePolygon(target: Polygon | number, partial: Partial<Polygon>): void;
     /** Update transform without re-parsing. */
     setTransform(t: Partial<PolyMeshTransform>): void;
     /** Revoke any blob URLs the parse created. Idempotent. */
@@ -156,10 +208,10 @@ interface PolySceneHandle {
     readonly host: HTMLElement;
     /**
      * Snapshot of the current options (camera, lighting, merge, autoCenter,
-     * textureLighting, atlasScale, 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.
+     * 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.
      */
     getOptions(): Readonly<PolySceneOptions>;
     /** Snapshot of mesh handles currently in the scene (insertion order).
@@ -364,4 +416,4 @@ declare class PolySelectElement extends ELEMENT_BASE {
     attributeChangedCallback(_name: string, oldValue: string | null, newValue: string | null): void;
 }
 
-export { type PolySceneHandle as P, 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, PolySceneElement as n, type PolySceneOptions as o, PolySelectElement as p, PolyTransformControlsElement as q, createPolyOrthographicCamera as r, createPolyPerspectiveCamera as s, createPolyScene as t };
+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 };

package/dist/{PolySelectElement-DCuYJb5J.d.ts → PolySelectElement-Tvsmhx2m.d.ts}

@@ -1,6 +1,13 @@
 import { Polygon, Vec3, ParseResult, PolyDirectionalLight, PolyAmbientLight, PolyTextureLightingMode, CameraHandle } from '@layoutit/polycss-core';
 
-type AtlasScale = number | "auto";
+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[];
+}
 
 /**
  * createPolyScene — imperative scene API. The vanilla counterpart to
@@ -50,8 +57,17 @@ interface PolySceneOptions {
     ambientLight?: PolyAmbientLight;
     /** Textured polygon lighting mode. Defaults to "baked". */
     textureLighting?: PolyTextureLightingMode;
-    /** Raster scale for generated atlas pages. `"auto"` reduces large atlases. */
-    atlasScale?: AtlasScale;
+    /** Atlas bitmap budget and CSS sprite size. `"auto"` uses a
+     *  device-appropriate memory budget (~4 MB mobile / ~16 MB desktop) and
+     *  desktop/mobile sprite sizing. Numeric values 0.1..1 force an explicit
+     *  raster scale and the 64px sprite. */
+    textureQuality?: TextureQuality;
+    /**
+     * 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).
+     * `<s>` is the universal fallback and cannot be disabled.
+     */
+    strategies?: PolyRenderStrategiesOption;
     /**
      * When `true`, rotation pivots around the union bbox of all added meshes
      * instead of world (0,0,0). The scene wraps polygons in an inner div
@@ -59,6 +75,24 @@ interface PolySceneOptions {
      * or `setOptions` is called. Mirrors React's `<PolyScene autoCenter>`.
      */
     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?: {
+        /** Shadow color as a CSS hex string. Default: `"#000000"`. */
+        color?: string;
+        /** Shadow opacity 0..1. Default: `0.25`. */
+        opacity?: number;
+        /**
+         * Raises the shadow plane slightly above the model bbox floor along
+         * +Z (Z up) so it sits on top of a receiver mesh placed at the bbox
+         * bottom, rather than below it where the receiver would occlude the
+         * shadow. In world units. Default: `0.05`.
+         */
+        lift?: number;
+    };
 }
 interface PolyMeshTransform {
     /** Stable identifier — exposed on the handle and reflected on the
@@ -85,6 +119,15 @@ interface PolyMeshTransform {
      * shift the camera target when toggled. Defaults to `false`.
      */
     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`.
+     */
+    castShadow?: boolean;
 }
 interface PolyMeshHandle {
     /** The polygons that were loaded after normalization and automatic merge. */
@@ -109,6 +152,15 @@ interface PolyMeshHandle {
         stableDom?: boolean;
         recomputeAutoCenter?: boolean;
     }): void;
+    /**
+     * Update a single polygon in place. `target` is either a polygon
+     * reference (as returned by `getPolygons()`) or its index. `partial`
+     * fields are merged onto the polygon; the mesh is then re-rendered.
+     * Skips the merge pass, so this is cheaper than `setPolygons` for
+     * targeted edits like color picker updates from an inspector UI.
+     * Silently no-ops if `target` isn't found.
+     */
+    updatePolygon(target: Polygon | number, partial: Partial<Polygon>): void;
     /** Update transform without re-parsing. */
     setTransform(t: Partial<PolyMeshTransform>): void;
     /** Revoke any blob URLs the parse created. Idempotent. */
@@ -156,10 +208,10 @@ interface PolySceneHandle {
     readonly host: HTMLElement;
     /**
      * Snapshot of the current options (camera, lighting, merge, autoCenter,
-     * textureLighting, atlasScale, 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.
+     * 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.
      */
     getOptions(): Readonly<PolySceneOptions>;
     /** Snapshot of mesh handles currently in the scene (insertion order).
@@ -364,4 +416,4 @@ declare class PolySelectElement extends ELEMENT_BASE {
     attributeChangedCallback(_name: string, oldValue: string | null, newValue: string | null): void;
 }
 
-export { type PolySceneHandle as P, 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, PolySceneElement as n, type PolySceneOptions as o, PolySelectElement as p, PolyTransformControlsElement as q, createPolyOrthographicCamera as r, createPolyPerspectiveCamera as s, createPolyScene as t };
+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 };