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

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { HelixWorldContext, HelixUser } from './protocol';
+import { HelixWorldContext, HelixUser, DebugLogEntry } from './protocol';
 import { HelixMultiplayer } from './multiplayer';
-export type { HelixWorldContext, HelixSession, HelixUser } from './protocol';
+export type { HelixWorldContext, HelixSession, HelixUser, DebugLogEntry, DebugLogLevel } from './protocol';
 export type { HelixRoom, JoinRoomOptions, ReplicaInput } from './multiplayer';
 export * from './multiplayer-contract';
 export type HelixInitResult = {
@@ -15,9 +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;
@@ -30,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

@@ -6,12 +6,17 @@ import { HelixMultiplayer } from './multiplayer';
 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).
@@ -33,6 +38,21 @@ class HelixSdk {
         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();
@@ -123,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);
@@ -149,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":"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"}

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

@@ -16,6 +16,15 @@ export interface RoomCredentialClaims {
     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;

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

@@ -1,8 +1,9 @@
 /**
- * Wire format version. Bump on any incompatible change to PlayerReplicaState, the message table, or
- * the credential claims, so the room/SDK/driver can detect a mismatch instead of misreading bytes.
+ * 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: 2;
+export declare const CONTRACT_VERSION: 11;
 export * from './state';
 export * from './room';
 export * from './messages';

package/dist/multiplayer-contract/index.js

@@ -14,10 +14,11 @@
 // 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, or
- * the credential claims, so the room/SDK/driver can detect a mismatch instead of misreading bytes.
+ * 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 = 2;
+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';

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

@@ -1 +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;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAU,CAAC;AAE3C,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC"}
+{"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

@@ -7,8 +7,25 @@ export declare const ClientMessageType: {
     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. */
@@ -23,6 +40,58 @@ export interface StateMessage {
     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). */
@@ -42,11 +111,45 @@ export interface ActionMessage {
     /** Primitive/Vec3 args, validated against the declared action's schema by the room. */
     args?: Record<string, RoomVarValue>;
 }
-/** Maps each message type to its payload, so senders/handlers stay in lockstep. */
+/**
+ * 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.
@@ -56,6 +159,13 @@ 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). */
-export declare const MAX_MESSAGE_BYTES = 1024;
+/**
+ * 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

@@ -12,7 +12,30 @@ export const ClientMessageType = {
     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.
@@ -21,7 +44,14 @@ 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). */
-export const MAX_MESSAGE_BYTES = 1024;
+/**
+ * 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

@@ -1 +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;CACR,CAAC;AA8CX;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,OAAO,EAAE,EAAE;IACX,SAAS,EAAE,EAAE;IACb,QAAQ,EAAE,EAAE;CACJ,CAAC;AAEX,oFAAoF;AACpF,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,CAAC"}
+{"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

@@ -1,13 +1,32 @@
 import type { Vec3 } from './state';
 import type { PlayerIdentity, PlayerReplicaState } from './state';
-/** The value vocabulary an agent may declare for custom state (Tier 1). Tier 2 widens this. */
-export type RoomVarValue = number | string | boolean | Vec3;
+/**
+ * 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
@@ -19,6 +38,19 @@ export interface EntityState {
     /** 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;
 }
@@ -30,4 +62,31 @@ export interface RoomState {
     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/state.d.ts

@@ -11,7 +11,7 @@ export declare const UNITS: {
 };
 /** Stable per-player identity (set at join from the room credential; not part of the per-tick churn). */
 export interface PlayerIdentity {
-    /** Player/user id (the credential `sub`). */
+    /** Opaque per-connection room playerKey (= the state.players map key). NOT the credential `sub` — that stays server-side (§4). */
     id: string;
     /** Sanitized display name for nameplates (sanitized before it enters room state — see plan H4). */
     displayName: string;

package/dist/multiplayer.d.ts

@@ -1,4 +1,4 @@
-import { type StateMessage, type RoomState, type PlayerState, type EntityState, type RoomVarValue } from './multiplayer-contract';
+import { type StateMessage, type RoomState, type PlayerState, type EntityState, type RoomVarValue, type Vec3 } from './multiplayer-contract';
 export type ReplicaInput = Omit<StateMessage, 'seq'>;
 /** Options for joinRoom — only needed where the API base can't be derived from the token (local dev/tests). */
 export interface JoinRoomOptions {
@@ -26,6 +26,27 @@ export interface HelixRoom {
     sendAbility(ability: string, active: boolean): void;
     /** A world-authored declared action (the generic extensibility channel). */
     sendAction(name: string, args?: Record<string, RoomVarValue>): void;
+    /**
+     * Upload an owner-authoritative entity's client-simulated state (Tier 2 Phase 4.6c). Call only for an entity
+     * whose `controller` is this client (state.entities[id].controller === sessionId); the room rejects others.
+     * Sent immediately, per-entity seq-tagged; the room gates the position against the kind's maxSpeed + clamps vars.
+     */
+    uploadEntity(entityId: string, input: {
+        position: Vec3;
+        vars?: Record<string, RoomVarValue>;
+    }): void;
+    /**
+     * Upload MANY owner-authoritative entities in ONE message (Tier 2 Phase 4.10). Prefer this over per-entity
+     * uploadEntity when hosting multiple entities: the per-connection rate cap counts messages, so N single uploads
+     * spend N tokens/tick and starve, while one batch spends one. Position is sent as a compact [x,y,z] tuple; each
+     * entry is gated/clamped server-side exactly like uploadEntity. Pass only entities this client controls.
+     */
+    uploadEntities(entities: ReadonlyArray<{
+        id: string;
+        position: Vec3;
+        vars?: Record<string, RoomVarValue>;
+        epoch?: number;
+    }>): void;
     /** Sent-but-unacknowledged states — the reconciliation tail the engine NetworkDriver replays (D4). */
     pendingInputs(): readonly StateMessage[];
     /** Prune the reconciliation buffer once the server confirms it processed up to `seq` (D4). */
@@ -50,10 +71,12 @@ export declare class HelixMultiplayer {
     private room;
     private callbacks;
     private seq;
+    private entitySeq;
+    private entityBatchSeq;
     private pendingInput;
     private flushTimer;
     private inputBuffer;
-    private onUnload;
+    private worldId;
     constructor(host: MultiplayerHost);
     configure(options: {
         apiBaseUrl: string;
@@ -63,7 +86,11 @@ export declare class HelixMultiplayer {
     private makeHandle;
     private startFlush;
     private flush;
-    private attachUnload;
+    private persistReconnect;
+    private readReconnect;
+    private reconnectWsUrl;
+    private clearReconnect;
+    private tryReconnect;
     private leave;
     private teardown;
 }