# Project rules — RPN Virtual Calculator

- 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.
- 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`, accepted range `2..16`)
  - `angleMode` (`deg` by default; also `rad` and `grad`)
  - `enabledCommands`
- Available constants are `pi` and `e`.
- Supported operations must stay centralized in one dictionary containing at least:
  - `argCount`
  - `category`
  - `aliases`
  - `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

- Current commands:
  - `add`, `sub`, `mul`, `div`, `mod`, `pow`, `sqr`, `neg`, `sqrt`, `recip`,
    `sin`, `cos`, `tan`, `asin`, `acos`, `atan`, `log`, `ln`,
    `dup`, `drop`, `swap`, `clear`, `enter`
- 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`.
- `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 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`
  - 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`.
- `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, keyboard help, exported API, command metadata, or calculator behavior, update these rules so they continue to match the current project behavior.