@rbxts/app-forge 0.7.1 → 0.7.2-alpha.2

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,18 @@
+export type DebugTag = "render" | "rules" | "state" | "px" | "lifecycle";
+type LogFn = (level: "DEBUG" | "PERF", message: string, data?: unknown, traceback?: string) => void;
+export default class Debugger {
+    private readonly log;
+    private timers;
+    private enabled;
+    private allEnabled;
+    constructor(log: LogFn);
+    enable(tag: DebugTag): void;
+    disable(tag: DebugTag): void;
+    enableAll(): void;
+    disableAll(): 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,89 @@
+-- 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.timers = {}
+		self.enabled = {}
+		self.allEnabled = false
+	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:enableAll()
+		self.allEnabled = true
+	end
+	function Debugger:disableAll()
+		self.allEnabled = false
+		table.clear(self.enabled)
+	end
+	function Debugger:isEnabled(tag)
+		local _condition = self.allEnabled
+		if not _condition then
+			local _enabled = self.enabled
+			local _tag = tag
+			_condition = _enabled[_tag] ~= nil
+		end
+		return _condition
+	end
+	function Debugger:logTag(tag, app, message, data)
+		if not RunService:IsStudio() then
+			return nil
+		end
+		if not self:isEnabled(tag) 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
+		if not self:isEnabled(tag) 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
+		if not self:isEnabled(tag) 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 };