+ 
+
Reflex
+Universal Reactive Runtime
+“One contract. One core. Any surface.”
--- -## 🚀 Overview +## What Reflex Actually Is -Reflex is not just another UI framework. -It is a **general-purpose reactive runtime**: a lightweight ownership system, fine-grained signals, and a scheduler — independent of JSX or the DOM. +**Reflex is not a UI framework.** -Unlike React, Solid, or Vue, Reflex is not locked to the browser. You can render into **DOM, Canvas, WebGL, mobile bridges, or custom targets** — the runtime stays the same. UI is just one of many possible frontends. +Reflex is a **deterministic reactive computation engine** with ownership semantics, epoch-based time, and intrusive graph topology. -**Core idea:** One **Owner** per scope governs signals, effects, and components. Lifecycle, dependency tracking, and cleanup all go through it — no leaks, no zombie state. +It can drive: + +- UI frameworks (DOM / Canvas / WebGL / Native) +- Simulation engines +- Reactive servers +- Dataflow pipelines +- Distributed systems +- Game engines +- Orchestration layers + +UI is just one possible **surface adapter** — not the core identity. --- -## ✨ Key Advantages +## Architecture + +### `@reflex/contract` + +Pure mathematical definitions. No logic. No runtime. + +Defines the **invariants** of the system: + +- `NodeKind`, `LifeState`, `Epoch`, `OwnerId` +- `INode`, `ITemporalNode`, `IOwner` +- `IScheduler`, `IAllocator` +- Reactive graph contracts + +This layer is **frozen by design**. It defines what reality means in Reflex. -- **Ownership as the Unit of Life** - Every signal, effect, or component belongs to an owner. Dispose of a scope → everything inside cleans up automatically. +### `@reflex/core` -- **Contextual Dependency Injection** - Context flows naturally down the ownership tree via prototype inheritance. No prop drilling, no manual context management. +The actual engine: -- **Fine-Grained Signals** - Reactive primitives (`signal`, `derived`, `effect`) update only what actually changes. No re-rendering unnecessary nodes. +- Ownership model (Owner Tree) +- Reactive DAG (signals → memos → effects) +- Epoch system (deterministic local time) +- Intrusive graph links (no adjacency arrays) +- Allocation strategies / pooling +- Dirty propagation +- Disposal algorithms +- Context prototype chain +- Event validation (epoch + version + life state) -- **Coarse Transactions & Batching** - Batched updates, snapshots, and async-safe consistency for SSR, hydration, and streaming pipelines. +**No DOM. No JSX. No rendering. No browser assumptions.** -- **Universal Surfaces** - DOM, Canvas, WebGL, server pipelines, native UI — the runtime is agnostic. +Pure logic. -- **Scheduler-Orchestrated Side Effects** - Timers, I/O, DOM patches, or workers run through a unified priority-based queue for smooth interactivity. +### `@reflex/runtime` -- **Lightweight & Fast** - Core size ~6 KB. Predictable scaling from micro widgets to massive app trees. +Surface implementations: + +- DOM adapter +- Scheduler bindings +- Async bridges +- Server integration +- Worker / thread bridges +- Experimental modules + +Uses **only contracts + core**. Swappable. Extensible. --- -## 🧩 Architectural Layers +## Core Model -1. **Ownership Layer (Coarse)** +Reflex operates on **4 fundamental invariants**: - - Scopes, parent/child hierarchy, disposals. - - Lifecycle backbone: mount, unmount, cleanup. +1. **Ownership is the unit of life** — nothing exists without an owner +2. **Reactivity is a DAG, not a tree** — real topological ordering +3. **Time is local (Epochs), not global** — deterministic causality +4. **Nothing exists without a context** — no ambient globals -2. **Reactive Layer (Fine)** +When an owner dies → everything dies safely. No zombies. No leaks. No magical GC. + +--- - - Signals, computed values, DAG dependency graph. - - Minimal updates only where needed. +## Ownership Model + +``` +Root Owner +└─ App Owner + ├─ Graph Owner + │ ├─ Signal A + │ ├─ Computation B + │ └─ Effect C + └─ Feature Owner + └─ Async Effect +``` -3. **Orchestration Layer** +Every reactive node (signal, memo, effect, async callback) has an owner. - - Unified scheduler for effects, timers, I/O, and batching. - - Priorities, deadlines, cancellations. +Child owners inherit: -4. **Surface Layer (Optional)** +- Context +- Scheduling +- Lifetime guarantees - - DOM, Canvas, WebGL, mobile, or custom renderers. +`dispose(owner)` guarantees **deterministic cleanup** of the entire subgraph. --- -## 🔍 Ownership Flow +## Reactive Graph — Real DAG -**Owner Tree Example:** +Reflex builds an **intrusive directed acyclic graph**: ``` -App Owner (macro) -├─ Main Owner -│ ├─ Signal A → Memo 1 → Effect 1 -│ └─ Signal B → Memo 2 → Effect 2 -└─ Footer Owner - └─ Effect 3 +signal → memo → memo → effect + │ ↘ + └─────→ effect ``` -_Signals mark DAG nodes dirty, scheduler flushes only affected computations._ -_Dispose is iterative post-order: children first, then parent._ +- Intrusive links (no arrays) +- O(1) relinking / unlinking +- Deterministic execution order +- Lazy evaluation support +- Stable topology under concurrency -**Dirty propagation:** +Signals **do not notify**. They mark versions and propagate dirtiness. The scheduler decides when to execute. +--- + +## Epoch System + +Reflex doesn't rely on JavaScript time. It uses **local epochs**. + +Each node tracks: + +```ts +epoch: number; +version: number; ``` -Signal A.set(99) - ↓ markDirty -Memo1 → dirty=true -Effect1 → scheduled run -Memo2 → unchanged + +When an event arrives: + +```ts +{ target: Node, payload } + +1. Validate: + - LifeState alive? + - Owner exists? + - Local epoch valid? + - Version matches? + - Observers exist? + +2. Only then → apply mutation ``` +This makes Reflex **asynchronous-safe by construction**. No race conditions. No stale updates. + --- -## 🔍 Reflex vs Existing Frameworks +## Scheduler Model + +The scheduler is not a re-render loop. + +It's a **universal task orchestrator**: -| Capability | React / Solid | Reflex | -| -------------- | ------------------------- | ----------------------------------------- | -| **Core Model** | Component-centric | Ownership-centric (scopes as first-class) | -| **Reactivity** | Hooks / signals (UI only) | Signals for any domain, not tied to UI | -| **Lifecycle** | Hooks / cleanup | Hierarchical ownership + dispose batch | -| **Context** | Context API | Prototype inheritance per scope | -| **Rendering** | DOM-bound | DOM, Canvas, WebGL, native, server | -| **Scheduling** | Fiber (UI only) | General-purpose priority-based scheduler | -| **Philosophy** | UI framework | Universal reactive runtime | +- Effects +- Async callbacks +- DOM patches +- Worker communication +- IO operations +- Microtasks / macrotasks + +Designed for: + +- Priority queues +- Frame-based batching +- Deadline-aware scheduling +- Backpressure handling +- Cooperative yielding + +Closer to an **OS microkernel** than React Fiber. --- -## 📦 Getting Started +## Context System -**Install:** +Contexts use **prototype inheritance**, not maps: -```bash -npm install @reflex/core +```ts +ChildOwner.context = Object.create(ParentOwner.context); ``` -**Basic Signal Example:** +Benefits: + +- O(1) lookup +- Zero registration overhead +- No provider boilerplate +- Fully deterministic +- Instant propagation + +Real lexical scoping — not React's simulated version. + +--- + +## Example ```ts -import { signal, derived, effect } from "@reflex/core"; +import { signal, derived, effect, createScope } from "@reflex/core"; -const count = signal(0); -const doubled = derived(() => count.value * 2); +createScope(() => { + const count = signal(0); + const double = derived(() => count.value * 2); -effect(() => { - console.log(`Count=${count.value}, Double=${doubled.value}`); -}); + effect(() => { + console.log(count.value, double.value); + }); -count.value++; // logs instantly + count.value = 5; +}); ``` -**DOM Example (optional surface binding):** +When the scope ends → automatic cleanup. No manual teardown needed. + +--- + +## Optional DOM Surface ```tsx -import { signal, render } from "@reflex/core/dom"; +import { signal, render } from "@reflex/runtime/dom"; function Counter() { const count = signal(0); @@ -144,53 +246,79 @@ function Counter() { render(