cluaupp 0.2.2 → 1.0.0

package/CHANGELOG.md

@@ -1,81 +1,20 @@
 # Changelog
 
-## Unreleased
+## 1.0.0
 
-## 0.2.2
+Breaking: Cluaupp no longer transpiles a C++ subset. Games are **CL++** (`.clpp` / `.clp` / `.clh`). The CLI orchestrates the [`clpp`](https://github.com/KartzRbx/CLPP) binary (`clpp api compile`), post-processes Luau (`ClppLibs` → `ReplicatedStorage.CluauppLibs`), and writes `out/` for Rojo.
 
-- 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`).
+- Requires `clpp` on PATH (`CLPP_PATH` override). Language, IntelliSense, and codegen live in CL++ (`clpp install`).
+- `cluaupp language` prints `clpp api manifest`.
+- Templates and `examples/game` use CL++ syntax (`guard`, `match`, `signal`, `.:`, `::`, Fusion).
+- Docs site and README are CL++ × Luau (no clangd / `.cpp` toolchain).
+- Tree-sitter C++ frontend removed. ForeverHD `"architecture": true` folder split is not implemented on this path.
+- See [migration](docs/migration.md) and [CL++ docs](https://kartzrbx.github.io/CLPP/).
 
-## 0.2.1
+## 0.2.3
 
-- Pin `tree-sitter` 0.21.1 and `tree-sitter-c` 0.23.2 so `npm i -g cluaupp` no longer pulls `tree-sitter-c@0.23.6` (peerOptional `tree-sitter@^0.22.1`).
-
-## 0.2.0
-
-- CLI rewritten as a TypeScript collector-emitter pipeline: Tree-sitter collection, Rojo-mapped `require`s, ordered Luau blocks (Services → Requires → Types → Constants → Code), then optional StyLua / `luau-analyze`. Commands `init`, `build`, `watch`, `lsp`, and `intellisense` stay. `cluaupp build -i file.cpp -o out.luau --rojo default.project.json` is the single-file path.
-- C++ IntelliSense is **clangd** only. The old tokenizer/`completeAt` engine is gone. Tree-sitter is the compiler frontend. `cluaupp lsp` publishes subset parse errors only.
-- `SystemUnderstander` scans identifiers, scores Roblox intents, and stamps Controller / Manager / utility plus `GetService` injections. Filename tags still decide Script vs LocalScript vs ModuleScript.
-- Sample game C++ lives in `examples/game/` (`src/server`, `src/client`, `src/shared`). Compiler `src/` is TypeScript only.
-- CLI security: StyLua / luau-analyze via `spawn` without a shell; emitted paths cannot leave the project; `.env*` stays out of git and the npm pack.
-- Docs / GitHub Pages: clangd, SystemUnderstander, one-file-out emit, `examples/game`. Rojo **7.7.0**.
-- Tests cover `out/` tree, types, modules, path safety, and understander roles.
-
-## 0.1.5
-
-- Default emit is one tagged `.cpp` → one `.server.luau` / `.client.luau`. `"architecture": true` keeps the old ForeverHD service folders.
-- `--!strict` is opt-in: `#pragma strict`, `#pragma nstrict`, or `"strict": true` in config (default `false`).
-- `.h` / `.hpp` emit type ModuleScripts (`export type` + typed table). A sibling `.cpp` becomes `*Impl.luau`; the header binds those functions.
-- Shared `#include` modules `require` game-rooted paths (`ReplicatedStorage.Cluaupp...` / `ServerScriptService.Cluaupp...`).
-
-## 0.1.4
-
-- Quoted `#include "Header.h"` of project files becomes `const Header = require(...)`. Header-only structs emit a constructor (`TemplateData()`); const headers bind `PLAYER_DATA_VERSION` from the module. Boot scripts require services (`LeaderstatsServer:init()`).
-- Keep `const` for injected `require` / `GetService` and `const function` for C++ functions (not `local`).
-- `init.meta.json` stays pure JSON. Library `require` injection no longer prepends Luau onto Rojo meta files (which made `rojo serve` fail with a JSONC parse error).
-- Server services emit `init.server.luau` + `init.meta.json` with **only** `RunContext.Server`. Rojo forbids `className` when an `init.*` script exists (the folder is already a Script, not a Folder). `init.luau` is pruned so the instance is not a ModuleScript.
-
-## 0.1.3
-
-- Architecture: generated services keep a fixed declaration order (requires, types, constants, variables, functions, cleanup, return) without section banners. Domain `Stop` runs `janitor:Cleanup()`.
-- IntelliSense: `cluaupp init` / `cluaupp intellisense` install Microsoft `ms-vscode.cpptools` (VSIX on Cursor, where the marketplace omits it), write `.vscode/c_cpp_properties.json` (LLVM clang++, C++20, `include/` + `src/`, `compile_commands.json`), and disable clangd so the two engines do not fight. `build`/`watch` only refresh `compile_commands.json`.
-- `Class::method` on game types becomes `Class:method()` (`self`). Datatype/library statics stay dotted (`CFrame.lookAt`, `Color3.fromRGB`, `FormatNumber.Abbreviate`).
-- `switch` / `case` / `default` / `break` compile to a one-shot `repeat` with `if` / `elseif` / `else`. The discriminant is evaluated once; stacked `case` labels share a body; `break` leaves the switch even from inside an `if`.
-- Janitor typed border re-exports `_impl` (`export type Janitor = Impl.Janitor; return Impl`). It no longer invents `Has` or requires Promise for a parallel type that did not match howmanysmall.
-- Emit: injected `require` / `GetService` are `const`. C++ functions emit as `const function` instead of `local function`.
-- `.server.cpp` emits `init.luau` + `init.meta.json` with `RunContext.Server`. `init.server.luau` is Legacy and is pruned.
-- `cout << ... << endl` emits `print(...)`. `cerr <<` emits `warn`. `cout::print` / `cout::warn` / `cout::error` / `cout::ping` map to the Roblox globals.
-- Docs: [print and cout](docs/print-cout.md); [Libraries](docs/libraries/index.md) how-tos (DataService Init, Janitor, Promise, Net); [OOP structure](docs/oop/index.md) (file tags, services, modules); [Examples](docs/examples/index.md) (leaderstats, combat validation, shop, HUD, sword). GitHub Pages Learn tabs: OOP, Libraries, print/cout, Examples — generated into `site/` (`guide/oop.html`, `guide/examples.html`).
-
-## 0.1.2
-
-- Watch does not write `out/` while any file fails to compile (Studio keeps the last good scripts).
-- Watch/build skip rewriting Luau whose contents did not change (a space in C++ no longer floods Rojo).
-- Watch never copies `libs/` or headers. Changing a constant no longer makes Rojo 7 crash on `libs/ArrayIndexer`.
-- `libs/` on `cluaupp build` is fill-only: missing files are restored, existing files are never overwritten or deleted.
-- Filename tags: `.server.cpp` → Script (`init.server.luau`), `.client.cpp` → LocalScript (`init.client.luau`), `.plugin.cpp` → Plugin, `.legacy` / `.legacy.client` / `.legacy.server` → Legacy. Bare `init.luau` is not used for `.server` (Rojo would make a ModuleScript).
-- Dropped `$optional` from `default.project.json` (Rojo 7.7 failed to deserialize it).
-
-## 0.1.1
-
-- DataService: `DataServiceOptions<T>.Template` is the required player-data table (`T` matches the save struct). Also documents `Exclude`.
-- Compiler: C++ designated initializers (`Type { .Field = value }`) emit Luau tables, so `DataService.Server:Init({ Template = ... })` type-checks and compiles.
-- Watch/build: delete orphaned `out/` files when a source is removed. Never wipe `out/` or `libs/` as a whole — Rojo 7 crashes if `libs/ArrayIndexer` disappears mid-serve. Vendor files are only created if missing; existing `libs/` is never overwritten on watch/build. Watch skips writing `out/` when compile fails, and skips rewriting Luau whose contents did not change.
-
-## 0.1.0
-
-- Product name: **Cluaupp** (C++ × Luau)
-- First public release
-- CLI: `init`, `build`, `watch`, `--version`
-- Transpile C++ subset → Luau `--!strict`
-- `local` and `const x = ...`
-- Full Roblox API from the official dump (925 classes, 636 enums)
-- Datatypes: Vector3, Vector2, CFrame, UDim, UDim2, Color3, BrickColor, Rect, Ray, …
-- `Enum::Material::Plastic` → `Enum.Material.Plastic`
-- GitHub Pages site for every class, method, and event
-- Game template + IntelliSense header (`roblox.hpp`, `compile_flags.txt`, clangd)
-- IntelliSense headers are valid C++: `LuaArray` for `GetPlayers`, templated `Connect`, optional dump defaults (`FindFirstChild`), no recursive `Vector3.Unit` field
-- Libraries: full GitHub systems in CluauppLibs (Janitor, Promise, Fusion, Iris, Cmdr, TopbarPlus, Chrono, DataServiceV2, EzVisualz, StateMachine, Spring, Display, Module3D, FormatNumber) plus Cluaupp originals (Net, MathUtils, Twinkle, StickyBillboard, VfxUtil)
-- Wally is optional; `node scripts/vendor-libs.js` re-copies from `vendor/` clones
-- Moonwave docs (C++ types, const, safety, organization)
-- Service architecture: filename tags (`.server` / `.client` / `.legacy.*` / module) plus AST intent scoring (combat, cache, players, …) — not leaderstats-only
-- Type functions ArrayIndexer (`Table`) and Occlude (`Keys`) in CluauppLibs
+- 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.

package/README.md

@@ -4,117 +4,71 @@
   <img src="site/assets/logo.png" alt="Cluaupp" width="160">
 </p>
 
-**The definitive merge of C++ and modern Luau.**
+**CL++ games on Roblox.** You write [CL++](https://kartzrbx.github.io/CLPP/). Cluaupp runs `clpp`, wires Rojo, and copies CluauppLibs.
 
-[Docs](https://kartzrbx.github.io/Cluaupp/) · [Learn](https://kartzrbx.github.io/Cluaupp/learn/) · [API](https://kartzrbx.github.io/Cluaupp/api/classes/)
+[CL++ language](https://kartzrbx.github.io/CLPP/) · [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)
-[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-
-Source-to-source transpiler: you write a C++ subset, Cluaupp emits modern [Luau](https://luau.org/getting-started) (`local`, `const`, optional `--!strict`). C++ structure, Luau quality, one language.
-
-No WASM. No Emscripten. No `lua_call`. Roblox APIs come out as they do in Studio: `game:GetService("Players")`, `player:FindFirstChild("leaderstats")`, `players:GetPlayers()`.
-
-```cpp
-auto* players = GetService<Players>();
-for (auto* player : players->GetPlayers()) {
-	CreateLeaderstats(player);
+[![License: MIT](https://img.shields.io/badge/license-MIT-white.svg)](LICENSE)
+
+Cluaupp is the **toolchain**, not the language compiler. [KartzRbx/CLPP](https://github.com/KartzRbx/CLPP) owns syntax, IntelliSense (`clpp install`), and Luau codegen. This CLI finds `.clpp` / `.clp` / `.clh`, runs `clpp api compile`, rewrites `ClppLibs` → `ReplicatedStorage.CluauppLibs`, and writes `out/` for Rojo.
+
+```clpp
+#include <clpp/roblox.clh>
+#include <clpp/libs/janitor.clh>
+
+void init() {
+	Players* players = GetService<Players>();
+	players::PlayerAdded~>Connect(func [](Player* player) {
+		guard (player != null) else {
+			return;
+		}
+		post("hello, " .: player.Name);
+	});
 }
-players->PlayerAdded.Connect(CreateLeaderstats);
-
-auto* part = new Part(workspace);
-part->Size = Vector3(8, 1, 8);
-part->CFrame = CFrame::lookAt(Vector3(0, 10, 0), Vector3(0, 10, -10));
-frame->Size = UDim2::fromScale(1, 1);
-```
-
-becomes
-
-```luau
---!strict
-local players: Players = game:GetService("Players")
-for _, player in players:GetPlayers() do
-	CreateLeaderstats(player)
-end
-players.PlayerAdded:Connect(CreateLeaderstats)
 ```
 
 ## Install
 
-Node.js 18+ and [Rojo](https://rojo.space/) **7.7.0** for Studio sync (`rokit.toml` in the game template).
+1. [Node.js](https://nodejs.org/) 18+
+2. [Rojo](https://rojo.space/) **7.7.0**
+3. **`clpp` on PATH** from [CL++](https://github.com/KartzRbx/CLPP) (`cargo install --path .`)
 
 ```bash
 npm install -g cluaupp
-```
-
-Or run without a global install:
-
-```bash
+clpp install
 npx cluaupp init my-game
-```
-
-## Quick start
-
-```bash
-cluaupp init my-game
 cd my-game
 rokit install
 cluaupp build
 rojo serve
 ```
 
-Connect the Rojo plugin in Roblox Studio. Edit `src/**/*.{cpp,h,hpp}`, run `cluaupp watch` to rebuild on save.
+| Source | Output | Rojo |
+| --- | --- | --- |
+| `*.server.clpp` | `*.server.luau` | Script |
+| `*.client.clpp` | `*.client.luau` | LocalScript |
+| `*.clp` / untagged `.clpp` | `*.luau` | ModuleScript |
+| `*.clh` | `*.luau` | ModuleScript |
 
-C++ autocomplete is **clangd**, not a Cluaupp tokenizer and not Microsoft cpptools. Put `#include <cluaupp/roblox.hpp>` at the top of each script; `cluaupp init` writes `.clangd` / `compile_flags.txt` / `compile_commands.json` with `-Iinclude` so clangd finds that header. Tree-sitter is only used to compile. See [IntelliSense](docs/intellisense.md).
+## CLI
 
-```
-src/server/*.server.cpp  →  out/server/*.server.luau  Script
-src/client/*.client.cpp  →  out/client/*.client.luau  LocalScript
-src/shared/*.cpp         →  out/shared/*.luau         ModuleScript
+```bash
+cluaupp init [folder]
+cluaupp build [folder]
+cluaupp watch [folder]
+cluaupp language          # clpp api manifest
+cluaupp intellisense      # files.associations + clpp install
 ```
 
-Filename tags: `.server.cpp`, `.client.cpp`, `.legacy.server.cpp`, `.legacy.client.cpp`, or no tag (ModuleScript). One source file becomes one instance. Set `"architecture": true` only for the old PascalCase folder split. See [Architecture](docs/architecture.md) and [OOP structure](docs/oop/index.md).
-
-Compiler TypeScript lives in `src/`. Sample game C++ is [`examples/game`](examples/game) (`src/server`, `src/client`, `src/shared`). `cluaupp init` still copies [`templates/game`](templates/game).
-
-## Documentation
-
-| Guide | What it covers |
-| --- | --- |
-| [Getting started](docs/getting-started.md) | Install, first project, Rojo, IntelliSense |
-| [**Docs + API (GitHub Pages)**](https://kartzrbx.github.io/Cluaupp/) | Site, Learn tab, every class / datatype / enum |
-| [Learn](https://kartzrbx.github.io/Cluaupp/learn/) | C++ subset, Luau output, safety, architecture |
-| [CLI](docs/cli.md) | `init`, `build`, `watch`, flags |
-| [Syntax](docs/syntax.md) | C++ subset → Luau (`local`, `const`, types) |
-| [print and cout](docs/print-cout.md) | `cout <<`, `cout::warn`, `endl` |
-| [Roblox API](docs/roblox-api.md) | Vector3, CFrame, UDim2, GetService, Instance.new |
-| [Architecture](docs/architecture.md) | One file in, one file out; opt-in ForeverHD folders |
-| [OOP structure](docs/oop/index.md) | File tags, services, modules, structs |
-| [Libraries](docs/libraries/index.md) | DataService Init, Janitor, Promise, Net |
-| [Examples](docs/examples/index.md) | Leaderstats, combat validation, shop, HUD, sword |
-| [C++ types](docs/cpp-types.md) | Typing, `const`, safety, organization |
-| [Comparison](docs/comparison.md) | vs roblox-ts and WASM toolchains |
-| [Contributing](CONTRIBUTING.md) | Tests, layout, how to ship |
-
-## Programmatic API
-
-```js
-const { compileSource, compileService } = require("cluaupp");
-
-const luau = compileSource(
-	`void init() { print("ok"); }`,
-	"init.cpp",
-	{ strict: true },
-);
-
-const service = compileService(
-	cppSource,
-	"server/leaderstats.server.cpp",
-	{ relativeName: "server/leaderstats.server.cpp" },
-);
-// service.files → LeaderStats/Main.luau, PlayersManager, CacheController, Types
-```
+`clpp` missing? Set `CLPP_PATH` or install [CL++](https://github.com/KartzRbx/CLPP).
+
+## Language
+
+Course and reference: **[kartzrbx.github.io/CLPP](https://kartzrbx.github.io/CLPP/)**.
+
+Exclusive CL++ (`guard`, `match`, `signal`, `observable`, `.:`, `::`, `~>`, Fusion) is compiled by `clpp`. Samples: [`examples/game`](examples/game). Old C++ games: [docs/migration.md](docs/migration.md).
 
 ## License
 

package/docs/README.md

@@ -1,23 +1,27 @@
 # Cluaupp documentation
 
-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/)**
+The live handbook is **[GitHub Pages](https://kartzrbx.github.io/Cluaupp/docs/)**. Language course: **[CL++](https://kartzrbx.github.io/CLPP/)**.
+
+## Start
+
+1. [Intro](intro.md)
+2. [Getting started](getting-started.md)
+3. [CLI](cli.md)
+4. [Config](config.md)
+5. [IntelliSense](intellisense.md) — `clpp install`
+6. [Migration](migration.md) — `.cpp` → `.clpp`
+
+## Language
+
+Syntax lives in CL++. Cluaupp [syntax](syntax.md) is a short map of operators and file tags.
+
+## Structure
+
+- [Architecture](architecture.md) — one file in, one file out
+- [OOP / file tags](oop/file-tags.md)
+
+## Roblox
+
+- [Libraries](libraries/index.md)
+- [Examples](examples/index.md)
+- [Comparison](comparison.md)

package/docs/architecture.md

@@ -5,88 +5,25 @@ sidebar_position: 15
 
 # One file in, one file out
 
-roblox-ts decides **what instance you get** from a filename **key** (the same idea as Rojo). Cluaupp does the same — and **stops there** by default. It does not invent Main / Controller / Types folders.
+roblox-ts decides **what instance you get** from a filename **key**. Cluaupp does the same for **CL++**.
 
 | Key | Rojo instance | Default output |
 | --- | --- | --- |
-| `*.server.cpp` | Script | `*.server.luau` |
-| `*.client.cpp` | LocalScript | `*.client.luau` |
-| no suffix | ModuleScript | `Name.luau` |
-| `*.legacy.server.cpp` | Legacy Script | `*.server.luau` |
-
-`DataBoot.client.cpp` becomes `out/client/boot/DataBoot.client.luau` with your `init()` at the end. Shared `#include` modules use `require(ReplicatedStorage.Cluaupp...)`.
-
-`--!strict` is opt-in: put `#pragma strict` in the `.cpp`, or set `"strict": true` in `cluaupp.config.json`.
-
-The ForeverHD-style folder split (`LeaderStats/Main.luau`, …) is **opt-in**: `"architecture": true`.
-
-## SystemUnderstander
-
-Like [roblox-ts](https://github.com/roblox-ts/roblox-ts) (filename **key** first) and [roblox-cs](https://github.com/roblox-csharp/roblox-cs) (scan the AST, then decide), Cluaupp does **not** call a generative model. `src/system-understander.ts` walks the Tree-sitter tree, scores token density against Roblox engine services, and returns a report the emitter may stamp as comments / extra `GetService` lines.
-
-| Step | What happens |
-| --- | --- |
-| `parseFileTag` | `.server.cpp` → Script / Server, `.client.cpp` → LocalScript / Client, no tag → ModuleScript |
-| `namesIn` | identifiers, `GetService<T>`, `new Class`, string literals |
-| `scoreIntents` | evidence count × side weight (server tokens count more on `.server.cpp`) |
-| `determineArchitecture` | score &lt; 2 → utility Module; otherwise Knit-style Controller / Manager / Service. `players` / `cache` stay supporting if combat, UI, or net already has ≥ 2 tokens |
-
-The **Rojo class never changes** because of a role. A HUD LocalScript can be classified as `ViewController` and still emit `hud.client.luau`. Sample sources: [examples/game](../examples/game).
-
-## Compiler pipeline
-
-Cluaupp does not rewrite C++ as text. The CLI parses a Tree-sitter CST, collects symbols (`GetService<T>()`, `#include`, types, constants), then emits Luau in a fixed order:
-
-1. `game:GetService(...)`
-2. `require(...)` (Rojo `default.project.json` when present)
-3. types
-4. constants
-5. functions / script body
-
-Formatting is delegated to StyLua; type sanity to `luau-analyze`. See [CLI](cli.md).
-
-## File tags
-
-| Source | Meaning | Output |
-| --- | --- | --- |
-| `combat.server.cpp` | **Script** | `combat.server.luau` |
-| `hud.client.cpp` | **LocalScript** | `hud.client.luau` |
-| `tools.plugin.cpp` | **Script** RunContext Plugin | `tools.luau` (legacy plugin tag) |
-| `boot.legacy.server.cpp` | Legacy Script | `boot.server.luau` |
-| `damage.cpp` (no tag) | **ModuleScript** | `Damage.luau` |
-
-## What a tagged file becomes
-
-```
-src/server/leaderstats.server.cpp  →  out/server/leaderstats.server.luau
-src/client/boot/DataBoot.client.cpp  →  out/client/boot/DataBoot.client.luau
-src/shared/damage.cpp  →  out/shared/Damage.luau
-```
-
-Scripts and LocalScripts keep your functions and call `init()` at the end. ModuleScripts return a table. There is no invented Main, Controller, or Types file.
-
-## Opt-in: ForeverHD folders (`"architecture": true`)
-
-Set `"architecture": true` in `cluaupp.config.json` to restore the old planner: PascalCase service folders, `Main` / Managers / Controllers / Types, and `require(script.Main):Start()`. Server folders emit `init.server.luau` plus a **pure JSON** `init.meta.json` with only `RunContext.Server` — never `className`, and never library `require` lines (Rojo 7.7 rejects both).
+| `*.server.clpp` | Script | `*.server.luau` |
+| `*.client.clpp` | LocalScript | `*.client.luau` |
+| `*.plugin.clpp` | Plugin Script | `*.plugin.luau` |
+| `.clp` / untagged `.clpp` | ModuleScript | `Name.luau` |
+| `.clh` | ModuleScript | `Name.luau` |
 
 ```
-filename key  →  server | client | module | legacy
-AST features  →  GetService, Instance.new, methods, identifiers
-intent scores →  combat:2, character:1, …
-roles         →  Main + Managers + Controllers + Types
+src/server/leaderstats.server.clpp  →  out/server/leaderstats.server.luau
+src/client/hud.client.clpp          →  out/client/hud.client.luau
+src/shared/config.clp               →  out/shared/config.luau
+src/shared/PlayerData.clh           →  out/shared/PlayerData.luau
 ```
 
-| Evidence in the C++ | Role |
-| --- | --- |
-| `PlayerAdded`, `GetPlayers` | `PlayersManager` (Janitor) |
-| `Folder` + `IntValue` / `StringValue` | `CacheController` |
-| `TakeDamage`, `Humanoid`, `Raycast` | `CombatController` (your functions) |
-| `UserInputService`, `InputBegan` | `InputController` |
-| `RemoteEvent`, `Net` | `NetController` |
-| `DataStore`, `DataService` | `DataController` |
-| Domain shapes / stats | `{Service}Types` (`export type`, `return {}`) |
-| Wiring | `Main.Start` / `Main.Stop` |
+`"architecture": true` (ForeverHD `Main` / Managers folders) is **not** generated in Cluaupp 1.0. `clpp` compiles each file; this CLI maps libraries and writes `out/`.
 
-Switching back to 1:1 deletes the stale `LeaderStats/` / `DataBoot/` folders on the next `cluaupp build`.
+`--!strict` is opt-in: `#pragma strict` or `"strict": true` in `cluaupp.config.json`.
 
-How to **write** a system, tags, and module-style OOP: [OOP structure](oop/index.md). Copy-paste systems: [Examples](examples/index.md). Also [organization](cpp-organization.md) and [comparison](comparison.md).
+Language: [kartzrbx.github.io/CLPP](https://kartzrbx.github.io/CLPP/). File tags: [OOP](oop/file-tags.md).

package/docs/cli.md

@@ -4,88 +4,36 @@
 cluaupp <command> [folder]
 ```
 
-If `[folder]` is omitted, the current directory is used.
-
-The compiler is a **collector-emitter** pipeline: Tree-sitter walks the C++ CST, Rojo maps `#include` to `require`, Luau is emitted in a fixed block order (Services → Requires → Types → Constants → Code), then StyLua / `luau-analyze` can run as post-process.
+Cluaupp orchestrates **CL++ → Luau**. It does not parse the language. `clpp` (on PATH) compiles each `.clpp` / `.clp` / `.clh`; Cluaupp post-processes and writes `out/`.
 
 ## `cluaupp init [folder]`
 
-Creates a game from the template:
-
-- `src/server`, `src/client`, `src/shared`
-- `cluaupp.config.json`
-- `default.project.json` (Rojo)
-- `rokit.toml` (Rojo 7.7.0)
-- `include/cluaupp/roblox.hpp` (IntelliSense)
-- `.vscode/` (clangd)
-
-```bash
-cluaupp init .
-cluaupp init my-game
-```
+Creates `src/server`, `src/client`, `src/shared`, Rojo, `rokit.toml`, and a CL++ scaffold. Then run `clpp install` for editor IntelliSense.
 
 ## `cluaupp build [folder]`
 
-Transpiles `src/**/*.{cpp,h,hpp}` into `out/`. One tagged `.cpp` becomes one Luau instance (`leaderstats.server.luau`, `hud.client.luau`). Shared untagged files become ModuleScripts. Set `"architecture": true` for the old PascalCase service folders.
-
-- `--!strict` only with `#pragma strict`, `"strict": true`, or `--strict` on the single-file path
-- `#include "file.h"` becomes `require(...)` resolved from `default.project.json` when present
-- `#include <cluaupp/roblox.hpp>` is ignored
-- `.h` / `.hpp` emit a type ModuleScript (`export type` + typed table). A sibling `.cpp` becomes `*Impl.luau` (the construction); the header binds those functions.
-- A parse error exits with code 1 and `file:line:column`
-- After emit, **orphans in `out/` are removed** (source deleted → matching Luau deleted). `out/` itself is never wiped, so a running Rojo serve keeps the live tree.
-- `libs/` and `include/cluaupp` are synced by writing missing/changed files only. They are **never** deleted as a folder — Rojo 7 unwrap-crashes if `libs/ArrayIndexer` vanishes while serving.
+Compiles `src/**/*.{clpp,clp,clh}` into `out/`. One tagged file becomes one Luau instance.
 
 ```bash
 cluaupp build
-cluaupp build ./my-game
 cluaupp build --format --analyze
+cluaupp build --input ./src/server/boot.server.clpp --output ./out/boot.server.luau
 ```
 
-### Single file
+`--format` runs StyLua; `--analyze` runs `luau-analyze`.
 
-```bash
-cluaupp build --input ./src/server/boot.server.cpp --output ./out/boot.server.luau --rojo ./default.project.json
-```
-
-`--format` runs StyLua; `--analyze` runs `luau-analyze`. On the single-file path both run by default (warnings if the binaries are missing). On a project build they are opt-in.
+If `clpp` is missing: install [CL++](https://github.com/KartzRbx/CLPP) or set `CLPP_PATH`.
 
 ## `cluaupp watch [folder]`
 
-Runs a compile (without copying `libs/`) and rebuilds when anything under `src/` changes, including deletes. Parse errors are printed; the watcher stays alive and **does not write `out/`** until the project compiles cleanly (Studio keeps the last good scripts). A second watcher in the same game exits. Deleted `.cpp` files prune their `out/` artifacts on the next successful compile.
-
-## `cluaupp lsp [folder]`
+Rebuilds on save. Does not write `out/` while compile fails.
 
-Stdio JSON-RPC for **Cluaupp subset diagnostics** only. Completion, hover, and definitions are clangd.
+## `cluaupp language`
 
-## `cluaupp intellisense [folder]`
+Prints `clpp api manifest` (extensions, tags, operators).
 
-Writes `compile_commands.json`, `.clangd`, and `.vscode` for clangd, and installs LLVM clangd when needed.
+## `cluaupp intellisense` / `cluaupp lsp`
 
-## `cluaupp --version` / `cluaupp -v`
+Delegates to CL++ (`clpp install`). Cluaupp only writes `files.associations` for `clpp`.
 
-Prints the npm package version.
-
-## `cluaupp --help`
-
-Shows usage.
-
-## Suggested npm scripts
-
-```json
-{
-	"scripts": {
-		"build": "cluaupp build",
-		"watch": "cluaupp watch"
-	}
-}
-```
-
-In the Cluaupp development repo:
-
-```bash
-npm run build:cli   # compile the TypeScript CLI
-npm test
-npm run dev         # local gitignored playground in game/ + Rojo
-npm run stop        # stop Rojo
-```
+## `cluaupp --version` / `--help`

package/docs/comparison.md

@@ -2,36 +2,18 @@
 
 ## vs roblox-ts
 
-[roblox-ts](https://roblox-ts.com/) transpiles TypeScript → Luau. Cluaupp is the same idea for C++: one language merge, readable output, quality Roblox APIs.
+[roblox-ts](https://roblox-ts.com/) transpiles TypeScript → Luau. Cluaupp does the same job for **[CL++](https://kartzrbx.github.io/CLPP/)**: one familiar syntax, readable Luau, Roblox APIs as in Studio.
 
-Both are source-to-source. Neither goes through WASM. Generated Luau calls the Roblox API directly.
+`*.server.clpp` → Script, `*.client.clpp` → LocalScript, untagged → ModuleScript.
 
-By default Cluaupp matches that filename key: `*.server.cpp` → one Script, `*.client.cpp` → one LocalScript, untagged → ModuleScript. The ForeverHD folder split is opt-in (`"architecture": true`). See [Architecture](architecture.md).
+## vs C++ → WASM
 
-Current Luau has [`local`, `const`, and `--!strict`](https://luau.org/getting-started). Cluaupp emits `const` from C++ `const`. `--!strict` is opt-in (`#pragma strict` or `"strict": true`).
-
-## vs C++ → WASM → Luau (RBX-CPP / Emscripten)
-
-Compiling real C++ to WASM and translating the binary to Luau works, but the cost shows up in the API:
-
-- Roblox methods become generic calls (`lua_call`, blobs)
-- `GetPlayers()` and `FindFirstChild()` do not come out as they do in Studio
-- Heavy toolchain: Emscripten, CMake, Python, tens of GB of cache
-
-Cluaupp skips that path. You write *script* C++ (the same mental subset as roblox-ts) and the compiler emits readable Luau.
-
-```cpp
-players->GetPlayers()
-player->FindFirstChild("leaderstats")
-GetService<Players>()
-```
-
-is exactly what Studio expects, not a parallel runtime.
+Cluaupp never compiles native C++ or WASM. The language compiler is `clpp` (Rust). This package is init / Rojo / CluauppLibs.
 
 ## When to use what
 
 | Goal | Tool |
 | --- | --- |
 | Game in TypeScript | roblox-ts |
-| Game in C++, clear Roblox API | **Cluaupp** |
-| Full native C++ (templates, STL, engines) | not Cluaupp today |
+| Game in CL++ | **Cluaupp** + [`clpp`](https://github.com/KartzRbx/CLPP) |
+| Language reference | [kartzrbx.github.io/CLPP](https://kartzrbx.github.io/CLPP/) |

package/docs/config.md

@@ -13,19 +13,18 @@ File: `cluaupp.config.json` at the game root (next to `src/`).
 
 | Field | Default | Effect |
 | --- | --- | --- |
-| `rootDir` | `"src"` | Where the `.cpp` / `.h` / `.hpp` files live |
+| `rootDir` | `"src"` | Where `.clpp` / `.clp` / `.clh` live |
 | `outDir` | `"out"` | Where Luau is written |
-| `strict` | `false` | Prefix `--!strict` on generated files (overridden by `#pragma strict` / `#pragma nstrict`) |
-| `architecture` | `false` | If `true`, emit PascalCase service folders (`LeaderStats/Main.luau`, …) instead of one Luau per `.cpp` |
-
-If the file is missing, those defaults apply.
+| `strict` | `false` | Prefix `--!strict` when `clpp` did not already (overridden by `#pragma`) |
+| `architecture` | `false` | Ignored in 1.0 (always one file in, one file out) |
 
 ## Rojo
 
-The template ships `default.project.json` mapping:
+The template maps:
 
 - `out/server` → `ServerScriptService.Cluaupp`
 - `out/client` → `StarterPlayer.StarterPlayerScripts.Cluaupp`
 - `out/shared` → `ReplicatedStorage.Cluaupp`
+- `libs` → `ReplicatedStorage.CluauppLibs`
 
-`*.server.cpp` becomes `*.server.luau` (Script). `*.client.cpp` becomes `*.client.luau` (LocalScript). Untagged files become ModuleScripts.
+`*.server.clpp` → `*.server.luau` (Script). `*.client.clpp` → LocalScript. `.clp` / `.clh` → ModuleScript.

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