@underpostnet/cyberia 3.3.0 → 3.3.76

package/src/api/object-layer/object-layer.service.js

@@ -11,17 +11,22 @@
  */
 
 import { DataBaseProviderService } from '../../db/DataBaseProvider.js';
-import { loggerFactory } from '../../server/logger.js';
+import { loggerFactory } from '../../server/ops/logger.js';
 import { ObjectLayerRenderFramesDto } from '../object-layer-render-frames/object-layer-render-frames.model.js';
 import { FileFactory } from '../file/file.service.js';
 import fs from 'fs-extra';
+import os from 'node:os';
+import path from 'node:path';
+import sharp from 'sharp';
+import { validateStats } from '../../client/components/cyberia/SharedDefaultsCyberia.js';
 import { ObjectLayerDto } from './object-layer.model.js';
 import { ObjectLayerEngine } from '../../projects/cyberia/object-layer.js';
-import { shellExec } from '../../server/process.js';
-import { DataQuery } from '../../server/data-query.js';
+import { shellExec } from '../../server/runtime/process.js';
+import { DataQuery } from '../../server/storage/data-query.js';
 import { AtlasSpriteSheetService } from '../atlas-sprite-sheet/atlas-sprite-sheet.service.js';
+import { AtlasSpriteSheetStore } from '../../projects/cyberia/atlas-sprite-sheet-store.js';
 import { IpfsClient } from '../../projects/cyberia/ipfs-client.js';
-import { createPinRecord, removePinRecordsAndUnpin } from '../ipfs/ipfs.service.js';
+import { removePinRecordsAndUnpin } from '../ipfs/ipfs.service.js';
 
 /**
  * Logger instance for this module.
@@ -45,8 +50,8 @@ class ObjectLayerService {
    * - `/metadata/:itemType/:itemId` — Create an object layer from uploaded frames and metadata.
    * - Default — Create an object layer directly from the request body.
    *
-   * The `/metadata` and default routes delegate to {@link ObjectLayerEngine.createObjectLayerDocuments}
-   * for document creation, atlas generation, SHA-256 computation, and IPFS pinning.
+   * The `/metadata` and default routes delegate to {@link ObjectLayerEngine.persistObjectLayerDocuments}
+   * for the document write, atlas generation, SHA-256 computation, and IPFS pinning.
    *
    * @async
    * @function post
@@ -160,22 +165,12 @@ class ObjectLayerService {
           metadataOverride: req.body,
         });
 
-      const { objectLayer } = await ObjectLayerEngine.createObjectLayerDocuments({
+      const { objectLayer } = await ObjectLayerEngine.persistObjectLayerDocuments({
         ObjectLayer,
         ObjectLayerRenderFrames,
         objectLayerRenderFramesData,
         objectLayerData,
-        createOptions: {
-          generateAtlas: true,
-          atlasServiceContext: {
-            req,
-            res,
-            options,
-            AtlasSpriteSheetService,
-            IpfsClient,
-            createPinRecord,
-          },
-        },
+        persistOptions: { options },
       });
 
       return objectLayer;
@@ -191,44 +186,32 @@ class ObjectLayerService {
     bodyData.data.render.cid = '';
     bodyData.data.render.metadataCid = '';
 
-    // If has render frames, generate atlas + CIDs BEFORE creating the ObjectLayer
+    // Stage the atlas CIDs before the write, so the document is never stored without them.
     if (bodyData.objectLayerRenderFramesId) {
       const renderFramesDoc = await ObjectLayerRenderFrames.findById(bodyData.objectLayerRenderFramesId);
       if (renderFramesDoc) {
         try {
-          const stagingOL = {
-            data: bodyData.data,
-            objectLayerRenderFramesId: renderFramesDoc,
-          };
-          const result = await AtlasSpriteSheetService.generate(
-            { objectLayer: stagingOL, auth: req.auth },
-            res,
+          const { atlasDoc, atlasCid, atlasMetadataCid } = await AtlasSpriteSheetStore.persist({
+            itemKey: bodyData.data.item.id,
+            objectLayerRenderFrames: renderFramesDoc,
             options,
-            { skipObjectLayerSave: true },
-          );
-          bodyData.data.render.cid = result.atlasCid;
-          bodyData.data.render.metadataCid = result.atlasMetadataCid;
-          bodyData.atlasSpriteSheetId = result.atlasDoc._id;
+          });
+          bodyData.data.render.cid = atlasCid;
+          bodyData.data.render.metadataCid = atlasMetadataCid;
+          bodyData.atlasSpriteSheetId = atlasDoc._id;
         } catch (atlasError) {
           logger.error('Failed to auto-generate atlas for new ObjectLayer:', atlasError);
         }
       }
     }
 
-    // Pin data JSON to IPFS
-    try {
-      const itemId = bodyData.data.item.id;
-      const mfsPath = `/object-layer/${itemId}/${itemId}_data.json`;
-      const ipfsResult = await IpfsClient.addJsonToIpfs(bodyData.data, `${itemId}_data.json`, mfsPath);
-      if (ipfsResult) {
-        bodyData.cid = ipfsResult.cid;
-        await createPinRecord({ cid: ipfsResult.cid, resourceType: 'object-layer-data', mfsPath, options });
-      }
-    } catch (ipfsError) {
-      logger.warn('Failed to pin data JSON to IPFS:', ipfsError.message);
-    }
+    const dataCid = await ObjectLayerEngine.pinObjectLayerData({
+      data: bodyData.data,
+      itemId: bodyData.data.item.id,
+      options,
+    });
+    if (dataCid) bodyData.cid = dataCid;
 
-    // Atomic create/replace – ObjectLayer is fully populated with all CIDs
     return await (await ObjectLayer.upsertByItemId(bodyData)).populate('objectLayerRenderFramesId');
   };
 
@@ -257,25 +240,33 @@ class ObjectLayerService {
     /** @type {import('./object-layer.model.js').ObjectLayerModel} */
     const ObjectLayer = DataBaseProviderService.getModel('ObjectLayer', options);
 
-    // GET /search-item-ids?q=<partial> - Fast partial match search on data.item.id
+    // Object layers are addressed by item id, the key the editor navigates by.
+    const keyFilter = (key) => DataQuery.naturalKeyFilter('data.item.id', key);
+
+    // GET /search-item-ids - item identity, by prefix (`q`, for type-ahead) or by exact ids
+    // (`ids`, comma separated). Carries the item's type because that is what addresses its
+    // sprite directory; an id alone cannot be previewed.
     if (req.path.startsWith('/search-item-ids')) {
       const q = (req.query.q || '').trim();
-      if (!q) return { itemIds: [] };
-      // Escape regex special characters for safe partial matching
-      const escaped = q.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-      const results = await ObjectLayer.find(
-        { 'data.item.id': { $regex: escaped, $options: 'i' } },
-        { 'data.item.id': 1, _id: 0 },
-      )
-        .limit(20)
+      const ids = String(req.query.ids || '')
+        .split(',')
+        .map((id) => id.trim())
+        .filter(Boolean);
+      if (!q && ids.length === 0) return { items: [] };
+      const query = ids.length
+        ? { 'data.item.id': { $in: ids } }
+        : // Escape regex special characters for safe partial matching
+          { 'data.item.id': { $regex: q.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), $options: 'i' } };
+      const results = await ObjectLayer.find(query, { 'data.item.id': 1, 'data.item.type': 1, _id: 0 })
+        .limit(ids.length ? ids.length : 20)
         .lean();
-      const itemIds = [...new Set(results.map((r) => r.data.item.id))];
-      return { itemIds };
+      const byId = new Map(results.map((r) => [r.data.item.id, r.data.item.type || '']));
+      return { items: [...byId].map(([id, type]) => ({ id, type })) };
     }
 
     // GET /frame-counts/:id - Get frame counts for each direction using numeric codes
     if (req.path.startsWith('/frame-counts/')) {
-      const objectLayer = await ObjectLayer.findById(req.params.id)
+      const objectLayer = await ObjectLayer.findOne(keyFilter(req.params.id))
         .select(ObjectLayerDto.select.getMetadata())
         .populate('objectLayerRenderFramesId');
       if (!objectLayer) {
@@ -318,7 +309,7 @@ class ObjectLayerService {
 
     // GET /render/:id - Get only render data for specific object layer
     if (req.path.startsWith('/render/')) {
-      const objectLayer = await ObjectLayer.findById(req.params.id)
+      const objectLayer = await ObjectLayer.findOne(keyFilter(req.params.id))
         .select(ObjectLayerDto.select.getRender())
         .populate('objectLayerRenderFramesId');
       if (!objectLayer) {
@@ -333,7 +324,7 @@ class ObjectLayerService {
 
     // GET /metadata/:id - Get only metadata (no render frames/colors) for specific object layer
     if (req.path.startsWith('/metadata/')) {
-      const objectLayer = await ObjectLayer.findById(req.params.id)
+      const objectLayer = await ObjectLayer.findOne(keyFilter(req.params.id))
         .select(ObjectLayerDto.select.getMetadata())
         .populate('objectLayerRenderFramesId', ObjectLayerRenderFramesDto.select.get());
       if (!objectLayer) {
@@ -385,22 +376,14 @@ class ObjectLayerService {
     }
 
     // GET / - Get paginated list of object layers
-    const id = req.params.id || req.query.id;
-    logger.info(`ObjectLayerService.get - filtering check - id: ${id}`);
-    if (id && id !== 'undefined' && !['render', 'metadata', 'frame-counts'].includes(id)) {
-      try {
-        const objectLayer = await ObjectLayer.findById(id)
-          .select(ObjectLayerDto.select.get())
-          .populate('atlasSpriteSheetId', 'cid')
-          .populate('objectLayerRenderFramesId', ObjectLayerRenderFramesDto.select.get());
-        if (objectLayer) {
-          logger.info(`ObjectLayerService.get - found record by id: ${id}`);
-          return { data: [objectLayer], total: 1, page: 1, totalPages: 1 };
-        }
-        logger.warn(`ObjectLayerService.get - record NOT found for id: ${id}`);
-      } catch (e) {
-        logger.warn(`Invalid ID format or not found: ${id}`);
-      }
+    const key = req.params.id || req.query.id;
+    if (key && key !== 'undefined' && !['render', 'metadata', 'frame-counts'].includes(key)) {
+      const objectLayer = await ObjectLayer.findOne(keyFilter(key))
+        .select(ObjectLayerDto.select.get())
+        .populate('atlasSpriteSheetId', 'cid')
+        .populate('objectLayerRenderFramesId', ObjectLayerRenderFramesDto.select.get());
+      if (objectLayer) return { data: [objectLayer], total: 1, page: 1, totalPages: 1 };
+      logger.warn(`ObjectLayerService.get - no object layer for key: ${key}`);
     }
 
     const { query, sort, skip, limit, page } = DataQuery.parse(req.query);
@@ -493,9 +476,14 @@ class ObjectLayerService {
     // Create temporary output file path
     const tempOutputPath = `${framesFolder}/${tmpOutputFileName}`;
 
+    // img2webp takes one frame size, and frames of one direction may differ: the game
+    // stretches each to the entity's cell box, so the preview stretches them to the
+    // largest one — nearest-neighbour, since a scaled frame is still pixel art.
+    const stagedFolder = await ObjectLayerService.stageUniformFrames(framesFolder, pngFiles);
+
     try {
       // Change to the frames directory and execute img2webp command
-      const cmd = `cd "${framesFolder}" && img2webp -d ${frameDuration} -loop 0 *.png -o ${tmpOutputFileName}`;
+      const cmd = `cd "${stagedFolder ?? framesFolder}" && img2webp -d ${frameDuration} -loop 0 *.png -o "${path.resolve(tempOutputPath)}"`;
 
       logger.info(`Executing command: ${cmd}`);
 
@@ -546,9 +534,41 @@ class ObjectLayerService {
       }
 
       throw error;
+    } finally {
+      if (stagedFolder) await fs.remove(stagedFolder);
     }
   };
 
+  /**
+   * Stages copies of the frames resized to one common size when they differ, or returns null
+   * when they already share one and can be encoded in place.
+   * @function stageUniformFrames
+   * @memberof ObjectLayerService
+   * @param {string} framesFolder - Directory holding the direction's PNG frames.
+   * @param {string[]} pngFiles - Frame file names, in animation order.
+   * @returns {Promise<string|null>} Temporary directory with the resized frames, or null.
+   */
+  static stageUniformFrames = async (framesFolder, pngFiles) => {
+    const sizes = await Promise.all(
+      pngFiles.map(async (file) => {
+        const { width, height } = await sharp(`${framesFolder}/${file}`).metadata();
+        return { file, width, height };
+      }),
+    );
+    const width = Math.max(...sizes.map((size) => size.width));
+    const height = Math.max(...sizes.map((size) => size.height));
+    if (sizes.every((size) => size.width === width && size.height === height)) return null;
+
+    const stagedFolder = await fs.mkdtemp(path.join(os.tmpdir(), 'ol-webp-'));
+    for (const { file } of sizes) {
+      await sharp(`${framesFolder}/${file}`)
+        .resize(width, height, { fit: 'fill', kernel: 'nearest' })
+        .toFile(`${stagedFolder}/${file}`);
+    }
+    logger.info(`Staged ${pngFiles.length} frame(s) at ${width}x${height} for webp encoding`);
+    return stagedFolder;
+  };
+
   /**
    * PUT handler for updating object layers, their frame images, and metadata.
    *
@@ -557,8 +577,8 @@ class ObjectLayerService {
    * - `/:id/metadata/:itemType/:itemId` — Update metadata and reprocess all frames.
    * - `/:id` — Standard update from request body.
    *
-   * The `/metadata` route delegates to {@link ObjectLayerEngine.updateObjectLayerDocuments}
-   * for document update, atlas regeneration, SHA-256 computation, and IPFS pinning.
+   * The `/metadata` route delegates to {@link ObjectLayerEngine.persistObjectLayerDocuments}
+   * for the document write, atlas regeneration, SHA-256 computation, and IPFS pinning.
    *
    * @async
    * @function put
@@ -652,7 +672,6 @@ class ObjectLayerService {
 
     // PUT /:id/metadata/:itemType/:itemId - Update object layer metadata and reprocess all frames
     if (req.path.includes('/metadata/')) {
-      const objectLayerId = req.params.id;
       const itemType = req.params.itemType;
       const itemId = req.params.itemId;
 
@@ -683,24 +702,12 @@ class ObjectLayerService {
           metadataOverride: req.body,
         });
 
-      // Update documents using engine method (with atlas generation)
-      const { objectLayer } = await ObjectLayerEngine.updateObjectLayerDocuments({
-        objectLayerId,
+      const { objectLayer } = await ObjectLayerEngine.persistObjectLayerDocuments({
         ObjectLayer,
         ObjectLayerRenderFrames,
         objectLayerRenderFramesData,
         objectLayerData,
-        updateOptions: {
-          generateAtlas: true,
-          atlasServiceContext: {
-            req,
-            res,
-            options,
-            AtlasSpriteSheetService,
-            IpfsClient,
-            createPinRecord,
-          },
-        },
+        persistOptions: { options },
       });
 
       return objectLayer;
@@ -715,25 +722,19 @@ class ObjectLayerService {
     // Apply body updates to staging data in memory
     const updateData = { ...req.body };
     const stagingData = updateData.data || existingOL.data.toObject();
+    stagingData.stats = validateStats(stagingData.stats);
     if (!stagingData.render) stagingData.render = {};
 
-    // Use existing render frames if available
-    const renderFramesData = existingOL.objectLayerRenderFramesId;
-    if (renderFramesData) {
+    if (existingOL.objectLayerRenderFramesId) {
       try {
-        const stagingOL = {
-          data: stagingData,
-          objectLayerRenderFramesId: renderFramesData,
-        };
-        const result = await AtlasSpriteSheetService.generate(
-          { objectLayer: stagingOL, auth: req.auth },
-          res,
+        const { atlasDoc, atlasCid, atlasMetadataCid } = await AtlasSpriteSheetStore.persist({
+          itemKey: stagingData.item.id,
+          objectLayerRenderFrames: existingOL.objectLayerRenderFramesId,
           options,
-          { skipObjectLayerSave: true },
-        );
-        stagingData.render.cid = result.atlasCid;
-        stagingData.render.metadataCid = result.atlasMetadataCid;
-        updateData.atlasSpriteSheetId = result.atlasDoc._id;
+        });
+        stagingData.render.cid = atlasCid;
+        stagingData.render.metadataCid = atlasMetadataCid;
+        updateData.atlasSpriteSheetId = atlasDoc._id;
       } catch (atlasError) {
         logger.error('Failed to auto-update atlas for ObjectLayer:', atlasError);
       }
@@ -742,25 +743,17 @@ class ObjectLayerService {
     updateData.data = stagingData;
     updateData.sha256 = ObjectLayerEngine.computeSha256(stagingData);
 
-    // Pin data JSON to IPFS
-    try {
-      const itemId = stagingData.item.id;
-      const mfsPath = `/object-layer/${itemId}/${itemId}_data.json`;
-      const ipfsResult = await IpfsClient.addJsonToIpfs(stagingData, `${itemId}_data.json`, mfsPath);
-      if (ipfsResult) {
-        updateData.cid = ipfsResult.cid;
-        await createPinRecord({ cid: ipfsResult.cid, resourceType: 'object-layer-data', mfsPath, options });
-      }
-    } catch (ipfsError) {
-      logger.warn('Failed to pin data JSON to IPFS:', ipfsError.message);
-    }
+    const dataCid = await ObjectLayerEngine.pinObjectLayerData({
+      data: stagingData,
+      itemId: stagingData.item.id,
+      options,
+    });
+    if (dataCid) updateData.cid = dataCid;
 
-    // Atomic update with all CIDs populated
-    let updatedObjectLayer = await ObjectLayer.findByIdAndUpdate(req.params.id, updateData, {
+    return await ObjectLayer.findByIdAndUpdate(req.params.id, updateData, {
       returnDocument: 'after',
+      runValidators: true,
     }).populate('objectLayerRenderFramesId');
-
-    return updatedObjectLayer;
   };
 
   /**

package/src/api/object-layer-render-frames/object-layer-render-frames.controller.js

@@ -1,4 +1,4 @@
-import { buildCrudController } from '../../server/middlewares.js';
+import { buildCrudController } from '../../server/network/middlewares.js';
 import { ObjectLayerRenderFramesService } from './object-layer-render-frames.service.js';
 
 const ObjectLayerRenderFramesController = buildCrudController(ObjectLayerRenderFramesService);

package/src/api/object-layer-render-frames/object-layer-render-frames.router.js

@@ -1,5 +1,5 @@
 import express from 'express';
-import { registerCrudRoutes } from '../../server/middlewares.js';
+import { registerCrudRoutes } from '../../server/network/middlewares.js';
 import { ObjectLayerRenderFramesController } from './object-layer-render-frames.controller.js';
 
 class ObjectLayerRenderFramesRouter {

package/src/api/object-layer-render-frames/object-layer-render-frames.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';
 
 const logger = loggerFactory(import.meta);
 

package/src/api/test/test.controller.js

@@ -1,4 +1,4 @@
-import { controllerHandler, sendSuccess, serviceHandler } from '../../server/middlewares.js';
+import { controllerHandler, sendSuccess, serviceHandler } from '../../server/network/middlewares.js';
 import { TestService } from './test.service.js';
 
 class TestController {

package/src/api/test/test.service.js

@@ -1,5 +1,5 @@
 import validator from 'validator';
-import { loggerFactory } from '../../server/logger.js';
+import { loggerFactory } from '../../server/ops/logger.js';
 import { TestModel } from './test.model.js';
 import { getYouTubeID, validatePassword } from '../../client/components/core/CommonJs.js';
 

package/src/api/user/guest.service.js

@@ -1,7 +1,7 @@
 import mongoose from 'mongoose';
 import { UserDto } from './user.model.js';
-import { ValkeyAPI } from '../../server/valkey.js';
-import { hashPassword, getBearerToken, jwtSign } from '../../server/auth.js';
+import { ValkeyAPI } from '../../db/valkey/Valkey.js';
+import { hashPassword, getBearerToken, jwtSign } from '../../server/security/auth.js';
 
 // ─── TTL ──────────────────────────────────────────────────────────────────────
 
@@ -15,7 +15,7 @@ const _guestTtlMs = () => {
 /**
  * Constructs a new ephemeral guest user object.
  * This is domain logic specific to the guest lifecycle; it does not belong
- * in the generic Valkey storage module.
+ * in the Valkey database adapter.
  *
  * @param {{ host?: string }} options
  * @returns {object}

package/src/api/user/user.controller.js

@@ -1,4 +1,4 @@
-import { loggerFactory } from '../../server/logger.js';
+import { loggerFactory } from '../../server/ops/logger.js';
 import { UserService } from './user.service.js';
 
 const logger = loggerFactory(import.meta);

package/src/api/user/user.router.js

@@ -1,6 +1,6 @@
-import { hashPassword } from '../../server/auth.js';
+import { hashPassword } from '../../server/security/auth.js';
 import fs from 'fs-extra';
-import { loggerFactory } from '../../server/logger.js';
+import { loggerFactory } from '../../server/ops/logger.js';
 import { UserController } from './user.controller.js';
 import express from 'express';
 import { DataBaseProviderService } from '../../db/DataBaseProvider.js';

package/src/api/user/user.service.js

@@ -7,8 +7,8 @@
  * @namespace UserService
  */
 
-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 {
   hashPassword,
   verifyPassword,
@@ -19,7 +19,7 @@ import {
   logoutSession,
   jwtSign,
   validatePasswordMiddleware,
-} from '../../server/auth.js';
+} from '../../server/security/auth.js';
 import { MailerProvider } from '../../mailer/MailerProvider.js';
 import { CoreWsEmitter } from '../../ws/core/core.ws.emit.js';
 import { CoreWsMailerChannel } from '../../ws/core/channels/core.ws.mailer.js';
@@ -29,7 +29,7 @@ import { FileFactory, FileCleanup } from '../file/file.service.js';
 import { UserDto } from './user.model.js';
 import { timer } from '../../client/components/core/CommonJs.js';
 import { GuestService } from './guest.service.js';
-import { resolveHostKeyContext } from '../../server/conf.js';
+import { resolveHostKeyContext } from '../../server/runtime/conf.js';
 
 const logger = loggerFactory(import.meta);
 

package/src/api.js

@@ -1,18 +1,14 @@
 'use strict';
 
-// https://nodejs.org/api
-// https://expressjs.com/en/4x/api.html
-
 import dotenv from 'dotenv';
-import { loggerFactory } from './server/logger.js';
-import { buildClient } from './server/client-build.js';
-import { buildRuntime } from './server/runtime.js';
-import { ProcessController } from './server/process.js';
-import { Config } from './server/conf.js';
+import { loggerFactory } from './server/ops/logger.js';
+import { buildRuntime } from './server/runtime/runtime.js';
+import { ProcessController } from './server/runtime/process.js';
+import { Config, buildApiConf } from './server/runtime/conf.js';
 
 dotenv.config();
 
-await Config.build();
+await Config.build(undefined, undefined, await buildApiConf());
 
 const logger = loggerFactory(import.meta);