@underpostnet/cyberia 3.3.0 → 3.3.76

package/scripts/test-monitor.sh

@@ -24,12 +24,12 @@ MODE=runtime                                  # runtime | instance
 ENV=development                               # development | production
 DEPLOY_ID=dd-test                             # deploy id (instance mode: parent of conf.instances.json)
 INSTANCE_IDS=                                 # instance mode: csv of ids (default: all in conf.instances.json)
-IMAGE=underpost/wp:v3.3.0                    # runtime mode image (instance mode reads image from conf)
+IMAGE=underpost/wp:v3.3.76                    # runtime mode image (instance mode reads image from conf)
 VERSIONS=green                                # csv of blue/green versions
 REPLICAS=1                                    # replicas per deployment
 NAMESPACE=default                             # k8s namespace
 CLUSTER=kind                                  # kind | kubeadm | k3s | "" (auto/none)
-TIMEOUT_RESPONSE=300000ms                     # HTTPProxy per-route response timeout
+TIMEOUT_RESPONSE=10000ms                     # HTTPProxy per-route response timeout
 TEMPLATE_REPO=underpostnet/pwa-microservices-template-private  # runtime mode link repo
 ENVOY_NAMESPACE=projectcontour                # ingress namespace (instance TLS exposure)
 ENVOY_SERVICE=envoy                           # ingress service (instance TLS exposure)
@@ -59,7 +59,7 @@ Common (every default is overridable):
   --replicas <n>
   --namespace <ns>
   --cluster <kind|kubeadm|k3s|none>
-  --timeout-response <dur>      e.g. 300000ms
+  --timeout-response <dur>      e.g. 10000ms
   --template-repo <owner/repo>  runtime mode link repo
   --envoy-namespace <ns>        instance TLS exposure ingress namespace
   --envoy-service <name>        instance TLS exposure ingress service
@@ -176,7 +176,7 @@ hosts_from() {
 
 # ─────────────────────────── runtime mode ───────────────────────────
 run_runtime_mode() {
-  local link_cmd="cd /home/dd,underpost clone ${TEMPLATE_REPO},cd /home/dd/${TEMPLATE_REPO##*/},npm install,npm link"
+  local link_cmd="cd /home/dd,underpost clone ${TEMPLATE_REPO},cd /home/dd/${TEMPLATE_REPO##*/},npm install,npm link --force"
   local deploy_cmd proxy_flag="" expose_flags="" start_flags=""
 
   # Publish the local engine src to underpostnet/engine-test-<id> so the pod
@@ -220,7 +220,7 @@ run_instance_mode() {
   for id in "${ids[@]}"; do
     [ -n "$id" ] || continue
     echo "[test-monitor] deploying instance ${DEPLOY_ID},${id}"
-    node bin run instance "${DEPLOY_ID},${id},${REPLICAS}" \
+    node bin run instance --deploy-id "$DEPLOY_ID" --instance-id "$id" --replicas "$REPLICAS" \
       $DEV_FLAG $CLUSTER_FLAG --namespace "$NAMESPACE" --etc-hosts $tls_flag \
       ${IMAGE:+--image-name "$IMAGE"}
   done

package/src/api/atlas-sprite-sheet/atlas-sprite-sheet.controller.js

@@ -4,9 +4,21 @@ import {
   sendBlob,
   serviceHandler,
   setCrossOriginHeaders,
-} from '../../server/middlewares.js';
+} from '../../server/network/middlewares.js';
 import { AtlasSpriteSheetService } from './atlas-sprite-sheet.service.js';
 
+/* Streams one render as a file. Headers go on before the lookup, so a cross-origin
+ * client can read a 404 too. */
+const blobHandler = (lookup) =>
+  controllerHandler(
+    async (req, res, options) => {
+      setCrossOriginHeaders(req, res);
+      const { buffer, mimetype, name } = await lookup(req, res, options);
+      return sendBlob(req, res, { buffer, mimetype, filename: name });
+    },
+    { errorStatus: 404 },
+  );
+
 const AtlasSpriteSheetController = buildCrudController(AtlasSpriteSheetService, {
   get: serviceHandler(AtlasSpriteSheetService.get, { crossOrigin: true, pagination: true }),
   getMetadata: serviceHandler(AtlasSpriteSheetService.getMetadata, {
@@ -16,15 +28,8 @@ const AtlasSpriteSheetController = buildCrudController(AtlasSpriteSheetService,
   }),
   generate: serviceHandler(AtlasSpriteSheetService.generate, { errorStatus: 500 }),
   deleteByObjectLayerId: serviceHandler(AtlasSpriteSheetService.deleteByObjectLayerId, { errorStatus: 500 }),
-  blob: controllerHandler(
-    async (req, res, options) => {
-      // Set before the service call so cross-origin clients can read 404s too.
-      setCrossOriginHeaders(req, res);
-      const { buffer, mimetype, name } = await AtlasSpriteSheetService.blob(req, res, options);
-      return sendBlob(req, res, { buffer, mimetype, filename: name });
-    },
-    { errorStatus: 404 },
-  ),
+  blob: blobHandler(AtlasSpriteSheetService.blob),
+  idlePreview: blobHandler(AtlasSpriteSheetService.idlePreview),
 });
 
 export { AtlasSpriteSheetController };

package/src/api/atlas-sprite-sheet/atlas-sprite-sheet.model.js

@@ -69,14 +69,27 @@ const DirectionFramesSchema = new Schema(
   { _id: false },
 );
 /**
+ * One atlas per item key, kept in two renders of one layout, plus the still that
+ * stands in for the item wherever a single picture is wanted.
+ *
+ * `fileId` is the human-resolution PNG, at `metadata.upscaleFactor` pixels per
+ * cell. `minifyFileId` is the PNG the client runtime downloads through
+ * `GET /atlas-sprite-sheet/blob/:itemKey`, at `metadata.cellPixelDim` pixels per
+ * cell. `metadata` describes the minified render, so blob and metadata agree.
+ * `idlePreviewFileId` is the first down-idle frame cut out of `fileId`, served by
+ * `GET /atlas-sprite-sheet/idle-preview/:itemKey` to every editor and overlay.
+ *
  * @typedef {Object} AtlasSpriteSheet
- * @property {Types.ObjectId} fileId - Reference to File document (consolidated PNG)
+ * @property {Types.ObjectId} fileId - Reference to the human-resolution PNG File document
+ * @property {Types.ObjectId} [minifyFileId] - Reference to the minified PNG File document
+ * @property {Types.ObjectId} [idlePreviewFileId] - Reference to the down-idle still File document
  * @property {string} [cid] - IPFS Content Identifier for the atlas PNG
  * @property {Object} metadata - Atlas sprite sheet metadata
  * @property {string} metadata.itemKey - Item identifier key for texture reference
- * @property {number} metadata.atlasWidth - Total atlas width in pixels
- * @property {number} metadata.atlasHeight - Total atlas height in pixels
- * @property {number} metadata.cellPixelDim - Pixel dimension of each cell
+ * @property {number} metadata.atlasWidth - Minified atlas width in pixels
+ * @property {number} metadata.atlasHeight - Minified atlas height in pixels
+ * @property {number} metadata.cellPixelDim - Pixels per cell of the minified render
+ * @property {number} metadata.upscaleFactor - Pixels per cell of the human-resolution render
  * @property {number} metadata.frame_duration - Duration of each frame in milliseconds
  * @property {DirectionFrames} metadata.frames - Frame positions in atlas by direction
  * @property {Date} createdAt - When the document was created
@@ -90,6 +103,18 @@ const AtlasSpriteSheetSchema = new Schema(
       ref: 'File',
       required: true,
     },
+    // Absent until `cyberia ol --minify` renders it for this item.
+    minifyFileId: {
+      type: Schema.Types.ObjectId,
+      ref: 'File',
+      default: null,
+    },
+    // The down-idle still every preview reads; absent until an atlas write fills it.
+    idlePreviewFileId: {
+      type: Schema.Types.ObjectId,
+      ref: 'File',
+      default: null,
+    },
     cid: {
       type: String,
       default: '',
@@ -99,7 +124,8 @@ const AtlasSpriteSheetSchema = new Schema(
       itemKey: { type: String, required: true, trim: true },
       atlasWidth: { type: Number, required: true, min: 1 },
       atlasHeight: { type: Number, required: true, min: 1 },
-      cellPixelDim: { type: Number, required: true, min: 1, default: 20 },
+      cellPixelDim: { type: Number, required: true, min: 1 },
+      upscaleFactor: { type: Number, required: false, min: 1 },
       frame_duration: { type: Number, min: 0, default: 100 },
       frames: { type: DirectionFramesSchema, required: true },
     },
@@ -113,6 +139,8 @@ const AtlasSpriteSheetSchema = new Schema(
 // Indexes for efficient querying
 AtlasSpriteSheetSchema.index({ 'metadata.itemKey': 1 }, { unique: true });
 AtlasSpriteSheetSchema.index({ fileId: 1 });
+AtlasSpriteSheetSchema.index({ minifyFileId: 1 });
+AtlasSpriteSheetSchema.index({ idlePreviewFileId: 1 });
 // Pre-save validation
 AtlasSpriteSheetSchema.pre('save', function () {
   if (!this.fileId || !this.metadata) {
@@ -127,6 +155,8 @@ class AtlasSpriteSheetDto {
       return {
         _id: 1,
         fileId: 1,
+        minifyFileId: 1,
+        idlePreviewFileId: 1,
         cid: 1,
         metadata: 1,
         createdAt: 1,
@@ -144,6 +174,7 @@ class AtlasSpriteSheetDto {
         'metadata.atlasWidth': 1,
         'metadata.atlasHeight': 1,
         'metadata.cellPixelDim': 1,
+        'metadata.upscaleFactor': 1,
         'metadata.frame_duration': 1,
         'metadata.frames': 1,
         createdAt: 1,

package/src/api/atlas-sprite-sheet/atlas-sprite-sheet.router.js

@@ -1,6 +1,6 @@
 import express from 'express';
-import { registerCrudRoutes } from '../../server/middlewares.js';
-import { moderatorGuard } from '../../server/auth.js';
+import { registerCrudRoutes } from '../../server/network/middlewares.js';
+import { moderatorGuard } from '../../server/security/auth.js';
 import { AtlasSpriteSheetController } from './atlas-sprite-sheet.controller.js';
 
 class AtlasSpriteSheetRouter {
@@ -23,6 +23,11 @@ class AtlasSpriteSheetRouter {
       async (req, res) => await AtlasSpriteSheetController.deleteByObjectLayerId(req, res, options),
     );
     router.get(`/blob/:itemKey`, async (req, res) => await AtlasSpriteSheetController.blob(req, res, options));
+    // The down-idle still of an item, for every editor and overlay that shows one picture of it.
+    router.get(
+      `/idle-preview/:itemKey`,
+      async (req, res) => await AtlasSpriteSheetController.idlePreview(req, res, options),
+    );
     // Metadata endpoints: returns itemKey, atlasWidth, atlasHeight, cellPixelDim, frames (no fileId).
     // Client fetches /metadata/:itemKey once, caches it, then fetches /blob/:itemKey for the PNG.
     router.get(

package/src/api/atlas-sprite-sheet/atlas-sprite-sheet.service.js

@@ -1,11 +1,15 @@
 import { DataBaseProviderService } from '../../db/DataBaseProvider.js';
-import { loggerFactory } from '../../server/logger.js';
-import { DataQuery } from '../../server/data-query.js';
-import { AtlasSpriteSheetGenerator } from '../../projects/cyberia/atlas-sprite-sheet-generator.js';
-import { FileFactory } from '../file/file.service.js';
+import { loggerFactory } from '../../server/ops/logger.js';
+import { DataQuery } from '../../server/storage/data-query.js';
+import { FileCleanup } from '../file/file.service.js';
 import { AtlasSpriteSheetDto } from './atlas-sprite-sheet.model.js';
 import { IpfsClient } from '../../projects/cyberia/ipfs-client.js';
-import { createPinRecord, removePinRecordsAndUnpin } from '../ipfs/ipfs.service.js';
+import { removePinRecordsAndUnpin } from '../ipfs/ipfs.service.js';
+import {
+  ATLAS_FILE_FIELDS,
+  AtlasSpriteSheetStore,
+  atlasMfsPaths,
+} from '../../projects/cyberia/atlas-sprite-sheet-store.js';
 
 const logger = loggerFactory(import.meta);
 const DEFAULT_ATLAS_FRAME_DURATION = 100;
@@ -51,133 +55,91 @@ async function withResolvedAtlasFrameDuration(doc, ObjectLayer) {
   };
 }
 
+/**
+ * Removes one atlas: its IPFS pins and MFS entries, both render File documents,
+ * and the AtlasSpriteSheet document itself.
+ *
+ * @param {Object} params
+ * @param {Object} params.atlasDoc - The AtlasSpriteSheet document.
+ * @param {Object} params.options - Router options ({ host, path }).
+ * @param {string} [params.itemKey] - Item key, when the caller already resolved it.
+ * @param {string} [params.metadataCid] - Atlas metadata CID, when the object layer holds it.
+ * @returns {Promise<void>}
+ */
+const purgeAtlasDoc = async ({ atlasDoc, options, itemKey, metadataCid }) => {
+  const AtlasSpriteSheet = DataBaseProviderService.getModel('AtlasSpriteSheet', options);
+  const File = DataBaseProviderService.getModel('File', options);
+  const key = itemKey || atlasDoc.metadata?.itemKey;
+  const mfsPaths = key ? atlasMfsPaths(key) : null;
+
+  for (const [cid, mfsPath] of [
+    [atlasDoc.cid, mfsPaths?.png],
+    [metadataCid, mfsPaths?.metadata],
+  ]) {
+    if (!cid) continue;
+    try {
+      await removePinRecordsAndUnpin(cid, options);
+      if (mfsPath) await IpfsClient.removeMfsPath(mfsPath);
+      logger.info(`Cleaned up IPFS CID ${cid} for AtlasSpriteSheet ${atlasDoc._id}`);
+    } catch (ipfsErr) {
+      logger.warn(`Failed to clean up IPFS CID ${cid}: ${ipfsErr.message}`);
+    }
+  }
+
+  await FileCleanup.deleteDocumentFiles({ doc: atlasDoc, fileFields: ATLAS_FILE_FIELDS, File });
+  await AtlasSpriteSheet.findByIdAndDelete(atlasDoc._id);
+};
+
 class AtlasSpriteSheetService {
-  static blob = async (req, res, options) => {
+  // Serves the minified render, the one `metadata` describes. The client runtime
+  // pairs this blob with GET /metadata/:itemKey, so the two must be the same layout.
+  /* One render of an item's atlas, by the File field that holds it. */
+  static render = async ({ itemKey, field, label }, options) => {
     /** @type {import('./atlas-sprite-sheet.model.js').AtlasSpriteSheetModel} */
     const AtlasSpriteSheet = DataBaseProviderService.getModel('AtlasSpriteSheet', options);
     /** @type {import('../file/file.model.js').FileModel} */
     const File = DataBaseProviderService.getModel('File', options);
 
-    const itemKey = req.params.itemKey;
     const atlasDoc = await AtlasSpriteSheet.findOne({ 'metadata.itemKey': itemKey }).lean();
     if (!atlasDoc) throw new Error(`Atlas not found for itemKey: ${itemKey}`);
+    if (!atlasDoc[field]) throw new Error(`${label} missing for itemKey: ${itemKey}`);
 
-    const fileDoc = await File.findById(atlasDoc.fileId);
+    const fileDoc = await File.findById(atlasDoc[field]);
     if (!fileDoc || !fileDoc.data) throw new Error(`File not found for atlas itemKey: ${itemKey}`);
 
     return { buffer: Buffer.from(fileDoc.data), mimetype: fileDoc.mimetype || 'image/png', name: fileDoc.name };
   };
-  static generate = async (req, res, options, generateOptions = {}) => {
-    /** @type {import('../object-layer/object-layer.model.js').ObjectLayerModel} */
-    const ObjectLayer = DataBaseProviderService.getModel('ObjectLayer', options);
-    /** @type {import('../file/file.model.js').FileModel} */
-    const File = DataBaseProviderService.getModel('File', options);
-    /** @type {import('./atlas-sprite-sheet.model.js').AtlasSpriteSheetModel} */
-    const AtlasSpriteSheet = DataBaseProviderService.getModel('AtlasSpriteSheet', options);
 
-    let objectLayer = req.objectLayer;
-
-    if (!objectLayer) {
-      objectLayer = await ObjectLayer.findById(req.params.id).populate('objectLayerRenderFramesId');
-    }
-
-    if (!objectLayer) {
-      throw new Error('ObjectLayer not found');
-    }
-
-    if (!objectLayer.objectLayerRenderFramesId) {
-      throw new Error('ObjectLayer has no render frames');
-    }
-
-    const itemKey = objectLayer.data.item.id;
-    const { buffer, metadata } = await AtlasSpriteSheetGenerator.generateAtlas(
-      objectLayer.objectLayerRenderFramesId,
-      itemKey,
+  static blob = (req, res, options) =>
+    AtlasSpriteSheetService.render(
+      { itemKey: req.params.itemKey, field: 'minifyFileId', label: 'Minified atlas render' },
+      options,
     );
 
-    const fileDoc = await new File(FileFactory.create(buffer, `${itemKey}.png`)).save();
-
-    // Add atlas PNG to IPFS and obtain its CID
-    let atlasCid = '';
-    let atlasMetadataCid = '';
-    const userId = req.auth && req.auth.user ? req.auth.user._id : undefined;
-    try {
-      const ipfsResult = await IpfsClient.addBufferToIpfs(
-        buffer,
-        `${itemKey}_atlas_sprite_sheet.png`,
-        `/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet.png`,
-      );
-      if (ipfsResult) {
-        atlasCid = ipfsResult.cid;
-        logger.info(`Atlas sprite sheet pinned to IPFS – CID: ${atlasCid}`);
-      }
-    } catch (ipfsError) {
-      logger.warn('Failed to add atlas sprite sheet to IPFS:', ipfsError.message);
-    }
-
-    // Pin atlas metadata JSON to IPFS (fast-json-stable-stringify) and obtain its CID
-    try {
-      const metadataIpfsResult = await IpfsClient.addJsonToIpfs(
-        metadata,
-        `${itemKey}_atlas_sprite_sheet_metadata.json`,
-        `/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet_metadata.json`,
-      );
-      if (metadataIpfsResult) {
-        atlasMetadataCid = metadataIpfsResult.cid;
-        logger.info(`Atlas metadata pinned to IPFS – CID: ${atlasMetadataCid}`);
-      }
-    } catch (ipfsError) {
-      logger.warn('Failed to add atlas metadata to IPFS:', ipfsError.message);
-    }
+  static idlePreview = (req, res, options) =>
+    AtlasSpriteSheetService.render(
+      { itemKey: req.params.itemKey, field: 'idlePreviewFileId', label: 'Idle preview' },
+      options,
+    );
+  static generate = async (req, res, options, generateOptions = {}) => {
+    /** @type {import('../object-layer/object-layer.model.js').ObjectLayerModel} */
+    const ObjectLayer = DataBaseProviderService.getModel('ObjectLayer', options);
 
-    let atlasDoc = await AtlasSpriteSheet.findOne({ 'metadata.itemKey': itemKey });
+    const objectLayer =
+      req.objectLayer || (await ObjectLayer.findById(req.params.id).populate('objectLayerRenderFramesId'));
 
-    if (atlasDoc) {
-      // Clean up old file if it exists
-      if (atlasDoc.fileId) {
-        await File.findByIdAndDelete(atlasDoc.fileId);
-      }
-      atlasDoc.fileId = fileDoc._id;
-      atlasDoc.cid = atlasCid;
-      atlasDoc.metadata = metadata;
-      await atlasDoc.save();
-    } else {
-      atlasDoc = await new AtlasSpriteSheet({
-        fileId: fileDoc._id,
-        cid: atlasCid,
-        metadata,
-      }).save();
-    }
+    if (!objectLayer) throw new Error('ObjectLayer not found');
+    if (!objectLayer.objectLayerRenderFramesId) throw new Error('ObjectLayer has no render frames');
 
-    // Register CIDs in the IPFS registry now that atlasDoc._id is known.
-    if (atlasCid) {
-      try {
-        await createPinRecord({
-          cid: atlasCid,
-          resourceType: 'atlas-sprite-sheet',
-          mfsPath: `/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet.png`,
-          options,
-        });
-      } catch (e) {
-        logger.warn('IPFS registry update failed (atlas PNG):', e.message);
-      }
-    }
-    if (atlasMetadataCid) {
-      try {
-        await createPinRecord({
-          cid: atlasMetadataCid,
-          resourceType: 'atlas-metadata',
-          mfsPath: `/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet_metadata.json`,
-          options,
-        });
-      } catch (e) {
-        logger.warn('IPFS registry update failed (atlas metadata):', e.message);
-      }
-    }
+    const { atlasDoc, atlasCid, atlasMetadataCid } = await AtlasSpriteSheetStore.persist({
+      itemKey: objectLayer.data.item.id,
+      objectLayerRenderFrames: objectLayer.objectLayerRenderFramesId,
+      upscaleFactor: generateOptions.upscaleFactor,
+      options,
+    });
 
-    // When skipObjectLayerSave is set, return CIDs without mutating the OL document.
-    // This enables cut-over consistency: callers stage CIDs in memory and write the
-    // ObjectLayer atomically only after all CIDs are computed.
+    // Callers that stage CIDs in memory write the ObjectLayer themselves, so the
+    // document stays untouched until every CID is known.
     if (generateOptions.skipObjectLayerSave) {
       return { atlasDoc, atlasCid, atlasMetadataCid };
     }
@@ -194,8 +156,6 @@ class AtlasSpriteSheetService {
   static deleteByObjectLayerId = async (req, res, options) => {
     /** @type {import('../object-layer/object-layer.model.js').ObjectLayerModel} */
     const ObjectLayer = DataBaseProviderService.getModel('ObjectLayer', options);
-    /** @type {import('../file/file.model.js').FileModel} */
-    const File = DataBaseProviderService.getModel('File', options);
     /** @type {import('./atlas-sprite-sheet.model.js').AtlasSpriteSheetModel} */
     const AtlasSpriteSheet = DataBaseProviderService.getModel('AtlasSpriteSheet', options);
 
@@ -207,37 +167,12 @@ class AtlasSpriteSheetService {
     if (objectLayer.atlasSpriteSheetId) {
       const atlasDoc = await AtlasSpriteSheet.findById(objectLayer.atlasSpriteSheetId);
       if (atlasDoc) {
-        // Remove pin records and unpin atlas CID from IPFS
-        const atlasCid = atlasDoc.cid || objectLayer.data.render?.cid;
-        const atlasMetadataCid = objectLayer.data.render?.metadataCid;
-        if (atlasCid) {
-          try {
-            await removePinRecordsAndUnpin(atlasCid, options);
-            // Remove the MFS entry for the atlas sprite sheet PNG
-            const itemId = objectLayer.data.item.id;
-            await IpfsClient.removeMfsPath(`/object-layer/${itemId}/${itemId}_atlas_sprite_sheet.png`);
-            logger.info(`Cleaned up IPFS atlas CID ${atlasCid} for ObjectLayer ${objectLayer._id}`);
-          } catch (ipfsErr) {
-            logger.warn(`Failed to clean up IPFS atlas CID ${atlasCid}: ${ipfsErr.message}`);
-          }
-        }
-        if (atlasMetadataCid) {
-          try {
-            await removePinRecordsAndUnpin(atlasMetadataCid, options);
-            const itemId = objectLayer.data.item.id;
-            await IpfsClient.removeMfsPath(`/object-layer/${itemId}/${itemId}_atlas_sprite_sheet_metadata.json`);
-            logger.info(`Cleaned up IPFS atlas metadata CID ${atlasMetadataCid} for ObjectLayer ${objectLayer._id}`);
-          } catch (ipfsErr) {
-            logger.warn(`Failed to clean up IPFS atlas metadata CID ${atlasMetadataCid}: ${ipfsErr.message}`);
-          }
-        }
-
-        // Delete the atlas File document from MongoDB
-        if (atlasDoc.fileId) {
-          await File.findByIdAndDelete(atlasDoc.fileId);
-        }
-        // Delete the AtlasSpriteSheet document itself
-        await AtlasSpriteSheet.findByIdAndDelete(atlasDoc._id);
+        await purgeAtlasDoc({
+          atlasDoc,
+          options,
+          itemKey: objectLayer.data.item.id,
+          metadataCid: objectLayer.data.render?.metadataCid,
+        });
       }
       objectLayer.atlasSpriteSheetId = undefined;
       if (!objectLayer.data.render) objectLayer.data.render = {};
@@ -328,54 +263,23 @@ class AtlasSpriteSheetService {
   static delete = async (req, res, options) => {
     /** @type {import('./atlas-sprite-sheet.model.js').AtlasSpriteSheetModel} */
     const AtlasSpriteSheet = DataBaseProviderService.getModel('AtlasSpriteSheet', options);
-    /** @type {import('../file/file.model.js').FileModel} */
-    const File = DataBaseProviderService.getModel('File', options);
 
     if (req.params.id) {
       const atlasDoc = await AtlasSpriteSheet.findById(req.params.id);
       if (!atlasDoc) return null;
+      await purgeAtlasDoc({ atlasDoc, options });
+      return atlasDoc;
+    }
 
-      // Remove pin records and unpin atlas CID from IPFS
-      if (atlasDoc.cid) {
-        try {
-          await removePinRecordsAndUnpin(atlasDoc.cid, options);
-          if (atlasDoc.metadata?.itemKey) {
-            const itemKey = atlasDoc.metadata.itemKey;
-            await IpfsClient.removeMfsPath(`/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet.png`);
-          }
-          logger.info(`Cleaned up IPFS atlas CID ${atlasDoc.cid} for AtlasSpriteSheet ${atlasDoc._id}`);
-        } catch (ipfsErr) {
-          logger.warn(`Failed to clean up IPFS atlas CID ${atlasDoc.cid}: ${ipfsErr.message}`);
-        }
-      }
-
-      // Delete the referenced File document (the atlas PNG blob)
-      if (atlasDoc.fileId) {
-        await File.findByIdAndDelete(atlasDoc.fileId);
-      }
-
-      return await AtlasSpriteSheet.findByIdAndDelete(req.params.id);
-    } else {
-      // Bulk delete: iterate each atlas to clean up File, IPFS pins, and pin records
-      const allAtlases = await AtlasSpriteSheet.find({});
-      for (const atlasDoc of allAtlases) {
-        try {
-          if (atlasDoc.cid) {
-            await removePinRecordsAndUnpin(atlasDoc.cid, options);
-            if (atlasDoc.metadata?.itemKey) {
-              const itemKey = atlasDoc.metadata.itemKey;
-              await IpfsClient.removeMfsPath(`/object-layer/${itemKey}/${itemKey}_atlas_sprite_sheet.png`);
-            }
-          }
-          if (atlasDoc.fileId) {
-            await File.findByIdAndDelete(atlasDoc.fileId);
-          }
-        } catch (err) {
-          logger.error(`Failed to clean up AtlasSpriteSheet ${atlasDoc._id} during bulk delete: ${err.message}`);
-        }
+    const allAtlases = await AtlasSpriteSheet.find({});
+    for (const atlasDoc of allAtlases) {
+      try {
+        await purgeAtlasDoc({ atlasDoc, options });
+      } catch (err) {
+        logger.error(`Failed to clean up AtlasSpriteSheet ${atlasDoc._id} during bulk delete: ${err.message}`);
       }
-      return await AtlasSpriteSheet.deleteMany();
     }
+    return { deletedCount: allAtlases.length };
   };
 }
 

package/src/api/core/core.controller.js

@@ -1,4 +1,4 @@
-import { buildCrudController, serviceHandler } from '../../server/middlewares.js';
+import { buildCrudController, serviceHandler } from '../../server/network/middlewares.js';
 import { CoreService } from './core.service.js';
 
 const CoreController = buildCrudController(CoreService, {

package/src/api/core/core.router.js

@@ -1,6 +1,6 @@
 import express from 'express';
-import { registerCrudRoutes } from '../../server/middlewares.js';
-import { adminGuard } from '../../server/auth.js';
+import { registerCrudRoutes } from '../../server/network/middlewares.js';
+import { adminGuard } from '../../server/security/auth.js';
 import { CoreController } from './core.controller.js';
 
 class CoreRouter {

package/src/api/core/core.service.js

@@ -1,6 +1,6 @@
 import { DataBaseProviderService } from '../../db/DataBaseProvider.js';
-import { loggerFactory } from '../../server/logger.js';
-import { shellExec } from '../../server/process.js';
+import { loggerFactory } from '../../server/ops/logger.js';
+import { shellExec } from '../../server/runtime/process.js';
 
 const logger = loggerFactory(import.meta);
 

package/src/api/crypto/crypto.controller.js

@@ -1,4 +1,4 @@
-import { serviceHandler } from '../../server/middlewares.js';
+import { serviceHandler } from '../../server/network/middlewares.js';
 import { CryptoService } from './crypto.service.js';
 
 class CryptoController {

package/src/api/crypto/crypto.service.js

@@ -1,4 +1,4 @@
-import { loggerFactory } from '../../server/logger.js';
+import { loggerFactory } from '../../server/ops/logger.js';
 import crypto from 'crypto';
 import { DataBaseProviderService } from '../../db/DataBaseProvider.js';
 const logger = loggerFactory(import.meta);

package/src/api/cyberia-action/cyberia-action.controller.js

@@ -1,4 +1,4 @@
-import { buildCrudController, serviceHandler } from '../../server/middlewares.js';
+import { buildCrudController, serviceHandler } from '../../server/network/middlewares.js';
 import { CyberiaActionService } from './cyberia-action.service.js';
 
 const CyberiaActionController = buildCrudController(CyberiaActionService, {

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

@@ -1,5 +1,5 @@
 import express from 'express';
-import { registerCrudRoutes } from '../../server/middlewares.js';
+import { registerCrudRoutes } from '../../server/network/middlewares.js';
 import { CyberiaActionController } from './cyberia-action.controller.js';
 
 class CyberiaActionRouter {
@@ -9,8 +9,8 @@ class CyberiaActionRouter {
    */
   static router(options) {
     const router = express.Router();
-    // Direct lookup by code — the client fetches an NPC's action metadata
-    // (label, dialogue map) by the action code the Go server sends over AOI.
+    // Direct lookup by code. The client fetches an NPC's action metadata
+    // (label, dialogue map) by the action code the AOI stream carries.
     router.get(`/code/:code`, async (req, res) => await CyberiaActionController.getByCode(req, res, options));
     return registerCrudRoutes(router, CyberiaActionController, options);
   }

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

@@ -1,6 +1,6 @@
 import { DataBaseProviderService } from '../../db/DataBaseProvider.js';
-import { loggerFactory } from '../../server/logger.js';
-import { DataQuery } from '../../server/data-query.js';
+import { loggerFactory } from '../../server/ops/logger.js';
+import { DataQuery } from '../../server/storage/data-query.js';
 import { DefaultCyberiaActions } from '../cyberia-server-defaults/cyberia-server-defaults.js';
 
 const logger = loggerFactory(import.meta);
@@ -34,10 +34,9 @@ class CyberiaActionService {
     if (!code) throw new Error('code parameter is required');
     const data = await CyberiaAction.findOne({ code }).lean();
     if (data) return data;
-    // Fallback world delivers actions to the Go server from the canonical
-    // defaults without persisting them; serve those so the client can fetch the
-    // action's label + dialogue map by code. Quest OFFERS are NOT resolved here —
-    // the client locates offered quests via the cyberia-quest API by cell.
+    // The fallback world serves actions from the canonical defaults and never
+    // persists them. Serve the same defaults here, so the client can fetch an
+    // action by code. Quest offers come from the cyberia-quest API by cell.
     const fallback = DefaultCyberiaActions.find((a) => a.code === code);
     if (fallback) return fallback;
     throw new Error(`No action found for code: ${code}`);

package/src/api/cyberia-audio/cyberia-audio.controller.js

@@ -0,0 +1,6 @@
+import { buildCrudController } from '../../server/network/middlewares.js';
+import { CyberiaAudioService } from './cyberia-audio.service.js';
+
+const CyberiaAudioController = buildCrudController(CyberiaAudioService);
+
+export { CyberiaAudioController };