cyberia 3.0.1 → 3.0.2

package/src/server/object-layer.js

@@ -1,13 +1,17 @@
 /**
  * Provides utilities and engine logic for processing and managing Cyberia Online's object layer assets (skins, floors, weapons, etc.).
+ * Centralizes shared logic consumed by both the Cyberia CLI and the REST API service layer.
  * @module src/server/object-layer.js
  * @namespace CyberiaObjectLayer
  */
 
 import fs from 'fs-extra';
+import path from 'path';
 import { PNG } from 'pngjs';
 import sharp from 'sharp';
 import { Jimp, intToRGBA, rgbaToInt } from 'jimp';
+import crypto from 'crypto';
+import stringify from 'fast-json-stable-stringify';
 
 import { range } from '../client/components/core/CommonJs.js';
 import { random } from '../client/components/core/CommonJs.js';
@@ -21,14 +25,71 @@ const logger = loggerFactory(import.meta);
  * @property {string} objectLayerType - The type of object layer (e.g., 'skin', 'floor').
  * @property {string} objectLayerId - The unique ID of the object layer asset.
  * @property {string} direction - The direction folder name (e.g., '08', '12').
- * @memberof CyberiaObjectLayer
  * @property {string} frame - The frame file name.
+ * @memberof CyberiaObjectLayer
+ */
+
+/**
+ * @typedef {Object} ObjectLayerRenderFramesData
+ * @property {Object<string, number[][][]>} frames - Map of direction names to arrays of frame matrices.
+ * @property {Array<number[]>} colors - Global color palette shared across all frames.
+ * @property {number} frame_duration - Duration of each frame in milliseconds.
+ * @property {boolean} is_stateless - Whether the render layer is stateless (no animation state).
+ * @memberof CyberiaObjectLayer
  */
 
+/**
+ * @typedef {Object} ObjectLayerData
+ * @property {Object} data - Object layer data payload.
+ * @property {Object} data.item - Item descriptor.
+ * @property {string} data.item.id - Unique identifier for the item.
+ * @property {string} data.item.type - Type of the item (e.g., 'skin', 'floor').
+ * @property {string} [data.item.description] - Human-readable description.
+ * @property {boolean} [data.item.activable] - Whether the item can be activated.
+ * @property {Object} data.stats - Statistical attributes of the object layer.
+ * @property {string} data.seed - Random UUID v4 for unique state generation.
+ * @property {string} [data.atlasSpriteSheetCid] - IPFS CID for the consolidated atlas sprite sheet PNG.
+ * @property {ObjectLayerRenderFramesData} [objectLayerRenderFramesData] - Render frames data (transient, used before persisting).
+ * @property {import('mongoose').Types.ObjectId} [objectLayerRenderFramesId] - Reference to persisted ObjectLayerRenderFrames document.
+ * @property {string} [sha256] - SHA-256 hash of the object layer data.
+ * @memberof CyberiaObjectLayer
+ */
+
+/**
+ * @typedef {Object} BuildFromDirectoryResult
+ * @property {ObjectLayerRenderFramesData} objectLayerRenderFramesData - The assembled render frames data.
+ * @property {Object} objectLayerData - The assembled object layer data (without render frames reference or sha256).
+ * @memberof CyberiaObjectLayer
+ */
+
+/**
+ * @typedef {Object} CreateDocumentsOptions
+ * @property {boolean} [generateAtlas=true] - Whether to generate the atlas sprite sheet after creating documents.
+ * @property {Object} [atlasServiceContext] - Context required by AtlasSpriteSheetService.generate (req, res, options).
+ * @property {Object} [atlasServiceContext.req] - Express-like request object (must include auth).
+ * @property {Object} [atlasServiceContext.res] - Express-like response object.
+ * @property {Object} [atlasServiceContext.options] - Server options (host, path).
+ * @memberof CyberiaObjectLayer
+ */
+
+/**
+ * @typedef {Object} CreateDocumentsResult
+ * @property {Object} objectLayer - The persisted ObjectLayer mongoose document.
+ * @property {Object} objectLayerRenderFramesDoc - The persisted ObjectLayerRenderFrames mongoose document.
+ * @memberof CyberiaObjectLayer
+ */
+
+/**
+ * Engine class providing static utilities for Cyberia Online object layer asset processing,
+ * frame extraction, directory iteration, image building, and centralized document creation logic.
+ * @class ObjectLayerEngine
+ * @memberof CyberiaObjectLayer
+ */
 export class ObjectLayerEngine {
   /**
+   * Iterates through the directory structure of object layer PNG assets for a given type.
+   * Walks `./src/client/public/cyberia/assets/{objectLayerType}/{id}/{direction}/{frame}`.
    * @static
-   * @description Iterates through the directory structure of object layer PNG assets for a given type.
    * @param {string} [objectLayerType='skin'] - The type of object layer to iterate over (e.g., 'skin', 'floor').
    * @param {function(ObjectLayerCallbackPayload): Promise<void>} [callback=() => {}] - The async function to execute for each image file found.
    * @returns {Promise<void>}
@@ -61,10 +122,10 @@ export class ObjectLayerEngine {
   }
 
   /**
+   * Asynchronously reads a PNG file and resolves with its raw bitmap data, width, and height.
    * @static
-   * @description Asynchronously reads a PNG file and resolves with its raw bitmap data, width, and height.
    * @param {string} filePath - The path to the PNG file.
-   * @returns {Promise<{width: number, height: number, data: Buffer} | {error: true, message: string}>} - The image data or an error object.
+   * @returns {Promise<{width: number, height: number, data: Buffer} | {error: true, message: string}>} The image data or an error object.
    * @memberof CyberiaObjectLayer
    */
   static readPngAsync(filePath) {
@@ -87,12 +148,12 @@ export class ObjectLayerEngine {
   }
 
   /**
-   * @static
-   * @description Processes an image file (PNG or GIF) to generate a frame matrix and a color palette (map_color).
+   * Processes an image file (PNG or GIF) to generate a frame matrix and a color palette (map_color).
    * It quantizes the image based on a factor derived from image height (mazeFactor).
+   * @static
    * @param {string} path - The path to the image file.
    * @param {Array<number[]>} [colors=[]] - The existing color palette array to append new colors to.
-   * @returns {Promise<{frame: number[][], colors: Array<number[]>}>} - The frame matrix and the updated color palette.
+   * @returns {Promise<{frame: number[][], colors: Array<number[]>}>} The frame matrix and the updated color palette.
    * @memberof CyberiaObjectLayer
    */
   static async frameFactory(path, colors = []) {
@@ -146,10 +207,10 @@ export class ObjectLayerEngine {
   }
 
   /**
+   * Converts a numerical folder direction (e.g., '08', '14') into an array of corresponding keyframe names (e.g., 'down_idle', 'left_walking').
    * @static
-   * @description Converts a numerical folder direction (e.g., '08', '14') into an array of corresponding keyframe names (e.g., 'down_idle', 'left_walking').
    * @param {string} direction - The numerical direction string.
-   * @returns {string[]} - An array of keyframe direction names.
+   * @returns {string[]} An array of keyframe direction names.
    * @memberof CyberiaObjectLayer
    */
   static getKeyFramesDirectionsFromNumberFolderDirection(direction) {
@@ -186,14 +247,14 @@ export class ObjectLayerEngine {
   }
 
   /**
-   * @static
-   * @description Processes an image file through frameFactory and adds the resulting frame to the render data structure.
+   * Processes an image file through {@link ObjectLayerEngine.frameFactory} and adds the resulting frame to the render data structure.
    * Updates the color palette and pushes the frame to all keyframe directions corresponding to the given direction code.
    * Initializes colors array, frames object, and direction arrays if they don't exist.
-   * @param {Object} objectLayerRenderFramesData - The render data object containing frames and colors.
+   * @static
+   * @param {ObjectLayerRenderFramesData} objectLayerRenderFramesData - The render data object containing frames and colors.
    * @param {string} imagePath - The path to the image file to process.
    * @param {string} directionCode - The numerical direction code (e.g., '08', '14').
-   * @returns {Promise<Object>} - The updated render data object.
+   * @returns {Promise<ObjectLayerRenderFramesData>} The updated render data object.
    * @memberof CyberiaObjectLayer
    */
   static async processAndPushFrame(objectLayerRenderFramesData, imagePath, directionCode) {
@@ -231,8 +292,8 @@ export class ObjectLayerEngine {
   }
 
   /**
+   * Builds a PNG image file from a tile matrix and color map using Jimp and Sharp.
    * @static
-   * @description Builds a PNG image file from a tile matrix and color map using Jimp and Sharp.
    * @param {Object} options - Options object.
    * @param {Object} options.tile - The tile data.
    * @param {Array<number[]>} options.tile.map_color - The color palette.
@@ -295,9 +356,9 @@ export class ObjectLayerEngine {
   }
 
   /**
+   * Generates a random set of character statistics for an item, with values between 0 and 10.
    * @static
-   * @description Generates a random set of character statistics for an item, with values between 0 and 10.
-   * @returns {{effect: number, resistance: number, agility: number, range: number, intelligence: number, utility: number}} - The random stats object.
+   * @returns {{effect: number, resistance: number, agility: number, range: number, intelligence: number, utility: number}} The random stats object.
    * @memberof CyberiaObjectLayer
    */
   static generateRandomStats() {
@@ -310,22 +371,592 @@ export class ObjectLayerEngine {
       utility: random(0, 10),
     };
   }
+
+  // ──────────────────────────────────────────────────────────────────────────
+  // Centralized document lifecycle methods
+  // ──────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Scans a local asset directory for PNG frame images and assembles both
+   * {@link ObjectLayerRenderFramesData} and {@link ObjectLayerData} from the directory contents
+   * and an optional `metadata.json` file.
+   *
+   * This is the shared first step consumed by both the Cyberia CLI `--import` flow
+   * and the REST API service `post` / `put` `/metadata` endpoints.
+   *
+   * @static
+   * @param {Object} params - Parameters.
+   * @param {string} params.folder - Absolute or relative path to the asset folder
+   *   (e.g., `./src/client/public/cyberia/assets/skin/myskin`). Must contain numeric
+   *   direction sub-folders (`08`, `18`, …) with PNG frame files.
+   * @param {string} params.objectLayerType - The item type string (e.g., 'skin', 'floor').
+   * @param {string} params.objectLayerId - The item id string.
+   * @param {Object} [params.metadataOverride=null] - When provided, used as the authoritative
+   *   metadata instead of reading `metadata.json` from disk.  The REST API passes `req.body`
+   *   here; the CLI passes `null` so the file is read from disk.
+   * @returns {Promise<BuildFromDirectoryResult>} The assembled render frames data and object layer data.
+   * @memberof CyberiaObjectLayer
+   */
+  static async buildObjectLayerDataFromDirectory({ folder, objectLayerType, objectLayerId, metadataOverride = null }) {
+    let metadata = metadataOverride;
+
+    // If no override was supplied, try to read metadata.json from the folder
+    if (!metadata) {
+      const metadataPath = `${folder}/metadata.json`;
+      if (fs.existsSync(metadataPath)) {
+        metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf8'));
+      }
+    }
+
+    // Build objectLayerRenderFramesData
+    let objectLayerRenderFramesData;
+    if (metadata && metadata.objectLayerRenderFramesData) {
+      objectLayerRenderFramesData = {
+        frame_duration: metadata.objectLayerRenderFramesData.frame_duration || 250,
+        is_stateless: metadata.objectLayerRenderFramesData.is_stateless || false,
+        frames: {},
+        colors: [],
+      };
+    } else if (metadata && metadata.data && metadata.data.render) {
+      objectLayerRenderFramesData = {
+        frame_duration: metadata.data.render.frame_duration || 250,
+        is_stateless: metadata.data.render.is_stateless || false,
+        frames: {},
+        colors: [],
+      };
+    } else {
+      objectLayerRenderFramesData = {
+        frame_duration: 250,
+        is_stateless: false,
+        frames: {},
+        colors: [],
+      };
+    }
+
+    // Build objectLayerData
+    let objectLayerData;
+    if (metadata && metadata.data) {
+      objectLayerData = {
+        data: {
+          item: metadata.data.item || {
+            id: objectLayerId,
+            type: objectLayerType,
+            description: '',
+            activable: true,
+          },
+          stats: metadata.data.stats || ObjectLayerEngine.generateRandomStats(),
+          seed: metadata.data.seed || crypto.randomUUID(),
+        },
+      };
+    } else {
+      objectLayerData = {
+        data: {
+          item: {
+            id: objectLayerId,
+            type: objectLayerType,
+            description: '',
+            activable: true,
+          },
+          stats: ObjectLayerEngine.generateRandomStats(),
+          seed: crypto.randomUUID(),
+        },
+      };
+    }
+
+    // Process all PNG files from direction sub-folders
+    if (fs.existsSync(folder)) {
+      const directionFolders = await fs.readdir(folder);
+      for (const directionCode of directionFolders) {
+        const directionPath = `${folder}/${directionCode}`;
+
+        // Skip non-directories (metadata.json, etc.)
+        try {
+          const stat = await fs.stat(directionPath);
+          if (!stat.isDirectory()) continue;
+        } catch (error) {
+          logger.warn(`Skipping ${directionCode}: ${error.message}`);
+          continue;
+        }
+
+        const frameFiles = await fs.readdir(directionPath);
+        // Sort frame files numerically
+        frameFiles.sort((a, b) => {
+          const numA = parseInt(a.split('.')[0]);
+          const numB = parseInt(b.split('.')[0]);
+          return numA - numB;
+        });
+
+        for (const frameFile of frameFiles) {
+          if (!frameFile.endsWith('.png')) continue;
+
+          const framePath = `${directionPath}/${frameFile}`;
+          await ObjectLayerEngine.processAndPushFrame(objectLayerRenderFramesData, framePath, directionCode);
+        }
+      }
+    }
+
+    return { objectLayerRenderFramesData, objectLayerData };
+  }
+
+  /**
+   * Computes a SHA-256 hash of the given object layer data using deterministic JSON serialisation.
+   * @static
+   * @param {Object} data - The `data` sub-document of an ObjectLayer (item, stats, seed, atlasSpriteSheetCid, …).
+   * @returns {string} Hex-encoded SHA-256 hash.
+   * @memberof CyberiaObjectLayer
+   */
+  static computeSha256(data) {
+    return crypto.createHash('sha256').update(stringify(data)).digest('hex');
+  }
+
+  /**
+   * Map of keyframe direction names to their numeric folder direction codes.
+   * Inverse of {@link ObjectLayerEngine.getKeyFramesDirectionsFromNumberFolderDirection}.
+   * @static
+   * @type {Object<string, string>}
+   * @memberof CyberiaObjectLayer
+   */
+  static directionNameToCode = {
+    down_idle: '08',
+    none_idle: '08',
+    default_idle: '08',
+    up_idle: '02',
+    left_idle: '04',
+    up_left_idle: '04',
+    down_left_idle: '04',
+    right_idle: '06',
+    up_right_idle: '06',
+    down_right_idle: '06',
+    down_walking: '18',
+    up_walking: '12',
+    left_walking: '14',
+    up_left_walking: '14',
+    down_left_walking: '14',
+    right_walking: '16',
+    up_right_walking: '16',
+    down_right_walking: '16',
+  };
+
+  /**
+   * Writes frame PNGs and an optional metadata.json to one or more base asset
+   * directories.  This is the shared write-to-disk step consumed by both the
+   * Cyberia CLI `--generate` / `--import` flows and the REST API service
+   * `post` / `put` `/metadata` endpoints.
+   *
+   * For each base path the layout produced is:
+   * ```
+   * {basePath}/assets/{itemType}/{itemId}/{directionCode}/{frameIndex}.png
+   * {basePath}/assets/{itemType}/{itemId}/metadata.json          (optional)
+   * ```
+   *
+   * @static
+   * @param {Object} params
+   * @param {string[]} params.basePaths - One or more root paths
+   *   (e.g. `['./src/client/public/cyberia/', './public/host/path/']`).
+   *   The conventional `assets/` prefix is appended automatically.
+   * @param {string} params.itemType - Object layer type ('floor', 'skin', …).
+   * @param {string} params.itemId   - Unique item identifier.
+   * @param {ObjectLayerRenderFramesData} params.objectLayerRenderFramesData
+   *   - The render frames data containing `frames`, `colors`,
+   *     `frame_duration` and `is_stateless`.
+   * @param {Object} [params.objectLayerData=null] - When provided, a
+   *   `metadata.json` file is written alongside the frame PNGs.
+   * @param {number} [params.cellPixelDim=20] - Pixel size per grid cell.
+   * @returns {Promise<string[]>} Flat list of every file path written.
+   * @memberof CyberiaObjectLayer
+   */
+  static async writeStaticFrameAssets({
+    basePaths,
+    itemType,
+    itemId,
+    objectLayerRenderFramesData,
+    objectLayerData = null,
+    cellPixelDim = 20,
+  }) {
+    const writtenPaths = [];
+    const dirToCode = ObjectLayerEngine.directionNameToCode;
+
+    for (const basePath of basePaths) {
+      // Track which directionCode/frameIndex combos we already wrote for
+      // this basePath so duplicate direction names (e.g. down_idle,
+      // none_idle, default_idle all map to '08') only write once.
+      const written = new Set();
+
+      for (const [dirName, dirFrames] of Object.entries(objectLayerRenderFramesData.frames)) {
+        const code = dirToCode[dirName];
+        if (!code) continue;
+
+        for (let fi = 0; fi < dirFrames.length; fi++) {
+          const key = `${code}/${fi}`;
+          if (written.has(key)) continue;
+          written.add(key);
+
+          const dirFolder = path.join(basePath, 'assets', itemType, itemId, code);
+          await fs.ensureDir(dirFolder);
+
+          const filePath = path.join(dirFolder, `${fi}.png`);
+
+          await ObjectLayerEngine.buildImgFromTile({
+            tile: {
+              map_color: objectLayerRenderFramesData.colors,
+              frame_matrix: dirFrames[fi],
+            },
+            cellPixelDim,
+            opacityFilter: (x, y, color) => 255,
+            imagePath: filePath,
+          });
+
+          writtenPaths.push(filePath);
+        }
+      }
+
+      // Write metadata.json when objectLayerData is supplied
+      if (objectLayerData) {
+        const metaDir = path.join(basePath, 'assets', itemType, itemId);
+        await fs.ensureDir(metaDir);
+        const metadataPath = path.join(metaDir, 'metadata.json');
+
+        await fs.writeJson(
+          metadataPath,
+          {
+            data: objectLayerData.data,
+            objectLayerRenderFramesData: {
+              frame_duration: objectLayerRenderFramesData.frame_duration,
+              is_stateless: objectLayerRenderFramesData.is_stateless,
+            },
+            generated: true,
+            generatorVersion: '1.0.0',
+          },
+          { spaces: 2 },
+        );
+        writtenPaths.push(metadataPath);
+      }
+    }
+
+    return writtenPaths;
+  }
+
+  /**
+   * Creates new ObjectLayerRenderFrames and ObjectLayer documents in MongoDB from the
+   * provided data, computes an initial SHA-256, and optionally generates the atlas sprite sheet.
+   *
+   * When `generateAtlas` is `true` (the default) the method delegates to
+   * `AtlasSpriteSheetService.generate` and then recomputes the definitive SHA-256
+   * (which now includes `data.atlasSpriteSheetCid`) and persists an IPFS CID.
+   *
+   * @static
+   * @param {Object} params - Parameters.
+   * @param {Object} params.ObjectLayer - Mongoose ObjectLayer model.
+   * @param {Object} params.ObjectLayerRenderFrames - Mongoose ObjectLayerRenderFrames model.
+   * @param {ObjectLayerRenderFramesData} params.objectLayerRenderFramesData - Render frames payload.
+   * @param {Object} params.objectLayerData - Object layer payload (must include `data`).
+   * @param {CreateDocumentsOptions} [params.createOptions={}] - Additional options controlling atlas generation and IPFS pinning.
+   * @returns {Promise<CreateDocumentsResult>} The persisted documents.
+   * @memberof CyberiaObjectLayer
+   */
+  static async createObjectLayerDocuments({
+    ObjectLayer,
+    ObjectLayerRenderFrames,
+    objectLayerRenderFramesData,
+    objectLayerData,
+    createOptions = {},
+  }) {
+    const { generateAtlas = true, atlasServiceContext = null } = createOptions;
+
+    // 1. Persist ObjectLayerRenderFrames
+    const objectLayerRenderFramesDoc = await ObjectLayerRenderFrames.create(objectLayerRenderFramesData);
+
+    // 2. Attach reference + compute temporary SHA-256
+    objectLayerData.objectLayerRenderFramesId = objectLayerRenderFramesDoc._id;
+    objectLayerData.data.atlasSpriteSheetCid = objectLayerData.data.atlasSpriteSheetCid || '';
+    objectLayerData.sha256 = ObjectLayerEngine.computeSha256(objectLayerData.data);
+
+    // 3. Upsert ObjectLayer (handle duplicate sha256 gracefully)
+    let objectLayer;
+    const existingObjectLayer = await ObjectLayer.findOne({ sha256: objectLayerData.sha256 });
+    if (existingObjectLayer) {
+      logger.info(`ObjectLayer with sha256 ${objectLayerData.sha256} already exists, updating...`);
+      objectLayer = await ObjectLayer.findByIdAndUpdate(existingObjectLayer._id, objectLayerData, {
+        new: true,
+      }).populate('objectLayerRenderFramesId');
+    } else {
+      objectLayer = await (await ObjectLayer.create(objectLayerData)).populate('objectLayerRenderFramesId');
+      logger.info(`ObjectLayer created successfully with id: ${objectLayer._id}`);
+    }
+
+    // 4. Optional atlas generation + final SHA-256 / IPFS CID
+    if (generateAtlas && atlasServiceContext) {
+      objectLayer = await ObjectLayerEngine._generateAtlasAndFinalize({
+        objectLayer,
+        ObjectLayer,
+        atlasServiceContext,
+        isNew: true,
+      });
+    }
+
+    return { objectLayer, objectLayerRenderFramesDoc };
+  }
+
+  /**
+   * Updates an existing ObjectLayer and its ObjectLayerRenderFrames from the provided data,
+   * recomputes SHA-256, and optionally regenerates the atlas sprite sheet.
+   *
+   * @static
+   * @param {Object} params - Parameters.
+   * @param {string} params.objectLayerId - The `_id` of the ObjectLayer document to update.
+   * @param {Object} params.ObjectLayer - Mongoose ObjectLayer model.
+   * @param {Object} params.ObjectLayerRenderFrames - Mongoose ObjectLayerRenderFrames model.
+   * @param {ObjectLayerRenderFramesData} params.objectLayerRenderFramesData - Render frames payload.
+   * @param {Object} params.objectLayerData - Object layer payload (must include `data`).
+   * @param {CreateDocumentsOptions} [params.updateOptions={}] - Additional options controlling atlas generation and IPFS pinning.
+   * @returns {Promise<CreateDocumentsResult>} The persisted documents.
+   * @memberof CyberiaObjectLayer
+   */
+  static async updateObjectLayerDocuments({
+    objectLayerId,
+    ObjectLayer,
+    ObjectLayerRenderFrames,
+    objectLayerRenderFramesData,
+    objectLayerData,
+    updateOptions = {},
+  }) {
+    const { generateAtlas = true, atlasServiceContext = null } = updateOptions;
+
+    // 1. Update or create ObjectLayerRenderFrames
+    let objectLayerRenderFramesDoc;
+    const existingObjectLayer = await ObjectLayer.findById(objectLayerId);
+    if (existingObjectLayer && existingObjectLayer.objectLayerRenderFramesId) {
+      objectLayerRenderFramesDoc = await ObjectLayerRenderFrames.findByIdAndUpdate(
+        existingObjectLayer.objectLayerRenderFramesId,
+        objectLayerRenderFramesData,
+        { new: true },
+      );
+      objectLayerData.objectLayerRenderFramesId = existingObjectLayer.objectLayerRenderFramesId;
+    } else {
+      objectLayerRenderFramesDoc = await ObjectLayerRenderFrames.create(objectLayerRenderFramesData);
+      objectLayerData.objectLayerRenderFramesId = objectLayerRenderFramesDoc._id;
+    }
+
+    // 2. Compute temporary SHA-256
+    objectLayerData.data.atlasSpriteSheetCid = objectLayerData.data.atlasSpriteSheetCid || '';
+    objectLayerData.sha256 = ObjectLayerEngine.computeSha256(objectLayerData.data);
+
+    // 3. Persist ObjectLayer update
+    let objectLayer;
+    try {
+      objectLayer = await ObjectLayer.findByIdAndUpdate(objectLayerId, objectLayerData, {
+        new: true,
+      }).populate('objectLayerRenderFramesId');
+      if (!objectLayer) {
+        throw new Error('ObjectLayer not found for update');
+      }
+      logger.info(`ObjectLayer updated successfully with id: ${objectLayerId}`);
+    } catch (error) {
+      logger.error('Error updating ObjectLayer:', error);
+      throw error;
+    }
+
+    // 4. Optional atlas generation + final SHA-256 / IPFS CID
+    if (generateAtlas && atlasServiceContext) {
+      objectLayer = await ObjectLayerEngine._generateAtlasAndFinalize({
+        objectLayer,
+        ObjectLayer,
+        atlasServiceContext,
+        isNew: false,
+      });
+    }
+
+    return { objectLayer, objectLayerRenderFramesDoc };
+  }
+
+  /**
+   * Recomputes the definitive SHA-256, pins the object layer data JSON to IPFS,
+   * and persists both fields on the ObjectLayer document.
+   *
+   * Intended for use after atlas generation has set `data.atlasSpriteSheetCid`.
+   *
+   * @static
+   * @param {Object} params - Parameters.
+   * @param {Object} params.objectLayer - The mongoose ObjectLayer document (must be populated).
+   * @param {Object} [params.ipfsClient=null] - The IpfsClient module; when `null`, IPFS pinning is skipped.
+   * @param {function} [params.createPinRecord=null] - The `createPinRecord` helper; when `null`, pin records are skipped.
+   * @param {string} [params.userId] - Authenticated user ID for IPFS pin record creation.
+   * @param {Object} [params.options] - Server options (host, path) forwarded to `createPinRecord`.
+   * @returns {Promise<Object>} The saved ObjectLayer document.
+   * @memberof CyberiaObjectLayer
+   */
+  static async computeAndSaveFinalSha256({ objectLayer, ipfsClient = null, createPinRecord = null, userId, options }) {
+    const finalSha256 = ObjectLayerEngine.computeSha256(objectLayer.data);
+
+    if (ipfsClient) {
+      try {
+        const itemId = objectLayer.data.item.id;
+        const ipfsResult = await ipfsClient.addJsonToIpfs(
+          objectLayer.data,
+          `${itemId}_data.json`,
+          `/object-layer/${itemId}/${itemId}_data.json`,
+        );
+        if (ipfsResult) {
+          objectLayer.cid = ipfsResult.cid;
+          if (userId && createPinRecord) {
+            await createPinRecord({ cid: ipfsResult.cid, userId, options });
+          }
+        }
+      } catch (ipfsError) {
+        logger.warn('Failed to add object layer data to IPFS:', ipfsError.message);
+      }
+    }
+
+    objectLayer.sha256 = finalSha256;
+    objectLayer.markModified('data');
+    await objectLayer.save();
+
+    return objectLayer;
+  }
+
+  /**
+   * Internal helper that generates an atlas sprite sheet and then finalizes the SHA-256 / IPFS CID.
+   * @static
+   * @param {Object} params - Parameters.
+   * @param {Object} params.objectLayer - The mongoose ObjectLayer document.
+   * @param {Object} params.ObjectLayer - Mongoose ObjectLayer model (for re-reading).
+   * @param {Object} params.atlasServiceContext - Context with `{ req, res, options, AtlasSpriteSheetService, IpfsClient, createPinRecord }`.
+   * @param {boolean} params.isNew - Whether this is a newly created object layer (used for logging).
+   * @returns {Promise<Object>} The finalized ObjectLayer document.
+   * @memberof CyberiaObjectLayer
+   * @private
+   */
+  static async _generateAtlasAndFinalize({ objectLayer, ObjectLayer, atlasServiceContext, isNew }) {
+    const { req, res, options, AtlasSpriteSheetService, IpfsClient: ipfsClient, createPinRecord } = atlasServiceContext;
+
+    // Generate atlas sprite sheet
+    try {
+      await AtlasSpriteSheetService.generate(
+        { params: { id: objectLayer._id }, objectLayer, auth: req ? req.auth : undefined },
+        res,
+        options,
+      );
+    } catch (atlasError) {
+      logger.error(`Failed to auto-${isNew ? 'generate' : 'update'} atlas for ObjectLayer:`, atlasError);
+    }
+
+    // Re-read the objectLayer so data.atlasSpriteSheetCid is up-to-date
+    objectLayer = await ObjectLayer.findById(objectLayer._id).populate('objectLayerRenderFramesId');
+
+    // Compute definitive SHA-256 and IPFS CID
+    const userId = req && req.auth && req.auth.user ? req.auth.user._id : undefined;
+    objectLayer = await ObjectLayerEngine.computeAndSaveFinalSha256({
+      objectLayer,
+      ipfsClient: ipfsClient || null,
+      createPinRecord: createPinRecord || null,
+      userId,
+      options,
+    });
+
+    return objectLayer;
+  }
 }
 
 /**
+ * Mapping of item type names to numerical IDs.
  * @constant
- * @description Mapping of item type names to numerical IDs.
  * @type {{floor: number, skin: number, weapon: number, skill: number, coin: number}}
  * @memberof CyberiaObjectLayer
  */
 export const itemTypes = { floor: 0, skin: 1, weapon: 2, skill: 3, coin: 4 };
 
-// Export equivalent for backward compatibility with existing destructured imports.
+// ──────────────────────────────────────────────────────────────────────────
+// Backward-compatible named exports matching the original destructured imports.
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * @see {@link ObjectLayerEngine.pngDirectoryIteratorByObjectLayerType}
+ * @function pngDirectoryIteratorByObjectLayerType
+ * @memberof CyberiaObjectLayer
+ */
 export const pngDirectoryIteratorByObjectLayerType = ObjectLayerEngine.pngDirectoryIteratorByObjectLayerType;
+
+/**
+ * @see {@link ObjectLayerEngine.readPngAsync}
+ * @function readPngAsync
+ * @memberof CyberiaObjectLayer
+ */
 export const readPngAsync = ObjectLayerEngine.readPngAsync;
+
+/**
+ * @see {@link ObjectLayerEngine.frameFactory}
+ * @function frameFactory
+ * @memberof CyberiaObjectLayer
+ */
 export const frameFactory = ObjectLayerEngine.frameFactory;
+
+/**
+ * @see {@link ObjectLayerEngine.getKeyFramesDirectionsFromNumberFolderDirection}
+ * @function getKeyFramesDirectionsFromNumberFolderDirection
+ * @memberof CyberiaObjectLayer
+ */
 export const getKeyFramesDirectionsFromNumberFolderDirection =
   ObjectLayerEngine.getKeyFramesDirectionsFromNumberFolderDirection;
+
+/**
+ * @see {@link ObjectLayerEngine.processAndPushFrame}
+ * @function processAndPushFrame
+ * @memberof CyberiaObjectLayer
+ */
 export const processAndPushFrame = ObjectLayerEngine.processAndPushFrame;
+
+/**
+ * @see {@link ObjectLayerEngine.buildImgFromTile}
+ * @function buildImgFromTile
+ * @memberof CyberiaObjectLayer
+ */
 export const buildImgFromTile = ObjectLayerEngine.buildImgFromTile;
+
+/**
+ * @see {@link ObjectLayerEngine.generateRandomStats}
+ * @function generateRandomStats
+ * @memberof CyberiaObjectLayer
+ */
 export const generateRandomStats = ObjectLayerEngine.generateRandomStats;
+
+/**
+ * @see {@link ObjectLayerEngine.buildObjectLayerDataFromDirectory}
+ * @function buildObjectLayerDataFromDirectory
+ * @memberof CyberiaObjectLayer
+ */
+export const buildObjectLayerDataFromDirectory = ObjectLayerEngine.buildObjectLayerDataFromDirectory;
+
+/**
+ * @see {@link ObjectLayerEngine.computeSha256}
+ * @function computeSha256
+ * @memberof CyberiaObjectLayer
+ */
+export const computeSha256 = ObjectLayerEngine.computeSha256;
+
+/**
+ * @see {@link ObjectLayerEngine.createObjectLayerDocuments}
+ * @function createObjectLayerDocuments
+ * @memberof CyberiaObjectLayer
+ */
+export const createObjectLayerDocuments = ObjectLayerEngine.createObjectLayerDocuments;
+
+/**
+ * @see {@link ObjectLayerEngine.updateObjectLayerDocuments}
+ * @function updateObjectLayerDocuments
+ * @memberof CyberiaObjectLayer
+ */
+export const updateObjectLayerDocuments = ObjectLayerEngine.updateObjectLayerDocuments;
+
+/**
+ * @see {@link ObjectLayerEngine.computeAndSaveFinalSha256}
+ * @function computeAndSaveFinalSha256
+ * @memberof CyberiaObjectLayer
+ */
+export const computeAndSaveFinalSha256 = ObjectLayerEngine.computeAndSaveFinalSha256;
+
+/**
+ * @see {@link ObjectLayerEngine.writeStaticFrameAssets}
+ * @function writeStaticFrameAssets
+ * @memberof CyberiaObjectLayer
+ */
+export const writeStaticFrameAssets = ObjectLayerEngine.writeStaticFrameAssets;