@es3d/es3d 1.0.0 → 1.0.1

package/docs/SPEC.md

@@ -1,417 +1,417 @@
-# ES3D: Extensible Scalable 3D
-
-**Format specification, version 1** · file extension `.es3d` · namespace `https://es3d.org/ns/1`
-
-ES3D is a declarative scene format in the spirit of SVG. A document says what a scene contains: boxes, spheres, extruded outlines, instanced groups, lights, cameras. It does not store the triangles a modelling tool happened to emit. A reader turns that description into GPU geometry, at whatever tessellation the view needs.
-
-This document defines the semantics. The complete list of elements, attributes, value types, defaults and ranges is generated from the reference implementation's schema in [REFERENCE.md](REFERENCE.md). Where this text and the reference implementation disagree, that is a bug in one of them; please report it.
-
-Key words: **must**, **must not**, **should** and **may** are used as in RFC 2119.
-
----
-
-## 1. Design goals and non-goals
-
-Goals:
-
-1. **Human-readable and writable.** A useful scene fits on a screen and can be written by hand, generated by a template, or diffed in version control.
-2. **Primitive- and transform-based.** Geometry is described by parameters (a sphere is a radius), so size does not depend on tessellation and the reader can choose detail per view.
-3. **Reuse is first class.** Definitions (`<defs>`, `<use>`), linear patterns (`<repeat>`) and deterministic procedural placement (`<scatter>`) keep repetitive scenes small, and map directly to GPU instancing.
-4. **Strict.** Malformed input is reported with a location and, where possible, a suggestion. A reader must not silently drop or "repair" geometry.
-5. **Lossless round trips.** Reading and writing a document must not change its meaning; the reference implementation preserves attribute spelling and comments as well.
-
-Non-goals, by design: version 1 describes scenes built from shapes, paths and repetition. It does not describe skinning, morph targets or physics, and it is not a CAD format. There is no boundary representation and no exact Boolean.
-
-Version 1 also refuses a few things that stalled SVG:
-
-- **One document, not a family of profiles.** Compact syntax and JSON are encodings of the same tree. They are not subsets that omit elements. SVG Tiny, Basic and Full left authors guessing which half of the spec a viewer had, and SVG 1.2 Full never shipped.
-- **No script, no event handlers, no style sheets.** A file is a scene. Opening it does not run a program. SVG's mix of picture and script is why "using it as an image" later needed a separate security mode.
-- **No required namespace.** An `xmlns` attribute may appear and is ignored. Leaving it out is not an error. A missing namespace was a common reason early SVG files rendered as an XML error page.
-- **No custom entities.** Only `&lt;`, `&gt;`, `&amp;`, `&quot;`, `&apos;` and numeric character references are expanded. A DOCTYPE is ignored and cannot declare entities, so a document cannot expand itself the way a billion-laughs payload does.
-- **No special compressed extension.** Gzip is `.es3d.gz`. SVG's `.svgz` was often gzipped a second time, or served with the wrong media type. Until `model/vnd.es3d` is registered, servers may send the text as `text/plain; charset=utf-8`.
-
-## 2. Conformance
-
-A **conforming document** is a document that parses in one of the surface syntaxes of section 4, has an `es3d` root element with `version="1"` (or `1.x`), and produces no errors under the rules of this specification and the schema in REFERENCE.md.
-
-A **conforming reader**:
-
-- must reject documents with errors, reporting each error with a stable code (section 15), a message, and a location (line and column for text input, an element path otherwise);
-- must report all errors it can find, not only the first (syntax errors that make the rest of the document unreadable are the exception);
-- must not render a document with errors as if it were valid (the reference viewer keeps showing the last valid state and marks it stale);
-- must produce, for every `<scatter>`, the instances defined in section 12.3 (procedural placement is part of the format, not a rendering hint);
-- may choose tessellation freely, within the accuracy rules of section 8.1.
-
-The legacy root name `<v3d>` is accepted with a warning (`W_LEGACY_ROOT`).
-
-## 3. Coordinate system, units and conventions
-
-- Right-handed coordinates, **+Y up**. Cameras look down their local **−Z** axis.
-- Lengths are plain numbers. The root attribute `unit` (`m` by default) is informative only; readers must not rescale.
-- Angles are in **degrees** everywhere (rotations, field of view, arcs, sweeps).
-- Colours are **sRGB**; readers convert to linear space for lighting.
-- 2D outline data (path data, polygons) lives in the local **XY plane with y up**. SVG's y axis points down. A path drawn in SVG coordinates can be used with `scale="1,-1,1"`.
-- Every primitive's default size fits the unit cube centred at the origin, so `<box/>`, `<sphere/>`, `<cylinder/>` … are all visible and directly comparable.
-
-## 4. Surface syntaxes
-
-All syntaxes produce the same abstract tree of elements, attributes, text and comments. Attribute values are strings in the tree; their typed interpretation (section 6) is defined by the schema. A reader detects the syntax from the first significant character: `<` markup, `[` or `{` JSON, anything else compact. There is no binary encoding of the document.
-
-### 4.1 Markup (canonical)
-
-An XML subset:
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<es3d version="1">
-  <material id="brass" color="#c9a227" metallic="1" roughness="0.35"/>
-  <group position="0,1,0" rotation="0,30,0">
-    <box size="2,0.2,1" material="brass"/>
-    <sphere radius="0.4" position="0,0.5,0" color="tomato"/>
-  </group>
-</es3d>
-```
-
-Supported: elements, single- or double-quoted attributes, comments, the five predefined entities and numeric character references, CDATA sections (treated as text), an optional XML declaration, and a DOCTYPE that is ignored. The DOCTYPE is not read for entity declarations. Not supported (errors): unquoted attribute values, duplicate attributes, text in elements that do not accept text, more than one root element, and any entity other than the five predefined ones. Element and attribute names are case-sensitive. Namespace prefixes are not interpreted. `xmlns` attributes are allowed and ignored, and a document does not need one.
-
-### 4.2 Compact syntax (ES3D-C)
-
-A brace-structured syntax for hand writing. On the example scenes it is 15–23 % smaller than minified markup and about half the size of indented markup (after gzip the difference shrinks to 5–12 %):
-
-```
-es3d version=1
-// comments: // line and /* block */
-material#brass c=#c9a227 metallic=1 roughness=0.35
-group p=0,1,0 rot=0,30,0 {
-  box s=2,0.2,1 m=brass
-  sphere r=0.4 p=0,0.5,0 c=tomato
-}
-use @tree p=10,0,5
-title "A \"quoted\" title"
-```
-
-Grammar (newlines are ordinary whitespace):
-
-```
-document  := comment* root
-root      := ('es3d' | 'v3d') header ( '{' statement* '}' | statement* )
-statement := element | comment | ';'
-element   := NAME header ( '{' statement* '}' )?
-header    := ( '#' ID )? ( '@' REF )? STRING? ( NAME '=' VALUE )*
-VALUE     := bare-value | '"' escaped-string '"'
-```
-
-`#x` is shorthand for `id="x"`, `@x` for `ref="x"`, and a quoted string in header position is the element's text content. A bare value runs until whitespace, `{`, `}`, `;` or `"`; values containing those characters (transforms with spaces, path data) must be quoted. An element header ends at the first token that is not `NAME=`, so the grammar is LL(2) and needs no schema knowledge.
-
-### 4.3 JSON (JsonML)
-
-`["es3d", {"version": "1"}, ["box", {"size": "2"}], ["title", {}, "text"]]`. An element is an array of name, attribute object (every value a string) and children. Strings are text. Comments are `["#comment", "text"]`. This form exists for tooling that prefers JSON. It is larger than the markup, and errors inside values have no line or column. It is an encoding of the same tree, not a reduced profile.
-
-### 4.4 Document encoding
-
-A document is UTF-8 text in one of the three syntaxes above. Gzip (`.es3d.gz`) is ordinary HTTP compression of that text. Meshes that have no procedural description stay inline as `<mesh>` (section 10). The format does not reference glTF, OBJ or any other container for its geometry.
-
-### 4.5 Attribute aliases
-
-Frequently used attributes have short aliases that are equivalent everywhere (an element must not give both forms): `p` position, `rot` rotation, `sc` scale, `t` transform, `m` material, `c` color, `s` size, `r` radius, `h` height, `n` count, `dir` direction, `href` ref. Writers producing minified output use the aliases; pretty output uses the full names.
-
-## 5. Document structure
-
-```
-<es3d version="1" [unit] [name]>
-  <title>, <desc>            optional metadata (text)
-  <environment>              background and ambient light (first one wins)
-  <controls>                 how viewers let people move the camera (first one wins)
-  <material id>              materials may appear anywhere; they are document-wide
-  <defs>                     definitions referenced by id; not rendered directly
-  <scene>                    optional wrapper; behaves like <group>
-  scene nodes …              shapes, containers, <use>, lights, cameras
-</es3d>
-```
-
-Each element's allowed children are listed in REFERENCE.md. Placing an element where it is not allowed is an error (`E_MISPLACED_ELEMENT`). Ids are unique per document (`E_DUPLICATE_ID`) and are referenced by `material`, `ref`, `path` and `randomMaterial` attributes; references are checked for existence (`E_UNKNOWN_REFERENCE`, with a suggestion), kind (`E_REFERENCE_KIND`) and cycles (`E_CIRCULAR_REFERENCE`).
-
-## 6. Values
-
-The exact syntax of every value type is listed at the end of REFERENCE.md. General rules:
-
-- Numbers follow the SVG/CSS number grammar: optional sign, digits with an optional fraction or a leading `.`, optional exponent (`-0.5`, `.5`, `2e-3`). `NaN`, `Infinity` and hexadecimal are not numbers.
-- Lists accept commas, whitespace or both as separators (`1,2,3`, `1 2 3`, `1, 2, 3`), but not empty items.
-- Vectors have fixed arity; `size` and `scale` also accept one number for all components.
-- Booleans are `true` or `false`.
-- An attribute that fails to parse is an error (`E_INVALID_VALUE`) located inside the value where possible; a value outside its range is `E_RANGE`.
-- Cross-attribute rules (for example "`bevel` must not exceed half the `depth`", "give `count` or `grid`, not both") are errors, never silent clamping.
-
-## 7. Transforms and the scene hierarchy
-
-Every scene node has a **local matrix**
-
-```
-local = transform · T(position) · R(rotation) · S(scale)
-```
-
-and its world matrix is `parentWorld · local`. Consequently `position`, `rotation` and `scale` are applied *inside* the `transform` attribute, like `x`/`y` inside the transform of an SVG `<use>`.
-
-- `rotation="x,y,z"` is in degrees and applied about X first, then Y, then Z: `R = Rz · Ry · Rx`. Sine and cosine of rotation angles are the functions in section 12.3, not the platform `sin` and `cos`.
-- `scale` may be negative (mirroring); readers must keep faces outward-facing by flipping the winding of mirrored instances.
-- `transform` is an SVG-style list of functions composed **left to right**: `translate(1,0,0) rotateY(90) scale(2)` means `T · Ry · S`; the rightmost function acts on the object first. Functions: `translate(x[,y[,z]])`, `rotate(x,y,z)` (Euler degrees), `rotate(a,ax,ay,az)` (axis-angle; zero axis is an error), `rotateX(a)`, `rotateY(a)`, `rotateZ(a)`, `scale(s)` or `scale(x,y,z)` (two arguments are an error), `quat(x,y,z,w)`, `matrix(m0 … m15)` (column-major, like CSS `matrix3d`). `rotate(45)` is an error, with a hint to use `rotateY(45)`. The 2D SVG meaning of a single angle is ambiguous in 3D.
-- `visible="false"` hides a node and its subtree (they still exist and can be referenced).
-
-## 8. Shapes
-
-Each shape element produces one renderable geometry in its local frame, centred at the origin unless stated otherwise. Dimensions, defaults and ranges are listed in REFERENCE.md.
-
-| Element | Local definition |
-|---|---|
-| `box` | axis-aligned box, `size` = edge lengths; `radius` rounds all edges |
-| `sphere` | radius `radius` |
-| `cylinder` | along Y from −h/2 to +h/2; `radiusTop` makes a truncated cone; `caps="false"` leaves it open |
-| `cone` | base at −h/2, apex at +h/2 |
-| `capsule` | along Y, total height `height` including the hemispherical caps |
-| `plane` | rectangle in XZ facing +Y, double-sided |
-| `torus` | around Y; `radius` to the tube centre, `tube` tube radius, `arc` partial sweep from +X towards −Z |
-| `line` | from `from` to `to`; a hairline, or a tube of `radius` |
-| `polyline` | 3D `points` or the outline of 2D path data `d`; `smooth` = Catmull-Rom; hairline or tube |
-| `polygon` | filled flat polygon in XY, double-sided |
-| `path` | filled flat 2D path in XY, double-sided; inside `<defs>` a reusable outline |
-| `extrude` | 2D path extruded from z = 0 to z = `depth` (or centred with `center="true"`), optional rounded `bevel` |
-| `revolve` | 2D profile revolved around Y; profile x = distance from the axis, y = height |
-| `sweep` | circle (`radius`) or 2D profile swept along a 3D spine (`along`) with rotation-minimising frames, optional `twist` and `taper` |
-| `gear` | involute spur gear with `teeth`, `module`, `pressureAngle`, extruded by `depth`, optional `bore` and `bevel` |
-| `mesh` | explicit triangles (section 10) |
-
-### 8.1 Tessellation
-
-Shapes are exact mathematical surfaces. A reader may choose the triangles, and every generated mesh must stay within that level's chordal-error bound: the maximum distance from the mesh to the true surface, measured in the generator's canonical units. The bound is part of the geometry. Identical triangles are not required. Platform `sin` and `cos` may be used while tessellating; placement (section 12.3) may not.
-
-The reference reader keeps up to four levels. At quality 1 the segment count is `max(minimum, round(base / 2^level))`:
-
-| Shape | Base | Minimum | Levels |
-|---|---:|---:|---|
-| Sphere, cylinder, cone | 48 | 8 | 48, 24, 12, 8 |
-| Capsule | 32 | 8 | 32, 16, 8, 8 |
-| Torus sweep / tube | 64 / 24 | 8 / 6 | 64, 32, 16, 8 and 24, 12, 6, 6 |
-| Rounded box | 4 | 1 | 4, 2, 1, 1 |
-
-A `segments` attribute (or both torus segment counts) requests one fixed tessellation, which is part of the shape. A `segments="6"` cylinder is a hexagonal prism at every distance. Exact shapes (box, plane, polygon, hairline, authored mesh) have one level and a bound of 0.
-
-Each level stores its bound. A frame may draw a level only while `bound × scale × pixelsPerUnit` is at most 1. `scale` is the longest column of the instance matrix. `pixelsPerUnit` is the projected size of one canonical unit. The reference reader picks the coarsest level that satisfies that test. A renderer `lodBias` above 1 (default 1) divides the one-pixel budget; it is not a document attribute. While a level is still being generated, a renderer may draw a coarser one in its place for a few frames (progressive refinement), as long as it keeps drawing until every level passes the test. For a unit sphere the switches fall near 59, 15 and 7 pixels of the sphere's own radius.
-
-Closed shapes must produce closed, outward-facing surfaces. Open or flat shapes (planes, polygons, paths, open revolves, `caps="false"`) are rendered double-sided.
-
-## 9. Path data
-
-`d` attributes use SVG path syntax with all commands, absolute and relative: `M L H V C S Q T A Z` (plus implicit repetition, `m` followed by implicit `l`, and the SVG separator rules). Arcs follow the SVG implementation notes (radii scaled up when too small). Coordinates are in the local XY plane, **y up**.
-
-- **Subpaths and fill rules.** A path can contain several closed subpaths. `fillRule` (`nonzero`, default, or `evenodd`) decides which nested contours become holes, exactly as SVG's `fill-rule`. Surfaces are generated where the fill changes, so same-direction nested contours under `nonzero` produce internal walls only where the filled region actually changes.
-- **Open subpaths** are closed implicitly for filling (SVG behaviour); `revolve` uses open profiles as-is.
-- **Degenerate input** is reported, never repaired: subpaths without area produce `W_DEGENERATE_CONTOUR`, a fill that leaves nothing to fill `W_EMPTY_FILL`, and a self-intersecting contour `W_SELF_INTERSECTION` stating how much of the expected area the triangulation covers. Readers must not invent geometry for invalid outlines.
-- `path="id"` references a `<path>` in `<defs>` instead of inline data; a shape gives either `d` or `path`.
-- 3D path data (sweep spines) uses `M L C S Q T Z` with three numbers per point; `H`, `V` and `A` are errors in 3D.
-
-`extrude` caps the front and back with the filled region, builds walls from every contour, and offsets the caps inwards by the bevel radius with a quarter-round profile. `revolve` profiles must stay at x ≥ 0 (`E_REVOLVE_AXIS`); closed profiles produce closed solids, open profiles open surfaces, and faces are oriented outwards automatically. `sweep` frames are rotation-minimising (double reflection); closed spines are corrected so the frames meet without a seam.
-
-## 10. Meshes (escape hatch)
-
-`<mesh positions="x y z …" indices="i j k …"/>` stores triangles explicitly, for content that has no procedural description (scans, sculpted shapes). `normals` and `uvs` are optional; without normals the reader computes them with the crease angle `smooth` (degrees; 0 = flat, 180 = fully smooth). Mesh arrays are float32 data. Index and array-length errors are reported (`E_MESH`), never truncated. A `<mesh>` in `<defs>` can be instanced with `<use>` like anything else.
-
-A writer that emits `<mesh>` from floating-point data rounds positions so the error is at most 10⁻⁵ of the scene extent, and rounds normals to two decimal places. Authored documents may use more digits; readers still store the values as float32.
-
-## 11. Materials
-
-`<material>` defines a metallic/roughness material in the glTF channel layout, stored on the element itself:
-
-- `color` is the base colour (sRGB). Its alpha multiplies `opacity`.
-- `metallic` and `roughness` are factors in 0…1.
-- `metallicRoughnessMap` is a linear texture: green multiplies roughness, blue multiplies metallic.
-- `occlusionMap` is a linear texture. Red darkens indirect light (hemisphere and environment), mixed by `occlusionStrength` (default 1). It does not scale direct lights.
-- `emissive` × `emissiveIntensity`, multiplied by `emissiveMap` (sRGB).
-- `map` (base colour, sRGB) and `normalMap` (linear, scaled by `normalScale`). A texture is an image URL or a procedural texture such as `checker(8)` or `bumps(12,0.6)`. `uvScale` repeats the coordinates.
-- `alphaMode` is `auto` (default), `opaque`, `mask` or `blend`. `auto` is `blend` when `opacity` × colour alpha is below 0.999 and `opaque` otherwise. `opaque` ignores alpha. `mask` discards fragments below `alphaCutoff` (default 0.5). `blend` uses opacity as coverage. Texture alpha is visible only with `alphaMode="blend"` and an opacity below 1.
-- `doubleSided` and `unlit`.
-
-Texture coordinates, before `uvScale`:
-
-- Sphere: `u` is longitude, 0 at +X, increasing through −Z; `v` is 1 at the north pole and 0 at the south pole. The seam is the +X meridian.
-- Cylinder and cone: `u` runs around the axis, 0 at +X; `v` is 0 at the bottom and 1 at the top. Caps use a planar projection in XZ, centred at (0.5, 0.5).
-- Plane: the unit square in XZ, `u` along +X and `v` along −Z.
-- Box: each face is 0…1, with the face's normal as the projection axis.
-- Torus: `u` along the sweep from the +X side, `v` around the tube.
-
-Inheritance follows SVG's `fill`:
-
-- `material="id"` on any node sets the material for the node and its descendants, and **clears** an inherited colour override.
-- `color="…"` on any node overrides the base colour (of the inherited or own material) for the node and its descendants.
-- A `<use>` passes its material and colour down into the referenced content as *inherited* values; values set inside the definition win.
-- Without any material, shapes use the default material (light grey, roughness 0.5).
-
-Identical parameter sets are the same material; readers should deduplicate them (the reference reader binds each distinct material once per frame).
-
-## 12. Reuse and procedural placement
-
-### 12.1 `<defs>` and `<use>`
-
-Children of `<defs>` are not rendered. `<use ref="id">` renders the referenced element (from `<defs>` or anywhere else in the document) as if it were a child of the `<use>`, under the use's transform and style. A definition referenced N times exists once; readers should render repeated geometry with instancing. Reference cycles are errors.
-
-### 12.2 `<repeat>`
-
-`<repeat count="n" step="transform">` renders its children n times. Copy i (0-based) is placed with `step` applied i times:
-
-```
-world(copy i) = world(repeat) · stepⁱ · local(child)
-```
-
-so `step="translate(0,0.2,0.3) rotateY(15)"` builds a spiral staircase. `count="0"` renders nothing.
-
-### 12.3 `<scatter>` (normative algorithm)
-
-`<scatter>` places `count` copies of its children (or `grid="nx,nz"` copies) in its local XZ plane. Every reader must implement this algorithm exactly, in IEEE 754 binary64 with round-to-nearest. The random sequence is integer arithmetic. `sqrt` is `Math.sqrt` (correctly rounded). Disc positions and every rotation matrix use `es3dSin` and `es3dCos` below, in the order written, so two readers produce the same bits.
-
-1. The random generator is **mulberry32** seeded with the unsigned 32-bit `seed` (default 1):
-   ```js
-   function mulberry32(seed) {
-     let a = seed >>> 0;
-     return () => {
-       a = (a + 0x6d2b79f5) >>> 0;
-       let t = a;
-       t = Math.imul(t ^ (t >>> 15), t | 1);
-       t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
-       return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
-     };
-   }
-   ```
-2. For copy i = 0 … n−1, draw exactly nine values u0 … u8 in order (all nine are drawn even when unused, so adding an attribute never changes the positions of other attributes' effects).
-3. Position (y = 0):
-   - grid: ix = i mod nx, iz = ⌊i / nx⌋; x = (ix − (nx−1)/2)·spacingₓ + (u0 − ½)·jitter·spacingₓ, z = (iz − (nz−1)/2)·spacing_z + (u1 − ½)·jitter·spacing_z;
-   - disc (`radius` R): r = R·√u0, a = u1·2π, x = r·es3dCos(a), z = r·es3dSin(a);
-   - rectangle (`area` w,d): x = (u0 − ½)·w, z = (u1 − ½)·d.
-4. Rotation (degrees, Euler as in section 7): component k = lo_k + (hi_k − lo_k)·u(2+k) for the ranges of `randomRotation`.
-5. Scale: uniform `randomScale` range → s = lo + (hi − lo)·u5 for all axes; per-axis ranges use u5, u6, u7.
-6. Material: with `randomMaterial="a,b,c"`, copy i uses entry ⌊u8 · count⌋ (clamped to the last entry) and the inherited colour override is cleared.
-7. world(copy i) = world(scatter) · T(position) · R(rotation) · S(scale) · local(child).
-
-`grid` and `count` are mutually exclusive, as are `area` and `radius`; a random layout needs one of them.
-
-`es3dSin` and `es3dCos` take radians. π, 2π, π/2 and π/4 are `Math.PI`, `Math.PI * 2`, `Math.PI * 0.5` and `Math.PI * 0.25`. A non-finite input is returned unchanged. Otherwise:
-
-```
-y = x - 2π · round(x / 2π)
-sign = 1
-if y < 0: sign = -1; y = -y
-if y > π/2: y = π - y
-if y < 0: y = 0
-s = y > π/4 ? kernelCos(π/2 - y) : kernelSin(y)
-es3dSin(x) = sign < 0 ? -s : s
-es3dCos(x) = es3dSin(x + π/2)
-```
-
-`kernelSin` and `kernelCos` are Horner polynomials. `z = x*x`. Coefficients, as binary64 literals:
-
-```
-S1 = -1.66666666666666324348e-1
-S2 =  8.33333333332248946124e-3
-S3 = -1.98412698298579493134e-4
-S4 =  2.75573137070700676789e-6
-S5 = -2.50507602534068634195e-8
-S6 =  1.58969099521155010221e-10
-kernelSin(x) = x + (z*x) * (S1 + z * (S2 + z * (S3 + z * (S4 + z * (S5 + z * S6)))))
-
-C1 =  4.16666666666666019037e-2
-C2 = -1.38888888888741095749e-3
-C3 =  2.48015872894767294178e-5
-C4 = -2.75573143513906633035e-7
-C5 =  2.0875723212981748279e-9
-C6 = -1.13596475577881948265e-11
-r = z * (C1 + z * (C2 + z * (C3 + z * (C4 + z * (C5 + z * C6)))))
-kernelCos(x) = 1 - 0.5*z + z*r
-```
-
-Every add, subtract and multiply is one binary64 operation, in that order. `round` is `Math.round` (a tie at n+0.5 rounds towards +∞).
-
-### 12.4 `<lod>`
-
-`<lod distances="d1,d2,…">` has exactly one more child than distances (`E_LOD_CHILDREN`). Child i is rendered while the distance from the camera to the lod's world origin is below dᵢ (and at least dᵢ₋₁); the last child beyond the last distance. Distances are in the lod's local units (scaled by the cube root of the world scale's determinant). Exporters to static formats write child 0. Automatic per-primitive tessellation LOD (section 8.1) is independent of `<lod>`.
-
-### 12.5 Resource limits
-
-Exceeding a limit is an error. The document is not rendered as valid.
-
-| Limit | Value | Code |
-|---|---:|---|
-| Expanded instances (`repeat`, `scatter`, `use`) | 2,000,000 | `E_TOO_MANY_INSTANCES` |
-| Nesting, counting each element and each use-to-target step | 64 | `E_TOO_DEEP` |
-| Commands in one path, after implicit repetition | 100,000 | `E_PATH_LIMIT` |
-| Copies in one `repeat` or `scatter` | 1,000,000 | `E_RANGE` |
-
-## 13. Lights, cameras and environment
-
-- `<light type="directional|point|spot|ambient|hemisphere">` with `color`, `intensity`; directional and spot lights take `direction` or `target`; point and spot lights `position` and an optional cut-off `range`; spot lights `angle` (full cone, degrees) and `penumbra` (0–1); hemisphere lights `color` (sky) and `groundColor`. Lights are placed by their ancestors' transforms like any node. Without any light, readers use a default key light so content is visible.
-- `<camera>` is perspective (`fov`, vertical, degrees) or orthographic (`height` of the visible area). Orientation comes from `target` (and `up`) or from `rotation` (looking down −Z); giving both is an error. `near`/`far` are optional. The first camera is the initial view.
-- **Framing on other screens.** `fov` (or `height`) is the vertical extent of a view `aspect` wide and 1 high (default `aspect="1"`). `fit` says how a viewport of another aspect ratio a is filled, like SVG's `preserveAspectRatio`. With s = aspect / a, the vertical extent is scaled by:
-  - `contain` (default): max(1, s). The whole framed view stays visible ("meet").
-  - `cover`: min(1, s). The viewport is filled and the framed view is cropped ("slice").
-  - `width`: s. The framed width is kept.
-  - `height`: 1. The framed height is kept.
-
-  The defaults reproduce the usual rule of applying `fov` to the shorter viewport side. An author who framed a scene for a 16:9 page writes `aspect="1.778"`, and a portrait phone then shows the same width instead of cropping the sides.
-- `<environment>` sets the clear colour (`background`), hemisphere ambient colours (`sky`, `ground`), their `intensity`, and tone-mapping `exposure`. Only the first `<environment>` is used (`W_MULTIPLE_ENVIRONMENTS`).
-- `<controls>` describes how an interactive reader lets people move the camera. Only the first one is used (`W_MULTIPLE_CONTROLS`), and a document without one gets the reader's defaults (usually free orbiting).
-  - `mode="orbit"` (default): drag to orbit the target, pan and zoom; `zoom="false"` and `pan="false"` turn those off.
-  - `mode="none"`: a fixed view from the first camera.
-  - `mode="scroll"`: the first camera is the view, moved only by its scroll-timeline animations (section 14). Dragging is off and the canvas must not capture touch scrolling.
-  - Limits keep the camera between `minDistance` and `maxDistance` from its target and between `minPolar` and `maxPolar` degrees from straight up (`maxPolar="90"` keeps it above the target). `targetMin` and `targetMax` bound the orbit target, and so panning.
-  - `collide="true"` stops the camera in front of surfaces. A move from the last camera position to the next is blocked by the first surface whose front faces the camera (double-sided surfaces always block). The camera stays far enough from the surface that its near plane does not cut into it, and a move that hits a surface at an angle slides along it. A camera that starts inside an object can leave it, and an orbit target inside an object does not trap the camera. Elements with `collide="false"` (inherited by their children, available on every node) are ignored.
-
-## 14. Animation
-
-`<animate attr="…" dur="4s" …>` inside a node animates an attribute of its parent: `position`, `rotation` or `scale` of any node, and also `target` and `fov` of a `<camera>` (`E_INVALID_VALUE` elsewhere; animating the target of a camera oriented by `rotation` is `E_CONFLICTING_ATTRIBUTES`). Animation replaces the attribute value, so `transform` still applies outside it.
-
-**Values.** Exactly one source is given (`E_MISSING_ATTRIBUTE` without one, `E_CONFLICTING_ATTRIBUTES` with several):
-- `to` (with optional `from`, default: the parent's value): a straight interpolation.
-- `values="v0; v1; …"`: two or more key values separated by semicolons. With `keyTimes="0, t1, …, 1"` (one per value, starting at 0, ending at 1, not decreasing), value i is reached at fraction tᵢ. Without it the keys are evenly spaced. Between keys the value is linear, or with `smooth="true"` on a centripetal Catmull-Rom curve through the keys. The end keys are extended by reflecting their neighbour, as for sweep spines.
-- `along` (position and target only): a path in the same syntax as a sweep's spine (points, 3D path data or `helix()`; `smooth` interpolates points). The fraction is measured along the path's length, so the value moves at constant speed.
-
-Each value has 3 numbers (1 or 3 for `scale`, 1 for `fov`).
-
-**Timeline.** The animation turns a fraction f in 0..1 into a value, after `easing` (`linear`, `ease-in`, `ease-out`, `ease-in-out`) is applied to f.
-- `timeline="time"` (default): `dur` is required. Before `begin` the animation has no effect. Then it plays `repeat` cycles (default `indefinite`), with `alternate="true"` playing every second cycle backwards, and after the last cycle it holds the end value.
-- `timeline="scroll"`: f is the reader's scroll progress, clamped to 0..1, and `dur`, `begin`, `repeat` and `alternate` are not used. How progress relates to a page is up to the reader. The reference viewer maps a page section's scroll position to it, with optional stops pinned to page elements. A reader without a page holds progress at 0.
-
-## 15. Diagnostics
-
-Readers report problems in this canonical form:
-
-```
-ES3D Parse Error
-line 2, column 11
-
-Unknown attribute: raduis
-
-Did you mean: radius?
-```
-
-The title names the phase (`Parse`, `Reference`, `Geometry`, `Render`, `File`) and severity (`Error`, `Warning`). Codes used by the reference reader:
-
-| Group | Codes |
-|---|---|
-| Syntax | `E_SYNTAX`, `E_UNEXPECTED_EOF`, `E_MISMATCHED_TAG`, `E_UNEXPECTED_CLOSE`, `E_UNCLOSED_ELEMENT`, `E_UNQUOTED_ATTRIBUTE`, `E_UNTERMINATED_ATTRIBUTE`, `E_UNTERMINATED_COMMENT`, `E_UNTERMINATED_CDATA`, `E_UNTERMINATED_PI`, `E_UNTERMINATED_DOCTYPE`, `E_UNTERMINATED_STRING`, `E_BAD_ENTITY`, `E_BAD_ESCAPE`, `E_MULTIPLE_ROOTS`, `E_TEXT_OUTSIDE_ROOT`, `E_EMPTY_DOCUMENT`, `E_COMPACT_ROOT`, `E_JSON`, `E_JSON_STRUCTURE` |
-| Structure | `E_ROOT`, `E_VERSION`, `E_UNKNOWN_ELEMENT`, `E_MISPLACED_ELEMENT`, `E_TEXT_NOT_ALLOWED`, `E_MULTIPLE_SCENES` |
-| Attributes | `E_UNKNOWN_ATTRIBUTE`, `E_DUPLICATE_ATTRIBUTE`, `E_MISSING_ATTRIBUTE`, `E_MISSING_VALUE`, `E_INVALID_VALUE`, `E_TYPE`, `E_RANGE`, `E_CONFLICTING_ATTRIBUTES` |
-| References | `E_DUPLICATE_ID`, `E_UNKNOWN_REFERENCE`, `E_REFERENCE_KIND`, `E_CIRCULAR_REFERENCE` |
-| Geometry | `E_GEOMETRY`, `E_MESH`, `E_DEGENERATE`, `E_DEGENERATE_SPINE`, `E_REVOLVE_AXIS`, `E_LOD_CHILDREN`, `E_TOO_MANY_INSTANCES`, `E_TOO_DEEP`, `E_PATH_LIMIT` |
-| Warnings | `W_LEGACY_ROOT`, `W_EXTENSION`, `W_DEF_WITHOUT_ID`, `W_MATERIAL_WITHOUT_ID`, `W_MULTIPLE_ENVIRONMENTS`, `W_MULTIPLE_CONTROLS`, `W_DEGENERATE_CONTOUR`, `W_SELF_INTERSECTION`, `W_EMPTY_FILL`, `W_TEXTURE` |
-
-Unknown names get a suggestion when a known name is within a small edit distance or shares a prefix (`raduis` → `radius`, `spotlight` → `spot`, `sphear` → `sphere`).
-
-## 16. Extensibility and versioning
-
-- Elements whose names start with `x-` (and their subtrees) are vendor extensions: readers that do not understand them skip them with `W_EXTENSION`. Unknown elements without the prefix are errors, so typos are never mistaken for extensions.
-- Unknown attributes are always errors. (A future version may reserve an `x-` attribute prefix as well.)
-- `version="1.x"` documents must remain readable by version-1 readers; incompatible changes require version 2, which version-1 readers reject with `E_VERSION`.
-
-## 17. File names and media types
-
-| | |
-|---|---|
-| Text (any syntax) | `.es3d`, UTF-8, optionally gzip-compressed (`.es3d.gz`) |
-| Media type (proposed, unregistered) | `model/vnd.es3d` |
+# ES3D: Extensible Scalable 3D
+
+**Format specification, version 1** · file extension `.es3d` · namespace `https://es3d.org/ns/1`
+
+ES3D is a declarative scene format in the spirit of SVG. A document says what a scene contains: boxes, spheres, extruded outlines, instanced groups, lights, cameras. It does not store the triangles a modelling tool happened to emit. A reader turns that description into GPU geometry, at whatever tessellation the view needs.
+
+This document defines the semantics. The complete list of elements, attributes, value types, defaults and ranges is generated from the reference implementation's schema in [REFERENCE.md](REFERENCE.md). Where this text and the reference implementation disagree, that is a bug in one of them; please report it.
+
+Key words: **must**, **must not**, **should** and **may** are used as in RFC 2119.
+
+---
+
+## 1. Design goals and non-goals
+
+Goals:
+
+1. **Human-readable and writable.** A useful scene fits on a screen and can be written by hand, generated by a template, or diffed in version control.
+2. **Primitive- and transform-based.** Geometry is described by parameters (a sphere is a radius), so size does not depend on tessellation and the reader can choose detail per view.
+3. **Reuse is first class.** Definitions (`<defs>`, `<use>`), linear patterns (`<repeat>`) and deterministic procedural placement (`<scatter>`) keep repetitive scenes small, and map directly to GPU instancing.
+4. **Strict.** Malformed input is reported with a location and, where possible, a suggestion. A reader must not silently drop or "repair" geometry.
+5. **Lossless round trips.** Reading and writing a document must not change its meaning; the reference implementation preserves attribute spelling and comments as well.
+
+Non-goals, by design: version 1 describes scenes built from shapes, paths and repetition. It does not describe skinning, morph targets or physics, and it is not a CAD format. There is no boundary representation and no exact Boolean.
+
+Version 1 also refuses a few things that stalled SVG:
+
+- **One document, not a family of profiles.** Compact syntax and JSON are encodings of the same tree. They are not subsets that omit elements. SVG Tiny, Basic and Full left authors guessing which half of the spec a viewer had, and SVG 1.2 Full never shipped.
+- **No script, no event handlers, no style sheets.** A file is a scene. Opening it does not run a program. SVG's mix of picture and script is why "using it as an image" later needed a separate security mode.
+- **No required namespace.** An `xmlns` attribute may appear and is ignored. Leaving it out is not an error. A missing namespace was a common reason early SVG files rendered as an XML error page.
+- **No custom entities.** Only `&lt;`, `&gt;`, `&amp;`, `&quot;`, `&apos;` and numeric character references are expanded. A DOCTYPE is ignored and cannot declare entities, so a document cannot expand itself the way a billion-laughs payload does.
+- **No special compressed extension.** Gzip is `.es3d.gz`. SVG's `.svgz` was often gzipped a second time, or served with the wrong media type. Until `model/vnd.es3d` is registered, servers may send the text as `text/plain; charset=utf-8`.
+
+## 2. Conformance
+
+A **conforming document** is a document that parses in one of the surface syntaxes of section 4, has an `es3d` root element with `version="1"` (or `1.x`), and produces no errors under the rules of this specification and the schema in REFERENCE.md.
+
+A **conforming reader**:
+
+- must reject documents with errors, reporting each error with a stable code (section 15), a message, and a location (line and column for text input, an element path otherwise);
+- must report all errors it can find, not only the first (syntax errors that make the rest of the document unreadable are the exception);
+- must not render a document with errors as if it were valid (the reference viewer keeps showing the last valid state and marks it stale);
+- must produce, for every `<scatter>`, the instances defined in section 12.3 (procedural placement is part of the format, not a rendering hint);
+- may choose tessellation freely, within the accuracy rules of section 8.1.
+
+The legacy root name `<v3d>` is accepted with a warning (`W_LEGACY_ROOT`).
+
+## 3. Coordinate system, units and conventions
+
+- Right-handed coordinates, **+Y up**. Cameras look down their local **−Z** axis.
+- Lengths are plain numbers. The root attribute `unit` (`m` by default) is informative only; readers must not rescale.
+- Angles are in **degrees** everywhere (rotations, field of view, arcs, sweeps).
+- Colours are **sRGB**; readers convert to linear space for lighting.
+- 2D outline data (path data, polygons) lives in the local **XY plane with y up**. SVG's y axis points down. A path drawn in SVG coordinates can be used with `scale="1,-1,1"`.
+- Every primitive's default size fits the unit cube centred at the origin, so `<box/>`, `<sphere/>`, `<cylinder/>` … are all visible and directly comparable.
+
+## 4. Surface syntaxes
+
+All syntaxes produce the same abstract tree of elements, attributes, text and comments. Attribute values are strings in the tree; their typed interpretation (section 6) is defined by the schema. A reader detects the syntax from the first significant character: `<` markup, `[` or `{` JSON, anything else compact. There is no binary encoding of the document.
+
+### 4.1 Markup (canonical)
+
+An XML subset:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<es3d version="1">
+  <material id="brass" color="#c9a227" metallic="1" roughness="0.35"/>
+  <group position="0,1,0" rotation="0,30,0">
+    <box size="2,0.2,1" material="brass"/>
+    <sphere radius="0.4" position="0,0.5,0" color="tomato"/>
+  </group>
+</es3d>
+```
+
+Supported: elements, single- or double-quoted attributes, comments, the five predefined entities and numeric character references, CDATA sections (treated as text), an optional XML declaration, and a DOCTYPE that is ignored. The DOCTYPE is not read for entity declarations. Not supported (errors): unquoted attribute values, duplicate attributes, text in elements that do not accept text, more than one root element, and any entity other than the five predefined ones. Element and attribute names are case-sensitive. Namespace prefixes are not interpreted. `xmlns` attributes are allowed and ignored, and a document does not need one.
+
+### 4.2 Compact syntax (ES3D-C)
+
+A brace-structured syntax for hand writing. On the example scenes it is 15–23 % smaller than minified markup and about half the size of indented markup (after gzip the difference shrinks to 5–12 %):
+
+```
+es3d version=1
+// comments: // line and /* block */
+material#brass c=#c9a227 metallic=1 roughness=0.35
+group p=0,1,0 rot=0,30,0 {
+  box s=2,0.2,1 m=brass
+  sphere r=0.4 p=0,0.5,0 c=tomato
+}
+use @tree p=10,0,5
+title "A \"quoted\" title"
+```
+
+Grammar (newlines are ordinary whitespace):
+
+```
+document  := comment* root
+root      := ('es3d' | 'v3d') header ( '{' statement* '}' | statement* )
+statement := element | comment | ';'
+element   := NAME header ( '{' statement* '}' )?
+header    := ( '#' ID )? ( '@' REF )? STRING? ( NAME '=' VALUE )*
+VALUE     := bare-value | '"' escaped-string '"'
+```
+
+`#x` is shorthand for `id="x"`, `@x` for `ref="x"`, and a quoted string in header position is the element's text content. A bare value runs until whitespace, `{`, `}`, `;` or `"`; values containing those characters (transforms with spaces, path data) must be quoted. An element header ends at the first token that is not `NAME=`, so the grammar is LL(2) and needs no schema knowledge.
+
+### 4.3 JSON (JsonML)
+
+`["es3d", {"version": "1"}, ["box", {"size": "2"}], ["title", {}, "text"]]`. An element is an array of name, attribute object (every value a string) and children. Strings are text. Comments are `["#comment", "text"]`. This form exists for tooling that prefers JSON. It is larger than the markup, and errors inside values have no line or column. It is an encoding of the same tree, not a reduced profile.
+
+### 4.4 Document encoding
+
+A document is UTF-8 text in one of the three syntaxes above. Gzip (`.es3d.gz`) is ordinary HTTP compression of that text. Meshes that have no procedural description stay inline as `<mesh>` (section 10). The format does not reference glTF, OBJ or any other container for its geometry.
+
+### 4.5 Attribute aliases
+
+Frequently used attributes have short aliases that are equivalent everywhere (an element must not give both forms): `p` position, `rot` rotation, `sc` scale, `t` transform, `m` material, `c` color, `s` size, `r` radius, `h` height, `n` count, `dir` direction, `href` ref. Writers producing minified output use the aliases; pretty output uses the full names.
+
+## 5. Document structure
+
+```
+<es3d version="1" [unit] [name]>
+  <title>, <desc>            optional metadata (text)
+  <environment>              background and ambient light (first one wins)
+  <controls>                 how viewers let people move the camera (first one wins)
+  <material id>              materials may appear anywhere; they are document-wide
+  <defs>                     definitions referenced by id; not rendered directly
+  <scene>                    optional wrapper; behaves like <group>
+  scene nodes …              shapes, containers, <use>, lights, cameras
+</es3d>
+```
+
+Each element's allowed children are listed in REFERENCE.md. Placing an element where it is not allowed is an error (`E_MISPLACED_ELEMENT`). Ids are unique per document (`E_DUPLICATE_ID`) and are referenced by `material`, `ref`, `path` and `randomMaterial` attributes; references are checked for existence (`E_UNKNOWN_REFERENCE`, with a suggestion), kind (`E_REFERENCE_KIND`) and cycles (`E_CIRCULAR_REFERENCE`).
+
+## 6. Values
+
+The exact syntax of every value type is listed at the end of REFERENCE.md. General rules:
+
+- Numbers follow the SVG/CSS number grammar: optional sign, digits with an optional fraction or a leading `.`, optional exponent (`-0.5`, `.5`, `2e-3`). `NaN`, `Infinity` and hexadecimal are not numbers.
+- Lists accept commas, whitespace or both as separators (`1,2,3`, `1 2 3`, `1, 2, 3`), but not empty items.
+- Vectors have fixed arity; `size` and `scale` also accept one number for all components.
+- Booleans are `true` or `false`.
+- An attribute that fails to parse is an error (`E_INVALID_VALUE`) located inside the value where possible; a value outside its range is `E_RANGE`.
+- Cross-attribute rules (for example "`bevel` must not exceed half the `depth`", "give `count` or `grid`, not both") are errors, never silent clamping.
+
+## 7. Transforms and the scene hierarchy
+
+Every scene node has a **local matrix**
+
+```
+local = transform · T(position) · R(rotation) · S(scale)
+```
+
+and its world matrix is `parentWorld · local`. Consequently `position`, `rotation` and `scale` are applied *inside* the `transform` attribute, like `x`/`y` inside the transform of an SVG `<use>`.
+
+- `rotation="x,y,z"` is in degrees and applied about X first, then Y, then Z: `R = Rz · Ry · Rx`. Sine and cosine of rotation angles are the functions in section 12.3, not the platform `sin` and `cos`.
+- `scale` may be negative (mirroring); readers must keep faces outward-facing by flipping the winding of mirrored instances.
+- `transform` is an SVG-style list of functions composed **left to right**: `translate(1,0,0) rotateY(90) scale(2)` means `T · Ry · S`; the rightmost function acts on the object first. Functions: `translate(x[,y[,z]])`, `rotate(x,y,z)` (Euler degrees), `rotate(a,ax,ay,az)` (axis-angle; zero axis is an error), `rotateX(a)`, `rotateY(a)`, `rotateZ(a)`, `scale(s)` or `scale(x,y,z)` (two arguments are an error), `quat(x,y,z,w)`, `matrix(m0 … m15)` (column-major, like CSS `matrix3d`). `rotate(45)` is an error, with a hint to use `rotateY(45)`. The 2D SVG meaning of a single angle is ambiguous in 3D.
+- `visible="false"` hides a node and its subtree (they still exist and can be referenced).
+
+## 8. Shapes
+
+Each shape element produces one renderable geometry in its local frame, centred at the origin unless stated otherwise. Dimensions, defaults and ranges are listed in REFERENCE.md.
+
+| Element | Local definition |
+|---|---|
+| `box` | axis-aligned box, `size` = edge lengths; `radius` rounds all edges |
+| `sphere` | radius `radius` |
+| `cylinder` | along Y from −h/2 to +h/2; `radiusTop` makes a truncated cone; `caps="false"` leaves it open |
+| `cone` | base at −h/2, apex at +h/2 |
+| `capsule` | along Y, total height `height` including the hemispherical caps |
+| `plane` | rectangle in XZ facing +Y, double-sided |
+| `torus` | around Y; `radius` to the tube centre, `tube` tube radius, `arc` partial sweep from +X towards −Z |
+| `line` | from `from` to `to`; a hairline, or a tube of `radius` |
+| `polyline` | 3D `points` or the outline of 2D path data `d`; `smooth` = Catmull-Rom; hairline or tube |
+| `polygon` | filled flat polygon in XY, double-sided |
+| `path` | filled flat 2D path in XY, double-sided; inside `<defs>` a reusable outline |
+| `extrude` | 2D path extruded from z = 0 to z = `depth` (or centred with `center="true"`), optional rounded `bevel` |
+| `revolve` | 2D profile revolved around Y; profile x = distance from the axis, y = height |
+| `sweep` | circle (`radius`) or 2D profile swept along a 3D spine (`along`) with rotation-minimising frames, optional `twist` and `taper` |
+| `gear` | involute spur gear with `teeth`, `module`, `pressureAngle`, extruded by `depth`, optional `bore` and `bevel` |
+| `mesh` | explicit triangles (section 10) |
+
+### 8.1 Tessellation
+
+Shapes are exact mathematical surfaces. A reader may choose the triangles, and every generated mesh must stay within that level's chordal-error bound: the maximum distance from the mesh to the true surface, measured in the generator's canonical units. The bound is part of the geometry. Identical triangles are not required. Platform `sin` and `cos` may be used while tessellating; placement (section 12.3) may not.
+
+The reference reader keeps up to four levels. At quality 1 the segment count is `max(minimum, round(base / 2^level))`:
+
+| Shape | Base | Minimum | Levels |
+|---|---:|---:|---|
+| Sphere, cylinder, cone | 48 | 8 | 48, 24, 12, 8 |
+| Capsule | 32 | 8 | 32, 16, 8, 8 |
+| Torus sweep / tube | 64 / 24 | 8 / 6 | 64, 32, 16, 8 and 24, 12, 6, 6 |
+| Rounded box | 4 | 1 | 4, 2, 1, 1 |
+
+A `segments` attribute (or both torus segment counts) requests one fixed tessellation, which is part of the shape. A `segments="6"` cylinder is a hexagonal prism at every distance. Exact shapes (box, plane, polygon, hairline, authored mesh) have one level and a bound of 0.
+
+Each level stores its bound. A frame may draw a level only while `bound × scale × pixelsPerUnit` is at most 1. `scale` is the longest column of the instance matrix. `pixelsPerUnit` is the projected size of one canonical unit. The reference reader picks the coarsest level that satisfies that test. A renderer `lodBias` above 1 (default 1) divides the one-pixel budget; it is not a document attribute. While a level is still being generated, a renderer may draw a coarser one in its place for a few frames (progressive refinement), as long as it keeps drawing until every level passes the test. For a unit sphere the switches fall near 59, 15 and 7 pixels of the sphere's own radius.
+
+Closed shapes must produce closed, outward-facing surfaces. Open or flat shapes (planes, polygons, paths, open revolves, `caps="false"`) are rendered double-sided.
+
+## 9. Path data
+
+`d` attributes use SVG path syntax with all commands, absolute and relative: `M L H V C S Q T A Z` (plus implicit repetition, `m` followed by implicit `l`, and the SVG separator rules). Arcs follow the SVG implementation notes (radii scaled up when too small). Coordinates are in the local XY plane, **y up**.
+
+- **Subpaths and fill rules.** A path can contain several closed subpaths. `fillRule` (`nonzero`, default, or `evenodd`) decides which nested contours become holes, exactly as SVG's `fill-rule`. Surfaces are generated where the fill changes, so same-direction nested contours under `nonzero` produce internal walls only where the filled region actually changes.
+- **Open subpaths** are closed implicitly for filling (SVG behaviour); `revolve` uses open profiles as-is.
+- **Degenerate input** is reported, never repaired: subpaths without area produce `W_DEGENERATE_CONTOUR`, a fill that leaves nothing to fill `W_EMPTY_FILL`, and a self-intersecting contour `W_SELF_INTERSECTION` stating how much of the expected area the triangulation covers. Readers must not invent geometry for invalid outlines.
+- `path="id"` references a `<path>` in `<defs>` instead of inline data; a shape gives either `d` or `path`.
+- 3D path data (sweep spines) uses `M L C S Q T Z` with three numbers per point; `H`, `V` and `A` are errors in 3D.
+
+`extrude` caps the front and back with the filled region, builds walls from every contour, and offsets the caps inwards by the bevel radius with a quarter-round profile. `revolve` profiles must stay at x ≥ 0 (`E_REVOLVE_AXIS`); closed profiles produce closed solids, open profiles open surfaces, and faces are oriented outwards automatically. `sweep` frames are rotation-minimising (double reflection); closed spines are corrected so the frames meet without a seam.
+
+## 10. Meshes (escape hatch)
+
+`<mesh positions="x y z …" indices="i j k …"/>` stores triangles explicitly, for content that has no procedural description (scans, sculpted shapes). `normals` and `uvs` are optional; without normals the reader computes them with the crease angle `smooth` (degrees; 0 = flat, 180 = fully smooth). Mesh arrays are float32 data. Index and array-length errors are reported (`E_MESH`), never truncated. A `<mesh>` in `<defs>` can be instanced with `<use>` like anything else.
+
+A writer that emits `<mesh>` from floating-point data rounds positions so the error is at most 10⁻⁵ of the scene extent, and rounds normals to two decimal places. Authored documents may use more digits; readers still store the values as float32.
+
+## 11. Materials
+
+`<material>` defines a metallic/roughness material in the glTF channel layout, stored on the element itself:
+
+- `color` is the base colour (sRGB). Its alpha multiplies `opacity`.
+- `metallic` and `roughness` are factors in 0…1.
+- `metallicRoughnessMap` is a linear texture: green multiplies roughness, blue multiplies metallic.
+- `occlusionMap` is a linear texture. Red darkens indirect light (hemisphere and environment), mixed by `occlusionStrength` (default 1). It does not scale direct lights.
+- `emissive` × `emissiveIntensity`, multiplied by `emissiveMap` (sRGB).
+- `map` (base colour, sRGB) and `normalMap` (linear, scaled by `normalScale`). A texture is an image URL or a procedural texture such as `checker(8)` or `bumps(12,0.6)`. `uvScale` repeats the coordinates.
+- `alphaMode` is `auto` (default), `opaque`, `mask` or `blend`. `auto` is `blend` when `opacity` × colour alpha is below 0.999 and `opaque` otherwise. `opaque` ignores alpha. `mask` discards fragments below `alphaCutoff` (default 0.5). `blend` uses opacity as coverage. Texture alpha is visible only with `alphaMode="blend"` and an opacity below 1.
+- `doubleSided` and `unlit`.
+
+Texture coordinates, before `uvScale`:
+
+- Sphere: `u` is longitude, 0 at +X, increasing through −Z; `v` is 1 at the north pole and 0 at the south pole. The seam is the +X meridian.
+- Cylinder and cone: `u` runs around the axis, 0 at +X; `v` is 0 at the bottom and 1 at the top. Caps use a planar projection in XZ, centred at (0.5, 0.5).
+- Plane: the unit square in XZ, `u` along +X and `v` along −Z.
+- Box: each face is 0…1, with the face's normal as the projection axis.
+- Torus: `u` along the sweep from the +X side, `v` around the tube.
+
+Inheritance follows SVG's `fill`:
+
+- `material="id"` on any node sets the material for the node and its descendants, and **clears** an inherited colour override.
+- `color="…"` on any node overrides the base colour (of the inherited or own material) for the node and its descendants.
+- A `<use>` passes its material and colour down into the referenced content as *inherited* values; values set inside the definition win.
+- Without any material, shapes use the default material (light grey, roughness 0.5).
+
+Identical parameter sets are the same material; readers should deduplicate them (the reference reader binds each distinct material once per frame).
+
+## 12. Reuse and procedural placement
+
+### 12.1 `<defs>` and `<use>`
+
+Children of `<defs>` are not rendered. `<use ref="id">` renders the referenced element (from `<defs>` or anywhere else in the document) as if it were a child of the `<use>`, under the use's transform and style. A definition referenced N times exists once; readers should render repeated geometry with instancing. Reference cycles are errors.
+
+### 12.2 `<repeat>`
+
+`<repeat count="n" step="transform">` renders its children n times. Copy i (0-based) is placed with `step` applied i times:
+
+```
+world(copy i) = world(repeat) · stepⁱ · local(child)
+```
+
+so `step="translate(0,0.2,0.3) rotateY(15)"` builds a spiral staircase. `count="0"` renders nothing.
+
+### 12.3 `<scatter>` (normative algorithm)
+
+`<scatter>` places `count` copies of its children (or `grid="nx,nz"` copies) in its local XZ plane. Every reader must implement this algorithm exactly, in IEEE 754 binary64 with round-to-nearest. The random sequence is integer arithmetic. `sqrt` is `Math.sqrt` (correctly rounded). Disc positions and every rotation matrix use `es3dSin` and `es3dCos` below, in the order written, so two readers produce the same bits.
+
+1. The random generator is **mulberry32** seeded with the unsigned 32-bit `seed` (default 1):
+   ```js
+   function mulberry32(seed) {
+     let a = seed >>> 0;
+     return () => {
+       a = (a + 0x6d2b79f5) >>> 0;
+       let t = a;
+       t = Math.imul(t ^ (t >>> 15), t | 1);
+       t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+       return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+     };
+   }
+   ```
+2. For copy i = 0 … n−1, draw exactly nine values u0 … u8 in order (all nine are drawn even when unused, so adding an attribute never changes the positions of other attributes' effects).
+3. Position (y = 0):
+   - grid: ix = i mod nx, iz = ⌊i / nx⌋; x = (ix − (nx−1)/2)·spacingₓ + (u0 − ½)·jitter·spacingₓ, z = (iz − (nz−1)/2)·spacing_z + (u1 − ½)·jitter·spacing_z;
+   - disc (`radius` R): r = R·√u0, a = u1·2π, x = r·es3dCos(a), z = r·es3dSin(a);
+   - rectangle (`area` w,d): x = (u0 − ½)·w, z = (u1 − ½)·d.
+4. Rotation (degrees, Euler as in section 7): component k = lo_k + (hi_k − lo_k)·u(2+k) for the ranges of `randomRotation`.
+5. Scale: uniform `randomScale` range → s = lo + (hi − lo)·u5 for all axes; per-axis ranges use u5, u6, u7.
+6. Material: with `randomMaterial="a,b,c"`, copy i uses entry ⌊u8 · count⌋ (clamped to the last entry) and the inherited colour override is cleared.
+7. world(copy i) = world(scatter) · T(position) · R(rotation) · S(scale) · local(child).
+
+`grid` and `count` are mutually exclusive, as are `area` and `radius`; a random layout needs one of them.
+
+`es3dSin` and `es3dCos` take radians. π, 2π, π/2 and π/4 are `Math.PI`, `Math.PI * 2`, `Math.PI * 0.5` and `Math.PI * 0.25`. A non-finite input is returned unchanged. Otherwise:
+
+```
+y = x - 2π · round(x / 2π)
+sign = 1
+if y < 0: sign = -1; y = -y
+if y > π/2: y = π - y
+if y < 0: y = 0
+s = y > π/4 ? kernelCos(π/2 - y) : kernelSin(y)
+es3dSin(x) = sign < 0 ? -s : s
+es3dCos(x) = es3dSin(x + π/2)
+```
+
+`kernelSin` and `kernelCos` are Horner polynomials. `z = x*x`. Coefficients, as binary64 literals:
+
+```
+S1 = -1.66666666666666324348e-1
+S2 =  8.33333333332248946124e-3
+S3 = -1.98412698298579493134e-4
+S4 =  2.75573137070700676789e-6
+S5 = -2.50507602534068634195e-8
+S6 =  1.58969099521155010221e-10
+kernelSin(x) = x + (z*x) * (S1 + z * (S2 + z * (S3 + z * (S4 + z * (S5 + z * S6)))))
+
+C1 =  4.16666666666666019037e-2
+C2 = -1.38888888888741095749e-3
+C3 =  2.48015872894767294178e-5
+C4 = -2.75573143513906633035e-7
+C5 =  2.0875723212981748279e-9
+C6 = -1.13596475577881948265e-11
+r = z * (C1 + z * (C2 + z * (C3 + z * (C4 + z * (C5 + z * C6)))))
+kernelCos(x) = 1 - 0.5*z + z*r
+```
+
+Every add, subtract and multiply is one binary64 operation, in that order. `round` is `Math.round` (a tie at n+0.5 rounds towards +∞).
+
+### 12.4 `<lod>`
+
+`<lod distances="d1,d2,…">` has exactly one more child than distances (`E_LOD_CHILDREN`). Child i is rendered while the distance from the camera to the lod's world origin is below dᵢ (and at least dᵢ₋₁); the last child beyond the last distance. Distances are in the lod's local units (scaled by the cube root of the world scale's determinant). Exporters to static formats write child 0. Automatic per-primitive tessellation LOD (section 8.1) is independent of `<lod>`.
+
+### 12.5 Resource limits
+
+Exceeding a limit is an error. The document is not rendered as valid.
+
+| Limit | Value | Code |
+|---|---:|---|
+| Expanded instances (`repeat`, `scatter`, `use`) | 2,000,000 | `E_TOO_MANY_INSTANCES` |
+| Nesting, counting each element and each use-to-target step | 64 | `E_TOO_DEEP` |
+| Commands in one path, after implicit repetition | 100,000 | `E_PATH_LIMIT` |
+| Copies in one `repeat` or `scatter` | 1,000,000 | `E_RANGE` |
+
+## 13. Lights, cameras and environment
+
+- `<light type="directional|point|spot|ambient|hemisphere">` with `color`, `intensity`; directional and spot lights take `direction` or `target`; point and spot lights `position` and an optional cut-off `range`; spot lights `angle` (full cone, degrees) and `penumbra` (0–1); hemisphere lights `color` (sky) and `groundColor`. Lights are placed by their ancestors' transforms like any node. Without any light, readers use a default key light so content is visible.
+- `<camera>` is perspective (`fov`, vertical, degrees) or orthographic (`height` of the visible area). Orientation comes from `target` (and `up`) or from `rotation` (looking down −Z); giving both is an error. `near`/`far` are optional. The first camera is the initial view.
+- **Framing on other screens.** `fov` (or `height`) is the vertical extent of a view `aspect` wide and 1 high (default `aspect="1"`). `fit` says how a viewport of another aspect ratio a is filled, like SVG's `preserveAspectRatio`. With s = aspect / a, the vertical extent is scaled by:
+  - `contain` (default): max(1, s). The whole framed view stays visible ("meet").
+  - `cover`: min(1, s). The viewport is filled and the framed view is cropped ("slice").
+  - `width`: s. The framed width is kept.
+  - `height`: 1. The framed height is kept.
+
+  The defaults reproduce the usual rule of applying `fov` to the shorter viewport side. An author who framed a scene for a 16:9 page writes `aspect="1.778"`, and a portrait phone then shows the same width instead of cropping the sides.
+- `<environment>` sets the clear colour (`background`), hemisphere ambient colours (`sky`, `ground`), their `intensity`, and tone-mapping `exposure`. Only the first `<environment>` is used (`W_MULTIPLE_ENVIRONMENTS`).
+- `<controls>` describes how an interactive reader lets people move the camera. Only the first one is used (`W_MULTIPLE_CONTROLS`), and a document without one gets the reader's defaults (usually free orbiting).
+  - `mode="orbit"` (default): drag to orbit the target, pan and zoom; `zoom="false"` and `pan="false"` turn those off.
+  - `mode="none"`: a fixed view from the first camera.
+  - `mode="scroll"`: the first camera is the view, moved only by its scroll-timeline animations (section 14). Dragging is off and the canvas must not capture touch scrolling.
+  - Limits keep the camera between `minDistance` and `maxDistance` from its target and between `minPolar` and `maxPolar` degrees from straight up (`maxPolar="90"` keeps it above the target). `targetMin` and `targetMax` bound the orbit target, and so panning.
+  - `collide="true"` stops the camera in front of surfaces. A move from the last camera position to the next is blocked by the first surface whose front faces the camera (double-sided surfaces always block). The camera stays far enough from the surface that its near plane does not cut into it, and a move that hits a surface at an angle slides along it. A camera that starts inside an object can leave it, and an orbit target inside an object does not trap the camera. Elements with `collide="false"` (inherited by their children, available on every node) are ignored.
+
+## 14. Animation
+
+`<animate attr="…" dur="4s" …>` inside a node animates an attribute of its parent: `position`, `rotation` or `scale` of any node, and also `target` and `fov` of a `<camera>` (`E_INVALID_VALUE` elsewhere; animating the target of a camera oriented by `rotation` is `E_CONFLICTING_ATTRIBUTES`). Animation replaces the attribute value, so `transform` still applies outside it.
+
+**Values.** Exactly one source is given (`E_MISSING_ATTRIBUTE` without one, `E_CONFLICTING_ATTRIBUTES` with several):
+- `to` (with optional `from`, default: the parent's value): a straight interpolation.
+- `values="v0; v1; …"`: two or more key values separated by semicolons. With `keyTimes="0, t1, …, 1"` (one per value, starting at 0, ending at 1, not decreasing), value i is reached at fraction tᵢ. Without it the keys are evenly spaced. Between keys the value is linear, or with `smooth="true"` on a centripetal Catmull-Rom curve through the keys. The end keys are extended by reflecting their neighbour, as for sweep spines.
+- `along` (position and target only): a path in the same syntax as a sweep's spine (points, 3D path data or `helix()`; `smooth` interpolates points). The fraction is measured along the path's length, so the value moves at constant speed.
+
+Each value has 3 numbers (1 or 3 for `scale`, 1 for `fov`).
+
+**Timeline.** The animation turns a fraction f in 0..1 into a value, after `easing` (`linear`, `ease-in`, `ease-out`, `ease-in-out`) is applied to f.
+- `timeline="time"` (default): `dur` is required. Before `begin` the animation has no effect. Then it plays `repeat` cycles (default `indefinite`), with `alternate="true"` playing every second cycle backwards, and after the last cycle it holds the end value.
+- `timeline="scroll"`: f is the reader's scroll progress, clamped to 0..1, and `dur`, `begin`, `repeat` and `alternate` are not used. How progress relates to a page is up to the reader. The reference viewer maps a page section's scroll position to it, with optional stops pinned to page elements. A reader without a page holds progress at 0.
+
+## 15. Diagnostics
+
+Readers report problems in this canonical form:
+
+```
+ES3D Parse Error
+line 2, column 11
+
+Unknown attribute: raduis
+
+Did you mean: radius?
+```
+
+The title names the phase (`Parse`, `Reference`, `Geometry`, `Render`, `File`) and severity (`Error`, `Warning`). Codes used by the reference reader:
+
+| Group | Codes |
+|---|---|
+| Syntax | `E_SYNTAX`, `E_UNEXPECTED_EOF`, `E_MISMATCHED_TAG`, `E_UNEXPECTED_CLOSE`, `E_UNCLOSED_ELEMENT`, `E_UNQUOTED_ATTRIBUTE`, `E_UNTERMINATED_ATTRIBUTE`, `E_UNTERMINATED_COMMENT`, `E_UNTERMINATED_CDATA`, `E_UNTERMINATED_PI`, `E_UNTERMINATED_DOCTYPE`, `E_UNTERMINATED_STRING`, `E_BAD_ENTITY`, `E_BAD_ESCAPE`, `E_MULTIPLE_ROOTS`, `E_TEXT_OUTSIDE_ROOT`, `E_EMPTY_DOCUMENT`, `E_COMPACT_ROOT`, `E_JSON`, `E_JSON_STRUCTURE` |
+| Structure | `E_ROOT`, `E_VERSION`, `E_UNKNOWN_ELEMENT`, `E_MISPLACED_ELEMENT`, `E_TEXT_NOT_ALLOWED`, `E_MULTIPLE_SCENES` |
+| Attributes | `E_UNKNOWN_ATTRIBUTE`, `E_DUPLICATE_ATTRIBUTE`, `E_MISSING_ATTRIBUTE`, `E_MISSING_VALUE`, `E_INVALID_VALUE`, `E_TYPE`, `E_RANGE`, `E_CONFLICTING_ATTRIBUTES` |
+| References | `E_DUPLICATE_ID`, `E_UNKNOWN_REFERENCE`, `E_REFERENCE_KIND`, `E_CIRCULAR_REFERENCE` |
+| Geometry | `E_GEOMETRY`, `E_MESH`, `E_DEGENERATE`, `E_DEGENERATE_SPINE`, `E_REVOLVE_AXIS`, `E_LOD_CHILDREN`, `E_TOO_MANY_INSTANCES`, `E_TOO_DEEP`, `E_PATH_LIMIT` |
+| Warnings | `W_LEGACY_ROOT`, `W_EXTENSION`, `W_DEF_WITHOUT_ID`, `W_MATERIAL_WITHOUT_ID`, `W_MULTIPLE_ENVIRONMENTS`, `W_MULTIPLE_CONTROLS`, `W_DEGENERATE_CONTOUR`, `W_SELF_INTERSECTION`, `W_EMPTY_FILL`, `W_TEXTURE` |
+
+Unknown names get a suggestion when a known name is within a small edit distance or shares a prefix (`raduis` → `radius`, `spotlight` → `spot`, `sphear` → `sphere`).
+
+## 16. Extensibility and versioning
+
+- Elements whose names start with `x-` (and their subtrees) are vendor extensions: readers that do not understand them skip them with `W_EXTENSION`. Unknown elements without the prefix are errors, so typos are never mistaken for extensions.
+- Unknown attributes are always errors. (A future version may reserve an `x-` attribute prefix as well.)
+- `version="1.x"` documents must remain readable by version-1 readers; incompatible changes require version 2, which version-1 readers reject with `E_VERSION`.
+
+## 17. File names and media types
+
+| | |
+|---|---|
+| Text (any syntax) | `.es3d`, UTF-8, optionally gzip-compressed (`.es3d.gz`) |
+| Media type (proposed, unregistered) | `model/vnd.es3d` |