Add React-owned machine atoms

.changeset/README.md

@@ -13,7 +13,7 @@ Do not create a major changeset before 1.0. Backward compatibility is not a desi
 
 ## Synchronized package versions
 
-`@typeonce/effect-machine`, `@typeonce/effect-machine-devtools`, and `@typeonce/oxlint-plugin-effect-machine` belong to the same Changesets fixed group. Keep their package versions equal and use `workspace:^` for the devtools dependency on core. A release affecting any package publishes all three at the same version, so users can select compatible packages by matching their versions.
+`@typeonce/effect-machine`, `@typeonce/effect-machine-react`, `@typeonce/effect-machine-devtools`, and `@typeonce/oxlint-plugin-effect-machine` belong to the same Changesets fixed group. Keep their package versions equal and use `workspace:^` for package dependencies on core. A release affecting any package publishes all four at the same version, so users can select compatible packages by matching their versions.
 
 ## Writing changelog entries
 

.changeset/calm-machines-own.md

@@ -0,0 +1,15 @@
+---
+"@typeonce/effect-machine": minor
+"@typeonce/effect-machine-react": minor
+---
+
+Add `@typeonce/effect-machine-react` with `useMachineAtom` for owning and mounting one stable machine atom without subscribing its React owner to machine state.
+
+Typed state-path projections now return the same atom for repeated calls with the same machine and path. Descendants can select state-owned data directly during render:
+
+```tsx
+const machine = useMachineAtom(() => MachineAtoms.make(AuthMachine, input))
+const editing = useAtomSuspense(AtomMachine.selectSnapshot(machine, "Editing")).value
+```
+
+Startup input is captured when React creates the owner. Send an event to update the running workflow, or change the owner's React key to replace the machine.

.changeset/config.json

@@ -5,6 +5,7 @@
   "fixed": [
     [
       "@typeonce/effect-machine",
+      "@typeonce/effect-machine-react",
       "@typeonce/effect-machine-devtools",
       "@typeonce/oxlint-plugin-effect-machine"
     ]

AGENTS.md

@@ -16,7 +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`, `@typeonce/effect-machine-devtools`, and `@typeonce/oxlint-plugin-effect-machine` 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.
+- `@typeonce/effect-machine`, `@typeonce/effect-machine-react`, `@typeonce/effect-machine-devtools`, and `@typeonce/oxlint-plugin-effect-machine` release from one Changesets fixed group and must always have the same version. Keep their package versions, workspace dependencies, 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.

README.md

@@ -49,9 +49,10 @@ statechart, and the result runs as an Effect-managed machine.
 
 ## Packages
 
-The workspace publishes three packages at the same version:
+The workspace publishes four packages at the same version:
 
 - [`@typeonce/effect-machine`](./packages/effect-machine/README.md) contains the machine runtime, testing modules, and documentation.
+- [`@typeonce/effect-machine-react`](./packages/effect-machine-react/README.md) owns machine atoms in React without subscribing their owners to machine state.
 - [`@typeonce/effect-machine-devtools`](./packages/devtools/README.md) contains the publishable local machine visualizer and CLI.
 - [`@typeonce/oxlint-plugin-effect-machine`](./packages/oxlint-plugin/README.md) checks Effect Machine models for common structural mistakes.
 

package.json

@@ -5,7 +5,7 @@
   "scripts": {
     "build": "pnpm --recursive --filter \"./packages/**\" run build",
     "test": "node --expose-gc ./node_modules/vitest/vitest.mjs run",
-    "test:types": "pnpm --dir packages/effect-machine test:types",
+    "test:types": "pnpm --recursive --filter \"./packages/effect-machine*\" run test:types",
     "devtools": "pnpm --dir packages/devtools dev",
     "visualizer": "pnpm devtools",
     "visualizer:build": "pnpm --dir packages/devtools build",
@@ -25,9 +25,10 @@
     "docs:site:serve": "node scripts/api-reference-site/serve.mjs",
     "test:consumer": "node scripts/test-consumer.mjs",
     "pack:check": "node scripts/pack-check.mjs",
+    "react:pack-check": "node scripts/react-pack-check.mjs",
     "devtools:pack-check": "node scripts/devtools-pack-check.mjs",
     "oxlint-plugin:pack-check": "node scripts/oxlint-plugin-pack-check.mjs",
-    "check": "pnpm format:check && pnpm check:architecture && pnpm check:ci && pnpm docs:api:check && pnpm docs:site:check && pnpm typecheck && pnpm build && pnpm test && pnpm test:types && pnpm test:consumer && pnpm pack:check && pnpm devtools:pack-check && pnpm oxlint-plugin:pack-check",
+    "check": "pnpm format:check && pnpm check:architecture && pnpm check:ci && pnpm docs:api:check && pnpm docs:site:check && pnpm typecheck && pnpm build && pnpm test && pnpm test:types && pnpm test:consumer && pnpm pack:check && pnpm react:pack-check && pnpm devtools:pack-check && pnpm oxlint-plugin:pack-check",
     "changeset": "changeset",
     "version-packages": "changeset version && dprint fmt",
     "release": "pnpm build && changeset publish"

packages/effect-machine-react/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.

packages/effect-machine-react/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.

packages/effect-machine-react/README.md

@@ -0,0 +1,26 @@
+# @typeonce/effect-machine-react
+
+React ownership hooks for machine atoms created by
+[`@typeonce/effect-machine`](../effect-machine/README.md).
+
+```tsx
+import { useMachineAtom } from "@typeonce/effect-machine-react"
+
+function AuthProvider({ input, children }: Props) {
+  const machine = useMachineAtom(() => MachineAtoms.make(AuthMachine, input))
+
+  return (
+    <AuthContext.Provider value={machine}>
+      {children}
+    </AuthContext.Provider>
+  )
+}
+```
+
+`useMachineAtom` strongly owns one machine atom, mounts it after commit, and
+does not subscribe the owner to machine state. Descendants subscribe to the
+specific state paths they render with `AtomMachine.select`,
+`AtomMachine.selectSnapshot`, or `AtomMachine.matches`.
+
+Machine input is startup-only. Send an event to update a running workflow, or
+change the provider's React `key` to replace it with a new machine.

packages/effect-machine-react/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@typeonce/effect-machine-react",
+  "version": "0.28.0",
+  "description": "React ownership hooks for Effect Machine atoms",
+  "author": "Sandro Maglione",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/typeonce-dev/effect-machine.git",
+    "directory": "packages/effect-machine-react"
+  },
+  "bugs": {
+    "url": "https://github.com/typeonce-dev/effect-machine/issues"
+  },
+  "homepage": "https://github.com/typeonce-dev/effect-machine/tree/main/packages/effect-machine-react#readme",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "files": [
+    "src/**/*.ts",
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js"
+      },
+      "./package.json": "./package.json"
+    }
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.build.json",
+    "check": "tsc -b tsconfig.json",
+    "test:types": "tstyche"
+  },
+  "dependencies": {
+    "@typeonce/effect-machine": "workspace:^"
+  },
+  "peerDependencies": {
+    "@effect/atom-react": "4.0.0-rc.112",
+    "effect": "4.0.0-rc.112",
+    "react": ">=19.0.0 <20.0.0",
+    "scheduler": ">=0.25.0 <0.28.0"
+  },
+  "devDependencies": {
+    "@effect/atom-react": "4.0.0-rc.112",
+    "@testing-library/react": "16.3.0",
+    "@types/react": "19.2.16",
+    "@types/react-dom": "19.2.3",
+    "effect": "4.0.0-rc.112",
+    "jsdom": "27.2.0",
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
+    "scheduler": "0.27.0",
+    "tstyche": "7.2.1",
+    "typescript": "6.0.3",
+    "vitest": "4.1.10"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

packages/effect-machine-react/src/MachineAtom.ts

@@ -0,0 +1,29 @@
+/**
+ * React ownership for machine atoms.
+ *
+ * @since 0.29.0
+ */
+"use client"
+
+import { useAtomMount } from "@effect/atom-react"
+import type { AtomMachine } from "@typeonce/effect-machine/reactivity"
+import * as React from "react"
+
+type AnyMachineAtom = AtomMachine.MachineAtom<any, never, any, any, any, any>
+
+/**
+ * Creates one machine atom for a committed React owner and mounts its machine
+ * reference without subscribing the owner to machine state.
+ *
+ * The factory is startup-only. Later changes to values captured by the factory
+ * do not replace the machine. Send an event to change a running workflow, or
+ * change the owner's React `key` to create a new machine.
+ *
+ * @category hooks
+ * @since 0.29.0
+ */
+export const useMachineAtom = <A extends AnyMachineAtom>(create: () => A): A => {
+  const [machine] = React.useState(create)
+  useAtomMount(machine.ref)
+  return machine
+}

packages/effect-machine-react/src/index.ts

@@ -0,0 +1,7 @@
+/**
+ * React ownership hooks for Effect Machine atoms.
+ *
+ * @since 0.29.0
+ */
+
+export * from "./MachineAtom.js"