117 lines
3.7 KiB
Markdown
117 lines
3.7 KiB
Markdown
# Ritz Framework
|
|
|
|
A WebAssembly UI framework with Python-like syntax that compiles to high-performance WASM while remaining executable in Python for debugging.
|
|
|
|
## Core Innovations
|
|
|
|
### 1. Python's AST Module for Parsing
|
|
No need for a custom parser! Since our components are valid Python, we use Python's own `ast` module to parse them. Zero parsing overhead, perfect compatibility, error messages for free.
|
|
|
|
### 2. Debug Python in WASM (Not JavaScript!)
|
|
Set breakpoints in Python source code, step through Python lines, inspect Python variables - all in the browser! We compile with DWARF debug symbols and source maps that map WASM → Python source.
|
|
|
|
### 3. Progressive Module Loading
|
|
Split apps into multiple WASM modules:
|
|
- `bootstrap.wasm` (50KB) - Login only, no business logic
|
|
- `app-core.wasm` (200KB) - Main app, requires auth
|
|
- Feature modules - Lazy loaded on demand
|
|
- Security: Unauthenticated users never receive app code!
|
|
|
|
### 4. Python Executable, WASM Compilable
|
|
Write components in **actual Python** that can run in CPython for debugging, but compile to WebAssembly for production with:
|
|
- No virtual DOM overhead
|
|
- Direct signal-to-DOM updates
|
|
- 99% fewer mutations than React
|
|
- Sub-200KB bundle sizes
|
|
|
|
## Quick Start
|
|
|
|
### Try the Python Prototype
|
|
|
|
```bash
|
|
# Run the example
|
|
python3 example.py
|
|
|
|
# Run tests
|
|
python3 test.py
|
|
```
|
|
|
|
### Component Syntax
|
|
|
|
```python
|
|
@component
|
|
def Counter():
|
|
count = signal(0)
|
|
|
|
def increment():
|
|
count += 1
|
|
|
|
with Div(class_='counter'):
|
|
yield H1('Counter App')
|
|
yield P(f'Count: {count}')
|
|
yield Button('Click me', onclick=increment)
|
|
```
|
|
|
|
### Key Features
|
|
|
|
1. **Yield-based composition** - Natural Python generators for building component trees
|
|
2. **Context managers** - Use `with` statements for nested structures
|
|
3. **Reactive signals** - Fine-grained reactivity without virtual DOM
|
|
4. **Mixed content** - Yield strings, components, or elements seamlessly
|
|
|
|
## Files
|
|
|
|
- `RESEARCH.md` - Complete technical architecture and implementation plan
|
|
- `framework.py` - Python prototype implementation
|
|
- `example.py` - Example components demonstrating the syntax
|
|
- `test.py` - Simple test file
|
|
- `ast_parser.py` - Parse components using Python's ast module!
|
|
- `debug_concept.py` - Revolutionary Python-in-WASM debugging
|
|
- `module_system.py` - Progressive loading & security architecture
|
|
- `compiler.py` - Complete compilation pipeline concept
|
|
|
|
## Architecture
|
|
|
|
The framework works in two modes:
|
|
|
|
1. **Debug Mode** (Current): Runs in Python interpreter, generates HTML/IR
|
|
2. **Production Mode** (TODO): Compiles to WebAssembly with LLVM
|
|
|
|
### Compilation Pipeline
|
|
|
|
```
|
|
Python-like syntax → Parser (AST) → LLVM IR → WebAssembly → Browser
|
|
```
|
|
|
|
### Reactive Runtime
|
|
|
|
- Signals store values + subscriber lists in WASM memory
|
|
- Effects track dependencies automatically
|
|
- Direct signal-to-DOM-node mapping (no diffing)
|
|
- Batched DOM operations across WASM/JS bridge
|
|
|
|
## Next Steps
|
|
|
|
1. ✅ Python prototype with working components
|
|
2. ⬜ Parser for Python subset (yields, functions, decorators)
|
|
3. ⬜ LLVM backend for WASM generation
|
|
4. ⬜ Reactive runtime in C/Rust
|
|
5. ⬜ DOM operation batching and JS bridge
|
|
6. ⬜ Benchmarks against React/SolidJS
|
|
|
|
## Performance Targets
|
|
|
|
Based on SolidJS and Leptos research:
|
|
- Bundle size: < 200KB compressed
|
|
- Startup time: < 500ms on slow 3G
|
|
- Update performance: Within 10% of vanilla JS
|
|
- Memory usage: 70% less than React
|
|
|
|
## Why This Approach?
|
|
|
|
1. **Developer happiness** - Write Python, debug Python, ship WASM
|
|
2. **Performance** - Compile-time optimization, no virtual DOM
|
|
3. **Simplicity** - Yield syntax is intuitive and composable
|
|
4. **Type safety** - Static typing at compile time
|
|
|
|
Start with `example.py` to see the syntax in action! |