chore: drop the screenshot harness, superseded by sim-test

docker/capture.sh substituted its own main() for src/main.cpp and drew one
prefilled stack, so it exercised neither the event loop nor the keymap, and it
needed its own Docker image plus the same Epsilon checkout. make sim-test covers
all of that and asserts, instead of producing a picture for a human to eyeball.

Removed: docker/capture.sh, docker/screenshot.sh, experimental/screenshot_main.cpp,
the screenshot target, the capture/ ignore rule. Dockerfile.capture is kept and
renamed Dockerfile.sim -- simtest.sh builds its image from it -- with its
dependency list aligned on the CI job that is proven to work: no libsdl2-dev
(Epsilon vendors SDL and links only -lX11 -lXext -ldl -lpthread), and no baked-in
entrypoint since the runner comes from the mounted repo.

Also: cap the simulator job at 30 min instead of 300 (measured 3.5 min cold,
~20 s warm on a 4-vCPU runner), and correct 1/(1+sqrt2) in README and
CONTRIBUTING -- both still claimed sqrt2-1 where the engine prints -1 + sqrt2,
the same error already fixed in the CHANGELOG.

Author: 1e1

.github/workflows/ci.yml

@@ -57,9 +57,10 @@ jobs:
   # 32 KiB.
   simulator:
     runs-on: ubuntu-latest
-    # Building Epsilon from scratch takes hours on a 4-vCPU runner; it happens
-    # once per EPSILON_REF and is cached afterwards. The cap is a backstop.
-    timeout-minutes: 300
+    # Measured on a 4-vCPU runner: ~3.5 min to build Epsilon from scratch, ~20 s
+    # once the cache is warm. The cap is a backstop against a hung build, with
+    # room for Epsilon to grow — not a budget to fill.
+    timeout-minutes: 30
     env:
       # Pinned on purpose: the scenarios compare screenshots pixel for pixel, so
       # an Epsilon font or layout change would fail them for no fault of ours.

.gitignore

@@ -5,7 +5,6 @@ tests/test_engine
 *.nwa
 node_modules/
 .DS_Store
-capture/
 *.dSYM/
 __pycache__/
 *.pyc

CONTRIBUTING.md

@@ -25,8 +25,8 @@ src/
   utf8.h               UTF-8 glyph counter (shared by layout + screen)
   eadkpp.h             C++ wrapper over the External App Dev Kit
   main.cpp             event loop + app metadata
-tests/                 host unit tests + PNG render harnesses
-docker/                web simulator (run.sh) + real-font screenshot (screenshot.sh)
+tests/                 host unit tests, PNG render harnesses, sim/ scenarios
+docker/                web simulator (run.sh) + simulator tests (simtest.sh)
 docs/                  GitHub Pages: landing page, interactive key map, ROADMAP
 .github/               CI / Release (rc + retention prune) / Pages workflows
 ```
@@ -39,13 +39,12 @@ device build also needs `arm-none-eabi-gcc`.
 ```shell
 make              # device app  -> output/rpn.nwa
 make install      # build + upload to a plugged-in calculator
-make test         # host unit tests for the engine (no calculator needed)
-make PLATFORM=web # web app .nwb (needs emcc)
+make test           # host unit tests for the engine (no calculator needed)
 make verify-install # perform the install-time link, no calculator needed
 make check-budgets  # assert the RAM and 32 KiB-stack budgets
-make sim-test     # replay tests/sim in the Epsilon simulator (Docker)
-make screenshot   # real-font render via the Epsilon Linux simulator (Docker)
-docker/run.sh     # run the app in the Epsilon web simulator (Docker)
+make sim-test       # replay tests/sim in the Epsilon simulator (Docker)
+make PLATFORM=web   # web app .nwb (needs emcc)
+docker/run.sh       # run the app in the Epsilon web simulator (Docker)
 ```
 
 The engine and layout are pure C++ with no calculator dependency, so `make test`
@@ -69,7 +68,7 @@ The exact form is a canonical *polynomial in atoms*: `Σ coeff · Π atom^e`, wh
 an atom is `π`, a variable, `√(sub-expression)`, or `1/(sub-expression)`. This
 represents fractions, `k√m`, rational multiples of π and their
 sums/products/integer powers, **nested radicals** (`√(1+√2)`) and **conjugate
-division** (`1/(1+√2)` → `√2−1`). Anything outside it (transcendental functions,
+division** (`1/(1+√2)` → `-1 + √2`). Anything outside it (transcendental functions,
 overflow, or exceeding the arena) falls back to a double — **never a wrongly
 exact result**.
 

Makefile

@@ -1,9 +1,13 @@
 # Build the NumWorks RPN external app.
 #
 #   make                     device app   -> output/rpn.nwa   (arm-none-eabi)
+#   make PLATFORM=simulator  Epsilon simulator app -> output/simulator/rpn.nwb
 #   make PLATFORM=web        web app      -> output/rpn.nwb   (emscripten)
 #   make install             upload to a plugged-in calculator
 #   make test                build & run the host engine tests
+#   make verify-install      perform the install-time link (no calculator)
+#   make check-budgets       assert the RAM and 32 KiB-stack budgets
+#   make sim-test            replay tests/sim in the Epsilon simulator (Docker)
 #   make clean
 #
 # Requirements: node/npx (nwlink); arm-none-eabi-gcc for device; emcc for web.
@@ -44,8 +48,7 @@ ifeq ($(PLATFORM),device)
 else ifeq ($(PLATFORM),simulator)
   # Native shared object dlopen'd by the Epsilon Linux/macOS simulator
   # (`epsilon.bin --nwb`). Same sources and same main() as the device app, so
-  # the real event loop and keymap are what gets exercised — unlike the
-  # screenshot harness, which substitutes its own main.
+  # the real event loop and keymap are what gets exercised.
   #
   # No LTO, no --gc-sections, no -fvisibility=internal here: the simulator
   # resolves main and eadk_app_name through dlsym, and those flags would hide
@@ -133,11 +136,6 @@ sim-test:
 sim-test-update:
 	docker/simtest.sh --update
 
-# Render the app in the Epsilon Linux simulator -> capture/render.png (Docker).
-.PHONY: screenshot
-screenshot:
-	docker/screenshot.sh
-
 .PHONY: clean
 clean:
 	rm -rf $(OUTPUT_DIR)

README.md

@@ -28,7 +28,7 @@ NumWorks feel, RPN-style.
 > **expression tree** kept in a canonical polynomial-in-atoms form. It keeps
 > exact fractions, `k√m`, rational multiples of π, their sums/products/integer
 > powers, **nested radicals** (`√(1+√2)`) and **conjugate division**
-> (`1/(1+√2)` → `√2−1`), and it carries symbolic variables. Transcendental
+> (`1/(1+√2)` → `-1 + √2`), and it carries symbolic variables. Transcendental
 > functions (`sin`, `ln`), integer overflow, or exceeding the on-device arena
 > fall back to a decimal — so a result is never *wrongly* exact. The engine is
 > STL-free with a compacting garbage collector over a fixed arena.
@@ -139,17 +139,20 @@ the web app alone with `make PLATFORM=web` (needs `emcc`).
 
 > **Note.** Loading the app in the *web* simulator is not wired up yet (our side
 > module needs libc/soft-float symbols Epsilon's size-deduped main module does
-> not export). To see a real-font render, use the native capture below.
+> not export). For a real-font render, use `make sim-test` below.
 
-### Real-font screenshot (Docker)
+### Automated runs in the Epsilon simulator (Docker)
 
 ```shell
-make screenshot        # or: docker/screenshot.sh
+make sim-test          # replay every scenario
+make sim-test-update   # rewrite the reference screenshots — review them
 ```
 
-Builds the Epsilon **Linux** simulator, renders the app headless with a sample
-stack, and writes `capture/render.png` — the actual NumWorks font, no browser
-needed.
+Builds the Epsilon **Linux** simulator, loads the app as a real external app and
+replays the key sequences in `tests/sim/scenarios/` headless, comparing each
+320×240 frame with `tests/sim/expected/` pixel for pixel. Real NumWorks fonts, no
+browser. This is the only test that runs `src/main.cpp` itself, so the event loop,
+the keymap and the Toolbox menu are covered.
 
 ## Project layout
 
@@ -167,7 +170,7 @@ src/
   utf8.h               UTF-8 glyph counter (shared by layout + screen)
   eadkpp.h             C++ wrapper over the External App Dev Kit
   main.cpp             event loop + metadata
-tests/                 host unit tests + PNG render harnesses
+tests/                 host unit tests, PNG render harnesses, sim/ scenarios
 docs/                  GitHub Pages landing page
 ```
 

docker/Dockerfile.capture

@@ -0,0 +1,24 @@
+# Native (non-emscripten) environment for `make sim-test`: builds the Epsilon
+# Linux simulator and replays tests/sim/scenarios against the app inside it.
+#
+# Pass --platform matching your host (docker/simtest.sh does) so the host tools
+# Epsilon builds — notably the font rasterizer — are native; an amd64 tool under
+# Rosetta breaks the font step.
+#
+# Dependency list mirrors the simulator job in .github/workflows/ci.yml. Note
+# there is no libsdl2-dev: Epsilon vendors SDL under
+# shared/ion/src/simulator/external/sdl and compiles it itself, linking only
+# -lX11 -lXext -ldl -lpthread. freetype feeds the font rasterizer; python3-pil,
+# python3-lz4 and imagemagick the image pipeline.
+FROM ubuntu:24.04
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        build-essential python3 python3-pil python3-lz4 imagemagick \
+        pkg-config libfreetype-dev libx11-dev libxext-dev \
+        libpng-dev libjpeg-dev \
+        nodejs npm ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+# The runner script comes from the mounted repo (docker/simtest.sh points
+# --entrypoint at /app/docker/sim.sh), so nothing is baked into the image.
+WORKDIR /work

docker/Dockerfile.sim

@@ -27,7 +27,7 @@ case "$(uname -m)" in
 esac
 
 docker build --platform "$PLATFORM" -q -t numworks-rpn-sim-test \
-  -f "$APP_DIR/docker/Dockerfile.capture" "$APP_DIR/docker" >/dev/null
+  -f "$APP_DIR/docker/Dockerfile.sim" "$APP_DIR/docker" >/dev/null
 
 exec docker run --rm --platform "$PLATFORM" \
   --entrypoint /app/docker/sim.sh \