@jgengine/ws 0.10.0 → 0.11.0

package/dist/hostRouter.js

@@ -1,6 +1,7 @@
 import { decidePoseSync, spawnPresenceState } from "@jgengine/core/multiplayer/presenceModel";
 import { createPositionHistory } from "@jgengine/core/multiplayer/lagCompensation";
 import { createChatRateLimiter, DEFAULT_CHAT_BODY_LENGTH, DEFAULT_CHAT_HISTORY_LIMIT, DEFAULT_CHAT_RATE_LIMIT, } from "@jgengine/core/game/chat";
+import { createCommandMiddleware, } from "./commandMiddleware.js";
 import { decodeWsClientMessage, encodeWsMessage, inspectWsDecodeFailure, subscriptionKey, } from "./protocol.js";
 export const DEFAULT_POSE_RULES = {
     maxSpeed: 12,
@@ -9,6 +10,8 @@ export const DEFAULT_POSE_RULES = {
     maxElapsedSec: 0.5,
     keepAliveRefreshMs: 10_000,
 };
+/** Cap on frames queued behind a connection's in-flight message; beyond this a flood gets rejected instead of piling up unbounded promises. */
+export const MAX_QUEUED_MESSAGES = 64;
 function appearanceEqual(a, b) {
     if (a === b)
         return true;
@@ -30,6 +33,29 @@ export function createHostRouter(options) {
         (allowAnonymous ? ({ userId }) => userId : null);
     const connections = new Set();
     const sessionsByUserId = new Map();
+    const subscribers = new Map();
+    const subscribersOf = (key) => {
+        const set = subscribers.get(key);
+        return set === undefined ? [] : [...set];
+    };
+    const addSubscription = (connection, key) => {
+        connection.subscriptions.add(key);
+        let set = subscribers.get(key);
+        if (set === undefined) {
+            set = new Set();
+            subscribers.set(key, set);
+        }
+        set.add(connection);
+    };
+    const removeSubscription = (connection, key) => {
+        connection.subscriptions.delete(key);
+        const set = subscribers.get(key);
+        if (set === undefined)
+            return;
+        set.delete(connection);
+        if (set.size === 0)
+            subscribers.delete(key);
+    };
     const presence = new Map();
     const positionHistoryMs = options.positionHistoryMs ?? 1_000;
     const histories = new Map();
@@ -65,13 +91,35 @@ export function createHostRouter(options) {
     };
     const broadcastPresence = (serverId) => {
         const key = subscriptionKey("presence", serverId);
+        const targets = subscribersOf(key);
+        if (targets.length === 0)
+            return;
         const data = presenceRows(serverId);
-        for (const connection of connections) {
-            if (!connection.subscriptions.has(key))
-                continue;
+        for (const connection of targets) {
             send(connection, { v: 1, t: "update", channel: "presence", serverId, data });
         }
     };
+    const commandMiddleware = createCommandMiddleware({
+        limits: options.limits,
+        authorize: options.authorize,
+        validate: options.validate,
+    });
+    const gate = async (connection, id, op, args = {}) => {
+        if (connection.userId === null)
+            return true;
+        const decision = await commandMiddleware.check({
+            connection,
+            userId: connection.userId,
+            op,
+            atMs: now(),
+            ...args,
+        });
+        if (!decision.allow) {
+            replyError(connection, id, decision.reason);
+            return false;
+        }
+        return true;
+    };
     const chatRings = new Map();
     const chatLimiter = createChatRateLimiter(options.chatRateLimit ?? DEFAULT_CHAT_RATE_LIMIT);
     const chatHistoryLimit = options.chatHistoryLimit ?? DEFAULT_CHAT_HISTORY_LIMIT;
@@ -88,10 +136,11 @@ export function createHostRouter(options) {
     };
     const broadcastChat = (serverId, channelId) => {
         const key = subscriptionKey("chat", serverId, channelId);
+        const targets = subscribersOf(key);
+        if (targets.length === 0)
+            return;
         const data = chatRing(serverId, channelId).slice();
-        for (const connection of connections) {
-            if (!connection.subscriptions.has(key))
-                continue;
+        for (const connection of targets) {
             send(connection, { v: 1, t: "update", channel: "chat", serverId, action: channelId, data });
         }
     };
@@ -108,10 +157,11 @@ export function createHostRouter(options) {
     const voiceParticipants = (serverId, channelId) => [...voiceRoster(serverId, channelId).values()].map((participant) => ({ ...participant }));
     const broadcastVoice = (serverId, channelId) => {
         const key = subscriptionKey("voice", serverId, channelId);
+        const targets = subscribersOf(key);
+        if (targets.length === 0)
+            return;
         const data = voiceParticipants(serverId, channelId);
-        for (const connection of connections) {
-            if (!connection.subscriptions.has(key))
-                continue;
+        for (const connection of targets) {
             send(connection, { v: 1, t: "update", channel: "voice", serverId, action: channelId, data });
         }
     };
@@ -226,24 +276,25 @@ export function createHostRouter(options) {
         }
     };
     const onHostEvent = (event) => {
-        for (const connection of connections) {
-            if (connection.userId === null)
-                continue;
-            if (event.type === "server") {
-                if (connection.subscriptions.has(subscriptionKey("server", event.serverId))) {
-                    void pushSubscription(connection, "server", event.serverId);
-                }
+        if (event.type === "server") {
+            for (const connection of subscribersOf(subscriptionKey("server", event.serverId))) {
+                if (connection.userId === null)
+                    continue;
+                void pushSubscription(connection, "server", event.serverId);
             }
-            else if (event.type === "player") {
-                if (connection.userId === event.userId &&
-                    connection.subscriptions.has(subscriptionKey("player", event.serverId))) {
+        }
+        else if (event.type === "player") {
+            for (const connection of subscribersOf(subscriptionKey("player", event.serverId))) {
+                if (connection.userId === event.userId) {
                     void pushSubscription(connection, "player", event.serverId);
                 }
             }
-            else {
-                if (connection.subscriptions.has(subscriptionKey("feed", event.serverId, event.action))) {
-                    void pushSubscription(connection, "feed", event.serverId, event.action);
-                }
+        }
+        else {
+            for (const connection of subscribersOf(subscriptionKey("feed", event.serverId, event.action))) {
+                if (connection.userId === null)
+                    continue;
+                void pushSubscription(connection, "feed", event.serverId, event.action);
             }
         }
     };
@@ -251,6 +302,15 @@ export function createHostRouter(options) {
     const handlePose = async (connection, serverId, pose) => {
         if (connection.userId === null)
             return;
+        const gateDecision = await commandMiddleware.check({
+            connection,
+            userId: connection.userId,
+            op: "pose",
+            atMs: now(),
+            serverId,
+        });
+        if (!gateDecision.allow)
+            return;
         if (!(await host.isMember({ userId: connection.userId, serverId })))
             return;
         const rows = presence.get(serverId) ?? new Map();
@@ -335,17 +395,22 @@ export function createHostRouter(options) {
         try {
             switch (message.t) {
                 case "join": {
+                    if (!(await gate(connection, message.id, "join", { serverId: message.serverId })))
+                        return;
                     const result = await host.joinServer({
                         userId,
                         gameId: message.gameId,
                         serverId: message.serverId,
                         attributes: message.attributes,
+                        code: message.code,
                     });
                     connection.joinedServers.add(result.serverId);
                     reply(connection, message.id, result);
                     return;
                 }
                 case "joinByCode": {
+                    if (!(await gate(connection, message.id, "join", {})))
+                        return;
                     const result = await host.joinByCode({
                         userId,
                         gameId: message.gameId,
@@ -357,6 +422,8 @@ export function createHostRouter(options) {
                     return;
                 }
                 case "browse": {
+                    if (!(await gate(connection, message.id, "browse", {})))
+                        return;
                     const result = await host.browseServers({
                         gameId: message.gameId,
                         filter: message.filter,
@@ -374,6 +441,12 @@ export function createHostRouter(options) {
                     return;
                 }
                 case "runCommand": {
+                    if (!(await gate(connection, message.id, "runCommand", {
+                        serverId: message.serverId,
+                        command: message.command,
+                        input: message.input,
+                    })))
+                        return;
                     const result = await host.runCommand({
                         userId,
                         serverId: message.serverId,
@@ -398,6 +471,8 @@ export function createHostRouter(options) {
                     return;
                 }
                 case "voiceJoin": {
+                    if (!(await gate(connection, message.id, "voice", { serverId: message.serverId })))
+                        return;
                     if ((await requireMembership(connection, message.id, message.serverId)) === null)
                         return;
                     const participant = { userId };
@@ -409,6 +484,8 @@ export function createHostRouter(options) {
                     return;
                 }
                 case "voiceLeave": {
+                    if (!(await gate(connection, message.id, "voice", { serverId: message.serverId })))
+                        return;
                     if ((await requireMembership(connection, message.id, message.serverId)) === null)
                         return;
                     const roster = voiceRoster(message.serverId, message.channelId);
@@ -419,6 +496,8 @@ export function createHostRouter(options) {
                     return;
                 }
                 case "voicePublish": {
+                    if (!(await gate(connection, message.id, "voice", { serverId: message.serverId })))
+                        return;
                     if ((await requireMembership(connection, message.id, message.serverId)) === null)
                         return;
                     const participant = voiceRoster(message.serverId, message.channelId).get(userId);
@@ -439,13 +518,13 @@ export function createHostRouter(options) {
                         replyError(connection, message.id, "Not a member of this server");
                         return;
                     }
-                    connection.subscriptions.add(subscriptionKey(message.channel, message.serverId, message.action));
+                    addSubscription(connection, subscriptionKey(message.channel, message.serverId, message.action));
                     reply(connection, message.id, null);
                     await pushSubscription(connection, message.channel, message.serverId, message.action);
                     return;
                 }
                 case "unsubscribe": {
-                    connection.subscriptions.delete(subscriptionKey(message.channel, message.serverId, message.action));
+                    removeSubscription(connection, subscriptionKey(message.channel, message.serverId, message.action));
                     reply(connection, message.id, null);
                     return;
                 }
@@ -473,30 +552,40 @@ export function createHostRouter(options) {
                 subscriptions: new Set(),
                 joinedServers: new Set(),
                 queue: Promise.resolve(),
+                queuedMessages: 0,
             };
             connections.add(connection);
             return {
                 handleRaw: (raw) => {
-                    connection.queue = connection.queue
-                        .then(async () => {
-                        const text = typeof raw === "string" ? raw : String(raw);
-                        const message = decodeWsClientMessage(text);
-                        if (message === null) {
-                            const failure = inspectWsDecodeFailure(text);
-                            if (failure.id !== undefined) {
-                                replyError(connection, failure.id, failure.reason);
-                            }
-                            return;
+                    const text = typeof raw === "string" ? raw : String(raw);
+                    const message = decodeWsClientMessage(text);
+                    if (message === null) {
+                        const failure = inspectWsDecodeFailure(text);
+                        if (failure.id !== undefined) {
+                            replyError(connection, failure.id, failure.reason);
                         }
-                        await handleMessage(connection, message);
-                    })
-                        .catch(() => undefined);
+                        return;
+                    }
+                    if (connection.queuedMessages >= MAX_QUEUED_MESSAGES) {
+                        if ("id" in message)
+                            replyError(connection, message.id, "Too many pending requests");
+                        return;
+                    }
+                    connection.queuedMessages += 1;
+                    connection.queue = connection.queue
+                        .then(() => handleMessage(connection, message))
+                        .catch(() => undefined)
+                        .finally(() => {
+                        connection.queuedMessages -= 1;
+                    });
                 },
                 close: () => {
                     if (connection.userId !== null && sessionsByUserId.get(connection.userId) === connection) {
                         sessionsByUserId.delete(connection.userId);
                     }
                     connections.delete(connection);
+                    for (const key of [...connection.subscriptions])
+                        removeSubscription(connection, key);
                     leaveJoinedServers(connection);
                     dropPresence(connection);
                     dropVoice(connection);
@@ -519,6 +608,7 @@ export function createHostRouter(options) {
         close: () => {
             unsubscribeHost();
             connections.clear();
+            subscribers.clear();
         },
     };
 }

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./commandMiddleware.js";
 export * from "./createWsBackend.js";
 export * from "./host.js";
 export * from "./hostRouter.js";

package/dist/index.js

@@ -1,3 +1,4 @@
+export * from "./commandMiddleware.js";
 export * from "./createWsBackend.js";
 export * from "./host.js";
 export * from "./hostRouter.js";

package/dist/pipe.js

@@ -1,3 +1,4 @@
+const OPEN = 1;
 export function webSocketPipe(url, webSocketFactory = (target) => new WebSocket(target)) {
     return (handlers) => {
         const socket = webSocketFactory(url);
@@ -6,7 +7,7 @@ export function webSocketPipe(url, webSocketFactory = (target) => new WebSocket(
         socket.onclose = () => handlers.onClose();
         return {
             send: (data) => {
-                if (socket.readyState !== 1)
+                if (socket.readyState !== OPEN)
                     return;
                 socket.send(data);
             },

package/dist/protocol.d.ts

@@ -3,6 +3,16 @@ import type { PlayerPose } from "@jgengine/core/multiplayer/poseSyncGate";
 import type { SessionAttributes } from "@jgengine/core/runtime/hostPersistence";
 import type { MatchFilter, SessionListing } from "@jgengine/core/multiplayer/matchmaking";
 export declare const WS_PROTOCOL_VERSION = 1;
+/** Max length of a `runCommand` command name, in UTF-16 code units. */
+export declare const MAX_COMMAND_LENGTH = 4096;
+/** Max length of a `pushFeed` action name, in UTF-16 code units. */
+export declare const MAX_FEED_ACTION_LENGTH = 256;
+/** Max serialized size of a `pushFeed` entry payload, in bytes. */
+export declare const MAX_FEED_ENTRY_BYTES = 65536;
+/** Max number of keys in a pose `appearance` tag map. */
+export declare const MAX_APPEARANCE_ENTRIES = 32;
+/** Max length of a single `appearance` tag string value, in UTF-16 code units. */
+export declare const MAX_APPEARANCE_VALUE_LENGTH = 256;
 export type WsChannel = "server" | "player" | "feed" | "presence" | "chat" | "voice";
 /** Client-set cosmetic/state tags carried alongside a pose (skin, mount, emote, ...). Primitive values only. */
 export type WsAppearance = Record<string, string | number | boolean>;
@@ -36,6 +46,7 @@ export type WsClientMessage = {
     gameId: string;
     serverId?: string;
     attributes?: SessionAttributes;
+    code?: string;
 } | {
     v: 1;
     t: "joinByCode";
@@ -172,12 +183,17 @@ export type WsJoinResult = JoinServerResult;
 export type WsRunCommandResult = TransportRunCommandResult;
 export type WsBrowseResult = SessionListing[];
 export type WsJoinByCodeResult = JoinServerResult | null;
+/** @internal */
 export declare function encodeWsMessage(message: WsClientMessage | WsServerMessage): string;
 export type WsDecodeFailure = {
     reason: string;
     id?: number;
 };
+/** @internal */
 export declare function inspectWsDecodeFailure(raw: unknown): WsDecodeFailure;
+/** @internal */
 export declare function decodeWsClientMessage(raw: unknown): WsClientMessage | null;
+/** @internal */
 export declare function decodeWsServerMessage(raw: unknown): WsServerMessage | null;
+/** @internal */
 export declare function subscriptionKey(channel: WsChannel, serverId: string, action?: string): string;

package/dist/protocol.js

@@ -1,4 +1,15 @@
 export const WS_PROTOCOL_VERSION = 1;
+/** Max length of a `runCommand` command name, in UTF-16 code units. */
+export const MAX_COMMAND_LENGTH = 4_096;
+/** Max length of a `pushFeed` action name, in UTF-16 code units. */
+export const MAX_FEED_ACTION_LENGTH = 256;
+/** Max serialized size of a `pushFeed` entry payload, in bytes. */
+export const MAX_FEED_ENTRY_BYTES = 65_536;
+/** Max number of keys in a pose `appearance` tag map. */
+export const MAX_APPEARANCE_ENTRIES = 32;
+/** Max length of a single `appearance` tag string value, in UTF-16 code units. */
+export const MAX_APPEARANCE_VALUE_LENGTH = 256;
+/** @internal */
 export function encodeWsMessage(message) {
     return JSON.stringify(message);
 }
@@ -32,8 +43,17 @@ function isWsChannel(value) {
         value === "voice");
 }
 function isAppearance(value) {
-    return (isRecord(value) &&
-        Object.values(value).every((v) => typeof v === "string" || typeof v === "number" || typeof v === "boolean"));
+    if (!isRecord(value))
+        return false;
+    const entries = Object.values(value);
+    if (entries.length > MAX_APPEARANCE_ENTRIES)
+        return false;
+    return entries.every((v) => (typeof v === "string" && v.length <= MAX_APPEARANCE_VALUE_LENGTH) ||
+        typeof v === "number" ||
+        typeof v === "boolean");
+}
+function withinFeedEntryBudget(entry) {
+    return new TextEncoder().encode(JSON.stringify(entry)).length <= MAX_FEED_ENTRY_BYTES;
 }
 function isFiniteNumber(value) {
     return typeof value === "number" && Number.isFinite(value);
@@ -47,6 +67,7 @@ function isPose(value) {
         isFiniteNumber(value.rotationPitch) &&
         (value.appearance === undefined || isAppearance(value.appearance)));
 }
+/** @internal */
 export function inspectWsDecodeFailure(raw) {
     if (typeof raw !== "string")
         return { reason: "Invalid message framing" };
@@ -66,8 +87,27 @@ export function inspectWsDecodeFailure(raw) {
     if (typeof parsed.t !== "string") {
         return { reason: "Invalid message type", id };
     }
+    if (parsed.t === "runCommand" && typeof parsed.command === "string" && parsed.command.length > MAX_COMMAND_LENGTH) {
+        return { reason: "Command exceeds max length", id };
+    }
+    if (parsed.t === "pushFeed" && typeof parsed.action === "string" && parsed.action.length > MAX_FEED_ACTION_LENGTH) {
+        return { reason: "Feed action exceeds max length", id };
+    }
+    if (parsed.t === "pushFeed" && "entry" in parsed && !withinFeedEntryBudget(parsed.entry)) {
+        return { reason: "Feed entry exceeds max size", id };
+    }
+    if (parsed.t === "pose" && isRecord(parsed.pose) && isRecord(parsed.pose.appearance)) {
+        const values = Object.values(parsed.pose.appearance);
+        if (values.length > MAX_APPEARANCE_ENTRIES) {
+            return { reason: "Appearance exceeds max entries", id };
+        }
+        if (values.some((v) => typeof v === "string" && v.length > MAX_APPEARANCE_VALUE_LENGTH)) {
+            return { reason: "Appearance value exceeds max length", id };
+        }
+    }
     return { reason: "Malformed message", id };
 }
+/** @internal */
 export function decodeWsClientMessage(raw) {
     const message = parseVersioned(raw);
     if (message === null)
@@ -82,7 +122,8 @@ export function decodeWsClientMessage(raw) {
         case "join":
             return typeof message.id === "number" &&
                 typeof message.gameId === "string" &&
-                (message.serverId === undefined || typeof message.serverId === "string")
+                (message.serverId === undefined || typeof message.serverId === "string") &&
+                (message.code === undefined || typeof message.code === "string")
                 ? message
                 : null;
         case "joinByCode":
@@ -102,13 +143,16 @@ export function decodeWsClientMessage(raw) {
         case "runCommand":
             return typeof message.id === "number" &&
                 typeof message.serverId === "string" &&
-                typeof message.command === "string"
+                typeof message.command === "string" &&
+                message.command.length <= MAX_COMMAND_LENGTH
                 ? message
                 : null;
         case "pushFeed":
             return typeof message.id === "number" &&
                 typeof message.serverId === "string" &&
-                typeof message.action === "string"
+                typeof message.action === "string" &&
+                message.action.length <= MAX_FEED_ACTION_LENGTH &&
+                withinFeedEntryBudget(message.entry)
                 ? message
                 : null;
         case "subscribe":
@@ -154,6 +198,7 @@ export function decodeWsClientMessage(raw) {
             return null;
     }
 }
+/** @internal */
 export function decodeWsServerMessage(raw) {
     const message = parseVersioned(raw);
     if (message === null)
@@ -176,6 +221,7 @@ export function decodeWsServerMessage(raw) {
             return null;
     }
 }
+/** @internal */
 export function subscriptionKey(channel, serverId, action) {
     return `${channel}|${serverId}|${action ?? ""}`;
 }

package/dist/readsHandler.js

@@ -41,7 +41,8 @@ export function createReadsHandler(options) {
                 return json(await options.listOpenServers({ gameId, limit }));
             }
             const records = await (await getPersistence()).listServers(gameId);
-            return json(toOpenServerListings(records.map((record) => toServerListing(record)), limit));
+            const publicRecords = records.filter((record) => (record.visibility ?? "public") !== "private");
+            return json(toOpenServerListings(publicRecords.map((record) => toServerListing(record)), limit));
         }
         if (head === "leaderboard" && tail !== undefined && segments.length === 2) {
             const scope = url.searchParams.get("scope") ?? "global";

package/dist/worldHost.js

@@ -72,7 +72,7 @@ export function createWorldGameHost(options) {
         async isMember({ userId, serverId }) {
             return live.get(serverId)?.session.members().includes(userId) ?? false;
         },
-        async getServerView({ serverId }) {
+        async getServerView({ userId, serverId }) {
             const entry = live.get(serverId);
             if (entry === undefined)
                 return null;
@@ -81,7 +81,7 @@ export function createWorldGameHost(options) {
                 gameId: entry.gameId,
                 revision: entry.session.revision(),
                 memberUserIds: [...entry.session.members()],
-                serverState: entry.session.runner().snapshot(),
+                serverState: entry.session.snapshotFor({ userId }),
                 updatedAt: now(),
             };
         },

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@jgengine/ws",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Browser-safe WebSocket client backend for JGengine: protocol codec, createWsBackend, and HTTP read helpers.",
-  "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,7 +31,7 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@jgengine/core": "^0.10.0"
+    "@jgengine/core": "^0.11.0"
   },
   "publishConfig": {
     "access": "public"

package/skills/jgengine/SKILL.md

@@ -0,0 +1,51 @@
+---
+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
+
+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 art direction
+- one observable completion scenario
+
+For a new in-repo game, scaffold with `bun run new:game <id> --name "Title"`. 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 |
+| --- | --- | --- |
+| 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 |
+
+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.
+
+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.