@rbxts/app-forge 0.7.2-alpha.22 → 0.7.2-alpha.24

package/README.md

@@ -1,183 +1,124 @@
 # AppForge
 
-> ⚠️ **Documentation Notice**
->
-> This README was written with the assistance of **AI tooling**.
-> I do not currently have the time to write a fully hand-crafted documentation site, so there may be typos, rough wording, or missing explanations.
->
-> If you find an issue, inconsistency, or bug in the docs or API, please **@ me on Discord** in the **roblox-ts Discord**: `@loner71x`.
->
-> Thank you for your patience ❤️
+> ⚠️ **Documentation Notice**  
+> Written with AI assistance. Please report any issues in [GitHub Issues](https://github.com/Loner1536/AppForge/issues) or on Discord: `@loner71x`.
 
-> **An App Manager for Vide**
-
-AppForge is a **declarative UI application manager** built on top of [Vide](https://github.com/centau/vide) for **roblox-ts**. It provides a structured way to register, mount, show/hide, group, and coordinate UI "apps" using rules instead of ad‑hoc state wiring.
-
-If you’ve ever ended up with tangled UI state, duplicated visibility logic, or brittle parent/child UI dependencies — AppForge is meant to solve that without forcing you into complex patterns.
+**AppForge** is a **declarative UI application manager** for [Vide](https://github.com/centau/vide) in **roblox-ts**. It allows you to structure, mount, and control UI “apps” with centralized visibility, parent-child relationships, exclusive groups, and ZIndex rules — without tangled state.
 
 ---
 
 ## ✨ Features
 
-* **App-based UI architecture**
-* **Centralized visibility state** per app
-* **Rule system** (parent/child, exclusive groups, z-index)
-* **Render groups** for selective mounting
-* **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**
+- **App-based UI architecture**: self-contained UI units  
+- **Centralized visibility** per app  
+- **Rules system**: parent/child, exclusive groups, ZIndex  
+- **Render groups** for selective mounting  
+- **Built-in debug logger & performance tracing**  
+- **Fully typed with roblox-ts**
 
 ---
 
 ## 📦 Installation
 
-### Using **bun**
-
-```bash
-bun add @rbxts/app-forge
-```
-
-Peer dependencies (choose one renderer):
-
-```bash
-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
-```
-
----
-
-## 🧠 Core Concepts
-
-### App
-
-An **App** is a self-contained UI unit:
-
-* owns its own visibility source
-* renders a Vide tree
-* can depend on other apps via rules
 
-Apps are registered using a decorator and rendered through `AppForge`.
+Or using Bun:
 
----
-
-### Forge
-
-`AppForge` is the runtime manager. It:
+bun add @rbxts/app-forge
+bun add @rbxts/vide
 
-* owns all app visibility sources
-* mounts and unmounts UI
-* enforces rules
-* exposes imperative helpers (`open`, `close`, `toggle`)
-* owns the **debugger & logger** instance
+🧠 Core Concepts
+App
 
-You usually create **one Forge per UI root**.
+An App is a self-contained UI unit:
 
----
+    Owns its visibility source
 
-### Rules
+    Renders a Vide tree
 
-Rules define **relationships between apps**, not layout.
+    Can have rules: parent/child, exclusive groups, ZIndex
 
-Currently supported:
+Apps are defined using the @App decorator and must extend Args.
+Forge
 
-| Rule             | Description                            |
-| ---------------- | -------------------------------------- |
-| `parent`         | Child app closes when parent closes    |
-| `detach`         | Prevents automatic anchoring to parent |
-| `exclusiveGroup` | Only one app in the group may be open  |
-| `index`          | Sets ZIndex of the app container       |
+AppForge is the runtime manager:
 
-Rules are enforced automatically whenever visibility changes.
+    Holds all visibility sources
 
----
+    Mounts/unmounts apps in the UI
 
-### Render Groups
+    Applies rules automatically
 
-Render groups let you **selectively mount apps**.
+    Exposes imperative helpers: open, close, toggle
 
-Example use cases:
+    Owns debugger & logger
 
-* Lobby UI vs In‑Game UI
-* HUD vs Menus
-* Feature‑flagged UI
+One Forge per UI root is recommended.
+Rules
+Rule	Description
+parent	Child app closes automatically when parent closes
+detach	Prevents automatic anchoring to parent
+exclusiveGroup	Only one app in the group may be open
+index	Sets ZIndex of the app container
 
----
+Rules are reactively enforced when visibility changes.
+Render Groups
 
-## 🧩 Basic Usage
+Render groups let you mount selective apps:
 
-### Creating a Forge
+    Example: Lobby UI vs In-Game UI
 
-```ts
-const forge = new CreateVideForge();
-```
+    Example: HUD vs Menus
 
-> `CreateVideForge` owns its internal state. You **do not pass the forge into itself** — it is only provided to Apps at render-time.
+Apps can be rendered by group, name, or multiple names using the Forge’s internal rendering methods.
+🧩 Basic Usage
+Creating a Forge
 
----
+import { CreateForge } from "@rbxts/app-forge";
 
-### Mounting (Game Runtime)
+const forge = new CreateForge();
 
-```ts
-const forge = new CreateVideForge();
+Mounting to the PlayerGui
 
 forge.mount(
- () => (
-  <screengui
-   Name="App"
-   ZIndexBehavior="Sibling"
-   ResetOnSpawn={false}
-  />
- ),
- props,
- Players.LocalPlayer.WaitForChild("PlayerGui"),
+ <screengui
+  Name="AppRoot"
+  ZIndexBehavior="Sibling"
+  ResetOnSpawn={false}
+ />,
+ { props: {}, forge },
+ Players.LocalPlayer.WaitForChild("PlayerGui")
 );
-```
 
----
+    ⚠️ Note: You pass the root node directly, not a function.
 
-### Opening & Closing Apps
+Controlling Apps
 
-```ts
 forge.open("Inventory");
 forge.close("Inventory");
 forge.toggle("Inventory");
-```
 
----
+    open(name): Shows the app
+
+    close(name): Hides the app
 
-## 🧱 Defining an App
+    toggle(name): Toggles visibility
 
-```ts
-@VideApp({
+Defining an App
+
+import { App, Args } from "@rbxts/app-forge";
+
+@App({
  name: "Inventory",
  renderGroup: "Lobby",
  visible: false,
- rules: {
-  index: 2,
- },
+ rules: { zIndex: 2 },
 })
-export class Inventory extends VideArgs {
+export class Inventory extends Args {
  render() {
-  const { px } = this.props;
+  const { px } = this.props; // px comes from the Forge
 
   return (
    <frame
@@ -187,81 +128,28 @@ export class Inventory extends VideArgs {
   );
  }
 }
-```
-
----
-
-## 🐞 Debugging & Logging
 
-AppForge includes a **built-in debugger** designed for Studio-only diagnostics.
+    @App registers the app with the Forge
 
-### Debug Tags
+    px provides scaling helpers automatically
 
-Debug output is grouped by **typed tags**:
+    rules define relationships (parent, exclusive group, ZIndex)
 
-```ts
-type DebugTag =
- | "render"
- | "rules"
- | "state"
- | "px"
- | "lifecycle";
-```
+🐞 Debugging
 
-Each subsystem logs under its respective tag.
+AppForge provides Studio-only debug logging:
 
----
-
-### Enabling Debug Tags
-
-```ts
 forge.debug.enable("render");
 forge.debug.enable("rules");
-```
-
-Enable everything at once:
-
-```ts
-forge.debug.enableAll();
-```
-
-Disable:
-
-```ts
+forge.debug.enableAll();   // everything
 forge.debug.disable("render");
-```
-
-Debug logging only runs in **Roblox Studio**.
-
----
-
-### Performance Tracing
-
-Certain systems emit **timing logs** when enabled:
 
-```ts
-forge.debug.enable("render");
-```
-
-Output example:
+Performance tracing example:
 
-```
 [PERF][render][Inventory] 1.243ms
-```
-
----
-
-### Static Registration Logs
-
-App registration (decorators) run **before a Forge exists**.
-
-These use an internal **static logger** and will still emit warnings and errors during Studio load (e.g. duplicate app names).
-
----
 
-## 🧱 Architecture Overview
+🧱 Architecture Overview
 
-```
 AppForge
  ├─ AppRegistry (static)
  ├─ Visibility Sources
@@ -271,42 +159,25 @@ AppForge
  │   └─ Exclusive Group Rule
  ├─ Debugger / Logger
  └─ Vide Mount
-```
 
----
-
-## ⚠️ Notes
-
-* 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
-
----
-
-## 🛣 Roadmap
+⚠️ Notes
 
-* [ ] Transition animations API
-* [ ] Async app loading
-* [ ] Better dev warnings
-* [ ] Debug inspector
+    Apps are singletons per Forge
 
----
+    Rendering twice warns if px is re-initialized
 
-## ⚛️ React Support (Planned)
+    Rules are reactive
 
-AppForge is designed as a **renderer-agnostic App Manager**.
+    Debug logging only runs in Studio
 
-Currently:
+    API is alpha — may change
 
-* ✅ **Vide renderer** is production-ready
-* 🚧 **React renderer** exists but is **very early / experimental**
+🛣 Roadmap
 
-Vide is the recommended and supported path today.
+    Better developer warnings
 
----
+    Debug inspector
 
-## 📜 License
+📜 License
 
-MIT
+MIT

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

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

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

@@ -5,7 +5,7 @@ local TS = _G[script]
 -- Hooks
 local px = TS.import(script, script.Parent, "hooks", "usePx").px
 -- Debug
-local Logger = TS.import(script, script.Parent, "debug", "logger").default
+local Logger = TS.import(script, script.Parent, "logger").default
 local logger = Logger.new("AppRegistry")
 local AppRegistry = {}
 --[[

package/out/context.d.ts

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

package/out/hooks/useAppContext.luau

@@ -3,7 +3,7 @@ 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 = TS.import(script, script.Parent.Parent, "logger").default
 local logger = Logger.new("useAppContext")
 local default = function()
 	local context = Contexts.App()

package/out/hooks/useEventListener.luau

@@ -2,7 +2,7 @@
 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 = TS.import(script, script.Parent.Parent, "logger").default
 local logger = Logger.new("useEventListener")
 local connect = function(event, callback)
 	local _event = event

package/out/hooks/usePx.luau

@@ -7,7 +7,7 @@ local source = TS.import(script, TS.getModule(script, "@rbxts", "vide").src).sou
 -- Helpers
 local useEventListener = TS.import(script, script.Parent, "useEventListener").useEventListener
 -- Debug
-local Logger = TS.import(script, script.Parent.Parent, "debug", "logger").default
+local Logger = TS.import(script, script.Parent.Parent, "logger").default
 local logger = Logger.new("usePx")
 --* Default reference resolution for px calculations 
 local BASE_RESOLUTION = source(Vector2.new(1920, 1080))

package/out/index.d.ts

@@ -1,5 +1,5 @@
-export { App, Args } from "./decorator";
-export { default as CreateForge } from "./main";
+export { App, Args } from "./appRegistry";
+export { default as CreateForge } from "./mount";
 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,11 +2,11 @@
 local TS = _G[script]
 local exports = {}
 -- Decorators
-local _decorator = TS.import(script, script, "decorator")
-exports.App = _decorator.App
-exports.Args = _decorator.Args
+local _appRegistry = TS.import(script, script, "appRegistry")
+exports.App = _appRegistry.App
+exports.Args = _appRegistry.Args
 -- Creators
-exports.CreateForge = TS.import(script, script, "main").default
+exports.CreateForge = TS.import(script, script, "mount").default
 -- Types
 exports.useAppContext = TS.import(script, script, "hooks", "useAppContext").default
 exports.Contexts = TS.import(script, script, "context").default

package/out/{main.d.ts → mount.d.ts}

@@ -1,7 +1,8 @@
 import Vide from "@rbxts/vide";
-import Renders from "./classes/renders";
+import Renders from "./renderManager";
+import Debugger from "./debugger";
+import Logger from "./logger";
 import Types from "./types";
-import { Logger, Debugger } from "./debug";
 type Destructor = () => void;
 type Loaded = {
     container: Vide.Node;
@@ -26,7 +27,7 @@ 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: AppProps, render: Types.Props.Render, target: GuiObject): Frame;
+    story(props: AppProps, target: GuiObject, render?: Types.Props.Render): Frame;
     mount(node: Vide.Node, props: Types.Props.Main, target: Instance): Destructor;
     unMount(): void;
 }

package/out/{main.luau → mount.luau}

@@ -12,13 +12,11 @@ local mount = _vide.mount
 local source = _vide.source
 local untrack = _vide.untrack
 -- Classes
-local Renders = TS.import(script, script.Parent, "classes", "renders").default
+local Renders = TS.import(script, script.Parent, "renderManager").default
 -- Helpers
-local AppRegistry = TS.import(script, script.Parent, "decorator").AppRegistry
--- Debug
-local _debug = TS.import(script, script.Parent, "debug")
-local Logger = _debug.Logger
-local Debugger = _debug.Debugger
+local AppRegistry = TS.import(script, script.Parent, "appRegistry").AppRegistry
+local Debugger = TS.import(script, script.Parent, "debugger").default
+local Logger = TS.import(script, script.Parent, "logger").default
 local AppForge
 do
 	local super = Renders
@@ -65,7 +63,7 @@ do
 		if _sources[_name_1] ~= nil then
 			return nil
 		end
-		local _debug_1 = self.debug
+		local _debug = self.debug
 		local _exp = name
 		local _object = {}
 		local _left = "default"
@@ -74,7 +72,7 @@ do
 			_condition = false
 		end
 		_object[_left] = _condition
-		_debug_1:logTag("state", _exp, "Creating visibility source", _object)
+		_debug:logTag("state", _exp, "Creating visibility source", _object)
 		local _sources_1 = self.sources
 		local _exp_1 = name
 		local _condition_1 = app.visible
@@ -263,7 +261,7 @@ do
 		end
 		self:set(name, not self:getSource(name)(), rules)
 	end
-	function AppForge:story(props, render, target)
+	function AppForge:story(props, target, render)
 		self.debug:logTag("lifecycle", "story", "Creating story mount")
 		local Container = create("Frame")({
 			Name = "Story Container",

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

@@ -1,7 +1,7 @@
 import Vide from "@rbxts/vide";
-import type Types from "../types";
-import type AppForge from "../main";
-import Rules from "./rules";
+import type Types from "./types";
+import type AppForge from "./mount";
+import Rules from "./ruleEngine";
 export default class Renders extends Rules {
     protected anchored: Map<string, {
         id: AppNames;

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

@@ -6,11 +6,11 @@ local apply = _vide.apply
 local create = _vide.create
 -- Types
 -- Components
-local AppRegistry = TS.import(script, script.Parent.Parent, "decorator").AppRegistry
+local AppRegistry = TS.import(script, script.Parent, "appRegistry").AppRegistry
 -- Hooks
-local usePx = TS.import(script, script.Parent.Parent, "hooks", "usePx").usePx
+local usePx = TS.import(script, script.Parent, "hooks", "usePx").usePx
 -- Classes
-local Rules = TS.import(script, script.Parent, "rules").default
+local Rules = TS.import(script, script.Parent, "ruleEngine").default
 local Renders
 do
 	local super = Rules

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

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

package/out/{classes/rules → ruleEngine}/exclusiveGroup.luau

@@ -2,7 +2,7 @@
 local TS = _G[script]
 -- Types
 -- Components
-local AppRegistry = TS.import(script, script.Parent.Parent.Parent, "decorator").AppRegistry
+local AppRegistry = TS.import(script, script.Parent.Parent, "appRegistry").AppRegistry
 local function ExclusiveGroupRule(entry, forge)
 	local _entry = entry
 	local entryApp = AppRegistry[_entry]

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

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

package/out/{classes/rules → ruleEngine}/init.luau

@@ -2,7 +2,7 @@
 local TS = _G[script]
 -- Types
 -- Components
-local AppRegistry = TS.import(script, script.Parent.Parent, "decorator").AppRegistry
+local AppRegistry = TS.import(script, script.Parent, "appRegistry").AppRegistry
 -- Rules
 local ExclusiveGroupRule = TS.import(script, script, "exclusiveGroup").default
 local ParentRule = TS.import(script, script, "parent").default
@@ -43,9 +43,9 @@ do
 			self:anchor(name, rules.parent, props)
 		end
 		-- Index
-		if rules.index ~= nil then
-			self.debug:logTag("rules", name, "Applying ZIndex", rules.index)
-			self:index(name, rules.index)
+		if rules.zIndex ~= nil then
+			self.debug:logTag("rules", name, "Applying ZIndex", rules.zIndex)
+			self:index(name, rules.zIndex)
 		end
 	end
 	function Rules:checkRules(name)

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

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

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

@@ -2,7 +2,7 @@
 local TS = _G[script]
 -- Types
 -- Components
-local AppRegistry = TS.import(script, script.Parent.Parent.Parent, "decorator").AppRegistry
+local AppRegistry = TS.import(script, script.Parent.Parent, "appRegistry").AppRegistry
 local function ParentRule(entry, forge)
 	local entryVisible = forge:getSource(entry)()
 	-- ▼ ReadonlyMap.forEach ▼

package/out/types.d.ts

@@ -1,6 +1,6 @@
 // Types
-import type { Args } from "./decorator";
-import type AppForge from "./main";
+import type { Args } from "./appRegistry";
+import type AppForge from "./mount";
 
 declare namespace Types {
 	namespace Props {
@@ -68,12 +68,12 @@ declare namespace Types {
 
 		export type Static = {
 			exclusiveGroup?: string;
-			index?: number;
+			zIndex?: number;
 		} & (WithParent<string> | WithoutParent);
 
 		export type Generic<N extends AppNames = AppNames> = {
 			exclusiveGroup?: AppGroups;
-			index?: number;
+			zIndex?: number;
 		} & (WithParent<Exclude<AppNames, N>> | WithoutParent);
 	}
 }

package/package.json

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

package/out/debug/index.d.ts

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

package/out/debug/init.luau

@@ -1,8 +0,0 @@
--- 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,
-}