docs: refresh README and add HP48-style browser demo

README.md

@@ -11,7 +11,107 @@ This project defines a reusable RPN calculator engine with:
 - centralized command metadata
 - a browser demo that uses the same public API as any consumer code
 
-## Package contents
+# RPN Virtual Calculator
+
+A browser-friendly RPN calculator built around a small, generic JavaScript API.
+
+## Goal
+
+This project provides a reusable Reverse Polish Notation (RPN) calculator engine with:
+
+- a simple stack-based public API
+- configurable numeric behavior
+- centralized command metadata
+- browser demos that use the same public API as any consumer code
+
+## Project structure
+
+- `src/rpn-calculator.js`: calculator engine
+- `samples/dev/index.html`: browser demo
+- `samples/hp48/index.html`: HP48-style browser demo
+
+## Main features
+
+- Single JavaScript class: `RpnCalculator`
+- Configurable stack size via `maxSize` (default: `2048`)
+- Configurable numeric base via `base` (default: `10`)
+- Configurable angle mode via `angleMode`:
+  - `deg` (default)
+  - `rad`
+  - `grad`
+- Optional command filtering through `enabledCommands`
+- Public API limited to generic methods:
+  - `push(value)`
+  - `pop()`
+  - `clear()`
+  - `swap(index1, index2)`
+  - `remove(index)`
+  - `edit(index)`
+  - `isValidIndex(index)`
+  - `input(command)`
+  - `command(name, ...args)`
+- `inputValue` is always stored as a string
+- `isEditing` is exposed as a boolean
+- Supported operations are centralized in one dictionary with metadata such as:
+  - `argCount`
+  - `category`
+  - `aliases`
+- Supported categories are limited to:
+  - `Stack`
+  - `Arithmetic`
+  - `Trigonometry`
+## Available constants
+
+- `pi`
+- `e`
+
+## Supported commands
+
+### Arithmetic
+- `add` (`+`)
+- `sub` (`-`)
+- `mul` (`*`)
+- `div` (`/`)
+- `mod` (`%`)
+- `pow` (`^`, `y^x`)
+- `sqr`
+- `neg`
+- `sqrt`
+- `recip` (`1/x`)
+- `log`
+- `ln`
+
+### Trigonometry
+- `sin`
+- `cos`
+- `tan`
+- `asin`
+- `acos`
+- `atan`
+
+### Stack
+- `dup`
+- `drop`
+- `swap`
+- `clear`
+- `enter`
+
+## Behavior rules
+
+- `mod` is a percentage operator:
+  - `a b % => (a * b) / 100`
+- `log` uses `Math.log10`
+- `ln` uses `Math.log`
+- `sqrt`, `asin`, `acos`, `log`, and `ln` throw explicit domain errors on invalid input
+- Trigonometric behavior depends on `angleMode`
+- In degree mode:
+  - `sin`, `cos`, `tan` convert degrees to radians internally
+  - `asin`, `acos`, `atan` return degrees
+- `inputValue` remains a string to preserve future support for formats such as hexadecimal input
+
+## Basic usage
+
+### In a browser
 - `rpn-calculator.js`: calculator engine
 - `rpn-example.html`: example browser interface