@underpostnet/cyberia 3.2.80

package/src/api/cyberia-instance/cyberia-instance.model.js

@@ -0,0 +1,117 @@
+import { Schema, model } from 'mongoose';
+
+/**
+ * Directed edge in a graph.
+ * Each portal represents an adjacency relation:
+ * source node -> target node
+ */
+const PortalEdgeSchema = new Schema(
+  {
+    // Origin node (graph source vertex)
+    sourceMapCode: { type: String, required: true, trim: true },
+    sourceCellX: { type: Number },
+    sourceCellY: { type: Number },
+
+    // Destination node (graph target vertex)
+    targetMapCode: { type: String, required: true, trim: true },
+    targetCellX: { type: Number },
+    targetCellY: { type: Number },
+
+    // Transport behaviour of this edge:
+    //   inter-portal  — teleport to a portal entity on another map
+    //   inter-random  — teleport to a random walkable cell on another map
+    //   intra-random  — teleport to a random walkable cell on the same map
+    //   intra-portal  — teleport to a portal entity on the same map
+    portalMode: {
+      type: String,
+      enum: ['inter-portal', 'inter-random', 'intra-random', 'intra-portal'],
+      default: 'inter-portal',
+    },
+  },
+  { _id: false },
+);
+
+/**
+ * Authoritative initial spawn position for new players joining this instance.
+ * When `random` is false and `sourceMapCode` names a loaded map, players spawn at
+ * (sourceCellX, sourceCellY) on it; otherwise (random true, or no/unknown map)
+ * the server spawns them at a random walkable cell on a random map.
+ */
+const PlayerSpawnSchema = new Schema(
+  {
+    sourceMapCode: { type: String, trim: true },
+    sourceCellX: { type: Number },
+    sourceCellY: { type: Number },
+    random: { type: Boolean, default: false },
+  },
+  { _id: false },
+);
+
+/**
+ * Graph container / instance.
+ * The instance stores:
+ * - nodes: cyberiaMapCodes[]
+ * - edges: portals[]
+ */
+const CyberiaInstanceSchema = new Schema(
+  {
+    // Instance identifier
+    code: { type: String, default: '', trim: true, unique: true },
+
+    name: { type: String, default: '', trim: true },
+    description: { type: String, default: '' },
+    tags: { type: [String], default: [] },
+    creator: { type: Schema.Types.ObjectId, ref: 'User' },
+    status: { type: String, default: 'unlisted' },
+    thumbnail: { type: Schema.Types.ObjectId, ref: 'File' },
+
+    // Vertex set of the graph
+    cyberiaMapCodes: { type: [String], default: [] },
+
+    // Instance-level object layer item IDs. Each entry binds an item id to the
+    // instance and flags whether it seeds every player's starting inventory
+    // (defaultPlayerInventory → merged into the player entityDefault's
+    // defaultObjectLayers when the world is served to cyberia-server).
+    itemIds: {
+      type: [
+        {
+          id: { type: String, required: true },
+          defaultPlayerInventory: { type: Boolean, default: false },
+        },
+      ],
+      default: [],
+    },
+
+    // Directed edge set of the graph
+    portals: { type: [PortalEdgeSchema], default: [] },
+
+    // Authoritative initial spawn for new players (see PlayerSpawnSchema).
+    playerSpawn: { type: PlayerSpawnSchema, default: () => ({}) },
+
+    // Optional topology generation mode
+    seed: { type: String, default: '' },
+    topologyMode: {
+      type: String,
+      enum: ['manual', 'procedural', 'hybrid'],
+      default: 'hybrid',
+    },
+
+    // Game server configuration (all tuning parameters live in a separate document).
+    // Linked to CyberiaInstanceConf.instanceCode === this.code.
+    conf: { type: Schema.Types.ObjectId, ref: 'CyberiaInstanceConf' },
+  },
+  { timestamps: true },
+);
+
+/**
+ * Indexes for fast adjacency lookups.
+ * Useful for traversing the graph by source or target node.
+ */
+CyberiaInstanceSchema.index({ 'portals.sourceMapCode': 1 });
+CyberiaInstanceSchema.index({ 'portals.targetMapCode': 1 });
+
+const CyberiaInstanceModel = model('CyberiaInstance', CyberiaInstanceSchema);
+
+const ProviderSchema = CyberiaInstanceSchema;
+
+export { CyberiaInstanceSchema, CyberiaInstanceModel, ProviderSchema };

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

@@ -0,0 +1,75 @@
+import express from 'express';
+import { registerCrudRoutes } from '../../server/middlewares.js';
+import { userGuard, moderatorGuard } from '../../server/auth.js';
+import { CyberiaInstanceController } from './cyberia-instance.controller.js';
+
+class CyberiaInstanceRouter {
+  /**
+   * @param {import('../types.js').RouterOptions} options
+   * @returns {import('express').Router}
+   */
+  static router(options) {
+    const router = express.Router();
+    // ── Custom actions (must come before generic /:id routes) ──────────────
+    // Boot transport — REST fallback of the gRPC CyberiaDataService, consumed
+    // server-to-server by cyberia-server (ENGINE_API_BASE_URL) when the engine
+    // gRPC server (ENGINE_GRPC_ADDRESS) is not enabled. Unauthenticated for
+    // parity with the internal-network insecure gRPC channel.
+    router.get(`/boot/ping`, async (req, res) => await CyberiaInstanceController.bootPing(req, res, options));
+    router.get(
+      `/boot/object-layers`,
+      async (req, res) => await CyberiaInstanceController.bootObjectLayerBatch(req, res, options),
+    );
+    router.get(
+      `/boot/object-layer-manifest`,
+      async (req, res) => await CyberiaInstanceController.bootObjectLayerManifest(req, res, options),
+    );
+    router.get(
+      `/boot/object-layer/:itemId`,
+      async (req, res) => await CyberiaInstanceController.bootObjectLayer(req, res, options),
+    );
+    router.get(`/boot/map/:mapCode`, async (req, res) => await CyberiaInstanceController.bootMapData(req, res, options));
+    router.get(
+      `/boot/full-instance/:instanceCode`,
+      async (req, res) => await CyberiaInstanceController.bootFullInstance(req, res, options),
+    );
+    router.get(
+      `/boot/full-instance`,
+      async (req, res) => await CyberiaInstanceController.bootFullInstance(req, res, options),
+    );
+    router.get(`/fallback-world`, async (req, res) => await CyberiaInstanceController.fallbackWorld(req, res, options));
+    // Instance Map — static topology/presence plus dynamic player capability activity.
+    router.get(
+      `/instance-map/:instanceCode/static`,
+      async (req, res) => await CyberiaInstanceController.instanceMapStatic(req, res, options),
+    );
+    router.get(
+      `/instance-map/:instanceCode/dynamic`,
+      async (req, res) => await CyberiaInstanceController.instanceMapDynamic(req, res, options),
+    );
+    // Cached node-background capture of a fallback-world map (PNG).
+    router.get(
+      `/instance-map/:instanceCode/preview/:mapCode`,
+      async (req, res) => await CyberiaInstanceController.instanceMapPreview(req, res, options),
+    );
+    // Hot reload — engine-cyberia -> cyberia-server control trigger. Elevated
+    // privilege only; the internal API key stays server-side.
+    router.post(
+      `/:id/hot-reload`,
+      options.authMiddleware,
+      moderatorGuard,
+      async (req, res) => await CyberiaInstanceController.hotReload(req, res, options),
+    );
+    router.get(
+      `/:id/portal-connect`,
+      options.authMiddleware,
+      userGuard,
+      async (req, res) => await CyberiaInstanceController.portalConnect(req, res, options),
+    );
+    return registerCrudRoutes(router, CyberiaInstanceController, options);
+  }
+}
+
+const ApiRouter = (options) => CyberiaInstanceRouter.router(options);
+
+export { ApiRouter, CyberiaInstanceRouter };

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

@@ -0,0 +1,190 @@
+import { DataBaseProviderService } from '../../db/DataBaseProvider.js';
+import { loggerFactory } from '../../server/logger.js';
+import { DataQuery } from '../../server/data-query.js';
+import { connectPortals } from './cyberia-portal-connector.js';
+import {
+  generateFallbackWorld,
+  fallbackListInstance,
+  DEFAULT_FALLBACK_INSTANCE_CODE,
+} from './cyberia-fallback-world.js';
+import { triggerHotReload } from '../../projects/cyberia/hot-reload-trigger.js';
+
+const logger = loggerFactory(import.meta);
+
+class CyberiaInstanceService {
+  static post = async (req, res, options) => {
+    /** @type {import('./cyberia-instance.model.js').CyberiaInstanceModel} */
+    const CyberiaInstance = DataBaseProviderService.getModel('CyberiaInstance', options);
+    const CyberiaInstanceConf = DataBaseProviderService.getModel('CyberiaInstanceConf', options);
+    if (req.auth && req.auth.user) req.body.creator = req.auth.user._id;
+    const instance = await new CyberiaInstance(req.body).save();
+
+    // Auto-upsert a CyberiaInstanceConf for this instance using schema defaults.
+    // $setOnInsert ensures existing conf documents are never overwritten.
+    if (instance.code && CyberiaInstanceConf) {
+      try {
+        const conf = await CyberiaInstanceConf.findOneAndUpdate(
+          { instanceCode: instance.code },
+          { $setOnInsert: { instanceCode: instance.code } },
+          { upsert: true, returnDocument: 'after' },
+        );
+        if (conf && !instance.conf) {
+          await CyberiaInstance.findByIdAndUpdate(instance._id, { conf: conf._id });
+          instance.conf = conf._id;
+        }
+      } catch (e) {
+        logger.error('auto-upsert CyberiaInstanceConf failed:', e);
+      }
+    }
+
+    return instance;
+  };
+  static get = async (req, res, options) => {
+    /** @type {import('./cyberia-instance.model.js').CyberiaInstanceModel} */
+    const CyberiaInstance = DataBaseProviderService.getModel('CyberiaInstance', options);
+    const populateCreator = { path: 'creator', model: 'User', select: '_id username' };
+    if (req.params.id) return await CyberiaInstance.findById(req.params.id).populate(populateCreator);
+
+    // Parse query parameters using DataQuery helper
+    const { query, sort, skip, limit, page } = DataQuery.parse(req.query);
+
+    const [data, total] = await Promise.all([
+      CyberiaInstance.find(query).sort(sort).limit(limit).skip(skip).populate(populateCreator),
+      CyberiaInstance.countDocuments(query),
+    ]);
+
+    // Opt-in (?fallback=true): surface the always-on TEST world so the selection
+    // view is never empty. Skipped when a real TEST instance is already present.
+    const injectFallback =
+      /^(true|1)$/i.test(String(req.query.fallback || '')) &&
+      !data.some((d) => d.code === DEFAULT_FALLBACK_INSTANCE_CODE);
+    const items = injectFallback ? [...data, fallbackListInstance()] : data;
+    const count = injectFallback ? total + 1 : total;
+
+    const totalPages = Math.ceil(count / limit);
+    return { data: items, total: count, page, totalPages };
+  };
+  static put = async (req, res, options) => {
+    /** @type {import('./cyberia-instance.model.js').CyberiaInstanceModel} */
+    const CyberiaInstance = DataBaseProviderService.getModel('CyberiaInstance', options);
+    const instance = await CyberiaInstance.findById(req.params.id);
+    if (!instance) throw new Error('instance not found');
+    if (req.auth.user.role !== 'admin' && String(instance.creator) !== String(req.auth.user._id))
+      throw new Error('insufficient permission');
+    if (req.body.thumbnail && instance.thumbnail && String(req.body.thumbnail) !== String(instance.thumbnail)) {
+      const File = DataBaseProviderService.getModel('File', options);
+      await File.findByIdAndDelete(instance.thumbnail);
+    }
+    return await CyberiaInstance.findByIdAndUpdate(req.params.id, req.body, { returnDocument: 'after' });
+  };
+  /**
+   * Central portal connector endpoint.
+   *
+   * Delegates topology computation to the pure-function `connectPortals()`
+   * from cyberia-portal-connector.js so the same logic can be used by the
+   * GUI without a DB dependency.
+   *
+   * Builds a minimal ring connecting all maps and assigns random portal
+   * subtypes to remaining portals.  Does NOT generate procedural entities —
+   * entity generation is handled exclusively by the fallback world logic
+   * (cyberia-world-generator.js).
+   *
+   *   ?persist=true  — save generated portals to DB
+   */
+  /**
+   * Ask a running cyberia-server to rebuild its world now (gRPC control
+   * service, REST fallback). Moderator/admin only — the route guards the
+   * caller; the internal CYBERIA_SERVER_API_KEY never leaves the engine.
+   */
+  static hotReload = async (req, res, options) => {
+    const CyberiaInstance = DataBaseProviderService.getModel('CyberiaInstance', options);
+    const { serverUrl, mode } = req.body || {};
+    if (!serverUrl) throw new Error('serverUrl is required');
+
+    // Resolve the instance the component is editing so the target server can
+    // reject a trigger aimed at a different world.
+    let instanceCode = req.body?.instanceCode || '';
+    if (!instanceCode && req.params.id) {
+      const instance = await CyberiaInstance.findById(req.params.id).select('code').lean();
+      instanceCode = instance?.code || '';
+    }
+
+    const { transport, result, grpcError } = await triggerHotReload({ serverUrl, instanceCode, mode });
+    return { transport, instanceCode, grpcError, ...result };
+  };
+
+  static portalConnect = async (req, res, options) => {
+    const CyberiaInstance = DataBaseProviderService.getModel('CyberiaInstance', options);
+    const CyberiaMap = DataBaseProviderService.getModel('CyberiaMap', options);
+
+    const instance = await CyberiaInstance.findById(req.params.id).lean();
+    if (!instance) throw new Error('instance not found');
+
+    const mapCodes = instance.cyberiaMapCodes || [];
+
+    // Load maps with the fields needed by the connector.
+    const mapDocs = await CyberiaMap.find(
+      { code: { $in: mapCodes } },
+      {
+        code: 1,
+        gridX: 1,
+        gridY: 1,
+        entities: 1,
+      },
+    ).lean();
+
+    // ── Portal topology (pure function) ──────────────────────────────────
+    const result = connectPortals(mapCodes, mapDocs);
+
+    // ── Persist to DB when requested ─────────────────────────────────────
+    const persist = req.query?.persist === 'true';
+    if (persist) {
+      await CyberiaInstance.findByIdAndUpdate(req.params.id, { portals: result.portals });
+    }
+
+    return {
+      ...result,
+      persisted: persist,
+    };
+  };
+
+  static delete = async (req, res, options) => {
+    /** @type {import('./cyberia-instance.model.js').CyberiaInstanceModel} */
+    const CyberiaInstance = DataBaseProviderService.getModel('CyberiaInstance', options);
+    if (req.params.id) {
+      const instance = await CyberiaInstance.findById(req.params.id);
+      if (!instance) throw new Error('instance not found');
+      if (req.auth.user.role !== 'admin' && String(instance.creator) !== String(req.auth.user._id))
+        throw new Error('insufficient permission');
+      if (instance.thumbnail) {
+        const File = DataBaseProviderService.getModel('File', options);
+        await File.findByIdAndDelete(instance.thumbnail);
+      }
+      return await CyberiaInstance.findByIdAndDelete(req.params.id);
+    } else return await CyberiaInstance.deleteMany();
+  };
+
+  /**
+   * Return an in-memory procedural fallback world.
+   *
+   * Nothing is persisted to MongoDB.  The world is regenerated on every
+   * call but stays deterministic for a given seed.
+   *
+   * Query params:
+   *   ?mapCount=<number>       — maps to generate  (default: 4)
+   *   ?botCount=<number>       — bots per map      (random 8–16 if omitted)
+   *   ?obstacleCount=<number>  — obstacles per map  (random 12–20 if omitted)
+   *   ?foregroundCount=<number>— foreground per map (random 6–12 if omitted)
+   */
+  static fallbackWorld = async (req) => {
+    const q = req.query || {};
+    return generateFallbackWorld({
+      mapCount: q.mapCount ? parseInt(q.mapCount, 10) : undefined,
+      botCount: q.botCount ? parseInt(q.botCount, 10) : undefined,
+      obstacleCount: q.obstacleCount ? parseInt(q.obstacleCount, 10) : undefined,
+      foregroundCount: q.foregroundCount ? parseInt(q.foregroundCount, 10) : undefined,
+    });
+  };
+}
+
+export { CyberiaInstanceService };

package/src/api/cyberia-instance/cyberia-portal-connector.js

@@ -0,0 +1,260 @@
+/**
+ * Central Portal Connector — pure-function module.
+ *
+ * Sole responsibility: build, validate, and connect portal topology
+ * for a CyberiaInstance.  Given map documents with portal entities,
+ * produces a minimal ring that guarantees full reachability, then
+ * assigns random portal behaviour to every remaining (unconnected)
+ * portal.
+ *
+ * Shared by the backend (CyberiaInstanceService.portalConnect) and the
+ * GUI (Instance Engine "Portal Connector" button) so the same logic
+ * runs everywhere without a DB dependency.
+ *
+ * This module does NOT generate procedural entities (obstacles,
+ * foreground, resources, bots, etc.).  For that, see
+ * cyberia-world-generator.js.
+ *
+ * All exported functions are stateless and synchronous.
+ *
+ * @module src/api/cyberia-instance/cyberia-portal-connector
+ */
+
+// ── Portal mode constants ────────────────────────────────────────────────────
+
+/**
+ * Canonical portal mode strings.
+ * @enum {string}
+ */
+const PORTAL_MODES = Object.freeze({
+  INTER_PORTAL: 'inter-portal', // teleport to a portal on another map
+  INTER_RANDOM: 'inter-random', // teleport to a random spot on another map
+  INTRA_RANDOM: 'intra-random', // teleport to a random spot on the same map
+  INTRA_PORTAL: 'intra-portal', // teleport to a portal on the same map
+});
+
+/**
+ * All portal mode values as an array (for random selection).
+ * @type {string[]}
+ */
+const PORTAL_MODE_LIST = Object.values(PORTAL_MODES);
+
+/**
+ * Map from portal mode to its palette colour key.
+ * @type {Record<string, string>}
+ */
+const PORTAL_MODE_COLOR_KEY = Object.freeze({
+  [PORTAL_MODES.INTER_PORTAL]: 'PORTAL_INTER_PORTAL',
+  [PORTAL_MODES.INTER_RANDOM]: 'PORTAL_INTER_RANDOM',
+  [PORTAL_MODES.INTRA_RANDOM]: 'PORTAL_INTRA_RANDOM',
+  [PORTAL_MODES.INTRA_PORTAL]: 'PORTAL_INTRA_PORTAL',
+});
+
+/**
+ * Portal modes available for extra (non-ring) portals.
+ * The ring always uses INTER_PORTAL; extras are randomly chosen from these.
+ * @type {string[]}
+ */
+const EXTRA_PORTAL_MODES = [PORTAL_MODES.INTRA_PORTAL, PORTAL_MODES.INTRA_RANDOM, PORTAL_MODES.INTER_RANDOM];
+
+// ── Portal topology builders ─────────────────────────────────────────────────
+
+/**
+ * Extract all portal-type entities from each map document and build
+ * a lookup: `{ [mapCode]: portalEntity[] }`.
+ *
+ * @param {Array<{ code: string, entities: Array<{ entityType: string, portalSubtype?: string, initCellX: number, initCellY: number }> }>} maps
+ * @returns {Record<string, object[]>}
+ */
+function indexPortalEntities(maps) {
+  const idx = {};
+  for (const map of maps) {
+    idx[map.code] = (map.entities || []).filter((e) => e.entityType === 'portal');
+  }
+  return idx;
+}
+
+/**
+ * Build portal edges from a set of maps with portal entities.
+ *
+ * Phase 1 — **Ring guarantee**: creates an inter-portal ring that
+ * connects every map in a circle (0→1→2→…→n-1→0) so that every map
+ * is reachable from every other map.  One portal entity per map is
+ * consumed for the ring.
+ *
+ * Phase 2 — **Extra edges**: remaining portal entities (those not used
+ * in the ring) produce edges according to their `portalSubtype`:
+ *   inter-portal  → portal on a DIFFERENT map
+ *   inter-random  → random pos on a DIFFERENT map
+ *   intra-random  → random pos on the SAME map
+ *   intra-portal  → portal on the SAME map
+ *
+ * @param {string[]} orderedCodes  Map codes in instance order.
+ * @param {Record<string, object[]>} portalIndex  From `indexPortalEntities`.
+ * @returns {{ portals: object[], topology: string }}
+ */
+function buildTopologyFromSubtypes(orderedCodes, portalIndex) {
+  const n = orderedCodes.length;
+  if (n < 1) return { portals: [], topology: 'none' };
+
+  const portals = [];
+  const usedInRing = new Set();
+
+  // ── Phase 1: Guaranteed inter-portal ring ───────────────────────────
+  // Each map links to the next in a circle: 0→1→2→…→(n-1)→0.
+  if (n >= 2) {
+    for (let i = 0; i < n; i++) {
+      const srcCode = orderedCodes[i];
+      const tgtCode = orderedCodes[(i + 1) % n];
+
+      // Prefer an unused inter-portal entity as source; fall back to any unused, then any
+      const srcAll = portalIndex[srcCode] || [];
+      const srcInterUnused = srcAll.filter(
+        (e) => (e.portalSubtype || PORTAL_MODES.INTER_PORTAL) === PORTAL_MODES.INTER_PORTAL && !usedInRing.has(e),
+      );
+      const srcAnyUnused = srcAll.filter((e) => !usedInRing.has(e));
+      const srcEnt = srcInterUnused[0] || srcAnyUnused[0] || srcAll[0];
+
+      // Target: pick any portal on the target map for landing coordinates
+      const tgtAll = portalIndex[tgtCode] || [];
+      const tgtEnt = tgtAll.length > 0 ? tgtAll[Math.floor(Math.random() * tgtAll.length)] : null;
+
+      if (srcEnt) {
+        usedInRing.add(srcEnt);
+        portals.push({
+          sourceMapCode: srcCode,
+          sourceCellX: srcEnt.initCellX ?? 0,
+          sourceCellY: srcEnt.initCellY ?? 0,
+          targetMapCode: tgtCode,
+          targetCellX: tgtEnt?.initCellX ?? 0,
+          targetCellY: tgtEnt?.initCellY ?? 0,
+          portalMode: PORTAL_MODES.INTER_PORTAL,
+        });
+      }
+    }
+  }
+
+  // ── Phase 2: Extra edges from remaining portals ─────────────────────
+  const otherMap = (srcCode) => {
+    if (n < 2) return srcCode;
+    let code;
+    do {
+      code = orderedCodes[Math.floor(Math.random() * n)];
+    } while (code === srcCode && n > 1);
+    return code;
+  };
+
+  for (const srcCode of orderedCodes) {
+    const allOnMap = portalIndex[srcCode] || [];
+    const remaining = allOnMap.filter((e) => !usedInRing.has(e));
+
+    for (const srcEnt of remaining) {
+      // If the entity already has an explicit subtype, honour it;
+      // otherwise assign a random mode (matching fallback-world behaviour).
+      const sub = srcEnt.portalSubtype || PORTAL_MODE_LIST[Math.floor(Math.random() * PORTAL_MODE_LIST.length)];
+
+      switch (sub) {
+        case PORTAL_MODES.INTER_PORTAL: {
+          const tgtCode = otherMap(srcCode);
+          const candidates = portalIndex[tgtCode] || [];
+          const tgtEnt = candidates.length > 0 ? candidates[Math.floor(Math.random() * candidates.length)] : null;
+          portals.push({
+            sourceMapCode: srcCode,
+            sourceCellX: srcEnt.initCellX ?? 0,
+            sourceCellY: srcEnt.initCellY ?? 0,
+            targetMapCode: tgtCode,
+            targetCellX: tgtEnt?.initCellX ?? 0,
+            targetCellY: tgtEnt?.initCellY ?? 0,
+            portalMode: PORTAL_MODES.INTER_PORTAL,
+          });
+          break;
+        }
+        case PORTAL_MODES.INTER_RANDOM: {
+          const tgtCode = otherMap(srcCode);
+          portals.push({
+            sourceMapCode: srcCode,
+            sourceCellX: srcEnt.initCellX ?? 0,
+            sourceCellY: srcEnt.initCellY ?? 0,
+            targetMapCode: tgtCode,
+            targetCellX: -1,
+            targetCellY: -1,
+            portalMode: PORTAL_MODES.INTER_RANDOM,
+          });
+          break;
+        }
+        case PORTAL_MODES.INTRA_RANDOM: {
+          portals.push({
+            sourceMapCode: srcCode,
+            sourceCellX: srcEnt.initCellX ?? 0,
+            sourceCellY: srcEnt.initCellY ?? 0,
+            targetMapCode: srcCode,
+            targetCellX: -1,
+            targetCellY: -1,
+            portalMode: PORTAL_MODES.INTRA_RANDOM,
+          });
+          break;
+        }
+        case PORTAL_MODES.INTRA_PORTAL: {
+          const candidates = allOnMap.filter(
+            (e) => e !== srcEnt && (e.initCellX !== srcEnt.initCellX || e.initCellY !== srcEnt.initCellY),
+          );
+          const tgtEnt = candidates.length > 0 ? candidates[Math.floor(Math.random() * candidates.length)] : null;
+          portals.push({
+            sourceMapCode: srcCode,
+            sourceCellX: srcEnt.initCellX ?? 0,
+            sourceCellY: srcEnt.initCellY ?? 0,
+            targetMapCode: srcCode,
+            targetCellX: tgtEnt?.initCellX ?? 0,
+            targetCellY: tgtEnt?.initCellY ?? 0,
+            portalMode: PORTAL_MODES.INTRA_PORTAL,
+          });
+          break;
+        }
+      }
+    }
+  }
+
+  return { portals, topology: n === 1 ? 'intra-only' : 'ring+mixed' };
+}
+
+/**
+ * Central portal-connect pipeline.
+ *
+ * Given an instance's ordered map codes and the full map documents (with
+ * entities), returns the auto-generated portal edge list.
+ *
+ * @param {string[]} mapCodes       Instance's `cyberiaMapCodes` array.
+ * @param {Array<{ code: string, entities: object[] }>} maps  Map documents (lean or JSON).
+ * @returns {{ portals: object[], topology: string, mapCount: number }}
+ */
+function connectPortals(mapCodes, maps) {
+  if (!mapCodes || mapCodes.length < 1) {
+    return { portals: [], topology: 'none', mapCount: mapCodes?.length ?? 0, message: 'Need at least 1 map.' };
+  }
+
+  const portalIndex = indexPortalEntities(maps);
+
+  // Filter to codes that actually exist in the fetched maps.
+  const knownCodes = new Set(maps.map((m) => m.code));
+  const ordered = mapCodes.filter((c) => knownCodes.has(c));
+  if (ordered.length < 1) {
+    return { portals: [], topology: 'none', mapCount: ordered.length, message: 'Need at least 1 map.' };
+  }
+
+  const { portals, topology } = buildTopologyFromSubtypes(ordered, portalIndex);
+  return { portals, topology, mapCount: ordered.length };
+}
+
+// ── Public API ───────────────────────────────────────────────────────────────
+
+export {
+  // Portal topology
+  connectPortals,
+  buildTopologyFromSubtypes,
+  indexPortalEntities,
+  // Portal modes
+  PORTAL_MODES,
+  PORTAL_MODE_LIST,
+  PORTAL_MODE_COLOR_KEY,
+  EXTRA_PORTAL_MODES,
+};