lego-dom 1.3.3 → 1.4.0

package/docs/contributing/12-render.md

@@ -1,138 +0,0 @@
-# Paint Me HTML
-
-In Topic 11, we mapped out where the dynamic "holes" in your HTML are. Now, we look at the engine that actually fills them with data. The `render()` function is the most frequently called piece of code in LegoDOM, it is the bridge between JavaScript state and the pixels on the screen.
-
-
-## Rendering `render()` Engine
-
-The `render(el)` function doesn't refresh the whole component. Instead, it iterates through the "Instruction Objects" (bindings) created during the scanning phase and updates only what is necessary.
-
-```js
-const render = (el) => {
-  const state = el._studs;
-  if (!state) return;
-  const data = getPrivateData(el);
-  if (data.rendering) return;
-  data.rendering = true;
-
-  try {
-    const shadow = el.shadowRoot;
-    if (!shadow) return;
-    if (!data.bindings) data.bindings = scanForBindings(shadow);
-
-    if (config.metrics?.onRenderStart) config.metrics.onRenderStart(el);
-
-    data.bindings.forEach(b => {
-      // 1. Conditionals (b-if)
-      if (b.type === 'b-if') {
-          const condition = !!safeEval(b.expr, { state, global: Lego.globals, self: b.node });
-          const isAttached = !!b.node.parentNode;
-          if (condition && !isAttached) b.anchor.parentNode.replaceChild(b.node, b.anchor);
-          else if (!condition && isAttached) b.node.parentNode.replaceChild(b.anchor, b.node);
-      }
-      
-      // 2. Visibility (b-show)
-      if (b.type === 'b-show') b.node.style.display = safeEval(b.expr, { state, self: b.node }) ? '' : 'none';
-      
-      // 3. Text (b-text, b-html)
-      if (b.type === 'b-text') b.node.textContent = escapeHTML(resolve(b.path, state));
-      if (b.type === 'b-html') b.node.innerHTML = safeEval(b.expr, { state, self: b.node }); // Trusted HTML
-      
-      // 4. Sync (b-sync)
-      if (b.type === 'b-sync') syncModelValue(b.node, resolve(b.node.getAttribute('b-sync'), state));
-      
-      // 5. Mustaches 
-      if (b.type === 'text') {
-        const out = b.template.replace(/\[\[(.*?)\]\]/g, (_, k) => escapeHTML(safeEval(k.trim(), { state, self: b.node }) ?? ''));
-        if (b.node.textContent !== out) b.node.textContent = out;
-      }
-      if (b.type === 'attr') {
-        const out = b.template.replace(/\[\[(.*?)\]\]/g, (_, k) => escapeHTML(safeEval(k.trim(), { state, self: b.node }) ?? ''));
-        if (b.node.getAttribute(b.attrName) !== out) {
-          b.node.setAttribute(b.attrName, out);
-          if (b.attrName === 'class') b.node.className = out;
-        }
-      }
-      if (b.type === 'b-for') {
-        const list = safeEval(b.listName, { state, global: Lego.globals, self: el }) || [];
-        if (!forPools.has(b.node)) forPools.set(b.node, new Map());
-        const pool = forPools.get(b.node);
-        const currentKeys = new Set();
-        list.forEach((item, i) => {
-          const key = (item && typeof item === 'object') ? (item.__id || (item.__id = Math.random())) : `${i}-${item}`;
-          currentKeys.add(key);
-          let child = pool.get(key);
-          if (!child) {
-            const temp = document.createElement('div');
-            temp.innerHTML = b.template;
-            child = temp.firstElementChild;
-            pool.set(key, child);
-            bind(child, el, { name: b.itemName, listName: b.listName, index: i });
-          }
-          const localScope = Object.assign(Object.create(state), { [b.itemName]: item });
-          updateNodeBindings(child, localScope);
-
-          child.querySelectorAll('[b-sync]').forEach(input => {
-            const path = input.getAttribute('b-sync');
-            if (path.startsWith(b.itemName + '.')) {
-              const list = safeEval(b.listName, { state, global: Lego.globals, self: el });
-              syncModelValue(input, resolve(path.split('.').slice(1).join('.'), list[i]));
-            }
-          });
-          if (b.node.children[i] !== child) b.node.insertBefore(child, b.node.children[i] || null);
-        });
-        for (const [key, node] of pool.entries()) {
-          if (!currentKeys.has(key)) { node.remove(); pool.delete(key); }
-        }
-      }
-    });
-  } finally {
-  } finally {
-    if (config.metrics?.onRenderEnd) config.metrics.onRenderEnd(el);
-    data.rendering = false;
-  }
-  }
-};
-```
-
-### 1. The Guard Rails
-
-Before doing any work, `render` checks two things:
-
--   **The State**: It ensures `el._studs` exists.
-    
--   **The Recursion Lock**: It sets `data.rendering = true` at the start and `false` at the end. This prevents a "Render Loop" where an update triggers a render, which accidentally triggers another update.
-    
-
-### 2. Surgical Execution
-
-The function loops through `data.bindings` and performs specific actions based on the `type`:
-
--   **`b-show`**: It evaluates the expression. If false, it sets `display: none`. This is a "CSS-based" conditional; the element stays in the DOM but becomes invisible. **Might change to `remove()` in the future**
-    
--   **`b-text`**: It uses the `resolve()` helper to find the value in your state and sets the `textContent`.
-    
--   **`text` (Mustaches)**: It takes the original template (e.g., `Count: {{count}}`), replaces the mustache with the actual value, and updates the text node.
-    
--   **`attr`**: It updates attributes like `src`, `href`, or `class`. It even has a special check: if the attribute is `class`, it also updates `node.className` to ensure the browser applies the styles correctly.
-    
-
-### 3. The `safeEval` Bridge & Security
-
-You’ll notice that for things like `b-show` or mustaches, the library calls `safeEval(expr, { state, self: b.node })`.
-
-**Why not just `eval()`?**
-`eval()` executes code in the global scope, which is a massive security hole and performance killer.
-
-`safeEval` uses `new Function` with a **Proxy Sandbox**:
-1.  **Block List**: It immediately throws if it sees dangerous keywords like `eval`, `Function`, `import`, or global objects like `window`, `document`, `fetch` (unless explicitly provided).
-2.  **Scope Proxy**: The execution context is a `Proxy` (`with(proxy) { ... }`). If the code tries to access `document.cookie` effectively, the proxy intercepts it.
-3.  **Configurable Syntax**: As of v2.0, this also handles the dynamic regex for `[[ ]]` vs `{{ }}` support via `Lego.config.syntax`.
-
-### 4. Directives vs. Mustache Priority
-
-`render` processes directives (like `b-show` and `b-text`) and mustaches in the same loop. However, because it works with direct DOM references saved in the `bindings` array, it never has to "re-parse" the HTML string. It simply touches the specific property (like `.value` or `.textContent`) of the existing DOM node.
-
-----------
-
-**Summary**: `render()` is a "Loop of Truth." It walks through the map created by the scanner, evaluates the current state of your data, and applies those values to the specific DOM nodes that need them.

package/docs/contributing/13-directives.md

@@ -1,243 +0,0 @@
-# You know C++, I know Web Components++
-
-Let's break down the two simplest yet most vital directives in the library: b-if and b-text. These are the "workhorses" that handle visibility and data display without you having to write manual DOM manipulation code.
-
-## Conditional Directives `b-if` & `b-show`
-
-Directives like `b-if`, `b-text`, and `b-for` are the "Instructions" that bridge the gap between your JavaScript state and the DOM. Without them, your state would just be numbers and strings sitting in memory with no way to manifest on the screen.
-
-### 1. Conditional Visibility (`b-show`)
-
-The `b-show` directive is used to show or hide elements based on a truthy or falsy value in your state.
-
--   **How it works**: During the `render()` cycle, the library executes `safeEval(b.expr, { state, self: b.node })`.
-    
--   **The Implementation**:
-
-    
-    ```js
-    if (b.type === 'b-show') b.node.style.display = safeEval(b.expr, { state, self: b.node }) ? '' : 'none';
-    ```
-    
-    -   LegoDOM does not physically remove the element from the DOM (which is expensive), this library uses `display: none`.
-    
-    -   This means **b-show** is incredibly fast because the browser doesn't have to recalculate the entire DOM tree.
-        
-    -  It however also means the element still exists in memory and its `mounted` hook remains active even when hidden.
-
-
-### 2. Alternating Visibility (`b-if`)
-
-#### 1. The "Place in Line" Problem
-
-When an element has `b-if="false"`, we want it to disappear. If we simply remove it (`node.remove()`), the browser "forgets" where that element was supposed to live.
-
--   **The Risk:** If that element was originally between a `<h1>` and a `<footer>`, and the condition turns `true` later, how does the library know exactly where to put it back?
-    
--   **The Solution:** We leave a "bookmark" or an **Anchor** (a tiny, invisible `Comment` node) exactly where the element used to be.
-
-```js
-if (node.hasAttribute('b-if')) {
-    const expr = node.getAttribute('b-if');
-    // Create an anchor point to keep track of where the element belongs in the DOM
-    const anchor = document.createComment(`b-if: ${expr}`);
-    const data = getPrivateData(node);
-    data.anchor = anchor;
-    bindings.push({ type: 'b-if', node, anchor, expr });
-}
-```
-    
-
-### 2. Why use a Comment Node?
-
-We use `document.createComment()` because:
-
--   It is a valid DOM node that occupies a specific position in the `childNodes` list.
-    
--   It is completely invisible to the user and doesn't affect CSS layouts or accessibility.
-    
--   It acts as a permanent reference point for the `replaceChild` operation.
-    
-
-### 3. Why store it in `getPrivateData`?
-
-LegoDOM was designed in a way that the `render()` function runs every time state changes.
-
--   **Consistency:** By storing the anchor in the element's `privateData` (via `WeakMap`), we ensure that the same specific element is always paired with the same specific anchor.
-    
--   **The Swap Logic:**
-    
-    -   **Condition becomes `false`:** We find the element in the DOM and replace it with its stored anchor: `parent.replaceChild(anchor, node)`.
-        
-    -   **Condition becomes `true`:** We find the anchor in the DOM and replace it with the element: `parent.replaceChild(node, anchor)`.
-        
-
-### 4. Memory Safety
-
-By using `getPrivateData` (which is a `WeakMap`), we ensure that if the component is destroyed, the reference to the `anchor` is garbage collected. If we didn't store it here, we would have to scan the entire DOM or maintain complex external maps to find where to re-insert hidden elements, which would be a massive performance hit.
-
-**In short:** The anchor is the "Reserved Seat" sign at a theater. `getPrivateData` is the list that remembers which seat belongs to which person while they are out in the lobby.
-
-
-## Raw HTML Injection (`b-html`)
-
-LegoDOM is secure by default: all text interpolation is escaped. If your data contains `<b>Bold</b>`, it detects it as text, not HTML.
-
-`b-html` is the **only** hatch to render raw HTML.
-
-```javascript
-if (b.type === 'b-html') {
-    // SECURITY CRITICAL: This is the only place we set innerHTML directly.
-    b.node.innerHTML = safeEval(b.expr, { state, self: b.node });
-}
-```
-
-**Why separate directive?**
-By forcing you to use `b-html="..."`, we make it obvious during code reviews that "This part is dangerous." It prevents accidental XSS where a developer thought `{{ content }}` would render HTML.
-
-
-
-## Simple Text Interpolation (`b-text`)
-
-While you can use <code v-pre>{{mustaches}}</code>, `b-text` is the "cleaner" way to bind the entire content of an element to a single variable.
-
--   **The Logic**: It uses the `resolve()` helper to walk through your state object based on a string path.
-    
-    -   Example: `<span b-text="user.profile.name"></span>`.
-        
--   **The Implementation**:
-    
-    ```js
-    if (b.type === 'b-text') b.node.textContent = escapeHTML(resolve(b.path, state));
-    ```
-
--   **Security**: Note the use of `escapeHTML()`. This is a critical security feature that prevents **XSS (Cross-Site Scripting) attacks** by turning characters like `<` into `&lt;`, ensuring that user-provided data cannot execute malicious scripts in your app.
-
-
-### 3. Efficiency in the Render Loop
-
-Because both of these were "mapped" during the `scanForBindings` phase (Topic 11), the `render` engine holds a direct reference to the DOM `node`.
-
--   It doesn't have to look for the element by ID or class.
-    
--   It just goes: "Variable X changed -> Go to memory address for Node Y -> Update `.style.display` or `.textContent`".
-
-
-## Iterative Directive: `b-for` & The Pool
-
-The library looks for the pattern `item in list` (e.g., `user in users`).
-
--   **Capture**: During the scanning phase, it saves a deep clone of the `b-for` element itself as the "template node" (using `node.cloneNode(true)`) and then empties the element so it can be filled dynamically. This approach handles both element children and text-only content correctly.
-    
-
-### The Concept of "The Pool" (`forPools`)
-
-To prevent "DOM Thrashing" (constantly creating and deleting elements), the library uses a `WeakMap` called `forPools`.
-
--   **The Cache**: Each `b-for` node has its own `Map` inside the pool.
-    
--   **The Key**: It identifies each item in your array. If the item is an object, it assigns a hidden `__id`. If it's a primitive (like a string), it combines the index and the value.
-    
--   **Why?**: If you re-order a list of 100 items, the library doesn't create 100 new elements. it finds the existing elements in the "pool" by their key and simply moves them to the new position.
-    
-
-### 3. The Local Scope Injection
-
-This is a brilliant piece of JavaScript engineering. When rendering a list item, the library needs the item (e.g., `user`) to be available, but it also needs the parent component's data to be available.
-
-
-```js
-const localScope = Object.assign(Object.create(state), { [b.itemName]: item });
-
-```
-
--   **Prototype Inheritance**: It creates a new object where the **prototype** is the component's state (`_studs`).
-    
-- **The Result**: Inside the loop, if you reference <code v-pre>{{user.name}}</code>, it finds it on the `localScope`. If you reference <code v-pre>{{globalTitle}}</code> (defined in the parent), it doesn't find it on `localScope`, so it automatically looks up the prototype chain to find it in the parent `state`.
-    
-
-### 4. Updating and Pruning
-
--   **Update**: For every item in the current array, it calls `updateNodeBindings(child, localScope)` to fill in the mustaches for that specific row.
-    
--   **Surgical Sync**: It specifically looks for `b-sync` inputs inside the loop to ensure two-way binding works correctly for individual list items.
-    
--   **Prune**: After the loop finishes, any element left in the "pool" that wasn't used in the current render (meaning it was deleted from your data array) is physically removed from the DOM.
-
-## Directive: `b-sync` (Two-Way Binding)
-
-The `b-sync` directive is designed to keep an `<input>`, `<textarea>`, or `<select>` element in perfect synchronization with a specific variable in your state.
-
-```js
-if (child.hasAttribute('b-sync')) {
-    const prop = child.getAttribute('b-sync');
-    const updateState = () => {
-        let target, last;
-        if (loopCtx && prop.startsWith(loopCtx.name + '.')) {
-        const list = safeEval(loopCtx.listName, { state, global: Lego.globals, self: componentRoot });
-        const item = list[loopCtx.index];
-        if (!item) return;
-        const subPath = prop.split('.').slice(1);
-        last = subPath.pop();
-        target = subPath.reduce((o, k) => o[k], item);
-        } else {
-        const keys = prop.split('.');
-        last = keys.pop();
-        target = keys.reduce((o, k) => o[k], state);
-        }
-        const newVal = child.type === 'checkbox' ? child.checked : child.value;
-        if (target && target[last] !== newVal) target[last] = newVal;
-    };
-    child.addEventListener('input', updateState);
-    child.addEventListener('change', updateState);
-}
-```
-
-### 1. The Setup: Listening for Changes
-
-When the `scanForBindings` function encounters a `b-sync="somePath"` attribute, it doesn't just record it for rendering; it attaches an **event listener** to the element.
-
--   **The Event**: It listens for the `input` event (which fires every time a character is typed).
-    
--   **The Logic**: When the event fires, the library captures the `event.target.value`.
-    
--   **The Update**: It uses the internal `set()` helper to reach into your component's `_studs` and update the value at the path you specified (e.g., `user.name`).
-    
-
-### 2. The Implementation: Multi-Type Support
-
-The library is smart enough to handle different types of inputs automatically:
-
--   **Checkboxes**: It looks at `.checked` instead of `.value`.
-    
--   **Numbers**: If the input `type` is "number" or "range", it automatically converts the string from the DOM into a real JavaScript `Number` before saving it to your state.
-    
-
-### 3. Preventing the "Echo" Effect
-
-A common problem in two-way binding is the "Infinite Update Loop":
-
-1.  You type "A".
-    
-2.  `b-sync` updates the state to "A".
-    
-3.  The state change triggers a `render()`.
-    
-4.  `render()` updates the input value to "A".
-    
-5.  The cursor jumps to the end of the input or triggers another event.
-    
-
-**How Lego solves it**: During the `render()` phase for a `b-sync` binding, the library checks if the element is currently the `document.activeElement` (the thing you are typing in). If it is, and the value hasn't changed from what's already there, it skips the update to avoid disturbing your typing flow.
-
-### 4. The `b-sync` inside `b-for` loops
-
-As mentioned in Topic 14, `b-sync` works inside loops. If you have a list of inputs generated by a `b-for`, each input is synced to its specific item in the array. The library uses the `localScope` (with its prototype chain) to ensure that typing in the 3rd input only updates the 3rd item in your data list.
-
-----------
-
-**Summary**: `b-if` manages visibility via CSS, and `b-text` manages safe text updates via property resolution.
-
-`b-for` is a "Reconciliation Engine". It uses a memory pool to recycle DOM nodes and clever prototype inheritance to give each row access to both its own data and the parent's data.
-
-`b-sync` automates the "Boilerplate" of web development. You no longer have to write `onchange` handlers for every input; you just name the variable, and the library handles the rest.

package/docs/contributing/14-events.md

@@ -1,57 +0,0 @@
-# Lights, Camera, Action
-
-This is how LegoDOM makes your components interactive by connecting DOM events (clicks, keypresses, submits) directly to the methods you wrote in
-your **SFC** (Single File Component) autodiscovered **.lego** file, `<template />` tag or Lego.define call.
-
-## Event Handling (The `@event` Syntax)
-
-The library uses a shorthand syntax for event listeners: `@event-name="methodName"`. For example, `@click="increment"` or `@submit="saveUser"`.
-
-### 1. The `bind(container, el)` Phase
-
-During the `snap()` process, after the Shadow DOM is attached, the library calls `bind(container, el)`.
-
--   **Scanning for Attributes**: It looks through all elements in the Shadow DOM for any attribute starting with `@`.
-    
--   **The Match**: If it finds `@click="toggle"`, it identifies `click` as the event and `toggle` as the function name to look for in `_studs`.
-    
-
-### 2. Context Preservation (`.bind`)
-
-This is a critical "under the hood" step. When you click a button, the browser usually sets the keyword `this` to the button itself. However, in Lego, you want `this` to be your **reactive state**.
-
--   **The Implementation**:
-    
-    ```js
-    const handler = state[methodName].bind(state);
-    node.addEventListener(eventName, handler);
-    ```
-    
--   By using `.bind(state)`, the library ensures that when your `toggle()` function runs, `this.show = true` actually updates the proxy state, not the HTML button.
-    
-
-### 3. Argument Support
-
-The library is flexible with how you call these methods:
-
--   **Standard Call**: `@click="doSomething"` passes the native `Event` object as the first argument.
-    
--   **Parameterized Call**: `@click="deleteItem(5)"`. The library uses a regex to check if there are parentheses. If it finds them, it parses the arguments (like `5`) and passes them to your function.
-    
--   **The "Native" `event`**: If you write `@click="move(event, 10)"`, the library injects the native browser event object into that specific slot. (Note: use `event`, not `$event`).
-    
-
-### 4. Event Modifiers
-
-Lego includes built-in modifiers to handle common web patterns without writing extra JS:
-
--   **`.prevent`**: Automatically calls `event.preventDefault()`. Great for `@submit.prevent="save"`.
-    
--   **`.stop`**: Calls `event.stopPropagation()` to stop the event from bubbling up to parent elements.
-    
--   **`.enter`**: Only triggers the method if the "Enter" key was pressed (perfect for search bars).
-    
-
-----------
-
-**Summary**: The `@` syntax automates `addEventListener`, ensures the correct `this` context for your methods, and provides powerful modifiers to keep your component logic clean.

package/docs/contributing/15-router.md

@@ -1,57 +0,0 @@
-# Where do you want to go?
-
-The true power of the Lego router isn't just changing the URL; it's the **targeted DOM injection** that allows you to swap _any_ part of the page with _any_ component, without writing a single line of `fetch` or `innerHTML` logic.
-
-## The "Surgical" Philosophy
-
-Most SPAs use a **Replacer Strategy**:
-`URL Change -> Match Route -> Destroy App -> Rebuild App with new Page.`
-
-LegoDOM uses a **Surgical Strategy**:
-`URL Change -> Match Route -> Find Targets (#sidebar, #main) -> Modify ONLY those nodes.`
-
-### The Implementation
-
-The core function is `_go` (exposed as `$go`). It doesn't just look for a `<router-outlet>`. It accepts a list of targets.
-
-```javascript
-/* main.js (simplified) */
-const _go = (path, ...targets) => {
-  // 1. Update History API
-  history.pushState({ legoTargets: targets }, "", path);
-  
-  // 2. Find the component for this route
-  const route = routes.find(r => r.path === path);
-  const template = registry[route.tagName];
-
-  // 3. Surgical Swap
-  targets.forEach(selector => {
-    const el = document.querySelector(selector);
-    // CRITICAL: We don't touch the parent, we only replace children.
-    // This preserves the element's own state (scroll, attributes).
-    el.replaceChildren(template.cloneNode(true));
-    
-    // 4. Trigger Snap (Reactivity & Lifecycle) on new content
-    snap(el); 
-  });
-};
-```
-
-### Why this matters
-
-This architecture enables **Persistent Shells**. You can have a sidebar that plays music or holds chat state, while the main content navigates freely. Traditional routers usually require complex "Layout Components" to achieve this. LegoDOM does it by simply *not touching the sidebar*.
-
-## Intelligent Defaults
-
-While surgical routing is powerful, sometimes you just want standard navigation.
-LegoDOM checks for a default `<lego-router>` element if no targets are specified.
-
-```javascript
-/* main.js */
-const resolveTargets = (query) => {
-  if (!query) return [document.querySelector('lego-router')];
-  // ...
-};
-```
-
-This hybrid approach gives you the best of both worlds: Rapid prototyping (defaults) and App-like fidelity (surgical targets).

package/docs/contributing/16-state.md

@@ -1,47 +0,0 @@
-# Lego and the Brain
-In Lego, the code is designed to allow a component in the footer to talk to a component in the header without them ever being "parents" or "children" of each other.
-
-## Global State (`Lego.globals`) & The Observer Pattern
-
-
-
-### 1. The "Why": Decoupling the Hierarchy
-
-In most frameworks, data flows down like a waterfall. If a deeply nested component needs a piece of data, every parent above it must "pass it down." The code in `main.js` avoids this by creating a centralized, reactive hub.
-
-### 2. The Implementation: "The Body is the Root"
-
-When you define `Lego.globals`, the library doesn't just store your object. It wraps it in the same `reactive()` proxy, but binds it to `document.body`.
-
--   **The Code**: `Globals = reactive(userState, document.body)`.
-    
--   **The Effect**: This means the entire `<body>` is technically the "component" for global state.
-
-### 3. The `$global` Dependency Check (Smart Broadcast)
-
-The library uses a specific optimization to avoid re-rendering the whole world.
-
--   **Depenedency Tracking**: During `scanForBindings`, if the parser sees a variable that looks global (e.g. `[[ global.user ]]`), it marks that specific component with a `hasGlobalDependency` flag.
-
--   **The Broadcast Loop**: When you change a global (e.g., `Lego.globals.theme = 'dark'`), the Proxy's `set` trap fires on `document.body`. The `render` function sees this is a global update and iterates through **activeComponents**, checking which ones have the flag. Only those components re-render.
-    
-
-### 4. Why `Object.defineProperty` is avoided for Globals
-
-The library sticks to **Proxy** for globals because it allows for **dynamic property addition**.
-
--   In older libraries, you had to declare all your global variables upfront.
-    
--   Because Lego uses a Proxy, you can do `Lego.globals.newVar = 'surprise'` at runtime, and the library will immediately catch that "set" operation and notify all components, even though `newVar` didn't exist when the app started.
-    
-
-### 5. The `$go` and Globals Synergy
-
-This is where the code becomes a "system." When you use `$go` to swap a component (Topic 17), the new component is born, it scans its HTML, sees a `$user` variable, and "subscribes" to the global state.
-
--   This allows for **Persistent Identity**: The user's name stays in the header because the header is subscribed to `Lego.globals.user`, even as the rest of the page is being torn down and rebuilt by the router.
-    
-
-----------
-
-**Summary**: The code uses a "Centralized Proxy" to bypass the DOM hierarchy, ensuring that data is shared via subscription rather than inheritance.

package/docs/contributing/17-legodom.md

@@ -1,48 +0,0 @@
-# Mama "We Made It!"
-Everything we’ve discussed i.e. the Scanner, the Registry, the Router, and the Snap etc. "Everything" stays dormant until `Lego.init()` is called. This function is not just a starter; it’s an orchestrator that synchronizes the JavaScript environment with the existing HTML on the page.
-
-## The Lego Initializer
-
-The code for `init()` is deceptively small because its primary job is to flip the switches on the systems we've already built.
-
-### 1. Bootstrapping the Watchdog
-
-The core of the initialization is setting up the `MutationObserver` we discussed in Topic 7.
-
--   **The Target**: It targets `document.body`.
-    
--   **The Configuration**: It uses `{ childList: true, subtree: true }`.
-    
--   **The Why**: By starting the observer _before_ the first render, the library ensures that any elements it creates during the initial startup are also caught and "snapped" into life.
-    
-
-### 3. The "Initial Snap" (The Recursive Wake-up)
-
-Once the observer is live, the code calls `snap(document.body)`.
-
--   **The Why**: The `MutationObserver` only sees _new_ changes. It cannot see the HTML that was already there when the page loaded.
-    
--   **The Logic**: By manually calling `snap` on the body, the library recursively walks through your entire server-rendered HTML. It finds every custom tag (e.g., `<user-card>`) and "upgrades" them into components.
-    
-
-### 4. Activating the Global Listener
-
-This is where the **Router Hijack** (Topic 17) is installed.
-
--   The code adds a single click listener to the `window`.
-    
--   **The Why**: Instead of attaching listeners to every individual `<a>` tag (which would be slow and break when new links are added), it uses **Event Delegation**. It waits for clicks to bubble up to the window, checks if they are `b-link` clicks, and then decides whether to trigger the router.
-    
-
-### 5. The First Route Check
-
-Finally, `init()` calls `router()` manually for the first time.
-
--   **The Why**: If a user navigates directly to `mysite.com/dashboard`, the browser loads the page, but the JavaScript needs to know which component to put into the `router-view` immediately. This manual call ensures the UI matches the URL on the very first frame.
-    
-
-----------
-
-**The Architecture "Why"**: Lego is designed to be **Zero-Config**. By putting all these steps into `init()`, the developer only has to care about one thing: "When is my DOM ready?" The code handles the complex timing of making sure the Watchdog is looking while the Router is switching and the Snap is initializing.
-
-**Summary**: `Lego.init()` is the bridge. It turns a static document into a reactive application by starting the observer, snapping the existing HTML, and hijacking the navigation.

package/docs/contributing/index.md

@@ -1,24 +0,0 @@
-# Architectural Deep Dive
-
-Welcome to the internal documentation of LegoDOM.
-
-This isn't a "how to use" guide. This is a **"how it works"** guide. I believe that understanding the soul of LegoDOM should/could make you a better contributor.
-
-## The Philosophy
-**"The Platform is the Runtime."**
-We avoid compilers, transpilers, and VDOMs. We use:
-- **Proxies** for state.
-- **TreeWalkers** for scanning.
-- **Regex** for parsing.
-- **MutationObservers** for efficiency.
-
-## The Journey
-Follow the path of a component from HTML string to Pixel:
-
-1.  [**Init**](./06-init) - How the library wakes up.
-2.  [**Scanner**](./11-scanner) - How we find holes in your HTML (Regex vs AST).
-3.  [**Studs**](./10-studs) - The Reactivity Engine (Proxies).
-4.  [**Render**](./12-render) - The "Loop of Truth" & Security.
-5.  [**Router**](./15-router) - The "Surgical" Update philosophy.
-
-Dive in.

package/docs/examples/form.md

@@ -1,42 +0,0 @@
-# Form Example
-
-Handling forms in Lego.
-
-## Live Demo
-
-```html
-<template b-id="login-form">
-  <form @submit.prevent="login()">
-    <div>
-      <label>Email:</label>
-      <input type="email" b-sync="email">
-    </div>
-    
-    <div>
-      <label>Password:</label>
-      <input type="password" b-sync="password">
-    </div>
-    
-    <p b-show="error" style="color: red">[[ error ]]</p>
-    
-    <button type="submit">Login</button>
-  </form>
-</template>
-
-<script>
-  Lego.define('login-form', {
-    email: '',
-    password: '',
-    error: '',
-    
-    login() {
-      if (!this.email || !this.password) {
-        this.error = 'Please fill in all fields';
-        return;
-      }
-      alert(`Logging in as ${this.email}`);
-      this.error = '';
-    }
-  });
-</script>
-```