cyberia 3.2.9 → 3.2.22

package/src/api/cyberia-client-hints/cyberia-client-hints.router.js

@@ -0,0 +1,98 @@
+/**
+ * @module src/api/cyberia-client-hints
+ *
+ * Client presentation hints — read-only REST endpoint.
+ *
+ * Purpose
+ * -------
+ * The cyberia-server (Go authoritative simulation) and the WS init payload
+ * carry *only* simulation contracts. Client-render policy (palette, camera
+ * defaults, status-icon visuals, interpolation window, dev-overlay flag)
+ * lives off the simulation path entirely.
+ *
+ * This endpoint exposes optional per-instance overrides of those values.
+ * The client is required to function with no calls to this endpoint at
+ * all (it ships built-in defaults that match the canonical engine
+ * defaults 1-to-1 — see cyberia-client/src/domain/presentation_defaults.h).
+ *
+ * Endpoint
+ * --------
+ *   GET /api/cyberia-client-hints/:instanceCode
+ *     -> 200 { palette, entityColorKeys, statusIcons, cameraSmoothing,
+ *              cameraZoom, defaultWidthScreenFactor,
+ *              defaultHeightScreenFactor, interpolationMs, devUi }
+ *     -> 404 if no instance with that code exists in the database — the
+ *            client falls back to its built-in defaults on 404 (this is
+ *            the normal path for stateless servers / fresh deployments).
+ *
+ *   GET /api/cyberia-client-hints/
+ *     -> 200 canonical defaults — same shape as above, no DB read.
+ *
+ * What it intentionally does NOT do
+ * ---------------------------------
+ *   - It does not touch gameplay state (no entity, map, economy, skill,
+ *     equipment, or stat fields).
+ *   - It is not consumed by cyberia-server; the Go process never calls
+ *     this endpoint.
+ *   - It is not authenticated. Presentation hints are not secret.
+ */
+
+import express from 'express';
+import { loggerFactory } from '../../server/logger.js';
+import { CYBERIA_CLIENT_HINTS_DEFAULTS } from '../../client/components/cyberia/SharedDefaultsCyberia.js';
+import { resolveClientHints } from './cyberia-client-hints.service.js';
+
+const logger = loggerFactory(import.meta);
+
+class CyberiaClientHintsRouter {
+  /**
+   * @param {import('../types.js').RouterOptions} options
+   * @returns {import('express').Router}
+   */
+  static router(options) {
+    const router = express.Router();
+
+    // GET /:code -> resolved hints.
+    // Resolution order is documented in cyberia-client-hints.service.js:
+    //   1. In-memory TTL cache.
+    //   2. CyberiaClientHints collection (preferred).
+    //   3. Legacy presentation fields on CyberiaInstanceConf (back-compat).
+    //   4. Canonical client defaults (never cached so a later DB insert wins).
+    router.get('/:code', async (req, res) => {
+      try {
+        if (req && req.headers && req.headers.origin) {
+          res.set('Access-Control-Allow-Origin', req.headers.origin);
+        } else res.setHeader('Access-Control-Allow-Origin', '*');
+        res.setHeader('Cross-Origin-Resource-Policy', 'cross-origin');
+        const { data, source } = await resolveClientHints(req.params.code, {
+          host: options.host || 'default',
+          path: options.path || '/',
+        });
+        // Surface the resolution source as a non-authoritative header so
+        // operators can see whether the runtime fetched from the new
+        // collection, the compatibility read on instance-conf, the cache, or defaults.
+        res.setHeader('X-Cyberia-Hints-Source', source);
+        return res.status(200).json({ status: 'success', data });
+      } catch (err) {
+        logger.error('cyberia-client-hints GET failed:', err);
+        return res.status(500).json({ status: 'error', message: err.message });
+      }
+    });
+
+    // GET / -> canonical defaults. No DB read. Documentation/diagnostic.
+    router.get('/', async (_req, res) => {
+      if (_req && _req.headers && _req.headers.origin) {
+        res.set('Access-Control-Allow-Origin', _req.headers.origin);
+      } else res.setHeader('Access-Control-Allow-Origin', '*');
+      res.setHeader('Cross-Origin-Resource-Policy', 'cross-origin');
+      res.setHeader('X-Cyberia-Hints-Source', 'defaults');
+      return res.status(200).json({ status: 'success', data: CYBERIA_CLIENT_HINTS_DEFAULTS });
+    });
+
+    return router;
+  }
+}
+
+const ApiRouter = (options) => CyberiaClientHintsRouter.router(options);
+
+export { ApiRouter, CyberiaClientHintsRouter };

package/src/api/cyberia-client-hints/cyberia-client-hints.service.js

@@ -0,0 +1,152 @@
+/**
+ * @module src/api/cyberia-client-hints/cyberia-client-hints.service.js
+ *
+ * Read-only service layer for client presentation hints.
+ *
+ * Resolution order (highest priority first):
+ *   1. CyberiaClientHints collection — the dedicated presentation-overrides
+ *      collection. Always preferred when present.
+ *   2. Compatibility read on CyberiaInstanceConf with the same `code` —
+ *      covers instances seeded before CyberiaClientHints existed.
+ *   3. Canonical compile-time defaults from
+ *      SharedDefaultsCyberia.js. The C client bakes the
+ *      same defaults at compile time, so this branch returns exactly the
+ *      values the client already has.
+ *
+ * Caching: in-memory TTL cache keyed by instance code. Read-only on the
+ * hot path; cache writes happen on cache miss + DB hit. CMS writes that
+ * mutate the underlying collection should call `clientHintsInvalidate(code)`.
+ *
+ * Output is a plain JSON-friendly object whose shape matches the C
+ * client's compile-time layout.
+ */
+
+import { DataBaseProviderService } from '../../db/DataBaseProvider.js';
+import { loggerFactory } from '../../server/logger.js';
+import { resolveHostKeyContext } from '../../server/conf.js';
+import {
+  buildClientHints,
+  CYBERIA_CLIENT_HINTS_DEFAULTS,
+} from '../../client/components/cyberia/SharedDefaultsCyberia.js';
+
+const logger = loggerFactory(import.meta);
+
+// TTL chosen long enough that bursty client fetches are absorbed, short
+// enough that an editor change shows up within ~30s without manual flush.
+const CACHE_TTL_MS = 30_000;
+
+// One per instance code. value: { data, expiresAt }
+const cache = new Map();
+
+function now() {
+  return Date.now();
+}
+
+function cacheGet(code) {
+  const entry = cache.get(code);
+  if (!entry) return null;
+  if (entry.expiresAt < now()) {
+    cache.delete(code);
+    return null;
+  }
+  return entry.data;
+}
+
+function cacheSet(code, data) {
+  cache.set(code, { data, expiresAt: now() + CACHE_TTL_MS });
+}
+
+/** Invalidate a cache entry. CMS write paths should call this after
+ *  mutating either CyberiaClientHints or CyberiaInstanceConf for
+ *  the given code. */
+export function clientHintsInvalidate(code) {
+  if (code) {
+    cache.delete(code);
+  } else {
+    cache.clear();
+  }
+}
+
+/**
+ * Resolve the merged client-hints document for an instance code.
+ *
+ * @param {string} code
+ * @param {Object} options  Engine routing context.
+ * @param {string} [options.host='default'] DataBaseProviderService host key.
+ * @param {string} [options.path='/']       DataBaseProviderService path key.
+ * @returns {Promise<{data: object, source: 'cache'|'presentation-hints'|'instance-conf'|'defaults'}>}
+ */
+export async function resolveClientHints(code, options = {}) {
+  if (code) {
+    const cached = cacheGet(code);
+    if (cached) {
+      return { data: cached, source: 'cache' };
+    }
+  }
+
+  const host = options.host || 'default';
+  const path = options.path || '/';
+  const context = { host, path };
+  const id = resolveHostKeyContext(context);
+
+  let HintsModel = null;
+  let ConfModel = null;
+  try {
+    HintsModel = DataBaseProviderService.getModel('CyberiaClientHints', context);
+  } catch {
+    // model may not be mounted on this context
+  }
+  try {
+    ConfModel = DataBaseProviderService.getModel('CyberiaInstanceConf', context);
+  } catch {
+    // model may not be mounted on this context
+  }
+
+  if (!HintsModel && !ConfModel) {
+    logger.warn('client-hints: mongoose models not available for', id, '— returning defaults');
+    return { data: CYBERIA_CLIENT_HINTS_DEFAULTS, source: 'defaults' };
+  }
+
+  // 1. Preferred — CyberiaClientHints collection (src/api/cyberia-client-hints/cyberia-client-hints.model.js).
+  if (HintsModel && code) {
+    const hint = await HintsModel.findOne({ code }).lean().catch(() => null);
+    if (hint) {
+      const merged = buildClientHints(hint);
+      cacheSet(code, merged);
+      return { data: merged, source: 'presentation-hints' };
+    }
+  }
+
+  // 2. Compatibility read — for instances seeded before CyberiaClientHints
+  //    existed, look up the same code in CyberiaInstanceConf and read its
+  //    presentation-shaped fields directly.
+  if (ConfModel && code) {
+    const fromConf =
+      (await ConfModel.findOne({ code }).lean().catch(() => null)) ||
+      (await ConfModel.findById(code).lean().catch(() => null));
+    if (fromConf) {
+      const merged = buildClientHints(fromConf);
+      cacheSet(code, merged);
+      return { data: merged, source: 'instance-conf' };
+    }
+  }
+
+  // 3. Any available CyberiaClientHints document — used when the requested
+  //    code has no record yet but another instance (e.g. the one the Go
+  //    server is currently running) does.  This avoids pure built-in
+  //    defaults in fresh environments where only a different code is seeded.
+  if (HintsModel) {
+    const anyHint = await HintsModel.findOne({}).lean().catch(() => null);
+    if (anyHint) {
+      const merged = buildClientHints(anyHint);
+      // Cache under the requested code so subsequent requests are fast,
+      // but with a shorter TTL (5 s) so a proper seed wins quickly.
+      if (code) cache.set(code, { data: merged, expiresAt: now() + 5_000 });
+      return { data: merged, source: 'presentation-hints-fallback' };
+    }
+  }
+
+  // 4. Canonical defaults. Not cached — we do not poison the cache with
+  //    a default that could mask a later DB insert.
+  return { data: CYBERIA_CLIENT_HINTS_DEFAULTS, source: 'defaults' };
+}

package/src/api/cyberia-dialogue/cyberia-dialogue.router.js

@@ -4,26 +4,31 @@ import express from 'express';
 
 const logger = loggerFactory(import.meta);
 
-const CyberiaDialogueRouter = (options) => {
-  const router = express.Router();
-  const authMiddleware = options.authMiddleware;
-  router.post(`/:id`, async (req, res) => await CyberiaDialogueController.post(req, res, options));
-  router.post(`/`, async (req, res) => await CyberiaDialogueController.post(req, res, options));
-  // Direct lookup by code — C client fetches dialogue by code (e.g. "default-lain")
-  router.get(`/code/:code`, async (req, res) => await CyberiaDialogueController.getByCode(req, res, options));
-  router.get(
-    `/:id`,
-    // authMiddleware,
-    async (req, res) => await CyberiaDialogueController.get(req, res, options),
-  );
-  router.get(`/`, async (req, res) => await CyberiaDialogueController.get(req, res, options));
-  router.put(`/:id`, async (req, res) => await CyberiaDialogueController.put(req, res, options));
-  router.put(`/`, async (req, res) => await CyberiaDialogueController.put(req, res, options));
-  router.delete(`/:id`, async (req, res) => await CyberiaDialogueController.delete(req, res, options));
-  router.delete(`/`, async (req, res) => await CyberiaDialogueController.delete(req, res, options));
-  return router;
-};
+class CyberiaDialogueRouter {
+  /**
+   * @param {import('../types.js').RouterOptions} options
+   * @returns {import('express').Router}
+   */
+  static router(options) {
+    const router = express.Router();
+    router.post(`/:id`, async (req, res) => await CyberiaDialogueController.post(req, res, options));
+    router.post(`/`, async (req, res) => await CyberiaDialogueController.post(req, res, options));
+    // Direct lookup by code — C client fetches dialogue by code (e.g. "default-lain")
+    router.get(`/code/:code`, async (req, res) => await CyberiaDialogueController.getByCode(req, res, options));
+    router.get(
+      `/:id`,
+      // options.authMiddleware,
+      async (req, res) => await CyberiaDialogueController.get(req, res, options),
+    );
+    router.get(`/`, async (req, res) => await CyberiaDialogueController.get(req, res, options));
+    router.put(`/:id`, async (req, res) => await CyberiaDialogueController.put(req, res, options));
+    router.put(`/`, async (req, res) => await CyberiaDialogueController.put(req, res, options));
+    router.delete(`/:id`, async (req, res) => await CyberiaDialogueController.delete(req, res, options));
+    router.delete(`/`, async (req, res) => await CyberiaDialogueController.delete(req, res, options));
+    return router;
+  }
+}
 
-const ApiRouter = CyberiaDialogueRouter;
+const ApiRouter = (options) => CyberiaDialogueRouter.router(options);
 
 export { ApiRouter, CyberiaDialogueRouter };

package/src/api/cyberia-dialogue/cyberia-dialogue.service.js

@@ -1,4 +1,4 @@
-import { DataBaseProvider } from '../../db/DataBaseProvider.js';
+import { DataBaseProviderService } from '../../db/DataBaseProvider.js';
 import { loggerFactory } from '../../server/logger.js';
 import { DataQuery } from '../../server/data-query.js';
 
@@ -7,12 +7,12 @@ const logger = loggerFactory(import.meta);
 class CyberiaDialogueService {
   static post = async (req, res, options) => {
     /** @type {import('./cyberia-dialogue.model.js').CyberiaDialogueModel} */
-    const CyberiaDialogue = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.CyberiaDialogue;
+    const CyberiaDialogue = DataBaseProviderService.getModel("CyberiaDialogue", options);
     return await new CyberiaDialogue(req.body).save();
   };
   static get = async (req, res, options) => {
     /** @type {import('./cyberia-dialogue.model.js').CyberiaDialogueModel} */
-    const CyberiaDialogue = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.CyberiaDialogue;
+    const CyberiaDialogue = DataBaseProviderService.getModel("CyberiaDialogue", options);
     if (req.params.id) return await CyberiaDialogue.findById(req.params.id);
 
     // Parse query parameters using DataQuery helper
@@ -28,18 +28,18 @@ class CyberiaDialogueService {
   };
   static put = async (req, res, options) => {
     /** @type {import('./cyberia-dialogue.model.js').CyberiaDialogueModel} */
-    const CyberiaDialogue = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.CyberiaDialogue;
+    const CyberiaDialogue = DataBaseProviderService.getModel("CyberiaDialogue", options);
     return await CyberiaDialogue.findByIdAndUpdate(req.params.id, req.body);
   };
   static delete = async (req, res, options) => {
     /** @type {import('./cyberia-dialogue.model.js').CyberiaDialogueModel} */
-    const CyberiaDialogue = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.CyberiaDialogue;
+    const CyberiaDialogue = DataBaseProviderService.getModel("CyberiaDialogue", options);
     if (req.params.id) return await CyberiaDialogue.findByIdAndDelete(req.params.id);
     else return await CyberiaDialogue.deleteMany();
   };
   static getByCode = async (req, res, options) => {
     /** @type {import('./cyberia-dialogue.model.js').CyberiaDialogueModel} */
-    const CyberiaDialogue = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.CyberiaDialogue;
+    const CyberiaDialogue = DataBaseProviderService.getModel("CyberiaDialogue", options);
     const { code } = req.params;
     if (!code) throw new Error('code parameter is required');
     const data = await CyberiaDialogue.find({ code }).sort({ order: 1 }).lean();

package/src/api/cyberia-entity/cyberia-entity.router.js

@@ -4,24 +4,28 @@ import express from 'express';
 
 const logger = loggerFactory(import.meta);
 
-const CyberiaEntityRouter = (options) => {
-  const router = express.Router();
-  const authMiddleware = options.authMiddleware;
-  router.post(`/:id`, async (req, res) => await CyberiaEntityController.post(req, res, options));
-  router.post(`/`, async (req, res) => await CyberiaEntityController.post(req, res, options));
-  router.get(
-    `/:id`,
-    // authMiddleware,
-    async (req, res) => await CyberiaEntityController.get(req, res, options),
-  );
-  router.get(`/`, async (req, res) => await CyberiaEntityController.get(req, res, options));
-  router.put(`/:id`, async (req, res) => await CyberiaEntityController.put(req, res, options));
-  router.put(`/`, async (req, res) => await CyberiaEntityController.put(req, res, options));
-  router.delete(`/:id`, async (req, res) => await CyberiaEntityController.delete(req, res, options));
-  router.delete(`/`, async (req, res) => await CyberiaEntityController.delete(req, res, options));
-  return router;
-};
+class CyberiaEntityRouter {
+  /**
+   * @param {import('../types.js').RouterOptions} options
+   * @returns {import('express').Router}
+   */
+  static router(options) {
+    const router = express.Router();
+    router.post(`/:id`, async (req, res) => await CyberiaEntityController.post(req, res, options));
+    router.post(`/`, async (req, res) => await CyberiaEntityController.post(req, res, options));
+    router.get(`/:id`,
+      // options.authMiddleware,
+      async (req, res) => await CyberiaEntityController.get(req, res, options),
+    );
+    router.get(`/`, async (req, res) => await CyberiaEntityController.get(req, res, options));
+    router.put(`/:id`, async (req, res) => await CyberiaEntityController.put(req, res, options));
+    router.put(`/`, async (req, res) => await CyberiaEntityController.put(req, res, options));
+    router.delete(`/:id`, async (req, res) => await CyberiaEntityController.delete(req, res, options));
+    router.delete(`/`, async (req, res) => await CyberiaEntityController.delete(req, res, options));
+    return router;
+  }
+}
 
-const ApiRouter = CyberiaEntityRouter;
+const ApiRouter = (options) => CyberiaEntityRouter.router(options);
 
 export { ApiRouter, CyberiaEntityRouter };

package/src/api/cyberia-entity/cyberia-entity.service.js

@@ -1,4 +1,4 @@
-import { DataBaseProvider } from '../../db/DataBaseProvider.js';
+import { DataBaseProviderService } from '../../db/DataBaseProvider.js';
 import { loggerFactory } from '../../server/logger.js';
 import { DataQuery } from '../../server/data-query.js';
 
@@ -7,12 +7,12 @@ const logger = loggerFactory(import.meta);
 class CyberiaEntityService {
   static post = async (req, res, options) => {
     /** @type {import('./cyberia-entity.model.js').CyberiaEntityModel} */
-    const CyberiaEntity = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.CyberiaEntity;
+    const CyberiaEntity = DataBaseProviderService.getModel("CyberiaEntity", options);
     return await new CyberiaEntity(req.body).save();
   };
   static get = async (req, res, options) => {
     /** @type {import('./cyberia-entity.model.js').CyberiaEntityModel} */
-    const CyberiaEntity = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.CyberiaEntity;
+    const CyberiaEntity = DataBaseProviderService.getModel("CyberiaEntity", options);
     if (req.params.id) return await CyberiaEntity.findById(req.params.id);
 
     // Parse query parameters using DataQuery helper
@@ -28,12 +28,12 @@ class CyberiaEntityService {
   };
   static put = async (req, res, options) => {
     /** @type {import('./cyberia-entity.model.js').CyberiaEntityModel} */
-    const CyberiaEntity = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.CyberiaEntity;
+    const CyberiaEntity = DataBaseProviderService.getModel("CyberiaEntity", options);
     return await CyberiaEntity.findByIdAndUpdate(req.params.id, req.body);
   };
   static delete = async (req, res, options) => {
     /** @type {import('./cyberia-entity.model.js').CyberiaEntityModel} */
-    const CyberiaEntity = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.CyberiaEntity;
+    const CyberiaEntity = DataBaseProviderService.getModel("CyberiaEntity", options);
     if (req.params.id) return await CyberiaEntity.findByIdAndDelete(req.params.id);
     else return await CyberiaEntity.deleteMany();
   };

package/src/api/cyberia-instance/cyberia-fallback-world.js

@@ -31,13 +31,69 @@ import {
   OccupancyGrid,
 } from './cyberia-world-generator.js';
 
-import { CYBERIA_INSTANCE_CONF_DEFAULTS } from '../cyberia-instance-conf/cyberia-instance-conf.defaults.js';
+import {
+  CYBERIA_INSTANCE_CONF_DEFAULTS,
+  ENTITY_TYPE_DEFAULTS,
+  RESOURCE_ENTITY_TYPE_DEFAULTS,
+  DefaultCyberiaItems,
+} from '../cyberia-server-defaults/cyberia-server-defaults.js';
+import {
+  CYBERIA_CLIENT_HINTS_DEFAULTS,
+  PALETTE,
+} from '../../client/components/cyberia/SharedDefaultsCyberia.js';
 
 // ── Defaults ─────────────────────────────────────────────────────────────────
 
 const DEFAULT_MAP_COUNT = 4;
 const DEFAULT_GRID_SIZE = 64;
 
+// ── Asset-id integrity ──────────────────────────────────────────────────────
+//
+// Every item id that the fallback world can place on a map must also be
+// present in DefaultCyberiaItems, otherwise the `import-default-items` seed
+// will not create an ObjectLayer for it and the runtime client will fall
+// back to a solid-colour rectangle instead of the intended sprite.
+//
+// auditFallbackItemIds() returns the set of unknown ids encountered in the
+// canonical defaults so callers (CLI, test harness, gRPC fallback path)
+// can surface drift immediately. Returns an empty array when in sync.
+
+const KNOWN_DEFAULT_ITEM_IDS = new Set(DefaultCyberiaItems.map((e) => e.item.id));
+
+function collectReferencedItemIds() {
+  const ids = new Set();
+  const push = (id) => { if (typeof id === 'string' && id.length > 0) ids.add(id); };
+
+  for (const e of ENTITY_TYPE_DEFAULTS) {
+    (e.liveItemIds || []).forEach(push);
+    (e.deadItemIds || []).forEach(push);
+    (e.dropItemIds || []).forEach(push);
+    (e.defaultObjectLayers || []).forEach((ol) => push(ol.itemId));
+  }
+  for (const r of RESOURCE_ENTITY_TYPE_DEFAULTS) {
+    (r.liveItemIds || []).forEach(push);
+    (r.deadItemIds || []).forEach(push);
+    (r.dropItemIds || []).forEach(push);
+  }
+  return ids;
+}
+
+/**
+ * Audit every item id the fallback world can place against the canonical
+ * DefaultCyberiaItems registry.  Returns an array of missing ids; an empty
+ * array means the registry is in sync.
+ *
+ * @returns {string[]}
+ */
+function auditFallbackItemIds() {
+  const referenced = collectReferencedItemIds();
+  const missing = [];
+  for (const id of referenced) {
+    if (!KNOWN_DEFAULT_ITEM_IDS.has(id)) missing.push(id);
+  }
+  return missing.sort();
+}
+
 // ── Single map generator ─────────────────────────────────────────────────────
 
 /**
@@ -45,7 +101,7 @@ const DEFAULT_GRID_SIZE = 64;
  * Everything except floor tiles is randomized.
  *
  * @param {string} mapCode
- * @param {Array} colors             Palette from CYBERIA_INSTANCE_CONF_DEFAULTS.
+ * @param {Array} colors             Palette (PALETTE from SharedDefaultsCyberia).
  * @param {object} [opts]
  * @param {number} [opts.gridSize]
  * @param {number} [opts.obstacleCount]
@@ -129,9 +185,27 @@ function generateFallbackWorld(opts = {}) {
     foregroundCount,
     botCount,
     resourceCount,
-    colors = CYBERIA_INSTANCE_CONF_DEFAULTS.colors,
+    // Palette lives in SharedDefaultsCyberia (presentation-owned). The
+    // world generator only uses it to stamp a cosmetic rgba(...) string on
+    // entities so the browser editor / preview can render a coloured
+    // fallback before atlases load. The C client resolves real colours
+    // through domain/presentation_runtime — it does not read this value.
+    colors = PALETTE,
   } = opts;
 
+  // Surface item-id drift loudly on the very first build, so a missing
+  // `bin/cyberia run-workflow import-default-items` run shows up at startup
+  // instead of as silent grey rectangles later.
+  const missing = auditFallbackItemIds();
+  if (missing.length > 0) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      '[cyberia-fallback-world] item ids referenced by defaults but absent from DefaultCyberiaItems:',
+      missing.join(', '),
+      '— run `node bin/cyberia run-workflow import-default-items` after adding them.',
+    );
+  }
+
   // Generate map codes.
   const mapCodes = [];
   for (let i = 0; i < mapCount; i++) {
@@ -169,10 +243,11 @@ function generateFallbackWorld(opts = {}) {
     portals,
     topology,
     config: CYBERIA_INSTANCE_CONF_DEFAULTS,
+    presentationHints: CYBERIA_CLIENT_HINTS_DEFAULTS,
     _fallback: true,
   };
 }
 
 // ── Public API ───────────────────────────────────────────────────────────────
 
-export { generateFallbackWorld, generateFallbackMap };
+export { generateFallbackWorld, generateFallbackMap, auditFallbackItemIds };