@typeonce/effect-machine-devtools 0.23.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sandro Maglione
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,3 @@
+Portions are adapted from the Effect project, which is distributed under the
+MIT License. See https://github.com/Effect-TS/effect and the source history for
+authorship and provenance.

package/README.md

@@ -0,0 +1,81 @@
+# Effect Machine devtools
+
+`@typeonce/effect-machine-devtools` scans a local project for exported Effect Machine `.handle(...)` results and serves a live text-tree visualizer.
+
+The package is experimental and pre-1.0. Minor releases may change its command options, document schemas, and programmatic modules.
+
+## Compatibility
+
+Core and devtools always release at the same version. Install matching versions:
+
+```sh
+pnpm add @typeonce/effect-machine@latest effect@4.0.0-rc.111
+pnpm add --save-dev @typeonce/effect-machine-devtools@latest
+```
+
+When pinning a release instead of using `latest`, use the same explicit version for both packages.
+
+The current release requires Node.js 22.19 or newer and Effect `4.0.0-rc.111`.
+
+## Run the visualizer
+
+Start it from the project that contains the machines:
+
+```sh
+pnpm exec effect-machine
+```
+
+The command scans `**/src/**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}` and serves the visualizer at `http://127.0.0.1:5173`.
+
+```sh
+pnpm exec effect-machine \
+  --root ./packages/app \
+  --include "src/**/*.ts" \
+  --port 4173 \
+  --open
+```
+
+| Option            | Default                                       | Purpose                                                    |
+| ----------------- | --------------------------------------------- | ---------------------------------------------------------- |
+| `--root`          | current directory                             | Project directory to inspect                               |
+| `--include`       | `**/src/**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}` | Machine source glob relative to the project root           |
+| `--host`          | `127.0.0.1`                                   | Local server host                                          |
+| `--port`          | `5173`                                        | Local server port                                          |
+| `--open`          | `false`                                       | Open the visualizer in the default browser                 |
+| `--watch-polling` | `false`                                       | Use polling when native file-system events are unavailable |
+
+Native file-system events are the default. Polling scans more frequently and may use more CPU in large repositories, so enable it only when the platform watcher misses changes.
+
+## Live results
+
+The browser reports one of these statuses for every candidate:
+
+- `Ready` contains the latest complete machine document.
+- `Partial` keeps the last valid document visible and adds diagnostics from the incomplete source.
+- `Failed` contains diagnostics when no valid document is available.
+
+An incomplete edit can remove `.handle(...)` or change an export temporarily without discarding the last valid topology. A syntactically valid removal removes the machine from the index on the next scan.
+
+## Trusted projects only
+
+Discovery parses source files without executing them. Evaluation then loads candidate modules in a fresh worker. Module initialization code executes during that load, although transition resolvers and activity sources do not.
+
+Run the devtools only against code you trust. The server has no authentication and binds to the loopback interface by default. Do not expose it on a public or untrusted network.
+
+## Inspection and simulation
+
+The visualizer shows topology, active initial paths, state annotations, events, transitions, branches, state updates, activities, source metadata, and diagnostics. The tree supports pointer and keyboard navigation, subtree expansion, related-state highlighting, and structured detail inspection.
+
+Simulation works from the serialized machine document and never runs project code. It advances only when an event has one required direct transition whose target is statically known.
+
+Declinable transitions, conditional branches, parallel transitions, history, and choices return an indeterminate result. Deterministic steps report skipped state updates, runtime effects, raised events, reentry lifecycles, and automatic stabilization instead of pretending to execute them.
+
+## Programmatic modules
+
+The first release publishes three programmatic modules:
+
+- `DevToolsProtocol` defines the versioned worker and browser messages.
+- `MachineDocument` defines and constructs the serializable inspection document.
+- `MachineSimulator` provides the side-effect-free document simulator.
+
+The project inspector, registry, worker, and local server remain implementation modules. Their interfaces can change without becoming package-level compatibility commitments.

package/dist/DevServer.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Local HTTP server for the Effect Machine visualizer.
+ *
+ * @since 0.23.0
+ */
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import type * as MachineRegistry from "./MachineRegistry.js";
+/**
+ * @category models
+ * @since 0.23.0
+ */
+export interface Options {
+    readonly root: string;
+    readonly host: string;
+    readonly port: number;
+    readonly open?: boolean | undefined;
+    readonly debounce?: number | undefined;
+    readonly watchPolling?: boolean | undefined;
+}
+declare const DevServerError_base: Schema.Class<DevServerError, Schema.Struct<{
+    readonly _tag: Schema.tag<"DevServerError">;
+    readonly message: Schema.String;
+    readonly cause: Schema.optional<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Failure while starting or serving the local visualizer.
+ *
+ * @category errors
+ * @since 0.23.0
+ */
+export declare class DevServerError extends DevServerError_base {
+}
+/**
+ * Starts the local visualizer and runs until interrupted.
+ *
+ * @category constructors
+ * @since 0.23.0
+ */
+export declare const run: (options: Options) => Effect.Effect<never, DevServerError, MachineRegistry.MachineRegistry>;
+export {};
+//# sourceMappingURL=DevServer.d.ts.map

package/dist/DevServer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DevServer.d.ts","sourceRoot":"","sources":["../src/DevServer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,OAAO,KAAK,KAAK,eAAe,MAAM,sBAAsB,CAAA;AAE5D;;;GAGG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACtC,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;CAC5C;;;;;;AAED;;;;;GAKG;AACH,qBAAa,cAAe,SAAQ,mBAMlC;CAAG;AAEL;;;;;GAKG;AACH,eAAO,MAAM,GAAG,GAAI,SAAS,OAAO,KAAG,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,cAAc,EAAE,eAAe,CAAC,eAAe,CACpE,CAAA"}

package/dist/DevServer.js

@@ -0,0 +1,28 @@
+/**
+ * Local HTTP server for the Effect Machine visualizer.
+ *
+ * @since 0.23.0
+ */
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as internal from "./internal/devServer.js";
+/**
+ * Failure while starting or serving the local visualizer.
+ *
+ * @category errors
+ * @since 0.23.0
+ */
+export class DevServerError extends Schema.Error("@typeonce/effect-machine-devtools/DevServer/DevServerError")({
+    _tag: Schema.tag("DevServerError"),
+    message: Schema.String,
+    cause: Schema.optional(Schema.Defect())
+}) {
+}
+/**
+ * Starts the local visualizer and runs until interrupted.
+ *
+ * @category constructors
+ * @since 0.23.0
+ */
+export const run = (options) => internal.run(DevServerError, options);
+//# sourceMappingURL=DevServer.js.map

package/dist/DevServer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DevServer.js","sourceRoot":"","sources":["../src/DevServer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,QAAQ,MAAM,yBAAyB,CAAA;AAgBnD;;;;;GAKG;AACH,MAAM,OAAO,cAAe,SAAQ,MAAM,CAAC,KAAK,CAC9C,4DAA4D,CAC7D,CAAC;IACA,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,gBAAgB,CAAC;IAClC,OAAO,EAAE,MAAM,CAAC,MAAM;IACtB,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;CACxC,CAAC;CAAG;AAEL;;;;;GAKG;AACH,MAAM,CAAC,MAAM,GAAG,GAAG,CAAC,OAAgB,EAAyE,EAAE,CAC7G,QAAQ,CAAC,GAAG,CAAC,cAAc,EAAE,OAAO,CAAC,CAAA"}