@jgengine/ws 0.18.1 → 0.21.0

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;
 }
@@ -126,7 +131,8 @@ export function decodeWsClientMessage(raw) {
                 typeof message.gameId === "string" &&
                 (message.serverId === undefined || typeof message.serverId === "string") &&
                 (message.code === undefined || typeof message.code === "string") &&
-                (message.role === undefined || message.role === "player" || message.role === "spectator")
+                (message.role === undefined || message.role === "player" || message.role === "spectator") &&
+                isOptionalSessionId(message.sessionId)
                 ? message
                 : null;
         case "joinByCode":
@@ -141,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":

package/dist/worldHost.d.ts

@@ -4,18 +4,29 @@ import type { GameHost } from "./host.js";
 export interface WorldGameHostOptions {
     /**
      * Resolve (or lazily build) the authoritative {@link HostedWorldSession} for a server — called once per new
-     * `serverId`. Return `null` for an unknown game. Bind the game's definition + content here.
+     * loaded `serverId`, and again after successful unload. Create a fresh session on reload. Return `null` for an
+     * unknown game. Bind the game's definition + content here.
      */
     session(args: {
         gameId: string;
         serverId: string;
     }): HostedWorldSession | Promise<HostedWorldSession | null> | null;
     now?: () => number;
+    /** Maximum active players per world; reconnecting members and spectators do not consume a new slot. */
+    slotsPerServer?: number;
 }
-/** A {@link GameHost} whose worlds run on `HostedWorldSession`s; `tick` advances them and re-broadcasts on change. */
+/** A {@link GameHost} backed by `HostedWorldSession`s; `tick` advances worlds and `unload` explicitly saves and releases idle world references. */
 export interface WorldGameHost extends GameHost {
     /** Advance every live world by `dtSeconds` and emit a `server` change for each whose revision moved. */
     tick(dtSeconds: number): void;
+    /**
+     * Save and release an unoccupied world's host references. Returns `occupied` for admitted players/spectators or
+     * resident members, and `missing` for an unloaded world. Save failure rejects and retains the world for retry.
+     * Later joins resolve a fresh session; external resources remain caller-owned. Closed hosts reject new unloads.
+     */
+    unload(serverId: string): Promise<"unloaded" | "missing" | "occupied">;
+    /** Permanently close admission/ticks, drain accepted world operations, and save. Repeated calls share completion. */
+    stop(): Promise<void>;
 }
 /**
  * The GameContext-loop counterpart of the reducer `createGameHost`: a structural {@link GameHost} that serves each

package/dist/worldHost.js

@@ -6,36 +6,71 @@ import { INPUT_COMMAND } from "@jgengine/core/runtime/hostedGameRunner";
  * the tick cadence (call {@link WorldGameHost.tick} on an interval); commands and joins broadcast immediately.
  */
 export function createWorldGameHost(options) {
+    if (options.slotsPerServer !== undefined && (!Number.isSafeInteger(options.slotsPerServer) || options.slotsPerServer < 1)) {
+        throw new Error("slotsPerServer must be a positive safe integer");
+    }
     const live = new Map();
+    const loading = new Map();
+    const queues = new Map();
     const roles = new Map();
+    const announcedRevisions = new Map();
     const listeners = new Set();
     const now = options.now ?? (() => Date.now());
+    let stopped = false;
+    let stopping = null;
     function emit(event) {
+        if (event.type === "server") {
+            const entry = live.get(event.serverId);
+            if (entry !== undefined)
+                announcedRevisions.set(event.serverId, entry.session.revision());
+        }
         for (const listener of listeners)
             listener(event);
     }
+    function enqueue(serverId, operation) {
+        if (stopped)
+            return Promise.reject(new Error("World host is closed"));
+        const previous = queues.get(serverId) ?? Promise.resolve();
+        const run = previous.catch(() => { }).then(operation);
+        queues.set(serverId, run);
+        void run.catch(() => { }).finally(() => {
+            if (queues.get(serverId) === run)
+                queues.delete(serverId);
+        });
+        return run;
+    }
     function ensure(gameId, serverId) {
         const existing = live.get(serverId);
         if (existing !== undefined)
-            return existing;
+            return existing.gameId === gameId ? existing : null;
+        const pending = loading.get(serverId);
+        if (pending !== undefined)
+            return pending.then((entry) => entry?.gameId === gameId ? entry : null);
         const resolved = options.session({ gameId, serverId });
         if (resolved instanceof Promise) {
-            return resolved.then((session) => {
+            const pending = resolved.then((session) => {
                 if (session === null)
                     return null;
-                const entry = { gameId, session };
+                const entry = { gameId, session, residentMembers: new Set(session.members()) };
                 live.set(serverId, entry);
                 return entry;
             });
+            loading.set(serverId, pending);
+            void pending.catch(() => { }).finally(() => loading.delete(serverId));
+            return pending;
         }
         if (resolved === null)
             return null;
-        const entry = { gameId, session: resolved };
+        const entry = { gameId, session: resolved, residentMembers: new Set(resolved.members()) };
         live.set(serverId, entry);
         return entry;
     }
     function tickAll(dtSeconds) {
+        if (stopped)
+            return;
         for (const [serverId, entry] of live) {
+            if (queues.has(serverId))
+                continue;
             const before = entry.session.revision();
             entry.session.tick(dtSeconds);
             if (entry.session.revision() !== before)
@@ -45,56 +80,74 @@ export function createWorldGameHost(options) {
     return {
         async joinServer({ userId, gameId, serverId, role }) {
             const id = serverId ?? gameId;
-            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);
-            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 };
+            return enqueue(id, async () => {
+                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 members = entry.session.members();
+                const admittedRoles = roles.get(id);
+                const occupiesSlot = (memberId) => admittedRoles?.get(memberId) === "player"
+                    || (admittedRoles?.get(memberId) === undefined && entry.residentMembers.has(memberId));
+                const usedSlots = members.filter(occupiesSlot).length;
+                if (role !== "spectator" && !(members.includes(userId) && occupiesSlot(userId)) && options.slotsPerServer !== undefined && usedSlots >= options.slotsPerServer) {
+                    throw new Error("Server is full");
+                }
+                const isNew = !entry.session.hasPlayer(userId);
+                let serverRoles = roles.get(id);
+                if (serverRoles === undefined) {
+                    serverRoles = new Map();
+                    roles.set(id, serverRoles);
+                }
+                if (role !== "spectator")
+                    entry.session.join(userId, isNew);
+                await entry.session.save();
+                serverRoles.set(userId, role ?? "player");
+                emit({ type: "server", serverId: id });
+                emit({ type: "player", serverId: id, userId });
+                return { serverId: id, isNew };
+            });
         },
         async leaveServer({ userId, serverId }) {
-            const entry = live.get(serverId);
-            if (entry === undefined)
-                return;
-            if (entry.session.members().includes(userId))
-                entry.session.leave(userId);
-            roles.get(serverId)?.delete(userId);
-            emit({ type: "server", serverId });
+            return enqueue(serverId, async () => {
+                const entry = live.get(serverId);
+                if (entry === undefined)
+                    return;
+                if (entry.session.members().includes(userId))
+                    entry.session.leave(userId);
+                roles.get(serverId)?.delete(userId);
+                await entry.session.save();
+                emit({ type: "server", serverId });
+            });
         },
         async runCommand({ userId, serverId, command, input }) {
-            const entry = live.get(serverId);
-            if (entry === undefined)
-                return { ok: false, reason: "no-server" };
-            if (command === INPUT_COMMAND) {
-                entry.session.input(userId, input);
+            return enqueue(serverId, async () => {
+                const entry = live.get(serverId);
+                if (entry === undefined)
+                    return { ok: false, reason: "no-server" };
+                if (!entry.session.members().includes(userId) || roles.get(serverId)?.get(userId) !== "player")
+                    return { ok: false, reason: "not-a-player" };
+                if (command === INPUT_COMMAND) {
+                    entry.session.input(userId, input);
+                    return { ok: true };
+                }
+                const result = entry.session.command(userId, command, input);
+                await entry.session.save();
+                if (result.status === "rejected")
+                    return { ok: false, reason: result.reason };
+                if (result.status === "unknown-command")
+                    return { ok: false, reason: "unknown-command" };
+                if (entry.session.revision() !== announcedRevisions.get(serverId))
+                    emit({ type: "server", serverId });
                 return { ok: true };
-            }
-            const before = entry.session.revision();
-            const result = entry.session.command(userId, command, input);
-            if (result.status === "rejected")
-                return { ok: false, reason: result.reason };
-            if (result.status === "unknown-command")
-                return { ok: false, reason: "unknown-command" };
-            if (entry.session.revision() !== before)
-                emit({ type: "server", serverId });
-            return { ok: true };
+            });
         },
         async isMember({ userId, serverId }) {
-            return live.get(serverId)?.session.members().includes(userId) || roles.get(serverId)?.has(userId) === true;
+            return !stopped && roles.get(serverId)?.has(userId) === true;
         },
         async getServerView({ userId, serverId, role }) {
             const entry = live.get(serverId);
-            if (entry === undefined)
+            if (stopped || entry === undefined || !roles.get(serverId)?.has(userId))
                 return null;
             return {
                 serverId,
@@ -107,7 +160,7 @@ export function createWorldGameHost(options) {
         },
         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"))
+            if (stopped || entry === undefined || !roles.get(serverId)?.has(userId))
                 return null;
             if (entry.session.projectsViewers()) {
                 return {
@@ -138,16 +191,48 @@ export function createWorldGameHost(options) {
             return [];
         },
         tick: tickAll,
+        unload(serverId) {
+            return enqueue(serverId, async () => {
+                const entry = live.get(serverId);
+                if (entry === undefined)
+                    return "missing";
+                if ((roles.get(serverId)?.size ?? 0) > 0 || entry.session.members().some(userId => entry.residentMembers.has(userId)))
+                    return "occupied";
+                await entry.session.save();
+                live.delete(serverId);
+                roles.delete(serverId);
+                announcedRevisions.delete(serverId);
+                return "unloaded";
+            });
+        },
         async tickOnce() {
             tickAll(0);
             return { ticked: live.size, saved: 0 };
         },
         async flushAll() {
-            return 0;
+            await Promise.allSettled([...queues.values()]);
+            await Promise.all([...live.values()].map((entry) => entry.session.save()));
+            return live.size;
         },
         start() { },
-        async stop() { },
+        stop() {
+            if (stopping !== null)
+                return stopping;
+            stopped = true;
+            stopping = (async () => {
+                await Promise.allSettled([...queues.values()]);
+                try {
+                    await Promise.all([...live.values()].map(entry => entry.session.save()));
+                }
+                finally {
+                    listeners.clear();
+                }
+            })();
+            return stopping;
+        },
         subscribe(listener) {
+            if (stopped)
+                return () => { };
             listeners.add(listener);
             return () => listeners.delete(listener);
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/ws",
-  "version": "0.18.1",
+  "version": "0.21.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.1"
+    "@jgengine/core": "^0.21.0"
   },
   "publishConfig": {
     "access": "public"

package/skills/ce-handoff/SKILL.md

@@ -25,7 +25,7 @@ Create one immutable handoff at the destination the user requested, or use the m
 ### Build the handoff
 
 1. Distill the current objective and the user's latest intent. If a focus was supplied, make it the `resume_focus`.
-2. Inspect only the workspace state needed to explain what exists now. Use JGengine project instructions already in context (`AGENTS.md` / `CLAUDE.md`, `workflow`, domain skills).
+2. Inspect only the workspace state needed to explain what exists now. Use JGengine project instructions already in context (`AGENTS.md`, `workflow`, domain skills).
 3. Point to plans, issues, commits, diffs, documentation, and relevant files instead of reproducing their contents. Prefer repository-relative paths (`docs/plans/…`, `packages/…`, `Games/…`).
 4. Redact secrets, credentials, tokens, and unrelated personal information. Preserve operational paths only when the next agent needs them.
 5. Write or publish with existing tools. If the user named another path, folder, format, or publication destination, honor it. Do not also create a managed-store copy unless asked.
@@ -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.
 - Durable process changes belong in skills, not only the handoff.

package/skills/jgengine/SKILL.md

@@ -5,7 +5,25 @@ description: Route game work to the smallest useful JGengine guidance set.
 
 # JGengine intake and router
 
-Read the JGengine README for package truth, commands, layering, and license — the repo-root [`README.md`](../../../README.md) in the monorepo, or [jgengine.com](https://jgengine.com) from a scaffolded consumer project (where the relative link does not resolve). This skill decides what to load; it is not an engine manual.
+This skill decides what to load; it is not an engine manual. Package map, commands, layering, and license live in the JGengine README (repo-root [`README.md`](../../../README.md) in the monorepo, [jgengine.com](https://jgengine.com) from a created project); open it when you need one of those facts.
+
+A created project installs only `jgengine`, `jgengine-editor`, `jgengine-verify`, `game-design`, and `jgengine-ui`. Run `npx jgengine skills -p --all` before loading any other domain named below. Those projects do not ship `api.md`; read exact signatures from the `.d.ts` files under `node_modules/@jgengine/<pkg>/dist/`.
+
+Created projects pin their scaffolding CLI as a local devDependency, separately from SDK versions. Run `npx jgengine doctor` after SDK upgrades to check CLI compatibility. Skill installation preserves newer or differing unversioned copies; update the project CLI first, and use `skills -p --force` only when replacement is intended. Each packaged skill install records its CLI and SDK versions in `.jgengine-version.json`.
+
+## Framework-first decisions
+
+For every requested interaction, feature, fix or visual change, follow the boundary in
+[AGENTS.md](../../../AGENTS.md): discover the installed
+capability, adopt it, or improve its shared owner before adding reusable game-local code.
+Games keep unique rules, content, assets and presentation. Custom markup is not a reason
+to copy focus handling, input tracking, storage or model lifecycle.
+
+Check installed versions before recreating an upstream fix. A published upgrade may
+replace a workaround; a beta merge does not update consumers. In the games workspace,
+the root catalog owns SDK versions. After adoption, remove superseded local machinery
+and verify the actual game. Outside these repositories, report missing SDK contracts
+upstream rather than treating a local engine implementation as the finished solution.
 
 ## 1. Establish the target
 
@@ -20,10 +38,14 @@ Treat the pitch as a unique composition of needs, not a genre to fill in — nev
 - HUD/menu states and **custom** UI art direction (compose shipped building blocks + HudTheme; no unskinned stock face)
 - one observable completion scenario
 
-For a new in-repo game, scaffold with `bun run new:game "<id-or-title>"` (thin script alias for `jgengine create`, auto-detects the in-repo variant). Outside this monorepo, start with `npx jgengine create`; never copy `Games/*`.
+Pick the dimension first: `create` defaults to a 3D world (terrain, sky, player model, editor scene); a grid, card, tile, or other board game with no 3D scene takes `create --2d` (a `board` world drawn by GameUI over `@jgengine/core/puzzle/cellGrid`). For a new in-repo game, scaffold with `bun run new:game "<id-or-title>"` (thin script alias for `jgengine create`, auto-detects the in-repo variant). Outside this monorepo, start with `npx jgengine create`; never copy `Games/*`.
 
 For an existing game asked to pick up a new engine release ("jgengine published a new version, grab it"), run `npx jgengine upgrade` in the project first: it diffs installed `@jgengine/*` versions against the latest release and prints every Migrate step and Adopt-worthy addition in between (`--json` for structured output). Bump, migrate oldest-first, then work the Adopt lists instead of reconstructing the changelog by hand.
 
+`doctor` and `upgrade` resolve Bun `catalog:` and `catalog:<name>` declarations from the nearest workspace's `workspaces.catalog` or `workspaces.catalogs`, and follow hoisted SDK installs. Missing or malformed catalog entries fail diagnostics. `upgrade` is read-only by default. For catalog-owned versions, run `upgrade --plan --to <published-version>` at the workspace root or in a game, review the whole root catalog plan and migrations, then run `upgrade --apply --to <published-version>`. Apply preserves per-game `catalog:` declarations, unrelated text, CLI/github versions, and a held editor override; it verifies published SDK targets and refuses files changed while planning. Apply changes declarations only: run `bun install` at the root, then `jgengine doctor --workspace --json` once there to check installed SDK identities across declared workspace owners. Rebuild, migrate, and verify game behavior afterward. `--json` includes exact before/after text; an apply prints its plan before writing and reports write status on stderr. A report without installed packages labels its resolved pins as a declared baseline.
+
+When a linked consumer renders differently despite matching root SDK versions, `doctor` checks direct consumers and SDK dependency/peer paths, including private copies with the same version. Review the reported importer and real paths, align the shared catalog and linked-consumer declarations, then reinstall at the root and rerun `doctor --workspace`; a root install may leave private linked-package installs intact. Restart running games after reinstall. Workspace mode checks installed identities only, reports coverage, and refuses unsupported patterns, escaped symlinks or exhausted traversal budgets. The default project audit stays scoped; neither mode covers custom bundler aliases or indirect non-SDK chains.
+
 ## 2. Select domains
 
 Load only rows the target needs. Do not preload every domain.
@@ -46,13 +68,13 @@ World content routes editor-first: any request that adds, moves, restyles, or re
 
 Within each selected domain:
 
-0. Fastest start for a common composition: `npx jgengine recipe <name>` prints a vetted, SDK-typechecked snippet (imports + wired code) for `combat-loop`, `boss-telegraph`, `loot`, `quest`, `coop-presence`, `third-person-camera`; `npx jgengine recipe` lists them. Copy that instead of reconning per-file.
-1. Search `capabilities.md` by intent; it maps needs to imports. Outside the monorepo (or before a domain skill is even loaded), `npx jgengine find <intent>` greps every shipped capability index at once and prints the primitive + import — reach for it the moment you're tempted to hand-roll a HUD window, inventory grid, paperdoll, hotkey listener, minimap, stat bar, or character motion. If you're writing a `z-index`, a `keydown` for a panel, a `<div>` inventory, or a limb bob, a shipped drop-in almost certainly exists (`usePanels`/`PanelHost`, `InventoryGrid`, `CharacterSheet`/`Paperdoll`, `PartMotionRig`, `EntityPreview`); games own the *skin*, not the re-derivation.
-2. Open `api.md` only when exact signatures or export inventory are needed.
+0. Fastest start for a common composition: `npx jgengine recipe <name>` prints a vetted, SDK-typechecked snippet (imports + wired code) (`combat-loop`, `loot`, `world-drops`, `click-target`, `ability-bar`, `hitscan-weapon`, `rolled-gear`, `enter-vehicle` and more); `npx jgengine recipe` lists them. Copy that instead of reconning per-file.
+1. Search capabilities by intent; do not read `capabilities.md` top to bottom. `npx jgengine find <intent>` searches every domain's index and every recipe at once, installed or not, and prints the primitive and its import (or the recipe to open); agents can use `--json --limit 5` for ranked imports and recipes with total, partial-match, and truncation fields. In the monorepo, `rg -i "<intent>" .claude/skills/*/capabilities.md` does the same search. Search the moment you are tempted to hand-roll a HUD window, inventory grid, paperdoll, hotkey listener, minimap, stat bar, or character motion. A `z-index`, a `keydown` for a panel, a `<div>` inventory, or a limb bob almost certainly has a shipped drop-in (`usePanels`/`PanelHost`, `InventoryGrid`, `CharacterSheet`/`Paperdoll`, `PartMotionRig`, `EntityPreview`); games own the *skin*, not the re-derivation.
+2. Open `api.md` (monorepo) or the package `.d.ts` only when exact signatures are needed; grep it, never read it whole.
 3. Open the linked reference only for a deeper recipe or trap.
 4. For how several primitives wire into a running loop, read the domain's `recipes/` — connected, genre-free walkthroughs organized by composition seam; this skill's own [recipes/minimal-game.md](recipes/minimal-game.md) is the default whole-game walkthrough. Prefer a recipe over reading a game's source; the games under `Games/*` are not templates or references, and a hybrid game is just a different composition of the same primitives.
 
-If no capability fits, identify the upstream package seam before writing game-local code. In this repository, implement a reusable primitive with its first adopter; if editor-owned content cannot be expressed, file the editor gap first.
+If no capability fits, identify the upstream package seam before writing game-local code. In this repository, implement a reusable primitive with its first adopter and a reviewed consumer cleanup; coordinate a differently composed second consumer when applicable. Recipes wire SDK APIs, not copied implementations. If editor-owned content cannot be expressed, file the editor gap first; track any fallback and its removal path.
 
 ## 4. Build and finish