@hypersoniclabs/helix-cli 0.1.25-helix3.520 → 0.1.25-helix3.521

package/docs/item-lod.md

@@ -239,8 +239,45 @@ empty gutters so filtering shows no dark fringes. Transparent materials are draw
 range); cutouts keep their alpha test.
 
 Capture runs in the shared placements capture host (`src/placements/captureHost.ts`): bundled headless Chromium, localhost
-only, one browser at a time under the host slot cap, never the system Chrome. The impostor has no normal map, so a runtime
-shades it flat; adding a normal atlas is a follow-up that needs a second object in the artifact.
+only, one browser at a time under the host slot cap, never the system Chrome. An `albedo` or `lit/1` impostor has no normal
+map, so a runtime cannot light it for the scene it stands in; the `gbuffer/1` impostor below is that second object.
+
+### `gbuffer/1`: a runtime-lit impostor (`item-lod/5`, `hemi-oct/1`)
+
+`compileItemLods(glb, { source, shading: 'gbuffer/1' })` bakes what a light needs instead of a light: the surface, not its
+shading. It is a contract of its own because it is neither read like `lit/1` nor laid out like it, and it is **not served yet**:
+`'gbuffer/1'` is deliberately absent from `ITEM_LOD_SHADINGS`, so the CLI's `--shading` flag does not accept it and no published
+Package version has one. The backend compiles `item-lod/5` next to `/4` and `/3` and serves it to a read that declares `gbuffer/1`
+(phase 2 of the impostor-gbuffer lane); an engine before it keeps its `lit/1` or albedo rendition.
+
+* **Layout `hemi-oct/1`** (`impostor.layout`): 8 x 8 views over the UPPER hemisphere only. Frame `(i, j)` has `u = 2i/7 - 1`,
+  `v = 2j/7 - 1`, `x = (u + v)/2`, `z = (u - v)/2`, `y = 1 - |x| - |z|`, normalised. The outer ring of 28 frames lies exactly on the
+  horizon (gaps of 9.5 to 16.2 degrees of azimuth) and the four corners look along the item axes. A viewer at or below the
+  horizon reads the ring, so it is looked at from where it stands. The full-sphere `oct/1` layout the other shadings use
+  spends half its frames below the ground and its nearest ring sat at 9.5 to 13 degrees ELEVATION: a car seen from 0.5 degrees
+  was drawn from above, with roof and bonnet over-represented, which was the whole of the +7 to +25 percent over-brightness
+  measured before the layout changed (a camera-elevation sweep of the same atlas; the lab reproduced it and the layout closes it).
+* **Maps** (`impostor.maps`, one KTX2 UASTC object each, 512 px, mips): `impostor.object` is `A`, sRGB albedo with the
+  coverage in alpha; `maps.surface` is `B`, linear: view-space normal x and y (z is rebuilt as `sqrt(1 - x² - y²)`), roughness,
+  metalness; `maps.emissive` is `C`, sRGB, emissive radiance / 4 in RGB (`scale: 0.25`) and the clear coat amount in alpha
+  (`clearcoat`), present only when at least 8 texels glow or are coated. View-space normals mean each baked view's own camera
+  frame (x right, y up, z to the viewer); the engine turns them into item space per frame and then into the scene's view space.
+* **Passes**: four captures per view (albedo, normal, material, emissive) of the source's own PBR values, written by small
+  `ShaderMaterial`s that output the quantity instead of a colour; supersampled (`IMPOSTOR_SSAA`) and reduced, then each map
+  dilated into the empty texels of its view cell so filtering at a silhouette mixes in no black. Rows are bottom first.
+* **Artifact**: `impostor.shading: "gbuffer/1"`, `impostor.layout: "hemi-oct/1"`, `impostor.maps`, no `bakeScale`; `compiler`
+  is `item-lod/5` (`ITEM_LOD_COMPILER_FOR_SHADING`). The schema id stays `helix.item-lod/1`; a reader that does not know
+  `impostor.shading` must not draw the document, which is why the backend serves it only to a declaration.
+* **Omission rule**: the `lit/1` rule (omit when the atlas is not smaller than the source GLB) would drop the impostor of a heavy
+  item with small textures, which has no other far representation and whose far placements are two triangles each, because the
+  impostor now carries up to three maps. A `gbuffer/1` impostor is omitted only when the source is at most 300 triangles AND
+  the maps are at least twice the source bytes (`GBUFFER_MIN_TRIANGLES`, `GBUFFER_BYTES_SLACK`);
+  `estimatedBytes.impostor` is the resident cost of all the maps, and `report.json` has `shading` and `maps`.
+* **Measured** (2026-10-11, lab `run/impostor-gbuffer-2026-10-11`): the sedan baked on this Mac's SwiftShader capture host takes
+  about 14 s for the impostor (23 s for the whole compile with both LODs): `A` 105 KB, `B` 131 KB, `C` 12 KB.
+
+Tests: `src/itemLod/gbuffer.spec.ts` (layout, packing, dilation, KTX2 encode; two real-browser captures) and
+`src/itemLod/artifact.spec.ts` "gbuffer/1 impostor" (artifact shape, validation, omission rule, the `lit/1` rule unchanged).
 
 ## Textures that cannot be decoded
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypersoniclabs/helix-cli",
-  "version": "0.1.25-helix3.520",
+  "version": "0.1.25-helix3.521",
   "description": "helix — the HELIX creator CLI: scaffold, validate, and publish Instant Worlds",
   "main": "dist/lib.js",
   "types": "dist/lib.d.ts",