Mover Rendering Optimization Status

Goal + Scope Snapshot

Goal: stabilize mover rendering under load and remove dense motion-plan fallback work in runtime ship execution.
Scope: pathfinding motion plan pipeline (PathFinding, PathFinderStepper, MiniMapTransformer), ship executions, UnitLayer rendering/trails, perf overlay counters, and targeted tests.

Motion smoothing remains linear segment interpolation (no Bézier).
Budget model is soft: 3ms target + on-screen overrun allowance.
Rendering model uses persistent canvases (static units + dynamic movers + trails).
Dense runtime fallback generation in transport/trade executions is removed.
Perf instrumentation is added to the in-game performance overlay.

Files changed: mover-optim-status.md
What changed: Created the tracking document with required sections and format.
Why changed: Plan requires a live engineering log documenting each change batch and rationale.
Behavior impact: None.
Perf impact expected: None.
Validation done: File structure reviewed against requested format.

Files changed: src/core/pathfinding/PathFinder.ts, src/core/pathfinding/PathFinderStepper.ts, src/core/pathfinding/transformers/MiniMapTransformer.ts, src/core/execution/TransportShipExecution.ts, src/core/execution/TradeShipExecution.ts, src/core/game/MotionPlans.ts
What changed: Enabled smoothing in WaterSimple path pipeline, made PathFinderStepper.findPath() prime step cache, added collinear segment compression in MiniMapTransformer segment upscaling, removed dense LOS fallback usage from trade/transport ship plan emission, and removed now-unused dense LOS fallback helper from MotionPlans.
Why changed: Remove duplicated path work, guarantee segment-plan availability in runtime water path configurations, reduce jagged keypoint verbosity at minimap boundary, and eliminate dense-to-sparse recomputation in ship execution loops.
Behavior impact: Trade/transport motion plan emission now relies on pathfinder-native planSegments with defensive single-point fallback only if unexpectedly unavailable.
Perf impact expected: Fewer redundant findPath calls, reduced per-plan payload complexity after compression, and less runtime planning overhead in ship executions.
Validation done: Pending targeted tests and type-check run.

Files changed: src/client/graphics/layers/UnitLayer.ts, src/client/graphics/layers/UnitMotionRenderQueue.ts
What changed: Reworked mover rendering to persistent dynamic-canvas drawing with a versioned priority queue scheduler; introduced soft 3ms budget (+on-screen overrun), off-screen throttling cadence, and per-unit mover state (plan/version/error/debt/rect); unified trail rendering onto a single trail canvas rebuilt from transport+nuke trail stores; switched nuke trail storage to unit-id keyed maps with explicit dirty/rebuild lifecycle.
Why changed: Prevent frame-local disappearance when budget is exhausted, prioritize visible movers deterministically, and simplify/repair trail lifecycle consistency.
Behavior impact: Motion-planned units now persist visually between frames even when skipped by budget; transport trails remain until despawn; nuke trail cleanup is driven by tracked unit ids.
Perf impact expected: Reduced redraw churn (targeted rect clears), bounded per-frame mover work, and fewer full-context draw operations.
Validation done: Pending targeted tests and runtime checks.

Files changed: src/client/graphics/layers/Layer.ts, src/client/graphics/GameRenderer.ts, src/client/graphics/layers/PerformanceOverlay.ts, src/client/graphics/layers/UnitLayer.ts
What changed: Added optional layer perf-counter API, wired renderer tick loop to collect and forward counters, added PerformanceOverlay.updateLayerCounters(...) and a UnitLayer counters panel, and exposed UnitLayer queue/budget counters via getPerfCounters().
Why changed: Provide visibility into whether the new mover scheduler respects budget and where skips/debt accumulate.
Behavior impact: Performance overlay can now show live UnitLayer operational counters when visible.
Perf impact expected: Negligible overhead; counters are lightweight numeric snapshots.
Validation done: Pending targeted tests and smoke run.

Files changed: tests/PathFinderStepperPriming.test.ts, tests/MiniMapTransformerPlanSegments.test.ts, tests/UnitMotionRenderQueue.test.ts, tests/UnitLayerTrailLifecycle.test.ts, src/client/graphics/layers/TrailLifecycle.ts, src/client/graphics/layers/UnitLayer.ts
What changed: Updated stepper priming expectation, added minimap segment-compression invariant test, added queue ordering/stale-entry tests, and added trail lifecycle pruning tests via a new pure helper used by UnitLayer.
Why changed: Cover the new runtime behavior with focused tests and keep trail cleanup logic testable without DOM canvas harness complexity.
Behavior impact: No runtime feature change beyond factoring trail cleanup into a helper.
Perf impact expected: None in production; helper is linear-time over existing trail maps.
Validation done: Pending execution of targeted vitest files.

Files changed: mover-optim-status.md
What changed: Recorded targeted and broader validation runs with pass status.
Why changed: Close the loop on implementation quality and keep audit trail in a single status document.
Behavior impact: None.
Perf impact expected: None.
Validation done:
- npx vitest run tests/PathFinderStepperPriming.test.ts tests/MiniMapTransformerPlanSegments.test.ts tests/UnitMotionRenderQueue.test.ts tests/UnitLayerTrailLifecycle.test.ts ✅
- npx vitest run tests/MotionPlansSegments.test.ts tests/SmoothingWaterTransformerPlanSegments.test.ts tests/MiniMapTransformerPlanSegments.test.ts tests/PathFinderStepperPriming.test.ts tests/UnitMotionRenderQueue.test.ts tests/UnitLayerTrailLifecycle.test.ts ✅

Files changed: mover-optim-status.md
What changed: Added build/type-check validation outcome.
Why changed: Confirm no TypeScript or build regressions in production code paths, including UnitLayer and overlay integration.
Behavior impact: None.
Perf impact expected: None.
Validation done:
- npm run build-dev ✅ (tsc --noEmit + vite build)
- Existing non-blocking build warnings noted (pre-existing JSON import-attributes consistency warnings, chunk-size warnings).

Targeted mover/path tests passed (7/7).
Broader related motion-plan/pathfinding subset passed (10/10).
Note: vitest required escalated execution in this environment due esbuild spawn permissions (EPERM without escalation).
Type-check + development build passed via npm run build-dev.

Large UnitLayer refactor has integration risk (canvas composition + trail lifecycle + budgeting).
Need targeted tests to cover queue semantics and path compression invariants.