@es3d/es3d 0.0.0-stage → 1.0.0

package/docs/REFERENCE.md

@@ -0,0 +1,581 @@
+# ES3D element reference
+
+<!-- Generated by `npm run docs:reference` from src/format/schema.js. Do not edit by hand. -->
+
+Every element and attribute of ES3D version 1 as implemented by the reference reader. Semantics are described in [SPEC.md](SPEC.md).
+Unknown attributes and elements are errors (with a "did you mean" suggestion); elements whose name starts with `x-` are vendor extensions and are skipped with a warning.
+
+## Common attributes
+
+Scene nodes (shapes, containers, `<use>`, `<scene>`) accept these placement and style attributes in addition to their own. The local transform is `transform · T(position) · R(rotation) · S(scale)`.
+
+| Attribute | Alias | Type | Default | Range | Description |
+|---|---|---|---|---|---|
+| `id` |  | id |  |  | Unique identifier, referenced by &lt;use ref&gt;, material="…" and path="…". |
+| `name` |  | string |  |  | Human readable label shown in tools. |
+| `transform` | `t` | transform |  |  | SVG-style transform list; applied outside position/rotation/scale. |
+| `position` | `p` | vec3 | `0,0,0` |  | Translation x,y,z. |
+| `rotation` | `rot` | vec3 | `0,0,0` |  | Euler angles in degrees, applied about X, then Y, then Z. |
+| `scale` | `sc` | scale3 | `1,1,1` |  | Uniform scale or x,y,z. |
+| `visible` |  | bool | `true` |  | When false the element and its children are not rendered. |
+| `material` | `m` | ref → material |  |  | Material id. Inherited by descendants, like SVG fill. |
+| `color` | `c` | color |  |  | Base colour override. Inherited by descendants. |
+
+## Document structure
+
+### `<es3d>`
+
+Root element of an ES3D document.
+
+Children: `<title>`, `<desc>`, `<defs>`, `<scene>`, `<environment>`, `<controls>`, `<box>`, `<sphere>`, `<cylinder>`, `<cone>`, `<capsule>`, `<plane>`, `<torus>`, `<line>`, `<polyline>`, `<polygon>`, `<path>`, `<extrude>`, `<revolve>`, `<sweep>`, `<gear>`, `<mesh>`, `<group>`, `<repeat>`, `<scatter>`, `<lod>`, `<use>`, `<light>`, `<camera>`, `<material>`.
+
+Attributes:
+
+| Attribute | Alias | Type | Default | Range | Description |
+|---|---|---|---|---|---|
+| `version` **(required)** |  | string |  |  | Format version; this implementation reads version 1. |
+| `unit` |  | `m` \| `cm` \| `mm` \| `km` \| `in` \| `ft` | `m` |  | Length unit (informative). |
+| `xmlns` |  | string |  |  | Optional. Ignored if present. A namespace is not required. |
+| `name` |  | string |  |  | Human readable label shown in tools. |
+
+### `<title>`
+
+Document title.
+
+Children: text content.
+
+No attributes.
+
+### `<desc>`
+
+Free text description.
+
+Children: text content.
+
+No attributes.
+
+### `<defs>`
+
+Definitions that are not rendered directly; referenced with &lt;use ref&gt;.
+
+Children: `<box>`, `<sphere>`, `<cylinder>`, `<cone>`, `<capsule>`, `<plane>`, `<torus>`, `<line>`, `<polyline>`, `<polygon>`, `<path>`, `<extrude>`, `<revolve>`, `<sweep>`, `<gear>`, `<mesh>`, `<group>`, `<repeat>`, `<scatter>`, `<lod>`, `<use>`, `<light>`, `<camera>`, `<material>`.
+
+No attributes.
+
+### `<scene>`
+
+Optional wrapper for scene content; behaves like a group.
+
+Children: `<box>`, `<sphere>`, `<cylinder>`, `<cone>`, `<capsule>`, `<plane>`, `<torus>`, `<line>`, `<polyline>`, `<polygon>`, `<path>`, `<extrude>`, `<revolve>`, `<sweep>`, `<gear>`, `<mesh>`, `<group>`, `<repeat>`, `<scatter>`, `<lod>`, `<use>`, `<light>`, `<camera>`, `<material>`, `<environment>`, `<controls>`.
+
+Accepts the common attributes, plus:
+
+| Attribute | Alias | Type | Default | Range | Description |
+|---|---|---|---|---|---|
+| `collide` |  | bool | `true` |  | When false the camera may pass through the element and its children (see &lt;controls collide&gt;). |
+
+### `<environment>`
+
+Background and ambient (hemisphere) lighting.
+
+Children: none.
+
+Attributes:
+
+| Attribute | Alias | Type | Default | Range | Description |
+|---|---|---|---|---|---|
+| `background` |  | color | `#171a1f` |  | Clear colour. |
+| `sky` |  | color | `#ccdbf2` |  | Ambient light colour from above. |
+| `ground` |  | color | `#403833` |  | Ambient light colour from below. |
+| `intensity` |  | number | `0.5` | ≥ 0 | Ambient / environment intensity. |
+| `exposure` |  | number | `1` | > 0 | Tone mapping exposure. |
+
+## Materials
+
+### `<material>`
+
+Minimal physically based material (metallic/roughness).
+
+Children: none.
+
+Attributes:
+
+| Attribute | Alias | Type | Default | Range | Description |
+|---|---|---|---|---|---|
+| `id` |  | id |  |  | Unique identifier, referenced by &lt;use ref&gt;, material="…" and path="…". |
+| `name` |  | string |  |  | Human readable label shown in tools. |
+| `color` | `c` | color | `#ccc` |  | Base colour (sRGB). |
+| `metallic` |  | number | `0` | ≥ 0, ≤ 1 | 0 = dielectric, 1 = metal. |
+| `roughness` |  | number | `0.5` | ≥ 0, ≤ 1 | 0 = mirror, 1 = fully rough. |
+| `opacity` |  | number | `1` | ≥ 0, ≤ 1 | Alpha; values below 1 are blended. |
+| `emissive` |  | color | `#000` |  | Emitted colour. |
+| `emissiveIntensity` |  | number | `1` | ≥ 0 | Multiplier for emissive. |
+| `map` |  | texture |  |  | Base colour texture: image URL or checker(), grid(), stripes(), noise(), bricks(). |
+| `normalMap` |  | normalTexture |  |  | Normal map: image URL or bumps(), tiles(), noise(), waves(), bricks(). |
+| `normalScale` |  | number | `1` |  | Normal map strength. |
+| `uvScale` |  | vec2 | `1,1` |  | Texture repeat in u and v. |
+| `doubleSided` |  | bool | `false` |  | Render back faces too. |
+| `unlit` |  | bool | `false` |  | Ignore lighting; output the base colour. |
+| `occlusionMap` |  | texture |  |  | Occlusion texture. The red channel darkens indirect light. Image URL or a procedural texture. |
+| `occlusionStrength` |  | number | `1` | ≥ 0, ≤ 1 | Strength of occlusionMap. 0 disables it, 1 uses the texture as stored. |
+| `metallicRoughnessMap` |  | texture |  |  | Packed texture: green multiplies roughness, blue multiplies metallic. |
+| `emissiveMap` |  | texture |  |  | sRGB texture multiplied with emissive. |
+| `alphaMode` |  | `auto` \| `opaque` \| `mask` \| `blend` | `auto` |  | auto blends when opacity is below 1 and is opaque otherwise. mask discards fragments below alphaCutoff. blend uses opacity as coverage. opaque ignores alpha. |
+| `alphaCutoff` |  | number | `0.5` | ≥ 0, ≤ 1 | Mask threshold. |
+
+## Containers and instancing
+
+### `<group>`
+
+Groups children under a common transform and style.
+
+Children: `<box>`, `<sphere>`, `<cylinder>`, `<cone>`, `<capsule>`, `<plane>`, `<torus>`, `<line>`, `<polyline>`, `<polygon>`, `<path>`, `<extrude>`, `<revolve>`, `<sweep>`, `<gear>`, `<mesh>`, `<group>`, `<repeat>`, `<scatter>`, `<lod>`, `<use>`, `<light>`, `<camera>`, `<material>`, `<animate>`.
+
+Accepts the common attributes, plus:
+
+| Attribute | Alias | Type | Default | Range | Description |
+|---|---|---|---|---|---|
+| `collide` |  | bool | `true` |  | When false the camera may pass through the element and its children (see &lt;controls collide&gt;). |
+
+### `<repeat>`
+
+Repeats its children count times; copy i is transformed by step applied i times.
+
+Children: `<box>`, `<sphere>`, `<cylinder>`, `<cone>`, `<capsule>`, `<plane>`, `<torus>`, `<line>`, `<polyline>`, `<polygon>`, `<path>`, `<extrude>`, `<revolve>`, `<sweep>`, `<gear>`, `<mesh>`, `<group>`, `<repeat>`, `<scatter>`, `<lod>`, `<use>`, `<light>`, `<camera>`, `<material>`, `<animate>`.
+
+Accepts the common attributes, plus:
+
+| Attribute | Alias | Type | Default | Range | Description |
+|---|---|---|---|---|---|
+| `collide` |  | bool | `true` |  | When false the camera may pass through the element and its children (see &lt;controls collide&gt;). |
+| `count` **(required)** | `n` | int |  | ≥ 0, ≤ 1000000 | Number of copies. |
+| `step` **(required)** |  | transform |  |  | Transform applied cumulatively between copies. |
+
+### `<scatter>`
+
+Deterministic pseudo-random or grid placement of its children (seeded mulberry32).
+
+Children: `<box>`, `<sphere>`, `<cylinder>`, `<cone>`, `<capsule>`, `<plane>`, `<torus>`, `<line>`, `<polyline>`, `<polygon>`, `<path>`, `<extrude>`, `<revolve>`, `<sweep>`, `<gear>`, `<mesh>`, `<group>`, `<repeat>`, `<scatter>`, `<lod>`, `<use>`, `<light>`, `<camera>`, `<material>`, `<animate>`.
+
+Accepts the common attributes, plus:
+
+| Attribute | Alias | Type | Default | Range | Description |
+|---|---|---|---|---|---|
+| `collide` |  | bool | `true` |  | When false the camera may pass through the element and its children (see &lt;controls collide&gt;). |
+| `count` | `n` | int |  | ≥ 0, ≤ 1000000 | Number of random copies (random layout). |
+| `grid` |  | count2 |  |  | Grid layout nx,nz (instead of count). |
+| `spacing` |  | vec2 | `1,1` |  | Grid cell size x,z. |
+| `area` |  | size2 |  |  | Random layout: rectangle width,depth centred at the origin (XZ plane). |
+| `radius` |  | number |  | > 0 | Random layout: disc radius (XZ plane). |
+| `seed` |  | int | `1` | ≥ 0 | Random seed. |
+| `jitter` |  | number | `0` | ≥ 0, ≤ 1 | Grid layout: random offset as a fraction of the cell. |
+| `randomScale` |  | range3 |  |  | Per-copy scale: a range (uniform, e.g. 0.8..1.2) or x,y,z ranges. |
+| `randomRotation` |  | range3 |  |  | Per-copy Euler ranges in degrees, e.g. 0,0..360,0. |
+| `randomMaterial` |  | ids → material |  |  | Per-copy material chosen from this list of ids. |
+
+### `<lod>`
+
+Level of detail switch: child i is shown while the camera distance is below distances[i].
+
+Children: `<box>`, `<sphere>`, `<cylinder>`, `<cone>`, `<capsule>`, `<plane>`, `<torus>`, `<line>`, `<polyline>`, `<polygon>`, `<path>`, `<extrude>`, `<revolve>`, `<sweep>`, `<gear>`, `<mesh>`, `<group>`, `<repeat>`, `<scatter>`, `<lod>`, `<use>`, `<light>`, `<camera>`, `<material>`, `<animate>`.
+
+Accepts the common attributes, plus:
+
+| Attribute | Alias | Type | Default | Range | Description |
+|---|---|---|---|---|---|
+| `collide` |  | bool | `true` |  | When false the camera may pass through the element and its children (see &lt;controls collide&gt;). |
+| `distances` **(required)** |  | numbers |  |  | Increasing switch distances; one fewer than the number of children. |
+
+### `<use>`
+
+Instantiates the element with the given id (like SVG &lt;use&gt;).
+
+Children: `<animate>`.
+
+Accepts the common attributes, plus:
+
+| Attribute | Alias | Type | Default | Range | Description |
+|---|---|---|---|---|---|
+| `collide` |  | bool | `true` |  | When false the camera may pass through the element and its children (see &lt;controls collide&gt;). |
+| `ref` **(required)** | `href` | ref → node |  |  | Id of the element to instantiate. |
+
+## Shapes
+
+### `<box>`
+
+Axis aligned box centred at the origin, optionally with rounded edges.
+
+Children: `<animate>`.
+
+Accepts the common attributes, plus:
+
+| Attribute | Alias | Type | Default | Range | Description |
+|---|---|---|---|---|---|
+| `collide` |  | bool | `true` |  | When false the camera may pass through the element and its children (see &lt;controls collide&gt;). |
+| `size` | `s` | size3 | `1,1,1` |  | Edge lengths (one value for a cube). |
+| `radius` | `r` | number | `0` | ≥ 0 | Edge rounding radius. |
+| `segments` |  | int |  | ≥ 1, ≤ 32 | Rounding segments (automatic when omitted). |
+
+### `<sphere>`
+
+Sphere centred at the origin.
+
+Children: `<animate>`.
+
+Accepts the common attributes, plus:
+
+| Attribute | Alias | Type | Default | Range | Description |
+|---|---|---|---|---|---|
+| `collide` |  | bool | `true` |  | When false the camera may pass through the element and its children (see &lt;controls collide&gt;). |
+| `radius` | `r` | number | `0.5` | > 0 | Radius. |
+| `segments` |  | int |  | ≥ 3, ≤ 512 | Fixed tessellation (automatic level of detail when omitted). |
+
+### `<cylinder>`
+
+Cylinder (or truncated cone) along Y, centred at the origin.
+
+Children: `<animate>`.
+
+Accepts the common attributes, plus:
+
+| Attribute | Alias | Type | Default | Range | Description |
+|---|---|---|---|---|---|
+| `collide` |  | bool | `true` |  | When false the camera may pass through the element and its children (see &lt;controls collide&gt;). |
+| `radius` | `r` | number | `0.5` | > 0 | Bottom radius (and top radius unless radiusTop is set). |
+| `radiusTop` |  | number |  | ≥ 0 | Top radius. |
+| `height` | `h` | number | `1` | > 0 | Height. |
+| `segments` |  | int |  | ≥ 3, ≤ 512 | Fixed number of sides, e.g. 6 for a hexagonal prism. |
+| `caps` |  | bool | `true` |  | Close the ends. |
+
+### `<cone>`
+
+Cone along Y with its base at -height/2 and apex at +height/2.
+
+Children: `<animate>`.
+
+Accepts the common attributes, plus:
+
+| Attribute | Alias | Type | Default | Range | Description |
+|---|---|---|---|---|---|
+| `collide` |  | bool | `true` |  | When false the camera may pass through the element and its children (see &lt;controls collide&gt;). |
+| `radius` | `r` | number | `0.5` | > 0 | Base radius. |
+| `height` | `h` | number | `1` | > 0 | Height. |
+| `segments` |  | int |  | ≥ 3, ≤ 512 | Fixed number of sides. |
+| `caps` |  | bool | `true` |  | Close the base. |
+
+### `<capsule>`
+
+Capsule along Y; height is the total height including both caps.
+
+Children: `<animate>`.
+
+Accepts the common attributes, plus:
+
+| Attribute | Alias | Type | Default | Range | Description |
+|---|---|---|---|---|---|
+| `collide` |  | bool | `true` |  | When false the camera may pass through the element and its children (see &lt;controls collide&gt;). |
+| `radius` | `r` | number | `0.25` | > 0 | Radius. |
+| `height` | `h` | number | `1` | > 0 | Total height (at least 2 × radius). |
+| `segments` |  | int |  | ≥ 3, ≤ 512 | Fixed tessellation. |
+
+### `<plane>`
+
+Flat rectangle in the XZ plane facing +Y (rendered double sided).
+
+Children: `<animate>`.
+
+Accepts the common attributes, plus:
+
+| Attribute | Alias | Type | Default | Range | Description |
+|---|---|---|---|---|---|
+| `collide` |  | bool | `true` |  | When false the camera may pass through the element and its children (see &lt;controls collide&gt;). |
+| `size` | `s` | size2 | `1,1` |  | Width (x) and depth (z). |
+
+### `<torus>`
+
+Torus around the Y axis.
+
+Children: `<animate>`.
+
+Accepts the common attributes, plus:
+
+| Attribute | Alias | Type | Default | Range | Description |
+|---|---|---|---|---|---|
+| `collide` |  | bool | `true` |  | When false the camera may pass through the element and its children (see &lt;controls collide&gt;). |
+| `radius` | `r` | number | `0.35` | > 0 | Distance from the centre to the tube centre. |
+| `tube` |  | number | `0.15` | > 0 | Tube radius. |
+| `arc` |  | angle | `360` | > 0, ≤ 360 | Swept angle in degrees (partial torus / pipe elbow). |
+| `segments` |  | int |  | ≥ 3, ≤ 1024 | Fixed segments around the ring. |
+| `tubeSegments` |  | int |  | ≥ 3, ≤ 512 | Fixed segments around the tube. |
+
+### `<line>`
+
+Straight line segment; rendered as a tube when radius &gt; 0.
+
+Children: `<animate>`.
+
+Accepts the common attributes, plus:
+
+| Attribute | Alias | Type | Default | Range | Description |
+|---|---|---|---|---|---|
+| `collide` |  | bool | `true` |  | When false the camera may pass through the element and its children (see &lt;controls collide&gt;). |
+| `from` **(required)** |  | vec3 |  |  | Start point. |
+| `to` **(required)** |  | vec3 |  |  | End point. |
+| `radius` | `r` | number | `0` | ≥ 0 | Tube radius (0 = hairline). |
+| `segments` |  | int |  | ≥ 3, ≤ 256 | Tube sides. |
+
+### `<polyline>`
+
+3D polyline or 2D path outline; rendered as a tube when radius &gt; 0.
+
+Children: `<animate>`.
+
+Accepts the common attributes, plus:
+
+| Attribute | Alias | Type | Default | Range | Description |
+|---|---|---|---|---|---|
+| `collide` |  | bool | `true` |  | When false the camera may pass through the element and its children (see &lt;controls collide&gt;). |
+| `points` |  | points3 |  |  | x,y,z x,y,z … |
+| `d` |  | path2d |  |  | Outline of 2D path data in the XY plane (alternative to points). |
+| `closed` |  | bool | `false` |  | Connect the last point to the first. |
+| `smooth` |  | bool | `false` |  | Interpolate the points with a Catmull-Rom spline. |
+| `radius` | `r` | number | `0` | ≥ 0 | Tube radius (0 = hairline). |
+| `segments` |  | int |  | ≥ 3, ≤ 256 | Tube sides. |
+
+### `<polygon>`
+
+Filled flat polygon in the XY plane (rendered double sided).
+
+Children: `<animate>`.
+
+Accepts the common attributes, plus:
+
+| Attribute | Alias | Type | Default | Range | Description |
+|---|---|---|---|---|---|
+| `collide` |  | bool | `true` |  | When false the camera may pass through the element and its children (see &lt;controls collide&gt;). |
+| `points` **(required)** |  | points2 |  |  | x,y x,y … (at least 3 points). |
+
+### `<path>`
+
+Filled flat 2D path in the XY plane (rendered double sided). In &lt;defs&gt; it is a reusable outline.
+
+Children: `<animate>`.
+
+Accepts the common attributes, plus:
+
+| Attribute | Alias | Type | Default | Range | Description |
+|---|---|---|---|---|---|
+| `collide` |  | bool | `true` |  | When false the camera may pass through the element and its children (see &lt;controls collide&gt;). |
+| `d` |  | path2d |  |  | SVG path data in the local XY plane (y up): M L H V C S Q T A Z. |
+| `path` |  | ref → path |  |  | Id of a &lt;path&gt; element whose d is used. |
+| `fillRule` |  | `nonzero` \| `evenodd` | `nonzero` |  | How nested contours become holes (SVG fill-rule). |
+
+### `<extrude>`
+
+Extrudes a 2D path along +Z, optionally with a rounded bevel.
+
+Children: `<animate>`.
+
+Accepts the common attributes, plus:
+
+| Attribute | Alias | Type | Default | Range | Description |
+|---|---|---|---|---|---|
+| `collide` |  | bool | `true` |  | When false the camera may pass through the element and its children (see &lt;controls collide&gt;). |
+| `d` |  | path2d |  |  | SVG path data in the local XY plane (y up): M L H V C S Q T A Z. |
+| `path` |  | ref → path |  |  | Id of a &lt;path&gt; element whose d is used. |
+| `fillRule` |  | `nonzero` \| `evenodd` | `nonzero` |  | How nested contours become holes (SVG fill-rule). |
+| `depth` |  | number | `1` | > 0 | Extrusion depth along Z. |
+| `bevel` |  | number | `0` | ≥ 0 | Bevel radius on the front and back edges. |
+| `bevelSegments` |  | int | `3` | ≥ 1, ≤ 16 | Segments per bevel. |
+| `center` |  | bool | `false` |  | Centre the extrusion on z = 0. |
+
+### `<revolve>`
+
+Revolves (lathes) a 2D profile around the Y axis; x is the distance from the axis.
+
+Children: `<animate>`.
+
+Accepts the common attributes, plus:
+
+| Attribute | Alias | Type | Default | Range | Description |
+|---|---|---|---|---|---|
+| `collide` |  | bool | `true` |  | When false the camera may pass through the element and its children (see &lt;controls collide&gt;). |
+| `d` |  | path2d |  |  | SVG path data in the local XY plane (y up): M L H V C S Q T A Z. |
+| `path` |  | ref → path |  |  | Id of a &lt;path&gt; element whose d is used. |
+| `fillRule` |  | `nonzero` \| `evenodd` | `nonzero` |  | How nested contours become holes (SVG fill-rule). |
+| `angle` |  | angle | `360` | > 0, ≤ 360 | Revolution angle in degrees. |
+| `segments` |  | int |  | ≥ 3, ≤ 1024 | Fixed number of radial segments. |
+
+### `<sweep>`
+
+Sweeps a profile (circle or 2D path) along a 3D spine with rotation minimising frames.
+
+Children: `<animate>`.
+
+Accepts the common attributes, plus:
+
+| Attribute | Alias | Type | Default | Range | Description |
+|---|---|---|---|---|---|
+| `collide` |  | bool | `true` |  | When false the camera may pass through the element and its children (see &lt;controls collide&gt;). |
+| `d` |  | path2d |  |  | SVG path data in the local XY plane (y up): M L H V C S Q T A Z. |
+| `path` |  | ref → path |  |  | Id of a &lt;path&gt; element whose d is used. |
+| `fillRule` |  | `nonzero` \| `evenodd` | `nonzero` |  | How nested contours become holes (SVG fill-rule). |
+| `radius` | `r` | number |  | > 0 | Circular profile radius (alternative to d/path). |
+| `along` **(required)** |  | spine |  |  | Spine: x,y,z points, 3D path data (M L C S Q T Z) or helix(r,pitch,turns). |
+| `smooth` |  | bool | `false` |  | Interpolate spine points with a Catmull-Rom spline. |
+| `twist` |  | angle | `0` |  | Profile rotation in degrees from start to end. |
+| `taper` |  | number | `1` | ≥ 0 | Profile scale at the end (1 = constant). |
+| `caps` |  | bool | `true` |  | Close open ends. |
+| `segments` |  | int |  | ≥ 3, ≤ 256 | Circle profile sides. |
+
+### `<gear>`
+
+Involute spur gear in the XY plane, extruded along Z.
+
+Children: `<animate>`.
+
+Accepts the common attributes, plus:
+
+| Attribute | Alias | Type | Default | Range | Description |
+|---|---|---|---|---|---|
+| `collide` |  | bool | `true` |  | When false the camera may pass through the element and its children (see &lt;controls collide&gt;). |
+| `teeth` |  | int | `24` | ≥ 5, ≤ 400 | Number of teeth. |
+| `module` |  | number | `0.04` | > 0 | Module: pitch diameter / teeth. |
+| `pressureAngle` |  | angle | `20` | ≥ 10, ≤ 35 | Pressure angle in degrees. |
+| `depth` |  | number | `0.2` | > 0 | Face width (extrusion depth). |
+| `bore` |  | number | `0` | ≥ 0 | Radius of the centre hole. |
+| `bevel` |  | number | `0` | ≥ 0 | Edge bevel radius. |
+| `center` |  | bool | `true` |  | Centre the gear on z = 0. |
+
+### `<mesh>`
+
+Explicit indexed triangle mesh (escape hatch for data that is not procedural).
+
+Children: `<animate>`.
+
+Accepts the common attributes, plus:
+
+| Attribute | Alias | Type | Default | Range | Description |
+|---|---|---|---|---|---|
+| `collide` |  | bool | `true` |  | When false the camera may pass through the element and its children (see &lt;controls collide&gt;). |
+| `positions` **(required)** |  | floats |  |  | x y z for every vertex. |
+| `indices` |  | indices |  |  | Triangle vertex indices (3 per triangle); omitted = non-indexed triangles. |
+| `normals` |  | floats |  |  | Optional x y z normal per vertex (computed when omitted). |
+| `uvs` |  | floats |  |  | Optional u v per vertex. |
+| `smooth` |  | angle | `30` | ≥ 0, ≤ 180 | Crease angle for computed normals (0 = flat). |
+
+## Lights and cameras
+
+### `<light>`
+
+Directional, point, spot, ambient or hemisphere light.
+
+Children: `<animate>`.
+
+Attributes:
+
+| Attribute | Alias | Type | Default | Range | Description |
+|---|---|---|---|---|---|
+| `id` |  | id |  |  | Unique identifier, referenced by &lt;use ref&gt;, material="…" and path="…". |
+| `name` |  | string |  |  | Human readable label shown in tools. |
+| `transform` | `t` | transform |  |  | SVG-style transform list; applied outside position/rotation/scale. |
+| `position` | `p` | vec3 | `0,0,0` |  | Light position (point/spot). |
+| `rotation` | `rot` | vec3 | `0,0,0` |  | Euler angles in degrees, applied about X, then Y, then Z. |
+| `visible` |  | bool | `true` |  | When false the element and its children are not rendered. |
+| `type` **(required)** |  | `directional` \| `point` \| `spot` \| `ambient` \| `hemisphere` |  |  | Light kind. |
+| `color` | `c` | color | `#fff` |  | Light colour. |
+| `intensity` |  | number | `1` | ≥ 0 | Intensity multiplier. |
+| `direction` | `dir` | vec3 |  |  | Direction the light travels (directional/spot). |
+| `target` |  | vec3 |  |  | Point the light aims at (alternative to direction). |
+| `range` |  | number | `0` | ≥ 0 | Point/spot cut-off distance (0 = unlimited). |
+| `angle` |  | angle | `45` | ≥ 1, ≤ 179 | Spot cone angle in degrees. |
+| `penumbra` |  | number | `0.2` | ≥ 0, ≤ 1 | Spot edge softness. |
+| `groundColor` |  | color | `#403833` |  | Hemisphere light colour from below. |
+
+### `<camera>`
+
+Perspective or orthographic camera. The first camera is the initial view.
+
+Children: `<animate>`.
+
+Attributes:
+
+| Attribute | Alias | Type | Default | Range | Description |
+|---|---|---|---|---|---|
+| `id` |  | id |  |  | Unique identifier, referenced by &lt;use ref&gt;, material="…" and path="…". |
+| `name` |  | string |  |  | Human readable label shown in tools. |
+| `transform` | `t` | transform |  |  | SVG-style transform list; applied outside position/rotation/scale. |
+| `position` | `p` | vec3 | `0,0,10` |  | Eye position. |
+| `rotation` | `rot` | vec3 |  |  | Euler orientation (used when no target is given; the camera looks down -Z). |
+| `target` |  | vec3 |  |  | Point the camera looks at. |
+| `up` |  | vec3 | `0,1,0` |  | Up vector. |
+| `type` |  | `perspective` \| `orthographic` | `perspective` |  | Projection. |
+| `fov` |  | angle | `45` | ≥ 1, ≤ 179 | Vertical field of view in degrees (perspective). |
+| `height` |  | number | `10` | > 0 | Visible height (orthographic). |
+| `near` |  | number |  | > 0 | Near clip distance (automatic when omitted). |
+| `far` |  | number |  | > 0 | Far clip distance (automatic when omitted). |
+| `aspect` |  | number | `1` | > 0 | Width / height of the view the author framed (e.g. 1.778 for 16:9). fov is the vertical angle at this aspect ratio. |
+| `fit` |  | `contain` \| `cover` \| `width` \| `height` | `contain` |  | How the framed view adapts to other screens: contain keeps all of it visible, cover fills the screen, width and height keep that extent fixed. |
+
+## Animation
+
+### `<animate>`
+
+Animates a transform of its parent (position, rotation, scale; target and fov of a camera) over time or over page scroll.
+
+Children: none.
+
+Attributes:
+
+| Attribute | Alias | Type | Default | Range | Description |
+|---|---|---|---|---|---|
+| `attr` **(required)** |  | `position` \| `rotation` \| `scale` \| `target` \| `fov` |  |  | Animated attribute. target and fov apply to &lt;camera&gt; only. |
+| `from` |  | animValue |  |  | Start value (defaults to the parent value). |
+| `to` |  | animValue |  |  | End value. |
+| `values` |  | keyframes |  |  | Key values separated by semicolons, e.g. 0,1,0; 2,1,0; 2,3,0 (instead of from/to). |
+| `keyTimes` |  | numbers |  |  | Progress (0 to 1) at which each of values is reached; evenly spaced when omitted. |
+| `along` |  | spine |  |  | Path to move along at constant speed (position and target): x,y,z points, 3D path data or helix(). |
+| `smooth` |  | bool | `false` |  | Pass through values or along points on a smooth (centripetal Catmull-Rom) curve. |
+| `dur` |  | duration |  |  | Duration of one cycle, e.g. 4s or 500ms (required unless timeline="scroll"). |
+| `begin` |  | duration | `0` | ≥ 0 | Delay before the animation starts. |
+| `repeat` |  | repeatCount | `indefinite` |  | Number of cycles or 'indefinite'. |
+| `alternate` |  | bool | `false` |  | Play every second cycle backwards. |
+| `easing` |  | `linear` \| `ease-in` \| `ease-out` \| `ease-in-out` | `linear` |  | Timing function. |
+| `timeline` |  | `time` \| `scroll` | `time` |  | time: plays by the clock. scroll: progress follows page scroll from 0 to 1 (dur, begin, repeat and alternate are not used). |
+
+## Value types
+
+| Type | Syntax |
+|---|---|
+| angle | Number of degrees. |
+| animValue | Three numbers (one or three for scale, one for fov). |
+| bool | `true` or `false`. |
+| color | `#rgb`, `#rrggbb`, `#rrggbbaa`, `rgb(r,g,b)`, `rgba(r,g,b,a)` or a CSS colour name; sRGB. |
+| count2 | Two positive whole numbers `nx,nz`. |
+| duration | Time: `4`, `4s` or `250ms`. |
+| enum | One of the listed keywords. |
+| floats | Whitespace separated numbers (mesh data, stored as float32). |
+| id | Identifier: a letter or `_` followed by letters, digits, `_ . : -`. |
+| idlist | Comma or space separated ids. |
+| indices | Whitespace separated non-negative whole numbers. |
+| int | Whole number. |
+| keyframes | Key values separated by semicolons, each with as many numbers as `from`/`to`: `0,1,0; 2,1,0; 2,3,0`. |
+| normalTexture | Image URL, or a procedural normal map: `bumps(count,strength)`, `tiles(count,strength,gap)`, `noise(scale,strength,seed)`, `waves(count,strength)`, `bricks(count,strength)`. |
+| number | Decimal number, e.g. `1`, `-0.25`, `.5`, `2e-3`. |
+| numbers | List of numbers. |
+| path2d | SVG path data: `M L H V C S Q T A Z` (absolute and relative), in the local XY plane with y up. |
+| points2 | Point list `x,y x,y …`. |
+| points3 | Point list `x,y,z x,y,z …`. |
+| range3 | A range `lo..hi` used for x, y and z, or three comma separated ranges/numbers `x,y,z`. |
+| ref | Id of another element of the indicated kind. |
+| repeatCount | Number of repetitions or `indefinite`. |
+| scale3 | One number (uniform) or three numbers. |
+| size2 | One number (both dimensions) or two numbers. |
+| size3 | One number (all three dimensions) or three numbers. |
+| spine | 3D spine: `x,y,z x,y,z …`, 3D path data (`M L C S Q T Z` with 3 numbers per point) or `helix(radius,pitch,turns[,segmentsPerTurn])`. |
+| string | Free text. |
+| texture | Image URL, or a procedural texture: `checker(count,color1,color2)`, `grid(count,width,line,background)`, `stripes(count,color1,color2)`, `noise(scale,color1,color2,seed)`, `bricks(count,brick,mortar)`; trailing arguments may be omitted. |
+| transform | SVG-style list: `translate(x[,y[,z]])`, `rotate(x,y,z)`, `rotate(a,ax,ay,az)`, `rotateX(a)`, `rotateY(a)`, `rotateZ(a)`, `scale(s)`, `scale(x,y,z)`, `quat(x,y,z,w)`, `matrix(16 numbers, column-major)`; composed left to right. |
+| vec2 | Two numbers `x,y` (comma and/or space separated). |
+| vec3 | Three numbers `x,y,z`. |
+