Module-Rust/client/src/entry.jsx

// ── The client entry point ────────────────────────────────────────────────
//
// Core serves `dist/entry.js` from this module's directory and injects it into
// its own HTML as a same-origin `<script type="module" src>` before `</body>`.
// This file registers what the module has; core renders it. Normative:
// MODULE_API.md §3.3.
//
// **Registration is synchronous and happens at evaluation time.** Module scripts
// are deferred, so this runs after core's bundle — which is where `window.__rg`
// is published — and before core's first render. There is no subscription and no
// late registration: a module that registered asynchronously would register after
// the route table had been read, and the symptom is a page that redirects home
// with nothing logged anywhere.
//
// So everything below is a plain top-level call and every page is a STATIC
// import. Lazy-loading the routes is the natural instinct for a chunk that grows,
// and it is the one thing this seam cannot have.

import { registry, coreApiVersion } from './core.js'

import Servers from './routes/public/Servers.jsx'
import ServerDetail from './routes/public/ServerDetail.jsx'
import Clan from './routes/public/Clan.jsx'
import Account from './routes/player/Account.jsx'
import Permissions from './routes/admin/Permissions.jsx'
import ModConfig from './routes/admin/ModConfig.jsx'
import Visibility from './routes/admin/Visibility.jsx'
import ServerSettings from './routes/admin/ServerSettings.jsx'
import UserRustSections from './routes/admin/UserRustSections.jsx'
import FooterStatus from './components/FooterStatus.jsx'
import { IconEye, IconKey, IconLink, IconServer, IconSliders } from './icons.jsx'

// The module id, exactly as `module.json` spells it. Core keys the registry by it
// and prefixes every route path with it.
const ID = 'rust'

// ── Routes ────────────────────────────────────────────────────────────────
//
// Paths are relative to the module's namespace and core prefixes them. Whatever
// is written here, a public route lands at `/<id>/<path>`, an admin route at
// `/admin/<id>/<path>` and a player route at `/player/<id>/<path>`. A module
// cannot write the segment its routes hang under, which is the point: two modules
// installed side by side cannot collide, and an operator can see from a URL which
// module served it.
//
// So the list below is at `/rust` and the detail page at `/rust/servers/:id`.
//
// **Note what is NOT here: an auth wrapper.** `gate: { roles: [...] }` is
// available and core applies it as its own `RoleGate`; supplying your own is not
// possible, because the sidebar and the route table have to agree about who may
// see what, and they only do if one thing decides.
//
// R8's landing page is the server list, and `/rust/servers/:id` hangs beneath it.
//
// **The list is registered with an EMPTY path**, which core renders as the
// module's namespace root: `/rust`. The prefixing code strips the separator it
// would otherwise leave behind (`registry.js`: `${id}/${path}` with trailing
// slashes trimmed), so a module can own its own root without being able to spell
// its way out of it. Phase 1 served this page at `/rust/servers` and left `/rust`
// to core's CMS catch-all; the org lead settled it at `/rust` in phase 4, so the
// address an operator links to is the module's name.
//
// React Router ranks a static segment above a dynamic one, so `/rust` wins
// against core's `/:slug` CMS route without depending on registration order.
//
// The player route is registered with an empty path for the same reason the
// public list is: `/player/rust` is the whole of what this module asks a player
// to do, and a landing page above one page is a page nobody wants. Core applies
// its own portal chrome and its own auth gate to the tier, so the component
// renders no layout and re-implements no check.
//
// **The admin route arrives in phase 7 and is this module's first.** Everything
// before it was configured through the API — the server rows still are — because
// nothing until now had to be AUTHORED. A permission model is different in kind:
// it is a thing an operator composes and keeps looking at, and there is no
// version of "grant somebody VIP" that belongs in a terminal.
//
// It is registered with an empty path, so it lands at `/admin/rust`, and core
// applies the admin tier's own gate. The routes underneath it are stricter than
// that gate (`requireRole('admin')` on every one), which is a server-side answer
// rather than a client one: a moderator who reached this page would see it fail
// honestly rather than be quietly shown a page that cannot save.
registry.registerRoutes(ID, {
  public: [
    { path: '', element: <Servers /> },
    { path: 'servers/:id', element: <ServerDetail /> },
    // Phase 9 (D56). Not nested under its server: core links here from Team
    // notification email through `pageUrlTemplate`, which substitutes
    // `{externalId}` and nothing else — and the server is inside that id.
    { path: 'clans/:externalId', element: <Clan /> },
  ],
  player: [{ path: '', element: <Account /> }],
  admin: [
    { path: '', element: <Permissions /> },
    // Phase 7b (R18). A second admin page rather than a tab on the first: the
    // permission mirror decides who may do what inside the game, and this edits
    // the game host's own files. They are neighbours, not halves of one screen,
    // and the nav says so with two rows.
    //
    // A static segment under the module's namespace, so it lands at
    // `/admin/rust/config` and core's admin gate applies to it exactly as it
    // does to the page above.
    { path: 'config', element: <ModConfig /> },
    // Who may see who is online — a third neighbour. The org lead's rule is that
    // nothing names who is online by default; this is where an operator widens
    // it on purpose, fleet-wide or per server.
    { path: 'visibility', element: <Visibility /> },
    // The servers themselves (phase 16, D133): the page that was missing. Until
    // it, a server row was written only through the API, and D130's wipe
    // schedule needed somewhere to be typed.
    { path: 'servers', element: <ServerSettings /> },
  ],
})

// ── Nav ───────────────────────────────────────────────────────────────────
//
// A registered row is an ORDINARY row from here on. It interleaves into core's
// own navigation, and an operator can reorder it, relabel it or hide it from the
// admin nav editor exactly as they can core's — because the interleave happens
// before the override merge, and the override layer is keyed by `to`.
//
// Three fields worth knowing before you need them:
//
//   • `order` places the row among core's, which are keyed by their index. A row
//     with NO order appends after them, rather than defaulting to 0 — otherwise
//     "I didn't ask for a position" would mean "put me first".
//   • `group` (admin sidebar) names an existing core group; an unknown name
//     appends a new group at the end rather than dropping the row.
//   • `icon` is a component, and core supplies no fallback. Public header rows
//     carry no icons, so there is none here — but an admin or player row without
//     one is the only row in its sidebar with no glyph, which reads as breakage.
registry.registerNav(ID, {
  area: 'public',
  items: [{ label: 'Servers', to: '/rust' }],
})

// The player portal's row. It carries an `icon` because core draws one on every
// portal row — a row without one is the only text in a column of glyphs, and
// core used to render `<n.icon />` unguarded, which blanked the whole portal.
//
// No `order`: an unordered row appends after core's own rather than claiming a
// position it was not given. Account, appeals and notifications are what a player
// came to the portal for; linking a game account is what they do once.
registry.registerNav(ID, {
  area: 'player',
  items: [{ label: 'Rust', to: '/player/rust', icon: IconLink }],
})

// The admin sidebar's row. `group` names an existing core group — an unknown name
// appends a new group at the end rather than dropping the row, which is the
// failure mode to avoid here: a row nobody can find is a feature nobody has.
//
// It carries an icon for the same reason the player row does: core draws one on
// every sidebar row, and the one without is the only text in a column of glyphs.
registry.registerNav(ID, {
  area: 'admin',
  items: [
    { label: 'Rust permissions', to: '/admin/rust', icon: IconKey },
    { label: 'Rust mod config', to: '/admin/rust/config', icon: IconSliders },
    { label: 'Rust visibility', to: '/admin/rust/visibility', icon: IconEye },
    { label: 'Rust servers', to: '/admin/rust/servers', icon: IconServer },
  ],
})

// ── Extension slots ───────────────────────────────────────────────────────
//
// Core declares a slot, only core may declare one, and at most one module may
// fill it (§3.7). `site.footer.status` is the status-ish spot in core's footer
// info row: core owns the position and passes `linkStyle`; the label, the
// destination, the data and whether anything renders at all are the module's.
//
// It is a CLIENT slot and cannot be named in `module.json`'s `extensions` —
// that array is validated against the SERVER registry, and naming a client slot
// there fails the load outright with `unknown extension slot`. Phase 1 found
// that the hard way; the two halves of R13 are declared in different places on
// purpose.
registry.registerExtension(ID, 'site.footer.status', FooterStatus)

// R13's other slot, and the one that IS named in `module.json` — because it has
// a server half too (`server/router/admin/usersRust.router.js`). The two halves
// carry one name on purpose: a module that adds routes under
// `/api/v1/admin/users/:id` is the module with something to show on that page.
//
// Core passes `userId` and nothing else, so the component builds its own client
// for the routes the server half registered. It renders NOTHING for a user with
// no linked Steam account, which is most of them.
registry.registerExtension(ID, 'admin.users.detail', UserRustSections)

// ── Inverted slots: core's Team contributions on OUR clan page ─────────────
//
// §3.7a. A clan is a Team (R5), and core renders no Team page because it does
// not own the word "clan". So the page is `routes/public/Clan.jsx` and core
// contributes the three things only it can render — into places this module
// names, in this module's vocabulary. Core offers a CONTRIBUTION; it never names
// a slot, which is what lets a second game use the same contract as module-uo.
//
// One slot per PLACE (D56): a slot holds one component, and a collapsed slot
// would hand core the decision about where each part sits on a page it does not
// own. Asking for a contribution core does not offer throws here, at
// registration — a typo fails loudly rather than rendering nothing for ever.
registry.declareModuleSlot(ID, 'rust.clan.header', { core: 'team.notify' })
registry.declareModuleSlot(ID, 'rust.clan.detail', { core: 'team.activity' })
registry.declareModuleSlot(ID, 'rust.clan.forum', { core: 'team.forum' })

// `module.json`'s `coreApi` range was checked by the loader before this file was
// ever served, so there is nothing to re-check here. Log it anyway: a mismatch
// between the core that validated the manifest and the core that published this
// global is otherwise invisible from the browser, which is where the client half
// actually fails.
console.info(`[${ID}] registered against core API ${coreApiVersion}`)