@dooboostore/simple-web-component 1.0.26 → 1.0.27

package/README.md

@@ -3,3583 +3,328 @@
 [![Build and Test](https://github.com/dooboostore-develop/packages/actions/workflows/main.yaml/badge.svg?branch=main)](https://github.com/dooboostore-develop/packages/actions/workflows/main.yaml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
 
-> **"Pure, Standards-Compliant, and Blazing Fast Web Components Framework."**
 
-`simple-web-component` (SWC) is a minimalist library designed for building high-performance Web Components and Single Page Applications (SPA). It follows a **Pure Architecture** that adheres strictly to browser standards, avoiding heavy Proxy traps or Virtual DOM overhead.
+**SWC** is a lightweight, production-ready Web Components framework for building fast, modular, and maintainable SPAs without Virtual DOM overhead.
 
 ---
 
-## 🚀 Why SWC?
+## 🎯 Core Features
 
-- **Zero Magic**: No Proxy traps, no Virtual DOM diffing. Predictive and standard-compliant.
-- **Native Inheritance**: Inherit directly from `HTMLElement`, `HTMLDivElement`, or `HTMLTemplateElement`.
-- **Extreme Performance**: Ideal for high-load UIs (1,000+ nodes) with minimal memory overhead.
-- **Micro-Frontend Ready**: Independent routing and DI containers for every component scope.
-- **Standard-First**: Works directly with native Custom Elements, Shadow DOM, and Slots.
-
----
-
-## 📦 Installation & Setup
-
-```bash
-npm install @dooboostore/simple-web-component reflect-metadata
-```
-
-### Browser Support
-For **Safari** support of the `is` attribute, add this to your `<head>`:
-```html
-<script src="https://unpkg.com/@ungap/custom-elements"></script>
-```
-
----
-
-## 💡 Complete Decorator Reference
-
-### Lifecycle Decorators
-
-#### 1. `@onConstructor()`
-Called during component construction (in `constructor`). Perfect for dependency injection setup.
+### 1. **@elementDefine** - Component Registration
+Register Web Components with automatic lifecycle management and DI support.
 
 ```typescript
 @elementDefine('my-component')
 class MyComponent extends HTMLElement {
-  private dataService: DataService;
-
-  @onConstructor
-  setupDI(dataService: DataService) {
-    this.dataService = dataService;
-    console.log('Component constructed with DI');
-  }
-}
-```
-
-**Execution Order**: First - during `new MyComponent()`
-
-#### 2. `@onBeforeConnected()`
-**Dependency Injection & Pre-connection Setup**
-
-Called before the component connects to the DOM. Perfect for initializing services via DI.
-
-**⚠️ Important**: Lifecycle DI works **WITHOUT `@Sim`** - regular `@elementDefine` components can receive services here!
-
-```typescript
-@elementDefine('my-component')  // ← NO @Sim needed for lifecycle DI
-class MyComponent extends HTMLElement {
-  #cartService: CartService;
-  #subscription?: Subscription;
-
-  // Lifecycle DI injection - works even without @Sim
-  @onBeforeConnected
-  async setupComponent(cartService: CartService) {
-    this.#cartService = cartService;
-    
-    // Can be async - waits before rendering
-    await this.#cartService.load();
-    
-    // Subscribe to reactive updates
-    this.#subscription = this.#cartService.store.subscribe(state => {
-      this.updateUI();
-    });
-  }
-
-  disconnectedCallback() {
-    this.#subscription?.unsubscribe();
-  }
-
-  @onConnectedInnerHtml
-  render() {
-    return `<div>Component ready</div>`;
-  }
-}
-```
-
-**Key Features:**
-- ✅ Services automatically injected via lifecycle decorators
-- ✅ **NO `@Sim` required** for lifecycle DI injection
-- ✅ Can be async - waits before rendering
-- ✅ Called once, before `connectedCallback`
-- ✅ Perfect for initialization and subscriptions
-
-**DI Injection Methods:**
-
-| Method | Requires `@Sim`? | Location |
-|--------|-----------------|----------|
-| Lifecycle (`@onBeforeConnected`) | ❌ NO | Lifecycle decorators |
-| Constructor Injection | ✅ YES | Inside `<swc-app>` only |
-| Static Registration | ✅ YES | `<swc-app>` DI container |
-
-**Execution Order**: Before `connectedCallback()`
-
-#### 3. `@onAfterConnected()` / `@onConnected()`
-Called after the component connects to the DOM. For post-render operations.
-
-```typescript
-@elementDefine('my-element')
-class MyElement extends HTMLElement {
-  @onAfterConnected  // or @onConnected (alias)
-  initializeAfterConnect() {
-    console.log('Element fully connected to DOM');
-    this.focus();  // Can interact with DOM now
-    
-    // Measure element size after render
-    const rect = this.getBoundingClientRect();
-    console.log('Size:', rect.width, rect.height);
+  @onInitialize
+  constructor(private service: MyService) {
+    super();
   }
 }
 ```
 
-**Execution Order**: After `connectedCallback()`
-
-#### 4. `@onBeforeDisconnected()`
-Called before the component disconnects from the DOM. For cleanup preparation.
+### 2. **Dependency Injection (@onInitialize)**
+Inject services into Web Components using the `@onInitialize` decorator.
 
 ```typescript
-@elementDefine('event-listener-component')
-class EventListenerComponent extends HTMLElement {
-  private resizeObserver: ResizeObserver;
-
-  @onBeforeDisconnected
-  prepareForDisconnect() {
-    console.log('About to disconnect, saving state...');
-    // Save state, cancel pending requests, etc.
-    const state = {
-      scrollPosition: window.scrollY,
-      formData: this.getFormData()
-    };
-    localStorage.setItem('component-state', JSON.stringify(state));
-  }
-
-  @onAfterDisconnected
-  cleanup() {
-    this.resizeObserver?.disconnect();
-    console.log('Cleanup completed');
+@elementDefine('dashboard')
+class Dashboard extends HTMLElement {
+  @onInitialize
+  constructor(
+    @Inject({ symbol: UserService.SYMBOL }) userService: UserService
+  ) {
+    super();
+    this.userService = userService;
   }
 }
 ```
 
-**Execution Order**: Before `disconnectedCallback()`
+### 3. **Declarative DOM Updates**
 
-#### 5. `@onAfterDisconnected()` / `@onDisconnected()`
-Called after the component disconnects from the DOM. Final cleanup.
+#### @onConnectedInnerHtml
+Render HTML automatically when component connects to DOM.
 
 ```typescript
-@elementDefine('resource-component')
-class ResourceComponent extends HTMLElement {
-  private timerId: number;
-  private subscription: Subscription;
-
-  @onAfterDisconnected  // or @onDisconnected (alias)
-  cleanup() {
-    // Cancel timers
-    clearTimeout(this.timerId);
-    
-    // Unsubscribe from observables
-    this.subscription?.unsubscribe();
-    
-    console.log('Resources cleaned up');
-  }
+@onConnectedInnerHtml({ useShadow: true })
+render() {
+  return `<div>Hello, <span>${this.name}</span>!</div>`;
 }
 ```
 
-**Execution Order**: After `disconnectedCallback()`
-
-#### 6. `@onBeforeAdopted()`
-Called before the element is adopted by a new document (useful for SSR/iframe scenarios).
+#### @applyInnerHtmlNodeHost
+Apply HTML to specific host element.
 
 ```typescript
-@elementDefine('document-aware')
-class DocumentAware extends HTMLElement {
-  @onBeforeAdopted
-  prepareForAdoption() {
-    console.log('Adopting to new document...');
-    // Prepare for document change
-  }
+@applyInnerHtmlNodeHost({ root: 'light' })
+updateContent() {
+  return `<p>Updated content</p>`;
 }
 ```
 
-#### 7. `@onAfterAdopted()` / `@onAdopted()`
-Called after the element is adopted by a new document.
+#### @applyReplaceChildrenNodeHost
+Replace child nodes with new content.
 
 ```typescript
-@elementDefine('iframe-component')
-class IframeComponent extends HTMLElement {
-  @onAfterAdopted  // or @onAdopted (alias)
-  onDocumentAdopted() {
-    console.log('Now in new document context');
-    // Re-attach to new document's resources
-    this.initializeInNewDocument();
-  }
-
-  private initializeInNewDocument() {
-    // Setup for new document
-  }
+@applyReplaceChildrenNodeHost({ root: 'light' })
+replaceChildren(node: Node) {
+  return node;
 }
 ```
 
-#### 8. `@onAddEventListener()`
-Called when an event listener is added to the element. For event tracking/analytics.
-
-```typescript
-@elementDefine('event-tracked')
-class EventTracked extends HTMLElement {
-  @onAddEventListener
-  onListenerAdded(type: string, listener: EventListener, options?: AddEventListenerOptions) {
-    console.log(`Event listener added: ${type}`);
-    // Track event listeners for debugging
-  }
-}
-```
+### 4. **Event Handling**
 
-#### 9. `@onConnectedInnerHtml(options?)`
-Defines the component's template. Renders to Shadow DOM or Light DOM based on `useShadow` option.
+#### @addEventListener
+Attach event listeners to elements.
 
 ```typescript
-@elementDefine('styled-card')
-class StyledCard extends HTMLElement {
-  @onConnectedInnerHtml({ useShadow: true })
-  render() {
-    return `
-      <style>
-        :host {
-          display: block;
-          padding: 20px;
-          border-radius: 8px;
-          background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
-        }
-      </style>
-      <div class="card-content">
-        <slot></slot>
-      </div>
-    `;
-  }
+@addEventListener('#submit-btn', 'click')
+onSubmit(event: Event) {
+  console.log('Submitted');
 }
 ```
 
-**Options:**
-- `useShadow: true` - Render to Shadow DOM (style encapsulation)
-- `useShadow: false` - Render to Light DOM (default)
-
----
-
-### Attribute & Property Decorators
-
-#### 10. `@attributeHost`
-Bidirectional attribute binding with automatic type conversion on `:host` element.
-
-All usage patterns support automatic field-name-to-attribute-name conversion:
-- Without parentheses: `@attributeHost` - uses field name as attribute name
-- Empty parentheses: `@attributeHost()` - uses field name as attribute name
-- Options only: `@attributeHost({ connectedInitialize: true })` - uses field name as attribute name
-- Custom name: `@attributeHost('custom-name')` - explicit attribute name
-- Custom name + options: `@attributeHost('custom-name', { type: Boolean })` - both specified
+#### @emitCustomEvent
+Emit custom events with data.
 
 ```typescript
-@elementDefine('input-field')
-class InputField extends HTMLElement {
-  @attributeHost
-  value: string = '';
-
-  @attributeHost('disabled')
-  disabled: boolean = false;
-
-  @attributeHost({ type: Number })
-  count: number = 0;
-
-  @onConnectedInnerHtml
-  render() {
-    return `
-      <input type="text" value="${this.value}" ${this.disabled ? 'disabled' : ''}>
-      <p>Count: ${this.count}</p>
-    `;
-  }
+@emitCustomEvent(':appHost', 'user-login')
+async onLogin() {
+  const user = await this.authService.login();
+  return { user };  // Sent as event detail
 }
 ```
 
-**Options:**
-- `connectedInitialize: true` - Push class value to DOM on connect
-- `connectedInitialize: false` - Pull DOM value on connect (default)
-- Auto-converts: `String`, `Number`, `Boolean`
-
-#### 11. `@changedAttributeHost(name)`
-Reactive handler triggered when attribute changes.
+#### @emitCustomEventHost
+Emit events from a method with custom event name mapping.
 
 ```typescript
-@elementDefine('reactive-input')
-class ReactiveInput extends HTMLElement {
-  private internalValue = '';
-
-  @changedAttributeHost('value')
-  onValueChange(newVal: string, oldVal: string) {
-    console.log(`Value changed: ${oldVal} → ${newVal}`);
-    this.internalValue = newVal;
-    this.updateDisplay();
-  }
-
-  updateDisplay() {
-    const input = this.querySelector('input') as HTMLInputElement;
-    if (input) input.value = this.internalValue;
-  }
+@emitCustomEventHost('navigate', { attributeName: 'on-navigate' })
+onNavClick(e: any) {
+  return { path: e.target.dataset.path };
 }
 ```
 
-#### 12. `@applyAttribute(selector, action?, options?)` - Universal Attribute Manipulation
+### 5. **DOM Querying**
 
-Universal decorator for handling attributes with flexible strategies.
+#### @query
+Query single element (Light DOM by default).
 
 ```typescript
-@elementDefine('attribute-demo')
-class AttributeDemo extends HTMLElement {
-  private status = 'active';
-  private priority = 1;
-
-  // Set attribute (replace all)
-  @applyAttribute('.status', 'set')
-  setStatus() {
-    return { 'data-status': this.status, 'aria-busy': 'false' };
-  }
-
-  // Update attribute (merge)
-  @applyAttribute('.priority', 'update')
-  updatePriority() {
-    return { 'data-priority': this.priority.toString() };
-  }
-
-  // Remove attribute
-  @applyAttribute('.temp', 'remove')
-  removeTemp() {
-    return ['data-temp'];
-  }
+@query('#form-input')
+formInput?: HTMLInputElement;
 
-  @onConnectedInnerHtml
-  render() {
-    return `
-      <div class="status">Status: ${this.status}</div>
-      <div class="priority">Priority: ${this.priority}</div>
-      <div class="temp">Temporary</div>
-    `;
-  }
-}
+@query('.card', { root: 'shadow' })
+shadowCard?: HTMLElement;
 ```
 
-**Convenience Methods** (specific actions):
-
-#### 12a. `@setAttribute(selector, name, options?)` - Set Single Attribute
-Reflect method's return value to a target element's DOM attribute. One-way binding (class → DOM).
+#### @queryAll
+Query multiple elements.
 
 ```typescript
-@elementDefine('status-badge')
-class StatusBadge extends HTMLElement {
-  private status: 'active' | 'inactive' | 'pending' = 'pending';
-  private items: any[] = [];
-
-  // Reflect status to host element's data-status attribute
-  @setAttribute(':host', 'data-status')
-  getStatus() {
-    return this.status;
-  }
-
-  // Reflect computed data to specific element
-  @setAttribute('#count-display', 'data-count')
-  getItemCount() {
-    return this.items.length.toString();
-  }
-
-  // Reflect to Shadow DOM element's aria-label
-  @setAttribute('.badge-label', 'aria-label', { root: 'shadow' })
-  getAriaLabel() {
-    return `Status is ${this.status}`;
-  }
-
-  @onConnectedInnerHtml
-  render() {
-    return `
-      <div data-status="${this.status}">
-        <span class="badge-label">Status: ${this.status}</span>
-        <span id="count-display" data-count="${this.items.length}">Items: ${this.items.length}</span>
-      </div>
-    `;
-  }
+@queryAll('input[type="text"]')
+textInputs?: HTMLInputElement[];
 
-  // Change status and update DOM attributes
-  setStatus(newStatus: typeof this.status) {
-    this.status = newStatus;
-    this.getStatus();        // Updates :host[data-status]
-    this.getItemCount();     // Updates #count-display[data-count]
-    this.getAriaLabel();     // Updates .badge-label[aria-label]
-  }
-}
+@queryAll('li', { root: 'shadow' })
+listItems?: HTMLLIElement[];
 ```
 
-**Signature:**
-- `@setAttribute(selector, attributeName, options?)`
-- Returns method's value → reflects to target's attribute
-
-#### 12c. `@updateAttribute(selector, name, options?)` - Update Attribute
-
-Merge return value with existing attributes instead of replacing.
+#### @queryHost
+Query the component element itself.
 
 ```typescript
-@updateAttribute(':host', 'data-modified')
-updateModifiedTime() {
-  return new Date().toISOString();
-}
-```
-
-#### 12d. `@removeAttribute(selector, name, options?)` - Remove Attribute
+@queryHost
+self?: HTMLElement;
 
-Remove specific attributes from target elements.
-
-```typescript
-@removeAttribute('.disabled-item', 'data-active')
-removeActive() {
-  return true;  // Remove if truthy
+printTag() {
+  console.log(this.self?.tagName);  // CUSTOM-CARD
 }
 ```
 
-**Selectors:**
-- `':host'` - The component itself
-- `'#element-id'` - Element by ID
-- `'.class-name'` - Element by class
-- `selector` - Any CSS selector
-
-#### 12e. `@setAttributeHost(name, options?)` - Shorthand for `:host`
-Simplified version of `@setAttribute` that always targets `:host`.
+#### @queryAllHost
+Query all direct children of the component.
 
 ```typescript
-@elementDefine('counter')
-class Counter extends HTMLElement {
-  private count = 0;
-
-  // Equivalent to @setAttribute(':host', 'aria-label')
-  @setAttributeHost('aria-label')
-  getAriaLabel() {
-    return `Count is ${this.count}`;
-  }
-
-  @setAttributeHost('data-count')
-  getCountValue() {
-    return this.count.toString();
-  }
-
-  @setAttributeHost('aria-disabled')
-  getDisabledState() {
-    return (this.count >= 10).toString();
-  }
+@queryAllHost
+children?: HTMLElement[];
 
-  @onConnectedInnerHtml
-  render() {
-    return `
-      <div>
-        <p>Count: ${this.count}</p>
-        <button swc-on-click="$host.increment()">+</button>
-      </div>
-    `;
-  }
-
-  increment() {
-    this.count++;
-    this.getAriaLabel();      // Updates :host[aria-label]
-    this.getCountValue();     // Updates :host[data-count]
-    this.getDisabledState();  // Updates :host[aria-disabled]
-  }
+getChildCount() {
+  return this.children?.length ?? 0;
 }
 ```
 
-**Usage:**
-```typescript
-// Full form
-@setAttribute(':host', 'data-status')
-// vs
-// Shorthand for :host
-@setAttributeHost('data-status')
-```
-
-**Key Differences:**
-- **`@attributeHost`** - Two-way binding: DOM ↔ Class (Bidirectional)
-- **`@setAttribute`** - One-way binding: Class → DOM (Any selector)
-- **`@setAttributeHost`** - One-way binding: Class → DOM (`:host` only)
-- **`@changedAttributeHost`** - Watch DOM attribute changes (Reactive handler)
-
-**Options:**
-- `root: 'light'` - Set attribute on light DOM element
-- `root: 'shadow'` - Set attribute on shadow DOM element
-- `root: 'auto'` - Auto-detect (default)
-
----
-
-### Query & DOM Selection Decorators
+### 6. **Attribute Binding**
 
-#### 13. `@query(selector, options?)`
-Inject a single element into a property.
+#### @attribute
+Bind HTML attributes to properties (automatic sync).
 
 ```typescript
-@elementDefine('form-handler')
-class FormHandler extends HTMLElement {
-  @query('#submit-btn') submitBtn?: HTMLButtonElement;
-  @query('.form-field', { root: 'shadow' }) formField?: HTMLElement;
-  @query(':host') self?: HTMLElement;
-
-  @onConnectedInnerHtml({ useShadow: true })
-  render() {
-    return `
-      <div class="form-field">
-        <input type="text" placeholder="Enter name">
-        <button id="submit-btn">Submit</button>
-      </div>
-    `;
-  }
-}
-```
-
-**Root Options:**
-- `'auto'` (default) - Search shadow DOM first, then light DOM
-- `'light'` - Search only light DOM
-- `'shadow'` - Search only shadow DOM
-- `'all'` - Search both, return `[lightElements, shadowElements]`
+@attribute
+width: string = '100px';
 
-**Special Targets:**
-```typescript
-@query(':host') self?: HTMLElement;           // Element itself
-@query(':parentHost') parent?: HTMLElement;   // Parent SWC component
-@query(':appHost') app?: SwcAppInterface;     // Nearest <swc-app>
-@query(':window') win?: Window;               // Global window
-@query(':document') doc?: Document;           // Global document
+@attribute('data-id')
+resourceId: string = '';
 ```
 
-#### 14. `@queryAll(selector, options?)`
-Inject multiple elements as an array.
+#### @attributeHost
+Bind attributes on host element itself.
 
 ```typescript
-@elementDefine('list-renderer')
-class ListRenderer extends HTMLElement {
-  @queryAll('.item') items?: HTMLElement[];
-  @queryAll('button', { root: 'shadow' }) buttons?: HTMLButtonElement[];
+@attributeHost('product-id')
+productId: string = '';
 
-  getItemCount() {
-    return this.items?.length ?? 0;
+@onInitialize
+constructor() {
+  super();
+  if (this.productId) {
+    this.loadProduct(this.productId);
   }
 }
 ```
 
-#### 14b. Removing Elements via `null` or `undefined`
-Both `@query` and `@queryAll` support element removal by setting the property to `null` or `undefined`. This triggers automatic removal of the matching element(s).
+### 7. **Lifecycle Hooks**
 
 ```typescript
-@elementDefine('todo-list')
-class TodoList extends HTMLElement {
-  @query('.notification') notification?: HTMLElement;
-  @queryAll('.todo-item') todoItems?: HTMLElement[];
-
-  removeNotification() {
-    // Setting to null triggers automatic removal
-    this.notification = null;
-  }
-
-  removeTodoItem(id: string) {
-    // Find and remove a specific todo item
-    const item = this.querySelector(`[data-id="${id}"]`);
-    if (item) {
-      // Setting @query to null removes the element from DOM
-      this.notification = null;
-    }
-  }
-
-  clearAllTodos() {
-    // Setting @queryAll to null/undefined removes all matching elements
-    this.todoItems = null;  // Removes all .todo-item elements
-  }
-
-  @onConnectedInnerHtml
-  render() {
-    return `
-      <div class="notification">New todos available!</div>
-      <ul>
-        <li class="todo-item" data-id="1">Task 1</li>
-        <li class="todo-item" data-id="2">Task 2</li>
-        <li class="todo-item" data-id="3">Task 3</li>
-      </ul>
-      <button swc-on-click="$host.removeNotification()">Clear Notification</button>
-      <button swc-on-click="$host.clearAllTodos()">Clear All Tasks</button>
-    `;
-  }
+@onConnected
+onConnected() {
+  // Called when element enters DOM
 }
-```
 
-**Removal Rules:**
-- `@query`: Setting to `null` or `undefined` removes the single element
-- `@queryAll`: Setting to `null` or `undefined` removes all matching elements
-- Special selectors (`:host`, `:window`, `:document`, etc.) are **NOT removed** (protected)
-- Only affects Light DOM by default; use `{ root: 'shadow' }` to remove from Shadow DOM
-
-**Use Cases:**
-- Close notification banners
-- Clear dynamic list items
-- Remove temporary overlays
-- Clean up modal dialogs
-
-#### 15. `@queryHost` - Query :host Element
-Specialized query for the component element itself. Supports automatic or explicit usage.
-
-All usage patterns automatically set the element reference:
-- Without parentheses: `@queryHost` self?: HTMLElement;
-- Empty parentheses: `@queryHost()` self?: HTMLElement;
-- With options: `@queryHost({ root: 'shadow' })` self?: HTMLElement;
-
-```typescript
-@elementDefine('custom-card')
-class CustomCard extends HTMLElement {
-  @queryHost
-  self?: HTMLElement;
-  
-  @queryHost()
-  selfExplicit?: HTMLElement;
-
-  printTag() {
-    console.log(this.self?.tagName); // Logs: CUSTOM-CARD
-  }
+@onDisconnected
+onDisconnected() {
+  // Called when element leaves DOM
 }
-```
-
-#### 16. `@queryAllHost` - Query All :host Children
-Returns all children of the component element. Useful for accessing direct children.
-
-All usage patterns automatically set the children array:
-- Without parentheses: `@queryAllHost` children?: HTMLElement[];
-- Empty parentheses: `@queryAllHost()` children?: HTMLElement[];
-- With options: `@queryAllHost({ root: 'shadow' })` children?: HTMLElement[];
-
-```typescript
-@elementDefine('card-container')
-class CardContainer extends HTMLElement {
-  @queryAllHost
-  allChildren?: HTMLElement[];
 
-  getChildCount() {
-    return this.allChildren?.length ?? 0;
-  }
+@onAttributeChanged
+onAttributeChanged(name: string, oldValue: string, newValue: string) {
+  // Called when attribute changes
 }
 ```
 
----
-
-### Event & Messaging Decorators
-
-#### 17. `@addEventListener(selector, event, options?)`
-Declarative event binding with automatic delegation.
+### 8. **Routing with @subscribeSwcAppRouteChange**
+Declarative route pattern matching with path parameters.
 
 ```typescript
-@elementDefine('todo-app')
-class TodoApp extends HTMLElement {
-  private todos: any[] = [];
-
-  // Direct binding to specific element
-  @addEventListener('#add-btn', 'click')
-  onAddTodo(event: MouseEvent) {
-    console.log('Add button clicked');
-  }
-
-  // Event delegation for dynamic elements
-  @addEventListener('.todo-item', 'click', { delegate: true })
-  onTodoClick(event: MouseEvent, hostSet: any, target: HTMLElement) {
-    const itemId = target.getAttribute('data-id');
-    console.log('Clicked todo:', itemId);
-  }
-
-  // Global window events
-  @addEventListener(':window', 'resize', { removeOnDisconnected: true })
-  onWindowResize(event: Event) {
-    console.log('Window resized');
-  }
-
-  // Parent app events
-  @addEventListener(':appHost', 'custom-event')
-  onCustomEvent(event: CustomEvent) {
-    console.log('Event received:', event.detail);
+@elementDefine('root-router')
+class RootRouter extends HTMLElement {
+  @subscribeSwcAppRouteChange('/')
+  @applyInnerHtmlNodeHost({ root: 'light' })
+  homeRoute(router: RouterEventType) {
+    return `<home-page/>`;
   }
 
-  @onConnectedInnerHtml
-  render() {
-    return `
-      <div>
-        <input type="text" id="todo-input" placeholder="Add todo...">
-        <button id="add-btn">Add</button>
-        <ul class="todo-list">
-          ${this.todos.map(t => `
-            <li class="todo-item" data-id="${t.id}">${t.text}</li>
-          `).join('')}
-        </ul>
-      </div>
-    `;
+  @subscribeSwcAppRouteChange('/product/{id}')
+  @applyInnerHtmlNodeHost({ root: 'light' })
+  productRoute(router: RouterEventType, pathData: any) {
+    return `<product-page product-id="${pathData.id}"/>`;
   }
 }
 ```
 
-**Features:**
-- ✅ Direct binding to static selectors
-- ✅ Event delegation for dynamic elements
-- ✅ Global events (`:window`, `:document`)
-- ✅ Parent communication (`:parentHost`, `:appHost`)
-- ✅ Auto-cleanup on `disconnectedCallback`
-
-#### 18. `@emitCustomEvent(target, type, options?)`
-Emit custom events to component hierarchy or global targets.
+### 9. **Accommodation Pattern**
+Factory-based component registration with explicit DI.
 
 ```typescript
-@elementDefine('auth-panel')
-class AuthPanel extends HTMLElement {
-  constructor(private authService: AuthService) { super(); }
-
-  // Emit to parent app when user logs in
-  @emitCustomEvent(':appHost', 'user-logged-in')
-  async onLogin() {
-    const user = await this.authService.login();
-    return { user, timestamp: Date.now() };
-  }
-
-  // Emit globally when logout happens
-  @emitCustomEvent(':window', 'user-logged-out')
-  async onLogout() {
-    await this.authService.logout();
-    return { timestamp: Date.now() };
-  }
-
-  // Emit to direct parent
-  @emitCustomEvent(':parentHost', 'child-ready')
-  notifyParent() {
-    return { childElement: this };
-  }
+// Component factory
+export default (w: Window) => {
+  const tagName = 'my-component';
+  const existing = w.customElements.get(tagName);
+  if (existing) return tagName;
 
-  @onConnectedInnerHtml
-  render() {
-    return `
-      <div>
-        <button swc-on-click="$host.onLogin()">Login</button>
-        <button swc-on-click="$host.onLogout()">Logout</button>
-      </div>
-    `;
+  @elementDefine(tagName, { window: w })
+  class MyComponent extends w.HTMLElement {
+    @onInitialize
+    constructor(service: MyService) {
+      super();
+      this.service = service;
+    }
   }
-}
-
-// Listen to the emitted event
-@elementDefine('user-widget')
-class UserWidget extends HTMLElement {
-  private user: any = null;
+  
+  return tagName;
+};
 
-  @addEventListener(':appHost', 'user-logged-in')
-  onUserLoggedIn(event: CustomEvent) {
-    this.user = event.detail.user;
-    this.render();
-  }
+// Boot factory
+export default (w: Window, container: symbol) => {
+  serviceFactories.forEach(s => s(container));
+  register(w, [...pageFactories, ...componentFactories]);
+};
 
-  @onConnectedInnerHtml
-  render() {
-    return `<p>User: ${this.user?.name ?? 'Anonymous'}</p>`;
+// Entry point
+const container = Symbol('app');
+bootFactory(w, container);
+appElement.connect({
+  container,
+  window: w,
+  onEngineStarted: () => {
+    appElement.innerHTML = '<root-router></root-router>';
   }
-}
+});
 ```
 
-**Emission Targets:**
-- `':appHost'` - Nearest parent `<swc-app>` (contained within app)
-- `':parentHost'` - Direct parent SWC component
-- `':firstHost'` / `':lastHost'` - First/last component in hierarchy
-- `':firstAppHost'` / `':lastAppHost'` - First/last `<swc-app>` in hierarchy
-- `':hosts'` - All SWC ancestors
-- `':appHosts'` - All `<swc-app>` ancestors
-- `':window'` - Global window (all apps can listen)
-- `':document'` - Global document
-- `selector` - CSS selector (emit to matching elements)
-
-**Options:**
-- `bubbles: true` (default) - Event bubbles up
-- `composed: true` (default) - Event crosses Shadow DOM boundary
-- `cancelable: true` - Event can be canceled
-- `root: 'auto' | 'light' | 'shadow'` - Where to find target elements
-
 ---
 
-### DOM Manipulation Decorators
-
-#### 19. `@applyNode(selector, options?)`
-Surgically add, update, or replace DOM nodes at specific positions.
+## ⚠️ Critical Rules
 
-```typescript
-import { htmlDivElement, htmlFragment, htmlSpanElement } from '@dooboostore/simple-web-component';
-
-@elementDefine('counter-display')
-class CounterDisplay extends HTMLElement {
-  private count = 0;
-  private errorMessage = '';
-
-  // Replace all children with new content (return Node)
-  @applyNode('#display', { position: 'replaceChildren' })
-  updateDisplayCount() {
-    return htmlSpanElement(`${this.count}`);
-  }
-
-  // Append to container (return Node)
-  @applyNode('#history', { position: 'beforeEnd' })
-  addHistoryEntry() {
-    return htmlFragment(`<p>Count was: ${this.count}</p>`);
-  }
-
-  // Set HTML content (return string)
-  @applyNode('#status', { position: 'innerHtml' })
-  setStatus() {
-    return `<strong>Status: Active</strong>`;
-  }
-
-  // Set text content (return string)
-  @applyNode('#counter', { position: 'innerText' })
-  updateCounter() {
-    return this.count.toString();
-  }
-
-  // Remove element if condition is truthy (return boolean)
-  @applyNode('#error-banner', { position: 'remove' })
-  dismissError() {
-    return this.errorMessage === '';  // Remove if no error
-  }
-
-  @onConnectedInnerHtml
-  render() {
-    return `
-      <div id="display">0</div>
-      <div id="counter">0</div>
-      <div id="status"></div>
-      <button swc-on-click="$host.count++; $host.updateDisplayCount?.()">+</button>
-      <div id="history"></div>
-      <div id="error-banner" style="display: ${this.errorMessage ? 'block' : 'none'};"></div>
-    `;
-  }
-}
-```
-
-**Position Options:**
-- `'beforeEnd'` (default) - Append to end
-- `'afterBegin'` - Prepend to start
-- `'beforeBegin'` - Insert before element
-- `'afterEnd'` - Insert after element
-- `'replace'` - Replace entire element
-- `'replaceChildren'` - Replace all children
-- `'innerHtml'` - Set `innerHTML`
-- `'innerText'` - Set `innerText`
-- `'remove'` - Remove element if returned value is truthy
-
-**Root Option:**
-Control which DOM tree is searched with the `root` option:
-- `'auto'` (default) - Search shadow DOM first, then light DOM
-- `'shadow'` - Search only shadow DOM
-- `'light'` - Search only light DOM
-- `'all'` - Search all ancestors
-
-#### Convenience Decorators
-
-Shorthand decorators for common position-specific operations:
-
-**Position-Specific Variants:**
-
-Return **DOM Nodes** for position-based insertion. Use DOM creation functions:
+### DO NOT Use @Sim on Web Components
+`@Sim` is for **Services only**. Web Components should use `@elementDefine`.
 
 ```typescript
-import { 
-  htmlFragment, htmlDivElement, htmlSpanElement, 
-  createElement, textNode 
-} from '@dooboostore/simple-web-component';
-
-@elementDefine('my-component')
-class MyComponent extends HTMLElement {
-  // Method 1: Using htmlFragment (DocumentFragment)
-  @applyBeforeBeginNode('#target') prependTarget() { 
-    return htmlFragment('<div>Before</div>');
-  }
-
-  // Method 2: Using htmlDivElement (single element)
-  @applyAfterBeginNode('#target') afterBeginTarget() { 
-    return htmlDivElement('After Begin');
-  }
-
-  // Method 3: Manual createElement (full control)
-  @applyBeforeEndNode('#target') beforeEndTarget() { 
-    return htmlDivElement('Before End');
-  }
-
-  @applyAfterEndNode('#target') afterEndTarget() { 
-    const el = htmlDivElement('After');
-    el.classList.add('highlight');
-    return el;
-  }
+// ✅ CORRECT
+@Sim()
+export class UserService { }
 
-  @applyReplaceNode('#target') replaceTarget() { 
-    return htmlFragment('<div class="replaced">Replaced</div>');
-  }
-
-  // Multiple nodes: return array
-  @applyReplaceChildrenNode('#target') replaceChildrenTarget() { 
-    return [
-      htmlDivElement('Item 1'),
-      htmlDivElement('Item 2'),
-      htmlDivElement('Item 3')
-    ];
-  }
-
-  // String return for innerHtml
-  @applyInnerHtmlNode('#target') setInnerHtml() { 
-    return `<b>Bold</b> <i>Italic</i>`;
-  }
-
-  // String return for innerText
-  @applyInnerTextNode('#target') setInnerText() { 
-    return 'Plain text';
-  }
-
-  // Boolean return for remove
-  @applyRemoveNode('#target') removeTarget() { 
-    return this.shouldHideTarget;
-  }
-}
-```
-
-**SSR Support (with custom Document):**
+@elementDefine(tagName, { window: w })
+class UserWidget extends w.HTMLElement { }
 
-```typescript
-// Browser
-return htmlDivElement('Content');  // Uses global document
-
-// SSR (e.g. Node.js with jsdom)
-const ssrDocument = new JSDOM().window.document;
-return htmlDivElement('Content', ssrDocument);  // Pass custom doc
+// ❌ WRONG
+@Sim()
+@elementDefine(tagName, { window: w })
+class UserWidget extends w.HTMLElement { }
 ```
 
-**Host-Targeted Variants (`:host` selector):**
-
-All Host variants support three usage patterns:
-- Without parentheses: `@applyBeforeBeginNodeHost` prependHost() { ... }
-- With empty parentheses: `@applyBeforeBeginNodeHost()` prependHost() { ... }
-- With options: `@applyBeforeBeginNodeHost({ ... })` prependHost() { ... }
-
+### Factory Always Returns tagName (String)
 ```typescript
-@elementDefine('my-component')
-class MyComponent extends HTMLElement {
-  @applyBeforeBeginNodeHost
-  prependHost() { 
-    return htmlFragment('<div>Before Host</div>');
-  }
-
-  @applyAfterBeginNodeHost() afterBeginHost() { 
-    return htmlSpanElement('After Begin');
-  }
-
-  @applyBeforeEndNodeHost beforeEndHost() { 
-    const el = htmlDivElement('Before End');
-    return el;
-  }
-
-  @applyAfterEndNodeHost afterEndHost() { 
-    return htmlFragment('After Host');
-  }
-
-  @applyReplaceNodeHost replaceHost() { 
-    return htmlFragment('<div>Replaced Host</div>');
-  }
-
-  // Multiple children in shadow DOM
-  @applyReplaceChildrenNodeHost() replaceChildrenHost() { 
-    return [
-      htmlDivElement('Shadow Child 1'),
-      htmlDivElement('Shadow Child 2')
-    ];
-  }
-
-  @applyInnerHtmlNodeHost setHostInnerHtml() { 
-    return `<h1>Host Content</h1>`;
-  }
-
-  @applyInnerTextNodeHost() setHostInnerText() { 
-    return 'Host text content';
-  }
+export default (w: Window) => {
+  const tagName = 'my-element';
+  const existing = w.customElements.get(tagName);
+  if (existing) return tagName;  // ← Return string!
 
-  @applyRemoveNodeHost removeHost() { 
-    return this.isRemoved;
-  }
-}
+  @elementDefine(tagName, { window: w })
+  class MyElement extends w.HTMLElement { }
+  
+  return tagName;  // ← Always return tagName, never class
+};
 ```
 
-**Return Types by Position:**
-- `beforeBegin`, `afterBegin`, `beforeEnd`, `afterEnd`: **Node | Node[]**
-- `replace`: **Node**
-- `replaceChildren`: **Node | Node[]**
-- `innerHtml`: **string**
-- `innerText`: **string**
-- `remove`: **boolean** (truthy = remove)
-
-**Available DOM Functions:**
-- `htmlFragment(html, doc?)` - Create DocumentFragment from HTML
-- `textNode(text, doc?)` - Create Text node
-- `commentNode(comment, doc?)` - Create Comment node
-- `createElement(tagName, options?, doc?)` - Create any element with attributes
-- `htmlDivElement(html, doc?)` - Create div element
-- `htmlSpanElement(html, doc?)` - Create span element
-- `htmlButtonElement(html, doc?)` - Create button element
-- `htmlAElement(html, href?, doc?)` - Create anchor element
-- `htmlPElement(html, doc?)` - Create paragraph element
-- `htmlLiElement(html, doc?)` - Create list item element
-- `htmlUlElement(doc?)` - Create unordered list
-- `htmlHeadingElement(level, html, doc?)` - Create h1-h6
-- `htmlSectionElement(doc?)` - Create section
-- `htmlArticleElement(doc?)` - Create article
-
-**All functions accept optional `doc` parameter for SSR support.**
-
-#### 20. `@applyStyle(selector, action?, options?)` - Universal Style Manipulation
-
-Universal decorator for style operations with flexible strategies.
-
+### @onInitialize for DI (Not Constructor Parameters)
 ```typescript
-@elementDefine('style-demo')
-class StyleDemo extends HTMLElement {
-  private isDark = false;
-
-  // Set styles (replace all inline styles)
-  @applyStyle('.panel', 'set')
-  setDarkMode() {
-    return this.isDark ? {
-      backgroundColor: '#222',
-      color: '#fff'
-    } : {
-      backgroundColor: '#fff',
-      color: '#000'
-    };
-  }
-
-  // Update styles (merge with existing)
-  @applyStyle('.btn', 'update')
-  addBtnStyle() {
-    return { padding: '10px', cursor: 'pointer' };
-  }
-
-  // Remove styles (delete properties)
-  @applyStyle('.temp', 'remove')
-  clearTempStyle() {
-    return ['transition', 'transform'];
-  }
+// ✅ CORRECT
+@onInitialize
+constructor(@Inject({ symbol: Service.SYMBOL }) service: Service) {
+  super();
+  this.service = service;
 }
-```
-
-**Convenience Methods** (specific actions):
-
-#### 20a. `@setStyle(selector, options?)` / `@updateStyle(selector, options?)` / `@removeStyle(selector, options?)`
-
-Manipulate CSS styles on elements with full Shadow DOM support.
-
-**Core Features:**
-- `@setStyle` - Set inline style (replaces all)
-- `@updateStyle` - Merge with existing styles
-- `@removeStyle` - Remove specific properties
-- `root` option for Shadow DOM / Light DOM targeting
-- Support for multiple elements with `querySelectorAll`
 
-```typescript
-@elementDefine('styled-component')
-class StyledComponent extends HTMLElement {
-  private isActive = false;
-
-  @setStyle('.button', { root: 'shadow' })
-  setPrimaryButtonStyle() {
-    return {
-      backgroundColor: '#0066cc',
-      color: 'white',
-      padding: '10px 20px',
-      border: 'none',
-      borderRadius: '4px'
-    };
-  }
-
-  @updateStyle('.button', { root: 'shadow' })
-  highlightButton() {
-    return {
-      boxShadow: '0 0 10px rgba(0, 102, 204, 0.5)',
-      transform: 'scale(1.05)'
-    };
-  }
-
-  @removeStyle('.button', { root: 'shadow' })
-  clearHighlight() {
-    return ['boxShadow', 'transform'];
-  }
-
-  @onConnectedInnerHtml({ useShadow: true })
-  render() {
-    return `
-      <style>
-        .button { cursor: pointer; transition: all 0.2s; }
-      </style>
-      <button class="button">Styled</button>
-    `;
-  }
-}
+// ❌ WRONG
+constructor(private service: Service) { super(); }  // Web Components can't have constructor parameters!
 ```
 
-**Host-Targeted Variants:**
-
-Note: `:host` selector targets the component itself (boundary), so `root` option is ignored.
+---
 
-All Host variants support three usage patterns:
-- Without parentheses: `@setStyleHost` setHostStyle() { ... }
-- With empty parentheses: `@setStyleHost()` setHostStyle() { ... }
-- With options: `@setStyleHost({ ... })` setHostStyle() { ... }
+## 📚 Examples
 
-```typescript
-@setStyleHost
-setHostStyle() {
-  return { display: 'flex', gap: '10px' };
-}
+- **[Commerce (E-Commerce SPA)](./examples/commerce)** - Full shopping cart example
+- **[Stock (Market Dashboard)](./examples/stock)** - Real-time data with routing
+- **[Accommodation (Reference Pattern)](./examples/accommodation)** - Standard setup pattern
 
-@updateStyleHost()
-updateHostStyle() {
-  return { backgroundColor: '#f0f0f0' };
-}
+---
 
-@removeStyleHost()
-clearHostStyle() {
-  return ['backgroundColor'];
-}
-```
-
----
-
-#### 21. `@applyClass(selector, action?, options?)` - Universal Class Manipulation
-
-Universal decorator for class operations with flexible strategies.
-
-```typescript
-@elementDefine('class-demo')
-class ClassDemo extends HTMLElement {
-  private isActive = false;
-  private isLoading = false;
-
-  @applyClass('.item', 'set')
-  setClasses() {
-    return this.isActive ? ['active', 'highlight'] : ['inactive'];
-  }
-
-  @applyClass('.spinner', 'update')
-  updateSpinner() {
-    return this.isLoading ? ['spinning', 'visible'] : ['hidden'];
-  }
-
-  @applyClass('.temp', 'remove')
-  removeTempClasses() {
-    return ['temporary', 'debug'];
-  }
-}
-```
-
-**Convenience Methods** (specific actions):
-
-#### 21a. `@setClass(selector, options?)` / `@addClass(selector, options?)` / `@removeClass(selector, options?)` / `@toggleClass(selector, options?)` / `@updateClass(selector, options?)`
-
-Manipulate CSS classes on elements declaratively with Shadow DOM support.
-
-**Core Features:**
-- `@addClass` - Add classes
-- `@removeClass` - Remove classes
-- `@toggleClass` - Toggle classes (returns boolean or bool array)
-- `@setClass` - Replace all classes
-- `@updateClass` - Merge with existing classes
-- `root` option for DOM layer targeting
-- Support for multiple elements
-
-```typescript
-@elementDefine('tab-component')
-class TabComponent extends HTMLElement {
-  activeTab = 'home';
-
-  @addClass('.tab', { root: 'shadow' })
-  addTabClasses() {
-    return ['interactive', 'focusable'];
-  }
-
-  @toggleClass('.tab', { root: 'shadow' })
-  toggleActiveTab() {
-    return this.activeTab === 'home';  // Returns boolean for all matched elements
-  }
-
-  @removeClass('.tab-inactive', { root: 'shadow' })
-  removeInactiveClass() {
-    return ['disabled'];
-  }
-
-  @setClass('.tab-pane', { root: 'shadow' })
-  updateTabPane() {
-    return [`pane-${this.activeTab}`, 'content'];
-  }
-
-  @onConnectedInnerHtml({ useShadow: true })
-  render() {
-    return `
-      <style>
-        .tab { cursor: pointer; padding: 10px; }
-        .tab.active { border-bottom: 2px solid blue; }
-      </style>
-      <div class="tabs">
-        <div class="tab" swc-on-click="$host.activeTab='home'; $host.toggleActiveTab?.();">Home</div>
-        <div class="tab" swc-on-click="$host.activeTab='about'; $host.toggleActiveTab?.();">About</div>
-      </div>
-      <div class="tab-pane">Content here</div>
-    `;
-  }
-}
-```
-
-**Host-Targeted Variants:**
-
-Note: `:host` selector targets the component itself (boundary), so `root` option is ignored.
-
-All Host variants support three usage patterns:
-- Without parentheses: `@setClassHost` setHostClasses() { ... }
-- With empty parentheses: `@setClassHost()` setHostClasses() { ... }
-- With options: `@setClassHost({ ... })` setHostClasses() { ... }
-
-```typescript
-@addClassHost
-addHostClasses() {
-  return ['component', 'interactive'];
-}
-
-@removeClassHost()
-removeHostClasses() {
-  return ['loading'];
-}
-
-@toggleClassHost()
-toggleHostClass() {
-  return this.isOpen;  // Apply 'open' class if true
-}
-
-@setClassHost
-setHostClasses() {
-  return this.isOpen ? ['open', 'expanded'] : ['closed'];
-}
-
-@updateClassHost()
-updateHostClasses() {
-  return ['visible'];
-}
-```
-
----
-
-### Dependency Injection & Singleton
-
-#### 22. `@Sim`
-Marks a class as a **Singleton** in the `<swc-app>` DI container for **constructor injection**.
-
-**Two DI Mechanisms:**
-
-1. **Lifecycle DI** (`@onBeforeConnected`, etc.) - ❌ NO `@Sim` needed
-  - Works on any `@elementDefine` component
-  - Services injected via method parameters
-  - Can be used outside `<swc-app>`
-
-2. **Constructor DI** - ✅ `@Sim` REQUIRED
-  - Only works inside `<swc-app>` boundary
-  - Both provider AND consumer need `@Sim`
-  - Singleton pattern within the app
-
-**Example: Both Approaches**
-
-```typescript
-// ============ SERVICE ============
-@Sim
-class CartService {
-  private items: any[] = [];
-  
-  addItem(item: any) {
-    this.items.push(item);
-  }
-  
-  getItems() {
-    return this.items;
-  }
-}
-
-// ============ APPROACH 1: Lifecycle DI (NO @Sim needed) ============
-@elementDefine('cart-header')  // ← NO @Sim
-class CartHeader extends HTMLElement {
-  #cartService: CartService;
-
-  @onBeforeConnected
-  async setup(cartService: CartService) {  // ← Injected here
-    this.#cartService = cartService;
-    await this.#cartService.load?.();
-  }
-
-  @onConnectedInnerHtml
-  render() {
-    return `<div>Cart: ${this.#cartService?.getItems().length}</div>`;
-  }
-}
-
-// ============ APPROACH 2: Constructor DI (NEEDS @Sim) ============
-@Sim  // ← Required for constructor injection
-@elementDefine('cart-component')
-class CartComponent extends HTMLElement {
-  // Constructor injection - CartService is auto-injected
-  constructor(private cartService: CartService) { super(); }
-
-  @onConnectedInnerHtml
-  render() {
-    const itemCount = this.cartService.getItems().length;
-    return `<div>Items: ${itemCount}</div>`;
-  }
-}
-
-// ============ ROUTING & BOOTSTRAP ============
-@Sim
-@Router({
-  path: '/',
-  route: {
-    '/home': HomePage,
-    '/cart': CartComponent  // Constructor DI works here
-  }
-})
-@elementDefine('app-router')
-class AppRouter extends HTMLElement {
-  @onConnectedInnerHtml
-  render() {
-    return `<div><slot></slot></div>`;
-  }
-}
-
-// ============ HTML ============
-<!-- Lifecycle DI works OUTSIDE <swc-app> -->
-<cart-header></cart-header>
-
-<!-- Constructor DI works INSIDE <swc-app> -->
-<swc-app swc-get-application-config="appConfig()">
-  <app-router></app-router>
-</swc-app>
-
-<script>
-  window.appConfig = () => ({
-    rootRouter: AppRouter,
-    routeType: 'element',
-    path: '/'
-  });
-</script>
-```
-
-**When to Use Each:**
-
-| Scenario | Use | Mark |
-|----------|-----|------|
-| Component needs services anywhere | Lifecycle DI in `@onBeforeConnected` | NO `@Sim` |
-| Component inside `<swc-app>` route | Constructor DI | YES `@Sim` |
-| Service/Singleton registration | Register in DI container | YES `@Sim` |
-| Standalone component | Lifecycle DI | NO `@Sim` |
-
-**Key Points:**
-- `@Sim` = Mark as singleton for **constructor injection inside `<swc-app>`**
-- Lifecycle DI = Inject via method parameters (works everywhere, no `@Sim`)
-- Each `<swc-app>` has its own isolated DI container
-- Services are local to their `<swc-app>` instance (for constructor DI)
-
----
-
-## Core Decorators
-
-#### Root Options
-The `root` option controls which DOM tree is searched:
-- **`'auto'`** (default): Searches shadow DOM first, then light DOM
-- **`'light'`**: Searches only light DOM
-- **`'shadow'`**: Searches only shadow DOM
-- **`'all'`**: Searches all ancestors, returning `[lightNodes, shadowNodes]` array
-
-#### Usage with Special Targets:
-Special targets (starting with `:`) navigate the hierarchy and environment.
-```typescript
-@query(':host') self!: HTMLElement;
-@query(':parentHost') parent!: HTMLElement;
-@query(':appHost') app!: SwcAppInterface;
-@query(':window') win!: Window;
-@query(':document') doc!: Document;
-@queryAll(':hosts') ancestors!: HTMLElement[];
-```
-
-#### Usage with Selectors & Root Options:
-Standard CSS selectors support precise root control.
-```typescript
-// root options: 'light' | 'shadow' | 'all' | 'auto' (default)
-@query('.btn', { root: 'shadow' }) shadowBtn!: HTMLButtonElement;
-```
-
-### 5. Event Binding (`@addEventListener`)
-
-Bind events declaratively with built-in **Event Delegation**, **Auto-Cleanup**, and **Context Injection**. Events flow through the component hierarchy with full access to parent scopes.
-
-#### Core Features:
-- **Direct Binding**: Bind to static selectors present at initialization
-- **Event Delegation**: Automatically handle dynamically added elements
-- **Auto-Cleanup**: Automatically remove listeners on `disconnectedCallback`
-- **Context Injection**: Receive `$host`, `$parentHost`, `$appHost` automatically
-- **Special Targets**: `:window`, `:document`, `:parentHost`, `:appHost`
-
-#### 6. Surgical DOM Manipulation (`@applyNode`)
-
-Surgically add, prepend, insert, or replace nodes with a single decorator. Perfect for dynami content updates without imperatively manipulating the DOM.
-
-```typescript
-@elementDefine('list-manager')
-class ListManager extends HTMLElement {
-  @applyNode('#list') addItem() { 
-    return '<li>New Item</li>'; 
-  }
-
-  @applyNode('#header', { position: 'afterBegin' }) prependTitle() { 
-    return '<h1>Title</h1>'; 
-  }
-
-  @applyNode('#item', { position: 'replace' }) replaceItem() { 
-    return '<div>Replaced Content</div>'; 
-  }
-}
-```
-
-**Positions:**
-- `'beforeEnd'` (default): Append to end of target
-- `'afterBegin'`: Prepend to start of target
-- `'beforeBegin'`: Insert before target
-- `'afterEnd'`: Insert after target
-- `'replace'`: Replace entire target element
-- `'replaceChildren'`: Replace all children of target element
-- `'innerHtml'`: Set target's `innerHTML` with string content
-- `'innerText'`: Set target's `innerText` with string content
-
----
-
-### 6. DOM Manipulation (`@applyNode`)
-
-Surgically add, prepend, insert, or replace nodes. Perfect for reactive updates without full re-renders.
-
-#### Pattern 1: Direct Binding & Static Selectors
-
-```typescript
-@Sim
-@elementDefine('form-handler')
-class FormHandler extends HTMLElement {
-  @query('#submit-btn') submitBtn?: HTMLButtonElement;
-  @query('#form') form?: HTMLFormElement;
-
-  // Bind to a specific static element
-  @addEventListener('#submit-btn', 'click')
-  onSubmit(event: MouseEvent) {
-    event.preventDefault();
-    console.log('Form submitted');
-    this.form?.submit();
-  }
-
-  // Bind to multiple elements with selector
-  @addEventListener('input[type="text"]', 'input')
-  onTextInput(event: Event) {
-    console.log('Input value:', (event.target as HTMLInputElement).value);
-  }
-
-  @onConnectedInnerHtml
-  render() {
-    return `
-      <form id="form">
-        <input type="text" placeholder="Enter name">
-        <input type="email" placeholder="Enter email">
-        <button id="submit-btn">Submit</button>
-      </form>
-    `;
-  }
-}
-```
-
-#### Pattern 2: Event Delegation (Dynamic Content)
-
-Automatically handle elements added **after component initialization**.
-
-```typescript
-@Sim
-@elementDefine('todo-app')
-class TodoApp extends HTMLElement {
-  private todos: any[] = [];
-
-  constructor(private todoService: TodoService) { super(); }
-
-  // Delegate: Handles all current AND future .todo-item elements
-  @addEventListener('.todo-item', 'click', { delegate: true })
-  onTodoClick(event: MouseEvent, hostSet: any, target: HTMLElement) {
-    const todoId = target.getAttribute('data-id');
-    console.log('Clicked todo:', todoId);
-    this.selectTodo(todoId);
-  }
-
-  // Event delegation with checkbox - even newly added items react
-  @addEventListener('.todo-checkbox', 'change', { delegate: true })
-  onTodoToggle(event: Event, hostSet: any, target: HTMLInputElement) {
-    const todoId = target.closest('.todo-item')?.getAttribute('data-id');
-    const isChecked = target.checked;
-    console.log(`Todo ${todoId} ${isChecked ? 'completed' : 'uncompleted'}`);
-  }
-
-  async addTodo(text: string) {
-    const newTodo = await this.todoService.create(text);
-    this.todos.push(newTodo);
-    this.render();
-    // New .todo-item elements automatically get event listeners!
-  }
-
-  selectTodo(id: string) {
-    const todo = this.todos.find(t => t.id === id);
-    console.log('Selected:', todo);
-  }
-
-  @onConnectedInnerHtml
-  render() {
-    return `
-      <div>
-        <input type="text" placeholder="Add todo">
-        <button swc-on-click="$host.addTodo(this.previousElementSibling.value)">Add</button>
-        <ul>
-          ${this.todos.map(t => `
-            <li class="todo-item" data-id="${t.id}">
-              <input type="checkbox" class="todo-checkbox" ${t.done ? 'checked' : ''}>
-              <span>${t.text}</span>
-            </li>
-          `).join('')}
-        </ul>
-      </div>
-    `;
-  }
-}
-```
-
-#### Pattern 3: Global Events with Context Access
-
-```typescript
-@Sim
-@elementDefine('responsive-layout')
-class ResponsiveLayout extends HTMLElement {
-  private isMobile = false;
-
-  // Listen to window resize with auto-cleanup on disconnect
-  @addEventListener(':window', 'resize', { removeOnDisconnected: true })
-  onWindowResize() {
-    this.isMobile = window.innerWidth < 768;
-    this.updateLayout();
-  }
-
-  // Listen to global scroll with host context
-  @addEventListener(':window', 'scroll', { removeOnDisconnected: true })
-  onScroll(event: Event, { $appHost }: any) {
-    const scrollPos = window.scrollY;
-    console.log('Scrolled in app:', $appHost?.tagName, 'Position:', scrollPos);
-  }
-
-  updateLayout() {
-    this.className = this.isMobile ? 'mobile-layout' : 'desktop-layout';
-  }
-
-  @onConnectedInnerHtml
-  render() {
-    return `<div class="${this.isMobile ? 'mobile' : 'desktop'}"><slot></slot></div>`;
-  }
-}
-```
-
-### 7. Dynamic Content Updates with `@applyNode`
-
-#### Advanced Patterns
-
-**Pattern 1: Simple Content Replacement with `replaceChildren`**
-
-```typescript
-@Sim
-@elementDefine('search-results')
-class SearchResults extends HTMLElement {
-  private results: any[] = [];
-  private isLoading = false;
-
-  // Replace #results-container with new search results
-  @replaceChildren('#results-container')
-  async displayResults(query: string) {
-    this.isLoading = true;
-    const startTime = Date.now();
-
-    try {
-      this.results = await fetch(`/api/search?q=${query}`)
-        .then(r => r.json());
-
-      return htmlFragment`
-        <div class="results-header">
-          <p>Found ${this.results.length} results in ${Date.now() - startTime}ms</p>
-        </div>
-        <div class="results-list">
-          ${this.results.map(item => `
-            <div class="result-item" data-id="${item.id}">
-              <h3>${item.title}</h3>
-              <p>${item.description}</p>
-              <a href="${item.url}">View</a>
-            </div>
-          `).join('')}
-        </div>
-      `;
-    } catch (error) {
-      return htmlFragment`<p class="error">Search failed: ${error.message}</p>`;
-    }
-  }
-
-  @onConnectedInnerHtml
-  render() {
-    return `
-      <div>
-        <input type="text" class="search-input" placeholder="Search...">
-        <button swc-on-click="$host.search($el.previousElementSibling.value)">Search</button>
-        <div id="results-container">
-          <p>Enter search term...</p>
-        </div>
-      </div>
-    `;
-  }
-
-  search(query: string) {
-    if (query.trim()) {
-      this.displayResults(query);
-    }
-  }
-}
-```
-
-**Pattern 2: Setting HTML Content**
-
-```typescript
-@applyNode('#message', { position: 'innerHtml' })
-displayMessage(text: string) {
-  return `<p style="color: blue;">${text}</p>`;
-}
-
-@applyNode('#count', { position: 'innerText' })
-updateCounter() {
-  return this.count.toString();
-}
-```
-
-**Pattern 3: Tab Content Switching
-
-```typescript
-@Sim
-@elementDefine('tabbed-panel')
-class TabbedPanel extends HTMLElement {
-  private activeTab = 'overview';
-  private tabData: any = {
-    overview: '<h3>Overview</h3><p>General information...</p>',
-    details: '<h3>Details</h3><p>Detailed specifications...</p>',
-    reviews: '<h3>Reviews</h3><p>Customer reviews...</p>'
-  };
-
-  // Click tab and automatically replace content
-  @replaceChildren('.tab-content')
-  switchTab(tabName: string) {
-    this.activeTab = tabName;
-
-    // Update tab buttons visual state
-    Array.from(this.querySelectorAll('.tab-btn')).forEach(btn => {
-      btn.classList.toggle('active', btn.getAttribute('data-tab') === tabName);
-    });
-
-    // Return new content
-    return htmlFragment`${this.tabData[tabName]}`;
-  }
-
-  @onConnectedInnerHtml
-  render() {
-    return `
-      <div class="tabs">
-        <button class="tab-btn active" data-tab="overview" 
-                swc-on-click="$host.switchTab('overview')">Overview</button>
-        <button class="tab-btn" data-tab="details" 
-                swc-on-click="$host.switchTab('details')">Details</button>
-        <button class="tab-btn" data-tab="reviews" 
-                swc-on-click="$host.switchTab('reviews')">Reviews</button>
-      </div>
-      <div class="tab-content">${this.tabData.overview}</div>
-    `;
-  }
-}
-```
-
-### 8. `@appendChild(selector, options?)`
-
-Appends or inserts the method's return value relative to a target element. Perfect for dynamically building lists, stacking notifications, or adding children without replacing existing content.
-
-**Position Options:**
-- **`'lastChild'`** (default): Append to end
-- **`'firstChild'`**: Prepend to beginning
-- **`'nextSibling'`**: Insert after element
-- **`'previousSibling'`**: Insert before element
-
-#### Pattern 1: Dynamic List Building
-
-```typescript
-@Sim
-@elementDefine('task-list')
-class TaskList extends HTMLElement {
-  private tasks: any[] = [];
-  private taskIdCounter = 0;
-
-  // Append new task to bottom of list
-  @appendChild('#task-list', { position: 'lastChild' })
-  addTask(title: string, priority: 'low' | 'medium' | 'high' = 'medium') {
-    const id = ++this.taskIdCounter;
-    const bgColor = { low: '#e8f5e9', medium: '#fff3e0', high: '#ffebee' }[priority];
-
-    return htmlFragment`
-      <div class="task-item" data-id="${id}" style="background: ${bgColor}; padding: 12px; margin: 8px 0; border-radius: 4px;">
-        <div class="task-header">
-          <input type="checkbox" class="task-checkbox" data-id="${id}">
-          <span class="task-title">${title}</span>
-          <span class="task-priority">${priority.toUpperCase()}</span>
-        </div>
-        <button class="task-delete" swc-on-click="$host.deleteTask(${id})">🗑️ Delete</button>
-      </div>
-    `;
-  }
-
-  // Prepend urgent task to top of list
-  @appendChild('#task-list', { position: 'firstChild' })
-  addUrgentTask(title: string) {
-    return htmlFragment`
-      <div class="task-item urgent" style="background: #ffcdd2; padding: 12px; border: 2px solid #f44336;">
-        <strong>🚨 URGENT: ${title}</strong>
-        <button swc-on-click="$host.deleteTask()">Close</button>
-      </div>
-    `;
-  }
-
-  deleteTask(id?: number) {
-    console.log('Delete task:', id);
-  }
-
-  @onConnectedInnerHtml
-  render() {
-    return `
-      <div>
-        <div class="task-input">
-          <input type="text" id="new-task" placeholder="Enter task...">
-          <select id="priority">
-            <option value="low">Low</option>
-            <option value="medium" selected>Medium</option>
-            <option value="high">High</option>
-          </select>
-          <button swc-on-click="
-            const input = document.getElementById('new-task');
-            const priority = document.getElementById('priority').value;
-            if (priority === 'high') {
-              $host.addUrgentTask(input.value);
-            } else {
-              $host.addTask(input.value, priority);
-            }
-            input.value = '';
-            input.focus();
-          ">Add Task</button>
-        </div>
-        <div id="task-list"></div>
-      </div>
-    `;
-  }
-}
-```
-
-#### Pattern 2: Notification Stack
-
-```typescript
-@Sim
-@elementDefine('notification-stack')
-class NotificationStack extends HTMLElement {
-  private notificationId = 0;
-
-  // Append notifications to stack (they auto-dismiss)
-  @appendChild('.notifications', { position: 'lastChild' })
-  notify(message: string, type: 'info' | 'success' | 'warning' | 'error' = 'info', duration = 5000) {
-    const id = ++this.notificationId;
-    const bgColor = { info: '#e3f2fd', success: '#e8f5e9', warning: '#fff3e0', error: '#ffebee' }[type];
-    const borderColor = { info: '#2196f3', success: '#4caf50', warning: '#ff9800', error: '#f44336' }[type];
-
-    // Auto-remove after duration
-    setTimeout(() => {
-      const el = document.querySelector(`[data-notify-id="${id}"]`);
-      if (el) el.remove();
-    }, duration);
-
-    return htmlFragment`
-      <div class="notification" data-notify-id="${id}" 
-           style="background: ${bgColor}; border-left: 4px solid ${borderColor}; padding: 16px; margin: 8px 0; border-radius: 4px; display: flex; justify-content: space-between;">
-        <span>${message}</span>
-        <button swc-on-click="this.closest('[data-notify-id]').remove()"
-                style="background: none; border: none; cursor: pointer; font-size: 18px;">×</button>
-      </div>
-    `;
-  }
-
-  @onConnectedInnerHtml
-  render() {
-    return `
-      <div class="notifications" style="position: fixed; top: 20px; right: 20px; width: 300px; z-index: 1000;"></div>
-    `;
-  }
-}
-
-// Usage
-const notifier = document.querySelector('notification-stack');
-notifier.notify('Operation successful!', 'success');
-notifier.notify('Something went wrong', 'error');
-```
-
----
-
-## 🛠 Template Utilities
-
-SWC provides powerful utilities to create DOM nodes using **Tagged Template Literals**. These are perfect for use with surgical decorators like `@replaceChildren`, `@appendChild`, and `@replaceChildren`.
-
-### Complete Factory List
-
-SWC provides element factories for **all common HTML tags**:
-
-```typescript
-import {
-  htmlFragment, textNode,
-  htmlDivElement, htmlSpanElement, htmlButtonElement,
-  htmlInputElement, htmlFormElement,
-  htmlTableElement, htmlTrElement, htmlTdElement,
-  htmlUlElement, htmlLiElement,
-  htmlHeadingElement, htmlImageElement,
-  // ... 50+ more factories
-} from '@dooboostore/simple-web-component';
-```
-
-### 1. `htmlFragment` - DOM Fragments
-
-Returns a `DocumentFragment` from an HTML string. Perfect for multi-element insertion.
-
-```typescript
-@Sim
-@elementDefine('fragment-demo')
-class FragmentDemo extends HTMLElement {
-  @replaceChildren('#container')
-  renderMultipleElements() {
-    // All elements wrapped in one fragment for efficient insertion
-    return htmlFragment`
-      <h2>Title</h2>
-      <p>First paragraph</p>
-      <p>Second paragraph</p>
-      <ul>
-        <li>Item 1</li>
-        <li>Item 2</li>
-      </ul>
-    `;
-  }
-
-  @onConnectedInnerHtml
-  render() {
-    return `<div id="container"></div>`;
-  }
-}
-```
-
-### 2. `textNode` - Pure Text Nodes
-
-Create raw text nodes (useful for escaping HTML or building text content).
-
-```typescript
-@Sim
-@elementDefine('text-renderer')
-class TextRenderer extends HTMLElement {
-  @appendChild('.text-list', { position: 'lastChild' })
-  addPlainText(userInput: string) {
-    // Create pure text node - prevents XSS
-    return textNode`User wrote: ${userInput}`;
-  }
-
-  @onConnectedInnerHtml
-  render() {
-    return `
-      <input type="text" id="user-input" placeholder="Enter text...">
-      <button swc-on-click="
-        const input = document.getElementById('user-input');
-        $host.addPlainText(input.value);
-        input.value = '';
-      ">Add Text</button>
-      <div class="text-list"></div>
-    `;
-  }
-}
-```
-
-### 2b. `commentNode` - HTML Comments
-
-Create HTML comment nodes (useful for debugging, markers, or template documentation).
-
-```typescript
-@elementDefine('debug-component')
-class DebugComponent extends HTMLElement {
-  @appendChild('#debug-area')
-  addDebugComment(message: string) {
-    // Create HTML comment node
-    return commentNode`DEBUG: ${message} at ${new Date().toISOString()}`;
-  }
-
-  @onConnectedInnerHtml
-  render() {
-    return `<div id="debug-area"></div>`;
-  }
-}
-```
-
-### 3. Element Factories (`html***Element`)
-
-Specific factories for common tags. Each returns a **typed element instance**.
-
-```typescript
-@Sim
-@elementDefine('element-factory-demo')
-class ElementFactoryDemo extends HTMLElement {
-  // htmlDivElement returns HTMLDivElement (typed)
-  @appendChild('#container')
-  addCard(title: string, description: string) {
-    return htmlDivElement`
-      <div class="card">
-        <h3>${title}</h3>
-        <p>${description}</p>
-        <button class="card-btn">Learn More</button>
-      </div>
-    `;
-  }
-
-  // htmlTableElement for building tables
-  @replaceChildren('#table-container')
-  buildTable(data: Array<{ name: string; age: number; role: string }>) {
-    const headerRow = htmlTrElement`
-      <tr style="background: #f0f0f0; font-weight: bold;">
-        <td>Name</td>
-        <td>Age</td>
-        <td>Role</td>
-      </tr>
-    `;
-
-    const rows = data.map(item => 
-      htmlTrElement`
-        <tr>
-          <td>${item.name}</td>
-          <td>${item.age}</td>
-          <td>${item.role}</td>
-        </tr>
-      `
-    );
-
-    return htmlTableElement`
-      ${headerRow}
-      ${rows}
-    `;
-  }
-
-  // htmlUlElement for lists
-  @appendChild('.sidebar')
-  addMenuList(items: string[]) {
-    const listItems = items.map(item =>
-      htmlLiElement`<li><a href="#">${item}</a></li>`
-    );
-
-    return htmlUlElement`
-      <ul class="menu">
-        ${listItems}
-      </ul>
-    `;
-  }
-
-  @onConnectedInnerHtml
-  render() {
-    return `
-      <div id="container"></div>
-      <div id="table-container"></div>
-      <div class="sidebar"></div>
-    `;
-  }
-}
-```
-
----
-
-## ⚡ Quick Start
-
-```ts
-import 'reflect-metadata';
-import swcRegister, { elementDefine, onConnectedInnerHtml } from '@dooboostore/simple-web-component';
-
-swcRegister(window);
-
-@elementDefine('hello-swc')
-class HelloSwc extends HTMLElement {
-  @onConnectedInnerHtml({ useShadow: true })
-  render() {
-    return `<style>:host{display:block;padding:12px;background:#111;color:#fefefe}</style><slot>Hello SWC</slot>`;
-  }
-}
-
-// <hello-swc> contents render automatically once the element is connected.
-```
-
-- Call `swcRegister(window)` once per window to register structural elements (`swc-if`, `swc-loop`, etc.) globally.
-- Decorators rely on `reflect-metadata`, so make sure it is imported before defining elements.
-
----
-
-## 🧪 Interactive Test Cases
-
-Every decorator and directive ships with runnable playgrounds under [test/case/src](test/case/src). They double as living documentation.
-
-1. Install dependencies at the repo root: `pnpm install`.
-2. Start the playground server:
-   ```bash
-   cd packages/@dooboostore/simple-web-component/test/case
-   pnpm run dev
-   ```
-3. Open `http://localhost:3005` and pick a scenario from the menu.
-
-| Scenario | Folder | Highlights |
-| --- | --- | --- |
-| Lifecycle hooks | `lifecycle/` | All pre/post connect, disconnect, adopt hooks with parent-child ordering. |
-| Attribute flow | `attr/` and `attribute-test/` | DOM-first attribute sync, `@setAttribute`, `@changedAttribute`, `connectedInitialize` edge cases. |
-| Events | `event/` and `event-attribute/` | Direct binding, delegation, special selectors, `swc-on-*`, custom event emission. |
-| Queries | `query/` | `@query`, `@queryAll`, special selectors like `:appHost`, element injection safety. |
-| Structural directives | `swc-loop/`, `swc-if/`, `swc-choose/`, `swc-async/` | Surgical list handling, portal rendering, async template states. |
-| SPA & DI | `spa/` | Multiple `<swc-app>` instances, DI containers, nested routers. |
-| Performance | `load-test/` | 1,000+ node stress tests showcasing zero MutationObserver overhead. |
-
-Each folder contains an `index.ts` that demonstrates the decorator usage and an `index.html` you can load standalone if needed.
-
----
-
-## 🧱 Project Layout
-
-- [src/](src) holds the production TypeScript sources (decorators, structural elements, router, utilities).
-- [test/case/src](test/case/src) aggregates example applications used in documentation and regression checks.
-- [test/case/src/README.md](test/case/src/README.md) provides an overview of every scenario along with the architectural ideas they validate.
-
----
-
-## 🛠 Developer Scripts
-
-Inside [package.json](package.json) you will find task shortcuts:
-
-- `pnpm run build` – produce ESM, CJS, and bundle artifacts (`dist/`).
-- `pnpm run watch` – rebuild all targets on file changes.
-- `pnpm run build:esm` / `build:cjs` – individual module formats when you only care about one output.
-- `pnpm run test:bundle` – launches the bundle regression playground (`@dooboostore/simple-web-component-bundle-test`).
-- `pnpm run typecheck` – validate TypeScript types without emitting output.
-
-Publishing uses `publish:npm`, which runs a clean build, packs artifacts, and pushes them with the correct metadata.
-
----
-
-## 🌐 Server-Side Rendering (SSR) & Hydration
-
-SWC provides seamless SSR support with automatic tag-name preservation and client-side hydration strategies.
-
-### SSR Features
-- **Tag Name Preservation**: Custom element tags (e.g., `<user-route>`, `<index-router>`) are preserved through the SSR virtual DOM layer.
-- **Metadata-Based Registration**: The `CustomElementRegistry` stores tagname metadata during `define()`, allowing `HTMLElementBase` to auto-infer correct tag names during construction.
-- **Virtual Window Support**: Pass a custom window object to `@elementDefine()` for SSR rendering environments.
-
-### Hydration Modes
-When connecting a server-rendered app to the client, choose a connection strategy via the `connectMode` config:
-
-```typescript
-const config = {
-  rootRouter: RootRouter,
-  routeType: 'element',
-  connectMode: 'swap' // or 'direct' (default)
-};
-
-app.connect(config);
-```
-
-#### Mode Behaviors:
-- **`'direct'`** (default): Directly connects the existing rendered DOM tree.
-- **`'swap'`**: Creates a clone of the rendered app, connects it, and smoothly replaces the original DOM (Zero FOUC - Flash of Unstyled Content).
-
-The swap mode is ideal for SSR workflows where you want to:
-1. Render components on the server with proper tag names
-2. Send minimal HTML to the client
-3. Clone and connect on the client side without visible DOM flashing
-
----
-
-## 🌐 Revolutionary SPA Architecture
-
-SWC introduces a **paradigm shift** in SPA design: **Each component scope is an independent, self-contained application** with its own DI container, router, and lifecycle. This enables true micro-frontend architectures without iframe overhead while maintaining perfect encapsulation.
-
-### Core Philosophy: Multi-App Composition
-Unlike traditional SPAs that force a global router and monolithic state tree, SWC allows:
-- **Nested Independent Apps**: Multiple `<swc-app>` instances on the same page, each with zero cross-contamination
-- **Autonomous Routing**: Each app handles its own navigation, history, and component lifecycle independently
-- **Decentralized DI**: Service dependencies are resolved within app scope, enabling natural code splitting and lazy loading
-- **Island Architecture**: Apps boot only when needed, reducing initial JavaScript payload
-
-### ✨ Complete Commerce App Example
-
-See the **[Commerce Example](examples/commerce/)** for a production-ready SPA implementation featuring:
-
-- **Multi-page routing** (Home, Product Detail, Cart, Orders)
-- **Service layer** (ProductService, CartService, OrderService) with localStorage persistence
-- **Reactive state management** using BehaviorSubject
-- **Modern UI design** with gradient backgrounds, responsive layouts, and sticky header
-- **Product images** from dynamic CDN (picsum.photos)
-- **DI integration** with `@onBeforeConnected` lifecycle hooks
-- **Shadow DOM** for style encapsulation
-- **Real-time updates** with cart count synchronization
-
-```bash
-cd packages/@dooboostore/simple-web-component/examples/commerce
-pnpm install
-pnpm build
-```
-
-This example demonstrates all decorators working together in a real-world e-commerce scenario.
-
----
-
-### Advanced Patterns
-
-#### Isolated App Scopes & Micro-Frontend Pattern
-
-Create self-contained apps with `<swc-app>` where routing and DI are completely isolated:
-
-```html
-<div class="dashboard">
-  <swc-app swc-get-application-config="createUserModule()"></swc-app>
-  <swc-app swc-get-application-config="createReportsModule()"></swc-app>
-</div>
-```
-
-Each app is independent: state, services, and routes don't cross boundaries.
-
----
-
-#### DI-Powered Routing with Lifecycle Hooks
-
-SWC routing injects services directly into components using `canActivate` lifecycle hook for permission checks and data preloading:
-
-```typescript
-// ============================================
-// 1. SERVICE LAYER (Shared by all routes)
-// ============================================
-@Sim
-class AuthService {
-  private user: { id: string; role: 'admin' | 'user' } | null = null;
-
-  async login(credentials: { username: string; password: string }) {
-    // Simulate API call
-    this.user = { id: 'user123', role: 'admin' };
-    return this.user;
-  }
-
-  async logout() {
-    this.user = null;
-  }
-
-  getCurrentUser() {
-    return this.user;
-  }
-
-  hasRole(role: string) {
-    return this.user?.role === role;
-  }
-}
-
-@Sim
-class UserService {
-  constructor(private auth: AuthService) {}
-
-  async getUsers() {
-    if (!this.auth.hasRole('admin')) {
-      throw new Error('Unauthorized');
-    }
-    return [
-      { id: '1', name: 'John Doe', email: 'john@example.com' },
-      { id: '2', name: 'Jane Smith', email: 'jane@example.com' }
-    ];
-  }
-
-  async getUserById(id: string) {
-    return { id, name: 'User ' + id, email: `user${id}@example.com` };
-  }
-}
-
-// ============================================
-// 2. ROUTE COMPONENTS (Nested routing)
-// ============================================
-@Sim
-@Router({
-  path: '/admin',
-  route: {
-    '/users': UserListPage,
-    '/users/:id': UserDetailPage,
-    '/settings': SettingsPage
-  }
-})
-@elementDefine('admin-router')
-class AdminRouter extends HTMLElement implements RouterAction.CanActivate {
-  constructor(private auth: AuthService) { super(); }
-
-  @onConnectedInnerHtml({ useShadow: true })
-  render() {
-    return `
-      <style>
-        :host { display: flex; height: 100vh; }
-        .sidebar { width: 200px; background: #333; color: white; padding: 20px; }
-        .sidebar nav a { display: block; margin: 10px 0; color: #0066cc; cursor: pointer; }
-        .content { flex: 1; padding: 20px; }
-      </style>
-      <div class="sidebar">
-        <h3>Admin Panel</h3>
-        <nav>
-          <a swc-on-click="$host.router.go('/admin/users')">Users</a>
-          <a swc-on-click="$host.router.go('/admin/settings')">Settings</a>
-        </nav>
-      </div>
-      <div class="content">
-        <slot></slot>
-      </div>
-    `;
-  }
-
-  // Lifecycle hook: Called BEFORE route transition
-  // Used for permission checks, data preloading, etc.
-  async canActivate(url: RoutingDataSet, data?: any) {
-    // Only admin can enter this route
-    if (!this.auth.hasRole('admin')) {
-      console.warn('Access Denied: Admin role required');
-      return false;
-    }
-
-    // If data is a rendered component (Node), inject it into DOM
-    if (data instanceof Node) {
-      this.replaceChildren(data);
-    }
-
-    return true;
-  }
-}
-
-// ============================================
-// 3. PAGE COMPONENTS (Leaf routes)
-// ============================================
-@Sim
-@elementDefine('user-list-page')
-class UserListPage extends HTMLElement {
-  private users: any[] = [];
-
-  constructor(
-    private userService: UserService,
-    private router: Router,
-    private auth: AuthService
-  ) {
-    super();
-  }
-
-  @onConnected
-  async loadUsers() {
-    try {
-      this.users = await this.userService.getUsers();
-      this.render();
-    } catch (error) {
-      console.error('Failed to load users:', error);
-      this.innerHTML = '<p style="color: red;">Failed to load users</p>';
-    }
-  }
-
-  @onConnectedInnerHtml
-  render() {
-    return `
-      <style>
-        .user-table { width: 100%; border-collapse: collapse; }
-        .user-table th, .user-table td { padding: 10px; text-align: left; border-bottom: 1px solid #ddd; }
-        .user-table tr:hover { background: #f5f5f5; }
-      </style>
-      <h2>Users</h2>
-      <table class="user-table">
-        <thead>
-          <tr><th>Name</th><th>Email</th><th>Actions</th></tr>
-        </thead>
-        <tbody>
-          ${this.users.map(u => `
-            <tr>
-              <td>${u.name}</td>
-              <td>${u.email}</td>
-              <td>
-                <button swc-on-click="$host.router.go('/admin/users/${u.id}')">View</button>
-                <button swc-on-click="$host.deleteUser('${u.id}')">Delete</button>
-              </td>
-            </tr>
-          `).join('')}
-        </tbody>
-      </table>
-    `;
-  }
-
-  deleteUser(id: string) {
-    if (confirm('Delete this user?')) {
-      this.users = this.users.filter(u => u.id !== id);
-      this.render();
-    }
-  }
-}
-
-@Sim
-@elementDefine('user-detail-page')
-class UserDetailPage extends HTMLElement {
-  private user: any = null;
-
-  constructor(
-    private userService: UserService,
-    private router: Router
-  ) {
-    super();
-  }
-
-  @onConnected
-  async loadUser() {
-    // Extract route parameter (:id)
-    const id = this.router.getIntent()?.params?.id;
-    if (id) {
-      this.user = await this.userService.getUserById(id);
-      this.render();
-    }
-  }
-
-  @onConnectedInnerHtml
-  render() {
-    if (!this.user) return '<p>Loading...</p>';
-
-    return `
-      <style>
-        .detail { max-width: 600px; background: #f9f9f9; padding: 20px; border-radius: 8px; }
-        .detail-row { margin: 10px 0; }
-        .detail-label { font-weight: bold; color: #333; }
-      </style>
-      <h2>User Details</h2>
-      <div class="detail">
-        <div class="detail-row">
-          <span class="detail-label">ID:</span> ${this.user.id}
-        </div>
-        <div class="detail-row">
-          <span class="detail-label">Name:</span> ${this.user.name}
-        </div>
-        <div class="detail-row">
-          <span class="detail-label">Email:</span> ${this.user.email}
-        </div>
-      </div>
-      <button swc-on-click="$host.router.back()">Back</button>
-    `;
-  }
-}
-
-// ============================================
-// 4. ROOT ROUTER (Entry point)
-// ============================================
-@Sim
-@Router({
-  path: '/',
-  route: {
-    '/': HomePage,
-    '/login': LoginPage,
-    '/admin': AdminRouter
-  }
-})
-@elementDefine('app-router')
-class RootRouter extends HTMLElement implements RouterAction.CanActivate {
-  constructor(private auth: AuthService) { super(); }
-
-  @onConnectedInnerHtml({ useShadow: true })
-  render() {
-    const user = this.auth.getCurrentUser();
-    return `
-      <style>
-        :host { display: block; font-family: Arial, sans-serif; }
-        header { background: #222; color: white; padding: 15px; }
-        header .user-info { float: right; font-size: 12px; }
-      </style>
-      <header>
-        <h1>SWC App</h1>
-        <div class="user-info">
-          ${user ? `Logged in as: ${user.id} (${user.role})` : 'Not logged in'}
-        </div>
-      </header>
-      <main><slot></slot></main>
-    `;
-  }
-
-  async canActivate(url: RoutingDataSet, data?: any) {
-    if (data instanceof Node) {
-      this.replaceChildren(data);
-    }
-    return true;
-  }
-}
-```
-
----
-
-### 3. Route Lifecycle & Guard Patterns
-
-**The `canActivate` lifecycle hook** is called **before** entering a route. Use it for:
-- **Permission Checks**: Verify user roles and access rights
-- **Data Preloading**: Fetch required data before rendering
-- **Route Interception**: Redirect to login or error pages
-- **Analytics**: Track user navigation
-
-```typescript
-@Router({ path: '/protected', route: { '/data': ProtectedDataPage } })
-@elementDefine('protected-router')
-class ProtectedRouter extends HTMLElement implements RouterAction.CanActivate {
-  constructor(private auth: AuthService) { super(); }
-
-  async canActivate(url: RoutingDataSet, data?: any) {
-    // Guard: Redirect if not authenticated
-    if (!this.auth.getCurrentUser()) {
-      console.log('Redirecting to login...');
-      this.parentElement?.querySelector('app-router')?.routing('/login');
-      return false;
-    }
-
-    // Data injection: Component receives pre-fetched data
-    if (data instanceof Node) {
-      this.replaceChildren(data);
-    }
-
-    return true;
-  }
-}
-```
-
----
-
-### 4. Advanced Patterns: Nested Routers & State Management
-
-```typescript
-// Real-world: Multi-level nested routing with shared state
-@Sim
-class GridStateService {
-  private sortBy = 'name';
-  private filterRole = '';
-
-  setSortBy(field: string) { this.sortBy = field; }
-  setFilterRole(role: string) { this.filterRole = role; }
-  getSortBy() { return this.sortBy; }
-  getFilterRole() { return this.filterRole; }
-}
-
-@Sim
-@Router({
-  path: '/crm',
-  route: {
-    '/contacts': ContactsRouter,
-    '/accounts': AccountsRouter
-  }
-})
-@elementDefine('crm-app')
-class CRMApp extends HTMLElement implements RouterAction.CanActivate {
-  async canActivate(url: RoutingDataSet, data?: any) {
-    if (data instanceof Node) this.replaceChildren(data);
-    return true;
-  }
-
-  @onConnectedInnerHtml
-  render() {
-    return `<div><slot></slot></div>`;
-  }
-}
-```
-
----
-
-## ✉️ Declarative & Scoped Messaging System
-
-SWC provides a **hierarchical messaging architecture** using native browser events with intelligent scoping. No external event bus or state manager needed—messages flow naturally through the DOM hierarchy.
-
-### Message Scope Hierarchy
-
-Messages can target different scopes using **Special Selectors**:
-
-| Selector | Scope | Use Case |
-|----------|-------|----------|
-| **`:appHost`** | Same `<swc-app>` instance | Module-to-module communication (confined) |
-| **`:parentHost`** | Direct parent SWC component | Parent-child coordination |
-| **`:window` / `:document`** | Entire page | Global broadcasts (Cross-app signals) |
-| **`:firstHost` / `:firstAppHost`** | Root of hierarchy | Communication with top-level container |
-| **`selector`** (CSS) | Direct query result | Point-to-point messaging |
-
-### Pattern 1: App-Scoped Communication
-
-Communicate within a micro-app without affecting siblings.
-
-```typescript
-// ========== SENDER COMPONENT ==========
-@Sim
-@elementDefine('auth-panel')
-class AuthPanel extends HTMLElement {
-  constructor(private auth: AuthService) { super(); }
-
-  @onConnectedInnerHtml
-  render() {
-    return `
-      <div style="padding: 10px; background: #f0f0f0; border-radius: 4px;">
-        <button swc-on-click="$host.onLogin()">Login</button>
-        <button swc-on-click="$host.onLogout()">Logout</button>
-      </div>
-    `;
-  }
-
-  // Emit event to the nearest parent <swc-app>
-  @emitCustomEvent(':appHost', 'auth-changed')
-  async onLogin() {
-    await this.auth.login({ username: 'demo', password: 'demo' });
-    return { user: this.auth.getCurrentUser(), timestamp: Date.now() };
-  }
-
-  @emitCustomEvent(':appHost', 'auth-changed')
-  async onLogout() {
-    await this.auth.logout();
-    return { user: null, timestamp: Date.now() };
-  }
-}
-
-// ========== RECEIVER COMPONENT (SAME APP) ==========
-@Sim
-@elementDefine('user-widget')
-class UserWidget extends HTMLElement {
-  private user: any = null;
-
-  @onConnectedInnerHtml
-  render() {
-    return `
-      <div style="padding: 10px; background: #e8f4f8; border-radius: 4px;">
-        ${this.user ? `<p>Welcome, ${this.user.name}!</p>` : '<p>Not logged in</p>'}
-      </div>
-    `;
-  }
-
-  // Listen for auth changes within the same app
-  @addEventListener(':appHost', 'auth-changed')
-  onAuthChanged(event: CustomEvent) {
-    const { detail } = event;
-    this.user = detail.user;
-    this.render();
-    console.log('Auth state changed at:', new Date(detail.timestamp).toLocaleTimeString());
-  }
-}
-
-// HTML
-<swc-app swc-get-application-config="dashboardConfig()">
-  <auth-panel></auth-panel>
-  <user-widget></user-widget>  <!-- Reacts to auth-changed event -->
-</swc-app>
-```
-
-**Result**: When user clicks "Login" in `<auth-panel>`, `<user-widget>` is notified and updates automatically. No explicit imperative connection needed.
-
----
-
-### Pattern 2: Cross-Module (Global) Broadcasting
-
-Send a signal that reaches all apps on the page.
-
-```typescript
-// ========== SENDER (In Module A) ==========
-@Sim
-@elementDefine('notification-sender')
-class NotificationSender extends HTMLElement {
-  @emitCustomEvent(':window', 'system-notification')
-  announceSystemMaintenance() {
-    return {
-      title: 'System Maintenance',
-      message: 'Server will be down for 2 hours',
-      severity: 'warning',
-      timestamp: new Date().toISOString()
-    };
-  }
-
-  @onConnectedInnerHtml
-  render() {
-    return `
-      <button swc-on-click="$host.announceSystemMaintenance()">
-        📢 Broadcast Maintenance Alert
-      </button>
-    `;
-  }
-}
-
-// ========== RECEIVER (In Module B, Different App) ==========
-@Sim
-@elementDefine('notification-display')
-class NotificationDisplay extends HTMLElement {
-  private notifications: any[] = [];
-
-  @addEventListener(':window', 'system-notification')
-  onSystemNotification(event: CustomEvent) {
-    this.notifications.push(event.detail);
-    this.render();
-  }
-
-  @onConnectedInnerHtml
-  render() {
-    return `
-      <div style="position: fixed; top: 10px; right: 10px; font-size: 12px;">
-        ${this.notifications.map(n => `
-          <div style="background: ${n.severity === 'warning' ? '#fff3cd' : '#fff'}; 
-                      border: 1px solid #ffc107; padding: 10px; margin: 5px 0; 
-                      border-radius: 4px; max-width: 300px;">
-            <strong>${n.title}</strong><br>
-            ${n.message}
-          </div>
-        `).join('')}
-      </div>
-    `;
-  }
-}
-
-<!-- Two independent apps receiving the same broadcast -->
-<swc-app swc-get-application-config="moduleAConfig()">
-  <notification-sender></notification-sender>
-</swc-app>
-
-<swc-app swc-get-application-config="moduleBConfig()">
-  <notification-display></notification-display>
-</swc-app>
-```
-
-**Result**: Clicking the button in Module A instantly triggers the notification in Module B, even though they're in separate `<swc-app>` instances.
-
----
-
-### Pattern 3: Hierarchical Parent-Child Messaging
-
-Communicate up and down the component tree with `$parentHost` and `:hosts` selector.
-
-```typescript
-// ========== PARENT CONTAINER ==========
-@Sim
-@elementDefine('modal-container')
-class ModalContainer extends HTMLElement {
-  private modals: any[] = [];
-
-  @onConnectedInnerHtml
-  render() {
-    return `
-      <div style="position: relative;">
-        <slot></slot>
-        ${this.modals.map(m => `
-          <div style="position: fixed; top: 50%; left: 50%; transform: translate(-50%, -50%); 
-                      background: white; border: 2px solid #333; padding: 20px; 
-                      border-radius: 8px; z-index: 1000;">
-            ${m.content}
-            <button swc-on-click="$host.closeModal()">Close</button>
-          </div>
-        `).join('')}
-      </div>
-    `;
-  }
-
-  // Listen for child components requesting to open a modal
-  @addEventListener(':hosts', 'request-modal')
-  onModalRequest(event: CustomEvent) {
-    this.modals.push({ id: Date.now(), content: event.detail.html });
-    this.render();
-    event.stopPropagation();
-  }
-
-  closeModal() {
-    this.modals.pop();
-    this.render();
-  }
-}
-
-// ========== CHILD COMPONENT ==========
-@Sim
-@elementDefine('form-with-modal')
-class FormWithModal extends HTMLElement {
-  @emitCustomEvent(':parentHost', 'request-modal')
-  showHelpModal() {
-    return {
-      html: '<h3>Help</h3><p>Fill in all required fields and click Submit.</p>'
-    };
-  }
-
-  @onConnectedInnerHtml
-  render() {
-    return `
-      <form>
-        <input type="text" placeholder="Full Name" required>
-        <button type="button" swc-on-click="$host.showHelpModal()">?</button>
-        <button type="submit">Submit</button>
-      </form>
-    `;
-  }
-}
-
-<!-- Structure -->
-<modal-container>
-  <form-with-modal></form-with-modal>
-</modal-container>
-```
-
-**Result**: Clicking "?" in the child form opens a modal managed by the parent container.
-
----
-
-### Pattern 4: Event Detail Payloads
-
-Send rich data structures through events.
-
-```typescript
-@Sim
-@elementDefine('data-grid')
-class DataGrid extends HTMLElement {
-  private rows: any[] = [];
-
-  @onConnected
-  loadData() {
-    this.rows = [
-      { id: 1, name: 'Alice', age: 28, department: 'Engineering' },
-      { id: 2, name: 'Bob', age: 34, department: 'Sales' }
-    ];
-    this.render();
-  }
-
-  // Emit complex payload when row is clicked
-  @emitCustomEvent(':appHost', 'row-selected', false) // 3rd arg: whether to bubble
-  selectRow(rowId: number) {
-    const row = this.rows.find(r => r.id === rowId);
-    return {
-      rowId,
-      rowData: row,
-      timestamp: Date.now(),
-      gridId: this.id,
-      userAgent: navigator.userAgent
-    };
-  }
-
-  @onConnectedInnerHtml
-  render() {
-    return `
-      <table>
-        <tbody>
-          ${this.rows.map(row => `
-            <tr swc-on-click="$host.selectRow(${row.id})">
-              <td>${row.name}</td>
-              <td>${row.age}</td>
-              <td>${row.department}</td>
-            </tr>
-          `).join('')}
-        </tbody>
-      </table>
-    `;
-  }
-}
-
-// Listener receives all payload details
-@Sim
-@elementDefine('detail-panel')
-class DetailPanel extends HTMLElement {
-  private selectedData: any = null;
-
-  @addEventListener(':appHost', 'row-selected')
-  onRowSelect(event: CustomEvent) {
-    const { rowData, timestamp } = event.detail;
-    this.selectedData = rowData;
-    console.log(`Selected at ${new Date(timestamp).toLocaleTimeString()}`);
-    this.render();
-  }
-
-  @onConnectedInnerHtml
-  render() {
-    if (!this.selectedData) return '<p>No selection</p>';
-    return `
-      <div>
-        <h3>${this.selectedData.name}</h3>
-        <p>Age: ${this.selectedData.age}</p>
-        <p>Department: ${this.selectedData.department}</p>
-      </div>
-    `;
-  }
-}
-```
-
----
-
-## 🏰 Host Hierarchy, Context Propagation & Template Events
-
-SWC automatically traverses the component tree to provide meaningful **context** to scripts and event handlers. This eliminates the need for prop drilling and global state managers.
-
-### Context Variables (In Templates & Event Handlers)
-
-When you use `swc-on-*` inline events or callback functions, these variables are automatically injected:
-
-| Variable | Type | Description |
-|----------|------|-------------|
-| **`$host`** | `HTMLElement` | The component that owns the event handler (the element itself) |
-| **`$parentHost`** | `HTMLElement` | The direct parent SWC component |
-| **`$appHost`** | `SwcAppInterface` | The nearest parent `<swc-app>` boundary |
-| **`$hosts`** | `HTMLElement[]` | Array of ALL SWC ancestors: `[Root, Parent, ..., Self]` |
-| **`$el`** | `HTMLElement` | The actual DOM element that triggered the event |
-| **`$item`** | `any` | (In `swc-loop`) Current iteration item |
-| **`$index`** | `number` | (In `swc-loop`) Current iteration index |
-
-### Pattern 1: Declarative Inline Events (`swc-on-*`)
-
-Bind events directly in HTML templates. The context is automatically available.
-
-```typescript
-@Sim
-@elementDefine('todo-item')
-class TodoItem extends HTMLElement {
-  private title = '';
-  private done = false;
-
-  constructor(private todoService: TodoService) { super(); }
-
-  @onConnectedInnerHtml
-  render() {
-    return `
-      <style>
-        .completed { text-decoration: line-through; color: #ccc; }
-        button { margin-left: 10px; padding: 2px 8px; cursor: pointer; }
-      </style>
-      <li class="${this.done ? 'completed' : ''}">
-        <!-- Access $host (self), $appHost (parent app), and $item -->
-        <span>${this.title}</span>
-        
-        <!-- Inline script with full context -->
-        <button swc-on-click="
-          $host.toggleDone();
-          console.log('Current item:', $item);
-          console.log('App instance:', $appHost);
-        ">
-          ${this.done ? '✓ Done' : '○ Pending'}
-        </button>
-
-        <button swc-on-click="$host.deleteTodo($index)">
-          🗑️ Delete
-        </button>
-
-        <!-- Access element coordinates -->
-        <button swc-on-click="
-          console.log('Clicked at:', $el.getBoundingClientRect());
-        ">
-          Info
-        </button>
-      </li>
-    `;
-  }
-
-  toggleDone() {
-    this.done = !this.done;
-    this.render();
-  }
-
-  deleteTodo(index: number) {
-    console.log('Deleting todo at index:', index);
-  }
-}
-```
-
-### Pattern 2: Loop Iteration Context
-
-`swc-loop` provides special iteration variables you can access in inline events.
-
-```typescript
-@Sim
-@elementDefine('todo-list')
-class TodoList extends HTMLElement {
-  private todos = [
-    { id: 1, title: 'Learn SWC', done: false },
-    { id: 2, title: 'Build an app', done: false }
-  ];
-
-  @onConnectedInnerHtml
-  render() {
-    return `
-      <ul>
-        <template is="swc-loop" on-get-value="todos"
-            on-clone-node="
-              if ($isElement) {
-                console.log('Cloning item:', $item, 'at index:', $index);
-                $node.querySelector('.index').textContent = $index + 1;
-              }
-            ">
-          <li class="todo-item">
-            <span class="index">0</span>. 
-            <span class="title">${'${item.title}'}</span>
-            <!-- Callback receives full context -->
-            <button swc-on-click="
-              $host.editTodo($item.id, $index, $el);
-              console.log('Hosts hierarchy:', $hosts.map(h => h.tagName));
-            ">
-              Edit
-            </button>
-          </li>
-        </template>
-      </ul>
-    `;
-  }
-
-  editTodo(id: number, index: number, element: HTMLElement) {
-    console.log(`Editing todo #${id} (index: ${index}):`, element);
-  }
-}
-```
-
-### Pattern 3: Accessing Ancestor Services via Context
-
-Use `$appHost` to access services from the parent app's DI container.
-
-```typescript
-@Sim
-@elementDefine('child-component')
-class ChildComponent extends HTMLElement {
-  @onConnectedInnerHtml
-  render() {
-    return `
-      <div>
-        <!-- Access parent app's router to navigate -->
-        <button swc-on-click="$appHost.routing('/dashboard')">
-          Go to Dashboard
-        </button>
-
-        <!-- Access other components in the app -->
-        <button swc-on-click="
-          const sibling = document.querySelector('other-component');
-          sibling.triggerUpdate();
-        ">
-          Notify Sibling
-        </button>
-
-        <!-- Emit event up the tree to parent app -->
-        <button swc-on-click="
-          $appHost.dispatchEvent(new CustomEvent('child-ready', {
-            detail: { child: $host, timestamp: Date.now() }
-          }));
-        ">
-          Notify Parent App
-        </button>
-      </div>
-    `;
-  }
-}
-```
-
-### Pattern 4: Host Hierarchy Traversal
-
-Manually traverse the component tree to find ancestors or siblings.
-
-```typescript
-@Sim
-@elementDefine('deep-child')
-class DeepChild extends HTMLElement {
-  findRootApp() {
-    // Traverse up until you find <swc-app> or root
-    let current = this.parentElement as any;
-    while (current && current.tagName !== 'SWC-APP') {
-      current = current.parentElement;
-    }
-    return current;
-  }
-
-  getSiblingCount() {
-    // Count siblings at same level
-    return this.parentElement?.querySelectorAll(':scope > *').length || 0;
-  }
-
-  @onConnectedInnerHtml
-  render() {
-    return `
-      <div>
-        <p>Root app: ${this.findRootApp()?.getAttribute('id')}</p>
-        <p>Sibling count: ${this.getSiblingCount()}</p>
-      </div>
-    `;
-  }
-}
-```
-
-### Real-World Example: Multi-Level Navigation with Context
-
-```typescript
-// ============ ROOT ROUTER ============
-@Sim
-@Router({ path: '/', route: { '/dashboard': Dashboard, '/profile': Profile } })
-@elementDefine('app-root')
-class AppRoot extends HTMLElement {
-  private breadcrumbs: string[] = [];
-
-  @onConnectedInnerHtml
-  render() {
-    return `
-      <div>
-        <header>
-          <h1>My App</h1>
-          <nav>
-            <button swc-on-click="$host.router.go('/dashboard')">Dashboard</button>
-            <button swc-on-click="$host.router.go('/profile')">Profile</button>
-          </nav>
-          <p>Breadcrumbs: ${this.breadcrumbs.join(' > ')}</p>
-        </header>
-        <main><slot></slot></main>
-      </div>
-    `;
-  }
-}
-
-// ============ CHILD ROUTE ============
-@Sim
-@elementDefine('dashboard-page')
-class DashboardPage extends HTMLElement {
-  @onConnectedInnerHtml
-  render() {
-    return `
-      <div>
-        <h2>Dashboard</h2>
-        <button swc-on-click="
-          console.log('App router:', $appHost.routing);
-          console.log('My tag:', $host.tagName);
-          console.log('All ancestors:', $hosts.map(h => h.tagName).join(' -> '));
-        ">
-          Debug Context
-        </button>
-      </div>
-    `;
-  }
-}
-```
-
----
-
-## 🏰 Advanced Host Context: Query & Portal Patterns
-
-### Custom Query with Root Options
-
-Combine `@query/@queryAll` with the `root` option from host methods to precision-target elements.
-
-```typescript
-@Sim
-@elementDefine('form-validator')
-class FormValidator extends HTMLElement {
-  @query('form', { root: 'light' }) lightForm?: HTMLFormElement;
-  @query('.hidden-form', { root: 'shadow' }) shadowForm?: HTMLFormElement;
-  @queryAll('input', { root: 'all' }) allInputs?: HTMLInputElement[];
-
-  @onConnectedInnerHtml({ useShadow: true })
-  render() {
-    return `
-      <form class="shadow-form">
-        <input type="text" placeholder="Shadow DOM input">
-      </form>
-      <slot></slot>
-    `;
-  }
-
-  validateAllForms() {
-    // Validate both light and shadow DOM forms
-    const allInputs = Array.from(this.allInputs || []);
-    return allInputs.every(input => input.value.trim() !== '');
-  }
-}
-```
-
-### Portal Pattern: Render Content Anywhere
-
-Use `on-get-portal` to render content at a completely different location in the DOM.
-
-```typescript
-@Sim
-@elementDefine('tooltip-manager')
-class TooltipManager extends HTMLElement {
-  private tooltips: any[] = [];
-
-  @onConnectedInnerHtml
-  render() {
-    return `
-      <style>
-        .tooltip { position: fixed; background: #222; color: white; 
-                   padding: 8px 12px; border-radius: 4px; font-size: 12px; }
-      </style>
-      <template is="swc-loop" on-get-value="tooltips"
-          on-get-portal="document.body">
-        <div class="tooltip" style="left: ${'${item.x}px'}; top: ${'${item.y}px'}">
-          ${'${item.text}'}
-        </div>
-      </template>
-    `;
-  }
-
-  addTooltip(text: string, x: number, y: number) {
-    this.tooltips.push({ text, x, y });
-    this.render();
-  }
-}
-
-// Usage: Tooltip renders outside component hierarchy
-const tooltipMgr = document.querySelector('tooltip-manager');
-tooltipMgr.addTooltip('Hover info', 100, 50);
-```
-
-
-
-## 🔄 Structural Directives (Advanced)
-
-SWC provides 4 core templates that empower your HTML without wrapper elements: `swc-loop`, `swc-if`, `swc-choose`, and `swc-async`. They all share a consistent, high-performance API with **zero wrapper elements** and **surgical DOM updates**.
-
-### Common Attributes:
-- **`on-get-value`**: Script to fetch data (evaluated in component context).
-- **`on-clone-node`**: Callback fired for **each individual node clone** (Args: `$node`, `$item`, `$index`, `$isElement`, etc.).
-- **`on-clone-nodes`**: Callback fired **once after all nodes cloned** (Args: `$nodes`, `$elements`, `$state`, etc.).
-- **`on-get-portal`**: Render nodes at a different DOM location using a selector.
-- **`on-state-changed`**: Track rendering state changes.
-
-### 1. `swc-if` - Binary Conditional Rendering
-
-Show/hide content based on a boolean expression. No DOM wrapper.
-
-```typescript
-@Sim
-@elementDefine('access-control')
-class AccessControl extends HTMLElement {
-  private user: any = null;
-  private isLoading = false;
-
-  @onConnectedInnerHtml
-  render() {
-    return `
-      <div class="access-panel">
-        <!-- Show ONLY if loading (no wrapper) -->
-        <template is="swc-if" on-get-value="isLoading">
-          <div class="loading-spinner">
-            <spinner-component></spinner-component>
-            <p>Verifying access...</p>
-          </div>
-        </template>
-
-        <!-- Show ONLY if user is authenticated -->
-        <template is="swc-if" on-get-value="user">
-          <template is="swc-default">
-            <p class="not-authorized">⛔ You are not authorized to view this content.</p>
-          </template>
-          <div class="admin-content">
-            <h2>Welcome, \${user?.name}! 🎉</h2>
-            <p>VIP Access Level: \${user?.role}</p>
-          </div>
-        </template>
-      </div>
-    `;
-  }
-}
-```
-
-### 2. `swc-loop` - High-Performance List Rendering
-
-Iterate over arrays with **index-preserving stability** and zero virtual DOM overhead.
-
-```typescript
-@Sim
-@elementDefine('product-grid')
-class ProductGrid extends HTMLElement {
-  private products = [
-    { id: 1, name: 'Laptop', price: 999 },
-    { id: 2, name: 'Mouse', price: 29 }
-  ];
-
-  @onConnectedInnerHtml
-  render() {
-    return `
-      <template is="swc-loop" on-get-value="products"
-          on-clone-node="
-            if ($isElement) {
-              $node.querySelector('.price').textContent = '$' + $item.price;
-            }
-          ">
-        <div class="product-card">
-          <h3>\${item.name}</h3>
-          <p class="price">$\${item.price}</p>
-        </div>
-      </template>
-    `;
-  }
-}
-```
-
-### 3. `swc-choose` - Multi-Branch Conditional
-
-Switch-like behavior for multiple conditions.
-
-```typescript
-@templateIsSim
-@elementDefine('order-status')
-class OrderStatus extends HTMLElement {
-  private order = { status: 'shipped' };
-
-  @onConnectedInnerHtml
-  render() {
-    return `
-      <template is="swc-choose" on-get-value="order.status">
-        <template is="swc-when" on-get-value="'pending'">
-          <p>⏳ Your order is being prepared...</p>
-        </template>
-        <template is="swc-when" on-get-value="'shipped'">
-          <p>📦 Your order has shipped!</p>
-        </template>
-        <template is="swc-default">
-          <p>❌ Order status unknown</p>
-        </template>
-      </template>
-    `;
-  }
-}
-```
-
-### 4. `swc-async` - Async Content Loading
-
-Automatically handle Promise rendering states.
-
-```typescript
-@Sim
-@elementDefine('async-data')
-class AsyncData extends HTMLElement {
-  async fetchUserData(userId: string) {
-    const response = await fetch(`/api/users/\${userId}`);
-    return response.json();
-  }
-
-  @onConnectedInnerHtml
-  render() {
-    return `
-      <template is="swc-async" on-get-value="fetchUserData('user123')">
-        <template is="swc-pending">
-          <p>Loading...</p>
-        </template>
-        <template is="swc-fulfilled">
-          <h2>\${data.name}</h2>
-          <p>Email: \${data.email}</p>
-        </template>
-        <template is="swc-rejected">
-          <p>❌ Error: \${error.message}</p>
-        </template>
-      </template>
-    `;
-  }
-}
-```
-
----
-
-## 🚀 Server-Side Rendering (SSR) Project Example
-
-SWC integrates seamlessly with `@dooboostore/simple-boot-http-server-ssr` to provide **full-stack SSR** applications with automatic tag-name preservation, hydration, and isomorphic routing.
-
-### Project Structure
-
-```
-ssr-project/
-├── back-end/              # Express/HTTP server with SSR
-│   └── index.ts          # SSR entry point
-├── front-end/            # Client-side app
-│   └── index.ts          # Client bootstrap
-├── src/
-│   ├── bootfactory.ts    # Universal app configuration
-│   ├── components/       # Shared components
-│   └── pages/            # Route components (routers + pages)
-```
-
-### 1. Backend SSR Setup
-
-The backend renders components on the server and sends HTML to the client:
-
-```typescript
-// back-end/index.ts
-import { SimpleBootHttpSSRServer } from '@dooboostore/simple-boot-http-server-ssr';
-import { SSRSimpleWebComponentFilter } from '@dooboostore/simple-boot-http-server-ssr';
-import swcRegister from '@dooboostore/simple-web-component';
-import bootfactory from '@swc-src/bootfactory';
-
-const swcFilter = new SSRSimpleWebComponentFilter({
-  frontDistPath: path.resolve(__dirname, '../dist-front-end'),
-  frontDistIndexFileName: 'index.html',
-  registerComponents: async (window: any) => {
-    // 1. Register core SWC elements (swc-if, swc-loop, etc.)
-    swcRegister(window);
-
-    // 2. Register and bootstrap your app with routing
-    const urlPath = window.location.pathname;
-    bootfactory(window, urlPath);
-
-    console.log('✅ Components registered for SSR');
-  }
-});
-
-const server = new SimpleBootHttpSSRServer({
-  listen: { port: 8080 },
-  filters: [swcFilter]
-});
-
-server.listen();
-console.log('🚀 SSR Server running on http://localhost:8080');
-```
-
-### 2. Universal Bootfactory
-
-The bootfactory runs on **both server and client** with different connection modes:
-
-```typescript
-// src/bootfactory.ts
-import register from '@dooboostore/simple-web-component';
-import { IndexRouter } from './pages/index.router';
-
-export default (window: Window, initialPath?: string) => {
-  // Register all components globally
-  register(window, [...componentFactories, ...pageFactories]);
-
-  const app = window.document.querySelector('#app') as any;
-
-  const config = {
-    rootRouter: IndexRouter.SYMBOL,
-    routeType: 'path',                    // Use browser path: /users, /pages/about
-    path: initialPath ?? '/',
-    window: window
-  };
-
-  // Detect client vs server environment
-  const isClientWindow = typeof window !== 'undefined' && window === globalThis.window;
-
-  if (isClientWindow) {
-    // CLIENT: Use 'swap' mode for zero FOUC hydration
-    app.connect({
-      ...config,
-      connectMode: 'swap'  // Clone → Connect → Replace original
-    });
-  } else {
-    // SERVER: Use 'direct' mode (no swap needed)
-    app.connect(config);
-  }
-
-  return app;
-};
-```
-
-### 3. Isomorphic Router & Pages
-
-Define routers that work the same way on server and client:
-
-```typescript
-// src/pages/index.router.ts
-import { Sim } from '@dooboostore/simple-boot';
-import { Router } from '@dooboostore/simple-boot';
-import { elementDefine, onConnectedInnerHtml, setAttribute } from '@dooboostore/simple-web-component';
-import { RouterAction } from '@dooboostore/simple-boot';
-
-@Sim
-@Router({
-  path: '',
-  route: {
-    '/': HomePage.SYMBOL,
-    '/user': UserPage.SYMBOL
-  }
-})
-@elementDefine('index-router')
-class IndexRouter extends HTMLElement implements RouterAction.CanActivate {
-  constructor(private router: Router) {
-    super();
-  }
-
-  // Lifecycle hook: Called BEFORE entering route
-  async canActivate(url: RoutingDataSet, data?: any) {
-    // Inject rendered page component
-    if (data instanceof Node) {
-      console.log(`✅ Rendering: \${data.nodeName}`);
-      this.replaceChildren(data);
-    }
-  }
-
-  @onConnectedInnerHtml({ useShadow: true })
-  render() {
-    return `
-      <style>
-        :host { display: block; }
-        header { background: #222; color: white; padding: 20px; }
-        nav button { margin: 5px; padding: 10px 15px; cursor: pointer; }
-        section { padding: 20px; }
-      </style>
-      <header>
-        <h1>SWC + SSR App</h1>
-        <nav>
-          <button swc-on-click="$host.router.go('/')">🏠 Home</button>
-          <button swc-on-click="$host.router.go('/user')">👤 Users</button>
-        </nav>
-      </header>
-      <section><slot></slot></section>
-    `;
-  }
-}
-```
-
-### 4. Page Components
-
-```typescript
-// src/pages/home.page.ts - Leaf route (no children)
-@Sim
-@elementDefine('home-page')
-class HomePage extends HTMLElement {
-  @onConnectedInnerHtml
-  render() {
-    return `
-      <h2>Welcome! 👋</h2>
-      <p>This page was rendered on the server and hydrated on the client.</p>
-      <template is="swc-loop" on-get-value="[1,2,3]">
-        <div style="padding: 10px; background: #f5f5f5; margin: 5px;">
-          Item \${item}
-        </div>
-      </template>
-    `;
-  }
-}
-
-// src/pages/user.router.ts - Nested router with sub-routes
-@Sim
-@Router({
-  path: '/user',
-  route: {
-    '': UserListPage.SYMBOL,
-    '/:id': UserDetailPage.SYMBOL
-  }
-})
-@elementDefine('user-router')
-class UserRouter extends HTMLElement implements RouterAction.CanActivate {
-  async canActivate(url: RoutingDataSet, data?: any) {
-    if (data instanceof Node) {
-      this.replaceChildren(data);
-    }
-  }
-
-  @onConnectedInnerHtml({ useShadow: true })
-  render() {
-    return `
-      <div style="margin-left: 20px;">
-        <h2>User Management</h2>
-        <slot></slot>
-      </div>
-    `;
-  }
-}
-```
-
-### 5. Client Entry Point
-
-The client reuses the same bootfactory:
-
-```typescript
-// front-end/index.ts
-import bootfactory from '@swc-src/bootfactory';
-import { UrlUtils } from '@dooboostore/core/url';
-
-console.log('🚀 Client-side app initializing...');
-
-// Get current URL path from browser
-const currentPath = UrlUtils.getUrlPath(window.location);
-
-// Bootstrap with swap mode (zero FOUC)
-bootfactory(window, currentPath);
-
-console.log('✅ Client app hydrated');
-```
-
-### 6. Flow Diagram
-
-```
-┌─────────────────────────────────────────────────────────┐
-│                     User Request                        │
-│                   GET /user/123                         │
-└──────────────────────┬──────────────────────────────────┘
-                       │
-        ┌──────────────▼──────────────┐
-        │  Backend SSR Renderer       │
-        ├─────────────────────────────┤
-        │ 1. bootfactory(virtualWin)  │
-        │ 2. IndexRouter routes       │
-        │ 3. UserRouter renders       │
-        │ 4. UserDetailPage → HTML    │
-        └──────────────┬──────────────┘
-                       │
-        ┌──────────────▼──────────────┐
-        │   Sent to Client as HTML    │
-        │  <swc-app>                  │
-        │   <index-router>            │
-        │    <user-router>            │
-        │     <user-detail-page>      │
-        │    </user-detail-page>      │
-        │    </user-router>           │
-        │   </index-router>           │
-        │  </swc-app>                 │
-        └──────────────┬──────────────┘
-                       │
-        ┌──────────────▼──────────────┐
-        │   Client Hydration Swap     │
-        ├─────────────────────────────┤
-        │ 1. Clone SSR HTML           │
-        │ 2. Connect listeners        │
-        │ 3. Replace original DOM     │
-        │ 4. Fully interactive        │
-        └─────────────────────────────┘
-```
-
-### 7. Key Benefits
-
-| Aspect | Benefit |
-|--------|---------|
-| **SEO** | Server renders initial HTML (searchable) |
-| **Performance** | Faster First Contentful Paint (FCP) |
-| **Tag Preservation** | Custom element tags survive SSR → client |
-| **Zero FOUC** | Swap mode clones & replaces seamlessly |
-| **Code Sharing** | Same router code on server & client |
-| **Island Architecture** | Multiple independent `<swc-app>` instances |
-| **Progressive Enhancement** | Works without JavaScript (graceful fallback) |
-
-### 8. Build & Run
-
-```bash
-# Build backend (Node.js server)
-cd back-end && npm run build
-
-# Build frontend (browser bundle)
-cd front-end && npm run build
-
-# Run SSR server on http://localhost:8080
-npm start
-
-# Visit http://localhost:8080/user/123
-# Server renders UserDetailPage → Client hydrates with swap mode
-```
-
----
+## 🔗 Related Packages
 
-## ⚡ Performance Features
-- **Zero "Deep Scan"**: Listeners and queries are only bound to specific selectors.
-- **Surgical Updates**: Manipulate DOM directly in `@changedAttribute` instead of full re-renders.
-- **Zero Background Overhead**: No polling, no background observers.
-- **Smart Delegation**: Host-level delegation with `__swc_handled` duplicate protection.
-- **Index-Preserving Removal**: `SwcLoop` maintains stable indices during item removal for maximum UI consistency.
+- **[@dooboostore/simple-boot](../simple-boot)** - DI & AOP Container
+- **[@dooboostore/core-web](../core-web)** - Web Utilities & Router
+- **[@dooboostore/dom-parser](../dom-parser)** - HTML Parsing & AST
 
 ---
 
-## 📜 License
-MIT
+## 📄 License
+MIT © 2024 dooboostore-develop