@teachinglab/omd 0.1.0

package/docs/api/simplificationEngine.md

@@ -0,0 +1,98 @@
+# SimplificationEngine
+
+The `SimplificationEngine` is a static class that provides a collection of helper methods for creating, matching, and transforming expression nodes. It forms the backbone of the simplification rule system.
+
+## Overview
+
+The engine is not instantiated. Instead, its static methods are used directly by the simplification rules to perform their logic. The methods can be grouped into several categories:
+
+- **Node Creation:** Helpers to build new `omdNode` instances (e.g., `createConstant`, `createBinaryOp`).
+- **Pattern Matching:** Helpers to check if a node matches a specific structure or value (e.g., `isBinaryOp`, `isConstantValue`).
+- **Monomial Helpers:** Specialized functions for working with monomials (terms like `2x^2`), which are essential for rules like combining like terms.
+- **Rule Definition:** The `SimplificationRule` inner class, which defines the structure for all simplification rules.
+
+## Node Creation Helpers
+
+These methods simplify the process of creating new nodes, often by abstracting away the underlying AST structure.
+
+#### `createConstant(value, fontSize)`
+- Creates an `omdConstantNode`.
+
+#### `createBinaryOp(left, operator, right, ...)`
+- Creates an `omdBinaryExpressionNode` for operations like 'add', 'subtract', etc.
+
+#### `createMultiplication(leftConstantNode, rightNode, ...)`
+- A specialized version of `createBinaryOp` for multiplication.
+
+#### `createRational(numerator, denominator, fontSize)`
+- Creates an `omdRationalNode` (a fraction).
+
+#### `createMonomial(coefficient, variable, power, ...)`
+- Constructs a complete monomial term (e.g., `2x^3`) from its constituent parts.
+
+## Pattern Matching Helpers
+
+These methods are used within the `match` function of a simplification rule to determine if the rule applies to a given node.
+
+#### `isType(node, typeName)`
+- Checks if a node is an instance of a specific class (e.g., `'omdConstantNode'`).
+
+#### `isBinaryOp(node, operator)`
+- Checks if a node is a binary operation, optionally matching a specific operator (e.g., `'add'`).
+
+#### `isConstantValue(node, value)`
+- Checks if a node is a constant, optionally matching a specific value.
+
+#### `hasConstantOperand(node)`
+- For a binary operation, checks if one of its operands is a constant and returns both the constant and the other operand.
+
+#### `unwrapParentheses(node)`
+- If the given node is an `omdParenthesisNode`, it returns the inner expression; otherwise, it returns the node itself.
+
+## Monomial and Like Terms Helpers
+
+#### `isMonomial(node)`
+- A powerful helper that checks if a node represents a monomial (e.g., `x`, `2x`, `-5x^2`).
+- **Returns:** An object with `{ coefficient, variable, power, ... }` if it is a monomial, otherwise `null`.
+
+#### `areLikeTerms(monomial1, monomial2)`
+- Compares the output of two `isMonomial` calls to see if they have the same variable and power.
+
+## `SimplificationRule` Class
+
+This is an inner class of `SimplificationEngine` that provides the blueprint for all simplification rules.
+
+### Constructor
+
+`new SimplificationRule(name, matchFn, transformFn, messageFn, type)`
+
+- `name` {string}: The name of the rule (e.g., "Combine Constants").
+- `matchFn` {function}: A function that takes a node and returns `true` or a data object if the rule applies, `false` otherwise.
+- `transformFn` {function}: A function that takes the matched node and the data from `matchFn` and returns a new, transformed node.
+- `messageFn` {function} (optional): A function to generate a user-friendly description of the change.
+
+### Key Methods
+
+- `canApply(node)`: Executes the `matchFn`.
+- `apply(node, ruleData, currentRoot)`: Executes the `transformFn` and handles replacing the old node with the new one in the expression tree.
+
+## Rule Factory Functions
+
+These are static methods on `SimplificationEngine` that create common types of rules.
+
+#### `createRule(...)`
+- The base factory function for creating a `SimplificationRule` instance.
+
+#### `createConstantFoldRule(name, operator)`
+- Creates a rule that evaluates binary operations on two constants (e.g., `2 + 3` -> `5`).
+
+#### `createIdentityRule(name, operator, identityValue, side)`
+- Creates a rule for identity operations (e.g., `x + 0` -> `x` or `y * 1` -> `y`).
+
+#### `createZeroMultiplicationRule()`
+- Creates the rule for `x * 0` -> `0`.
+
+### See Also
+
+- [`omdSimplification`](./omdSimplification.md): The top-level module that uses the engine.
+- [`simplificationRules`](./simplificationRules.md): The module where specific rules are defined using the engine's helpers.

package/docs/api/simplificationRules.md

@@ -0,0 +1,77 @@
+# Simplification Rules
+
+This module defines the specific simplification rules used by the `SimplificationEngine`. The rules are organized into an object, keyed by the `omdNode` type they apply to.
+
+## Rule Structure
+
+Each rule is an instance of `SimplificationEngine.SimplificationRule` and has three main parts:
+
+1.  **`match` function:** Determines if the rule can be applied to a given node.
+2.  **`transform` function:** Executes the simplification and returns a new, transformed node.
+3.  **`message` function:** Generates a human-readable description of the transformation.
+
+## Available Rules
+
+The `rules` object contains arrays of rules for each of the following node types:
+
+### `binary` (for `omdBinaryExpressionNode`)
+
+- **Same Term Cancellation:** `a - a` simplifies to `0`.
+- **Opposite Term Cancellation:** `a + (-a)` simplifies to `0`.
+- **Cancel Constants in Sums:** `x + 2 - 2` simplifies to `x + 0`.
+- **Constant Folding:** Evaluates operations on constants (e.g., `2 + 3` -> `5`). Includes rules for `add`, `subtract`, `multiply`, and `divide`.
+- **Identity Operations:** Simplifies operations with identity elements (e.g., `x + 0` -> `x`, `y * 1` -> `y`).
+- **Zero Multiplication:** `x * 0` simplifies to `0`.
+- **Combine Coefficients:** `2 * 3x` simplifies to `6x`.
+- **Distributive Property:** `2 * (x + 3)` expands to `2x + 6`.
+- **Expand Polynomial Multiplication:** `(x + 2)(x + 3)` expands to `x^2 + 5x + 6`.
+- **Multiply Monomials:** `2x * 3x` simplifies to `6x^2`.
+- **Combine Like Factors:** `x * x` simplifies to `x^2`.
+- **Combine Multiple Constants in Sums:** `x + 2 + 3` simplifies to `x + 5`.
+- **Combine Like Terms:** `2x + 3x` simplifies to `5x`.
+
+### `rational` (for `omdRationalNode`)
+
+- **Variable Self Division:** `x / x` simplifies to `1`.
+- **Power Base Division:** `x^n / x` simplifies to `x^(n-1)`.
+- **Monomial Variable Division:** `cx / x` simplifies to `c`.
+- **Simplify Fraction:** Reduces constant fractions to their simplest form (e.g., `6/8` -> `3/4`).
+- **Simplify Multiplication in Rational:** `(4x)/3` restructures to `(4/3) * x`.
+- **Simplify Rational Division:** `(4x + 6) / 2` distributes the division to `2x + 3`.
+
+### `parenthesis` (for `omdParenthesisNode`)
+
+- **Remove Redundant Parentheses:** `((x))` simplifies to `(x)`.
+
+### `unary` (for `omdUnaryExpressionNode`)
+
+- **Simplify Double Negation:** `-(-x)` simplifies to `x`.
+- **Remove Unary Plus:** `+x` simplifies to `x`.
+
+### `power` (for `omdPowerNode`)
+
+- **Calculate Powers:** Evaluates constant powers (e.g., `2^3` -> `8`).
+- **Power of Zero:** `x^0` simplifies to `1`.
+- **Power of One:** `x^1` simplifies to `x`.
+- **Expand Polynomial Power:** `(x - 2)^2` expands to `x^2 - 4x + 4`.
+- **Square of Square Root:** `(sqrt(x))^2` simplifies to `x`.
+- **Fractional Exponent to Square Root:** `x^(1/2)` converts to `sqrt(x)`.
+
+### `sqrt` (for `omdSqrtNode`)
+
+- **Simplify Square Root of Constant:** `sqrt(9)` simplifies to `3`.
+- **Square Root of Square:** `sqrt(x^2)` simplifies to `x` (assuming `x >= 0`).
+
+### `function` (for `omdFunctionNode`)
+
+- **Function Inverse Simplification:** `sin(arcsin(x))` simplifies to `x`.
+- **Function to Sqrt Node:** Converts `sqrt(x)` from a function representation to the dedicated `omdSqrtNode`.
+
+## Rule Lookup
+
+The `getRulesForNode(node)` function is used by the simplification engine to retrieve the appropriate list of rules for a given node based on its type.
+
+### See Also
+
+- [`omdSimplification`](./omdSimplification.md): The top-level module that uses these rules.
+- [`SimplificationEngine`](./simplificationEngine.md): The engine that provides the helpers to create and apply these rules.

package/docs/api/simplificationUtils.md

@@ -0,0 +1,64 @@
+# Simplification Utilities
+
+This module provides a collection of helper functions that are used throughout the simplification engine and rules. These utilities handle common tasks like creating nodes, manipulating expression trees, and formatting output.
+
+## Core Functions
+
+#### `gcd(a, b)`
+- Calculates the greatest common divisor of two numbers.
+
+#### `createConstantNode(value, fontSize)`
+- Creates a new, fully initialized `omdConstantNode`.
+
+#### `createRationalNode(numerator, denominator, fontSize)`
+- Creates a new, fully initialized `omdRationalNode`, handling negative numerators and cases where the denominator is 1.
+
+#### `nodeToString(node)`
+- A robust function that converts any `omdNode` into a human-readable string, handling different node types and formatting them correctly.
+
+## Expression Tree Manipulation
+
+#### `flattenSum(node, terms)`
+- A key utility that takes a nested tree of additions and subtractions (e.g., `a - (b + c)`) and flattens it into a linear list of terms, each with an associated sign.
+- **Parameters:**
+  - `node`: The root of the expression to flatten.
+  - `terms`: An array that will be populated with the term objects (`{ node, sign }`).
+
+#### `buildSumTree(terms, fontSize)`
+- The counterpart to `flattenSum`. It takes a list of terms (like the one produced by `flattenSum`) and reconstructs a valid, balanced `omdBinaryExpressionNode` tree from them.
+
+#### `_replaceNodeInTree(oldNode, newNode, currentRoot)`
+- An internal helper that safely replaces a node within the larger expression tree, handling parent-child connections and ensuring the tree remains valid.
+
+## Polynomial and Monomial Helpers
+
+#### `expandPolynomialPower(terms, exponent, fontSize)`
+- Expands a polynomial raised to a power (e.g., `(a+b)^2`). It uses more specific helpers for common cases.
+
+#### `expandBinomialSquare(terms, fontSize)`
+- Expands `(a+b+...)^2`.
+
+#### `expandBinomialCube(terms, fontSize)`
+- Expands `(a+b)^3`.
+
+#### `expandBinomialFourth(terms, fontSize)`
+- Expands `(a+b)^4`.
+
+#### `multiplyTermArrays(terms1, terms2, fontSize)`
+- Performs polynomial multiplication by multiplying each term from the first array by each term from the second.
+
+## Provenance Helpers
+
+#### `extractLeafNodes(node)`
+- Traverses an expression and returns an array of all its leaf nodes (constants and variables). This is used for detailed provenance tracking.
+
+#### `extractMonomialProvenance(termNode)`
+- A specialized function that separates the leaf nodes of a monomial into `coefficientNodes` and `variableNodes` for highly granular highlighting.
+
+#### `createMonomialWithGranularProvenance(...)`
+- Creates a monomial while assigning separate provenance chains to its coefficient and variable parts.
+
+### See Also
+
+- [`omdSimplification`](./omdSimplification.md)
+- [`simplificationRules`](./simplificationRules.md)

package/docs/api/transcribe.md

@@ -0,0 +1,43 @@
+# Netlify Function: transcribe
+
+This Netlify serverless function provides a backend for the `omdTranscriptionService`. It receives an image, sends it to the Gemini API for transcription, and returns the result.
+
+## Endpoint
+
+`/.netlify/functions/transcribe`
+
+## Method
+
+`POST`
+
+## Request Body
+
+The request body should be a JSON object with the following properties:
+
+*   **imageBase64** (`string`, required): The base64 encoded image data (without the `data:image/png;base64,` prefix).
+*   **prompt** (`string`, optional): A custom prompt to guide the transcription. If not provided, a default prompt for mathematical expressions is used.
+
+## Responses
+
+### Success Response (200 OK)
+
+A successful response will be a JSON object with the following properties:
+
+*   **text** (`string`): The transcribed text.
+*   **provider** (`string`): The transcription provider used (always `'gemini'`).
+*   **confidence** (`number`): The confidence score of the transcription (currently hardcoded to `1.0`).
+
+### Error Responses
+
+*   **400 Bad Request**: This error is returned if the `imageBase64` property is missing from the request body.
+*   **500 Internal Server Error**: This error is returned if there is an issue with the transcription process on the server, such as an error from the Gemini API.
+
+## Environment Variables
+
+This function requires the following environment variable to be set in your Netlify environment:
+
+*   `GEMINI_API_KEY`: Your API key for the Gemini service.
+
+## CORS
+
+The function is configured to allow cross-origin requests from any origin.

package/docs/api-reference.md

@@ -0,0 +1,85 @@
+# OMD Library API Reference
+
+> This is the complete API reference for the OMD (On-screen Math Display) library. Use the table of contents below to navigate to the detailed documentation for each module and class.
+
+---
+
+## Table of Contents
+
+The API is organized into the following categories for clarity:
+
+| Category                | Description                                                                       |
+| ----------------------- | --------------------------------------------------------------------------------- |
+| **[Core Components](#core-components)**    | The main entry points for rendering and managing expressions.                     |
+| **[Node Types](#node-types)**              | The building blocks of all mathematical expressions.                              |
+| **[UI Components](#ui-components)**        | Interactive components for user interfaces.                                       |
+| **[Helper Utilities](#helper-utilities)**  | Utility functions for common tasks like node creation and visualization.          |
+| **[Configuration](#configuration)**        | Modules for managing the library's settings and behavior.                         |
+| **[Simplification](#simplification)**      | The expression simplification engine and its components.                          |
+
+---
+
+
+### Core Components
+
+The foundational classes for interacting with the OMD library.
+
+- **[`omdNode`](./api/omdNode.md)**: The abstract base class for all mathematical nodes in the expression tree.
+- **[`omdDisplay`](./api/omdDisplay.md)**: A component for rendering a single, auto-centered mathematical expression.
+- **[`omdEquationStack`](./api/omdEquationStack.md)**: A component for managing and displaying a sequence of equation steps.
+
+### Node Types
+
+These classes represent the different parts of a mathematical expression.
+
+- **[`omdConstantNode`](./api/omdConstantNode.md)**: Represents numeric constants (e.g., `5`, `3.14`).
+- **[`omdVariableNode`](./api/omdVariableNode.md)**: Represents variables (e.g., `x`, `y`).
+- **[`omdBinaryExpressionNode`](./api/omdBinaryExpressionNode.md)**: Represents binary operations (`+`, `-`, `*`, `/`).
+- **[`omdUnaryExpressionNode`](./api/omdUnaryExpressionNode.md)**: Represents unary operations (e.g., negation `-x`).
+- **[`omdPowerNode`](./api/omdPowerNode.md)**: Represents exponentiation (`x^2`).
+- **[`omdSqrtNode`](./api/omdSqrtNode.md)**: Represents square roots (`√x`).
+- **[`omdRationalNode`](./api/omdRationalNode.md)**: Represents fractions and rational numbers (`x/y`).
+- **[`omdEquationNode`](./api/omdEquationNode.md)**: Represents equations with a left and right side.
+- **[`omdFunctionNode`](./api/omdFunctionNode.md)**: Represents mathematical functions (e.g., `sin(x)`).
+- **[`omdParenthesisNode`](./api/omdParenthesisNode.md)**: Represents expressions enclosed in parentheses.
+- **[`omdEquationSequenceNode`](./api/omdEquationSequenceNode.md)**: A container for displaying step-by-step solutions.
+- **[`omdOperationDisplayNode`](./api/omdOperationDisplayNode.md)**: Represents visual operation hints.
+- **[`omdGroupNode`](./api/omdGroupNode.md)**: A container for grouping related nodes.
+
+### UI Components
+
+Interactive components for building math interfaces.
+
+- **[`omdToolbar`](./api/omdToolbar.md)**: A customizable toolbar for mathematical operations.
+- **[`omdStepVisualizer`](./api/omdStepVisualizer.md)**: Component for visualizing step-by-step solutions.
+- **[`omdStepVisualizerHighlighting`](./api/omdStepVisualizerHighlighting.md)**: Manages highlighting of nodes in step visualizations.
+- **[`omdStepVisualizerLayout`](./api/omdStepVisualizerLayout.md)**: Handles layout and positioning of step visualizer elements.
+- **[`omdStepVisualizerTextBoxes`](./api/omdStepVisualizerTextBoxes.md)**: Manages interactive text boxes for step explanations.
+- **[`omdStepVisualizerInteractiveSteps`](./api/omdStepVisualizerInteractiveSteps.md)**: Creates interactive step elements for explanations.
+
+### Helper Utilities
+
+- **[`omdHelpers`](./api/omdHelpers.md)**: Utility functions for node creation.
+- **[`omdUtilities`](./api/omdUtilities.md)**: General utilities for AST mapping and text bounds.
+- **[`omdStepVisualizerNodeUtils`](./api/omdStepVisualizerNodeUtils.md)**: Utilities for node operations in step visualizations.
+- **[`omdTreeDiff`](./api/omdTreeDiff.md)**: Utilities for comparing expression trees.
+
+### Configuration
+
+- **[`omdConfigManager`](./api/omdConfigManager.md)**: The main object for managing library configuration.
+- **[`Configuration Options`](./api/configuration-options.md)**: A detailed list of all available configuration settings.
+
+### Simplification
+
+- **[`omdSimplification`](./api/omdSimplification.md)**: The main simplification module.
+- **[`omdSimplificationEngine`](./api/simplificationEngine.md)**: Core simplification engine.
+- **[`Simplification Rules`](./api/simplificationRules.md)**: Available simplification rules.
+- **[`Simplification Utilities`](./api/simplificationUtils.md)**: Helper functions for simplification rules.
+
+
+---
+
+
+## See Also
+- **[User Guide](user-guide.md)**: Getting started, usage, and tutorials (in progress)
+- **[Examples](../examples/)**: A directory of live, interactive examples.