@underpostnet/cyberia 3.2.80

package/scripts/test-monitor.sh

@@ -0,0 +1,248 @@
+#!/usr/bin/env bash
+#
+# test-monitor.sh — end-to-end deploy + two-phase monitor smoke test.
+#
+# Two deployment shapes are supported:
+#
+#   --mode runtime   `underpost start` deploy (e.g. dd-test). Monitored with the
+#                    HTTP gate: /_internal/ready probes + port-forward status.
+#   --mode instance  Custom instances from conf.instances.json (e.g. cyberia
+#                    mmo-server / mmo-client). Monitored with the kubernetes gate
+#                    (TCP readinessProbe) + exec status transport.
+#
+# Every variable in the DEFAULTS block below is overridable with a flag of the
+# same name (--env, --deploy-id, …). Run with --help for the full list.
+#
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ENGINE_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
+cd "$ENGINE_DIR"
+
+# ─────────────────────────── DEFAULTS (all overridable) ───────────────────────────
+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.2.80                    # 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
+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)
+HTTPS_PORT=443                                # local https port for instance TLS exposure
+
+USE_CERT=false                                # runtime: pass --cert to the proxy step
+USE_PULL_BUNDLE=false                         # runtime: include --pull-bundle in the start cmd
+USE_TLS=false                                 # generate self-signed certs + expose over HTTPS
+USE_TEST_REPO=false                           # runtime: publish src to engine-test-<id> + pod clones it (--private-test-repo)
+DO_BUILD_TEMPLATE=true                        # run `node bin/build.template --update-private`
+DO_CLUSTER_MANIFESTS=true                     # run `node bin run build-cluster-deployment-manifests`
+DO_EXPOSE=true                                # expose locally after deploy + monitor
+
+usage() {
+  cat <<'EOF'
+Usage: scripts/test-monitor.sh [flags]
+
+Modes:
+  --mode <runtime|instance>     Deployment shape to test (default: runtime)
+
+Common (every default is overridable):
+  --env <development|production>
+  --deploy-id <id>
+  --instance-ids <csv>          instance mode only; default = all ids in conf.instances.json
+  --image <image>               runtime mode only
+  --versions <csv>              e.g. green or blue,green
+  --replicas <n>
+  --namespace <ns>
+  --cluster <kind|kubeadm|k3s|none>
+  --timeout-response <dur>      e.g. 300000ms
+  --template-repo <owner/repo>  runtime mode link repo
+  --envoy-namespace <ns>        instance TLS exposure ingress namespace
+  --envoy-service <name>        instance TLS exposure ingress service
+  --https-port <port>           local https port for instance TLS exposure
+
+Toggles (use --x / --no-x):
+  --tls | --no-tls              self-signed certs + HTTPS exposure (default: off)
+  --cert | --no-cert            runtime proxy --cert (default: off)
+  --pull-bundle | --no-pull-bundle   runtime start --pull-bundle (default: off)
+  --test-repo | --no-test-repo  runtime: publish src to engine-test-<id> and have the
+                                pod clone it via --private-test-repo (default: off)
+  --expose | --no-expose        local exposure after monitor (default: on)
+  --build-template | --no-build-template       sync private template (default: on)
+  --cluster-manifests | --no-cluster-manifests  rebuild cluster manifests (default: on)
+
+  -h, --help
+
+Examples:
+  # Runtime deploy (default), no TLS
+  scripts/test-monitor.sh
+
+  # Runtime deploy over HTTPS
+  scripts/test-monitor.sh --tls
+
+  # Runtime deploy from a work-in-progress test source repo (engine-test-<id>)
+  scripts/test-monitor.sh --test-repo
+
+  # Cyberia instances (both), dev on kind, no TLS
+  scripts/test-monitor.sh --mode instance --deploy-id dd-cyberia --cluster kind
+
+  # Only the mmo-server instance, production, over HTTPS
+  scripts/test-monitor.sh --mode instance --deploy-id dd-cyberia \
+    --instance-ids mmo-server --env production --cluster kubeadm --tls
+EOF
+}
+
+# ─────────────────────────── flag parsing ───────────────────────────
+# Supports `--key value` and `--key=value` for value flags, plus --x/--no-x toggles.
+needval() { [[ $# -ge 2 ]] || { echo "Missing value for $1" >&2; exit 1; }; }
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --mode) needval "$@"; MODE="$2"; shift 2;;            --mode=*) MODE="${1#*=}"; shift;;
+    --env) needval "$@"; ENV="$2"; shift 2;;              --env=*) ENV="${1#*=}"; shift;;
+    --deploy-id) needval "$@"; DEPLOY_ID="$2"; shift 2;;  --deploy-id=*) DEPLOY_ID="${1#*=}"; shift;;
+    --instance-ids) needval "$@"; INSTANCE_IDS="$2"; shift 2;; --instance-ids=*) INSTANCE_IDS="${1#*=}"; shift;;
+    --image) needval "$@"; IMAGE="$2"; shift 2;;          --image=*) IMAGE="${1#*=}"; shift;;
+    --versions) needval "$@"; VERSIONS="$2"; shift 2;;    --versions=*) VERSIONS="${1#*=}"; shift;;
+    --replicas) needval "$@"; REPLICAS="$2"; shift 2;;    --replicas=*) REPLICAS="${1#*=}"; shift;;
+    --namespace) needval "$@"; NAMESPACE="$2"; shift 2;;  --namespace=*) NAMESPACE="${1#*=}"; shift;;
+    --cluster) needval "$@"; CLUSTER="$2"; shift 2;;      --cluster=*) CLUSTER="${1#*=}"; shift;;
+    --timeout-response) needval "$@"; TIMEOUT_RESPONSE="$2"; shift 2;; --timeout-response=*) TIMEOUT_RESPONSE="${1#*=}"; shift;;
+    --template-repo) needval "$@"; TEMPLATE_REPO="$2"; shift 2;; --template-repo=*) TEMPLATE_REPO="${1#*=}"; shift;;
+    --envoy-namespace) needval "$@"; ENVOY_NAMESPACE="$2"; shift 2;; --envoy-namespace=*) ENVOY_NAMESPACE="${1#*=}"; shift;;
+    --envoy-service) needval "$@"; ENVOY_SERVICE="$2"; shift 2;; --envoy-service=*) ENVOY_SERVICE="${1#*=}"; shift;;
+    --https-port) needval "$@"; HTTPS_PORT="$2"; shift 2;; --https-port=*) HTTPS_PORT="${1#*=}"; shift;;
+    --tls) USE_TLS=true; shift;;                          --no-tls) USE_TLS=false; shift;;
+    --cert) USE_CERT=true; shift;;                        --no-cert) USE_CERT=false; shift;;
+    --pull-bundle) USE_PULL_BUNDLE=true; shift;;          --no-pull-bundle) USE_PULL_BUNDLE=false; shift;;
+    --test-repo) USE_TEST_REPO=true; shift;;              --no-test-repo) USE_TEST_REPO=false; shift;;
+    --expose) DO_EXPOSE=true; shift;;                     --no-expose) DO_EXPOSE=false; shift;;
+    --build-template) DO_BUILD_TEMPLATE=true; shift;;     --no-build-template) DO_BUILD_TEMPLATE=false; shift;;
+    --cluster-manifests) DO_CLUSTER_MANIFESTS=true; shift;; --no-cluster-manifests) DO_CLUSTER_MANIFESTS=false; shift;;
+    -h|--help) usage; exit 0;;
+    *) echo "Unknown flag: $1" >&2; usage; exit 1;;
+  esac
+done
+
+# ─────────────────────────── derived flags ───────────────────────────
+CLUSTER_FLAG=""
+case "$CLUSTER" in
+  kind)    CLUSTER_FLAG="--kind";;
+  kubeadm) CLUSTER_FLAG="--kubeadm";;
+  k3s)     CLUSTER_FLAG="--k3s";;
+  ""|none) CLUSTER_FLAG="";;
+  *) echo "Unknown --cluster: $CLUSTER (expected kind|kubeadm|k3s|none)" >&2; exit 1;;
+esac
+DEV_FLAG=""; [ "$ENV" = development ] && DEV_FLAG="--dev"
+INSTANCES_CONF="./engine-private/conf/${DEPLOY_ID}/conf.instances.json"
+SERVER_CONF="./engine-private/conf/${DEPLOY_ID}/conf.server.json"
+
+echo "[test-monitor] mode=$MODE env=$ENV deploy=$DEPLOY_ID cluster=${CLUSTER:-none} tls=$USE_TLS test-repo=$USE_TEST_REPO expose=$DO_EXPOSE"
+
+# ─────────────────────────── shared helpers ───────────────────────────
+
+# setup_tls_secrets <host> [<host> …] — regenerate self-signed certs and create
+# the per-host k8s TLS secret the HTTPProxy references (name == host).
+setup_tls_secrets() {
+  local ssl_base="${ENGINE_DIR}/engine-private/ssl"
+  for host in "$@"; do
+    local cert_dir="${ssl_base}/${host}"
+    mkdir -p "$cert_dir"
+    bash "${SCRIPT_DIR}/ssl.sh" "$cert_dir" "$host"
+    local name_safe="${host//[^a-zA-Z0-9_.-]/_}"
+    kubectl delete secret "$host" -n "$NAMESPACE" --ignore-not-found
+    kubectl create secret tls "$host" \
+      --cert="${cert_dir}/${name_safe}.pem" \
+      --key="${cert_dir}/${name_safe}-key.pem" \
+      -n "$NAMESPACE"
+  done
+}
+
+# hosts_from <conf.json> — unique hosts declared in a conf.server.json or conf.instances.json.
+hosts_from() {
+  node -e "
+    const c = require('$1');
+    const hosts = Array.isArray(c) ? c.map(i => i.host) : Object.keys(c);
+    console.log([...new Set(hosts)].join(' '));
+  "
+}
+
+# ─────────────────────────── pre-steps ───────────────────────────
+[ "$DO_CLUSTER_MANIFESTS" = true ] && node bin run build-cluster-deployment-manifests
+[ "$DO_BUILD_TEMPLATE" = true ] && node bin/build.template --update-private
+
+# ─────────────────────────── 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 deploy_cmd proxy_flag="" expose_flags="" start_flags=""
+
+  # Publish the local engine src to underpostnet/engine-test-<id> so the pod
+  # (started with --private-test-repo) clones this work-in-progress source.
+  [ "$USE_TEST_REPO" = true ] && node bin/build "$DEPLOY_ID" --update-private
+
+  [ "$USE_PULL_BUNDLE" = true ] && start_flags="${start_flags} --pull-bundle"
+  [ "$USE_TEST_REPO" = true ] && start_flags="${start_flags} --private-test-repo"
+  deploy_cmd="${link_cmd},underpost start --build --run${start_flags} ${DEPLOY_ID} ${ENV}"
+
+  [ "$USE_CERT" = true ] && proxy_flag="--cert"
+  [ "$USE_TLS" = true ] && proxy_flag="--self-signed"
+
+  node bin deploy "$DEPLOY_ID" "$ENV" $CLUSTER_FLAG --sync --build-manifest \
+    --image "$IMAGE" --timeout-response "$TIMEOUT_RESPONSE" --versions "$VERSIONS" --replicas "$REPLICAS" --cmd "$deploy_cmd"
+  node bin deploy "$DEPLOY_ID" "$ENV" $CLUSTER_FLAG --disable-update-proxy $proxy_flag
+  node bin monitor "$DEPLOY_ID" "$ENV" --ready-deployment --promote \
+    --timeout-response "$TIMEOUT_RESPONSE" --versions "$VERSIONS" --replicas "$REPLICAS"
+
+  node bin run etc-hosts --deploy-id "$DEPLOY_ID"
+
+  if [ "$USE_TLS" = true ]; then
+    setup_tls_secrets $(hosts_from "$SERVER_CONF")
+    expose_flags="--tls"
+  fi
+  [ "$DO_EXPOSE" = true ] && node bin deploy --expose --local-proxy "$DEPLOY_ID" "$ENV" $expose_flags
+}
+
+# ─────────────────────────── instance mode ───────────────────────────
+run_instance_mode() {
+  [ -f "$INSTANCES_CONF" ] || { echo "Missing $INSTANCES_CONF" >&2; exit 1; }
+  if [ -z "$INSTANCE_IDS" ]; then
+    INSTANCE_IDS=$(node -e "console.log(require('$INSTANCES_CONF').map(i=>i.id).join(','))")
+  fi
+  local tls_flag=""; [ "$USE_TLS" = true ] && tls_flag="--tls --test"
+
+  # `run instance` builds/pulls the image, applies the manifest, monitors with the
+  # kubernetes gate (TCP readinessProbe) + exec status, then promotes traffic.
+  IFS=',' read -ra ids <<< "$INSTANCE_IDS"
+  for id in "${ids[@]}"; do
+    [ -n "$id" ] || continue
+    echo "[test-monitor] deploying instance ${DEPLOY_ID},${id}"
+    node bin run instance "${DEPLOY_ID},${id},${REPLICAS}" \
+      $DEV_FLAG $CLUSTER_FLAG --namespace "$NAMESPACE" --etc-hosts $tls_flag \
+      ${IMAGE:+--image-name "$IMAGE"}
+  done
+
+  [ "$DO_EXPOSE" = true ] || return 0
+  if [ "$USE_TLS" = true ]; then
+    # Instances are routed by the Contour ingress; port-forward Envoy so the
+    # HTTPProxy host routing (server/client.cyberiaonline.com) works locally.
+    echo "[test-monitor] exposing HTTPS via ${ENVOY_NAMESPACE}/${ENVOY_SERVICE} on :${HTTPS_PORT}"
+    sudo kubectl port-forward -n "$ENVOY_NAMESPACE" "svc/${ENVOY_SERVICE}" "${HTTPS_PORT}:443" &
+  else
+    # Plain HTTP: port-forward each instance service port directly.
+    for id in "${ids[@]}"; do
+      [ -n "$id" ] || continue
+      node bin deploy --expose "${DEPLOY_ID}-${id}" "$ENV" --namespace "$NAMESPACE" || true
+    done
+  fi
+}
+
+case "$MODE" in
+  runtime)  run_runtime_mode;;
+  instance) run_instance_mode;;
+  *) echo "Unknown --mode: $MODE (expected runtime|instance)" >&2; exit 1;;
+esac
+
+echo "[test-monitor] done (mode=$MODE tls=$USE_TLS)"

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

@@ -0,0 +1,30 @@
+import {
+  buildCrudController,
+  controllerHandler,
+  sendBlob,
+  serviceHandler,
+  setCrossOriginHeaders,
+} from '../../server/middlewares.js';
+import { AtlasSpriteSheetService } from './atlas-sprite-sheet.service.js';
+
+const AtlasSpriteSheetController = buildCrudController(AtlasSpriteSheetService, {
+  get: serviceHandler(AtlasSpriteSheetService.get, { crossOrigin: true, pagination: true }),
+  getMetadata: serviceHandler(AtlasSpriteSheetService.getMetadata, {
+    crossOrigin: true,
+    pagination: true,
+    errorStatus: 404,
+  }),
+  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 },
+  ),
+});
+
+export { AtlasSpriteSheetController };

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

@@ -0,0 +1,155 @@
+/**
+ * Mongoose model for AtlasSpriteSheet API, defining schema for consolidated sprite sheet atlases.
+ * @module src/api/atlas-sprite-sheet/atlas-sprite-sheet.model.js
+ * @namespace CyberiaAtlasSpriteSheetModel
+ */
+import { Schema, model, Types } from 'mongoose';
+/**
+ * @typedef {Object} FrameMetadata
+ * @property {number} x - X position in the atlas
+ * @property {number} y - Y position in the atlas
+ * @property {number} width - Frame width
+ * @property {number} height - Frame height
+ * @property {number} frameIndex - Frame index in animation sequence
+ * @memberof CyberiaAtlasSpriteSheetModel
+ */
+const FrameMetadataSchema = new Schema(
+  {
+    x: { type: Number, required: true, min: 0 },
+    y: { type: Number, required: true, min: 0 },
+    width: { type: Number, required: true, min: 1 },
+    height: { type: Number, required: true, min: 1 },
+    frameIndex: { type: Number, required: true, min: 0 },
+  },
+  { _id: false },
+);
+/**
+ * @typedef {Object} DirectionFrames
+ * @property {FrameMetadata[]} up_idle - Up idle animation frames
+ * @property {FrameMetadata[]} down_idle - Down idle animation frames
+ * @property {FrameMetadata[]} right_idle - Right idle animation frames
+ * @property {FrameMetadata[]} left_idle - Left idle animation frames
+ * @property {FrameMetadata[]} up_right_idle - Up-right idle animation frames
+ * @property {FrameMetadata[]} down_right_idle - Down-right idle animation frames
+ * @property {FrameMetadata[]} up_left_idle - Up-left idle animation frames
+ * @property {FrameMetadata[]} down_left_idle - Down-left idle animation frames
+ * @property {FrameMetadata[]} default_idle - Default idle animation frames
+ * @property {FrameMetadata[]} up_walking - Up walking animation frames
+ * @property {FrameMetadata[]} down_walking - Down walking animation frames
+ * @property {FrameMetadata[]} right_walking - Right walking animation frames
+ * @property {FrameMetadata[]} left_walking - Left walking animation frames
+ * @property {FrameMetadata[]} up_right_walking - Up-right walking frames
+ * @property {FrameMetadata[]} down_right_walking - Down-right walking frames
+ * @property {FrameMetadata[]} up_left_walking - Up-left walking frames
+ * @property {FrameMetadata[]} down_left_walking - Down-left walking frames
+ * @property {FrameMetadata[]} none_idle - None state animation frames
+ * @memberof CyberiaAtlasSpriteSheetModel
+ */
+const DirectionFramesSchema = new Schema(
+  {
+    up_idle: { type: [FrameMetadataSchema], default: [] },
+    down_idle: { type: [FrameMetadataSchema], default: [] },
+    right_idle: { type: [FrameMetadataSchema], default: [] },
+    left_idle: { type: [FrameMetadataSchema], default: [] },
+    up_right_idle: { type: [FrameMetadataSchema], default: [] },
+    down_right_idle: { type: [FrameMetadataSchema], default: [] },
+    up_left_idle: { type: [FrameMetadataSchema], default: [] },
+    down_left_idle: { type: [FrameMetadataSchema], default: [] },
+    default_idle: { type: [FrameMetadataSchema], default: [] },
+    up_walking: { type: [FrameMetadataSchema], default: [] },
+    down_walking: { type: [FrameMetadataSchema], default: [] },
+    right_walking: { type: [FrameMetadataSchema], default: [] },
+    left_walking: { type: [FrameMetadataSchema], default: [] },
+    up_right_walking: { type: [FrameMetadataSchema], default: [] },
+    down_right_walking: { type: [FrameMetadataSchema], default: [] },
+    up_left_walking: { type: [FrameMetadataSchema], default: [] },
+    down_left_walking: { type: [FrameMetadataSchema], default: [] },
+    none_idle: { type: [FrameMetadataSchema], default: [] },
+  },
+  { _id: false },
+);
+/**
+ * @typedef {Object} AtlasSpriteSheet
+ * @property {Types.ObjectId} fileId - Reference to File document (consolidated PNG)
+ * @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.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
+ * @property {Date} updatedAt - When the document was last updated
+ * @memberof CyberiaAtlasSpriteSheetModel
+ */
+const AtlasSpriteSheetSchema = new Schema(
+  {
+    fileId: {
+      type: Schema.Types.ObjectId,
+      ref: 'File',
+      required: true,
+    },
+    cid: {
+      type: String,
+      default: '',
+      trim: true,
+    },
+    metadata: {
+      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 },
+      frame_duration: { type: Number, min: 0, default: 100 },
+      frames: { type: DirectionFramesSchema, required: true },
+    },
+  },
+  {
+    timestamps: true,
+    toJSON: { virtuals: true },
+    toObject: { virtuals: true },
+  },
+);
+// Indexes for efficient querying
+AtlasSpriteSheetSchema.index({ 'metadata.itemKey': 1 }, { unique: true });
+AtlasSpriteSheetSchema.index({ fileId: 1 });
+// Pre-save validation
+AtlasSpriteSheetSchema.pre('save', function () {
+  if (!this.fileId || !this.metadata) {
+    throw new Error('AtlasSpriteSheet missing required fields: fileId or metadata');
+  }
+});
+const AtlasSpriteSheetModel = model('AtlasSpriteSheet', AtlasSpriteSheetSchema);
+const ProviderSchema = AtlasSpriteSheetSchema;
+class AtlasSpriteSheetDto {
+  static select = {
+    get: () => {
+      return {
+        _id: 1,
+        fileId: 1,
+        cid: 1,
+        metadata: 1,
+        createdAt: 1,
+        updatedAt: 1,
+      };
+    },
+    // Returns all fields the client needs per itemKey:
+    // layout dims + frames for rendering, no fileId.
+    // Client flow: GET /metadata/:itemKey → cache → GET /blob/:itemKey → cache PNG.
+    getMetadataOnly: () => {
+      return {
+        _id: 1,
+        cid: 1,
+        'metadata.itemKey': 1,
+        'metadata.atlasWidth': 1,
+        'metadata.atlasHeight': 1,
+        'metadata.cellPixelDim': 1,
+        'metadata.frame_duration': 1,
+        'metadata.frames': 1,
+        createdAt: 1,
+        updatedAt: 1,
+      };
+    },
+  };
+}
+export { AtlasSpriteSheetSchema, AtlasSpriteSheetModel, ProviderSchema, AtlasSpriteSheetDto };

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

@@ -0,0 +1,39 @@
+import express from 'express';
+import { registerCrudRoutes } from '../../server/middlewares.js';
+import { moderatorGuard } from '../../server/auth.js';
+import { AtlasSpriteSheetController } from './atlas-sprite-sheet.controller.js';
+
+class AtlasSpriteSheetRouter {
+  /**
+   * @param {import('../types.js').RouterOptions} options
+   * @returns {import('express').Router}
+   */
+  static router(options) {
+    const router = express.Router();
+    router.post(
+      `/generate/:id`,
+      options.authMiddleware,
+      moderatorGuard,
+      async (req, res) => await AtlasSpriteSheetController.generate(req, res, options),
+    );
+    router.delete(
+      `/object-layer/:id`,
+      options.authMiddleware,
+      moderatorGuard,
+      async (req, res) => await AtlasSpriteSheetController.deleteByObjectLayerId(req, res, options),
+    );
+    router.get(`/blob/:itemKey`, async (req, res) => await AtlasSpriteSheetController.blob(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(
+      `/metadata/:itemKey`,
+      async (req, res) => await AtlasSpriteSheetController.getMetadata(req, res, options),
+    );
+    router.get(`/metadata`, async (req, res) => await AtlasSpriteSheetController.getMetadata(req, res, options));
+    return registerCrudRoutes(router, AtlasSpriteSheetController, options);
+  }
+}
+
+const ApiRouter = (options) => AtlasSpriteSheetRouter.router(options);
+
+export { ApiRouter, AtlasSpriteSheetRouter };