@teachinglab/omd 0.5.7 → 0.6.0

package/npm-docs/README.md

@@ -0,0 +1,251 @@
+# OMD (Open Math Display)
+
+> A JavaScript library for creating interactive mathematical interfaces in web applications
+
+[![npm version](https://img.shields.io/npm/v/@teachinglab/omd.svg)](https://www.npmjs.com/package/@teachinglab/omd)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+OMD is a comprehensive JavaScript library for building rich, interactive mathematical experiences in the browser. From simple equation displays to complex step-by-step solution systems with full visual feedback and user interaction.
+
+![OMD Demo](https://i.imgur.com/CdtEi33.png)
+
+## Quick Start
+
+### Installation
+
+```bash
+npm install @teachinglab/omd
+```
+
+### Basic Usage
+
+```javascript
+import { omdDisplay } from '@teachinglab/omd';
+
+// Create a math display
+const container = document.getElementById('math-container');
+const display = new omdDisplay(container);
+
+// Render an equation
+display.render('2x + 3 = 11');
+```
+
+## Documentation
+
+### Getting Started
+- **[Installation & Setup](./guides/getting-started.md)** - Get up and running with OMD
+- **[Quick Examples](./guides/quick-examples.md)** - Common use cases and code snippets
+- **[Factory Functions](./guides/factory-functions.md)** - Creating objects from JSON (AI-friendly)
+
+### Core Concepts
+
+#### 1. Global Context & Configuration
+Learn about the foundational systems that power OMD:
+
+- **[Configuration Manager](./api/omdConfigManager.md)** - Library-wide settings and theming
+- **[Configuration Options](./api/configuration-options.md)** - Complete list of available settings
+- **[Display System](./api/omdDisplay.md)** - Main rendering engine
+- **[Canvas System](./api/omdCanvas.md)** - Multi-expression layout manager
+- **[Event Manager](./api/eventManager.md)** - Event handling and coordination
+- **[Helpers & Utilities](./api/omdHelpers.md)** - Utility functions for common tasks
+
+#### 2. Visualizations
+Interactive visual components for teaching and learning:
+
+##### Number & Ratio Visualizations
+- **[Number Line](./guides/visualizations.md#number-line)** - `omdNumberLine` - Interactive number lines with dots and labels
+- **[Number Tiles](./guides/visualizations.md#number-tiles)** - `omdNumberTile` - Visual counting tiles with dots
+- **[Tape Diagrams](./guides/visualizations.md#tape-diagrams)** - `omdTapeDiagram` - Part-whole relationship diagrams
+- **[Ratio Charts](./guides/visualizations.md#ratio-charts)** - `omdRatioChart` - Pie and bar chart ratio visualizations
+- **[Balance Hanger](./guides/visualizations.md#balance-hanger)** - `omdBalanceHanger` - Balance scale visualizations
+
+##### Graphing & Geometry
+- **[Coordinate Plane](./guides/visualizations.md#coordinate-plane)** - `omdCoordinatePlane` - 2D graphing with functions and shapes
+- **[Shapes](./guides/visualizations.md#shapes)** - `omdShapes` - Geometric shapes (circles, rectangles, polygons, triangles)
+- **[Spinner](./guides/visualizations.md#spinner)** - `omdSpinner` - Interactive circular spinners
+
+##### Data Display
+- **[Tables](./guides/visualizations.md#tables)** - `omdTable` - Data tables with customizable styling
+- **[Function Graphs](./guides/visualizations.md#function-graphs)** - Plotting mathematical functions
+
+#### 3. Equations & Expressions
+The heart of mathematical notation and manipulation:
+
+##### Core Expression Components
+- **[Expression Nodes](./api/expression-nodes.md)** - Understanding the node tree structure and omdEquationNode class
+- **[omdEquationNode](./api/omdEquationNode.md)** - Complete equations with manipulation methods (e.g., `2x + 3 = 11`)
+- **[omdExpression](./guides/equations.md#expressions)** - Mathematical expressions (e.g., `3x² + 5`)
+- **[omdTerm](./guides/equations.md#terms)** - Individual terms (e.g., `3x²`)
+- **[omdNumber](./guides/equations.md#numbers)** - Numeric constants
+- **[omdVariable](./guides/equations.md#variables)** - Variables (e.g., `x`, `y`)
+- **[omdOperator](./guides/equations.md#operators)** - Mathematical operators (+, -, ×, ÷)
+
+##### Advanced Expression Types
+- **[omdPowerExpression](./guides/equations.md#power-expressions)** - Exponentiation (e.g., `(x+1)²`)
+- **[omdRationalExpression](./guides/equations.md#rational-expressions)** - Fractions (e.g., `(x+1)/(x-1)`)
+- **[omdFunction](./guides/equations.md#functions)** - Mathematical functions (e.g., `f(x) = 2x + 1`)
+- **[omdTileEquation](./guides/equations.md#tile-equations)** - Visual tile-based equations
+
+##### Step-by-Step Solutions
+- **[Equation Stack](./api/omdEquationStack.md)** - Sequenced solution steps
+- **[Step Visualizer](./api/omdStepVisualizer.md)** - Interactive step visualization
+- **[Simplification Engine](./api/omdSimplification.md)** - Rule-based expression simplification
+- **[Simplification Rules](./api/simplificationRules.md)** - Available transformation rules
+
+### Complete API Reference
+- **[Full API Documentation](./api/api-reference.md)** - Complete reference for all components
+- **[JSON Schemas](./json-schemas.md)** - Detailed JSON structure for all components
+
+## Features
+
+### **Interactive Math Rendering**
+- High-quality SVG-based mathematical notation
+- Real-time expression manipulation and visualization
+- Automatic layout and alignment for complex equations
+
+### **Step-by-Step Solutions**
+- Visual step tracking with detailed explanations
+- Simplification engine with rule-based transformations
+- Provenance tracking for highlighting related elements
+
+### **Rich UI Components**
+- Built-in toolbar for common mathematical operations
+- Drag & drop interface for intuitive manipulation
+- Customizable canvas for multi-expression layouts
+
+### **Educational Features**
+- Interactive learning experiences
+- Progressive step revelation
+- Visual operation feedback and highlighting
+
+## Guides
+
+### By Use Case
+- **[Creating Equations](./guides/equations.md)** - Work with equations and expressions
+- **[Visualizations Guide](./guides/visualizations.md)** - All visualization components
+- **[Step-by-Step Solutions](./guides/step-by-step.md)** - Building interactive solutions
+- **[Interactive Features](./guides/interactive-features.md)** - Drag & drop, toolbars, and more
+
+### Advanced Topics
+- **[Expression Tree Structure](./guides/expression-tree.md)** - Understanding the AST
+- **[Custom Simplification Rules](./guides/custom-rules.md)** - Extending the simplification engine
+- **[Theming & Styling](./guides/theming.md)** - Customizing appearance
+- **[Performance Optimization](./guides/performance.md)** - Best practices for large applications
+
+## Architecture
+
+```
+OMD Library Structure
+├── Core Systems
+│   ├── Configuration Manager (Global settings)
+│   ├── Display System (Rendering engine)
+│   └── Event Manager (Coordination)
+│
+├── Visualizations
+│   ├── Number Visualizations (Number line, tiles, tape diagrams)
+│   ├── Graphing (Coordinate plane, functions)
+│   └── Data Display (Tables, charts)
+│
+└── Equations & Expressions
+    ├── Node System (Expression tree)
+    ├── Equation Components (Equations, terms, operators)
+    ├── Advanced Expressions (Powers, rationals, functions)
+    └── Step-by-Step System (Simplification, visualization)
+```
+
+## Examples
+
+### Creating Objects from JSON (Factory Method)
+
+```javascript
+import { createFromJSON } from '@teachinglab/omd';
+
+// AI-generated or dynamic JSON data
+const jsonData = {
+    omdType: 'numberLine',
+    min: 0,
+    max: 10,
+    dotValues: [2, 5, 8]
+};
+
+// Create the object - no switch statement needed!
+const numberLine = createFromJSON(jsonData);
+```
+
+### Basic Equation
+```javascript
+import { omdDisplay, omdEquationNode } from '@teachinglab/omd';
+
+const display = new omdDisplay(document.getElementById('container'));
+const equation = omdEquationNode.fromString('2x + 3 = 11');
+display.render(equation);
+```
+
+### Step-by-Step Solution
+```javascript
+import { omdEquationStack } from '@teachinglab/omd';
+
+const steps = [
+    '2x + 3 = 11',
+    '2x = 8',
+    'x = 4'
+];
+
+const stack = new omdEquationStack(steps.map(s => 
+    omdEquationNode.fromString(s)
+), {
+    toolbar: true,
+    stepVisualizer: true
+});
+
+display.render(stack);
+```
+
+### Coordinate Plane with Function
+```javascript
+import { omdCoordinatePlane } from '@teachinglab/omd';
+
+const plane = new omdCoordinatePlane();
+plane.loadFromJSON({
+    xMin: -10, xMax: 10,
+    yMin: -10, yMax: 10,
+    graphEquations: [
+        { equation: 'y = x^2 - 4', color: '#e11d48', strokeWidth: 2 }
+    ]
+});
+
+display.render(plane);
+```
+
+### Number Line Visualization
+```javascript
+import { omdNumberLine } from '@teachinglab/omd';
+
+const numberLine = new omdNumberLine();
+numberLine.loadFromJSON({
+    min: 0,
+    max: 10,
+    dotValues: [2, 5, 8],
+    label: 'Number Line Example'
+});
+
+display.render(numberLine);
+```
+
+## Dependencies
+
+- **JSVG** (`@teachinglab/jsvg`) - High-performance SVG rendering
+- **math.js** - Mathematical expression parsing
+- **Modern Browser** - ES6 modules, SVG support required
+
+## License
+
+MIT License - see [LICENSE](../LICENSE) for details
+
+## Contributing
+
+We welcome contributions! See our [contributing guidelines](../CONTRIBUTING.md) for more information.
+
+---
+
+**Ready to get started?** Check out the [Getting Started Guide](./guides/getting-started.md) or explore the [JSON Schemas](./json-schemas.md) for detailed component configurations.

package/npm-docs/api/api-reference.md

@@ -0,0 +1,85 @@
+# OMD Library API Reference
+
+> This is the complete API reference for the OMD (Open 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.

package/npm-docs/api/configuration-options.md

@@ -0,0 +1,198 @@
+# Configuration Options
+
+This document details all available configuration options for the OMD library, managed by the `omdConfigManager` module. These options allow you to customize various aspects of the library's behavior, appearance, and mathematical preferences.
+
+## Overview
+
+The OMD configuration is a single JavaScript object that can be loaded from a JSON file or set programmatically. It is organized into logical categories.
+
+## Default Configuration Structure
+
+If no custom configuration is provided, the library uses the following default structure:
+
+```json
+{
+    "multiplication": {
+        "symbol": "·",
+        "forceImplicit": false,
+        "implicitCombinations": {
+            "constantVariable": true,
+            "variableConstant": false,
+            "parenthesisAfterVariable": true,
+            "parenthesisAfterConstant": true,
+            "variableParenthesis": true,
+            "parenthesisParenthesis": true,
+            "parenthesisVariable": true,
+            "parenthesisConstant": true,
+            "variableVariable": true
+        }
+    },
+    "stepVisualizer": {
+        "dotSizes": {
+            "level0": 8,
+            "level1": 6,
+            "level2": 4
+        },
+        "fontWeights": {
+            "level0": 400,
+            "level1": 400,
+            "level2": 400
+        }
+    }
+}
+```
+
+## Configuration Categories and Options
+
+### `multiplication`
+
+Settings related to how multiplication is displayed and handled.
+
+-   **`symbol`** {string}
+    -   The character used to represent multiplication. Default: `"·"` (middle dot).
+    -   Example: `"*"` or `"×"`.
+
+-   **`forceImplicit`** {boolean}
+    -   If `true`, implicit multiplication (e.g., `2x` instead of `2 * x`) is always used where mathematically valid, overriding `implicitCombinations`.
+    -   Default: `false`.
+
+-   **`implicitCombinations`** {Object}
+    -   An object defining specific scenarios where implicit multiplication should be used. Each property is a boolean.
+    -   **`constantVariable`** {boolean}: `2x` (Default: `true`)
+    -   **`variableConstant`** {boolean}: `x2` (Default: `false`)
+    -   **`parenthesisAfterVariable`** {boolean}: `x(y+z)` (Default: `true`)
+    -   **`parenthesisAfterConstant`** {boolean}: `2(x+y)` (Default: `true`)
+    -   **`variableParenthesis`** {boolean}: `(x+y)z` (Default: `true`)
+    -   **`parenthesisParenthesis`** {boolean}: `(x+y)(a+b)` (Default: `true`)
+    -   **`parenthesisVariable`** {boolean}: `(x+y)z` (Default: `true`)
+    -   **`parenthesisConstant`** {boolean}: `(x+y)2` (Default: `true`)
+    -   **`variableVariable`** {boolean}: `xy` (Default: `true`)
+
+### `stepVisualizer`
+
+Settings specific to the `omdStepVisualizer` component, controlling the appearance of step dots and text.
+
+-   **`dotSizes`** {Object}
+    -   Defines the radius of the step dots based on their importance level.
+    -   **`level0`** {number}: Radius for major steps. Default: `8`.
+    -   **`level1`** {number}: Radius for minor steps. Default: `6`.
+    -   **`level2`** {number}: Radius for detailed steps. Default: `4`.
+
+-   **`fontWeights`** {Object}
+    -   Defines the font weight for the equations based on their importance level.
+    -   **`level0`** {number}: Font weight for major steps. Default: `400`.
+    -   **`level1`** {number}: Font weight for minor steps. Default: `400`.
+    -   **`level2`** {number}: Font weight for detailed steps. Default: `400`.
+
+## Usage
+
+Configuration options can be set during initialization or updated at runtime using the `omdConfigManager` functions.
+
+### `initializeConfig(configSource)`
+
+Initializes the configuration by loading it from a file or object. This should be called early in the application lifecycle.
+
+-   **`configSource`** {string|Object} (optional) - The path to a JSON configuration file or a configuration object.
+
+```javascript
+import { initializeConfig } from '@teachinglab/omd';
+
+// Initialize with a custom config file
+await initializeConfig('./my-custom-omd-config.json');
+```
+
+### `setConfig(config)`
+
+Sets the configuration directly, bypassing file loading.
+
+-   **`config`** {Object} - A configuration object.
+
+```javascript
+import { setConfig } from '@teachinglab/omd';
+
+setConfig({
+    multiplication: {
+        symbol: '*'
+    }
+});
+```
+
+### `getDefaultConfig()`
+
+Returns a copy of the default configuration object.
+
+-   **Returns** {Object} - The default configuration.
+
+### `isEnabled(category, setting)`
+
+Checks if a specific feature is enabled in the configuration.
+
+-   **`category`** {string} - The configuration category (e.g., 'multiplication').
+-   **`setting`** {string} - The specific setting to check.
+-   **Returns** {boolean} - `true` if the setting is enabled, `false` otherwise.
+
+### `useImplicitMultiplication(combination)`
+
+Checks if implicit multiplication should be used for a specific combination of terms.
+
+-   **`combination`** {string} (optional) - The type of combination (e.g., 'constantVariable'). If not provided, it checks the `forceImplicit` setting.
+-   **Returns** {boolean} - `true` if implicit multiplication should be used.
+
+### `getMultiplicationSymbol()`
+
+Returns the configured multiplication symbol.
+
+-   **Returns** {string} - The multiplication symbol.
+
+### `updateConfig(category, setting, value)`
+
+Updates a configuration setting at runtime.
+
+-   **`category`** {string} - The configuration category.
+-   **`setting`** {string} - The setting to update.
+-   **`value`** {any} - The new value.
+
+### `getConfigValue(path)`
+
+Retrieves a configuration value using a dot-separated path.
+
+-   **`path`** {string} - The path to the value (e.g., 'multiplication.symbol').
+-   **Returns** {any} - The configuration value.
+
+### `setConfigValue(path, value)`
+
+Sets a configuration value using a dot-separated path.
+
+-   **`path`** {string} - The path to the value.
+-   **`value`** {any} - The new value.
+
+### `resetConfig()`
+
+Resets the configuration to its default state. Note: In the current implementation, this throws an error and advises to edit the `omdConfig.json` file directly.
+
+### `reloadConfig()`
+
+Reloads the configuration from the JSON file.
+
+-   **Returns** {Promise<Object>} - A promise that resolves to the reloaded configuration object.
+
+### `getConfigAsync()`
+
+Asynchronously retrieves the configuration object, loading it if necessary.
+
+-   **Returns** {Promise<Object>} - A promise that resolves to the configuration object.
+
+### `getDotRadius(level)`
+
+Gets the dot radius for a given step level in the step visualizer.
+
+-   **`level`** {number} (optional, default: 0) - The step level (0, 1, or 2).
+-   **Returns** {number} - The dot radius.
+
+### `getFontWeight(level)`
+
+Gets the font weight for a given step level in the step visualizer.
+
+-   **`level`** {number} (optional, default: 0) - The step level (0, 1, or 2).
+-   **Returns** {number} - The font weight.
+

package/npm-docs/api/eventManager.md

@@ -0,0 +1,83 @@
+# EventManager
+
+The `EventManager` class is the central hub for all user interactions with the OMD canvas. It is responsible for listening to raw browser events, normalizing them into a consistent format, and delegating them to the appropriate handlers, such as the active tool (`PencilTool`, `SelectTool`, etc.) or the `pointerEventHandler` for panning and zooming.
+
+## Class Definition
+
+```javascript
+export class EventManager {
+    // ...
+}
+```
+
+## Constructor
+
+### `new EventManager(canvas)`
+
+Creates a new `EventManager` instance.
+
+-   **`canvas`** (`OMDCanvas`): The main canvas instance to which this event manager is attached.
+
+## Public Methods
+
+### `initialize()`
+
+Binds all necessary event listeners to the canvas's SVG element and the document. This includes listeners for pointer events, keyboard events, and the mouse wheel. It also sets the `touch-action: none;` style on the SVG element to prevent default touch behaviors like scrolling.
+
+### `getPointerInfo()`
+
+Retrieves the current state of the pointers.
+
+-   **Returns**: `object` - An object containing:
+    -   `activePointers` {number}: The number of currently active pointers.
+    -   `isDrawing` {boolean}: Whether a drawing operation is in progress.
+    -   `multiTouch` {boolean}: Whether a multi-touch interaction is occurring.
+
+### `destroy()`
+
+Removes all event listeners and cleans up the event manager. This should be called when the canvas is no longer in use.
+
+## Event Handling Workflow
+
+The `EventManager` follows a clear workflow for handling events:
+
+1.  **Capture Raw Event**: Listens for native browser events (`pointerdown`, `keydown`, etc.).
+2.  **Prevent Default**: Calls `event.preventDefault()` for most events to stop the browser's default behavior (e.g., text selection, page scrolling).
+3.  **Normalize Event**: Converts the raw event object into a standardized format. For pointer events, this includes converting screen coordinates to SVG coordinates and normalizing pressure values (see `_normalizePointerEvent`).
+4.  **Delegate to Handlers**: Passes the normalized event to the relevant handlers:
+    -   **`pointerEventHandler`**: For core interactions like panning and zooming.
+    -   **Active Tool**: The currently selected tool (e.g., `PencilTool`) receives the event to perform its specific function (e.g., drawing a line).
+5.  **Emit Canvas Event**: Emits a high-level event on the canvas instance (e.g., `pointerDown`, `keyDown`) that other parts of the application can listen to.
+
+## Pointer Event Handler
+
+The `EventManager` uses an instance of `pointerEventHandler` to manage view transformations like panning and zooming, which are typically initiated with multi-touch gestures or mouse wheel interactions.
+
+## Private Methods (Internal Logic)
+
+The following methods handle the internal logic of the `EventManager`. While you won't call them directly, understanding their role can be helpful for debugging or extending the library.
+
+-   **`_onPointerDown(event)`**: Handles the start of a pointer interaction. It tracks the active pointer, sets pointer capture, and delegates to the appropriate handlers.
+-   **`_onPointerMove(event)`**: Handles pointer movement. It throttles events to maintain performance, updates the cursor position, and delegates to handlers if a drawing is in progress.
+-   **`_onPointerUp(event)`**: Handles the end of a pointer interaction. It cleans up the active pointer and notifies the active tool that the stroke has finished.
+-   **`_onPointerCancel(event)`**: Handles cases where a pointer interaction is unexpectedly terminated.
+-   **`_onPointerEnter(event)` / `_onPointerLeave(event)`**: Manages the visibility of the custom cursor as the pointer enters and leaves the canvas.
+-   **`_onKeyDown(event)` / `_onKeyUp(event)`**: Handles keyboard input, checking for global shortcuts (like switching tools) before delegating to the active tool.
+-   **`_onWheel(event)`**: Handles mouse wheel events, typically for zooming.
+-   **`_onContextMenu(event)`**: Prevents the browser's context menu from appearing over the canvas.
+-   **`_normalizePointerEvent(event, canvasCoords)`**: Converts a raw pointer event into a normalized object with consistent properties (e.g., `x`, `y`, `pressure`).
+-   **`_normalizePressure(pressure)`**: Clamps the pointer pressure value to a range between 0 and 1, providing a default value for devices without pressure sensitivity.
+
+## Emitted Events
+
+The `EventManager` emits the following events on the `OMDCanvas` instance, allowing other modules to react to user input:
+
+-   `pointerDown`
+-   `pointerMove`
+-   `pointerUp`
+-   `pointerCancel`
+-   `pointerEnter`
+-   `pointerLeave`
+-   `keyDown`
+-   `keyUp`
+-   `wheel`