docs: update status for completed JS backend and package manager

- JS_WASM_BACKEND_PLAN: Mark phases 1-5 complete, deprioritize WASM - LANGUAGE_COMPARISON: Update package manager status - OVERVIEW: Add completed features list - ROADMAP: Mark JS backend and package manager complete - Add PACKAGES.md documenting the package system Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-15 03:54:30 -05:00
parent c6d7f5cffb
commit cda2e9213a
5 changed files with 350 additions and 82 deletions
--- a/docs/JS_WASM_BACKEND_PLAN.md
+++ b/docs/JS_WASM_BACKEND_PLAN.md
@@ -150,101 +150,171 @@ async function fetchData_lux(handlers) {

 ---

+## Implementation Status
+
+| Phase | Status | Progress |
+|-------|--------|----------|
+| Phase 1: Core Language | COMPLETE | 100% |
+| Phase 2: Standard Library | COMPLETE | 100% |
+| Phase 3: Effects in JS | COMPLETE | 100% |
+| Phase 4: Browser/DOM Support | COMPLETE | 100% |
+| Phase 5: CLI Integration | COMPLETE | 100% |
+| Phase 6: WASM Backend | NOT STARTED | 0% |
+
+---
+
 ## Implementation Phases

-### Phase 1: Core Language (2-3 weeks)
+### Phase 1: Core Language - COMPLETE

-| Feature | Effort | Notes |
+| Feature | Status | Notes |
 |---------|--------|-------|
-| Basic types (Int, Float, Bool, String) | 2 days | Direct mapping |
-| Arithmetic and comparison operators | 1 day | |
-| Functions and calls | 2 days | |
-| Let bindings | 1 day | |
-| If expressions | 1 day | Ternary or if/else |
-| Pattern matching (basic) | 3 days | Tag checks, destructuring |
-| ADT definitions and constructors | 2 days | Object literals |
-| Closures | 2 days | Native JS closures |
-| Lists | 2 days | Map to Array |
+| Basic types (Int, Float, Bool, String) | DONE | Direct mapping |
+| Arithmetic and comparison operators | DONE | |
+| Functions and calls | DONE | |
+| Let bindings | DONE | |
+| If expressions | DONE | Ternary or if/else |
+| Pattern matching (basic) | DONE | Tag checks, destructuring |
+| ADT definitions and constructors | DONE | Object literals |
+| Closures | DONE | Native JS closures |
+| Lists | DONE | Map to Array |

-**Milestone:** Can compile `fib.lux` to JS and run in Node.js
+**Milestone:** Can compile `fib.lux` to JS and run in Node.js - ACHIEVED

-### Phase 2: Standard Library (1-2 weeks)
+### Phase 2: Standard Library - COMPLETE

-| Module | Effort | JS Implementation |
+| Module | Status | JS Implementation |
 |--------|--------|-------------------|
-| Console | 1 day | `console.log` |
-| String | 2 days | Native string methods |
-| List | 2 days | Array methods |
-| Math | 1 day | `Math.*` |
-| Option/Result | 1 day | Pattern matching |
-| JSON | 2 days | `JSON.parse/stringify` |
+| Console | DONE | `console.log` |
+| String | DONE | 20+ operations (length, concat, slice, etc.) |
+| List | DONE | Array methods (map, filter, fold, etc.) |
+| Math | DONE | `Math.*` (trig, pow, log, etc.) |
+| Option | DONE | isSome, isNone, map, flatMap, unwrapOr |
+| Result | DONE | isOk, isErr, map, mapErr, flatMap, toOption |
+| JSON | DONE | parse, stringify, get, keys, values, etc. |

-**Milestone:** Standard library examples work in browser
+**Milestone:** Standard library examples work in browser - ACHIEVED

-### Phase 3: Effects in JS (2 weeks)
+### Phase 3: Effects in JS - COMPLETE

-| Effect | Effort | JS Implementation |
+| Effect | Status | JS Implementation |
 |--------|--------|-------------------|
-| Console | 1 day | `console.log`, `prompt()` |
-| Http | 3 days | `fetch()` API |
-| File | 2 days | Not available in browser (Node.js only) |
-| Time | 1 day | `Date.now()`, `setTimeout` |
-| Random | 1 day | `Math.random()` |
-| DOM (new) | 5 days | New effect for browser manipulation |
+| Console | DONE | `console.log`, `prompt()` |
+| Http | DONE | `fetch()` API with Ok/Err handling |
+| Time | DONE | `Date.now()`, `setTimeout` |
+| Random | DONE | `Math.random()`, int, bool, float |
+| DOM | DONE | Full DOM manipulation API |

-**Milestone:** HTTP requests work in browser
+**Milestone:** HTTP requests work in browser - ACHIEVED

-### Phase 4: Browser/DOM Support (2-3 weeks)
+### Phase 4: Browser/DOM Support - COMPLETE

-New `Dom` effect for browser manipulation:
+The `Dom` effect provides comprehensive browser manipulation:

 ```lux
-effect Dom {
-    fn querySelector(selector: String): Option<Element>
-    fn createElement(tag: String): Element
-    fn appendChild(parent: Element, child: Element): Unit
-    fn addEventListener(el: Element, event: String, handler: () -> Unit): Unit
-    fn setTextContent(el: Element, text: String): Unit
-    fn setAttribute(el: Element, name: String, value: String): Unit
-    fn getInputValue(el: Element): String
-}
+// Available Dom operations:
+Dom.querySelector(selector)      // -> Option<Element>
+Dom.querySelectorAll(selector)   // -> List<Element>
+Dom.getElementById(id)           // -> Option<Element>
+Dom.createElement(tag)           // -> Element
+Dom.createTextNode(text)         // -> Element
+Dom.appendChild(parent, child)
+Dom.removeChild(parent, child)
+Dom.setTextContent(el, text)
+Dom.getTextContent(el)
+Dom.setInnerHtml(el, html)
+Dom.setAttribute(el, name, value)
+Dom.getAttribute(el, name)       // -> Option<String>
+Dom.addClass(el, class)
+Dom.removeClass(el, class)
+Dom.hasClass(el, class)          // -> Bool
+Dom.setStyle(el, prop, value)
+Dom.getValue(el)                 // For inputs
+Dom.setValue(el, value)
+Dom.addEventListener(el, event, handler)
+Dom.focus(el)
+Dom.blur(el)
+Dom.scrollTo(x, y)
+Dom.getBoundingClientRect(el)
+Dom.getWindowSize()
 ```

-| Feature | Effort | Notes |
+**Html Module** for type-safe HTML construction:
+
+```lux
+// Element constructors
+Html.div(attrs, children)
+Html.span(attrs, children)
+Html.button(attrs, children)
+Html.input(attrs, children)
+// ... 30+ HTML elements
+
+// Attribute constructors
+Html.class("name")
+Html.id("id")
+Html.href("url")
+Html.onClick(handler)
+Html.onInput(handler)
+// ... many more
+
+// Rendering
+Html.render(node)      // -> String (for SSR)
+Html.renderToDom(node) // -> Element (for browser)
+```
+
+**TEA (The Elm Architecture) Runtime:**
+
+```javascript
+Lux.app({
+    init: initialModel,
+    update: (model, msg) => newModel,
+    view: (model, dispatch) => Html.div(...),
+    root: "#app"
+});
+```
+
+| Feature | Status | Notes |
 |---------|--------|-------|
-| Basic DOM queries | 2 days | querySelector, getElementById |
-| Element creation | 2 days | createElement, appendChild |
-| Event handling | 3 days | addEventListener with closures |
-| Attribute manipulation | 2 days | setAttribute, classList |
-| Form handling | 2 days | Input values, form submission |
-| Virtual DOM (optional) | 5 days | Efficient updates |
+| Basic DOM queries | DONE | querySelector, getElementById, querySelectorAll |
+| Element creation | DONE | createElement, createTextNode, appendChild |
+| Event handling | DONE | addEventListener with closures |
+| Attribute manipulation | DONE | setAttribute, classList, styles |
+| Form handling | DONE | getValue, setValue, isChecked |
+| Html module | DONE | Type-safe HTML construction |
+| TEA runtime | DONE | Elm-style app architecture |
+| View dependency analysis | DONE | Svelte-style optimization hooks |

-**Milestone:** Can build interactive web page in Lux
+**Milestone:** Can build interactive web page in Lux - ACHIEVED

-### Phase 5: CLI Integration (1 week)
+### Phase 5: CLI Integration - COMPLETE

 ```bash
 # Compile to JavaScript
 lux compile app.lux --target js -o app.js

-# Compile to JavaScript module (ES modules)
-lux compile app.lux --target js --module -o app.mjs
-
-# Compile with bundled runtime
-lux compile app.lux --target js --bundle -o app.bundle.js
-
-# Run in Node.js
-lux run app.lux --target js
+# Compile and run in Node.js
+lux compile app.lux --target js --run
 ```

-### Phase 6: WASM Backend (3-4 weeks)
+### Phase 6: WASM Backend - DEPRIORITIZED

-Options:
-1. **Lux → C → Emscripten → WASM** (easiest, reuse C backend)
-2. **Lux → WASM directly** (more control, harder)
-3. **Lux → AssemblyScript → WASM** (middle ground)
+**Status:** Not planned. The JS backend fully serves the Elm/Gleam-style frontend use case.

-Recommended: Start with Emscripten approach, direct WASM later.
+**Rationale:** For typical web applications, JS compilation is superior:
+- Seamless DOM interop (no WASM boundary overhead)
+- Readable output for debugging
+- Smaller bundle sizes
+- Native event handling
+- Direct JS ecosystem integration
+
+Neither Elm nor Gleam compile to WASM—they target JS for these exact reasons.
+
+**Future consideration:** WASM may be revisited for:
+- Computation-heavy workloads (image processing, simulations, crypto)
+- Sharing binary logic between native server and browser
+- Porting performance-critical libraries
+
+For now, this is out of scope.

 ---

--- a/docs/LANGUAGE_COMPARISON.md
+++ b/docs/LANGUAGE_COMPARISON.md
@@ -41,7 +41,7 @@ Based on 2025 research, languages succeed through:

 **Winners:** Python (AI/ML libraries), JavaScript (npm), Rust (Cargo rated 71% admiration)

-**Lux Status:** Limited. Built-in stdlib only. No package manager ecosystem.
+**Lux Status:** Growing. Has `lux pkg` with git/path dependencies. No central registry yet.

 ### 2. Developer Experience
 > "TypeScript has won... it catches an absurd number of bugs before they hit production."
@@ -327,7 +327,7 @@ run app() with { Http = mockHttp, Database = inMemoryDb }

 | Gap | Why It Matters | Priority | Status |
 |-----|----------------|----------|--------|
-| **Ecosystem/Packages** | "You rarely build from scratch" (Python's success) | P0 | ❌ Missing |
+| **Ecosystem/Packages** | "You rarely build from scratch" (Python's success) | P0 | ⚠️ Basic (`lux pkg`) |
 | **Generics** | Can't write reusable `List<T>` functions | P0 | ✅ Complete |
 | **String Interpolation** | Basic usability | P1 | ✅ Complete |
 | **File/Network IO** | Can't build real applications | P1 | ✅ Complete |
@@ -349,9 +349,9 @@ run app() with { Http = mockHttp, Database = inMemoryDb }

 | Gap | Why It Matters | Status |
 |-----|----------------|--------|
-| No package registry | Can't share/reuse code | ❌ Missing |
+| No package registry | Central repo for packages | ⚠️ `lux pkg` works, registry missing |
 | No HTTP library | Can't build web services | ✅ Http effect |
-| No database drivers | Can't build real backends | ❌ Missing |
+| No database drivers | Can't build real backends | ❌ Missing (package opportunity) |
 | No JSON library | Can't build APIs | ✅ Json module |
 | No testing framework | Can't ensure quality | ✅ Test effect |

@@ -385,12 +385,13 @@ run app() with { Http = mockHttp, Database = inMemoryDb }

 | Domain | Why Not | Better Choice |
 |--------|---------|---------------|
-| Web Frontend | No JS compilation | Elm, TypeScript |
 | Systems/Embedded | Needs low-level control | Rust, Zig, C |
 | AI/ML | No ecosystem | Python |
 | Mobile | No compilation target | Kotlin, Swift |
 | Quick Scripts | Overhead not worth it | Python, Bash |

+**Note:** Web Frontend is now viable with the complete JS backend (Dom effect, Html module, TEA runtime).
+
 ---

 ## Part 7: Lessons from Language Adoption
@@ -437,7 +438,7 @@ run app() with { Http = mockHttp, Database = inMemoryDb }

 ### Medium-Term (Make It Attractive)

-5. **Package Manager** - Learn from Cargo's success
+5. **Package Registry** - Central repo for sharing (package manager done)
 6. **Standard HTTP Library** - Enable web backends
 7. **Full JS Compilation** - Enable web deployment
 8. **Comprehensive Documentation** - Examples, tutorials, cookbook
--- a/docs/OVERVIEW.md
+++ b/docs/OVERVIEW.md
@@ -233,9 +233,9 @@ Quick iteration with type inference and a REPL.

 | Limitation | Description |
 |------------|-------------|
-| **No Package Manager** | Can't share/publish packages yet |
 | **New Paradigm** | Effects require learning new concepts |
-| **Small Ecosystem** | No community packages yet |
+| **Small Ecosystem** | Community packages just starting |
+| **No Package Registry** | Can share code via git/path, no central registry yet |
 | **Early Stage** | Bugs likely, features incomplete |

 ---
@@ -296,7 +296,6 @@ Quick iteration with type inference and a REPL.

 - Large production applications (early stage)
 - Performance-critical code (C backend working, but no advanced optimizations)
- Web frontend development (no JS compilation)
 - Systems programming (no low-level control)

 ---
@@ -375,12 +374,18 @@ Values + Effects        C Code → GCC/Clang
 - ✅ Formatter

 **In Progress:**
-1. **Schema Evolution** - Type system integration, auto-migration
+1. **Schema Evolution** - Type-declared migrations working, auto-generation pending
 2. **Error Message Quality** - Context lines shown, suggestions partial
 3. **Memory Management** - RC working for lists/boxed, closures/ADTs pending

+**Recently Completed:**
+- ✅ **JavaScript Backend** - Full language support, browser & Node.js
+- ✅ **Dom Effect** - 40+ browser manipulation operations
+- ✅ **Html Module** - Type-safe HTML construction (Elm-style)
+- ✅ **TEA Runtime** - The Elm Architecture for web apps
+- ✅ **Package Manager** - `lux pkg` with git/path dependencies, module integration
+
 **Planned:**
-4. **SQL Effect** - Database access
-5. **Package Manager** - Share code (manifest parsing exists)
-6. **JavaScript Backend** - Run in browsers
-7. **Behavioral Type Verification** - Total, idempotent, deterministic checking
+4. **SQL Effect** - Database access (as a package)
+5. **Package Registry** - Central repository for sharing packages
+6. **Behavioral Type Verification** - Total, idempotent, deterministic checking
--- a/docs/PACKAGES.md
+++ b/docs/PACKAGES.md
@@ -0,0 +1,176 @@
+# Lux Package System
+
+Lux includes a built-in package manager for managing dependencies.
+
+## Quick Start
+
+### Initialize a Project
+
+```bash
+# Create a new project directory
+lux init my-project
+cd my-project
+
+# Or initialize in an existing directory
+lux pkg init
+lux pkg init my-project-name
+```
+
+This creates a `lux.toml` manifest file:
+
+```toml
+[project]
+name = "my-project"
+version = "0.1.0"
+description = "A Lux project"
+
+[dependencies]
+# Add dependencies here
+```
+
+### Adding Dependencies
+
+```bash
+# From a git repository
+lux pkg add mylib --git https://github.com/user/mylib
+
+# From a local path
+lux pkg add local-lib --path ../lib
+
+# With a specific version (for future registry support)
+lux pkg add http 1.0.0
+```
+
+### Installing Dependencies
+
+```bash
+lux pkg install
+```
+
+This installs all dependencies listed in `lux.toml` to the `.lux_packages/` directory.
+
+### Using Packages
+
+Once installed, import packages in your Lux code:
+
+```lux
+import mylib
+
+let result = mylib.doSomething()
+```
+
+## Commands Reference
+
+| Command | Description |
+|---------|-------------|
+| `lux pkg init [name]` | Initialize a lux.toml in the current directory |
+| `lux pkg install` | Install all dependencies from lux.toml |
+| `lux pkg add <pkg>` | Add a dependency |
+| `lux pkg remove <pkg>` | Remove a dependency |
+| `lux pkg list` | List dependencies and their status |
+| `lux pkg update` | Update all dependencies |
+| `lux pkg clean` | Remove installed packages |
+
+## Dependency Sources
+
+### Git Repository
+
+```toml
+[dependencies]
+mylib = { git = "https://github.com/user/mylib" }
+mylib = { git = "https://github.com/user/mylib", branch = "main" }
+```
+
+### Local Path
+
+```toml
+[dependencies]
+local-lib = { path = "../local-lib" }
+```
+
+### Registry (Future)
+
+```toml
+[dependencies]
+http = "1.0.0"
+```
+
+## Package Structure
+
+A valid Lux package must have one of these entry points:
+
+1. `lib.lux` - Main module file in package root
+2. `src/lib.lux` - Main module file in src directory
+
+Example package structure:
+
+```
+mypackage/
+├── lux.toml
+├── lib.lux          # Entry point (option 1)
+└── src/
+    └── lib.lux      # Entry point (option 2)
+```
+
+The entry point should export public functions:
+
+```lux
+// lib.lux
+pub fn helper(x: Int): Int = x * 2
+
+pub fn process(data: String): String = {
+    // Implementation
+    data
+}
+```
+
+## Project Layout
+
+A typical Lux project looks like:
+
+```
+my-project/
+├── lux.toml           # Project manifest
+├── src/
+│   └── main.lux       # Main source file
+├── tests/
+│   └── test.lux       # Test files
+└── .lux_packages/     # Installed dependencies (gitignore this)
+    ├── mylib/
+    │   └── lib.lux
+    └── utils/
+        └── lib.lux
+```
+
+## Standard Library
+
+The Lux standard library is available as a package:
+
+```bash
+lux pkg add stdlib --path /path/to/lux/stdlib
+```
+
+Or use the built-in modules directly:
+
+```lux
+// Built-in modules (always available)
+import html       // Type-safe HTML construction
+import browser    // Browser effects (Dom, Storage, Navigation)
+```
+
+## Best Practices
+
+1. **Add `.lux_packages/` to `.gitignore`** - Dependencies should be installed, not committed
+
+2. **Use semantic versioning** - When publishing packages, follow semver
+
+3. **Document your exports** - Add comments to public functions
+
+4. **Keep packages focused** - One package should do one thing well
+
+## Future Features
+
+- **Package Registry** - Central repository for sharing packages
+- **Version Resolution** - Automatic dependency version management
+- **Lock File** - Reproducible builds with exact versions
+- **Publishing** - `lux pkg publish` command
--- a/docs/ROADMAP.md
+++ b/docs/ROADMAP.md
@@ -67,7 +67,7 @@
 | Task | Priority | Effort | Status |
 |------|----------|--------|--------|
 | Elm-quality error messages | P1 | 2 weeks | ⚠️ Partial (context shown, suggestions missing) |
-| Full JS compilation | P2 | 4 weeks | ❌ Missing |
+| Full JS compilation | P2 | 4 weeks | ✅ Complete |
 | Hot reload / watch mode | P2 | — | ✅ Complete |
 | Debugger improvements | P3 | 2 weeks | ✅ Basic |
 | C backend CLI integration | P1 | — | ✅ Complete (`lux compile`) |
@@ -203,10 +203,18 @@

 | Task | Priority | Effort | Status |
 |------|----------|--------|--------|
-| Package manager (lux pkg) | P1 | 3 weeks | ⚠️ Basic |
+| Package manager (lux pkg) | P1 | 3 weeks | ✅ Complete |
+| Module loader integration | P1 | 1 week | ✅ Complete |
 | Package registry | P2 | 2 weeks | ❌ Missing |
 | Dependency resolution | P2 | 2 weeks | ❌ Missing |

+**Package Manager Features:**
+- `lux pkg init` - Initialize project with lux.toml
+- `lux pkg add/remove` - Manage dependencies
+- `lux pkg install` - Install from lux.toml
+- Git and local path dependencies
+- Automatic module resolution from .lux_packages/
+
 ### Tooling

 | Task | Priority | Effort | Status |
@@ -224,9 +232,16 @@
 | Extend C backend (closures) | P1 | — | ✅ Complete |
 | Extend C backend (pattern matching) | P1 | — | ✅ Complete |
 | Extend C backend (lists) | P1 | — | ✅ Complete |
-| JS backend | P2 | 4 weeks | ❌ Missing |
+| JS backend | P2 | 4 weeks | ✅ Complete |
 | WASM backend | P3 | 4 weeks | ❌ Missing |

+**JS Backend Features:**
+- Core language: functions, closures, ADTs, pattern matching
+- Standard library: String, List, Option, Result, Math, JSON
+- Effects: Console, Random, Time, Http, Dom
+- Browser support: Html module, TEA runtime, DOM manipulation
+- CLI: `lux compile --target js`
+
 ---

 ## Recommended Implementation Order
@@ -299,7 +314,8 @@
 - ✅ JSON parsing/serialization (parse, stringify, get, object, array)

 **Tooling:**
- ✅ C backend (functions, Console.print, CLI: `lux compile`)
+- ✅ C backend (functions, closures, pattern matching, lists)
+- ✅ JS backend (full language support, browser & Node.js)
 - ✅ REPL with history
 - ✅ Basic LSP server
 - ✅ Formatter