@teachinglab/omd 0.5.7 → 0.6.0

package/npm-docs/api/omdEquationNode.md

@@ -0,0 +1,174 @@
+# omdEquationNode
+
+Represents a mathematical equation, consisting of a left side, a right side, and an equals sign. This class provides extensive functionality for manipulating the equation, such as applying operations to both sides, swapping sides, simplification, and rendering to various visualization formats.
+
+## Class Definition
+
+```javascript
+export class omdEquationNode extends omdNode
+```
+
+## Constructor
+
+### `new omdEquationNode(ast)`
+
+Creates a new `omdEquationNode` instance.
+
+-   **`ast`** (`object`): The math.js Abstract Syntax Tree (AST) for the equation. It typically expects an `AssignmentNode` (with `object` for the left side and `value` for the right side) or an `OperatorNode` (with `op: '='` and two arguments).
+
+## Static Methods
+
+### `fromString(equationString)`
+
+Creates an `omdEquationNode` instance from a string representation of an equation.
+
+-   **`equationString`** (`string`): The string to parse (e.g., `"2x + 4 = 10"`).
+-   **Returns**: `omdEquationNode` - A new instance of `omdEquationNode`.
+-   **Throws**: `Error` if the string is not a valid equation (must contain exactly one `'='` and both sides must be non-empty).
+
+## Public Properties
+
+-   **`left`** ([`omdNode`](./omdNode.md)): The node representing the left side of the equation.
+-   **`right`** ([`omdNode`](./omdNode.md)): The node representing the right side of the equation.
+-   **`equalsSign`** ([`omdOperatorNode`](./omdOperatorNode.md)): The node for the equals sign.
+
+## Public Methods
+
+### `addToBothSides(value)`
+
+Returns a new equation with a value added to both sides.
+
+-   **`value`** (`number` | `object`): The value (number or math.js AST) to add.
+-   **Returns**: `omdEquationNode` - A new equation node with the operation applied.
+
+### `subtractFromBothSides(value)`
+
+Returns a new equation with a value subtracted from both sides.
+
+-   **`value`** (`number` | `object`): The value (number or math.js AST) to subtract.
+-   **Returns**: `omdEquationNode` - A new equation node.
+
+### `multiplyBothSides(value)`
+
+Returns a new equation with both sides multiplied by a value.
+
+-   **`value`** (`number` | `object`): The value (number or math.js AST) to multiply by.
+-   **Returns**: `omdEquationNode` - A new equation node.
+
+### `divideBothSides(value)`
+
+Returns a new equation with both sides divided by a value.
+
+-   **`value`** (`number` | `object`): The value (number or math.js AST) to divide by.
+-   **Returns**: `omdEquationNode` - A new equation node.
+
+### `applyFunction(functionName)`
+
+Applies a function (e.g., `sqrt`, `log`) to both sides of the equation.
+
+-   **`functionName`** (`string`): The name of the function to apply.
+-   **Returns**: `omdEquationNode` - A new equation with the function applied to both sides.
+
+### `applyOperation(value, operation, side = 'both')`
+
+Applies an arithmetic operation to one or both sides of the equation.
+
+-   **`value`** (`number` | `omdNode`): The value to apply.
+-   **`operation`** (`string`): The operation to perform: `'add'`, `'subtract'`, `'multiply'`, or `'divide'`.
+-   **`side`** (`string`): The side to apply the operation to: `'left'`, `'right'`, or `'both'`. Defaults to `'both'`.
+-   **Returns**: `omdEquationNode` - A new equation node with the operation applied.
+
+### `swapSides()`
+
+Swaps the left and right sides of the equation.
+
+-   **Returns**: `omdEquationNode` - A new equation node with the sides swapped.
+
+### `simplify()`
+
+Simplifies both sides of the equation using the simplification engine.
+
+-   **Returns**: `object` - An object containing `{ success, newRoot, message }`.
+
+### `clone()`
+
+Creates a deep clone of the equation node, preserving its structure and provenance.
+
+-   **Returns**: `omdEquationNode` - A new, identical instance of the equation node.
+
+### `toString()`
+
+Converts the equation to its string representation.
+
+-   **Returns**: `string` - The equation as a string (e.g., `"x + 1 = 5"`).
+
+### `evaluate(variables)`
+
+Evaluates both sides of the equation with a given set of variables.
+
+-   **`variables`** (`object`): A map of variable names to their numeric values (e.g., `{ x: 2 }`).
+-   **Returns**: `object` - An object with the evaluated `left` and `right` side values.
+
+### `setBackgroundStyle(style)`
+
+Configures the background styling for the equation node. This can include `backgroundColor`, `cornerRadius`, and `pill` (for a pill-shaped background).
+
+-   **`style`** (`object`): An object containing style properties.
+
+### `getEqualsAnchorX()`
+
+Returns the horizontal X-coordinate of the center of the equals sign relative to this node's origin. Useful for aligning equations in a sequence.
+
+-   **Returns**: `number`.
+
+### `getBackgroundPaddingX()`
+
+Returns the horizontal padding applied by the background style.
+
+-   **Returns**: `number`.
+
+### `getEffectiveBackgroundPaddingX()`
+
+Returns the effective horizontal padding used in layout, accounting for factors like pill clamping.
+
+-   **Returns**: `number`.
+
+### `renderTo(visualizationType, options)`
+
+Renders the equation to different visualization formats (e.g., graph, table, balance hanger, tile equation).
+
+-   **`visualizationType`** (`string`): The type of visualization (`"graph"`, `"table"`, `"hanger"`, `"tileequation"`).
+-   **`options`** (`object`, optional): Configuration options specific to the visualization type.
+-   **Returns**: `object` - A JSON object conforming to the schemas defined in `src/json-schemas.md`.
+
+### `getLeft()`
+
+Returns the `omdNode` representing the left side of the equation.
+
+-   **Returns**: `omdNode`.
+
+### `getRight()`
+
+Returns the `omdNode` representing the right side of the equation.
+
+-   **Returns**: `omdNode`.
+
+## Internal Methods
+
+-   **`_applyOperation(value, op, fn)`**: Internal helper for applying arithmetic operations to both sides.
+-   **`_needsParenthesesForOperation(node, operation)`**: Determines if a child node needs parentheses when an operation is applied, based on operator precedence.
+-   **`_createNodeFromValue(value)`**: Converts a number or math.js AST into an appropriate `omdNode`.
+-   **`_establishGranularProvenance(newNode, originalNode, operationValue, operation)`**: Manages provenance tracking for equation operations, linking new nodes to their origins.
+-   **`_isMultiplicationOperation(node)`**: Checks if a given node represents a multiplication operation.
+-   **`_copyProvenanceStructure(target, source)`**: Recursively copies provenance information from a source node to a target node.
+-   **`_createFunctionNode(functionName, argument)`**: Creates an `omdFunctionNode` wrapping a given argument.
+-   **`_createNewEquation(left, right)`**: Creates a new `omdEquationNode` from two `omdNode` instances.
+-   **`_getEffectivePadding(contentHeight)`**: Computes effective padding for background styling, considering pill radius clamping.
+-   **`_applyPillToDescendants()`**: Applies pill-shaped corner radius to all descendant nodes' backgrounds when the parent equation uses a pill style.
+-   **`_matchChildBackgrounds(color)`**: Hides child node backgrounds by setting their color to match the parent equation's background.
+-   **`_renderToGraph(options)`**: Generates JSON for a coordinate plane graph visualization.
+-   **`_renderToTable(options)`**: Generates JSON for a table visualization.
+-   **`_renderSingleSideTable(side, title, options)`**: Helper for generating tables for a single side of the equation.
+-   **`_renderToHanger()`**: Generates JSON for a balance hanger visualization.
+-   **`_normalizeExpressionString(expr)`**: Normalizes expression strings for evaluation/graphing (e.g., inserts `*` for implicit multiplication).
+-   **`_convertToHangerValues(node)`**: Converts an equation side into values suitable for a balance hanger visualization.

package/npm-docs/api/omdEquationSequenceNode.md

@@ -0,0 +1,259 @@
+# omdEquationSequenceNode
+
+Represents a sequence of equations or mathematical expressions, designed for step-by-step calculations and visual problem-solving. This node manages the vertical layout of multiple steps, ensuring elements like equals signs are vertically aligned for readability. It also provides robust provenance tracking, simplification capabilities, and filtering options for displaying different levels of detail.
+
+## Class Definition
+
+```javascript
+export class omdEquationSequenceNode extends omdNode
+```
+
+## Constructor
+
+### `new omdEquationSequenceNode(steps)`
+
+Creates a new `omdEquationSequenceNode` instance.
+
+-   **`steps`** (`Array<omdNode>`): An initial array of `omdNode` objects (typically `omdEquationNode` or `omdOperationDisplayNode`) representing the sequence of steps.
+
+Upon construction, the sequence initializes its internal state, sets up layout helpers, and builds a comprehensive node map for provenance tracking across all steps.
+
+## Static Properties
+
+### `OPERATION_MAP`
+
+A static map that links common operation names (e.g., `'add'`) to the corresponding method names on `omdEquationNode` (e.g., `'addToBothSides'`).
+
+```javascript
+{
+    'add': 'addToBothSides',
+    'subtract': 'subtractFromBothSides',
+    'multiply': 'multiplyBothSides',
+    'divide': 'divideBothSides',
+}
+```
+
+## Static Methods
+
+### `fromStringArray(stepStrings)`
+
+Creates an `omdEquationSequenceNode` instance from an array of equation strings. Each string must contain an equals sign (`=`).
+
+-   **`stepStrings`** (`Array<string>`): An array of strings, each representing an equation step.
+-   **Returns**: `omdEquationSequenceNode` - A new instance.
+-   **Throws**: `Error` if any string is not a valid equation (e.g., missing `=` or invalid format).
+
+### `fromSteps(stepsArray)`
+
+Creates an `omdEquationSequenceNode` instance from an array of expression strings. This method is more flexible than `fromStringArray` as it can parse both full equations (containing `=`) and general mathematical expressions.
+
+-   **`stepsArray`** (`Array<string>`): An array of expression strings.
+-   **Returns**: `omdEquationSequenceNode` - A new sequence node.
+
+## Public Properties
+
+-   **`steps`** (`Array<omdNode>`): An array of `omdNode` objects representing each step in the sequence.
+-   **`currentStepIndex`** (`number`): The 0-based index of the currently active step. Default: `0`.
+-   **`stepDescriptions`** (`Array<string>`): An array storing optional human-readable descriptions for each step.
+-   **`importanceLevels`** (`Array<number>`): An array storing the importance level (0, 1, or 2) for each step, used for filtering.
+-   **`currentFilterLevels`** (`Array<number>`): An array of numbers representing the currently active importance levels for step visibility. Default: `[0]`.
+-   **`defaultEquationBackground`** (`object` | `null`): An object defining a default background style to be applied to all `omdEquationNode` steps added to the sequence.
+
+## Public Methods
+
+### `getCurrentEquation()`
+
+Retrieves the last `omdEquationNode` in the sequence, which typically represents the current working equation.
+
+-   **Returns**: `omdEquationNode` | `null` - The last equation, or `null` if no equations exist.
+
+### `getCurrentStep()`
+
+Retrieves the currently active step node based on `currentStepIndex` and visibility. It prioritizes visible equation nodes.
+
+-   **Returns**: `omdNode` | `null` - The current step node.
+
+### `addStep(step, descriptionOrOptions, importance)`
+
+Adds a new step to the sequence. This method supports multiple signatures:
+
+-   `addStep(omdNode, optionsObject)`
+-   `addStep(omdNode, descriptionString, importanceNumber)`
+-   `addStep(expressionString, optionsObject)`
+-   `addStep(expressionString, descriptionString, importanceNumber)`
+
+-   **`step`** (`omdNode` | `string`): The `omdNode` object or an expression string for the step.
+-   **`descriptionOrOptions`** (`object` | `string`, optional): An options object (e.g., `{ description: '...', stepMark: 0 }`) or a description string.
+-   **`importance`** (`number`, optional): The importance level (0, 1, or 2) if `descriptionOrOptions` is a string.
+-   **Returns**: `number` - The index of the added step.
+
+### `setDefaultEquationBackground(style)`
+
+Sets a default background style that will be applied to all new `omdEquationNode` steps added to the sequence. It also applies the style to existing `omdEquationNode` steps immediately.
+
+-   **`style`** (`object`): An object defining the background style (e.g., `{ backgroundColor: '#f0f0f0', cornerRadius: 8, pill: true }`).
+
+### `rebuildNodeMap()`
+
+Rebuilds the internal `nodeMap`, which is a comprehensive map of all `omdNode` instances within the entire sequence, including historical nodes referenced in provenance chains. This is crucial for accurate highlighting and provenance tracking.
+
+### `recordSimplificationHistory(name, affectedNodes, message, metadata)`
+
+Records a simplification step in the sequence's history.
+
+-   **`name`** (`string`): The name of the simplification rule applied.
+-   **`affectedNodes`** (`Array<string>`): An array of node IDs that were affected by the simplification.
+-   **`message`** (`string`): A human-readable description of the simplification.
+-   **`metadata`** (`object`, optional): Additional metadata about the simplification.
+
+### `getSimplificationHistory()`
+
+Retrieves the complete simplification history for this sequence.
+
+-   **Returns**: `Array<object>` - An array of simplification history entries.
+
+### `clearSimplificationHistory()`
+
+Clears all recorded simplification history entries.
+
+### `setFontSize(fontSize)`
+
+Sets the font size for the entire sequence and propagates this setting to all individual steps. This triggers a re-computation of dimensions and layout.
+
+-   **`fontSize`** (`number`): The new font size in pixels.
+
+### `applyEquationOperation(value, operation)`
+
+Applies a specified arithmetic operation to the current equation in the sequence and adds the result as a new step. This method also adds an `omdOperationDisplayNode` to visually represent the operation.
+
+-   **`value`** (`number` | `string`): The constant value or expression string to apply.
+-   **`operation`** (`string`): The operation name (`'add'`, `'subtract'`, `'multiply'`, `'divide'`).
+-   **Returns**: `omdEquationSequenceNode` - Returns this sequence instance for chaining.
+
+### `applyEquationFunction(functionName)`
+
+Applies a mathematical function (e.g., `'sqrt'`, `'log'`) to both sides of the current equation in the sequence and adds the result as a new step.
+
+-   **`functionName`** (`string`): The name of the function to apply.
+-   **Returns**: `omdEquationSequenceNode` - Returns this sequence instance for chaining.
+
+### `simplify()`
+
+Applies one round of simplification rules to the last step in the sequence. If simplifications are applied, a new step is added to the sequence.
+
+-   **Returns**: `object` - A result object containing `success` (boolean), `foldedCount` (number of operations applied), `isFinalSimplification` (boolean), and `message` (string).
+
+### `simplifyAll(maxIterations)`
+
+Repeatedly calls `simplify()` until no more simplifications can be applied or `maxIterations` is reached. This adds multiple simplification steps to the sequence.
+
+-   **`maxIterations`** (`number`, optional): Maximum number of iterations to prevent infinite loops. Default: `50`.
+-   **Returns**: `object` - A result object containing `success`, `totalSteps`, `iterations`, and `message`.
+
+### `evaluate(variables)`
+
+Evaluates the current step in the sequence with the given variables and logs the result to the console.
+
+-   **`variables`** (`object`): A map of variable names to their numeric values.
+
+### `validateSequenceProvenance()`
+
+Validates the integrity of provenance tracking across all steps in the sequence.
+
+-   **Returns**: `Array<object>` - An array of validation issues found.
+
+### `select()` / `deselect()` / `highlight(color)` / `clearProvenanceHighlights()`
+
+These methods override the default `omdNode` behavior. The `omdEquationSequenceNode` itself does not highlight or respond to selection events directly. Instead, these methods propagate the calls to their child steps, allowing individual steps to be highlighted or selected.
+
+### `computeDimensions()`
+
+Calculates the overall dimensions (width and height) of the entire sequence, determining the correct alignment point for all equals signs.
+
+### `updateLayout()`
+
+Positions each step vertically and aligns their equals signs to the calculated alignment point, ensuring a clean, readable layout.
+
+### `toMathJSNode()`
+
+Converts the sequence to a math.js-compatible AST node. Currently, this returns the AST of the last step in the sequence.
+
+-   **Returns**: `object` - A math.js AST node.
+
+### `navigateToStep(index)`
+
+Navigates to a specific step in the sequence by setting `currentStepIndex`.
+
+-   **`index`** (`number`): The 0-based index of the step to navigate to.
+-   **Returns**: `boolean` - `true` if navigation was successful.
+
+### `nextStep()`
+
+Navigates to the next step in the sequence.
+
+-   **Returns**: `boolean` - `true` if there was a next step.
+
+### `previousStep()`
+
+Navigates to the previous step in the sequence.
+
+-   **Returns**: `boolean` - `true` if there was a previous step.
+
+### `getFilteredSteps(maxImportance)`
+
+Retrieves steps filtered by their importance level.
+
+-   **`maxImportance`** (`number`): The maximum importance level to include (0, 1, or 2).
+-   **Returns**: `Array<object>` - An array of objects, each containing `step`, `description`, `importance`, and `index`.
+
+### `renderCurrentStep()`
+
+Renders only the current step of the sequence.
+
+-   **Returns**: `SVGElement` - The SVG representation of the current step.
+
+### `toString()`
+
+Converts the entire sequence to a multi-line string representation, including step descriptions.
+
+-   **Returns**: `string` - Multi-line string of all steps.
+
+### `clear()`
+
+Removes all steps from the sequence, clears all associated data (descriptions, importance levels, history), and resets the sequence to its initial state.
+
+### `show()` / `hide()`
+
+Overrides `omdNode`'s `show()` and `hide()` to also update the visibility of the layout manager.
+
+### `updateStepsVisibility(visibilityPredicate)`
+
+Updates the visibility of multiple steps at once based on a provided predicate function. Also applies font weights based on `stepMark`.
+
+-   **`visibilityPredicate`** (`Function`): A function that takes a step node and returns `true` if it should be visible, `false` otherwise.
+
+## Internal Methods
+
+-   **`_initializeState()`**: Initializes internal state variables like `currentStepIndex`, `stepDescriptions`, etc.
+-   **`_initializeLayout()`**: Sets up the `jsvgLayoutGroup` for vertical arrangement.
+-   **`_initializeNodeMap()`**: Initializes the `nodeMap` and calls `rebuildNodeMap()`.
+-   **`_disableContainerInteractions()`**: Disables default mouse interactions on the sequence container.
+-   **`_markInitialSteps()`**: Marks the initial steps with a default `stepMark` of 0.
+-   **`_applyDefaultFilter()`**: Applies the default filter (showing only level 0 steps) upon initialization.
+-   **`_reapplyCurrentFilter()`**: Reapplies the currently set filter levels to ensure consistent visibility.
+-   **`_determineStepMark(step, options)`**: Determines the appropriate `stepMark` for a new step.
+-   **`_isFullySimplified(step)`**: Heuristic to check if an equation step appears fully simplified.
+-   **`_isSimpleExpression(node)`**: Heuristic to check if an expression is simple (constant, variable, or simple operations).
+-   **`preserveProvenanceHistory(newNodeMap)`**: Ensures historical nodes referenced in provenance chains are preserved in the `nodeMap`.
+-   **`_collectAllProvenanceIds(newNodeMap)`**: Collects all provenance IDs from nodes in the `newNodeMap`.
+-   **`_collectNodeProvenanceIds(node, referencedIds, processedNodes)`**: Recursively collects provenance IDs for a given node.
+-   **`_preserveReferencedNodes(referencedIds, newNodeMap)`**: Preserves nodes referenced by `referencedIds` in the `newNodeMap`.
+-   **`_preserveNodeAndContext(id, newNodeMap, processedIds)`**: Preserves a node and its parent/sibling context.
+-   **`_preserveParentContext(node, newNodeMap)`**: Preserves the parent context of a node.
+-   **`_preserveSiblingContext(node, newNodeMap)`**: Preserves the sibling context of a node.
+-   **`_handleSuccessfulSimplification(originalStep, simplificationResult)`**: Handles the result of a successful simplification, adding a new step and recording history.
+-   **`_getOperationDescription(operation, value, isUnsimplified)`**: Generates a human-readable description for an equation operation.
+-   **`_calculateAlignmentPoint(visibleSteps)`**: Calculates the optimal X-coordinate for aligning equals signs across all visible steps.
+-   **`_calculateTotalDimensions(visibleSteps)`**: Calculates the total width and height of the sequence.
+-   **`_computeStepXOffset(step)`**: Computes the horizontal offset needed to align a step within the sequence.
+-   **`_stringToNode(str)`**: Converts an expression string into an `omdNode` (either `omdEquationNode` or a general expression node).

package/npm-docs/api/omdEquationStack.md

@@ -0,0 +1,193 @@
+# omdEquationStack
+
+A renderable component that bundles a sequence of mathematical equations with optional UI controls (toolbar). It extends `jsvgGroup` and acts as a node that can be rendered by an `omdDisplay`.
+
+## Class Definition
+
+```js
+import { omdEquationStack } from './omd/core/omdEquationStack.js';
+```
+
+## Constructor
+
+### `new omdEquationStack(steps, options)`
+
+Creates a new `omdEquationStack` instance.
+
+-   **`steps`** (`Array<omdNode>`, optional): An initial array of equation steps. Default: empty array.
+-   **`options`** (`object`, optional): Configuration options:
+    -   **`toolbar`** (`boolean` | `object`): If `true`, creates a toolbar for equation operations. Can also be an object for more granular control:
+        -   `enabled` (`boolean`): Whether the toolbar is enabled. Default: `false`.
+        -   `position` (`string`): Where the toolbar should be positioned (`'bottom'`, `'overlay-bottom'`). Default: `'bottom'`.
+        -   `showUndoButton` (`boolean`): Whether to show an undo button. Default: `false`.
+        -   `onUndo` (`function`): Custom undo handler. If not provided, it attempts to call `window.onOMDToolbarUndo`.
+        -   `overlayPadding` (`number`): Padding from the bottom edge when `position` is `'overlay-bottom'`. Default: `34`.
+    -   **`stepVisualizer`** (`boolean`): If `true`, the underlying sequence will be an `omdStepVisualizer` instead of a plain `omdEquationSequenceNode`. Default: `false`.
+    -   **`styling`** (`object`): Styling options for the equation stack:
+        -   `equationBackground` (`object`): Default background style for equation steps (e.g., `{ backgroundColor: '#f0f0f0', cornerRadius: 8, pill: true }`).
+
+## Public Properties
+
+-   **`sequence`** (`omdEquationSequenceNode` | `omdStepVisualizer`): The underlying sequence component that manages the equation steps.
+-   **`toolbar`** (`omdToolbar` | `undefined`): The toolbar component instance, if enabled.
+-   **`layoutGroup`** (`jsvgLayoutGroup`): The internal layout container that arranges the sequence and toolbar vertically.
+-   **`options`** (`object`): The merged configuration options passed to the constructor.
+-   **`overlayPadding`** (`number`): The calculated padding for the toolbar when it's in an overlay position.
+
+## Public Methods
+
+### `updateLayout()`
+
+Updates the layout and positioning of internal components. This method ensures the sequence and toolbar are correctly arranged and that the toolbar is horizontally centered if it's in-flow.
+
+### `getSequence()`
+
+Returns the underlying sequence instance (either `omdEquationSequenceNode` or `omdStepVisualizer`).
+
+-   **Returns**: `omdEquationSequenceNode` | `omdStepVisualizer`.
+
+### `getToolbar()`
+
+Returns the toolbar instance, if one was created during construction.
+
+-   **Returns**: `omdToolbar` | `undefined`.
+
+### `getOverlayPadding()`
+
+Returns the padding value used for positioning the toolbar when it's in an overlay mode.
+
+-   **Returns**: `number`.
+
+### `getToolbarVisualHeight()`
+
+Returns the unscaled visual height of the toolbar's background element, if the toolbar is present.
+
+-   **Returns**: `number`.
+
+### `isToolbarOverlay()`
+
+Checks if the toolbar is configured to be overlaid at the bottom of the container.
+
+-   **Returns**: `boolean`.
+
+### `positionToolbarOverlay(containerWidth, containerHeight, padding)`
+
+Positions the toolbar overlay at the bottom center of the container. This method is typically called by the `omdDisplay` to ensure the toolbar remains visible and correctly placed even when the main content scales.
+
+-   **`containerWidth`** (`number`): The width of the parent container.
+-   **`containerHeight`** (`number`): The height of the parent container.
+-   **`padding`** (`number`, optional): Padding from the bottom edge. Default: `16`.
+
+### `undoLastOperation()`
+
+Removes the last equation step and any preceding operation display node from the sequence. This method also triggers a re-layout and updates any associated step visualizer.
+
+-   **Returns**: `boolean` - `true` if an operation was successfully undone, `false` otherwise.
+
+## Usage
+
+The `omdEquationStack` component is a complete equation solving interface that combines an equation sequence with an optional toolbar. It automatically handles layout and positioning.
+
+```javascript
+import { omdDisplay } from 'omd';
+import { omdEquationStack } from 'omd';
+import { omdEquationNode } from 'omd';
+
+// Create display
+const container = document.getElementById('math-display');
+const display = new omdDisplay(container);
+
+// Create equation steps
+const steps = [
+    omdEquationNode.fromString('2x + 3 = 11'),
+    omdEquationNode.fromString('2x = 8'),
+    omdEquationNode.fromString('x = 4')
+];
+
+// Basic equation stack with toolbar
+const stack = new omdEquationStack(steps, {
+    toolbar: true
+});
+
+// Render the stack
+display.render(stack);
+
+// Alternative: Create with step visualizer and custom toolbar options
+const stackWithVisualizer = new omdEquationStack(steps, {
+    toolbar: {
+        enabled: true,
+        showUndoButton: true,
+        position: 'overlay-bottom'
+    },
+    stepVisualizer: true,
+    styling: {
+        equationBackground: {
+            backgroundColor: '#e0f7fa',
+            cornerRadius: 10,
+            pill: true
+        }
+    }
+});
+
+display.render(stackWithVisualizer);
+```
+
+## Integration
+
+The equation stack integrates seamlessly with the step visualizer:
+
+```javascript
+import { omdEquationStack } from 'omd';
+import { omdEquationNode } from 'omd';
+import { omdDisplay } from 'omd';
+
+// Create steps for a more complex equation
+const steps = [
+    omdEquationNode.fromString('x/2 + 3 = 7'),
+    omdEquationNode.fromString('x/2 = 4'),
+    omdEquationNode.fromString('x = 8')
+];
+
+// Enable step visualizer with highlighting
+const stack = new omdEquationStack(steps, {
+    toolbar: true,
+    stepVisualizer: true
+});
+
+// Render in display
+const container = document.getElementById('equation-display');
+const display = new omdDisplay(container);
+display.render(stack);
+
+// Access the visualizer for programmatic control
+const visualizer = stack.getSequence();
+// visualizer.nextStep(); // Progress through solution steps if interactive
+```
+
+## Layout Behavior
+
+The equation stack automatically manages its internal layout:
+- The sequence is positioned at the top
+- The toolbar (if present) is centered below the sequence
+- Layout updates automatically when content changes
+
+```javascript
+// Create a stack and let it handle layout automatically
+const stack = new omdEquationStack(steps, { toolbar: true });
+
+// Manual layout update (rarely needed)
+stack.updateLayout();
+
+// Access components
+const sequence = stack.getSequence();
+const toolbar = stack.getToolbar();
+```
+
+---
+
+### See Also
+
+- [`omdEquationSequenceNode`](./omdEquationSequenceNode.md)
+- [`omdStepVisualizer`](./omdStepVisualizer.md)
+- [`omdToolbar`](./omdToolbar.md)
+- [`jsvgGroup`](../../jsvg/jsvg.js)