@layoutit/polycss-react 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/PolyMesh-7fLCYk5L.d.cts

@@ -0,0 +1,343 @@
+import * as React from 'react';
+import { CSSProperties, MouseEventHandler, PointerEventHandler, FocusEventHandler, KeyboardEventHandler, ReactNode } from 'react';
+import * as _layoutit_polycss_core from '@layoutit/polycss-core';
+import { Vec3, PolyTextureImageSource, PolyTexturePresentation, Vec2, PolyMaterial, PolyDirectionalLight, PolyTextureLightingMode, TextureQuality, PolyTextureLeafSizing, PolyTextureImageRendering, PolyTextureBackend, PolyTextureProjection, LoadMeshOptions, Polygon, ParseResult, PolySeamBleed, MeshResolution } from '@layoutit/polycss-core';
+
+/** Three.js-style transform props accepted by every PolyCSS component. */
+interface TransformProps {
+    position?: Vec3;
+    scale?: number | Vec3;
+    rotation?: Vec3;
+}
+/**
+ * DOM event handlers, ARIA, and style props forwarded to the rendered
+ * element by every Poly component.
+ *
+ * This is the DOM-native pitch: polygons are real DOM nodes you can
+ * target with CSS, attach event handlers to, and inspect in DevTools.
+ */
+interface DOMPassthroughProps {
+    className?: string;
+    style?: CSSProperties;
+    id?: string;
+    onClick?: MouseEventHandler<HTMLElement>;
+    onDoubleClick?: MouseEventHandler<HTMLElement>;
+    onMouseEnter?: MouseEventHandler<HTMLElement>;
+    onMouseLeave?: MouseEventHandler<HTMLElement>;
+    onMouseMove?: MouseEventHandler<HTMLElement>;
+    onPointerDown?: PointerEventHandler<HTMLElement>;
+    onPointerUp?: PointerEventHandler<HTMLElement>;
+    onPointerEnter?: PointerEventHandler<HTMLElement>;
+    onPointerLeave?: PointerEventHandler<HTMLElement>;
+    onFocus?: FocusEventHandler<HTMLElement>;
+    onBlur?: FocusEventHandler<HTMLElement>;
+    onKeyDown?: KeyboardEventHandler<HTMLElement>;
+    tabIndex?: number;
+    role?: string;
+    "aria-label"?: string;
+    "aria-hidden"?: boolean;
+    pointerEvents?: "auto" | "none";
+    [dataAttr: `data-${string}`]: string | number | boolean | undefined;
+}
+/**
+ * Props for the `<Poly>` component — the atomic polygon primitive.
+ *
+ * Extends TransformProps + DOMPassthroughProps with the polygon's own fields.
+ * This is the canonical Poly component API.
+ */
+interface PolyProps extends TransformProps, DOMPassthroughProps {
+    vertices: Vec3[];
+    color?: string;
+    texture?: string;
+    textureImageSource?: PolyTextureImageSource;
+    texturePresentation?: PolyTexturePresentation;
+    uvs?: Vec2[];
+    data?: Record<string, string | number | boolean>;
+    doubleSided?: boolean;
+    /** Shared material. When set AND the polygon's UVs form an axis-aligned
+     *  rectangle, renders via `background-image` directly — no per-polygon
+     *  canvas rasterization. Falls back to the atlas path otherwise. */
+    material?: PolyMaterial;
+    context?: {
+        tileSize?: number;
+        layerElevation?: number;
+        directionalLight?: PolyDirectionalLight;
+        textureLighting?: PolyTextureLightingMode;
+        textureQuality?: TextureQuality;
+        textureLeafSizing?: PolyTextureLeafSizing;
+        textureImageRendering?: PolyTextureImageRendering;
+        textureBackend?: PolyTextureBackend;
+        textureProjection?: PolyTextureProjection;
+        debugShowBackfaces?: boolean;
+        [key: string]: unknown;
+    };
+    /** Textured polygon lighting mode. Defaults to scene context, then "baked". */
+    textureLighting?: PolyTextureLightingMode;
+    /** Atlas bitmap budget and CSS sprite size. `"auto"` (default) uses a
+     *  device-appropriate memory budget and desktop/mobile sprite sizing. */
+    textureQuality?: TextureQuality;
+    /** Atlas leaf CSS primitive sizing. Defaults to scene context, then canonical. */
+    textureLeafSizing?: PolyTextureLeafSizing;
+    /** Default image filtering for atlas and direct image texture leaves. */
+    textureImageRendering?: PolyTextureImageRendering;
+    /** Default texture backend request. Defaults to scene context, then "auto". */
+    textureBackend?: PolyTextureBackend;
+    /** Default texture projection request. Defaults to scene context, then "affine". */
+    textureProjection?: PolyTextureProjection;
+    /** Pre-computed shaded base color from the parent (optional override). */
+    baseColor?: string;
+}
+
+type UseMeshOptions = LoadMeshOptions;
+interface UseMeshResult {
+    polygons: Polygon[];
+    voxelSource: ParseResult["voxelSource"];
+    loading: boolean;
+    error: Error | null;
+    warnings: string[];
+    /** Manually trigger cleanup (also called on unmount automatically). */
+    dispose: () => void;
+}
+declare function usePolyMesh(src: string, options?: UseMeshOptions): UseMeshResult;
+
+/**
+ * Pointer event API for <PolyMesh>. Mirrors @react-three/fiber's mesh
+ * event surface (handler names + payload shape) so devs migrating from
+ * three.js use the same mental model. PolyCSS is DOM-native so we get
+ * native pointer events for free — no raycaster, no canvas event
+ * synthesis.
+ *
+ * Diverges from r3f in two intentional ways:
+ *   1. Bubbling matches DOM (pointer hits the front element only). r3f
+ *      replays events to occluded objects behind the front hit; doing
+ *      that here would require running our own raycaster, which defeats
+ *      the point of being DOM-native.
+ *   2. `face`, `uv`, `uv1`, `instanceId` are omitted — they're three.js
+ *      BufferGeometry / InstancedMesh concepts with no polycss analogue.
+ *      The polycss-native equivalent of `face` is the hit polygon's
+ *      index, exposed via `polygon` (set when the underlying DOM target
+ *      is an `<i>` polygon element).
+ */
+
+/**
+ * Imperative handle exposed by `<PolyMesh ref>`. Read-only view of the
+ * mesh's element + current transform + polygons. Mutation flows through
+ * controlled props (parent owns transform state) — matches three.js
+ * editor's pattern of keeping `selected` external to the object.
+ */
+interface PolyMeshHandle {
+    /** The `.polycss-mesh` wrapper div (null until mounted). */
+    readonly element: HTMLDivElement | null;
+    /** Identifier passed via the `id` prop, if any. */
+    readonly id?: string;
+    /** Current `position` prop value. */
+    getPosition(): Vec3 | undefined;
+    /** Current `rotation` prop value (Euler degrees). */
+    getRotation(): Vec3 | undefined;
+    /** Current `scale` prop value. */
+    getScale(): number | Vec3 | undefined;
+    /** Polygons currently being rendered (post-autoCenter). */
+    getPolygons(): Polygon[];
+    /**
+     * Replace the mesh polygons imperatively. Animated solid-triangle meshes use
+     * a stable DOM update path that mutates mounted leaves directly; unsupported
+     * topology falls back to the normal framework render path.
+     */
+    setPolygons(polygons: Polygon[]): void;
+    /**
+     * Snapshot the current `rotation` prop as the new "baked rotation" and
+     * trigger an atlas re-rasterization with the directional light
+     * inverse-rotated into the mesh's local frame.
+     *
+     * Call this after a rotate-mode drag ends (i.e. on pointer release) —
+     * **not** on every pointermove during the drag. The visual wrapper already
+     * follows the live `rotation` prop smoothly; the atlas only needs to
+     * update once per committed rotation so it doesn't re-bake every frame.
+     *
+     * Math rationale: baked atlas tiles encode `baseColor × Lambert(worldNormal,
+     * worldLight)`. When the mesh wrapper rotates via CSS the world-space normal
+     * changes but the baked color does not, causing stale shading. Calling
+     * `rebakeAtlas()` inverse-rotates the world light into the mesh-local frame
+     * before re-running the atlas baker, so `dot(localNormal, localLight) ===
+     * dot(worldNormal, worldLight)` and the shading is correct again.
+     *
+     * In dynamic (`textureLighting="dynamic"`) mode this call is a no-op for
+     * shading purposes (dynamic mode re-evaluates per frame), but it is still
+     * safe to call.
+     */
+    rebakeAtlas(): void;
+    /** Resolves when this mesh's current texture generation has usable backgrounds. */
+    whenTexturesReady(): Promise<void>;
+    /**
+     * Mutate a single polygon in place and re-render the mesh. `target` is
+     * either a polygon reference (as returned by `getPolygons()`) or its index.
+     * `partial` fields are merged onto the polygon via `Object.assign`. Skips
+     * the merge pass — cheaper than a full prop change for targeted edits like
+     * color picker updates from an inspector UI. Silently no-ops when `target`
+     * is not found or the index is out of range.
+     */
+    updatePolygon(target: Polygon | number, partial: Partial<Polygon>): void;
+}
+/**
+ * Pointer event payload delivered to <PolyMesh> handlers. Mirrors r3f's
+ * shape, minus raycaster-specific fields. See module docstring for the
+ * intentional divergences.
+ */
+interface PolyPointerEvent<E extends Event = PointerEvent> {
+    /** The mesh originally under the pointer (deepest hit). */
+    object: PolyMeshHandle;
+    /** The mesh whose handler is being invoked. Equal to `object` until
+     *  ancestor bubbling is added (out of scope for v1). */
+    eventObject: PolyMeshHandle;
+    /** All meshes stacked under the pointer this moment, front-to-back.
+     *  Computed via `document.elementsFromPoint` then filtered to
+     *  registered `.polycss-mesh` ancestors. */
+    intersections: Array<{
+        object: PolyMeshHandle;
+    }>;
+    /** Pointer position in normalized device coords [-1, 1] relative to
+     *  the camera viewport. (0,0) = viewport center. Falls back to (0,0)
+     *  when the mesh is rendered outside a `<PolyCamera>`. */
+    pointer: {
+        x: number;
+        y: number;
+    };
+    /** Pixel distance from the most recent `pointerdown` to this event.
+     *  0 on pointerdown itself. Use to discriminate click-vs-drag. */
+    delta: number;
+    /** The underlying DOM event. */
+    nativeEvent: E;
+    /** Stops native bubbling. (Equivalent to `nativeEvent.stopPropagation()`
+     *  today; reserved for future r3f-style bubbling above the wrapper.) */
+    stopPropagation(): void;
+}
+type PolyMouseEvent = PolyPointerEvent<MouseEvent>;
+type PolyWheelEvent = PolyPointerEvent<WheelEvent>;
+type PolyEventHandler<E extends Event = PointerEvent> = (event: PolyPointerEvent<E>) => void;
+/**
+ * Pointer / mouse / wheel handlers accepted by `<PolyMesh>`. Names mirror
+ * r3f exactly. Provide any handler to opt the mesh into receiving events;
+ * absent handlers add zero overhead.
+ */
+interface InteractionProps {
+    onClick?: PolyEventHandler<MouseEvent>;
+    onContextMenu?: PolyEventHandler<MouseEvent>;
+    onDoubleClick?: PolyEventHandler<MouseEvent>;
+    onWheel?: PolyEventHandler<WheelEvent>;
+    onPointerDown?: PolyEventHandler<PointerEvent>;
+    onPointerUp?: PolyEventHandler<PointerEvent>;
+    onPointerMove?: PolyEventHandler<PointerEvent>;
+    onPointerOver?: PolyEventHandler<PointerEvent>;
+    onPointerOut?: PolyEventHandler<PointerEvent>;
+    onPointerEnter?: PolyEventHandler<PointerEvent>;
+    onPointerLeave?: PolyEventHandler<PointerEvent>;
+    onPointerCancel?: PolyEventHandler<PointerEvent>;
+}
+/** Walk up from `el` looking for the nearest registered mesh wrapper. */
+declare function findPolyMeshHandle(el: Element | null): PolyMeshHandle | null;
+/** Test whether `(clientX, clientY)` falls inside any polygon leaf
+ *  child of `meshEl`'s post-3D bounding rect. Skips zero-area rects
+ *  (happy-dom and pre-layout SSR return those). */
+declare function pointInMeshElement(meshEl: HTMLElement, clientX: number, clientY: number): boolean;
+/** Walk every registered `.polycss-mesh` in the document and return
+ *  the first whose polygon bounding-rects contain `(clientX, clientY)`.
+ *  An optional `filter` skips matched mesh elements (e.g. gizmos). */
+declare function findMeshUnderPoint(clientX: number, clientY: number, filter?: (meshEl: HTMLElement) => boolean): PolyMeshHandle | null;
+
+interface PolyMeshProps extends TransformProps, InteractionProps {
+    /** Stable identifier — exposed on the mesh handle and reflected as
+     *  `data-poly-mesh-id` on the wrapper div. Use for selection lookups. */
+    id?: string;
+    /** URL to .obj / .glb / .gltf. Mutually exclusive with `polygons`. */
+    src?: string;
+    /**
+     * Companion `.mtl` URL for OBJ models. When set, materials defined in
+     * the mtl (Kd colors, map_Kd textures) are applied to the loaded mesh.
+     * Ignored for GLB/GLTF (they carry materials inline).
+     */
+    mtl?: string;
+    /** Pre-parsed polygons. Mutually exclusive with `src`. */
+    polygons?: Polygon[];
+    /** Optional `parseResult.voxelSource` companion for `.vox` meshes. When
+     *  set alongside `polygons`, the direct voxel renderer fast path activates
+     *  — emitting one `<b>` per visible voxel quad inside `.polycss-voxel-face`
+     *  wrappers (matches vanilla's `scene.add(parseResult)` behaviour).
+     *  Callers fetching via core's `loadMesh()` pass `parseResult.voxelSource`
+     *  here so the fast path engages; callers fetching via PolyMesh's `src`
+     *  prop get the same data wired through `useMesh` automatically. */
+    voxelSource?: _layoutit_polycss_core.ParseResult["voxelSource"];
+    /** Translate so mesh's bbox center is at local origin before applying `position`. */
+    autoCenter?: boolean;
+    /** Textured polygon lighting mode. Defaults to "baked". */
+    textureLighting?: PolyTextureLightingMode;
+    /** Atlas bitmap budget and CSS sprite size. `"auto"` (default) 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;
+    /** Atlas leaf CSS primitive sizing. Defaults to scene context, then canonical. */
+    textureLeafSizing?: PolyTextureLeafSizing;
+    /** Default image filtering for atlas and direct image texture leaves. */
+    textureImageRendering?: PolyTextureImageRendering;
+    /** Default texture backend request. Defaults to scene context, then "auto". */
+    textureBackend?: PolyTextureBackend;
+    /** Default texture projection request. Defaults to scene context, then "affine". */
+    textureProjection?: PolyTextureProjection;
+    /** Solid seam overscan. `"auto"` computes a fitted per-edge amount from the polygon plan. */
+    seamBleed?: PolySeamBleed;
+    /**
+     * Hold the whole previous frame (geometry + texture) until the next atlas is
+     * decoded, then swap atomically — so a geometry edit never shows geometry
+     * before its texture. Best when edits arrive as discrete commits (no
+     * continuous drag). Defaults to false (bitmap streams in over live geometry).
+     */
+    atomicAtlas?: boolean;
+    /** Fires when the displayed atlas frame swaps to a ready one (atomic mode). */
+    onFrameReady?: () => void;
+    /** Per-polygon override render, or static children mounted inside the mesh wrapper. */
+    children?: ((polygon: Polygon, index: number) => ReactNode) | ReactNode;
+    /** Loading slot — rendered while `src` is being fetched/parsed. */
+    fallback?: ReactNode;
+    /** Error slot — rendered if parse fails. Receives the Error. */
+    errorFallback?: (error: Error) => ReactNode;
+    /** Parser options forwarded to parseObj/parseGltf. */
+    parseOptions?: UseMeshOptions;
+    /** Mesh optimization intent. Defaults to "lossy"; set "lossless" to keep
+     *  authored surface fidelity. Top-level prop wins over `parseOptions.meshResolution`
+     *  when both are present. */
+    meshResolution?: MeshResolution;
+    /**
+     * When `true`, emits a per-mesh SVG shadow path in both lighting modes.
+     * Each casting polygon projects onto the scene ground plane along the
+     * directional light; overlapping outlines are merged into one silhouette.
+     * Defaults to `false`.
+     */
+    castShadow?: boolean;
+    /**
+     * When `true`, this mesh acts as a shadow receiver. The scene's caster
+     * meshes (those with `castShadow=true`) project per-coplanar-face SVG
+     * shadows onto each visible surface of this mesh, matching Three.js's
+     * `mesh.receiveShadow` semantics. Disables the ground-shadow fallback
+     * for caster meshes — receivers handle shadow display. Defaults to `false`.
+     */
+    receiveShadow?: boolean;
+    /**
+     * Per-mesh parametric-shadow detail, overriding the scene's
+     * `shadow.definition` for this mesh's cast/self shadow. Only used when the
+     * scene's `shadow.parametric` is true. Unset → inherit the scene definition.
+     */
+    shadowDefinition?: number;
+    /**
+     * Apply mesh optimization (coplanar merge + interior cull) before
+     * rendering. Defaults to `true` — matches vanilla `scene.add`'s default.
+     * Set `false` for helper meshes (axes, light markers) whose geometry
+     * shouldn't be merged, or when the imperative `updatePolygon` API needs
+     * polygon refs to survive across updates.
+     */
+    merge?: boolean;
+    className?: string;
+    style?: CSSProperties;
+}
+declare const PolyMesh: React.ForwardRefExoticComponent<PolyMeshProps & React.RefAttributes<PolyMeshHandle>>;
+
+export { type DOMPassthroughProps as D, type InteractionProps as I, type PolyProps as P, type TransformProps as T, type UseMeshOptions as U, type PolyMeshProps as a, type PolyMeshHandle as b, type PolyEventHandler as c, PolyMesh as d, type PolyMouseEvent as e, type PolyPointerEvent as f, type PolyWheelEvent as g, type UseMeshResult as h, findMeshUnderPoint as i, findPolyMeshHandle as j, pointInMeshElement as p, usePolyMesh as u };