@typetorch/framework 0.5.5 → 0.5.6

package/README.md

@@ -9,6 +9,21 @@ It ships **inside every artifact**, so each generation runs its own fresh copy a
 code. It needs the TypeTorch kernel in the place (`@typetorch/kernel`), which calls your `Server/boot` and
 `Client/boot` modules.
 
+### How it fits with the other TypeTorch packages
+
+| Package | Role | Where it runs |
+|---|---|---|
+| `@typetorch/kernel` | Baked into the place. Picks the branch, loads the payload, calls `boot(kernel)`, swaps generations, owns the stable remotes, `persist`, roles, settings and the health window. | the place (server and client) |
+| `@typetorch/framework` (this) | Modules, DI, lifecycle, troves, network, hot assets, analytics and the dev menu, on top of the kernel API (`src/kernel.ts` types it). | inside every payload |
+| `@typetorch/transformer` | roblox-ts compiler plugin: constructor dependency ids, network guards, `Dependency<T>()` / `Lazy<T>` / `TypeTorch.module<T>()` ids and user macros. Its `runtime-kit/` is copied here as `src/reflection/`. | your compile (Node) |
+| `@typetorch/cli` (`typetorch`, alias `tt`) | Builds the payload (`typetorch build`), deploys and hot-swaps it, rolls back, syncs hot assets, writes the signed settings (`liveConfig`, analytics, experiments), migrates Flamework games. | your machine / CI |
+| `@typetorch/dev-server` | `remote-claude`: the dev menu's Claude tab and Logs > Upload talk to it. | a dev's machine |
+
+The framework never talks to the CLI directly: the CLI builds and signs payloads and settings, the kernel loads them,
+and the framework reads what the kernel hands it. Features that need a newer kernel check `TypeTorch.features` and say
+"needs kernel x.y.z" on older ones; the dev menu flags kernels older than `LATEST_KERNEL` (`src/devtools/health.ts`,
+now 0.5.3) with a Migrate issue.
+
 ## Install
 
 ```sh
@@ -84,7 +99,7 @@ mapping.
 ```ts
 // src/server/boot.ts
 import { startServer, type ServerKernel } from "@typetorch/framework";
-import { BUILD } from "../shared/build";
+import { BUILD } from "../shared/build"; // written by `typetorch build`
 export function boot(kernel: ServerKernel) {
 	return startServer(kernel, { modules: [script.Parent!.FindFirstChild("services")!], build: BUILD });
 }
@@ -96,6 +111,10 @@ interface ServerToClient { coins: { changed(total: number): void } }
 export const network = createNetwork<ClientToServer, ServerToClient>();
 
 // src/server/services/coin.service.ts
+import { Module, Service, type OnStart } from "@typetorch/framework";
+import { network } from "../../shared/net";
+import { ScoreService } from "./score.service";
+
 @Service()
 export class CoinService extends Module implements OnStart {
 	constructor(private readonly score: ScoreService) { // injected
@@ -103,13 +122,22 @@ export class CoinService extends Module implements OnStart {
 	}
 	onStart() {
 		this.trove.add(network.server.coins.collect.on((player, coinId) => this.score.add(player, 1)));
+		this.trove.add(network.server.coins.balance.handle((player) => [this.score.get(player)]));
 	}
 }
 ```
 
+`startClient(kernel, options)` is the same for `src/client/boot.ts` with your controllers folder. `StartOptions`:
+`modules` (folders whose ModuleScripts are required, recursively, so their decorators register), `build` (the
+generated build info, shown in the dev menu) and `devtools` (default `true`; `false` leaves the dev menu out). Both
+return the generation's stop function, which the kernel calls on a swap.
+
 - **Modules:** `@Service()` (server) and `@Controller()` (client) classes extending `Module`. Constructor parameters
   are other modules, injected by type. Lifecycle: `OnInit` (sequential, dependencies first), `OnStart` (spawned),
   `OnStop` (reverse order), `OnTick`, `OnPhysics`, `OnRender`, `OnPlayerAdded` (replays players already in the server).
+  `@Service({ loadOrder: -1 })` breaks ties between modules with no dependency relation (lower first, default 0).
+  `this.ctx` has the realm, artifact, branch, channel, generation, build info, the raw kernel, `persist` and
+  `playerState`. `observePlayers(trove, (player, playerTrove) => ...)` is `OnPlayerAdded` for code outside a module.
 - **Modules outside the constructor:** `Dependency<T>()` (or `TypeTorch.module<T>()`) returns the running module of
   type T from anywhere: a method, a plain class a module built, a command handler. `TypeTorch.tryModule<T>()` returns
   undefined instead of throwing. They work once every module is constructed (from onInit on); in a constructor, a
@@ -161,6 +189,11 @@ export class CoinService extends Module implements OnStart {
   last minute's average, its slowest second and the physics FPS (`59.9 avg, 52.0 min, physics 60`; the warning colour
   under 50 on average). Older kernels show `needs kernel 0.4.2`. The same numbers ride on fleet heartbeats (the
   explorer's fleet table).
+- **Devtools reach devs only (kernel 0.5.6+):** the kernel leaves `devtools` off the shared client tree of a framework
+  with `devtools/on-demand.ts`. `runtime/devtools-loader.ts` then clones the folder, minus the server-only modules, into
+  each dev's PlayerGui (join, each generation, dev status changes), and that client copies it into its own tree and
+  starts it. On older kernels the folder stays in the tree as before. A failure costs a dev the menu, with a warning, and
+  never the generation.
 - **Dev-only tools (framework 0.4.1, `devtools/access.ts`):** Claude, Logs > Upload, Dex edits on the server, Network
   packet blocking and the hot-swap sound work under dev rules (private, reserved and Studio servers on a dev branch)
   for every dev, and on a public server an owner switched to a dev branch (Server > Branch) for owners only. Everywhere
@@ -198,10 +231,19 @@ export class CoinService extends Module implements OnStart {
 - **Owners and devs:** two roles (no admins: an older kernel's or typetorch.json's "admin" counts as a dev). The Manage
   group (Players, Servers, Bans) is for owners only.
 - **Remote Claude** (a dev-only tool: dev rules, or owners on a public server an owner switched to a dev branch):
-  while `typetorch remote-claude` (`@typetorch/dev-server`) runs on a dev's machine, allowlisted devs prompt Claude
-  Code from the Claude tab. Each dev pairs once by pasting the pairing code printed by
+  while `typetorch remote-claude` (alias `typetorch dev`; it runs `@typetorch/dev-server`) runs on a dev's machine,
+  allowlisted devs prompt Claude Code from the Claude tab. The allowlist is `--users`; without it the dev-server uses
+  the owners in the game's `typetorch.json`. Each dev pairs once by pasting the pairing code printed by
   typetorch-dev-server; the game server keeps the session URL and the tokens in memory and never sends them to clients.
-  No Roblox secret is needed.
+  No Roblox secret is needed. (The Studio plugin's Claude tab, with Apply / Deploy to dev / Discard, is a separate
+  client of the same dev-server, started by `typetorch serve --claude`; it doesn't go through the framework.)
+- **Remote debug (framework 0.5.0, kernel 0.5.0, `devtools/remote-debug.ts`):** owners can read a fleet server from
+  the backend's explorer (`/servers/<JobId>`). The kernel polls the backend, checks the op, the rate and that the
+  caller is an owner, then hands the framework's ops to the handler installed through `kernel.onRemoteDebug`. Read-only,
+  with the dev menu's own readers and limits: `modules`, `state` (Modules > State queries, rate-limited per caller),
+  `assets` (the last hot-asset sync), `network` (per-remote counters, no packet capture), `dex.children` (8 nodes, 200
+  rows each at most) and `dex.props`. There are no edit ops. Older kernels don't have the hook, so nothing is
+  installed. It is part of the devtools server, so `devtools: false` leaves it out too.
 
 ## Runtime API: `TypeTorch`
 
@@ -358,10 +400,15 @@ rebuild(shop.get());
 - **AssetSync** is a server built-in. It runs on every generation start, before any module loads (top-level code
   included). For each manifest key:
   1. it keeps the live copy that already has the manifest's version;
-  2. else it adopts the place's own copy, if its `TypeTorchAssetHash` matches (or if the manifest's optional
-     `placeVersion` is this server's place version);
-  3. else it runs `InsertService:LoadAssetVersion(ver)` (all loads in parallel), strips any scripts, places the copy
-     at its path (creating missing Folders), tags it, then destroys the copy it replaces.
+  2. else it adopts the place's own copy, if its `TypeTorchAssetHash` matches, or if the place holds exactly the
+     copies the manifest was exported from: the manifest's optional `placeVersion` is this server's place version, or
+     the place's backup build (`ServerStorage.TypeTorchBackup`, attributes `HotAssetsPlaceVersion` /
+     `HotAssetsSavedAs`) vouches that this place version is a save of that one which changed nothing outside the
+     kernel slots (the CLI's backup refresh);
+  3. else it runs `InsertService:LoadAssetVersion(ver)` (all loads in parallel), strips any scripts, gives back the
+     CollectionService tags the place's copy has (uploaded versions arrive without them, so a game that finds its UI
+     by tag keeps working), places the copy at its path (creating missing Folders), tags it, then destroys the copy it
+     replaces.
 
   It holds the start for at most 8 s. Loads still running after that keep going, swap in when done and fire
   `changed`. A failed load keeps the old copy (on a new server, the place's copy) and shows under Server > Status >
@@ -373,7 +420,8 @@ rebuild(shop.get());
   `TypeTorchAssetPath` (stamped by AssetSync) is the live one. So a template cloned into PlayerGui never shows up in
   `get()`, and AssetSync never destroys it.
 - **Dev menu:** Modules > Assets (Server | Client) lists each key's source (kept, baked, loaded, failed), version,
-  load time and last error.
+  load time and last error. With analytics on, each generation also sends one `tech` / `assets` row (the place match
+  and the counts per source; `src/analytics/SCHEMA.md`).
 
 ## Analytics: `AnalyticsEngine`
 
@@ -420,7 +468,9 @@ const variant = analytics.experiment("onboarding", ["short", "long"]); // same a
 - **Experiments:** `experiment(...)` is deterministic per player and name (they keep their variant in every session),
   may yield briefly the first time (until the player's id loads), and stamps the variant on the player's later events.
   The settings turn one off (`active: false`: everyone gets the first variant), sets `weights` or forces a
-  `variant`, live.
+  `variant`, live. `players` (framework 0.5.3+) forces a variant for single players, keyed by UserId or pid, over
+  everything else (QA, support); a client only ever gets its own entry. The CLI writes these with `typetorch
+  experiment weights | settle | stop | resume | clear | force | unforce`.
 - **First-ever session:** for new players (a share of them, `recordShare`), the client records character and camera
   about 10 times a second, every input (never while a TextBox or the chat has focus; text boxes only say which box was
   used), buttons pressed and hovered, screens, prompts and deaths, from the join until 60 s after the first input.
@@ -493,8 +543,11 @@ bun install
 bun run build   # rbxtsc --type package -> out/
 ```
 
-- **Runtime of the transformer:** `src/reflection/` (`Reflect`, `Modding`, `t`) is a copy of
-  `@typetorch/transformer`'s `runtime-kit/`; keep the two identical.
+- **Runtime of the transformer:** `src/reflection/reflect.ts` and `modding.ts` are copies of
+  `@typetorch/transformer`'s `runtime-kit/` (the source of truth); keep them identical. The framework compiles itself
+  without the transformer (only `rbxts-transform-debug`): it declares macros, which expand in the game's compile.
+- **Versions:** bump `src/version.ts` (`FRAMEWORK_VERSION`, shown in uploaded log headers) with package.json, and
+  `LATEST_KERNEL` in `src/devtools/health.ts` when the framework starts relying on a newer kernel.
 - **Tests (Lune, offline):** `scripts/test-*.luau`; each file's header has its command (Lune is pinned in the
   kernel's and the template's `rokit.toml`). `scripts/test-generations.luau` takes a game's built payload:
   `cd ../template && bun run payload && lune run ../framework/scripts/test-generations.luau build/payload.rbxm` boots
@@ -522,13 +575,37 @@ bun run build   # rbxtsc --type package -> out/
   retries, a NetFail streak and its one log line a minute, a swap with a request in flight, shutdown; the recorder,
   screens, batching). `scripts/test-net-health.luau` checks the dev menu's Fleet API / Analytics status lines and
   Attention issues.
-- **Publishing:** `npm publish` runs `prepublishOnly` (clean + build). The package ships only `out/` (no
-  `.tsbuildinfo`), `README.md` and `LICENSE`; check with `bun pm pack --dry-run`.
-
+  The others, each on the compiled `out/`: `test-hot-assets` (manifest parser, AssetSync decisions incl. the backup
+  vouch, live-copy rules), `test-messaging` (messaging and the server list), `test-settings` (`liveConfig` and the
+  settings lines), `test-detached` (`runDetached`), `test-dev-access` (the dev-only tools rule and every gate through
+  it), `test-remote-debug` (the remote debug ops and their limits), `test-net-inspect` (packet capture),
+  `test-explorer-core` (Dex), `test-toolbox-sanitize` (the Creator Store sanitizer) and `test-sha256` (the pairing-code
+  fingerprint). `node scripts/check-self-calls.mjs out` flags compiled functions that call themselves on their first
+  lines (after `bun run build`).
+- **Package contents:** only `out/` (no `.tsbuildinfo`), `README.md` and `LICENSE`; check with `bun pm pack --dry-run`.
 - **Explorer class icons:** `assets/class-icons.png` (kept locally, not in the repo: it is Roblox's own texture) is
   the client's `content/textures/ClassImages.PNG` (a 2352x16 strip) repacked into a 32-column grid, because live
   clients downscale textures wider than 1024 px:
   `ffmpeg -i ClassImages.PNG -vf "untile=147x1,tile=32x5:color=0x00000000" class-icons.png`. It is uploaded as image
   `rbxassetid://97389585475400`; `scripts/gen-explorer-icons.ts` generates the index table.
 
+## Release
+
+Publishing is tag-only, from CI (`.github/workflows/publish.yml`), with npm trusted publishing (OIDC, provenance):
+
+```sh
+# first commit src/version.ts set to the new version (npm version needs a clean tree)
+npm version 0.5.6 -m "release %s"
+git push origin main --follow-tags
+```
+
+The workflow runs on a `v*` tag, checks that the tag matches package.json and that the version isn't on npm yet, then
+`npm publish --provenance` (which runs `prepublishOnly`: a clean `rbxtsc --type package` into `out/`) and creates the
+GitHub release with generated notes. A prerelease version (`x.y.z-next.0`) goes to the `next` dist-tag and a GitHub
+prerelease; anything else to `latest`. Trusted publishing is set on npmjs.com (@typetorch/framework > Settings >
+Trusted publishing: this repo, workflow `publish.yml`, environment `npm`); an `NPM_TOKEN` repo secret is the fallback.
+Don't run `npm publish` by hand. Games pick the new version up with `bun update @typetorch/framework` and their next
+deploy, since the framework ships inside the payload.
+
+
 MIT licensed.

package/out/devtools/client.d.ts

@@ -5,4 +5,9 @@ export interface DevtoolsClient {
     /** Call once the client generation is up (all modules started). */
     readonly started: () => void;
 }
+/**
+ * Starts the dev menu for this client generation. Everything it creates or connects lives in `trove`, so a swap
+ * removes it; the open state, tab, sub-tab, window rectangle and options survive the swap through the kernel persist
+ * store.
+ */
 export declare function startDevtoolsClient(kernel: ClientKernel, dispatcher: ClientDispatcher, trove: Trove): DevtoolsClient;

package/out/devtools/client.luau

@@ -22,6 +22,10 @@ local showCliNote = _build_actions.showCliNote
 local switchedText = _build_actions.switchedText
 local switchOffered = _build_actions.switchOffered
 local viewerIsOwner = _build_actions.viewerIsOwner
+local _dev_gui = TS.import(script, script.Parent.Parent, "runtime", "dev-gui")
+local DEV_GUI_GENERATION = _dev_gui.DEV_GUI_GENERATION
+local DEV_GUI_NAME = _dev_gui.DEV_GUI_NAME
+local sweepStaleMenus = _dev_gui.sweepStaleMenus
 local _ui = TS.import(script, script.Parent.Parent, "ui")
 local bump = _ui.bump
 local popIn = _ui.popIn
@@ -422,7 +426,7 @@ local function every(trove, interval, callback)
 		while true do
 			local ok, err = pcall(callback)
 			if not ok then
-				warn("[src/devtools/client.ts:367]", `[devtools] refresh failed: {err}`)
+				warn("[src/devtools/client.ts:368]", `[devtools] refresh failed: {err}`)
 			end
 			task.wait(interval)
 		end
@@ -534,36 +538,7 @@ end
 	 * store.
 	 
 ]]
-local DEV_GUI_NAME = "TypeTorchDev"
---* The client generation that built a dev menu gui (an attribute on the ScreenGui). 
-local DEV_GUI_GENERATION = "TypeTorchGeneration"
---[[
-	*
-	 * Destroys dev menus an older generation left behind. Its trove should have removed them, but a generation whose stop
-	 * was cut short (a throwing cleanup, before framework 0.5.2) left its menu on screen, dead, over the new one.
-	 * Menus without the attribute come from a framework before 0.5.2: always older, since this generation hasn't built one.
-	 
-]]
-local function sweepStaleMenus(playerGui, generation)
-	for _, child in playerGui:GetChildren() do
-		if child.Name ~= DEV_GUI_NAME or not child:IsA("ScreenGui") then
-			continue
-		end
-		local built = child:GetAttribute(DEV_GUI_GENERATION)
-		if type(built) == "number" and built >= generation then
-			continue
-		end
-		pcall(function()
-			return child:Destroy()
-		end)
-	end
-end
 local function startDevtoolsClient(kernel, dispatcher, trove)
-	-- Before anything else, so a leaked menu goes away even for players who never get the dev menu.
-	local startGui = Players.LocalPlayer:FindFirstChildOfClass("PlayerGui")
-	if startGui then
-		sweepStaleMenus(startGui, kernel.generation)
-	end
 	local state = kernel:persist(PERSIST_KEY, function()
 		return {
 			open = false,
@@ -2547,7 +2522,7 @@ local function startDevtoolsClient(kernel, dispatcher, trove)
 			})
 		end)
 		if not ok then
-			warn("[src/devtools/client.ts:1768]", `[devtools] {key} tab failed: {err}`)
+			warn("[src/devtools/client.ts:1748]", `[devtools] {key} tab failed: {err}`)
 			page:text(`This tab failed: {err}`, COLORS.bad)
 		end
 	end
@@ -3154,7 +3129,7 @@ local function startDevtoolsClient(kernel, dispatcher, trove)
 					return playReloadSound()
 				end)
 				if not ok then
-					warn("[src/devtools/client.ts:2189]", `[devtools] reload sound failed: {err}`)
+					warn("[src/devtools/client.ts:2169]", `[devtools] reload sound failed: {err}`)
 				end
 			end))
 		end,

package/out/devtools/on-demand.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The kernel (0.5.6+) looks for this module by name: its presence says this framework's `devtools` folder can stay off
+ * the shared client tree, because runtime/devtools-loader.ts hands each dev a copy. Older frameworks don't have it, and
+ * keep the folder where their static imports need it.
+ */
+export declare const DEVTOOLS_ON_DEMAND = true;

package/out/devtools/on-demand.luau

@@ -0,0 +1,12 @@
+-- Compiled with roblox-ts v3.0.0
+--[[
+	*
+	 * The kernel (0.5.6+) looks for this module by name: its presence says this framework's `devtools` folder can stay off
+	 * the shared client tree, because runtime/devtools-loader.ts hands each dev a copy. Older frameworks don't have it, and
+	 * keep the folder where their static imports need it.
+	 
+]]
+local DEVTOOLS_ON_DEMAND = true
+return {
+	DEVTOOLS_ON_DEMAND = DEVTOOLS_ON_DEMAND,
+}

package/out/runtime/dev-gui.d.ts

@@ -0,0 +1,8 @@
+/** The dev menu's ScreenGui name, and the attribute with the generation that built it. */
+export declare const DEV_GUI_NAME = "TypeTorchDev";
+export declare const DEV_GUI_GENERATION = "TypeTorchGeneration";
+/**
+ * Destroys menus an older generation left behind, so a leaked menu goes away. Lives outside devtools: a player who has
+ * since lost dev access gets no devtools, and still needs this.
+ */
+export declare function sweepStaleMenus(playerGui: Instance, generation: number): void;

package/out/runtime/dev-gui.luau

@@ -0,0 +1,29 @@
+-- Compiled with roblox-ts v3.0.0
+--* The dev menu's ScreenGui name, and the attribute with the generation that built it. 
+local DEV_GUI_NAME = "TypeTorchDev"
+local DEV_GUI_GENERATION = "TypeTorchGeneration"
+--[[
+	*
+	 * Destroys menus an older generation left behind, so a leaked menu goes away. Lives outside devtools: a player who has
+	 * since lost dev access gets no devtools, and still needs this.
+	 
+]]
+local function sweepStaleMenus(playerGui, generation)
+	for _, child in playerGui:GetChildren() do
+		if child.Name ~= DEV_GUI_NAME or not child:IsA("ScreenGui") then
+			continue
+		end
+		local built = child:GetAttribute(DEV_GUI_GENERATION)
+		if type(built) == "number" and built >= generation then
+			continue
+		end
+		pcall(function()
+			return child:Destroy()
+		end)
+	end
+end
+return {
+	sweepStaleMenus = sweepStaleMenus,
+	DEV_GUI_NAME = DEV_GUI_NAME,
+	DEV_GUI_GENERATION = DEV_GUI_GENERATION,
+}

package/out/runtime/devtools-loader.d.ts

@@ -0,0 +1,6 @@
+import type { Trove } from "@rbxts/trove";
+import type { ClientKernel, ServerKernel } from "../kernel";
+import type { ClientDispatcher, ServerDispatcher } from "../net/runtime";
+export declare function loadDevtoolsServer(kernel: ServerKernel, dispatcher: ServerDispatcher, trove: Trove): void;
+/** Starts the client's devtools now or when its copy arrives. Returns the "every module has started" hook. */
+export declare function loadDevtoolsClient(kernel: ClientKernel, dispatcher: ClientDispatcher, trove: Trove): () => void;

package/out/runtime/devtools-loader.luau

@@ -0,0 +1,227 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local Players = TS.import(script, TS.getModule(script, "@rbxts", "services")).Players
+local TypeTorch = TS.import(script, script.Parent.Parent, "typetorch").TypeTorch
+local sweepStaleMenus = TS.import(script, script.Parent, "dev-gui").sweepStaleMenus
+--[[
+	*
+	 * Loads the devtools, and only for those who get them. Kernel 0.5.6+ leaves `devtools` off the shared client tree of a
+	 * framework that has devtools/on-demand.ts, and sets ON_DEMAND_ATTRIBUTE on the generation's trees. Then the server
+	 * clones the folder into each dev's PlayerGui (which replicates to its owner only), and that dev's client copies it
+	 * back to its place in its own tree, so the compiled relative imports and the module cache work as usual. On an older
+	 * kernel the attribute is missing and the folder is in the tree as before.
+	 *
+	 * The devtools are never imported statically outside this file's dynamic imports: TS.import waits on a missing child
+	 * forever. A failure here costs a dev the menu, with a warning, and never the generation.
+	 
+]]
+local ON_DEMAND_ATTRIBUTE = "DevtoolsOnDemand"
+local COPY_NAME = "TypeTorchDevtools"
+local COPY_GENERATION = "Generation"
+local COPY_INSTANCES = "Instances"
+--* Devtools modules only servers require: left out of a dev's copy. scripts/check-devtools-split.mjs checks the list. 
+local SERVER_ONLY = { "access", "admin-server", "artifact-notes", "claude", "explorer-server", "network-server", "remote-debug", "server", "sha256", "toolbox-sanitize", "toolbox-server" }
+--* Seconds a dev's client waits for its copy to finish replicating. 
+local REPLICATION_TIMEOUT = 60
+local frameworkRoot = function()
+	return script.Parent.Parent
+end
+--* This generation's tree: the same name on the server and the client (kernel: `<artifact>#<n>`). 
+local generationTree = function()
+	local _result = script:FindFirstAncestor("include")
+	if _result ~= nil then
+		_result = _result.Parent
+	end
+	return _result
+end
+local function shareWithDevs(devtools, generation, trove)
+	local copies = {}
+	local give = function(player)
+		local ok, problem = pcall(function()
+			local _player = player
+			local _condition = copies[_player] ~= nil
+			if not _condition then
+				_condition = not TypeTorch:isDev(player)
+			end
+			if _condition then
+				return nil
+			end
+			local playerGui = player:WaitForChild("PlayerGui", 30)
+			if not playerGui then
+				error("no PlayerGui after 30 s")
+			end
+			local _player_1 = player
+			local _condition_1 = copies[_player_1] ~= nil
+			if not _condition_1 then
+				_condition_1 = player.Parent == nil
+			end
+			if _condition_1 then
+				return nil
+			end
+			local copy = devtools:Clone()
+			for _, name in SERVER_ONLY do
+				local _result = copy:FindFirstChild(name)
+				if _result ~= nil then
+					_result:Destroy()
+				end
+			end
+			copy.Name = COPY_NAME
+			copy:SetAttribute(COPY_GENERATION, generation)
+			copy:SetAttribute(COPY_INSTANCES, #copy:GetDescendants())
+			local _player_2 = player
+			copies[_player_2] = copy
+			trove:add(copy)
+			copy.Parent = playerGui
+		end)
+		if not ok then
+			warn(`[TypeTorch] no devtools for {player.Name}: {problem}`)
+		end
+	end
+	trove:connect(Players.PlayerAdded, function(player)
+		return give(player)
+	end)
+	trove:connect(Players.PlayerRemoving, function(player)
+		local _player = player
+		-- ▼ Map.delete ▼
+		local _valueExisted = copies[_player] ~= nil
+		copies[_player] = nil
+		-- ▲ Map.delete ▲
+		return _valueExisted
+	end)
+	trove:add(TypeTorch:onPlayerDevChanged(function(player, info)
+		if info.dev then
+			give(player)
+			return nil
+		end
+		local _player = player
+		local copy = copies[_player]
+		if copy then
+			local _player_1 = player
+			copies[_player_1] = nil
+			trove:remove(copy)
+		end
+	end))
+	for _, player in Players:GetPlayers() do
+		trove:add(task.spawn(give, player))
+	end
+end
+local function loadDevtoolsServer(kernel, dispatcher, trove)
+	local ok, problem = pcall(function()
+		local _binding = TS.Promise.new(function(resolve)
+			resolve(TS.import(script, script.Parent.Parent, "devtools", "server"))
+		end):expect()
+		local startDevtoolsServer = _binding.startDevtoolsServer
+		startDevtoolsServer(kernel, dispatcher, trove:extend())
+		local tree = generationTree()
+		local devtools = frameworkRoot():FindFirstChild("devtools")
+		local _result = tree
+		if _result ~= nil then
+			_result = _result:GetAttribute(ON_DEMAND_ATTRIBUTE)
+		end
+		local _condition = _result == true
+		if _condition then
+			_condition = devtools
+		end
+		if _condition then
+			shareWithDevs(devtools, tree.Name, trove)
+		end
+	end)
+	if not ok then
+		warn(`[TypeTorch] devtools failed to start, the game goes on without them: {problem}`)
+	end
+end
+--* Starts the client's devtools now or when its copy arrives. Returns the "every module has started" hook. 
+local function loadDevtoolsClient(kernel, dispatcher, trove)
+	local playerGui = Players.LocalPlayer:FindFirstChildOfClass("PlayerGui")
+	if playerGui then
+		sweepStaleMenus(playerGui, kernel.generation)
+	end
+	local alive = true
+	trove:add(function()
+		alive = false
+	end)
+	local onStarted
+	local modulesStarted = false
+	local runStarted = function()
+		if not onStarted or not modulesStarted then
+			return nil
+		end
+		local ok, problem = pcall(onStarted)
+		if not ok then
+			warn(`[TypeTorch] devtools: {problem}`)
+		end
+	end
+	local begin = function()
+		local ok, result = pcall(function()
+			local _binding = TS.Promise.new(function(resolve)
+				resolve(TS.import(script, script.Parent.Parent, "devtools", "client"))
+			end):expect()
+			local startDevtoolsClient = _binding.startDevtoolsClient
+			return startDevtoolsClient(kernel, dispatcher, trove:extend())
+		end)
+		if not ok then
+			warn(`[TypeTorch] devtools failed to start, the game goes on without them: {result}`)
+			return nil
+		end
+		onStarted = result.started
+		runStarted()
+	end
+	local tree = generationTree()
+	local _result = tree
+	if _result ~= nil then
+		_result = _result:GetAttribute(ON_DEMAND_ATTRIBUTE)
+	end
+	local _condition = _result ~= true
+	if not _condition then
+		_condition = frameworkRoot():FindFirstChild("devtools")
+	end
+	if _condition then
+		begin()
+	else
+		local taken = false
+		local take = function(copy)
+			if taken or copy.Name ~= COPY_NAME or copy:GetAttribute(COPY_GENERATION) ~= tree.Name then
+				return nil
+			end
+			taken = true
+			local expected = copy:GetAttribute(COPY_INSTANCES)
+			local deadline = os.clock() + REPLICATION_TIMEOUT
+			while alive and type(expected) == "number" and #copy:GetDescendants() < expected do
+				if os.clock() > deadline then
+					warn("[TypeTorch] the devtools copy didn't finish replicating: no dev menu until the next generation")
+					return nil
+				end
+				task.wait(0.1)
+			end
+			if not alive then
+				return nil
+			end
+			-- A clone, so a retry of this generation on a fresh tree (kernel client) still finds the original.
+			local ok, problem = pcall(function()
+				local placed = copy:Clone()
+				placed.Name = "devtools"
+				placed.Parent = frameworkRoot()
+			end)
+			if ok then
+				begin()
+			else
+				warn(`[TypeTorch] devtools copy failed: {problem}`)
+			end
+		end
+		trove:add(task.spawn(function()
+			local gui = Players.LocalPlayer:WaitForChild("PlayerGui")
+			trove:connect(gui.ChildAdded, take)
+			for _, child in gui:GetChildren() do
+				take(child)
+			end
+		end))
+	end
+	return function()
+		modulesStarted = true
+		runStarted()
+	end
+end
+return {
+	loadDevtoolsServer = loadDevtoolsServer,
+	loadDevtoolsClient = loadDevtoolsClient,
+}

package/out/runtime/start.luau

@@ -6,8 +6,6 @@ local RunService = _services.RunService
 local Trove = TS.import(script, TS.getModule(script, "@rbxts", "trove").out).Trove
 local bindHotAssets = TS.import(script, script.Parent.Parent, "assets", "hot-asset").bindHotAssets
 local syncHotAssets = TS.import(script, script.Parent.Parent, "assets", "sync").syncHotAssets
-local startDevtoolsClient = TS.import(script, script.Parent.Parent, "devtools", "client").startDevtoolsClient
-local startDevtoolsServer = TS.import(script, script.Parent.Parent, "devtools", "server").startDevtoolsServer
 local _runtime = TS.import(script, script.Parent.Parent, "net", "runtime")
 local ClientDispatcher = _runtime.ClientDispatcher
 local ServerDispatcher = _runtime.ServerDispatcher
@@ -22,6 +20,9 @@ local startedTypeTorch = _typetorch.startedTypeTorch
 local swapOutTypeTorch = _typetorch.swapOutTypeTorch
 local TypeTorch = _typetorch.TypeTorch
 local unbindTypeTorch = _typetorch.unbindTypeTorch
+local _devtools_loader = TS.import(script, script.Parent, "devtools-loader")
+local loadDevtoolsClient = _devtools_loader.loadDevtoolsClient
+local loadDevtoolsServer = _devtools_loader.loadDevtoolsServer
 local _dependency = TS.import(script, script.Parent, "dependency")
 local addModuleInstance = _dependency.addModuleInstance
 local createLazy = _dependency.createLazy
@@ -251,7 +252,7 @@ local function start(realm, kernel, options)
 			return dispatcher:forget(player)
 		end)
 		if options.devtools ~= false then
-			startDevtoolsServer(serverKernel, dispatcher, root:extend())
+			loadDevtoolsServer(serverKernel, dispatcher, root:extend())
 		end
 		stopNetwork = function()
 			return setServerDispatcher(nil)
@@ -271,7 +272,7 @@ local function start(realm, kernel, options)
 		-- The server queues what it sends this player until this (0.3.0).
 		dispatcher:hello()
 		if options.devtools ~= false then
-			onStarted = startDevtoolsClient(clientKernel, dispatcher, root:extend()).started
+			onStarted = loadDevtoolsClient(clientKernel, dispatcher, root:extend())
 		end
 		stopNetwork = function()
 			dispatcher:stop()
@@ -308,7 +309,7 @@ local function start(realm, kernel, options)
 					return (running.instance):onStop()
 				end)
 				if not ok then
-					warn("[src/runtime/start.ts:206]", `{running.name}.onStop threw: {err}`)
+					warn("[src/runtime/start.ts:205]", `{running.name}.onStop threw: {err}`)
 				end
 			end
 			-- Object by object, each pcalled: a cleanup that throws (e.g. trove.remove inside a cleanup) can't skip the
@@ -461,7 +462,7 @@ local function start(realm, kernel, options)
 		_result()
 	end
 	startedTypeTorch()
-	print("[src/runtime/start.ts:305]", `TypeTorch {realm} started {#runningModules} modules in {math.floor((os.clock() - startedAt) * 1000)} ms (artifact {kernel.artifact.id}, generation {kernel.generation})`)
+	print("[src/runtime/start.ts:304]", `TypeTorch {realm} started {#runningModules} modules in {math.floor((os.clock() - startedAt) * 1000)} ms (artifact {kernel.artifact.id}, generation {kernel.generation})`)
 	return function(info)
 		-- TypeTorch.onSwapOut first, while every module still runs (so they can save into persist).
 		stopStep("onSwapOut", function()

package/out/servers.d.ts

@@ -1,9 +1,9 @@
 import type { Trove } from "@rbxts/trove";
-import { RollCall } from "./devtools/roll-call";
+import { RollCall } from "./roll-call";
 import type { Channel, ServerKernel, ServerType } from "./kernel";
 /**
  * The universe's live servers for game code: `TypeTorch.servers()` and `TypeTorch.setServerInfo()` (server only;
- * plans/19 item 19). Built on the framework's roll call (devtools/roll-call.ts; the same one Manage > Servers uses): no
+ * plans/19 item 19). Built on the framework's roll call (roll-call.ts; the same one Manage > Servers uses): no
  * MemoryStore, no heartbeat writes.
  *
  * - One roll call per generation, owned here and shared with the dev menu. Every server answers asks with its row: the

package/out/servers.luau

@@ -4,7 +4,7 @@ local _services = TS.import(script, TS.getModule(script, "@rbxts", "services"))
 local HttpService = _services.HttpService
 local MessagingService = _services.MessagingService
 local Players = _services.Players
-local _roll_call = TS.import(script, script.Parent, "devtools", "roll-call")
+local _roll_call = TS.import(script, script.Parent, "roll-call")
 local isJobId = _roll_call.isJobId
 local ROLL_CALL_TOPIC = _roll_call.ROLL_CALL_TOPIC
 local RollCall = _roll_call.RollCall
@@ -16,7 +16,7 @@ local Relay = TS.import(script, script.Parent, "runtime", "relay").Relay
 --[[
 	*
 	 * The universe's live servers for game code: `TypeTorch.servers()` and `TypeTorch.setServerInfo()` (server only;
-	 * plans/19 item 19). Built on the framework's roll call (devtools/roll-call.ts; the same one Manage > Servers uses): no
+	 * plans/19 item 19). Built on the framework's roll call (roll-call.ts; the same one Manage > Servers uses): no
 	 * MemoryStore, no heartbeat writes.
 	 *
 	 * - One roll call per generation, owned here and shared with the dev menu. Every server answers asks with its row: the

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@typetorch/framework",
-	"version": "0.5.5",
+	"version": "0.5.6",
 	"description": "TypeTorch framework for roblox-ts: hot-swappable modules (dependency injection, lifecycle, troves), guarded networking, hot assets and the in-game dev menu. Ships inside every TypeTorch artifact.",
 	"license": "MIT",
 	"author": "TypeTorch",