@vgai/engine 0.3.0 → 0.4.0-canary.20260715.0

package/src/character/spring-chain.ts

@@ -0,0 +1,307 @@
+/**
+ * Character primitive — spring-bone chains (hair, ponytails, cloth strips)
+ * on top of `@pixiv/three-vrm-springbone`'s raw API.
+ *
+ * This is a THIN COMPOSITION HELPER, not a wrapper (CLAUDE.md "use libraries
+ * directly"): every export here is a small function that assembles the
+ * library's own objects (`THREE.Bone`, `VRMSpringBoneJoint`,
+ * `VRMSpringBoneCollider`, `VRMSpringBoneManager`) — nothing from the
+ * library is re-exported, and callers still import `@pixiv/three-vrm-
+ * springbone` types directly for anything beyond what's here. Kept
+ * deliberately bare: composing a specific character (a caped viking, a
+ * ponytailed ranger) is ordinary calling code on top of these pieces, not a
+ * costume/preset system in the engine.
+ *
+ * Sharp edge this module exists partly to contain (see the mission brief /
+ * `cloth-hair-bench/spring-rig.ts`'s header for the full discovery):
+ * `VRMSpringBoneCollider` overrides `updateWorldMatrix` (the ON-DEMAND,
+ * manually-invoked method), NOT `updateMatrixWorld` (the one the renderer
+ * calls automatically) — `SpringColliderRig.reposition()` below calls
+ * `collider.updateWorldMatrix(true, false)` itself every tick so callers
+ * can't forget it.
+ */
+
+import {
+  VRMSpringBoneCollider,
+  type VRMSpringBoneColliderGroup,
+  VRMSpringBoneColliderShapeCapsule,
+  VRMSpringBoneColliderShapeSphere,
+  VRMSpringBoneJoint,
+  VRMSpringBoneManager,
+} from '@pixiv/three-vrm-springbone';
+import * as THREE from 'three';
+
+const DEFAULT_GRAVITY_DIR = new THREE.Vector3(0, -1, 0);
+
+// ---------------------------------------------------------------------------
+// Bone chains
+// ---------------------------------------------------------------------------
+
+export interface BoneChain {
+  /** Swinging bones, root (nearest the anchor) first. */
+  bones: THREE.Bone[];
+  /** A non-simulated leaf `Object3D` past the last bone — the spring joint
+   *  "tail" target for the last bone in the chain. */
+  tip: THREE.Object3D;
+}
+
+/** World-space offset from `parent`'s CURRENT world position -> the local
+ *  position a new direct child of `parent` must have to sit there. Requires
+ *  `parent.matrixWorld` to be current. Sidesteps ever reasoning about a
+ *  bone's local rest-axis convention (arbitrary per-bone on an imported
+ *  rig) — the caller only ever thinks in world-space directions. */
+export function worldOffsetToLocalPos(
+  parent: THREE.Object3D,
+  worldDir: THREE.Vector3,
+  length: number,
+): THREE.Vector3 {
+  const parentWorld = new THREE.Vector3();
+  parent.getWorldPosition(parentWorld);
+  const targetWorld = parentWorld.clone().addScaledVector(worldDir, length);
+  return parent.worldToLocal(targetWorld.clone());
+}
+
+/** Build a straight chain of `count` new `THREE.Bone`s under `parent`, each
+ *  offset `segmentLength` further along the WORLD-space unit vector
+ *  `worldDir` — the natural rest shape for hair/cloth hanging under gravity.
+ *  Ends with a `tip` `Object3D` (one more segment past the last bone) so
+ *  every bone has an explicit spring-joint child target. Can be anchored to
+ *  either an existing rig bone (hair off a head) or any plain `Object3D`. */
+export function buildBoneChain(
+  parent: THREE.Object3D,
+  namePrefix: string,
+  count: number,
+  segmentLength: number,
+  worldDir: THREE.Vector3,
+): BoneChain {
+  const bones: THREE.Bone[] = [];
+  let cur: THREE.Object3D = parent;
+  cur.updateWorldMatrix(true, false);
+  for (let i = 0; i < count; i++) {
+    const localPos = worldOffsetToLocalPos(cur, worldDir, segmentLength);
+    const bone = new THREE.Bone();
+    bone.name = `${namePrefix}${i}`;
+    bone.position.copy(localPos);
+    cur.add(bone);
+    bone.updateWorldMatrix(true, false);
+    bones.push(bone);
+    cur = bone;
+  }
+  const tip = new THREE.Object3D();
+  tip.name = `${namePrefix}Tip`;
+  tip.position.copy(worldOffsetToLocalPos(cur, worldDir, segmentLength));
+  cur.add(tip);
+  return { bones, tip };
+}
+
+// ---------------------------------------------------------------------------
+// Spring joints
+// ---------------------------------------------------------------------------
+
+export interface ChainJointSettings {
+  stiffness?: number;
+  gravityPower?: number;
+  gravityDir?: THREE.Vector3;
+  dragForce?: number;
+  hitRadius?: number;
+}
+
+export interface ChainJointHandle {
+  joints: VRMSpringBoneJoint[];
+  /** Deregisters every joint this chain added from `manager`. Does NOT
+   *  detach the bones from the scene graph (the caller owns that). */
+  dispose(): void;
+}
+
+/** Register one `VRMSpringBoneJoint` per bone in `chain` on `manager` (each
+ *  targeting the next bone, the last targeting `chain.tip`). Does not call
+ *  `manager.setInitState()` — batch that once after all chains for a
+ *  manager are registered and the scene's world matrices are current (sharp
+ *  edge: `VRMSpringBoneJoint` sets `bone.matrixAutoUpdate = false`, so
+ *  `setInitState()` must run AFTER `scene.updateMatrixWorld(true)`). */
+export function registerChainJoints(
+  manager: VRMSpringBoneManager,
+  chain: BoneChain,
+  colliderGroups: VRMSpringBoneColliderGroup[],
+  settings: ChainJointSettings = {},
+): ChainJointHandle {
+  const joints: VRMSpringBoneJoint[] = [];
+  for (let i = 0; i < chain.bones.length; i++) {
+    const bone = chain.bones[i]!;
+    const child = chain.bones[i + 1] ?? chain.tip;
+    const joint = new VRMSpringBoneJoint(
+      bone,
+      child,
+      {
+        stiffness: settings.stiffness ?? 1.2,
+        gravityPower: settings.gravityPower ?? 0.9,
+        gravityDir: settings.gravityDir ?? DEFAULT_GRAVITY_DIR,
+        dragForce: settings.dragForce ?? 0.35,
+        hitRadius: settings.hitRadius ?? 0.02,
+      },
+      colliderGroups,
+    );
+    manager.addJoint(joint);
+    joints.push(joint);
+  }
+  return {
+    joints,
+    dispose(): void {
+      for (const joint of joints) manager.deleteJoint(joint);
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Colliders
+// ---------------------------------------------------------------------------
+
+export interface SphereColliderDef {
+  shape: 'sphere';
+  name: string;
+  /** The collider tracks this object's world position every `reposition()`. */
+  followBone: THREE.Object3D;
+  radius: number;
+  /** Extra WORLD-space offset added after sampling `followBone`'s position
+   *  (e.g. nudging a head collider up from the neck joint). */
+  worldOffset?: THREE.Vector3;
+}
+
+export interface CapsuleColliderDef {
+  shape: 'capsule';
+  name: string;
+  followBone: THREE.Object3D;
+  radius: number;
+  /** Capsule tail, in the collider's own local space (world-axis-aligned —
+   *  colliders are parented directly to the scene, see `buildSpringColliderRig`). */
+  tail: THREE.Vector3;
+  worldOffset?: THREE.Vector3;
+}
+
+export type ColliderDef = SphereColliderDef | CapsuleColliderDef;
+
+export interface SpringColliderRig {
+  group: VRMSpringBoneColliderGroup;
+  colliders: Map<string, VRMSpringBoneCollider>;
+  /** Reposition every collider from its `followBone`'s CURRENT world
+   *  transform and refresh its `colliderMatrix` (see module header). Call
+   *  once per tick, BEFORE `manager.update(dt)`. */
+  reposition(): void;
+  dispose(): void;
+}
+
+/** Build sphere/capsule colliders parented directly to `scene` (world
+ *  space) — sidesteps reasoning about any bone's local rest-axis convention
+ *  for the collider shape's offset/tail vectors. */
+export function buildSpringColliderRig(scene: THREE.Scene, defs: ColliderDef[]): SpringColliderRig {
+  const colliders = new Map<string, VRMSpringBoneCollider>();
+  const followers: Array<{ def: ColliderDef; collider: VRMSpringBoneCollider }> = [];
+
+  for (const def of defs) {
+    const collider =
+      def.shape === 'sphere'
+        ? new VRMSpringBoneCollider(new VRMSpringBoneColliderShapeSphere({ radius: def.radius }))
+        : new VRMSpringBoneCollider(
+            new VRMSpringBoneColliderShapeCapsule({
+              radius: def.radius,
+              offset: new THREE.Vector3(0, 0, 0),
+              tail: def.tail,
+            }),
+          );
+    scene.add(collider);
+    colliders.set(def.name, collider);
+    followers.push({ def, collider });
+  }
+
+  const group: VRMSpringBoneColliderGroup = {
+    name: 'body',
+    colliders: [...colliders.values()],
+  };
+
+  const worldTmp = new THREE.Vector3();
+  return {
+    group,
+    colliders,
+    reposition(): void {
+      for (const { def, collider } of followers) {
+        def.followBone.getWorldPosition(worldTmp);
+        collider.position.copy(worldTmp);
+        if (def.worldOffset) collider.position.add(def.worldOffset);
+        collider.updateWorldMatrix(true, false);
+      }
+    },
+    dispose(): void {
+      for (const collider of colliders.values()) scene.remove(collider);
+      colliders.clear();
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Composed chain rig (the common case: one chain, its own manager)
+// ---------------------------------------------------------------------------
+
+export interface SpringChainRigOptions {
+  parent: THREE.Object3D;
+  namePrefix: string;
+  count: number;
+  segmentLength: number;
+  worldDir: THREE.Vector3;
+  /** Colliders this chain collides against. Omit for a chain with no
+   *  collision (e.g. a side strand tucked away from the body). */
+  colliderRig?: SpringColliderRig;
+  settings?: ChainJointSettings;
+}
+
+export interface SpringChainRig {
+  bones: THREE.Bone[];
+  tip: THREE.Object3D;
+  /** The manager owning this chain's joints — a "manager-compatible handle"
+   *  a caller can also register additional joints on directly. */
+  manager: VRMSpringBoneManager;
+  /** Repositions `colliderRig` (if given) and steps the spring simulation.
+   *  Handles the collider `updateWorldMatrix` footgun internally — callers
+   *  never need to call `collider.updateWorldMatrix` themselves. */
+  tick(dt: number): void;
+  dispose(): void;
+}
+
+/** Compose `buildBoneChain` + `registerChainJoints` behind one call for the
+ *  common single-chain case: builds the chain, gives it its OWN
+ *  `VRMSpringBoneManager` (managers are cheap — one per independent chain
+ *  keeps `dispose()`/`tick()` fully self-contained), registers its joints,
+ *  and calls `setInitState()` once construction is complete.
+ *
+ *  For MULTIPLE chains sharing one collider rig (e.g. a ponytail + two side
+ *  strands all colliding against the same head), build each chain with its
+ *  own `buildSpringChainRig` call (same `colliderRig` passed to each) and
+ *  tick all of them — `colliderRig.reposition()` is idempotent per frame, so
+ *  calling it once per chain tick is correct, just slightly redundant work
+ *  (cheap: it only touches a handful of colliders). */
+export function buildSpringChainRig(options: SpringChainRigOptions): SpringChainRig {
+  const chain = buildBoneChain(
+    options.parent,
+    options.namePrefix,
+    options.count,
+    options.segmentLength,
+    options.worldDir,
+  );
+  const manager = new VRMSpringBoneManager();
+  const colliderGroups = options.colliderRig ? [options.colliderRig.group] : [];
+  const jointHandle = registerChainJoints(manager, chain, colliderGroups, options.settings);
+  manager.setInitState();
+
+  return {
+    bones: chain.bones,
+    tip: chain.tip,
+    manager,
+    tick(dt: number): void {
+      options.colliderRig?.reposition();
+      manager.update(dt);
+    },
+    dispose(): void {
+      jointHandle.dispose();
+      chain.bones[0]?.removeFromParent();
+    },
+  };
+}

package/src/core/game-loop.ts

@@ -1,4 +1,4 @@
-import type { GameLoopConfig } from './types';
+import type { GameLoopConfig, GameLoopLiveness } from './types';
 
 /**
  * Fixed-timestep game loop with accumulator pattern.
@@ -104,12 +104,22 @@ export function createGameLoop(config: GameLoopConfig) {
       // listener to fire in the first place.
       if (externalDrive) return;
 
-      rafId = requestAnimationFrame(frame);
-
+      // A play session can be started while the editor tab is ALREADY
+      // hidden. In that case no future visibilitychange-to-hidden event will
+      // arrive, and arming rAF would leave `running=true` forever while the
+      // browser executes zero callbacks. Classify and park the loop before
+      // arming it so status is truthful and visibility restore can resume it.
       if (!visibilityListenerAttached && typeof document !== 'undefined') {
         document.addEventListener('visibilitychange', handleVisibilityChange);
         visibilityListenerAttached = true;
       }
+      if (typeof document !== 'undefined' && document.hidden) {
+        running = false;
+        hiddenPaused = true;
+        return;
+      }
+
+      rafId = requestAnimationFrame(frame);
     },
 
     stop() {
@@ -127,6 +137,22 @@ export function createGameLoop(config: GameLoopConfig) {
       return running;
     },
 
+    /**
+     * Truthful liveness (issue #175 — see `GameLoopLiveness`'s doc comment
+     * in `core/types.ts` for the full contract). Unlike `isRunning` above,
+     * this DISTINGUISHES a hidden-tab pause from an actually-stopped loop:
+     * `hiddenPaused` is only ever set by `handleVisibilityChange` (T2.1's
+     * idle throttle) and cleared by `start()`/`stop()`/visibility-restore,
+     * so it can never be true at the same time `running` is true. An
+     * `externalDrive` loop never installs the visibility listener at all
+     * (see `start()` above), so `hiddenPaused` stays permanently `false` for
+     * it — it only ever reports `'running'` or `'stopped'`.
+     */
+    get liveness(): GameLoopLiveness {
+      if (hiddenPaused) return 'hidden-paused';
+      return running ? 'running' : 'stopped';
+    },
+
     set timeScale(value: number) {
       const clamped = Math.min(8, Math.max(0, value));
       if (clamped !== value) {
@@ -140,5 +166,17 @@ export function createGameLoop(config: GameLoopConfig) {
     get timeScale() {
       return timeScale;
     },
+
+    /**
+     * The fixed substep timestep (seconds) this loop's accumulator consumes
+     * per `config.update()` call (`config.fixedTimestep ?? 1/60`) — read by
+     * `Game.runTicks` (D15, `runtime/game.ts`) so a synchronous fast-forward
+     * burst drives `game.runFrame` with the SAME `fixedDt` this loop's own
+     * rAF-driven accumulator would have used, without exposing (or
+     * `runTicks` needing) any other internal loop state.
+     */
+    get fixedDt() {
+      return fixedDt;
+    },
   };
 }

package/src/core/seeded-random.ts

@@ -0,0 +1,161 @@
+/**
+ * D15 — the seeded-random core (`docs/D15-DETERMINISM-DESIGN.md` §2.a,
+ * T-D15.1). `ctx.random` is a game-scoped PRNG with NAMED STREAMS: calling
+ * the object itself (`ctx.random()`) draws from the `'gameplay'` stream;
+ * `ctx.random.stream('vfx')` (or any other name) derives an INDEPENDENT
+ * generator, so a cosmetic/VFX draw can never perturb the gameplay draw
+ * order — the classic replay-drift trap option B ("one game-scoped PRNG
+ * only") would fall into (see the design doc's §2.a option table).
+ *
+ * Each stream is seeded from `fnv1a(name) ^ rootSeed` — deterministic given
+ * the root seed, independent of draw order across streams (drawing from
+ * `'vfx'` never advances `'gameplay'`'s generator, since they are two
+ * separate mulberry32 instances). `reseed(seed)` re-derives every stream
+ * that has EVER been asked for via `.stream(name)` (including the implicit
+ * `'gameplay'` stream `ctx.random()` itself draws from) — future draws only:
+ * numbers already returned before a `reseed()` call are not (and cannot be)
+ * un-returned; this matches `play.seed.set`'s documented semantics (T-D15.6).
+ *
+ * Deliberately reuses {@link createMulberry32} FROM `runtime/render-seed.ts`
+ * (the render/capture door's own generator) rather than duplicating the
+ * algorithm — `render-seed.ts` stays a zero-import module itself (this file
+ * imports FROM it, never the reverse), so this is a dependency-clean
+ * direction: the render/capture door and the gameplay determinism door share
+ * one PRNG implementation without either depending on the other's door
+ * logic (§2.a: "Kept as-is for the render/capture door only" — the two doors
+ * stay orthogonal; only the generator function itself is shared).
+ */
+
+import { createMulberry32 } from '../runtime/render-seed';
+
+/** The name `ctx.random()` (called with no `.stream(...)`) draws from. */
+export const GAMEPLAY_STREAM = 'gameplay';
+
+/** The fixed fallback seed a `SeededRandom` boots with when no explicit seed
+ *  is supplied (mirrors `render-seed.ts`'s own `DEFAULT_RENDER_SEED` in
+ *  spirit — an arbitrary but fixed golden-ratio-derived constant, never
+ *  wall-clock/`Math.random`-derived, so an UNDECLARED project's `ctx.random`
+ *  is still perfectly reproducible on its own terms even though nothing in
+ *  the manifest asked for that — it just isn't a documented CONTRACT until
+ *  `determinism.seededRandom` is declared, per T4.1's "no dead field" rule). */
+export const DEFAULT_SEEDED_RANDOM_SEED = 0x9e3779b9;
+
+/**
+ * The `ctx.random` surface (`GameContext.random`, `runtime/types.ts`).
+ * Callable (draws from the `'gameplay'` stream), plus:
+ * - `stream(name)` — an independent named generator, `[0, 1)` floats, same
+ *   call signature as `Math.random`/the bare `SeededRandom` call itself.
+ * - `reseed(seed)` — re-derive every stream ever requested so far (future
+ *   draws only) from a NEW root seed.
+ * - `seed` — the CURRENT root seed (reflects the last `reseed()` call, if
+ *   any) — a live getter, not a value snapshotted at construction.
+ */
+export interface SeededRandom {
+  (): number;
+  stream(name: string): () => number;
+  reseed(seed: number): void;
+  readonly seed: number;
+}
+
+/** fnv1a-32, the standard non-cryptographic string hash — used only to mix a
+ *  stream NAME into the root seed, never as a determinism primitive on its
+ *  own (mulberry32 is still what actually produces the `[0,1)` sequence). */
+function fnv1a32(str: string): number {
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < str.length; i++) {
+    hash ^= str.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return hash >>> 0;
+}
+
+interface StreamBox {
+  /** Reassigned wholesale on `reseed()` — the wrapper function `.stream(name)`
+   *  returns to callers stays the SAME identity forever; only what it reads
+   *  from changes, which is what makes reseed observable through a handle a
+   *  caller obtained long before the reseed call. */
+  gen: () => number;
+}
+
+/**
+ * Construct a fresh, game-scoped seeded-random surface. `initialSeed` is
+ * coerced to an unsigned 32-bit integer the same way `render-seed.ts`'s
+ * `installDeterministicRandom` does (`>>> 0`), so any finite JS number is
+ * accepted.
+ */
+export function createSeededRandom(initialSeed: number): SeededRandom {
+  let rootSeed = initialSeed >>> 0;
+  const streams = new Map<string, StreamBox>();
+
+  function deriveStreamSeed(name: string): number {
+    return (fnv1a32(name) ^ rootSeed) >>> 0;
+  }
+
+  function getBox(name: string): StreamBox {
+    let box = streams.get(name);
+    if (!box) {
+      box = { gen: createMulberry32(deriveStreamSeed(name)) };
+      streams.set(name, box);
+    }
+    return box;
+  }
+
+  function streamFn(name: string): () => number {
+    const box = getBox(name);
+    return () => box.gen();
+  }
+
+  const random = (() => getBox(GAMEPLAY_STREAM).gen()) as SeededRandom;
+
+  Object.defineProperties(random, {
+    stream: { value: streamFn, enumerable: true },
+    reseed: {
+      value: (seed: number) => {
+        rootSeed = seed >>> 0;
+        // Re-derive every stream ANYONE has ever asked for (including the
+        // implicit 'gameplay' stream, once `random()` or
+        // `.stream('gameplay')` has been called at least once) — a handle a
+        // caller stashed before this call keeps its identity but now reads
+        // from the freshly-seeded generator on its NEXT call (future draws
+        // only, per the design doc's `play.seed.set` semantics).
+        for (const [name, box] of streams) {
+          box.gen = createMulberry32(deriveStreamSeed(name));
+        }
+      },
+      enumerable: true,
+    },
+    seed: {
+      get: () => rootSeed,
+      enumerable: true,
+    },
+  });
+
+  return random;
+}
+
+// ---------------------------------------------------------------------------
+// Game-scoped registry — mirrors `runtime/debug-registry.ts`'s
+// `registerDebugRegistry`/`getDebugRegistry` WeakMap pattern exactly, but
+// keyed on a bare `object` (not `Game`) so this module never needs to import
+// `runtime/game.ts` even as a type — `core/` stays independent of `runtime/`
+// except for the one explicit, documented `render-seed.ts` reuse above.
+// `createGame` (`runtime/game.ts`) is the one real registrant, passing itself
+// (the `GameInternal` shell) as the key, exactly like it does for
+// `registerDebugRegistry(gameInternal, debugRegistry)`.
+// ---------------------------------------------------------------------------
+
+const registryByOwner = new WeakMap<object, SeededRandom>();
+
+/** Called once by `createGame`, right after both the seeded-random surface
+ *  and the Game shell object exist — mirrors `registerDebugRegistry`. */
+export function registerSeededRandom(owner: object, random: SeededRandom): void {
+  registryByOwner.set(owner, random);
+}
+
+/** The game-scoped `SeededRandom` backing every world's `ctx.random` — `null`
+ *  for an owner built without one (there is always one for every real
+ *  `createGame` call; `null` only for a hand-built `Game`-shaped stand-in a
+ *  test constructs without going through `createGame`). */
+export function getSeededRandom(owner: object): SeededRandom | null {
+  return registryByOwner.get(owner) ?? null;
+}

package/src/core/system-runner.ts

@@ -1,4 +1,11 @@
-import { PHASE_ORDER, type SystemDef, type SystemFn, type SystemPhaseName } from './types';
+import {
+  PHASE_ORDER,
+  type SystemDef,
+  type SystemFn,
+  type SystemOptions,
+  type SystemPhaseName,
+  type SystemRunObserver,
+} from './types';
 
 /**
  * Ordered system execution by named phase.
@@ -25,10 +32,12 @@ import { PHASE_ORDER, type SystemDef, type SystemFn, type SystemPhaseName } from
  *
  * Within each bucket, systems run in registration order.
  */
-export function createSystemRunner() {
+export function createSystemRunner(observer?: SystemRunObserver, scope = 'world') {
   const systems = new Map<SystemPhaseName, SystemFn[]>();
   const registered: SystemDef[] = [];
   const componentTicks = new Map<SystemPhaseName, SystemFn | null>();
+  const labels = new Map<SystemFn, string>();
+  let anonymousId = 0;
 
   // Initialize all phases with empty arrays / no component tick.
   for (const phase of PHASE_ORDER) {
@@ -56,11 +65,16 @@ export function createSystemRunner() {
 
   /** Run one system function, isolating a throw so it never wedges the frame. */
   function runOne(fn: SystemFn, phase: SystemPhaseName, dt: number): void {
+    const label = labels.get(fn) ?? fn.name ?? `anonymous-${++anonymousId}`;
+    labels.set(fn, label);
+    observer?.beginSystem(scope, phase, label);
     try {
       fn(dt);
     } catch (err) {
       const label = fn.name ? `"${fn.name}"` : '(anonymous)';
       console.error(`[system-runner] system ${label} in phase "${phase}" threw:`, err);
+    } finally {
+      observer?.endSystem(scope, phase, label);
     }
   }
 
@@ -69,12 +83,13 @@ export function createSystemRunner() {
      * Register a bare system function in a specific phase.
      * Systems within the same phase run in the order they were added.
      */
-    add(phase: SystemPhaseName, fn: SystemFn) {
+    add(phase: SystemPhaseName, fn: SystemFn, options?: SystemOptions) {
       const list = systems.get(phase);
       if (!list) {
         throw new Error(`Unknown phase: ${phase}. Valid phases: ${PHASE_ORDER.join(', ')}`);
       }
       list.push(fn);
+      labels.set(fn, options?.name ?? fn.name ?? `anonymous-${++anonymousId}`);
     },
 
     /**
@@ -102,6 +117,7 @@ export function createSystemRunner() {
         throw new Error(`Unknown phase: ${system.phase}. Valid phases: ${PHASE_ORDER.join(', ')}`);
       }
       list.push(system.update);
+      labels.set(system.update, system.name ?? system.update.name ?? `anonymous-${++anonymousId}`);
       registered.push(system);
     },
 
@@ -141,6 +157,7 @@ export function createSystemRunner() {
         );
       }
       componentTicks.set(phase, fn);
+      labels.set(fn, `components.${phase}`);
     },
 
     /**

package/src/core/types.ts

@@ -30,8 +30,20 @@ export const PHASE_ORDER: SystemPhaseName[] = [
 /** A system is just a function that takes delta time */
 export type SystemFn = (dt: number) => void;
 
+export interface SystemOptions {
+  /** Stable diagnostic label; falls back to the function name. */
+  readonly name?: string;
+}
+
+export interface SystemRunObserver {
+  beginSystem(scope: string, phase: SystemPhaseName, name: string): void;
+  endSystem(scope: string, phase: SystemPhaseName, name: string): void;
+}
+
 /** A lifecycle system with init/update/dispose hooks. */
 export interface SystemDef {
+  /** Stable diagnostic label; falls back to the update function name. */
+  readonly name?: string;
   /** Which phase the update function runs in */
   phase: SystemPhaseName;
   /** One-time setup after all entities are spawned, before the first frame */
@@ -69,3 +81,28 @@ export interface GameLoopConfig {
    */
   externalDrive?: boolean;
 }
+
+/**
+ * Truthful liveness classification for `createGameLoop`'s returned loop
+ * (issue #175 — "state must never claim health it cannot observe"). See
+ * `GameLoop.liveness`'s doc comment in `game-loop.ts` for the full contract;
+ * exported here (rather than only inline on the loop's return type) so
+ * callers elsewhere in the engine (`runtime/game.ts`, `runtime/
+ * debug-registry.ts`) can name the union without importing `game-loop.ts`
+ * as a value.
+ *
+ * - `'running'` — the rAF chain is armed and `config.update` is being
+ *   driven by real frames (or, for an `externalDrive` loop, `start()` has
+ *   been called — see that mode's own liveness note below).
+ * - `'hidden-paused'` — the T2.1 idle throttle stopped the loop because
+ *   `document.hidden` is true; this is deliberate and reversible (resumes
+ *   automatically on visibility), but ZERO ticks are advancing right now.
+ * - `'stopped'` — `stop()` was called, or `start()` was never called.
+ *
+ * `isRunning` collapses `'hidden-paused'` and `'stopped'` into the same
+ * `false` — exactly the ambiguity that let a hidden-paused game report as
+ * healthy ("playing") through every consumer that only read `isRunning`/
+ * store-level play state. Read `liveness` wherever "is this game actually
+ * advancing" matters.
+ */
+export type GameLoopLiveness = 'running' | 'hidden-paused' | 'stopped';

package/src/data/data-asset.ts

@@ -25,7 +25,7 @@
  * Game code reads `tuning.get()` inside its update loop (never cache fields
  * across frames) or `subscribe()`s; an edit to the `.data.json` — from
  * VS Code, an agent, or the future editor Data tab (W2) — flows through Vite
- * HMR into the running game with no remount. React worlds/tools get a
+ * HMR into the running game with no remount. React roots/tools get a
  * `useData` hook with W3's tool-hooks package (deferred with it: the engine
  * core stays React-free).
  */