@jgengine/convex 0.18.0 → 0.19.0

package/dist/territory.d.ts

@@ -0,0 +1,20 @@
+import { type GameRuntimeSnapshot } from "@jgengine/core/runtime/snapshot";
+import type { JGMutationCtx, JGDataModel } from "./server.js";
+import type { GenericQueryCtx } from "convex/server";
+type JGQueryCtx = GenericQueryCtx<JGDataModel>;
+/**
+ * Trusted host hydration for claim/bootstrap work; the caller checks access before invoking it.
+ * @capability territory-host-hydration Load an actor profile and bounded claim chunks for a host transaction.
+ */
+export declare function loadTerritoryState(ctx: JGQueryCtx | JGMutationCtx, args: {
+    serverId: string;
+    gameId: string;
+    userId: string;
+    chunkKeys: readonly string[];
+}): Promise<GameRuntimeSnapshot>;
+/**
+ * Persist dirty territory chunks and profiles in the caller's mutation, without a shared-server write.
+ * @capability territory-host-persistence Persist dirty ownership chunks and profiles without rewriting the shared server.
+ */
+export declare function persistTerritoryState(ctx: JGMutationCtx, snapshot: GameRuntimeSnapshot, nowMs?: number): Promise<void>;
+export {};

package/dist/territory.js

@@ -0,0 +1,47 @@
+import { createEmptyPlayerRow, createRuntimeSnapshot } from "@jgengine/core/runtime/snapshot";
+/**
+ * Trusted host hydration for claim/bootstrap work; the caller checks access before invoking it.
+ * @capability territory-host-hydration Load an actor profile and bounded claim chunks for a host transaction.
+ */
+export async function loadTerritoryState(ctx, args) {
+    const keys = [...new Set(args.chunkKeys)];
+    if (keys.length > 64)
+        throw new RangeError("Territory read exceeds 64 chunks");
+    const profile = await ctx.db.query("jgPlayerProfiles").withIndex("by_user_and_game", q => q.eq("userId", args.userId).eq("gameId", args.gameId)).unique();
+    const chunks = {};
+    for (const chunkKey of keys) {
+        const row = await ctx.db.query("jgWorldChunks").withIndex("by_server_and_chunk", q => q.eq("serverId", args.serverId).eq("chunkKey", chunkKey)).unique();
+        if (row)
+            chunks[chunkKey] = row.snapshot;
+    }
+    return createRuntimeSnapshot({ serverId: args.serverId, gameId: args.gameId, players: { [args.userId]: profile?.playerState ?? createEmptyPlayerRow(args.userId) }, chunks, revision: profile?.revision ?? 0 });
+}
+/**
+ * Persist dirty territory chunks and profiles in the caller's mutation, without a shared-server write.
+ * @capability territory-host-persistence Persist dirty ownership chunks and profiles without rewriting the shared server.
+ */
+export async function persistTerritoryState(ctx, snapshot, nowMs = Date.now()) {
+    for (const userId of snapshot.dirty.players) {
+        const playerState = snapshot.players[userId];
+        if (!playerState)
+            throw new Error("Dirty territory player was not hydrated");
+        const row = await ctx.db.query("jgPlayerProfiles").withIndex("by_user_and_game", q => q.eq("userId", userId).eq("gameId", snapshot.gameId)).unique();
+        if (row)
+            await ctx.db.patch(row._id, { playerState, revision: row.revision + 1, updatedAt: nowMs });
+        else
+            await ctx.db.insert("jgPlayerProfiles", { userId, gameId: snapshot.gameId, playerState, revision: 1, createdAt: nowMs, updatedAt: nowMs });
+    }
+    for (const chunkKey of snapshot.dirty.chunks) {
+        const chunk = snapshot.chunks[chunkKey];
+        const row = await ctx.db.query("jgWorldChunks").withIndex("by_server_and_chunk", q => q.eq("serverId", snapshot.serverId).eq("chunkKey", chunkKey)).unique();
+        if (!chunk) {
+            if (row)
+                await ctx.db.delete(row._id);
+            continue;
+        }
+        if (row)
+            await ctx.db.patch(row._id, { snapshot: chunk, updatedAt: nowMs });
+        else
+            await ctx.db.insert("jgWorldChunks", { serverId: snapshot.serverId, chunkKey, snapshot: chunk, updatedAt: nowMs });
+    }
+}

package/dist/worldPresence.d.ts

@@ -0,0 +1,68 @@
+import type { DocumentByName, GenericQueryCtx } from "convex/server";
+import type { JGDataModel, JGMutationCtx } from "./server.js";
+import { type IncomingPose, type PoseSyncRules } from "@jgengine/core/multiplayer/presenceModel";
+import type { PresencePosition, PresenceResidentRow } from "@jgengine/core/multiplayer/presenceContract";
+type ReadContext = {
+    db: Pick<GenericQueryCtx<JGDataModel>["db"], "get" | "query">;
+};
+type PoseRow = DocumentByName<JGDataModel, "jgPoses">;
+/** Normalized actor identity and pose read from an indexed jgPoses row. */
+export interface WorldPresenceRecord extends PresenceResidentRow {
+    _id: PoseRow["_id"];
+    serverId: string;
+    presenceId: string;
+    homeGameId: string;
+    kind: string;
+    label: string | null;
+    position: PresencePosition;
+    rotationY: number;
+    rotationPitch: number;
+    lastSeenAt: number;
+    lastWorldSnapshotAt?: number;
+}
+/** World chunk size and host-owned pose, checkpoint and retention policies. */
+export interface WorldPresenceOptions {
+    chunkSize?: number;
+    rules?: PoseSyncRules;
+    idleTimeoutMs?: number;
+    revokedTtlMs?: number;
+    snapshotIntervalMs?: number;
+}
+/** Persist game-owned last-position state when the host store requests a checkpoint. */
+export type PresenceSnapshotWriter = (presence: WorldPresenceRecord, nowMs: number) => Promise<void>;
+/** Indexed presence storage for hosts that own authentication, bot ownership and spawn policy.
+ * @capability world-presence-store indexed neighborhood presence with pose throttling and physical expiry
+ * Call only after resolving the actor and their world access; browser arguments are not trusted identities.
+ */
+export declare function createWorldPresenceStore(options?: WorldPresenceOptions): {
+    active: (ctx: ReadContext, actorExternalId: string, serverId?: string) => Promise<WorldPresenceRecord | null>;
+    ensure(ctx: JGMutationCtx, args: {
+        serverId: string;
+        actorExternalId: string;
+        homeGameId: string;
+        kind: string;
+        position: PresencePosition;
+        presenceId?: string;
+        label?: string;
+        ownerActorId?: string;
+    }, nowMs?: number): Promise<WorldPresenceRecord>;
+    sync(ctx: JGMutationCtx, presence: WorldPresenceRecord, incoming?: IncomingPose, args?: {
+        nowMs?: number;
+        rules?: PoseSyncRules;
+        onSnapshot?: PresenceSnapshotWriter;
+    }): Promise<WorldPresenceRecord>;
+    revoke(ctx: JGMutationCtx, presence: WorldPresenceRecord, onSnapshot?: PresenceSnapshotWriter, nowMs?: number): Promise<void>;
+    nearby(ctx: ReadContext, serverId: string, viewerChunkKey?: string, args?: {
+        rings?: number;
+        limit?: number;
+    }): Promise<WorldPresenceRecord[]>;
+    reap(ctx: JGMutationCtx, args?: {
+        nowMs?: number;
+        batchSize?: number;
+        onSnapshot?: PresenceSnapshotWriter;
+    }): Promise<{
+        reaped: number;
+        deleted: number;
+    }>;
+};
+export {};

package/dist/worldPresence.js

@@ -0,0 +1,128 @@
+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) {
+    return { _id: row._id, serverId: row.serverId, presenceId: row.sessionId ?? row.userId,
+        actorExternalId: row.userId, ownerActorId: row.ownerActorId,
+        homeGameId: row.homeGameId ?? "", kind: row.kind ?? "player", label: row.label ?? null,
+        position: { x: row.x, y: row.y, z: row.z }, rotationY: row.rotationY,
+        rotationPitch: row.rotationPitch, lastSeenAt: row.updatedAt, lastWorldSnapshotAt: row.lastWorldSnapshotAt };
+}
+function finitePose(position, rotationY, rotationPitch) {
+    for (const value of [position.x, position.z, position.y ?? 0, rotationY ?? 0, rotationPitch ?? 0]) {
+        if (!Number.isFinite(value))
+            throw new RangeError("Presence pose must be finite");
+    }
+}
+/** Indexed presence storage for hosts that own authentication, bot ownership and spawn policy.
+ * @capability world-presence-store indexed neighborhood presence with pose throttling and physical expiry
+ * Call only after resolving the actor and their world access; browser arguments are not trusted identities.
+ */
+export function createWorldPresenceStore(options = {}) {
+    const size = options.chunkSize ?? DEFAULT_CHUNK_SIZE;
+    const rules = options.rules ?? DEFAULT_POSE_SYNC_RULES;
+    const idle = options.idleTimeoutMs ?? 240_000;
+    const revokedTtl = options.revokedTtlMs ?? 600_000;
+    const snapshotInterval = options.snapshotIntervalMs ?? 30_000;
+    if (!Number.isFinite(size) || size <= 0 || !Number.isFinite(idle) || idle < 1 ||
+        !Number.isFinite(revokedTtl) || revokedTtl < 0 || !Number.isFinite(snapshotInterval) || snapshotInterval < 0)
+        throw new RangeError("Invalid world presence policy");
+    async function active(ctx, actorExternalId, serverId) {
+        const rows = serverId === undefined
+            ? await ctx.db.query("jgPoses").withIndex("by_user", q => q.eq("userId", actorExternalId)).take(32)
+            : await ctx.db.query("jgPoses").withIndex("by_server_and_user", q => q.eq("serverId", serverId).eq("userId", actorExternalId)).take(32);
+        const live = rows.filter(row => row.revokedAt === undefined).sort((a, b) => b.updatedAt - a.updatedAt)[0];
+        return live ? record(live) : null;
+    }
+    return {
+        active,
+        async ensure(ctx, args, nowMs = Date.now()) {
+            finitePose(args.position);
+            const rows = await ctx.db.query("jgPoses").withIndex("by_server_and_user", q => q.eq("serverId", args.serverId).eq("userId", args.actorExternalId)).take(32);
+            const existing = rows.filter(row => row.revokedAt === undefined).sort((a, b) => b.updatedAt - a.updatedAt)[0];
+            for (const row of rows)
+                if (row._id !== existing?._id)
+                    await ctx.db.delete(row._id);
+            const patch = { serverId: args.serverId, userId: args.actorExternalId, sessionId: args.presenceId ?? args.actorExternalId,
+                homeGameId: args.homeGameId, kind: args.kind, ownerActorId: args.ownerActorId,
+                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);
+            if (existing)
+                await ctx.db.patch(id, patch);
+            return record((await ctx.db.get("jgPoses", id)));
+        },
+        async sync(ctx, presence, incoming, args = {}) {
+            const nowMs = args.nowMs ?? Date.now();
+            if (incoming)
+                finitePose(incoming.position, incoming.rotationY, incoming.rotationPitch);
+            const current = await ctx.db.get("jgPoses", presence._id);
+            if (!current || current.revokedAt !== undefined)
+                return presence;
+            const currentRecord = record(current);
+            const decision = decidePoseSync({ position: currentRecord.position, rotationY: current.rotationY,
+                rotationPitch: current.rotationPitch, lastSeenAtMs: current.updatedAt }, incoming ?? { position: currentRecord.position }, args.rules ?? rules, nowMs);
+            const next = { ...currentRecord, position: decision.position, rotationY: decision.rotationY, rotationPitch: decision.rotationPitch };
+            const patch = {};
+            if (decision.changed)
+                Object.assign(patch, { x: next.position.x, y: next.position.y, z: next.position.z,
+                    chunkKey: chunkKeyAt([next.position.x, next.position.y, next.position.z], size), rotationY: next.rotationY, rotationPitch: next.rotationPitch });
+            if (decision.changed || decision.refreshKeepAlive) {
+                patch.updatedAt = nowMs;
+                next.lastSeenAt = nowMs;
+            }
+            if (args.onSnapshot && shouldPersistWorldSnapshot(current.lastWorldSnapshotAt, nowMs, snapshotInterval)) {
+                await args.onSnapshot(next, nowMs);
+                patch.lastWorldSnapshotAt = nowMs;
+                next.lastWorldSnapshotAt = nowMs;
+            }
+            if (Object.keys(patch).length)
+                await ctx.db.patch(current._id, patch);
+            return next;
+        },
+        async revoke(ctx, presence, onSnapshot, nowMs = Date.now()) {
+            const row = await ctx.db.get("jgPoses", presence._id);
+            if (!row || row.revokedAt !== undefined)
+                return;
+            if (onSnapshot)
+                await onSnapshot(record(row), nowMs);
+            await ctx.db.patch(row._id, { revokedAt: nowMs, updatedAt: nowMs });
+        },
+        async nearby(ctx, serverId, viewerChunkKey = "0,0", args = {}) {
+            const coord = parseChunkKey(viewerChunkKey);
+            if (!coord)
+                return [];
+            const requestedLimit = args.limit ?? 500;
+            if (!Number.isSafeInteger(requestedLimit) || requestedLimit < 1)
+                throw new RangeError("Invalid presence limit");
+            const limit = Math.min(1000, requestedLimit);
+            const rows = [];
+            for (const chunkKey of chunkKeysAround([coord.cx * size, 0, coord.cz * size], args.rings ?? 1, size)) {
+                const chunk = await ctx.db.query("jgPoses").withIndex("by_server_and_chunk", q => q.eq("serverId", serverId).eq("chunkKey", chunkKey)).take(limit - rows.length);
+                rows.push(...chunk.filter(row => row.revokedAt === undefined).map(record));
+                if (rows.length >= limit)
+                    break;
+            }
+            return rows;
+        },
+        async reap(ctx, args = {}) {
+            const nowMs = args.nowMs ?? Date.now();
+            const requestedBatch = args.batchSize ?? 200;
+            if (!Number.isFinite(nowMs) || !Number.isSafeInteger(requestedBatch) || requestedBatch < 1)
+                throw new RangeError("Invalid presence reaper batch");
+            const batchSize = Math.min(500, requestedBatch);
+            const rows = await ctx.db.query("jgPoses").withIndex("by_revoked_updated", q => q.eq("revokedAt", undefined).lt("updatedAt", nowMs - idle)).take(batchSize);
+            let reaped = 0;
+            for (const row of rows) {
+                if (args.onSnapshot)
+                    await args.onSnapshot(record(row), nowMs);
+                await ctx.db.delete(row._id);
+                reaped++;
+            }
+            const revoked = await ctx.db.query("jgPoses").withIndex("by_revoked", q => q.gte("revokedAt", 0).lte("revokedAt", nowMs - revokedTtl)).take(batchSize - reaped);
+            for (const row of revoked)
+                await ctx.db.delete(row._id);
+            return { reaped, deleted: reaped + revoked.length };
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/convex",
-  "version": "0.18.0",
+  "version": "0.19.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": "bun ../../scripts/check-types-preflight.ts && tsgo --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@jgengine/core": "^0.18.0"
+    "@jgengine/core": "^0.19.0"
   },
   "peerDependencies": {
     "convex": "^1.31.2",

package/skills/ce-handoff/SKILL.md

@@ -143,7 +143,7 @@ When sufficient, return a concise orientation: objective, progress, decisions, c
 
 ## JGengine notes
 
-- Multi-session engine work often spans `docs/plans/`, GitHub issues, and stacked PRs — point at those; do not paste full plan bodies.
+- Multi-session engine work spans GitHub issues and PRs — point at those; do not paste full plan bodies.
 - Prefer `bun run agent:bootstrap --check` status, branch names, and PR links as state anchors.
 - Local parallelism uses `.claude/worktrees/`; never invent `C:\tmp\…` Codex-shared trees.
-- Papercuts and durable process changes belong in `PAPERCUTS.md` / skills, not only the handoff.
+- Durable process changes belong in skills, not only the handoff.

package/skills/jgengine/SKILL.md

@@ -5,10 +5,14 @@ description: Route game work to the smallest useful JGengine guidance set.
 
 # JGengine intake and router
 
-Read the JGengine README for package truth, commands, layering, and license — the repo-root [`README.md`](../../../README.md) in the monorepo, or [jgengine.com](https://jgengine.com) from a scaffolded consumer project (where the relative link does not resolve). This skill decides what to load; it is not an engine manual.
+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/`.
 
 ## 1. Establish the target
 
+For greenfield builds, write `src/art-direction.md` before any code.
+
 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:
 
 - player point of view and controls
@@ -18,7 +22,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
 
-For a new in-repo game, scaffold with `bun run new:game "<id-or-title>"` (thin script alias for `jgengine create`, auto-detects the in-repo variant). Outside this monorepo, start with `npx jgengine create`; never copy `Games/*`.
+Pick the dimension first: `create` defaults to a 3D world (terrain, sky, player model, editor scene); a grid, card, tile, or other board game with no 3D scene takes `create --2d` (a `board` world drawn by GameUI over `@jgengine/core/puzzle/cellGrid`). For a new in-repo game, scaffold with `bun run new:game "<id-or-title>"` (thin script alias for `jgengine create`, auto-detects the in-repo variant). Outside this monorepo, start with `npx jgengine create`; never copy `Games/*`.
 
 For an existing game asked to pick up a new engine release ("jgengine published a new version, grab it"), run `npx jgengine upgrade` in the project first: it diffs installed `@jgengine/*` versions against the latest release and prints every Migrate step and Adopt-worthy addition in between (`--json` for structured output). Bump, migrate oldest-first, then work the Adopt lists instead of reconstructing the changelog by hand.
 
@@ -44,9 +48,9 @@ World content routes editor-first: any request that adds, moves, restyles, or re
 
 Within each selected domain:
 
-0. Fastest start for a common composition: `npx jgengine recipe <name>` prints a vetted, SDK-typechecked snippet (imports + wired code) for `combat-loop`, `boss-telegraph`, `loot`, `quest`, `coop-presence`, `third-person-camera`; `npx jgengine recipe` lists them. Copy that instead of reconning per-file.
-1. Search `capabilities.md` by intent; it maps needs to imports. Outside the monorepo (or before a domain skill is even loaded), `npx jgengine find <intent>` greps every shipped capability index at once and prints the primitive + import — reach for it the moment you're tempted to hand-roll a HUD window, inventory grid, paperdoll, hotkey listener, minimap, stat bar, or character motion. If you're writing a `z-index`, a `keydown` for a panel, a `<div>` inventory, or a limb bob, a shipped drop-in almost certainly exists (`usePanels`/`PanelHost`, `InventoryGrid`, `CharacterSheet`/`Paperdoll`, `PartMotionRig`, `EntityPreview`); games own the *skin*, not the re-derivation.
-2. Open `api.md` only when exact signatures or export inventory are needed.
+0. Fastest start for a common composition: `npx jgengine recipe <name>` prints a vetted, SDK-typechecked snippet (imports + wired code) (`combat-loop`, `loot`, `world-drops`, `click-target`, `ability-bar`, `hitscan-weapon`, `rolled-gear`, `enter-vehicle` and more); `npx jgengine recipe` lists them. Copy that instead of reconning per-file.
+1. Search capabilities by intent; do not read `capabilities.md` top to bottom. `npx jgengine find <intent>` searches every domain's index and every recipe at once, installed or not, and prints the primitive and its import (or the recipe to open); in the monorepo, `grep -i "<intent>" .claude/skills/*/capabilities.md` does the same. Search the moment you are tempted to hand-roll a HUD window, inventory grid, paperdoll, hotkey listener, minimap, stat bar, or character motion. A `z-index`, a `keydown` for a panel, a `<div>` inventory, or a limb bob almost certainly has a shipped drop-in (`usePanels`/`PanelHost`, `InventoryGrid`, `CharacterSheet`/`Paperdoll`, `PartMotionRig`, `EntityPreview`); games own the *skin*, not the re-derivation.
+2. Open `api.md` (monorepo) or the package `.d.ts` only when exact signatures are needed; grep it, never read it whole.
 3. Open the linked reference only for a deeper recipe or trap.
 4. For how several primitives wire into a running loop, read the domain's `recipes/` — connected, genre-free walkthroughs organized by composition seam; this skill's own [recipes/minimal-game.md](recipes/minimal-game.md) is the default whole-game walkthrough. Prefer a recipe over reading a game's source; the games under `Games/*` are not templates or references, and a hybrid game is just a different composition of the same primitives.