round-core 0.2.0 → 0.2.2

package/README.md

@@ -12,20 +12,20 @@
   <em><b>Round</b> is a lightweight, DOM-first framework for building SPAs with fine-grained reactivity, and fast, predictable updates powered by signals and bindables</em>
 </h3>
 
-
 <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
@@ -101,103 +101,109 @@ such as extended control flow.
 Example `src/app.round`:
 
 ```jsx
-import { Route } from 'round-core';
-import { Counter } from './counter.round';
+import { Route } from "round-core";
+import { Counter } from "./counter.round";
 
 export default function App() {
-    return (
-        <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center' }}>
-            <Route route="/" title="Home">
-                <Counter />
-            </Route>
-        </div>
-    );
+  return (
+    <div
+      style={{ display: "flex", flexDirection: "column", alignItems: "center" }}
+    >
+      <Route route="/" title="Home">
+        <Counter />
+      </Route>
+    </div>
+  );
 }
 ```
 
-## Markdown rendering with `@round-core/markdown`
+## Core API & Examples
 
-Round includes an optional companion package for markdown rendering with
-syntax highlighting and rich code blocks.
+### `signal(initialValue)`
 
-Install it alongside `round-core`:
+Create a reactive signal.
 
-```bash
-npm install @round-core/markdown
-```
+- Call with no arguments to **read**.
+- Call with one argument to **write**.
+- Use `.value` to read/write the current value in a non-subscribing way (static access).
 
-or with Bun:
+```jsx
+import { signal } from "round-core";
 
-```bash
-bun add @round-core/markdown
+export function Counter() {
+  const count = signal(0);
+
+  return (
+    <div>
+      <p>Count: {count()}</p>
+
+      <button onClick={() => count(count() + 1)}>Increment</button>
+
+      <button onClick={() => count(0)}>Reset</button>
+    </div>
+  );
+}
 ```
 
-Then use it in a `.round` file or JSX component:
+##### Explanation:
+
+- `signal(0)` creates a reactive value initialized to 0
+
+- Calling `count()` reads the current value and subscribes the DOM
+
+- Calling `count(newValue)` writes a new value and updates only the subscribed nodes
+
+- The component function runs once — only the text node updates when count changes
+
+#### Non-reactive (static) access with .value
 
 ```jsx
-import { createElement } from 'round-core';
-import { Markdown, defaultMarkdownStyles as markdown } from '@round-core/markdown';
-import '@round-core/markdown/styles.css';
+const count = signal(5);
 
-export default function App() {
-    const content = `
-# Markdown with code blocks
+// Read without tracking
+console.log(count.value); // 5
+```
 
-You can render fenced code blocks with syntax highlighting:
+### `asyncSignal(fetcher)`
 
-\`\`\`javascript
-const value = signal(0);
-\`\`\`
-`;
+Create a signal that manages asynchronous data fetching.
+
+- It returns a signal that resolves to the data once fetched.
+- **`.pending`**: A reactive signal (boolean) indicating if the fetch is in progress.
+- **`.error`**: A reactive signal containing any error that occurred during fetching.
+- **`.refetch()`**: A method to manually trigger a re-fetch.
+
+```jsx
+import { asyncSignal } from 'round-core';
 
+const user = asyncSignal(async () => {
+    const res = await fetch('/api/user');
+    return res.json();
+});
+
+export function UserProfile() {
     return (
         <div>
-            <Markdown content={content}/>
+            {if(user.pending()){
+                <div>Loading...</div>
+            } else if(user.error()){
+                <div>Error: {user.error().message}</div>
+            } else {
+                <div>Welcome, {user().name}</div>
+            }}
+            <button onClick={() => user.refetch()}>Reload</button>
         </div>
     );
 }
 ```
 
-You can also theme the markdown surface (background/text) and accents via
-`options.theme`:
-
-```jsx
-<Markdown
-  content={content}
-  options={{
-    theme: {
-      // Dark card-like surface
-      markdownBackground: '#020617',
-      markdownText: '#e5e7eb',
-      primaryColor: '#e5e7eb',
-      secondaryColor: '#38bdf8',
-    },
-  }}
-/>
-
-<Markdown
-  content={content}
-  options={{
-    theme: {
-      // Light mode
-      markdownBackground: '#ffffff',
-      markdownText: '#0f172a',
-      primaryColor: '#0f172a',
-      secondaryColor: '#2563eb',
-    },
-  }}
-/>
-```
-
-## Core API & Examples
-
-### `signal(initialValue)`
+### Signals Internals
 
-Create a reactive signal.
+RoundJS utilizes a high-performance reactivity engine designed for efficiency and minimal memory overhead:
 
-- Call with no arguments to **read**.
-- Call with one argument to **write**.
-- Use `.value` to read/write the current value in a non-subscribing way (static access).
+- **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.
 
 ### `derive(fn)`
 
@@ -218,7 +224,7 @@ export default function Counter() {
     return (
         <div>
             <h1>Count: {count()} (Doubled: {doubled()})</h1>
-            
+
             {/* Control flow is part of the Round JSX superset */}
             {if(count() > 5){
                  <p style="color: red">Count is high!</p>
@@ -233,14 +239,6 @@ export default function Counter() {
 }
 ```
 
-### 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.
-
 ## JSX superset control flow
 
 Round extends JSX inside `.round` files with a control-flow syntax that compiles to JavaScript. This is preferred over ternary operators for complex logic.
@@ -248,18 +246,21 @@ Round extends JSX inside `.round` files with a control-flow syntax that compiles
 ### `if / else if / else`
 
 ```jsx
-{if(user.loggedIn){
-    <Dashboard />
-} else if(user.loading){
-    <div>Loading...</div>
-} else {
-    <Login />
-}}
+{
+  if (user.loggedIn) {
+    <Dashboard />;
+  } else if (user.loading) {
+    <div>Loading...</div>;
+  } else {
+    <Login />;
+  }
+}
 ```
 
 Notes:
+
 - Conditions may be normal JS expressions.
-- For *simple paths* like `flags.showCounter` (identifier/member paths), Round will auto-unwrap signal-like values (call them) so the condition behaves as expected.
+- For _simple paths_ like `flags.showCounter` (identifier/member paths), Round will auto-unwrap signal-like values (call them) so the condition behaves as expected.
 - Multiple elements inside a block are automatically wrapped in a Fragment.
 
 ### `for (... in ...)`
@@ -270,26 +271,30 @@ Notes:
 }}
 ```
 
-This compiles to efficient **keyed reconciliation** using the `ForKeyed` runtime component. 
+This compiles to efficient **keyed reconciliation** using the `ForKeyed` runtime component.
 
 #### Keyed vs Unkeyed
+
 - **Keyed (Recommended)**: By providing `key=expr`, Round maintains the identity of DOM nodes. If the list reorders, Round moves the existing nodes instead of recreating them. This preserves local state (like input focus, cursor position, or CSS animations).
 - **Unkeyed**: If no key is provided, Round simply maps over the list. Reordering the list will cause nodes to be reused based on their index, which might lead to state issues in complex lists.
 
 ### `switch(...)`
 
 ```jsx
-{switch(status()){
-    case 'loading': 
-        <Spinner />;
-    case 'error':
-        <ErrorMessage />;
+{
+  switch (status()) {
+    case "loading":
+      <Spinner />;
+    case "error":
+      <ErrorMessage />;
     default:
-        <DataView />;
-}}
+      <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.
 
@@ -301,6 +306,7 @@ Round supports both static and **reactive** `try/catch` blocks inside JSX.
 - **Reactive**: By passing one or more signals to `try(...)`, the block will **automatically re-run** if any of those signals (or their dependencies) update. This is perfect for handling transient errors in async data.
 
 **Single dependency:**
+
 ```jsx
 {try(user()) {
     // Note: we access .error because it is a asyncSignal() not a normal signal
@@ -334,48 +340,15 @@ You can track multiple signals by listing them using the comma operator. Both si
 Run `fn` whenever the signals it reads change.
 
 ```javascript
-import { signal, effect } from 'round-core';
+import { signal, effect } from "round-core";
 
-const name = signal('Ada');
+const name = signal("Ada");
 
 effect(() => {
-    console.log('Name changed:', name());
+  console.log("Name changed:", name());
 });
 
-name('Grace');
-```
-
-### `asyncSignal(fetcher)`
-
-Create a signal that manages asynchronous data fetching.
-
-- It returns a signal that resolves to the data once fetched.
-- **`.pending`**: A reactive signal (boolean) indicating if the fetch is in progress.
-- **`.error`**: A reactive signal containing any error that occurred during fetching.
-- **`.refetch()`**: A method to manually trigger a re-fetch.
-
-```jsx
-import { asyncSignal } from 'round-core';
-
-const user = asyncSignal(async () => {
-    const res = await fetch('/api/user');
-    return res.json();
-});
-
-export function UserProfile() {
-    return (
-        <div>
-            {if(user.pending()){
-                <div>Loading...</div>
-            } else if(user.error()){
-                <div>Error: {user.error().message}</div>
-            } else {
-                <div>Welcome, {user().name}</div>
-            }}
-            <button onClick={() => user.refetch()}>Reload</button>
-        </div>
-    );
-}
+name("Grace");
 ```
 
 ### `untrack(fn)`
@@ -383,15 +356,15 @@ export function UserProfile() {
 Run a function without tracking any signals it reads.
 
 ```javascript
-import { signal, untrack, effect } from 'round-core';
+import { signal, untrack, effect } from "round-core";
 
 const count = signal(0);
 effect(() => {
-    console.log('Count is:', count());
-    untrack(() => {
-        // This read won't trigger the effect if it changes elsewhere
-        console.log('Static value:', count());
-    });
+  console.log("Count is:", count());
+  untrack(() => {
+    // This read won't trigger the effect if it changes elsewhere
+    console.log("Static value:", count());
+  });
 });
 ```
 
@@ -400,17 +373,17 @@ effect(() => {
 `bindable()` creates a signal intended for **two-way DOM bindings**.
 
 ```jsx
-import { bindable } from 'round-core';
+import { bindable } from "round-core";
 
 export function Example() {
-    const email = bindable('');
+  const email = bindable("");
 
-    return (
-        <div>
-            <input bind:value={email} placeholder="Email" />
-            <div>Typed: {email()}</div>
-        </div>
-    );
+  return (
+    <div>
+      <input bind:value={email} placeholder="Email" />
+      <div>Typed: {email()}</div>
+    </div>
+  );
 }
 ```
 
@@ -428,23 +401,23 @@ Round will warn if the value is not signal-like, and will warn if you bind a pla
 Round supports object-shaped state with ergonomic deep bindings via proxies.
 
 ```jsx
-import { bindable } from 'round-core';
+import { bindable } from "round-core";
 
 export function Profile() {
-    const user = bindable.object({
-        profile: { bio: '' },
-        flags: { newsletter: false }
-    });
+  const user = bindable.object({
+    profile: { bio: "" },
+    flags: { newsletter: false },
+  });
 
-    return (
-        <div>
-            <textarea bind:value={user.profile.bio} />
-            <label>
-                <input type="checkbox" bind:checked={user.flags.newsletter} />
-                Subscribe
-            </label>
-        </div>
-    );
+  return (
+    <div>
+      <textarea bind:value={user.profile.bio} />
+      <label>
+        <input type="checkbox" bind:checked={user.flags.newsletter} />
+        Subscribe
+      </label>
+    </div>
+  );
 }
 ```
 
@@ -460,16 +433,16 @@ const store = createStore({
     todos: [],
     filter: 'all'
 }, {
-    addTodo: (state, text) => ({ 
-        ...state, 
-        todos: [...state.todos, { text, done: false }] 
+    addTodo: (state, text) => ({
+        ...state,
+        todos: [...state.todos, { text, done: false }]
     })
 });
 
 // 2. Use in Component
 export function TodoList() {
     const todos = store.use('todos'); // Returns a bindable signal
-    
+
     return (
         <div>
             {for(todo in todos()){
@@ -481,10 +454,10 @@ export function TodoList() {
 }
 
 // 3. Persistence (Optional)
-store.persist('my-app-store', { 
+store.persist('my-app-store', {
     debounce: 100, // ms
-    exclude: ['someSecretKey'] 
-}); 
+    exclude: ['someSecretKey']
+});
 
 // 4. Advanced Methods
 store.patch({ filter: 'completed' }); // Update multiple keys at once
@@ -502,23 +475,22 @@ Attach validation to a signal/bindable.
 - `options.validateInitial` can trigger validation on startup.
 
 ```jsx
-import { bindable } from 'round-core';
+import { bindable } from "round-core";
 
 export function EmailField() {
-    const email = bindable('')
-        .validate(
-            (v) => v.includes('@') || 'Invalid email',
-            { validateOn: 'blur' }
-        );
+  const email = bindable("").validate(
+    (v) => v.includes("@") || "Invalid email",
+    { validateOn: "blur" }
+  );
 
-    return (
-        <div>
-            <input bind:value={email} placeholder="name@example.com" />
-            <div style={() => ({ color: email.error() ? 'crimson' : '#666' })}>
-                {email.error}
-            </div>
-        </div>
-    );
+  return (
+    <div>
+      <input bind:value={email} placeholder="name@example.com" />
+      <div style={() => ({ color: email.error() ? "crimson" : "#666" })}>
+        {email.error}
+      </div>
+    </div>
+  );
 }
 ```
 
@@ -527,30 +499,34 @@ export function EmailField() {
 Round provides hooks to tap into the lifecycle of components. These must be called during the synchronous execution of your component function.
 
 ### `onMount(fn)`
+
 Runs after the component is first created and its elements are added to the DOM. If `fn` returns a function, it's used as a cleanup (equivalent to `onUnmount`).
 
 ### `onUnmount(fn)`
+
 Runs when the component's elements are removed from the DOM.
 
 ### `onUpdate(fn)`
-Runs whenever any signal read during the component's *initial* render is updated.
+
+Runs whenever any signal read during the component's _initial_ render is updated.
 
 ### `onCleanup(fn)`
+
 Alias for `onUnmount`.
 
 ```jsx
-import { onMount, onUnmount } from 'round-core';
+import { onMount, onUnmount } from "round-core";
 
 export function MyComponent() {
-    onMount(() => {
-        console.log('Mounted!');
-        const timer = setInterval(() => {}, 1000);
-        return () => clearInterval(timer); // Cleanup
-    });
+  onMount(() => {
+    console.log("Mounted!");
+    const timer = setInterval(() => {}, 1000);
+    return () => clearInterval(timer); // Cleanup
+  });
 
-    onUnmount(() => console.log('Goodbye!'));
+  onUnmount(() => console.log("Goodbye!"));
 
-    return <div>Hello</div>;
+  return <div>Hello</div>;
 }
 ```
 
@@ -561,24 +537,24 @@ Round includes router primitives intended for SPA navigation. All route paths mu
 ### Basic Usage
 
 ```jsx
-import { Route, Link } from 'round-core';
+import { Route, Link } from "round-core";
 
 export default function App() {
-    return (
-        <div>
-            <nav>
-                <Link href="/">Home</Link>
-                <Link href="/about">About</Link>
-            </nav>
-
-            <Route route="/" title="Home" exact>
-                <div>Welcome Home</div>
-            </Route>
-            <Route route="/about" title="About">
-                <div>About Us Content</div>
-            </Route>
-        </div>
-    );
+  return (
+    <div>
+      <nav>
+        <Link href="/">Home</Link>
+        <Link href="/about">About</Link>
+      </nav>
+
+      <Route route="/" title="Home" exact>
+        <div>Welcome Home</div>
+      </Route>
+      <Route route="/about" title="About">
+        <div>About Us Content</div>
+      </Route>
+    </div>
+  );
 }
 ```
 
@@ -591,33 +567,128 @@ Routes can be nested to create hierarchical layouts. Child routes automatically
 
 ```jsx
 <Route route="/dashboard" title="Dashboard">
-    <h1>Dashboard Shell</h1>
+  <h1>Dashboard Shell</h1>
+
+  {/* This route matches /dashboard/profile */}
+  <Route route="/dashboard/profile">
+    <h2>User Profile</h2>
+  </Route>
+
+  {/* This route matches /dashboard/settings */}
+  <Route route="/dashboard/settings">
+    <h2>Settings</h2>
+  </Route>
+</Route>
+```
+
+### Routing Memoization (Keep-Alive)
+
+Round allows you to **persist the state and DOM nodes** of a route even when you navigate away. This is perfect for maintaining the state of a complex list or preserving the state of a multi-step form.
+
+When `memo` is set to `true`, the route's DOM nodes are hidden using `display: none` instead of being removed. This ensures that:
 
-    {/* This route matches /dashboard/profile */}
-    <Route route="/dashboard/profile">
-        <h2>User Profile</h2>
-    </Route>
+- **Signals and local state** are preserved.
+- **CSS Transitions and Animations** don't reset.
+- **Form inputs** maintain their value and focus.
 
-    {/* This route matches /dashboard/settings */}
-    <Route route="/dashboard/settings">
-        <h2>Settings</h2>
-    </Route>
+```jsx
+<Route route="/explore" memo={true}>
+  <ExploreFeed />
 </Route>
 ```
 
+> [!TIP]
+> This works even if the `Route` component itself is unmounted and remounted (e.g., within an `if` block), as Round maintains a global persistence cache for memoized routes.
+
 ## Suspense and lazy loading
 
 Round supports `Suspense` for promise-based rendering and `lazy()` for code splitting.
 
 ```jsx
-import { Suspense, lazy } from 'round-core';
-const LazyWidget = lazy(() => import('./Widget'));
+import { Suspense, lazy } from "round-core";
+const LazyWidget = lazy(() => import("./Widget"));
 
 <Suspense fallback={<div>Loading...</div>}>
-    <LazyWidget />
-</Suspense>
+  <LazyWidget />
+</Suspense>;
+```
+
+## Markdown rendering with `@round-core/markdown`
+
+Round includes an optional companion package for markdown rendering with
+syntax highlighting and rich code blocks.
+
+Install it alongside `round-core`:
+
+```bash
+npm install @round-core/markdown
 ```
 
+or with Bun:
+
+```bash
+bun add @round-core/markdown
+```
+
+Then use it in a `.round` file or JSX component:
+
+```jsx
+import { createElement } from "round-core";
+import {
+  Markdown,
+  defaultMarkdownStyles as markdown,
+} from "@round-core/markdown";
+import "@round-core/markdown/styles.css";
+
+export default function App() {
+  const content = `
+# Markdown with code blocks
+
+You can render fenced code blocks with syntax highlighting:
+
+\`\`\`javascript
+const value = signal(0);
+\`\`\`
+`;
+
+  return (
+    <div>
+      <Markdown content={content} />
+    </div>
+  );
+}
+```
+
+You can also theme the markdown surface (background/text) and accents via
+`options.theme`:
+
+```jsx
+<Markdown
+  content={content}
+  options={{
+    theme: {
+      // Dark card-like surface
+      markdownBackground: '#020617',
+      markdownText: '#e5e7eb',
+      primaryColor: '#e5e7eb',
+      secondaryColor: '#38bdf8',
+    },
+  }}
+/>
+
+<Markdown
+  content={content}
+  options={{
+    theme: {
+      // Light mode
+      markdownBackground: '#ffffff',
+      markdownText: '#0f172a',
+      primaryColor: '#0f172a',
+      secondaryColor: '#2563eb',
+    },
+  }}
+/>
+```
 
 ## Error handling
 
@@ -641,13 +712,6 @@ The CLI is intended for day-to-day development:
 
 Run `round -h` to see available commands.
 
-## 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.

package/package.json

@@ -1,54 +1,57 @@
-{
-    "name": "round-core",
-    "version": "0.2.0",
-    "description": "A lightweight frontend framework for SPA with signals and fine grained reactivity",
-    "main": "./src/index.js",
-    "types": "./src/index.d.ts",
-    "readme": "README.md",
-    "exports": {
-        ".": {
-            "types": "./src/index.d.ts",
-            "default": "./src/index.js"
-        },
-        "./vite-plugin": {
-            "types": "./src/compiler/vite-plugin.d.ts",
-            "default": "./src/compiler/vite-plugin.js"
-        }
-    },
-    "files": [
-        "src",
-        "README.md",
-        "LICENSE"
-    ],
-    "type": "module",
-    "icon": "Round.png",
-    "repository": {
-        "url": "https://github.com/ZtaMDev/RoundJS.git"
-    },
-    "bin": {
-        "round": "./src/cli.js"
-    },
-    "scripts": {
-        "dev": "node ./src/cli.js dev --config ./test/main/round.config.json",
-        "build": "node ./src/cli.js build --config ./test/main/round.config.json",
-        "bench": "bun run --cwd benchmarks bench",
-        "bench:build": "bun run --cwd benchmarks bench:build",
-        "bench:runtime": "bun run --cwd benchmarks bench:runtime"
-    },
-    "keywords": [
-        "framework",
-        "spa",
-        "signals",
-        "vite"
-    ],
-    "author": "Round Framework Team",
-    "license": "MIT",
-    "dependencies": {
-        "vite": "^5.0.0"
-    },
-    "devDependencies": {
-        "@types/node": "latest",
-        "bun-types": "latest",
-        "vitest": "^1.6.0"
-    }
-}
+{
+    "name": "round-core",
+    "version": "0.2.2",
+    "description": "A lightweight frontend framework for SPA with signals and fine grained reactivity",
+    "workspaces": [
+        "packages/*"
+    ],
+    "main": "./src/index.js",
+    "types": "./src/index.d.ts",
+    "readme": "README.md",
+    "exports": {
+        ".": {
+            "types": "./src/index.d.ts",
+            "default": "./src/index.js"
+        },
+        "./vite-plugin": {
+            "types": "./src/compiler/vite-plugin.d.ts",
+            "default": "./src/compiler/vite-plugin.js"
+        }
+    },
+    "files": [
+        "src",
+        "README.md",
+        "LICENSE"
+    ],
+    "type": "module",
+    "icon": "Round.png",
+    "repository": {
+        "url": "https://github.com/ZtaMDev/RoundJS.git"
+    },
+    "bin": {
+        "round": "./src/cli.js"
+    },
+    "scripts": {
+        "bench": "bun run --cwd benchmarks bench",
+        "bench:build": "bun run --cwd benchmarks bench:build",
+        "bench:runtime": "bun run --cwd benchmarks bench:runtime"
+    },
+    "keywords": [
+        "framework",
+        "spa",
+        "signals",
+        "vite"
+    ],
+    "author": "Round Framework Team",
+    "license": "MIT",
+    "dependencies": {
+        "vite": "^5.0.0"
+    },
+    "devDependencies": {
+        "@types/node": "latest",
+        "bun-types": "latest",
+        "eslint": "^9.39.2",
+        "prettier": "^3.7.4",
+        "vitest": "^1.6.0"
+    }
+}

package/src/cli.js

@@ -211,15 +211,33 @@ async function runInit({ name }) {
 
     const projectDir = path.resolve(process.cwd(), name);
     const srcDir = path.join(projectDir, 'src');
-
-    ensureDir(srcDir);
-
+    const vscodeDir = path.join(projectDir, '.vscode');
+    const vscodeSettingsPath = path.join(vscodeDir, 'settings.json');
     const pkgPath = path.join(projectDir, 'package.json');
     const configPath = path.join(projectDir, 'round.config.json');
     const viteConfigPath = path.join(projectDir, 'vite.config.js');
+    const prettierConfigPath = path.join(projectDir, '.prettierrc');
+    const eslintConfigPath = path.join(projectDir, 'eslint.config.js');
     const appRoundPath = path.join(srcDir, 'app.round');
     const counterRoundPath = path.join(srcDir, 'counter.round');
 
+    ensureDir(srcDir);
+    ensureDir(vscodeDir);
+
+    writeFileIfMissing(vscodeSettingsPath, JSON.stringify({
+        "eslint.validate": [
+            "javascript",
+            "javascriptreact",
+            "round"
+        ],
+        "prettier.documentSelectors": [
+            "**/*.round"
+        ],
+        "[round]": {
+            "editor.defaultFormatter": "esbenp.prettier-vscode"
+        }
+    }, null, 4) + '\n');
+
     writeFileIfMissing(pkgPath, JSON.stringify({
         name,
         private: true,
@@ -228,16 +246,71 @@ async function runInit({ name }) {
         scripts: {
             dev: 'round dev',
             build: 'round build',
-            preview: 'round preview'
+            preview: 'round preview',
+            lint: 'eslint src',
+            format: 'prettier --write src'
         },
         dependencies: {
-            'round-core': '^0.1.9'
+            'round-core': '^' + getRoundVersion(),
+            '@round-core/shared': '^1.0.0'
         },
         devDependencies: {
-            vite: '^5.0.0'
+            '@round-core/lint': '^0.1.0',
+            '@round-core/prettier': '^0.1.0',
+            'eslint': '^9.39.2',
+            'espree': '^10.0.0',
+            'globals': '^17.0.0',
+            'prettier': '^3.7.4',
+            'vite': '^5.0.0'
         }
     }, null, 4) + '\n');
 
+    writeFileIfMissing(prettierConfigPath, JSON.stringify({
+        plugins: ["@round-core/prettier"],
+        overrides: [
+            {
+                files: "*.round",
+                options: {
+                    parser: "round"
+                }
+            }
+        ]
+    }, null, 4) + '\n');
+
+    const eslintConfigContent = `import lintPlugin from '@round-core/lint';
+import globals from 'globals';
+import * as espree from 'espree';
+
+export default [
+    {
+        files: ["**/*.round"],
+        plugins: {
+            '@round-core/lint': lintPlugin
+        },
+        processor: lintPlugin.processors['.round'],
+        rules: {
+            "no-unused-vars": "warn",
+            "no-undef": "error"
+        },
+        languageOptions: {
+            parser: espree,
+            ecmaVersion: "latest",
+            sourceType: "module",
+            globals: {
+                ...globals.browser,
+                ...globals.node,
+            },
+            parserOptions: {
+                ecmaFeatures: {
+                    jsx: true
+                }
+            }
+        }
+    }
+];
+`;
+    writeFileIfMissing(eslintConfigPath, eslintConfigContent);
+
     writeFileIfMissing(configPath, JSON.stringify({
         mode,
         entry: './src/app.round',

package/src/index.d.ts

@@ -282,8 +282,21 @@ export interface RouteProps {
     title?: string;
     /** Meta description to set in the document header when active. */
     description?: string;
-    /** Advanced head configuration including links and meta tags. */
-    head?: any;
+    /** If true, the route stays rendered (hidden) when not active. Preserves state. */
+    memo?: boolean;
+    /** Meta tags to set in the document header when active. */
+    meta?: any;
+    /** Advanced head configuration including links and icons. */
+    head?: { 
+        /** Title of the page. */
+        title?: string;
+        /** Links to include in the head. */
+        links?: string;
+        /** Icon to include in the head. */
+        icon?: string;
+        /** Favicon to include in the head. */
+        favicon?: string;
+    };
     /** Component or elements to render when matched. */
     children?: any;
 }
@@ -441,4 +454,15 @@ export function Suspense(props: SuspenseProps): any;
 /**
  * Defines static head metadata (titles, meta tags, etc.).
  */
-export function startHead(head: any): any;
+export function startHead(head: any): any;
+
+
+/**
+ * Raises an error to be handled by the runtime.
+ * Use cases:
+ * - Throwing errors in reactive functions
+ * - Throwing errors in try catch JSX statements
+ * 
+ * @param error - The error to raise.
+ */
+export function raise(error: any): never;

package/src/index.js

@@ -14,7 +14,8 @@ import * as Router from './runtime/router.js';
 import * as Suspense from './runtime/suspense.js';
 import * as Context from './runtime/context.js';
 import * as Store from './runtime/store.js';
-
+import { raise } from './runtime/errors.js';
+export { raise } from './runtime/errors.js';
 export function render(Component, container) {
     Lifecycle.initLifecycleRoot(container);
     // Errors are no longer handled by a global overlay.
@@ -31,5 +32,6 @@ export default {
     ...Suspense,
     ...Context,
     ...Store,
-    render
+    render,
+    raise
 };

package/src/runtime/dom.js

@@ -67,8 +67,11 @@ export function createElement(tag, props = {}, ...children) {
         }
 
         if (node instanceof Node) {
-            node._componentInstance = componentInstance;
-            componentInstance.nodes.push(node);
+            // Only set the instance if not already present (supports memoization/persistence)
+            if (!node._componentInstance) {
+                node._componentInstance = componentInstance;
+                componentInstance.nodes.push(node);
+            }
 
             componentInstance.mountTimerId = setTimeout(() => {
                 componentInstance.mountTimerId = null;

package/src/runtime/errors.js

@@ -150,3 +150,7 @@ export function initErrorHandling(container) {
         });
     }
 }
+
+export function raise(error) {
+    throw error;
+}

package/src/runtime/lifecycle.js

@@ -116,6 +116,7 @@ const observer = (typeof MutationObserver !== 'undefined')
         mutations.forEach(mutation => {
             if (mutation.removedNodes.length > 0) {
                 mutation.removedNodes.forEach(node => {
+                    if (node._roundKeepAlive) return;
                     if (node._componentInstance) {
                         unmountComponent(node._componentInstance);
                     }
@@ -127,6 +128,7 @@ const observer = (typeof MutationObserver !== 'undefined')
     : null;
 
 function cleanupNodeRecursively(node) {
+    if (node._roundKeepAlive) return;
     if (node._componentInstance) {
         unmountComponent(node._componentInstance);
     }

package/src/runtime/router.js

@@ -1,4 +1,4 @@
-import { signal, effect } from './signals.js';
+import { signal, effect, batch } from './signals.js';
 import { createElement } from './dom.js';
 import { createContext, readContext } from './context.js';
 
@@ -26,6 +26,7 @@ let autoNotFoundMounted = false;
 let userProvidedNotFound = false;
 
 const RoutingContext = createContext('');
+const routeMemoCache = new Map();
 
 function ensureListener() {
     if (!hasWindow || listenerInitialized) return;
@@ -99,19 +100,31 @@ export function useRouteReady() {
 export function getIsNotFound() {
     const pathname = normalizePathname(currentPath());
     if (pathname === '/') return false;
-    return !Boolean(pathHasMatch());
+    if (pathHasMatch()) return false;
+    if (!pathEvalReady()) return false;
+    return true;
 }
 
 export function useIsNotFound() {
     return () => {
         const pathname = normalizePathname(currentPath());
         if (pathname === '/') return false;
-        // Mirror getIsNotFound: react immediately to the current path and
-        // the latest match flag, instead of waiting for pathEvalReady.
-        return !Boolean(pathHasMatch());
+        if (pathHasMatch()) return false;
+        if (!pathEvalReady()) return false;
+        return true;
     };
 }
 
+// Global effect to trigger path evaluation whenever the path changes.
+// This ensures that pathEvalReady and pathHasMatch are managed centrally.
+effect(() => {
+    const pathname = normalizePathname(currentPath());
+    beginPathEvaluation(pathname);
+}, { onLoad: false }); // We run it manually once below
+
+// Initialize synchronous evaluation for the starting path.
+beginPathEvaluation(normalizePathname(currentPath.peek()));
+
 function mountAutoNotFound() {
     if (!hasWindow || autoNotFoundMounted) return;
     autoNotFoundMounted = true;
@@ -290,11 +303,13 @@ function matchRoute(route, pathname, exact = true) {
 
 function beginPathEvaluation(pathname) {
     if (pathname !== lastPathEvaluated) {
-        lastPathEvaluated = pathname;
-        hasMatchForPath = false;
-        pathHasMatch(false);
+        batch(() => {
+            lastPathEvaluated = pathname;
+            hasMatchForPath = false;
+            pathEvalReady(false);
+            pathHasMatch(false);
+        });
 
-        pathEvalReady(false);
         setTimeout(() => {
             if (lastPathEvaluated !== pathname) return;
             pathEvalReady(true);
@@ -314,6 +329,11 @@ export function setNotFound(Component) {
  * @param {string} [props.title] Page title to set when active.
  * @param {string} [props.description] Meta description to set when active.
  * @param {any} [props.children] Content to render.
+ * @param {object} [props.head] Advanced head configuration including links and meta tags.
+ * @param {string} [props.head.title] Title of the page.
+ * @param {string} [props.head.links] Links to include in the head.
+ * @param {string} [props.head.icon] Icon to include in the head.
+ * @param {string} [props.head.favicon] Favicon to include in the head.
  */
 export function Route(props = {}) {
     ensureListener();
@@ -321,7 +341,6 @@ export function Route(props = {}) {
     return createElement('span', { style: { display: 'contents' } }, () => {
         const parentPath = readContext(RoutingContext) || '';
         const pathname = normalizePathname(currentPath());
-        beginPathEvaluation(pathname);
 
         const routeProp = props.route ?? '/';
         if (typeof routeProp === 'string' && !routeProp.startsWith('/')) {
@@ -344,9 +363,45 @@ export function Route(props = {}) {
 
         const isRoot = fullRoute === '/';
         const exact = props.exact !== undefined ? Boolean(props.exact) : isRoot;
+        const isMatch = matchRoute(fullRoute, pathname, exact);
+
+        if (props.memo) {
+            if (isMatch) {
+                if (matchRoute(fullRoute, pathname, true)) {
+                    hasMatchForPath = true;
+                    pathHasMatch(true);
+                }
+
+                const mergedHead = (props.head && typeof props.head === 'object') ? props.head : {};
+                const meta = props.description
+                    ? ([{ name: 'description', content: String(props.description) }].concat(mergedHead.meta ?? props.meta ?? []))
+                    : (mergedHead.meta ?? props.meta);
+                const links = mergedHead.links ?? props.links;
+                const title = mergedHead.title ?? props.title;
+                const icon = mergedHead.icon ?? props.icon;
+                const favicon = mergedHead.favicon ?? props.favicon;
+
+                applyHead({ title, meta, links, icon, favicon });
+            }
+
+            if (routeMemoCache.has(fullRoute)) {
+                const cached = routeMemoCache.get(fullRoute);
+                cached.style.display = isMatch ? 'contents' : 'none';
+                return cached;
+            }
+
+            if (!isMatch) return null;
+
+            const memoContainer = createElement('div', { style: { display: 'contents' } },
+                createElement(RoutingContext.Provider, { value: fullRoute }, props.children)
+            );
+            memoContainer._roundKeepAlive = true;
+            routeMemoCache.set(fullRoute, memoContainer);
+            return memoContainer;
+        }
 
         // For nested routing, we match as a prefix so parents stay rendered while children are active
-        if (!matchRoute(fullRoute, pathname, exact)) return null;
+        if (!isMatch) return null;
 
         // If it's an exact match of the FULL segments, mark as matched for 404 purposes
         if (matchRoute(fullRoute, pathname, true)) {
@@ -375,55 +430,7 @@ export function Route(props = {}) {
  * @param {object} props Page properties (same as Route).
  */
 export function Page(props = {}) {
-    ensureListener();
-
-    return createElement('span', { style: { display: 'contents' } }, () => {
-        const parentPath = readContext(RoutingContext) || '';
-        const pathname = normalizePathname(currentPath());
-        beginPathEvaluation(pathname);
-
-        const routeProp = props.route ?? '/';
-        if (typeof routeProp === 'string' && !routeProp.startsWith('/')) {
-            throw new Error(`Invalid route: "${routeProp}". All routes must start with a forward slash "/". (Nested under: "${parentPath || 'root'}")`);
-        }
-
-        let fullRoute = '';
-        if (parentPath && parentPath !== '/') {
-            const cleanParent = parentPath.endsWith('/') ? parentPath.slice(0, -1) : parentPath;
-            const cleanChild = routeProp.startsWith('/') ? routeProp : '/' + routeProp;
-
-            if (cleanChild.startsWith(cleanParent + '/') || cleanChild === cleanParent) {
-                fullRoute = normalizePathname(cleanChild);
-            } else {
-                fullRoute = normalizePathname(cleanParent + cleanChild);
-            }
-        } else {
-            fullRoute = normalizePathname(routeProp);
-        }
-
-        const isRoot = fullRoute === '/';
-        const exact = props.exact !== undefined ? Boolean(props.exact) : isRoot;
-
-        if (!matchRoute(fullRoute, pathname, exact)) return null;
-
-        if (matchRoute(fullRoute, pathname, true)) {
-            hasMatchForPath = true;
-            pathHasMatch(true);
-        }
-
-        const mergedHead = (props.head && typeof props.head === 'object') ? props.head : {};
-        const meta = props.description
-            ? ([{ name: 'description', content: String(props.description) }].concat(mergedHead.meta ?? props.meta ?? []))
-            : (mergedHead.meta ?? props.meta);
-        const links = mergedHead.links ?? props.links;
-        const title = mergedHead.title ?? props.title;
-        const icon = mergedHead.icon ?? props.icon;
-        const favicon = mergedHead.favicon ?? props.favicon;
-
-        applyHead({ title, meta, links, icon, favicon });
-
-        return createElement(RoutingContext.Provider, { value: fullRoute }, props.children);
-    });
+    return Route(props);
 }
 
 /**
@@ -436,7 +443,6 @@ export function NotFound(props = {}) {
 
     return createElement('span', { style: { display: 'contents' } }, () => {
         const pathname = normalizePathname(currentPath());
-        beginPathEvaluation(pathname);
 
         const ready = pathEvalReady();
         const hasMatch = pathHasMatch();