@typetorch/framework 0.4.0 → 0.5.2

package/LICENSE

@@ -1,22 +1,22 @@
-MIT License
-
-Copyright (c) 2026 TypeTorch contributors
-Copyright (c) 2021 Flamework (src/reflection: the Reflect and Modding runtime, adapted from @flamework/core)
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 TypeTorch contributors
+Copyright (c) 2021 Flamework (src/reflection: the Reflect and Modding runtime, adapted from @flamework/core)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -152,8 +152,18 @@ export class CoinService extends Module implements OnStart {
 - **Dev menu:** devs (Studio, project members, dev badge) get a DEV button, `Ctrl+Shift+D` and `/tt dev`: artifact
   (with how long the server and client generations have run, the server's uptime and the build's age), server status,
   logs (server, own client, other players' clients), client and server dex, network stats, module state, a branch and
-  build picker (Server > Branch) and a Claude prompt. Prod-channel servers are read-only. The window can be dragged by
-  its header and resized from its corner (double-tap the header to reset).
+  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).
+- **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).
+- **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
+  else the menu is read-only, with a short reason: "Dev branch only", "Owners only on public servers", "Owner-switched
+  servers only". The rules themselves don't change (`TypeTorch.channel`, signatures, owner-only rollbacks).
 - **Panes and windows (dev menu):** every page shows in a pane with a small header: tap the title to pick another
   page, or use Split right, Split down, Open in new window and Close. Drag the line between two panes to resize them.
   The sidebar opens pages in the focused pane (the highlighted one; tap a pane to focus it). Floating windows move by
@@ -171,8 +181,8 @@ export class CoinService extends Module implements OnStart {
   strings (cut), numbers, booleans, nil, datatypes through `tostring`, an Instance as its full path, a Player as its
   name, `function`, `thread`, buffer sizes. Nothing is ever called (raw reads only: no metamethods, no getters); a
   value that is its own ancestor shows as a cycle. A key filter (open nodes stay listed), Refresh and Auto (every 2 s).
-  Server state comes from the op `state.inspect` (rate-limited, size-capped): devs on dev-channel servers, owners only
-  on prod-effective servers, since server state can hold player data.
+  Server state comes from the op `state.inspect` (rate-limited, size-capped): owners everywhere, other devs where the
+  dev-only tools are open to them, since server state can hold player data.
 - **Logs > Upload:** sends the logs shown (Server: this server's log ring; Client: your own client's; Others: the
   picked player's client) to the dev PC paired in the Claude tab, which saves them under `<repo>/.typetorch/logs/`.
   No Claude run, no prompt quota. Not paired: "Pair in the Claude tab first".
@@ -182,11 +192,12 @@ export class CoinService extends Module implements OnStart {
   verified head). A public switch lasts for that server's lifetime and is never stored, so new servers still boot the
   signed prod head. Others see "Join", which moves only them to a reserved server. Manage > Servers "Load a build..."
   does the same for this server, the ticked servers or a share of one branch (A/B pins), with one status line under
-  the list.
+  the list. A public server an owner switched to a dev branch opens the dev-only tools (Claude too) to owners.
 - **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** (dev-channel servers only): 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
+- **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
   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.
 
@@ -416,7 +427,7 @@ const variant = analytics.experiment("onboarding", ["short", "long"]); // same a
   row carries a UserId.
 - **Identities** (option `identity`, default on): once the pid is known, one row `{ pid, uid, t }` (the UserId, nothing
   else) per session goes to the dev's own server only, never into the events: duckdb games in the batch body, Basin
-  games to the fleet API (the settings' `fleet` url + `/v1/identity`, or the `identity` / `identityToken` settings). The
+  games to the backend (the record's `backend` url + `/v1/identity`, or the `identity` / `identityToken` settings). The
   analytics server keeps pid -> UserId in a deletable table (support lookups, Right to Erasure).
 - **Player ids:** DataStore `TypeTorchAnalytics`, key `p/<UserId>` -> `{ pid, first, last }`: one read per join, a
   write on the first join and at leave. Deleting the key (Right to Erasure) leaves that player's rows anonymous.
@@ -454,8 +465,9 @@ count affected players by pid, never by name) and counts its own DataStore and H
 menu **Server > Budget**: bars per Roblox limit for the player count, who spends it, the DataStore budget left, memory).
 
 **Settings** (server only, never sent to clients): the signed settings record's `analytics` field (kernel 0.3.8,
-plans/20), written with `typetorch settings set analytics -` (JSON on stdin; `@typetorch/analytics`' `writeSettings()`
-and `bun run local` call it). Every new copy applies live within seconds (the CLI pings servers). Before kernel 0.3.8
+plans/20), derived from `backend` by `typetorch backend setup` (`writeBackendSettings()` in `@typetorch/backend` runs it, and
+`bun run local` too). Every new copy applies live within seconds (the CLI pings servers). A Basin sink has no CLI writer
+since CLI 0.9: `backend setup` replaces it. Before kernel 0.3.8
 there are no settings unless the game passes `new AnalyticsEngine({ settings })`:
 
 ```json

package/out/analytics/SCHEMA.md

@@ -26,7 +26,7 @@ Integers are written with every digit (never exponent notation).
 | `seq` | int64 | That artifact's deploy seq (`0` when unknown) |
 | `branch` | string | Server branch |
 | `channel` | string | Effective channel: `prod` or `dev` |
-| `dev` | string | `desktop`, `phone`, `tablet`, `console`, `vr`, `unknown` (from the client's hello; `unknown` for server-only events and until the client reports) |
+| `dev` | string | The session's device class: `desktop`, `phone`, `tablet`, `console`, `vr`, `unknown`. Set once per session from the client's first hello (`unknown` for server-only events and until the client reports; frameworks after 0.4.2 keep it when a later hello says otherwise). How it is decided: the `session` / `device` row below |
 | `newp` | bool | The event belongs to the player's first-ever session |
 | `state` | string | The player's state **after** this event: `zone:<z>\|screen:<s>\|activity:<a>`, empty parts left out (`""` when nothing is known). Server-only events: `activity:<server activity>` or `""` |
 | `exp` | string | JSON object of the player's active experiments, `{"onboarding":"short"}`; `{}` when none |
@@ -58,7 +58,7 @@ First-ever-session detail, one row per packed chunk.
 | kind | name | props |
 |---|---|---|
 | session | `join` | `from`: `direct` (Home, search, sorts: Roblox doesn't say), `teleport` (same game), `teleport_game` (another game), `referral` (invite/referral link), `share` (launch data), `follow` (followed someone); `ctx?` (GameJoinContext.JoinSource name); `tp?` (had teleport data); `party?` (players teleported along); `age` (account age: `<1d`, `1-7d`, `7-30d`, `30-90d`, `90-365d`, `1-3y`, `3y+`); `prem` (Premium); `country?` (ISO code); `friends` (how many of the player's friends are in the server: one friend-list lookup per join, at most 10 pages, `0` when it fails); `ret` (days since the last visit, `-1` first visit or unknown); `late?` (the engine started over 60 s after the join). `t` is the join time |
-| session | `device` (src client) | `input` (`kbm`, `touch`, `gamepad`, `vr`, `unknown`), `w`, `h` (viewport points), `touch`, `kb`, `mouse`, `pad`, `vr`. Once per session |
+| session | `device` (src client) | `dev?` (the device class, as the `dev` column; frameworks after 0.4.2, older ones leave it out), `input` (`kbm`, `touch`, `gamepad`, `vr`, `unknown`), `w`, `h` (viewport points), `touch`, `kb`, `mouse`, `pad`, `vr`. Once per session. The class (Roblox gives game scripts no OS): `vr` when VRService.VREnabled; `console` when GuiService:IsTenFootInterface(); touch without a keyboard: `tablet` when the viewport's short side is 600 points or more, else `phone` (the first hello waits up to 2 s for a real viewport); a keyboard or mouse: `desktop` (touch laptops, tablets with a keyboard); else `unknown` |
 | session | `leave` | `secs` (session length), `why`: `left`, `shutdown`, `gone` (left while no generation ran the engine), `swap60?` (left within 60 s of a hot swap) |
 | tech | `server` | Every `techEvery` s: `fps` (physics), `hb` (Heartbeat rate), `mem` (MB, 10s), `players`, `ping50?`, `ping90?` (ms), `q`, `qr` (queued events, recordings), `dropped`, `sent`, `fails`, `health?`, `errors?` (kernel 0.3.2 health) |
 | tech | `client` (src client) | Every `techEvery` s: `fps`, `mem` (MB, 10s), `ping?` (ms) |
@@ -142,7 +142,7 @@ repo's `bun run local` does it). Every new signed copy applies at once, so dials
   "flushSeconds": 15,
   "recordShare": 1,
   "techEvery": 60,
-  "experiments": { "onboarding": { "active": true, "weights": [1, 1], "variant": "short" } }
+  "experiments": { "onboarding": { "active": true, "weights": [1, 1], "variant": "short", "players": { "123456": "long" } } }
 }
 ```
 
@@ -155,7 +155,7 @@ repo's `bun run local` does it). Every new signed copy applies at once, so dials
 | `flushSeconds` | 15 | 5..300 |
 | `recordShare` | 1 | 0..1, share of new players recorded (stable per pid) |
 | `techEvery` | 60 | 15..3600 seconds between tech samples |
-| `experiments` | none | Per experiment: `active: false` (everyone gets the first variant, not stamped), `weights` (per variant, in the game's order), `variant` (force one) |
+| `experiments` | none | Per experiment: `active: false` (everyone gets the first variant, not stamped), `weights` (per variant, in the game's order), `variant` (force one), `players` (`{ [UserId or pid]: variant }`, at most 200: forces one player's variant over everything else, stamped `forced`; each client's hello gets only its own entry). The CLI writes them: `typetorch experiment` |
 | `identity` | the settings' `fleet` url + `/v1/identity` | basin: where identity rows go (below); none and no `fleet` in the settings: not sent. duckdb: unused |
 | `identityToken` | the settings' `fleet` token | basin: the token for `identity`. Never logged |
 

package/out/analytics/client.luau

@@ -26,6 +26,7 @@ local CHUNK_SECONDS = _protocol.CHUNK_SECONDS
 local CHUNK_TARGET_BYTES = _protocol.CHUNK_TARGET_BYTES
 local CLIENT_BATCH_BYTES = _protocol.CLIENT_BATCH_BYTES
 local CLIENT_BATCH_MAX = _protocol.CLIENT_BATCH_MAX
+local deviceClass = _protocol.deviceClass
 local isEventName = _protocol.isEventName
 local _props = TS.import(script, script.Parent, "props")
 local encodeProps = _props.encodeProps
@@ -60,23 +61,28 @@ local IGNORED_GUIS = {
 }
 --* A screen that closes and opens again within this many seconds (ResetOnSpawn) never left. 
 local SCREEN_DEBOUNCE = 1
-local function deviceInfo()
+--* The camera's viewport in points (0 x 0 without a camera). 
+local function viewportSize()
 	local camera = Workspace.CurrentCamera
-	local viewport = if camera then camera.ViewportSize else Vector2.new(0, 0)
+	return if camera then camera.ViewportSize else Vector2.new(0, 0)
+end
+--* Seconds the first hello waits for a real viewport (a camera reports 1 x 1 for a moment at startup). 
+local VIEWPORT_WAIT = 2
+local function deviceInfo()
+	local viewport = viewportSize()
 	local vr = VRService.VREnabled
 	local consoleOk, isConsole = pcall(function()
 		return GuiService:IsTenFootInterface()
 	end)
-	local dev = "unknown"
-	if vr then
-		dev = "vr"
-	elseif consoleOk and isConsole then
-		dev = "console"
-	elseif UserInputService.TouchEnabled and not UserInputService.KeyboardEnabled then
-		dev = if math.min(viewport.X, viewport.Y) >= 600 then "tablet" else "phone"
-	elseif UserInputService.KeyboardEnabled or UserInputService.MouseEnabled then
-		dev = "desktop"
-	end
+	local dev = deviceClass({
+		vr = vr,
+		tenFoot = consoleOk and isConsole == true,
+		touch = UserInputService.TouchEnabled,
+		keyboard = UserInputService.KeyboardEnabled,
+		mouse = UserInputService.MouseEnabled,
+		w = viewport.X,
+		h = viewport.Y,
+	})
 	local last = UserInputService:GetLastInputType()
 	local input = "unknown"
 	if vr then
@@ -698,7 +704,7 @@ do
 				end
 			end)
 			if not ok then
-				warn("[src/analytics/client.ts:506]", `[analytics] server message failed: {string.sub(tostring(err), 1, 200)}`)
+				warn("[src/analytics/client.ts:518]", `[analytics] server message failed: {string.sub(tostring(err), 1, 200)}`)
 			end
 		end)
 		trove:add(function()
@@ -805,6 +811,11 @@ do
 	end
 	function ClientAnalytics:startSending()
 		self.trove:add(task.spawn(function()
+			-- The device class reads the viewport (phone vs tablet): give the camera a moment to report a real size.
+			local waitUntil = os.clock() + VIEWPORT_WAIT
+			while math.min(viewportSize().X, viewportSize().Y) <= 1 and os.clock() < waitUntil and not self.stopped do
+				task.wait(0.1)
+			end
 			-- Hello until the server answers (its engine may start later than this one): every 5 s for a minute, then
 			-- every 30 s.
 			local tries = 0
@@ -839,7 +850,7 @@ do
 	end
 	function ClientAnalytics:track(kind, name, props)
 		if not isEventName(name) then
-			warn("[src/analytics/client.ts:622]", `[analytics] {kind} event name must be 1-64 characters: {string.sub(tostring(name), 1, 80)}`)
+			warn("[src/analytics/client.ts:637]", `[analytics] {kind} event name must be 1-64 characters: {string.sub(tostring(name), 1, 80)}`)
 			return nil
 		end
 		self:push(kind, name, encodeProps(props))
@@ -897,7 +908,7 @@ do
 		end
 		local control = _condition
 		if not isExperimentName(name) or not isVariantList(variants) then
-			warn("[src/analytics/client.ts:656]", `[analytics] experiment("{string.sub(tostring(name), 1, 64)}"): bad name or variants (1-16 distinct names)`)
+			warn("[src/analytics/client.ts:671]", `[analytics] experiment("{string.sub(tostring(name), 1, 64)}"): bad name or variants (1-16 distinct names)`)
 			return control
 		end
 		local deadline = os.clock() + 10

package/out/analytics/experiments.d.ts

@@ -19,10 +19,16 @@ export interface Assignment {
 /**
  * The variant of experiment `name` for player `pid`. The first variant is the control: everyone gets it while the
  * experiment is switched off (`active: false`). `weights` split players unevenly (`[9, 1]`: 10% get the second);
- * `variant` forces one for everyone. The point in [0, 1) is unitHash(`<name>:<pid>`), so changing weights moves as few
+ * `variant` forces one for everyone; `player` (one player's entry of `players`, see `playerOverride`) forces one for
+ * this player and wins over the rest. The point in [0, 1) is unitHash(`<name>:<pid>`), so changing weights moves as few
  * players as possible.
  */
 export declare function assignVariant(pid: string, name: string, variants: string[], override?: ExperimentOverride): Assignment;
+/**
+ * One player's view of an override: `players` resolved to `player` (by UserId, else pid) and dropped, so a client's
+ * hello never carries other players' ids.
+ */
+export declare function playerOverride(override: ExperimentOverride | undefined, userId: number | undefined, pid: string): ExperimentOverride | undefined;
 /** Whether player `pid` is in the recorded share (0..1) of new players. Stable per player. */
 export declare function inShare(pid: string, share: number): boolean;
 /** A valid experiment name: 1-64 chars, letters, digits, `_`, `-`, `.`, `/`. */

package/out/analytics/experiments.luau

@@ -44,7 +44,8 @@ end
 	*
 	 * The variant of experiment `name` for player `pid`. The first variant is the control: everyone gets it while the
 	 * experiment is switched off (`active: false`). `weights` split players unevenly (`[9, 1]`: 10% get the second);
-	 * `variant` forces one for everyone. The point in [0, 1) is unitHash(`<name>:<pid>`), so changing weights moves as few
+	 * `variant` forces one for everyone; `player` (one player's entry of `players`, see `playerOverride`) forces one for
+	 * this player and wins over the rest. The point in [0, 1) is unitHash(`<name>:<pid>`), so changing weights moves as few
 	 * players as possible.
 	 
 ]]
@@ -61,6 +62,18 @@ local function assignVariant(pid, name, variants, override)
 			forced = false,
 		}
 	end
+	local _mine = override
+	if _mine ~= nil then
+		_mine = _mine.player
+	end
+	local mine = _mine
+	if type(mine) == "string" and table.find(variants, mine) ~= nil then
+		return {
+			variant = mine,
+			active = true,
+			forced = true,
+		}
+	end
 	local _result = override
 	if _result ~= nil then
 		_result = _result.active
@@ -129,6 +142,34 @@ local function assignVariant(pid, name, variants, override)
 		forced = false,
 	}
 end
+--[[
+	*
+	 * One player's view of an override: `players` resolved to `player` (by UserId, else pid) and dropped, so a client's
+	 * hello never carries other players' ids.
+	 
+]]
+local function playerOverride(override, userId, pid)
+	if override == nil then
+		return nil
+	end
+	local result = {
+		active = override.active,
+		weights = override.weights,
+		variant = override.variant,
+	}
+	local players = override.players
+	if players ~= nil then
+		local _condition = (if userId ~= nil then players[tostring(userId)] else nil)
+		if _condition == nil then
+			_condition = players[pid]
+		end
+		local mine = _condition
+		if mine ~= nil then
+			result.player = mine
+		end
+	end
+	return result
+end
 --* Whether player `pid` is in the recorded share (0..1) of new players. Stable per player. 
 local function inShare(pid, share)
 	if share >= 1 then
@@ -182,6 +223,7 @@ return {
 	hash32 = hash32,
 	unitHash = unitHash,
 	assignVariant = assignVariant,
+	playerOverride = playerOverride,
 	inShare = inShare,
 	isExperimentName = isExperimentName,
 	isVariantList = isVariantList,

package/out/analytics/protocol.d.ts

@@ -35,6 +35,27 @@ export interface HelloInfo {
     /** Seconds from the client starting to the engine starting (first client generation only). */
     load?: number;
 }
+/** What the client knows about its device when it says hello (UserInputService, VRService, GuiService, the camera). */
+export interface DeviceFacts {
+    vr: boolean;
+    /** GuiService:IsTenFootInterface(): a console (Xbox, PlayStation). */
+    tenFoot: boolean;
+    touch: boolean;
+    keyboard: boolean;
+    mouse: boolean;
+    /** Viewport size in points (0 when the camera has none yet). */
+    w: number;
+    h: number;
+}
+/** A touch-only device whose viewport's short side is at least this many points is a tablet, else a phone. */
+export declare const TABLET_MIN_SHORT_SIDE = 600;
+/**
+ * The session's device class (the `dev` column), in this order: VR headset; console (ten-foot interface); touch without
+ * a keyboard: tablet when the viewport's short side is 600 points or more, else phone (also when the viewport isn't
+ * known); a keyboard or mouse: desktop (a touch laptop or a tablet with a keyboard counts here); else unknown. Roblox
+ * gives game scripts no OS, so this is the closest a game gets.
+ */
+export declare function deviceClass(f: DeviceFacts): DeviceKind;
 /** [ageMs, kind, name, propsJson] */
 export type ClientEvent = [
     age: number,

package/out/analytics/protocol.luau

@@ -22,6 +22,32 @@ local CLIENT_BATCH_BYTES = 12000
 local CHUNK_TARGET_BYTES = 6000
 local CHUNK_MAX_BYTES = 16384
 local CHUNK_SECONDS = 10
+--* What the client knows about its device when it says hello (UserInputService, VRService, GuiService, the camera). 
+--* A touch-only device whose viewport's short side is at least this many points is a tablet, else a phone. 
+local TABLET_MIN_SHORT_SIDE = 600
+--[[
+	*
+	 * The session's device class (the `dev` column), in this order: VR headset; console (ten-foot interface); touch without
+	 * a keyboard: tablet when the viewport's short side is 600 points or more, else phone (also when the viewport isn't
+	 * known); a keyboard or mouse: desktop (a touch laptop or a tablet with a keyboard counts here); else unknown. Roblox
+	 * gives game scripts no OS, so this is the closest a game gets.
+	 
+]]
+local function deviceClass(f)
+	if f.vr then
+		return "vr"
+	end
+	if f.tenFoot then
+		return "console"
+	end
+	if f.touch and not f.keyboard then
+		return if math.min(f.w, f.h) >= TABLET_MIN_SHORT_SIDE then "tablet" else "phone"
+	end
+	if f.keyboard or f.mouse then
+		return "desktop"
+	end
+	return "unknown"
+end
 --* [ageMs, kind, name, propsJson] 
 local DEVICES = {
 	["desktop"] = true,
@@ -127,6 +153,7 @@ local function cleanClientEvent(value)
 	return { math.floor(age), kind, name, props }
 end
 return {
+	deviceClass = deviceClass,
 	cleanHello = cleanHello,
 	isEventName = isEventName,
 	cleanClientEvent = cleanClientEvent,
@@ -136,5 +163,6 @@ return {
 	CHUNK_TARGET_BYTES = CHUNK_TARGET_BYTES,
 	CHUNK_MAX_BYTES = CHUNK_MAX_BYTES,
 	CHUNK_SECONDS = CHUNK_SECONDS,
+	TABLET_MIN_SHORT_SIDE = TABLET_MIN_SHORT_SIDE,
 	CLIENT_KINDS = CLIENT_KINDS,
 }

package/out/analytics/schema.d.ts

@@ -86,6 +86,13 @@ export interface ExperimentOverride {
     weights?: number[];
     /** Everyone gets this variant (must be one of the game's variants). */
     variant?: string;
+    /**
+     * Per-player forced variants, keyed by UserId (`"123456"`) or pid (32 hex): wins over `active`, `variant` and
+     * `weights` for that player (QA, support). Server-only: a client gets only its own entry, as `player`.
+     */
+    players?: Record<string, string>;
+    /** This player's forced variant (resolved from `players` by `playerOverride`; what a client's hello carries). */
+    player?: string;
 }
 /** The sink settings: the signed settings' `analytics` (kernel 0.3.8, server-only), or `new AnalyticsEngine({ settings })`. */
 export interface AnalyticsSettings {

package/out/analytics/server.d.ts

@@ -101,6 +101,7 @@ export declare class ServerAnalytics {
     /** Activity: per player, or server-wide (every player without their own) when `player` is undefined. */
     setActivity(player: Player | undefined, activity: string | undefined): void;
     setScreen(session: PlayerSession, screen: string, src: "server" | "client", t?: number, props?: string): void;
+    /** The overrides as this player sees them (their own `players` entry only; hello). */
     private overrides;
     /** The player's variant (stamped on their later events while active). May yield until the player's pid loads. */
     experiment(player: Player, name: string, variants: string[]): string;

package/out/analytics/server.luau

@@ -28,6 +28,7 @@ local assignVariant = _experiments.assignVariant
 local inShare = _experiments.inShare
 local isExperimentName = _experiments.isExperimentName
 local isVariantList = _experiments.isVariantList
+local playerOverride = _experiments.playerOverride
 local _protocol = TS.import(script, script.Parent, "protocol")
 local CHANNEL = _protocol.CHANNEL
 local CHUNK_MAX_BYTES = _protocol.CHUNK_MAX_BYTES
@@ -586,11 +587,11 @@ do
 		end
 		_self:emit(_exp, "state", "screen", _condition, src, t)
 	end
-	function ServerAnalytics:overrides()
+	function ServerAnalytics:overrides(player, session)
 		local result = {}
 		if self.settings then
 			for name, override in self.settings.experiments do
-				result[name] = override
+				result[name] = playerOverride(override, player.UserId, session.pid)
 			end
 		end
 		return result
@@ -602,7 +603,7 @@ do
 		end
 		local control = _condition
 		if not isExperimentName(name) or not isVariantList(variants) then
-			warn("[src/analytics/server.ts:522]", `[analytics] experiment("{string.sub(tostring(name), 1, 64)}"): bad name or variants (1-16 distinct names)`)
+			warn("[src/analytics/server.ts:523]", `[analytics] experiment("{string.sub(tostring(name), 1, 64)}"): bad name or variants (1-16 distinct names)`)
 			return control
 		end
 		local session = self:sessionOf(player)
@@ -641,7 +642,7 @@ do
 			local _name_1 = name
 			_result = _experiments_1[_name_1]
 		end
-		local assignment = assignVariant(_exp_1, _exp_2, _exp_3, _result)
+		local assignment = assignVariant(_exp_1, _exp_2, _exp_3, playerOverride(_result, player.UserId, session.pid))
 		local _exp_4 = session.exp
 		local _name_1 = name
 		local current = _exp_4[_name_1]
@@ -667,7 +668,7 @@ do
 	function ServerAnalytics:applySettings(parsed)
 		local errorsText = table.concat(parsed.errors, "; ")
 		if errorsText ~= table.concat(self.settingsErrors, "; ") and errorsText ~= "" then
-			warn("[src/analytics/server.ts:557]", `[analytics] the sink settings (settings.backend or settings.analytics): {errorsText}`)
+			warn("[src/analytics/server.ts:558]", `[analytics] the sink settings (settings.backend or settings.analytics): {errorsText}`)
 		end
 		self.settingsErrors = parsed.errors
 		local hadSettings = self.settings ~= nil
@@ -697,7 +698,7 @@ do
 		-- `new AnalyticsEngine({ settings })`.
 		if not settingsSupported() then
 			if self.kernel ~= nil and self.kernel.test ~= true then
-				warn("[src/analytics/server.ts:584]", `[analytics] no sink settings: they come from the signed settings record (kernel 0.3.8+, "typetorch backend setup"); this server runs kernel {self.kernel.kernelVersion}. Or pass new AnalyticsEngine(\{ settings \})`)
+				warn("[src/analytics/server.ts:585]", `[analytics] no sink settings: they come from the signed settings record (kernel 0.3.8+, "typetorch backend setup"); this server runs kernel {self.kernel.kernelVersion}. Or pass new AnalyticsEngine(\{ settings \})`)
 			end
 			self.settingsTried = true
 			return nil
@@ -1273,7 +1274,7 @@ do
 			_condition = DEFAULT_TECH_EVERY
 		end
 		_object[_left] = _condition
-		_object.exps = self:overrides()
+		_object.exps = self:overrides(player, session)
 		local hello = _object
 		dispatcher.kernel:send(player, CHANNEL, "hi", hello)
 	end
@@ -1284,9 +1285,14 @@ do
 		end
 		local first = session.device == nil
 		session.device = info
-		session.dev = info.dev
+		-- The device class is the session's: set by the first hello and kept (a later hello after a hot swap, or a keyboard
+		-- plugged into a tablet, doesn't move the session's rows to another class), unless the first one didn't know.
+		if first or session.dev == "unknown" then
+			session.dev = info.dev
+		end
 		if first and self.options.sessions ~= false then
 			self:emit(session, "session", "device", encodeProps({
+				dev = info.dev,
 				input = info.input,
 				w = info.w,
 				h = info.h,
@@ -1494,7 +1500,7 @@ do
 				end
 			end)
 			if not ok then
-				warn("[src/analytics/server.ts:1075]", `[analytics] client message failed: {string.sub(tostring(err), 1, 200)}`)
+				warn("[src/analytics/server.ts:1078]", `[analytics] client message failed: {string.sub(tostring(err), 1, 200)}`)
 			end
 		end)
 		self.trove:add(function()
@@ -1777,7 +1783,7 @@ do
 		self.lastWarnAt = now
 		local more = if self.suppressed > 0 then ` (+{self.suppressed} more in the last minute)` else ""
 		self.suppressed = 0
-		warn("[src/analytics/server.ts:1270]", `[analytics] {message}{more}`)
+		warn("[src/analytics/server.ts:1273]", `[analytics] {message}{more}`)
 		return true
 	end
 	function ServerAnalytics:noteSuccess()

package/out/analytics/settings.d.ts

@@ -13,6 +13,8 @@ export interface ParsedSettings {
     settings?: ResolvedSettings;
     errors: string[];
 }
+/** Per-player overrides one experiment may hold (`players`). */
+export declare const EXPERIMENT_PLAYERS_MAX = 200;
 /**
  * Reads the settings value: a table (the configs API stores JSON objects) or a JSON string. `undefined` (no key) gives
  * no settings and no errors. Unknown fields are ignored.

package/out/analytics/settings.luau

@@ -35,6 +35,19 @@ local function clampNumber(value, fallback, low, high, label, errors)
 	end
 	return math.clamp(value, low, high)
 end
+--* Per-player overrides one experiment may hold (`players`). 
+local EXPERIMENT_PLAYERS_MAX = 200
+--* A `players` key: a UserId (digits) or a pid (32 lowercase hex). 
+local function isPlayerKey(key)
+	local _key = key
+	if not (type(_key) == "string") then
+		return false
+	end
+	if #key >= 1 and #key <= 19 and (string.match(key, "^%d+$")) ~= nil then
+		return true
+	end
+	return #key == 32 and (string.match(key, "^[0-9a-f]+$")) ~= nil
+end
 local function parseExperiments(value, errors)
 	local result = {}
 	if value == nil then
@@ -103,6 +116,29 @@ local function parseExperiments(value, errors)
 				table.insert(_errors, _arg0)
 			end
 		end
+		if entry.players ~= nil then
+			local players = {}
+			local _players = entry.players
+			local ok = type(_players) == "table"
+			local count = 0
+			if ok then
+				for key, variant in pairs(entry.players) do
+					count += 1
+					if not isPlayerKey(key) or not (type(variant) == "string") or #variant < 1 or #variant > 32 then
+						ok = false
+					else
+						players[key] = variant
+					end
+				end
+			end
+			if ok and count <= EXPERIMENT_PLAYERS_MAX then
+				override.players = players
+			else
+				local _errors = errors
+				local _arg0 = `experiments.{name}.players must map UserIds or pids to variant names (at most {EXPERIMENT_PLAYERS_MAX})`
+				table.insert(_errors, _arg0)
+			end
+		end
 		result[name] = override
 	end
 	return result
@@ -326,4 +362,5 @@ return {
 	recordsSupported = recordsSupported,
 	DEFAULT_FLUSH_SECONDS = DEFAULT_FLUSH_SECONDS,
 	DEFAULT_TECH_EVERY = DEFAULT_TECH_EVERY,
+	EXPERIMENT_PLAYERS_MAX = EXPERIMENT_PLAYERS_MAX,
 }