@jgengine/convex 0.44.0 → 0.46.0

package/README.md

@@ -19,7 +19,7 @@ const session = resolveConvexMultiplayer({
 <GamePlayerShell playable={playable} multiplayer={session} />;
 ```
 
-`resolveShellMultiplayer` (`@jgengine/shell/multiplayer`) is the ws counterpart — a dev host can try both in sequence (`resolveConvexMultiplayer(...) ?? resolveShellMultiplayer(...)`, see `apps/dev/src/main.tsx`) and pass whichever resolves to the shell.
+`resolveShellMultiplayer` (`@jgengine/core/multiplayer/multiplayer.draw`) is the ws counterpart — a dev host can try both in sequence (`resolveConvexMultiplayer(...) ?? resolveShellMultiplayer(...)`, see `apps/dev/src/main.tsx`) and pass whichever resolves to the shell.
 
 Once a session resolves, `GamePlayerShell` wires it up with no game code changes: pose presence (`RemotePlayers`), `feedActions` (default `entity.died`) bridged both ways with echo suppression, and `global`-kind chat channels relayed through `chatSyncFor` (`whisper`/`party`/`proximity` stay local). Everything else in `GameContext` stays client-local unless the game also registers a server-side `GameRuntime`.
 

package/dist/convexChatTransport.d.ts

@@ -1,6 +1,6 @@
 import type { FunctionReference } from "convex/server";
-import type { ChatMessage } from "@jgengine/core/game/chat";
-import type { ChatTransport } from "@jgengine/core/multiplayer/chatContract";
+import type { ChatMessage } from "@jgengine/core/chat/chat";
+import type { ChatTransport } from "@jgengine/core/chat/chatContract";
 export interface ConvexChatFunctions {
     messages: FunctionReference<"query">;
     sendMessage: FunctionReference<"mutation">;

package/dist/convexSaveBackend.d.ts

@@ -1,6 +1,6 @@
 import type { ConvexReactClient } from "convex/react";
 import type { FunctionReference } from "convex/server";
-import { type SaveBackend } from "@jgengine/core/game/saveStore";
+import { type SaveBackend } from "@jgengine/core/save/saveStore";
 /** The three Convex functions a save backend calls — a `query` that returns the stored string (or `null`) and two `mutation`s. Point them at your app's own module, or lean on the default `saves.*` convention. */
 export interface ConvexSaveFunctions {
     read: FunctionReference<"query", "public", {

package/dist/convexSaveBackend.js

@@ -1,5 +1,5 @@
 import { anyApi } from "convex/server";
-import { remoteSaveBackend } from "@jgengine/core/game/saveStore";
+import { remoteSaveBackend } from "@jgengine/core/save/saveStore";
 /** Default `saves.read` / `saves.write` / `saves.remove` refs for apps that follow the convention — pass your own `functions` to override. */
 export function defaultConvexSaveFunctions() {
     return anyApi.saves;

package/dist/createConvexGameTransport.d.ts

@@ -1,10 +1,10 @@
 import type { ConvexReactClient } from "convex/react";
 import type { DefaultFunctionArgs, FunctionReference } from "convex/server";
 import type { GameRuntimeFeeds, JoinServerOutcome, GameRuntimeTransport, PresencePoseRow, PresenceSync } from "@jgengine/core/runtime/transport";
-import type { ChatMessage } from "@jgengine/core/game/chat";
-import type { ChatSendOutcome, ChatSync } from "@jgengine/core/multiplayer/chatContract";
+import type { ChatMessage } from "@jgengine/core/chat/chat";
+import type { ChatSendOutcome, ChatSync } from "@jgengine/core/chat/chatContract";
 import { type PoseSyncTuning } from "@jgengine/core/multiplayer/poseSyncGate";
-import type { LeaderboardScope } from "@jgengine/core/game/leaderboard";
+import type { LeaderboardScope } from "@jgengine/core/leaderboard/leaderboard";
 /** Structural client seam avoids requiring the engine and game to share a class instance type. */
 export type ConvexGameClient = Pick<ConvexReactClient, "mutation" | "watchQuery">;
 export type ConvexGameTransportConfig = {

package/dist/server.d.ts

@@ -1,13 +1,14 @@
 import type { Auth, FunctionReference, DataModelFromSchemaDefinition, DocumentByName, GenericMutationCtx, GenericQueryCtx } 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";
+import { type ChatMessage } from "@jgengine/core/chat/chat";
+import type { ChatSendOutcome } from "@jgengine/core/chat/chatContract";
 import { type PoseSyncRules } from "@jgengine/core/multiplayer/presenceModel";
-import type { CommandScope } from "@jgengine/core/runtime/commandRunner";
+import type { CommandScope } from "@jgengine/core/commands/commandRunner";
 import type { GameRuntime } from "@jgengine/core/runtime/gameRuntime";
+import type { RunCommandArgs } from "@jgengine/core/runtime/transport";
 import type { LeaderboardIncrement } from "@jgengine/core/runtime/hostPersistence";
 import { type MatchmakingMode } from "@jgengine/core/runtime/hostPolicy";
-import type { SaveConfig } from "@jgengine/core/runtime/save";
+import type { SaveConfig } from "@jgengine/core/save/saveConfig";
 import type { GameRuntimeSnapshot, RuntimePlayerRow } from "@jgengine/core/runtime/snapshot";
 /** @internal Re-export shared host-policy pure helpers so existing convex imports keep working. */
 export { JG_MAX_MEMBERS_PER_SERVER, canJoinPrivateServer, isListablePublicly, validateSlotsPerServer, type MatchmakingMode, } from "@jgengine/core/runtime/hostPolicy";
@@ -581,8 +582,6 @@ export declare function resolveActor(ctx: {
 }, 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 +625,7 @@ export type RunCommandOutcome = {
     reason: string;
 };
 /** Arguments of the `runCommand` mutation, and of the equivalent {@link GameServerHelpers.runCommand} helper. */
-export type RunCommandArgs = {
-    serverId: string;
-    command: string;
-    input: unknown;
+export type ConvexRunCommandArgs = RunCommandArgs & {
     externalId?: string;
     /**
      * How much of the server to hydrate before applying the command. Overrides whatever the
@@ -687,7 +683,7 @@ export type GameServerHelpers = {
      * 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>;
+    runCommand: (ctx: JGMutationCtx, args: ConvexRunCommandArgs) => 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

package/dist/server.js

@@ -1,12 +1,12 @@
 import { defineSchema, defineTable, internalMutationGeneric, mutationGeneric, queryGeneric, } from "convex/server";
 import { ConvexError, v } from "convex/values";
-import { validateChatMessage } from "@jgengine/core/game/chat";
+import { validateChatMessage } from "@jgengine/core/chat/chat";
 import { createFeedWriteGate, validateFeedWrite, } from "@jgengine/core/multiplayer/feedWriteGate";
 import { DEFAULT_POSE_SYNC_RULES, decidePoseSync, isPresenceExpired, pickReusablePresence, resolveActivePresence, spawnPresenceState, } from "@jgengine/core/multiplayer/presenceModel";
-import { SERVER_ONLY_COMMAND_REASON, commandScopeEscape, scopeWithActor } from "@jgengine/core/runtime/commandRunner";
+import { SERVER_ONLY_COMMAND_REASON, commandScopeEscape, scopeWithActor } from "@jgengine/core/commands/commandRunner";
 import { createGameRuntime, initialPlayerState } from "@jgengine/core/runtime/gameRuntime";
 import { buildHydratePlayers, planServerPersist, shouldAutoSave, trimFeedEntries, } from "@jgengine/core/runtime/hostPersistence";
-import { JG_MAX_MEMBERS_PER_SERVER, isListablePublicly, isPrivateJoinBlocked, isServerFull, isServerMember, selectJoinTarget, statusAfterLeave, validateSlotsPerServer, withJoinedMember, withoutMember, } from "@jgengine/core/runtime/hostPolicy";
+import { JG_MAX_MEMBERS_PER_SERVER, isListablePublicly, isPrivateJoinBlocked, isServerFull, isServerMember, selectJoinTarget, statusAfterLeave, validateSlotsPerServer, withJoinedMember, withoutMember, MAX_SESSION_ID_LENGTH, } from "@jgengine/core/runtime/hostPolicy";
 import { createEmptyServerRow } from "@jgengine/core/runtime/snapshot";
 import { chunkKeyAt, parseChunkKey, chunkKeysAround, DEFAULT_CHUNK_SIZE } from "@jgengine/core/runtime/worldChunks";
 import { applyCommandWithOcc, commitIfRevisionMatch } from "./occ.js";
@@ -203,8 +203,6 @@ async function memberRow(ctx, serverId, userId) {
 }
 /** Most live client sessions one shared-topology membership remembers; the oldest drop first. */
 export const MAX_MEMBER_SESSIONS = 16;
-/** Longest accepted client `sessionId`. */
-export const MAX_SESSION_ID_LENGTH = 128;
 function withSession(sessionIds, sessionId) {
     return [...(sessionIds ?? []).filter((id) => id !== sessionId), sessionId].slice(-MAX_MEMBER_SESSIONS);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/convex",
-  "version": "0.44.0",
+  "version": "0.46.0",
   "description": "Convex adapters for JGengine: game transport, presence transport, and backend wiring over @jgengine/core.",
   "license": "Apache-2.0",
   "type": "module",
@@ -30,16 +30,16 @@
     "check-types": "tsgo --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@jgengine/core": "^0.44.0"
+    "@jgengine/core": "^0.46.0"
   },
   "peerDependencies": {
     "convex": "^1.31.2",
     "react": "^19.0.0"
   },
   "devDependencies": {
-    "convex": "^1.31.2",
-    "react": "19.2.3",
-    "@types/react": "^19"
+    "convex": "catalog:",
+    "react": "catalog:",
+    "@types/react": "catalog:"
   },
   "publishConfig": {
     "access": "public"

package/skills/ce-handoff/SKILL.md

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

package/skills/jgengine/SKILL.md

@@ -38,11 +38,11 @@ Treat the pitch as a unique composition of needs, not a genre to fill in — nev
 - HUD/menu states and **custom** UI art direction (compose shipped building blocks + HudTheme; no unskinned stock face)
 - one observable completion scenario
 
-Pick the dimension first: `create` defaults to a 3D world (terrain, sky, player model, editor scene); a grid, card, tile, or other board game with no 3D scene takes `create --2d` (a `board` world drawn by GameUI over `@jgengine/core/puzzle/cellGrid`). For a new in-repo game, scaffold with `bun run new:game "<id-or-title>"` (thin script alias for `jgengine create`, auto-detects the in-repo variant). Outside this monorepo, start with `npx jgengine create`; never copy `Games/*`.
+Pick the dimension first: `create` defaults to a 3D world (terrain, sky, player model, editor scene); a grid, card, tile, or other board game with no 3D scene takes `create --template 2d` (a `board` world drawn by GameUI over `@jgengine/core/puzzle/cellGrid`). `create --template 3d|2d|builder` is the one way to start a game, in this monorepo too (`bun run jgengine create "<Title>"` lands in `games/`); never copy `games/*`. The game's `jgengine.json` says what it is and uses (template, editor, `@jgengine` packages, and in-repo its capability answers). Change what a game uses by editing it, then run `jgengine sync`, which also brings a game up to the running engine: its `@jgengine` versions and its template's shared files (wiring, page, tooling scripts, AGENTS.md). A shared file the game rewrote goes in its `owns` list so sync leaves it alone.
 
-For an existing game asked to pick up a new engine release ("jgengine published a new version, grab it"), run `npx jgengine upgrade` in the project first: it diffs installed `@jgengine/*` versions against the latest release and prints every Migrate step and Adopt-worthy addition in between (`--json` for structured output). Bump, migrate oldest-first, then work the Adopt lists instead of reconstructing the changelog by hand.
+For an existing game asked to pick up a new engine release ("jgengine published a new version, grab it"), run `npx jgengine@latest sync` in the project (or at its workspace root): it moves every `@jgengine` pin and catalog entry to that release, refreshes the template's files, and prints every Migrate step and Adopt-worthy addition in between. Install, migrate oldest-first, then work the Adopt lists instead of reconstructing the changelog by hand.
 
-`doctor` and `upgrade` resolve Bun `catalog:` and `catalog:<name>` declarations from the nearest workspace's `workspaces.catalog` or `workspaces.catalogs`, and follow hoisted SDK installs. Missing or malformed catalog entries fail diagnostics. `upgrade` is read-only by default. For catalog-owned versions, run `upgrade --plan --to <published-version>` at the workspace root or in a game, review the whole root catalog plan and migrations, then run `upgrade --apply --to <published-version>`. Apply preserves per-game `catalog:` declarations, unrelated text, CLI/github versions, and a held editor override; it verifies published SDK targets and refuses files changed while planning. Apply changes declarations only: run `bun install` at the root, then `jgengine doctor --workspace --json` once there to check installed SDK identities across declared workspace owners. Rebuild, migrate, and verify game behavior afterward. `--json` includes exact before/after text; an apply prints its plan before writing and reports write status on stderr. A report without installed packages labels its resolved pins as a declared baseline.
+`doctor` resolves Bun `catalog:` and `catalog:<name>` declarations from the nearest workspace's `workspaces.catalog` or `workspaces.catalogs` and follows hoisted SDK installs; missing or malformed catalog entries fail diagnostics. `sync` at a workspace root moves the catalog pins (preserving per-game `catalog:` declarations, CLI/github versions and a held editor override) and changes declarations only: run `bun install` at the root, then `jgengine doctor --workspace --json` once there.
 
 When a linked consumer renders differently despite matching root SDK versions, `doctor` checks direct consumers and SDK dependency/peer paths, including private copies with the same version. Review the reported importer and real paths, align the shared catalog and linked-consumer declarations, then reinstall at the root and rerun `doctor --workspace`; a root install may leave private linked-package installs intact. Restart running games after reinstall. Workspace mode checks installed identities only, reports coverage, and refuses unsupported patterns, escaped symlinks or exhausted traversal budgets. The default project audit stays scoped; neither mode covers custom bundler aliases or indirect non-SDK chains.
 
@@ -70,10 +70,10 @@ World content routes editor-first: any request that adds, moves, restyles, or re
 Within each selected domain:
 
 0. Fastest start for a common composition: `npx jgengine recipe <name>` prints a vetted, SDK-typechecked snippet (imports + wired code) (`combat-loop`, `loot`, `world-drops`, `click-target`, `ability-bar`, `hitscan-weapon`, `rolled-gear`, `enter-vehicle` and more); `npx jgengine recipe` lists them. Copy that instead of reconning per-file.
-1. Search capabilities by intent; do not read `capabilities.md` top to bottom. `npx jgengine find <intent>` searches every domain's index and every recipe at once, installed or not, and prints the primitive and its import (or the recipe to open); agents can use `--json --limit 5` for ranked imports and recipes with total, partial-match, and truncation fields. In the monorepo, `rg -i "<intent>" .claude/skills/*/capabilities.md` does the same search. Search the moment you are tempted to hand-roll a HUD window, inventory grid, paperdoll, hotkey listener, minimap, stat bar, or character motion. A `z-index`, a `keydown` for a panel, a `<div>` inventory, or a limb bob almost certainly has a shipped drop-in (`usePanels`/`PanelHost`, `InventoryGrid`, `CharacterSheet`/`Paperdoll`, `PartMotionRig`, `EntityPreview`); games own the *skin*, not the re-derivation.
+1. Search capabilities by intent; do not read `capabilities.md` top to bottom. `npx jgengine find <intent>` names the concept's home folder in each layer (read from the engine source or the installed packages), searches every domain's index and every recipe at once, and prints the primitive and its import (or the recipe to open) and matching assets; agents can use `--json --limit 5` for ranked imports and recipes with total, partial-match, and truncation fields. In the monorepo, `rg -i "<intent>" .claude/skills/*/capabilities.md` does the same search. Search the moment you are tempted to hand-roll a HUD window, inventory grid, paperdoll, hotkey listener, minimap, stat bar, or character motion. A `z-index`, a `keydown` for a panel, a `<div>` inventory, or a limb bob almost certainly has a shipped drop-in (`usePanels`/`PanelHost`, `InventoryGrid`, `CharacterSheet`/`Paperdoll`, `PartMotionRig`, `EntityPreview`); games own the *skin*, not the re-derivation.
 2. Open `api.md` (monorepo) or the package `.d.ts` only when exact signatures are needed; grep it, never read it whole.
 3. Open the linked reference only for a deeper recipe or trap.
-4. For how several primitives wire into a running loop, read the domain's `recipes/` — connected, genre-free walkthroughs organized by composition seam; this skill's own [recipes/minimal-game.md](recipes/minimal-game.md) is the default whole-game walkthrough. Prefer a recipe over reading a game's source; the games under `Games/*` are not templates or references, and a hybrid game is just a different composition of the same primitives.
+4. For how several primitives wire into a running loop, read the domain's `recipes/` — connected, genre-free walkthroughs organized by composition seam; this skill's own [recipes/minimal-game.md](recipes/minimal-game.md) is the default whole-game walkthrough. Prefer a recipe over reading a game's source; the games under `games/*` are not templates or references, and a hybrid game is just a different composition of the same primitives.
 
 If no capability fits, identify the upstream package seam before writing game-local code. In this repository, implement a reusable primitive with its first adopter and a reviewed consumer cleanup; coordinate a differently composed second consumer when applicable. Recipes wire SDK APIs, not copied implementations. If editor-owned content cannot be expressed, file the editor gap first; track any fallback and its removal path.