@teachinglab/omd 0.1.0

package/docs/api/omdPopup.md

@@ -0,0 +1,117 @@
+# omdPopup
+
+The `omdPopup` class handles the creation and management of popups for node overlays. These popups can be used for text input or for drawing with a pen tool.
+
+## Class Definition
+
+```javascript
+export class omdPopup {
+    // ...
+}
+```
+
+## Constructor
+
+### `new omdPopup(targetNode, parentElement, [options])`
+
+Creates a new `omdPopup` instance.
+
+*   **targetNode** (`omdNode`): The node to which the popup is attached.
+*   **parentElement** (`jsvgElement`): The parent element for the popup.
+*   **[options]** (`object`, optional): Configuration options for the popup.
+    *   **editable** (`boolean`, optional): Whether the popup is editable. Defaults to `true`.
+    *   **animationDuration** (`number`, optional): The duration of the show/hide animation in milliseconds. Defaults to `200`.
+
+## Public Methods
+
+### `show(x, y)`
+
+Creates and shows the popup at the specified coordinates.
+
+*   **x** (`number`): The x-coordinate for the popup.
+*   **y** (`number`): The y-coordinate for the popup.
+*   **Returns**: `Promise` - A promise that resolves when the show animation is complete.
+
+### `hide()`
+
+Hides the popup.
+
+*   **Returns**: `Promise` - A promise that resolves when the hide animation is complete.
+
+### `toggle(x, y)`
+
+Toggles the visibility of the popup.
+
+*   **x** (`number`): The x-coordinate for showing the popup.
+*   **y** (`number`): The y-coordinate for showing the popup.
+*   **Returns**: `Promise` - A promise that resolves when the animation is complete.
+
+### `setValidationCallback(callback)`
+
+Sets the callback function to be called when the user submits their input.
+
+*   **callback** (`Function`): The function to call for validation.
+
+### `setClearCallback(callback)`
+
+Sets the callback function to be called when the user clears the input.
+
+*   **callback** (`Function`): The function to call when clearing.
+
+### `getValue()`
+
+Gets the current input value from the popup.
+
+*   **Returns**: `string` - The current input value.
+
+### `setValue(value)`
+
+Sets the input value of the popup.
+
+*   **value** (`string`): The value to set.
+
+### `switchToMode(mode)`
+
+Switches the popup between `'text'` and `'pen'` mode.
+
+*   **mode** (`string`): The mode to switch to. Can be `'text'` or `'pen'`.
+
+### `flashValidation(isValid)`
+
+Flashes the popup background to indicate whether the user's input was valid.
+
+*   **isValid** (`boolean`): Whether the validation was successful.
+
+### `destroy()`
+
+Destroys the popup and cleans up all associated elements.
+
+## Modes
+
+The `omdPopup` has two modes:
+
+*   **Text Mode**: This is the default mode. It provides a simple text input field.
+*   **Pen Mode**: This mode allows the user to draw inside the popup using a pen tool. The drawing can then be transcribed to text using an OCR service.
+
+The user can switch between modes using the 'T' and 'P' buttons on the popup.
+
+## Example Usage
+
+```javascript
+// Create a popup for a node
+const popup = new omdPopup(node, parentElement);
+
+// Set a validation callback
+popup.setValidationCallback(() => {
+    const value = popup.getValue();
+    if (value === 'correct') {
+        popup.flashValidation(true);
+        popup.hide();
+    } else {
+        popup.flashValidation(false);
+    }
+});
+
+// Show the popup
+popup.show(100, 100);
+```

package/docs/api/omdPowerNode.md

@@ -0,0 +1,127 @@
+# omdPowerNode
+
+Represents an exponentiation in a mathematical expression, such as `x^2` or `(a+b)^c`. It handles the specific layout requirements of a base and a superscripted exponent.
+
+## Class: `omdPowerNode extends omdNode`
+
+```javascript
+import { omdPowerNode } from './omd/nodes/omdPowerNode.js';
+```
+
+### Constructor
+
+```javascript
+new omdPowerNode(ast)
+```
+
+
+**Parameters:**
+- `ast` {Object} - The math.js AST for the power operation. It must be an `OperatorNode` with `op: '^'` and an `args` array containing two elements: the base and the exponent.
+
+### Static Methods
+
+
+#### `fromString(expressionString)`
+Creates an `omdPowerNode` from a string.
+
+```javascript
+const powerNode = omdPowerNode.fromString('x^2');
+```
+- **Parameters:**
+  - `expressionString` {string} - The power expression as a string.
+- **Returns:** `omdPowerNode` A new instance.
+- **Throws:** Error if math.js is not available or the string is not a valid power expression.
+
+### Properties
+
+Inherits properties from [`omdNode`](./omdNode.md), plus:
+
+#### `base`
+- **Type:** [`omdNode`](./omdNode.md)
+- **Description:** The node representing the base of the power operation.
+
+#### `exponent`
+- **Type:** [`omdNode`](./omdNode.md)
+- **Description:** The node representing the exponent.
+
+### Methods
+
+Inherits methods from [`omdNode`](./omdNode.md). Key methods include:
+
+
+#### `evaluate(variables)`
+Evaluates the expression by raising the evaluated base to the power of the evaluated exponent.
+- **Parameters:**
+  - `variables` {Object} - A map of variable names to their numeric values.
+- **Returns:** `number` - The result of the exponentiation, or `NaN` if base or exponent cannot be evaluated.
+
+---
+
+
+#### `simplify()`
+Delegates to the central simplification engine to simplify the base and exponent.
+- **Returns:** `Object` - An object indicating the result: `{ success, newRoot, message }`.
+- **Note:** This method is not implemented directly on `omdPowerNode`, but is available via the central simplification engine (see [omdSimplification](./omdSimplification.md)).
+
+---
+
+
+#### `isSquare()`
+Checks if the exponent is the constant value `2`.
+- **Returns:** `boolean`.
+
+---
+
+
+#### `isCube()`
+Checks if the exponent is the constant value `3`.
+- **Returns:** `boolean`.
+
+---
+
+
+#### `getAlignmentBaseline()`
+Calculates the vertical alignment point for the node, which is determined by the baseline of its `base` expression.
+- **Returns:** `number` - The y-coordinate for alignment.
+
+---
+
+
+#### `toMathJSNode()`
+Converts the node back into its math.js AST representation.
+- **Returns:** `Object` - A math.js `OperatorNode` for the power operation.
+
+---
+
+
+#### `toString()`
+Converts the node to its string representation, adding parentheses where necessary to preserve order of operations.
+- **Returns:** `string` - e.g., `"(x+1)^2"`.
+
+### Example
+
+```javascript
+// Create a node representing x^2
+const ast = math.parse('x^2');
+const powerNode = new omdPowerNode(ast);
+
+// Set font size and render
+powerNode.setFontSize(32);
+powerNode.initialize();
+
+// Check properties
+console.log(powerNode.isSquare()); // true
+
+// Evaluate
+console.log(powerNode.evaluate({ x: 5 })); // 25
+
+// Add to an SVG container to display
+const svgContainer = new jsvgContainer();
+svgContainer.addChild(powerNode);
+document.body.appendChild(svgContainer.svgObject);
+```
+
+### See Also
+
+- [`omdNode`](./omdNode.md) - The base class.
+- [`omdBinaryExpressionNode`](./omdBinaryExpressionNode.md) - Can be used for complex bases or exponents.

package/docs/api/omdRationalNode.md

@@ -0,0 +1,128 @@
+# omdRationalNode
+
+Represents a fraction, with a numerator and a denominator, such as `1/2` or `(x+1)/(x-1)`. It handles the distinct visual layout of a fraction, with the numerator positioned above the denominator, separated by a horizontal line.
+
+## Class: `omdRationalNode extends omdNode`
+
+```javascript
+import { omdRationalNode } from './omd/nodes/omdRationalNode.js';
+```
+
+### Constructor
+
+```javascript
+new omdRationalNode(astNodeData)
+```
+
+**Parameters:**
+- `astNodeData` {Object} - The math.js AST for the division operation. It must be an `OperatorNode` with `op: '/'` and an `args` array containing two elements: the numerator and the denominator.
+
+### Static Methods
+
+
+#### `fromString(expressionString)`
+Creates an `omdRationalNode` from a string containing a division.
+
+```javascript
+const rationalNode = omdRationalNode.fromString('x / 2');
+```
+- **Parameters:**
+  - `expressionString` {string} - The fractional expression as a string.
+- **Returns:** `omdRationalNode` A new instance.
+- **Throws:** Error if math.js is not available or the string is not a valid division expression.
+
+### Properties
+
+Inherits properties from [`omdNode`](./omdNode.md), plus:
+
+#### `numerator`
+- **Type:** [`omdNode`](./omdNode.md)
+- **Description:** The node representing the top part of the fraction.
+
+#### `denominator`
+- **Type:** [`omdNode`](./omdNode.md)
+- **Description:** The node representing the bottom part of the fraction.
+
+### Methods
+
+Inherits methods from [`omdNode`](./omdNode.md). Key methods include:
+
+
+#### `evaluate(variables)`
+Evaluates the fraction by dividing the evaluated numerator by the evaluated denominator.
+- **Parameters:**
+  - `variables` {Object} - A map of variable names to their numeric values.
+- **Returns:** `number` - The result of the division.
+- **Throws:** Error if the denominator evaluates to zero.
+
+---
+
+
+#### `simplify()`
+Delegates to the central simplification engine to simplify the numerator and denominator and to reduce the fraction.
+- **Returns:** `Object` - An object indicating the result: `{ success, newRoot, message }`.
+- **Note:** This method is not implemented directly on `omdRationalNode`, but is available via the central simplification engine (see [omdSimplification](./omdSimplification.md)).
+
+---
+
+
+#### `reduce()`
+If the fraction is constant, reduces it to its lowest terms (e.g., `4/8` becomes `1/2`). If the new denominator is `1`, it returns an `omdConstantNode`.
+- **Returns:** `omdRationalNode | omdConstantNode` The reduced node, or a clone of the original if it's not constant.
+
+---
+
+
+#### `isProper()`
+Checks if the fraction is proper (the absolute value of the numerator is less than the absolute value of the denominator). Only applies to constant fractions.
+- **Returns:** `boolean | null` - `true` if proper, `false` if improper, `null` if not constant.
+
+---
+
+
+#### `getAlignmentBaseline()`
+Calculates the vertical alignment point for the node, which is the y-position of the fraction bar.
+- **Returns:** `number` - The y-coordinate for alignment.
+
+---
+
+
+#### `toMathJSNode()`
+Converts the node back into its math.js AST representation.
+- **Returns:** `Object` - A math.js `OperatorNode` for division.
+
+---
+
+
+#### `toString()`
+Converts the node to its string representation, adding parentheses where necessary.
+- **Returns:** `string` - e.g., `"(x + 1) / (x - 1)"`.
+
+fraction.initialize();
+document.body.appendChild(svgContainer.svgObject);
+
+### Example
+
+```javascript
+// Create a fraction from a string
+const fraction = omdRationalNode.fromString('(a+b)/(a-b)');
+
+// Set font size and render
+fraction.setFontSize(28);
+fraction.initialize();
+
+// Evaluate with given variables
+const result = fraction.evaluate({ a: 3, b: 1 });
+console.log(result); // Output: 2 (since (3+1)/(3-1) = 4/2 = 2)
+
+// Add to an SVG container to display
+const svgContainer = new jsvgContainer();
+svgContainer.addChild(fraction);
+document.body.appendChild(svgContainer.svgObject);
+```
+
+### See Also
+
+- [`omdNode`](./omdNode.md) - The base class.
+- [`omdConstantNode`](./omdConstantNode.md) - For constant numerators/denominators.
+- [`omdBinaryExpressionNode`](./omdBinaryExpressionNode.md) - For complex numerators/denominators.

package/docs/api/omdSequenceNode.md

@@ -0,0 +1,128 @@
+# omdEquationSequenceNode
+
+Represents a sequence of mathematical steps, typically a series of equations that show the process of solving a problem. This node is a container that manages the layout, alignment, and simplification history of its steps.
+
+## Class: `omdEquationSequenceNode extends omdNode`
+
+```javascript
+import { omdEquationSequenceNode } from './omd/nodes/omdEquationSequenceNode.js';
+```
+
+### Constructor
+
+```javascript
+new omdEquationSequenceNode(steps)
+```
+
+**Parameters:**
+- `steps` {Array<[`omdNode`](./omdNode.md)>} - An array of nodes (usually `omdEquationNode` or `omdOperationDisplayNode`) that make up the sequence.
+
+
+### Static Methods
+
+#### `fromSteps(stepsArray)`
+Creates an `omdEquationSequenceNode` from an array of expression strings.
+
+```javascript
+const sequence = omdEquationSequenceNode.fromSteps([
+    '2x + 4 = 10',
+    '2x = 6',
+    'x = 3'
+]);
+```
+- **Parameters:**
+  - `stepsArray` {Array<string>} - An array of strings, where each string is a step (either an equation or an expression).
+- **Returns:** `omdEquationSequenceNode` A new instance.
+- **Throws:** Error if a string is not a valid equation or expression, or if math.js is not available.
+
+### Core Methods
+
+
+#### `addStep(step, options)`
+Adds a new step to the end of the sequence.
+
+- **Parameters:**
+  - `step` {omdNode | string} - The node or expression string to add. If a string, it is parsed as an equation or expression.
+  - `options` {Object|string} (optional) - Options for the step, such as `description` and `stepMark` (importance level), or a description string for backward compatibility.
+  - `importance` {number} (optional) - Importance level (0, 1, or 2) if using legacy signature.
+- **Returns:** `number` - The index of the newly added step.
+
+---
+
+
+#### `simplify()`
+Applies one round of simplification to the **last step** in the sequence and adds the result as a new step.
+
+- **Returns:** `Object` - An object detailing the result: `{ success, foldedCount, isFinalSimplification, message }`.
+
+---
+
+
+#### `simplifyAll(maxIterations)`
+Repeatedly calls `simplify()` on the last step until no more simplifications can be applied or the iteration limit is reached.
+
+- **Parameters:**
+  - `maxIterations` {number} (optional) - A safeguard against infinite loops. Defaults to `50`.
+- **Returns:** `Object` - An object summarizing the process: `{ success, totalSteps, iterations, message }`.
+
+---
+
+
+#### `applyEquationOperation(value, operation)`
+Applies an operation (e.g., 'add', 'subtract', 'multiply', 'divide') to both sides of the last equation in the sequence. This typically adds two new steps: a visual display of the operation and the resulting new equation.
+
+- **Parameters:**
+  - `value` {number} - The value to apply.
+  - `operation` {string} - The name of the operation ('add', 'subtract', 'multiply', 'divide').
+- **Returns:** `omdEquationSequenceNode` The sequence instance, for chaining.
+
+---
+
+
+#### `applyEquationFunction(functionName)`
+Applies a function (e.g., 'sqrt') to both sides of the last equation and adds the result as a new step.
+
+- **Parameters:**
+  - `functionName` {string} - The name of the function.
+- **Returns:** `omdEquationSequenceNode` The sequence instance, for chaining.
+
+
+### Other Key Methods
+
+- `getCurrentEquation()`: Returns the last `omdEquationNode` in the sequence, or `null` if none.
+- `getCurrentStep()`: Returns the current step node (may not be an equation).
+- `getSimplificationHistory()`: Returns an array of all simplification events that have occurred.
+- `rebuildNodeMap()`: Re-indexes all nodes within the sequence, which is crucial for provenance tracking and highlighting.
+- `updateStepsVisibility(predicate)`: Shows or hides steps based on a provided function, useful for filtering and UI.
+- `clear()`: Removes all steps and history from the sequence.
+- `navigateToStep(index)`: Navigates to a specific step by index.
+- `nextStep()`, `previousStep()`: Navigate forward/backward through steps.
+
+
+### Layout and Provenance
+
+The `omdEquationSequenceNode` automatically aligns all `omdEquationNode` steps by their equals signs, creating a clean, readable layout. It also tracks provenance for all nodes, supporting step-by-step highlighting and history.
+
+
+### Example
+
+```javascript
+// Create a sequence with an initial equation
+const sequence = omdEquationSequenceNode.fromSteps([
+  '2 * (x + 1) = 10'
+]);
+
+// Apply operations and simplifications
+sequence.applyEquationOperation(2, 'divide'); // Adds a step: (2*(x+1))/2 = 10/2
+sequence.simplifyAll(); // Simplifies to x+1=5, then x=4
+
+// Add the sequence to a display
+const display = new omdDisplay(document.getElementById('container'));
+display.render(sequence);
+```
+
+### See Also
+
+- [`omdNode`](./omdNode.md) - The base class.
+- [`omdEquationNode`](./omdEquationNode.md) - The primary type of node held within a sequence.
+- [`omdStepVisualizer`](./omdStepVisualizer.md) - A subclass that adds interactive dots and explanations to the sequence.

package/docs/api/omdSimplification.md

@@ -0,0 +1,110 @@
+# omdSimplification
+
+Core module that provides the main entry points for expression simplification.
+
+## Functions
+
+
+### `simplifyExpression(rootNode)`
+
+Simplifies an entire mathematical expression tree by repeatedly applying simplification rules.
+
+**Parameters:**
+- `rootNode` (`omdNode`): The root node of the expression to simplify.
+
+**Returns:** `{ foldedCount: number, newRoot: omdNode }`
+  - `foldedCount`: Number of simplifications applied.
+  - `newRoot`: The simplified expression tree (fresh clone if any simplifications occurred).
+
+**Notes:**
+- Limited to 50 iterations to prevent infinite loops.
+- Preserves font size from the original node.
+- Handles errors gracefully by returning the original node if an error occurs.
+
+**Example:**
+```javascript
+import { simplifyExpression } from './omd/simplification/omdSimplification.js';
+
+const result = simplifyExpression(node);
+console.log(result.newRoot.toString());
+console.log(`Applied ${result.foldedCount} simplifications`);
+```
+
+
+### `simplifyStep(rootNode)`
+
+Applies a single simplification step to the expression tree.
+
+**Parameters:**
+- `rootNode` (`omdNode`): The root node of the expression.
+
+**Returns:** `{ foldedCount: number, newRoot: omdNode, historyEntry: object|null }`
+  - `foldedCount`: 1 if a simplification was applied, 0 otherwise.
+  - `newRoot`: The expression tree after applying the step.
+  - `historyEntry`: Object describing the applied simplification, or `null` if none.
+
+**Notes:**
+- Only applies the first matching rule found.
+- Preserves font size from the original node.
+- Handles errors gracefully by returning the original node if an error occurs.
+
+**Example:**
+```javascript
+import { simplifyStep } from './omd/simplification/omdSimplification.js';
+
+const stepResult = simplifyStep(node);
+if (stepResult.historyEntry) {
+  console.log('Applied:', stepResult.historyEntry);
+}
+```
+
+
+### `findSimplificationOpportunities(rootNode)`
+
+Finds all possible simplification opportunities in an expression tree.
+
+**Parameters:**
+- `rootNode` (`omdNode`): The root node to search.
+
+**Returns:** `Array<{ node: omdNode, rule: object, ruleData: object }>`
+  - `node`: The node where a rule can be applied.
+  - `rule`: The applicable rule.
+  - `ruleData`: Data needed to apply the rule.
+
+**Notes:**
+- Uses depth-first traversal.
+- Skips already visited nodes.
+- Only checks rules relevant to each node type.
+- Stops after finding the first applicable rule for each node.
+
+
+### Debug Functions
+
+> **Note:** The following functions are intended for development and debugging, not for production use.
+
+#### `getAvailableRulesForNode(node)`
+
+Lists all rules that could potentially apply to a node.
+
+**Parameters:**
+- `node` (`omdNode`): The node to check.
+
+**Returns:** `Array<string>` - Array of rule names.
+
+#### `getApplicableRulesForNode(node)`
+
+Lists rules that can actually be applied to a node.
+
+**Parameters:**
+- `node` (`omdNode`): The node to check.
+
+**Returns:** `Array<string>` - Array of applicable rule names.
+
+**Notes:**
+- Handles errors gracefully by skipping failed rule checks.
+
+## See Also
+
+- [Simplification Rules](./simplificationRules.md)
+- [Simplification Engine](./simplificationEngine.md)
+- [Configuration Options](./configuration-options.md) 

package/docs/api/omdSqrtNode.md

@@ -0,0 +1,79 @@
+# omdSqrtNode
+
+Represents a square root node in the mathematical expression tree. Handles rendering of the radical symbol and the expression under the root.
+
+## Class: `omdSqrtNode extends omdNode`
+
+```js
+import { omdSqrtNode } from './omd/nodes/omdSqrtNode.js';
+```
+
+### Constructor
+
+```js
+new omdSqrtNode(astNodeData)
+```
+- `astNodeData` {Object}: Math.js AST node with a single argument (the radicand)
+
+### Properties
+
+Inherits all properties from [omdNode](./omdNode.md), plus:
+
+- `argument` (`omdNode`): The radicand node (expression under the root)
+- `value` (`string`): Always "sqrt"
+- `radicalPath` (`jsvgPath`): The radical symbol (√)
+- `radicalLine` (`jsvgLine`): The horizontal line above the radicand
+
+### Methods
+
+Inherits all methods from [omdNode](./omdNode.md), plus:
+
+- `toString()`: Returns string representation, e.g. `sqrt(x+1)`
+- `toMathJSNode()`: Converts to a math.js-compatible AST node
+- `evaluate(variables)`: Evaluates the square root numerically
+  - `variables` {Object}: Variable name to value mapping
+  - **Returns:** `number` (or `NaN` if radicand can't be evaluated)
+- `simplify()`: Attempts to simplify the expression (delegates to central simplification engine)
+  - **Returns:** `{ success, newRoot, message }`
+- `clone()`: Deep clone of the node
+- `highlightAll()`, `unhighlightAll()`: Recursively highlight/unhighlight this node and its argument
+- `toPowerForm()`: Returns an equivalent `omdPowerNode` (x^(1/2)), or `null` if no argument
+
+#### Static Methods
+
+- `fromString(expressionString)`: Create a sqrt node from a string (must be a sqrt function)
+  - `expressionString` {string}
+  - **Returns:** `omdSqrtNode`
+  - **Throws:** Error if not a sqrt function or if math.js is not available
+
+### Example
+
+```js
+import { omdSqrtNode } from './omd/nodes/omdSqrtNode.js';
+
+// Create from AST
+const node = new omdSqrtNode({
+  type: 'FunctionNode',
+  fn: { name: 'sqrt' },
+  args: [ { type: 'SymbolNode', name: 'x' } ]
+});
+
+// Or from string (if static method is available)
+const node2 = omdSqrtNode.fromString('sqrt(x+1)');
+
+// Render and layout
+node.setFontSize(24);
+node.computeDimensions();
+node.updateLayout();
+
+// Evaluate
+const val = node.evaluate({ x: 9 }); // 3
+
+// Convert to power form
+const powerNode = node.toPowerForm(); // x^(1/2)
+```
+
+### See Also
+- [omdNode](./omdNode.md) — Parent class
+- [omdPowerNode](./omdPowerNode.md) — For power form (x^(1/2))
+- [omdFunctionNode](./omdFunctionNode.md) — For other functions