@jgengine/ws 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -11,6 +11,42 @@ Agents building on the published SDK can also read this programmatically:
 same data as typed values, so an updater can diff its installed version against
 the latest and surface the migration steps.
 
+## 0.10.0
+
+### Migrate
+
+- **Nothing to change for existing games** — the shared mobile-composition system (viewport allocation, region collision, `--jg-*` viewport vars) is wired automatically by the shell for every game; `HudPanel`s inside a `HudCanvas` register themselves. Legacy `orientation: "landscape" | "portrait"` keeps its advisory dismissible-hint behavior unchanged.
+- **Opt a driving/landscape game into the strict gate**: replace the advisory `orientation` with the contract form — `orientation: { mobile: "landscape-required" }` (rules: `any` · `portrait`/`landscape` advisory · `portrait-required`/`landscape-required` · `unsupported`). In portrait the engine now shows a polished `RotateDeviceScreen`, suppresses input, freezes the sim, and unmounts the HUD/controls until the device is landscape.
+- **Declare HUD intent** where useful: `HudPanel` gains `priority` (`critical`/`secondary`/`tertiary`), `mobileBehavior` (`hidden` unmounts on phones, `transient` softens collision, …), `allowOverlapWith`, and `collisionGroup`. Optional — omitting them keeps prior behavior.
+- **Mobile validation now also fails on overlap**: `bun run shoot <game> --device mobile|mobile-landscape|both` exits non-zero on forbidden inter-element collisions (not just viewport overflow), naming both regions.
+
+### Added
+
+- Shared mobile layout composition — `@jgengine/core/ui/gameLayout` (pure geometry: `resolveLayoutMode`, `intersects`, `overlapArea`, `detectLayoutCollisions`, `computeGameplayRect`, `LayoutRegion`, `GameViewportLayout`) and `@jgengine/core/ui/orientation` (`resolveOrientationRequirement`, `orientationGateActive`, `MobileOrientationRule`). `@jgengine/react` adds `GameViewportProvider` (mounted by the shell), hooks (`useGameViewportLayout`, `useGameLayoutMode`, `useGameOrientation`, `useReservedControlZones`, `useLayoutCollisions`, `useRegisterLayoutRegion`), and a headless `RotateDeviceScreen`. The provider tracks `window.visualViewport`, publishes `--jg-viewport-*` / `--jg-visual-viewport-*` / `--jg-safe-*` CSS vars, resolves the explicit layout mode, and detects forbidden region overlaps (dev `data-jg-layout-collision` + console diagnostic).
+- Mandatory orientation contract — `PlayableGame.orientation` accepts `{ mobile: <rule> }`; `landscape-required`/`portrait-required` render an engine-owned rotate gate that blocks gameplay (input suppressed, simulation frozen, HUD/controls unmounted), self-correcting when the device is turned. Reduced-motion and safe-area respected; `visualViewport`-sized for mobile Safari/PWA.
+- Reserved touch-control zones — the touch dock registers its joystick / action-cluster / utility rectangles (runtime-measured) as `control` regions, so HUD placement and collision validation know exactly where controls sit.
+- HUD placement metadata — `HudPanel` gains `priority`, `mobileBehavior`, `allowOverlapWith`, `collisionGroup`, and registers as a collision-tracked layout region.
+- Mobile-landscape shoot device — `bun run shoot --device mobile-landscape` (844×390) plus collision-gate reads that fail mobile validation on forbidden overlaps.
+- Canyon Chase migrated as the reference landscape-required game — declares `orientation: { mobile: "landscape-required" }`, composes its HUD through coordinated `HudPanel` regions (pursuit distance critical, border secondary, survey map hidden on mobile, radio transient) instead of independent fixed corners.
+
+### Changed
+
+- First-person projectile tracers now originate from the weapon muzzle instead of the camera/eye centerline. Hit detection is unchanged (still crosshair-accurate) — only the drawn tracer's start point moved to the viewmodel muzzle, which tracks full aim yaw and pitch. Non-viewmodel games and enemy tracers are unaffected.
+
+## 0.9.0
+
+### Added
+
+- Mobile HUD fit — design-resolution UI scaling now applies to every game by default: `HudCanvas` measures the live viewport and scales the whole HUD from `PlayableGame.hudFit.designSize` (default 1600×900, clamps `minScale`/`maxScale` 0.4–1) so desktop-authored layouts shrink to fit a phone instead of overflowing it; `hudFit.mobile` overrides tune the phone fit separately. Pure math lives in `@jgengine/core/ui/hudScale` (`hudScaleForViewport`, `resolveHudFit`, `rectOverflow`, `overflowingPanels`); the shell mounts `@jgengine/react`'s `HudViewportProvider` around `GameUI` so games need no wiring.
+- Graphics → UI scale — a player-facing `graphics.uiScale` slider (0.5–1.5, default 1) multiplies the computed HUD scale on every platform; the same resolution system drives desktop preference and mobile shrink.
+- HUD overflow gate — `HudCanvas` measures every `HudPanel` against the viewport at runtime and reports offenders on a `data-hud-overflow` attribute (plus a console warning); `bun run shoot <game> --device mobile|both` now exits non-zero naming the panels that escape the viewport.
+- Automatic visibility & streaming defaults — an engine-level `VisibilitySystem` (exported from `@jgengine/core`) gives every scene renderer-agnostic culling and asset-streaming policy with no per-object wiring: distance culling, preload margins, hysteresis, delayed unloading, multi-camera awareness (including cameras excluded from streaming), and per-object overrides (always-visible, never-unload, disabled culling/streaming, custom render distance and preload margin).
+- Self-hosted asset mirror — `DEFAULT_RELEASE_BASE` now points at this repo's rolling `packs` release instead of the upstream host; a catalog-driven `mirror-assets` workflow (weekly cron + manual dispatch) keeps the mirror in sync with the asset catalog.
+
+### Changed
+
+- Mobile HUD fit is on by default — design-resolution HUD scaling now applies to every game with no config change (previously opt-in via `platforms: ["web", "mobile"]`). A desktop-only game keeps the legacy fixed 0.85 compact zoom by declaring `platforms: ["web"]` (without `"mobile"`).
+
 ## 0.8.0
 
 Transport-agnostic multiplayer (socket.io, WebRTC p2p, LAN/Fly adapters) plus grid/voxel

package/dist/createWsBackend.d.ts

@@ -13,8 +13,12 @@ export type WsBackendOptions = {
     token?: string;
     webSocketFactory?: (url: string) => WebSocket;
     reconnectDelayMs?: number;
+    maxReconnectDelayMs?: number;
+    rpcTimeoutMs?: number;
     poseTuning?: PoseSyncTuning;
     now?: () => number;
+    setTimeoutFn?: typeof setTimeout;
+    clearTimeoutFn?: typeof clearTimeout;
 };
 export type WsPresenceSync = {
     subscribe: (serverId: string, onChange: (rows: WsPresenceRow[]) => void) => () => void;

package/dist/createWsBackend.js

@@ -1,5 +1,5 @@
 import { createPoseSyncGate } from "@jgengine/core/multiplayer/poseSyncGate";
-import { decodeWsServerMessage, encodeWsMessage, subscriptionKey, } from "./protocol.js";
+import { decodeWsServerMessage, encodeWsMessage, inspectWsDecodeFailure, subscriptionKey, } from "./protocol.js";
 import { webSocketPipe } from "./pipe.js";
 const DEFAULT_POSE_TUNING = {
     minIntervalMs: 100,
@@ -8,9 +8,16 @@ const DEFAULT_POSE_TUNING = {
     verticalEpsilon: 0.01,
     rotationEpsilon: 0.01,
 };
+const DEFAULT_RPC_TIMEOUT_MS = 15_000;
+const DEFAULT_RECONNECT_DELAY_MS = 1_000;
+const DEFAULT_MAX_RECONNECT_DELAY_MS = 30_000;
 export function createWsBackend(options) {
     const now = options.now ?? Date.now;
-    const reconnectDelayMs = options.reconnectDelayMs ?? 1_000;
+    const baseReconnectDelayMs = options.reconnectDelayMs ?? DEFAULT_RECONNECT_DELAY_MS;
+    const maxReconnectDelayMs = options.maxReconnectDelayMs ?? DEFAULT_MAX_RECONNECT_DELAY_MS;
+    const rpcTimeoutMs = options.rpcTimeoutMs ?? DEFAULT_RPC_TIMEOUT_MS;
+    const schedule = options.setTimeoutFn ?? setTimeout;
+    const cancel = options.clearTimeoutFn ?? clearTimeout;
     const pipeFactory = options.pipe ??
         (() => {
             const url = options.url;
@@ -22,29 +29,89 @@ export function createWsBackend(options) {
     let open = false;
     let ready = null;
     let closed = false;
+    let wantConnection = false;
     let nextId = 1;
+    let reconnectAttempt = 0;
+    let reconnectTimer = null;
     const pending = new Map();
     const subscriptions = new Map();
+    const clearRequestTimer = (request) => {
+        if (request.timer !== null) {
+            cancel(request.timer);
+            request.timer = null;
+        }
+    };
     const failPending = (reason) => {
         for (const request of pending.values()) {
+            clearRequestTimer(request);
             request.reject(new Error(reason));
         }
         pending.clear();
     };
+    const armRpcTimeout = (request) => {
+        if (rpcTimeoutMs <= 0 || request.kind === "hello")
+            return;
+        request.timer = schedule(() => {
+            const current = pending.get(request.id);
+            if (current !== request)
+                return;
+            pending.delete(request.id);
+            request.timer = null;
+            request.reject(new Error("RPC timeout"));
+        }, rpcTimeoutMs);
+    };
     const rawSend = (message) => {
         if (pipe === null || !open)
             return;
         pipe.send(encodeWsMessage(message));
     };
+    const resendPendingRpcs = () => {
+        const entries = [...pending.entries()];
+        pending.clear();
+        for (const [, request] of entries) {
+            if (request.kind === "hello") {
+                clearRequestTimer(request);
+                request.reject(new Error("Connection reset"));
+                continue;
+            }
+            request.id = nextId++;
+            request.sent = true;
+            pending.set(request.id, request);
+            rawSend(request.build(request.id));
+        }
+    };
+    const resubscribeAll = () => {
+        for (const subscription of subscriptions.values()) {
+            rawSend({
+                v: 1,
+                t: "subscribe",
+                id: nextId++,
+                channel: subscription.channel,
+                serverId: subscription.serverId,
+                action: subscription.action,
+            });
+        }
+    };
     const handleMessage = (raw) => {
         const message = decodeWsServerMessage(raw);
-        if (message === null)
+        if (message === null) {
+            const failure = inspectWsDecodeFailure(raw);
+            if (failure.id !== undefined) {
+                const request = pending.get(failure.id);
+                if (request !== undefined) {
+                    pending.delete(failure.id);
+                    clearRequestTimer(request);
+                    request.reject(new Error(failure.reason));
+                }
+            }
             return;
+        }
         if (message.t === "reply") {
             const request = pending.get(message.id);
             if (request === undefined)
                 return;
             pending.delete(message.id);
+            clearRequestTimer(request);
             if (message.ok) {
                 request.resolve(message.result);
             }
@@ -65,58 +132,129 @@ export function createWsBackend(options) {
         for (const callback of subscription.callbacks)
             callback(data);
     };
+    const clearReconnectTimer = () => {
+        if (reconnectTimer !== null) {
+            cancel(reconnectTimer);
+            reconnectTimer = null;
+        }
+    };
+    const scheduleReconnect = () => {
+        if (closed || !wantConnection || reconnectTimer !== null)
+            return;
+        const delay = Math.min(maxReconnectDelayMs, baseReconnectDelayMs * 2 ** reconnectAttempt);
+        reconnectAttempt += 1;
+        reconnectTimer = schedule(() => {
+            reconnectTimer = null;
+            if (closed || !wantConnection)
+                return;
+            void connect().catch(() => undefined);
+        }, delay);
+    };
     const connect = () => {
         if (closed)
             return Promise.reject(new Error("Backend closed"));
+        wantConnection = true;
         if (ready !== null)
             return ready;
+        clearReconnectTimer();
         ready = new Promise((resolve, reject) => {
+            let settled = false;
+            const settleReject = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                reject(error);
+            };
+            const settleResolve = () => {
+                if (settled)
+                    return;
+                settled = true;
+                resolve();
+            };
             pipe = pipeFactory({
                 onOpen: () => {
                     open = true;
                     const id = nextId++;
+                    const helloBuild = (requestId) => ({
+                        v: 1,
+                        t: "hello",
+                        id: requestId,
+                        userId: options.userId,
+                        token: options.token,
+                    });
                     pending.set(id, {
+                        id,
                         resolve: () => {
-                            for (const subscription of subscriptions.values()) {
-                                rawSend({
-                                    v: 1,
-                                    t: "subscribe",
-                                    id: nextId++,
-                                    channel: subscription.channel,
-                                    serverId: subscription.serverId,
-                                    action: subscription.action,
-                                });
-                            }
-                            resolve();
+                            reconnectAttempt = 0;
+                            resubscribeAll();
+                            resendPendingRpcs();
+                            settleResolve();
                         },
-                        reject,
+                        reject: (error) => {
+                            settleReject(error);
+                        },
+                        build: helloBuild,
+                        timer: null,
+                        kind: "hello",
+                        sent: true,
                     });
-                    rawSend({ v: 1, t: "hello", id, userId: options.userId, token: options.token });
+                    rawSend(helloBuild(id));
                 },
                 onMessage: handleMessage,
                 onClose: () => {
                     open = false;
-                    failPending("Connection closed");
                     pipe = null;
                     ready = null;
-                    reject(new Error("Connection closed"));
-                    if (!closed && subscriptions.size > 0) {
-                        setTimeout(() => {
-                            if (!closed)
-                                void connect().catch(() => undefined);
-                        }, reconnectDelayMs);
+                    for (const [id, request] of [...pending.entries()]) {
+                        if (request.kind === "hello") {
+                            pending.delete(id);
+                            clearRequestTimer(request);
+                            request.reject(new Error("Connection closed"));
+                        }
+                        else {
+                            request.sent = false;
+                        }
+                    }
+                    settleReject(new Error("Connection closed"));
+                    if (!closed && wantConnection) {
+                        scheduleReconnect();
                     }
                 },
             });
         });
         return ready;
     };
-    const request = async (build) => {
-        await connect();
+    const request = (build) => {
+        if (closed)
+            return Promise.reject(new Error("Backend closed"));
+        wantConnection = true;
         const id = nextId++;
         return new Promise((resolve, reject) => {
-            pending.set(id, { resolve, reject });
-            rawSend(build(id));
+            const entry = {
+                id,
+                resolve,
+                reject,
+                build,
+                timer: null,
+                kind: "rpc",
+                sent: false,
+            };
+            pending.set(id, entry);
+            armRpcTimeout(entry);
+            void connect()
+                .then(() => {
+                if (pending.get(entry.id) !== entry || entry.sent || !open)
+                    return;
+                entry.sent = true;
+                rawSend(build(entry.id));
+            })
+                .catch((error) => {
+                if (pending.get(entry.id) !== entry)
+                    return;
+                pending.delete(entry.id);
+                clearRequestTimer(entry);
+                reject(error instanceof Error ? error : new Error(String(error)));
+            });
         });
     };
     const transport = {
@@ -290,6 +428,8 @@ export function createWsBackend(options) {
         },
         close: () => {
             closed = true;
+            wantConnection = false;
+            clearReconnectTimer();
             failPending("Backend closed");
             pipe?.close();
             pipe = null;

package/dist/host.d.ts

@@ -2,6 +2,7 @@ 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";
+/** A change notification emitted by a `GameHost` for a server, player, or feed mutation. */
 export type HostChangeEvent = {
     type: "server";
     serverId: string;
@@ -14,6 +15,7 @@ export type HostChangeEvent = {
     serverId: string;
     action: string;
 };
+/** Configuration for {@link createGameHost}, including persistence, tick rate, and game runtimes. */
 export type GameHostOptions = {
     runtimes?: GameRuntime[];
     persistence: HostPersistence;
@@ -21,7 +23,9 @@ export type GameHostOptions = {
     slotsPerServer?: number;
     now?: () => number;
     createServerId?: () => string;
+    allowedFeedActions?: readonly string[];
 };
+/** A transport-agnostic authoritative game server host that manages sessions, ticking, and persistence. */
 export type GameHost = {
     joinServer: (args: {
         userId: string;
@@ -49,6 +53,10 @@ export type GameHost = {
         command: string;
         input: unknown;
     }) => Promise<TransportRunCommandResult>;
+    isMember: (args: {
+        userId: string;
+        serverId: string;
+    }) => Promise<boolean>;
     getServerView: (args: {
         userId: string;
         serverId: string;
@@ -81,5 +89,7 @@ export type GameHost = {
     stop: () => Promise<void>;
     subscribe: (listener: (event: HostChangeEvent) => void) => () => void;
 };
+/** Creates a `GameHost` that runs game servers over the given persistence and runtimes. */
 export declare function createGameHost(options: GameHostOptions): GameHost;
+/** Creates an in-memory `HostPersistence` implementation, useful for tests and ephemeral hosts. */
 export declare function memoryPersistence(now?: () => number): HostPersistence;

package/dist/host.js

@@ -1,6 +1,7 @@
 import { createGameRuntime } from "@jgengine/core/runtime/gameRuntime";
 import { applyLeaderboardRows, buildHydratePlayers, planServerPersist, profileLeaderboardStats, shouldAutoSave, topLeaderboardRows, toOpenServerListings, toServerListing, trimFeedEntries, } from "@jgengine/core/runtime/hostPersistence";
 import { browseSessions, findByJoinCode } from "@jgengine/core/multiplayer/matchmaking";
+import { createFeedWriteGate, validateFeedWrite, } from "@jgengine/core/multiplayer/feedWriteGate";
 import { clearDirtyFlags, createEmptyServerRow, splitProfilePlayer } from "@jgengine/core/runtime/snapshot";
 const builtinCommands = {
     "engine.ping": {
@@ -8,12 +9,14 @@ const builtinCommands = {
         apply: (snapshot) => snapshot,
     },
 };
+/** Creates a `GameHost` that runs game servers over the given persistence and runtimes. */
 export function createGameHost(options) {
     const now = options.now ?? Date.now;
     const tickMs = options.tickMs ?? 1_000;
     const defaultSlots = options.slotsPerServer ?? 16;
     const createServerId = options.createServerId ?? (() => `srv-${crypto.randomUUID()}`);
     const persistence = options.persistence;
+    const feedWriteGate = createFeedWriteGate(options.allowedFeedActions ?? []);
     const runtimes = new Map();
     for (const runtime of options.runtimes ?? []) {
         runtimes.set(runtime.gameId, runtime);
@@ -55,6 +58,7 @@ export function createGameHost(options) {
             serverRow: record.serverState,
             playersByUserId: buildHydratePlayers(record, profiles),
             chunksByKey,
+            revision: record.revision,
         });
         const existing = live.get(record.serverId);
         if (existing)
@@ -89,6 +93,9 @@ export function createGameHost(options) {
             if (cleared.chunks.length > 0) {
                 await persistence.saveChunks(entry.record.serverId, cleared.chunks);
             }
+            if (cleared.deletedChunks.length > 0) {
+                await persistence.deleteChunks(entry.record.serverId, cleared.deletedChunks);
+            }
             await persistence.saveServer(cleared.server);
         }
         entry.record = cleared.server;
@@ -132,7 +139,7 @@ export function createGameHost(options) {
         }
         return { ticked, saved };
     });
-    const collectListings = async (gameId) => {
+    const collectListings = async (gameId, options = {}) => {
         const byId = new Map();
         for (const record of await persistence.listServers(gameId)) {
             byId.set(record.serverId, record);
@@ -151,7 +158,9 @@ export function createGameHost(options) {
             slotsPerServer: record.slotsPerServer,
             label: record.label,
             mode: record.mode,
-            joinCode: record.joinCode,
+            ...(options.includeJoinCode === true && record.joinCode !== undefined
+                ? { joinCode: record.joinCode }
+                : {}),
             tags: record.tags,
             updatedAt: record.updatedAt,
         }));
@@ -161,6 +170,9 @@ export function createGameHost(options) {
             const timestamp = now();
             const runtime = resolveRuntime(args.gameId);
             let entry = args.serverId === undefined ? null : await getLive(args.serverId);
+            if (args.serverId !== undefined && entry === null) {
+                throw new Error("Server not found");
+            }
             if (entry !== null && entry.record.gameId !== args.gameId) {
                 throw new Error("Server belongs to a different game");
             }
@@ -211,7 +223,7 @@ export function createGameHost(options) {
         }),
         browseServers: async (args) => browseSessions(await collectListings(args.gameId), args.filter ?? {}, { limit: args.limit }),
         joinByCode: async (args) => {
-            const match = findByJoinCode(await collectListings(args.gameId), args.code);
+            const match = findByJoinCode(await collectListings(args.gameId, { includeJoinCode: true }), args.code);
             if (match === null)
                 return null;
             return host.joinServer({ userId: args.userId, gameId: args.gameId, serverId: match.serverId });
@@ -262,6 +274,12 @@ export function createGameHost(options) {
             emit({ type: "player", serverId: args.serverId, userId: args.userId });
             return { ok: true };
         }),
+        isMember: async (args) => {
+            const entry = await getLive(args.serverId);
+            if (entry === null)
+                return false;
+            return entry.record.memberUserIds.includes(args.userId);
+        },
         getServerView: async (args) => {
             const entry = await getLive(args.serverId);
             if (entry === null)
@@ -311,6 +329,10 @@ export function createGameHost(options) {
             return persistence.loadFeed({ serverId: args.serverId, action: args.action });
         },
         pushFeedEntry: (args) => enqueue(async () => {
+            const allowed = validateFeedWrite(feedWriteGate, args.action);
+            if (!allowed.ok) {
+                throw new Error(allowed.reason);
+            }
             const entry = await getLive(args.serverId);
             if (entry === null || !entry.record.memberUserIds.includes(args.userId)) {
                 throw new Error("Not a member of this server");
@@ -368,6 +390,7 @@ export function createGameHost(options) {
     };
     return host;
 }
+/** Creates an in-memory `HostPersistence` implementation, useful for tests and ephemeral hosts. */
 export function memoryPersistence(now = Date.now) {
     const servers = new Map();
     const profiles = new Map();
@@ -403,6 +426,14 @@ export function memoryPersistence(now = Date.now) {
             }
             chunks.set(serverId, byKey);
         },
+        async deleteChunks(serverId, chunkKeys) {
+            const byKey = chunks.get(serverId);
+            if (byKey === undefined)
+                return;
+            for (const chunkKey of chunkKeys) {
+                byKey.delete(chunkKey);
+            }
+        },
         async loadFeed({ serverId, action }) {
             return clone(feeds.get(`${serverId}|${action}`) ?? []);
         },

package/dist/hostRouter.d.ts

@@ -2,12 +2,15 @@ import type { PoseSyncRules } from "@jgengine/core/multiplayer/presenceModel";
 import { type ChatRateLimit } from "@jgengine/core/game/chat";
 import type { GameHost } from "./host.js";
 import type { TransportPipeFactory } from "./pipe.js";
+export type HostRouterAuthenticate = (args: {
+    userId: string;
+    token?: string;
+}) => Promise<string | null> | string | null;
 export type HostRouterOptions = {
     host: GameHost;
-    authenticate?: (args: {
-        userId: string;
-        token?: string;
-    }) => Promise<string | null> | string | null;
+    authenticate?: HostRouterAuthenticate;
+    allowAnonymous?: boolean;
+    singleSession?: boolean;
     poseRules?: PoseSyncRules;
     positionHistoryMs?: number;
     chatRateLimit?: ChatRateLimit;
@@ -23,6 +26,7 @@ export type HostRouterConnection = {
     handleRaw: (raw: unknown) => void;
     close: () => void;
 };
+/** A player's interpolated position sampled from history at a past timestamp. */
 export type RewoundPosition = {
     userId: string;
     x: number;