@alwatr/action 9.12.0 → 9.14.0

package/src/delegate.ts

@@ -0,0 +1,315 @@
+/**
+ * @file delegate.ts
+ *
+ * Global Event Delegation engine for `@alwatr/action`.
+ *
+ * ## Why delegation instead of per-element listeners?
+ *
+ * The classic directive approach attaches one `addEventListener` per element.
+ * With 100 buttons on a page, that means 100 listener registrations at boot
+ * time — O(N) initialization cost, O(N) memory for listener references, and
+ * zero support for elements added after bootstrap.
+ *
+ * This module implements the **Qwik-inspired global delegation** pattern:
+ * - A single listener per event type is attached to `document.body` with
+ *   `capture: true` (so it fires even for non-bubbling events).
+ * - When an event fires, the handler walks up the DOM from `event.target`
+ *   using `closest()` to find the nearest element with an `on-action`
+ *   attribute whose event type matches.
+ * - Modifiers and payload resolvers run in the same pipeline as before.
+ * - `dispatchAction` is called with the resolved payload.
+ *
+ * ## Complexity
+ *
+ * | Metric          | Per-element listeners | Global delegation |
+ * | --------------- | --------------------- | ----------------- |
+ * | Boot time       | O(N elements)         | O(1) — 1 loop     |
+ * | Memory          | O(N listeners)        | O(1) — 1 handler  |
+ * | Dynamic content | Requires re-bootstrap | Works out-of-box  |
+ * | `once` modifier | Native option         | Manual tracking   |
+ *
+ * ## Trade-offs vs. the directive approach
+ *
+ * - `passive` is not supported as a per-element option (all delegated listeners
+ *   are non-passive so that `prevent` can call `preventDefault()`).
+ * - `stop` stops further bubbling but the delegation handler has already
+ *   captured the event at `body` level — it does not prevent other delegation
+ *   handlers from running on the same element.
+ * - `once` is emulated by delete attribute elements after first fire.
+ */
+
+import {internalChannel_, logger_} from './lib.js';
+import {modifierRegistry, payloadRegistry} from './registry.js';
+
+// ─── Syntax Parser ────────────────────────────────────────────────────────────
+
+/**
+ * Parses the `on-action` attribute value into its three segments.
+ *
+ * Full syntax: `eventType[.modifier…]->actionId[:payload]`
+ *
+ * | Capture group | Matches                                     | Example              |
+ * | ------------- | ------------------------------------------- | -------------------- |
+ * | 1             | Event type + optional dot-chained modifiers | `click.prevent.once` |
+ * | 2             | Action identifier                           | `open-drawer`        |
+ * | 3             | Optional payload token or literal           | `main` / `$value`    |
+ *
+ * @example
+ * ```
+ * 'click.prevent.once->open-drawer:main' → ['click.prevent.once', 'open-drawer', 'main']
+ * 'input->search-query:$value'           → ['input',              'search-query', '$value']
+ * 'submit.prevent->submit-form'          → ['submit.prevent',     'submit-form',  undefined]
+ * ```
+ */
+const syntaxRegex = /^([a-z0-9.-]+)->([a-z0-9-]+)(?::(.+))?$/;
+
+// ─── Parsed Action Descriptor ─────────────────────────────────────────────────
+
+/**
+ * Parsed and cached representation of a single `on-action` attribute value.
+ *
+ * Caching avoids re-parsing the same attribute string on every event fire.
+ * The cache is keyed by the raw attribute string so identical values share
+ * the same descriptor object.
+ */
+interface ActionDescriptor {
+  /** The DOM event type to listen for (e.g. `'click'`, `'input'`). */
+  readonly eventType: string;
+  /** Set of active modifier names (e.g. `{'prevent', 'once'}`). */
+  readonly modifiers: ReadonlySet<string>;
+  /** The action identifier dispatched to `onAction` subscribers. */
+  readonly actionId: string;
+  /** Raw payload token from the attribute (literal string or `$`-resolver key). */
+  readonly payload: string | undefined;
+}
+
+/**
+ * LRU-style cache for parsed `on-action` attribute values.
+ *
+ * Attribute strings are typically repeated across many elements (e.g. every
+ * "add to cart" button shares the same `on-action` value). Caching the parsed
+ * descriptor avoids redundant regex work on every event.
+ *
+ * Using a plain `Map` here is intentional — attribute strings are short-lived
+ * keys and the map size is bounded by the number of distinct `on-action` values
+ * in the page, which is typically small.
+ *
+ * @internal
+ */
+const descriptorCache__ = new Map<string, ActionDescriptor | null>();
+
+/**
+ * Parses an `on-action` attribute value into an `ActionDescriptor`.
+ *
+ * Returns `null` when the syntax is invalid. Results are cached by the raw
+ * attribute string so repeated calls for the same value are O(1).
+ *
+ * @internal
+ */
+function parseDescriptor__(attributeValue: string): ActionDescriptor | null {
+  logger_.logMethodArgs?.('parseDescriptor__', {attributeValue});
+
+  const cached = descriptorCache__.get(attributeValue);
+  // Explicit `undefined` check: `null` means "already parsed and invalid".
+  if (cached !== undefined) return cached;
+
+  const match = attributeValue.match(syntaxRegex);
+  if (!match) {
+    logger_.accident('parseDescriptor__', 'invalid_syntax', {attributeValue});
+    descriptorCache__.set(attributeValue, null);
+    return null;
+  }
+
+  const [eventType, ...modifierList] = match[1].split('.');
+  if (!eventType) {
+    logger_.accident('parseDescriptor__', 'missing_event_type', {attributeValue});
+    descriptorCache__.set(attributeValue, null);
+    return null;
+  }
+
+  const modifiers = new Set(modifierList);
+  const actionId = match[2];
+  const payload: string | undefined = match[3];
+
+  const descriptor: ActionDescriptor = {
+    eventType,
+    modifiers,
+    actionId,
+    payload,
+  };
+
+  descriptorCache__.set(attributeValue, descriptor);
+  return descriptor;
+}
+
+// ─── Core Delegation Handler ──────────────────────────────────────────────────
+
+const onActionAttrib__ = 'on-action';
+/**
+ * Central event handler attached to `document.body` for every delegated event type.
+ *
+ * Execution flow for each incoming event:
+ * 1. Walk up from `event.target` to find the nearest element with an
+ *    `on-action` attribute whose event type matches the current event.
+ * 2. Parse (or retrieve from cache) the `ActionDescriptor` for that attribute.
+ * 3. Run each modifier in order; if any returns `false`, abort.
+ * 4. Resolve the payload token (literal or `$`-resolver).
+ * 5. Call `dispatchAction(actionId, payload)`.
+ *
+ * @internal
+ */
+function handleDelegatedEvent__(event: Event): void {
+  const eventType = event.type;
+  logger_.logMethodArgs?.('handleDelegatedEvent__', {eventType});
+
+  // Walk up the DOM to find the closest element with a matching on-action attribute.
+  // We use `closest` on the composedPath target to support Shadow DOM correctly.
+  const target = event.target as Element | null;
+  if (!target) return;
+
+  // Find the nearest ancestor (or self) that has an on-action attribute
+  const actionElement = target.closest?.(`[${onActionAttrib__}^=${eventType}]`);
+  if (!actionElement) return;
+
+  const attributeValue = actionElement.getAttribute?.(onActionAttrib__)?.trim();
+  if (!attributeValue) {
+    logger_.accident('handleDelegatedEvent__', 'empty_attribute', {eventType, attributeValue, actionElement});
+    return;
+  }
+
+  if (!(actionElement instanceof HTMLElement)) {
+    logger_.accident('handleDelegatedEvent__', 'target_not_html_element', {eventType, attributeValue, actionElement});
+    return;
+  }
+
+  const descriptor = parseDescriptor__(attributeValue);
+  if (!descriptor) {
+    logger_.accident('handleDelegatedEvent__', 'invalid_attribute', {eventType, attributeValue, actionElement});
+    return;
+  }
+
+  if (descriptor.eventType !== eventType) return;
+
+  logger_.logMethodArgs?.('handleDelegatedEvent__.action', descriptor);
+
+  // Step 1: handle once modifier
+  if (descriptor.modifiers.has('once')) {
+    actionElement.removeAttribute(onActionAttrib__); // remove on-action to prevent repeat the action
+    descriptorCache__.delete(attributeValue); // free memory for once
+  }
+
+  // Step 2: run modifiers
+  for (const modifier of descriptor.modifiers) {
+    if (modifier === 'once') continue; // handled separately
+    const handler = modifierRegistry.get(modifier);
+    if (!handler) {
+      logger_.accident('handleDelegatedEvent__', 'unknown_modifier', {modifier, attributeValue});
+      return; // unknown modifier — abort to avoid silent misbehaviour
+    }
+    if (handler(event, actionElement) === false) return;
+  }
+
+  // Step 3: resolve payload
+  let payload: unknown = descriptor.payload;
+  if (payload) {
+    const resolver = payloadRegistry.get(payload as string);
+    if (resolver) payload = resolver(event, actionElement);
+  }
+
+  // Step 4: dispatch
+  internalChannel_.dispatch(descriptor.actionId, payload);
+}
+
+// ─── Setup ────────────────────────────────────────────────────────────────────
+
+/**
+ * The set of event types currently delegated to `document.body`.
+ *
+ * Tracked so that `setupActionDelegation` is idempotent — calling it multiple
+ * times with the same event types does not register duplicate listeners.
+ *
+ * @internal
+ */
+const delegatedEventTypes__ = new Set<string>();
+
+/**
+ * Default DOM event types that cover the vast majority of interactive elements.
+ *
+ * - `click` — buttons, links, checkboxes, custom interactive elements
+ * - `submit` — form submission
+ * - `input` — live text input, range sliders
+ * - `change` — select boxes, checkboxes, radio buttons (fires on commit)
+ *
+ * Pass additional types to `setupActionDelegation` when your app uses other
+ * events (e.g. `'keydown'`, `'pointerup'`).
+ */
+export const DEFAULT_DELEGATED_EVENTS: readonly string[] = ['click', 'submit', 'input', 'change'];
+
+/**
+ * Registers global event delegation for `on-action` attributes.
+ *
+ * Attaches a single `capture`-phase listener on `document.body` for each
+ * event type in `eventTypes`. All `on-action` processing — modifier execution,
+ * payload resolution, and `dispatchAction` — happens inside that one handler.
+ *
+ * **Call this once at application bootstrap**, before any user interaction.
+ * Subsequent calls with the same event types are no-ops (idempotent).
+ *
+ * ### Why `capture: true`?
+ *
+ * Capture-phase listeners fire before bubble-phase listeners and also catch
+ * events that do not bubble (e.g. `focus`, `blur`). This ensures the delegation
+ * handler always runs, even when a child element calls `stopPropagation()`.
+ *
+ * ### Dynamic content
+ *
+ * Because the listener lives on `document.body`, any element added to the DOM
+ * after this call — via `innerHTML`, `lit-html`, a framework renderer, or
+ * server-sent HTML — is automatically covered. No re-bootstrap is needed.
+ *
+ * @param eventTypes - Event types to delegate. Defaults to `DEFAULT_DELEGATED_EVENTS`.
+ *
+ * @example — minimal bootstrap
+ * ```ts
+ * import {setupActionDelegation, onAction} from '@alwatr/action';
+ *
+ * // One call activates the entire page.
+ * setupActionDelegation();
+ *
+ * onAction('open-drawer', (panel) => openDrawer(panel));
+ * ```
+ *
+ * @example — with extra event types
+ * ```ts
+ * import {setupActionDelegation, DEFAULT_DELEGATED_EVENTS} from '@alwatr/action';
+ *
+ * setupActionDelegation([...DEFAULT_DELEGATED_EVENTS, 'keydown', 'pointerup']);
+ * ```
+ */
+export function setupActionDelegation(eventTypes: readonly string[] = DEFAULT_DELEGATED_EVENTS): void {
+  logger_.logMethodArgs?.('setupActionDelegation', {eventTypes});
+
+  for (const eventType of eventTypes) {
+    if (delegatedEventTypes__.has(eventType)) continue; // already registered — skip
+    delegatedEventTypes__.add(eventType);
+    // capture: true — fires before bubble-phase listeners and catches non-bubbling events.
+    document.body.addEventListener(eventType, handleDelegatedEvent__, {capture: true});
+  }
+}
+
+/**
+ * Removes all global delegation listeners registered by `setupActionDelegation`.
+ *
+ * Useful in test environments where each test needs a clean slate, or in
+ * micro-frontend setups where a sub-app is unmounted.
+ *
+ * After calling this, `setupActionDelegation` can be called again to re-register.
+ */
+export function teardownActionDelegation(): void {
+  logger_.logMethod?.('teardownActionDelegation');
+  for (const eventType of delegatedEventTypes__) {
+    document.body.removeEventListener(eventType, handleDelegatedEvent__, {capture: true});
+  }
+  delegatedEventTypes__.clear();
+  descriptorCache__.clear();
+}

package/src/lib.ts

@@ -1,28 +1,5 @@
 import {createLogger} from '@alwatr/logger';
-import {createEventSignal} from '@alwatr/signal';
-
-/**
- * The shape of every payload carried by the internal action signal.
- *
- * `actionId` identifies which action was dispatched (e.g. `'open-drawer'`).
- * `actionPayload` is the optional value attached to the action — defaults to
- * `string` but can be narrowed to any type via the generic parameter `T`.
- *
- * @template T The type of the action payload. Defaults to `string`.
- *
- * @example
- * ```ts
- * // Typed payload for a cart action
- * const payload: ActionSignalPayload<{productId: number; qty: number}> = {
- *   actionId: 'add-to-cart',
- *   actionPayload: {productId: 42, qty: 1},
- * };
- * ```
- */
-export interface ActionSignalPayload<T = string> {
-  actionId: string;
-  actionPayload?: T;
-}
+import {createChannelSignal} from '@alwatr/signal';
 
 /**
  * Module-scoped logger for `@alwatr/action`.
@@ -33,15 +10,16 @@ export interface ActionSignalPayload<T = string> {
 export const logger_ = createLogger('alwatr-action');
 
 /**
- * The single shared event signal that carries every dispatched action.
+ * The action channel — a `ChannelSignal` strictly typed by `ActionRecord`.
  *
- * All `ActionDirective` instances write to this signal via `dispatchAction`,
- * and all `onAction` subscriptions read from it. Using one central signal keeps
- * the pub/sub wiring minimal and makes the action flow easy to trace.
+ * Only action names declared in `ActionRecord` (via declaration merging) are
+ * accepted at compile time. Passing an unknown action name to `onAction` or
+ * `dispatchAction` is a **compile error** — there is no string fallback.
  *
- * The payload is typed as `ActionSignalPayload<unknown>` at the signal level;
- * individual subscribers narrow the type through the `onAction` generic.
+ * Uses `ChannelSignal` for O(1) routing: dispatching action `'A'` performs a
+ * single `Map.get('A')` lookup and invokes only the handlers registered for
+ * that specific action — never handlers for `'B'`, `'C'`, etc.
  *
  * @internal — not part of the public API; use `onAction` / `dispatchAction` instead.
  */
-export const internalSignal_ = createEventSignal<ActionSignalPayload<unknown>>({name: 'alwatr-action'});
+export const internalChannel_ = createChannelSignal<Record<string, unknown>>({name: 'alwatr-action'});

package/src/main.ts

@@ -1,15 +1,54 @@
 /**
  * @alwatr/action — Declarative DOM action-dispatch for Unidirectional Data Flow.
  *
- * Public API surface:
+ * ## Activating `on-action` attributes
+ *
+ * Call `setupActionDelegation()` once at bootstrap. A single capture-phase
+ * listener on `document.body` handles every `on-action` element — including
+ * elements added dynamically after bootstrap — with O(1) initialization cost.
+ *
+ * ```ts
+ * import {setupActionDelegation, onAction} from '@alwatr/action';
+ *
+ * setupActionDelegation();
+ * onAction('open-drawer', (panel) => openDrawer(panel));
+ * ```
+ *
+ * ## Programmatic dispatch
+ *
+ * ```ts
+ * import {dispatchAction} from '@alwatr/action';
+ *
+ * dispatchAction('navigate', '/dashboard');
+ * ```
+ *
+ * ## Registering typed actions
+ *
+ * Extend `ActionRecord` via declaration merging to get full type safety:
+ *
+ * ```ts
+ * // src/action-record.ts
+ * declare module '@alwatr/action' {
+ *   interface ActionRecord {
+ *     'open-drawer': string;
+ *     'add-to-cart': {productId: number; qty: number};
+ *     'logout': void;
+ *   }
+ * }
+ * ```
+ *
+ * ## Public API
+ *
+ * - `ActionRecord` — extend this interface to register typed actions
+ * - `setupActionDelegation` / `teardownActionDelegation` — global delegation lifecycle
+ * - `DEFAULT_DELEGATED_EVENTS` — default event types covered by delegation
  * - `onAction` / `dispatchAction` — subscribe to and dispatch named actions
- * - `registerActionDirective` — opt-in to `on-action` HTML attribute support
- * - `registerPageIdDirective` — opt-in to `page-id` HTML attribute support
- * - `registerModifier` / `registerPayloadResolver` — extend the directive syntax
- * - `ActionDirective` / `PageIdDirective` — directive classes (advanced use)
- * - `ActionSignalPayload` — payload type carried by the internal signal
+ * - `registerModifier` / `registerPayloadResolver` — extend the attribute syntax
+ *
+ * ## Page identity
+ *
+ * For page-ready signals in SSG/SSR apps, use `@alwatr/page-ready` instead.
  */
+export type {ActionRecord} from './action-record.js';
 export * from './method.js';
-export * from './directive.js';
-export * from './page-id.js';
-export type {ActionSignalPayload} from './lib.js';
+export * from './delegate.js';

package/src/method.ts

@@ -1,6 +1,8 @@
-import {internalSignal_, logger_} from './lib.js';
+import type {Awaitable} from '@alwatr/type-helper';
+import {internalChannel_, logger_} from './lib.js';
 import type {SubscribeResult} from '@alwatr/signal';
 import {modifierRegistry, payloadRegistry, type ModifierHandler, type PayloadResolver} from './registry.js';
+import type {ActionRecord} from './action-record.js';
 
 // Re-export extension types so consumers can import them from the package root.
 export type {ModifierHandler, PayloadResolver};
@@ -10,82 +12,106 @@ export type {ModifierHandler, PayloadResolver};
 /**
  * Subscribes to a named action dispatched anywhere in the application.
  *
- * The handler is invoked every time `dispatchAction(actionId, payload)` is
- * called — whether from an `on-action` directive or from code — and the
- * `actionId` matches. Multiple subscribers for the same `actionId` are all
- * notified in subscription order.
+ * `actionId` must be a key of `ActionRecord`. The handler's `payload` parameter
+ * is automatically typed to the corresponding `ActionRecord` value — no manual
+ * generic annotation needed:
  *
- * The generic parameter `T` narrows the type of the received payload.
- * Defaults to `string`, which covers the common case of attribute-driven
- * literal payloads.
+ * ```ts
+ * // ActionRecord declares: 'add-to-cart': {productId: number; qty: number}
+ * onAction('add-to-cart', (item) => {
+ *   cartService.add(item.productId, item.qty); // fully typed, no `!` needed
+ * });
+ * ```
  *
- * @param actionId - The action identifier to listen for (e.g. `'open-drawer'`).
- * @param handler  - Callback invoked with the resolved payload each time the
- *                   action is dispatched. `payload` is `undefined` when the
- *                   action was dispatched without a value.
- * @returns A `SubscribeResult` with an `unsubscribe()` method for cleanup.
+ * Passing an action name not declared in `ActionRecord` is a **compile error**.
+ * Register new actions by extending `ActionRecord` via declaration merging:
  *
- * @example — basic string payload
  * ```ts
- * import {onAction} from '@alwatr/action';
+ * // src/action-record.ts
+ * declare module '@alwatr/action' {
+ *   interface ActionRecord {
+ *     'open-drawer': string;
+ *   }
+ * }
+ * ```
  *
- * const sub = onAction('open-drawer', (panel) => {
- *   openDrawer(panel); // panel === 'settings'
- * });
+ * Internally delegates to `ChannelSignal.on()` for **O(1) routing** — dispatching
+ * action `'A'` never invokes handlers registered for action `'B'`.
  *
- * // Stop listening when the component is destroyed
- * sub.unsubscribe();
- * ```
+ * @param actionId - A key of `ActionRecord`.
+ * @param handler  - Callback invoked with the typed payload on each dispatch.
+ * @returns A `SubscribeResult` with an `unsubscribe()` method for cleanup.
  *
- * @example — typed object payload
+ * @example
  * ```ts
  * import {onAction} from '@alwatr/action';
  *
- * onAction<{productId: number; qty: number}>('add-to-cart', (item) => {
- *   cartService.add(item!.productId, item!.qty);
+ * const sub = onAction('page-ready', (pageId) => {
+ *   router.setPage(pageId); // pageId: string — inferred from ActionRecord
  * });
+ *
+ * sub.unsubscribe(); // stop listening when no longer needed
  * ```
  */
-export function onAction<T = string>(actionId: string, handler: (payload?: T) => void): SubscribeResult {
+export function onAction<K extends keyof ActionRecord>(
+  actionId: K,
+  handler: (payload: ActionRecord[K]) => Awaitable<void>,
+): SubscribeResult {
   logger_.logMethodArgs?.('onAction', {actionId});
-  return internalSignal_.subscribe((signal) => {
-    if (signal.actionId === actionId) {
-      logger_.logMethodArgs?.('onAction.invoke', {actionId, payload: signal.actionPayload});
-      handler(signal.actionPayload as T);
-    }
-  });
+  return internalChannel_.on(actionId, handler as (payload: unknown) => Awaitable<void>);
 }
 
 /**
  * Dispatches a named action to all `onAction` subscribers with a matching `actionId`.
  *
- * This is the programmatic counterpart to the `on-action` HTML attribute.
- * Use it when you need to trigger an action from code rather than from a DOM
- * event (e.g. after an async operation completes, or from a service layer).
+ * `actionId` must be a key of `ActionRecord`. The `payload` parameter is
+ * automatically typed — passing the wrong type is a **compile error**:
  *
- * The generic parameter `T` types the payload. Omit it to default to `string`.
+ * ```ts
+ * // ActionRecord declares: 'add-to-cart': {productId: number; qty: number}
+ * dispatchAction('add-to-cart', {productId: 42, qty: 1}); // ✅
+ * dispatchAction('add-to-cart', 'wrong');                  // ❌ compile error
+ * dispatchAction('unknown-action', 'x');                   // ❌ compile error
+ * ```
  *
- * @param actionId     - The action identifier (e.g. `'navigate'`).
- * @param actionPayload - Optional value passed to every matching subscriber.
+ * Register new actions by extending `ActionRecord` via declaration merging:
  *
- * @example — dispatch without payload
  * ```ts
- * import {dispatchAction} from '@alwatr/action';
- *
- * dispatchAction('logout');
+ * // src/action-record.ts
+ * declare module '@alwatr/action' {
+ *   interface ActionRecord {
+ *     'navigate': string;
+ *     'logout': void;
+ *   }
+ * }
  * ```
  *
- * @example — dispatch with a typed payload
+ * Use `dispatchAction` when triggering an action from code — e.g. after an
+ * async operation, from a service layer, or in tests. For DOM-driven actions,
+ * use the `on-action` HTML attribute with `setupActionDelegation`.
+ *
+ * @param actionId      - A key of `ActionRecord`.
+ * @param actionPayload - The payload; type is enforced by `ActionRecord`.
+ *
+ * @example — with payload
  * ```ts
  * import {dispatchAction} from '@alwatr/action';
  *
+ * dispatchAction('page-ready', 'home');
  * dispatchAction('navigate', '/dashboard');
- * dispatchAction<{code: number}>('show-error', {code: 404});
+ * ```
+ *
+ * @example — void payload (no second argument)
+ * ```ts
+ * dispatchAction('logout');
  * ```
  */
-export function dispatchAction<T = string>(actionId: string, actionPayload?: T): void {
+export function dispatchAction<K extends keyof ActionRecord>(
+  ...args: ActionRecord[K] extends void | undefined ? [actionId: K] : [actionId: K, actionPayload: ActionRecord[K]]
+): void {
+  const [actionId, actionPayload] = args;
   logger_.logMethodArgs?.('dispatchAction', {actionId, actionPayload});
-  internalSignal_.dispatch({actionId, actionPayload});
+  internalChannel_.dispatch(actionId, actionPayload);
 }
 
 // ─── Extension API ────────────────────────────────────────────────────────────
@@ -97,22 +123,20 @@ export function dispatchAction<T = string>(actionId: string, actionPayload?: T):
  * (e.g. `click.mymod->action-id`). Its handler runs before the payload is
  * resolved and the action is dispatched. Returning `false` cancels the dispatch.
  *
- * Built-in modifiers (`prevent`, `stop`, `validate`, `once`, `passive`) are
- * always available. This function lets you add domain-specific ones.
+ * Built-in modifiers (`prevent`, `stop`, `validate`, `once`) are always
+ * available. This function lets you add domain-specific ones.
  *
  * Registering the same name twice logs an accident and overwrites the previous
  * handler — avoid duplicate registrations in production code.
  *
  * @param name    - The modifier token (lowercase, no dots or arrows).
- * @param handler - The `ModifierHandler` function bound to the directive instance.
+ * @param handler - A `ModifierHandler` receiving `(event, element)`.
  *
  * @example — a `confirm` modifier that shows a browser dialog
  * ```ts
  * import {registerModifier} from '@alwatr/action';
  *
- * registerModifier('confirm', function () {
- *   return window.confirm('Are you sure?');
- * });
+ * registerModifier('confirm', () => window.confirm('Are you sure?'));
  * ```
  * ```html
  * <button on-action="click.confirm->delete-item:42">Delete</button>
@@ -131,7 +155,7 @@ export function registerModifier(name: string, handler: ModifierHandler): void {
  *
  * A payload resolver is a colon-suffixed token in the attribute value
  * (e.g. `click->action-id:$mytoken`). Its function is called at dispatch time
- * with the directive instance as `this` and the DOM event as the argument.
+ * with an `ActionContext` as `this` and the DOM event as the argument.
  * The return value becomes the `actionPayload` passed to `onAction` subscribers.
  *
  * Built-in resolvers (`$value`, `$formdata`) are always available. This function
@@ -141,29 +165,19 @@ export function registerModifier(name: string, handler: ModifierHandler): void {
  * resolver — avoid duplicate registrations in production code.
  *
  * @param name     - The resolver token (should start with `$` by convention).
- * @param resolver - The `PayloadResolver` function bound to the directive instance.
+ * @param resolver - A `PayloadResolver` receiving `(event, element)`.
  *
  * @example — a `$checked` resolver for checkbox state
  * ```ts
  * import {registerPayloadResolver} from '@alwatr/action';
  *
- * registerPayloadResolver('$checked', function () {
- *   return (this.element_ as HTMLInputElement).checked;
+ * registerPayloadResolver('$checked', (_event, element) => {
+ *   return (element as HTMLInputElement).checked;
  * });
  * ```
  * ```html
  * <input type="checkbox" on-action="change->toggle-feature:$checked" />
  * ```
- *
- * @example — a `$dataset-id` resolver for data attributes
- * ```ts
- * registerPayloadResolver('$dataset-id', function () {
- *   return (this.element_ as HTMLElement).dataset.id ?? null;
- * });
- * ```
- * ```html
- * <li on-action="click->select-item:$dataset-id" data-id="42">Item</li>
- * ```
  */
 export function registerPayloadResolver(name: string, resolver: PayloadResolver): void {
   logger_.logMethodArgs?.('registerPayloadResolver', {name});