lego-dom 1.0.0 → 1.3.4

package/.legodom

@@ -0,0 +1,87 @@
+# LegoDOM Framework Definition (.legodom)
+
+This file defines the valid syntax, API, and behavior of the LegoDOM framework. Use this context to write valid `.lego` components and understand the runtime behavior.
+
+## 1. Component Structure (.lego)
+A `.lego` file is a Single File Component (SFC) composed of three sections:
+
+```html
+<template b-styles="optional-style-id">
+  <!-- HTML template with directives -->
+</template>
+
+<script>
+  export default {
+    // Reactive State
+    count: 0,
+    
+    // Lifecycle Hooks
+    mounted() { console.log('Mounted'); },
+    updated() { console.log('State updated'); },
+    unmounted() { console.log('Destroyed'); },
+
+    // Methods
+    increment() { this.count++ }
+  }
+</script>
+
+<style>
+  /* Scoped CSS. 'self' is replaced with ':host' automatically */
+  self { display: block; }
+  h1 { color: blue; }
+</style>
+```
+
+## 2. Template Directives
+
+| Directive | Syntax | Description |
+|-----------|--------|-------------|
+| **b-if** | `b-if="expr"` | Conditionally renders element if `expr` is truthy. Replaced by comment anchor if false. |
+| **b-show**| `b-show="expr"` | Toggles `display: none` based on `expr`. |
+| **b-for** | `b-for="item in list"` | Renders element for each item in `list`. `item` is available in scope. |
+| **b-text**| `b-text="path"` | Sets `textContent` to value at `path` (e.g. `user.name`). |
+| **b-html**| `b-html="expr"` | Sets `innerHTML` to result of `expr`. **Unsafe**. |
+| **b-sync**| `b-sync="path"` | Two-way binding for inputs. Updates `state.path` on input/change. |
+| **Event** | `@event="expr"` | Native event listener. `event` is available in scope. E.g. `@click="save()"`. |
+| **Interpolation** | `[[ expr ]]` | Text interpolation. Delimiters are `[[` and `]]` by default. |
+
+Note: `b-data` can be used on `<template>` or the custom element tag to inject initial state from JSON string.
+
+## 3. Script Context & Helpers
+The `script` exports a default object which becomes the reactive state (`this`).
+Inside methods and template expressions, the following helpers are available:
+
+### Scope
+- **this**: The reactive state of the component.
+- **event**: The native DOM event (only in `@event` handlers).
+
+### Helpers
+- **$element**: The component's host DOM element.
+- **$emit(name, detail)**: Dispatches a CustomEvent `name` with `detail` (bubbles: true, composed: true).
+- **$go(path, ...targets)**: Router navigation helper. Returns object with method calls.
+  - `this.$go('/url', '#target').get()`
+  - `this.$go('/api', '#response').post({data})`
+- **$ancestors(tagName)**: Finds the state of the nearest ancestor component with `tagName`.
+- **$registry(tagName)**: Access shared state of logical-only components defined via `Lego.define`.
+- **$route**: Global route state object.
+
+## 4. Router & Targets
+LegoDOM uses a "Target-Oriented" router. Navigation updates specific DOM elements (targets) rather than full page reloads.
+
+- **Definition**: `Lego.route('/path/:id', 'tag-name', middleware)`
+- **Targets**:
+  - `string`: CSS selector (e.g., `#main`, `user-card`).
+  - `function`: `(allComponents) => elements`
+- **Usage**:
+  - HTML: `<a href="/path" b-target="#main">Link</a>` creates a surgical navigation link.
+  - JS: `this.$go('/path', '#main').get()`
+
+## 5. Lifecycle Hooks
+- **mounted()**: Called when the component is attached to DOM, shadow root created, and initial render complete.
+- **updated()**: Called after reactive state changes have been batched and applied to the DOM.
+- **unmounted()**: Called when component is removed from the DOM.
+
+## 6. Global Configuration
+- `Lego.init(root, { styles: { ... }, loader: callback })`: Initializes the app.
+- `Lego.globals`: Global reactive state shared across all components.
+```

package/CHANGELOG.md

@@ -2,12 +2,96 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.3.4] - 2026-01-16
+
+### Improvements
+
+- **Minified Build:** Added a build script (`npm run build`) that uses `esbuild` to generate a `main.min.js` file, reducing file size by ~55% for optimal CDN performance.
+
+## [1.3.3] - 2026-01-16
+
+### Fixes
+
+- **Inline Arrays in `b-for`:** Fixed a bug where inline arrays like `b-for="item in [{ name: 'A' }, { name: 'B' }]"` would fail to render. The fix changes `b-for` to clone the entire node as a template instead of storing innerHTML.
+
+### Documentation
+
+- **Large Apps Guide:** Added "Scaling to Multi-Domain Apps" section for enterprise projects with multiple business domains (HRIS, Finance, Planning, etc.).
+
+### Improvements
+
+- **Vite Plugin:** Added `importPath` option to `legoPlugin()`, allowing developers to override where the `Lego` core is imported from (e.g., for local testing or custom builds).
+
+## [1.3.1] - 2026-01-16
+
+### Fixes
+
+- **`this.$emit()` in Script Methods:** `$emit` is now available on the component state, allowing event dispatching from script logic.
+  ```javascript
+  handleSave() {
+    this.$emit('save', { id: this.itemId });
+  }
+  ```
+
+## [1.3.0] - 2026-01-16
+
+### New Features
+
+- **`b-var` Directive:** Access DOM elements directly via `this.$vars.name`. Useful for triggering `.click()`, `.focus()`, or `.play()` on hidden inputs, video elements, etc.
+  ```html
+  <input type="file" b-var="fileInput" style="display:none">
+  <button @click="$vars.fileInput.click()">Upload</button>
+  ```
+
+### Documentation
+
+- **New Guide: Large Apps ("Chaos Tends To A Minimum"):** Added a comprehensive architectural guide for structuring enterprise-scale projects with 200+ components. Introduces the Blocks, Widgets, Components, Pages hierarchy to cleanly separate Identity, Intent, Computation, and Coordination.
+- **`b-if` Directive:** Documented the `b-if` directive for conditional rendering (DOM insertion/removal).
+- **`b-text` Directive:** Documented the limited `b-text` directive (property paths only, no expressions).
+- **Directives "See Also":** Added cross-references to `b-target`, `b-id`, `b-styles` in the Directives guide.
+
+## [1.2.0] - 2026-01-15
+
+**Breaking Change: New Template Syntax** 🚨
+To ensure compatibility with server-side frameworks (Jinja, Django, Flask) and JavaScript template literals, **LegoDOM now uses `[[ ]]` by default** instead of `{{ }}`.
+
+- **Breaking:** Default interpolation syntax changed from `{{ variable }}` to `[[ variable ]]`.
+- **Feature:** Added `Lego.config.syntax` to configure delimiters.
+    - Set to `'mustache'` to revert to `{{ }}`.
+    - Set to `'brackets'` (default) for `[[ ]]`.
+- **Feature:** Added support for snake_case, PascalCase, camelCase, and kebab-case component names for `.lego` files.
+- **Feature:** Added `Lego.config.loader` to fetch SFCs from a server endpoint.
+- **Fix:** Fixed a critical bug where `snap()` triggered double renders and mounted hooks.
+
+## [1.1.0] - 2026-01-12
+
+**The Enterprise Readiness Update** 
+This release focuses on Security, Performance, and Resilience, making LegoDOM suitable for high-traffic production environments.
+
+### Security Hardening
+
+- **Secure Expression Evaluation:** Implemented a new `safeEval` validator that blocks dangerous keywords (e.g., `function`, `eval`, `constructor`) to prevent arbitrary code execution.
+- **XSS Protection:** `safeEval` now automatically escapes output by default.
+- **New `b-html` Directive:** Added `b-html` for safely rendering raw HTML content (replacing `innerHTML`), requiring explicit opt-in for potential XSS risks.
+
+### Performance
+
+- **Expression Caching:** Compiled expressions are now cached in a `WeakMap`, transforming `O(n)` compilation costs into `O(1)` for repeated renders. This yields a massive performance boost for large lists (`b-for`).
+- **Optimized Binding:** Replaced `querySelectorAll('*')` with `TreeWalker`, significantly reducing memory allocation and DOM traversal time during component initialization.
+
+### Resilience & Scalability
+
+- **Global Error Handling:** Introduced `Lego.config.onError` hook for centralized error reporting (compatible with Sentry/Datadog).
+- **Graceful Rendering:** Rendering errors (e.g., accessing undefined properties in `{{ }}`) are now caught and reported, but do not crash the component or application.
+- **Memory Management:** Fixed nested component lifecycle issues where Shadow DOM children were not correctly tracked, preventing memory leaks in complex trees.
+- **Monitoring Plugin:** Added performance monitoring hooks (`onRenderStart`, `onRenderEnd`) and a new `monitoring-plugin.js` for realtime metrics.
+
 ## [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
+### 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.
@@ -21,7 +105,7 @@ LegoDOM moves out of beta with a finalized API, robust routing, and a hybrid ren
     - **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
+### Improvements
 
 - **Router:**
     - Exposed `$go(path, ...targets).get()` for programmatic surgical navigation.
@@ -37,7 +121,7 @@ LegoDOM moves out of beta with a finalized API, robust routing, and a hybrid ren
     - 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
+### 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).

package/cdn.html

@@ -56,8 +56,8 @@
       }
     </style>
 
-    <h3>{{title}}</h3>
-    <p>{{ items.filter(t => !t.done).length }} of {{ items.length }} items remaining</p>
+    <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">
       <button @click="() => {
@@ -71,7 +71,7 @@
     <div b-for="todo in items">
       <div class="item-row {{todo.done ? 'done' : ''}}">
         <input type="checkbox" b-sync="todo.done">
-        <span>{{todo.text}}</span>
+        <span>[[todo.text]]</span>
       </div>
     </div>
   </template>
@@ -96,8 +96,8 @@
       }
     </style>
 
-    <h3>{{name}}</h3>
-    <p>{{bio}}</p>
+    <h3>[[name]]</h3>
+    <p>[[bio]]</p>
     <slot></slot>
   </template>
 
@@ -119,6 +119,11 @@
         }">
     </todo-list>
   </user-card>
+  <script>
+    // Initialize Lego
+    // We need to wait for DOM, but script at end of body is fine
+    Lego.init();
+  </script>
 </body>
 
 </html>

package/docs/.vitepress/config.js

@@ -10,14 +10,15 @@ export default defineConfig({
 
     nav: [
       { text: 'Guide', link: '/guide/' },
+      { text: 'Tutorial', link: '/tutorial/' },
       { text: 'Contributing', link: '/contributing/' },
       { text: 'API', link: '/api/' },
       { text: 'Examples', link: '/examples/' },
       { text: 'Router', link: '/router/' },
       {
-        text: 'v1.0.0',
+        text: 'v1.3.4',
         items: [
-          { text: 'Changelog', link: 'https://github.com/rayattack/LegoJS/releases' }
+          { text: 'Changelog', link: 'https://github.com/rayattack/LegoDOM/releases' }
 
         ]
       }
@@ -48,14 +49,26 @@ export default defineConfig({
           ]
         }
       ],
+      '/tutorial/': [
+        {
+          text: 'Tutorial: Your First App',
+          items: [
+            { text: 'Overview', link: '/tutorial/' },
+            { text: '1. Project Setup', link: '/tutorial/01-project-setup' },
+            { text: '2. Your First Component', link: '/tutorial/02-your-first-component' },
+            { text: '3. Adding Routes', link: '/tutorial/03-adding-routes' },
+            { text: '4. Multi-Page App', link: '/tutorial/04-multi-page-app' },
+            { text: '5. State & Globals', link: '/tutorial/05-state-and-globals' }
+          ]
+        }
+      ],
       '/guide/': [
         {
           text: 'Introduction',
           items: [
-            { text: 'What is Lego?', link: '/guide/' },
+            { text: 'What is LegoDOM?', link: '/guide/' },
             { text: 'Getting Started', link: '/guide/getting-started' },
             { text: 'Quick Start', link: '/guide/quick-start' },
-            { text: 'Contributing', link: '/guide/contributing' }
           ]
         },
         {
@@ -73,7 +86,9 @@ export default defineConfig({
             { text: 'Single File Components', link: '/guide/sfc' },
             { text: 'Routing', link: '/guide/routing' },
             { text: 'CDN Usage', link: '/guide/cdn-usage' },
-            { text: 'Lifecycle Hooks', link: '/guide/lifecycle' }
+            { text: 'Lifecycle Hooks', link: '/guide/lifecycle' },
+            { text: 'Large Apps', link: '/guide/directory-structure' },
+            { text: 'FAQ', link: '/guide/faq' }
           ]
         }
       ],
@@ -85,6 +100,7 @@ export default defineConfig({
             { text: 'Lego.define()', link: '/api/define' },
             { text: 'Lego.route()', link: '/api/route' },
             { text: 'Lego.globals', link: '/api/globals' },
+            { text: 'Lego.config', link: '/api/config' },
             { text: 'Directives', link: '/api/directives' },
             { text: 'Lifecycle Hooks', link: '/api/lifecycle' },
             { text: 'Vite Plugin', link: '/api/vite-plugin' }
@@ -118,7 +134,7 @@ export default defineConfig({
     },
 
     socialLinks: [
-      { icon: 'github', link: 'https://github.com/rayattack/LegoJS' }
+      { icon: 'github', link: 'https://github.com/rayattack/LegoDOM' }
     ],
 
     footer: {
@@ -131,7 +147,7 @@ export default defineConfig({
     },
 
     editLink: {
-      pattern: 'https://github.com/rayattack/LegoJS/edit/main/docs/:path',
+      pattern: 'https://github.com/rayattack/LegoDOM/edit/main/docs/:path',
       text: 'Edit this page on GitHub'
     }
   },

package/docs/api/config.md

@@ -0,0 +1,95 @@
+# Global Configuration
+
+`Lego.config` allows you to customize framework behavior, including error handling and metrics.
+
+## Properties
+
+### `syntax`
+
+*   **Type**: `'mustache' | 'brackets'`
+*   **Default**: `'brackets'`
+
+Configures the template delimiter style.
+
+*   `'brackets'`: Uses <code v-pre>[[ variable ]]</code> (Default)
+*   `'mustache'`: Uses <code v-pre>{{ variable }}</code> (Legacy/Vue-style)
+
+```javascript
+// Switch back to mustache syntax if preferred
+Lego.config.syntax = 'mustache';
+```
+
+### `loader`
+
+*   **Type**: `(tagName: string) => string | Promise<string> | null`
+*   **Default**: `undefined`
+
+Use this hook to implement **Server-Side Component Delivery**.
+
+**Option 1: Simple Mode (Return URL)**
+We fetch it for you.
+```javascript
+loader: (tag) => `/components/${tag}.lego`
+```
+
+**Option 2: Power Mode (Return Promise)**
+You control the fetch. Useful for **Authentication** (Cookies, JWT) or Custom Headers.
+
+```javascript
+Lego.init(document.body, {
+  loader: async (tagName) => {
+    // Custom Authenticated Fetch
+    const res = await fetch(`/components/${tagName}.lego`, {
+      credentials: 'include', // Send Cookies
+      headers: { 'Authorization': getToken() }
+    });
+    return await res.text(); // Return SFC content directly
+  }
+});
+```
+**Mechanism:**
+1. Browser sees unknown `<admin-widget>`.
+2. `Lego` calls `config.loader('admin-widget')`.
+3. If URL returned, it fetches the file.
+4. The server returns raw SFC content (`<template>...`).
+5. `Lego.defineSFC()` parses and upgrades the element instantly.
+
+### `onError`
+
+*   **Type**: `(error: Error, type: string, context: HTMLElement) => void`
+*   **Default**: `undefined`
+
+Global error handler hook. Called when an error occurs during:
+*   `render`: Template rendering (expression evaluation)
+*   `event-handler`: `@event` callbacks
+*   `define`: Component definition
+*   `sync-update`: `b-sync` updates
+
+```javascript
+Lego.config.onError = (err, type, context) => {
+  console.error(`Error in ${type}:`, err);
+  // Send to Sentry/Datadog
+  captureException(err, { tags: { type } });
+};
+```
+
+### `metrics`
+
+*   **Type**: `Object`
+
+Performance monitoring hooks, primarily used by plugins.
+
+*   `onRenderStart(el)`: Called before a component renders.
+*   `onRenderEnd(el)`: Called after a component finishes rendering.
+
+```javascript
+// Example monitoring implementation
+Lego.config.metrics = {
+  onRenderStart(el) {
+    console.time(el.tagName);
+  },
+  onRenderEnd(el) {
+    console.timeEnd(el.tagName);
+  }
+};
+```

package/docs/api/define.md

@@ -21,11 +21,38 @@ import { Lego } from 'lego-dom';
 
 Lego.define('user-card', `
   <div class="card">
-    <h3>{{ name }}</h3>
-    <p>{{ role }}</p>
+    <h3>[[ name ]]</h3>
+    <p>[[ role ]]</p>
   </div>
 `, {
   name: 'John Doe',
   role: 'Admin'
 });
 ```
+
+## Lego.defineSFC()
+
+Runtime parser for Single File Components (SFC). Useful for **Server-Side Rendering** or dynamic loading architectures.
+
+```ts
+Lego.defineSFC(content: string, filename?: string)
+```
+
+### Example
+
+```javascript
+const sfc = `
+<template>
+  <h1>[[ title ]]</h1>
+</template>
+<script>
+  export default { title: 'Hello World' }
+</script>
+<style>
+  h1 { color: red; }
+</style>
+`;
+
+// Registers <my-component> instantly
+Lego.defineSFC(sfc, 'my-component.lego');
+```

package/docs/api/directives.md

@@ -11,6 +11,14 @@ Conditionally render an element.
 <div b-show="!loading">Content loaded!</div>
 ```
 
+## b-html
+
+Renders raw HTML. **Security Risk**: Use with caution.
+
+```html
+<div b-html="htmlContent"></div>
+```
+
 ## b-for
 
 Render a list of items.
@@ -18,7 +26,7 @@ Render a list of items.
 ```html
 <ul>
   <li b-for="user in users">
-    {{ user.name }}
+    [[ user.name ]]
   </li>
 </ul>
 ```
@@ -29,7 +37,7 @@ Two-way data binding for form inputs.
 
 ```html
 <input b-sync="username" placeholder="Enter username">
-<p>You typed: {{ username }}</p>
+<p>You typed: [[ username ]]</p>
 ```
 
 ## @event

package/docs/api/index.md

@@ -7,6 +7,7 @@ Welcome to the Lego API documentation.
 - [Lego.define()](/api/define) - Defining components
 - [Lego.route()](/api/route) - Client-side routing
 - [Lego.globals](/api/globals) - Global state
+- [Lego.config](/api/config) - Configuration & Error Handling
 - [Lifecycle Hooks](/api/lifecycle) - Component lifecycle methods
 
 ## Templates & Binding

package/docs/contributing/01-welcome.md

@@ -6,8 +6,10 @@ LegoDOM is wrapped in an **IIFE** (Immediately Invoked Function Expression) assi
 const Lego = (() => {
   // ... all the logic ...
   return {
+    init: () => { ... },
     init: () => { ... },
     define: (tagName, templateHTML, logic = {}) => { ... },
+    defineSFC: (content, filename) => { ... }, // Runtime SFC Parser
     // ...
   };
 })();

package/docs/contributing/02-registry.md

@@ -94,6 +94,40 @@ async load(id) {
         
     -   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.
+    -   **Result:** You just create a file named `user-card.lego`, and suddenly `<user-card>` is a valid HTML tag in your app.
+
+**Paradigm 3: Runtime Component Definition (New in v2.0)**
+
+```js
+defineSFC: (content, filename) => {
+  // Regex parsing of <template>, <script>, <style>
+  const templateMatch = content.match(/<template([\s\S]*?)>([\s\S]*?)<\/template>/);
+  // ...
+  const logicObj = new Function(`return ${script}`)();
+  // ...
+  sfcLogic.set(name, logicObj);
+}
+```
+
+This is the power behind the **Server Loader**. We can fetch a string from the server and "compile" it in the browser using `new Function()`. It populates `registry` and `sfcLogic` just like the build-time tools, but on the fly.
+
+### 4. Component Naming Conventions ("Explicit or Go Home")
+
+When you define a component via a file (e.g. `.lego`), the library automatically derives the tag name. To keep the web platform happy, we enforce **Custom Element Best Practices**:
+
+1.  **Automatic Conversion**: All filenames are converted to `kebab-case`.
+    -   `UserProfile.lego` -> `<user-profile>`
+    -   `navBar.lego` -> `<nav-bar>`
+    -   `data_table.lego` -> `<data-table>`
+    
+2.  **The Hyphen Rule**: A custom element **MUST** contain a hyphen.
+    -   `Button.lego` -> Error
+    -   `Adidas.lego` -> Error
+
+> [!TIP]
+> **Single Word Component? Namespace It!** 
+> Custom Element specs require a hyphen to distinguish from native tags. To ensure forward compatibility, **LegoDOM will throw an error** if you try to define a single-word component.
+> Simply add your app or product prefix to the filename:
+> -   `fb-button.lego` -> `<fb-button>`
+> -   `shop-card.lego` -> `<shop-card>`
+> -   `mobile-button.lego` -> `<mobile-button>`

package/docs/contributing/06-init.md

@@ -77,13 +77,24 @@ This is the most critical part of the initialization. The library creates a `Mut
 
 ```js
 const observer = new MutationObserver(m => m.forEach(r => {
-  r.addedNodes.forEach(n => n.nodeType === Node.ELEMENT_NODE && snap(n));
+  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.
+- **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.
     

package/docs/contributing/07-observer.md

@@ -27,6 +27,9 @@ Whenever a new piece of HTML is injected (via `innerHTML`, `appendChild`, etc.),
 -   **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`

package/docs/contributing/08-snap.md

@@ -19,6 +19,11 @@ const snap = (el) => {
     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) || {};
 
@@ -32,7 +37,10 @@ const snap = (el) => {
     el._studs = reactive({
       ...scriptLogic,
       ...templateLogic,
-      ...instanceLogic
+      ...instanceLogic,
+      // Inject Global Helpers
+      get $route() { return Lego.globals.$route },
+      get $go() { return Lego.globals.$go }
     }, el);
 
     shadow.appendChild(tpl);
@@ -83,6 +91,12 @@ 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

package/docs/contributing/10-studs.md

@@ -25,7 +25,9 @@ Once `snap()` has merged the data from the SFC (Tier 1), the Template (Tier 2),
   el._studs = reactive({
     ...scriptLogic,
     ...templateLogic,
-    ...instanceLogic
+    ...instanceLogic,
+    get $route() { return Lego.globals.$route },
+    get $go() { return Lego.globals.$go }
   }, el);
   //... rest of code
 ```

package/docs/contributing/11-scanner.md

@@ -52,6 +52,19 @@ const scanForBindings = (container) => {
 };
 ```
 
+## Why Regex? (The "Forbidden" Choice)
+
+You will notice we use Regular Expressions to find bindings.
+
+**"Regex is bad for HTML!"** they say.
+Usually, yes. But we are not parsing *arbitrary* HTML to build a DOM. We are scanning *specific known tokens* inside trusted templates.
+
+**The Trade-off:**
+- **AST Parser**: Reliable, but heavy (10kb+).
+- **Regex Scanner**: Good enough for 99% of bindings, extremely light (<1kb).
+
+Since LegoDOM targets **speed** and **size** (<4kb), Regex is the correct architectural choice. We mitigate edge cases by ignoring bindings inside `<script>` and `<style>` blocks.
+
 ### 1. The `TreeWalker` Efficiency
 
 LegoDOM uses a native browser tool called a `TreeWalker`.