cyberia 3.2.9 → 3.2.12

package/src/client/public/cyberia-docs/CYBERIA-CLIENT.md

@@ -1,269 +1,252 @@
-# Cyberia Client
+<p align="center">
+  <img src="https://www.cyberiaonline.com/assets/splash/apple-touch-icon-precomposed.png" alt="CYBERIA online"/>
+</p>
 
-**Path:** `cyberia-client/` | **Language:** C (C11/GNU11) → WebAssembly via Emscripten
+<div align="center">
 
----
+<h1>cyberia client</h1>
+
+</div>
+
+**Path:** `cyberia-client/` · **Language:** C11/GNU11 → WebAssembly (Emscripten) · **Role:** presentation runtime for Cyberia
 
-## Overview
+`cyberia-client` is the rendering and interactive runtime for the Cyberia MMO extension on Underpost Platform. It captures input, predicts the local player, reconciles against authoritative snapshots, interpolates remote entities, and renders the world. It owns the render policy locally.
 
-`cyberia-client` is the real-time game client for Cyberia Online. It is written in C, compiled to WebAssembly via Emscripten, and rendered in a `<canvas>` element inside a browser. It uses **Raylib** for rendering (OpenGL ES2 under WASM) and connects to the Go game server via a persistent binary WebSocket.
+It is **not** a world-simulation authority. The authoritative simulation runs on `cyberia-server`. Persistent content and asset metadata come from `engine-cyberia` via REST.
 
 ---
 
-## Architecture
+## Operating model
 
+Three independent processes, non-overlapping roles. The ecosystem is playable only when all three are running and healthy at the same time.
+
+```text
+engine-cyberia          cyberia-server          cyberia-client
+content authority       simulation authority    presentation runtime
+  ^ REST                  | WebSocket binary
+  | atlases, asset        | snapshots  (server -> client)
+  | metadata, optional    | input cmds (client -> server)
+  | client hints          v
+  `---------------- Browser tab: prediction, reconciliation, interpolation, render
 ```
-┌────────────────────────────────────────────────────────────┐
-│  Browser                                                   │
-│  ┌──────────────────────────────────────────────────────┐  │
-│  │  index.html + shell.html                            │  │
-│  │  JS glue (Emscripten + services.js + interact_overlay.js + notify_badge.js)  │
-│  │                                                      │  │
-│  │  ┌────────────────────────────────────────────────┐ │  │
-│  │  │  index.wasm (main.c → game loop)               │ │  │
-│  │  │                                                │ │  │
-│  │  │  Raylib (OpenGL ES2)  ←  game_render.c         │ │  │
-│  │  │  Input system         ←  input.c               │ │  │
-│  │  │  AOI decoder          ←  binary_aoi_decoder.c  │ │  │
-│  │  │  ObjectLayer cache    ←  object_layer.c        │ │  │
-│  │  │  Texture manager      ←  texture_manager.c     │ │  │
-│  │  │  Game state           ←  game_state.c          │ │  │
-│  │  │  Network I/O          ←  network.c             │ │  │
-│  │  │  UI components        ←  modal.c, inventory_*.c│ │  │
-│  │  └────────────────────────────────────────────────┘ │  │
-│  └──────────────────────────────────────────────────────┘  │
-│       │ WebSocket binary                ↑ HTTP JSON         │
-└───────┼─────────────────────────────────┼──────────────────┘
-        │                                 │
-        ▼                                 ▼
-  Go Game Server :8081              Engine REST API :4005
-  (AOI binary protocol)             (atlas, file/blob, object-layer)
-```
+
+- Each service owns its own monitor and reconnector.
+- The client reconnects to `cyberia-server` over WebSocket and fetches content from `engine-cyberia` over REST.
+- If any of the three services is unhealthy, the game moves to standby until all three recover.
+
+The client speaks two transports:
+
+- **WebSocket binary** to `cyberia-server` for snapshots and input commands
+- **REST** to `engine-cyberia` for atlas frames, asset blobs, and optional client-hints overrides
+
+Asset distribution flows through Underpost Platform's static and PWA pipeline.
 
 ---
 
-## Source Files
-
-| File                                                      | Responsibility                                           |
-| --------------------------------------------------------- | -------------------------------------------------------- |
-| `main.c`                                                  | Entry point, Raylib init, main game loop, event dispatch |
-| `client.c / client.h`                                     | Client session state (player UUID, position, coins)      |
-| `game_state.c / game_state.h`                             | World state: entity registry, map grid, frame tick       |
-| `game_render.c / game_render.h`                           | Top-level render pipeline (map tiles → entities → UI)    |
-| `entity_render.c / entity_render.h`                       | Per-entity composited layer stack rendering              |
-| `binary_aoi_decoder.c / binary_aoi_decoder.h`             | Binary AOI message parser (0x01–0x05 messages)           |
-| `message_parser.c / message_parser.h`                     | JSON message parser for `init_data` (0x02)               |
-| `network.c / network.h`                                   | WebSocket connect, send, receive wrappers                |
-| `object_layer.c / object_layer.h`                         | ObjectLayer metadata struct + LRU cache                  |
-| `object_layers_management.c / object_layers_management.h` | ObjectLayer fetch pipeline (API → cache → render)        |
-| `texture_manager.c / texture_manager.h`                   | Atlas texture LRU cache keyed by IPFS CID                |
-| `layer_z_order.c / layer_z_order.h`                       | Z-order comparator for entity layer stack rendering      |
-| `serial.c / serial.h`                                     | IDBFS-based persistent local storage                     |
-| `input.c / input.h`                                       | Mouse/touch event → game action translation              |
-| `tap_effect.c / tap_effect.h`                             | Visual tap ripple animation                              |
-| `floating_combat_text.c / floating_combat_text.h`         | FCT pop-up renderer (damage, regen, coin, item)          |
-| `interaction_bubble.c / interaction_bubble.h`             | NPC interaction indicator bubble above entity            |
-| `entity_overhead_ui.c / entity_overhead_ui.h`             | Name plates, HP bars above entities                      |
-| `nameplate.c / nameplate.h`                               | Entity nameplate rendering                               |
-| `inventory_bar.c / inventory_bar.h`                       | Equipped items bar (bottom of screen)                    |
-| `inventory_modal.c / inventory_modal.h`                   | Full inventory grid modal                                |
-| `modal.c / modal.h`                                       | Base modal container (backdrop, open/close animation)    |
-| `modal_dialogue.c / modal_dialogue.h`                     | Dialogue modal — renders NPC conversation + choices      |
-| `modal_player.c / modal_player.h`                         | Player profile modal (stats, wallet, equipment)          |
-| `dialogue_data.c / dialogue_data.h`                       | Dialogue tree data structure                             |
-| `ol_as_animated_ico.c / ol_as_animated_ico.h`             | Render ObjectLayer as animated icon (inventory cells)    |
-| `ol_stack_ico.c / ol_stack_ico.h`                         | Render ObjectLayer stack as composite icon               |
-| `ui_icon.c / ui_icon.h`                                   | Generic icon primitives                                  |
-| `dev_ui.c / dev_ui.h`                                     | Development overlay (coords, FPS, entity count)          |
-| `helper.h`                                                | Common macros and utility definitions                    |
-| `config.h`                                                | Compile-time configuration constants                     |
-| `shell.html`                                              | Emscripten HTML shell template                           |
-| `js/services.js`                                          | JS↔WASM bridge: fetch atlas, file blob, object-layer     |
-| `js/interact_overlay.js`                                  | JS overlay for tap-to-interact element                   |
-| `js/notify_badge.js`                                      | Browser notification badge helper                        |
+## Render loop
+
+The render loop runs at vsync. Tick simulation is decoupled from render frames via a fixed-timestep accumulator. Step ordering inside one render frame:
+
+1. **Optional client hints poll** — advance the asynchronous hints fetch state machine.
+2. **Input capture** — drain raw OS events.
+3. **Input dispatch** — UI hit-test → build typed input command (`kind`, `clientTick`, `sequence`, payload) → apply to prediction → send on the wire.
+4. **Reconciliation** — apply latest snapshot's `lastAcked`: drop acknowledged input commands from the replay buffer; rewind predicted self to authoritative position; replay unacked input commands.
+5. **Fixed-timestep prediction** — while accumulator ≥ `tickDuration`, advance prediction one tick.
+6. **Interpolation** — compute remote-entity view positions at `renderTick = serverTickEstimate − INTERP_TICKS`.
+7. **Render** — read view models; never mutate world state.
+
+Render frame rate is independent of simulation tick rate. The fixed-timestep accumulator ensures the predicted simulation advances at the authoritative `tickRate` regardless of FPS.
 
 ---
 
-## Rendering Pipeline
+## Module map
 
-Each frame:
+Directional dependency: from outermost (UI / render) inward toward `domain/`. Nothing in `domain/` imports outward.
 
 ```
-BeginDrawing()
-  └─ game_render_frame()
-       ├─ RenderMapLayer(ground tiles)        ← atlas-clipped tile sprites
-       ├─ RenderMapLayer(object tiles)        ← decorative overlay tiles
-       ├─ for each entity in z-sorted list:
-       │    entity_render_entity()
-       │      ├─ for each ObjectLayer in entity stack (bottom → top z-order):
-       │      │    texture_manager_get_texture(layer.cid)
-       │      │    DrawTextureRec(atlas, frame_rect, position)
-       │      ├─ entity_overhead_ui (nameplate + HP bar)
-       │      └─ interaction_bubble (if NPC with action)
-       ├─ floating_combat_text_tick()         ← animated pop-ups
-       ├─ tap_effect_tick()                   ← tap ripple animations
-       ├─ inventory_bar_render()              ← equipped items (bottom HUD)
-       └─ dev_ui_render()                     ← debug overlay (if ENABLE_DEV_UI)
-EndDrawing()
+src/
+  domain/
+    tick.h                          tick rate constants, monotonic types
+    presentation_runtime.{c,h}      sole owner of presentation: async fetch of
+                                    /api/cyberia-client-hints/:CYBERIA_CLIENT_HINTS_CODE,
+                                    palette/status-icon/camera accessors, tiny
+                                    inline bootstrap fallback
+  input/
+    input_command.{c,h}             typed InputCommand factory; sequence allocation
+  prediction/
+    prediction.{c,h}                predicted self position; replay buffer; reconcile
+  interpolation/
+    interpolation.{c,h}             remote entity view positions at renderTick
+  network/
+    session.{c,h}                   last server tick, last acked sequence, tick estimate
+    client.{c,h}                    WebSocket lifecycle + binary I/O
+    socket.{c,h}                    Emscripten WebSocket bridge
+  ui/                               modals, HUD, inventory bar, FCT, nameplates
+  game_state.{c,h}                  world state mirror (gameplay subset only)
+  binary_aoi_decoder.{c,h}          server snapshot parser
+  game_render.{c,h}, render.{c,h}   render pipeline
+  main.c                            entry point + render loop
+  js/services.{js,c,h}              REST fetch bridge (atlas, ui-icons, client-hints)
 ```
 
-**Atlas clipping:** Every sprite is a rectangular clip from a texture atlas. The atlas CID (IPFS) is fetched from the Engine API at `/api/atlas-sprite-sheet/{cid}`. The engine returns frame metadata JSON; the client clips `DrawTextureRec(atlas, {x,y,w,h}, screenPos)`.
+| Owner                         | Owns                                                                                                                                                              | Reads                                          | Writes                                                                                          |
+| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `domain/presentation_runtime` | the entire presentation surface (palette, entity colour keys, status icons, camera, cell, interpolation). Inline bootstrap fallback while the fetch is in flight. | JSON response from `/api/cyberia-client-hints` | own table + one-shot hydration of `g_game_state.cell_size`, `.interpolation_ms`, `.camera.zoom` |
+| `input/input_command`         | typed InputCommand factory                                                                                                                                        | session for tick + sequence                    | —                                                                                               |
+| `prediction/`                 | predicted self position, input replay buffer                                                                                                                      | snapshot self + session ack                    | predicted self                                                                                  |
+| `interpolation/`              | remote entity `interp_pos`                                                                                                                                        | snapshot history                               | remote `interp_pos` only                                                                        |
+| `network/session`             | last server tick, last acked sequence                                                                                                                             | snapshot header                                | session singletons                                                                              |
+| `binary_aoi_decoder`          | wire parser                                                                                                                                                       | binary frames                                  | `game_state` + session + prediction (via callback)                                              |
+| `game_state`                  | gameplay world mirror                                                                                                                                             | —                                              | —                                                                                               |
+| `render/`, `ui/`              | rendering                                                                                                                                                         | view models                                    | screen                                                                                          |
+
+`game_state` holds only the gameplay subset of world state (entities, positions, life, AOI, equipment, frozen flag, coins). It does not carry palette state, status-icon visuals, or any other presentation field.
 
 ---
 
-## Binary AOI Protocol (Decoder)
+## Presentation ownership
 
-`binary_aoi_decoder.c` parses all server → client messages:
+The client owns its render policy. The authoritative server holds no presentation state.
 
-| Message Type | Byte   | Decoder Function    | Description                               |
-| ------------ | ------ | ------------------- | ----------------------------------------- |
-| `aoi_update` | `0x01` | `decode_aoi_update` | Delta AOI — entities entered/left view    |
-| `init_data`  | `0x02` | `decode_init_data`  | Full config on connect (JSON sub-payload) |
-| `full_aoi`   | `0x03` | `decode_full_aoi`   | Full AOI snapshot                         |
-| `FCT`        | `0x04` | `decode_fct`        | Floating Combat Text (14-byte fixed)      |
-| `ItemFCT`    | `0x05` | `decode_item_fct`   | Item FCT with string item ID (variable)   |
+Three layers, strictly inward-dependent:
 
-**All multi-byte integers: little-endian.**
+1. **`domain/presentation_runtime.{c,h}`** — sole owner of every presentation value. Fires a single asynchronous GET against `/api/cyberia-client-hints/:CYBERIA_CLIENT_HINTS_CODE` at startup, polled once per render frame. When the response settles, parses palette, entity colour keys, status-icon visuals, and camera/cell tunings into a process-local table and writes a one-shot hydration into `g_game_state` (cell_size, interpolation_ms, camera.zoom). The C client carries NO compile-time palette or status table — only a tiny inline neutral-grey bootstrap so the splash screen has something to draw while the fetch is in flight. The canonical schema for the response lives at engine-cyberia's `src/client/components/cyberia/SharedDefaultsCyberia.js`.
+2. **Renderers** — call `presentation_runtime_palette("KEY")`, `presentation_runtime_status_icon(u8)`, `presentation_runtime_status_border(u8)`, `presentation_runtime_entity_fallback_color(entity_type)` at each use site.
 
-**FCT type → visual:**
+What lives in this layer:
 
-| FCT Type | Byte   | Color  |
-| -------- | ------ | ------ |
-| Damage   | `0x00` | Red    |
-| Regen    | `0x01` | Green  |
-| CoinGain | `0x02` | Yellow |
-| CoinLoss | `0x03` | Yellow |
-| ItemGain | `0x04` | Cyan   |
-| ItemLoss | `0x05` | Purple |
+- Named palette (colors).
+- Per-entity-type fallback color keys.
+- Status-icon visual table (icon stem + border color per numeric ID).
+- Camera smoothing / zoom defaults.
+- Interpolation window.
+- Dev-overlay flag.
+- Viewport screen factors.
 
----
+What does **not** travel on the WebSocket init or AOI streams:
 
-## ObjectLayer Cache
+- Palette.
+- Camera knobs.
+- Dev-overlay flag.
+- Interpolation window.
+- Status-icon visuals.
+- Per-entity-type color keys.
 
-`object_layer.c` maintains an LRU cache (`MAX_LAYER_CACHE_SIZE = 256`) of parsed `ObjectLayerMetadata` structs:
-
-```
-Fetch pipeline per item ID:
-  1. Check LRU cache → hit? return immediately
-  2. Call JS bridge: services.fetchObjectLayer(itemId)
-     → GET {API_BASE_URL}/api/object-layer/{itemId}
-  3. Parse JSON response → populate ObjectLayerMetadata
-  4. Evict LRU entry if cache full → insert new entry
-  5. Trigger texture fetch for each layer CID
-```
+The numeric status-icon u8 still rides on the AOI wire — that is the protocol-level half. The icon stem and border color are presentation and are resolved entirely on the client.
 
----
+### Optional client hints
 
-## Texture Manager
+`GET /api/cyberia-client-hints/:instanceCode` (engine-cyberia REST, **not** cyberia-server) returns a JSON document mirroring the structure of the compile-time defaults. The client is required to function with no successful call to this endpoint:
 
-`texture_manager.c` maintains an LRU cache (`MAX_TEXTURE_CACHE_SIZE = 512`) of Raylib `Texture2D` objects:
+- 200 with `{ palette, entityColorKeys, statusIcons, cameraSmoothing, cameraZoom, defaultWidthScreenFactor, defaultHeightScreenFactor, interpolationMs, devUi }` — overrides applied on top of defaults.
+- 404 if the instance has no overrides — defaults are used.
+- Network error — defaults are used.
 
-```
-Fetch pipeline per CID:
-  1. Check cache by CID → hit? return Texture2D*
-  2. Call JS bridge: services.fetchFileBlob(cid)
-     → GET {API_BASE_URL}/api/file/blob/{cid}
-  3. Decode PNG blob → Raylib Image → Texture2D (GPU upload)
-  4. Evict LRU on full cache → insert new entry
-```
+No authentication; presentation hints are not secret. The Go authoritative server never calls this endpoint.
 
 ---
 
-## Input System (Tap-Based)
+## Tick-aware components
 
-The client uses a **tap-first** interaction model:
+### Session
 
-| Input                           | Action                                                       |
-| ------------------------------- | ------------------------------------------------------------ |
-| Tap empty tile                  | Send `tap_move` WS message → player moves to cell            |
-| Tap entity (NPC/resource)       | Send `tap_entity` WS message → server dispatches interaction |
-| Tap inventory item              | Toggle equip/unequip → send `item_activation`                |
-| Tap interact overlay (JS layer) | Opens action modal via `_c_open_dialogue_from_js`            |
+`network/session.{c,h}` tracks per-connection tick state:
 
-`input.c` translates raw Raylib mouse/touch events into game-world cell coordinates using the current camera offset, then dispatches the appropriate WS message via `network_send_message`.
+- `last_server_tick` — highest snapshot tick observed.
+- `last_acked_input_sequence` — highest sequence the server has applied for this client; echoed in every snapshot header.
+- `next_input_sequence` — monotonic counter for outgoing input commands.
+- `server_tick_estimate` — extrapolation of last server tick by elapsed wall time, used to stamp outgoing input commands and to compute `renderTick`.
 
----
+### Prediction
 
-## JS↔WASM Bridge
+`prediction/prediction.{c,h}` owns the predicted self position. It is the only writer of the predicted state. Internally it tracks **two** positions: the discrete per-tick `predicted_pos` (where the simulation says the player is) and the continuous render-frame `display_pos` (what the renderer reads). The renderer never sees the discrete value.
 
-Emscripten exported C functions (callable from JavaScript):
+- `prediction_apply(cmd)` — optimistic local apply of an input command + push onto replay buffer.
+- `prediction_step(dt)` — fixed-timestep advance, called by the accumulator. Mutates `predicted_pos` only.
+- `prediction_reconcile()` — on snapshot arrival: drop acknowledged inputs, rewind self to authoritative position, replay unacked inputs. Mutates `predicted_pos` only.
+- `prediction_display_step(frame_dt)` — per-render-frame exponential lerp of `display_pos` toward `predicted_pos`. This is the layer that absorbs reconcile snaps and sim-tick stepping so the visible main player moves continuously.
+- `prediction_self_position()` — render-time accessor; returns the smoothed `display_pos`.
 
-| C Function                        | Description                                   |
-| --------------------------------- | --------------------------------------------- |
-| `_c_send_ws_message(ptr, len)`    | Send raw bytes over the WebSocket             |
-| `_c_open_dialogue_from_js(ptr)`   | Open dialogue modal with serialized JSON      |
-| `_c_interact_overlay_did_close()` | Notify WASM that the JS overlay was dismissed |
+### Interpolation
 
-JavaScript library functions (callable from C via `EM_ASM` / `--js-library`):
+`interpolation/interpolation.{c,h}` owns remote-entity render-time positions. It is the only writer of remote `interp_pos`. It never touches the local player (prediction owns that). Sampling happens at `renderTick = serverTickEstimate − INTERP_TICKS`.
 
-| JS Function                               | Source                   | Description                            |
-| ----------------------------------------- | ------------------------ | -------------------------------------- |
-| `services.fetchObjectLayer(itemId, cb)`   | `js/services.js`         | Fetch ObjectLayer JSON from Engine API |
-| `services.fetchAtlasSpriteSheet(cid, cb)` | `js/services.js`         | Fetch atlas frame metadata             |
-| `services.fetchFileBlob(cid, cb)`         | `js/services.js`         | Fetch raw IPFS-addressed blob          |
-| `interact_overlay.show(entityId)`         | `js/interact_overlay.js` | Show tap-to-interact HTML overlay      |
-| `notify_badge.set(count)`                 | `js/notify_badge.js`     | Update browser notification badge      |
+### Input command pipeline
+
+```
+mouse / touch / keyboard
+        │
+        ▼
+input/input_capture
+        │
+        ▼
+UI hit-test cascade  ──► modal/inventory/HUD consumed?
+        │  no
+        ▼
+input_command_build_*   stamps client_tick + sequence
+        │
+        ▼
+prediction_apply        optimistic local apply
+        │
+        ▼
+uplink send             WebSocket binary frame
+```
+
+`InputCommand.Sequence` is allocated by `session_next_input_sequence`. Monotonic, never reused. The server echoes the highest applied sequence in every snapshot header; the prediction module drops acked commands from its replay buffer on reconciliation.
 
 ---
 
-## Compile-Time Configuration (`config.h`)
+## Binary AOI snapshot format
+
+The client decodes server-pushed AOI frames. Header (little-endian, 11 bytes for `0x01`/`0x03`):
 
-| Constant                    | Default                             | Description                                    |
-| --------------------------- | ----------------------------------- | ---------------------------------------------- |
-| `WS_URL`                    | `wss://server.cyberiaonline.com/ws` | WebSocket endpoint                             |
-| `API_BASE_URL`              | `https://www.cyberiaonline.com`     | Engine REST API base URL                       |
-| `HTTP_TIMEOUT_SECONDS`      | `10`                                | HTTP request timeout (asset fetching)          |
-| `MAX_TEXTURE_CACHE_SIZE`    | `512`                               | Max atlas textures in VRAM cache               |
-| `MAX_LAYER_CACHE_SIZE`      | `256`                               | Max ObjectLayer metadata entries in cache      |
-| `MAX_ATLAS_CACHE_SIZE`      | `256`                               | Max atlas sprite sheet metadata entries        |
-| `DEFAULT_FRAME_DURATION_MS` | `100`                               | Default animation frame rate                   |
-| `ENABLE_DEV_UI`             | `false`                             | Force dev overlay on (override server setting) |
-| `APP_VERSION`               | `"1.0.0"`                           | Application version string                     |
+```
+[0]      u8   msgType     0x01 aoi_update | 0x03 full_aoi
+[1..4]   u32  tick        simulation tick at which the snapshot was produced
+[5..8]   u32  lastAcked   highest InputCommand.Sequence applied for this client
+[9..10]  u16  entityCount entity blocks that follow
+```
 
-For local development, change `WS_URL` and `API_BASE_URL` to `localhost` variants before rebuilding.
+After parsing the header, the decoder invokes `session_on_snapshot(tick, lastAcked)` and then `prediction_reconcile()` so the predicted self stays consistent with the just-arrived authoritative state.
 
----
+Other message types — init data (0x02), FCT (0x04), ItemFCT (0x05) — carry their own headers and are not part of the per-tick replication stream.
 
-## Build System
+---
 
-### Dependencies
+## REST fetches (engine-cyberia)
 
-| Library    | Version | Usage                               |
-| ---------- | ------- | ----------------------------------- |
-| Emscripten | ≥ 3.1   | C → WASM compiler + JS runtime      |
-| Raylib     | ≥ 5.0   | Rendering (OpenGL ES2 via WebGL)    |
-| cJSON      | 1.7.x   | JSON parsing (ObjectLayer metadata) |
+The client speaks REST directly to engine-cyberia for content. None of these calls go through cyberia-server.
 
-Raylib and cJSON are vendored under `libs/`.
+| Endpoint                                         | Purpose                              |
+| ------------------------------------------------ | ------------------------------------ |
+| `GET /api/atlas-sprite-sheet/metadata/:itemKey`  | Frame layout JSON for a sprite atlas |
+| `GET /api/atlas-sprite-sheet/blob/:itemKey`      | Atlas PNG                            |
+| `GET /api/object-layer/:itemId`                  | ObjectLayer JSON metadata            |
+| `GET /api/cyberia-dialogue/code/default-:itemId` | Dialogue lines for an NPC            |
+| `GET /assets/ui-icons/:iconId.png`               | Status-bar icons                     |
+| `GET /api/cyberia-client-hints/:instanceCode`    | Optional presentation overrides      |
 
-### Build Modes
+All requests are CORS-simple GETs (no preflight) and cacheable. None require credentials.
 
-| Mode              | Flags                | Use                                             |
-| ----------------- | -------------------- | ----------------------------------------------- |
-| `DEBUG` (default) | `-O0 -g --profiling` | Development — includes symbols, no optimization |
-| `RELEASE`         | `-O3 -DNDEBUG`       | Production — fully optimized                    |
+---
 
-### Build Commands
+## Build and run
 
 ```bash
 cd cyberia-client
 
-# Debug build (default)
-make -f Web.mk
+# Development build
+make -f Web.mk clean && make -f Web.mk web
 
 # Release build
-make -f Web.mk BUILD_MODE=RELEASE
+make -f Web.mk clean && make -f Web.mk web BUILD_MODE=RELEASE
 
 # Build + serve on dev port :8082
 make -f Web.mk serve-development
-
-# Build release + serve on production port :8081
-make -f Web.mk serve-production
-
-# Clean build artifacts
-make -f Web.mk clean
 ```
 
+The build is part of the Underpost Platform static + PWA pipeline; production deploys go through `underpost client` and `underpost deploy`.
+
 ### Output
 
 ```
@@ -271,43 +254,38 @@ bin/
   index.html    — Emscripten HTML container (from shell.html template)
   index.wasm    — Compiled WebAssembly module
   index.js      — Emscripten JS glue
-  index.data    — Preloaded data bundle (assets)
+  index.data    — Preloaded data bundle
 ```
 
 ---
 
-## Persistent Storage
+## Compile-time configuration
 
-`serial.c` uses Emscripten's **IDBFS** (IndexedDB File System) to persist:
+`src/config.h`:
 
-- Player authentication token (EIP-712 signature)
-- Local game settings (audio volume, key bindings)
-- Cached ObjectLayer metadata (session cache warm-up)
+| Constant                    | Default                             | Description                                                                                                      |
+| --------------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `WS_URL`                    | `wss://server.cyberiaonline.com/ws` | WebSocket endpoint of cyberia-server                                                                             |
+| `API_BASE_URL`              | `https://www.cyberiaonline.com`     | engine-cyberia REST base URL                                                                                     |
+| `CYBERIA_CLIENT_HINTS_CODE` | `cyberia-main`                      | Lookup key for the optional client-hints fetch (presentation override key — never an instance/server identifier) |
+| `HTTP_TIMEOUT_SECONDS`      | `10`                                | HTTP request timeout                                                                                             |
+| `MAX_TEXTURE_CACHE_SIZE`    | `512`                               | Atlas texture LRU cap                                                                                            |
+| `MAX_LAYER_CACHE_SIZE`      | `256`                               | ObjectLayer metadata LRU cap                                                                                     |
+| `MAX_ATLAS_CACHE_SIZE`      | `256`                               | Atlas metadata LRU cap                                                                                           |
+| `DEFAULT_FRAME_DURATION_MS` | `100`                               | Default animation frame duration                                                                                 |
+| `ENABLE_DEV_UI`             | `false`                             | Force dev overlay regardless of presentation hints                                                               |
+| `APP_VERSION`               | `"1.0.0"`                           | Application version string                                                                                       |
 
-Data is stored at `/persistent/` in the virtual IDBFS mount.
+For local development, point `WS_URL` and `API_BASE_URL` at `localhost` before rebuilding.
 
 ---
 
-## Environment: Local Development
-
-Change these two constants in `src/config.h` and rebuild:
-
-```c
-static const char* WS_URL = "ws://localhost:8081/ws";
-static const char* API_BASE_URL = "http://localhost:4005";
-```
-
-Then:
+## Persistent storage
 
-```bash
-# Terminal 1 — Engine (Node.js)
-cd /path/to/engine && node src/index.js
+`serial.c` uses Emscripten's IDBFS (IndexedDB File System) at `/persistent/` for:
 
-# Terminal 2 — Go game server
-cd cyberia-server && go run main.go
-
-# Terminal 3 — Client build + serve
-cd cyberia-client && make -f Web.mk serve-development
-```
+- Player authentication token (EIP-712 signature).
+- Local game settings (audio volume, key bindings).
+- Cached ObjectLayer metadata (session warm-up cache).
 
-Open `http://localhost:8082` in a browser.
+No game state is persisted client-side; the authoritative server is the source of truth.