@jgengine/convex 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/hostedServer.d.ts

@@ -0,0 +1,96 @@
+import type { GameDefinition } from "@jgengine/core/game/defineGame";
+import type { GameContextContent } from "@jgengine/core/runtime/gameContext";
+import { type InputFrame } from "@jgengine/core/runtime/hostedGameRunner";
+import { type HostedWorldSession, type HostedWorldStore } from "@jgengine/core/runtime/hostedWorldSession";
+import type { ModelAssetRef } from "@jgengine/core/scene/assetCatalog";
+import { type JgAuthMode } from "./server.js";
+/** One game the hosted path can serve, bound per `gameId`: its definition plus content lookup. */
+export interface HostedGameConfig {
+    definition: GameDefinition<ModelAssetRef, unknown>;
+    content: GameContextContent;
+}
+/**
+ * Everything one stateless invocation reconstructs a hosted world from: the persisted record via `store`,
+ * plus the member roster and held inputs the snapshot doesn't carry, and the op to apply to the fresh session.
+ */
+export interface HostedWorldInvocation<T> {
+    game: HostedGameConfig;
+    store: HostedWorldStore;
+    members?: readonly string[];
+    inputs?: Readonly<Record<string, InputFrame>>;
+    now?: () => number;
+    op: (session: HostedWorldSession) => T;
+}
+/** What one stateless invocation produced: the op's value, the resulting revision, whether the world changed (and was saved back), and the post-op roster. */
+export interface HostedWorldOutcome<T> {
+    value: T;
+    revision: number;
+    changed: boolean;
+    members: readonly string[];
+}
+/**
+ * The reconstruct → op → save core of the stateless hosted path, Convex-agnostic so it unit-tests against
+ * `memoryWorldStore`: build a fresh {@link createHostedWorldSession} from `store.load()`, resume persisted
+ * members and replay held inputs, run the op, then persist the snapshot at `revision + 1` iff the world changed.
+ */
+export declare function invokeHostedWorld<T>(invocation: HostedWorldInvocation<T>): HostedWorldOutcome<T>;
+/** Default minimum elapsed ms before `tickHostedWorlds` advances a world — override via the factory's `tickMs`. */
+export declare const JG_HOSTED_TICK_MS = 1000;
+/**
+ * The Convex counterpart of ws's `createWorldGameHost`: serves GameContext worlds statelessly by
+ * reconstructing a hosted session from the persisted `jgHostedWorlds` row on every invocation via
+ * {@link invokeHostedWorld}. Destructure + re-export the returned functions from a `convex/` module and
+ * drive `tickHostedWorlds` from a cron. Requires {@link jgengineHostedTables} in the deployment schema.
+ */
+export declare function createHostedGameServerFunctions(options: {
+    games: Record<string, HostedGameConfig>;
+    auth?: JgAuthMode;
+    tickMs?: number;
+}): {
+    getHostedServer: import("convex/server").RegisteredQuery<"public", {
+        externalId?: string | undefined;
+        gameId: string;
+        serverId?: string | undefined;
+    }, Promise<{
+        serverId: string;
+        gameId: string;
+        revision: number;
+        serverState: any;
+        memberUserIds: string[];
+    } | null>>;
+    joinHostedServer: import("convex/server").RegisteredMutation<"public", {
+        externalId?: string | undefined;
+        gameId: string;
+        serverId?: string | undefined;
+    }, Promise<{
+        serverId: string;
+        isNew: boolean;
+    }>>;
+    leaveHostedServer: import("convex/server").RegisteredMutation<"public", {
+        externalId?: string | undefined;
+        gameId: string;
+        serverId?: string | undefined;
+    }, Promise<null>>;
+    runHostedCommand: import("convex/server").RegisteredMutation<"public", {
+        command: string;
+        externalId?: string | undefined;
+        gameId: string;
+        input: any;
+        serverId?: string | undefined;
+    }, Promise<{
+        ok: false;
+        reason: string;
+    } | {
+        ok: true;
+    }>>;
+    submitHostedInput: import("convex/server").RegisteredMutation<"public", {
+        externalId?: string | undefined;
+        frame: any;
+        gameId: string;
+        serverId?: string | undefined;
+    }, Promise<null>>;
+    tickHostedWorlds: import("convex/server").RegisteredMutation<"internal", {}, Promise<{
+        ticked: number;
+        saved: number;
+    }>>;
+};

package/dist/hostedServer.js

@@ -0,0 +1,350 @@
+import { defineSchema, internalMutationGeneric, mutationGeneric, queryGeneric, } from "convex/server";
+import { ConvexError, v } from "convex/values";
+import { INPUT_COMMAND } from "@jgengine/core/runtime/hostedGameRunner";
+import { createHostedWorldSession, } from "@jgengine/core/runtime/hostedWorldSession";
+import { commitIfRevisionMatch } from "./occ.js";
+import { jgengineHostedTables, resolveActor } from "./server.js";
+/**
+ * The reconstruct → op → save core of the stateless hosted path, Convex-agnostic so it unit-tests against
+ * `memoryWorldStore`: build a fresh {@link createHostedWorldSession} from `store.load()`, resume persisted
+ * members and replay held inputs, run the op, then persist the snapshot at `revision + 1` iff the world changed.
+ */
+export function invokeHostedWorld(invocation) {
+    const { game, store, members = [], inputs = {}, now, op } = invocation;
+    const loaded = store.load();
+    const loadedJson = loaded === null ? null : JSON.stringify(loaded.snapshot);
+    const session = createHostedWorldSession({
+        definition: game.definition,
+        content: game.content,
+        store: { load: () => loaded, save: () => { } },
+        ...(now === undefined ? {} : { now }),
+    });
+    for (const userId of members)
+        session.runner().resume(userId);
+    for (const [userId, frame] of Object.entries(inputs))
+        session.input(userId, frame);
+    const value = op(session);
+    const snapshot = session.runner().snapshot();
+    const baseRevision = loaded?.revision ?? 0;
+    if (loadedJson !== null && JSON.stringify(snapshot) === loadedJson) {
+        return { value, revision: baseRevision, changed: false, members: session.members() };
+    }
+    const record = { snapshot, revision: baseRevision + 1 };
+    store.save(record);
+    return { value, revision: record.revision, changed: true, members: session.members() };
+}
+const hostedSchemaForTypes = defineSchema(jgengineHostedTables());
+const query = queryGeneric;
+const mutation = mutationGeneric;
+const internalMutation = internalMutationGeneric;
+/** Default minimum elapsed ms before `tickHostedWorlds` advances a world — override via the factory's `tickMs`. */
+export const JG_HOSTED_TICK_MS = 1_000;
+async function getWorldRow(ctx, gameId, serverId) {
+    return await ctx.db
+        .query("jgHostedWorlds")
+        .withIndex("by_game_and_server", (q) => q.eq("gameId", gameId).eq("serverId", serverId))
+        .unique();
+}
+function heldInputsOf(row) {
+    return (row?.inputs ?? {});
+}
+function worldStoreForRow(row) {
+    const loaded = row === null ? null : { snapshot: row.snapshot, revision: row.revision };
+    let captured = null;
+    return {
+        store: {
+            load: () => loaded,
+            save(record) {
+                captured = record;
+            },
+        },
+        captured: () => captured,
+    };
+}
+async function persistWorldRow(ctx, args) {
+    const nowMs = Date.now();
+    if (args.row === null) {
+        if (args.record === null)
+            return;
+        await ctx.db.insert("jgHostedWorlds", {
+            gameId: args.gameId,
+            serverId: args.serverId,
+            snapshot: args.record.snapshot,
+            revision: args.record.revision,
+            memberUserIds: [...args.memberUserIds],
+            inputs: args.inputs,
+            tickAnchorMs: args.tickAnchorMs ?? nowMs,
+            createdAt: nowMs,
+            updatedAt: nowMs,
+        });
+        return;
+    }
+    await ctx.db.patch(args.row._id, {
+        ...(args.record === null
+            ? {}
+            : { snapshot: args.record.snapshot, revision: args.record.revision }),
+        memberUserIds: [...args.memberUserIds],
+        inputs: args.inputs,
+        ...(args.tickAnchorMs === undefined ? {} : { tickAnchorMs: args.tickAnchorMs }),
+        updatedAt: nowMs,
+    });
+}
+/**
+ * The Convex counterpart of ws's `createWorldGameHost`: serves GameContext worlds statelessly by
+ * reconstructing a hosted session from the persisted `jgHostedWorlds` row on every invocation via
+ * {@link invokeHostedWorld}. Destructure + re-export the returned functions from a `convex/` module and
+ * drive `tickHostedWorlds` from a cron. Requires {@link jgengineHostedTables} in the deployment schema.
+ */
+export function createHostedGameServerFunctions(options) {
+    const mode = options.auth ?? "anonymous";
+    const tickMs = options.tickMs ?? JG_HOSTED_TICK_MS;
+    function resolveGame(gameId) {
+        const game = options.games[gameId];
+        if (game === undefined)
+            throw new ConvexError(`Unknown hosted game "${gameId}"`);
+        return game;
+    }
+    const getHostedServer = query({
+        args: {
+            gameId: v.string(),
+            serverId: v.optional(v.string()),
+            externalId: v.optional(v.string()),
+        },
+        returns: v.union(v.object({
+            serverId: v.string(),
+            gameId: v.string(),
+            revision: v.number(),
+            serverState: v.any(),
+            memberUserIds: v.array(v.string()),
+        }), v.null()),
+        handler: async (ctx, args) => {
+            const actorUserId = await resolveActor(ctx, args.externalId, mode);
+            if (!actorUserId)
+                return null;
+            const row = await getWorldRow(ctx, args.gameId, args.serverId ?? args.gameId);
+            if (!row)
+                return null;
+            if (!row.memberUserIds.includes(actorUserId))
+                return null;
+            return {
+                serverId: row.serverId,
+                gameId: row.gameId,
+                revision: row.revision,
+                serverState: row.snapshot,
+                memberUserIds: row.memberUserIds,
+            };
+        },
+    });
+    const joinHostedServer = mutation({
+        args: {
+            gameId: v.string(),
+            serverId: v.optional(v.string()),
+            externalId: v.optional(v.string()),
+        },
+        returns: v.object({ serverId: v.string(), isNew: v.boolean() }),
+        handler: async (ctx, args) => {
+            const actorUserId = await resolveActor(ctx, args.externalId, mode);
+            if (!actorUserId) {
+                throw new ConvexError("Not authenticated");
+            }
+            const game = resolveGame(args.gameId);
+            const serverId = args.serverId ?? args.gameId;
+            const row = await getWorldRow(ctx, args.gameId, serverId);
+            const isNew = !(row?.memberUserIds ?? []).includes(actorUserId);
+            const { store, captured } = worldStoreForRow(row);
+            const outcome = invokeHostedWorld({
+                game,
+                store,
+                members: row?.memberUserIds ?? [],
+                inputs: heldInputsOf(row),
+                op: (session) => session.join(actorUserId, isNew),
+            });
+            await persistWorldRow(ctx, {
+                gameId: args.gameId,
+                serverId,
+                row,
+                record: captured(),
+                memberUserIds: outcome.members,
+                inputs: heldInputsOf(row),
+            });
+            return { serverId, isNew };
+        },
+    });
+    const leaveHostedServer = mutation({
+        args: {
+            gameId: v.string(),
+            serverId: v.optional(v.string()),
+            externalId: v.optional(v.string()),
+        },
+        returns: v.null(),
+        handler: async (ctx, args) => {
+            const actorUserId = await resolveActor(ctx, args.externalId, mode);
+            if (!actorUserId) {
+                throw new ConvexError("Not authenticated");
+            }
+            const serverId = args.serverId ?? args.gameId;
+            const row = await getWorldRow(ctx, args.gameId, serverId);
+            if (!row)
+                return null;
+            if (!row.memberUserIds.includes(actorUserId))
+                return null;
+            const game = resolveGame(args.gameId);
+            const { store, captured } = worldStoreForRow(row);
+            const outcome = invokeHostedWorld({
+                game,
+                store,
+                members: row.memberUserIds,
+                inputs: heldInputsOf(row),
+                op: (session) => session.leave(actorUserId),
+            });
+            const inputs = heldInputsOf(row);
+            delete inputs[actorUserId];
+            await persistWorldRow(ctx, {
+                gameId: args.gameId,
+                serverId,
+                row,
+                record: captured(),
+                memberUserIds: outcome.members,
+                inputs,
+            });
+            return null;
+        },
+    });
+    const runHostedCommand = mutation({
+        args: {
+            gameId: v.string(),
+            serverId: v.optional(v.string()),
+            command: v.string(),
+            input: v.any(),
+            externalId: v.optional(v.string()),
+        },
+        returns: v.union(v.object({ ok: v.literal(true) }), v.object({ ok: v.literal(false), reason: v.string() })),
+        handler: async (ctx, args) => {
+            const actorUserId = await resolveActor(ctx, args.externalId, mode);
+            if (!actorUserId) {
+                throw new ConvexError("Not authenticated");
+            }
+            const serverId = args.serverId ?? args.gameId;
+            const row = await getWorldRow(ctx, args.gameId, serverId);
+            if (!row) {
+                return { ok: false, reason: "Server not found" };
+            }
+            if (!row.memberUserIds.includes(actorUserId)) {
+                return { ok: false, reason: "Not a member of this server" };
+            }
+            if (args.command === INPUT_COMMAND) {
+                await ctx.db.patch(row._id, {
+                    inputs: { ...heldInputsOf(row), [actorUserId]: args.input },
+                    updatedAt: Date.now(),
+                });
+                return { ok: true };
+            }
+            const game = resolveGame(args.gameId);
+            const loadedRevision = row.revision;
+            const { store, captured } = worldStoreForRow(row);
+            const outcome = invokeHostedWorld({
+                game,
+                store,
+                members: row.memberUserIds,
+                inputs: heldInputsOf(row),
+                op: (session) => session.command(actorUserId, args.command, args.input),
+            });
+            if (outcome.value.status === "rejected") {
+                return { ok: false, reason: outcome.value.reason };
+            }
+            if (outcome.value.status === "unknown-command") {
+                return { ok: false, reason: "unknown-command" };
+            }
+            const latest = await getWorldRow(ctx, args.gameId, serverId);
+            if (!latest) {
+                return { ok: false, reason: "Server not found" };
+            }
+            const commit = commitIfRevisionMatch(loadedRevision, latest.revision);
+            if (!commit.ok) {
+                return commit;
+            }
+            await persistWorldRow(ctx, {
+                gameId: args.gameId,
+                serverId,
+                row: latest,
+                record: captured(),
+                memberUserIds: outcome.members,
+                inputs: heldInputsOf(latest),
+            });
+            return { ok: true };
+        },
+    });
+    const submitHostedInput = mutation({
+        args: {
+            gameId: v.string(),
+            serverId: v.optional(v.string()),
+            frame: v.any(),
+            externalId: v.optional(v.string()),
+        },
+        returns: v.null(),
+        handler: async (ctx, args) => {
+            const actorUserId = await resolveActor(ctx, args.externalId, mode);
+            if (!actorUserId) {
+                throw new ConvexError("Not authenticated");
+            }
+            const row = await getWorldRow(ctx, args.gameId, args.serverId ?? args.gameId);
+            if (!row || !row.memberUserIds.includes(actorUserId)) {
+                throw new ConvexError("Not a member of this server");
+            }
+            await ctx.db.patch(row._id, {
+                inputs: { ...heldInputsOf(row), [actorUserId]: args.frame },
+                updatedAt: Date.now(),
+            });
+            return null;
+        },
+    });
+    const tickHostedWorlds = internalMutation({
+        args: {},
+        handler: async (ctx) => {
+            const nowMs = Date.now();
+            const rows = await ctx.db.query("jgHostedWorlds").collect();
+            let ticked = 0;
+            let saved = 0;
+            for (const row of rows) {
+                const game = options.games[row.gameId];
+                if (game === undefined)
+                    continue;
+                if (row.memberUserIds.length === 0)
+                    continue;
+                const elapsedMs = nowMs - row.tickAnchorMs;
+                if (elapsedMs < tickMs)
+                    continue;
+                const { store, captured } = worldStoreForRow(row);
+                const outcome = invokeHostedWorld({
+                    game,
+                    store,
+                    members: row.memberUserIds,
+                    inputs: heldInputsOf(row),
+                    op: (session) => session.tick(elapsedMs / 1_000),
+                });
+                ticked += 1;
+                const record = captured();
+                if (record !== null)
+                    saved += 1;
+                await persistWorldRow(ctx, {
+                    gameId: row.gameId,
+                    serverId: row.serverId,
+                    row,
+                    record,
+                    memberUserIds: outcome.members,
+                    inputs: heldInputsOf(row),
+                    tickAnchorMs: nowMs,
+                });
+            }
+            return { ticked, saved };
+        },
+    });
+    return {
+        getHostedServer,
+        joinHostedServer,
+        leaveHostedServer,
+        runHostedCommand,
+        submitHostedInput,
+        tickHostedWorlds,
+    };
+}

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export * from "./convexChatTransport.js";
 export * from "./convexPresenceTransport.js";
 export * from "./createConvexBackend.js";
 export * from "./createConvexGameTransport.js";
+export * from "./hostedServer.js";
 export * from "./occ.js";
 export * from "./resolveConvexMultiplayer.js";
 export * from "./server.js";

package/dist/index.js

@@ -2,6 +2,7 @@ export * from "./convexChatTransport.js";
 export * from "./convexPresenceTransport.js";
 export * from "./createConvexBackend.js";
 export * from "./createConvexGameTransport.js";
+export * from "./hostedServer.js";
 export * from "./occ.js";
 export * from "./resolveConvexMultiplayer.js";
 export * from "./server.js";

package/dist/server.d.ts

@@ -1,4 +1,4 @@
-import type { DataModelFromSchemaDefinition, GenericMutationCtx } from "convex/server";
+import type { Auth, DataModelFromSchemaDefinition, GenericMutationCtx } from "convex/server";
 import type { GenericId } from "convex/values";
 import type { ChatMessage } from "@jgengine/core/game/chat";
 import type { ChatSendOutcome } from "@jgengine/core/multiplayer/chatContract";
@@ -163,6 +163,36 @@ export declare function jgengineTables(): {
         by_server_channel: ["serverId", "channelId", "_creationTime"];
     }, {}, {}>;
 };
+/**
+ * Convex table for the hosted GameContext-world path: one row per (gameId, serverId) holding the full
+ * `WorldSnapshot` blob, its revision, the member roster, and each member's held input. A sibling of
+ * {@link jgengineTables} — spread either (or both) into `defineSchema`.
+ */
+export declare function jgengineHostedTables(): {
+    jgHostedWorlds: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        createdAt: number;
+        gameId: string;
+        inputs: any;
+        memberUserIds: string[];
+        revision: number;
+        serverId: string;
+        snapshot: any;
+        tickAnchorMs: number;
+        updatedAt: number;
+    }, {
+        gameId: import("convex/values").VString<string, "required">;
+        serverId: import("convex/values").VString<string, "required">;
+        snapshot: import("convex/values").VAny<any, "required", string>;
+        revision: import("convex/values").VFloat64<number, "required">;
+        memberUserIds: import("convex/values").VArray<string[], import("convex/values").VString<string, "required">, "required">;
+        inputs: import("convex/values").VAny<any, "required", string>;
+        tickAnchorMs: import("convex/values").VFloat64<number, "required">;
+        createdAt: import("convex/values").VFloat64<number, "required">;
+        updatedAt: import("convex/values").VFloat64<number, "required">;
+    }, "required", "createdAt" | "gameId" | "inputs" | "memberUserIds" | "revision" | "serverId" | "snapshot" | "tickAnchorMs" | "updatedAt" | `inputs.${string}` | `snapshot.${string}`>, {
+        by_game_and_server: ["gameId", "serverId", "_creationTime"];
+    }, {}, {}>;
+};
 declare const schemaForTypes: import("convex/server").SchemaDefinition<{
     jgGameServers: import("convex/server").TableDefinition<import("convex/values").VObject<{
         createdAt: number;
@@ -325,6 +355,10 @@ type JGDataModel = DataModelFromSchemaDefinition<typeof schemaForTypes>;
 type JGMutationCtx = GenericMutationCtx<JGDataModel>;
 export type JgAuthMode = "anonymous" | "required";
 export declare const DEFAULT_CONVEX_POSE_RULES: PoseSyncRules;
+/** Resolve the acting user id under a {@link JgAuthMode}: the Convex identity when signed in (rejecting a mismatched claim), the claimed external id under `"anonymous"`, else `null`. */
+export declare function resolveActor(ctx: {
+    auth: Auth;
+}, claimedExternalId: string | undefined, mode: JgAuthMode): Promise<string | null>;
 export declare function applyLeaderboardIncrements(ctx: JGMutationCtx, gameId: string, entries: LeaderboardIncrement[]): Promise<void>;
 export declare const JG_RUNTIME_TICK_MS = 1000;
 export declare function createGameServerFunctions(options?: {

package/dist/server.js

@@ -87,6 +87,26 @@ export function jgengineTables() {
         }).index("by_server_channel", ["serverId", "channelId"]),
     };
 }
+/**
+ * Convex table for the hosted GameContext-world path: one row per (gameId, serverId) holding the full
+ * `WorldSnapshot` blob, its revision, the member roster, and each member's held input. A sibling of
+ * {@link jgengineTables} — spread either (or both) into `defineSchema`.
+ */
+export function jgengineHostedTables() {
+    return {
+        jgHostedWorlds: defineTable({
+            gameId: v.string(),
+            serverId: v.string(),
+            snapshot: v.any(),
+            revision: v.number(),
+            memberUserIds: v.array(v.string()),
+            inputs: v.any(),
+            tickAnchorMs: v.number(),
+            createdAt: v.number(),
+            updatedAt: v.number(),
+        }).index("by_game_and_server", ["gameId", "serverId"]),
+    };
+}
 const schemaForTypes = defineSchema(jgengineTables());
 const query = queryGeneric;
 const mutation = mutationGeneric;
@@ -98,7 +118,8 @@ export const DEFAULT_CONVEX_POSE_RULES = {
     maxElapsedSec: 0.5,
     keepAliveRefreshMs: 10_000,
 };
-async function resolveActor(ctx, claimedExternalId, mode) {
+/** Resolve the acting user id under a {@link JgAuthMode}: the Convex identity when signed in (rejecting a mismatched claim), the claimed external id under `"anonymous"`, else `null`. */
+export async function resolveActor(ctx, claimedExternalId, mode) {
     const identity = await ctx.auth.getUserIdentity();
     if (identity !== null) {
         if (claimedExternalId !== undefined &&

package/llms.txt

@@ -1,7 +1,7 @@
 # @jgengine/convex
 > Convex adapters for JGengine: game transport, presence transport, and backend wiring over @jgengine/core.
 
-Version: 0.9.0
+Version: 0.10.0
 License: AGPL-3.0-only
 Repository: https://github.com/Noisemaker111/jgengine
 Docs: https://jgengine.com
@@ -39,6 +39,15 @@ Imports use deep paths: `@jgengine/convex/<path>`.
 - defaultConvexGameApi (function): function defaultConvexGameApi(): ConvexGameApi
 - watchConvexQuery (function): function watchConvexQuery<TArgs extends DefaultFunctionArgs, TResult, TView>(client: ConvexReactClient, query: FunctionReference<"query", "public", TArgs, TResult>, args: TArgs, toView: (result: TResult) => TView, onChange: (view: TView) => void): () => void
 
+### @jgengine/convex/hostedServer
+
+- HostedGameConfig (interface): interface HostedGameConfig — One game the hosted path can serve, bound per `gameId`: its definition plus content lookup.
+- HostedWorldInvocation (interface): interface HostedWorldInvocation<T> — Everything one stateless invocation reconstructs a hosted world from: the persisted record via `store`, plus the member roster and held inputs the snapshot doesn't carry, and the op to apply to the fresh session.
+- HostedWorldOutcome (interface): interface HostedWorldOutcome<T> — What one stateless invocation produced: the op's value, the resulting revision, whether the world changed (and was saved back), and the post-op roster.
+- JG_HOSTED_TICK_MS (const): const JG_HOSTED_TICK_MS: 1000 — Default minimum elapsed ms before `tickHostedWorlds` advances a world — override via the factory's `tickMs`.
+- createHostedGameServerFunctions (function): function createHostedGameServerFunctions(options: { games: Record<string, HostedGameConfig>; auth?: JgAuthMode; tickMs?: number; }): { getHostedServer: RegisteredQuery<"public", { serverId?: string | undefined; externalId?: string | undefined; gameId: string; }, Promise<{ serverId: string; gameId: s… — The Convex counterpart of ws's `createWorldGameHost`: serves GameContext worlds statelessly by reconstructing a hosted session from the persisted `jgHostedWorlds` row on every invocation via {@link invokeHostedWorld}. Destructure + re-export the returned functions from a `convex/` module and drive `tickHostedWorlds` from a cron. Requires {@link jgengineHostedTables} in the deployment schema.
+- invokeHostedWorld (function): function invokeHostedWorld<T>(invocation: HostedWorldInvocation<T>): HostedWorldOutcome<T> — The reconstruct → op → save core of the stateless hosted path, Convex-agnostic so it unit-tests against `memoryWorldStore`: build a fresh {@link createHostedWorldSession} from `store.load()`, resume persisted members and replay held inputs, run the op, then persist the snapshot at `revision + 1` iff the world changed.
+
 ### @jgengine/convex/index
 
 - ConvexBackend (type): type ConvexBackend<TPresenceRow = unknown, TPresenceLocation = unknown, TGameId extends string = string> = LiveGameBackend<TPresenceRow, TPresenceLocation, TGameId> & { leaderboard: ConvexLeaderboardReads; }
@@ -49,6 +58,10 @@ Imports use deep paths: `@jgengine/convex/<path>`.
 - ConvexLeaderboardReads (type): type ConvexLeaderboardReads = ReturnType<typeof createConvexLeaderboardReads>
 - ConvexPresenceFunctions (interface): interface ConvexPresenceFunctions
 - DEFAULT_CONVEX_POSE_RULES (const): const DEFAULT_CONVEX_POSE_RULES: PoseSyncRules
+- HostedGameConfig (interface): interface HostedGameConfig — One game the hosted path can serve, bound per `gameId`: its definition plus content lookup.
+- HostedWorldInvocation (interface): interface HostedWorldInvocation<T> — Everything one stateless invocation reconstructs a hosted world from: the persisted record via `store`, plus the member roster and held inputs the snapshot doesn't carry, and the op to apply to the fresh session.
+- HostedWorldOutcome (interface): interface HostedWorldOutcome<T> — What one stateless invocation produced: the op's value, the resulting revision, whether the world changed (and was saved back), and the post-op roster.
+- JG_HOSTED_TICK_MS (const): const JG_HOSTED_TICK_MS: 1000 — Default minimum elapsed ms before `tickHostedWorlds` advances a world — override via the factory's `tickMs`.
 - JG_RUNTIME_TICK_MS (const): const JG_RUNTIME_TICK_MS: 1000
 - JgAuthMode (type): type JgAuthMode = "anonymous" | "required"
 - JgCronSpec (type): type JgCronSpec = { name: string; intervalSeconds: number; functionKey: "tickActiveServers" | "flushDirtyServers"; }
@@ -66,13 +79,17 @@ Imports use deep paths: `@jgengine/convex/<path>`.
 - createConvexLeaderboardReads (function): function createConvexLeaderboardReads(api: ConvexGameApi, config: ConvexGameTransportConfig): { getTop(args: { stat: string; scope: LeaderboardScope; serverId?: string | undefined; limit?: number | undefined; }): { query: FunctionReference<"query", "public", { gameId: string; stat: string; scope: Le…
 - createConvexPresenceSync (function): function createConvexPresenceSync(client: ConvexReactClient, api: ConvexGameApi, config: ConvexGameTransportConfig, tuning?: PoseSyncTuning): PresenceSync
 - createConvexPresenceTransport (function): function createConvexPresenceTransport<TRawRow extends RawPresenceActor, TRow, TLocation, TGameId extends string = string>(functions: ConvexPresenceFunctions, mapRow: (row: TRawRow) => TRow): PresenceTransport<TRow, TLocation, TGameId> — Wires a game's Convex presence functions into the engine's PresenceTransport contract: one snapshot subscription (my location + online players), one residents subscription (dormant candidates, decoupled from pose writes), and one tick mutation for pose upload + keep-alive. Dormant rows are derived client-side by subtracting the snapshot's online actors, so pose ticks never re-execute the residents query. mapRow converts backend rows into the game's row type (e.g. branding positions into its coordinate space).
-- createGameServerFunctions (function): function createGameServerFunctions(options?: { runtimes?: GameRuntime[]; auth?: JgAuthMode; slotsPerServer?: number; allowedFeedActions?: readonly string[]; }): { joinServer: RegisteredMutation<"public", { mode?: string | undefined; modeConfig?: any; visibility?: "public" | "private" | undefined; jo…
+- createGameServerFunctions (function): function createGameServerFunctions(options?: { runtimes?: GameRuntime[]; auth?: JgAuthMode; slotsPerServer?: number; allowedFeedActions?: readonly string[]; }): { joinServer: RegisteredMutation<"public", { serverId?: Id<"jgGameServers"> | undefined; externalId?: string | undefined; mode?: string | u…
+- createHostedGameServerFunctions (function): function createHostedGameServerFunctions(options: { games: Record<string, HostedGameConfig>; auth?: JgAuthMode; tickMs?: number; }): { getHostedServer: RegisteredQuery<"public", { serverId?: string | undefined; externalId?: string | undefined; gameId: string; }, Promise<{ serverId: string; gameId: s… — The Convex counterpart of ws's `createWorldGameHost`: serves GameContext worlds statelessly by reconstructing a hosted session from the persisted `jgHostedWorlds` row on every invocation via {@link invokeHostedWorld}. Destructure + re-export the returned functions from a `convex/` module and drive `tickHostedWorlds` from a cron. Requires {@link jgengineHostedTables} in the deployment schema.
 - createLeaderboardFunctions (function): function createLeaderboardFunctions(options?: { auth?: JgAuthMode }): { getTop: RegisteredQuery<"public", { serverId?: Id<"jgGameServers"> | undefined; externalId?: string | undefined; limit?: number | undefined; gameId: string; scope: "global" | "server" | "profile"; stat: string; }, Promise<{ user…
 - createPresenceFunctions (function): function createPresenceFunctions(options?: { auth?: JgAuthMode; freshWindowMs?: number; poseRules?: PoseSyncRules; }): { list: RegisteredQuery<"public", { externalId?: string | undefined; serverId: string; }, Promise<{ userId: string; position: { x: number; y: number; z: number; }; rotationY: number…
 - defaultConvexGameApi (function): function defaultConvexGameApi(): ConvexGameApi
+- invokeHostedWorld (function): function invokeHostedWorld<T>(invocation: HostedWorldInvocation<T>): HostedWorldOutcome<T> — The reconstruct → op → save core of the stateless hosted path, Convex-agnostic so it unit-tests against `memoryWorldStore`: build a fresh {@link createHostedWorldSession} from `store.load()`, resume persisted members and replay held inputs, run the op, then persist the snapshot at `revision + 1` iff the world changed.
 - jgengineCronSpecs (function): function jgengineCronSpecs(): readonly JgCronSpec[]
-- jgengineTables (function): function jgengineTables(): { jgGameServers: TableDefinition<VObject<{ mode?: string | undefined; modeConfig?: any; visibility?: "public" | "private" | undefined; joinCode?: string | undefined; lastSavedAt?: number | undefined; dirtyAt?: number | undefined; save: "none" | { auto: string; scope: "play…
+- jgengineHostedTables (function): function jgengineHostedTables(): { jgHostedWorlds: TableDefinition<VObject<{ gameId: string; serverId: string; snapshot: any; revision: number; memberUserIds: string[]; inputs: any; tickAnchorMs: number; createdAt: number; updatedAt: number; }, { gameId: VString<string, "required">; serverId: VStrin… — Convex table for the hosted GameContext-world path: one row per (gameId, serverId) holding the full `WorldSnapshot` blob, its revision, the member roster, and each member's held input. A sibling of {@link jgengineTables} — spread either (or both) into `defineSchema`.
+- jgengineTables (function): function jgengineTables(): { jgGameServers: TableDefinition<VObject<{ mode?: string | undefined; modeConfig?: any; visibility?: "public" | "private" | undefined; joinCode?: string | undefined; lastSavedAt?: number | undefined; dirtyAt?: number | undefined; gameId: string; revision: number; memberUse…
 - randomConvexPlayerId (function): function randomConvexPlayerId(): string
+- resolveActor (function): function resolveActor(ctx: { auth: Auth }, claimedExternalId: string | undefined, mode: JgAuthMode): Promise<string | null> — Resolve the acting user id under a {@link JgAuthMode}: the Convex identity when signed in (rejecting a mismatched claim), the claimed external id under `"anonymous"`, else `null`.
 - resolveConvexMultiplayer (function): function resolveConvexMultiplayer(args: { game: GameDefinition; gameId: string; url?: string; client?: ConvexReactClient; api?: ConvexGameApi; userId?: string; force?: boolean; feedActions?: string[]; poseTuning?: PoseSyncTuning; }): MultiplayerSession | null
 - watchConvexQuery (function): function watchConvexQuery<TArgs extends DefaultFunctionArgs, TResult, TView>(client: ConvexReactClient, query: FunctionReference<"query", "public", TArgs, TResult>, args: TArgs, toView: (result: TResult) => TView, onChange: (view: TView) => void): () => void
 
@@ -95,11 +112,13 @@ Imports use deep paths: `@jgengine/convex/<path>`.
 - JgCronSpec (type): type JgCronSpec = { name: string; intervalSeconds: number; functionKey: "tickActiveServers" | "flushDirtyServers"; }
 - applyLeaderboardIncrements (function): function applyLeaderboardIncrements(ctx: JGMutationCtx, gameId: string, entries: LeaderboardIncrement[]): Promise<void>
 - createChatFunctions (function): function createChatFunctions(options?: { auth?: JgAuthMode; historyLimit?: number; maxBodyLength?: number; minIntervalMs?: number; }): { messages: RegisteredQuery<"public", { externalId?: string | undefined; serverId: string; channelId: string; }, Promise<ChatMessage[]>>; sendMessage: RegisteredMuta…
-- createGameServerFunctions (function): function createGameServerFunctions(options?: { runtimes?: GameRuntime[]; auth?: JgAuthMode; slotsPerServer?: number; allowedFeedActions?: readonly string[]; }): { joinServer: RegisteredMutation<"public", { mode?: string | undefined; modeConfig?: any; visibility?: "public" | "private" | undefined; jo…
+- createGameServerFunctions (function): function createGameServerFunctions(options?: { runtimes?: GameRuntime[]; auth?: JgAuthMode; slotsPerServer?: number; allowedFeedActions?: readonly string[]; }): { joinServer: RegisteredMutation<"public", { serverId?: Id<"jgGameServers"> | undefined; externalId?: string | undefined; mode?: string | u…
 - createLeaderboardFunctions (function): function createLeaderboardFunctions(options?: { auth?: JgAuthMode }): { getTop: RegisteredQuery<"public", { serverId?: Id<"jgGameServers"> | undefined; externalId?: string | undefined; limit?: number | undefined; gameId: string; scope: "global" | "server" | "profile"; stat: string; }, Promise<{ user…
 - createPresenceFunctions (function): function createPresenceFunctions(options?: { auth?: JgAuthMode; freshWindowMs?: number; poseRules?: PoseSyncRules; }): { list: RegisteredQuery<"public", { externalId?: string | undefined; serverId: string; }, Promise<{ userId: string; position: { x: number; y: number; z: number; }; rotationY: number…
 - jgengineCronSpecs (function): function jgengineCronSpecs(): readonly JgCronSpec[]
-- jgengineTables (function): function jgengineTables(): { jgGameServers: TableDefinition<VObject<{ mode?: string | undefined; modeConfig?: any; visibility?: "public" | "private" | undefined; joinCode?: string | undefined; lastSavedAt?: number | undefined; dirtyAt?: number | undefined; save: "none" | { auto: string; scope: "play…
+- jgengineHostedTables (function): function jgengineHostedTables(): { jgHostedWorlds: TableDefinition<VObject<{ gameId: string; serverId: string; snapshot: any; revision: number; memberUserIds: string[]; inputs: any; tickAnchorMs: number; createdAt: number; updatedAt: number; }, { gameId: VString<string, "required">; serverId: VStrin… — Convex table for the hosted GameContext-world path: one row per (gameId, serverId) holding the full `WorldSnapshot` blob, its revision, the member roster, and each member's held input. A sibling of {@link jgengineTables} — spread either (or both) into `defineSchema`.
+- jgengineTables (function): function jgengineTables(): { jgGameServers: TableDefinition<VObject<{ mode?: string | undefined; modeConfig?: any; visibility?: "public" | "private" | undefined; joinCode?: string | undefined; lastSavedAt?: number | undefined; dirtyAt?: number | undefined; gameId: string; revision: number; memberUse…
+- resolveActor (function): function resolveActor(ctx: { auth: Auth }, claimedExternalId: string | undefined, mode: JgAuthMode): Promise<string | null> — Resolve the acting user id under a {@link JgAuthMode}: the Convex identity when signed in (rejecting a mismatched claim), the claimed external id under `"anonymous"`, else `null`.
 
 ## Guides
 
@@ -201,7 +220,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` |
@@ -493,7 +514,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/
@@ -524,6 +545,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";
@@ -585,7 +608,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.
@@ -670,7 +693,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 |
@@ -729,7 +752,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/convex",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Convex adapters for JGengine: game transport, presence transport, and backend wiring over @jgengine/core.",
   "license": "AGPL-3.0-only",
   "type": "module",
@@ -30,7 +30,7 @@
     "check-types": "tsgo --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@jgengine/core": "^0.9.0"
+    "@jgengine/core": "^0.10.0"
   },
   "peerDependencies": {
     "convex": "^1.31.2",