@quenty/steputils 3.6.3 → 3.7.1

package/CHANGELOG.md

@@ -3,187 +3,119 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-## [3.6.3](https://github.com/Quenty/NevermoreEngine/compare/@quenty/steputils@3.6.2...@quenty/steputils@3.6.3) (2026-01-12)
-
+## [3.7.1](https://github.com/Quenty/NevermoreEngine/compare/@quenty/steputils@3.7.0...@quenty/steputils@3.7.1) (2026-07-25)
 
 ### Bug Fixes
 
-* Fix dependency installation process for pnpm ([9651b09](https://github.com/Quenty/NevermoreEngine/commit/9651b09af34f252ef3f9c7c539793cc878dd8cba))
+- Fix things ([de8a3b5](https://github.com/Quenty/NevermoreEngine/commit/de8a3b5fbe2aa839f6fc928d4052405d3a13cd71))
 
+# [3.7.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/steputils@3.6.3...@quenty/steputils@3.7.0) (2026-07-23)
 
+### Bug Fixes
 
+- Cleanup code a bit ([fa8c596](https://github.com/Quenty/NevermoreEngine/commit/fa8c596544e45610e180f5ae3797154f35930ccd))
 
+### Features
 
-## [3.6.2](https://github.com/Quenty/NevermoreEngine/compare/@quenty/steputils@3.6.1...@quenty/steputils@3.6.2) (2026-01-10)
+- Add baseline player-mock and support across Nevermore for mocked players. ([567d121](https://github.com/Quenty/NevermoreEngine/commit/567d121ffc014b42391554088189a1a6296dda83))
 
-**Note:** Version bump only for package @quenty/steputils
+## [3.6.3](https://github.com/Quenty/NevermoreEngine/compare/@quenty/steputils@3.6.2...@quenty/steputils@3.6.3) (2026-01-12)
 
+### Bug Fixes
 
+- Fix dependency installation process for pnpm ([9651b09](https://github.com/Quenty/NevermoreEngine/commit/9651b09af34f252ef3f9c7c539793cc878dd8cba))
 
+## [3.6.2](https://github.com/Quenty/NevermoreEngine/compare/@quenty/steputils@3.6.1...@quenty/steputils@3.6.2) (2026-01-10)
 
+**Note:** Version bump only for package @quenty/steputils
 
 ## [3.6.1](https://github.com/Quenty/NevermoreEngine/compare/@quenty/steputils@3.6.0...@quenty/steputils@3.6.1) (2026-01-03)
 
 **Note:** Version bump only for package @quenty/steputils
 
-
-
-
-
 # [3.6.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/steputils@3.5.5...@quenty/steputils@3.6.0) (2025-05-10)
 
 **Note:** Version bump only for package @quenty/steputils
 
-
-
-
-
 ## [3.5.5](https://github.com/Quenty/NevermoreEngine/compare/@quenty/steputils@3.5.3...@quenty/steputils@3.5.5) (2025-04-07)
 
-
 ### Bug Fixes
 
-* Add types to packages ([2374fb2](https://github.com/Quenty/NevermoreEngine/commit/2374fb2b043cfbe0e9b507b3316eec46a4e353a0))
-* Bump package versions for republishing ([ba47c62](https://github.com/Quenty/NevermoreEngine/commit/ba47c62e32170bf74377b0c658c60b84306dc294))
-
-
-
-
+- Add types to packages ([2374fb2](https://github.com/Quenty/NevermoreEngine/commit/2374fb2b043cfbe0e9b507b3316eec46a4e353a0))
+- Bump package versions for republishing ([ba47c62](https://github.com/Quenty/NevermoreEngine/commit/ba47c62e32170bf74377b0c658c60b84306dc294))
 
 ## [3.5.4](https://github.com/Quenty/NevermoreEngine/compare/@quenty/steputils@3.5.3...@quenty/steputils@3.5.4) (2025-04-07)
 
-
 ### Bug Fixes
 
-* Add types to packages ([2374fb2](https://github.com/Quenty/NevermoreEngine/commit/2374fb2b043cfbe0e9b507b3316eec46a4e353a0))
-
-
-
-
+- Add types to packages ([2374fb2](https://github.com/Quenty/NevermoreEngine/commit/2374fb2b043cfbe0e9b507b3316eec46a4e353a0))
 
 ## [3.5.3](https://github.com/Quenty/NevermoreEngine/compare/@quenty/steputils@3.5.2...@quenty/steputils@3.5.3) (2025-03-21)
 
 **Note:** Version bump only for package @quenty/steputils
 
-
-
-
-
 ## [3.5.2](https://github.com/Quenty/NevermoreEngine/compare/@quenty/steputils@3.5.1...@quenty/steputils@3.5.2) (2024-10-09)
 
-
 ### Bug Fixes
 
-* Deprecate a large set of APIs ([#506](https://github.com/Quenty/NevermoreEngine/issues/506)) ([d6bdd65](https://github.com/Quenty/NevermoreEngine/commit/d6bdd6567668f238c45d3bd0c85bedb763d30e5c))
-
-
-
-
+- Deprecate a large set of APIs ([#506](https://github.com/Quenty/NevermoreEngine/issues/506)) ([d6bdd65](https://github.com/Quenty/NevermoreEngine/commit/d6bdd6567668f238c45d3bd0c85bedb763d30e5c))
 
 ## [3.5.1](https://github.com/Quenty/NevermoreEngine/compare/@quenty/steputils@3.5.0...@quenty/steputils@3.5.1) (2024-10-04)
 
 **Note:** Version bump only for package @quenty/steputils
 
-
-
-
-
 # [3.5.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/steputils@3.4.0...@quenty/steputils@3.5.0) (2024-09-25)
 
 **Note:** Version bump only for package @quenty/steputils
 
-
-
-
-
 # [3.4.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/steputils@3.3.0...@quenty/steputils@3.4.0) (2024-05-09)
 
-
 ### Bug Fixes
 
-* Fix .package-lock.json replicating in packages ([75d0efe](https://github.com/Quenty/NevermoreEngine/commit/75d0efeef239f221d93352af71a5b3e930ec23c5))
-
-
-
-
+- Fix .package-lock.json replicating in packages ([75d0efe](https://github.com/Quenty/NevermoreEngine/commit/75d0efeef239f221d93352af71a5b3e930ec23c5))
 
 # [3.3.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/steputils@3.2.0...@quenty/steputils@3.3.0) (2023-09-04)
 
-
 ### Features
 
-* Add StepUtils.deferWait() ([caac896](https://github.com/Quenty/NevermoreEngine/commit/caac896fc8439d0de87245cf4bdcb534ba2a9efe))
-
-
-
-
+- Add StepUtils.deferWait() ([caac896](https://github.com/Quenty/NevermoreEngine/commit/caac896fc8439d0de87245cf4bdcb534ba2a9efe))
 
 # [3.2.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/steputils@3.1.0...@quenty/steputils@3.2.0) (2022-10-11)
 
-
 ### Features
 
-* Add StepUtils.bindToStepped ([f49f70d](https://github.com/Quenty/NevermoreEngine/commit/f49f70d870fa9fd8276a9cb0056a40ebeb85c049))
-
-
-
-
+- Add StepUtils.bindToStepped ([f49f70d](https://github.com/Quenty/NevermoreEngine/commit/f49f70d870fa9fd8276a9cb0056a40ebeb85c049))
 
 # [3.1.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/steputils@3.0.1...@quenty/steputils@3.1.0) (2022-03-27)
 
 **Note:** Version bump only for package @quenty/steputils
 
-
-
-
-
 ## [3.0.1](https://github.com/Quenty/NevermoreEngine/compare/@quenty/steputils@3.0.0...@quenty/steputils@3.0.1) (2021-12-30)
 
 **Note:** Version bump only for package @quenty/steputils
 
-
-
-
-
 # [3.0.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/steputils@2.0.0...@quenty/steputils@3.0.0) (2021-09-11)
 
-
 ### Features
 
-* Add new methods to StepUtils ([738712a](https://github.com/Quenty/NevermoreEngine/commit/738712a3fea2ccf5ba1d479749d6db73d28a0902))
-
-
-
-
+- Add new methods to StepUtils ([738712a](https://github.com/Quenty/NevermoreEngine/commit/738712a3fea2ccf5ba1d479749d6db73d28a0902))
 
 # [2.0.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/steputils@1.2.0...@quenty/steputils@2.0.0) (2021-09-05)
 
-
 ### Bug Fixes
 
-* Remove peer dependencies. This is because lerna doesn't really support peer dependencies being linked and getting a new version on build, which is unfortunate. ([5f5aeee](https://github.com/Quenty/NevermoreEngine/commit/5f5aeeea8de9975435309e53679f0ef7064f9dd0))
-
-
-
-
+- Remove peer dependencies. This is because lerna doesn't really support peer dependencies being linked and getting a new version on build, which is unfortunate. ([5f5aeee](https://github.com/Quenty/NevermoreEngine/commit/5f5aeeea8de9975435309e53679f0ef7064f9dd0))
 
 # 1.2.0 (2021-07-31)
 
-
 ### Bug Fixes
 
-* Add CI and CD ([47513e9](https://github.com/Quenty/NevermoreEngine/commit/47513e9b568162707534af132396dd8756947dd3))
-* Adjust CI badge to show automatic build and release state ([5a55d3f](https://github.com/Quenty/NevermoreEngine/commit/5a55d3f19bf8d66a760d67da9b56ed47fab74656))
-* Fix selene linting ([45fc074](https://github.com/Quenty/NevermoreEngine/commit/45fc07489ee59127ac6582689f19a0e87c1e5b5a))
-
-
+- Add CI and CD ([47513e9](https://github.com/Quenty/NevermoreEngine/commit/47513e9b568162707534af132396dd8756947dd3))
+- Adjust CI badge to show automatic build and release state ([5a55d3f](https://github.com/Quenty/NevermoreEngine/commit/5a55d3f19bf8d66a760d67da9b56ed47fab74656))
+- Fix selene linting ([45fc074](https://github.com/Quenty/NevermoreEngine/commit/45fc07489ee59127ac6582689f19a0e87c1e5b5a))
 
 ## 1.0.2 (2021-07-25)
 
-
-
 ## 1.0.1 (2021-07-25)
 
-
-
 # 1.0.0 (2021-07-24)

package/deploy.nevermore.json

@@ -0,0 +1,10 @@
+{
+  "targets": {
+    "test": {
+      "universeId": 9716264427,
+      "placeId": 80583370987435,
+      "project": "test/default.project.json",
+      "scriptTemplate": "test/scripts/Server/ServerMain.server.lua"
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/steputils",
-  "version": "3.6.3",
+  "version": "3.7.1",
   "description": "Binds animations into step, where the animation only runs as needed",
   "keywords": [
     "Roblox",
@@ -27,8 +27,13 @@
   "contributors": [
     "Quenty"
   ],
+  "dependencies": {
+    "@quenty/loader": "10.11.0",
+    "@quenty/nevermore-test-runner": "1.5.0",
+    "@quentystudios/jest-lua": "3.10.0-quenty.2"
+  },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "55f4a7407de7247aceea574de4d2f57dab70cb91"
+  "gitHead": "f276b791b8eb4e88b952b5babaf0f4189c1a11d0"
 }

package/src/Shared/StepUtils.lua

@@ -10,7 +10,59 @@ local RunService = game:GetService("RunService")
 local StepUtils = {}
 
 --[=[
-	Binds the given update function to [RunService.RenderStepped].
+	Returns the signal animation should step on: [RunService.RenderStepped] on the client,
+	[RunService.Stepped] (the physics pre-step) on a running server so that writes land before
+	the physics step -- springs that drive CFrames stay in lockstep with constraints, characters,
+	and replication. Heartbeat is only the fallback for a non-running DataModel (headless test
+	runs, edit mode), where Stepped never fires.
+
+	Use this instead of hand-rolling the realm branch at call sites.
+
+	:::caution
+	The argument shape is realm-dependent: RenderStepped fires `(deltaTime)` but Stepped fires
+	`(time, deltaTime)`. Shared code connecting directly to this signal must not assume the
+	first argument is deltaTime.
+	:::
+
+	@return RBXScriptSignal
+]=]
+function StepUtils.getAnimationStepSignal(): RBXScriptSignal
+	if RunService:IsClient() then
+		return RunService.RenderStepped
+	elseif RunService:IsRunning() then
+		return RunService.Stepped
+	else
+		return RunService.Heartbeat
+	end
+end
+
+--[=[
+	Returns the signal per-frame bookkeeping should run on: [RunService.Stepped] (the physics
+	pre-step) on a running DataModel, falling back to [RunService.Heartbeat] on a non-running one
+	(headless test runs, edit mode) where Stepped never fires.
+
+	Unlike [StepUtils.getAnimationStepSignal] this does not branch to RenderStepped on the client,
+	so both realms step at the same point in the frame. Prefer it for work that is not driving
+	visuals -- rescoring, polling, cache invalidation -- and that would otherwise silently stop
+	running outside a live game.
+
+	:::caution
+	Stepped fires `(time, deltaTime)` but Heartbeat fires `(deltaTime)`. Do not assume the first
+	argument is deltaTime when connecting directly to this signal.
+	:::
+
+	@return RBXScriptSignal
+]=]
+function StepUtils.getSteppedSignal(): RBXScriptSignal
+	if RunService:IsRunning() then
+		return RunService.Stepped
+	else
+		return RunService.Heartbeat
+	end
+end
+
+--[=[
+	Binds the given update function to [StepUtils.getAnimationStepSignal].
 
 	```lua
 	local spring = Spring.new(0)
@@ -37,7 +89,7 @@ local StepUtils = {}
 	@return () -> () -- Disconnect function
 ]=]
 function StepUtils.bindToRenderStep(update: () -> boolean): (() -> (), () -> ())
-	return StepUtils.bindToSignal(RunService.RenderStepped, update)
+	return StepUtils.bindToSignal(StepUtils.getAnimationStepSignal(), update)
 end
 
 --[=[
@@ -183,7 +235,7 @@ end
 	@return function -- Call this function to cancel call
 ]=]
 function StepUtils.onceAtRenderStepped(func: () -> ()): () -> ()
-	local conn = RunService.RenderStepped:Once(func)
+	local conn = StepUtils.getAnimationStepSignal():Once(func)
 	return function()
 		conn:Disconnect()
 	end

package/src/Shared/StepUtils.spec.lua

@@ -0,0 +1,635 @@
+--!strict
+--[[
+	@class StepUtils.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local RunService = game:GetService("RunService")
+
+local Jest = require("Jest")
+local StepUtils = require("StepUtils")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+type Controller = {
+	newBindable: () -> BindableEvent,
+	bind: (RBXScriptSignal, (...any) -> boolean) -> ((...any) -> (), () -> ()),
+	bindRenderStep: ((...any) -> boolean) -> ((...any) -> (), () -> ()),
+	bindStepped: ((...any) -> boolean) -> ((...any) -> (), () -> ()),
+	track: (() -> ()) -> () -> (),
+	stepFrames: (number) -> (),
+	destroy: () -> (),
+}
+
+local function setup(): Controller
+	local instances: { Instance } = {}
+	local cleanups: { () -> () } = {}
+
+	local function track(cleanup: () -> ()): () -> ()
+		table.insert(cleanups, cleanup)
+		return cleanup
+	end
+
+	local controller: Controller = {
+		newBindable = function()
+			local bindable = Instance.new("BindableEvent")
+			table.insert(instances, bindable)
+			return bindable
+		end,
+
+		bind = function(signal, update)
+			local connect, disconnect = StepUtils.bindToSignal(signal, update)
+			track(disconnect)
+			return connect, disconnect
+		end,
+
+		bindRenderStep = function(update)
+			local connect, disconnect = StepUtils.bindToRenderStep(update)
+			track(disconnect)
+			return connect, disconnect
+		end,
+
+		bindStepped = function(update)
+			local connect, disconnect = StepUtils.bindToStepped(update)
+			track(disconnect)
+			return connect, disconnect
+		end,
+
+		track = track,
+
+		stepFrames = function(count: number)
+			for _ = 1, count do
+				task.wait()
+			end
+		end,
+
+		destroy = function()
+			for _, cleanup in cleanups do
+				cleanup()
+			end
+			for _, inst in instances do
+				inst:Destroy()
+			end
+		end,
+	}
+
+	return controller
+end
+
+describe("StepUtils.getAnimationStepSignal", function()
+	it("returns a signal", function()
+		local controller = setup()
+
+		expect(typeof(StepUtils.getAnimationStepSignal())).toBe("RBXScriptSignal")
+
+		controller.destroy()
+	end)
+
+	it("falls back to Heartbeat off a running client", function()
+		local controller = setup()
+
+		expect(StepUtils.getAnimationStepSignal()).toBe(RunService.Heartbeat)
+
+		controller.destroy()
+	end)
+
+	it("returns a signal that actually fires here", function()
+		local controller = setup()
+
+		local fired = false
+		local conn = StepUtils.getAnimationStepSignal():Connect(function()
+			fired = true
+		end)
+		controller.track(function()
+			conn:Disconnect()
+		end)
+
+		controller.stepFrames(2)
+
+		expect(fired).toBe(true)
+
+		controller.destroy()
+	end)
+end)
+
+describe("StepUtils.getSteppedSignal", function()
+	it("returns a signal", function()
+		local controller = setup()
+
+		expect(typeof(StepUtils.getSteppedSignal())).toBe("RBXScriptSignal")
+
+		controller.destroy()
+	end)
+
+	it("falls back to Heartbeat on a non-running DataModel", function()
+		local controller = setup()
+
+		expect(StepUtils.getSteppedSignal()).toBe(RunService.Heartbeat)
+		expect(StepUtils.getSteppedSignal()).never.toBe(RunService.Stepped)
+
+		controller.destroy()
+	end)
+
+	it("returns a signal that actually fires here", function()
+		local controller = setup()
+
+		local fired = false
+		local conn = StepUtils.getSteppedSignal():Connect(function()
+			fired = true
+		end)
+		controller.track(function()
+			conn:Disconnect()
+		end)
+
+		controller.stepFrames(2)
+
+		expect(fired).toBe(true)
+
+		controller.destroy()
+	end)
+end)
+
+describe("StepUtils.bindToSignal", function()
+	it("invokes the update immediately on connect", function()
+		local controller = setup()
+		local bindable = controller.newBindable()
+
+		local calls = 0
+		local connect = controller.bind(bindable.Event, function()
+			calls += 1
+			return false
+		end)
+
+		connect()
+
+		expect(calls).toBe(1)
+
+		controller.destroy()
+	end)
+
+	it("does not connect when the first update returns false", function()
+		local controller = setup()
+		local bindable = controller.newBindable()
+
+		local calls = 0
+		local connect = controller.bind(bindable.Event, function()
+			calls += 1
+			return false
+		end)
+
+		connect()
+		bindable:Fire()
+		bindable:Fire()
+
+		expect(calls).toBe(1)
+
+		controller.destroy()
+	end)
+
+	it("keeps invoking the update while it returns true", function()
+		local controller = setup()
+		local bindable = controller.newBindable()
+
+		local calls = 0
+		local connect = controller.bind(bindable.Event, function()
+			calls += 1
+			return calls < 3
+		end)
+
+		connect()
+		bindable:Fire()
+		bindable:Fire()
+
+		expect(calls).toBe(3)
+
+		controller.destroy()
+	end)
+
+	it("stops invoking the update once it returns false", function()
+		local controller = setup()
+		local bindable = controller.newBindable()
+
+		local calls = 0
+		local connect = controller.bind(bindable.Event, function()
+			calls += 1
+			return calls < 2
+		end)
+
+		connect()
+		bindable:Fire()
+		bindable:Fire()
+		bindable:Fire()
+
+		expect(calls).toBe(2)
+
+		controller.destroy()
+	end)
+
+	it("forwards the connect arguments to every later update", function()
+		local controller = setup()
+		local bindable = controller.newBindable()
+
+		local seen = {}
+		local connect = controller.bind(bindable.Event, function(arg)
+			table.insert(seen, arg)
+			return #seen < 3
+		end)
+
+		connect("self")
+		bindable:Fire()
+		bindable:Fire()
+
+		expect(seen).toEqual({ "self", "self", "self" })
+
+		controller.destroy()
+	end)
+
+	it("ignores the signal's own arguments", function()
+		local controller = setup()
+		local bindable = controller.newBindable()
+
+		local seen = {}
+		local connect = controller.bind(bindable.Event, function(arg)
+			table.insert(seen, { value = arg })
+			return #seen < 2
+		end)
+
+		connect()
+		bindable:Fire("fromSignal")
+
+		expect(seen).toEqual({ { value = nil }, { value = nil } })
+
+		controller.destroy()
+	end)
+
+	it("ignores a repeated connect while already connected", function()
+		local controller = setup()
+		local bindable = controller.newBindable()
+
+		local calls = 0
+		local connect = controller.bind(bindable.Event, function()
+			calls += 1
+			return true
+		end)
+
+		connect()
+		connect()
+
+		expect(calls).toBe(1)
+
+		controller.destroy()
+	end)
+
+	it("reconnects after an explicit disconnect", function()
+		local controller = setup()
+		local bindable = controller.newBindable()
+
+		local calls = 0
+		local connect, disconnect = controller.bind(bindable.Event, function()
+			calls += 1
+			return true
+		end)
+
+		connect()
+		disconnect()
+		bindable:Fire()
+		expect(calls).toBe(1)
+
+		connect()
+		bindable:Fire()
+
+		expect(calls).toBe(3)
+
+		controller.destroy()
+	end)
+
+	it("tolerates disconnect before connect and repeated disconnects", function()
+		local controller = setup()
+		local bindable = controller.newBindable()
+
+		local _connect, disconnect = controller.bind(bindable.Event, function()
+			return true
+		end)
+
+		expect(function()
+			disconnect()
+			disconnect()
+		end).never.toThrow()
+
+		controller.destroy()
+	end)
+
+	it("throws on something that is not a signal", function()
+		local controller = setup()
+
+		expect(function()
+			(StepUtils :: any).bindToSignal({}, function()
+				return false
+			end)
+		end).toThrow()
+
+		controller.destroy()
+	end)
+
+	it("throws on a non-function update", function()
+		local controller = setup()
+		local bindable = controller.newBindable()
+
+		expect(function()
+			(StepUtils :: any).bindToSignal(bindable.Event, "update")
+		end).toThrow()
+
+		controller.destroy()
+	end)
+end)
+
+describe("StepUtils.bindToRenderStep", function()
+	it("drives the update off the animation step signal", function()
+		local controller = setup()
+
+		local calls = 0
+		local connect = controller.bindRenderStep(function()
+			calls += 1
+			return calls < 3
+		end)
+
+		connect()
+		controller.stepFrames(5)
+
+		expect(calls).toBe(3)
+
+		controller.destroy()
+	end)
+
+	it("does not bind when the first update returns false", function()
+		local controller = setup()
+
+		local calls = 0
+		local connect = controller.bindRenderStep(function()
+			calls += 1
+			return false
+		end)
+
+		connect()
+		controller.stepFrames(3)
+
+		expect(calls).toBe(1)
+
+		controller.destroy()
+	end)
+
+	it("stops driving the update after disconnect", function()
+		local controller = setup()
+
+		local calls = 0
+		local connect, disconnect = controller.bindRenderStep(function()
+			calls += 1
+			return true
+		end)
+
+		connect()
+		controller.stepFrames(2)
+		disconnect()
+
+		local afterDisconnect = calls
+		controller.stepFrames(3)
+
+		expect(calls).toBe(afterDisconnect)
+
+		controller.destroy()
+	end)
+end)
+
+describe("StepUtils.bindToStepped", function()
+	it("invokes the update immediately on connect", function()
+		local controller = setup()
+
+		local calls = 0
+		local connect = controller.bindStepped(function()
+			calls += 1
+			return false
+		end)
+
+		connect()
+
+		expect(calls).toBe(1)
+
+		controller.destroy()
+	end)
+
+	it("tolerates disconnect before connect", function()
+		local controller = setup()
+
+		local _connect, disconnect = controller.bindStepped(function()
+			return true
+		end)
+
+		expect(function()
+			disconnect()
+		end).never.toThrow()
+
+		controller.destroy()
+	end)
+end)
+
+describe("StepUtils.deferWait", function()
+	it("resumes only after already-queued deferrals run", function()
+		local controller = setup()
+
+		local order = {}
+		task.defer(function()
+			table.insert(order, "deferred")
+		end)
+
+		StepUtils.deferWait()
+		table.insert(order, "resumed")
+
+		expect(order).toEqual({ "deferred", "resumed" })
+
+		controller.destroy()
+	end)
+end)
+
+describe("StepUtils.onceAtEvent", function()
+	it("invokes the function on the next event", function()
+		local controller = setup()
+		local bindable = controller.newBindable()
+
+		local calls = 0
+		controller.track(StepUtils.onceAtEvent(bindable.Event, function()
+			calls += 1
+		end))
+
+		bindable:Fire()
+
+		expect(calls).toBe(1)
+
+		controller.destroy()
+	end)
+
+	it("passes the event arguments through", function()
+		local controller = setup()
+		local bindable = controller.newBindable()
+
+		local seen: any = nil
+		controller.track(StepUtils.onceAtEvent(bindable.Event, function(value: any)
+			seen = value
+		end))
+
+		bindable:Fire("payload")
+
+		expect(seen).toBe("payload")
+
+		controller.destroy()
+	end)
+
+	it("only invokes the function once", function()
+		local controller = setup()
+		local bindable = controller.newBindable()
+
+		local calls = 0
+		controller.track(StepUtils.onceAtEvent(bindable.Event, function()
+			calls += 1
+		end))
+
+		bindable:Fire()
+		bindable:Fire()
+
+		expect(calls).toBe(1)
+
+		controller.destroy()
+	end)
+
+	it("does not invoke the function once cancelled", function()
+		local controller = setup()
+		local bindable = controller.newBindable()
+
+		local calls = 0
+		local cancel = StepUtils.onceAtEvent(bindable.Event, function()
+			calls += 1
+		end)
+
+		cancel()
+		bindable:Fire()
+
+		expect(calls).toBe(0)
+
+		controller.destroy()
+	end)
+
+	it("tolerates cancelling after the function ran", function()
+		local controller = setup()
+		local bindable = controller.newBindable()
+
+		local cancel = StepUtils.onceAtEvent(bindable.Event, function() end)
+		bindable:Fire()
+
+		expect(function()
+			cancel()
+			cancel()
+		end).never.toThrow()
+
+		controller.destroy()
+	end)
+
+	it("throws on a non-function", function()
+		local controller = setup()
+		local bindable = controller.newBindable()
+
+		expect(function()
+			(StepUtils :: any).onceAtEvent(bindable.Event, "func")
+		end).toThrow()
+
+		controller.destroy()
+	end)
+end)
+
+describe("StepUtils.onceAtRenderStepped", function()
+	it("invokes the function once on the animation step signal", function()
+		local controller = setup()
+
+		local calls = 0
+		controller.track(StepUtils.onceAtRenderStepped(function()
+			calls += 1
+		end))
+
+		controller.stepFrames(3)
+
+		expect(calls).toBe(1)
+
+		controller.destroy()
+	end)
+
+	it("does not invoke the function once cancelled", function()
+		local controller = setup()
+
+		local calls = 0
+		local cancel = StepUtils.onceAtRenderStepped(function()
+			calls += 1
+		end)
+
+		cancel()
+		controller.stepFrames(3)
+
+		expect(calls).toBe(0)
+
+		controller.destroy()
+	end)
+end)
+
+describe("StepUtils.onceAtStepped", function()
+	it("returns a cancel function that is safe to call twice", function()
+		local controller = setup()
+
+		local calls = 0
+		local cancel = StepUtils.onceAtStepped(function()
+			calls += 1
+		end)
+
+		expect(function()
+			cancel()
+			cancel()
+		end).never.toThrow()
+		expect(calls).toBe(0)
+
+		controller.destroy()
+	end)
+end)
+
+describe("StepUtils.onceAtRenderPriority", function()
+	it("returns a cancel function that is safe to call twice", function()
+		local controller = setup()
+
+		local cancel = StepUtils.onceAtRenderPriority(Enum.RenderPriority.Last.Value, function() end)
+
+		expect(function()
+			cancel()
+			cancel()
+		end).never.toThrow()
+
+		controller.destroy()
+	end)
+
+	it("throws on a non-number priority", function()
+		local controller = setup()
+
+		expect(function()
+			(StepUtils :: any).onceAtRenderPriority("high", function() end)
+		end).toThrow()
+
+		controller.destroy()
+	end)
+
+	it("throws on a non-function", function()
+		local controller = setup()
+
+		expect(function()
+			(StepUtils :: any).onceAtRenderPriority(100, "func")
+		end).toThrow()
+
+		controller.destroy()
+	end)
+end)

package/src/Shared/onRenderStepFrame.spec.lua

@@ -0,0 +1,98 @@
+--!strict
+--[[
+	@class onRenderStepFrame.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Jest = require("Jest")
+local onRenderStepFrame = require("onRenderStepFrame")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+type Controller = {
+	bind: (number, () -> ()) -> () -> (),
+	destroy: () -> (),
+}
+
+local function setup(): Controller
+	local unbinds: { () -> () } = {}
+
+	local controller: Controller = {
+		bind = function(priority: number, callback: () -> ())
+			local unbind = onRenderStepFrame(priority, callback)
+			table.insert(unbinds, unbind)
+			return unbind
+		end,
+
+		destroy = function()
+			for _, unbind in unbinds do
+				unbind()
+			end
+		end,
+	}
+
+	return controller
+end
+
+describe("onRenderStepFrame", function()
+	it("returns an unbind function", function()
+		local controller = setup()
+
+		local unbind = controller.bind(Enum.RenderPriority.Last.Value, function() end)
+
+		expect(type(unbind)).toBe("function")
+
+		controller.destroy()
+	end)
+
+	it("tolerates a repeated unbind", function()
+		local controller = setup()
+
+		local unbind = controller.bind(Enum.RenderPriority.Last.Value, function() end)
+
+		expect(function()
+			unbind()
+			unbind()
+		end).never.toThrow()
+
+		controller.destroy()
+	end)
+
+	it("binds each call under its own key", function()
+		local controller = setup()
+
+		local first = controller.bind(Enum.RenderPriority.Last.Value, function() end)
+		local second = controller.bind(Enum.RenderPriority.Last.Value, function() end)
+
+		expect(second).never.toBe(first)
+		expect(function()
+			first()
+			second()
+		end).never.toThrow()
+
+		controller.destroy()
+	end)
+
+	it("throws on a non-number priority", function()
+		local controller = setup()
+
+		expect(function()
+			(onRenderStepFrame :: any)("high", function() end)
+		end).toThrow()
+
+		controller.destroy()
+	end)
+
+	it("throws on a non-function callback", function()
+		local controller = setup()
+
+		expect(function()
+			(onRenderStepFrame :: any)(100, "callback")
+		end).toThrow()
+
+		controller.destroy()
+	end)
+end)

package/src/Shared/onSteppedFrame.spec.lua

@@ -0,0 +1,85 @@
+--!strict
+--[[
+	@class onSteppedFrame.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Jest = require("Jest")
+local onSteppedFrame = require("onSteppedFrame")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+type Controller = {
+	bind: (() -> ()) -> RBXScriptConnection,
+	destroy: () -> (),
+}
+
+local function setup(): Controller
+	local connections: { RBXScriptConnection } = {}
+
+	local controller: Controller = {
+		bind = function(callback)
+			local conn = onSteppedFrame(callback)
+			table.insert(connections, conn)
+			return conn
+		end,
+
+		destroy = function()
+			for _, conn in connections do
+				conn:Disconnect()
+			end
+		end,
+	}
+
+	return controller
+end
+
+describe("onSteppedFrame", function()
+	it("returns a live connection", function()
+		local controller = setup()
+
+		local conn = controller.bind(function() end)
+
+		expect(typeof(conn)).toBe("RBXScriptConnection")
+		expect(conn.Connected).toBe(true)
+
+		controller.destroy()
+	end)
+
+	it("goes dead once disconnected", function()
+		local controller = setup()
+
+		local conn = controller.bind(function() end)
+		conn:Disconnect()
+
+		expect(conn.Connected).toBe(false)
+
+		controller.destroy()
+	end)
+
+	it("tolerates a repeated disconnect", function()
+		local controller = setup()
+
+		local conn = controller.bind(function() end)
+
+		expect(function()
+			conn:Disconnect()
+			conn:Disconnect()
+		end).never.toThrow()
+
+		controller.destroy()
+	end)
+
+	it("throws on a non-function", function()
+		local controller = setup()
+
+		expect(function()
+			(onSteppedFrame :: any)("func")
+		end).toThrow()
+
+		controller.destroy()
+	end)
+end)

package/src/jest.config.lua

@@ -0,0 +1,3 @@
+return {
+	testMatch = { "**/*.spec" },
+}

package/src/node_modules.project.json

@@ -0,0 +1,7 @@
+{
+  "name": "node_modules",
+  "globIgnorePaths": [ "**/.package-lock.json" ],
+  "tree": {
+    "$path": { "optional": "../node_modules" }
+  }
+}

package/test/default.project.json

@@ -0,0 +1,25 @@
+{
+  "name": "StepUtilsTest",
+  "globIgnorePaths": [
+    "**/.package-lock.json",
+    "**/.pnpm",
+    "**/.pnpm-workspace-state-v1.json",
+    "**/.modules.yaml",
+    "**/.ignored",
+    "**/.ignored_*"
+  ],
+  "tree": {
+    "$className": "DataModel",
+    "ServerScriptService": {
+      "$properties": {
+        "LoadStringEnabled": true
+      },
+      "steputils": {
+        "$path": ".."
+      },
+      "Script": {
+        "$path": "scripts/Server"
+      }
+    }
+  }
+}

package/test/scripts/Server/ServerMain.server.lua

@@ -0,0 +1,14 @@
+--!nonstrict
+--[[
+	@class ServerMain
+]]
+
+local ServerScriptService = game:GetService("ServerScriptService")
+
+local root = ServerScriptService.steputils
+local loader = root:FindFirstChild("LoaderUtils", true).Parent
+local require = require(loader).bootstrapGame(root)
+
+local NevermoreTestRunnerUtils = require("NevermoreTestRunnerUtils")
+
+NevermoreTestRunnerUtils.runTestsIfNeededAsync(root)