Add interactive text machine visualizer

.changeset/README.md

@@ -11,6 +11,10 @@ Effect Machine is experimental and pre-1.0. Use only:
 
 Do not create a major changeset before 1.0. Backward compatibility is not a design goal during this phase: prefer the clearest long-term API and provide a direct migration instead of adding deprecated aliases or compatibility wrappers.
 
+## Synchronized package versions
+
+`@typeonce/effect-machine` and `@typeonce/effect-machine-devtools` belong to the same Changesets fixed group. Keep their package versions equal and use `workspace:^` for the devtools dependency on core. A release affecting either package publishes both at the same version, so users can select compatible packages by matching their versions.
+
 ## Writing changelog entries
 
 Changeset descriptions are published directly on the documentation website. Write them for library users rather than repository maintainers.

.changeset/bright-trees-listen.md

@@ -0,0 +1,7 @@
+---
+"@typeonce/effect-machine-devtools": minor
+---
+
+Add a local interactive text visualizer prototype that renders the public machine inspection data as a collapsible tree.
+
+Use the text tree to navigate topology, expand nested states, select subtrees, and inspect structured machine details without converting the model into a chart.

.changeset/calm-events-simulate.md

@@ -0,0 +1,5 @@
+---
+"@typeonce/effect-machine-devtools": minor
+---
+
+Add `MachineSimulator` and browser controls for side-effect-free, best-effort topology simulation. Direct required transitions advance the active tree; runtime-dependent transitions remain visibly indeterminate instead of executing user code or guessing.

.changeset/calm-tools-organize.md

@@ -0,0 +1,5 @@
+---
+"@typeonce/effect-machine": patch
+---
+
+Move the published package into an Effect-style workspace without changing its public exports.

.changeset/config.json

@@ -2,7 +2,12 @@
   "$schema": "https://unpkg.com/@changesets/config@3.1.2/schema.json",
   "changelog": "@changesets/cli/changelog",
   "commit": false,
-  "fixed": [],
+  "fixed": [
+    [
+      "@typeonce/effect-machine",
+      "@typeonce/effect-machine-devtools"
+    ]
+  ],
   "linked": [],
   "access": "public",
   "baseBranch": "main",

.changeset/fair-tools-align.md

@@ -0,0 +1,6 @@
+---
+"@typeonce/effect-machine": patch
+"@typeonce/effect-machine-devtools": patch
+---
+
+Release `@typeonce/effect-machine` and `@typeonce/effect-machine-devtools` at the same version. Install matching versions so the devtools inspection protocol and machine model remain compatible.

.changeset/young-machines-watch.md

@@ -0,0 +1,7 @@
+---
+"@typeonce/effect-machine-devtools": minor
+---
+
+Add a local `effect-machine` command that discovers exported `.handle(...)` machines, keeps their last valid inspection document across incomplete reloads, and serves the live interactive text visualizer.
+
+Native file-system events are used by default. Pass `--watch-polling` on platforms where native events are unavailable.

.github/CODEOWNERS

@@ -1,7 +1,7 @@
-/src/ @SandroMaglione
+/packages/ @SandroMaglione
 /scripts/ @SandroMaglione
 /.github/ @SandroMaglione
 /package.json @SandroMaglione
 /pnpm-lock.yaml @SandroMaglione
-/tsconfig.build.json @SandroMaglione
+/tsconfig*.json @SandroMaglione
 /.changeset/config.json @SandroMaglione

.github/pull_request_template.md

@@ -5,7 +5,7 @@
 ## Changeset
 
 - [ ] Added or updated for a library or package-metadata change
-- [ ] Not required because this PR does not change `src/` or `package.json`
+- [ ] Not required because this PR does not change a publishable package
 
 ## Validation
 

.github/workflows/release.yml

@@ -6,8 +6,9 @@ on:
     paths:
       - ".changeset/**"
       - "package.json"
+      - "packages/*/package.json"
       - "pnpm-lock.yaml"
-      - "src/**"
+      - "packages/*/src/**"
 
 concurrency:
   group: release-${{ github.ref }}

.gitignore

@@ -5,3 +5,4 @@ references/
 *.tgz
 .DS_Store
 .pnpm-store
+*.tsbuildinfo

AGENTS.md

@@ -16,6 +16,7 @@ When compatibility, convenience, concision, and semantic clarity conflict, prefe
 ## Experimental versioning
 
 - The library is experimental and pre-1.0. Public additions and breaking API changes use a minor changeset; compatible fixes and implementation improvements use a patch changeset. Do not create major changesets before 1.0.
+- `@typeonce/effect-machine` and `@typeonce/effect-machine-devtools` release from one Changesets fixed group and must always have the same version. Keep their package versions, workspace dependency, and release configuration synchronized so users can install matching versions for compatibility.
 - Backward compatibility is not currently a design goal. Change or remove an existing API whenever a clearer, safer, smaller long-term design replaces it.
 - Do not add deprecated aliases, compatibility wrappers, or parallel APIs solely to preserve an inferior existing design unless the user explicitly requests them.
 - Explain the resulting API and direct migration in changesets. Do not use changelog entries to credit an external library or narrate implementation history.
@@ -31,12 +32,12 @@ When compatibility, convenience, concision, and semantic clarity conflict, prefe
 ## Effect internal standards
 
 - Before introducing an internal abstraction or protocol, inspect the analogous implementation under `references/effect` and follow its naming, module-boundary, and ownership conventions where they apply.
-- Keep public modules declarative and route implementation through `src/internal`. Preserve directed dependencies and avoid internal barrel modules.
+- Keep public modules declarative and route implementation through `packages/effect-machine/src/internal`. Preserve directed dependencies and avoid internal barrel modules.
 - Give optimized planners and runtimes explicit contracts and ownership boundaries. Do not hide mutable state behind readonly types or retain caller-owned mutable containers in cached structures.
 - Treat the generic planner/runtime as the semantic reference. Optimized strategies must fail closed: a new capability uses the generic path until its optimized semantics are implemented deliberately.
 - Keep casts at genuine erased boundaries only. Prefer narrower internal representations, explicit invariants, and exhaustive capability checks over broad `any`-based protocols.
 - For every optimized semantic change, add forced generic-versus-optimized differential coverage and a focused regression test. Include relevant edge cases such as targetless and reentering transitions, simultaneous transitions, raised events, completion, invocation, and retained snapshots.
-- Put public behavioral tests under `test/` and implementation-strategy tests under `test/internal/`. Tests should establish observable semantics, not mirror implementation details.
+- Put public behavioral tests under `packages/effect-machine/test/` and implementation-strategy tests under `packages/effect-machine/test/internal/`. Tests should establish observable semantics, not mirror implementation details.
 - Treat correctness, type safety, and benchmark regressions as blockers. Do not recover performance by weakening semantics or public inference.
 
 ## Verification
@@ -63,5 +64,5 @@ Use the pull request performance workflows to compare against the base branch; d
 
 ## Pull request conventions
 
-- Add or update a changeset for changes under `src/` or changes to `package.json`, following the changelog-writing guide in `.changeset/README.md`.
+- Add or update a changeset for changes under `packages/effect-machine/src/` or changes to a publishable package manifest, following the changelog-writing guide in `.changeset/README.md`.
 - Fill in the pull request template, including the validation performed and the changeset decision.

CONTRIBUTING.md

@@ -9,7 +9,7 @@ Wait for the proposal to be discussed and accepted before starting an implementa
 The source tree follows Effect's public-module/internal-implementation split:
 
 ```text
-src/
+packages/effect-machine/src/
 ├── Machine.ts
 ├── index.ts
 ├── testing/
@@ -23,7 +23,7 @@ Public entrypoints and public modules use Effect-style names. Private files sit
 under the domain they implement and use responsibility names such as
 `planner.ts`, `process.ts`, and `runtime.ts`; they do not repeat `machine` in
 every filename. Runtime tests mirror the same domains. Tests below
-`test/internal/` are the only white-box suites allowed to import `src/internal`.
+`packages/effect-machine/test/internal/` are the only white-box suites allowed to import `packages/effect-machine/src/internal`.
 
 The core dependency direction is:
 
@@ -39,7 +39,7 @@ public entrypoint -> public module -> process -> planner
 Internal machine modules may refer back to the public `Machine` types through
 type-only imports. The runtime is intentionally unaware of the model, planner,
 and process layers. Testing implementations are isolated under
-`src/internal/testing` and may only be consumed by the public testing module or
+`packages/effect-machine/src/internal/testing` and may only be consumed by the public testing module or
 other testing internals.
 
 `pnpm check:architecture` builds a TypeScript dependency graph using the