lego-dom 0.0.8 → 1.0.0

package/docs/guide/templating.md

@@ -1,6 +1,6 @@
 # Templating
 
-Learn about LegoJS templating features and syntax.
+Learn about Lego templating features and syntax.
 
 ## Interpolation
 
@@ -72,7 +72,7 @@ Interpolate in any attribute:
 
 ## Escaping
 
-LegoJS automatically escapes HTML to prevent XSS:
+Lego automatically escapes HTML to prevent XSS:
 
 ```js
 {
@@ -343,8 +343,8 @@ If a calculation is expensive, cache it:
 ### Show/Hide Based on Condition
 
 ```html
-<p b-if="user">Welcome, {{ user.name }}!</p>
-<p b-if="!user">Please log in</p>
+<p b-show="user">Welcome, {{ user.name }}!</p>
+<p b-show="!user">Please log in</p>
 ```
 
 ### List with Index

package/docs/index.md

@@ -2,19 +2,19 @@
 layout: home
 
 hero:
-  name: LegoJS
+  name: LegoDOM
   text: Build Reactive Web Components
-  tagline: A tiny, zero-dependency JavaScript library for creating reactive Web Components directly in the browser
+  tagline: A tiny, zero-dependency Web library for creating reactive Web Components directly in the browser
   image:
     src: /logo.svg
-    alt: LegoJS
+    alt: Lego
   actions:
     - theme: brand
       text: Get Started
       link: /guide/getting-started
     - theme: alt
       text: View on GitHub
-      link: https://github.com/rayattack/LegoJS
+      link: https://github.com/rayattack/Lego
     - theme: alt
       text: Try Examples
       link: /examples/
@@ -57,11 +57,35 @@ features:
     details: Battle-tested patterns from Vue and React, adapted for pure Web Components. No framework lock-in.
 ---
 
-## Quick Example
+## Components & Naming
+
+How you name your components depends on how you use Lego:
+
+### 1. Vite / Build Tools (Recommended)
+**Convention over Configuration.** The filename *is* the tag name.
+- `user-card.lego` → `<user-card></user-card>`
+- `app-nav.lego` → `<app-nav></app-nav>`
+
+You do not need `b-id` inside `.lego` files; the build system handles registration automatically.
+
+### 2. CDN / Script Tags
+Since there are no files, you must explicitly name your components using the `b-id` attribute on the `<template>` tag.
+
+```html
+<!-- Only needed for CDN usage -->
+<template b-id="user-profile">
+  <h1>User Profile</h1>
+</template>
+```
+
+## Quick Start (CDN)
 
 ```html
 <!-- Define a component -->
-<template b-id="counter-button">
+<template b-id="counter-button" b-data="{
+  title: 'My counter',
+  count: 0
+}">
   <style>
     self {
       display: block;
@@ -80,14 +104,26 @@ features:
 </template>
 
 <!-- Use it -->
-<counter-button b-data="{ title: 'My Counter', count: 0 }"></counter-button>
+<counter-button b-data="{ title: 'Override b-data title' }"></counter-button>
 
 <script src="https://unpkg.com/lego-dom/main.js"></script>
+<script>
+  // Complete the initialization
+  Lego.init();
+</script>
 ```
 
 That's it. No build step, no npm, no configuration.
 
-## Why LegoJS?
+> [!IMPORTANT]
+> **Why call `Lego.init()`?**
+> While `Lego.define()` will "snap" your components into the page immediately, you must call `Lego.init()` to start the background engine. Without it:
+> - **Reactivity** to data changes won't work.
+> - **Mustaches** (<code v-pre>{{...}}</code>) outside of components won't hydrate.
+> - **Single Page Routing** won't be activated.
+> - **New components** added to the DOM dynamically won't be auto-initialized.
+
+## Why Lego?
 
 **For small projects**, you get reactive components without the overhead of a full framework.
 
@@ -97,7 +133,7 @@ That's it. No build step, no npm, no configuration.
 
 ## Comparison
 
-| Feature | LegoJS | Vue | React |
+| Feature | Lego | Vue | React |
 |---------|--------|-----|-------|
 | Size | < 17KB | ~33KB | ~40KB |
 | Dependencies | 0 | Many | Many |
@@ -110,7 +146,7 @@ That's it. No build step, no npm, no configuration.
 
 ## Browser Support
 
-LegoJS works in all modern browsers that support:
+Lego works in all modern browsers that support:
 - Web Components
 - Shadow DOM
 - ES6 Proxy
@@ -119,8 +155,6 @@ LegoJS works in all modern browsers that support:
 This includes Chrome 63+, Firefox 63+, Safari 11.1+, and Edge 79+.
 
 ## Community
-
-- 📖 [Documentation](https://rayattack.github.io/LegoJS/)
-- 💬 [Discussions](https://github.com/rayattack/LegoJS/discussions)
-- 🐛 [Issue Tracker](https://github.com/rayattack/LegoJS/issues)
+- 💬 [Discussions](https://github.com/rayattack/LegoDOM/discussions)
+- 🐛 [Issue Tracker](https://github.com/rayattack/LegoDOM/issues)
 - 📦 [npm Package](https://www.npmjs.com/package/lego-dom)

package/docs/public/logo.svg

@@ -1,38 +1,17 @@
-<svg width="200" height="200" viewBox="0 0 200 200" fill="none" xmlns="http://www.w3.org/2000/svg">
-  <defs>
-    <linearGradient id="blockGrad" x1="0%" y1="0%" x2="100%" y2="100%">
-      <stop offset="0%" style="stop-color:#FF4B2B" />
-      <stop offset="100%" style="stop-color:#FF416C" />
-    </linearGradient>
-    <filter id="shadow" x="-20%" y="-20%" width="140%" height="140%">
-      <feGaussianBlur in="SourceAlpha" stdDeviation="3" />
-      <feOffset dx="2" dy="4" result="offsetblur" />
-      <feComponentTransfer>
-        <feFuncA type="linear" slope="0.2" />
-      </feComponentTransfer>
-      <feMerge>
-        <feMergeNode />
-        <feMergeNode in="SourceGraphic" />
-      </feMerge>
-    </filter>
-  </defs>
-
-  <g filter="url(#shadow)" transform="translate(40, 40)">
-    <path d="M60 80 L90 65 L90 95 L60 110 Z" fill="#D32F2F" />
-    <path d="M90 65 L120 80 L120 110 L90 95 Z" fill="#B71C1C" />
-    <path d="M60 80 L90 65 L120 80 L90 95 Z" fill="url(#blockGrad)" />
-    <circle cx="90" cy="80" r="4" fill="white" fill-opacity="0.3" />
-
-    <path d="M30 65 L60 50 L60 80 L30 95 Z" fill="#D32F2F" />
-    <path d="M60 50 L90 65 L90 95 L60 80 Z" fill="#B71C1C" />
-    <path d="M30 65 L60 50 L90 65 L60 80 Z" fill="url(#blockGrad)" />
-    <circle cx="60" cy="65" r="4" fill="white" fill-opacity="0.3" />
-
-    <path d="M30 35 L60 20 L60 50 L30 65 Z" fill="#D32F2F" />
-    <path d="M60 20 L90 35 L90 65 L60 50 Z" fill="#B71C1C" />
-    <path d="M30 35 L60 20 L90 35 L60 50 Z" fill="url(#blockGrad)" />
-    <circle cx="60" cy="35" r="4" fill="white" fill-opacity="0.3" />
-  </g>
-  
-  <text x="100" y="180" font-family="Arial, sans-serif" font-weight="900" font-size="24" fill="#333" text-anchor="middle" letter-spacing="1">LEGO.JS</text>
-</svg>
+<svg width="270" height="270" viewBox="0 0 270 270" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M19.8 199H250.2C257.88 199 263 202.657 263 208.143V253.857C263 259.343 257.88 263 250.2 263H19.8C12.12 263 7.00001 259.343 7.00001 253.857V208.143C7.00001 202.657 12.12 199 19.8 199Z" fill="#FFCA28"/>
+<path d="M205.194 199H238.226V183C238.226 178.2 234.923 175 229.968 175H213.452C208.497 175 205.194 178.2 205.194 183V199Z" fill="#FFCA28"/>
+<path d="M147.387 199H180.419V183C180.419 178.2 177.116 175 172.161 175H155.645C150.69 175 147.387 178.2 147.387 183V199Z" fill="#FFCA28"/>
+<path d="M15.2581 143H106.097C111.052 143 114.355 146.2 114.355 151V191C114.355 195.8 111.052 199 106.097 199H15.2581C10.3032 199 7 195.8 7 191V151C7 146.2 10.3032 143 15.2581 143Z" fill="#FFCA28"/>
+<path d="M15.2581 87H106.097C111.052 87 114.355 90.2 114.355 95V135C114.355 139.8 111.052 143 106.097 143H15.2581C10.3032 143 7 139.8 7 135V95C7 90.2 10.3032 87 15.2581 87Z" fill="#FFCA28"/>
+<path d="M15.2581 31H106.097C111.052 31 114.355 34.2 114.355 39V79C114.355 83.8 111.052 87 106.097 87H15.2581C10.3032 87 7 83.8 7 79V39C7 34.2 10.3032 31 15.2581 31Z" fill="#FFCA28"/>
+<path d="M73.0645 31H106.097V15C106.097 10.2 102.794 7 97.8387 7H81.3226C76.3677 7 73.0645 10.2 73.0645 15V31Z" fill="#FFCA28"/>
+<path d="M15.2581 31H48.2903V15C48.2903 10.2 44.9871 7 40.0323 7H23.5161C18.5613 7 15.2581 10.2 15.2581 15V31Z" fill="#FFCA28"/>
+<path d="M256 208.143C256 207.853 255.974 207.612 255.411 207.21C254.671 206.682 253.019 206 250.2 206H19.7998C16.9807 206 15.3288 206.682 14.5889 207.21C14.0263 207.612 14 207.853 14 208.143V253.857C14 254.147 14.0263 254.388 14.5889 254.79C15.3288 255.318 16.9807 256 19.7998 256H250.2C253.019 256 254.671 255.318 255.411 254.79C255.974 254.388 256 254.147 256 253.857V208.143ZM173.419 183C173.419 182.606 173.352 182.39 173.319 182.308C173.302 182.265 173.29 182.243 173.285 182.236C173.281 182.23 173.278 182.228 173.277 182.228C173.275 182.226 173.266 182.217 173.244 182.203C173.22 182.188 173.174 182.163 173.098 182.135C172.946 182.078 172.647 182 172.161 182H155.646C155.16 182 154.861 182.078 154.709 182.135C154.632 182.163 154.585 182.188 154.562 182.203C154.538 182.218 154.529 182.227 154.528 182.228C154.527 182.228 154.526 182.23 154.521 182.236C154.517 182.243 154.504 182.264 154.486 182.308C154.453 182.39 154.387 182.606 154.387 183V192H173.419V183ZM231.226 183C231.226 182.606 231.159 182.39 231.126 182.308C231.109 182.264 231.095 182.243 231.091 182.236C231.087 182.23 231.085 182.228 231.084 182.228C231.082 182.226 231.073 182.217 231.051 182.203C231.027 182.188 230.981 182.163 230.904 182.135C230.752 182.078 230.453 182 229.968 182H213.451C212.966 182 212.666 182.078 212.515 182.135C212.438 182.163 212.392 182.188 212.368 182.203C212.345 182.218 212.336 182.227 212.335 182.228C212.334 182.228 212.332 182.23 212.328 182.236C212.324 182.243 212.31 182.264 212.293 182.308C212.26 182.39 212.193 182.606 212.193 183V192H231.226V183ZM107.354 151C107.354 150.606 107.288 150.39 107.255 150.308C107.238 150.264 107.224 150.243 107.22 150.236C107.216 150.23 107.214 150.228 107.213 150.228C107.211 150.226 107.202 150.217 107.18 150.203C107.156 150.188 107.109 150.163 107.033 150.135C106.881 150.078 106.582 150 106.097 150H15.2578C14.7724 150 14.4731 150.078 14.3213 150.135C14.2449 150.163 14.1986 150.188 14.1748 150.203C14.1521 150.217 14.143 150.226 14.1416 150.228C14.1408 150.228 14.139 150.23 14.1348 150.236C14.1304 150.243 14.1168 150.264 14.0996 150.308C14.0667 150.39 14 150.606 14 151V191C14 191.394 14.0667 191.61 14.0996 191.692C14.1168 191.736 14.1304 191.757 14.1348 191.764C14.139 191.77 14.1408 191.772 14.1416 191.772C14.143 191.774 14.1521 191.783 14.1748 191.797C14.1986 191.812 14.2449 191.837 14.3213 191.865C14.4731 191.922 14.7724 192 15.2578 192H106.097C106.582 192 106.881 191.922 107.033 191.865C107.109 191.837 107.156 191.812 107.18 191.797C107.202 191.783 107.211 191.774 107.213 191.772C107.214 191.772 107.216 191.77 107.22 191.764C107.224 191.757 107.238 191.736 107.255 191.692C107.288 191.61 107.354 191.394 107.354 191V151ZM107.354 95C107.354 94.6058 107.288 94.3904 107.255 94.3076C107.238 94.2644 107.224 94.2429 107.22 94.2363C107.216 94.2302 107.214 94.2283 107.213 94.2275C107.211 94.2257 107.202 94.2168 107.18 94.2031C107.156 94.1883 107.109 94.1632 107.033 94.1348C106.881 94.0782 106.582 94 106.097 94H15.2578C14.7724 94 14.4731 94.0782 14.3213 94.1348C14.2449 94.1632 14.1986 94.1883 14.1748 94.2031C14.1521 94.2173 14.143 94.2262 14.1416 94.2275C14.1408 94.2284 14.139 94.2301 14.1348 94.2363C14.1304 94.2429 14.1168 94.2643 14.0996 94.3076C14.0667 94.3904 14 94.6058 14 95V135C14 135.394 14.0667 135.61 14.0996 135.692C14.1168 135.736 14.1304 135.757 14.1348 135.764C14.139 135.77 14.1408 135.772 14.1416 135.772C14.143 135.774 14.1521 135.783 14.1748 135.797C14.1986 135.812 14.2449 135.837 14.3213 135.865C14.4731 135.922 14.7724 136 15.2578 136H106.097C106.582 136 106.881 135.922 107.033 135.865C107.109 135.837 107.156 135.812 107.18 135.797C107.202 135.783 107.211 135.774 107.213 135.772C107.214 135.772 107.216 135.77 107.22 135.764C107.224 135.757 107.238 135.736 107.255 135.692C107.288 135.61 107.354 135.394 107.354 135V95ZM107.354 39C107.354 38.6058 107.288 38.3904 107.255 38.3076C107.238 38.2644 107.224 38.2429 107.22 38.2363C107.216 38.2302 107.214 38.2283 107.213 38.2275C107.211 38.2257 107.202 38.2168 107.18 38.2031C107.156 38.1883 107.109 38.1632 107.033 38.1348C106.881 38.0782 106.582 38 106.097 38H15.2578C14.7724 38 14.4731 38.0782 14.3213 38.1348C14.2449 38.1632 14.1986 38.1883 14.1748 38.2031C14.1521 38.2173 14.143 38.2262 14.1416 38.2275C14.1408 38.2284 14.139 38.2301 14.1348 38.2363C14.1304 38.2429 14.1168 38.2643 14.0996 38.3076C14.0667 38.3904 14 38.6058 14 39V79C14 79.3942 14.0667 79.6096 14.0996 79.6924C14.1168 79.7357 14.1304 79.7571 14.1348 79.7637C14.139 79.7699 14.1408 79.7716 14.1416 79.7725C14.143 79.7738 14.1521 79.7827 14.1748 79.7969C14.1986 79.8117 14.2449 79.8368 14.3213 79.8652C14.4731 79.9218 14.7724 80 15.2578 80H106.097C106.582 80 106.881 79.9218 107.033 79.8652C107.109 79.8368 107.156 79.8117 107.18 79.7969C107.202 79.7832 107.211 79.7743 107.213 79.7725C107.214 79.7717 107.216 79.7698 107.22 79.7637C107.224 79.7571 107.238 79.7356 107.255 79.6924C107.288 79.6096 107.354 79.3942 107.354 79V39ZM41.29 15C41.29 14.6058 41.2233 14.3904 41.1904 14.3076C41.1732 14.2644 41.1596 14.2429 41.1553 14.2363C41.1511 14.2302 41.1493 14.2283 41.1484 14.2275C41.1466 14.2258 41.1372 14.2169 41.1152 14.2031C41.0914 14.1883 41.045 14.1632 40.9688 14.1348C40.8169 14.0782 40.5178 14 40.0322 14H23.5166C23.031 14 22.7309 14.0782 22.5791 14.1348C22.5027 14.1633 22.4563 14.1883 22.4326 14.2031C22.4092 14.2177 22.4004 14.2266 22.3994 14.2275C22.3986 14.2284 22.3968 14.23 22.3926 14.2363C22.3882 14.2429 22.3747 14.2643 22.3574 14.3076C22.3245 14.3904 22.2578 14.6058 22.2578 15V24H41.29V15ZM99.0967 15C99.0967 14.6058 99.03 14.3904 98.9971 14.3076C98.9799 14.2644 98.9663 14.2429 98.9619 14.2363C98.9577 14.2301 98.9559 14.2283 98.9551 14.2275C98.9535 14.2261 98.9443 14.2171 98.9219 14.2031C98.8981 14.1883 98.8517 14.1632 98.7754 14.1348C98.6236 14.0782 98.3244 14 97.8389 14H81.3223C80.8369 14 80.5375 14.0782 80.3857 14.1348C80.3094 14.1632 80.263 14.1883 80.2393 14.2031C80.2164 14.2174 80.2073 14.2263 80.2061 14.2275C80.2052 14.2284 80.2034 14.23 80.1992 14.2363C80.1948 14.2429 80.1813 14.2643 80.1641 14.3076C80.1312 14.3904 80.0645 14.6058 80.0645 15V24H99.0967V15ZM113.097 25.5107C114.495 26.1706 115.799 27.0527 116.954 28.1719C119.921 31.0462 121.354 34.9412 121.354 39V79C121.354 81.8462 120.648 84.6105 119.204 87C120.648 89.3895 121.354 92.1538 121.354 95V135C121.354 137.846 120.648 140.611 119.204 143C120.648 145.389 121.354 148.154 121.354 151V191C121.354 191.335 121.345 191.668 121.325 192H140.387V183C140.387 178.941 141.82 175.046 144.787 172.172C147.734 169.317 151.643 168 155.646 168H172.161C176.164 168 180.071 169.317 183.019 172.172C185.986 175.046 187.419 178.941 187.419 183V192H198.193V183C198.193 178.941 199.627 175.046 202.594 172.172C205.541 169.317 209.449 168 213.451 168H229.968C233.97 168 237.878 169.317 240.825 172.172C243.792 175.046 245.226 178.941 245.226 183V192H250.2C255.06 192 259.809 193.147 263.549 195.818C267.466 198.616 270 202.947 270 208.143V253.857C270 259.053 267.466 263.384 263.549 266.182C259.809 268.853 255.06 270 250.2 270H19.7998C14.9396 270 10.1913 268.853 6.45117 266.182C2.53412 263.384 8.92991e-05 259.053 0 253.857V208.143C5.4865e-05 204.95 0.95743 202.085 2.60352 199.701C0.853644 197.16 0 194.129 0 191V151C0 148.154 0.706222 145.389 2.15039 143C0.706222 140.611 0 137.846 0 135V95C0 92.1539 0.706222 89.3894 2.15039 87C0.706222 84.6106 0 81.8461 0 79V39C0 34.9412 1.43333 31.0462 4.40039 28.1719C5.55577 27.0526 6.85931 26.1706 8.25781 25.5107V15C8.25781 10.9412 9.69114 7.04622 12.6582 4.17188C15.6053 1.31691 19.5139 0 23.5166 0H40.0322C44.0348 0 47.9426 1.3171 50.8896 4.17188C53.8567 7.04622 55.29 10.9412 55.29 15V24H66.0645V15C66.0645 10.9412 67.4978 7.04622 70.4648 4.17188C73.4119 1.31705 77.3197 6.86267e-05 81.3223 0H97.8389C101.841 3.51509e-05 105.749 1.31707 108.696 4.17188C111.663 7.04622 113.097 10.9412 113.097 15V25.5107Z" fill="#3E3E3E"/>
+<path d="M151.988 148.804L143 48H241.76L232.76 148.788L192.32 160L151.988 148.804Z" fill="#E44F26"/>
+<path d="M192.381 151.432L225.061 142.372L232.749 56.2441H192.381V151.432Z" fill="#F1662A"/>
+<path d="M192.381 93.628H176.021L174.893 80.968H192.381V68.604H192.337H161.381L164.713 105.992H192.381V93.628Z" fill="#EBEBEB"/>
+<path d="M192.382 125.736L192.326 125.752L178.558 122.036L177.678 112.176H165.266L166.998 131.584L192.326 138.616L192.382 138.6V125.736Z" fill="#EBEBEB"/>
+<path d="M192.336 93.6279V105.992H207.56L206.128 122.028L192.336 125.748V138.612L217.684 131.584L217.868 129.496L220.772 96.9479L221.076 93.6279H192.336Z" fill="white"/>
+<path d="M192.337 68.604L192.336 80.968H222.2L223.308 68.604H192.337Z" fill="white"/>
+</svg>

package/docs/router/basic-routing.md

@@ -0,0 +1,103 @@
+# Basic Routing: The Global Outlet
+
+Before we dive into surgical swaps, we must understand how LegoJS handles the initial entry into your application. Every application needs a primary gateway—a place where the main content lives. In Lego, this is the `<lego-router>`.
+
+## The Entry Point
+
+In your `index.html`, you define a single custom element that acts as the "Master Outlet":
+
+```html
+<body>
+  <my-application-nav></my-application-nav>
+  <lego-router></lego-router>
+</body>
+
+```
+
+
+When the page loads, the LegoJS router looks at the current browser URL and searches its internal "Route Map" for a match.
+
+## Defining Your First Routes
+
+Routes are defined using the `Lego.route(path, componentName)` method. This creates a contract between a URL pattern and a Web Component.
+
+```js
+// Static Route
+Lego.route('/', 'home-page');
+
+// Dynamic Route (with parameters)
+Lego.route('/user/:id', 'profile-page');
+
+```
+
+### How the Matching Works
+
+1.  **The Match**: Lego uses Regex to compare the window location with your defined paths.
+    
+2.  **The Injection**: If a match is found, Lego creates an instance of the associated component (e.g., `<home-page>`) and injects it into the `<lego-router>` tag.
+    
+3.  **The Hydration**: The framework then "snaps" the component to life, initializing its state and running its `mounted()` lifecycle hook.
+    
+
+## The Global Fallback
+
+If no route matches the current URL, LegoJS looks for a special fallback route. This is essential for handling **404 Not Found** states gracefully.
+
+```js
+Lego.route('*', 'not-found-page');
+
+```
+
+## Handling Parameters (`$params`)
+
+When you use a dynamic path like `/user/:id`, Lego automatically parses the URL and makes the data available to the component via the global `$route` object.
+
+In your component template:
+
+```html
+<template b-id="profile-page">
+  <h1>User Profile</h1>
+  <p>Viewing ID: {{ $route.params.id }}</p>
+</template>
+
+```
+
+In your component logic:
+
+```js
+mounted() {
+  const userId = this.$route.params.id;
+  this.fetchUserData(userId);
+}
+
+```
+
+**or**
+
+
+```html
+<!-- profile-page.lego -->
+<style>
+  /* nothing here for now */
+</style>
+
+<template>
+  <h1>User Profile</h1>
+  <p>Viewing ID: {{ $params.id }}</p>
+</template>
+
+<script>
+export default {
+  mounted() {
+    const userId = this.$route.params.id;
+    this.fetchUserData(userId);
+  }
+}
+</script>
+```
+
+## Summary
+
+The `<lego-router>` is the foundation. It handles the "Big Swaps" of your application. However, in a modern "Enterprise" application, we rarely want to swap the _entire_ page content every time the URL changes.
+
+In the next section, we will learn about **Surgical Swaps**, where we move beyond the global router and start updating specific pieces of the DOM using `b-target`.

package/docs/router/cold-entry.md

@@ -0,0 +1,91 @@
+
+# The Cold Start: Self-Healing Layouts
+
+In the previous section, we learned how to use `b-target` to surgically swap fragments while the app is running. But what happens when a user types `myapp.com/messaging/123` directly into the address bar or hits **Refresh (F5)**?
+
+In a traditional nested router, the framework handles this automatically. In LegoJS, we use a more powerful, explicit pattern called **Self-Healing Layouts**.
+
+## The Cold Entry/Start Challenge
+
+When a "Cold Start" occurs:
+
+1.  The browser requests the URL from the server.
+    
+2.  The server returns the base `index.html`.
+    
+3.  LegoJS matches the route `/messaging/:id` to the `messaging-shell` component.
+    
+4.  The `messaging-shell` mounts, but the `#chat-window` target is empty (or showing its default "Select a conversation" text).
+    
+
+The user is at the correct URL, but the **fragment** (the specific email or chat) is missing.
+
+## The Solution: The "Self-Healing" Mounted Hook
+
+To fix this, the Parent Shell must be responsible for "healing" its own internal state if it detects a parameter in the URL on mount.
+
+### Step 1: Define the Shared Route
+
+First, ensure your route configuration points both the list and the detail view to the same Shell component.
+
+```js
+Lego.route('/messaging', 'messaging-shell');
+Lego.route('/messaging/:id', 'messaging-shell');
+
+```
+
+### Step 2: Implement the Healing Logic
+
+Inside your `messaging-shell` component, use the `mounted()` hook to check for the presence of a parameter.
+
+```js
+Lego.define('messaging-shell', `
+  <div class="layout">
+    <aside class="sidebar">
+      <!-- List of threads -->
+    </aside>
+
+    <main id="chat-window">
+       <!-- Default content -->
+       <p>Select a conversation.</p>
+    </main>
+  </div>
+`, {
+  mounted() {
+    // Check if we arrived here via a deep-link (e.g., /messaging/123)
+    if (this.$route.params.id) {
+      // SURGICAL HEALING:
+      // Tell Lego to render the current URL into the local target.
+      // This pulls the 'messaging-details' fragment into the main window.
+      this.$go(window.location.pathname, '#chat-window').get();
+    }
+  }
+});
+
+```
+
+## Why This Pattern is Superior
+
+1.  **Explicit Control**: You decide exactly when and how the child fragment appears.
+    
+2.  **Layout Persistence**: The Sidebar and Header are rendered immediately. The user sees the "Shell" instantly, while the specific data fragment "pops" in a few milliseconds later. This improves the **Perceived Performance**.
+    
+3.  **No Nested Config Hell**: You don't need a complex tree of routes. The DOM structure of your shell defines the nesting naturally.
+    
+
+## Using Slots for Better Defaults
+
+You can use the native `<slot>` tag inside your target area to provide a better "Loading" or "Empty" experience before the healing happens.
+
+```html
+<main id="chat-window">
+  <slot>
+    <div class="skeleton-loader">Loading your message...</div>
+  </slot>
+</main>
+
+```
+
+## Summary
+
+"Self-Healing" is the bridge between a static website and a dynamic application. It ensures that your surgical routing works perfectly even on hard refreshes. By using the `mounted()` hook and the `$go` helper, your components become intelligent enough to manage their own internal layout based on the global URL state.

package/docs/router/history.md

@@ -0,0 +1,69 @@
+
+# Smart History & The Back Button
+
+One of the biggest frustrations in modern web development is "breaking the back button." When you use JavaScript to update only part of a page, the browser often doesn't realize a navigation event occurred. If the user hits "Back," they might be booted out of your app entirely.
+
+LegoJS solves this using a system called **Smart History**. It ensures that even surgical, fragment-level updates are recorded and reversible.
+
+## How Traditional Routers Fail
+
+In a standard SPA, the router usually manages a single "current view." When you navigate:
+
+1.  The URL changes.
+    
+2.  The old component is destroyed.
+    
+3.  The new component is mounted.
+    
+
+Because the whole page (or the main outlet) is replaced, the browser's history stack is simple: Page A -> Page B. But in a complex layout like LinkedIn, you might have changed the chat window 5 times while the sidebar stayed exactly the same. Users expect the "Back" button to cycle through those chats, not take them back to the login screen.
+
+## The LegoJS Approach: Target Tracking
+
+When you use `b-link` with a `b-target`, LegoJS does two things simultaneously:
+
+1.  It updates the browser URL using the History API.
+    
+2.  It stores a "snapshot" of the target information in the history state.
+    
+
+### Inside the History State
+
+Every time a surgical swap happens, LegoJS saves the target selector in the `history.state`. It looks something like this:
+
+```js
+// Internal representation
+history.pushState({ 
+  legoTargets: '#chat-window' 
+}, '', '/messaging/124');
+
+```
+
+## The "Popstate" Magic
+
+When a user hits the **Back** or **Forward** button, the browser triggers a `popstate` event. LegoJS intercepts this event and checks if the incoming state contains `legoTargets`.
+
+-   **If `legoTargets` exists:** LegoJS performs a surgical swap. It takes the URL the browser is moving to and renders it _only_ into the specified target (e.g., `#chat-window`).
+    
+-   **If no target exists:** It performs a global swap in the `<lego-router>`.
+    
+
+## Why This Matters for User Experience
+
+### 1. Persistence of Sibling State
+
+Because only the target is swapped during history navigation, your sidebar remains untouched. If the user had scrolled halfway down a list of 500 emails, they stay exactly at that scroll position as they hit "Back" and "Forward" to view different email details.
+
+### 2. Zero-Config History
+
+You don't have to write a single line of code to make the back button work. As long as you are using `b-link` and `b-target`, the framework handles the history reconciliation automatically.
+
+### 3. Deep Link Consistency
+
+Because the history state uses the same URLs as your standard links, a "Back" navigation and a "Hard Refresh" result in the same UI state (thanks to the Self-Healing logic we covered in the previous section).
+
+## Summary
+
+Smart History is the "glue" that makes a multi-fragment interface feel like a single, cohesive application. It respects the user's intent by making the browser's navigation tools work for specific parts of the page, not just the whole page.
+
+Next, we'll dive into the mechanics of how LegoJS finds these targets in complex, nested DOM trees in **Target Resolver: Scoping and Logic**.

package/docs/router/index.md

@@ -0,0 +1,73 @@
+
+# LegoDOM vs Traditional SPA Router
+
+Traditional Single Page Application (SPA) routers (like React Router, Vue Router, or Angular's Router) rely on a **Centralized Configuration Tree**. As your project grows, this JSON or JavaScript object becomes a "source of truth" that is fragile, hard to maintain, and forces a rigid hierarchy on your UI.
+
+**LegoJS breaks this pattern.**
+
+In Lego, we don't nest routes in a config file. Instead, we use the **URL as the Data Source** and the **DOM as the Layout Engine**.
+
+## The Shift in Thinking
+
+|Concept | Traditional SPAs | LegoDOM |
+|-----------|---------------|--------|
+| **Route Map** | Nested JSON Objects | Flat Component List |
+| **Nesting** | Defined in JS | Defined by your HTML structure |
+| **UI Updates** | "Nuclear" (Re-renders parent + children) | "Surgical" (Swaps exactly one fragment"|
+| **State** | Lost unless lifted to Global Store | Persists naturally in unaffected siblings |
+
+
+## The "Flat Route" Philosophy
+
+In a large project, your route definitions should remain a flat list of "Shells" (Layouts).
+
+```js
+// A flat list of structural shells
+Lego.route('/', 'home-shell');
+Lego.route('/messaging', 'messaging-shell');
+Lego.route('/messaging/:id', 'messaging-shell');
+Lego.route('/settings', 'settings-shell');
+
+```
+
+By pointing `/messaging` and `/messaging/:id` to the same **Shell**, you are telling Lego: _"I want the same layout for both URLs, but I'll decide how to fill the holes inside the component based on the URL parameters."_
+
+## Why This Scales
+
+In a LinkedIn-sized project, a traditional router would need to know that the `ChatWindow` is a child of the `MessagingLayout`. If you wanted to move that `ChatWindow` to the `HomeLayout`, you’d have to refactor your entire route tree.
+
+In Lego, you just change the **Target**. Because the components are agnostic, they don't care who their parent is. They just care about where the `b-target` tells them to go.
+
+### Defining with SFCs
+
+LegoDOM supports the use of Single File Components and this works seamlessly with the Router. You can define your Shell components via the `<template>` tag. This keeps our architectural "Shells" clean and readable.
+
+```html
+<style></style>
+<template b-id="home-shell">
+  <div class="layout">
+    <nav-bar></nav-bar>
+    <lego-router></lego-router> <!-- The global outlet -->
+  </div>
+</template>
+<script>
+  export default {
+    name: 'HomeShell'
+  }
+</script>
+```
+
+### Key Vocabulary for the Tutorial
+
+Throughout this guide, we will refer to three primary concepts:
+
+1.  **The Shell**: The high-level SFC that provides the grid, navigation, and sidebar.
+    
+2.  **The Fragment**: A self-contained SFC (like a chat thread or a profile header) that is surgically injected into a shell.
+    
+3.  **The Target**: A CSS selector, Tag Name, or ID that acts as the "destination hole" for a fragment.
+    
+
+## What's Next?
+
+We will move away from the theory and look at **Basic Routing**. We'll see how the `<lego-router>` element acts as the default gateway for your application and how Lego identifies which component to mount when the page first loads.

package/docs/router/resolver.md

@@ -0,0 +1,74 @@
+
+# 06. Target Resolver: Scoping and Logic
+
+In the previous chapters, we used `b-target` to send content to different parts of the page. But how does LegoJS actually find those "holes" in a complex, nested DOM? This is where the **Target Resolver** comes in.
+
+The Target Resolver is a prioritized logic engine that ensures your links always find the correct destination, even in massive applications with thousands of components.
+
+## The Problem with Global Selectors
+
+In traditional JavaScript, if you use `document.querySelector('#detail-view')`, the browser searches the entire page. This is fine for small sites, but in a "Web Component First" architecture, it causes two major issues:
+
+1.  **ID Collisions**: If you accidentally use the same ID in two different components, your link might update the wrong part of the page.
+    
+2.  **Tight Coupling**: Your sidebar link has to know the exact global ID of the main content area, making it harder to move components around.
+    
+
+## The Resolver Hierarchy
+
+When you click a `b-link` with a `b-target`, LegoJS follows a strict search order to resolve the target:
+
+### 1. Local Component Scope (The Primary Search)
+
+LegoJS first looks for the target **inside the component that contains the link**.
+
+If you use `b-target="email-view"`, Lego looks for an `<email-view>` tag _within the current parent shell_. This allows you to have multiple instances of the same layout on one screen without them interfering with each other.
+
+### 2. Tag Name Resolution (The Web Component Way)
+
+If your target doesn't start with a `#`, Lego treats it as a **Component Tag Name**.
+
+```
+<!-- Lego looks for a <thread-view> tag nearby -->
+<a href="/chat/1" b-link b-target="thread-view">Open Chat</a>
+
+<thread-view></thread-view>
+
+```
+
+This is the most "Enterprise" way to build. It makes your HTML self-documenting. You aren't targeting a generic `div`; you are targeting a specific functional slot.
+
+### 3. Global ID Fallback
+
+If no local tag or element matches, the resolver expands its search to the entire `document` using ID selectors.
+
+```
+<!-- Lego looks for any element with id="global-sidebar" -->
+<a href="/menu" b-link b-target="#global-sidebar">Menu</a>
+
+```
+
+### 4. The Router Default
+
+If the resolver exhausts all options and still can't find the target, it defaults to the `<lego-router>`. This ensures that even if you make a typo in your target name, the user still sees the content (it just might take over the whole page instead of a small fragment).
+
+## Advanced: The Functional Target
+
+For highly dynamic UIs, `b-target` can even be a function or a dynamic expression.
+
+```
+<!-- Logic decides the target based on screen size -->
+<a href="/settings" b-link b-target="{{ isMobile ? '#main' : 'settings-pane' }}">
+  Settings
+</a>
+
+```
+
+## Why This Matters
+
+By prioritizing local tags over global IDs, LegoJS encourages **Encapsulation**. Your components become "Black Boxes" that manage their own internal routing targets. This means you can take a complex "Messaging Shell" and drop it into a "Dashboard Shell" without changing a single line of routing code—the targets will still resolve correctly because they are scoped to their parents.
+
+## Summary
+
+The Target Resolver turns string attributes into intelligent DOM navigation. It respects the boundaries of your Web Components while providing a robust fallback system.
+