@helixdev/helix-sdk 0.1.1-staging.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hypersonic Labs
+
+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

@@ -0,0 +1,68 @@
+# @hypersoniclabs/helix-sdk
+
+The **HELIX Instant browser SDK** — the runtime a world embeds to talk to the HELIX shell
+(the play page that iframes it). v0.1 provides identity; later versions add multiplayer, voice,
+wallet, and inventory.
+
+A world is a static bundle that runs inside a **sandboxed iframe**. The shell hands it a
+short-lived, world-scoped session token (minted by the backend at
+`POST /api/v1/instant-worlds/:worldId/session`) over `postMessage`. The SDK wraps that handshake.
+
+## Install
+
+```bash
+npm install @hypersoniclabs/helix-sdk
+```
+
+## Usage
+
+```ts
+import { Helix } from '@hypersoniclabs/helix-sdk';
+
+const { embedded, world, user } = await Helix.init(); // call once, at startup
+
+if (Helix.auth.isAuthenticated()) {
+  const me = await Helix.auth.getUser(); // { id, username, displayName }
+}
+
+// Raise the shell's login overlay (no-op reload — world state is preserved):
+loginButton.onclick = async () => {
+  try {
+    const user = await Helix.auth.requestLogin();
+    console.log('signed in as', user.username);
+  } catch {
+    /* dismissed or unavailable */
+  }
+};
+
+Helix.auth.onAuthChanged((user) => updateUi(user)); // login + logout
+```
+
+When the world is opened directly (e.g. a local `vite dev` server with no shell), `init()` resolves
+with `embedded: false` and all identity APIs return `null`/`false` — so the same build runs locally
+and embedded.
+
+### API
+
+- `Helix.init(): Promise<{ embedded, world, user }>` — handshake; call once before anything else.
+- `Helix.auth.getUser(): Promise<HelixUser | null>`
+- `Helix.auth.isAuthenticated(): boolean`
+- `Helix.auth.requestLogin(): Promise<HelixUser>` — resolves on login, rejects on dismiss/unavailable.
+- `Helix.auth.onAuthChanged(fn): () => void` — fires on login and logout; returns an unsubscribe fn.
+- `Helix.getSessionToken(): string | null` — the world-scoped token, for advanced direct API calls.
+
+## Protocol
+
+[`src/protocol.ts`](src/protocol.ts) is the wire contract (`postMessage` messages between world and
+shell) and is imported by both sides. Any breaking change must bump `PROTOCOL_VERSION`. The
+`HelixSession` shape matches the backend's `InstantWorldSessionResponseDto`, so the shell forwards
+the backend response verbatim.
+
+## Develop
+
+```bash
+npm install
+npm test       # jest + jsdom
+npm run build  # tsc → dist/ (ESM)
+npm run lint
+```

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+import { HelixWorldContext, HelixUser, DebugLogEntry } from './protocol';
+import { HelixMultiplayer } from './multiplayer';
+export type { HelixWorldContext, HelixSession, HelixUser, DebugLogEntry, DebugLogLevel } from './protocol';
+export type { HelixRoom, JoinRoomOptions, ReplicaInput } from './multiplayer';
+export * from './multiplayer-contract';
+export type HelixInitResult = {
+    embedded: boolean;
+    world: HelixWorldContext | null;
+    user: HelixUser | null;
+};
+type AuthListener = (user: HelixUser | null) => void;
+declare class HelixSdk {
+    private shellOrigin;
+    private session;
+    private world;
+    private initialized;
+    private listeners;
+    private debugEnabled;
+    private debugRing;
+    private debugListeners;
+    private consoleHooked;
+    private pendingLogins;
+    init(): Promise<HelixInitResult>;
+    readonly multiplayer: HelixMultiplayer;
+    readonly debug: {
+        enabled: () => boolean;
+        log: (...args: unknown[]) => void;
+        onLog: (cb: (entry: DebugLogEntry) => void) => (() => void);
+        recent: () => DebugLogEntry[];
+    };
+    readonly auth: {
+        getUser: () => Promise<HelixUser | null>;
+        isAuthenticated: () => boolean;
+        requestLogin: () => Promise<HelixUser>;
+        onAuthChanged: (listener: AuthListener) => (() => void);
+    };
+    getSessionToken(): string | null;
+    private snapshot;
+    private assertInitialized;
+    private waitForInit;
+    private onMessage;
+    private setSession;
+    private enableDebug;
+    private hookConsole;
+    private captureLog;
+    private post;
+}
+export declare const Helix: HelixSdk;

package/dist/index.js

@@ -0,0 +1,238 @@
+import { isShellMessage, PROTOCOL_VERSION, } from './protocol';
+import { HelixMultiplayer } from './multiplayer';
+// The multiplayer wire contract. Re-exported here so `@hypersoniclabs/helix-sdk` root consumers (and
+// classic node-resolution type imports, e.g. the backend minting RoomCredentialClaims) get it; bundler
+// consumers that want only the contract import the lighter '@hypersoniclabs/helix-sdk/multiplayer-contract'.
+export * from './multiplayer-contract';
+const INIT_TIMEOUT_MS = 3000;
+const LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
+const DEBUG_LOG_MAX = 200; // bounded ring of recent log entries (overlay backfill + pre-init forward flush)
+class HelixSdk {
+    shellOrigin = null;
+    session = null;
+    world = null;
+    initialized = false;
+    listeners = new Set();
+    debugEnabled = false;
+    debugRing = [];
+    debugListeners = new Set();
+    consoleHooked = false;
+    pendingLogins = new Map();
+    // Performs the shell handshake. Call once at world start, before any other
+    // Helix API. Resolves with embedded=false if no shell answers (local dev).
+    async init() {
+        if (this.initialized)
+            return this.snapshot();
+        window.addEventListener('message', this.onMessage);
+        if (window.parent !== window) {
+            this.post({ type: 'helix:ready', protocolVersion: PROTOCOL_VERSION }, '*');
+            await this.waitForInit();
+        }
+        this.initialized = true;
+        return this.snapshot();
+    }
+    // Multiplayer (pillar D): Helix.multiplayer.joinRoom(). Reads the world_session token + world id off
+    // this singleton; the heavy Colyseus client is dynamically imported only on join.
+    multiplayer = new HelixMultiplayer({
+        isInitialized: () => this.initialized,
+        getToken: () => this.session?.token ?? null,
+        getWorldId: () => this.world?.id ?? null,
+    });
+    // Debug surface. A world's own console lives in its cross-origin iframe — invisible to DevTools / an
+    // automation harness attached to the shell, and to teammates without that frame selected. debug.log feeds
+    // a bounded ring an in-world overlay can render (onLog/recent), and — when the shell enabled debug
+    // (?debug) — is mirrored to the shell frame's console via helix:log. enableDebug() also hooks console.*
+    // so ALL world output is captured, not just explicit debug.log calls. enabled() is a fn (the flag flips
+    // at init, after the field initializer runs).
+    debug = {
+        enabled: () => this.debugEnabled,
+        log: (...args) => this.captureLog('info', args),
+        onLog: (cb) => {
+            this.debugListeners.add(cb);
+            return () => this.debugListeners.delete(cb);
+        },
+        recent: () => this.debugRing.slice(),
+    };
+    auth = {
+        getUser: async () => {
+            this.assertInitialized();
+            return this.session?.user ?? null;
+        },
+        isAuthenticated: () => {
+            this.assertInitialized();
+            return this.session !== null;
+        },
+        // Asks the shell to raise its login overlay. Resolves with the user after
+        // a successful login; rejects if the player dismisses it or no shell is
+        // present. World state is untouched either way — no reload happens.
+        requestLogin: () => {
+            this.assertInitialized();
+            if (this.session)
+                return Promise.resolve(this.session.user);
+            if (!this.shellOrigin) {
+                return Promise.reject(new Error('Helix: not embedded in a HELIX shell — login unavailable'));
+            }
+            const requestId = Math.random().toString(36).slice(2);
+            return new Promise((resolve, reject) => {
+                const timer = setTimeout(() => {
+                    this.pendingLogins.delete(requestId);
+                    reject(new Error('Helix: login request timed out'));
+                }, LOGIN_TIMEOUT_MS);
+                this.pendingLogins.set(requestId, {
+                    resolve: (u) => {
+                        clearTimeout(timer);
+                        resolve(u);
+                    },
+                    reject: (e) => {
+                        clearTimeout(timer);
+                        reject(e);
+                    },
+                });
+                this.post({ type: 'helix:request-login', requestId }, this.shellOrigin);
+            });
+        },
+        // Fires on login and logout (user becomes null). Returns an unsubscribe fn.
+        onAuthChanged: (listener) => {
+            this.listeners.add(listener);
+            return () => this.listeners.delete(listener);
+        },
+    };
+    // World-scoped session token for direct platform API calls (used by later
+    // SDK modules; exposed for advanced cases). Null when unauthenticated.
+    getSessionToken() {
+        return this.session?.token ?? null;
+    }
+    snapshot() {
+        return {
+            embedded: this.shellOrigin !== null,
+            world: this.world,
+            user: this.session?.user ?? null,
+        };
+    }
+    assertInitialized() {
+        if (!this.initialized) {
+            throw new Error('Helix: call Helix.init() before using the SDK');
+        }
+    }
+    waitForInit() {
+        return new Promise((resolve) => {
+            const timer = setTimeout(resolve, INIT_TIMEOUT_MS);
+            const check = () => {
+                if (this.shellOrigin) {
+                    clearTimeout(timer);
+                    resolve();
+                }
+                else {
+                    setTimeout(check, 10);
+                }
+            };
+            check();
+        });
+    }
+    onMessage = (event) => {
+        if (!isShellMessage(event.data))
+            return;
+        // First valid helix:init pins the shell origin; everything after must match it.
+        if (this.shellOrigin && event.origin !== this.shellOrigin)
+            return;
+        const msg = event.data;
+        switch (msg.type) {
+            case 'helix:init':
+                if (this.shellOrigin)
+                    return;
+                this.shellOrigin = event.origin;
+                this.world = msg.world;
+                this.setSession(msg.session);
+                if (msg.debug)
+                    this.enableDebug();
+                break;
+            case 'helix:session':
+                this.setSession(msg.session);
+                break;
+            case 'helix:login-result': {
+                const pending = this.pendingLogins.get(msg.requestId);
+                if (!pending)
+                    return;
+                this.pendingLogins.delete(msg.requestId);
+                if (msg.ok && this.session)
+                    pending.resolve(this.session.user);
+                else
+                    pending.reject(new Error(`Helix: login ${msg.reason ?? 'failed'}`));
+                break;
+            }
+        }
+    };
+    setSession(session) {
+        const before = this.session?.user.id ?? null;
+        this.session = session;
+        const after = session?.user.id ?? null;
+        if (before !== after) {
+            for (const listener of this.listeners)
+                listener(session?.user ?? null);
+        }
+    }
+    enableDebug() {
+        if (this.debugEnabled)
+            return;
+        this.debugEnabled = true;
+        this.hookConsole();
+        // Flush anything buffered before the shell turned debug on (e.g. early lifecycle logs).
+        if (this.shellOrigin)
+            for (const entry of this.debugRing)
+                this.post({ type: 'helix:log', entry }, this.shellOrigin);
+    }
+    // Capture ALL console output once debug is on (three.js warnings, SDK errors, uncaught logs) — not just
+    // explicit debug.log calls. Pass-through preserves normal console behaviour in the iframe.
+    hookConsole() {
+        if (this.consoleHooked || typeof console === 'undefined')
+            return;
+        this.consoleHooked = true;
+        const levels = ['log', 'info', 'warn', 'error', 'debug'];
+        const c = console;
+        for (const level of levels) {
+            const orig = c[level]?.bind(console);
+            if (!orig)
+                continue;
+            c[level] = (...args) => {
+                this.captureLog(level, args);
+                orig(...args);
+            };
+        }
+    }
+    captureLog(level, args) {
+        const entry = { level, args: args.map(stringifyArg), t: Date.now() };
+        this.debugRing.push(entry);
+        if (this.debugRing.length > DEBUG_LOG_MAX)
+            this.debugRing.shift();
+        for (const cb of this.debugListeners) {
+            try {
+                cb(entry);
+            }
+            catch {
+                /* a listener must never break logging */
+            }
+        }
+        if (this.debugEnabled && this.shellOrigin)
+            this.post({ type: 'helix:log', entry }, this.shellOrigin);
+    }
+    post(message, targetOrigin) {
+        window.parent.postMessage(message, targetOrigin);
+    }
+}
+// Serialize a console arg to a string the shell can print: strings as-is, Errors to their stack, other
+// objects to compact JSON (falling back to String() on cyclic/unserializable values).
+function stringifyArg(a) {
+    if (typeof a === 'string')
+        return a;
+    if (a instanceof Error)
+        return a.stack ?? `${a.name}: ${a.message}`;
+    try {
+        return typeof a === 'object' && a !== null ? JSON.stringify(a) : String(a);
+    }
+    catch {
+        return String(a);
+    }
+}
+// Worlds import this singleton: `import { Helix } from '@hypersoniclabs/helix-sdk'`.
+export const Helix = new HelixSdk();
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/multiplayer-contract/credential.d.ts

@@ -0,0 +1,34 @@
+export declare const ROOM_CREDENTIAL_AUDIENCE: "helix-instant-room";
+/**
+ * Claims the backend signs (HS384) and the room verifies. Mirrors the world_session claim shape
+ * (sub/displayName/worldId/scopes/jti) plus the immutable buildId the room loads its config from.
+ */
+export interface RoomCredentialClaims {
+    /** Player/user id. */
+    sub: string;
+    /** Sanitized display name for nameplates. */
+    displayName: string;
+    /** World the room belongs to. */
+    worldId: string;
+    /** Immutable build the room loads its declarative config (allowed messages, room-var shape) from. */
+    buildId: string;
+    /** Scopes from manifest.permissions; must include 'multiplayer' to join a room. */
+    scopes: string[];
+    /** Manifest maxPlayers (authoritative) → the room's maxClients cap, so it auto-locks + spills when full. */
+    maxPlayers: number;
+    /** Monotonic per-world build counter (1, 2, 3 …) of the active build — telemetry + config cache key. */
+    buildNumber: number;
+    /**
+     * Signed URL of this build's `multiplayer.json` — the validated declarative config baked into the
+     * published bundle. Derived server-side from the build, NEVER client-supplied, so the room fetches its
+     * config from an authentic, immutable location and caches the parsed result by buildId. The room
+     * tolerates its absence (older credentials / a build with no declared config) by running the fixed schema.
+     */
+    configUrl: string;
+    /** Always ROOM_CREDENTIAL_AUDIENCE. */
+    aud: typeof ROOM_CREDENTIAL_AUDIENCE;
+    iss: string;
+    exp: number;
+    iat: number;
+    jti: string;
+}

package/dist/multiplayer-contract/credential.js

@@ -0,0 +1,5 @@
+// Room credential — the short-lived JWT the backend mints (createRoomSession) and the Colyseus room
+// verifies in onAuth with a shared HMAC secret (ROOM_JWT_SECRET, Option C). Distinct audience from the
+// world_session token (aud 'helix-instant-world') so a world token can't be replayed to join a room.
+export const ROOM_CREDENTIAL_AUDIENCE = 'helix-instant-room';
+//# sourceMappingURL=credential.js.map

package/dist/multiplayer-contract/credential.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential.js","sourceRoot":"","sources":["../../src/multiplayer-contract/credential.ts"],"names":[],"mappings":"AAAA,oGAAoG;AACpG,uGAAuG;AACvG,qGAAqG;AAErG,MAAM,CAAC,MAAM,wBAAwB,GAAG,oBAA6B,CAAC"}

package/dist/multiplayer-contract/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Wire format version. Bump on any incompatible change to PlayerReplicaState, the message table, the
+ * credential claims, or the realized declared-state shape (roomVars / per-player vars / entities).
+ *
+ * The SDK sends this in its join options; the room compares it in onAuth and LOGS a mismatch (P1.C2) — it
+ * does NOT reject. The SDK is frozen into each published bundle, so a newer room must keep admitting older
+ * builds; rejecting on mismatch would brick every published world on a bump. The detection is for
+ * cross-version diagnostics, and contract changes are kept additive/forward so older clients still play.
+ */
+export declare const CONTRACT_VERSION: 11;
+export * from './state';
+export * from './room';
+export * from './messages';
+export * from './credential';

package/dist/multiplayer-contract/index.js

@@ -0,0 +1,30 @@
+// @hypersoniclabs/helix-sdk/multiplayer-contract — the multiplayer wire contract.
+//
+// The single source of truth for the data shapes three independently-built pieces must agree on:
+//   • the Colyseus room (@colyseus/schema state + message dispatch + runtime validation),
+//   • this SDK's Helix.multiplayer client (send path + room.state),
+//   • the engine's NetworkDriver adapter (consumes the replicated params → blackboard).
+// Plus the backend (mints RoomCredentialClaims) and the room (verifies them).
+//
+// Pure types + constants, ZERO runtime deps — so the standalone three.js engine adapter can import
+// the types at zero runtime cost. Runtime message validation lives in the room (the only place
+// untrusted inbound messages arrive), not here.
+//
+// The state has two layers (see room.ts): players are FIXED (the engine character contract); roomVars,
+// per-player vars, and entities are DECLARED per-world — that's how an agent syncs custom game state
+// without writing server code. The generic 'action' message (messages.ts) is the channel for it.
+/**
+ * Wire format version. Bump on any incompatible change to PlayerReplicaState, the message table, the
+ * credential claims, or the realized declared-state shape (roomVars / per-player vars / entities).
+ *
+ * The SDK sends this in its join options; the room compares it in onAuth and LOGS a mismatch (P1.C2) — it
+ * does NOT reject. The SDK is frozen into each published bundle, so a newer room must keep admitting older
+ * builds; rejecting on mismatch would brick every published world on a bump. The detection is for
+ * cross-version diagnostics, and contract changes are kept additive/forward so older clients still play.
+ */
+export const CONTRACT_VERSION = 11; // v11: EntityStateBatch — many owner-entity uploads in one message (Tier 2 Phase 4.10, beats the per-connection message-count cap)
+export * from './state';
+export * from './room';
+export * from './messages';
+export * from './credential';
+//# sourceMappingURL=index.js.map

package/dist/multiplayer-contract/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/multiplayer-contract/index.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,EAAE;AACF,iGAAiG;AACjG,0FAA0F;AAC1F,oEAAoE;AACpE,wFAAwF;AACxF,8EAA8E;AAC9E,EAAE;AACF,mGAAmG;AACnG,+FAA+F;AAC/F,gDAAgD;AAChD,EAAE;AACF,uGAAuG;AACvG,qGAAqG;AACrG,iGAAiG;AAEjG;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,EAAW,CAAC,CAAC,mIAAmI;AAEhL,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC"}

package/dist/multiplayer-contract/messages.d.ts

@@ -0,0 +1,173 @@
+import type { Vec3 } from './state';
+import type { RoomVarValue } from './room';
+export declare const ClientMessageType: {
+    /** The player's predicted kinematic state for this tick (seq-tagged for reconciliation). */
+    readonly State: "state";
+    /** Activate or deactivate an ability on this player (the built-in, engine-level intent). */
+    readonly Ability: "ability";
+    /** A world-authored declared action (the generic extensibility channel — see ActionMessage). */
+    readonly Action: "action";
+    /** An owner-authoritative entity's client-simulated state for this tick (Tier 2 Phase 4.6c — see EntityStateMessage). */
+    readonly EntityState: "entityState";
+    /**
+     * A BATCH of owner-authoritative entity uploads for this tick — ALL the entities this connection hosts in one
+     * message (Tier 2 Phase 4.10 — see EntityStateBatchMessage). The per-connection rate cap counts MESSAGES, so a
+     * host of N entities must batch (one message/tick) instead of N single EntityState messages, or it starves its
+     * own upload budget. EntityScene uses this; the single EntityState stays for one-off uploads (e.g. a flag).
+     */
+    readonly EntityStateBatch: "entityStateBatch";
+    /** Clock-sync probe: the client's local timestamp, which the room echoes in a Pong (RTT + offset). */
+    readonly Ping: "ping";
+};
+export type ClientMessageType = (typeof ClientMessageType)[keyof typeof ClientMessageType];
+/** Server → client messages (the room sends these; SDK exposes them via room.onMessage(type, cb)). */
+export declare const ServerMessageType: {
+    /** Reply to a Ping: the client's echoed timestamp + the server's current time, for offset estimation. */
+    readonly Pong: "pong";
+};
+export type ServerMessageType = (typeof ServerMessageType)[keyof typeof ServerMessageType];
+/** Per-tick state upload. Units match PlayerReplicaState (position m; all angles degrees, see *Deg). */
+export interface StateMessage {
+    /** Monotonic per-client sequence; the room echoes the last applied seq for client reconciliation. */
+    seq: number;
+    position: Vec3;
+    facingYawDeg: number;
+    speed: number;
+    moveDirectionDeg: number;
+    verticalVelocity: number;
+    grounded: boolean;
+    crouched: boolean;
+    aimYawDeg: number;
+    aimPitchDeg: number;
+}
+/**
+ * An owner-authoritative entity's client-simulated state for this tick (Tier 2 Phase 4.6c, spec §9/§10.4). The
+ * client that the server marked as the entity's `controller` (see EntityState.controller) simulates the entity
+ * and uploads its transform + declared vars; the room sanity-validates (it owns this entity? movement within
+ * its declared `maxSpeed`? vars within their declared bounds?) and relays. Cross-player consequences still go
+ * through server-validated rules/actions — never this channel (the publish-time firewall enforces that).
+ */
+export interface EntityStateMessage {
+    /** The entity id this upload is for (the state.entities map key). Rejected unless the sender is its controller. */
+    entity: string;
+    /** Monotonic per-entity sequence; the room ignores a stale/out-of-order frame. */
+    seq: number;
+    /** The entity's world position, METERS — gated against the kind's declared maxSpeed. */
+    position: Vec3;
+    /** Declared per-kind vars to set (same vocabulary as roomVars); each is clamped to its declared type/bounds on ingest. */
+    vars?: Record<string, RoomVarValue>;
+    /**
+     * The authority EPOCH the client is simulating under (Tier 2 Phase 4.5.12, spec §9). Mirror the entity's synced
+     * `authorityEpoch`; the room bumps it on every controller handoff (host migration AND voluntary ownership
+     * transfer) and rejects an upload whose epoch ≠ the entity's current one — fencing a revoked/stale authority
+     * era even from a still-connected prior owner whose sessionId would otherwise pass. Omit only for the very
+     * first frame before the field is observed; the room tolerates absence (sessionId ownership still gates).
+     */
+    epoch?: number;
+}
+/**
+ * One entity's slot in an EntityStateBatchMessage. Compact, short keys (sent verbatim in msgpack), with position
+ * as a 3-tuple instead of a {x,y,z} object — the same authoritative meaning as EntityStateMessage's per-entity
+ * fields. `v`/`ep` are omitted when unchanged/unobserved to keep the batch small.
+ */
+export interface EntityStateBatchEntry {
+    /** Entity id (the state.entities map key). Rejected unless the sender is its controller. */
+    e: string;
+    /** World position as [x, y, z], METERS — gated against the kind's declared maxSpeed. */
+    p: [number, number, number];
+    /** Declared per-kind vars to set (clamped to declared type/bounds on ingest). Omit when unchanged this tick. */
+    v?: Record<string, RoomVarValue>;
+    /** Authority epoch this entity is simulated under (mirror its synced authorityEpoch). Omit before observed. */
+    ep?: number;
+}
+/**
+ * A batch of owner-authoritative entity uploads (Tier 2 Phase 4.10, spec §10.4) — every entity this connection
+ * hosts, in ONE message. The per-connection rate cap (MESSAGE_RATE.entityStateHz) counts messages, so batching
+ * lets a host refresh many entities per tick within one token instead of spending one token per entity. The room
+ * applies each entry exactly like a single EntityStateMessage (ownership + epoch + maxSpeed gate + var clamp).
+ */
+export interface EntityStateBatchMessage {
+    /** Monotonic per-connection batch sequence; the room ignores a stale/out-of-order batch per entity (gate seq). */
+    seq: number;
+    /** One entry per hosted entity changed this tick (bounded by the room's per-owner entity cap). */
+    states: EntityStateBatchEntry[];
+}
+/** Discrete ability activation intent. */
+export interface AbilityMessage {
+    /** Ability id (must be one the world's build declares). */
+    ability: string;
+    /** true = activate, false = deactivate. */
+    active: boolean;
+}
+/**
+ * A world-authored declared action — the generic extensibility channel (e.g. 'captureFlag',
+ * 'scorePoint'). The room validates `name` against the world's declared action set and `args` against
+ * that action's declared arg schema before mutating authoritative state (table-driven dispatch); this
+ * module carries the envelope + arg vocabulary only, never the per-world rules.
+ */
+export interface ActionMessage {
+    /** Action name; must be one the world's build declares. */
+    name: string;
+    /** Primitive/Vec3 args, validated against the declared action's schema by the room. */
+    args?: Record<string, RoomVarValue>;
+}
+/**
+ * Clock-sync probe. The client sends its local send time; the room replies (Pong) with this value echoed
+ * plus its own clock, so the client estimates RTT (recv − send) and offset (serverTimeMs − send − RTT/2).
+ */
+export interface PingMessage {
+    /** The client's local clock (epoch ms) at send — echoed verbatim in the Pong. */
+    clientTimeMs: number;
+}
+/** Reply to a Ping — the echoed client time + the server's clock at reply, for offset/RTT estimation. */
+export interface PongMessage {
+    clientTimeMs: number;
+    serverTimeMs: number;
+}
+/**
+ * A server→client broadcast event (Tier 2 Phase 2.5, spec §10.3). A world declares named events with a
+ * payload schema; a `broadcast` rule-effect sends one on the event's NAME (not a fixed ServerMessageType),
+ * received via `room.onMessage(name, cb)`. Payload values are the declared fields; a `ref` field serializes
+ * to its `playerKey` string on the wire (so `who:"self"` and `who:{aggregate argmax}` are the same type).
+ */
+export type BroadcastPayload = Record<string, RoomVarValue>;
+/**
+ * Wire message-type names a world's declared event/action names MUST NOT shadow — the fixed client→server
+ * and server→client channels. The manifest validator rejects a declared name in this set so a `broadcast`
+ * can't collide with `pong` (or confuse the fixed channels). Inlined in @hypersoniclabs/helix-manifest with
+ * a cross-ref (the manifest takes no SDK dependency); keep the two in sync.
+ */
+export declare const RESERVED_MESSAGE_TYPES: readonly ["state", "ability", "action", "entityState", "entityStateBatch", "ping", "pong"];
+/** Maps each client→server message type to its payload, so senders/handlers stay in lockstep. */
+export interface ClientMessagePayloads {
+    [ClientMessageType.State]: StateMessage;
+    [ClientMessageType.Ability]: AbilityMessage;
+    [ClientMessageType.Action]: ActionMessage;
+    [ClientMessageType.EntityState]: EntityStateMessage;
+    [ClientMessageType.EntityStateBatch]: EntityStateBatchMessage;
+    [ClientMessageType.Ping]: PingMessage;
+}
+/** Maps each server→client message type to its payload. */
+export interface ServerMessagePayloads {
+    [ServerMessageType.Pong]: PongMessage;
+}
+/**
+ * Per-connection rate ceilings (messages/second) the room enforces; over-rate clients are dropped.
+ * State is the throttled input channel (≤~10Hz, plan D3); ability is bursty but bounded.
+ */
+export declare const MESSAGE_RATE: {
+    readonly stateHz: 10;
+    readonly abilityHz: 20;
+    readonly actionHz: 20;
+    readonly entityStateHz: 10;
+    readonly pingHz: 4;
+};
+/**
+ * Hard payload bound the room rejects above (defense against oversized frames), measured on the JSON form (a
+ * cheap proxy; the msgpack wire is smaller). Sized (P1.B4) to admit a full EntityStateBatch — MAX_ENTITIES_PER_OWNER
+ * (128) entities with modest vars in one message (≈75 JSON bytes/entry) — so the byte cap and the per-owner entity
+ * cap don't disagree. MUST stay below the Colyseus transport `maxPayload` (16 KB, helix-colyseus-server src/index.ts)
+ * in WIRE terms, so the room's reject fires before the transport drops the frame / closes the socket. A var-heavy
+ * batch past this is a CLEAN DROP (the room's guard does not strike on an over-byte payload), never a kick.
+ */
+export declare const MAX_MESSAGE_BYTES = 12288;