@layoutit/polycss-core 0.2.7 → 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
@@ -187,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/camera-VU-yix11.d.cts

@@ -0,0 +1,304 @@
+declare const DEFAULT_PROJECTION: "cubic";
+/**
+ * How polygon lighting is applied by DOM renderers.
+ * - "baked": multiply the light tint into the off-DOM canvas before the
+ *   polygon becomes an atlas sprite. Best fidelity (full RGB tint) but
+ *   the atlas re-rasterizes whenever the light changes.
+ * - "dynamic": lighting computed entirely in CSS via per-polygon normals
+ *   embedded in calc() and scene-root light vars (background-color +
+ *   background-blend-mode multiply, masked by the atlas alpha). Atlas
+ *   stays light-independent — sliding the light only writes a few CSS
+ *   variables, no JS work, no atlas re-rasterization.
+ */
+type PolyTextureLightingMode = "baked" | "dynamic";
+type PolyTextureLeafSizing = "canonical" | "local" | "raster";
+type PolyTextureBackend = "auto" | "atlas" | "image";
+type PolyTextureImageRendering = "auto" | "pixelated";
+type PolyTextureImageLighting = "scene" | "source";
+type PolyTextureProjection = "affine" | "projective";
+interface PolyTextureImageSource {
+    url: string;
+    width: number;
+    height: number;
+    sourceRect?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    imageRendering?: PolyTextureImageRendering;
+}
+interface PolyTexturePresentation {
+    imageRendering?: PolyTextureImageRendering;
+    backend?: PolyTextureBackend;
+    lighting?: PolyTextureImageLighting;
+    projection?: PolyTextureProjection;
+}
+/**
+ * Mesh post-processing intent.
+ * - "lossless": preserve the authored surface while applying exact
+ *   reductions such as interior culling and coplanar merge.
+ * - "lossy": allow bounded geometric approximation when it reduces the
+ *   rendered polygon/DOM count.
+ */
+type MeshResolution = "lossless" | "lossy";
+/**
+ * 3D point/vector, stored as a `[x, y, z]` tuple. Tuple (rather than
+ * `{x, y, z}`) for compact JSON: meshes serialize to thousands of vertices
+ * and the difference adds up. Destructure with `const [x, y, z] = v` when
+ * you need named axes.
+ *
+ * PolyCSS world space convention: +X right, +Y forward, +Z up.
+ */
+type Vec3 = [number, number, number];
+/**
+ * 2D point/vector — `[u, v]`. Used for texture-atlas UV coordinates on
+ * polygons. Convention follows OBJ: u is horizontal (0=left, 1=right),
+ * v is vertical (0=bottom, 1=top). Renderers flip v when binding to raster
+ * image space whose Y-axis points down.
+ */
+type Vec2 = [number, number];
+interface TextureTriangle {
+    vertices: [Vec3, Vec3, Vec3];
+    uvs: [Vec2, Vec2, Vec2];
+}
+type PolyTextureWrapMode = "repeat" | "clamp-to-edge" | "mirrored-repeat";
+interface PolyTextureWrap {
+    s: PolyTextureWrapMode;
+    t: PolyTextureWrapMode;
+}
+type PolyTextureAlphaMode = "opaque" | "mask" | "blend";
+/**
+ * Directional light — simulates a single distant source (sun, key light).
+ * Contributes Lambert shading scaled by `intensity`. `direction` is in
+ * scene-local CSS-pixel coords and does not need to be pre-normalized.
+ * Mirrors three.js's `DirectionalLight`.
+ */
+interface PolyDirectionalLight {
+    /** Unit direction from the surface toward the distant light source. */
+    direction: Vec3;
+    /** Light tint, hex string. White by default. */
+    color?: string;
+    /** Scalar multiplier on the directional contribution. Default 1. */
+    intensity?: number;
+}
+/**
+ * Point light — radiates from a world-space position. Contributes per-face
+ * Lambert like a directional light, but the light direction is computed
+ * per polygon (face centroid → light position) rather than being global.
+ *
+ * DIRECTION-ONLY by design: there is no distance falloff (no `decay`/
+ * `distance`). A point light differs from a directional light only in that
+ * its direction varies per face. To emulate in three.js for parity, use
+ * `new THREE.PointLight(color, intensity, 0, 0)` (distance 0, decay 0 →
+ * no attenuation). Shading is flat per face (the centroid direction), so it
+ * approximates three.js's per-fragment gradient — exact for small faces /
+ * distant lights, never a CSS gradient.
+ */
+interface PolyPointLight {
+    /** World-space position the light radiates from. */
+    position: Vec3;
+    /** Light tint, hex string. White by default. */
+    color?: string;
+    /** Scalar multiplier on the contribution. Default 1. */
+    intensity?: number;
+    /** When true, this light casts shadows (radial projection). Default false. */
+    castShadow?: boolean;
+}
+/**
+ * Ambient light — uniform fill that adds to every polygon regardless of
+ * orientation. Mirrors three.js's `AmbientLight`. Decoupled from the
+ * directional contribution: the two add independently rather than
+ * splitting a fixed energy budget.
+ */
+interface PolyAmbientLight {
+    /** Tint, hex string. White by default. */
+    color?: string;
+    /** Scalar multiplier on the ambient contribution. Default 0.4. */
+    intensity?: number;
+}
+/**
+ * Material — paint configuration shareable across many polygons.
+ *
+ * In CSS terms, a material bundles the `background-image` source plus paint
+ * config. When a polygon references a material AND its UVs form an
+ * axis-aligned rectangle, PolyCSS renders the polygon as an <i> with
+ * `background-image: url(material.texture)` directly — no per-polygon canvas
+ * rasterization, browser-cached texture, mounting / unmounting one polygon
+ * does not affect any other.
+ *
+ * Three.js parallel: combines THREE.Texture + a basic Material in one. CSS
+ * has no shader/sampler concerns, so the texture/material split from
+ * Three.js doesn't pay rent here.
+ */
+interface PolyMaterial {
+    /** Image source. Anything `background-image: url(...)` can use. */
+    texture: string;
+    /** Optional unique key (used by PolyCSS to dedupe / cache). Caller can
+     *  pass a stable string; if omitted, the material's identity is its object
+     *  reference. */
+    key?: string;
+    imageSource?: PolyTextureImageSource;
+    presentation?: PolyTexturePresentation;
+}
+/**
+ * The single polygon type for polycss. N coplanar vertices in 3D space,
+ * CCW winding from outside. No bbox field, no shape discriminator, no
+ * input/output distinction — one type, used by parsers, by the merge
+ * pass, and by the renderer.
+ */
+interface Polygon {
+    /** N coplanar vertices in 3D space, CCW winding from outside. */
+    vertices: Vec3[];
+    /**
+     * Solid base color. Falls back to "#cccccc" when neither color nor
+     * texture is set.
+     */
+    color?: string;
+    /**
+     * Texture URL. When set with `uvs`, UV-mapped via affine; without
+     * `uvs`, single-tile fill. If the load fails, renderer falls back to
+     * `color` (or default gray).
+     */
+    texture?: string;
+    /**
+     * Texture sampler wrap mode for UVs outside [0, 1]. glTF imports preserve
+     * sampler.wrapS / wrapT here so the atlas rasterizer can tile repeated UVs.
+     * When unset, renderers keep the historical single-image behavior.
+     * @internal
+     */
+    textureWrap?: PolyTextureWrap;
+    /**
+     * Texture alpha interpretation imported from glTF `material.alphaMode`.
+     * Opaque textures can use transparent PNG padding without cutting holes in
+     * the rendered polygon.
+     * @internal
+     */
+    textureAlphaMode?: PolyTextureAlphaMode;
+    /**
+     * Shared material. When set, `material.texture` takes precedence over the
+     * inline `texture` field. If the polygon's UVs form an axis-aligned
+     * rectangle, PolyCSS uses the direct CSS background-image path (no per-
+     * polygon canvas rasterization). Falls back to the atlas path otherwise.
+     */
+    material?: PolyMaterial;
+    textureImageSource?: PolyTextureImageSource;
+    texturePresentation?: PolyTexturePresentation;
+    /**
+     * Per-vertex UV coords (0..1, OBJ convention with v=0 at bottom).
+     * Length MUST equal vertices.length when set; mismatched UVs are
+     * stripped by `normalizePolygons`.
+     */
+    uvs?: Vec2[];
+    /**
+     * Renderer-internal source triangles for UV textures. Merge passes use this
+     * to reduce DOM planes while preserving per-triangle texture mapping in the
+     * generated atlas.
+     * @internal
+     */
+    textureTriangles?: TextureTriangle[];
+    /**
+     * Import-time simplifier seam keys retained after solid texture baking.
+     * Renderers ignore this; mesh optimization uses it to avoid welding vertices
+     * that shared a position but came from different texture/attribute seams.
+     * @internal
+     */
+    simplifyVertexKeys?: string[];
+    /**
+     * Stricter import-time simplifier keys that preserve source vertex identity.
+     * Renderers ignore this; candidate simplification uses it only for fallback
+     * passes where relaxed seam welding loses after render-cost optimization.
+     * @internal
+     */
+    simplifySourceVertexKeys?: string[];
+    /**
+     * Source material requested two-sided rendering. Importers use this so
+     * optimization passes do not collapse intentional reverse-wound faces.
+     * @internal
+     */
+    doubleSided?: boolean;
+    /**
+     * User-controlled metadata. Reflected to DOM as `data-*` attributes via
+     * stringification by the framework wrappers. Only string|number|boolean
+     * values are kept; other shapes are dropped by `normalizePolygons`.
+     */
+    data?: Record<string, string | number | boolean>;
+}
+
+/**
+ * Base tile size in CSS pixels. One PolyCSS world unit = BASE_TILE CSS
+ * pixels (pre-scale). Used to convert world-coordinate target values to
+ * CSS translations in the transform string.
+ */
+declare const BASE_TILE = 50;
+interface AutoRotateConfig {
+    axis?: "x" | "y";
+    speed?: number;
+    pauseOnInteraction?: boolean;
+}
+type AutoRotateOption = boolean | number | AutoRotateConfig;
+/**
+ * World-coordinate camera state (Three.js-style).
+ *
+ * `target` is the world point that should appear at the viewport centre.
+ * PolyCSS world axes: [0]=X (rows/south), [1]=Y (cols/east), [2]=Z (up).
+ *
+ * `pan`, `tilt`, and `depthOffset` are gone. Translations now live inside
+ * `target` so they happen BEFORE rotations — enabling correct world-space
+ * pan at any tilt angle.
+ *
+ * `distance` is the camera's pull-back from the target in CSS pixels.
+ * Increasing distance moves the camera farther from the target along the
+ * view axis (dolly out) — analogous to three.js's spherical radius.
+ * Default 0 keeps orthographic/isometric scenes flat.
+ */
+interface CameraState {
+    target: Vec3;
+    rotX: number;
+    rotY: number;
+    zoom: number;
+    /** Camera pull-back from target in CSS pixels. Default 0. */
+    distance: number;
+}
+interface CameraStyleInput {
+    rows?: number;
+    cols?: number;
+}
+interface CameraHandle {
+    state: CameraState;
+    update(next: Partial<CameraState>): void;
+    getStyle(input?: CameraStyleInput): {
+        transform: string;
+        width: string;
+        height: string;
+    };
+}
+interface PolyCameraSceneTransformOptions {
+    autoCenterOffset?: Vec3;
+    layoutScale?: number;
+    tileSize?: number;
+}
+type PolyCameraProjection = "orthographic" | "perspective";
+interface PolyCameraSnapshot {
+    projection: PolyCameraProjection;
+    perspectiveStyle: string;
+    appliedPerspectiveStyle: string;
+    state: CameraState;
+}
+interface PolyCameraSnapshotOptions {
+    projection?: PolyCameraProjection;
+    perspectiveStyle?: string;
+}
+type PolyCameraSnapshotSource = CameraHandle & {
+    readonly type?: PolyCameraProjection;
+    readonly perspectiveStyle?: string;
+};
+declare function normalizeInvertMultiplier(value: number | boolean | undefined): number | undefined;
+declare const DEFAULT_CAMERA_STATE: CameraState;
+declare function polyCameraTargetToCss(target?: Vec3, autoCenterOffset?: Vec3, tileSize?: number): Vec3;
+declare function buildPolyCameraSceneTransform(state?: Partial<CameraState>, options?: PolyCameraSceneTransformOptions): string;
+declare function resolvePolyCameraAppliedPerspectiveStyle(perspectiveStyle?: string): string;
+declare function capturePolyCameraSnapshot(camera: PolyCameraSnapshotSource, options?: PolyCameraSnapshotOptions): PolyCameraSnapshot;
+declare function createIsometricCamera(initial?: Partial<CameraState>): CameraHandle;
+
+export { type AutoRotateConfig as A, BASE_TILE as B, type CameraState as C, DEFAULT_CAMERA_STATE as D, capturePolyCameraSnapshot as E, createIsometricCamera as F, normalizeInvertMultiplier as G, polyCameraTargetToCss as H, resolvePolyCameraAppliedPerspectiveStyle as I, type MeshResolution as M, type Polygon as P, type TextureTriangle as T, type Vec3 as V, type PolyDirectionalLight as a, type PolyAmbientLight as b, type PolyPointLight as c, type PolyTextureLightingMode as d, type Vec2 as e, type PolyTextureLeafSizing as f, type PolyTextureImageSource as g, type PolyTextureImageRendering as h, type PolyTextureImageLighting as i, type PolyTextureProjection as j, type PolyTextureBackend as k, type PolyTexturePresentation as l, type AutoRotateOption as m, type CameraHandle as n, type CameraStyleInput as o, DEFAULT_PROJECTION as p, type PolyCameraProjection as q, type PolyCameraSceneTransformOptions as r, type PolyCameraSnapshot as s, type PolyCameraSnapshotOptions as t, type PolyCameraSnapshotSource as u, type PolyMaterial as v, type PolyTextureAlphaMode as w, type PolyTextureWrap as x, type PolyTextureWrapMode as y, buildPolyCameraSceneTransform as z };

package/dist/camera-VU-yix11.d.ts

@@ -0,0 +1,304 @@
+declare const DEFAULT_PROJECTION: "cubic";
+/**
+ * How polygon lighting is applied by DOM renderers.
+ * - "baked": multiply the light tint into the off-DOM canvas before the
+ *   polygon becomes an atlas sprite. Best fidelity (full RGB tint) but
+ *   the atlas re-rasterizes whenever the light changes.
+ * - "dynamic": lighting computed entirely in CSS via per-polygon normals
+ *   embedded in calc() and scene-root light vars (background-color +
+ *   background-blend-mode multiply, masked by the atlas alpha). Atlas
+ *   stays light-independent — sliding the light only writes a few CSS
+ *   variables, no JS work, no atlas re-rasterization.
+ */
+type PolyTextureLightingMode = "baked" | "dynamic";
+type PolyTextureLeafSizing = "canonical" | "local" | "raster";
+type PolyTextureBackend = "auto" | "atlas" | "image";
+type PolyTextureImageRendering = "auto" | "pixelated";
+type PolyTextureImageLighting = "scene" | "source";
+type PolyTextureProjection = "affine" | "projective";
+interface PolyTextureImageSource {
+    url: string;
+    width: number;
+    height: number;
+    sourceRect?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    imageRendering?: PolyTextureImageRendering;
+}
+interface PolyTexturePresentation {
+    imageRendering?: PolyTextureImageRendering;
+    backend?: PolyTextureBackend;
+    lighting?: PolyTextureImageLighting;
+    projection?: PolyTextureProjection;
+}
+/**
+ * Mesh post-processing intent.
+ * - "lossless": preserve the authored surface while applying exact
+ *   reductions such as interior culling and coplanar merge.
+ * - "lossy": allow bounded geometric approximation when it reduces the
+ *   rendered polygon/DOM count.
+ */
+type MeshResolution = "lossless" | "lossy";
+/**
+ * 3D point/vector, stored as a `[x, y, z]` tuple. Tuple (rather than
+ * `{x, y, z}`) for compact JSON: meshes serialize to thousands of vertices
+ * and the difference adds up. Destructure with `const [x, y, z] = v` when
+ * you need named axes.
+ *
+ * PolyCSS world space convention: +X right, +Y forward, +Z up.
+ */
+type Vec3 = [number, number, number];
+/**
+ * 2D point/vector — `[u, v]`. Used for texture-atlas UV coordinates on
+ * polygons. Convention follows OBJ: u is horizontal (0=left, 1=right),
+ * v is vertical (0=bottom, 1=top). Renderers flip v when binding to raster
+ * image space whose Y-axis points down.
+ */
+type Vec2 = [number, number];
+interface TextureTriangle {
+    vertices: [Vec3, Vec3, Vec3];
+    uvs: [Vec2, Vec2, Vec2];
+}
+type PolyTextureWrapMode = "repeat" | "clamp-to-edge" | "mirrored-repeat";
+interface PolyTextureWrap {
+    s: PolyTextureWrapMode;
+    t: PolyTextureWrapMode;
+}
+type PolyTextureAlphaMode = "opaque" | "mask" | "blend";
+/**
+ * Directional light — simulates a single distant source (sun, key light).
+ * Contributes Lambert shading scaled by `intensity`. `direction` is in
+ * scene-local CSS-pixel coords and does not need to be pre-normalized.
+ * Mirrors three.js's `DirectionalLight`.
+ */
+interface PolyDirectionalLight {
+    /** Unit direction from the surface toward the distant light source. */
+    direction: Vec3;
+    /** Light tint, hex string. White by default. */
+    color?: string;
+    /** Scalar multiplier on the directional contribution. Default 1. */
+    intensity?: number;
+}
+/**
+ * Point light — radiates from a world-space position. Contributes per-face
+ * Lambert like a directional light, but the light direction is computed
+ * per polygon (face centroid → light position) rather than being global.
+ *
+ * DIRECTION-ONLY by design: there is no distance falloff (no `decay`/
+ * `distance`). A point light differs from a directional light only in that
+ * its direction varies per face. To emulate in three.js for parity, use
+ * `new THREE.PointLight(color, intensity, 0, 0)` (distance 0, decay 0 →
+ * no attenuation). Shading is flat per face (the centroid direction), so it
+ * approximates three.js's per-fragment gradient — exact for small faces /
+ * distant lights, never a CSS gradient.
+ */
+interface PolyPointLight {
+    /** World-space position the light radiates from. */
+    position: Vec3;
+    /** Light tint, hex string. White by default. */
+    color?: string;
+    /** Scalar multiplier on the contribution. Default 1. */
+    intensity?: number;
+    /** When true, this light casts shadows (radial projection). Default false. */
+    castShadow?: boolean;
+}
+/**
+ * Ambient light — uniform fill that adds to every polygon regardless of
+ * orientation. Mirrors three.js's `AmbientLight`. Decoupled from the
+ * directional contribution: the two add independently rather than
+ * splitting a fixed energy budget.
+ */
+interface PolyAmbientLight {
+    /** Tint, hex string. White by default. */
+    color?: string;
+    /** Scalar multiplier on the ambient contribution. Default 0.4. */
+    intensity?: number;
+}
+/**
+ * Material — paint configuration shareable across many polygons.
+ *
+ * In CSS terms, a material bundles the `background-image` source plus paint
+ * config. When a polygon references a material AND its UVs form an
+ * axis-aligned rectangle, PolyCSS renders the polygon as an <i> with
+ * `background-image: url(material.texture)` directly — no per-polygon canvas
+ * rasterization, browser-cached texture, mounting / unmounting one polygon
+ * does not affect any other.
+ *
+ * Three.js parallel: combines THREE.Texture + a basic Material in one. CSS
+ * has no shader/sampler concerns, so the texture/material split from
+ * Three.js doesn't pay rent here.
+ */
+interface PolyMaterial {
+    /** Image source. Anything `background-image: url(...)` can use. */
+    texture: string;
+    /** Optional unique key (used by PolyCSS to dedupe / cache). Caller can
+     *  pass a stable string; if omitted, the material's identity is its object
+     *  reference. */
+    key?: string;
+    imageSource?: PolyTextureImageSource;
+    presentation?: PolyTexturePresentation;
+}
+/**
+ * The single polygon type for polycss. N coplanar vertices in 3D space,
+ * CCW winding from outside. No bbox field, no shape discriminator, no
+ * input/output distinction — one type, used by parsers, by the merge
+ * pass, and by the renderer.
+ */
+interface Polygon {
+    /** N coplanar vertices in 3D space, CCW winding from outside. */
+    vertices: Vec3[];
+    /**
+     * Solid base color. Falls back to "#cccccc" when neither color nor
+     * texture is set.
+     */
+    color?: string;
+    /**
+     * Texture URL. When set with `uvs`, UV-mapped via affine; without
+     * `uvs`, single-tile fill. If the load fails, renderer falls back to
+     * `color` (or default gray).
+     */
+    texture?: string;
+    /**
+     * Texture sampler wrap mode for UVs outside [0, 1]. glTF imports preserve
+     * sampler.wrapS / wrapT here so the atlas rasterizer can tile repeated UVs.
+     * When unset, renderers keep the historical single-image behavior.
+     * @internal
+     */
+    textureWrap?: PolyTextureWrap;
+    /**
+     * Texture alpha interpretation imported from glTF `material.alphaMode`.
+     * Opaque textures can use transparent PNG padding without cutting holes in
+     * the rendered polygon.
+     * @internal
+     */
+    textureAlphaMode?: PolyTextureAlphaMode;
+    /**
+     * Shared material. When set, `material.texture` takes precedence over the
+     * inline `texture` field. If the polygon's UVs form an axis-aligned
+     * rectangle, PolyCSS uses the direct CSS background-image path (no per-
+     * polygon canvas rasterization). Falls back to the atlas path otherwise.
+     */
+    material?: PolyMaterial;
+    textureImageSource?: PolyTextureImageSource;
+    texturePresentation?: PolyTexturePresentation;
+    /**
+     * Per-vertex UV coords (0..1, OBJ convention with v=0 at bottom).
+     * Length MUST equal vertices.length when set; mismatched UVs are
+     * stripped by `normalizePolygons`.
+     */
+    uvs?: Vec2[];
+    /**
+     * Renderer-internal source triangles for UV textures. Merge passes use this
+     * to reduce DOM planes while preserving per-triangle texture mapping in the
+     * generated atlas.
+     * @internal
+     */
+    textureTriangles?: TextureTriangle[];
+    /**
+     * Import-time simplifier seam keys retained after solid texture baking.
+     * Renderers ignore this; mesh optimization uses it to avoid welding vertices
+     * that shared a position but came from different texture/attribute seams.
+     * @internal
+     */
+    simplifyVertexKeys?: string[];
+    /**
+     * Stricter import-time simplifier keys that preserve source vertex identity.
+     * Renderers ignore this; candidate simplification uses it only for fallback
+     * passes where relaxed seam welding loses after render-cost optimization.
+     * @internal
+     */
+    simplifySourceVertexKeys?: string[];
+    /**
+     * Source material requested two-sided rendering. Importers use this so
+     * optimization passes do not collapse intentional reverse-wound faces.
+     * @internal
+     */
+    doubleSided?: boolean;
+    /**
+     * User-controlled metadata. Reflected to DOM as `data-*` attributes via
+     * stringification by the framework wrappers. Only string|number|boolean
+     * values are kept; other shapes are dropped by `normalizePolygons`.
+     */
+    data?: Record<string, string | number | boolean>;
+}
+
+/**
+ * Base tile size in CSS pixels. One PolyCSS world unit = BASE_TILE CSS
+ * pixels (pre-scale). Used to convert world-coordinate target values to
+ * CSS translations in the transform string.
+ */
+declare const BASE_TILE = 50;
+interface AutoRotateConfig {
+    axis?: "x" | "y";
+    speed?: number;
+    pauseOnInteraction?: boolean;
+}
+type AutoRotateOption = boolean | number | AutoRotateConfig;
+/**
+ * World-coordinate camera state (Three.js-style).
+ *
+ * `target` is the world point that should appear at the viewport centre.
+ * PolyCSS world axes: [0]=X (rows/south), [1]=Y (cols/east), [2]=Z (up).
+ *
+ * `pan`, `tilt`, and `depthOffset` are gone. Translations now live inside
+ * `target` so they happen BEFORE rotations — enabling correct world-space
+ * pan at any tilt angle.
+ *
+ * `distance` is the camera's pull-back from the target in CSS pixels.
+ * Increasing distance moves the camera farther from the target along the
+ * view axis (dolly out) — analogous to three.js's spherical radius.
+ * Default 0 keeps orthographic/isometric scenes flat.
+ */
+interface CameraState {
+    target: Vec3;
+    rotX: number;
+    rotY: number;
+    zoom: number;
+    /** Camera pull-back from target in CSS pixels. Default 0. */
+    distance: number;
+}
+interface CameraStyleInput {
+    rows?: number;
+    cols?: number;
+}
+interface CameraHandle {
+    state: CameraState;
+    update(next: Partial<CameraState>): void;
+    getStyle(input?: CameraStyleInput): {
+        transform: string;
+        width: string;
+        height: string;
+    };
+}
+interface PolyCameraSceneTransformOptions {
+    autoCenterOffset?: Vec3;
+    layoutScale?: number;
+    tileSize?: number;
+}
+type PolyCameraProjection = "orthographic" | "perspective";
+interface PolyCameraSnapshot {
+    projection: PolyCameraProjection;
+    perspectiveStyle: string;
+    appliedPerspectiveStyle: string;
+    state: CameraState;
+}
+interface PolyCameraSnapshotOptions {
+    projection?: PolyCameraProjection;
+    perspectiveStyle?: string;
+}
+type PolyCameraSnapshotSource = CameraHandle & {
+    readonly type?: PolyCameraProjection;
+    readonly perspectiveStyle?: string;
+};
+declare function normalizeInvertMultiplier(value: number | boolean | undefined): number | undefined;
+declare const DEFAULT_CAMERA_STATE: CameraState;
+declare function polyCameraTargetToCss(target?: Vec3, autoCenterOffset?: Vec3, tileSize?: number): Vec3;
+declare function buildPolyCameraSceneTransform(state?: Partial<CameraState>, options?: PolyCameraSceneTransformOptions): string;
+declare function resolvePolyCameraAppliedPerspectiveStyle(perspectiveStyle?: string): string;
+declare function capturePolyCameraSnapshot(camera: PolyCameraSnapshotSource, options?: PolyCameraSnapshotOptions): PolyCameraSnapshot;
+declare function createIsometricCamera(initial?: Partial<CameraState>): CameraHandle;
+
+export { type AutoRotateConfig as A, BASE_TILE as B, type CameraState as C, DEFAULT_CAMERA_STATE as D, capturePolyCameraSnapshot as E, createIsometricCamera as F, normalizeInvertMultiplier as G, polyCameraTargetToCss as H, resolvePolyCameraAppliedPerspectiveStyle as I, type MeshResolution as M, type Polygon as P, type TextureTriangle as T, type Vec3 as V, type PolyDirectionalLight as a, type PolyAmbientLight as b, type PolyPointLight as c, type PolyTextureLightingMode as d, type Vec2 as e, type PolyTextureLeafSizing as f, type PolyTextureImageSource as g, type PolyTextureImageRendering as h, type PolyTextureImageLighting as i, type PolyTextureProjection as j, type PolyTextureBackend as k, type PolyTexturePresentation as l, type AutoRotateOption as m, type CameraHandle as n, type CameraStyleInput as o, DEFAULT_PROJECTION as p, type PolyCameraProjection as q, type PolyCameraSceneTransformOptions as r, type PolyCameraSnapshot as s, type PolyCameraSnapshotOptions as t, type PolyCameraSnapshotSource as u, type PolyMaterial as v, type PolyTextureAlphaMode as w, type PolyTextureWrap as x, type PolyTextureWrapMode as y, buildPolyCameraSceneTransform as z };