@flow-industries/id 0.18.0 → 0.19.0

package/dist/sdk/hex.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Normalizes a hex string to the `0x`-prefixed form ox/viem expect.
+ *
+ * The template literal infers `` `0x${string}` `` on its own, so callers need no assertion.
+ */
+export declare const hex0x: (value: string) => `0x${string}`;

package/dist/sdk/hex.js

@@ -0,0 +1,6 @@
+/**
+ * Normalizes a hex string to the `0x`-prefixed form ox/viem expect.
+ *
+ * The template literal infers `` `0x${string}` `` on its own, so callers need no assertion.
+ */
+export const hex0x = (value) => `0x${value.replace(/^0x/, "")}`;

package/dist/sdk/id-host.d.ts

@@ -5,7 +5,7 @@
  * without carrying any per-app configuration.
  */
 export declare const DEFAULT_ISSUER_URL = "https://id.flow.industries";
-/** Flow ID origin of a local auth stack (`bun run dev` in the auth repo). */
+/** Legacy fallback for local consumers that do not pass the dev.sh-selected host. */
 export declare const LOCAL_ISSUER_URL = "http://localhost:5175";
 /**
  * Path of the first-party session route every app serves from its own origin

package/dist/sdk/id-host.js

@@ -5,7 +5,7 @@
  * without carrying any per-app configuration.
  */
 export const DEFAULT_ISSUER_URL = "https://id.flow.industries";
-/** Flow ID origin of a local auth stack (`bun run dev` in the auth repo). */
+/** Legacy fallback for local consumers that do not pass the dev.sh-selected host. */
 export const LOCAL_ISSUER_URL = "http://localhost:5175";
 /**
  * Path of the first-party session route every app serves from its own origin
@@ -24,7 +24,7 @@ export function isLocalHostname(hostname) {
  * to the request's own origin.
  */
 export function defaultAudience(requestOrigin) {
-    return ((typeof process !== "undefined" ? process.env?.APP_ORIGIN : undefined) ??
+    return ((globalThis.process !== undefined ? process.env?.APP_ORIGIN : undefined) ??
         requestOrigin);
 }
 /**
@@ -34,11 +34,10 @@ export function defaultAudience(requestOrigin) {
  * behalf of a request (servers have no `window`).
  */
 export function defaultIdHost(appOrigin) {
-    if (typeof process !== "undefined" && process.env?.FLOW_ID_HOST) {
+    if (globalThis.process !== undefined && process.env?.FLOW_ID_HOST) {
         return process.env.FLOW_ID_HOST;
     }
-    const origin = appOrigin ??
-        (typeof window !== "undefined" ? window.location.origin : undefined);
+    const origin = appOrigin ?? ("window" in globalThis ? window.location.origin : undefined);
     if (origin) {
         try {
             if (isLocalHostname(new URL(origin).hostname))

package/dist/sdk/json.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The value domain for data that arrives as JSON — request bodies, provider responses, stored
+ * blobs, postMessage payloads.
+ *
+ * Primitive tests are written as coercion round-trips rather than `typeof`: `String(x) === x` and
+ * `Number(x) === x` hold only for the primitive itself, so each one establishes the value's
+ * contract instead of narrowing a representation.
+ */
+export type RawValue = string | number | boolean | null | undefined | RawValue[] | RawRecord;
+export type RawRecord = {
+    readonly [key: string]: RawValue;
+};
+export declare const isString: (v: RawValue) => v is string;
+export declare const isBool: (v: RawValue) => v is boolean;
+export declare const isNum: (v: RawValue) => v is number;
+export declare const isRecord: (v: RawValue) => v is RawRecord;
+export declare const isStrings: (v: RawValue) => v is string[];

package/dist/sdk/json.js

@@ -0,0 +1,5 @@
+export const isString = (v) => String(v) === v;
+export const isBool = (v) => v === true || v === false;
+export const isNum = (v) => Number(v) === v && Number.isFinite(v);
+export const isRecord = (v) => v !== null && v !== undefined && !Array.isArray(v) && Object(v) === v;
+export const isStrings = (v) => Array.isArray(v) && v.every((entry) => isString(entry));

package/dist/sdk/react/flow-widget.js

@@ -29,8 +29,8 @@ export function FlowWidget({ widget, className, host, theme, }) {
             widget,
             container,
             flow,
-            ...(host ? { host } : {}),
-            ...(themeRef.current ? { theme: themeRef.current } : {}),
+            host: host ? host : undefined,
+            theme: themeRef.current ? themeRef.current : undefined,
         });
         handleRef.current = handle;
         if (handle.frame) {

package/dist/sdk/react/hooks.d.ts

@@ -39,24 +39,28 @@ export declare function useFlowId(): {
  * Fetches the public room list once (call `reload` to refresh). Pagination
  * stays manual: pass the returned `nextCursor` back through `flow.rooms.list`.
  */
-export declare function useRooms(): {
+/** What {@link useRooms} returns. */
+export type RoomsState = {
     rooms: RoomSummary[];
     nextCursor: string | null;
     loading: boolean;
     error: Error | null;
     reload: () => void;
 };
+export declare function useRooms(): RoomsState;
 /**
  * Fetches one room's detail, and optionally polls its live presence when
  * `presencePollMs` is set (polling until the presence store grows a push
  * channel). Re-fetches when the slug changes; call `reload` to refresh.
  */
-export declare function useRoom(slug: string, options?: {
-    presencePollMs?: number;
-}): {
+/** What {@link useRoom} returns. */
+export type RoomState = {
     room: RoomDetail | null;
     presence: RoomPresenceSnapshot | null;
     loading: boolean;
     error: Error | null;
     reload: () => void;
 };
+export declare function useRoom(slug: string, options?: {
+    presencePollMs?: number;
+}): RoomState;

package/dist/sdk/react/hooks.js

@@ -1,7 +1,7 @@
 import { useCallback, useContext, useEffect, useState, useSyncExternalStore, } from "react";
 import { getFlow as getSingletonFlow } from "../client/create-flow";
 import { FlowContext } from "./provider";
-const asError = (e) => e instanceof Error ? e : new Error(String(e));
+const asError = (cause) => cause instanceof Error ? cause : new Error(String(cause));
 /**
  * Returns the Flow instance to use. Resolution order:
  *  1. The instance from a `<FlowIdProvider>` ancestor (if any)
@@ -54,10 +54,6 @@ export function useFlowId() {
         getToken: flow.getToken,
     };
 }
-/**
- * Fetches the public room list once (call `reload` to refresh). Pagination
- * stays manual: pass the returned `nextCursor` back through `flow.rooms.list`.
- */
 export function useRooms() {
     const flow = useFlow();
     const [result, setResult] = useState(null);
@@ -80,11 +76,6 @@ export function useRooms() {
         reload: load,
     };
 }
-/**
- * Fetches one room's detail, and optionally polls its live presence when
- * `presencePollMs` is set (polling until the presence store grows a push
- * channel). Re-fetches when the slug changes; call `reload` to refresh.
- */
 export function useRoom(slug, options) {
     const flow = useFlow();
     const pollMs = options?.presencePollMs ?? 0;

package/dist/sdk/react/profile-button.js

@@ -26,8 +26,8 @@ export function ProfileButton({ className, host, theme }) {
         const handle = createProfileButton({
             container,
             flow,
-            ...(host ? { host } : {}),
-            ...(themeRef.current ? { theme: themeRef.current } : {}),
+            host: host ? host : undefined,
+            theme: themeRef.current ? themeRef.current : undefined,
         });
         handleRef.current = handle;
         return () => {

package/dist/sdk/server.js

@@ -11,6 +11,7 @@ async function fetchProfile(issuerUrl, jwt, audience) {
         });
         if (!res.ok)
             return undefined;
+        /* SAFETY: this server's own /session/verify endpoint, called over the loopback. */
         const data = (await res.json());
         return data.payload?.profile ?? undefined;
     }
@@ -39,6 +40,6 @@ export async function resolveSession(cookieHeader, opts) {
         state,
         claims,
         setCookies,
-        ...(profile ? { profile } : {}),
+        profile: profile ? profile : undefined,
     };
 }

package/dist/sdk/session-core.d.ts

@@ -1,11 +1,6 @@
-/**
- * Internal session-resolution core shared by `resolveSession` (SSR) and the
- * session route. Not part of the published API surface — `server.ts` and
- * `session-route.ts` compose it into the public entry points.
- */
 import type { FlowUser, SessionRouteSession, VerifiedFlowJWT } from "./types";
 export declare function claimsToUser(claims: VerifiedFlowJWT): FlowUser;
-export declare function isJwtVerificationFailure(err: unknown): boolean;
+export declare function isJwtVerificationFailure(cause: unknown): boolean;
 /** The Set-Cookie pair carrying a session (1h JWT + 30-day refresh token). */
 export declare function sessionCookies(audience: string, jwt: string, refreshToken: string): string[];
 /** The Set-Cookie pair deleting both session cookies. */

package/dist/sdk/session-core.js

@@ -1,3 +1,4 @@
+import { errField } from "./driver-error";
 /**
  * Internal session-resolution core shared by `resolveSession` (SSR) and the
  * session route. Not part of the published API surface — `server.ts` and
@@ -9,7 +10,7 @@ import { verifyFlowJWT } from "./verify";
 export function claimsToUser(claims) {
     return {
         id: claims.sub,
-        username: typeof claims.username === "string" ? claims.username : "",
+        username: String(claims.username) === claims.username ? claims.username : "",
         // Fail-safe: only an explicit `false` marks a full account; a missing or
         // mangled claim must never grant full privileges.
         isGuest: claims.guest !== false,
@@ -25,6 +26,8 @@ async function refreshSession(issuerUrl, token) {
             return "dead";
         if (!res.ok)
             return null;
+        /* SAFETY: the response is this issuer's own /session/restore payload; a non-ok status has
+         already thrown above. */
         return (await res.json());
     }
     catch {
@@ -57,9 +60,9 @@ function refreshOnce(issuerUrl, token) {
 // fetch failure, timeouts — is transient infrastructure trouble, and falling
 // through to a rotation there would turn a JWKS outage into a rotation storm
 // against the same struggling server.
-export function isJwtVerificationFailure(err) {
-    const code = err?.code;
-    if (typeof code !== "string")
+export function isJwtVerificationFailure(cause) {
+    const code = errField(cause, "code");
+    if (!code)
         return false;
     return (code.startsWith("ERR_JWT") ||
         code.startsWith("ERR_JWS") ||

package/dist/sdk/session-route.d.ts

@@ -1,23 +1,3 @@
-/**
- * The first-party session route every consumer app serves from its own
- * origin — the only path between a browser and the refresh token. The
- * rotating refresh token lives in an HttpOnly cookie owned by the app's
- * server; the browser client calls this route instead of ever holding the
- * token itself:
- *
- *  - `GET`    resolve: fresh JWT from the cookies, rotating server-side when
- *             the access token is expiring.
- *  - `POST`   install: one-time handoff of a freshly minted session (refresh
- *             token + access JWT from the dialog) into the HttpOnly cookies.
- *             The JWT verifies locally against the issuer's cached JWKS — no
- *             rotation of a seconds-old token; a bogus refresh token simply
- *             dies at the first GET, like any planted cookie.
- *  - `DELETE` sign-out: revoke the token's lineage at the issuer and clear
- *             the cookies.
- *
- * Framework-agnostic (`Request` → `Response`); `flowSessionHandlers` from
- * `@flow-industries/id/start` adapts it to a TanStack Start route file.
- */
 import type { SessionRouteOptions } from "./types";
 /**
  * Handles one session-route request (no path check — the caller routed it).

package/dist/sdk/session-route.js

@@ -1,3 +1,4 @@
+import { z } from "zod";
 /**
  * The first-party session route every consumer app serves from its own
  * origin — the only path between a browser and the refresh token. The
@@ -22,6 +23,21 @@ import { cookieNamesFor, parseCookieHeader } from "./cookies";
 import { DEFAULT_SESSION_PATH, defaultAudience, resolveIdHost, } from "./id-host";
 import { claimsToUser, clearingCookies, isJwtVerificationFailure, resolveSessionCore, sessionCookies, } from "./session-core";
 import { verifyFlowJWT } from "./verify";
+/** The body the browser SDK posts to its own app's session route. */
+const installBodySchema = z.object({
+    refreshToken: z.string().min(1).optional(),
+    jwt: z.string().min(1).optional(),
+    mint: z.array(z.string()).optional(),
+});
+const additionalBodySchema = z.object({
+    additionalSessions: z
+        .array(z.object({
+        audience: z.string(),
+        jwt: z.string(),
+        refreshToken: z.string(),
+    }))
+        .optional(),
+});
 function json(body, status, setCookies = []) {
     const headers = new Headers({
         "Content-Type": "application/json",
@@ -65,14 +81,15 @@ export async function handleSessionRequest(request, opts = {}) {
             return json({ state: session }, 200, setCookies);
         }
         case "POST": {
-            const body = (await request.json().catch(() => null));
+            const parsed = installBodySchema.safeParse(await request.json().catch(() => null));
+            const body = parsed.success ? parsed.data : null;
             // Reconcile mint: the browser asks its own server to obtain additional-
             // audience sessions (e.g. talk.flow.game) authorized by the PRIMARY
             // refresh cookie, for an embed that booted with no session of its own.
             // The refresh token never touches page JS — it's read from the HttpOnly
             // cookie here and presented to the issuer as a bearer.
-            if (Array.isArray(body?.mint)) {
-                const audiences = body.mint.filter((a) => typeof a === "string");
+            if (body?.mint) {
+                const audiences = body.mint;
                 const names = cookieNamesFor(audience);
                 const token = parseCookieHeader(request.headers.get("Cookie"))[names.refresh];
                 let additionalSessions = [];
@@ -87,8 +104,10 @@ export async function handleSessionRequest(request, opts = {}) {
                             body: JSON.stringify({ audiences }),
                         });
                         if (res.ok) {
-                            const data = (await res.json());
-                            additionalSessions = data.additionalSessions ?? [];
+                            const data = additionalBodySchema.safeParse(await res.json());
+                            additionalSessions = data.success
+                                ? (data.data.additionalSessions ?? [])
+                                : [];
                         }
                     }
                     catch { }
@@ -97,10 +116,7 @@ export async function handleSessionRequest(request, opts = {}) {
             }
             const refreshToken = body?.refreshToken;
             const jwt = body?.jwt;
-            if (typeof refreshToken !== "string" ||
-                refreshToken.length === 0 ||
-                typeof jwt !== "string" ||
-                jwt.length === 0) {
+            if (!refreshToken || !jwt) {
                 return json({ state: null }, 400);
             }
             // The audience check on the verified JWT is what stops a token minted

package/dist/sdk/start/graceful-shutdown.d.ts

@@ -0,0 +1,8 @@
+import type { GracefulShutdownCleanup, GracefulShutdownOptions, GracefulShutdownServer } from "../types";
+export declare const DEFAULT_GRACEFUL_SHUTDOWN_TIMEOUT_MS = 20000;
+/**
+ * Install one process-wide graceful-shutdown handler for a Bun-compatible
+ * server. The first signal stops new accepts, drains active HTTP and consumer
+ * cleanup together, force-closes at the deadline, and exits successfully.
+ */
+export declare function installGracefulShutdown(server: GracefulShutdownServer | null | undefined, options?: GracefulShutdownOptions): GracefulShutdownCleanup;

package/dist/sdk/start/graceful-shutdown.js

@@ -0,0 +1,81 @@
+export const DEFAULT_GRACEFUL_SHUTDOWN_TIMEOUT_MS = 20_000;
+let installation;
+function timeoutMs(options) {
+    const configured = options.timeoutMs;
+    if (configured === undefined)
+        return DEFAULT_GRACEFUL_SHUTDOWN_TIMEOUT_MS;
+    if (!Number.isFinite(configured) || configured < 0) {
+        return DEFAULT_GRACEFUL_SHUTDOWN_TIMEOUT_MS;
+    }
+    return configured;
+}
+function deadline(ms) {
+    let timer;
+    return {
+        promise: new Promise((resolve) => {
+            timer = setTimeout(() => resolve(false), ms);
+        }),
+        cancel: () => {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        },
+    };
+}
+async function shutdown(current, signal) {
+    let gracefulStop;
+    try {
+        gracefulStop = Promise.resolve(current.server.stop(false));
+    }
+    catch (error) {
+        gracefulStop = Promise.reject(error);
+    }
+    const consumerDrain = Promise.resolve().then(() => current.options.onShutdown?.(signal));
+    const drained = Promise.allSettled([gracefulStop, consumerDrain]).then(() => true);
+    const timeout = deadline(timeoutMs(current.options));
+    const completed = await Promise.race([drained, timeout.promise]);
+    timeout.cancel();
+    if (!completed) {
+        try {
+            void current.server.stop(true);
+        }
+        catch {
+            // The configured deadline is authoritative even if forced close fails.
+        }
+    }
+    process.exit(0);
+}
+function handleSignal(signal) {
+    const current = installation;
+    if (!current || current.shuttingDown)
+        return;
+    current.shuttingDown = true;
+    void shutdown(current, signal);
+}
+function handleSigterm() {
+    handleSignal("SIGTERM");
+}
+function handleSigint() {
+    handleSignal("SIGINT");
+}
+/**
+ * Install one process-wide graceful-shutdown handler for a Bun-compatible
+ * server. The first signal stops new accepts, drains active HTTP and consumer
+ * cleanup together, force-closes at the deadline, and exits successfully.
+ */
+export function installGracefulShutdown(server, options = {}) {
+    if (!server)
+        return () => undefined;
+    if (installation)
+        return installation.cleanup;
+    const cleanup = () => {
+        if (!installation || installation.cleanup !== cleanup)
+            return;
+        process.off("SIGTERM", handleSigterm);
+        process.off("SIGINT", handleSigint);
+        installation = undefined;
+    };
+    installation = { cleanup, options, server, shuttingDown: false };
+    process.on("SIGTERM", handleSigterm);
+    process.on("SIGINT", handleSigint);
+    return cleanup;
+}

package/dist/sdk/start/index.d.ts

@@ -22,6 +22,8 @@
  */
 import { type ReactNode } from "react";
 import type { AdditionalSession, FlowSessionState } from "../types";
+export type { GracefulShutdownCleanup, GracefulShutdownOptions, GracefulShutdownServer, GracefulShutdownSignal, } from "../types";
+export { DEFAULT_GRACEFUL_SHUTDOWN_TIMEOUT_MS, installGracefulShutdown, } from "./graceful-shutdown";
 /**
  * The `beforeLoad` body: during SSR resolve the session server-side (via the
  * app's `getFlowSession` server fn, which appends rotated Set-Cookie values);

package/dist/sdk/start/index.js

@@ -24,13 +24,14 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { useMemo } from "react";
 import { createFlow, createStaticFlow, getFlow } from "../client";
 import { FlowIdProvider } from "../react";
+export { DEFAULT_GRACEFUL_SHUTDOWN_TIMEOUT_MS, installGracefulShutdown, } from "./graceful-shutdown";
 /**
  * The `beforeLoad` body: during SSR resolve the session server-side (via the
  * app's `getFlowSession` server fn, which appends rotated Set-Cookie values);
  * in the browser snapshot the live singleton instead — no network.
  */
 export async function flowSessionContext(getSession) {
-    if (typeof window === "undefined")
+    if (!("window" in globalThis))
         return { session: await getSession() };
     const flow = getFlow();
     const session = flow?.user && flow.jwt
@@ -45,7 +46,7 @@ export async function flowSessionContext(getSession) {
  * is fresh.
  */
 export function FlowRoot({ session, autoGuest, host, additionalAudiences, onAdditionalSessions, children, }) {
-    const flow = useMemo(() => typeof window === "undefined"
+    const flow = useMemo(() => !("window" in globalThis)
         ? createStaticFlow(session, { host })
         : createFlow({
             initialState: session,

package/dist/sdk/token-expiry.js

@@ -1,3 +1,4 @@
+import { isNum, isRecord } from "./json";
 // Refresh a little before the JWT's `exp` so a token handed out to a caller
 // is still valid by the time it reaches the relying party, absorbing request
 // latency and minor client/server clock skew.
@@ -10,7 +11,8 @@ export function jwtExp(token) {
     try {
         const padded = (parts[1] ?? "").replace(/-/g, "+").replace(/_/g, "/");
         const payload = JSON.parse(atob(padded));
-        return typeof payload.exp === "number" ? payload.exp : null;
+        const exp = isRecord(payload) ? payload.exp : undefined;
+        return isNum(exp) ? exp : null;
     }
     catch {
         return null;

package/dist/sdk/types/cosmetics.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Cosmetic items, the space they occupy on the model, and the equipped set a
+ * game server receives on `/api/session/verify`.
+ *
+ * Two region vocabularies live here and must never be collapsed into one:
+ * {@link EquipRegion} is *item vs item* (can these be worn together), while
+ * {@link BodyRegion} is *cosmetic vs body* (what geometry must stop drawing so
+ * nothing pokes through). TF2 keeps them separate — equip regions and
+ * bodygroups — and conflating them is what produces the clipping bugs.
+ *
+ * {@link CosmeticMaterial} is a third vocabulary and belongs to neither: it
+ * names a *surface* of the model rather than a space on it, and it is what a
+ * colour is applied to.
+ */
+/**
+ * A space on the model an item occupies. Two items occupying the same region,
+ * or overlapping ones, cannot be equipped together.
+ *
+ * A deliberately small subset of TF2's 68: enough to express the composite
+ * case (`whole_head` swallowing the pieces of a head) that makes the rule
+ * non-trivial, without inventing regions no item claims yet.
+ */
+export type EquipRegion = "whole_head" | "hat" | "hair" | "face" | "glasses" | "ears" | "torso" | "arms" | "back" | "legs" | "feet";
+/**
+ * Every body area a cosmetic may suppress — the bodygroup half's whole
+ * vocabulary, head down.
+ *
+ * SOURCE OF TRUTH: the `regions` keys of
+ * `game/games/arena/player/luna_bodygroups.tres`, which is authored against
+ * the shipped model. This is a mirror, kept as a constant so auth can resolve
+ * a loadout without reaching into the game repo at runtime.
+ *
+ * WHEN THE MODEL IS RE-CUT: update this list to the new `regions` keys, then
+ * fix whatever `hides` in the catalog no longer resolves. `cosmetics.test.ts`
+ * fails on the first entry that names a region absent here, and the type below
+ * makes the same mistake a typecheck error — which is the whole point of
+ * mirroring the names into one constant. AUTH-210 is what happens without it:
+ * the catalog was written from a nine-region proposal in
+ * `docs/internal/cosmetics/bodygroups.md` section 6, the fifteen-region cut
+ * that actually shipped shared not one name with it, and every cosmetic
+ * silently suppressed nothing.
+ */
+export declare const BODY_REGIONS: readonly ["head", "ears", "hair", "body_neck", "body_chest", "body_arm_upper_l", "body_arm_upper_r", "body_arm_lower_l", "body_arm_lower_r", "body_hand_l", "body_hand_r", "body_pelvis", "body_leg_upper_l", "body_leg_upper_r", "body_leg_lower_l", "body_leg_lower_r", "body_foot_l", "body_foot_r"];
+/**
+ * A body area a cosmetic suppresses so the body cannot clip through it — the
+ * bodygroup half. Derived from {@link BODY_REGIONS} rather than written out a
+ * second time, so the list and the type cannot disagree.
+ */
+export type BodyRegion = (typeof BODY_REGIONS)[number];
+/**
+ * Every material the shipped model set exposes, body and cosmetic alike — the
+ * surfaces a colour can be applied to.
+ *
+ * SOURCE OF TRUTH: the glTF material names inside
+ * `game/games/arena/resources/models/LUNA12.7.glb` (`skin`, `brownhair`,
+ * `tshirt`, `shorts`) and the per-cosmetic GLBs beside it
+ * (`cosmetics/LUNA_boots.glb` names `Shoes`, `cosmetics/LUNA_glasses.glb`
+ * names `outline`). `Shoes` is capitalised because the model capitalises it: a
+ * tidied-up copy here would name a material no renderer can find, and the
+ * paint would silently land nowhere.
+ *
+ * WHEN THE MODEL IS RE-CUT: update this list to the new material names, then
+ * fix whatever `paintable` in the catalog no longer resolves. This is the same
+ * mirror-and-guard {@link BODY_REGIONS} is, kept for the same reason —
+ * AUTH-210 is what a hardcoded copy with no test looks like a month later.
+ */
+export declare const COSMETIC_MATERIALS: readonly ["skin", "brownhair", "tshirt", "shorts", "Shoes", "outline"];
+/**
+ * A material a cosmetic may expose for recolouring. Derived from
+ * {@link COSMETIC_MATERIALS} rather than written out a second time, so the
+ * list and the type cannot disagree.
+ */
+export type CosmeticMaterial = (typeof COSMETIC_MATERIALS)[number];
+/**
+ * One equipment slot. The slot name IS the key inside the `appearance` blob,
+ * so equipped state needs no table and no migration of its own.
+ *
+ * The vocabulary is complete rather than "the slots something is sold for":
+ * `hat` has no product today and is still a slot, because the wire format, the
+ * game's whitelist and the region rules all speak in slots, and a vocabulary
+ * that shrank whenever a slot emptied would churn the contract every time
+ * content lands.
+ */
+export type CosmeticSlot = "hat" | "face" | "top" | "bottom" | "feet";
+/** One item in the catalog. */
+export interface CosmeticItem {
+    id: string;
+    slot: CosmeticSlot;
+    name: string;
+    /**
+     * ALWAYS plural, even for a single region, and the only shape there is: TF2
+     * carried a singular `equip_region` key alongside the plural one, and items
+     * that declared several regions through the singular form silently escaped
+     * enforcement (Source-1-Games#4678). A singular field is never added here.
+     */
+    regions: readonly EquipRegion[];
+    /**
+     * Body regions this item suppresses. Required rather than optional: a
+     * cosmetic that declares nothing is a content bug, not a default, so an
+     * author must write `[]` deliberately (an accessory that covers no skin)
+     * instead of forgetting the field on a cosmetic that does.
+     */
+    hides: readonly BodyRegion[];
+    /**
+     * The materials on this item a player may recolour. Plural for the reason
+     * {@link CosmeticItem.regions} is, and required for the reason
+     * {@link CosmeticItem.hides} is: `[]` is an item stating that nothing on it
+     * takes paint, while a missing field is an author who never considered the
+     * question. The fault is silence, not emptiness.
+     */
+    paintable: readonly CosmeticMaterial[];
+}
+/**
+ * One painted surface on an equipped item, as `/api/session/verify` hands it
+ * to a renderer: recolour this material on this item to this colour.
+ *
+ * A LIST per item rather than a `material -> colour` map, because a map is
+ * exactly the shape that cannot grow: GAME-178 paints a masked region of an
+ * item instead of its whole surface, which arrives as another field here and a
+ * SECOND entry naming the same material.
+ */
+export interface CosmeticPaint {
+    material: CosmeticMaterial;
+    color: string;
+}
+/**
+ * One recolourable surface the equipped set exposes: which worn item, which of
+ * its materials, and the `appearance` key holding the colour.
+ */
+export interface PaintSlot {
+    key: string;
+    slot: CosmeticSlot;
+    item: CosmeticItem;
+    material: CosmeticMaterial;
+}
+/** One equipped item as `/api/session/verify` hands it to a game server. */
+export interface EquippedCosmetic {
+    id: string;
+    name: string;
+    regions: readonly EquipRegion[];
+    hides: readonly BodyRegion[];
+    /** The colours to apply, one entry per material the player has painted. */
+    paint: readonly CosmeticPaint[];
+}
+/** The verified equipped set, keyed by slot. An absent slot is empty. */
+export type EquippedCosmetics = Partial<Record<CosmeticSlot, EquippedCosmetic>>;
+/** The two items that cannot be worn together, and the region they fight over. */
+export interface EquipConflict {
+    region: EquipRegion;
+    items: [string, string];
+    slots: [CosmeticSlot, CosmeticSlot];
+}
+/**
+ * Why a settings write was refused by its surface's cross-field rule. Returned
+ * from the one write path and rendered as the 409 body, so a client can mark
+ * the offending keys instead of guessing which of them lost.
+ */
+export interface SettingsConflict {
+    code: string;
+    message: string;
+    keys: string[];
+}