@jgengine/convex 0.49.1 → 0.50.0

package/CHANGELOG.md

@@ -26,6 +26,164 @@ At publish, rename this heading to the new version and mirror the entries into
 `packages/core/src/meta/changelog.ts` (the typed `CHANGELOG` export).
 -->
 
+## 0.50.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.50.0`:** `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.47.0`; `@jgengine/github` is `0.37.0`.
+- declare the tour's steps in createOnboardingSystem({ steps: [{ id, text, detail, anchor, placement, done: { next: true } }] }) and mount <OnboardingCallout />; a coach-mark condition becomes done: { when } or { event }
+
+### Added
+
+- An action's bindings take `locked: true`: players can't rebind it, saved overrides for it are ignored, and controls menus show it read-only. `isActionLocked(codes)` reads the flag.
+- `persist.storage` in `defineGame` also takes any `SaveBackend`, such as `createConvexSaveBackend`, so a solo game's whole-world save can go to the cloud.
+- Brightway Park design brief: core loop, session goal, long loop, second 0, the first 10 minutes and a content budget
+- `OnboardingCallout` (`@jgengine/core/onboarding/onboardingCallout.view`): The onboarding's UI callout, for steps about the interface rather than the world: a step with an `anchor` (a CSS selector) gets a card beside that element with a spotlight around it, and a step that finishes on Next with no anchor gets a centred card. Also `OnboardingCalloutCard`, `OnboardingCalloutCardProps`, `OnboardingCalloutProps`, `OnboardingCalloutTheme`.
+- `OnboardingCallout` (`@jgengine/react`): The onboarding's UI callout, for steps about the interface rather than the world: a step with an `anchor` (a CSS selector) gets a card beside that element with a spotlight around it, and a step that finishes on Next with no anchor gets a centred card. Also `OnboardingCalloutCard`, `OnboardingCalloutCardProps`, `OnboardingCalloutProps`, `OnboardingCalloutTheme`.
+- Fernwild's Survivor's path takes a new survivor from the first tree to the Broodmother in 23 steps, with a star on the map at each target.
+- Fernwild taming works from a new game with no cheats: punch a dodo out and feed it berries, club a phiomia and keep it under with narcotics. A club hit now lands its full torpor.
+- Fernwild has 21 explorer notes, a Dossier tab of species met, tamed and notes read, and an always-on map baked from the island's ground with notes, obelisks, caves and tames marked.
+- Fernwild danger rises with distance (wild levels capped at 5 by the beach, the full 30 from 1250 m), and the start beach holds only grazers.
+- createSpoilage in @jgengine/core/inventory/spoilage; Fernwild meat spoils into spoiled meat and the timers survive a save.
+- an onboarding step can set inArea: false so a teaching-area pointer sends the player past the area.
+- Fernwild's PLAN.md design brief compares it with ARK beat by beat, and its from-zero proof plays 19 minutes from a new game; Fernwild is off the depth known-failing list.
+- `createSpoilage` (`@jgengine/core/inventory/spoilage`): Perishables in an inventory, as ARK keeps them: each stack runs one timer, and every time it runs out one unit spoils and the timer starts again, so a big stack lasts longer than a small one. Also `SpoilRule`, `Spoilage`, `SpoiledUnits`, `SpoilingStack`.
+- every game's PLAN.md carries a design brief (core, session and long loops, second 0, the first 10 minutes beat by beat, content budget, systems, onboarding); check games-design fails a game without a complete one
+- games/scripts/depth-known-failing.json lists the 18 games that fail the brief, from-zero and depth rules today, with why; the list only shrinks
+- every game has a from-zero proof (proofs/flows/from-zero.flow.ts) that boots a new game with no prepared state or save and plays its first 10 minutes through real input; it fails a start beyond the brief's second 0, nothing taught or unlocked by minute 2, or new things stopping at the brief's pace
+- check games-depth plays that proof and measures systems touched, time to first unlock, unlocks per 10 minutes, content against the budget, the longest cycle and minutes of content; it blocks landing, and today's games are on the shrink-only known-failing list
+- a game declares its new-game start as data (defineGame newGame: cash, kit, unlocked items, prebuilt pieces, systems that start running). The engine builds every new game from that declaration only, refuses start items handed out anywhere else, and exposes it on the definition for checks to read
+- Fernwild declares its start: empty-handed, knowing only the Stone Pick and Torch engrams
+- `NewGameConfig` (`@jgengine/core/game/newGame`): A game's new-game declaration, passed as `defineGame({ newGame })`: the {@link NewGameState} plus the hooks that apply its game-owned parts. Also `NewGameKit`, `NewGamePiece`, `NewGameState`.
+- onboarding as data (createOnboardingSystem). A game declares its steps; each has text, can point at an entity, the nearest thing of a kind or a spot (on-screen pin or edge arrow, minimap marker, waypoint), completes from a game event, a condition, a measured amount or a Next press, can lock commands until done, and grants items, xp, currency or unlocks. Three styles: a separate tutorial level, a teaching start area, or hints blended into stage one. Skippable, saved per player, shown in the quest tracker and objective banner (OnboardingHud, OnboardingBanner, OnboardingPointer, onboardingLock)
+- ctx.game.commands.gate, one place to refuse commands before they run
+- Fernwild's first day: punch a tree for thatch, gather stone, craft a Stone Pick, tame a dodo, each pointing at the nearest tree, stones or dodo with an arrow and a minimap star; engram learning waits for the pick
+- `Onboarding` (`@jgengine/core/onboarding/onboarding`): One player's run through an {@link OnboardingConfig}. Also `OnboardingConfig`, `OnboardingDone`, `OnboardingPoint`, `OnboardingSnapshot`, `OnboardingStep`, `OnboardingStepView`, `OnboardingStyle`, `OnboardingTarget`.
+- `OnboardingBanner` (`@jgengine/core/onboarding/onboarding.view`): The step-done banner ("Gather stone" / "Next: Craft a Stone Pick") through `ObjectiveBannerHost`, near the top of the screen. Also `OnboardingHud`, `OnboardingHudProps`, `useOnboarding`.
+- `OnboardingPointer` (`@jgengine/core/onboarding/OnboardingPointer.draw`): The onboarding's on-screen pointer, mounted in a game's `WorldOverlay`: a pin over the current step's target while it is in view, an edge arrow pointing the way with the distance while it is not (`WaypointMarkers` over the onboarding's waypoint).
+- `ONBOARDING_MARK` (`@jgengine/core/onboarding/onboardingSystem`): The id of the waypoint and minimap marker the onboarding owns. Also `OnboardingRuntime`, `OnboardingSystemOptions`, `createOnboardingSystem`, `onboardingLock`, `onboardingOf`.
+- repeat targeted tests under concurrent load with complete failure evidence
+- A from-zero proof plays a new Scrap Signal game for ten minutes through real input: Bolt's quests one at a time, the crash chest's pistol, the whelps, the convoy's bruisers and red crate, Old Tusk and his whelps, the road to Breakwater Shelf and Captain Rusk. Scrap Signal is off the depth known-failing list for both from-zero and depth.
+- Camp enemies carry four times their listed health and shield (one dial); bosses and Overdrive crews keep their own numbers; cleared camps refill after four minutes away.
+- Ammo crates that restock, ammo packs sized to a camp fight, and kills that always drop ammo while you are nearly dry.
+- Named targets behind side quests and quest-reward uniques.
+- browser proof flows can move the mouse, look and aim with real pointer input again (flow.moveMouse, flow.look, flow.aimAt), restoring the pointer-lock look and crosshair aim lost when the JSON drive steps were replaced
+- `FLOW_AIM_TOLERANCE_PX` (`@jgengine/core/play/flow`): How close {@link BrowserFlow.aimAt} must bring the target to the crosshair, in CSS pixels.
+- withField(row, key, value) in @jgengine/core/data/withField sets an optional field, or leaves it out when value is undefined, so a cleared field is never stored as key: undefined.
+- `definedOnly` (`@jgengine/core/data/definedOnly`): `value` without its undefined fields, so `{ ...defaults, ...definedOnly(overrides) }` never erases a default with an explicit `undefined`, and a record built from optional inputs can be written where an optional field must be absent rather than `undefined`. Also `DefinedOnly`.
+- `withField` (`@jgengine/core/data/withField`): A copy of `row` with the optional field `key` set to `value`, or left out when `value` is `undefined`. Also `OptionalKey`.
+
+### Changed
+
+- AGENTS.md settles two rules: an agent's own scratch files go in the session scratchpad (.scratch/ is only tool output), and a wait under 10 minutes runs in the foreground with a timeout while only dev servers and game launches run in the background
+- Brightway Park keeps monthly books: eight-day months from 1 March, a report of every line (gate, rides, shops, awards, borrowing, wages, upkeep, restocking, repairs, research, marketing, interest, building), loan interest at each month's close, two red month-ends in a row close the park, and three marketing campaigns that bring more guests while they run
+- Brightway Park has a design brief in its PLAN.md and a from-zero proof that plays the first 10 minutes of a new game
+- Brightway Park's probe reports taught, unlocks, each content kind's seen and total, and one reading per system
+- Brightway Park's lab opens with four short topics and the first-scenario hints now teach the lab, so the first unlock lands inside two minutes
+- A new Brightway ride or shop that is still shut opens its window, where Connect it waits
+- Brightway Park leaves the depth known-failing list
+- Brightway Park restarts its calendar for every new park or scenario: 09:00 on 1 March, day one, one midnight a day, even when a scenario is started or replayed mid-way through another park
+- Brightway Park's midnight uses the engine clock's cancel handle, so re-arming it after a reset cancels the old timer
+- Brightway Park starts on an empty lot: a gate plaza, the gate shut, no guests until the player builds a path and a ride and opens the gate
+- Guests trickle in and ramp with rating and appeal; the rating follows the park over the day instead of in seconds
+- The open-park and staff proofs play from the empty lot by mouse and keyboard
+- Brightway Park scenarios run for months: a new game starts Brightway Beginnings on the empty lot (120 guests and 400 stars by the end of May, Year 1), Star Attraction runs the whole first season and Full House two; each is won the moment its targets hold, unlocks the next, and the HUD shows days left; time runs at up to 8x
+- Brightway Park's first scenario teaches itself: a card says the next step and rings the button that does it, with an arrow over the spot on the lot (lay a path from the gate, build a ride, connect it, open the gate), and at the first breakdown it says to hire a mechanic from Staff; a new proof plays from the empty lot to a natural breakdown and the hired mechanic fixing it
+- Brightway Park's README states the award range and what the balance bot really measures, and jgengine.json describes the loan the park actually has
+- Brightway's balance bot plays a new game the way a player starts one: the first scenario, the gate opened, a mechanic hired, and it prints how the scenario stands
+- Brightway Park rides stay down until a mechanic fixes them: mechanics are hireable from the start and go straight to broken rides, the ride window shows reliability for the next run, the lab takes five times longer (34 topics over about thirteen park months, Dodgems now a topic), and litter bins catch litter
+- Brightway Park's hint cards now run on the engine's onboarding system, keep up while the game is paused, and have a Hide hints button
+- Brightway Park scenarios run for months: a new game starts Brightway Beginnings on the empty lot (120 guests and 400 stars by the end of May, Year 1), Star Attraction runs the whole first season and Full House two; each is won the moment its targets hold, unlocks the next, and the HUD shows days left; time runs at up to 8x
+- drive's command line and help move to scripts/driveArgs.ts and its lockstep recorder to scripts/driveLockstep.ts, so drive-dev.ts is the run alone (1074 to 684 lines); the move drops four type casts
+- New create-game-jg skill: a new game starts by agreeing its direction with the user (references, how faithful, breadth, look, scale, players, platforms, what done means), mapping every feature with one jgengine has call, and writing PLAN.md before jgengine create
+- bun run drive prints the result, its warnings and failures by default; --verbose adds the progress, reuse and timing lines, and the GPU driver's shader precision warnings move there too
+- drive --step: try flow calls on a live game page, with closest-match failures A --step runs one browser-flow call on a page of the game kept running (paused between commands) in the warm browser, so trying a click, wait or check answers in seconds instead of a full proof run. A failed click names the closest controls and whether one is covered; a failed probe check names missing probe keys and the closest real ones; see() names the closest page text; a misspelt f.call names the closest calls. The page work moves out of drive-dev.ts into drivePage.ts, shared by --flow --browser and --step. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
+- Landing fails fast: lane:close runs bun run preflight (install, gen, type-checks and gates) first and stops at the first failure, before any test runs
+- bun run preflight is that cheap check on its own; preflight --ship is gone
+- verify:fast starts type-checks and gates before tests and stops starting tests after a failure; --cheap runs only the type-checks and gates
+- bun run gen runs independent generators side by side, and gen barrels reads core's surface once instead of five times
+- lane:close starts the queue for its PR in the background and names the one command that prints the outcome
+- Flaky tests fixed: folder deletes retry on Windows (Bun ignores rm's maxRetries), ws grace-window tests use hand-fired timers, the CDP deadline test waits for the server's message, and scrap-signal's audio test restores fetch instead of deleting it
+- game-making skills start from the PLAN.md design brief: milestones are the next 10 minutes of play proven by the from-zero flow, the greenfield contract folds into the brief, and the first tutorial step no longer has to be doable from starting inventory
+- create-game-jg description back under the 15-word skill limit
+- Changelog: locked bindings and SaveBackend storage
+- Faster frames in every game: half-resolution ambient occlusion, a matrix pass that skips what stood still, and a cheaper per-frame scene walk
+- Ambient occlusion and its denoise run on a quarter of the pixels; at 1080p that cut its GPU time from about 2-3.8 ms to 0.6-1.6 ms in every game that uses it, with no visible change in a side-by-side shot.
+- The scene's matrix pass rebuilds only nodes whose position, rotation, scale, parent or world matrix changed; the shader warmup and other traverseVisible callers use a stack walk (visitVisible), 1.4 ms -> 0.12 ms on fernwild.
+- Dev telemetry reads the GPU name once instead of every second; bun run perf names the engine or game function behind each hot three.js function, and a compile hitch names the draw that waited.
+- bun run perf takes several games in one browser and ends with a table per game; a clean-tree run is cached per commit so --compare HEAD measures only the after side; the process exits once results are written.
+- shoot, verify:fast, preflight and lane:close print only results, warnings, failures and summaries by default; --verbose prints progress, reuse, timing and every pass
+- release --wait: wait on npm serving every package, not on the run's 5-minute check 0.49.0's core reached npm 7m12s after upload, 24 s after publish.yml's 300 s check gave up; release --wait reported a failure and a second release followed (~50 min). release --wait now polls the registry for every lockstep package (bounded at 20 minutes) instead of one npm view of core, and a run that failed only at its registry check keeps waiting on npm and then runs the same artifact check locally. publish.yml's check budget goes from 300 s to 900 s because 300 s was measured too short. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
+- The Rustflat Front's crews wake only after Old Tusk is down; Old Tusk has 2000 health, Captain Rusk 1800 plus a 400 shield.
+- Bruiser Bash now ends at the convoy's red crate, and Old Tusk's quest starts by thinning his whelps.
+- Games: the six strict compiler flags (`noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`, `noImplicitOverride`, `noPropertyAccessFromIndexSignature`, `noImplicitReturns`, `noFallthroughCasesInSwitch`) are now on for every in-repo game through `games/tsconfig.base.json`, and in llmville's own tsconfig. Each game's `check-types` (run by CI) now enforces them, so new strict errors cannot come back.
+- ember-command, drift-foundry and brightway-park now pass the strictest type settings. Their catalogs name their ids, so a mistyped unit, building or research id is a type error, and save loading reads old saves without casts.
+- New `@jgengine/core/data/untyped` (`isRecord`, `isFiniteNumber`, `recordOf`) narrows parsed JSON and old saves without casts. New `slotText`/`slotNumber` in `@jgengine/core/save/saveSlots` read a save slot's chips.
+- `ModelConfig.dims`, `ModelBodySource.dims`, `DrivableVehicleOptions.modifiers`, `BuildingSurfaceMaterial.roughness`/`metalness` and the kit objective's `steps`/`deadline` accept an explicit `undefined`.
+- scrap-signal now type-checks clean under the strict flags (unchecked index access, exact optional properties, no index-signature dot access): save reads go through named locals, optional fields are passed only when set, and catalog lookups say when a key can be missing.
+- The shared legacy-save reader reads the envelope by key.
+- harbor-heat now type-checks clean under the strict flags (unchecked index access, exact optional properties, no index-signature dot access).
+- harbor-heat reads scene meta through the engine's typed meta readers, so a wrong value in the scene file fails naming the marker instead of silently falling back to a default.
+- harbor-heat's save reader uses the engine's shared record check instead of its own copy, and drops casts it no longer needs.
+- deepward now type-checks clean under the strict flags (unchecked index access, exact optional properties, no index-signature dot access).
+- deepward's save reader checks stored fields through named raw shapes and the engine's shared record check, instead of reading an open record by dot.
+- deepward's probe now reports its own named readings, so its proof flows are checked against the real probe keys instead of any string.
+- odd-orbit now type-checks clean under the strict flags (unchecked index access, exact optional properties, no index-signature dot access).
+- odd-orbit's save checker names every stored field it reads, so a misspelled field is a type error instead of a silent `undefined`.
+- A career rung with no pay value now fails loudly instead of paying `NaN`.
+- New engine helper `definedFields` (`@jgengine/core/data/definedFields`): passes maybe-missing values on as optional fields, leaving out the undefined ones, so code stays correct under exact optional property types.
+- llmville: first pass toward the strict type flags (517 errors down to 303). Builder session, agent asset requests, dev endpoints, generated assets and rack commands read untyped input through the engine's record check instead of dot access; map decor and procedural props pass optional transforms through `definedFields`.
+- llmville: the game package, Convex backend, dev-server bridges and scripts now pass the strict compiler flags (strict-flag errors 303 → 173; the rest are in `src/`).
+- llmville: command and save readers use bracket reads, optional fields that can be unset say so with `| undefined`, and Convex calls only pass optional fields that are set.
+- llmville: the whole game now passes the strict compiler flags (strict-flag errors 173 → 0).
+- llmville: component props and view-model fields that can be unset say so with `| undefined`; list reads check for a missing entry; fixed lists (avatars, builder materials, room templates) are typed as never empty.
+- llmville: the error-report payload only sends fields that are set, and the toast theme no longer needs a cast.
+- Nine games (apex-nights, beacon-bastion, briarcrown, hold-the-line, orbit-watch, outpost-zero, red-frontier, saltwick, the-sunken-crown) now pass the strictest type settings, ahead of those settings turning on for every game.
+- Games read a placed object's authored settings through `metaNumber`, `metaText` and `requireMetaText` (`@jgengine/core/editor/markerMeta`), which fail loudly on a wrong value instead of casting it.
+- `CompassProps.center`, the kit vitals objective's `id`/`goal`, and kit buttons' `cue` accept an explicit `undefined`.
+- Every engine package (assets, convex, editor, github, jgengine, navbake, node, rapier, react, sql) now type-checks with the strict flags core, shell and ws already had. 400 errors fixed with guards and real types, no new casts.
+- definedOnly in @jgengine/core/data/definedOnly is public, and its result keeps always-defined fields required; only fields that may be undefined become optional.
+- Scripts, the UI registry, the dev, web and desktop apps and the host examples now type-check with the same strict flags as the engine packages. About 1000 errors fixed with guards and real types, no new casts.
+- optional fields on registry slot props (ActionBarSlot, ItemGridSlot, BuffChip), EditorAppProps, the ws host's listOpenServers args and a few core option types accept an explicit undefined.
+
+### Fixed
+
+- Beacon Bastion's pacing test counts only gold the keep could still have spent: the bounty from the last kill, paid after the final chance to buy, no longer fails a keep that spent everything it could. A keep that stops buying still fails the test.
+- Brightway Park's status card no longer overlaps the goal card at 1600x900; it keeps a steady height as guest thoughts come and go, with mood and cleanliness side by side
+- Brightway's goal hint no longer says to lay a path when the only ride is broken down
+- Fernwild's Harvest Stones prompt no longer shows when you aim at a tree.
+- Fernwild's dehydration test steps whole seconds so it finishes inside CI's test timeout.
+- Fernwild no longer freezes for about a second when you press Play: the island's 33k trees and rocks are placed while the title loads (worst click 940 ms -> 510 ms, menu shows ~0.5 s later)
+- drive --playtest judges a softlock only after the player first acts; a quiet title or idle start no longer counts
+- the capability boot probe presses Play (the game's capture.play) and gives a system 300 frames from there, not from the menu
+- closing a lane again with -m adds the new lines to its change note instead of replacing it
+- the automatic worktree cleanup now removes a lane that never committed once it has sat untouched for an hour with no changed or new files, and its dry run lists only what a real run would take
+- waypoint pins and edge arrows near a screen edge keep their label on screen
+- world-anchored floating text no longer re-renders every frame while nothing floats
+- the worktree cleanup leaves a tree a running process holds whole and reports it in use, instead of half-deleting it and stopping, so the trees after it still go
+- bun run worktree new runs the cleanup from the new tree's own code, not the main checkout's possibly older copy
+- Rockets burst on the first thing they hit instead of flying through it.
+- Chest and crate drops land two metres out on the opener's side, so picking one up no longer puts the camera inside the chest.
+- on Windows a new worktree shares the main checkout's installed packages instead of installing 713 of its own, so it is ready in about 10s instead of 30s to 2 minutes
+- a worktree whose bun.lock moved on gets its own install instead of writing into the shared one
+- the 17 aim and look checks removed with the old drive steps are restored, and the 12 removed drive-step assertion checks now live as browser flow tests (failing expect stops the run, strict value matching, a page error, a timed-out wait)
+- A new game made with `--no-editor` now gets the starter sun angle; it was written in the editor's shape, which `sky()` ignored.
+- the casts and non-null assertions the type-escape baseline was raised to accept (boot sequence, asset prefetch, frame breakdown, perf panel, dev asset plugin, perf scripts) are replaced by real checks.
+- Convex inserts and query results no longer write field: undefined for optional columns.
+- the workspace catalog JSON scanner throws a clear error on truncated JSON instead of reading past the end.
+- script readers of changelog headings, PNG headers and screenshot pixels no longer read past the end of their input.
+
+### Removed
+
+- createCoachMarkSequence, CoachMark and CoachMarkHost. UI tours are onboarding steps now: give a step an anchor (CSS selector) and placement, or finish it on Next, and OnboardingCallout shows it as a card with a spotlight, Next and Skip, saved with the game
+- `@jgengine/core/ui` no longer exports `CoachMarkPlacement`, `CoachMarkSequence`, `CoachMarkSequenceOptions`, `CoachMarkSnapshot`, `CoachMarkStep`, `CoachMarkView`, `createCoachMarkSequence`.
+- `@jgengine/core/ui/coachMarks` no longer exports `CoachMarkPlacement`, `CoachMarkSequence`, `CoachMarkSequenceOptions`, `CoachMarkSnapshot`, `CoachMarkStep`, `CoachMarkView`, `createCoachMarkSequence`.
+- `@jgengine/core/ui/coachMarks.view` no longer exports `CoachMark`, `CoachMarkHost`, `CoachMarkHostProps`, `CoachMarkProps`, `CoachMarkTheme`, `useCoachMarks`.
+- `@jgengine/react` no longer exports `CoachMark`, `CoachMarkHost`, `CoachMarkHostProps`, `CoachMarkProps`, `CoachMarkTheme`, `useCoachMarks`.
+- the jgengine plan command; the skill replaces it, and jgengine has stays as the lookup
+- the progression-curve seam from games-framework; a game's own level numbers, unlock order and tutorial beats stay in the game at any length (games/AGENTS.md mechanism signal)
+- system checkboxes from the game READMEs' progression sections; progression is written as what the player gets over hours
+
 ## 0.49.1
 
 ### Migrate

package/dist/createConvexBackend.d.ts

@@ -13,8 +13,8 @@ export type ConvexBackendOptions<TRawPresenceRow extends {
     client: ConvexReactClient;
     gameId: string;
     userId: string;
-    api?: ConvexGameApi;
-    poseTuning?: PoseSyncTuning;
+    api?: ConvexGameApi | undefined;
+    poseTuning?: PoseSyncTuning | undefined;
     presence?: {
         functions: ConvexPresenceFunctions;
         mapRow: (row: TRawPresenceRow) => TPresenceRow;

package/dist/createConvexGameTransport.d.ts

@@ -15,23 +15,23 @@ export type ConvexGameApi = {
     runtime: {
         joinServer: FunctionReference<"mutation", "public", {
             gameId: string;
-            serverId?: string;
+            serverId?: string | undefined;
             mode?: string;
             visibility?: "public" | "private";
             joinCode?: string;
-            externalId?: string;
+            externalId?: string | undefined;
             sessionId?: string;
         }, JoinServerOutcome>;
         leaveServer: FunctionReference<"mutation", "public", {
             serverId: string;
-            externalId?: string;
+            externalId?: string | undefined;
             sessionId?: string;
         }, null>;
         runCommand: FunctionReference<"mutation", "public", {
             serverId: string;
             command: string;
             input: unknown;
-            externalId?: string;
+            externalId?: string | undefined;
         }, {
             ok: true;
         } | {
@@ -42,7 +42,7 @@ export type ConvexGameApi = {
             serverId: string;
             action: string;
             entry: unknown;
-            externalId?: string;
+            externalId?: string | undefined;
         }, null>;
         getServer: FunctionReference<"query", "public", {
             serverId: string;
@@ -55,13 +55,13 @@ export type ConvexGameApi = {
         getFeed: FunctionReference<"query", "public", {
             serverId: string;
             action: string;
-            externalId?: string;
+            externalId?: string | undefined;
         }, unknown[]>;
     };
     presence: {
         list: FunctionReference<"query", "public", {
             serverId: string;
-            externalId?: string;
+            externalId?: string | undefined;
             viewerChunkKey?: string;
         }, PresencePoseRow[]>;
         sync: FunctionReference<"mutation", "public", {
@@ -76,7 +76,7 @@ export type ConvexGameApi = {
             sessionId?: string;
             kind?: string;
             label?: string;
-            externalId?: string;
+            externalId?: string | undefined;
         }, {
             pose: {
                 x: number;
@@ -98,13 +98,13 @@ export type ConvexGameApi = {
         messages: FunctionReference<"query", "public", {
             serverId: string;
             channelId: string;
-            externalId?: string;
+            externalId?: string | undefined;
         }, ChatMessage[]>;
         sendMessage: FunctionReference<"mutation", "public", {
             serverId: string;
             channelId: string;
             body: string;
-            externalId?: string;
+            externalId?: string | undefined;
         }, ChatSendOutcome>;
     };
     leaderboard: {

package/dist/hostedServer.d.ts

@@ -53,9 +53,9 @@ export declare function createHostedGameServerFunctions(options: {
     tickMs?: number;
 }): {
     getHostedServer: import("convex/server").RegisteredQuery<"public", {
-        externalId?: string | undefined;
+        externalId?: string;
         gameId: string;
-        serverId?: string | undefined;
+        serverId?: string;
     }, Promise<{
         serverId: string;
         gameId: string;
@@ -64,24 +64,24 @@ export declare function createHostedGameServerFunctions(options: {
         memberUserIds: string[];
     } | null>>;
     joinHostedServer: import("convex/server").RegisteredMutation<"public", {
-        externalId?: string | undefined;
+        externalId?: string;
         gameId: string;
-        serverId?: string | undefined;
+        serverId?: string;
     }, Promise<{
         serverId: string;
         isNew: boolean;
     }>>;
     leaveHostedServer: import("convex/server").RegisteredMutation<"public", {
-        externalId?: string | undefined;
+        externalId?: string;
         gameId: string;
-        serverId?: string | undefined;
+        serverId?: string;
     }, Promise<null>>;
     runHostedCommand: import("convex/server").RegisteredMutation<"public", {
         command: string;
-        externalId?: string | undefined;
+        externalId?: string;
         gameId: string;
         input: any;
-        serverId?: string | undefined;
+        serverId?: string;
     }, Promise<{
         ok: false;
         reason: string;
@@ -89,10 +89,10 @@ export declare function createHostedGameServerFunctions(options: {
         ok: true;
     }>>;
     submitHostedInput: import("convex/server").RegisteredMutation<"public", {
-        externalId?: string | undefined;
+        externalId?: string;
         frame: any;
         gameId: string;
-        serverId?: string | undefined;
+        serverId?: string;
     }, Promise<null>>;
     tickHostedWorlds: import("convex/server").RegisteredMutation<"internal", {}, Promise<{
         ticked: number;

package/dist/resolveConvexMultiplayer.d.ts

@@ -7,7 +7,7 @@ export declare function randomConvexPlayerId(): string;
 export declare function resolveConvexMultiplayer(args: {
     game: GameDefinition;
     gameId: string;
-    url?: string;
+    url?: string | undefined;
     client?: ConvexReactClient;
     api?: ConvexGameApi;
     userId?: string;

package/dist/server.d.ts

@@ -16,13 +16,13 @@ export { JG_MAX_MEMBERS_PER_SERVER, canJoinPrivateServer, isListablePublicly, va
 export declare function jgengineTables(): {
     jgGameServers: import("convex/server").TableDefinition<import("convex/values").VObject<{
         createdAt: number;
-        dirtyAt?: number | undefined;
+        dirtyAt?: number;
         gameId: string;
-        joinCode?: string | undefined;
-        lastSavedAt?: number | undefined;
-        memberCount?: number | undefined;
+        joinCode?: string;
+        lastSavedAt?: number;
+        memberCount?: number;
         memberUserIds: string[];
-        mode?: string | undefined;
+        mode?: string;
         modeConfig?: any;
         revision: number;
         save: "none" | {
@@ -34,9 +34,9 @@ export declare function jgengineTables(): {
         slotsPerServer: number;
         status: "closed" | "open" | "running";
         tickAnchorMs: number;
-        topology?: "rooms" | "shared" | undefined;
+        topology?: "rooms" | "shared";
         updatedAt: number;
-        visibility?: "private" | "public" | undefined;
+        visibility?: "private" | "public";
     }, {
         gameId: import("convex/values").VString<string, "required">;
         status: import("convex/values").VUnion<"closed" | "open" | "running", [import("convex/values").VLiteral<"open", "required">, import("convex/values").VLiteral<"running", "required">, import("convex/values").VLiteral<"closed", "required">], "required", never>;
@@ -75,7 +75,7 @@ export declare function jgengineTables(): {
     jgServerCapacity: import("convex/server").TableDefinition<import("convex/values").VObject<{
         gameId: string;
         memberCount: number;
-        mode?: string | undefined;
+        mode?: string;
         serverId: GenericId<"jgGameServers">;
         slotsPerServer: number;
         status: "closed" | "open" | "running";
@@ -92,7 +92,7 @@ export declare function jgengineTables(): {
     jgServerMembers: import("convex/server").TableDefinition<import("convex/values").VObject<{
         joinedAt: number;
         serverId: GenericId<"jgGameServers">;
-        sessionIds?: string[] | undefined;
+        sessionIds?: string[];
         userId: string;
     }, {
         serverId: import("convex/values").VId<GenericId<"jgGameServers">, "required">;
@@ -133,11 +133,11 @@ export declare function jgengineTables(): {
     }, {}, {}>;
     jgPlayerProfiles: import("convex/server").TableDefinition<import("convex/values").VObject<{
         createdAt: number;
-        dirtyAt?: number | undefined;
+        dirtyAt?: number;
         gameId: string;
         playerState: any;
         revision: number;
-        sessionServerId?: GenericId<"jgGameServers"> | undefined;
+        sessionServerId?: GenericId<"jgGameServers">;
         sessionState?: any;
         updatedAt: number;
         userId: string;
@@ -156,7 +156,7 @@ export declare function jgengineTables(): {
     }, {}, {}>;
     jgWorldChunks: import("convex/server").TableDefinition<import("convex/values").VObject<{
         chunkKey: string;
-        dirtyAt?: number | undefined;
+        dirtyAt?: number;
         serverId: GenericId<"jgGameServers">;
         snapshot: any;
         updatedAt: number;
@@ -173,7 +173,7 @@ export declare function jgengineTables(): {
     jgLeaderboardRows: import("convex/server").TableDefinition<import("convex/values").VObject<{
         gameId: string;
         scope: "global" | "profile" | "server";
-        serverId?: GenericId<"jgGameServers"> | undefined;
+        serverId?: GenericId<"jgGameServers">;
         stat: string;
         updatedAt: number;
         userId: string;
@@ -204,17 +204,17 @@ export declare function jgengineTables(): {
         by_server_and_action: ["serverId", "action", "_creationTime"];
     }, {}, {}>;
     jgPoses: import("convex/server").TableDefinition<import("convex/values").VObject<{
-        chunkKey?: string | undefined;
-        homeGameId?: string | undefined;
-        kind?: string | undefined;
-        label?: string | undefined;
-        lastWorldSnapshotAt?: number | undefined;
-        ownerActorId?: string | undefined;
-        revokedAt?: number | undefined;
+        chunkKey?: string;
+        homeGameId?: string;
+        kind?: string;
+        label?: string;
+        lastWorldSnapshotAt?: number;
+        ownerActorId?: string;
+        revokedAt?: number;
         rotationPitch: number;
         rotationY: number;
         serverId: string;
-        sessionId?: string | undefined;
+        sessionId?: string;
         updatedAt: number;
         userId: string;
         x: number;
@@ -255,7 +255,7 @@ export declare function jgengineTables(): {
     }, {}, {}>;
     jgChatMessages: import("convex/server").TableDefinition<import("convex/values").VObject<{
         at: number;
-        authorName?: string | undefined;
+        authorName?: string;
         body: string;
         channelId: string;
         serverId: string;
@@ -307,13 +307,13 @@ export declare function jgengineHostedTables(): {
 declare const schemaForTypes: import("convex/server").SchemaDefinition<{
     jgGameServers: import("convex/server").TableDefinition<import("convex/values").VObject<{
         createdAt: number;
-        dirtyAt?: number | undefined;
+        dirtyAt?: number;
         gameId: string;
-        joinCode?: string | undefined;
-        lastSavedAt?: number | undefined;
-        memberCount?: number | undefined;
+        joinCode?: string;
+        lastSavedAt?: number;
+        memberCount?: number;
         memberUserIds: string[];
-        mode?: string | undefined;
+        mode?: string;
         modeConfig?: any;
         revision: number;
         save: "none" | {
@@ -325,9 +325,9 @@ declare const schemaForTypes: import("convex/server").SchemaDefinition<{
         slotsPerServer: number;
         status: "closed" | "open" | "running";
         tickAnchorMs: number;
-        topology?: "rooms" | "shared" | undefined;
+        topology?: "rooms" | "shared";
         updatedAt: number;
-        visibility?: "private" | "public" | undefined;
+        visibility?: "private" | "public";
     }, {
         gameId: import("convex/values").VString<string, "required">;
         status: import("convex/values").VUnion<"closed" | "open" | "running", [import("convex/values").VLiteral<"open", "required">, import("convex/values").VLiteral<"running", "required">, import("convex/values").VLiteral<"closed", "required">], "required", never>;
@@ -366,7 +366,7 @@ declare const schemaForTypes: import("convex/server").SchemaDefinition<{
     jgServerCapacity: import("convex/server").TableDefinition<import("convex/values").VObject<{
         gameId: string;
         memberCount: number;
-        mode?: string | undefined;
+        mode?: string;
         serverId: GenericId<"jgGameServers">;
         slotsPerServer: number;
         status: "closed" | "open" | "running";
@@ -383,7 +383,7 @@ declare const schemaForTypes: import("convex/server").SchemaDefinition<{
     jgServerMembers: import("convex/server").TableDefinition<import("convex/values").VObject<{
         joinedAt: number;
         serverId: GenericId<"jgGameServers">;
-        sessionIds?: string[] | undefined;
+        sessionIds?: string[];
         userId: string;
     }, {
         serverId: import("convex/values").VId<GenericId<"jgGameServers">, "required">;
@@ -424,11 +424,11 @@ declare const schemaForTypes: import("convex/server").SchemaDefinition<{
     }, {}, {}>;
     jgPlayerProfiles: import("convex/server").TableDefinition<import("convex/values").VObject<{
         createdAt: number;
-        dirtyAt?: number | undefined;
+        dirtyAt?: number;
         gameId: string;
         playerState: any;
         revision: number;
-        sessionServerId?: GenericId<"jgGameServers"> | undefined;
+        sessionServerId?: GenericId<"jgGameServers">;
         sessionState?: any;
         updatedAt: number;
         userId: string;
@@ -447,7 +447,7 @@ declare const schemaForTypes: import("convex/server").SchemaDefinition<{
     }, {}, {}>;
     jgWorldChunks: import("convex/server").TableDefinition<import("convex/values").VObject<{
         chunkKey: string;
-        dirtyAt?: number | undefined;
+        dirtyAt?: number;
         serverId: GenericId<"jgGameServers">;
         snapshot: any;
         updatedAt: number;
@@ -464,7 +464,7 @@ declare const schemaForTypes: import("convex/server").SchemaDefinition<{
     jgLeaderboardRows: import("convex/server").TableDefinition<import("convex/values").VObject<{
         gameId: string;
         scope: "global" | "profile" | "server";
-        serverId?: GenericId<"jgGameServers"> | undefined;
+        serverId?: GenericId<"jgGameServers">;
         stat: string;
         updatedAt: number;
         userId: string;
@@ -495,17 +495,17 @@ declare const schemaForTypes: import("convex/server").SchemaDefinition<{
         by_server_and_action: ["serverId", "action", "_creationTime"];
     }, {}, {}>;
     jgPoses: import("convex/server").TableDefinition<import("convex/values").VObject<{
-        chunkKey?: string | undefined;
-        homeGameId?: string | undefined;
-        kind?: string | undefined;
-        label?: string | undefined;
-        lastWorldSnapshotAt?: number | undefined;
-        ownerActorId?: string | undefined;
-        revokedAt?: number | undefined;
+        chunkKey?: string;
+        homeGameId?: string;
+        kind?: string;
+        label?: string;
+        lastWorldSnapshotAt?: number;
+        ownerActorId?: string;
+        revokedAt?: number;
         rotationPitch: number;
         rotationY: number;
         serverId: string;
-        sessionId?: string | undefined;
+        sessionId?: string;
         updatedAt: number;
         userId: string;
         x: number;
@@ -546,7 +546,7 @@ declare const schemaForTypes: import("convex/server").SchemaDefinition<{
     }, {}, {}>;
     jgChatMessages: import("convex/server").TableDefinition<import("convex/values").VObject<{
         at: number;
-        authorName?: string | undefined;
+        authorName?: string;
         body: string;
         channelId: string;
         serverId: string;
@@ -626,7 +626,7 @@ export type RunCommandOutcome = {
 };
 /** Arguments of the `runCommand` mutation, and of the equivalent {@link GameServerHelpers.runCommand} helper. */
 export type ConvexRunCommandArgs = RunCommandArgs & {
-    externalId?: string;
+    externalId?: string | undefined;
     /**
      * How much of the server to hydrate before applying the command. Overrides whatever the
      * {@link CommandDef} declares through its own `scope`; omit both to hydrate the whole world.
@@ -723,42 +723,42 @@ export declare function createGameServerFunctions(options?: {
     allowedFeedActions?: readonly string[];
 }): {
     joinServer: import("convex/server").RegisteredMutation<"public", {
-        externalId?: string | undefined;
+        externalId?: string;
         gameId: string;
-        joinCode?: string | undefined;
-        mode?: string | undefined;
+        joinCode?: string;
+        mode?: string;
         modeConfig?: any;
-        serverId?: GenericId<"jgGameServers"> | undefined;
-        sessionId?: string | undefined;
-        visibility?: "private" | "public" | undefined;
+        serverId?: GenericId<"jgGameServers">;
+        sessionId?: string;
+        visibility?: "private" | "public";
     }, Promise<EnsureJoinedOutcome>>;
     leaveServer: import("convex/server").RegisteredMutation<"public", {
-        externalId?: string | undefined;
+        externalId?: string;
         serverId: GenericId<"jgGameServers">;
-        sessionId?: string | undefined;
+        sessionId?: string;
     }, Promise<null>>;
     runCommand: import("convex/server").RegisteredMutation<"public", {
         command: string;
-        externalId?: string | undefined;
+        externalId?: string;
         input: any;
         scope?: {
-            chunkKeys?: string[] | undefined;
-            players?: string[] | undefined;
-        } | undefined;
+            chunkKeys?: string[];
+            players?: string[];
+        };
         serverId: GenericId<"jgGameServers">;
     }, Promise<RunCommandOutcome>>;
     flushSave: import("convex/server").RegisteredMutation<"public", {
-        externalId?: string | undefined;
+        externalId?: string;
         serverId: GenericId<"jgGameServers">;
     }, Promise<boolean>>;
     getServer: import("convex/server").RegisteredQuery<"public", {
-        externalId?: string | undefined;
+        externalId?: string;
         serverId: GenericId<"jgGameServers">;
     }, Promise<{
         _id: GenericId<"jgGameServers">;
         gameId: string;
         status: "closed" | "open" | "running";
-        mode: string | undefined;
+        mode?: string;
         memberUserIds: string[];
         slotsPerServer: number;
         save: "none" | {
@@ -773,30 +773,30 @@ export declare function createGameServerFunctions(options?: {
         updatedAt: number;
     } | null>>;
     getServerMeta: import("convex/server").RegisteredQuery<"public", {
-        externalId?: string | undefined;
+        externalId?: string;
         serverId: GenericId<"jgGameServers">;
-    }, Promise<{
+    }, Promise<import("@jgengine/core/data/definedOnly").DefinedOnly<{
         _id: GenericId<"jgGameServers">;
         gameId: string;
         status: "closed" | "open" | "running";
         mode: string | undefined;
         memberCount: number;
         slotsPerServer: number;
-    } | null>>;
+    }> | null>>;
     getServerCapacity: import("convex/server").RegisteredQuery<"public", {
-        externalId?: string | undefined;
+        externalId?: string;
         serverId: GenericId<"jgGameServers">;
-    }, Promise<{
+    }, Promise<import("@jgengine/core/data/definedOnly").DefinedOnly<{
         _id: GenericId<"jgGameServers">;
         gameId: string;
         status: "closed" | "open" | "running";
         mode: string | undefined;
         memberCount: number;
         slotsPerServer: number;
-    } | null>>;
+    }> | null>>;
     getChunks: import("convex/server").RegisteredQuery<"public", {
         chunkKeys: string[];
-        externalId?: string | undefined;
+        externalId?: string;
         serverId: GenericId<"jgGameServers">;
     }, Promise<{
         chunkKey: string;
@@ -804,7 +804,7 @@ export declare function createGameServerFunctions(options?: {
         updatedAt: number;
     }[]>>;
     getPlayerProfile: import("convex/server").RegisteredQuery<"public", {
-        externalId?: string | undefined;
+        externalId?: string;
         gameId: string;
     }, Promise<{
         userId: string;
@@ -815,27 +815,28 @@ export declare function createGameServerFunctions(options?: {
     } | null>>;
     getFeed: import("convex/server").RegisteredQuery<"public", {
         action: string;
-        externalId?: string | undefined;
+        externalId?: string;
         serverId: GenericId<"jgGameServers">;
     }, Promise<any[]>>;
     pushFeedEntry: import("convex/server").RegisteredMutation<"public", {
         action: string;
         entry: any;
-        externalId?: string | undefined;
+        externalId?: string;
         serverId: GenericId<"jgGameServers">;
     }, Promise<null>>;
     listOpenServers: import("convex/server").RegisteredQuery<"public", {
-        externalId?: string | undefined;
+        externalId?: string;
         gameId: string;
-        limit?: number | undefined;
-    }, Promise<{
+        limit?: number;
+    }, Promise<({
         _id: GenericId<"jgGameServers">;
         status: "closed" | "open" | "running";
         memberCount: number;
         slotsPerServer: number;
-        mode: string | undefined;
         updatedAt: number;
-    }[]>>;
+    } & {
+        mode?: string;
+    })[]>>;
     tickActiveServers: import("convex/server").RegisteredMutation<"internal", {}, Promise<{
         ticked: number;
         saved: number;
@@ -850,18 +851,18 @@ export declare function createLeaderboardFunctions(options?: {
     auth?: JgAuthMode;
 }): {
     getTop: import("convex/server").RegisteredQuery<"public", {
-        externalId?: string | undefined;
+        externalId?: string;
         gameId: string;
-        limit?: number | undefined;
+        limit?: number;
         scope: "global" | "profile" | "server";
-        serverId?: GenericId<"jgGameServers"> | undefined;
+        serverId?: GenericId<"jgGameServers">;
         stat: string;
     }, Promise<{
         userId: string;
         value: number;
     }[]>>;
     getProfile: import("convex/server").RegisteredQuery<"public", {
-        externalId?: string | undefined;
+        externalId?: string;
         gameId: string;
         userId: string;
     }, Promise<Record<string, number>>>;
@@ -869,7 +870,7 @@ export declare function createLeaderboardFunctions(options?: {
         entries: {
             by: number;
             scope: "global" | "profile" | "server";
-            serverId?: GenericId<"jgGameServers"> | undefined;
+            serverId?: GenericId<"jgGameServers">;
             stat: string;
             userId: string;
         }[];
@@ -925,7 +926,7 @@ export declare function createPresenceFunctions(options?: {
     resolveSpawn?: (ctx: JGMutationCtx, args: {
         serverId: string;
         userId: string;
-        kind?: string;
+        kind?: string | undefined;
     }) => Promise<{
         x: number;
         y: number;
@@ -937,28 +938,28 @@ export declare function createPresenceFunctions(options?: {
     } | null;
 }): {
     list: import("convex/server").RegisteredQuery<"public", {
-        externalId?: string | undefined;
+        externalId?: string;
         serverId: string;
-        viewerChunkKey?: string | undefined;
+        viewerChunkKey?: string;
     }, Promise<PresenceListRow[]>>;
     sync: import("convex/server").RegisteredMutation<"public", {
-        externalId?: string | undefined;
-        kind?: string | undefined;
-        label?: string | undefined;
+        externalId?: string;
+        kind?: string;
+        label?: string;
         pose?: {
             rotationPitch: number;
             rotationY: number;
             x: number;
             y: number;
             z: number;
-        } | undefined;
+        };
         serverId: string;
-        sessionId?: string | undefined;
+        sessionId?: string;
     }, Promise<PresenceSyncResult | null>>;
     leave: import("convex/server").RegisteredMutation<"public", {
-        externalId?: string | undefined;
+        externalId?: string;
         serverId: string;
-        sessionId?: string | undefined;
+        sessionId?: string;
     }, Promise<null>>;
     reapIdlePresence: import("convex/server").RegisteredMutation<"internal", {}, Promise<{
         reaped: number;
@@ -1033,7 +1034,7 @@ export declare function recentChatMessages(ctx: {
     _creationTime: number;
     _id: GenericId<"jgChatMessages">;
     at: number;
-    authorName?: string | undefined;
+    authorName?: string;
     body: string;
     channelId: string;
     serverId: string;
@@ -1045,19 +1046,19 @@ export declare function recentChatMessages(ctx: {
  */
 export declare function createClientErrorFunctions(): {
     reportClientError: import("convex/server").RegisteredMutation<"public", {
-        agentPrompt?: string | undefined;
-        componentStack?: string | undefined;
-        kind?: string | undefined;
+        agentPrompt?: string;
+        componentStack?: string;
+        kind?: string;
         message: string;
-        pathname?: string | undefined;
-        stack?: string | undefined;
-        url?: string | undefined;
-        userAgent?: string | undefined;
+        pathname?: string;
+        stack?: string;
+        url?: string;
+        userAgent?: string;
     }, Promise<{
         ok: boolean;
         reason: string;
     } | {
-        reason?: undefined;
+        reason?: never;
         ok: boolean;
     }>>;
     pruneClientErrors: import("convex/server").RegisteredMutation<"internal", {}, Promise<{
@@ -1078,18 +1079,18 @@ export declare function createChatFunctions(options?: {
 }): {
     messages: import("convex/server").RegisteredQuery<"public", {
         channelId: string;
-        externalId?: string | undefined;
+        externalId?: string;
         serverId: string;
     }, Promise<ChatMessage[]>>;
     recent: import("convex/server").RegisteredQuery<"public", {
         channelId: string;
-        externalId?: string | undefined;
+        externalId?: string;
         serverId: string;
     }, Promise<ChatMessage[]>>;
     sendMessage: import("convex/server").RegisteredMutation<"public", {
         body: string;
         channelId: string;
-        externalId?: string | undefined;
+        externalId?: string;
         serverId: string;
     }, Promise<ChatSendOutcome>>;
     pruneChatMessages: import("convex/server").RegisteredMutation<"internal", {}, Promise<{

package/dist/server.js

@@ -1,6 +1,7 @@
 import { defineSchema, defineTable, internalMutationGeneric, mutationGeneric, queryGeneric, } from "convex/server";
 import { ConvexError, v } from "convex/values";
 import { validateChatMessage } from "@jgengine/core/chat/chat";
+import { definedOnly } from "@jgengine/core/data/definedOnly";
 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/commands/commandRunner";
@@ -298,10 +299,10 @@ async function ensureServerCapacity(ctx, server) {
     const existing = await serverCapacity(ctx, server);
     if (existing)
         return existing;
-    const id = await ctx.db.insert("jgServerCapacity", {
+    const id = await ctx.db.insert("jgServerCapacity", definedOnly({
         serverId: server._id, gameId: server.gameId, status: server.status, mode: server.mode,
         memberCount: server.memberCount ?? server.memberUserIds.length, slotsPerServer: server.slotsPerServer,
-    });
+    }));
     return (await ctx.db.get("jgServerCapacity", id));
 }
 /**
@@ -387,7 +388,7 @@ export async function applyLeaderboardIncrements(ctx, gameId, entries) {
             await ctx.db.patch(existing._id, { value: existing.value + entry.by, updatedAt: now });
         }
         else {
-            await ctx.db.insert("jgLeaderboardRows", {
+            await ctx.db.insert("jgLeaderboardRows", definedOnly({
                 gameId,
                 stat: entry.stat,
                 scope: entry.scope,
@@ -395,7 +396,7 @@ export async function applyLeaderboardIncrements(ctx, gameId, entries) {
                 userId: entry.userId,
                 value: entry.by,
                 updatedAt: now,
-            });
+            }));
         }
     }
 }
@@ -475,7 +476,8 @@ export async function persistServerSnapshot(ctx, server, snapshot, save) {
             await ctx.db.insert("jgWorldChunks", {
                 serverId: server._id,
                 chunkKey: chunk.chunkKey,
-                ...chunkPatch,
+                snapshot: chunk.snapshot,
+                updatedAt: chunk.updatedAt,
             });
         }
     }
@@ -582,10 +584,10 @@ export function createGameServerFunctions(options) {
             const serverId = await ctx.db.insert("jgGameServers", {
                 gameId: args.gameId,
                 status: "running",
-                mode: args.mode,
+                ...(args.mode === undefined ? {} : { mode: args.mode }),
                 modeConfig: args.modeConfig,
                 visibility: args.visibility ?? "public",
-                joinCode: args.joinCode,
+                ...(args.joinCode === undefined ? {} : { joinCode: args.joinCode }),
                 topology: shared ? "shared" : "rooms",
                 memberCount: 0,
                 memberUserIds: [],
@@ -930,7 +932,7 @@ export function createGameServerFunctions(options) {
                 _id: server._id,
                 gameId: server.gameId,
                 status: server.status,
-                mode: server.mode,
+                ...(server.mode === undefined ? {} : { mode: server.mode }),
                 memberUserIds: server.memberUserIds,
                 slotsPerServer: server.slotsPerServer,
                 save: server.save,
@@ -958,7 +960,7 @@ export function createGameServerFunctions(options) {
             memberCount: v.number(),
             slotsPerServer: v.number(),
         }), v.null()),
-        handler: (ctx, args) => withMember(ctx, mode, args, null, async (server) => ({
+        handler: (ctx, args) => withMember(ctx, mode, args, null, async (server) => definedOnly({
             _id: server._id,
             gameId: server.gameId,
             status: server.status,
@@ -983,10 +985,10 @@ export function createGameServerFunctions(options) {
                 const member = await ctx.db.query("jgServerMembers").withIndex("by_server_and_user", q => q.eq("serverId", args.serverId).eq("userId", actor)).unique();
                 if (!member)
                     return null;
-                return { _id: capacity.serverId, gameId: capacity.gameId, status: capacity.status, mode: capacity.mode, memberCount: capacity.memberCount, slotsPerServer: capacity.slotsPerServer };
+                return definedOnly({ _id: capacity.serverId, gameId: capacity.gameId, status: capacity.status, mode: capacity.mode, memberCount: capacity.memberCount, slotsPerServer: capacity.slotsPerServer });
             }
             const server = await requireServerMember(ctx, args.serverId, actor);
-            return server ? { _id: server._id, gameId: server.gameId, status: server.status, mode: server.mode, memberCount: server.memberUserIds.length, slotsPerServer: server.slotsPerServer } : null;
+            return server ? definedOnly({ _id: server._id, gameId: server.gameId, status: server.status, mode: server.mode, memberCount: server.memberUserIds.length, slotsPerServer: server.slotsPerServer }) : null;
         },
     });
     /**
@@ -1125,7 +1127,7 @@ export function createGameServerFunctions(options) {
             return Promise.all(rows
                 .filter((row) => isListablePublicly(row.visibility))
                 .slice(0, limit)
-                .map(async (row) => ({
+                .map(async (row) => definedOnly({
                 _id: row._id,
                 status: row.status,
                 memberCount: (await serverCapacity(ctx, row))?.memberCount ?? row.memberCount ?? row.memberUserIds.length,
@@ -1327,7 +1329,7 @@ export function createPresenceFunctions(options) {
                 }
                 return rows
                     .filter((row) => row.revokedAt === undefined && row.updatedAt >= threshold)
-                    .map((row) => ({
+                    .map((row) => definedOnly({
                     userId: row.userId,
                     sessionId: row.sessionId,
                     kind: row.kind,
@@ -1550,7 +1552,7 @@ export async function sendChatMessage(ctx, args) {
     const gate = await rateLimit(ctx, { key: JSON.stringify(["chat", args.serverId, args.userId]), windowMs: args.minIntervalMs ?? 2000, max: 1 });
     if (!gate.ok)
         return { ok: false, reason: "rate_limited" };
-    await ctx.db.insert("jgChatMessages", { serverId: args.serverId, channelId: args.channelId ?? "global", userId: args.userId, body: validation.text, authorName: args.authorName, at: Date.now() });
+    await ctx.db.insert("jgChatMessages", definedOnly({ serverId: args.serverId, channelId: args.channelId ?? "global", userId: args.userId, body: validation.text, authorName: args.authorName, at: Date.now() }));
     return { ok: true };
 }
 /**
@@ -1664,8 +1666,8 @@ export function createChatFunctions(options) {
                 .withIndex("by_server_channel", (q) => q.eq("serverId", args.serverId).eq("channelId", args.channelId))
                 .order("desc")
                 .take(historyLimit * 2 + 16);
-            for (let i = historyLimit * 2; i < recent.length; i += 1) {
-                await ctx.db.delete(recent[i]._id);
+            for (const stale of recent.slice(historyLimit * 2)) {
+                await ctx.db.delete(stale._id);
             }
             return { ok: true };
         },

package/dist/worldPresence.d.ts

@@ -18,7 +18,7 @@ export interface WorldPresenceRecord extends PresenceResidentRow {
     rotationY: number;
     rotationPitch: number;
     lastSeenAt: number;
-    lastWorldSnapshotAt?: number;
+    lastWorldSnapshotAt?: number | undefined;
 }
 /** World chunk size and host-owned pose, checkpoint and retention policies. */
 export interface WorldPresenceOptions {

package/dist/worldPresence.js

@@ -1,3 +1,4 @@
+import { definedOnly } from "@jgengine/core/data/definedOnly";
 import { DEFAULT_POSE_SYNC_RULES, decidePoseSync, shouldPersistWorldSnapshot } from "@jgengine/core/multiplayer/presenceModel";
 import { chunkKeyAt, chunkKeysAround, parseChunkKey, DEFAULT_CHUNK_SIZE } from "@jgengine/core/runtime/worldChunks";
 function record(row) {
@@ -47,7 +48,7 @@ export function createWorldPresenceStore(options = {}) {
                 label: args.label ?? existing?.label, x: args.position.x, y: args.position.y, z: args.position.z,
                 rotationY: 0, rotationPitch: 0, chunkKey: chunkKeyAt([args.position.x, args.position.y, args.position.z], size),
                 updatedAt: nowMs, revokedAt: undefined };
-            const id = existing ? existing._id : await ctx.db.insert("jgPoses", patch);
+            const id = existing ? existing._id : await ctx.db.insert("jgPoses", definedOnly(patch));
             if (existing)
                 await ctx.db.patch(id, patch);
             return record((await ctx.db.get("jgPoses", id)));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/convex",
-  "version": "0.49.1",
+  "version": "0.50.0",
   "description": "Convex adapters for JGengine: game transport, presence transport, and backend wiring over @jgengine/core.",
   "license": "Apache-2.0",
   "type": "module",
@@ -30,7 +30,7 @@
     "check-types": "tsgo --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@jgengine/core": "^0.49.1"
+    "@jgengine/core": "^0.50.0"
   },
   "peerDependencies": {
     "convex": "^1.31.2",

package/skills/jgengine/SKILL.md

@@ -7,7 +7,7 @@ description: Route game work to the smallest useful JGengine guidance set.
 
 This skill decides what to load; it is not an engine manual. Package map, commands, layering, and license live in the JGengine README (repo-root [`README.md`](../../../README.md) in the monorepo, [jgengine.com](https://jgengine.com) from a created project); open it when you need one of those facts.
 
-A created project installs only `jgengine`, `jgengine-editor`, `jgengine-verify`, `game-design`, and `jgengine-ui`. Run `npx jgengine skills -p --all` before loading any other domain named below. Those projects do not ship `api.md`; read exact signatures from the `.d.ts` files under `node_modules/@jgengine/<pkg>/dist/`.
+A created project installs only `jgengine`, `create-game-jg`, `jgengine-editor`, `jgengine-verify`, `game-design`, and `jgengine-ui`. Run `npx jgengine skills -p --all` before loading any other domain named below. Those projects do not ship `api.md`; read exact signatures from the `.d.ts` files under `node_modules/@jgengine/<pkg>/dist/`.
 
 Created projects pin their scaffolding CLI as a local devDependency, separately from SDK versions. Run `npx jgengine doctor` after SDK upgrades to check CLI compatibility. Skill installation preserves newer or differing unversioned copies; update the project CLI first, and use `skills -p --force` only when replacement is intended. Each packaged skill install records its CLI and SDK versions in `.jgengine-version.json`.
 
@@ -27,7 +27,7 @@ finished solution.
 
 ## 1. Establish the target
 
-Before building a game or a big feature, plan it: `npx jgengine plan <game> --brief "<brief>"` writes `PLAN.md`; list every feature the brief implies under `## Features` and run `npx jgengine plan <game>` again to fill each feature's engine owner and the gaps; then order `## Milestones`, one PR each, and tick each as it lands. For greenfield builds, also write `src/art-direction.md` before any code.
+A new game or a big new feature starts with the `create-game-jg` skill: agree the direction with the user, map every feature with `jgengine has`, write `PLAN.md` with its design brief, then `jgengine create` and build it one milestone per PR, each the next 10 minutes of play. Load it before anything below.
 
 Treat the pitch as a unique composition of needs, not a genre to fill in — never reach for a genre kit, preset, archetype, or class template ("default sports car", "default RPG", "default FPS") in the SDK or skills (see [AGENTS.md](../../../AGENTS.md)). Use `game-design` to turn the pitch into a testable player promise, verbs, loops, progression, failure, and completion scenario. Use `level-design` when play depends on authored spaces, routes, encounters, exploration, or spatial pacing. Capture only decisions that change architecture:
 
@@ -38,7 +38,7 @@ 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 --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 adoption debt and boot probes). 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.
+Start a game only through `create-game-jg` (it picks the template and runs `jgengine create`); never copy `games/*`. The game's `jgengine.json` says what it is and uses (template, editor, `@jgengine` packages, and in-repo its adoption debt and boot probes). 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@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.
 

package/skills/jgengine/api.md

@@ -6,7 +6,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.49.1" — Installed `@jgengine/core` semver - compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.50.0" — Installed `@jgengine/core` semver - compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/authoring
 
@@ -277,6 +277,7 @@
 ## @jgengine/core/devtools/frameBreakdown
 
 - `DrawCost` (interface): interface DrawCost — One object or material's share of the draws: totals while gathering, per-frame averages in a summary.
+- `FrameBreakdown` (interface): interface FrameBreakdown — A running breakdown, as `installFrameBreakdown` returns it and `window.__jgFrameBreakdown` holds it.
 - `FrameBreakdownRecord` (interface): interface FrameBreakdownRecord — One frame, as the hooks saw it. GPU times arrive a few frames late; `gpu` is null until they do.
 - `FrameBreakdownSummary` (interface): interface FrameBreakdownSummary — A window of frames, summarized for a person or a diff.
 - `HITCH_MS` (const): const HITCH_MS: 33 — Where each frame goes: the record of one frame (CPU per system, GPU per render pass, draws, shader compiles, uploads, heap) and the summary of a window of them (percentiles, the costliest systems, passes, objects and materials, and every hitch with what caused it). This file is the arithmetic; `frameBreakdown.draw.ts` fills the records from a live renderer.
@@ -286,9 +287,6 @@
 
 ## @jgengine/core/devtools/frameBreakdown.draw
 
-- `BreakdownRenderer` (interface): interface BreakdownRenderer — What the breakdown needs from a three.js WebGLRenderer.
-- `BreakdownStore` (interface): interface BreakdownStore — What it needs from the r3f store: the subscriber list and the subscribe call.
-- `FrameBreakdown` (interface): interface FrameBreakdown — A running breakdown.
 - `measureComposerPasses` (function): function measureComposerPasses(composer: { passes: readonly object[] }): void — Time each post pass of a composer by name, CPU and GPU. Cheap when no breakdown is installed; call it each frame before `composer.render` so passes added later are timed too.
 
 ## @jgengine/core/devtools/frameSampler.view
@@ -438,7 +436,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.49.1" — Installed `@jgengine/core` semver - compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.50.0" — Installed `@jgengine/core` semver - compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/runtime/adapter
 
@@ -576,7 +574,7 @@
 ## @jgengine/core/runtime/hostPersistence
 
 - `FEED_RING_LIMIT` (const): const FEED_RING_LIMIT: 20 — ⚠ undocumented
-- `GameServerRecord` (type): type GameServerRecord = { serverId: string; gameId: string; status: GameServerStatus; mode?: string; modeConfig?: unknown; label?: string; visibility?: SessionVisibility; joinCode?: string; tags?: string[]; memberUserIds: string[]; slotsPerServer: number; save: SaveConfig; serverState: RuntimeServer… — ⚠ undocumented
+- `GameServerRecord` (type): type GameServerRecord = { serverId: string; gameId: string; status: GameServerStatus; mode?: string | undefined; modeConfig?: unknown; label?: string; visibility?: SessionVisibility | undefined; joinCode?: string | undefined; tags?: string[]; memberUserIds: string[]; slotsPerServer: number; save: Sa… — ⚠ undocumented
 - `GameServerStatus` (type): type GameServerStatus = "open" | "running" | "closed" — ⚠ undocumented · used by `statusAfterLeave` (@jgengine/core/runtime/hostPolicy): Status after a leave: empty rooms reopen; non-empty rooms keep their current status.
 - `HostPersistence` (type): type HostPersistence = { savePlan?: (plan: ServerPersistPlan) => Promise<void>; resetScenario?: (reset: NormalizedScenarioReset) => Promise<void>; loadServer: (serverId: string) => Promise<GameServerRecord | null>; saveServer: (record: GameServerRecord) => Promise<void>; listServers: (gameId: string… — ⚠ undocumented · used by `memoryPersistence` (@jgengine/node): Creates an in-memory `HostPersistence` implementation, useful for tests and ephemeral hosts.
 - `LEADERBOARD_PENDING_KEY` (const): const LEADERBOARD_PENDING_KEY: "leaderboardPending" — ⚠ undocumented
@@ -750,7 +748,7 @@
 - `GameRuntimeFeeds` (type): type GameRuntimeFeeds = { subscribeServer: ( serverId: string, onChange: (view: GameRuntimeServerView | null) => void, ) => FeedUnsubscribe; subscribePlayer: ( args: { serverId: string }, onChange: (view: GameRuntimePlayerView | null) => void, ) => FeedUnsubscribe; subscribeFeed: ( args: { serverId:… — ⚠ undocumented
 - `GameRuntimePlayerView` (type): type GameRuntimePlayerView = { userId: string; gameId: string; playerState: unknown; updatedAt: number; } — ⚠ undocumented
 - `GameRuntimeServerView` (type): type GameRuntimeServerView = { serverId: string; gameId: string; revision: number; memberUserIds: string[]; serverState: unknown | WorldSyncFrame; updatedAt: number; } — ⚠ undocumented
-- `GameRuntimeTransport` (type): type GameRuntimeTransport = { /** * Join a server. `sessionId` names this client session (one tab, one mounted view) so the host keeps * the user a member while any of their sessions is still live. */ joinServer: (args: { gameId: string; serverId?: string; role?: MultiplayerRole; sessionId?: string … — ⚠ undocumented · used by `useServerSession` (@jgengine/core/session/useServerSession.view): Joins a host and exposes a retryable blocking state until membership is confirmed.
+- `GameRuntimeTransport` (type): type GameRuntimeTransport = { /** * Join a server. `sessionId` names this client session (one tab, one mounted view) so the host keeps * the user a member while any of their sessions is still live. */ joinServer: (args: { gameId: string; serverId?: string | undefined; role?: MultiplayerRole; session… — ⚠ undocumented · used by `useServerSession` (@jgengine/core/session/useServerSession.view): Joins a host and exposes a retryable blocking state until membership is confirmed.
 - `JoinServerOutcome` (type): type JoinServerOutcome = | (JoinServerResult & { ok: true }) | { ok: false; reason: "full" | "closed" | "unauthorized" } — Join failures are returned to the caller so the triggering surface can offer retry.
 - `JoinServerResult` (type): type JoinServerResult = { serverId: string; isNew: boolean; resumeTicket?: ResumeTicket; } — ⚠ undocumented
 - `LiveGameBackend` (type): type LiveGameBackend<TPresenceRow = unknown, TPresenceLocation = unknown, TGameId extends string = string> = GameBackend<TPresenceRow, TPresenceLocation, TGameId> & { presenceSync: PresenceSync; pushFeedEntry: (args: { serverId: string; action: string; entry: unknown }) => Promise<void>; chatSyncFor… — ⚠ undocumented

package/skills/jgengine-multiplayer/api.md

@@ -5,14 +5,14 @@
 ## @jgengine/convex
 
 - `ConvexBackend` (type): type ConvexBackend<TPresenceRow = unknown, TPresenceLocation = unknown, TGameId extends string = string> = LiveGameBackend<TPresenceRow, TPresenceLocation, TGameId> & { leaderboard: ConvexLeaderboardReads; } — ⚠ undocumented
-- `ConvexBackendOptions` (type): type ConvexBackendOptions<TRawPresenceRow extends { actorExternalId: string }, TPresenceRow> = { client: ConvexReactClient; gameId: string; userId: string; api?: ConvexGameApi; poseTuning?: PoseSyncTuning; presence?: { functions: ConvexPresenceFunctions; mapRow: (row: TRawPresenceRow) => TPresenceRo… — ⚠ undocumented
+- `ConvexBackendOptions` (type): type ConvexBackendOptions<TRawPresenceRow extends { actorExternalId: string }, TPresenceRow> = { client: ConvexReactClient; gameId: string; userId: string; api?: ConvexGameApi | undefined; poseTuning?: PoseSyncTuning | undefined; presence?: { functions: ConvexPresenceFunctions; mapRow: (row: TRawPre… — ⚠ undocumented
 - `ConvexChatFunctions` (interface): interface ConvexChatFunctions { messages: FunctionReference<"query">; sendMessage: FunctionReference<"mutation"> } — ⚠ undocumented · used by `createConvexChatTransport`: Wires a game's Convex chat functions into the engine's ChatTransport contract: one live query per subscribed channel (the channel's recent h…
-- `ConvexGameApi` (type): type ConvexGameApi = { runtime: { joinServer: FunctionReference< "mutation", "public", { gameId: string; serverId?: string; mode?: string; visibility?: "public" | "private"; joinCode?: string; externalId?: string; sessionId?: string; }, JoinServerOutcome >; leaveServer: FunctionReference<"mutation",… — ⚠ undocumented
+- `ConvexGameApi` (type): type ConvexGameApi = { runtime: { joinServer: FunctionReference< "mutation", "public", { gameId: string; serverId?: string | undefined; mode?: string; visibility?: "public" | "private"; joinCode?: string; externalId?: string | undefined; sessionId?: string; }, JoinServerOutcome >; leaveServer: Funct… — ⚠ undocumented
 - `ConvexGameClient` (type): type ConvexGameClient = Pick<ConvexReactClient, "mutation" | "watchQuery"> — Structural client seam avoids requiring the engine and game to share a class instance type.
 - `ConvexGameTransportConfig` (type): type ConvexGameTransportConfig = { gameId: string; userId?: string; } — ⚠ undocumented
 - `ConvexLeaderboardReads` (type): type ConvexLeaderboardReads = ReturnType<typeof createConvexLeaderboardReads> — ⚠ undocumented
 - `ConvexPresenceFunctions` (interface): interface ConvexPresenceFunctions — The Convex functions a **game** supplies for a world it owns: presence keyed by the game's own ids, including which residents exist while offline, which is game content and has no engine analogue. Not satisfied by `createPresenceFunctions` (`@jgengine/convex/server`) — that is the pose lane of a hosted `jgGameServers` server, backing `PresenceSync` rather than `PresenceTransport`.
-- `ConvexRunCommandArgs` (type): type ConvexRunCommandArgs = RunCommandArgs & { externalId?: string; /** * How much of the server to hydrate before applying the command. Overrides whatever the * {@link CommandDef} declares through its own `scope`; omit both to hydrate the whole world. */ scope?: LoadSnapshotScope; /** * Trusted hos… — Arguments of the `runCommand` mutation, and of the equivalent {@link GameServerHelpers.runCommand} helper.
+- `ConvexRunCommandArgs` (type): type ConvexRunCommandArgs = RunCommandArgs & { externalId?: string | undefined; /** * How much of the server to hydrate before applying the command. Overrides whatever the * {@link CommandDef} declares through its own `scope`; omit both to hydrate the whole world. */ scope?: LoadSnapshotScope; /** *… — Arguments of the `runCommand` mutation, and of the equivalent {@link GameServerHelpers.runCommand} helper.
 - `ConvexSaveBackendOptions` (interface): interface ConvexSaveBackendOptions — Config for {@link createConvexSaveBackend} — the Convex client, optional function refs (defaults to the `saves.*` convention), and an optional key `namespace`.
 - `ConvexSaveFunctions` (interface): interface ConvexSaveFunctions — 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.
 - `DEFAULT_CONVEX_POSE_RULES` (const): const DEFAULT_CONVEX_POSE_RULES: PoseSyncRules — ⚠ undocumented
@@ -62,7 +62,7 @@
 - `randomConvexPlayerId` (function): function randomConvexPlayerId(): string — ⚠ undocumented
 - `rateLimit` (function): function rateLimit(ctx: JGMutationCtx, args: { key: string; windowMs: number; max: number; nowMs?: number }): Promise<{ ok: boolean; retryAfterMs: number }> — Consume one request in a fixed rate window; concurrent callers serialize on the indexed key.
 - `recentChatMessages` (function): function recentChatMessages(ctx: { db: Pick<JGQueryCtx["db"], "query"> }, args: { serverId: string; channelId?: string; limit?: number }): Promise<{ _id: Id<"jgChatMessages">; _creationTime: number; authorName?: string | undefined; serverId: string; userId: string; channelId: string; body: string; a… — Bounded recent chat for a resolved server; authorization belongs to the calling query.
-- `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 — ⚠ undocumented
+- `resolveConvexMultiplayer` (function): function resolveConvexMultiplayer(args: { game: GameDefinition; gameId: string; url?: string | undefined; client?: ConvexReactClient; api?: ConvexGameApi; userId?: string; force?: boolean; feedActions?: string[]; poseTuning?: PoseSyncTuning; }): MultiplayerSession | null — ⚠ undocumented
 - `sendChatMessage` (function): function sendChatMessage(ctx: JGMutationCtx, args: { serverId: string; userId: string; body: string; channelId?: string; authorName?: string; maxBodyLength?: number; minIntervalMs?: number }): Promise<ChatSendOutcome> — Write validated chat in a host transaction after the caller resolves its actor and world.
 - `validateSlotsPerServer` (function): function validateSlotsPerServer(slotsPerServer: number, topology: "rooms" | "shared" = "rooms"): { ok: true } | { ok: false; reason: string } — Whether a `slotsPerServer` value is a capacity a single hosted server row can actually hold.
 - `watchConvexQuery` (function): function watchConvexQuery<TArgs extends DefaultFunctionArgs, TResult, TView>(client: ConvexGameClient, query: FunctionReference<"query", "public", TArgs, TResult>, args: TArgs, toView: (result: TResult) => TView, onChange: (view: TView) => void): () => void — ⚠ undocumented
@@ -87,13 +87,13 @@
 ## @jgengine/convex/createConvexBackend
 
 - `ConvexBackend` (type): type ConvexBackend<TPresenceRow = unknown, TPresenceLocation = unknown, TGameId extends string = string> = LiveGameBackend<TPresenceRow, TPresenceLocation, TGameId> & { leaderboard: ConvexLeaderboardReads; } — ⚠ undocumented
-- `ConvexBackendOptions` (type): type ConvexBackendOptions<TRawPresenceRow extends { actorExternalId: string }, TPresenceRow> = { client: ConvexReactClient; gameId: string; userId: string; api?: ConvexGameApi; poseTuning?: PoseSyncTuning; presence?: { functions: ConvexPresenceFunctions; mapRow: (row: TRawPresenceRow) => TPresenceRo… — ⚠ undocumented
+- `ConvexBackendOptions` (type): type ConvexBackendOptions<TRawPresenceRow extends { actorExternalId: string }, TPresenceRow> = { client: ConvexReactClient; gameId: string; userId: string; api?: ConvexGameApi | undefined; poseTuning?: PoseSyncTuning | undefined; presence?: { functions: ConvexPresenceFunctions; mapRow: (row: TRawPre… — ⚠ undocumented
 - `ConvexLeaderboardReads` (type): type ConvexLeaderboardReads = ReturnType<typeof createConvexLeaderboardReads> — ⚠ undocumented
 - `createConvexBackend` (function): function createConvexBackend<TRawPresenceRow extends { actorExternalId: string } = { actorExternalId: string }, TPresenceRow = unknown, TPresenceLocation = unknown, TGameId extends string = string>(options: ConvexBackendOptions<TRawPresenceRow, TPresenceRow>): ConvexBackend<TPresenceRow, TPresenceLo… — ⚠ undocumented
 
 ## @jgengine/convex/createConvexGameTransport
 
-- `ConvexGameApi` (type): type ConvexGameApi = { runtime: { joinServer: FunctionReference< "mutation", "public", { gameId: string; serverId?: string; mode?: string; visibility?: "public" | "private"; joinCode?: string; externalId?: string; sessionId?: string; }, JoinServerOutcome >; leaveServer: FunctionReference<"mutation",… — ⚠ undocumented
+- `ConvexGameApi` (type): type ConvexGameApi = { runtime: { joinServer: FunctionReference< "mutation", "public", { gameId: string; serverId?: string | undefined; mode?: string; visibility?: "public" | "private"; joinCode?: string; externalId?: string | undefined; sessionId?: string; }, JoinServerOutcome >; leaveServer: Funct… — ⚠ undocumented
 - `ConvexGameClient` (type): type ConvexGameClient = Pick<ConvexReactClient, "mutation" | "watchQuery"> — Structural client seam avoids requiring the engine and game to share a class instance type.
 - `ConvexGameTransportConfig` (type): type ConvexGameTransportConfig = { gameId: string; userId?: string; } — ⚠ undocumented
 - `createConvexChatSync` (function): function createConvexChatSync(client: ConvexGameClient, api: ConvexGameApi, config: ConvexGameTransportConfig, serverId: string): ChatSync — ⚠ undocumented
@@ -119,11 +119,11 @@
 ## @jgengine/convex/resolveConvexMultiplayer
 
 - `randomConvexPlayerId` (function): function randomConvexPlayerId(): string — ⚠ undocumented
-- `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 — ⚠ undocumented
+- `resolveConvexMultiplayer` (function): function resolveConvexMultiplayer(args: { game: GameDefinition; gameId: string; url?: string | undefined; client?: ConvexReactClient; api?: ConvexGameApi; userId?: string; force?: boolean; feedActions?: string[]; poseTuning?: PoseSyncTuning; }): MultiplayerSession | null — ⚠ undocumented
 
 ## @jgengine/convex/server
 
-- `ConvexRunCommandArgs` (type): type ConvexRunCommandArgs = RunCommandArgs & { externalId?: string; /** * How much of the server to hydrate before applying the command. Overrides whatever the * {@link CommandDef} declares through its own `scope`; omit both to hydrate the whole world. */ scope?: LoadSnapshotScope; /** * Trusted hos… — Arguments of the `runCommand` mutation, and of the equivalent {@link GameServerHelpers.runCommand} helper.
+- `ConvexRunCommandArgs` (type): type ConvexRunCommandArgs = RunCommandArgs & { externalId?: string | undefined; /** * How much of the server to hydrate before applying the command. Overrides whatever the * {@link CommandDef} declares through its own `scope`; omit both to hydrate the whole world. */ scope?: LoadSnapshotScope; /** *… — Arguments of the `runCommand` mutation, and of the equivalent {@link GameServerHelpers.runCommand} helper.
 - `DEFAULT_CONVEX_POSE_RULES` (const): const DEFAULT_CONVEX_POSE_RULES: PoseSyncRules — ⚠ undocumented
 - `DEFAULT_MAX_SERVERS_PER_TICK` (const): const DEFAULT_MAX_SERVERS_PER_TICK: 32 — How many running servers one `tickActiveServers` transaction may hydrate, tick, and persist.
 - `EnsureJoinedOutcome` (type): type EnsureJoinedOutcome = | { ok: true; serverId: GenericId<"jgGameServers">; isNew: boolean } | { ok: false; reason: "full" | "closed" | "unauthorized" } — Outcome of a join: the server joined and whether the player's profile was created, or why it was refused.
@@ -200,7 +200,7 @@
 - `createFeedWriteGate` (function): function createFeedWriteGate(allowedActions: readonly string[] = []): FeedWriteGate — ⚠ undocumented
 - `createLocalVoiceTransport` (function): function createLocalVoiceTransport(options?: { userId?: string }): { transport: VoiceTransport; participants(channelId: string): readonly VoiceParticipant[]; } — ⚠ undocumented
 - `createPoseSyncGate` (function): function createPoseSyncGate(tuning: PoseSyncTuning = DEFAULT_POSE_SYNC_TUNING): PoseSyncGate — ⚠ undocumented
-- `createPushToTalk` (function): function createPushToTalk(config?: { mode?: PushToTalkMode; onChange?: (transmitting: boolean) => void; }): PushToTalk — ⚠ undocumented
+- `createPushToTalk` (function): function createPushToTalk(config?: { mode?: PushToTalkMode | undefined; onChange?: (transmitting: boolean) => void; }): PushToTalk — ⚠ undocumented
 - `findByJoinCode` (function): function findByJoinCode(listings: readonly SessionListing[], code: string): SessionListing | null — ⚠ undocumented
 - `fromRuntimeObjectRow` (function): function fromRuntimeObjectRow(row: RuntimeObjectRow): SceneObject — Inverse of {@link toRuntimeObjectRow}: rebuild the live placed object a host persisted.
 - `normalizeJoinCode` (function): function normalizeJoinCode(code: string): string — ⚠ undocumented
@@ -286,7 +286,7 @@
 - `DEFAULT_FEED_ACTIONS` (const): const DEFAULT_FEED_ACTIONS: string[] — ⚠ undocumented
 - `PeerShellFactories` (interface): interface PeerShellFactories — Alternate peer factories for hosts that provide their own WebRTC implementation or transport pipe.
 - `ResolvePeerShellMultiplayerArgs` (interface): interface ResolvePeerShellMultiplayerArgs — Peer bootstrap options; passing a playable hosts its authoritative GameContext world.
-- `ResolveShellMultiplayerArgs` (type): type ResolveShellMultiplayerArgs = { game: GameDefinition; gameId: string; url?: string | undefined; userId?: string; force?: boolean; feedActions?: string[]; } — ⚠ undocumented
+- `ResolveShellMultiplayerArgs` (type): type ResolveShellMultiplayerArgs = { game: GameDefinition; gameId: string; url?: string | undefined; userId?: string | undefined; force?: boolean; feedActions?: string[]; } — ⚠ undocumented
 - `ShellMultiplayer` (type): type ShellMultiplayer = MultiplayerSession — ⚠ undocumented · used by `resolvePeerShellMultiplayer`: Opens a peer session.
 - `randomPlayerId` (function): function randomPlayerId(): string — ⚠ undocumented
 - `resolvePeerShellMultiplayer` (function): function resolvePeerShellMultiplayer(args: ResolvePeerShellMultiplayerArgs): Promise<ShellMultiplayer & { close: () => Promise<void> }> — Opens a peer session. With `playable`, one host runs the game loop and guests mirror its shared world. Await `close()` to finish authoritative persistence. Same-origin rooms use BroadcastChannel signaling.
@@ -319,7 +319,7 @@
 - `ActivePresenceResolution` (interface): interface ActivePresenceResolution<T> { active: T | null; extras: T[] } — ⚠ undocumented
 - `DEFAULT_POSE_SYNC_RULES` (const): const DEFAULT_POSE_SYNC_RULES: PoseSyncRules — Canonical client-authoritative pose-sync tuning shared by every host transport (WS, Convex).
 - `DEFAULT_SPAWN_ORIGIN` (const): const DEFAULT_SPAWN_ORIGIN: { readonly x: 0; readonly y: 0; readonly z: 0; } — ⚠ undocumented
-- `IncomingPose` (interface): interface IncomingPose { position: {x: number; z: number; y?: number}; rotationY?: number; rotationPitch?: number; appearance?: Record<string, string> } — ⚠ undocumented
+- `IncomingPose` (interface): interface IncomingPose { position: {x: number; z: number; y?: number}; rotationY?: number; rotationPitch?: number | undefined; appearance?: Record<string, string> } — ⚠ undocumented
 - `PoseSyncDecision` (interface): interface PoseSyncDecision { position: {x: number; y: number; z: number}; rotationY: number; rotationPitch: number; appearance?: Record<string, string> | undefined; changed: boolean; refreshKeepAlive: boolean } — ⚠ undocumented
 - `PoseSyncRules` (interface): interface PoseSyncRules { maxSpeed: number; minIntervalMs?: number; maxVerticalOffset: number; floorY?: number; minElapsedSec: number; maxElapsedSec: number; keepAliveRefreshMs: number } — ⚠ undocumented · used by `DEFAULT_POSE_SYNC_RULES`: Canonical client-authoritative pose-sync tuning shared by every host transport (WS, Convex).
 - `PresencePoseState` (interface): interface PresencePoseState { position: {x: number; y: number; z: number}; rotationY: number; rotationPitch?: number; lastSeenAtMs?: number; appearance?: Record<string, string> | undefined } — ⚠ undocumented
@@ -354,7 +354,7 @@
 - `VoiceRoute` (interface): interface VoiceRoute { fromUserId: string; channelId: string; gain: number } — ⚠ undocumented
 - `VoiceTransport` (interface): interface VoiceTransport — Signaling seam for voice: who is in a channel and which media stream descriptor they published. The media plane (WebRTC, SFU, or anything else that moves audio bytes) stays behind this seam, host-supplied — the engine never touches it. subscribers delivers the channel roster on every change, starting with the current roster.
 - `createLocalVoiceTransport` (function): function createLocalVoiceTransport(options?: { userId?: string }): { transport: VoiceTransport; participants(channelId: string): readonly VoiceParticipant[]; } — ⚠ undocumented
-- `createPushToTalk` (function): function createPushToTalk(config?: { mode?: PushToTalkMode; onChange?: (transmitting: boolean) => void; }): PushToTalk — ⚠ undocumented
+- `createPushToTalk` (function): function createPushToTalk(config?: { mode?: PushToTalkMode | undefined; onChange?: (transmitting: boolean) => void; }): PushToTalk — ⚠ undocumented
 
 ## @jgengine/core/runtime/worldProjection