@underpostnet/cyberia 3.3.73 → 3.3.77

package/src/client/components/cyberia/ObjectLayerEngineViewer.js

@@ -29,7 +29,7 @@ class ObjectLayerEngineViewer {
     currentMode: 'idle',
     webp: null,
     isGenerating: false,
-    currentObjectId: undefined, // Track current loaded object layer id to prevent unnecessary reloads
+    currentItemId: undefined, // Item id in the URL, so an unchanged route skips a reload
     atlasSpriteSheet: null,
     isGeneratingAtlas: false,
     webpMetadata: null,
@@ -52,8 +52,8 @@ class ObjectLayerEngineViewer {
   }
   static async instance({ appStore }) {
     const id = 'object-layer-engine-viewer';
-    // Reset currentObjectId when modal is rendered to ensure Reload triggers properly
-    ObjectLayerEngineViewer.Data.currentObjectId = undefined;
+    // Reset so a modal render always triggers Reload.
+    ObjectLayerEngineViewer.Data.currentItemId = undefined;
     Modal.Data[`modal-${id}`].onReloadModalListener[id] = async () => {
       ObjectLayerEngineViewer.Reload({ appStore });
     };
@@ -61,13 +61,12 @@ class ObjectLayerEngineViewer {
     listenQueryParamsChange({
       id: `${id}-query-listener`,
       event: async (queryParams) => {
-        const objectId = queryParams.id || null;
+        const itemId = queryParams.itemId || null;
         if (!s(`.modal-${id}`) || !s(`#${id}`)) {
           logger.warn('ObjectLayerEngineViewer DOM not ready for query param change');
           return;
         }
-        // Only reload if object id actually changed (normalize undefined to null for comparison)
-        if (objectId !== ObjectLayerEngineViewer.Data.currentObjectId) {
+        if (itemId !== ObjectLayerEngineViewer.Data.currentItemId) {
           await ObjectLayerEngineViewer.Reload({ appStore });
         }
       },
@@ -90,8 +89,7 @@ class ObjectLayerEngineViewer {
       logger.warn('ObjectLayerEngineViewer DOM not ready for renderEmpty');
       return;
     }
-    // Clear current object id when rendering empty state
-    ObjectLayerEngineViewer.Data.currentObjectId = null;
+    ObjectLayerEngineViewer.Data.currentItemId = null;
     // Check if the management table grid already exists AND its DOM is still present
     // If it does, don't re-render (just let DefaultManagement's RouterEvents handle URL changes)
     const gridId = `object-layer-engine-management-grid-${idModal}`;
@@ -116,7 +114,7 @@ class ObjectLayerEngineViewer {
       }),
     );
   }
-  static async loadObjectLayer(objectLayerId, appStore, options = {}) {
+  static async loadObjectLayer(itemId, appStore, options = {}) {
     const { skipWebp = false } = options;
     const id = 'object-layer-engine-viewer';
     // Check if DOM element exists
@@ -126,7 +124,7 @@ class ObjectLayerEngineViewer {
     }
     try {
       // Load metadata first
-      const { status: metaStatus, data: metadata } = await ObjectLayerService.getMetadata({ id: objectLayerId });
+      const { status: metaStatus, data: metadata } = await ObjectLayerService.getMetadata({ id: itemId });
       if (metaStatus !== 'success' || !metadata) {
         throw new Error('Failed to load object layer metadata');
       }
@@ -142,15 +140,11 @@ class ObjectLayerEngineViewer {
         ObjectLayerEngineViewer.Data.atlasSpriteSheet = null;
       }
       // Load frame counts for all directions
-      const { status: frameStatus, data: frameData } = await ObjectLayerService.getFrameCounts({ id: objectLayerId });
+      const { status: frameStatus, data: frameData } = await ObjectLayerService.getFrameCounts({ id: itemId });
       if (frameStatus !== 'success' || !frameData) {
         throw new Error('Failed to load frame counts');
       }
       ObjectLayerEngineViewer.Data.frameCounts = frameData.frameCounts;
-      // Priority order for directions
-      const directions = ['down', 'up', 'left', 'right'];
-      // Priority order for modes
-      const modes = ['idle', 'walking'];
       ObjectLayerEngineViewer.Data.currentDirection = 'down';
       ObjectLayerEngineViewer.Data.currentMode = 'idle';
       // instance the viewer UI
@@ -162,7 +156,7 @@ class ObjectLayerEngineViewer {
     } catch (error) {
       logger.error('Error loading object layer:', error);
       NotificationManager.Push({
-        html: `Failed to load object layer: ${error.message}`,
+        html: `Failed to load object layer "${itemId}": ${error.message}`,
         status: 'error',
       });
       htmls(
@@ -170,12 +164,16 @@ class ObjectLayerEngineViewer {
         html`
           <div class="in section-mp">
             <div class="in">
-              <h3>Error</h3>
-              <p>Failed to load object layer. Please try again.</p>
+              <h3>Object layer not found</h3>
+              <p>No object layer answers to the item id <strong>${itemId}</strong>.</p>
+              <button class="default-viewer-btn" id="return-to-list-btn">
+                <i class="fa-solid fa-list"></i> Back to the list
+              </button>
             </div>
           </div>
         `,
       );
+      ObjectLayerEngineViewer.attachReturnToList({ appStore });
     }
   }
   static async renderViewer({ appStore }) {
@@ -208,6 +206,29 @@ class ObjectLayerEngineViewer {
       const numericCode = ObjectLayerEngineViewer.getDirectionCode(direction, mode);
       return numericCode ? frameCounts[numericCode] || 0 : 0;
     };
+    // One atlas render: which one it is, how large it is, and its PNG.
+    // `native` draws the blob at its own pixel size, with no fit to the panel.
+    const atlasRender = ({ label, fileId, pixelsPerCell, emptyText, native }) => {
+      const metadata = ObjectLayerEngineViewer.Data.atlasSpriteSheet.metadata;
+      const size =
+        pixelsPerCell > 0
+          ? `${metadata.atlasWidth * pixelsPerCell}x${metadata.atlasHeight * pixelsPerCell}px · ${pixelsPerCell}px per cell`
+          : '';
+      return html`<div class="atlas-render">
+        <p class="atlas-render-label">
+          <strong class="item-data-key-label">${label}</strong>
+          <span class="atlas-render-size">${size}</span>
+        </p>
+        <div class="atlas-img-wrapper">
+          ${fileId
+            ? html`<img
+                src="${getProxyPath()}api/file/blob/${fileId._id || fileId}"
+                class="in atlas-img-preview ${native ? 'atlas-img-native' : ''}"
+              />`
+            : html`<div class="atlas-img-placeholder">${emptyText}</div>`}
+        </div>
+      </div>`;
+    };
     ThemeEvents[id] = () => {
       if (!s(`.style-${id}`)) return;
       htmls(
@@ -240,6 +261,32 @@ class ObjectLayerEngineViewer {
           }
           .atlas-img-preview {
             width: 100%;
+            image-rendering: pixelated;
+            background: repeating-conic-gradient(#80808020 0% 25%, #fff0 0% 50%) 50% / 20px 20px;
+          }
+          /* Own pixel size, so one atlas pixel is one screen pixel. */
+          .atlas-img-native {
+            width: auto;
+            height: auto;
+            margin: auto;
+          }
+          .atlas-img-placeholder {
+            padding: 20px;
+            text-align: center;
+            font-size: 13px;
+            color: ${darkTheme ? '#aaa' : '#666'};
+          }
+          .atlas-render-label {
+            display: flex;
+            flex-wrap: wrap;
+            align-items: baseline;
+            gap: 8px;
+            padding: 2px;
+            font-size: 14px;
+          }
+          .atlas-render-size {
+            font-size: 12px;
+            opacity: 0.75;
           }
           .atlas-metadata-grid {
             display: grid;
@@ -723,7 +770,7 @@ class ObjectLayerEngineViewer {
                                   />
                                   <span class="item-data-key-label">${statInfo.title}</span>
                                 </div>
-                                <span class="item-data-value-label">${statValue}</span>
+                                <span class="item-data-value-label" style="color: ${statValue < 0 ? '#ef7777' : statValue > 0 ? '#7bdd9a' : '#aaa'}">${statValue > 0 ? '+' : ''}${statValue}</span>
                               </div>
                             `;
                           })
@@ -871,24 +918,19 @@ class ObjectLayerEngineViewer {
                       ${ObjectLayerEngineViewer.Data.atlasSpriteSheet
                         ? html`
                         <div class="atlas-preview-container">
-                          ${
-                            ObjectLayerEngineViewer.Data.atlasSpriteSheet.fileId
-                              ? html`
-                                  <div class="atlas-img-wrapper">
-                                    <img
-                                      src="${getProxyPath()}api/file/blob/${ObjectLayerEngineViewer.Data
-                                        .atlasSpriteSheet.fileId._id ||
-                                      ObjectLayerEngineViewer.Data.atlasSpriteSheet.fileId}"
-                                      class="in atlas-img-preview"
-                                    />
-                                  </div>
-                                `
-                              : html`
-                                  <div class="atlas-img-wrapper">
-                                    <div class="atlas-img-placeholder">Atlas image not available</div>
-                                  </div>
-                                `
-                          }
+                          ${atlasRender({
+                            label: 'Upscaled',
+                            fileId: ObjectLayerEngineViewer.Data.atlasSpriteSheet.fileId,
+                            pixelsPerCell: ObjectLayerEngineViewer.Data.atlasSpriteSheet.metadata.upscaleFactor,
+                            emptyText: 'Upscaled render not available',
+                          })}
+                          ${atlasRender({
+                            label: 'Minified',
+                            fileId: ObjectLayerEngineViewer.Data.atlasSpriteSheet.minifyFileId,
+                            pixelsPerCell: ObjectLayerEngineViewer.Data.atlasSpriteSheet.metadata.cellPixelDim,
+                            emptyText: 'Minified render not available',
+                            native: true,
+                          })}
                           <div class="atlas-metadata-grid">
                             <div>
                               <p style="padding: 2px"><strong class="item-data-key-label">ID:</strong></p>
@@ -904,16 +946,6 @@ class ObjectLayerEngineViewer {
                                   </div>`
                                 : ''
                             }
-                            <div>
-                              <p style="padding: 2px"><strong class="item-data-key-label">Dimensions:</strong></p>
-                              <p style="padding: 2px">
-                                ${ObjectLayerEngineViewer.Data.atlasSpriteSheet.metadata.atlasWidth}x${ObjectLayerEngineViewer.Data.atlasSpriteSheet.metadata.atlasHeight}
-                              </p>
-                            </div>
-                            <div>
-                                <p style="padding: 2px"><strong class="item-data-key-label">Cell Dim:</strong></p>
-                              <p style="padding: 2px">${ObjectLayerEngineViewer.Data.atlasSpriteSheet.metadata.cellPixelDim}px</p>
-                            </div>
                             <div>
                                 <p style="padding: 2px"><strong class="item-data-key-label">Item Key:</strong></p>
                               <p style="padding: 2px">${ObjectLayerEngineViewer.Data.atlasSpriteSheet.metadata.itemKey}</p>
@@ -1125,12 +1157,12 @@ class ObjectLayerEngineViewer {
         }
         delete ThemeEvents['metadata-json-editor-theme'];
         // Navigate back to list
-        ObjectLayerEngineViewer.Data.currentObjectId = undefined;
+        ObjectLayerEngineViewer.Data.currentItemId = undefined;
         ObjectLayerEngineViewer.Data.objectLayer = null;
         ObjectLayerEngineViewer.Data.webp = null;
         ObjectLayerEngineViewer.Data.webpMetadata = null;
         ObjectLayerEngineViewer.Data.atlasSpriteSheet = null;
-        setQueryParams({ id: null }, { replace: false });
+        setQueryParams({ itemId: null }, { replace: false });
       } else {
         throw new Error(result.message || 'Failed to delete object layer');
       }
@@ -1142,6 +1174,21 @@ class ObjectLayerEngineViewer {
       });
     }
   }
+  static attachReturnToList({ appStore }) {
+    const listBtn = s('#return-to-list-btn');
+    if (!listBtn) return;
+    listBtn.addEventListener('click', async () => {
+      ObjectLayerEngineViewer.Data.webp = null;
+      ObjectLayerEngineViewer.Data.webpMetadata = null;
+      ObjectLayerEngineViewer.Data.objectLayer = null;
+      ObjectLayerEngineViewer.Data.frameCounts = null;
+      // Cleared before the URL changes, so the query listener sees a match and
+      // skips the Reload that would render the list twice.
+      ObjectLayerEngineViewer.Data.currentItemId = null;
+      setQueryParams({ itemId: null }, { replace: false });
+      await ObjectLayerEngineViewer.renderEmpty({ appStore });
+    });
+  }
   static attachEventListeners({ appStore }) {
     // Direction buttons
     const directionButtons = document.querySelectorAll('[data-direction]');
@@ -1178,28 +1225,7 @@ class ObjectLayerEngineViewer {
         ObjectLayerEngineViewer.downloadWebp();
       });
     }
-    // Return to list button
-    const listBtn = s('#return-to-list-btn');
-    if (listBtn) {
-      listBtn.addEventListener('click', async () => {
-        // Clear object data and reset state
-        ObjectLayerEngineViewer.Data.webp = null;
-        ObjectLayerEngineViewer.Data.webpMetadata = null;
-        ObjectLayerEngineViewer.Data.objectLayer = null;
-        ObjectLayerEngineViewer.Data.frameCounts = null;
-        // Set currentObjectId to null BEFORE setQueryParams so the
-        // listenQueryParamsChange listener sees the id already matches
-        // and skips calling Reload (avoids double-render race condition)
-        ObjectLayerEngineViewer.Data.currentObjectId = null;
-        // Update the URL to remove the id parameter
-        setQueryParams({ id: null }, { replace: false });
-        // Directly render the list view instead of relying on the
-        // listener → Reload → renderEmpty chain which can silently
-        // fail when the URL was already clean or currentObjectId
-        // was already null
-        await ObjectLayerEngineViewer.renderEmpty({ appStore });
-      });
-    }
+    ObjectLayerEngineViewer.attachReturnToList({ appStore });
     // Edit button
     const editBtn = s('#edit-object-layer-btn');
     if (editBtn) {
@@ -1477,12 +1503,10 @@ class ObjectLayerEngineViewer {
     });
   }
   static toEngine() {
-    const { objectLayer } = ObjectLayerEngineViewer.Data;
-    if (!objectLayer || !objectLayer._id) return;
-    // Navigate to editor route first
+    const itemId = ObjectLayerEngineViewer.Data.objectLayer?.data?.item?.id;
+    if (!itemId) return;
     setPath(`${getProxyPath()}object-layer-engine`);
-    // Then add query param without replacing history
-    setQueryParams({ id: objectLayer._id }, { replace: true });
+    setQueryParams({ itemId }, { replace: true });
     if (s(`.modal-object-layer-engine`)) {
       ObjectLayerEngineModal.Reload();
     } else {
@@ -1491,31 +1515,22 @@ class ObjectLayerEngineViewer {
   }
   static async Reload(options = {}) {
     const { appStore, force = false, skipWebp = false } = options;
-    const queryParams = getQueryParams();
-    const objectId = queryParams.id || null;
-    // Only reload if object id actually changed (same logic as listener) or forced
-    if (objectId !== ObjectLayerEngineViewer.Data.currentObjectId || force) {
-      if (objectId !== ObjectLayerEngineViewer.Data.currentObjectId && !skipWebp) {
+    const itemId = getQueryParams().itemId || null;
+    const changed = itemId !== ObjectLayerEngineViewer.Data.currentItemId;
+    if (changed || force) {
+      if (changed && !skipWebp) {
         ObjectLayerEngineViewer.Data.webp = null;
         ObjectLayerEngineViewer.Data.webpMetadata = null;
       }
-      ObjectLayerEngineViewer.Data.currentObjectId = objectId;
-      if (objectId) {
-        await ObjectLayerEngineViewer.loadObjectLayer(objectId, appStore, { skipWebp });
-      } else {
-        await ObjectLayerEngineViewer.renderEmpty({ appStore });
-      }
-    } else if (!objectId && (ObjectLayerEngineViewer.Data.currentObjectId === null || force)) {
-      // Special case: if we're already in empty state but DOM might have been reset
-      // (e.g., modal reopened), force render the table if DOM is missing
-      const id = 'object-layer-engine-viewer';
-      const idModal = 'modal-object-layer-engine-viewer';
-      const gridId = `object-layer-engine-management-grid-${idModal}`;
-      const gridDomExists = s(`.${gridId}`);
-      if (!gridDomExists) {
-        // DOM was reset (e.g., modal HTML reloaded), re-render the table
-        await ObjectLayerEngineViewer.renderEmpty({ appStore });
-      }
+      ObjectLayerEngineViewer.Data.currentItemId = itemId;
+      if (itemId) await ObjectLayerEngineViewer.loadObjectLayer(itemId, appStore, { skipWebp });
+      else await ObjectLayerEngineViewer.renderEmpty({ appStore });
+      return;
+    }
+    // Already on the list, but a modal reopen can drop its DOM.
+    if (!itemId && ObjectLayerEngineViewer.Data.currentItemId === null) {
+      const gridId = `object-layer-engine-management-grid-modal-object-layer-engine-viewer`;
+      if (!s(`.${gridId}`)) await ObjectLayerEngineViewer.renderEmpty({ appStore });
     }
   }
 }

package/src/client/components/cyberia/SharedDefaultsCyberia.js

@@ -1,51 +1,4 @@
-/**
- * Shared Cyberia defaults — isomorphic, dependency-free, importable from
- * **both** Node and the browser.
- *
- * Pure plain-data ESM module: no Node built-ins, no DOM APIs, no
- * environment guards. Every export is a frozen literal, a constant
- * lookup table, or a pure function over those tables. Side-effect free
- * on import.
- *
- * Two responsibilities, no others:
- *
- *   1. **Presentation values** — palette, entity colour keys, status-icon
- *      visuals (icon stem + border colour + bounce), camera tunings,
- *      render flags. Mirrored 1-to-1 by the C/WASM client's compile-time
- *      defaults in `cyberia-client/src/domain/presentation_defaults.h`.
- *      Optionally overridable per deployment through the REST endpoint
- *      `/api/cyberia-client-hints/:code`.
- *
- *   2. **Shared content vocabulary** — `ITEM_TYPES`, `ENTITY_TYPES`,
- *      `DefaultCyberiaItems` registry + lookups, type-to-item mapping,
- *      quest step objective enum. The data shape both the
- *      browser-side editor UI and the engine REST controllers need to
- *      understand; it is **not** simulation state.
- *
- * STRICT BOUNDARIES
- * -----------------
- *   - The cyberia-server (Go) MUST NOT load this file. None of these
- *     values influence the authoritative simulation. The server owns the
- *     numeric Entity Status Indicator IDs only (see `cyberia-server-defaults`).
- *
- *   - The C/WASM cyberia-client embeds *presentation* defaults at compile
- *     time and fetches optional overrides through REST. It does NOT carry
- *     the JS vocabulary constants — entity-type and item-id strings
- *     arrive on the wire and are matched directly.
- *
- *   - The browser editor bundles this file via esbuild. It MUST NOT
- *     import `cyberia-server-defaults.js` — that would pull simulation
- *     rules, economy, and seed content into the browser bundle. All
- *     shared vocabulary the editor needs lives here.
- *
- * Naming: this file is intentionally placed under `src/client/` so its
- * URL is `/components/cyberia/SharedDefaultsCyberia.js` when the engine
- * static server resolves it. Node-side importers reach in with a
- * relative path; both halves see the same module instance.
- *
- * @module src/client/components/cyberia/SharedDefaultsCyberia.js
- */
-
+// Shared content, stat contract, and presentation defaults.
 // ─────────────────────────────────────────────────────────────────────────────
 // Shared content vocabulary
 // ─────────────────────────────────────────────────────────────────────────────
@@ -150,6 +103,126 @@ export const SKILL_LOGIC_ID_VALUES = Object.freeze(SKILL_LOGIC_IDS.map((l) => l.
 /** True when `logicEventId` is a known canonical skill LogicId. */
 export const isCanonicalSkillLogicId = (logicEventId) => SKILL_LOGIC_ID_VALUES.includes(logicEventId);
 
+/**
+ * The two audio routes: a held music bed, and one-shot effects over it.
+ *
+ * One bus vocabulary, spelled once: the same ids name the `src/audio-module/<bus-id>/` directory
+ * an asset is authored in, the argument `cyberia-audio <bus-id> <id>` dispatches on, the `bus` a
+ * recorded manifest carries, and the route a binding's `settings.bus` selects.
+ */
+export const AUDIO_BUS_MUSIC = 'music';
+export const AUDIO_BUS_SFX = 'sfx';
+export const AUDIO_BUSES = Object.freeze([AUDIO_BUS_MUSIC, AUDIO_BUS_SFX]);
+
+/**
+ * Canonical audio LogicId registry — the runtime events an audio binding may answer.
+ *
+ * Audio is a consumer of the game's semantic event vocabulary, never a second one: a
+ * `cyberia-map-audio-conf` binding resolves one of these ids (or a canonical skill LogicId, which
+ * the client emits by the same name) to an `audioCode`. The ids live here, beside the other shared
+ * vocabularies, because three parties must agree on them — the C client that emits them, the seed
+ * that binds them, and the editor that offers them.
+ *
+ * `bus` is the binding's natural routing: music events take over the map's bed until `idle`
+ * restores it; sfx events are one shots. A binding may override it in its own settings.
+ *
+ * MUST stay aligned with the events emitted by cyberia-client (`src/audio/audio_events.h`).
+ *
+ * @type {ReadonlyArray<{id:string,name:string,description:string,bus:'music'|'sfx'}>}
+ */
+export const AUDIO_LOGIC_IDS = Object.freeze([
+  Object.freeze({
+    id: 'idle',
+    name: 'Idle',
+    description: 'No event is holding the bed: the map returns to its default music.',
+    bus: AUDIO_BUS_MUSIC,
+  }),
+  Object.freeze({
+    id: 'combat',
+    name: 'Combat',
+    description: 'The player is taking damage: combat music takes over until the exchange ends.',
+    bus: AUDIO_BUS_MUSIC,
+  }),
+  Object.freeze({ id: 'boss', name: 'Boss', description: 'A boss encounter is under way.', bus: AUDIO_BUS_MUSIC }),
+  Object.freeze({
+    id: 'portal-cooldown',
+    name: 'Portal Cooldown',
+    description: 'The player is standing on a portal while its teleport charge runs.',
+    bus: AUDIO_BUS_MUSIC,
+  }),
+  Object.freeze({
+    id: 'portal',
+    name: 'Portal',
+    description: 'The teleport charge completed and the player jumps — within a map or across one.',
+    bus: AUDIO_BUS_SFX,
+  }),
+  Object.freeze({
+    id: 'hit',
+    name: 'Hit',
+    description: 'Damage landed on any entity in view, not only on the player.',
+    bus: AUDIO_BUS_SFX,
+  }),
+  Object.freeze({ id: 'heal', name: 'Heal', description: 'Life was restored to an entity in view.', bus: AUDIO_BUS_SFX }),
+  Object.freeze({ id: 'drop', name: 'Drop', description: 'An item drop spawned in the world.', bus: AUDIO_BUS_SFX }),
+  Object.freeze({
+    id: 'victory',
+    name: 'Victory',
+    description: 'A quest or encounter was completed.',
+    bus: AUDIO_BUS_SFX,
+  }),
+  Object.freeze({
+    id: 'level-up',
+    name: 'Level Up',
+    description: 'An entity in view reached a new level.',
+    bus: AUDIO_BUS_SFX,
+  }),
+  Object.freeze({
+    id: 'death',
+    name: 'Death',
+    description: 'An entity in view was defeated.',
+    bus: AUDIO_BUS_SFX,
+  }),
+  Object.freeze({
+    id: 'item-pickup',
+    name: 'Item Pickup',
+    description: 'An item landed in the player inventory — loot, a reward, a purchase, an assembly output.',
+    bus: AUDIO_BUS_SFX,
+  }),
+  Object.freeze({
+    id: 'craft',
+    name: 'Craft',
+    description: 'An assembly is charging: the bed is held until the recipe progress bar finishes.',
+    bus: AUDIO_BUS_MUSIC,
+  }),
+  Object.freeze({
+    id: 'ui-click',
+    name: 'UI Click',
+    description: 'The interface accepted a tap — a button, a modal control, a bubble.',
+    bus: AUDIO_BUS_SFX,
+  }),
+  Object.freeze({
+    id: 'footsteps',
+    name: 'Footsteps',
+    description: 'Something with feet is walking in view; repeats on a gait cadence while it lasts.',
+    bus: AUDIO_BUS_SFX,
+  }),
+]);
+
+/** Ordered list of canonical audio LogicId values. */
+export const AUDIO_LOGIC_ID_VALUES = Object.freeze(AUDIO_LOGIC_IDS.map((l) => l.id));
+
+/** Map: audio LogicId → its natural bus. */
+export const AUDIO_LOGIC_ID_BUSES = Object.freeze(
+  Object.fromEntries(AUDIO_LOGIC_IDS.map((l) => [l.id, l.bus])),
+);
+
+/**
+ * True when `logicEventId` is a runtime event an audio binding may answer: an audio event, or a
+ * skill event the dispatcher fires (a skill's own id is what the client emits when it runs).
+ */
+export const isCanonicalAudioLogicId = (logicEventId) =>
+  AUDIO_LOGIC_ID_VALUES.includes(logicEventId) || isCanonicalSkillLogicId(logicEventId);
+
 /**
  * Canonical entity-behavior registry — the authoritative vocabulary for the
  * `behavior` an entity-type default may bind to its matched entities. The Go
@@ -277,19 +350,105 @@ export const OBJECT_LAYER_DIRECTION_NAME_TO_CODE = Object.freeze(
   }, {}),
 );
 
+// Stat order is shared by authoring, simulation, and snapshots. `scale` is what one point is
+// worth in the simulation; the server reads it from the generated contract.
+export const STAT_DEFINITIONS = Object.freeze([
+  { key: 'effect', title: 'Effect', description: 'Removes life on impact.', detail: 'Each point removes one life point per hit.', floor: 1, scale: 1 },
+  { key: 'resistance', title: 'Resistance', description: 'Adds maximum life and regeneration amount.', detail: 'Each point adds one point of maximum life and a tenth of a point to each regeneration.', floor: 0, scale: 1 },
+  { key: 'agility', title: 'Agility', description: 'Changes movement speed.', detail: 'Each point adds one percent of base speed.', floor: -90, scale: 0.01 },
+  { key: 'range', title: 'Range', description: 'Adds lifetime to summoned entities.', detail: 'Each point adds fifty milliseconds of summon lifetime.', floor: 0, scale: 50 },
+  { key: 'intelligence', title: 'Intelligence', description: 'Adds summon success chance.', detail: 'Each point adds five percentage points of summon chance.', floor: 0, scale: 0.05 },
+  { key: 'utility', title: 'Utility', description: 'Reduces action cooldown and increases regeneration chance.', detail: 'Each point removes one percent of base cooldown and adds one percentage point of regeneration chance.', floor: 0, scale: 0.01 },
+].map((stat) => Object.freeze({ ...stat, icon: `stat-${stat.key}.png` })));
+export const STAT_TYPES = Object.freeze(STAT_DEFINITIONS.map(({ key }) => key));
+/** What one point of each stat is worth in the simulation. */
+export const STAT_SCALES = Object.freeze(Object.fromEntries(STAT_DEFINITIONS.map(({ key, scale }) => [key, scale])));
+/** Life regenerated per trigger for each point of resistance, on top of the entity's base regeneration. */
+export const STAT_REGEN_PER_RESISTANCE = 0.1;
+export const STAT_MODIFIER_MIN = -100;
+export const STAT_MODIFIER_MAX = 100;
+export const STAT_DEFAULT = 0;
+export const ENTITY_LEVEL_MIN = 1;
+export const ENTITY_LEVEL_MAX = 65535;
+export function validateEntityLevel(level) {
+  if (!Number.isInteger(level) || level < ENTITY_LEVEL_MIN || level > ENTITY_LEVEL_MAX) {
+    throw new RangeError('Entity level must be an integer from 1 to 65535.');
+  }
+  return level;
+}
+export const STAT_CONTRACT_VERSION = 2;
+export const STAT_DEFAULTS = Object.freeze(Object.fromEntries(STAT_TYPES.map((key) => [key, STAT_DEFAULT])));
+export const STAT_EFFECTIVE_FLOORS = Object.freeze(Object.fromEntries(STAT_DEFINITIONS.map(({ key, floor }) => [key, floor])));
+export const STAT_DESCRIPTIONS = Object.freeze(Object.fromEntries(STAT_DEFINITIONS.map(({ key, ...info }) => [key, Object.freeze(info)])));
+
+export function validateStatModifier(value) {
+  if (!Number.isInteger(value) || value < STAT_MODIFIER_MIN || value > STAT_MODIFIER_MAX) {
+    throw new RangeError(`Stat modifiers must be integers from ${STAT_MODIFIER_MIN} to +${STAT_MODIFIER_MAX}.`);
+  }
+  return value;
+}
+
+export function validateStats(stats = {}) {
+  if (!stats || typeof stats !== 'object' || Array.isArray(stats)) throw new TypeError('Stats must be an object.');
+  for (const key of Object.keys(stats)) {
+    if (!STAT_TYPES.includes(key)) throw new TypeError(`Unknown stat: ${key}`);
+  }
+  return Object.fromEntries(STAT_TYPES.map((key) => [key, validateStatModifier(stats[key] === undefined ? STAT_DEFAULT : stats[key])]));
+}
+
 /**
- * Canonical entity/item stat types, in display order. Shared by the object-layer
- * editor (stat inputs) and the asset pipeline (random stat generation).
+ * Semantic stat bounds per item type, inclusive, as `[min, max]` per stat.
+ *
+ * What a type may carry: a weapon deals its effect and can cost resistance, a skin and a
+ * breastplate defend, a skill reaches, and world content carries nothing. A type absent here,
+ * or a stat a type leaves out, keeps the contract bounds.
  */
-export const STAT_TYPES = Object.freeze(['effect', 'resistance', 'agility', 'range', 'intelligence', 'utility']);
+export const STAT_TYPE_BOUNDS = Object.freeze({
+  weapon:      { effect: [5, 20], resistance: [-10, 2], agility: [-5, 5], range: [0, 10], intelligence: [0, 5], utility: [0, 10] },
+  skin:        { effect: [1, 1], resistance: [0, 20], agility: [-5, 10], range: [0, 0], intelligence: [0, 2], utility: [0, 5] },
+  breastplate: { effect: [0, 0], resistance: [5, 30], agility: [-15, 0], range: [0, 0], intelligence: [0, 3], utility: [0, 5] },
+  skill:       { effect: [0, 15], resistance: [0, 5], agility: [0, 5], range: [5, 30], intelligence: [0, 10], utility: [0, 10] },
+  resource:    { effect: [0, 0], resistance: [0, 10], agility: [0, 0], range: [0, 0], intelligence: [0, 0], utility: [0, 0] },
+  coin:        { effect: [0, 0], resistance: [0, 0], agility: [0, 0], range: [0, 0], intelligence: [0, 0], utility: [0, 0] },
+  floor:       { effect: [0, 0], resistance: [0, 0], agility: [0, 0], range: [0, 0], intelligence: [0, 0], utility: [0, 0] },
+  obstacle:    { effect: [0, 0], resistance: [0, 0], agility: [0, 0], range: [0, 0], intelligence: [0, 0], utility: [0, 0] },
+  portal:      { effect: [0, 0], resistance: [0, 0], agility: [0, 0], range: [0, 0], intelligence: [0, 0], utility: [0, 0] },
+  foreground:  { effect: [0, 0], resistance: [0, 0], agility: [0, 0], range: [0, 0], intelligence: [0, 0], utility: [0, 0] },
+  static:      { effect: [0, 0], resistance: [0, 0], agility: [0, 0], range: [0, 0], intelligence: [0, 0], utility: [0, 0] },
+});
+
+for (const [type, bounds] of Object.entries(STAT_TYPE_BOUNDS)) {
+  if (!Object.values(ITEM_TYPES).includes(type)) throw new Error(`STAT_TYPE_BOUNDS: unknown item type "${type}"`);
+  for (const [key, [min, max]] of Object.entries(bounds)) {
+    if (!STAT_TYPES.includes(key)) throw new Error(`STAT_TYPE_BOUNDS: ${type} names unknown stat "${key}"`);
+    validateStatModifier(min);
+    validateStatModifier(max);
+    if (min > max) throw new Error(`STAT_TYPE_BOUNDS: ${type}.${key} minimum exceeds its maximum`);
+  }
+}
 
 /**
- * Build a random stat block keyed by STAT_TYPES, each value 0–10 inclusive.
- * Non-deterministic (uses Math.random) — the asset pipeline uses it to seed
- * default stats for newly authored object layers.
+ * The inclusive `[min, max]` every stat may take for an item type: the semantic bound where the
+ * type declares one, the contract bound where it does not.
+ *
+ * @param {string} itemType
+ * @returns {Readonly<Record<string,[number,number]>>}
  */
-export const generateRandomStats = () =>
-  Object.fromEntries(STAT_TYPES.map((statType) => [statType, Math.floor(Math.random() * 11)]));
+export function statBoundsForType(itemType) {
+  const typed = STAT_TYPE_BOUNDS[itemType] ?? {};
+  return Object.freeze(Object.fromEntries(STAT_TYPES.map((key) => [key, typed[key] ?? [STAT_MODIFIER_MIN, STAT_MODIFIER_MAX]])));
+}
+
+export function generateRandomStats(min = STAT_MODIFIER_MIN, max = STAT_MODIFIER_MAX, random = Math.random) {
+  validateStatModifier(min);
+  validateStatModifier(max);
+  if (min > max) throw new RangeError('Random minimum must not exceed maximum.');
+  return Object.fromEntries(STAT_TYPES.map((key) => {
+    const value = random();
+    if (!Number.isFinite(value) || value < 0 || value >= 1) throw new RangeError('Random source must return [0, 1).');
+    return [key, Math.floor(value * (max - min + 1)) + min];
+  }));
+}
 
 /**
  * Canonical (itemId → itemType) registry shipped with the engine. Used