Document SCXML import and safe conditions

[JovaniPink]

Summary

• add a focused SCXML import guide covering path loading, converted elements, transition execution, parallel semantics, and safe conditions
• document the importer boundary separately from the richer native machine configuration surface
• add a self-contained SCXML toggle document and Python runner with no conformance-submodule dependency
• execute the new runner through the isolated example smoke suite
• link the guide and example from the README and documentation indexes

Why

SCXML import is a useful adoption path, but users need a precise contract. The runtime supports a broader statechart model than the XML converter currently recognizes, and the condition evaluator is intentionally much smaller than JavaScript.

This PR makes those boundaries explicit while giving users a runnable local example that exercises the supported path.

Supported surface documented

• filesystem path and PathLike input
• <scxml>, <state>, <parallel>, and <transition>
• event targets, multiple target IDs, document-order selection, and parallel region behavior
• <raise> in transition, <onentry>, and <onexit> content
• safe conditions using true, false, !, &&, ||, and parentheses

Limits documented

• unsupported JavaScript and datamodel expressions raise InvalidConfigError
• <script>, <assign>, <send>, general ECMAScript, and broader executable content are not imported
• structural <final>, <history>, and explicit <initial> elements are not converted yet
• the configured result is 54 passed, 0 failed, including all 13 enabled more-parallel cases, but this is not a claim of complete W3C conformance
• more-parallel/test10 and test10b remain outside the configured subset pending assignment support

User impact

Users can import and run a local SCXML file using a tested example, understand how parallel transitions execute, and know immediately which conditions and XML elements are safe to rely on. No public API or runtime behavior changes.

Validation

• poetry run python docs/examples/scxml_toggle.py
• poetry run python -m pytest tests/test_examples.py -q (5 passed)
• poetry run python -m pytest tests/ --ignore=tests/test_scxml.py (397 passed)
• poetry run python -m pytest tests/test_scxml.py (54 passed)
• poetry run mypy src/xstate/
• poetry run ruff format --check src/ tests/ docs/examples/
• poetry run ruff check src/ tests/ docs/examples/
• git diff --check

[gemini-code-assist]

Code Review

This pull request introduces comprehensive documentation and a runnable example for SCXML import capabilities in xstate-python. It adds an SCXML import guide, a self-contained toggle example (scxml_toggle.py and scxml_toggle.scxml), and integrates the new example into the test suite and README files. Feedback suggests replacing the assert statements in the runnable example with explicit conditional checks and exceptions to ensure validation logic is not optimized away when Python is run with the -O flag.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

Using assert statements for verification in runnable examples/scripts is discouraged because they can be optimized away and ignored when Python is run with the -O flag (e.g., python -O docs/examples/scxml_toggle.py). To ensure the validation logic always executes, use explicit conditional checks and raise an exception like ValueError or RuntimeError instead.

Suggested change

	state = machine.initial_state
	assert state.matches("off")
	state = machine.transition(state, "TOGGLE")
	assert state.matches("on")
	state = machine.transition(state, "TOGGLE")
	assert state.matches("off")
	state = machine.initial_state
	if not state.matches("off"):
	raise ValueError("Expected state 'off'")
	state = machine.transition(state, "TOGGLE")
	if not state.matches("on"):
	raise ValueError("Expected state 'on'")
	state = machine.transition(state, "TOGGLE")
	if not state.matches("off"):
	raise ValueError("Expected state 'off'")