smoothlife/plans/04_raylib_visualization_workbench.md

Macrostep 04 — Raylib visualization workbench

Objective

Deliver the first useful interactive product: a portable, resize-safe raylib laboratory that runs the CPU backend and makes the rule, kernels, neighborhoods, and update logic visible.

Dependencies

Macrosteps 00–03 complete.

Phase 4.1 — Application lifecycle and scheduler

Substep 4.1.1 — Raylib ownership

Initialize and own raylib on the main thread. Keep handles out of the mathematical core. Establish explicit startup, running, backend-rebuild, and shutdown states so partial resource failures do not corrupt the model.

Substep 4.1.2 — Decoupled timing

Implement:

• render FPS independent of a fixed updates-per-second simulation clock;
• pause, single-step, reset, and an explicit finite advance N steps command that is not tied to rendering;
• bounded catch-up to avoid a spiral of death;
• headless benchmarking outside the render loop rather than an uncapped frame-driven mode;
• model dt independent of wall-clock tick duration.

Animations and camera movement are time-based, not frame-count-based.

Substep 4.1.3 — Unified action map

Map keyboard, mouse, and UI widgets to one Action enum. Retain practical legacy aliases (p, c, x/y, parameter pairs, preset cycling), but do not encode behavior directly in key handlers. Add a searchable/help overlay.

Phase 4.2 — Shared presentation primitives

Substep 4.2.1 — Scalar texture uploader

Convert CPU scalar fields to reusable raylib textures without allocating every frame. Start with a portable normalized or packed upload path; retain original f32 values in the model. Make filtering (nearest default, optional linear) explicit.

Substep 4.2.2 — Palettes

Implement named versions of all seven legacy palettes in one shared Rust/GLSL definition:

1. phase hue on black;
2. white on black;
3. black on white;
4. value rainbow;
5. brown/green;
6. gold/brown;
7. phase-shifted value rainbow.

Sanitize palette inputs and show a legend/range. Palette phase changes in units per second.

Substep 4.2.3 — Cameras

• 2-D uses a coherent Camera2D, cursor-centered wheel zoom, drag pan, reset, and fit-to-view.
• 1-D and 3-D placeholders use their own presentation state; do not overload simulation coordinates.
• Window resize changes presentation only, never simulation shape or state.

Phase 4.3 — Model and logic views

Substep 4.3.1 — Live state

Render the selected field at correct aspect ratio with periodic coordinate indicators. Display generation, update rate, render FPS, shape, seed, preset, dynamics, integrator, and backend.

Substep 4.3.2 — Read-only inspection

Provide a tab/grid selector for:

• A, M, N, S, derivative/increment, and proposed next state;
• raw/normalized disk and ring kernels;
• rule surface S(N,M) with labeled axes and current (N,M) probe;
• radial kernel profile and numeric value-under-cursor.

Inspection never modifies state. Keep c as an optional “next primary view” shortcut.

Substep 4.3.3 — Compare layout

Support at least a two-pane mode, for example A | S, M | N, or kernel | radial profile. All panes refer to the same committed generation and show stale-generation warnings if an async backend is introduced later.

Phase 4.4 — Configuration UI

Build a collapsible raylib-native panel (or a deliberately selected raygui binding after a compatibility spike) with sections:

• run/preset/variant;
• domain and initializer;
• rule intervals and curves;
• dynamics/integrator/timestep and RK4 relaxation reference when applicable;
• kernel geometry;
• backend, FFT algorithm, and performance;
• view/palette/camera;
• capture and diagnostics.

Classify edits visibly:

• Hot: presentation and pointwise rule edits; apply immediately.
• Warm: kernel geometry/timestep/integrator; rebuild caches and invalidate integration history as specified.
• Cold: shape, topology, variant, or backend; require transactional recreate/apply.

Provide sliders plus precise numeric entry. Show validation inline; never silently clamp model parameters to UI ranges.

Phase 4.5 — Presets, sessions, and capture

Substep 4.5.1 — Preset browser

Filter by variant/dimension/tags, show provenance and notes, and indicate modified (“dirty”) parameters. Applying a preset is transactional and logs the resulting run descriptor.

Substep 4.5.2 — Persistence

Persist user preferences separately from model presets. Add “save as user preset,” not append-to-bundled-file behavior. Save enough precision for exact round trips.

Substep 4.5.3 — Exports

Provide:

• viewport PNG, optionally with HUD;
• native field image with active palette;
• restart-state export (field plus metadata, numerical history resets on load);
• exact continuation checkpoint with integrator/variant history;
• metadata sidecar containing run descriptor and generation.

Use collision-safe timestamp/sequence names in the platform pictures/data directory.

Phase 4.6 — Robustness and UX tests

• Resize/minimize/fullscreen/high-DPI smoke tests.
• Launch from arbitrary working directories.
• Repeated valid/invalid warm and cold edits.
• Pause and single-step accuracy.
• Screenshot/state export while paused and running.
• Keyboard focus does not alter parameters while numeric input is active.
• Visible fallback if texture/shader creation fails.

Deliverables

• Portable raylib application using the CPU planar backend.
• Discoverable controls, inspectors, preset browser, and exports.
• Stable action, camera, palette, and presentation abstractions for later variants.

Exit gate

• A user can launch, choose a preset, reset with a seed, run/pause/step, edit parameters, and inspect every base pipeline channel.
• Headless and interactive CPU runs produce identical model states for equal commands.
• Resize and fullscreen never reset simulation.
• No inspection mode destroys or advances state.
• The application works outside the repository and reports failures visibly.