npm - lego-dom - Versions diffs - 0.0.9 → 1.0.0 - Mend

lego-dom 0.0.9 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (166) hide show

package/CHANGELOG.md ADDED Viewed

@@ -0,0 +1,44 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+## [1.0.0] - 2026-01-10
+**The Launch Release!** 🚀
+LegoDOM moves out of beta with a finalized API, robust routing, and a hybrid rendering engine.
+### 🌟 Major features
+- **Surgical Routing:** Introduced a groundbreaking `b-target` attribute that allows any link to update any part of the page without a full reload.
+    - **Smart History:** The router now tracks surgical updates in `history.state`, correctly restoring "fragment" states when using the Back/Forward buttons.
+    - **Persistent Layouts:** Support for "Holy Grail" layouts where sidebars never reload or lose state (scroll position, inputs) while main content changes.
+- **Hybrid Rendering Engine:**
+    - **Light DOM Support:** The engine now hydrates `{{mustaches}}` in `index.html` and Light DOM slots, not just inside Shadow Roots.
+    - **Global Reactivity:** Components now automatically broadcast global state changes (like URL params) to all active subscribers.
+    - **Optimized Updates:** A dependency tracking system ensures only components that *use* global state are re-rendered.
+- **Developer Experience (DX):**
+    - **Automatic Injection:** `$route` and `$go` are now injected into every component's script scope (`this.$route`, `this.$go`), removing the need for `Lego.globals.xxx`.
+    - **Cleaner Templates:** Template expressions now support `$route` directly (`{{ $route.params.id }}`) without `global.` prefix.
+    - **HMR 2.0:** The Vite plugin now correctly handles adding/deleting `.lego` files and performs smarter hot updates.
+### ⚡ Improvements
+- **Router:**
+    - Exposed `$go(path, ...targets).get()` for programmatic surgical navigation.
+    - Fixed `TypeError` where `$go` was not found in component scopes.
+    - Support for multiple URL parameters (e.g., `/customers/:id/orders/:orderId`).
+    - Defaults `b-link` to `true` (always push history) unless explicitly set to `false`.
+- **Core:**
+    - `Lego.init()` is now required to start the engine, allowing for explicit control over startup timing.
+    - `e.composedPath()` is used for event delegation, allowing links inside Shadow DOM to trigger the global router.
+    - Fixed `b-sync` losing reactivity inside `b-for` loops.
+    - Fixed hydration of attributes like `href="/user/{{id}}"`.
+- **Docs:**
+    - Complete overhaul of Routing guide with "Surgical Swaps", "Deep Linking", and "Self-Healing" patterns.
+    - Clarified component naming conventions (Filename for Vite vs. `b-id` for CDN).
+### 🐛 Bug Fixes
+- Fixed "Literal Mustaches" appearing in `href` and text content on initial load.
+- Fixed Deep Linking where hitting Refresh on a sub-route would render an empty shell (addressed via Self-Healing pattern).
+- Fixed an issue where `Lego.globals` changes triggered a full re-render of unrelated components.

package/README.md CHANGED Viewed

@@ -14,6 +14,7 @@ Lego embraces the web platform. It turns standard HTML `<template>` tags into re
 - 📦 **Zero Dependencies** – Weighs less than 4kb gzipped.
 - 🛠️ **No Build Step** – Works directly in the browser with standard `<script>` tags.
 - 🧩 **Native Web Components** – Real Custom Elements, real Shadow DOM.
+- 🌐 **Built-in Routing** – Lego Router included for client-side routing.
 - 📝 **Familiar Mentals** – Plain JavaScript objects for state, plain HTML for templates.
 ---

package/{go.html → cdn.html} RENAMED Viewed

@@ -8,7 +8,14 @@
 </head>
 <body @todo-added="() => {console.log('Todo added!')}">
-  <template b-id="todo-list">
+  <template b-id="todo-list" b-data="{
+      title: 'My Todo List',
+      items: [],
+      newItem: '',
+      mounted() {
+        console.log('Todo list mounted!');
+      }
+    }">
     <style>
       :host {
         display: block;
@@ -52,14 +59,13 @@
     <h3>{{title}}</h3>
     <p>{{ items.filter(t => !t.done).length }} of {{ items.length }} items remaining</p>
     <div style="margin-bottom: 20px;">
-      <input b-sync="newItem" placeholder="Add task..." class="input" @keydown="() => {
-        }">
+      <input b-sync="newItem" placeholder="Add task..." class="input">
       <button @click="() => {
-          if(!newItem.trim()) return;
-          items.push({text: `${newItem} - ${items.length + 1} - ${$ancestors('user-card').name}`, done: false});
-          newItem = '';
-          $emit('todo-added', { item: newItem });
-        }">Add</button>
+            if(!newItem.trim()) return;
+            items.push({text: `${newItem} - ${items.length + 1}`, done: false});
+            newItem = '';
+            $emit('todo-added', { item: newItem });
+          }">Add</button>
     </div>
     <div b-for="todo in items">
@@ -70,7 +76,10 @@
     </div>
   </template>
-  <template b-id="user-card">
+  <template b-id="user-card" b-data="{
+      name: 'Anonymous',
+      bio: 'No bio provided'
+    }">
     <style>
       :host {
         display: block;
@@ -78,6 +87,7 @@
         padding: 20px;
         border: 1px solid #ccc;
         border-radius: 8px;
+        margin-bottom: 20px;
       }
       h3 {
@@ -91,25 +101,22 @@
     <slot></slot>
   </template>
+  <!-- Using defaults -->
+  <user-card>
+    <p>This user uses default data from the template.</p>
+  </user-card>
+  <!-- Overriding defaults -->
   <user-card b-data="{
-      name: 'John Doe',
-      bio: 'Software Engineer'
-    }">
-    <p>Additional content here</p>
-    <todo-list b-data="{
-        title: 'Enterprise Todo List',
-        items: [{text: 'Fix b-for strikethrough', done: true}],
-        newItem: '',
-        mounted() {
-          console.log('THis lego block has been mounted!');
-        },
-        updated() {
-          console.log('This lego block has been updated!');
-        },
-        unmounted() {
-          console.log('This lego block has been unmounted!');
-        }
+        name: 'John Doe',
+        bio: 'Software Engineer'
       }">
+    <p>This user overrides the defaults.</p>
+    <todo-list b-data="{
+          title: 'Work Tasks',
+          items: [{text: 'Implement template defaults', done: true}]
+        }">
     </todo-list>
   </user-card>
 </body>

package/docs/.vitepress/config.js CHANGED Viewed

@@ -10,10 +10,12 @@ export default defineConfig({
     nav: [
       { text: 'Guide', link: '/guide/' },
+      { text: 'Contributing', link: '/contributing/' },
       { text: 'API', link: '/api/' },
       { text: 'Examples', link: '/examples/' },
+      { text: 'Router', link: '/router/' },
       {
-        text: 'v0.0.7',
+        text: 'v1.0.0',
         items: [
           { text: 'Changelog', link: 'https://github.com/rayattack/LegoJS/releases' }
@@ -22,6 +24,30 @@ export default defineConfig({
     ],
     sidebar: {
+      '/contributing/': [
+        {
+          text: 'Contributing',
+          items: [
+            { text: 'Topic 1 - Welcome', link: '/contributing/01-welcome' },
+            { text: 'Topic 2 - The Registry', link: '/contributing/02-registry' },
+            { text: 'Topic 3 - Batching', link: '/contributing/03-batcher' },
+            { text: 'Topic 4 - Reactivity', link: '/contributing/04-reactivity' },
+            { text: 'Topic 5 - Caching', link: '/contributing/05-caching' },
+            { text: 'Topic 6 - LegoDOM Init', link: '/contributing/06-init' },
+            { text: 'Topic 7 - Observer', link: '/contributing/07-observer' },
+            { text: 'Topic 8 - Snap', link: '/contributing/08-snap' },
+            { text: 'Topic 9 - Diffing', link: '/contributing/09-diffing' },
+            { text: 'Topic 10 - State', 'link': '/contributing/10-studs' },
+            { text: 'Topic 11 - Scanner', 'link': '/contributing/11-scanner' },
+            { text: 'Topic 12 - Render', 'link': '/contributing/12-render' },
+            { text: 'Topic 13 - Directives', 'link': '/contributing/13-directives' },
+            { text: 'Topic 14 - Events', 'link': '/contributing/14-events' },
+            { text: 'Topic 15 - Router', 'link': '/contributing/15-router' },
+            { text: 'Topic 16 - State', 'link': '/contributing/16-state' },
+            { text: 'Topic 17 - LegoDOM', 'link': '/contributing/17-legodom' },
+          ]
+        }
+      ],
       '/guide/': [
         {
           text: 'Introduction',
@@ -65,6 +91,18 @@ export default defineConfig({
           ]
         }
       ],
+      '/router/': [
+        {
+          text: 'LegoDOM Router',
+          items: [
+            { text: 'About', link: '/router/' },
+            { text: 'Basic Routing', link: '/router/basic-routing' },
+            { text: 'Surgical Swaps', link: '/router/surgical-swaps' },
+            { text: 'Cold Entry', link: '/router/cold-entry' },
+            { text: 'History', link: '/router/history' }
+          ]
+        }
+      ],
       '/examples/': [
         {
           text: 'Examples',

package/docs/api/directives.md CHANGED Viewed

@@ -2,13 +2,13 @@
 Special attributes that control DOM behavior.
-## b-if
+## b-show
 Conditionally render an element.
 ```html
-<div b-if="loading">Loading...</div>
-<div b-if="!loading">Content loaded!</div>
+<div b-show="loading">Loading...</div>
+<div b-show="!loading">Content loaded!</div>
 ```
 ## b-for

package/docs/api/index.md CHANGED Viewed

@@ -11,7 +11,7 @@ Welcome to the Lego API documentation.
 ## Templates & Binding
-- [Directives](/api/directives) - `b-if`, `b-for`, `b-sync`
+- [Directives](/api/directives) - `b-show`, `b-for`, `b-sync`
 ## Browser Support

package/docs/contributing/01-welcome.md ADDED Viewed

@@ -0,0 +1,36 @@
+# Topic 1: The Module Pattern & Private Scope
+LegoDOM is wrapped in an **IIFE** (Immediately Invoked Function Expression) assigned to `const Lego`. This creates a closure, meaning any variable declared at the top (like `registry` or `proxyCache`) is "private"—it cannot be accessed or tampered with from the browser console unless explicitly exposed.
+```js
+const Lego = (() => {
+  // ... all the logic ...
+  return {
+    init: () => { ... },
+    define: (tagName, templateHTML, logic = {}) => { ... },
+    // ...
+  };
+})();
+if (typeof window !== 'undefined') {
+  document.addEventListener('DOMContentLoaded', Lego.init);
+  window.Lego = Lego;
+}
+```
+### Why Not Modular ES6?
+I started with an **IIFE** and underestimated how big it could grow. It might be a better idea to use ES6 modules, but I'm too lazy to refactor it at the moment.
+### The use of `WeakMap`
+You’ll notice the use of `WeakMap` for `proxyCache`, `privateData`, and `forPools`.
+-   **Why not a regular Map?** A `WeakMap` allows the keys (which are DOM elements in this code) to be **garbage collected** if the element is removed from the DOM.
+-   **Memory Leak Prevention:** If we used a regular `Map`, the library would hold a reference to every component ever created, even if you deleted them, eventually crashing the browser tab.
+### Internal Registry
+`const registry = {}` acts as the library's "brain." It stores the `<template>` elements that define what a component looks like. When you write `<my-button>`, Lego looks into this object to find the blueprint.

package/docs/contributing/02-registry.md ADDED Viewed

@@ -0,0 +1,99 @@
+# The Good Ole Registry (Lego Basket)
+Let's not keep our toys everywhere, let's be good citizens and put them in a basket.
+PSS!!! Come here lemme tell you a secret - are you a frontend developer? "The DOM is not your enemy"
+we talk about Light DOM and Shadow DOM in a minute ;-).
+## Topic 2: The Registry & Internal Storage
+LegoDOM uses three specialized collections to store the "DNA" of your application. This separation allows the framework to distinguish between what a component **looks like** versus how it **behaves**.
+```js
+const registry = {};
+const sfcLogic = new Map();
+const sharedStates = new Map();
+```
+### 1. The HTML Blueprint Collection (`registry`)
+`const registry = {}` is a plain object that stores references to `<template>` elements.
+-   When the library initializes, it scans the DOM for any `<template b-id="my-component">` and saves it here.
+-   The `b-id` becomes the key, and the DOM node itself is the value.
+-   **Purpose:** This is the "Light DOM" source used to populate the "Shadow DOM" later during the "snapping" process.
+### 2. The SFC Logic Collection (`sfcLogic`)
+`const sfcLogic = new Map();` stores the JavaScript objects passed into `Lego.define()`.
+-   While `registry` holds the HTML/CSS, `sfcLogic` holds the functions like `mounted()`, `updated()`, or custom methods.
+-   **Why a Map?** Unlike a plain object, a `Map` is more performant for frequent lookups by string keys (tag names) - I think!!! or maybe I read wrong (call me out).
+### 3. The Singleton States Collection (`sharedStates`)
+`const sharedStates = new Map();` is one of the most powerful "hidden" features of LegoDOM.
+-   Every time you define a component, Lego creates a **reactive version** of its logic and stores it here.
+-   This allows other components to access a specific component's state globally via the `$registry('tag-name')` helper. **NOTE** the component's (template/blueprint) state, not the instance state.
+-   **Example:** If you have 3 `user-profile` components, any other component on the page can peek at their (shared) state data by asking the `sharedStates` map.
+#### Dissecting Registration
+The `registry` doesn't just wait for you to type; it's fed by three distinct streams across 2 paradigms.
+**Paradigm 1: Explicitly**
+```js
+const sfcLogic = new Map(); // Specifically for SFC script logic
+// ...
+define: (tagName, templateHTML, logic = {}) => {
+  const t = document.createElement('template');
+  // ... stores template in registry
+  sfcLogic.set(tagName, logic); // Stores the JS part separately
+}
+```
+**Paradigm 2: Implicitly**
+```js
+// vite-plugin.js
+async buildStart() {
+  const root = config?.root || process.cwd();
+  legoFiles = await fg(include, { cwd: searchPath, absolute: true }); // Scans for .lego files
+}
+// ...
+async load(id) {
+  if (id.endsWith('.lego')) {
+    const defineCall = generateDefineCall(parsed); // Converts .lego file to Lego.define()
+    return `import { Lego } from 'lego-dom/main.js';\n${defineCall}`;
+  }
+}
+```
+**The Three Ways to Register:**
+1.  **The HTML Manual Method:** You put `<template b-id="my-comp">` directly in your `*.html` files. During `Lego.init()`, the library scrapes these and populates the registry. This is great for "no-build" prototypes.
+2.  **The `Lego.define()` JS Method:** You call `Lego.define('my-comp', '<h1>Hi</h1>', { ... logic })` in a standard JavaScript file.
+3.  **The SFC Automatic Method (The "Vite Way"):** * The **Vite Plugin** (as seen in `vite-plugin.js`) acts as a build-time robot.
+    -   It uses `fast-glob` (`fg`) to scan your entire `src/components` directory for any file ending in `.lego`.
+    -   It parses the `<template>` and `<script>` inside that `.lego` file.
+    -   It **injects** a `Lego.define()` call into your JavaScript bundle automatically.
+    -   **Result:** You just create a file named `UserCard.lego`, and suddenly `<user-card>` is a valid HTML tag in your app.
+**Key Insight:** Notice in `main.js` how `define` uses `sfcLogic.set(tagName, logic)`. This is where the plugin "parks" your component's JavaScript code so that when the component "snaps" (Topic 23), it can find its specific logic.

package/docs/contributing/03-batcher.md ADDED Viewed

@@ -0,0 +1,110 @@
+# Batching, Scheduling, and doing things the right way
+Say you are building the next big thing, if you update checkboxes, input fields a 100 times,
+you don't want the DOM to re-render 100 times. That would be a performance nightmare.
+LegoDOM uses Batching & Scheduling to do things the right way.
+## Topic 3: The Global Batcher & Scheduler
+When you change data in a reactive application, you often change multiple things at once (e.g., updating a user's name, age, and profile picture). Without a **Batcher**, the browser would try to re-render the HTML every single time one of those properties changed. This would cause "jank" (stuttering) and poor performance.
+### The `createBatcher` Factory
+The library defines `createBatcher` as a closure that manages the update cycle. It provides three critical layers of protection:
+```js
+  const createBatcher = () => {
+    let queued = false;
+    const componentsToUpdate = new Set();
+    let isProcessing = false;
+    return {
+      add: (el) => {
+        if (!el || isProcessing) return;
+        componentsToUpdate.add(el);
+        if (queued) return;
+        queued = true;
+        requestAnimationFrame(() => {
+          isProcessing = true;
+          const batch = Array.from(componentsToUpdate);
+          componentsToUpdate.clear();
+          queued = false;
+          batch.forEach(el => render(el));
+          setTimeout(() => {
+            batch.forEach(el => {
+              const state = el._studs;
+              if (state && typeof state.updated === 'function') {
+                try {
+                  state.updated.call(state);
+                } catch (e) {
+                  console.error(`[Lego] Error in updated hook:`, e);
+                }
+              }
+            });
+            isProcessing = false;
+          }, 0);
+        });
+      }
+    };
+  };
+  const globalBatcher = createBatcher();
+```
+1.  **Deduplication with `Set`**:
+    -   The batcher maintains a `componentsToUpdate = new Set()`.
+    -   Because a `Set` only stores unique values, if you trigger an update on the same component 50 times in a single loop, it is only added to the "todo" list **once**.
+2.  **The `queued` Gatekeeper**:
+    -   A boolean flag `queued` prevents multiple update cycles from being scheduled simultaneously.
+    -   Once the first change hits the batcher, it "locks the gate," schedules the work, and ignores further requests to start a new cycle until the current one begins.
+3.  **The `isProcessing` Lock**:
+    -   This flag ensures that if a component’s state changes _while_ the render is actually happening, it doesn't cause a collision or infinite loop.
+### Timing: `requestAnimationFrame` (rAF)
+Instead of updating immediately, the library uses `requestAnimationFrame`.
+-   **What it does**: It tells the browser, "Wait until you are just about to draw the next frame on the screen, then run this code".
+-   **Efficiency**: It bundles every single change from every component into a single "tick."
+-   **The Benefit**: This syncs your JavaScript logic with the monitor's refresh rate (usually 60 times per second), making animations and updates look buttery smooth.
+### The Execution Phase
+When the "frame" triggers, the batcher:
+1.  Takes a snapshot of the `Set`.
+2.  Clears the `Set` for the next round.
+3.  Runs `render(el)` for every component in that batch.
+### The `updated` Lifecycle Hook
+After the render is complete, the batcher uses a `setTimeout(() => ..., 0)`.
+-   **The Trick**: Even with a delay of `0`, this "macro-task" ensures the code inside runs **after** the browser has finished its rendering work.
+-   **The Hook**: It looks for `our` lifecycle hook function a.k.a or notoriously known as `updated`
+in each component's state (`_studs`) and executes it. This is the perfect place for us to run code that needs to measure the new size of an element or scroll a list to the bottom.
+**Example**
+If you have a `chat-box` component and you update the messages, you might use the `updated()` hook to scroll to the bottom. Because of this batcher, you are guaranteed that the DOM has finished changing before your scroll logic runs.
+> **Visualizing the flow:** State Change -> `batcher.add(el)` -> `Set` collects `el` -> `rAF` triggers -> `render(el)` runs -> `updated()` hook fires.

package/docs/contributing/04-reactivity.md ADDED Viewed

@@ -0,0 +1,87 @@
+# Reacting to stimuli is how we react to stimuli
+If living things react to stimuli, then so should our components.
+## Topic 4: Reactivity (The Proxy)
+LegoDOM uses the JavaScript **`Proxy`** object to create its reactivity. Think of a Proxy as a "security guard" that sits in front of your data object. Every time you try to read or change a property, the guard intercepts the request.
+### The `reactive(obj, el, batcher)` Function
+When a component is "snapped" (created), its data is passed through this function.
+```js
+  //... rest of the code
+  const reactive = (obj, el, batcher = globalBatcher) => {
+    if (obj === null || typeof obj !== 'object' || obj instanceof Node) return obj;
+    if (proxyCache.has(obj)) return proxyCache.get(obj);
+    const handler = {
+      get: (t, k) => {
+        const val = Reflect.get(t, k);
+        if (val !== null && typeof val === 'object' && !(val instanceof Node)) {
+          return reactive(val, el, batcher);
+        }
+        return val;
+      },
+      set: (t, k, v) => {
+        const old = t[k];
+        const r = Reflect.set(t, k, v);
+        if (old !== v) batcher.add(el);
+        return r;
+      },
+      deleteProperty: (t, k) => {
+        const r = Reflect.deleteProperty(t, k);
+        batcher.add(el);
+        return r;
+      }
+    };
+    const p = new Proxy(obj, handler);
+    proxyCache.set(obj, p);
+    return p;
+  };
+  //... rest of the code
+```
+1.  **The Traps (`get` and `set`)**:
+    -   **The `get` trap**: When you access a property (e.g., `state.count`), the Proxy checks if that property is _also_ an object. If it is, it recursively wraps that object in a Proxy too. This ensures that "deep" data like `user.profile.name` is also reactive.
+    -   **The `set` trap**: This is the trigger. When you do `state.count = 5`, the Proxy compares the `old` value with the `new` value. If they are different, it immediately calls `batcher.add(el)`.
+    -   **The `deleteProperty` trap**: Even if you delete a key (e.g., `delete state.tempData`), the Proxy intercepts this and tells the batcher to re-render the UI.
+2.  **Handling Objects vs. Nodes**:
+    -   The code explicitly checks if a value is an `instanceof Node`. If you try to store a raw HTML element in your state, the library **will not** wrap it in a Proxy. This prevents the library from accidentally trying to "observe" the entire DOM tree, which would crash the browser.
+### Concrete Example
+Imagine you have a component defined like this:
+```js
+Lego.define('counter-app', '<h1>{{count}}</h1>', {
+  count: 0,
+  increment() { this.count++; }
+});
+```
+-   **Step A**: Lego takes that object `{ count: 0, ... }` and wraps it in a Proxy.
+-   **Step B**: You call `increment()`.
+-   **Step C**: The line `this.count++` triggers the Proxy's `set` trap.
+-   **Step D**: The `set` trap notices `0` is now `1` and calls `globalBatcher.add(thisElement)`.
+-   **Step E**: The Batcher (from Topic 3) schedules a render for the next animation frame.
+### Why this is "Surgical"
+Because the `reactive` function is passed the specific element (`el`) it belongs to, it knows exactly which component in the DOM needs to re-render. It doesn't have to guess or refresh the whole page; it targets the specific "Lego block" that owns that data.

package/docs/contributing/05-caching.md ADDED Viewed

@@ -0,0 +1,59 @@
+# There are 2 hard things in computer science
+- cache invalidation
+- naming things
+- off-by-one errors
+## Proxy Caching (`proxyCache`)
+In [Topic 4](/contributing/04-reactivity), we saw how `reactive()` wraps objects in a Proxy.
+However, a common issue in reactive programming is trying to wrap the same object multiple
+times, or dealing with circular references
+(e.g. Object A points to Object B, and Object B points back to Object A).
+### The Problem: Infinite Recursion
+Without a cache, every time you access a nested object, the `get` trap would create a **new** Proxy wrapper.
+```js
+// Without a cache:
+const p1 = state.user;
+const p2 = state.user;
+console.log(p1 === p2); // false! They are different "guards" for the same data.
+```
+This wastes memory and breaks object identity. Even worse, if an object points to itself, the code would keep creating Proxies until the browser crashed with a "Maximum call stack size exceeded" error.
+### The Solution: `proxyCache`
+The library uses `const proxyCache = new WeakMap()` to keep track of every object it has already turned into a Proxy.
+1.  **Checking the Map**: At the very start of the `reactive()` function, the code checks: `if (proxyCache.has(obj)) return proxyCache.get(obj);`.
+2.  **Storing the Result**: If it's a new object, the code creates the Proxy and then immediately saves it: `proxyCache.set(obj, p);`.
+3.  **The Result**: If you access `state.user` 100 times, you get the exact same Proxy instance every time. It ensures that `p1 === p2` is always `true`.
+### Why a `WeakMap`?
+This is a critical "expert-level" choice.
+-   A regular `Map` holds a "strong reference" to its keys. If you deleted a piece of data from your state, but that data was still a key in a regular `Map`, the browser could never delete it from memory.
+-   Because `proxyCache` is a `WeakMap`, as soon as your component is destroyed and the original object is no longer needed, the browser’s Garbage Collector can automatically wipe it from the cache.
+### Summary of Logic:
+-   **Step 1:** Request to make `obj` reactive.
+-   **Step 2:** Check `proxyCache`. Found it? Return the existing Proxy.
+-   **Step 3:** Not found? Create a new Proxy.
+-   **Step 4:** Store `obj -> Proxy` in `proxyCache`.
+-   **Step 5:** Return the new Proxy.