@jgengine/convex 0.18.1 → 0.21.0

package/dist/createConvexGameTransport.d.ts

@@ -20,10 +20,12 @@ export type ConvexGameApi = {
             visibility?: "public" | "private";
             joinCode?: string;
             externalId?: string;
+            sessionId?: string;
         }, JoinServerOutcome>;
         leaveServer: FunctionReference<"mutation", "public", {
             serverId: string;
             externalId?: string;
+            sessionId?: string;
         }, null>;
         runCommand: FunctionReference<"mutation", "public", {
             serverId: string;

package/dist/createConvexGameTransport.js

@@ -5,10 +5,12 @@ export function defaultConvexGameApi() {
     return anyApi;
 }
 export function createConvexGameTransport(client, api, config) {
-    const joinedServers = new Set();
+    const joinedServers = new Map();
     const onPageHide = () => {
-        for (const serverId of joinedServers) {
-            void client.mutation(api.runtime.leaveServer, { serverId, externalId: config.userId }).catch(() => undefined);
+        for (const [serverId, sessions] of joinedServers) {
+            for (const sessionId of sessions) {
+                void client.mutation(api.runtime.leaveServer, { serverId, externalId: config.userId, ...(sessionId === undefined ? {} : { sessionId }) }).catch(() => undefined);
+            }
         }
         joinedServers.clear();
         globalThis.removeEventListener?.("pagehide", onPageHide);
@@ -19,16 +21,26 @@ export function createConvexGameTransport(client, api, config) {
                 gameId: config.gameId,
                 serverId: args.serverId,
                 externalId: config.userId,
+                ...(args.sessionId === undefined ? {} : { sessionId: args.sessionId }),
             });
             if (result.ok) {
-                joinedServers.add(result.serverId);
+                const sessions = joinedServers.get(result.serverId) ?? new Set();
+                sessions.add(args.sessionId);
+                joinedServers.set(result.serverId, sessions);
                 globalThis.addEventListener?.("pagehide", onPageHide);
             }
             return result;
         },
         async leaveServer(args) {
             await client.mutation(api.runtime.leaveServer, { ...args, externalId: config.userId });
-            joinedServers.delete(args.serverId);
+            const sessions = joinedServers.get(args.serverId);
+            if (args.sessionId === undefined)
+                joinedServers.delete(args.serverId);
+            else {
+                sessions?.delete(args.sessionId);
+                if (sessions?.size === 0)
+                    joinedServers.delete(args.serverId);
+            }
             if (joinedServers.size === 0)
                 globalThis.removeEventListener?.("pagehide", onPageHide);
         },

package/dist/hostedServer.d.ts

@@ -1,7 +1,8 @@
 import type { GameDefinition } from "@jgengine/core/game/defineGame";
 import type { GameContextContent, GameContextModels } 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 HostedWorldSession, type HostedWorldStore, type SyncHostedWorldStore } from "@jgengine/core/runtime/hostedWorldSession";
+import type { WorldSnapshot } from "@jgengine/core/runtime/worldSnapshot";
 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. */
@@ -17,7 +18,7 @@ export interface HostedGameConfig {
  */
 export interface HostedWorldInvocation<T> {
     game: HostedGameConfig;
-    store: HostedWorldStore;
+    store: HostedWorldStore | SyncHostedWorldStore;
     members?: readonly string[];
     inputs?: Readonly<Record<string, InputFrame>>;
     now?: () => number;
@@ -59,7 +60,7 @@ export declare function createHostedGameServerFunctions(options: {
         serverId: string;
         gameId: string;
         revision: number;
-        serverState: any;
+        serverState: WorldSnapshot;
         memberUserIds: string[];
     } | null>>;
     joinHostedServer: import("convex/server").RegisteredMutation<"public", {

package/dist/hostedServer.js

@@ -1,6 +1,6 @@
 import { defineSchema, internalMutationGeneric, mutationGeneric, queryGeneric, } from "convex/server";
 import { ConvexError, v } from "convex/values";
-import { INPUT_COMMAND } from "@jgengine/core/runtime/hostedGameRunner";
+import { createHostedGameRunner, INPUT_COMMAND } from "@jgengine/core/runtime/hostedGameRunner";
 import { createHostedWorldSessionAsync, } from "@jgengine/core/runtime/hostedWorldSession";
 import { commitIfRevisionMatch } from "./occ.js";
 import { jgengineHostedTables, resolveActor } from "./server.js";
@@ -26,7 +26,7 @@ export async function invokeHostedWorld(invocation) {
     for (const [userId, frame] of Object.entries(inputs))
         session.input(userId, frame);
     const value = op(session);
-    const snapshot = session.runner().snapshot();
+    const snapshot = session.runner().state();
     const baseRevision = loaded?.revision ?? 0;
     if (loadedJson !== null && JSON.stringify(snapshot) === loadedJson) {
         return { value, revision: baseRevision, changed: false, members: session.members() };
@@ -129,11 +129,15 @@ export function createHostedGameServerFunctions(options) {
                 return null;
             if (!row.memberUserIds.includes(actorUserId))
                 return null;
+            const game = resolveGame(row.gameId);
+            const runner = createHostedGameRunner({ ...game, restore: row.snapshot });
+            for (const userId of row.memberUserIds)
+                runner.resume(userId);
             return {
                 serverId: row.serverId,
                 gameId: row.gameId,
                 revision: row.revision,
-                serverState: row.snapshot,
+                serverState: runner.snapshot({ userId: actorUserId }),
                 memberUserIds: row.memberUserIds,
             };
         },
@@ -153,14 +157,17 @@ export function createHostedGameServerFunctions(options) {
             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 = await invokeHostedWorld({
                 game,
                 store,
                 members: row?.memberUserIds ?? [],
                 inputs: heldInputsOf(row),
-                op: (session) => session.join(actorUserId, isNew),
+                op: (session) => {
+                    const isNew = !session.hasPlayer(actorUserId) && !session.members().includes(actorUserId);
+                    session.join(actorUserId, isNew);
+                    return isNew;
+                },
             });
             await persistWorldRow(ctx, {
                 gameId: args.gameId,
@@ -170,7 +177,7 @@ export function createHostedGameServerFunctions(options) {
                 memberUserIds: outcome.members,
                 inputs: heldInputsOf(row),
             });
-            return { serverId, isNew };
+            return { serverId, isNew: outcome.value };
         },
     });
     const leaveHostedServer = mutation({

package/dist/server.d.ts

@@ -91,12 +91,15 @@ export declare function jgengineTables(): {
     jgServerMembers: import("convex/server").TableDefinition<import("convex/values").VObject<{
         joinedAt: number;
         serverId: GenericId<"jgGameServers">;
+        sessionIds?: string[] | undefined;
         userId: string;
     }, {
         serverId: import("convex/values").VId<GenericId<"jgGameServers">, "required">;
         userId: import("convex/values").VString<string, "required">;
         joinedAt: import("convex/values").VFloat64<number, "required">;
-    }, "required", "joinedAt" | "serverId" | "userId">, {
+        /** Live client sessions holding this membership; absent on legacy and host-driven joins. */
+        sessionIds: import("convex/values").VArray<string[] | undefined, import("convex/values").VString<string, "required">, "optional">;
+    }, "required", "joinedAt" | "serverId" | "sessionIds" | "userId">, {
         by_server: ["serverId", "_creationTime"];
         by_server_and_user: ["serverId", "userId", "_creationTime"];
     }, {}, {}>;
@@ -379,12 +382,15 @@ declare const schemaForTypes: import("convex/server").SchemaDefinition<{
     jgServerMembers: import("convex/server").TableDefinition<import("convex/values").VObject<{
         joinedAt: number;
         serverId: GenericId<"jgGameServers">;
+        sessionIds?: string[] | undefined;
         userId: string;
     }, {
         serverId: import("convex/values").VId<GenericId<"jgGameServers">, "required">;
         userId: import("convex/values").VString<string, "required">;
         joinedAt: import("convex/values").VFloat64<number, "required">;
-    }, "required", "joinedAt" | "serverId" | "userId">, {
+        /** Live client sessions holding this membership; absent on legacy and host-driven joins. */
+        sessionIds: import("convex/values").VArray<string[] | undefined, import("convex/values").VString<string, "required">, "optional">;
+    }, "required", "joinedAt" | "serverId" | "sessionIds" | "userId">, {
         by_server: ["serverId", "_creationTime"];
         by_server_and_user: ["serverId", "userId", "_creationTime"];
     }, {}, {}>;
@@ -573,6 +579,10 @@ export declare const DEFAULT_CONVEX_POSE_RULES: PoseSyncRules;
 export declare function resolveActor(ctx: {
     auth: Auth;
 }, claimedExternalId: string | undefined, mode: JgAuthMode): Promise<string | null>;
+/** Most live client sessions one shared-topology membership remembers; the oldest drop first. */
+export declare const MAX_MEMBER_SESSIONS = 16;
+/** Longest accepted client `sessionId`. */
+export declare const MAX_SESSION_ID_LENGTH = 128;
 /**
  * How much of a server to hydrate. Both fields default to "everything", which is a document read per
  * member plus one per chunk — the cost that makes a large shared world unaffordable per mutation.
@@ -626,10 +636,23 @@ export type RunCommandArgs = {
      * {@link CommandDef} declares through its own `scope`; omit both to hydrate the whole world.
      */
     scope?: LoadSnapshotScope;
-    /** Trusted host override after game-specific authorization; never forward a client-supplied actor. */
+    /**
+     * Trusted host override after game-specific authorization; never forward a client-supplied actor.
+     * The actor must be a member; when they might have no live session (a closed tab, an agent), call
+     * {@link GameServerHelpers.ensureJoined} first.
+     */
     actorUserId?: string;
     beforePersist?: (ctx: JGMutationCtx, loaded: LoadedServerSnapshot) => Promise<void>;
 };
+/** Outcome of a join: the server joined and whether the player's profile was created, or why it was refused. */
+export type EnsureJoinedOutcome = {
+    ok: true;
+    serverId: GenericId<"jgGameServers">;
+    isNew: boolean;
+} | {
+    ok: false;
+    reason: "full" | "closed" | "unauthorized";
+};
 /** A server resolved for runtime work: its row, its registered runtime, and its hydrated snapshot. */
 export type LoadedServerSnapshot = {
     server: ServerDoc;
@@ -660,7 +683,21 @@ export type GameServerHelpers = {
         reason: string;
     };
     persistSnapshot: (ctx: JGMutationCtx, server: ServerDoc, snapshot: GameRuntimeSnapshot, save?: SaveConfig) => Promise<boolean>;
+    /**
+     * Apply a command as the actor. Refuses non-members with "Not a member of this server"; host
+     * mutations acting for a user who might have no live session call {@link ensureJoined} first.
+     */
     runCommand: (ctx: JGMutationCtx, args: RunCommandArgs) => Promise<RunCommandOutcome>;
+    /**
+     * Join a trusted, already-authorized actor through the same path as the `joinServer` mutation.
+     * Idempotent: an existing member of `serverId` returns at once. Pins no client session, so it never
+     * keeps a membership alive past the user's own session leaves.
+     */
+    ensureJoined: (ctx: JGMutationCtx, args: {
+        gameId: string;
+        userId: string;
+        serverId?: string;
+    }) => Promise<EnsureJoinedOutcome>;
     resetPlayerProfile: (ctx: JGMutationCtx, serverId: string, userId: string) => Promise<RuntimePlayerRow>;
 };
 /** How many running servers one `tickActiveServers` transaction may hydrate, tick, and persist. */
@@ -696,31 +733,13 @@ export declare function createGameServerFunctions(options?: {
         mode?: string | undefined;
         modeConfig?: any;
         serverId?: GenericId<"jgGameServers"> | undefined;
+        sessionId?: string | undefined;
         visibility?: "private" | "public" | undefined;
-    }, Promise<{
-        ok: false;
-        reason: "unauthorized";
-        serverId?: undefined;
-        isNew?: undefined;
-    } | {
-        ok: false;
-        reason: "closed";
-        serverId?: undefined;
-        isNew?: undefined;
-    } | {
-        ok: false;
-        reason: "full";
-        serverId?: undefined;
-        isNew?: undefined;
-    } | {
-        reason?: undefined;
-        ok: true;
-        serverId: GenericId<"jgGameServers">;
-        isNew: boolean;
-    }>>;
+    }, Promise<EnsureJoinedOutcome>>;
     leaveServer: import("convex/server").RegisteredMutation<"public", {
         externalId?: string | undefined;
         serverId: GenericId<"jgGameServers">;
+        sessionId?: string | undefined;
     }, Promise<null>>;
     runCommand: import("convex/server").RegisteredMutation<"public", {
         command: string;