lego-dom 1.3.4 → 1.5.0

package/docs/contributing/04-reactivity.md

@@ -1,87 +0,0 @@
-# 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

@@ -1,59 +0,0 @@
-# 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.

package/docs/contributing/06-init.md

@@ -1,136 +0,0 @@
-# In the beginning - `Lego.init()`
-
-The `init()` function is the heart of LegoDOM. It orchestrates the entire initialization process, setting up the observer, connecting the global state, and processing existing components.
-
-## The LegoDOM Entry Point
-
-When your HTML finishes loading
-
-```js
-if (typeof window !== 'undefined') {
-  document.addEventListener('DOMContentLoaded', Lego.init);
-  window.Lego = Lego;
-}
-```
-
-
-LegoDOM executes `Lego.init()`. This is the orchestration phase where the library sets up its "eyes" (the observer) and connects the global state to the page.
-
-```js
-  return {
-    init: () => {
-      document.querySelectorAll('template[b-id]').forEach(t => {
-        registry[t.getAttribute('b-id')] = t;
-      });
-      const observer = new MutationObserver(m => m.forEach(r => {
-        r.addedNodes.forEach(n => n.nodeType === Node.ELEMENT_NODE && snap(n));
-        r.removedNodes.forEach(n => n.nodeType === Node.ELEMENT_NODE && unsnap(n));
-      }));
-      observer.observe(document.body, { childList: true, subtree: true });
-
-      snap(document.body);
-      bind(document.body, { _studs: Lego.globals, _data: { bound: false } });
-
-      if (routes.length > 0) {
-        // Smart History: Restore surgical targets on Back button
-        window.addEventListener('popstate', (event) => {
-          const targets = event.state?.legoTargets || null;
-          _matchRoute(targets);
-        });
-
-        document.addEventListener('click', e => {
-          const link = e.target.closest('a[b-link]');
-          if (link) {
-            e.preventDefault();
-            const href = link.getAttribute('href');
-            const targetAttr = link.getAttribute('b-target');
-            const targets = targetAttr ? targetAttr.split(' ') : [];
-
-            // Execute navigation via $go logic
-            Lego.globals.$go(href, ...targets);
-          }
-        });
-        _matchRoute();
-      }
-    },
-    // ... other functions ...
-  };
-
-```
-
-### 1. Template Registration
-
-The first thing `init()` does is look for blueprints you've already defined in your HTML.
-
-```js
-document.querySelectorAll('template[b-id]').forEach(t => {
-  registry[t.getAttribute('b-id')] = t;
-});
-
-```
-
-It scans the entire document for any `<template>` tag that has a `b-id` attribute. It then adds these to the `registry` object we discussed in [Topic 2](/contributing/02-registry). This allows you to define components directly in your HTML file without writing a single line of JavaScript.
-
-### 2. Setting up the "Eyes" (`MutationObserver`)
-
-This is the most critical part of the initialization. The library creates a `MutationObserver`.
-
-```js
-const observer = new MutationObserver(m => m.forEach(r => {
-  r.addedNodes.forEach(n => {
-    if (n.nodeType === Node.ELEMENT_NODE) {
-      snap(n);
-      
-      // Auto-Discovery (v2.0): Check for remote components
-      const tagName = n.tagName.toLowerCase();
-      if (tagName.includes('-') && !registry[tagName] && config.loader && !activeComponents.has(n)) {
-        // ... Call loader ...
-      }
-    }
-  });
-  r.removedNodes.forEach(n => n.nodeType === Node.ELEMENT_NODE && unsnap(n));
-}));
-observer.observe(document.body, { childList: true, subtree: true });
-```
-
-- **What it does**: It watches the `document.body` for any changes to the HTML structure.
-- **Auto-Discovery (New in v2.0)**: If `snap(n)` fails because the component isn't in the registry, the observer now checks `config.loader`. If a loader is defined, it triggers a fetch to pull the component definition from the server. This enables the "HTMX+Components" pattern.
-    
--   **The Config**: It observes `{ childList: true, subtree: true }`. This means it sees if an element is added to the body, or if an element is added deep inside another element.
-    
--   **The Reaction**:
-    
-    -   If a new node is **added**, it calls `snap(n)` (which we will cover soon) to turn that raw HTML into a living component.
-        
-    -   If a node is **removed**, it calls `unsnap(n)` to clean up memory and fire lifecycle hooks.
-        
-
-### 3. The "First Snap"
-
-After setting up the observer, it calls `snap(document.body)`.
-
--   **Why?** The observer only sees _new_ things being added. It doesn't see what was already there when the page loaded.
-    
--   By calling `snap` on the body, the library manually processes every custom component that was present in the initial HTML.
-    
-
-### 4. Global Data Binding
-
-Finally, it binds the `Lego.globals` state to the `document.body`.
-
-JavaScript
-
-```
-bind(document.body, { _studs: Lego.globals, _data: { bound: false } });
-
-```
-
-This is a clever move: it treats the entire website body as if it were a giant component. This allows you to use reactive data in your "Light DOM" (the regular HTML outside of components) by referencing values stored in `Lego.globals`.
-
-### 5. Routing Initialization
-
-If you have defined any routes using `Lego.route()`, the `init` function sets up global click listeners and history management so that links with the `b-link` attribute don't refresh the page but instead perform a "surgical" swap of content.
-
-----------
-
-**Summary of `init()`:** It finds templates, starts a "watchdog" for new elements, processes existing elements, and enables global data.

package/docs/contributing/07-observer.md

@@ -1,72 +0,0 @@
-# Big Brother is Watching
-
-In Topic 6, we saw that Lego.init() sets up a "watchdog." Now, let's look at exactly how that watchdog functions. This is what makes the library feel "automatic"—you can inject HTML into the page using vanilla JavaScript, and Lego will instantly recognize it and bring it to life.
-
-## Mutation Observer
-
-The `MutationObserver` is a built-in browser API that provides the ability to watch for changes being made to the DOM tree. In this library, it acts as the "Event Loop" for component lifecycles.
-
-### 1. The Configuration
-
-The library observes the `document.body` with specific settings:
-
-```js
-observer.observe(document.body, { childList: true, subtree: true });
-
-```
-
--   **`childList: true`**: Tells the observer to watch for elements being added or removed.
-
--   **`subtree: true`**: This is vital. Without this, the library would only see things added directly to the `<body>`. With it, the library sees changes happening deep inside nested divs or other components.
-
-
-### 2. Processing `addedNodes`
-
-Whenever a new piece of HTML is injected (via `innerHTML`, `appendChild`, etc.), the observer receives a list of `addedNodes`.
-
--   **Filter**: The library checks `n.nodeType === Node.ELEMENT_NODE` to ensure it is an **Element** (like a `<div>` or `<my-comp>`) and not just a fragment of text.
-
--   **The Action**: It calls `snap(n)`. This triggers the entire initialization process: attaching the Shadow DOM, creating reactive state, and rendering the template.
-    
--   **Auto-Discovery (v2.0)**: If `snap(n)` doesn't find a template in the registry, the observer now checks `Lego.config.loader`. If configured, it pauses to fetch the component definition from the server.
-
-
-
-### 3. Processing `removedNodes`
-
-When an element is deleted from the page, the observer catches it in `removedNodes`.
-
--   **Cleanup**: It calls `unsnap(n)`.
-
--   **Lifecycle Hook**: `unsnap` checks the component's state for an `unmounted` function. This allows you to perform cleanup, like stopping timers or closing WebSocket connections, preventing memory leaks.
-
-
-### Why this is superior to manual initialization
-In most frameworks, you have to tell the library when you’ve changed the page (e.g., calling `root.render()`). This library turns that upside down by using the browser's native **MutationObserver** to watch the DOM and react automatically.
-Unlike some libraries where adding a button via `innerHTML` requires a manual "re-scan" or "re-bind" call, this setup makes LegoDOM **reactive to the DOM itself**: the moment a tag like `<user-card>` appears in the document, it is automatically detected and upgraded into a functional, living component.
-
-### 1. The Strategy: "Observe Once, Act Everywhere"
-
-The library sets up a single observer on `document.body`.
-
--   **`childList: true`**: This tells the observer to watch for the addition or removal of direct children.
-
--   **`subtree: true`**: This is the "secret sauce." It extends the observation to the entire DOM tree. If you have a deeply nested `div` and you inject a Lego component into it, the observer will see it.
-
-
-### 2. The Logic Loop: Added Nodes
-
-When the observer detects changes, it provides a list of `MutationRecord` objects. The library loops through these records specifically looking for `addedNodes`.
-
--   **Type Filtering**: It checks `n.nodeType === Node.ELEMENT_NODE`. This ensures the library ignores text changes or comments and only focuses on **Elements** (tags).
-
--   **The Upgrade (Snapping)**: For every new element found, it calls `snap(n)`. This is why you can do `document.body.innerHTML += '<my-counter></my-counter>'` in the console, and the counter will immediately start working.
-
-
-### 3. The Logic Loop: Removed Nodes
-
-This is equally important for "garbage collection." When an element is deleted, it appears in `removedNodes`.
-
--   **The `unsnap` Trigger**: The library calls `unsnap(n)`.
-
--   **Lifecycle Cleanup**: Inside `unsnap`, the library looks for a developer-defined `unmounted` function. This is where you'd kill `setInterval` timers or close database connections. Without this, your app would suffer from "Memory Leaks"—processes that keep running even though the component is gone.

package/docs/contributing/08-snap.md

@@ -1,140 +0,0 @@
-# Let there be, and it was!
-
-If LegoDOM were a robot it would probably say - snap() is the most complex function I have because it acts as the "Middleman" between the static DOM, the reactive state, and the Shadow DOM. It is the "constructor" that the ~~stingy~~ browser never gave anyone - LegoDOM.
-
-
-## Snap, snap, snap!
-
-The `snap(el)` function is responsible for "upgrading" a standard HTML element. It is recursive, meaning if you snap a `<div>`, it will automatically look inside that `<div>` and snap every child as well.
-
-```js
-const snap = (el) => {
-  if (!el || el.nodeType !== Node.ELEMENT_NODE) return;
-  const data = getPrivateData(el);
-  const name = el.tagName.toLowerCase();
-  const templateNode = registry[name];
-
-  if (templateNode && !data.snapped) {
-    data.snapped = true;
-    const tpl = templateNode.content.cloneNode(true);
-    const shadow = el.attachShadow({ mode: 'open' });
-
-    const splitStyles = (templateNode.getAttribute('b-styles') || "").split(/\s+/).filter(Boolean);
-    if (splitStyles.length) {
-       shadow.adoptedStyleSheets = splitStyles.flatMap(k => styleRegistry.get(k) || []);
-    }
-
-    // TIER 1: Logic from Lego.define (SFC)
-    const scriptLogic = sfcLogic.get(name) || {};
-
-    // TIER 2: Logic from the <template b-data="..."> attribute
-    const templateLogic = parseJSObject(templateNode.getAttribute('b-data') || '{}');
-
-    // TIER 3: Logic from the <my-comp b-data="..."> tag
-    const instanceLogic = parseJSObject(el.getAttribute('b-data') || '{}');
-
-    // Priority: Script < Template < Instance
-    el._studs = reactive({
-      ...scriptLogic,
-      ...templateLogic,
-      ...instanceLogic,
-      // Inject Global Helpers
-      get $route() { return Lego.globals.$route },
-      get $go() { return Lego.globals.$go }
-    }, el);
-
-    shadow.appendChild(tpl);
-
-    const style = shadow.querySelector('style');
-    if (style) {
-      style.textContent = style.textContent.replace(/\bself\b/g, ':host');
-    }
-
-    bind(shadow, el);
-    render(el);
-
-    if (typeof el._studs.mounted === 'function') {
-      try { el._studs.mounted.call(el._studs); } catch (e) { console.error(`[Lego] Error in mounted <${name}>:`, e); }
-    }
-  }
-
-  let provider = el.parentElement;
-  while (provider && !provider._studs) provider = provider.parentElement;
-  if (provider && provider._studs) bind(el, provider);
-
-  [...el.children].forEach(snap);
-};
-```
-
-### 1. The Blueprint Lookup
-
-When `snap(el)` runs, the first thing it does is determine if the element is a Lego component.
-
--   It converts the tag name to lowercase (e.g., `<MY-COMP>` becomes `my-comp`).
-    
--   It checks the **`registry`** (which we filled in [Topic 2](./02-registry.md)) to see if a `<template>` exists for that name.
-    
--   It uses `getPrivateData(el).snapped` to ensure it never "snaps" the same element twice, preventing infinite loops.
-    
-
-### 2. Attaching the Shadow DOM
-
-If a template is found, Lego creates a **Shadow DOM** for the element:
-
-JavaScript
-
-```
-const shadow = el.attachShadow({ mode: 'open' });
-
-```
-
--   **Encapsulation**: By using `attachShadow`, the component’s internal styles and HTML are shielded from the rest of the page.
-    
--   **Template Injection**: It clones the content of the template and appends it to this new Shadow Root.
-
-#### What about `<slot>`?
-Because we use native Shadow DOM, `<slot>` just works.
-When `snap` attaches the shadow root, any children *already* inside the custom element (the "Light DOM") are automatically projected into the `<slot>` tags defined in your template.
-We don't need to write any code for this—the browser does it for us.
-
-    
-
-### 3. CSS "self" Transformation
-
-Lego includes a small but clever utility for styling:
-
-JavaScript
-
-```
-style.textContent = style.textContent.replace(/\bself\b/g, ':host');
-
-```
-
--   This allows you to write `self { color: red; }` in your template CSS.
-    
--   During the snap process, Lego converts the word `self` to the official Web Component selector `:host`, which targets the component itself.
-    
-
-### 4. Data Merging & Reactivity
-
-This is where the component's state is born. The library merges data from three different sources (we will dive deeper into this "Tier System" in Topic 9) and wraps the result in the **`reactive()`** proxy.
-
--   The resulting proxy is stored in `el._studs`. This is the "brain" of your component.
-    
-
-### 5. The First Render and Lifecycle
-
-Once the data is ready and the Shadow DOM is attached:
-
-1.  **`bind(shadow, el)`**: Connects event listeners (like `@click`) inside the Shadow DOM.
-    
-2.  **`render(el)`**: Performs the initial pass to fill in <code v-pre>{{ variables }}</code> and handle `b-show/b-for` logic.
-    
-3.  **`mounted()`**: If you defined a `mounted` function in your logic, Lego calls it now. This is your signal that the component is officially "alive" and visible on the page.
-
----------
-
-**Crucial Logic Note:** At the very end of the function, `snap` calls itself on every child of the element: `[...el.children].forEach(snap)`. This ensures that if you have components nested inside components, they all "wake up" in a top-down order.
-    
-
-**Summary**: `snap()` takes a raw tag, gives it a Shadow DOM "soul," injects its HTML blueprint, sets up its reactive "brain" (`_studs`), and triggers its first breath (`mounted`).

package/docs/contributing/09-diffing.md

@@ -1,69 +0,0 @@
-# He said, She said, They Said, Who Said?
-
-This topic is about the "Power Struggle" inside the code. When a component is born, it needs to know what its data is. The library looks at three different places to find that data, and it has a strict hierarchy of who wins in a conflict.
-
-
-## Diffing, Merging, and Priorities (The Tier System)
-
-Inside the `snap(el)` function, you will see a variable called `logic`. This isn't just a simple object; it is the result of a three-way merge. The code uses the spread operator `{ ... }` to layer these "Tiers."
-
-### The Three Tiers of Authority
-
-1.  **Tier 1: The Global Definition (Lowest Priority)**
-    
-    ```js
-    const baseLogic = sfcLogic.get(name) || {};
-    
-    ```
-    
-    This is the JavaScript object you provided when you called `Lego.define()`. It contains your default values and methods. It’s the "fallback" data. SFCs and .lego files fall under this tier.
-    
-2.  **Tier 2: The Template Attributes (Middle Priority)**
-
-    
-    ```js
-    const templateLogic = parseJSObject(t.getAttribute('b-data')) || {};
-    
-    ```
-    
-    Lego looks at the `<template>` tag itself in your HTML. If you added a `b-data` attribute there, it overrides the global definition. This is useful for creating "variants" of a component template without writing new JavaScript.
-    
-3.  **Tier 3: The Instance Attributes (Highest Priority)**
-    
-    ```js
-    const instanceLogic = parseJSObject(el.getAttribute('b-data')) || {};
-    
-    ```
-    
-    This is the data attached to the specific tag on your page (e.g., `<user-profile b-data="{id: 42}">`). This is the "Final Word." If the instance says the ID is 42, it doesn't matter what the template or the global definition said.
-    
-
-### The Merge Order
-
-The code combines them like this:
-
-JavaScript
-
-```
-const mergedLogic = { ...baseLogic, ...templateLogic, ...instanceLogic };
-
-```
-
-In JavaScript, when you spread objects, the properties on the right overwrite properties on the left. So, Instance > Template > Definition.
-
-### The `parseJSObject` Utility
-
-To make this work, the library includes a helper called `parseJSObject`.
-
--   **Why not `JSON.parse`?** JSON is strict (requires double quotes, no functions).
-    
--   **The Library's Way**: It uses `new Function('return ' + str)()`. This is a powerful (and dangerous) trick that allows you to write actual JavaScript inside your HTML attributes, including functions or arrays, which Lego then evaluates into a real object.
-    
-
-### The Edge Case: `b-data` as a "Ref"
-
-If the `b-data` attribute starts with a `$`, like `b-data="$someGlobal"`, the library treats it as a pointer to a global variable instead of a raw object string. This allows for deep data sharing between the component and the outside world.
-
-----------
-
-**Summary**: A component's data is a "Cake" with three layers. The Global Logic is the bottom, the Template Logic is the middle, and the Instance Logic is the frosting. The "Frosting" (Instance) is what the user ultimately sees.

package/docs/contributing/10-studs.md

@@ -1,78 +0,0 @@
-# State Management
-
-Let's see how the "Cake" of data we merged in Topic 9 is actually brought to life. This is the moment a static object becomes a **Reactive State**, which the library stores in a property called `_studs`.
-
-
-## The `reactive` State (`_studs`)
-
-Once `snap()` has merged the data from the SFC (Tier 1), the Template (Tier 2), and the Instance (Tier 3), it doesn't just save that object to the element. It transforms it.
-
-```js
-//...rest of code
-  const tpl = templateNode.content.cloneNode(true);
-  const shadow = el.attachShadow({ mode: 'open' });
-
-  // TIER 1: Logic from Lego.define (SFC)
-  const scriptLogic = sfcLogic.get(name) || {};
-
-  // TIER 2: Logic from the <template b-data="..."> attribute
-  const templateLogic = parseJSObject(templateNode.getAttribute('b-data') || '{}');
-
-  // TIER 3: Logic from the <my-comp b-data="..."> tag
-  const instanceLogic = parseJSObject(el.getAttribute('b-data') || '{}');
-
-  // Priority: Script < Template < Instance
-  el._studs = reactive({
-    ...scriptLogic,
-    ...templateLogic,
-    ...instanceLogic,
-    get $route() { return Lego.globals.$route },
-    get $go() { return Lego.globals.$go }
-  }, el);
-  //... rest of code
-```
-
-### 1. Why the name `_studs`?
-
-In the physical world, "studs" are the bumps on top of a Lego brick that allow it to connect to others. In this library:
-
--   **`el._studs`** represents the connection point between your JavaScript logic and the DOM.
-    
--   It is the "source of truth" for the component. Every `{{variable}}` you write in your HTML is looking for a matching key inside `_studs`.
-    
-
-### 2. The Transformation
-
-The library executes this line during the snap process:
-
-```js
-el._studs = reactive({ ...mergedLogic }, el);
-
-```
-
--   **The `reactive` call**: This wraps the merged object in the **Proxy** we discussed in Topic 4.
-    
--   **The `el` argument**: Crucially, the proxy is given a reference to the DOM element (`el`). This allows the Proxy's `set` trap to know exactly which component needs to be added to the `globalBatcher` when a property changes.
-    
-
-### 3. Contextual Binding (The `this` Keyword)
-
-After the `_studs` proxy is created, the library ensures that your methods work correctly. When you define a method in your SFC, you expect `this` to point to your data.
-
--   Inside `snap()`, lifecycle hooks are called like this: `el._studs.mounted.call(el._studs)`.
-    
--   By using `.call(el._studs)`, the library forces the execution context of your functions to be the reactive proxy.
-    
--   **Result**: When you write `this.count++` in your code, you are actually interacting with the **Proxy**, which triggers the `set` trap, which notifies the **Batcher**, which triggers the **Render**.
-    
-
-### 4. Visibility vs. Privacy
-
--   **`_studs`**: This is attached directly to the DOM element. You can actually type `document.querySelector('my-component')._studs` in your browser console to see and even modify the live state of any component.
-    
--   **`privateData`**: Unlike `_studs`, the internal "housekeeping" (like whether the component has already snapped) is kept in a `WeakMap` called `privateData`, making it inaccessible to the outside world.
-    
-
-----------
-
-**Summary**: `_studs` is the reactive engine of your component. It is created by merging all data tiers into a Proxy that is uniquely linked to that specific DOM element.