rip-lang 3.10.14 → 3.12.0

package/CHANGELOG.md

@@ -1,4 +1,4 @@
-<p><img src="docs/rip.svg" alt="Rip Logo" width="100"></p>
+<img src="https://raw.githubusercontent.com/shreeve/rip-lang/main/docs/assets/rip.png" style="width:50px" /> <br>
 
 # Changelog
 

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="docs/rip-1280w.png" alt="Rip Logo" width="400">
+  <img src="docs/assets/rip-1280w.png" alt="Rip Logo" width="400">
 </p>
 
 <h1 align="center">Rip</h1>
@@ -9,7 +9,7 @@
 </p>
 
 <p align="center">
-  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-3.10.14-blue.svg" alt="Version"></a>
+  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-3.12.0-blue.svg" alt="Version"></a>
   <a href="#zero-dependencies"><img src="https://img.shields.io/badge/dependencies-ZERO-brightgreen.svg" alt="Dependencies"></a>
   <a href="#"><img src="https://img.shields.io/badge/tests-1%2C243%2F1%2C243-brightgreen.svg" alt="Tests"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License"></a>

package/docs/RIP-INTERNALS.md

@@ -1,4 +1,4 @@
-<img src="https://raw.githubusercontent.com/shreeve/rip-lang/main/docs/rip.png" style="width:50px" /> <br>
+<img src="https://raw.githubusercontent.com/shreeve/rip-lang/main/docs/assets/rip.png" style="width:50px" /> <br>
 
 # Rip Internals
 

package/docs/RIP-LANG.md

@@ -1,4 +1,4 @@
-<img src="https://raw.githubusercontent.com/shreeve/rip-lang/main/docs/rip.png" style="width:50px" /> <br>
+<img src="https://raw.githubusercontent.com/shreeve/rip-lang/main/docs/assets/rip.png" style="width:50px" /> <br>
 
 # Rip Language Reference
 

package/docs/RIP-TYPES.md

@@ -1,4 +1,4 @@
-<img src="https://raw.githubusercontent.com/shreeve/rip-lang/main/docs/rip.png" style="width:50px" /> <br>
+<img src="https://raw.githubusercontent.com/shreeve/rip-lang/main/docs/assets/rip.png" style="width:50px" /> <br>
 
 # Rip Types
 

package/docs/WEB-FRAMEWORKS.md

@@ -0,0 +1,486 @@
+# Web Framework Landscape: 2025–2026
+
+> A structured comparison for evaluating the positioning of Rip UI against the
+> five dominant JavaScript UI frameworks. Data gathered February 2026.
+
+---
+
+## Summary Matrix
+
+| Dimension                | React 19                  | Solid.js 1.9              | Svelte 5                   | Vue 3.5                   | Angular 19–20              |
+|--------------------------|---------------------------|---------------------------|-----------------------------|---------------------------|----------------------------|
+| **Reactive model**       | VDOM + compiler hints     | Signals (fine-grained)    | Compiler + signals (runes)  | Proxy-based reactivity    | Signals + zone.js (legacy) |
+| **Runtime size (gzip)**  | ~45 KB                    | ~7 KB                     | ~2–18 KB (scales w/ usage)  | ~27–34 KB                 | ~50–65 KB (130 KB+ fresh)  |
+| **Build step**           | Required (Babel/SWC+)     | Required (Vite/Rollup)    | Required (Svelte compiler)  | Required (Vite)           | Required (Angular CLI)     |
+| **Compiler**             | React Compiler (opt-in)   | Compile-time transforms   | Core design (deep compiler) | Vapor mode (in progress)  | AOT template compiler      |
+| **SSR strategy**         | RSC + streaming           | SolidStart (streaming)    | SvelteKit (streaming)       | Nuxt 3 (streaming)        | Angular SSR + incremental  |
+| **Hydration**            | Full (selective w/ RSC)   | Streaming progressive     | Progressive (SvelteKit)     | Lazy hydration (3.5)      | Incremental (on-demand)    |
+| **Component model**      | Functions + hooks          | Functions + signals       | `.svelte` files + runes     | SFC (script/template)     | Classes → standalone fns   |
+| **State management**     | External (Zustand, etc.)  | Built-in (signals/stores) | Built-in (runes)            | Built-in (ref/reactive)   | Built-in (signals) + RxJS  |
+| **Maturity / ecosystem** | Dominant (60% job market) | Niche (~1.2% adoption)    | Growing (loved by devs)     | Strong (esp. APAC/EU)     | Enterprise standard        |
+
+---
+
+## 1. React 19+
+
+### Core Reactive Model
+**Virtual DOM with compiler-assisted optimization.** React still diffs a virtual
+tree against the real DOM, but the new React Compiler (formerly React Forget)
+automatically inserts memoization, eliminating most manual `useMemo`/`useCallback`.
+Components re-execute on every state change — the VDOM diffing algorithm then
+determines what DOM mutations to apply.
+
+### Runtime Size
+- **~45 KB** min+gzip for `react` + `react-dom`
+- Server Components reduce *shipped* JS by keeping components server-side (zero
+  client JS for those components), but the React runtime itself is unchanged
+- Real-world production apps with Server Components: ~156 KB total JS (vs. heavier
+  without RSC)
+
+### Build Step
+Required. Babel or SWC for JSX transforms, plus a bundler (Webpack, Vite, Turbopack).
+React Compiler is an additional Babel plugin. Next.js/Remix abstract most of this.
+
+### Developer Experience
+- **Strengths:** Massive ecosystem (50,000+ npm packages), dominant job market (~60%
+  of frontend positions), excellent tooling (React DevTools, extensive docs), Server
+  Components reduce full-stack data-fetching boilerplate
+- **React Compiler:** Eliminates memoization ceremony — one project removed 2,300
+  lines of `useMemo`/`useCallback` after migration
+
+### Known Pain Points
+- **`useEffect` remains the #1 footgun:** Dependency array confusion, accidental
+  infinite loops, race conditions, memory leaks. Developers consistently misuse it
+  for data fetching, subscription management, and lifecycle events
+- **Mental model complexity:** Rules of hooks (no conditionals, no loops), closure
+  stale-state bugs, the server/client component boundary adds another dimension of
+  mental overhead (`'use client'` directives, RSC payload format)
+- **Bundle size:** Even with RSC, the base runtime is the largest among non-Angular
+  frameworks. Tree-shaking doesn't reduce React's core
+- **Decision paralysis:** No canonical state management, routing, or data fetching —
+  developers must evaluate Zustand vs. Jotai vs. Redux vs. Recoil vs. signals
+  libraries vs. context, etc.
+
+### Component Composition
+Functions returning JSX. Server Components (default) render on server, Client
+Components (opt-in via `'use client'`) render on client. Props flow downward; state
+is lifted or managed externally. Context API for dependency injection.
+
+### State Management
+No built-in solution beyond `useState`/`useReducer`. Ecosystem solutions dominate:
+Zustand, Jotai, Redux Toolkit, Recoil. React 19 adds `useActionState` and
+`useOptimistic` for form/mutation state.
+
+### SSR / Hydration
+- **React Server Components (RSC):** Components render on the server, producing a
+  compact binary RSC Payload. Client components receive serialized props and hydrate.
+  Server components ship zero JS to clients.
+- **Streaming SSR:** HTML streams to the client progressively via `renderToPipeableStream`
+- **Selective hydration:** Suspense boundaries allow React to hydrate high-priority
+  components first
+- **Performance:** Initial page loads improve ~38% with RSC; e-commerce cases report
+  47% load time reduction
+- **Limitation:** RSC is effectively a Next.js/framework feature — raw React doesn't
+  provide SSR infrastructure
+
+---
+
+## 2. Solid.js 1.9 (2.0 Experimental)
+
+### Core Reactive Model
+**True fine-grained reactivity via signals.** Components execute once — only signal
+subscriptions trigger targeted DOM updates. No virtual DOM. No diffing. No
+re-rendering of component functions. Signal reads automatically create subscriptions;
+signal writes trigger only the exact DOM nodes that depend on them.
+
+### Runtime Size
+- **~7 KB** min+gzip (compiler + minimal runtime)
+- 3x smaller than React's initial bundle
+- Near-vanilla-JS benchmark performance: scores **1.07** (vs. 1.00 for raw JS, vs.
+  React's **1.71** — lower is better)
+
+### Build Step
+Required. Vite with `vite-plugin-solid` for JSX compilation. The compiler transforms
+JSX into fine-grained reactive DOM operations (not virtual DOM creation).
+
+### Developer Experience
+- **Strengths:** JSX syntax familiar to React devs, signals are simple
+  (`createSignal`, `createEffect`, `createMemo`), no rules-of-hooks constraints,
+  components run once (easier mental model for when code executes), extreme
+  performance out of the box
+- **SolidStart 1.0:** Full-stack meta-framework with SSR, SSG, CSR, file-based
+  routing, server functions — comparable to Next.js but for Solid
+
+### Known Pain Points
+- **Tiny ecosystem:** ~1.2% adoption (declining from 1.36%), disappeared from 2025
+  Stack Overflow survey. Few UI component libraries, limited third-party integrations
+- **Bus factor:** 1,592 of 1,592 commits from Ryan Carniato; second contributor has
+  33. Entire project depends on one person
+- **Code quality concerns:** 204 `@ts-expect-error`/`@ts-ignore` annotations,
+  `type TODO = any` at the core of the signal system (persisted 4+ years)
+- **Hot reload instability:** Regular crashes requiring dev server restarts
+- **Job market:** Negligible hiring demand
+- **Solid 2.0 is experimental:** Breaking changes to reactivity, SSR, and hydration
+  are in progress. No release date. SolidStart 2.0 (Vite-native) is also being
+  rebuilt from scratch
+
+### Component Composition
+Functions returning JSX (same syntax as React). Components execute once — the return
+value is the actual DOM. Control flow via `<Show>`, `<For>`, `<Switch>` components
+(not JS conditionals, because the function body doesn't re-execute).
+
+### State Management
+Built-in and first-class:
+- `createSignal()` — atomic reactive value
+- `createStore()` — nested reactive objects (Proxy-based)
+- `createResource()` — async data with Suspense integration
+- `createMemo()` — derived computations
+No need for external state libraries in most cases.
+
+### SSR / Hydration
+- **SolidStart:** Streaming SSR with progressive hydration
+- **Islands architecture:** Partial hydration possible via Astro integration
+- **Performance:** Among the fastest SSR implementations due to no VDOM overhead
+- **Limitation:** SolidStart is less battle-tested than Next.js/Nuxt; the Vinxi
+  foundation is being replaced with pure Vite in SolidStart 2.0
+
+---
+
+## 3. Svelte 5
+
+### Core Reactive Model
+**Compiler-first with signal-like runes.** The Svelte compiler transforms `.svelte`
+files into imperative DOM operations at build time. Svelte 5 introduces "runes" — a
+signal-based reactivity system using `$state`, `$derived`, `$effect` — replacing the
+implicit `let`-based reactivity of Svelte 4.
+
+Key runes:
+- `$state(value)` — reactive state (backed by Proxy)
+- `$state.raw(value)` — reactive but non-deep (no Proxy)
+- `$derived(expr)` — computed value, auto-tracks dependencies
+- `$effect(() => ...)` — side effect that re-runs on dependency changes
+
+### Runtime Size
+- **~2–18 KB** depending on features used (compiler includes only what's needed)
+- Svelte 5 achieves **up to 50% smaller bundles** vs. Svelte 4
+- Production dashboard benchmark: 47 KB total JS (vs. React's 156 KB for identical
+  functionality)
+- The "disappearing framework" ideal is partially preserved — but Svelte 5 now ships
+  a small runtime for the reactivity system
+
+### Build Step
+Required. The Svelte compiler is the core of the framework — `.svelte` files are not
+valid JavaScript. SvelteKit uses Vite as the build tool.
+
+### Developer Experience
+- **Strengths:** Minimal boilerplate, single-file components with scoped CSS, runes
+  provide explicit reactivity that works outside `.svelte` files (in `.svelte.js` and
+  `.svelte.ts`), excellent tutorial/documentation, SvelteKit is batteries-included
+- **Performance:** Fastest initial render in benchmarks (110ms vs. Vue 142ms vs.
+  React 178ms), lowest memory footprint (7.9 MB idle vs. React's 18.7 MB)
+
+### Known Pain Points
+- **Runes add complexity:** Three state runes (`$state`, `$state.raw`,
+  `$state.snapshot`) force choices that didn't exist before. Proxy-based state has
+  non-obvious performance implications
+- **Loss of "magic" simplicity:** Svelte 4's `let x = 0` reactivity was beloved for
+  its simplicity. Runes feel more like "React hooks but for Svelte" to some devs
+- **Store deprecation:** The transparent, simple store system is deprecated in favor
+  of runes. Stores and runes have subtly different reactivity models that don't fully
+  interoperate
+- **Runtime shift:** Svelte now ships actual runtime code for reactivity, moving away
+  from the pure "compile-away-the-framework" philosophy
+- **Custom component format:** `.svelte` files are not standard JS — requires tooling
+  for every editor, linter, formatter, and build pipeline
+- **Smaller ecosystem than React/Vue:** Fewer component libraries, less hiring demand
+
+### Component Composition
+Single-file `.svelte` components with `<script>`, markup, and `<style>` sections.
+Props via `$props()` rune. Slots for content projection. Snippets (new in Svelte 5)
+for reusable template fragments.
+
+### State Management
+Built-in via runes:
+- `$state` for component-local and shared state
+- `$derived` for computed values
+- `$effect` for side effects
+- Shared state via `.svelte.js` modules (exportable reactive state)
+- Legacy stores still work but are deprecated
+
+### SSR / Hydration
+- **SvelteKit:** Full-featured meta-framework with streaming SSR, SSG, ISR
+- **Progressive hydration:** Components hydrate as needed
+- **Load functions:** Data fetching runs on server, serialized to client
+- **Adapter system:** Deploy to Node, Vercel, Cloudflare, static, etc.
+- **Performance:** Excellent — small JS payloads mean fast hydration
+
+---
+
+## 4. Vue 3.5+
+
+### Core Reactive Model
+**Proxy-based reactivity system.** Vue uses JavaScript Proxies to intercept
+property access and mutation on reactive objects. When a reactive property is read
+during a component's render, Vue tracks it as a dependency. When the property changes,
+Vue re-renders only the affected components.
+
+Key primitives:
+- `ref(value)` — reactive wrapper (access via `.value`)
+- `reactive(object)` — deep reactive proxy
+- `computed(() => ...)` — cached derived value
+- `watch()` / `watchEffect()` — explicit side effects
+
+**Vapor Mode** (in development for Vue 3.6): A new compilation strategy that
+eliminates the Virtual DOM entirely, generating direct DOM-update code similar to
+Solid.js. Same developer-facing API, different compilation output.
+
+### Runtime Size
+- **~27–34 KB** min+gzip (official: ~27 KB runtime, reported in benchmarks as ~34 KB)
+- Vue 3.5: 56% memory usage improvement, 10x faster for large reactive arrays
+- Vapor Mode (when stable) will further reduce overhead by removing VDOM diffing code
+
+### Build Step
+Required. Vite (created by Vue's author, Evan You) is the standard build tool.
+Single-file components (`.vue`) require the Vue compiler.
+
+### Developer Experience
+- **Strengths:** Best learning curve among major frameworks, excellent documentation,
+  Composition API offers React-hooks-like composability without the footguns,
+  progressive adoption (can use Options API or Composition API), strong TypeScript
+  integration
+- **Nuxt 3:** Mature meta-framework with auto-imports, file-based routing, server
+  routes, excellent DX
+
+### Known Pain Points
+- **`.value` ceremony:** `ref()` requires accessing `.value` in script but not in
+  templates — a persistent source of confusion
+- **Two API styles:** Options API vs. Composition API creates ecosystem fragmentation;
+  tutorials/libraries may use either
+- **Vapor Mode delays:** Originally planned for Vue 3.4, now expected in 3.6+.
+  Compatibility challenges have pushed the timeline repeatedly
+- **Enterprise adoption gaps:** Strong in APAC/EU design-led markets but limited
+  hiring pools in US enterprise compared to React/Angular
+- **Ecosystem size:** Large but smaller than React's — fewer choices in some niches
+
+### Component Composition
+Single-file `.vue` components with `<script setup>`, `<template>`, and `<style>`
+sections. `<script setup>` is the modern default — top-level bindings are
+automatically exposed to the template. Props via `defineProps()`, events via
+`defineEmits()`. Slots for content projection.
+
+### State Management
+Built-in reactivity is often sufficient:
+- `ref()` / `reactive()` for local/shared state
+- `computed()` for derived values
+- `provide` / `inject` for dependency injection
+- **Pinia** (official) for complex global state — simple, TypeScript-native, devtools
+  integration
+- Vue 3.5+ SSR: `useId()` for hydration-safe unique IDs
+
+### SSR / Hydration
+- **Nuxt 3:** Full-featured meta-framework (SSR, SSG, ISR, hybrid rendering)
+- **Lazy hydration (Vue 3.5):** Components can defer hydration until needed
+- **Streaming SSR:** Supported via Nuxt 3 + `renderToWebStream`
+- **`useId()`:** Stable hydration-safe IDs for accessibility and form elements
+- **Performance:** Good — smaller runtime means less JS to hydrate
+
+---
+
+## 5. Angular 19–20
+
+### Core Reactive Model
+**Signals (new) + Zone.js change detection (legacy).** Angular is transitioning from
+Zone.js-based change detection (monkey-patches all async APIs to trigger global
+change detection) to a granular Signals-based system.
+
+Signal primitives:
+- `signal(value)` — writable reactive value (`.set()`, `.update()`)
+- `computed(() => ...)` — read-only derived signal
+- `effect(() => ...)` — side effect (stabilized in Angular 20)
+- `linkedSignal()` — signal linked to a source (stabilized in Angular 20)
+
+**Zoneless** (Developer Preview in Angular 20): Removes Zone.js entirely, relying
+on Signals for change detection. Cleaner stack traces, smaller bundles, better
+compatibility with third-party code.
+
+### Runtime Size
+- **~50–65 KB** gzipped for core framework
+- Fresh "Hello World" project: **130–138 KB+** min+gzip
+- Removing Zone.js (zoneless) reduces this, but Angular remains the heaviest framework
+- FCP: 400–800 ms (vs. Vue's 150–300 ms, React's ~300 ms)
+
+### Build Step
+Required. Angular CLI with Webpack or esbuild. AOT (Ahead-of-Time) template
+compilation is the default — templates are compiled to optimized JS at build time.
+Strict project structure enforced by the CLI.
+
+### Developer Experience
+- **Strengths:** Opinionated "batteries-included" framework (routing, forms, HTTP,
+  i18n, testing all built-in), excellent for large teams with enforced patterns,
+  strong TypeScript integration (TypeScript is required, not optional), dependency
+  injection is powerful for enterprise architecture
+- **Angular 19–20 improvements:** Standalone components as default (no more
+  NgModules), Signals stabilized, resource API for async data, better DevTools
+
+### Known Pain Points
+- **Boilerplate:** Even with standalone components, Angular requires more ceremony
+  than alternatives. Decorators, metadata, DI registration
+- **Change detection confusion:** `ExpressionChangedAfterItHasBeenCheckedError`
+  produces stack traces pointing to framework code, not developer code. This error
+  has been a top Angular complaint for years
+- **Bundle size:** Largest runtime of all major frameworks. Zone.js adds ~35 KB alone
+- **Learning curve:** Steepest of all frameworks. New hires struggle for months.
+  RxJS adds another learning dimension on top of Signals
+- **Two reactive paradigms:** RxJS Observables and Signals now coexist, creating
+  confusion about when to use which. `toSignal()` / `toObservable()` bridge the gap
+  but add complexity
+- **DI runtime errors:** "No provider for X!" errors are common and hard to debug
+
+### Component Composition
+Standalone components (Angular 19+ default) — no NgModule required. Components are
+TypeScript classes with decorators. Templates use Angular's own syntax (`@if`, `@for`,
+`@switch` — new control flow in Angular 17+). Content projection via `<ng-content>`.
+Directives for cross-cutting behavior.
+
+### State Management
+Built-in (increasingly):
+- Signals for synchronous reactive state
+- RxJS for async streams (legacy but deeply embedded)
+- Services + DI for shared state
+- **NgRx** (Redux-like) for complex enterprise state — being updated for Signals
+- **Resource API** (Angular 19+) for async data fetching with Signals integration
+
+### SSR / Hydration
+- **Angular SSR:** Built-in (formerly Angular Universal), now tightly integrated
+- **Incremental hydration:** Components stay dehydrated until triggered. Triggers:
+  `viewport`, `interaction`, `idle`, `timer(ms)`, `immediate`, `never`,
+  `when(condition)`
+- **`@defer` blocks:** Lazy-load components with built-in hydration trigger syntax
+- **Event replay:** User interactions during SSR are captured and replayed after
+  hydration (Angular 18+)
+- **Performance:** Incremental hydration significantly improves FID and CLS, but
+  larger initial bundle still creates overhead vs. lighter frameworks
+
+---
+
+## Cross-Cutting Analysis
+
+### The Convergence Toward Signals
+
+Every major framework is converging on signal-based reactivity:
+
+| Framework | Signal Implementation              | Status           |
+|-----------|------------------------------------|------------------|
+| Solid.js  | Pioneered the pattern              | Stable (1.x)     |
+| Angular   | `signal()`, `computed()`, `effect()` | Stable (v20)   |
+| Vue       | `ref()`, `reactive()`, `computed()` | Stable (v3.0+) |
+| Svelte    | `$state`, `$derived`, `$effect`    | Stable (v5)      |
+| React     | No signals — VDOM + Compiler       | Divergent path   |
+
+React is the outlier. Every other framework has adopted signals (or signal-like
+reactivity). React's response is the React Compiler — automating VDOM optimizations
+rather than changing the reactive model.
+
+### The Compiler Spectrum
+
+Frameworks sit on a spectrum from pure runtime to pure compiler:
+
+```
+Pure Runtime ←——————————————————————————→ Pure Compiler
+   React          Vue         Angular        Svelte        (Solid)
+   (VDOM +     (Proxy +     (AOT +       (Compiler +     (Compiler +
+   Compiler     future       template      runes          signals,
+   hints)       Vapor)       compile)      runtime)       minimal RT)
+```
+
+- **React:** Mostly runtime. Compiler adds optimization hints but doesn't change
+  the execution model.
+- **Vue:** Runtime reactivity. Vapor Mode will add a compiler path that bypasses VDOM.
+- **Angular:** AOT template compilation + runtime change detection. Signals are
+  reducing runtime overhead.
+- **Svelte:** Deep compiler, but Svelte 5 added a signal runtime. Shifting right
+  to left.
+- **Solid:** Compiler transforms JSX to fine-grained DOM ops. Minimal runtime (~7 KB).
+
+### Where the Gaps Are (Opportunities for Rip UI)
+
+1. **No framework has unified the server/client model cleanly.** React's RSC is the
+   most ambitious attempt but creates a two-world problem (`'use client'` directives,
+   different rules for each). Every other framework punts to a meta-framework (Nuxt,
+   SvelteKit, SolidStart).
+
+2. **Reactivity is powerful but each flavor has ergonomic costs.** React's hooks have
+   rules and footguns. Vue's `.value` is a papercut. Svelte's runes added complexity.
+   Angular's Signals coexist awkwardly with RxJS. Solid's signals are elegant but the
+   JSX control flow (`<For>`, `<Show>`) is a compromise.
+
+3. **Bundle size vs. DX is an unresolved tension.** Svelte and Solid ship tiny bundles
+   but require custom file formats or component-level conventions. React and Angular
+   are heavy but offer familiar JS/TS ergonomics.
+
+4. **State management is fragmented.** React has no built-in solution (dozens of
+   competing libraries). Vue/Svelte/Solid have built-in primitives but each with
+   quirks. Angular has two competing paradigms (RxJS + Signals).
+
+5. **Hydration is still a problem everyone is solving differently.** Full hydration
+   (wasteful), progressive hydration (complex), incremental hydration (Angular's
+   approach), resumability (Qwik's approach). No consensus, each with trade-offs.
+
+6. **TypeScript integration varies.** Angular requires it. React/Vue/Svelte support
+   it but with varying degrees of type inference quality (Svelte's compiler and Vue's
+   SFC templates are harder to type-check than plain TSX).
+
+7. **Custom file formats create tooling tax.** `.svelte`, `.vue`, `.astro` files
+   each need custom language server support, linter plugins, formatter configs. Plain
+   `.js`/`.ts` (React, Solid) avoid this at the cost of less framework-level
+   optimization.
+
+### Performance Benchmarks (JS Framework Benchmark, 2025)
+
+| Framework    | Score (lower = faster) | Startup (ms) | Memory (MB) |
+|-------------|------------------------|-------------|-------------|
+| Vanilla JS  | 1.00                   | —           | —           |
+| Solid.js    | 1.07                   | 28          | ~8          |
+| Svelte 5    | ~1.10                  | 35          | ~8          |
+| Vue 3       | ~1.30                  | 42          | ~11         |
+| React 19    | 1.71                   | 55          | ~19         |
+| Angular 19  | ~1.80+                 | 78          | ~22         |
+
+---
+
+## Positioning Questions for Rip UI
+
+Based on this landscape, a new framework should be prepared to answer:
+
+1. **Reactive model:** Signals, VDOM, compiler-generated, or something new? The
+   industry has nearly converged on signals — deviating needs a strong argument.
+
+2. **Compiler depth:** How much work happens at build time vs. runtime? The trend is
+   toward more compilation, but each compiler approach creates tooling complexity.
+
+3. **Runtime weight:** Can you beat Solid's 7 KB? Can you approach zero-runtime like
+   original Svelte promised? What's the minimum viable runtime?
+
+4. **Server integration:** Is the server/client boundary a first-class concept? Can
+   it avoid the `'use client'` / meta-framework split that plagues React?
+
+5. **Hydration strategy:** Full, progressive, incremental, resumable, or none? This
+   is the current frontier of framework innovation.
+
+6. **File format:** Custom (`.svelte`, `.vue`) or standard JS/TS? Custom formats
+   enable deeper optimization but impose ecosystem costs.
+
+7. **State management:** Built-in or ecosystem? Every framework that delegated this
+   to the ecosystem (React) regrets it. Every framework with built-in state must
+   balance simplicity with power.
+
+8. **TypeScript story:** First-class types? Type inference quality? Can the framework
+   provide better type safety than existing options?
+
+9. **Migration story:** Can React/Vue/Svelte developers adopt incrementally, or is it
+   all-or-nothing?
+
+10. **What's the one thing you can do that none of them can?** Every successful
+    framework had a clear differentiator: React had the VDOM (2013), Vue had
+    progressive adoption (2014), Svelte had compile-away-the-framework (2019),
+    Solid had true fine-grained reactivity (2021), Qwik had resumability (2023).

package/docs/WEB-ROADMAP.md

@@ -0,0 +1,126 @@
+# Rip UI — Roadmap
+
+## What's There
+
+### Core Reactive System
+- **Reactive primitives** — `:=` (state), `~=` (computed), `~>` (effects) as
+  language syntax. Fine-grained dependency tracking, batching, readonly (`=!`).
+- **`__Component` base class** — mount, unmount, context push/pop, constructor
+  lifecycle all handled in the runtime. Components just override `_init`.
+- **`__state` signal passthrough** — if a value is already a signal, `__state`
+  returns it as-is. No separate `isSignal` check needed.
+- **Fine-grained DOM** — `_create` builds real DOM nodes, `_setup` wires
+  reactive effects that update individual text nodes and attributes.
+- **Timing primitives** — `delay`, `debounce`, `throttle`, `hold` as small
+  user-space functions composing `:=` + `~>` + cleanup. No framework API.
+
+### Component Model
+- **Component composition** — PascalCase identifiers in render blocks
+  instantiate child components. `card.rip` → `Card`. App-scoped, lazy-compiled,
+  cached after first use. No imports needed.
+- **Reactive props** — parent passes `:=` signals directly to children.
+  Child's `__state` passthrough returns the signal as-is. Two-way binding.
+- **Readonly props** — `=!` for props that children can read but not write.
+- **Children blocks** — `Card title: "Hello" -> p "content"` passes children
+  as a DOM node via the `@children` slot. `#content` for layout slots.
+- **Unmount cascade** — parent tracks child instances in `_children`.
+  `unmount()` cascades depth-first.
+- **Conditional rendering** — `if`/`else` in render blocks with anchor-based
+  conditional DOM.
+- **List rendering** — `for item in items` with keyed reconciliation.
+- **Event handling** — `@click: method` binds to `this.method` correctly.
+- **CSS classes** — `div.counter.active` compiles to static className.
+  Dynamic classes via `__clsx(...)`.
+- **Context** — `setContext`/`getContext`/`hasContext` for sharing data
+  between ancestor and descendant components without prop drilling.
+- **Lifecycle hooks** — `mounted`, `unmounted` work. `beforeMount`,
+  `beforeUnmount` are recognized.
+
+### State & Routing
+- **Reactive stash** — shared reactive store with proxy-based access.
+- **File-based router** — URL-to-component mapping with params, guards,
+  layouts, `_navigating` signal, keep-alive component cache.
+- **Hash routing** — `launch '/app', hash: true` for static single-file
+  deployment. Uses `readUrl()`/`writeUrl()` helpers. Back/forward and
+  direct URL loading work correctly.
+- **State persistence** — `persist: true` enables debounced auto-save of
+  `app.data` to sessionStorage. `_writeVersion` signal + `beforeunload` safety.
+- **Error boundaries** — catch mount-time errors.
+
+### Infrastructure
+- **Component store** — in-memory `.rip` file storage with compilation cache
+  and file watchers for hot reload via SSE.
+- **`launch bundle:`** — inline all components as heredoc strings in a single
+  HTML file. Zero-server deployment. `docs/demo.html` is a 337-line example.
+- **Combined bundle** — `rip-ui.min.js` (~52KB Brotli) packages the compiler
+  and pre-compiled UI framework in one file. Eliminates the `ui.rip` fetch
+  and its runtime compilation. `importRip('ui.rip')` is intercepted and returns
+  the pre-compiled module instantly.
+- **Parallel loading** — Monaco Editor preloaded via `<link rel="preload">`,
+  compiler exports available instantly via `globalThis.__ripExports`. All
+  synchronous setup runs in parallel with the Monaco CDN fetch.
+- **FOUC prevention** — playground pages use `body { opacity: 0 }` with a
+  `body.ready` fade-in transition after full initialization.
+- **Runtime deduplication** — both runtimes register on `globalThis.__rip`
+  and `globalThis.__ripComponent`. Multiple compilations share one runtime.
+- **Smooth app launch** — container fades in after first mount + font load.
+- **Navigation anti-flicker** — `_navigating` uses `delay 100` to suppress
+  brief loading indicators.
+
+---
+
+## Where Rip UI Wins
+
+1. **Simplicity of the reactive model.** Three operators, minimal complete set. No hooks rules, no dependency arrays, no `.value` papercuts.
+2. **Zero-build development.** No other framework runs entirely in the browser with zero build tooling.
+3. **Timing primitives from composition.** `delay`, `debounce`, `throttle`, `hold` prove architectural correctness — hard problems dissolve into small functions.
+4. **Effect cleanup design.** Returning a function from an effect for cleanup is the cleanest pattern across all frameworks.
+5. **Syntax over API.** `:=` beats `ref()`. `~=` beats `computed()`. `~>` beats `watchEffect()`. Less ceremony, same power.
+6. **Static deployment.** Hash routing + `launch bundle:` = full SPA in a single HTML file on any static host.
+
+## Where Others Win
+
+1. **Ecosystem.** Zero component libraries, zero third-party integrations, zero community packages.
+2. **SSR.** No server-side rendering means no SEO, no progressive enhancement.
+3. **Performance proof.** No benchmarks, no published numbers.
+4. **TypeScript depth.** Framework exports have no `.d.ts` files.
+5. **Tooling.** No DevTools extension, no CLI scaffolding.
+6. **Battle-testing.** React serves billions. We serve a demo app.
+
+---
+
+## The Path Forward
+
+### Must-have (blocks adoption)
+1. Named slots — multiple content projection points (header, body, footer)
+2. Framework `.d.ts` files — TypeScript definitions for all exports
+
+### Should-have (competitive parity)
+3. AOT compilation path — component-level ahead-of-time for production (framework AOT done in v0.3.2)
+4. SSR — server rendering for SEO
+5. js-framework-benchmark — published performance numbers
+6. Keyed list reconciliation — optimized array diffing for large datasets
+
+### Nice-to-have (ecosystem growth)
+7. DevTools extension — visual component/state inspector
+8. `create-rip-app` CLI — project scaffolding
+9. Headless UI primitives — accessible dropdown, modal, dialog
+10. State-preserving HMR — keep reactive state during hot reload
+11. Scoped slots and teleport — advanced composition patterns
+
+---
+
+## Known Caveats
+
+- **`getCompiled`/`setCompiled` cache modules, not JS strings.** Same source
+  at two paths = two cached modules. No deduplication across paths.
+- **Stash proxy missing `getOwnPropertyDescriptor` trap.** Works in practice
+  but could cause issues with `Object.keys`/spread in strict environments.
+- **Router regex recreated on every `buildRoutes` call.** Not a problem with
+  small route tables. Could optimize with fingerprint comparison.
+- **`router.current` creates a new object on every read.** A cached object
+  that updates inside batch would reduce garbage.
+- **REPL reactive state doesn't persist across `rip()` calls.** Each call is
+  a separate compilation. All reactive code must be in a single call.
+- **Hash routing and path routing are mutually exclusive.** Set once at
+  `launch` time. No runtime switching between modes.