@helixdev/helix-sdk 0.1.1-staging.7 → 0.1.1-staging.9

package/dist/index.d.ts

@@ -1,5 +1,8 @@
-import { HelixWorldContext, HelixUser } from './protocol';
-export type { HelixWorldContext, HelixSession, HelixUser } from './protocol';
+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;
@@ -12,8 +15,19 @@ declare class HelixSdk {
     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;
@@ -26,6 +40,9 @@ declare class HelixSdk {
     private waitForInit;
     private onMessage;
     private setSession;
+    private enableDebug;
+    private hookConsole;
+    private captureLog;
     private post;
 }
 export declare const Helix: HelixSdk;

package/dist/index.js

@@ -1,12 +1,22 @@
 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).
@@ -21,6 +31,28 @@ class HelixSdk {
         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();
@@ -111,6 +143,8 @@ class HelixSdk {
                 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);
@@ -137,10 +171,68 @@ class HelixSdk {
                 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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAOL,cAAc,EACd,gBAAgB,GACjB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAKjD,qGAAqG;AACrG,uGAAuG;AACvG,6GAA6G;AAC7G,cAAc,wBAAwB,CAAC;AAYvC,MAAM,eAAe,GAAG,IAAI,CAAC;AAC7B,MAAM,gBAAgB,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;AACvC,MAAM,aAAa,GAAG,GAAG,CAAC,CAAC,iFAAiF;AAE5G,MAAM,QAAQ;IACJ,WAAW,GAAkB,IAAI,CAAC;IAClC,OAAO,GAAwB,IAAI,CAAC;IACpC,KAAK,GAA6B,IAAI,CAAC;IACvC,WAAW,GAAG,KAAK,CAAC;IACpB,SAAS,GAAG,IAAI,GAAG,EAAgB,CAAC;IACpC,YAAY,GAAG,KAAK,CAAC;IACrB,SAAS,GAAoB,EAAE,CAAC;IAChC,cAAc,GAAG,IAAI,GAAG,EAAkC,CAAC;IAC3D,aAAa,GAAG,KAAK,CAAC;IACtB,aAAa,GAAG,IAAI,GAAG,EAG5B,CAAC;IAEJ,2EAA2E;IAC3E,2EAA2E;IAC3E,KAAK,CAAC,IAAI;QACR,IAAI,IAAI,CAAC,WAAW;YAAE,OAAO,IAAI,CAAC,QAAQ,EAAE,CAAC;QAC7C,MAAM,CAAC,gBAAgB,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QAEnD,IAAI,MAAM,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;YAC7B,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,eAAe,EAAE,gBAAgB,EAAE,EAAE,GAAG,CAAC,CAAC;YAC3E,MAAM,IAAI,CAAC,WAAW,EAAE,CAAC;QAC3B,CAAC;QACD,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;QACxB,OAAO,IAAI,CAAC,QAAQ,EAAE,CAAC;IACzB,CAAC;IAED,qGAAqG;IACrG,kFAAkF;IACzE,WAAW,GAAG,IAAI,gBAAgB,CAAC;QAC1C,aAAa,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,WAAW;QACrC,QAAQ,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,IAAI,IAAI;QAC3C,UAAU,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,IAAI,IAAI;KACzC,CAAC,CAAC;IAEH,qGAAqG;IACrG,0GAA0G;IAC1G,mGAAmG;IACnG,wGAAwG;IACxG,wGAAwG;IACxG,8CAA8C;IACrC,KAAK,GAAG;QACf,OAAO,EAAE,GAAY,EAAE,CAAC,IAAI,CAAC,YAAY;QACzC,GAAG,EAAE,CAAC,GAAG,IAAe,EAAQ,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,IAAI,CAAC;QAChE,KAAK,EAAE,CAAC,EAAkC,EAAgB,EAAE;YAC1D,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAC5B,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAC9C,CAAC;QACD,MAAM,EAAE,GAAoB,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE;KACtD,CAAC;IAEO,IAAI,GAAG;QACd,OAAO,EAAE,KAAK,IAA+B,EAAE;YAC7C,IAAI,CAAC,iBAAiB,EAAE,CAAC;YACzB,OAAO,IAAI,CAAC,OAAO,EAAE,IAAI,IAAI,IAAI,CAAC;QACpC,CAAC;QAED,eAAe,EAAE,GAAY,EAAE;YAC7B,IAAI,CAAC,iBAAiB,EAAE,CAAC;YACzB,OAAO,IAAI,CAAC,OAAO,KAAK,IAAI,CAAC;QAC/B,CAAC;QAED,0EAA0E;QAC1E,wEAAwE;QACxE,oEAAoE;QACpE,YAAY,EAAE,GAAuB,EAAE;YACrC,IAAI,CAAC,iBAAiB,EAAE,CAAC;YACzB,IAAI,IAAI,CAAC,OAAO;gBAAE,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YAC5D,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;gBACtB,OAAO,OAAO,CAAC,MAAM,CACnB,IAAI,KAAK,CAAC,0DAA0D,CAAC,CACtE,CAAC;YACJ,CAAC;YAED,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACtD,OAAO,IAAI,OAAO,CAAY,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;gBAChD,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;oBAC5B,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;oBACrC,MAAM,CAAC,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC,CAAC;gBACtD,CAAC,EAAE,gBAAgB,CAAC,CAAC;gBACrB,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,SAAS,EAAE;oBAChC,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE;wBACb,YAAY,CAAC,KAAK,CAAC,CAAC;wBACpB,OAAO,CAAC,CAAC,CAAC,CAAC;oBACb,CAAC;oBACD,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE;wBACZ,YAAY,CAAC,KAAK,CAAC,CAAC;wBACpB,MAAM,CAAC,CAAC,CAAC,CAAC;oBACZ,CAAC;iBACF,CAAC,CAAC;gBACH,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,qBAAqB,EAAE,SAAS,EAAE,EAAE,IAAI,CAAC,WAAY,CAAC,CAAC;YAC3E,CAAC,CAAC,CAAC;QACL,CAAC;QAED,4EAA4E;QAC5E,aAAa,EAAE,CAAC,QAAsB,EAAgB,EAAE;YACtD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YAC7B,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC/C,CAAC;KACF,CAAC;IAEF,0EAA0E;IAC1E,uEAAuE;IACvE,eAAe;QACb,OAAO,IAAI,CAAC,OAAO,EAAE,KAAK,IAAI,IAAI,CAAC;IACrC,CAAC;IAEO,QAAQ;QACd,OAAO;YACL,QAAQ,EAAE,IAAI,CAAC,WAAW,KAAK,IAAI;YACnC,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,IAAI,IAAI;SACjC,CAAC;IACJ,CAAC;IAEO,iBAAiB;QACvB,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;QACnE,CAAC;IACH,CAAC;IAEO,WAAW;QACjB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;YAC7B,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;YACnD,MAAM,KAAK,GAAG,GAAG,EAAE;gBACjB,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;oBACrB,YAAY,CAAC,KAAK,CAAC,CAAC;oBACpB,OAAO,EAAE,CAAC;gBACZ,CAAC;qBAAM,CAAC;oBACN,UAAU,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;gBACxB,CAAC;YACH,CAAC,CAAC;YACF,KAAK,EAAE,CAAC;QACV,CAAC,CAAC,CAAC;IACL,CAAC;IAEO,SAAS,GAAG,CAAC,KAAmB,EAAE,EAAE;QAC1C,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,IAAI,CAAC;YAAE,OAAO;QACxC,gFAAgF;QAChF,IAAI,IAAI,CAAC,WAAW,IAAI,KAAK,CAAC,MAAM,KAAK,IAAI,CAAC,WAAW;YAAE,OAAO;QAElE,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC;QACvB,QAAQ,GAAG,CAAC,IAAI,EAAE,CAAC;YACjB,KAAK,YAAY;gBACf,IAAI,IAAI,CAAC,WAAW;oBAAE,OAAO;gBAC7B,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC,MAAM,CAAC;gBAChC,IAAI,CAAC,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC;gBACvB,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;gBAC7B,IAAI,GAAG,CAAC,KAAK;oBAAE,IAAI,CAAC,WAAW,EAAE,CAAC;gBAClC,MAAM;YACR,KAAK,eAAe;gBAClB,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;gBAC7B,MAAM;YACR,KAAK,oBAAoB,CAAC,CAAC,CAAC;gBAC1B,MAAM,OAAO,GAAG,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;gBACtD,IAAI,CAAC,OAAO;oBAAE,OAAO;gBACrB,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;gBACzC,IAAI,GAAG,CAAC,EAAE,IAAI,IAAI,CAAC,OAAO;oBAAE,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;;oBAC1D,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,gBAAgB,GAAG,CAAC,MAAM,IAAI,QAAQ,EAAE,CAAC,CAAC,CAAC;gBACzE,MAAM;YACR,CAAC;QACH,CAAC;IACH,CAAC,CAAC;IAEM,UAAU,CAAC,OAA4B;QAC7C,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC;QAC7C,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,MAAM,KAAK,GAAG,OAAO,EAAE,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC;QACvC,IAAI,MAAM,KAAK,KAAK,EAAE,CAAC;YACrB,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS;gBAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,IAAI,IAAI,CAAC,CAAC;QACzE,CAAC;IACH,CAAC;IAEO,WAAW;QACjB,IAAI,IAAI,CAAC,YAAY;YAAE,OAAO;QAC9B,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;QACzB,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,wFAAwF;QACxF,IAAI,IAAI,CAAC,WAAW;YAAE,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,SAAS;gBAAE,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;IACtH,CAAC;IAED,wGAAwG;IACxG,2FAA2F;IACnF,WAAW;QACjB,IAAI,IAAI,CAAC,aAAa,IAAI,OAAO,OAAO,KAAK,WAAW;YAAE,OAAO;QACjE,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC;QAC1B,MAAM,MAAM,GAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QAC1E,MAAM,CAAC,GAAG,OAA+D,CAAC;QAC1E,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;YACrC,IAAI,CAAC,IAAI;gBAAE,SAAS;YACpB,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,IAAe,EAAE,EAAE;gBAChC,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;gBAC7B,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;YAChB,CAAC,CAAC;QACJ,CAAC;IACH,CAAC;IAEO,UAAU,CAAC,KAAoB,EAAE,IAAe;QACtD,MAAM,KAAK,GAAkB,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;QACpF,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC3B,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,GAAG,aAAa;YAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;QAClE,KAAK,MAAM,EAAE,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACrC,IAAI,CAAC;gBACH,EAAE,CAAC,KAAK,CAAC,CAAC;YACZ,CAAC;YAAC,MAAM,CAAC;gBACP,yCAAyC;YAC3C,CAAC;QACH,CAAC;QACD,IAAI,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,WAAW;YAAE,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;IACvG,CAAC;IAEO,IAAI,CAAC,OAA4B,EAAE,YAAoB;QAC7D,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;IACnD,CAAC;CACF;AAED,uGAAuG;AACvG,sFAAsF;AACtF,SAAS,YAAY,CAAC,CAAU;IAC9B,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,CAAC,CAAC;IACpC,IAAI,CAAC,YAAY,KAAK;QAAE,OAAO,CAAC,CAAC,KAAK,IAAI,GAAG,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;IACpE,IAAI,CAAC;QACH,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAC7E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC;IACnB,CAAC;AACH,CAAC;AAED,qFAAqF;AACrF,MAAM,CAAC,MAAM,KAAK,GAAG,IAAI,QAAQ,EAAE,CAAC"}

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,10 @@
+/**
+ * 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), so the
+ * room/SDK/driver can detect a mismatch instead of misreading bytes.
+ */
+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,26 @@
+// @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), so the
+ * room/SDK/driver can detect a mismatch instead of misreading bytes.
+ */
+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;;;;GAIG;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,171 @@
+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 to admit a full EntityStateBatch — up to MAX_ENTITIES_PER_OWNER
+ * entities in one message. MUST stay below the Colyseus transport `maxPayload` (set in helix-colyseus-server
+ * src/index.ts) in WIRE terms, so our clean reject fires before the transport drops the frame / closes the socket.
+ */
+export declare const MAX_MESSAGE_BYTES = 8192;

package/dist/multiplayer-contract/messages.js

@@ -0,0 +1,57 @@
+// Client → server messages. The SDK send path emits these; the room dispatches them through a
+// table keyed by ClientMessageType and validates every payload before mutating authoritative state
+// (the room owns runtime validation — this module is types + limits only, no validator, no deps).
+//
+// Tier 1 (lean authoritative, no server physics): the client predicts locally and sends its state
+// each tick (seq-tagged so the room can echo for reconciliation); the room validates bounds/rate and
+// writes the authoritative copy. Discrete intents (ability on/off) are their own message.
+export const ClientMessageType = {
+    /** The player's predicted kinematic state for this tick (seq-tagged for reconciliation). */
+    State: 'state',
+    /** Activate or deactivate an ability on this player (the built-in, engine-level intent). */
+    Ability: 'ability',
+    /** A world-authored declared action (the generic extensibility channel — see ActionMessage). */
+    Action: 'action',
+    /** An owner-authoritative entity's client-simulated state for this tick (Tier 2 Phase 4.6c — see EntityStateMessage). */
+    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).
+     */
+    EntityStateBatch: 'entityStateBatch',
+    /** Clock-sync probe: the client's local timestamp, which the room echoes in a Pong (RTT + offset). */
+    Ping: 'ping',
+};
+/** Server → client messages (the room sends these; SDK exposes them via room.onMessage(type, cb)). */
+export const ServerMessageType = {
+    /** Reply to a Ping: the client's echoed timestamp + the server's current time, for offset estimation. */
+    Pong: 'pong',
+};
+/**
+ * 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 const RESERVED_MESSAGE_TYPES = ['state', 'ability', 'action', 'entityState', 'entityStateBatch', 'ping', 'pong'];
+/**
+ * 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 const MESSAGE_RATE = {
+    stateHz: 10,
+    abilityHz: 20,
+    actionHz: 20,
+    entityStateHz: 10, // owner-entity upload — same cadence as the player state channel (one bucket per connection)
+    pingHz: 4, // clock-sync probe — a few per second is ample to track offset/RTT
+};
+/**
+ * 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 to admit a full EntityStateBatch — up to MAX_ENTITIES_PER_OWNER
+ * entities in one message. MUST stay below the Colyseus transport `maxPayload` (set in helix-colyseus-server
+ * src/index.ts) in WIRE terms, so our clean reject fires before the transport drops the frame / closes the socket.
+ */
+export const MAX_MESSAGE_BYTES = 8192;
+//# sourceMappingURL=messages.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"messages.js","sourceRoot":"","sources":["../../src/multiplayer-contract/messages.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,mGAAmG;AACnG,kGAAkG;AAClG,EAAE;AACF,kGAAkG;AAClG,qGAAqG;AACrG,0FAA0F;AAK1F,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,4FAA4F;IAC5F,KAAK,EAAE,OAAO;IACd,4FAA4F;IAC5F,OAAO,EAAE,SAAS;IAClB,gGAAgG;IAChG,MAAM,EAAE,QAAQ;IAChB,yHAAyH;IACzH,WAAW,EAAE,aAAa;IAC1B;;;;;OAKG;IACH,gBAAgB,EAAE,kBAAkB;IACpC,sGAAsG;IACtG,IAAI,EAAE,MAAM;CACJ,CAAC;AAGX,sGAAsG;AACtG,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,yGAAyG;IACzG,IAAI,EAAE,MAAM;CACJ,CAAC;AAqHX;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,EAAE,MAAM,CAAU,CAAC;AAiBjI;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,OAAO,EAAE,EAAE;IACX,SAAS,EAAE,EAAE;IACb,QAAQ,EAAE,EAAE;IACZ,aAAa,EAAE,EAAE,EAAE,6FAA6F;IAChH,MAAM,EAAE,CAAC,EAAE,mEAAmE;CACtE,CAAC;AAEX;;;;;GAKG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,CAAC"}

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

@@ -0,0 +1,92 @@
+import type { Vec3 } from './state';
+import type { PlayerIdentity, PlayerReplicaState } from './state';
+/**
+ * The runtime value vocabulary for declared custom state. A `ref`-typed var's value is the **id** of a live
+ * member (a player's `playerKey` or an entity id) as a string, or `null` when unset/dangling — hence `null`
+ * is included. The DECLARATION vocabulary (`VarType`: number/string/boolean/vec3/ref + bounds) lives in
+ * `@hypersoniclabs/helix-manifest` (authored config, validated at publish); this is the wire value side.
+ */
+export type RoomVarValue = number | string | boolean | Vec3 | null | RoomVarCollection;
+/**
+ * Per-player/room COLLECTION values (Tier 2 Phase 4.5.13, spec §5). A `list` var reads as an ordered array of
+ * its declared scalar element type (realized server-side as a colyseus ArraySchema); a `counterMap` var reads as
+ * a string→number record over its declared key enum (a MapSchema<number>). Mutated only via the dedicated
+ * append/clear/addCount effects + read via listLength/listAt/count ops — never a normal scalar expr/payload/arg.
+ */
+export type RoomVarCollection = number[] | string[] | boolean[] | Record<string, number>;
+/** A declared bag of custom state — names + types are declared per-world; used for both room-level and per-player vars. */
+export type RoomVars = Record<string, RoomVarValue>;
+/** Full authoritative per-player state: the FIXED character contract + identity + DECLARED game vars. */
+export interface PlayerState extends PlayerIdentity, PlayerReplicaState {
+    /** Declared per-player game state (e.g. team, health, score). Same vocabulary as roomVars; declared per-world. */
+    vars: RoomVars;
+    /**
+     * Presence (Tier 2 Phase 3, spec §8): `false` while this seat sits in the reconnection grace window after an
+     * unexpected drop — the seat (and its refs) persists, but the server excludes it from reductions. The seat is
+     * removed (an `onRemove('players')`) only at grace expiry; until then the engine should render the replica idle.
+     * This layers on Colyseus's own reconnection — it annotates the seat, it does not drive the reconnect handshake.
+     */
+    connected: boolean;
+}
+/**
+ * RESERVED (Tier 2): a server-spawned object (pickup, projectile, NPC). Empty in v1 — the shape is
+ * reserved so adding server-spawned entities later is additive. Tier 2 gives these author-defined
+ * behavior; v1 only freezes the slot in RoomState.
+ */
+export interface EntityState {
+    id: string;
+    /** Author-defined kind (e.g. 'flag', 'pickup'). */
+    kind: string;
+    position?: Vec3;
+    /**
+     * Who simulates this entity (Tier 2 Phase 4.6c, spec §9). '' = server-authoritative (deterministic kinematics).
+     * A player id (a state.players key) = an owner-authoritative entity that client simulates + uploads (the others
+     * render it); a client reads this to know which entities it should be uploading via uploadEntity.
+     */
+    controller: string;
+    /**
+     * Monotonic authority epoch (Tier 2 Phase 4.5.12, spec §9), bumped on every controller handoff — host
+     * migration AND voluntary ownership transfer. A controller client mirrors this into each EntityStateMessage;
+     * the room rejects an upload whose epoch ≠ the current one, fencing a stale authority era (a still-connected
+     * prior owner's in-flight frames after ownership moved). 0 at spawn; clients only read it.
+     */
+    authorityEpoch: number;
+    /** Declared custom vars (same vocabulary as roomVars). */
+    vars: RoomVars;
+}
+/** The authoritative shared state. Always carries all three collections (entities empty until Tier 2). */
+export interface RoomState {
+    /** Per-player authoritative state, keyed by player id. Realized as a colyseus MapSchema. */
+    players: Record<string, PlayerState>;
+    /** Room-level declared game state (scores, timers, objectives). Names/types declared per-world. */
+    roomVars: RoomVars;
+    /** RESERVED (Tier 2): server-spawned entities. Empty in v1. */
+    entities: Record<string, EntityState>;
+    /** Authoritative server clock: a monotonic counter advanced once per fixed-rate sim tick. */
+    serverTick: number;
+    /**
+     * Authoritative server wall-clock (epoch ms) sampled at the last tick. Clients align to it (offset via the
+     * ping/pong echo, see messages.ts) and interpolate between patches, so timer/phase deadlines expressed
+     * against server time agree across clients without a per-tick countdown var.
+     */
+    serverTimeMs: number;
+    /**
+     * The current phase of the world's room-scoped state machine (Tier 2 Phase 3, spec §8), or `''` when the
+     * world declares no `states`. Authored phase names; changed only by the server's `transitionTo`. A
+     * late-joiner reads it off synced state to know whether to spawn in or spectate (the join policy).
+     */
+    phase: string;
+    /**
+     * The `serverTick` at which the room entered its current `phase`. With `serverTick`/`serverTimeMs` a client
+     * computes time-in-phase locally (e.g. a round countdown) without a per-tick countdown var.
+     */
+    phaseStartTick: number;
+    /**
+     * Active timers (Tier 2 Phase 3, spec §8) → absolute deadline as `serverTimeMs` (epoch ms). The map key is
+     * the timer name for a room-scoped timer, or `"<timer>|<playerKey>"` for a per-player **keyed** timer (e.g.
+     * read your own cooldown at `"cooldown|" + room.sessionId`). A client computes the seconds remaining as
+     * `(deadline − estimatedServerTimeMs) / 1000` using its ping/pong offset, so a countdown interpolates locally
+     * without a per-tick countdown var. An entry is removed when the timer fires or is cancelled.
+     */
+    timerDeadlines: Record<string, number>;
+}

package/dist/multiplayer-contract/room.js

@@ -0,0 +1,17 @@
+// The authoritative room state shape — the FRAMEWORK for what a world syncs. The room holds this as
+// @colyseus/schema (the Record<string, T> maps below are realized as MapSchema); the SDK exposes it as
+// room.state. Two layers, and the distinction is the whole answer to "how does an agent sync more?":
+//
+//   • players  — FIXED. Each player is the engine's character contract (PlayerReplicaState) + identity.
+//                Universal across every world; an agent never changes its fields.
+//   • roomVars / per-player vars / entities — DECLARED PER-WORLD. This is where an agent's game state
+//                lives (scores, timers, teams, objectives). The agent DECLARES names + types in the
+//                world's multiplayer config (loaded by buildId at onCreate); the one generic HelixRoom
+//                interprets the declaration — no agent-authored server code (Tier 1).
+//
+// Tier-1 vocabulary is intentionally bounded (primitives + Vec3). Rich/nested custom state and
+// author-defined entity behavior are Tier 2 (a reflection-based dynamic schema + behavior DSL),
+// deferred — the `entities` collection and this declared-bag shape are the reserved seams that keep
+// Tier 2 additive rather than a rewrite.
+export {};
+//# sourceMappingURL=room.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"room.js","sourceRoot":"","sources":["../../src/multiplayer-contract/room.ts"],"names":[],"mappings":"AAAA,oGAAoG;AACpG,uGAAuG;AACvG,qGAAqG;AACrG,EAAE;AACF,wGAAwG;AACxG,kFAAkF;AAClF,sGAAsG;AACtG,oGAAoG;AACpG,uGAAuG;AACvG,sFAAsF;AACtF,EAAE;AACF,+FAA+F;AAC/F,gGAAgG;AAChG,oGAAoG;AACpG,yCAAyC"}