@teachinglab/omd 0.5.7 → 0.6.0

package/npm-docs/api/omdRationalNode.md

@@ -0,0 +1,145 @@
+# 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 Definition
+
+```javascript
+export class omdRationalNode extends omdNode
+```
+
+## Constructor
+
+### `new omdRationalNode(astNodeData)`
+
+Creates a new `omdRationalNode` instance.
+
+-   **`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. The constructor also creates and initializes the visual `fractionLine`.
+
+## Static Methods
+
+### `fromString(expressionString)`
+
+Creates an `omdRationalNode` from a string containing a division. Requires `window.math` (math.js) to be available globally for parsing.
+
+-   **`expressionString`** (`string`): The fractional expression as a string (e.g., `"x / 2"`, `"(a+b)/(a-b)"`).
+-   **Returns**: `omdRationalNode` - A new instance.
+-   **Throws**: `Error` if `math.js` is not available, if the string cannot be parsed, or if it does not represent a valid division expression.
+
+## Public Properties
+
+-   **`numerator`** (`omdNode`): The node representing the top part of the fraction.
+-   **`denominator`** (`omdNode`): The node representing the bottom part of the fraction.
+-   **`fractionLine`** (`jsvgLine`): The visual horizontal line separating the numerator and denominator.
+
+## Public Methods
+
+### `computeDimensions()`
+
+Calculates the dimensions of the rational node. It scales down the font size of the numerator and denominator, computes their individual dimensions, and then determines the total width (maximum of numerator/denominator width plus spacing) and total height (sum of numerator, denominator, and padding for the fraction line).
+
+-   **Overrides**: `omdNode.computeDimensions()`.
+
+### `updateLayout()`
+
+Updates the layout of the rational node. It positions the `numerator` at the top, the `fractionLine` in the middle, and the `denominator` at the bottom, ensuring they are horizontally centered and have appropriate vertical spacing.
+
+-   **Overrides**: `omdNode.updateLayout()`.
+
+### `getAlignmentBaseline()`
+
+Calculates the vertical alignment point for the node. For a rational node, this is the y-position of the fraction bar, which serves as the visual baseline.
+
+-   **Overrides**: `omdNode.getAlignmentBaseline()`.
+
+### `isConstant()`
+
+Checks if both the numerator and the denominator are constant numerical values.
+
+-   **Returns**: `boolean`.
+
+### `getRationalValue()`
+
+Retrieves the rational value of the node as a numerator/denominator pair. This method only works if the fraction is constant.
+
+-   **Returns**: `{ num: number, den: number }`.
+-   **Throws**: `Error` if the rational node is not constant.
+
+### `getValue()`
+
+Retrieves the numerical value of the rational node by dividing the numerator's value by the denominator's value. This method only works if the fraction is constant.
+
+-   **Returns**: `number`.
+-   **Throws**: `Error` if the rational node is not constant or if division by zero occurs.
+
+### `clone()`
+
+Creates a deep, structural clone of the rational node, including its `numerator` and `denominator` nodes. The `fractionLine` is also recreated. The cloned node's `provenance` array is updated to include the original node's ID.
+
+-   **Returns**: `omdRationalNode` - A new, identical instance of the rational node.
+
+### `toMathJSNode()`
+
+Converts the `omdRationalNode` back into its math.js AST representation. It creates an `OperatorNode` with `op: '/'` and `fn: 'divide'`, containing the converted numerator and denominator ASTs.
+
+-   **Returns**: `object` - A math.js `OperatorNode` for division. The returned object also includes a `clone` method for compatibility.
+
+### `toString()`
+
+Converts the node to its string representation, adding parentheses around the numerator and/or denominator if they are complex expressions (e.g., binary expressions) to maintain correct order of operations.
+
+-   **Returns**: `string` - e.g., `"(x + 1) / (x - 1)"`.
+
+### `evaluate(variables)`
+
+Evaluates the rational expression by evaluating the numerator and denominator and then performing the division.
+
+-   **`variables`** (`object`): A map of variable names to their values.
+-   **Returns**: `number` - The result of the division.
+-   **Throws**: `Error` if the denominator evaluates to zero.
+
+### `reduce()`
+
+If the fraction is constant, this method reduces it to its lowest terms (e.g., `4/8` becomes `1/2`). If the reduced denominator is `1`, it returns an `omdConstantNode` representing the integer value. It uses a `gcd` (greatest common divisor) helper function internally.
+
+-   **Returns**: `omdRationalNode` | `omdConstantNode` - The reduced fraction node, or an `omdConstantNode` if it simplifies to an integer.
+
+### `isProper()`
+
+Checks if the fraction is proper (the absolute value of the numerator is less than the absolute value of the denominator). This check only applies to constant fractions.
+
+-   **Returns**: `boolean` | `null` - `true` if proper, `false` if improper, `null` if the fraction is not constant.
+
+## Internal Methods
+
+-   **`parseValue()`**: Sets the `value` property to `"/"`.
+-   **`createOperand(ast)`**: Creates an `omdNode` instance for the numerator or denominator from its AST, attempting to preserve provenance.
+
+## Example
+
+```javascript
+import { omdRationalNode } from '@teachinglab/omd';
+import * as math from 'mathjs';
+
+// 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/npm-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/npm-docs/api/omdSimplification.md

@@ -0,0 +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).
+-   [`Configuration Options`](./configuration-options.md) - For configuring simplification behavior.

package/npm-docs/api/omdSqrtNode.md

@@ -0,0 +1,144 @@
+# omdSqrtNode
+
+Represents a square root node in the mathematical expression tree. It handles the rendering of the radical symbol (√) and the expression under the root (radicand), ensuring correct visual layout and mathematical behavior.
+
+## Class Definition
+
+```javascript
+export class omdSqrtNode extends omdNode
+```
+
+## Constructor
+
+### `new omdSqrtNode(astNodeData)`
+
+Creates a new `omdSqrtNode` instance.
+
+-   **`astNodeData`** (`object`): The math.js AST node containing square root function information. It should have an `args` property, which is an array containing a single AST node for the radicand. The constructor also initializes the visual `radicalPath` and `radicalLine` elements.
+
+## Static Methods
+
+### `fromString(expressionString)`
+
+Creates an `omdSqrtNode` from a string representation of a square root function. Requires `window.math` (math.js) to be available globally for parsing.
+
+-   **`expressionString`** (`string`): The square root expression as a string (e.g., `"sqrt(x+1)"`).
+-   **Returns**: `omdSqrtNode` - A new instance.
+-   **Throws**: `Error` if `math.js` is not available, if the string cannot be parsed, or if it does not represent a valid `sqrt` function.
+
+## Public Properties
+
+-   **`argument`** (`omdNode`): The node representing the radicand (the expression under the root).
+-   **`value`** (`string`): Always `"sqrt"` for this node type.
+-   **`radicalPath`** (`jsvgPath`): The SVG path element that draws the radical symbol (√).
+-   **`radicalLine`** (`jsvgLine`): The SVG line element that draws the horizontal line above the radicand.
+-   **`args`** (`Array<object>`): The raw AST arguments passed to the constructor.
+
+## Public Methods
+
+### `computeDimensions()`
+
+Calculates the dimensions of the square root node. It scales down the font size of the `argument`, computes its dimensions, and then determines the overall width (radical width + spacing + argument width) and height (argument height + extra height for the radical top).
+
+-   **Overrides**: `omdNode.computeDimensions()`.
+
+### `updateLayout()`
+
+Updates the layout of the square root node. It positions the `argument` node, then draws and positions the `radicalPath` and `radicalLine` elements relative to the argument, ensuring the radical symbol correctly encloses the radicand.
+
+-   **Overrides**: `omdNode.updateLayout()`.
+
+### `clone()`
+
+Creates a deep, structural clone of the square root node, including its `argument` node and visual elements. The cloned node's `provenance` array is updated to include the original node's ID.
+
+-   **Returns**: `omdSqrtNode` - A new, identical instance of the square root node.
+
+### `highlightAll()`
+
+Applies a highlight to the square root node itself and recursively highlights its `argument` node.
+
+### `unhighlightAll()`
+
+Removes the highlight from the square root node and recursively unhighlights its `argument` node.
+
+### `toMathJSNode()`
+
+Converts the `omdSqrtNode` back into its math.js AST representation. It creates a `FunctionNode` with `fn: 'sqrt'` and the converted `argument` AST.
+
+-   **Returns**: `object` - A math.js `FunctionNode` for the square root operation. The returned object also includes a `clone` method for compatibility.
+
+### `toString()`
+
+Converts the square root node to its string representation (e.g., `"sqrt(x+1)"`).
+
+-   **Returns**: `string`.
+
+### `evaluate(variables)`
+
+Evaluates the square root expression. It evaluates the `argument` and then calculates its square root.
+
+-   **`variables`** (`object`): A map of variable names to their numeric values.
+-   **Returns**: `number` - The evaluated square root, or `NaN` if the radicand cannot be evaluated or is negative.
+
+### `isSquareRoot()`
+
+Checks if the node represents a square root. Always returns `true` for `omdSqrtNode`.
+
+-   **Returns**: `boolean`.
+
+### `isCubeRoot()`
+
+Checks if the node represents a cube root. Always returns `false` for `omdSqrtNode`.
+
+-   **Returns**: `boolean`.
+
+### `toPowerForm()`
+
+Converts the square root node into an equivalent `omdPowerNode` representation (e.g., `sqrt(x)` becomes `x^(0.5)`).
+
+-   **Returns**: `omdPowerNode` - The equivalent power expression, or `null` if the `argument` is missing.
+
+## Internal Methods
+
+-   **`parseValue()`**: Sets the `value` property to `"sqrt"`.
+-   **`createArgumentNode()`**: Creates an `omdNode` instance for the radicand from its AST, and adds it as a child.
+-   **`createRadicalElements()`**: Creates and initializes the `jsvgPath` for the radical symbol and the `jsvgLine` for the horizontal bar, adding them as children.
+
+## Example
+
+```javascript
+import { omdSqrtNode } from '@teachinglab/omd';
+import * as math from 'mathjs';
+
+// Create from AST
+const node = new omdSqrtNode({
+  type: 'FunctionNode',
+  fn: { name: 'sqrt' },
+  args: [ { type: 'SymbolNode', name: 'x' } ]
+});
+
+// Or from string
+const node2 = omdSqrtNode.fromString('sqrt(x+1)');
+
+// Render and layout
+node.setFontSize(24);
+node.initialize();
+
+// Evaluate
+const val = node.evaluate({ x: 9 }); // 3
+
+// Convert to power form
+const powerNode = node.toPowerForm(); // x^(1/2)
+
+// Add to an SVG container to display
+// const svgContainer = new jsvgContainer();
+// svgContainer.addChild(node);
+// document.body.appendChild(svgContainer.svgObject);
+```
+
+## See Also
+
+-   [`omdNode`](./omdNode.md) - The base class.
+-   [`omdPowerNode`](./omdPowerNode.md) - For power form (e.g., `x^(1/2)`).
+-   [`omdFunctionNode`](./omdFunctionNode.md) - For other mathematical functions.

package/npm-docs/api/omdStepVisualizer.md

@@ -0,0 +1,147 @@
+# omdStepVisualizer
+
+Visualizes a sequence of mathematical steps (typically equations) and provides interactive explanations for how one step transforms into the next. It extends `omdEquationSequenceNode` by adding a visual track of dots and lines to the right of the steps, which can be clicked to reveal details about the simplification or operation applied.
+
+## Class Hierarchy
+
+```
+omdNode
+  └─ omdEquationSequenceNode
+       └─ omdStepVisualizer
+```
+
+See: [`omdEquationSequenceNode`](./omdEquationSequenceNode.md) for base sequence functionality.
+
+## Constructor
+
+### `new omdStepVisualizer(steps)`
+
+Creates a new `omdStepVisualizer` instance.
+
+-   **`steps`** (`Array<omdNode>`): An array of nodes (usually `omdEquationNode`) representing the initial steps in the sequence.
+
+During construction, it initializes internal arrays for `stepDots` and `stepLines`, creates a `visualContainer` for these elements, and sets up managers for `highlighting`, `textBoxes`, and `layout`. It also populates `nodeToStepMap` for efficient lookup.
+
+## Public Properties
+
+-   **`stepDots`** (`Array<jsvgEllipse>`): An array of `jsvgEllipse` objects representing the clickable dots for each equation step.
+-   **`stepLines`** (`Array<jsvgLine>`): An array of `jsvgLine` objects connecting the step dots.
+-   **`visualContainer`** (`jsvgLayoutGroup`): The `jsvgLayoutGroup` that holds the `stepDots` and `stepLines`.
+-   **`dotRadius`** (`number`): The radius of the step dots, determined by `omdConfigManager`.
+-   **`lineWidth`** (`number`): The stroke width of the connecting lines.
+-   **`visualSpacing`** (`number`): The horizontal spacing between the equation sequence and the visual tracker.
+-   **`activeDotIndex`** (`number`): The 0-based index of the currently active (clicked) dot. `-1` if none.
+-   **`dotsClickable`** (`boolean`): Controls whether the step dots can be clicked to show explanations. Default: `true`.
+-   **`nodeToStepMap`** (`Map<string, number>`): A map from `omdNode` IDs to their corresponding step index in the sequence.
+-   **`stepVisualizerHighlights`** (`Set<string>`): A set of node IDs that are currently highlighted by the visualizer.
+-   **`highlighting`** ([`omdStepVisualizerHighlighting`](./omdStepVisualizerHighlighting.md)): The manager responsible for all highlighting logic.
+-   **`textBoxManager`** ([`omdStepVisualizerTextBoxes`](./omdStepVisualizerTextBoxes.md)): The manager responsible for creating, positioning, and removing the explanation text boxes.
+-   **`layoutManager`** ([`omdStepVisualizerLayout`](./omdStepVisualizerLayout.md)): The manager responsible for layout and z-ordering of all visual elements.
+
+## Public Methods
+
+### `rebuildVisualizer()`
+
+Forces a complete rebuild of the visual elements (dots and lines) from scratch. This is useful after significant changes to the underlying `steps` array.
+
+### `addStep(step, options)`
+
+Adds a new step to the sequence. This method overrides the base `omdEquationSequenceNode.addStep` to also create and manage the corresponding visual dot and connecting line for the new step.
+
+-   **`step`** (`omdNode` | `string`): The node object or expression string for the step.
+-   **`options`** (`object`): Options for the step, such as `description` and `stepMark` (importance level).
+
+### `getNodeStepNumber(nodeId)`
+
+Retrieves the step number (index) associated with a given `omdNode` ID within the sequence.
+
+-   **`nodeId`** (`string`): The ID of the node to look up.
+-   **Returns**: `number` | `undefined` - The 0-based step index, or `undefined` if the node is not found within a step.
+
+### `computeDimensions()`
+
+Calculates the overall dimensions of the visualizer, accounting for the width and height of the equation sequence and the additional space required for the visual tracker (dots and lines).
+
+-   **Overrides**: `omdEquationSequenceNode.computeDimensions()`.
+
+### `updateLayout()`
+
+Updates the layout of the visualizer, positioning both the equation sequence and the visual tracker elements. It delegates to the `layoutManager` for precise positioning of dots and lines.
+
+-   **Overrides**: `omdEquationSequenceNode.updateLayout()`.
+
+### `undoLastOperation()`
+
+Removes the most recent operation and its resulting equation from the sequence. This method overrides the base `omdEquationSequenceNode.undoLastOperation` to also trigger a `rebuildVisualizer()` to ensure visual elements are synchronized.
+
+-   **Returns**: `boolean` - `true` if an operation was undone, `false` otherwise.
+
+### `setDotColor(dotIndex, color)`
+
+Sets the fill and stroke color of a specific step dot.
+
+-   **`dotIndex`** (`number`): The index of the dot to color.
+-   **`color`** (`string`): The new color.
+
+### `setLineAboveColor(dotIndex, color)`
+
+Sets the stroke color of the line segment directly above a specific step dot.
+
+-   **`dotIndex`** (`number`): The index of the dot whose preceding line should be colored.
+-   **`color`** (`string`): The new color.
+
+### `setDotsClickable(enabled)`
+
+Enables or disables the ability for users to click on the step dots to reveal explanations.
+
+-   **`enabled`** (`boolean`): `true` to enable clicking, `false` to disable.
+
+### `getStepTextBoxes()`
+
+Retrieves the array of currently visible explanation text box components managed by the `textBoxManager`.
+
+-   **Returns**: `Array<omdStepVisualizerTextBox>` - The active text box instances.
+
+## Internal Methods
+
+-   **`_initializeVisualElements()`**: Creates and initializes the visual dots and lines for all existing equation steps, and populates the `nodeToStepMap`.
+-   **`_createStepDot(equation, index)`**: Creates a single `jsvgEllipse` representing a step dot, associates it with an equation, and adds it to the `visualContainer`.
+-   **`_createStepLine(fromIndex, toIndex)`**: Creates a `jsvgLine` connecting two step dots and adds it to the `visualContainer`.
+-   **`_clearVisualElements()`**: Removes all existing dots, lines, and text boxes from the display and resets internal arrays.
+-   **`_handleDotClick(dot, dotIndex)`**: Event handler for when a step dot is clicked. It manages the active dot state, triggers highlighting, and creates/removes explanation text boxes.
+-   **`setActiveDot(dotIndex)`**: Sets a specific dot as the visually active one, changing its color and triggering the display of its explanation text box.
+-   **`_clearActiveDot()`**: Clears the currently active dot, resetting its color, removing its text box, and clearing highlights.
+-   **`_getSimplificationDataForDot(dotIndex)`**: Gathers and formats the simplification and operation data relevant to a specific step dot, used to populate the explanation text box.
+-   **`_createDefaultSimplificationData(message)`**: Helper to create a default data object for step explanations.
+-   **`_findPreviousVisibleEquationIndex(currentIndex)`**: Finds the index of the last visible equation step before the given `currentIndex`.
+-   **`_getRelevantSimplifications(simplificationHistory, startIndex, endIndex)`**: Filters the full simplification history to find entries relevant to a specific range of steps.
+-   **`_createMultipleSimplificationsData(simplifications)`**: Formats data for displaying multiple simplification events in a single text box.
+-   **`_checkForOperationStep(equationIndex)`**: Checks if a step at a given index is an `omdOperationDisplayNode` and extracts its data.
+-   **`_checkForSingleSimplification(simplificationHistory, equationIndex)`**: Checks for a single simplification entry relevant to a specific step.
+-   **`_getFallbackSimplificationData(equationIndex)`**: Provides a default explanation if no specific simplification or operation data is found for a step.
+
+## Example
+
+```javascript
+import { omdStepVisualizer } from '@teachinglab/omd';
+import { omdEquationNode } from '@teachinglab/omd';
+import { omdDisplay } from '@teachinglab/omd';
+
+// 1. Define the steps of a solution (must be omdEquationNode for dots to appear)
+const steps = [
+  omdEquationNode.fromString('2x + 4 = 10'),
+  omdEquationNode.fromString('2x = 6'),
+  omdEquationNode.fromString('x = 3')
+];
+
+// 2. Create the visualizer
+const visualizer = new omdStepVisualizer(steps);
+
+// 3. Add it to a display container
+const display = new omdDisplay(document.getElementById('container'));
+display.render(visualizer);
+
+// Now the steps will be displayed with interactive dots on the right.
+// Only omdEquationNode steps are visualized with dots/lines.
+// Clicking the dot next to "2x = 6" will explain that 4 was subtracted from both sides.
+```