cluaupp 0.2.2 → 0.2.3

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+## 0.2.3
+
+- Parser accepts `(void)x`, `static_cast<T>(x)`, `static constexpr` fields, and lambdas (`[](Player* p) { ... }`, `[&]`, `[=]`) so `Connect` / `BindToClose` compile without named-function wrappers.
+- Parser keeps `LuaArray<T>` / `vector<T>` field types on structs (`HotBar` / `Storage` on a Template).
+- `string_concat(...)` joins to Luau `..` (alongside string `+`).
+- Cursor is not a licensed host for Microsoft `ms-vscode.cpptools`. Cluaupp no longer writes `C_Cpp.*` settings or `c_cpp_properties.json`; `watch` strips leftover keys and marks cpptools as unwanted. C++ completion stays clangd.
+- Docs site is a C++-class handbook (syntax through lambdas and Luau `--!strict`). Per-class and per-enum dump pages are gone; engine members stay on create.roblox.com.
+
 ## 0.2.2
 
 - Header modules with a sibling `.cpp` now re-export those functions (`startingCoins` from `config.cpp` lands on `config.luau` via `configImpl`). The impl no longer `require`s its own header (`ReplicatedStorage.config`).

package/README.md

@@ -6,7 +6,7 @@
 
 **The definitive merge of C++ and modern Luau.**
 
-[Docs](https://kartzrbx.github.io/Cluaupp/) · [Learn](https://kartzrbx.github.io/Cluaupp/learn/) · [API](https://kartzrbx.github.io/Cluaupp/api/classes/)
+[Docs](https://kartzrbx.github.io/Cluaupp/) · [Handbook](https://kartzrbx.github.io/Cluaupp/docs/)
 
 [![npm version](https://img.shields.io/npm/v/cluaupp.svg)](https://www.npmjs.com/package/cluaupp)
 [![Node.js](https://img.shields.io/node/v/cluaupp.svg)](https://nodejs.org)

package/docs/README.md

@@ -1,23 +1,35 @@
 # Cluaupp documentation
 
+The live handbook is **[GitHub Pages](https://kartzrbx.github.io/Cluaupp/docs/)** — every construct the CLI accepts, not an Enum dump.
+
+## Start
+
 1. [Intro](intro.md) — what Cluaupp is
-2. [Getting started](getting-started.md) — npm, Rojo, Wally
-3. [CLI](cli.md) — `init`, `build`, `watch`
-4. [Syntax](syntax.md) — C++ subset, `local`, `const`
-5. [print and cout](print-cout.md) — `cout <<`, `cout::warn`, `endl`
-6. [C++ types](cpp-types.md) — primitives, Instances, `nullptr`
-7. [const](cpp-const.md) — immutability
-8. [Safety](cpp-safety.md) — client trust, Janitor, Net, DataService
-9. [Organization](cpp-organization.md) — server / client / shared
-10. [Advanced](cpp-advanced.md) — `::` vs `:`, Wally, performance
-11. [Architecture](architecture.md) — one file in, one file out; opt-in ForeverHD folders
-12. [OOP structure](oop/index.md) — file tags, services, modules, structs
-13. [Libraries](libraries/index.md) — DataService Init, Janitor, Promise, Net, more
-14. [Examples](examples/index.md) — leaderstats, combat validation, shop, HUD, sword
-15. [Roblox API](roblox-api.md) — Vector3, CFrame, UDim2, classes
-16. [Config](config.md) — `cluaupp.config.json`
-17. [Comparison](comparison.md) — roblox-ts and WASM
-
-Moonwave site (local): `npx moonwave dev`
-
-Full site + engine API: **[GitHub Pages](https://kartzrbx.github.io/Cluaupp/)**
+2. [Getting started](getting-started.md) — npm, `init`, Rojo, clangd
+3. [CLI](cli.md) — `init`, `build`, `watch`, `lsp`, `intellisense`, flags
+4. [Config](config.md) — `cluaupp.config.json`
+5. [IntelliSense](intellisense.md) — clangd only
+
+## Language
+
+6. [Syntax](syntax.md) — **complete subset**: files, types, functions, scopes, control, operators, strings, `string_concat`, callbacks, casts, OOP, singletons, unsupported
+7. [print and cout](print-cout.md) — logging
+8. [C++ types](cpp-types.md) — primitives, Instances, `LuaArray`
+9. [const](cpp-const.md) — immutability
+10. [Advanced](cpp-advanced.md) — `::` vs `:`, Wally, optimization notes
+
+## Structure
+
+11. [Organization](cpp-organization.md) — server / client / shared, filename tags
+12. [Architecture](architecture.md) — one file in, one file out
+13. [OOP structure](oop/index.md) — structs, sibling headers, `Class::` methods, singletons
+14. [Safety](cpp-safety.md) — client trust, Janitor, Net, DataService
+
+## Roblox
+
+15. [Libraries](libraries/index.md) — DataService, Janitor, Fusion / Iris / UI
+16. [Examples](examples/index.md) — leaderstats, combat, shop, HUD
+17. [Roblox API](roblox-api.md) — how to spell engine calls (Creator Hub for members)
+18. [Comparison](comparison.md) — roblox-ts and WASM
+
+Moonwave (local): `npx moonwave dev`. Site rebuild: `npm run site`.

package/docs/cli.md

@@ -60,7 +60,7 @@ Stdio JSON-RPC for **Cluaupp subset diagnostics** only. Completion, hover, and d
 
 ## `cluaupp intellisense [folder]`
 
-Writes `compile_commands.json`, `.clangd`, and `.vscode` for clangd, and installs LLVM clangd when needed.
+Alias: `intelisense`. Writes `compile_commands.json`, `.clangd`, and `.vscode` for clangd, and installs LLVM clangd when needed.
 
 ## `cluaupp --version` / `cluaupp -v`
 

package/docs/cpp-advanced.md

@@ -10,15 +10,18 @@ The subset is intentional. What exists is enough for game scripts; what is missi
 ## Supported
 
 - Functions, prototypes (headers only), `if` / `else` / `while` / range-`for` / `switch` (`case`, `default`, `break`)
+- `struct` types + `Class::` methods in a sibling `.h` / `.cpp`
 - `new Class(parent)`, `GetService<T>()`, `::` statics (`CFrame::lookAt`, `Enum::Material::Plastic`)
+- `static_cast<T>(x)`, `(void)x`, lambdas in `Connect` / `Add`
+- `static` / `constexpr` / `inline` specifiers, `LuaArray<T>`, `string_concat`
 - `->` methods and properties, `.` members, `Connect`
-- `const`, `auto`, `nullptr`, arithmetic, `&&` `||` `!=`
+- `const`, `auto`, `nullptr`, arithmetic, `&&` `||` `!=`, string `+`
 - Quoted includes, `.h` / `.hpp` as sources
 - Libraries via `#include <cluaupp/libs/...>` → `require(CluauppLibs.*)`
 
 ## Not supported (yet)
 
-Full C++: templates besides `GetService<T>`, `class` bodies as emitted types, `std::`, overloading as two runtimes, C-style `for`, macros, pointer arithmetic.
+Full C++: templates besides `GetService<T>` / `static_cast` / `LuaArray`, `class` bodies as emitted metatables, `std::`, overloading as two runtimes, C-style `for`, macros, pointer arithmetic, JSX.
 
 If you need a custom type, it is usually a **ModuleScript in shared** (a `.cpp` of functions) or a Wally package, not a C++ class the compiler would lower to a metatable.
 
@@ -72,4 +75,4 @@ void Grant(Player* player, int amount) {
 5. **Headers declare, scripts define.** Prototypes in `.h`, bodies in `.cpp`.
 6. **Do not share mutable statics across server and client** — use Net or DataService.
 
-See also: [syntax](syntax.md), [print and cout](print-cout.md), [libraries](libraries/index.md), [OOP](oop/index.md), [examples](examples/index.md), [comparison](comparison.md).
+See also: [syntax](syntax.md) (complete subset), [print and cout](print-cout.md), [libraries](libraries/index.md), [OOP](oop/index.md), [examples](examples/index.md), [comparison](comparison.md). Optimization notes on the site: [Optimization](https://kartzrbx.github.io/Cluaupp/docs/optimization.html).

package/docs/cpp-types.md

@@ -17,6 +17,8 @@ Cluaupp is statically typed in the C++ you write and in the Luau it emits. A typ
 | `void` | (no return) | procedures |
 | `auto` | inferred | when `new` or `GetService` makes the type obvious |
 | `Player*`, `Folder*`, … | `Player`, `Folder` | Instances |
+| `LuaArray<int>` / `vector<T>` | `{number}` | arrays (Template inventory, `GetPlayers`) |
+| `optional<T>` | `T?` | missing values (prefer `nullptr` on Instances) |
 | `Vector3`, `CFrame`, `UDim2` | same | datatypes |
 
 ```cpp

package/docs/examples/hud.md

@@ -9,7 +9,7 @@ Client-only: wait for the replicated profile, write labels, listen for currency
 
 Put a ScreenGui named `Hud` in StarterGui with `MoneyLabel` and `LevelLabel` (`TextLabel`).
 
-Define callbacks **above** `init()` so clangd and the subset both see them (no lambdas).
+Define callbacks **above** `init()` or use lambdas in `Connect`.
 
 ## `HudClient.client.cpp`
 

package/docs/examples/index.md

@@ -9,7 +9,7 @@ High-quality Cluaupp systems you can copy. Each page is a full service: C++ that
 
 In this repo the live sample is [`examples/game`](../../examples/game) (`src/server`, `src/client`, `src/shared`). Compiler TypeScript is never mixed with game C++. `cluaupp init` still copies [`templates/game`](../../templates/game).
 
-These are **not** dumps of `int main()`. Entry is `void init()`. There are no lambdas and no custom C++ classes — named functions + structs.
+These are **not** dumps of `int main()`. Entry is `void init()`. Types are `struct` + `Class::` methods. Callbacks may be named functions or lambdas. Canonical Leaderstats: [handbook](https://kartzrbx.github.io/Cluaupp/docs/leaderstats.html).
 
 ## Suggested layout
 

package/docs/examples/leaderstats.md

@@ -5,136 +5,65 @@ sidebar_position: 3
 
 # Leaderstats
 
-Roblox shows the player list from a Folder named exactly `leaderstats` under the Player, with `IntValue` / `StringValue` children. This service **creates** those values, then mirrors DataService currencies into them.
+Canonical copy (three files): [Docs → Example: Leaderstats](https://kartzrbx.github.io/Cluaupp/docs/leaderstats.html).
 
-It does **not** call `DataService.Init`. Boot that in [Data boot](data-boot.md).
+Roblox shows the player list from a Folder named exactly `leaderstats` under the Player. This service **creates** those values, then mirrors DataService coins into them.
 
-## Why this shape
+It does **not** call `DataService.Init`. Boot that in [Data boot](data-boot.md) with your `PlayerData` Template.
+
+## Files
+
+| File | Role |
+| --- | --- |
+| `shared/PlayerData.h` | Template structs (`Currencies.Coins`, inventory `LuaArray`) |
+| `server/LeaderstatsServer.h` | `struct LeaderstatsServer` — fields + method decls (same stem) |
+| `server/LeaderstatsServer.server.cpp` | `Class::` bodies + `void init()` |
+
+## Rules
 
 | Rule | Why |
 | --- | --- |
-| Create the Folder if missing | `FindFirstChild` is not a constructor |
-| Create the stat if missing | Returning early when it is absent never shows Money |
-| `StringValue` + `FormatNumber::Abbreviate` | Player list wants a string like `1.5K` |
-| Janitor per player, keyed by `player->Name` | Leaving the game must `Destroy` the section janitor |
-| `GetChangedSignal(Paths.Currencies)` | HUD / list update without polling |
-| Named function, not a lambda | Cluaupp has no lambdas. The shared callback refreshes **all** players (currency writes are rare) |
+| Same-stem header | `LeaderstatsServer.h` + `LeaderstatsServer.server.cpp`. A differently named `leaderstats.h` is a `require`. |
+| `.server.cpp` | Untagged cpp is a ModuleScript; `init()` will not run by itself. |
+| `Paths.Currencies.Coins` | After `Init`. A local `int Coins` is not a Data path. |
+| `string_concat` or string `+` | Luau `..`. Do not write `..` in the `.cpp`. |
+| Janitor keyed by player name | Leaving the game must `Destroy` the folder. |
+| Lambda or named function | `GetChangedSignal(...).Connect([coinsValue](int n) { ... })` is valid. |
 
-## `LeaderstatsServer.server.cpp`
+## Header
 
 ```cpp
+#pragma once
 #include <cluaupp/roblox.hpp>
 #include <cluaupp/libs/janitor.hpp>
 #include <cluaupp/libs/dataservice.hpp>
-#include <cluaupp/libs/formatnumber.hpp>
-
-Players* Players = GetService<Players>();
-Janitor* janitor = new Janitor();
-
-void EnsureStat(Folder* leaderstats, string name) {
-	Instance* existing = leaderstats->FindFirstChild(name);
-	if (existing != nullptr) {
-		return;
-	}
-	StringValue* stat = new StringValue(leaderstats);
-	stat->Name = name;
-	stat->Value = "0";
-}
-
-void SetStat(Folder* leaderstats, string name, int value) {
-	StringValue* stat = leaderstats->FindFirstChild(name);
-	if (stat == nullptr) {
-		cout::warn << "leaderstats missing " << name << endl;
-		return;
-	}
-	stat->Value = FormatNumber::Abbreviate(value);
-}
-
-Folder* EnsureLeaderstats(Player* player) {
-	Folder* leaderstats = player->FindFirstChild("leaderstats");
-	if (leaderstats != nullptr) {
-		return leaderstats;
-	}
-	leaderstats = new Folder(player);
-	leaderstats->Name = "leaderstats";
-	return leaderstats;
-}
-
-void ApplyCurrencies(Player* player) {
-	Data* data = DataService::Server.Get(player);
-	if (data == nullptr) {
-		return;
-	}
-	Folder* leaderstats = player->FindFirstChild("leaderstats");
-	if (leaderstats == nullptr) {
-		return;
-	}
-	int money = data->Get(DataService::Server.Paths.Currencies.Money);
-	int level = data->Get(DataService::Server.Paths.Currencies.Level);
-	SetStat(leaderstats, "Money", money);
-	SetStat(leaderstats, "Level", level);
-}
-
-void OnCurrenciesChanged() {
-	for (Player* player : Players->GetPlayers()) {
-		ApplyCurrencies(player);
-	}
-}
-
-void SetupPlayer(Player* player) {
-	Data* data = DataService::Server.WaitFor(player);
-	if (data == nullptr) {
-		cout::warn << "no profile for " << player->Name << endl;
-		return;
-	}
-
-	Folder* leaderstats = EnsureLeaderstats(player);
-	EnsureStat(leaderstats, "Money");
-	EnsureStat(leaderstats, "Level");
-	ApplyCurrencies(player);
 
-	Janitor* section = new Janitor();
-	section->Add(data->GetChangedSignal(DataService::Server.Paths.Currencies).Connect(OnCurrenciesChanged));
-	section->Add(leaderstats, "Destroy");
-	janitor->Add(section, "Destroy", player->Name);
-}
+struct LeaderstatsServer {
+	static constexpr int STARTING_COINS = 0;
+	Janitor* janitor;
+	string GetPlayerJanitorKey(Player* player);
+	void UpdateLeaderstatsWithValues(IntValue* currentValue, int newValue);
+	Folder* EnsurePlayerLeaderstatsFolder(Player* player);
+	void PlayerEntered(Player* player);
+};
+```
 
-void OnPlayerRemoving(Player* player) {
-	if (janitor->Get(player->Name)) {
-		janitor->Remove(player->Name);
-	}
-}
+## `PlayerEntered`
 
-void OnClose() {
-	janitor->Destroy();
-}
-
-void init() {
-	for (Player* player : Players->GetPlayers()) {
-		SetupPlayer(player);
+```cpp
+void LeaderstatsServer::PlayerEntered(Player* player) {
+	Folder* leaderstatsFolder = EnsurePlayerLeaderstatsFolder(player);
+	Data* playerData = DataService::Server.WaitFor(player);
+	IntValue* coinsValue = static_cast<IntValue*>(leaderstatsFolder->FindFirstChild("Coins"));
+	if (coinsValue) {
+		playerData->GetChangedSignal(DataService::Server.Paths.Currencies.Coins).Connect(
+			[coinsValue](int newValue) {
+				UpdateLeaderstatsWithValues(coinsValue, newValue);
+			}
+		);
 	}
-	janitor->Add(Players->PlayerAdded.Connect(SetupPlayer));
-	janitor->Add(Players->PlayerRemoving.Connect(OnPlayerRemoving));
-	game->BindToClose(OnClose);
+	janitor->Add(leaderstatsFolder, "Destroy", GetPlayerJanitorKey(player));
 }
 ```
 
-## Output
-
-`LeaderstatsServer.server.cpp` becomes a service folder: `init.luau` (Script, RunContext **Server**), `Main`, `PlayersManager`, `DataController` / `CacheController`, Types. Your functions stay in the domain controller. See [services](../oop/services.md).
-
-## Bugs this example avoids
-
-| Broken | Correct |
-| --- | --- |
-| `if (!existing) { return; }` then never create the value | `EnsureStat` **creates** when missing |
-| `if (!money) { money->Value = ... }` | That writes only when the child is **nil** (crash / no-op). Set when the child **exists** |
-| `DataService.Get` before `WaitFor` on join | `WaitFor` in `SetupPlayer`, `Get` in the refresh path |
-| `int main()` | `void init()` |
-| One global connection, never removed | Section janitor destroyed on `PlayerRemoving` |
-
-`Paths.Currencies` is valid **after** your Template was passed to `Init`. The library header does not define those fields.
-
-## IntValue vs StringValue
-
-Use `IntValue` if you want the default numeric sort and no abbreviation. Use `StringValue` + `FormatNumber::Abbreviate` for `1.5K`. Do not mix both names (`Money` twice).
+`init()` constructs `LeaderstatsServer`, assigns `janitor = new Janitor()`, runs `PlayerEntered` for everyone already in the game, then `PlayerAdded` + `BindToClose`. Full listing is on the [handbook page](https://kartzrbx.github.io/Cluaupp/docs/leaderstats.html).

package/docs/getting-started.md

@@ -93,7 +93,7 @@ void init() {
 
 This becomes `Vector3.new`, `CFrame.lookAt`, `Color3.fromRGB`, `UDim2.fromScale`, `Enum.Material.Plastic`.
 
-Full reference (every class from [create.roblox.com](https://create.roblox.com/docs/reference/engine)): [Cluaupp GitHub Pages](https://kartzrbx.github.io/Cluaupp/).
+How to spell engine calls: [Roblox in Cluaupp](https://kartzrbx.github.io/Cluaupp/docs/engine.html). Official members: [create.roblox.com](https://create.roblox.com/docs/reference/engine). The complete subset: [Language reference](https://kartzrbx.github.io/Cluaupp/docs/reference.html).
 
 ## How to write
 
@@ -130,7 +130,7 @@ If a file defines `void init()`, Cluaupp calls `init()` at the end of the `.luau
 cluaupp intellisense
 ```
 
-`#include <cluaupp/roblox.hpp>` at the top of each source file. The header is **not** compiled to Luau. clangd learns that path from `-Iinclude` in `.clangd`, `compile_flags.txt`, and `compile_commands.json` — it does not read `c_cpp_properties.json`.
+`#include <cluaupp/roblox.hpp>` at the top of each source file. The header is **not** compiled to Luau. clangd learns that path from `-Iinclude` in `.clangd`, `compile_flags.txt`, and `compile_commands.json`.
 
 See [IntelliSense](intellisense.md).
 
@@ -163,6 +163,8 @@ See [Libraries](libraries/index.md), [OOP](oop/index.md), [types](cpp-types.md),
 
 ## Next
 
+Language handbook (GitHub Pages): **[Docs](https://kartzrbx.github.io/Cluaupp/docs/)** — [every construct](https://kartzrbx.github.io/Cluaupp/docs/reference.html).
+
 - [C++ → Luau syntax](syntax.md)
 - [print and cout](print-cout.md)
 - [C++ types](cpp-types.md)

package/docs/intellisense.md

@@ -6,12 +6,12 @@ C++ completion, hover, and go-to-definition are **clangd**. Cluaupp does not shi
 
 1. [clangd](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd) (`llvm-vs-code-extensions.vscode-clangd`)
 2. LLVM `clang++` when missing (Windows: `winget install --id LLVM.LLVM -e`)
-3. `.clangd`, `compile_flags.txt`, and `compile_commands.json` so clangd finds `include/` (clangd does **not** read `.vscode/c_cpp_properties.json`)
+3. `.clangd`, `compile_flags.txt`, and `compile_commands.json` so clangd finds `include/`
 4. Forced include of `include/cluaupp/roblox.hpp` so `GetService`, `Player`, `Janitor` complete from the real C++ stubs
 
 Tree-sitter is the **compiler** frontend (collect → emit Luau). It is not an editor language server. A homemade tokenizer in the CLI would fight clangd — that path is gone.
 
-Microsoft `ms-vscode.cpptools` is **not** used. Two C++ engines in the same window fight; Cluaupp disables the Microsoft engine (`C_Cpp.intelliSenseEngine: Disabled`).
+Microsoft `ms-vscode.cpptools` is **not** used and is **not licensed for Cursor**. Two C++ engines in the same window fight; Cluaupp recommends only clangd and marks cpptools as unwanted.
 
 `cluaupp lsp` only publishes **subset parse errors** (code that clangd may accept as C++ but Cluaupp will not transpile).
 
@@ -39,9 +39,8 @@ Reload: Command Palette → **Developer: Reload Window**. clangd should attach t
 
 | File | Role |
 | --- | --- |
-| `.vscode/c_cpp_properties.json` | compiler path (unused by clangd; kept if someone re-enables cpptools) |
-| `.vscode/settings.json` | `C_Cpp.intelliSenseEngine: Disabled`, `clangd.enable: true`, `--compile-commands-dir` |
-| `.vscode/extensions.json` | recommends `llvm-vs-code-extensions.vscode-clangd` |
+| `.vscode/settings.json` | `clangd.enable: true`, `--compile-commands-dir` |
+| `.vscode/extensions.json` | recommends `llvm-vs-code-extensions.vscode-clangd`; marks `ms-vscode.cpptools` unwanted |
 | `.clangd` | C++20, `-Iinclude`, skip `out/` and `libs/` |
 | `compile_flags.txt` | fallback flags if a file is not yet in `compile_commands.json` |
 | `compile_commands.json` | one entry per `src/` file |

package/docs/libraries/dataservice.md

@@ -91,9 +91,12 @@ void OnCurrenciesChanged() {
 }
 
 data->GetChangedSignal(DataService::Server.Paths.Currencies).Connect(OnCurrenciesChanged);
+data->GetChangedSignal(DataService::Server.Paths.Currencies.Coins).Connect([](int coins) {
+	print(coins);
+});
 ```
 
-`GetChangedSignal` fires when that path (or a child) changes. Cluaupp has no lambdas — use a named function.
+`GetChangedSignal` fires when that path (or a child) changes. Use a named function or a lambda (`[](int newValue) { ... }`).
 
 ## Rules
 

package/docs/libraries/index.md

@@ -13,7 +13,8 @@ sidebar_position: 1
 | [Janitor](janitor.md) | Connections, instances, cleanup on leave |
 | [Promise](promise.md) | Delay, Then / Catch / Await |
 | [Net](net.md) | RemoteEvent / RemoteFunction without making remotes |
-| [More libraries](more.md) | FormatNumber, Fusion, Cmdr, Twinkle, MathUtils, … |
+| [Declarative UI](ui.md) | Fusion, Iris, Vide, React/Roact — no JSX |
+| [More libraries](more.md) | FormatNumber, Twinkle, TopbarPlus, EzVisualz, … |
 
 Sources: [runtime/SOURCES.md](https://github.com/KartzRbx/Cluaupp/blob/main/runtime/SOURCES.md). Re-vendor: `node scripts/vendor-libs.js`.
 

package/docs/libraries/more.md

@@ -60,7 +60,9 @@ billboard->SetText("Hello");
 
 ## Fusion / Iris / Cmdr / TopbarPlus / Chrono / EzVisualz / StateMachine / Spring / Display
 
-These are the GitHub systems behind typed `init.luau` borders. Include the matching `<cluaupp/libs/*.hpp>` and call the same names as the upstream README. Cluaupp does not re-document every Fusion `Value` / Cmdr command — use:
+Cluaupp has **no JSX**. Declarative UI is function calls. First-party: Fusion (reactive) and Iris (immediate-mode debug). Vide and Roact/React use the same C++ spelling (`createElement` / `source`), not `<frame />`. Handbook: [Declarative UI](https://kartzrbx.github.io/Cluaupp/docs/ui.html).
+
+Include the matching `<cluaupp/libs/*.hpp>` and call the same names as the upstream README:
 
 | Lib | Header | Upstream |
 | --- | --- | --- |

package/docs/libraries/ui.md

@@ -0,0 +1,76 @@
+---
+title: Declarative UI
+sidebar_position: 5
+---
+
+# Declarative UI
+
+Live handbook (examples, C++ / Luau tabs): **[Declarative UI](https://kartzrbx.github.io/Cluaupp/docs/ui.html)**.
+
+roblox-ts can compile [Roact JSX](https://roblox-ts.com/docs/guides/roact-jsx) because TypeScript has JSX. **Cluaupp does not.** There are no `<frame />` tags. You call the library the way Luau does: functions, designated-initializer tables, lambdas.
+
+## Pick a model
+
+| When you want… | Use | In Cluaupp |
+| --- | --- | --- |
+| A few labels you set by hand | Imperative Instances | `new TextLabel(gui)` |
+| UI that follows state | [Fusion](https://github.com/dphfox/Fusion) | Shipped: `#include <cluaupp/libs/fusion.hpp>` |
+| The same idea, sources | [Vide](https://github.com/centau/vide) | Not shipped — calling convention on the handbook |
+| A virtual tree | Roact / [jsdotlua React](https://github.com/jsdotlua/react) | Not shipped — `createElement`, never JSX |
+| Studio debug panels | [Iris](https://github.com/SirMallard/Iris) | Shipped: `#include <cluaupp/libs/iris.hpp>` |
+| Topbar / fade / rainbow | TopbarPlus, Twinkle, EzVisualz | Shipped — polish Instances you already have |
+
+Fusion and Iris are in CluauppLibs. Vide and React/Roact are **not** vendored.
+
+## JSX → Cluaupp
+
+| roblox-ts JSX | Cluaupp |
+| --- | --- |
+| `<frame Size={u} />` | `React::createElement("Frame", { .Size = u })` |
+| `<textlabel Key="Coins" />` | `.Key = "Coins"` on the props table |
+| `Event={{ Activated: fn }}` | `.Event = { .Activated = fn }` |
+| `<MyButton text="Buy" />` | `React::createElement(MyButton, { .text = "Buy" })` |
+
+## Fusion (shipped)
+
+```cpp
+#include <cluaupp/libs/fusion.hpp>
+
+FusionScope scope = Fusion::scoped();
+FusionState coins = Fusion::Value(0);
+Fusion::New("TextLabel")({
+	.Name = "Coins",
+	.Parent = gui,
+	.Size = UDim2::fromScale(1, 0.1),
+});
+```
+
+Wire `coins(newValue)` from `DataService::Client` `GetChangedSignal(Paths.Currencies.Coins)`. Use `Computed` for strings, `Hydrate` for a ScreenGui that already exists in Studio, `Spring` / `Tween` for motion.
+
+## Vide / React
+
+Same subset: **no JSX**. Vide is `source` / `derive` / `create("TextLabel")({ .Parent = gui })`. React is `createElement("Frame", { .Key = "Child" }, child)` plus `Key`, `Ref`, `Change`, `Event` as table fields. Full copies with C++ / Luau tabs: the [handbook page](https://kartzrbx.github.io/Cluaupp/docs/ui.html).
+
+## Iris (shipped, debug only)
+
+```cpp
+#include <cluaupp/libs/iris.hpp>
+
+void DrawEconomy() {
+	if (Iris::Window("Economy")) {
+		Iris::Text("Coins");
+		Iris::End();
+	}
+}
+
+void init() {
+	Iris::Init();
+	Iris::Connect(DrawEconomy);
+}
+```
+
+Do not use Iris as the live player HUD. Pair every `Window` / `Tree` with `End()`.
+
+## One owner per ScreenGui
+
+Do not mount Fusion and React on the same gui. Twinkle / TopbarPlus / EzVisualz can decorate that owner’s Instances. Client code must not `Set` persisted DataService paths.

package/docs/oop/index.md

@@ -3,15 +3,28 @@ title: OOP structure
 sidebar_position: 1
 ---
 
-# OOP structure
+# Structs and methods
 
-The **live site** (not just these markdown files) is GitHub Pages:
+Live handbook: [Structs and methods](https://kartzrbx.github.io/Cluaupp/docs/structs.html). Singletons: [one table in `init()`](https://kartzrbx.github.io/Cluaupp/docs/singletons.html).
 
-- [Learn → OOP structure](https://kartzrbx.github.io/Cluaupp/learn/index.html)
-- [Guide → OOP](https://kartzrbx.github.io/Cluaupp/guide/oop.html)
-- [Examples](https://kartzrbx.github.io/Cluaupp/guide/examples.html)
+Cluaupp does **not** emit C++ `class` metatables. You write a **type** as a `struct` in a sibling header and implement `Class::Method` in the `.cpp`. Filename tags still decide Script / LocalScript / ModuleScript.
 
-Cluaupp does **not** compile custom C++ `class` types yet. “OOP” here is how you **lay out systems** so Studio gets Script / LocalScript / ModuleScript from the filename tag — the same idea as roblox-ts. Flamework-style Start/Stop folders are opt-in (`"architecture": true`).
+Construct **one** `LeaderstatsServer` in `void init()`, assign `janitor = new Janitor()`, and capture it in `[&]` lambdas. Library singletons already exist (`DataService::Server`) — `Init` once from a boot script. Join strings with `string_concat` or string `+`, not Luau `..`.
+
+```cpp
+#pragma once
+#include <cluaupp/roblox.hpp>
+#include <cluaupp/libs/janitor.hpp>
+
+struct LeaderstatsServer {
+	static constexpr int STARTING_COINS = 0;
+	Janitor* janitor;
+	string GetPlayerJanitorKey(Player* player);
+	void PlayerEntered(Player* player);
+};
+```
+
+The stem must match: `LeaderstatsServer.h` next to `LeaderstatsServer.server.cpp`. `#include "leaderstats.h"` from a differently named cpp is a `require`, not the class body.
 
 | Page | What you learn |
 | --- | --- |
@@ -19,4 +32,4 @@ Cluaupp does **not** compile custom C++ `class` types yet. “OOP” here is how
 | [Services](services.md) | One `.server.cpp` → one `.server.luau` |
 | [Modules](modules.md) | Untagged files, structs, named functions as methods |
 
-Planner details: [Architecture](../architecture.md). Folder layout: [Organization](../cpp-organization.md). Full services: [Examples](../examples/index.md).
+Planner: [Architecture](../architecture.md). Folder layout: [Organization](../cpp-organization.md). Full copy: [Leaderstats](../examples/leaderstats.md).

package/docs/roblox-api.md

@@ -1,16 +1,10 @@
 # Roblox API
 
-Cluaupp covers the engine API listed on [create.roblox.com](https://create.roblox.com/docs/reference/engine): **925 classes**, **636 enums**, and the datatypes (`Vector3`, `CFrame`, `UDim`, `UDim2`, …).
+Cluaupp uses the official engine. Spell the call in C++; look up members on [create.roblox.com](https://create.roblox.com/docs/reference/engine). The GitHub Pages site is a **language handbook**, not a dump of every Enum item.
 
-The **page-by-page** reference (every property, method, and event, with C++ and Luau) lives on the generated site:
+Handbook: **[Docs](https://kartzrbx.github.io/Cluaupp/docs/)** · [Roblox in Cluaupp](https://kartzrbx.github.io/Cluaupp/docs/engine.html)
 
-**[Cluaupp docs (GitHub Pages)](https://kartzrbx.github.io/Cluaupp/)**
-
-- [Datatypes](https://kartzrbx.github.io/Cluaupp/api/datatypes/)
-- [Classes](https://kartzrbx.github.io/Cluaupp/api/classes/)
-- [Enums](https://kartzrbx.github.io/Cluaupp/api/enums/)
-
-In C++, `#include <cluaupp/roblox.hpp>`. The compiler ignores the header and emits real Luau.
+`#include <cluaupp/roblox.hpp>` is IntelliSense. The compiler ignores the header and emits real Luau.
 
 ## Datatypes
 
@@ -20,7 +14,6 @@ part->Position = Vector3(0, 10, 0);
 part->CFrame = CFrame::lookAt(Vector3(0, 10, 0), Vector3(0, 10, -10));
 part->Color = Color3::fromRGB(255, 0, 0);
 frame->Size = UDim2::fromScale(1, 1);
-frame->Position = UDim2(0, 0, 0.5, 0);
 auto material = Enum::Material::Plastic;
 ```
 
@@ -30,52 +23,7 @@ part.Position = Vector3.new(0, 10, 0)
 part.CFrame = CFrame.lookAt(Vector3.new(0, 10, 0), Vector3.new(0, 10, -10))
 part.Color = Color3.fromRGB(255, 0, 0)
 frame.Size = UDim2.fromScale(1, 1)
-frame.Position = UDim2.new(0, 0, 0.5, 0)
 local material = Enum.Material.Plastic
 ```
 
-| C++ | Luau |
-| --- | --- |
-| `Vector3(x, y, z)` | `Vector3.new(x, y, z)` |
-| `Vector2(x, y)` | `Vector2.new(x, y)` |
-| `CFrame(x, y, z)` | `CFrame.new(x, y, z)` |
-| `CFrame::lookAt(from, look)` | `CFrame.lookAt(from, look)` |
-| `UDim(scale, offset)` | `UDim.new(scale, offset)` |
-| `UDim2(xs, xo, ys, yo)` | `UDim2.new(xs, xo, ys, yo)` |
-| `UDim2::fromScale(x, y)` | `UDim2.fromScale(x, y)` |
-| `UDim2::fromOffset(x, y)` | `UDim2.fromOffset(x, y)` |
-| `Color3::fromRGB(r, g, b)` | `Color3.fromRGB(r, g, b)` |
-| `Color3::fromHSV(h, s, v)` | `Color3.fromHSV(h, s, v)` |
-| `BrickColor("Bright red")` | `BrickColor.new("Bright red")` |
-| `Enum::Material::Plastic` | `Enum.Material.Plastic` |
-| `Rect(x0, y0, x1, y1)` | `Rect.new(x0, y0, x1, y1)` |
-| `Ray(origin, direction)` | `Ray.new(origin, direction)` |
-| `NumberRange(min, max)` | `NumberRange.new(min, max)` |
-| `TweenInfo(time, style)` | `TweenInfo.new(time, style)` |
-
-## Instances and services
-
-```cpp
-auto* part = new Part(workspace);
-auto* players = GetService<Players>();
-player->FindFirstChild("leaderstats");
-players->GetPlayers();
-```
-
-```luau
-local part: Part = Instance.new("Part")
-part.Parent = workspace
-local players: Players = game:GetService("Players")
-player:FindFirstChild("leaderstats")
-players:GetPlayers()
-```
-
-`new Class(parent)` is for creatable classes (`Instance.new`). Services use `GetService<Name>()`.
-
-Generated headers (official client dump):
-
-- `include/cluaupp/datatypes.hpp`
-- `include/cluaupp/generated/enums.hpp`
-- `include/cluaupp/generated/instances.hpp`
-
-To regenerate: `npm run generate-api` in the `cluau/` folder.
+Every enum is `Enum::Name::Item` → `Enum.Name.Item`. Services are `GetService<Players>()`. Instances are `new Folder(parent)` and `player->FindFirstChild("x")`.