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

package/README.md

@@ -26,6 +26,7 @@ If you’ve ever ended up with tangled UI state, duplicated visibility logic, or
 * **px scaling** built-in via `loners-pretty-vide-utils`
 * **Vide context integration**
 * **Story / sandbox rendering**
+* **Built-in debug logger & performance tracing**
 * Fully typed with **roblox-ts**
 
 ---
@@ -86,6 +87,7 @@ Apps are registered using a decorator and rendered through `AppForge`.
 * mounts and unmounts UI
 * enforces rules
 * exposes imperative helpers (`open`, `close`, `toggle`)
+* owns the **debugger & logger** instance
 
 You usually create **one Forge per UI root**.
 
@@ -134,8 +136,6 @@ const forge = new CreateVideForge();
 
 ### Mounting (Game Runtime)
 
-AppForge is mounted once from application bootstrap code (commonly a Flamework controller).
-
 ```ts
 const forge = new CreateVideForge();
 
@@ -152,52 +152,6 @@ forge.mount(
 );
 ```
 
-Notes:
-
-* `forge` is **implicitly available** to Apps
-* `props` are user-defined and become `this.props` inside Apps
-* visibility & rules are controlled entirely by the Forge
-
----
-
-### Mounting (Game Runtime)
-
-AppForge is typically mounted from a **controller** (e.g. Flamework) and targets `PlayerGui`.
-
-```ts
-const forge = new CreateVideForge();
-
-forge.mount(
- () => (
-  <screengui
-   Name="App"
-   ZIndexBehavior="Sibling"
-   ResetOnSpawn={false}
-  />
- ),
- props,
- Players.LocalPlayer.WaitForChild("PlayerGui"),
-);
-```
-
-This:
-
-* creates a single root `ScreenGui`
-* mounts all rendered apps under it
-* keeps AppForge in control of visibility & rules
-
----
-
-### Mounting
-
-```ts
-forge.mount(
- () => <screengui ResetOnSpawn={false} />,
- props,
- playerGui,
-);
-```
-
 ---
 
 ### Opening & Closing Apps
@@ -208,20 +162,11 @@ forge.close("Inventory");
 forge.toggle("Inventory");
 ```
 
-You can also access the reactive source directly:
-
-```ts
-const visible = forge.getSource("Inventory");
-```
-
 ---
 
 ## 🧱 Defining an App
 
 ```ts
-import { VideApp, VideArgs } from "@rbxts/app-forge";
-import Vide from "@rbxts/vide";
-
 @VideApp({
  name: "Inventory",
  renderGroup: "Lobby",
@@ -246,165 +191,71 @@ export class Inventory extends VideArgs {
 
 ---
 
-## 🔗 Parent / Child Apps
-
-```ts
-@VideApp({
- name: "InventoryInfo",
- renderGroup: "Lobby",
- rules: {
-  parent: "Inventory",
- },
-})
-export class InventoryInfo extends VideArgs {
- render() {
-  return <frame />;
- }
-}
-```
-
-Behavior:
-
-* When `Inventory` closes → `InventoryInfo` closes
-* Child is **anchored** to parent unless `detach: true`
-
-```ts
-rules: {
- parent: "Inventory",
- detach: true,
-}
-```
-
----
-
-## 🚦 Exclusive Groups
-
-```ts
-@VideApp({
- name: "Settings",
- rules: {
-  exclusiveGroup: "Menus",
- },
-})
-```
+## 🐞 Debugging & Logging
 
-Only one app in the same `exclusiveGroup` may be open at a time.
+AppForge includes a **built-in debugger** designed for Studio-only diagnostics.
 
----
+### Debug Tags
 
-## 🎭 Render Control
-
-AppForge supports **multiple render selection modes**. You can render by:
-
-* a single app name
-* multiple app names
-* one or more render groups
-* combinations of `group + name(s)`
-
-All render options are passed via `VideRenderProps`.
-
----
-
-### Render a single app
+Debug output is grouped by **typed tags**:
 
 ```ts
-render: { name: "Inventory" }
+type DebugTag =
+ | "render"
+ | "rules"
+ | "state"
+ | "px"
+ | "lifecycle";
 ```
 
----
-
-### Render multiple apps
-
-```ts
-render: { names: ["Inventory", "InventoryInfo"] }
-```
+Each subsystem logs under its respective tag.
 
 ---
 
-### Render by group
+### Enabling Debug Tags
 
 ```ts
-render: { group: "Lobby" }
+forge.debug.enable("render");
+forge.debug.enable("rules");
 ```
 
----
-
-### Render by group + name
+Enable everything at once:
 
 ```ts
-render: {
- group: "Lobby",
- name: "Inventory",
-}
+forge.debug.enableAll();
 ```
 
-Only renders `Inventory` **if** it belongs to the `Lobby` group.
-
----
-
-### Render by group + names
+Disable:
 
 ```ts
-render: {
- group: "Lobby",
- names: ["Inventory", "Settings"],
-}
+forge.debug.disable("render");
 ```
 
-Only renders apps that:
-
-* are in the specified group(s)
-* and whose names match the provided list
+Debug logging only runs in **Roblox Studio**.
 
 ---
 
-## 🧪 Story / Sandbox Rendering
+### Performance Tracing
 
-AppForge provides `forge.story` for **isolated rendering**, commonly used with **UI Labs**.
+Certain systems emit **timing logs** when enabled:
 
 ```ts
-const forge = new CreateVideForge();
-
-return forge.story({
- props,
- config: {
-  px: {
-   target: storyProps.target,
-  },
- },
- render: { group: "Lobby" },
-});
+forge.debug.enable("render");
 ```
 
-This is ideal for:
+Output example:
 
-* component stories
-* previews
-* controlled visibility via bindings
+```
+[PERF][render][Inventory] 1.243ms
+```
 
 ---
 
-## 🧠 Context Access Inside Apps
+### Static Registration Logs
 
-App props are provided via Vide context.
+App registration (decorators) run **before a Forge exists**.
 
-```ts
-import { Provider } from "@rbxts/vide";
-import { VideContexts } from "@rbxts/app-forge";
-
-<Provider context={VideContexts.App} value={this.props}>
- {() => <Child />}
-</Provider>
-```
-
-Or via hook:
-
-````ts
-```ts
-import { useVideAppContext } from "@rbxts/app-forge";
-
-const app = useVideAppContext();
-````
+These use an internal **static logger** and will still emit warnings and errors during Studio load (e.g. duplicate app names).
 
 ---
 
@@ -418,6 +269,7 @@ AppForge
  ├─ Rule Engine
  │   ├─ Parent Rule
  │   └─ Exclusive Group Rule
+ ├─ Debugger / Logger
  └─ Vide Mount
 ```
 
@@ -428,6 +280,7 @@ AppForge
 * Apps are **singletons per Forge**
 * Rendering twice will warn if px is re‑initialized
 * Rules are enforced **reactively**
+* Debug logging is **Studio-only**
 * This package is currently **alpha** — APIs may change
 
 ---
@@ -443,27 +296,17 @@ AppForge
 
 ## ⚛️ React Support (Planned)
 
-AppForge is designed as a **renderer-agnostic App Manager**.b
+AppForge is designed as a **renderer-agnostic App Manager**.
 
 Currently:
 
 * ✅ **Vide renderer** is production-ready
 * 🚧 **React renderer** exists but is **very early / experimental**
 
-React support is intentionally paused while the Vide API stabilizes. The author is still learning React, and decided to refocus on Vide first. React will be revisited once the core architecture is fully locked in.
-
-Public surface (subject to change):
-
-```ts
-import { ReactApp, ReactArgs, CreateReactForge } from "@rbxts/app-forge";
-```
-
-**Vide is the recommended and supported path today.**
+Vide is the recommended and supported path today.
 
 ---
 
 ## 📜 License
 
 MIT
-
----

package/out/{vide/classes → classes}/renders.d.ts

@@ -1,6 +1,6 @@
 import Vide from "@rbxts/vide";
 import type Types from "../types";
-import type AppForge from "..";
+import type AppForge from "../main";
 import Rules from "./rules";
 export default class Renders extends Rules {
     protected anchored: Map<string, {
@@ -12,7 +12,9 @@ export default class Renders extends Rules {
      * Entry point for mounting renders.
      * Decides render strategy based on props.
      */
-    protected renderMount(this: AppForge, props: Types.Props.Main): Vide.Node;
+    protected renderMount(this: AppForge, props: Types.Props.Main): void | Instance | Vide.InstanceAttributes<Instance> | Vide.Action<any> | ReadonlyMap<number, Vide.Node> | {
+        readonly [key: number]: Vide.Node;
+    } | Vide.FunctionNode;
     private renderNames;
     private collectByGroup;
     private normalizeGroups;
@@ -21,5 +23,5 @@ export default class Renders extends Rules {
     protected renderGroup(this: AppForge, props: Types.Props.Main): Vide.Node[];
     protected renderGroupByName(this: AppForge, props: Types.Props.Main): Vide.Node[];
     protected renderGroupByNames(this: AppForge, props: Types.Props.Main): Vide.Node[];
-    protected renderAll(this: AppForge, props: Types.Props.Main): Vide.Node[];
+    protected renderAll(this: AppForge, props: Types.Props.Main): void | Vide.Node[];
 }

package/out/{vide/classes → classes}/renders.luau

@@ -162,7 +162,6 @@ do
 		end
 		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",
@@ -248,6 +247,9 @@ do
 			_callback(_v, _k, AppRegistry)
 		end
 		-- ▲ ReadonlyMap.forEach ▲
+		if not names then
+			return self.logger:log("WARN", "When mounting | Renderer found 0 apps, Makes sure you add the Directory of the Apps to Flamework!")
+		end
 		return self:renderNames(props, names, self)
 	end
 end

package/out/{vide/classes → classes}/rules/exclusiveGroup.d.ts

@@ -1,2 +1,2 @@
-import type AppForge from "../..";
+import type AppForge from "../../main";
 export default function ExclusiveGroupRule(entry: AppNames, forge: AppForge): void;

package/out/{vide/classes → classes}/rules/index.d.ts

@@ -1,5 +1,5 @@
 import type Types from "../../types";
-import type AppForge from "../..";
+import type AppForge from "../../main";
 export default class Rules {
     protected processing: Set<string>;
     protected renderRules(this: AppForge, name: AppNames, props: Types.Props.Main): void;

package/out/{react → classes}/rules/parent.d.ts

@@ -1,2 +1,2 @@
-import type AppForge from "..";
+import type AppForge from "../../main";
 export default function ParentRule(entry: AppNames, forge: AppForge): void;

package/out/{vide/classes → classes}/rules/parent.luau

@@ -19,6 +19,7 @@ local function ParentRule(entry, forge)
 			return nil
 		end
 		forge.debug:logTag("rules", entry, "Closing child app (parent closed)", {
+			parent = entry,
 			child = name,
 		})
 		forge:close(name, false)

package/out/{vide/context.d.ts → context.d.ts}

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

package/out/{vide/debug → debug}/debugger.luau

@@ -53,7 +53,7 @@ do
 		if not self:isEnabled(tag) then
 			return nil
 		end
-		self.log("DEBUG", `[{tag}][{app}] {message}`, data, debug.traceback(nil, 3))
+		self.log("DEBUG", `[{tag}][{app}] {message}`, data)
 	end
 	function Debugger:time(tag, app)
 		if not RunService:IsStudio() then

package/out/{vide/decorator.d.ts → decorator.d.ts}

@@ -1,6 +1,6 @@
 import Vide from "@rbxts/vide";
 import type Types from "./types";
-import type AppForge from ".";
+import type AppForge from "./main";
 export declare const AppRegistry: Map<string, Types.AppRegistry.Static>;
 /**
  * Registers a Vide App with AppForge.

package/out/{vide/decorator.luau → decorator.luau}

@@ -29,12 +29,6 @@ local function App(props)
 			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,

package/out/{vide/hooks → hooks}/useAppContext.d.ts

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

package/out/{vide/hooks → hooks}/usePx.luau

@@ -74,11 +74,6 @@ local function usePx(target, baseResolution, minScale)
 		return nil
 	end
 	INITIALIZED = true
-	logger:log("DEBUG", "Initializing px scaling", {
-		target = target,
-		baseResolution = baseResolution,
-		minScale = minScale,
-	})
 	if baseResolution then
 		BASE_RESOLUTION(baseResolution)
 	end

package/out/index.d.ts

@@ -1,11 +1,5 @@
-export { App as ReactApp, Args as ReactArgs } from "./react/decorator";
-export { App as VideApp, Args as VideArgs } from "./vide/decorator";
-export { default as CreateReactForge } from "./react";
-export { default as CreateVideForge } from "./vide";
-export { Render as RenderReact } from "./react/helpers";
-export type { MainProps as VideProps, ClassProps as VideClassProps, RenderProps as VideRenderProps, } from "./vide/types";
-export type { MainProps as ReactProps, ClassProps as ReactClassProps, } from "./react/types";
-export { default as useReactAppContext } from "./react/hooks/useAppContext";
-export { default as ReactContexts } from "./react/context";
-export { default as useVideAppContext } from "./vide/hooks/useAppContext";
-export { default as VideContexts } from "./vide/context";
+export { App, Args } from "./decorator";
+export { default as CreateForge } from "./main";
+export type { ForgeProps, ClassProps, RenderProps, } from "./types";
+export { default as useAppContext } from "./hooks/useAppContext";
+export { default as Contexts } from "./context";

package/out/init.luau

@@ -2,20 +2,12 @@
 local TS = _G[script]
 local exports = {}
 -- Decorators
-local _decorator = TS.import(script, script, "react", "decorator")
-exports.ReactApp = _decorator.App
-exports.ReactArgs = _decorator.Args
-local _decorator_1 = TS.import(script, script, "vide", "decorator")
-exports.VideApp = _decorator_1.App
-exports.VideArgs = _decorator_1.Args
+local _decorator = TS.import(script, script, "decorator")
+exports.App = _decorator.App
+exports.Args = _decorator.Args
 -- Creators
-exports.CreateReactForge = TS.import(script, script, "react").default
-exports.CreateVideForge = TS.import(script, script, "vide").default
--- Helpers
-exports.RenderReact = TS.import(script, script, "react", "helpers").Render
+exports.CreateForge = TS.import(script, script, "main").default
 -- Types
-exports.useReactAppContext = TS.import(script, script, "react", "hooks", "useAppContext").default
-exports.ReactContexts = TS.import(script, script, "react", "context").default
-exports.useVideAppContext = TS.import(script, script, "vide", "hooks", "useAppContext").default
-exports.VideContexts = TS.import(script, script, "vide", "context").default
+exports.useAppContext = TS.import(script, script, "hooks", "useAppContext").default
+exports.Contexts = TS.import(script, script, "context").default
 return exports

package/out/{vide/index.d.ts → main.d.ts}

@@ -26,8 +26,8 @@ export default class AppForge extends Renders {
     open(name: AppNames, rules?: boolean): void;
     close(name: AppNames, rules?: boolean): void;
     toggle(name: AppNames, rules?: boolean): void;
-    story(props: Types.Props.Main): Frame;
-    mount(callback: () => Vide.Node, props: Types.Props.Main, target: Instance): Destructor;
+    story(props: AppProps, render: Types.Props.Render, target: GuiObject): Frame;
+    mount(node: Vide.Node, props: Types.Props.Main, target: Instance): Destructor;
     unMount(): void;
 }
 export {};

package/out/{vide/init.luau → main.luau}

@@ -4,6 +4,7 @@ local TS = _G[script]
 local RunService = TS.import(script, TS.getModule(script, "@rbxts", "services")).RunService
 -- Packages
 local _vide = TS.import(script, TS.getModule(script, "@rbxts", "vide").src)
+local Vide = _vide
 local apply = _vide.apply
 local create = _vide.create
 local effect = _vide.effect
@@ -11,11 +12,11 @@ local mount = _vide.mount
 local source = _vide.source
 local untrack = _vide.untrack
 -- Classes
-local Renders = TS.import(script, script, "classes", "renders").default
+local Renders = TS.import(script, script.Parent, "classes", "renders").default
 -- Helpers
-local AppRegistry = TS.import(script, script, "decorator").AppRegistry
+local AppRegistry = TS.import(script, script.Parent, "decorator").AppRegistry
 -- Debug
-local _debug = TS.import(script, script, "debug")
+local _debug = TS.import(script, script.Parent, "debug")
 local Logger = _debug.Logger
 local Debugger = _debug.Debugger
 local AppForge
@@ -109,11 +110,27 @@ do
 			local _name = name
 			local _value = value
 			_sources[_name] = _value
+			local prev
+			local log = function()
+				return self.debug:logTag("state", name, "Visibility changed", {
+					from = prev,
+					to = value,
+				})
+			end
+			local count = 0
 			effect(function()
-				value()
+				count += 1
+				prev = value()
 				untrack(function()
 					return self:checkRules(name)
 				end)
+				if Vide.strict and count == 2 then
+					log()
+					count = 0
+				elseif not Vide.strict and count == 1 then
+					log()
+					count = 0
+				end
 			end)
 		else
 			self.logger:log("WARN", "forge.bind called while game is running", {
@@ -246,7 +263,7 @@ do
 		end
 		self:set(name, not self:getSource(name)(), rules)
 	end
-	function AppForge:story(props)
+	function AppForge:story(props, render, target)
 		self.debug:logTag("lifecycle", "story", "Creating story mount")
 		local Container = create("Frame")({
 			Name = "Story Container",
@@ -256,18 +273,26 @@ do
 			Size = UDim2.fromScale(1, 1),
 		})
 		apply(Container)({
-			[0] = self:renderMount(props),
+			[0] = self:renderMount({
+				props = props,
+				forge = self,
+				render = render,
+				config = {
+					px = {
+						target = target,
+					},
+				},
+			}),
 		})
 		return Container
 	end
-	function AppForge:mount(callback, props, target)
+	function AppForge:mount(node, props, target)
 		self.debug:logTag("lifecycle", "mount", "Mounting AppForge")
-		local Container = callback()
 		self.innerMount = mount(function()
-			apply(Container)({
+			apply(node)({
 				[0] = self:renderMount(props),
 			})
-			return Container
+			return node
 		end, target)
 		return self.innerMount
 	end

package/out/{vide/types.d.ts → types.d.ts}

@@ -1,6 +1,6 @@
 // Types
 import type { Args } from "./decorator";
-import type AppForge from ".";
+import type AppForge from "./main";
 
 declare namespace Types {
 	namespace Props {
@@ -78,7 +78,7 @@ declare namespace Types {
 	}
 }
 
-export type MainProps = Types.Props.Main;
+export type ForgeProps = Types.Props.Main;
 export type ClassProps = Types.Props.Class;
 export type RenderProps = Types.Props.Render;
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rbxts/app-forge",
-	"version": "0.7.2-alpha.2",
+	"version": "0.7.2-alpha.20",
 	"description": "An App Manager for Vide",
 	"main": "out/init.lua",
 	"types": "out/index.d.ts",
@@ -34,24 +34,18 @@
 		"access": "public"
 	},
 	"dependencies": {
+		"@rbxts/set-timeout": "^1.1.2",
 		"@rbxts/services": "^1.6.0",
-		"@rbxts/set-timeout": "^1.1.2"
-	},
-	"peerDependencies": {
-		"@rbxts/react": "^17.3.7-ts.1",
-		"@rbxts/vide": "^0.5.7"
+		"@rbxts/vide": "^0.6.0"
 	},
 	"peerDependenciesMeta": {
-		"@rbxts/react": {
-			"optional": true
-		},
 		"@rbxts/vide": {
 			"optional": true
 		}
 	},
 	"devDependencies": {
-		"@biomejs/biome": "^2.3.7",
 		"@rbxts/compiler-types": "3.0.0-types.0",
+		"@biomejs/biome": "^2.3.7",
 		"@rbxts/types": "^1.0.891",
 		"roblox-ts": "3.0.0",
 		"typescript": "^5.9.3"