@jgengine/node 0.10.0 → 0.12.0

package/dist/promotedAssetCatalog.js

@@ -0,0 +1,176 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { MODEL_EXT, assetIdFromRel, safeAssetFilename } from "./assetNaming.js";
+/**
+ * True when `dir` is an already-promoted game project: one whose assets resolve through a typed
+ * `src/game/assets.ts` catalog rather than a scanned model folder.
+ * @internal
+ */
+export function isPromotedProject(dir) {
+    return existsSync(join(dir, "src", "game", "assets.ts"));
+}
+/** Scans forward from `open` (index of `{` or `[`) to its matching close, respecting string literals. */
+function matchBracketSpan(source, open) {
+    const openCh = source[open];
+    const closeCh = openCh === "{" ? "}" : "]";
+    let depth = 0;
+    let quote = null;
+    for (let i = open; i < source.length; i++) {
+        const ch = source[i];
+        if (quote !== null) {
+            if (ch === "\\") {
+                i++;
+                continue;
+            }
+            if (ch === quote)
+                quote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'" || ch === "`") {
+            quote = ch;
+            continue;
+        }
+        if (ch === openCh)
+            depth++;
+        else if (ch === closeCh) {
+            depth--;
+            if (depth === 0)
+                return i;
+        }
+    }
+    throw new Error("promotedAssetCatalog: unbalanced brackets in assets.ts");
+}
+/** Serializes one extras entry as a `{ id, url, label }` object literal with stable key order. */
+function serializeEntry(extra) {
+    return `{ id: ${JSON.stringify(extra.id)}, url: ${JSON.stringify(extra.url)}, label: ${JSON.stringify(extra.label)} }`;
+}
+/**
+ * Adds or replaces one `extras` entry in a promoted game's `src/game/assets.ts` and returns the
+ * rewritten text. PURE and deterministic — it does not touch the filesystem.
+ *
+ * A bounded, non-AST transform: it locates the single `buildCatalog({ ... })` call by brace-depth
+ * scan, then upserts an id-keyed entry into that call's `extras: [ ... ]` array (creating the array
+ * when absent, collapsing it back to no `extras` when it would become empty). Re-import of the same
+ * id replaces its entry in place, so the transform is idempotent and never duplicates an id. If the
+ * source has zero or more than one `buildCatalog(` call it THROWS, so the caller falls back to the
+ * legacy folder-scan import rather than risk corrupting the file.
+ * @internal
+ */
+export function upsertCatalogExtra(source, extra) {
+    const callRe = /\bbuildCatalog\(\s*\{/g;
+    const matches = [...source.matchAll(callRe)];
+    if (matches.length !== 1) {
+        throw new Error(`promotedAssetCatalog: expected exactly one buildCatalog({...}) call, found ${matches.length}`);
+    }
+    const match = matches[0];
+    // Brace of the options object literal is the last char of the matched `buildCatalog(\s*{`.
+    const objOpen = match.index + match[0].length - 1;
+    const objClose = matchBracketSpan(source, objOpen);
+    const objBody = source.slice(objOpen, objClose + 1);
+    // Detect indentation of the object's first inner line to keep emitted code consistent.
+    const indentMatch = /\{\s*\n(\s+)\S/.exec(objBody);
+    const indent = indentMatch ? indentMatch[1] : "  ";
+    const extrasRe = /\bextras\s*:\s*\[/;
+    const extrasMatch = extrasRe.exec(objBody);
+    const entries = new Map();
+    if (extrasMatch) {
+        const arrOpenInObj = objBody.indexOf("[", extrasMatch.index);
+        const arrCloseInObj = matchBracketSpan(objBody, arrOpenInObj);
+        const arrInner = objBody.slice(arrOpenInObj + 1, arrCloseInObj);
+        // Parse each `{ ... }` object literal in the array via brace-depth scan + JSON.parse.
+        let cursor = 0;
+        while (cursor < arrInner.length) {
+            const braceOpen = arrInner.indexOf("{", cursor);
+            if (braceOpen === -1)
+                break;
+            const braceClose = matchBracketSpan(arrInner, braceOpen);
+            const literal = arrInner.slice(braceOpen, braceClose + 1);
+            const parsed = parseEntryLiteral(literal);
+            entries.set(parsed.id, parsed);
+            cursor = braceClose + 1;
+        }
+        entries.set(extra.id, extra);
+        const arrOpenAbs = objOpen + arrOpenInObj;
+        const arrCloseAbs = objOpen + arrCloseInObj;
+        // Collapse an emptied array back to no `extras` for clean reversibility. Unreachable via a plain
+        // import (we just added an entry), but keeps the transform's remove-symmetry intact.
+        if (entries.size === 0) {
+            return spliceOutExtras(source, objOpen + extrasMatch.index, arrCloseAbs);
+        }
+        const serialized = serializeArray([...entries.values()], indent);
+        return source.slice(0, arrOpenAbs) + serialized + source.slice(arrCloseAbs + 1);
+    }
+    // No extras yet: splice a fresh `extras: [ <entry> ],` right after the opening `{`.
+    entries.set(extra.id, extra);
+    const serialized = serializeArray([...entries.values()], indent);
+    const insertAt = objOpen + 1;
+    const insertion = `\n${indent}extras: ${serialized},`;
+    return source.slice(0, insertAt) + insertion + source.slice(insertAt);
+}
+/** Removes an `extras: [...]` declaration (and a trailing comma) so the object reverts cleanly. */
+function spliceOutExtras(source, declStartAbs, arrCloseAbs) {
+    let declEndAbs = arrCloseAbs + 1;
+    // Swallow a trailing comma after `]`.
+    if (source[declEndAbs] === ",")
+        declEndAbs++;
+    // Swallow leading whitespace/newline before the declaration.
+    let start = declStartAbs;
+    while (start > 0 && /[ \t]/.test(source[start - 1]))
+        start--;
+    if (source[start - 1] === "\n")
+        start--;
+    return source.slice(0, start) + source.slice(declEndAbs);
+}
+/** Serializes an extras array literal with one entry per indented line. */
+function serializeArray(entries, indent) {
+    if (entries.length === 0)
+        return "[]";
+    const inner = entries.map((e) => `${indent}  ${serializeEntry(e)},`).join("\n");
+    return `[\n${inner}\n${indent}]`;
+}
+/** Parses a `{ id, url, label }` object literal (unquoted keys) into a PromotedExtra via JSON. */
+function parseEntryLiteral(literal) {
+    // Quote bare identifier keys so JSON.parse accepts the source-literal form.
+    const jsonish = literal.replace(/([{,]\s*)([A-Za-z_$][\w$]*)(\s*:)/g, '$1"$2"$3');
+    const obj = JSON.parse(jsonish);
+    if (typeof obj.id !== "string" || typeof obj.url !== "string") {
+        throw new Error("promotedAssetCatalog: malformed extras entry");
+    }
+    return {
+        id: obj.id,
+        url: obj.url,
+        label: typeof obj.label === "string" ? obj.label : obj.id,
+    };
+}
+/** Reads the `basePath` string literal from a promoted `assets.ts`, defaulting to `/models`. */
+function readBasePath(source) {
+    const m = /\bbasePath\s*:\s*["'`]([^"'`]+)["'`]/.exec(source);
+    return m ? m[1] : "/models";
+}
+/**
+ * Persists an imported model into a promoted game's `public/` and registers a durable `extras`
+ * entry in its `src/game/assets.ts`, so the shipped game resolves the asset through its typed
+ * catalog. Copies the bytes under `public/<basePath>/imported/<safe>` and rewrites the catalog
+ * source via {@link upsertCatalogExtra}. Returns the same `{ id, url, label }` shape the folder-scan
+ * `importEditorAsset` returns — but the url is the shipped `public/` path, not the dev asset route.
+ * @internal
+ */
+export function importPromotedAsset(dir, filename, bytes) {
+    if (!MODEL_EXT.test(filename)) {
+        throw new Error(`unsupported asset file (expected .glb/.gltf): ${filename}`);
+    }
+    const assetsTsPath = join(dir, "src", "game", "assets.ts");
+    const source = readFileSync(assetsTsPath, "utf8");
+    const basePath = readBasePath(source);
+    const safe = safeAssetFilename(filename);
+    const publicSub = basePath.replace(/^\/+/, "");
+    const targetDir = join(dir, "public", publicSub, "imported");
+    mkdirSync(targetDir, { recursive: true });
+    writeFileSync(join(targetDir, safe), bytes);
+    const url = `${basePath.replace(/\/+$/, "")}/imported/${safe}`;
+    const id = assetIdFromRel(safe);
+    const label = safe;
+    const rewritten = upsertCatalogExtra(source, { id, url, label });
+    writeFileSync(assetsTsPath, rewritten);
+    return { id, url, label };
+}

package/dist/shutdown.d.ts

@@ -0,0 +1,23 @@
+/** A live signal listener installed by {@link installShutdownHook}; call `remove()` to uninstall it (tests, embedders opting out). */
+export interface ShutdownHook {
+    remove(): void;
+}
+/** Config for {@link installShutdownHook}. */
+export interface InstallShutdownHookOptions {
+    /** Signals to listen for; default `["SIGINT", "SIGTERM"]`. */
+    signals?: readonly NodeJS.Signals[];
+    /** Bound on how long `shutdown()` may run before the hook gives up and exits anyway; default 5000ms. */
+    timeoutMs?: number;
+    /** Called with `0` on a clean shutdown, `1` on error or timeout; default `process.exit`. Override in tests to avoid killing the test process. */
+    exit?: (code: number) => void;
+    /** Called when `shutdown()` rejects or times out; default logs to `console.error`. */
+    onError?: (error: unknown) => void;
+}
+/**
+ * Wires `SIGINT`/`SIGTERM` (or a custom signal list) to a clean-shutdown callback — e.g.
+ * `() => worldServer.close()` or `() => Promise.all([wsServer.close(), host.stop()])`. Bounded by
+ * `timeoutMs` so a stuck flush can't hang the process forever; idempotent — a second signal delivered
+ * mid-shutdown reuses the same in-flight run instead of flushing twice. Returns a {@link ShutdownHook}
+ * whose `remove()` uninstalls the listeners, for tests and embedders that want their own handling.
+ */
+export declare function installShutdownHook(shutdown: () => Promise<void> | void, options?: InstallShutdownHookOptions): ShutdownHook;

package/dist/shutdown.js

@@ -0,0 +1,50 @@
+const DEFAULT_SIGNALS = ["SIGINT", "SIGTERM"];
+const DEFAULT_TIMEOUT_MS = 5_000;
+/**
+ * Wires `SIGINT`/`SIGTERM` (or a custom signal list) to a clean-shutdown callback — e.g.
+ * `() => worldServer.close()` or `() => Promise.all([wsServer.close(), host.stop()])`. Bounded by
+ * `timeoutMs` so a stuck flush can't hang the process forever; idempotent — a second signal delivered
+ * mid-shutdown reuses the same in-flight run instead of flushing twice. Returns a {@link ShutdownHook}
+ * whose `remove()` uninstalls the listeners, for tests and embedders that want their own handling.
+ */
+export function installShutdownHook(shutdown, options = {}) {
+    const signals = options.signals ?? DEFAULT_SIGNALS;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const exit = options.exit ?? ((code) => process.exit(code));
+    const onError = options.onError ?? ((error) => console.error("shutdown failed:", error));
+    let inFlight = null;
+    function run() {
+        inFlight ??= (async () => {
+            let timer;
+            try {
+                await Promise.race([
+                    Promise.resolve(shutdown()),
+                    new Promise((_resolve, reject) => {
+                        timer = setTimeout(() => reject(new Error(`shutdown exceeded ${timeoutMs}ms`)), timeoutMs);
+                    }),
+                ]);
+                exit(0);
+            }
+            catch (error) {
+                onError(error);
+                exit(1);
+            }
+            finally {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+            }
+        })();
+        return inFlight;
+    }
+    function handler() {
+        void run();
+    }
+    for (const signal of signals)
+        process.on(signal, handler);
+    return {
+        remove() {
+            for (const signal of signals)
+                process.off(signal, handler);
+        },
+    };
+}

package/dist/worldServer.d.ts

@@ -1,12 +1,15 @@
 import type { GameDefinition } from "@jgengine/core/game/defineGame";
-import type { GameContextContent } from "@jgengine/core/runtime/gameContext";
+import type { GameContextContent, GameContextModels } from "@jgengine/core/runtime/gameContext";
 import type { ModelAssetRef } from "@jgengine/core/scene/assetCatalog";
 import { type WorldGameHost } from "@jgengine/ws/worldHost";
+import { type WorldPersistence } from "./persistence.js";
 import { type GameWsServer, type GameWsServerOptions } from "./wsServer.js";
 /** A game the world server can host — its authoritative {@link GameDefinition} and the content lookup a `GameContext` reads. */
 export interface HostedGameDefinition {
     game: GameDefinition<ModelAssetRef, unknown>;
     content: GameContextContent;
+    /** Render-model lookup for collider auto-fit — pass the same lookup the shell derives (`contextModels(playable)`) so the authoritative host resolves the hitboxes clients see. */
+    models?: GameContextModels;
 }
 /** Config for {@link createWorldGameServer}: how to resolve a game by id, the tick cadence, and the underlying ws-server/router options (minus `host`, which the server builds). */
 export interface WorldGameServerOptions extends Omit<GameWsServerOptions, "host"> {
@@ -14,6 +17,8 @@ export interface WorldGameServerOptions extends Omit<GameWsServerOptions, "host"
     resolveGame(gameId: string): HostedGameDefinition | null;
     /** Ticks per second for the real-clock loop {@link WorldGameServer.start} drives; default 30. Tests call {@link WorldGameServer.tick} manually instead. */
     tickHz?: number;
+    /** Where each hosted world's authoritative state persists; defaults to an isolated in-memory store per world (lost on exit). Inject a file/SQL/Convex-backed {@link WorldPersistence} to survive a redeploy or crash. */
+    persistence?: WorldPersistence;
 }
 /** A runnable ws host for GameContext worlds: {@link createWorldGameHost} + {@link createGameWsServer} + a tick loop, with a manual `tick(dt)` seam so a fake clock can drive it in tests. */
 export interface WorldGameServer {
@@ -25,7 +30,9 @@ export interface WorldGameServer {
     start(): void;
     /** Stop the tick interval (idempotent). */
     stop(): void;
-    /** Stop the tick loop and tear down the ws server. */
+    /** Force-persist every live world's current state via the injected {@link WorldPersistence} (idempotent — safe to call repeatedly). */
+    flush(): void;
+    /** Stop the tick loop, flush persistence, and tear down the ws server — the clean-shutdown path for a SIGINT/SIGTERM handler. */
     close(): Promise<void>;
     /** The bound ws port. */
     port(): number;

package/dist/worldServer.js

@@ -1,18 +1,28 @@
 import { createHostedWorldSession } from "@jgengine/core/runtime/hostedWorldSession";
 import { createWorldGameHost } from "@jgengine/ws/worldHost";
+import { memoryWorldPersistence } from "./persistence.js";
 import { createGameWsServer } from "./wsServer.js";
 const DEFAULT_TICK_HZ = 30;
 /** Build a {@link WorldGameServer} — one process hosting authoritative GameContext worlds over ws, ready for two-client play once {@link WorldGameServer.start} runs. */
 export function createWorldGameServer(options) {
-    const { resolveGame, tickHz = DEFAULT_TICK_HZ, ...serverOptions } = options;
+    const { resolveGame, tickHz = DEFAULT_TICK_HZ, persistence = memoryWorldPersistence(), ...serverOptions } = options;
     const clock = options.now ?? (() => Date.now());
+    const liveSessions = new Map();
     const host = createWorldGameHost({
         now: clock,
-        session: ({ gameId }) => {
+        session: ({ gameId, serverId }) => {
             const resolved = resolveGame(gameId);
             if (resolved === null)
                 return null;
-            return createHostedWorldSession({ definition: resolved.game, content: resolved.content, now: clock });
+            const session = createHostedWorldSession({
+                definition: resolved.game,
+                content: resolved.content,
+                now: clock,
+                store: persistence.store({ gameId, serverId }),
+                ...(resolved.models === undefined ? {} : { models: resolved.models }),
+            });
+            liveSessions.set(serverId, session);
+            return session;
         },
     });
     const ws = createGameWsServer({ ...serverOptions, host });
@@ -27,11 +37,16 @@ export function createWorldGameServer(options) {
             interval = null;
         }
     }
+    function flush() {
+        for (const session of liveSessions.values())
+            session.save();
+    }
     return {
         host,
         ws,
         tick,
         stop,
+        flush,
         port: ws.port,
         start() {
             if (interval !== null)
@@ -45,6 +60,7 @@ export function createWorldGameServer(options) {
         },
         async close() {
             stop();
+            flush();
             await ws.close();
         },
     };

package/dist/wsServer.d.ts

@@ -2,10 +2,22 @@ import type { Server as HttpServer } from "node:http";
 import { WebSocketServer } from "ws";
 import { type HostRouterOptions, type RewoundPosition } from "@jgengine/ws/hostRouter";
 export type { RewoundPosition };
+/** Default per-message payload cap (bytes) — `ws` closes the socket with 1009 past this. */
+export declare const DEFAULT_MAX_PAYLOAD_BYTES = 1048576;
+/** Default max concurrent sockets this server accepts before rejecting new ones. */
+export declare const DEFAULT_MAX_CONNECTIONS = 10000;
+/** Default ping/pong interval; a socket that misses one round-trip is terminated. */
+export declare const DEFAULT_HEARTBEAT_INTERVAL_MS = 30000;
 export type GameWsServerOptions = HostRouterOptions & {
     server?: HttpServer;
     port?: number;
     path?: string;
+    /** Per-message payload cap in bytes. Defaults to {@link DEFAULT_MAX_PAYLOAD_BYTES}. */
+    maxPayloadBytes?: number;
+    /** Max concurrent sockets accepted; connections beyond this are closed immediately. Defaults to {@link DEFAULT_MAX_CONNECTIONS}. */
+    maxConnections?: number;
+    /** Ping/pong heartbeat interval in ms; a socket that misses a round-trip is terminated. Defaults to {@link DEFAULT_HEARTBEAT_INTERVAL_MS}. */
+    heartbeatIntervalMs?: number;
 };
 export type GameWsServer = {
     wss: WebSocketServer;

package/dist/wsServer.js

@@ -1,11 +1,40 @@
 import { WebSocketServer } from "ws";
 import { createHostRouter } from "@jgengine/ws/hostRouter";
+/** Default per-message payload cap (bytes) — `ws` closes the socket with 1009 past this. */
+export const DEFAULT_MAX_PAYLOAD_BYTES = 1_048_576;
+/** Default max concurrent sockets this server accepts before rejecting new ones. */
+export const DEFAULT_MAX_CONNECTIONS = 10_000;
+/** Default ping/pong interval; a socket that misses one round-trip is terminated. */
+export const DEFAULT_HEARTBEAT_INTERVAL_MS = 30_000;
 export function createGameWsServer(options) {
     const router = createHostRouter(options);
+    const maxPayload = options.maxPayloadBytes ?? DEFAULT_MAX_PAYLOAD_BYTES;
+    const maxConnections = options.maxConnections ?? DEFAULT_MAX_CONNECTIONS;
+    const heartbeatIntervalMs = options.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
     const wss = options.server !== undefined
-        ? new WebSocketServer({ server: options.server, path: options.path })
-        : new WebSocketServer({ port: options.port ?? 0, path: options.path });
+        ? new WebSocketServer({ server: options.server, path: options.path, maxPayload })
+        : new WebSocketServer({ port: options.port ?? 0, path: options.path, maxPayload });
+    const heartbeat = setInterval(() => {
+        for (const client of wss.clients) {
+            const socket = client;
+            if (socket.isAlive === false) {
+                socket.terminate();
+                continue;
+            }
+            socket.isAlive = false;
+            socket.ping();
+        }
+    }, heartbeatIntervalMs);
+    wss.on("close", () => clearInterval(heartbeat));
     wss.on("connection", (socket) => {
+        if (wss.clients.size > maxConnections) {
+            socket.close(1013, "Server at capacity");
+            return;
+        }
+        socket.isAlive = true;
+        socket.on("pong", () => {
+            socket.isAlive = true;
+        });
         const connection = router.connect({
             send: (data) => {
                 if (socket.readyState !== socket.OPEN)
@@ -28,6 +57,7 @@ export function createGameWsServer(options) {
         },
         rewind: router.rewind,
         close: () => new Promise((resolve) => {
+            clearInterval(heartbeat);
             router.close();
             for (const client of wss.clients) {
                 client.terminate();

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@jgengine/node",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Standalone authoritative game host for JGengine: in-memory server snapshots, tick loop, save-cadence flush, WebSocket server, memory/file persistence.",
-  "license": "AGPL-3.0-only",
+  "license": "Apache-2.0",
   "type": "module",
   "sideEffects": false,
   "repository": {
@@ -13,7 +13,7 @@
   "files": [
     "dist",
     "CHANGELOG.md",
-    "llms.txt"
+    "skills"
   ],
   "exports": {
     ".": {
@@ -31,11 +31,12 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@jgengine/core": "^0.10.0",
-    "@jgengine/ws": "^0.10.0",
+    "@jgengine/core": "^0.12.0",
+    "@jgengine/ws": "^0.12.0",
     "ws": "^8.18.0"
   },
   "devDependencies": {
+    "@jgengine/assets": "workspace:*",
     "@jgengine/sql": "workspace:*",
     "@types/node": "^24",
     "@types/ws": "^8",

package/skills/jgengine/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: jgengine
+description: Route game work to the smallest useful JGengine guidance set.
+---
+
+# JGengine intake and router
+
+Read the repository [README](../../../README.md) for package truth, commands, layering, and license. This skill decides what to load; it is not an engine manual.
+
+## 1. Establish the target
+
+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
+- world shape and authored content
+- core loop, interaction, combat, and progression
+- solo, local, hosted, or persistent multiplayer
+- HUD/menu states and **custom** UI art direction (every game owns its presentation — no stock drop-in 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/*`.
+
+## 2. Select domains
+
+Load only rows the target needs. Do not preload every domain.
+
+| Need | Skill | Owner |
+| --- | --- | --- |
+| player promise, pillars, verbs, loops, economy, progression, balance | `game-design` | experience and rule intent |
+| metrics, topology, encounters, navigation, spatial pacing | `level-design` | playable space intent |
+| scene placement, terrain painting, paths, asset authoring | `jgengine-editor` | editor document and authoring tools |
+| runtime world, movement, input, interaction, AI, navigation, audio | `jgengine-world` | spatial simulation and world runtime |
+| game state, systems, inventory, crafting, quests, economy, turns | `jgengine-gameplay` | non-combat rules and state |
+| targeting, stats, damage, effects, abilities, projectiles, loot | `jgengine-combat` | combat resolution |
+| HUD, menus, layout, accessibility, touch presentation | `jgengine-ui` | player-facing interface |
+| models, sprites, materials, audio files, source licensing | `jgengine-assets` | asset discovery and catalogs |
+| authority, transport, replication, sessions, host persistence | `jgengine-multiplayer` | network topology and persistence adapters |
+
+World content routes editor-first: any request that adds, moves, restyles, or removes something visible in the world — however phrased ("design this world", "place the enemies", "make it look better") — starts in `jgengine-editor`; the other domains consume the authored document. Scenes normally require both `jgengine-editor` for authoring and `jgengine-world` for runtime consumption. Combat and multiplayer are opt-in, not default intake.
+
+## 3. Discover before designing
+
+Within each selected domain:
+
+1. Search `capabilities.md` by intent; it maps needs to imports.
+2. Open `api.md` only when exact signatures or export inventory are needed.
+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.
+
+If no capability fits, identify the upstream package seam before writing game-local code. In this repository, implement a reusable primitive with its first adopter; if editor-owned content cannot be expressed, file the editor gap first.
+
+## 4. Build and finish
+
+Keep scene coordinates in the editor document, state serializable, randomness injected, and hot-path work bounded. Use `jgengine-verify` for evidence appropriate to the change. Inside this monorepo, `workflow` owns issue/PR completion. Visual polish work also uses the `jgengine-ui` quality reference.