@dooboostore/simple-web-component 1.0.50 → 1.0.52

package/README.md

@@ -10,6 +10,8 @@
 
 ## 🎯 Core Features
 
+> **No arguments → no parentheses.** Every decorator that can run without arguments is used bare (`@query`, `@innerHtml`, `@eventClick`, `@swcAppRouteGo`, ...). The empty-call form `@x()` is a type error; pass arguments only when you have them (`@innerHtml('.wrap')`, `@eventClick({ once: true })`).
+
 ### 1. **@elementDefine** - Component Registration
 Register Web Components with automatic lifecycle management and DI support.
 
@@ -22,6 +24,22 @@ class MyComponent extends HTMLElement {
 }
 ```
 
+**`@elementDefine(name, options?)` options:** `window`, `extends` (customized built-in, e.g. `'body'`), `useShadow` (`true | 'open' | 'closed'`), `observedAttributes`, `customElementRegistry`.
+`window` may be another window than the one running the code (an iframe's, or a server-side DOM window) — the class then extends that window's `HTMLElement` (`class X extends w.HTMLElement`).
+
+**Inheritance:** decorators on a base class apply to its subclasses — lifecycle hooks, events, observers, timers, message/route subscriptions, `@changedAttribute`, `@query`, `@state` …
+- hooks on both run parent first, then child
+- a subclass's own decorators never leak into the base class or into sibling subclasses
+- a subclass of a class that is itself `@elementDefine`d runs each lifecycle once (not once per level)
+
+```typescript
+class BasePage extends HTMLElement {
+  @onInitialize init(@inject(AuthService.SYMBOL) auth: AuthService) { this.auth = auth; }
+  @onDisconnected cleanup() { /* … */ }
+}
+@elementDefine('my-page') class MyPage extends BasePage {}   // init / cleanup run for <my-page>
+```
+
 ### 2. **Dependency Injection (@onInitialize)**
 Inject services into Web Components using the `@onInitialize` decorator.
 
@@ -64,8 +82,8 @@ Replace child nodes with new content.
 
 ```typescript
 @replaceChildrenLight
-replaceChildren(node: Node) {
-  return node;
+renderNode() {
+  return this.buildNode(); // Node, Node[] or HTML string
 }
 ```
 ### 3.5 **Slot Management with @applySlot**
@@ -76,7 +94,7 @@ Manage dynamic content insertion into named slots using slot decorators. Slots a
 @elementDefine('content-manager')
 class ContentManager extends HTMLElement {
   // Method: Replace children in slot with HTML
-  @addEventListener('.update-btn', 'click')
+  @event('.update-btn', 'click')
   @replaceChildrenHtmlSlot('main-content')
   updateContent() {
     return '<div>Updated content here</div>';
@@ -95,7 +113,7 @@ class ContentManager extends HTMLElement {
   }
 
   // Method: Clear slot content
-  @addEventListener('.clear-btn', 'click')
+  @event('.clear-btn', 'click')
   @clearSlot('main-content')
   clearContent() {
     return true;
@@ -166,7 +184,7 @@ class CounterApp extends HTMLElement {
   @state('isActive')
   isActive: boolean = false;
 
-  @addEventListener('button', 'click')
+  @event('button', 'click')
   increment() {
     this.count++;  // Triggers automatic DOM update
   }
@@ -179,7 +197,7 @@ class CounterApp extends HTMLElement {
         <!--[html @message@ ]-->
         
         <!-- Text directive: render as text -->
-        <!--[text Count: @count@ ]-->
+        <!--[text 'Count: ' + @count@ ]-->
         
         <!-- Attribute binding with a:: prefix -->
         <div a::title="'Count is'+@count@"></div>
@@ -227,7 +245,7 @@ State values accessed in templates via `@stateName@` syntax are read-only. You c
 
 ```typescript
 // ✅ CORRECT - Update state from method
-@addEventListener('button', 'click')
+@event('button', 'click')
 increment() {
   this.count++;  // Direct property assignment in code
 }
@@ -249,7 +267,7 @@ class UserProfile extends HTMLElement {
   @state('isEditing')
   isEditing = false;
 
-  @addEventListener('.edit-btn', 'click')
+  @event('.edit-btn', 'click')
   toggleEdit() {
     this.isEditing = !this.isEditing;
   }
@@ -276,19 +294,19 @@ class UserProfile extends HTMLElement {
 
 ### 4. **Event Handling**
 
-#### @addEventListener
+#### @event
 Attach event listeners to elements with optional filter support.
 
 ```typescript
-@addEventListener('#submit-btn', 'click')
+@event('#submit-btn', 'click')
 onSubmit(event: Event) {
   console.log('Submitted');
 }
 
 // Filter events - only process matching events
-@addEventListener('button', 'click', {
-  filter: (event, helper) => {
-    return event.target?.id === 'critical-button';
+@event('button', 'click', {
+  filter: (event, meta) => {
+    return (event.target as HTMLElement)?.id === 'critical-button';
   }
 })
 onCriticalClick(event: Event) {
@@ -296,27 +314,31 @@ onCriticalClick(event: Event) {
 }
 ```
 
-**@addEventListener Decorator Variants:**
-- `addEventListener(selector, type, options)` - Full form
-- `event(selector, type, options)` - Short alias
-- `addEventListenerThis(type, options)` - Listen on $this element
-- `addEventListenerAppHost(type, options)` - Listen on $appHost
-- `addEventListenerWindow(type, options)` - Listen on window
-- `addEventListenerDocument(type, options)` - Listen on document
-- `addEventListenerDelegate(selector, type, options)` - Event delegation
-- `eventDelegate(selector, type, options)` - Short alias
-- `addEventListenerDelegateLight(selector, type, options)` - Delegate in light DOM
-- `eventDelegateLight(selector, type, options)` - Short alias
-- `addEventListenerDelegateShadow(selector, type, options)` - Delegate in shadow DOM
-- `eventDelegateShadow(selector, type, options)` - Short alias
-- `addEventListenerDelegateAll(selector, type, options)` - Delegate in all DOM
-- `eventDelegateAll(selector, type, options)` - Short alias
-- `addEventListenerLight(selector, type, options)` / `eventLight(...)` - Bind (non-delegated) in light DOM
-- `addEventListenerShadow(selector, type, options)` / `eventShadow(...)` - Bind (non-delegated) in shadow DOM
-- `addEventListenerAll(selector, type, options)` / `eventAll(...)` - Bind (non-delegated) in both light & shadow DOM
-- `addEventListenerMutation(selector, type, options)` / `eventMutation(...)` - Delegate via `MutationObserver` instead of event bubbling (useful for non-bubbling events like `focus`/`blur`); `*Light`/`*Shadow`/`*All` variants also available
-
-**Event-Type-Specific Aliases (eventClick, eventInputThis, ...):**
+**@event Decorator Variants:**
+- `event(selector, type, options)` - Full form
+- `event(type, options)` (no selector) - Listen on $this element. With the default `root: 'auto'` it binds to the shadowRoot when the element has one (clicks inside the shadow bubble to it, but events dispatched on the element itself — `el.click()`, a parent's `el.dispatchEvent(...)` — never go down into it); use `{ root: 'light' }` to bind the element itself, `{ root: 'all' }` for both
+- `eventAppHost(type, options)` - Listen on $appHost
+- `eventWindow(type, options)` - Listen on window
+- `eventDocument(type, options)` - Listen on document
+- `eventDelegate(selector, type, options)` - Event delegation
+- `eventDelegateLight(selector, type, options)` - Delegate in light DOM
+- `eventDelegateShadow(selector, type, options)` - Delegate in shadow DOM
+- `eventDelegateAll(selector, type, options)` - Delegate in all DOM
+- `eventLight(selector, type, options)` - Bind (non-delegated) in light DOM
+- `eventShadow(selector, type, options)` - Bind (non-delegated) in shadow DOM
+- `eventAll(selector, type, options)` - Bind (non-delegated) in both light & shadow DOM
+- `eventMutation(selector, type, options)` - Delegate via `MutationObserver` instead of event bubbling (useful for non-bubbling events like `focus`/`blur`); `*Light`/`*Shadow`/`*All` variants also available
+
+**@event Options:**
+- `capture` / `once` / `passive` - standard listener options
+- `preventDefault` / `stopPropagation` / `stopImmediatePropagation` - applied before the handler runs
+- `filter: (event, { currentThis, helper }) => boolean | Promise<boolean>` - skip the handler when it returns false
+- `before: (event, meta, args) => any` - runs after `filter`; its return value is injectable with `@eventBeforeReturn`
+- `finally: (event, meta, { args, result, error }) => any` - always runs after the handler
+- `debounceTime` / `throttleTime` (ms) / `distinctUntilChanged` - rate-limit the event stream
+- `removeListener: (target, options) => void` - cleanup callback on disconnect
+
+**Event-Type-Specific Aliases (eventClick, eventInputDelegateShadow, ...):**
 
 Beyond the generic `event(selector, type, options)` form, every scope/delegate variant above is also pre-bound to ~59 common DOM event types, so you don't have to repeat the type string:
 
@@ -324,16 +346,22 @@ Beyond the generic `event(selector, type, options)` form, every scope/delegate v
 @eventClick('.logo')
 onLogoClick() { ... }
 
+// No selector → the element itself (same as @event('click')); bare form, no parens
+@eventClick
+onClick(event: MouseEvent) { ... }
+
+// Options without a selector → still the element itself
+@eventKeydown({ filter: (e, meta) => !meta.currentThis.isLocked })
+onKeydown(event: KeyboardEvent) { ... }
+
 // Same as: @eventDelegateLight('.item', 'click')
 @eventClickDelegateLight('.item')
 onItemClick(event: Event) { ... }
-
-// Same as: @addEventListenerThis('keydown')
-@eventKeydownThis()
-onKeydown(event: KeyboardEvent) { ... }
 ```
 
-Naming pattern: `event` + `PascalCase(type)` + scope suffix (`''`(base) / `DelegateLight` / `DelegateShadow` / `DelegateAll` / `Delegate` / `MutationLight` / `MutationShadow` / `MutationAll` / `Mutation` / `Light` / `Shadow` / `All` / `This` / `AppHost` / `Window` / `Document`) — e.g. `eventClick`, `eventClickDelegateShadow`, `eventDblclickThis`, `eventPointerdownDelegateAll`, `eventKeydownWindow`.
+Naming pattern: `event` + `PascalCase(type)` + scope suffix (`''`(base) / `DelegateLight` / `DelegateShadow` / `DelegateAll` / `Delegate` / `MutationLight` / `MutationShadow` / `MutationAll` / `Mutation` / `Light` / `Shadow` / `All` / `AppHost` / `Window` / `Document`) — e.g. `eventClick`, `eventClickDelegateShadow`, `eventDblclick`, `eventPointerdownDelegateAll`, `eventKeydownWindow`.
+
+The base alias (`eventClick`) takes an optional selector: bare `@eventClick` or `@eventClick({...})` listens on the element itself, `@eventClick('.btn', {...})` on the selector (there is no separate `…This` variant). The `AppHost`/`Window`/`Document` variants take no selector — only options — so they are used bare (`@eventClickWindow`) or with options. Never use empty parens. The `Delegate*`/`Light`/`Shadow`/`All` variants require a `selector`.
 
 Covered event types include mouse (`click`, `dblclick`, `mousedown`, `mouseup`, `mousemove`, `mouseover`, `mouseout`, `mouseenter`, `mouseleave`, `contextmenu`, `wheel`), keyboard (`keydown`, `keyup`, `keypress`), form (`input`, `change`, `submit`, `reset`, `invalid`, `select`), focus (`focus`, `blur`, `focusin`, `focusout`), drag & drop (`dragstart`, `drag`, `dragend`, `dragenter`, `dragleave`, `dragover`, `drop`), touch (`touchstart`, `touchmove`, `touchend`, `touchcancel`), pointer (`pointerdown`, `pointerup`, `pointermove`, `pointerover`, `pointerout`, `pointerenter`, `pointerleave`, `pointercancel`), clipboard (`copy`, `cut`, `paste`), animation/transition (`animationstart/end/iteration/cancel`, `transitionstart/end/cancel/run`), and misc (`scroll`, `resize`, `load`, `error`, `toggle`).
 
@@ -341,27 +369,27 @@ These aliases are generated in `addEventListener.ts` from a small internal `make
 
 #### Order-Independent Parameter Decorators (@eventObject, @matchedElement, @hostSet, @helperHostSet, @helperSet)
 
-`@addEventListener`-bound handlers normally receive fixed positional arguments (`(event, legacyHelper1, legacyHelper2)`). If you'd rather not memorize that order, decorate individual parameters instead — order and position no longer matter, and any parameter left undecorated in a method that uses none of these decorators still gets the legacy positional arguments (fully backward-compatible):
+`@event`-bound handlers normally receive fixed positional arguments (`(event, legacyHelper1, legacyHelper2)`). If you'd rather not memorize that order, decorate individual parameters instead — order and position no longer matter, and any parameter left undecorated in a method that uses none of these decorators still gets the legacy positional arguments (fully backward-compatible):
 
 ```typescript
-import { addEventListener, eventObject, matchedElement, hostSet, helperHostSet, helperSet } from '@dooboostore/simple-web-component';
+import { event, eventObject, matchedElement, hostSet, helperHostSet, helperSet } from '@dooboostore/simple-web-component';
 
 @elementDefine('product-list')
 class ProductList extends HTMLElement {
   // Order can be anything you like
-  @addEventListenerDelegateLight('.item', 'click')
+  @eventDelegateLight('.item', 'click')
   onItemClick(@matchedElement $item: Element, @eventObject event: Event) {
     console.log('clicked item:', $item, event);
   }
 
   // Only need the host tree info? Just ask for @hostSet.
-  @eventClickThis()
+  @eventClick
   onHostClick(@hostSet hs: HostSet) {
     console.log(hs.$appHost, hs.$hosts);
   }
 
   // Need DOM helpers ($q, $qa, ...) too? Use @helperHostSet (superset of @hostSet) or @helperSet (helpers only).
-  @eventClickThis()
+  @eventClick
   onHostClickFull(@helperHostSet full: HelperHostSet, @helperSet helpers: HelperSet) { ... }
 }
 ```
@@ -372,19 +400,24 @@ class ProductList extends HTMLElement {
 - `@helperHostSet` - `@hostSet` + DOM/window helpers (`$d`, `$w`, `$q`, `$qa`, `$qi`) + `$this`
 - `@helperSet` - DOM/window helpers only (`$d`, `$w`, `$q`, `$qa`, `$qi`), no host-tree info
 
+`$w`/`$d` (and the `helper` passed to every decorator's `filter`/`before`/`finally`) come from the element's window, resolved the same way everywhere: its own `@elementDefine({ window })` → the nearest ancestor SWC host's → the global `window`. Route subscribers (`@subscribeSwcAppRouteChange`) and app messages use the SwcApp's runtime `window` instead (the per-request window under SSR).
+
 The same mechanism (and the same 5 decorators, plus two more) also applies to:
 - **`@onInitialize`/`@onConnectedBefore`/`@onConnectedAfter`/... lifecycle methods** — can freely mix `@hostSet`/`@helperHostSet`/`@helperSet` with `@inject(...)` on the same method.
-- **`@subscribeSwcAppRouteChangeWhileConnected`** — add `@routerEvent` to receive the `RouterEventType` regardless of position.
-- **`@subscribeSwcAppMessageWhileConnected`** — add `@appMessage` to receive the `SwcAppMessage` regardless of position.
+- **`@subscribeSwcAppRouteChange`** — add `@swcAppRouterEvent` to receive the `RouterEventType` regardless of position.
+- **`@subscribeSwcAppMessage`** — add `@appMessage` to receive the `SwcAppMessage` regardless of position.
+- **`before` hook results** — `@eventBeforeReturn`, `@routeChangeBeforeReturn`, `@appMessageBeforeReturn`, `@changedAttributeBeforeReturn`, `@mutationObserverBeforeReturn`, `@resizeObserverBeforeReturn`, `@intersectionObserverBeforeReturn`, `@eventMediaBeforeReturn`, `@setIntervalBeforeReturn`, `@setTimeoutBeforeReturn` inject the value returned by that decorator's `before` option.
+
+Note: once any parameter of a method is decorated, only decorated parameters receive values (the legacy positional arguments are no longer passed).
 
 ```typescript
 @onConnectedAfter
 onconstructor(@inject(UserService.SYMBOL) userService: UserService, @hostSet hs: HostSet) { ... }
 
-@subscribeSwcAppRouteChangeWhileConnected()
-onRouteChanged(@helperSet helpers: HelperSet, @routerEvent re: RouterEventType) { ... }
+@subscribeSwcAppRouteChange
+onRouteChanged(@helperSet helpers: HelperSet, @swcAppRouterEvent re: RouterEventType) { ... }
 
-@subscribeSwcAppMessageWhileConnected
+@subscribeSwcAppMessage
 onMessage(@hostSet hs: HostSet, @appMessage msg: SwcAppMessage) { ... }
 ```
 
@@ -402,13 +435,16 @@ async onLogin() {
 **@emitCustomEvent Decorator Variants:**
 - `emitCustomEvent(target, type, options)` - Full form
 - `emit(target, type, options)` - Short alias
-- `emitCustomEventThis(type, options)` - Emit from $this element
+- `emitCustomEvent(type, options)` - Without a selector it emits from the element itself (`emitAppHost` / `emitWindow` / `emitDocument` take `(type, options)`; `emitLight` / `emitShadow` / `emitAll` take `(selector, type, options)`)
+- Options: `bubbles`, `composed`, `cancelable`, `filter`, `valueKey`, `attributeName`, `root`
+- `valueKey`: if the returned object has that key, only its value becomes `detail` (otherwise the whole return value); default key `EMIT_CUSTOM_EVENT_METADATA_KEY`. The method still returns the full value, so several emit/publish decorators can share one return object
 
 #### @publishSwcAppMessage
 Publish messages through the message bus when method completes.
 
 ```typescript
-@publishSwcAppMessage()
+// No arguments needed → bare form
+@publishSwcAppMessage
 async onLogin() {
   const user = await this.authService.login();
   return user;  // Published as message with data: user
@@ -422,13 +458,13 @@ updateProfile() {
 ```
 
 **@publishSwcAppMessage Decorator Variants:**
-- `publishSwcAppMessage()` - Publish without message type
+- `publishSwcAppMessage` - Bare decorator, publish without message type
 - `publishSwcAppMessage(messageType)` - Publish with specific message type
 - `publishSwcAppMessage(messageType, { valueKey: 'customKey' })` - Publish with custom value extraction
 - `publishSwcAppMessage({ messageType: 'type', valueKey: 'customKey' })` - Publish with options object
-- `publish()` - Short alias
-- `publish(messageType)` - Short alias with message type
-- `publish(messageType, options)` - Short alias with options
+- `publishMessage` - Short alias
+- `publishMessage(messageType)` - Short alias with message type
+- `publishMessage(messageType, options)` - Short alias with options
 
 **Using valueKey for Multiple Decorators:**
 
@@ -443,38 +479,40 @@ handleMultipleEvents() {
 }
 ```
 
-#### @emitCustomEventThis
-Emit events from a method with custom event name mapping.
+#### Emitting from the element itself
+`@emitCustomEvent(type, options)` without a selector emits from $this. Pass `attributeName` so a parent can attach a handler through that attribute
+(there is no default attribute name; set it explicitly). The attribute script gets `event` and `$data` (= `event.detail`).
 
 ```typescript
-@emitCustomEventThis('navigate', { attributeName: 'on-navigate' })
+@emitCustomEvent('navigate', { attributeName: 'on-emit-navigate' })
 onNavClick(e: any) {
   return { path: e.target.dataset.path };
 }
+// Parent: <app-header on-emit-navigate="$host.onHeaderNavigate(event, $data)"></app-header>
 ```
 
-#### @addEventListenerThis
-Listen to events on the component element itself (`$this` selector).
+#### Listening on the element itself
+`@event(type, options)` without a selector (or a typed alias without one, e.g. bare `@eventClick`) listens on the component element itself (`$this`). If the element has a shadow root, the default `root: 'auto'` binds to the shadowRoot — clicks inside the shadow are received, events dispatched on the element itself are not. Use `@event('click', { root: 'light' })` (or `'all'`) to also catch those.
 
 ```typescript
-@addEventListenerThis('click')
+@event('click')
 onHostClick(event: Event) {
   console.log('Host element clicked');
 }
 ```
 
-#### @addEventListenerAppHost
+#### @eventAppHost
 Listen to events on the app root host element (`$appHost` selector). Enables selective event handling with filters.
 
 ```typescript
 // Listen to all user-action events from $appHost
-@addEventListenerAppHost('user-action')
+@eventAppHost('user-action')
 onUserAction(e: CustomEvent) {
   console.log('User action:', e.detail);
 }
 
 // Filter specific events - loose coupling pattern
-@addEventListenerAppHost('user-action', {
+@eventAppHost('user-action', {
   filter: (event, helper) => event.detail?.type === 'login'
 })
 onUserLogin(e: CustomEvent) {
@@ -482,7 +520,7 @@ onUserLogin(e: CustomEvent) {
 }
 
 // Different component filtering same event differently
-@addEventListenerAppHost('user-action', {
+@eventAppHost('user-action', {
   filter: (event, helper) => event.detail?.type === 'logout'
 })
 onUserLogout(e: CustomEvent) {
@@ -493,7 +531,7 @@ onUserLogout(e: CustomEvent) {
 ### 5. **DOM Querying**
 
 #### @query
-Query single element (Light DOM by default).
+Query a single element. The default `root: 'auto'` searches the shadow root if one exists, otherwise the light DOM.
 
 ```typescript
 @query('#form-input')
@@ -514,91 +552,86 @@ textInputs?: HTMLInputElement[];
 listItems?: HTMLLIElement[];
 ```
 
-#### @queryThis
-Query the component element itself.  == this
+#### Special selectors, `pick`, and shorthands
+Special selectors: `$this`, `$host`, `$parentHost`, `$appHost`, `$firstHost`, `$lastHost`, `$firstAppHost`, `$lastAppHost`, `$hosts`, `$appHosts`, `$window`, `$document`. A function selector `(currentThis, helper) => Element | Element[] | NodeList | null` is also accepted (no `root` option).
 
 ```typescript
-@queryThis
-self?: HTMLElement;
+@query                       // bare = the component itself (same as @query('$this')); @queryAll → [itself]
+self?: HTMLElement;          // no arguments → no parentheses: @query() / @queryAll() are type errors
 
-printTag() {
-  console.log(this.self?.tagName);  // CUSTOM-CARD
-}
+@query('.item', { pick: 'last' })   // 'first' (default) | 'last' | number → single; 'all' | 'even' | 'odd' → array
+lastItem?: HTMLElement;
+
+@(queryIn('shadow', 'even')('.row'))  // root + pick factory — the chained call needs the outer parentheses
+evenRows?: HTMLElement[];
 ```
 
+- Shorthands: `queryLight` / `queryShadow` / `queryAllRoots` (single), `queryAllLight` / `queryAllShadow` / `queryAllAll` (arrays)
+- `filter: (el, { currentThis, helper }) => boolean` narrows the matches
+- Assigning `null` / `undefined` / `[]` to a `@query` field removes the matched elements from the DOM
+
 ### 6. **Attribute Binding**
 
-#### @attribute (Field Decorator)
-Bind HTML attributes to properties with automatic read/write synchronization.
+#### @attribute (Field / Method Decorator)
+Works on both fields and methods; behavior depends on where it is applied.
+- **Field**: getter/setter that reads/writes the element attribute (`type` converts to Number/Boolean)
+- **Method**: applies the return value to the attribute. `null` **removes** it, `undefined` does nothing
 
-Intelligently distinguishes between attribute names and CSS selectors:
+**One string = attribute name on `$this`**, **two strings = (selector, attribute name)**.
 
 ```typescript
 @elementDefine('product-card')
 class ProductCard extends HTMLElement {
-  // Attribute name on $this (auto-detected)
+  // Field — product-id on $this
   @attribute('product-id')
   productId: string;
 
-  // Attribute name on selector
+  // Field — data-id on the selector target
   @attribute('#user', 'data-id')
   userId: string;
 
-  // Bare decorator (uses field name as attribute)
+  // Field — bare (field name = attribute name)
   @attribute
   title: string;
 
-  @onInitialize
-  onconstructor() {
-    if (this.productId) {
-      this.loadProduct(this.productId);
-    }
-  }
-}
-```
-
-#### @setAttribute (Method Decorator)
-Set element attributes from method return values.
-
-```typescript
-@elementDefine('status-updater')
-class StatusUpdater extends HTMLElement {
-  // Set attribute on $this
-  @setAttribute('data-status')
-  updateStatus() {
-    return this.isActive ? 'active' : 'inactive';
+  // Method — return value goes to nav[data-active] (null → removed)
+  @attribute('nav', 'data-active')
+  updateNav() {
+    return this.section; // 'releases' | null
   }
 
-  // Set attribute on selector
-  @setAttribute('#user', 'data-name')
+  // Method — data-name on $this
+  @attribute('data-name')
   setUserName() {
     return this.userName;
   }
-
-  // Bare decorator (uses method name as attribute)
-  @setAttribute
-  setValue() {
-    return this.computedValue;
-  }
 }
 ```
 
-**Usage Patterns:**
-- `@attribute('attr-name')` - Attribute name on $this (auto-detected)
-- `@attribute('#selector', 'attr-name')` - Attribute name on selector
-- `@attribute('attr-name', options)` - Attribute name on $this with options
-- `@attribute('#selector', 'attr-name', options)` - Attribute name on selector with options
-- `@attribute` - Bare decorator (uses field name as attribute on $this)
+**Patterns:**
+- `@attribute` - `$this`, name = field/method name
+- `@attribute('attr-name', options?)` - attr-name on `$this`
+- `@attribute('selector', 'attr-name', options?)` - selector target (`nav`, `#user`, `.card`, `$appHost`, ...)
+- `@attribute((this, helper) => el, 'attr-name')` - function selector
+- `@attribute('selector', 'attr-name', { valueKey: 'k' })` - (method) set only `k` from the returned object
+- Options: `type`, `filter`, `valueKey`, `root`. Shorthands: `attrAppHost`, `attrLight`, `attrShadow`, `attrAll` (for $this just give the name: `@attribute('name')`)
+- A field getter evaluates a `{{= expr }}` attribute value (see "Attribute Expressions")
+
+#### @removeAttribute (Method Decorator)
+Always removes the attribute when the method runs. The return value passes through unchanged,
+so it is safe on subscriber handlers that must not return a value (e.g. route changes).
 
-**@setAttribute Patterns:**
-- `@setAttribute('attr-name')` - Set attribute on $this
-- `@setAttribute('#selector', 'attr-name')` - Set attribute on selector
-- `@setAttribute('attr-name', options)` - Set attribute on $this with options
-- `@setAttribute('#selector', 'attr-name', options)` - Set attribute on selector with options
-- `@setAttribute` - Bare decorator (uses method name as attribute on $this)
+```typescript
+// Runs before the other route handlers — reset the nav highlight
+@subscribeSwcAppRouteChange({ order: -1 })
+@removeAttribute('nav', 'href')
+handleNavReset() {
+  return undefined; // keep the chain going
+}
+```
 
 #### @changedAttribute (Method Decorator)
-Listen for attribute changes on the component this element.
+Listen for attribute changes on the component itself (`attributeChangedCallback`). Handler arguments: `(newValue, oldValue, name, helperHostSet)`; `newValue` is converted by `type` (and a `{{= expr }}` value is evaluated first).
 
 ```typescript
 @elementDefine('reactive-component')
@@ -614,80 +647,59 @@ class ReactiveComponent extends HTMLElement {
     console.log(`Status is now: ${newValue}`);
   }
 
-  // Listen to any attribute change
-  @changedAttribute()
-  onAnyAttributeChanged(newValue: any, oldValue: any) {
-    console.log('An attribute changed');
-  }
+  // Bare (or no name) → the method name is used as the attribute name
+  @changedAttribute
+  status(newValue: string) { }
 }
 ```
 
 **@changedAttribute Options:**
 - `attributeName` - Attribute name to listen for (optional, defaults to method name)
 - `type` - Type converter: `Number`, `Boolean`, or `String`
-- `while` - Execution condition: `'connected'` (only while connected to DOM)
+- `while` - `'connected'`: skip changes while disconnected, and run once on connect with the current value (if set)
+- `filter` / `before` / `finally` - same hook pattern as `@event` (`before` result → `@changedAttributeBeforeReturn`)
 
 ### 6.5 **Property Binding**
 
-#### @property (Field Decorator)
-Bind element properties to component fields with automatic read/write synchronization.
-
-```typescript
-@elementDefine('input-wrapper')
-class InputWrapper extends HTMLElement {
-  // Property on $this (auto-detected)
-  @property('value')
-  inputValue: string;
+#### @property (Field / Method Decorator)
+Works on both fields and methods.
+- **Field**: getter/setter that reads/writes a property of the target element
+  - Bare `@property` (= `$this` + same name) stays a plain field with no getter/setter and is only registered as an **SSR hydration target**
+- **Method**: assigns the return value to the target element's property (`undefined` is ignored)
 
-  // Property on selector
-  @property('#submit-btn', 'disabled')
-  isSubmitDisabled: boolean;
-
-  // Bare decorator (uses field name as property)
-  @property
-  checked: boolean;
-}
-```
-
-#### @setProperty (Method Decorator)
-Set element properties from method return values.
+Unlike `@attribute`, **the first string is always a selector**. A property on the element itself is just the field, so a name-only form would be meaningless.
 
 ```typescript
 @elementDefine('form-handler')
 class FormHandler extends HTMLElement {
-  // Set property on $this
-  @setProperty('disabled')
-  disableForm() {
-    return !this.isValid();
-  }
+  // Field — bare: own field (SSR hydration target)
+  @property
+  declare rows: Row[];
+
+  // Field — property of the selector target
+  @property('#chart', 'data')
+  chartData: number[];
 
-  // Set property on selector
-  @setProperty('#submit-btn', 'disabled')
+  // Method — return value goes to #submit-btn.disabled
+  @property('#submit-btn', 'disabled')
   updateSubmitState() {
     return this.hasErrors;
   }
 
-  // Bare decorator (uses method name as property)
-  @setProperty
-  setValue() {
-    return this.computedValue;
+  // Method — same-named property on the selector target (input.value)
+  @property('input')
+  value() {
+    return this.initialValue;
   }
 }
 ```
 
-**Usage Patterns:**
-- `@property('propertyName')` - Property on $this
-- `@property('#selector', 'propertyName')` - Property on selector
-- `@property('propertyName', options)` - Property on $this with options
-- `@property('#selector', 'propertyName', options)` - Property on selector with options
-- `@property` - Bare decorator (uses field name as property on $this)
-
-**@setProperty Patterns:**
-- `@setProperty('propertyName')` - Set property on $this
-- `@setProperty('#selector', 'propertyName')` - Set property on selector
-- `@setProperty('propertyName', options)` - Set property on $this with options
-- `@setProperty('#selector', 'propertyName', options)` - Set property on selector with options
-- `@setProperty` - Bare decorator (uses method name as property on $this)
+**Patterns:**
+- `@property` - `$this`, name = field/method name
+- `@property('selector', options?)` - same-named property on the target
+- `@property('selector', 'propertyName', options?)` - propertyName on the target
+- `@property((this, helper) => el, 'propertyName')` - function selector
+- To call a method on the target, use `@callProperty('selector', 'methodName')` (an array return value is spread as arguments; `callPropertyLight` / `callPropertyShadow` / `callPropertyAll` also exist)
 
 ### 6.6 **DOM Observers (@mutationObserver, @resizeObserver, @intersectionObserver)**
 
@@ -714,8 +726,10 @@ class ListObserver extends HTMLElement {
 ```
 
 **Callback signature:**
-- `matchedEls: HTMLElement[]` - Elements matching the selector (1st arg)
-- `mutations: MutationRecord[]` - Original mutation records (2nd arg)
+- `matchedEls: HTMLElement[]` - Elements matching the selector (1st arg). For the element itself (bare `@mutationObserver` / `$this`) it is just `[element]` — the added/removed nodes are in `mutations`
+- `mutations: MutationRecord[]` - Mutation records for this method's own targets (2nd arg)
+
+Bare `@mutationObserver` (no arguments) watches the element's whole subtree (`childList` + `subtree`) and is attached **before** the first render, so it sees the render itself. Pass options to narrow it (e.g. `@mutationObserver({ childList: true })` = direct children only).
 - `observer: MutationObserver` - The observer instance (3rd arg)
 
 **How delegate works:**
@@ -746,7 +760,7 @@ Detect element size changes and react automatically.
 @elementDefine('chart-widget')
 class ChartWidget extends HTMLElement {
   // Re-render when component size changes (selector defaults to $this)
-  @resizeObserverLight()
+  @resizeObserverLight
   onResize(matchedEls: HTMLElement[], entries: ResizeObserverEntry[], observer: ResizeObserver) {
     this.redraw(entries[0]?.contentRect);
   }
@@ -838,20 +852,20 @@ Surgically add, replace, or remove nodes in the DOM with fine-grained control.
 ```typescript
 @elementDefine('content-updater')
 class ContentUpdater extends HTMLElement {
-  @addEventListener('button', 'click')
-  @replaceChildren()
+  @event('button', 'click')
+  @replaceChildren
   updateContent() {
     return `<div>New content</div>`;
   }
 
-  @addEventListener('.append-btn', 'click')
-  @beforeEndNode()
+  @event('.append-btn', 'click')
+  @insertBeforeEnd
   appendContent() {
     return `<p>Appended content</p>`;
   }
 
-  @addEventListener('.prepend-btn', 'click')
-  @afterBegin()
+  @event('.prepend-btn', 'click')
+  @insertAfterBegin
   prependContent() {
     return `<p>Prepended content</p>`;
   }
@@ -870,15 +884,14 @@ class ContentUpdater extends HTMLElement {
 ```
 
 **@applyNode Decorator Variants:**
-- `replaceChildren()` - Replace all children
-- `replaceChildrenLight()` - Replace children in light DOM
-- `beforeEnd()` - Append to end
-- `beforeEndLight()` - Append to light DOM end
-- `afterBegin()` - Prepend to beginning
-- `afterBeginLight()` - Prepend to light DOM beginning
-- `innerHtml()` - Set innerHTML
-- `innerHtmlLight()` - Set innerHTML in light DOM
-- `innerText()` - Set innerText
+- `applyNode(selector?, options?)` / `apply` / `node` - Full form (selector defaults to `$this`). Position: with no options at all it is `replaceChildren`; once you pass an options object without `position` it is `beforeEnd` (append) — bare `@applyAppHost` appends too. Pass `position` explicitly when it matters; `applyAppHost` / `applyLight` / `applyShadow` / `applyAll`
+- `@replaceChildren` / `@replaceChildrenLight` - Replace all children
+- `@insertBeforeEnd` / `@insertBeforeEndLight` / `@insertBeforeEndShadow` - Append to end
+- `@insertAfterBegin` / `@insertAfterBeginLight` - Prepend to beginning
+- `@innerHtml` / `@innerHtmlLight` / `@innerHtmlShadow` - Set innerHTML
+- `@innerText` / `@innerTextLight` / `@innerTextShadow` - Set innerText
+- `@clearChildrenNode` / `@clearChildrenLight` - Remove all children
+- Options: `position`, `root`, `filter`, `fallback`, `valueKey`. Ready-made `filter` helpers: `skipIfSameTagPresent`, `skipIfExists(selector)`, `skipIfEmpty`, `applyIfChanged` (e.g. `@innerHtmlLight({ filter: skipIfExists('my-page') })`)
 
 **Position Options:**
 ```typescript
@@ -891,7 +904,8 @@ export type ApplyNodePosition =
   | 'replaceChildren'  // Replace children
   | 'innerHtml'        // Set innerHTML
   | 'innerText'        // Set innerText
-  | 'remove';          // Remove element
+  | 'remove'           // Remove element
+  | 'clearChildren';   // Remove all children
 ```
 
 ### 8. **Style & Class Management**
@@ -904,8 +918,8 @@ class StyledComponent extends HTMLElement {
   @state('isActive')
   isActive = false;
 
-  @addEventListener('button', 'click')
-  @updateStyle()
+  @event('button', 'click')
+  @updateStyle
   toggleStyle() {
     return {
       color: this.isActive ? 'green' : 'red',
@@ -913,9 +927,9 @@ class StyledComponent extends HTMLElement {
     };
   }
 
-  @addEventListener('.toggle-btn', 'click')
-  @updateClass()
-  toggleClass() {
+  @event('.toggle-btn', 'click')
+  @updateClass
+  toggleState() {
     return {
       'active': this.isActive,
       'disabled': !this.isActive
@@ -934,17 +948,18 @@ class StyledComponent extends HTMLElement {
 }
 ```
 
-**@applyStyle Variants:**
-- `setStyleThis()` - Clear and set styles
-- `updateStyleThis()` - Update/merge styles
-- `removeStyleThis()` - Remove specific styles
+**@applyStyle Variants:** (each takes `(selector?, options?)`; bare form targets `$this`)
+- `setStyle` - Clear and set styles
+- `updateStyle` - Update/merge styles
+- `removeStyle` - Remove specific styles
+- `applyStyle(selector, action?)` / `style` - action `'set' | 'update' | 'remove'` (default `'update'`); `styleAppHost` / `styleLight` / `styleShadow` / `styleAll` (for $this use bare `@setStyle` / `@updateStyle` / `@removeStyle`)
 
-**@applyClass Variants:**
-- `setClassThis()` - Replace all classes
-- `updateClassThis()` - Toggle classes
-- `addClassThis()` - Add classes
-- `removeClassThis()` - Remove classes
-- `toggleClassThis()` - Toggle classes
+**@applyClass Variants:** (each takes `(selector?, classMapOrOptions?, options?)`; bare form targets `$this`)
+- `setClass` - Replace all classes
+- `updateClass` - Toggle classes by a `{ className: boolean }` map
+- `addClass` / `removeClass` / `toggleClass`
+- `applyClass(selector, action?)` / `cls` - action `'set' | 'update' | 'add' | 'remove' | 'toggle'` (default `'update'`); `clsAppHost` / `clsLight` / `clsShadow` / `clsAll` (for $this use bare `@setClass` / `@updateClass` / `@addClass` / `@removeClass` / `@toggleClass`)
+- Note: for the class decorators, an options object in the 2nd position must contain `root` (e.g. `{ root: 'auto', valueKey: 'k' }`); an object without `root` is read as a class map
 
 ### 8.5 **Lifecycle Hooks**
 
@@ -961,17 +976,18 @@ class MyComponent extends HTMLElement {
 
   @onConnectedBefore({ order: 0 })
   beforeConnected() {
-    // Called before element connects to DOM
+    // Called on connect, before rendering
   }
 
   @onConnectedAfter({ order: 1 })
   afterConnected() {
-    // Called after element connects to DOM
+    // Called on connect, after rendering and observer setup
   }
 
-  @onConnected
-  onConnected() {
-    // Called when element enters DOM
+  @onConnectedBody
+  render() {
+    // Called when element enters DOM — renders the returned HTML (variants: @onConnectedBodyShadow / @onConnectedBodyLight)
+    return `<div>...</div>`;
   }
 
   @onDisconnectedBefore
@@ -979,7 +995,7 @@ class MyComponent extends HTMLElement {
     // Called before element disconnects from DOM
   }
 
-  @onDisconnected
+  @onDisconnected // alias of @onDisconnectedAfter
   onDisconnected() {
     // Called when element leaves DOM
   }
@@ -989,15 +1005,15 @@ class MyComponent extends HTMLElement {
     // Called before element is adopted into new document
   }
 
-  @onAdopted
+  @onAdopted // alias of @onAdoptedAfter
   onAdopted() {
     // Called when element is adopted into new document
   }
 
   @onConnectedSwcApp({ order: 0 })
   onSwcAppConnected() {
-    // Called after SwcApp.connect() completes
-    // Full DI support available through hostSet
+    // Called when the element registers with a connected SwcApp host
+    // (deferred until SwcApp.connect() if the app is not connected yet)
   }
 
   @onConnectedCompleted({ order: 0 })
@@ -1007,17 +1023,16 @@ class MyComponent extends HTMLElement {
 }
 ```
 
-**Lifecycle Execution Order:**
-- `@onInitialize` - Component construction
-- `@onConnectedBefore` - Before DOM connection
-- `@onConnectedAfter` - After DOM connection
-- `@onConnected` - DOM connection (with HTML rendering)
-- `@onConnectedSwcApp` - After SwcApp initialization
-- `@onConnectedCompleted` - All connected hooks done
-- `@onDisconnectedBefore` - Before DOM disconnection
-- `@onDisconnected` - DOM disconnection
-- `@onAdoptedBefore` - Before document adoption
-- `@onAdopted` - Document adoption
+**Lifecycle Execution Order (connectedCallback):**
+1. `@onInitialize` - once, on first init (DI via `@inject` parameters)
+2. `@onConnectedSwcApp` - the element registers with its app host (deferred until `connect()` if needed)
+3. `@onConnectedBefore` - before rendering
+4. `@onConnectedBody` (`Shadow` / `Light`) - render the returned HTML/Node (skipped for SSR-rendered elements)
+5. Observers / timers / listeners are wired up
+6. `@onConnectedAfter` - after rendering
+7. `@onConnectedCompleted` - always runs last (in a `finally` block), then `trigger: 'connectedDone'` replays fire
+
+Disconnect: `@onDisconnectedBefore` → cleanup → `@onDisconnected` (`@onDisconnectedAfter`). Adopt: `@onAdoptedBefore` → `@onAdopted` (`@onAdoptedAfter`).
 
 **Order Parameter:**
 All lifecycle decorators support `order?: number` for controlling execution sequence:
@@ -1029,17 +1044,19 @@ onFirst() { }
 onSecond() { }
 ```
 
-### 8.6 **Timers (@setInterval, @setTimeout)**
+### 8.6 **Timers (@setInterval, @setTimeout, @requestAnimationFrame)**
 
-Declaratively run a method on a repeating interval or after a one-time delay, tied to the component's connected lifecycle. Both are pure metadata-collecting decorators — they never touch the method itself (no `descriptor.value` wrapping) — so they compose safely with any other decorator stacked on the same method, regardless of declaration order. All the actual scheduling/cleanup is handled by `SetIntervalLifeCycler`/`SetTimeoutLifeCycler` (`ElementDefineLifeCycler` implementations, same plugin pattern as the observers above):
+Declaratively schedule work tied to the component. Every timer the decorator starts is cleared automatically on disconnect. There are two modes (`type` option):
 
-- Starts automatically when the component connects.
-- Automatically `clearInterval`/`clearTimeout`s when the component disconnects — no manual cleanup needed.
+- `type: 'returnValue'` (**default**) - nothing starts automatically. When you call the method, its return value (a function, or the function under `valueKey`) becomes the repeating/delayed callback, called with `(id: number)`. The original return value passes through.
+- `type: 'onConnected'` - starts on connect and calls the decorated method itself on every tick/fire.
 
 ```typescript
 @elementDefine('live-clock')
 class LiveClock extends HTMLElement {
+  // Auto-start on connect
   @setInterval(1000, {
+    type: 'onConnected',
     parameter: (set) => [Date.now()],
     created: (set, id) => console.log('interval started, timer id:', id)
   })
@@ -1047,94 +1064,94 @@ class LiveClock extends HTMLElement {
     this.textContent = new Date(now).toLocaleTimeString();
   }
 
-  // No options - called with no arguments, once per second
-  @setInterval(1000)
-  onTick() {
-    console.log('tick');
-  }
-
   // Fires once, 3 seconds after connect
-  @setTimeout(3000)
+  @setTimeout(3000, { type: 'onConnected' })
   onceAfter3s() {
     console.log('3 seconds have passed');
   }
+
+  // Default 'returnValue': starts when you call startPolling()
+  @setInterval(900)
+  startPolling() {
+    return (id: number) => console.log('interval', id, 'ticked');
+  }
 }
 ```
 
 **`@setInterval(interval, options?)` / `@setTimeout(delay, options?)`:**
 - `interval` / `delay` - milliseconds. `setInterval` repeats; `setTimeout` fires once.
-- `parameter?: (set: HelperHostSet) => any[]` - computes the arguments passed to the method on each tick/fire. Omitted → method is called with no arguments.
-- `created?: (set: HelperHostSet, id: number) => void` - fires once, right after the timer is armed, with the real `setInterval`/`setTimeout` return value. For logging/debugging only — cleanup is still handled automatically, this is not a manual-clear hook.
-- `valueKey?: symbol | string` - same convention as `@applyAttribute`'s `valueKey` (see "Multiple Decorators with Shared Return Value" below): if the method's return value is an object and this key's value is a function, that function is called on every tick/fire — but note the callback signature is just `(id: number)`, not `(set, id)` like `created`.
+- `type` - `'returnValue'` (default) | `'onConnected'`
+- `parameter?: (set: HelperHostSet) => any[]` - (`onConnected`) arguments for each tick/fire; omitted → no arguments.
+- `created?: (set: HelperHostSet, id: number) => void` - called once right after the timer is armed. For logging only; cleanup is automatic.
+- `filter` / `before` / `finally` - (`onConnected`) per-tick hooks; `before` result → `@setIntervalBeforeReturn` / `@setTimeoutBeforeReturn`.
+- `valueKey?: symbol | string` - which key of the returned object holds the callback function (defaults to `SET_INTERVAL_METADATA_KEY` / `SET_TIMEOUT_METADATA_KEY`).
+
+**`@requestAnimationFrame(options?)`** (bare form also works) - same two modes. The frame callback is `(timestamp, prevValue) => any`: return `undefined`/`null` to stop the loop, anything else is passed as `prevValue` to the next frame. Options: `type`, `created`, `valueKey`.
 
 ```typescript
-@setInterval(900, { valueKey: 'onTick' })
-poll() {
-  return {
-    onTick: (id: number) => console.log('interval', id, 'ticked'),
-  };
+@requestAnimationFrame
+animate() {
+  return (ts: number, prev = 0) => (prev < 100 ? prev + 1 : null); // stops at 100
 }
 ```
 
-**Why no wrapping is needed:** unlike `@applyAttribute`/`@setAttribute` (which must wrap the method because it can be called by arbitrary code — event handlers, other decorators, etc.), the timer's own `LifeCycler` is the one calling `inst[propertyKey](...)` every tick/fire — it already has the return value in hand at that call site, so it can read `valueKey` off of it without ever needing to intercept the method.
+### 8.7 **@around (AOP) and @eventMedia**
 
-> `@requestAnimationFrame` is not implemented yet.
+`@around` wraps a method (`before(helper, args)` → new args, `after(helper, result)` → new result, `finally(helper, { args, result, error })`) or a field (`get(helper, stored)`, `set(helper, incoming)`). Async hooks are supported when the method is async.
 
-### 9. **Structural Directives**
+```typescript
+@around({ before: (h, args: [string]) => [args[0].trim()], after: (h, r: string) => r + '!' })
+greet(name: string) { return `hi ${name}`; }
 
-Structural Directives allow declarative conditional rendering, list iteration, async handling, and routing with automatic attribute substitution and dynamic expressions.
+@around({ set: (h, v: string) => v?.trim() })
+label: string = '';
+```
 
-#### 8.0 **Expression Syntax - Dynamic Evaluation**
+`@eventMedia(query, eventType, options?)` / `@eventMediaChange(query, options?)` subscribe to `window.matchMedia(query)` on connect and unsubscribe on disconnect. Handler arguments: `(event: MediaQueryListEvent, helperHostSet)`. Options: `filter`, `before`, `finally`.
 
-SWC supports two types of expression syntax for dynamic value evaluation:
+```typescript
+@eventMediaChange('(max-width: 600px)')
+onMobile(e: MediaQueryListEvent) { this.compact = e.matches; }
+```
+
+### 9. **Attribute Expressions (`{{= }}`)**
 
-**`{{ }} - Standard Expression Evaluation**
-- Used for boolean conditions and value comparisons
-- Syntax: `{{ expression }}`
-- Example: `{{ $value === 'pending' }}`, `{{ $host.isLoggedIn }}`
-- Context variables: `$value`, `$item`, `$index`, `$host`, `$parentHost`, `$appHost`, etc.
+An attribute value of the form `{{= expression }}` is evaluated as JavaScript instead of being used as a string:
 
-**`{{= }} - Function Call & Return Expression**
-- Evaluates JavaScript expressions and returns result
-- Syntax: `{{= functionCall() }}`  or `{{= computedValue }}`
-- Automatically executes functions and captures return values
-- Example: `{{= $item.name }}`, `{{= $parentHost.getData() }}`, `{{= formatDate($item.date) }}`
-- Used in attributes for dynamic substitution
-- Result is converted to string for DOM attributes
+```html
+<product-detail product-id="{{= $host.selectedId }}"></product-detail>
+```
 
-**Context Variables Available in All Directives:**
-- `$value` - the value passed to the template
-- `$host` - the current Web Component instance
-- `$parentHost` - parent component
-- `$appHost` - root application component
-- `$item` - current item (in SwcLoop)
-- `$index` - current index (in SwcLoop)
-- Helper functions - utility methods from `SwcUtils.getHelperAndHostSet()`
+- Evaluated when the value is read by an `@attribute` field getter and before it is passed to `@changedAttribute` handlers
+- `this` is the element that owns the attribute; the helper/host variables are in scope: `$this`, `$host`, `$parentHost`, `$hosts`, `$firstHost`, `$lastHost`, `$appHost`, `$appHosts`, `$d`, `$w`, `$q`, `$qa`, `$qi`
+- The result keeps its JavaScript type (then `type` conversion applies); on error the raw string is used
+
+Template bindings inside `@onConnectedBody*` HTML (`@state@`, `<!--[html ]-->`, `<!--[text ]-->`, `a::`, `e::`, and `p::` for DOM properties) are described in the `@state` section.
 
 ---
 
-### 9. **Component Communication - Message Bus**
+### 10. **Component Communication - Message Bus**
 
 SWC provides a powerful message bus system for inter-component communication through SwcApp. Components can publish and subscribe to typed messages while connected.
 
-#### @subscribeSwcAppMessageWhileConnected
+#### @subscribeSwcAppMessage
 Subscribe to messages while component is connected to DOM.
 
 ```typescript
 @elementDefine('notification-panel')
 class NotificationPanel extends HTMLElement {
-  @subscribeSwcAppMessageWhileConnected
+  @subscribeSwcAppMessage
   onAnyMessage(message: SwcAppMessage) {
     console.log('Received message:', message);
   }
 
-  @subscribeSwcAppMessageWhileConnected('user-login')
+  @subscribeSwcAppMessage('user-login')
   onUserLogin(message: SwcAppMessage<{ username: string }>) {
     console.log(`Welcome ${message.data?.username}`);
   }
 
-  @subscribeSwcAppMessageWhileConnected('user-login', {
-    filter: (msg) => msg.data?.username === 'admin'
+  @subscribeSwcAppMessage('user-login', {
+    filter: (msg, currentThis) => msg.data?.username === 'admin'
   })
   onAdminLogin(message: SwcAppMessage) {
     console.log('Admin logged in!');
@@ -1142,13 +1159,16 @@ class NotificationPanel extends HTMLElement {
 }
 ```
 
+**@subscribeSwcAppMessage Options:** `filter(message, currentThis)`, `before(message, currentThis)` (result → `@appMessageBeforeReturn`), `finally(message, currentThis, { args, result, error })`, `subject`, `trigger` (see "Message Replay"). Every matching subscriber runs (fire-and-forget); return values do not stop other subscribers.
+
 #### @publishSwcAppMessage
 Publish a message from a method's return value.
 
 ```typescript
 @elementDefine('login-form')
 class LoginForm extends HTMLElement {
-  @publishSwcAppMessage()
+  // No arguments needed → bare form
+  @publishSwcAppMessage
   async onSubmit() {
     const user = await this.authService.login(
       this.username,
@@ -1166,11 +1186,11 @@ class LoginForm extends HTMLElement {
 ```
 
 **@publishSwcAppMessage Decorator Variants:**
-- `publishSwcAppMessage()` - Publish without message type
+- `publishSwcAppMessage` - Publish without message type (bare)
 - `publishSwcAppMessage(messageType)` - Publish with specific message type
 - `publishSwcAppMessage(messageType, { valueKey: 'customKey' })` - Publish with custom value extraction
 - `publishSwcAppMessage({ messageType: 'type', valueKey: 'customKey' })` - Publish with options object
-- `publishMessage()` - Short alias
+- `publishMessage` - Short alias
 - `publishMessage(messageType)` - Short alias with message type
 - `publishMessage(messageType, options)` - Short alias with options
 
@@ -1202,7 +1222,7 @@ type SwcAppMessage<T = any> = {
 - ✅ **Filter support** - use custom filter functions to handle specific conditions
 - ✅ **Auto-publishing** - return value automatically becomes message payload
 - ✅ **Async support** - works with async methods (promises)
-- ✅ **Centralized** - all messages routed through SwcApp host
+- ✅ **Centralized** - all messages routed through the nearest SwcApp host (`$appHost`)
 - ✅ **Decoupled** - components don't need to know about each other
 
 **Usage Example:**
@@ -1220,7 +1240,7 @@ class ProductList extends HTMLElement {
 // Subscriber component
 @elementDefine('product-detail')
 class ProductDetail extends HTMLElement {
-  @subscribeSwcAppMessageWhileConnected('product-selected')
+  @subscribeSwcAppMessage('product-selected')
   onProductSelected(message: SwcAppMessage<Product>) {
     this.displayProduct(message.data);
   }
@@ -1236,6 +1256,8 @@ SWC provides a flexible Mixin-based architecture for creating SwcApp elements th
 #### Available SwcApp Variants
 
 ```typescript
+// SwcApp, SwcAppBody, ... are createElement helpers: SwcAppBody(w, data?) creates the element.
+// defineSwcApp, defineSwcAppBody, ... register the custom element.
 import {
   SwcApp,           // swc-app (HTMLElement)
   SwcAppBody,       // swc-app-body (HTMLBodyElement, is="body")
@@ -1292,7 +1314,7 @@ w.document.addEventListener('DOMContentLoaded', async () => {
       path: '/',
       routeType: 'path',
       container: container,
-      onStartedLazyDefineComponent: [yourComponentFactory1, yourComponentFactor2],
+      onStartedLazyDefineComponent: [yourComponentFactory1, yourComponentFactory2],
       window: w,
       onEngineStarted: () => {
         console.log('🚀 Application started successfully');
@@ -1302,6 +1324,10 @@ w.document.addEventListener('DOMContentLoaded', async () => {
 });
 ```
 
+**Main `connect()` options (`SwcAttributeConfigType`):** `routeType` (`'path' | 'hash' | 'element'`), `path` (first URL), `container` (DI container symbol), `window`, `onStartedLazyDefineComponent` (component factories), `onEngineStarted(sp, app)`, `onConnected` / `onDisconnected`, `onConnectedChildBefore` / `onConnectedChildAfter`, `onDisconnectedChildBefore` / `onDisconnectedChildAfter`, `onChildrenConnectedDone`, `onChildrenRouteChanged`, `messageReplayBufferSize`, `ssr`, `otherInstanceSim`.
+
+App host methods: `routing(path)`, `back()`, `forward()`, `reload()`, `publishMessage(message)`, `observeMessage(...)`, `connectedElements()`.
+
 #### Factory Pattern - Component Registration
 
 ```typescript
@@ -1341,7 +1367,7 @@ appElement.connect({
 });
 ```
 
-#### 12. **Routing with @subscribeSwcAppRouteChangeWhileConnected**
+#### 12. **Routing with @subscribeSwcAppRouteChange**
 
 SWC provides declarative routing with automatic path matching, order-based execution, and optional propagation control.
 
@@ -1350,26 +1376,26 @@ SWC provides declarative routing with automatic path matching, order-based execu
 ```typescript
 @elementDefine('root-router')
 class RootRouter extends HTMLElement {
-  @subscribeSwcAppRouteChangeWhileConnected(['', '/'], { order: 0 })
+  @subscribeSwcAppRouteChange(['', '/'], { order: 0 })
   @innerHtmlLight
   handleHome(routerPathSet: RouterEventType) {
     return `<landing-page/>`;
   }
 
-  @subscribeSwcAppRouteChangeWhileConnected(['/products'], { order: 1 })
+  @subscribeSwcAppRouteChange(['/products'], { order: 1 })
   @innerHtmlLight
   handleProducts(routerPathSet: RouterEventType) {
     return `<products-list/>`;
   }
 
-  @subscribeSwcAppRouteChangeWhileConnected(['/product/{id}'], { order: 2 })
+  @subscribeSwcAppRouteChange(['/product/{id}'], { order: 2 })
   @innerHtmlLight
   handleProductDetail(routerPathSet: RouterEventType) {
     const { id } = routerPathSet.pathData;
     return `<product-detail product-id="${id}"/>`;
   }
 
-  @subscribeSwcAppRouteChangeWhileConnected(['/{tail:.*}'], { order: 999 })
+  @subscribeSwcAppRouteChange(['/{tail:.*}'], { order: 999 })
   @innerHtmlLight
   handle404(routerPathSet: RouterEventType) {
     return `<not-found-page/>`;
@@ -1380,48 +1406,138 @@ class RootRouter extends HTMLElement {
 #### Route Handler Features
 
 **1. Path Matching**
-- **No path pattern** (omit path): `@subscribeSwcAppRouteChangeWhileConnected({ order: -1 })` - matches all routes
-- **Exact match**: `['', '/']` - matches home route only
-- **Prefix match**: `['/products']` - matches `/products` and `/products/...`
-- **Dynamic segments**: `['/product/{id}']` - captures `id` parameter
-- **Wildcard**: `['/{tail:.*}']` - matches any remaining path (use for 404)
+- **No path pattern** (omit path): `@subscribeSwcAppRouteChange({ order: -1 })` - matches all routes
+- Patterns are matched against the **whole** path (anchored regex); a string, an array (first match wins), or a function `(currentThis) => string | string[]`
+- **Exact match**: `['', '/']` - matches home route only; `['/products']` matches `/products` only
+- **Sub paths**: `['/products/{tail:.*}']` - use a regex segment to match `/products/...`
+- **Dynamic segments**: `['/product/{id}']` - captures `id` (`[^/]+`); custom regex: `{slug:[a-z0-9-]+}`
+- **Wildcard**: `['/{tail:.*}']` - matches any path (use for 404)
 
 **2. Order-Based Execution**
-Routes are executed in order of `order` value (lowest first). First matching route with a return value stops propagation:
+Handlers of one element run in `order` (lowest first, default 0). The first matching handler that returns a value stops the rest of **that element's** chain:
 
 ```typescript
-@subscribeSwcAppRouteChangeWhileConnected(['', '/'], { order: 0 })  // Checked first
-@subscribeSwcAppRouteChangeWhileConnected(['/admin'], { order: 1 })  // Checked second
-@subscribeSwcAppRouteChangeWhileConnected(['/{tail:.*}'], { order: 999 })  // Checked last (404)
+@subscribeSwcAppRouteChange(['', '/'], { order: 0 })  // Checked first
+@subscribeSwcAppRouteChange(['/admin'], { order: 1 })  // Checked second
+@subscribeSwcAppRouteChange(['/{tail:.*}'], { order: 999 })  // Checked last (404)
 ```
 
 **3. Propagation Control**
-- **Return a value** (HTML string) → Stops propagation to next handlers
-- **Return undefined/null** → Continues to next handler
+- **Return a value** (anything other than `undefined`/`null`, after `valueKey` extraction) → stops this element's remaining handlers
+- **Return `undefined`/`null`** → continues to the next handler
 
 ```typescript
 // This handler stops propagation (returns HTML)
-@subscribeSwcAppRouteChangeWhileConnected(['/admin'], { order: 1 })
+@subscribeSwcAppRouteChange(['/admin'], { order: 1 })
 @innerHtmlLight
 handleAdmin(routerPathSet: RouterEventType) {
   return `<admin-panel/>`; // ✅ Stops here
 }
 
 // This handler continues propagation (no return value)
-@subscribeSwcAppRouteChangeWhileConnected({ order: -1 })
+@subscribeSwcAppRouteChange({ order: -1 })
 onRouteChange(routerPathSet: RouterEventType) {
   console.log('Route changed:', routerPathSet.path);
   // No return value → continues to next handler
 }
 ```
 
+**4. When to run: `on`** (default `'match'` — the behavior above)
+
+| `on` | Runs when |
+|---|---|
+| `'match'` | the path matches (every route change) |
+| `'enter'` | it didn't match before and matches now (also the replay when the element connects) |
+| `'update'` | it keeps matching but the path or query changed |
+| `'leave'` | it matched before and doesn't now — only for elements that stay connected (a page that gets replaced should clean up in `onDisconnected`) |
+| `'beforeLeave'` | before leaving this route; return `false` (or `Promise<false>`) to cancel the navigation |
+
+A bare `@subscribeSwcAppRouteChange` (no path) matches every route: with `'match'` it runs on every change, `'update'` on every URL change, `'enter'` once.
+
+```typescript
+@subscribeSwcAppRouteChange('/releases/{releaseSeq}/tasks/{taskSeq}', { on: 'update' })
+@innerHtml('.card')
+swapCard(@swcAppRoutePathVariable('taskSeq') taskSeq: string) { ... }   // same page, only the card changes
+
+@subscribeSwcAppRouteChange('/edit/{id}', { on: 'beforeLeave' })
+confirmLeave() { return this.dirty ? confirm('Discard your changes?') : true; }
+```
+
+`beforeLeave` covers `router.go(...)` and the browser back/forward buttons. Back/forward have already changed the history when the guard runs, so a cancel restores the previous URL with `pushState`. Calling `pushState`/`replaceState` directly and closing the tab (`beforeunload`) are not covered. The handler receives the route being left with `to` (the target `RouteData`).
+
+**5. Route parameter decorators**
+
+No prefix means *first*; `First`/`Last` pick the first/last value when a key repeats; plural forms return every value.
+
+| Query (`?tag=a&tag=b`) | Value | Path (`/a/{id}/b/{id}` ← `/a/1/b/2`) | Value |
+|---|---|---|---|
+| `@swcAppRouteQueryParam('tag')` | `'a'` (`null` if absent) | `@swcAppRoutePathVariable('id')` | `'1'` |
+| `@swcAppRouteFirstQueryParam('tag')` | `'a'` | `@swcAppRouteFirstPathVariable('id')` | `'1'` |
+| `@swcAppRouteLastQueryParam('tag')` | `'b'` | `@swcAppRouteLastPathVariable('id')` | `'2'` |
+| `@swcAppRouteQueryParams('tag')` | `['a','b']` | `@swcAppRoutePathVariables('id')` | `['1','2']` |
+| `@swcAppRouteQueryParamObject` | `{ tag: 'a' }` | `@swcAppRoutePathVariableObject` | `{ id: '1' }` |
+| `@swcAppRouteFirstQueryParamObject` | `{ tag: 'a' }` | `@swcAppRouteFirstPathVariableObject` | `{ id: '1' }` |
+| `@swcAppRouteLastQueryParamObject` | `{ tag: 'b' }` | `@swcAppRouteLastPathVariableObject` | `{ id: '2' }` |
+| `@swcAppRouteQueryParamsObject` | `{ tag: ['a','b'] }` | `@swcAppRoutePathVariablesObject` | `{ id: ['1','2'] }` |
+| `@swcAppRouteURLSearchParams` | `URLSearchParams` | | |
+
+```typescript
+@subscribeSwcAppRouteChange('/releases/{releaseSeq}')
+load(@swcAppRoutePathVariable('releaseSeq') seq: string, @swcAppRouteQueryParam('tab') tab: string | null) { ... }
+```
+
+- Once any parameter is decorated, the positional route argument is no longer passed — add `@swcAppRouterEvent` for the whole event.
+- `route.pathData` keeps its old behavior: a repeated variable name holds the **last** value. Use the decorators above to pick first/last explicitly.
+
+**6. Navigating: `@swcAppRoute` / `@swcAppRouteGo`**
+
+The method returns where to go; the decorator calls the element's SwcApp router — no `Router` injection needed. `@swcAppRoute({ type })` picks the Router method (default `'go'`); `@swcAppRouteGo`, `@swcAppRoutePush`, ... are aliases with the type fixed.
+
+```typescript
+@eventDelegateAll('[data-href]', 'click')
+@swcAppRouteGo
+onNavigate(@matchedElement el: Element) {
+  return el.getAttribute('data-href');
+}
+
+@eventShadow('form', 'submit', { preventDefault: true })
+@swcAppRouteGo
+async onSubmit() {
+  await this.authService.login(...);
+  return '/releases';            // after an async body too
+}
+```
+
+| Return value (`go`) | Result |
+|---|---|
+| `'/path'` / `{ path, searchParams }` | `router.go(...)` |
+| `{ path, replace?, state?, scrollToTop? }` | `router.go` with those options |
+| a number | history move (`-1` = back) |
+| `undefined` / `null` / `false` | no navigation (conditional) |
+
+- Other Router methods: `@swcAppRoute({ type: 'push' })` or the alias with the type fixed (`@swcAppRoutePush` / `@swcAppRoutePush({ state, valueKey })`):
+
+| Alias | `type` | Return value |
+|---|---|---|
+| `@swcAppRouteGo` | `go` (default) | see the table above |
+| `@swcAppRoutePush` / `@swcAppRouteReplace` | `push` / `replace` | `RouteAction` |
+| `@swcAppRoutePushUpsertSearchParam` / `@swcAppRouteReplaceUpsertSearchParam` | `pushUpsertSearchParam` / `replaceUpsertSearchParam` | `{ key: value \| value[] }` |
+| `@swcAppRoutePushAddSearchParam` / `@swcAppRouteReplaceAddSearchParam` | `pushAddSearchParam` / `replaceAddSearchParam` | `[[key, value], ...]` |
+| `@swcAppRoutePushDeleteSearchParam` / `@swcAppRouteReplaceDeleteSearchParam` | `pushDeleteSearchParam` / `replaceDeleteSearchParam` | `string \| string[]` |
+| `@swcAppRoutePushDeleteHashSearchParam` / `@swcAppRouteReplaceDeleteHashSearchParam` | `pushDeleteHashSearchParam` / `replaceDeleteHashSearchParam` | `string \| string[]` |
+
+  `push`/`replace` go through `beforeLeave` guards like `go`. The search-param methods keep the path, so they don't count as leaving and skip the guards.
+- Options: `@swcAppRoute({ type, state, valueKey, filter })`, plus `replace` / `scrollToTop` for `go` (`@swcAppRouteGo({ replace: true })`). `valueKey` picks the target out of a return object when stacked with other output decorators (default key `SWC_APP_ROUTE_METADATA_KEY`).
+- `filter(router, value, { currentThis, helper })` → `false` skips the navigation (same shape as the other output decorators' `filter`; `value` is after `valueKey` extraction). E.g. `@swcAppRouteGo({ filter: (router, to) => to !== router.value.path })`.
+- The original return value still passes through, and navigation goes through `router.go`, so `beforeLeave` guards apply.
+
 #### Advanced Example with Logging
 
 ```typescript
 @elementDefine('accommodation-router')
 class AccommodationRouter extends HTMLElement {
   // Global route logger (order: -1 runs first, no path pattern = matches all routes)
-  @subscribeSwcAppRouteChangeWhileConnected({ order: -1 })
+  @subscribeSwcAppRouteChange({ order: -1 })
   onRouteChange(routerPathSet: RouterEventType) {
     console.log('[Route Change]', {
       path: routerPathSet.path,
@@ -1432,7 +1548,7 @@ class AccommodationRouter extends HTMLElement {
   }
 
   // Home route
-  @subscribeSwcAppRouteChangeWhileConnected(['', '/'], { order: 0 })
+  @subscribeSwcAppRouteChange(['', '/'], { order: 0 })
   @innerHtmlLight
   handleHome(routerPathSet: RouterEventType) {
     console.log('[Route Handler] Home');
@@ -1440,7 +1556,7 @@ class AccommodationRouter extends HTMLElement {
   }
 
   // List route
-  @subscribeSwcAppRouteChangeWhileConnected(['/list'], { order: 1 })
+  @subscribeSwcAppRouteChange(['/list'], { order: 1 })
   @innerHtmlLight
   handleList(routerPathSet: RouterEventType) {
     console.log('[Route Handler] List');
@@ -1448,7 +1564,7 @@ class AccommodationRouter extends HTMLElement {
   }
 
   // Detail route with dynamic parameter
-  @subscribeSwcAppRouteChangeWhileConnected(['/detail/{productId}'], { order: 2 })
+  @subscribeSwcAppRouteChange(['/detail/{productId}'], { order: 2 })
   @innerHtmlLight
   handleDetail(routerPathSet: RouterEventType) {
     const { productId } = routerPathSet.pathData;
@@ -1457,7 +1573,7 @@ class AccommodationRouter extends HTMLElement {
   }
 
   // 404 fallback (order: 999 runs last)
-  @subscribeSwcAppRouteChangeWhileConnected(['/{tail:.*}'], { order: 999 })
+  @subscribeSwcAppRouteChange(['/{tail:.*}'], { order: 999 })
   @innerHtmlLight
   handle404(routerPathSet: RouterEventType) {
     console.log('[Route Handler] 404 Not Found', routerPathSet.path);
@@ -1470,15 +1586,21 @@ class AccommodationRouter extends HTMLElement {
 
 ```typescript
 interface SwcAppRouteChangeOptions {
-  path?: RoutePathType;  // Route path pattern(s)
+  path?: RoutePathType;  // string | string[] | (currentThis) => string | string[]
   order?: number;        // Execution order (default: 0)
-  filter?: (router: Router, meta: {currentThis: any, helper: HelperHostSet}) => boolean;
+  filter?: (router: Router, meta: { currentThis: any; helper: HelperHostSet }) => boolean | Promise<boolean>;
+  before?: (router: Router, meta) => any;           // result → @routeChangeBeforeReturn
+  finally?: (router: Router, meta, ctx: { args; result?; error? }) => any;
+  valueKey?: symbol | string;                       // value used for the stop check
+  trigger?: 'connected' | 'connectedDone';          // replay timing (see "Message Replay")
 }
 ```
 
+Forms: `@subscribeSwcAppRouteChange` (bare, all routes), `('/path')`, `(['/a', '/b'])`, `(path, options)`, `(options)`. Alias: `@changedRoute`.
+
 **Usage:**
 ```typescript
-@subscribeSwcAppRouteChangeWhileConnected(
+@subscribeSwcAppRouteChange(
   ['/admin/{section}'],
   {
     order: 5,
@@ -1492,13 +1614,43 @@ handleAdminSection(routerPathSet: RouterEventType) {
 }
 ```
 
+#### Combined Example: Route + Attribute (nav highlight)
+
+Stack several decorators on one method and split the returned object with `valueKey`.
+**Note:** returning a value stops the later handlers, so an observer-style handler uses `order: -1` and returns `undefined` to keep the chain going.
+
+```typescript
+@replaceChildrenLight({ valueKey: 'element' })
+@subscribeSwcAppRouteChange('/releases')
+@attribute('nav', 'href', { valueKey: 'href' })
+handleExplore() {
+  return { element: ExplorePage(w), href: 'releases' }; // highlight nav + render the page
+}
+
+@subscribeSwcAppRouteChange({ order: -1 })
+@removeAttribute('nav', 'href')
+handleNavReset() {
+  return undefined; // reset the highlight, keep the chain going
+}
+```
+
+```css
+/* Highlight the current section button */
+nav[href="releases"] [data-href="/releases"] { color: var(--color-text); background: var(--color-bg-alt); }
+```
+
 #### RouterEventType Structure
 
 ```typescript
 type RouterEventType = {
-  path: string;           // Current route path
-  pathData: Record<string, any>;  // Extracted path parameters
-  triggerPoint: 'start' | 'end';  // Route change phase
+  path: string;                   // Current route path
+  url: string;
+  search: string;
+  searchParams: URLSearchParams;
+  data?: any;
+  pathData?: Record<string, any>; // Extracted path parameters (filled per matched pattern)
+  router: Router;
+  triggerPoint: 'start' | 'end' | 'first-end';  // Route change phase
 };
 ```
 
@@ -1531,10 +1683,10 @@ import {
 
 @elementDefine('multi-decorator-example')
 class MultiDecoratorExample extends HTMLElement {
-  @setAttribute('selector')
-  @setProperty('selector')
-  @updateStyle()
-  @updateClass()
+  @attribute('selector', 'data-state')
+  @property('selector', 'value')
+  @updateStyle
+  @updateClass
   handleUpdate() {
     return {
       [ATTRIBUTE_METADATA_KEY]: 'attribute-value',
@@ -1553,10 +1705,10 @@ For more readable code, use the `valueKey` option to specify custom keys:
 ```typescript
 @elementDefine('custom-key-example')
 class CustomKeyExample extends HTMLElement {
-  @setAttribute('selector', { valueKey: 'attrValue' })
-  @setProperty('selector', { valueKey: 'propValue' })
-  @updateStyle({ valueKey: 'styleValue' })
-  @updateClass({ valueKey: 'classValue' })
+  @attribute('selector', 'data-state', { valueKey: 'attrValue' })
+  @property('selector', 'value', { valueKey: 'propValue' })
+  @updateStyle('$this', { valueKey: 'styleValue' })
+  @updateClass('$this', { root: 'auto', valueKey: 'classValue' })  // class options need `root`
   handleUpdate() {
     return {
       attrValue: 'attribute-value',
@@ -1575,9 +1727,9 @@ You can mix both approaches in the same method:
 ```typescript
 @elementDefine('mixed-keys-example')
 class MixedKeysExample extends HTMLElement {
-  @setAttribute('selector')  // Uses default ATTRIBUTE_METADATA_KEY
-  @setProperty('selector', { valueKey: 'customProp' })  // Uses custom key
-  @updateStyle({ valueKey: 'styles' })  // Uses custom key
+  @attribute('selector', 'data-state')  // Uses default ATTRIBUTE_METADATA_KEY
+  @property('selector', 'value', { valueKey: 'customProp' })  // Uses custom key
+  @updateStyle('$this', { valueKey: 'styles' })  // Uses custom key
   handleUpdate() {
     return {
       [ATTRIBUTE_METADATA_KEY]: 'attr-value',
@@ -1589,15 +1741,16 @@ class MixedKeysExample extends HTMLElement {
 ```
 
 **Supported Decorators with valueKey:**
-- `@applyAttribute` / `@setAttribute`
-- `@applyProperty` / `@setProperty`
-- `@applySlot` / `@clearSlot` / `@appendHtmlSlot` / etc.
-- `@applyNode` / `@replaceChildrenNode` / etc.
+- `@applyAttribute` / `@attribute`
+- `@applyProperty` / `@property`
+- `@applySlot(id, { position, valueKey })` (the `clearSlot` / `appendHtmlSlot` / ... shorthands take no options)
+- `@applyNode` / `@replaceChildren` / `@innerHtml` / etc.
 - `@applyStyle` / `@updateStyle` / etc.
 - `@applyClass` / `@updateClass` / etc.
 - `@emitCustomEvent` / `@emit`
-- `@publishSwcAppMessage` / `@publish`
-- `@setInterval` / `@setTimeout` - variant: the extracted value must itself be a function, and that function is invoked with `(id: number)` on every tick/fire (see "Timers" section above) rather than being applied directly like the other decorators here.
+- `@publishSwcAppMessage` / `@publishMessage`
+- `@subscribeSwcAppRouteChange` - the extracted value decides whether the chain stops
+- `@setInterval` / `@setTimeout` / `@requestAnimationFrame` - variant: the extracted value must itself be a function, which becomes the timer/frame callback (see "Timers" above) rather than being applied directly.
 
 Each decorator will use only its corresponding value from the return object, preventing conflicts and allowing clean separation of concerns.
 
@@ -1648,7 +1801,7 @@ appElement.connect({
 
 ### Simplified Decorator API
 
-The decorator API uses a consolidated pattern where all decorators support **optional selector parameter** that defaults to `$this` when omitted. This eliminates redundant `*This` functions.
+Most DOM decorators take an **optional selector** that defaults to `$this` when omitted (or when used bare). Scope shorthands (`*This`, `*AppHost`, `*Light`, `*Shadow`, `*All`) are still provided for brevity.
 
 #### Current Usage Pattern
 ```typescript
@@ -1656,7 +1809,7 @@ The decorator API uses a consolidated pattern where all decorators support **opt
 @applyClass('selector', 'update')
 method() { ... }
 
-@applyClass('update')  // Selector defaults to $this
+@applyClass('$this', 'update')  // a single string is treated as the selector, so name $this explicitly (or use bare @updateClass)
 method() { ... }
 
 @applyClass  // Bare decorator - selector defaults to $this
@@ -1666,7 +1819,7 @@ method() { ... }
 #### Decorator Functions (Current API)
 
 **applyClass.ts:**
-- `applyClass(selector?, options?)` - Set/update/add/remove/toggle classes
+- `applyClass(selector?, action?, options?)` - Set/update/add/remove/toggle classes
 - `setClass(selector?, options?)` - Replace all classes
 - `updateClass(selector?, options?)` - Toggle classes
 - `addClass(selector?, options?)` - Add classes
@@ -1674,52 +1827,51 @@ method() { ... }
 - `toggleClass(selector?, options?)` - Toggle classes
 
 **applyStyle.ts:**
-- `applyStyle(selector?, options?)` - Set/update/remove styles
+- `applyStyle(selector?, action?, options?)` - Set/update/remove styles
 - `setStyle(selector?, options?)` - Clear and set styles
 - `updateStyle(selector?, options?)` - Update/merge styles
 - `removeStyle(selector?, options?)` - Remove specific styles
 
 **applyProperty.ts:**
-- `property(selector?, options?)` - Get/set element properties
-- `setProperty(selector?, options?)` - Set element properties
+- `property(selector?, propertyKey?, options?)` - field: property get/set; method: return value → property
 
 **applyAttribute.ts:**
-- `attribute(selector?, options?)` - Get/set element attributes
-- `setAttribute(selector?, options?)` - Set element attributes
+- `attribute(attrName | selector?, attrName?, options?)` - field: attribute get/set; method: return value → attribute (one string = $this)
 
 **query.ts:**
-- `query(selector?, options?)` - Query single element (supports $this, $host, $appHost, etc.)
-- `queryAll(selector?, options?)` - Query multiple elements (same file as `query`)
+- `query(selector, options?)` - Query single element (supports $this, $host, $appHost, etc.; `pick` option)
+- `queryAll(selector, options?)` - Query multiple elements (`query` with `pick: 'all'`)
 
 **emitCustomEvent.ts:**
 - `emitCustomEvent(target, type, options?)` - Emit custom events
 - `emit(target, type, options?)` - Short alias
+- `emitCustomEvent(type, options?)` - Emit from `$this`
 
 #### Usage Examples
 
 ```typescript
 @elementDefine('my-component')
 class MyComponent extends HTMLElement {
-  // Class management - all default to $this
-  @updateClass()
+  // Class management - bare form targets $this
+  @updateClass
   toggleActive() {
     return { 'active': this.isActive };
   }
 
-  // Style management - all default to $this
-  @updateStyle()
+  // Style management - bare form targets $this
+  @updateStyle
   applyTheme() {
     return { color: this.theme.color, fontSize: '16px' };
   }
 
-  // Property binding - all default to $this
-  @setProperty()
+  // Property binding - first string is the selector
+  @property('input', 'value')
   updateValue() {
     return this.computedValue;
   }
 
-  // Attribute binding - all default to $this
-  @setAttribute()
+  // Attribute binding - one string = attribute on $this
+  @attribute('data-id')
   updateId() {
     return this.elementId;
   }
@@ -1732,14 +1884,14 @@ class MyComponent extends HTMLElement {
   listItems?: HTMLLIElement[];
 
   // Emit custom events
-  @addEventListener('button', 'click')
+  @event('button', 'click')
   @emitCustomEvent('$this', 'item-selected')
   onItemSelect() {
     return { itemId: this.selectedId };
   }
 
-  // With selector
-  @updateClass('.card', 'update')
+  // With selector and action
+  @applyClass('.card', 'update')
   updateCardClass() {
     return { 'highlighted': true };
   }
@@ -1748,7 +1900,7 @@ class MyComponent extends HTMLElement {
 
 #### Key Features
 
-1. **Reduced API Surface** - Consolidated decorators eliminate redundant `*This` functions
+1. **Optional Selector** - Omit the selector (or use the bare form) to target `$this`
 2. **Cleaner Code** - Single function name with multiple overloads
 3. **Better Discoverability** - Intuitive parameter patterns
 4. **Flexible Usage** - Supports bare decorators, with options, and with selectors
@@ -1775,17 +1927,16 @@ class UserWidget extends w.HTMLElement { }
 class UserWidget extends w.HTMLElement { }
 ```
 
-### Factory Always Returns 
+### Factory Always Returns (the tag name)
 ```typescript
 export default (w: Window) => {
   const tagName = 'my-element';
-  const existing = w.customElements.get(tagName);
-  if (existing) return existing;  
+  if (w.customElements.get(tagName)) return tagName;
 
   @elementDefine(tagName, { window: w })
   class MyElement extends w.HTMLElement { }
-  
-  return existing; 
+
+  return tagName;
 };
 ```
 
@@ -1803,6 +1954,20 @@ constructor(private service: Service) { super(); }  // Web Components can't have
 
 ---
 
+## 🧪 Testing
+
+`pnpm test` type-checks the tests and runs them in a real browser (Chromium via Playwright, falling back to the installed Chrome) — no jsdom. Each test gets its own same-origin iframe window, so custom elements, `history` and `location` never leak between tests.
+
+```bash
+pnpm test                                            # type checks + all tests
+node test/unit/run.mjs query event                   # only files whose name contains "query" / "event"
+SWC_TEST_GREP='bare @query' node test/unit/run.mjs   # only tests whose name matches
+SWC_TEST_DEBUG=1 node test/unit/run.mjs route        # print the page console
+SWC_TEST_SERVE=1 node test/unit/run.mjs route        # just serve the pages and open them yourself
+```
+
+Test files are plain `node:test` / `node:assert` code (`test/unit/*.test.ts`); the runner maps those imports to small in-browser versions. `test/unit/empty-parens.types.ts` is checked by `tsc` only and guards the "no arguments → no parentheses" rule.
+
 ## 📚 Examples
 
 - **[Commerce (E-Commerce SPA)](https://github.com/dooboostore-develop/packages/tree/main/%40dooboostore/simple-web-component/examples/commerce)** - Full shopping cart example
@@ -1822,3 +1987,219 @@ constructor(private service: Service) { super(); }  // Web Components can't have
 ## 📄 License
 [MIT License](https://github.com/dooboostore-develop/packages/tree/main/%40dooboostore/simple-web-component/LICENSE.md)
 
+
+---
+
+---
+
+## 📨 Message Replay (subject / trigger)
+
+Late subscribers can receive past messages. The buffer keeps every typed message
+(`SwcConfigType.messageReplayBufferSize`, default 10, minimum 1 guaranteed).
+
+```typescript
+// 'behavior' = last message only, 'replay' = whole buffer in order.
+// Unset (or 'subject') = live only.
+@subscribeSwcAppMessage('auth-changed', { subject: 'behavior' })
+onAuth(@appMessage msg: SwcAppMessage<User | null>) { ... }
+```
+
+`trigger` controls when replay happens (default `'connected'`).
+
+- `'connected'`: replay when the element registers with the app host, i.e. before its own
+  `@onConnectedBody` render. For handlers that don't need DOM targets.
+- `'connectedDone'`: replay after the element finished rendering (after `@onConnectedCompleted`).
+  Use it when the handler targets DOM rendered by the element itself, like `@innerHtml('.wrap')`
+  (avoids the race where replay arrives before render and gets silently dropped).
+
+```typescript
+@subscribeSwcAppMessage('auth-changed', { subject: 'behavior', trigger: 'connectedDone' })
+@innerHtml('.wrap')
+async load(@appMessage msg: SwcAppMessage<User | null>) { ... }
+```
+
+Route subscribers (`@subscribeSwcAppRouteChange`) accept the same `trigger`.
+Live broadcasts always reach everyone regardless of trigger.
+
+## 🔌 App Host Hooks (onConnected / onSwcAppConnected / onDisconnected)
+
+The three host hooks of `SwcAppMixin` are **abstract**: a subclass must implement them (use an empty method if there is nothing to do).
+`@inject` parameters are resolved via DI (host element itself included).
+
+- `onConnected()` - at connectedCallback (every time it is attached). It runs one async step after attaching, so its order relative to `connect()` depends on when you call `connect()`:
+  - `connect()` right after attaching → `connect()` → `onSwcAppConnected()` → `onConnected()` (DI already exists)
+  - `connect()` later → `onConnected()` (no DI yet) → `connect()` → `onSwcAppConnected()`
+
+  So don't rely on DI or on ordering here — keep it to DOM/attribute work and subscriptions; call services in `onSwcAppConnected()`
+- `onSwcAppConnected()` - after `connect()` completes (DI container and router are ready). **Call services here**
+- `onDisconnected()` - at disconnectedCallback. Release subscriptions created in `onConnected`
+
+```typescript
+class MyAppBody extends SwcAppMixin(w.HTMLBodyElement) {
+  onConnected() {}
+  async onSwcAppConnected(@inject(AuthService.SYMBOL) auth: AuthService) {
+    this.publishMessage({ type: 'auth-changed', data: await auth.me().catch(() => null) });
+  }
+  onDisconnected() {}
+}
+```
+
+### observeMessage — the message bus as an Observable
+
+```typescript
+host.observeMessage()                                    // all types, live only
+host.observeMessage('auth-changed')                      // one type
+host.observeMessage('auth-changed', { subject: 'behavior' }) // type + replay of the last value
+host.observeMessage({ type: 'auth-changed', subject: 'replay' }) // options-object form
+```
+
+- `subject`: `'behavior'` (last one) / `'replay'` (whole buffer) is delivered first at subscribe time, then live messages.
+- Replay only works when `type` is given; options without a type receive live messages only.
+- Returns an `Observable`; `unsubscribe()` the `Subscription` yourself (usually in `onDisconnected`).
+
+When publishing from the host itself, call `this.publishMessage` directly.
+The `@publishSwcAppMessage` decorator publishes through the parent host, and the
+host itself has no parent, so the message would be dropped.
+
+Use `connectedElements()` to get the currently connected child elements.
+
+## 🌐 @fetch — Declarative HTTP
+
+```typescript
+// bare form: GET by default
+@fetch('https://api.example.com/post/1')
+async load(@fetchSettled settled: PromiseSettledResult<any>) {
+  return settled;
+}
+
+// before (default): build request → fetch → inject settled → run method.
+// Returns the method result.
+@fetch({ url: '/api/post/1', request: 'GET' })
+async loadBefore(@fetchSettled settled: PromiseSettledResult<any>) {
+  return settled.status === 'fulfilled' ? settled.value : null;
+}
+
+// after: run method → use its return value as the body → fetch. Returns the fetch result.
+@fetch({ url: '/api/posts', trigger: 'after', process: 'json' })
+async save() {
+  return { title: 'hello' };
+}
+
+// after + valueKey: use returnValue[valueKey] as the body.
+@fetch({ url: '/api/echo', trigger: 'after', valueKey: 'form', process: 'form' })
+async saveForm() {
+  return { form: { title: 'hi' } };
+}
+```
+
+**Modes**
+- **before** (default, or `trigger: 'before'`): build request → fetch → inject the settled result via
+  `@fetchSettled` → run the method. Returns the method result. A failed fetch does not
+  throw — it arrives as `{ status: 'rejected', reason }`.
+- **after** (`trigger: 'after'`, or just `valueKey`): run the method → its return value
+  (or `returnValue[valueKey]`) becomes the body → fetch. Returns the fetch result; a failed fetch throws.
+  `valueKey` is after-only — combining it with `trigger: 'before'` is a type error.
+
+**Declarative vs manual** — pick one:
+- **Declarative**: describe the request with `url` / `request` / `process` and the framework fetches.
+- **Manual**: give `manual` and make the request yourself (a service call, your own `fetch`, ...).
+  `url` / `request` / `process` are unused then, so combining them with `manual` is a type error.
+
+```typescript
+// service call — only the result matters
+@fetch({ manual: (self) => self.myService.getProfile({}) })
+async load(@fetchSettled settled?: PromiseSettledResult<MyService.ProfileResponse>) { ... }
+
+// your own fetch — pass the signal so an abort cancels the network request too
+@fetch({ trigger: 'after', manual: (_self, _helper, _params, signal, returnValue) =>
+  window.fetch('/api/save', { method: 'POST', body: JSON.stringify(returnValue), signal }).then(r => r.json()) })
+async save() { return { title: 'hi' }; }
+```
+
+`manual(this, helper, params, signal, returnValue?)` — `signal` aborts on disconnect / `abortPrevious`;
+`returnValue` is the method's return value (or `returnValue[valueKey]`) in after mode, `undefined` in before mode.
+Its return value is the fetch result.
+
+**Options (declarative)**
+- `url`: a string/`URL`/`Request`, or a factory `(this, helper, params) => url`.
+- `request`: an HTTP method string (`'GET'`/`'POST'`/...) or a factory returning `RequestInit` —
+  `(this, helper, params) => RequestInit` in before mode, `(this, helper, params, returnValue) => RequestInit`
+  in after mode. Absent = GET, or POST when there is a body.
+- `process`: body encoding for plain values — `'json'` / `'form'` (multipart) / `'urlencoded'` / `'text'`.
+  Values that already are a `BodyInit` (string, `Blob`, `ArrayBuffer`, `FormData`, `URLSearchParams`,
+  `ReadableStream`) are sent as-is. Unset = pass through untouched.
+- Headers: `request` may return `headers` as an object, array or `Headers` instance. A `Content-Type`
+  you set wins over the one `process` would add.
+- The request uses the element's window `fetch` (the per-request window under SSR), falling back to `globalThis.fetch`.
+- Default response handling: empty body (e.g. 204) → `undefined`, JSON content types (`application/json`,
+  `*+json`) → parsed, otherwise text. A non-OK status throws `HttpResponseError` from `@dooboostore/core`
+  with `response` (status, headers) and the parsed `body`:
+
+```typescript
+@fetch('/api/post/1')
+async load(@fetchSettled settled?: PromiseSettledResult<any>) {
+  if (settled?.status === 'rejected' && isHttpResponseError(settled.reason)) {
+    return settled.reason.response?.status; // e.g. 404
+  }
+}
+```
+
+**Hooks** (same order as every other SWC decorator: `filter → before → handler → finally`)
+- `filter(this, helper, params)` → `false` skips the whole call (no method, no fetch; returns `undefined`).
+- `before(this, helper, params)` runs first after `filter` and is awaited; its return value is ignored.
+- `after(this, helper, params, settled)` runs right after the fetch settles (fulfilled or rejected).
+- `finally(this, helper, params, { args, result, error })` always runs around the whole call.
+  `result` is what the call returns (the method result in before mode, the fetch result in after mode).
+
+**Cancellation**
+- Every call gets its own `AbortController`. Declarative requests get its signal as `init.signal`
+  (merged with a `signal` you return from `request`, via `AbortSignal.any` or a fallback); `manual` gets it as
+  the `signal` argument.
+- When the element disconnects, all its in-flight `@fetch` requests are aborted. Such a call ends
+  quietly with `undefined`: the method (before mode) and the `after` hook are skipped so nothing touches
+  a detached DOM; `finally` still runs with `ctx.error` set to the `AbortError`.
+- A call that *starts* while the element is detached (e.g. a `setTimeout` scheduled just before the user
+  navigated away) is skipped the same quiet way. Elements that were never connected are not affected.
+- `manual` should pass `signal` on to its own client (`fetch`, axios, ...) so the network
+  request is actually cancelled. If it ignores the signal, the call still ends as soon as it's aborted
+  (the result is raced against the abort) — the request just keeps running in the background and its
+  late result is discarded.
+- `abortPrevious: true` aborts the previous in-flight call of the same method when it's called again
+  (search-as-you-type) — the superseded call ends quietly the same way, so a late old response can't
+  overwrite the newest result.
+- Aborting through your own signal is not quiet: it surfaces as a rejected settled result (before mode)
+  or a thrown error (after mode), like any other failure.
+
+**Aliases**
+
+| Alias | Same as |
+|---|---|
+| `@fetchManual(fn, options?)` | `@fetch({ ...options, manual: fn })` |
+| `@fetchGet(url, options?)` / `@fetchDelete(url, options?)` | before mode, `method` fixed to GET / DELETE |
+| `@fetchPost(url, options?)` / `@fetchPut(...)` / `@fetchPatch(...)` | after mode (the method's return value is the body), `method` fixed |
+| `@fetchLatest(url \| options)` | `@fetch({ ...options, abortPrevious: true })` |
+| `@fetchBefore(options)` / `@fetchAfter(options)` | `@fetch({ ...options, trigger })` |
+
+For the method aliases, `request` may only be a factory returning `RequestInit` (e.g. headers) — its `method` is overwritten.
+
+```typescript
+@fetchManual((self) => self.myService.getProfile({}))
+async load(@fetchSettled settled?: PromiseSettledResult<Profile>) { ... }
+
+@fetchPost('/api/posts', { process: 'json' })
+async save() { return { title: 'hi' }; }
+
+@fetchDelete((_self, _helper, params) => `/api/posts/${params[0]}`)
+async remove(id: number, @fetchSettled settled?: PromiseSettledResult<unknown>) { ... }
+```
+
+**Composition** — e.g. form submit:
+`@event('form', 'submit', { before: (e) => new FormData(e.target), preventDefault: true })`
+stacked on `@fetch({ url: '/api/echo', trigger: 'after', process: 'form' })`, with the method taking
+`@eventBeforeReturn formData: FormData` and returning it.
+
+## 💧 @property Hydration Rules
+
+- Attach bare `@property` (no args) to a field to mark it as an SSR hydration target.
+- Self fields (`$this` + matching key) stay plain fields with no getter/setter.
+- Declare the field with `declare` (both `= null` and `;` initializers get overwritten on upgrade).