@teachinglab/omd 0.6.1 → 0.6.3

package/npm-docs/api/omdSqrtNode.md

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

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