cluaupp 1.5.0 → 1.5.2-cf

package/CHANGELOG.md

@@ -2,6 +2,53 @@
 
 ## Unreleased
 
+- **GetService ownership** — `GetService<T>()` is Cluaupp Roblox Target (registry + `CLUAU_SVC001` + Context Safety + header stubs + postprocess normalize). CL++ only forwards a generic call. New `src/target/get-service.ts`; wired into compile + doctor.
+- **Named `import` host support** — Parse/resolve `import { } from` alongside `#include`; Rojo mapper strips `.clh`/`.clpp`; authority + project graph; game-rooted require rewrite for all services; incremental cache fingerprints imported deps; CompileArtifact `nativeHints`/`layoutHints`/`requires`/`optimize` wired through `clpp api compile`.
+- **CL++ 0.8 floor** — `MIN_CLPP_VERSION` raised to **0.8.0** (refuse older `clpp`). Templates/examples use `import { PlayerTemplate } from` for app modules; angle `#include <clpp/…>` stays for prelude. Named `import` host support, `nativeHints`/`layoutHints`/`requires`, docs pages Option/Result + Cluaupp host.
+- **Docs site sync** — Home / Why / Comparison / Benchmarks / Parallel / Typed DataModel / Product pillars / Getting started aligned to shipped platform. New [Studio tools](docs) page. Real measured benches via `scripts/bench-site.cjs` (registry ~700 ms cold; `examples/game` warm cache ~1.5 s vs cold ~3.7 s) with Mermaid charts. Docs chat prompt updated.
+- **SoA / buffer codegen (opt-in)** — `cluaupp optimize --apply --layout` writes `#pragma layout soa` and emits `.cluaupp/generated/soa/*Soa.luau` (`--buffer` packs f32/i32 columns). Build also regenerates SoA for existing pragmas.
+- **Studio debug panel** — CluauppNav dock: selection CL++ path, ScriptContext.Error → CL++ remap, Open IDE.
+- **Studio↔IDE bridge** — `cluaupp bridge` (:3847); VS Code/Cursor polls and opens CL++ files on Studio events.
+- **Authority call-graph** — `CLUAU_AUTH004` transitive Client/Shared → ServerScriptService/ServerStorage via include graph; `cluaupp check-authority`; wired into doctor.
+- **PGO Studio ingest** — `cluaupp profile --ingest <jsonl>` merges playtest hits; `plugins/CluauppNav/ProfileLogger.luau` stub.
+- **Luau stamps** — `-- cluaupp-source:` + `#pragma native` → `--!native` on emit; source maps no longer pruned.
+- **Build** — `cluaupp build` uses async path so `-j/--jobs` applies; `--frozen` honored on async.
+- **Incremental + parallel compile** — `.cluaupp/compile-cache` fingerprints sources; `build --no-incremental`, `-j/--jobs` (async path). Default incremental on.
+- **Optimizer apply + PGO** — `cluaupp optimize --apply` inserts `#pragma native` on numeric-hot fns; `cluaupp profile` + `optimize --profile` ranks advice via `cluaupp.profile.json`.
+- **Project docs** — `cluaupp docs` writes `.cluaupp/PROJECT.md` (DataModel, graph, Flare, advice).
+- **Typed DataModel** — variable-root `WaitForChild` chains (`auto assets = …; assets.WaitForChild(...)`).
+- **Flare** — parse `version N;` / `opt version = N` into schema; conflicts still via doctor/`--frozen`.
+- **Platform analyzers (code)** — Parallel `CLUAU-PAR*`, Authority `CLUAU-AUTH*` + `cluaupp.config.json` rules, component contracts, Optimizer advisor (`cluaupp optimize`), security scan, lifetime heuristics, project graph, Flare version conflicts, file-level source maps on build, `build --frozen`, expanded `target doctor` / `analyze`. Wally thin `cluaupp add`.
+- **Typed DataModel v1 (code)** — Parse Rojo `default.project.json` (+ `$path` filesystem scan) into an instance graph. Compile-time `WaitForChild`/`FindFirstChild` chain validation (`CLUAU_DM_MISSING_CHILD`). CLI: `cluaupp target datamodel`, `target check-datamodel`. Emits `.cluaupp/datamodel-profile.json` + `include/clpp/generated/datamodel.clh`. Wired into `cluaupp build` / compile payload (`datamodelProfilePath`).
+- **Docs — Cluaupp Optimizer** — Philosophy locked: idiomatic CL++; compiler chooses table/SoA/buffer/native/parallel. Buffer ≠ programming model (wire Flare codecs stay separate). Page `architecture/optimizer`, roadmap + product-pillars + libraries index clarified. Modules demos: named `import { … } from`, Wallet/PlayerData, shared `const`.
+- **Docs site** — Splash + Why / Benchmarks / Comparison / **Roadmap** (shipped vs next vs later). Absolute `/…` links rewritten relative for `base: /Cluaupp/`. CL++ version callouts updated to **0.7.0+**. Docs chat system prompt (`api/chat.js`) aligned to 0.7 + Context Safety / registry.
+- **Product architecture (deep)** — Five true differentiators: Semantic / Authority / **Parallel** / DataModel / Performance compilers. Identity set: Typed DataModel + Thread Safety + Remote Contracts + Authority. Do not reinvent LSP/Rojo/debugger.
+- **ThreadSafety in registry** — Normalize dump `ThreadSafety` onto properties/methods/events/callbacks; surface in `lsp-index.json`. Foundation for Parallel Compiler (`CLUAU-PAR*`).
+- **Product architecture** — Canonical doc: Cluaupp = Roblox project host (five pillars, hard CL++/Cluaupp/ecosystem split, killer combo order). Context Safety v1 shipped; next = Typed DataModel.
+- **Context Safety (v1)** — Compile-time capability rules from RunContext (`.server`/`.client`/`.plugin`): forbid `LocalPlayer` on server, `DataStoreService`/`ServerStorage`/`MessagingService` on client, wrong-direction `FireServer`/`FireClient`. Profile at `api/generated/capability-profile.json`; passed to `clpp` as `runContext` + `capabilityProfilePath`. CLI: `target capabilities`, `target check-context`.
+- **Reuse-first Roblox backend** — Cluaupp integrates CL++ with the Roblox ecosystem (consume dump/docs → registry → bindings); does not reinvent LSP/IDE/sourcemap/docs. Exports `api/generated/lsp-index.json` for the CL++ Language Server. `api aux-diff` for optional `@rbxts/types` / LuauTypes coverage. Docs/CONTRIBUTING matrix CONSUME/GENERATE/IMPLEMENT/DO NOT BUILD.
+- **Roblox Target Registry** — `src/api/` pipeline (loaders → normalize → validate → registry → generators), `RobloxTargetProfile` `schemaVersion` 2, `api/overrides/` (datatype migration from `DATATYPE_SPEC`), CLI `api` / `target`, lock + manifest, Luau `.d.luau` projection, Studio smoke harness, fixtures, coverage/diff.
+- **CL++ contract** — `MIN_CLPP_VERSION` raised to **0.7.0**; compile payload may pass `targetProfilePath` / `targetCacheDir`.
+- `npm run generate-api` delegates to `cluaupp api generate`.
+
+## 1.5.1
+
+- DataBoot `PlayerTemplate()` is rewritten to `TemplateData()` when that module is required (the constructor is the require bind).
+- Cluaupp always reindents emitted Luau with the Roblox tab style (`stylua.toml`: tabs, width 4, double quotes). Nested `Connect` / Sweep `Add` lambdas no longer dump `end` at column 0. Blank lines separate `if` / `for` / `while` scopes at the same indent. Consecutive `Table.Field =` inits (struct tables) are compacted. `--format` still runs StyLua when it is on PATH.
+- Method `~>` Connect hoists Sweep to `self.janitor` (one per controller). Instance binds (`Touched`, etc.) keep a local Sweep and `LinkToInstance` so they die with that instance.
+- Ward rate-limit (`Allow`) drops extra packets instead of striking every deny. A strike happens only after `FloodAt` (80) consecutive denials. Clicker spam is not a kick. Studio still does not Kick unless `KickInStudio`.
+- Ward no longer kicks Studio playtests by default (`KickInStudio = false`). Spawn/respawn get 3s grace, `lastPos` resets when the character is missing, Heartbeat uses a 1/30 dt floor, and mostly-vertical falls are not speed strikes. Placeholder spawn/fall no longer stacks to “Movement or traffic rejected”.
+- Gleam stores per-instance Sweep in a weak table. Assigning `_gleamSweep` on a `ScreenGui` errors (`not a valid member`).
+- Postprocess qualifies bare `HiveWorld` as `Hive.HiveWorld` (or `any` if Hive is not required) and reapplies Roster / ReplicatedStorage rewrites when writing `out/`.
+- Postprocess rewrites `Instance.new("Roster")` to `Roster.new()`, and replaces `script.Parent…ReplicatedStorage` walks with `ReplicatedStorage`. `Roster.New` is an alias of `Roster.new`.
+- Postprocess also rewrites `Sweep.New` / `Spark.New` / `Coil.New` → `.new`, and `Pin.new_` / `Crest.new_` / `Stage.new_` → `.new`. Runtime aliases: `Sweep.New`, `Coil.New`, `Pin.new_`, `Crest.new_`.
+- **Editor** — `npm install` / `cluaupp init` / `cluaupp intellisense` install the Cursor/VS Code extension for `.flare` `.hive` `.mint` `.bloom` `.helm` `.shift` `.axiom` (postinstall + init).
+- **Hive** `Set` / `Get` / `Remove` / `Has` / `Query` / `Snapshot` accept either a numeric component id or a generated schema row `{ Id = n, Fields = … }` (`.hive` Luau emit). Snapshot no longer crashes with `writeu8` on a table.
+- **Pin** no longer assigns `BillboardGui.MinDistance` (not a Roblox property). `PinOptions.MinDistance` stays in the API as reserved/ignored.
+- **Schema highlighting** — `.hive` `.mint` `.bloom` `.helm` `.shift` `.axiom` (plus existing `.flare`) in the Cluaupp editor extension. `cluaupp intellisense` / `cluaupp init` associate the extensions.
+- **CL++ skills book** — `skills/clpp-language`, `clpp-style`, `clpp-hive-flare`. `cluaupp init` copies them to `.cursor/skills/`.
+- **Flare** packs `...` instances **before** the query `pcall`. Nested `function()` cannot see `...` (`Cannot use '...' outside of a vararg function`).
+
 ## 1.5.0
 
 - **Flare IntelliSense** — VS Code / Cursor extension for `.flare` (highlighting, completions, hover, diagnostics, outline, snippets). `cluaupp intellisense` installs it; `cluaupp lsp` serves the same engine.

package/README.md

@@ -6,18 +6,18 @@
 
 **CL++ games on Roblox.** You write [CL++](https://kartzrbx.github.io/CLPP/). Cluaupp runs `clpp`, wires Rojo, and copies CluauppLibs.
 
-[CL++ language](https://kartzrbx.github.io/CLPP/) · [Docs](https://kartzrbx.github.io/Cluaupp/)
+[CL++ language](https://kartzrbx.github.io/CLPP/) · [Docs](https://kartzrbx.github.io/Cluaupp/) · [Why Cluaupp](https://kartzrbx.github.io/Cluaupp/why-cluaupp/) · [Benchmarks](https://kartzrbx.github.io/Cluaupp/benchmarks/) · [Roadmap](https://kartzrbx.github.io/Cluaupp/roadmap/)
 
 [![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-white.svg)](LICENSE)
 
-Cluaupp is the **toolchain**, not the language compiler. [KartzRbx/CLPP](https://github.com/KartzRbx/CLPP) owns syntax, IntelliSense (`clpp setup`), and Luau codegen. This CLI finds `.clpp` / `.clp` / `.clh` (and `.flare` / `.mint` / `.bloom` / `.helm` / `.shift` / `.hive` / `.axiom`), runs `clpp api compile`, rewrites `ClppLibs` → `ReplicatedStorage.CluauppLibs`, and writes `out/` for Rojo.
+Cluaupp is the **Roblox project host** for [CL++](https://kartzrbx.github.io/CLPP/) — not the language compiler and not “roblox-ts with different syntax.” It turns **CL++ + project semantics** into a **validated Roblox project**, then emits Luau. [KartzRbx/CLPP](https://github.com/KartzRbx/CLPP) owns language, checker, Language Server (`clpp setup`), and codegen. Cluaupp owns Rojo/DataModel wiring, Context Safety, Flare remotes, API Registry (`cluaupp api generate`), and CluauppLibs. Optional Luau IntelliSense: **luau-lsp** + Rojo. Never `CL++ → roblox-ts → Luau`. Architecture: [`docs/.../product-pillars.md`](docs/src/content/docs/architecture/product-pillars.md).
 
 Native PascalCase CluauppLibs: **Flare** net, **Sweep** zelador, **Spark** signal, **Keep** data, **Mint** numbers, **Axiom** math, **Roster** tables, **Gleam** UI, **Bloom** effects, **Lens** debug UI, **Crest** topbar, **Pin** billboard, **Stage** viewport 3D, **Coil** spring, **Helm** commands, **Shift** states, **Hive** ECS, **Ward** anti-cheat, **Ember** VFX, **Echo** replication, **Guide** tutorials, **Trace** pretty-print. Schemas pack u8 ids / ColorSequence / tables — never JSON on the hot path. Name map: [`runtime/SOURCES.md`](runtime/SOURCES.md).
 
 ```clpp
-#include <clpp/roblox.clh>
+link @clpp.roblox;
 
 struct HelloServer {
 	void Greet(Player player);
@@ -45,7 +45,7 @@ void init() {
 
 1. [Node.js](https://nodejs.org/) 18+
 2. [Rojo](https://rojo.space/) **7.7.0**
-3. **`clpp` 0.3.2** on PATH from [CL++](https://github.com/KartzRbx/CLPP/releases/tag/v0.3.2) (`clpp-setup.exe` or `clpp setup`). Do not leave a cargo `clpp 0.1.0` first on PATH.
+3. **`clpp` 0.8.0+** on PATH from [CL++](https://github.com/KartzRbx/CLPP/releases) (`clpp-setup.exe` or `clpp setup`; host **refuses** older compilers). Do not leave a cargo `clpp 0.1.0` first on PATH.
 
 ```bash
 npm install -g cluaupp@latest
@@ -71,10 +71,15 @@ cluaupp init [folder]
 cluaupp build [folder]
 cluaupp watch [folder]
 cluaupp language          # clpp api manifest
-cluaupp intellisense      # Flare extension + clpp setup
+cluaupp intellisense      # schema highlighting (.flare .hive …) + clpp setup (CL++ LSP)
+cluaupp api generate      # Registry → headers + lsp-index.json + lock
+cluaupp target info       # schemaVersion, class/enum counts
+cluaupp api aux-diff <p>  # optional coverage vs @rbxts/types / LuauTypes
 ```
 
-`clpp` missing? Set `CLPP` / `CLPP_PATH` or install [CL++ 0.3.2](https://github.com/KartzRbx/CLPP/releases/tag/v0.3.2).
+**IntelliSense:** CL++ → `clpp` Language Server + Cluaupp `lsp-index.json`. Schemas (`.flare`/…) → Cluaupp editor extension. Emitted Luau → luau-lsp (optional). Cluaupp does not ship a Roblox class IntelliSense engine.
+
+`clpp` missing? Set `CLPP` / `CLPP_PATH` or install [CL++ 0.8.0+](https://github.com/KartzRbx/CLPP/releases).
 
 ## Language
 

package/api/CHANGELOG.md

@@ -0,0 +1,3 @@
+# API changelog
+
+- 2026-09-22: Introduced RobloxTargetProfile schemaVersion 2, multi-source loaders, overrides migration from DATATYPE_SPEC, typed events (PlayerAdded), UnsupportedRepresentation gaps, lock/manifest.

package/api/chat.js

@@ -0,0 +1,74 @@
+"use strict";
+
+const SYSTEM = "You are the Cluaupp docs assistant. Cluaupp is the Roblox project host for CL++ 0.8+ (KartzRbx/CLPP). Shipped platform: Context Safety, Typed DataModel (variable-root WaitForChild), API Registry with ThreadSafety + CLUAU-PAR*, Authority + call-graph AUTH004, Flare remotes + versions, Optimizer (optimize --apply / --layout SoA), PGO profile ingest, source maps + cluaupp-source stamps, CluauppNav Studio plugin, cluaupp bridge IDE sync, incremental compile cache, build --frozen, doctor/analyze. It does not reimplement the CL++ parser.\nYou write CL++ for .clpp/.clp/.clh and show Luau only when explaining emit.\n\nCluaupp facts:\n- Tags: *.server.clpp Script, *.client.clpp LocalScript, *.plugin.clpp plugin Script, *.clp / untagged .clpp ModuleScript, *.clh headers.\n- void init() is the Script/LocalScript entry. There is no int main().\n- #include <clpp/...> is IntelliSense (and library require for libs). Quoted includes become game-rooted requires.\n- Libraries live in ReplicatedStorage.CluauppLibs after cluaupp build.\n- Native PascalCase libraries: Flare (net), Sweep (zelador), Spark (signal), Keep (data), Mint (numbers), Axiom (math), Roster (tables), Gleam (UI), Bloom (effects), Lens (debug UI), Crest (topbar), Pin (billboard), Stage (viewport 3D), Coil (spring), Helm (commands), Shift (states), Hive (ECS), Ember (VFX), Echo (replication), Guide (tutorials), Trace (pretty-print). Old Wally includes (janitor, fusion, iris, cmdr, formatnumber, …) are aliases. Buffer law: .flare/.mint/.bloom/.helm/.shift/.hive/.axiom pack u8 ids, ColorSequence, or tables — never JSON on the hot path. Gameplay SoA is opt-in via #pragma layout soa / optimize --apply --layout — not silent. ~>Connect is owned by Sweep.\n- MIN_CLPP_VERSION floor is 0.8.0; language law is CL++ 0.8+. Install CL++ 0.8+ from KartzRbx/CLPP releases, then clpp setup. Cluaupp package is 1.5.x.\n- Keep answers concise. Fences use language id clpp.\n\nThe remainder of this system prompt is the CL++ 0.8+ language law. Follow it for every snippet.\n\nYou are an expert in **CL++ 0.8+**. When you write or edit code, you output **only valid CL++** (or Luau when showing compiler emit). You never invent C++, Roblox-SDK, or VM features that this language does not have.\n\n## What CL++ is\n\nCL++ is a **C++-inspired language that compiles to Luau**. It is **language-only**: syntax, types, semantics, OOP. The compiler (`clpp`) is source-to-source: Pest parse → semantic check → Luau file. There is **no** CL++ VM, bytecode, or C++ hosting API.\n\n**Cluaupp** (separate project) owns Roblox API dumps, generated Instance headers, Rojo, and project `init`. If a Roblox class is missing from IntelliSense, that is a Cluaupp header problem, not a CL++ syntax problem.\n\nMarkdown / docs fences use the language id `clpp` (not `cpp`). File extensions: `.clh` `.clp` `.clpp`.\n\nCompiler: `clpp 0.8.0`. Host tools call `clpp api compile` (JSON) or `clpp compile`.\n\n## Files and entry\n\n| File | Role | Rojo |\n| --- | --- | --- |\n| `*.clh` | Header: `struct`, constants, prototypes | ModuleScript |\n| `*.clp` | Module implementation | ModuleScript |\n| `Foo.server.clpp` | Script | Script |\n| `Foo.client.clpp` | LocalScript | LocalScript |\n| `Foo.plugin.clpp` | Plugin | Script |\n| untagged `*.clpp` | Module | ModuleScript |\n\nThere is **no** `int main()`. Scripts and LocalScripts start at **`void init()`**.\n\nPrefer one service type per pair: `LeaderstatsServer.clh` beside `LeaderstatsServer.server.clpp`.\n\n## Authoritative operator table\n\nThis table is law. Almost every bug is the wrong accessor.\n\n| Write | Meaning | Luau |\n| --- | --- | --- |\n| `player.Name` / `player.Kick()` / `workspace.FindFirstChild(\"x\")` | property **and** instance method (the default) | `.` / `:` |\n| `age: int` / `player:Kick()` | type annotation **or** protected call (`pcall`; `nil` on error, never throws) | Luau `:` / `pcall` |\n| `task::wait` / `Vector3::new` / `Class::Method` (definition) / `signal::Connect` | static scope, method **definition**, **manual** Connect (you Disconnect) | `.` / `:` |\n| `\"hi \" .: name` | string concat | `..` |\n| `signal~>Connect(fn)` / `~>Once` | Sweep auto-cleanup Connect / Once | `sweep:Add(..., \"Disconnect\")` |\n| `items[0]` / `data[\"Coins\"]` / `workspace[\"Name\"]` | **index only** | `[key]` |\n| `name.Fire(...)` | fire a signal | `:Fire` |\n| `!=` `&&` `\\|\\|` `!` | logic | `~=` `and` `or` `not` |\n| `++` `--` | increment | `+= 1` `-= 1` |\n| `+` `-` `*` `/` | arithmetic only (`+` does **not** concat; `*` is never pointer deref) | same |\n\n**Never write:** `->` · `..` (Luau concat) · `\"hi \" + name` · `player->Name` · `this->x`.\n\n`.` on an instance **method** still passes `self` in Luau (`player.Kick()` → `player:Kick()`). `player:Kick()` in CL++ is the **pcall** form.\n\n## Types\n\nWrite types. Always initialize (`int coins = 0;` — bare `int coins;` emits `nil`).\n\n| CL++ | Luau |\n| --- | --- |\n| `int` `float` `double` | `number` |\n| `bool` | `boolean` |\n| `string` | `string` |\n| `void` | no return |\n| `func` | function |\n| `auto` | inferred (`new`, `GetService`, datatype ctor) |\n| `optional<T>` | `T?` |\n| `array<T>` / `vector<T>` / `LuaArray<T>` / `span<T>` | `{T}` |\n| `dictionary<K, V>` | `{ [K]: V }` |\n| `const` / `static constexpr` | Luau `const` |\n| `null` | `nil` |\n| `Player` `Folder` `Part` … | Instance **class name** |\n| `Vector3` `CFrame` `UDim2` `Color3` | same |\n| `signal<T...>` | typed BindableEvent-style signal |\n| `observable T` | ValueBase |\n| `Enum.Material.Plastic` | same |\n\n**Instances are class names.** Write `Player player`, never `Player*`, never `Player *player`. There is no address-of, no references `int&`, no pointer arithmetic. Lifetime is Roblox: `Destroy` or Janitor.\n\n`match` arms use the class name: `Part p =>`, not `Part* p`.\n\n`static_cast<T>(x)` (and other `*_cast`) emit the argument; Luau does not check `ClassName`.\n\n`using …;` is skipped. `namespace { }` is flattened. `enum` declarations are skipped or unused — prefer `Enum.*` from Roblox.\n\n## Functions and callbacks\n\nNamed:\n\n```clpp\nvoid Greet(Player player) {\n    post(\"hello, \" .: player.Name);\n}\n```\n\nAnonymous callbacks are **`func (params) { }`**. Zero parameters: `func () { }`. Luau still closes over outer locals. There is **no** C++ capture list.\n\n```clpp\nplayers.PlayerAdded~>Connect(func (Player playerEntered) {\n    post(playerEntered.Name);\n});\n\npcall(func () {\n    return 1;\n});\n\nfunc callback = func () {};\n```\n\n**These do not compile:** `func [](Player p) { }` · `[]() { }` · `func []() { }` · `[x](int n) { }`. `[]` is **only** indexing.\n\nNo `->` trailing return on lambdas. Body is `{ … }`.\n\n## OOP\n\nHeader (`.clh`):\n\n```clpp\n#pragma once\n#include <clpp/libs/janitor.clh>\n\nstruct LeaderstatsServer {\n    static constexpr int STARTING_COINS = 0;\n    Janitor janitor;\n    void PlayerEntered(Player player);\n};\n```\n\nImplementation (`.server.clpp`):\n\n```clpp\nvoid LeaderstatsServer::PlayerEntered(Player player) {\n    guard (player != null) else {\n        warn(\"Invalid player\");\n        return;\n    }\n    Folder folder = new Folder(player);\n    folder.Name = \"leaderstats\";\n}\n```\n\n- Define methods with `Class::Method` → Luau `function Class:Method`.\n- Call methods with `.` (`hello.Greet(player)`).\n- **`@` is the receiver sigil**, not a pointer and not `[[attribute]]`.\n- Inside `Class::Method` only:\n  - `@this` → `self`\n  - `@janitor` → `self.janitor`\n  - `@field` → `self.field`\n  - bare field names still become `self.field`\n  - `this` without `@` is the same alias; prefer `@this`\n- `@this` is a value: `other.Register(@this)` → `other:Register(self)`.\n- Do **not** put `@this` on the parameter list. `::` already injects the receiver.\n- **`@this` / `@field` in `void init()` or a free function is a compile error.**\n\n`init` builds **one** service object and captures it:\n\n```clpp\nvoid init() {\n    Players players = GetService<Players>();\n    LeaderstatsServer leaderstatsServer;\n    Janitor janitor = new Janitor();\n    leaderstatsServer.janitor = janitor;\n\n    for (Player player in players.GetPlayers()) {\n        leaderstatsServer.PlayerEntered(player);\n    }\n\n    players.PlayerAdded~>Connect(func (Player playerEntered) {\n        leaderstatsServer.PlayerEntered(playerEntered);\n    });\n\n    game.BindToClose(func () {\n        janitor.Cleanup();\n        janitor.Destroy();\n    });\n}\n```\n\n`new Folder(player)` → `Instance.new(\"Folder\"); folder.Parent = player`.  \n`GetService<Players>()` → `game:GetService(\"Players\")`.\n\nField-only structs in a `.clh` can emit `const function Name()` with default fields.\n\nUntagged files that only define `Class::` methods `return` the table (ModuleScript).\n\n`[[server]]` / `[[client]]` on functions are attributes (not `@`).\n\n## Includes and pragma\n\n```clpp\n#include <clpp/roblox.clh>                 // IntelliSense only — no Luau emitted\n#include <clpp/generated/instances.clh>    // Cluaupp-generated dump\n#include <clpp/datatypes.clh>\n#include <clpp/libs/sweep.clh>           // IntelliSense + require (janitor.clh aliases Sweep)\n#include <clpp/libs/dataservice.clh>\n#include \"LeaderstatsServer.clh\"           // same stem as the .clpp → inlined\n#include \"../shared/PlayerData.clh\"        // other stem → require\n```\n\n| Pragma | Luau |\n| --- | --- |\n| `#pragma once` | include guard (headers) |\n| `#pragma strict` | `--!strict` |\n| `#pragma nostrict` / `nonstrict` / `nstrict` | `--!nonstrict` |\n| `#pragma native` | `--!native` |\n| `#pragma optimize` / `#pragma optimize 2` | `--!optimize 2` |\n| `#pragma layout soa StructName` | opt-in SoA companion module (Cluaupp) |\n\nNo other macros. Comments: `//` and `/* */`.\n\n## I/O and conversions\n\n| CL++ | Luau |\n| --- | --- |\n| `post(...)` | `print` |\n| `warn(...)` | `warn` |\n| `report(...)` | `error` |\n| `to_string(x)` | `tostring` |\n| `to_number(x)` | `tonumber` (fail → `null`) |\n| `to_bool(x)` | `not not` |\n\nDo not write `print`, `error`, `tostring`, `tonumber` in CL++ source. `cout` / `cerr` / `endl` are mapped leftovers — prefer `post` / `warn`.\n\nStrings: `\"double\"` · `'single'` · `` `PlayerName is {player.Name}` `` · `` `a`, expr, `b` ``.\n\n## Collections\n\n```clpp\narray<string> names = {\"Kartz\", \"Player1\"};\ndictionary<string, int> stats = {\n    {\"Coins\", 100},\n    {\"Gems\", 50}\n};\npost(stats.Coins);\nnames[0];\nplayerData[\"Coins\"] = 600;\n```\n\n## Control flow\n\n```clpp\nif (coins > 50) {\n    post(\"Enough\");\n} else if (coins == 0) {\n    warn(\"None\");\n} else {\n    report(\"sync\");\n}\n\nwhile (n > 0) {\n    n--;\n}\n\nfor (int i = 0; i < 10; i++) {\n    post(\"Count: \" .: i);\n}\n\nfor (Player player in players.GetPlayers()) {\n    post(player.Name);\n}\n\nguard (player != null) else {\n    warn(\"Invalid player\");\n    return;\n}\n\nmatch (instance) {\n    Part p => p.Anchored = true,\n    Model m => post(m.Name),\n    string s => post(s),\n    _ => warn(\"not supported\")\n};\n\nswitch (n) {\n    case 1:\n        post(\"one\");\n        break;\n    default:\n        break;\n}\n```\n\n- Prefer range-for `for (T name in collection)` over C++ `for (T name : collection)`.\n- `guard (cond) else { … }` runs the else when cond is **false**. Happy path stays unindented. Almost always `return`.\n- `match` type arms: `Part p` → `IsA(\"Part\")`. `string s` → `typeof == \"string\"`. `_` fallback.\n- `break` and `return` exist. Prefer Result+`?` for recoverable errors. C++ `try/catch` is not shipped — use `pcall` or Result. Ternary `c ? t : e` exists (below try/`:`).\n\nDesignated initializers:\n\n```clpp\nDataService.Server.Init(DataServiceOptions {\n    .Template = playerData,\n    .StoreName = \"PlayerData\",\n    .UseMock = true,\n});\n```\n\n## Signals and observables\n\n```clpp\nobservable int coins = 100;\ncoins.OnChange(func (int newValue) {\n    post(\"Coins changed to: \" .: newValue);\n});\ncoins = 50;   // writes .Value, fires Changed\npost(coins);  // reads .Value\n\nsignal<Player, int> OnCoinsUpdated;\nOnCoinsUpdated~>Connect(func (Player player, int amount) {\n    post(player.Name .: \": \" .: amount);\n});\nOnCoinsUpdated~>Once(func (Player player, int amount) {\n    post(\"first\");\n});\nOnCoinsUpdated.Fire(player, 500);\nOnCoinsUpdated.Wait();\n\nobj.GetPropertyChangedSignal(\"Name\")~>Connect(func () {\n    post(\"Name changed\");\n});\n```\n\n`observable int` → `IntValue`; `float`/`double` → `NumberValue`; `string` → `StringValue`; `bool` → `BoolValue`; other → `ObjectValue`.\n\nDefault listen with **`~>`** (Sweep). Use `::Connect` only when you will Disconnect yourself.\n\n## Concurrency\n\n```clpp\nasync Data FetchData(Player player) {\n    Data data = await DataService.Server.WaitFor(player);\n    return data;\n}\n\nspawn {\n    task::wait(2);\n    post(\"Delay finished!\");\n};\n\nparallel {\n    post(\"desync\");\n};\n\nauto [success, result] = pcall(func () {\n    return 1;\n});\n```\n\n`await` → `__await`. `spawn { }` → `task.spawn`. `parallel { }` → `task.desynchronize` / `task.synchronize` (keep Instance access on the synchronized side).\n\n
+
+## GetService (Cluaupp host)\n\nGetService<T>() is Cluaupp Roblox Target (registry, Context Safety, CLUAU_SVC001, headers). CL++ only parses a generic call.\n\n## Modules (0.8+)
+
+Canonical: `import { Name } from \"./Path.clh\";` — no `export` keyword. Angle `#include <clpp/…>` is Cluaupp host only. Cycles → CLPP1001. Missing path → CLPP0801.
+
+## Option / Result (0.8+)
+
+`optional<T>` / `Option<T>`: `Some(x)` / `None`. `Result<T,E>`: `Ok(v)` / `Err(e)`. Try: `expr?` (Result only — CLPP1101 otherwise). Exhaustive match Ok+Err / Some+None or `_` (CLPP1102). Assign Result→plain T → CLPP0202. Precedence: assign → ? → : → ternary → ??.
+
+## Forbidden (never generate)\n\n- ISO C++: templates, overloading, `std::`, `delete`, `new int`, `unique_ptr`\n- `->`, `Player*`, `int&`, address-of, pointer arithmetic\n- `continue`, ternary, `do/while`, `try/catch`, `goto`\n- `func [](…)`, `[]() { }`, capture lists `[x]` `[&]`\n- `@this` / `@field` outside `Class::Method`\n- JSX\n- `int main()`\n- `print` / `error` / `tostring` in CL++ source (use `post` / `report` / `to_string`)\n- Luau `..` or `+` for strings (use `.:`)\n- Macros other than the `#pragma` list above\n- Inventing a CL++ bytecode VM or embedding API\n\n## Compiler emit order (when you show Luau)\n\n1. `--!strict` / `--!nonstrict` / `--!native` / `--!optimize N` from pragma  \n2. `game:GetService`  \n3. `require` (libs + quoted includes that are not the same stem)  \n4. types / constants  \n5. functions / body  \n6. `init()` at the end of Scripts / LocalScripts  \n\n## How you answer\n\n1. Write CL++ that **compiles on 0.8.0+**.\n2. If the user pastes C++ or old CL++ (`Player*`, `func []`, `->`), **rewrite** it to the table above and briefly say why.\n3. When showing both, label fences `clpp` and `luau`.\n4. Do not dump Roblox API surface; use class names and let Cluaupp headers exist.\n5. Prefer the hello / leaderstats / features shapes below as templates.\n\n## Canonical examples (these compile)\n\n### Hello Script\n\n```clpp\n#include <clpp/roblox.clh>\n\nstruct HelloServer {\n    void Greet(Player player);\n};\n\nvoid HelloServer::Greet(Player player) {\n    post(\"Player name: \" .: player.Name);\n}\n\nvoid init() {\n    HelloServer hello;\n    Players players = GetService<Players>();\n\n    for (Player player in players.GetPlayers()) {\n        hello.Greet(player);\n    }\n\n    players.PlayerAdded~>Connect(func (Player playerEntered) {\n        hello.Greet(playerEntered);\n    });\n}\n```\n\n### Method body with `@this`\n\n```clpp\nvoid CombatServer::BindPart(BasePart part) {\n    @janitor.Add(part, \"Destroy\");\n    other.Register(@this);\n}\n```\n\nEmits:\n\n```luau\nfunction CombatServer:BindPart(part: BasePart)\n\tself.janitor:Add(part, \"Destroy\")\n\tother:Register(self)\nend\n```\n\n### Language tour (module `.clp`)\n\n```clpp\nstruct Wallet {\n    int coins;\n    void Add(int n);\n};\n\nvoid Wallet::Add(int n) {\n    @coins = coins + n;\n    post(\"wallet \" .: @coins);\n}\n\nvoid Features(int coins) {\n    int n = 100;\n    string name = \"Kartz\";\n    Player playerRef = null;\n    Wallet pocket;\n    pocket.Add(10);\n\n    array<string> names = {\"Kartz\", \"Player1\"};\n    dictionary<string, int> stats = {\n        {\"Coins\", 100},\n        {\"Gems\", 50}\n    };\n\n    for (int i = 0; i < 10; i++) {\n        post(\"Count: \" .: i);\n    }\n\n    observable int wallet = 100;\n    wallet.OnChange(func (int newValue) {\n        post(newValue);\n    });\n\n    signal<Player, int> OnCoinsUpdated;\n    OnCoinsUpdated~>Connect(func (Player player, int newAmount) {\n        post(player.Name .: \": \" .: newAmount);\n    });\n    OnCoinsUpdated.Fire(playerRef, wallet);\n\n    guard (coins != null) else {\n        return;\n    }\n\n    auto [success, result] = pcall(func () {\n        return 1;\n    });\n\n    spawn {\n        task::wait(2);\n        post(\"Delay finished!\");\n    };\n}\n```";
+
+module.exports = async function handler(req, res) {
+	res.setHeader("Access-Control-Allow-Origin", "*");
+	res.setHeader("Access-Control-Allow-Methods", "POST, OPTIONS");
+	res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+
+	if (req.method === "OPTIONS") {
+		res.status(204).end();
+		return;
+	}
+
+	if (req.method !== "POST") {
+		res.status(405).json({ error: "POST only" });
+		return;
+	}
+
+	const key = process.env.AI_GATEWAY_API_KEY;
+	if (!key) {
+		res.status(500).json({ error: "AI Gateway is not configured" });
+		return;
+	}
+
+	const incoming = Array.isArray(req.body && req.body.messages) ? req.body.messages : [];
+	const messages = incoming
+		.filter((msg) => msg && (msg.role === "user" || msg.role === "assistant") && typeof msg.content === "string")
+		.slice(-16)
+		.map((msg) => ({ role: msg.role, content: msg.content.slice(0, 4000) }));
+
+	if (messages.length === 0) {
+		res.status(400).json({ error: "messages required" });
+		return;
+	}
+
+	try {
+		const upstream = await fetch("https://ai-gateway.vercel.sh/v1/chat/completions", {
+			method: "POST",
+			headers: {
+				Authorization: `Bearer ${key}`,
+				"Content-Type": "application/json",
+			},
+			body: JSON.stringify({
+				model: process.env.AI_GATEWAY_MODEL || "openai/gpt-5.6-sol",
+				messages: [{ role: "system", content: SYSTEM }, ...messages],
+				temperature: 0.4,
+			}),
+		});
+
+		const data = await upstream.json();
+		if (!upstream.ok) {
+			res.status(upstream.status >= 400 && upstream.status < 600 ? upstream.status : 502).json({
+				error: "AI Gateway error",
+			});
+			return;
+		}
+
+		const text = data.choices && data.choices[0] && data.choices[0].message && data.choices[0].message.content;
+		res.status(200).json({ text: text || "" });
+	} catch (err) {
+		res.status(502).json({ error: "Could not reach AI Gateway" });
+	}
+};

package/api/fixtures/roblox/README.md

@@ -0,0 +1,6 @@
+# Roblox API fixtures
+
+Use these dumps in CI without a local Studio install.
+
+- `mini/` — tiny structural fixture for ingest tests
+- Full dumps: point tests at `data/Mini-API-Dump.json` or set `CLUAUPP_API_DUMP`

package/api/fixtures/roblox/aux/sample.d.luau

@@ -0,0 +1,6 @@
+-- Minimal auxiliary types for coverage cross-check tests (not a full Roblox defs set).
+declare class Instance
+declare class Players
+declare class Vector3
+declare class OnlyInAuxPhantom
+type EnumMaterial = { Plastic: EnumItem }

package/api/fixtures/roblox/mini/Mini-API-Dump.json

@@ -0,0 +1,72 @@
+{
+	"Version": "fixture-mini-1",
+	"Classes": [
+		{
+			"Name": "Instance",
+			"Superclass": "<<<ROOT>>>",
+			"Tags": ["NotCreatable"],
+			"Members": [
+				{
+					"MemberType": "Property",
+					"Name": "Name",
+					"ValueType": { "Category": "Primitive", "Name": "string" },
+					"Security": { "Read": "None", "Write": "None" }
+				},
+				{
+					"MemberType": "Function",
+					"Name": "FindFirstChild",
+					"ReturnType": { "Category": "Class", "Name": "Instance" },
+					"Parameters": [
+						{ "Name": "name", "Type": { "Category": "Primitive", "Name": "string" } }
+					],
+					"Security": "None"
+				},
+				{
+					"MemberType": "Event",
+					"Name": "ChildAdded",
+					"Parameters": [
+						{ "Name": "child", "Type": { "Category": "Class", "Name": "Instance" } }
+					],
+					"Security": "None"
+				}
+			]
+		},
+		{
+			"Name": "Players",
+			"Superclass": "Instance",
+			"Tags": ["Service", "NotCreatable"],
+			"Members": [
+				{
+					"MemberType": "Event",
+					"Name": "PlayerAdded",
+					"Parameters": [
+						{ "Name": "player", "Type": { "Category": "Class", "Name": "Player" } }
+					],
+					"Security": "None"
+				}
+			]
+		},
+		{
+			"Name": "Player",
+			"Superclass": "Instance",
+			"Tags": ["NotCreatable"],
+			"Members": [
+				{
+					"MemberType": "Property",
+					"Name": "UserId",
+					"ValueType": { "Category": "Primitive", "Name": "int64" },
+					"Security": { "Read": "None", "Write": "None" }
+				}
+			]
+		}
+	],
+	"Enums": [
+		{
+			"Name": "Material",
+			"Items": [
+				{ "Name": "Plastic", "Value": 256 },
+				{ "Name": "Wood", "Value": 512 }
+			]
+		}
+	]
+}

package/api/generated/bench-latest.json

@@ -0,0 +1,39 @@
+{
+	"measuredAt": "2026-09-22T13:24:47.067Z",
+	"node": "v24.20.0",
+	"platform": "win32",
+	"registry": {
+		"classes": 925,
+		"enums": 636,
+		"datatypes": 47,
+		"services": 337,
+		"props": 4070,
+		"methods": 3282,
+		"events": 1092,
+		"threadSafety": 8462,
+		"buildMs": 352,
+		"regMs": 39,
+		"lspMs": 306,
+		"totalMs": 697
+	},
+	"gameBuild": {
+		"cold": {
+			"ms": 3719,
+			"status": 0,
+			"cacheHit": null,
+			"parallel": "8"
+		},
+		"fill": {
+			"ms": 3477,
+			"status": 0,
+			"cacheHit": null,
+			"parallel": "8"
+		},
+		"warm": {
+			"ms": 1506,
+			"status": 0,
+			"cacheHit": "7/7",
+			"parallel": null
+		}
+	}
+}

package/api/generated/capability-profile.json

@@ -0,0 +1,76 @@
+{
+	"schemaVersion": 1,
+	"target": "roblox",
+	"rules": [
+		{
+			"id": "CLUAUPP_CTX_LOCALPLAYER",
+			"message": "`LocalPlayer` is client-only — illegal in Server scripts",
+			"pattern": "\\bLocalPlayer\\b",
+			"forbiddenIn": [
+				"Server"
+			],
+			"severity": "error",
+			"capability": "client_player"
+		},
+		{
+			"id": "CLUAUPP_CTX_LOCALPLAYER_SHARED",
+			"message": "`LocalPlayer` in Shared modules is unsafe if required from the server — prefer Client scripts",
+			"pattern": "\\bLocalPlayer\\b",
+			"forbiddenIn": [
+				"Shared"
+			],
+			"severity": "warning",
+			"capability": "client_player"
+		},
+		{
+			"id": "CLUAUPP_CTX_DATASTORE",
+			"message": "`DataStoreService` is server-only — illegal in Client scripts",
+			"pattern": "\\bDataStoreService\\b|GetService\\s*<\\s*DataStoreService\\s*>|GetService\\s*\\(\\s*[\"']DataStoreService[\"']\\s*\\)",
+			"forbiddenIn": [
+				"Client"
+			],
+			"severity": "error",
+			"capability": "data_stores"
+		},
+		{
+			"id": "CLUAUPP_CTX_MESSAGING",
+			"message": "`MessagingService` is server-only — illegal in Client scripts",
+			"pattern": "\\bMessagingService\\b|GetService\\s*<\\s*MessagingService\\s*>",
+			"forbiddenIn": [
+				"Client"
+			],
+			"severity": "error",
+			"capability": "messaging"
+		},
+		{
+			"id": "CLUAUPP_CTX_SERVERSTORAGE",
+			"message": "`ServerStorage` is server-only — illegal in Client scripts",
+			"pattern": "\\bServerStorage\\b|GetService\\s*<\\s*ServerStorage\\s*>",
+			"forbiddenIn": [
+				"Client"
+			],
+			"severity": "error",
+			"capability": "server_storage"
+		},
+		{
+			"id": "CLUAUPP_CTX_FIRE_SERVER",
+			"message": "`FireServer` is client→server — illegal in Server scripts",
+			"pattern": "\\bFireServer\\b",
+			"forbiddenIn": [
+				"Server"
+			],
+			"severity": "error",
+			"capability": "fire_server"
+		},
+		{
+			"id": "CLUAUPP_CTX_FIRE_CLIENT",
+			"message": "`FireClient` / `FireAllClients` are server→client — illegal in Client scripts",
+			"pattern": "\\bFireAllClients\\b|\\bFireClient\\b",
+			"forbiddenIn": [
+				"Client"
+			],
+			"severity": "error",
+			"capability": "fire_client"
+		}
+	]
+}