@vgai/p2p-colyseus 0.5.2 → 0.5.4

package/package.json

@@ -2,7 +2,7 @@
   "name": "@vgai/p2p-colyseus",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "type": "module",
   "description": "Colyseus-compatible transport for vgai — real Colyseus, loopback, WebRTC, or relay, chosen at runtime.",
   "homepage": "https://github.com/volter-ai/vgai-engine#readme",
@@ -18,8 +18,6 @@
   "exports": {
     ".": "./src/index.ts",
     "./engine": "./src/engine.ts",
-    "./schema": "./src/schema.ts",
-    "./codec": "./src/codec.ts",
     "./client": "./src/client.ts",
     "./browser": "./src/browser.ts",
     "./server": "./src/room.ts",
@@ -35,11 +33,11 @@
     "wrangler:deploy": "wrangler deploy --config wrangler.toml"
   },
   "dependencies": {
+    "@colyseus/schema": "^4.0.14",
     "ws": "^8.19.0"
   },
   "devDependencies": {
     "@colyseus/sdk": "^0.17.34",
-    "@colyseus/schema": "^4.0.14",
     "@colyseus/ws-transport": "^0.17.9",
     "@types/node": "^25.3.0",
     "@types/ws": "^8.5.13",

package/src/access-token.ts

@@ -1,7 +1,101 @@
 export interface P2PAccessTokenClaims {
   readonly roomName: string;
   readonly peerId?: string | undefined;
+  /**
+   * The account this token was minted for. Absent on anonymous/self-hosted
+   * tokens (which must still verify — backward compat); present on managed-lane
+   * tokens so the relay can meter a free byte allotment per account.
+   */
+  readonly userId?: string | undefined;
   readonly expiresAt: number;
+  /**
+   * Token purpose. Absent/`'relay'` → a spendable relay access token the relay
+   * accepts. `'grant'` → a per-game mint GRANT (see {@link mintRelayGrant}):
+   * NOT spendable on the relay, only exchangeable at `/relay/session` for a
+   * fresh relay token. The relay read path ({@link readP2PAccessToken}) rejects
+   * `'grant'` outright, and a grant is signed with a DIFFERENT key besides, so
+   * a grant can never be replayed as a relay token.
+   */
+  readonly kind?: 'relay' | 'grant' | undefined;
+}
+
+/**
+ * The grant claims baked into a deployed game's public manifest. A grant
+ * authorizes ANONYMOUS players of that one game to mint short-lived relay
+ * tokens for the deployer's account, scoped to the deployed room — the
+ * authorization that lets `/relay/session` (unauthenticated) safely issue a
+ * relay token bearing the deployer's `userId`. Abuse is bounded to the
+ * deployer's per-account/per-room relay byte budget, exactly as the old baked
+ * relay token was — but the grant is refreshable and, unlike a raw relay
+ * token, is not directly spendable on the relay.
+ */
+export interface RelayGrantClaims {
+  readonly kind: 'grant';
+  readonly userId: string;
+  readonly roomName: string;
+  readonly expiresAt: number;
+}
+
+/**
+ * Domain-separated grant-signing subkey derived from the relay access secret.
+ * A grant is signed with THIS key, never the raw secret, so the relay — which
+ * only ever holds the raw secret — cannot verify (and therefore cannot accept)
+ * a grant as a spendable token. This gives cryptographic key separation
+ * between "grant" and "relay token" with a SINGLE provisioned secret; the relay
+ * needs no new binding and never learns this subkey.
+ */
+export async function deriveRelayGrantKey(secret: string): Promise<string> {
+  return sign(secret, 'vgai-relay-grant-v1');
+}
+
+/**
+ * Mint a long-lived per-game relay-mint GRANT (see {@link RelayGrantClaims}).
+ * Signed with {@link deriveRelayGrantKey}, so it is inert against the relay.
+ * `vgai deploy` mints one of these (authenticated as the deployer) and bakes it
+ * into the served manifest; players exchange it at `/relay/session` for a fresh
+ * short-lived relay token at connect time — which is why a deployed game's
+ * multiplayer never expires on the token's clock, only on the grant's much
+ * longer one.
+ */
+export async function mintRelayGrant(
+  secret: string,
+  opts: { userId: string; roomName: string; ttlMs: number; nowMs: number },
+): Promise<{ grant: string; expiresAt: number }> {
+  const grantKey = await deriveRelayGrantKey(secret);
+  const expiresAt = opts.nowMs + opts.ttlMs;
+  const grant = await createP2PAccessToken(grantKey, {
+    kind: 'grant',
+    userId: opts.userId,
+    roomName: opts.roomName,
+    expiresAt,
+  });
+  return { grant, expiresAt };
+}
+
+/**
+ * Verify a grant and return its `{ userId, roomName }` (or null when invalid,
+ * wrong-kind, or expired). The exchange path `/relay/session` calls this to
+ * decide whether to mint a relay token, and for which account/room.
+ */
+export async function readRelayGrant(
+  secret: string,
+  grant: string,
+  now = Date.now(),
+): Promise<{ userId: string; roomName: string } | null> {
+  const grantKey = await deriveRelayGrantKey(secret);
+  const [payload, signature, extra] = grant.split('.');
+  if (!payload || !signature || extra !== undefined) return null;
+  if (!constantTimeEqual(signature, await sign(grantKey, payload))) return null;
+  let claims: RelayGrantClaims;
+  try {
+    claims = JSON.parse(decodeBase64Url(payload)) as RelayGrantClaims;
+  } catch {
+    return null;
+  }
+  if (claims.kind !== 'grant') return null;
+  if (typeof claims.userId !== 'string' || typeof claims.roomName !== 'string') return null;
+  if (!(Number.isFinite(claims.expiresAt) && claims.expiresAt > now)) return null;
+  return { userId: claims.userId, roomName: claims.roomName };
 }
 
 export async function createP2PAccessToken(
@@ -13,27 +107,76 @@ export async function createP2PAccessToken(
   return `${payload}.${signature}`;
 }
 
-export async function verifyP2PAccessToken(
+/**
+ * NEW (2026-08): the shared relay-token mint. A thin wrapper over
+ * {@link createP2PAccessToken} that turns a wall-clock issuance moment plus a
+ * TTL into the `expiresAt` the token claims carry, so every managed home that
+ * issues relay access (the CF-native `@vgai/auth` Worker, and the legacy
+ * account-service route in `app.ts` until it is retired) computes expiry one
+ * way. Keeps the `createP2PAccessToken` primitive untouched — this only owns
+ * the `expiresAt = nowMs + ttlMs` convention and returns it alongside the token
+ * so the caller can echo it to the client.
+ *
+ * `expiresAt` is an epoch-MILLISECONDS instant, not seconds: the read path
+ * ({@link readP2PAccessToken}) compares it against `Date.now()` directly, and
+ * the account-service route it mirrors (`app.ts` `relayToken`) already mints
+ * `Date.now() + ttlMs`. A seconds value would be ~1000x smaller than `now` and
+ * so read as permanently expired.
+ */
+export async function mintRelayToken(
+  secret: string,
+  opts: { userId: string; roomName: string; ttlMs: number; nowMs: number },
+): Promise<{ token: string; expiresAt: number }> {
+  const expiresAt = opts.nowMs + opts.ttlMs;
+  const token = await createP2PAccessToken(secret, {
+    roomName: opts.roomName,
+    userId: opts.userId,
+    expiresAt,
+  });
+  return { token, expiresAt };
+}
+
+/**
+ * Verify a token AND return its decoded claims (or null when invalid). This is
+ * the read path the relay uses to recover `userId` for per-account metering;
+ * {@link verifyP2PAccessToken} is the boolean shorthand over the same checks.
+ */
+export async function readP2PAccessToken(
   secret: string,
   token: string,
   expected: { roomName: string; peerId?: string | undefined },
   now = Date.now(),
-): Promise<boolean> {
+): Promise<P2PAccessTokenClaims | null> {
   const [payload, signature, extra] = token.split('.');
-  if (!payload || !signature || extra !== undefined) return false;
+  if (!payload || !signature || extra !== undefined) return null;
   const expectedSignature = await sign(secret, payload);
-  if (!constantTimeEqual(signature, expectedSignature)) return false;
+  if (!constantTimeEqual(signature, expectedSignature)) return null;
 
   let claims: P2PAccessTokenClaims;
   try {
     claims = JSON.parse(decodeBase64Url(payload)) as P2PAccessTokenClaims;
   } catch {
-    return false;
+    return null;
   }
 
-  if (claims.roomName !== expected.roomName) return false;
-  if (expected.peerId && claims.peerId && claims.peerId !== expected.peerId) return false;
-  return Number.isFinite(claims.expiresAt) && claims.expiresAt > now;
+  // A GRANT is never spendable on the relay — it is only exchangeable at
+  // /relay/session. Reject it here too (belt-and-suspenders: a grant is also
+  // signed with a different key, so it would already fail the signature check
+  // above unless the grant key were misconfigured to equal the raw secret).
+  if (claims.kind === 'grant') return null;
+  if (claims.roomName !== expected.roomName) return null;
+  if (expected.peerId && claims.peerId && claims.peerId !== expected.peerId) return null;
+  if (!(Number.isFinite(claims.expiresAt) && claims.expiresAt > now)) return null;
+  return claims;
+}
+
+export async function verifyP2PAccessToken(
+  secret: string,
+  token: string,
+  expected: { roomName: string; peerId?: string | undefined },
+  now = Date.now(),
+): Promise<boolean> {
+  return (await readP2PAccessToken(secret, token, expected, now)) !== null;
 }
 
 async function sign(secret: string, payload: string): Promise<string> {

package/src/browser.ts

@@ -1,3 +1,49 @@
+export {
+  $changes,
+  $childType,
+  $decoder,
+  $deleteByIndex,
+  $encoder,
+  $filter,
+  $getByIndex,
+  $refId,
+  $track,
+  ArraySchema,
+  Callbacks as SchemaCallbacks,
+  ChangeTree,
+  CollectionSchema,
+  Decoder,
+  decode,
+  decodeKeyValueOperation,
+  decodeSchemaOperation,
+  defineCustomTypes,
+  defineTypes,
+  deprecated,
+  dumpChanges,
+  Encoder,
+  encode,
+  encodeArray,
+  encodeKeyValueOperation,
+  encodeSchemaOperation,
+  entity,
+  getDecoderStateCallbacks,
+  getRawChangesCallback,
+  MapSchema,
+  Metadata,
+  OPERATION,
+  Reflection,
+  ReflectionField,
+  ReflectionType,
+  registerType,
+  Schema,
+  SetSchema,
+  StateCallbackStrategy,
+  StateView,
+  schema,
+  TypeContext,
+  type,
+  view,
+} from '@colyseus/schema';
 export type { P2PAccessTokenClaims } from './access-token';
 export { createP2PAccessToken, verifyP2PAccessToken } from './access-token';
 export { Callbacks } from './callbacks';
@@ -19,7 +65,6 @@ export {
 export { SignalingRelayCoordinator } from './cloudflare/coordinator';
 export type { RelayLimits } from './cloudflare/limits';
 export { DEFAULT_RELAY_LIMITS } from './cloudflare/limits';
-export { applyStatePatch, clone, createStatePatch, encodeSnapshot } from './codec';
 export type {
   NetDiagnostics,
   RelayProofDiagnostics,
@@ -146,57 +191,11 @@ export {
   WebSocketClient,
   WebSocketTransport,
 } from './platform';
-export type { Envelope, Snapshot, StatePatch, StatePatchOperation } from './protocol';
+export type { Envelope } from './protocol';
 export { isEnvelope, P2P_CLOSE_CODES } from './protocol';
 export { CloudflareRelayPacketChannel } from './relay';
 export type { CompatClient } from './room';
 export { Room } from './room';
 export type { RoomClass } from './runtime';
 export { UniversalRoomRuntime } from './runtime';
-export {
-  $changes,
-  $childType,
-  $decoder,
-  $deleteByIndex,
-  $encoder,
-  $filter,
-  $getByIndex,
-  $refId,
-  $track,
-  ArraySchema,
-  Callbacks as SchemaCallbacks,
-  ChangeTree,
-  CollectionSchema,
-  Decoder,
-  decode,
-  decodeKeyValueOperation,
-  decodeSchemaOperation,
-  defineCustomTypes,
-  defineTypes,
-  deprecated,
-  dumpChanges,
-  Encoder,
-  encode,
-  encodeArray,
-  encodeKeyValueOperation,
-  encodeSchemaOperation,
-  entity,
-  getDecoderStateCallbacks,
-  getRawChangesCallback,
-  MapSchema,
-  Metadata,
-  OPERATION,
-  Reflection,
-  ReflectionField,
-  ReflectionType,
-  registerType,
-  Schema,
-  SetSchema,
-  StateCallbackStrategy,
-  StateView,
-  schema,
-  TypeContext,
-  type,
-  view,
-} from './schema';
 export { createWebRTCDataChannelPacketChannel, WebRTCDataChannelPacketChannel } from './webrtc';

package/src/callbacks.ts

@@ -1,7 +1,11 @@
-import type { CompatRoom } from './client';
-
-export const Callbacks = {
-  get(room: CompatRoom): CompatRoom['replication'] {
-    return room.replication;
-  },
-};
+/**
+ * The client Callbacks API is the REAL `@colyseus/schema` one.
+ *
+ * `Callbacks.get(room)` returns the legacy string-keyed strategy
+ * (`onAdd('players', …)`, `onChange(item, …)`, `bindTo(…)`) and accepts a
+ * `{ serializer: { decoder } }` — exactly the shape `CompatRoom` exposes — so
+ * an authored game that calls `Callbacks.get(room)` behaves identically on the
+ * P2P path and against a real Colyseus server. The v4 `$` proxy is
+ * `getStateCallbacks(room)` (see `client.ts`).
+ */
+export { Callbacks } from '@colyseus/schema';

package/src/channels.ts

@@ -21,4 +21,15 @@ export interface PacketChannel {
    * against a wire-incompatible peer instead of hanging forever.
    */
   onProtocolError?(handler: (reason: string) => void): () => void;
+  /**
+   * Optional: send this envelope over an UNRELIABLE (unordered, no-retransmit)
+   * sub-transport when the channel has one — the delivery `sendUnreliable`
+   * asks for. Only the WebRTC channel has a second `RTCDataChannel`
+   * (`{ordered: false, maxRetransmits: 0}`) to carry it; ordered transports
+   * (loopback, websocket, relay, real Colyseus) have no unreliable mode and
+   * omit this, so `CompatRoom.sendUnreliable` correctly degrades to the
+   * reliable `send` path on them. The envelope shape is identical to `send`'s
+   * — same JSON `Envelope` protocol, different channel.
+   */
+  sendUnreliable?(envelope: Envelope): void;
 }

package/src/client.ts

@@ -1,14 +1,21 @@
+import {
+  Decoder,
+  getDecoderStateCallbacks,
+  Schema,
+  type SchemaCallbackProxy,
+} from '@colyseus/schema';
 import type { PacketChannel } from './channels';
-import { applyStatePatch } from './codec';
 import type { P2PColyseusMode } from './engine';
 import { createSignal } from './events';
 import { createLoopbackPair } from './loopback';
 import { type Envelope, P2P_CLOSE_CODES } from './protocol';
-import { ClientReplication } from './replication';
+import { getRegisteredRoom, registeredRoomNames, registerLoopbackRoom } from './room-registry';
 import { type RoomClass, UniversalRoomRuntime } from './runtime';
 import { createWebSocketPacketChannel } from './websocket';
+import { base64ToBytes } from './wire-bytes';
+
+export { registerLoopbackRoom } from './room-registry';
 
-const loopbackRooms = new Map<string, RoomClass>();
 let configuredP2P:
   | {
       mode: Extract<P2PColyseusMode, { kind: 'p2p-host' | 'p2p-join' }>;
@@ -19,10 +26,6 @@ let configuredP2P:
 const hostedP2PRoomIds = new Map<string, string>();
 const localP2PClientCounts = new Map<string, number>();
 
-export function registerLoopbackRoom(roomName: string, roomClass: RoomClass): void {
-  loopbackRooms.set(roomName, roomClass);
-}
-
 export function configureP2PColyseusClient(options: {
   mode: Extract<P2PColyseusMode, { kind: 'p2p-host' | 'p2p-join' }>;
   rooms?: Record<string, RoomClass> | undefined;
@@ -154,7 +157,7 @@ export class Client {
   async getAvailableRooms(roomName?: string): Promise<AvailableRoom[]> {
     const roomNames = configuredP2P
       ? Object.keys(configuredP2P.rooms ?? {})
-      : [...loopbackRooms.keys()];
+      : registeredRoomNames();
     return roomNames
       .filter((name) => roomName === undefined || name === roomName)
       .map((name) => ({
@@ -215,7 +218,7 @@ export class Client {
     if (!this.url.startsWith('loopback://')) {
       throw new Error(`Unsupported @vgai/p2p-colyseus client URL: ${this.url}`);
     }
-    const roomClass = loopbackRooms.get(roomName);
+    const roomClass = getRegisteredRoom(roomName);
     if (!roomClass) throw new Error(`Loopback room not registered: ${roomName}`);
 
     // joinOrCreate semantics: the creating client's options reach onCreate.
@@ -277,14 +280,65 @@ function publishP2PMode(mode: string): void {
 
 export const ColyseusSDK = Client;
 
-export function getStateCallbacks(room: CompatRoom): ClientReplication {
-  return room.replication;
+/**
+ * The v4 Callbacks proxy over the client's REAL `@colyseus/schema` decoder —
+ * identical to `@colyseus/sdk`'s `getStateCallbacks(room)`
+ * (`$(state).players.onAdd(...)`, `$(item).listen(...)`, `$(item).onChange`,
+ * `$(from).bindTo(...)`). The legacy string-keyed API is `Callbacks.get(room)`,
+ * which the real `@colyseus/schema` `Callbacks` provides directly off
+ * `room.serializer.decoder`.
+ */
+export function getStateCallbacks(room: CompatRoom): SchemaCallbackProxy<Schema> {
+  if (!room.decoder) {
+    throw new Error(
+      `getStateCallbacks: room "${room.name}" has no decoded @colyseus/schema state — ` +
+        `register the room class via configureP2PColyseusClient({ rooms }).`,
+    );
+  }
+  return getDecoderStateCallbacks(room.decoder);
 }
 
 export function registerSerializer(): void {}
 
+/**
+ * Build the client-side decoder root from the LOCALLY-REGISTERED room class
+ * (shipped to the client via `configureP2PColyseusClient({ rooms })`). No
+ * Reflection handshake — a fresh instance of the room's `Schema` state class is
+ * all the real `Decoder` needs, and it is compatible with the host `Encoder`
+ * because both use the same class through the same `@colyseus/schema`.
+ */
+function buildDecoder(roomName: string): Decoder<Schema> | undefined {
+  const RoomClass = getRegisteredRoom(roomName);
+  if (!RoomClass) return undefined;
+  const probe = new RoomClass() as { state?: unknown; onCreate?: (options?: unknown) => void };
+  let state = probe.state;
+  if (!(state instanceof Schema)) {
+    // Rooms that assign state in onCreate rather than a field initializer.
+    try {
+      probe.onCreate?.();
+    } catch {
+      /* best-effort probe — the state class is all we need */
+    }
+    state = probe.state;
+  }
+  try {
+    (probe as { _disposeRuntime?: () => void })._disposeRuntime?.();
+  } catch {
+    /* the probe never attached a runtime; nothing to clean up */
+  }
+  if (!(state instanceof Schema)) return undefined;
+  return new Decoder(new (state.constructor as new () => Schema)());
+}
+
 export class CompatRoom {
-  readonly replication = new ClientReplication();
+  /**
+   * The client's real `@colyseus/schema` decoder — undefined for stateless
+   * rooms. Rebuilt from a fresh state root on a FULL snapshot (resync) so
+   * host-side removals since the last sync cannot linger as ghost entries.
+   */
+  decoder: Decoder<Schema> | undefined;
+  /** Exposed so the real `Callbacks.get(room)` / `getStateCallbacks(room)` resolve the decoder. */
+  readonly serializer: { decoder: Decoder<Schema> | undefined };
   readonly onLeave = createSignal<(code?: number, reason?: string) => void>();
   readonly onError = createSignal<(code: number, message?: string) => void>();
   readonly onReconnect = createSignal<() => void>();
@@ -293,7 +347,7 @@ export class CompatRoom {
   roomId = '';
   sessionId = '';
   reconnectionToken = '';
-  state: Record<string, unknown> = this.replication.state;
+  state: Record<string, unknown> = {};
   private readonly messages = new Map<string, Set<(payload: unknown) => void>>();
   private readonly wildcardMessages = new Set<(type: string, payload: unknown) => void>();
   private readonly pendingPings = new Map<number, (ms: number) => void>();
@@ -303,6 +357,9 @@ export class CompatRoom {
     readonly name: string,
     private readonly channel: PacketChannel,
   ) {
+    this.decoder = buildDecoder(name);
+    this.serializer = { decoder: this.decoder };
+    if (this.decoder) this.state = this.decoder.state as unknown as Record<string, unknown>;
     this.channel.onEnvelope((envelope) => this.handleEnvelope(envelope));
     this.channel.onClose((reason) => {
       this.onDrop.emit(undefined, reason);
@@ -318,11 +375,11 @@ export class CompatRoom {
       // package's compat wire protocol at all — most concretely, a compat
       // client pointed at a real Colyseus server (raw `ws://`), which frames
       // its own binary schema-diff protocol and never sends `join-ok`/
-      // `join-error`. Without this, that mismatch hangs `join()` forever
-      // (see docs/decisions/h4-endpoint-interop.md). All three listeners are
-      // torn down the moment the join settles one way or another, so none of
-      // them can observe — or reject on — anything that happens in a normal
-      // session after a successful join, including its normal eventual close.
+      // `join-error`. Without this, that mismatch hangs `join()` forever. All
+      // three listeners are torn down the moment the join settles one way or
+      // another, so none of them can observe — or reject on — anything that
+      // happens in a normal session after a successful join, including its
+      // normal eventual close.
       const unsubscribers: Array<() => void> = [];
       const teardown = () => {
         for (const off of unsubscribers) off();
@@ -336,8 +393,7 @@ export class CompatRoom {
             this.sessionId = envelope.sessionId;
             this.reconnectionToken = `${this.roomId}:${this.sessionId}`;
             this.clock = envelope.clock;
-            this.replication.applySnapshot(envelope.snapshot.state);
-            this.state = this.replication.state;
+            this.applyEncodedState(envelope.state);
             resolve();
           } else if (envelope.kind === 'join-error' && envelope.requestId === requestId) {
             teardown();
@@ -369,6 +425,15 @@ export class CompatRoom {
   }
 
   sendUnreliable<T = unknown>(type: string, payload?: T): void {
+    // Route over the channel's unreliable (unordered, no-retransmit) transport
+    // when it has one — only the WebRTC channel does. On ordered transports
+    // (loopback, websocket, relay, real Colyseus) there is no unreliable
+    // channel, and degrading to the reliable `send` path is correct: the
+    // message still arrives, just ordered/reliable.
+    if (this.channel.sendUnreliable) {
+      this.channel.sendUnreliable({ kind: 'message', type, payload });
+      return;
+    }
     this.send(type, payload);
   }
 
@@ -450,11 +515,44 @@ export class CompatRoom {
     }
   }
 
+  /** Decode base64-carried `@colyseus/schema` bytes into the live decoder state. */
+  private applyEncodedState(base64: string): void {
+    if (!this.decoder) return;
+    this.decoder.decode(base64ToBytes(base64));
+    this.state = this.decoder.state as unknown as Record<string, unknown>;
+  }
+
+  /**
+   * Replace the decoder with a fresh root before applying a FULL snapshot. A
+   * full snapshot (`encodeAll`) emits only ADDs for current entries and never
+   * removals; decoding it onto the already-populated decoder would leave stale
+   * "ghost" entries for anything the host dropped since the last sync. A fresh
+   * root — built from the same locally-registered room class the join decoder
+   * used — reflects EXACTLY the snapshot.
+   *
+   * Consequence: this swaps the decoder the `$`/Callbacks proxy is bound to, so
+   * persistent `$(state)....onAdd/onChange` handlers registered before a resync
+   * stop firing afterward and would need re-registration. Accepted because a
+   * ghost entry is data corruption (correctness outranks callback persistence)
+   * and a full-snapshot resync is rare (state patches ride the ordered-reliable
+   * channel — gaps essentially only follow real loss or a setState-replace). If
+   * that ever bites a real game, the parity-correct fix is to reconcile the live
+   * decoder's collections in place instead of swapping the root.
+   */
+  private rebuildDecoder(): void {
+    const fresh = buildDecoder(this.name);
+    if (!fresh) return;
+    this.decoder = fresh;
+    this.serializer.decoder = fresh;
+    this.state = fresh.state as unknown as Record<string, unknown>;
+  }
+
   private handleStateSnapshot(envelope: Extract<Envelope, { kind: 'state-snapshot' }>): void {
     if (envelope.clock <= this.clock) return;
     this.clock = envelope.clock;
-    this.replication.applySnapshot(envelope.snapshot.state);
-    this.state = this.replication.state;
+    // FULL snapshot only (resync / setState-replace) — clear ghosts, then decode.
+    this.rebuildDecoder();
+    this.applyEncodedState(envelope.state);
     this.onStateChange.emit(this.state);
   }
 
@@ -465,9 +563,7 @@ export class CompatRoom {
       return;
     }
     this.clock = envelope.clock;
-    const patched = applyStatePatch(this.replication.state, envelope.patch);
-    this.replication.applySnapshot(patched);
-    this.state = this.replication.state;
+    this.applyEncodedState(envelope.patch);
     this.onStateChange.emit(this.state);
   }