chore(task): archive 08-03-smooth-cesium-preview-vehicle-cruise

.trellis/tasks/archive/2026-08/08-03-smooth-cesium-preview-vehicle-cruise/prd.md

@@ -0,0 +1,67 @@
+# Smooth Cesium preview vehicle cruise
+
+## Goal
+
+Improve perceived smoothness of vehicle cruise in the Cesium preview for
+`nantaizi-lake-innovation-valley` while the scene model is visible, especially
+when Follow passes through scrub-heavy areas.
+
+The initial preview-layer optimization helped but did not solve the root cause:
+closing `Scene` helps a lot, and the current nantaizi GLB contains about 707
+scrub bush nodes. The root fix is allowed to reduce scrub bush instance density
+while preserving the flat scrub ground cover and existing preview controls.
+
+## Requirements
+
+1. Optimize `scripts/lib/cesium-preview.js` so vehicle animation does less
+   per-frame work during cruise without reducing default visual clarity.
+2. Preserve existing controls and behavior:
+   - Play/Pause still drives `viewer.clock.shouldAnimate`.
+   - Speed slider still maps m/s to clock multiplier.
+   - Vehicle selection still chooses the follow target.
+   - Scene/routes/vehicles/FPS/diagnostics toggles still work.
+   - Follow mode still tracks the selected vehicle.
+3. Keep the preview layer dependency-free and browser-native; no build step,
+   npm dependency, module system, or hard-coded area filenames.
+4. Reduce scrub edge bush instance density in `blender/generate_scene.py` to
+   lower Cesium render load in scrub-heavy Follow views. Preserve deterministic
+   sampling, scrub ground polygons, scrub tree sampling, and scene stats fields.
+5. Regenerate or copy the updated preview JS into
+   `outputs/nantaizi-lake-innovation-valley/cesium-preview.js` only if needed
+   for local manual verification; do not commit generated outputs.
+6. Rebuild `nantaizi-lake-innovation-valley` `blender,cesium,preview` outputs
+   for manual validation. This task intentionally changes generated GLB
+   structure, so full parity-identical output is not expected.
+
+## Acceptance Criteria
+
+- [ ] `scripts/lib/cesium-preview.js` has a small, reviewable optimization that
+      reduces per-frame allocations or render overhead for vehicle cruise.
+- [ ] `blender/generate_scene.py` reduces nantaizi scrub bush node count by at
+      least 50% while keeping scrub polygons present.
+- [ ] Vehicle controls listed in Requirements continue to work by inspection
+      and/or local smoke check.
+- [ ] Blender/Cesium rebuild for `nantaizi-lake-innovation-valley` completes
+      and generated metadata still includes scrub counts.
+- [ ] `node --check scripts/lib/cesium-preview.js` passes.
+- [ ] `python3 -m py_compile blender/generate_scene.py` passes.
+- [ ] If local output preview JS is updated for testing, it remains ignored and
+      is not committed.
+
+## Out Of Scope
+
+- Full scene geometry/material optimization beyond scrub edge bush density.
+- Reducing tree count or changing road/building/water assets.
+- Replacing Cesium or adding profiling libraries.
+- Visual design changes to the preview UI.
+
+## Technical Notes
+
+- User confirmed closing `Scene` improves smoothness, so the scene render load
+  is a real contributor.
+- Current route data is small: `nantaizi-lake-innovation-valley` has 9 route
+  segments and the preview uses at most 5 vehicles.
+- Current nantaizi GLB has 1271 nodes; about 707 are scrub bush nodes. Lowering
+  scrub edge sampling from `0.82m / 180 per patch` to `1.8m / 60 per patch`
+  should reduce nantaizi bush samples to about 266 while leaving scrub ground
+  cover intact.