openvistapro/docs/plans/wgpu-egui-architecture-spike.md

WGPU/egui Interactive App Architecture Spike

Goal: introduce an interactive OpenVistaPro app without destabilizing the existing CLI, importer pipeline, or deterministic CPU reference renderer.

Decision

Keep the repository as a single Rust crate for now.

The current boundary set is still moving, but it is already useful:

• src/terrain.rs, src/terrain_gen.rs, src/import.rs, src/scene.rs, src/scene_file.rs, src/script.rs, src/script_exec.rs, src/path.rs, src/render.rs, and src/colormap.rs are the clean-room core.
• src/cli.rs and src/main.rs are the command-line adapter.
• src/app_state.rs, src/ui_shell.rs, src/app.rs, and src/bin/openvistapro_app.rs are the optional interactive shell.

A workspace split into openvistapro-core, openvistapro-cli, and openvistapro-app would add maintenance overhead before there is a second renderer/backend boundary that truly justifies it. The better near-term move is to keep a monolith and enforce boundaries with modules, feature flags, and tests.

Revisit a workspace split only when at least one of these becomes true:

1. the GPU renderer needs materially different dependencies from the CLI/reference renderer,
2. the core API stabilizes enough that the app shell can depend on it as a published internal crate boundary, or
3. build times / dependency fanout make the single-crate layout painful.

Integration recommendation

Use egui as the interactive shell now, and treat WGPU as the rendering backend that arrives later behind a narrow viewport abstraction.

Recommended path:

1. Keep eframe for the windowing / egui host while the shell is still mostly controls and state.
2. Keep the current CPU renderer as the canonical reference output for tests and CLI smoke runs.
3. Introduce a tiny viewport trait or adapter boundary before any full GPU renderer lands.
4. Add a WGPU-backed viewport only once the render pipeline actually needs GPU surfaces, textures, and custom passes.

Why this order:

• eframe already gives a working egui host with the least glue.
• CLI builds stay GPU-free because the app stays behind the app feature.
• The CPU renderer remains the reference implementation for determinism and testability.
• WGPU can then become an implementation detail of the viewport, not a rewrite of the app state model.

Module boundaries

Keep the following responsibilities separate:

Core domain

• terrain.rs: immutable height grid and sampling rules.
• terrain_gen.rs: deterministic procedural generation inputs and output grid creation.
• import.rs: import boundary and source metadata.
• scene.rs: camera, lighting, hydrology, and palette-linked scene state.
• scene_file.rs: .ovp.toml persistence.
• script.rs / script_exec.rs: project-owned script language and executor.
• path.rs: MakePath-style camera path generation.
• render.rs: deterministic CPU render outputs.
• colormap.rs: palette / band mapping.

CLI adapter

• cli.rs should stay focused on argument parsing and orchestration.
• Keep it thin enough that the same core operations can be called from future automation or from the app shell.

Interactive shell state

• app_state.rs should remain pure state plus reducers / actions.
• ui_shell.rs should own section ordering, labels, and placeholder metadata.
• Avoid leaking egui types into either file.

egui view/controller

• app.rs should remain the presentation layer that turns AppData into panels, menus, and a preview texture.
• The shell should consume state snapshots and call backend actions, not embed render or import logic inline.

Future GPU viewport

• Introduce a narrow backend boundary for viewport rendering before the first custom WGPU renderer lands.
• Keep surface creation, texture upload, and draw passes out of AppData.
• Prefer a dedicated GPU adapter module over scattering WGPU setup across the UI code.

Minimal first app shell

The smallest durable shell is:

• a stable top command bar,
• a left or right dock for section-specific controls,
• a central viewport that can show the CPU preview now and a GPU surface later,
• a status bar for file paths, script status, and render feedback,
• a tiny about/help dialog for orientation.

That is already enough to validate layout, interaction, and state management without pretending the GPU renderer exists yet.

Testing strategy

Keep the test surface split the same way as the code.

Unit tests

• AppData reducers and state transitions.
• UiShellState navigation order and section metadata.
• render-mode selection and preview-state plumbing.
• scene / script / path / importer behavior.

Smoke commands

Use existing CLI and app entry points as smoke tests for the architecture:

• cargo run -- info
• cargo run -- render --preset fractal --seed 1337 --width 64 --height 64 --output /tmp/openvistapro-fractal.png
• cargo run --features app --bin openvistapro_app when a display is available

Later integration tests

Once the GPU viewport exists, add lightweight screenshot or frame-smoke coverage around the viewport adapter rather than baking WGPU assumptions into the core state model.

Next tasks

1. Add a small viewport abstraction so the egui shell can switch between CPU preview and a future GPU backend without changing AppData.
2. Keep the CPU renderer as the reference implementation for deterministic validation.
3. Add a dedicated GPU adapter module only when the WGPU surface truly exists.
4. Revisit a workspace split after the GPU path forces a second hard boundary.
5. Keep docs/knowledgebase/architecture-notes.md and docs/knowledgebase/ui-panel-map.md aligned with any later shell or viewport changes.

Recommendation summary

Stay monolithic now, keep egui as the host shell, and treat WGPU as a future viewport backend rather than the reason to split the crate today. That gives OpenVistaPro the fastest path to a usable interactive app while protecting the CLI and deterministic renderer from churn.