@jgengine/ws 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -11,7 +11,27 @@ 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.
 
-## Unreleased
+## 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
 

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;
@@ -23,6 +25,7 @@ export type GameHostOptions = {
     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;
@@ -86,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

@@ -9,6 +9,7 @@ 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;
@@ -389,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();

package/dist/hostRouter.d.ts

@@ -26,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;

package/dist/index.d.ts

@@ -8,3 +8,4 @@ export * from "./protocol.js";
 export * from "./readsHandler.js";
 export * from "./socketIoPipe.js";
 export * from "./voiceChannel.js";
+export * from "./worldHost.js";

package/dist/index.js

@@ -8,3 +8,4 @@ export * from "./protocol.js";
 export * from "./readsHandler.js";
 export * from "./socketIoPipe.js";
 export * from "./voiceChannel.js";
+export * from "./worldHost.js";

package/dist/worldHost.d.ts

@@ -0,0 +1,26 @@
+import type { HostedWorldSession } from "@jgengine/core/runtime/hostedWorldSession";
+import type { GameHost } from "./host.js";
+/** Config for {@link createWorldGameHost}: how to resolve a hosted world's authoritative session per server. */
+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.
+     */
+    session(args: {
+        gameId: string;
+        serverId: string;
+    }): HostedWorldSession | null;
+    now?: () => number;
+}
+/** A {@link GameHost} whose worlds run on `HostedWorldSession`s; `tick` advances them and re-broadcasts on change. */
+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;
+}
+/**
+ * The GameContext-loop counterpart of the reducer `createGameHost`: a structural {@link GameHost} that serves each
+ * world's full `WorldSnapshot` as `serverState`, so the existing ws router, `createWsBackend`, and the shell's
+ * `attachWorldSync` carry host-authoritative GameContext worlds with zero changes to any of them. The harness owns
+ * the tick cadence (call {@link WorldGameHost.tick} on an interval); commands and joins broadcast immediately.
+ */
+export declare function createWorldGameHost(options: WorldGameHostOptions): WorldGameHost;

package/dist/worldHost.js

@@ -0,0 +1,119 @@
+import { INPUT_COMMAND } from "@jgengine/core/runtime/hostedGameRunner";
+/**
+ * The GameContext-loop counterpart of the reducer `createGameHost`: a structural {@link GameHost} that serves each
+ * world's full `WorldSnapshot` as `serverState`, so the existing ws router, `createWsBackend`, and the shell's
+ * `attachWorldSync` carry host-authoritative GameContext worlds with zero changes to any of them. The harness owns
+ * the tick cadence (call {@link WorldGameHost.tick} on an interval); commands and joins broadcast immediately.
+ */
+export function createWorldGameHost(options) {
+    const live = new Map();
+    const listeners = new Set();
+    const now = options.now ?? (() => Date.now());
+    function emit(event) {
+        for (const listener of listeners)
+            listener(event);
+    }
+    function ensure(gameId, serverId) {
+        const existing = live.get(serverId);
+        if (existing !== undefined)
+            return existing;
+        const session = options.session({ gameId, serverId });
+        if (session === null)
+            return null;
+        const entry = { gameId, session };
+        live.set(serverId, entry);
+        return entry;
+    }
+    function tickAll(dtSeconds) {
+        for (const [serverId, entry] of live) {
+            const before = entry.session.revision();
+            entry.session.tick(dtSeconds);
+            if (entry.session.revision() !== before)
+                emit({ type: "server", serverId });
+        }
+    }
+    return {
+        async joinServer({ userId, gameId, serverId }) {
+            const id = serverId ?? gameId;
+            const entry = ensure(gameId, id);
+            if (entry === null)
+                throw new Error(`no hosted world for game "${gameId}"`);
+            const isNew = !entry.session.members().includes(userId);
+            entry.session.join(userId, isNew);
+            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;
+            entry.session.leave(userId);
+            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 { 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) ?? false;
+        },
+        async getServerView({ serverId }) {
+            const entry = live.get(serverId);
+            if (entry === undefined)
+                return null;
+            return {
+                serverId,
+                gameId: entry.gameId,
+                revision: entry.session.revision(),
+                memberUserIds: [...entry.session.members()],
+                serverState: entry.session.runner().snapshot(),
+                updatedAt: now(),
+            };
+        },
+        async getPlayerView() {
+            return null;
+        },
+        async getFeed() {
+            return [];
+        },
+        async pushFeedEntry() { },
+        async browseServers() {
+            return [];
+        },
+        async joinByCode() {
+            return null;
+        },
+        async listOpenServers() {
+            return [];
+        },
+        tick: tickAll,
+        async tickOnce() {
+            tickAll(0);
+            return { ticked: live.size, saved: 0 };
+        },
+        async flushAll() {
+            return 0;
+        },
+        start() { },
+        async stop() { },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+    };
+}

package/llms.txt

@@ -1,7 +1,7 @@
 # @jgengine/ws
 > Browser-safe WebSocket client backend for JGengine: protocol codec, createWsBackend, and HTTP read helpers.
 
-Version: 0.9.0
+Version: 0.10.0
 License: AGPL-3.0-only
 Repository: https://github.com/Noisemaker111/jgengine
 Docs: https://jgengine.com
@@ -20,11 +20,11 @@ Imports use deep paths: `@jgengine/ws/<path>`.
 
 ### @jgengine/ws/host
 
-- GameHost (type): type GameHost = { joinServer: (args: { userId: string; gameId: string; serverId?: string; attributes?: SessionAttributes; }) => Promise<JoinServerResult>; browseServers: (args: { gameId: string; filter?: MatchFilter; limit?: number; }) => Promise<SessionListing[]>; joinByCode: (args: { userId: strin…
-- GameHostOptions (type): type GameHostOptions = { runtimes?: GameRuntime[]; persistence: HostPersistence; tickMs?: number; slotsPerServer?: number; now?: () => number; createServerId?: () => string; allowedFeedActions?: readonly string[]; }
-- HostChangeEvent (type): type HostChangeEvent = | { type: "server"; serverId: string } | { type: "player"; serverId: string; userId: string } | { type: "feed"; serverId: string; action: string }
-- createGameHost (function): function createGameHost(options: GameHostOptions): GameHost
-- memoryPersistence (function): function memoryPersistence(now: () => number = Date.now): HostPersistence
+- GameHost (type): type GameHost = { joinServer: (args: { userId: string; gameId: string; serverId?: string; attributes?: SessionAttributes; }) => Promise<JoinServerResult>; browseServers: (args: { gameId: string; filter?: MatchFilter; limit?: number; }) => Promise<SessionListing[]>; joinByCode: (args: { userId: strin… — A transport-agnostic authoritative game server host that manages sessions, ticking, and persistence.
+- GameHostOptions (type): type GameHostOptions = { runtimes?: GameRuntime[]; persistence: HostPersistence; tickMs?: number; slotsPerServer?: number; now?: () => number; createServerId?: () => string; allowedFeedActions?: readonly string[]; } — Configuration for {@link createGameHost}, including persistence, tick rate, and game runtimes.
+- HostChangeEvent (type): type HostChangeEvent = | { type: "server"; serverId: string } | { type: "player"; serverId: string; userId: string } | { type: "feed"; serverId: string; action: string } — A change notification emitted by a `GameHost` for a server, player, or feed mutation.
+- createGameHost (function): function createGameHost(options: GameHostOptions): GameHost — Creates a `GameHost` that runs game servers over the given persistence and runtimes.
+- memoryPersistence (function): function memoryPersistence(now: () => number = Date.now): HostPersistence — Creates an in-memory `HostPersistence` implementation, useful for tests and ephemeral hosts.
 
 ### @jgengine/ws/hostRouter
 
@@ -34,7 +34,7 @@ Imports use deep paths: `@jgengine/ws/<path>`.
 - HostRouterConnection (type): type HostRouterConnection = { handleRaw: (raw: unknown) => void; close: () => void; }
 - HostRouterOptions (type): type HostRouterOptions = { host: GameHost; authenticate?: HostRouterAuthenticate; allowAnonymous?: boolean; singleSession?: boolean; poseRules?: PoseSyncRules; positionHistoryMs?: number; chatRateLimit?: ChatRateLimit; chatHistoryLimit?: number; chatMaxBodyLength?: number; now?: () => number; }
 - HostRouterTransport (type): type HostRouterTransport = { send: (data: string) => void; close: () => void; }
-- RewoundPosition (type): type RewoundPosition = { userId: string; x: number; y: number; z: number; }
+- RewoundPosition (type): type RewoundPosition = { userId: string; x: number; y: number; z: number; } — A player's interpolated position sampled from history at a past timestamp.
 - createHostRouter (function): function createHostRouter(options: HostRouterOptions): HostRouter
 - loopbackPipe (function): function loopbackPipe(router: HostRouter): TransportPipeFactory
 
@@ -47,9 +47,9 @@ Imports use deep paths: `@jgengine/ws/<path>`.
 ### @jgengine/ws/index
 
 - DEFAULT_POSE_RULES (const): const DEFAULT_POSE_RULES: PoseSyncRules
-- GameHost (type): type GameHost = { joinServer: (args: { userId: string; gameId: string; serverId?: string; attributes?: SessionAttributes; }) => Promise<JoinServerResult>; browseServers: (args: { gameId: string; filter?: MatchFilter; limit?: number; }) => Promise<SessionListing[]>; joinByCode: (args: { userId: strin…
-- GameHostOptions (type): type GameHostOptions = { runtimes?: GameRuntime[]; persistence: HostPersistence; tickMs?: number; slotsPerServer?: number; now?: () => number; createServerId?: () => string; allowedFeedActions?: readonly string[]; }
-- HostChangeEvent (type): type HostChangeEvent = | { type: "server"; serverId: string } | { type: "player"; serverId: string; userId: string } | { type: "feed"; serverId: string; action: string }
+- GameHost (type): type GameHost = { joinServer: (args: { userId: string; gameId: string; serverId?: string; attributes?: SessionAttributes; }) => Promise<JoinServerResult>; browseServers: (args: { gameId: string; filter?: MatchFilter; limit?: number; }) => Promise<SessionListing[]>; joinByCode: (args: { userId: strin… — A transport-agnostic authoritative game server host that manages sessions, ticking, and persistence.
+- GameHostOptions (type): type GameHostOptions = { runtimes?: GameRuntime[]; persistence: HostPersistence; tickMs?: number; slotsPerServer?: number; now?: () => number; createServerId?: () => string; allowedFeedActions?: readonly string[]; } — Configuration for {@link createGameHost}, including persistence, tick rate, and game runtimes.
+- HostChangeEvent (type): type HostChangeEvent = | { type: "server"; serverId: string } | { type: "player"; serverId: string; userId: string } | { type: "feed"; serverId: string; action: string } — A change notification emitted by a `GameHost` for a server, player, or feed mutation.
 - HostRouter (type): type HostRouter = { connect: (transport: HostRouterTransport) => HostRouterConnection; rewind: (args: { serverId: string; atMs: number }) => RewoundPosition[]; close: () => void; }
 - HostRouterAuthenticate (type): type HostRouterAuthenticate = (args: { userId: string; token?: string; }) => Promise<string | null> | string | null
 - HostRouterConnection (type): type HostRouterConnection = { handleRaw: (raw: unknown) => void; close: () => void; }
@@ -68,7 +68,7 @@ Imports use deep paths: `@jgengine/ws/<path>`.
 - ReadsHandler (type): type ReadsHandler = (request: Request) => Promise<Response>
 - ReadsHandlerOptions (type): type ReadsHandlerOptions = { persistence: ReadsPersistence | (() => Promise<ReadsPersistence>); basePath?: string; listOpenServers?: (args: { gameId: string; limit?: number }) => Promise<ServerListing[]>; authenticate?: ReadsAuthenticate; allowPublicProfiles?: boolean; }
 - ReadsPersistence (type): type ReadsPersistence = Pick< HostPersistence, "listServers" | "loadProfile" | "getLeaderboardTop" | "getLeaderboardProfile" >
-- RewoundPosition (type): type RewoundPosition = { userId: string; x: number; y: number; z: number; }
+- RewoundPosition (type): type RewoundPosition = { userId: string; x: number; y: number; z: number; } — A player's interpolated position sampled from history at a past timestamp.
 - SocketIoBackendOptions (type): type SocketIoBackendOptions = Omit<WsBackendOptions, "url" | "pipe" | "webSocketFactory"> & { socket: SocketIoLikeSocket; }
 - SocketIoLikeSocket (type): type SocketIoLikeSocket = { connected: boolean; on: (event: string, listener: (payload: string) => void) => unknown; off: (event: string, listener: (payload: string) => void) => unknown; send: (data: string) => unknown; disconnect: () => unknown; }
 - TransportPipe (type): type TransportPipe = { send: (data: string) => void; close: () => void; }
@@ -81,6 +81,8 @@ Imports use deep paths: `@jgengine/ws/<path>`.
 - VoicePosition (interface): interface VoicePosition
 - VoiceRoute (interface): interface VoiceRoute
 - WS_PROTOCOL_VERSION (const): const WS_PROTOCOL_VERSION: 1
+- WorldGameHost (interface): interface WorldGameHost extends GameHost — A {@link GameHost} whose worlds run on `HostedWorldSession`s; `tick` advances them and re-broadcasts on change.
+- WorldGameHostOptions (interface): interface WorldGameHostOptions — Config for {@link createWorldGameHost}: how to resolve a hosted world's authoritative session per server.
 - WsAppearance (type): type WsAppearance = Record<string, string | number | boolean> — Client-set cosmetic/state tags carried alongside a pose (skin, mount, emote, ...). Primitive values only.
 - WsBackend (type): type WsBackend = GameBackend & { pushFeedEntry: (args: { serverId: string; action: string; entry: unknown }) => Promise<void>; browse: (args: { gameId: string; filter?: MatchFilter; limit?: number }) => Promise<SessionListing[]>; joinByCode: (args: { gameId: string; code: string }) => Promise<JoinSe…
 - WsBackendOptions (type): type WsBackendOptions = { url?: string; pipe?: TransportPipeFactory; userId: string; token?: string; webSocketFactory?: (url: string) => WebSocket; reconnectDelayMs?: number; maxReconnectDelayMs?: number; rpcTimeoutMs?: number; poseTuning?: PoseSyncTuning; now?: () => number; setTimeoutFn?: typeof s…
@@ -103,7 +105,7 @@ Imports use deep paths: `@jgengine/ws/<path>`.
 - announcePeerHost (function): function announcePeerHost(host: PeerHost, signaling: PeerSignaling): () => void
 - broadcastChannelSignaling (function): function broadcastChannelSignaling(room: string): PeerSignaling
 - computeVoiceGain (function): function computeVoiceGain(def: VoiceChannelDef, distance: number | null): number
-- createGameHost (function): function createGameHost(options: GameHostOptions): GameHost
+- createGameHost (function): function createGameHost(options: GameHostOptions): GameHost — Creates a `GameHost` that runs game servers over the given persistence and runtimes.
 - createHostRouter (function): function createHostRouter(options: HostRouterOptions): HostRouter
 - createHttpReads (function): function createHttpReads(options: HttpReadsOptions): HttpReads
 - createPeerGuest (function): function createPeerGuest(options: PeerGuestOptions): PeerGuest
@@ -111,6 +113,7 @@ Imports use deep paths: `@jgengine/ws/<path>`.
 - createReadsHandler (function): function createReadsHandler(options: ReadsHandlerOptions): ReadsHandler
 - createSocketIoBackend (function): function createSocketIoBackend(options: SocketIoBackendOptions): WsBackend
 - createVoiceChannelRouter (function): function createVoiceChannelRouter(channels?: readonly VoiceChannelDef[]): VoiceChannelRouter
+- createWorldGameHost (function): function createWorldGameHost(options: WorldGameHostOptions): WorldGameHost — The GameContext-loop counterpart of the reducer `createGameHost`: a structural {@link GameHost} that serves each world's full `WorldSnapshot` as `serverState`, so the existing ws router, `createWsBackend`, and the shell's `attachWorldSync` carry host-authoritative GameContext worlds with zero changes to any of them. The harness owns the tick cadence (call {@link WorldGameHost.tick} on an interval); commands and joins broadcast immediately.
 - createWsBackend (function): function createWsBackend(options: WsBackendOptions): WsBackend
 - decodePeerSignal (function): function decodePeerSignal(code: string): PeerSignalPayload | null
 - decodeWsClientMessage (function): function decodeWsClientMessage(raw: unknown): WsClientMessage | null
@@ -120,7 +123,7 @@ Imports use deep paths: `@jgengine/ws/<path>`.
 - inspectWsDecodeFailure (function): function inspectWsDecodeFailure(raw: unknown): WsDecodeFailure
 - joinPeerSession (function): function joinPeerSession(guest: PeerGuest, signaling: PeerSignaling): Promise<WsBackend>
 - loopbackPipe (function): function loopbackPipe(router: HostRouter): TransportPipeFactory
-- memoryPersistence (function): function memoryPersistence(now: () => number = Date.now): HostPersistence
+- memoryPersistence (function): function memoryPersistence(now: () => number = Date.now): HostPersistence — Creates an in-memory `HostPersistence` implementation, useful for tests and ephemeral hosts.
 - socketIoPipe (function): function socketIoPipe(socket: SocketIoLikeSocket): TransportPipeFactory
 - subscriptionKey (function): function subscriptionKey(channel: WsChannel, serverId: string, action?: string): string
 - webSocketPipe (function): function webSocketPipe(url: string, webSocketFactory: (url: string) => WebSocket = (target) => new WebSocket(target)): TransportPipeFactory
@@ -198,6 +201,12 @@ Imports use deep paths: `@jgengine/ws/<path>`.
 - computeVoiceGain (function): function computeVoiceGain(def: VoiceChannelDef, distance: number | null): number
 - createVoiceChannelRouter (function): function createVoiceChannelRouter(channels?: readonly VoiceChannelDef[]): VoiceChannelRouter
 
+### @jgengine/ws/worldHost
+
+- WorldGameHost (interface): interface WorldGameHost extends GameHost — A {@link GameHost} whose worlds run on `HostedWorldSession`s; `tick` advances them and re-broadcasts on change.
+- WorldGameHostOptions (interface): interface WorldGameHostOptions — Config for {@link createWorldGameHost}: how to resolve a hosted world's authoritative session per server.
+- createWorldGameHost (function): function createWorldGameHost(options: WorldGameHostOptions): WorldGameHost — The GameContext-loop counterpart of the reducer `createGameHost`: a structural {@link GameHost} that serves each world's full `WorldSnapshot` as `serverState`, so the existing ws router, `createWsBackend`, and the shell's `attachWorldSync` carry host-authoritative GameContext worlds with zero changes to any of them. The harness owns the tick cadence (call {@link WorldGameHost.tick} on an interval); commands and joins broadcast immediately.
+
 ## Guides
 
 # JGengine
@@ -298,7 +307,9 @@ Exact import paths and export names — **do not invent paths**; every row below
 | Loadout | `game/loadout` | `LoadoutDef`, `LoadoutItemEntry`, `Loadouts` |
 | Cosmetic loadout | `game/cosmetics` | `createCosmetics`, `Cosmetics`, `CosmeticLoadoutDef` |
 | Quest | `game/quest` | `QuestDef`, `QuestRewards`, `QuestObjective`, `QuestJournal` |
-| World features | `world/features` | `WorldFeature`, `biomes`, `voxel`, `plots`, `tilemap`, `flat`, `environment`, `terrain`, `rain`, `snow`, `grass`, `ocean`, `building` |
+| World features | `world/features` | `WorldFeature`, `biomes`, `voxel`, `plots`, `tilemap`, `flat`, `environment`, `terrain`, `rain`, `snow`, `grass`, `ocean`, `building`, `road` |
+| Street layout | `world/streets` | `laneCenters`, `sidewalkPaths`, `furnitureSpots`, `parkingSpots`, `sidewalkPoint`, `offsetPath`, `sidewalkWidthOf`, `StreetLane`, `FurnitureSpot`, `ParkingSpot` — where things belong on a `road()`: lanes for traffic, sidewalks for peds, curb anchors for furniture |
+| Road ribbons | `world/roads` | `buildRoadRibbon`, `dashSegments`, `nearestOnPath`, `isOnRoad`, `pathLength`, `RoadRibbon`, `RoadSample`, `RoadPoint` — geometry + queries behind the `road()` environment feature |
 | Voxel field | `world/voxelField` | `createVoxelField`, `VoxelField`, `VoxelCell`, `VoxelHit`, `VoxelBounds`, `VoxelFieldSummary`, `VoxelFace`, `VOXEL_FACES`, `VOXEL_FACE_NORMALS` — a chunked block lattice, distinct from the `voxel()` `WorldFeature` descriptor |
 | Terrain field | `world/terrain` | `TerrainField`, `noiseField`, `resolveTerrainField`, `rollingField`, `fractalNoise`, `valueNoise`, `withNormal`, `arenaField`, `flatField`, `resolveGroundStep`, `snapToGround`, `snapEntityToGround`, `resolveTerrainPalette`, `TERRAIN_MATERIAL_PALETTES` |
 | Seeded RNG | `random/rng` | `seededRng`, `seededStreams` |
@@ -590,7 +601,7 @@ A voxel block is an object. A rack is an object with a slot inventory. A GPU is
 
 ## Game repo layout
 
-Every game is one shape, enforced by `check-game-shape` (part of `check-types`): the top of `src/` holds only the skeleton, and every game-specific module, UI component, and test lives under `src/game/`. Dense files — one `catalog.ts` per domain, never one file per entry.
+Every game is one shape, enforced by `check-game-shape` (part of `check-types`): the top of `src/` holds only the skeleton, and every game-specific module, UI component, and test lives under `src/game/`. In this repo the gate also requires a root `package.json` script `"games:<id>": "bun run --cwd Games/<id> dev"` for every `Games/*` directory — add it with the scaffold, or the very first `check-types` fails before the compiler even runs. Dense files — one `catalog.ts` per domain, never one file per entry.
 
 ```
 src/
@@ -621,6 +632,8 @@ src/
 
 **Smart defaults** — omit any of these and the call still resolves: `multiplayer` → `offline()`; `assets` → an empty asset catalog; `loop` hooks (`onInit`/`onNewPlayer`/`onTick`) → no-ops; `content` → `{}`; `GameUI` → an empty component; `camera` → third-person orbit; `feed` → 20-entry ring buffers per action; a `world` of kind `environment()` auto-renders as the backdrop with no `environment` component supplied — a non-`environment()` world (`flat()`, `voxel()`, …) still needs the game to hand it one.
 
+**Opt-in `ctx.game.*` subsystems (`features`)** — core is genre-agnostic: the always-on base is `commands` / `events` / `store` / `feed` (plus `audio`), and genre subsystems are opt-in via `defineGame({ features: { roster, cards, turn, race, leaderboard, social, chat } })`. Omit one and `ctx.game.<name>` is `undefined` — a puzzle game isn't handed a card pile, race state, or party/chat it never asked for. Declare only what the game uses (`chat` implies `social`). (The content cluster — economy/quest/loot/trade — joins this manifest in a later slim-core phase.)
+
 ```ts
 // game.config.ts — imports only, nothing inline
 import { defineGame } from "@jgengine/shell/defineGame";
@@ -682,7 +695,7 @@ export const physics: PhysicsConfig = { gravity: -32 };
 
 - `PhysicsConfig.gravity`/`jumpVelocity` tune the shell's built-in walk controller's fall/jump feel (defaults ~`-24`/`7.1`) — the only two levers on gravity and jump height; everything else about movement (speed, poses) stays catalog `movement` fields.
 - Input bindings are string arrays (hold semantics) or `{ hold, toggle, repeatMs? }` for the same verb. `repeatMs` turns a held action into an auto-repeat fire (build-mode place-on-drag, rapid-fire without a separate `wasPressed`/interval combo in game code) — the shell refires the command every `repeatMs` while the binding stays down, on top of its normal press-edge fire.
-- **Keybind → command convention.** The shell fires a command for any bound action that isn't reserved: pressing an action runs a command of the **same name** if one is defined, else a `ui.<action>` fallback (so `openBackpack` → `ui.openBackpack`). Just declare the binding and a matching command — no per-game `keydown` listener. Reserved actions the shell consumes natively and never routes to a command: `moveForward/moveBack/moveLeft/moveRight`, `turnLeft/turnRight`, `sprint`, `jump`, `tabTarget`, `clearTarget`, `useAbility`, `interact`, and any `hotbarSlotN`/`slotN`. `tabTarget`/`clearTarget` run `target.cycle`/`target.clear` (native `cycleTarget`/`setTarget` fallback).
+- **Keybind → command convention.** The shell fires a command for any bound action that isn't reserved: pressing an action runs a command of the **same name** if one is defined, else a `ui.<action>` fallback (so `openBackpack` → `ui.openBackpack`). Just declare the binding and a matching command — no per-game `keydown` listener. Reserved actions the shell consumes natively and never routes to a command: `moveForward/moveBack/moveLeft/moveRight`, `turnLeft/turnRight`, `sprint`, `jump`, `tabTarget`, `clearTarget`, `useAbility`, `interact`, and any `hotbarSlotN`/`slotN`. `tabTarget`/`clearTarget` run `target.cycle`/`target.clear` (native `cycleTarget`/`setTarget` fallback). Because `hotbarSlotN` never reaches a command, a game that drives selection from game code binds its own `selectSlot1..N` actions, defines matching commands that write a store key, and reads it back through `hotbarSelection: () => ...` on `defineGame` (see `loot-shooter`).
 - **`interact`** is special: pressing it resolves the active proximity prompt from the `prompts` field of `defineGame({...})` and runs that prompt's `invoke` command. A prompt with `invoke: null` is display-only and does nothing on the key.
 - UI keybind badges derive from `keybinds` via `actionLabel(keybinds, "openBackpack")` — `bindingLabel` maps codes to short labels (`Digit1`→`1`, `KeyB`→`B`, `mouse0`→`LMB`, `Escape`→`Esc`). Never hardcode label strings; they drift the moment a binding changes.
 - `server.mode` is a string your loop/commands interpret — the engine ships no gamemode presets.
@@ -767,7 +780,7 @@ Catalog-first, no per-game audio glue. The `audio` field of `defineGame({...})`
 The shell ships a **rig library**; a game picks and tunes one through `camera` config, never by writing camera positions from `onTick`. Select with `camera.rig` (or the `perspective: "third" | "first"` shorthand) — or by config block alone (#207.8): supplying `camera.<rig>` selects that rig with no redundant `rig` field, checked in the table's order; an explicit `rig` wins when several blocks are present:
 | `rig` | For | Key config (`camera.<rig>`) |
 |-------|-----|------------------------------|
-| `orbit` (default) | Third-person chase | `initialDistance`, `targetHeight`, `min/maxPolarAngle`, drag/zoom |
+| `orbit` (default) | Third-person chase | Top-level fields on `camera` itself — `initialDistance`, `minDistance`/`maxDistance`, `targetHeight`, `min/maxPolarAngle`, drag/zoom. There is **no `camera.orbit` block**; orbit is the one rig tuned at the top level |
 | `first` | FPS mouse-look | `firstPerson: { eyeHeight, sensitivity, maxPitch, reticle, viewmodel }` |
 | `topDown` | ARPG iso / top-down (Diablo IV, Hades II) | `topDown: { height, pitch, yaw, followSmoothing, zoom }` — decoupled follow; `pitch` is camera elevation (PI/2 = straight down, near 0 = grazing and boom-distance blows up past `frustum.far`) |
 | `rts` | Free-pan / edge-scroll (The Sims, Manor Lords) | `rts: { panSpeed, edgeScroll, rotateSpeed, bounds, start, pan }` — `pan: false` turns it into a static backdrop camera: no WASD/arrow pan, no edge-scroll, no Q/E rotate, no wheel zoom, still re-centers on `followEntityId` if one resolves |
@@ -826,7 +839,7 @@ ctx.time            advance, now, calendar, snapshot; pause, play, toggle,
 ctx.subscribe / ctx.version    change signal — UI layers bind via useSyncExternalStore
 ```
 
-`content.itemById(id)` supplies `{ use?, weapon?, trade? }`; `content.entityById(id)` supplies `{ stats?, receive?, onDeath?, movement?, role? }`; `content.objectById(id)` supplies `GameContextObjectEntry` `{ proximityPrompt?, breakable?, slotInventory? }`. Build all three from your catalogs in `content.ts`. A placed object resolves its catalog entry via `ctx.scene.object.catalog(instanceId)`; `ctx.scene.object.at(x, y, z, tolerance?)` finds placed objects near a point (grid interaction, click resolution beyond the pointer service). `ctx.scene.entity.update(id, patch)` writes a shallow patch onto a spawned entity's mutable fields (e.g. `movement.walkSpeed`) without a full respawn — `scene/movementSpeed`'s `applyStatDrivenSpeed(deps, id, { baseSpeed, multiplierStat?, flatBonusStat? })` is the catalog-driven helper that recomputes and writes `movement.walkSpeed` from a stat-modifier pair each time a buff changes.
+`content.itemById(id)` supplies `{ use?, weapon?, trade? }` — exact shapes: `use` is the handler **name string** (not an object), `weapon` is a flat `Record<string, number | Record<string, number>>` built from your catalog stats (`damage`, `projectile.{...}`, `explosion.{...}`), and every lookup returns **`null`** (not `undefined`) for an unknown id; `content.entityById(id)` supplies `{ stats?, receive?, onDeath?, movement?, role? }`; `content.objectById(id)` supplies `GameContextObjectEntry` `{ proximityPrompt?, breakable?, slotInventory? }`. Build all three from your catalogs in `content.ts`. Call-shape gotchas that cost typecheck loops: `ctx.item.use.use(input)` takes **one** argument on the ctx surface (the two-arg `use(state, input)` is the raw factory shape); `ctx.scene.entity.moveToward(id, target, { speed, dt, stopDistance? })` — the third argument is an options object, never a bare `dt`; `nav/pathFollow`'s `createPathFollow(config)` returns the initial `PathFollowState` directly and `advancePathFollow(config, state, dt)` returns the **next state** (with `position: [x,y,z]`, `heading`, `done`) — there is no wrapper object, and `Waypoint` is a `[x, y, z]` tuple. A placed object resolves its catalog entry via `ctx.scene.object.catalog(instanceId)`; `ctx.scene.object.at(x, y, z, tolerance?)` finds placed objects near a point (grid interaction, click resolution beyond the pointer service). `ctx.scene.entity.update(id, patch)` writes a shallow patch onto a spawned entity's mutable fields (e.g. `movement.walkSpeed`) without a full respawn — `scene/movementSpeed`'s `applyStatDrivenSpeed(deps, id, { baseSpeed, multiplierStat?, flatBonusStat? })` is the catalog-driven helper that recomputes and writes `movement.walkSpeed` from a stat-modifier pair each time a buff changes.
 
 ### Two tiers: `ctx` runtime vs pure factories
 

package/package.json

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