cyberia 3.2.9 → 3.2.22

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

@@ -0,0 +1,259 @@
+<div align="center">
+
+  <img src="https://www.cyberiaonline.com/assets/splash/apple-touch-icon-precomposed.png" alt="CYBERIA Network Object Layer Engine"/>
+
+<h1>CYBERIA</h1>
+
+**Network Object Layers**
+
+_Stackable Rendering Layers as a Unified Tokenized Reality_
+
+[![Version](https://img.shields.io/npm/v/cyberia.svg)](https://www.npmjs.org/package/cyberia)
+
+</div>
+Cyberia is an MMORPG extension built on the Underpost Platform. The platform owns the
+toolchain, deployment surface, PWA delivery, and base infrastructure. Cyberia adds a three-service MMO
+runtime: `engine-cyberia`, `cyberia-server`, and `cyberia-client`.
+
+`engine-cyberia` is the **sidecar-backed data layer**: a Node.js sidecar that owns content,
+validation, persistence, the gRPC/REST data services, and asset metadata. It backs the authoritative
+Go server and the WASM client with data — it does not run the simulation or the presentation.
+
+---
+
+## Ecosystem at a glance
+
+```text
+                         ┌───────────────────────────────────────────────┐
+                         │              UNDERPOST PLATFORM                 │
+                         │  toolchain · deploy · PWA build · static        │
+                         │  delivery · cluster/image/db · monitoring       │
+                         │                                                 │
+                         │   underpost CLI  ──▶  builds & deploys all      │
+                         └───────────────────────────────────────────────┘
+                                            │  hosts / delivers
+                                            ▼
+   ╔═══════════════════════════════ CYBERIA MMO ══════════════════════════════════╗
+   ║                                                                               ║
+   ║   ┌──────────────────┐   gRPC    ┌──────────────────┐   WebSocket            ║
+   ║   │  engine-cyberia  │ ────────▶ │  cyberia-server  │ ───────────┐           ║
+   ║   │     (Node.js)    │           │       (Go)       │            │           ║
+   ║   │                  │           │                  │            ▼           ║
+   ║   │ content          │           │ authoritative    │   ┌──────────────────┐ ║
+   ║   │ validation       │           │ simulation       │   │  cyberia-client  │ ║
+   ║   │ persistence      │           │ world tick       │   │    (C / WASM)    │ ║
+   ║   │ gRPC/REST data   │           │ AOI replication  │   │                  │ ║
+   ║   │ asset metadata   │           │                  │   │ rendering        │ ║
+   ║   └──────────────────┘           └──────────────────┘   │ input            │ ║
+   ║            │                                             │ prediction       │ ║
+   ║            └──────────────── REST (content/assets) ─────▶│ presentation     │ ║
+   ║                                                          └──────────────────┘ ║
+   ╚═══════════════════════════════════════════════════════════════════════════════╝
+
+   One source of truth per concern:
+     content & world config ── engine-cyberia
+     real-time world state  ── cyberia-server
+     presentation & input   ── cyberia-client
+```
+
+---
+
+## 1. Toolchain and base infrastructure
+
+Underpost Platform is the operational backbone and the source of truth for deploy IDs, runtime
+selection, host/path layout, generated client assets, and environment resolution.
+
+| Area            | What it owns                                                                         |
+| --------------- | ------------------------------------------------------------------------------------ |
+| Toolchain       | `underpost` CLI, build, deploy, release, metadata, secrets, environment selection    |
+| Infrastructure  | bare metal, LXD, Kubernetes, K3s, kubeadm, images, SSH, runners                      |
+| Data operations | MongoDB, MariaDB where needed, backups, cron, monitoring                             |
+| Delivery        | static build, SSR views, PWA packaging, service worker generation, host/path routing |
+
+`underpost` is the shared control surface for everything infrastructural. Cyberia-specific work belongs
+in the `cyberia` CLI, never in parallel platform commands. When a concern already exists in `underpost`,
+reuse it instead of forking a Cyberia variant.
+
+---
+
+## 2. PWA workflow
+
+Every deployed client ships as a static application shell with PWA support. The pipeline has exactly two
+inputs:
+
+- the deploy `ssr` configuration in `conf.dd-*.js` (or `conf.ssr.json`)
+- the service worker source in `src/client/sw/core.sw.js`
+
+Everything else — `index.html` pages, `sw.js`, the precache list — is **generated** during the client
+build. Treat them as outputs only; never hand-edit them.
+
+Runtime service-worker behavior:
+
+| Request       | Strategy                         |
+| ------------- | -------------------------------- |
+| static assets | stale-while-revalidate           |
+| API `GET`     | network-first + short cache      |
+| API mutations | network-only + background replay |
+| navigation    | network-first + fallback shells  |
+
+Fallback selection: offline network → offline fallback view; origin/server failure → maintenance
+fallback view. Only fallback-marked views are guaranteed precached.
+
+---
+
+## 3. Cyberia MMO extension
+
+### Responsibility split
+
+| Service          | Owns                                                                      | Must not own                                  |
+| ---------------- | ------------------------------------------------------------------------- | --------------------------------------------- |
+| `engine-cyberia` | content, validation, persistence, gRPC/REST data services, asset metadata | authoritative simulation, render policy       |
+| `cyberia-server` | authoritative simulation, world tick, gameplay mutation, AOI replication  | content authority, presentation metadata      |
+| `cyberia-client` | rendering, input, prediction, interpolation, presentation                 | authoritative world state, gameplay authority |
+
+Two boundaries are non-negotiable:
+
+- Do not move authoritative logic into the client.
+- Do not move content-authority logic into the Go runtime.
+
+### Data flow
+
+```text
+engine-cyberia ──gRPC──▶ cyberia-server ──WebSocket──▶ cyberia-client
+engine-cyberia ──REST──────────────────────────────▶ cyberia-client
+```
+
+### `engine-cyberia` as the sidecar-backed data layer
+
+`engine-cyberia` is the only Cyberia service that owns content-backed data and asset metadata.
+
+- Boot-time world configuration flows from `engine-cyberia` to `cyberia-server` over gRPC `GetFullInstance`.
+- Client-facing assets, object layers, dialogues, and presentation hints flow from `engine-cyberia` to `cyberia-client` over REST.
+- Simulation never migrates into the sidecar, and presentation policy never migrates out of the client.
+
+### Runtime / health model
+
+Three supervised processes run in parallel, each with its own monitor and reconnect loop. Gameplay is live only when all three are healthy at once.
+
+```text
+        ┌──────────────────────────────────────────────────────────────┐
+        │                    SUPERVISION (parallel)                      │
+        │                                                                │
+        │   engine-cyberia        cyberia-server        cyberia-client   │
+        │   ┌────────────┐        ┌────────────┐        ┌────────────┐   │
+        │   │  monitor   │        │  monitor   │        │  monitor   │   │
+        │   │ +reconnect │        │ +reconnect │        │ +reconnect │   │
+        │   └─────┬──────┘        └─────┬──────┘        └─────┬──────┘   │
+        │         │                     │                     │          │
+        │         └──────────┬──────────┴──────────┬──────────┘          │
+        │                    ▼                     ▼                     │
+        │            all three up & connected?                          │
+        └────────────────────────────┬─────────────────────────────────┘
+                                      │
+                ┌─────────────────────┼─────────────────────┐
+                ▼                     ▼                     ▼
+          ┌───────────┐        ┌───────────┐         ┌───────────┐
+          │  HEALTHY  │        │ DEGRADED  │         │  STANDBY  │
+          │ all 3 up  │        │ ≥1 service│         │ gameplay  │
+          │ gameplay  │        │ reconnect-│         │ paused    │
+          │ live      │        │ ing / down│         │ until all │
+          │           │        │           │         │ 3 healthy │
+          └───────────┘        └───────────┘         └───────────┘
+```
+
+| State      | Meaning                                                              |
+| ---------- | -------------------------------------------------------------------- |
+| `healthy`  | all three Cyberia services are up and connected                      |
+| `degraded` | at least one service is reconnecting or unavailable                  |
+| `standby`  | gameplay is paused because the full three-service set is not healthy |
+
+---
+
+## User commands
+
+Use `underpost` for platform, infrastructure, build, and deploy. Use `cyberia` for MMO content and
+extension workflows. Both share the same helpers — never duplicate config, env, or path logic.
+
+### Platform (underpost)
+
+```bash
+# Bootstrap a new app (local app serves on http://localhost:4001)
+underpost new app-name
+
+# Build the client bundle / static + PWA output
+underpost client
+npm run build            # node bin client
+
+# Deploy and operate
+underpost deploy <deploy-id>
+underpost monitor
+```
+
+### Cyberia (cyberia) — `bin/cyberia.js`
+
+| Group          | Command                                | Purpose                                                  |
+| -------------- | -------------------------------------- | -------------------------------------------------------- |
+| `ol`           | `cyberia ol [item-id]`                 | ObjectLayer import, procedural generation, atlas/sprite  |
+| `instance`     | `cyberia instance [instance-code]`     | export / import / drop a Cyberia instance and its data   |
+| `client-hints` | `cyberia client-hints [instance-code]` | per-instance presentation hints (palette, camera, icons) |
+| `chain`        | `cyberia chain <sub>`                  | Hyperledger Besu + ERC-1155 ObjectLayerToken lifecycle   |
+| `run-workflow` | `cyberia run-workflow <name>`          | named maintenance/build scripts from `scripts/`          |
+
+Common examples:
+
+```bash
+# Object layer content
+cyberia ol hatchet,sword --import                 # import specific items
+cyberia ol --import-types skin,floors             # batch import by type (or: all)
+cyberia ol floor-desert --generate --seed fx-42   # procedural generation
+cyberia ol hatchet --to-atlas-sprite-sheet        # build atlas sprite sheet
+cyberia ol --drop --client-public                 # drop data + static asset folders
+
+# Instance data
+cyberia instance FOREST --export ./backup
+cyberia instance FOREST --import ./backup
+cyberia instance FOREST --drop
+
+# Presentation hints
+cyberia client-hints cyberia-main --seed-defaults
+
+# Chain / token lifecycle
+cyberia chain deploy --chain-id 777771
+cyberia chain status
+cyberia chain register / mint / transfer / burn / pause / unpause
+
+# Named workflows
+cyberia run-workflow import-default-items
+cyberia run-workflow seed-skill-config --instance-code default
+cyberia run-workflow seed-dialogues
+cyberia run-workflow build-manifest
+cyberia run-workflow build-server-dashboard
+```
+
+### Run the MMO services
+
+```bash
+# engine-cyberia (Node.js data/content services)
+npm start                                          # node src/server
+
+# cyberia-server (Go authoritative simulation)
+cd cyberia-server && go run main.go                # dev
+cd cyberia-server && go build -o cyberia-server . && ./cyberia-server
+
+# cyberia-client (C / WASM presentation)
+cd cyberia-client && make -f Web.mk clean && make -f Web.mk web
+cd cyberia-client && make -f Web.mk serve-development     # serves on :8082
+```
+
+---
+
+## Operational guardrails
+
+- Prefer one source of truth for config, deploy IDs, runtime selection, startup behavior, and generated assets.
+- Reuse existing helpers and conventions instead of creating parallel implementations.
+- Do not duplicate parsing, env resolution, or path normalization logic across modules.
+- Treat generated artifacts (`sw.js`, static pages, atlases, README, manifests) as outputs only.
+- Host-level changes must be idempotent, reversible, and explicit; validate before mutating; keep
+  orchestration scripts safe to rerun.
+- `engine-private/` is a private external dependency. Reference it only as private input; never assume
+  its contents exist locally.

package/src/client/public/cyberia-docs/OFF-CHAIN-ECONOMY.md

@@ -4,7 +4,7 @@
 
 > **Status:** Alpha (sinks disabled by default; all values reset on reconnect).
 > **On-chain bridge:** CKY ERC-1155 token (ID 0) on Hyperledger Besu.
-> See [WHITE-PAPER.md](WHITE-PAPER.md) §7 for the bridge protocol.
+> The bridge protocol stays aligned with the project's CKY tokenomics model.
 
 ---
 
@@ -61,7 +61,7 @@ Cyberia Online uses the **Fountain & Sink** economy — the industry standard fo
 
 Economy parameters live in `CyberiaInstanceConf.economyRules`. A document without an `economyRules` sub-document receives canonical defaults automatically.
 
-### 2.1 JavaScript Defaults (`cyberia-instance-conf.defaults.js`)
+### 2.1 JavaScript Defaults (`cyberia-server-defaults.js`)
 
 ```javascript
 economyRules: {

package/src/client/public/cyberia-docs/QUEST-SYSTEM.md

@@ -10,7 +10,7 @@ The Quest System is a **chain/tree-structured progression framework** linking NP
 
 Quests are defined server-side as MongoDB documents and delivered to the client through the Engine REST API. Progress is tracked per-player in `CyberiaQuestProgress` documents.
 
-> **Implementation status — Pre-alpha:** The Quest and QuestProgress MongoDB schemas and Engine REST API (`src/api/cyberia-quest`, `src/api/cyberia-quest-progress`) are defined and seeded. Go server integration (quest tracking, objective evaluation, reward delivery via FCT) is planned for the **Alpha milestone**. For pre-alpha, quest progress is ephemeral: it lives in the client session only and resets on page reload.
+> **Implementation status — Alpha (talk objectives):** The Quest and QuestProgress MongoDB schemas and Engine REST API (`src/api/cyberia-quest`, `src/api/cyberia-quest-progress`) are defined and seeded. The Go server fetches quest definitions at instance init and now evaluates `talk` objectives, grants quests, advances steps, and delivers rewards via FCT on completion (driven by `dlg_complete` — see ACTION-SYSTEM.md). `collect` and `kill` objective evaluation remains planned for a later Alpha increment. Quest progress is authoritative **per Go session** (in-memory) and best-effort mirrored to `POST /api/cyberia-quest-progress`; it resets on reconnect. The C client surfaces it through the **Quest Journal** (see below).
 
 ---
 
@@ -168,6 +168,28 @@ On quest completion, the Engine grants each `rewards[].{itemId, quantity}` to th
 
 ---
 
+## Quest Journal (client)
+
+The C client keeps a local `quest_store` (in `cyberia-client/src/ui/quest_store.c`)
+populated from two server sources — **no extra REST calls**:
+
+- `init_data.quests[]` — the player's active/completed snapshot on connect.
+- `dlg_ack.quests[]` — live upserts as quests are granted or completed.
+
+The **Quest Journal** modal (`ui/quest_journal.c`) renders this store on the
+right side below the map info modal: a three-section tree (Active / Completed /
+Failed), each section independently collapsible via the shared `ui_toggle`
+component, each with its own 10-per-page pagination cursor. The interaction
+bubble column on the left is collapsible by the same toggle pattern. Both panels
+default collapsed on screens narrower than 600 px. Collapse state is not
+persisted across sessions.
+
+Each server quest snapshot entry carries `{ code, title, description, status,
+activeStep, objectivesText }` so the journal can render rows and inline detail
+without re-fetching the quest definition.
+
+---
+
 ## Indexes
 
 ```javascript

package/src/client/public/cyberia-docs/ROADMAP.md

@@ -1,6 +1,6 @@
 # Cyberia Online — Development Roadmap
 
-**Current version:** 3.0.3 | **Target milestone:** Open Alpha
+**Current version:** 3.2.22 | **Target milestone:** Open Alpha
 
 ---
 

package/src/client/public/cyberia-docs/UNDERPOST-PLATFORM.md

@@ -0,0 +1,106 @@
+# Underpost Platform
+
+Underpost Platform is the base product. It owns the toolchain, deployment surface, PWA delivery, and operational infrastructure. Cyberia is an MMO extension that runs on top of it; Cyberia is not the platform.
+
+---
+
+## Toolchain and base infrastructure
+
+Underpost Platform covers the shared delivery surface for applications and extensions:
+
+| Area            | What it owns                                                                         |
+| --------------- | ------------------------------------------------------------------------------------ |
+| Toolchain       | `underpost` CLI, build, deploy, release, metadata, secrets, environment selection    |
+| Infrastructure  | bare metal, LXD, Kubernetes, K3s, kubeadm, images, SSH, runners                      |
+| Data operations | MongoDB, MariaDB where needed, backups, cron, monitoring                             |
+| Delivery        | static build, SSR views, PWA packaging, service worker generation, host/path routing |
+
+The platform is the operational backbone. It should stay the source of truth for deploy IDs, runtime selection, host/path layout, generated client assets, and environment resolution.
+
+---
+
+## Underpost CLI
+
+`underpost` is the shared control surface for platform operations. Top-level commands (`underpost <cmd> --help` for options):
+
+| Group              | Command     | Purpose                                                       |
+| ------------------ | ----------- | ------------------------------------------------------------- |
+| **Project / repo** | `new`       | Initialize a new project, service, or configuration           |
+|                    | `clone`     | Clone a GitHub repository into the current directory          |
+|                    | `pull`      | Pull latest changes from a repository                         |
+|                    | `cmt`       | Manage commits (commit types and options)                     |
+|                    | `push`      | Push committed changes to a remote repository                 |
+|                    | `install`   | Import Underpost npm dependencies by copying                  |
+|                    | `root`      | Print the npm installation root path                          |
+| **Build / config** | `client`    | Build client assets / single replicas; sync environment ports |
+|                    | `static`    | Static build of pages, bundles, and documentation             |
+|                    | `env`       | Set env vars and config for a deploy ID                       |
+|                    | `config`    | Manage Underpost configuration via operators                  |
+|                    | `metadata`  | Import/export cluster metadata                                |
+| **Deploy / infra** | `cluster`   | Manage Kubernetes clusters (defaults to Kind init)            |
+|                    | `deploy`    | Manage deployments (defaults to development pods)             |
+|                    | `image`     | Build, save, and load Docker images into clusters             |
+|                    | `secret`    | Manage secrets across platforms                               |
+|                    | `lxd`       | Manage LXD VMs as K3s nodes (control plane / workers)         |
+|                    | `baremetal` | Bare-metal provisioning workflows                             |
+|                    | `ip`        | Show current public machine IP addresses                      |
+| **Data / ops**     | `db`        | Database backup / restore and related operations              |
+|                    | `cron`      | Run cron jobs or generate/apply K8s CronJob manifests         |
+|                    | `fs`        | File storage (defaults to upload)                             |
+|                    | `monitor`   | Health-server monitoring for deployments                      |
+|                    | `ssh`       | Manage SSH credentials and sessions for cluster nodes         |
+|                    | `run`       | Run scripts via named runners                                 |
+|                    | `test`      | Run the test suites                                           |
+|                    | `release`   | Release orchestrator for building and shipping CLI versions   |
+
+Cyberia-specific operations belong in `cyberia`, not in parallel platform commands. Use the base CLI for infrastructure and delivery, then layer Cyberia workflows on top.
+
+---
+
+## PWA delivery model
+
+Every deployed client is delivered as a static application shell with PWA support.
+
+- SSR views declare which pages exist and which fallbacks are precached.
+- The service worker is generated from the configured view set.
+- Offline and maintenance fallbacks are part of the build output, not hand-maintained runtime artifacts.
+- Generated outputs such as `sw.js`, static pages, and compiled bundles are outputs only; never edit them by hand.
+
+```text
+conf.dd-*.js / conf.ssr.json    +    src/client/sw/core.sw.js
+			   │
+			   └──── underpost client / build ────▶ generated index.html + sw.js + precache
+```
+
+Keep those two inputs as the only authored PWA sources.
+
+---
+
+## Cyberia on top of the platform
+
+Cyberia adds a three-service MMO runtime on top of the base platform:
+
+| Service          | Responsibility                                                            |
+| ---------------- | ------------------------------------------------------------------------- |
+| `engine-cyberia` | content, validation, persistence, gRPC/REST data services, asset metadata |
+| `cyberia-server` | authoritative simulation and tick processing                              |
+| `cyberia-client` | rendering, input, prediction, presentation                                |
+
+---
+
+## Operational rules
+
+- Prefer one source of truth for config, deploy IDs, runtime selection, startup behavior, and generated assets.
+- Reuse existing helpers and conventions instead of creating parallel implementations.
+- Do not duplicate parsing, env resolution, or path normalization logic across modules.
+- Treat generated artifacts as outputs only; never hand-edit them.
+- `engine-private/` is a private external dependency. Reference it as private input only and never assume its contents exist locally.
+
+---
+
+## Safety and orchestration
+
+- Any host-level change must be idempotent, reversible, and explicit.
+- Never assume mounts, users, groups, namespaces, or volumes already exist.
+- Validate before mutating: check paths, permissions, ownership, and target state first.
+- Keep orchestration scripts resilient to interruption and safe to rerun.

package/src/client/public/cyberia-docs/WHITE-PAPER.md

@@ -18,7 +18,7 @@ _Stackable Rendering Layers as a Unified Tokenized Reality_
 
 ---
 
-**Version:** 3.2.9 | **Status:** Draft | **Authors:** Underpost Engineering
+**Version:** 3.2.22 | **Status:** Draft | **Authors:** Underpost Engineering
 
 ---
 

package/src/client/services/cyberia-client-hints/cyberia-client-hints.service.js

@@ -0,0 +1,99 @@
+import { Auth } from '../../components/core/Auth.js';
+import { loggerFactory } from '../../components/core/Logger.js';
+import { getApiBaseUrl, headersFactory, payloadFactory, buildQueryUrl } from '../core/core.service.js';
+const logger = loggerFactory(import.meta);
+logger.info('Load service');
+const endpoint = 'cyberia-client-hints';
+class CyberiaClientHintsService {
+  static post = (options = { id: '', body: {} }) =>
+    new Promise((resolve, reject) =>
+      fetch(getApiBaseUrl({ id: options.id, endpoint }), {
+        method: 'POST',
+        headers: headersFactory(),
+        credentials: 'include',
+        body: payloadFactory(options.body),
+      })
+        .then(async (res) => {
+          return await res.json();
+        })
+        .then((res) => {
+          logger.info(res);
+          return resolve(res);
+        })
+        .catch((error) => {
+          logger.error(error);
+          return reject(error);
+        }),
+    );
+  static put = (options = { id: '', body: {} }) =>
+    new Promise((resolve, reject) =>
+      fetch(getApiBaseUrl({ id: options.id, endpoint }), {
+        method: 'PUT',
+        headers: headersFactory(),
+        credentials: 'include',
+        body: payloadFactory(options.body),
+      })
+        .then(async (res) => {
+          return await res.json();
+        })
+        .then((res) => {
+          logger.info(res);
+          return resolve(res);
+        })
+        .catch((error) => {
+          logger.error(error);
+          return reject(error);
+        }),
+    );
+  static get = (options = {}) => {
+    const { id, page, limit, filterModel, sortModel, sort, asc, order } = options;
+    const url = buildQueryUrl(getApiBaseUrl({ id, endpoint }), {
+      page,
+      limit,
+      filterModel,
+      sortModel,
+      sort,
+      asc,
+      order,
+    });
+    return new Promise((resolve, reject) =>
+      fetch(url.toString(), {
+        method: 'GET',
+        headers: headersFactory(),
+        credentials: 'include',
+      })
+        .then(async (res) => {
+          return await res.json();
+        })
+        .then((res) => {
+          logger.info(res);
+          return resolve(res);
+        })
+        .catch((error) => {
+          logger.error(error);
+          return reject(error);
+        }),
+    );
+  };
+  static delete = (options = { id: '', body: {} }) =>
+    new Promise((resolve, reject) =>
+      fetch(getApiBaseUrl({ id: options.id, endpoint }), {
+        method: 'DELETE',
+        headers: headersFactory(),
+        credentials: 'include',
+        body: payloadFactory(options.body),
+      })
+        .then(async (res) => {
+          return await res.json();
+        })
+        .then((res) => {
+          logger.info(res);
+          return resolve(res);
+        })
+        .catch((error) => {
+          logger.error(error);
+          return reject(error);
+        }),
+    );
+}
+export { CyberiaClientHintsService };