@dooboostore/simple-web-component 1.0.11 → 1.0.12

package/README.md

@@ -1,7 +1,21 @@
 # @dooboostore/simple-web-component
 
-A lightweight UI library built on top of the native Web Components API with a **TypeScript decorator-based reactive system**.  
-Updates only the specific text nodes and attributes bound to data — no Virtual DOM, no diffing.
+> **Web Standards. Zero Virtual DOM. Surgical Updates.**
+
+Build reactive UIs using nothing but the browser's own APIs — Custom Elements, Shadow DOM, Proxy, and MutationObserver.  
+No diffing. No runtime overhead. Just the DOM, done right.
+
+---
+
+## Why SWC?
+
+Most UI libraries bring their own runtime, their own DOM, their own rules.  
+SWC doesn't. It enhances what the browser already gives you.
+
+- **`{{expression}}`** — binds directly to text nodes and attributes. Only that node updates when data changes.
+- **`<template is="swc-for-of">`** — loop over a list using a real `<template>` tag. No custom syntax, no compiler.
+- **`swc-on-click="$host.save()"`** — call your component's method from any nested element. No event bubbling gymnastics.
+- **TypeScript decorators** — `@state`, `@attribute`, `@addEventListener` feel like Angular but weigh almost nothing.
 
 ---
 
@@ -11,26 +25,25 @@ Updates only the specific text nodes and attributes bound to data — no Virtual
 pnpm add @dooboostore/simple-web-component reflect-metadata
 ```
 
-Add this at the very top of your entry point:
-
 ```typescript
+// Entry point — must be first
 import 'reflect-metadata';
 ```
 
-> **Safari Support** — The `is` attribute requires a polyfill:
+> **Safari** requires a polyfill for the `is` attribute:
 > ```bash
 > pnpm add @ungap/custom-elements
 > ```
-> ```typescript
-> import '@ungap/custom-elements';
-> import 'reflect-metadata';
+> ```html
+> <script src="https://unpkg.com/@ungap/custom-elements"></script>
 > ```
 
 ---
 
-## Quick Start
+## 30-Second Example
 
 ```typescript
+import 'reflect-metadata';
 import { elementDefine, innerHtml, state, addEventListener } from '@dooboostore/simple-web-component';
 
 @elementDefine('my-counter')
@@ -39,13 +52,14 @@ class MyCounter extends HTMLElement {
 
   @innerHtml({ useShadow: true })
   render() {
-    return `<button id="btn">Clicked: {{count}} times</button>`;
+    return `
+      <button id="btn">Clicked {{count}} times</button>
+      <p>{{count > 5 ? '🔥 On fire!' : 'Keep going...'}}</p>
+    `;
   }
 
   @addEventListener({ type: 'click', query: '#btn' })
-  onClick() {
-    this.count++;
-  }
+  onClick() { this.count++; }
 }
 ```
 
@@ -53,181 +67,231 @@ class MyCounter extends HTMLElement {
 <my-counter></my-counter>
 ```
 
+That's it. No build config changes. No JSX. No virtual DOM.
+
 ---
 
-## Decorator API
+## The `<template>` Pattern — HTML-First Logic
 
-### `@elementDefine(config)`
+The most powerful feature of SWC is using the native `<template>` tag as a logic container.  
+Your HTML stays semantic. Your logic lives in the markup. No JS required to wire it up.
+
+### Loop — `<template is="swc-for-of">`
 
-Registers a Custom Element.
+```html
+<ul class="user-list">
+  <template is="swc-for-of" id="user-loop" as-item="user" as-index="i">
+    <li>
+      <strong>#{{i}}</strong>: {{user.name}}
+      <span class="{{user.active ? 'badge-green' : 'badge-red'}}">
+        {{user.active ? 'Active' : 'Offline'}}
+      </span>
+    </li>
+  </template>
+</ul>
+```
 
 ```typescript
-// Tag name only
-@elementDefine('my-component')
-class MyComponent extends HTMLElement {}
-
-// With options
-@elementDefine({
-  name: 'my-component',
-  extends: 'div',                  // Extend a built-in tag (used with `is` attribute)
-  observedAttributes: ['data-id'], // Additional observed attributes
-  autoRemoveEventListeners: true,  // Auto-remove listeners on disconnect (default: true)
-  window: w,                       // Custom window injection (SSR, multi-window)
-})
-class MyComponent extends HTMLElement {}
+const loop = document.querySelector('#user-loop') as SwcForOf;
+loop.value = [
+  { name: 'Alice', active: true },
+  { name: 'Bob',   active: false },
+];
+
+// Reactive — push/splice trigger surgical DOM updates
+loop.value.push({ name: 'Carol', active: true });
 ```
 
----
+The `<template>` tag is invisible by default. SWC uses it as a blueprint and stamps out clones for each item. The wrapper `<ul>` is untouched — it stays in the DOM exactly as you wrote it.
 
-### `@innerHtml(options?)`
+### Conditional — `<template is="swc-if">`
 
-Defines the component template. Use `{{varName}}` syntax for data binding.
+```html
+<template is="swc-if" id="alert-box">
+  <div class="alert">⚠️ Something went wrong!</div>
+</template>
+```
 
 ```typescript
-@elementDefine('my-card')
-class MyCard extends HTMLElement {
-  @state title = 'Hello';
-  @state count = 0;
+const box = document.querySelector('#alert-box') as SwcIf;
+box.value = true;   // content appears in DOM
+box.value = false;  // content is physically removed
+```
 
-  // Light DOM (default)
-  @innerHtml
-  render() {
-    return `<h1>{{title}}</h1><p>Count: {{count}}</p>`;
-  }
-}
+### Switch/Case — `<template is="swc-choose">`
+
+```html
+<template is="swc-choose" id="status-panel">
+  <template is="swc-when" test="loading">
+    <div class="spinner">⏳ Loading...</div>
+  </template>
+  <template is="swc-when" test="error">
+    <div class="error">❌ Something went wrong</div>
+  </template>
+  <template is="swc-when" test="success">
+    <div class="success">✅ Done!</div>
+  </template>
+  <template is="swc-other">
+    <div class="idle">⚪ Waiting...</div>
+  </template>
+</template>
 ```
 
 ```typescript
-// Shadow DOM
-@innerHtml({ useShadow: true })
-render() {
-  return `
-    <style>h1 { color: blue; }</style>
-    <h1>{{title}}</h1>
-  `;
-}
+const panel = document.querySelector('#status-panel') as SwcChoose;
+panel.value = 'loading';  // shows spinner
+panel.value = 'success';  // shows ✅
+panel.value = 'unknown';  // shows ⚪ (swc-other)
+```
+
+### Object Binding — `<template is="swc-object">`
+
+```html
+<template is="swc-object" id="user-card" as="u">
+  <div class="card">
+    <h2>{{u.name}}</h2>
+    <p>Age: {{u.age}}</p>
+    <p>Role: {{u.role.toUpperCase()}}</p>
+  </div>
+</template>
 ```
 
 ```typescript
-// Shadow DOM + Light DOM simultaneously
-@innerHtml({ useShadow: true })
-shadowContent() {
-  return `<style>:host { display: block; }</style><slot></slot>`;
-}
+const card = document.querySelector('#user-card') as SwcObject;
+card.value = { name: 'Alice', age: 28, role: 'admin' };
 
-@innerHtml
-lightContent() {
-  return `<p>Light DOM: {{name}}</p>`;
-}
+// Proxy-based — nested changes are reactive
+card.value.name = 'Bob';  // DOM updates instantly
 ```
 
-Async templates are supported:
+---
+
+## Decorator API
+
+### `@elementDefine(config)`
 
 ```typescript
-@innerHtml
-async render() {
-  const data = await fetch('/api/data').then(r => r.json());
-  return `<p>${data.message}</p>`;
-}
+@elementDefine('my-button')                          // simple
+@elementDefine({ name: 'my-button', window: w })     // with options
+@elementDefine({ name: 'my-button', extends: 'button', autoRemoveEventListeners: true })
 ```
 
+| Option | Default | Description |
+|---|---|---|
+| `name` | required | Custom element tag name |
+| `extends` | auto-detected | Extend a built-in HTML element |
+| `autoRemoveEventListeners` | `true` | Clean up listeners on disconnect |
+| `window` | global `window` | Inject a custom window (SSR, multi-window) |
+
 ---
 
-### `@state(alias?)`
+### `@innerHtml(options?)`
 
-Declares a reactive property. When the value changes, only the bound DOM nodes are surgically updated.
+Defines the component's template. Supports async, Shadow DOM, and multiple render methods.
 
 ```typescript
-@elementDefine('user-card')
-class UserCard extends HTMLElement {
-  @state name = 'Kim';
-  @state age = 30;
-  @state('userName') displayName = 'Kim'; // Access as {{userName}} in template
+// Light DOM (default)
+@innerHtml
+render() { return `<p>Hello {{name}}</p>`; }
 
-  @innerHtml
-  render() {
-    return `
-      <p>Name: {{name}}</p>
-      <p>Age: {{age}}</p>
-      <p>Display: {{userName}}</p>
-    `;
-  }
+// Shadow DOM with encapsulated styles
+@innerHtml({ useShadow: true })
+render() {
+  return `
+    <style>p { color: blue; }</style>
+    <p>Hello {{name}}</p>
+  `;
 }
-```
 
-Objects and arrays are also reactive:
+// Async — fetch data before rendering
+@innerHtml
+async render() {
+  const { title } = await fetch('/api/config').then(r => r.json());
+  return `<h1>${title}</h1>`;
+}
 
-```typescript
-@state user = { name: 'Kim', age: 30 };
-@state items = ['a', 'b', 'c'];
+// Both Shadow and Light DOM simultaneously
+@innerHtml({ useShadow: true })
+shadow() { return `<style>:host{display:block}</style><slot></slot>`; }
 
-// Nested property changes are detected
-this.user.name = 'Lee';   // DOM auto-updates
-this.items.push('d');     // DOM auto-updates
+@innerHtml
+light() { return `<p>{{description}}</p>`; }
 ```
 
 ---
 
-### `@attribute(options?)`
+### `@state(alias?)`
 
-Syncs an HTML attribute with a JS property bidirectionally.
+Reactive property. Changes trigger surgical DOM updates — only the bound nodes are touched.
 
 ```typescript
-@elementDefine('my-input')
-class MyInput extends HTMLElement {
-  @attribute() label = '';                     // attribute name: label
-  @attribute('data-count') count = 0;          // attribute name: data-count
-  @attribute({ type: Number }) size = 10;      // type conversion
-  @attribute({ type: Boolean }) disabled = false;
-  @attribute({ type: Object }) config = {};
-  @attribute({ disableReflect: true }) secret = ''; // JS→HTML reflection disabled
+@state name = 'Alice';
+@state count = 0;
+@state('userName') displayName = 'Alice';  // template uses {{userName}}
 
-  @innerHtml
-  render() {
-    return `<label>{{label}}: {{count}}</label>`;
-  }
-}
+// Objects and arrays — nested changes are reactive via Proxy
+@state user = { name: 'Alice', scores: [10, 20, 30] };
+@state items: string[] = [];
+
+// These all trigger DOM updates:
+this.name = 'Bob';
+this.user.name = 'Bob';
+this.items.push('new item');
+this.user.scores[0] = 99;
 ```
 
+Template expressions — full JS expressions work:
+
 ```html
-<my-input label="Name" data-count="5" disabled></my-input>
+<p>{{count + 1}} of {{total}}</p>
+<p class="{{score > 90 ? 'gold' : 'silver'}}">{{score}}</p>
+<p>{{items.length === 0 ? 'Empty' : items.join(', ')}}</p>
 ```
 
-Combine with `@state` for reactive attribute handling:
+---
+
+### `@attribute(options?)`
+
+Syncs an HTML attribute ↔ JS property. Supports type coercion.
 
 ```typescript
+@attribute() label = '';                          // attr: label
+@attribute('data-id') itemId = '';                // attr: data-id
+@attribute({ type: Number }) count = 0;           // auto-converts "5" → 5
+@attribute({ type: Boolean }) disabled = false;   // presence → true
+@attribute({ type: Object }) config = {};         // JSON.parse/stringify
+@attribute({ disableReflect: true }) secret = ''; // JS-only, not reflected to HTML
+
+// Combine with @state for reactive attributes
 @state @attribute({ type: Number }) count = 0;
 ```
 
+```html
+<!-- Set initial values from HTML -->
+<my-input label="Email" data-id="42" disabled></my-input>
+```
+
 ---
 
 ### `@query(selector?)` / `@queryAll(selector?)`
 
-Lazily binds DOM elements.
-
 ```typescript
-@elementDefine('form-component')
-class FormComponent extends HTMLElement {
-  // Property getter
-  @query('input[name="email"]') emailInput!: HTMLInputElement;
-  @queryAll('li') listItems!: NodeListOf<HTMLLIElement>;
-
-  // Method — called once after connectedCallback
-  @query('input')
-  onInputReady(el: HTMLInputElement) {
-    el.focus();
-  }
-
-  // Search in Shadow DOM
-  @query({ selector: 'p', root: 'shadow' }) shadowP!: HTMLElement;
-
-  // Search in Light DOM
-  @query({ selector: 'slot', root: 'light' }) slotEl!: HTMLSlotElement;
-
-  @innerHtml({ useShadow: true })
-  render() {
-    return `<input name="email" type="email" /><p>Status</p>`;
-  }
+// Property getter — lazy, always fresh
+@query('input[name="email"]') emailInput!: HTMLInputElement;
+@queryAll('li.item') items!: NodeListOf<HTMLLIElement>;
+
+// No selector = the host element itself
+@query hostEl!: HTMLElement;
+
+// Scoped search
+@query({ selector: 'button', root: 'shadow' }) shadowBtn!: HTMLButtonElement;
+@query({ selector: 'slot',   root: 'light'  }) slot!: HTMLSlotElement;
+
+// Method form — called once after connectedCallback
+@query('canvas')
+onCanvasReady(canvas: HTMLCanvasElement) {
+  const ctx = canvas.getContext('2d');
+  // initialize...
 }
 ```
 
@@ -235,41 +299,27 @@ class FormComponent extends HTMLElement {
 
 ### `@addEventListener(options)`
 
-Declaratively registers event listeners. Auto-removed on disconnect when `autoRemoveEventListeners: true` (default).
+Declarative event binding. Auto-removed on disconnect.
 
 ```typescript
-@elementDefine('event-demo')
-class EventDemo extends HTMLElement {
-  @state value = '';
-
-  @innerHtml({ useShadow: true })
-  render() {
-    return `
-      <input id="input" type="text" />
-      <button id="submit-btn">Submit</button>
-    `;
-  }
-
-  @addEventListener({ type: 'input', query: '#input' })
-  onInput(event: InputEvent) {
-    this.value = (event.target as HTMLInputElement).value;
-  }
-
-  @addEventListener({
-    type: 'click',
-    query: '#submit-btn',
-    stopPropagation: true,
-    preventDefault: true,
-  })
-  onSubmit() {
-    console.log('Submitted:', this.value);
-  }
+// Basic
+@addEventListener({ type: 'click', query: '#save-btn' })
+onSave() { this.save(); }
+
+// With modifiers
+@addEventListener({ type: 'submit', query: 'form', preventDefault: true, stopPropagation: true })
+onSubmit(event: SubmitEvent) { /* ... */ }
+
+// Host element (no query)
+@addEventListener({ type: 'keydown' })
+onKeyDown(event: KeyboardEvent) {
+  if (event.key === 'Escape') this.close();
+}
 
-  // Host element event (no query)
-  @addEventListener({ type: 'click' })
-  onHostClick(event: MouseEvent) {
-    console.log('Component clicked');
-  }
+// Shadow DOM scope
+@addEventListener({ type: 'click', query: '.tab', root: 'shadow' })
+onTabClick(event: MouseEvent, target: Element) {
+  this.activeTab = target.dataset.tab!;
 }
 ```
 
@@ -277,28 +327,25 @@ class EventDemo extends HTMLElement {
 
 ### `@emitCustomEvent(options)`
 
-Automatically dispatches a `CustomEvent` with the method's return value as `detail`.
+Wraps a method to automatically dispatch a `CustomEvent` with the return value as `detail`.
 
 ```typescript
-@elementDefine('data-emitter')
-class DataEmitter extends HTMLElement {
-  @emitCustomEvent('data-change')
-  updateData() {
-    return { value: 42, timestamp: Date.now() };
-    // → CustomEvent('data-change', { detail: { value: 42, ... } })
-  }
+@emitCustomEvent('user-saved')
+save() {
+  return { id: this.userId, name: this.name };
+  // → dispatches CustomEvent('user-saved', { detail: { id, name }, bubbles: true })
+}
 
-  @emitCustomEvent({ type: 'user-select', bubbles: true, composed: true })
-  selectUser(id: number) {
-    return { id, name: 'Kim' };
-  }
+@emitCustomEvent({ type: 'item-select', bubbles: true, composed: true })
+selectItem(id: string) {
+  return { id, timestamp: Date.now() };
 }
 ```
 
 ```typescript
-// Listen from parent
-document.querySelector('data-emitter')?.addEventListener('data-change', (e: CustomEvent) => {
-  console.log(e.detail); // { value: 42, timestamp: ... }
+// Listen from anywhere in the tree
+document.addEventListener('user-saved', (e: CustomEvent) => {
+  console.log('Saved:', e.detail); // { id: '...', name: '...' }
 });
 ```
 
@@ -306,105 +353,66 @@ document.querySelector('data-emitter')?.addEventListener('data-change', (e: Cust
 
 ## Lifecycle Hooks
 
-### Decorator Hooks
-
 ```typescript
-@elementDefine('lifecycle-demo')
-class LifecycleDemo extends HTMLElement {
-  @onBeforeConnected
-  beforeConnect() { console.log('Before template injection'); }
-
-  @onAfterConnected  // alias: @onConnected
-  afterConnect() { console.log('After template injection and binding'); }
-
-  @onBeforeDisconnected
-  beforeDisconnect() { console.log('Before removal from DOM'); }
-
-  @onAfterDisconnected  // alias: @onDisconnected
-  afterDisconnect() { console.log('After removal and cleanup'); }
+@elementDefine('my-element')
+class MyElement extends HTMLElement {
+  @onBeforeConnected  beforeConnect()  { /* before template injection */ }
+  @onAfterConnected   afterConnect()   { /* after template + binding ready */ }
+  @onBeforeDisconnected beforeDisconnect() { /* cleanup prep */ }
+  @onAfterDisconnected  afterDisconnect()  { /* fully removed */ }
 
   // Single attribute
   @onAttributeChanged('name')
-  onNameChange(newVal: string, oldVal: string, attrName: string) {
-    console.log(`name: ${oldVal} → ${newVal}`);
-  }
-
-  // MutationSubscriber
-  @onMutationSubscribe({root: 'all'})
-  onMutationSubscribe(mutations: MutationRecord[], observer: MutationObserver, root: 'light' | 'shadow') {
-    console.log('mutations', mutations, observer, root);
-  }
-  
-  // Wildcard: any attribute change
-  @onAttributeChanged
-  onAnyChange(newVal: string, oldVal: string, attrName: string) {
-    console.log(`${attrName} changed`);
-  }
+  onNameChange(newVal: string, oldVal: string) { }
 
   // Multiple attributes
   @onAttributeChanged(['name', 'age'])
-  onNameOrAgeChange(newVal: string, oldVal: string, attrName: string) {
-    console.log(`${attrName} changed`);
-  }
+  onNameOrAge(newVal: string, oldVal: string, attr: string) { }
+
+  // Wildcard — any attribute
+  @onAttributeChanged
+  onAnyAttr(newVal: string, oldVal: string, attr: string) { }
 
-  @onAddEventListener
-  onListenerAdded(el: Element, type: string, handler: EventListener) {
-    console.log(`Event registered: ${type}`);
+  // MutationObserver lifecycle
+  @onMutationSubscribe({ root: 'all' })
+  onDomChanged(mutations: MutationRecord[], observer: MutationObserver) {
+    console.log('DOM changed:', mutations.length, 'mutations');
   }
+
+  @onMutationSubscribe({ root: 'shadow' })
+  onShadowChanged(mutations: MutationRecord[]) { }
+
+  @onMutationSubscribe({ root: 'light' })
+  onLightChanged(mutations: MutationRecord[]) { }
 }
 ```
 
 ### HTML Attribute Hooks (Zero-JS)
 
-Execute scripts directly in HTML without any JS class definition.
-
 ```html
-<my-component
+<my-element
   swc-on-constructor="console.log('created', this)"
   swc-on-connected="console.log('connected', $host)"
   swc-on-disconnected="console.log('removed')"
-  swc-on-attribute-changed="console.log($name, $old, '→', $new)"
-></my-component>
-```
-
----
-
-## Template Binding & Expressions
-
-```typescript
-@state user = { name: 'Kim', age: 30 };
-@state items = ['apple', 'banana'];
-@state isActive = true;
-@state count = 0;
-```
-
-```html
-<!-- Simple value -->
-<p>{{name}}</p>
-
-<!-- Object path -->
-<p>{{user.name}} (age: {{user.age}})</p>
-
-<!-- Expressions -->
-<p>Item #{{count + 1}}</p>
-<p class="{{isActive ? 'active' : 'inactive'}}">Status</p>
-<p>{{items.length}} items</p>
+  swc-on-attribute-changed="console.log($name, ':', $old, '→', $new)"
+></my-element>
 ```
 
 ---
 
-## Inline Event Handler Variables
+## Inline Event Scripts & Built-in Variables
 
-Available variables in all `swc-on-*` attribute scripts:
+Every `swc-on-*` attribute has access to these variables at runtime:
 
-| Variable | Description |
+| Variable | Value |
 |---|---|
-| `this` | The DOM element where the event fired |
-| `event` | The event object |
+| `this` | The element the attribute is on |
+| `event` | The native Event object |
 | `$data` | `event.detail` (CustomEvent) |
-| `$host` / `$lastHost` | Nearest SWC parent component |
-| `$firstHost` | Top-most SWC ancestor component |
-| `$hosts` | All SWC ancestors array `[root, ..., parent]` |
+| `$host` | Nearest SWC parent component |
+| `$firstHost` | Top-most SWC ancestor |
+| `$lastHost` | Same as `$host` |
+| `$hosts` | All SWC ancestors `[root, ..., parent]` |
 | `$q(sel, root?)` | `querySelector` shorthand |
 | `$qa(sel, root?)` | `querySelectorAll` → Array |
 | `$qi(id, root?)` | `getElementById` shorthand |
@@ -412,160 +420,60 @@ Available variables in all `swc-on-*` attribute scripts:
 | `$w` | `window` |
 
 ```html
-<!-- Call host component method -->
+<!-- Call host method directly -->
 <button swc-on-click="$host.save();">Save</button>
 
-<!-- Access top-most component in nested structure -->
-<button swc-on-click="$firstHost.logout();">Logout</button>
+<!-- Access top-most ancestor (useful inside swc-for-of) -->
+<button swc-on-click="$firstHost.deleteItem({{i}});">Delete</button>
 
-<!-- DOM query shorthands -->
+<!-- DOM shortcuts -->
 <button swc-on-click="$qi('modal')?.show();">Open Modal</button>
-<button swc-on-click="$q('.panel', $host.shadowRoot)?.classList.toggle('open');">Panel</button>
+<button swc-on-click="$q('.panel', $host.shadowRoot)?.classList.toggle('open');">Toggle</button>
 
-<!-- Event object -->
-<input swc-on-input="$host.name = event.target.value" />
+<!-- Two-way binding via inline event -->
+<input swc-on-input="$host.name = event.target.value" value="{{name}}" />
 
 <!-- Run once on connect -->
-<div swc-on-connected="console.log('connected', $host, $firstHost)"></div>
+<canvas swc-on-connected="$qi('{{id}}')?.getContext('2d')"></canvas>
 ```
 
 ---
 
-## Built-in Logic Components
-
-All standard HTML tags support logic via the `is` attribute.  
-Pass data with `swc-value`, item alias with `as`, index alias with `as-index`.
-
-### `swc-for-of` — Loop (removes element when array is empty)
-
-```html
-<!-- Standalone component -->
-<swc-for-of swc-value="{{users}}" as="u">
-  <div>{{u.name}}</div>
-</swc-for-of>
-
-<!-- is attribute (keeps semantic HTML) -->
-<ul is="swc-for-of-ul" swc-value="{{users}}" as="u" as-index="i">
-  <li>{{i + 1}}. {{u.name}} — {{u.active ? 'Active' : 'Inactive'}}</li>
-</ul>
-```
-
-```typescript
-const list = document.querySelector('ul[is="swc-for-of-ul"]') as SwcForOfUl;
-list.swcValue = [{ name: 'Kim', active: true }, { name: 'Lee', active: false }];
-list.addRow({ name: 'Park', active: true });  // add row
-list.removeRow(0);                             // remove first row
-```
-
-### `swc-for-of-children` — Loop (keeps wrapper element)
-
-```html
-<ul is="swc-for-of-children-ul" swc-value="{{items}}" as="item" as-index="idx">
-  <li class="{{item.done ? 'done' : ''}}">
-    {{idx + 1}}. {{item.text}}
-    <button swc-on-click="$firstHost.removeItem({{idx}});">Delete</button>
-  </li>
-</ul>
-```
-
-### `swc-if` — Conditional rendering (removes from DOM when false)
-
-```html
-<swc-if swc-value="{{isLoggedIn}}">
-  <p>Welcome!</p>
-</swc-if>
-
-<div is="swc-if-div" swc-value="{{isVisible}}" style="background: yellow;">
-  <b>Conditional content</b>
-</div>
-```
-
-```typescript
-const el = document.querySelector('[is="swc-if-div"]') as SwcIfDiv;
-el.swcValue = true;   // insert into DOM
-el.swcValue = false;  // remove from DOM
-```
-
-### `swc-if-children` — Conditional rendering (keeps wrapper, swaps children)
-
-```html
-<section is="swc-if-children-section" swc-value="{{showContent}}">
-  <p>Shown only when showContent is true.</p>
-</section>
-```
-
-### `swc-choose` / `swc-when` / `swc-other` — Switch/Case
+## Nested Components & Hierarchical Context
 
-```html
-<!-- Removes element if no case matches -->
-<div is="swc-choose-div" swc-value="{{status}}">
-  <span is="swc-when-span" test="'loading'">⏳ Loading...</span>
-  <span is="swc-when-span" test="'error'">❌ Error</span>
-  <span is="swc-when-span" test="'success'">✅ Done</span>
-  <span is="swc-other-span">⚪ Idle</span>
-</div>
-```
+SWC tracks the component tree automatically. From any nested element, you can reach up to any ancestor.
 
 ```typescript
-const el = document.querySelector('[is="swc-choose-div"]') as SwcChooseDiv;
-el.swcValue = 'loading';  // shows "⏳ Loading..."
-el.swcValue = 'success';  // shows "✅ Done"
-el.swcValue = 'unknown';  // shows "⚪ Idle" (swc-other)
-```
-
-### `swc-choose-children` — Switch/Case (keeps wrapper)
-
-```html
-<div is="swc-choose-children-div" swc-value="{{tab}}">
-  <div is="swc-when-div" test="'home'">Home tab content</div>
-  <div is="swc-when-div" test="'profile'">Profile tab content</div>
-  <div is="swc-other-div">Default tab content</div>
-</div>
-```
-
-### `swc-object` — Object binding
-
-```html
-<div is="swc-object-div" swc-value="{{user}}" as="u">
-  <p>Name: {{u.name}}</p>
-  <p>Age: {{u.age}}</p>
-</div>
-```
-
-```typescript
-const el = document.querySelector('[is="swc-object-div"]') as SwcObjectDiv;
-el.swcValue = { name: 'Kim', age: 30 };
-el.swcValue.name = 'Lee';  // Proxy reactive — DOM auto-updates
-```
-
----
-
-## Hierarchical Context (`$host` System)
-
-Access parent components from nested components.
-
-```typescript
-@elementDefine('parent-comp')
-class ParentComp extends HTMLElement {
-  @state count = 0;
-  @state items = [{ name: 'Item 1' }, { name: 'Item 2' }];
+@elementDefine('user-list')
+class UserList extends HTMLElement {
+  @state users = [
+    { id: 1, name: 'Alice', active: true },
+    { id: 2, name: 'Bob',   active: false },
+  ];
+  @state currentUser = { name: 'Admin', role: 'admin' };
 
-  removeItem(index: number) {
-    this.items.splice(index, 1);
+  removeUser(index: number) {
+    this.users.splice(index, 1);
   }
 
   @innerHtml({ useShadow: true })
   render() {
     return `
-      <p>Count: {{count}}</p>
-      <!-- Call parent method from child event -->
-      <button swc-on-click="$host.count++;">Increment</button>
-
-      <!-- In nested for-of: $host = swc-for-of-children-ul, $firstHost = parent-comp -->
-      <ul is="swc-for-of-children-ul" swc-value="{{items}}" as="item" as-index="i">
-        <li>
-          {{item.name}}
-          <button swc-on-click="$firstHost.removeItem({{i}});">Delete</button>
+      <p>Logged in as: <strong>{{currentUser.name}}</strong></p>
+
+      <ul is="swc-for-of-ul" value="{{users}}" as="u" as-index="i">
+        <li class="{{u.active ? 'active' : 'inactive'}}">
+          #{{i + 1}} — {{u.name}}
+
+          <!--
+            $host     = swc-for-of-ul (nearest SWC parent)
+            $firstHost = user-list    (top-most SWC ancestor)
+
+            Access parent @state directly in child template:
+            {{currentUser.name}} resolves from user-list's @state
+          -->
+          <small>by {{currentUser.name}}</small>
+          <button swc-on-click="$firstHost.removeUser({{i}});">✕</button>
         </li>
       </ul>
     `;
@@ -573,32 +481,25 @@ class ParentComp extends HTMLElement {
 }
 ```
 
-### Accessing parent `@state` from nested components
+### Alias System (`as` / `as-index`)
 
-```typescript
-@elementDefine('app-root')
-class AppRoot extends HTMLElement {
-  @state currentUser = { name: 'Kim', role: 'admin' };
-  @state items = [{ id: 1, text: 'Item 1' }, { id: 2, text: 'Item 2' }];
+Give components and loop items readable names for cross-scope access:
 
-  @innerHtml({ useShadow: true })
-  render() {
-    return `
-      <ul is="swc-for-of-children-ul" swc-value="{{items}}" as="item">
-        <li>
-          {{item.text}}
-          <!-- Access parent's currentUser.name directly in child template -->
-          <small>(by: {{currentUser.name}})</small>
-        </li>
-      </ul>
-    `;
-  }
-}
+```html
+<!-- as="t1" makes this component accessible as {{t1.count}} from children -->
+<t-test id="parent" as="t1">
+  <t-test2 as="t2" slot="content">
+    <div>
+      <p>T1 count: <strong>{{t1.count}}</strong></p>
+      <p>T2 count: <strong>{{t2.count}}</strong></p>
+    </div>
+  </t-test2>
+</t-test>
 ```
 
 ---
 
-## Shadow DOM + Slot Pattern
+## Shadow DOM + Slots
 
 ```typescript
 @elementDefine('card-layout')
@@ -609,26 +510,26 @@ class CardLayout extends HTMLElement {
   render() {
     return `
       <style>
-        :host { display: block; border: 1px solid #ccc; border-radius: 8px; }
-        .header { background: #f5f5f5; padding: 12px; font-weight: bold; }
-        .body { padding: 16px; }
+        :host { display: block; border: 1px solid #ddd; border-radius: 8px; overflow: hidden; }
+        .header { background: #f5f5f5; padding: 12px 16px; font-weight: 600; }
+        .body   { padding: 16px; }
+        .footer { padding: 12px 16px; border-top: 1px solid #eee; }
       </style>
       <div class="header">{{title}}</div>
-      <div class="body">
-        <slot></slot>
-        <slot name="footer"></slot>
-      </div>
+      <div class="body"><slot></slot></div>
+      <div class="footer"><slot name="footer"></slot></div>
     `;
   }
 }
 ```
 
 ```html
-<card-layout title="User Info">
-  <p>Name: Kim</p>
-  <p>Email: kim@example.com</p>
+<card-layout title="User Profile">
+  <p>Name: Alice</p>
+  <p>Email: alice@example.com</p>
   <div slot="footer">
     <button>Edit</button>
+    <button>Delete</button>
   </div>
 </card-layout>
 ```
@@ -637,74 +538,70 @@ class CardLayout extends HTMLElement {
 
 ## File Separation Pattern
 
-When splitting a component into its own file, use `export default (w: Window) => {...}` to inject `window`:
+When splitting components into separate files, use `export default (w: Window) => {...}` to inject `window`:
 
 ```typescript
-// MyComponent.ts
-import { elementDefine, innerHtml, state } from '@dooboostore/simple-web-component';
+// UserCard.ts
+import { elementDefine, innerHtml, state, attribute, addEventListener } from '@dooboostore/simple-web-component';
+import { Sim } from '@dooboostore/simple-boot/decorators/SimDecorator';
 
 export default (w: Window) => {
-  @elementDefine({ name: 'my-component', window: w })
-  class MyComponent extends HTMLElement {
-    @state name = '';
+  @Sim
+  @elementDefine({ name: 'user-card', window: w })
+  class UserCard extends HTMLElement {
+    @state @attribute name = 'Guest';
+    @state @attribute({ type: Number }) age = 0;
 
     @innerHtml({ useShadow: true })
     render() {
-      return `<p>Hello, {{name}}!</p>`;
+      return `
+        <div class="card">
+          <h2>{{name}}</h2>
+          <p>Age: {{age}}</p>
+          <button id="edit-btn">Edit</button>
+        </div>
+      `;
     }
+
+    @addEventListener({ type: 'click', query: '#edit-btn' })
+    onEdit() { console.log('editing', this.name); }
   }
-  return MyComponent;
+
+  return UserCard;
 };
 ```
 
 ```typescript
 // index.ts — inject window at the entry point
-import createMyComponent from './MyComponent';
+import createUserCard from './UserCard';
 
-const MyComponent = createMyComponent(window);
+const UserCard = createUserCard(window);
 ```
 
-> For browser-only SPAs, you can omit the `window` option entirely.  
-> `@elementDefine('my-component')` works fine — `buildEnv` falls back to the global `window` automatically.
+> For browser-only apps, `window` injection is optional.  
+> `@elementDefine('user-card')` works fine — SWC falls back to the global `window` automatically.
 
 ---
 
-## SPA Routing — Full Working Example
+## SPA Routing
 
-SWC provides two ways to bootstrap a SPA. Choose the one that fits your setup.
+SWC integrates with `@dooboostore/simple-boot` for DI-powered routing.
 
----
+### Option A — `<swc-app>` (HTML-first, zero JS bootstrap)
 
-### Option A — `<swc-app>` Custom Element (HTML-first, no JS bootstrap)
+Drop a single tag in your HTML. No `DOMContentLoaded` wiring needed.
 
-The simplest approach. Drop `<swc-app>` into your HTML and point it at a config function via `swc-get-application-config`. No manual `DOMContentLoaded` wiring needed.
-
-**`index.html`**
 ```html
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8" />
-  <title>SWC SPA</title>
-  <script type="module" src="./index.js"></script>
-</head>
-<body>
-  <!--
-    swc-get-application-config: a global function name that returns SwcAttributeConfigType.
-    SwcApp calls this function after the script is evaluated.
-  -->
-  <swc-app swc-get-application-config="applicationConfig(this)"></swc-app>
-</body>
-</html>
+<!-- index.html -->
+<swc-app swc-get-application-config="applicationConfig(this)"></swc-app>
 ```
 
-**`index.ts`**
 ```typescript
+// index.ts
 import 'reflect-metadata';
 import {
-  elementDefine, innerHtml, state, attribute,
-  query, addEventListener, onAfterConnected, onMutationSubscribe,
-  SwcApp, SwcAppInterface, SwcAttributeConfigType
+  elementDefine, innerHtml, state, query, addEventListener,
+  onMutationSubscribe, SwcApp, SwcAppInterface, SwcAttributeConfigType
 } from '@dooboostore/simple-web-component';
 import { SimpleApplication } from '@dooboostore/simple-boot/SimpleApplication';
 import { Sim } from '@dooboostore/simple-boot/decorators/SimDecorator';
@@ -715,24 +612,18 @@ import { RoutingDataSet } from '@dooboostore/simple-boot/route/RouterManager';
 import createMyComponent from './MyComponent';
 
 const w = window;
+const MyComponent = createMyComponent(w);
 
 // ─── Pages ───────────────────────────────────────────────────────────────────
 
-// MyComponent is defined in a separate file and receives `window` via factory
-const MyComponent = createMyComponent(w);
-
 @Sim
 @elementDefine({ name: 'my-component2', window: w })
 class MyComponent2 extends HTMLElement {
-  say() { console.log('hello MyComponent2'); }
+  say() { console.log('hello from MyComponent2'); }
 
   @innerHtml
   render() {
-    return `
-      <div style="padding: 10px; border: 1px solid #ccc;">
-        <h3>My Component2</h3>
-      </div>
-    `;
+    return `<div style="padding: 10px; border: 1px solid #ccc;"><h3>Component 2</h3></div>`;
   }
 }
 
@@ -742,7 +633,7 @@ class MyComponent2 extends HTMLElement {
 @Router({
   path: '/hello',
   route: {
-    '/good': MyComponent,
+    '/good':  MyComponent,
     '/good2': MyComponent2,
   }
 })
@@ -762,7 +653,7 @@ class MyRouter extends HTMLElement implements RouterAction.CanActivate {
 
   async canActivate(url: RoutingDataSet, data?: any): Promise<void> {
     if (data instanceof Node && !this.myRoute.contains(data)) {
-      this.myRoute.replaceChildren(data);
+      this.myRoute.replaceChildren(data);  // atomic, flicker-free swap
     }
   }
 }
@@ -774,14 +665,12 @@ class MyRouter extends HTMLElement implements RouterAction.CanActivate {
 @elementDefine({ name: 'root-router', window: w })
 class RootRouter extends HTMLDivElement implements RouterAction.CanActivate {
   @state route = '';
-  @state name = 'Root Name';
+  @state name = 'Root';
 
   constructor(
     private router: WebRouter,
     private sim: SimpleApplication
-  ) {
-    super();
-  }
+  ) { super(); }
 
   async canActivate(url: RoutingDataSet, data?: any): Promise<void> {
     this.route = url.intent.pathname;
@@ -791,27 +680,25 @@ class RootRouter extends HTMLDivElement implements RouterAction.CanActivate {
   }
 
   @addEventListener({ type: 'click', query: '#route-btn' })
-  onRouteBtnClick() {
-    this.name = 'Changed Root ' + new Date().getSeconds();
+  onRoute() {
+    this.name = 'Changed ' + new Date().getSeconds();
     this.router.go('/hello/good');
   }
 
-  // @onMutationSubscribe — fires when MutationObserver detects DOM changes
+  // React to DOM mutations (Shadow + Light)
   @onMutationSubscribe({ root: 'all' })
-  onDomChanged(mutations: MutationRecord[], observer: MutationObserver) {
-    console.log('DOM changed:', mutations);
+  onDomChanged(mutations: MutationRecord[]) {
+    console.log('DOM changed:', mutations.length, 'mutations');
   }
 
   @innerHtml({ useShadow: true })
   render() {
     return `
-      <style>
-        .container { padding: 10px; border: 1px solid #ccc; }
-      </style>
+      <style>.container { padding: 10px; border: 1px solid #ccc; }</style>
       <div class="container">
         <h3>Root Router</h3>
-        <p>Current Route: <strong>{{route}}</strong></p>
-        <p>Current name: <strong>{{name}}</strong></p>
+        <p>Route: <strong>{{route}}</strong></p>
+        <p>Name: <strong>{{name}}</strong></p>
         <button id="route-btn">Go to /hello/good</button>
         <slot></slot>
       </div>
@@ -819,99 +706,81 @@ class RootRouter extends HTMLDivElement implements RouterAction.CanActivate {
   }
 }
 
-// ─── Bootstrap (Option A) ────────────────────────────────────────────────────
-// Export a config factory function and expose it on window.
-// <swc-app swc-get-application-config="applicationConfig(this)"> calls this.
+// ─── Bootstrap ───────────────────────────────────────────────────────────────
 
+// Expose config factory on window — <swc-app> calls this via new Function()
 export const applicationConfig = (app: SwcAppInterface): SwcAttributeConfigType => ({
   rootRouter: RootRouter,
   path: '/hello/good',
   window: w,
 });
-
 (w as any).applicationConfig = applicationConfig;
 ```
 
-**`MyComponent.ts`** — separate file, receives `window` via factory
 ```typescript
+// MyComponent.ts — decoupled from global window
 import { elementDefine, innerHtml, state, attribute, onAfterConnected, addEventListener } from '@dooboostore/simple-web-component';
 import { Sim } from '@dooboostore/simple-boot/decorators/SimDecorator';
 import { Router as WebRouter } from '@dooboostore/core-web/routers/Router';
 
-// export default (w: Window) => {...} pattern
-// — keeps the file decoupled from the global window
 export default (w: Window) => {
   @Sim
   @elementDefine({ name: 'my-component', window: w })
   class MyComponent extends HTMLElement {
-    @state route = 'zz';
+    @state route = '';
     @state @attribute name?: string | null;
     @state showExtra = false;
     @state showRealIf = true;
 
-    constructor(private router: WebRouter) {
-      super();
-    }
+    constructor(private router: WebRouter) { super(); }
 
     @innerHtml({ useShadow: true })
     render() {
       return `
         <div style="padding: 10px; border: 1px solid #ccc;">
           <h3>My Component</h3>
-          <p>Route: <strong>{{route}}</strong></p>
           <p>Name: <strong>{{name}}</strong></p>
-          <button id="change-name-btn">Change Name</button>
+          <button id="change-btn">Change Name</button>
           <button id="toggle-extra-btn">Toggle IfChildren</button>
-          <button id="toggle-real-if-btn">Toggle Real If</button>
-
-          <!-- Inline event: this = button, $host = my-component -->
-          <button swc-on-click="console.log('host:', $host);">Log Host</button>
+          <button id="toggle-if-btn">Toggle Real If</button>
 
-          <!-- Two-way binding via inline event -->
+          <!-- Inline event: $host = my-component -->
           <input swc-on-input="$host.name = event.target.value" value="{{name}}" />
 
-          <h4>IfChildren (wrapper stays)</h4>
-          <div is="swc-if-children-div" swc-value="{{showExtra}}">
-            <p style="color: blue;">Extra content!</p>
+          <div is="swc-if-children-div" value="{{showExtra}}">
+            <p style="color: blue;">Extra content (wrapper stays in DOM)</p>
           </div>
 
-          <h4>Real If (removed from DOM)</h4>
-          <div is="swc-if-div" swc-value="{{showRealIf}}" style="background: yellow; padding: 5px;"
-            swc-on-click="console.log(this, $host, $firstHost, 'clicked')"
+          <div is="swc-if-div" value="{{showRealIf}}" style="background: yellow; padding: 5px;"
+            swc-on-click="console.log('clicked', $host, $firstHost)"
             swc-on-connected="console.log('connected', $host)">
-            <b>Toggle me to disappear from DOM.</b>
+            <b>Toggle me to disappear from DOM entirely.</b>
           </div>
         </div>
       `;
     }
 
     @onAfterConnected
-    init() { console.log('MyComponent connected', this.name); }
+    init() { console.log('MyComponent ready', this.name); }
 
-    @addEventListener({ type: 'click', query: '#change-name-btn' })
+    @addEventListener({ type: 'click', query: '#change-btn' })
     onChangeName() { this.name = 'Changed ' + new Date().getSeconds(); }
 
     @addEventListener({ type: 'click', query: '#toggle-extra-btn' })
     onToggleExtra() { this.showExtra = !this.showExtra; }
 
-    @addEventListener({ type: 'click', query: '#toggle-real-if-btn' })
-    onToggleRealIf() { this.showRealIf = !this.showRealIf; }
+    @addEventListener({ type: 'click', query: '#toggle-if-btn' })
+    onToggleIf() { this.showRealIf = !this.showRealIf; }
   }
 
   return MyComponent;
 };
 ```
 
----
-
 ### Option B — Programmatic Bootstrap (`Swc` class)
 
-Use this when you need full control over the bootstrap lifecycle.
-
 ```typescript
-import 'reflect-metadata';
 import { Swc } from '@dooboostore/simple-web-component';
-// ... same component definitions as Option A ...
 
 const swc = new Swc({ rootRouter: RootRouter, window: w });
 
@@ -921,246 +790,23 @@ window.addEventListener('DOMContentLoaded', async () => {
 });
 ```
 
----
-
 ### Routing Architecture
 
 ```
-RootRouter (extends HTMLDivElement)
-  └── implements RouterAction.CanActivate
-  └── replaceChildren(data)  ← routed component docks here (Light DOM)
-        │
-        └── MyRouter  (@Router path: '/hello')
-              └── implements RouterAction.CanActivate
-              └── #my-route.replaceChildren(data)
-                    ├── /good  → MyComponent
-                    └── /good2 → MyComponent2
-```
-
-Key points:
-- `canActivate(url, data)` receives the instantiated component node as `data`
-- `replaceChildren(data)` swaps the routed component atomically — no flicker
-- `RootRouter` can extend any built-in element (`HTMLDivElement`, `HTMLElement`, etc.)
-- The `@Router` decorator wires path matching; `canActivate` decides where to mount
-
----
-
-## Complete Component Example
-
-@Sim
-@elementDefine({ name: 'page-home', window: w })
-class PageHome extends HTMLElement {
-  @state count = 0;
-  @state todos: { text: string; done: boolean }[] = [
-    { text: 'Learn SWC', done: true },
-    { text: 'Build something', done: false },
-  ];
-
-  addTodo() {
-    this.todos = [...this.todos, { text: 'New todo ' + Date.now(), done: false }];
-  }
-
-  toggleTodo(index: number) {
-    this.todos[index].done = !this.todos[index].done;
-  }
-
-  @innerHtml({ useShadow: true })
-  render() {
-    return `
-      <style>
-        :host { display: block; padding: 20px; }
-        .done { text-decoration: line-through; color: #999; }
-        button { cursor: pointer; margin: 4px; padding: 6px 12px; }
-        li { margin: 6px 0; }
-      </style>
-
-      <h2>🏠 Home Page</h2>
-
-      <section>
-        <h3>Counter: {{count}}</h3>
-        <button swc-on-click="$host.count++;">+1</button>
-        <button swc-on-click="$host.count--;">-1</button>
-        <button swc-on-click="$host.count = 0;">Reset</button>
-      </section>
-
-      <hr/>
-
-      <section>
-        <h3>Todo List ({{todos.length}} items)</h3>
-        <button id="add-btn">Add Todo</button>
-        <ul is="swc-for-of-children-ul" swc-value="{{todos}}" as="todo" as-index="i">
-          <li class="{{todo.done ? 'done' : ''}}">
-            <input type="checkbox"
-              swc-on-change="$firstHost.toggleTodo({{i}});"
-              {{todo.done ? 'checked' : ''}}
-            />
-            {{todo.text}}
-          </li>
-        </ul>
-      </section>
-    `;
-  }
-
-  @addEventListener({ type: 'click', query: '#add-btn' })
-  onAddTodo() {
-    this.addTodo();
-  }
-
-  @onAfterConnected
-  init() {
-    console.log('PageHome connected');
-  }
-}
-
-// ─── Page: About ─────────────────────────────────────────────────────────────
-
-@Sim
-@elementDefine({ name: 'page-about', window: w })
-class PageAbout extends HTMLElement {
-  @state @attribute name = 'World';
-
-  @innerHtml({ useShadow: true })
-  render() {
-    return `
-      <style>
-        :host { display: block; padding: 20px; }
-        input { padding: 6px; margin-right: 8px; }
-      </style>
-
-      <h2>ℹ️ About Page</h2>
-      <p>Hello, <strong>{{name}}</strong>!</p>
-      <input
-        type="text"
-        placeholder="Enter your name"
-        value="{{name}}"
-        swc-on-input="$host.name = event.target.value"
-      />
-
-      <hr/>
-
-      <h3>Status Panel</h3>
-      <div is="swc-choose-children-div" swc-value="{{name}}">
-        <p is="swc-when-p" test="'World'">👋 Default greeting</p>
-        <p is="swc-when-p" test="'Admin'">🔑 Admin mode activated</p>
-        <p is="swc-other-p">😊 Hello, {{name}}!</p>
-      </div>
-    `;
-  }
-}
-
-// ─── Sub Router ──────────────────────────────────────────────────────────────
-
-@Sim
-@Router({
-  path: '/app',
-  route: {
-    '/home': PageHome,
-    '/about': PageAbout,
-  }
-})
-@elementDefine({ name: 'app-sub-router', window: w })
-class AppSubRouter extends HTMLElement implements RouterAction.CanActivate {
-  @query('#outlet') outlet!: HTMLElement;
-
-  @innerHtml({ useShadow: true })
-  render() {
-    return `
-      <style>
-        :host { display: block; }
-        nav { background: #f0f0f0; padding: 10px; }
-        nav a { margin-right: 12px; cursor: pointer; color: #1a73e8; text-decoration: none; }
-        nav a:hover { text-decoration: underline; }
-        #outlet { min-height: 200px; }
-      </style>
-      <nav>
-        <a id="nav-home">Home</a>
-        <a id="nav-about">About</a>
-      </nav>
-      <div id="outlet"></div>
-    `;
-  }
-
-  async canActivate(url: RoutingDataSet, data?: any): Promise<void> {
-    if (data instanceof Node && !this.outlet?.contains(data)) {
-      this.outlet?.replaceChildren(data);
-    }
-  }
-
-  @addEventListener({ type: 'click', query: '#nav-home', root: 'shadow' })
-  goHome() { (this as any)._sim?.routing('/app/home'); }
-
-  @addEventListener({ type: 'click', query: '#nav-about', root: 'shadow' })
-  goAbout() { (this as any)._sim?.routing('/app/about'); }
-}
-
-// ─── Root Router ─────────────────────────────────────────────────────────────
-
-@Sim
-@Router({ routers: [AppSubRouter] })
-@elementDefine({ name: 'root-router', window: w })
-class RootRouter extends HTMLElement implements RouterAction.CanActivate {
-  @state currentPath = '/';
-
-  constructor(
-    private router: WebRouter,
-    private sim: SimpleApplication
-  ) {
-    super();
-  }
-
-  async canActivate(url: RoutingDataSet, data?: any): Promise<void> {
-    this.currentPath = url.intent.pathname;
-    if (data instanceof Node && !this.contains(data)) {
-      this.replaceChildren(data);
-    }
-  }
-
-  @innerHtml({ useShadow: true })
-  render() {
-    return `
-      <style>
-        :host { display: block; font-family: sans-serif; max-width: 800px; margin: 0 auto; }
-        header {
-          background: #1a73e8; color: white;
-          padding: 16px 20px; display: flex;
-          align-items: center; justify-content: space-between;
-        }
-        header h1 { margin: 0; font-size: 1.2rem; }
-        .path { font-size: 0.85rem; opacity: 0.8; }
-        main { padding: 0; }
-      </style>
-      <header>
-        <h1>SWC SPA Demo</h1>
-        <span class="path">{{currentPath}}</span>
-      </header>
-      <main><slot></slot></main>
-    `;
-  }
-}
-
-// ─── Bootstrap ───────────────────────────────────────────────────────────────
-
-const swc = new Swc({ rootRouter: RootRouter, window: w });
-
-window.addEventListener('DOMContentLoaded', async () => {
-  document.body.appendChild(swc.run());
-  await swc.routing('/app/home');
-});
+<swc-app>  or  swc.run()
+  └── RootRouter (extends HTMLDivElement)
+        └── canActivate → replaceChildren(data)   ← Light DOM slot
+              │
+              └── MyRouter  (@Router path: '/hello')
+                    └── canActivate → #my-route.replaceChildren(data)
+                          ├── /good  → MyComponent
+                          └── /good2 → MyComponent2
 ```
 
-```html
-<!-- index.html -->
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8" />
-  <title>SWC SPA Demo</title>
-</head>
-<body>
-  <!-- root-router is appended by swc.run() -->
-</body>
-</html>
-```
+- `canActivate(url, data)` — `data` is the instantiated component node
+- `replaceChildren(data)` — atomic DOM swap, zero flicker
+- `RootRouter` can extend any HTML element (`HTMLDivElement`, `HTMLElement`, etc.)
+- Shadow DOM `<slot>` + Light DOM `replaceChildren` = instant page transitions
 
 ---
 
@@ -1171,7 +817,7 @@ import 'reflect-metadata';
 import {
   elementDefine, innerHtml, state, attribute,
   query, addEventListener, onAfterConnected,
-  emitCustomEvent, onAttributeChanged
+  emitCustomEvent, onAttributeChanged, onMutationSubscribe
 } from '@dooboostore/simple-web-component';
 
 @elementDefine({ name: 'user-profile', autoRemoveEventListeners: true })
@@ -1182,40 +828,46 @@ class UserProfile extends HTMLElement {
   @state history: string[] = [];
 
   @query('input[name="name"]') nameInput!: HTMLInputElement;
+  @query('input[name="age"]')  ageInput!: HTMLInputElement;
 
   @emitCustomEvent({ type: 'profile-save', bubbles: true })
   save() {
     return { name: this.name, age: this.age };
+    // → CustomEvent('profile-save', { detail: { name, age } })
   }
 
   @innerHtml({ useShadow: true })
   render() {
     return `
       <style>
-        :host { display: block; font-family: sans-serif; }
+        :host { display: block; font-family: sans-serif; max-width: 400px; }
         .card { padding: 16px; border: 1px solid #ddd; border-radius: 8px; }
-        button { cursor: pointer; margin: 4px; padding: 6px 12px; }
-        input { padding: 6px; margin: 4px; }
+        .edit { padding: 16px; background: #f9f9f9; border-radius: 8px; margin-top: 8px; }
+        input { padding: 6px 10px; margin: 4px 0; width: 100%; box-sizing: border-box; }
+        button { cursor: pointer; padding: 6px 14px; margin: 4px 2px; }
+        .history { font-size: 0.85rem; color: #666; }
       </style>
 
       <div class="card">
-        <h2>{{name}} (age: {{age}})</h2>
-        <button id="edit-btn">Edit</button>
+        <h2>{{name}} <small style="color:#999">(age {{age}})</small></h2>
+        <button id="edit-btn">✏️ Edit</button>
       </div>
 
-      <div is="swc-if-children-div" swc-value="{{isEditing}}">
-        <div class="card">
-          <input name="name" type="text" value="{{name}}" placeholder="Name" />
-          <input name="age" type="number" value="{{age}}" placeholder="Age" />
-          <button id="save-btn">Save</button>
-          <button id="cancel-btn">Cancel</button>
+      <div is="swc-if-children-div" value="{{isEditing}}">
+        <div class="edit">
+          <input name="name" type="text"   value="{{name}}" placeholder="Name" />
+          <input name="age"  type="number" value="{{age}}"  placeholder="Age"  />
+          <button id="save-btn">💾 Save</button>
+          <button id="cancel-btn">✕ Cancel</button>
         </div>
       </div>
 
-      <h4>Change History ({{history.length}})</h4>
-      <ul is="swc-for-of-children-ul" swc-value="{{history}}" as="log">
-        <li>{{log}}</li>
-      </ul>
+      <div is="swc-if-div" value="{{history.length > 0}}">
+        <h4>Change History</h4>
+        <ul is="swc-for-of-ul" value="{{history}}" as-item="log" as-index="i">
+          <li class="history">#{{i + 1}}: {{log}}</li>
+        </ul>
+      </div>
     `;
   }
 
@@ -1228,8 +880,9 @@ class UserProfile extends HTMLElement {
   @addEventListener({ type: 'click', query: '#save-btn' })
   onSave() {
     this.name = this.nameInput?.value ?? this.name;
+    this.age  = Number(this.ageInput?.value) || this.age;
     this.isEditing = false;
-    this.save(); // dispatches CustomEvent automatically
+    this.save();
   }
 
   @onAttributeChanged('name')
@@ -1239,15 +892,18 @@ class UserProfile extends HTMLElement {
     }
   }
 
-  @onAfterConnected
-  init() {
-    console.log('UserProfile ready');
+  @onMutationSubscribe({ root: 'shadow' })
+  onShadowChanged(mutations: MutationRecord[]) {
+    console.log('Shadow DOM updated:', mutations.length, 'changes');
   }
+
+  @onAfterConnected
+  init() { console.log('UserProfile ready'); }
 }
 ```
 
 ```html
-<user-profile name="Kim" age="30"></user-profile>
+<user-profile name="Alice" age="28"></user-profile>
 
 <script>
   document.querySelector('user-profile').addEventListener('profile-save', (e) => {