@layoutit/polycss 0.2.6 → 0.2.8

package/README.md

@@ -21,7 +21,6 @@ npm install @layoutit/polycss-vue
 
 ```
 
-
 You can also load PolyCSS directly from a CDN. Here is a minimal custom-element scene:
 
 ```html
@@ -39,7 +38,7 @@ You can also load PolyCSS directly from a CDN. Here is a minimal custom-element
 
 ## Framework Components
 
-React and Vue expose the same component model. `<PolyCamera>` owns the viewpoint, `<PolyScene>` owns lighting and atlas options, and `<PolyMesh>` loads or receives polygon data.
+React and Vue expose the same component model. `<PolyCamera>` owns the viewpoint, `<PolyScene>` owns lighting and options, and `<PolyMesh>` loads or receives polygon data.
 
 ```tsx
 import { PolyCamera, PolyScene, PolyOrbitControls, PolyMesh } from "@layoutit/polycss-react";
@@ -56,6 +55,54 @@ export default function App() {
 }
 ```
 
+## Three.js Parity API
+
+When porting Three.js scenes or generating code with an agent, use the explicit
+`*/three` subpaths:
+
+- `@layoutit/polycss-core/three`
+- `@layoutit/polycss/three`
+- `@layoutit/polycss-react/three`
+- `@layoutit/polycss-vue/three`
+
+They expose Three-like `PerspectiveCamera`, `OrthographicCamera`, `Object3D`,
+`Vector3`, `DirectionalLight`, `PointLight`, `AmbientLight`, radians for object
+rotations, Y-up authoring coordinates, and `camera.position` + `camera.lookAt(...)`
+framing. The adapters convert into native PolyCSS coordinates with a right-handed
+axis map, so the apparent object size, projection, orientation, depth ordering,
+and light direction line up with Three.js scene math while still rendering
+through the DOM.
+
+```tsx
+import { PolyScene } from "@layoutit/polycss-react";
+import {
+  DirectionalLight,
+  PolyThreeMesh,
+  PolyThreePerspectiveCamera,
+} from "@layoutit/polycss-react/three";
+
+const sun = new DirectionalLight("#ffffff", 1);
+sun.position.set(3, 5, 4);
+sun.target.position.set(0, 0, 0);
+
+export function App() {
+  return (
+    <PolyThreePerspectiveCamera
+      fov={50}
+      aspect={16 / 9}
+      position={[3, 2, 5]}
+      lookAt={[0, 0, 0]}
+    >
+      <PolyScene directionalLight={sun.toPolyDirectionalLight()}>
+        <PolyThreeMesh src="/models/cube.glb" rotation={[0, Math.PI / 4, 0]} />
+      </PolyScene>
+    </PolyThreePerspectiveCamera>
+  );
+}
+```
+
+Full reference: [polycss.com/api/three-parity](https://polycss.com/api/three-parity).
+
 ## API Reference
 
 ### PolyCamera
@@ -69,7 +116,7 @@ export default function App() {
 ### PolyScene
 
 - `polygons` renders a static `Polygon[]` directly.
-- `directionalLight` and `ambientLight` control scene lighting.
+- `directionalLight`, `pointLights` (direction-only, baked mode; optional per-light `castShadow`), and `ambientLight` control scene lighting.
 - `textureLighting` chooses `"baked"` or `"dynamic"`.
 - `textureQuality` controls atlas raster budget.
 - `strategies` can disable selected render strategies for diagnostics.
@@ -84,7 +131,6 @@ export default function App() {
 - `autoCenter` shifts the mesh bbox center to local origin.
 - `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`, `buildPolySceneTransform`, `worldPositionToPolyCss`, `worldDirectionToPolyCss`, `worldDirectionalLightToPolyCss`, `worldDistanceToPolyCss`, `polyCssDistanceToWorld`, and `polyCssPositionToWorld` for renderer-compatible transforms and world/CSS conversions.
 
 ### Controls
 
@@ -188,10 +234,11 @@ Each visible polygon is emitted as one leaf element; the renderer chooses the le
 
 ## Made with PolyCSS
 
-[Layoutit Voxels](https://voxels.layoutit.com)
--> A CSS Voxel editor
+[cssQuake](https://cssquake.com)
+-> A CSS port of Quake (1996)
+
+<img width="1280" height="720" alt="quake" src="https://github.com/user-attachments/assets/6d9d809c-857a-4a39-b5cf-733ead2661ec" />
 
-<img width="1000" height="600" alt="layoutit-voxels" src="https://polycss.com/layoutit-voxels.png" />
 
 [Layoutit Terra](https://terra.layoutit.com)
 -> A CSS Terrain Generator

package/dist/PolyShapeElements-BviHejaw.d.cts

@@ -0,0 +1,371 @@
+import { P as PolySceneHandle, a as PolyMeshHandle, f as PolyPerspectiveCameraHandle, d as PolyOrthographicCameraHandle } from './types-CfRKEj2z.cjs';
+import { Vec3, Polygon } from '@layoutit/polycss-core';
+
+/**
+ * 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;
+    /**
+     * Returns the underlying PolySceneHandle. Children call this during their own
+     * connectedCallback to register meshes.
+     */
+    getScene(): PolySceneHandle | null;
+    private _findAncestorCamera;
+    private _buildImplicitCamera;
+    private _readNonCameraOptions;
+    private _readDirectionalLight;
+    private _readAmbientLight;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+}
+
+declare const ELEMENT_BASE$a: typeof HTMLElement;
+declare class PolyMeshElement extends ELEMENT_BASE$a {
+    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$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[];
+    private _handle;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(_name: string, oldValue: string | null, newValue: string | null): void;
+    private _tearDown;
+    private _mount;
+}
+
+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;
+    private _attach;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(_name: string, oldValue: string | null, newValue: string | null): void;
+}
+
+declare const ELEMENT_BASE$6: typeof HTMLElement;
+declare class PolyMapControlsElement extends ELEMENT_BASE$6 {
+    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$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.
+ *
+ * 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 32000)
+ *   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$4: typeof HTMLElement;
+declare class PolyPerspectiveCameraElement extends ELEMENT_BASE$4 {
+    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$3: typeof HTMLElement;
+declare class PolyOrthographicCameraElement extends ELEMENT_BASE$3 {
+    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;
+}
+
+/**
+ * <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;
+    private _findTargetMesh;
+    private _readOptions;
+    private _attach;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+}
+
+declare const ELEMENT_BASE$1: typeof HTMLElement;
+declare class PolySelectElement extends ELEMENT_BASE$1 {
+    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;
+}
+
+/**
+ * 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;
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): 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 { PolySceneElement as A, PolySelectElement as B, PolySphereElement as C, PolyTetrahedronElement as D, PolyTorusElement as E, PolyTransformControlsElement as F, createPolyOrbitControls as G, type PolyControlsHandle as P, type PolyControlsBaseOptions as a, type PolyControlsEvent as b, type PolyControlsListener as c, PolyBoxElement as d, PolyCameraElement as e, PolyConeElement as f, type PolyControlsAnimateOptions as g, type PolyControlsCamera as h, type PolyControlsChangeEvent as i, type PolyControlsInteractionEvent as j, PolyCylinderElement as k, PolyDodecahedronElement as l, PolyFirstPersonControlsElement as m, PolyIcosahedronElement as n, PolyIframeElement as o, PolyMapControlsElement as p, PolyMeshElement as q, PolyOctahedronElement as r, PolyOrbitControlsElement as s, type PolyOrbitControlsHandle as t, type PolyOrbitControlsOptions as u, PolyOrthographicCameraElement as v, PolyPerspectiveCameraElement as w, PolyPlaneElement as x, PolyPolygonElement as y, PolyRingElement as z };