@teachinglab/omd 0.1.4 → 0.1.6

package/docs/api/omdUtilities.md

@@ -1,70 +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.
-
-## 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.
-
-- **Parameters:**
-  - `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`).
-- **Returns:** {class} The appropriate `omdNode` class constructor.
-
----
-
-#### `getNodeForAST(ast)`
-
-A wrapper function that takes a complete math.js AST node and returns the corresponding OMD node class. It uses `astToOmdType` internally.
-
-- **Parameters:**
-  - `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 used for precise layout calculations.
-
-- **Parameters:**
-  - `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 is based on the complexity of the numerator and denominator.
-
-- **Parameters:**
-  - `ast` {Object} - The AST node representing a division operation.
-- **Returns:** {boolean} `true` if it should be 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 is used by `shouldUseFractionNotation` to decide on rendering style.
-
-- **Parameters:**
-  - `ast` {Object} - The AST node to check.
-- **Returns:** {boolean} `true` if the expression is considered complex, `false` otherwise.
-
-### Example
-
-```javascript
-import { getNodeForAST, getTextBounds } from './omd/omdUtilities.js';
-
-// Example of getting a node class
-const ast = math.parse('x + 2');
-const NodeClass = getNodeForAST(ast);
-const node = new NodeClass(ast);
-
-// Example of getting text bounds
-const bounds = getTextBounds('Hello World', 24);
-console.log(`Text width: ${bounds.width}, height: ${bounds.height}`);
-```
+# 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/docs/api/omdVariableNode.md

@@ -1,148 +1,123 @@
-# omdVariableNode
-
-Represents a variable (like x, y, a, b) in mathematical expressions.
-
-## Class: `omdVariableNode extends omdLeafNode`
-
-```javascript
-import { omdVariableNode } from './omd/nodes/omdVariableNode.js';
-```
-
-### Constructor
-
-```javascript
-new omdVariableNode(nodeData)
-```
-
-**Parameters:**
-- `nodeData` {Object|string} - The AST node data or variable name
-
-**Description:**
-Creates a node representing a variable. Usually created automatically when parsing expressions.
-
-### Properties
-
-Inherits all properties from [`omdLeafNode`](./omdLeafNode.md), plus:
-
-#### `name`
-- **Type:** string
-- **Description:** The variable name (e.g., 'x', 'y', 'theta')
-
-#### `type`
-- **Type:** string
-- **Description:** Always "variable"
-
-#### `textElement`
-- **Type:** SVGElement
-- **Description:** The SVG text element displaying the variable name
-
-### Methods
-
-Inherits all methods from [`omdLeafNode`](./omdLeafNode.md), plus:
-
-#### `parseName(nodeData)`
-Internal method to extract variable name from AST data.
-- **Returns:** string
-
----
-
-#### `parseType()`
-Internal method to set node type.
-- **Returns:** "variable"
-
----
-
-#### `computeDimensions()`
-Calculates dimensions with padding around the variable.
-Overrides base class method.
-
----
-
-#### `updateLayout()`
-Updates the layout of the node.
-Overrides base class method.
-
----
-
-#### `toMathJSNode()`
-Converts to math.js AST format.
-- **Returns:** Object - A math.js-compatible AST node with:
-  - `type`: "SymbolNode"
-  - `name`: The variable name
-  - `id`: Node ID
-  - `provenance`: Provenance array
-
----
-
-#### `highlight(color)`
-Highlights the node and sets text color to white.
-- `color` {omdColor} - The highlight color
-
----
-
-#### `clearProvenanceHighlights()`
-Clears highlights and resets text color.
-
----
-
-#### `toString()`
-Convert to string representation.
-- **Returns:** string - The variable name
-
----
-
-#### `evaluate(variables)`
-Evaluates the variable by looking up its value in a map.
-- `variables` {Object} - A map of variable names to their numeric values
-- **Returns:** number - The value of the variable
-- **Throws:** Error if variable is not defined in the map
-
----
-
-#### `simplify()`
-Attempt to simplify the variable.
-- **Returns:** Object
-  - `success`: false (variables cannot be simplified)
-  - `newRoot`: null
-  - `message`: "Cannot simplify a variable"
-
-### Static Methods
-
-#### `fromName(name)`
-Create a variable node from a name.
-- `name` {string} - The variable name
-- **Returns:** omdVariableNode
-
-### Examples
-
-#### Creating Variables
-
-```javascript
-// From a name
-const nodeX = omdVariableNode.fromName('x');
-const nodeTheta = omdVariableNode.fromName('θ');
-
-// From AST data
-const node = new omdVariableNode({
-  type: 'SymbolNode',
-  name: 'x'
-});
-
-// Direct string name
-const nodeY = new omdVariableNode('y');
-```
-
-#### Rendering Variables
-
-```javascript
-const node = omdVariableNode.fromName('x');
-node.setFontSize(24);
-node.computeDimensions(); // Calculate size with padding
-node.updateLayout(); // Position the text element
-```
-
-### See Also
-
-- [omdLeafNode](./omdLeafNode.md) - Parent class
-- [omdNode](./omdNode.md) - Base class
-- [omdConstantNode](./omdConstantNode.md) - For numeric values
+# 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.

package/index.js

@@ -5,10 +5,10 @@
  * It exports all core OMD components and visualization tools from a single endpoint.
  * 
  * Usage:
- * import { omdTable, omdBalanceHanger, omdEquationNode, omdDisplay } from 'omd-library'
+ * import { omdTable, omdBalanceHanger, omdEquationNode, omdDisplay } from '@teachinglab/omd'
  * 
  * Or for dynamic imports:
- * const { omdTable } = await import('omd-library')
+ * const { omdTable } = await import('@teachinglab/omd')
  */
 
 // Export everything from the core OMD library (equations, nodes, display, etc.)

package/omd/core/index.js

@@ -21,6 +21,7 @@ import { omdEquationStack } from './omdEquationStack.js';
 import { omdStepVisualizer } from '../step-visualizer/omdStepVisualizer.js';
 import { omdDisplay } from '../display/omdDisplay.js';
 import { omdToolbar } from '../display/omdToolbar.js';
+import { omdNodeOverlay, omdNodeOverlayPresets } from '../utils/omdNodeOverlay.js';
 
 // Utilities
 import { getNodeForAST } from './omdUtilities.js';
@@ -30,6 +31,7 @@ import {
     setConfig,
     getDefaultConfig
 } from '../config/omdConfigManager.js';
+import { aiNextEquationStep } from '../utils/aiNextEquationStep.js';
 
 // Expression handling
 import { omdExpression } from '../../src/omdExpression.js';
@@ -60,6 +62,8 @@ export {
     omdStepVisualizer,
     omdDisplay,
     omdToolbar,
+    omdNodeOverlay,
+    omdNodeOverlayPresets,
     
     // Utilities
     getNodeForAST,
@@ -69,6 +73,8 @@ export {
     getDefaultConfig,
     omdExpression,
     omdColor
+    ,
+    aiNextEquationStep
 };
 
 // Helper utilities for common operations
@@ -131,6 +137,8 @@ export default {
     omdStepVisualizer,
     omdDisplay,
     omdToolbar,
+    omdNodeOverlay,
+    omdNodeOverlayPresets,
     
     // Utilities
     getNodeForAST,
@@ -140,6 +148,7 @@ export default {
     getDefaultConfig,
     omdExpression,
     omdColor,
+    aiNextEquationStep,
     
     // Helper functions
     helpers: omdHelpers

package/omd/nodes/omdEquationSequenceNode.js

@@ -479,6 +479,21 @@ export class omdEquationSequenceNode extends omdNode {
         this.updateLayout();
     }
 
+    /**
+     * Convenience helper: recompute dimensions, update layout, and optionally render via a renderer.
+     * Use this instead of calling computeDimensions/updateLayout everywhere.
+     * @param {object} [renderer] - Optional renderer (e.g., an omdDisplay instance) to re-render the sequence
+     */
+    refresh(renderer, center=true) {
+        this.computeDimensions();
+        this.updateLayout();
+        renderer.render(this);
+
+        if (center) {
+            renderer.centerNode();
+        }
+    }
+
     /**
      * Applies a specified operation to the current equation in the sequence and adds the result as a new step.
      * @param {number|string} value - The constant value or expression string to apply.

package/omd/utils/aiNextEquationStep.js

@@ -0,0 +1,106 @@
+import OpenAI from 'openai';
+
+/**
+ * Ask the AI for the next algebraic step for an equation.
+ * This helper can be called in Node (server) with an API key, or can proxy to an endpoint.
+ *
+ * @param {string} equation - The equation string (e.g. "3x+2=14")
+ * @param {object} [options]
+ * @param {string} [options.apiKey] - API key for the OpenAI-compatible client (GEMINI_API_KEY)
+ * @param {string} [options.baseURL] - Optional baseURL override for the OpenAI client
+ * @param {string} [options.model] - Model name (default: "gemini-2.0-flash")
+ * @param {string} [options.endpoint] - If provided, POSTs to this endpoint with { equation } and expects the same JSON response
+ */
+export async function aiNextEquationStep(equation, options = {}) {
+    if (!equation) throw new Error('equation is required');
+
+    const prompt = `Given the equation ${equation}, return ONLY the next algebraic step required to solve for the variable, in one of the following strict JSON formats:
+
+For an operation (add, subtract, multiply, divide):
+{ "operation": "add|subtract|multiply|divide", "value": number or string }
+
+For a function applied to both sides (e.g., sqrt, log, sin):
+{ "function": "functionName" }
+
+If the equation is already solved (like x=4) or no valid algebraic step can be applied:
+{ "operation": "none" }
+
+Important rules for solving:
+1. When variables appear on both sides, first move all variables to one side by adding/subtracting variable terms
+2. When constants appear on both sides, move all constants to one side by adding/subtracting constants
+3. Focus on isolating the variable systematically
+4. For equations like 2x-5=3x+7, subtract the smaller variable term (2x) from both sides first
+
+Do not include any explanation, LaTeX, or extra text. Only output the JSON object.`;
+
+    // If an endpoint is provided, proxy the request there (useful for browser usage)
+    if (options.endpoint) {
+        const res = await fetch(options.endpoint, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json'
+            },
+            body: JSON.stringify({ equation })
+        });
+
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`Remote endpoint error: ${res.status} ${text}`);
+        }
+
+        const json = await res.json();
+        return json;
+    }
+
+    const apiKey = options.apiKey || (typeof process !== 'undefined' && process.env && process.env.GEMINI_API_KEY);
+    if (!apiKey) throw new Error('API key is required when not using a remote endpoint');
+
+    const baseURL = options.baseURL || 'https://generativelanguage.googleapis.com/v1beta/openai/';
+    const model = options.model || 'gemini-2.0-flash';
+
+    const client = new OpenAI({ apiKey, baseURL });
+
+    const messages = [
+        {
+            role: 'user',
+            content: [
+                {
+                    type: 'text',
+                    text: prompt
+                }
+            ]
+        }
+    ];
+
+    const response = await client.chat.completions.create({
+        model,
+        messages,
+        max_tokens: 150
+    });
+
+    // Extract JSON object from model output
+    let aiText = '';
+    try {
+        aiText = (response.choices && response.choices[0] && response.choices[0].message && response.choices[0].message.content) || '';
+        if (Array.isArray(aiText)) {
+            // Some SDKs return arrays of content objects
+            aiText = aiText.map(c => c.text || c.content || '').join('');
+        }
+        if (typeof aiText === 'object' && aiText.text) aiText = aiText.text;
+        aiText = String(aiText).trim();
+    } catch (e) {
+        throw new Error('Unexpected AI response format');
+    }
+
+    const jsonMatch = aiText.match(/\{[\s\S]*\}/);
+    if (!jsonMatch) throw new Error('AI did not return a JSON object');
+
+    try {
+        const parsed = JSON.parse(jsonMatch[0]);
+        return parsed;
+    } catch (e) {
+        throw new Error('Failed to parse AI JSON response: ' + e.message + ' -- raw: ' + aiText);
+    }
+}
+
+export default aiNextEquationStep;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teachinglab/omd",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "omd",
   "main": "./index.js",
   "module": "./index.js",

package/src/omdBalanceHanger.js

@@ -1,6 +1,6 @@
 
 import { omdColor } from "./omdColor.js";
-import { jsvgGroup, jsvgLine, jsvgEllipse, jsvgRect } from "@teachinglab/jsvg";
+import { jsvgGroup, jsvgLine, jsvgEllipse, jsvgRect, jsvgTextBox } from "@teachinglab/jsvg";
 
 export class omdBalanceHanger extends jsvgGroup
 {

package/src/omdCoordinatePlane.js

@@ -1,5 +1,5 @@
 import { omdColor } from "./omdColor.js";
-import { jsvgGroup, jsvgRect, jsvgClipMask, jsvgLine, jsvgEllipse, jsvgTextBox, jsvgPath } from "@teachinglab/jsvg";
+import { jsvgGroup, jsvgRect, jsvgClipMask, jsvgLine, jsvgEllipse, jsvgTextBox, jsvgTextLine, jsvgPath } from "@teachinglab/jsvg";
 import {
     omdRightTriangle,
     omdIsoscelesTriangle,