@rbxts/app-forge 0.7.2-alpha.9 → 0.7.2-prototype.2

package/README.md

@@ -1,238 +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**
-* 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`.
-
----
-
-### Forge
-
-`AppForge` is the runtime manager. It:
-
-* owns all app visibility sources
-* mounts and unmounts UI
-* enforces rules
-* exposes imperative helpers (`open`, `close`, `toggle`)
-
-You usually create **one Forge per UI root**.
-
----
-
-### Rules
 
-Rules define **relationships between apps**, not layout.
+Or using Bun:
 
-Currently supported:
-
-| 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       |
-
-Rules are enforced automatically whenever visibility changes.
-
----
-
-### Render Groups
-
-Render groups let you **selectively mount apps**.
-
-Example use cases:
-
-* Lobby UI vs In‑Game UI
-* HUD vs Menus
-* Feature‑flagged UI
+bun add @rbxts/app-forge
+bun add @rbxts/vide
 
----
+🧠 Core Concepts
+App
 
-## 🧩 Basic Usage
+An App is a self-contained UI unit:
 
-### Creating a Forge
+    Owns its visibility source
 
-```ts
-const forge = new CreateVideForge();
-```
+    Renders a Vide tree
 
-> `CreateVideForge` owns its internal state. You **do not pass the forge into itself** — it is only provided to Apps at render-time.
+    Can have rules: parent/child, exclusive groups, ZIndex
 
----
+Apps are defined using the @App decorator and must extend Args.
+Forge
 
-### Mounting (Game Runtime)
+AppForge is the runtime manager:
 
-AppForge is mounted once from application bootstrap code (commonly a Flamework controller).
+    Holds all visibility sources
 
-```ts
-const forge = new CreateVideForge();
+    Mounts/unmounts apps in the UI
 
-forge.mount(
- () => (
-  <screengui
-   Name="App"
-   ZIndexBehavior="Sibling"
-   ResetOnSpawn={false}
-  />
- ),
- props,
- Players.LocalPlayer.WaitForChild("PlayerGui"),
-);
-```
+    Applies rules automatically
 
-Notes:
+    Exposes imperative helpers: open, close, toggle
 
-* `forge` is **implicitly available** to Apps
-* `props` are user-defined and become `this.props` inside Apps
-* visibility & rules are controlled entirely by the Forge
+    Owns debugger & logger
 
----
+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
 
-### Mounting (Game Runtime)
+Rules are reactively enforced when visibility changes.
+Render Groups
 
-AppForge is typically mounted from a **controller** (e.g. Flamework) and targets `PlayerGui`.
+Render groups let you mount selective apps:
 
-```ts
-const forge = new CreateVideForge();
+    Example: Lobby UI vs In-Game UI
 
-forge.mount(
- () => (
-  <screengui
-   Name="App"
-   ZIndexBehavior="Sibling"
-   ResetOnSpawn={false}
-  />
- ),
- props,
- Players.LocalPlayer.WaitForChild("PlayerGui"),
-);
-```
+    Example: HUD vs Menus
 
-This:
+Apps can be rendered by group, name, or multiple names using the Forge’s internal rendering methods.
+🧩 Basic Usage
+Creating a Forge
 
-* creates a single root `ScreenGui`
-* mounts all rendered apps under it
-* keeps AppForge in control of visibility & rules
+import { CreateForge } from "@rbxts/app-forge";
 
----
+const forge = new CreateForge();
 
-### Mounting
+Mounting to the PlayerGui
 
-```ts
 forge.mount(
- () => <screengui ResetOnSpawn={false} />,
- props,
- 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");
-```
 
-You can also access the reactive source directly:
+    open(name): Shows the app
 
-```ts
-const visible = forge.getSource("Inventory");
-```
+    close(name): Hides the app
 
----
+    toggle(name): Toggles visibility
 
-## 🧱 Defining an App
+Defining an App
 
-```ts
-import { VideApp, VideArgs } from "@rbxts/app-forge";
-import Vide from "@rbxts/vide";
+import { App, Args } from "@rbxts/app-forge";
 
-@VideApp({
+@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
@@ -242,175 +128,28 @@ 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 />;
- }
-}
-```
+    @App registers the app with the Forge
 
-Behavior:
+    px provides scaling helpers automatically
 
-* When `Inventory` closes → `InventoryInfo` closes
-* Child is **anchored** to parent unless `detach: true`
+    rules define relationships (parent, exclusive group, ZIndex)
 
-```ts
-rules: {
- parent: "Inventory",
- detach: true,
-}
-```
+🐞 Debugging
 
----
+AppForge provides Studio-only debug logging:
 
-## 🚦 Exclusive Groups
+forge.debug.enable("render");
+forge.debug.enable("rules");
+forge.debug.enableAll();   // everything
+forge.debug.disable("render");
 
-```ts
-@VideApp({
- name: "Settings",
- rules: {
-  exclusiveGroup: "Menus",
- },
-})
-```
+Performance tracing example:
 
-Only one app in the same `exclusiveGroup` may be open at a time.
+[PERF][render][Inventory] 1.243ms
 
----
+🧱 Architecture Overview
 
-## 🎭 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
-
-```ts
-render: { name: "Inventory" }
-```
-
----
-
-### Render multiple apps
-
-```ts
-render: { names: ["Inventory", "InventoryInfo"] }
-```
-
----
-
-### Render by group
-
-```ts
-render: { group: "Lobby" }
-```
-
----
-
-### Render by group + name
-
-```ts
-render: {
- group: "Lobby",
- name: "Inventory",
-}
-```
-
-Only renders `Inventory` **if** it belongs to the `Lobby` group.
-
----
-
-### Render by group + names
-
-```ts
-render: {
- group: "Lobby",
- names: ["Inventory", "Settings"],
-}
-```
-
-Only renders apps that:
-
-* are in the specified group(s)
-* and whose names match the provided list
-
----
-
-## 🧪 Story / Sandbox Rendering
-
-AppForge provides `forge.story` for **isolated rendering**, commonly used with **UI Labs**.
-
-```ts
-const forge = new CreateVideForge();
-
-return forge.story({
- props,
- config: {
-  px: {
-   target: storyProps.target,
-  },
- },
- render: { group: "Lobby" },
-});
-```
-
-This is ideal for:
-
-* component stories
-* previews
-* controlled visibility via bindings
-
----
-
-## 🧠 Context Access Inside Apps
-
-App props are provided via Vide context.
-
-```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();
-````
-
----
-
-## 🧱 Architecture Overview
-
-```
 AppForge
  ├─ AppRegistry (static)
  ├─ Visibility Sources
@@ -418,52 +157,27 @@ AppForge
  ├─ Rule Engine
  │   ├─ Parent Rule
  │   └─ Exclusive Group Rule
+ ├─ Debugger / Logger
  └─ Vide Mount
-```
-
----
 
-## ⚠️ Notes
+⚠️ Notes
 
-* Apps are **singletons per Forge**
-* Rendering twice will warn if px is re‑initialized
-* Rules are enforced **reactively**
-* This package is currently **alpha** — APIs may change
+    Apps are singletons per Forge
 
----
-
-## 🛣 Roadmap
+    Rendering twice warns if px is re-initialized
 
-* [ ] Transition animations API
-* [ ] Async app loading
-* [ ] Better dev warnings
-* [ ] Debug inspector
-
----
+    Rules are reactive
 
-## ⚛️ React Support (Planned)
+    Debug logging only runs in Studio
 
-AppForge is designed as a **renderer-agnostic App Manager**.b
+    API is alpha — may change
 
-Currently:
+🛣 Roadmap
 
-* ✅ **Vide renderer** is production-ready
-* 🚧 **React renderer** exists but is **very early / experimental**
+    Better developer warnings
 
-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.
+    Debug inspector
 
-Public surface (subject to change):
+📜 License
 
-```ts
-import { ReactApp, ReactArgs, CreateReactForge } from "@rbxts/app-forge";
-```
-
-**Vide is the recommended and supported path today.**
-
----
-
-## 📜 License
-
-MIT
-
----
+MIT

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

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

package/out/{vide/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/{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("./mount").default;
         px: typeof import("./hooks/usePx").px;
     } | undefined>;
 };

package/out/global.d.ts

@@ -1,7 +1,7 @@
 declare global {
 	// These will be overridden by the user
 	// They are only placeholders for your build
-	type GroupNames = string;
+	type AppGroups = string;
 	type AppNames = string;
 	type AppProps = {};
 }

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}/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/{vide/hooks → 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/{vide/hooks → 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))
@@ -77,7 +77,7 @@ local function usePx(target, baseResolution, minScale)
 	if baseResolution then
 		BASE_RESOLUTION(baseResolution)
 	end
-	if minScale ~= nil then
+	if minScale ~= 0 and minScale == minScale and minScale then
 		MIN_SCALE(minScale)
 	end
 	if target then

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 "./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,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 _appRegistry = TS.import(script, script, "appRegistry")
+exports.App = _appRegistry.App
+exports.Args = _appRegistry.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, "mount").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