@echothink-ui/events 0.1.0

package/README.md

@@ -0,0 +1,55 @@
+# @echothink-ui/events
+
+The backend-event contract for `@echothink-ui` components.
+
+`@echothink-ui` components expose plain React callbacks (`onClick`,
+`EthAction.onSelect`, form `onSubmit`, table `rowActions`) with no path to a
+backend process. This package provides the serializable binding shape and the
+host-injected dispatch that carry those events to a backend (ultimately
+`runProcess` → gateway), while staying structurally compatible with the
+echothink-fugue registry `EventBinding` / action-graph contract.
+
+## Pieces
+
+- `EthEventBinding` / `EthAction` — the serializable "when this event fires, run
+  these actions" shape a builder authors. Action kinds: `runProcess`,
+  `navigate`, `setState`, `openModal`, `closeModal`, `showToast`.
+- `EchoEventProvider` — the host injects a `dispatch(binding, payload, data)`
+  implementation here. A no-op default lets components render with no provider.
+- `useEchoEvents()` — returns `{ dispatch }`.
+- `useEthAction(binding)` — returns an `onSelect`/`onClick` handler to wire
+  `EthAction.onSelect` → dispatch (or `undefined` when unbound).
+- `useEthEventHandler(binding)` — returns a payload-carrying handler for events
+  that produce live data (form values, selected row, chosen rowAction).
+- `toRegistryEventBinding(binding)` — the edge adapter that renames the authoring
+  shape (`kind`/`payload`/`target`) to the registry action-graph shape
+  (`action`/`externalInput`/`route`/`modalId`/`key`).
+
+## Usage
+
+```tsx
+import {
+  EchoEventProvider,
+  useEthAction,
+  toRegistryEventBinding,
+  type EthEventBinding,
+} from "@echothink-ui/events";
+
+// Host wires dispatch to the registry/renderer action runtime:
+const dispatch = (binding, payload) => {
+  const reg = toRegistryEventBinding(binding);
+  pageRuntime.dispatch([reg], binding.event, { row: payload });
+};
+
+<EchoEventProvider dispatch={dispatch}>
+  <MyPage />
+</EchoEventProvider>;
+
+// Component wires a rich callback to a backend binding:
+function ArchiveButton({ binding }: { binding?: EthEventBinding }) {
+  const onSelect = useEthAction(binding);
+  return <Button onClick={onSelect}>Archive</Button>;
+}
+```
+
+See `../echothink-UI-components/docs/backend-events.md` for the full design.

package/dist/bridge.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `bridge` — the field-renaming adapter that turns an {@link EthEventBinding}
+ * (the UI-library shape, discriminant `kind`) into the echothink-fugue registry
+ * `EventBinding` shape (discriminant `action`) that
+ * `runActionGraph`/`runProcess` consume.
+ *
+ * This lives in the UI library (not the registry) so the UI side OWNS its
+ * authoring shape and the host's `dispatch` can be a thin `runActionGraph(
+ * toRegistryActions(binding.actions), ctx)`. It is the documented, single point
+ * where the two contracts meet — keeping the rest of `@echothink-ui/events`
+ * free of any registry coupling.
+ *
+ * The output objects are plain JSON-compatible records typed `unknown` at the
+ * boundary; the registry validates/narrows them with its own
+ * `validateActionGraph`. We do not import registry types here.
+ */
+import type { EthAction, EthEventBinding } from "./types.js";
+/** A registry-shaped action node (discriminant `action`). */
+export type RegistryActionNode = Record<string, unknown> & {
+    action: string;
+};
+/** A registry-shaped event binding (`{ event, actions: ActionNode[] }`). */
+export interface RegistryEventBinding {
+    event: string;
+    actions: RegistryActionNode[];
+}
+/**
+ * Convert one {@link EthAction} to the registry `ActionNode` shape. The mapping:
+ *  - `kind` → `action`
+ *  - `runProcess`: `payload` → `externalInput`, `target`/`expectedVersion`/`optimistic` pass through
+ *  - `navigate`: `target` → `route`, `params` pass through
+ *  - `setState`: `target` → `key`, `value` passes through
+ *  - `openModal`/`closeModal`: `target` → `modalId`
+ *  - `showToast`: `message`/`level` pass through
+ */
+export declare function toRegistryAction(action: EthAction): RegistryActionNode;
+/**
+ * Convert an {@link EthEventBinding} to the registry `EventBinding` shape. A host
+ * that speaks the registry contract uses this to adapt at the dispatch edge:
+ *
+ * ```ts
+ * const dispatch: EchoEventDispatch = (binding, payload) => {
+ *   const reg = toRegistryEventBinding(binding);
+ *   runtime.dispatch([reg], binding.event, { row: payload });
+ * };
+ * ```
+ */
+export declare function toRegistryEventBinding(binding: EthEventBinding): RegistryEventBinding;

package/dist/context.d.ts

@@ -0,0 +1,43 @@
+/**
+ * `EchoEventContext` — the injectable dispatch surface a component reads to send
+ * its authored {@link EthEventBinding} to the backend.
+ *
+ * Mirrors the registry's `EventDispatchContext` / `PageInteractionProvider`
+ * pattern: the UI library owns the CONTEXT + hooks; the HOST (the echothink-fugue
+ * renderer, a demo app, or a test) provides the real `dispatch` implementation
+ * that walks the action graph → `runProcess` → gateway. A NO-OP default lets
+ * components render with no provider, so standalone render/snapshot tests never
+ * crash.
+ */
+import { type ReactNode } from "react";
+import type { EchoEventDispatch } from "./types.js";
+/**
+ * The interaction surface a component reads via {@link useEchoEvents}. The host
+ * constructs the real one; absent a provider, {@link NOOP_DISPATCH} is used so
+ * components never crash.
+ */
+export interface EchoEventContextValue {
+    /** Carry a binding (+ live payload) to the backend. */
+    dispatch: EchoEventDispatch;
+}
+/**
+ * Provide an {@link EchoEventDispatch} (constructed by the host) to the
+ * component tree. The host's `dispatch` is the bridge to the backend — it
+ * typically adapts each {@link EthEventBinding} to the registry action graph and
+ * runs it through `runProcess` → gateway.
+ *
+ * ```tsx
+ * <EchoEventProvider dispatch={(binding, payload) => runtime.dispatch(binding, payload)}>
+ *   <MyAuthoredPage />
+ * </EchoEventProvider>
+ * ```
+ */
+export declare function EchoEventProvider({ dispatch, children, }: {
+    dispatch: EchoEventDispatch;
+    children: ReactNode;
+}): ReactNode;
+/**
+ * Read the {@link EchoEventContextValue}. Returns the no-op dispatch when no
+ * provider is mounted, so components (and their render tests) work standalone.
+ */
+export declare function useEchoEvents(): EchoEventContextValue;

package/dist/hooks.d.ts

@@ -0,0 +1,34 @@
+import type { EthDispatchData, EthEventBinding } from "./types.js";
+/**
+ * Build an `onSelect` / `onClick`-shaped handler from an {@link EthEventBinding}.
+ *
+ * Returns `undefined` when `binding` is absent, so a component can spread it into
+ * `EthAction.onSelect` and fall back to its own default when unbound:
+ *
+ * ```tsx
+ * const onSelect = useEthAction(action.binding);
+ * <Button onClick={onSelect}>{action.label}</Button>
+ * // or, for EthAction:
+ * { ...action, onSelect: useEthAction(action.binding) ?? action.onSelect }
+ * ```
+ *
+ * The optional `data` (current row / route params) is threaded into the dispatch
+ * so the host can resolve `field:` / `route:` payloads — matching the registry's
+ * `DispatchDataContext`.
+ */
+export declare function useEthAction(binding: EthEventBinding | undefined, data?: EthDispatchData): (() => void) | undefined;
+/**
+ * Build a payload-carrying handler from an {@link EthEventBinding} — for events
+ * that produce live data (form `onSubmit` values, the selected row, the chosen
+ * `rowAction` id). The returned function forwards whatever it is called with as
+ * the dispatch `payload`, so the host can merge it into the binding's actions.
+ *
+ * Returns a no-op (still callable) when `binding` is absent, so callers don't
+ * need to null-check at the call site.
+ *
+ * ```tsx
+ * const onSubmit = useEthEventHandler(binding);
+ * <form onSubmit={(e) => { e.preventDefault(); onSubmit(readFormValues(e)); }} />
+ * ```
+ */
+export declare function useEthEventHandler<P = unknown>(binding: EthEventBinding | undefined, data?: EthDispatchData): (payload?: P) => void;

package/dist/index.cjs

@@ -0,0 +1,128 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  EchoEventProvider: () => EchoEventProvider,
+  toRegistryAction: () => toRegistryAction,
+  toRegistryEventBinding: () => toRegistryEventBinding,
+  useEchoEvents: () => useEchoEvents,
+  useEthAction: () => useEthAction,
+  useEthEventHandler: () => useEthEventHandler
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/context.tsx
+var import_react = require("react");
+var NOOP_DISPATCH = () => {
+};
+var EchoEventContext = (0, import_react.createContext)({
+  dispatch: NOOP_DISPATCH
+});
+function EchoEventProvider({
+  dispatch,
+  children
+}) {
+  return (0, import_react.createElement)(
+    EchoEventContext.Provider,
+    { value: { dispatch } },
+    children
+  );
+}
+function useEchoEvents() {
+  return (0, import_react.useContext)(EchoEventContext);
+}
+
+// src/hooks.tsx
+var import_react2 = require("react");
+function useEthAction(binding, data) {
+  const { dispatch } = useEchoEvents();
+  return (0, import_react2.useCallback)(() => {
+    if (!binding) return;
+    void dispatch(binding, void 0, data);
+  }, [dispatch, binding, data]);
+}
+function useEthEventHandler(binding, data) {
+  const { dispatch } = useEchoEvents();
+  return (0, import_react2.useCallback)(
+    (payload) => {
+      if (!binding) return;
+      void dispatch(binding, payload, data);
+    },
+    [dispatch, binding, data]
+  );
+}
+
+// src/bridge.ts
+function toRegistryAction(action) {
+  switch (action.kind) {
+    case "runProcess":
+      return {
+        action: "runProcess",
+        process: action.process,
+        ...action.target !== void 0 ? { target: action.target } : {},
+        ...action.payload !== void 0 ? { externalInput: action.payload } : {},
+        ...action.expectedVersion !== void 0 ? { expectedVersion: action.expectedVersion } : {},
+        ...action.optimistic !== void 0 ? { optimistic: action.optimistic } : {}
+      };
+    case "navigate":
+      return {
+        action: "navigate",
+        route: action.target,
+        ...action.params !== void 0 ? { params: action.params } : {}
+      };
+    case "setState":
+      return {
+        action: "setState",
+        key: action.target,
+        ...action.value !== void 0 ? { value: action.value } : {}
+      };
+    case "openModal":
+      return { action: "openModal", modalId: action.target };
+    case "closeModal":
+      return { action: "closeModal", modalId: action.target };
+    case "showToast":
+      return {
+        action: "showToast",
+        message: action.message,
+        ...action.level !== void 0 ? { level: action.level } : {}
+      };
+    default: {
+      const unknownAction = action;
+      return { ...action, action: unknownAction.kind };
+    }
+  }
+}
+function toRegistryEventBinding(binding) {
+  return {
+    event: binding.event,
+    actions: (binding.actions ?? []).map(toRegistryAction)
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  EchoEventProvider,
+  toRegistryAction,
+  toRegistryEventBinding,
+  useEchoEvents,
+  useEthAction,
+  useEthEventHandler
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/context.tsx","../src/hooks.tsx","../src/bridge.ts"],"sourcesContent":["/**\n * `@echothink-ui/events` — public API.\n *\n * The backend-event contract for `@echothink-ui` components: a serializable\n * {@link EthEventBinding} (structurally compatible with the echothink-fugue\n * registry `EventBinding`), an {@link EchoEventProvider} the host uses to inject\n * a backend `dispatch`, a {@link useEchoEvents} hook, and component-facing\n * {@link useEthAction} / {@link useEthEventHandler} helpers that wire rich\n * semantic callbacks (`EthAction.onSelect`, form `onSubmit`, table `rowActions`)\n * to that dispatch. The {@link toRegistryEventBinding} bridge adapts the\n * authoring shape to the registry action-graph shape at the host edge.\n */\nexport type {\n  EthEventName,\n  EthActionTarget,\n  EthActionKind,\n  EthAction,\n  EthRunProcessAction,\n  EthNavigateAction,\n  EthSetStateAction,\n  EthOpenModalAction,\n  EthCloseModalAction,\n  EthShowToastAction,\n  EthEventBinding,\n  EthDispatchData,\n  EchoEventDispatch,\n} from \"./types.js\";\n\nexport {\n  EchoEventProvider,\n  useEchoEvents,\n  type EchoEventContextValue,\n} from \"./context.js\";\n\nexport { useEthAction, useEthEventHandler } from \"./hooks.js\";\n\nexport {\n  toRegistryAction,\n  toRegistryEventBinding,\n  type RegistryActionNode,\n  type RegistryEventBinding,\n} from \"./bridge.js\";\n","/**\n * `EchoEventContext` — the injectable dispatch surface a component reads to send\n * its authored {@link EthEventBinding} to the backend.\n *\n * Mirrors the registry's `EventDispatchContext` / `PageInteractionProvider`\n * pattern: the UI library owns the CONTEXT + hooks; the HOST (the echothink-fugue\n * renderer, a demo app, or a test) provides the real `dispatch` implementation\n * that walks the action graph → `runProcess` → gateway. A NO-OP default lets\n * components render with no provider, so standalone render/snapshot tests never\n * crash.\n */\nimport {\n  createContext,\n  createElement,\n  useContext,\n  type ReactNode,\n} from \"react\";\nimport type { EchoEventDispatch } from \"./types.js\";\n\n/**\n * The interaction surface a component reads via {@link useEchoEvents}. The host\n * constructs the real one; absent a provider, {@link NOOP_DISPATCH} is used so\n * components never crash.\n */\nexport interface EchoEventContextValue {\n  /** Carry a binding (+ live payload) to the backend. */\n  dispatch: EchoEventDispatch;\n}\n\n/** A no-op dispatch — used when no provider is mounted. */\nconst NOOP_DISPATCH: EchoEventDispatch = () => {};\n\nconst EchoEventContext = createContext<EchoEventContextValue>({\n  dispatch: NOOP_DISPATCH,\n});\n\n/**\n * Provide an {@link EchoEventDispatch} (constructed by the host) to the\n * component tree. The host's `dispatch` is the bridge to the backend — it\n * typically adapts each {@link EthEventBinding} to the registry action graph and\n * runs it through `runProcess` → gateway.\n *\n * ```tsx\n * <EchoEventProvider dispatch={(binding, payload) => runtime.dispatch(binding, payload)}>\n *   <MyAuthoredPage />\n * </EchoEventProvider>\n * ```\n */\nexport function EchoEventProvider({\n  dispatch,\n  children,\n}: {\n  dispatch: EchoEventDispatch;\n  children: ReactNode;\n}): ReactNode {\n  return createElement(\n    EchoEventContext.Provider,\n    { value: { dispatch } },\n    children,\n  );\n}\n\n/**\n * Read the {@link EchoEventContextValue}. Returns the no-op dispatch when no\n * provider is mounted, so components (and their render tests) work standalone.\n */\nexport function useEchoEvents(): EchoEventContextValue {\n  return useContext(EchoEventContext);\n}\n","/**\n * Component-facing helpers that wire a component's rich semantic callbacks\n * (`EthAction.onSelect`, `onClick`, form `onSubmit`, table `rowActions`) to a\n * backend {@link EthEventBinding} via the injected {@link EchoEventDispatch}.\n *\n * These are the OPT-IN seam: a component that wants backend-aware behavior takes\n * an optional `binding?: EthEventBinding` prop and calls one of these helpers to\n * produce the handler it passes to its native callback prop. A component with no\n * binding behaves exactly as today (the no-op dispatch is inert).\n */\nimport { useCallback } from \"react\";\nimport { useEchoEvents } from \"./context.js\";\nimport type { EthDispatchData, EthEventBinding } from \"./types.js\";\n\n/**\n * Build an `onSelect` / `onClick`-shaped handler from an {@link EthEventBinding}.\n *\n * Returns `undefined` when `binding` is absent, so a component can spread it into\n * `EthAction.onSelect` and fall back to its own default when unbound:\n *\n * ```tsx\n * const onSelect = useEthAction(action.binding);\n * <Button onClick={onSelect}>{action.label}</Button>\n * // or, for EthAction:\n * { ...action, onSelect: useEthAction(action.binding) ?? action.onSelect }\n * ```\n *\n * The optional `data` (current row / route params) is threaded into the dispatch\n * so the host can resolve `field:` / `route:` payloads — matching the registry's\n * `DispatchDataContext`.\n */\nexport function useEthAction(\n  binding: EthEventBinding | undefined,\n  data?: EthDispatchData,\n): (() => void) | undefined {\n  const { dispatch } = useEchoEvents();\n  return useCallback(() => {\n    if (!binding) return;\n    void dispatch(binding, undefined, data);\n  }, [dispatch, binding, data]);\n}\n\n/**\n * Build a payload-carrying handler from an {@link EthEventBinding} — for events\n * that produce live data (form `onSubmit` values, the selected row, the chosen\n * `rowAction` id). The returned function forwards whatever it is called with as\n * the dispatch `payload`, so the host can merge it into the binding's actions.\n *\n * Returns a no-op (still callable) when `binding` is absent, so callers don't\n * need to null-check at the call site.\n *\n * ```tsx\n * const onSubmit = useEthEventHandler(binding);\n * <form onSubmit={(e) => { e.preventDefault(); onSubmit(readFormValues(e)); }} />\n * ```\n */\nexport function useEthEventHandler<P = unknown>(\n  binding: EthEventBinding | undefined,\n  data?: EthDispatchData,\n): (payload?: P) => void {\n  const { dispatch } = useEchoEvents();\n  return useCallback(\n    (payload?: P) => {\n      if (!binding) return;\n      void dispatch(binding, payload, data);\n    },\n    [dispatch, binding, data],\n  );\n}\n","/**\n * `bridge` — the field-renaming adapter that turns an {@link EthEventBinding}\n * (the UI-library shape, discriminant `kind`) into the echothink-fugue registry\n * `EventBinding` shape (discriminant `action`) that\n * `runActionGraph`/`runProcess` consume.\n *\n * This lives in the UI library (not the registry) so the UI side OWNS its\n * authoring shape and the host's `dispatch` can be a thin `runActionGraph(\n * toRegistryActions(binding.actions), ctx)`. It is the documented, single point\n * where the two contracts meet — keeping the rest of `@echothink-ui/events`\n * free of any registry coupling.\n *\n * The output objects are plain JSON-compatible records typed `unknown` at the\n * boundary; the registry validates/narrows them with its own\n * `validateActionGraph`. We do not import registry types here.\n */\nimport type { EthAction, EthEventBinding } from \"./types.js\";\n\n/** A registry-shaped action node (discriminant `action`). */\nexport type RegistryActionNode = Record<string, unknown> & { action: string };\n\n/** A registry-shaped event binding (`{ event, actions: ActionNode[] }`). */\nexport interface RegistryEventBinding {\n  event: string;\n  actions: RegistryActionNode[];\n}\n\n/**\n * Convert one {@link EthAction} to the registry `ActionNode` shape. The mapping:\n *  - `kind` → `action`\n *  - `runProcess`: `payload` → `externalInput`, `target`/`expectedVersion`/`optimistic` pass through\n *  - `navigate`: `target` → `route`, `params` pass through\n *  - `setState`: `target` → `key`, `value` passes through\n *  - `openModal`/`closeModal`: `target` → `modalId`\n *  - `showToast`: `message`/`level` pass through\n */\nexport function toRegistryAction(action: EthAction): RegistryActionNode {\n  switch (action.kind) {\n    case \"runProcess\":\n      return {\n        action: \"runProcess\",\n        process: action.process,\n        ...(action.target !== undefined ? { target: action.target } : {}),\n        ...(action.payload !== undefined ? { externalInput: action.payload } : {}),\n        ...(action.expectedVersion !== undefined\n          ? { expectedVersion: action.expectedVersion }\n          : {}),\n        ...(action.optimistic !== undefined ? { optimistic: action.optimistic } : {}),\n      };\n    case \"navigate\":\n      return {\n        action: \"navigate\",\n        route: action.target,\n        ...(action.params !== undefined ? { params: action.params } : {}),\n      };\n    case \"setState\":\n      return {\n        action: \"setState\",\n        key: action.target,\n        ...(action.value !== undefined ? { value: action.value } : {}),\n      };\n    case \"openModal\":\n      return { action: \"openModal\", modalId: action.target };\n    case \"closeModal\":\n      return { action: \"closeModal\", modalId: action.target };\n    case \"showToast\":\n      return {\n        action: \"showToast\",\n        message: action.message,\n        ...(action.level !== undefined ? { level: action.level } : {}),\n      };\n    default: {\n      // Forward-compatible: pass an unknown kind through as its own action.\n      const unknownAction = action as { kind: string };\n      return { ...(action as Record<string, unknown>), action: unknownAction.kind };\n    }\n  }\n}\n\n/**\n * Convert an {@link EthEventBinding} to the registry `EventBinding` shape. A host\n * that speaks the registry contract uses this to adapt at the dispatch edge:\n *\n * ```ts\n * const dispatch: EchoEventDispatch = (binding, payload) => {\n *   const reg = toRegistryEventBinding(binding);\n *   runtime.dispatch([reg], binding.event, { row: payload });\n * };\n * ```\n */\nexport function toRegistryEventBinding(binding: EthEventBinding): RegistryEventBinding {\n  return {\n    event: binding.event,\n    actions: (binding.actions ?? []).map(toRegistryAction),\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACWA,mBAKO;AAcP,IAAM,gBAAmC,MAAM;AAAC;AAEhD,IAAM,uBAAmB,4BAAqC;AAAA,EAC5D,UAAU;AACZ,CAAC;AAcM,SAAS,kBAAkB;AAAA,EAChC;AAAA,EACA;AACF,GAGc;AACZ,aAAO;AAAA,IACL,iBAAiB;AAAA,IACjB,EAAE,OAAO,EAAE,SAAS,EAAE;AAAA,IACtB;AAAA,EACF;AACF;AAMO,SAAS,gBAAuC;AACrD,aAAO,yBAAW,gBAAgB;AACpC;;;AC1DA,IAAAA,gBAA4B;AAqBrB,SAAS,aACd,SACA,MAC0B;AAC1B,QAAM,EAAE,SAAS,IAAI,cAAc;AACnC,aAAO,2BAAY,MAAM;AACvB,QAAI,CAAC,QAAS;AACd,SAAK,SAAS,SAAS,QAAW,IAAI;AAAA,EACxC,GAAG,CAAC,UAAU,SAAS,IAAI,CAAC;AAC9B;AAgBO,SAAS,mBACd,SACA,MACuB;AACvB,QAAM,EAAE,SAAS,IAAI,cAAc;AACnC,aAAO;AAAA,IACL,CAAC,YAAgB;AACf,UAAI,CAAC,QAAS;AACd,WAAK,SAAS,SAAS,SAAS,IAAI;AAAA,IACtC;AAAA,IACA,CAAC,UAAU,SAAS,IAAI;AAAA,EAC1B;AACF;;;AChCO,SAAS,iBAAiB,QAAuC;AACtE,UAAQ,OAAO,MAAM;AAAA,IACnB,KAAK;AACH,aAAO;AAAA,QACL,QAAQ;AAAA,QACR,SAAS,OAAO;AAAA,QAChB,GAAI,OAAO,WAAW,SAAY,EAAE,QAAQ,OAAO,OAAO,IAAI,CAAC;AAAA,QAC/D,GAAI,OAAO,YAAY,SAAY,EAAE,eAAe,OAAO,QAAQ,IAAI,CAAC;AAAA,QACxE,GAAI,OAAO,oBAAoB,SAC3B,EAAE,iBAAiB,OAAO,gBAAgB,IAC1C,CAAC;AAAA,QACL,GAAI,OAAO,eAAe,SAAY,EAAE,YAAY,OAAO,WAAW,IAAI,CAAC;AAAA,MAC7E;AAAA,IACF,KAAK;AACH,aAAO;AAAA,QACL,QAAQ;AAAA,QACR,OAAO,OAAO;AAAA,QACd,GAAI,OAAO,WAAW,SAAY,EAAE,QAAQ,OAAO,OAAO,IAAI,CAAC;AAAA,MACjE;AAAA,IACF,KAAK;AACH,aAAO;AAAA,QACL,QAAQ;AAAA,QACR,KAAK,OAAO;AAAA,QACZ,GAAI,OAAO,UAAU,SAAY,EAAE,OAAO,OAAO,MAAM,IAAI,CAAC;AAAA,MAC9D;AAAA,IACF,KAAK;AACH,aAAO,EAAE,QAAQ,aAAa,SAAS,OAAO,OAAO;AAAA,IACvD,KAAK;AACH,aAAO,EAAE,QAAQ,cAAc,SAAS,OAAO,OAAO;AAAA,IACxD,KAAK;AACH,aAAO;AAAA,QACL,QAAQ;AAAA,QACR,SAAS,OAAO;AAAA,QAChB,GAAI,OAAO,UAAU,SAAY,EAAE,OAAO,OAAO,MAAM,IAAI,CAAC;AAAA,MAC9D;AAAA,IACF,SAAS;AAEP,YAAM,gBAAgB;AACtB,aAAO,EAAE,GAAI,QAAoC,QAAQ,cAAc,KAAK;AAAA,IAC9E;AAAA,EACF;AACF;AAaO,SAAS,uBAAuB,SAAgD;AACrF,SAAO;AAAA,IACL,OAAO,QAAQ;AAAA,IACf,UAAU,QAAQ,WAAW,CAAC,GAAG,IAAI,gBAAgB;AAAA,EACvD;AACF;","names":["import_react"]}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `@echothink-ui/events` — public API.
+ *
+ * The backend-event contract for `@echothink-ui` components: a serializable
+ * {@link EthEventBinding} (structurally compatible with the echothink-fugue
+ * registry `EventBinding`), an {@link EchoEventProvider} the host uses to inject
+ * a backend `dispatch`, a {@link useEchoEvents} hook, and component-facing
+ * {@link useEthAction} / {@link useEthEventHandler} helpers that wire rich
+ * semantic callbacks (`EthAction.onSelect`, form `onSubmit`, table `rowActions`)
+ * to that dispatch. The {@link toRegistryEventBinding} bridge adapts the
+ * authoring shape to the registry action-graph shape at the host edge.
+ */
+export type { EthEventName, EthActionTarget, EthActionKind, EthAction, EthRunProcessAction, EthNavigateAction, EthSetStateAction, EthOpenModalAction, EthCloseModalAction, EthShowToastAction, EthEventBinding, EthDispatchData, EchoEventDispatch, } from "./types.js";
+export { EchoEventProvider, useEchoEvents, type EchoEventContextValue, } from "./context.js";
+export { useEthAction, useEthEventHandler } from "./hooks.js";
+export { toRegistryAction, toRegistryEventBinding, type RegistryActionNode, type RegistryEventBinding, } from "./bridge.js";

package/dist/index.js

@@ -0,0 +1,100 @@
+// src/context.tsx
+import {
+  createContext,
+  createElement,
+  useContext
+} from "react";
+var NOOP_DISPATCH = () => {
+};
+var EchoEventContext = createContext({
+  dispatch: NOOP_DISPATCH
+});
+function EchoEventProvider({
+  dispatch,
+  children
+}) {
+  return createElement(
+    EchoEventContext.Provider,
+    { value: { dispatch } },
+    children
+  );
+}
+function useEchoEvents() {
+  return useContext(EchoEventContext);
+}
+
+// src/hooks.tsx
+import { useCallback } from "react";
+function useEthAction(binding, data) {
+  const { dispatch } = useEchoEvents();
+  return useCallback(() => {
+    if (!binding) return;
+    void dispatch(binding, void 0, data);
+  }, [dispatch, binding, data]);
+}
+function useEthEventHandler(binding, data) {
+  const { dispatch } = useEchoEvents();
+  return useCallback(
+    (payload) => {
+      if (!binding) return;
+      void dispatch(binding, payload, data);
+    },
+    [dispatch, binding, data]
+  );
+}
+
+// src/bridge.ts
+function toRegistryAction(action) {
+  switch (action.kind) {
+    case "runProcess":
+      return {
+        action: "runProcess",
+        process: action.process,
+        ...action.target !== void 0 ? { target: action.target } : {},
+        ...action.payload !== void 0 ? { externalInput: action.payload } : {},
+        ...action.expectedVersion !== void 0 ? { expectedVersion: action.expectedVersion } : {},
+        ...action.optimistic !== void 0 ? { optimistic: action.optimistic } : {}
+      };
+    case "navigate":
+      return {
+        action: "navigate",
+        route: action.target,
+        ...action.params !== void 0 ? { params: action.params } : {}
+      };
+    case "setState":
+      return {
+        action: "setState",
+        key: action.target,
+        ...action.value !== void 0 ? { value: action.value } : {}
+      };
+    case "openModal":
+      return { action: "openModal", modalId: action.target };
+    case "closeModal":
+      return { action: "closeModal", modalId: action.target };
+    case "showToast":
+      return {
+        action: "showToast",
+        message: action.message,
+        ...action.level !== void 0 ? { level: action.level } : {}
+      };
+    default: {
+      const unknownAction = action;
+      return { ...action, action: unknownAction.kind };
+    }
+  }
+}
+function toRegistryEventBinding(binding) {
+  return {
+    event: binding.event,
+    actions: (binding.actions ?? []).map(toRegistryAction)
+  };
+}
+export {
+  EchoEventProvider,
+  toRegistryAction,
+  toRegistryEventBinding,
+  useEchoEvents,
+  useEthAction,
+  useEthEventHandler
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/context.tsx","../src/hooks.tsx","../src/bridge.ts"],"sourcesContent":["/**\n * `EchoEventContext` — the injectable dispatch surface a component reads to send\n * its authored {@link EthEventBinding} to the backend.\n *\n * Mirrors the registry's `EventDispatchContext` / `PageInteractionProvider`\n * pattern: the UI library owns the CONTEXT + hooks; the HOST (the echothink-fugue\n * renderer, a demo app, or a test) provides the real `dispatch` implementation\n * that walks the action graph → `runProcess` → gateway. A NO-OP default lets\n * components render with no provider, so standalone render/snapshot tests never\n * crash.\n */\nimport {\n  createContext,\n  createElement,\n  useContext,\n  type ReactNode,\n} from \"react\";\nimport type { EchoEventDispatch } from \"./types.js\";\n\n/**\n * The interaction surface a component reads via {@link useEchoEvents}. The host\n * constructs the real one; absent a provider, {@link NOOP_DISPATCH} is used so\n * components never crash.\n */\nexport interface EchoEventContextValue {\n  /** Carry a binding (+ live payload) to the backend. */\n  dispatch: EchoEventDispatch;\n}\n\n/** A no-op dispatch — used when no provider is mounted. */\nconst NOOP_DISPATCH: EchoEventDispatch = () => {};\n\nconst EchoEventContext = createContext<EchoEventContextValue>({\n  dispatch: NOOP_DISPATCH,\n});\n\n/**\n * Provide an {@link EchoEventDispatch} (constructed by the host) to the\n * component tree. The host's `dispatch` is the bridge to the backend — it\n * typically adapts each {@link EthEventBinding} to the registry action graph and\n * runs it through `runProcess` → gateway.\n *\n * ```tsx\n * <EchoEventProvider dispatch={(binding, payload) => runtime.dispatch(binding, payload)}>\n *   <MyAuthoredPage />\n * </EchoEventProvider>\n * ```\n */\nexport function EchoEventProvider({\n  dispatch,\n  children,\n}: {\n  dispatch: EchoEventDispatch;\n  children: ReactNode;\n}): ReactNode {\n  return createElement(\n    EchoEventContext.Provider,\n    { value: { dispatch } },\n    children,\n  );\n}\n\n/**\n * Read the {@link EchoEventContextValue}. Returns the no-op dispatch when no\n * provider is mounted, so components (and their render tests) work standalone.\n */\nexport function useEchoEvents(): EchoEventContextValue {\n  return useContext(EchoEventContext);\n}\n","/**\n * Component-facing helpers that wire a component's rich semantic callbacks\n * (`EthAction.onSelect`, `onClick`, form `onSubmit`, table `rowActions`) to a\n * backend {@link EthEventBinding} via the injected {@link EchoEventDispatch}.\n *\n * These are the OPT-IN seam: a component that wants backend-aware behavior takes\n * an optional `binding?: EthEventBinding` prop and calls one of these helpers to\n * produce the handler it passes to its native callback prop. A component with no\n * binding behaves exactly as today (the no-op dispatch is inert).\n */\nimport { useCallback } from \"react\";\nimport { useEchoEvents } from \"./context.js\";\nimport type { EthDispatchData, EthEventBinding } from \"./types.js\";\n\n/**\n * Build an `onSelect` / `onClick`-shaped handler from an {@link EthEventBinding}.\n *\n * Returns `undefined` when `binding` is absent, so a component can spread it into\n * `EthAction.onSelect` and fall back to its own default when unbound:\n *\n * ```tsx\n * const onSelect = useEthAction(action.binding);\n * <Button onClick={onSelect}>{action.label}</Button>\n * // or, for EthAction:\n * { ...action, onSelect: useEthAction(action.binding) ?? action.onSelect }\n * ```\n *\n * The optional `data` (current row / route params) is threaded into the dispatch\n * so the host can resolve `field:` / `route:` payloads — matching the registry's\n * `DispatchDataContext`.\n */\nexport function useEthAction(\n  binding: EthEventBinding | undefined,\n  data?: EthDispatchData,\n): (() => void) | undefined {\n  const { dispatch } = useEchoEvents();\n  return useCallback(() => {\n    if (!binding) return;\n    void dispatch(binding, undefined, data);\n  }, [dispatch, binding, data]);\n}\n\n/**\n * Build a payload-carrying handler from an {@link EthEventBinding} — for events\n * that produce live data (form `onSubmit` values, the selected row, the chosen\n * `rowAction` id). The returned function forwards whatever it is called with as\n * the dispatch `payload`, so the host can merge it into the binding's actions.\n *\n * Returns a no-op (still callable) when `binding` is absent, so callers don't\n * need to null-check at the call site.\n *\n * ```tsx\n * const onSubmit = useEthEventHandler(binding);\n * <form onSubmit={(e) => { e.preventDefault(); onSubmit(readFormValues(e)); }} />\n * ```\n */\nexport function useEthEventHandler<P = unknown>(\n  binding: EthEventBinding | undefined,\n  data?: EthDispatchData,\n): (payload?: P) => void {\n  const { dispatch } = useEchoEvents();\n  return useCallback(\n    (payload?: P) => {\n      if (!binding) return;\n      void dispatch(binding, payload, data);\n    },\n    [dispatch, binding, data],\n  );\n}\n","/**\n * `bridge` — the field-renaming adapter that turns an {@link EthEventBinding}\n * (the UI-library shape, discriminant `kind`) into the echothink-fugue registry\n * `EventBinding` shape (discriminant `action`) that\n * `runActionGraph`/`runProcess` consume.\n *\n * This lives in the UI library (not the registry) so the UI side OWNS its\n * authoring shape and the host's `dispatch` can be a thin `runActionGraph(\n * toRegistryActions(binding.actions), ctx)`. It is the documented, single point\n * where the two contracts meet — keeping the rest of `@echothink-ui/events`\n * free of any registry coupling.\n *\n * The output objects are plain JSON-compatible records typed `unknown` at the\n * boundary; the registry validates/narrows them with its own\n * `validateActionGraph`. We do not import registry types here.\n */\nimport type { EthAction, EthEventBinding } from \"./types.js\";\n\n/** A registry-shaped action node (discriminant `action`). */\nexport type RegistryActionNode = Record<string, unknown> & { action: string };\n\n/** A registry-shaped event binding (`{ event, actions: ActionNode[] }`). */\nexport interface RegistryEventBinding {\n  event: string;\n  actions: RegistryActionNode[];\n}\n\n/**\n * Convert one {@link EthAction} to the registry `ActionNode` shape. The mapping:\n *  - `kind` → `action`\n *  - `runProcess`: `payload` → `externalInput`, `target`/`expectedVersion`/`optimistic` pass through\n *  - `navigate`: `target` → `route`, `params` pass through\n *  - `setState`: `target` → `key`, `value` passes through\n *  - `openModal`/`closeModal`: `target` → `modalId`\n *  - `showToast`: `message`/`level` pass through\n */\nexport function toRegistryAction(action: EthAction): RegistryActionNode {\n  switch (action.kind) {\n    case \"runProcess\":\n      return {\n        action: \"runProcess\",\n        process: action.process,\n        ...(action.target !== undefined ? { target: action.target } : {}),\n        ...(action.payload !== undefined ? { externalInput: action.payload } : {}),\n        ...(action.expectedVersion !== undefined\n          ? { expectedVersion: action.expectedVersion }\n          : {}),\n        ...(action.optimistic !== undefined ? { optimistic: action.optimistic } : {}),\n      };\n    case \"navigate\":\n      return {\n        action: \"navigate\",\n        route: action.target,\n        ...(action.params !== undefined ? { params: action.params } : {}),\n      };\n    case \"setState\":\n      return {\n        action: \"setState\",\n        key: action.target,\n        ...(action.value !== undefined ? { value: action.value } : {}),\n      };\n    case \"openModal\":\n      return { action: \"openModal\", modalId: action.target };\n    case \"closeModal\":\n      return { action: \"closeModal\", modalId: action.target };\n    case \"showToast\":\n      return {\n        action: \"showToast\",\n        message: action.message,\n        ...(action.level !== undefined ? { level: action.level } : {}),\n      };\n    default: {\n      // Forward-compatible: pass an unknown kind through as its own action.\n      const unknownAction = action as { kind: string };\n      return { ...(action as Record<string, unknown>), action: unknownAction.kind };\n    }\n  }\n}\n\n/**\n * Convert an {@link EthEventBinding} to the registry `EventBinding` shape. A host\n * that speaks the registry contract uses this to adapt at the dispatch edge:\n *\n * ```ts\n * const dispatch: EchoEventDispatch = (binding, payload) => {\n *   const reg = toRegistryEventBinding(binding);\n *   runtime.dispatch([reg], binding.event, { row: payload });\n * };\n * ```\n */\nexport function toRegistryEventBinding(binding: EthEventBinding): RegistryEventBinding {\n  return {\n    event: binding.event,\n    actions: (binding.actions ?? []).map(toRegistryAction),\n  };\n}\n"],"mappings":";AAWA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OAEK;AAcP,IAAM,gBAAmC,MAAM;AAAC;AAEhD,IAAM,mBAAmB,cAAqC;AAAA,EAC5D,UAAU;AACZ,CAAC;AAcM,SAAS,kBAAkB;AAAA,EAChC;AAAA,EACA;AACF,GAGc;AACZ,SAAO;AAAA,IACL,iBAAiB;AAAA,IACjB,EAAE,OAAO,EAAE,SAAS,EAAE;AAAA,IACtB;AAAA,EACF;AACF;AAMO,SAAS,gBAAuC;AACrD,SAAO,WAAW,gBAAgB;AACpC;;;AC1DA,SAAS,mBAAmB;AAqBrB,SAAS,aACd,SACA,MAC0B;AAC1B,QAAM,EAAE,SAAS,IAAI,cAAc;AACnC,SAAO,YAAY,MAAM;AACvB,QAAI,CAAC,QAAS;AACd,SAAK,SAAS,SAAS,QAAW,IAAI;AAAA,EACxC,GAAG,CAAC,UAAU,SAAS,IAAI,CAAC;AAC9B;AAgBO,SAAS,mBACd,SACA,MACuB;AACvB,QAAM,EAAE,SAAS,IAAI,cAAc;AACnC,SAAO;AAAA,IACL,CAAC,YAAgB;AACf,UAAI,CAAC,QAAS;AACd,WAAK,SAAS,SAAS,SAAS,IAAI;AAAA,IACtC;AAAA,IACA,CAAC,UAAU,SAAS,IAAI;AAAA,EAC1B;AACF;;;AChCO,SAAS,iBAAiB,QAAuC;AACtE,UAAQ,OAAO,MAAM;AAAA,IACnB,KAAK;AACH,aAAO;AAAA,QACL,QAAQ;AAAA,QACR,SAAS,OAAO;AAAA,QAChB,GAAI,OAAO,WAAW,SAAY,EAAE,QAAQ,OAAO,OAAO,IAAI,CAAC;AAAA,QAC/D,GAAI,OAAO,YAAY,SAAY,EAAE,eAAe,OAAO,QAAQ,IAAI,CAAC;AAAA,QACxE,GAAI,OAAO,oBAAoB,SAC3B,EAAE,iBAAiB,OAAO,gBAAgB,IAC1C,CAAC;AAAA,QACL,GAAI,OAAO,eAAe,SAAY,EAAE,YAAY,OAAO,WAAW,IAAI,CAAC;AAAA,MAC7E;AAAA,IACF,KAAK;AACH,aAAO;AAAA,QACL,QAAQ;AAAA,QACR,OAAO,OAAO;AAAA,QACd,GAAI,OAAO,WAAW,SAAY,EAAE,QAAQ,OAAO,OAAO,IAAI,CAAC;AAAA,MACjE;AAAA,IACF,KAAK;AACH,aAAO;AAAA,QACL,QAAQ;AAAA,QACR,KAAK,OAAO;AAAA,QACZ,GAAI,OAAO,UAAU,SAAY,EAAE,OAAO,OAAO,MAAM,IAAI,CAAC;AAAA,MAC9D;AAAA,IACF,KAAK;AACH,aAAO,EAAE,QAAQ,aAAa,SAAS,OAAO,OAAO;AAAA,IACvD,KAAK;AACH,aAAO,EAAE,QAAQ,cAAc,SAAS,OAAO,OAAO;AAAA,IACxD,KAAK;AACH,aAAO;AAAA,QACL,QAAQ;AAAA,QACR,SAAS,OAAO;AAAA,QAChB,GAAI,OAAO,UAAU,SAAY,EAAE,OAAO,OAAO,MAAM,IAAI,CAAC;AAAA,MAC9D;AAAA,IACF,SAAS;AAEP,YAAM,gBAAgB;AACtB,aAAO,EAAE,GAAI,QAAoC,QAAQ,cAAc,KAAK;AAAA,IAC9E;AAAA,EACF;AACF;AAaO,SAAS,uBAAuB,SAAgD;AACrF,SAAO;AAAA,IACL,OAAO,QAAQ;AAAA,IACf,UAAU,QAAQ,WAAW,CAAC,GAAG,IAAI,gBAAgB;AAAA,EACvD;AACF;","names":[]}

package/dist/types.d.ts

@@ -0,0 +1,125 @@
+/**
+ * `@echothink-ui/events` — the BACKEND-EVENT CONTRACT for `@echothink-ui`
+ * components.
+ *
+ * `@echothink-ui` components expose plain React callbacks (`onClick`,
+ * `onSelect`, `EthAction.onSelect`, form `onSubmit`, table `rowActions`) with no
+ * path to a backend process/action. This module defines the serializable
+ * data shape — {@link EthEventBinding} + {@link EthAction} — that lets a
+ * builder-authored page declare "when this UI event fires, run these backend
+ * actions", plus the {@link EchoEventDispatch} contract a HOST injects to
+ * actually carry those actions to a backend (ultimately `runProcess` → gateway).
+ *
+ * STRUCTURAL COMPATIBILITY (the load-bearing constraint): these types are kept
+ * field-for-field compatible with the echothink-fugue registry's `EventBinding`
+ * / `ActionNode` contract (see `echothink-component-registry/.../events.tsx` and
+ * `echothink-app-renderer/.../logic/graph.ts`). A plain `EthEventBinding[]`
+ * array produced here flows through that registry's `eventsAware` HOC →
+ * `PageInteractionRuntime.dispatch` → `runActionGraph` → `runProcess` WITHOUT
+ * conversion. We deliberately DO NOT import the registry types (that would
+ * invert the dependency direction — the registry/renderer depend on the UI
+ * library, never the reverse); we mirror the shapes locally instead.
+ */
+/**
+ * The known UI event names. Kept open (`string & {}`) so custom / semantic
+ * events (e.g. `"onRowAction:archive"`) flow through, mirroring the registry's
+ * `EventName`.
+ */
+export type EthEventName = "onClick" | "onSelect" | "onSubmit" | "onChange" | "onLoad" | (string & {});
+/** Optimistic-process target reference (the entity the process acts on). */
+export interface EthActionTarget {
+    entityType?: string;
+    entityId?: string;
+}
+/**
+ * The action discriminant — the verbs the host runtime knows how to perform.
+ * Kept identical to the registry `ActionNode["action"]` vocabulary (the subset a
+ * UI component realistically authors); unknown kinds are tolerated by the
+ * runtime, so this stays forward-compatible.
+ */
+export type EthActionKind = "runProcess" | "navigate" | "setState" | "openModal" | "closeModal" | "showToast";
+/** Invoke a unit process through the host runtime (ultimately the gateway). */
+export interface EthRunProcessAction {
+    kind: "runProcess";
+    /** The unit-process name to invoke. */
+    process: string;
+    target?: EthActionTarget;
+    /** Inline payload for the process. May contain `field:` / `route:` refs. */
+    payload?: Record<string, unknown>;
+    expectedVersion?: number;
+    /** Hint that the UI applied an optimistic change before this ran. */
+    optimistic?: boolean;
+}
+/** Client-side navigation to a route, with optional params. */
+export interface EthNavigateAction {
+    kind: "navigate";
+    /** Target route / href. */
+    target: string;
+    params?: Record<string, string>;
+}
+/** Set a page-scoped state key to a value. */
+export interface EthSetStateAction {
+    kind: "setState";
+    /** State key to set. */
+    target: string;
+    value?: unknown;
+}
+/** Open a modal by id. */
+export interface EthOpenModalAction {
+    kind: "openModal";
+    /** Modal id to open. */
+    target: string;
+}
+/** Close a modal by id. */
+export interface EthCloseModalAction {
+    kind: "closeModal";
+    /** Modal id to close. */
+    target: string;
+}
+/** Surface a transient toast notification. */
+export interface EthShowToastAction {
+    kind: "showToast";
+    /** Toast message (the `target` mirrors `message` for field uniformity). */
+    message: string;
+    level?: "info" | "success" | "error";
+}
+/** The action union an {@link EthEventBinding} carries (discriminant: `kind`). */
+export type EthAction = EthRunProcessAction | EthNavigateAction | EthSetStateAction | EthOpenModalAction | EthCloseModalAction | EthShowToastAction;
+/**
+ * An event → action(s) binding attached to a component (the value a builder
+ * authors). When the named `event` fires the host runs `actions` in order.
+ *
+ * Structurally compatible with the registry `EventBinding` — see the conversion
+ * note in {@link toRegistryEventBinding}: `event` is the same field; the
+ * registry calls its action list `actions` with an `action` discriminant, while
+ * we use `kind` for ergonomics. {@link toRegistryEventBinding} renames the two
+ * fields (`kind`→`action`, `payload`→`externalInput`, `target`→`route`/`modalId`/`key`)
+ * so a host that speaks the registry contract can adapt at the edge.
+ */
+export interface EthEventBinding {
+    /** The UI event this binding reacts to. */
+    event: EthEventName;
+    /** The ordered backend/client actions to run when `event` fires. */
+    actions: EthAction[];
+}
+/**
+ * Optional dispatch-time data context, structurally compatible with the
+ * registry's `DispatchDataContext` / `EventDispatchData` — `row` is the current
+ * data-binding row (for `field:` resolution), `route` the route params.
+ */
+export interface EthDispatchData {
+    row?: Record<string, unknown>;
+    route?: Record<string, string>;
+}
+/**
+ * The capability a HOST injects (via {@link EchoEventProvider}) to carry a
+ * component's authored binding to the backend. `payload` is the live runtime
+ * data captured at the event (e.g. the form values, the selected row, the
+ * chosen action id). The host is responsible for merging `payload` into the
+ * binding's actions and running them (typically by adapting to the registry
+ * action graph → `runProcess` → gateway).
+ *
+ * Returns the host's promise so callers MAY await completion (e.g. to clear an
+ * optimistic flag); a fire-and-forget host returns `void`.
+ */
+export type EchoEventDispatch = (binding: EthEventBinding, payload?: unknown, data?: EthDispatchData) => void | Promise<void>;

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@echothink-ui/events",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "react": ">=18.3.0",
+    "react-dom": ">=18.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.9.1",
+    "@types/react": "^19.2.2",
+    "@types/react-dom": "^19.2.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --sourcemap --clean --external react --external react-dom && tsc -p tsconfig.json --declaration --emitDeclarationOnly --noEmit false --outDir dist",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run --root . --config ../echothink-UI-components/vitest.config.ts --passWithNoTests",
+    "lint": "eslint src"
+  }
+}

package/src/__tests__/events.test.tsx

@@ -0,0 +1,159 @@
+import { describe, it, expect, vi } from "vitest";
+import * as React from "react";
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+
+// Opt into React's act() testing environment so state updates flush synchronously
+// and React does not warn about an unconfigured act environment.
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+import {
+  EchoEventProvider,
+  useEthAction,
+  useEthEventHandler,
+  toRegistryEventBinding,
+  type EchoEventDispatch,
+  type EthEventBinding,
+} from "../index.js";
+
+/* A binding a builder would author for a Button → backend process. */
+const archiveBinding: EthEventBinding = {
+  event: "onSelect",
+  actions: [
+    { kind: "runProcess", process: "ArchiveOrder", payload: { reason: "stale" } },
+    { kind: "showToast", message: "Archived", level: "success" },
+  ],
+};
+
+/** Mount a component into a real DOM container (jsdom) and return cleanup. */
+function mount(ui: React.ReactElement) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const root = createRoot(container);
+  act(() => {
+    root.render(ui);
+  });
+  return {
+    container,
+    cleanup() {
+      act(() => root.unmount());
+      container.remove();
+    },
+  };
+}
+
+/* A tiny component that wires EthAction.onSelect → useEthAction(binding). */
+function ArchiveButton({ binding }: { binding?: EthEventBinding }) {
+  const onSelect = useEthAction(binding);
+  return (
+    <button type="button" data-testid="archive" onClick={onSelect}>
+      Archive
+    </button>
+  );
+}
+
+/* A component that forwards live payload (form values) through the handler. */
+function SubmitForm({ binding }: { binding?: EthEventBinding }) {
+  const onSubmit = useEthEventHandler<Record<string, unknown>>(binding);
+  return (
+    <button
+      type="button"
+      data-testid="submit"
+      onClick={() => onSubmit({ name: "Ada" })}
+    >
+      Submit
+    </button>
+  );
+}
+
+describe("useEthAction → EchoEventProvider.dispatch", () => {
+  it("dispatches the exact binding when EthAction.onSelect fires", () => {
+    const dispatch = vi.fn<EchoEventDispatch>();
+    const { container, cleanup } = mount(
+      <EchoEventProvider dispatch={dispatch}>
+        <ArchiveButton binding={archiveBinding} />
+      </EchoEventProvider>,
+    );
+
+    const button = container.querySelector<HTMLButtonElement>('[data-testid="archive"]')!;
+    act(() => button.click());
+
+    expect(dispatch).toHaveBeenCalledTimes(1);
+    expect(dispatch).toHaveBeenCalledWith(archiveBinding, undefined, undefined);
+    cleanup();
+  });
+
+  it("is inert (no dispatch) when no binding is authored", () => {
+    const dispatch = vi.fn<EchoEventDispatch>();
+    const { container, cleanup } = mount(
+      <EchoEventProvider dispatch={dispatch}>
+        <ArchiveButton />
+      </EchoEventProvider>,
+    );
+    const button = container.querySelector<HTMLButtonElement>('[data-testid="archive"]')!;
+    act(() => button.click());
+    expect(dispatch).not.toHaveBeenCalled();
+    cleanup();
+  });
+
+  it("does not crash with no provider mounted (no-op dispatch)", () => {
+    const { container, cleanup } = mount(<ArchiveButton binding={archiveBinding} />);
+    const button = container.querySelector<HTMLButtonElement>('[data-testid="archive"]')!;
+    expect(() => act(() => button.click())).not.toThrow();
+    cleanup();
+  });
+});
+
+describe("useEthEventHandler — live payload", () => {
+  it("forwards the live payload to dispatch", () => {
+    const dispatch = vi.fn<EchoEventDispatch>();
+    const binding: EthEventBinding = {
+      event: "onSubmit",
+      actions: [{ kind: "runProcess", process: "CreateUser" }],
+    };
+    const { container, cleanup } = mount(
+      <EchoEventProvider dispatch={dispatch}>
+        <SubmitForm binding={binding} />
+      </EchoEventProvider>,
+    );
+    const button = container.querySelector<HTMLButtonElement>('[data-testid="submit"]')!;
+    act(() => button.click());
+    expect(dispatch).toHaveBeenCalledWith(binding, { name: "Ada" }, undefined);
+    cleanup();
+  });
+});
+
+describe("toRegistryEventBinding — registry structural compatibility", () => {
+  it("renames kind→action and payload→externalInput for runProcess", () => {
+    const reg = toRegistryEventBinding(archiveBinding);
+    expect(reg.event).toBe("onSelect");
+    expect(reg.actions[0]).toEqual({
+      action: "runProcess",
+      process: "ArchiveOrder",
+      externalInput: { reason: "stale" },
+    });
+    expect(reg.actions[1]).toEqual({
+      action: "showToast",
+      message: "Archived",
+      level: "success",
+    });
+  });
+
+  it("maps navigate/setState/openModal targets to registry field names", () => {
+    const reg = toRegistryEventBinding({
+      event: "onClick",
+      actions: [
+        { kind: "navigate", target: "/orders", params: { tab: "open" } },
+        { kind: "setState", target: "selected", value: 3 },
+        { kind: "openModal", target: "confirm" },
+      ],
+    });
+    expect(reg.actions[0]).toEqual({
+      action: "navigate",
+      route: "/orders",
+      params: { tab: "open" },
+    });
+    expect(reg.actions[1]).toEqual({ action: "setState", key: "selected", value: 3 });
+    expect(reg.actions[2]).toEqual({ action: "openModal", modalId: "confirm" });
+  });
+});

package/src/bridge.ts

@@ -0,0 +1,96 @@
+/**
+ * `bridge` — the field-renaming adapter that turns an {@link EthEventBinding}
+ * (the UI-library shape, discriminant `kind`) into the echothink-fugue registry
+ * `EventBinding` shape (discriminant `action`) that
+ * `runActionGraph`/`runProcess` consume.
+ *
+ * This lives in the UI library (not the registry) so the UI side OWNS its
+ * authoring shape and the host's `dispatch` can be a thin `runActionGraph(
+ * toRegistryActions(binding.actions), ctx)`. It is the documented, single point
+ * where the two contracts meet — keeping the rest of `@echothink-ui/events`
+ * free of any registry coupling.
+ *
+ * The output objects are plain JSON-compatible records typed `unknown` at the
+ * boundary; the registry validates/narrows them with its own
+ * `validateActionGraph`. We do not import registry types here.
+ */
+import type { EthAction, EthEventBinding } from "./types.js";
+
+/** A registry-shaped action node (discriminant `action`). */
+export type RegistryActionNode = Record<string, unknown> & { action: string };
+
+/** A registry-shaped event binding (`{ event, actions: ActionNode[] }`). */
+export interface RegistryEventBinding {
+  event: string;
+  actions: RegistryActionNode[];
+}
+
+/**
+ * Convert one {@link EthAction} to the registry `ActionNode` shape. The mapping:
+ *  - `kind` → `action`
+ *  - `runProcess`: `payload` → `externalInput`, `target`/`expectedVersion`/`optimistic` pass through
+ *  - `navigate`: `target` → `route`, `params` pass through
+ *  - `setState`: `target` → `key`, `value` passes through
+ *  - `openModal`/`closeModal`: `target` → `modalId`
+ *  - `showToast`: `message`/`level` pass through
+ */
+export function toRegistryAction(action: EthAction): RegistryActionNode {
+  switch (action.kind) {
+    case "runProcess":
+      return {
+        action: "runProcess",
+        process: action.process,
+        ...(action.target !== undefined ? { target: action.target } : {}),
+        ...(action.payload !== undefined ? { externalInput: action.payload } : {}),
+        ...(action.expectedVersion !== undefined
+          ? { expectedVersion: action.expectedVersion }
+          : {}),
+        ...(action.optimistic !== undefined ? { optimistic: action.optimistic } : {}),
+      };
+    case "navigate":
+      return {
+        action: "navigate",
+        route: action.target,
+        ...(action.params !== undefined ? { params: action.params } : {}),
+      };
+    case "setState":
+      return {
+        action: "setState",
+        key: action.target,
+        ...(action.value !== undefined ? { value: action.value } : {}),
+      };
+    case "openModal":
+      return { action: "openModal", modalId: action.target };
+    case "closeModal":
+      return { action: "closeModal", modalId: action.target };
+    case "showToast":
+      return {
+        action: "showToast",
+        message: action.message,
+        ...(action.level !== undefined ? { level: action.level } : {}),
+      };
+    default: {
+      // Forward-compatible: pass an unknown kind through as its own action.
+      const unknownAction = action as { kind: string };
+      return { ...(action as Record<string, unknown>), action: unknownAction.kind };
+    }
+  }
+}
+
+/**
+ * Convert an {@link EthEventBinding} to the registry `EventBinding` shape. A host
+ * that speaks the registry contract uses this to adapt at the dispatch edge:
+ *
+ * ```ts
+ * const dispatch: EchoEventDispatch = (binding, payload) => {
+ *   const reg = toRegistryEventBinding(binding);
+ *   runtime.dispatch([reg], binding.event, { row: payload });
+ * };
+ * ```
+ */
+export function toRegistryEventBinding(binding: EthEventBinding): RegistryEventBinding {
+  return {
+    event: binding.event,
+    actions: (binding.actions ?? []).map(toRegistryAction),
+  };
+}

package/src/context.tsx

@@ -0,0 +1,69 @@
+/**
+ * `EchoEventContext` — the injectable dispatch surface a component reads to send
+ * its authored {@link EthEventBinding} to the backend.
+ *
+ * Mirrors the registry's `EventDispatchContext` / `PageInteractionProvider`
+ * pattern: the UI library owns the CONTEXT + hooks; the HOST (the echothink-fugue
+ * renderer, a demo app, or a test) provides the real `dispatch` implementation
+ * that walks the action graph → `runProcess` → gateway. A NO-OP default lets
+ * components render with no provider, so standalone render/snapshot tests never
+ * crash.
+ */
+import {
+  createContext,
+  createElement,
+  useContext,
+  type ReactNode,
+} from "react";
+import type { EchoEventDispatch } from "./types.js";
+
+/**
+ * The interaction surface a component reads via {@link useEchoEvents}. The host
+ * constructs the real one; absent a provider, {@link NOOP_DISPATCH} is used so
+ * components never crash.
+ */
+export interface EchoEventContextValue {
+  /** Carry a binding (+ live payload) to the backend. */
+  dispatch: EchoEventDispatch;
+}
+
+/** A no-op dispatch — used when no provider is mounted. */
+const NOOP_DISPATCH: EchoEventDispatch = () => {};
+
+const EchoEventContext = createContext<EchoEventContextValue>({
+  dispatch: NOOP_DISPATCH,
+});
+
+/**
+ * Provide an {@link EchoEventDispatch} (constructed by the host) to the
+ * component tree. The host's `dispatch` is the bridge to the backend — it
+ * typically adapts each {@link EthEventBinding} to the registry action graph and
+ * runs it through `runProcess` → gateway.
+ *
+ * ```tsx
+ * <EchoEventProvider dispatch={(binding, payload) => runtime.dispatch(binding, payload)}>
+ *   <MyAuthoredPage />
+ * </EchoEventProvider>
+ * ```
+ */
+export function EchoEventProvider({
+  dispatch,
+  children,
+}: {
+  dispatch: EchoEventDispatch;
+  children: ReactNode;
+}): ReactNode {
+  return createElement(
+    EchoEventContext.Provider,
+    { value: { dispatch } },
+    children,
+  );
+}
+
+/**
+ * Read the {@link EchoEventContextValue}. Returns the no-op dispatch when no
+ * provider is mounted, so components (and their render tests) work standalone.
+ */
+export function useEchoEvents(): EchoEventContextValue {
+  return useContext(EchoEventContext);
+}

package/src/hooks.tsx

@@ -0,0 +1,69 @@
+/**
+ * Component-facing helpers that wire a component's rich semantic callbacks
+ * (`EthAction.onSelect`, `onClick`, form `onSubmit`, table `rowActions`) to a
+ * backend {@link EthEventBinding} via the injected {@link EchoEventDispatch}.
+ *
+ * These are the OPT-IN seam: a component that wants backend-aware behavior takes
+ * an optional `binding?: EthEventBinding` prop and calls one of these helpers to
+ * produce the handler it passes to its native callback prop. A component with no
+ * binding behaves exactly as today (the no-op dispatch is inert).
+ */
+import { useCallback } from "react";
+import { useEchoEvents } from "./context.js";
+import type { EthDispatchData, EthEventBinding } from "./types.js";
+
+/**
+ * Build an `onSelect` / `onClick`-shaped handler from an {@link EthEventBinding}.
+ *
+ * Returns `undefined` when `binding` is absent, so a component can spread it into
+ * `EthAction.onSelect` and fall back to its own default when unbound:
+ *
+ * ```tsx
+ * const onSelect = useEthAction(action.binding);
+ * <Button onClick={onSelect}>{action.label}</Button>
+ * // or, for EthAction:
+ * { ...action, onSelect: useEthAction(action.binding) ?? action.onSelect }
+ * ```
+ *
+ * The optional `data` (current row / route params) is threaded into the dispatch
+ * so the host can resolve `field:` / `route:` payloads — matching the registry's
+ * `DispatchDataContext`.
+ */
+export function useEthAction(
+  binding: EthEventBinding | undefined,
+  data?: EthDispatchData,
+): (() => void) | undefined {
+  const { dispatch } = useEchoEvents();
+  return useCallback(() => {
+    if (!binding) return;
+    void dispatch(binding, undefined, data);
+  }, [dispatch, binding, data]);
+}
+
+/**
+ * Build a payload-carrying handler from an {@link EthEventBinding} — for events
+ * that produce live data (form `onSubmit` values, the selected row, the chosen
+ * `rowAction` id). The returned function forwards whatever it is called with as
+ * the dispatch `payload`, so the host can merge it into the binding's actions.
+ *
+ * Returns a no-op (still callable) when `binding` is absent, so callers don't
+ * need to null-check at the call site.
+ *
+ * ```tsx
+ * const onSubmit = useEthEventHandler(binding);
+ * <form onSubmit={(e) => { e.preventDefault(); onSubmit(readFormValues(e)); }} />
+ * ```
+ */
+export function useEthEventHandler<P = unknown>(
+  binding: EthEventBinding | undefined,
+  data?: EthDispatchData,
+): (payload?: P) => void {
+  const { dispatch } = useEchoEvents();
+  return useCallback(
+    (payload?: P) => {
+      if (!binding) return;
+      void dispatch(binding, payload, data);
+    },
+    [dispatch, binding, data],
+  );
+}

package/src/index.ts

@@ -0,0 +1,42 @@
+/**
+ * `@echothink-ui/events` — public API.
+ *
+ * The backend-event contract for `@echothink-ui` components: a serializable
+ * {@link EthEventBinding} (structurally compatible with the echothink-fugue
+ * registry `EventBinding`), an {@link EchoEventProvider} the host uses to inject
+ * a backend `dispatch`, a {@link useEchoEvents} hook, and component-facing
+ * {@link useEthAction} / {@link useEthEventHandler} helpers that wire rich
+ * semantic callbacks (`EthAction.onSelect`, form `onSubmit`, table `rowActions`)
+ * to that dispatch. The {@link toRegistryEventBinding} bridge adapts the
+ * authoring shape to the registry action-graph shape at the host edge.
+ */
+export type {
+  EthEventName,
+  EthActionTarget,
+  EthActionKind,
+  EthAction,
+  EthRunProcessAction,
+  EthNavigateAction,
+  EthSetStateAction,
+  EthOpenModalAction,
+  EthCloseModalAction,
+  EthShowToastAction,
+  EthEventBinding,
+  EthDispatchData,
+  EchoEventDispatch,
+} from "./types.js";
+
+export {
+  EchoEventProvider,
+  useEchoEvents,
+  type EchoEventContextValue,
+} from "./context.js";
+
+export { useEthAction, useEthEventHandler } from "./hooks.js";
+
+export {
+  toRegistryAction,
+  toRegistryEventBinding,
+  type RegistryActionNode,
+  type RegistryEventBinding,
+} from "./bridge.js";

package/src/types.ts

@@ -0,0 +1,177 @@
+/**
+ * `@echothink-ui/events` — the BACKEND-EVENT CONTRACT for `@echothink-ui`
+ * components.
+ *
+ * `@echothink-ui` components expose plain React callbacks (`onClick`,
+ * `onSelect`, `EthAction.onSelect`, form `onSubmit`, table `rowActions`) with no
+ * path to a backend process/action. This module defines the serializable
+ * data shape — {@link EthEventBinding} + {@link EthAction} — that lets a
+ * builder-authored page declare "when this UI event fires, run these backend
+ * actions", plus the {@link EchoEventDispatch} contract a HOST injects to
+ * actually carry those actions to a backend (ultimately `runProcess` → gateway).
+ *
+ * STRUCTURAL COMPATIBILITY (the load-bearing constraint): these types are kept
+ * field-for-field compatible with the echothink-fugue registry's `EventBinding`
+ * / `ActionNode` contract (see `echothink-component-registry/.../events.tsx` and
+ * `echothink-app-renderer/.../logic/graph.ts`). A plain `EthEventBinding[]`
+ * array produced here flows through that registry's `eventsAware` HOC →
+ * `PageInteractionRuntime.dispatch` → `runActionGraph` → `runProcess` WITHOUT
+ * conversion. We deliberately DO NOT import the registry types (that would
+ * invert the dependency direction — the registry/renderer depend on the UI
+ * library, never the reverse); we mirror the shapes locally instead.
+ */
+
+/* -------------------------------------------------------------------------- */
+/* Event names (mirror the registry `EventBinding["event"]` union)            */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * The known UI event names. Kept open (`string & {}`) so custom / semantic
+ * events (e.g. `"onRowAction:archive"`) flow through, mirroring the registry's
+ * `EventName`.
+ */
+export type EthEventName =
+  | "onClick"
+  | "onSelect"
+  | "onSubmit"
+  | "onChange"
+  | "onLoad"
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  | (string & {});
+
+/* -------------------------------------------------------------------------- */
+/* Action targets / payload                                                   */
+/* -------------------------------------------------------------------------- */
+
+/** Optimistic-process target reference (the entity the process acts on). */
+export interface EthActionTarget {
+  entityType?: string;
+  entityId?: string;
+}
+
+/**
+ * The action discriminant — the verbs the host runtime knows how to perform.
+ * Kept identical to the registry `ActionNode["action"]` vocabulary (the subset a
+ * UI component realistically authors); unknown kinds are tolerated by the
+ * runtime, so this stays forward-compatible.
+ */
+export type EthActionKind =
+  | "runProcess"
+  | "navigate"
+  | "setState"
+  | "openModal"
+  | "closeModal"
+  | "showToast";
+
+/** Invoke a unit process through the host runtime (ultimately the gateway). */
+export interface EthRunProcessAction {
+  kind: "runProcess";
+  /** The unit-process name to invoke. */
+  process: string;
+  target?: EthActionTarget;
+  /** Inline payload for the process. May contain `field:` / `route:` refs. */
+  payload?: Record<string, unknown>;
+  expectedVersion?: number;
+  /** Hint that the UI applied an optimistic change before this ran. */
+  optimistic?: boolean;
+}
+
+/** Client-side navigation to a route, with optional params. */
+export interface EthNavigateAction {
+  kind: "navigate";
+  /** Target route / href. */
+  target: string;
+  params?: Record<string, string>;
+}
+
+/** Set a page-scoped state key to a value. */
+export interface EthSetStateAction {
+  kind: "setState";
+  /** State key to set. */
+  target: string;
+  value?: unknown;
+}
+
+/** Open a modal by id. */
+export interface EthOpenModalAction {
+  kind: "openModal";
+  /** Modal id to open. */
+  target: string;
+}
+
+/** Close a modal by id. */
+export interface EthCloseModalAction {
+  kind: "closeModal";
+  /** Modal id to close. */
+  target: string;
+}
+
+/** Surface a transient toast notification. */
+export interface EthShowToastAction {
+  kind: "showToast";
+  /** Toast message (the `target` mirrors `message` for field uniformity). */
+  message: string;
+  level?: "info" | "success" | "error";
+}
+
+/** The action union an {@link EthEventBinding} carries (discriminant: `kind`). */
+export type EthAction =
+  | EthRunProcessAction
+  | EthNavigateAction
+  | EthSetStateAction
+  | EthOpenModalAction
+  | EthCloseModalAction
+  | EthShowToastAction;
+
+/* -------------------------------------------------------------------------- */
+/* The binding                                                                */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * An event → action(s) binding attached to a component (the value a builder
+ * authors). When the named `event` fires the host runs `actions` in order.
+ *
+ * Structurally compatible with the registry `EventBinding` — see the conversion
+ * note in {@link toRegistryEventBinding}: `event` is the same field; the
+ * registry calls its action list `actions` with an `action` discriminant, while
+ * we use `kind` for ergonomics. {@link toRegistryEventBinding} renames the two
+ * fields (`kind`→`action`, `payload`→`externalInput`, `target`→`route`/`modalId`/`key`)
+ * so a host that speaks the registry contract can adapt at the edge.
+ */
+export interface EthEventBinding {
+  /** The UI event this binding reacts to. */
+  event: EthEventName;
+  /** The ordered backend/client actions to run when `event` fires. */
+  actions: EthAction[];
+}
+
+/* -------------------------------------------------------------------------- */
+/* Dispatch contract                                                          */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Optional dispatch-time data context, structurally compatible with the
+ * registry's `DispatchDataContext` / `EventDispatchData` — `row` is the current
+ * data-binding row (for `field:` resolution), `route` the route params.
+ */
+export interface EthDispatchData {
+  row?: Record<string, unknown>;
+  route?: Record<string, string>;
+}
+
+/**
+ * The capability a HOST injects (via {@link EchoEventProvider}) to carry a
+ * component's authored binding to the backend. `payload` is the live runtime
+ * data captured at the event (e.g. the form values, the selected row, the
+ * chosen action id). The host is responsible for merging `payload` into the
+ * binding's actions and running them (typically by adapting to the registry
+ * action graph → `runProcess` → gateway).
+ *
+ * Returns the host's promise so callers MAY await completion (e.g. to clear an
+ * optimistic flag); a fire-and-forget host returns `void`.
+ */
+export type EchoEventDispatch = (
+  binding: EthEventBinding,
+  payload?: unknown,
+  data?: EthDispatchData,
+) => void | Promise<void>;