@teachinglab/omd 0.5.6 → 0.5.8

package/npm-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.

package/npm-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/npm-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/npm-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/npm-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.