docs: refresh project rules and README for current engine API

.continue/rules/project.md

@@ -1,20 +1,24 @@
 # Project rules — RPN Virtual Calculator
 
-- Build a browser-friendly RPN calculator as a JavaScript class, preferably in a single file.
+- Build a browser-friendly RPN calculator as a JavaScript class, currently implemented in `src/rpn-calculator.js`.
 - Keep code names, categories, and API identifiers in English.
-- Use only read-only / generic public API methods: `push`, `pop`, `clear`, `swap(index1, index2)`, `remove(index)`, `edit(index)`, `isValidIndex(index)`, `input(command)`, and `command(name, ...args)`.
-- Expose `inputValue` as a string and `isEditing` as a boolean.
-- Constructor options:
+- Keep the public calculator API centered on the generic methods `push`, `pop`, `clear`, `swap(index1, index2)`, `remove(index)`, `edit(index)`, `isValidIndex(index)`, `input(command)`, and `command(name, ...args)`.
+- `inputValue` must remain a string and `isEditing` must remain a boolean.
+- Keep constructor options aligned with the current engine:
   - `maxSize` (default `2048`)
-  - `base` (default `10`)
-  - `angleMode` (`deg` default; also `rad` and `grad`)
+  - `base` (default `10`, accepted range `2..16`)
+  - `angleMode` (`deg` by default; also `rad` and `grad`)
   - `enabledCommands`
-- Available constants: `pi`, `e`.
-- Supported operations must be centralized in one dictionary containing at least:
+- Available constants are `pi` and `e`.
+- Supported operations must stay centralized in one dictionary containing at least:
   - `argCount`
   - `category`
   - `aliases`
-- Allowed categories are limited to: `Stack`, `Arithmetic`, and `Trigonometry`.
+  - `execute`
+- Allowed operation categories are limited to `Stack`, `Arithmetic`, and `Trigonometry`.
+- The engine currently exposes static helpers for category discovery: `getOperationCategories()` and `getOperationsByCategory()`.
+- The instance currently exposes `getOperationsByCategory()` and `getConstants()` helpers in addition to the generic API.
+- Preserve browser and CommonJS exports for `RpnCalculator`.
 
 ## Supported commands
 
@@ -22,42 +26,70 @@
   - `add`, `sub`, `mul`, `div`, `mod`, `pow`, `sqr`, `neg`, `sqrt`, `recip`,
     `sin`, `cos`, `tan`, `asin`, `acos`, `atan`, `log`, `ln`,
     `dup`, `drop`, `swap`, `clear`, `enter`
-- Aliases:
+- Current aliases include:
   - `+`, `-`, `*`, `/`, `%`, `^`, `y^x`, `1/x`
+- Existing extra alias also present in code:
+  - `sqrt(x)` for `sqrt`
 
 ## Behavior rules
 
-- `mod` is the percentage operator: `a b % => (a * b) / 100`
-- `sqrt`, `asin`, `acos`, `log`, and `ln` must throw clear, explicit domain errors
-- `log` uses `Math.log10`
-- `ln` uses `Math.log`
-- Trigonometric functions must support `deg`, `rad`, and `grad`
-- In the browser demo, degrees are the default angle mode
-- `inputValue` must remain a string to preserve future hexadecimal input support
+- `mod` is the percentage operator: `a b % => (a * b) / 100`.
+- `div` and `recip` must throw `Division by zero` on zero divisors.
+- `sqrt`, `asin`, `acos`, `log`, and `ln` must throw explicit domain errors.
+- `log` uses `Math.log10`.
+- `ln` uses `Math.log`.
+- Trigonometric functions must support `deg`, `rad`, and `grad`.
+- Direct trigonometric functions convert input angles with `toRadians(...)`.
+- Inverse trigonometric functions convert results back using the current angle mode via `toDegrees(...)`.
+- The engine rounds formatted numeric results to 12 decimal places and normalizes `-0` to `0`.
+- `inputValue` must remain a string to preserve future hexadecimal-style input support.
+- `parseInputValue(...)` currently uses `Number(...)` in base 10 and `parseInt(..., base)` for other bases.
+- `input(command)` currently accepts single-character numeric editing input, including `0-9`, `A-F`, `a-f`, `+`, `-`, and `.`.
+- `command(name, ...args)` currently resolves aliases, supports constants, commits pending input before execution, checks `enabledCommands`, and throws clear `Unknown command`, `Command disabled`, `Stack overflow`, `Stack underflow`, `Invalid stack index`, `Invalid number`, and `Invalid input value` errors where appropriate.
 
 ## Demo rules
 
-- The browser demo lives under `samples/dev/`
-- `samples/dev/index.html` is the demo entry page
-- `samples/dev/index.css` contains the calculator visual theme
-- `samples/dev/index.js` contains demo-side presentation helpers and UI logic
-- The demo UI must expose:
-  - a stack display
-  - a main display
+- The active browser demo lives under `samples/dev/`.
+- `samples/dev/index.html` is the demo entry page.
+- `samples/dev/index.css` contains the calculator visual theme.
+- `samples/dev/index.js` contains demo-side presentation helpers and UI logic.
+- The demo currently exposes:
+  - a stack display with four visible lines
+  - a main display/status area
   - a visible angle mode indicator
   - an angle mode selector for `deg`, `rad`, and `grad`
-- The demo may present user-facing labels such as `+`, `−`, `×`, `÷`, `y^x`, `1/x`, and `x²` while still using English command identifiers internally
-- The example HTML must group buttons by `Stack`, `Arithmetic`, and `Trigonometry`
-- The example HTML must call `command(...)` for actions
-- Keyboard support in the demo should remain consistent with the displayed help text
+  - status pills showing `inputValue` and `isEditing`
+  - grouped command panels for `Stack`, `Arithmetic`, `Trigonometry`, and `Constants`
+  - an error display area
+- The demo may present user-facing labels such as `+`, `−`, `×`, `÷`, `y^x`, `1/x`, and `x²` while still using English command identifiers internally.
+- The example HTML groups buttons by `Stack`, `Arithmetic`, and `Trigonometry`, plus a dedicated `Constants` section.
+- Demo buttons are wired through demo helpers that eventually call `command(...)` for calculator commands.
+- The demo default angle mode is degrees.
+- Keyboard support in the demo must remain consistent with the displayed help text.
+- The current demo keyboard behavior supports:
+  - digits and decimal point
+  - numpad digits and numpad arithmetic keys
+  - `Enter` to validate input or toggle stack-item move mode
+  - `Backspace` to edit input or drop from the stack
+  - `Delete` to clear
+  - `Escape` to cancel editing, cancel move mode, or clear selection
+  - `ArrowUp` / `ArrowDown` to navigate or move selected stack items
+  - `ArrowRight` for swap
+  - `+`, `-`, `*`, `/`, `%`, `^`
+  - `q`, `n`, `r`, `i`, `g`, `l`, `s`, `c`, `S`, `C`
+  - `x`, `y`, `z`, `t` to select visible stack registers
+- The demo currently implements stack selection and stack-item move mode in its own UI logic using the public stack methods.
+- The demo currently duplicates X on `enter` when not editing, matching classic RPN-style behavior in the UI layer.
 
 ## File references
 
-- `samples/dev/index.html` references `src/rpn-calculator.js` as the calculator engine used by the demo
-- Keep the demo aligned with the public calculator API exposed by `src/rpn-calculator.js`
+- `samples/dev/index.html` references `../../src/rpn-calculator.js` as the calculator engine used by the demo.
+- Keep the demo aligned with the public calculator API exposed by `src/rpn-calculator.js`.
+- `README.md` is currently outdated and duplicated in places; if documentation work is done later, align it with the actual engine and demo behavior.
 
 ## Maintenance
 
+- Re-read `src/rpn-calculator.js` and `samples/dev/` before updating these rules after project changes.
 - Keep this file updated after each project change using the provided editing tools.
-- When changing the demo UI or calculator API, update these rules so they continue to match the current project behavior.
+- When changing the demo UI, keyboard help, exported API, command metadata, or calculator behavior, update these rules so they continue to match the current project behavior.