@teachinglab/omd 0.5.7 → 0.5.8

package/npm-docs/api/omdTranscriptionService.md

@@ -0,0 +1,96 @@
+# omdTranscriptionService
+
+The `omdTranscriptionService` class provides an interface to an AI-powered transcription service for handwritten content. It sends image data to a server-side endpoint for processing, abstracting away the complexities of AI model interaction and API key management.
+
+## Class Definition
+
+```javascript
+export class omdTranscriptionService
+```
+
+## Constructor
+
+### `new omdTranscriptionService([options])`
+
+Creates a new `omdTranscriptionService` instance.
+
+-   **`options`** (`object`, optional): Configuration options for the service:
+    -   `endpoint` (`string`): The server endpoint for the transcription service. Defaults to `'/.netlify/functions/transcribe'`.
+    -   `defaultProvider` (`string`): The default transcription provider to use. Defaults to `'gemini'`.
+
+## Public Properties
+
+-   **`options`** (`object`): The configuration options for the service, including `endpoint` and `defaultProvider`.
+
+## Public Methods
+
+### `async transcribe(imageBlob, [options])`
+
+Transcribes an image containing handwritten content by sending it to the configured server endpoint. The image is converted to base64 before transmission.
+
+-   **`imageBlob`** (`Blob`): The image blob to transcribe.
+-   **`options`** (`object`, optional): Transcription options:
+    -   `prompt` (`string`): A custom prompt for the transcription service. If not provided, a default mathematical transcription prompt is used.
+-   **Returns**: `Promise<object>` - A promise that resolves with the transcription result, containing the `text`, `provider`, and `confidence`.
+-   **Throws**: `Error` if the API call fails.
+
+### `async transcribeWithFallback(imageBlob, [options])`
+
+Transcribes an image with a fallback mechanism. Currently, this method simply calls `transcribe()`, but it is designed to allow for future implementations of fallback transcription providers or strategies.
+
+-   **`imageBlob`** (`Blob`): The image blob to transcribe.
+-   **`options`** (`object`, optional): Transcription options.
+-   **Returns**: `Promise<object>` - A promise that resolves with the transcription result.
+
+### `isAvailable()`
+
+Checks if the transcription service is available. In the current implementation, this always returns `true` as it relies on a serverless function endpoint.
+
+-   **Returns**: `boolean` - `true` if the service is available, `false` otherwise.
+
+### `getAvailableProviders()`
+
+Gets the list of available transcription providers. In the current implementation, this always returns `['gemini']` as the server handles the actual provider selection.
+
+-   **Returns**: `Array<string>` - An array of available provider names.
+
+### `isProviderAvailable(provider)`
+
+Checks if a specific transcription provider is available. In the current implementation, this only returns `true` for the `'gemini'` provider.
+
+-   **`provider`** (`string`): The name of the provider to check.
+-   **Returns**: `boolean` - `true` if the provider is available, `false` otherwise.
+
+## Internal Methods
+
+-   **`_getDefaultEndpoint()`**: Returns the default server endpoint URL for the transcription service (`'/.netlify/functions/transcribe'`).
+-   **`_blobToBase64(blob)`**: Converts an `imageBlob` into a base64 encoded string, suitable for sending in a JSON payload.
+
+## Example Usage
+
+```javascript
+import { omdTranscriptionService } from '@teachinglab/omd';
+
+// Create a transcription service instance
+const transcriptionService = new omdTranscriptionService();
+
+// Assume getMyImageBlob() is a function that returns an image Blob
+async function getMyImageBlob() {
+    // Example: Create a dummy canvas and get its blob
+    const canvas = document.createElement('canvas');
+    canvas.width = 100; canvas.height = 50;
+    const ctx = canvas.getContext('2d');
+    ctx.fillText('2x + 3', 10, 30);
+    return new Promise(resolve => canvas.toBlob(resolve, 'image/png'));
+}
+
+// Get an image blob from a canvas or file input
+const imageBlob = await getMyImageBlob();
+
+// Transcribe the image
+const result = await transcriptionService.transcribe(imageBlob, {
+    prompt: 'Transcribe the handwritten math equation. Return only the mathematical expression.'
+});
+
+console.log(result.text); // The transcribed text (e.g., "2x + 3")
+```

package/npm-docs/api/omdTreeDiff.md

@@ -0,0 +1,170 @@
+# omdTreeDiff
+
+Implements a robust tree differencing algorithm to identify changes between two `omdNode` expression trees. This module is crucial for `omdStepVisualizerHighlighting`, providing precise visual feedback on how mathematical expressions transform from one step to the next.
+
+## Algorithm Overview
+
+`omdTreeDiff` uses a multi-stage approach to compare two expression trees (`oldEquation` and `newEquation`):
+
+1.  **Special Cases**: It first attempts to identify common pedagogical patterns (like adding/subtracting the same value from both sides, or simple identity/double negative simplifications). If found, these specific changes are highlighted directly.
+2.  **Optimal Subtree Matching**: If no special cases apply, it proceeds to find the largest, non-overlapping set of matched subtrees between the old and new expressions. A match can be either structurally identical or semantically equivalent (e.g., `2+3` and `5`).
+3.  **Identify Changes**: Any parts of the `newEquation` that are *not* part of these optimal matches are considered the actual changes and are returned for highlighting.
+4.  **Educational Mode**: When enabled, the algorithm includes additional heuristics to highlight subtle simplifications that might not involve a direct structural change but are important for understanding the transformation (e.g., removing `+ 0`).
+
+## Class Definition
+
+```javascript
+export class omdTreeDiff
+```
+
+This class is not meant to be instantiated. All its methods are static.
+
+## Static Methods
+
+### `findChangedNodes(oldEquation, newEquation, options)`
+
+Main entry point for the tree differencing algorithm. Compares two `omdEquationNode` instances (or any `omdNode` subtrees) and returns a list of nodes in the `newEquation` that have changed or are new.
+
+-   **`oldEquation`** (`omdNode`): The root node of the previous expression tree.
+-   **`newEquation`** (`omdNode`): The root node of the current expression tree.
+-   **`options`** (`object`, optional): Configuration options:
+    -   `educationalMode` (`boolean`): If `true`, the diff algorithm will also highlight mathematically neutral changes that are pedagogically significant (e.g., removing `+ 0`). Default: `false`.
+-   **Returns**: `Array<omdNode>` - An array of `omdNode` instances from `newEquation` that should be highlighted.
+
+### `findEquationSpecialCases(oldEquation, newEquation)`
+
+Identifies specific equation-level transformation patterns, such as adding/subtracting the same operation to both sides of an equation. This allows for more intuitive highlighting in common step-by-step solution scenarios.
+
+-   **`oldEquation`** (`omdEquationNode`): The previous equation.
+-   **`newEquation`** (`omdEquationNode`): The current equation.
+-   **Returns**: `Array<omdNode>` - An array of nodes to highlight for these special cases, or an empty array if no such pattern is found.
+
+### `diffSubtrees(oldTree, newTree, educationalMode)`
+
+Core recursive differencing method. It first checks for various pedagogical highlighting patterns (common prefix, variable preservation, type differences, subtraction patterns). If none apply, it falls back to finding an optimal matching between subtrees of the `oldTree` and `newTree`. Nodes in `newTree` that do not have a match in `oldTree` are considered changed.
+
+-   **`oldTree`** (`omdNode`): The root of the old subtree.
+-   **`newTree`** (`omdNode`): The root of the new subtree.
+-   **`educationalMode`** (`boolean`): Same as in `findChangedNodes`.
+-   **Returns**: `Array<omdNode>` - An array of unmatched leaf nodes in `newTree`.
+
+### `findEducationalHighlights(oldTree, newTree, optimalMatches)`
+
+When `educationalMode` is enabled, this method identifies additional nodes to highlight for pedagogical reasons, even if they don't represent a structural change. This includes cases like the removal of additive/multiplicative identities or double negations.
+
+-   **`oldTree`** (`omdNode`): The old expression tree.
+-   **`newTree`** (`omdNode`): The new expression tree.
+-   **`optimalMatches`** (`Array`): The list of optimally matched subtrees.
+-   **Returns**: `Array<omdNode>` - Additional nodes to highlight.
+
+### `findAdditiveIdentityChanges(oldTree, newTree)`
+
+Identifies changes related to the removal of additive identities (e.g., `+ 0` or `- 0`).
+
+-   **`oldTree`** (`omdNode`): The old expression tree.
+-   **`newTree`** (`omdNode`): The new expression tree.
+-   **Returns**: `Array<omdNode>` - Nodes to highlight for additive identity changes.
+
+### `findMultiplicativeIdentityChanges(oldTree, newTree)`
+
+Identifies changes related to the removal of multiplicative identities (e.g., `* 1` or `/ 1`).
+
+-   **`oldTree`** (`omdNode`): The old expression tree.
+-   **`newTree`** (`omdNode`): The new expression tree.
+-   **Returns**: `Array<omdNode>` - Nodes to highlight for multiplicative identity changes.
+
+### `findDoubleNegativeChanges(oldTree, newTree)`
+
+Identifies changes related to the simplification of double negatives (e.g., `--x` to `x`).
+
+-   **`oldTree`** (`omdNode`): The old expression tree.
+-   **`newTree`** (`omdNode`): The new expression tree.
+-   **Returns**: `Array<omdNode>` - Nodes to highlight for double negative removal.
+
+### `findCommonPrefixHighlights(oldTree, newTree)`
+
+Identifies highlighting patterns based on common prefixes between the string representations of the old and new trees. For example, if `"2x + 4"` becomes `"2x + 4 - 4"`, it highlights only the `"- 4"` part.
+
+-   **`oldTree`** (`omdNode`): The old expression tree.
+-   **`newTree`** (`omdNode`): The new expression tree.
+-   **Returns**: `Array<omdNode>` - Nodes to highlight for common prefix patterns.
+
+### `findVariablePreservationHighlights(oldTree, newTree)`
+
+Identifies highlighting patterns where a variable term remains the same but associated constants change. For example, `"2x + 4"` becoming `"2x + 2"` should highlight only the changed constant.
+
+-   **`oldTree`** (`omdNode`): The old expression tree.
+-   **`newTree`** (`omdNode`): The new expression tree.
+-   **Returns**: `Array<omdNode>` - Nodes to highlight for variable preservation patterns.
+
+### `findTypeDifferenceHighlights(oldTree, newTree)`
+
+Identifies highlighting patterns where the type of an expression changes significantly (e.g., a constant becoming a binary expression). In such cases, it highlights the new expression.
+
+-   **`oldTree`** (`omdNode`): The old expression tree.
+-   **`newTree`** (`omdNode`): The new expression tree.
+-   **Returns**: `Array<omdNode>` - Nodes to highlight for type difference patterns.
+
+### `findSubtractionPatternHighlights(oldTree, newTree)`
+
+Identifies highlighting patterns specific to subtraction, where the old tree matches the left side of a new subtraction. For example, `"x + 2"` becoming `"x + 2 - 2"` should highlight only the `"- 2"` part.
+
+-   **`oldTree`** (`omdNode`): The old expression tree.
+-   **`newTree`** (`omdNode`): The new expression tree.
+-   **Returns**: `Array<omdNode>` - Nodes to highlight for subtraction patterns.
+
+### `findAllSubtreeMatches(oldTree, newTree)`
+
+Generates all possible subtree matches between two expression trees. A match is determined by structural or string equivalence.
+
+-   **`oldTree`** (`omdNode`): The old expression tree.
+-   **`newTree`** (`omdNode`): The new expression tree.
+-   **Returns**: `Array<object>` - An array of match objects, each containing `oldNode`, `newNode`, `size`, `score`, and `type` of match.
+
+### `selectOptimalMatching(matches)`
+
+Given a list of all possible subtree matches, this method selects the optimal, non-overlapping set of matches. It uses a greedy approach, prioritizing larger and higher-scoring matches.
+
+-   **`matches`** (`Array<object>`): The array of potential matches from `findAllSubtreeMatches`.
+-   **Returns**: `Array<object>` - The selected optimal matches.
+
+### `findUnmatchedLeafNodes(newTree, matches)`
+
+Identifies all leaf nodes in the `newTree` that are not covered by any of the `optimalMatches`. These are the nodes that represent the actual changes.
+
+-   **`newTree`** (`omdNode`): The new expression tree.
+-   **`matches`** (`Array<object>`): The array of selected optimal matches.
+-   **Returns**: `Array<omdNode>` - An array of unmatched leaf nodes.
+
+### `findUnmatchedOldNodes(oldTree, matches)`
+
+Finds leaf nodes in the `oldTree` that are not covered by any match. These represent nodes that were removed or transformed.
+
+-   **`oldTree`** (`omdNode`): The old expression tree.
+-   **`matches`** (`Array<object>`): The array of selected optimal matches.
+-   **Returns**: `Array<omdNode>` - An array of unmatched leaf nodes from the old tree.
+
+## Internal Helper Methods
+
+-   **`_findCommonPrefix(str1, str2)`**: Finds the longest common string prefix between two strings.
+-   **`getAllSubtrees(root)`**: Recursively collects all subtrees from a given root node.
+-   **`calculateSimilarity(tree1, tree2)`**: Determines the similarity score between two subtrees, considering structural and string equivalence.
+-   **`treesStructurallyEqual(tree1, tree2)`**: Checks for exact structural equality between two subtrees.
+-   **`getSubtreeSize(root)`**: Calculates the number of nodes in a subtree.
+-   **`hasNodeOverlap(node, usedNodes)`**: Checks if a node or any of its descendants overlap with a set of already used nodes.
+-   **`markSubtreeAsUsed(root, usedNodes)`**: Marks all nodes in a subtree as used by adding them to a `Set`.
+-   **`debugPrintTree(node, depth)`**: A utility function for debugging that prints the structure of an `omdNode` tree to the console.
+
+## How it Works
+
+See the Algorithm Overview above for a summary of the process. The class is designed for internal use by step visualizer components.
+
+### Example
+
+This class is typically used internally by `omdStepVisualizerHighlighting`:
+
+```javascript
+// Example of internal usage within omdStepVisualizerHighlighting:
+// const changedNodes = omdTreeDiff.findChangedNodes(previousEquation, currentEquation, { educationalMode: true });
+// changedNodes.forEach(node => node.setExplainHighlight(true));
+```

package/npm-docs/api/omdUnaryExpressionNode.md

@@ -0,0 +1,137 @@
+# omdUnaryExpressionNode
+
+Represents unary operations (like negation) in mathematical expressions (e.g., `-x`, `-(a + b)`). This node handles rendering, layout, evaluation, and conversion to math.js AST for expressions with a single operand.
+
+## Class Definition
+
+```javascript
+export class omdUnaryExpressionNode extends omdNode
+```
+
+## Constructor
+
+### `new omdUnaryExpressionNode(ast)`
+
+Creates a new `omdUnaryExpressionNode` instance.
+
+-   **`ast`** (`object`): The math.js AST node for the unary operation. It must contain:
+    -   `args`: An array with exactly one operand AST node.
+    -   `op`: The operator symbol (e.g., `'-'`, `'+'`).
+    -   `fn`: The operation name (e.g., `'unaryMinus'`, `'unaryPlus'`).
+
+During construction, it creates an `omdOperatorNode` for the unary operator and an `omdNode` for the operand. It throws an error if the AST does not have exactly one argument.
+
+## Static Methods
+
+### `fromString(expressionString)`
+
+Creates an `omdUnaryExpressionNode` from a string representation of a unary expression. Requires `window.math` (math.js) to be available globally for parsing.
+
+-   **`expressionString`** (`string`): The unary expression as a string (e.g., `"-x"`, `"-(a+b)"`).
+-   **Returns**: `omdUnaryExpressionNode` - 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 unary minus operation.
+
+## Public Properties
+
+-   **`op`** (`omdOperatorNode`): The `omdOperatorNode` representing the unary operator (e.g., `-`).
+-   **`operand`** (`omdNode`): The `omdNode` representing the expression being operated on.
+-   **`operation`** (`string`): The name of the operation (e.g., `'unaryMinus'`).
+
+## Public Methods
+
+### `computeDimensions()`
+
+Calculates the dimensions of the unary expression node. It sums the widths of the operator and the operand to get the total width. The height is the maximum of the operator's and operand's heights. No extra spacing is added between the unary operator and its operand.
+
+-   **Overrides**: `omdNode.computeDimensions()`.
+
+### `updateLayout()`
+
+Updates the layout of the unary expression node. It positions the operator to the left and the operand to its right, both vertically centered within the node's total height.
+
+-   **Overrides**: `omdNode.updateLayout()`.
+
+### `clone()`
+
+Creates a deep, structural clone of the unary expression node, including its `op` and `operand` nodes. The cloned node's `provenance` array is updated to include the original node's ID.
+
+-   **Returns**: `omdUnaryExpressionNode` - A new, identical instance of the unary expression node.
+
+### `toMathJSNode()`
+
+Converts the `omdUnaryExpressionNode` back into its math.js AST representation. It creates an `OperatorNode` with the unary operator and the converted operand AST.
+
+-   **Returns**: `object` - A math.js `OperatorNode` for the unary operation. The returned object also includes a `clone` method for compatibility.
+
+### `toString()`
+
+Converts the unary expression node to its string representation. It adds parentheses around the operand if `needsParentheses()` returns `true` (e.g., for binary expressions).
+
+-   **Returns**: `string` - Format: `"-operand"` or `"-(operand)"`.
+
+### `needsParentheses()`
+
+Checks if the operand needs to be wrapped in parentheses when converted to a string. This is typically `true` if the operand is a binary expression, to maintain correct order of operations.
+
+-   **Returns**: `boolean` - `true` if parentheses are required around the operand.
+
+### `evaluate(variables)`
+
+Evaluates the unary expression. It evaluates the `operand` and then applies the unary operation (e.g., negation for `'-'`).
+
+-   **`variables`** (`object`): A map of variable names to their numeric values.
+-   **Returns**: `number` - The result of the unary operation, or `NaN` if the operand cannot be evaluated to a number.
+
+## Internal Methods
+
+-   **`createOperatorNode(ast)`**: Creates an `omdOperatorNode` for the unary operator from its AST, setting its parent to this node.
+-   **`createExpressionNode(ast)`**: Creates an `omdNode` instance for the operand from its AST, setting its parent to this node.
+
+## Example
+
+```javascript
+import { omdUnaryExpressionNode } from '@teachinglab/omd';
+import * as math from 'mathjs';
+
+// Create from AST: -x
+const node = new omdUnaryExpressionNode({
+  type: 'OperatorNode',
+  op: '-',
+  fn: 'unaryMinus',
+  args: [
+    { type: 'SymbolNode', name: 'x' }
+  ]
+});
+
+// Create from AST: -(x + 1)
+const complex = new omdUnaryExpressionNode({
+  type: 'OperatorNode',
+  op: '-',
+  fn: 'unaryMinus',
+  args: [{
+    type: 'OperatorNode',
+    op: '+',
+    fn: 'add',
+    args: [
+      { type: 'SymbolNode', name: 'x' },
+      { type: 'ConstantNode', value: 1 }
+    ]
+  }]
+});
+
+// Render and layout
+node.setFontSize(24);
+node.initialize();
+
+// Add to an SVG container to display
+// const svgContainer = new jsvgContainer();
+// svgContainer.addChild(node);
+// document.body.appendChild(svgContainer.svgObject);
+```
+
+## See Also
+
+-   [`omdNode`](./omdNode.md) - Parent class.
+-   [`omdOperatorNode`](./omdOperatorNode.md) - For the operator symbol.
+-   [`omdBinaryExpressionNode`](./omdBinaryExpressionNode.md) - Often used for complex operands within a unary expression.
+-   [`omdConstantNode`](./omdConstantNode.md) - For numeric operands.

package/npm-docs/api/omdUtilities.md

@@ -0,0 +1,83 @@
+# omdUtilities
+
+This module provides a collection of utility functions primarily used for mapping math.js AST nodes to OMD node classes, determining rendering behavior, and calculating text dimensions. These functions are internal helpers that support the core OMD node system.
+
+## Functions
+
+### `astToOmdType(type, ast)`
+
+Maps a math.js AST node type to its corresponding OMD node class. This function is crucial for dynamically creating the correct `omdNode` subclass based on the parsed expression.
+
+-   **`type`** (`string`): The `type` property of the AST node (e.g., `"OperatorNode"`, `"ParenthesisNode"`).
+-   **`ast`** (`object`): The full AST node object, which may contain additional context (e.g., `op` for `OperatorNode`, `fn` for `FunctionNode`).
+-   **Returns**: `class` - The appropriate `omdNode` class constructor.
+
+**Detailed Logic:**
+
+-   **`AssignmentNode`**: Returns `omdEquationNode`.
+-   **`OperatorNode`**: 
+    -   If `op` is `'-'` and `args.length` is `1` (unary minus), returns `omdUnaryExpressionNode`.
+    -   If `op` is `'='`, returns `omdEquationNode`.
+    -   If `op` is `'^'`, returns `omdPowerNode`.
+    -   If `op` is `'/'`, returns `omdRationalNode`.
+    -   Otherwise (binary operator), returns `omdBinaryExpressionNode`.
+-   **`ParenthesisNode`**: Returns `omdParenthesisNode`.
+-   **`ConstantNode`**: Returns `omdConstantNode`.
+-   **`SymbolNode`**: Returns `omdVariableNode`.
+-   **`FunctionNode`**: 
+    -   If `fn.name` or `name` is `'multiply'` and `ast.implicit` is `true` (implicit multiplication), returns `omdBinaryExpressionNode`.
+    -   If `fn.name` or `name` is `'sqrt'`, returns `omdSqrtNode`.
+    -   Otherwise, returns `omdFunctionNode`.
+-   **Default**: Returns `omdNode`.
+
+### `getNodeForAST(ast)`
+
+A wrapper function that takes a complete math.js AST node and returns the corresponding OMD node class. It uses `astToOmdType` internally, handling cases where the AST might have a `mathjs` property indicating its type.
+
+-   **`ast`** (`object`): The math.js AST node.
+-   **Returns**: `class` - The appropriate `omdNode` class constructor.
+
+### `getTextBounds(text, fontSize)`
+
+Calculates the rendered width and height of a given text string at a specific font size. This is achieved by creating a temporary, hidden `<span>` element in the DOM, applying the text and styling, measuring its dimensions, and then removing it.
+
+-   **`text`** (`string`): The text content to measure.
+-   **`fontSize`** (`number`): The font size in pixels.
+-   **Returns**: `object` - An object with `width` and `height` properties.
+
+### `shouldUseFractionNotation(ast)`
+
+Determines whether a division operation (represented by an AST node) should be rendered as a fraction (stacked numerator over denominator) or as a linear division (e.g., `a / b`). This decision is based on the complexity of the numerator and denominator.
+
+-   **`ast`** (`object`): The AST node representing a division operation.
+-   **Returns**: `boolean` - `true` if the division should be rendered as a fraction, `false` otherwise.
+
+### `isComplexExpression(ast)`
+
+Checks if an AST node represents a "complex" expression, typically one that contains multiple operations or nested structures. This function is used by `shouldUseFractionNotation` to decide on the appropriate rendering style for fractions.
+
+-   **`ast`** (`object`): The AST node to check.
+-   **Returns**: `boolean` - `true` if the expression is considered complex, `false` otherwise.
+
+## Example
+
+```javascript
+import { getNodeForAST, getTextBounds } from '@teachinglab/omd'; // Assuming @teachinglab/omd exports these
+import * as math from 'mathjs';
+
+// Example of getting a node class for an expression
+const astExpression = math.parse('x + 2');
+const NodeClassExpression = getNodeForAST(astExpression);
+const nodeExpression = new NodeClassExpression(astExpression);
+console.log(nodeExpression.type); // e.g., "omdBinaryExpressionNode"
+
+// Example of getting a node class for an equation
+const astEquation = math.parse('y = 2x');
+const NodeClassEquation = getNodeForAST(astEquation);
+const nodeEquation = new NodeClassEquation(astEquation);
+console.log(nodeEquation.type); // "omdEquationNode"
+
+// Example of getting text bounds
+const bounds = getTextBounds('Hello World', 24);
+console.log(`Text width: ${bounds.width}, height: ${bounds.height}`);
+```

package/npm-docs/api/omdVariableNode.md

@@ -0,0 +1,123 @@
+# omdVariableNode
+
+Represents a variable (like `x`, `y`, `a`, `b`) in mathematical expressions. This node handles the visual representation of variables, their evaluation, and conversion to math.js AST.
+
+## Class Definition
+
+```javascript
+export class omdVariableNode extends omdLeafNode
+```
+
+## Constructor
+
+### `new omdVariableNode(nodeData)`
+
+Creates a new `omdVariableNode` instance.
+
+-   **`nodeData`** (`object` | `string`): The AST node data (from math.js, typically a `SymbolNode` with a `name` property) or the variable name as a string (e.g., `"x"`). The constructor extracts the variable `name` and creates the `textElement` for display.
+
+## Static Methods
+
+### `fromName(name)`
+
+Creates a variable node directly from a given name string. This is a convenience method for creating simple variable nodes without needing to construct a full AST object.
+
+-   **`name`** (`string`): The variable name (e.g., `"x"`, `"theta"`).
+-   **Returns**: `omdVariableNode` - A new instance of `omdVariableNode`.
+
+## Public Properties
+
+-   **`name`** (`string`): The name of the variable (e.g., `'x'`, `'y'`, `'theta'`).
+-   **`type`** (`string`): Always `"omdVariableNode"`.
+-   **`textElement`** (`jsvgTextLine`): The internal `jsvgTextLine` instance that displays the variable name.
+
+## Public Methods
+
+### `computeDimensions()`
+
+Calculates the dimensions of the node based on its text content, adding a small amount of padding around the variable name to improve visual spacing.
+
+-   **Overrides**: `omdLeafNode.computeDimensions()`.
+
+### `updateLayout()`
+
+Updates the layout of the node. This method primarily calls the superclass's `updateLayout`.
+
+-   **Overrides**: `omdLeafNode.updateLayout()`.
+
+### `toMathJSNode()`
+
+Converts the `omdVariableNode` to a math.js-compatible AST format. It creates a `SymbolNode` with the variable's `name`, `id`, and `provenance`.
+
+-   **Returns**: `object` - A math.js-compatible AST node with `type: "SymbolNode"` and `name` set to the variable name. The returned object also includes `id`, `provenance`, and a `clone` method for compatibility.
+
+### `highlight(color)`
+
+Applies a highlight to the node's background and sets the variable's text color to white for better contrast. This method respects the `isExplainHighlighted` lock.
+
+-   **`color`** (`string`): The color of the highlight.
+
+### `clearProvenanceHighlights()`
+
+Clears any provenance-related highlights from the node and resets the variable's text color to its default (black).
+
+### `toString()`
+
+Converts the variable node to its string representation, which is simply its `name`.
+
+-   **Returns**: `string` - The variable name.
+
+### `evaluate(variables)`
+
+Evaluates the variable by looking up its value in the provided `variables` map. If the variable is not defined in the map, it throws an error.
+
+-   **`variables`** (`object`): A map of variable names to their numeric values.
+-   **Returns**: `number` - The value of the variable.
+-   **Throws**: `Error` if the variable is not defined in the map.
+
+## Internal Methods
+
+-   **`parseName(nodeData)`**: Extracts the variable name from the constructor's `nodeData`. It handles both string input and AST objects with a `name` property.
+-   **`parseType()`**: Sets the node's type. Always returns `"variable"`.
+
+## Examples
+
+#### Creating Variables
+
+```javascript
+import { omdVariableNode } from '@teachinglab/omd';
+import * as math from 'mathjs';
+
+// From a name string
+const nodeX = omdVariableNode.fromName('x');
+const nodeTheta = omdVariableNode.fromName('θ');
+
+// From AST data (e.g., from math.js parse result)
+const astNode = math.parse('y');
+const nodeY = new omdVariableNode(astNode);
+
+// Direct string name (less common, but supported)
+const nodeZ = new omdVariableNode('z');
+```
+
+#### Rendering Variables
+
+```javascript
+import { omdVariableNode } from '@teachinglab/omd';
+// import { jsvgContainer } from '@teachinglab/jsvg'; // if rendering directly
+
+const node = omdVariableNode.fromName('x');
+node.setFontSize(24);
+node.initialize(); // Computes dimensions and layout
+
+// To render, typically add to a parent node or an omdDisplay
+// const svgContainer = new jsvgContainer();
+// svgContainer.addChild(node);
+// document.body.appendChild(svgContainer.svgObject);
+```
+
+## See Also
+
+-   [`omdLeafNode`](./omdLeafNode.md) - Parent class.
+-   [`omdNode`](./omdNode.md) - Base class.
+-   [`omdConstantNode`](./omdConstantNode.md) - For numeric values.