@teachinglab/omd 0.1.0

package/docs/api/omdTranscriptionService.md

@@ -0,0 +1,76 @@
+# 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.
+
+## 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`, optional): The server endpoint for the transcription service. Defaults to `'/.netlify/functions/transcribe'`.
+    *   **defaultProvider** (`string`, optional): The default transcription provider to use. Defaults to `'gemini'`.
+
+## Public Methods
+
+### `transcribe(imageBlob, [options])`
+
+Transcribes an image containing handwritten content.
+
+*   **imageBlob** (`Blob`): The image blob to transcribe.
+*   **[options]** (`object`, optional): Transcription options.
+    *   **prompt** (`string`, optional): A custom prompt for the transcription service.
+*   **Returns**: `Promise<object>` - A promise that resolves with the transcription result, containing the `text`, `provider`, and `confidence`.
+
+### `transcribeWithFallback(imageBlob, [options])`
+
+Transcribes an image with a fallback mechanism (currently, this is the same as `transcribe`).
+
+*   **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.
+
+*   **Returns**: `boolean` - `true` if the service is available, `false` otherwise.
+
+### `getAvailableProviders()`
+
+Gets the available transcription providers.
+
+*   **Returns**: `Array<string>` - An array of available provider names.
+
+### `isProviderAvailable(provider)`
+
+Checks if a specific transcription provider is available.
+
+*   **provider** (`string`): The name of the provider to check.
+*   **Returns**: `boolean` - `true` if the provider is available, `false` otherwise.
+
+## Example Usage
+
+```javascript
+// Create a transcription service instance
+const transcriptionService = new omdTranscriptionService();
+
+// 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.'
+});
+
+console.log(result.text); // The transcribed text
+```

package/docs/api/omdTreeDiff.md

@@ -0,0 +1,134 @@
+
+# omdTreeDiff
+
+Implements a robust tree differencing algorithm to identify changes between two `omdNode` expression trees. Used by `omdStepVisualizerHighlighting` to provide visual feedback on how mathematical expressions transform from one step to the next.
+
+## Algorithm Overview
+
+`omdTreeDiff` uses a multi-stage approach:
+1. **Special Cases:** Attempts to identify common pedagogical patterns (like adding/subtracting the same value from both sides). If found, highlights those nodes.
+2. **Generate All Matches:** Finds all possible pairs of subtrees between the old and new expressions that are either structurally identical or semantically equivalent (e.g., `2+3` and `5`).
+3. **Select Optimal Set:** Selects the largest, non-overlapping set of matches, identifying the largest common sub-expressions between the two trees.
+4. **Identify Changes:** Any parts of the new tree that are *not* part of these optimal matches are considered changes and are returned for highlighting.
+5. **Educational Mode:** In educational mode, includes additional heuristics to highlight subtle simplifications that might not involve a direct structural change but are important for understanding the transformation.
+
+## Class: `omdTreeDiff`
+
+```javascript
+import { omdTreeDiff } from './omd/utils/omdTreeDiff.js';
+```
+
+
+## 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.
+
+- **Parameters:**
+  - `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 the same operation (e.g., `+ X` or `- X`) to both sides of an equation. Allows for more intuitive highlighting in common step-by-step solution scenarios.
+
+- **Parameters:**
+  - `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. Attempts to find an optimal matching between subtrees of the `oldTree` and `newTree`. Nodes in `newTree` that do not have a match in `oldTree` are considered changed.
+
+- **Parameters:**
+  - `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, identifies additional nodes to highlight for pedagogical reasons, even if they don't represent a structural change. Includes cases like the removal of additive/multiplicative identities or double negations.
+
+- **Parameters:**
+  - `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.
+
+---
+
+
+### `findAllSubtreeMatches(oldTree, newTree)`
+
+Generates all possible subtree matches between two expression trees. A match is determined by structural or string equivalence.
+
+- **Parameters:**
+  - `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, selects the optimal, non-overlapping set of matches. Uses a greedy approach, prioritizing larger and higher-scoring matches.
+
+- **Parameters:**
+  - `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.
+
+- **Parameters:**
+  - `newTree` {omdNode} - The new expression tree.
+  - `matches` {Array<Object>} - The array of selected optimal matches.
+- **Returns:** {Array<omdNode>} An array of unmatched leaf nodes.
+
+
+## Internal Helper Methods
+
+- `_findCommonPrefix(str1, str2)`: Finds the longest common string prefix.
+- `getAllSubtrees(root)`: Recursively collects all subtrees from a given root node.
+- `calculateSimilarity(tree1, tree2)`: Determines the similarity score between two subtrees.
+- `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 its descendants overlap with a set of used nodes.
+- `markSubtreeAsUsed(root, usedNodes)`: Marks all nodes in a subtree as used.
+- `findUnmatchedOldNodes(oldTree, matches)`: Finds leaf nodes in the old tree that were removed.
+
+
+## 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/docs/api/omdUnaryExpressionNode.md

@@ -0,0 +1,174 @@
+# omdUnaryExpressionNode
+
+Represents unary operations (like negation) in mathematical expressions (e.g., `-x`, `-(a + b)`). Handles rendering, layout, evaluation, and conversion to math.js AST.
+
+## Class: `omdUnaryExpressionNode extends omdNode`
+
+```javascript
+import { omdUnaryExpressionNode } from './omd/nodes/omdUnaryExpressionNode.js';
+```
+
+### Constructor
+
+```javascript
+new omdUnaryExpressionNode(ast)
+```
+
+**Parameters:**
+- `ast` {Object} - The AST node containing:
+  - `args`: Array with exactly 1 operand AST node
+  - `op`: Operator symbol (e.g., '-')
+  - `fn`: Operation name (e.g., 'unaryMinus')
+
+**Description:**
+Creates a node representing a unary operation (like negation) on an expression. Throws an error if the AST does not have exactly one argument.
+
+### Properties
+
+Inherits all properties from [omdNode](./omdNode.md), plus:
+
+#### `op`
+- **Type:** [omdOperatorNode](./omdOperatorNode.md)
+- **Description:** The unary operator node (e.g., '-')
+
+#### `operand`
+- **Type:** [omdNode](./omdNode.md)
+- **Description:** The expression being operated on
+
+#### `operation`
+- **Type:** string
+- **Description:** The operation name (e.g., 'unaryMinus')
+
+### Methods
+
+Inherits all methods from [omdNode](./omdNode.md), plus:
+
+#### `createOperatorNode(ast)`
+Internal method to create operator node.
+- `ast` {Object} - The AST with operator info
+- **Returns:** omdOperatorNode
+
+---
+
+#### `createExpressionNode(ast)`
+Internal method to create operand node.
+- `ast` {Object} - The AST for the operand
+- **Returns:** omdNode
+
+---
+
+#### `computeDimensions()`
+Calculates dimensions of expression.
+- Computes dimensions of operator and operand
+- Sets total width and height
+- No extra spacing for unary minus
+
+---
+
+#### `updateLayout()`
+Updates positions of elements.
+- Centers operator and operand vertically
+- Places operator before operand
+
+---
+
+#### `clone()`
+Creates a deep clone of the expression node, including operator and operand, and preserves provenance.
+- **Returns:** omdUnaryExpressionNode - New instance with:
+  - Cloned AST data
+  - Preserved background rectangle
+  - Cloned operator and operand
+  - Rebuilt argument list
+  - Original node's ID added to provenance array
+
+---
+
+#### `toMathJSNode()`
+Converts to math.js AST format.
+- **Returns:** Object - A math.js-compatible AST node with:
+  - `type`: "OperatorNode"
+  - `op`: Operator symbol
+  - `fn`: Operation name
+  - `args`: [operand AST]
+  - `id`: Node ID
+  - `provenance`: Provenance array
+
+---
+
+#### `toString()`
+Convert to string representation.
+- Adds parentheses if needed
+- **Returns:** string - Format: "-operand" or "-(operand)"
+
+---
+
+#### `needsParentheses()`
+Check if operand needs parentheses.
+- **Returns:** boolean - True if operand is binary expression
+
+---
+
+#### `evaluate(variables)`
+Evaluate the expression.
+- `variables` {Object} - Variable name to value mapping
+- **Returns:** number - Negated value for '-', same value for '+'
+- **Returns:** NaN if operand can't be evaluated
+
+---
+
+#### `simplify()`
+Attempt to simplify expression using the central simplification engine.
+- **Returns:** Object with:
+  - `success`: Whether simplified
+  - `newRoot`: Simplified expression
+  - `message`: Description of changes
+
+### Static Methods
+
+#### `fromString(expressionString)`
+Create node from string.
+- `expressionString` {string} - Expression with unary operation
+- **Returns:** omdUnaryExpressionNode
+- **Throws:** Error if not unary minus operation or if parsing fails
+
+### Example
+
+```javascript
+// Create from AST
+const node = new omdUnaryExpressionNode({
+  type: 'OperatorNode',
+  op: '-',
+  fn: 'unaryMinus',
+  args: [
+    { type: 'SymbolNode', name: 'x' }
+  ]
+});
+
+// Complex operand
+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 with proper spacing
+node.setFontSize(24);
+node.computeDimensions();
+node.updateLayout();
+```
+
+### See Also
+
+- [omdNode](./omdNode.md) - Parent class
+- [omdOperatorNode](./omdOperatorNode.md) - For operator symbol
+- [omdBinaryExpressionNode](./omdBinaryExpressionNode.md) - For complex operands
+- [omdConstantNode](./omdConstantNode.md) - For numeric operands

package/docs/api/omdUtilities.md

@@ -0,0 +1,70 @@
+# 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}`);
+```

package/docs/api/omdVariableNode.md

@@ -0,0 +1,148 @@
+# 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

package/docs/api/selectTool.md

@@ -0,0 +1,74 @@
+
+# SelectTool
+
+The `SelectTool` is a tool for selecting, moving, and deleting stroke segments on the canvas. It extends the `Tool` class.
+
+## Class Definition
+
+```javascript
+export class SelectTool extends Tool {
+    // ...
+}
+```
+
+## Constructor
+
+### `new SelectTool(canvas, [options])`
+
+Creates a new `SelectTool` instance.
+
+*   **canvas** (`OMDCanvas`): The canvas instance.
+*   **[options]** (`object`, optional): Configuration options for the tool.
+    *   **selectionColor** (`string`, optional): The color of the selection box. Defaults to `'#007bff'`.
+    *   **selectionOpacity** (`number`, optional): The opacity of the selection box. Defaults to `0.3`.
+
+## Public Methods
+
+### `onPointerDown(event)`
+
+Handles the pointer down event to start a selection.
+
+*   **event** (`PointerEvent`): The pointer event.
+
+### `onPointerMove(event)`
+
+Handles the pointer move event to update the selection box.
+
+*   **event** (`PointerEvent`): The pointer event.
+
+### `onPointerUp(event)`
+
+Handles the pointer up event to complete the selection.
+
+*   **event** (`PointerEvent`): The pointer event.
+
+### `onCancel()`
+
+Cancels the current selection operation.
+
+### `onKeyboardShortcut(key, event)`
+
+Handles keyboard shortcuts for selection-related actions.
+
+*   **key** (`string`): The key that was pressed.
+*   **event** (`KeyboardEvent`): The keyboard event.
+*   **Returns**: `boolean` - True if the shortcut was handled, false otherwise.
+
+### `getCursor()`
+
+Gets the cursor for the tool.
+
+*   **Returns**: `string` - The CSS cursor name.
+
+### `clearSelection()`
+
+Clears the current selection.
+
+## Properties
+
+*   **displayName** (`string`): The display name of the tool.
+*   **description** (`string`): A description of the tool.
+*   **icon** (`string`): The icon for the tool.
+*   **shortcut** (`string`): The keyboard shortcut for the tool.
+*   **category** (`string`): The category of the tool.
+*   **selectedSegments** (`Map<string, Set<number>>`): A map of selected segments, where the key is the stroke ID and the value is a set of segment indices.