@octanejs/xstate 0.0.1

package/LICENSE

@@ -0,0 +1,49 @@
+Octane XState binding
+=====================
+
+MIT License
+
+Copyright (c) 2026 Dominic Gannaway
+
+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.
+
+@xstate/react-derived implementation and types
+==============================================
+
+MIT License
+
+Copyright (c) 2015 David Khourshid
+
+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/README.md

@@ -0,0 +1,83 @@
+# @octanejs/xstate
+
+XState for Octane — a port of [`@xstate/react@6.1.0`](https://github.com/statelyai/xstate/tree/main/packages/xstate-react).
+
+The `xstate` actor core is framework-neutral and has no runtime dependencies, so
+it is reused **unmodified** as a peer dependency. Only the React binding is
+ported. See [`UPSTREAM.md`](./UPSTREAM.md) for the pin, the module and export
+crosswalk, and the disposition of every upstream test.
+
+```bash
+pnpm add @octanejs/xstate xstate
+```
+
+## Usage
+
+```tsx
+import { createMachine } from 'xstate';
+import { useMachine } from '@octanejs/xstate';
+
+const toggleMachine = createMachine({
+	id: 'toggle',
+	initial: 'inactive',
+	states: {
+		inactive: { on: { TOGGLE: 'active' } },
+		active: { on: { TOGGLE: 'inactive' } },
+	},
+});
+
+export function Toggle() @{
+	const [state, send] = useMachine(toggleMachine);
+
+	<button onClick={() => send({ type: 'TOGGLE' })}>
+		{state.value as string}
+	</button>
+}
+```
+
+`createActorContext` works exactly as upstream, including the member-call form:
+
+```tsx
+import { createActorContext } from '@octanejs/xstate';
+
+const ToggleContext = createActorContext(toggleMachine);
+
+function Display() @{
+	const value = ToggleContext.useSelector((state) => state.value as string);
+	<span>{value}</span>
+}
+
+export function App() @{
+	<ToggleContext.Provider>
+		<Display />
+	</ToggleContext.Provider>
+}
+```
+
+## Exports
+
+`useActor`, `useActorRef`, `useSelector`, `useMachine` (deprecated upstream alias
+of `useActor`), `createActorContext`, `shallowEqual` — the complete
+`@xstate/react@6.1.0` surface.
+
+## Intentional differences from `@xstate/react` on React
+
+- **No StrictMode double-invoke.** Octane has no StrictMode, so effects, renders,
+  and observer notifications fire once where React's development StrictMode fires
+  them twice. Production counts are identical. Upstream's own suite parametrizes
+  eight assertions over both modes; the non-strict values are this port's
+  contract.
+- **`useSyncExternalStore` skips React's commit-time `getSnapshot` re-read** when
+  the rendered value was unchanged, because Octane's synchronous renderer closes
+  the concurrent-interleaving window React guards there. An actor always
+  notifies, so this is not reachable through this binding's public API.
+- **Error boundaries are `@try`/`@catch` blocks**, not class components. An actor
+  whose snapshot enters the `error` status still throws from render and is caught
+  by the nearest boundary; only the way you write the boundary changes.
+- **Server snapshots.** `getServerSnapshot` is optional in Octane and falls back
+  to `getSnapshot`; React throws when it is missing. Both ported hooks always
+  supply one.
+
+`stopRootWithRehydration` is kept verbatim even though its motivating case
+(React Strict Effects) cannot occur here, because it also governs
+unmount-then-remount, which stays observable to consumers.

package/UPSTREAM.md

@@ -0,0 +1,140 @@
+# Upstream
+
+## Pin and oracle boundary
+
+| Field | Value |
+| --- | --- |
+| Repository | https://github.com/statelyai/xstate |
+| Release tag | `@xstate/react@6.1.0` |
+| Commit | `d4f8c5b709291d44f70139a7f9ff333abd7c615c` |
+| Supported upstream range | exactly `@xstate/react@6.1.0` |
+| Source root | `packages/xstate-react/src` |
+| Test root | `packages/xstate-react/test` |
+| Actor-core peer | `xstate@^5.28.0` (oracle `xstate@5.32.5`) |
+| React oracle | `react@19.2.3`, `react-dom@19.2.3`, `@types/react@19.2.17` |
+| License | MIT |
+
+The vendored tree under [`upstream/`](./upstream) is byte-exact at that commit and
+carries upstream's `LICENSE`. It is prettier-ignored and excluded from the
+published `files`, so it is development evidence rather than shipped code.
+[`upstream/SHA256SUMS`](./upstream/SHA256SUMS) pins every vendored byte;
+`pnpm --dir packages/xstate upstream:verify` re-hashes the tree and fails on any
+drift or on an added/removed file.
+
+## Source boundary
+
+`xstate` itself is **not** ported and **not** vendored. It has no React import
+and no runtime dependencies, so the actor core, machine interpreter, and every
+`xstate` export are consumed unmodified from npm as a peer dependency. Only the
+React binding in `packages/xstate-react/src` is ported, module for module, and
+`src/` mirrors that layout so the two trees read side by side.
+
+Two of upstream's npm dependencies are React-specific and are replaced by
+in-repo ports rather than consumed:
+
+| Upstream dependency | Replacement | Why |
+| --- | --- | --- |
+| `use-sync-external-store/shim/with-selector` | [`src/useSyncExternalStoreWithSelector.ts`](./src/useSyncExternalStoreWithSelector.ts) | React's shim closes over React's concurrent-render model. The port keeps the exact memoization algorithm on Octane's native `useSyncExternalStore`. |
+| `use-isomorphic-layout-effect` | [`src/useIsomorphicLayoutEffect.ts`](./src/useIsomorphicLayoutEffect.ts) | The package is a bare hook alias. Octane hooks take a trailing compiler-assigned slot, so the helper has to be a function that forwards one. The DOM probe is unchanged. |
+| `#is-development` (package `imports` condition) | [`src/isDevelopment.ts`](./src/isDevelopment.ts) | Upstream publishes a prebuilt `dist/` and resolves the condition at build time. This package publishes raw `src/`, so the equivalent is the `NODE_ENV` probe every bundler constant-folds. |
+
+React and `@xstate/react` are development-only differential oracles; neither is a
+runtime dependency of the port.
+
+## Module crosswalk
+
+| Upstream module | Octane module | Disposition |
+| --- | --- | --- |
+| `src/index.ts` | [`src/index.ts`](./src/index.ts) | Ported; same six exports, same deprecation comment |
+| `src/useActor.ts` | [`src/useActor.ts`](./src/useActor.ts) | Ported; plain uSES shim replaced by Octane's native hook |
+| `src/useActorRef.ts` | [`src/useActorRef.ts`](./src/useActorRef.ts) | Ported; `useIdleActorRef` takes a positional internal signature (see below) |
+| `src/useMachine.ts` | [`src/useMachine.ts`](./src/useMachine.ts) | Ported; deprecated alias retained |
+| `src/useSelector.ts` | [`src/useSelector.ts`](./src/useSelector.ts) | Ported |
+| `src/createActorContext.ts` | [`src/createActorContext.ts`](./src/createActorContext.ts) | Ported. Stays plain `.ts`: the hooks it returns must forward their CALLER's compiler-assigned slot, and a compiled `.tsrx` appends its own symbol after any forwarded one, which would collapse every consumer call site onto a single hook cell. |
+| — | [`src/ActorProvider.tsrx`](./src/ActorProvider.tsrx) + [`.tsrx.d.ts`](./src/ActorProvider.tsrx.d.ts) | Octane-only split of the above: the provider is a component, so it lives in a compiled `.tsrx` and owns its hooks instead of forwarding them. Replaces upstream's `React.createElement(ReactContext.Provider, …)`. |
+| `src/shallowEqual.ts` | [`src/shallowEqual.ts`](./src/shallowEqual.ts) | Reused verbatim — pure comparator, no framework surface |
+| `src/stopRootWithRehydration.ts` | [`src/stopRootWithRehydration.ts`](./src/stopRootWithRehydration.ts) | Reused verbatim — touches xstate internals only |
+| `src/true.ts`, `src/false.ts` | [`src/isDevelopment.ts`](./src/isDevelopment.ts) | Dependency substitution; see the table above |
+| — | [`src/internal.ts`](./src/internal.ts) | Octane-only: `splitSlot`/`subSlot` hook-slot plumbing |
+
+## Export crosswalk
+
+Every export of the pinned upstream entry point `@xstate/react`:
+
+| Upstream export | Octane disposition | Evidence |
+| --- | --- | --- |
+| `useActor` | Ported | Types: `xstate-adapted-types`. Runtime: `xstate-adapted-upstream`, 26 upstream cases |
+| `useActorRef` | Ported | Types: `xstate-adapted-types`. Runtime: `xstate-adapted-upstream`, 18 upstream cases |
+| `useSelector` | Ported | Types: `xstate-adapted-types`. Runtime: `xstate-adapted-upstream`, 18 upstream cases |
+| `useMachine` | Ported (deprecated alias of `useActor`, as upstream) | Types: `xstate-adapted-types`. Runtime: `xstate-adapted-upstream` (upstream exercises it through the `useActor` suite) and `xstate-runtime-differential` |
+| `createActorContext` | Ported | Runtime: `xstate-adapted-upstream`, 13 upstream cases, plus `xstate-runtime-differential`. Not covered by the upstream type suite. |
+| `shallowEqual` | Reused verbatim | Runtime: exercised by the `xstate-adapted-upstream` `useSelector` cases. Not covered by the upstream type suite. |
+| `useIdleActorRef` (module-level, not exported from `index.ts`) | Ported with a positional `(logic, options, slot)` signature instead of upstream's `ConditionalRequired` variadic tuple. Unreachable for consumers: the package `exports` map exposes only the barrel, and upstream's `index.ts` does not re-export it either. | [`src/useActorRef.ts`](./src/useActorRef.ts) |
+
+## Sibling xstate packages
+
+The community request covered "xstate", so the rest of the org's React-facing
+surface is accounted for here rather than silently omitted:
+
+| Package | Disposition |
+| --- | --- |
+| `xstate` | Framework-neutral. Reused unmodified as a peer dependency; no binding needed. |
+| `@xstate/store`, `@xstate/store-react` | Ported separately as [`@octanejs/xstate-store`](../xstate-store). |
+| `@xstate/immer` | Framework-neutral (one module, no React import). Consume directly alongside this binding; no Octane binding needed. |
+| Stately inspection tooling (`@statelyai/inspect`) | Framework-neutral and published from a different repository. Consume directly; not applicable to this port. |
+| `@xstate/solid`, `@xstate/svelte`, `@xstate/vue`, `@xstate/store-{angular,preact,solid,svelte,vue}` | Not React bindings. Out of scope. |
+
+## React-parity lanes
+
+| Lane | Status |
+| --- | --- |
+| `xstate-pristine` | **Landed.** Runs the byte-exact `test/*.test.tsx` suite against `@xstate/react@6.1.0` and `react@19.2.3` after re-hashing every vendored byte, in upstream's own `happy-dom` environment with `globals: true`. 144 of 144 cases pass; the passing identities are pinned in [`audit/pristine-runtime.json`](./audit/pristine-runtime.json). |
+| `xstate-adapted-upstream` | **Landed.** Runs the one-for-one adapted `useActor`, `useActorRef`, `useSelector`, and `createActorContext` suites on Octane: 75 cases whose full names match the pristine lane's identities exactly. Inventory: [`audit/adapted-runtime.json`](./audit/adapted-runtime.json); permitted transformations are listed in the lane's `notes` in [`audit/react-parity.json`](./audit/react-parity.json). |
+| `xstate-pristine-types` | **Landed.** Compiles the vendored `test/types.test.tsx` together with the vendored `src` using plain `tsc` against `react@19.2.3` / `@types/react@19.2.17`, reproducing upstream's `allowImportingTsExtensions`. Config: [`audit/upstream-typetests/tsconfig.pristine.json`](./audit/upstream-typetests/tsconfig.pristine.json). |
+| `xstate-adapted-types` | **Landed.** Compiles [`typetests/types.test-d.tsx`](./typetests/types.test-d.tsx) with `tsrx-tsc`. The file is byte-identical to the vendored upstream suite below its header apart from one line (`@testing-library/react` → `@octanejs/testing-library`), and that is machine-checked rather than asserted: `react-parity:check` strips the header, undoes the transformation ledger in [`audit/type-parity.json`](./audit/type-parity.json), and requires the result to equal the vendored bytes. Any other edit — a deleted case, a softened type, a dropped `@ts-expect-error` — fails. |
+| `xstate-runtime-differential` | **Landed.** Runs one `.tsrx` fixture through this binding on Octane AND the real `@xstate/react@6.1.0` on `react@19.2.3`, asserting byte-identical `innerHTML` after every click. Covers `useMachine` transitions, `createActorContext` provider + selectors + `assign`, a final-state transition, a post-final no-op send, and an unbound `useSelector` over a context actor. `xstate@5.32.5` is shared by both sides and deliberately not rewritten, so any difference is attributable to the binding. |
+
+## Type suite evidence
+
+Both type suites are inventoried at file and assertion-group granularity in
+[`audit/pristine-types.json`](./audit/pristine-types.json) and
+[`audit/adapted-types.json`](./audit/adapted-types.json): 14 assertion groups
+each, of which 3 are `@ts-expect-error` negative assertions. The inventories are
+regenerated with `node scripts/react-parity/xstate-types-inventory.mjs` and a
+stale one fails the audit, so an inventory cannot stand in for a suite it no
+longer describes.
+
+The suites are compiled, never executed, so a compiler exit code alone is weak
+evidence: a gutted suite also compiles clean. Negative controls in
+[`scripts/react-parity/xstate-parity-controls.test.mjs`](../../scripts/react-parity/xstate-parity-controls.test.mjs)
+delete an assertion, drop a `@ts-expect-error`, empty the file, retarget an
+undeclared import, and stale the inventory, and require each to be rejected.
+
+## Runtime suite disposition
+
+Both columns are evidence today: the pristine lane runs the vendored suite
+unchanged against React, and the adapted lane runs the same cases on Octane.
+
+| Upstream artifact | Cases | Pristine | Adapted |
+| --- | --- | --- | --- |
+| `test/useActor.test.tsx` | 26 × 2 modes | Runs unchanged, 52 passing | One-for-one, non-strict mode only |
+| `test/useActorRef.test.tsx` | 18 × 2 modes | Runs unchanged, 36 passing | One-for-one, non-strict mode only |
+| `test/useSelector.test.tsx` | 18 × 2 modes | Runs unchanged, 36 passing | One-for-one, non-strict mode only |
+| `test/createActorContext.test.tsx` | 13 | Runs unchanged, 13 passing | One-for-one |
+| `test/types.test.tsx` | 7 | Runs unchanged, 7 passing | Pristine and adapted type lanes |
+| `test/utils.tsx` | — | Support only | `describeEachReactMode` parametrizes three files over `non-strict` and `strict`; the adapted helper runs the single applicable mode and the strict pass is not applicable (Octane has no StrictMode double-invoke). |
+| `package.json` | — | Support only: its `imports` map is what resolves `#is-development` for the vendored source, so the pristine runner reproduces that field verbatim in the run root. | Replaced by [`src/isDevelopment.ts`](./src/isDevelopment.ts). |
+| `vitest.config.mts` | — | Support only; [`tests/upstream-vitest.config.ts`](./tests/upstream-vitest.config.ts) reuses its `happy-dom` environment and `globals` setting. | Not applicable. |
+
+## Intentional divergences
+
+Every row is declared in [`audit/react-parity.json`](./audit/react-parity.json)
+with the case ids that pin it, and each is bound to a structured
+`OCTANE DIVERGENCE[id][caseId]` marker at the code it describes.
+
+| Divergence | Consumer impact | Pinned by |
+| --- | --- | --- |
+| No StrictMode double-invoke, so upstream's eight `suiteKey === 'strict'` render/effect/observer counts collapse to their non-strict values | Fewer renders and effect invocations in development than React StrictMode; production counts are identical | The eight adapted cases themselves (`xstate-no-strictmode-double-invoke`) |
+| `useSyncExternalStore` skips React's commit-time `getSnapshot` re-read when the rendered value was unchanged | Only observable for a store that mutates without notifying between render and commit; xstate always notifies | [`tests/conformance/divergences.test.ts`](./tests/conformance/divergences.test.ts), with a notifying control proving the reconciliation path is live at that exact point |
+| Server `getServerSnapshot` is optional and falls back to `getSnapshot` where React throws | Only reachable through a hand-rolled actor-like object; both ported hooks always supply one. Two layers contribute: Octane's server runtime defaults the argument, and [`src/useSyncExternalStoreWithSelector.ts`](./src/useSyncExternalStoreWithSelector.ts) passes `getServerSelection ?? getSelection` where upstream's replaced shim forwards it unchanged. | [`tests/ssr/server.test.ts`](./tests/ssr/server.test.ts), with a control proving the fallback is a real fallback. React throws the same error on the client while hydrating; this package has no hydration lane, so that half is untested here and belongs in `packages/octane/tests/hydration/`. |
+| Error boundaries are `@try`/`@catch` template blocks, not class components | Upstream's error tests use a class `ErrorBoundary`; the adapted fixtures use `@try`/`@catch`. The assertion — a thrown actor error reaching the nearest boundary — is unchanged. | The two adapted error-boundary cases (`xstate-error-boundary-try-catch`) |

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@octanejs/xstate",
+  "version": "0.0.1",
+  "description": "XState tools for Octane — reuses the framework-agnostic xstate actor core unchanged and ports the @xstate/react 6.1.0 binding onto Octane hooks.",
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/xstate"
+  },
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.22.2"
+  },
+  "octane": {
+    "hookSlots": {
+      "manual": [
+        "src"
+      ]
+    }
+  },
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "UPSTREAM.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "xstate": "^5.28.0",
+    "octane": "0.1.43"
+  },
+  "peerDependenciesMeta": {
+    "xstate": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "16.3.1",
+    "@tsrx/react": "^0.2.58",
+    "@types/react": "19.2.17",
+    "@types/react-dom": "19.2.3",
+    "@types/use-sync-external-store": "^1.5.0",
+    "@xstate/react": "6.1.0",
+    "esbuild": "^0.28.1",
+    "happy-dom": "^20.11.0",
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
+    "rxjs": "^7.8.2",
+    "use-isomorphic-layout-effect": "1.2.1",
+    "use-sync-external-store": "1.6.0",
+    "vitest": "^4.1.10",
+    "xstate": "5.32.5",
+    "@octanejs/testing-library": "0.1.40",
+    "octane": "0.1.43"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:upstream": "node scripts/run-pristine-upstream.mjs",
+    "typecheck": "tsrx-tsc --noEmit -p tsconfig.json && tsrx-tsc --noEmit -p typetests/tsconfig.adapted.json",
+    "typecheck:pristine": "tsc --noEmit -p audit/upstream-typetests/tsconfig.pristine.json",
+    "upstream:verify": "node scripts/verify-upstream.mjs"
+  }
+}

package/src/ActorProvider.tsrx

@@ -0,0 +1,31 @@
+// Octane-only: the component half of `createActorContext`.
+//
+// Upstream builds its provider with `React.createElement(ReactContext.Provider,
+// { value, children })` inside `createActorContext.ts`. Octane splits the two
+// halves by file type, because that is what makes slots work: a `.tsrx` module
+// is fully compiled and every hook call inside it receives a compiler-assigned
+// call-site slot, while a plain `.ts` module in a package that declares
+// `octane.hookSlots.manual` is left alone so it can forward slots by hand.
+//
+// The factory's hooks therefore stay in `createActorContext.ts` — a hook there
+// must forward its CALLER's slot, which is impossible in a compiled module
+// because the compiler appends its own symbol after the forwarded one — and only
+// this component, which owns its hooks rather than forwarding them, lives here.
+import { useActorRef } from './useActorRef.ts';
+import type { Context, OctaneNode } from 'octane';
+import type { Actor, ActorOptions, AnyActorLogic } from 'xstate';
+
+export function ActorProvider(props: {
+	context: Context<Actor<AnyActorLogic> | null>;
+	logic: AnyActorLogic;
+	options?: ActorOptions<AnyActorLogic>;
+	children?: OctaneNode;
+}) @{
+	// Held in a local so the template sees a stable component identity, the same
+	// way @octanejs/redux's Provider resolves its context prop.
+	const ActorContext = props.context;
+
+	const actor = useActorRef(props.logic, props.options as never);
+
+	<ActorContext.Provider value={actor}>{props.children}</ActorContext.Provider>
+}

package/src/ActorProvider.tsrx.d.ts

@@ -0,0 +1,14 @@
+// Type declaration for the .tsrx provider component (ActorProvider.tsrx).
+//
+// A SPECIFIC module declaration resolved by relative path, never an ambient
+// `declare module '*.tsrx'` — so it types only this module and cannot silence
+// `.tsrx` resolution in a consumer's own program.
+import type { ComponentBody, Context, OctaneNode } from 'octane';
+import type { Actor, ActorOptions, AnyActorLogic } from 'xstate';
+
+export declare const ActorProvider: ComponentBody<{
+	context: Context<Actor<AnyActorLogic> | null>;
+	logic: AnyActorLogic;
+	options?: ActorOptions<AnyActorLogic>;
+	children?: OctaneNode;
+}>;

package/src/createActorContext.ts

@@ -0,0 +1,111 @@
+// Ported from @xstate/react@6.1.0 src/createActorContext.ts
+// (statelyai/xstate @ d4f8c5b709291d44f70139a7f9ff333abd7c615c).
+//
+// This module stays plain `.ts` on purpose. The two hooks it returns must
+// forward their CALLER's compiler-assigned slot to the unbound hooks they
+// delegate to, and only an uncompiled module can do that: in a compiled `.tsrx`
+// the compiler appends its own symbol AFTER any forwarded one, so every consumer
+// call site would collapse onto a single hook cell — the selected values would
+// still be right (the selector memo recomputes per component) but one
+// subscriber's update would re-render all of them.
+//
+// The provider component, which owns its hooks instead of forwarding them, lives
+// in ./ActorProvider.tsrx.
+import { createContext, createElement, useContext } from 'octane';
+import { Actor, ActorOptions, AnyActorLogic, SnapshotFrom } from 'xstate';
+import { ActorProvider } from './ActorProvider.tsrx';
+import { splitSlot, subSlot } from './internal.ts';
+import { useSelector as useSelectorUnbound } from './useSelector.ts';
+import type { Context, OctaneNode } from 'octane';
+
+export function createActorContext<TLogic extends AnyActorLogic>(
+	actorLogic: TLogic,
+	actorOptions?: ActorOptions<TLogic>,
+): {
+	useSelector: <T>(
+		selector: (snapshot: SnapshotFrom<TLogic>) => T,
+		...rest: [compare?: (a: T, b: T) => boolean, slot?: symbol]
+	) => T;
+	useActorRef: () => Actor<TLogic>;
+	Provider: (props: {
+		children?: OctaneNode;
+		options?: ActorOptions<TLogic>;
+		/** @deprecated Use `logic` instead. */
+		machine?: never;
+		logic?: TLogic;
+	}) => unknown;
+} {
+	const ActorContext = createContext<Actor<TLogic> | null>(null);
+
+	function Provider(props: {
+		children?: OctaneNode;
+		options?: ActorOptions<TLogic>;
+		/** @deprecated Use `logic` instead. */
+		machine?: never;
+		logic?: TLogic;
+	}) {
+		if (props.machine) {
+			throw new Error(`The "machine" prop has been deprecated. Please use "logic" instead.`);
+		}
+
+		return createElement(ActorProvider, {
+			context: ActorContext as unknown as Context<Actor<AnyActorLogic> | null>,
+			logic: props.logic ?? actorLogic,
+			options: { ...actorOptions, ...props.options } as ActorOptions<AnyActorLogic>,
+			children: props.children,
+		});
+	}
+
+	// TODO: add properties to actor ref to make more descriptive
+	//
+	// Upstream reads `Provider.displayName` back out when building the
+	// missing-provider error. The name is held in a local as well so the message
+	// is identical without depending on the property's declared type.
+	const displayName = `ActorProvider`;
+	(Provider as typeof Provider & { displayName?: string }).displayName = displayName;
+
+	function useActorContext(): Actor<TLogic> {
+		// `useContext` is keyed by context identity rather than by a call-site
+		// slot, so this hook needs none of the forwarding below. A consumer's
+		// `SomeContext.useActorRef()` still compiles to a call with a trailing
+		// symbol; the extra argument is simply ignored here.
+		const actor = useContext(ActorContext);
+
+		if (!actor) {
+			throw new Error(
+				`You used a hook from "${displayName}" but it's not inside a <${displayName}> component.`,
+			);
+		}
+
+		return actor;
+	}
+
+	function useSelector<T>(
+		selector: (snapshot: SnapshotFrom<TLogic>) => T,
+		...rest: [compare?: (a: T, b: T) => boolean, slot?: symbol]
+	): T {
+		// Consumers reach this through the member form the upstream README and test
+		// suite use — `SomeContext.useSelector(fn)` — which the compiler rewrites to
+		// `withSlot(sym, () => SomeContext.useSelector(fn, sym))`. `sym` identifies
+		// the CONSUMER's call site, so deriving the unbound hook's slot from it is
+		// what keeps two selectors in one component, and the same selector in two
+		// components, on independent hook cells.
+		const [userArgs, slot] = splitSlot(rest as unknown[]);
+		const compare = userArgs[0] as ((a: T, b: T) => boolean) | undefined;
+
+		const actor = useActorContext();
+
+		return useSelectorUnbound(
+			actor,
+			selector as never,
+			compare as never,
+			subSlot(slot, 'context:selector'),
+		) as T;
+	}
+
+	return {
+		Provider,
+		useActorRef: useActorContext,
+		useSelector,
+	};
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+// Barrel mirroring @xstate/react@6.1.0 src/index.ts
+// (statelyai/xstate @ d4f8c5b709291d44f70139a7f9ff333abd7c615c).
+//
+// The framework-agnostic `xstate` core is NOT re-exported here, exactly as
+// upstream does not re-export it: consumers import machines, actors, and logic
+// creators straight from `xstate`, which this package takes as a peer.
+export { createActorContext } from './createActorContext.ts';
+export { shallowEqual } from './shallowEqual.ts';
+export { useActor } from './useActor.ts';
+export { useActorRef } from './useActorRef.ts';
+export { useSelector } from './useSelector.ts';
+
+// deprecated
+export { useMachine } from './useMachine.ts';

package/src/internal.ts

@@ -0,0 +1,38 @@
+// Slot mechanics for the binding's plain-`.ts` hooks. Octane injects a
+// per-call-site Symbol into calls made by compiled components; the binding
+// forwards that symbol and derives a distinct sub-slot for each hook it
+// composes. This package declares `octane.hookSlots.manual` for `src`, so the
+// compiler's plain-`.ts` slotting pass skips these modules and the forwarding
+// below is the only thing that keeps two call sites of the same hook apart.
+const subSlotCache = new Map<symbol, Map<string, symbol>>();
+const bareTagCache = new Map<string, symbol>();
+
+export function subSlot(slot: symbol | undefined, tag: string): symbol {
+	if (slot === undefined) {
+		let bare = bareTagCache.get(tag);
+		if (bare === undefined) {
+			bare = Symbol.for(`@octanejs/xstate:${tag}`);
+			bareTagCache.set(tag, bare);
+		}
+		return bare;
+	}
+
+	let byTag = subSlotCache.get(slot);
+	if (byTag === undefined) {
+		byTag = new Map();
+		subSlotCache.set(slot, byTag);
+	}
+
+	let child = byTag.get(tag);
+	if (child === undefined) {
+		child = Symbol.for(`${slot.description ?? ''}:${tag}`);
+		byTag.set(tag, child);
+	}
+	return child;
+}
+
+export function splitSlot(args: unknown[]): [unknown[], symbol | undefined] {
+	const tail = args[args.length - 1];
+	const slot = typeof tail === 'symbol' ? tail : undefined;
+	return [slot === undefined ? args : args.slice(0, -1), slot];
+}

package/src/isDevelopment.ts

@@ -0,0 +1,17 @@
+// Replaces @xstate/react@6.1.0's `#is-development` subpath import.
+//
+// Upstream resolves `#is-development` to `src/true.ts` or `src/false.ts` through
+// a package-`imports` map keyed on the `development` export condition, because it
+// publishes a prebuilt `dist/`. This package publishes raw `src/`, so the
+// condition never gets a chance to run in the consumer's bundler for our
+// modules; the equivalent, and the thing every bundler already constant-folds, is
+// the NODE_ENV probe.
+//
+// `process` is declared locally rather than pulled from @types/node: this module
+// ships to consumers, and their program must not be forced to include Node types
+// to typecheck it. The same idiom is used by @octanejs/jotai.
+declare const process: { env: { NODE_ENV?: string } };
+
+const isDevelopment = typeof process !== 'undefined' && process.env.NODE_ENV !== 'production';
+
+export default isDevelopment;

package/src/shallowEqual.ts

@@ -0,0 +1,36 @@
+// Ported verbatim from @xstate/react@6.1.0 src/shallowEqual.ts
+// (statelyai/xstate @ d4f8c5b709291d44f70139a7f9ff333abd7c615c). Pure
+// comparator with no React surface, so the upstream implementation is the port.
+//
+// From https://github.com/reduxjs/react-redux/blob/720f0ba79236cdc3e1115f4ef9a7760a21784b48/src/utils/shallowEqual.ts
+function is(x: unknown, y: unknown) {
+	if (x === y) {
+		return x !== 0 || y !== 0 || 1 / (x as number) === 1 / (y as number);
+	} else {
+		return x !== x && y !== y;
+	}
+}
+
+export function shallowEqual(objA: any, objB: any) {
+	if (is(objA, objB)) return true;
+
+	if (typeof objA !== 'object' || objA === null || typeof objB !== 'object' || objB === null) {
+		return false;
+	}
+
+	const keysA = Object.keys(objA);
+	const keysB = Object.keys(objB);
+
+	if (keysA.length !== keysB.length) return false;
+
+	for (let i = 0; i < keysA.length; i++) {
+		if (
+			!Object.prototype.hasOwnProperty.call(objB, keysA[i]) ||
+			!is(objA[keysA[i]], objB[keysA[i]])
+		) {
+			return false;
+		}
+	}
+
+	return true;
+}

package/src/stopRootWithRehydration.ts

@@ -0,0 +1,47 @@
+// Ported verbatim from @xstate/react@6.1.0 src/stopRootWithRehydration.ts
+// (statelyai/xstate @ d4f8c5b709291d44f70139a7f9ff333abd7c615c). It touches only
+// xstate internals — no React or Octane surface — so the upstream implementation
+// is the port.
+//
+// Upstream's motivating case (React Strict Effects double-invoking the
+// start/stop effect) does not exist on Octane, which never double-invokes
+// effects. The behavior is retained regardless because it also governs a real
+// unmount followed by a remount: the actor tree is persisted and rehydrated
+// rather than cold-restarted, which is observable to consumers and is what the
+// pinned upstream release does.
+import { AnyActorRef, Snapshot } from 'xstate';
+
+const forEachActor = (actorRef: AnyActorRef, callback: (ref: AnyActorRef) => void) => {
+	callback(actorRef);
+	const children = actorRef.getSnapshot().children;
+	if (children) {
+		Object.values(children).forEach((child) => {
+			forEachActor(child as AnyActorRef, callback);
+		});
+	}
+};
+
+export function stopRootWithRehydration(actorRef: AnyActorRef) {
+	// persist snapshot here in a custom way allows us to persist inline actors and to preserve actor references
+	// we do it to avoid setState in useEffect when the effect gets "reconnected"
+	// this currently only happens in Strict Effects but it simulates the Offscreen aka Activity API
+	// it also just allows us to end up with a somewhat more predictable behavior for the users
+	const persistedSnapshots: Array<[AnyActorRef, Snapshot<unknown>]> = [];
+	forEachActor(actorRef, (ref) => {
+		persistedSnapshots.push([ref, ref.getSnapshot()]);
+		// muting observers allow us to avoid `useSelector` from being notified about the stopped snapshot
+		// React reconnects its subscribers (from the useSyncExternalStore) on its own
+		// and userland subscribers should basically always do the same anyway
+		// as each subscription should have its own cleanup logic and that should be called each such reconnect
+		(ref as any).observers = new Set();
+	});
+	const systemSnapshot = actorRef.system.getSnapshot?.();
+
+	actorRef.stop();
+
+	(actorRef.system as any)._snapshot = systemSnapshot;
+	persistedSnapshots.forEach(([ref, snapshot]) => {
+		(ref as any)._processingStatus = 0;
+		(ref as any)._snapshot = snapshot;
+	});
+}

package/src/useActor.ts

@@ -0,0 +1,94 @@
+// Ported from @xstate/react@6.1.0 src/useActor.ts
+// (statelyai/xstate @ d4f8c5b709291d44f70139a7f9ff333abd7c615c).
+//
+// Upstream imports the plain `use-sync-external-store/shim`. Octane's
+// `useSyncExternalStore` is a first-class runtime hook, so the shim is dropped
+// and the native hook is called directly.
+import { useCallback, useEffect, useSyncExternalStore } from 'octane';
+import {
+	Actor,
+	ActorOptions,
+	AnyActorLogic,
+	Snapshot,
+	SnapshotFrom,
+	type ConditionalRequired,
+	type IsNotNever,
+	type RequiredActorOptionsKeys,
+} from 'xstate';
+import isDevelopment from './isDevelopment.ts';
+import { splitSlot, subSlot } from './internal.ts';
+import { stopRootWithRehydration } from './stopRootWithRehydration.ts';
+import { useIdleActorRef } from './useActorRef.ts';
+
+export function useActor<TLogic extends AnyActorLogic>(
+	logic: TLogic,
+	...rest: [
+		...ConditionalRequired<
+			[
+				options?: ActorOptions<TLogic> & {
+					[K in RequiredActorOptionsKeys<TLogic>]: unknown;
+				},
+			],
+			IsNotNever<RequiredActorOptionsKeys<TLogic>>
+		>,
+		slot?: symbol,
+	]
+): [SnapshotFrom<TLogic>, Actor<TLogic>['send'], Actor<TLogic>] {
+	const [userArgs, slot] = splitSlot(rest as unknown[]);
+	const options = userArgs[0] as ActorOptions<TLogic> | undefined;
+
+	if (isDevelopment && !!logic && 'send' in logic && typeof logic.send === 'function') {
+		throw new Error(
+			`useActor() expects actor logic (e.g. a machine), but received an ActorRef. Use the useSelector(actorRef, ...) hook instead to read the ActorRef's snapshot.`,
+		);
+	}
+
+	const actorRef = useIdleActorRef(logic, options, subSlot(slot, 'actor:idle'));
+
+	const getSnapshot = useCallback(
+		() => {
+			return actorRef.getSnapshot();
+		},
+		[actorRef],
+		subSlot(slot, 'actor:snapshot'),
+	);
+
+	const subscribe = useCallback(
+		(handleStoreChange: () => void) => {
+			const { unsubscribe } = actorRef.subscribe({
+				next: handleStoreChange,
+				error: handleStoreChange,
+			});
+			return unsubscribe;
+		},
+		[actorRef],
+		subSlot(slot, 'actor:subscribe'),
+	);
+
+	const actorSnapshot = useSyncExternalStore(
+		subscribe,
+		getSnapshot,
+		getSnapshot,
+		subSlot(slot, 'actor:external-store'),
+	);
+
+	const snapshotWithStatus =
+		'status' in (actorSnapshot as object) ? (actorSnapshot as Snapshot<unknown>) : undefined;
+	if (snapshotWithStatus?.status === 'error') {
+		throw snapshotWithStatus.error;
+	}
+
+	useEffect(
+		() => {
+			actorRef.start();
+
+			return () => {
+				stopRootWithRehydration(actorRef);
+			};
+		},
+		[actorRef],
+		subSlot(slot, 'actor:lifecycle'),
+	);
+
+	return [actorSnapshot as SnapshotFrom<TLogic>, actorRef.send, actorRef];
+}

package/src/useActorRef.ts

@@ -0,0 +1,140 @@
+// Ported from @xstate/react@6.1.0 src/useActorRef.ts
+// (statelyai/xstate @ d4f8c5b709291d44f70139a7f9ff333abd7c615c).
+import { useEffect, useState } from 'octane';
+import {
+	Actor,
+	ActorOptions,
+	AnyActorLogic,
+	AnyStateMachine,
+	Observer,
+	SnapshotFrom,
+	createActor,
+	toObserver,
+	type IsNotNever,
+	type RequiredActorOptionsKeys,
+} from 'xstate';
+import { splitSlot, subSlot } from './internal.ts';
+import { stopRootWithRehydration } from './stopRootWithRehydration.ts';
+import { useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect.ts';
+
+// Upstream exports `useIdleActorRef` from this module but not from `index.ts`,
+// and this package's `exports` map exposes only the barrel, so it is reachable
+// solely from `useActorRef` and `useActor` here. It therefore takes a plain
+// positional `(logic, options, slot)` signature instead of mirroring upstream's
+// `ConditionalRequired` variadic tuple: the public hooks below already enforce
+// that contract for consumers, and re-deriving it on an internal call would buy
+// no type safety.
+export function useIdleActorRef<TLogic extends AnyActorLogic>(
+	logic: TLogic,
+	options: ActorOptions<TLogic> | undefined,
+	slot: symbol | undefined,
+): Actor<TLogic> {
+	// The "derive state from props" pattern: a render-phase update. When the
+	// logic's config identity changes, a replacement actor is created and the
+	// state setter is called from the render body, so this render is replayed
+	// with the new actor before it commits. Octane implements React's semantics
+	// here (render-phase updates render in the current pass, under the same
+	// 25-attempt cap), which is what keeps the upstream re-render counts intact.
+	//
+	// Do NOT reach for Octane's `useLinkedState` here. It is the native
+	// replacement for exactly this pattern, but it resolves the new value without
+	// the replay, which would change the observable render count and break parity
+	// with the pinned upstream release.
+	let [[currentConfig, actorRef], setCurrent] = useState<[unknown, Actor<TLogic>]>(
+		() => {
+			const actorRef = createActor(logic, options);
+			return [logic.config, actorRef];
+		},
+		subSlot(slot, 'idle:current'),
+	);
+
+	if (logic.config !== currentConfig) {
+		const newActorRef = createActor(logic, {
+			...options,
+			snapshot: (actorRef.getPersistedSnapshot as any)({
+				__unsafeAllowInlineActors: true,
+			}),
+		} as ActorOptions<TLogic>);
+		setCurrent([logic.config, newActorRef]);
+		actorRef = newActorRef;
+	}
+
+	// TODO: consider using `useAsapEffect` that would do this in `useInsertionEffect` is that's available
+	//
+	// Upstream passes no dependency array, which in React means "run after every
+	// render". This package declares manual hook slots, so the compiler never
+	// infers a dependency array for it; `null` is Octane's explicit spelling of
+	// the same every-render behavior.
+	useIsomorphicLayoutEffect(
+		() => {
+			(actorRef.logic as any as AnyStateMachine).implementations = (
+				logic as any as AnyStateMachine
+			).implementations;
+		},
+		null,
+		subSlot(slot, 'idle:implementations'),
+	);
+
+	return actorRef;
+}
+
+export function useActorRef<TLogic extends AnyActorLogic>(
+	machine: TLogic,
+	...rest: [
+		...(IsNotNever<RequiredActorOptionsKeys<TLogic>> extends true
+			? [
+					options: ActorOptions<TLogic> & {
+						[K in RequiredActorOptionsKeys<TLogic>]: unknown;
+					},
+					observerOrListener?:
+						Observer<SnapshotFrom<TLogic>> | ((value: SnapshotFrom<TLogic>) => void),
+				]
+			: [
+					options?: ActorOptions<TLogic>,
+					observerOrListener?:
+						Observer<SnapshotFrom<TLogic>> | ((value: SnapshotFrom<TLogic>) => void),
+				]),
+		slot?: symbol,
+	]
+): Actor<TLogic> {
+	// Both user arguments are optional in the common case, so the compiler-owned
+	// trailing symbol cannot be located positionally.
+	const [userArgs, slot] = splitSlot(rest as unknown[]);
+	const options = userArgs[0] as ActorOptions<TLogic> | undefined;
+	const observerOrListener = userArgs[1] as
+		Observer<SnapshotFrom<TLogic>> | ((value: SnapshotFrom<TLogic>) => void) | undefined;
+
+	const actorRef = useIdleActorRef(machine, options, subSlot(slot, 'ref:idle'));
+
+	// Upstream's dependency array is `[observerOrListener]` even though the effect
+	// also closes over `actorRef`. Kept verbatim: an explicit array is never
+	// rewritten by Octane, so this preserves the pinned release's subscription
+	// lifetime exactly.
+	useEffect(
+		() => {
+			if (!observerOrListener) {
+				return;
+			}
+			const sub = actorRef.subscribe(toObserver(observerOrListener));
+			return () => {
+				sub.unsubscribe();
+			};
+		},
+		[observerOrListener],
+		subSlot(slot, 'ref:observer'),
+	);
+
+	useEffect(
+		() => {
+			actorRef.start();
+
+			return () => {
+				stopRootWithRehydration(actorRef);
+			};
+		},
+		[actorRef],
+		subSlot(slot, 'ref:lifecycle'),
+	);
+
+	return actorRef;
+}

package/src/useIsomorphicLayoutEffect.ts

@@ -0,0 +1,21 @@
+// Replaces @xstate/react@6.1.0's `use-isomorphic-layout-effect` dependency.
+//
+// The npm package is a bare `typeof document !== 'undefined' ? useLayoutEffect :
+// useEffect` alias. That shape cannot be reused here: Octane hooks take a
+// trailing compiler-assigned slot, and this package hand-forwards slots, so the
+// helper has to be a real function that passes `(effect, deps, slot)` through.
+// The DOM probe itself is upstream's, unchanged.
+//
+// A conditional hook call is legal in Octane — hooks are keyed by slot, not by
+// call order — and `typeof document` is constant for the lifetime of a program,
+// so a given call site resolves to one hook kind for every render.
+import { useEffect, useLayoutEffect } from 'octane';
+
+export function useIsomorphicLayoutEffect(
+	effect: () => void | (() => void),
+	deps: unknown[] | null | undefined,
+	slot?: symbol,
+): void {
+	const hook = typeof document !== 'undefined' ? useLayoutEffect : useEffect;
+	hook(effect as never, deps as never, slot);
+}

package/src/useMachine.ts

@@ -0,0 +1,44 @@
+// Ported from @xstate/react@6.1.0 src/useMachine.ts
+// (statelyai/xstate @ d4f8c5b709291d44f70139a7f9ff333abd7c615c).
+//
+// Deprecated upstream and retained here for the same reason: it is still a
+// published export of the pinned release.
+import {
+	Actor,
+	ActorOptions,
+	AnyStateMachine,
+	StateFrom,
+	type ConditionalRequired,
+	type IsNotNever,
+	type RequiredActorOptionsKeys,
+} from 'xstate';
+import { splitSlot } from './internal.ts';
+import { useActor } from './useActor.ts';
+
+/** @alias useActor */
+export function useMachine<TMachine extends AnyStateMachine>(
+	machine: TMachine,
+	...rest: [
+		...ConditionalRequired<
+			[
+				options?: ActorOptions<TMachine> & {
+					[K in RequiredActorOptionsKeys<TMachine>]: unknown;
+				},
+			],
+			IsNotNever<RequiredActorOptionsKeys<TMachine>>
+		>,
+		slot?: symbol,
+	]
+): [StateFrom<TMachine>, Actor<TMachine>['send'], Actor<TMachine>] {
+	// This hook composes no hook cells of its own, so the caller's slot is
+	// forwarded unchanged: `useMachine(m)` and `useActor(m)` at one call site must
+	// resolve to the same hook identities, exactly as the upstream alias does.
+	const [userArgs, slot] = splitSlot(rest as unknown[]);
+	const options = userArgs[0] as ActorOptions<TMachine> | undefined;
+
+	return useActor(machine as AnyStateMachine, options as never, slot) as [
+		StateFrom<TMachine>,
+		Actor<TMachine>['send'],
+		Actor<TMachine>,
+	];
+}

package/src/useSelector.ts

@@ -0,0 +1,69 @@
+// Ported from @xstate/react@6.1.0 src/useSelector.ts
+// (statelyai/xstate @ d4f8c5b709291d44f70139a7f9ff333abd7c615c).
+//
+// Upstream imports `useSyncExternalStoreWithSelector` from
+// `use-sync-external-store/shim/with-selector`. That shim is React-specific, so
+// this package carries a local port of the same algorithm; see
+// ./useSyncExternalStoreWithSelector.ts.
+import { useCallback } from 'octane';
+import { AnyActorRef } from 'xstate';
+import { splitSlot, subSlot } from './internal.ts';
+import { useSyncExternalStoreWithSelector } from './useSyncExternalStoreWithSelector.ts';
+
+type SyncExternalStoreSubscribe = (onStoreChange: () => void) => () => void;
+
+function defaultCompare<T>(a: T, b: T) {
+	return a === b;
+}
+
+export function useSelector<
+	TActor extends Pick<AnyActorRef, 'subscribe' | 'getSnapshot'> | undefined,
+	T,
+>(
+	actor: TActor,
+	selector: (
+		snapshot: TActor extends { getSnapshot(): infer TSnapshot } ? TSnapshot : undefined,
+	) => T,
+	...rest: [compare?: (a: T, b: T) => boolean, slot?: symbol]
+): T {
+	const [userArgs, slot] = splitSlot(rest as unknown[]);
+	const compare = (userArgs[0] as ((a: T, b: T) => boolean) | undefined) ?? defaultCompare;
+
+	const subscribe: SyncExternalStoreSubscribe = useCallback(
+		(handleStoreChange) => {
+			if (!actor) {
+				return () => {};
+			}
+			const { unsubscribe } = actor.subscribe({
+				next: handleStoreChange,
+				error: handleStoreChange,
+			});
+			return unsubscribe;
+		},
+		[actor],
+		subSlot(slot, 'selector:subscribe'),
+	);
+
+	const boundGetSnapshot = useCallback(
+		() => {
+			const snapshot = actor?.getSnapshot();
+			if (snapshot && 'status' in snapshot && snapshot.status === 'error') {
+				throw snapshot.error;
+			}
+			return snapshot;
+		},
+		[actor],
+		subSlot(slot, 'selector:snapshot'),
+	);
+
+	const selectedSnapshot = useSyncExternalStoreWithSelector(
+		subscribe,
+		boundGetSnapshot,
+		boundGetSnapshot,
+		selector as (snapshot: unknown) => T,
+		compare,
+		subSlot(slot, 'selector:external-store'),
+	);
+
+	return selectedSnapshot;
+}

package/src/useSyncExternalStoreWithSelector.ts

@@ -0,0 +1,113 @@
+// Replaces @xstate/react@6.1.0's `use-sync-external-store/shim/with-selector`
+// dependency: React's shim, reimplemented on Octane's native
+// useSyncExternalStore with the exact same memoization algorithm. The selection
+// is recomputed only when the SNAPSHOT changes; when `isEqual` says the new
+// selection matches the previous one, the previous REFERENCE is kept so the
+// store's uSES bails the re-render out.
+//
+// Byte-compatible with the copies in @octanejs/redux and
+// @octanejs/tanstack-store; kept local so this package's published source has no
+// cross-binding runtime dependency.
+import { useSyncExternalStore, useRef, useMemo, useEffect } from 'octane';
+import { splitSlot, subSlot } from './internal.ts';
+
+const objectIs: (x: unknown, y: unknown) => boolean =
+	typeof Object.is === 'function'
+		? Object.is
+		: (x: any, y: any) => (x === y && (x !== 0 || 1 / x === 1 / y)) || (x !== x && y !== y);
+
+export function useSyncExternalStoreWithSelector<Snapshot, Selection>(
+	subscribe: (onStoreChange: () => void) => () => void,
+	getSnapshot: () => Snapshot,
+	getServerSnapshot: undefined | null | (() => Snapshot),
+	selector: (snapshot: Snapshot) => Selection,
+	...rest: [isEqual?: (a: Selection, b: Selection) => boolean, slot?: symbol]
+): Selection {
+	// A compiled direct call that omits the optional equality function arrives as
+	// `[slot]`, while binding-internal calls arrive as `[isEqual, slot]`. Split the
+	// compiler-owned tail before interpreting the user argument so a Symbol can
+	// never be mistaken for an equality function.
+	const [userArgs, slot] = splitSlot(rest);
+	const isEqual = userArgs[0] as ((a: Selection, b: Selection) => boolean) | undefined;
+	const instRef = useRef<{ hasValue: boolean; value: Selection | null } | null>(
+		null,
+		subSlot(slot, 'ws:inst'),
+	);
+	let inst: { hasValue: boolean; value: Selection | null };
+	if (instRef.current === null) {
+		inst = { hasValue: false, value: null };
+		instRef.current = inst;
+	} else {
+		inst = instRef.current;
+	}
+
+	const [getSelection, getServerSelection] = useMemo(
+		() => {
+			let hasMemo = false;
+			let memoizedSnapshot: Snapshot;
+			let memoizedSelection: Selection;
+			const memoizedSelector = (nextSnapshot: Snapshot): Selection => {
+				if (!hasMemo) {
+					hasMemo = true;
+					memoizedSnapshot = nextSnapshot;
+					const nextSelection = selector(nextSnapshot);
+					if (isEqual !== undefined && inst.hasValue) {
+						const currentSelection = inst.value as Selection;
+						if (isEqual(currentSelection, nextSelection)) {
+							return (memoizedSelection = currentSelection);
+						}
+					}
+					return (memoizedSelection = nextSelection);
+				}
+				const currentSelection = memoizedSelection;
+				if (objectIs(memoizedSnapshot, nextSnapshot)) return currentSelection;
+				const nextSelection = selector(nextSnapshot);
+				if (isEqual !== undefined && isEqual(currentSelection, nextSelection)) {
+					memoizedSnapshot = nextSnapshot;
+					return currentSelection;
+				}
+				memoizedSnapshot = nextSnapshot;
+				return (memoizedSelection = nextSelection);
+			};
+			const maybeGetServerSnapshot = getServerSnapshot === undefined ? null : getServerSnapshot;
+			return [
+				() => memoizedSelector(getSnapshot()),
+				maybeGetServerSnapshot === null
+					? undefined
+					: () => memoizedSelector(maybeGetServerSnapshot!()),
+			] as const;
+		},
+		[getSnapshot, getServerSnapshot, selector, isEqual],
+		subSlot(slot, 'ws:memo'),
+	);
+
+	// Octane gates its commit-time store sync on the VALUE rather than re-reading
+	// `getSnapshot` at commit the way React does, so a store that mutates without
+	// notifying between render and commit is not reconciled until its next notify.
+	// Unreachable through this binding, whose actors always notify.
+	// OCTANE DIVERGENCE[xstate-sync-external-store-commit-reread][ordinary:xstate-sync-external-store-skips-commit-reread]
+	//
+	// The server snapshot is defaulted rather than forwarded as `undefined`.
+	// Upstream's `use-sync-external-store` shim passes `getServerSelection`
+	// through, which is what makes React throw when a caller supplies no server
+	// snapshot; Octane's hook already falls back to `getSnapshot`, and this
+	// default keeps the memoized selection on that same path.
+	// OCTANE DIVERGENCE[xstate-optional-server-snapshot][ordinary:xstate-server-snapshot-fallback]
+	const value = useSyncExternalStore(
+		subscribe,
+		getSelection,
+		getServerSelection ?? getSelection,
+		subSlot(slot, 'ws:uses'),
+	);
+
+	useEffect(
+		() => {
+			inst.hasValue = true;
+			inst.value = value;
+		},
+		[value],
+		subSlot(slot, 'ws:eff'),
+	);
+
+	return value;
+}