@teachinglab/omd 0.6.1 → 0.6.2

package/docs/api/omdSequenceNode.md

@@ -1,128 +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.
+# 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

@@ -1,79 +1,79 @@
-# omdSimplification
-
-This module provides the core logic for simplifying mathematical expression trees within the OMD library. It defines functions for applying simplification rules, finding opportunities for simplification, and managing the simplification process.
-
-## Functions
-
-### `simplifyExpression(rootNode)`
-
-Simplifies an entire mathematical expression tree by repeatedly applying simplification rules until no further simplifications are possible or a maximum iteration limit is reached. This function ensures that the resulting expression is in its most simplified form.
-
--   **`rootNode`** (`omdNode`): The root node of the expression tree to simplify.
--   **Returns**: `{ foldedCount: number, newRoot: omdNode }`
-    -   `foldedCount`: The total number of individual simplifications applied across all iterations.
-    -   `newRoot`: The simplified expression tree. This is a fresh clone of the final simplified state, with its font size preserved from the original `rootNode`.
-
-**Notes:**
-
--   A maximum of `50` iterations is performed to prevent potential infinite loops.
--   Handles errors gracefully; if an error occurs during simplification, the original node is returned.
-
-### `simplifyStep(rootNode)`
-
-Applies a single simplification step to the expression tree. This function finds the first applicable simplification rule and applies it, returning the result.
-
--   **`rootNode`** (`omdNode`): The root node of the expression to simplify.
--   **Returns**: `{ foldedCount: number, newRoot: omdNode, historyEntry: object | null }`
-    -   `foldedCount`: `1` if a simplification was applied, `0` otherwise.
-    -   `newRoot`: The expression tree after applying the single step. This will be a new `omdNode` instance if a simplification occurred.
-    -   `historyEntry`: An object describing the applied simplification (e.g., rule name, affected nodes, message), or `null` if no simplification was applied.
-
-**Notes:**
-
--   Only the first matching rule found is applied in a single step.
--   Preserves the font size from the original node.
--   Handles errors gracefully; if an error occurs during rule application, the original node is returned.
-
-### `findSimplificationOpportunities(rootNode)`
-
-Traverses the expression tree (depth-first) to find all possible simplification opportunities. It identifies nodes where a simplification rule can be applied.
-
--   **`rootNode`** (`omdNode`): The root node of the expression tree to search.
--   **Returns**: `Array<{ node: omdNode, rule: object, ruleData: object }>` - An array of objects, where each object represents a simplification opportunity:
-    -   `node`: The `omdNode` instance where a rule can be applied.
-    -   `rule`: The simplification rule object that can be applied.
-    -   `ruleData`: Data needed by the rule's `apply` method.
-
-**Notes:**
-
--   Uses a `visitedNodes` set to prevent infinite loops in cyclic graphs (though expression trees are typically acyclic).
--   Only checks rules relevant to each node type, optimizing performance.
--   For each node, it stops after finding the first applicable rule.
-
-### `getAvailableRulesForNode(node)`
-
-**Debug Function:** Lists all simplification rules that are potentially relevant to a given `omdNode`'s type, regardless of whether they can currently be applied.
-
--   **`node`** (`omdNode`): The node to check.
--   **Returns**: `Array<string>` - An array of rule names.
-
-### `getApplicableRulesForNode(node)`
-
-**Debug Function:** Lists simplification rules that can actually be applied to a given `omdNode` based on its current structure and values.
-
--   **`node`** (`omdNode`): The node to check.
--   **Returns**: `Array<string>` - An array of applicable rule names.
-
-**Notes:**
-
--   Handles errors gracefully by skipping rule checks that might fail.
-
-## Integration with `omdNode`
-
-This module also sets the `simplifyStep` function as the global simplification handler for `omdNode` instances. This allows any `omdNode` to call its `simplify()` method, which will internally use the `simplifyStep` function defined here.
-
-## See Also
-
--   [`Simplification Rules`](./simplificationRules.md) - Details the individual simplification rules.
--   [`Simplification Engine`](./simplificationEngine.md) - (If applicable, for higher-level orchestration).
+# omdSimplification
+
+This module provides the core logic for simplifying mathematical expression trees within the OMD library. It defines functions for applying simplification rules, finding opportunities for simplification, and managing the simplification process.
+
+## Functions
+
+### `simplifyExpression(rootNode)`
+
+Simplifies an entire mathematical expression tree by repeatedly applying simplification rules until no further simplifications are possible or a maximum iteration limit is reached. This function ensures that the resulting expression is in its most simplified form.
+
+-   **`rootNode`** (`omdNode`): The root node of the expression tree to simplify.
+-   **Returns**: `{ foldedCount: number, newRoot: omdNode }`
+    -   `foldedCount`: The total number of individual simplifications applied across all iterations.
+    -   `newRoot`: The simplified expression tree. This is a fresh clone of the final simplified state, with its font size preserved from the original `rootNode`.
+
+**Notes:**
+
+-   A maximum of `50` iterations is performed to prevent potential infinite loops.
+-   Handles errors gracefully; if an error occurs during simplification, the original node is returned.
+
+### `simplifyStep(rootNode)`
+
+Applies a single simplification step to the expression tree. This function finds the first applicable simplification rule and applies it, returning the result.
+
+-   **`rootNode`** (`omdNode`): The root node of the expression to simplify.
+-   **Returns**: `{ foldedCount: number, newRoot: omdNode, historyEntry: object | null }`
+    -   `foldedCount`: `1` if a simplification was applied, `0` otherwise.
+    -   `newRoot`: The expression tree after applying the single step. This will be a new `omdNode` instance if a simplification occurred.
+    -   `historyEntry`: An object describing the applied simplification (e.g., rule name, affected nodes, message), or `null` if no simplification was applied.
+
+**Notes:**
+
+-   Only the first matching rule found is applied in a single step.
+-   Preserves the font size from the original node.
+-   Handles errors gracefully; if an error occurs during rule application, the original node is returned.
+
+### `findSimplificationOpportunities(rootNode)`
+
+Traverses the expression tree (depth-first) to find all possible simplification opportunities. It identifies nodes where a simplification rule can be applied.
+
+-   **`rootNode`** (`omdNode`): The root node of the expression tree to search.
+-   **Returns**: `Array<{ node: omdNode, rule: object, ruleData: object }>` - An array of objects, where each object represents a simplification opportunity:
+    -   `node`: The `omdNode` instance where a rule can be applied.
+    -   `rule`: The simplification rule object that can be applied.
+    -   `ruleData`: Data needed by the rule's `apply` method.
+
+**Notes:**
+
+-   Uses a `visitedNodes` set to prevent infinite loops in cyclic graphs (though expression trees are typically acyclic).
+-   Only checks rules relevant to each node type, optimizing performance.
+-   For each node, it stops after finding the first applicable rule.
+
+### `getAvailableRulesForNode(node)`
+
+**Debug Function:** Lists all simplification rules that are potentially relevant to a given `omdNode`'s type, regardless of whether they can currently be applied.
+
+-   **`node`** (`omdNode`): The node to check.
+-   **Returns**: `Array<string>` - An array of rule names.
+
+### `getApplicableRulesForNode(node)`
+
+**Debug Function:** Lists simplification rules that can actually be applied to a given `omdNode` based on its current structure and values.
+
+-   **`node`** (`omdNode`): The node to check.
+-   **Returns**: `Array<string>` - An array of applicable rule names.
+
+**Notes:**
+
+-   Handles errors gracefully by skipping rule checks that might fail.
+
+## Integration with `omdNode`
+
+This module also sets the `simplifyStep` function as the global simplification handler for `omdNode` instances. This allows any `omdNode` to call its `simplify()` method, which will internally use the `simplifyStep` function defined here.
+
+## See Also
+
+-   [`Simplification Rules`](./simplificationRules.md) - Details the individual simplification rules.
+-   [`Simplification Engine`](./simplificationEngine.md) - (If applicable, for higher-level orchestration).
 -   [`Configuration Options`](./configuration-options.md) - For configuring simplification behavior.