@jgengine/ws 0.18.0 → 0.19.0

package/dist/host.d.ts

@@ -1,7 +1,8 @@
 import type { GameRuntime } from "@jgengine/core/runtime/gameRuntime";
 import type { HostPersistence, ServerListing, SessionAttributes } from "@jgengine/core/runtime/hostPersistence";
 import type { MatchFilter, SessionListing } from "@jgengine/core/multiplayer/matchmaking";
-import type { GameRuntimePlayerView, GameRuntimeServerView, JoinServerResult, TransportRunCommandResult } from "@jgengine/core/runtime/transport";
+import type { GameRuntimePlayerView, GameRuntimeServerView, JoinServerResult, TransportRunCommandResult, WorldSyncFrame } from "@jgengine/core/runtime/transport";
+import type { SnapshotViewer } from "@jgengine/core/runtime/worldSnapshot";
 /** A change notification emitted by a `GameHost` for a server, player, or feed mutation. */
 export type HostChangeEvent = {
     type: "server";
@@ -33,6 +34,7 @@ export type GameHost = {
         serverId?: string;
         attributes?: SessionAttributes;
         code?: string;
+        role?: SnapshotViewer["role"];
     }) => Promise<JoinServerResult>;
     browseServers: (args: {
         gameId: string;
@@ -53,6 +55,8 @@ export type GameHost = {
         serverId: string;
         command: string;
         input: unknown;
+        /** Set only from host code: runs commands marked `access: "server"`, which client messages cannot. */
+        trusted?: boolean;
     }) => Promise<TransportRunCommandResult>;
     isMember: (args: {
         userId: string;
@@ -61,7 +65,14 @@ export type GameHost = {
     getServerView: (args: {
         userId: string;
         serverId: string;
+        role?: SnapshotViewer["role"];
     }) => Promise<GameRuntimeServerView | null>;
+    pullWorld?: (args: {
+        userId: string;
+        serverId: string;
+        sinceRevision: number | null;
+        role?: SnapshotViewer["role"];
+    }) => Promise<WorldSyncFrame | null>;
     getPlayerView: (args: {
         userId: string;
         serverId: string;

package/dist/host.js

@@ -1,4 +1,5 @@
 import { createGameRuntime } from "@jgengine/core/runtime/gameRuntime";
+import { SERVER_ONLY_COMMAND_REASON } from "@jgengine/core/runtime/commandRunner";
 import { applyLeaderboardRows, buildHydratePlayers, planServerPersist, profileLeaderboardStats, shouldAutoSave, topLeaderboardRows, toOpenServerListings, toServerListing, trimFeedEntries, } from "@jgengine/core/runtime/hostPersistence";
 import { isListablePublicly, isPrivateJoinBlocked, isServerFull, isServerMember, statusAfterLeave, withJoinedMember, withoutMember, } from "@jgengine/core/runtime/hostPolicy";
 import { browseSessions, findByJoinCode } from "@jgengine/core/multiplayer/matchmaking";
@@ -96,6 +97,7 @@ export function createGameHost(options) {
             playersByUserId: buildHydratePlayers(record, profiles),
             chunksByKey,
             revision: record.revision,
+            nowMs: now(),
         });
         const existing = live.get(record.serverId);
         if (existing)
@@ -160,7 +162,7 @@ export function createGameHost(options) {
                 return { ticked: 0, saved: 0 };
             const runtime = resolveRuntime(entry.record.gameId);
             const before = entry.snapshot.revision;
-            entry.snapshot = runtime.tick(entry.snapshot, elapsedMs / 1_000);
+            entry.snapshot = runtime.tick(entry.snapshot, elapsedMs / 1_000, timestamp);
             entry.record = { ...entry.record, tickAnchorMs: timestamp, updatedAt: timestamp };
             if (entry.snapshot.revision !== before) {
                 markMutated(entry);
@@ -265,7 +267,7 @@ export function createGameHost(options) {
                     updatedAt: timestamp,
                     dirtyAt: timestamp,
                 };
-                entry.snapshot = runtime.joinPlayer(entry.snapshot, args.userId, isNew);
+                entry.snapshot = runtime.joinPlayer(entry.snapshot, args.userId, isNew, timestamp);
                 await flushServer(entry);
                 emit({ type: "server", serverId: entry.record.serverId });
                 emit({ type: "player", serverId: entry.record.serverId, userId: args.userId });
@@ -329,7 +331,10 @@ export function createGameHost(options) {
             }
             const commandInput = envelope !== null ? envelope.input : args.input;
             const runtime = resolveRuntime(entry.record.gameId);
-            const result = runtime.runCommand(entry.snapshot, args.userId, args.command, commandInput);
+            if (args.trusted !== true && runtime.commandAccess(args.command) === "server") {
+                return { ok: false, reason: SERVER_ONLY_COMMAND_REASON };
+            }
+            const result = runtime.runCommand(entry.snapshot, args.userId, args.command, commandInput, now());
             const outcome = result.ok
                 ? { ok: true }
                 : { ok: false, reason: result.reason };

package/dist/hostRouter.d.ts

@@ -17,13 +17,15 @@ export type HostRouterOptions = {
     chatRateLimit?: ChatRateLimit;
     chatHistoryLimit?: number;
     chatMaxBodyLength?: number;
-    /** Per-op rate limits for pose/runCommand/join/browse/voice. Omit (default) for no rate limiting; pass {@link DEFAULT_COMMAND_LIMITS} or a custom {@link CommandLimits} to opt in. */
+    /** Per-op rate limits for pose/runCommand/join/browse/voice. Defaults to {@link DEFAULT_COMMAND_LIMITS}. */
     limits?: CommandLimits;
     /** Per-command authorization hook; defaults to allow-all. */
     authorize?: CommandAuthorize;
     /** Declared `runCommand` names and input validators. Omit (default) to pass every command through unchanged; set to reject unknown command names and validate declared ones. */
     validate?: CommandCatalog;
     now?: () => number;
+    /** How long a disconnected membership remains reclaimable. Defaults to 15 seconds. */
+    graceMs?: number;
 };
 export type HostRouterTransport = {
     send: (data: string) => void;
@@ -51,5 +53,7 @@ export type HostRouter = {
 export declare const DEFAULT_POSE_RULES: PoseSyncRules;
 /** Cap on frames queued behind a connection's in-flight message; beyond this a flood gets rejected instead of piling up unbounded promises. */
 export declare const MAX_QUEUED_MESSAGES = 64;
+/** Default reconnect grace period for hosted socket sessions. */
+export declare const DEFAULT_GRACE_MS = 15000;
 export declare function createHostRouter(options: HostRouterOptions): HostRouter;
 export declare function loopbackPipe(router: HostRouter): TransportPipeFactory;

package/dist/hostRouter.js

@@ -2,10 +2,13 @@ import { DEFAULT_POSE_SYNC_RULES, decidePoseSync, spawnPresenceState, } from "@j
 import { createPositionHistory } from "@jgengine/core/multiplayer/lagCompensation";
 import { createChatRateLimiter, DEFAULT_CHAT_BODY_LENGTH, DEFAULT_CHAT_HISTORY_LIMIT, DEFAULT_CHAT_RATE_LIMIT, } from "@jgengine/core/game/chat";
 import { createCommandMiddleware, } from "./commandMiddleware.js";
+import { DEFAULT_COMMAND_LIMITS } from "./commandMiddleware.js";
 import { decodeWsClientMessage, encodeWsMessage, inspectWsDecodeFailure, subscriptionKey, } from "./protocol.js";
 export const DEFAULT_POSE_RULES = DEFAULT_POSE_SYNC_RULES;
 /** Cap on frames queued behind a connection's in-flight message; beyond this a flood gets rejected instead of piling up unbounded promises. */
 export const MAX_QUEUED_MESSAGES = 64;
+/** Default reconnect grace period for hosted socket sessions. */
+export const DEFAULT_GRACE_MS = 15_000;
 function appearanceEqual(a, b) {
     if (a === b)
         return true;
@@ -43,6 +46,7 @@ function dropUserFrom(store, userId, shouldVisit, onChanged) {
 export function createHostRouter(options) {
     const host = options.host;
     const now = options.now ?? Date.now;
+    const graceMs = options.graceMs ?? DEFAULT_GRACE_MS;
     const poseRules = options.poseRules ?? DEFAULT_POSE_RULES;
     const allowAnonymous = options.allowAnonymous === true;
     const singleSession = options.singleSession !== false;
@@ -50,6 +54,29 @@ export function createHostRouter(options) {
         (allowAnonymous ? ({ userId }) => userId : null);
     const connections = new Set();
     const sessionsByUserId = new Map();
+    const resumeTokens = new Map();
+    const pendingLeaves = new Map();
+    const ticketKey = (userId, serverId) => `${userId}|${serverId}`;
+    const ticketFor = (userId, serverId) => {
+        const token = resumeTokens.get(userId) ?? crypto.randomUUID();
+        resumeTokens.set(userId, token);
+        return { userId, serverId, token };
+    };
+    const clearPendingLeave = (userId, serverId) => {
+        const key = ticketKey(userId, serverId);
+        const timer = pendingLeaves.get(key);
+        if (timer === undefined)
+            return;
+        clearTimeout(timer);
+        pendingLeaves.delete(key);
+    };
+    const heldByOtherConnection = (self, userId, serverId) => {
+        for (const other of connections) {
+            if (other !== self && other.userId === userId && other.joinedServers.has(serverId))
+                return true;
+        }
+        return false;
+    };
     const subscribers = new Map();
     const subscribersOf = (key) => {
         const set = subscribers.get(key);
@@ -115,7 +142,7 @@ export function createHostRouter(options) {
         data: presenceRows(serverId),
     }));
     const commandMiddleware = createCommandMiddleware({
-        limits: options.limits,
+        limits: options.limits ?? DEFAULT_COMMAND_LIMITS,
         authorize: options.authorize,
         validate: options.validate,
     });
@@ -221,7 +248,19 @@ export function createHostRouter(options) {
         if (connection.userId === null)
             return;
         if (channel === "server") {
-            const data = await host.getServerView({ userId: connection.userId, serverId });
+            if (host.pullWorld !== undefined) {
+                const sinceRevision = connection.worldRevisions.get(serverId) ?? null;
+                const world = await host.pullWorld({ userId: connection.userId, serverId, sinceRevision, role: connection.roles.get(serverId) });
+                if (world !== null) {
+                    connection.worldRevisions.set(serverId, world.revision);
+                    const data = await host.getServerView({ userId: connection.userId, serverId, role: connection.roles.get(serverId) });
+                    if (data !== null) {
+                        send(connection, { v: 1, t: "update", channel, serverId, data: { ...data, serverState: world } });
+                    }
+                    return;
+                }
+            }
+            const data = await host.getServerView({ userId: connection.userId, serverId, role: connection.roles.get(serverId) });
             send(connection, { v: 1, t: "update", channel, serverId, data });
         }
         else if (channel === "player") {
@@ -336,7 +375,10 @@ export function createHostRouter(options) {
                 connection.transport.close();
                 return;
             }
-            const userId = await authenticate({ userId: message.userId, token: message.token });
+            const resumeToken = resumeTokens.get(message.userId);
+            const userId = resumeToken !== undefined && message.token === resumeToken
+                ? message.userId
+                : await authenticate({ userId: message.userId, token: message.token });
             if (userId === null) {
                 replyError(connection, message.id, "Not authenticated");
                 connection.transport.close();
@@ -352,10 +394,20 @@ export function createHostRouter(options) {
                 sessionsByUserId.set(userId, connection);
             }
             connection.userId = userId;
+            if (resumeToken !== undefined && message.token === resumeToken) {
+                for (const key of [...pendingLeaves.keys()]) {
+                    if (key.startsWith(`${userId}|`)) {
+                        const serverId = key.slice(userId.length + 1);
+                        clearPendingLeave(userId, serverId);
+                    }
+                }
+            }
             reply(connection, message.id, { userId });
             return;
         }
         if (message.t === "pose") {
+            if (connection.roles.get(message.serverId) === "spectator")
+                return;
             await handlePose(connection, message.serverId, message.pose);
             return;
         }
@@ -366,6 +418,9 @@ export function createHostRouter(options) {
         const userId = connection.userId;
         try {
             switch (message.t) {
+                case "ping":
+                    send(connection, { v: 1, t: "pong", id: message.id, at: message.at, serverAt: now() });
+                    break;
                 case "join": {
                     if (!(await gate(connection, message.id, "join", { serverId: message.serverId })))
                         return;
@@ -375,9 +430,16 @@ export function createHostRouter(options) {
                         serverId: message.serverId,
                         attributes: message.attributes,
                         code: message.code,
+                        role: message.role,
                     });
                     connection.joinedServers.add(result.serverId);
-                    reply(connection, message.id, result);
+                    connection.roles.set(result.serverId, message.role ?? "player");
+                    if (message.sessionId !== undefined)
+                        getOrCreate(connection.sessions, result.serverId, () => new Set()).add(message.sessionId);
+                    reply(connection, message.id, {
+                        ...result,
+                        resumeTicket: ticketFor(userId, result.serverId),
+                    });
                     return;
                 }
                 case "joinByCode": {
@@ -388,9 +450,13 @@ export function createHostRouter(options) {
                         gameId: message.gameId,
                         code: message.code,
                     });
-                    if (result !== null)
+                    if (result !== null) {
                         connection.joinedServers.add(result.serverId);
-                    reply(connection, message.id, result);
+                        connection.roles.set(result.serverId, message.role ?? "player");
+                    }
+                    reply(connection, message.id, result === null
+                        ? null
+                        : { ...result, resumeTicket: ticketFor(userId, result.serverId) });
                     return;
                 }
                 case "browse": {
@@ -405,14 +471,31 @@ export function createHostRouter(options) {
                     return;
                 }
                 case "leave": {
-                    await host.leaveServer({ userId, serverId: message.serverId });
+                    const sessions = connection.sessions.get(message.serverId);
+                    // A leave for a session that is not live (a disposed join) must not end the sessions that are.
+                    if (message.sessionId !== undefined && sessions !== undefined && sessions.size > 0) {
+                        if (!sessions.delete(message.sessionId) || sessions.size > 0) {
+                            reply(connection, message.id, null);
+                            return;
+                        }
+                    }
+                    connection.sessions.delete(message.serverId);
                     connection.joinedServers.delete(message.serverId);
-                    dropPresenceForServer(userId, message.serverId);
-                    dropVoiceForServer(userId, message.serverId);
+                    connection.roles.delete(message.serverId);
+                    if (!heldByOtherConnection(connection, userId, message.serverId)) {
+                        await host.leaveServer({ userId, serverId: message.serverId });
+                        clearPendingLeave(userId, message.serverId);
+                        dropPresenceForServer(userId, message.serverId);
+                        dropVoiceForServer(userId, message.serverId);
+                    }
                     reply(connection, message.id, null);
                     return;
                 }
                 case "runCommand": {
+                    if (connection.roles.get(message.serverId) === "spectator") {
+                        replyError(connection, message.id, "Spectators cannot run commands");
+                        return;
+                    }
                     if (!(await gate(connection, message.id, "runCommand", {
                         serverId: message.serverId,
                         command: message.command,
@@ -490,6 +573,8 @@ export function createHostRouter(options) {
                         replyError(connection, message.id, "Not a member of this server");
                         return;
                     }
+                    if (message.channel === "server")
+                        connection.worldRevisions.set(message.serverId, null);
                     addSubscription(connection, subscriptionKey(message.channel, message.serverId, message.action));
                     reply(connection, message.id, null);
                     await pushSubscription(connection, message.channel, message.serverId, message.action);
@@ -512,8 +597,16 @@ export function createHostRouter(options) {
         const userId = connection.userId;
         const servers = [...connection.joinedServers];
         connection.joinedServers.clear();
+        connection.sessions.clear();
         for (const serverId of servers) {
-            void host.leaveServer({ userId, serverId }).catch(() => undefined);
+            const key = ticketKey(userId, serverId);
+            clearPendingLeave(userId, serverId);
+            pendingLeaves.set(key, setTimeout(() => {
+                pendingLeaves.delete(key);
+                if (heldByOtherConnection(connection, userId, serverId))
+                    return;
+                void host.leaveServer({ userId, serverId }).catch(() => undefined);
+            }, graceMs));
         }
     };
     return {
@@ -523,8 +616,11 @@ export function createHostRouter(options) {
                 userId: null,
                 subscriptions: new Set(),
                 joinedServers: new Set(),
+                sessions: new Map(),
                 queue: Promise.resolve(),
                 queuedMessages: 0,
+                worldRevisions: new Map(),
+                roles: new Map(),
             };
             connections.add(connection);
             return {
@@ -579,6 +675,9 @@ export function createHostRouter(options) {
         },
         close: () => {
             unsubscribeHost();
+            for (const timer of pendingLeaves.values())
+                clearTimeout(timer);
+            pendingLeaves.clear();
             connections.clear();
             subscribers.clear();
         },

package/dist/protocol.d.ts

@@ -5,6 +5,8 @@ import type { MatchFilter, SessionListing } from "@jgengine/core/multiplayer/mat
 export declare const WS_PROTOCOL_VERSION = 1;
 /** Max length of a `runCommand` command name, in UTF-16 code units. */
 export declare const MAX_COMMAND_LENGTH = 4096;
+/** Max length of a join/leave `sessionId`, in UTF-16 code units. */
+export declare const MAX_SESSION_ID_LENGTH = 128;
 /** Max length of a `pushFeed` action name, in UTF-16 code units. */
 export declare const MAX_FEED_ACTION_LENGTH = 256;
 /** Max serialized size of a `pushFeed` entry payload, in bytes. */
@@ -34,6 +36,11 @@ export type WsVoiceParticipant = {
     streamId?: string;
 };
 export type WsClientMessage = {
+    v: 1;
+    t: "ping";
+    id: number;
+    at: number;
+} | {
     v: 1;
     t: "hello";
     id: number;
@@ -47,12 +54,16 @@ export type WsClientMessage = {
     serverId?: string;
     attributes?: SessionAttributes;
     code?: string;
+    role?: "player" | "spectator";
+    /** Client session holding this join; see `GameRuntimeTransport.joinServer`. */
+    sessionId?: string;
 } | {
     v: 1;
     t: "joinByCode";
     id: number;
     gameId: string;
     code: string;
+    role?: "player" | "spectator";
 } | {
     v: 1;
     t: "browse";
@@ -65,6 +76,7 @@ export type WsClientMessage = {
     t: "leave";
     id: number;
     serverId: string;
+    sessionId?: string;
 } | {
     v: 1;
     t: "runCommand";
@@ -167,6 +179,12 @@ export type WsUpdateMessage = {
     data: WsVoiceParticipant[];
 };
 export type WsServerMessage = {
+    v: 1;
+    t: "pong";
+    id: number;
+    at: number;
+    serverAt: number;
+} | {
     v: 1;
     t: "reply";
     id: number;

package/dist/protocol.js

@@ -1,6 +1,8 @@
 export const WS_PROTOCOL_VERSION = 1;
 /** Max length of a `runCommand` command name, in UTF-16 code units. */
 export const MAX_COMMAND_LENGTH = 4_096;
+/** Max length of a join/leave `sessionId`, in UTF-16 code units. */
+export const MAX_SESSION_ID_LENGTH = 128;
 /** Max length of a `pushFeed` action name, in UTF-16 code units. */
 export const MAX_FEED_ACTION_LENGTH = 256;
 /** Max serialized size of a `pushFeed` entry payload, in bytes. */
@@ -13,6 +15,9 @@ export const MAX_APPEARANCE_VALUE_LENGTH = 256;
 export function encodeWsMessage(message) {
     return JSON.stringify(message);
 }
+function isOptionalSessionId(value) {
+    return value === undefined || (typeof value === "string" && value.length > 0 && value.length <= MAX_SESSION_ID_LENGTH);
+}
 function isRecord(value) {
     return typeof value === "object" && value !== null;
 }
@@ -113,6 +118,8 @@ export function decodeWsClientMessage(raw) {
     if (message === null)
         return null;
     switch (message.t) {
+        case "ping":
+            return typeof message.id === "number" && typeof message.at === "number" ? message : null;
         case "hello":
             return typeof message.id === "number" &&
                 typeof message.userId === "string" &&
@@ -123,13 +130,16 @@ export function decodeWsClientMessage(raw) {
             return typeof message.id === "number" &&
                 typeof message.gameId === "string" &&
                 (message.serverId === undefined || typeof message.serverId === "string") &&
-                (message.code === undefined || typeof message.code === "string")
+                (message.code === undefined || typeof message.code === "string") &&
+                (message.role === undefined || message.role === "player" || message.role === "spectator") &&
+                isOptionalSessionId(message.sessionId)
                 ? message
                 : null;
         case "joinByCode":
             return typeof message.id === "number" &&
                 typeof message.gameId === "string" &&
-                typeof message.code === "string"
+                typeof message.code === "string" &&
+                (message.role === undefined || message.role === "player" || message.role === "spectator")
                 ? message
                 : null;
         case "browse":
@@ -137,7 +147,7 @@ export function decodeWsClientMessage(raw) {
                 ? message
                 : null;
         case "leave":
-            return typeof message.id === "number" && typeof message.serverId === "string"
+            return typeof message.id === "number" && typeof message.serverId === "string" && isOptionalSessionId(message.sessionId)
                 ? message
                 : null;
         case "runCommand":
@@ -204,6 +214,8 @@ export function decodeWsServerMessage(raw) {
     if (message === null)
         return null;
     switch (message.t) {
+        case "pong":
+            return typeof message.id === "number" && typeof message.at === "number" && typeof message.serverAt === "number" ? message : null;
         case "reply":
             if (typeof message.id !== "number")
                 return null;

package/dist/worldHost.d.ts

@@ -9,7 +9,7 @@ export interface WorldGameHostOptions {
     session(args: {
         gameId: string;
         serverId: string;
-    }): HostedWorldSession | null;
+    }): HostedWorldSession | Promise<HostedWorldSession | null> | null;
     now?: () => number;
 }
 /** A {@link GameHost} whose worlds run on `HostedWorldSession`s; `tick` advances them and re-broadcasts on change. */

package/dist/worldHost.js

@@ -7,6 +7,7 @@ import { INPUT_COMMAND } from "@jgengine/core/runtime/hostedGameRunner";
  */
 export function createWorldGameHost(options) {
     const live = new Map();
+    const roles = new Map();
     const listeners = new Set();
     const now = options.now ?? (() => Date.now());
     function emit(event) {
@@ -17,10 +18,19 @@ export function createWorldGameHost(options) {
         const existing = live.get(serverId);
         if (existing !== undefined)
             return existing;
-        const session = options.session({ gameId, serverId });
-        if (session === null)
+        const resolved = options.session({ gameId, serverId });
+        if (resolved instanceof Promise) {
+            return resolved.then((session) => {
+                if (session === null)
+                    return null;
+                const entry = { gameId, session };
+                live.set(serverId, entry);
+                return entry;
+            });
+        }
+        if (resolved === null)
             return null;
-        const entry = { gameId, session };
+        const entry = { gameId, session: resolved };
         live.set(serverId, entry);
         return entry;
     }
@@ -33,13 +43,21 @@ export function createWorldGameHost(options) {
         }
     }
     return {
-        async joinServer({ userId, gameId, serverId }) {
+        async joinServer({ userId, gameId, serverId, role }) {
             const id = serverId ?? gameId;
-            const entry = ensure(gameId, id);
+            const pending = ensure(gameId, id);
+            const entry = pending instanceof Promise ? await pending : pending;
             if (entry === null)
                 throw new Error(`no hosted world for game "${gameId}"`);
             const isNew = !entry.session.members().includes(userId);
-            entry.session.join(userId, isNew);
+            let serverRoles = roles.get(id);
+            if (serverRoles === undefined) {
+                serverRoles = new Map();
+                roles.set(id, serverRoles);
+            }
+            serverRoles.set(userId, role ?? "player");
+            if (role !== "spectator")
+                entry.session.join(userId, isNew);
             emit({ type: "server", serverId: id });
             emit({ type: "player", serverId: id, userId });
             return { serverId: id, isNew };
@@ -48,7 +66,9 @@ export function createWorldGameHost(options) {
             const entry = live.get(serverId);
             if (entry === undefined)
                 return;
-            entry.session.leave(userId);
+            if (entry.session.members().includes(userId))
+                entry.session.leave(userId);
+            roles.get(serverId)?.delete(userId);
             emit({ type: "server", serverId });
         },
         async runCommand({ userId, serverId, command, input }) {
@@ -70,9 +90,9 @@ export function createWorldGameHost(options) {
             return { ok: true };
         },
         async isMember({ userId, serverId }) {
-            return live.get(serverId)?.session.members().includes(userId) ?? false;
+            return live.get(serverId)?.session.members().includes(userId) || roles.get(serverId)?.has(userId) === true;
         },
-        async getServerView({ userId, serverId }) {
+        async getServerView({ userId, serverId, role }) {
             const entry = live.get(serverId);
             if (entry === undefined)
                 return null;
@@ -81,10 +101,26 @@ export function createWorldGameHost(options) {
                 gameId: entry.gameId,
                 revision: entry.session.revision(),
                 memberUserIds: [...entry.session.members()],
-                serverState: entry.session.snapshotFor({ userId }),
+                serverState: entry.session.snapshotFor({ userId, role: role ?? roles.get(serverId)?.get(userId) ?? "player" }),
                 updatedAt: now(),
             };
         },
+        async pullWorld({ userId, serverId, sinceRevision, role }) {
+            const entry = live.get(serverId);
+            if (entry === undefined || (!entry.session.members().includes(userId) && roles.get(serverId)?.get(userId) !== "spectator"))
+                return null;
+            if (entry.session.projectsViewers()) {
+                return {
+                    kind: "baseline",
+                    revision: entry.session.revision(),
+                    snapshot: entry.session.snapshotFor({ userId, role: role ?? roles.get(serverId)?.get(userId) ?? "player" }),
+                };
+            }
+            const sync = entry.session.pull(sinceRevision);
+            return sync.kind === "baseline"
+                ? sync
+                : { kind: "diff", revision: sync.diff.revision, diff: sync.diff };
+        },
         async getPlayerView() {
             return null;
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/ws",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Browser-safe WebSocket client backend for JGengine: protocol codec, createWsBackend, and HTTP read helpers.",
   "license": "Apache-2.0",
   "type": "module",
@@ -31,7 +31,7 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@jgengine/core": "^0.18.0"
+    "@jgengine/core": "^0.19.0"
   },
   "publishConfig": {
     "access": "public"

package/skills/ce-handoff/SKILL.md

@@ -143,7 +143,7 @@ When sufficient, return a concise orientation: objective, progress, decisions, c
 
 ## JGengine notes
 
-- Multi-session engine work often spans `docs/plans/`, GitHub issues, and stacked PRs — point at those; do not paste full plan bodies.
+- Multi-session engine work spans GitHub issues and PRs — point at those; do not paste full plan bodies.
 - Prefer `bun run agent:bootstrap --check` status, branch names, and PR links as state anchors.
 - Local parallelism uses `.claude/worktrees/`; never invent `C:\tmp\…` Codex-shared trees.
-- Papercuts and durable process changes belong in `PAPERCUTS.md` / skills, not only the handoff.
+- Durable process changes belong in skills, not only the handoff.