From 91b6deaf7f80125c3515cfe9c9fad0f9d70fd949 Mon Sep 17 00:00:00 2001
From: Sanjay Bhangar <sanjay@developmentseed.org>
Date: Mon, 9 Feb 2026 17:01:15 +0530
Subject: [PATCH] add CLAUDE.md with overall structure and plan to migrate to
 ES modules

---
 CLAUDE.md                   | 185 ++++++++++++++++++++++++++++++++++++
 ES_MODULE_MIGRATION_PLAN.md | 119 +++++++++++++++++++++++
 2 files changed, 304 insertions(+)
 create mode 100644 CLAUDE.md
 create mode 100644 ES_MODULE_MIGRATION_PLAN.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000..aebeecd9
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,185 @@
+# OxJS Codebase Analysis
+
+## Overview
+OxJS is a JavaScript UI framework created around 2008, predating modern JavaScript build tools and module systems. It uses a custom build system and loading mechanism that was innovative for its time but needs modernization.
+
+## Current Architecture
+
+### 1. Module Structure
+The codebase is organized into distinct modules:
+- **Ox**: Core library with utilities (Array, String, Math, Type, etc.)
+- **UI**: User interface components and themes
+- **Geo**: Geographic utilities
+- **Image**: Image manipulation utilities
+- **Unicode**: Unicode utilities
+
+Each module follows the pattern:
+```
+source/
+├── ModuleName/
+│   ├── ModuleName.js  (module loader)
+│   ├── js/           (JavaScript files)
+│   └── json/         (locale and config files)
+```
+
+### 2. Custom Import/Loading System
+
+#### Core Loader (`source/Ox.js`)
+- The framework uses a custom `Ox.load()` function instead of ES modules
+- Loading process:
+  1. Detects script path from `<script>` tag
+  2. Loads `Ox/json/Ox.json` manifest file
+  3. Sequentially loads script groups in dependency order
+  4. Supports dev (individual files) and min (bundled) modes
+
+#### Module Loading Pattern
+```javascript
+// Usage in applications
+Ox.load('UI', function() {
+    // Module is loaded, can use Ox.UI
+});
+
+// Module definition pattern
+Ox.load.ModuleName = function(options, callback) {
+    // Module initialization code
+    callback(true); // success
+};
+```
+
+### 3. Build System (`tools/build/build.py`)
+
+The Python build script performs several tasks:
+
+#### Core Processing (`Ox` module)
+1. **Dependency ordering**: Files are loaded in specific groups to handle dependencies
+   - Group 1: `Core.js` (defines Ox object)
+   - Group 2: `Function.js`, `Polyfill.js`
+   - Group 3: `Array.js`, `String.js`, `Type.js`
+   - Group 4: `Collection.js`, `Math.js`
+   - Remaining files loaded alphabetically
+
+2. **Version injection**: Replaces `Ox.VERSION` placeholder
+3. **Locale aggregation**: Collects all locale files into `Ox.LOCALES`
+4. **Minification**: Uses `ox.js.minify()` to create compressed version
+
+#### UI Module Processing
+1. **Theme handling**:
+   - Reads theme data from `themes/*/json/theme.jsonc`
+   - Generates theme-specific CSS by replacing variables
+   - Creates theme-specific SVG files
+
+2. **Asset management**:
+   - SVG files are embedded as strings in `ui_images`
+   - PNG files are copied to build directories
+   - CSS imports are dynamically generated
+
+3. **File bundling**:
+   - All UI JavaScript files are concatenated into `UI/js/UI.js`
+   - Creates `UI/json/UI.json` manifest with file lists
+
+#### Output Structure
+Creates two build directories:
+- `dev/`: Development version with symlinks to source files
+- `min/`: Minified production version with concatenated files
+
+### 4. Key Patterns and Conventions
+
+#### No External Dependencies
+- jQuery is bundled but loaded separately
+- No npm packages or node_modules
+- All dependencies are included in source
+
+#### Global Namespace
+- Everything hangs off the global `Ox` object
+- No module-level scope isolation
+- Methods are attached directly to `Ox` or `Ox.ModuleName`
+
+#### Custom JSON with Comments (JSONC)
+- Uses `.jsonc` files that support comments
+- Custom parser in build process
+
+#### Dynamic Loading
+- Modules can be loaded on-demand
+- Supports conditional loading based on options
+- Locale files loaded lazily
+
+## Challenges for ES Module Migration
+
+### 1. Circular Dependencies
+The current load order suggests potential circular dependencies that need careful handling.
+
+### 2. Global State
+Heavy reliance on global `Ox` object and sequential initialization.
+
+### 3. Dynamic Module Loading
+The `Ox.load()` pattern allows runtime module loading which differs from ES module static imports.
+
+### 4. Build Process Integration
+The Python build script handles many transformations that would need webpack/rollup equivalents.
+
+### 5. Theme and Asset Processing
+Complex CSS variable substitution and SVG processing needs modern build tool equivalents.
+
+### 6. Browser Compatibility
+Current system supports very old browsers; ES modules require modern browser support.
+
+## Migration Strategy Considerations
+
+### Phase 1: Preparation
+- Add package.json and npm infrastructure
+- Set up modern build tooling (webpack/rollup/vite)
+- Create comprehensive test suite
+
+### Phase 2: Module Conversion
+- Convert individual files to ES modules
+- Maintain backward compatibility layer
+- Create barrel exports for each module
+
+### Phase 3: Build System
+- Replace Python build with npm scripts
+- Implement CSS/SVG processing with PostCSS/webpack
+- Set up development and production builds
+
+### Phase 4: Distribution
+- Publish to npm
+- Support both ES modules and UMD builds
+- Maintain script tag compatibility
+
+## Inline Test System
+
+OxJS has a unique inline test system integrated with its documentation:
+
+### Test Format
+Tests are embedded directly in documentation comments:
+```javascript
+/*@
+My.foo <f> Returns an item's bar per baz
+    (item) -> <n> Bar per baz, or NaN
+    item <o> Any item
+    > My.foo({bar: 1, baz: 10})
+    0.1
+    > My.foo({})
+    NaN
+@*/
+```
+
+### Test Execution
+- `Ox.doc()` parses documentation and extracts test statements
+- `Ox.test()` runs the tests and compares actual vs expected results
+- Tests can be synchronous or asynchronous (using callbacks)
+- Test results include pass/fail status and actual values
+
+### Benefits
+- Tests serve as executable documentation
+- Examples are guaranteed to be accurate
+- No separate test files needed for basic unit tests
+- Human-readable format
+
+## Key Files to Study
+1. `source/Ox.js` - Core loader implementation
+2. `source/Ox/js/Core.js` - Module loading logic
+3. `source/Ox/js/JavaScript.js` - Documentation parser and test runner
+4. `tools/build/build.py` - Build process details
+5. `source/UI/UI.js` - Module initialization pattern
+6. `examples/documentation/oxdoc_tutorial/js/example.js` - Documentation format examples
+7. `index.js` - Main entry point usage
\ No newline at end of file
diff --git a/ES_MODULE_MIGRATION_PLAN.md b/ES_MODULE_MIGRATION_PLAN.md
new file mode 100644
index 00000000..55df327d
--- /dev/null
+++ b/ES_MODULE_MIGRATION_PLAN.md
@@ -0,0 +1,119 @@
+# OxJS ES Modules Migration Plan
+
+## Phase 1: Test Suite Creation
+
+### Existing Test Infrastructure
+OxJS has an innovative inline test system built into its documentation format:
+- Tests are embedded in documentation comments using `> statement` followed by expected result
+- The `Ox.test()` function extracts and runs these tests from the source
+- Tests can be synchronous or asynchronous
+- Tests are human-readable and serve as documentation examples
+
+### Test Migration Strategy
+1. **Extract and modernize existing inline tests**
+   - Use `Ox.doc()` to parse all inline tests from source files
+   - Convert inline tests to Jest/Vitest test suites
+   - Maintain inline tests for documentation purposes
+   - Ensure all existing inline tests pass before migration
+
+2. **Create additional test coverage**
+   - Integration tests for module loading patterns
+   - Verify that ES module imports/exports work correctly
+   - Test the compatibility layer (Ox.load to ES modules bridge)
+   - Simple validation that existing examples still function
+
+3. **Set up test infrastructure**
+   - Add Jest or Vitest for running extracted tests
+   - Create test helpers for legacy Ox.load patterns
+   - Build a test runner that can execute both inline and external tests
+   - Focus on verifying functionality, not UI testing initially
+
+## Phase 2: Build Infrastructure Setup
+1. **Initialize npm project**
+   - Create package.json with proper metadata
+   - Add development dependencies (Vite, TypeScript, PostCSS, etc.)
+   - Set up ESLint and Prettier for code quality
+
+2. **Configure Vite build system**
+   - Development server with ES modules
+   - Production builds (ES modules + UMD)
+   - Asset handling for themes, SVGs, and images
+   - CSS processing with PostCSS for theme variables
+
+## Phase 3: Core Module Conversion
+1. **Convert Ox core files to ES modules**
+   - Start with leaf modules (no dependencies)
+   - Add explicit imports/exports
+   - Create index.js barrel exports
+   - Maintain careful load order for circular dependencies
+
+2. **Create compatibility layer**
+   - Global Ox object for backward compatibility
+   - Polyfill for Ox.load() using dynamic imports
+   - Bridge between ES modules and legacy code
+
+## Phase 4: UI Module Migration
+1. **Convert UI components to ES modules**
+   - Refactor each component as separate ES module
+   - Extract theme system to CSS variables
+   - Modernize SVG and image handling
+
+2. **Update theme processing**
+   - Use CSS custom properties instead of build-time substitution
+   - Implement theme switching via CSS classes
+   - Bundle theme assets with Vite
+
+## Phase 5: Testing and Validation
+1. **Verify all functionality**
+   - Run test suite
+   - Test all examples with new build
+   - Validate both dev and production builds
+   - Check browser compatibility
+
+2. **Performance testing**
+   - Compare bundle sizes
+   - Measure load times
+   - Profile runtime performance
+
+## Phase 6: Documentation and Release
+1. **Update documentation**
+   - Migration guide for existing users
+   - New ES modules usage examples
+   - API documentation updates
+
+2. **NPM package release**
+   - Publish to npm registry
+   - Support multiple entry points (ES modules, UMD, legacy)
+   - Maintain backward compatibility
+
+## Key Implementation Tasks
+- Convert ~50+ JavaScript files to ES modules
+- Replace Python build script with Vite/npm scripts
+- Modernize theme and asset processing
+- Create basic test suite for functionality verification
+- Ensure all existing examples continue working
+- Support both modern ES imports and legacy script tags
+
+## Testing Strategy Details
+
+### Unit Tests (Phase 1)
+Focus on core functionality:
+- Test Ox.Array methods (unique, sort, etc.)
+- Test Ox.String utilities (capitalize, format, etc.)
+- Test Ox.Math functions
+- Test Ox.Type checking utilities
+- Verify module export/import structure
+
+### Integration Tests (Phase 1)
+Verify module loading:
+- Test dynamic import() for lazy loading
+- Test circular dependency resolution
+- Test module initialization order
+- Test compatibility layer (Ox.load to ES modules)
+- Basic smoke tests for UI component initialization
+
+### Advanced Testing (Future)
+- E2E testing with Playwright
+- Visual regression testing
+- Performance benchmarking
+- Cross-browser testing
\ No newline at end of file