@dooboostore/simple-web-component 1.0.54 → 1.0.56

package/README.md

@@ -399,16 +399,20 @@ class ProductList extends HTMLElement {
 - `@hostSet` - host-ancestor-tree info only (`$host`, `$parentHost`, `$hosts`, `$appHost`, `$appHosts`, `$firstHost`, `$lastHost`, `$firstAppHost`, `$lastAppHost`)
 - `@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
+- `@swcAppRouter` - the `Router` instance (`$appHost.router`) directly, no `@inject`/DI container needed; `undefined` outside a `SwcApp` tree
+- `@swcAppSimpleApplication` - the `SimpleApplication` (DI container) instance (`$appHost.simpleApplication`) directly; `undefined` outside a `SwcApp` tree or without a DI container. `@inject` is usually what you want instead — reach for this only when you need the container itself (e.g. `simstanceManager`).
+- `@swcAppHost` - the `SwcApp` host element itself (`$appHost`) directly, when you just need the host and not the whole `HostSet`; `null` outside a `SwcApp` tree (matches `HostSet.$appHost`'s own type, unlike the two above which use optional chaining down to `undefined`)
 
 `$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.
+The same mechanism (and the same 8 decorators, plus two more) also applies to:
+- **`@onInitialize`/`@onConnectedBefore`/`@onConnectedAfter`/... lifecycle methods** — can freely mix `@hostSet`/`@helperHostSet`/`@helperSet`/`@swcAppRouter`/`@swcAppSimpleApplication`/`@swcAppHost` with `@inject(...)` on the same method.
 - **`@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.
+- **`@subscribeSwcAppMessage`** — add `@swcAppMessage` to receive the `SwcAppMessage` regardless of position.
+- **`before` hook results** — `@eventBeforeReturn`, `@routeChangeBeforeReturn`, `@swcAppMessageBeforeReturn`, `@changedAttributeBeforeReturn`, `@mutationObserverBeforeReturn`, `@resizeObserverBeforeReturn`, `@intersectionObserverBeforeReturn`, `@eventMediaBeforeReturn`, `@setIntervalBeforeReturn`, `@setTimeoutBeforeReturn` inject the value returned by that decorator's `before` option.
+- **DOM/storage/fetch values** — `@querySelectorParam`, `@attributeParam`, `@localStorageParam`/`@sessionStorageParam`/`@cookieParam`/`@indexedDbParam`, `@fetchParam` go a step further and actively compute/fetch a value instead of just handing you context — see "Value-Injecting Parameter Decorators" below.
 
-Note: once any parameter of a method is decorated, only decorated parameters receive values (the legacy positional arguments are no longer passed).
+Note: once any parameter of a method is decorated, every parameter still gets a value — decorated ones receive their injected value, and any parameter left undecorated falls back to its legacy positional argument. So mixing is safe: `onChanged(nv, @querySelectorParam('#x') el, name)` still gets `nv`/`name` from the usual positional arguments.
 
 ```typescript
 @onConnectedAfter
@@ -418,7 +422,7 @@ onconstructor(@inject(UserService.SYMBOL) userService: UserService, @hostSet hs:
 onRouteChanged(@helperSet helpers: HelperSet, @swcAppRouterEvent re: RouterEventType) { ... }
 
 @subscribeSwcAppMessage
-onMessage(@hostSet hs: HostSet, @appMessage msg: SwcAppMessage) { ... }
+onMessage(@hostSet hs: HostSet, @swcAppMessage msg: SwcAppMessage) { ... }
 ```
 
 #### @emitCustomEvent
@@ -618,7 +622,8 @@ class ProductCard extends HTMLElement {
 - 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,
+Always removes the attribute when the method runs — the name already says what to do, so the return value doesn't matter.
+With `valueKey`, it removes only when that key is truthy. The return value passes through unchanged,
 so it is safe on subscriber handlers that must not return a value (e.g. route changes).
 
 ```typescript
@@ -891,6 +896,20 @@ class ContentUpdater extends HTMLElement {
 - `@innerHtml` / `@innerHtmlLight` / `@innerHtmlShadow` - Set innerHTML
 - `@innerText` / `@innerTextLight` / `@innerTextShadow` - Set innerText
 - `@clearChildrenNode` / `@clearChildrenLight` - Remove all children
+- `@removeNode` - Remove the target element itself (bare / `'$this'` removes the component)
+
+**Declaration = action** (`@removeNode`, `@clearChildrenNode`, `@removeAttribute`, and `@addClass` / `@removeClass` / `@toggleClass` with the class name written in the decorator):
+they run whatever the method returns. Give a `valueKey` to decide per call — then they run only when that key is truthy
+(`@toggleClass('.x', 'open')`: no return toggles, `true` / `false` forces on / off).
+
+```typescript
+@eventClick('.close')
+@removeNode('.toast')                          // always removes
+close() {}
+
+@removeNode('.editor', { valueKey: 'close' })  // removes only when close is truthy
+save() { return { close: this.saved }; }
+```
 - Options: `position`, `root`, `filter`, `fallback`, `valueKey`. Ready-made `filter` helpers: `skipIfSameTagPresent`, `skipIfExists(selector)`, `skipIfEmpty`, `applyIfChanged` (e.g. `@innerHtmlLight({ filter: skipIfExists('my-page') })`)
 
 **Position Options:**
@@ -957,7 +976,7 @@ class StyledComponent extends HTMLElement {
 **@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`
+- `addClass` / `removeClass` / `toggleClass` — with the class name in the decorator (`@addClass('.x', 'on')`) the declaration is the action (see "Declaration = action" above)
 - `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
 
@@ -1158,7 +1177,11 @@ 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.
+**@subscribeSwcAppMessage Options:** `filter(message, currentThis)`, `before(message, currentThis)` (result → `@swcAppMessageBeforeReturn`), `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.
+
+**Shortcuts for `subject`:** `@subscribeSwcAppMessageBehavior(type, options?)` = `{ subject: 'behavior' }` (a late subscriber gets the last message),
+`@subscribeSwcAppMessageReplay(type, options?)` = `{ subject: 'replay' }` (gets the whole buffer). Same forms as `@subscribeSwcAppMessage`
+(bare, type, options, type + options); the other options pass through.
 
 #### @publishSwcAppMessage
 Publish a message from a method's return value.
@@ -1485,9 +1508,25 @@ No prefix means *first*; `First`/`Last` pick the first/last value when a key rep
 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.
+- Add `@swcAppRouterEvent` for the whole event — any parameter left undecorated still gets the positional route argument even after others are decorated (see the parameter-decorator note earlier in this doc).
 - `route.pathData` keeps its old behavior: a repeated variable name holds the **last** value. Use the decorators above to pick first/last explicitly.
 
+**On fields.** The same decorators work on fields. The SwcApp fills them on every route change and, for an element attached later, from the current route before its first render. Inside a route handler of the same element, the field already holds this route's value.
+
+```typescript
+class UserPage extends HTMLElement {
+  @swcAppRouteQueryParam('tab') tab?: string | null;                          // query: no pattern needed
+  @swcAppRoutePathVariable('id', { path: '/user/{id}' }) userId?: string;    // path variables need { path }
+  @swcAppRoutePathVariableObject({ path: ['/user/{id}', '/member/{id}'] }) vars?: { id?: string };
+
+  @onConnectedBodyShadow render() { return `<h1>${this.userId} · ${this.tab}</h1>`; }
+}
+```
+
+- `path` takes the same forms as `@subscribeSwcAppRouteChange` (string, array, or `(currentThis) => ...`). When it doesn't match the current route, path fields are empty (`undefined`, `[]`, `{}`); query fields keep updating. A path-variable field without `{ path }` warns once at definition.
+- A field is reassigned only when its value changes (object fields keep their reference otherwise), so a setter on it doesn't fire for unrelated route changes.
+- Don't name such fields after built-in `HTMLElement` properties (`id`, `lang`, `title`, `prefix`, ...): assigning to them changes the element instead.
+
 **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.
@@ -1953,6 +1992,40 @@ constructor(private service: Service) { super(); }  // Web Components can't have
 
 ---
 
+## ⚡ Benchmarks
+
+Measured in real Chrome against a hand-written `innerHTML` renderer and Lit, rendering the same 1,000-row table (state in fields, a decorated method returns the HTML, `@replaceChildren*` applies it):
+
+- **Bulk rendering keeps up with Lit.** Creating 10,000 rows takes 244 ms, versus 232 ms for Lit and 222 ms for a hand-written `innerHTML` loop.
+- **Low memory.** 1,000 rows keep about 94 KB of JS heap, 6x less than Lit (558 KB); at 10,000 rows it is 1.6 MB versus 4.9 MB (3x less). Only the data is retained, no per-row template bookkeeping.
+- **Thin layer.** Rendering through the decorators costs within about 5% to 25% of the equivalent hand-written `innerHTML` code.
+
+```text
+create 10,000 rows  (lower is better)
+  vanilla (innerHTML)   ██████████████████████████        222  ▲
+  lit                   ████████████████████████████      232
+  simple-web-component  █████████████████████████████     244
+  vanilla (DOM calls)   ████████████████████████████████  269
+
+JS heap, 1,000 rows (KB)  (lower is better)
+  vanilla (innerHTML)   ████                              73.4  ▲
+  simple-web-component  █████                             93.5
+  vanilla (DOM calls)   ███████                           119
+  lit                   ████████████████████████████████  558
+```
+
+Full results, including the operations where other approaches are faster, methodology and caveats: [bench/RESULTS.md](./bench/RESULTS.md). Reproduce with `pnpm bench` inside `bench/`.
+
+---
+
+## 🧰 Editor Support (LSP)
+
+The package ships a language server for SWC templates — `npx swc-lsp --stdio`:
+tag / attribute / `@state@` / `$host.` completion, hover, go to definition, parameter hints, and type errors inside `swc-on-*`, `{{= }}` and `@x@`
+(`swc-on-click="$host.tt(4)"` → *number is not assignable to string*).
+
+Setup for IntelliJ, VS Code and Neovim: [lsp/README.md](https://github.com/dooboostore-develop/packages/tree/main/@dooboostore/simple-web-component/lsp).
+
 ## 🧪 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.
@@ -1999,8 +2072,8 @@ Late subscribers can receive past messages. The buffer keeps every typed message
 ```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>) { ... }
+@subscribeSwcAppMessageBehavior('auth-changed')   // = @subscribeSwcAppMessage('auth-changed', { subject: 'behavior' })
+onAuth(@swcAppMessage msg: SwcAppMessage<User | null>) { ... }
 ```
 
 `trigger` controls when replay happens (default `'connected'`).
@@ -2014,12 +2087,26 @@ onAuth(@appMessage msg: SwcAppMessage<User | null>) { ... }
 ```typescript
 @subscribeSwcAppMessage('auth-changed', { subject: 'behavior', trigger: 'connectedDone' })
 @innerHtml('.wrap')
-async load(@appMessage msg: SwcAppMessage<User | null>) { ... }
+async load(@swcAppMessage msg: SwcAppMessage<User | null>) { ... }
 ```
 
 Route subscribers (`@subscribeSwcAppRouteChange`) accept the same `trigger`.
 Live broadcasts always reach everyone regardless of trigger.
 
+### `@swcAppMessage` on fields
+
+On a field, `@swcAppMessage` holds the latest `SwcAppMessage` — set on every publish, before the same element's subscribers run. It takes the same forms and `subject` rule as `@subscribeSwcAppMessage`:
+
+```typescript
+@swcAppMessage last?: SwcAppMessage;                                         // every type, live only
+@swcAppMessage('auth-changed') auth?: SwcAppMessage<User | null>;            // live only (default 'subject')
+@swcAppMessage('auth-changed', { subject: 'behavior' }) me?: SwcAppMessage<User | null>;   // late element: last one
+@swcAppMessage({ messageType: 'auth-changed', subject: 'replay' }) all?: SwcAppMessage;    // late element: buffer in order
+```
+
+- With `'behavior'`/`'replay'` (and a type), an element attached after the publish gets the field filled from the buffer before its first render. Without a type nothing is replayed.
+- `@swcAppMessageBeforeReturn` stays parameter-only: it is the `before` hook's result for one handler call.
+
 ## 🔌 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).
@@ -2064,37 +2151,119 @@ Use `connectedElements()` to get the currently connected child elements.
 
 ## 🌐 @fetch — Declarative HTTP
 
+`@fetch` and its aliases (`@fetchGet`, `@fetchPost`, `@fetchLatest`, `@fetchManual`, …) go in one of three places.
+Pick by **who calls it** and **whether the result should be remembered**:
+
+| Where | Declare | Use when | Remembers the result? |
+|---|---|---|---|
+| **Method** | `load(@fetchPromise p: Promise<T>) { … }` | the framework calls it — a trigger handler (`@eventClick`, `@onConnectedAfter`, a route…) | no |
+| **Function field** | `declare getPost: (id: number) => Promise<T>;` | you call it yourself, anywhere, maybe with arguments (`this.getPost(1)`) | no — every call is a new request |
+| **Value field** | `declare me?: Promise<T>;` | data you load once and keep reading (`await this.me`) | **yes** — until you clear it |
+
+### 1. On a method — trigger handlers
+
+Stack the trigger, the outputs and `@fetch` on one method. The request starts first; its `Promise` is handed to the
+`@fetchPromise` parameter and the method runs **right away**. The method's own return value is returned unchanged, so the
+signature you wrote stays true (a sync method stays sync).
+
 ```typescript
-// bare form: GET by default
-@fetch('https://api.example.com/post/1')
-async load(@fetchSettled settled: PromiseSettledResult<any>) {
-  return settled;
+@eventClick('.load')
+@innerHtml('.out', { fallback: () => 'Loading…' })   // shown until the returned Promise settles
+@fetchLatest('/api/post/1')                           // click again → the previous request is aborted
+load(@fetchPromise p: Promise<Post>) {
+  return p.then(post => post.title, () => 'Failed');   // success / failure, no try/catch
 }
+```
 
-// 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;
-}
+If you also call such a method yourself, declare the parameter optional (`@fetchPromise p?: Promise<T>`) — the
+framework fills it, callers don't. For a request you call yourself, a field (below) is the better fit.
 
-// 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' };
-}
+### 2. Function field — a request function you call
+
+The framework writes the function body; the declared type is the real signature (no injected parameter, no changed
+return type).
 
-// after + valueKey: use returnValue[valueKey] as the body.
-@fetch({ url: '/api/echo', trigger: 'after', valueKey: 'form', process: 'form' })
-async saveForm() {
-  return { form: { title: 'hi' } };
+```typescript
+// GET / DELETE: the arguments feed url / request
+@fetchGet((_self, _helper, [id]) => `/api/posts/${id}`)
+declare getPost: (id: number) => Promise<Post>;
+
+// POST / PUT / PATCH: the last argument is the body
+@fetchPost('/api/posts', { process: 'json' })
+declare createPost: (body: NewPost) => Promise<Post>;
+
+@fetchLatest({ url: (_s, _h, [q]) => `/api/search?q=${q}` })   // only the latest call settles
+declare search: (q: string) => Promise<Item[]>;
+
+// use it from a trigger handler (or anywhere)
+@eventClick('.load')
+@innerHtml('.out', { fallback: () => 'Loading…' })
+show() {
+  return this.getPost(1).then(p => p.title);
 }
 ```
 
-**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 }`.
+Every call is a new request. Success resolves, failure rejects with `HttpResponseError` (see below).
+
+### 3. Value field — data that is remembered
+
+```typescript
+@fetch('/api/me')
+declare me?: Promise<User>;   // `?` so that `this.me = undefined` type-checks under `strict`
+
+await this.me;          // first read: request → remembered on success
+await this.me;          // remembered result (no request)
+
+this.me = undefined;    // forget it (null works too) …
+await this.me;          // … so this read requests again — this is how you reload
+
+this.me = savedUser;    // or seed a value yourself (e.g. data that came with SSR) — no request
+```
+
+- Declare it optional (`declare me?: Promise<T>`) if you ever clear it: under `strict`, assigning `undefined` to a
+  plain `Promise<T>` is a type error. Reading it is still `await this.me` (the result type is `T | undefined`).
+  If you never clear it, `declare me: Promise<T>` is fine.
+- Clear it by assigning, not with `delete this.me` — the memory lives behind the field's setter.
+
+- **Remembered**: success, per element. **Not remembered**: failure — the next read requests again.
+- **Forgotten**: when you assign `undefined` / `null`, and when the element disconnects (the request is aborted; a read
+  after reconnecting requests again).
+- There are no arguments — build the body in the `request` factory if the request needs one.
+- If the data must be fresh on every use, declare a function field instead (`declare loadMe: () => Promise<User>`).
+- The value is a real Promise to your code (`instanceof Promise` is true), so it can be returned straight to an output
+  decorator: `@innerHtml('.name') showName() { return this.me.then(u => u.name); }`.
+
+### Field rules (function and value fields)
+
+- **Always write `declare`.** Without it, builds with `useDefineForClassFields: true` (the default for target ES2022+)
+  create an instance field that hides what the framework put there:
+
+  | Build setting | `declare me: Promise<T>` | `me!: Promise<T>` (no `declare`) |
+  |---|---|---|
+  | `useDefineForClassFields: false` | works | works (but `strict` needs the `!`) |
+  | `useDefineForClassFields: true` / ES2022+ default | works | **broken** — reported on connect: *must be declared with `declare`* |
+
+- **Declared type is checked.** At compile time the field must be `(...args) => Promise<T>` or `Promise<T>`
+  (`string`, `() => T`, … are errors; optional `?` fields are fine; `private` / `protected` fields can't be seen by
+  TypeScript and are not checked).
+  Builds that emit `design:type` (`emitDecoratorMetadata` with tsc / ts-loader) also reject a non-function, non-Promise
+  type at runtime.
+- **Nothing else on the field.** Triggers and outputs go on a method that calls the field. Method decorators on a field
+  are already compile errors; any other SWC decorator on the same field (`@attribute`, `@query`, …, or anything via
+  `as any`) throws when the class is defined.
+- **Same in every build.** Function vs. value is decided by how you declared it, not by build metadata: the field holds
+  one object that is callable and a Promise, and TypeScript lets you use it only the way you declared it.
+- **Quiet ends.** A call skipped by `filter` or made while the element is detached, and a call aborted by the framework
+  (disconnect, `abortPrevious`), return a Promise that **never settles** — nothing draws on a detached DOM, nothing throws.
+
+### Method modes
+
+- **before** (default, or `trigger: 'before'`): start the request → inject its `Promise` via
+  `@fetchPromise` → run the method **right away**. Returns the method's own return value, so the
+  signature you wrote stays true (sync stays sync). Success resolves, failure rejects — handle both with
+  `then` / `catch` / `finally` on the Promise.
+  If you also call the method yourself, declare the parameter optional (`@fetchPromise p?: Promise<T>`) —
+  the framework fills it, callers don't.
 - **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.
@@ -2107,7 +2276,7 @@ async saveForm() {
 ```typescript
 // service call — only the result matters
 @fetch({ manual: (self) => self.myService.getProfile({}) })
-async load(@fetchSettled settled?: PromiseSettledResult<MyService.ProfileResponse>) { ... }
+load(@fetchPromise p: Promise<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) =>
@@ -2136,38 +2305,37 @@ Its return value is the fetch result.
 
 ```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
-  }
+load(@fetchPromise p: Promise<Post>) {
+  return p.catch(e => isHttpResponseError(e) ? e.response?.status : undefined); // 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).
+**filter** — the only hook
+- `filter({ self, helper, args })` → `false` skips the whole call: no request, no method. A method returns `undefined`;
+  a field returns a Promise that never settles.
+  It is synchronous: the request starts before the method runs, so "send or not" can only be decided here.
+- There is no `before` / `after` / `finally` on `@fetch`: result handling is plain Promise code
+  (`then` / `catch` / `finally`), and gating or cleanup around the call lives on the trigger you stack it with
+  (`@eventClick`, `@onConnectedAfter`, …), which already has `filter → before → handler → finally`.
 
 **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`.
+- When the element disconnects, all its in-flight `@fetch` requests are aborted. The injected Promise then
+  **never settles** (before mode), so nothing draws on a detached DOM and nothing throws; an after-mode call
+  ends quietly with `undefined`.
 - 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
+- `abortPrevious: true` aborts the previous in-flight call of the same method (per element) when it's called again
+  (search-as-you-type) — the superseded Promise never settles, 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.
+- Aborting through your own signal is not quiet: it rejects the Promise (before mode)
+  or throws (after mode), like any other failure.
 
 **Aliases**
 
@@ -2183,13 +2351,13 @@ For the method aliases, `request` may only be a factory returning `RequestInit`
 
 ```typescript
 @fetchManual((self) => self.myService.getProfile({}))
-async load(@fetchSettled settled?: PromiseSettledResult<Profile>) { ... }
+load(@fetchPromise p: Promise<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>) { ... }
+remove(id: number, @fetchPromise p?: Promise<unknown>) { ... }
 ```
 
 **Composition** — e.g. form submit:
@@ -2197,6 +2365,124 @@ async remove(id: number, @fetchSettled settled?: PromiseSettledResult<unknown>)
 stacked on `@fetch({ url: '/api/echo', trigger: 'after', process: 'form' })`, with the method taking
 `@eventBeforeReturn formData: FormData` and returning it.
 
+## 🧩 Value-Injecting Parameter Decorators (@querySelectorParam, @attributeParam, @local/session/cookie/indexedDbParam, @fetchParam, @swcAppRouter)
+
+Unlike `@hostSet`/`@helperSet`/`@helperHostSet` (which just hand you context objects), these decorators actively **go compute or fetch a value** and inject it — once, at the moment the method's trigger fires (`@onConnectedAfter` and friends, `@addEventListener`, `@setInterval`/`@setTimeout`, the observer decorators, `@eventMedia`, route/message subscribers, ...). They only work inside such auto-triggered methods — a plain method you call yourself gets `undefined` for these parameters, since nothing builds the lookup for it.
+
+> Unlike `@query`/`@queryAll` (lazy — re-queries the DOM on every read), these resolve **once per call**, as a plain captured value, not a live reference. If the DOM/storage changes after the method runs, the parameter you already received does not change.
+
+### @querySelectorParam / @querySelectorAllParam
+Same engine as the field decorators `@query`/`@queryAll` (`root`, `pick`, `filter`, function selectors all supported) — named "querySelector" instead of "query" so it doesn't read like a URL query parameter.
+
+```typescript
+@onConnectedAfter
+onReady(
+  @querySelectorParam('#name') input: HTMLInputElement,
+  @querySelectorAllParam('.item', { root: 'all' }) items: HTMLElement[]
+) {
+  input.focus();
+}
+
+@addEventListener('#save', 'click')
+onSave(@querySelectorShadowParam('.form') form: HTMLFormElement) { ... }
+```
+- Root/pick shorthands mirror `@query`'s own family: `querySelectorShadowParam` / `querySelectorLightParam` / `querySelectorAllRootsParam` (single), `querySelectorAllShadowParam` / `querySelectorAllLightParam` / `querySelectorAllAllParam` (arrays).
+
+### @attributeParam
+Same engine as the field/method `@attribute`.
+
+```typescript
+onReady(
+  @attributeParam('data-x') ownAttr: string,
+  @attributeParam('#child', 'data-y', { root: 'shadow' }) childAttr: string
+) { ... }
+```
+- One string = this element's own attribute; `(selector, name, options?)` = another element's attribute (same two-form shape as the field decorator).
+- `options.type` converts to `Number`/`Boolean`, same as the field decorator; missing attribute/target → `null`.
+
+### @localStorageParam / @sessionStorageParam / @cookieParam / @indexedDbParam
+Inject a persisted value by key (see "Persisted State" below for the backing storage). `@indexedDbParam` is async, so it injects a **Promise** rather than the resolved value — the surrounding resolution has to stay synchronous:
+
+```typescript
+onReady(
+  @localStorageParam('theme') theme: string,
+  @indexedDbParam('draft') draftPromise: Promise<string>
+) {
+  this.applyTheme(theme);
+  draftPromise.then(d => this.restoreDraft(d));
+}
+```
+
+### @fetchParam
+A minimal fetch — no abort-on-disconnect, no `abortPrevious`, no `filter` (reach for `@fetch`/`@fetchManual` + `@fetchPromise` when you need those). It injects a **Promise** that resolves to the parsed JSON/text body, or rejects with an `Error` on a non-OK status.
+
+```typescript
+@onConnectedAfter
+async onReady(@fetchParam('/api/products/1') p: Promise<Product>) {
+  this.product = await p;
+}
+
+// url/init accept (currentThis, helper) => ... callbacks too, same shape as @fetch's factories —
+// handy for referencing instance fields to build a dynamic URL or body.
+@addEventListener('#save', 'click')
+async onSave(@fetchParam(
+  (self) => `/api/products/${self.productId}`,
+  (self) => ({ method: 'POST', body: JSON.stringify({ qty: self.qty }) })
+) p: Promise<any>) {
+  await p;
+}
+```
+
+### @swcAppRouter / @swcAppSimpleApplication / @swcAppHost
+Documented above alongside `@hostSet`/`@helperSet` — these just hand you a context reference (the `Router`, the DI container, or the `SwcApp` host element itself), they don't compute anything the way the rest of this section's decorators do.
+
+## 💾 Persisted State (@localStorage, @sessionStorage, @cookie, @indexedDb, @persistState)
+
+Field or method decorator that mirrors a value to a storage backend. Survives disconnect/reconnect and page reloads — the whole point is that **element lifecycle never clears it**; only you do (see "Removing a key" below).
+
+```typescript
+class Settings extends HTMLElement {
+  // Field — bare key defaults to the field name; the stored value wins over the initializer on reconnect
+  @localStorage theme: string = 'dark';
+
+  // Explicit key
+  @sessionStorage('draft-id') draftId?: string;
+
+  @cookie('session-token', { maxAge: 3600, sameSite: 'Strict' })
+  token?: string;
+
+  // Method — persists the return value (JSON-serialized) each time it runs
+  @localStorage('last-search')
+  search(q: string) { return q; }
+}
+```
+
+- **Field**: getter/setter. Reading re-hydrates from storage on first access; assigning writes through. Assigning `undefined` **removes** the key (and clears the in-memory value too).
+- **Method**: the return value is persisted after the method runs (`valueKey` picks one field out of an object return).
+- Backends: `local` / `session` / `cookie` (sync) and `indexeddb` (async). The generic form is `@persistState(key?, { storage, ... })`; `@localStorage`/`@sessionStorage`/`@cookie`/`@indexedDb` are storage-fixed aliases.
+- `@indexedDb` on a field: reading can't `await`, so the first read returns the initializer immediately and the stored value lands right after (a console warning flags this once per class) — prefer calling `persistReadAsync` directly, or a `Promise`-typed field, for async backends.
+- Options: `valueKey`, `serialize`/`deserialize` (default `JSON.stringify`/`JSON.parse`); `cookie` also takes `path`/`domain`/`maxAge`/`expires`/`secure`/`sameSite`.
+
+**Removing a key**
+```typescript
+class Settings extends HTMLElement {
+  @localStorage theme: string = 'dark';
+
+  @removeLocalStorage('theme')
+  clearTheme() {}
+}
+```
+- `@removeLocalStorage` / `@removeSessionStorage` / `@removeCookie` / `@removeIndexedDb` (method-only) — call them, or just assign `undefined` to the field directly (`this.theme = undefined`), which does the same thing and also clears the live value.
+- Generic form: `@removePersistState(key?, options?)`.
+
+**Direct function access** (no decorator needed) — for a plain method body, or the async backend:
+```typescript
+import { persistRead, persistWrite, persistRemove, persistReadAsync, persistWriteAsync, persistRemoveAsync } from '@dooboostore/simple-web-component';
+
+const cached = persistRead(this, 'theme', { storage: 'local' });
+const draft = await persistReadAsync(this, 'draft', { storage: 'indexeddb' });
+```
+
 ## 💧 @property Hydration Rules
 
 - Attach bare `@property` (no args) to a field to mark it as an SSR hydration target.

package/dist/cjs/decorators/addEventListener.js

@@ -920,6 +920,21 @@ __export(addEventListener_exports, {
   eventTransitionstartMutationShadow: () => eventTransitionstartMutationShadow,
   eventTransitionstartShadow: () => eventTransitionstartShadow,
   eventTransitionstartWindow: () => eventTransitionstartWindow,
+  eventVisibilitychange: () => eventVisibilitychange,
+  eventVisibilitychangeAll: () => eventVisibilitychangeAll,
+  eventVisibilitychangeAppHost: () => eventVisibilitychangeAppHost,
+  eventVisibilitychangeDelegate: () => eventVisibilitychangeDelegate,
+  eventVisibilitychangeDelegateAll: () => eventVisibilitychangeDelegateAll,
+  eventVisibilitychangeDelegateLight: () => eventVisibilitychangeDelegateLight,
+  eventVisibilitychangeDelegateShadow: () => eventVisibilitychangeDelegateShadow,
+  eventVisibilitychangeDocument: () => eventVisibilitychangeDocument,
+  eventVisibilitychangeLight: () => eventVisibilitychangeLight,
+  eventVisibilitychangeMutation: () => eventVisibilitychangeMutation,
+  eventVisibilitychangeMutationAll: () => eventVisibilitychangeMutationAll,
+  eventVisibilitychangeMutationLight: () => eventVisibilitychangeMutationLight,
+  eventVisibilitychangeMutationShadow: () => eventVisibilitychangeMutationShadow,
+  eventVisibilitychangeShadow: () => eventVisibilitychangeShadow,
+  eventVisibilitychangeWindow: () => eventVisibilitychangeWindow,
   eventWheel: () => eventWheel,
   eventWheelAll: () => eventWheelAll,
   eventWheelAppHost: () => eventWheelAppHost,
@@ -2005,6 +2020,22 @@ const eventToggleAll = toggleAliases.all;
 const eventToggleAppHost = toggleAliases.appHost;
 const eventToggleWindow = toggleAliases.window;
 const eventToggleDocument = toggleAliases.document;
+const visibilitychangeAliases = makeTypedEventAliases("visibilitychange");
+const eventVisibilitychange = visibilitychangeAliases.base;
+const eventVisibilitychangeDelegateLight = visibilitychangeAliases.delegateLight;
+const eventVisibilitychangeDelegateShadow = visibilitychangeAliases.delegateShadow;
+const eventVisibilitychangeDelegateAll = visibilitychangeAliases.delegateAll;
+const eventVisibilitychangeDelegate = visibilitychangeAliases.delegate;
+const eventVisibilitychangeMutationLight = visibilitychangeAliases.mutationLight;
+const eventVisibilitychangeMutationShadow = visibilitychangeAliases.mutationShadow;
+const eventVisibilitychangeMutationAll = visibilitychangeAliases.mutationAll;
+const eventVisibilitychangeMutation = visibilitychangeAliases.mutation;
+const eventVisibilitychangeLight = visibilitychangeAliases.light;
+const eventVisibilitychangeShadow = visibilitychangeAliases.shadow;
+const eventVisibilitychangeAll = visibilitychangeAliases.all;
+const eventVisibilitychangeAppHost = visibilitychangeAliases.appHost;
+const eventVisibilitychangeWindow = visibilitychangeAliases.window;
+const eventVisibilitychangeDocument = visibilitychangeAliases.document;
 const getAddEventListenerMetadata = (target) => {
   const constructor = typeof target === "function" ? target : target.constructor;
   return import_core.ReflectUtils.findAllMetadata(ADD_EVENT_LISTENER_METADATA_KEY, constructor).flat();
@@ -2054,16 +2085,12 @@ class EventListenerLifeCycler {
       if (options.stopPropagation) event2.stopPropagation();
       if (options.stopImmediatePropagation) event2.stopImmediatePropagation();
       if (options.preventDefault) event2.preventDefault();
-      const currentHostSet = import_Utils.SwcUtils.getHostSet(inst);
-      const legacyArgs = [event2, { currentHostSet, $matchedElement: matchedElement }, { event: event2, ...currentHostSet, $el: target, $root: target }];
-      const currentHelperSet = import_Utils.SwcUtils.getHelperSet(currentWin);
-      const currentHelperHostSet = { ...currentHelperSet, ...currentHostSet, $this: inst };
+      const common = (0, import_parameter.buildCommonKindValues)(inst, currentWin);
+      const legacyArgs = [event2, { currentHostSet: common.hostSet, $matchedElement: matchedElement }, { event: event2, ...common.hostSet, $el: target, $root: target }];
       const buildArgs = (beforeReturn) => (0, import_parameter.buildSwcParameterArgs)(inst, meta.propertyKey, {
+        ...common,
         eventObject: event2,
         matchedElement,
-        hostSet: currentHostSet,
-        helperHostSet: currentHelperHostSet,
-        helperSet: currentHelperSet,
         eventBeforeReturn: beforeReturn
       }, legacyArgs);
       let args = buildArgs(void 0);
@@ -2199,16 +2226,12 @@ class EventListenerLifeCycler {
               if (m.options.stopPropagation) event2.stopPropagation();
               if (m.options.stopImmediatePropagation) event2.stopImmediatePropagation();
               if (m.options.preventDefault) event2.preventDefault();
-              const hs = import_Utils.SwcUtils.getHostSet(inst);
-              const legacyArgs = [event2, { ...hs, $matchedElement: matchedEl }, { event: event2, ...hs, $el: matchedEl, $root: br }];
-              const helperSetForMatch = import_Utils.SwcUtils.getHelperSet(currentWin);
-              const helperHostSetForMatch = { ...helperSetForMatch, ...hs, $this: inst };
+              const common = (0, import_parameter.buildCommonKindValues)(inst, currentWin);
+              const legacyArgs = [event2, { ...common.hostSet, $matchedElement: matchedEl }, { event: event2, ...common.hostSet, $el: matchedEl, $root: br }];
               const buildArgs = (beforeReturn) => (0, import_parameter.buildSwcParameterArgs)(inst, m.propertyKey, {
+                ...common,
                 eventObject: event2,
                 matchedElement: matchedEl,
-                hostSet: hs,
-                helperHostSet: helperHostSetForMatch,
-                helperSet: helperSetForMatch,
                 eventBeforeReturn: beforeReturn
               }, legacyArgs);
               let args = buildArgs(void 0);