@layoutit/polycss-vue 0.2.0 → 0.2.2

package/README.md

@@ -1,188 +1,202 @@
-> **Status: pre-1.0. APIs may still change before a stable 1.0 release.**
+# PolyCSS
 
-# @layoutit/polycss-vue
+A CSS polygon mesh library. A 3D engine for the DOM. Renders OBJ/MTL, STL, glTF/GLB, and VOX as real HTML elements transformed with CSS `matrix3d(...)`. Supports colors, textures, lighting, shadows, shapes and animations. Works with React, Vue or plain JavaScript.
 
-Native Vue 3 components for CSS-based polygon mesh rendering. Loads OBJ, glTF, GLB, and MagicaVoxel `.vox` files; renders each polygon as a real DOM element (atlas-backed `<i>` for both textured and flat-color faces) positioned with `transform: matrix3d(...)`. No WebGL, no canvas-as-scene.
+Visit [polycss.com](https://polycss.com) for docs and model examples.
 
-## Install
+<img width="1600" height="300" alt="PolyCSS primitives banner" src="https://github.com/user-attachments/assets/b05e2204-9323-4f83-8d1b-01ea0dd000db" />
+
+## Installation
 
 ```bash
-npm install @layoutit/polycss-vue
-```
 
-Requires Vue 3 as a peer dependency.
+# Vanilla
+npm install @layoutit/polycss
 
-## Quickstart
+# React
+npm install @layoutit/polycss-react
 
-```vue
-<template>
-  <PolyCamera :rot-x="65" :rot-y="45" :perspective="1000">
-    <PolyScene>
-      <PolyMesh src="/cottage.glb" />
-    </PolyScene>
-  </PolyCamera>
-</template>
+# Vue
+npm install @layoutit/polycss-vue
 
-<script setup lang="ts">
-import { PolyCamera, PolyScene, PolyMesh } from "@layoutit/polycss-vue";
-</script>
 ```
 
-## Component reference
 
-### `<PolyScene>`
+You can also load PolyCSS directly from a CDN. Here is a minimal custom-element scene:
 
-Root of every Vue polycss render tree. Renders polygons and meshes inside a `<PolyCamera>` context, and owns scene-level lighting and atlas options.
+```html
+<script type="module" src="https://esm.sh/@layoutit/polycss/elements"></script>
 
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `directional-light` | `PolyDirectionalLight` | None | Directional light config |
-| `ambient-light` | `PolyAmbientLight` | None | Ambient light config |
-| `texture-lighting` | `"baked" \| "dynamic"` | `"baked"` | Texture lighting mode |
-| `atlas-scale` | `number \| "auto"` | `"auto"` | Atlas bitmap budget and compositor sprite size |
-| `polygons` | `Polygon[]` | None | Static polygon array (composes with slot) |
+<poly-camera rot-x="65" rot-y="45">
+  <poly-scene>
+    <poly-orbit-controls drag wheel></poly-orbit-controls>
+    <poly-box size="100" color="#ffd166"></poly-box>
+  </poly-scene>
+</poly-camera>
+```
 
-For pointer drag, wheel zoom, and autorotate, mount `<PolyOrbitControls>` (or `<PolyMapControls>` for pan-first map-style input) inside `<PolyCamera>`: it receives the camera context. Mirrors Three.js's split between camera state and input.
+<img width="2500" height="1145" alt="PolyCSS intro" src="https://github.com/user-attachments/assets/0e5df0d8-04a8-4e50-8e3a-1097a96ce42f" />
 
-### `<PolyMesh>`
+## Framework Components
 
-Loads a mesh from a URL and renders its polygons. Manages blob-URL lifecycle automatically.
+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.
 
-| Prop | Type | Description |
-|---|---|---|
-| `src` | `string` | URL to `.obj`, `.glb`, `.gltf`, or `.vox` |
-| `polygons` | `Polygon[]` | Pre-parsed polygons (alternative to `src`) |
-| `position` | `Vec3` | `[x, y, z]` offset in scene space |
-| `scale` | `number \| Vec3` | Uniform or per-axis scale |
-| `rotation` | `Vec3` | Euler angles in degrees `[x, y, z]` |
-| `atlas-scale` | `number \| "auto"` | Atlas bitmap budget and compositor sprite size |
-| `auto-center` | `boolean` | Shift mesh so its bbox center is at origin |
-| `mtl` | `string` | Companion `.mtl` URL for OBJ models |
+```tsx
+import { PolyCamera, PolyScene, PolyOrbitControls, PolyMesh } from "@layoutit/polycss-react";
 
-Named slot: `#polygon="{ polygon, index }"`: per-polygon scoped slot for rendering overrides. The default slot is for static children inside the mesh wrapper.
+export default function App() {
+  return (
+    <PolyCamera rotX={65} rotY={45}>
+      <PolyScene textureLighting="dynamic">
+        <PolyOrbitControls drag wheel />
+        <PolyMesh src="/gallery/obj/cottage.obj" mtl="/gallery/obj/cottage.mtl" />
+      </PolyScene>
+    </PolyCamera>
+  );
+}
+```
 
-### `<Poly>`
+## API Reference
 
-Single polygon. Renders one atlas-backed `<i>` for UV-textured and flat-color faces. Accepts standard Vue event bindings and class/style.
+### PolyCamera
 
-| Prop | Type | Description |
-|---|---|---|
-| `vertices` | `Vec3[]` | Required: 3+ `[x, y, z]` points |
-| `color` | `string` | CSS color; used when no texture is set |
-| `texture` | `string` | Image URL for UV-mapped rendering |
-| `uvs` | `Vec2[]` | UV coordinates, one per vertex |
-| `data` | `Record<string, string \| number \| boolean>` | Reflected as `data-*` DOM attributes |
-| `position` | `Vec3` | Local offset |
-| `scale` | `number \| Vec3` | Scale |
-| `rotation` | `Vec3` | Euler rotation in degrees |
-| `atlas-scale` | `number \| "auto"` | Atlas bitmap budget and compositor sprite size |
+- `rotX`, `rotY` control the orbit angle in degrees.
+- `zoom` scales the projected scene.
+- `target` pans the camera target in world coordinates.
+- `distance` adds dolly pull-back.
+- `PolyCamera` is the orthographic default. Use `PolyPerspectiveCamera` when you want perspective depth.
 
-### `<PolyCamera>`
+### PolyScene
 
-Camera wrapper for perspective, rotation, zoom, target, and dolly distance. Vue scenes must render inside `<PolyCamera>` (or `<PolyPerspectiveCamera>` / `<PolyOrthographicCamera>`) so controls and scenes share camera state.
+- `polygons` renders a static `Polygon[]` directly.
+- `directionalLight` and `ambientLight` control scene lighting.
+- `textureLighting` chooses `"baked"` or `"dynamic"`.
+- `textureQuality` controls atlas raster budget.
+- `strategies` can disable selected render strategies for diagnostics.
+- `autoCenter` rotates around the rendered mesh bounds instead of world origin.
 
-### Composables
+### PolyMesh
 
-| Composable | Description |
-|---|---|
-| `usePolyCamera(options)` | Internal camera integration composable |
-| `usePolySceneContext(polygons, options)` | Lower-level hook for custom scene wrappers |
-| `usePolyMesh(srcRef, options?)` | Reactive mesh loader. Returns reactive `{ polygons, loading, error, warnings, dispose }`. |
+- `src` loads `.obj`, `.gltf`, `.glb`, or `.vox` files.
+- `mtl` loads companion OBJ materials.
+- `polygons` accepts pre-parsed geometry.
+- `position`, `scale`, and `rotation` transform the mesh wrapper.
+- `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.
 
-### Utility
+### Controls
 
-| Export | Description |
-|---|---|
-| `injectPolyBaseStyles(doc?)` | Inject polycss base CSS into the document. Idempotent. |
+- `<PolyOrbitControls>` adds drag orbit, shift-drag pan, wheel zoom, and optional auto-rotate.
+- `<PolyMapControls>` uses pan-first map-style input.
+- `<PolyFirstPersonControls>` provides keyboard and pointer-look navigation.
+- `<PolyTransformControls>` adds translate/rotate gizmos for selected mesh handles.
 
-## Re-exports from `@layoutit/polycss-core`
+### Snapshot Export
 
-All types and core functions are re-exported:
+The vanilla package exports `exportPolySceneSnapshot(target)`. It clones the current rendered `.polycss-camera` / `.polycss-scene` DOM, injects only the PolyCSS CSS needed by that snapshot, inlines CSS `url(...)` image assets as `data:image/...;base64,...`, strips scripts and inline event handlers, and returns a standalone HTML document string with no PolyCSS runtime import. It works with rendered React/Vue scenes too; import it from `@layoutit/polycss` and pass the rendered camera or scene element.
 
 ```ts
-import type { Polygon, Vec2, Vec3, PolyDirectionalLight, PolyAmbientLight, ParseResult } from "@layoutit/polycss-vue";
-import { parseObj, parseGltf, parseVox, loadMesh, normalizePolygons, mergePolygons } from "@layoutit/polycss-vue";
+import { exportPolySceneSnapshot } from "@layoutit/polycss";
+
+const html = await exportPolySceneSnapshot(scene.host);
 ```
 
-## Examples
+If any referenced asset cannot be inlined, the function throws `PolySceneSnapshotError` with `code: "ASSET_INLINE_FAILED"`.
 
-### With lighting and multiple meshes
+### Polygon Data Model
 
-```vue
-<template>
-  <PolyCamera :rot-x="65" :rot-y="45">
-    <PolyScene :directional-light="light">
-      <PolyMesh src="/cottage.glb" />
-      <PolyMesh src="/tree.glb" :position="[8, 0, 0]" :scale="0.5" />
-    </PolyScene>
-  </PolyCamera>
-</template>
+Each polygon describes one renderable face:
 
-<script setup lang="ts">
-import { PolyCamera, PolyScene, PolyMesh } from "@layoutit/polycss-vue";
-const light = { direction: [0.5, -0.7, 0.6] as [number, number, number], color: "#ffe4a8" };
-</script>
+```ts
+const polygons = [
+  {
+    vertices: [[0, 0, 0], [60, 0, 0], [0, 60, 0]],
+    color: "#f97316",
+  },
+  {
+    vertices: [[0, 0, 0], [60, 0, 0], [60, 60, 0], [0, 60, 0]],
+    texture: "/texture.png",
+    uvs: [[0, 0], [1, 0], [1, 1], [0, 1]],
+  },
+];
 ```
 
-### Per-polygon interactive
+Render polygons directly when you need per-face DOM events or custom styling:
 
-```vue
-<template>
-  <PolyCamera :rot-x="65" :rot-y="45">
-    <PolyScene>
+```tsx
+<PolyCamera>
+  <PolyScene>
+    {polygons.map((polygon, index) => (
       <Poly
-        v-for="(p, i) in polygons"
-        :key="i"
-        v-bind="p"
-        @click="() => alert(`clicked polygon ${i}`)"
-        @mouseenter="hoveredId = i"
-        @mouseleave="hoveredId = null"
-        :class="{ highlight: hoveredId === i }"
+        key={index}
+        {...polygon}
+        onClick={() => console.log("clicked polygon", index)}
+        className="my-polygon"
       />
-    </PolyScene>
-  </PolyCamera>
-</template>
-
-<script setup lang="ts">
-import { ref } from "vue";
-import { PolyCamera, PolyScene, Poly } from "@layoutit/polycss-vue";
-import type { Polygon } from "@layoutit/polycss-vue";
-
-defineProps<{ polygons: Polygon[] }>();
-const hoveredId = ref<number | null>(null);
-</script>
-
-<style>
-.highlight { filter: brightness(1.5); }
-</style>
+    ))}
+  </PolyScene>
+</PolyCamera>
 ```
 
-### `PolyMesh` with scoped slot
-
-```vue
-<template>
-  <PolyCamera :rot-x="65" :rot-y="45">
-    <PolyScene>
-      <PolyMesh src="/character.glb" :position="[5, 0, 0]" :scale="2">
-        <template #polygon="{ polygon, index }">
-          <Poly
-            v-bind="polygon"
-            @click="selected = index"
-            :class="{ outlined: selected === index }"
-          />
-        </template>
-      </PolyMesh>
-    </PolyScene>
-  </PolyCamera>
-</template>
-
-<script setup lang="ts">
-import { ref } from "vue";
-import { PolyCamera, PolyScene, PolyMesh, Poly } from "@layoutit/polycss-vue";
-const selected = ref<number | null>(null);
-</script>
+## Loading Mesh Files
+
+Use `loadMesh()` to parse supported model formats:
+
+```ts
+import { createPolyCamera, createPolyScene, loadMesh } from "@layoutit/polycss";
+
+const host = document.getElementById("polycss")!;
+const camera = createPolyCamera({ rotX: 65, rotY: 45 });
+const scene = createPolyScene(host, { camera });
+
+const mesh = await loadMesh("https://polycss.com/gallery/obj/cottage.obj", {
+  mtlUrl: "https://polycss.com/gallery/obj/cottage.mtl",
+});
+
+scene.add(mesh);
 ```
 
-## Docs
+Supported formats:
+
+- OBJ + MTL, including `map_Kd` textures and UV coordinates.
+- STL triangle meshes, including binary Magics face colors. STL has no standard units, textures, UVs, or hierarchy, so imports skip lossy simplification and ray-based interior culling.
+- glTF / GLB, including embedded images and `TEXCOORD_0`.
+- MagicaVoxel `.vox`, with direct voxel fast paths when eligible.
+- Generated primitives: box, plane, ring, sphere, torus, cylinder, cone, and Platonic solids.
+
+## Performance
+
+PolyCSS renders through the DOM, so performance is mostly shaped by two things: the number of mounted leaves, and the amount of texture atlas area the browser has to paint. The renderer tries to keep the common cases cheap. Simple surfaces stay as solid CSS elements, while textured, irregular, or high-detail geometry falls back to atlas-backed slices only when needed.
+
+Each visible polygon is emitted as one leaf element; the renderer chooses the least expensive CSS primitive that can represent the polygon, then uses `matrix3d(...)` to place that primitive in 3D space.
+
+- `<b>` uses `background: currentColor` on a fixed box for solid rectangles and stable quads.
+- `<u>` uses `corner-shape` for stable triangles and beveled-corner solids, with a `border-width` triangle fallback when needed.
+- `<i>` clips solid polygons with `border-shape: polygon(...)` when the browser supports it.
+- `<s>` maps a packed texture-atlas slice with `background-image`, and is the fallback for textured or unsupported shapes.
+
+## Packages
+
+| Package | Description |
+|---|---|
+| `@layoutit/polycss-core` | Pure math, parsers, lighting, camera helpers, mesh optimization. Zero browser globals. |
+| `@layoutit/polycss` | Vanilla custom elements and imperative `createPolyScene` API. |
+| `@layoutit/polycss-react` | React components, hooks, controls, and core re-exports. |
+| `@layoutit/polycss-vue` | Vue 3 components, composables, controls, and core re-exports. |
+
+## Made with PolyCSS
+
+[Layoutit Voxels](https://voxels.layoutit.com)
+-> A CSS Voxel editor
+
+<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
+
+<img width="1000" height="601" alt="layoutit-terra" src="https://polycss.com/layoutit-terra.png" />
+
+## License
 
-Full documentation at [polycss.com](https://polycss.com).
+MIT.