@netforge/engine 0.0.0-stage → 0.2.0

package/dist/net/prediction.js

@@ -0,0 +1,101 @@
+// Client-side prediction and server reconciliation (Gambetta).
+//
+// The client applies each input to its local world the moment it is sampled
+// and keeps it until the server acknowledges it. When a snapshot arrives, the
+// predicted entity is reset to the server's state and every input the server
+// has not yet applied is replayed on top. Input never waits for the round
+// trip, and the result converges to the server's state.
+//
+// A correction (server disagreed) would snap the character; instead the
+// visual position carries the error as an offset that decays over ~100 ms.
+export class Predictor {
+    sim;
+    player;
+    selfEntity;
+    world;
+    pending = [];
+    nextSeq = 1;
+    ready = false;
+    offsetX = 0;
+    offsetY = 0;
+    /** Magnitude of the last correction in world units (telemetry/tests). */
+    lastCorrection = 0;
+    /** Count of reconciliations that moved the predicted entity. */
+    corrections = 0;
+    constructor(sim, player, selfEntity, seed = 0, firstSeq = 1) {
+        this.sim = sim;
+        this.player = player;
+        this.selfEntity = selfEntity;
+        this.world = sim.createWorld(seed, 'client');
+        this.nextSeq = firstSeq;
+    }
+    /** The seq the next predicted command gets (a rebased predictor continues from here). */
+    get upcomingSeq() {
+        return this.nextSeq;
+    }
+    get isReady() {
+        return this.ready;
+    }
+    /** Applies one tick of input locally. Returns the command to send. */
+    predict(input, viewTick16) {
+        if (!this.ready)
+            return null;
+        const cmd = { seq: this.nextSeq++, viewTick16, input };
+        this.pending.push(cmd);
+        // Bound memory if the server stops acking (disconnect): keep ~4 s at 60 Hz.
+        if (this.pending.length > 240)
+            this.pending.shift();
+        this.sim.step(this.world, new Map([[this.player, [input]]]));
+        return cmd;
+    }
+    /** Unacknowledged commands, oldest first. */
+    unacked() {
+        return this.pending;
+    }
+    reconcile(ackSeq, serverSelf) {
+        const before = this.ready ? this.state() : null;
+        this.pending = this.pending.filter((c) => c.seq > ackSeq);
+        this.sim.applySnapshot(this.world, [serverSelf]);
+        for (const c of this.pending)
+            this.sim.step(this.world, new Map([[this.player, [c.input]]]));
+        this.ready = true;
+        if (!before)
+            return;
+        const after = this.state();
+        if (!after)
+            return;
+        const xi = this.sim.schema.xField;
+        const yi = this.sim.schema.yField;
+        const ex = (before.values[xi] ?? 0) - (after.values[xi] ?? 0);
+        const ey = (before.values[yi] ?? 0) - (after.values[yi] ?? 0);
+        this.lastCorrection = Math.hypot(ex, ey) / this.sim.schema.unitsPerWorld;
+        if (ex !== 0 || ey !== 0) {
+            this.corrections++;
+            this.offsetX += ex;
+            this.offsetY += ey;
+        }
+    }
+    /** The predicted entity, exact (what reconciliation converges on). */
+    state() {
+        return this.sim.snapshot(this.world).find((e) => e.id === this.selfEntity);
+    }
+    /** The predicted entity with the correction offset applied, for drawing. */
+    renderState(dtMs) {
+        const s = this.state();
+        if (!s)
+            return undefined;
+        const decay = Math.exp(-dtMs / 50);
+        this.offsetX *= decay;
+        this.offsetY *= decay;
+        if (Math.abs(this.offsetX) < 0.01)
+            this.offsetX = 0;
+        if (Math.abs(this.offsetY) < 0.01)
+            this.offsetY = 0;
+        const values = [...s.values];
+        const xi = this.sim.schema.xField;
+        const yi = this.sim.schema.yField;
+        values[xi] = (values[xi] ?? 0) + this.offsetX;
+        values[yi] = (values[yi] ?? 0) + this.offsetY;
+        return { ...s, values };
+    }
+}

package/dist/net/profile-client.d.ts

@@ -0,0 +1,75 @@
+import { type GameProfile } from './protocol.js';
+/** Storage key for the guest id: shared by every game on one origin, like a Launcher guest. */
+export declare const GUEST_KEY = "netnet:guest:v1";
+/** This browser's guest id (made on first use). Storage blocked: one per page load. */
+export declare function guestId(): string;
+/** A fresh guest id: after a guest profile merges into a wallet, the old id is spent. */
+export declare function rotateGuestId(): string;
+/** The saved session token for a rooms server, if it has not expired. */
+export declare function savedSession(endpoint: string): {
+    token: string;
+    address: string;
+} | null;
+export declare function saveSession(endpoint: string, s: {
+    token: string;
+    address: string;
+    expiresAt: number;
+} | null): void;
+/** The slice of an EIP-1193 provider sign-in needs. */
+export interface Eip1193 {
+    request(args: {
+        method: string;
+        params?: unknown[];
+    }): Promise<unknown>;
+}
+/**
+ * Sign in to a rooms server with a wallet: its nonce, an EIP-4361 message
+ * for its domain, one personal_sign (no gas), a session token. Saved for
+ * this endpoint until it expires.
+ */
+export declare function signInWithWallet(endpoint: string, provider: Eip1193, statement?: string): Promise<{
+    token: string;
+    address: string;
+    expiresAt: number;
+}>;
+/** Who is asking: a signed-in session (bearer) or a guest id. */
+export type ProfileAuth = {
+    readonly session: string;
+} | {
+    readonly guest: string;
+};
+export interface LocalProgress {
+    /** Achievement ids this browser reached before profiles. */
+    readonly achievements?: readonly string[];
+    /** Goals done today (UTC day) in this browser. */
+    readonly goals?: {
+        readonly day: number;
+        readonly done: readonly string[];
+    };
+    /** Settings to carry over (the keeper pick, sound). */
+    readonly settings?: Readonly<Record<string, unknown>>;
+}
+/** The room server's profile routes for one game. */
+export declare class ProfileApi {
+    readonly endpoint: string;
+    readonly game: string;
+    constructor(endpoint: string, game: string);
+    private headers;
+    private call;
+    /** This game's profile for a session or a guest (an empty one before any progress). */
+    get(auth: ProfileAuth): Promise<GameProfile>;
+    /** One time per guest and game: carry progress this browser kept before profiles existed. */
+    importLocal(guest: string, local: LocalProgress): Promise<GameProfile>;
+    /** Merge a guest's progress into the signed-in wallet's profile (the guest id is spent: rotate it). */
+    claim(session: string, guest: string): Promise<GameProfile>;
+    /** Replace this game's settings for the player (a small JSON object). */
+    setSettings(auth: ProfileAuth, settings: Readonly<Record<string, unknown>>): Promise<GameProfile>;
+    /** The display name the Launcher and end screens show (1-24 characters). */
+    setName(auth: ProfileAuth, displayName: string): Promise<GameProfile>;
+    /**
+     * Turn a committed coin spend (kit.coins.spend(price, id) returned `key`)
+     * into ownership: a cosmetic, an unlock, or the next level of a meta
+     * upgrade. The server checks the price from the game's manifest.
+     */
+    redeem(session: string, item: string, key: string): Promise<GameProfile>;
+}

package/dist/net/profile-client.js

@@ -0,0 +1,173 @@
+// The browser side of universal saves: a guest id,
+// wallet sign-in (SIWE over any EIP-1193 wallet) and the room server's
+// profile routes. Progress lives on the server, keyed by the signed-in
+// wallet or by the guest id; the browser keeps only the guest id and the
+// session token, both conveniences. Plain fetch, no chain calls.
+import { GUEST_ID_RE } from './protocol.js';
+/** Storage key for the guest id: shared by every game on one origin, like a Launcher guest. */
+export const GUEST_KEY = 'netnet:guest:v1';
+const SESSION_KEY = 'netnet:rooms-session:v1';
+function storage() {
+    try {
+        return typeof localStorage === 'undefined' ? null : localStorage;
+    }
+    catch {
+        return null;
+    }
+}
+function randomGuest() {
+    const bytes = new Uint8Array(16);
+    globalThis.crypto.getRandomValues(bytes);
+    return `g-${Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('')}`;
+}
+let memoGuest = null;
+/** This browser's guest id (made on first use). Storage blocked: one per page load. */
+export function guestId() {
+    if (memoGuest)
+        return memoGuest;
+    const s = storage();
+    try {
+        const have = s?.getItem(GUEST_KEY);
+        if (have && GUEST_ID_RE.test(have))
+            return (memoGuest = have);
+    }
+    catch {
+        /* blocked */
+    }
+    memoGuest = randomGuest();
+    try {
+        s?.setItem(GUEST_KEY, memoGuest);
+    }
+    catch {
+        /* per page */
+    }
+    return memoGuest;
+}
+/** A fresh guest id: after a guest profile merges into a wallet, the old id is spent. */
+export function rotateGuestId() {
+    memoGuest = randomGuest();
+    try {
+        storage()?.setItem(GUEST_KEY, memoGuest);
+    }
+    catch {
+        /* per page */
+    }
+    return memoGuest;
+}
+/** The saved session token for a rooms server, if it has not expired. */
+export function savedSession(endpoint) {
+    try {
+        const raw = storage()?.getItem(`${SESSION_KEY}:${endpoint}`);
+        if (!raw)
+            return null;
+        const o = JSON.parse(raw);
+        if (typeof o.token !== 'string' || typeof o.address !== 'string' || typeof o.expiresAt !== 'number' || o.expiresAt <= Date.now() + 60_000)
+            return null;
+        return { token: o.token, address: o.address };
+    }
+    catch {
+        return null;
+    }
+}
+export function saveSession(endpoint, s) {
+    try {
+        if (s)
+            storage()?.setItem(`${SESSION_KEY}:${endpoint}`, JSON.stringify(s));
+        else
+            storage()?.removeItem(`${SESSION_KEY}:${endpoint}`);
+    }
+    catch {
+        /* this page only */
+    }
+}
+function hexUtf8(text) {
+    return `0x${Array.from(new TextEncoder().encode(text), (b) => b.toString(16).padStart(2, '0')).join('')}`;
+}
+/**
+ * Sign in to a rooms server with a wallet: its nonce, an EIP-4361 message
+ * for its domain, one personal_sign (no gas), a session token. Saved for
+ * this endpoint until it expires.
+ */
+export async function signInWithWallet(endpoint, provider, statement = 'Sign in to save your progress.') {
+    const accounts = (await provider.request({ method: 'eth_requestAccounts' }));
+    const address = Array.isArray(accounts) && typeof accounts[0] === 'string' ? accounts[0] : null;
+    if (!address || !/^0x[0-9a-fA-F]{40}$/.test(address))
+        throw new Error('no wallet account');
+    const n = (await (await fetch(`${endpoint}/auth/nonce`)).json());
+    if (!n.nonce || !n.domain || !n.uri || !n.chainId)
+        throw new Error('the server sent no sign-in nonce');
+    const now = new Date();
+    const message = [
+        `${n.domain} wants you to sign in with your Ethereum account:`,
+        address,
+        '',
+        statement,
+        '',
+        `URI: ${n.uri}`,
+        'Version: 1',
+        `Chain ID: ${n.chainId}`,
+        `Nonce: ${n.nonce}`,
+        `Issued At: ${now.toISOString()}`,
+        `Expiration Time: ${new Date(now.getTime() + 12 * 3600_000).toISOString()}`,
+    ].join('\n');
+    const signature = (await provider.request({ method: 'personal_sign', params: [hexUtf8(message), address] }));
+    const res = await fetch(`${endpoint}/auth/sign-in`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ message, signature }) });
+    const body = (await res.json());
+    if (!res.ok || !body.token || !body.address || !body.expiresAt)
+        throw new Error(body.error ?? `sign-in failed (${res.status})`);
+    const out = { token: body.token, address: body.address, expiresAt: body.expiresAt };
+    saveSession(endpoint, out);
+    return out;
+}
+/** The room server's profile routes for one game. */
+export class ProfileApi {
+    endpoint;
+    game;
+    constructor(endpoint, game) {
+        this.endpoint = endpoint;
+        this.game = game;
+    }
+    headers(auth) {
+        const h = { 'content-type': 'application/json' };
+        if (auth && 'session' in auth)
+            h.authorization = `Bearer ${auth.session}`;
+        else if (auth)
+            h['x-guest-id'] = auth.guest;
+        return h;
+    }
+    async call(method, path, auth, body) {
+        const res = await fetch(`${this.endpoint}${path}`, { method, headers: this.headers(auth), ...(body !== undefined ? { body: JSON.stringify(body) } : {}) });
+        const out = (await res.json().catch(() => null));
+        if (!res.ok || out === null)
+            throw new Error(out?.error ?? `profile ${path} failed (${res.status})`);
+        return out;
+    }
+    /** This game's profile for a session or a guest (an empty one before any progress). */
+    get(auth) {
+        return this.call('GET', `/profile/game/${encodeURIComponent(this.game)}`, auth);
+    }
+    /** One time per guest and game: carry progress this browser kept before profiles existed. */
+    importLocal(guest, local) {
+        return this.call('POST', '/profile/import', { guest }, { game: this.game, ...local });
+    }
+    /** Merge a guest's progress into the signed-in wallet's profile (the guest id is spent: rotate it). */
+    claim(session, guest) {
+        return this.call('POST', '/profile/claim', { session }, { guest, game: this.game });
+    }
+    /** Replace this game's settings for the player (a small JSON object). */
+    setSettings(auth, settings) {
+        return this.call('POST', '/profile/settings', auth, { game: this.game, settings });
+    }
+    /** The display name the Launcher and end screens show (1-24 characters). */
+    setName(auth, displayName) {
+        return this.call('POST', '/profile/name', auth, { game: this.game, displayName });
+    }
+    /**
+     * Turn a committed coin spend (kit.coins.spend(price, id) returned `key`)
+     * into ownership: a cosmetic, an unlock, or the next level of a meta
+     * upgrade. The server checks the price from the game's manifest.
+     */
+    redeem(session, item, key) {
+        return this.call('POST', '/profile/redeem', { session }, { game: this.game, item, key });
+    }
+}

package/dist/net/protocol.d.ts

@@ -0,0 +1,215 @@
+export declare const MSG_INPUT = 1;
+export declare const MSG_SNAPSHOT = 2;
+export declare const ROOM_NAME = "instance";
+export interface WelcomeMessage {
+    readonly player: number;
+    readonly entity: number;
+    readonly tickHz: number;
+    readonly snapshotHz: number;
+    readonly sim: string;
+    readonly version: string;
+    readonly place: string;
+    readonly template: string;
+    /** Present when the player joined with a wallet and earn is tracked. */
+    readonly runId: string | null;
+    /** False when the referee has no signer: earn is tracked but not paid. */
+    readonly earnLive: boolean;
+    /**
+     * Why this seat earns nothing, when it does not: 'guest' (no signed-in
+     * session), 'wallet-busy' (the wallet is already earning in another
+     * session of this game), 'session' (the session token did not verify).
+     */
+    readonly earnRefused?: EarnRefusal;
+    /** The game's buy-in run terms in whole coins (earn.stake), or absent when it takes no stakes. */
+    readonly stake?: StakeTermsView;
+    /** The game's PvP pot in whole coins (earn.pot), or absent when it has none. */
+    readonly pot?: {
+        readonly entry: number;
+        readonly recycle: number;
+    };
+}
+/**
+ * Server -> client ('pot'): 'in' this round's pot holds the player's entry
+ * (`pot` is the whole pot so far); 'waiting' the entry is placed for the
+ * next round; 'closed' the round split the pot (`paid` is this player's
+ * part); 'refused' (`reason`). Whole coins.
+ */
+export interface PotMessage {
+    readonly state: 'in' | 'waiting' | 'closed' | 'refused';
+    readonly entry: number;
+    readonly pot?: number;
+    readonly paid?: number;
+    readonly reason?: string;
+}
+/** A game's buy-in run terms as a client shows them (whole coins). */
+export interface StakeTermsView {
+    readonly min: number;
+    readonly max: number;
+    /** The stake's payout ceiling is stake x multiple. */
+    readonly multiple: number;
+}
+/**
+ * Client -> server ('stake'): the player spent a stake (the Kit's
+ * coins.spend(amount, "stake"), committed). The room fixes the stake from
+ * its own ledger when a run starts: always the NEXT run (sign-in or the
+ * next round; a run in progress never restarts), and a
+ * staked run starts from zero earn progress. `amount` (whole coins) is read only
+ * by a room whose store runs in mock mode (local play).
+ */
+export interface StakeRequest {
+    readonly amount?: number;
+}
+/**
+ * Server -> client ('stake'): 'live' the run in progress is staked;
+ * 'waiting' a stake is placed for the next run; 'closed' a staked run ended
+ * (`paid` is its stake share); 'refused' the stake was not taken (`reason`).
+ * Amounts are whole coins.
+ */
+export interface StakeMessage {
+    readonly state: 'live' | 'waiting' | 'closed' | 'refused';
+    readonly stake: number;
+    /** Most the run can pay: its free earn plus stake x multiple. */
+    readonly ceiling?: number;
+    readonly paid?: number;
+    readonly reason?: string;
+    /** 'live': gear the staked run brought in; 'closed': gear it lost (SKU ids). */
+    readonly gear?: readonly string[];
+    readonly lost?: readonly string[];
+}
+export type EarnRefusal = 'guest' | 'wallet-busy' | 'session';
+export interface EarnMessage {
+    readonly rule: string;
+    readonly units: number;
+}
+export interface JoinOptions {
+    /**
+     * Ignored by the referee. Earning needs `session`: the room takes the
+     * wallet from the signed session, never from this field.
+     */
+    readonly wallet?: string;
+    /** Session token from POST /auth/sign-in (SIWE). Without it the seat is a guest. */
+    readonly session?: string;
+    /**
+     * A guest's random profile id (16-80 of A-Z a-z 0-9 _ -), kept by the
+     * browser. Progress a guest makes is saved to it on the server and merges
+     * into the wallet's profile at sign-in (POST /profile/claim).
+     */
+    readonly guest?: string;
+}
+/** Guest profile ids: 16-80 characters of A-Z, a-z, 0-9, _ or - (the same rule as Launcher guest drafts). */
+export declare const GUEST_ID_RE: RegExp;
+/** One item of a game's permanent store as a profile sees it (cosmetics, unlocks, meta levels). */
+export interface ProfileStoreItem {
+    readonly id: string;
+    readonly kind: 'cosmetic' | 'unlock' | 'meta' | 'gear';
+    /** Coins for the next purchase (the next level of a meta upgrade); null when owned or at the top. */
+    readonly coins: number | null;
+    readonly owned: boolean;
+    /** Cosmetic id, or the keeper an unlock opens. */
+    readonly cosmetic?: number;
+    readonly keeper?: string;
+    /** Gear: the run upgrade it brings into staked runs, and the share of a run's most earn below which it is lost. */
+    readonly gear?: string;
+    readonly loseBelow?: number;
+    /** Meta upgrades: the stat, bonus per level (0.05 = +5%), the level owned, the top level, the bonus now. */
+    readonly stat?: string;
+    readonly step?: number;
+    readonly level?: number;
+    readonly levels?: number;
+    readonly bonus?: number;
+}
+/**
+ * A player's saved progress in one game, kept by the room server: the same on every device the player signs in on.
+ * Achievements, goals and titles come from the authoritative sim only.
+ */
+export interface GameProfile {
+    readonly game: string;
+    /** Whose: a signed-in wallet, a guest id, or null (nothing is saved for this seat). */
+    readonly kind: 'wallet' | 'guest' | null;
+    readonly wallet: string | null;
+    readonly displayName: string | null;
+    readonly achievements: readonly {
+        readonly id: string;
+        readonly at: number;
+        readonly source: 'sim' | 'import';
+    }[];
+    /** Keeper ids this player may pick. */
+    readonly keepers: readonly string[];
+    /** Permanent SKUs owned (cosmetics and unlocks), by id. */
+    readonly owned: readonly string[];
+    /** Cosmetic ids owned (0, the default look, always). */
+    readonly cosmetics: readonly number[];
+    /** Meta upgrade levels owned (opt-in games only). */
+    readonly meta: Readonly<Record<string, number>>;
+    /** Today's goals (UTC day) and which are done. */
+    readonly goals: {
+        readonly day: number;
+        readonly today: readonly string[];
+        readonly done: readonly string[];
+    };
+    /** Titles taken, by id, with how many times. */
+    readonly titles: Readonly<Record<string, number>>;
+    /** The game's settings for this player (JSON, set by the client). */
+    readonly settings: Readonly<Record<string, unknown>>;
+    /** The permanent store: cosmetics, unlocks and meta levels with their next price. */
+    readonly store: readonly ProfileStoreItem[];
+    /** True once local (pre-profile) progress was imported. */
+    readonly imported: boolean;
+    /** Store credit in whole coins: a refunded purchase the server could not return as earned coins. The next purchase spends it first. */
+    readonly credit: number;
+    /** Across every game: for the Launcher's profile page. */
+    readonly totals: {
+        readonly achievements: number;
+        readonly titles: number;
+        readonly games: number;
+    };
+}
+/** Client -> server: sign in mid-session (a guest who just signed the SIWE message). */
+export interface SignInMessage {
+    readonly session: string;
+}
+/** Server -> client: the outcome of a mid-session sign-in. */
+export interface SignInResult {
+    readonly ok: boolean;
+    readonly runId: string | null;
+    readonly earnRefused?: EarnRefusal;
+}
+/**
+ * Server -> client: the room rebuilt its world at a safe point (between
+ * rounds): a new logic module (hot swap, `version` changed) or a fresh
+ * verification segment. The player keeps its id; its entity id may change,
+ * baselines are void and the next snapshot is full.
+ */
+export interface RebaseMessage {
+    readonly entity: number;
+    readonly sim: string;
+    readonly version: string;
+}
+/** Client -> server: a store hook (paid revive, cosmetic). The room verifies before the sim applies it. */
+export interface CommandMessage {
+    readonly name: string;
+    readonly value?: number;
+    /** Proof of payment from the Kit: a transaction hash, or the key of a coin spend (POST /referee/spend). Verified by the room when the store is live. */
+    readonly proof?: string;
+}
+/** Server -> client: the outcome of a command. */
+export interface CommandResult {
+    readonly name: string;
+    readonly ok: boolean;
+    readonly reason?: string;
+}
+/** Server -> client: a fresh referee run started (new runId after a run reset). */
+export interface RunIdMessage {
+    readonly runId: string | null;
+}
+export interface CreateOptions {
+    readonly place: string;
+    readonly template: string;
+    /**
+     * The game's slug when one room server runs several games of one template
+     * (launched Net Forge games, keyed by slug). Absent: the template's own game.
+     */
+    readonly game?: string;
+}
+/** A game slug as the GameFactory and the room server take it. */
+export declare const GAME_SLUG_RE: RegExp;

package/dist/net/protocol.js

@@ -0,0 +1,10 @@
+// Room wire protocol, shared by the server, the demo client and the bots.
+// Hot-path messages are raw bytes under numeric types (smallest header);
+// rare control messages are msgpack objects under string types.
+export const MSG_INPUT = 1; // client -> server, bytes (netcode/input.ts)
+export const MSG_SNAPSHOT = 2; // server -> client, bytes (netcode/snapshot.ts)
+export const ROOM_NAME = 'instance';
+/** Guest profile ids: 16-80 characters of A-Z, a-z, 0-9, _ or - (the same rule as Launcher guest drafts). */
+export const GUEST_ID_RE = /^[A-Za-z0-9_-]{16,80}$/;
+/** A game slug as the GameFactory and the room server take it. */
+export const GAME_SLUG_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;

package/dist/net/room-client.d.ts

@@ -0,0 +1,65 @@
+import { Client, type Room } from '@colyseus/sdk';
+import { NetClient } from './client.js';
+import type { SimAdapter } from './sim-adapter.js';
+import { type CommandMessage, type CommandResult, type EarnMessage, type GameProfile, type RebaseMessage, type RunIdMessage, type SignInResult, type PotMessage, type StakeMessage, type WelcomeMessage } from './protocol.js';
+export interface JoinParams {
+    readonly endpoint: string;
+    readonly place: string;
+    readonly template: string;
+    /**
+     * The launched game's slug: one room server runs every launched game of a
+     * template side by side. Absent: the page's own ?game= (Net Forge frames a
+     * launched game with it), else the template's own game.
+     */
+    readonly game?: string;
+    readonly wallet?: string;
+    /** Session token from POST /auth/sign-in. Without it the seat plays as a guest and earns nothing. */
+    readonly session?: string;
+    /** A guest profile id (see protocol GUEST_ID_RE): a guest's progress is saved under it. */
+    readonly guest?: string;
+    readonly friendRoomId?: string;
+}
+export interface RoomConnection<W, I> {
+    readonly room: Room;
+    /** The current predictor. Replaced on a rebase (new entity id), so read it each time. */
+    readonly net: NetClient<W, I>;
+    readonly welcome: WelcomeMessage;
+    readonly roomId: string;
+    /** Snapshot payload bytes received (excluding Colyseus/WS framing). */
+    bytesIn(): number;
+    messagesIn(): number;
+    onEarn(cb: (e: EarnMessage) => void): void;
+    /** Run state the room broadcasts (game-defined JSON), latest first-come. */
+    onRun(cb: (info: unknown) => void): void;
+    latestRun(): unknown;
+    /** A fresh referee run after the game reset (new runId). */
+    onRunId(cb: (m: RunIdMessage) => void): void;
+    /** The room rebuilt its world at a safe point (hot swap or a new verification segment). */
+    onRebase(cb: (m: RebaseMessage) => void): void;
+    /** Sign in mid-session with a token from POST /auth/sign-in. */
+    signIn(session: string): Promise<SignInResult>;
+    /** The seat's saved progress, pushed by the room on join and whenever it changes (achievements, unlocks, goals). */
+    onProfile(cb: (p: GameProfile) => void): void;
+    latestProfile(): GameProfile | null;
+    /**
+     * The buy-in run: tell the room a stake was spent (the Kit's
+     * coins.spend(amount, "stake"), committed). The room fixes the stake from
+     * its own ledger at run start and answers with a 'stake' message.
+     * `amount` (whole coins) counts only on a mock-store room (local play).
+     */
+    stake(amount?: number): void;
+    /** Stake state from the room: live, waiting for the next run, closed (with its share paid), or refused. */
+    onStake(cb: (m: StakeMessage) => void): void;
+    latestStake(): StakeMessage | null;
+    /** PvP pot: tell the room an entry was spent (coins.spend(entry, "pot")); it joins the next round's pot (taken once, at that round's start). */
+    pot(): void;
+    onPot(cb: (m: PotMessage) => void): void;
+    /** A store hook (revive token, cosmetic); resolves with the room's verdict. */
+    command(cmd: CommandMessage): Promise<CommandResult>;
+    claim(): Promise<unknown>;
+    leave(): Promise<void>;
+}
+/** The page's ?game= slug (set by Net Forge on a launched game's frame), or null outside a browser or without one. */
+export declare function pageGame(): string | null;
+export declare function joinRoom<W, I>(sim: SimAdapter<W, I>, p: JoinParams): Promise<RoomConnection<W, I>>;
+export declare function connectReservation<W, I>(sim: SimAdapter<W, I>, endpoint: string, reservation: Parameters<Client['consumeSeatReservation']>[0]): Promise<RoomConnection<W, I>>;