Improve cacheability with content-hashed public assets and a cacheable app shell (#3494)

## Description:

This reworks asset delivery and cacheability across the app and moves
non-bundled public resources onto immutable, content-hashed URLs.

Vite bundle outputs continue to live under `/assets/**` and remain
content-hashed by Vite. Public resources that were previously fetched
from stable paths in `resources/` now go through a custom hashed
namespace under `/_assets/**`, backed by a generated asset manifest that
is available to the server, browser, and worker runtime.

In parallel, the root app shell is now cacheable shared HTML instead of
request-time `no-store` HTML. Dynamic and live routes remain explicitly
uncached.

## Why
- Improve browser and Cloudflare cacheability for static assets.
- Remove query-string and release-version cache busting for
runtime-fetched assets.
- Allow unchanged public assets to keep the same URL across releases.
- Reduce avoidable work on `/` by serving a shared app shell instead of
rendering HTML on every request.
- Make cache behavior explicit instead of relying on mixed framework
defaults and file-extension heuristics.

## What Changed

### 1. Content-hashed public asset pipeline
- Added a build-time public asset manifest and hashing pipeline for
non-Vite resources.
- Production now emits hashed public assets under `/_assets/**`.
- Added runtime manifest loading for Node so server-rendered paths
resolve against built hashed files instead of rebuilding from source at
runtime.
- Emitted the runtime asset manifest as an ESM module for server
consumption.

Result:
- `/assets/**` = Vite-managed hashed bundle outputs
- `/_assets/**` = custom content-hashed public resources

### 2. Runtime asset URL migration
- Added a shared `assetUrl(...)` resolution path.
- Migrated runtime references away from query-string versioning and
stable source paths.
- Updated browser, worker, and server-side rendering paths to resolve
through the asset manifest.
- Moved map manifests, map binaries, thumbnails, sprites, sounds, fonts,
flags, icons, screenshots, and other runtime-fetched resources onto
hashed URLs.

### 3. Map and preview fixes
- Fixed directory and per-file map asset resolution so map manifest and
binary fetches resolve to the correct hashed URLs.
- Updated preview metadata and map thumbnail paths to use the hashed
asset namespace.
- Fixed runtime manifest loading in prod after deployment.

### 4. Explicit cache policies
- Added explicit immutable cache headers for:
  - `/assets/**`
  - `/_assets/**`
  - worker-prefixed equivalents under `/wN/...`
- Added explicit `no-store` headers for live and dynamic APIs.
- Removed the old `/api/env` bootstrap request and baked `gameEnv` into
the HTML bootstrap instead.

### 5. Cacheable root app shell
- Refactored the root HTML path to serve a shared app shell with:
- `Cache-Control: public, max-age=0, s-maxage=300,
stale-while-revalidate=86400`
- `/` and the SPA fallback now serve shared cacheable HTML instead of
request-time `no-store` rendering.
- `/game/:id` remains dynamic and `no-store`, but now reuses the shared
shell before injecting preview tags.

### 6. Matchmaking instance handling
- Because the app shell is now cacheable, `INSTANCE_ID` was removed from
shared HTML.
- Added `/api/instance` as a temporary `no-store` runtime lookup used
only by matchmaking.
- This preserves correctness with the current random-per-boot
`INSTANCE_ID` model while keeping `/` cacheable, but it is not the
intended long-term design.

## Behavior Changes

### Asset URL contract
Production URLs for non-Vite public resources now change from stable
paths such as:
- `/maps/...`
- `/images/...`
- `/manifest.json`

to content-hashed paths under:
- `/_assets/...`

Examples:
- `/_assets/maps/<map>/manifest.<hash>.json`
- `/_assets/images/Favicon.<hash>.svg`

### Bootstrap/config
- `/api/env` is removed.
- `gameEnv` is now bootstrapped from HTML.

### HTML caching
- `/` and the SPA fallback are now cacheable shared HTML.
- `/game/:id` remains dynamic.

## Cache Matrix After This Branch
- `/_assets/**`: `public, max-age=31536000, immutable`
- `/assets/**`: `public, max-age=31536000, immutable`
- live `/api/**`: explicit `no-store`
- `/api/health`: explicit `no-store`
- `/api/instance`: explicit `no-store`
- `/game/:id`: explicit `no-store`
- `/` and SPA fallback: `public, max-age=0, s-maxage=300,
stale-while-revalidate=86400`

## Notes / Tradeoffs
- `/api/instance` is a temporary compromise. It exists because
`INSTANCE_ID` is currently random per boot, which is not safe to embed
into cacheable shared HTML.
- The current matchmaking flow still asks the client to provide
`instance_id` during `matchmaking/join`. That is functional, but it is
the wrong ownership boundary: instance selection should be handled by
the matchmaking service, not by the browser.
- The cleaner end-state would be:
- make `matchmaking/join` stop requiring `instance_id` from the client,
and let the matchmaking service select a healthy instance from worker
check-ins
- This branch makes the origin behavior edge-cache-friendly, but
Cloudflare still needs matching cache rules if HTML itself should be
cached at the edge.

## Validation
Verified during development with:
- `npx tsc --noEmit`
- `node node_modules\\vite\\bin\\vite.js build`
- `node node_modules\\vitest\\vitest.mjs run
tests/server/RenderHtml.test.ts tests/server/NoStoreHeaders.test.ts
tests/server/StaticAssetCache.test.ts
tests/core/configuration/ConfigLoader.test.ts`

Additional targeted tests added:
- `tests/AssetUrls.test.ts`
- `tests/core/game/FetchGameMapLoader.test.ts`
- `tests/core/configuration/ConfigLoader.test.ts`
- `tests/server/NoStoreHeaders.test.ts`
- `tests/server/StaticAssetCache.test.ts`
- `tests/server/RenderHtml.test.ts`

## Known Existing Warnings
The production build still reports pre-existing warnings that are not
addressed by this branch:
- inconsistent JSON import attributes for `resources/countries.json`
- inconsistent JSON import attributes for `resources/QuickChat.json`
- large chunk warnings from Vite

## Rollout Notes
- Cache rules should treat `/_assets/**` and `/assets/**` as immutable.
- Cloudflare will still classify HTML as dynamic after deploy unless
matching edge cache rules are configured for it.

## Follow-ups
- Remove `/api/instance` by changing `matchmaking/join` so the server
selects the target instance, or by making `INSTANCE_ID` deploy-stable if
the current contract must remain.


## Please complete the following:

- [ ] I have added screenshots for all UI updates
- [ ] I process any text displayed to the user through translateText()
and I've added it to the en.json file
- [ ] I have added relevant tests to the test directory
- [ ] I confirm I have thoroughly tested these changes and take full
responsibility for any bugs introduced

## Please put your Discord username so you can be contacted if a bug or
regression is found:

DISCORD_USERNAME

src/client/HelpModal.ts

@@ -1,6 +1,7 @@
 import { html } from "lit";
 import { customElement, query, state } from "lit/decorators.js";
 import { translateText, TUTORIAL_VIDEO_URL } from "../client/Utils";
+import { assetUrl } from "../core/AssetUrls";
 import { BaseModal } from "./components/BaseModal";
 import "./components/Difficulties";
 import { modalHeader } from "./components/ui/ModalHeader";
@@ -527,7 +528,7 @@ export class HelpModal extends BaseModal {
                     >${translateText("help_modal.ui_leaderboard")}</span
                   >
                   <img
-                    src="/images/helpModal/leaderboard2.webp"
+                    src=${assetUrl("images/helpModal/leaderboard2.webp")}
                     alt="Leaderboard"
                     class="rounded-lg shadow-lg border border-white/20 max-w-[200px]"
                     loading="lazy"
@@ -550,7 +551,7 @@ export class HelpModal extends BaseModal {
                     >${translateText("help_modal.ui_control")}</span
                   >
                   <img
-                    src="/images/helpModal/controlPanel.webp"
+                    src=${assetUrl("images/helpModal/controlPanel.webp")}
                     alt="Control Panel"
                     class="rounded-lg shadow-lg border border-white/20 max-w-[200px]"
                     loading="lazy"
@@ -578,13 +579,13 @@ export class HelpModal extends BaseModal {
                   >
                   <div class="flex flex-col gap-2">
                     <img
-                      src="/images/helpModal/eventsPanel.webp"
+                      src=${assetUrl("images/helpModal/eventsPanel.webp")}
                       alt="Events"
                       class="rounded-lg shadow-lg border border-white/20 max-w-[200px]"
                       loading="lazy"
                     />
                     <img
-                      src="/images/helpModal/eventsPanelAttack.webp"
+                      src=${assetUrl("images/helpModal/eventsPanelAttack.webp")}
                       alt="Events Attack"
                       class="rounded-lg shadow-lg border border-white/20 max-w-[200px]"
                       loading="lazy"
@@ -613,7 +614,7 @@ export class HelpModal extends BaseModal {
                     >${translateText("help_modal.ui_options")}</span
                   >
                   <img
-                    src="/images/helpModal/options2.webp"
+                    src=${assetUrl("images/helpModal/options2.webp")}
                     alt="Options"
                     class="rounded-lg shadow-lg border border-white/20 max-w-[200px]"
                     loading="lazy"
@@ -643,7 +644,7 @@ export class HelpModal extends BaseModal {
                     >${translateText("help_modal.ui_playeroverlay")}</span
                   >
                   <img
-                    src="/images/helpModal/playerInfoOverlay.webp"
+                    src=${assetUrl("images/helpModal/playerInfoOverlay.webp")}
                     alt="Player Info"
                     class="rounded-lg shadow-lg border border-white/20 max-w-[200px]"
                     loading="lazy"
@@ -692,13 +693,13 @@ export class HelpModal extends BaseModal {
             >
               <div class="flex flex-col gap-4 shrink-0">
                 <img
-                  src="/images/helpModal/radialMenu2.webp"
+                  src=${assetUrl("images/helpModal/radialMenu2.webp")}
                   alt="Radial Menu"
                   class="rounded-lg shadow-lg border border-white/20 max-w-[200px]"
                   loading="lazy"
                 />
                 <img
-                  src="/images/helpModal/radialMenuAlly.webp"
+                  src=${assetUrl("images/helpModal/radialMenuAlly.webp")}
                   alt="Radial Menu Ally"
                   class="rounded-lg shadow-lg border border-white/20 max-w-[200px]"
                   loading="lazy"
@@ -711,42 +712,42 @@ export class HelpModal extends BaseModal {
                 <ul class="space-y-3">
                   <li class="flex items-center gap-3">
                     <img
-                      src="/images/BuildIconWhite.svg"
+                      src=${assetUrl("images/BuildIconWhite.svg")}
                       class="w-8 h-8 scale-75 origin-left"
                     />
                     <span>${translateText("help_modal.radial_build")}</span>
                   </li>
                   <li class="flex items-center gap-3">
                     <img
-                      src="/images/InfoIcon.svg"
+                      src=${assetUrl("images/InfoIcon.svg")}
                       class="w-8 h-8 scale-75 origin-left"
                     />
                     <span>${translateText("help_modal.radial_info")}</span>
                   </li>
                   <li class="flex items-center gap-3">
                     <img
-                      src="/images/BoatIconWhite.svg"
+                      src=${assetUrl("images/BoatIconWhite.svg")}
                       class="w-8 h-8 scale-75 origin-left"
                     />
                     <span>${translateText("help_modal.radial_boat")}</span>
                   </li>
                   <li class="flex items-center gap-3">
                     <img
-                      src="/images/AllianceIconWhite.svg"
+                      src=${assetUrl("images/AllianceIconWhite.svg")}
                       class="w-8 h-8 scale-75 origin-left"
                     />
                     <span>${translateText("help_modal.info_alliance")}</span>
                   </li>
                   <li class="flex items-center gap-3">
                     <img
-                      src="/images/TraitorIconWhite.svg"
+                      src=${assetUrl("images/TraitorIconWhite.svg")}
                       class="w-8 h-8 scale-75 origin-left"
                     />
                     <span>${translateText("help_modal.ally_betray")}</span>
                   </li>
                   <li class="flex items-center gap-3">
                     <img
-                      src="/images/DonateTroopIconWhite.svg"
+                      src=${assetUrl("images/DonateTroopIconWhite.svg")}
                       class="w-8 h-8 scale-75 origin-left"
                     />
                     <span
@@ -755,7 +756,7 @@ export class HelpModal extends BaseModal {
                   </li>
                   <li class="flex items-center gap-3">
                     <img
-                      src="/images/DonateGoldIconWhite.svg"
+                      src=${assetUrl("images/DonateGoldIconWhite.svg")}
                       class="w-8 h-8 scale-75 origin-left"
                     />
                     <span
@@ -808,7 +809,7 @@ export class HelpModal extends BaseModal {
                     >${translateText("help_modal.info_enemy_panel")}</span
                   >
                   <img
-                    src="/images/helpModal/infoMenu2.webp"
+                    src=${assetUrl("images/helpModal/infoMenu2.webp")}
                     alt="Enemy Info"
                     class="rounded-lg shadow-lg border border-white/20 max-w-[240px]"
                     loading="lazy"
@@ -821,35 +822,35 @@ export class HelpModal extends BaseModal {
                   <ul class="space-y-3">
                     <li class="flex items-center gap-3">
                       <img
-                        src="/images/ChatIconWhite.svg"
+                        src=${assetUrl("images/ChatIconWhite.svg")}
                         class="w-8 h-8 scale-75 origin-left"
                       />
                       <span>${translateText("help_modal.info_chat")}</span>
                     </li>
                     <li class="flex items-center gap-3">
                       <img
-                        src="/images/TargetIconWhite.svg"
+                        src=${assetUrl("images/TargetIconWhite.svg")}
                         class="w-8 h-8 scale-75 origin-left"
                       />
                       <span>${translateText("help_modal.info_target")}</span>
                     </li>
                     <li class="flex items-center gap-3">
                       <img
-                        src="/images/AllianceIconWhite.svg"
+                        src=${assetUrl("images/AllianceIconWhite.svg")}
                         class="w-8 h-8 scale-75 origin-left"
                       />
                       <span>${translateText("help_modal.info_alliance")}</span>
                     </li>
                     <li class="flex items-center gap-3">
                       <img
-                        src="/images/EmojiIconWhite.svg"
+                        src=${assetUrl("images/EmojiIconWhite.svg")}
                         class="w-8 h-8 scale-75 origin-left"
                       />
                       <span>${translateText("help_modal.info_emoji")}</span>
                     </li>
                     <li class="flex items-center gap-3">
                       <img
-                        src="/images/StopIconWhite.png"
+                        src=${assetUrl("images/StopIconWhite.png")}
                         class="w-8 h-8 scale-75 origin-left"
                         loading="lazy"
                       />
@@ -869,7 +870,7 @@ export class HelpModal extends BaseModal {
                     >${translateText("help_modal.info_ally_panel")}</span
                   >
                   <img
-                    src="/images/helpModal/infoMenu2Ally.webp"
+                    src=${assetUrl("images/helpModal/infoMenu2Ally.webp")}
                     alt="Ally Info"
                     class="rounded-lg shadow-lg border border-white/20 max-w-[240px]"
                     loading="lazy"
@@ -882,21 +883,21 @@ export class HelpModal extends BaseModal {
                   <ul class="space-y-3">
                     <li class="flex items-center gap-3">
                       <img
-                        src="/images/TraitorIconWhite.svg"
+                        src=${assetUrl("images/TraitorIconWhite.svg")}
                         class="w-8 h-8 scale-75 origin-left"
                       />
                       <span>${translateText("help_modal.ally_betray")}</span>
                     </li>
                     <li class="flex items-center gap-3">
                       <img
-                        src="/images/DonateTroopIconWhite.svg"
+                        src=${assetUrl("images/DonateTroopIconWhite.svg")}
                         class="w-8 h-8 scale-75 origin-left"
                       />
                       <span>${translateText("help_modal.ally_donate")}</span>
                     </li>
                     <li class="flex items-center gap-3">
                       <img
-                        src="/images/DonateGoldIconWhite.svg"
+                        src=${assetUrl("images/DonateGoldIconWhite.svg")}
                         class="w-8 h-8 scale-75 origin-left"
                       />
                       <span
@@ -971,7 +972,7 @@ export class HelpModal extends BaseModal {
                     </td>
                     <td class="py-3 border-b border-white/5">
                       <img
-                        src="/images/CityIconWhite.svg"
+                        src=${assetUrl("images/CityIconWhite.svg")}
                         class="w-8 h-8 scale-75 origin-left"
                       />
                     </td>
@@ -987,7 +988,7 @@ export class HelpModal extends BaseModal {
                     </td>
                     <td class="py-3 border-b border-white/5">
                       <img
-                        src="/images/ShieldIconWhite.svg"
+                        src=${assetUrl("images/ShieldIconWhite.svg")}
                         class="w-8 h-8 scale-75 origin-left"
                       />
                     </td>
@@ -1003,7 +1004,7 @@ export class HelpModal extends BaseModal {
                     </td>
                     <td class="py-3 border-b border-white/5">
                       <img
-                        src="/images/PortIcon.svg"
+                        src=${assetUrl("images/PortIcon.svg")}
                         class="w-8 h-8 scale-75 origin-left"
                       />
                     </td>
@@ -1019,7 +1020,7 @@ export class HelpModal extends BaseModal {
                     </td>
                     <td class="py-3 border-b border-white/5">
                       <img
-                        src="/images/FactoryIconWhite.svg"
+                        src=${assetUrl("images/FactoryIconWhite.svg")}
                         class="w-8 h-8 scale-75 origin-left"
                       />
                     </td>
@@ -1035,7 +1036,7 @@ export class HelpModal extends BaseModal {
                     </td>
                     <td class="py-3 border-b border-white/5">
                       <img
-                        src="/images/BattleshipIconWhite.svg"
+                        src=${assetUrl("images/BattleshipIconWhite.svg")}
                         class="w-8 h-8 scale-75 origin-left"
                       />
                     </td>
@@ -1051,7 +1052,7 @@ export class HelpModal extends BaseModal {
                     </td>
                     <td class="py-3 border-b border-white/5">
                       <img
-                        src="/images/MissileSiloIconWhite.svg"
+                        src=${assetUrl("images/MissileSiloIconWhite.svg")}
                         class="w-8 h-8 scale-75 origin-left"
                       />
                     </td>
@@ -1067,7 +1068,7 @@ export class HelpModal extends BaseModal {
                     </td>
                     <td class="py-3 border-b border-white/5">
                       <img
-                        src="/images/SamLauncherIconWhite.svg"
+                        src=${assetUrl("images/SamLauncherIconWhite.svg")}
                         class="w-8 h-8 scale-75 origin-left"
                       />
                     </td>
@@ -1083,7 +1084,7 @@ export class HelpModal extends BaseModal {
                     </td>
                     <td class="py-3 border-b border-white/5">
                       <img
-                        src="/images/NukeIconWhite.svg"
+                        src=${assetUrl("images/NukeIconWhite.svg")}
                         class="w-8 h-8 scale-75 origin-left"
                       />
                     </td>
@@ -1099,7 +1100,7 @@ export class HelpModal extends BaseModal {
                     </td>
                     <td class="py-3 border-b border-white/5">
                       <img
-                        src="/images/MushroomCloudIconWhite.svg"
+                        src=${assetUrl("images/MushroomCloudIconWhite.svg")}
                         class="w-8 h-8 scale-75 origin-left"
                       />
                     </td>
@@ -1115,7 +1116,7 @@ export class HelpModal extends BaseModal {
                     </td>
                     <td class="py-3 border-b border-white/5">
                       <img
-                        src="/images/MIRVIcon.svg"
+                        src=${assetUrl("images/MIRVIcon.svg")}
                         class="w-8 h-8 scale-75 origin-left"
                       />
                     </td>
@@ -1169,7 +1170,7 @@ export class HelpModal extends BaseModal {
                 class="bg-black/20 rounded-xl border border-white/10 p-4 flex flex-col items-center gap-3 hover:bg-white/5 transition-colors"
               >
                 <img
-                  src="/images/helpModal/crown.webp"
+                  src=${assetUrl("images/helpModal/crown.webp")}
                   alt="Rank 1"
                   class="rounded shadow-lg border border-white/10 h-24 w-auto object-contain"
                   loading="lazy"
@@ -1186,7 +1187,7 @@ export class HelpModal extends BaseModal {
                 class="bg-black/20 rounded-xl border border-white/10 p-4 flex flex-col items-center gap-3 hover:bg-white/5 transition-colors"
               >
                 <img
-                  src="/images/helpModal/traitor2.webp"
+                  src=${assetUrl("images/helpModal/traitor2.webp")}
                   alt="Traitor"
                   class="rounded shadow-lg border border-white/10 h-24 w-auto object-contain"
                   loading="lazy"
@@ -1203,7 +1204,7 @@ export class HelpModal extends BaseModal {
                 class="bg-black/20 rounded-xl border border-white/10 p-4 flex flex-col items-center gap-3 hover:bg-white/5 transition-colors"
               >
                 <img
-                  src="/images/helpModal/ally2.webp"
+                  src=${assetUrl("images/helpModal/ally2.webp")}
                   alt="Ally"
                   class="rounded shadow-lg border border-white/10 h-24 w-auto object-contain"
                   loading="lazy"
@@ -1220,7 +1221,7 @@ export class HelpModal extends BaseModal {
                 class="bg-black/20 rounded-xl border border-white/10 p-4 flex flex-col items-center gap-3 hover:bg-white/5 transition-colors"
               >
                 <img
-                  src="/images/helpModal/embargo.webp"
+                  src=${assetUrl("images/helpModal/embargo.webp")}
                   alt="Embargo"
                   class="rounded shadow-lg border border-white/10 h-24 w-auto object-contain"
                   loading="lazy"
@@ -1237,7 +1238,7 @@ export class HelpModal extends BaseModal {
                 class="bg-black/20 rounded-xl border border-white/10 p-4 flex flex-col items-center gap-3 hover:bg-white/5 transition-colors"
               >
                 <img
-                  src="/images/helpModal/allianceRequest.webp"
+                  src=${assetUrl("images/helpModal/allianceRequest.webp")}
                   alt="Request"
                   class="rounded shadow-lg border border-white/10 h-24 w-auto object-contain"
                   loading="lazy"