fix: None event label in create_machine_class_from_definition + docs

Fix bug where transition_data.get("event") returning None was
interpolated as literal "None" in event IDs (e.g., "next None").

Complete remaining documentation: configuration property in states.md,
cross-boundary transitions and transition priority in transitions.md,
async-specific limitations in async.md, prepare_event convention and
create_machine_class_from_definition docstring in api.md.

Author: fgmacedo

docs/api.md

@@ -101,6 +101,31 @@
     :members:
 ```
 
+## Callback conventions
+
+These are convention-based callbacks that you can define on your state machine
+subclass. They are not methods on the base class — define them in your subclass
+to enable the behavior.
+
+### `prepare_event`
+
+Called before every event is processed. Returns a `dict` of keyword arguments
+that will be merged into `**kwargs` for all subsequent callbacks (guards, actions,
+entry/exit handlers) during that event's processing:
+
+```python
+class MyMachine(StateMachine):
+    initial = State(initial=True)
+    loop = initial.to.itself()
+
+    def prepare_event(self):
+        return {"request_id": generate_id()}
+
+    def on_loop(self, request_id):
+        # request_id is available here
+        ...
+```
+
 ## create_machine_class_from_definition
 
 ```{versionadded} 3.0.0

docs/async.md

@@ -201,3 +201,14 @@ async def run():
     await sm.activate_initial_state()
     await sm.send("event")
 ```
+
+### Async-specific limitations
+
+- **Initial state activation**: In async code, you must `await sm.activate_initial_state()`
+  before inspecting `sm.configuration` or `sm.current_state`. In sync code this happens
+  automatically at instantiation time.
+- **Delayed events**: Both sync and async engines support `delay=` on `send()`. The async
+  engine uses `asyncio.sleep()` internally, so it integrates naturally with event loops.
+- **Thread safety**: The processing loop uses a non-blocking lock (`_processing.acquire`).
+  All callbacks run on the same thread they are called from — do not share a state machine
+  instance across threads without external synchronization.

docs/states.md

@@ -268,3 +268,43 @@ in nested compounds.
 ```{seealso}
 See {ref}`history-states` for shallow vs deep history and default transitions.
 ```
+
+## Configuration
+
+```{versionadded} 3.0.0
+```
+
+The `configuration` property returns the set of currently active states as an
+`OrderedSet[State]`. With compound and parallel states, multiple states can be
+active simultaneously:
+
+```py
+>>> from statemachine import State, StateChart
+
+>>> class Journey(StateChart):
+...     class shire(State.Compound):
+...         bag_end = State(initial=True)
+...         green_dragon = State()
+...         visit_pub = bag_end.to(green_dragon)
+...     road = State(final=True)
+...     depart = shire.to(road)
+
+>>> sm = Journey()
+>>> {s.id for s in sm.configuration} == {"shire", "bag_end"}
+True
+
+```
+
+Use `configuration_values` for a set of the active state values (or IDs if no
+custom value is defined):
+
+```py
+>>> set(sm.configuration_values) == {"shire", "bag_end"}
+True
+
+```
+
+```{note}
+The older `current_state` property is deprecated. Use `configuration` instead,
+which works consistently for both flat and hierarchical state machines.
+```

docs/transitions.md

@@ -420,3 +420,113 @@ the third `bear_ring` event pushes `ring_power` past the threshold.
 ```{seealso}
 See {ref}`eventless-transitions` for chains, compound interactions, and `In()` guards.
 ```
+
+(cross-boundary-transitions)=
+
+### Cross-boundary transitions
+
+```{versionadded} 3.0.0
+```
+
+In statecharts, transitions can cross compound state boundaries — going from a
+state inside one compound to a state outside, or into a different compound. The
+engine automatically determines which states to exit and enter by computing the
+**transition domain**: the smallest compound ancestor that contains both the
+source and all target states.
+
+```py
+>>> from statemachine import State, StateChart
+
+>>> class MiddleEarthJourney(StateChart):
+...     validate_disconnected_states = False
+...     class rivendell(State.Compound):
+...         council = State(initial=True)
+...         preparing = State()
+...         get_ready = council.to(preparing)
+...     class moria(State.Compound):
+...         gates = State(initial=True)
+...         bridge = State(final=True)
+...         cross = gates.to(bridge)
+...     march = rivendell.to(moria)
+
+>>> sm = MiddleEarthJourney()
+>>> set(sm.configuration_values) == {"rivendell", "council"}
+True
+
+>>> sm.send("march")
+>>> set(sm.configuration_values) == {"moria", "gates"}
+True
+
+```
+
+When `march` fires, the engine:
+1. Computes the transition domain (the root, since `rivendell` and `moria` are siblings)
+2. Exits `council` and `rivendell` (running their exit actions)
+3. Enters `moria` and its initial child `gates` (running their entry actions)
+
+A transition can also go from a deeply nested child to an outer state:
+
+```py
+>>> from statemachine import State, StateChart
+
+>>> class MoriaEscape(StateChart):
+...     class moria(State.Compound):
+...         class halls(State.Compound):
+...             entrance = State(initial=True)
+...             bridge = State(final=True)
+...             cross = entrance.to(bridge)
+...         assert isinstance(halls, State)
+...         depths = State(final=True)
+...         descend = halls.to(depths)
+...     daylight = State(final=True)
+...     escape = moria.to(daylight)
+
+>>> sm = MoriaEscape()
+>>> set(sm.configuration_values) == {"moria", "halls", "entrance"}
+True
+
+>>> sm.send("escape")
+>>> set(sm.configuration_values) == {"daylight"}
+True
+
+```
+
+(transition-priority)=
+
+### Transition priority in compound states
+
+```{versionadded} 3.0.0
+```
+
+When an event could match transitions at multiple levels of the state hierarchy,
+transitions from **descendant states take priority** over transitions from
+ancestor states. This follows the SCXML specification: the most specific
+(deepest) matching transition wins.
+
+```py
+>>> from statemachine import State, StateChart
+
+>>> class PriorityExample(StateChart):
+...     log = []
+...     class outer(State.Compound):
+...         class inner(State.Compound):
+...             s1 = State(initial=True)
+...             s2 = State(final=True)
+...             go = s1.to(s2, on="log_inner")
+...         assert isinstance(inner, State)
+...         after_inner = State(final=True)
+...         done_state_inner = inner.to(after_inner)
+...     after_outer = State(final=True)
+...     done_state_outer = outer.to(after_outer)
+...     def log_inner(self):
+...         self.log.append("inner won")
+
+>>> sm = PriorityExample()
+>>> sm.send("go")
+>>> sm.log
+['inner won']
+
+```
+
+If two transitions at the same level would exit overlapping states (a conflict),
+the one selected first in document order wins.

statemachine/io/__init__.py

@@ -146,10 +146,22 @@ def _parse_states(
 def create_machine_class_from_definition(
     name: str, states: Mapping[str, "StateKwargs | StateDefinition"], **definition
 ) -> StateChart:  # noqa: C901
-    """
-    Creates a StateChart class from a dictionary definition, using the StateMachineMetaclass.
+    """Create a StateChart class dynamically from a dictionary definition.
+
+    Args:
+        name: The class name for the generated state machine.
+        states: A mapping of state IDs to state definitions. Each state definition
+            can include ``initial``, ``final``, ``parallel``, ``name``, ``value``,
+            ``enter``/``exit`` callbacks, ``donedata``, nested ``states``,
+            ``history``, and transitions via ``on`` (event-triggered) or
+            ``transitions`` (eventless).
+        **definition: Additional keyword arguments passed to the metaclass
+            (e.g., ``validate_disconnected_states=False``).
 
-    Example usage with a traffic light machine:
+    Returns:
+        A new StateChart subclass configured with the given states and transitions.
+
+    Example:
 
     >>> machine = create_machine_class_from_definition(
     ...     "TrafficLightMachine",
@@ -173,8 +185,10 @@ def create_machine_class_from_definition(
 
                 target_state_id = transition_data["target"]
                 transition_event_name = transition_data.get("event")
-                if event_name is not None:
-                    transition_event_name = f"{event_name} {transition_event_name}".strip()
+                if event_name is not None and transition_event_name is not None:
+                    transition_event_name = f"{event_name} {transition_event_name}"
+                elif event_name is not None:
+                    transition_event_name = event_name
 
                 transition_kwargs = {
                     "event": transition_event_name,