RPN v2.0.0 — symbolic stack with 2D rendering

The stack value is a bounded sum of terms  Σ (num/den)·√rad·πⁿ:

- Exact fractions, k·√m, rational multiples of π and their sums, products
  and integer powers stay exact: 8 √ 2 × → 4√2, π 2 ÷ → π/2, √2+√3,
  (1+√2)² → 3+2√2, (√2+√3)(√2−√3) → -1; like terms are collected.
- Nested radicals, division by a sum, transcendental functions, overflow
  or more than 8 terms fall back to a decimal — never a wrongly-exact result.
- 2D rendering on the stack (stacked fractions, radicals with a vinculum,
  raised exponents) via a backend-agnostic layout engine; every level shows
  its exact form, level 1 also its decimal (≈). The layout code feeds both
  the EADK screen and a host PNG harness (make -C tests render / render-screen).
- Overflow-checked int64 throughout; π exact; factorial via gamma.
- Pure host-tested core (make test, 47 checks); device build via nwlink.
- Makefile supports PLATFORM=web (.nwb via emcc); docker/ runs the app in the
  Epsilon web simulator in a browser with only Docker installed.
- R↵ identity across the .nwa, README, site and interactive N0120 key map;
  slogan, badges; landing page, roadmap and CHANGELOG.

Author: 1e1

.github/workflows/release.yml

@@ -31,15 +31,21 @@ jobs:
       - name: Stage release asset
         run: cp output/rpn.nwa rpn-${{ github.ref_name }}.nwa
 
-      - name: Create GitHub Release
+      - name: Publish GitHub Release (idempotent)
         env:
           GH_TOKEN: ${{ github.token }}
+          TAG: ${{ github.ref_name }}
         run: |
-          gh release create "${{ github.ref_name }}" \
-            "rpn-${{ github.ref_name }}.nwa#RPN app (${{ github.ref_name }}) — install via my.numworks.com/apps" \
-            --title "RPN ${{ github.ref_name }}" \
-            --notes "RPN calculator for NumWorks.
+          FILE="rpn-${TAG}.nwa"
+          if gh release view "$TAG" >/dev/null 2>&1; then
+            echo "Release $TAG exists — updating asset."
+            gh release upload "$TAG" "$FILE" --clobber
+          else
+            gh release create "$TAG" "${FILE}#RPN app (${TAG}) — install via my.numworks.com/apps" \
+              --title "RPN ${TAG}" \
+              --notes "RPN calculator for NumWorks.
 
-          **Install:** download \`rpn-${{ github.ref_name }}.nwa\` below, then open <https://my.numworks.com/apps>, plug in your calculator and upload the file.
+          **Install:** download \`rpn-${TAG}.nwa\` below, then open <https://my.numworks.com/apps>, plug in your calculator and upload the file.
 
           See the [project page](https://1e1.github.io/numworks-RPN/) for the full key map."
+          fi

CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this project are documented here. This project follows
+[Semantic Versioning](https://semver.org/).
+
+## v2.0.0 — Symbolic stack
+
+- The stack value is now symbolic: exact results are kept as a bounded **sum of
+  terms** `Σ (num/den)·√rad·πⁿ`.
+  - `8 √ 2 ×` → `4√2`, `π 2 ÷` → `π/2`, `√2·√2` → `2`, `1/√2` → `√2/2`.
+  - Sums stay exact too: `√2 + √3`, `π + 1`, `(1+√2)²` → `3+2√2`,
+    `(√2+√3)(√2−√3)` → `-1`; like terms are collected (`√2+√2` → `2√2`).
+- Anything outside that form (nested radicals, division by a sum, `sin`, `ln`,
+  overflow, or more than 8 terms) falls back to a decimal approximation — a
+  result is never *wrongly* exact.
+- **2D rendering** on the stack: stacked fractions, radicals with a vinculum and
+  raised exponents; every level shows its exact form and level 1 also shows its
+  decimal approximation (`≈`).
+- π is an exact constant; `→Dec` (`Ans`) forces the decimal form.
+- Factorial now uses `gamma(n+1)` for large or non-integer arguments instead of
+  an unbounded loop.
+- All arithmetic remains overflow-checked `int64` with a decimal fallback.
+
+## v1.0.0 — First release
+
+- Reverse Polish Notation calculator as a NumWorks external app (`.nwa`).
+- Exact rational arithmetic for `+ − × ÷` and integer powers; IEEE double for
+  transcendental functions.
+- Stack-oriented key map: operator keys act on the stack, RPN-unused keys become
+  stack operations, `Toolbox` opens a stack menu; RAD/DEG angle mode.
+- Pure, host-tested numeric core (`make test`); device build via `nwlink` and
+  `arm-none-eabi`.
+- GitHub Actions for CI, tagged releases and a GitHub Pages site with an
+  interactive N0120 key map.

Makefile

@@ -1,55 +1,65 @@
-# Self-contained build for the NumWorks RPN external app.
+# Build the NumWorks RPN external app.
 #
-#   make            build the device app  -> output/rpn.nwa
-#   make test       build & run the host engine tests
-#   make install    build and upload to a plugged-in calculator
+#   make                     device app   -> output/rpn.nwa   (arm-none-eabi)
+#   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 clean
 #
-# Requirements: arm-none-eabi-gcc (device build) and node/npx (nwlink).
+# Requirements: node/npx (nwlink); arm-none-eabi-gcc for device; emcc for web.
 
 APP_NAME = rpn
 APP_ICON = src/icon.png
 OUTPUT_DIR = output
+PLATFORM ?= device
 
 NWLINK = npx --yes -- nwlink
 
-CC = arm-none-eabi-gcc
-CXX = arm-none-eabi-g++
-
 SOURCES = $(wildcard src/*.cpp)
-OBJS = $(patsubst src/%.cpp,$(OUTPUT_DIR)/%.o,$(SOURCES))
-
-# Flags provided by nwlink for the calculator target (Cortex-M7 + EADK headers).
-EADK_CFLAGS := $(shell $(NWLINK) eadk-cflags-device)
-EADK_LDFLAGS := $(shell $(NWLINK) eadk-ldflags-device)
-
-CXXFLAGS = $(EADK_CFLAGS) -std=c++11 -fno-exceptions -Wall -Os -MMD -MP
-CXXFLAGS += -fdata-sections -ffunction-sections
-CXXFLAGS += -flto -fno-fat-lto-objects -fwhole-program -fvisibility=internal
-
-LDFLAGS = $(EADK_LDFLAGS) --specs=nano.specs
-LDFLAGS += -Wl,-e,main -Wl,-u,eadk_app_name -Wl,-u,eadk_app_icon -Wl,-u,eadk_api_level
-LDFLAGS += -Wl,--gc-sections -flinker-output=nolto-rel
-# Pull float support into newlib-nano's printf so decimals render (%g).
-LDFLAGS += -Wl,-u,_printf_float
+OBJDIR = $(OUTPUT_DIR)/$(PLATFORM)
+OBJS = $(patsubst src/%.cpp,$(OBJDIR)/%.o,$(SOURCES))
+
+ifeq ($(PLATFORM),device)
+  CC = arm-none-eabi-gcc
+  CXX = arm-none-eabi-g++
+  EADK_CFLAGS := $(shell $(NWLINK) eadk-cflags-device)
+  CXXFLAGS = $(EADK_CFLAGS) -std=c++11 -fno-exceptions -Wall -Os -MMD -MP
+  CXXFLAGS += -fdata-sections -ffunction-sections
+  CXXFLAGS += -flto -fno-fat-lto-objects -fwhole-program -fvisibility=internal
+  LDFLAGS = $(shell $(NWLINK) eadk-ldflags-device) --specs=nano.specs
+  LDFLAGS += -Wl,-e,main -Wl,-u,eadk_app_name -Wl,-u,eadk_app_icon -Wl,-u,eadk_api_level
+  LDFLAGS += -Wl,--gc-sections -flinker-output=nolto-rel -Wl,-u,_printf_float
+  APP = $(OUTPUT_DIR)/$(APP_NAME).nwa
+else ifeq ($(PLATFORM),web)
+  CC = emcc
+  CXX = em++
+  EADK_CFLAGS := $(shell $(NWLINK) eadk-cflags-web)
+  CXXFLAGS = $(EADK_CFLAGS) -std=c++11 -fno-exceptions -Wall -O0 -g -MMD -MP
+  LDFLAGS = -sSIDE_MODULE=2 -sEXPORTED_FUNCTIONS=_main -sASYNCIFY=1
+  LDFLAGS += -sASYNCIFY_IMPORTS=eadk_event_get,_eadk_keyboard_scan_do_scan,eadk_timing_msleep,eadk_display_wait_for_vblank
+  LDFLAGS += -lc
+  APP = $(OUTPUT_DIR)/$(APP_NAME).nwb
+else
+  $(error Unknown PLATFORM '$(PLATFORM)' (use device or web))
+endif
 
 .PHONY: all
-all: $(OUTPUT_DIR)/$(APP_NAME).nwa
+all: $(APP)
 
-$(OUTPUT_DIR)/$(APP_NAME).nwa: $(OBJS) $(OUTPUT_DIR)/icon.o
+$(APP): $(OBJS) $(OBJDIR)/icon.o
 	@echo "LD      $@"
 	$(CC) $(CXXFLAGS) $(LDFLAGS) $^ -o $@
 
-$(OUTPUT_DIR)/%.o: src/%.cpp | $(OUTPUT_DIR)
+$(OBJDIR)/%.o: src/%.cpp | $(OBJDIR)
 	@echo "CXX     $<"
 	$(CXX) $(CXXFLAGS) -c $< -o $@
 
-$(OUTPUT_DIR)/icon.o: $(APP_ICON) | $(OUTPUT_DIR)
+$(OBJDIR)/icon.o: $(APP_ICON) | $(OBJDIR)
 	@echo "ICON    $<"
 	$(NWLINK) png-icon-o $< $@
 
-$(OUTPUT_DIR):
-	mkdir -p $(OUTPUT_DIR)
+$(OBJDIR):
+	mkdir -p $(OBJDIR)
 
 .PHONY: install
 install: $(OUTPUT_DIR)/$(APP_NAME).nwa

README.md

@@ -1,19 +1,37 @@
+<div align="center">
+
+<img src="src/icon.png" alt="RPN app icon" width="64" height="64">
+
 # RPN for NumWorks
 
+[![GitHub release](https://img.shields.io/github/v/release/1e1/numworks-RPN?style=flat-square)](https://github.com/1e1/numworks-RPN/releases)
+[![GitHub commit activity](https://img.shields.io/github/commit-activity/m/1e1/numworks-RPN?style=flat-square&color=brightgreen)](https://github.com/1e1/numworks-RPN/commits/main)
+[![License](https://img.shields.io/github/license/1e1/numworks-RPN?style=flat-square)](https://github.com/1e1/numworks-RPN/blob/main/LICENSE)
+
+### *No parentheses, no `=`.*
+
+</div>
+
 A **Reverse Polish Notation** (RPN) calculator as an external app for the
 [NumWorks](https://www.numworks.com) graphing calculator.
 
 No parentheses, no `=`: you push numbers onto a stack and operators act on it.
-Arithmetic keeps **exact fractions** (`1/3 + 1/6` stays `1/2`), and functions
-fall back to decimal approximations — the familiar NumWorks feel, RPN-style.
+Results stay **symbolic and exact** where they can — fractions (`1/3 + 1/6` →
+`1/2`), radicals (`8 √ 2 ×` → `4√2`), and rational multiples of π (`π 2 ÷` →
+`π/2`) — and fall back to a decimal approximation otherwise. The familiar
+NumWorks feel, RPN-style.
 
 ➡️ **Project page & key map:** <https://1e1.github.io/numworks-RPN/>
 
 > **Scope.** NumWorks external apps run in a sandbox and cannot call the
-> built-in Poincaré engine, so this app ships its own numeric core: exact
-> rational arithmetic for `+ − × ÷` and integer powers, IEEE double for
-> transcendental functions. Full symbolic simplification would require a native
-> build of Epsilon rather than an external app.
+> built-in Poincaré engine, so this app ships its own symbolic core. Values are
+> held as a bounded **sum of terms** `Σ (num/den)·√rad·πⁿ`, which keeps exact
+> fractions, `k√m`, rational multiples of π **and their sums/products**
+> (`√2 + √3`, `(1+√2)²` → `3+2√2`). What still collapses to a decimal: nested
+> radicals, division by a sum, transcendental functions (`sin`, `ln`), overflow
+> — so a result is never *wrongly* exact. A full expression-tree CAS with 2D
+> layout would require a native build of Epsilon rather than an external app
+> (see the roadmap).
 
 ## Install
 
@@ -31,12 +49,18 @@ stack. Subtraction and division are `level2 (op) level1`:
 
 ```
 3 EXE 6 ÷        → 1/2          exact fraction
-2 EXE √          → 1.414214     approximation
+2 EXE √          → √2           exact radical
+8 EXE √ 2 ×      → 4√2          simplified
+2 √ 3 √ +        → √2 + √3      sums stay exact
+π EXE 2 ÷        → π/2          rational multiple of π
 5 EXE 4 EXE −    → 1            (5 − 4)
-π EXE 2 ×        → 6.283185
 5 !              → 120          exact factorial
 ```
 
+On the calculator these render in **2D** — stacked fractions, `√` with a
+vinculum, raised exponents — and level 1 also shows its decimal (`≈`). Press
+`Ans` (→Dec) to force the decimal approximation of the top level.
+
 If you enter operands in the wrong order, press **( = SWAP** to exchange the top
 two levels.
 
@@ -90,6 +114,21 @@ The numeric core (`src/value`, `src/stack`, `src/rpn`, `src/input_field`) is pur
 C++ with no calculator dependency, so `make test` compiles and runs it on your
 host machine.
 
+## Try it in a web simulator (Docker)
+
+Run the app in a browser via the Epsilon web simulator — only Docker is needed
+(the emscripten/node toolchain lives inside the container). You need an
+[Epsilon](https://github.com/numworks/epsilon) checkout next to this repo (its
+folder must contain Epsilon's `Makefile`).
+
+```shell
+docker/run.sh                      # or: EPSILON_DIR=/path/to/epsilon docker/run.sh
+```
+
+Then open <http://localhost:8000/epsilon.html?nwb=/rpn.nwb>. The first run builds
+the simulator (long; cached in a Docker volume afterwards). You can also build
+the web app alone with `make PLATFORM=web` (needs `emcc`).
+
 ## Project layout
 
 ```

docker/Dockerfile

@@ -0,0 +1,21 @@
+# Web-simulator dev environment for the RPN app.
+#
+# Builds the Epsilon web simulator (from a mounted Epsilon checkout) and the RPN
+# app (.nwb), then serves them so you can run the app in a browser — no local
+# emscripten/node install needed, just Docker.
+#
+# The emsdk version matches Epsilon's .emsdk-version (4.0.10).
+FROM emscripten/emsdk:4.0.10
+
+# Epsilon's asset pipeline and the app build need these on top of emsdk
+# (which already ships python3 and node).
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        git python3 python3-pil imagemagick pkg-config \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY serve.sh /usr/local/bin/serve.sh
+RUN chmod +x /usr/local/bin/serve.sh
+
+WORKDIR /work
+EXPOSE 8000
+ENTRYPOINT ["/usr/local/bin/serve.sh"]

docker/run.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# Build the image and run the web simulator in a browser via Docker.
+#
+#   docker/run.sh
+#
+# By default it looks for an Epsilon checkout next to this repo:
+#   ../epsilon/epsilon  (the dir that contains Epsilon's Makefile)
+# Override with EPSILON_DIR=/path/to/epsilon docker/run.sh
+set -euo pipefail
+
+APP_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+EPSILON_DIR="${EPSILON_DIR:-$APP_DIR/../epsilon/epsilon}"
+
+if [ ! -f "$EPSILON_DIR/Makefile" ]; then
+  echo "Epsilon checkout not found at: $EPSILON_DIR" >&2
+  echo "Set EPSILON_DIR to the folder containing Epsilon's Makefile." >&2
+  exit 1
+fi
+EPSILON_DIR="$(cd "$EPSILON_DIR" && pwd)"
+
+echo ">> App:     $APP_DIR"
+echo ">> Epsilon: $EPSILON_DIR"
+
+docker build -t numworks-rpn-sim "$APP_DIR/docker"
+docker run --rm -it -p 8000:8000 \
+  -v "$EPSILON_DIR":/epsilon \
+  -v "$APP_DIR":/app \
+  -v numworks-rpn-simcache:/serve \
+  numworks-rpn-sim

docker/serve.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# Container entrypoint: build the Epsilon web simulator + the RPN .nwb, then
+# serve them. Expects two mounts:
+#   /epsilon   an Epsilon source tree (the dir that contains its Makefile)
+#   /app       this repository
+# and (optionally) a persistent volume on /serve to cache the simulator build.
+set -euo pipefail
+
+EPSILON=/epsilon
+APP=/app
+SERVE=/serve
+mkdir -p "$SERVE"
+
+if [ ! -f "$EPSILON/Makefile" ]; then
+  echo "!! /epsilon does not look like an Epsilon checkout (no Makefile)." >&2
+  echo "   Mount the Epsilon source dir there (see docker/run.sh)." >&2
+  exit 1
+fi
+
+if [ ! -f "$SERVE/epsilon.html" ]; then
+  echo ">> Building the Epsilon web simulator — first run is long (cached afterwards)…"
+  ( cd "$EPSILON" && make PLATFORM=web WEB_EXTERNAL_APPS=1 -j"$(nproc)" epsilon.html )
+  cp "$EPSILON"/output/release/web/epsilon.* "$SERVE"/
+else
+  echo ">> Reusing cached Epsilon web simulator in the /serve volume."
+fi
+
+echo ">> Building the RPN app for web (.nwb)…"
+( cd "$APP" && make PLATFORM=web )
+cp "$APP"/output/rpn.nwb "$SERVE"/rpn.nwb
+
+echo
+echo "==============================================================="
+echo "  Open:  http://localhost:8000/epsilon.html?nwb=/rpn.nwb"
+echo "==============================================================="
+echo
+cd "$SERVE" && exec python3 -m http.server 8000

docs/ROADMAP.md

@@ -1,8 +1,13 @@
-# Roadmap — v2: symbolic stack with Poincaré-style presentation
-
-v1.0.0 is a numeric RPN calculator: the stack holds *numbers* (exact rationals
-or doubles) and every operator computes eagerly. v2 changes the nature of the
-stack.
+# Roadmap — symbolic stack with Poincaré-style presentation
+
+> **Status.** v1.0.0 held plain numbers. **v2.0.0 ships a symbolic layer**:
+> values are a bounded **sum of terms** `Σ (num/den)·√rad·πⁿ`, so `8 √ 2 ×` →
+> `4√2`, `π 2 ÷` → `π/2`, `√2·√2` → `2`, and sums stay exact too (`√2 + √3`,
+> `(1+√2)²` → `3+2√2`). It also renders results in **2D** (stacked fractions,
+> radicals with a vinculum, raised exponents) with the level-1 decimal shown
+> beneath. Still remaining toward a *full* Poincaré-grade CAS, staying portable:
+> a **general expression tree** — nested radicals (`√(1+√2)`), division by a
+> sum, symbolic variables — the harder, higher-risk part.
 
 ## Vision