mtm-rpn-js/.continue/rules/project.md

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.