@rbxts/app-forge 0.7.2-alpha.12 → 0.7.2-alpha.13

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/renders.d.ts

@@ -12,14 +12,16 @@ 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.VideAction<any> | ReadonlyMap<number, Vide.Node> | {
+        readonly [key: number]: Vide.Node;
+    } | Vide.FunctionNode;
     private renderNames;
     private collectByGroup;
     private normalizeGroups;
     protected renderApp(this: AppForge, props: Types.Props.Main): Vide.Node;
-    protected renderApps(this: AppForge, props: Types.Props.Main): Vide.Node[];
-    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 renderApps(this: AppForge, props: Types.Props.Main): void | Vide.Node[];
+    protected renderGroup(this: AppForge, props: Types.Props.Main): void | Vide.Node[];
+    protected renderGroupByName(this: AppForge, props: Types.Props.Main): void | Vide.Node[];
+    protected renderGroupByNames(this: AppForge, props: Types.Props.Main): void | Vide.Node[];
+    protected renderAll(this: AppForge, props: Types.Props.Main): void | Vide.Node[];
 }

package/out/vide/classes/renders.luau

@@ -92,7 +92,7 @@ do
 	end
 	function Renders:renderNames(props, names, forge)
 		if #names == 0 then
-			error("No app names provided to render", 2)
+			return warn("No app names provided to render | Make sure you have the paths where decorators are used!")
 		end
 		-- ▼ ReadonlyArray.map ▼
 		local _newValue = table.create(#names)

package/out/vide/init.luau

@@ -265,26 +265,28 @@ do
 	end
 	function AppForge:story(props)
 		self.debug:logTag("lifecycle", "story", "Creating story mount")
-		local Container = create("Frame")({
+		local container = create("Frame")({
 			Name = "Story Container",
 			BackgroundTransparency = 1,
 			AnchorPoint = Vector2.new(0.5, 0.5),
 			Position = UDim2.fromScale(0.5, 0.5),
 			Size = UDim2.fromScale(1, 1),
 		})
-		apply(Container)({
-			[0] = self:renderMount(props),
+		local render = self:renderMount(props)
+		apply(container)({
+			[0] = if render then render else nil,
 		})
-		return Container
+		return container
 	end
 	function AppForge:mount(callback, props, target)
 		self.debug:logTag("lifecycle", "mount", "Mounting AppForge")
-		local Container = callback()
+		local container = callback()
+		local render = self:renderMount(props)
 		self.innerMount = mount(function()
-			apply(Container)({
-				[0] = self:renderMount(props),
+			apply(container)({
+				[0] = if render then render else nil,
 			})
-			return Container
+			return container
 		end, target)
 		return self.innerMount
 	end

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rbxts/app-forge",
-	"version": "0.7.2-alpha.12",
+	"version": "0.7.2-alpha.13",
 	"description": "An App Manager for Vide",
 	"main": "out/init.lua",
 	"types": "out/index.d.ts",