@underpostnet/cyberia 3.2.90 → 3.3.0

package/src/client/components/cyberia/FallbackWorldEngineCyberia.js

@@ -0,0 +1,368 @@
+/**
+ * Fallback World Engine — editor for the procedural fallback world's default items.
+ *
+ * The fallback world (src/api/cyberia-instance/cyberia-fallback-world.js) is
+ * generated in memory and never persisted, so it has no CyberiaInstance document
+ * to edit. This view is the trimmed-down counterpart of InstanceEngineCyberia:
+ * only the default-items section plus a reload trigger.
+ *
+ * The composed item set is staged on the engine process and shipped with the
+ * reload trigger — it is deliberately volatile (see cyberia-fallback-default-items.js),
+ * so an engine restart returns the world to pure code defaults.
+ */
+
+import { BtnIcon } from '../core/BtnIcon.js';
+import { Input } from '../core/Input.js';
+import { htmls, s } from '../core/VanillaJs.js';
+import { commonModeratorGuard } from '../core/CommonJs.js';
+import { NotificationManager } from '../core/NotificationManager.js';
+import { DropDown } from '../core/DropDown.js';
+import { CyberiaInstanceService } from '../../services/cyberia-instance/cyberia-instance.service.js';
+import { ObjectLayerService } from '../../services/object-layer/object-layer.service.js';
+import { DefaultCyberiaItems } from './SharedDefaultsCyberia.js';
+
+const dropdownValueKey = (value = '') => String(value).trim().replaceAll(' ', '-');
+const createDropdownOption = (value, onClick = () => {}, display = value, data = value) => ({
+  value,
+  display,
+  data,
+  onClick,
+});
+
+class FallbackWorldEngineCyberia {
+  static itemIdsDropdownId = 'fallback-world-engine-item-ids-dropdown';
+  static itemInventoryListId = 'fallback-world-engine-item-inventory-list';
+  // itemId → defaultPlayerInventory flag for the currently selected item ids.
+  static itemInventoryFlags = {};
+  // Ids the code defaults already ship in an entity's defaultObjectLayers.
+  // Selecting one and leaving it unchecked REMOVES it from those defaults, so
+  // the list flags them instead of letting a player lose their starting kit.
+  static entityDefaultItemIds = [];
+
+  // Current selection, read from the dropdown's `oncheckvalues` (always live —
+  // it is updated before `_renderSelectedBadges` runs, unlike `.value` which
+  // lags by one in the option-click path).
+  static getSelectedItemIds() {
+    const token = DropDown.Tokens[FallbackWorldEngineCyberia.itemIdsDropdownId];
+    if (!token) return [];
+    const fromChecks = Object.values(token.oncheckvalues || {})
+      .map((v) => v.data)
+      .filter(Boolean);
+    if (fromChecks.length > 0) return fromChecks;
+    return Array.isArray(token.value) ? token.value.filter(Boolean) : [];
+  }
+
+  /** Payload shape shared with CyberiaInstance.itemIds. */
+  static getItemIdsPayload() {
+    return FallbackWorldEngineCyberia.getSelectedItemIds().map((id) => ({
+      id,
+      defaultPlayerInventory: !!FallbackWorldEngineCyberia.itemInventoryFlags[id],
+    }));
+  }
+
+  // Render the per-item "Default Player Inventory" toggles for every selected
+  // item id. Kept in sync with the dropdown via a MutationObserver on its badge
+  // container (see render()).
+  static renderItemInventoryList(containerId = FallbackWorldEngineCyberia.itemInventoryListId) {
+    const container = s(`.${containerId}`);
+    if (!container) return;
+
+    const selected = FallbackWorldEngineCyberia.getSelectedItemIds();
+
+    // Drop flags for items no longer selected so the payload never carries them.
+    for (const key of Object.keys(FallbackWorldEngineCyberia.itemInventoryFlags)) {
+      if (!selected.includes(key)) delete FallbackWorldEngineCyberia.itemInventoryFlags[key];
+    }
+
+    if (selected.length === 0) {
+      htmls(
+        `.${containerId}`,
+        html`<div style="color:#888;font-size:12px;">
+          No item IDs selected — the fallback world runs on pure code defaults.
+        </div>`,
+      );
+      return;
+    }
+
+    let listHtml = '';
+    for (const itemId of selected) {
+      const isChecked = !!FallbackWorldEngineCyberia.itemInventoryFlags[itemId];
+      const checked = isChecked ? 'checked' : '';
+      const strips = !isChecked && FallbackWorldEngineCyberia.entityDefaultItemIds.includes(itemId);
+      listHtml += html`<div class="fl" style="border-bottom:1px solid #444;padding:4px 0;align-items:center;">
+        <div class="in fll" style="flex:1;font-size:12px;font-family:monospace;">
+          ${itemId}
+          ${strips
+            ? html`<span
+                style="color:#d90;font-size:11px;font-family:initial;margin-left:6px;"
+                title="This id is part of the code entity defaults. Left unchecked, it is removed from them."
+                ><i class="fa-solid fa-triangle-exclamation"></i> removes from entity defaults</span
+              >`
+            : ''}
+        </div>
+        <div class="in fll" style="display:flex;align-items:center;justify-content:flex-end;">
+          <label style="font-size:11px;cursor:pointer;display:flex;align-items:center;gap:5px;">
+            <input
+              type="checkbox"
+              class="fallback-world-engine-item-inv-checkbox"
+              data-item-id="${itemId}"
+              ${checked}
+              style="cursor:pointer;"
+            />
+            Default Player Inventory
+          </label>
+        </div>
+      </div>`;
+    }
+    htmls(`.${containerId}`, listHtml);
+
+    container.querySelectorAll('.fallback-world-engine-item-inv-checkbox').forEach((cb) => {
+      cb.onchange = () => {
+        FallbackWorldEngineCyberia.itemInventoryFlags[cb.dataset.itemId] = cb.checked;
+      };
+    });
+  }
+
+  static syncItemIdsDropdownSelection(itemIds = []) {
+    const dropdownId = FallbackWorldEngineCyberia.itemIdsDropdownId;
+    if (!DropDown.Tokens[dropdownId]) return;
+
+    // Accept both the `[{ id, defaultPlayerInventory }]` shape and a plain
+    // string[], matching what the fallback-world endpoint may return.
+    const normalized = (itemIds || [])
+      .map((entry) => (typeof entry === 'string' ? { id: entry, defaultPlayerInventory: false } : entry))
+      .filter((entry) => entry && entry.id);
+
+    DropDown.Tokens[dropdownId].value = [];
+    if (s(`.${dropdownId}`)) s(`.${dropdownId}`).value = [];
+    DropDown.Tokens[dropdownId].oncheckvalues = {};
+    htmls(`.dropdown-current-${dropdownId}`, '');
+    htmls(`.${dropdownId}-render-container`, '');
+
+    FallbackWorldEngineCyberia.itemInventoryFlags = {};
+    const ids = [];
+    for (const entry of normalized) {
+      const key = dropdownValueKey(entry.id);
+      DropDown.Tokens[dropdownId].oncheckvalues[key] = {
+        data: entry.id,
+        display: entry.id,
+        value: entry.id,
+      };
+      FallbackWorldEngineCyberia.itemInventoryFlags[entry.id] = !!entry.defaultPlayerInventory;
+      ids.push(entry.id);
+    }
+    DropDown.Tokens[dropdownId].value = [...ids];
+    if (s(`.${dropdownId}`)) s(`.${dropdownId}`).value = [...ids];
+    DropDown.Tokens[dropdownId]._renderSelectedBadges?.();
+    FallbackWorldEngineCyberia.renderItemInventoryList();
+  }
+
+  static async buildItemIdsDropdown() {
+    return await DropDown.instance({
+      id: FallbackWorldEngineCyberia.itemIdsDropdownId,
+      label: html`Object Layer Item IDs`,
+      data: [],
+      type: 'checkbox',
+      containerClass: 'inl',
+      excludeSelected: true,
+      serviceProvider: async (q) => {
+        const result = await ObjectLayerService.searchItemIds({ q });
+        if (result.status === 'success' && result.data?.itemIds) {
+          return result.data.itemIds.map((itemId) => createDropdownOption(itemId));
+        }
+        return [];
+      },
+    });
+  }
+
+  static async render(options = {}) {
+    const { appStore } = options;
+    const role = appStore?.Data?.user?.main?.model?.user?.role || 'guest';
+    const canMutate = commonModeratorGuard(role);
+    const idHotReloadUrl = 'fallback-world-engine-input-hot-reload-url';
+    const idItemIdsDropdown = FallbackWorldEngineCyberia.itemIdsDropdownId;
+    const idItemInventoryList = FallbackWorldEngineCyberia.itemInventoryListId;
+
+    setTimeout(async () => {
+      // Keep the per-item "Default Player Inventory" toggles in sync with the
+      // item-ids dropdown. Every add/remove/clear re-renders the dropdown badge
+      // container, so observing it is a reliable change hook (the dropdown
+      // exposes no onChange callback).
+      const itemBadgeContainer = s(`.dropdown-current-${idItemIdsDropdown}`);
+      if (itemBadgeContainer) {
+        const itemInventoryObserver = new MutationObserver(() => {
+          FallbackWorldEngineCyberia.renderItemInventoryList();
+        });
+        itemInventoryObserver.observe(itemBadgeContainer, { childList: true, subtree: true });
+      }
+
+      // Load whatever this engine process currently serves, so reopening the
+      // view shows the live set rather than an empty form.
+      try {
+        const result = await CyberiaInstanceService.getFallbackDefaultItems();
+        if (result?.status === 'success') {
+          FallbackWorldEngineCyberia.entityDefaultItemIds = result.data?.entityDefaultItemIds || [];
+          FallbackWorldEngineCyberia.syncItemIdsDropdownSelection(result.data?.itemIds || []);
+        }
+      } catch (error) {
+        NotificationManager.Push({ html: error.message, status: 'error' });
+      }
+      FallbackWorldEngineCyberia.renderItemInventoryList();
+
+      if (s(`.btn-fallback-world-engine-load-defaults`))
+        s(`.btn-fallback-world-engine-load-defaults`).onclick = () => {
+          // Seed from the canonical registry so an operator starts from the
+          // same list `import-default-items` creates ObjectLayers for. Ids the
+          // entity defaults already ship start checked: selecting them
+          // unchecked would strip them from those defaults, which is never what
+          // "load the defaults" is asking for.
+          const flags = Object.fromEntries(
+            FallbackWorldEngineCyberia.getItemIdsPayload().map((e) => [e.id, e.defaultPlayerInventory]),
+          );
+          FallbackWorldEngineCyberia.syncItemIdsDropdownSelection(
+            DefaultCyberiaItems.map((entry) => ({
+              id: entry.item.id,
+              defaultPlayerInventory:
+                flags[entry.item.id] ?? FallbackWorldEngineCyberia.entityDefaultItemIds.includes(entry.item.id),
+            })),
+          );
+        };
+
+      if (s(`.btn-fallback-world-engine-clear`))
+        s(`.btn-fallback-world-engine-clear`).onclick = () => {
+          FallbackWorldEngineCyberia.syncItemIdsDropdownSelection([]);
+        };
+
+      if (s(`.btn-fallback-world-engine-toggle-hot-reload`))
+        s(`.btn-fallback-world-engine-toggle-hot-reload`).onclick = () => {
+          const body = s(`.fallback-world-engine-hot-reload-body`);
+          const caret = s(`.fallback-world-engine-hot-reload-caret`);
+          if (body) body.classList.toggle('hide');
+          if (caret) {
+            caret.classList.toggle('fa-caret-right');
+            caret.classList.toggle('fa-caret-down');
+          }
+        };
+
+      const triggerHotReload = async (mode) => {
+        const buttons = [
+          s(`.btn-fallback-world-engine-hot-reload`),
+          s(`.btn-fallback-world-engine-hot-reload-incremental`),
+        ];
+        const statusSelector = `.fallback-world-engine-hot-reload-status`;
+        const serverUrl = s(`.${idHotReloadUrl}`)?.value?.trim();
+        if (!serverUrl) {
+          NotificationManager.Push({ html: 'Set the cyberia-server URL first.', status: 'warning' });
+          return;
+        }
+
+        for (const btn of buttons) if (btn) btn.disabled = true;
+        if (s(statusSelector))
+          htmls(statusSelector, html`<span style="color:#888;">Triggering ${mode} hot reload…</span>`);
+        try {
+          const result = await CyberiaInstanceService.fallbackHotReload({
+            body: { serverUrl, mode, itemIds: FallbackWorldEngineCyberia.getItemIdsPayload() },
+          });
+          if (result.status === 'error') {
+            NotificationManager.Push({ html: result.message, status: 'error' });
+            if (s(statusSelector)) htmls(statusSelector, html`<span style="color:#d66;">${result.message}</span>`);
+            return;
+          }
+          const { transport, durationMs, message, grpcError, itemIds } = result.data || {};
+          NotificationManager.Push({ html: `Hot reload via ${transport}: ${message}`, status: 'success' });
+          if (s(statusSelector))
+            htmls(
+              statusSelector,
+              html`<span style="color:#6b6;">
+                  via <b>${transport}</b> · ${durationMs}ms · ${(itemIds || []).length} default item(s) staged ·
+                  ${message} </span
+                >${grpcError ? html`<div style="color:#a80;">gRPC unavailable: ${grpcError}</div>` : ''}`,
+            );
+        } catch (error) {
+          NotificationManager.Push({ html: error.message, status: 'error' });
+          if (s(statusSelector)) htmls(statusSelector, html`<span style="color:#d66;">${error.message}</span>`);
+        } finally {
+          for (const btn of buttons) if (btn) btn.disabled = false;
+        }
+      };
+
+      if (s(`.btn-fallback-world-engine-hot-reload`))
+        s(`.btn-fallback-world-engine-hot-reload`).onclick = () => triggerHotReload('full');
+      if (s(`.btn-fallback-world-engine-hot-reload-incremental`))
+        s(`.btn-fallback-world-engine-hot-reload-incremental`).onclick = () => triggerHotReload('incremental');
+    });
+
+    return html`
+      <div class="in fallback-world-engine-container">
+        <div class="in section-mp" style="color:#888;font-size:12px;">
+          The fallback world is generated in memory and never persisted, so it has no instance document to edit. Items
+          selected here are staged on this engine process and applied when a cyberia-server reloads. They are volatile:
+          an engine restart returns the world to its code defaults.
+        </div>
+
+        <div class="in section-mp" style="margin-top: 10px;">
+          <div class="in input-label" style="font-size:14px;margin-bottom:5px;">Default Items</div>
+          ${await FallbackWorldEngineCyberia.buildItemIdsDropdown()}
+        </div>
+        <div class="in section-mp" style="margin-top: 5px;">
+          <div class="in input-label" style="font-size:13px;margin-bottom:5px;">Default Player Inventory</div>
+          <div class="in" style="color:#888;font-size:12px;margin-bottom:6px;">
+            Every selected id is resolved to an atlas at boot. Ids checked here are seeded into each new player's
+            inventory (inactive, never auto-equipped); unchecked ids are explicitly removed from the player's default
+            layers.
+          </div>
+          <div class="in ${idItemInventoryList}" style="max-height:200px;overflow-y:auto;"></div>
+          ${canMutate
+            ? html`<div class="in" style="display:flex;gap:5px;flex-wrap:wrap;margin-top:10px;">
+                ${await BtnIcon.instance({
+                  class: 'wfa btn-fallback-world-engine-load-defaults',
+                  label: html`<i class="fa-solid fa-list-check"></i> Load Canonical Defaults`,
+                })}
+                ${await BtnIcon.instance({
+                  class: 'wfa btn-fallback-world-engine-clear',
+                  label: html`<i class="fa-solid fa-eraser"></i> Clear Selection`,
+                })}
+              </div>`
+            : ''}
+        </div>
+
+        ${canMutate
+          ? html`<div class="in section-mp" style="margin-top: 10px;">
+              ${await BtnIcon.instance({
+                class: 'wfa btn-fallback-world-engine-toggle-hot-reload',
+                label: html`<i class="fa-solid fa-caret-right fallback-world-engine-hot-reload-caret"></i> Hot Reload`,
+              })}
+              <div class="in fallback-world-engine-hot-reload-body hide">
+                <div class="in" style="color:#888;font-size:12px;margin:5px 0;">
+                  Stages the items above on this engine, then rebuilds the world of a running cyberia-server so it
+                  re-fetches them. Tries the gRPC control service first and falls back to the REST endpoint. For a
+                  multi-instance deployment, append the variant sub-path so the trigger reaches the right world (e.g.
+                  <code>https://server.cyberiaonline.com/TEST</code>); the default world uses the bare origin.
+                </div>
+                ${await Input.instance({
+                  id: idHotReloadUrl,
+                  label: html`<i class="fa-solid fa-server"></i> Cyberia Server URL`,
+                  containerClass: 'in',
+                  placeholder: 'https://server.cyberiaonline.com/TEST',
+                  type: 'text',
+                })}
+                <div class="in" style="display:flex;gap:5px;flex-wrap:wrap;margin-top:5px;">
+                  ${await BtnIcon.instance({
+                    class: 'wfa btn-fallback-world-engine-hot-reload',
+                    label: html`<i class="fa-solid fa-rotate"></i> Trigger Hot Reload`,
+                  })}
+                  ${await BtnIcon.instance({
+                    class: 'wfa btn-fallback-world-engine-hot-reload-incremental',
+                    label: html`<i class="fa-solid fa-layer-group"></i> Incremental (assets only)`,
+                  })}
+                </div>
+                <div class="in fallback-world-engine-hot-reload-status" style="margin-top:5px;font-size:12px;"></div>
+              </div>
+            </div>`
+          : ''}
+      </div>
+    `;
+  }
+}
+
+export { FallbackWorldEngineCyberia };

package/src/client/components/cyberia-portal/AppShellCyberiaPortal.js

@@ -34,6 +34,7 @@ import { InstanceEngineCyberia } from '../cyberia/InstanceEngineCyberia.js';
 import { InstanceSelectionView } from '../cyberia/InstanceSelectionView.js';
 import { ActionEngineCyberia } from '../cyberia/ActionEngineCyberia.js';
 import { EntityEngineCyberia } from '../cyberia/EntityEngineCyberia.js';
+import { FallbackWorldEngineCyberia } from '../cyberia/FallbackWorldEngineCyberia.js';
 
 class AppShellCyberiaPortal {
   static Data = {};
@@ -288,6 +289,18 @@ class AppShellCyberiaPortal {
             handleContainerClass: 'handle-btn-container',
             tooltipHtml: await Badge.instance(buildBadgeToolTipMenuOption('cyberia-entity-engine')),
           })}
+          ${await BtnIcon.instance({
+            class: 'in wfa main-btn-menu main-btn-fallback-world-engine',
+            useMenuBtn: true,
+            label: renderMenuLabel({
+              icon: html`<img class="inl cyberia-menu-icon" src="${getProxyPath()}assets/ui-icons/engine.png" />`,
+              text: html`<span class="menu-label-text">${Translate.instance('fallback-world-engine')}</span>`,
+            }),
+            attrs: `data-id="fallback-world-engine"`,
+            tabHref: `${getProxyPath()}fallback-world-engine`,
+            handleContainerClass: 'handle-btn-container',
+            tooltipHtml: await Badge.instance(buildBadgeToolTipMenuOption('fallback-world-engine')),
+          })}
         </div>
       `,
       // htmlMainBody: async () => {
@@ -762,6 +775,26 @@ class AppShellCyberiaPortal {
       });
     });
 
+    EventsUI.onClick(`.main-btn-fallback-world-engine`, async () => {
+      const { barConfig } = await Themes[Css.currentTheme]();
+      await Modal.instance({
+        id: 'modal-fallback-world-engine',
+        route: 'fallback-world-engine',
+        barConfig,
+        title: renderViewTitle({
+          icon: html`<img class="inl cyberia-menu-icon-modal" src="${getProxyPath()}assets/ui-icons/engine.png" />`,
+          text: `<span class='inl cyberia-text-title-modal'>${Translate.instance('fallback-world-engine')}</span>`,
+        }),
+        html: async () => await FallbackWorldEngineCyberia.render({ appStore: AppStoreCyberiaPortal }),
+        handleType: 'bar',
+        maximize: true,
+        mode: 'view',
+        slideMenu: 'modal-menu',
+        RouterInstance,
+        observer: true,
+      });
+    });
+
     s(`.main-btn-admin`).onclick = () => {
       const { protocol, hostname } = window.location;
       return (location.href = `${protocol}//${hostname}/admin${['', 0][random(0, 1)]}`);

package/src/client/components/cyberia-portal/RouterCyberiaPortal.js

@@ -56,6 +56,10 @@ class RouterCyberiaPortal {
         title: 'cyberia-entity-engine',
         render: () => s(`.main-btn-cyberia-entity-engine`).click(),
       },
+      '/fallback-world-engine': {
+        title: 'fallback-world-engine',
+        render: () => s(`.main-btn-fallback-world-engine`).click(),
+      },
       '/instance-selection': {
         title: 'instance-selection',
         render: () => s(`.main-btn-instance-selection`).click(),

package/src/client/components/cyberia-portal/TranslateCyberiaPortal.js

@@ -30,6 +30,10 @@ class TranslateCyberiaPortal {
       en: 'Cyberia Entity Engine',
       es: 'Cyberia Entity Engine',
     };
+    Translate.Data['fallback-world-engine'] = {
+      en: 'Fallback World Engine',
+      es: 'Fallback World Engine',
+    };
     Translate.Data['instance-selection'] = {
       en: 'Select World',
       es: 'Seleccionar Mundo',

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

@@ -193,7 +193,7 @@ The render frame runs at vsync. Inside one render frame, `cyberia-client` perfor
 
 1. Poll any pending optional client-hints fetch.
 2. Capture raw input → build typed input command (`kind`, `clientTick`, `sequence`, payload) → apply to prediction → send on the wire.
-3. Reconcile against the latest snapshot: drop input commands ≤ `lastAckedSequence`, rewind self to authoritative position, replay unacked commands.
+3. Reconcile against the latest snapshot: difference the authoritative position against the position this client predicted for that same tick, shift the prediction trail by that error, and — once `moveAck` covers the newest command — adopt the server's own `targetPos` and route as the walk destination.
 4. Fixed-timestep simulation: while accumulator ≥ `tickDuration`, advance prediction one tick.
 5. Interpolation: compute remote-entity view positions at `renderTick`.
 6. Render. Read view models; never mutate world state.
@@ -236,7 +236,20 @@ WS frame (binary)  →  decode  →  typed InputCommand{kind, clientTick, sequen
                        authoritative world state
 ```
 
-`InputCommand.Sequence` is monotonic per client. The server tracks the highest applied sequence per player; `phaseReplication` writes it into every snapshot header. The client drops acknowledged input commands from its prediction replay buffer using this value.
+`InputCommand.Sequence` is monotonic per client. Every snapshot carries two acknowledgements of it, and they are not interchangeable:
+
+| Field     | Meaning                                                       | Client use                                                                       |
+| --------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `ack`     | Highest sequence **received** for this player.                 | Retires commands from the prediction buffer.                                      |
+| `moveAck` | Highest `PlayerAction` sequence that **re-planned movement**.  | Gates adoption of the authoritative `targetPos` / `path`.                         |
+
+**Movement re-plans once per player per tick, and nothing else throttles it.** Handlers record the tap's destination; `phaseInput` runs one A* per player after the queue is drained. Taps that land in the same tick describe the same instant, so only the newest is planned — the rest were superseded before they could mean anything. That coalescing is the only bound on pathfinder cost.
+
+This is why the two acknowledgements diverge: a superseded tap is acked on arrival and never planned, so `self.path` and `self.targetPos` can still describe an earlier command. A client that adopted the route on `ack` alone would turn back toward the abandoned target — worst during rapid changes of direction, where it reads as input lag and as a walk that sets off the wrong way.
+
+Skills are not coalesced: they fire on every accepted tap, so the uplink carries every tap and the inbound rate limiter (`DefaultMessageRate`, 30/s) is what bounds the stream.
+
+The client predicts every tap immediately and never waits on a cadence. `self.actionCooldownMs` is the skill-trigger period only; keyboard steering paces its *refresh* by it, while a change of heading emits at once.
 
 ---
 
@@ -271,7 +284,8 @@ Every Cyberia document uses the same terms. Aliases are not permitted.
 | **tick rate**             | Simulation Hz on `cyberia-server`.                                                                                                                                                                                                                                                                         |
 | **snapshot**              | AOI-filtered world view at one tick for one player.                                                                                                                                                                                                                                                        |
 | **prediction**            | Optimistic local apply of input commands to the predicted self entity.                                                                                                                                                                                                                                     |
-| **reconciliation**        | Drop acknowledged inputs, rewind self to authoritative position, replay unacked inputs.                                                                                                                                                                                                                    |
+| **reconciliation**        | Correct prediction by the error measured at one tick: authoritative position minus the position predicted for that tick. Input is a destination, not a per-tick impulse, so the client keeps walking toward the `targetPos` that `moveAck` confirms, rather than replaying a command log.                   |
+| **move coalescing**       | One movement re-plan per player per tick, from the newest tap of that tick. The only bound on pathfinder cost, and the reason `moveAck` trails `ack`.                                                                                                                                                       |
 | **display smoothing**     | Per-render-frame exponential lerp from the discrete predicted self position to a continuous on-screen position. Decouples the visible main player from sim-tick boundaries.                                                                                                                                |
 | **interpolation**         | Render-time smoothing of remote entities, sampled from snapshot history.                                                                                                                                                                                                                                   |
 | **authoritative server**  | `cyberia-server`. Sole authority on world state.                                                                                                                                                                                                                                                           |

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

@@ -157,7 +157,7 @@ Per player:
 [9..10]  u16  entityCount entity blocks that follow
 ```
 
-The `tick` and `lastAcked` fields are how the client reconciles its predicted self with authoritative state. The client drops input commands with `sequence ≤ lastAcked` from its replay buffer, then rewinds and replays the rest.
+The `tick` and `lastAcked` fields are how the client reconciles its predicted self with authoritative state. `lastAcked` proves arrival, not acceptance: movement re-plans once per player per tick from the newest tap of that tick, so a tap superseded within its own tick is acknowledged and never planned. The snapshot therefore carries a second acknowledgement, `moveAck` — the highest `PlayerAction` sequence that actually re-planned movement — and the client adopts the authoritative `targetPos` / `path` only once `moveAck` covers its newest command. See ARCHITECTURE.md § Input replication.
 
 Other message types (init data, FCT) carry their own headers and are not part of the per-tick replication stream.
 

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

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

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

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

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

@@ -96,6 +96,46 @@ class CyberiaInstanceService {
           return reject(error);
         }),
     );
+  /** Fallback-world default items currently staged on the engine process. */
+  static getFallbackDefaultItems = () =>
+    new Promise((resolve, reject) =>
+      fetch(getApiBaseUrl({ id: 'fallback-world/default-items', endpoint }), {
+        method: 'GET',
+        headers: headersFactory(),
+        credentials: 'include',
+      })
+        .then(async (res) => res.json())
+        .then((res) => {
+          logger.info(res);
+          return resolve(res);
+        })
+        .catch((error) => {
+          logger.error(error);
+          return reject(error);
+        }),
+    );
+  /**
+   * Stage the fallback world's default items and reload a running cyberia-server
+   * (moderator/admin). The items ride along with the trigger — nothing is persisted.
+   */
+  static fallbackHotReload = (options = { body: {} }) =>
+    new Promise((resolve, reject) =>
+      fetch(getApiBaseUrl({ id: 'fallback-world/hot-reload', endpoint }), {
+        method: 'POST',
+        headers: headersFactory(),
+        credentials: 'include',
+        body: JSON.stringify(options.body ?? {}),
+      })
+        .then(async (res) => res.json())
+        .then((res) => {
+          logger.info(res);
+          return resolve(res);
+        })
+        .catch((error) => {
+          logger.error(error);
+          return reject(error);
+        }),
+    );
   static portalConnect = (options = { id: '' }) =>
     new Promise((resolve, reject) =>
       fetch(getApiBaseUrl({ id: `${options.id}/portal-connect`, endpoint }), {

package/src/client/services/object-layer/object-layer.management.js

@@ -293,7 +293,7 @@ class ObjectLayerManagement {
         width: 160,
         editable: false,
         sortable: false,
-        filter: false,
+        filter: 'agTextColumnFilter',
       },
       {
         field: 'cid',
@@ -302,7 +302,7 @@ class ObjectLayerManagement {
         cellRenderer: CidRenderer,
         editable: false,
         sortable: false,
-        filter: false,
+        filter: 'agTextColumnFilter',
       },
       {
         field: 'data.render.cid',
@@ -311,7 +311,7 @@ class ObjectLayerManagement {
         cellRenderer: AtlasCidRenderer,
         editable: false,
         sortable: false,
-        filter: false,
+        filter: 'agTextColumnFilter',
       },
       {
         field: 'data.render.metadataCid',
@@ -320,7 +320,7 @@ class ObjectLayerManagement {
         cellRenderer: MetadataCidRenderer,
         editable: false,
         sortable: false,
-        filter: false,
+        filter: 'agTextColumnFilter',
       },
       {
         field: 'frame08',