@layoutit/polycss 0.2.0 → 0.2.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@layoutit/polycss",
-  "version": "0.2.0",
-  "description": "Polycss vanilla / custom-elements + imperative API. Renders OBJ / glTF / GLB mesh polygons as DOM via CSS matrix3d.",
+  "version": "0.2.2",
+  "description": "PolyCSS vanilla / custom-elements + imperative API. Renders OBJ / STL / glTF / GLB mesh polygons as DOM via CSS matrix3d.",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
@@ -47,7 +47,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@layoutit/polycss-core": "^0.2.0"
+    "@layoutit/polycss-core": "^0.2.2"
   },
   "devDependencies": {
     "tsup": "^8.0.1",

package/dist/PolySelectElement-Tvsmhx2m.d.cts

@@ -1,419 +0,0 @@
-import { Polygon, Vec3, ParseResult, PolyDirectionalLight, PolyAmbientLight, PolyTextureLightingMode, CameraHandle } 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[];
-}
-
-/**
- * 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.
- */
-
-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).
-     */
-    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;
-    directionalLight?: PolyDirectionalLight;
-    ambientLight?: PolyAmbientLight;
-    /** Textured polygon lighting mode. Defaults to "baked". */
-    textureLighting?: PolyTextureLightingMode;
-    /** 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
-     * translated by `-bboxCenter`. Updates whenever a mesh is added/removed
-     * 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
-     *  wrapper as `data-poly-mesh-id`. Used by selection helpers to
-     *  resolve clicks back to the mesh and to dedupe selection state. */
-    id?: string;
-    position?: Vec3;
-    scale?: number | Vec3;
-    rotation?: Vec3;
-    /**
-     * Whether `scene.add()` should merge coplanar polygons before rendering.
-     * Defaults to `true`. Set `false` for animated/deforming meshes whose
-     * triangle topology must remain stable from frame to frame.
-     */
-    merge?: boolean;
-    /**
-     * Keep polygon leaf DOM nodes stable across setPolygons() calls when the
-     * mesh topology is unchanged. Intended for animated/deforming meshes.
-     */
-    stableDom?: boolean;
-    /**
-     * When `true`, this mesh's polygons are NOT included in the scene's
-     * auto-center bbox. Use for debug overlays / helpers that shouldn't
-     * 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. */
-    polygons: Polygon[];
-    /** The `.polycss-mesh` wrapper div for this mesh. Exposed so layered
-     *  helpers (selection, transform controls) can resolve a click target
-     *  back to its owning mesh, attach event listeners, or measure the
-     *  mesh's screen position via `getBoundingClientRect`. */
-    readonly element: HTMLElement;
-    /** Identifier passed via `PolyMeshTransform.id` (if any). Reflected on
-     *  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. */
-    readonly transform: PolyMeshTransform;
-    /** Remove the mesh from the scene. */
-    remove(): void;
-    /** Replace polygon geometry without tearing down the scene or controls. */
-    setPolygons(polygons: Polygon[], options?: {
-        merge?: boolean;
-        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. */
-    dispose(): void;
-    /**
-     * Re-rasterize the atlas using the directional light inverse-rotated into
-     * the mesh's local frame. Call this after a mesh rotation has been
-     * committed (e.g., on pointer release in rotate-mode transform controls) to
-     * correct stale baked shading.
-     *
-     * **Background:** Baked atlas tiles encode `baseColor × Lambert(worldNormal,
-     * worldLight)`. When the mesh wrapper rotates via CSS, the polygon's normal
-     * in world space changes but the baked color doesn't — faces stay lit/unlit
-     * incorrectly. `rebakeAtlas()` inverse-rotates the world light into the
-     * mesh's local frame and re-runs the rasterizer; because
-     * `dot(localNormal, localLight) === dot(worldNormal, worldLight)` the
-     * output is correct for any rotation.
-     *
-     * **Performance note:** This does NOT run on every `setTransform` call —
-     * only when explicitly invoked, so dragging remains smooth. Call it on
-     * pointer release (or any point where you want to commit the new shading).
-     */
-    rebakeAtlas(): void;
-    /** Current `position` from the transform (matches framework API). */
-    getPosition(): Vec3 | undefined;
-    /** Current `rotation` from the transform (matches framework API). */
-    getRotation(): Vec3 | undefined;
-    /** Current `scale` from the transform (matches framework API). */
-    getScale(): number | Vec3 | undefined;
-    /** Polygons currently being rendered (matches framework API). */
-    getPolygons(): Polygon[];
-}
-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;
-    /** Tear down the scene; revokes all blob URLs of registered meshes. */
-    destroy(): void;
-    /**
-     * The host element passed to `createPolyScene`. Exposed for layered
-     * helpers like `createPolyOrbitControls` that need to attach event listeners
-     * without tracking the host separately.
-     */
-    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.
-     */
-    getOptions(): Readonly<PolySceneOptions>;
-    /** Snapshot of mesh handles currently in the scene (insertion order).
-     *  Used by selection helpers to enumerate hit-test candidates. */
-    meshes(): readonly PolyMeshHandle[];
-    /** Resolve a `.polycss-mesh` element back to its handle, or `null` if
-     *  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 const ELEMENT_BASE$8: typeof HTMLElement;
-declare class PolySceneElement extends ELEMENT_BASE$8 {
-    static get observedAttributes(): string[];
-    private _scene;
-    /**
-     * Returns the underlying PolySceneHandle. Children call this during their own
-     * connectedCallback to register meshes.
-     */
-    getScene(): PolySceneHandle | null;
-    private _readOptions;
-    private _readDirectionalLight;
-    private _readAmbientLight;
-    connectedCallback(): void;
-    disconnectedCallback(): 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 {
-    static get observedAttributes(): string[];
-    private _handle;
-    private _parseResult;
-    private _loadToken;
-    /** Returns the current mesh handle, or null if not yet loaded. */
-    getMeshHandle(): PolyMeshHandle | null;
-    connectedCallback(): void;
-    disconnectedCallback(): void;
-    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
-    private _tearDown;
-    private _maybeLoad;
-}
-
-declare const ELEMENT_BASE$6: typeof HTMLElement;
-declare class PolyPolygonElement extends ELEMENT_BASE$6 {
-    static get observedAttributes(): string[];
-    private _handle;
-    connectedCallback(): void;
-    disconnectedCallback(): void;
-    attributeChangedCallback(_name: string, oldValue: string | null, newValue: string | null): void;
-    private _tearDown;
-    private _mount;
-}
-
-declare const ELEMENT_BASE$5: typeof HTMLElement;
-declare class PolyOrbitControlsElement extends ELEMENT_BASE$5 {
-    static get observedAttributes(): string[];
-    private _controls;
-    private _readAnimate;
-    private _readOptions;
-    private _findScene;
-    private _attach;
-    connectedCallback(): void;
-    disconnectedCallback(): void;
-    attributeChangedCallback(_name: string, oldValue: string | null, newValue: string | null): void;
-}
-
-declare const ELEMENT_BASE$4: typeof HTMLElement;
-declare class PolyMapControlsElement extends ELEMENT_BASE$4 {
-    static get observedAttributes(): string[];
-    private _controls;
-    private _readAnimate;
-    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.
- *
- * Wraps `createPolyPerspectiveCamera`. Unlike <poly-scene> which owns the
- * scene DOM, this element provides a camera context that child controls can
- * read. It creates a `<div class="polycss-camera">` wrapper with the
- * CSS `perspective` property set.
- *
- * Attributes (all optional):
- *   perspective   — number, CSS perspective in pixels (default 8000)
- *   zoom          — number
- *   rot-x         — number, degrees (default 65)
- *   rot-y         — number, degrees (default 45)
- *   target        — "x,y,z" comma-separated world coordinates
- *   distance      — number, camera pull-back in CSS pixels
- */
-
-declare const ELEMENT_BASE$3: typeof HTMLElement;
-declare class PolyPerspectiveCameraElement extends ELEMENT_BASE$3 {
-    static get observedAttributes(): string[];
-    private _camera;
-    private _wrapper;
-    /** Returns the camera handle, or null if not yet connected. */
-    getCamera(): PolyPerspectiveCameraHandle | null;
-    private _readOptions;
-    private _mount;
-    private _teardown;
-    connectedCallback(): void;
-    disconnectedCallback(): void;
-    attributeChangedCallback(_name: string, oldValue: string | null, newValue: string | null): void;
-}
-
-/**
- * <poly-orthographic-camera> — standalone orthographic camera element.
- *
- * Wraps `createPolyOrthographicCamera`. Sets CSS `perspective: none` on the
- * camera wrapper, disabling perspective projection.
- *
- * Attributes (all optional):
- *   zoom          — number
- *   rot-x         — number, degrees (default 65)
- *   rot-y         — number, degrees (default 45)
- *   target        — "x,y,z" comma-separated world coordinates
- *   distance      — number, camera pull-back in CSS pixels
- */
-
-declare const ELEMENT_BASE$2: typeof HTMLElement;
-declare class PolyOrthographicCameraElement extends ELEMENT_BASE$2 {
-    static get observedAttributes(): string[];
-    private _camera;
-    private _wrapper;
-    /** Returns the camera handle, or null if not yet connected. */
-    getCamera(): PolyOrthographicCameraHandle | null;
-    private _readOptions;
-    private _mount;
-    private _teardown;
-    connectedCallback(): void;
-    disconnectedCallback(): void;
-    attributeChangedCallback(_name: string, oldValue: string | null, newValue: string | null): void;
-}
-
-declare const ELEMENT_BASE$1: typeof HTMLElement;
-declare class PolyTransformControlsElement extends ELEMENT_BASE$1 {
-    static get observedAttributes(): string[];
-    private _tc;
-    private _findScene;
-    private _findTargetMesh;
-    private _readOptions;
-    private _attach;
-    connectedCallback(): void;
-    disconnectedCallback(): void;
-    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
-}
-
-declare const ELEMENT_BASE: typeof HTMLElement;
-declare class PolySelectElement extends ELEMENT_BASE {
-    static get observedAttributes(): string[];
-    private _selection;
-    private _findScene;
-    private _readOptions;
-    private _attach;
-    connectedCallback(): void;
-    disconnectedCallback(): void;
-    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 };