@vgai/engine 0.5.39 → 0.5.41

package/src/ai/navigation.ts

@@ -67,6 +67,37 @@ export interface NavMeshBuildParams {
   mergeRegionArea?: number | undefined;
 }
 
+/** One authored Detour polygon. Vertex order is clockwise in the engine's XZ world basis. */
+export interface NavMeshPolygon {
+  readonly vertices: readonly number[];
+  readonly flags?: number | undefined;
+  readonly area?: number | undefined;
+}
+
+/** Detail-row offsets/counts for the polygon at the same index. */
+export interface NavMeshDetailMesh {
+  readonly vertexBase: number;
+  readonly triangleBase: number;
+  readonly vertexCount: number;
+  readonly triangleCount: number;
+}
+
+/**
+ * An already-authored polygon mesh, before Detour's ABI-specific tile serialization.
+ *
+ * This is the direct-data sibling of {@link buildFromMeshes}: use it when a source ecosystem has
+ * already baked navigation. Re-rasterizing an editor bake is lossy—the polygon borders and detail
+ * heights are the output, not another input mesh.
+ */
+export interface NavMeshPolygonData {
+  readonly vertices: readonly (readonly [number, number, number])[];
+  readonly polygons: readonly NavMeshPolygon[];
+  readonly detailMeshes: readonly NavMeshDetailMesh[];
+  readonly detailVertices: readonly (readonly [number, number, number])[];
+  /** Three local vertex indices plus Detour edge flags; all four values are uint8. */
+  readonly detailTriangles: readonly (readonly [number, number, number, number])[];
+}
+
 let wasmInitialized = false;
 
 export async function initNavigation(): Promise<void> {
@@ -103,24 +134,47 @@ function reverseTriangleWinding(geometry: BufferGeometry): void {
   index.needsUpdate = true;
 }
 
+/** Signed world-up area across a geometry's triangles. Closed obstacle meshes cancel to zero;
+ * broad walkable surfaces retain the winding Recast uses for its slope test. */
+function upwardTriangleArea(geometry: BufferGeometry): number {
+  const position = geometry.getAttribute('position');
+  const index = geometry.getIndex();
+  const vertexAt = (offset: number): number => index?.getX(offset) ?? offset;
+  let area = 0;
+  const count = index?.count ?? position.count;
+  for (let triangle = 0; triangle + 2 < count; triangle += 3) {
+    const a = vertexAt(triangle);
+    const b = vertexAt(triangle + 1);
+    const c = vertexAt(triangle + 2);
+    const ux = position.getX(b) - position.getX(a);
+    const uz = position.getZ(b) - position.getZ(a);
+    const vx = position.getX(c) - position.getX(a);
+    const vz = position.getZ(c) - position.getZ(a);
+    area += uz * vx - ux * vz;
+  }
+  return area;
+}
+
 function recastInputMeshes(meshes: Mesh[]): {
   readonly meshes: Mesh[];
   readonly temporaryGeometries: BufferGeometry[];
 } {
   const temporaryGeometries: BufferGeometry[] = [];
-  const mirroredGeometries = new WeakMap<BufferGeometry, BufferGeometry>();
-  const geometryForMatrix = (source: BufferGeometry, matrix: Matrix4): BufferGeometry => {
-    if (matrix.determinant() >= 0) return source;
-    const cached = mirroredGeometries.get(source);
-    if (cached !== undefined) return cached;
-    const geometry = source.clone();
-    reverseTriangleWinding(geometry);
-    mirroredGeometries.set(source, geometry);
-    temporaryGeometries.push(geometry);
-    return geometry;
-  };
   const proxyAt = (geometry: BufferGeometry, matrix: Matrix4): Mesh => {
-    const proxy = new Mesh(geometryForMatrix(geometry, matrix));
+    if (matrix.determinant() < 0) {
+      // Bake the complete mirrored transform into this clone. Passing a negative-determinant
+      // matrix through `@recast-navigation/three` after reversing the source indices still lets
+      // its geometry merge recalculate the triangle orientation from that matrix. An identity
+      // proxy over already-world-space vertices has exactly one winding decision.
+      const transformed = geometry.clone().applyMatrix4(matrix);
+      // A negative determinant alone is insufficient: reflecting across a plane's normal axis
+      // leaves every vertex in place, while reflecting an in-plane axis reverses its triangles.
+      // Inspect the transformed walkable area instead of guessing from the 3D transform.
+      if (upwardTriangleArea(transformed) < 0) reverseTriangleWinding(transformed);
+      temporaryGeometries.push(transformed);
+      return new Mesh(transformed);
+    }
+    const proxy = new Mesh(geometry);
     // The proxy has no parent, so its local matrix is the source mesh's complete world matrix.
     // The recast bridge calls updateMatrixWorld() itself; disabling auto-update preserves it.
     proxy.matrixAutoUpdate = false;
@@ -148,6 +202,224 @@ function recastInputMeshes(meshes: Mesh[]): {
   return { meshes: corrected, temporaryGeometries };
 }
 
+const NAV_MESH_SET_MAGIC = 0x4d53_4554;
+const NAV_MESH_SET_VERSION = 1;
+const DETOUR_NAV_MESH_MAGIC = 0x444e_4156;
+const DETOUR_NAV_MESH_VERSION = 7;
+
+function nextPowerOfTwo(value: number): number {
+  let result = 1;
+  while (result < value) result *= 2;
+  return result;
+}
+
+/** Serialize portable polygon/detail arrays as one ordinary Detour tile. */
+function polygonNavMeshData(data: NavMeshPolygonData, params?: NavMeshBuildParams): Uint8Array {
+  const vertexCount = data.vertices.length;
+  const polygonCount = data.polygons.length;
+  if (vertexCount === 0 || polygonCount === 0) {
+    throw new Error('NavMeshManager.buildFromPolygons: vertices and polygons must be non-empty');
+  }
+  if (vertexCount > 0xffff) {
+    throw new Error(
+      `NavMeshManager.buildFromPolygons: ${vertexCount} vertices exceed Detour's uint16 tile index`,
+    );
+  }
+  if (data.detailMeshes.length !== polygonCount) {
+    throw new Error(
+      `NavMeshManager.buildFromPolygons: ${polygonCount} polygons require the same number of detail rows`,
+    );
+  }
+
+  const neighbours = data.polygons.map((polygon) => polygon.vertices.map(() => 0));
+  const edges = new Map<string, readonly [number, number]>();
+  let maxLinkCount = 0;
+  for (let polygonIndex = 0; polygonIndex < polygonCount; polygonIndex += 1) {
+    const polygon = data.polygons[polygonIndex] as NavMeshPolygon;
+    if (polygon.vertices.length < 3 || polygon.vertices.length > 6) {
+      throw new Error(
+        `NavMeshManager.buildFromPolygons: polygon ${polygonIndex} has ` +
+          `${polygon.vertices.length} vertices; Detour permits 3..6`,
+      );
+    }
+    maxLinkCount += polygon.vertices.length;
+    for (let edgeIndex = 0; edgeIndex < polygon.vertices.length; edgeIndex += 1) {
+      const from = polygon.vertices[edgeIndex] as number;
+      const to = polygon.vertices[(edgeIndex + 1) % polygon.vertices.length] as number;
+      if (
+        !Number.isInteger(from) ||
+        !Number.isInteger(to) ||
+        from < 0 ||
+        to < 0 ||
+        from >= vertexCount ||
+        to >= vertexCount
+      ) {
+        throw new Error(
+          `NavMeshManager.buildFromPolygons: polygon ${polygonIndex} references an invalid vertex`,
+        );
+      }
+      const directed = `${from},${to}`;
+      if (edges.has(directed)) {
+        throw new Error(
+          `NavMeshManager.buildFromPolygons: directed edge ${directed} occurs more than once`,
+        );
+      }
+      const reverse = edges.get(`${to},${from}`);
+      if (reverse === undefined) {
+        edges.set(directed, [polygonIndex, edgeIndex]);
+      } else {
+        const [otherPolygon, otherEdge] = reverse;
+        neighbours[polygonIndex]![edgeIndex] = otherPolygon + 1;
+        neighbours[otherPolygon]![otherEdge] = polygonIndex + 1;
+      }
+    }
+  }
+
+  for (let polygonIndex = 0; polygonIndex < polygonCount; polygonIndex += 1) {
+    const row = data.detailMeshes[polygonIndex] as NavMeshDetailMesh;
+    if (
+      row.vertexBase < 0 ||
+      row.vertexCount < 0 ||
+      row.vertexBase + row.vertexCount > data.detailVertices.length ||
+      row.triangleBase < 0 ||
+      row.triangleCount < 0 ||
+      row.triangleBase + row.triangleCount > data.detailTriangles.length ||
+      row.vertexCount > 0xff ||
+      row.triangleCount > 0xff
+    ) {
+      throw new Error(
+        `NavMeshManager.buildFromPolygons: polygon ${polygonIndex} has an invalid detail row`,
+      );
+    }
+  }
+  for (const triangle of data.detailTriangles) {
+    if (triangle.some((value) => !Number.isInteger(value) || value < 0 || value > 0xff)) {
+      throw new Error(
+        'NavMeshManager.buildFromPolygons: detail triangles must contain uint8 values',
+      );
+    }
+  }
+
+  const boundsMin = [Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY];
+  const boundsMax = [Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY];
+  for (const vertex of [...data.vertices, ...data.detailVertices]) {
+    for (let component = 0; component < 3; component += 1) {
+      const value = vertex[component] as number;
+      if (!Number.isFinite(value)) {
+        throw new Error('NavMeshManager.buildFromPolygons: every vertex component must be finite');
+      }
+      boundsMin[component] = Math.min(boundsMin[component] as number, value);
+      boundsMax[component] = Math.max(boundsMax[component] as number, value);
+    }
+  }
+
+  // Detour's in-memory structs are emitted in its stable 32-bit serialized layout. `importNavMesh`
+  // owns the ABI boundary and recreates live WASM objects from these ordinary bytes.
+  const headerBytes = 100;
+  const polygonBytes = 32;
+  const linkBytes = 12;
+  const detailMeshBytes = 12;
+  const detailTriangleBytes = 4;
+  const tileBytes =
+    headerBytes +
+    vertexCount * 12 +
+    polygonCount * polygonBytes +
+    maxLinkCount * linkBytes +
+    polygonCount * detailMeshBytes +
+    data.detailVertices.length * 12 +
+    data.detailTriangles.length * detailTriangleBytes;
+  const bytes = new Uint8Array(48 + tileBytes);
+  const view = new DataView(bytes.buffer);
+  let offset = 0;
+  const uint8 = (value: number): void => {
+    view.setUint8(offset, value);
+    offset += 1;
+  };
+  const uint16 = (value: number): void => {
+    view.setUint16(offset, value, true);
+    offset += 2;
+  };
+  const uint32 = (value: number): void => {
+    view.setUint32(offset, value, true);
+    offset += 4;
+  };
+  const int32 = (value: number): void => {
+    view.setInt32(offset, value, true);
+    offset += 4;
+  };
+  const float32 = (value: number): void => {
+    view.setFloat32(offset, value, true);
+    offset += 4;
+  };
+
+  const maxPolygons = nextPowerOfTwo(polygonCount);
+  uint32(NAV_MESH_SET_MAGIC);
+  uint32(NAV_MESH_SET_VERSION);
+  uint32(1);
+  for (const value of boundsMin) float32(value);
+  float32(Math.max((boundsMax[0] as number) - (boundsMin[0] as number), Number.EPSILON));
+  float32(Math.max((boundsMax[2] as number) - (boundsMin[2] as number), Number.EPSILON));
+  uint32(1);
+  uint32(maxPolygons);
+  // With one tile, Detour's first valid salt occupies the bits above maxPolygons.
+  uint32(maxPolygons);
+  uint32(tileBytes);
+
+  uint32(DETOUR_NAV_MESH_MAGIC);
+  uint32(DETOUR_NAV_MESH_VERSION);
+  int32(0);
+  int32(0);
+  int32(0);
+  uint32(0);
+  uint32(polygonCount);
+  uint32(vertexCount);
+  uint32(maxLinkCount);
+  uint32(polygonCount);
+  uint32(data.detailVertices.length);
+  uint32(data.detailTriangles.length);
+  uint32(0);
+  uint32(0);
+  uint32(polygonCount);
+  const defaults = DEFAULTS.navigation;
+  float32(params?.walkableHeight ?? defaults.walkableHeight);
+  float32(params?.walkableRadius ?? defaults.walkableRadius);
+  float32(params?.walkableClimb ?? defaults.walkableClimb);
+  for (const value of boundsMin) float32(value);
+  for (const value of boundsMax) float32(value);
+  float32(1 / (params?.cellSize ?? defaults.cellSize));
+
+  for (const vertex of data.vertices) for (const value of vertex) float32(value);
+  for (let polygonIndex = 0; polygonIndex < polygonCount; polygonIndex += 1) {
+    const polygon = data.polygons[polygonIndex] as NavMeshPolygon;
+    uint32(0xffff_ffff);
+    for (let index = 0; index < 6; index += 1) uint16(polygon.vertices[index] ?? 0);
+    for (let index = 0; index < 6; index += 1) {
+      uint16(neighbours[polygonIndex]?.[index] ?? 0);
+    }
+    uint16(polygon.flags ?? 1);
+    uint8(polygon.vertices.length);
+    uint8((polygon.area ?? 0) & 0x3f);
+  }
+  // `dtNavMesh::addTile` turns this zeroed capacity into its free-list, then populates the
+  // internal links from the polygon neighbour indices above.
+  offset += maxLinkCount * linkBytes;
+  for (const row of data.detailMeshes) {
+    uint32(row.vertexBase);
+    uint32(row.triangleBase);
+    uint8(row.vertexCount);
+    uint8(row.triangleCount);
+    uint16(0);
+  }
+  for (const vertex of data.detailVertices) for (const value of vertex) float32(value);
+  for (const triangle of data.detailTriangles) for (const value of triangle) uint8(value);
+  if (offset !== bytes.length) {
+    throw new Error(
+      `NavMeshManager.buildFromPolygons: encoded ${offset} bytes into a ${bytes.length}-byte allocation`,
+    );
+  }
+  return bytes;
+}
+
 export class NavMeshManager {
   private navMesh: NavMesh | null = null;
   private query: NavMeshQuery | null = null;
@@ -187,7 +459,10 @@ export class NavMeshManager {
     try {
       result =
         params?.tiled === true || input.meshes.length > 256 || triangleCount > 10_000
-          ? threeToTiledNavMesh(input.meshes, { ...config, tileSize: params?.tileSize ?? 256 })
+          ? threeToTiledNavMesh(input.meshes, {
+              ...config,
+              tileSize: params?.tileSize ?? 256,
+            })
           : threeToSoloNavMesh(input.meshes, config);
     } finally {
       for (const geometry of input.temporaryGeometries) geometry.dispose();
@@ -202,6 +477,16 @@ export class NavMeshManager {
     return true;
   }
 
+  /** Load an authored polygon/detail mesh directly, without a second rasterization. */
+  buildFromPolygons(data: NavMeshPolygonData, params?: NavMeshBuildParams): boolean {
+    try {
+      this.loadFromData(polygonNavMeshData(data, params));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
   /**
    * Destroy all live recast handles (crowd, query, navmesh) and dispose the
    * debug helper. Recast objects live on the WASM heap and are NOT GC'd —

package/src/ecs/user-data.ts

@@ -193,6 +193,10 @@ export interface UserDataSchema {
     readonly name: string;
     readonly title: string;
   };
+  /** Project-owned identity used to join authored hierarchy rows across adapter roots. */
+  authoringHierarchyId: string;
+  /** Source-owned sibling ordinal used when hierarchy rows cross native roots. */
+  authoringHierarchyOrder: number;
   editorHelper: boolean;
   editorHelperType: EditorHelperType;
   editorIcon: boolean;
@@ -249,6 +253,8 @@ export const UserDataKeys = {
   vgaiBodyOwner: 'vgaiBodyOwner',
   authoringComponent: 'authoringComponent',
   authoringDocument: 'authoringDocument',
+  authoringHierarchyId: 'authoringHierarchyId',
+  authoringHierarchyOrder: 'authoringHierarchyOrder',
   editorHelper: 'editorHelper',
   editorHelperType: 'editorHelperType',
   editorIcon: 'editorIcon',

package/src/runtime/debug-registry.ts

@@ -452,6 +452,8 @@ function warnOnce(
 export function createDebugRegistry(opts: {
   getTick(): number;
   getSimT(): number;
+  /** The host loop's configured simulation step, when a real Game owns this registry. */
+  getFixedDt?(): number;
   getDefaultRootId?(): string | null;
   getLoopLiveness?(): GameLoopLiveness;
 }): DebugRegistry {
@@ -540,6 +542,7 @@ export function createDebugRegistry(opts: {
       simSeconds: opts.getSimT(),
       tick: opts.getTick(),
       loopLiveness: opts.getLoopLiveness?.() ?? null,
+      ...(opts.getFixedDt === undefined ? {} : { fixedDt: opts.getFixedDt() }),
     }),
     tier: 'observable',
     worldId: '__engine__',

package/src/runtime/game.ts

@@ -122,8 +122,9 @@ export type AdapterSurface = AdapterSurfaceLeaf;
  * A world's per-phase frame hooks.
  * Populated on a `RootInstance` only for first-party mounts — an opaque/
  * foreign mount has no phase-partitioned entry point, so it stays
- * `undefined` and the Game's frame executor (`GameInternal.runFrame`) falls
- * back to calling its single `mounted.update(dt)` once per substep instead.
+ * `undefined` and the Game's frame executor falls back to its single
+ * `mounted.update(dt)`. The mount's `updateCadence` chooses fixed-substep
+ * (the default) or display-rate dispatch.
  */
 export interface RootFrameHooks {
   /** Run this world's engine systems + component ticks + world-bound game
@@ -639,8 +640,8 @@ export interface Game {
    * sway, a cosmetic bob. It is NOT a gameplay hook: it can fire twice
    * between two fixed substeps (120 Hz display, 60 Hz sim) and zero times
    * across a `runTicks` fast-forward, so anything that must be deterministic
-   * belongs in a fixed phase (`ctx.systems.add`, a `useFrame` hook, a
-   * `useFrame`) instead.
+   * belongs in a fixed engine phase (`ctx.systems.add`) instead. Ecosystem
+   * presentation hooks such as R3F's `useFrame` share this display clock.
    *
    * Reached from game code as `ctx.game?.onRenderStep(...)`. Returns an
    * unsubscribe function; pass `opts.signal` to unsubscribe with the same
@@ -685,13 +686,17 @@ export interface GameInternal extends Game {
    * for world in roots:                       // after ALL phases
    *   if world.mounted.drivesOwnLoop: continue
    *   if world.frame: world.frame.endFrame?.()
-   *   else: world.mounted.update?.(dt)          // opaque world fallback
+   *   else if updateCadence != 'display' OR render phases are included:
+   *     world.mounted.update?.(dt)              // opaque world fallback
    * ```
    *
    * A single first-party world and its direct `mounted.update(dt)` entry run
    * the same `SystemRunner` and `postFrame` work. A `drivesOwnLoop` world is
    * never ticked here. An opaque host-driven world (no `frame`) gets exactly
-   * one `update(dt)` call per substep, after the phase loop.
+   * one `update(dt)` call per substep after the phase loop by default. A
+   * display-cadence opaque world is withheld when `skipRenderPhases` is true;
+   * the matching host calls it once from {@link runRenderFrame}. A direct
+   * `runFrame` with render phases included still calls it once.
    *
    * D10/T7.6 play-state addendum: when `Game.play.paused` is true, every
    * `pausable` (and non-`drivesOwnLoop`) world skips every phase EXCEPT
@@ -729,6 +734,8 @@ export interface GameInternal extends Game {
    *   for world in roots (declaration order):
    *     if world.mounted.drivesOwnLoop: continue
    *     world.frame?.runPhase(phase, frozen ? 0 : displayDt)
+   * for opaque world with updateCadence == 'display':
+   *   world.mounted.update?.(frozen ? 0 : displayDt)
    * ```
    *
    * Advances NOTHING: no `tick`, no `simT`, no sim-clock flush, no state-bridge
@@ -913,6 +920,7 @@ export function createGame(opts: {
   const debugRegistry = createDebugRegistry({
     getTick: () => tick,
     getSimT: () => simT,
+    getFixedDt: () => opts.loop.fixedDt,
     // D15/T-D15.5 — "the manifest's first/default world" for the debug
     // registry's world-addressed input-target surface. Every
     // first-party root now registers the SAME game-owned InputManager, but the
@@ -1080,7 +1088,12 @@ export function createGame(opts: {
           );
         }
       }
-      const audio = world.mounted.systems?.audio;
+      // A native entry's static `systems` export is this root's primary
+      // declaration surface. `computeSystemAdapters()` already gives it
+      // precedence over a substrate-seeded mounted adapter; pause must read
+      // the same source or a valid entry-declared audio graph is visible to
+      // the editor yet paradoxically reported as ungateable here.
+      const audio = declaredSystemAdapters.get(world.id)?.audio ?? world.mounted.systems?.audio;
       if (audio) {
         audio.setMuted(next);
       } else if (
@@ -1287,10 +1300,21 @@ export function createGame(opts: {
           // Checklist item 2: same isolation for the opaque-world fallback —
           // one foreign mount's `update` throwing must not starve its
           // siblings' `endFrame`/`update` calls this same loop.
-          try {
-            world.mounted.update?.(dt);
-          } catch (err) {
-            console.error(`[game] world "${world.id}" (kind: ${world.kind}) update() threw:`, err);
+          // A display-cadence opaque update is the root's indivisible native
+          // presentation (R3F `advance()` is callbacks + draw). The real
+          // rAF host withholds render phases from EVERY fixed catch-up step;
+          // withhold this update beside them, then run it once in
+          // `runRenderFrameImpl`. A direct/offline `runFrame` includes render
+          // phases and therefore still advances the root exactly once.
+          if (!(skipRenderPhases && world.mounted.updateCadence === 'display')) {
+            try {
+              world.mounted.update?.(dt);
+            } catch (err) {
+              console.error(
+                `[game] world "${world.id}" (kind: ${world.kind}) update() threw:`,
+                err,
+              );
+            }
           }
         }
       }
@@ -1389,6 +1413,27 @@ export function createGame(opts: {
       profiler.endPhase(phase);
     }
 
+    // An opaque display-cadence root cannot expose phase hooks because its
+    // native advance is inseparable. It still belongs to THIS presentation
+    // frame, once — never to every fixed catch-up substep that preceded it.
+    // A frozen world redraws at dt=0, preserving the established pause rule.
+    for (let i = 0; i < n; i++) {
+      const world = roots[i]!;
+      if (world.disposed) continue;
+      if (world.mounted.drivesOwnLoop) continue;
+      if (world.frame) continue;
+      if (world.mounted.updateCadence !== 'display') continue;
+      const frozen = paused && world.pausable;
+      try {
+        world.mounted.update?.(frozen ? 0 : displayDt);
+      } catch (err) {
+        console.error(
+          `[game] world "${world.id}" (kind: ${world.kind}) update() threw (display frame):`,
+          err,
+        );
+      }
+    }
+
     profiler.endFrame();
     if (rngTrapEnabled) rngTrap.disable();
   }

package/src/world3d-react/frame-delta.ts

@@ -0,0 +1,25 @@
+/**
+ * The exact host-owned delta for the synchronous R3F frame currently being dispatched.
+ *
+ * Fiber's `frameloop: 'never'` API accepts an absolute timestamp and reconstructs the frame
+ * delta by subtracting its previous timestamp. Once that timestamp is large enough, ordinary
+ * floating-point cancellation can turn an exact host `1 / 60` into either adjacent double. The
+ * host still owns the original exact `dt`; adapter-boundary runtimes that must reproduce another
+ * engine's clock can read it here instead of mistaking Fiber's reconstruction residue for game
+ * time. The seat exists only for the synchronous `advance(...)` call and is cleared immediately
+ * afterwards, so an async consumer can never read a stale frame.
+ */
+
+const hostFrameDeltas = new WeakMap<object, number>();
+
+export function setHostFrameDelta(state: object, delta: number): void {
+  hostFrameDeltas.set(state, delta);
+}
+
+export function clearHostFrameDelta(state: object): void {
+  hostFrameDeltas.delete(state);
+}
+
+export function hostFrameDelta(state: object, fiberDelta: number): number {
+  return hostFrameDeltas.get(state) ?? fiberDelta;
+}

package/src/world3d-react/r3f-root-factory.tsx

@@ -60,6 +60,7 @@ import { getDebugRegistry } from '../runtime/debug-registry';
 import { devBuildEnabled } from '../runtime/dev-build';
 import { DEFAULT_INPUT_MAP_PATH, wireGameInputSeams } from '../runtime/game-input-seams';
 import type { AdapterSurfaceFactory } from '../runtime/mount-game';
+import { clearHostFrameDelta, setHostFrameDelta } from './frame-delta';
 
 /** The slice of `WebGLRenderer.info` the vitals reporter reads. Declared
  *  structurally rather than imported from `three`, per this module's own
@@ -347,11 +348,10 @@ function threeWorldAdapter(id: string, component: ComponentType): RootAdapter {
       if (renderDebugWiring) systemAdapters.renderDebug = renderDebugWiring.adapter;
 
       // The engine drives every `useFrame` through the mounted world's
-      // `update(dt)` hook, never off a raw host-loop callback. That is the
-      // whole pause story: `runFrameImpl` (`runtime/game.ts`) calls
-      // `mounted.update?.(dt)` per substep for a host-driven world and SKIPS
-      // it while that world is frozen, and `Game.play.step()` ticks it exactly
-      // once.
+      // `update(dt)` hook, never off a raw Fiber loop. This mount declares
+      // that indivisible Fiber advance at DISPLAY cadence below: the real
+      // host calls it once per presentation, a paused world gets dt=0, and an
+      // explicit `Game.play.step()` still ticks it exactly once.
       //
       // `advance(timestamp, runGlobalEffects, state)`'s `timestamp` is
       // consumed as `THREE.Clock.elapsedTime` DIRECTLY when
@@ -384,6 +384,14 @@ function threeWorldAdapter(id: string, component: ComponentType): RootAdapter {
           return live().camera;
         },
         drivesOwnLoop: false,
+        // Fiber's `advance()` cannot separate its `useFrame` callbacks from
+        // its WebGL draw. Running this opaque update in every fixed catch-up
+        // substep renders N complete frames inside one rAF callback: once a
+        // scene costs more than 16.7ms, the accumulator asks for more draws,
+        // those draws make the next gap larger, and the loop spirals to its
+        // max-substep ceiling. The host's display pass is the one clock that
+        // must own this inseparable native advance.
+        updateCadence: 'display',
         // Adapter surface: `debug` (the shared game registry) and, when a real
         // WebGL2 context exists, `renderDebug` are engine-seeded. The game's
         // own capabilities arrive as the entry module's declared `systems`.
@@ -391,8 +399,12 @@ function threeWorldAdapter(id: string, component: ComponentType): RootAdapter {
         update(dt: number): void {
           elapsed += dt;
           const current = live();
-          renderDebugWiring?.beforeRender();
+          // Fiber receives an ABSOLUTE timestamp and reconstructs `delta` by subtraction. Publish
+          // the exact host-owned dt beside the synchronous advance so compatibility adapters that
+          // reproduce another engine's frame clock do not inherit one-ulp cancellation residue.
+          setHostFrameDelta(current, dt);
           try {
+            renderDebugWiring?.beforeRender();
             const profiler = host.game?.profiler;
             if (!profiler?.enabled) {
               advance(elapsed, true, current);
@@ -429,6 +441,7 @@ function threeWorldAdapter(id: string, component: ComponentType): RootAdapter {
               });
             }
           } finally {
+            clearHostFrameDelta(current);
             renderDebugWiring?.afterRender();
           }
         },