@typetorch/framework 0.5.5 → 0.5.7

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
@@ -157,10 +185,25 @@ export class CoinService extends Module implements OnStart {
   build picker (Server > Branch) and a Claude prompt. The sidebar, top to bottom: Artifact, Server, Network, Modules,
   Manage, Logs, Dex, Claude. The window can be dragged by its header and resized from its corner (double-tap the
   header to reset).
+- **Command palette (`Ctrl+K`, `Cmd+K` on a Mac, or the search button in the menu header):** opens the dev menu if it
+  is closed and searches every command the dev may run now (fuzzy: `swb` finds *Switch branch*). Up / Down pick,
+  Enter runs, Shift+Enter opens a page in a split, Escape closes; recent commands come first on an empty query. Never
+  fires while typing in chat or a text box. Commands: open any page; split right / down, open the pane in a new window,
+  close it, dock all windows; Reload, Roll back, switch branch, load a build here, join a server on a branch or build
+  (the Branch tab's rules and words, `devtools/build-actions.ts`), New server and Join a listed server (owners); find a
+  player by name, display name or UserId and open them in Manage > Players or their Kick / Ban card (owners); copy the
+  job id, artifact id, commit, branch or place version (the copy popup); "Ask Claude: ..." puts the query in the Claude
+  draft. Anything that swaps what runs on the server takes a second Enter or tap to confirm. The kernel and the server
+  re-check every request. Core: `devtools/commands.ts` (pure, Lune-tested by `scripts/test-commands.luau`).
 - **Server TPS (framework 0.4.2, kernel 0.4.2):** Server > Status has a *TPS* line next to Memory and Lua heap: the
   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 +241,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 +410,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 +430,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 +478,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 +553,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 +585,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/admin-ui.d.ts

@@ -15,6 +15,28 @@ export interface AdminDeps {
         ok: boolean,
         result: unknown
     ];
+    /** The command palette's player lookup (client.ts): who Manage > Players shows next. */
+    playerFocus?: PlayerFocus;
+}
+/** What the command palette asked Manage > Players for: show this player, and open Kick or Ban for them. */
+export interface PlayerFocusRequest {
+    userId: number;
+    action?: "kick" | "ban";
+    at: number;
+}
+/**
+ * The command palette's way into Manage > Players (one per client generation, client.ts): `request` remembers a player
+ * and tells an open Players tab; a tab that mounts later takes it after its first load. The Kick and Ban cards are the
+ * tab's own (reason, duration, armed button); the server re-checks every action.
+ */
+export declare class PlayerFocus {
+    private pending?;
+    private readonly listeners;
+    request(userId: number, action?: "kick" | "ban"): void;
+    /** The waiting request (dropped after FOCUS_WAIT s), taken once. */
+    take(): PlayerFocusRequest | undefined;
+    waiting(): boolean;
+    listen(trove: Trove, listener: () => void): void;
 }
 /** The Manage sub-tabs, keyed like client.ts RENDER ("Tab/Sub"). */
 export declare function adminTabs(deps: AdminDeps): Record<string, (tab: AdminTab) => void>;

package/out/devtools/admin-ui.luau

@@ -115,6 +115,64 @@ local ERRORS = {
 	publish_failed = "Couldn't send",
 	["not a dev"] = "Not a dev",
 }
+--* How long a palette request waits for Manage > Players to load (seconds). 
+local FOCUS_WAIT = 15
+--* What the command palette asked Manage > Players for: show this player, and open Kick or Ban for them. 
+--[[
+	*
+	 * The command palette's way into Manage > Players (one per client generation, client.ts): `request` remembers a player
+	 * and tells an open Players tab; a tab that mounts later takes it after its first load. The Kick and Ban cards are the
+	 * tab's own (reason, duration, armed button); the server re-checks every action.
+	 
+]]
+local PlayerFocus
+do
+	PlayerFocus = setmetatable({}, {
+		__tostring = function()
+			return "PlayerFocus"
+		end,
+	})
+	PlayerFocus.__index = PlayerFocus
+	function PlayerFocus.new(...)
+		local self = setmetatable({}, PlayerFocus)
+		return self:constructor(...) or self
+	end
+	function PlayerFocus:constructor()
+		self.listeners = {}
+	end
+	function PlayerFocus:request(userId, action)
+		self.pending = {
+			userId = userId,
+			action = action,
+			at = os.clock(),
+		}
+		for listener in self.listeners do
+			task.spawn(listener)
+		end
+	end
+	function PlayerFocus:take()
+		local pending = self.pending
+		self.pending = nil
+		return if pending ~= nil and os.clock() - pending.at <= FOCUS_WAIT then pending else nil
+	end
+	function PlayerFocus:waiting()
+		return self.pending ~= nil
+	end
+	function PlayerFocus:listen(trove, listener)
+		local _listeners = self.listeners
+		local _listener = listener
+		_listeners[_listener] = true
+		trove:add(function()
+			local _listeners_1 = self.listeners
+			local _listener_1 = listener
+			-- ▼ Set.delete ▼
+			local _valueExisted = _listeners_1[_listener_1] ~= nil
+			_listeners_1[_listener_1] = nil
+			-- ▲ Set.delete ▲
+			return _valueExisted
+		end)
+	end
+end
 --* The Manage sub-tabs, keyed like client.ts RENDER ("Tab/Sub"). 
 local renderPlayers, renderServers, renderBans
 local function adminTabs(deps)
@@ -140,7 +198,7 @@ local function every(trove, interval, callback)
 		while true do
 			local ok, err = pcall(callback)
 			if not ok then
-				warn("[src/devtools/admin-ui.ts:162]", `[devtools] manage refresh failed: {err}`)
+				warn("[src/devtools/admin-ui.ts:205]", `[devtools] manage refresh failed: {err}`)
 			end
 			task.wait(interval)
 		end
@@ -786,6 +844,7 @@ function renderPlayers(tab, deps)
 	local list = page:group(4)
 	local rows = {}
 	local busy = false
+	local loaded = false
 	local act = function(label, op, userId, doneText)
 		if busy then
 			return nil
@@ -1072,6 +1131,47 @@ function renderPlayers(tab, deps)
 		frame.Parent = list.frame
 		return row
 	end
+	-- The command palette's player lookup: scroll to the player and flash their row, or open Kick / Ban for them.
+	local applyFocus = function()
+		local focus = deps.playerFocus
+		if not focus or not loaded or not focus:waiting() then
+			return nil
+		end
+		local want = focus:take()
+		if not want then
+			return nil
+		end
+		local _userId = want.userId
+		local row = rows[_userId]
+		if not row then
+			setResult("Not in this server", COLORS.warn)
+			return nil
+		end
+		local content = tab.content
+		local top = row.frame.AbsolutePosition.Y - content.AbsolutePosition.Y + content.CanvasPosition.Y
+		content.CanvasPosition = Vector2.new(0, math.max(0, top - 8))
+		row.frame.BackgroundColor3 = COLORS.button
+		bump(row.frame)
+		trove:add(task.delay(1.5, function()
+			if row.frame.Parent then
+				row.frame.BackgroundColor3 = COLORS.row
+			end
+		end))
+		local data = row.data
+		if want.action == "kick" then
+			if data.can.kick then
+				openKick(data)
+			else
+				setResult(`Can't kick {data.displayName}`, COLORS.bad)
+			end
+		elseif want.action == "ban" then
+			if data.can.ban then
+				openBan(data)
+			else
+				setResult(`Can't ban {data.displayName}`, COLORS.bad)
+			end
+		end
+	end
 	local refresh = function()
 		local _binding_1 = deps.call("admin.players")
 		local ok = _binding_1[1]
@@ -1137,6 +1237,12 @@ function renderPlayers(tab, deps)
 			row.frame:Destroy()
 			rows[userId] = nil
 		end
+		loaded = true
+		applyFocus()
+	end
+	local _result = deps.playerFocus
+	if _result ~= nil then
+		_result:listen(trove, applyFocus)
 	end
 	every(trove, PLAYERS_REFRESH, refresh)
 end
@@ -2656,4 +2762,5 @@ end
 return {
 	adminTabs = adminTabs,
 	migrateControl = migrateControl,
+	PlayerFocus = PlayerFocus,
 }

package/out/devtools/build-actions.d.ts

@@ -38,6 +38,20 @@ export declare function buildAction(ctx: PickerContext, entry: {
     channel: string;
 }): BuildAction;
 export declare function buildLabel(action: BuildAction): string;
+/**
+ * The "pin" op's payload for a build the viewer may pin (`buildAction` "pin"): an A/B experiment pin when an owner pins
+ * on an unsigned public server whose kernel has experiments (0.2.3+), else the plain asset id. The Branch tab and the
+ * command palette both send this.
+ */
+export declare function pinPayload(ctx: PickerContext, assetId: number): number | {
+    assetId: number;
+    experiment: true;
+};
+/**
+ * Whether an action swaps what runs on THIS server (every player on it): the owner's switch or load ("here"), the stored
+ * switch and the dev pin. "join" moves only you. The command palette makes all of them two-step.
+ */
+export declare function swapsServer(action: BranchAction | BuildAction): boolean;
 /** Kernels before 0.3.4 on prod servers: in-game loads can't reach them, only `typetorch pin`. */
 export declare function showCliNote(ctx: PickerContext): boolean;
 /** Whether this client's player is an owner (cosmetic: the kernel re-checks). An older kernel's "admin" is a dev. */

package/out/devtools/build-actions.luau

@@ -63,6 +63,29 @@ end
 local function buildLabel(action)
 	return if action == "join" then "Join" else "Load here"
 end
+--[[
+	*
+	 * The "pin" op's payload for a build the viewer may pin (`buildAction` "pin"): an A/B experiment pin when an owner pins
+	 * on an unsigned public server whose kernel has experiments (0.2.3+), else the plain asset id. The Branch tab and the
+	 * command palette both send this.
+	 
+]]
+local function pinPayload(ctx, assetId)
+	local abInPlace = ctx.serverType == "public" and ctx.isOwner and ctx.experiments and not ctx.signedOnly
+	return if abInPlace then {
+		assetId = assetId,
+		experiment = true,
+	} else assetId
+end
+--[[
+	*
+	 * Whether an action swaps what runs on THIS server (every player on it): the owner's switch or load ("here"), the stored
+	 * switch and the dev pin. "join" moves only you. The command palette makes all of them two-step.
+	 
+]]
+local function swapsServer(action)
+	return action == "here" or action == "stored" or action == "pin"
+end
 --* Kernels before 0.3.4 on prod servers: in-game loads can't reach them, only `typetorch pin`. 
 local function showCliNote(ctx)
 	return not ctx.switchKernel and ctx.signedOnly and (ctx.isOwner or ctx.serverType ~= "public")
@@ -255,6 +278,8 @@ return {
 	branchLabel = branchLabel,
 	buildAction = buildAction,
 	buildLabel = buildLabel,
+	pinPayload = pinPayload,
+	swapsServer = swapsServer,
 	showCliNote = showCliNote,
 	viewerIsOwner = viewerIsOwner,
 	switchOffered = switchOffered,

package/out/devtools/claude-ui.d.ts

@@ -45,5 +45,10 @@ type Block = {
 export declare function parseMarkdown(text: string): Block[];
 /** Inline Markdown → RichText: escapes &, < and > first, then `code`, links, **bold** and *italic*. */
 export declare function inline(text: string): string;
+/**
+ * The command palette's "Ask Claude": replaces the draft with `text` (kept in the persist store like typing) and, when
+ * the Claude tab is open, shows it in its message box with the caret at the end. Nothing is sent.
+ */
+export declare function setClaudeDraft(kernel: ClientKernel, text: string): void;
 export declare function renderClaudeChat(tab: ClaudeChatTab, deps: ClaudeChatDeps): void;
 export {};

package/out/devtools/claude-ui.luau

@@ -1065,19 +1065,37 @@ local function readableDetail(text)
 	return if #out > DETAIL_CHARS then `{string.sub(out, 1, DETAIL_CHARS)}\n...` else out
 end
 -- The tab -------------------------------------------------------------------------------------------------------------
-local buildClaudeChat
-local function renderClaudeChat(tab, deps)
-	local _binding = deps
-	local kernel = _binding.kernel
-	local call = _binding.call
-	local trove = tab.trove
-	local state = kernel:persist(PERSIST_KEY, function()
+local function chatState(kernel)
+	return kernel:persist(PERSIST_KEY, function()
 		return {
 			draft = "",
 			attachPath = false,
 			attachErrors = false,
 		}
 	end)
+end
+--* The open Claude tab's message box (one at most: Claude is a single page), for setClaudeDraft. 
+local showDraft
+--[[
+	*
+	 * The command palette's "Ask Claude": replaces the draft with `text` (kept in the persist store like typing) and, when
+	 * the Claude tab is open, shows it in its message box with the caret at the end. Nothing is sent.
+	 
+]]
+local function setClaudeDraft(kernel, text)
+	chatState(kernel).draft = text
+	local _result = showDraft
+	if _result ~= nil then
+		_result(text)
+	end
+end
+local buildClaudeChat
+local function renderClaudeChat(tab, deps)
+	local _binding = deps
+	local kernel = _binding.kernel
+	local call = _binding.call
+	local trove = tab.trove
+	local state = chatState(kernel)
 	-- The chat takes the content's place in the window body (like the explorer).
 	local content = tab.content
 	local host = trove:add(make("Frame", {
@@ -1549,6 +1567,17 @@ function buildClaudeChat(tab, deps, host, state)
 		state.draft = text
 	end)
 	fitBox()
+	local myShowDraft = function(text)
+		box.Text = text
+		box:CaptureFocus()
+		box.CursorPosition = #text + 1
+	end
+	showDraft = myShowDraft
+	trove:add(function()
+		if showDraft == myShowDraft then
+			showDraft = nil
+		end
+	end)
 	-- The actions row draws above the message box (the "+" menu hangs over it).
 	local actions = make("Frame", {
 		BackgroundTransparency = 1,
@@ -4595,5 +4624,6 @@ return {
 	stripEmoji = stripEmoji,
 	parseMarkdown = parseMarkdown,
 	inline = inline,
+	setClaudeDraft = setClaudeDraft,
 	renderClaudeChat = renderClaudeChat,
 }

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;