@alwatr/action 9.14.0 → 9.17.0

package/dist/method.d.ts

@@ -2,18 +2,22 @@ import type { Awaitable } from '@alwatr/type-helper';
 import type { SubscribeResult } from '@alwatr/signal';
 import { type ModifierHandler, type PayloadResolver } from './registry.js';
 import type { ActionRecord } from './action-record.js';
+import type { Action } from './action.js';
 export type { ModifierHandler, PayloadResolver };
+export type { Action };
 /**
  * Subscribes to a named action dispatched anywhere in the application.
  *
- * `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:
+ * `type` must be a key of `ActionRecord`. The handler receives the full
+ * `Action<K>` object — giving access to `payload`, `context`, and `meta`
+ * in one place. No manual generic annotation is needed; the compiler infers
+ * the correct `payload` type from `ActionRecord`:
  *
  * ```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
+ * // ActionRecord declares: 'add_to_cart': {productId: number; qty: number}
+ * onAction('add_to_cart', (action) => {
+ *   cartService.add(action.payload.productId, action.payload.qty); // fully typed
+ *   console.log(action.context); // e.g. 'product-list' (from DOM) or undefined
  * });
  * ```
  *
@@ -24,7 +28,7 @@ export type { ModifierHandler, PayloadResolver };
  * // src/action-record.ts
  * declare module '@alwatr/action' {
  *   interface ActionRecord {
- *     'open-drawer': string;
+ *     'open_drawer': string;
  *   }
  * }
  * ```
@@ -32,83 +36,87 @@ export type { ModifierHandler, PayloadResolver };
  * Internally delegates to `ChannelSignal.on()` for **O(1) routing** — dispatching
  * action `'A'` never invokes handlers registered for action `'B'`.
  *
- * @param actionId - A key of `ActionRecord`.
- * @param handler  - Callback invoked with the typed payload on each dispatch.
+ * @param type    - A key of `ActionRecord`.
+ * @param handler - Callback invoked with the full `Action<K>` on each dispatch.
  * @returns A `SubscribeResult` with an `unsubscribe()` method for cleanup.
  *
  * @example
  * ```ts
  * import {onAction} from '@alwatr/action';
  *
- * const sub = onAction('page-ready', (pageId) => {
- *   router.setPage(pageId); // pageId: string — inferred from ActionRecord
+ * const sub = onAction('page_ready', (action) => {
+ *   router.setPage(action.payload); // payload: string — inferred from ActionRecord
  * });
  *
  * sub.unsubscribe(); // stop listening when no longer needed
  * ```
  */
-export declare function onAction<K extends keyof ActionRecord>(actionId: K, handler: (payload: ActionRecord[K]) => Awaitable<void>): SubscribeResult;
+export declare function onAction<K extends keyof ActionRecord>(type: K, handler: (action: Action<K>) => Awaitable<void>): SubscribeResult;
 /**
- * Dispatches a named action to all `onAction` subscribers with a matching `actionId`.
+ * Dispatches an action to all `onAction` subscribers with a matching `type`.
  *
- * `actionId` must be a key of `ActionRecord`. The `payload` parameter is
- * automatically typed — passing the wrong type is a **compile error**:
+ * Accepts a full `Action<K>` object. The `payload` field is automatically
+ * typed from `ActionRecord[K]` — passing the wrong shape 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({type: 'add_to_cart', payload: {productId: 42, qty: 1}}); // ✅
+ * dispatchAction({type: 'add_to_cart', payload: 'wrong'});                  // ❌ compile error
+ * dispatchAction({type: 'unknown_action', payload: 'x'});                   // ❌ compile error
  * ```
  *
- * Register new actions by extending `ActionRecord` via declaration merging:
- *
- * ```ts
- * // src/action-record.ts
- * declare module '@alwatr/action' {
- *   interface ActionRecord {
- *     'navigate': string;
- *     'logout': void;
- *   }
- * }
- * ```
+ * The `context` and `meta` fields are optional. When dispatching from code
+ * (not from the DOM), omit `context` — it is only meaningful for DOM-originated
+ * actions where an `[action-context]` ancestor exists.
  *
  * 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`.
+ * @param action - A full `Action<K>` object with at minimum `type` and `payload`.
  *
  * @example — with payload
  * ```ts
  * import {dispatchAction} from '@alwatr/action';
  *
- * dispatchAction('page-ready', 'home');
- * dispatchAction('navigate', '/dashboard');
+ * dispatchAction({type: 'navigate', payload: '/dashboard'});
+ * dispatchAction({type: 'add_to_cart', payload: {productId: 42, qty: 1}});
  * ```
  *
- * @example — void payload (no second argument)
+ * @example — void payload
  * ```ts
- * dispatchAction('logout');
+ * dispatchAction({type: 'logout', payload: undefined});
+ * ```
+ *
+ * @example — with context and meta
+ * ```ts
+ * dispatchAction({
+ *   type: 'slider_change',
+ *   payload: 75,
+ *   context: 'volume_slider',
+ *   meta: {traceId: 'abc-123'},
+ * });
  * ```
  */
-export declare function dispatchAction<K extends keyof ActionRecord>(...args: ActionRecord[K] extends void | undefined ? [actionId: K] : [actionId: K, actionPayload: ActionRecord[K]]): void;
+export declare function dispatchAction<K extends keyof ActionRecord>(action: Action<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
- * available. This function lets you add domain-specific ones.
+ * The handler also receives the **mutable** `action` object being built, so it
+ * can attach data to `action.meta` before the action reaches subscribers.
+ *
+ * Built-in modifiers (`prevent`, `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 - A `ModifierHandler` receiving `(event, element)`.
+ * @param name    - The modifier token (lowercase, no special characters).
+ * @param handler - A `ModifierHandler` receiving `(event, element, action)`.
  *
  * @example — a `confirm` modifier that shows a browser dialog
  * ```ts
@@ -117,20 +125,29 @@ 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>
+ * ```
+ *
+ * @example — a `trace` modifier that stamps a trace ID into meta
+ * ```ts
+ * registerModifier('trace', (_event, _element, action) => {
+ *   action.meta ??= {};
+ *   action.meta['traceId'] = crypto.randomUUID();
+ *   return true;
+ * });
  * ```
  */
 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
- * with an `ActionContext` as `this` and the DOM event as the argument.
- * The return value becomes the `actionPayload` passed to `onAction` subscribers.
+ * 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 the DOM event and the element. The return value becomes the `payload`
+ * field of the `Action` object passed to `onAction` subscribers.
  *
- * Built-in resolvers (`$value`, `$formdata`) are always available. This function
- * lets you add domain-specific ones.
+ * Built-in resolvers (`$value`, `$formdata`, `$checked`) are always available.
+ * This function lets you add domain-specific ones.
  *
  * Registering the same name twice logs an accident and overwrites the previous
  * resolver — avoid duplicate registrations in production code.
@@ -138,16 +155,16 @@ export declare function registerModifier(name: string, handler: ModifierHandler)
  * @param name     - The resolver token (should start with `$` by convention).
  * @param resolver - A `PayloadResolver` receiving `(event, element)`.
  *
- * @example — a `$checked` resolver for checkbox state
+ * @example — a `$data-id` resolver that reads a data attribute
  * ```ts
  * import {registerPayloadResolver} from '@alwatr/action';
  *
- * registerPayloadResolver('$checked', (_event, element) => {
- *   return (element as HTMLInputElement).checked;
+ * registerPayloadResolver('$data-id', (_event, element) => {
+ *   return (element as HTMLElement).dataset.id ?? null;
  * });
  * ```
  * ```html
- * <input type="checkbox" on-action="change->toggle-feature:$checked" />
+ * <button on-click="select_item:$data-id" data-id="42">Select</button>
  * ```
  */
 export declare function registerPayloadResolver(name: string, resolver: PayloadResolver): void;

package/dist/method.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"method.d.ts","sourceRoot":"","sources":["../src/method.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAEnD,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAoC,KAAK,eAAe,EAAE,KAAK,eAAe,EAAC,MAAM,eAAe,CAAC;AAC5G,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,oBAAoB,CAAC;AAGrD,YAAY,EAAC,eAAe,EAAE,eAAe,EAAC,CAAC;AAI/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,MAAM,YAAY,EACnD,QAAQ,EAAE,CAAC,EACX,OAAO,EAAE,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,IAAI,CAAC,GACrD,eAAe,CAGjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,YAAY,EACzD,GAAG,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,SAAS,IAAI,GAAG,SAAS,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,EAAE,aAAa,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,GAChH,IAAI,CAIN;AAID;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,IAAI,CAM7E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAMrF"}
+{"version":3,"file":"method.d.ts","sourceRoot":"","sources":["../src/method.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,gBAAgB,CAAC;AAGpD,OAAO,EAAoC,KAAK,eAAe,EAAE,KAAK,eAAe,EAAC,MAAM,eAAe,CAAC;AAC5G,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,aAAa,CAAC;AAGxC,YAAY,EAAC,eAAe,EAAE,eAAe,EAAC,CAAC;AAC/C,YAAY,EAAC,MAAM,EAAC,CAAC;AAIrB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,MAAM,YAAY,EACnD,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,IAAI,CAAC,GAC9C,eAAe,CAMjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,YAAY,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,IAAI,CAGpF;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,IAAI,CAM7E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAMrF"}

package/dist/registry.d.ts

@@ -1,35 +1,47 @@
+import type { Action } from './action.js';
 /**
- * A modifier handler used in `on-action` attribute syntax.
+ * A modifier handler used in `on-<eventType>` attribute syntax.
  *
- * Receives the triggering DOM `event` and the `element` that owns the
- * `on-action` attribute. Return `true` (or any truthy value) to allow the
- * action to proceed, or `false` to cancel the dispatch.
+ * Receives the triggering DOM `event`, the `element` that owns the
+ * `on-<eventType>` attribute, and the **mutable** `action` object being built.
+ * The handler may mutate `action.meta` to attach cross-cutting data (e.g. a
+ * trace ID, a timestamp, or an A/B flag) before the action reaches subscribers.
+ *
+ * Return `true` (or any truthy value) to allow the action to proceed, or
+ * `false` to cancel the dispatch entirely.
  *
  * Using explicit parameters instead of `this` binding makes handlers
  * compatible with arrow functions and easier to test in isolation.
  *
- * @example
+ * @example — a modifier that stamps a timestamp into meta
+ * ```ts
+ * const timestampHandler: ModifierHandler = (_event, _element, action) => {
+ *   action.meta ??= {};
+ *   action.meta['timestamp'] = Date.now();
+ *   return true;
+ * };
+ * ```
+ *
+ * @example — a modifier that cancels dispatch when the element is disabled
  * ```ts
- * // A modifier that only allows the action when the element is not disabled
  * const notDisabledHandler: ModifierHandler = (_event, element) => {
  *   return !(element as HTMLButtonElement).disabled;
  * };
  * ```
  */
-export type ModifierHandler = (event: Event, element: HTMLElement) => boolean;
+export type ModifierHandler = (event: Event, element: HTMLElement, action: Action) => boolean;
 /**
- * A payload resolver used in `on-action` attribute syntax.
+ * A payload resolver used in `on-<eventType>` attribute syntax.
  *
  * Receives the triggering DOM `event` and the `element` that owns the
- * `on-action` attribute. The return value becomes the `actionPayload` passed
- * to `onAction` subscribers. Use this to compute dynamic payloads from DOM state.
+ * `on-<eventType>` attribute. The return value becomes the `payload` field of
+ * the `Action` object passed to `onAction` subscribers.
  *
  * Using explicit parameters instead of `this` binding makes resolvers
  * compatible with arrow functions and easier to test in isolation.
  *
- * @example
+ * @example — a resolver that returns the element's dataset id
  * ```ts
- * // A resolver that returns the element's dataset id
  * const dataIdResolver: PayloadResolver = (_event, element) => {
  *   return (element as HTMLElement).dataset.id ?? null;
  * };
@@ -39,8 +51,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 +62,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/dist/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC;AAE9E;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC;AAI9E;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,8BAAqC,CAAC;AAEnE;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,8BAAqC,CAAC"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,aAAa,CAAC;AAIxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;AAE9F;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC;AAI9E;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,8BAAqC,CAAC;AAEnE;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,8BAAqC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alwatr/action",
-  "version": "9.14.0",
+  "version": "9.17.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": "782563375f55c55d29719cbcfebaca251d69ddcd"
 }

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/action.ts

@@ -0,0 +1,97 @@
+/**
+ * @file action.ts
+ *
+ * Defines the Alwatr Flux Standard Action (AFSA) — the single, unified data
+ * structure that flows through the entire action bus for both dispatch and
+ * subscription.
+ *
+ * ## Why a single Action object?
+ *
+ * Previously, `dispatchAction(id, payload)` and `onAction(id, handler(payload))`
+ * treated the action as two separate concerns: an identifier and a raw payload.
+ * This made it impossible to carry cross-cutting metadata (context, trace IDs,
+ * timestamps) without breaking every call site.
+ *
+ * AFSA wraps everything into one object:
+ * - `type`    — the action identifier (replaces the first positional argument)
+ * - `payload` — the business data (replaces the second positional argument)
+ * - `context` — the DOM context extracted from the nearest `[action-context]`
+ *               ancestor at delegation time; `undefined` for programmatic dispatches
+ * - `meta`    — open-ended bag for future cross-cutting concerns (trace IDs,
+ *               timestamps, A/B flags, etc.) without breaking the typed API
+ *
+ * Modifiers in the delegation pipeline can also mutate `meta` before the action
+ * reaches subscribers — e.g. a `trace` modifier could stamp a request ID.
+ */
+
+import type {DictionaryOpt} from '@alwatr/type-helper';
+import type {ActionRecord} from './action-record.js';
+
+/**
+ * Alwatr Flux Standard Action (AFSA).
+ *
+ * The single, canonical object passed to every `dispatchAction` call and
+ * received by every `onAction` handler. Keeping all action data in one
+ * structure makes the bus extensible without breaking existing call sites.
+ *
+ * @template K - A key of `ActionRecord`; constrains `type` and `payload` together.
+ *
+ * @example — dispatching
+ * ```ts
+ * dispatchAction({type: 'add_to_cart', payload: {productId: 42, qty: 1}});
+ * ```
+ *
+ * @example — subscribing
+ * ```ts
+ * onAction('add_to_cart', (action) => {
+ *   console.log(action.type);    // 'add_to_cart'
+ *   console.log(action.payload); // {productId: 42, qty: 1}
+ *   console.log(action.context); // e.g. 'product-list' (from DOM) or undefined
+ * });
+ * ```
+ */
+export interface Action<K extends keyof ActionRecord = keyof ActionRecord> {
+  /**
+   * Unique action identifier — must be a key of `ActionRecord`.
+   *
+   * @example 'cart:add-item', 'open_drawer', 'logout'
+   */
+  readonly type: K;
+
+  /**
+   * The DOM context in which the action was triggered.
+   *
+   * Extracted at delegation time from the nearest ancestor element that carries
+   * an `action-context` attribute. Useful for scoping the same action type to
+   * different UI regions (e.g. two sliders on the same page both dispatching
+   * `'slider:change'` but with different context values).
+   *
+   * `undefined` when the action is dispatched programmatically (no DOM involved)
+   * or when no `[action-context]` ancestor exists.
+   *
+   * @example 'slider-123', 'product-list', 'checkout-form'
+   */
+  readonly context?: string;
+
+  /**
+   * The pure business payload carried by this action.
+   *
+   * Type is inferred from `ActionRecord[K]` — the compiler enforces the correct
+   * shape at every call site. No manual generic annotation is needed.
+   */
+  readonly payload: ActionRecord[K];
+
+  /**
+   * Open-ended metadata bag for cross-cutting concerns.
+   *
+   * Intentionally untyped so that future infrastructure layers (tracing,
+   * analytics, A/B testing) can attach data without touching the typed API.
+   * Modifiers in the delegation pipeline may also write to `meta` before the
+   * action reaches subscribers.
+   *
+   * Treat values here as `unknown` and validate before use.
+   *
+   * @example {traceId: 'abc-123', timestamp: Date.now()}
+   */
+  meta?: DictionaryOpt<unknown>;
+}