README.md

@@ -12,7 +12,7 @@ This repository currently contains:
 - A first-pass knowledgebase under `docs/knowledgebase/`.
 - An implementation roadmap under `docs/plans/`.
 - Legal and reference-material hygiene notes under `docs/legal/` and `docs/research/`.
-- A clean-room terrain import boundary with project-owned `ovp-text` fixtures and an SRTM/HGT byte importer behind the `hgt` Cargo feature.
+- A clean-room terrain import boundary with project-owned `ovp-text` fixtures, a PNG heightmap script importer, an SRTM/HGT byte importer behind the `hgt` Cargo feature, and an ESRI ASCII Grid parser behind the `ascii-grid-import` feature.
 
 ## Development
 
@@ -32,15 +32,20 @@ It opens an `eframe`/`egui` window titled `OpenVistaPro` with scene controls and
 
 Importer status:
 
-- `ovp-text`: project-owned plain-text heightfield fixture format used for tests.
+- `heightmap`: script execution can import grayscale PNG heightmaps with `import heightmap "path.png"` and map brightness to elevation.
+- `ovp-text`: project-owned plain-text heightfield fixture format used for import-boundary tests.
 - `hgt`: enabled by the optional `hgt` Cargo feature; parses SRTM HGT payloads as square grids of big-endian signed 16-bit metre samples. The implementation and tests use open specifications and synthetic/tiny fixtures only.
+- `esri-ascii-grid`: enabled by the optional `ascii-grid-import` Cargo feature; parses open ESRI ASCII Grid text with synthetic/project-owned fixtures only.
 
 To verify the importer feature surface:
 
 ```bash
+cargo test import
 cargo test hgt
 cargo test hgt --features hgt
+cargo test ascii_grid --features ascii-grid-import
 cargo run --features hgt --bin openvistapro -- info
+cargo run --features ascii-grid-import --bin openvistapro -- info
 cargo test --no-default-features
 ```
 
@@ -70,14 +75,19 @@ or one command:
 ```text
 use preset hill                              # `hill` or `plane`
 set thresholds water=0.18 tree=0.42 snow=0.77
-import heightmap "data/demo-height.png"
+import heightmap "data/demo-height.png"      # optional grayscale PNG terrain input
 render output "out/demo.png"
 ```
 
-Design goals for the MVP: one command per line for readable diffs,
-deterministic parsing with no I/O, and parse errors that carry a 1-based line
-number. This slice only parses scripts into an AST; executing those commands is
-intentionally left for a later card.
+Run the checked-in demo script with:
+
+```bash
+cargo run --bin openvistapro -- script run --input examples/demo.ovps
+```
+
+Script paths are resolved relative to the script file. `use preset` and
+`import heightmap` select the active terrain, `set thresholds` updates scene
+bands, and execution writes each `render output` to a deterministic PNG.
 
 ## Project principles
 

docs/knowledgebase/architecture-notes.md

@@ -1,16 +1,18 @@
 # Architecture Notes
 
-## Proposed Rust workspace structure
+## Current Rust module structure
 
 Start simple, then split into crates when module boundaries stabilize.
 
-- `src/terrain.rs`: height grid, bounds, sampling, normals, terrain transforms.
-- `src/import/`: importers for open/safe formats; historical compatibility later.
-- `src/scene.rs`: camera, target, light, atmosphere, water, vegetation parameters.
-- `src/render/`: CPU reference renderer first, then WGPU renderer.
-- `src/script.rs`: parse and execute OpenVistaPro script commands.
+- `src/terrain.rs`: height grid, bounds, sampling, and deterministic terrain fixtures.
+- `src/import.rs`: importers for open/safe formats (`ovp-text`, feature-gated HGT, feature-gated ESRI ASCII Grid); historical compatibility later.
+- `src/scene.rs` and `src/scene_file.rs`: camera, light, atmosphere, water/vegetation thresholds, and `.ovp.toml` persistence.
+- `src/render.rs`: deterministic CPU top-down renderer plus CPU perspective demo renderer; WGPU renderer later.
+- `src/script.rs` and `src/script_exec.rs`: parse and execute project-owned OpenVistaPro script commands.
+- `src/path.rs`: MakePath-inspired camera keyframe interpolation.
 - `src/colormap.rs`: palettes and elevation/biome color mapping.
-- `src/bin/openvistapro.rs` or current `src/main.rs`: CLI entry point.
+- `src/cli.rs` plus `src/main.rs`: CLI entry point for `info`, `scene export`, `render`, and `script run`.
+- `src/app_state.rs`, `src/app.rs`, and `src/bin/openvistapro_app.rs`: optional `app` feature shell built with `eframe`/`egui`.
 
 ## Suggested technology choices
 

docs/plans/initial-roadmap.md

@@ -183,11 +183,18 @@ Expected: image is created; no panic for reasonable scene defaults.
 ## Phase 4: Formats, scripts, UI
 
 - Add open DEM/HGT/GeoTIFF importers behind feature flags.
+  - Current importer surface: project-owned `ovp-text` fixtures, script-level PNG heightmap input, feature-gated SRTM/HGT byte parsing, and feature-gated ESRI ASCII Grid parsing.
+  - GeoTIFF remains a strategy/research item until a separate feature slice chooses a dependency boundary.
 - Define OpenVistaPro scene file format.
   - Initial implementation: `.ovp.toml` files with
     `schema = "openvistapro.scene"`, `version = 1`, and a serialized `Scene`
     payload. CLI support starts with
     `openvistapro scene export --output scene.ovp.toml` and
     `openvistapro render --preset hill --scene scene.ovp.toml --output out.png`.
-- Implement a VistaPro-inspired script language, then a MakePath-like spline path generator.
+- Implement a VistaPro-inspired script language and executor.
+  - Current CLI: `openvistapro script run --input examples/demo.ovps`.
+  - The syntax is project-owned and not legacy VistaPro-compatible.
+- Add a MakePath-like spline path generator.
+  - Current module: `src/path.rs` with deterministic keyframe interpolation used as a foundation for future animation output.
 - Build an interactive app with WGPU and egui after CLI renderer is stable.
+  - Current app shell: `cargo run --features app --bin openvistapro_app`; it uses `eframe`/`egui` scene controls and a CPU terrain preview while full WGPU terrain rendering remains future work.

docs/plans/phase-4-formats-scripts-ui.md

@@ -19,10 +19,14 @@ The repository already has:
 - `src/scene_file.rs`: project-owned `.ovp.toml` files with `schema = "openvistapro.scene"`, `version = 1`, and a serialized `Scene` payload.
 - `src/colormap.rs`: deterministic elevation-band colors.
 - `src/render.rs`: deterministic top-down PNG renderer plus spike-quality CPU perspective raymarcher.
-- `src/cli.rs`: `info`, `scene export`, and `render` commands.
+- `src/import.rs`: open-format import boundary with `ovp-text`, feature-gated SRTM/HGT bytes, and feature-gated ESRI ASCII Grid parsing.
+- `src/script.rs` and `src/script_exec.rs`: project-owned script parsing and execution for presets, grayscale PNG heightmaps, threshold changes, and PNG render outputs.
+- `src/path.rs`: deterministic MakePath-inspired camera keyframe interpolation.
+- `src/app_state.rs`, `src/app.rs`, and `src/bin/openvistapro_app.rs`: feature-gated `app` shell using `eframe`/`egui` with scene controls and CPU preview rendering.
+- `src/cli.rs`: `info`, `scene export`, `render`, and `script run` commands.
 - `README.md`, `docs/legal/asset-policy.md`, `docs/research/reference-inventory.md`, and `docs/knowledgebase/*.md`: clean-room context and project constraints.
 
-Phase 4 work should preserve this baseline and extend it in thin, tested slices.
+Phase 4 thin slices have landed as implementation checkpoints, while this file remains a historical implementation plan for follow-on work and validation.
 
 ## Non-negotiable clean-room and repository hygiene rules
 

tests/docs_conformance.rs

@@ -0,0 +1,34 @@
+#[test]
+fn readme_script_section_matches_executable_script_cli() {
+    let readme = include_str!("../README.md");
+
+    assert!(
+        readme.contains("cargo run --bin openvistapro -- script run --input examples/demo.ovps"),
+        "README should show the executable script-run command used by examples/demo.ovps"
+    );
+    assert!(
+        readme.contains("execut") && readme.contains("writes each `render output`"),
+        "README should describe current script execution behavior, not parser-only behavior"
+    );
+    assert!(
+        !readme.contains("only parses scripts into an AST"),
+        "README must not retain the pre-execution script MVP wording"
+    );
+}
+
+#[test]
+fn readme_lists_current_importer_surface() {
+    let readme = include_str!("../README.md");
+
+    for importer in ["`ovp-text`", "`hgt`", "`esri-ascii-grid`"] {
+        assert!(
+            readme.contains(importer),
+            "README should mention current importer {importer}"
+        );
+    }
+    assert!(
+        readme.contains("cargo test ascii_grid")
+            && readme.contains("cargo test ascii_grid --features ascii-grid-import"),
+        "README should document the ASCII-grid validation commands"
+    );
+}