@jgengine/ws 0.18.0 → 0.18.1

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,22 @@ 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 subscribers = new Map();
     const subscribersOf = (key) => {
         const set = subscribers.get(key);
@@ -115,7 +135,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 +241,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 +368,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 +387,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 +411,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 +423,14 @@ 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");
+                    reply(connection, message.id, {
+                        ...result,
+                        resumeTicket: ticketFor(userId, result.serverId),
+                    });
                     return;
                 }
                 case "joinByCode": {
@@ -388,9 +441,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": {
@@ -406,13 +463,19 @@ export function createHostRouter(options) {
                 }
                 case "leave": {
                     await host.leaveServer({ userId, serverId: message.serverId });
+                    clearPendingLeave(userId, message.serverId);
                     connection.joinedServers.delete(message.serverId);
+                    connection.roles.delete(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 +553,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);
@@ -513,7 +578,12 @@ export function createHostRouter(options) {
         const servers = [...connection.joinedServers];
         connection.joinedServers.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);
+                void host.leaveServer({ userId, serverId }).catch(() => undefined);
+            }, graceMs));
         }
     };
     return {
@@ -525,6 +595,8 @@ export function createHostRouter(options) {
                 joinedServers: new Set(),
                 queue: Promise.resolve(),
                 queuedMessages: 0,
+                worldRevisions: new Map(),
+                roles: new Map(),
             };
             connections.add(connection);
             return {
@@ -579,6 +651,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

@@ -34,6 +34,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 +52,14 @@ export type WsClientMessage = {
     serverId?: string;
     attributes?: SessionAttributes;
     code?: string;
+    role?: "player" | "spectator";
 } | {
     v: 1;
     t: "joinByCode";
     id: number;
     gameId: string;
     code: string;
+    role?: "player" | "spectator";
 } | {
     v: 1;
     t: "browse";
@@ -167,6 +174,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

@@ -113,6 +113,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 +125,15 @@ 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")
                 ? 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":
@@ -204,6 +208,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.18.1",
   "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.18.1"
   },
   "publishConfig": {
     "access": "public"

package/skills/ce-handoff/SKILL.md

@@ -146,4 +146,4 @@ When sufficient, return a concise orientation: objective, progress, decisions, c
 - Multi-session engine work often spans `docs/plans/`, GitHub issues, and stacked 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.

package/skills/jgengine/SKILL.md

@@ -9,6 +9,8 @@ Read the JGengine README for package truth, commands, layering, and license —
 
 ## 1. Establish the target
 
+For greenfield builds, write `src/art-direction.md` before any code.
+
 Treat the pitch as a unique composition of needs, not a genre to fill in — never reach for a genre kit, preset, archetype, or class template ("default sports car", "default RPG", "default FPS") in the SDK or skills (see [AGENTS.md](../../../AGENTS.md)). Use `game-design` to turn the pitch into a testable player promise, verbs, loops, progression, failure, and completion scenario. Use `level-design` when play depends on authored spaces, routes, encounters, exploration, or spatial pacing. Capture only decisions that change architecture:
 
 - player point of view and controls