cluaupp 1.3.0 → 1.4.1

package/runtime/Fusion/Colour/Oklab.luau

@@ -1,70 +0,0 @@
---!strict
---!nolint LocalUnused
---!nolint LocalShadow
-local task = nil -- Disable usage of Roblox's task scheduler
-
---[[
-	Provides functions for converting Color3s into Oklab space, for more
-	perceptually uniform colour blending.
-
-	See: https://bottosson.github.io/posts/oklab/
-]]
-
-local sRGB = require(script.Parent.sRGB)
-
-local Oklab = {}
-
--- Converts a Color3 in linear RGB space to a Vector3 in Oklab space.
-function Oklab.fromLinear(rgb: Color3): Vector3
-
-	local l = rgb.R * 0.4122214708 + rgb.G * 0.5363325363 + rgb.B * 0.0514459929
-	local m = rgb.R * 0.2119034982 + rgb.G * 0.6806995451 + rgb.B * 0.1073969566
-	local s = rgb.R * 0.0883024619 + rgb.G * 0.2817188376 + rgb.B * 0.6299787005
-
-	local lRoot = l ^ (1/3)
-	local mRoot = m ^ (1/3)
-	local sRoot = s ^ (1/3)
-
-	return Vector3.new(
-		lRoot * 0.2104542553 + mRoot * 0.7936177850 - sRoot * 0.0040720468,
-		lRoot * 1.9779984951 - mRoot * 2.4285922050 + sRoot * 0.4505937099,
-		lRoot * 0.0259040371 + mRoot * 0.7827717662 - sRoot * 0.8086757660
-	)
-end
-
--- Converts a Color3 in sRGB space to a Vector3 in Oklab space.
-function Oklab.fromSRGB(srgb: Color3): Vector3
-	return Oklab.fromLinear(sRGB.toLinear(srgb))
-end
-
--- Converts a Vector3 in Oklab space to a Color3 in linear RGB space.
--- The Color3 will be clamped by default unless specified otherwise.
-function Oklab.toLinear(lab: Vector3, unclamped: boolean?): Color3
-	local lRoot = lab.X + lab.Y * 0.3963377774 + lab.Z * 0.2158037573
-	local mRoot = lab.X - lab.Y * 0.1055613458 - lab.Z * 0.0638541728
-	local sRoot = lab.X - lab.Y * 0.0894841775 - lab.Z * 1.2914855480
-
-	local l = lRoot ^ 3
-	local m = mRoot ^ 3
-	local s = sRoot ^ 3
-
-	local red = l * 4.0767416621 - m * 3.3077115913 + s * 0.2309699292
-	local green = l * -1.2684380046 + m * 2.6097574011 - s * 0.3413193965
-	local blue = l * -0.0041960863 - m * 0.7034186147 + s * 1.7076147010
-
-	if not unclamped then
-		red = math.clamp(red, 0, 1)
-		green = math.clamp(green, 0, 1)
-		blue = math.clamp(blue, 0, 1)
-	end
-
-	return Color3.new(red, green, blue)
-end
-
--- Converts a Vector3 in Oklab space to a Color3 in sRGB space.
--- The Color3 will be clamped by default unless specified otherwise.
-function Oklab.toSRGB(lab: Vector3, unclamped: boolean?): Color3
-	return sRGB.fromLinear(Oklab.toLinear(lab, unclamped))
-end
-
-return Oklab

package/runtime/Fusion/Colour/sRGB.luau

@@ -1,47 +0,0 @@
---!strict
---!nolint LocalUnused
---!nolint LocalShadow
-local task = nil -- Disable usage of Roblox's task scheduler
-
---[[
-    Provides transformation functions for converting linear RGB values
-    into sRGB values.
-
-    RGB color channel transformations are outlined here:
-    https://bottosson.github.io/posts/colorwrong/#what-can-we-do%3F
-]]
-
-local sRGB = {}
-
--- Equivalent to f_inv. Takes a linear sRGB channel and returns
--- the sRGB channel
-local function transform(channel: number): number
-    if channel < 0.04045 then
-        return channel / 12.92
-    end
-
-    return ((channel + 0.055) / 1.055) ^ 2.4
-end
-
--- Equivalent to f. Takes an sRGB channel and returns
--- the linear sRGB channel
-local function inverse(channel: number): number
-    if channel < 0.0031308 then
-        return 12.92 * channel
-    end
-
-    return (1.055 * channel ^ (1 / 2.4)) - 0.055
-end
-
--- Uses a transformation to convert linear RGB into sRGB.
-function sRGB.fromLinear(rgb: Color3): Color3
-    return Color3.new(inverse(rgb.R), inverse(rgb.G), inverse(rgb.B))
-end
-
--- Converts an sRGB into linear RGB using a
--- (The inverse of sRGB.fromLinear).
-function sRGB.toLinear(srgb: Color3): Color3
-    return Color3.new(transform(srgb.R), transform(srgb.G), transform(srgb.B))
-end
-
-return sRGB

package/runtime/Fusion/External.luau

@@ -1,156 +0,0 @@
---!strict
---!nolint LocalUnused
---!nolint LocalShadow
-local task = nil -- Disable usage of Roblox's task scheduler
-
---[[
-	Abstraction layer between Fusion internals and external environments,
-	allowing for flexible integration with schedulers and test mocks.
-]]
-
-local Package = script.Parent
-local formatError = require(Package.Logging.formatError)
-local Types = require(Package.Types)
-
-local ERROR_INFO_URL = "https://elttob.uk/Fusion/0.3/api-reference/general/errors/#"
-
-local External = {}
-
--- Multiplier for running-time safety checks across the Fusion codebase. Used to
--- stricten tests on infinite loop detection during unit testing.
-External.safetyTimerMultiplier = 1
-
-local updateStepCallbacks = {}
-local currentProvider: Types.ExternalProvider? = nil
-local lastUpdateStep = 0
-
---[[
-	Swaps to a new provider for external operations.
-	Returns the old provider, so it can be used again later.
-]]
-function External.setExternalProvider(
-	newProvider: Types.ExternalProvider?
-): Types.ExternalProvider?
-	local oldProvider = currentProvider
-	if oldProvider ~= nil then
-		oldProvider.stopScheduler()
-	end
-	currentProvider = newProvider
-	if newProvider ~= nil then
-		newProvider.startScheduler()
-	end
-	return oldProvider
-end
-
---[[
-   Sends an immediate task to the external provider. Throws if none is set.
-]]
-function External.doTaskImmediate(
-	resume: () -> ()
-)
-	if currentProvider == nil then
-		External.logError("noTaskScheduler")
-	else
-		currentProvider.doTaskImmediate(resume)
-	end
-end
-
---[[
-	Sends a deferred task to the external provider. Throws if none is set.
-]]
-function External.doTaskDeferred(
-	resume: () -> ()
-)
-	if currentProvider == nil then
-		External.logError("noTaskScheduler")
-	else
-		currentProvider.doTaskDeferred(resume)
-	end
-end
-
---[[
-	Errors in the current thread and halts execution.
-]]
-function External.logError(
-	messageID: string,
-	errObj: Types.Error?,
-	...: unknown
-): never
-	error(formatError(currentProvider, messageID, errObj, ...), 0)
-end
-
---[[
-	Errors in a different thread to preserve the flow of execution.
-]]
-function External.logErrorNonFatal(
-	messageID: string,
-	errObj: Types.Error?,
-	...: unknown
-): ()
-	local errorString = formatError(currentProvider, messageID, errObj, ...)
-	if currentProvider ~= nil then
-		currentProvider.logErrorNonFatal(errorString)
-	else
-		print(errorString)
-	end
-end
-
---[[
-	Shows a warning message in the output.
-]]
-function External.logWarn(
-	messageID: string,
-	...: unknown
-): ()
-	local errorString = formatError(currentProvider, messageID, debug.traceback(nil, 2), ...)
-	if currentProvider ~= nil then
-		currentProvider.logWarn(errorString)
-	else
-		print(errorString)
-	end
-end
-
---[[
-	Registers a callback to the update step of the external provider.
-	Returns a function that can be used to disconnect later.
-
-	Callbacks are given the current number of seconds since an arbitrary epoch.
-	
-	TODO: This epoch may change between providers. We could investigate ways
-	of allowing providers to co-operate to keep the epoch the same, so that
-	monotonicity can be better preserved.
-]]
-function External.bindToUpdateStep(
-	callback: (
-		now: number
-	) -> ()
-): () -> ()
-	local uniqueIdentifier = {}
-	updateStepCallbacks[uniqueIdentifier] = callback
-	return function()
-		updateStepCallbacks[uniqueIdentifier] = nil
-	end
-end
-
---[[
-	Steps time-dependent systems with the current number of seconds since an
-	arbitrary epoch. This should be called as early as possible in the external
-	provider's update cycle.
-]]
-function External.performUpdateStep(
-	now: number
-)
-	lastUpdateStep = now
-	for _, callback in updateStepCallbacks do
-		callback(now)
-	end
-end
-
---[[
-	Returns the timestamp of the last update step.
-]]
-function External.lastUpdateStep()
-	return lastUpdateStep
-end
-
-return External

package/runtime/Fusion/ExternalDebug.luau

@@ -1,70 +0,0 @@
---!strict
---!nolint LocalUnused
---!nolint LocalShadow
-local task = nil -- Disable usage of Roblox's task scheduler
-
---[[
-	Abstraction layer between Fusion internals and external debuggers, allowing
-	for deep introspection using function hooks.
-
-	Unlike `External`, attaching a debugger is optional, and all debugger
-	functions are expected to be infallible and non-blocking.
-]]
-
-local Package = script.Parent
-local Types = require(Package.Types)
-
-local currentProvider: Types.ExternalDebugger? = nil
-local lastUpdateStep = 0
-
-local Debugger = {}
-
---[[
-	Swaps to a new debugger.
-	Returns the old debugger, so it can be used again later.
-]]
-function Debugger.setDebugger(
-	newProvider: Types.ExternalDebugger?
-): Types.ExternalDebugger?
-	local oldProvider = currentProvider
-	if oldProvider ~= nil then
-		oldProvider.stopDebugging()
-	end
-	currentProvider = newProvider
-	if newProvider ~= nil then
-		newProvider.startDebugging()
-	end
-	return oldProvider
-end
-
---[[
-	Called at the earliest moment after a scope is created or removed from the
-	scope pool, but not before the scope has finished being prepared by the
-	library, so that debuggers can register its existence and track changes
-	to the scope over time.
-]]
-function Debugger.trackScope(
-	scope: Types.Scope<unknown>
-): ()
-	if currentProvider == nil then
-		return
-	end
-	currentProvider.trackScope(scope)
-end
-
---[[
-	Called at the final moment before a scope is poisoned or added to the scope
-	pool, after all cleanup tasks have completed, so that debuggers can erase 
-	the scope from internal trackers. Note that, due to scope pooling and user
-	code, never assume that this correlates with garbage collection events.
-]]
-function Debugger.untrackScope(
-	scope: Types.Scope<unknown>
-): ()
-	if currentProvider == nil then
-		return
-	end
-	currentProvider.trackScope(scope)
-end
-
-return Debugger

package/runtime/Fusion/Graph/Observer.luau

@@ -1,111 +0,0 @@
---!strict
---!nolint LocalUnused
---!nolint LocalShadow
-local task = nil -- Disable usage of Roblox's task scheduler
-
---[[
-	A graph object that runs user code when it's updated by the reactive graph.
-
-	http://elttob.uk/Fusion/0.3/api-reference/state/types/observer/
-]]
-
-local Package = script.Parent.Parent
-local Types = require(Package.Types)
-local External = require(Package.External)
--- Memory
-local checkLifetime = require(Package.Memory.checkLifetime)
--- Graph
-local castToGraph = require(Package.Graph.castToGraph)
-local depend = require(Package.Graph.depend)
-local evaluate = require(Package.Graph.evaluate)
--- Utility
-local nicknames = require(Package.Utility.nicknames)
-
-type Self = Types.Observer & {
-	_watchingGraph: Types.GraphObject?,
-	_changeListeners: {[unknown]: () -> ()}
-}
-
-local class = {}
-class.type = "Observer"
-class.timeliness = "eager"
-class.dependentSet = table.freeze {}
-
-local METATABLE = table.freeze {__index = class}
-
-local function Observer(
-	scope: Types.Scope<unknown>,
-	watching: unknown
-): Types.Observer
-	local createdAt = os.clock()
-
-	local self: Self = setmetatable(
-		{
-			scope = scope,
-			createdAt = createdAt,
-			dependencySet = {},
-			lastChange = nil,
-			validity = "invalid",
-			_watchingGraph = castToGraph(watching),
-			_changeListeners = {}
-		},
-		METATABLE
-	) :: any
-	local destroy = function()
-		self.scope = nil
-		for dependency in pairs(self.dependencySet) do
-			dependency.dependentSet[self] = nil
-		end
-	end
-	self.oldestTask = destroy
-	nicknames[self.oldestTask] = "Observer"
-	table.insert(scope, destroy)
-
-	if self._watchingGraph ~= nil then
-		checkLifetime.bOutlivesA(
-			scope, self.oldestTask,
-			self._watchingGraph.scope, self._watchingGraph.oldestTask,
-			checkLifetime.formatters.observer
-		)
-	end
-
-	-- Eagerly evaluated objects need to evaluate themselves so that they're
-	-- valid at all times.
-	evaluate(self, true)
-
-	return self
-end
-
-function class.onBind(
-	self: Self,
-	callback: () -> ()
-): () -> ()
-	External.doTaskImmediate(callback)
-	return self:onChange(callback)
-end
-
-function class.onChange(
-	self: Self,
-	callback: () -> ()
-): () -> ()
-	local uniqueIdentifier = table.freeze {}
-	self._changeListeners[uniqueIdentifier] = callback
-	return function()
-		self._changeListeners[uniqueIdentifier] = nil
-	end
-end
-
-function class._evaluate(
-	self: Self
-): ()
-	if self._watchingGraph ~= nil then
-		depend(self, self._watchingGraph)
-	end
-	for _, callback in self._changeListeners do
-		External.doTaskImmediate(callback)
-	end
-	return true
-end
-
-table.freeze(class)
-return Observer :: Types.ObserverConstructor

package/runtime/Fusion/Graph/castToGraph.luau

@@ -1,29 +0,0 @@
---!strict
---!nolint LocalUnused
---!nolint LocalShadow
-local task = nil -- Disable usage of Roblox's task scheduler
-
---[[
-	Returns the input *only* if it is a graph object.
-]]
-
-local Package = script.Parent.Parent
-local Types = require(Package.Types)
-
-local function castToGraph(
-	target: any
-): Types.GraphObject?
-	if 
-		typeof(target) == "table" and
-		typeof(target.validity) == "string" and
-		typeof(target.timeliness) == "string" and
-		typeof(target.dependencySet) == "table" and
-		typeof(target.dependentSet) == "table"
-	then
-		return target
-	else
-		return nil
-	end
-end
-
-return castToGraph

package/runtime/Fusion/Graph/change.luau

@@ -1,81 +0,0 @@
---!strict
---!nolint LocalUnused
---!nolint LocalShadow
-local task = nil -- Disable usage of Roblox's task scheduler
-
---[[
-	Prompts a graph object to re-evaluate its own value. If it meaningfully
-	changes, then dependents will have to re-evaluate their own values in the
-	future.
-
-	https://fluff.blog/2024/04/16/monotonic-painting.html
-]]
-
-local Package = script.Parent.Parent
-local Types = require(Package.Types)
-local External = require(Package.External)
-local evaluate = require(Package.Graph.evaluate)
-
--- How long should this function run before it's considered to be in an infinite
--- cycle and error out?
-local TERMINATION_TIME = 1
-
-local function change(
-	target: Types.GraphObject
-): ()
-	if target.validity == "busy" then
-		return External.logError("infiniteLoop")
-	end
-
-	local meaningfullyChanged = evaluate(target, true)
-	if not meaningfullyChanged then
-		return
-	end
-
-	local searchInNow: {Types.GraphObject} = {}
-	local searchInNext: {Types.GraphObject} = {}
-	local invalidateList: {Types.GraphObject} = {}
-
-	searchInNow[1] = target
-	local terminateBy = os.clock() + TERMINATION_TIME * External.safetyTimerMultiplier
-	repeat
-		if os.clock() > terminateBy then
-			return External.logError("infiniteLoop")
-		end
-		local done = true
-		for _, searchTarget in searchInNow do
-			for dependent in searchTarget.dependentSet do
-				if dependent.validity == "valid" then
-					done = false
-					table.insert(invalidateList, dependent)
-					table.insert(searchInNext, dependent)
-				elseif dependent.validity == "busy" then
-					return External.logError("infiniteLoop")
-				end
-			end
-		end
-		searchInNow, searchInNext = searchInNext, searchInNow
-		table.clear(searchInNext)
-	until done
-
-	local eagerList: {Types.GraphObject} = {}
-
-	for _, invalidateTarget in invalidateList do
-		invalidateTarget.validity = "invalid"
-		if invalidateTarget.timeliness == "eager" then
-			table.insert(eagerList, invalidateTarget)
-		end
-	end
-	-- If objects are not executed in order of creations, then dynamic graphs
-	-- may experience 'glitches' where nested graph objects see intermediate
-	-- values before being destroyed.
-	-- https://fluff.blog/2024/07/14/glitches-in-dynamic-reactive-graphs.html
-	table.sort(eagerList, function(a, b)
-		return a.createdAt < b.createdAt
-	end)
-	for _, eagerTarget in eagerList do
-		evaluate(eagerTarget, false)
-	end
-end
-
-return change

package/runtime/Fusion/Graph/depend.luau

@@ -1,33 +0,0 @@
---!strict
---!nolint LocalUnused
---!nolint LocalShadow
-local task = nil -- Disable usage of Roblox's task scheduler
-
---[[
-	Forms a dependency on a graph object.
-]]
-
-local Package = script.Parent.Parent
-local Types = require(Package.Types)
-local External = require(Package.External)
-local evaluate = require(Package.Graph.evaluate)
-local nameOf = require(Package.Utility.nameOf)
-
-local function depend<T>(
-	dependent: Types.GraphObject,
-	dependency: Types.GraphObject
-): ()
-	-- Ensure dependencies are evaluated and up-to-date
-	-- when they are depended on. Also, newly created objects
-	-- might not have any transitive dependencies captured yet,
-	-- so ensure that they're present.
-	evaluate(dependency, false)
-
-	if table.isfrozen(dependent.dependencySet) or table.isfrozen(dependency.dependentSet) then
-		External.logError("cannotDepend", nil, nameOf(dependent, "Dependent"), nameOf(dependency, "dependency"))
-	end
-	dependency.dependentSet[dependent] = true
-	dependent.dependencySet[dependency] = true
-end
-
-return depend

package/runtime/Fusion/Graph/evaluate.luau

@@ -1,56 +0,0 @@
---!strict
---!nolint LocalUnused
---!nolint LocalShadow
-local task = nil -- Disable usage of Roblox's task scheduler
-
---[[
-	Evaluates the graph object if necessary, so that it is up to date.
-	Returns true if it meaningfully changed.
-
-	https://fluff.blog/2024/04/16/monotonic-painting.html
-]]
-
-local Package = script.Parent.Parent
-local Types = require(Package.Types)
-local External = require(Package.External)
-
-local function evaluate(
-	target: Types.GraphObject,
-	forceComputation: boolean
-): boolean
-	if target.validity == "busy" then
-		return External.logError("infiniteLoop")
-	end
-	local firstEvaluation = target.lastChange == nil
-	local isInvalid = target.validity == "invalid"
-	if firstEvaluation or isInvalid or forceComputation then
-		local needsComputation = firstEvaluation or forceComputation
-		if not needsComputation then
-			for dependency in target.dependencySet do
-				evaluate(dependency, false)
-				if dependency.lastChange > target.lastChange then
-					needsComputation = true
-					break
-				end
-			end
-		end
-		local targetMeaningfullyChanged = false
-		if needsComputation then
-			for dependency in target.dependencySet do
-				dependency.dependentSet[target] = nil
-				target.dependencySet[dependency] = nil
-			end
-			target.validity = "busy"
-			targetMeaningfullyChanged = target:_evaluate() or firstEvaluation
-		end
-		if targetMeaningfullyChanged then
-			target.lastChange = os.clock()
-		end
-		target.validity = "valid"
-		return targetMeaningfullyChanged
-	else
-		return false
-	end
-end
-
-return evaluate