tooling: headless real-font screenshot via the Epsilon Linux simulator

Add docker/screenshot.sh + docker/Dockerfile.capture + docker/capture.sh
and a 'make screenshot' target: build the Epsilon Linux simulator, load the
app as a native shared object with a framebuffer-dumping entry point
(experimental/screenshot_main.cpp), and write capture/render.png with the
real NumWorks font. Documents why the web simulator can't load the app yet.

Author: 1e1

.gitignore

@@ -5,3 +5,4 @@ tests/test_engine
 *.nwa
 node_modules/
 .DS_Store
+capture/

Makefile

@@ -72,6 +72,11 @@ install: $(OUTPUT_DIR)/$(APP_NAME).nwa
 test:
 	$(MAKE) -C tests run
 
+# 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

@@ -129,6 +129,20 @@ Then open <http://localhost:8000/epsilon.html?nwb=/rpn.nwb>. The first run build
 the simulator (long; cached in a Docker volume afterwards). You can also build
 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.
+
+### Real-font screenshot (Docker)
+
+```shell
+make screenshot        # or: docker/screenshot.sh
+```
+
+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.
+
 ## Project layout
 
 ```

docker/Dockerfile.capture

@@ -0,0 +1,17 @@
+# Native (non-emscripten) environment to render the app in the Epsilon Linux
+# simulator and capture a real-font screenshot. Pass --platform matching your
+# host (docker/screenshot.sh does this) so host tools are built for the native
+# architecture — running an amd64 build tool under Rosetta breaks the font step.
+FROM ubuntu:24.04
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        build-essential git python3 python3-pil python3-lz4 imagemagick \
+        pkg-config libfreetype-dev libsdl2-dev libpng-dev libjpeg-dev \
+        nodejs npm ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY capture.sh /usr/local/bin/capture.sh
+RUN chmod +x /usr/local/bin/capture.sh
+
+WORKDIR /work
+ENTRYPOINT ["/usr/local/bin/capture.sh"]

docker/capture.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# Container entrypoint: build the Epsilon Linux simulator (once), build the RPN
+# app as a native shared object with a screenshot entry point that dumps the
+# framebuffer, run it headless, and convert the dump to /out/render.png.
+# Mounts: /epsilon (fork root), /app (this repo), /out (output dir).
+set -euo pipefail
+
+EPSILON=/epsilon/epsilon
+APP=/app
+OUT=/out
+BIN="$EPSILON/output/release/linux/epsilon.bin"
+
+[ -f "$EPSILON/Makefile" ] || { echo "!! mount the Epsilon fork ROOT at /epsilon" >&2; exit 1; }
+
+if [ ! -f "$BIN" ]; then
+  echo ">> Building the Epsilon Linux simulator — first run is long (reused after)…"
+  ( cd "$EPSILON" && make PLATFORM=linux -j"$(nproc)" epsilon.bin )
+fi
+
+CAP="$EPSILON/external_apps/rpn_capture"
+rm -rf "$CAP"; mkdir -p "$CAP/src"
+cp "$APP"/src/*.cpp "$APP"/src/*.h "$APP"/src/icon.png "$CAP/src/"
+rm -f "$CAP/src/main.cpp"
+cp "$APP"/experimental/screenshot_main.cpp "$CAP/src/main.cpp"
+sed -i 's#\.\./src/##' "$CAP/src/main.cpp"
+printf 'APP_NAME = rpn_capture\nAPP_ICON = src/icon.png\nOUTPUT_DIR = output\nSOURCES = $(wildcard src/*.cpp)\ninclude ../build/external_app.mak\n' > "$CAP/Makefile"
+
+echo ">> Building the app as a native shared object…"
+( cd "$CAP" && make PLATFORM=linux SIMULATOR="$BIN" build )
+NWB="$CAP/output/linux/rpn_capture.nwb"
+
+echo ">> Rendering headless and capturing the framebuffer…"
+( cd "$EPSILON" && timeout 40 "$BIN" --headless --take-screenshot /tmp/ignore.png --nwb "$NWB" || true )
+python3 -c "from PIL import Image; Image.open('$OUT/shot.ppm').save('$OUT/render.png')"
+rm -rf "$CAP" "$OUT/shot.ppm"
+echo ">> Wrote /out/render.png"

docker/screenshot.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# Render the app in the Epsilon Linux simulator and write a real-font screenshot
+# to capture/render.png — only Docker is needed.
+#
+#   docker/screenshot.sh
+#
+# Needs an Epsilon fork ROOT next to this repo (../epsilon), i.e. the folder
+# containing epsilon/, haussmann/, poincare/, shared/. Override with
+#   EPSILON_DIR=/path/to/epsilon docker/screenshot.sh
+set -euo pipefail
+
+APP_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+EPSILON_DIR="${EPSILON_DIR:-$APP_DIR/../epsilon}"
+OUT_DIR="${OUT_DIR:-$APP_DIR/capture}"
+
+if [ ! -f "$EPSILON_DIR/epsilon/Makefile" ]; then
+  echo "Epsilon fork root not found at: $EPSILON_DIR" >&2
+  echo "Set EPSILON_DIR to the fork root (contains epsilon/, haussmann/, …)." >&2
+  exit 1
+fi
+EPSILON_DIR="$(cd "$EPSILON_DIR" && pwd)"
+mkdir -p "$OUT_DIR"
+
+# Build host tools for the native arch (an amd64 tool under Rosetta breaks fonts).
+case "$(uname -m)" in
+  arm64|aarch64) PLATFORM=linux/arm64 ;;
+  *)             PLATFORM=linux/amd64 ;;
+esac
+
+docker build --platform "$PLATFORM" -t numworks-rpn-capture \
+  -f "$APP_DIR/docker/Dockerfile.capture" "$APP_DIR/docker"
+docker run --rm --platform "$PLATFORM" \
+  -v "$EPSILON_DIR":/epsilon \
+  -v "$APP_DIR":/app \
+  -v "$OUT_DIR":/out \
+  numworks-rpn-capture
+
+echo "Wrote $OUT_DIR/render.png"

experimental/screenshot_main.cpp

@@ -0,0 +1,69 @@
+// Screenshot build of the RPN app (native simulator only): prefills a stack of
+// representative symbolic values, draws once, then reads the framebuffer back
+// with eadk_display_pull_rect and writes it as a PPM to /out/shot.ppm. Used by
+// the headless capture harness; never shipped.
+extern "C" {
+#include <stdint.h>
+#include <stdio.h>
+}
+
+#include "../src/eadkpp.h"  // brings in eadk.h (pull_rect, eadk_rect_t, eadk_color_t)
+#include "../src/rpn.h"
+#include "../src/view.h"
+
+const char eadk_app_name[]
+#if PLATFORM_DEVICE
+    __attribute__((section(".rodata.eadk_app_name")))
+#endif
+    = "RPN";
+const uint32_t eadk_api_level
+#if PLATFORM_DEVICE
+    __attribute__((section(".rodata.eadk_api_level")))
+#endif
+    = 0;
+
+static void feed(Engine& e, const char* digits) {
+  for (const char* p = digits; *p; p++) {
+    char s[2] = {*p, 0};
+    e.appendText(s);
+  }
+}
+
+int main(int argc, char* argv[]) {
+  (void)argc;
+  (void)argv;
+  Engine e;
+  feed(e, "1"); e.execute(Command::EnterOrDup);
+  feed(e, "2"); e.execute(Command::Div);            // 1/2
+  feed(e, "2"); e.execute(Command::Sqrt);
+  feed(e, "3"); e.execute(Command::Sqrt);
+  e.execute(Command::Add);                          // √2 + √3
+  feed(e, "1"); e.execute(Command::EnterOrDup);
+  feed(e, "2"); e.execute(Command::Sqrt); e.execute(Command::Add);
+  feed(e, "2"); e.execute(Command::Pow);            // (1+√2)^2 = 3 + 2√2
+  e.execute(Command::PushPi);
+  feed(e, "2"); e.execute(Command::Div);            // π/2
+
+  View view;
+  view.draw(e, false, 0);
+
+  const int w = 320, h = 240;
+  static eadk_color_t buf[320 * 240];
+  eadk_rect_t full = {0, 0, w, h};
+  eadk_display_pull_rect(full, buf);
+
+  FILE* f = fopen("/out/shot.ppm", "wb");
+  if (f) {
+    fprintf(f, "P6\n%d %d\n255\n", w, h);
+    for (int i = 0; i < w * h; i++) {
+      uint16_t c = buf[i];  // RGB565
+      unsigned char rgb[3] = {
+          static_cast<unsigned char>(((c >> 11) & 0x1F) << 3),
+          static_cast<unsigned char>(((c >> 5) & 0x3F) << 2),
+          static_cast<unsigned char>((c & 0x1F) << 3)};
+      fwrite(rgb, 1, 3, f);
+    }
+    fclose(f);
+  }
+  return 0;
+}