@underpostnet/cyberia 3.3.73 → 3.3.76

package/src/db/mongo/MongoExpress.js

@@ -0,0 +1,187 @@
+/**
+ * Mongo Express Deployment Module
+ * @module src/db/mongo/MongoExpress
+ * @namespace MongoExpress
+ * @description Deploys the mongo-express web client used to inspect the cluster's MongoDB
+ * StatefulSet collections. The workload is a plain Deployment plus a ClusterIP Service, so the
+ * same manifests converge identically under Kind, Kubeadm and K3s; the only runtime-dependent
+ * decision is whether the deployed mongod enforces authentication, which selects the overlay.
+ */
+
+import { loggerFactory } from '../../server/ops/logger.js';
+import { shellExec } from '../../server/runtime/process.js';
+// Cyclic by construction (index -> cluster -> MongoExpress -> index), same as MongoBootstrap.js.
+// Safe because the binding is only dereferenced inside method bodies, never at module scope.
+import Underpost from '../../index.js';
+import { MONGODB_DEFAULT_PORT, MONGODB_SERVICE_NAME, MONGODB_STATEFULSET_NAME } from './MongooseDB.js';
+
+const logger = loggerFactory(import.meta);
+
+const MONGO_EXPRESS_NAME = 'mongo-express';
+const MONGO_EXPRESS_SERVICE_NAME = 'mongo-express-service';
+const MONGO_EXPRESS_IMAGE = 'mongo-express:1.0.2';
+const MONGO_EXPRESS_PORT = 8081;
+const MONGO_EXPRESS_NODE_PORT = 32081;
+const MONGO_EXPRESS_BASE_URL = '/mongo/';
+// The UI reads the root credentials and gates its own session with the same pair, so it consumes
+// the StatefulSet's secret rather than owning a second credential of its own.
+const MONGO_EXPRESS_SECRET_NAME = 'mongodb-secret';
+const MONGO_EXPRESS_MANIFEST_DIR = 'manifests/deployment/mongo-express';
+const MONGO_EXPRESS_NO_AUTH_MANIFEST_DIR = 'manifests/deployment/mongo-express-no-auth';
+
+// Literal and unescaped: kubectl's jsonpath quotes carry escape sequences of their own, and no
+// mongod argument contains a pipe.
+const MONGOD_ARGS_FIELD_SEPARATOR = '|';
+
+/**
+ * Parses the mongod argument vector reported by `kubectl -o jsonpath` for the StatefulSet.
+ * @param {string} raw - Raw jsonpath stdout: the StatefulSet name, then one field per argument.
+ * @returns {Array<string>|null} Argument vector, or null when no StatefulSet was reported.
+ * @memberof MongoExpress
+ */
+const parseMongodArgs = (raw) => {
+  const value = `${raw || ''}`;
+  if (!value.trim()) return null;
+  const [, ...args] = value.split(MONGOD_ARGS_FIELD_SEPARATOR);
+  return args.map((arg) => arg.trim()).filter(Boolean);
+};
+
+/**
+ * Decides whether mongo-express must authenticate against the deployed mongod.
+ *
+ * The deployed StatefulSet is the authority: `manifests/mongodb` starts mongod with `--auth` and
+ * `manifests/mongodb-4.4` does not, and either can be the one running regardless of which flag
+ * this invocation carries. The flags only answer for a cluster with no StatefulSet deployed yet,
+ * where `--mongodb` (the auth-enabled manifest set) is the default the platform installs.
+ * @param {object} [params={}] - Resolution inputs.
+ * @param {Array<string>|null} [params.args=null] - mongod argument vector, or null when undeployed.
+ * @param {object} [params.options={}] - Cluster options (`mongodb`, `mongodb4`).
+ * @returns {boolean} True when the admin credential pair must be projected.
+ * @memberof MongoExpress
+ */
+const mongoAuthEnabledFactory = ({ args = null, options = {} } = {}) => {
+  if (Array.isArray(args)) return args.includes('--auth');
+  return options.mongodb4 !== true;
+};
+
+/**
+ * Resolves the kustomization root the auth mode selects.
+ * @param {object} [params={}] - Path inputs.
+ * @param {string} [params.underpostRoot='.'] - Repository root holding `manifests/`.
+ * @param {boolean} [params.authEnabled=true] - Whether mongod enforces authentication.
+ * @returns {string} Kustomization directory path.
+ * @memberof MongoExpress
+ */
+const mongoExpressManifestPathFactory = ({ underpostRoot = '.', authEnabled = true } = {}) =>
+  `${underpostRoot}/${authEnabled ? MONGO_EXPRESS_MANIFEST_DIR : MONGO_EXPRESS_NO_AUTH_MANIFEST_DIR}`;
+
+/**
+ * Resolves the opt-in NodePort Service manifest path. It lives in the base directory and is left
+ * out of both kustomizations: exposing an admin UI on the node network is a caller's decision.
+ * @param {object} [params={}] - Path inputs.
+ * @param {string} [params.underpostRoot='.'] - Repository root holding `manifests/`.
+ * @returns {string} NodePort manifest path.
+ * @memberof MongoExpress
+ */
+const mongoExpressNodePortManifestFactory = ({ underpostRoot = '.' } = {}) =>
+  `${underpostRoot}/${MONGO_EXPRESS_MANIFEST_DIR}/mongo-express-nodeport.yaml`;
+
+/**
+ * @class MongoExpress
+ * @description Static deployment surface for the mongo-express admin client.
+ * @memberof MongoExpress
+ */
+class MongoExpress {
+  /**
+   * Reads the mongod argument vector from the deployed MongoDB StatefulSet.
+   *
+   * The projection leads with the StatefulSet name so a deployed server that declares no arguments
+   * stays distinguishable from no server at all — one is mongod on its defaults, the other is a
+   * cluster with no data tier yet, and both would otherwise reduce to empty output.
+   * @param {string} [namespace='default'] - Namespace holding the StatefulSet.
+   * @returns {Array<string>|null} Argument vector, or null when no StatefulSet is deployed.
+   * @memberof MongoExpress
+   */
+  static readMongodArgs(namespace = 'default') {
+    const raw = shellExec(
+      `kubectl get statefulset ${MONGODB_STATEFULSET_NAME} -n ${namespace} --ignore-not-found -o jsonpath=` +
+        `'{.metadata.name}{"${MONGOD_ARGS_FIELD_SEPARATOR}"}` +
+        `{range .spec.template.spec.containers[?(@.name=="${MONGODB_STATEFULSET_NAME}")].args[*]}` +
+        `{@}{"${MONGOD_ARGS_FIELD_SEPARATOR}"}{end}'`,
+      { stdout: true, silent: true, silentOnError: true },
+    );
+    return parseMongodArgs(raw);
+  }
+
+  /**
+   * Deploys mongo-express and, once it is Ready, applies the exposure and placement the caller
+   * asked for. Cluster-type agnostic by construction: only the image pull differs between Kind
+   * (loaded into the node's image store) and Kubeadm/K3s (pulled through the CRI).
+   * @param {object} [params={}] - Deployment parameters.
+   * @param {string} [params.namespace='default'] - Target namespace.
+   * @param {string} [params.underpostRoot='.'] - Repository root holding `manifests/`.
+   * @param {object} [params.options={}] - Cluster options (`pullImage`, `nodePort`, `nodeName`, `mongodb4`).
+   * @returns {Promise<boolean>} Whether the deployment reported Ready.
+   * @memberof MongoExpress
+   */
+  static async deploy({ namespace = 'default', underpostRoot = '.', options = {} } = {}) {
+    // Secret before workload: the Deployment's secretKeyRef must resolve at pod admission, and
+    // the encrypted store stays the source of truth wherever a manifest exists.
+    if (!Underpost.secret.applyIfPresent(MONGO_EXPRESS_SECRET_NAME, namespace))
+      Underpost.secret.applyFromOriginSeed(MONGO_EXPRESS_SECRET_NAME, namespace);
+
+    if (options.pullImage) Underpost.cluster.pullImage(MONGO_EXPRESS_IMAGE, options);
+
+    const args = MongoExpress.readMongodArgs(namespace);
+    const authEnabled = mongoAuthEnabledFactory({ args, options });
+    const manifestPath = mongoExpressManifestPathFactory({ underpostRoot, authEnabled });
+    logger.info('Deploying mongo-express', {
+      namespace,
+      authEnabled,
+      manifestPath,
+      mongodb: args ? 'deployed' : 'not deployed',
+    });
+    shellExec(`kubectl apply -k ${manifestPath} -n ${namespace}`);
+
+    const ready = await Underpost.test.statusMonitor(MONGO_EXPRESS_NAME, 'Running', 'pods', 1000, 60 * 10);
+    if (!ready) {
+      logger.error('mongo-express did not report Running', { namespace });
+      return false;
+    }
+
+    if (options.nodePort)
+      shellExec(`kubectl apply -f ${mongoExpressNodePortManifestFactory({ underpostRoot })} -n ${namespace}`);
+    if (options.nodeName)
+      Underpost.cluster.pinToNode({
+        kind: 'deployment',
+        name: MONGO_EXPRESS_NAME,
+        namespace,
+        node: options.nodeName,
+      });
+
+    logger.info('mongo-express ready', {
+      server: `${MONGODB_STATEFULSET_NAME}-0.${MONGODB_SERVICE_NAME}:${MONGODB_DEFAULT_PORT}`,
+      basicAuth: `secret/${MONGO_EXPRESS_SECRET_NAME}`,
+      clusterIp: `${MONGO_EXPRESS_SERVICE_NAME}:${MONGO_EXPRESS_PORT}${MONGO_EXPRESS_BASE_URL}`,
+      nodePort: options.nodePort ? `<node>:${MONGO_EXPRESS_NODE_PORT}${MONGO_EXPRESS_BASE_URL}` : null,
+      portForward: `kubectl port-forward -n ${namespace} svc/${MONGO_EXPRESS_SERVICE_NAME} ${MONGO_EXPRESS_PORT}:${MONGO_EXPRESS_PORT}`,
+    });
+    return true;
+  }
+}
+
+export {
+  MONGO_EXPRESS_BASE_URL,
+  MONGO_EXPRESS_IMAGE,
+  MONGO_EXPRESS_NAME,
+  MONGO_EXPRESS_NODE_PORT,
+  MONGO_EXPRESS_PORT,
+  MONGO_EXPRESS_SECRET_NAME,
+  MONGO_EXPRESS_SERVICE_NAME,
+  MongoExpress,
+  mongoAuthEnabledFactory,
+  mongoExpressManifestPathFactory,
+  mongoExpressNodePortManifestFactory,
+  parseMongodArgs,
+};
+export default MongoExpress;

package/src/grpc/cyberia/grpc-server.js

@@ -1,10 +1,9 @@
 /**
  * gRPC transport for the Cyberia Engine data pipeline.
  *
- * Runs alongside Express on a separate port (default 50051).
- * Thin adapter over src/projects/cyberia/instance-data.js — the shared
- * world-load/boot assembly also served by the REST fallback at
- * /api/cyberia-instance/boot/* — so both transports stay equivalent.
+ * Runs beside Express on its own port (default 50051). Thin adapter over
+ * src/projects/cyberia/instance-data.js, the same assembly the REST fallback
+ * at /api/cyberia-instance/boot/* serves, so both transports stay equivalent.
  *
  * @module src/grpc/cyberia/grpc-server.js
  */
@@ -16,7 +15,6 @@ import { fileURLToPath } from 'url';
 import { loggerFactory } from '../../server/ops/logger.js';
 import {
   buildFallbackConfig,
-  buildFallbackInstanceConfig,
   fetchFullInstance,
   fetchMapData,
   fetchObjectLayer,
@@ -131,7 +129,7 @@ class GrpcServer {
 
     server.addService(proto.CyberiaDataService.service, buildHandlers(dbKey));
 
-    // gRPC runs over Kubernetes internal network (ClusterIP) — always insecure
+    // gRPC stays on the cluster-internal network, so credentials are insecure.
     const creds = grpc.ServerCredentials.createInsecure();
 
     return new Promise((resolve, reject) => {
@@ -159,4 +157,4 @@ class GrpcServer {
   }
 }
 
-export { GrpcServer, buildFallbackConfig, buildFallbackInstanceConfig };
+export { GrpcServer, buildFallbackConfig };

package/src/index.js

@@ -52,7 +52,7 @@ class Underpost {
    * @type {String}
    * @memberof Underpost
    */
-  static version = 'v3.3.73';
+  static version = 'v3.3.76';
 
   /**
    * Required Node.js major version

package/src/projects/cyberia/atlas-sprite-sheet-generator.js

@@ -5,14 +5,28 @@
  * @namespace CyberiaAtlasSpriteSheetGenerator
  */
 
-import fs from 'fs-extra';
-import path from 'path';
-import sharp from 'sharp';
 import { Jimp, rgbaToInt } from 'jimp';
 import { loggerFactory } from '../../server/ops/logger.js';
+import { getKeyframeDirectionsByCode } from '../../client/components/cyberia/SharedDefaultsCyberia.js';
 
 const logger = loggerFactory(import.meta);
 
+/** Direction code of the still an item is previewed by: down idle. */
+export const IDLE_PREVIEW_DIRECTION_CODE = '08';
+
+/**
+ * Pixels per cell of the human-resolution atlas, when no factor is given.
+ * @memberof CyberiaAtlasSpriteSheetGenerator
+ */
+export const DEFAULT_ATLAS_UPSCALE_FACTOR = 20;
+
+/**
+ * Pixels per cell of the minified atlas. The client runtime downloads this one,
+ * so it stays at one pixel per cell.
+ * @memberof CyberiaAtlasSpriteSheetGenerator
+ */
+const MINIFY_CELL_PIXEL_DIM = 1;
+
 /**
  * @typedef {Object} AtlasFrame
  * @property {number} x - X position in atlas
@@ -38,7 +52,7 @@ export class AtlasSpriteSheetGenerator {
    * @returns {Promise<Jimp>} The generated image
    * @memberof CyberiaAtlasSpriteSheetGenerator
    */
-  static async frameMatrixToImage(frameMatrix, colors, cellPixelDim = 20) {
+  static async frameMatrixToImage(frameMatrix, colors, cellPixelDim = 1) {
     if (!frameMatrix || frameMatrix.length === 0 || frameMatrix[0].length === 0) {
       throw new Error('Invalid frame matrix');
     }
@@ -79,59 +93,47 @@ export class AtlasSpriteSheetGenerator {
    * @memberof CyberiaAtlasSpriteSheetGenerator
    */
   static calculateOptimalDimension(frameImages) {
-    if (!frameImages || frameImages.length === 0) {
-      logger.warn('No frames provided for dimension calculation, using default 2048');
-      return 2048;
-    }
-
-    // Get max frame dimensions with defensive checks
-    const widths = frameImages.map((f) => f.width).filter((w) => !isNaN(w) && w > 0);
-    const heights = frameImages.map((f) => f.height).filter((h) => !isNaN(h) && h > 0);
-
-    if (widths.length === 0 || heights.length === 0) {
-      logger.warn('Invalid frame dimensions found, using default 2048');
-      return 2048;
+    if (
+      !frameImages?.length ||
+      frameImages.some(
+        ({ width, height }) => !Number.isInteger(width) || !Number.isInteger(height) || width <= 0 || height <= 0,
+      )
+    ) {
+      throw new Error('Invalid frame dimensions');
     }
-
-    const maxFrameWidth = Math.max(...widths);
-    const maxFrameHeight = Math.max(...heights);
-
-    logger.info(`Frame dimensions: max ${maxFrameWidth}x${maxFrameHeight}, count: ${frameImages.length}`);
-
-    // Calculate grid layout (try to make it roughly square)
-    const frameCount = frameImages.length;
-    const cols = Math.ceil(Math.sqrt(frameCount));
-    const rows = Math.ceil(frameCount / cols);
-
-    // Calculate required dimensions
-    const requiredWidth = cols * maxFrameWidth;
-    const requiredHeight = rows * maxFrameHeight;
-    const requiredDim = Math.max(requiredWidth, requiredHeight);
-
-    logger.info(`Grid layout: ${cols}x${rows}, required: ${requiredWidth}x${requiredHeight}`);
-
-    // Round up to next power of 2
-    const optimalDim = AtlasSpriteSheetGenerator.nextPowerOf2(requiredDim);
-
-    // Ensure minimum 1024, maximum 8192
-    const finalDim = Math.max(1024, Math.min(8192, optimalDim));
-
-    logger.info(`Calculated optimal dimension: ${finalDim}x${finalDim}`);
-
-    return finalDim;
+    const cols = Math.ceil(Math.sqrt(frameImages.length));
+    const rows = Math.ceil(frameImages.length / cols);
+    return AtlasSpriteSheetGenerator.nextPowerOf2(
+      Math.max(
+        cols * Math.max(...frameImages.map((frame) => frame.width)),
+        rows * Math.max(...frameImages.map((frame) => frame.height)),
+      ),
+    );
   }
 
   /**
-   * Consolidates all frames from an ObjectLayerRenderFrames into a single atlas sprite sheet
+   * Consolidates all frames of an ObjectLayerRenderFrames into one atlas sprite sheet.
+   *
+   * One packing produces two renders of the same layout: `minifyBuffer` at one
+   * pixel per cell, which the client runtime downloads, and `buffer` at
+   * `upscaleFactor` pixels per cell for human viewing. `metadata` describes the
+   * minified render, so atlas metadata and the served blob always agree.
+   *
    * @static
    * @param {Object} objectLayerRenderFrames - The ObjectLayerRenderFrames document
    * @param {string} itemKey - The item key for the atlas
-   * @param {number} [cellPixelDim=20] - Pixel dimension per cell
+   * @param {number} [upscaleFactor=DEFAULT_ATLAS_UPSCALE_FACTOR] - Pixels per cell of the human-resolution render
    * @param {number} [maxAtlasDim=null] - Maximum atlas dimension (auto-calculated if null)
-   * @returns {Promise<{buffer: Buffer, metadata: Object}>} Atlas buffer and metadata
+   * @returns {Promise<{buffer: Buffer, minifyBuffer: Buffer, metadata: Object}>} Both renders and the shared metadata
    * @memberof CyberiaAtlasSpriteSheetGenerator
    */
-  static async generateAtlas(objectLayerRenderFrames, itemKey, cellPixelDim = 20, maxAtlasDim = null) {
+  static async generateAtlas(
+    objectLayerRenderFrames,
+    itemKey,
+    upscaleFactor = DEFAULT_ATLAS_UPSCALE_FACTOR,
+    maxAtlasDim = null,
+  ) {
+    if (!Number.isInteger(upscaleFactor) || upscaleFactor < 1) throw new Error('Invalid pixel scale');
     const { frames, colors } = objectLayerRenderFrames;
     const frameDuration = Number(objectLayerRenderFrames?.frame_duration);
 
@@ -157,7 +159,7 @@ export class AtlasSpriteSheetGenerator {
       'none_idle',
     ];
 
-    // Generate all frame images
+    // The packing works on the minified render; the upscaled render reuses its layout.
     const frameImages = [];
 
     for (const direction of directionOrder) {
@@ -167,10 +169,15 @@ export class AtlasSpriteSheetGenerator {
       for (let frameIndex = 0; frameIndex < directionFrames.length; frameIndex++) {
         const frameMatrix = directionFrames[frameIndex];
         try {
-          const frameImage = await AtlasSpriteSheetGenerator.frameMatrixToImage(frameMatrix, colors, cellPixelDim);
+          const frameImage = await AtlasSpriteSheetGenerator.frameMatrixToImage(
+            frameMatrix,
+            colors,
+            MINIFY_CELL_PIXEL_DIM,
+          );
 
           frameImages.push({
             image: frameImage,
+            frameMatrix,
             direction,
             frameIndex,
             width: frameImage.bitmap.width,
@@ -194,10 +201,8 @@ export class AtlasSpriteSheetGenerator {
       );
     }
 
-    // Validate maxAtlasDim
-    if (isNaN(maxAtlasDim) || maxAtlasDim <= 0) {
-      logger.error(`Invalid maxAtlasDim: ${maxAtlasDim}, using default 2048`);
-      maxAtlasDim = 2048;
+    if (!Number.isInteger(maxAtlasDim) || maxAtlasDim <= 0 || maxAtlasDim > 4096) {
+      throw new Error('Atlas dimension must be between 1 and 4096');
     }
 
     // Simple grid packing algorithm
@@ -215,43 +220,29 @@ export class AtlasSpriteSheetGenerator {
       );
     }
 
-    // Create atlas canvas
-    const atlasImage = new Jimp({ width: atlasWidth, height: atlasHeight, color: 0x00000000 });
+    const minifyImage = new Jimp({ width: atlasWidth, height: atlasHeight, color: 0x00000000 });
+    const upscaledImage = new Jimp({
+      width: atlasWidth * upscaleFactor,
+      height: atlasHeight * upscaleFactor,
+      color: 0x00000000,
+    });
 
-    // Build metadata structure first
     const frameMetadata = {};
 
-    // Composite frames onto atlas
-    let loggedCount = 0;
     for (const packedFrame of packedFrames) {
-      const { image, x, y, direction, frameIndex } = packedFrame;
-
-      // Log first few frames for debugging
-      if (loggedCount < 3) {
-        logger.info(
-          `Frame ${loggedCount + 1}: ${direction}[${frameIndex}] → (${x},${y}) ${image.bitmap.width}x${image.bitmap.height}`,
-        );
-        loggedCount++;
-      }
-
-      // Manually copy pixels to ensure correct positioning
-      for (let srcY = 0; srcY < image.bitmap.height; srcY++) {
-        for (let srcX = 0; srcX < image.bitmap.width; srcX++) {
-          const destX = x + srcX;
-          const destY = y + srcY;
+      const { image, frameMatrix, x, y, direction, frameIndex } = packedFrame;
 
-          // Skip if out of bounds
-          if (destX >= atlasWidth || destY >= atlasHeight) continue;
+      AtlasSpriteSheetGenerator.blitFrame(minifyImage, image, x, y);
 
-          // Get pixel color from source image
-          const color = image.getPixelColor(srcX, srcY);
-
-          // Set pixel in atlas at destination position
-          atlasImage.setPixelColor(color, destX, destY);
-        }
+      // The same cell grid at a larger scale, so the upscaled atlas is an exact
+      // multiple of the layout the metadata describes.
+      if (upscaleFactor > MINIFY_CELL_PIXEL_DIM) {
+        const upscaledFrame = await AtlasSpriteSheetGenerator.frameMatrixToImage(frameMatrix, colors, upscaleFactor);
+        AtlasSpriteSheetGenerator.blitFrame(upscaledImage, upscaledFrame, x * upscaleFactor, y * upscaleFactor);
+      } else {
+        AtlasSpriteSheetGenerator.blitFrame(upscaledImage, image, x, y);
       }
 
-      // Store metadata in correct order
       if (!frameMetadata[direction]) {
         frameMetadata[direction] = [];
       }
@@ -265,19 +256,80 @@ export class AtlasSpriteSheetGenerator {
       };
     }
 
-    // Convert to PNG buffer
-    const buffer = await atlasImage.getBuffer('image/png');
-
     const metadata = {
       itemKey,
       atlasWidth,
       atlasHeight,
-      cellPixelDim,
+      cellPixelDim: MINIFY_CELL_PIXEL_DIM,
+      upscaleFactor,
       frame_duration: Number.isFinite(frameDuration) ? frameDuration : 100,
       frames: frameMetadata,
     };
 
-    return { buffer, metadata };
+    return {
+      buffer: await upscaledImage.getBuffer('image/png'),
+      minifyBuffer: await minifyImage.getBuffer('image/png'),
+      metadata,
+    };
+  }
+
+  /**
+   * The frame an item is previewed by: the first frame of the first down-idle keyframe the
+   * atlas carries, or the first frame of any direction when it has none.
+   *
+   * @static
+   * @param {Object} metadata - Atlas metadata as {@link generateAtlas} returns it.
+   * @returns {{x:number,y:number,width:number,height:number}|null} Frame box in minified cells.
+   * @memberof CyberiaAtlasSpriteSheetGenerator
+   */
+  static idlePreviewFrame(metadata) {
+    const frames = metadata?.frames ?? {};
+    const preferred = getKeyframeDirectionsByCode(IDLE_PREVIEW_DIRECTION_CODE);
+    for (const direction of [...preferred, ...Object.keys(frames)]) {
+      const frame = frames[direction]?.[0];
+      if (frame) return frame;
+    }
+    return null;
+  }
+
+  /**
+   * Cuts the idle-preview still out of the human-resolution render, using the same layout
+   * `metadata.frames` describes for the minified one scaled by `metadata.upscaleFactor`.
+   *
+   * @static
+   * @param {Buffer} buffer - PNG bytes of the human-resolution atlas render.
+   * @param {Object} metadata - Atlas metadata as {@link generateAtlas} returns it.
+   * @returns {Promise<Buffer|null>} PNG bytes of the still, or null when the atlas has no frame.
+   * @memberof CyberiaAtlasSpriteSheetGenerator
+   */
+  static async idlePreviewFromAtlas(buffer, metadata) {
+    const frame = AtlasSpriteSheetGenerator.idlePreviewFrame(metadata);
+    if (!frame) return null;
+    const scale = Number(metadata.upscaleFactor) || 1;
+    const image = await Jimp.read(buffer);
+    image.crop({ x: frame.x * scale, y: frame.y * scale, w: frame.width * scale, h: frame.height * scale });
+    return await image.getBuffer('image/png');
+  }
+
+  /**
+   * Copies a frame image onto an atlas canvas at the given origin.
+   * @static
+   * @param {Jimp} atlasImage - Destination atlas canvas.
+   * @param {Jimp} frameImage - Source frame image.
+   * @param {number} originX - Destination X origin.
+   * @param {number} originY - Destination Y origin.
+   * @returns {void}
+   * @memberof CyberiaAtlasSpriteSheetGenerator
+   */
+  static blitFrame(atlasImage, frameImage, originX, originY) {
+    for (let srcY = 0; srcY < frameImage.bitmap.height; srcY++) {
+      for (let srcX = 0; srcX < frameImage.bitmap.width; srcX++) {
+        const destX = originX + srcX;
+        const destY = originY + srcY;
+        if (destX >= atlasImage.bitmap.width || destY >= atlasImage.bitmap.height) continue;
+        atlasImage.setPixelColor(frameImage.getPixelColor(srcX, srcY), destX, destY);
+      }
+    }
   }
 
   /**
@@ -302,7 +354,6 @@ export class AtlasSpriteSheetGenerator {
     let rowHeight = 0;
     let maxWidth = 0;
     let totalHeight = 0;
-    let exceedsCount = 0;
 
     for (const frame of sortedFrames) {
       // Check if frame fits in current row
@@ -313,9 +364,8 @@ export class AtlasSpriteSheetGenerator {
         rowHeight = 0;
       }
 
-      // Check if we exceed max height
-      if (currentY + frame.height > maxDim) {
-        exceedsCount++;
+      if (frame.width > maxDim || currentY + frame.height > maxDim) {
+        throw new Error(`Frames exceed atlas dimension ${maxDim}`);
       }
 
       packedFrames.push({
@@ -330,20 +380,8 @@ export class AtlasSpriteSheetGenerator {
       totalHeight = Math.max(totalHeight, currentY + frame.height);
     }
 
-    // Log once if frames exceeded dimensions
-    if (exceedsCount > 0) {
-      const recommendedSize = AtlasSpriteSheetGenerator.nextPowerOf2(Math.max(maxWidth, totalHeight));
-      logger.warn(
-        `${exceedsCount} frames exceed atlas dimension (${maxDim}x${maxDim}). ` +
-          `Actual required: ${maxWidth}x${totalHeight}. ` +
-          `Recommended: --to-atlas-sprite-sheet ${recommendedSize}`,
-      );
-    }
-
-    // Use maxDim as the atlas dimensions (already power-of-2 and optimal from auto-calculation)
-    // If all frames fit within a smaller power-of-2, use that instead
-    const atlasWidth = maxDim;
-    const atlasHeight = maxDim;
+    const atlasWidth = maxWidth;
+    const atlasHeight = totalHeight;
 
     return {
       packedFrames,
@@ -369,45 +407,4 @@ export class AtlasSpriteSheetGenerator {
     n |= n >> 16;
     return n + 1;
   }
-
-  /**
-   * Generates atlas and saves to file system
-   * @static
-   * @param {Object} objectLayerRenderFrames - The ObjectLayerRenderFrames document
-   * @param {string} itemKey - The item key for the atlas
-   * @param {string} outputPath - Output file path
-   * @param {number} [cellPixelDim=20] - Pixel dimension per cell
-   * @param {number} [maxAtlasDim=null] - Maximum atlas dimension (auto-calculated if null)
-   * @returns {Promise<{buffer: Buffer, metadata: Object, outputPath: string}>}
-   * @memberof CyberiaAtlasSpriteSheetGenerator
-   */
-  static async generateAtlasToFile(
-    objectLayerRenderFrames,
-    itemKey,
-    outputPath,
-    cellPixelDim = 20,
-    maxAtlasDim = null,
-  ) {
-    const { buffer, metadata } = await AtlasSpriteSheetGenerator.generateAtlas(
-      objectLayerRenderFrames,
-      itemKey,
-      cellPixelDim,
-      maxAtlasDim,
-    );
-
-    await fs.ensureDir(path.dirname(outputPath));
-    await fs.writeFile(outputPath, buffer);
-
-    logger.info(`Atlas sprite sheet generated: ${outputPath}`);
-
-    return { buffer, metadata, outputPath };
-  }
 }
-
-// Export convenience functions
-export const generateAtlas = AtlasSpriteSheetGenerator.generateAtlas;
-export const generateAtlasToFile = AtlasSpriteSheetGenerator.generateAtlasToFile;
-export const frameMatrixToImage = AtlasSpriteSheetGenerator.frameMatrixToImage;
-export const packFramesGrid = AtlasSpriteSheetGenerator.packFramesGrid;
-export const nextPowerOf2 = AtlasSpriteSheetGenerator.nextPowerOf2;
-export const calculateOptimalDimension = AtlasSpriteSheetGenerator.calculateOptimalDimension;