rip-lang 2.5.1 → 2.7.1

package/docs/INTERNALS.md

@@ -76,7 +76,7 @@ class BinaryOp {
 ["+", left, right]  // That's it!
 ```
 
-**Result:** CoffeeScript's compiler is 17,760 LOC. Rip's is ~14,000 LOC—**smaller, yet includes a full reactive framework, template engine, and component system.**
+**Result:** CoffeeScript's compiler is 17,760 LOC. Rip's is ~11,000 LOC—**smaller, yet includes a full reactive runtime.**
 
 ## S-Expression Structure
 

package/docs/PHILOSOPHY.md

@@ -40,7 +40,7 @@ class BinaryOp {
 ["+", left, right]  // That's it!
 ```
 
-**Result:** CoffeeScript's compiler is 17,760 LOC. Rip's is ~14,000 LOC—smaller, yet includes a complete reactive framework with signals, templates, and components.
+**Result:** CoffeeScript's compiler is 17,760 LOC. Rip's is ~11,000 LOC—smaller, yet includes a complete reactive runtime with state, computed values, and effects.
 
 ## The Fundamental Rule
 
@@ -421,8 +421,8 @@ counter = ->
 |-----------|------------------|-----|------------|
 | **Lexer+Rewriter** | 3,558 LOC | 3,537 LOC | Expanded syntax |
 | **Parser Generator** | 2,285 LOC (Jison) | ~1,000 LOC (Solar) | Built-in, ~250× faster! |
-| **Compiler** | 10,346 LOC (AST Nodes) | 7,965 LOC (S-expressions) | +Reactive framework! |
-| **Total** | **17,760 LOC** | **~14,000 LOC** | **Smaller + full framework** |
+| **Compiler** | 10,346 LOC (AST Nodes) | 5,500 LOC (S-expressions) | +Reactive runtime! |
+| **Total** | **17,760 LOC** | **~11,000 LOC** | **Smaller + reactive runtime** |
 
 ## Feature Comparison Table
 
@@ -470,24 +470,20 @@ counter = ->
 
 > **v2.5.1 - Production-Ready with Fine-Grained Reactivity**
 
-## Summary Matrix
+## Summary
 
 | Layer | Syntax | Runtime | Features | DX | Score |
 |-------|--------|---------|----------|-----|-------|
 | **Reactivity** | A+ | A+ | A+ | A+ | **A+** |
-| **Templates** | A+ | A | A | A+ | **A** |
-| **Components** | A | A | A- | A | **A-** |
-
-*Components A- due to missing SSR/Hydration. Context API and Error Primitives are implemented.*
 
 ## Reactivity ⭐⭐⭐⭐⭐ (Production-Ready)
 
 **This is genuinely excellent.**
 
 ```coffee
-count := 0                     # Signal (state)
-doubled ~= count * 2          # Derived (auto-tracks)
-effect -> console.log count   # Effect (auto-runs)
+count := 0                    # State
+doubled ~= count * 2          # Computed (auto-tracks)
+log ~> console.log count      # Effect (auto-runs)
 ```
 
 | Aspect | Rating | Notes |
@@ -499,83 +495,32 @@ effect -> console.log count   # Effect (auto-runs)
 
 **Competitive with:** SolidJS signals, Vue 3 refs, Preact signals
 
-## Templates ⭐⭐⭐⭐⭐ (Great DX, Fast Runtime)
-
-**Innovative syntax with fine-grained performance.**
-
-```coffee
-render
-  div#main.card ...props
-    h1.title "Hello, #{name}!"
-    input value <=> username, @keydown.enter: submit
-    button.('btn', isActive && 'active') @click.prevent: handleClick, "Submit"
-```
-
-| Aspect | Rating | Notes |
-|--------|--------|-------|
-| Syntax | A+ | Indentation-based, clean, intuitive |
-| Features | A | Classes, IDs, events, modifiers, spread, two-way binding |
-| Runtime | A | Fine-grained: only dynamic parts get effects |
-| Innovation | A | Dynamic classes `div.('a', x && 'b')`, `<=>` binding |
+## Framework-Agnostic Design
 
-## Components ⭐⭐⭐⭐⭐ (Fine-Grained, Production-Ready)
-
-**Clean syntax with Svelte-class performance.**
-
-| Aspect | Rating | Notes |
-|--------|--------|-------|
-| Syntax | A | Clean, obvious structure |
-| Props | A | Required, optional, defaults, rest props |
-| **Performance** | **A+** | **Fine-grained O(1) updates!** |
-
-### Performance Comparison
-
-| Operation | Old Approach | New Approach |
-|-----------|--------------|--------------|
-| Update 1 text | O(n) rebuild | **O(1)** single node |
-| Update 1 attr | O(n) rebuild | **O(1)** single attr |
-| Add list item | O(n) rebuild | **O(1)** create 1 node |
-| Remove list item | O(n) rebuild | **O(1)** remove 1 node |
-
-**Result:** 30-40x faster for typical reactive updates!
+Rip's reactivity system is **framework-agnostic** — use it with React, Vue, Svelte, or vanilla JavaScript. The reactive primitives (state, computed, effects) work independently of any UI layer.
 
 ## Competitive Analysis
 
-| Framework | Reactivity | Templates | Components | Performance | DX | Overall |
-|-----------|------------|-----------|------------|-------------|-----|---------|
-| **Rip** | A+ | A | A- | A | A+ | **A-** |
-| SolidJS | A+ | A | A | A+ | A | A |
-| Svelte 5 | A | A+ | A | A+ | A+ | A |
-| Vue 3 | A- | A | A | B+ | A | A- |
-| React | B | B+ | A | B | A- | B+ |
+| Framework | Reactivity | DX | Performance | Overall |
+|-----------|------------|-----|-------------|---------|
+| **Rip** | A+ | A+ | A | **A** |
+| SolidJS | A+ | A | A+ | A |
+| Vue 3 | A- | A | B+ | A- |
+| React | B | A- | B | B+ |
 
 **Rip's Position:**
 
 | Strength | Why |
 |----------|-----|
-| **Reactivity A+** | Signals, computed, effects, batching, Context API |
+| **Reactivity A+** | State, computed, effects, batching |
 | **DX A+** | Cleanest syntax of all, no boilerplate |
-| **Performance A** | O(1) fine-grained updates, keyed reconciliation |
-
-| Gap | Path to A |
-|-----|-----------|
-| **Components A-** (not A) | Missing SSR/Hydration |
-| **Overall A-** (not A) | No ecosystem (router, state lib, devtools) |
-
-## Completed Features ✅
-
-- [x] Reactivity primitives (signals, computed, effects)
-- [x] Template syntax and features
-- [x] Props system (`@prop`, `@prop?`, `@prop = default`, `@...rest`)
-- [x] Component composition
-- [x] Children/slots
-- [x] Lifecycle hooks
-- [x] Fine-grained DOM updates
-- [x] Fine-grained conditionals (if/else) with effect cleanup
-- [x] Fine-grained loops (for) with keyed reconciliation
-- [x] **Context API** (`setContext`, `getContext`, `hasContext`)
-- [x] **Error primitives** (`__catchErrors`, `__handleError`)
+| **Framework-agnostic** | Use with any UI framework |
+
+## Completed Features
+
+- [x] Reactivity primitives (state, computed, effects)
 - [x] **Batching** (`__batch()` for grouped updates)
+- [x] **Error primitives** (`__catchErrors`, `__handleError`)
 
 ## Best Current Uses
 

package/docs/REACTIVITY.md

@@ -0,0 +1,288 @@
+# Rip Reactivity System
+
+Rip implements a **fine-grained reactive system** that rivals and often exceeds the capabilities of major frameworks like Vue, Svelte, Solid, and React — in just ~200 lines of runtime code.
+
+## The Reactive Triad
+
+Rip's entire reactivity model is built on three foundational concepts:
+
+| Primitive | Description | Read As | Role | Purpose |
+|-----------|-------------|---------|------|---------|
+| `:=` | state | "has state" | **Source** | Where reactive data originates |
+| `~=` | computed | "always equals" | **Derivation** | Computed values (lazy, cached) |
+| `~>` | effect | "reacts to" | **Reaction** | Side effects when data changes |
+
+These three primitives are the **minimal complete set** for reactive programming — everything React, Vue, Svelte, and Solid can do with state management, Rip can do too.
+
+---
+
+## Why These Three Are Complete
+
+Every reactive system reduces to these three concepts:
+
+| Framework | Source | Derivation | Reaction |
+|-----------|--------|------------|----------|
+| **Rip** | `:=` | `~=` | `~>` |
+| Angular | `signal()` | `computed()` | `effect()` |
+| Imba | `@property` | implicit | implicit |
+| MobX | `observable` | `computed` | `autorun` |
+| Next.js | `useState` | `useMemo` | `useEffect` |
+| React | `useState` | `useMemo` | `useEffect` |
+| Solid | `createSignal` | `createMemo` | `createEffect` |
+| Svelte 4 | `let x` | `$: x` | `$: {}` |
+| Svelte 5 | `$state` | `$derived` | `$effect` |
+| Vue | `ref()` | `computed()` | `watch()` |
+
+### What You Can Build From These Three
+
+- **Stores** → objects with state properties
+- **Two-way binding** → state + effect that syncs
+- **Async resources** → state + effect that fetches
+- **Event handling** → update state → triggers reactions
+- **Derived stores** → computed from other state
+
+### What's Missing Without Any One
+
+- **Without `:=`** → No source of truth
+- **Without `~=`** → Manual tracking or inefficient effects
+- **Without `~>`** → Can't react to changes (no side effects)
+
+---
+
+## Quick Example
+
+```rip
+count := 0                      # count has state 0
+doubled ~= count * 2            # doubled always equals count * 2
+logger ~> console.log count     # reacts to count changes
+~> console.log count            # same thing, but the "fire and forget" version
+
+increment: -> count += 1
+
+increment()  # Logs: 1
+increment()  # Logs: 2
+```
+
+---
+
+## How It Works
+
+### State (`:=`) — "has state"
+
+State creates a **reactive container** that tracks its readers and notifies them on change.
+
+```rip
+count := 0        # count has state 0
+count += 1        # Update triggers dependents
+```
+
+**Compiles to:**
+```javascript
+const count = __state(0);
+count.value += 1;
+```
+
+**What happens internally:**
+1. Reading `count.value` inside an effect/computed **tracks** the dependency
+2. Writing to `count.value` **notifies** all subscribers
+3. Effects re-run, computeds mark dirty
+
+### Computed (`~=`) — "always equals"
+
+Computed creates a **computed value** that automatically updates when dependencies change.
+
+```rip
+count := 0
+doubled ~= count * 2    # doubled always equals count * 2
+```
+
+**Key features:**
+- **Lazy** — only computes when read
+- **Cached** — won't recompute unless dependencies change
+- **Chainable** — computeds can depend on other computeds
+
+### Effect (`~>`) — "reacts to"
+
+The effect operator runs **side effects** when dependencies change. Dependencies are auto-tracked from reactive values read in the body.
+
+```rip
+~> document.title = "Count: #{count}"
+```
+
+**Key features:**
+- **Auto-tracking** — dependencies detected automatically from body
+- **Immediate** — runs once immediately to establish dependencies
+- **Controllable** — optionally assign to a variable to control the effect
+
+**Syntax:**
+```rip
+# Fire and forget (no assignment)
+~> console.log count
+
+# Controllable (assign to variable)
+logger ~> console.log count
+logger.stop!     # Pause reactions
+logger.run!      # Resume reactions
+logger.cancel!   # Permanent disposal
+```
+
+---
+
+## Comparison with Major Frameworks
+
+### State
+
+| Feature | Rip | Vue | Solid | React |
+|---------|:---:|:---:|:-----:|:-----:|
+| Auto-tracking on read | ✅ | ✅ | ✅ | ❌ |
+| Same-value skip | ✅ | ✅ | ✅ | ✅ |
+| Re-entry protection | ✅ | ❌ | ❌ | ❌ |
+| Lock for SSR | ✅ | ❌ | ❌ | ❌ |
+| Cleanup/disposal | ✅ | ✅ | ✅ | ❌ |
+| Raw read (untracked) | ✅ | ✅ | ✅ | ❌ |
+| Primitive coercion | ✅ | ❌ | ❌ | N/A |
+
+**Rip advantage:** `.lock()`, `.kill()`, `.read()` utilities that others lack.
+
+### Computed
+
+| Feature | Rip | Vue | Solid | MobX |
+|---------|:---:|:---:|:-----:|:----:|
+| Lazy evaluation | ✅ | ✅ | ✅ | ✅ |
+| Cached until deps change | ✅ | ✅ | ✅ | ✅ |
+| Dirty propagation | ✅ | ✅ | ✅ | ✅ |
+| Auto dependency cleanup | ✅ | ✅ | ✅ | ✅ |
+| Chainable | ✅ | ✅ | ✅ | ✅ |
+| Read without tracking | ✅ | ❌ | ❌ | ❌ |
+| Lock (freeze value) | ✅ | ❌ | ❌ | ❌ |
+
+**Rip advantage:** `.read()` for untracked access, `.lock()` to freeze.
+
+### Effect (`~>`)
+
+| Feature | Rip | Vue | Svelte | React |
+|---------|:---:|:---:|:------:|:-----:|
+| Auto-tracking | ✅ | ✅ | ✅ | ❌ |
+| No manual deps array | ✅ | ✅ | ✅ | ❌ |
+| Runs immediately | ✅ | ✅ | ✅ | ✅ |
+| Controllable (stop/run) | ✅ | ✅ | ✅ | ❌ |
+| Re-runs on change | ✅ | ✅ | ✅ | ✅ |
+
+**Rip advantage over React:** No manual dependency arrays!
+
+```javascript
+// React - manual, error-prone
+useEffect(() => {
+  document.title = `Count: ${count}`;
+}, [count]);  // 😩 Must list deps manually
+
+// Rip - automatic
+~> document.title = "Count: #{count}"  // 🎉 Deps tracked automatically
+```
+
+### Bundle Size
+
+| Framework | Runtime Size |
+|-----------|-------------|
+| React | ~40 KB (minified) |
+| Vue | ~34 KB |
+| Svelte | ~2 KB (but grows with app size) |
+| **Rip** | **~4 KB** (full runtime) |
+
+---
+
+## Advanced Features
+
+### Batching
+
+Group multiple updates into a single flush:
+
+```javascript
+__batch(() => {
+  count.value = 1;
+  name.value = "Alice";
+  // Effects run once at the end, not twice
+});
+```
+
+### Untracked Reads
+
+Read a value without creating a dependency:
+
+```javascript
+const currentValue = count.read();  // No tracking
+```
+
+### Locking (SSR/Hydration)
+
+Prevent writes during server-side rendering or freeze values:
+
+```javascript
+count.lock();  // Now immutable
+```
+
+### Cleanup
+
+Dispose of reactive values:
+
+```javascript
+const finalValue = count.kill();  // Returns value, clears subscribers
+```
+
+---
+
+## The Architecture
+
+```
+┌─────────────┐     reads     ┌─────────────┐
+│   STATE     │◄──────────────│   EFFECT    │
+│   count     │               │   (side fx) │
+└──────┬──────┘               └─────────────┘
+       │                             ▲
+       │ notifies                    │ triggers
+       ▼                             │
+┌─────────────┐     reads     ┌──────┴──────┐
+│  COMPUTED   │◄──────────────│   EFFECT    │
+│  doubled    │               │   (logger)  │
+└─────────────┘               └─────────────┘
+```
+
+1. **State** is the source of truth
+2. **Computed** derives from state (lazy, cached)
+3. **Effects** react to state/computed changes
+4. **Changes propagate** through the dependency graph
+
+---
+
+## Why Fine-Grained Reactivity?
+
+Rip uses **fine-grained reactivity** (like Vue/Solid), not Virtual DOM diffing (like React).
+
+| Approach | How it works | Pros | Cons |
+|----------|--------------|------|------|
+| **VDOM** (React) | Re-render tree, diff, patch | Simple mental model | Overhead, requires optimization |
+| **Fine-grained** (Rip) | Track dependencies, update directly | Surgical updates, fast | More complex internally |
+
+### Result
+
+- **No VDOM overhead** — changes propagate directly to subscribers
+- **Surgical updates** — only the exact things that changed update
+- **No `useMemo`/`useCallback` dance** — caching is automatic
+- **Smaller bundles** — no diffing algorithm needed
+
+---
+
+## Summary
+
+Rip's reactivity system:
+
+✅ **The Reactive Triad** — state (`:=`), computed (`~=`), effect (`~>`) <br>
+✅ **Natural reading** — "has state", "always equals", "reacts to" <br>
+✅ **Minimal complete set** — same model as Vue, Solid, MobX <br>
+✅ **Lazy computed** — only calculates when needed <br>
+✅ **Fine-grained** — surgical updates to subscribers <br>
+✅ **Controllable effects** — `.stop!`, `.run!`, `.cancel!` when needed <br>
+✅ **Tiny runtime** — ~200 lines, ~4 KB <br>
+✅ **Extra utilities** — `.lock()`, `.read()`, `.kill()` that others lack <br>
+
+**On par with Vue/Solid. Better than React. A fraction of the size.**