// ── Public · World ────────────────────────────────────────────────────────
//
// Mounted at `/api/v1/public/world` by `index.js`. One express Router, built
// from CORE's express (`core.express`) — never from a `require('express')` of
// your own, which would not resolve from here anyway (MODULE_API.md §7.2).
//
// **The tier's gate is already on.** This router sits inside core's public tier,
// which is behind nothing by design — the public API is public. Per-route
// middleware goes on top, and `siteMode` below is the one worth understanding:
// it is what makes a page respect the operator's maintenance switch. Core applies
// it to its own content routes (`/posts`, `/wiki`) and deliberately does not
// apply it to its status endpoints, because status is exactly what an operator
// wants visible *during* maintenance. Which of those two your route is depends on
// what it serves, and it is your decision to make.
//
// ── About the `#swagger` comments ─────────────────────────────────────────
//
// They are not documentation *of* the code, they are the source the OpenAPI
// fragment is generated from — `npm run swagger` parses this file (§2.8). Two
// rules that cost this project real time:
//
//   • swagger-autogen reads these as JavaScript literals it evaluates, so a
//     QUOTE CHARACTER inside a single-quoted description ends the string early.
//     Both `'` and `"` — use a typographic apostrophe (’) in prose, and rewrite
//     a quoted phrase without the quotes. A backtick is fine: Markdown spans like
//     `online: false` below survive verbatim, and the fragment shows them.
//
//     **The failure is silent, and this is the part worth remembering.** It is
//     not always a parse error you get told about. A `"` in the middle of a
//     description truncates the value at that character — `'A "quoted" status'`
//     becomes `A "` — while swagger-autogen prints `Success` in green and the
//     error capture below sees nothing to capture, because nothing threw. The
//     only signal is `npm run check:swagger` reporting the fragment stale, whose
//     message will blame your routes. When it does and your routes did not
//     change, look for a quote in an annotation before you look anywhere else.
//     (Measured, not inferred: docs/modules/kit-acceptance.md, F5.)
//   • A `\'` escape is valid JavaScript and wrong here: the annotation is never
//     evaluated as JS by the reader, so Swagger UI renders the backslash.

const core = require('../../core')

const express = core.express
const world = require('./world.controller')
const { siteMode } = core.middleware

const worldRouter = express.Router()

worldRouter.get(
  '/status',
  // #swagger.tags = ['Public · Example Game']
  // #swagger.summary = 'The game world’s current status'
  // #swagger.description = 'What the game server last reported: whether it is up, how many players are on, and when that was. Answers with `online: false` and `stale: true` rather than failing when the game or its sidecar is unreachable — the site’s availability does not depend on the game’s.'
  /* #swagger.responses[200] = { description: 'The world’s status', content: { "application/json": { schema: { $ref: "#/components/schemas/ExamplegameWorldStatus" } } } } */
  siteMode,
  world.getStatus,
)

module.exports = worldRouter