@teachinglab/omd 0.5.7 → 0.6.0

package/npm-docs/api/omdFunctionNode.md

@@ -0,0 +1,83 @@
+# omdFunctionNode
+
+Represents a mathematical function call, such as `sin(x)`, `sqrt(9)`, or `log(x, 10)`. This node handles the rendering of the function name, its arguments, and surrounding parentheses. It supports evaluation, simplification, and conversion to/from math.js AST.
+
+## Class Definition
+
+```javascript
+export class omdFunctionNode extends omdNode
+```
+
+## Constructor
+
+### `new omdFunctionNode(astNodeData)`
+
+Creates a new `omdFunctionNode` instance.
+
+-   **`astNodeData`** (`object`): The math.js AST node for the function. It should contain:
+    -   `fn.name` or `name`: The name of the function (e.g., `"sin"`, `"log"`).
+    -   `args`: An array of AST nodes for the function's arguments.
+
+## Static Methods
+
+### `fromString(functionString)`
+
+Creates an `omdFunctionNode` from a string representation of a function call. This method requires `window.math` (math.js library) to be available globally for parsing.
+
+-   **`functionString`** (`string`): The function call as a string (e.g., `"sqrt(16)"`, `"log(100, 10)"`).
+-   **Returns**: `omdFunctionNode` - A new instance of `omdFunctionNode`.
+-   **Throws**: `Error` if `math.js` is not available, if the string cannot be parsed, or if it does not represent a valid function call.
+
+## Public Properties
+
+-   **`functionName`** (`string`): The name of the function (e.g., `"sin"`, `"log"`).
+-   **`args`** (`Array<omdNode>`): An array of `omdNode` instances representing the arguments of the function.
+
+## Public Methods
+
+### `computeDimensions()`
+
+Calculates the bounding box of the function node, taking into account the dimensions of the function name, arguments, and parentheses. It also sets the font sizes for the function name and arguments (arguments are typically scaled down slightly).
+
+### `updateLayout()`
+
+Positions the function name, arguments, and parentheses within the node's bounding box. It ensures proper spacing and vertical alignment of all elements.
+
+### `highlightAll()`
+
+Applies a highlight to the function node itself (its background rectangle) and recursively highlights all of its argument nodes.
+
+### `unhighlightAll()`
+
+Removes the highlight from the function node and recursively unhighlights all of its argument nodes.
+
+### `clone()`
+
+Creates a deep, structural clone of the function node, including all its argument nodes and their associated SVG elements. The clone's provenance array is updated to include the original node's ID.
+
+-   **Returns**: `omdFunctionNode` - A new, identical instance of the function node.
+
+### `toMathJSNode()`
+
+Converts the `omdFunctionNode` back into its math.js AST representation. This includes converting its function name and all argument nodes.
+
+-   **Returns**: `object` - A math.js-compatible `FunctionNode` AST object.
+
+### `toString()`
+
+Converts the function node to its string representation (e.g., `"sqrt(x^2)"`, `"log(100, 10)"`).
+
+-   **Returns**: `string` - The function as a string.
+
+### `evaluate(variables)`
+
+Evaluates the function by first evaluating its arguments and then applying the function to the results. It primarily uses `window.math` (math.js) for evaluation. If `math.js` is not available, it falls back to standard JavaScript `Math` functions for common cases (e.g., `sin`, `cos`, `sqrt`).
+
+-   **`variables`** (`object`, optional): A map of variable names to their numeric values (e.g., `{ x: 2 }`).
+-   **Returns**: `number` - The result of the function evaluation.
+-   **Throws**: `Error` if the function is unknown or cannot be evaluated.
+
+## Internal Methods
+
+-   **`createTextElements()`**: Creates `jsvgTextLine` elements for the function name and parentheses.
+-   **`createArgumentNodes()`**: Iterates through the AST arguments, creates corresponding `omdNode` instances for each, and adds them as children.

package/npm-docs/api/omdGroupNode.md

@@ -0,0 +1,79 @@
+# omdGroupNode
+
+Represents a single grouping symbol, such as `(` or `)`, as a leaf node in the expression tree. This node is primarily used for visual representation and layout, rather than mathematical operations.
+
+## Class Definition
+
+```javascript
+export class omdGroupNode extends omdLeafNode
+```
+
+## Constructor
+
+### `new omdGroupNode(nodeData)`
+
+Creates a new `omdGroupNode` instance.
+
+-   **`nodeData`** (`string`): The single character string representing the grouping symbol (e.g., `'('`, `')'`, `'['`, `']'`).
+
+## Public Properties
+
+-   **`symbol`** (`string`): The grouping symbol character (e.g., `'('`).
+-   **`type`** (`string`): Always `"parenthesis"` for this node type.
+-   **`textElement`** (`jsvgTextLine`): The internal `jsvgTextLine` instance responsible for rendering the symbol.
+
+## Public Methods
+
+### `clone()`
+
+Creates a deep clone of the group node. The new node's `provenance` array is updated to include the original node's ID.
+
+-   **Returns**: `omdGroupNode` - A new, identical instance of the group node.
+
+### `computeDimensions()`
+
+Calculates the dimensions of the node based on its text content. Unlike other leaf nodes, `omdGroupNode` does *not* add extra padding around the symbol, allowing for tighter visual integration.
+
+-   **Overrides**: `omdLeafNode.computeDimensions()`.
+
+### `updateLayout()`
+
+Updates the position of the node's internal text element. This method primarily calls the superclass's `updateLayout`.
+
+-   **Overrides**: `omdLeafNode.updateLayout()`.
+
+### `toMathJSNode()`
+
+Converts the `omdGroupNode` to a math.js-compatible AST format. It represents the grouping symbol as a `SymbolNode`.
+
+-   **Returns**: `object` - A math.js-compatible AST node with `type: "SymbolNode"` and `name` set to the grouping symbol. The returned object also includes a `clone` method for compatibility.
+
+## Internal Methods
+
+-   **`parseSymbol(nodeData)`**: Extracts the symbol from the constructor's `nodeData`. Returns the input string unchanged.
+-   **`parseType()`**: Sets the node's type. Always returns `"parenthesis"`.
+
+## Example
+
+```javascript
+// Create grouping symbols
+const leftParen = new omdGroupNode('(');
+const rightParen = new omdGroupNode(')');
+const leftBracket = new omdGroupNode('[');
+
+// Render a symbol
+const node = new omdGroupNode('(');
+node.setFontSize(24);
+node.initialize(); // Computes dimensions and layout
+
+// Add to an SVG container to display
+// const svgContainer = new jsvgContainer();
+// svgContainer.addChild(node);
+// document.body.appendChild(svgContainer.svgObject);
+```
+
+## See Also
+
+-   [`omdLeafNode`](./omdLeafNode.md) - The parent class for all leaf nodes.
+-   [`omdNode`](./omdNode.md) - The base class for all OMD nodes.
+-   [`omdParenthesisNode`](./omdParenthesisNode.md) - For complete parenthetical expressions that contain other nodes.

package/npm-docs/api/omdHelpers.md

@@ -0,0 +1,88 @@
+# omdHelpers
+
+`omdHelpers` is a collection of convenience functions designed to simplify common tasks when working with the OMD library. These helpers abstract away underlying complexities, making it easier to create and manipulate mathematical expressions and visualizations.
+
+## Overview
+
+The `omdHelpers` object is exported from the main `omd/core/index.js` entry point, making its functions readily available for use in your project.
+
+## Functions
+
+### `createNodeFromExpression(expression, mathInstance)`
+
+Creates an `omdNode` instance from a string representation of a mathematical expression. This function parses the expression using the provided math.js instance and instantiates the appropriate `omdNode` subclass.
+
+-   **`expression`** (`string`): The mathematical expression as a string (e.g., `"x^2 + 2x + 1"`).
+-   **`mathInstance`** (`object`): The math.js instance to use for parsing the expression (e.g., `window.math`).
+-   **Returns**: `omdNode` - The root `omdNode` of the created expression tree.
+
+```javascript
+import { omdHelpers } from '@teachinglab/omd';
+// Assuming math.js is loaded globally as window.math
+
+const expressionNode = omdHelpers.createNodeFromExpression('2x + 5', window.math);
+// expressionNode will be an instance of omdBinaryExpressionNode or another omdNode subclass
+```
+
+### `createEquation(equationString)`
+
+Creates an `omdEquationNode` instance from a string representation of an equation. This is a specialized helper for equations, ensuring proper parsing and node creation.
+
+-   **`equationString`** (`string`): The equation as a string (e.g., `"x + 2 = 5"`).
+-   **Returns**: `omdEquationNode` - The created `omdEquationNode`.
+
+```javascript
+import { omdHelpers } from '@teachinglab/omd';
+
+const equation = omdHelpers.createEquation('3y - 7 = 14');
+// equation will be an instance of omdEquationNode
+```
+
+### `createStepVisualizer(equationStrings)`
+
+Creates an `omdStepVisualizer` instance from an array of equation strings. This is useful for quickly setting up a step-by-step solution display.
+
+-   **`equationStrings`** (`Array<string>`): An array of strings, where each string represents an equation step (e.g., `["2x = 10", "x = 5"]`).
+-   **Returns**: `omdStepVisualizer` - The created `omdStepVisualizer` instance.
+
+```javascript
+import { omdHelpers } from '@teachinglab/omd';
+
+const steps = [
+    '4x + 8 = 20',
+    '4x = 12',
+    'x = 3'
+];
+const visualizer = omdHelpers.createStepVisualizer(steps);
+// visualizer will be an instance of omdStepVisualizer
+```
+
+## Example Usage
+
+```javascript
+import { omdDisplay, omdHelpers } from '@teachinglab/omd';
+// Assuming math.js is loaded globally as window.math
+
+// Get a container element (assuming it exists in your HTML)
+const container = document.getElementById('math-display-area');
+
+// Create an expression node using a helper
+const expression = omdHelpers.createNodeFromExpression('a^2 + b^2', window.math);
+
+// Create an equation using a helper
+const equation = omdHelpers.createEquation('E = mc^2');
+
+// Create a step visualizer using a helper
+const solutionSteps = [
+    'x + 5 = 10',
+    'x = 5'
+];
+const stepVisualizer = omdHelpers.createStepVisualizer(solutionSteps);
+
+// You can then render these nodes using omdDisplay or omdCanvas
+const display = new omdDisplay(container);
+display.render(expression);
+
+// Or for the step visualizer
+// display.render(stepVisualizer);
+```

package/npm-docs/api/omdLeafNode.md

@@ -0,0 +1,86 @@
+# omdLeafNode
+
+Represents a base class for all leaf nodes in the OMD expression tree, such as constants, variables, operators, and grouping symbols. This class provides fundamental functionalities for handling text content, computing dimensions, and managing layout for single-element nodes.
+
+## Class Definition
+
+```javascript
+export class omdLeafNode extends omdNode
+```
+
+## Constructor
+
+### `new omdLeafNode(astNodeData)`
+
+Creates a new `omdLeafNode` instance. This is an abstract base class; you should use its concrete subclasses (e.g., `omdConstantNode`, `omdVariableNode`) instead.
+
+-   **`astNodeData`** (`object`): The abstract syntax tree (AST) node data from a parser like math.js, containing information relevant to the leaf node.
+
+## Public Properties
+
+-   **`textElement`** (`jsvgTextLine`): The internal `jsvgTextLine` instance that renders the text content of the leaf node.
+
+## Public Methods
+
+### `clone()`
+
+Creates a deep clone of the leaf node. This method uses the original node's constructor to create a new instance, ensuring that the correct subclass is instantiated. The clone's `provenance` array is updated to include the original node's ID.
+
+-   **Returns**: `omdLeafNode` - A new instance of the specific leaf node subclass.
+
+### `updateTextElement(text)`
+
+Updates the text content displayed by the node's `textElement`. After updating the text, you typically need to call `computeDimensions()` and `updateLayout()` to reflect the change visually.
+
+-   **`text`** (`string` | `number`): The new text content to display.
+
+### `computeDimensions()`
+
+Calculates the dimensions (width and height) of the node based on its text content and current font size. It uses the `getTextBounds` utility function to accurately measure the text. This method also updates the font size of the internal `textElement`.
+
+-   **Overrides**: `omdNode.computeDimensions()`.
+
+### `updateLayout()`
+
+Updates the position of the node's internal text element to center it within the node's bounding box. This method primarily calls the internal `updateTextPosition()`.
+
+-   **Overrides**: `omdNode.updateLayout()`.
+
+## Internal Methods
+
+-   **`createTextElement(text)`**: Creates and initializes a `jsvgTextLine` element with the given text. It sets the text anchor to `'middle'` and dominant baseline to `'middle'` for proper centering, and adds it as a child of this node.
+    -   **Returns**: `jsvgTextLine` - The created text element.
+-   **`updateTextPosition()`**: Positions the `textElement` at the center of the node's calculated width and height.
+
+## Example
+
+```javascript
+// omdLeafNode is an abstract class—use concrete subclasses
+import { omdConstantNode } from './omdConstantNode.js';
+import { omdVariableNode } from './omdVariableNode.js';
+import { omdOperatorNode } from './omdOperatorNode.js';
+
+const constant = new omdConstantNode({ value: 5 });
+const variable = new omdVariableNode({ name: 'x' });
+const operator = new omdOperatorNode({ op: '+' });
+
+// All leaf nodes handle text rendering and layout similarly
+constant.initialize(); // Computes dimensions and layout
+variable.initialize();
+operator.initialize();
+
+// You can then add these to an omdDisplay or other container
+```
+
+## See Also
+
+Concrete implementations:
+
+-   [`omdConstantNode`](./omdConstantNode.md) - For numeric values.
+-   [`omdVariableNode`](./omdVariableNode.md) - For variables.
+-   [`omdOperatorNode`](./omdOperatorNode.md) - For operators.
+-   [`omdGroupNode`](./omdGroupNode.md) - For grouping symbols.
+
+Base class:
+
+-   [`omdNode`](./omdNode.md) - The fundamental base class for all OMD nodes.

package/npm-docs/api/omdNode.md

@@ -0,0 +1,202 @@
+# omdNode
+
+The abstract base class for all nodes in the mathematical expression tree. It provides the core functionality for tree structure (parent-child relationships), layout calculations, rendering, and provenance tracking. All specific mathematical elements (constants, variables, operators, functions, equations) extend this class.
+
+## Class Definition
+
+```javascript
+export class omdNode extends omdMetaExpression
+```
+
+This class is not meant to be instantiated directly. Instead, you should use one of its concrete subclasses (e.g., `omdConstantNode`, `omdBinaryExpressionNode`).
+
+### Key Concepts
+
+-   **AST (Abstract Syntax Tree):** Each `omdNode` is typically created from a node in the math.js AST, providing a structured representation of the mathematical expression.
+-   **Tree Structure:** Nodes are organized in a hierarchical tree with `parent` and `childList` properties, enabling traversal and manipulation of the expression.
+-   **Layout:** The `computeDimensions()` and `updateLayout()` methods are fundamental for determining the size and position of a node and its children, ensuring correct visual rendering.
+-   **Provenance:** The `provenance` array on each node tracks its history. When a node is cloned (e.g., during a simplification step), the new node's provenance array will contain the ID of the original node, creating a traceable link back to its predecessor. This is crucial for features like step-by-step explanations and highlighting.
+
+## Public Properties
+
+-   **`id`** (`number`): A unique identifier for each node instance, automatically assigned upon creation.
+-   **`type`** (`string`): A string indicating the specific type of the OMD node (e.g., `"omdConstantNode"`, `"omdBinaryExpressionNode"`).
+-   **`parent`** (`omdNode` | `null`): A reference to the parent node in the expression tree. `null` for the root node.
+-   **`astNodeData`** (`object`): The original math.js AST node from which this `omdNode` was created. This preserves the raw parsed data.
+-   **`provenance`** (`Array<number>`): An array of IDs from which this node was derived. This forms a historical chain, linking a node back through transformations or simplifications.
+-   **`argumentNodeList`** (`object`): A map (or object) containing references to the node's structurally significant children (e.g., `left`, `right` for binary expressions, `args` for functions). This is used for recursive operations and provenance tracking.
+-   **`isExplainHighlighted`** (`boolean`): A flag indicating if the node is currently highlighted for explanation purposes. This acts as a lock, preventing other highlights from overriding it.
+-   **`x`** (`number`): The x-coordinate of the node's top-left corner relative to its parent.
+-   **`y`** (`number`): The y-coordinate of the node's top-left corner relative to its parent.
+-   **`width`** (`number`): The calculated width of the node's bounding box.
+-   **`height`** (`number`): The calculated height of the node's bounding box.
+-   **`fontSize`** (`number`): The base font size applied to this node and its children.
+-   **`svgElement`** (`SVGElement`): The root SVG element that represents this node visually.
+
+## Public Methods
+
+### `initialize()`
+
+Initializes the node by recursively computing its dimensions and updating its layout. This method should be called after a node and its children have been fully constructed to ensure proper sizing and positioning.
+
+### `clone()`
+
+Creates a deep, structural clone of the node. The new node will have a new `id`, and its `provenance` will link back to the original node's `id`, establishing a historical connection.
+
+-   **Returns**: `omdNode` - A new instance of the same type as the original, with all children also cloned.
+
+### `replaceWith(newNode, options)`
+
+Replaces this node with a `newNode` in the expression tree. This updates all parent and child references and triggers a re-layout and re-rendering of the affected parts of the SVG.
+
+-   **`newNode`** (`omdNode`): The node to substitute in.
+-   **`options`** (`object`, optional): Configuration for the replacement.
+    -   `updateLayout` (`boolean`): If `true` (default), the layout of the entire tree will be recalculated upwards from the point of replacement.
+-   **Returns**: `boolean` - `true` if the replacement was successful.
+
+### `simplify()`
+
+Asynchronously attempts to simplify the expression rooted at this node by invoking the central simplification engine (`simplifyStep`).
+
+-   **Returns**: `Promise<object>` - A promise that resolves to an object like `{ success, foldedCount, newRoot, message }`. Throws an error if the `simplifyStep` function is not set.
+
+### `toMathJSNode()`
+
+Converts the `omdNode` and its children back into a math.js-compatible AST object. This method must be implemented by all concrete subclasses.
+
+-   **Returns**: `object` - The math.js AST node.
+-   **Throws**: `Error` if not implemented by the subclass.
+
+### `toString()`
+
+Converts the node into a human-readable string representation. It typically uses the `toMathJSNode()` method internally to leverage math.js's string conversion capabilities.
+
+-   **Returns**: `string`.
+
+### `render()`
+
+Generates or retrieves the SVG representation of the node. This method calls `renderSelf()` if the SVG element has not been created yet.
+
+-   **Returns**: `SVGElement` - The root SVG element representing this node.
+
+### `renderSelf()`
+
+Abstract method that must be implemented by subclasses. This method is responsible for creating the specific SVG elements and structure for the node's visual representation.
+
+-   **Returns**: `SVGElement` - The SVG element created for this node.
+-   **Throws**: `Error` if not implemented by the subclass.
+
+### `setFontSize(size)`
+
+Sets the base font size for this node and recursively propagates the new font size to all its children.
+
+-   **`size`** (`number`): The font size in pixels.
+
+### `moveTo(x, y)`
+
+Moves the node to a new absolute position (`x`, `y`) relative to its parent. It also recursively moves all children by the same delta.
+
+-   **`x`** (`number`): The new x-coordinate.
+-   **`y`** (`number`): The new y-coordinate.
+
+### `show()`
+
+Makes the node and its SVG representation visible.
+
+### `hide()`
+
+Hides the node and its SVG representation.
+
+### `getDepth()`
+
+Calculates the depth of the node in the expression tree (0 for the root node).
+
+-   **Returns**: `number` - The depth of the node.
+
+### `findParentOfType(type)`
+
+Traverses up the tree to find the nearest parent node of a specific type.
+
+-   **`type`** (`string`): The `type` property of the node to search for (e.g., `"omdEquationNode"`).
+-   **Returns**: `omdNode` | `null` - The found parent node or `null` if not found.
+
+### `validateProvenance(nodeMap)`
+
+Validates the provenance integrity of this node and all its descendants. It checks for duplicate IDs, invalid references, and self-references in the `provenance` arrays.
+
+-   **`nodeMap`** (`Map`, optional): An optional map of all known nodes in the system, used for cross-referencing provenance IDs.
+-   **Returns**: `Array<object>` - An array of validation issues found, each describing the type of issue, the node involved, and relevant IDs.
+
+### `setHighlight(highlightOn, color)`
+
+Applies or removes a highlight from the node's background. If `isExplainHighlighted` is `true`, this method will not override the existing explanation highlight.
+
+-   **`highlightOn`** (`boolean`): `true` to highlight, `false` to remove.
+-   **`color`** (`string`, optional): The color of the highlight. Defaults to `omdColor.highlightColor`.
+
+### `lowlight()`
+
+Reduces the opacity of the node's background. Similar to `setHighlight`, it respects the `isExplainHighlighted` lock.
+
+### `setFillColor(color)`
+
+Sets the fill color of the node's background rectangle. This method also respects the `isExplainHighlighted` lock.
+
+## Abstract Methods (to be implemented by subclasses)
+
+-   **`computeDimensions()`**: Calculates the `width` and `height` of the node based on its content and children. Provides a default empty implementation.
+-   **`updateLayout()`**: Positions the node's children relative to itself. Provides a default empty implementation.
+-   **`getAlignmentBaseline()`**: Returns the vertical y-coordinate within the node's bounding box that should be used for alignment with its siblings. By default, this is the vertical center (`this.height / 2`).
+-   **`isConstant()`**: Determines if the node represents a constant numerical value. Returns `false` by default.
+-   **`getValue()`**: Retrieves the numerical value of a constant node. Throws an error if the node is not constant.
+-   **`getRationalValue()`**: Retrieves the rational value of a constant node as a numerator/denominator pair. Throws an error if the node is not a constant rational expression.
+
+## Internal Methods
+
+-   **`_syncProvenanceFrom(originalNode)`**: Recursively walks a cloned node tree and sets the provenance of each node to point back to the corresponding node in the original tree. This is a crucial part of maintaining the provenance chain during cloning operations.
+-   **`replaceNodeInParent(newNode)`**: Helper method used by `replaceWith` to update specific references to this node within its parent's `argumentNodeList` and other properties.
+-   **`updateSvg(newNode)`**: Helper method used by `replaceWith` to perform the actual DOM manipulation (replacing SVG elements).
+-   **`updateLayoutUpwards()`**: Traverses up the tree from this node's parent to re-calculate dimensions and layouts for all ancestors, ensuring the entire affected tree is correctly rendered after a change.
+-   **`_validateStepsProvenance(issues)`**: Helper for `validateProvenance` to check provenance within steps.
+-   **`_findOrphanedNodes(issues)`**: Helper for `validateProvenance` to find nodes in the `nodeMap` that are no longer part of the active tree.
+-   **`_collectAllProvenanceIds(newNodeMap)`**: Collects all provenance IDs from nodes in a given map.
+-   **`_collectNodeProvenanceIds(node, referencedIds, processedNodes)`**: Recursively collects provenance IDs for a single node.
+-   **`_preserveReferencedNodes(referencedIds, newNodeMap)`**: Ensures that historical nodes referenced in provenance chains are kept in the `nodeMap`.
+-   **`_preserveNodeAndContext(id, newNodeMap, processedIds)`**: Preserves a historical node and its relevant parent/sibling context.
+-   **`_preserveParentContext(node, newNodeMap)`**: Preserves the parent nodes of a historical node.
+-   **`_preserveSiblingContext(node, newNodeMap)`**: Preserves the sibling nodes of a historical node.
+
+## Example
+
+```javascript
+// omdNode is an abstract class - use concrete subclasses
+import { omdConstantNode } from './omdConstantNode.js';
+import { omdBinaryExpressionNode } from './omdBinaryExpressionNode.js';
+import { omdDisplay } from '../display/omdDisplay.js';
+
+// Create a simple expression tree
+const two = new omdConstantNode({ value: 2 });
+const x = new omdVariableNode({ name: 'x' });
+const twoX = new omdBinaryExpressionNode({
+    type: 'OperatorNode', op: '*', fn: 'multiply',
+    args: [two.astNodeData, x.astNodeData],
+    implicit: true
+});
+
+// Initialize the root node (this will recursively initialize children)
+twoX.initialize();
+
+// Render it using omdDisplay
+const container = document.getElementById('math-container');
+const display = new omdDisplay(container);
+display.render(twoX);
+
+console.log(twoX.toString()); // Output: 2x
+```
+
+## See Also
+
+-   [`omdLeafNode`](./omdLeafNode.md) - The base class for nodes with no children (constants, variables, operators).
+-   [`omdBinaryExpressionNode`](./omdBinaryExpressionNode.md) - For nodes with two children (e.g., addition, subtraction, multiplication).
+-   [`omdFunctionNode`](./omdFunctionNode.md) - For function calls (e.g., `sin(x)`).
+-   [`omdEquationNode`](./omdEquationNode.md) - For representing mathematical equations.

package/npm-docs/api/omdOperationDisplayNode.md

@@ -0,0 +1,118 @@
+# omdOperationDisplayNode
+
+Represents a visual node for displaying an operation applied to both sides of an equation. This node is designed to show the operation (e.g., `+5` or `×2`) on both the left and right sides of an equation, typically used in step-by-step solution visualizers. It is non-interactive and non-highlightable by design.
+
+## Class Definition
+
+```javascript
+export class omdOperationDisplayNode extends omdNode
+```
+
+## Static Properties
+
+### `OPERATOR_SYMBOLS`
+
+A static map that defines the display symbols for various operations.
+
+```javascript
+static OPERATOR_SYMBOLS = {
+    'add': '+',
+    'subtract': '-',
+    'multiply': '×',
+    'divide': '÷'
+};
+```
+
+## Constructor
+
+### `new omdOperationDisplayNode(operation, value)`
+
+Creates a new `omdOperationDisplayNode` instance.
+
+-   **`operation`** (`string`): The type of operation (e.g., `'add'`, `'subtract'`, `'multiply'`, `'divide'`).
+-   **`value`** (`number` | `string` | `omdNode`): The value being applied in the operation. Can be a number, a variable name string, or an `omdNode` instance.
+
+During construction, the node initializes its display, creates the visual elements for the operation, disables all user interactions and highlighting, and adds the elements as children.
+
+## Public Properties
+
+-   **`operation`** (`string`): The type of operation (e.g., `'add'`, `'subtract'`).
+-   **`value`** (`number` | `string` | `omdNode`): The value used in the operation.
+-   **`type`** (`string`): Always `"omdOperationDisplayNode"`.
+-   **`leftToken`** (`omdVariableNode`): The `omdVariableNode` representing the operation and value on the left side.
+-   **`rightToken`** (`omdVariableNode`): The `omdVariableNode` representing the operation and value on the right side.
+-   **`gap`** (`number`): The horizontal spacing between the left and right operation tokens.
+-   **`leftClusterWidth`** (`number`): The calculated width of the left operation token, used for alignment in equation sequences.
+
+## Public Methods
+
+### `computeDimensions()`
+
+Calculates the dimensions (width and height) of the operation display node. It determines the total width by summing the widths of the left and right tokens and the `gap` between them. The height is based on the tallest token with some vertical padding.
+
+### `updateLayout()`
+
+Updates the layout of the operation display node. It positions the `leftToken` at the beginning and the `rightToken` after the calculated `gap`, ensuring they are vertically centered within the node's height.
+
+### `getLeftWidthForAlignment()`
+
+Returns the effective width of the left operation cluster. This is used by `omdEquationSequenceNode` to align the equals signs of equations with the center of the gap in the operation display.
+
+-   **Returns**: `number`.
+
+### `showLeftOnly()`
+
+Hides the right operation token and recalculates the dimensions and layout to display only the left operation. This is useful for scenarios where only one side of the operation needs to be shown.
+
+### `clone()`
+
+Creates a deep clone of the `omdOperationDisplayNode`. The cloned node will have the same operation and value, and its provenance will link back to the original node. The cloned node is also made non-highlightable.
+
+-   **Returns**: `omdOperationDisplayNode` - A new, identical instance.
+
+## Internal Methods
+
+-   **`_initializeDisplay()`**: Sets up the initial display properties, making the background transparent and ensuring the node is non-highlightable.
+-   **`_createOperationElements()`**: Creates the `leftToken` and `rightToken` `omdVariableNode` instances based on the operation and value, and immediately disables their highlighting.
+-   **`_disableAllInteractions()`**: Calls helper methods to disable mouse interactions and highlighting for both operation tokens.
+-   **`_addChildElements()`**: Adds the `leftToken` and `rightToken` as children of this node.
+-   **`_getOperatorSymbol(operation)`**: Converts the operation name (e.g., `'add'`) to its corresponding display symbol (e.g., `'+'`).
+-   **`_valueToString(value)`**: Converts the input `value` (number, string, or `omdNode`) into a string representation for display.
+-   **`_disableElement(element)`**: Recursively disables background, mouse interactions, and highlighting for a given `omdNode` and its children.
+-   **`_hideElementBackground(element)`**: Sets the background of an element to transparent.
+-   **`_disableMouseInteractions(element)`**: Removes mouse event listeners and sets the cursor to `'default'`.
+-   **`_disableHighlighting(element)`**: Overrides highlighting methods (`setHighlight`, `lowlight`, `setFillColor`) on an element to prevent it from being highlighted.
+-   **`_makeNodeNonHighlightable()`**: Applies the `_disableHighlighting` logic to the `omdOperationDisplayNode` itself.
+-   **`_disableChildElements(element)`**: Recursively calls `_disableElement` on all children of a given element.
+
+## Example
+
+```javascript
+// Create operation display for subtracting 3
+const subtractNode = new omdOperationDisplayNode('subtract', 3);
+
+// Create operation display for multiplying by 'x'
+const multiplyNode = new omdOperationDisplayNode('multiply', 'x');
+
+// Create operation display for dividing by a complex expression
+const complexDivideNode = new omdOperationDisplayNode('divide', {
+  type: 'OperatorNode',
+  op: '+',
+  args: [
+    { type: 'ConstantNode', value: 1 },
+    { type: 'SymbolNode', name: 'x' }
+  ]
+});
+
+// To render these, you would typically add them to an omdEquationSequenceNode
+// or an omdDisplay.
+// For example:
+// const display = new omdDisplay(document.getElementById('container'));
+// display.render(subtractNode);
+```
+
+## See Also
+
+-   [`omdNode`](./omdNode.md) - The base class for all OMD nodes.
+-   [`omdEquationNode`](./omdEquationNode.md) - For representing mathematical equations.
+-   [`omdEquationSequenceNode`](./omdEquationSequenceNode.md) - For managing sequences of equation steps.