round-core 0.0.7 → 0.0.9

package/README.md

@@ -1,4 +1,4 @@
-<h1 align="center">Round Framework</h1>
+<h1 align="center">Round JS</h1>
  
 <p align="center">
   <img src="https://raw.githubusercontent.com/ZtaMDev/RoundJS/main/Round.png" alt="Round Framework Logo" width="200" />
@@ -12,27 +12,46 @@
   <em>Round is a lightweight frontend framework focused on building <b>single-page applications (SPAs)</b> with <b>fine‑grained reactivity.</b></em>
 </p>
 
+<div align="center">
+ 
+Extension for [VSCode](https://marketplace.visualstudio.com/items?itemName=ZtaMDev.round) and [OpenVSX](https://open-vsx.org/extension/ztamdev/round)
+
+</div>
+
+--- 
+
+Instead of a Virtual DOM diff, Round updates the UI by subscribing DOM updates directly to reactive primitives (**signals**) and **bindables**. This keeps rendering predictable, small, and fast for interactive apps.
+
+The `round-core` package is the **foundation of RoundJS**.
+
+You can think of `round-core` as:
+- A **framework-level runtime**, not just a state library
+- Comparable in scope to React + Router + Signals, but significantly smaller
+- Suitable for fast SPAs and simple SSR setups without heavy infrastructure
+
+## Installation
+
+To use Round JS today, install the core package:
+
 ```bash
 npm install round-core
 ```
 
-Instead of a Virtual DOM diff, Round updates the UI by subscribing DOM updates directly to reactive primitives (**signals**) and **bindables**. This keeps rendering predictable, small, and fast for interactive apps.
-
-## What Round is focused on
+Or with Bun:
 
-- **SPA-first**: client-side navigation and UI updates.
-- **Fine-grained reactivity**: update only what depends on the changed signal.
-- **Ergonomic bindings**: built-in two-way bindings with `bind:*` directives.
-- **A JSX superset**: `.round` files support extra control-flow syntax that compiles to JavaScript.
-- **Minimal runtime**: DOM-first runtime (no VDOM diffing).
+```bash
+bun add round-core
+```
 
-## Architecture
+## What Round is focused on
 
 Round is a **No-VDOM** framework.
 
 1.  **Direct DOM Manipulation**: Components run once. They return real DOM nodes (via `document.createElement`).
 2.  **Fine-Grained Reactivity**: Use of `signal`, `effect`, and `bindable` creates a dependency graph.
-3.  **Surgical Updates**: When a signal changes, only the specific text node, attribute, or property subscribed to that signal is updated. The component function does not re-run.
+3.  **Ergonomic bindings**: built-in two-way bindings with `bind:*` directives.
+4.  **Surgical Updates**: When a signal changes, only the specific text node, attribute, or property subscribed to that signal is updated. The component function does not re-run.
+5.  **A JSX superset**: `.round` files support extra control-flow syntax that compiles to JavaScript.
 
 This avoids the overhead of Virtual DOM diffing and reconciliation entirely.
 
@@ -49,35 +68,6 @@ A **signal** is a small reactive container.
 - Reading a signal inside an `effect()` tracks a dependency.
 - Writing to a signal triggers only the subscribed computations.
 
-
-## Normal Installation
-
-Simply install the `round-core` package
-
-```bash
-bun add round-core
-```
-
-Or:
-
-```bash
-npm install round-core
-```
-
-## Repo Installation
-
-> Round is currently in active development. If you are using the repository directly, install dependencies and run the CLI locally.
-
-```bash
-bun install
-```
-
-Or:
-
-```bash
-npm install
-```
-
 ## Quick start (create a new app)
 
 Round includes a CLI with a project initializer.
@@ -93,7 +83,9 @@ This scaffolds a minimal Round app with `src/app.round` and an example `src/coun
 
 ## `.round` files
 
-A `.round` file is a JSX-based component module (ESM) compiled by the Round toolchain. you can also use .jsx files but you wont get the round JSX superset features like conditional rendering and other features.
+A `.round` file is a JSX-based component module (ESM) compiled by the Round toolchain.
+You can also use `.jsx` files, but you will not get the Round JSX superset features
+such as extended control flow.
 
 Example `src/app.round`:
 
@@ -320,6 +312,20 @@ Notes:
 
 This compiles roughly to a `.map(...)` under the hood.
 
+### `switch`
+
+```jsx
+{switch(status()){
+    case 'loading': return <Spinner />;
+    case 'error':   return <ErrorMessage />;
+    default:        return <DataView />;
+}}
+```
+
+Notes:
+- The `switch` expression is automatically wrapped in a reactive tracker, ensuring that the view updates surgically when the condition (e.g., a signal) changes.
+- Each case handles its own rendering without re-running the parent component.
+
 ## Routing
 
 Round includes router primitives intended for SPA navigation. All route paths must start with a forward slash `/`.
@@ -403,6 +409,21 @@ The CLI is intended for day-to-day development:
 
 Run `round -h` to see available commands.
 
+## Signals Internals
+
+RoundJS utilizes a high-performance reactivity engine designed for efficiency and minimal memory overhead:
+
+- **Doubly-Linked List Dependency Tracking**: Instead of using heavy `Set` objects, RoundJS uses a linked-list of subscription nodes. This eliminates array spreads and object allocations during signal updates, providing constant-time performance for adding/removing dependencies.
+- **Global Versioning (Clock)**: Every signal write increments a global version counter. Computed signals (`derive`) track the version of their dependencies and only recompute if they are "dirty" (out of date). This ensures true lazyness and avoids redundant calculations.
+- **Automatic Batching**: Multiple signal updates within the same execution cycle are batched. Effects and DOM updates only trigger once at the end of the batch, preventing "glitches" and unnecessary re-renders.
+
+## Performance
+
+RoundJS sits in a powerful "middle ground" of performance:
+
+- **vs React**: Round's fine-grained reactivity is **massively faster** (>30x in micro-benchmarks) than React's component-level reconciliation. DOM updates are surgical and don't require diffing a virtual tree.
+- **vs Preact Signals**: While highly optimized, RoundJS signals are currently slightly slower than Preact Signals (~10x difference in raw signal-to-signal updates), as Preact utilizes more aggressive internal optimizations. However, for most real-world applications, RoundJS provides more than enough performance.
+
 ## Status
 
 Round is under active development and the API is still stabilizing. The README is currently the primary documentation; a dedicated documentation site will be built later using Round itself.