@rbxts/app-forge 0.7.0 → 0.7.2-alpha.1

package/README.md

@@ -32,14 +32,34 @@ If you’ve ever ended up with tangled UI state, duplicated visibility logic, or
 
 ## 📦 Installation
 
+### Using **bun**
+
 ```bash
 bun add @rbxts/app-forge
 ```
 
-Peer dependencies:
+Peer dependencies (choose one renderer):
 
 ```bash
-bun add @rbxts/vide @rbxts/loners-pretty-vide-utils
+bun add @rbxts/vide
+# or
+bun add @rbxts/react
+```
+
+---
+
+### Using **npm**
+
+```bash
+npm install @rbxts/app-forge
+```
+
+Peer dependencies (choose one renderer):
+
+```bash
+npm install @rbxts/vide
+# or
+npm install @rbxts/react
 ```
 
 ---
@@ -127,9 +147,7 @@ forge.mount(
    ResetOnSpawn={false}
   />
  ),
- {
-  props,
- },
+ props,
  Players.LocalPlayer.WaitForChild("PlayerGui"),
 );
 ```
@@ -157,9 +175,7 @@ forge.mount(
    ResetOnSpawn={false}
   />
  ),
- {
-  props,
- },
+ props,
  Players.LocalPlayer.WaitForChild("PlayerGui"),
 );
 ```
@@ -177,9 +193,7 @@ This:
 ```ts
 forge.mount(
  () => <screengui ResetOnSpawn={false} />,
- {
-  props: {},
- },
+ props,
  playerGui,
 );
 ```
@@ -352,7 +366,6 @@ AppForge provides `forge.story` for **isolated rendering**, commonly used with *
 const forge = new CreateVideForge();
 
 return forge.story({
- forge,
  props,
  config: {
   px: {
@@ -430,7 +443,7 @@ AppForge
 
 ## ⚛️ React Support (Planned)
 
-AppForge is designed as a **renderer-agnostic App Manager**.
+AppForge is designed as a **renderer-agnostic App Manager**.b
 
 Currently:
 

package/out/react/hooks/usePx.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Scaled pixel unit helper.
+ */
+export declare const px: ((value: number) => number) & {
+    scale: (value: number) => number;
+    even: (value: number) => number;
+    floor: (value: number) => number;
+    ceil: (value: number) => number;
+};
+/**
+ * Initializes global px scaling.
+ *
+ * Should be called exactly once at app mount.
+ */
+export declare function usePx(target?: GuiObject | Camera, baseResolution?: Vector2, minScale?: number): void;

package/out/react/hooks/usePx.luau

@@ -0,0 +1,117 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+-- Services
+local Workspace = TS.import(script, TS.getModule(script, "@rbxts", "services")).Workspace
+-- React
+local useEffect = TS.import(script, TS.getModule(script, "@rbxts", "react")).useEffect
+--* Default reference resolution for px calculations 
+local BASE_RESOLUTION = Vector2.new(1920, 1080)
+--* Minimum allowed scale to prevent unreadable UI 
+local MIN_SCALE = 0.5
+--[[
+	*
+	 * Interpolates between width- and height-based scaling.
+	 * 0 = width-driven, 1 = height-driven
+	 
+]]
+local DOMINANT_AXIS = 0.5
+local TARGET = Workspace.CurrentCamera
+local SCALE = 1
+local GLOBAL_INITIALIZED = false
+--[[
+	*
+	 * Assigns a call signature to an object.
+	 
+]]
+local function callable(callback, object)
+	return setmetatable(object, {
+		__call = function(_, ...)
+			local args = { ... }
+			return callback(unpack(args))
+		end,
+	})
+end
+--[[
+	*
+	 * Scaled pixel unit helper.
+	 
+]]
+local px = callable(function(value)
+	return math.round(value * SCALE)
+end, {
+	scale = function(value)
+		return value * SCALE
+	end,
+	even = function(value)
+		return math.round(value * SCALE * 0.5) * 2
+	end,
+	floor = function(value)
+		return math.floor(value * SCALE)
+	end,
+	ceil = function(value)
+		return math.ceil(value * SCALE)
+	end,
+})
+--[[
+	*
+	 * Recalculates the current scale factor.
+	 
+]]
+local function calculateScale()
+	local target = TARGET
+	if not target then
+		return nil
+	end
+	local size = if target:IsA("Camera") then target.ViewportSize elseif target:IsA("GuiObject") then target.AbsoluteSize else nil
+	if not size then
+		return nil
+	end
+	if BASE_RESOLUTION.X <= 0 or BASE_RESOLUTION.Y <= 0 then
+		return nil
+	end
+	local width = math.log(size.X / BASE_RESOLUTION.X, 2)
+	local height = math.log(size.Y / BASE_RESOLUTION.Y, 2)
+	local centered = width + (height - width) * DOMINANT_AXIS
+	local scale = 2 ^ centered
+	SCALE = math.max(scale, MIN_SCALE)
+end
+--[[
+	*
+	 * Initializes global px scaling.
+	 *
+	 * Should be called exactly once at app mount.
+	 
+]]
+local function usePx(target, baseResolution, minScale)
+	useEffect(function()
+		if GLOBAL_INITIALIZED then
+			warn("usePx() may only be called once globally")
+			return nil
+		end
+		GLOBAL_INITIALIZED = true
+		if baseResolution then
+			BASE_RESOLUTION = baseResolution
+		end
+		if minScale ~= nil then
+			MIN_SCALE = minScale
+		end
+		if target then
+			TARGET = target
+		end
+		local resolvedTarget = TARGET
+		if not resolvedTarget then
+			warn("usePx(): no valid target to observe")
+			return nil
+		end
+		local signal = if resolvedTarget:IsA("Camera") then resolvedTarget:GetPropertyChangedSignal("ViewportSize") else resolvedTarget:GetPropertyChangedSignal("AbsoluteSize")
+		local connection = signal:Connect(calculateScale)
+		calculateScale()
+		return function()
+			connection:Disconnect()
+		end
+	end, {})
+end
+return {
+	usePx = usePx,
+	px = px,
+}

package/out/vide/classes/renders.d.ts

@@ -8,6 +8,10 @@ export default class Renders extends Rules {
         render: Vide.Node;
     }>;
     constructor();
+    /**
+     * Entry point for mounting renders.
+     * Decides render strategy based on props.
+     */
     protected renderMount(this: AppForge, props: Types.Props.Main): Vide.Node;
     private renderNames;
     private collectByGroup;

package/out/vide/classes/renders.luau

@@ -1,14 +1,14 @@
 -- Compiled with roblox-ts v3.0.0
 local TS = _G[script]
--- Services
 -- Packages
-local usePx = TS.import(script, TS.getModule(script, "@rbxts", "loners-pretty-vide-utils").out).usePx
 local _vide = TS.import(script, TS.getModule(script, "@rbxts", "vide").src)
 local apply = _vide.apply
 local create = _vide.create
 -- Types
 -- Components
 local AppRegistry = TS.import(script, script.Parent.Parent, "decorator").AppRegistry
+-- Hooks
+local usePx = TS.import(script, script.Parent.Parent, "hooks", "usePx").usePx
 -- Classes
 local Rules = TS.import(script, script.Parent, "rules").default
 local Renders
@@ -35,22 +35,28 @@ do
 		local render = _binding.render
 		local forge = _binding.forge
 		if not forge.__px then
+			local _debug = forge.debug
 			local _result = config
 			if _result ~= nil then
-				_result = _result.px.target
+				_result = _result.px
 			end
+			_debug:logTag("px", "global", "Initializing px scaling", _result)
 			local _result_1 = config
 			if _result_1 ~= nil then
-				_result_1 = _result_1.px.resolution
+				_result_1 = _result_1.px.target
 			end
 			local _result_2 = config
 			if _result_2 ~= nil then
-				_result_2 = _result_2.px.minScale
+				_result_2 = _result_2.px.resolution
 			end
-			usePx(_result, _result_1, _result_2)
+			local _result_3 = config
+			if _result_3 ~= nil then
+				_result_3 = _result_3.px.minScale
+			end
+			usePx(_result_1, _result_2, _result_3)
 			forge.__px = true
 		else
-			warn("Rendering twice making a second px")
+			forge.debug:logTag("px", "global", "Skipped duplicate px initialization")
 		end
 		if render then
 			local _condition = render.name
@@ -58,34 +64,35 @@ do
 				_condition = render.group
 			end
 			if _condition ~= "" and _condition then
+				forge.debug:logTag("render", "global", "Rendering group by name", render)
 				return forge:renderGroupByName(props)
-			else
-				local _value = render.names and render.group
-				if _value ~= "" and _value then
-					return forge:renderGroupByNames(props)
-				else
-					local _result = render
-					if _result ~= nil then
-						_result = _result.name
-					end
-					if _result ~= "" and _result then
-						return forge:renderApp(props)
-					elseif render.names then
-						return forge:renderApps(props)
-					else
-						local _value_1 = render.group
-						if _value_1 ~= "" and _value_1 then
-							return forge:renderGroup(props)
-						end
-					end
-				end
+			end
+			local _value = render.names and render.group
+			if _value ~= "" and _value then
+				forge.debug:logTag("render", "global", "Rendering group by names", render)
+				return forge:renderGroupByNames(props)
+			end
+			local _value_1 = render.name
+			if _value_1 ~= "" and _value_1 then
+				forge.debug:logTag("render", render.name, "Rendering single app")
+				return forge:renderApp(props)
+			end
+			if render.names then
+				forge.debug:logTag("render", "global", "Rendering multiple apps", render.names)
+				return forge:renderApps(props)
+			end
+			local _value_2 = render.group
+			if _value_2 ~= "" and _value_2 then
+				forge.debug:logTag("render", "global", "Rendering group", render.group)
+				return forge:renderGroup(props)
 			end
 		end
+		forge.debug:logTag("render", "global", "Rendering all apps")
 		return self:renderAll(props)
 	end
 	function Renders:renderNames(props, names, forge)
 		if #names == 0 then
-			error("No app names provided to renderApps")
+			error("No app names provided to render", 2)
 		end
 		-- ▼ ReadonlyArray.map ▼
 		local _newValue = table.create(#names)
@@ -141,22 +148,21 @@ do
 		return _result
 	end
 	function Renders:renderApp(props)
-		local _binding = props
-		local forge = _binding.forge
-		local render = _binding.render
-		local _name = render
+		local _name = props.render
 		if _name ~= nil then
 			_name = _name.name
 		end
 		local name = _name
 		if not (name ~= "" and name) then
-			error("App name is required to create instance")
+			error("renderApp requires an app name", 2)
 		end
 		local appClass = AppRegistry[name]
 		if not appClass then
-			error(`App "{name}" not registered`)
+			error(`App "{name}" not registered`, 2)
 		end
-		if not (forge.loaded[name] ~= nil) then
+		self.debug:time("render", name)
+		if not (self.loaded[name] ~= nil) then
+			self.debug:logTag("render", name, "Creating render instance")
 			local render = appClass.constructor.new(props, name):render()
 			apply(render)({
 				Name = "Render",
@@ -169,19 +175,18 @@ do
 				Size = UDim2.fromScale(1, 1),
 				[0] = render,
 			})
-			local _loaded = forge.loaded
+			local _loaded = self.loaded
 			local _arg1 = {
 				container = container,
 				render = render,
 			}
 			_loaded[name] = _arg1
-		end
-		local element = forge.loaded[name]
-		if not element then
-			error(`Failed to create instance for app "{name}"`)
+		else
+			self.debug:logTag("render", name, "Reusing existing render instance")
 		end
 		self:renderRules(name, props)
-		return element.container
+		self.debug:timeEnd("render", name)
+		return self.loaded[name].container
 	end
 	function Renders:renderApps(props)
 		local _names = props.render
@@ -190,7 +195,7 @@ do
 		end
 		local names = _names
 		if not names then
-			error("No app names provided")
+			error("renderApps requires app names", 2)
 		end
 		return self:renderNames(props, names, self)
 	end
@@ -201,7 +206,7 @@ do
 		end
 		local group = _group
 		if not (group ~= "" and group) then
-			error("No group provided")
+			error("renderGroup requires a group", 2)
 		end
 		local groups = self:normalizeGroups(group)
 		return self:renderNames(props, self:collectByGroup(groups), self)
@@ -211,7 +216,7 @@ do
 		local group = _binding.group
 		local name = _binding.name
 		if not (group ~= "" and group) or not (name ~= "" and name) then
-			error("Invalid renderGroupByName")
+			error("Invalid renderGroupByName call", 2)
 		end
 		local groups = self:normalizeGroups(group)
 		return self:renderNames(props, self:collectByGroup(groups, function(n)
@@ -223,7 +228,7 @@ do
 		local group = _binding.group
 		local names = _binding.names
 		if not (group ~= "" and group) or not names then
-			error("Invalid renderGroupByNames")
+			error("Invalid renderGroupByNames call", 2)
 		end
 		local groups = self:normalizeGroups(group)
 		return self:renderNames(props, self:collectByGroup(groups, function(n)

package/out/vide/classes/rules/exclusiveGroup.luau

@@ -6,36 +6,43 @@ local AppRegistry = TS.import(script, script.Parent.Parent.Parent, "decorator").
 local function ExclusiveGroupRule(entry, forge)
 	local _entry = entry
 	local entryApp = AppRegistry[_entry]
-	local _result = entryApp
-	if _result ~= nil then
-		_result = _result.rules
-		if _result ~= nil then
-			_result = _result.exclusiveGroup
+	local _group = entryApp
+	if _group ~= nil then
+		_group = _group.rules
+		if _group ~= nil then
+			_group = _group.exclusiveGroup
 		end
 	end
-	if not (_result ~= "" and _result) then
+	local group = _group
+	if not (group ~= "" and group) then
 		return nil
 	end
-	local group = entryApp.rules.exclusiveGroup
-	local entrySource = forge:getSource(entry)()
-	if not entrySource then
+	local entryVisible = forge:getSource(entry)()
+	if not entryVisible then
 		return nil
 	end
+	forge.debug:logTag("rules", entry, "Exclusive group activated", group)
 	-- ▼ ReadonlyMap.forEach ▼
 	local _callback = function(app, name)
 		if name == entry then
 			return nil
 		end
-		local _result_1 = app.rules
-		if _result_1 ~= nil then
-			_result_1 = _result_1.exclusiveGroup
+		local _result = app.rules
+		if _result ~= nil then
+			_result = _result.exclusiveGroup
 		end
-		if _result_1 ~= group then
+		if _result ~= group then
 			return nil
 		end
-		if forge:getSource(name)() then
-			forge:close(name, false)
+		local visible = forge:getSource(name)()
+		if not visible then
+			return nil
 		end
+		forge.debug:logTag("rules", entry, "Closing app due to exclusive group", {
+			closed = name,
+			group = group,
+		})
+		forge:close(name, false)
 	end
 	for _k, _v in AppRegistry do
 		_callback(_v, _k, AppRegistry)

package/out/vide/classes/rules/init.luau

@@ -25,36 +25,40 @@ do
 		local _name = name
 		local appClass = AppRegistry[_name]
 		if not appClass then
-			error(`Failed to get class for app: {name} for renderRules`)
+			error(`renderRules: App "{name}" not registered`, 2)
 		end
-		local _result = appClass.rules
-		if _result ~= nil then
-			_result = _result.parent
+		local rules = appClass.rules
+		if not rules then
+			return nil
 		end
-		local _condition = _result
+		-- Parent Anchor
+		local _condition = rules.parent
 		if _condition ~= "" and _condition then
-			_condition = not appClass.rules.detach
+			_condition = not rules.detach
 		end
 		if _condition ~= "" and _condition then
-			self:anchor(name, appClass.rules.parent, props)
-		end
-		local _result_1 = appClass.rules
-		if _result_1 ~= nil then
-			_result_1 = _result_1.index
+			self.debug:logTag("rules", name, "Applying parent anchor", {
+				parent = rules.parent,
+			})
+			self:anchor(name, rules.parent, props)
 		end
-		if _result_1 ~= 0 and _result_1 == _result_1 and _result_1 then
-			self:index(name, appClass.rules.index)
+		-- Index
+		if rules.index ~= nil then
+			self.debug:logTag("rules", name, "Applying ZIndex", rules.index)
+			self:index(name, rules.index)
 		end
 	end
 	function Rules:checkRules(name)
 		local _processing = self.processing
 		local _name = name
 		if _processing[_name] ~= nil then
+			self.debug:logTag("rules", name, "Skipped rule processing (cycle detected)")
 			return nil
 		end
 		local _processing_1 = self.processing
 		local _name_1 = name
 		_processing_1[_name_1] = true
+		self.debug:logTag("rules", name, "Evaluating rules")
 		TS.try(function()
 			ParentRule(name, self)
 			ExclusiveGroupRule(name, self)

package/out/vide/classes/rules/parent.luau

@@ -4,7 +4,7 @@ local TS = _G[script]
 -- Components
 local AppRegistry = TS.import(script, script.Parent.Parent.Parent, "decorator").AppRegistry
 local function ParentRule(entry, forge)
-	local entrySource = forge:getSource(entry)()
+	local entryVisible = forge:getSource(entry)()
 	-- ▼ ReadonlyMap.forEach ▼
 	local _callback = function(app, name)
 		local rules = app.rules
@@ -14,10 +14,14 @@ local function ParentRule(entry, forge)
 		if name == entry then
 			return nil
 		end
-		local childSource = forge:getSource(name)()
-		if not entrySource and childSource then
-			forge:close(name, false)
+		local childVisible = forge:getSource(name)()
+		if entryVisible or not childVisible then
+			return nil
 		end
+		forge.debug:logTag("rules", entry, "Closing child app (parent closed)", {
+			child = name,
+		})
+		forge:close(name, false)
 	end
 	for _k, _v in AppRegistry do
 		_callback(_v, _k, AppRegistry)

package/out/vide/context.d.ts

@@ -1,7 +1,7 @@
 declare const Contexts: {
     readonly App: import("@rbxts/vide").Context<{
         forge: import(".").default;
-        px: typeof import("@rbxts/loners-pretty-vide-utils").px;
+        px: typeof import("./hooks/usePx").px;
     } | undefined>;
 };
 export default Contexts;

package/out/vide/debug/debugger.d.ts

@@ -0,0 +1,15 @@
+export type DebugTag = string;
+type LogFn = (level: "DEBUG" | "PERF", message: string, data?: unknown, traceback?: string) => void;
+export default class Debugger {
+    private readonly log;
+    private enabled;
+    private timers;
+    constructor(log: LogFn);
+    enable(tag: DebugTag): void;
+    disable(tag: DebugTag): void;
+    isEnabled(tag: DebugTag): boolean;
+    logTag(tag: DebugTag, app: AppNames, message: string, data?: unknown): void;
+    time(tag: DebugTag, app: AppNames): void;
+    timeEnd(tag: DebugTag, app: AppNames): void;
+}
+export {};

package/out/vide/debug/debugger.luau

@@ -0,0 +1,83 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+-- Services
+local RunService = TS.import(script, TS.getModule(script, "@rbxts", "services")).RunService
+local Debugger
+do
+	Debugger = setmetatable({}, {
+		__tostring = function()
+			return "Debugger"
+		end,
+	})
+	Debugger.__index = Debugger
+	function Debugger.new(...)
+		local self = setmetatable({}, Debugger)
+		return self:constructor(...) or self
+	end
+	function Debugger:constructor(log)
+		self.log = log
+		self.enabled = {}
+		self.timers = {}
+	end
+	function Debugger:enable(tag)
+		local _enabled = self.enabled
+		local _tag = tag
+		_enabled[_tag] = true
+	end
+	function Debugger:disable(tag)
+		local _enabled = self.enabled
+		local _tag = tag
+		_enabled[_tag] = nil
+	end
+	function Debugger:isEnabled(tag)
+		local _enabled = self.enabled
+		local _tag = tag
+		return _enabled[_tag] ~= nil
+	end
+	function Debugger:logTag(tag, app, message, data)
+		if not RunService:IsStudio() then
+			return nil
+		end
+		local _enabled = self.enabled
+		local _tag = tag
+		if not (_enabled[_tag] ~= nil) then
+			return nil
+		end
+		self.log("DEBUG", `[{tag}][{app}] {message}`, data, debug.traceback(nil, 3))
+	end
+	function Debugger:time(tag, app)
+		if not RunService:IsStudio() then
+			return nil
+		end
+		local _enabled = self.enabled
+		local _tag = tag
+		if not (_enabled[_tag] ~= nil) then
+			return nil
+		end
+		local _timers = self.timers
+		local _arg0 = `{tag}:{app}`
+		local _arg1 = os.clock()
+		_timers[_arg0] = _arg1
+	end
+	function Debugger:timeEnd(tag, app)
+		if not RunService:IsStudio() then
+			return nil
+		end
+		local _enabled = self.enabled
+		local _tag = tag
+		if not (_enabled[_tag] ~= nil) then
+			return nil
+		end
+		local key = `{tag}:{app}`
+		local start = self.timers[key]
+		if start == nil then
+			return nil
+		end
+		self.timers[key] = nil
+		local elapsed = os.clock() - start
+		self.log("PERF", `[{tag}][{app}] {string.format("%.3fms", elapsed * 1000)}`)
+	end
+end
+return {
+	default = Debugger,
+}

package/out/vide/debug/index.d.ts

@@ -0,0 +1,3 @@
+import Debugger from "./debugger";
+import Logger from "./logger";
+export { Debugger, Logger };

package/out/vide/debug/init.luau

@@ -0,0 +1,8 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local Debugger = TS.import(script, script, "debugger").default
+local Logger = TS.import(script, script, "logger").default
+return {
+	Debugger = Debugger,
+	Logger = Logger,
+}

package/out/vide/debug/logger.d.ts

@@ -0,0 +1,5 @@
+export default class Logger {
+    private readonly scope;
+    constructor(scope: string);
+    log(level: "DEBUG" | "PERF" | "INFO" | "WARN" | "ERROR", message: string, data?: unknown, traceback?: string): void;
+}

package/out/vide/debug/logger.luau

@@ -0,0 +1,37 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+-- debug/logger.ts
+local RunService = TS.import(script, TS.getModule(script, "@rbxts", "services")).RunService
+local Logger
+do
+	Logger = setmetatable({}, {
+		__tostring = function()
+			return "Logger"
+		end,
+	})
+	Logger.__index = Logger
+	function Logger.new(...)
+		local self = setmetatable({}, Logger)
+		return self:constructor(...) or self
+	end
+	function Logger:constructor(scope)
+		self.scope = scope
+	end
+	function Logger:log(level, message, data, traceback)
+		if not RunService:IsStudio() then
+			return nil
+		end
+		local prefix = `[{self.scope}][{level}]`
+		if data ~= nil then
+			print(prefix, message, data)
+		else
+			print(prefix, message)
+		end
+		if traceback ~= "" and traceback then
+			print(traceback)
+		end
+	end
+end
+return {
+	default = Logger,
+}

package/out/vide/decorator.d.ts

@@ -2,7 +2,15 @@ import Vide from "@rbxts/vide";
 import type Types from "./types";
 import type AppForge from ".";
 export declare const AppRegistry: Map<string, Types.AppRegistry.Static>;
+/**
+ * Registers a Vide App with AppForge.
+ *
+ * This runs at definition time and validates static configuration.
+ */
 export declare function App<N extends AppNames>(props: Types.AppRegistry.Props<N>): <T extends new (props: Types.Props.Main, name: AppNames) => Args>(constructor: T) => T;
+/**
+ * Base class for all AppForge Apps.
+ */
 export declare abstract class Args {
     readonly forge: AppForge;
     readonly props: Types.Props.Class;

package/out/vide/decorator.luau

@@ -1,15 +1,40 @@
 -- Compiled with roblox-ts v3.0.0
 local TS = _G[script]
 -- Packages
-local px = TS.import(script, TS.getModule(script, "@rbxts", "loners-pretty-vide-utils").out).px
 -- Types
+-- Hooks
+local px = TS.import(script, script.Parent, "hooks", "usePx").px
+-- Debug
+local Logger = TS.import(script, script.Parent, "debug", "logger").default
+local logger = Logger.new("AppRegistry")
 local AppRegistry = {}
+--[[
+	*
+	 * Registers a Vide App with AppForge.
+	 *
+	 * This runs at definition time and validates static configuration.
+	 
+]]
 local function App(props)
 	return function(constructor)
 		local _name = props.name
 		if AppRegistry[_name] ~= nil then
-			error(`Duplicate registered App name "{props.name}"`)
+			logger:log("ERROR", "Duplicate App name detected", {
+				name = props.name,
+			})
+			error(`Duplicate registered App name "{props.name}". ` .. `App names must be globally unique.`, 2)
 		end
+		local _value = props.name
+		if not (_value ~= "" and _value) then
+			logger:log("ERROR", "Attempted to register App without a name", props)
+			error("App registration failed: missing app name", 2)
+		end
+		logger:log("DEBUG", "Registering App", {
+			name = props.name,
+			renderGroup = props.renderGroup,
+			visible = props.visible,
+			rules = props.rules,
+		})
 		local _name_1 = props.name
 		local _arg1 = {
 			constructor = constructor,
@@ -21,6 +46,11 @@ local function App(props)
 		return constructor
 	end
 end
+--[[
+	*
+	 * Base class for all AppForge Apps.
+	 
+]]
 local Args
 do
 	Args = {}
@@ -28,13 +58,20 @@ do
 		local _binding = props
 		local forge = _binding.forge
 		self.forge = forge
+		self.name = name
 		local _object = table.clone(props.props)
 		setmetatable(_object, nil)
 		_object.px = px
 		_object.forge = forge
 		self.props = _object
-		self.name = name
-		self.source = forge:getSource(name)
+		local src = forge:getSource(name)
+		if not src then
+			logger:log("ERROR", "Missing visibility source for App", {
+				name = name,
+			})
+			error(`Failed to retrieve visibility source for app "{name}"`, 2)
+		end
+		self.source = src
 	end
 end
 return {

package/out/vide/hooks/useAppContext.d.ts

@@ -1,5 +1,5 @@
 declare const _default: () => {
     forge: import("..").default;
-    px: typeof import("@rbxts/loners-pretty-vide-utils").px;
+    px: typeof import("./usePx").px;
 };
 export default _default;

package/out/vide/hooks/useAppContext.luau

@@ -2,10 +2,14 @@
 local TS = _G[script]
 -- Components
 local Contexts = TS.import(script, script.Parent.Parent, "context").default
+-- Debug
+local Logger = TS.import(script, script.Parent.Parent, "debug", "logger").default
+local logger = Logger.new("useAppContext")
 local default = function()
 	local context = Contexts.App()
 	if not context then
-		error(`Failed to retrieve App Props for Vide {debug.traceback()}`)
+		logger:log("ERROR", "Failed to retrieve App context")
+		error(`Failed to retrieve App Props for Vide\n{debug.traceback()}`, 2)
 	end
 	return context
 end

package/out/vide/hooks/useEventListener.d.ts

@@ -0,0 +1,17 @@
+type EventLike<T extends Callback = Callback> = {
+    Connect(callback: T): ConnectionLike;
+} | {
+    connect(callback: T): ConnectionLike;
+} | {
+    subscribe(callback: T): ConnectionLike;
+};
+type ConnectionLike = {
+    Disconnect(): void;
+} | {
+    disconnect(): void;
+} | (() => void);
+/**
+ * Subscribes to an event-like object and auto-cleans up.
+ */
+export declare function useEventListener<T extends EventLike>(event: T, listener: T extends EventLike<infer U> ? U : never): ReturnType<T>;
+export {};

package/out/vide/hooks/useEventListener.luau

@@ -0,0 +1,61 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local cleanup = TS.import(script, TS.getModule(script, "@rbxts", "vide").src).cleanup
+-- Debug
+local Logger = TS.import(script, script.Parent.Parent, "debug", "logger").default
+local logger = Logger.new("useEventListener")
+local connect = function(event, callback)
+	local _event = event
+	if typeof(_event) == "RBXScriptSignal" then
+		local connection
+		connection = event:Connect(function(...)
+			local args = { ... }
+			if connection.Connected then
+				return callback(unpack(args))
+			end
+		end)
+		return connection
+	elseif event.Connect ~= nil then
+		return event:Connect(callback)
+	elseif event.connect ~= nil then
+		return event:connect(callback)
+	elseif event.subscribe ~= nil then
+		return event:subscribe(callback)
+	end
+	logger:log("ERROR", "Unsupported event-like object", event)
+	error("Event-like object does not have a supported connect method.", 2)
+end
+local disconnect = function(connection)
+	local _connection = connection
+	if type(_connection) == "function" then
+		connection()
+	else
+		local _connection_1 = connection
+		local _condition = typeof(_connection_1) == "RBXScriptConnection"
+		if not _condition then
+			_condition = connection.Disconnect ~= nil
+		end
+		if _condition then
+			connection:Disconnect()
+		elseif connection.disconnect ~= nil then
+			connection:disconnect()
+		else
+			logger:log("WARN", "Unsupported connection-like object during cleanup", connection)
+		end
+	end
+end
+--[[
+	*
+	 * Subscribes to an event-like object and auto-cleans up.
+	 
+]]
+local function useEventListener(event, listener)
+	local connection = connect(event, listener)
+	cleanup(function()
+		return disconnect(connection)
+	end)
+	return connection
+end
+return {
+	useEventListener = useEventListener,
+}

package/out/vide/hooks/usePx.d.ts

@@ -0,0 +1,11 @@
+export declare const px: ((value: number) => number) & {
+    scale: (value: number) => number;
+    even: (value: number) => number;
+    floor: (value: number) => number;
+    ceil: (value: number) => number;
+};
+/**
+ * Initializes global px scaling.
+ * Must be called exactly once.
+ */
+export declare function usePx(target?: GuiObject | Camera, baseResolution?: Vector2, minScale?: number): void;

package/out/vide/hooks/usePx.luau

@@ -0,0 +1,103 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+-- Services
+local Workspace = TS.import(script, TS.getModule(script, "@rbxts", "services")).Workspace
+-- Packages
+local source = TS.import(script, TS.getModule(script, "@rbxts", "vide").src).source
+-- Helpers
+local useEventListener = TS.import(script, script.Parent, "useEventListener").useEventListener
+-- Debug
+local Logger = TS.import(script, script.Parent.Parent, "debug", "logger").default
+local logger = Logger.new("usePx")
+--* Default reference resolution for px calculations 
+local BASE_RESOLUTION = source(Vector2.new(1920, 1080))
+--* Minimum allowed scale to prevent unreadable UI 
+local MIN_SCALE = source(0.5)
+--* 0 = width-based, 1 = height-based 
+local DOMINANT_AXIS = 0.5
+local TARGET = source(Workspace.CurrentCamera)
+local SCALE = source(1)
+local INITIALIZED = false
+local function callable(callback, object)
+	return setmetatable(object, {
+		__call = function(_, ...)
+			local args = { ... }
+			return callback(unpack(args))
+		end,
+	})
+end
+local px = callable(function(value)
+	return math.round(value * SCALE())
+end, {
+	scale = function(value)
+		return value * SCALE()
+	end,
+	even = function(value)
+		return math.round(value * SCALE() * 0.5) * 2
+	end,
+	floor = function(value)
+		return math.floor(value * SCALE())
+	end,
+	ceil = function(value)
+		return math.ceil(value * SCALE())
+	end,
+})
+local function calculateScale()
+	local target = TARGET()
+	if not target then
+		return nil
+	end
+	local size = if target:IsA("Camera") then target.ViewportSize elseif target:IsA("GuiObject") then target.AbsoluteSize else nil
+	if not size then
+		return nil
+	end
+	local res = BASE_RESOLUTION()
+	if res.X <= 0 or res.Y <= 0 then
+		return nil
+	end
+	local min = MIN_SCALE()
+	local width = math.log(size.X / res.X, 2)
+	local height = math.log(size.Y / res.Y, 2)
+	local centered = width + (height - width) * DOMINANT_AXIS
+	local scale = 2 ^ centered
+	SCALE(math.max(scale, min))
+end
+--[[
+	*
+	 * Initializes global px scaling.
+	 * Must be called exactly once.
+	 
+]]
+local function usePx(target, baseResolution, minScale)
+	if INITIALIZED then
+		logger:log("WARN", "usePx() called more than once")
+		return nil
+	end
+	INITIALIZED = true
+	logger:log("DEBUG", "Initializing px scaling", {
+		target = target,
+		baseResolution = baseResolution,
+		minScale = minScale,
+	})
+	if baseResolution then
+		BASE_RESOLUTION(baseResolution)
+	end
+	if minScale ~= nil then
+		MIN_SCALE(minScale)
+	end
+	if target then
+		TARGET(target)
+	end
+	local resolvedTarget = TARGET()
+	if not resolvedTarget then
+		logger:log("WARN", "usePx(): no valid target to observe")
+		return nil
+	end
+	local signal = if resolvedTarget:IsA("Camera") then resolvedTarget:GetPropertyChangedSignal("ViewportSize") else resolvedTarget:GetPropertyChangedSignal("AbsoluteSize")
+	useEventListener(signal, calculateScale)
+	calculateScale()
+end
+return {
+	usePx = usePx,
+	px = px,
+}

package/out/vide/index.d.ts

@@ -1,6 +1,7 @@
 import Vide from "@rbxts/vide";
 import Renders from "./classes/renders";
 import Types from "./types";
+import { Logger, Debugger } from "./debug";
 type Destructor = () => void;
 type Loaded = {
     container: Vide.Node;
@@ -8,17 +9,19 @@ type Loaded = {
     anchor?: Vide.Node;
 };
 export default class AppForge extends Renders {
+    readonly logger: Logger;
+    readonly debug: Debugger;
     protected sources: Map<string, Vide.Source<boolean>>;
     protected loaded: Map<string, Loaded>;
     protected innerMount?: Destructor;
     protected __px: boolean;
     constructor();
-    protected createSource(name: AppNames): typeof Vide.source | undefined;
+    protected createSource(name: AppNames): void;
+    getSource(name: AppNames): Vide.Source<boolean>;
     isLoaded(name: AppNames): boolean;
     bind(name: AppNames, value: Vide.Source<boolean>): void;
     anchor(name: AppNames, anchorName: AppNames, props: Types.Props.Main): void;
     index(name: AppNames, index: number): void;
-    getSource(name: AppNames): Vide.Source<boolean>;
     set(name: AppNames, value: boolean, rules?: boolean): void;
     open(name: AppNames, rules?: boolean): void;
     close(name: AppNames, rules?: boolean): void;

package/out/vide/init.luau

@@ -14,6 +14,10 @@ local untrack = _vide.untrack
 local Renders = TS.import(script, script, "classes", "renders").default
 -- Helpers
 local AppRegistry = TS.import(script, script, "decorator").AppRegistry
+-- Debug
+local _debug = TS.import(script, script, "debug")
+local Logger = _debug.Logger
+local Debugger = _debug.Debugger
 local AppForge
 do
 	local super = Renders
@@ -30,6 +34,10 @@ do
 	end
 	function AppForge:constructor()
 		super.constructor(self)
+		self.logger = Logger.new("AppForge")
+		self.debug = Debugger.new(function(level, msg, data, trace)
+			return self.logger:log(level, msg, data, trace)
+		end)
 		self.sources = {}
 		self.loaded = {}
 		self.__px = false
@@ -46,22 +54,48 @@ do
 		local _name = name
 		local app = AppRegistry[_name]
 		if not app then
-			error(`App "{name}" not registered`)
+			self.logger:log("ERROR", "App not registered while creating source", {
+				name = name,
+			})
+			return nil
 		end
 		local _sources = self.sources
 		local _name_1 = name
 		if _sources[_name_1] ~= nil then
 			return nil
 		end
-		local _sources_1 = self.sources
+		local _debug_1 = self.debug
 		local _exp = name
+		local _object = {}
+		local _left = "default"
 		local _condition = app.visible
 		if _condition == nil then
 			_condition = false
 		end
-		local _arg1 = source(_condition)
-		_sources_1[_exp] = _arg1
-		return source
+		_object[_left] = _condition
+		_debug_1:logTag("state", _exp, "Creating visibility source", _object)
+		local _sources_1 = self.sources
+		local _exp_1 = name
+		local _condition_1 = app.visible
+		if _condition_1 == nil then
+			_condition_1 = false
+		end
+		local _arg1 = source(_condition_1)
+		_sources_1[_exp_1] = _arg1
+	end
+	function AppForge:getSource(name)
+		local _sources = self.sources
+		local _name = name
+		if not (_sources[_name] ~= nil) then
+			self:createSource(name)
+		end
+		local _sources_1 = self.sources
+		local _name_1 = name
+		local src = _sources_1[_name_1]
+		if not src then
+			error(`AppForge invariant broken: missing visibility source for {name}`, 2)
+		end
+		return src
 	end
 	function AppForge:isLoaded(name)
 		local _loaded = self.loaded
@@ -70,6 +104,7 @@ do
 	end
 	function AppForge:bind(name, value)
 		if not RunService:IsRunning() then
+			self.debug:logTag("state", name, "Binding external visibility source")
 			local _sources = self.sources
 			local _name = name
 			local _value = value
@@ -81,17 +116,26 @@ do
 				end)
 			end)
 		else
-			warn("forge.bind is used for studio when game isnt running")
+			self.logger:log("WARN", "forge.bind called while game is running", {
+				name = name,
+			})
 		end
 	end
 	function AppForge:anchor(name, anchorName, props)
 		if name == anchorName then
-			error(`Tried to anchor an App to itself`)
+			self.logger:log("ERROR", "Attempted to anchor app to itself", {
+				name = name,
+			})
+			return nil
 		end
 		local _anchorName = anchorName
 		local anchorApp = AppRegistry[_anchorName]
 		if not anchorApp then
-			error(`Failed to get class for {anchorName} from AppRegistry for anchor`)
+			self.logger:log("ERROR", "Anchor parent not registered", {
+				child = name,
+				parent = anchorName,
+			})
+			return nil
 		end
 		local _loaded = self.loaded
 		local _name = name
@@ -101,11 +145,17 @@ do
 		end
 		local render = _render
 		if not render then
-			error(`Failed to get {name} from this.loaded for anchor to {anchorName}`)
+			self.debug:logTag("rules", name, "Anchor skipped (child not rendered yet)", {
+				parent = anchorName,
+			})
+			return nil
 		end
+		self.debug:logTag("rules", name, "Anchoring to parent", {
+			parent = anchorName,
+		})
 		local anchor = anchorApp.constructor.new(props, anchorName):render()
-		for _, children in anchor:GetDescendants() do
-			children:Destroy()
+		for _, child in anchor:GetDescendants() do
+			child:Destroy()
 		end
 		apply(anchor)({
 			Name = "Anchor",
@@ -116,7 +166,7 @@ do
 		local _name_1 = name
 		local prev = _loaded_1[_name_1]
 		if not prev then
-			error(`Failed to retreive prev loaded data for {name}`)
+			error(`AppForge invariant broken: missing loaded app for {name}`, 2)
 		end
 		apply(prev.container)({
 			[0] = anchor,
@@ -133,22 +183,19 @@ do
 		local _name = name
 		local loaded = _loaded[_name]
 		if not loaded then
-			error(`Failed to retreive loaded data for app: {name}`)
+			self.logger:log("WARN", "ZIndex skipped (app not loaded)", {
+				name = name,
+				index = index,
+			})
+			return nil
 		end
+		self.debug:logTag("rules", name, "Applying ZIndex", {
+			index = index,
+		})
 		apply(loaded.container)({
 			ZIndex = index,
 		})
 	end
-	function AppForge:getSource(name)
-		local _sources = self.sources
-		local _name = name
-		if not (_sources[_name] ~= nil) then
-			self:createSource(name)
-		end
-		local _sources_1 = self.sources
-		local _name_1 = name
-		return _sources_1[_name_1]
-	end
 	function AppForge:set(name, value, rules)
 		if rules == nil then
 			rules = true
@@ -162,10 +209,21 @@ do
 			local _name_1 = name
 			src = _sources_1[_name_1]
 		end
-		if src() == value then
+		if not src then
+			self.logger:log("ERROR", "Failed to set visibility (missing source)", {
+				name = name,
+			})
+			return nil
+		end
+		local prev = src()
+		if prev == value then
 			return nil
 		end
 		src(value)
+		self.debug:logTag("state", name, "Visibility changed", {
+			from = prev,
+			to = value,
+		})
 		if rules then
 			self:checkRules(name)
 		end
@@ -189,6 +247,7 @@ do
 		self:set(name, not self:getSource(name)(), rules)
 	end
 	function AppForge:story(props)
+		self.debug:logTag("lifecycle", "story", "Creating story mount")
 		local Container = create("Frame")({
 			Name = "Story Container",
 			BackgroundTransparency = 1,
@@ -202,6 +261,7 @@ do
 		return Container
 	end
 	function AppForge:mount(callback, props, target)
+		self.debug:logTag("lifecycle", "mount", "Mounting AppForge")
 		local Container = callback()
 		self.innerMount = mount(function()
 			apply(Container)({
@@ -212,6 +272,7 @@ do
 		return self.innerMount
 	end
 	function AppForge:unMount()
+		self.debug:logTag("lifecycle", "unmount", "Unmounting AppForge")
 		local _result = self.innerMount
 		if _result ~= nil then
 			_result()

package/out/vide/types.d.ts

@@ -26,7 +26,7 @@ declare namespace Types {
 
 		type Class = AppProps & {
 			forge: AppForge;
-			px: typeof import("@rbxts/loners-pretty-vide-utils").px;
+			px: typeof import("./hooks/usePx").px;
 		};
 	}
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rbxts/app-forge",
-	"version": "0.7.0",
+	"version": "0.7.2-alpha.1",
 	"description": "An App Manager for Vide",
 	"main": "out/init.lua",
 	"types": "out/index.d.ts",
@@ -38,11 +38,17 @@
 		"@rbxts/set-timeout": "^1.1.2"
 	},
 	"peerDependencies": {
-		"@rbxts/loners-pretty-react-hooks": "^0.2.9",
-		"@rbxts/loners-pretty-vide-utils": "^0.1.7",
 		"@rbxts/react": "^17.3.7-ts.1",
 		"@rbxts/vide": "^0.5.7"
 	},
+	"peerDependenciesMeta": {
+		"@rbxts/react": {
+			"optional": true
+		},
+		"@rbxts/vide": {
+			"optional": true
+		}
+	},
 	"devDependencies": {
 		"@biomejs/biome": "^2.3.7",
 		"@rbxts/compiler-types": "3.0.0-types.0",