Add optional GLB compression stage

.trellis/tasks/08-03-experiment-glb-compression/report.md

@@ -0,0 +1,99 @@
+# GLB compression experiment report
+
+## Baseline
+
+Target: `nantaizi-lake-innovation-valley`
+
+- source GLB: `20.50 MB`
+- embedded images: `17.72 MB`
+- non-image buffers: `2.45 MB`
+- counts: `830` nodes, `113` meshes, `32` materials, `18` images, `675` accessors
+
+The file is texture-heavy, so texture resize / transcode is the primary lever.
+
+## Implemented
+
+Added `scripts/compress-glb.js` and `npm run compress:glb`.
+
+Default chain:
+
+```text
+gltf-transform resize -> gltf-transform webp
+```
+
+The script:
+
+- leaves source `.glb` intact
+- writes a separate compressed `.glb`
+- optionally copies metadata to point at the compressed GLB
+- optionally copies the existing Cesium preview HTML to point at compressed
+  metadata
+- prints `GLB_COMPRESS_DONE` with before/after size, image/non-image size,
+  counts, and extensions
+
+After visual review accepted the WebP result, added an explicit `compress`
+stage to `scripts/build-area.js`:
+
+```bash
+npm run build:area -- --config config/areas/nantaizi-lake-innovation-valley.json --stages compress
+```
+
+The stage calls the same script, writes `<fileStem>-compressed-webp768.*` by
+default, and remains outside `all`.
+
+## Results
+
+Commands:
+
+```bash
+npm run compress:glb -- --input outputs/nantaizi-lake-innovation-valley/nantaizi-lake-innovation-valley.glb --output outputs/nantaizi-lake-innovation-valley/nantaizi-lake-innovation-valley-compressed-webp1024.glb --metadata outputs/nantaizi-lake-innovation-valley/nantaizi-lake-innovation-valley.json --preview outputs/nantaizi-lake-innovation-valley/nantaizi-lake-innovation-valley-cesium-preview.html
+npm run compress:glb -- --input outputs/nantaizi-lake-innovation-valley/nantaizi-lake-innovation-valley.glb --output outputs/nantaizi-lake-innovation-valley/nantaizi-lake-innovation-valley-compressed-webp768.glb --texture-size 768 --metadata outputs/nantaizi-lake-innovation-valley/nantaizi-lake-innovation-valley.json --preview outputs/nantaizi-lake-innovation-valley/nantaizi-lake-innovation-valley-cesium-preview.html
+```
+
+Results:
+
+| Variant | Size | Image bytes | Non-image bytes | Structure |
+|---|---:|---:|---:|---|
+| source | `20.50 MB` | `17.72 MB` | `2.45 MB` | baseline |
+| WebP 1024 | `5.48 MB` | `2.73 MB` | `2.45 MB` | unchanged counts |
+| WebP 768 | `4.80 MB` | `2.04 MB` | `2.45 MB` | unchanged counts |
+
+Both WebP outputs keep `830` nodes, `113` meshes, `32` materials, `18` images,
+and `675` accessors. They introduce `EXT_texture_webp` and
+`KHR_texture_transform`.
+
+`scripts/glb-digest.js` can inspect both compressed GLBs and reports the same
+node/mesh/material/image/accessor counts as the source.
+
+Visual review in Cesium on 2026-08-03: the user compared the generated WebP
+preview and reported no obvious visible difference from the source preview.
+
+Extra experiments:
+
+- `optimize --texture-compress webp --texture-size 1024`: `4.29 MB`, but mesh
+  and material counts changed because `optimize` runs broader structural passes.
+- `meshopt + WebP 1024`: `3.66 MB` with direct `meshopt`, introducing
+  `EXT_meshopt_compression` and `KHR_mesh_quantization`.
+- KTX2 was blocked locally because glTF Transform requires external
+  KTX-Software `ktx`, which is not installed.
+
+## Recommendation
+
+Use the explicit `compress` stage for optional compressed Cesium review /
+delivery candidates. Keep the uncompressed GLB as the baseline artifact. Do not
+make Meshopt or KTX2 default until Cesium compatibility is verified visually.
+
+Generated preview candidates:
+
+- `outputs/nantaizi-lake-innovation-valley/nantaizi-lake-innovation-valley-compressed-webp1024-cesium-preview.html`
+- `outputs/nantaizi-lake-innovation-valley/nantaizi-lake-innovation-valley-compressed-webp768-cesium-preview.html`
+
+Validation:
+
+- `node --check scripts/compress-glb.js`
+- `node --check scripts/build-area.js`
+- `npm run build:area -- --config config/areas/nantaizi-lake-innovation-valley.json --stages compress`
+- `node scripts/glb-digest.js outputs/nantaizi-lake-innovation-valley/nantaizi-lake-innovation-valley-compressed-webp768.glb`
+- `node scripts/glb-digest.js outputs/nantaizi-lake-innovation-valley/nantaizi-lake-innovation-valley-compressed-webp1024.glb`
+- `python3 ./.trellis/scripts/task.py validate .trellis/tasks/08-03-experiment-glb-compression`
+- `git diff --check`