Consolidate runnable examples

[JovaniPink]

Summary

• make docs/examples/ the sole canonical example location
• remove four unlinked, untested top-level scripts after confirming their behavior is covered by maintained examples
• mark the configured more-parallel, concept documentation, persistence adoption, and runnable-example milestones complete
• keep PyPI publication and broader SCXML/datamodel coverage open on the roadmap
• record the documentation and example milestone in the existing untagged 0.7.0 changelog entry

Why

The repository had two example locations with very different quality levels. The top-level scripts used path mutation, real sleeps, legacy action calling patterns, or a manual Tk loop, while docs/examples/ now contains focused programs that run in isolated subprocesses on every supported CI Python version.

One canonical location makes links, contributor commands, and adoption guidance predictable.

Legacy coverage audit

• examples/basic.py: pure transitions and traffic-light structure are covered by the JSON-backed traffic_intersection example and machine guide
• examples/actions.py: named entry actions and sync execution are covered by traffic_intersection
• examples/substates.py: nested states, final states, and completion flows are covered across traffic_intersection, fetch_with_retry, and async_workflow
• examples/ui.py: contained no UI integration abstraction beyond calling the pure transition API; that API is covered by the machine guide and multiple runnable examples

Milestone status

Completed:

• all 13 configured more-parallel cases and the 54-case configured SCXML suite
• concept guides for machines/implementations, runtime choices, actors, persistence, and SCXML import
• five subprocess-tested runners covering JSON, sync, async, actors, persistence, and SCXML

Still open:

• publish 0.7.0 through the GitHub Release flow
• expand SCXML datamodel and executable-content coverage without adding JavaScript evaluation
• inspector compatibility, more v5 utilities, and later framework integrations

User impact

Users and contributors now have one maintained example collection with no stale alternate path. No public API, package contents, or runtime behavior changes.

Validation

• 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/
• local Markdown link audit: all repository-relative links resolve
• legacy example reference audit: no references remain
• git diff --check

[gemini-code-assist]

Code Review

This pull request updates the documentation, product roadmap, and examples for the 0.7.0 correctness and adoption milestone. It consolidates runnable examples under docs/examples/, adds concept guides (covering machine configuration, runtime choices, actors, snapshot persistence, and SCXML import), documents completed milestones, and removes legacy untested top-level scripts. I have no feedback to provide as there are no review comments.

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.