@alwatr/action 9.14.0 → 9.16.0

package/dist/main.js.map

@@ -3,11 +3,11 @@
   "sources": ["../src/lib.ts", "../src/registry.ts", "../src/method.ts", "../src/delegate.ts"],
   "sourcesContent": [
     "import {createLogger} from '@alwatr/logger';\nimport {createChannelSignal} from '@alwatr/signal';\n\n/**\n * Module-scoped logger for `@alwatr/action`.\n * Scoped to `'alwatr-action'` so log lines are easy to filter in the console.\n *\n * @internal\n */\nexport const logger_ = createLogger('alwatr-action');\n\n/**\n * The action channel — a `ChannelSignal` strictly typed by `ActionRecord`.\n *\n * Only action names declared in `ActionRecord` (via declaration merging) are\n * accepted at compile time. Passing an unknown action name to `onAction` or\n * `dispatchAction` is a **compile error** — there is no string fallback.\n *\n * Uses `ChannelSignal` for O(1) routing: dispatching action `'A'` performs a\n * single `Map.get('A')` lookup and invokes only the handlers registered for\n * that specific action — never handlers for `'B'`, `'C'`, etc.\n *\n * @internal — not part of the public API; use `onAction` / `dispatchAction` instead.\n */\nexport const internalChannel_ = createChannelSignal<Record<string, unknown>>({name: 'alwatr-action'});\n",
-    "// ─── Type Definitions ────────────────────────────────────────────────────────\n\n/**\n * A modifier handler used in `on-action` attribute syntax.\n *\n * Receives the triggering DOM `event` and the `element` that owns the\n * `on-action` attribute. Return `true` (or any truthy value) to allow the\n * action to proceed, or `false` to cancel the dispatch.\n *\n * Using explicit parameters instead of `this` binding makes handlers\n * compatible with arrow functions and easier to test in isolation.\n *\n * @example\n * ```ts\n * // A modifier that only allows the action when the element is not disabled\n * const notDisabledHandler: ModifierHandler = (_event, element) => {\n *   return !(element as HTMLButtonElement).disabled;\n * };\n * ```\n */\nexport type ModifierHandler = (event: Event, element: HTMLElement) => boolean;\n\n/**\n * A payload resolver used in `on-action` attribute syntax.\n *\n * Receives the triggering DOM `event` and the `element` that owns the\n * `on-action` attribute. The return value becomes the `actionPayload` passed\n * to `onAction` subscribers. Use this to compute dynamic payloads from DOM state.\n *\n * Using explicit parameters instead of `this` binding makes resolvers\n * compatible with arrow functions and easier to test in isolation.\n *\n * @example\n * ```ts\n * // A resolver that returns the element's dataset id\n * const dataIdResolver: PayloadResolver = (_event, element) => {\n *   return (element as HTMLElement).dataset.id ?? null;\n * };\n * ```\n */\nexport type PayloadResolver = (event: Event, element: HTMLElement) => unknown;\n\n// ─── Registries ──────────────────────────────────────────────────────────────\n\n/**\n * Registry of all named modifier handlers.\n *\n * Keys are modifier names used in the `on-action` attribute syntax\n * (e.g. `click.prevent->action-id`). Values are `ModifierHandler` functions.\n * Populated at module load with built-in modifiers; extended at runtime via\n * `registerModifier`.\n *\n * @internal\n */\nexport const modifierRegistry = new Map<string, ModifierHandler>();\n\n/**\n * Registry of all named payload resolvers.\n *\n * Keys are resolver tokens used in the `on-action` attribute syntax\n * (e.g. `click->action-id:$value`). Values are `PayloadResolver` functions.\n * Populated at module load with built-in resolvers; extended at runtime via\n * `registerPayloadResolver`.\n *\n * @internal\n */\nexport const payloadRegistry = new Map<string, PayloadResolver>();\n\n// ─── Built-in Modifiers ───────────────────────────────────────────────────────\n\n/**\n * `prevent` — calls `event.preventDefault()` before dispatching.\n *\n * Use it to suppress the browser's default behaviour (e.g. form submission,\n * link navigation, context menu).\n *\n * @example `<form on-action=\"submit.prevent->submit-form\">`\n */\nmodifierRegistry.set('prevent', (event) => {\n  event.preventDefault();\n  return true;\n});\n\n/**\n * `validate` — cancels the dispatch if the nearest `<form>` fails validation.\n *\n * Looks for a `<form>` ancestor (or the element itself if it is a form) and\n * calls `checkValidity()`. If the form is invalid the action is not dispatched,\n * allowing native constraint-validation UI to surface errors. If no form is\n * found the dispatch is also cancelled.\n *\n * Pair with `.prevent` on `submit` events to avoid page reloads:\n *\n * @example `<form on-action=\"submit.prevent.validate->submit-form:$formdata\" novalidate>`\n */\nmodifierRegistry.set('validate', (_event, element) => {\n  const form = element instanceof HTMLFormElement ? element : element.closest('form');\n  if (!form) return false;\n  return form.checkValidity();\n});\n\n// ─── Built-in Payload Resolvers ───────────────────────────────────────────────\n\n/**\n * `$value` — resolves to the element's `.value` property at dispatch time.\n *\n * Works with any element that exposes a `value` property: `<input>`,\n * `<textarea>`, `<select>`. Returns `null` for elements without `.value`.\n *\n * @example `<input on-action=\"input->search-query:$value\" />`\n */\npayloadRegistry.set('$value', (_event, element) => {\n  return 'value' in element ? (element as {value: unknown}).value : null;\n});\n\n/**\n * `$formdata` — resolves to a plain object of all fields in the nearest `<form>`.\n *\n * Collects entries via `FormData` and converts them to a `Record<string, FormDataEntryValue>`.\n * Looks for a `<form>` ancestor (or the element itself). Returns `null` when no\n * form is found.\n *\n * @example `<form on-action=\"submit.prevent.validate->submit-form:$formdata\">`\n * ```ts\n * onAction('submit-form', (data) => {\n *   console.log(data); // {username: 'ali', password: '…'}\n * });\n * ```\n */\npayloadRegistry.set('$formdata', (_event, element) => {\n  const form = element instanceof HTMLFormElement ? element : element.closest('form');\n  return form ? Object.fromEntries(new FormData(form).entries()) : null;\n});\n",
-    "import type {Awaitable} from '@alwatr/type-helper';\nimport {internalChannel_, logger_} from './lib.js';\nimport type {SubscribeResult} from '@alwatr/signal';\nimport {modifierRegistry, payloadRegistry, type ModifierHandler, type PayloadResolver} from './registry.js';\nimport type {ActionRecord} from './action-record.js';\n\n// Re-export extension types so consumers can import them from the package root.\nexport type {ModifierHandler, PayloadResolver};\n\n// ─── Core Action API ──────────────────────────────────────────────────────────\n\n/**\n * Subscribes to a named action dispatched anywhere in the application.\n *\n * `actionId` must be a key of `ActionRecord`. The handler's `payload` parameter\n * is automatically typed to the corresponding `ActionRecord` value — no manual\n * generic annotation needed:\n *\n * ```ts\n * // ActionRecord declares: 'add-to-cart': {productId: number; qty: number}\n * onAction('add-to-cart', (item) => {\n *   cartService.add(item.productId, item.qty); // fully typed, no `!` needed\n * });\n * ```\n *\n * Passing an action name not declared in `ActionRecord` is a **compile error**.\n * Register new actions by extending `ActionRecord` via declaration merging:\n *\n * ```ts\n * // src/action-record.ts\n * declare module '@alwatr/action' {\n *   interface ActionRecord {\n *     'open-drawer': string;\n *   }\n * }\n * ```\n *\n * Internally delegates to `ChannelSignal.on()` for **O(1) routing** — dispatching\n * action `'A'` never invokes handlers registered for action `'B'`.\n *\n * @param actionId - A key of `ActionRecord`.\n * @param handler  - Callback invoked with the typed payload on each dispatch.\n * @returns A `SubscribeResult` with an `unsubscribe()` method for cleanup.\n *\n * @example\n * ```ts\n * import {onAction} from '@alwatr/action';\n *\n * const sub = onAction('page-ready', (pageId) => {\n *   router.setPage(pageId); // pageId: string — inferred from ActionRecord\n * });\n *\n * sub.unsubscribe(); // stop listening when no longer needed\n * ```\n */\nexport function onAction<K extends keyof ActionRecord>(\n  actionId: K,\n  handler: (payload: ActionRecord[K]) => Awaitable<void>,\n): SubscribeResult {\n  logger_.logMethodArgs?.('onAction', {actionId});\n  return internalChannel_.on(actionId, handler as (payload: unknown) => Awaitable<void>);\n}\n\n/**\n * Dispatches a named action to all `onAction` subscribers with a matching `actionId`.\n *\n * `actionId` must be a key of `ActionRecord`. The `payload` parameter is\n * automatically typed — passing the wrong type is a **compile error**:\n *\n * ```ts\n * // ActionRecord declares: 'add-to-cart': {productId: number; qty: number}\n * dispatchAction('add-to-cart', {productId: 42, qty: 1}); // ✅\n * dispatchAction('add-to-cart', 'wrong');                  // ❌ compile error\n * dispatchAction('unknown-action', 'x');                   // ❌ compile error\n * ```\n *\n * Register new actions by extending `ActionRecord` via declaration merging:\n *\n * ```ts\n * // src/action-record.ts\n * declare module '@alwatr/action' {\n *   interface ActionRecord {\n *     'navigate': string;\n *     'logout': void;\n *   }\n * }\n * ```\n *\n * Use `dispatchAction` when triggering an action from code — e.g. after an\n * async operation, from a service layer, or in tests. For DOM-driven actions,\n * use the `on-action` HTML attribute with `setupActionDelegation`.\n *\n * @param actionId      - A key of `ActionRecord`.\n * @param actionPayload - The payload; type is enforced by `ActionRecord`.\n *\n * @example — with payload\n * ```ts\n * import {dispatchAction} from '@alwatr/action';\n *\n * dispatchAction('page-ready', 'home');\n * dispatchAction('navigate', '/dashboard');\n * ```\n *\n * @example — void payload (no second argument)\n * ```ts\n * dispatchAction('logout');\n * ```\n */\nexport function dispatchAction<K extends keyof ActionRecord>(\n  ...args: ActionRecord[K] extends void | undefined ? [actionId: K] : [actionId: K, actionPayload: ActionRecord[K]]\n): void {\n  const [actionId, actionPayload] = args;\n  logger_.logMethodArgs?.('dispatchAction', {actionId, actionPayload});\n  internalChannel_.dispatch(actionId, actionPayload);\n}\n\n// ─── Extension API ────────────────────────────────────────────────────────────\n\n/**\n * Registers a custom modifier that can be used in `on-action` attribute syntax.\n *\n * A modifier is a dot-chained token placed after the event type\n * (e.g. `click.mymod->action-id`). Its handler runs before the payload is\n * resolved and the action is dispatched. Returning `false` cancels the dispatch.\n *\n * Built-in modifiers (`prevent`, `stop`, `validate`, `once`) are always\n * available. This function lets you add domain-specific ones.\n *\n * Registering the same name twice logs an accident and overwrites the previous\n * handler — avoid duplicate registrations in production code.\n *\n * @param name    - The modifier token (lowercase, no dots or arrows).\n * @param handler - A `ModifierHandler` receiving `(event, element)`.\n *\n * @example — a `confirm` modifier that shows a browser dialog\n * ```ts\n * import {registerModifier} from '@alwatr/action';\n *\n * registerModifier('confirm', () => window.confirm('Are you sure?'));\n * ```\n * ```html\n * <button on-action=\"click.confirm->delete-item:42\">Delete</button>\n * ```\n */\nexport function registerModifier(name: string, handler: ModifierHandler): void {\n  logger_.logMethodArgs?.('registerModifier', {name});\n  if (modifierRegistry.has(name)) {\n    logger_.accident('registerModifier', 'modifier_already_registered', {name});\n  }\n  modifierRegistry.set(name, handler);\n}\n\n/**\n * Registers a custom payload resolver that can be used in `on-action` attribute syntax.\n *\n * A payload resolver is a colon-suffixed token in the attribute value\n * (e.g. `click->action-id:$mytoken`). Its function is called at dispatch time\n * with an `ActionContext` as `this` and the DOM event as the argument.\n * The return value becomes the `actionPayload` passed to `onAction` subscribers.\n *\n * Built-in resolvers (`$value`, `$formdata`) are always available. This function\n * lets you add domain-specific ones.\n *\n * Registering the same name twice logs an accident and overwrites the previous\n * resolver — avoid duplicate registrations in production code.\n *\n * @param name     - The resolver token (should start with `$` by convention).\n * @param resolver - A `PayloadResolver` receiving `(event, element)`.\n *\n * @example — a `$checked` resolver for checkbox state\n * ```ts\n * import {registerPayloadResolver} from '@alwatr/action';\n *\n * registerPayloadResolver('$checked', (_event, element) => {\n *   return (element as HTMLInputElement).checked;\n * });\n * ```\n * ```html\n * <input type=\"checkbox\" on-action=\"change->toggle-feature:$checked\" />\n * ```\n */\nexport function registerPayloadResolver(name: string, resolver: PayloadResolver): void {\n  logger_.logMethodArgs?.('registerPayloadResolver', {name});\n  if (payloadRegistry.has(name)) {\n    logger_.accident('registerPayloadResolver', 'payload_resolver_already_registered', {name});\n  }\n  payloadRegistry.set(name, resolver);\n}\n",
-    "/**\n * @file delegate.ts\n *\n * Global Event Delegation engine for `@alwatr/action`.\n *\n * ## Why delegation instead of per-element listeners?\n *\n * The classic directive approach attaches one `addEventListener` per element.\n * With 100 buttons on a page, that means 100 listener registrations at boot\n * time — O(N) initialization cost, O(N) memory for listener references, and\n * zero support for elements added after bootstrap.\n *\n * This module implements the **Qwik-inspired global delegation** pattern:\n * - A single listener per event type is attached to `document.body` with\n *   `capture: true` (so it fires even for non-bubbling events).\n * - When an event fires, the handler walks up the DOM from `event.target`\n *   using `closest()` to find the nearest element with an `on-action`\n *   attribute whose event type matches.\n * - Modifiers and payload resolvers run in the same pipeline as before.\n * - `dispatchAction` is called with the resolved payload.\n *\n * ## Complexity\n *\n * | Metric          | Per-element listeners | Global delegation |\n * | --------------- | --------------------- | ----------------- |\n * | Boot time       | O(N elements)         | O(1) — 1 loop     |\n * | Memory          | O(N listeners)        | O(1) — 1 handler  |\n * | Dynamic content | Requires re-bootstrap | Works out-of-box  |\n * | `once` modifier | Native option         | Manual tracking   |\n *\n * ## Trade-offs vs. the directive approach\n *\n * - `passive` is not supported as a per-element option (all delegated listeners\n *   are non-passive so that `prevent` can call `preventDefault()`).\n * - `stop` stops further bubbling but the delegation handler has already\n *   captured the event at `body` level — it does not prevent other delegation\n *   handlers from running on the same element.\n * - `once` is emulated by delete attribute elements after first fire.\n */\n\nimport {internalChannel_, logger_} from './lib.js';\nimport {modifierRegistry, payloadRegistry} from './registry.js';\n\n// ─── Syntax Parser ────────────────────────────────────────────────────────────\n\n/**\n * Parses the `on-action` attribute value into its three segments.\n *\n * Full syntax: `eventType[.modifier…]->actionId[:payload]`\n *\n * | Capture group | Matches                                     | Example              |\n * | ------------- | ------------------------------------------- | -------------------- |\n * | 1             | Event type + optional dot-chained modifiers | `click.prevent.once` |\n * | 2             | Action identifier                           | `open-drawer`        |\n * | 3             | Optional payload token or literal           | `main` / `$value`    |\n *\n * @example\n * ```\n * 'click.prevent.once->open-drawer:main' → ['click.prevent.once', 'open-drawer', 'main']\n * 'input->search-query:$value'           → ['input',              'search-query', '$value']\n * 'submit.prevent->submit-form'          → ['submit.prevent',     'submit-form',  undefined]\n * ```\n */\nconst syntaxRegex = /^([a-z0-9.-]+)->([a-z0-9-]+)(?::(.+))?$/;\n\n// ─── Parsed Action Descriptor ─────────────────────────────────────────────────\n\n/**\n * Parsed and cached representation of a single `on-action` attribute value.\n *\n * Caching avoids re-parsing the same attribute string on every event fire.\n * The cache is keyed by the raw attribute string so identical values share\n * the same descriptor object.\n */\ninterface ActionDescriptor {\n  /** The DOM event type to listen for (e.g. `'click'`, `'input'`). */\n  readonly eventType: string;\n  /** Set of active modifier names (e.g. `{'prevent', 'once'}`). */\n  readonly modifiers: ReadonlySet<string>;\n  /** The action identifier dispatched to `onAction` subscribers. */\n  readonly actionId: string;\n  /** Raw payload token from the attribute (literal string or `$`-resolver key). */\n  readonly payload: string | undefined;\n}\n\n/**\n * LRU-style cache for parsed `on-action` attribute values.\n *\n * Attribute strings are typically repeated across many elements (e.g. every\n * \"add to cart\" button shares the same `on-action` value). Caching the parsed\n * descriptor avoids redundant regex work on every event.\n *\n * Using a plain `Map` here is intentional — attribute strings are short-lived\n * keys and the map size is bounded by the number of distinct `on-action` values\n * in the page, which is typically small.\n *\n * @internal\n */\nconst descriptorCache__ = new Map<string, ActionDescriptor | null>();\n\n/**\n * Parses an `on-action` attribute value into an `ActionDescriptor`.\n *\n * Returns `null` when the syntax is invalid. Results are cached by the raw\n * attribute string so repeated calls for the same value are O(1).\n *\n * @internal\n */\nfunction parseDescriptor__(attributeValue: string): ActionDescriptor | null {\n  logger_.logMethodArgs?.('parseDescriptor__', {attributeValue});\n\n  const cached = descriptorCache__.get(attributeValue);\n  // Explicit `undefined` check: `null` means \"already parsed and invalid\".\n  if (cached !== undefined) return cached;\n\n  const match = attributeValue.match(syntaxRegex);\n  if (!match) {\n    logger_.accident('parseDescriptor__', 'invalid_syntax', {attributeValue});\n    descriptorCache__.set(attributeValue, null);\n    return null;\n  }\n\n  const [eventType, ...modifierList] = match[1].split('.');\n  if (!eventType) {\n    logger_.accident('parseDescriptor__', 'missing_event_type', {attributeValue});\n    descriptorCache__.set(attributeValue, null);\n    return null;\n  }\n\n  const modifiers = new Set(modifierList);\n  const actionId = match[2];\n  const payload: string | undefined = match[3];\n\n  const descriptor: ActionDescriptor = {\n    eventType,\n    modifiers,\n    actionId,\n    payload,\n  };\n\n  descriptorCache__.set(attributeValue, descriptor);\n  return descriptor;\n}\n\n// ─── Core Delegation Handler ──────────────────────────────────────────────────\n\nconst onActionAttrib__ = 'on-action';\n/**\n * Central event handler attached to `document.body` for every delegated event type.\n *\n * Execution flow for each incoming event:\n * 1. Walk up from `event.target` to find the nearest element with an\n *    `on-action` attribute whose event type matches the current event.\n * 2. Parse (or retrieve from cache) the `ActionDescriptor` for that attribute.\n * 3. Run each modifier in order; if any returns `false`, abort.\n * 4. Resolve the payload token (literal or `$`-resolver).\n * 5. Call `dispatchAction(actionId, payload)`.\n *\n * @internal\n */\nfunction handleDelegatedEvent__(event: Event): void {\n  const eventType = event.type;\n  logger_.logMethodArgs?.('handleDelegatedEvent__', {eventType});\n\n  // Walk up the DOM to find the closest element with a matching on-action attribute.\n  // We use `closest` on the composedPath target to support Shadow DOM correctly.\n  const target = event.target as Element | null;\n  if (!target) return;\n\n  // Find the nearest ancestor (or self) that has an on-action attribute\n  const actionElement = target.closest?.(`[${onActionAttrib__}^=${eventType}]`);\n  if (!actionElement) return;\n\n  const attributeValue = actionElement.getAttribute?.(onActionAttrib__)?.trim();\n  if (!attributeValue) {\n    logger_.accident('handleDelegatedEvent__', 'empty_attribute', {eventType, attributeValue, actionElement});\n    return;\n  }\n\n  if (!(actionElement instanceof HTMLElement)) {\n    logger_.accident('handleDelegatedEvent__', 'target_not_html_element', {eventType, attributeValue, actionElement});\n    return;\n  }\n\n  const descriptor = parseDescriptor__(attributeValue);\n  if (!descriptor) {\n    logger_.accident('handleDelegatedEvent__', 'invalid_attribute', {eventType, attributeValue, actionElement});\n    return;\n  }\n\n  if (descriptor.eventType !== eventType) return;\n\n  logger_.logMethodArgs?.('handleDelegatedEvent__.action', descriptor);\n\n  // Step 1: handle once modifier\n  if (descriptor.modifiers.has('once')) {\n    actionElement.removeAttribute(onActionAttrib__); // remove on-action to prevent repeat the action\n    descriptorCache__.delete(attributeValue); // free memory for once\n  }\n\n  // Step 2: run modifiers\n  for (const modifier of descriptor.modifiers) {\n    if (modifier === 'once') continue; // handled separately\n    const handler = modifierRegistry.get(modifier);\n    if (!handler) {\n      logger_.accident('handleDelegatedEvent__', 'unknown_modifier', {modifier, attributeValue});\n      return; // unknown modifier — abort to avoid silent misbehaviour\n    }\n    if (handler(event, actionElement) === false) return;\n  }\n\n  // Step 3: resolve payload\n  let payload: unknown = descriptor.payload;\n  if (payload) {\n    const resolver = payloadRegistry.get(payload as string);\n    if (resolver) payload = resolver(event, actionElement);\n  }\n\n  // Step 4: dispatch\n  internalChannel_.dispatch(descriptor.actionId, payload);\n}\n\n// ─── Setup ────────────────────────────────────────────────────────────────────\n\n/**\n * The set of event types currently delegated to `document.body`.\n *\n * Tracked so that `setupActionDelegation` is idempotent — calling it multiple\n * times with the same event types does not register duplicate listeners.\n *\n * @internal\n */\nconst delegatedEventTypes__ = new Set<string>();\n\n/**\n * Default DOM event types that cover the vast majority of interactive elements.\n *\n * - `click` — buttons, links, checkboxes, custom interactive elements\n * - `submit` — form submission\n * - `input` — live text input, range sliders\n * - `change` — select boxes, checkboxes, radio buttons (fires on commit)\n *\n * Pass additional types to `setupActionDelegation` when your app uses other\n * events (e.g. `'keydown'`, `'pointerup'`).\n */\nexport const DEFAULT_DELEGATED_EVENTS: readonly string[] = ['click', 'submit', 'input', 'change'];\n\n/**\n * Registers global event delegation for `on-action` attributes.\n *\n * Attaches a single `capture`-phase listener on `document.body` for each\n * event type in `eventTypes`. All `on-action` processing — modifier execution,\n * payload resolution, and `dispatchAction` — happens inside that one handler.\n *\n * **Call this once at application bootstrap**, before any user interaction.\n * Subsequent calls with the same event types are no-ops (idempotent).\n *\n * ### Why `capture: true`?\n *\n * Capture-phase listeners fire before bubble-phase listeners and also catch\n * events that do not bubble (e.g. `focus`, `blur`). This ensures the delegation\n * handler always runs, even when a child element calls `stopPropagation()`.\n *\n * ### Dynamic content\n *\n * Because the listener lives on `document.body`, any element added to the DOM\n * after this call — via `innerHTML`, `lit-html`, a framework renderer, or\n * server-sent HTML — is automatically covered. No re-bootstrap is needed.\n *\n * @param eventTypes - Event types to delegate. Defaults to `DEFAULT_DELEGATED_EVENTS`.\n *\n * @example — minimal bootstrap\n * ```ts\n * import {setupActionDelegation, onAction} from '@alwatr/action';\n *\n * // One call activates the entire page.\n * setupActionDelegation();\n *\n * onAction('open-drawer', (panel) => openDrawer(panel));\n * ```\n *\n * @example — with extra event types\n * ```ts\n * import {setupActionDelegation, DEFAULT_DELEGATED_EVENTS} from '@alwatr/action';\n *\n * setupActionDelegation([...DEFAULT_DELEGATED_EVENTS, 'keydown', 'pointerup']);\n * ```\n */\nexport function setupActionDelegation(eventTypes: readonly string[] = DEFAULT_DELEGATED_EVENTS): void {\n  logger_.logMethodArgs?.('setupActionDelegation', {eventTypes});\n\n  for (const eventType of eventTypes) {\n    if (delegatedEventTypes__.has(eventType)) continue; // already registered — skip\n    delegatedEventTypes__.add(eventType);\n    // capture: true — fires before bubble-phase listeners and catches non-bubbling events.\n    document.body.addEventListener(eventType, handleDelegatedEvent__, {capture: true});\n  }\n}\n\n/**\n * Removes all global delegation listeners registered by `setupActionDelegation`.\n *\n * Useful in test environments where each test needs a clean slate, or in\n * micro-frontend setups where a sub-app is unmounted.\n *\n * After calling this, `setupActionDelegation` can be called again to re-register.\n */\nexport function teardownActionDelegation(): void {\n  logger_.logMethod?.('teardownActionDelegation');\n  for (const eventType of delegatedEventTypes__) {\n    document.body.removeEventListener(eventType, handleDelegatedEvent__, {capture: true});\n  }\n  delegatedEventTypes__.clear();\n  descriptorCache__.clear();\n}\n"
+    "// ─── Type Definitions ────────────────────────────────────────────────────────\n\n/**\n * A modifier handler used in `on-action` attribute syntax.\n *\n * Receives the triggering DOM `event` and the `element` that owns the\n * `on-action` attribute. Return `true` (or any truthy value) to allow the\n * action to proceed, or `false` to cancel the dispatch.\n *\n * Using explicit parameters instead of `this` binding makes handlers\n * compatible with arrow functions and easier to test in isolation.\n *\n * @example\n * ```ts\n * // A modifier that only allows the action when the element is not disabled\n * const notDisabledHandler: ModifierHandler = (_event, element) => {\n *   return !(element as HTMLButtonElement).disabled;\n * };\n * ```\n */\nexport type ModifierHandler = (event: Event, element: HTMLElement) => boolean;\n\n/**\n * A payload resolver used in `on-action` attribute syntax.\n *\n * Receives the triggering DOM `event` and the `element` that owns the\n * `on-action` attribute. The return value becomes the `actionPayload` passed\n * to `onAction` subscribers. Use this to compute dynamic payloads from DOM state.\n *\n * Using explicit parameters instead of `this` binding makes resolvers\n * compatible with arrow functions and easier to test in isolation.\n *\n * @example\n * ```ts\n * // A resolver that returns the element's dataset id\n * const dataIdResolver: PayloadResolver = (_event, element) => {\n *   return (element as HTMLElement).dataset.id ?? null;\n * };\n * ```\n */\nexport type PayloadResolver = (event: Event, element: HTMLElement) => unknown;\n\n// ─── Registries ──────────────────────────────────────────────────────────────\n\n/**\n * Registry of all named modifier handlers.\n *\n * Keys are modifier names used in the `on-<eventType>` attribute syntax\n * (e.g. `on-click=\"action-id; prevent\"`). Values are `ModifierHandler` functions.\n * Populated at module load with built-in modifiers; extended at runtime via\n * `registerModifier`.\n *\n * @internal\n */\nexport const modifierRegistry = new Map<string, ModifierHandler>();\n\n/**\n * Registry of all named payload resolvers.\n *\n * Keys are resolver tokens used in the `on-<eventType>` attribute syntax\n * (e.g. `on-input=\"search_query:$value\"`). Values are `PayloadResolver` functions.\n * Populated at module load with built-in resolvers; extended at runtime via\n * `registerPayloadResolver`.\n *\n * @internal\n */\nexport const payloadRegistry = new Map<string, PayloadResolver>();\n\n// ─── Built-in Modifiers ───────────────────────────────────────────────────────\n\n/**\n * `prevent` — calls `event.preventDefault()` before dispatching.\n *\n * Use it to suppress the browser's default behaviour (e.g. form submission,\n * link navigation, context menu).\n *\n * @example `<form on-submit=\"submit-form; prevent\">`\n */\nmodifierRegistry.set('prevent', (event) => {\n  event.preventDefault();\n  return true;\n});\n\n/**\n * `validate` — cancels the dispatch if the nearest `<form>` fails validation.\n *\n * Looks for a `<form>` ancestor (or the element itself if it is a form) and\n * calls `checkValidity()`. If the form is invalid the action is not dispatched,\n * allowing native constraint-validation UI to surface errors. If no form is\n * found the dispatch is also cancelled.\n *\n * Pair with `.prevent` on `submit` events to avoid page reloads:\n *\n * @example `<form on-submit=\"submit_form:$formdata; prevent,validate\" novalidate>`\n */\nmodifierRegistry.set('validate', (_event, element) => {\n  const form = element instanceof HTMLFormElement ? element : element.closest('form');\n  if (!form) return false;\n  return form.checkValidity();\n});\n\n// ─── Built-in Payload Resolvers ───────────────────────────────────────────────\n\n/**\n * `$value` — resolves to the element's `.value` property at dispatch time.\n *\n * Works with any element that exposes a `value` property: `<input>`,\n * `<textarea>`, `<select>`. Returns `null` for elements without `.value`.\n *\n * @example `<input on-input=\"search_query:$value\" />`\n */\npayloadRegistry.set('$value', (_event, element) => {\n  return 'value' in element ? (element as {value: unknown}).value : null;\n});\n\n/**\n * `$formdata` — resolves to a plain object of all fields in the nearest `<form>`.\n *\n * Collects entries via `FormData` and converts them to a `Record<string, FormDataEntryValue>`.\n * Looks for a `<form>` ancestor (or the element itself). Returns `null` when no\n * form is found.\n *\n * @example `<form on-submit=\"submit_form:$formdata; prevent,validate\">`\n * ```ts\n * onAction('submit_form', (data) => {\n *   console.log(data); // {username: 'ali', password: '…'}\n * });\n * ```\n */\npayloadRegistry.set('$formdata', (_event, element) => {\n  const form = element instanceof HTMLFormElement ? element : element.closest('form');\n  return form ? Object.fromEntries(new FormData(form)) : null;\n});\n\n/**\n * `$checked` — resolves to the `.checked` boolean property of a checkbox or radio input.\n *\n * Works with `<input type=\"checkbox\">` and `<input type=\"radio\">`.\n * Returns `null` for elements that do not have a `checked` property.\n *\n * @example `<input type=\"checkbox\" on-change=\"toggle_feature:$checked\" />`\n * ```ts\n * onAction('toggle_feature', (isChecked) => {\n *   featureSignal.set(isChecked as boolean);\n * });\n * ```\n */\npayloadRegistry.set('$checked', (_event, element) => {\n  return 'checked' in element ? (element as HTMLInputElement).checked : null;\n});\n",
+    "import type {Awaitable} from '@alwatr/type-helper';\nimport {internalChannel_, logger_} from './lib.js';\nimport type {SubscribeResult} from '@alwatr/signal';\nimport {modifierRegistry, payloadRegistry, type ModifierHandler, type PayloadResolver} from './registry.js';\nimport type {ActionRecord} from './action-record.js';\n\n// Re-export extension types so consumers can import them from the package root.\nexport type {ModifierHandler, PayloadResolver};\n\n// ─── Core Action API ──────────────────────────────────────────────────────────\n\n/**\n * Subscribes to a named action dispatched anywhere in the application.\n *\n * `actionId` must be a key of `ActionRecord`. The handler's `payload` parameter\n * is automatically typed to the corresponding `ActionRecord` value — no manual\n * generic annotation needed:\n *\n * ```ts\n * // ActionRecord declares: 'add_to_cart': {productId: number; qty: number}\n * onAction('add_to_cart', (item) => {\n *   cartService.add(item.productId, item.qty); // fully typed, no `!` needed\n * });\n * ```\n *\n * Passing an action name not declared in `ActionRecord` is a **compile error**.\n * Register new actions by extending `ActionRecord` via declaration merging:\n *\n * ```ts\n * // src/action-record.ts\n * declare module '@alwatr/action' {\n *   interface ActionRecord {\n *     'open_drawer': string;\n *   }\n * }\n * ```\n *\n * Internally delegates to `ChannelSignal.on()` for **O(1) routing** — dispatching\n * action `'A'` never invokes handlers registered for action `'B'`.\n *\n * @param actionId - A key of `ActionRecord`.\n * @param handler  - Callback invoked with the typed payload on each dispatch.\n * @returns A `SubscribeResult` with an `unsubscribe()` method for cleanup.\n *\n * @example\n * ```ts\n * import {onAction} from '@alwatr/action';\n *\n * const sub = onAction('page_ready', (pageId) => {\n *   router.setPage(pageId); // pageId: string — inferred from ActionRecord\n * });\n *\n * sub.unsubscribe(); // stop listening when no longer needed\n * ```\n */\nexport function onAction<K extends keyof ActionRecord>(\n  actionId: K,\n  handler: (payload: ActionRecord[K]) => Awaitable<void>,\n): SubscribeResult {\n  logger_.logMethodArgs?.('onAction', {actionId});\n  return internalChannel_.on(actionId, handler as (payload: unknown) => Awaitable<void>);\n}\n\n/**\n * Dispatches a named action to all `onAction` subscribers with a matching `actionId`.\n *\n * `actionId` must be a key of `ActionRecord`. The `payload` parameter is\n * automatically typed — passing the wrong type is a **compile error**:\n *\n * ```ts\n * // ActionRecord declares: 'add_to_cart': {productId: number; qty: number}\n * dispatchAction('add_to_cart', {productId: 42, qty: 1}); // ✅\n * dispatchAction('add_to_cart', 'wrong');                  // ❌ compile error\n * dispatchAction('unknown_action', 'x');                   // ❌ compile error\n * ```\n *\n * Register new actions by extending `ActionRecord` via declaration merging:\n *\n * ```ts\n * // src/action-record.ts\n * declare module '@alwatr/action' {\n *   interface ActionRecord {\n *     'navigate': string;\n *     'logout': void;\n *   }\n * }\n * ```\n *\n * Use `dispatchAction` when triggering an action from code — e.g. after an\n * async operation, from a service layer, or in tests. For DOM-driven actions,\n * use the `on-<eventType>` HTML attribute with `setupActionDelegation`.\n *\n * @param actionId      - A key of `ActionRecord`.\n * @param actionPayload - The payload; type is enforced by `ActionRecord`.\n *\n * @example — with payload\n * ```ts\n * import {dispatchAction} from '@alwatr/action';\n *\n * dispatchAction('page_ready', 'home');\n * dispatchAction('navigate', '/dashboard');\n * ```\n *\n * @example — void payload (no second argument)\n * ```ts\n * dispatchAction('logout');\n * ```\n */\nexport function dispatchAction<K extends keyof ActionRecord>(\n  ...args: ActionRecord[K] extends void | undefined ? [actionId: K] : [actionId: K, actionPayload: ActionRecord[K]]\n): void {\n  const [actionId, actionPayload] = args;\n  logger_.logMethodArgs?.('dispatchAction', {actionId, actionPayload});\n  internalChannel_.dispatch(actionId, actionPayload);\n}\n\n// ─── Extension API ────────────────────────────────────────────────────────────\n\n/**\n * Registers a custom modifier that can be used in `on-<eventType>` attribute syntax.\n *\n * A modifier is a comma-separated token placed after the `;` separator\n * (e.g. `on-click=\"action-id; mymod\"`). Its handler runs before the payload is\n * resolved and the action is dispatched. Returning `false` cancels the dispatch.\n *\n * Built-in modifiers (`prevent`, `stop`, `validate`, `once`) are always\n * available. This function lets you add domain-specific ones.\n *\n * Registering the same name twice logs an accident and overwrites the previous\n * handler — avoid duplicate registrations in production code.\n *\n * @param name    - The modifier token (lowercase, no special characters).\n * @param handler - A `ModifierHandler` receiving `(event, element)`.\n *\n * @example — a `confirm` modifier that shows a browser dialog\n * ```ts\n * import {registerModifier} from '@alwatr/action';\n *\n * registerModifier('confirm', () => window.confirm('Are you sure?'));\n * ```\n * ```html\n * <button on-click=\"delete_item:42; confirm\">Delete</button>\n * ```\n */\nexport function registerModifier(name: string, handler: ModifierHandler): void {\n  logger_.logMethodArgs?.('registerModifier', {name});\n  if (modifierRegistry.has(name)) {\n    logger_.accident('registerModifier', 'modifier_already_registered', {name});\n  }\n  modifierRegistry.set(name, handler);\n}\n\n/**\n * Registers a custom payload resolver that can be used in `on-<eventType>` attribute syntax.\n *\n * A payload resolver is a colon-prefixed token in the attribute value\n * (e.g. `on-click=\"action-id:$mytoken\"`). Its function is called at dispatch time\n * with an `ActionContext` as `this` and the DOM event as the argument.\n * The return value becomes the `actionPayload` passed to `onAction` subscribers.\n *\n * Built-in resolvers (`$value`, `$formdata`) are always available. This function\n * lets you add domain-specific ones.\n *\n * Registering the same name twice logs an accident and overwrites the previous\n * resolver — avoid duplicate registrations in production code.\n *\n * @param name     - The resolver token (should start with `$` by convention).\n * @param resolver - A `PayloadResolver` receiving `(event, element)`.\n *\n * @example — a `$checked` resolver for checkbox state\n * ```ts\n * import {registerPayloadResolver} from '@alwatr/action';\n *\n * registerPayloadResolver('$checked', (_event, element) => {\n *   return (element as HTMLInputElement).checked;\n * });\n * ```\n * ```html\n * <input type=\"checkbox\" on-change=\"toggle_feature:$checked\" />\n * ```\n */\nexport function registerPayloadResolver(name: string, resolver: PayloadResolver): void {\n  logger_.logMethodArgs?.('registerPayloadResolver', {name});\n  if (payloadRegistry.has(name)) {\n    logger_.accident('registerPayloadResolver', 'payload_resolver_already_registered', {name});\n  }\n  payloadRegistry.set(name, resolver);\n}\n",
+    "/**\n * @file delegate.ts\n *\n * Global Event Delegation engine for `@alwatr/action`.\n *\n * ## Why delegation instead of per-element listeners?\n *\n * The classic directive approach attaches one `addEventListener` per element.\n * With 100 buttons on a page, that means 100 listener registrations at boot\n * time — O(N) initialization cost, O(N) memory for listener references, and\n * zero support for elements added after bootstrap.\n *\n * This module implements the global delegation pattern:\n * - A single listener per event type is attached to `document.body` with\n *   `capture: true` (so it fires even for non-bubbling events).\n * - When an event fires, the handler walks up the DOM from `event.target`\n *   using `closest()` to find the nearest element with an `on-<eventType>`\n *   attribute (e.g. `on-click`, `on-submit`).\n * - Modifiers and payload resolvers run in the same pipeline as before.\n * - `dispatchAction` is called with the resolved payload.\n *\n * ## Complexity\n *\n * | Metric          | Per-element listeners | Global delegation |\n * | --------------- | --------------------- | ----------------- |\n * | Boot time       | O(N elements)         | O(1) — 1 loop     |\n * | Memory          | O(N listeners)        | O(1) — 1 handler  |\n * | Dynamic content | Requires re-bootstrap | Works out-of-box  |\n * | `once` modifier | Native option         | Manual tracking   |\n *\n * ## Trade-offs vs. the directive approach\n *\n * - `passive` is not supported as a per-element option (all delegated listeners\n *   are non-passive so that `prevent` can call `preventDefault()`).\n * - `stop` stops further bubbling but the delegation handler has already\n *   captured the event at `body` level — it does not prevent other delegation\n *   handlers from running on the same element.\n * - `once` is emulated by removing the attribute after first fire.\n */\n\nimport {internalChannel_, logger_} from './lib.js';\nimport {modifierRegistry, payloadRegistry} from './registry.js';\n\n// ─── Syntax Parser ────────────────────────────────────────────────────────────\n\n/**\n * Parses the `on-<eventType>` attribute value into its segments.\n *\n * Syntax: `actionId[:payload][; modifier1,modifier2,…]`\n *\n * The event type is encoded in the **attribute name** itself (`on-click`,\n * `on-submit`, etc.) rather than inside the value. This makes the HTML more\n * readable and aligns with native event attribute conventions.\n *\n * | Capture group | Matches                                | Example                |\n * | ------------- | -------------------------------------- | ---------------------- |\n * | 1             | Action identifier                      | `open_drawer`          |\n * | 2             | Optional payload token or literal      | `main_menu` / `$value` |\n * | 3             | Optional comma-separated modifier list | `prevent,validate`     |\n *\n * @example\n * ```\n * 'close_drawer'\n *   → actionId='close_drawer', payload=undefined, modifiers={}\n *\n * 'open_drawer:main_menu'\n *   → actionId='open_drawer', payload='main_menu', modifiers={}\n *\n * 'my_submit_handler:$formdata; prevent,validate'\n *   → actionId='my_submit_handler', payload='$formdata', modifiers={'prevent','validate'}\n * ```\n */\nconst syntaxRegex = /^([a-z0-9_-]+)(?::([^;]+))?(?:;\\s*([a-z0-9_,-]+))?$/;\n\n// ─── Parsed Action Descriptor ─────────────────────────────────────────────────\n\n/**\n * Parsed and cached representation of a single `on-<eventType>` attribute value.\n *\n * Does not store `eventType` — the caller always has it from `event.type`,\n * and the attribute name already encodes it (e.g. `on-click`), so storing it\n * here would be redundant. This also keeps the cache key simple: just the raw\n * attribute value string, with no composite key needed.\n */\ninterface ActionDescriptor {\n  /** Set of active modifier names (e.g. `{'prevent', 'once'}`). */\n  readonly modifiers: ReadonlySet<string>;\n  /** The action identifier dispatched to `onAction` subscribers. */\n  readonly actionId: string;\n  /** Raw payload token from the attribute (literal string or $-resolver key). */\n  readonly payload: string | undefined;\n}\n\n/**\n * Cache for parsed `on-<eventType>` attribute values.\n *\n * Attribute strings are typically repeated across many elements (e.g. every\n * \"add to cart\" button shares the same `on-click` value). Caching the parsed\n * descriptor avoids redundant regex work on every event.\n *\n * The cache key is the raw attribute value string. No composite key with\n * event type is needed because the attribute name already encodes the event\n * type — `on-click=\"open_drawer\"` and `on-submit=\"open_drawer\"` are two\n * separate attributes with the same value string, but they are read from\n * different attribute names and never collide in this cache.\n *\n * @internal\n */\nconst descriptorCache__ = new Map<string, ActionDescriptor | null>();\n\n/**\n * Parses an `on-<eventType>` attribute value into an `ActionDescriptor`.\n *\n * Returns `null` when the syntax is invalid. Results are cached by the raw\n * attribute value string so repeated calls for the same value are O(1).\n *\n * @internal\n */\nfunction parseDescriptor__(attributeValue: string): ActionDescriptor | null {\n  logger_.logMethodArgs?.('parseDescriptor__', {attributeValue});\n\n  const cached = descriptorCache__.get(attributeValue);\n  // Explicit `undefined` check: `null` means \"already parsed and invalid\".\n  if (cached !== undefined) return cached;\n\n  const match = attributeValue.match(syntaxRegex);\n  if (!match) {\n    logger_.accident('parseDescriptor__', 'invalid_syntax', {attributeValue});\n    descriptorCache__.set(attributeValue, null);\n    return null;\n  }\n\n  const actionId = match[1];\n  const payload: string | undefined = match[2];\n  // match[3] is the raw modifier list string, e.g. \"prevent,validate\"\n  const modifierString = match[3];\n  const modifiers: Set<string> = modifierString ? new Set(modifierString.split(',').filter(Boolean)) : new Set();\n  const descriptor: ActionDescriptor = {modifiers, actionId, payload};\n\n  descriptorCache__.set(attributeValue, descriptor);\n  return descriptor;\n}\n\n// ─── Core Delegation Handler ──────────────────────────────────────────────────\n\n/**\n * Central event handler attached to `document.body` for every delegated event type.\n *\n * Execution flow for each incoming event:\n * 1. Walk up from `event.target` to find the nearest element with an\n *    `on-<eventType>` attribute (e.g. `on-click`, `on-submit`).\n * 2. Parse (or retrieve from cache) the `ActionDescriptor` for that attribute.\n * 3. Run each modifier in order; if any returns `false`, abort.\n * 4. Resolve the payload token (literal or $-resolver).\n * 5. Call `dispatchAction(actionId, payload)`.\n *\n * @internal\n */\nfunction handleDelegatedEvent__(event: Event): void {\n  const eventType = event.type;\n  logger_.logMethodArgs?.('handleDelegatedEvent__', {eventType});\n\n  const target = event.target as Element | null;\n  if (!target) return;\n\n  // Attribute name encodes the event type: on-click, on-submit, etc.\n  const actionAttrib = `on-${eventType}`;\n\n  // Walk up the DOM to find the closest element with the matching on-<eventType> attribute.\n  const actionElement = target.closest?.(`[${actionAttrib}]`);\n  if (!actionElement) return;\n\n  const attributeValue = actionElement.getAttribute?.(actionAttrib)?.trim();\n  if (!attributeValue) {\n    logger_.accident('handleDelegatedEvent__', 'empty_attribute', {eventType, actionElement});\n    return;\n  }\n\n  if (!(actionElement instanceof HTMLElement)) {\n    logger_.accident('handleDelegatedEvent__', 'target_not_html_element', {eventType, actionElement});\n    return;\n  }\n\n  const descriptor = parseDescriptor__(attributeValue);\n  if (!descriptor) return;\n\n  logger_.logMethodArgs?.('handleDelegatedEvent__.action', {eventType, descriptor});\n\n  // Step 1: handle once modifier — remove attribute before running other modifiers\n  // so that even if a modifier aborts, the element will not fire again.\n  if (descriptor.modifiers.has('once')) {\n    actionElement.removeAttribute(actionAttrib);\n  }\n\n  // Step 2: run modifiers\n  for (const modifier of descriptor.modifiers) {\n    if (modifier === 'once') continue; // handled above\n    const handler = modifierRegistry.get(modifier);\n    if (!handler) {\n      logger_.accident('handleDelegatedEvent__', 'unknown_modifier', {eventType, modifier, attributeValue, descriptor});\n      return; // unknown modifier — abort to avoid silent misbehavior\n    }\n    if (handler(event, actionElement) === false) return;\n  }\n\n  // Step 3: resolve payload\n  let payload: unknown = descriptor.payload;\n  if (payload) {\n    const resolver = payloadRegistry.get(payload as string);\n    if (resolver) payload = resolver(event, actionElement);\n  }\n\n  // Step 4: dispatch\n  internalChannel_.dispatch(descriptor.actionId, payload);\n}\n\n// ─── Setup ────────────────────────────────────────────────────────────────────\n\n/**\n * The set of event types currently delegated to `document.body`.\n *\n * Tracked so that `setupActionDelegation` is idempotent — calling it multiple\n * times with the same event types does not register duplicate listeners.\n *\n * @internal\n */\nconst delegatedEventTypes__ = new Set<string>();\n\n/**\n * Default DOM event types that cover the vast majority of interactive elements.\n *\n * - `click` — buttons, links, checkboxes, custom interactive elements\n * - `submit` — form submission\n * - `input` — live text input, range sliders\n * - `change` — select boxes, checkboxes, radio buttons (fires on commit)\n *\n * Pass additional types to `setupActionDelegation` when your app uses other\n * events (e.g. `'keydown'`, `'pointerup'`).\n */\nexport const DEFAULT_DELEGATED_EVENTS: readonly string[] = ['click', 'submit', 'input', 'change'];\n\n/**\n * Registers global event delegation for `on-<eventType>` attributes.\n *\n * Attaches a single `capture`-phase listener on `document.body` for each\n * event type in `eventTypes`. All processing — modifier execution, payload\n * resolution, and `dispatchAction` — happens inside that one handler.\n *\n * **Call this once at application bootstrap**, before any user interaction.\n * Subsequent calls with the same event types are no-ops (idempotent).\n *\n * ### Why `capture: true`?\n *\n * Capture-phase listeners fire before bubble-phase listeners and also catch\n * events that do not bubble (e.g. `focus`, `blur`). This ensures the delegation\n * handler always runs, even when a child element calls `stopPropagation()`.\n *\n * ### Dynamic content\n *\n * Because the listener lives on `document.body`, any element added to the DOM\n * after this call — via `innerHTML`, `lit-html`, a framework renderer, or\n * server-sent HTML — is automatically covered. No re-bootstrap is needed.\n *\n * @param eventTypes - Event types to delegate. Defaults to `DEFAULT_DELEGATED_EVENTS`.\n *\n * @example — minimal bootstrap\n * ```ts\n * import {setupActionDelegation, onAction} from '@alwatr/action';\n *\n * // One call activates the entire page.\n * setupActionDelegation();\n *\n * onAction('open_drawer', (panel) => openDrawer(panel));\n * ```\n *\n * @example — with extra event types\n * ```ts\n * import {setupActionDelegation, DEFAULT_DELEGATED_EVENTS} from '@alwatr/action';\n *\n * setupActionDelegation([...DEFAULT_DELEGATED_EVENTS, 'keydown', 'pointerup']);\n * ```\n */\nexport function setupActionDelegation(eventTypes: readonly string[] = DEFAULT_DELEGATED_EVENTS): void {\n  logger_.logMethodArgs?.('setupActionDelegation', {eventTypes});\n\n  for (const eventType of eventTypes) {\n    if (delegatedEventTypes__.has(eventType)) continue; // already registered — skip\n    delegatedEventTypes__.add(eventType);\n    // capture: true — fires before bubble-phase listeners and catches non-bubbling events.\n    document.body.addEventListener(eventType, handleDelegatedEvent__, {capture: true});\n  }\n}\n\n/**\n * Removes all global delegation listeners registered by `setupActionDelegation`.\n *\n * Useful in test environments where each test needs a clean slate, or in\n * micro-frontend setups where a sub-app is unmounted.\n *\n * After calling this, `setupActionDelegation` can be called again to re-register.\n */\nexport function teardownActionDelegation(): void {\n  logger_.logMethod?.('teardownActionDelegation');\n  for (const eventType of delegatedEventTypes__) {\n    document.body.removeEventListener(eventType, handleDelegatedEvent__, {capture: true});\n  }\n  delegatedEventTypes__.clear();\n  descriptorCache__.clear();\n}\n"
   ],
-  "mappings": "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",
-  "debugId": "7E5E853AFB39285764756E2164756E21",
+  "mappings": "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",
+  "debugId": "C5F4214484C292C364756E2164756E21",
   "names": []
 }

package/dist/method.d.ts

@@ -11,8 +11,8 @@ export type { ModifierHandler, PayloadResolver };
  * generic annotation needed:
  *
  * ```ts
- * // ActionRecord declares: 'add-to-cart': {productId: number; qty: number}
- * onAction('add-to-cart', (item) => {
+ * // ActionRecord declares: 'add_to_cart': {productId: number; qty: number}
+ * onAction('add_to_cart', (item) => {
  *   cartService.add(item.productId, item.qty); // fully typed, no `!` needed
  * });
  * ```
@@ -24,7 +24,7 @@ export type { ModifierHandler, PayloadResolver };
  * // src/action-record.ts
  * declare module '@alwatr/action' {
  *   interface ActionRecord {
- *     'open-drawer': string;
+ *     'open_drawer': string;
  *   }
  * }
  * ```
@@ -40,7 +40,7 @@ export type { ModifierHandler, PayloadResolver };
  * ```ts
  * import {onAction} from '@alwatr/action';
  *
- * const sub = onAction('page-ready', (pageId) => {
+ * const sub = onAction('page_ready', (pageId) => {
  *   router.setPage(pageId); // pageId: string — inferred from ActionRecord
  * });
  *
@@ -55,10 +55,10 @@ export declare function onAction<K extends keyof ActionRecord>(actionId: K, hand
  * automatically typed — passing the wrong type is a **compile error**:
  *
  * ```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
+ * // 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
  * ```
  *
  * Register new actions by extending `ActionRecord` via declaration merging:
@@ -75,7 +75,7 @@ export declare function onAction<K extends keyof ActionRecord>(actionId: K, hand
  *
  * 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`.
+ * use the `on-<eventType>` HTML attribute with `setupActionDelegation`.
  *
  * @param actionId      - A key of `ActionRecord`.
  * @param actionPayload - The payload; type is enforced by `ActionRecord`.
@@ -84,7 +84,7 @@ export declare function onAction<K extends keyof ActionRecord>(actionId: K, hand
  * ```ts
  * import {dispatchAction} from '@alwatr/action';
  *
- * dispatchAction('page-ready', 'home');
+ * dispatchAction('page_ready', 'home');
  * dispatchAction('navigate', '/dashboard');
  * ```
  *
@@ -95,10 +95,10 @@ export declare function onAction<K extends keyof ActionRecord>(actionId: K, hand
  */
 export declare function dispatchAction<K extends keyof ActionRecord>(...args: ActionRecord[K] extends void | undefined ? [actionId: K] : [actionId: K, actionPayload: ActionRecord[K]]): void;
 /**
- * Registers a custom modifier that can be used in `on-action` attribute syntax.
+ * Registers a custom modifier that can be used in `on-<eventType>` attribute syntax.
  *
- * A modifier is a dot-chained token placed after the event type
- * (e.g. `click.mymod->action-id`). Its handler runs before the payload is
+ * A modifier is a comma-separated token placed after the `;` separator
+ * (e.g. `on-click="action-id; mymod"`). 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`) are always
@@ -107,7 +107,7 @@ export declare function dispatchAction<K extends keyof ActionRecord>(...args: Ac
  * 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 name    - The modifier token (lowercase, no special characters).
  * @param handler - A `ModifierHandler` receiving `(event, element)`.
  *
  * @example — a `confirm` modifier that shows a browser dialog
@@ -117,15 +117,15 @@ export declare function dispatchAction<K extends keyof ActionRecord>(...args: Ac
  * registerModifier('confirm', () => window.confirm('Are you sure?'));
  * ```
  * ```html
- * <button on-action="click.confirm->delete-item:42">Delete</button>
+ * <button on-click="delete_item:42; confirm">Delete</button>
  * ```
  */
 export declare function registerModifier(name: string, handler: ModifierHandler): void;
 /**
- * Registers a custom payload resolver that can be used in `on-action` attribute syntax.
+ * Registers a custom payload resolver that can be used in `on-<eventType>` attribute syntax.
  *
- * 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
+ * A payload resolver is a colon-prefixed token in the attribute value
+ * (e.g. `on-click="action-id:$mytoken"`). Its function is called at dispatch time
  * with an `ActionContext` as `this` and the DOM event as the argument.
  * The return value becomes the `actionPayload` passed to `onAction` subscribers.
  *
@@ -147,7 +147,7 @@ export declare function registerModifier(name: string, handler: ModifierHandler)
  * });
  * ```
  * ```html
- * <input type="checkbox" on-action="change->toggle-feature:$checked" />
+ * <input type="checkbox" on-change="toggle_feature:$checked" />
  * ```
  */
 export declare function registerPayloadResolver(name: string, resolver: PayloadResolver): void;

package/dist/registry.d.ts

@@ -39,8 +39,8 @@ export type PayloadResolver = (event: Event, element: HTMLElement) => unknown;
 /**
  * Registry of all named modifier handlers.
  *
- * Keys are modifier names used in the `on-action` attribute syntax
- * (e.g. `click.prevent->action-id`). Values are `ModifierHandler` functions.
+ * Keys are modifier names used in the `on-<eventType>` attribute syntax
+ * (e.g. `on-click="action-id; prevent"`). Values are `ModifierHandler` functions.
  * Populated at module load with built-in modifiers; extended at runtime via
  * `registerModifier`.
  *
@@ -50,8 +50,8 @@ export declare const modifierRegistry: Map<string, ModifierHandler>;
 /**
  * Registry of all named payload resolvers.
  *
- * Keys are resolver tokens used in the `on-action` attribute syntax
- * (e.g. `click->action-id:$value`). Values are `PayloadResolver` functions.
+ * Keys are resolver tokens used in the `on-<eventType>` attribute syntax
+ * (e.g. `on-input="search_query:$value"`). Values are `PayloadResolver` functions.
  * Populated at module load with built-in resolvers; extended at runtime via
  * `registerPayloadResolver`.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alwatr/action",
-  "version": "9.14.0",
+  "version": "9.16.0",
   "description": "Declarative DOM action-dispatch — bridge HTML attributes to typed signal handlers.",
   "license": "MPL-2.0",
   "author": "S. Ali Mihandoost <ali.mihandoost@gmail.com> (https://ali.mihandoost.com)",
@@ -21,12 +21,12 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@alwatr/logger": "9.14.0",
-    "@alwatr/signal": "9.14.0"
+    "@alwatr/logger": "9.16.0",
+    "@alwatr/signal": "9.16.0"
   },
   "devDependencies": {
     "@alwatr/nano-build": "9.14.0",
-    "@alwatr/standard": "9.14.0",
+    "@alwatr/standard": "9.16.0",
     "@alwatr/type-helper": "9.14.0",
     "typescript": "^6.0.3"
   },
@@ -79,5 +79,5 @@
     "vanilla-js",
     "web-development"
   ],
-  "gitHead": "4e499b23191d4460ea60f34cde8a99b472741f1a"
+  "gitHead": "c210044f6e8ab444ec2f9e600f095761cbd279bd"
 }

package/src/action-record.ts

@@ -13,8 +13,8 @@
  * // In your package: src/action-record.ts
  * declare module '@alwatr/action' {
  *   interface ActionRecord {
- *     'open-drawer': string;
- *     'add-to-cart': {productId: number; qty: number};
+ *     'open_drawer': string;
+ *     'add_to_cart': {productId: number; qty: number};
  *     'logout': void;
  *   }
  * }
@@ -43,8 +43,8 @@
  * // pkg/my-feature/src/action-record.ts
  * declare module '@alwatr/action' {
  *   interface ActionRecord {
- *     'open-drawer': string;
- *     'add-to-cart': {productId: number; qty: number};
+ *     'open_drawer': string;
+ *     'add_to_cart': {productId: number; qty: number};
  *     'logout': void;
  *   }
  * }

package/src/delegate.ts

@@ -10,12 +10,12 @@
  * 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:
+ * This module implements the 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.
+ *   using `closest()` to find the nearest element with an `on-<eventType>`
+ *   attribute (e.g. `on-click`, `on-submit`).
  * - Modifiers and payload resolvers run in the same pipeline as before.
  * - `dispatchAction` is called with the resolved payload.
  *
@@ -35,7 +35,7 @@
  * - `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.
+ * - `once` is emulated by removing the attribute after first fire.
  */
 
 import {internalChannel_, logger_} from './lib.js';
@@ -44,65 +44,75 @@ import {modifierRegistry, payloadRegistry} from './registry.js';
 // ─── Syntax Parser ────────────────────────────────────────────────────────────
 
 /**
- * Parses the `on-action` attribute value into its three segments.
+ * Parses the `on-<eventType>` attribute value into its segments.
  *
- * Full syntax: `eventType[.modifier…]->actionId[:payload]`
+ * Syntax: `actionId[:payload][; modifier1,modifier2,…]`
  *
- * | 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`    |
+ * The event type is encoded in the **attribute name** itself (`on-click`,
+ * `on-submit`, etc.) rather than inside the value. This makes the HTML more
+ * readable and aligns with native event attribute conventions.
+ *
+ * | Capture group | Matches                                | Example                |
+ * | ------------- | -------------------------------------- | ---------------------- |
+ * | 1             | Action identifier                      | `open_drawer`          |
+ * | 2             | Optional payload token or literal      | `main_menu` / `$value` |
+ * | 3             | Optional comma-separated modifier list | `prevent,validate`     |
  *
  * @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]
+ * 'close_drawer'
+ *   → actionId='close_drawer', payload=undefined, modifiers={}
+ *
+ * 'open_drawer:main_menu'
+ *   → actionId='open_drawer', payload='main_menu', modifiers={}
+ *
+ * 'my_submit_handler:$formdata; prevent,validate'
+ *   → actionId='my_submit_handler', payload='$formdata', modifiers={'prevent','validate'}
  * ```
  */
-const syntaxRegex = /^([a-z0-9.-]+)->([a-z0-9-]+)(?::(.+))?$/;
+const syntaxRegex = /^([a-z0-9_-]+)(?::([^;]+))?(?:;\s*([a-z0-9_,-]+))?$/;
 
 // ─── Parsed Action Descriptor ─────────────────────────────────────────────────
 
 /**
- * Parsed and cached representation of a single `on-action` attribute value.
+ * Parsed and cached representation of a single `on-<eventType>` 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.
+ * Does not store `eventType` — the caller always has it from `event.type`,
+ * and the attribute name already encodes it (e.g. `on-click`), so storing it
+ * here would be redundant. This also keeps the cache key simple: just the raw
+ * attribute value string, with no composite key needed.
  */
 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). */
+  /** Raw payload token from the attribute (literal string or $-resolver key). */
   readonly payload: string | undefined;
 }
 
 /**
- * LRU-style cache for parsed `on-action` attribute values.
+ * Cache for parsed `on-<eventType>` 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
+ * "add to cart" button shares the same `on-click` 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.
+ * The cache key is the raw attribute value string. No composite key with
+ * event type is needed because the attribute name already encodes the event
+ * type — `on-click="open_drawer"` and `on-submit="open_drawer"` are two
+ * separate attributes with the same value string, but they are read from
+ * different attribute names and never collide in this cache.
  *
  * @internal
  */
 const descriptorCache__ = new Map<string, ActionDescriptor | null>();
 
 /**
- * Parses an `on-action` attribute value into an `ActionDescriptor`.
+ * Parses an `on-<eventType>` 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).
+ * attribute value string so repeated calls for the same value are O(1).
  *
  * @internal
  */
@@ -120,23 +130,12 @@ function parseDescriptor__(attributeValue: string): ActionDescriptor | 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,
-  };
+  const actionId = match[1];
+  const payload: string | undefined = match[2];
+  // match[3] is the raw modifier list string, e.g. "prevent,validate"
+  const modifierString = match[3];
+  const modifiers: Set<string> = modifierString ? new Set(modifierString.split(',').filter(Boolean)) : new Set();
+  const descriptor: ActionDescriptor = {modifiers, actionId, payload};
 
   descriptorCache__.set(attributeValue, descriptor);
   return descriptor;
@@ -144,16 +143,15 @@ function parseDescriptor__(attributeValue: string): ActionDescriptor | null {
 
 // ─── 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.
+ *    `on-<eventType>` attribute (e.g. `on-click`, `on-submit`).
  * 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).
+ * 4. Resolve the payload token (literal or $-resolver).
  * 5. Call `dispatchAction(actionId, payload)`.
  *
  * @internal
@@ -162,49 +160,45 @@ 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}]`);
+  // Attribute name encodes the event type: on-click, on-submit, etc.
+  const actionAttrib = `on-${eventType}`;
+
+  // Walk up the DOM to find the closest element with the matching on-<eventType> attribute.
+  const actionElement = target.closest?.(`[${actionAttrib}]`);
   if (!actionElement) return;
 
-  const attributeValue = actionElement.getAttribute?.(onActionAttrib__)?.trim();
+  const attributeValue = actionElement.getAttribute?.(actionAttrib)?.trim();
   if (!attributeValue) {
-    logger_.accident('handleDelegatedEvent__', 'empty_attribute', {eventType, attributeValue, actionElement});
+    logger_.accident('handleDelegatedEvent__', 'empty_attribute', {eventType, actionElement});
     return;
   }
 
   if (!(actionElement instanceof HTMLElement)) {
-    logger_.accident('handleDelegatedEvent__', 'target_not_html_element', {eventType, attributeValue, actionElement});
+    logger_.accident('handleDelegatedEvent__', 'target_not_html_element', {eventType, actionElement});
     return;
   }
 
   const descriptor = parseDescriptor__(attributeValue);
-  if (!descriptor) {
-    logger_.accident('handleDelegatedEvent__', 'invalid_attribute', {eventType, attributeValue, actionElement});
-    return;
-  }
-
-  if (descriptor.eventType !== eventType) return;
+  if (!descriptor) return;
 
-  logger_.logMethodArgs?.('handleDelegatedEvent__.action', descriptor);
+  logger_.logMethodArgs?.('handleDelegatedEvent__.action', {eventType, descriptor});
 
-  // Step 1: handle once modifier
+  // Step 1: handle once modifier — remove attribute before running other modifiers
+  // so that even if a modifier aborts, the element will not fire again.
   if (descriptor.modifiers.has('once')) {
-    actionElement.removeAttribute(onActionAttrib__); // remove on-action to prevent repeat the action
-    descriptorCache__.delete(attributeValue); // free memory for once
+    actionElement.removeAttribute(actionAttrib);
   }
 
   // Step 2: run modifiers
   for (const modifier of descriptor.modifiers) {
-    if (modifier === 'once') continue; // handled separately
+    if (modifier === 'once') continue; // handled above
     const handler = modifierRegistry.get(modifier);
     if (!handler) {
-      logger_.accident('handleDelegatedEvent__', 'unknown_modifier', {modifier, attributeValue});
-      return; // unknown modifier — abort to avoid silent misbehaviour
+      logger_.accident('handleDelegatedEvent__', 'unknown_modifier', {eventType, modifier, attributeValue, descriptor});
+      return; // unknown modifier — abort to avoid silent misbehavior
     }
     if (handler(event, actionElement) === false) return;
   }
@@ -246,11 +240,11 @@ const delegatedEventTypes__ = new Set<string>();
 export const DEFAULT_DELEGATED_EVENTS: readonly string[] = ['click', 'submit', 'input', 'change'];
 
 /**
- * Registers global event delegation for `on-action` attributes.
+ * Registers global event delegation for `on-<eventType>` 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.
+ * event type in `eventTypes`. All 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).
@@ -276,7 +270,7 @@ export const DEFAULT_DELEGATED_EVENTS: readonly string[] = ['click', 'submit', '
  * // One call activates the entire page.
  * setupActionDelegation();
  *
- * onAction('open-drawer', (panel) => openDrawer(panel));
+ * onAction('open_drawer', (panel) => openDrawer(panel));
  * ```
  *
  * @example — with extra event types